docs: wiki重构设计spec+实施计划 — 移至 docs/wiki-restructure/

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-22 21:26:51 +08:00
parent de7d88afcc
commit 73139da57a
2 changed files with 827 additions and 0 deletions
--- a/docs/wiki-restructure/design-spec.md
+++ b/docs/wiki-restructure/design-spec.md
@@ -0,0 +1,335 @@
+# Wiki Restructure Design
+
+> Date: 2026-04-22
+> Status: Approved
+> Author: Claude + User brainstorming session
+
+## 1. Problem Statement
+
+Current wiki (16 files, ~155KB) has three structural problems:
+
+1. **No task-oriented navigation** — Cannot go from symptom to module quickly
+2. **Duplicate content** — Middleware/security/evolution described in 3+ pages
+3. **Missing integration contracts** — Cross-module boundaries undocumented
+4. **Growing append-only sections** — log.md already 31KB, known-issues.md 13KB
+
+The wiki's primary reader is a Claude AI session that reads it at conversation start to orient itself. Secondary reader is the human developer.
+
+## 2. Design Principles
+
+1. **Wiki documents what code cannot tell you** — WHY decisions, navigation shortcuts, traps, invariants
+2. **Code logic sections focus on flows + invariants + algorithms** — NOT field lists or function signatures
+3. **Page size budget** — index ≤ 120 lines, module pages 100-200 lines (3-6KB)
+4. **Single source of truth per topic** — No content duplicated across pages; use references
+5. **Append-only sections are capped** — log.md capped at 50 entries, old entries archived
+
+## 3. Structure
+
+### 3.1 Level 1: `index.md` — Navigation + Symptom Index
+
+```
+wiki/index.md
+├── Project one-liner
+├── Key numbers table (cross-validated with TRUTH.md)
+├── System data flow diagram (existing ASCII art)
+├── Module navigation tree (one-line description per module)
+├── Symptom navigation table (NEW)
+└── Module dependency map (who calls who)
+```
+
+**Symptom Navigation Table** (NEW):
+
+| Symptom | First check | Then check | Common root cause |
+|---------|-------------|------------|-------------------|
+| Stream stuck | routing | chat → middleware | Connection lost / SaaS relay timeout |
+| Memory not injected | memory | middleware | FTS5 index empty / middleware skipped |
+| Hand trigger failed | hands-skills | middleware | Tool call blocked by Guardrail |
+| SaaS relay 502 | saas | routing | Token Pool exhausted / Key expired |
+| Model switch not working | routing | chat | SaaS whitelist vs local config mismatch |
+| Agent creation failed | chat | saas | Permission or persistence issue |
+| Pipeline execution stuck | pipeline | middleware | DAG cycle / missing dependency |
+| Admin page 403 | saas | security | JWT expired / admin_guard blocked |
+
+**Target**: ≤ 120 lines. A new AI session reads index and immediately knows which modules to open.
+
+### 3.2 Level 2: Module Pages (~15)
+
+Each module page has 5 sections in reading priority order:
+
+#### Section 1: Design Decisions (WHY)
+
+- Why this module was designed this way
+- Historical context and background
+- Trade-offs made and alternatives rejected
+- Key architectural decisions
+
+Format: prose paragraphs + Q&A pairs for important decisions.
+
+#### Section 2: Key Files + Data Flow (WHERE)
+
+- Core files table (3-7 files, one-line responsibility each)
+- Module-internal data flow diagram (ASCII or mermaid)
+- **Integration contracts** (NEW):
+  - What this module calls upstream
+  - What this module exposes downstream
+  - Interface shapes at boundaries
+
+#### Section 3: Code Logic (LOGIC)
+
+Focus on three types of information that code alone cannot efficiently convey:
+
+- **Key data flows**: Cross-function/cross-file complete paths
+- **Invariants**: Constraints that must always hold (marked with ⚡)
+- **Non-obvious algorithms**: Logic that is hard to understand from reading code alone
+
+Explicitly EXCLUDED:
+- Field lists (read from code)
+- Function signatures (read from code)
+- CRUD operations (obvious from code)
+- Anything that can be answered by `grep`
+
+#### Section 4: Active Issues + Gotchas (GOTCHAS)
+
+- Active issues (0-5 items, removed when fixed)
+- Historical pitfall records (≤ 10 items, distilled to one lesson each)
+- ⚠️ Warnings (error-prone areas)
+
+#### Section 5: Change Log (CHANGES)
+
+- Last 5 changes (format: date + one-liner)
+- Older changes → global `log.md`
+
+### 3.3 Module Page Template
+
+```markdown
+---
+title: {Module Name}
+updated: {YYYY-MM-DD}
+status: active | stable | developing
+tags: [{module-specific tags}]
+---
+
+# {Module Name}
+
+> From [[index]]. Related: [[related-module-1]] [[related-module-2]]
+
+## Design Decisions
+
+{Why this module exists, key design choices, tradeoffs}
+
+## Key Files + Data Flow
+
+### Core Files
+
+| File | Responsibility |
+|------|---------------|
+| `path/to/file` | One-line description |
+
+### Data Flow
+
+```
+{ASCII flow diagram}
+```
+
+### Integration Contracts
+
+> Format: Direction | Module | Interface (Rust trait / Tauri invoke / TS function) | Trigger
+
+| Direction | Module | Interface | Trigger |
+|-----------|--------|-----------|---------|
+| Calls → | {module} | `{rust_fn / tauri_invoke / ts_fn}` | {when/why} |
+| Called by ← | {module} | `{rust_fn / tauri_invoke / ts_fn}` | {when/why} |
+
+<!-- Example (middleware.md):
+| Calls → | runtime | `MiddlewareChain::run_before_completion()` | Every chat request before LLM call |
+| Called by ← | kernel | `kernel/mod.rs:create_middleware_chain()` | Kernel boot, once per session |
+| Called by ← | saas | HTTP relay handler | SaaS relay routes (10 HTTP middleware) |
+| Provides → | all modules | `AgentMiddleware` trait | 14 implementations registered |
+-->
+
+## Code Logic
+
+### Key Data Flows
+
+{Cross-function paths with intent}
+
+### Invariants
+
+⚡ {Invariant 1}: {description of what must always be true}
+
+⚡ {Invariant 2}: {description}
+
+### Non-obvious Algorithms
+
+{Algorithms that are hard to understand from reading code}
+
+## Active Issues + Gotchas
+
+### Active Issues
+
+| Issue | Severity | Status | Notes |
+|-------|----------|--------|-------|
+| {description} | P{0-3} | Open | {context} |
+
+### Historical Pitfalls
+
+- {Lesson learned}: {one-line description of what went wrong and the fix}
+
+### Warnings
+
+⚠️ {Warning}: {what to watch out for}
+
+## Change Log
+
+| Date | Change |
+|------|--------|
+| {YYYY-MM-DD} | {one-line description} |
+```
+
+## 4. Migration Plan
+
+### 4.0 Execution Order
+
+Migration must follow this sequence due to cross-page dependencies:
+
+1. **Phase A — Archive/cap** (no dependencies): Cap `log.md` at 50 entries, archive old to `wiki/archive/`. Convert `known-issues.md` to pointer. Archive `hermes-analysis.md`.
+2. **Phase B — Single source of truth**: Restructure `middleware.md` first (other pages reference it).
+3. **Phase C — Dependent pages**: `saas.md`, `security.md`, `memory.md` (remove middleware/evolution duplicates, add contracts).
+4. **Phase D — Remaining modules**: `routing.md`, `chat.md`, `butler.md`, `hands-skills.md`, `pipeline.md`, `data-model.md`.
+5. **Phase E — Index last**: `index.md` restructure (depends on all modules being complete).
+6. **Phase F — feature-map.md**: Distribute chain traces to module "Code Logic" sections, convert to index page.
+
+**Rollback strategy**: Migrate one module per commit. Any partial state is internally consistent per-page. `git revert` on a single commit restores that module's old version.
+
+### 4.1 Per-Page Source-to-Target Mapping
+
+#### `index.md` (8KB → target ≤ 120 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| Key numbers table | Keep | Stay (cross-validated with TRUTH.md) |
+| System data flow diagram | Keep | Stay |
+| Module navigation tree | Keep | Stay |
+| Architecture Q&A "Why 14 middleware" | Move | → `middleware.md` Design Decisions |
+| Architecture Q&A "Why 管家 default" | Move | → `butler.md` Design Decisions |
+| Architecture Q&A "Why 3 ChatStream" | Move | → `chat.md` Design Decisions |
+| Architecture Q&A "Why SaaS relay" | Move | → `routing.md` Design Decisions |
+| Architecture Q&A "Evolution engine" | Move | → `memory.md` Design Decisions |
+| Symptom navigation table | NEW | Add after navigation tree |
+
+#### `middleware.md` (7KB → target 150-200 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| Design thought | Keep as "Design Decisions" | Expand with WHY from index Q&A |
+| 14-layer table | Keep | Core Files + Data Flow |
+| Execution flow diagram | Keep | Code Logic |
+| SaaS HTTP middleware (10 layers) | Keep | Integration Contracts |
+| "11/14 no tests" warning | Keep | Active Issues |
+| API interface (trait) | Trim to key data flow | Code Logic (flows only) |
+
+#### `routing.md` (13KB → target 150-200 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| 5-branch decision tree | Keep | Code Logic → Key Data Flows |
+| Store layer listing (25 stores) | Remove | Split: chat stores → `chat.md`, saas stores → `saas.md`, connection stores stay |
+| lib/ file listing (75 files) | Remove | → `development.md` reference appendix |
+| Model routing full chain | Keep (simplified) | Code Logic → Key Data Flows |
+| Tauri commands table | Keep | Integration Contracts |
+
+#### `chat.md` (6KB → target 150-200 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| 3 ChatStream implementations | Keep as Design Decision | Add WHY from index Q&A |
+| Store 拆分 (5 Store) | Move | → Key Files table |
+| Send message flow | Keep | Code Logic → Key Data Flows |
+| Add invariants | NEW | e.g., ⚡ sessionKey must be consistent within a conversation |
+| Add integration contracts | NEW | Calls → routing (getClient), middleware (chain), saas (relay) |
+
+#### `memory.md` (19KB → target 200 lines, largest compression needed)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| Memory pipeline design | Keep as Design Decisions | + Absorb WHY from index Q&A |
+| FTS5/TF-IDF/embedding details | Keep invariants and flows | Code Logic |
+| Hermes insights (from hermes-analysis.md) | Distill 3-5 key lessons | Design Decisions (one paragraph) + Gotchas |
+| Detailed extraction logic | Trim to flows + invariants | Archive detailed prose to `wiki/archive/` |
+| Cross-session injection fix | Keep as historical pitfall | Gotchas |
+| Profile store connection fix | Keep as historical pitfall | Gotchas |
+
+#### `saas.md` (10KB → target 150-200 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| Auth flow (JWT/Cookie/TOTP) | Remove details | → `security.md` owns design, saas.md keeps reference |
+| Billing/subscription | Keep | Code Logic → Key Data Flows |
+| Admin V2 | Keep summary | Key Files |
+| Token Pool RPM/TPM | Keep | Code Logic → Non-obvious Algorithms |
+| Add integration contracts | NEW | Calls → relay, Called by ← desktop client |
+
+#### `security.md` (6KB → target 150-200 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| Auth flow details | OWN this content | Absorb from saas.md, become single source |
+| JWT/Cookie/TOTP details | Keep | Code Logic |
+| Rate limiting | Keep | Code Logic |
+| Add integration contracts | NEW | Provides auth middleware to SaaS, crypto utils to client |
+
+#### Other modules (`butler`, `hands-skills`, `pipeline`, `data-model`)
+
+All follow same pattern: keep existing design/code sections, add integration contracts, add invariants, trim to size budget.
+
+#### `feature-map.md` (15KB → Convert to index)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| F-01~F-05 chat chains | Distribute | → `chat.md` Code Logic as chain trace reference |
+| F-06~F-10 memory chains | Distribute | → `memory.md` Code Logic |
+| F-11~F-15 hand chains | Distribute | → `hands-skills.md` Code Logic |
+| Remaining chains | Distribute | → Corresponding module pages |
+| File itself | Keep as index | Module → feature chain mapping only |
+
+### 4.2 Pages to Merge/Archive
+
+| Page | Action | Destination |
+|------|--------|-------------|
+| `known-issues.md` | Convert to pointer | Active issues → per-module, global file = links only |
+| `log.md` | Cap at 50 entries | Archive old entries to `wiki/archive/log-{YYYY-MM}.md` |
+| `hermes-analysis.md` | Archive | Key insights → `memory.md` Gotchas, file → `wiki/archive/` |
+| `development.md` | Keep as-is | Global dev standards, not per-module |
+
+### 4.3 Duplicate Content Resolution
+
+| Content | Current Location | New Owner | Others |
+|---------|-----------------|-----------|--------|
+| Middleware descriptions | middleware + saas + security | `middleware.md` | Reference only |
+| Security mechanisms | security + saas | `security.md` | saas.md references |
+| Evolution engine | memory + middleware + index | `memory.md` | Others reference |
+| Store listing (25) | routing.md | Split: chat→chat, saas→saas, etc. | routing.md keeps connection stores |
+| lib/ file listing (75) | routing.md | `development.md` or dedicated reference | routing.md removes |
+
+## 5. Validation Criteria
+
+- [ ] New AI session can locate any module's core files from index in ≤ 2 hops
+- [ ] Each module page has integration contracts section
+- [ ] No content duplicated across ≥ 3 pages
+- [ ] index.md ≤ 120 lines
+- [ ] Each module page 100-200 lines
+- [ ] log.md ≤ 50 active entries
+- [ ] Symptom navigation table covers top 8 common debugging scenarios
+
+## 6. Risks and Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Module pages exceed size budget | Medium | AI context waste | Trim during migration, move details to archive |
+| Invariants drift from code | Medium | Misleading docs | Add "last verified" date, check during code changes |
+| Integration contracts incomplete | High | Gap remains | Start with existing cross-references, fill during next debug session |
+| Migration breaks existing workflow | Low | Confusion | Migrate one module at a time, verify after each |
+
+## 7. Open Questions
+
+- Should we add a `wiki/templates/module-template.md` for consistency?
--- a/docs/wiki-restructure/implementation-plan.md
+++ b/docs/wiki-restructure/implementation-plan.md
@@ -0,0 +1,492 @@
+# Wiki Restructure Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Restructure ZCLAW wiki from inconsistent module pages to a unified 5-section template with symptom navigation, integration contracts, and size budgets.
+
+**Architecture:** 6-phase migration following dependency order: archive/cap → middleware (single source) → dependents → remaining modules → index → feature-map. One module per commit for safe rollback.
+
+**Spec:** `docs/wiki-restructure/design-spec.md`
+
+---
+
+## Chunk 1: Phase A — Archive & Cap (no dependencies)
+
+### Task 1: Archive log.md old entries
+
+**Files:**
+- Create: `wiki/archive/log-2026-04-pre.md`
+- Modify: `wiki/log.md`
+
+- [ ] **Step 1: Count entries and identify cutoff**
+
+Run: `grep -c '^\[' wiki/log.md`
+Expected: ~100+ entries
+
+- [ ] **Step 2: Create archive file with entries beyond the most recent 50**
+
+Open `wiki/log.md`, identify the first 50 entries (newest first), move everything after line ~250 (the 50th entry boundary) to `wiki/archive/log-2026-04-pre.md`. Keep the frontmatter and header in both files.
+
+- [ ] **Step 3: Verify log.md has ≤ 50 entries**
+
+Run: `grep -c '^\[' wiki/log.md`
+Expected: ≤ 50
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add wiki/log.md wiki/archive/log-2026-04-pre.md
+git commit -m "docs(wiki): 归档 log.md 旧条目 — 保留最近50条"
+```
+
+### Task 2: Archive hermes-analysis.md
+
+**Files:**
+- Move: `wiki/hermes-analysis.md` → `wiki/archive/hermes-analysis.md`
+
+- [ ] **Step 1: Move file to archive**
+
+```bash
+mv wiki/hermes-analysis.md wiki/archive/hermes-analysis.md
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add wiki/hermes-analysis.md wiki/archive/hermes-analysis.md
+git commit -m "docs(wiki): 归档 hermes-analysis.md — 洞察已在 memory.md"
+```
+
+### Task 3: Convert known-issues.md to pointer
+
+**Files:**
+- Create: `wiki/archive/known-issues-full-2026-04-22.md`
+- Modify: `wiki/known-issues.md`
+
+- [ ] **Step 1: Archive full content**
+
+```bash
+cp wiki/known-issues.md wiki/archive/known-issues-full-2026-04-22.md
+```
+
+- [ ] **Step 2: Extract active issues per module for later use**
+
+Read `wiki/known-issues.md`, note all currently OPEN issues and which module they belong to. Use these when writing Task 5-13 module pages.
+
+- [ ] **Step 3: Rewrite known-issues.md as pointer index**
+
+Replace with:
+```markdown
+---
+title: 已知问题索引
+updated: 2026-04-22
+status: active
+---
+
+# 已知问题索引
+
+> 活跃问题已迁移至各模块页面的"活跃问题+陷阱"章节。本文件仅作索引。
+
+## 活跃问题
+
+| 模块 | 问题数 | 详见 |
+|------|--------|------|
+| chat | 1 | [[chat#Active Issues]] |
+| memory | 1 | [[memory#Active Issues]] |
+| hands-skills | 2 | [[hands-skills#Active Issues]] |
+| middleware | 2 | [[middleware#Active Issues]] |
+
+## 已归档
+
+- 全量问题记录: `wiki/archive/known-issues-full-2026-04-22.md`
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add wiki/known-issues.md wiki/archive/known-issues-full-2026-04-22.md
+git commit -m "docs(wiki): known-issues.md 转为索引 — 活跃问题迁入各模块"
+```
+
+---
+
+## Chunk 2: Phase B — middleware.md (single source of truth)
+
+### Task 4: Restructure middleware.md
+
+**Files:**
+- Modify: `wiki/middleware.md` (7KB → target 150-200 lines)
+
+- [ ] **Step 1: Write new middleware.md**
+
+Rewrite with 5-section template. Content mapping:
+
+| New Section | Source |
+|-------------|--------|
+| Design Decisions | Current "设计思想" + index Q&A "为什么14层中间件" |
+| Key Files + Data Flow | 14-layer table → Core Files, execution flow → Data Flow |
+| Integration Contracts | NEW (see below) |
+| Code Logic | Priority ordering, decision types |
+| Active Issues + Gotchas | "11/14 no tests" warning, TrajectoryRecorder fix |
+| Change Log | Last 5 from log.md |
+
+Integration contracts:
+- Called by ← kernel: `kernel/mod.rs:create_middleware_chain()` (kernel boot, once per session)
+- Calls → runtime: `MiddlewareChain::run_before_completion()` (every chat request before LLM call)
+- Called by ← saas: HTTP relay handler (10 HTTP middleware layers)
+- Provides → all: `AgentMiddleware` trait (14 implementations registered)
+
+Invariants:
+- ⚡ Priority is ascending: 0-999, lower = earlier execution
+- ⚡ Registration order ≠ execution order; chain sorts by priority at runtime
+- ⚡ Stop/Block/AbortLoop halts the chain immediately (no further middleware runs)
+
+- [ ] **Step 2: Verify line count**
+
+Run: `wc -l wiki/middleware.md`
+Expected: 150-200
+
+- [ ] **Step 3: Verify all 5 sections**
+
+Run: `grep '^## ' wiki/middleware.md`
+Expected: ≥ 5 sections
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add wiki/middleware.md
+git commit -m "docs(wiki): 重构 middleware.md — 5节模板+集成契约+不变量"
+```
+
+---
+
+## Chunk 3: Phase C — Dependent pages
+
+### Task 5: Restructure saas.md
+
+**Files:**
+- Modify: `wiki/saas.md` (231 lines → target 150-200)
+
+- [ ] **Step 1: Remove security duplicates**
+
+Delete: 认证流 (L46-61), 密码安全 (L78-89), Token刷新 (L91-98). Replace with: "认证安全详见 [[security]]"
+
+- [ ] **Step 2: Write 5-section structure**
+
+- Design Decisions: WHY SaaS relay architecture, WHY Token Pool
+- Key Files: 16 SaaS dirs, 3-7 core files
+- Integration Contracts: Called by ← desktop (Tauri invoke), Calls → relay, Token Pool
+- Code Logic: Token Pool RPM/TPM algorithm, Workers (7), billing flow
+- Active Issues + Gotchas: Active items from known-issues + Embedding deferred
+- Change Log: Last 5
+
+- [ ] **Step 3: Verify line count and commit**
+
+```bash
+git add wiki/saas.md
+git commit -m "docs(wiki): 重构 saas.md — 移除安全重复+5节模板+契约"
+```
+
+### Task 6: Restructure security.md
+
+**Files:**
+- Modify: `wiki/security.md` (158 lines → target 150-200)
+
+- [ ] **Step 1: Absorb auth content from saas.md**
+
+Import the authentication flow, JWT pwv, password security content removed from saas.md.
+
+- [ ] **Step 2: Write 5-section structure**
+
+- Design Decisions: WHY each security mechanism
+- Key Files: security files, auth flow diagram
+- Integration Contracts: Provides → saas (auth middleware), Provides → desktop (crypto utils)
+- Code Logic: JWT pwv mechanism, Argon2id, AES-256-GCM, rate limiting
+- Active Issues + Gotchas: Security audit findings
+- Change Log: Last 5
+
+- [ ] **Step 3: Verify and commit**
+
+```bash
+git add wiki/security.md
+git commit -m "docs(wiki): 重构 security.md — 吸收saas安全内容+5节模板"
+```
+
+### Task 7: Restructure memory.md
+
+**Files:**
+- Create: `wiki/archive/memory-extraction-details.md`
+- Modify: `wiki/memory.md` (363 lines → target 200)
+
+- [ ] **Step 1: Archive detailed extraction prose**
+
+Move detailed extraction logic to `wiki/archive/memory-extraction-details.md`. Keep only flows + invariants in memory.md.
+
+- [ ] **Step 2: Write 5-section structure**
+
+- Design Decisions: WHY memory pipeline + index Q&A "进化引擎做什么" + Hermes insights (3-5 lessons in one paragraph)
+- Key Files: 闭环数据流 diagram, 3-7 core files
+- Integration Contracts: Called by ← middleware (Memory@150), Calls → FTS5/TF-IDF, Provides → loop_runner
+- Code Logic: Pipeline flow, cross-session injection, FTS5+TF-IDF
+- Active Issues + Gotchas: Cross-session fix history, profile store fix, Embedding deferred
+- Change Log: Last 5
+
+Invariants:
+- ⚡ memories.db and data.db are separate SQLite databases; cross-DB queries need correct connection
+- ⚡ Memory injection at middleware@150, AFTER ButlerRouter@80, BEFORE SkillIndex@200
+
+- [ ] **Step 3: Verify ≤ 200 lines and commit**
+
+```bash
+git add wiki/memory.md wiki/archive/memory-extraction-details.md
+git commit -m "docs(wiki): 重构 memory.md — 压缩至200行+不变量+Hermes提炼"
+```
+
+---
+
+## Chunk 4: Phase D — Remaining modules
+
+### Task 8: Restructure routing.md
+
+**Files:**
+- Modify: `wiki/routing.md` (13KB → target 150-200)
+
+- [ ] **Step 1: Remove Store/lib listings**
+
+Move chat stores → chat.md, saas stores → saas.md. Move lib/ listing → development.md.
+
+- [ ] **Step 2: Write 5-section structure**
+
+- Design Decisions: WHY 5-branch + WHY SaaS relay + index Q&A
+- Key Files: 5-branch decision tree, degradation flow
+- Integration Contracts: Calls → saas, Calls → kernel, Called by ← stores (getClient)
+- Code Logic: Decision tree flow, model routing, SaaS degradation
+- Active Issues + Gotchas: Current known issues
+- Change Log: Last 5
+
+- [ ] **Step 3: Verify and commit**
+
+```bash
+git add wiki/routing.md
+git commit -m "docs(wiki): 重构 routing.md — 移除Store/lib列表+5节模板"
+```
+
+### Task 9: Restructure chat.md
+
+**Files:**
+- Modify: `wiki/chat.md` (~180 lines → target 150-200)
+
+- [ ] **Step 1: Write 5-section structure**
+
+- Design Decisions: WHY 3 ChatStream + index Q&A
+- Key Files: 5 Store split, key files, send flow
+- Integration Contracts: Calls → routing (getClient), Called by ← UI, Emits → streamStore
+- Code Logic: Send message flow, stream events, 5-min timeout
+- Active Issues: B-CHAT-07 (P2)
+- Change Log: Last 5
+
+Invariants:
+- ⚡ sessionKey consistent within conversation
+- ⚡ cancelStream sets atomic flag, no race with onDelta
+
+- [ ] **Step 2: Verify and commit**
+
+```bash
+git add wiki/chat.md
+git commit -m "docs(wiki): 重构 chat.md — 3种ChatStream WHY+契约+不变量"
+```
+
+### Task 10: Restructure butler.md
+
+**Files:**
+- Modify: `wiki/butler.md` (215 lines → target 150-200)
+
+- [ ] **Step 1: Remove duplicates**
+
+MemorySection frontend path → reference [[memory]]. SemanticSkillRouter → reference [[hands-skills]].
+
+- [ ] **Step 2: Write 5-section structure**
+
+- Design Decisions: WHY 管家默认 + WHY 双模式
+- Key Files: ButlerRouter flow, cold start hook
+- Integration Contracts: Middleware@80, Calls → skill router, Calls → memory
+- Code Logic: Keyword matching, XML fencing, cross-session continuity
+- Active Issues + Gotchas: Current issues
+- Change Log: Last 5
+
+- [ ] **Step 3: Verify and commit**
+
+```bash
+git add wiki/butler.md
+git commit -m "docs(wiki): 重构 butler.md — 移除重复+5节模板+契约"
+```
+
+### Task 11: Restructure hands-skills.md
+
+**Files:**
+- Modify: `wiki/hands-skills.md` (281 lines → target 150-200)
+
+- [ ] **Step 1: Write 5-section structure**
+
+- Design Decisions: WHY 7 hands + WHY 75 skills + semantic routing
+- Key Files: Hand trigger flow, skill chain
+- Integration Contracts: Called by ← loop_runner, Calls → browser/Twitter, Provides → SkillIndex middleware
+- Code Logic: Hand trigger+approval, TF-IDF routing, MCP bridge
+- Active Issues: Hands E2E, Clip needs FFmpeg
+- Change Log: Last 5
+
+- [ ] **Step 2: Verify and commit**
+
+```bash
+git add wiki/hands-skills.md
+git commit -m "docs(wiki): 重构 hands-skills.md — 5节模板+契约"
+```
+
+### Task 12: Restructure pipeline.md
+
+**Files:**
+- Modify: `wiki/pipeline.md` (157 lines → target 150-200)
+
+- [ ] **Step 1: Add contracts and reorganize**
+
+Already near target. Add integration contracts, invariants, reorganize to 5-section.
+
+- Design Decisions: WHY DAG + WHY YAML
+- Key Files: Architecture, templates
+- Integration Contracts: Called by ← UI, Calls → runtime (DAG executor)
+- Code Logic: DAG execution, template loading
+- Active Issues: E2E pass rate
+- Change Log: Last 5
+
+- [ ] **Step 2: Verify and commit**
+
+```bash
+git add wiki/pipeline.md
+git commit -m "docs(wiki): 重构 pipeline.md — 5节模板+契约"
+```
+
+### Task 13: Restructure data-model.md
+
+**Files:**
+- Modify: `wiki/data-model.md` (181 lines → target 150-200)
+
+- [ ] **Step 1: Add contracts and reorganize**
+
+Already near target. Add integration contracts, reorganize to 5-section.
+
+- Design Decisions: WHY dual database (PG+SQLite)
+- Key Files: DB schema overview
+- Integration Contracts: Called by ← saas (PG), Called by ← memory (SQLite/FTS5)
+- Code Logic: Dual-DB architecture, FTS5 structure
+- Active Issues: pgvector deferred, CJK fallback
+- Change Log: Last 5
+
+- [ ] **Step 2: Verify and commit**
+
+```bash
+git add wiki/data-model.md
+git commit -m "docs(wiki): 重构 data-model.md — 5节模板+契约"
+```
+
+---
+
+## Chunk 5: Phase E — Index restructure
+
+### Task 14: Restructure index.md
+
+**Files:**
+- Modify: `wiki/index.md` (144 lines → target ≤ 120)
+
+- [ ] **Step 1: Remove architecture Q&A**
+
+Delete "核心架构决策" section (5 Q&A pairs). Now in respective module pages.
+
+- [ ] **Step 2: Add symptom navigation table**
+
+8-row table from spec, after module navigation tree.
+
+- [ ] **Step 3: Add module dependency map**
+
+Simple ASCII: UI → routing → chat → middleware → memory → saas → security
+
+- [ ] **Step 4: Verify ≤ 120 lines**
+
+Run: `wc -l wiki/index.md`
+Expected: ≤ 120
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add wiki/index.md
+git commit -m "docs(wiki): 重构 index.md — 症状导航+依赖图+≤120行"
+```
+
+---
+
+## Chunk 6: Phase F — feature-map.md conversion
+
+### Task 15: Distribute feature-map chain traces
+
+**Files:**
+- Modify: `wiki/feature-map.md` (424 lines → ~80, index only)
+- Modify: Module pages (add chain trace references)
+
+- [ ] **Step 1: Add one-line chain traces to module Code Logic sections**
+
+| Module | Features |
+|--------|----------|
+| chat | F-01~F-05, F-06~F-09 |
+| hands-skills | F-10~F-13 |
+| memory | F-14~F-16 |
+| saas | F-17~F-22 |
+| butler | F-23~F-25 |
+| pipeline | F-26~F-28 |
+| routing | F-29~F-31 |
+| security | F-32~F-33 |
+
+- [ ] **Step 2: Rewrite feature-map.md as lightweight index**
+
+Module → feature mapping table only. No full chain details.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add wiki/feature-map.md wiki/chat.md wiki/memory.md wiki/hands-skills.md wiki/saas.md wiki/butler.md wiki/pipeline.md wiki/routing.md wiki/security.md
+git commit -m "docs(wiki): feature-map 分发链路到各模块 — 转为索引页"
+```
+
+---
+
+## Final: Validation
+
+### Task 16: Validate all criteria
+
+- [ ] **Step 1: Line counts**
+
+```bash
+wc -l wiki/index.md wiki/routing.md wiki/chat.md wiki/saas.md wiki/security.md wiki/memory.md wiki/butler.md wiki/middleware.md wiki/hands-skills.md wiki/pipeline.md wiki/data-model.md
+```
+
+Expected: index ≤ 120, all others 100-200
+
+- [ ] **Step 2: 5-section coverage**
+
+```bash
+for f in wiki/routing.md wiki/chat.md wiki/saas.md wiki/security.md wiki/memory.md wiki/butler.md wiki/middleware.md wiki/hands-skills.md wiki/pipeline.md wiki/data-model.md; do echo "=== $f ===" && grep '^## ' $f; done
+```
+
+Expected: each has Design Decisions, Key Files, Code Logic, Active Issues, Change Log
+
+- [ ] **Step 3: Integration contracts**
+
+```bash
+grep -l 'Integration Contracts\|集成契约' wiki/*.md
+```
+
+Expected: all module pages
+
+- [ ] **Step 4: Push**
+
+```bash
+git push
+```