iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: wiki重构设计spec+实施计划 — 移至 docs/wiki-restructure/
Some checks failed
CI / E2E Tests (push) Has been cancelled
Details
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details

Browse Source 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
iven
2026-04-22 21:26:51 +08:00
parent de7d88afcc
commit 73139da57a
2 changed files with 827 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

335
docs/wiki-restructure/design-spec.md Normal file
View File

@@ -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?

492
docs/wiki-restructure/implementation-plan.md Normal file
View File

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