From de7d88afcc46d252986308f3f893249310a16bd6 Mon Sep 17 00:00:00 2001 From: iven Date: Wed, 22 Apr 2026 20:04:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(spec):=20wiki=E9=87=8D=E6=9E=84=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1v2=20=E2=80=94=20=E4=BF=AE=E5=A4=8Dreview=E9=97=AE?= =?UTF-8?q?=E9=A2=98(=E6=89=A7=E8=A1=8C=E9=A1=BA=E5=BA=8F+=E5=86=85?= =?UTF-8?q?=E5=AE=B9=E6=98=A0=E5=B0=84+=E5=A5=91=E7=BA=A6=E7=A4=BA?= =?UTF-8?q?=E4=BE=8B)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.7 --- .../2026-04-22-wiki-restructure-design.md | 138 +++++++++++++++--- 1 file changed, 116 insertions(+), 22 deletions(-) diff --git a/docs/superpowers/specs/2026-04-22-wiki-restructure-design.md b/docs/superpowers/specs/2026-04-22-wiki-restructure-design.md index fc8ff24..db6a4a4 100644 --- a/docs/superpowers/specs/2026-04-22-wiki-restructure-design.md +++ b/docs/superpowers/specs/2026-04-22-wiki-restructure-design.md @@ -133,10 +133,19 @@ tags: [{module-specific tags}] ### Integration Contracts -| Direction | Module | Interface | Notes | -|-----------|--------|-----------|-------| -| Calls → | {module} | {function/API} | {when/why} | -| Called by ← | {module} | {function/API} | {when/why} | +> 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 @@ -179,22 +188,109 @@ tags: [{module-specific tags}] ## 4. Migration Plan -### 4.1 Pages to Create/Update +### 4.0 Execution Order -| Page | Action | Notes | -|------|--------|-------| -| `index.md` | Restructure | Add symptom table, remove architectural Q&A (move to modules), target ≤ 120 lines | -| `routing.md` | Restructure | Move Store list to respective modules, add integration contracts | -| `chat.md` | Restructure | Add invariants, integration contracts | -| `saas.md` | Restructure | Remove security details (reference security.md), add contracts | -| `butler.md` | Restructure | Add integration contracts with middleware | -| `middleware.md` | Restructure | Become single source of truth for middleware, add contracts | -| `memory.md` | Restructure | Absorb hermes insights, add invariants | -| `hands-skills.md` | Restructure | Add integration contracts | -| `pipeline.md` | Restructure | Add integration contracts | -| `security.md` | Restructure | Own all security design, add contracts | -| `data-model.md` | Restructure | Add integration contracts | -| `feature-map.md` | Convert to index | Distribute chain traces to modules, keep as index | +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 @@ -202,7 +298,7 @@ tags: [{module-specific tags}] |------|--------|-------------| | `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`, file → `wiki/archive/` | +| `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 @@ -236,6 +332,4 @@ tags: [{module-specific tags}] ## 7. Open Questions -- Should feature-map.md be fully absorbed into modules or kept as a standalone index? -- What format for integration contracts — prose table or structured schema? - Should we add a `wiki/templates/module-template.md` for consistency?