@geminilight/mindos 0.5.14 → 0.5.16

package/skills/project-wiki/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-wiki
-description: "组织和维护 Vibe Coding 项目的 wiki 文档体系。当用户要求初始化/重构 wiki 结构、进入新项目且 wiki/ 不存在、或需要诊断和修复文档腐化时触发。"
+description: "组织和维护 Vibe Coding 项目的 wiki 文档体系。当用户要求初始化/重构 wiki 结构、进入新项目且 wiki/ 不存在、需要诊断和修复文档腐化、或需要管理 specs/refs/reviews 子目录的生命周期时触发。"
 ---
 
 # Project Wiki Skill
@@ -75,9 +75,15 @@ wiki/
 │   └── 90-changelog.md
 │
 ├── specs/                   — 任务 spec（活跃的，完成后归档）
-│   └── task-spec-xxx.md
+│   └── spec-{feature-name}.md
 ├── refs/                    — 参考资料（外部机制说明、技术调研）
-└── archive/                 — 已完结的 spec 和历史文档
+│   └── ref-{topic}.md
+├── reviews/                 — 代码/设计/spec 评审记录
+│   └── review-{date}-{subject}.md
+└── archive/                 — 已完结的文档（保留溯源，不污染活跃目录）
+    ├── specs/               — 已完成的 spec
+    ├── reviews/             — 历史评审
+    └── stages/              — 已归档的 stage 文件
 ```
 
 | 区段 | 用途 | 扩展性 |
@@ -132,8 +138,9 @@ wiki/
 | 40 | `conventions.md` | 有明确的编码偏好/约束（库选择、命名、错误处理模式等） |
 | 41 | `dev-pitfall-patterns.md` | 踩坑积累到需要系统性记录时 |
 | 6X | `stage-X.md` | 功能复杂度超过一句话能说清（150-300 行） |
-| — | `specs/task-spec-xxx.md` | 小功能 / 改进点的 spec；实现完成后归档到 `archive/` |
-| — | `refs/xxx.md` | 外部机制说明、技术调研、协议文档 |
+| — | `specs/spec-{name}.md` | 小功能 / 改进点的 spec；完成后移入 `archive/specs/` |
+| — | `refs/ref-{topic}.md` | 外部机制调研、技术选型对比、第三方 API 文档摘要 |
+| — | `reviews/review-{date}-{subject}.md` | 代码审查、spec 评审、设计评审的结论与 action items |
 | 80 | `known-pitfalls.md` | 踩坑即记，不等阶段结束 |
 | 81 | `postmortem-*.md` | 多个 bug 互相关联、暴露系统性问题时（单点问题用 pitfalls，系统性问题用 postmortem） |
 | 84 | `design-exploration.md` | 有 UI 设计探索、原型记录等创意过程产物时 |
@@ -148,17 +155,174 @@ wiki/
 
 **归档判断标准：** 同时满足以下两条才归档：① 该 stage 已完结超过一个阶段；② 当前及未来 stage 文件中无对它的跨引用。不确定时保留，宁可冗余不要断链。
 
+### 子目录管理
+
+四个子目录各有独立的命名规范、生命周期和归档规则。
+
+#### specs/ — 任务规格
+
+活跃的功能 spec，是比 stage 文件更细粒度的任务描述。
+
+| 项目 | 规则 |
+|------|------|
+| 命名 | `spec-{feature-name}.md`（用 kebab-case，名称反映功能而非编号） |
+| 创建时机 | 功能复杂度介于"backlog 一行"和"stage 文件一整章"之间 |
+| 内容 | 背景、目标、边界、验收标准、受影响文件列表 |
+| 归档 | 实现完成且 review 通过 → 移入 `archive/specs/`，backlog 对应项打勾 |
+| 头部标记 | `<!-- Status: draft | in-review | approved | done | archived -->` |
+
+#### refs/ — 参考资料
+
+外部知识的内部镜像——第三方 API 行为、协议格式、技术选型调研等。
+
+| 项目 | 规则 |
+|------|------|
+| 命名 | `ref-{topic}.md`（如 `ref-stripe-webhook.md`、`ref-webrtc-signaling.md`） |
+| 创建时机 | 外部知识在 2+ 个文件/对话中被重复查阅 |
+| 内容 | 机制说明、关键 API 摘要、与本项目的集成点、踩坑备注 |
+| 归档 | 不主动归档；集成方案废弃时标记 `<!-- Deprecated: YYYY-MM-DD | Reason -->` |
+| 引用 | stage/spec 文件中通过 `→ 详见 [refs/ref-xxx.md](./refs/ref-xxx.md)` 链接，不复制内容 |
+
+#### reviews/ — 评审记录
+
+代码审查、spec 评审、设计评审的结论存档。
+
+| 项目 | 规则 |
+|------|------|
+| 命名 | `review-{YYYY-MM-DD}-{subject}.md`（如 `review-2026-03-18-auth-spec.md`） |
+| 创建时机 | spec 评审完成后、重大代码变更 review 后、设计方案评审后 |
+| 内容 | 评审对象（链接到 spec/PR）、结论（通过/修改/拒绝）、action items、遗留讨论点 |
+| 归档 | action items 全部完成 → 移入 `archive/reviews/` |
+| 联动 | 创建 review 后，在对应 spec 头部追加 `<!-- Reviewed: YYYY-MM-DD → reviews/review-xxx.md -->` |
+
+#### archive/ — 归档目录
+
+已完结文档的长期存储。保留完整历史以便溯源，但不污染活跃目录。
+
+```
+archive/
+├── specs/      — 已完成的 spec（保留原文件名）
+├── reviews/    — 历史评审
+└── stages/     — 已归档的 stage 文件
+```
+
+| 规则 | 说明 |
+|------|------|
+| 归档操作 | `git mv wiki/specs/spec-xxx.md wiki/archive/specs/` |
+| 原位留痕 | 在 `01-project-roadmap.md` 或 `85-backlog.md` 中标注 `[archived → archive/specs/spec-xxx.md]` |
+| 引用不断链 | 归档后全文搜索旧路径（`grep -r "specs/spec-xxx" wiki/`），更新所有引用指向 `archive/` 下的新路径 |
+| 不删除 | archive 目录下的文件只做追加和查阅，不删除 |
+
 ---
 
-## Agent 阅读顺序
+### 渐进式披露
+
+wiki 文件按三层加载，避免 Agent 一次读入全部内容导致上下文浪费。
+
+#### 第一层：索引（始终可用）
+
+Agent 进入项目时只读两个文件，建立全局心智模型：
+
+```
+00-product-proposal.md  → 知道"做什么、不做什么"
+01-project-roadmap.md   → 知道"当前在哪个阶段、有哪些功能"
+```
+
+roadmap 中每行功能附带链接，Agent 根据当前任务决定是否深入。
+
+#### 第二层：结构（按场景加载）
+
+根据任务类型，Agent 按需加载对应的结构文件：
+
+| 任务类型 | 加载文件 | 不加载 |
+|---------|---------|--------|
+| 新功能开发 | `20-system-architecture` → 当前 `6X-stage` → 相关 `specs/` | 其他 stage、refs、reviews |
+| 修 Bug | `20-system-architecture` → `80-known-pitfalls` → 相关 `6X-stage` | 战略文件、无关 stage |
+| UI 调整 | `21-design-principle` → `20-system-architecture`（目录部分） | stage 文件（除非涉及功能逻辑） |
+| 技术调研 | `refs/ref-{topic}` → `20-system-architecture`（集成点） | spec、review |
+| 评审 | 对应 `specs/` → 相关 `refs/` → `40-conventions` | 不相关的 stage |
+
+#### 第三层：细节（按需钻取）
+
+Agent 只在以下信号出现时才读取更深层文件：
+
+- stage 文件中写了 `→ 详见 refs/ref-xxx.md` → 加载该 ref
+- spec 头部有 `<!-- Reviewed: ... -->` → 加载该 review 查看历史决策
+- pitfalls 中提到 `→ 复盘见 81-postmortem-xxx.md` → 加载该 postmortem
+- backlog 中有 `[archived → archive/specs/spec-xxx.md]` → 需要溯源时加载
+
+**关键原则：** 不主动扫描子目录。索引文件（roadmap、backlog）中的链接是唯一的"入口导航"。
+
+---
+
+### 关联管理
+
+wiki 文件之间存在引用依赖。一个文件变更后，引用它的文件可能需要同步更新。这套规则帮助 Agent 追踪和维护这些关联。
+
+#### 引用语法
+
+文件间引用统一使用相对路径 + 锚点：
+
+```markdown
+→ 详见 [20-system-architecture.md](./20-system-architecture.md#数据流)
+→ 详见 [refs/ref-stripe-webhook.md](./refs/ref-stripe-webhook.md)
+→ 归档于 [archive/specs/spec-auth.md](./archive/specs/spec-auth.md)
+```
+
+#### 依赖图（哪些文件引用谁）
+
+| 被引用文件 | 典型引用者 | 变更时需检查 |
+|-----------|-----------|------------|
+| `00-product-proposal` | roadmap、stage 文件 | 产品方向变更 → 检查所有 stage 的"背景"段 |
+| `20-system-architecture` | 所有 stage、所有 spec | 架构变更 → `grep -r "system-architecture" wiki/` 检查引用 |
+| `21-design-principle` | 前端相关 stage、spec | 新增 token → 检查现有组件是否需要适配 |
+| `refs/ref-*` | 引用该外部系统的 stage/spec | 外部 API 更新 → 沿引用链更新所有消费方 |
+| `specs/spec-*` | backlog（索引）、reviews（评审） | spec 完成 → 更新 backlog 状态、归档 spec |
+
+#### 变更联动 Checklist
+
+Agent 修改 wiki 文件时，执行以下检查：
+
+```
+修改文件 X
+  → grep -r "X" wiki/        # 找到所有引用 X 的文件
+  → 逐一检查：引用的信息是否仍然准确
+  → 不准确 → 更新引用方（或在引用旁加 <!-- May be outdated -->）
+```
+
+**特别注意的高频联动：**
+- 重命名/移动文件 → 全文搜索旧路径，更新所有引用
+- stage 归档 → 更新 roadmap 索引行、更新 backlog 对应条目
+- spec 完成 → 更新 backlog 打勾、移入 archive、检查 review 中的 action items
+
+#### 腐化检测
+
+每个阶段开始时（或触发重构流程时），Agent 执行一次完整性扫描：
+
+1. **断链检测**：`grep -rn '\./[a-z].*\.md' wiki/ | while read line; do ...` 检查所有 `./xxx.md` 引用目标是否存在
+2. **新鲜度检查**：扫描所有 `<!-- Last verified: YYYY-MM-DD -->` 标记，超过 30 天未验证的标记为 `<!-- May be outdated -->`
+3. **孤立文件检测**：`refs/` 和 `specs/` 下的文件如果没有被任何其他 wiki 文件引用 → 提示用户：是否需要归档或删除？
+4. **重复信息检测**：同一概念在两个文件中都有段落级展开 → 提示合并，保留一个权威源，另一个改为引用链接
+
+---
+
+## Agent 阅读顺序（渐进式）
+
+第一层（必读）：`00-product-proposal` → `01-project-roadmap`（定位当前阶段）
+
+第二层（按任务加载）：
 
 | 场景 | 路径 |
 |------|------|
-| 新对话 / 新功能 | `00-product-proposal` → `20-system-architecture` → 当前 `6X-stage-X` |
+| 新对话 / 新功能 | `20-system-architecture` → 当前 `6X-stage-X` → 相关 `specs/` |
 | 修 Bug | `20-system-architecture` → `80-known-pitfalls` → 相关 `6X-stage-X` |
 | 修 Bug（反复出现） | `81-postmortem-*` → `20-system-architecture` → `80-known-pitfalls` → 相关 `6X-stage-X` |
 | UI 调整 | `21-design-principle` → `20-system-architecture`（目录结构）→ 相关组件 |
 | 了解全貌 | `00-product-proposal` → `01-project-roadmap` → `20-system-architecture` |
+| 技术调研 | 相关 `refs/ref-*` → `20-system-architecture`（集成点部分） |
+| 评审任务 | 对应 `specs/spec-*` → `40-conventions` → 相关 `refs/` |
+
+第三层（按引用钻取）：文件中出现 `→ 详见 xxx` 链接时才加载目标文件。不主动扫描子目录。
 
 ---
 
@@ -218,8 +382,18 @@ Skill 触发时生成 wiki 结构，但 wiki 的日常同步发生在每次开
 
 **新建文件时机：**
 - 新功能复杂度超过一句话说清 → 新建 `wiki/6X-stage-X.md`
-- 小功能 / 改进点需要 spec → 新建 `wiki/specs/task-spec-xxx.md`（实现完成后归档到 `archive/`）
-- 外部机制调研 → 新建 `wiki/refs/xxx.md`
+- 小功能 / 改进点需要 spec → 新建 `wiki/specs/spec-{name}.md`（完成后移入 `archive/specs/`）
+- 外部机制调研 → 新建 `wiki/refs/ref-{topic}.md`
+- Spec / 代码 / 设计评审完成 → 新建 `wiki/reviews/review-{date}-{subject}.md`
+
+**归档时机：**
+- Spec 完成且 review 通过 → `git mv wiki/specs/spec-xxx.md wiki/archive/specs/`，backlog 打勾
+- Review 的 action items 全部完成 → `git mv wiki/reviews/review-xxx.md wiki/archive/reviews/`
+- Stage 归档 → `git mv wiki/6X-stage-X.md wiki/archive/stages/`，roadmap 标注 `[archived]`
+
+**关联维护（每次修改 wiki 文件时）：**
+- `grep -r "{被修改文件名}" wiki/` → 检查引用方是否需要同步更新
+- 重命名/移动文件 → 全文搜索旧路径，更新所有引用
 
 **定期检查（每个阶段开始时）：**
 - 扫描 wiki/ 下所有文件，更新 `Last verified` 日期
@@ -250,3 +424,6 @@ Skill 触发时生成 wiki 结构，但 wiki 的日常同步发生在每次开
 | `design-exploration.tmpl.md` | `84-design-exploration.md` |
 | `backlog.tmpl.md` | `85-backlog.md` |
 | `changelog.tmpl.md` | `90-changelog.md` |
+| `spec.tmpl.md` | `specs/spec-{name}.md` |
+| `ref.tmpl.md` | `refs/ref-{topic}.md` |
+| `review.tmpl.md` | `reviews/review-{date}-{subject}.md` |

package/skills/project-wiki/assets/ref.tmpl.md

@@ -0,0 +1,34 @@
+<!-- Last verified: YYYY-MM-DD -->
+
+# Ref: {主题名称}
+
+## 概述
+
+一句话说明这是什么、为什么需要记录。
+
+## 机制说明
+
+<!-- 外部系统/协议/API 的工作原理 -->
+
+## 关键 API 摘要
+
+| 端点/方法 | 用途 | 注意事项 |
+|-----------|------|---------|
+| ... | ... | ... |
+
+## 与本项目的集成点
+
+<!-- 本项目在哪里使用了这个外部系统？涉及哪些文件？ -->
+
+| 集成位置 | 文件 | 说明 |
+|---------|------|------|
+| ... | `src/xxx.ts` | ... |
+
+## 踩坑备注
+
+<!-- 集成过程中遇到的非显而易见的问题 -->
+
+## 来源
+
+- 官方文档：[链接]
+- 版本：X.Y.Z（记录时的版本）

package/skills/project-wiki/assets/review.tmpl.md

@@ -0,0 +1,27 @@
+<!-- Created: YYYY-MM-DD -->
+
+# Review: {评审主题}
+
+## 评审对象
+
+- 类型：spec / code / design
+- 链接：[specs/spec-xxx.md](../specs/spec-xxx.md) 或 PR #xxx
+
+## 结论
+
+<!-- 通过 / 需修改 / 拒绝 -->
+
+## 发现的问题
+
+| # | 严重程度 | 问题描述 | 建议修改 |
+|---|---------|---------|---------|
+| 1 | high/medium/low | ... | ... |
+
+## Action Items
+
+- [ ] Action 1（负责人：xxx）
+- [ ] Action 2
+
+## 遗留讨论点
+
+<!-- 未达成共识、需要后续讨论的内容 -->

package/skills/project-wiki/assets/spec.tmpl.md

@@ -0,0 +1,45 @@
+<!-- Status: draft | in-review | approved | done | archived -->
+<!-- Created: YYYY-MM-DD -->
+<!-- Reviewed: (填写评审日期和链接) -->
+
+# Spec: {功能名称}
+
+## 背景
+
+为什么要做这个功能？解决什么问题？
+
+## 目标
+
+- 目标 1
+- 目标 2
+
+## 边界（不做什么）
+
+- 不做 X
+- 不做 Y
+
+## 设计方案
+
+### 数据模型
+
+<!-- 类型定义、数据结构 -->
+
+### API 变更
+
+<!-- 新增/修改的接口 -->
+
+### 受影响文件
+
+| 文件 | 变更类型 | 说明 |
+|------|---------|------|
+| `src/xxx.ts` | 修改 | ... |
+
+## 验收标准
+
+- [ ] 标准 1
+- [ ] 标准 2
+
+## 相关链接
+
+- → 详见 [refs/ref-xxx.md](../refs/ref-xxx.md)（如有）
+- → 所属阶段 [6X-stage-X.md](../6X-stage-X.md)

package/skills/project-wiki/references/file-reference.md

@@ -252,3 +252,66 @@
 | 会议纪要 | 对话历史就是"会议纪要"，MEMORY.md 更有效 | 有多个人类参与决策时 |
 | 贡献指南（CONTRIBUTING.md） | 除非有其他人类贡献者 | 开源或团队扩展时 |
 | 架构决策记录（ADR） | stage 文件的"设计决策"章节够用 | stage 超过 10 个、早期决策上下文丢失时 |
+
+---
+
+## 子目录文件说明
+
+### specs/spec-{name}.md — 任务规格
+
+**为什么需要：** Stage 文件覆盖一个阶段的全部功能，粒度偏大。当一个小功能/改进点需要明确的边界和验收标准，但又不值得开一个完整的 stage 时，spec 是最合适的载体。它也是 review 的评审对象——没有 spec，评审就没有锚点。
+
+**写给谁看：** Agent + 评审者
+
+**核心内容：** 背景、目标、边界、设计方案（数据模型 + API + 受影响文件）、验收标准
+
+**生命周期：** draft → in-review → approved → done → archived。完成后移入 `archive/specs/`。
+
+**与 stage 文件的关系：** Spec 是 stage 内某个功能点的展开。Stage 文件用一行索引指向 spec，不重复 spec 的内容。
+
+**维护频率：** 活跃开发期间持续更新，完成后归档不再修改。
+
+---
+
+### refs/ref-{topic}.md — 参考资料
+
+**为什么需要：** Agent 没有外部系统的内部知识。Stripe webhook 的重试机制、WebRTC 的 signaling 流程、某个私有 API 的字段含义——这些信息每次新对话都要重新查阅。写一次 ref，后续所有 stage/spec 直接引用，不重复调研。
+
+**写给谁看：** Agent
+
+**核心内容：** 机制说明、关键 API 摘要、与本项目的集成点、踩坑备注、来源链接和版本
+
+**生命周期：** 长期存在，不主动归档。外部系统更新时更新内容并刷新 `Last verified` 标记。集成方案废弃时标记 `<!-- Deprecated -->`。
+
+**与其他文件的关系：** Stage/spec 中通过 `→ 详见 refs/ref-xxx.md` 引用。Ref 文件本身不引用 stage/spec（单向依赖）。
+
+**维护频率：** 外部系统版本更新时检查。日常开发中基本稳定。
+
+---
+
+### reviews/review-{date}-{subject}.md — 评审记录
+
+**为什么需要：** Spec 通过评审进入 approved 状态，但评审中发现的问题和 action items 如果不记录，下次对话就丢失了。Review 文件是评审结论的持久化存储，也是归档前的 checklist——action items 全部完成才能归档。
+
+**写给谁看：** 你自己 + Agent（检查 action items）
+
+**核心内容：** 评审对象（链接到 spec/PR）、结论、发现的问题列表、action items、遗留讨论点
+
+**生命周期：** 创建后更新 action items 的完成状态，全部完成后移入 `archive/reviews/`。
+
+**联动规则：** 创建后在对应 spec 头部追加 `<!-- Reviewed: YYYY-MM-DD → reviews/review-xxx.md -->`。
+
+**维护频率：** 评审后创建，action items 推进时更新勾选，归档后不再修改。
+
+---
+
+### archive/ — 归档目录
+
+**为什么需要：** 删除历史文档会丢失上下文——三个月后你想知道"当时为什么这样设计"却找不到了。归档保留完整历史，但把它们从活跃目录移走，减少 Agent 的搜索噪音。
+
+**子结构：** `archive/specs/`、`archive/reviews/`、`archive/stages/`
+
+**归档原则：**
+- 只做移入，不删除（`git mv` 保留 git 历史）
+- 原位留痕：在 roadmap/backlog 中标注 `[archived → archive/xxx]`
+- 引用不断链：归档后全文搜索旧路径，更新指向新路径