@geminilight/mindos 0.5.18 → 0.5.19

package/skills/project-wiki/SKILL.md

@@ -19,13 +19,18 @@ description: "组织和维护 Vibe Coding 项目的 wiki 文档体系。当用
 4. **生成骨架**：从本 Skill 的 `assets/` 目录读取对应模板，填入用户上下文（不确定的部分留 `<!-- TODO: ... -->` 占位）
 5. **更新导航**：如已有 `01-project-roadmap.md`，追加新阶段索引行
 6. **标记新鲜度**：每个生成的文件头部加 `<!-- Last verified: YYYY-MM-DD | Current stage: X -->`
-7. **注入维护规则**：检查项目 `CLAUDE.md` 中是否已有 wiki 维护规则。已有则跳过或合并差异；没有则**追加**（不替换整个文件）
+7. **注入维护规则**：将下方"日常维护规则"章节的内容追加到项目 `CLAUDE.md`（已有则合并差异，不替换整个文件）。这一步不能跳过——wiki 的日常同步依赖这些规则写入 CLAUDE.md
 
 ### 重构 / 更新（wiki/ 已有文件）
 
-1. **扫描** `wiki/` 下所有文件，检查编号前缀、新鲜度标记
-2. **诊断**：缺编号前缀？信息重叠？文件过大需拆分？已完结 stage 未归档？内容与代码不一致？
-3. **生成改动清单**（重命名 / 合并 / 拆分 / 归档 / 更新内容），与用户确认
+1. **扫描** `wiki/` 下所有文件和子目录，检查编号方案（紧凑 or 展开）、新鲜度标记
+2. **诊断**：
+   - 缺编号前缀？信息重叠？已完结 stage 未归档？内容与代码不一致？
+   - **膨胀检测**：stage 文件超 300 行、其他文件超 500 行 → 建议拆分
+   - **散落文件**：wiki 根目录中不属于任何编号区段的文件（如 `ui-audit-*.md`）→ 建议归入合适的子目录（`reviews/`）或运维区段（`8x`）
+   - **命名一致性**：`specs/` 下混有 `task-spec-*` 和 `spec-*` → 不强制迁移，但新建一律用 `spec-*`；spec 散落在 wiki 根目录 → 建议迁入 `specs/`
+   - **自定义子目录**：识别 `plugins/`、`images/` 等项目特有目录，标记为已知自定义目录，不报为异常
+3. **生成改动清单**（重命名 / 合并 / 拆分 / 归档 / 迁移 / 更新内容），与用户确认
 4. **执行改动**
 5. **验证一致性**：文件间引用链接有效、roadmap 索引与实际文件对应
 6. **检查维护规则**：确认项目 `CLAUDE.md` 中已有 wiki 维护规则，缺失则追加（不替换整个文件）
@@ -34,78 +39,69 @@ description: "组织和维护 Vibe Coding 项目的 wiki 文档体系。当用
 
 ## 文件体系
 
-### 编号体系：十位 = 层级，个位 = 序号
+### 编号体系
 
-编号按**"战略 → 架构 → 规范 → 阶段 → 运维 → 日志"**分层，均匀分布，奇数十位留空备用。
+编号按**"战略 → 架构 → 规范 → 阶段 → 运维 → 日志"**分层。根据项目规模选择紧凑或展开方案：
+
+**紧凑方案**（≤5 个 stage，适合多数项目）：
 
 ```
 wiki/
-├── 0x  战略 Strategy       — 全局视角，不看代码也能读懂
+├── 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   — 系统是怎么建的（描述事实）
+│   ├── 02-business-model.md
+│   └── 03-technical-pillars.md
+├── 2x  架构 Architecture   — 系统是怎么建的
 │   ├── 20-system-architecture.md
-│   └── 21-design-principle.md        # 有自定义视觉语言时
-│
-├── 3x  （空，留给接口/API 文档）
-│
-├── 4x  规范 Conventions    — 怎么参与开发（约束行为）
+│   └── 21-design-principle.md
+├── 3x  接口 API
+│   └── 30-api-reference.md
+├── 4x  规范 Conventions
 │   ├── 40-conventions.md
-│   └── 41-dev-pitfall-patterns.md    # 踩坑经验
-│
-├── 5x  （空）
-│
-├── 6x  阶段 Stages         — 各阶段详细 spec（按需查阅）
-│   ├── 60-stage-a.md
-│   ├── 61-stage-b.md
-│   └── ...
-│
-├── 7x  （空）
-│
-├── 8x  运维 Operations     — 坑、复盘、backlog
+│   └── 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      # 有 UI 探索时
+│   ├── 84-design-exploration.md
 │   └── 85-backlog.md
-│
 ├── 9x  日志 Log
 │   └── 90-changelog.md
-│
-├── specs/                   — 任务 spec（活跃的，完成后归档）
-│   └── spec-{feature-name}.md
-├── refs/                    — 参考资料（外部机制说明、技术调研）
-│   └── ref-{topic}.md
-├── reviews/                 — 代码/设计/spec 评审记录
-│   └── review-{date}-{subject}.md
-└── archive/                 — 已完结的文档（保留溯源，不污染活跃目录）
-    ├── specs/               — 已完成的 spec
-    ├── reviews/             — 历史评审
-    └── stages/              — 已归档的 stage 文件
+├── specs/ · refs/ · reviews/ · archive/
 ```
 
-| 区段 | 用途 | 扩展性 |
-|------|------|--------|
-| `0x` | 战略：产品方向、路线图、商业、壁垒 | 最多 10 个全局文档 |
-| `2x` | 架构：系统设计 + 设计系统 | 可加 22-data-model 等 |
-| `3x` | 留空 | 未来放 API reference、协议文档 |
-| `4x` | 规范：开发流程 + 踩坑经验 | 可加 42-testing-standards 等 |
-| `5x` | 留空 | 未来按需定义 |
-| `6x` | 阶段：各功能的详细 spec | 最多 10 个阶段 |
-| `7x` | 留空 | 未来按需定义 |
-| `8x` | 运维：已知坑、复盘、backlog | 可加 82-xxx、83-xxx |
-| `9x` | 日志 | changelog、release notes |
+**选择规则：** 初始化时问用户，或根据已有文件自动识别。两种方案的文件内容和模板完全相同，只是编号前缀不同。关键是**一个项目内保持一致**，不混用。
+
+**项目特有子目录：** wiki 可能出现 skill 未预设的子目录（如 `plugins/`、`images/`），这是正常的项目演化。扫描时将它们识别为"自定义目录"，不报为异常，不强制重命名。
 
 ### 核心模型：Why / What / How / Look × 全局 / 阶段
 
 | | 全局（稳定，新阶段才改） | 阶段（增量更新） |
 |---|---|---|
-| **Why** | `00-product-proposal.md` | — |
-| **What** | `01-project-roadmap.md` — 功能索引 | `6X-stage-X.md` — 设计决策 |
-| **How** | `20-system-architecture.md` — 架构 + 类型 | `6X-stage-X.md` — API、数据模型、受影响文件 |
-| **Look** | `21-design-principle.md` — 视觉语言 | — |
+| **Why** | `product-proposal` | — |
+| **What** | `project-roadmap` — 功能索引 | `stage-X` — 设计决策 |
+| **How** | `system-architecture` — 架构 + 类型 | `stage-X` — API、数据模型、受影响文件 |
+| **Look** | `design-principle` — 视觉语言 | — |
 
 **关键规则：** stage 文件同时包含 What 和 How。一个功能的设计决策、API 契约、数据模型放在一个文件里。全局文件只做索引和导航，不重复 stage 的细节。
 
@@ -165,11 +161,12 @@ wiki/
 
 | 项目 | 规则 |
 |------|------|
-| 命名 | `spec-{feature-name}.md`（用 kebab-case，名称反映功能而非编号） |
+| 命名 | `spec-{feature-name}.md`（推荐）。历史遗留的 `task-spec-*.md` 也可接受，不强制迁移 |
+| 位置 | 放在 `wiki/specs/` 下。发现散落在 wiki 根目录的 spec → 重构时提示迁入 `specs/` |
 | 创建时机 | 功能复杂度介于"backlog 一行"和"stage 文件一整章"之间 |
 | 内容 | 背景、目标、边界、验收标准、受影响文件列表 |
-| 归档 | 实现完成且 review 通过 → 移入 `archive/specs/`，backlog 对应项打勾 |
-| 头部标记 | `<!-- Status: draft | in-review | approved | done | archived -->` |
+| 归档 | 实现完成 → 移入 `archive/specs/`，backlog 对应项打勾 |
+| 状态追踪 | **位置即状态**：在 `specs/` = 活跃，在 `archive/specs/` = 完成。无需维护 Status 头标记 |
 
 #### refs/ — 参考资料
 
@@ -177,11 +174,11 @@ wiki/
 
 | 项目 | 规则 |
 |------|------|
-| 命名 | `ref-{topic}.md`（如 `ref-stripe-webhook.md`、`ref-webrtc-signaling.md`） |
+| 命名 | 描述性文件名即可（如 `git-sync-workflow.md`、`npx-skills-mechanism.md`）。`ref-` 前缀可选 |
 | 创建时机 | 外部知识在 2+ 个文件/对话中被重复查阅 |
 | 内容 | 机制说明、关键 API 摘要、与本项目的集成点、踩坑备注 |
 | 归档 | 不主动归档；集成方案废弃时标记 `<!-- Deprecated: YYYY-MM-DD | Reason -->` |
-| 引用 | stage/spec 文件中通过 `→ 详见 [refs/ref-xxx.md](./refs/ref-xxx.md)` 链接，不复制内容 |
+| 引用 | stage/spec 中通过 `→ 详见 [refs/xxx.md](./refs/xxx.md)` 链接，不复制内容 |
 
 #### reviews/ — 评审记录
 
@@ -236,11 +233,11 @@ roadmap 中每行功能附带链接，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 |
+| 新功能开发 | `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 |
 
 #### 第三层：细节（按需钻取）
 
@@ -299,10 +296,15 @@ Agent 修改 wiki 文件时，执行以下检查：
 
 每个阶段开始时（或触发重构流程时），Agent 执行一次完整性扫描：
 
-1. **断链检测**：`grep -rn '\./[a-z].*\.md' wiki/ | while read line; do ...` 检查所有 `./xxx.md` 引用目标是否存在
+1. **断链检测**：`grep -rn '\./[a-z].*\.md' wiki/` 检查所有相对路径引用目标是否存在
 2. **新鲜度检查**：扫描所有 `<!-- Last verified: YYYY-MM-DD -->` 标记，超过 30 天未验证的标记为 `<!-- May be outdated -->`
 3. **孤立文件检测**：`refs/` 和 `specs/` 下的文件如果没有被任何其他 wiki 文件引用 → 提示用户：是否需要归档或删除？
 4. **重复信息检测**：同一概念在两个文件中都有段落级展开 → 提示合并，保留一个权威源，另一个改为引用链接
+5. **膨胀检测**：`wc -l wiki/*.md wiki/**/*.md` → stage >300 行、其他 >500 行的文件列出，建议拆分
+6. **散落文件**：wiki 根目录中不匹配编号体系的 `.md` 文件（如审计报告、临时笔记）→ 建议迁入合适子目录
+7. **命名迁移**：`specs/` 中 `task-spec-*` 和 `spec-*` 混用 → 提示但不强制（新建一律用 `spec-*`）
+
+检测完成后，输出**汇总表**（检查项 × 严重程度 × 发现数）和**优先建议**（按严重程度排序，每条含具体操作步骤）。用户看完报告应清楚"先做哪个、怎么做"。
 
 ---
 
@@ -314,13 +316,13 @@ Agent 修改 wiki 文件时，执行以下检查：
 
 | 场景 | 路径 |
 |------|------|
-| 新对话 / 新功能 | `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/` |
+| 新对话 / 新功能 | `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` 链接时才加载目标文件。不主动扫描子目录。
 
@@ -348,10 +350,14 @@ Agent 修改 wiki 文件时，执行以下检查：
 - 每句话删到"再删就丢信息"为止
 
 **膨胀信号——出现以下情况说明写多了：**
+- Stage 文件超过 300 行（如 `65-stage-knowledge-api` 696 行 → 应拆分出独立的 API spec 或 ref）
+- 非 stage 文件超过 500 行（如 `82-external-*` 1057 行 → 应拆入 `refs/`）
 - 一个 section 超过 20 行却没有代码块或表格
 - 同一个概念在两个文件中都有段落级展开
 - 读完一段话后能概括成一行表格而不丢失关键信息
 
+**拆分策略：** 膨胀文件中识别独立主题块 → 提取为 `refs/` 或新 stage → 原位替换为一行引用链接。拆分后原文件应缩至建议行数内。
+
 > 文档维护的投入信号和时机指南见 `references/writing-guide.md`。
 
 ---

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

@@ -261,11 +261,13 @@
 
 **为什么需要：** Stage 文件覆盖一个阶段的全部功能，粒度偏大。当一个小功能/改进点需要明确的边界和验收标准，但又不值得开一个完整的 stage 时，spec 是最合适的载体。它也是 review 的评审对象——没有 spec，评审就没有锚点。
 
+**命名兼容：** 推荐 `spec-{name}.md`，历史遗留的 `task-spec-*.md` 也可接受。新建一律用 `spec-*`。
+
 **写给谁看：** Agent + 评审者
 
 **核心内容：** 背景、目标、边界、设计方案（数据模型 + API + 受影响文件）、验收标准
 
-**生命周期：** draft → in-review → approved → done → archived。完成后移入 `archive/specs/`。
+**生命周期：** 在 `specs/` = 活跃，在 `archive/specs/` = 完成。位置即状态，无需维护额外标记。
 
 **与 stage 文件的关系：** Spec 是 stage 内某个功能点的展开。Stage 文件用一行索引指向 spec，不重复 spec 的内容。
 
@@ -273,10 +275,12 @@
 
 ---
 
-### refs/ref-{topic}.md — 参考资料
+### refs/{topic}.md — 参考资料
 
 **为什么需要：** Agent 没有外部系统的内部知识。Stripe webhook 的重试机制、WebRTC 的 signaling 流程、某个私有 API 的字段含义——这些信息每次新对话都要重新查阅。写一次 ref，后续所有 stage/spec 直接引用，不重复调研。
 
+**命名：** 描述性文件名即可（如 `git-sync-workflow.md`、`npx-skills-mechanism.md`）。`ref-` 前缀可选。
+
 **写给谁看：** Agent
 
 **核心内容：** 机制说明、关键 API 摘要、与本项目的集成点、踩坑备注、来源链接和版本