AGENTS.md — 本仓库浏览与改动导航

这份文件给进入仓库的代理/协作者一个最快的心智模型：这里有什么、哪些能碰、哪些绝不能碰、改动会被哪些检查拦截。详细契约见 docs/architecture.md。

一句话

这是 Personal AI 公开发布仓（机制层：Skill 包 + MCP 发行包 + DSH 插件包 + 质量脚手架；认知层：soul/ 可携带认知状态 + mind/ 认知维护工具链 + host/ 可执行控制宿主），不是运行时工作区。根目录 top-level 目录属于下列分层之一。

分层目录（改动前先认层）

硬约束（改目录结构的红线）

1. Skill 统一收在 skills/<name>/ 下。scripts/validate_repo.py::discover_skill_dirs() 识别 skills/ 子目录里含 SKILL.md 的目录（为兼容也认可根目录平铺的旧包）。新增 Skill 放进 skills/ 并登记到 skills.json 的 path（./skills/<name>）；两处不同步会让 --strict 判 FAIL。
2. 两个注册表必须与目录一致：skills.json ↔ skills/*；mcp.json ↔ mcp/*。校验器逐一核对。
3. 发布门禁：git diff --check、python scripts/validate_repo.py --strict、python skills/skill-quality-gate/scripts/quality_report.py --root . --strict、仓库回归、MCP 回归全绿才可合并。
4. 测试不得继承部署挂载：host / pi / dsh 三个套件的 test 脚本都带 --import ./tests/scrub-env.mjs（pi / dsh 复用 host 那一份，不复制）。这不是"让测试变绿"： 本机若有 WORLD_MODEL_HOME（这正是挂载 canonical 的文档写法），未隔离的测试会把 canonicalDir 解析到真实 canonical，任何启动时的编译/写入都会落到受治理状态里。 新增测试套件照此办理。删掉它 → 会出现一整片红（WORLD_MODEL_HOME is set… 或 attestation 失败）， 而那只是征兆，根因是测试在动真数据。

Project Facts 与禁忌检查（真实物理底座）

架构事实与传感器基准见 docs/project-facts-spec.md。

• 不可逆操作前核对：在执行涉及写库、修改注册表、跨身体切换或删除持久数据等不可逆操作前，必须先阅读 FAILURES.md，核对相关已知禁忌并运行对应的退出码验证命令。
• 事故即记账（观察窗口的观测器）：一旦发生 FAILURES.md 未覆盖、且代价 > 1 小时或不可逆的事故，当场追加一行（症状 | 根因 | 禁忌动作 | 验证命令 | commit SHA）。此义务不可省：没人记录，两周观察期必然得到「零条」，那是观测缺失，不是假设被证伪。
• 承载物与门禁成本：本节的 AGENTS.md 与 FAILURES.md 已在 scripts/gate_planner.py::KNOWN_PLAIN_FILES 登记为根级普通文档，其改动只走 DELTA 计价；未登记的其他根级文件（README.md / CONTRIBUTING.md / BOOTSTRAP.md）仍按 unknown: 判 FULL 全量回归。新增根级事实文档时须同步登记，否则维护它等于每次付 13 分钟门禁（b7059fe 与 c2516ab 两次实测：787s / 807s）。
• 环境怪癖（沙箱 temp-root）：Windows ACL 下 temp-root 若位于 workspace 内，子进程创建会被预检直接拒绝并返回空输出；此时缺输出并不代表二进制不存在，严禁盲目尝试重装。
• 环境怪癖（提交解释器）：.githooks/pre-commit 与 .githooks/post-commit 里 PY="${PYTHON:-python3}" 只验证解释器可启动，不验证依赖是否齐全。系统默认 python 常缺 pyyaml，会让回归出现数十个 No module named 'yaml' 假失败。提交前显式指定：PYTHON=<装有 pyyaml 的解释器> git commit ...（本机为 anaconda 的 python.exe）。

改动后检查（按改动范围精准执行，禁止无脑全跑）

1. 模块级局部检查（日常开发只跑改动层，严禁跨层空耗）

• 仅改动 app/（前端 UI、组件与工作台）：

  npm --prefix app run lint                         # UI 样式与 HTML 校验
  npm --prefix app test                             # supervisor + 离屏 Electron DOM/Axe 门禁

• 仅改动 host/（中立控制宿主）：

  npm --prefix host test                            # host 契约与零依赖防火墙

• 仅改动 dsh/（DSH 身体适配器）：

  npm --prefix dsh test                             # L4 契约与 L5/L6 切换演练

• 仅改动 pi/（Pi 身体适配器，改了它才跑它）：

  npm --prefix pi test                              # pi 侧边界与底层能力回归（耗时较长）

• 仅改动 skills/：

  python skills/skill-quality-gate/scripts/quality_report.py --root . --strict

• 改动了结构、注册表或基础脚手架：

  python scripts/validate_repo.py --strict
  git diff --check

2. 发布合入门禁（仅在整仓发版或 PR 合并前全量执行）

python scripts/validate_repo.py --strict
python skills/skill-quality-gate/scripts/quality_report.py --root . --strict
python -m unittest discover -s tests -v
npm --prefix host test
npm --prefix pi test
npm --prefix dsh test
npm --prefix app test
npm --prefix app run lint
git diff --check

本地缓存与运行态（当前仓库的"大块头"）

• mcp/agent-switchboard/_sdk_probe_deps/ 曾放 Claude Agent SDK 缓存（约 360MB，含打包的 claude.exe）。已移到 ~/.cache/agent-switchboard-sdk/，claude_sdk_backend.py 从那里探测（可用 AGENT_BROKER_CLAUDE_SDK_DEPS 覆盖）。仓库不应再出现这种大体积缓存目录。
• 任何 state.sqlite、.jsonl、.log、用户路径、会话/任务 ID、模型/认证信息都是运行时态，禁止由 mcp.json 或 CI 校验放行到发布集。

本地经验与跨设备复用入口（新会话/新设备先读这里）

本仓库既是浏览导航，也是本地特有经验的事实源。新会话或新设备上第一个会话，先按此索引直达，不重复发明：

跨设备同步工具：scripts/sync_skills.py（技能栈）、skills/dsh-config-sync（配置骨架，含 --template 路径适配）、scripts/publish_check.py / scripts/run_skill_evals.py（发布与质量门禁）。凭据纪律：同步/发布永远只带环境变量名引用，.credentials.yaml 与运行态绝不出包。