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

.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` 中 |
 
 ### 整合自检执行规则