kill136 · kill136 · Jun 1, 2026 · May 22, 2026 · May 22, 2026 · May 22, 2026
diff --git a/AXON.md b/AXON.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,7 +1,17 @@
+# CLAUDE.md
 
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## Project Overview
 
+**axon = Manus 复刻 + 编程护城河**（北极星 — 所有产品/架构决策的根）：
+- 形态完全对齐 Manus（三栏 workbench、12 种内建 mode chip、blueprint 卡片对话流、tldraw 画布、image preview panel）
+- 差异化护城河 = 真实编程能力（slides/website/desktop-app 等 mode 必须用真实代码工程交付，不只是文本/截图）
+- Manus 用 E2B Firecracker microVM 做沙盒，axon **不抄**（用本地 VFS + Sandpack 替代）
+- LLM 路由：当前唯一可用 backend = axon-cloud GPT 5.5（codex-client.ts），不是 Claude
+
+**Milestone 命名**：项目 refactor 用 `F<阶段>.<子任务>` 或 `M<阶段>.<子任务>` 命名（如 F5.b / M2.a / M4.b）。提交/记忆/对话都用这个 ID 引用历史决策。
+
 ## 铁律（每条都是硬性约束，没有例外）
 
 ### 铁律1：先读后改，无一例外
@@ -81,6 +91,20 @@ npm run test:watch          # Watch mode
 npm run test:ui             # Vitest UI
 ```
 
+### Evals（铁律 11：agent 评估大于一切）
+
+端到端 eval 系统在 `evals/`，跑真实 WebSocket → ConversationLoop → LLM 链路：
+
+- 入口：`evals/cli.ts`（`npx tsx evals/cli.ts <suite-name>`）
+- Suite：`evals/suites/<name>/{cases.ts, harness.ts}` — case 含 prompt + contract，harness 起 ws client 喂消息收事件做断言
+- Contracts：`noContextPollution` / `expectAssistantNotEmpty` / `expectAnyKeyword` / `expectToolCalled` / `combine`
+- **vision 回归门一条命令**：`npx tsx evals/regression.ts`（默认跑 prompt-refactor + m5-m9 + m10-jsx/picker 共 8 套 + 汇总表对照基线；`--with-e2e` 加端到端长流程）。基线：prompt-refactor 5/5 · m5 10/10 · m6 6/6+skip · m7 3/3+skip · m8 5/5 · m9 1/1 · m10-jsx 3/3 · m10-picker 1/1（2026-05-25 实跑校准；m8 5/5 含 V2 第 5 case m8-harness-truth-negative）。**m8 是最重 suite，codex 负载下 agent 易没走完多轮流程假挂，批量 miss 必隔离单跑 `evals/suites/m8-deliver/run.ts` 确认 flaky vs 真退步**。
+- 单套：`AXON_EVAL_DEBUG=1 npx tsx evals/suites/<name>/run.ts`（m6/m7/m8/m9 各自 run.ts）。老 suite 走 `evals/cli.ts <smoke|curated|...>`。
+- 跑前必须有本地 axon-web 跑在 :3456（建议 `AXON_EVAL_DEBUG=1 ... tsx src/web-cli.ts &`；m8/e2e 加 `AXON_E2E_MAX_MS=20000` 压 e2e 上限）。
+- **flaky**：codex 负载下重型多轮 case 易超时假挂 → `runSmokeCase` 已内置「超时+失败」自愈重试一次；批量仍假挂的隔离复跑确认（[[feedback_never_kill_by_port_range]] 同 session 的 flaky roulette 教训）。
+
+每次改 prompt/conversation/tool loop 后**必须**跑回归门、确认无真退步才能 commit。
+
 ### Running the Web UI
 
 ```bash
@@ -124,6 +148,7 @@ All tools extend `BaseTool`, define input schema with Zod, implement `execute()`
 | Perception | Eye (camera), Ear (microphone) |
 | Integration | MCP, Skills, CreateTool, SelfEvolve, Schedule |
 | Structured | StructuredOutput, SubmitReview |
+| Coding Pipeline (M5-M9) | enter/exit_coding_mode, propose_coding_spec, generate_coding_blueprint, verify_task, run_blueprint_tests, verify_against_spec, deliver_app, request_user_action（详见下文 Coding Agent Pipeline；多为 marker 工具，真逻辑在 conversation.ts 拦截）|
 
 ### Key Data Flow
 
@@ -143,6 +168,51 @@ Full-stack web application:
 - **Client** (`src/web/client/`) - React SPA with Monaco Editor, file tree, multi-tab editing, checkpoint/rewind, blueprint console, activity dashboard
 - **Shared** (`src/web/shared/`) - Shared types and utilities
 
+### Prompt 子系统（M2.a/M4 重构后）
+
+老路径 `src/prompt/`（SystemPromptBuilder + 40+ 字段 PromptContext + 6-15K tokens 注入）已**整体删除**（`src/prompt/` 目录已不存在，仅余各新文件注释里的历史引用），由三路替代：
+
+| 调用方 | 新构造器 | 说明 |
+|---|---|---|
+| Web 主对话 | `src/web/server/manus-prompt.ts` (`buildManusSystemPrompt`) | M2.a 落地，对齐 Manus 极简风，~3 静态段 + mode extra + 动态 env，<10ms 构造 |
+| Sub-agent (Task/Explore/...) | `src/tools/agent-prompts.ts` (5 个常量) | `GENERAL_PURPOSE_AGENT_PROMPT` / `EXPLORE_AGENT_PROMPT` / `CODE_ANALYZER_PROMPT` / `BLUEPRINT_WORKER_PROMPT` / `WEBSITE_BUILDER_PROMPT`。agent.ts 通过 `options.systemPrompt` 直传字符串 |
+| Loop fallback (schedule/未传 systemPrompt) | `src/core/loop-prompt.ts` (`buildLoopSystemPrompt`) | M4.b，identity + tool discipline + hostedTools + env，同步 <1ms |
+
+**M4 状态（已完结）**：`src/prompt/` 整段已删除 —— 5 sub-agent prompts 搬到 `agent-prompts.ts`，`PromptBlock` 类型内联进 `manus-prompt.ts`，loop fallback 走 `loop-prompt.ts`。改动 prompt 走上面三个新文件，**不存在也不要新建 `src/prompt/`**。
+
+### Mode Chip 系统（axon-web 主对话核心）
+
+12 种内建 mode 对齐 Manus 1.6 Lite，前后端硬编码镜像：
+
+- 配置源：`src/web/server/modeRegistry.ts` — 每 mode 含 `systemPromptExtra` 追加到 system prompt 末尾 + 可选 `toolFilter`（目前仅 `chat` mode 禁所有工具）
+- 前端 chip：`src/web/client/src/pages/ManusWorkbench/ChatPane.tsx` — `PINNED_CHIPS`(4) + `POPOVER_CHIPS`(9)，每 chip 的 `id` 对齐 modeRegistry mode id
+- 消息协议：前端发 `message_start { payload: { content, mode } }` → WebSocket handler 调 `conversationManager.setSessionMode(sessionId, mode)` → manus-prompt.ts 把 `modeCfg.systemPromptExtra` 拼到 prompt 末尾
+- 12 个 mode：`slides` / `website` / `desktop-app` / `design` / `video` / `app` / `schedule`(axon 加) / `wide-research` / `spreadsheet` / `visualization` / `audio` / `chat`(axon 加)
+- mode 决定**产品形态**而不只是 prompt：`website` mode LLM 第一调用 `propose_website_builder` blueprint 卡片，确认后才走 `apply_webpage_edits` 真改文件
+
+### Coding Agent Pipeline（M5-M9 — vision 五层，2026-05-24 全落地）
+
+北极星 vision（[docs/spec/vision.md](docs/spec/vision.md) + 各层 `docs/spec/roadmap/M{5..9}-overview.md`）的「编程护城河」流水线。普通任务走 base agent；编程任务自动升级到受 spec 约束的 coding agent，流程化交付**可运行**的工程。五层：
+
+| 层 | 能力 | 关键工具 / 产物 | eval suite |
+|---|---|---|---|
+| L1 (M5) | 识别编程任务 → 升级 coding agent | `enter_coding_mode`/`exit_coding_mode`（翻 `state.mode='coding'`）| `evals/suites/m5-coding-agent` 10/10 |
+| L2 (M6) | spec 引导卡片 + 硬契约 | `propose_coding_spec` → `<cwd>/spec.json`（每轮注入）| `m6-spec-card` |
+| L3.a/b (M7) | 蓝图生成 + 串行执行 + 严格门 | `generate_coding_blueprint`/`verify_task` → `blueprint.json`（task 状态机）| `m7-blueprint` |
+| L3.c/d/e (M8) | 测试 + 评估 + 交付 | `run_blueprint_tests`/`verify_against_spec`/`deliver_app` → `test-report.json`/`acceptance.json`/`delivery.json` | `m8-deliver` 5/5 |
+| L4 (M9) | user-in-the-loop 卡点协作 | `request_user_action`（前端金色 inline 状态条）| `m9-collab` |
+
+**真闭环实证**：`evals/suites/e2e-full-flow` —— coding agent 自主把一个真实 Express TODO API 跑通全 5 层（spec→蓝图→执行→测试→验收 100%→交付），1/1 PASS。
+
+**核心架构范式（改这套时必懂）**：
+- **marker 工具 + conversation.ts 拦截**：上述 coding 工具几乎都是**纯 marker**（`BaseTool.execute(input)` 拿不到 sessionId/session — base.ts:83）。真逻辑（翻 mode / 落盘 spec/blueprint / 跑 typecheck / 双门交付）在 `conversation.ts` 的 tool-result 循环里**按 `toolUse.name` 拦截**（那里有 `state` + `sessionId` + `cwd`）。**拦截一律按 `toolUse.name` + `toolUse.input`，别碰 `result.data`**（`executeToolWithCancellation` 不保真 data —— M7 踩过坑）。
+- **结构化硬门 > prompt 祈祷**：实测「应该先做 X」纯 prompt 只 ~50% 遵守率。所以硬约束都**代码强制**：M6.f `getFilteredTools` 在无 spec 时物理屏蔽 Write/Edit；M7 `verify_task` server 真跑 typecheck 绿才置 task done；M8 `deliver_app` 双硬门（测试绿 + 验收 100%）物理屏蔽。门由 server 确定性裁决，不信 LLM 口头。
+- **AI-native 不过度工程化（铁律2）**：拆解/验收评分让 LLM 自己产出当工具入参（agent 本就是 LLM），server 只做确定性校验/落盘。M7 实测**否决了复用 SmartPlanner**（强耦合 + parallelGroups + 多一次 LLM 调用）。
+- coding identity 在 `manus-prompt.ts` 的 `CODING_AGENT_IDENTITY`（`mode==='coding'` 时替换 base identity）；spec/blueprint/进度每轮注入动态块。
+- `modeRegistry.ts` 的 `coding` mode 黑名单屏蔽非编程工具，但**保留 web_search + Browser**（编程护城河）。
+
+**eval 自愈**：`runSmokeCase`（m5 harness）对「某轮命中超时 deadline 且契约未过」的 stall 假挂自动重试一次（codex 负载下重型多轮 case 易超时，根治 flaky roulette）。
+
 ### Multi-Agent System
 
 - **Blueprint** (`src/blueprint/`) - Task decomposition into execution graphs, planner, lead agent, autonomous workers