菜单
组织和维护 Vibe Coding 项目的 wiki 文档体系。当用户要求初始化/重构 wiki 结构、进入新项目且 wiki/ 不存在、需要诊断和修复文档腐化、或需要管理 specs/refs/reviews 子目录的生命周期时触发。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/GeminiLight/MindOS --skill project-wiki命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
MindOS: local knowledge assistant & shared KB. Keeps decisions, notes, SOPs, debugging lessons, research findings, preferences across sessions/agents. Core: save notes, search KB, organize files, run workflows, review, append CSV, hand off context, distill lessons. NOT for app source or paths outside KB. Triggers: save/record, search notes, update files, organize, run workflow, capture decisions, append CSV, hand off context, check past discussions, distill lessons. Proactive: (1) search first for stored context, (2) offer to save after valuable work, (3) suggest persisting key decisions.
MindOS 是用户的本地知识助手，也是跨会话、跨 Agent 共享的知识库。它保存决策记录、会议纪要、SOP、 排错经验、架构选型、调研结论和偏好设置。 仅 mindRoot 知识库内任务。不用于：改代码仓库、项目源码、KB 外路径。 核心概念：空间、指令(INSTRUCTION.md)、技能(SKILL.md)；笔记可承载指令与技能。 触发场景：保存或记录任何内容、搜索历史笔记或上下文、更新或编辑文件、整理或重组文件结构、 执行SOP或工作流、捕获对话中的决策、复盘或总结经验、追加表格或CSV数据、跨Agent交接上下文、 提炼经验教训、同步关联文档、查找之前是否讨论过某事、查询历史决策、查找模板或SOP、 为会议准备上下文、快速保存到收集箱、整理收集箱、知识健康检查、检测知识冲突或矛盾、 查找过期内容。 触发词：帮我记下来、搜一下我的笔记、更新知识库、整理文件、执行工作流、保存到知识库、 记录一下、整理笔记、复盘、提炼经验、同步文档、查一下之前的记录、有没有相关的笔记、 我之前写过什么、把这个存起来、总结一下保存、交接给其他Agent、追加到表格、 放到收集箱、整理收集箱、知识健康检查、检测知识冲突。 主动行为——不要等用户提到 MindOS： (1) 用户的问题暗示可能存在历史记录（过去的决策、之前的讨论、会议纪要）→ 先搜 MindOS， 即使没有明确提到知识库。 (2) 完成有价值的工作后（修了 bug、做了决策、总结了经验、选定了架构、开完了会）→ 主动提议保存到 MindOS，方便以后查阅。 (3) 经历了较长或多主题的对话后 → 建议把关键决策和上下文持久化。
MindOS: local knowledge assistant & shared KB. Keeps decisions, notes, SOPs, debugging lessons, research findings, preferences across sessions/agents. Core: save notes, search KB, organize files, run workflows, review, append CSV, hand off context, distill lessons. NOT for app source or paths outside KB. Triggers: save/record, search notes, update files, organize, run workflow, capture decisions, append CSV, hand off context, check past discussions, distill lessons. Proactive: (1) search first for stored context, (2) offer to save after valuable work, (3) suggest persisting key decisions.
基于 SOC 职业分类
正在显示 SKILL.md
| name | project-wiki |
| description | 组织和维护 Vibe Coding 项目的 wiki 文档体系。当用户要求初始化/重构 wiki 结构、进入新项目且 wiki/ 不存在、需要诊断和修复文档腐化、或需要管理 specs/refs/reviews 子目录的生命周期时触发。 |
为 Vibe Coding 项目（人类描述意图，Agent 写代码）生成和维护结构化 wiki。wiki 是 Agent 的输入物料，直接决定输出质量。
wiki/ 目录，列出已有文件assets/ 目录读取对应模板，填入用户上下文（不确定的部分留 <!-- TODO: ... --> 占位）01-project-roadmap.md，追加新阶段索引行<!-- Last verified: YYYY-MM-DD | Current stage: X -->CLAUDE.md（已有则合并差异，不替换整个文件）。这一步不能跳过——wiki 的日常同步依赖这些规则写入 CLAUDE.mdwiki/ 下所有文件和子目录，检查编号方案（紧凑 or 展开）、新鲜度标记ui-audit-*.md）→ 建议归入合适的子目录（reviews/）或运维区段（8x）specs/ 下混有 task-spec-* 和 spec-* → 不强制迁移，但新建一律用 spec-*；spec 散落在 wiki 根目录 → 建议迁入 specs/plugins/、images/ 等项目特有目录，标记为已知自定义目录，不报为异常CLAUDE.md 中已有 wiki 维护规则，缺失则追加（不替换整个文件）编号按**"战略 → 架构 → 规范 → 阶段 → 运维 → 日志"**分层。根据项目规模选择紧凑或展开方案：
紧凑方案（≤5 个 stage，适合多数项目）：
wiki/
├── 00-product-proposal.md
├── 01-project-roadmap.md
├── 02-system-architecture.md # 紧凑方案用 0x 统一放战略+架构
├── 03-design-principle.md
├── 04-api-reference.md
├── 1x 阶段 Stages
│ ├── 10-stage-a.md
│ ├── 11-stage-b.md ...
├── 80-known-pitfalls.md
├── 85-backlog.md
├── 90-changelog.md
├── specs/ · refs/ · reviews/ · archive/
展开方案（>5 个 stage 或需要更多分层空间）：
wiki/
├── 0x 战略 Strategy — 全局视角
│ ├── 00-product-proposal.md
│ ├── 01-project-roadmap.md
│ ├── 02-business-model.md
│ └── 03-technical-pillars.md
├── 2x 架构 Architecture — 系统是怎么建的
│ ├── 20-system-architecture.md
│ └── 21-design-principle.md
├── 3x 接口 API
│ └── 30-api-reference.md
├── 4x 规范 Conventions
│ ├── 40-conventions.md
│ └── 41-dev-pitfall-patterns.md
├── 6x 阶段 Stages — 各阶段详细 spec
│ ├── 60-stage-a.md ...
├── 8x 运维 Operations
│ ├── 80-known-pitfalls.md
│ ├── 81-postmortem-*.md
│ ├── 84-design-exploration.md
│ └── 85-backlog.md
├── 9x 日志 Log
│ └── 90-changelog.md
├── specs/ · refs/ · reviews/ · archive/
选择规则： 初始化时问用户，或根据已有文件自动识别。两种方案的文件内容和模板完全相同，只是编号前缀不同。关键是一个项目内保持一致，不混用。
项目特有子目录： wiki 可能出现 skill 未预设的子目录（如 plugins/、images/），这是正常的项目演化。扫描时将它们识别为"自定义目录"，不报为异常，不强制重命名。
| 全局（稳定，新阶段才改） | 阶段（增量更新） | |
|---|---|---|
| Why | product-proposal | — |
| What | project-roadmap — 功能索引 | stage-X — 设计决策 |
| How | system-architecture — 架构 + 类型 | stage-X — API、数据模型、受影响文件 |
| Look | design-principle — 视觉语言 | — |
关键规则： 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链接）、里程碑 |
| 20 | system-architecture.md | Agent | 技术栈、目录结构、数据流、核心类型、环境变量（300-500 行） |
| 编号 | 文件 | 何时需要 |
|---|---|---|
| 02 | business-model.md | 有商业化/变现需求时 |
| 03 | technical-pillars.md | 有明确的技术壁垒或研究方向时 |
| 21 | design-principle.md | 有自定义视觉语言时（非默认 UI 库样式） |
| 30 | api-reference.md | API 超过 5 条路由，或 stage 归档后仍需查 API 细节 |
| 40 | conventions.md | 有明确的编码偏好/约束（库选择、命名、错误处理模式等） |
| 41 | dev-pitfall-patterns.md | 踩坑积累到需要系统性记录时 |
| 6X | stage-X.md | 功能复杂度超过一句话能说清（150-300 行） |
| — | 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 设计探索、原型记录等创意过程产物时 |
| 85 | backlog.md | 有临时 bug、技术债、改进想法需要追踪时 |
| 90 | changelog.md | 发版时从 85-backlog.md 已完成条目整理写入，面向用户描述变更，不记内部实现细节 |
每个文件的详细说明和"为什么需要"的论证见
references/file-reference.md。
阶段完全交付且后续阶段不再引用其 API/数据模型时 → 移入 wiki/archive/，01-project-roadmap.md 中保留索引行并标注 [archived]。
归档判断标准： 同时满足以下两条才归档：① 该 stage 已完结超过一个阶段；② 当前及未来 stage 文件中无对它的跨引用。不确定时保留，宁可冗余不要断链。
四个子目录各有独立的命名规范、生命周期和归档规则。
活跃的功能 spec，是比 stage 文件更细粒度的任务描述。
| 项目 | 规则 |
|---|---|
| 命名 | spec-{feature-name}.md（推荐）。历史遗留的 task-spec-*.md 也可接受，不强制迁移 |
| 位置 | 放在 wiki/specs/ 下。发现散落在 wiki 根目录的 spec → 重构时提示迁入 specs/ |
| 创建时机 | 功能复杂度介于"backlog 一行"和"stage 文件一整章"之间 |
| 内容 | 背景、目标、边界、验收标准、受影响文件列表 |
| 归档 | 实现完成 → 移入 archive/specs/，backlog 对应项打勾 |
| 状态追踪 | 位置即状态：在 specs/ = 活跃，在 archive/specs/ = 完成。无需维护 Status 头标记 |
外部知识的内部镜像——第三方 API 行为、协议格式、技术选型调研等。
| 项目 | 规则 |
|---|---|
| 命名 | 描述性文件名即可（如 git-sync-workflow.md、npx-skills-mechanism.md）。ref- 前缀可选 |
| 创建时机 | 外部知识在 2+ 个文件/对话中被重复查阅 |
| 内容 | 机制说明、关键 API 摘要、与本项目的集成点、踩坑备注 |
| 归档 | 不主动归档；集成方案废弃时标记 `<!-- Deprecated: YYYY-MM-DD |
| 引用 | stage/spec 中通过 → 详见 [refs/xxx.md](./refs/xxx.md) 链接，不复制内容 |
代码审查、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/
├── 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 目录下的文件只做追加和查阅，不删除 |
wiki 文件按三层加载，避免 Agent 一次读入全部内容导致上下文浪费。
Agent 进入项目时只读两个文件，建立全局心智模型：
00-product-proposal.md → 知道"做什么、不做什么"
01-project-roadmap.md → 知道"当前在哪个阶段、有哪些功能"
roadmap 中每行功能附带链接，Agent 根据当前任务决定是否深入。
根据任务类型，Agent 按需加载对应的结构文件：
| 任务类型 | 加载文件 | 不加载 |
|---|---|---|
| 新功能开发 | system-architecture → 当前 stage → 相关 specs/ | 其他 stage、refs、reviews |
| 修 Bug | system-architecture → known-pitfalls → 相关 stage | 战略文件、无关 stage |
| UI 调整 | design-principle → system-architecture（目录部分） | stage 文件（除非涉及功能逻辑） |
| 技术调研 | refs/{topic} → system-architecture（集成点） | spec、review |
| 评审 | 对应 specs/ → 相关 refs/ → conventions | 不相关的 stage |
Agent 只在以下信号出现时才读取更深层文件：
→ 详见 refs/ref-xxx.md → 加载该 ref<!-- Reviewed: ... --> → 加载该 review 查看历史决策→ 复盘见 81-postmortem-xxx.md → 加载该 postmortem[archived → archive/specs/spec-xxx.md] → 需要溯源时加载关键原则： 不主动扫描子目录。索引文件（roadmap、backlog）中的链接是唯一的"入口导航"。
wiki 文件之间存在引用依赖。一个文件变更后，引用它的文件可能需要同步更新。这套规则帮助 Agent 追踪和维护这些关联。
文件间引用统一使用相对路径 + 锚点：
→ 详见 [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 |
Agent 修改 wiki 文件时，执行以下检查：
修改文件 X
→ grep -r "X" wiki/ # 找到所有引用 X 的文件
→ 逐一检查：引用的信息是否仍然准确
→ 不准确 → 更新引用方（或在引用旁加 <!-- May be outdated -->）
特别注意的高频联动：
每个阶段开始时（或触发重构流程时），Agent 执行一次完整性扫描：
grep -rn '\./[a-z].*\.md' wiki/ 检查所有相对路径引用目标是否存在<!-- Last verified: YYYY-MM-DD --> 标记，超过 30 天未验证的标记为 <!-- May be outdated -->refs/ 和 specs/ 下的文件如果没有被任何其他 wiki 文件引用 → 提示用户：是否需要归档或删除？wc -l wiki/*.md wiki/**/*.md → stage >300 行、其他 >500 行的文件列出，建议拆分.md 文件（如审计报告、临时笔记）→ 建议迁入合适子目录specs/ 中 task-spec-* 和 spec-* 混用 → 提示但不强制（新建一律用 spec-*）检测完成后，输出汇总表（检查项 × 严重程度 × 发现数）和优先建议（按严重程度排序，每条含具体操作步骤）。用户看完报告应清楚"先做哪个、怎么做"。
第一层（必读）：00-product-proposal → 01-project-roadmap（定位当前阶段）
第二层（按任务加载）：
| 场景 | 路径 |
|---|---|
| 新对话 / 新功能 | system-architecture → 当前 stage → 相关 specs/ |
| 修 Bug | system-architecture → known-pitfalls → 相关 stage |
| 修 Bug（反复出现） | postmortem-* → system-architecture → known-pitfalls → 相关 stage |
| UI 调整 | design-principle → system-architecture（目录结构）→ 相关组件 |
| 了解全貌 | product-proposal → project-roadmap → system-architecture |
| 技术调研 | 相关 refs/* → system-architecture（集成点部分） |
| 评审任务 | 对应 specs/* → conventions → 相关 refs/ |
第三层（按引用钻取）：文件中出现 → 详见 xxx 链接时才加载目标文件。不主动扫描子目录。
<!-- Last verified: YYYY-MM-DD | Current stage: X | May be outdated after Stage Y -->./XX-filename.md#锚点 格式，引用源码用 ../server/src/xxx.ts 格式。内容取舍——写什么、不写什么：
表达密度——同一信息用最少字数传达：
膨胀信号——出现以下情况说明写多了：
65-stage-knowledge-api 696 行 → 应拆分出独立的 API spec 或 ref）82-external-* 1057 行 → 应拆入 refs/）拆分策略： 膨胀文件中识别独立主题块 → 提取为 refs/ 或新 stage → 原位替换为一行引用链接。拆分后原文件应缩至建议行数内。
文档维护的投入信号和时机指南见
references/writing-guide.md。
Skill 触发时生成 wiki 结构，但 wiki 的日常同步发生在每次开发对话中。以下规则应在初始化完成后写入项目 CLAUDE.md，使 Agent 在正常开发流程中自动维护 wiki，无需反复触发本 skill。
写入 CLAUDE.md 的内容（根据项目实际存在的 wiki 文件裁剪，只保留已创建的文件对应的行）：
## Wiki 维护
开发过程中，以下操作需要同步更新对应 wiki 文件：
| 当你做了这件事 | 更新哪个文件 |
|--------------|------------|
| 新增/修改 API 路由 | `wiki/30-api-reference.md` 追加或修改对应条目 |
| 完成一个 stage 的功能 | `wiki/01-project-roadmap.md` 对应行状态改为 ✅ |
| 遇到非显而易见的坑 | `wiki/80-known-pitfalls.md` 追加一条（现象、原因、解法） |
| 多个 bug 互相关联、暴露系统性问题 | 新建 `wiki/81-postmortem-*.md`（单点问题用 pitfalls，系统性问题用 postmortem） |
| 架构变更（新模块、新数据流） | `wiki/20-system-architecture.md` 更新对应章节 |
| 阶段全部交付 | `wiki/90-changelog.md` 补一笔（从 backlog 已完成条目整理） |
| 发现 bug / 技术债 / 改进想法 | `wiki/85-backlog.md` 追加一条 |
| 新增设计 token / 动效 | `wiki/21-design-principle.md` 追加对应条目 |
| 出现新领域术语 | `wiki/05-glossary.md` 追加定义，防止 Agent 后续用词混乱 |
| 重命名 / 移动 wiki 文件 | 同步更新所有引用该文件的链接 |
**新建文件时机：**
- 新功能复杂度超过一句话说清 → 新建 `wiki/6X-stage-X.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` 日期
- 标出内容可能已过时的章节（加 `<!-- May be outdated -->` 注释）
不需要在每次 commit 时都更新——在功能完成、API 变更、架构调整这些"节点"时同步即可。
所有模板位于本 Skill 的 assets/ 目录。生成文件时读取对应模板，填入项目上下文。
| 模板文件 | 对应 wiki 文件 |
|---|---|
product-proposal.tmpl.md | 00-product-proposal.md |
project-roadmap.tmpl.md | 01-project-roadmap.md |
business-model.tmpl.md | 02-business-model.md |
technical-pillars.tmpl.md | 03-technical-pillars.md |
system-architecture.tmpl.md | 20-system-architecture.md |
design-principle.tmpl.md | 21-design-principle.md |
api-reference.tmpl.md | 30-api-reference.md |
conventions.tmpl.md | 40-conventions.md |
stage-x.tmpl.md | 6X-stage-X.md |
known-pitfalls.tmpl.md | 80-known-pitfalls.md |
postmortem.tmpl.md | 81-postmortem-*.md |
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 |