@geminilight/mindos 0.5.7 → 0.5.9

package/skills/project-wiki/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: project-wiki
+description: "组织和维护 Vibe Coding 项目的 wiki 文档体系。当用户要求初始化/重构 wiki 结构、进入新项目且 wiki/ 不存在、或需要诊断和修复文档腐化时触发。"
+---
+
+# Project Wiki Skill
+
+为 Vibe Coding 项目（人类描述意图，Agent 写代码）生成和维护结构化 wiki。wiki 是 Agent 的输入物料，直接决定输出质量。
+
+---
+
+## 执行流程
+
+### 初始化（wiki/ 不存在或为空）
+
+1. **扫描** `wiki/` 目录，列出已有文件
+2. **对照必要文件清单**（见下方"文件体系"），识别缺失项
+3. **与用户确认**将要创建的文件列表
+4. **生成骨架**：从本 Skill 的 `assets/` 目录读取对应模板，填入用户上下文（不确定的部分留 `<!-- TODO: ... -->` 占位）
+5. **更新导航**：如已有 `01-project-roadmap.md`，追加新阶段索引行
+6. **标记新鲜度**：每个生成的文件头部加 `<!-- Last verified: YYYY-MM-DD | Current stage: X -->`
+7. **注入维护规则**：检查项目 `CLAUDE.md` 中是否已有 wiki 维护规则。已有则跳过或合并差异；没有则**追加**（不替换整个文件）
+
+### 重构 / 更新（wiki/ 已有文件）
+
+1. **扫描** `wiki/` 下所有文件，检查编号前缀、新鲜度标记
+2. **诊断**：缺编号前缀？信息重叠？文件过大需拆分？已完结 stage 未归档？内容与代码不一致？
+3. **生成改动清单**（重命名 / 合并 / 拆分 / 归档 / 更新内容），与用户确认
+4. **执行改动**
+5. **验证一致性**：文件间引用链接有效、roadmap 索引与实际文件对应
+6. **检查维护规则**：确认项目 `CLAUDE.md` 中已有 wiki 维护规则，缺失则追加（不替换整个文件）
+
+---
+
+## 文件体系
+
+### 核心模型：Why / What / How / Look × 全局 / 阶段
+
+| | 全局（稳定，新阶段才改） | 阶段（增量更新） |
+|---|---|---|
+| **Why** | `00-product-proposal.md` | — |
+| **What** | `01-project-roadmap.md` — 功能索引 | `1X-stage-X.md` — 设计决策 |
+| **How** | `02-system-architecture.md` — 架构 + 类型 | `1X-stage-X.md` — API、数据模型、受影响文件 |
+| **API** | `04-api-reference.md` — 完整 API 参考 | `1X-stage-X.md` — 新增 API 的设计决策 |
+| **Look** | `03-design-principle.md` — 视觉语言 | — |
+
+**关键规则：** stage 文件同时包含 What 和 How。一个功能的设计决策、API 契约、数据模型放在一个文件里。全局文件只做索引和导航，不重复 stage 的细节。
+
+### 规划层级
+
+| | Roadmap (`01`) | Backlog (`85`) |
+|---|---|---|
+| 时间跨度 | 月 / 季度级 | 周 / 迭代级 |
+| 粒度 | 方向、里程碑、大功能 | 具体任务、bug、小需求 |
+| 回答 | 我们要去哪里？ | 下一步做什么？ |
+
+**使用时机：** 开始任务前先对照 roadmap 确认阶段匹配，再从 backlog 取具体任务执行。任务完成后在 backlog 打勾，发版时从已完成条目整理写入 changelog。
+
+### 必要文件（第一梯队）
+
+| 编号 | 文件 | 写给谁 | 核心内容 |
+|------|------|--------|---------|
+| 00 | `product-proposal.md` | Agent + 你 | 产品愿景、产品定位、**不做什么**、目标用户、功能矩阵、路线图叙事 |
+| 01 | `project-roadmap.md` | Agent + 你 | 阶段总览表、全量功能索引（功能×状态×stage链接）、里程碑 |
+| 02 | `system-architecture.md` | Agent | 技术栈、目录结构、数据流、核心类型、环境变量（300-500 行） |
+
+### 按需文件（第二梯队）
+
+| 编号 | 文件 | 何时需要 |
+|------|------|---------|
+| 03 | `design-principle.md` | 有自定义视觉语言时（非默认 UI 库样式） |
+| 04 | `api-reference.md` | API 超过 5 条路由，或 stage 归档后仍需查 API 细节 |
+| 05 | `glossary.md` | 项目有领域术语，Agent 容易用错词或混用近义词 |
+| 06 | `conventions.md` | 有明确的编码偏好/约束（库选择、命名、错误处理模式等） |
+| 1X | `stage-X.md` | 功能复杂度超过一句话能说清（150-300 行） |
+| — | `task-spec-xxx.md` | 小功能 / 改进点的 spec，包含需求描述和验收标准；实现完成后归档或合并进对应 stage 文件 |
+| 80 | `known-pitfalls.md` | 踩坑即记，不等阶段结束 |
+| 81 | `development-guide.md` | 有非显而易见的配置要求时 |
+| 82 | `postmortem-*.md` | 多个 bug 互相关联、暴露系统性问题时（单点问题用 pitfalls，系统性问题用 postmortem） |
+| 84 | `design-exploration.md` | 有 UI 设计探索、原型记录等创意过程产物时 |
+| 85 | `backlog.md` | 有临时 bug、技术债、改进想法需要追踪时 |
+| 8X | `external-*.md` | 依赖外部系统私有数据格式时 |
+| 90 | `changelog.md` | 发版时从 `85-backlog.md` 已完成条目整理写入，面向用户描述变更，不记内部实现细节 |
+
+> 每个文件的详细说明和"为什么需要"的论证见 `references/file-reference.md`。
+
+### 目录结构与编号规范
+
+```
+wiki/
+├── 00-product-proposal.md        # Why
+├── 01-project-roadmap.md         # What（全局索引）
+├── 02-system-architecture.md     # How（全局）
+├── 03-design-principle.md        # Look（全局）
+├── 04-api-reference.md           # API（全局）
+├── 05-glossary.md                # 术语表（有领域术语时）
+├── 06-conventions.md             # 编码约定（有明确偏好时）
+├── 10-stage-a.md                 # 阶段文件
+├── 11-stage-b.md
+├── ...
+├── 80-known-pitfalls.md          # 辅助参考
+├── 81-development-guide.md
+├── 82-postmortem-*.md            # 系统性问题复盘（多 bug 关联时）
+├── 84-design-exploration.md      # 设计探索/原型记录（有 UI 探索时）
+├── 85-backlog.md                 # Bug、技术债、改进想法
+├── 90-changelog.md               # 日志
+└── archive/                      # 已完结阶段归档
+```
+
+| 区段 | 用途 |
+|------|------|
+| `00-09` | 全局文件，按阅读优先级排列 |
+| `10-79` | 阶段文件，按时间递增 |
+| `80-89` | 辅助参考文件 |
+| `90-99` | 日志类文件 |
+
+### Stage 文件生命周期
+
+阶段完全交付且后续阶段不再引用其 API/数据模型时 → 移入 `wiki/archive/`，`01-project-roadmap.md` 中保留索引行并标注 `[archived]`。
+
+**归档判断标准：** 同时满足以下两条才归档：① 该 stage 已完结超过一个阶段；② 当前及未来 stage 文件中无对它的跨引用。不确定时保留，宁可冗余不要断链。
+
+---
+
+## Agent 阅读顺序
+
+| 场景 | 路径 |
+|------|------|
+| 新对话 / 新功能 | `00-product-proposal` → `02-system-architecture` → 当前 `stage-X` |
+| 修 Bug | `02-system-architecture` → `80-known-pitfalls` → 相关 `stage-X` |
+| 修 Bug（反复出现） | `82-postmortem-*` → `02-system-architecture` → `80-known-pitfalls` → 相关 `stage-X` |
+| UI 调整 | `03-design-principle` → `02-system-architecture`（目录结构）→ 相关组件 |
+| 了解全貌 | `00-product-proposal` → `01-project-roadmap` → `02-system-architecture` |
+
+---
+
+## 文档编写规范
+
+1. **写给 Agent 的文档用结构化格式。** 表格 > 段落，代码块 > 文字描述，类型定义 > 自然语言。
+2. **写给自己的文档记决策不记细节。** "为什么选 X 不选 Y" > "X 的安装命令"。
+3. **一个信息只在一个地方维护。** 两处记录同一信息必然不一致。
+4. **Stage 文件是功能的唯一权威来源。** 全局文件只做索引。
+5. **标记新鲜度：** `<!-- Last verified: YYYY-MM-DD | Current stage: X | May be outdated after Stage Y -->`
+6. **宁可不写，不要写了不维护。** 过时文档比没文档更危险。
+7. **文件间引用用相对路径。** wiki 文件之间互引用 `./XX-filename.md#锚点` 格式，引用源码用 `../server/src/xxx.ts` 格式。
+8. **追求信息密度，不追求篇幅。** 具体标准：
+
+**内容取舍——写什么、不写什么：**
+- 写决策和约束（"用 dayjs，因为 moment 已废弃"），不写 Agent 能从源码读到的事实（"LoginForm 接受 onSubmit prop"）
+- 写跨模块关系（"A 通过 WebSocket 推送给 B"），不写模块内部显而易见的逻辑
+- 写"为什么不"（"不用 SSR，因为纯内网工具"），当"为什么是"显而易见时不写
+
+**表达密度——同一信息用最少字数传达：**
+- 一行表格能说清的，不展开成一段话
+- 不写铺垫句（"在这一节中我们将讨论..."）、不写总结句（"综上所述..."）、不复述上下文
+- 每句话删到"再删就丢信息"为止
+
+**膨胀信号——出现以下情况说明写多了：**
+- 一个 section 超过 20 行却没有代码块或表格
+- 同一个概念在两个文件中都有段落级展开
+- 读完一段话后能概括成一行表格而不丢失关键信息
+
+> 文档维护的投入信号和时机指南见 `references/writing-guide.md`。
+
+---
+
+## 日常维护规则
+
+Skill 触发时生成 wiki 结构，但 wiki 的日常同步发生在每次开发对话中。以下规则应在初始化完成后写入项目 `CLAUDE.md`，使 Agent 在正常开发流程中自动维护 wiki，无需反复触发本 skill。
+
+写入 CLAUDE.md 的内容（根据项目实际存在的 wiki 文件裁剪，只保留已创建的文件对应的行）：
+
+```markdown
+## Wiki 维护
+
+开发过程中，以下操作需要同步更新对应 wiki 文件：
+
+| 当你做了这件事 | 更新哪个文件 |
+|--------------|------------|
+| 新增/修改 API 路由 | `wiki/04-api-reference.md` 追加或修改对应条目 |
+| 完成一个 stage 的功能 | `wiki/01-project-roadmap.md` 对应行状态改为 ✅ |
+| 遇到非显而易见的坑 | `wiki/80-known-pitfalls.md` 追加一条（现象、原因、解法） |
+| 多个 bug 互相关联、暴露系统性问题 | 新建 `wiki/82-postmortem-*.md`（单点问题用 pitfalls，系统性问题用 postmortem） |
+| 架构变更（新模块、新数据流） | `wiki/02-system-architecture.md` 更新对应章节 |
+| 阶段全部交付 | `wiki/90-changelog.md` 补一笔（从 backlog 已完成条目整理） |
+| 发现 bug / 技术债 / 改进想法 | `wiki/85-backlog.md` 追加一条 |
+| 新增设计 token / 动效 | `wiki/03-design-principle.md` 追加对应条目 |
+| 出现新领域术语 | `wiki/05-glossary.md` 追加定义，防止 Agent 后续用词混乱 |
+| 重命名 / 移动 wiki 文件 | 同步更新所有引用该文件的链接 |
+
+**新建文件时机：**
+- 新功能复杂度超过一句话说清 → 新建 `wiki/1X-stage-X.md`
+- 小功能 / 改进点需要 spec → 新建 `wiki/task-spec-xxx.md`（实现完成后归档或合并进 stage 文件）
+
+**定期检查（每个阶段开始时）：**
+- 扫描 wiki/ 下所有文件，更新 `Last verified` 日期
+- 标出内容可能已过时的章节（加 `<!-- May be outdated -->` 注释）
+
+不需要在每次 commit 时都更新——在功能完成、API 变更、架构调整这些"节点"时同步即可。
+```
+
+---
+
+## 模板
+
+所有模板位于本 Skill 的 `assets/` 目录。生成文件时读取对应模板，填入项目上下文。
+
+| 模板文件 | 对应 wiki 文件 |
+|---------|---------------|
+| `product-proposal.tmpl.md` | `00-product-proposal.md` |
+| `project-roadmap.tmpl.md` | `01-project-roadmap.md` |
+| `system-architecture.tmpl.md` | `02-system-architecture.md` |
+| `design-principle.tmpl.md` | `03-design-principle.md` |
+| `api-reference.tmpl.md` | `04-api-reference.md` |
+| `glossary.tmpl.md` | `05-glossary.md` |
+| `conventions.tmpl.md` | `06-conventions.md` |
+| `stage-x.tmpl.md` | `1X-stage-X.md` |
+| `known-pitfalls.tmpl.md` | `80-known-pitfalls.md` |
+| `development-guide.tmpl.md` | `81-development-guide.md` |
+| `postmortem.tmpl.md` | `82-postmortem-*.md` |
+| `design-exploration.tmpl.md` | `84-design-exploration.md` |
+| `backlog.tmpl.md` | `85-backlog.md` |
+| `changelog.tmpl.md` | `90-changelog.md` |

package/skills/project-wiki/assets/api-reference.tmpl.md

@@ -0,0 +1,49 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# API 参考
+
+> 设计决策见各 stage 文件，本文件只记录活跃 API 的完整契约。
+
+## 概览
+
+| 方法 | 路径 | 用途 | 引入阶段 |
+|------|------|------|---------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+---
+
+## <!-- TODO: API 分组名称 -->
+
+### `METHOD /api/path`
+
+<!-- TODO: 一句话说明用途 -->
+
+**请求：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+```json
+{
+  // <!-- TODO: 请求体示例 -->
+}
+```
+
+**响应：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+```json
+{
+  // <!-- TODO: 响应体示例 -->
+}
+```
+
+**错误码：**
+
+| 状态码 | 含义 |
+|--------|------|
+| <!-- TODO --> | <!-- TODO --> |

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

@@ -0,0 +1,15 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# Backlog
+
+> 临时 bug、技术债、改进想法。解决后移除或转入对应 stage 文件。
+
+## Bug
+
+- [ ] <!-- TODO -->
+
+## 技术债
+
+## 改进想法
+
+## 待验证

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

@@ -0,0 +1,16 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 变更日志
+
+## Stage A — <!-- TODO: 主题 -->
+
+**日期：** <!-- TODO: YYYY-MM-DD -->
+
+### 新增
+- <!-- TODO -->
+
+### 变更
+- <!-- TODO -->
+
+### 关键决策
+- <!-- TODO: 为什么这样做 -->

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

@@ -0,0 +1,29 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 编码约定
+
+> 项目级编码偏好和约束。Agent 写代码前参考此文件。
+
+## 库选择
+
+| 用途 | 使用 | 不使用 | 原因 |
+|------|------|--------|------|
+| <!-- TODO: e.g., 日期处理 --> | <!-- TODO: e.g., dayjs --> | <!-- TODO: e.g., moment --> | <!-- TODO --> |
+
+## 命名规范
+
+| 对象 | 规范 | 示例 |
+|------|------|------|
+| <!-- TODO: e.g., React 组件 --> | <!-- TODO: e.g., PascalCase --> | <!-- TODO: e.g., UserProfile --> |
+
+## 代码模式
+
+### 错误处理
+<!-- TODO: e.g., 统一用 Result 模式 / try-catch + 自定义 Error 类 -->
+
+### 类型约束
+<!-- TODO: e.g., 禁止 any，使用 unknown + 类型守卫 -->
+
+## 禁止项
+
+- <!-- TODO: e.g., 不使用 console.log 做日志，统一用 logger -->

package/skills/project-wiki/assets/design-exploration.tmpl.md

@@ -0,0 +1,26 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 设计探索
+
+> 记录 UI 设计探索、原型迭代、视觉方案对比等创意过程产物。不追求完整，有就记。
+
+## <!-- TODO: 探索主题 -->
+
+### 背景 / 目标
+
+<!-- TODO: 为什么要探索这个方向 -->
+
+### 方案对比
+
+| 方案 | 描述 | 优点 | 缺点 |
+|------|------|------|------|
+| A | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+| B | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+### 最终选择
+
+<!-- TODO: 选了哪个、为什么 -->
+
+### 参考 / 截图
+
+<!-- TODO: 参考链接、截图路径、灵感来源 -->

package/skills/project-wiki/assets/design-principle.tmpl.md

@@ -0,0 +1,48 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 设计原则
+
+## 设计哲学
+
+<!-- TODO: 一句话定义视觉方向，如"CRT 终端美学"或"极简留白" -->
+
+## 调色板
+
+| Token | 值 | 语义用途 |
+|-------|-----|---------|
+| `--primary` | <!-- TODO --> | <!-- TODO --> |
+| `--bg` | <!-- TODO --> | <!-- TODO --> |
+| `--text` | <!-- TODO --> | <!-- TODO --> |
+| `--success` | <!-- TODO --> | 成功状态 |
+| `--warning` | <!-- TODO --> | 警告状态 |
+| `--error` | <!-- TODO --> | 错误状态 |
+
+## 字体系统
+
+| 属性 | 值 |
+|------|-----|
+| 字体族 | <!-- TODO --> |
+| 基础字号 | <!-- TODO --> |
+| 字号阶梯 | <!-- TODO: e.g., 12 / 14 / 16 / 20 / 24 / 32 --> |
+| 行高 | <!-- TODO --> |
+
+## 间距与布局
+
+| 属性 | 值 |
+|------|-----|
+| 基准单位 | <!-- TODO: e.g., 4px --> |
+| 间距阶梯 | <!-- TODO: e.g., 4 / 8 / 12 / 16 / 24 / 32 / 48 --> |
+| 栅格 | <!-- TODO --> |
+| 响应式断点 | <!-- TODO --> |
+
+## 动效规范
+
+| 属性 | 值 |
+|------|-----|
+| 过渡时长 | <!-- TODO: e.g., 150ms / 300ms --> |
+| 缓动函数 | <!-- TODO --> |
+| 关键帧动画 | <!-- TODO --> |
+
+## 组件模式
+
+<!-- TODO: 卡片、面板、按钮等的通用视觉约束 -->

package/skills/project-wiki/assets/development-guide.tmpl.md

@@ -0,0 +1,38 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 开发指南
+
+## 环境要求
+
+| 依赖 | 版本 |
+|------|------|
+| <!-- TODO --> | <!-- TODO --> |
+
+## 快速启动
+
+```bash
+# 安装依赖
+<!-- TODO -->
+
+# 启动开发环境
+<!-- TODO -->
+```
+
+## 特殊配置
+
+<!-- TODO: 代理地址、特殊环境变量、构建顺序依赖等非显而易见的配置 -->
+
+## 构建与部署
+
+```bash
+# 生产构建
+<!-- TODO -->
+
+# 部署
+<!-- TODO -->
+```
+
+## 常见问题
+
+### <!-- TODO: 问题标题 -->
+<!-- TODO: 解决方法 -->

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

@@ -0,0 +1,9 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 术语表
+
+> 统一项目中的领域术语，防止 Agent 用错词或混用近义词。
+
+| 术语 | 定义 | 不要混淆 |
+|------|------|---------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO: 容易混淆的近义词 --> |

package/skills/project-wiki/assets/known-pitfalls.tmpl.md

@@ -0,0 +1,21 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 踩坑记录
+
+## API 集成
+
+### <!-- TODO: 现象标题 -->
+- **现象：** <!-- TODO -->
+- **原因：** <!-- TODO -->
+- **解决方案：** <!-- TODO -->
+- **教训：** <!-- TODO: 可迁移到其他模块的规则 -->
+
+## 前端
+
+## 文件系统
+
+## 进程生命周期
+
+## 并发 / 性能
+
+## 构建 / 部署

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

@@ -0,0 +1,38 @@
+<!-- Last verified: YYYY-MM-DD -->
+
+# Postmortem — <!-- TODO: 主题 -->
+
+> 多个 bug 互相关联时的深度复盘。单点问题用 `80-known-pitfalls.md`，系统性问题用本文件。
+
+## Bug 时间线
+
+| # | 现象 | 根因 | 修复轮次 |
+|---|------|------|---------|
+| 1 | <!-- TODO --> | <!-- TODO --> | 轮次 1 |
+
+## 为什么不断出现
+
+<!-- 系统性根因分析，不是重复每个 bug 的技术原因。典型角度：
+     - 缺少端到端心智模型（只看局部代码，不画数据流）
+     - 组件各自正确但组合出错（接口契约缺失）
+     - 测试只覆盖 happy path（遗漏了关键场景组合）
+     - 数据来源混乱（运行态 vs 配置态不分）
+-->
+
+### <!-- TODO: 根因 1 标题 -->
+
+<!-- TODO -->
+
+## 提炼的设计规则
+
+<!-- 从本次事故中提炼的可复用规则，适用于同类模块 -->
+
+### 规则 1: <!-- TODO -->
+
+<!-- TODO -->
+
+## Checklist
+
+<!-- 以后改这类代码时对照使用 -->
+
+- [ ] <!-- TODO -->

package/skills/project-wiki/assets/product-proposal.tmpl.md

@@ -0,0 +1,41 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 产品提案：<!-- TODO: 产品名称 -->
+
+<!-- 目标长度：150-200 行。这是 Agent 的行为边界文件，不是完整 PRD。
+     写"不做什么"比"做什么"更重要——它防止 Agent 越界发挥。
+     用户场景、竞品分析、成功指标等 PRD 内容不放在这里。 -->
+
+## 产品愿景
+
+<!-- TODO: 2-3 句话。为什么做这个？解决什么根本问题？长期往哪走？ -->
+
+## 产品定位
+
+<!-- TODO: 一句话说清楚现在做什么 -->
+
+## 不做什么
+
+<!-- 这比"做什么"更重要——防止 Agent 越界发挥 -->
+
+- <!-- TODO: 明确的边界约束 -->
+
+## 目标用户
+
+| 用户角色 | 核心场景 | 当前替代方案 | 痛点 |
+|---------|---------|------------|------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+## 功能矩阵
+
+| 功能 | 解决的问题 | 阶段 | 状态 |
+|------|-----------|------|------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+## 路线图叙事
+
+<!-- 每个阶段 3 行以内：主题、一句话目标、成功标志。详细设计见 stage 文件。 -->
+
+### Stage A — <!-- TODO: 主题 -->
+**目标：** <!-- TODO: 一句话 -->
+**成功标志：** <!-- TODO -->

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

@@ -0,0 +1,23 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 项目路线图
+
+## 阶段总览
+
+| 阶段 | 主题 | 状态 | 文件 |
+|------|------|------|------|
+| A | <!-- TODO --> | <!-- ✅ Done / 🚧 In Progress / 📋 Planned --> | [stage-a](./10-stage-a.md) |
+
+## 功能索引
+
+### Stage A — <!-- TODO: 主题 -->
+
+| # | 功能 | 状态 | 备注 |
+|---|------|------|------|
+| A1 | <!-- TODO --> | <!-- ✅ / 🚧 / 📋 --> | |
+
+## 里程碑
+
+| 日期 | 里程碑 | 状态 |
+|------|--------|------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |

package/skills/project-wiki/assets/stage-x.tmpl.md

@@ -0,0 +1,78 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: X -->
+
+# Stage X — <!-- TODO: 主题 -->
+
+## 功能汇总
+
+| # | 功能 | 状态 | 备注 |
+|---|------|------|------|
+| X1 | <!-- TODO --> | <!-- ✅ / 🚧 / 📋 --> | |
+
+---
+
+## X1: <!-- TODO: 功能名称 -->
+
+### 用户场景
+
+<!-- TODO: 谁在什么情况下做什么 -->
+
+### 设计决策
+
+| 决策点 | 选择 | 原因 | 放弃的方案 |
+|--------|------|------|-----------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+### 数据流（涉及多组件/多进程交互时必填）
+
+<!-- 数据在组件间怎么流：谁写、谁读、什么时机、用什么介质（env / file / API / PID / DB）。
+     关注点：
+     - 同一份数据有几个来源？优先级是什么？
+     - 写入和读取是否在同一个进程/时间线？
+     - 配置变更后，哪些组件需要重新加载？
+-->
+
+```
+<!-- TODO: 用文字或 ASCII 图描述数据流 -->
+```
+
+### API 契约
+
+```
+METHOD /api/path
+```
+
+**请求：**
+```json
+{
+  // <!-- TODO -->
+}
+```
+
+**响应：**
+```json
+{
+  // <!-- TODO -->
+}
+```
+
+### 数据模型
+
+```typescript
+// <!-- TODO -->
+```
+
+### 受影响文件
+
+| 文件 | 改动类型 | 说明 |
+|------|---------|------|
+| <!-- TODO --> | 新增 / 修改 | <!-- TODO --> |
+
+### 实现摘要
+
+<!-- 功能完成后填写：关键实现细节、与设计的偏差 -->
+
+---
+
+## 遗留项 / Backlog
+
+- <!-- TODO -->