1073 lines
36 KiB
Markdown
1073 lines
36 KiB
Markdown
---
|
||
name: opencode-init
|
||
phases: ["all"]
|
||
description: >-
|
||
初始化新项目的 .opencode 结构，以及将实际项目中孵化出的跨项目能力整合回模板框架。
|
||
三种触发方式：
|
||
（1）首次自动触发 —— 当 `.opencode/.init-done` sentinel 不存在时，
|
||
AGENTS.md 会在会话首次响应前引导 Agent 主动执行本 Skill；
|
||
（2）关键词手动触发 —— "初始化opencode"、"opencode init"、"重置 opencode"、"补 gitignore" 等。
|
||
（3）框架整合 —— "整合到框架"、"合并到模板"、"加入框架白名单"、"template integration" 等。
|
||
流程：清理模板残留的项目专用数据（changelog/deferred/pitfalls/profile/distillery），
|
||
可选生成 .gitignore 模板，最后写入 `.opencode/.init-done` 标记完成。
|
||
已 init 仓库不会再自动触发，除非用户主动通过关键词请求。
|
||
---
|
||
|
||
# OpenCode Init Skill
|
||
|
||
把从其它项目复制过来（或通过 git clone 模板仓库获得）的 `.opencode/` 目录重置为当前新项目的干净起点。
|
||
|
||
## 使用场景
|
||
|
||
### 场景 A：克隆模板仓库后的首次会话
|
||
|
||
```
|
||
1. 用户把本模板作为 git 仓库发布
|
||
2. 其他人 `git clone <模板仓库>` 得到新项目骨架
|
||
3. 用户打开 OpenCode，在该仓库发出任意第一条消息
|
||
4. AGENTS.md 检测 .opencode/.init-done 不存在
|
||
→ 引导 Agent 暂停用户原始请求，先执行本 Skill
|
||
5. Agent 按阶段 0 → 7 跑完，写入 .init-done
|
||
6. 后续会话 sentinel 已存在，不再自动触发
|
||
```
|
||
|
||
### 场景 B：从已有项目直接复制 .opencode 目录
|
||
|
||
```
|
||
1. 用户在 "源项目 A" 中使用本 .opencode 模板开发
|
||
2. 用户开 "新项目 B"，把 A 的 .opencode/ 整体拷贝到 B
|
||
3. 用户在 B 中说"初始化opencode"（或首次会话被 AGENTS.md 触发）
|
||
4. 本 Skill 清空 A 遗留的项目数据，重建 registry，生成 .gitignore，写入 sentinel
|
||
```
|
||
|
||
### 场景 C：只补 .gitignore
|
||
|
||
```
|
||
init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
|
||
```
|
||
|
||
### 场景 D：框架整合（反向流程）
|
||
|
||
```
|
||
1. 在实际项目开发中，孵化出了一个新的跨项目能力（新 Skill / 新数据文件 / 新依赖）
|
||
2. 用户认为该能力应成为模板框架的一部分
|
||
3. 用户说"把这个能力整合到 opencode 框架"
|
||
4. Agent 按"框架整合流程"清单逐项执行，更新本 SKILL.md 各截面
|
||
5. 框架整合流程**不**操作 .init-done，**不**修改项目数据文件
|
||
```
|
||
|
||
## 触发条件
|
||
|
||
本 Skill 由 AGENTS.md 触发，两类入口：
|
||
|
||
### A. 全流程（阶段 0 → 7）
|
||
|
||
- `.opencode/.init-done` 不存在 → 会话首次响应前由 AGENTS.md 自动引导
|
||
- 用户关键词：`初始化opencode` / `opencode init` / `重置 opencode` / `reset opencode` 等
|
||
- 口头描述"把复制过来的 .opencode 清理一下"、"按规范归位一下"
|
||
|
||
### B. 仅补 .gitignore（只跑阶段 5.5）
|
||
|
||
- 用户关键词：`补 gitignore` / `生成 gitignore` / `gitignore 模板`
|
||
- 跳过阶段 1-5 和阶段 7 的除"更新 gitignore_generated 字段"外的其他操作
|
||
|
||
### C. 框架整合（执行框架整合清单）
|
||
|
||
- 用户关键词：`整合到框架` / `合并到模板` / `加入框架白名单` / `template integration` / `framework sync` / `规模化这个 Skill` / `沉淀到模板`
|
||
- 口头描述"把这个能力加进模板"、"这个 Skill 应该是框架级的"
|
||
- 执行本文件"框架整合流程"章节的完整检核清单，不走阶段 0→7
|
||
|
||
## 执行原则（不可协商）
|
||
|
||
1. **稳定准确 > token 成本**：每一步可以多读、多确认、让用户点头，不要图快
|
||
2. **破坏性操作必须 dry-run**：删除、重置必须先列清单给用户确认
|
||
3. **不可逆操作前提醒 git**：开始前先提示用户确认工作区已 commit/stash
|
||
4. **模糊就问**：分类不清的文件一律问用户，不要猜
|
||
5. **幂等**：反复运行应当无害（第二次在已干净状态下不会做破坏）
|
||
6. **中断可恢复**：任何阶段异常 abort **不写入** `.init-done`，下次会话仍会被 AGENTS.md 触发从头继续
|
||
|
||
## 核心流程
|
||
|
||
### 阶段 0：前置确认 + 幂等判断
|
||
|
||
```
|
||
1. 检查当前工作目录下存在 .opencode/
|
||
- 不存在 → 直接结束，提示用户先复制模板
|
||
2. 读取 .opencode/.init-done
|
||
- 不存在 → 继续，按"首次 init"路径执行
|
||
- 已存在 → 展示其元数据（initialized_at、project_type 等），提示：
|
||
"检测到本仓库已于 {initialized_at} 完成初始化（project_type: {type}）。
|
||
继续执行会清空 deferred / pitfalls / distillery 等数据文件。确认要继续吗？"
|
||
等用户明确回复"继续"再往下
|
||
3. 运行 `git status`：
|
||
- 不是 git 仓库 → 警告但不阻塞，建议手动备份
|
||
- 有未提交改动 → 提醒"建议先 commit 或 stash，便于回滚"，等用户明确回复"继续"
|
||
4. 向用户声明本次操作范围（见"分组规则"），请求口头确认启动
|
||
```
|
||
|
||
### 阶段 1：递归扫描 `.opencode/`
|
||
|
||
```
|
||
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 或 template_phase_files 中，需要删除或重置为模板
|
||
- C 组（foreign）：manifest 三组之外的所有路径，视作未知项
|
||
4. 把分组结果用表格汇报给用户：
|
||
| 组 | 路径 | 处理动作 |
|
||
```
|
||
|
||
### 阶段 2：处理 C 组（未知文件归位）
|
||
|
||
对 C 组中的每个文件，逐条询问用户（可一次性列清单批量确认）：
|
||
|
||
| 文件特征 | 建议归属 | 目标路径 |
|
||
|----------|----------|----------|
|
||
| 包含 `SKILL.md` 的目录 | Skill（无论通用/项目专属） | `.opencode/skills/<skill-name>/` |
|
||
| 看不出归属 | 询问用户 | — |
|
||
| 明显是临时/垃圾文件（`*.log`、`*.tmp`、缓存等） | 删除（需用户确认） | — |
|
||
|
||
执行要点：
|
||
- **先列清单一次性确认**，然后批量执行移动/删除，避免交互过于频繁
|
||
- **重名冲突**：C 组文件若与 A 组规范文件重名，**保留 A 组版本**，把 C 组备份到 `.opencode/_init-backup/` 下让用户自行 diff，不直接覆盖
|
||
- **迁移后核查**：移动完成后重新扫描，确认 C 组已清空
|
||
|
||
### 阶段 3：处理 B 组（源项目数据清理/重置）
|
||
|
||
按"清理清单"执行：
|
||
|
||
**A. 直接删除**
|
||
|
||
- `.opencode/data/` 下所有数据文件的内容（目录保留）
|
||
- `.opencode/node_modules/`（如有）
|
||
- `.opencode/*.log` —— 调试日志
|
||
|
||
**B. 重置为空模板**（保留文件，仅清内容）
|
||
|
||
| 文件 | 模板（见"模板内容"节） |
|
||
|------|------------------------|
|
||
| `.opencode/data/changelog/changelog-full.md` | L1 模板 |
|
||
| `.opencode/data/changelog/changelog-recent.md` | L2 模板 |
|
||
| `.opencode/data/changelog/changelog-headlines.md` | L3 模板 |
|
||
| `.opencode/data/deferred/registry.md` | deferred 模板 |
|
||
| `.opencode/data/pitfalls/pitfalls.md` | pitfalls 模板 |
|
||
| `.opencode/data/distillery/problems.md` | problems 模板 |
|
||
| `.opencode/data/distillery/insights.md` | insights 模板 |
|
||
| `.opencode/data/distillery/golden-rules.md` | golden-rules 模板 |
|
||
| `.opencode/data/profile/user-profile.md` | user-profile 模板 |
|
||
| `.opencode/data/profile/user-profile-log.md` | user-profile-log 模板 |
|
||
| `.opencode/data/profile/project-profile.md` | project-profile 模板 |
|
||
| `.opencode/data/profile/project-profile-log.md` | project-profile-log 模板 |
|
||
| `.opencode/data/spec-docs/state.json` | state.json 模板 |
|
||
| `.opencode/phase/current.json` | current.json 模板 |
|
||
| `.opencode/phase/data/design/state.json` | state.json 模板 |
|
||
| `.opencode/phase/data/design/concept.md` | concept.md 模板 |
|
||
| `.opencode/phase/data/design/design-outline.md` | design-outline.md 模板 |
|
||
| `.opencode/phase/data/design/qa-quality-report.md` | qa-quality-report.md 模板 |
|
||
| `.opencode/phase/data/design/reference-analysis/gdd-reverse.md` | gdd-reverse.md 模板 |
|
||
| `.opencode/phase/data/design/reference-analysis/community-iteration.md` | community-iteration.md 模板 |
|
||
|
||
执行要点：
|
||
- 每个重置前**先 Read 现有内容预览前 10 行**给用户，避免误删有价值数据（特别是 deferred/pitfalls 用户可能想保留）
|
||
- 如用户对某个数据文件明确说"保留"（例如 golden-rules 想带过去），跳过该文件的重置
|
||
|
||
### 阶段 4：重建 registry
|
||
|
||
打开 `.opencode/skills/epee-orchestrator/registry.md`：
|
||
|
||
1. 解析现有条目（每条 `### <skill-name>` 块）
|
||
2. 删除所有标记为"项目级"的条目
|
||
3. 遍历 `.opencode/skills/` 目录，对照 registry：
|
||
- registry 有条目但 skill 目录不存在 → 删除条目
|
||
- skill 目录存在但 registry 无条目 → 读取该 skill 的 SKILL.md frontmatter，新增条目
|
||
4. **确保 `opencode-init` 条目本身存在**（类型: 基础设施）
|
||
5. 写回 registry.md
|
||
|
||
### 阶段 5：同步 opencode.json 配置
|
||
|
||
- 读取 `opencode.json`
|
||
- 确认 `instructions` 字段中包含所有必要的数据文件路径（changelog-headlines、deferred/registry、golden-rules、project-profile）
|
||
- 如有缺失或路径不正确，更新之
|
||
|
||
### 阶段 5.5：`.gitignore` 交互式生成
|
||
|
||
#### 5.5.1 前置检测
|
||
|
||
```
|
||
检测项目根 .gitignore：
|
||
不存在 → 进入 5.5.2 问卷
|
||
已存在且非空 → Read 前 30 行展示给用户，询问：
|
||
[覆盖 / 追加到文件末尾 / 跳过本阶段]
|
||
用户选"跳过" → 本阶段结束，.init-done 里标记 gitignore_generated: false
|
||
```
|
||
|
||
#### 5.5.2 问卷（一次性批量 AskQuestion 收集）
|
||
|
||
必问 3 项 + 可选 1 项：
|
||
|
||
| 编号 | 问题 | 类型 | 选项 |
|
||
|------|------|------|------|
|
||
| Q1 | 项目主要技术栈 | 多选 | Unity / Node.js / Python / Rust / Go / C# 非 Unity / Web 静态站点 / 其他 / **不确定（跳过语言段）** |
|
||
| Q2 | IDE 偏好 | 多选 | OpenCode（预勾）/ VSCode / JetBrains 全家桶 / Visual Studio / Vim+Emacs |
|
||
| Q3 | 操作系统 | 多选 | Windows / macOS / Linux（按探测到的当前 OS 预勾） |
|
||
| Q4（可选）| 其他要忽略的路径 | 自由文本 | 用户可跳过 |
|
||
|
||
#### 5.5.3 片段组装
|
||
|
||
按问卷选择拼装，片段内容见下方"模板内容 · .gitignore 片段库"。拼装顺序固定：
|
||
|
||
```
|
||
# === OpenCode（固定，所有项目都包含） ===
|
||
# === OS ===
|
||
# === IDE ===
|
||
# === Language / Framework ===
|
||
# === Custom ===
|
||
```
|
||
|
||
若 Q1 选"不确定" → 跳过 Language 段，其他段正常拼装（极简版仍可用）。
|
||
|
||
#### 5.5.4 预览与确认
|
||
|
||
1. 把组装结果写到 `.opencode/_gitignore-preview`（临时文件）
|
||
2. 给用户完整展示（超过 60 行则折叠中段）
|
||
3. AskQuestion：`[写入 .gitignore / 让我调整再确认 / 放弃本阶段]`
|
||
4. "写入"→ move 到项目根 `.gitignore`（已存在时按 5.5.1 的选择做覆盖或追加），删除预览文件
|
||
5. "调整"→ 根据用户描述修改后重复步骤 2-3
|
||
6. "放弃"→ 删除预览文件，`.init-done` 标记 `gitignore_generated: false`
|
||
|
||
### 阶段 6：验证与报告
|
||
|
||
```
|
||
1. 重新递归扫描 .opencode/，再次分组
|
||
2. 【强制】验证所有 Skills 的 frontmatter：
|
||
- 遍历 `.opencode/skills/*/SKILL.md`
|
||
- 每个文件必须检查：第一行是否为 `---`、是否包含 `name:` 字段、frontmatter 是否正确闭合
|
||
- 缺失 frontmatter 的 Skill 会无法被 opencode 注册（即使文件存在也不会出现在 available_skills 中）
|
||
- 发现缺失 → 立即报告并修复（参考其他 Skill 的 frontmatter 格式）
|
||
3. 期望状态：
|
||
- A 组：全部保留，文件内容未被动过
|
||
- B 组：数据文件仅含模板内容
|
||
- C 组：为空（或仅剩用户明确要求保留的文件）
|
||
- 所有 Skill 的 frontmatter 完整
|
||
- 项目根 .gitignore：按用户选择存在或被放弃（状态记到报告里）
|
||
- project根 opencode.json：instructions 已正确配置
|
||
4. 给用户一份结构化报告，至少包含：
|
||
- 删除的文件
|
||
- 重置的文件
|
||
- 新注册/移除的 registry 条目
|
||
- .gitignore 的处理结果（新建/追加/覆盖/放弃）
|
||
- Skill frontmatter 验证结果
|
||
- 未处理的文件（如果有，逐条说明原因）
|
||
```
|
||
|
||
### 阶段 7：写入 `.init-done` sentinel
|
||
|
||
**仅在阶段 6 验证全部通过后执行**。任何前序阶段异常中断都不写入此文件，确保下次会话 AGENTS.md 能再次触发。
|
||
|
||
```
|
||
1. 按"模板内容 · .init-done"格式，填充实际值写入 .opencode/.init-done
|
||
2. 向用户输出收尾提示：
|
||
> 初始化完成。建议现在执行：
|
||
> git add .opencode/ .gitignore
|
||
> git diff --cached -- .opencode/
|
||
> git commit -m "chore(opencode): initialize .opencode from template"
|
||
>
|
||
> ⚠️ .opencode/.init-done 必须 commit，否则团队其他成员 clone 后会被再次触发 init。
|
||
```
|
||
|
||
**仅跑阶段 5.5 时**（用户说"补 gitignore"）：
|
||
- 若 `.init-done` 存在 → 更新其中的 `gitignore_generated: true` 字段，保留其他字段
|
||
- 若 `.init-done` 不存在 → 提示用户"仓库尚未完整 init，只补 gitignore 不会写 sentinel。是否改为跑完整 init？"
|
||
|
||
---
|
||
|
||
## 规范清单（canonical）
|
||
|
||
> **声明**：以下清单与 `.opencode/canonical-manifest.json` 保持同步。Agent 在阶段 1 必须读取 manifest.json，
|
||
> 不得凭本节的 Markdown 文本做文件分组。本节的文本版仅供人类阅读和 Skill 维护参考。
|
||
|
||
下列文件构成本 `.opencode` 模板的"主干"，初始化后必须都在、内容不被删改（数据文件除外）：
|
||
|
||
### 顶层
|
||
|
||
- `AGENTS.md` —— 项目规则文件（项目根目录）
|
||
- `opencode.json` —— OpenCode 配置文件
|
||
- `.opencode/.init-done` —— **阶段 7 写入**；模板仓库自身不应包含此文件
|
||
- `.opencode/.gitignore` —— node_modules 忽略规则
|
||
- `.opencode/package.json` —— opencode 插件运行时依赖声明（`@opencode-ai/plugin`）
|
||
- `.opencode/package-lock.json` —— 依赖锁定文件，确保跨环境依赖版本一致
|
||
|
||
### Skills（规范 Skill 目录白名单）
|
||
|
||
- `.opencode/skills/opencode-init/`
|
||
- `.opencode/skills/deferred-decisions/`
|
||
- `.opencode/skills/dev-changelog/`
|
||
- `.opencode/skills/epee-orchestrator/`（含 `registry.md`，见阶段 4）
|
||
- `.opencode/skills/pitfall-journal/`
|
||
- `.opencode/skills/problem-distillery/`
|
||
- `.opencode/skills/profile-memory/`
|
||
- `.opencode/skills/spec-docs/`
|
||
- `.opencode/skills/game-design/`
|
||
- `.opencode/skills/skill-tester/`
|
||
|
||
> **任何不在此白名单中的 skill 目录**，在阶段 3 中一律删除（视为源项目的项目级 Skill）。
|
||
|
||
### 数据占位目录（保留目录，文件重置为模板内容）
|
||
|
||
- `.opencode/data/changelog/{changelog-full.md, changelog-recent.md, changelog-headlines.md}`
|
||
- `.opencode/data/deferred/registry.md`
|
||
- `.opencode/data/pitfalls/pitfalls.md`
|
||
- `.opencode/data/distillery/{problems.md, insights.md, golden-rules.md}`
|
||
- `.opencode/data/profile/{user-profile.md, user-profile-log.md, project-profile.md, project-profile-log.md}`
|
||
- `.opencode/data/spec-docs/state.json`
|
||
|
||
### 阶段数据占位目录（保留目录，文件重置为模板内容）
|
||
|
||
- `.opencode/phase/current.json`
|
||
- `.opencode/phase/data/design/state.json`
|
||
- `.opencode/phase/data/design/concept.md`
|
||
- `.opencode/phase/data/design/design-outline.md`
|
||
- `.opencode/phase/data/design/qa-quality-report.md`
|
||
- `.opencode/phase/data/design/reference-analysis/gdd-reverse.md`
|
||
- `.opencode/phase/data/design/reference-analysis/community-iteration.md`
|
||
|
||
---
|
||
|
||
## 清理清单（cleanup list）
|
||
|
||
### 强制删除
|
||
|
||
| 路径 | 原因 |
|
||
|------|------|
|
||
| `.opencode/*.log`、`.opencode/**/*.log` | 调试日志遗留 |
|
||
| `.opencode/_init-backup/`（如果是上一轮残留） | 仅阶段 2 冲突备份用，运行前应不存在 |
|
||
| `.opencode/_gitignore-preview`（如果是上一轮残留） | 阶段 5.5 临时文件 |
|
||
|
||
### 重置为模板
|
||
|
||
见"模板内容"节。
|
||
|
||
---
|
||
|
||
## 模板内容
|
||
|
||
重置数据文件时使用以下内容。带 `{{DATE}}` 的占位符替换为当天日期（`YYYY-MM-DD`）。
|
||
|
||
### changelog-full.md
|
||
|
||
```markdown
|
||
# Dev Changelog — Full
|
||
|
||
完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。
|
||
|
||
## 记录
|
||
```
|
||
|
||
### changelog-recent.md
|
||
|
||
```markdown
|
||
# Dev Changelog — Recent
|
||
|
||
最近 ~10 次改动的摘要记录，按时间倒序排列。
|
||
当 Agent 检测到当前任务与近期改动相关时自动读取。
|
||
```
|
||
|
||
### changelog-headlines.md
|
||
|
||
```markdown
|
||
# Dev Changelog — Headlines
|
||
|
||
最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。
|
||
```
|
||
|
||
### deferred/registry.md
|
||
|
||
```markdown
|
||
# Deferred Decisions Registry
|
||
|
||
## Active Items
|
||
|
||
（暂无延期方案）
|
||
|
||
---
|
||
|
||
## Completed / Cancelled Items
|
||
|
||
（暂无已完成或已废弃的方案）
|
||
```
|
||
|
||
### pitfalls/pitfalls.md
|
||
|
||
```markdown
|
||
# Pitfall Journal
|
||
|
||
开发过程中踩过的坑，按时间倒序排列。
|
||
Agent 进入 Debug mode 或遇到运行时错误时自动检索匹配。
|
||
|
||
---
|
||
```
|
||
|
||
### distillery/problems.md
|
||
|
||
```markdown
|
||
# Problem Distillery — Problems
|
||
|
||
反复出现的顽固问题追踪记录，按时间倒序排列。
|
||
|
||
<!-- 新条目追加在此行下方 -->
|
||
```
|
||
|
||
### distillery/insights.md
|
||
|
||
```markdown
|
||
# Problem Distillery — Insights
|
||
|
||
从已解决的顽固问题中蒸馏出的精炼方法论。
|
||
|
||
<!-- 新条目追加在此行下方 -->
|
||
|
||
---
|
||
last_distill_date: {{DATE}}
|
||
```
|
||
|
||
### distillery/golden-rules.md
|
||
|
||
```markdown
|
||
# Golden Rules
|
||
|
||
经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。
|
||
|
||
<!-- 当条目达到权重阈值后由 Agent 自动写入 -->
|
||
```
|
||
|
||
### profile/user-profile.md
|
||
|
||
```markdown
|
||
# User Profile
|
||
|
||
## 审美与设计
|
||
|
||
## 技术偏好
|
||
|
||
## 做事风格
|
||
|
||
## 沟通偏好
|
||
|
||
## 产品理解
|
||
```
|
||
|
||
### profile/user-profile-log.md
|
||
|
||
```markdown
|
||
# User Profile Log
|
||
|
||
详细记录每次画像更新的完整上下文，按时间正序追加。
|
||
|
||
## 记录
|
||
```
|
||
|
||
### profile/project-profile.md
|
||
|
||
```markdown
|
||
# Project Profile
|
||
|
||
## 项目定位
|
||
|
||
## 技术栈与架构
|
||
|
||
## 设计约定
|
||
|
||
## 产品方向
|
||
```
|
||
|
||
### profile/project-profile-log.md
|
||
|
||
```markdown
|
||
# Project Profile Log
|
||
|
||
详细记录每次项目画像更新的完整上下文，按时间正序追加。
|
||
|
||
## 记录
|
||
```
|
||
|
||
### spec-docs/state.json
|
||
|
||
```json
|
||
{
|
||
"last_review_date": null,
|
||
"last_processed_changelog_id": null,
|
||
"review_count": 0
|
||
}
|
||
```
|
||
|
||
### phase/current.json
|
||
|
||
```json
|
||
{
|
||
"phase": "design",
|
||
"switched_at": null,
|
||
"previous_phase": null
|
||
}
|
||
```
|
||
|
||
### phase/data/design/state.json
|
||
|
||
```json
|
||
{
|
||
"workflow_state": "WAITING_FOR_CONCEPT",
|
||
"concept_summary": "",
|
||
"reference_games": [],
|
||
"in_progress": {
|
||
"active": false,
|
||
"operation": null,
|
||
"started_at": null,
|
||
"detail": null
|
||
},
|
||
"checkpoints": [],
|
||
"sessions": [],
|
||
"created_at": null,
|
||
"updated_at": null
|
||
}
|
||
```
|
||
|
||
### phase/data/design/concept.md
|
||
|
||
```markdown
|
||
# 游戏概念
|
||
|
||
（设计阶段步骤 1 的用户原始概念记录）
|
||
```
|
||
|
||
### phase/data/design/design-outline.md
|
||
|
||
```markdown
|
||
# 游戏设计大纲
|
||
|
||
（设计阶段完成后由 game-design Skill 生成）
|
||
|
||
详见 `## 四、开发阶段交接` 章节供开发阶段 Agent 参考。
|
||
```
|
||
|
||
### phase/data/design/qa-quality-report.md
|
||
|
||
```markdown
|
||
# 问答质量评估报告
|
||
|
||
本文件记录设计工作流中每轮问答的质量评估结果。每次评估追加，不覆盖。
|
||
|
||
## 评估维度
|
||
|
||
- **劣质问题类型**：引导性 / 过于抽象 / 遗漏选项 / 不可回答 / 基于推测
|
||
- **问题原文**：保留用户质疑的原问题
|
||
- **用户反馈**：用户的具体质疑或自定义回答
|
||
- **优化方案**：改进后的提问方式
|
||
- **通用建议**：可跨项目复用的经验
|
||
|
||
---
|
||
|
||
## 质量报告
|
||
```
|
||
|
||
### phase/data/design/reference-analysis/gdd-reverse.md
|
||
|
||
```markdown
|
||
# GDD 逆向分析
|
||
|
||
（game-design Skill 步骤 3 sub-agent A 产物）
|
||
```
|
||
|
||
### phase/data/design/reference-analysis/community-iteration.md
|
||
|
||
```markdown
|
||
# 社群口碑与品类迭代分析
|
||
|
||
（game-design Skill 步骤 3 sub-agent B 产物）
|
||
```
|
||
|
||
### .init-done
|
||
|
||
阶段 7 写入的 sentinel，YAML 格式，字段固定：
|
||
|
||
```yaml
|
||
# .opencode/.init-done — opencode-init Skill 写入的初始化标记文件
|
||
# 本文件的存在表示本仓库已完成 .opencode 模板初始化
|
||
# 请务必 git commit 此文件，避免团队成员 clone 后被再次触发 init
|
||
initialized_at: {{ISO_DATETIME}} # 如 2026-04-30T16:30:00+08:00
|
||
initialized_by: opencode-init
|
||
skill_version: 2
|
||
project_type: {{PROJECT_TYPE}} # 阶段 5.5 问卷 Q1 结果；多选逗号分隔；"不确定"写 unknown
|
||
gitignore_generated: {{BOOL}} # true / false
|
||
```
|
||
|
||
**写入时机**：
|
||
- 全流程跑完（阶段 6 验证通过）时由阶段 7 写入
|
||
- "补 gitignore" 单独跑阶段 5.5 时，若已存在则只更新 `gitignore_generated` 字段
|
||
|
||
---
|
||
|
||
## 模板内容 · .gitignore 片段库
|
||
|
||
阶段 5.5 按用户问卷选择拼接以下片段。每段前后各空一行，保证可读性。
|
||
|
||
### 固定段：OpenCode
|
||
|
||
```gitignore
|
||
# === OpenCode ===
|
||
# opencode-init 临时产物
|
||
.opencode/_init-backup/
|
||
.opencode/_gitignore-preview
|
||
```
|
||
|
||
### OS 段（按问卷 Q3 多选拼接）
|
||
|
||
**Windows**
|
||
|
||
```gitignore
|
||
# === OS: Windows ===
|
||
Thumbs.db
|
||
Thumbs.db:encryptable
|
||
ehthumbs.db
|
||
ehthumbs_vista.db
|
||
Desktop.ini
|
||
$RECYCLE.BIN/
|
||
*.stackdump
|
||
*.lnk
|
||
```
|
||
|
||
**macOS**
|
||
|
||
```gitignore
|
||
# === OS: macOS ===
|
||
.DS_Store
|
||
.AppleDouble
|
||
.LSOverride
|
||
Icon
|
||
._*
|
||
.DocumentRevisions-V100
|
||
.fseventsd
|
||
.Spotlight-V100
|
||
.TemporaryItems
|
||
.Trashes
|
||
.VolumeIcon.icns
|
||
.com.apple.timemachine.donotpresent
|
||
```
|
||
|
||
**Linux**
|
||
|
||
```gitignore
|
||
# === OS: Linux ===
|
||
*~
|
||
.fuse_hidden*
|
||
.directory
|
||
.Trash-*
|
||
.nfs*
|
||
```
|
||
|
||
### IDE 段（按问卷 Q2 多选拼接）
|
||
|
||
**VSCode**
|
||
|
||
```gitignore
|
||
# === IDE: VSCode ===
|
||
.vscode/*
|
||
!.vscode/settings.json
|
||
!.vscode/tasks.json
|
||
!.vscode/launch.json
|
||
!.vscode/extensions.json
|
||
!.vscode/*.code-snippets
|
||
.history/
|
||
*.vsix
|
||
```
|
||
|
||
**JetBrains**
|
||
|
||
```gitignore
|
||
# === IDE: JetBrains ===
|
||
.idea/
|
||
*.iml
|
||
*.ipr
|
||
*.iws
|
||
.idea_modules/
|
||
atlassian-ide-plugin.xml
|
||
```
|
||
|
||
**Visual Studio**
|
||
|
||
```gitignore
|
||
# === IDE: Visual Studio ===
|
||
.vs/
|
||
*.user
|
||
*.suo
|
||
*.userprefs
|
||
bin/
|
||
obj/
|
||
[Dd]ebug/
|
||
[Rr]elease/
|
||
x64/
|
||
x86/
|
||
```
|
||
|
||
**Vim/Emacs**
|
||
|
||
```gitignore
|
||
# === IDE: Vim / Emacs ===
|
||
*.swp
|
||
*.swo
|
||
*.swn
|
||
Session.vim
|
||
.netrwhist
|
||
*~
|
||
\#*\#
|
||
.\#*
|
||
```
|
||
|
||
**OpenCode**：固定段已覆盖，无需额外片段。
|
||
|
||
### Language / Framework 段（按问卷 Q1 多选拼接）
|
||
|
||
**Unity**
|
||
|
||
```gitignore
|
||
# === Language: Unity ===
|
||
[Ll]ibrary/
|
||
[Tt]emp/
|
||
[Oo]bj/
|
||
[Bb]uild/
|
||
[Bb]uilds/
|
||
[Ll]ogs/
|
||
[Uu]ser[Ss]ettings/
|
||
[Mm]emoryCaptures/
|
||
[Rr]ecordings/
|
||
sysinfo.txt
|
||
*.apk
|
||
*.aab
|
||
*.unitypackage
|
||
*.app
|
||
*.csproj
|
||
*.unityproj
|
||
*.sln
|
||
*.suo
|
||
*.tmp
|
||
*.user
|
||
*.userprefs
|
||
*.pidb
|
||
*.booproj
|
||
*.svd
|
||
*.pdb
|
||
*.mdb
|
||
*.opendb
|
||
*.VC.db
|
||
```
|
||
|
||
**Node.js**
|
||
|
||
```gitignore
|
||
# === Language: Node.js ===
|
||
node_modules/
|
||
.npm/
|
||
.yarn/
|
||
.pnp.*
|
||
dist/
|
||
build/
|
||
out/
|
||
.next/
|
||
.nuxt/
|
||
.cache/
|
||
.parcel-cache/
|
||
coverage/
|
||
.env
|
||
.env.local
|
||
.env.*.local
|
||
npm-debug.log*
|
||
yarn-debug.log*
|
||
yarn-error.log*
|
||
pnpm-debug.log*
|
||
.turbo/
|
||
```
|
||
|
||
**Python**
|
||
|
||
```gitignore
|
||
# === Language: Python ===
|
||
__pycache__/
|
||
*.py[cod]
|
||
*$py.class
|
||
*.so
|
||
.Python
|
||
build/
|
||
dist/
|
||
*.egg-info/
|
||
*.egg
|
||
.venv/
|
||
venv/
|
||
env/
|
||
.pytest_cache/
|
||
.mypy_cache/
|
||
.ruff_cache/
|
||
.coverage
|
||
.coverage.*
|
||
htmlcov/
|
||
.tox/
|
||
.nox/
|
||
.hypothesis/
|
||
.ipynb_checkpoints/
|
||
```
|
||
|
||
**Rust**
|
||
|
||
```gitignore
|
||
# === Language: Rust ===
|
||
target/
|
||
**/*.rs.bk
|
||
*.pdb
|
||
# Cargo.lock：lib crate 建议忽略，bin crate 建议提交，默认不忽略
|
||
# Cargo.lock
|
||
```
|
||
|
||
**Go**
|
||
|
||
```gitignore
|
||
# === Language: Go ===
|
||
bin/
|
||
vendor/
|
||
*.exe
|
||
*.exe~
|
||
*.dll
|
||
*.so
|
||
*.dylib
|
||
*.test
|
||
*.out
|
||
go.work
|
||
```
|
||
|
||
**C# 非 Unity**
|
||
|
||
```gitignore
|
||
# === Language: C# (non-Unity) ===
|
||
bin/
|
||
obj/
|
||
*.user
|
||
*.suo
|
||
*.pdb
|
||
*.cache
|
||
[Dd]ebug/
|
||
[Rr]elease/
|
||
x64/
|
||
x86/
|
||
[Bb]uild/
|
||
*.dll
|
||
*.pdb
|
||
```
|
||
|
||
**Web 静态站点**
|
||
|
||
```gitignore
|
||
# === Language: Web Static ===
|
||
node_modules/
|
||
dist/
|
||
build/
|
||
public/build/
|
||
.cache/
|
||
.tmp/
|
||
.sass-cache/
|
||
.parcel-cache/
|
||
```
|
||
|
||
**其他**：不拼接语言段，用户在 `# === Custom ===` 段自行补充。
|
||
|
||
### Custom 段（固定尾部）
|
||
|
||
```gitignore
|
||
# === Custom ===
|
||
# 在此段追加项目专属需要忽略的路径
|
||
```
|
||
|
||
若用户在问卷 Q4 填了自由文本，按行拆分后追加到 Custom 段下方。
|
||
|
||
---
|
||
|
||
## 冲突与边界情况处理
|
||
|
||
| 场景 | 处理 |
|
||
|------|------|
|
||
| C 组某文件与 A 组重名 | 保留 A 组；C 组移到 `.opencode/_init-backup/`，告知用户自行 diff |
|
||
| C 组有 `SKILL.md` 且 skill 名与 A 组白名单同名 | 保留 A 组 skill；C 组整个 skill 目录移到 `_init-backup/` |
|
||
| 数据文件（如 `pitfalls.md`）用户明确说"保留" | 跳过该文件重置 |
|
||
| 扫描到 `.opencode/_init-backup/`（上轮残留） | 警告用户并询问：删除 / 保留 / 重命名 |
|
||
| `git status` 不能执行（不是 git 仓库） | 警告但不阻塞，改为建议用户手动备份 |
|
||
| `.opencode/.init-done` 已存在且用户触发了全流程 | 阶段 0 展示其元数据并要求二次确认 |
|
||
| 阶段 5.5 项目根已有 `.gitignore` 且用户选"追加" | 把拼装结果追加到现有文件末尾（用 `\n\n# --- 以下由 opencode-init 追加 ---\n` 分隔） |
|
||
| 阶段 5.5 中途异常或用户放弃 | 不写入 `.gitignore`，`.init-done` 的 `gitignore_generated` 记 false |
|
||
| 阶段 7 写 `.init-done` 前前序阶段已 abort | 不写入 sentinel，下次会话 AGENTS.md 会重新触发 |
|
||
| 用户说"补 gitignore" 但 `.init-done` 不存在 | 提醒"仓库尚未完整 init"，询问是否改为跑全流程 |
|
||
|
||
---
|
||
|
||
## 一次运行的最终状态（验收标准）
|
||
|
||
全流程（阶段 0 → 7）完成后 `.opencode/` 应当满足：
|
||
|
||
1. 规范清单中列出的所有文件/目录都存在
|
||
2. 所有数据文件（changelog/deferred/pitfalls/distillery/profile）仅含模板内容
|
||
3. `.opencode/skills/` 下仅有白名单中的 skill 目录
|
||
4. `.opencode/skills/epee-orchestrator/registry.md` 中只有：基础设施 + 个人级 skill 条目，且包含 `opencode-init` 条目
|
||
5. 不存在 `*.log`、`_init-backup/`、`_gitignore-preview`
|
||
6. `.opencode/.init-done` 已写入，字段完整且值有效
|
||
7. `opencode.json` 的 `instructions` 字段配置正确
|
||
8. 项目根 `.gitignore` 状态明确（存在且有内容 / 被用户显式放弃）
|
||
9. `git status .opencode/ .gitignore` 能让用户清楚看到所有改动
|
||
|
||
仅跑阶段 5.5（"补 gitignore"）完成后：
|
||
|
||
1. 项目根 `.gitignore` 存在或被显式放弃
|
||
2. 若 `.init-done` 已存在，其 `gitignore_generated` 字段被更新
|
||
3. 其他 `.opencode/` 内容**零改动**
|
||
|
||
---
|
||
|
||
## 框架整合流程（Template Integration）
|
||
|
||
> 本清单是框架整合的**唯一检核入口**。当在实际项目中创建了新的跨项目级别能力，需要合并回本模板时，Agent 必须按本清单逐项执行，不得跳过任何一步。
|
||
|
||
### 触发关键词
|
||
|
||
`整合到框架` / `合并到模板` / `加入框架白名单` / `template integration` / `framework sync` / `规模化这个 Skill` / `沉淀到模板`
|
||
|
||
### 执行流程
|
||
|
||
1. **识别整合类型**：判断本次整合属于下方哪一（或几）类
|
||
2. **逐项执行该类的全部检核项**：打勾即改，不可只记 "后续补充"
|
||
3. **交叉验证**：执行完成后，用"框架截面自检"反向核对每项是否存在
|
||
4. **生成报告**：列出每个检核项的完成状态
|
||
|
||
---
|
||
|
||
### 整合类型与检核清单
|
||
|
||
#### 类型 1：新增基础设施 Skill
|
||
|
||
> 触发条件：在项目中创建了一个服务于 opencode 自身元系统的新 Skill（非项目业务 Skill）
|
||
|
||
| # | 检核项 | 操作 |
|
||
|---|--------|------|
|
||
| 1.1 | Skill 目录存在 `SKILL.md` 且含正确 YAML frontmatter | **强制**：第一行必须是 `---`，必须含 `name:` 字段，必须正确闭合。缺失 frontmatter 会导致 opencode 无法注册该 Skill（`"Skill not found"`），即使文件存在、registry 有注册、AGENTS.md 有引用。 |
|
||
| 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：新增数据文件
|
||
|
||
> 触发条件：新增或修改了 `.opencode/data/` 下的数据文件（changelog/deferred/pitfalls/distillery/profile/spec-docs 等）
|
||
|
||
| # | 检核项 | 操作 |
|
||
|---|--------|------|
|
||
| 2.1 | `canonical-manifest.json` → `template_data_files` 或 `template_phase_files` | **首选更新目标**：在 JSON 对应数组中追加新数据文件路径。phase 阶段数据文件归入 `template_phase_files`，其余归入 `template_data_files` |
|
||
| 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-tester/static-checks/run.py` → `MANIFEST_TO_INIT_SECTION` | 若新增了 manifest JSON 分组（非单文件），在 run.py 的映射表中新增条目。meta-check 会自动检测未映射的分组 |
|
||
| 2.7 | 所属 Skill 的 SKILL.md | 若数据文件归属某个 Skill，该 Skill 应引用正确的文件路径 |
|
||
|
||
#### 类型 3：新增运行时依赖
|
||
|
||
> 触发条件：新增或修改了 `.opencode/package.json` 中的 `dependencies`
|
||
|
||
| # | 检核项 | 操作 |
|
||
|---|--------|------|
|
||
| 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 规则
|
||
|
||
> 触发条件：在 AGENTS.md 中新增章节、修改规则逻辑、调整 Skill 调度条件
|
||
|
||
| # | 检核项 | 操作 |
|
||
|---|--------|------|
|
||
| 4.1 | AGENTS.md 引用新 Skill | 检查：新增的 Skill 是否已在 `opencode-init` Skills 白名单？是否已在 `epee-orchestrator/registry.md` 注册？ |
|
||
| 4.2 | AGENTS.md 引用新数据文件 | 检查：路径是否在 `opencode.json` 的 `instructions` 中？是否在 `opencode-init` 数据占位目录中？ |
|
||
| 4.3 | AGENTS.md 引用 `spec-docs` Skill | 检查：`spec-docs` Skill 是否已在 Skills 白名单？（此项为固定检查，因历史上发生过遗漏） |
|
||
| 4.4 | AGENTS.md 引用新 docs/ 文档 | 检查：`docs/` 下的文档路径是否存在？frontmatter 是否完整？（见 `docs/README.md` 元数据标准） |
|
||
|
||
#### 类型 5：修改 opencode.json 指令注入
|
||
|
||
> 触发条件：修改了 `opencode.json` 的 `instructions` 数组
|
||
|
||
| # | 检核项 | 操作 |
|
||
|---|--------|------|
|
||
| 5.1 | 新增路径指向的数据文件存在 | `read` 验证路径可访问 |
|
||
| 5.2 | 数据文件已在 `opencode-init` 数据占位目录中 | 确保 init 流程会保留/重置该文件 |
|
||
| 5.3 | 若路径指向 Skill 内部资源 | 确保该 Skill 在 Skills 白名单中 |
|
||
|
||
#### 类型 6：新增 docs/ 规范文档
|
||
|
||
> 触发条件：在 `docs/` 下新增了架构方案/技术规范/项目约定文档，且是框架级别（非项目专属）
|
||
|
||
| # | 检核项 | 操作 |
|
||
|---|--------|------|
|
||
| 6.1 | `docs/README.md` 目录结构图 | 若新增了子目录分类，更新目录结构图 |
|
||
| 6.2 | 文档 frontmatter 完整 | `id` / `title` / `type` / `status` / `created` / `updated` / `related_changelogs` |
|
||
| 6.3 | 文档编号唯一 | 检查 `id` 不与已有文档重复 |
|
||
| 6.4 | `spec-docs` Skill 可覆盖 | 确认 `spec-docs` 操作 B（周期审查）能发现该文档 |
|
||
|
||
---
|
||
|
||
### 框架截面自检（Cross-Section Verification）
|
||
|
||
> 整合完成后，Agent 必须运行此自检：逐一检查以下 "截面"，确认所有被引用的组件在对应位置都存在。
|
||
|
||
| 截面 | 检查方式 |
|
||
|------|---------|
|
||
| `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 `template_phase_files` | glob `.opencode/phase/**/*.md` + `.opencode/phase/*.json` → 不在 manifest 中 → 警告 |
|
||
| `canonical-manifest.json` VS disk | manifest 中的路径 → glob/read 验证文件存在 |
|
||
| Skill frontmatter 完整性 | 遍历所有 `SKILL.md` → 验证第一行 `---`、含 `name:` 字段、正确闭合 |
|
||
| `AGENTS.md` 引用的 Skill | grep Skill 名 → 必须在 `canonical-manifest.json` → `canonical_skills` 中 |
|
||
| `AGENTS.md` 引用的数据文件 | grep 文件路径 → 必须在 `canonical-manifest.json` → `template_data_files` 或 `template_phase_files` 中 |
|
||
| `AGENTS.md` 引用的 docs/ 文档 | glob 检查文件存在 |
|
||
| `opencode.json` → `instructions` 所列路径 | `read` 逐条验证文件存在 |
|
||
| `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 | 必须在 `canonical-manifest.json` → `canonical_skills` 中 |
|
||
| `.opencode/skills/` 下的 Skill 目录 | 若不在 `epee-orchestrator/registry.md` 中 → 缺失注册 |
|
||
| `.opencode/skills/` 下的 Skill 目录 | 若不在 `canonical_skills` 中且非项目级 → 警告 |
|
||
| `.opencode/data/` 下的数据文件 | 若不在 `template_data_files` 中 → 警告 |
|
||
| `.opencode/phase/` 下的数据文件 | 若不在 `template_phase_files` 中 → 警告 |
|
||
| `.opencode/data/` 下的数据文件 | 若需要注入上下文 → 检查是否在 `opencode.json` → `instructions` 中 |
|
||
|
||
### 整合自检执行规则
|
||
|
||
1. **先整合后自检**：先完成所有类型检核项的修改，再跑截面自检
|
||
2. **自检发现缺口 → 回到对应类型的检核清单补充**，不可手动修补绕过
|
||
3. **每项自检必须输出结果**：`✅ 通过` / `❌ 缺失：<具体描述>` / `⚠️ 跳过：<原因>`
|
||
4. **任何 ❌ 结果必须在最终报告前修复**
|
||
5. **运行 Layer 1 静态检查**：`python .opencode/skills/skill-tester/static-checks/run.py`，7 项检查必须全部通过。脚本验证 manifest↔init↔registry↔SKILL.md 之间的交叉引用一致性。**meta-check（第0项）会自动检测 manifest 新增分组是否被覆盖**——如有 FAIL，先在 run.py 的 `MANIFEST_TO_INIT_SECTION` 中补充映射再重跑。
|
||
|
||
---
|
||
|
||
## 自迭代日志
|
||
|
||
本节记录使用本 Skill 过程中发现的必要检查项。
|
||
|
||
### 已知必要检查
|
||
|
||
1. **阶段 2 的 C 组归位前必须先做 dry-run 展示** —— 批量移动文件是高破坏性操作，只要有一条分类错误就会污染 canonical 结构，必须让用户在列表上逐条过一遍再执行。
|
||
|
||
2. **重名冲突不许直接覆盖** —— C 组与 A 组重名时，A 组（模板版本）永远是 source of truth，冲突文件只能进 `_init-backup/`，让用户自行决定是否把差异合并回规范文件。
|
||
|
||
3. **registry 重建时先读后写** —— 阶段 4 不要直接用硬编码模板覆盖 registry.md，必须先解析现有条目，只移除项目级条目、补齐缺失条目，避免丢失已有条目。
|
||
|
||
4. **`.init-done` 是完成度契约** —— 只有阶段 6 验证通过后才能写入此文件。中途 abort 必须让 sentinel 缺失，这是保证下次会话能恢复触发的关键设计。
|
||
|
||
5. **`.gitignore` 用户主导** —— 阶段 5.5 对语言栈/IDE/OS 的判断完全来自用户问卷，不要根据文件探测"智能推断"，因为新项目此时通常还是空白，推断不准反而会填错条目。
|