zclaw_openfang/docs/wiki-restructure/implementation-plan.md

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

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

mv wiki/hermes-analysis.md wiki/archive/hermes-analysis.md

• Step 2: Commit

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

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:

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

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

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

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

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

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

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

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

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

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

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

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

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-01F-05, F-06F-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

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

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

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

grep -l 'Integration Contracts\|集成契约' wiki/*.md

Expected: all module pages

• Step 4: Push

git push