@geminilight/mindos 0.5.18 → 0.5.20

package/skills/mindos/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mindos
 description: >
-  MindOS knowledge base operation guide, only for agent tasks on files inside the MindOS knowledge base (mindRoot path).
+  MindOS knowledge base operation guide, only for agent tasks on files inside the MindOS knowledge base.
   Trigger only when the target files are inside the MindOS knowledge base directory.
   Typical requests: "update notes", "search knowledge base", "organize files", "execute SOP",
   "review with our standards", "handoff to another agent", "sync decisions", "append CSV",
@@ -12,173 +12,15 @@ description: >
   or the task involves modifying project source code or project documentation.
 ---
 
-# MindOS Knowledge Base Operation Guide
+# MindOS Skill
 
-Use this skill to operate safely and consistently in a MindOS-style local knowledge base.
+Load operating rules from the knowledge base, then execute the user's task.
 
-## Core Principles
+## Protocol
 
-- Treat repository state as source of truth.
-- **The directory tree loaded at bootstrap is a first-class semantic asset.** Directory names, file names, and their hierarchy encode what the user has stored and how they organize their thinking. Always reason from this structure before resorting to search — it often tells you where content lives without any tool call.
-- Read before write.
-- Prefer minimal, precise edits.
-- Keep changes auditable and easy to review.
-
-## Startup Protocol
-
-Run this sequence before substantive edits:
-
-1. Load root guidance.
-- Prefer `mindos_bootstrap`.
-- If unavailable, read root `INSTRUCTION.md` and root `README.md` directly.
-
-2. Discover current structure dynamically.
-- Use `mindos_list_files` and targeted `mindos_search_notes`.
-- Do not assume fixed top-level directory names.
-
-3. Load local guidance around target paths.
-- Read nearby `README.md` / `INSTRUCTION.md` when present.
-- Follow local conventions over global assumptions.
-
-4. Execute edits.
-
-If required context is missing, continue with best effort and state assumptions explicitly.
-
-## Dynamic Structure Rules
-
-- Do not hardcode a canonical directory tree.
-- Infer conventions from neighboring files before creating or rewriting content.
-- Mirror existing local patterns for naming, heading structure, CSV schema, and references.
-- For new files, follow sibling style rather than inventing a new standard.
-- **Never create files or directories in the root directory unless the user explicitly requests it.** The root is reserved for top-level governance files (README, INSTRUCTION, CONFIG). New content should be placed under the most semantically appropriate existing subdirectory. Reason from the directory tree in context to find the right home.
-- When creating a new file or directory, always determine the best parent directory first by reviewing the existing structure. If no existing directory is a clear fit, propose 1-2 candidate locations and ask the user before creating.
-- **After any file create/delete/move/rename, always sync affected README files.** READMEs serve as directory indexes and navigation entry points. Any operation that changes a directory's contents (creating, deleting, moving, or renaming files or subdirectories) must trigger an automatic check and update of the README in that directory and its parent directory, so they accurately reflect the current structure. This requires no user prompting — it is basic structural consistency discipline.
-
-## Pre-Write Checklist
-
-Before any non-trivial write, confirm all checks:
-
-1. Target file/path is confirmed and exists or should be created.
-2. **Target location is under an appropriate subdirectory, not the root.** If unsure which directory fits best, propose candidates and ask the user.
-3. Current content has been read, or absence is explicitly confirmed.
-4. Local governance docs near the target path are considered.
-5. Edit scope is minimal and aligned with user intent.
-6. Reference/backlink impact is evaluated for path changes.
-
-## Tool Selection Guide
-
-### Discovery
-
-- `mindos_bootstrap`: Load startup context.
-- `mindos_list_files`: Inspect file tree.
-- `mindos_search_notes`: Locate relevant files by keyword/scope/type/date. **When searching, always issue multiple parallel searches with different keywords upfront** — synonyms, abbreviations, English/Chinese variants, and broader/narrower terms. A single keyword is fragile; casting a wider net on the first try avoids wasted rounds.
-- `mindos_get_recent`: Inspect latest activity.
-- `mindos_get_backlinks`: Assess impact before rename/move/delete.
-
-### Read and write
-
-- `mindos_read_file`: Read file content.
-- `mindos_write_file`: Use only for true full replacement.
-- `mindos_create_file`: Create `.md`/`.csv` files.
-- `mindos_delete_file`: Delete only with explicit user intent.
-- `mindos_rename_file`, `mindos_move_file`: Structural edits with follow-up reference checks.
-
-### Precise editing
-
-- `mindos_read_lines`: Locate exact lines.
-- `mindos_insert_lines`: Insert at index.
-- `mindos_update_lines`: Replace specific range.
-- `mindos_append_to_file`: Append to end.
-- `mindos_insert_after_heading`: Insert under heading.
-- `mindos_update_section`: Replace one markdown section.
-
-### History and tables
-
-- `mindos_get_history`, `mindos_get_file_at_version`: Investigate/recover history.
-- `mindos_append_csv`: Append validated row after header check.
-
-## Fallback Rules
-
-- If some `mindos_*` tools are unavailable, use equivalent available tools while preserving the same safety discipline.
-- If `mindos_bootstrap` is unavailable, do manual startup reads.
-- If line/section edit tools are unavailable, emulate minimal edits through read plus constrained rewrite.
-- If `mindos_search_notes` returns no results, do not give up. The directory tree loaded at bootstrap is already in your context — directory names, file names, and their hierarchy are semantically rich and often enough to infer where content lives. Escalate progressively:
-  1. Review the directory structure already in context. Reason about which directories and files are likely relevant based on naming, hierarchy, and topic proximity.
-  2. Read the most promising candidate files directly to confirm relevance.
-  3. If candidates are unclear, use `mindos_list_files` on a specific subdirectory for finer-grained structure not captured at bootstrap.
-  4. Try alternative search terms (synonyms, broader/narrower keywords, English/Chinese variants) as a parallel strategy.
-
-## Execution Patterns
-
-Select the matching pattern below. All patterns share a common discipline: search → read → minimal edit → verify → summarize.
-
-### Core patterns (high-frequency)
-
-#### Capture or update notes
-Search → read target + local rules → apply minimal edit → keep references consistent.
-
-#### Context-aware question answering
-Reason from directory tree → read relevant files → answer grounded in stored content with file citations → if info is missing, say so explicitly.
-
-#### Structure-aware multi-file routing
-For unstructured inputs (meeting notes, braindumps, chat exports) that belong in multiple places:
-1. Parse input into semantic units (facts, decisions, action items, ideas).
-2. For each unit, search + read candidate destination files.
-3. **Present routing plan to user for approval** (table: what → which file → where).
-4. Apply minimal edits. Create new files only when no existing file fits.
-5. Summarize all changes for audit.
-
-#### Conversation retrospective
-1. Confirm scope with user.
-2. Extract reusable artifacts: decisions, rationale, pitfalls, next actions.
-3. Route each to the best existing file (or create near related docs).
-4. Add trace note of what changed and why. Ask user when routing confidence is low.
-
-### Structural change patterns (always apply after file create/delete/move/rename)
-
-- **Rename/move**: `get_backlinks` → report impact → confirm → execute → update all references → verify no orphans.
-- **Auto-sync READMEs**: After any structural change, update README in affected directories + parent directories to reflect current contents. This is automatic — no separate user request needed.
-
-### Reference patterns (use when task matches)
-
-| Pattern | Key steps |
-|---------|-----------|
-| CSV operations | Read header → validate fields → append row |
-| TODO/task management | Locate list → read format → minimal edit preserving conventions |
-| SOP/workflow execution | Read doc fully → execute stepwise → update only affected section |
-| Cross-agent handoff | Read task state + decisions → continue without re-discovery → write back progress |
-| Knowledge conflict resolution | Multi-term search for old info → list all affected files → present change plan → update after approval |
-| Distill experience into SOP | Extract procedure → generalize → create under Workflows/ with prerequisites, steps, pitfalls |
-| Periodic review/summary | `get_recent`/`get_history` → read changed files → categorize → structured summary |
-| Handoff document synthesis | Identify sources → read → synthesize (background, decisions, status, open items) → place in project dir |
-| Relationship management | Extract updates from notes → update contact records → generate next-step strategy |
-| Information collection | Locate sources → read outreach docs → personalize per target → write back outcomes |
-| Project bootstrap | Read preference/stack docs → scaffold aligned with standards → record decisions |
-| Code review | Read review standards → check naming/security/performance → output actionable findings |
-| Distill cross-agent discussion | Confirm decisions with user → structure as problem/decision/rationale/next-actions → minimal write-back |
-
-## Interaction Rules
-
-- **When a request is ambiguous or too broad (e.g., "help me organize things"), always ask for clarification before acting.** Propose specific options based on what you see in the knowledge base (recent changes, directory structure), but do not start reorganizing or rewriting without understanding the user's intent and scope.
-- When presenting search results or options, prioritize brevity and relevance. Show the most likely match first.
-- When answering questions from stored knowledge, always cite the source file path so the user can verify.
-
-## Safety Rules
-
-- By default, treat root `INSTRUCTION.md`, root `README.md`, and any directory-level `INSTRUCTION.md` governance docs as high-sensitivity; ask for confirmation before modifying them.
-- Ask before editing high-sensitivity governance files.
-- Ask before high-impact actions.
-- High-impact actions include bulk deletion, large-scale rename/move, broad directory restructuring, and cross-file mass rewrites.
-- **When an operation will touch multiple files, always present the full change plan to the user first.** List each target file, what will change, and why. Wait for approval before executing. This is non-negotiable — users must be able to see and control multi-file updates before they happen.
-- Never store secrets, tokens, or passwords.
-- Never delete or rewrite outside user intent.
-
-## Quality Gates
-
-Before finishing any operation, verify:
-
-1. Result directly answers user intent.
-2. Updated content matches local style and structure.
-3. References/links remain valid after structural edits.
-4. No sensitive information was introduced.
-5. Summary to user is specific enough for quick audit.
+1. Read `.agents/skills/mindos/skill-rules.md` — operating rules.
+   - If not found: fall back to `mindos_bootstrap` (or read root INSTRUCTION.md
+     + README.md). Inform user: "Run `mindos init-skills` for full skill rules."
+2. If `.agents/skills/mindos/user-rules.md` exists and is non-empty:
+   read it. User rules override default rules on conflict.
+3. Execute task following loaded rules. After completion, evaluate proactive hooks.

package/skills/mindos-zh/SKILL.md

@@ -1,182 +1,24 @@
 ---
 name: mindos-zh
 description: >
-  MindOS 知识库中文操作指南，仅用于 MindOS 知识库（mindRoot 路径）内的 Agent 任务。
-  仅当操作目标是 MindOS 知识库目录下的文件时触发，典型请求包括”更新笔记””搜索知识库”
-  “整理文件””执行 SOP””按团队标准 review””把任务交接给另一个 Agent””同步决策”
-  “追加 CSV””复盘这段对话””提炼关键经验””把复盘结果自适应更新到对应文档”
-  “把这些信息路由到对应文件””同步更新所有相关文档”等。
+  MindOS 知识库中文操作指南，仅用于 MindOS 知识库内的 Agent 任务。
+  仅当操作目标是 MindOS 知识库目录下的文件时触发，典型请求包括"更新笔记""搜索知识库"
+  "整理文件""执行 SOP""按团队标准 review""把任务交接给另一个 Agent""同步决策"
+  "追加 CSV""复盘这段对话""提炼关键经验""把复盘结果自适应更新到对应文档"
+  "把这些信息路由到对应文件""同步更新所有相关文档"等。
   不触发：操作目标是本地代码仓库文件（如 /code/xxx/wiki/*.md）、
   用户给出的是绝对路径且不在 MindOS mindRoot 下、或任务是修改项目源码/文档。
 ---
 
-# MindOS 知识库操作指南
+# MindOS Skill
 
-用于在 MindOS 风格的本地知识库中进行安全、一致、可审计的操作。
+从知识库加载操作规则，然后执行用户任务。
 
-## 核心原则
+## 协议
 
-- 以仓库当前状态为唯一依据。
-- **bootstrap 加载的目录树是一等语义资产。** 目录名、文件名及其层级结构编码了用户存了什么、如何组织思维。在调用搜索之前，先从这个结构推断内容位置——它往往不需要任何工具调用就能告诉你答案。
-- 写入前先读取。
-- 优先最小化、精确化修改。
-- 变更结果应易于审阅与追踪。
-
-## 启动协议
-
-在进行实质编辑前执行以下流程：
-
-1. 加载根级规则。
-- 优先调用 `mindos_bootstrap`。
-- 若不可用，直接读取根 `INSTRUCTION.md` 与根 `README.md`。
-
-2. 动态发现当前结构。
-- 使用 `mindos_list_files` 与按需 `mindos_search_notes`。
-- 不假设固定一级目录名。
-
-3. 加载目标路径附近的局部规则。
-- 若存在，读取就近 `README.md` / `INSTRUCTION.md`。
-- 优先遵循局部约定，而非全局假设。
-
-4. 再执行编辑。
-
-若关键上下文缺失，按最佳努力继续，并明确写出假设。
-
-## 动态结构规则
-
-- 不硬编码”标准目录树”。
-- 创建或重写内容前，先从相邻文件推断约定。
-- 命名、标题结构、CSV 字段顺序、引用格式均优先复用现有模式。
-- 新建文件优先跟随同级风格，不引入新标准。
-- **除非用户明确要求，不在根目录下创建文件或子目录。** 根目录仅保留顶层治理文件（README、INSTRUCTION、CONFIG）。新内容应放在语义最匹配的现有子目录下，从上下文中的目录树推断合适位置。
-- 创建新文件或目录时，先根据现有结构确定最佳父目录。若没有明显匹配的目录，提出 1-2 个候选位置并询问用户后再创建。
-- **文件增删/移动/重命名后，必须同步更新受影响的 README 文件。** README 是目录的索引与导航入口，任何改变目录内容的操作（创建、删除、移动、重命名文件或子目录）都应自动检查并更新对应目录及其父目录的 README，使其准确反映当前结构。这不需要用户提醒——属于结构一致性的基本纪律。
-
-## 写前检查清单
-
-在任何非 trivial 写入前，确认以下检查项：
-
-1. 目标文件或路径已确认，且存在或应当创建。
-2. **目标位置在合适的子目录下，而非根目录。** 若不确定哪个目录最合适，先提出候选并询问用户。
-3. 现有内容已读取，或已明确确认不存在。
-4. 已考虑目标路径附近的治理文档。
-5. 修改范围最小化，且与用户意图一致。
-6. 路径变更带来的引用/反链影响已评估。
-
-## 工具选型指南
-
-### 发现
-
-- `mindos_bootstrap`：加载启动上下文。
-- `mindos_list_files`：查看文件树。
-- `mindos_search_notes`：按关键词/范围/类型/日期定位文件。**搜索时，第一次就应并行发起多个关键词搜索**——同义词、缩写、中英文变体、更宽/更窄的表述。单一关键词很脆弱，一开始就撒网能避免多轮空搜。
-- `mindos_get_recent`：查看近期活动。
-- `mindos_get_backlinks`：重命名/移动/删除前评估影响。
-
-### 读写
-
-- `mindos_read_file`：读取文件内容。
-- `mindos_write_file`：仅在确需整文件替换时使用。
-- `mindos_create_file`：创建 `.md`/`.csv` 文件。
-- `mindos_delete_file`：仅在用户明确意图下删除。
-- `mindos_rename_file`、`mindos_move_file`：结构变更后补做引用检查。
-
-### 精确编辑
-
-- `mindos_read_lines`：定位精确行。
-- `mindos_insert_lines`：按索引插入。
-- `mindos_update_lines`：替换指定行区间。
-- `mindos_append_to_file`：文件末尾追加。
-- `mindos_insert_after_heading`：标题后插入。
-- `mindos_update_section`：替换单个 Markdown 章节。
-
-### 历史与表格
-
-- `mindos_get_history`、`mindos_get_file_at_version`：追踪/回溯历史。
-- `mindos_append_csv`：读表头校验后追加单行。
-
-## 回退规则
-
-- 若部分 `mindos_*` 工具不可用，使用可用等效工具，但保持同样安全纪律。
-- 若 `mindos_bootstrap` 不可用，改为手动读取启动文件。
-- 若缺少行级/章节级工具，用”读取 + 受限重写”方式模拟最小化修改。
-- 若 `mindos_search_notes` 无结果，不要放弃。bootstrap 时加载的目录树已经在你的上下文中——目录名、文件名及其层级结构本身就有丰富的语义，往往足以推断内容可能在哪里。逐步升级：
-  1. 先回顾上下文中已有的目录结构，根据命名、层级与主题相关性推断哪些目录和文件最可能相关。
-  2. 直接读取最可能的候选文件确认内容。
-  3. 若候选不明确，对特定子目录调用 `mindos_list_files` 获取 bootstrap 未覆盖的更细粒度结构。
-  4. 同时尝试替代关键词（同义词、更宽/更窄范围、中英文变体）作为并行策略。
-
-## 执行模式
-
-选择匹配的模式。所有模式共享统一纪律：搜索 → 读取 → 最小化编辑 → 验证 → 总结。
-
-### 核心模式（高频）
-
-#### 记录或更新笔记
-搜索 → 读取目标 + 局部规则 → 最小化修改 → 路径变化时保持引用一致。
-
-#### 基于上下文的问答
-从目录树推断 → 读取相关文件 → 基于存储内容回答并注明来源 → 信息缺失时明确告知。
-
-#### 结构感知的多文件联动更新
-处理非结构化输入（会议纪要、braindump、聊天记录）分属多文件的场景：
-1. 将输入解析为语义单元（事实、决策、行动项、想法等）。
-2. 为每个单元搜索 + 读取候选目标文件。
-3. **写入前向用户展示路由计划（表格：信息 → 目标文件 → 写入位置）并请求确认。**
-4. 执行最小化编辑。仅当无匹配文件时才新建。
-5. 汇总所有变更供审计。
-
-#### 对话复盘与自适应更新
-1. 先让用户确认复盘范围。
-2. 抽取可复用资产：决策、理由、踩坑、下一步动作。
-3. 路由到最合适的现有文件（或在相邻位置新建）。
-4. 补变更说明。路由置信度低时先问用户。
-
-### 结构变更模式（文件增删/移动/重命名后必须执行）
-
-- **重命名/移动**：`get_backlinks` → 报告影响 → 确认 → 执行 → 更新所有引用 → 验证无孤链。
-- **同步 README**：任何结构变更后，自动更新受影响目录及父目录的 README。无需用户单独请求。
-
-### 参考模式（任务匹配时使用）
-
-| 模式 | 关键步骤 |
-|------|----------|
-| CSV 操作 | 读表头 → 校验字段 → 追加行 |
-| TODO/任务管理 | 定位列表 → 读取格式 → 最小化编辑保持约定 |
-| SOP/工作流执行 | 完整读取 → 分步执行 → 仅更新过时章节 |
-| 跨 Agent 接力 | 读任务状态+决策 → 无需重复探索直接接续 → 回写进度 |
-| 知识冲突联动 | 多关键词搜索旧信息 → 列出受影响文件 → 展示变更计划 → 确认后更新 |
-| 经验提炼 SOP | 提取步骤 → 泛化 → 在 Workflows/ 下创建含前置条件、步骤、踩坑的 SOP |
-| 周期性回顾 | `get_recent`/`get_history` → 读变动文件 → 分类 → 结构化总结 |
-| 交接文档合成 | 识别来源 → 读取 → 合成（背景、决策、状态、待办）→ 放项目目录 |
-| 关系维护与跟进 | 从纪要提取更新 → 更新联系人记录 → 生成跟进策略 |
-| 信息收集与外联 | 定位来源 → 读外联文档 → 按画像个性化 → 回写结果 |
-| 项目启动 | 读偏好/技术栈 → 脚手架对齐标准 → 记录决策 |
-| 代码审查 | 读审查规范 → 检查命名/安全/性能 → 输出可执行建议 |
-| 沉淀跨 Agent 讨论 | 与用户确认决策 → 结构化为问题/决策/理由/下一步 → 最小化写回 |
-
-## 交互规则
-
-- **当请求模糊或范围过大时（如"帮我整理一下"），先问清楚再动手。** 基于知识库现状（近期变动、目录结构）提出具体选项，但不要在理解用户意图和范围之前就开始重组或重写。
-- 展示搜索结果或选项时，优先简洁和相关性，最可能的匹配排前面。
-- 从存储内容回答问题时，始终注明来源文件路径，便于用户验证。
-
-## 安全规则
-
-- 默认将根级 `INSTRUCTION.md`、根级 `README.md` 和其他目录下的 `INSTRUCTION.md` 治理文档视为高敏感，先确认再改。
-- 修改高敏感治理文件前先确认。
-- 执行高影响动作前先确认。
-- 高影响动作包括批量删除、大规模重命名/移动、目录大重构、跨文件批量重写。
-- **当操作涉及多个文件时，必须先向用户展示完整的变更计划。** 列出每个目标文件、将做什么修改、为什么。等用户确认后再执行。多文件更新在执行前必须可见、可控。
-- 不写入密钥、Token、密码。
-- 不执行超出用户意图的删除或覆写。
-
-## 质量闸门
-
-在结束任何操作前确认：
-
-1. 结果直接回应用户意图。
-2. 新增或修改内容符合局部风格与结构。
-3. 结构调整后引用/链接仍有效。
-4. 未引入敏感信息。
-5. 给用户的总结足够具体，便于快速审计。
+1. 读取 `.agents/skills/mindos-zh/skill-rules.md` — 操作规则。
+   - 若文件不存在：退化到 `mindos_bootstrap`（或手动读取根 INSTRUCTION.md
+     + README.md）。提示用户："运行 `mindos init-skills` 启用完整 skill 规则。"
+2. 若 `.agents/skills/mindos-zh/user-rules.md` 存在且非空：
+   读取。用户规则在冲突时覆盖默认规则。
+3. 按加载的规则执行任务。完成后评估任务后 hooks。

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`。
 
 ---