用agent.md + manifest解决目录对齐问题

2026-05-02 03:20:01 +08:00
parent 0ae4f752b2
commit 4ab6336b13
3 changed files with 86 additions and 28 deletions
--- a/.opencode/canonical-manifest.json
+++ b/.opencode/canonical-manifest.json
@@ -0,0 +1,45 @@
+{
+  "version": 1,
+  "description": "OpenCode 模板框架规范清单 — 定义 init 阶段 1 文件分组的唯一数据源。框架整合时需同步更新此文件。",
+  "canonical_root": [
+    {"path": "AGENTS.md", "note": "项目规则文件（项目根目录）"},
+    {"path": "opencode.json", "note": "OpenCode 配置文件"}
+  ],
+  "canonical_opencode_top": [
+    {"path": ".opencode/.gitignore", "note": "node_modules 等忽略规则"},
+    {"path": ".opencode/canonical-manifest.json", "note": "框架规范清单自身（本文件）"},
+    {"path": ".opencode/package.json", "note": "opencode 插件运行时依赖（@opencode-ai/plugin）"},
+    {"path": ".opencode/package-lock.json", "note": "依赖锁定文件"}
+  ],
+  "canonical_skills": [
+    ".opencode/skills/opencode-init/",
+    ".opencode/skills/deferred-decisions/",
+    ".opencode/skills/dev-changelog/",
+    ".opencode/skills/epee-orchestrator/",
+    ".opencode/skills/pitfall-journal/",
+    ".opencode/skills/problem-distillery/",
+    ".opencode/skills/profile-memory/",
+    ".opencode/skills/spec-docs/"
+  ],
+  "template_data_files": [
+    ".opencode/data/changelog/changelog-full.md",
+    ".opencode/data/changelog/changelog-recent.md",
+    ".opencode/data/changelog/changelog-headlines.md",
+    ".opencode/data/deferred/registry.md",
+    ".opencode/data/pitfalls/pitfalls.md",
+    ".opencode/data/distillery/problems.md",
+    ".opencode/data/distillery/insights.md",
+    ".opencode/data/distillery/golden-rules.md",
+    ".opencode/data/profile/user-profile.md",
+    ".opencode/data/profile/user-profile-log.md",
+    ".opencode/data/profile/project-profile.md",
+    ".opencode/data/profile/project-profile-log.md",
+    ".opencode/data/spec-docs/state.json"
+  ],
+  "cleanup_delete_patterns": [
+    { "pattern": ".opencode/*.log", "note": "调试日志" },
+    { "pattern": ".opencode/_init-backup/", "note": "上一轮冲突备份残留" },
+    { "pattern": ".opencode/_gitignore-preview", "note": "阶段 5.5 临时预览文件" }
+  ],
+  "sentinel": ".opencode/.init-done"
+}
--- a/.opencode/skills/opencode-init/SKILL.md
+++ b/.opencode/skills/opencode-init/SKILL.md
@@ -107,12 +107,14 @@ init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
 ### 阶段 1：递归扫描 `.opencode/`

 ```
-1. 用 shell 列出 .opencode 下所有文件（含子目录）
-2. 把每个文件对照"规范清单"和"清理清单"分成三组：
-   - A 组（canonical）：在规范清单中，原样保留
-   - B 组（template-data）：在清理清单中，需要删除或重置
-   - C 组（foreign）：两张清单都没覆盖到的，视作未知项
-3. 把分组结果用表格汇报给用户：
+1. 【强制】读取 `.opencode/canonical-manifest.json`
+   — 此文件是文件分组的唯一数据源，不允许凭记忆或 Skill 描述摘要判断
+2. 用 shell 列出 .opencode 下所有文件（含子目录）
+3. 把每个文件对照 manifest.json 分成三组：
+   - A 组（canonical）：路径在 canonical_root / canonical_opencode_top / canonical_skills 中，原样保留
+   - B 组（template-data）：路径在 template_data_files 中，需要删除或重置为模板
+   - C 组（foreign）：manifest 三组之外的所有路径，视作未知项
+4. 把分组结果用表格汇报给用户：
   | 组 | 路径 | 处理动作 |
 ```

@@ -268,6 +270,9 @@ init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5

 ## 规范清单（canonical）

+> **声明**：以下清单与 `.opencode/canonical-manifest.json` 保持同步。Agent 在阶段 1 必须读取 manifest.json，
+> 不得凭本节的 Markdown 文本做文件分组。本节的文本版仅供人类阅读和 Skill 维护参考。
+
 下列文件构成本 `.opencode` 模板的"主干"，初始化后必须都在、内容不被删改（数据文件除外）：

 ### 顶层
@@ -837,12 +842,13 @@ public/build/
 | # | 检核项 | 操作 |
 |---|--------|------|
 | 1.1 | Skill 目录存在 `SKILL.md` 且含正确 frontmatter | 验证 `name`、`description` 字段 |
-| 1.2 | `opencode-init` 规范清单 → Skills 白名单 | 在 `### Skills（规范 Skill 目录白名单）` 下新增条目 |
-| 1.3 | `opencode-init` 清理清单 → 阶段 3 | 检查：新 Skill 如有数据文件，需在 B 组重置列表新增条目 |
-| 1.4 | `epee-orchestrator/registry.md` | 新增条目（格式见 registry.md 注释），类型标注 `基础设施` 或 `个人级` |
-| 1.5 | `AGENTS.md` | 检查：新 Skill 是否被 AGENTS.md 引用？若有，引用路径是否正确？ |
-| 1.6 | `opencode.json` → `instructions` | 检查：新 Skill 是否有数据文件需要注入到会话上下文？若有，追加路径 |
-| 1.7 | Skill 自迭代日志 | 新 Skill 必须包含 `## 自迭代日志` 章节（空白即可） |
+| 1.2 | `canonical-manifest.json` → `canonical_skills` | **首选更新目标**：在 JSON 数组中追加新 Skill 目录路径 |
+| 1.3 | `opencode-init` 规范清单 → Skills 白名单 | 在 `### Skills（规范 Skill 目录白名单）` 下新增条目（与 1.2 保持同步） |
+| 1.4 | `opencode-init` 清理清单 → 阶段 3 | 检查：新 Skill 如有数据文件，需在 B 组重置列表新增条目 |
+| 1.5 | `epee-orchestrator/registry.md` | 新增条目（格式见 registry.md 注释），类型标注 `基础设施` 或 `个人级` |
+| 1.6 | `AGENTS.md` | 检查：新 Skill 是否被 AGENTS.md 引用？若有，引用路径是否正确？ |
+| 1.7 | `opencode.json` → `instructions` | 检查：新 Skill 是否有数据文件需要注入到会话上下文？若有，追加路径 |
+| 1.8 | Skill 自迭代日志 | 新 Skill 必须包含 `## 自迭代日志` 章节（空白即可） |

 #### 类型 2：新增数据文件

@@ -850,11 +856,12 @@ public/build/

 | # | 检核项 | 操作 |
 |---|--------|------|
-| 2.1 | `opencode-init` 规范清单 → 数据占位目录 | 在 `### 数据占位目录` 下新增路径 |
-| 2.2 | `opencode-init` 清理清单 → B 组重置列表 | 在阶段 3 的 B 组表格中新增一行 |
-| 2.3 | `opencode-init` → 模板内容 | 新增该文件的模板内容（最小化版本，含占位注释） |
-| 2.4 | `opencode.json` → `instructions` | 若该数据文件应注入会话上下文，追加到 `instructions` 数组 |
-| 2.5 | 所属 Skill 的 SKILL.md | 若数据文件归属某个 Skill，该 Skill 应引用正确的文件路径 |
+| 2.1 | `canonical-manifest.json` → `template_data_files` | **首选更新目标**：在 JSON 数组中追加新数据文件路径 |
+| 2.2 | `opencode-init` 规范清单 → 数据占位目录 | 在 `### 数据占位目录` 下新增路径（与 2.1 保持同步） |
+| 2.3 | `opencode-init` 清理清单 → B 组重置列表 | 在阶段 3 的 B 组表格中新增一行 |
+| 2.4 | `opencode-init` → 模板内容 | 新增该文件的模板内容（最小化版本，含占位注释） |
+| 2.5 | `opencode.json` → `instructions` | 若该数据文件应注入会话上下文，追加到 `instructions` 数组 |
+| 2.6 | 所属 Skill 的 SKILL.md | 若数据文件归属某个 Skill，该 Skill 应引用正确的文件路径 |

 #### 类型 3：新增运行时依赖

@@ -862,10 +869,11 @@ public/build/

 | # | 检核项 | 操作 |
 |---|--------|------|
-| 3.1 | `opencode-init` 规范清单 → 顶层 | 确认 `.opencode/package.json` + `.opencode/package-lock.json` 在顶层 canonical 列表中 |
-| 3.2 | `.opencode/.gitignore` | 确保 **不** 包含 `package.json` 和 `package-lock.json`（这些是基础设施文件，应被 git 跟踪） |
-| 3.3 | `npm install` 后 `package-lock.json` 变更 | 提醒用户提交更新后的 `package-lock.json` |
-| 3.4 | 根目录 `.gitignore`（如存在） | 确认未错误排除 `.opencode/package.json` |
+| 3.1 | `canonical-manifest.json` → `canonical_opencode_top` | 确认 `.opencode/package.json` + `.opencode/package-lock.json` 在 JSON 中 |
+| 3.2 | `opencode-init` 规范清单 → 顶层 | 确认 `.opencode/package.json` + `.opencode/package-lock.json` 在顶层 canonical 列表中（与 3.1 保持同步） |
+| 3.3 | `.opencode/.gitignore` | 确保 **不** 包含 `package.json` 和 `package-lock.json`（这些是基础设施文件，应被 git 跟踪） |
+| 3.4 | `npm install` 后 `package-lock.json` 变更 | 提醒用户提交更新后的 `package-lock.json` |
+| 3.5 | 根目录 `.gitignore`（如存在） | 确认未错误排除 `.opencode/package.json` |

 #### 类型 4：修改 AGENTS.md 规则

@@ -907,16 +915,19 @@ public/build/

 | 截面 | 检查方式 |
 |------|---------|
-| `AGENTS.md` 引用的 Skill | grep Skill 名 → 必须在 `opencode-init` Skills 白名单中 |
-| `AGENTS.md` 引用的数据文件 | grep 文件路径 → 必须在 `opencode-init` 数据占位目录中 |
+| `canonical-manifest.json` VS `canonical_skills` | glob `.opencode/skills/*/` → 不在 manifest 中且非项目级 → 警告 |
+| `canonical-manifest.json` VS `template_data_files` | glob `.opencode/data/**/*` → 不在 manifest 中 → 警告 |
+| `canonical-manifest.json` VS disk | manifest 中的路径 → glob/read 验证文件存在 |
+| `AGENTS.md` 引用的 Skill | grep Skill 名 → 必须在 `canonical-manifest.json` → `canonical_skills` 中 |
+| `AGENTS.md` 引用的数据文件 | grep 文件路径 → 必须在 `canonical-manifest.json` → `template_data_files` 中 |
 | `AGENTS.md` 引用的 docs/ 文档 | glob 检查文件存在 |
 | `opencode.json` → `instructions` 所列路径 | `read` 逐条验证文件存在 |
-| `opencode.json` → `instructions` 所列路径 | 必须在 `opencode-init` 数据占位目录 或 顶层 canonical 中 |
+| `opencode.json` → `instructions` 所列路径 | 必须在 `canonical-manifest.json` 的 `template_data_files` 或 `canonical_opencode_top` 中 |
 | `epee-orchestrator/registry.md` 注册的 Skill | glob 检查对应 `SKILL.md` 存在 |
-| `epee-orchestrator/registry.md` 注册的 Skill | 必须在 `opencode-init` Skills 白名单中（基础设施类 + 个人级） |
+| `epee-orchestrator/registry.md` 注册的 Skill | 必须在 `canonical-manifest.json` → `canonical_skills` 中 |
 | `.opencode/skills/` 下的 Skill 目录 | 若不在 `epee-orchestrator/registry.md` 中 → 缺失注册 |
-| `.opencode/skills/` 下的 Skill 目录 | 若不在 `opencode-init` Skills 白名单中且非项目级 → 警告 |
-| `.opencode/data/` 下的数据文件 | 若不在 `opencode-init` 数据占位目录中 → 警告 |
+| `.opencode/skills/` 下的 Skill 目录 | 若不在 `canonical_skills` 中且非项目级 → 警告 |
+| `.opencode/data/` 下的数据文件 | 若不在 `template_data_files` 中 → 警告 |
 | `.opencode/data/` 下的数据文件 | 若需要注入上下文 → 检查是否在 `opencode.json` → `instructions` 中 |

 ### 整合自检执行规则
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,7 +11,9 @@
 ### 0. 初始化 Sentinel 检查（必须最先执行）

 检查 `.opencode/.init-done` 是否存在：
- **不存在** → 暂存用户原始请求，提示用户需先完成 opencode 初始化，加载 `opencode-init` Skill 并执行阶段 0→7
+- **不存在** → 暂存用户原始请求，提示用户需先完成 opencode 初始化，
+  1. 【强制】`read .opencode/canonical-manifest.json` 加载规范清单 — 必须通过 read 工具读取，不得凭记忆或 Skill 描述摘要做文件分组
+  2. 加载 `opencode-init` Skill 并执行阶段 0→7
 - **已存在** → 跳过，进入后续自检项

 用户主动触发全流程的关键词：`初始化opencode` / `opencode init` / `重置 opencode` / `reset opencode`