flavor-code 1.2.13 → 1.2.15

package/dist/sdk/index.js

@@ -4,7 +4,7 @@ import {
   FlavorRpcServer,
   TraceRecordSchema,
   TraceRecorder
-} from "../chunk-G6Q2Y2A7.js";
+} from "../chunk-BKARQJQZ.js";
 import {
   AgentMessageQueue,
   DockerExecutionEnvironment,
@@ -13,8 +13,8 @@ import {
   WorkspaceCheckpointStore,
   buildDockerInvocation,
   createProductionRuntime
-} from "../chunk-Y5MZDG7I.js";
-import "../chunk-XFCJXRJ2.js";
+} from "../chunk-5TG3E2EJ.js";
+import "../chunk-IG4Z23CL.js";
 import "../chunk-RQTYHUMK.js";
 import "../chunk-S32JRDZK.js";
 

package/dist/session/store.d.ts

@@ -35,6 +35,7 @@ export declare const SessionDocumentSchema: z.ZodObject<{
                 dependencies: z.ZodArray<z.ZodString>;
                 expectedOutputs: z.ZodArray<z.ZodString>;
                 verification: z.ZodArray<z.ZodString>;
+                files: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
         states: z.ZodRecord<z.ZodString, z.ZodEnum<{

package/dist/tools/shell.d.ts

@@ -42,6 +42,19 @@ export interface ShellBackgroundResult extends ShellResult {
 type ShellTool = Omit<ToolDefinition<z.infer<typeof ShellInput>, ShellResult | ShellBackgroundResult>, "execute"> & {
     execute(input: z.infer<typeof ShellInput>, signal: AbortSignal, context?: import("./types.js").ToolContext): Promise<ShellResult | ShellBackgroundResult>;
 };
+/**
+ * Normalize weak model calls that stuff a whole command line into `command`
+ * (e.g. `command: "git log --oneline"`). Splits only when the first token is a
+ * bare command name (no path separators), so explicit paths with spaces —
+ * `command: "C:\\Program Files\\node.exe"` — are left untouched.
+ */
+export declare function normalizeShellCommand(input: {
+    command: string;
+    args: readonly string[];
+}): {
+    command: string;
+    args: string[];
+};
 export declare function createShellTool(workspace: string, options?: ShellToolOptions): ShellTool;
 export declare function executeShell(root: string, input: z.infer<typeof ShellInput>, cancellation: AbortSignal, maxBytes: number, onOutput?: (stream: "stdout" | "stderr", text: string) => void): Promise<ShellResult>;
 export {};

package/dist/ui/commands.d.ts

@@ -1,4 +1,4 @@
-export declare const MVP_COMMANDS: readonly ["model", "init", "config", "login", "permissions", "skills", "plugins", "hooks", "tasks", "finish", "compact", "clear", "help", "exit", "audit", "usage", "loop", "goal", "mcp", "ide", "memory", "remember", "forget", "forget-cold", "checkpoint", "tree", "rewind", "unrevert", "fork", "pals", "chat", "co-work"];
+export declare const MVP_COMMANDS: readonly ["model", "init", "config", "login", "permissions", "skills", "plugins", "hooks", "tasks", "finish", "compact", "clear", "help", "exit", "audit", "usage", "loop", "goal", "evolve", "mcp", "commit", "review", "ide", "memory", "remember", "forget", "forget-cold", "checkpoint", "tree", "rewind", "unrevert", "fork", "pals", "chat", "co-work"];
 export declare const COMMAND_DESCRIPTIONS: Record<(typeof MVP_COMMANDS)[number], string>;
 export type PermissionCommandMode = PermissionMode;
 export type ModelRole = "main" | "subagent";
@@ -63,6 +63,12 @@ export type SlashCommand = {
 } | {
     name: "goal";
     goal: string;
+} | {
+    name: "commit";
+    hint?: string;
+} | {
+    name: "review";
+    focus?: string;
 } | {
     name: "remember";
     type: MemoryType;
@@ -81,10 +87,13 @@ export type SlashCommand = {
     target: string;
     goal: string;
 } | CoWorkSlashCommand | {
-    name: Exclude<(typeof MVP_COMMANDS)[number], "model" | "permissions" | "audit" | "loop" | "goal" | "mcp" | "remember" | "forget" | "checkpoint" | "rewind" | "fork" | "pals" | "chat" | "co-work">;
+    name: Exclude<(typeof MVP_COMMANDS)[number], "model" | "permissions" | "audit" | "loop" | "goal" | "evolve" | "commit" | "review" | "mcp" | "remember" | "forget" | "checkpoint" | "rewind" | "fork" | "pals" | "chat" | "co-work">;
 } | {
     name: "audit";
     toolFilter?: string | undefined;
+} | {
+    name: "evolve";
+    args: string[];
 } | {
     name: "unknown";
     input: string;

package/dist/ui/session.d.ts

@@ -128,6 +128,9 @@ export interface SessionServices {
     hooksStatus(): readonly unknown[];
     tasks(): unknown;
     audit(toolFilter?: string): string | Promise<string>;
+    evolve(args: readonly string[]): string | Promise<string>;
+    gitCommit?(hint: string | undefined, signal: AbortSignal): Promise<string>;
+    gitReview?(focus: string | undefined, signal: AbortSignal): Promise<string>;
     usage(): string | Promise<string>;
     cancelActiveTask(): void | Promise<void>;
     clearContext(): void | Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flavor-code",
-  "version": "1.2.13",
+  "version": "1.2.15",
   "author": "YachuanWzh",
   "type": "module",
   "publishConfig": {

package//346/212/200/346/234/257/346/226/271/346/241/210/346/212/245/345/221/212.md

@@ -1,6 +1,6 @@
 # flavor-code 技术方案报告
 
-> 版本：1.2.9 | 语言：TypeScript | 运行时：Node.js ≥20 | 包管理器：npm
+> 版本：1.2.14 | 语言：TypeScript | 运行时：Node.js ≥20 | 包管理器：npm
 
 ---
 
@@ -139,6 +139,25 @@
   - [38.8 原生 WebSearch 与 WebFetch](#388-原生-websearch-与-webfetch)
   - [38.9 安全边界](#389-安全边界)
   - [38.10 文件地图与验证](#3810-文件地图与验证)
+- [39. 1.2.13 代码图索引（astgraph）与结构化输出强健化](#39-1213-代码图索引astgraph与结构化输出强健化)
+  - [39.1 总体架构](#391-总体架构)
+  - [39.2 索引管道：提取、入库与增量同步](#392-索引管道提取入库与增量同步)
+  - [39.3 存储模型：SQLite + FTS5](#393-存储模型sqlite--fts5)
+  - [39.4 查询语义与工具](#394-查询语义与工具)
+  - [39.5 插件形态与懒加载](#395-插件形态与懒加载)
+  - [39.6 结构化输出强健化](#396-结构化输出强健化)
+  - [39.7 只读工具声明](#397-只读工具声明)
+  - [39.8 安全边界](#398-安全边界)
+  - [39.9 文件地图与验证](#399-文件地图与验证)
+- [40. 1.2.14 自进化闭环（evolve）](#40-1214-自进化闭环evolve)
+  - [40.1 总体架构](#401-总体架构)
+  - [40.2 信号捕获与去重存储](#402-信号捕获与去重存储)
+  - [40.3 建议生成与趋势排序](#403-建议生成与趋势排序)
+  - [40.4 修复插件生命周期](#404-修复插件生命周期)
+  - [40.5 运行评估与自动验证](#405-运行评估与自动验证)
+  - [40.6 配置与命令](#406-配置与命令)
+  - [40.7 安全边界](#407-安全边界)
+  - [40.8 文件地图与验证](#408-文件地图与验证)
 
 ---
 
@@ -255,6 +274,12 @@
 - **原型沙箱预览** — 只监听 `127.0.0.1` 的静态服务器 + 严格 CSP + sandbox iframe，确认设计基线前可安全地交互体验原型；拒绝路径穿越、切换工作区/退出时自动停止
 - 新增 `docs/specs/2026-08-12-e2e-requirement-to-delivery.md` 规范文档及 `tests/d2c/product.test.ts`、`tests/d2c/interaction-review.test.ts`、`tests/desktop/e2e-shell.test.ts`、`tests/desktop/d2c-product-preview.test.ts` 等测试
 
+**1.2.13 新增：**
+
+- **astgraph 代码图索引** — 项目初始化时在 `.flavor/plugins/astgraph/` 安装基于 tree-sitter 的代码图插件，生成 `.flavor/astgraph/index.db`（SQLite + FTS5），提供 `ast_search` / `ast_callers` / `ast_callees` / `ast_impact` / `ast_context` 五个只读工具与 `/ast` 命令定位符号、追踪可达性、计算爆炸半径、装配精确读范围；`FLAVOR.md` 自动生成 Search 章节，PostToolUse 钩子对编辑过的文件做增量同步，详见第 39 章
+- **结构化输出强健化** — 模型以纯文本（含 ```json 代码块）返回 JSON 时自动提取；按 JSON Schema 对字符串形式的数字/布尔字段做类型强制转换后再校验，减少无效的修复模型调用
+- **只读工具声明** — 工具可声明 `readOnly`，只读工具在默认模式与 plan 模式下自动放行，与 Read/Glob/Grep 同等对待
+
 ### 2.2 非目标（明确排除）
 
 - 全局用户画像、云端记忆同步和团队自动同步
@@ -5546,3 +5571,280 @@ npm run typecheck
 npm run vscode:typecheck
 npm run build
 ```
+
+---
+
+## 39. 1.2.13 代码图索引（astgraph）与结构化输出强健化
+
+1.2.13 为 Agent 补上“先看代码图、再读文件”的定位能力：项目初始化时在 `.flavor/plugins/astgraph/` 安装一个基于 tree-sitter 的代码图插件，把工作区的函数、类、方法、接口、类型别名和变量连同调用/导入边建成 `.flavor/astgraph/index.db`（SQLite + FTS5），并提供 `ast_search` / `ast_callers` / `ast_callees` / `ast_impact` / `ast_context` 五个只读工具。模型先用代码图确定改动点与爆炸半径，再按精确行范围读取文件，替代“全仓 grep + 大段读文件”的盲目探索。同批还落地了结构化输出强健化（纯文本 JSON 提取 + 字符串类型强制转换）与只读工具声明（`readOnly` 免审批）。
+
+### 39.1 总体架构
+
+```mermaid
+flowchart LR
+  INIT["initializeFlavor\n项目初始化"] --> COPY["copyAstgraphPlugin\n复制到 .flavor/plugins/astgraph/"]
+  COPY --> SESSION["SessionStart 钩子\n缓存工作区"]
+  COPY --> TOOLS["5 个只读工具\nast_search/ast_callers/ast_callees/ast_impact/ast_context"]
+  COPY --> HOOK["PostToolUse 钩子\n编辑后增量同步"]
+  TOOLS --> DB[".flavor/astgraph/index.db\nSQLite WAL + FTS5"]
+  HOOK --> DB
+  DB --> FLAVOR["FLAVOR.md\n自动生成 Search 章节"]
+```
+
+设计要点：
+
+1. **插件即交付物**：astgraph 以 flavor-code 插件（`flavor-plugin.json` + 运行时 + vendored WASM grammar + zod）的形式随项目初始化复制安装，已存在时不覆盖，与 codeisland 插件同一条分发路径。
+2. **重量级工作全部懒加载**：插件 activation 只注册命令、工具与钩子；WASM grammar 与数据库连接在首次使用时才加载，保证激活不超时。
+3. **编辑即同步**：PostToolUse 钩子从 Edit/Write/ApplyPatch 输入中提取工作区相对路径，仅对变更文件增量重索引，fire-and-forget 语义，绝不阻塞或失败 Agent 的编辑。
+4. **定位优先于阅读**：`FLAVOR.md` 在检测到索引存在时自动生成 Search 章节，引导模型把 `ast_search` 与 `grep`/`glob` 配对使用，用 `ast_impact` 等确定可达性后再决定读哪些行。
+
+### 39.2 索引管道：提取、入库与增量同步
+
+#### 文件发现
+
+`indexer.listCodeFiles` 递归遍历工作区，只收录 tree-sitter 语法支持的文件（`.ts/.tsx/.js/.jsx/.mts/.cts/.mjs/.cjs`），并跳过以下目录（无论深度）：
+
+```text
+node_modules  dist  build  out  coverage  release  .git  .flavor
+.claude  .worktrees  .cache  .idea  .vscode  vendor
+```
+
+#### 结构提取
+
+`extract.mjs` 用 web-tree-sitter 解析每个文件，产出三类记录：
+
+- **nodes** — `function_declaration` / `class_declaration` / `interface_declaration` / `type_alias_declaration` / 词法声明中的 `variable_declarator`（值为函数时按 function 计），类成员 `method_definition` 使用 `ClassName.methodName` 限定名；每个节点携带 1-based 起止行号（与 Read 工具坐标一致）、单行签名、JSDoc/`//` 注释 docstring、`isExported`、`isAsync`
+- **edges** — 文件内调用（`calls`）、继承（`extends` / `implements`），指向本地已声明符号
+- **refs** — 跨文件引用：import 绑定、未解析的调用/继承，先入 `unresolved_refs` 表等待解析
+
+#### 入库与解析
+
+`indexOneFile` 按文件先清旧边/旧引用、`replaceNodes` 替换全部节点（单事务 + FTS 触发器同步），再插入新边/新引用，最后用 SHA-256 内容哈希更新 `files` 记录。全量/增量 pass 结束后执行 `resolvePass`：把 `module_specifier` 指向已索引文件的 pending 引用解析成具体边——import 语句本身不属于任何函数，会归属到同文件中真正使用该绑定的节点；未使用的 import 静默解析为空。
+
+#### 增量同步
+
+- 全量构建：`/ast init` 或首次工具调用前的 `indexProject(root)`，遍历全部代码文件
+- 增量构建：`/ast sync [path...]` 与 PostToolUse 钩子，只对指定路径重索引；磁盘上已删除的文件仍会被裁剪
+- 内容哈希相同即跳过，避免重复解析
+
+### 39.3 存储模型：SQLite + FTS5
+
+数据库使用 Node 内置 `node:sqlite` 的 `DatabaseSync`，打开时设置 WAL 日志模式（并发读者不阻塞写者）、外键约束与 `synchronous = NORMAL`：
+
+| 表 | 作用 |
+|----|------|
+| `files` | 路径、内容哈希、语言、大小、节点数（增量检测依据） |
+| `nodes` | 节点 id（`src/order.ts#cancelOrder`）、kind、name、qualified_name、文件、语言、起止行、签名、docstring、exported/async 标记 |
+| `edges` | `source → target` 调用/导入/继承边，带行列；`(source, target, kind, line, col)` 唯一索引去重 |
+| `unresolved_refs` | 待解析的跨文件引用（`pending` 状态），解析成功后删除 |
+| `nodes_fts` | FTS5 虚拟表，`content='nodes'` + 触发器维护，覆盖 name / qualified_name / signature / docstring |
+| `project_metadata` | 最近索引时间戳等 provenance 元数据 |
+
+边与引用通过外键级联删除；`schema_versions` 记录初始 schema 版本以便未来迁移。
+
+### 39.4 查询语义与工具
+
+五个工具全部声明 `readOnly: true`，输入 Schema 的数字字段用 `z.coerce` 接受字符串形式（`"10"` 而非 `10`）：
+
+| 工具 | 语义 | 关键参数 |
+|------|------|----------|
+| `ast_search` | 锚点搜索：先 FTS5 前缀匹配，再用 camelCase/snake_case 标识符分段匹配（`order cancel` 可命中 `cancelOrder`），按分数排序 | `query`；`limit` 1–50（默认 10） |
+| `ast_callers` | 谁调用/导入了该节点（反向边，kind ∈ calls/imports） | `id` |
+| `ast_callees` | 该节点调用了谁（正向边） | `id` |
+| `ast_impact` | K-hop 爆炸半径：`up`=谁依赖我、`down`=我依赖谁、`both`=并集，按 hop 排序 | `id`；`hops` 1–5（默认 2）；`direction`（默认 up） |
+| `ast_context` | 锚点 + K-hop 双方向可达子图，装配为精确 `file:start-end` 读范围清单 | `id`；`hops` 1–3（默认 1） |
+
+CLI 侧对应 `/ast` 命令：`/ast init | sync | status | search <query> | callers/callees/impact/context <node-id> [--hops N] [--direction up|down|both]`。未知节点 id 会提示先用 `ast_search` 找锚点；索引未构建时返回 `"astgraph index not built"` 引导先执行 `/ast init`。
+
+### 39.5 插件形态与懒加载
+
+- `src/init/astgraph/flavor-plugin.json`：`apiVersion: 1`，声明 1 个命令、5 个工具、SessionStart 与 PostToolUse 两个钩子，`permissions: []`
+- `index.js` 的 `activate(context)` 只注册 handler；`grammars.mjs` 通过 `import.meta.url` 解析 vendor 目录，使其在源码树（`src/init/astgraph`）与复制后的插件根（`.flavor/plugins/astgraph`）下都能工作
+- WASM grammar（typescript / tsx / javascript）与 `tree-sitter.js` 运行时按语言缓存，首次使用时加载一次
+- `PluginHost.registerCommand` 支持可选 description 参数，命令注册语义向后兼容
+
+### 39.6 结构化输出强健化
+
+`src/models/structured.ts` 新增两个能力，减少“模型输出了可修复的数据却仍被送去修复调用”的浪费：
+
+1. **纯文本 JSON 提取**（`extractJsonObject`）：部分 provider 用纯文本（含 ```json 围栏或嵌在 prose 中）而不是工具调用返回 JSON。`withStructuredOutput` 在未收到工具调用但收到文本时提取第一个可解析的 JSON 对象/数组作为候选，纳入既有校验重试管道。
+2. **字符串类型强制转换**（`coerceByJsonSchema`）：按 JSON Schema 递归把字符串形式的数字/布尔字段转成真实类型（`"10"` → `10`、`"true"` → `true`），再做 schema 校验；`AgentLoop` 对标记为 `valid` 的工具调用同样先按 `strictJsonSchema` 强制转换并复验，能过才继续，否则才走修复模型调用。可选字段在 strict schema 中统一展开为 `anyOf [T, null]` 且 `additionalProperties: false`，提升 provider 的服从性。
+
+修复提示词仍携带原始无效输出、最近候选与校验错误，但触发条件明显收窄。
+
+### 39.7 只读工具声明
+
+- `ToolDefinition` 新增 `readOnly?: boolean`：声明后与 Read/Glob/Grep 同等对待
+- `PermissionEngine` 在默认模式、plan 模式与 d2c profile 下对 `request.readOnly === true` 直接放行，无需用户审批；`ToolRuntime` 构造权限请求时透传该标记
+- 规划模式仍保持只读语义：只读工具可执行，写工具照旧拒绝
+
+### 39.8 安全边界
+
+| 层面 | 措施 |
+|------|------|
+| 索引范围 | 固定排除依赖/产物/元数据目录（node_modules、dist、.git、.flavor 等），不索引工作区外的任何路径 |
+| 插件分发 | 复制安装沿用 codeisland 模式：目标已存在即跳过，不覆盖用户修改；插件目录权限 `0o700` |
+| 增量同步 | PostToolUse 钩子只接受 Edit/Write/ApplyPatch 输入中解析出的相对路径，fire-and-forget，失败仅记 debug 日志 |
+| 工具权限 | 五个 AST 工具声明 `readOnly`，只读放行但不持有任何写路径；`z.coerce` 仅做类型标准化，不改变校验边界 |
+| 运行时隔离 | grammar 全部 vendored 本地 WASM，无网络请求；数据库仅本工作区 `.flavor/astgraph/` 内 |
+
+### 39.9 文件地图与验证
+
+| 路径 | 职责 |
+|------|------|
+| `src/init/astgraph/index.js` | 插件入口：`/ast` 命令、5 个工具、SessionStart/PostToolUse 钩子、增量同步调度 |
+| `src/init/astgraph/extract.mjs` | tree-sitter 结构提取：nodes/edges/refs、docstring、签名、限定名 |
+| `src/init/astgraph/indexer.mjs` | 全量/增量索引、内容哈希跳过、文件裁剪、resolvePass 调度 |
+| `src/init/astgraph/db.mjs` | `node:sqlite` WAL 数据库、schema、FTS5 触发器、统计与元数据 |
+| `src/init/astgraph/query.mjs` | FTS5 + 标识符分段搜索、callers/callees、K-hop impact、子图读范围装配 |
+| `src/init/astgraph/resolve.mjs` | 模块说明符解析（`.js`→`.ts` 重定向、扩展名/`index` 候选）与引用→边 |
+| `src/init/astgraph/grammars.mjs` | WASM grammar 加载与语言缓存 |
+| `src/init/astgraph/vendor/` | vendored tree-sitter 运行时、三种语言 grammar、zod |
+| `src/init/project.ts` | `copyAstgraphPlugin`、`hasCodeGraph` 探测、FLAVOR.md Search 章节生成 |
+| `src/models/structured.ts` / `src/agent/loop.ts` | 纯文本 JSON 提取、字符串类型强制转换、strict schema |
+| `src/permissions/engine.ts` / `src/tools/runtime.ts` / `src/tools/types.ts` | `readOnly` 声明、放行逻辑与权限请求透传 |
+
+对应测试位于 `tests/plugins/astgraph/{db,extract,indexer,plugin,query,resolve}.test.mjs`、`tests/init/astgraph-copy.test.ts`、`tests/init/project.test.ts`、`tests/models/structured.test.ts`、`tests/permissions/engine.test.ts` 与 `tests/ui/slash-completion.test.ts`。
+
+---
+
+## 40. 1.2.14 自进化闭环（evolve）
+
+1.2.14 引入内置的**有界自进化闭环**（evolve）：Agent 在日常运行中捕获重复的工具失败信号，把它们聚合、去重后以建议形式注入系统提示词，由模型自行判断是否值得修；修复以 flavor-code 插件的形式落地（`fix-<tool>/`），必须先通过影子沙箱干跑与完整测试套件两道门禁，才允许热重载进运行中的宿主。循环永不完全自治：建议只是提案，任何修改仍走普通工具循环与权限系统，用户可以随时用 `/evolve` 查看、验证、回滚或关闭。
+
+### 40.1 总体架构
+
+```mermaid
+flowchart LR
+  CAPTURE["1. CAPTURE\nPostToolUseFailure + Shell 非零退出旁路"] --> STORE[".flavor/evolve/\nsignals.jsonl 指纹去重聚合"]
+  STORE --> ASSESS["2. ASSESS\n重复 >= minRepeats 建议注入系统提示词"]
+  ASSESS --> MODIFY["3. MODIFY\nevolve_improve / /evolve improve\n脚手架 fix-<tool>/ 插件 + PLAN.md"]
+  MODIFY --> VERIFY["4. VERIFY\n影子沙箱干跑 → 测试套件 → 热重载"]
+  VERIFY --> REPEAT["5. REPEAT\nendRun 写 reflection\nsignalDelta / perTool 趋势"]
+  REPEAT --> CAPTURE
+```
+
+循环分五步：
+
+1. **CAPTURE**：`PostToolUseFailure` 记录工具失败；Shell 工具对命令失败刻意返回结果而非抛异常，因此从 `PostToolUse` 输出旁路捕获非零退出与超时（用户取消除外）。
+2. **ASSESS**：同一失败重复 ≥ `minRepeats` 次后，按趋势排序取前 `promptTop` 条注入系统提示词；模型决定是否值得修、修什么。
+3. **MODIFY**：模型侧 `evolve_improve` 工具或人工侧 `/evolve improve <id>` 脚手架 `fix-<tool>/` 插件目录并写入 PLAN.md；实现本身（Write/Edit + reload）走普通工具循环。
+4. **VERIFY**：`/evolve verify` 在影子 PluginHost 沙箱中干跑；`/evolve test` 运行测试套件；`/evolve reload` 热重载；`/evolve revert` 回滚到最近良好快照。
+5. **REPEAT**：每次 loop 运行结束追加一条 reflection，记录 `signalDelta` 与按工具维度的 `perTool` 趋势，使“修复是否真的减少了失败”跨运行可度量。
+
+### 40.2 信号捕获与去重存储
+
+`EvolveStore` 将全部状态持久化在 `<workspace>/.flavor/evolve/`：
+
+| 文件 | 内容 |
+|------|------|
+| `signals.jsonl` | 聚合后的工具失败信号（按指纹去重，上限 400 条，超出丢最旧） |
+| `reflections.jsonl` | 每次 agent 运行（loop 结束）一行评估记录 |
+| `done.json` / `verified.json` | 建议的已处理 / 已自动验证标记 |
+
+捕获来源：
+
+- **`PostToolUseFailure`**：工具抛错、校验失败、权限拒绝等真实失败；
+- **`PostToolUse` Shell 旁路**：Shell 工具对 `exit ≠ 0` 或超时返回结果对象而非异常，从不触发失败事件。evolve 从输出中识别非零退出与 `timeout`（`cancelled` 不计），错误码记为 `shell_exit_<code>` / `shell_exit_timeout`，与工具失败信号同一去重管线；
+- **`AfterModelCall`**：统计每轮模型调用次数。
+
+去重与隐私：
+
+- 按 `(tool, errorCode, 规范化错误)` 三元组计算 SHA-1 指纹（前 12 位）；重复失败只 bump `count` 与 `lastAt`，不无限增长；
+- `normalizeError` 折叠空白、把双引号/反引号包裹的值替换为 `"…"` 占位符、截断 160 字符，敏感细节不落盘；
+- 参数只记录键名（`argKeys`，最多 12 个），**绝不记录值**；
+- 目录权限 `0700`，文件权限 `0600`；文件写入经串行队列，避免钩子并发互踩。
+
+### 40.3 建议生成与趋势排序
+
+- 同一失败重复 ≥ `minRepeats`（默认 2）次即成为候选建议；
+- 系统提示词在末尾追加 `# self-improvement suggestions (evolve)` 段，最多 `promptTop`（默认 3）条，只含 id、工具与一行提示；
+- 排序按趋势：恶化（delta > 0）优先于稳定（delta = 0），稳定优先于改善（delta < 0）；同趋势下重复次数多者优先；
+- 某信号首次达到重复阈值时，通过 notice 向用户提示一次（指向 `/evolve suggest`），不会反复打扰；
+- `/evolve suggest` 列出全部开放建议与修复思路；`/evolve`（无参数）显示状态概览（信号数 / 开放建议 / 已验证 / 总失败数 / 最近信号）。
+
+### 40.4 修复插件生命周期
+
+`fixPluginDir = .flavor/plugins/fix-<tool>/`，快照目录 `.flavor/plugins/.versions/fix-<tool>/<timestamp>/`。
+
+1. **脚手架**：`evolve_improve` 或 `/evolve improve <id>` 生成 `flavor-plugin.json`（apiVersion "1"）+ `index.js` 模板 + `PLAN.md`；幂等，已存在绝不覆盖 Agent 已写内容；
+2. **沙箱验证**：`/evolve verify <name>` 把插件复制到临时目录，用影子 `PluginHost` 加载，检查 activation、`contributes` 声明与实际注册的一致性及诊断信息，不触碰真实宿主的 hooks/tools/commands；通过后自动写入快照；
+3. **热重载**：`/evolve reload <name>` 调用 `PluginHost.reload`——先卸载旧实例、重新发现并激活当前版本；入口 import 附加 `&v=${Date.now()}` 查询参数，绕过 Node ESM 模块缓存，保证取到磁盘最新代码；
+4. **测试门禁**：`/evolve test` 运行配置的测试命令（默认 `npm test`，120s 超时，超时杀进程）；
+5. **回滚**：`/evolve revert <name>` 从 `.versions/` 恢复最后一份良好快照；
+6. **关闭**：`/evolve done <id>` 将建议标记为已处理，不再提议。
+
+### 40.5 运行评估与自动验证
+
+- loop 运行前 `beginRun` 重置每轮计数器（modelCalls / toolCalls / toolErrors / runToolErrors）；
+- 运行结束 `endRun` 追加 reflection：`iterations`、`toolCalls`、`toolErrors`、`steers`、`totalFailures`（历史累计失败数）、`signalDelta`（相对上次 reflection 的失败总数变化，负值 = 修复生效）、`failedTools`、`perTool`（每工具当次失败数与 delta）；
+- **自动验证闭环**：某工具 delta < 0 时，其开放建议自动标记 `verified` 不再提议；某工具 delta > 0（再次恶化）时，已验证的建议重新开放并标注 `worsening`——意味着旧修复可能失效，应重做或回滚；
+- 运行结束输出一行用户摘要（工具错误数、失败总数 `前→后 (delta)`、逐工具 `improved/worsening` 与“建议自动验证/重开”标注）；无错误时仅一行静默摘要；
+- 同时广播 `LoopEnd` hook 事件（status / iterations / toolCalls / toolErrors / totalFailures / signalDelta），插件可订阅。
+
+### 40.6 配置与命令
+
+`flavor.json` 新增 `evolve` 配置段：
+
+```json
+{
+  "evolve": {
+    "promptTop": 3,
+    "minRepeats": 2,
+    "testCommand": "npm test",
+    "testTimeoutMs": 120000
+  }
+}
+```
+
+| 字段 | 范围 | 默认 | 含义 |
+|------|------|------|------|
+| `promptTop` | 1–10 | 3 | 注入系统提示词的建议条数 |
+| `minRepeats` | 2–100 | 2 | 同一失败重复多少次才成为建议 |
+| `testCommand` | — | `npm test` | `/evolve test` 使用的测试命令 |
+| `testTimeoutMs` | 1,000–600,000 | 120,000 | 测试命令超时 |
+
+命令族：
+
+```text
+/evolve                         状态概览
+/evolve signals                 最近失败信号
+/evolve suggest                 聚合重复失败为建议（趋势排序）
+/evolve improve <id>            脚手架 fix 插件 + PLAN.md
+/evolve verify <name>           影子沙箱干跑（通过后自动快照）
+/evolve reload <name>           热重载进运行中宿主
+/evolve test                    运行测试套件
+/evolve revert <name>           恢复最后良好快照
+/evolve done <id>               关闭建议
+/evolve verified                已自动验证的建议
+/evolve clear                   重置信号与标记
+```
+
+模型侧对应 `evolve_improve` 工具（输入 `suggestionId` + `implementation`），在系统提示词出现建议时由模型自行调用。
+
+### 40.7 安全边界
+
+| 层面 | 措施 |
+|------|------|
+| 修改有界 | 建议只是系统提示词中的提案；实现走普通工具循环，Write/Edit 与 Shell 照旧经过权限引擎 |
+| 验证门禁 | 激活前必须通过影子沙箱干跑与测试套件；`verify` 在临时目录的影子 PluginHost 中执行，不触碰真实宿主的 hooks/tools/commands |
+| 可回滚 | 每次 `improve`/`verify` 后自动快照到 `.flavor/plugins/.versions/`，`revert` 恢复最后良好快照 |
+| 隐私 | 信号只存规范化错误与参数键名，值、密钥、Token 不落盘；文件 `0600`、目录 `0700` |
+| 存储有界 | 信号上限 400 条自动淘汰最旧；reflection 追加式、不重写历史 |
+| 资源防护 | 测试命令默认 120s 超时，超时强杀子进程；捕获钩子失败只记 warn，绝不影响主循环 |
+
+### 40.8 文件地图与验证
+
+| 路径 | 职责 |
+|------|------|
+| `src/evolve/service.ts` | 循环编排：捕获钩子、提示词段缓存、命令处理、`evolve_improve` 工具、reflection 与自动验证 |
+| `src/evolve/store.ts` | `signals.jsonl` / `reflections.jsonl` / `done.json` / `verified.json` 持久化、指纹去重、趋势聚合 |
+| `src/evolve/loader.ts` | fix 插件脚手架、影子沙箱验证、快照与回滚 |
+| `src/plugins/host.ts` | `PluginHost.reload` 热重载；import 时间戳查询参数破除 ESM 缓存 |
+| `src/hooks/types.ts` | 新增 `LoopEnd` hook 事件 |
+| `src/config/schema.ts` | `evolve` 配置段（promptTop / minRepeats / testCommand / testTimeoutMs） |
+| `src/production.ts` | 运行时集成：service 创建、`evolve_improve` 注册、system 段注入、`beginRun`/`endRun` 挂接、dispose |
+| `src/ui/commands.ts` / `src/ui/session.ts` | `/evolve` 命令解析、帮助与分发 |
+| `src/tools/shell.ts` | 弱类型模型命令分词（整行命令拆为 command + args），保证 Shell 失败旁路在 Windows 下稳定 |
+
+对应测试位于 `tests/evolve/{store,service,loader}.test.ts`、`tests/plugins/host.test.ts`、`tests/tools/shell.test.ts`、`tests/cli/commands.test.ts`、`tests/cli/session.test.ts` 与 `tests/config/load.test.ts`。