From 73139da57a81e2b89714bb2c0223a1e539783e00 Mon Sep 17 00:00:00 2001 From: iven Date: Wed, 22 Apr 2026 21:26:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20wiki=E9=87=8D=E6=9E=84=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1spec+=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92=20=E2=80=94?= =?UTF-8?q?=20=E7=A7=BB=E8=87=B3=20docs/wiki-restructure/?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.7 --- docs/wiki-restructure/design-spec.md | 335 +++++++++++++ docs/wiki-restructure/implementation-plan.md | 492 +++++++++++++++++++ 2 files changed, 827 insertions(+) create mode 100644 docs/wiki-restructure/design-spec.md create mode 100644 docs/wiki-restructure/implementation-plan.md diff --git a/docs/wiki-restructure/design-spec.md b/docs/wiki-restructure/design-spec.md new file mode 100644 index 0000000..db6a4a4 --- /dev/null +++ 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} | + + + +## 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? diff --git a/docs/wiki-restructure/implementation-plan.md b/docs/wiki-restructure/implementation-plan.md new file mode 100644 index 0000000..7cb9828 --- /dev/null +++ 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 +```