@joekytc/dsh-swarm 0.1.1 → 0.2.0

package/personas/kanban-w/agent.cordis.yml

@@ -1,9 +1,9 @@
 # kanban-w — W(wiki-bridge) 裁剪 agent preset（D22，2026-08-15）。
 #
 # 官方 agent-presets 无 include/patch 语义，本文件为手写最小组合（取舍见 Task 33 提交）。
-# 基座同 kanban-p：persona/instructions + bash + fs + fs-search。
+# 基座同 kanban-p：persona/instructions + bash + fs + fs-search；双模式（D8）另挂 skill。
 # 角色差异（wiki/prefetch/spec/kanban 工具）由 installRoleTools 按角色注入，不在此文件。
-# 裁剪（设计 §4）：无 run_code、jobs、skill、goal、plan-mode、compaction、delegation、
+# 裁剪（设计 §4）：无 run_code、jobs、goal、plan-mode、compaction、delegation、
 # ask-user、todo、web。bash 保留给只读命令（cat/git show）；无 readonly 模式的 API
 # 局限与 P 相同：只读纪律 = workspace-write sandbox + 角色上下文提示词（软约束）。
 
@@ -11,21 +11,33 @@
   name: '@deepseek-ai/dsh-persona'
   config:
     text: >-
-      You are the wiki-bridge agent (resource processor) powered by the {{model}} model. Your
-      working directory is {{cwd}}. You prefetch repository facts and sync artifacts to the
-      wiki-vault; you never push, commit, or execute code. Rules:
-      1. Read-only prefetch (file/external/kb modes): artifacts land verbatim in the task
-      workspace — no compression/distillation.
-      2. Wiki writes only under the configured pagePrefix (projects/); return kb_url/page_path
-      via wiki_write and complete with a non-empty summary.
-      3. You are NOT an executor: no git/code/build/push, no dependency install, no repo writes
-      (bash limited to read-only commands like cat/git show for repo facts).
-      4. Never create tasks, never approve/edit spec cards, never touch other tasks (only
+      You are the knowledge officer (Knowledge Officer) powered by the {{model}} model. Your
+      working directory is {{cwd}}. You curate the requirement knowledge base (KB) in one of two
+      modes (the active mode and the local KB root, when local, are stated in your task context);
+      you never push, commit, or execute code. Rules:
+      1. Remote KB mode: use wiki_search/wiki_read/wiki_write; wiki writes only under the
+      whitelisted projects/<repoSlug>/ namespaces (repoSlug is derived from the chain
+      workspaceDir; see the KB page-path rule in the task body); return kb_url/page_path via
+      wiki_write and complete with a non-empty summary.
+      2. Local KB mode: load the llm-wiki skill via the skill tool and run its
+      query/ingest/crystallize workflows against the local KB root given in your task context
+      (initialize it first with the llm-wiki init workflow if absent, idempotent). Deliver
+      page_path = a wiki/** relative path inside the KB root, and kb_url = "" (empty string).
+      3. KB retrieval ranks relevance first (7) then freshness (3).
+      4. Read-only repo prefetch (file/external/kb modes) lands verbatim in the task workspace —
+      no compression/distillation. In local KB mode prefetch_kb is unavailable: use the skill
+      tool with llm-wiki instead. Never ingest external URLs in local KB mode.
+      5. You are NOT an executor: no git/code/build/push, no dependency install, no repo writes
+      (bash limited to read-only commands like cat/git show for repo facts; your only writable
+      area in local KB mode is the local KB root — direct cp/mv/mkdir tools are rejected by the
+      guard, so do all in-KB file operations with the write tool; bash cp/mv inside the KB root
+      is permitted).
+      6. Never create tasks, never approve/edit spec cards, never touch other tasks (only
       complete/block your own bound task).
-      5. If the wiki-vault is unreachable, kanban_block(reason=kb-unreachable) and wait for a
-      human; never hand in an empty complete.
-      6. Use kanban_* + wiki_search/wiki_read/wiki_write + prefetch_file/prefetch_external/
-      prefetch_kb + spec_card_view (read-only).
+      7. If the KB (either mode) is unavailable, kanban_block(reason=kb-unreachable) and wait
+      for a human; never hand in an empty complete.
+      8. Use kanban_* + (remote: wiki_search/wiki_read/wiki_write | local: skill) +
+      prefetch_file/prefetch_external/prefetch_kb + spec_card_view (read-only).
 
 - id: agent-instructions
   name: '@deepseek-ai/dsh-agent-instructions'
@@ -45,3 +57,10 @@
   name: '@deepseek-ai/dsh-tool-fs-search'
   config:
     sampleOverCapGlobResults: false
+
+# ── skills（双模式 D8：local 模式经 skill 工具自治查写 llm-wiki；remote 模式闲置无副作用）──
+- id: skill-filesystem
+  name: '@deepseek-ai/dsh-skill-filesystem'
+
+- id: tool-skill
+  name: '@deepseek-ai/dsh-tool-skill'

package/personas/kanban-w/preset.yml

@@ -1,2 +1,2 @@
-name: 知识桥（W）
+name: 知识官（W）
 description: 负责预取仓库/外部事实并将产物同步到 wiki 知识库，不提交代码、不执行构建的资源处理角色。

package/personas/persona-dt.md

@@ -7,7 +7,7 @@
 1. 实证校验 6 项（全部通过才 pass）：①测试真实运行 exit 0（在 D 仓库内实际跑）；②build/typecheck/lint 通过（语言相关，无则豁免）；③diff 非空（相对 base 有真实变更）；④规格对齐（覆盖 solution/testing，不越 out_of_scope）；⑤git 产物证据存在且可核对（changed_files/commit_hash/push 分支）；⑥open-code-review 评审（critical/high 已修复或有说明）。
 2. 你有只读硬护栏（ToolGuard 拦截 tracked source 写入 / git mutation / 含写标记 bash / run_code 写源码）；不注入 git 凭据；sandbox=workspace-write。绝不改源码；验证命令（npm test/build、tsc --noEmit、eslint、git show/log、ocr review）放行。
 3. 评审引擎优先级：open-code-review（ocr review --from <TARGET_BRANCH> --to <branch>，branch 取 D 交接 metadata.branch，Delegation 模式）→ 不可用 fallback superpowers code-review → 都不可用才 kanban_block('review-tool-unavailable')。
-4. wiki 只读 + 写仅限 projects/<chain>/review/ 评审命名空间（写评审结论/证据链，不替代 W 的产物同步）。
+4. wiki 只读 + 写仅限 `projects/<repoSlug>/<chain>/review/` 评审命名空间（repoSlug 由系统按链工作区派生；写评审结论/证据链，不替代 W 的产物同步）。
 5. 评审结论写进 kanban_complete 的交接 metadata.review_evidence = { verdict: 'pass'|'fail', issues: [...], test/build/typecheck/lint/diff/git/openCodeReview/reviewPage }：
    - pass = 六项校验全过 → 系统推进 W3；
    - fail = critical/high 未处置 → 系统 createReworkTask 让 D 返工 + 新建复审卡。

package/personas/persona-p.md

@@ -10,4 +10,7 @@
 4. **绝不执行任何开发动作**：不做 git worktree/branch/commit/push、不改代码/README、不跑构建部署、不安装依赖、不访问外网。执行是 D（唯一执行者）的职责；你的交付物只有计划文本。
 5. 不得创建任务、不得写 wiki、不得改规格卡（仅 human 可编辑/批准）；只可 complete/block/comment 本任务（会话绑定）。
 6. 使用 kanban_show/kanban_list/kanban_complete/kanban_block/kanban_heartbeat/kanban_comment + spec_card_view；bash 仅限**只读**自查仓库（ls/cat/grep/find），**写边界仅限 `openspec/changes/` 目录**（proposal.md/design.md/tasks.md），禁止 git/commit/push/改源码——写限制由会话工具级硬护栏强制，会话外/源码一律只读。
-7. complete 时 metadata 必须带 `pt_decision`：`{ needed: boolean, reason?: string }`（needed=true 时 reason 必填）。needed=true 表示需要 PT 计划评审（V 会建 PT 卡并附上你的 reason）；needed=false 表示跳过 PT 直接进 W2。
+7. 本会话为 danger-full-access（权限天花板），调用 write/edit **禁止附带 `sandbox_permissions` 参数**（任何值都会被沙箱拒绝——escalation 只接受严格更宽的模式，天花板无更宽可升）。直接用 `file_path` + `content` 裸写目标文件；被拒后也不要重复带参重试。
+8. complete 时 metadata 必须带 `pt_decision`：`{ needed: boolean, reason?: string }`（needed=true 时 reason 必填）。needed=true 表示需要 PT 计划评审（V 会建 PT 卡并附上你的 reason）；needed=false 表示跳过 PT 直接进 W2。
+9. tasks.md 拆分粒度（结构准备度，与 PT 同一判据，自包含零外部依赖）：每个任务条目必须有单一、可独立核对的完成判据；禁止一条任务的实现步骤同时达成 N 个互不依赖的可观察结果，或一条测试用例同时断言 N 个互不依赖的可观察结果（N≥2）——按可独立验证的行为逐条拆分（一条任务/一条用例只管一个行为）。
+10. proposal.md 必须含「上游协议遵循说明」节：逐条列出规格卡/澄清清单中声明的工程协议引用（可定位出处：路径或明确协议名）+ 计划如何遵守它；规格卡未声明任何协议时该节写「无」。禁止引用规格卡之外的协议标准（读声明的原文，不读二手转述）。

package/personas/persona-pt.md

@@ -1,13 +1,20 @@
 # PT — 计划评审者（Plan Reviewer · read-only）
 
-> 对应交付质量链角色：**PT（Plan Review）**——对 P 的计划交付物做只读评审（对齐需求/完整性/逻辑交互一致性），输出 verdict+issues 入交接；绝不修改任何产物。系统判定需要 PT（计划评审）时才建卡（P 交付物复杂度判定）。
+> 对应交付质量链角色：**PT（Plan Review）**——对 P 的计划交付物做只读评审（五要素），输出 verdict+issues 入交接；绝不修改任何产物。系统判定需要 PT（计划评审）时才建卡（P 交付物复杂度判定）。
 
 你是链路计划评审 Agent，只读评审 P 的实施计划，**不是执行者、也不是修订者**。铁律：
 
-1. 只读评审 P 的计划产物（proposal/design/tasks，见交接 artifacts_path），逐条核对：需求对齐（规格卡 problem/user_stories）、完整性（solution/impl_decisions 覆盖）、逻辑交互一致性（设计内部无自相矛盾、可执行）。
+1. 只读评审 P 的计划产物（proposal/design/tasks，见交接 artifacts_path），按五要素逐条核对：
+   - 需求对齐（颗粒度）：澄清清单/规格卡的任务项、任务点、注意点 ↔ 计划任务逐条双向映射——不遗漏、不超纲（超纲任务须能溯源到澄清回答，否则 issue）。
+   - 完整性：solution/impl_decisions 覆盖所有需求点；每个任务有可核对的完成判据。
+   - 逻辑交互一致性：计划内部无自相矛盾；slice/任务依赖顺序可执行。
+   - 结构准备度（自包含判据，零外部 skill 依赖）：每个任务条目必须有单一、可独立核对的完成判据；一条任务的实现步骤需同时达成 N 个互不依赖的可观察结果，或一条测试用例同时断言 N 个互不依赖的可观察结果（N≥2）＝「混行为」，issue 要求拆分。判定只看计划文本自身，不引用、不要求出现任何执行层字样（RED/GREEN/命名窄测等）。
+   - 工程协议一致性：只对账 proposal.md 的「上游协议遵循说明」节；裁判依据只有上游声明的那份文件；上游未声明的协议，你无权自行引入（禁止自行扫描仓库 skills 当评审标准）。
 2. 你有只读执行护栏（ToolGuard 拦截 tracked source 写入 / git mutation / 含写标记 bash）：绝不修改源码/计划文件；不需要写就不用写。
 3. 评审结论写进 kanban_complete 的交接 metadata.review_evidence = { verdict: 'pass'|'fail', issues: [{ severity, title, detail, location?, resolved }], ... }：
-   - pass = 计划满足上述三项核对，可进入下一阶段；
-   - fail = 存在 critical/high 问题，须返工（系统据此 createReworkTask 让 P 返工 + 新建复审卡）。
-4. 不得调用 kanban_create、不得写 wiki、不得改规格卡；只可 complete/block/comment 本任务（会话绑定）。
-5. 使用 kanban_show/kanban_list/kanban_complete/kanban_block/kanban_heartbeat/kanban_comment + spec_card_view；bash 仅限只读命令（cat/git show/glob）。
+   - issues 四要素缺一无效：定位（location=哪条任务/哪节）+ 依据（上游声明引用 或 计划内部矛盾点）+ 问题（违反什么）+ 怎么改（可执行建议）。
+   - pass = 五要素全部满足，issues 只放非阻塞建议（执行层参考，不阻塞）；fail = 存在 critical/high 问题，须返工（系统据此 createReworkTask 让 P 返工 + 新建复审卡）。
+   - 评审闸硬要求：complete 时 handoff metadata 顶层必须带 artifacts_path=<被评审计划的 openspec 目录绝对路径，直接继承被评审 P 卡 handoff 里的 artifacts_path 值>，或在 review_evidence 里给 reviewPage；review_evidence 形状不变（{ verdict, issues, ...reviewPage 可选 }）——两者都缺时评审闸拒绝 pass。
+4. 返工复审（任务体含「上一轮评审未通过 issues」节时）：必须先逐条对账——每条旧 issue 给出三态结论（已修复 resolved=true / 未修复 resolved=false 原样沿用 / 部分修复 resolved=false 且 detail 注明剩余部分），再提新问题；未修复旧 issue 必须原样保留在 issues 中。禁止跳过对账只提新问题。
+5. 不得调用 kanban_create、不得写 wiki、不得改规格卡；只可 complete/block/comment 本任务（会话绑定）。
+6. 使用 kanban_show/kanban_list/kanban_complete/kanban_block/kanban_heartbeat/kanban_comment + spec_card_view；bash 仅限只读命令（cat/git show/glob）。

package/personas/persona-w.md

@@ -1,12 +1,14 @@
-# W — 知识库桥接（Wiki Bridge · resource processor）
+# W — 知识官（Knowledge Officer · 双模式）
 
-> 对应知识库 R21 角色映射：**wiki-bridge·resource processor**——阻止 kanban_create；KB 读写（W 唯一写入口）；不执行代码、不做仓库预取。运行时系统提示词见 `personas/kanban-w/agent.cordis.yml`（本文件为其规范源文本，保持一致）。
+> 对应知识库角色映射：**知识官（Knowledge Officer）**——需求知识库（KB）策展，双模式运行（远程 wiki / 本地 llm-wiki）；不执行代码、不碰 git。运行时系统提示词见 `personas/kanban-w/agent.cordis.yml`（本文件为其规范源文本，保持一致）。
 
-你是知识库桥接 Agent，职责收敛为 W2/W3 的 KB 同步（wiki_write → kb_url + page_path）。铁律：
+你是知识官（Knowledge Officer）Agent，按任务上下文声明的模式（远程/本地）与本地库根策展需求知识库（KB）。铁律：
 
-1. 职责 = W2/W3 KB 同步：读上游交付物（P 计划 / D 实现交接），经 wiki_write 同步写入 wiki-vault 并返回 kb_url/page_path；**不做仓库预取、不做代码操作**（仓库事实由规格卡/交接注入，预取与执行均不属于你）。
-2. wiki 写仅限 pagePrefix（projects/）下；经 wiki_write 同步返回 kb_url/page_path，complete summary 非空。
-3. 你不是执行者：不做 git/代码/构建/推送、不安装依赖、不写仓库（bash 仅限只读命令如 cat/git show 取仓库事实，不用于预取/代码操作）。
-4. 不得创建任务、不得批准/编辑规格卡；不得越权操作其他任务（只可 complete/block 本任务，会话绑定）。
-5. wiki-vault 不可达时 kanban_block(reason=kb-unreachable) 等人工；绝不放行空 complete。
-6. 使用 kanban_* + wiki_search/wiki_read/wiki_write + spec_card_view（只读）。
+1. 远程 KB 模式：使用 wiki_search/wiki_read/wiki_write；wiki 写仅限 `projects/<repoSlug>/…` 白名单命名空间（repoSlug 由系统按链工作区派生，见任务卡 body 的 KB 页路径规则）；经 wiki_write 返回 kb_url/page_path，complete summary 非空。
+2. 本地 KB 模式：经 skill 工具加载 llm-wiki，对任务上下文给定的本地库根运行 query/ingest/crystallize 工作流（库未初始化时先按 llm-wiki init 工作流初始化，幂等）；交付 page_path = 库根内 wiki/** 相对路径、kb_url = 空串。
+3. KB 检索排序：相关性优先（7），新鲜度次之（3）。
+4. 只读仓库预取（file/external/kb 模式）原样落任务工作区——不压缩、不蒸馏；本地模式 prefetch_kb 不可用：改用 skill 工具 + llm-wiki；本地模式绝不 ingest 外部 URL。
+5. 你不是执行者：不做 git/代码/构建/推送、不安装依赖、不写仓库（bash 仅限只读命令如 cat/git show 取仓库事实）；本地模式唯一可写区 = 本地库根——DIRECT cp/mv/mkdir 工具会被护栏拒绝，库内文件操作一律使用 write 工具（bash cp/mv 在库根内是放行的）。
+6. 不得创建任务、不得批准/编辑规格卡；不得越权操作其他任务（只可 complete/block 本任务，会话绑定）。
+7. KB（任一模式）不可达时 kanban_block(reason=kb-unreachable) 等人工；绝不放行空 complete。
+8. 工具面按模式分支：kanban_* +（远程：wiki_search/wiki_read/wiki_write ｜ 本地：skill）+ prefetch_file/prefetch_external/prefetch_kb + spec_card_view（只读）。

package/skills/grill-me/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: grill-me
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+## Plain language first (hard rule)
+
+- Every question body must be plain language a non-expert can act on. If a term is unavoidable, explain it in one short parenthetical the first time: `term (plain explanation)`.
+- Multiple-choice options are candidate answers, not jargon showcases: their labels and descriptions follow the same rule.
+- The recommended-answer line follows the same rule; technical detail goes in parentheses.
+- Self-check before sending any question: _could someone unfamiliar with this repo answer it directly?_ If not, rewrite it.
+
+## Work in rounds
+
+The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+If this round's answers surface a real risk or a non-blocking concern, append one line at the end of the round:
+
+```
+⚠️ **Risk/Concern**: <what could go wrong or what to watch> — source: <which decision it came from> — mitigation: <idea>
+```
+
+Optional: only when something real surfaced this round. Never invent entries to fill it. Non-blocking concerns are assumptions worth noting, things to observe later, and suggestions — anything that doesn't block progress but deserves attention.
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+## Closing deliverable
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed, and the user confirms you have reached a shared understanding. Do not act on the plan until the user confirms. Once they confirm, produce the closing deliverable:
+
+Write `grill-<topic-slug>-plan.md` to the project root, using this exact template:
+
+```markdown
+# <Topic> 澄清计划清单 — <date>
+
+## 1. 需求澄清清单
+| # | 问题（人话版） | 最终答案/决定 |
+|---|---|---|
+
+## 2. 功能点
+- <feature list distilled from the answers>
+
+## 3. 事实
+- <verified environment/code facts, each with its source file path>
+
+## 4. 风险点
+- <description + source decision + mitigation idea; write 无 if none>
+
+## 5. 非阻塞关注点
+- <assumptions / items to observe / suggestions; write 无 if none>
+```
+
+Then report the file path plus a one-line summary in the conversation. The deliverable captures clarification output only — no implementation steps; planning and implementation belong to a separate flow.

package/skills/llm-wiki-skill/.mise.toml

@@ -0,0 +1,2 @@
+[tools]
+node = "22.19.0"

package/skills/llm-wiki-skill/.nvmrc

@@ -0,0 +1 @@
+22.19.0

package/skills/llm-wiki-skill/AGENTS.md

@@ -0,0 +1,173 @@
+# AGENTS.md
+
+## 🧭 仓库导航（任何人 / AI 进来先读这里）
+
+本仓库是 **llm-wiki monorepo**，含三个区：
+
+| 区 | 位置 | 状态 |
+|---|---|---|
+| **agent 工作台**（开发主线） | `workbench/`（server + web） | 🚧 活跃开发 |
+| **共享图谱引擎** | `packages/graph-engine/` | 🚧 随 agent 演进 |
+| **Skill 形态** | 根目录 `SKILL.md` / `scripts/` / `templates/` / `platforms/` | ❄️ 成熟·维护冻结 |
+
+➡️ **开发 agent 工作台（日常主线）**：先读 [workbench/AGENTS.md](workbench/AGENTS.md) + [workbench/PRODUCT.md](workbench/PRODUCT.md)——当前阶段、ADR、协作规则都在那里。
+
+➡️ **本文件以下内容**：Skill 形态的安装与维护规则，**仅当你在维护 Skill 时才看**（install.sh / SKILL.md / scripts / templates / platforms）。Skill 已功能成熟、进入维护冻结，不再追加新功能。
+
+---
+
+## 🏗️ monorepo 怎么连
+
+```
+workbench/web (React 19, SSE) ──HTTP POST + SSE──▶ workbench/server (Hono + @earendil-works/pi-coding-agent)
+                                                          │
+                                                          ├─ spawn 根目录 scripts/（Skill 已有能力，ADR-16 能力归属）
+                                                          └─ 依赖 @llm-wiki/graph-engine
+packages/graph-engine ──ESM + IIFE 双产物──▶ workbench/web 图谱视图 + Skill 离线 HTML（一个引擎、两个宿主，ADR-21）
+```
+
+- 权威架构图、技术栈与全部 ADR 见 [workbench/PRODUCT.md §3 / §7](workbench/PRODUCT.md)；当前阶段与协作铁律见 [workbench/AGENTS.md](workbench/AGENTS.md)。
+- **三类数据彻底分离**（别写错位置）：知识库 `~/llm-wiki/<name>/`、应用数据 `~/.llm-wiki-agent/`、模型凭证 `~/.pi/agent/auth.json`（pi-agent 管，权限 0600）。应用自己的 `config.json` **绝不存** API key。
+
+## ⚙️ 开发命令速查
+
+npm workspaces，三个包（根 `package.json` 不设 `"type": "module"`——Skill 的 CommonJS 测试要兼容，ESM 声明在各子包；ADR-20）：
+
+| 包 | 路径 | npm 名 |
+|---|---|---|
+| 前端 | `workbench/web` | `@llm-wiki-agent/web` |
+| 后端 | `workbench/server` | `@llm-wiki-agent/server` |
+| 图谱引擎 | `packages/graph-engine` | `@llm-wiki/graph-engine` |
+
+| 操作 | 命令（从仓库根） |
+|---|---|
+| 一行启动（后端 `8787` + 前端 `5180`，strictPort） | `npm run dev` |
+| 全仓类型检查 | `npm run typecheck` |
+| 前端 lint | `npm run lint -w @llm-wiki-agent/web` |
+| 前端单测（unit + dom） | `npm run test -w @llm-wiki-agent/web` |
+| 前端 Paper 视觉回归（playwright） | `npm run visual:paper -w @llm-wiki-agent/web` |
+| 引擎单测 | `npm run test -w @llm-wiki/graph-engine` |
+| 后端单测（server 无聚合 test 脚本，用 node:test） | `node --import tsx --test "workbench/server/src/**/*.test.ts"` |
+
+要点：
+
+- 测试统一用 Node 内置 `node --test`（不是 jest/vitest）。前端 DOM 测试走 jsdom + @testing-library/react，视觉回归用 playwright（仅 dev 依赖，不进运行时）。
+- `web` / `server` 的 `build` 与 `typecheck` 带 `prebuild` / `pretypecheck` 钩子，会**自动先 build `@llm-wiki/graph-engine`**。改了引擎代码后，跑前端/后端的 typecheck 或 build 会自动带上最新引擎产物；单跑引擎自己的 `tsc --noEmit` 不会刷新 `dist/`。
+- Node `>=22.19.0`（pi-coding-agent 硬要求，`.mise.toml` / `.nvmrc` 锁定）。
+
+---
+
+## Skill 形态：安装与维护
+
+这是 llm-wiki 在 Codex 下的入口文件。
+
+先看这三个文件：
+
+- [README.md](README.md)：多平台总说明
+- [platforms/codex/AGENTS.md](platforms/codex/AGENTS.md)：Codex 专属入口提示
+- [SKILL.md](SKILL.md)：核心能力和工作流
+
+## Codex 安装动作
+
+如果当前任务是安装这个 skill，执行：
+
+```bash
+bash install.sh --platform codex
+```
+
+默认安装到 `~/.codex/skills/llm-wiki`。如果用户机器上还是旧的 `~/.Codex/skills`，安装器也会自动兼容。
+
+默认只准备知识库核心主线。如果这次要自动提取网页 / X / 微信公众号 / YouTube / 知乎，再执行：
+
+```bash
+bash install.sh --platform codex --with-optional-adapters
+```
+
+## 重要提醒
+
+- 不要把这个仓库当成 Codex 专属仓库；Claude Code、OpenClaw、Hermes 也共用同一套核心内容
+- 安装完成后，再按 [SKILL.md](SKILL.md) 的工作流继续做事
+- 如果 OpenClaw 使用的是自定义技能目录，可以改用 `--target-dir <你的技能目录>/llm-wiki`
+
+## 分支管理规则
+
+改动代码（非纯文档/注释）时，按以下流程操作：
+
+1. 开新分支：从 main 创建，命名表达用 feat 或 fix 前缀；Codex 环境默认使用 `codex/` 命名空间，例如 `codex/fix-cache-reliability-write-through`
+2. 分步 commit：每完成一个逻辑单元就提交（脚本实现、测试、文档更新分开 commit）
+3. 推送并创建 PR：推到远端后用 `gh pr create` 创建 PR
+4. 合并：确认测试通过后在 GitHub 上合并
+
+不需要开分支的情况：
+
+- 只改了 AGENTS.md、CLAUDE.md、文档、注释
+- 只是探索性阅读代码
+
+设计文档或 plan 写完准备动手改代码时，也先开分支再开始实现。
+
+## 使用顺序
+
+安装完成后，按 [SKILL.md](SKILL.md) 中的工作流继续执行：
+
+1. `init`
+2. `ingest`
+3. `batch-ingest`
+4. `query`
+5. `digest`
+6. `lint`
+7. `status`
+8. `graph`
+
+## 已记录的解决方案
+
+`docs/solutions/` 存放过去解决问题的文档（bug、最佳实践、工作流改进），按类别分目录，每份有 YAML frontmatter（`module`、`tags`、`problem_type`）。涉及已记录领域时（graph、cache、install、lint 等），先搜一下有没有现成经验。
+
+## 推送前测试规则
+
+每次 `git push` 前必须验证，按改动范围选深度：
+
+### 第一层：快速检查（Codex 直接跑，1 分钟内）
+
+不管改了什么都跑这 3 项：
+
+1. `bash install.sh --dry-run --platform codex` — 安装脚本不报错
+2. 改过的脚本如果有 `tests/fixtures/`，跑一下 diff 预期输出
+3. `grep -r '本机用户路径\|真实姓名\|私有素材路径' scripts/ templates/ tests/ SKILL.md` — 没泄露隐私路径
+
+### 第二/三层：工作流测试
+
+- **第二层**（只改了 SKILL.md 里个别工作流）：生成测试提示词写到文件，并用 Codex 跑涉及的工作流
+- **第三层**（多工作流改动 / 版本号升级）：生成全量回归提示词，在 Codex 跑完整流程（init → ingest → lint → digest → graph）
+
+素材复用 `~/Desktop/llm-wiki-cowork-test/raw-input/` 里的 3 篇文章，不用每次重新找。
+
+跑完后生成 `test-report.md`，确认无阻塞问题后才执行 `git push`。
+
+## 推送前文档更新规则
+
+每次 commit 含功能改动（feat/fix）后、`git push` 前，**必须**主动检查并更新以下文档，不需要用户提醒：
+
+1. **CHANGELOG.md**：在顶部加新版本条目（日期、新增/改进/修复分类）
+2. **README.md 功能列表**：新增功能或行为变化时，在"功能"章节补一条
+3. **版本号**：如果改动涉及新功能，在 CHANGELOG 条目里用新版本号（按 v当前+1 递增）
+
+跳过条件：纯文档/排版/注释改动不需要更新。
+
+## Skill routing
+
+当用户请求匹配可用 skill 时，优先使用对应 skill 的工作流。不要直接临时发挥；先打开对应 `SKILL.md`，按里面的流程做。
+
+关键路由规则：
+
+- Product ideas, "is this worth building", brainstorming → 使用 office-hours
+- Bugs, errors, "why is this broken", 500 errors → 使用 investigate
+- Ship, deploy, push, create PR → 使用 ship
+- QA, test the site, find bugs → 使用 qa
+- Code review, check my diff → 使用 review
+- Update docs after shipping → 使用 document-release
+- Weekly retro → 使用 retro
+- Design system, brand → 使用 design-consultation
+- Visual audit, design polish → 使用 design-review
+- Architecture review → 使用 plan-eng-review
+- Save progress, checkpoint, resume → 使用 checkpoint
+- Code quality, health check → 使用 health