flavor-code 1.4.4-beta.2 → 1.4.5-beta.2

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.4.3-beta.2 | 语言：TypeScript | 运行时：Node.js ≥20 | 包管理器：npm
+> 版本：1.4.5-beta.2 | 语言：TypeScript | 运行时：Node.js ≥20 | 包管理器：npm
 
 ---
 
@@ -167,6 +167,7 @@
 - [47. 1.4.1 至 1.4.2 终端交互与输出呈现升级](#47-141-至-142-终端交互与输出呈现升级)
 - [48. 1.4.3 内置浏览器（Browser）](#48-143-内置浏览器browser)
 - [49. 无头 CLI、命令行子命令族与 Prompt Cache 增强](#49-无头-cli命令行子命令族与-prompt-cache-增强)
+- [50. 1.4.5-beta.1 可评价的自进化试运行](#50-145-beta1-可评价的自进化试运行)
 
 ---
 
@@ -1052,7 +1053,8 @@ flowchart TD
     C -->|是| D["Cheap 模型提取、分类并四维评分"]
     D --> E{"宿主阈值和安全规则通过？"}
     E -->|否| Z
-    E -->|是| F["CLI / Electron 向用户展示候选"]
+    E -->|项目 / 引用| F["进入持久审核队列"]
+    E -->|偏好 / 反馈| P["按用户证据进入偏好演化；证据不足则待审核"]
     F -->|忽略| Z
     F -->|接受| G["宿主用 n-gram / Jaccard 最终查重"]
     G -->|已有同类记忆| H["不重复追加"]
@@ -1064,8 +1066,8 @@ flowchart TD
 这个闭环把成本和风险放在三个逐级变窄的闸门后面：
 
 - **长度闸门完全本地执行。** 200 字符以下不调用模型，短问答没有额外 token。
-- **质量闸门只调用 cheap/subagent 模型一次。** 模型负责提出和评分最重要的一条候选，宿主负责按固定阈值裁决并把解析和审阅容量都硬限制为 1，模型不能用一个 `worthRemembering: true` 绕过规则。
-- **隐式候选的写入闸门掌握在用户手里。** 自动评价或 `/finish` 的模型输出先停在内存中的审阅队列，用户接受后才会触碰长期存储；最终查重还会再次拦住重复项。
+- **质量闸门只调用 cheap/subagent 模型一次。** 模型负责提出和评分最重要的一条候选，宿主按固定阈值筛选；每次最多提出 1 条，持久审核队列最多容纳 20 条。模型不能用一个 `worthRemembering: true` 绕过规则。
+- **项目约定和外部引用的写入闸门掌握在用户手里。** 自动评价或 `/finish` 的候选先进入持久审核队列；用户接受后才会写入长期存储，最终查重还会再次拦住重复项。用户偏好和行为反馈进入独立的证据评价流程。
 
 ##### 显式“记住”快捷路径
 
@@ -1086,7 +1088,7 @@ flowchart LR
 
 memory task ID、当前任务的消息起点、完成状态和对话哈希一起保存到 session。自动评价后再对同一份对话点击“完成任务”不会再次调用模型；完成后在同一会话开始新的普通任务会生成新的 memory task ID，并记录新的消息边界，因此第二项任务不会重新评价第一项任务的对话，正文归档和召回计数也不会混在一起。
 
-项目配置 `language` 后，提取提示要求候选的摘要、正文和关键词使用对应 BCP 47 语言，同时保留代码标识符、命令、路径、URL 和专有名称。待确认候选不跨 query 保留：用户直接发送新的普通 query 时，`MemoryReviewBridge` 在模型处理前整批清空旧候选并发布状态变化，因此 CLI 和 Electron 都会立即隐藏旧授权，旧 review ID 也不能再保存。
+项目配置 `language` 后，提取提示要求候选的摘要、正文和关键词使用对应 BCP 47 语言，同时保留代码标识符、命令、路径、URL 和专有名称。待确认候选写入 `.flavor/memory/review-inbox.json`，发送下一条 query 或重启都不会清空；默认不自动过期。队列满 20 条时暂停新的自动提取，直到用户保存或忽略一条。
 
 只有长度短路或 cheap 模型成功返回并完成宿主校验，才会把这份 hash 标为已评价。模型暂时离线、返回损坏 JSON 或审阅桥接失败时，任务不会被误标为完成，用户修复问题后可以再次 `/finish`。
 
@@ -1244,7 +1246,7 @@ authority >= 2
 
 Electron 桌面端在任务头部提供“完成任务”按钮。评分通过后，候选出现在右侧非阻塞审阅栏，用户可以继续阅读当前结果，再逐条保存或忽略，不需要把记忆确认伪装成 Agent 的普通对话问题。左侧“长期记忆”工作台仍支持查询、新建、更新和精确删除；渲染进程只能通过受限 preload API 调用主进程，不能提供任意存储路径。
 
-候选等待确认时只存在于内存；关闭或切换会话不会偷偷保存。非交互 `--print` 模式没有可信的确认通道，因此完全关闭自动评价。`/remember` 和管理工作台是用户主动、明确的持久化操作，不经过 cheap 模型评分，但仍经过长度、敏感信息和去重规则。
+候选等待确认时保存在持久审核队列里，关闭或切换会话不会把它写成长期记忆。非交互 `--print` 模式没有可信的确认通道，因此完全关闭自动评价。`/remember` 和管理工作台是用户主动、明确的持久化操作，不经过 cheap 模型评分，但仍经过长度、敏感信息和去重规则。
 
 不进入交互会话时，可以用 CLI 做精确维护：
 
@@ -6496,3 +6498,92 @@ Windows 实测冷态启动 17 秒+、暖态 0.35 秒，主因是 Node ESM loader
 | `src/models/`（Anthropic/OpenAI 适配器）+ `src/context/manager.ts` | cacheTtl、prompt_cache_key、滚动标记、epoch append-only |
 
 对应测试：`tests/session/cli.test.ts`、`tests/config/cli.test.ts`、`tests/usage/cli.test.ts` 共 17 项单测（注入 fake store/deps）；`tests/config/load.test.ts` 的真实落盘集成；`tests/cli/launcher.test.ts` 轻量判定；`tests/cli/print.test.ts` 无头格式与白名单；缓存侧覆盖 OpenAI 稳定路由键、显式断点数量上限、兼容端点降级、官方 usage 口径，以及 Anthropic 首轮滚动标记、动态 system 顺序、1 小时 TTL、context epoch append-only 恢复的回归。当期全仓 **2282 个用例通过**、`tsc --noEmit` 通过。
+
+---
+
+## 50. 1.4.5-beta.1 可评价的自进化试运行
+
+### 50.1 一句话理解
+
+自进化不是让模型随意改自己的代码。它先把「可能有用的改变」记录下来，确认在哪些任务用过，再看用户反馈和测试结果；有问题就停用或回到上一个可用版本。本版先落地最直接的两类：**回答习惯**和**修复插件**。
+
+例如，用户说「以后请用中文解释」，这是明确要求，可以在后续任务中生效。模型从一次任务猜测「用户可能喜欢简短回答」，证据不足，先只记录；同一偏好在两个独立任务中出现后才试用。这里的“独立任务”按任务 ID 去重，同一个任务反复提及不会算作两条证据。
+
+### 50.2 偏好怎样自动变化
+
+偏好保存在项目的 `.flavor/evolution/preferences.json`。每条记录有来源（用户明确提出或模型推断）、状态、实际注入过的任务、正面和负面反馈。自动提取的偏好必须能在用户自己的话中找到相近表述；模型回答里凭空猜出的偏好不会进入试用。运行时最多注入五条可用偏好，推断偏好只在相关任务中注入；当前用户的新要求优先于这些旧偏好。
+
+| 状态 | 含义 | 进入条件 |
+| --- | --- | --- |
+| `proposed` | 已发现，暂不使用 | 第一次推断 |
+| `canary` | 小范围试用 | 至少两个独立任务支持该推断；或从停用状态手动恢复 |
+| `active` | 正常使用 | 用户明确提出；或试用命中至少十个任务、两个不同任务得到明确正面反馈且没有负面反馈 |
+| `suspended` / `dropped` | 停用 | 用户否定或手动 drop；推断偏好被明确否定后直接 drop |
+
+每次注入只证明“模型看到了这条偏好”，**不能证明它帮助了用户**。因此系统不会因为一段时间没有投诉就自动晋级，泛泛的“这次很好”也不算偏好好评。用户明确指出某条已注入的偏好有错时，它会停用；下一次模型调用还会收到“这条偏好已撤回”的提示，避免继续沿用对话历史里的旧版本。若同时注入多条偏好，无法确定用户在批评哪条时，不做自动归因，可在反馈中写偏好 ID，或用命令指定。
+
+可用 `/evolve preference list` 查看状态和证据，`/evolve preference drop <id>` 停用，`/evolve preference restore <id>` 重新试用。原有 `/memory` 管理的旧记忆仍由 `/forget` 等原命令处理；本版的新偏好状态机只管理新捕获的偏好。
+
+### 50.3 修复插件如何防止“更新有害”
+
+重复的工具错误仍会生成修复建议，但建议不是成功证明。开发完成一个 `fix-*` 插件后，依次运行：
+
+```text
+/evolve verify fix-read  →  在隔离环境检查插件，确认它确实注册了能力，记下文件内容哈希
+/evolve test             →  运行配置的测试命令，记录通过的哈希
+/evolve reload fix-read  →  只有当前文件哈希与两次检查完全一致才启用
+```
+
+任何文件在测试后改变，都要重做检查。启用前保存快照；若加载失败，恢复上一有效快照。重启时，未登记为有效版本的 `fix-*` 插件不会加载。修复插件实际运行时始终使用与检查时一致的隔离沙箱。`/evolve revert <name>` 可恢复最后的有效版本。
+
+工具趋势现在用“该工具失败调用数 ÷ 该工具总调用数”观察，普通任务和 `/loop` 都写入记录。例如 2 次失败/4 次调用为 50%；下一轮没有调用该工具，就没有可比结果，不能宣称修复成功。相邻运行的失败率也只是观察值，不会自动把建议标为已验证。空白脚手架无法通过 `/evolve verify`。
+
+模型提出的一句护栏也可能有害。因此 `evolve_improve kind=prompt_rule` 现在只把它列为 `proposed`，不立即加入提示词，也不关闭原建议。用 `/evolve rule list` 看内容，确认合适后执行 `/evolve rule accept <id>`；手动 `/evolve rule add <文字>` 是用户明确要求，仍立即生效。
+
+### 50.4 这版评价能回答什么，下一步缺什么
+
+本版能回答：偏好从哪里来、在哪些任务实际注入、收到多少明确反馈、为什么进入或退出试用；插件的**当前字节版本**是否通过隔离加载和测试、能否回滚。它不能仅凭测试全绿证明插件改善了目标故障，也没有在同一批任务上自动比较“启用前/启用后”的结果。自动编写并热更新核心代码也未开放。
+
+要进一步做到稳定的正向自进化，需要给每个候选加可复现的目标回归用例，再用固定任务集做成对评测，记录未启用版本的基线、候选版本的效果和样本数；真实任务中持续观察用户纠正、任务结果和成本。只有目标故障确实下降、其他关键任务不退化，才考虑更大范围自动推广。完整路线见 `docs/specs/2026-09-26-evaluable-self-evolution.md`。
+
+相关代码：`src/evolution/preferences.ts`（偏好状态和反馈）、`src/production.ts`（任务接入与命令）、`src/evolve/verification.ts`（插件哈希门禁）、`src/evolve/service.ts`（命令与趋势）、`src/plugins/host.ts`（运行沙箱）。
+
+### 50.5 深度检查后的结论
+
+目前实现的是“**能提出变化、有限试用、能撤销**”的基础，不等于已经证明“越用越好”。深度检查后已修好普通任务记录、推断偏好跨话题注入、泛化好评误归因、模型规则直接生效和空白插件过关。剩余缺口是：
+
+1. **有范围还需更准**：用户原话相似度和任务相关性只是保守的文字筛选，不等于模型推断正确；还需明确任务类别、冲突检测和可检查的验收标准。
+2. **评价真实收益**：十次注入和两次特定好评只是初步反馈。要用固定任务集比较启用前后是否遵守偏好，记录冲突指令、其他任务和成本；插件要有针对原故障的失败转通过回归用例。没有这些证据，不能自动宣布改进。
+3. **跨运行归因**：当前按工具比较相邻任务的失败率，尚未按错误指纹、环境和候选版本做成对比较；并发运行也需要独立计数上下文，才能避免统计混合。
+4. **统一规则生命周期**：模型规则现在先待审核，但还没有像偏好一样的自动试用和效果评价；旧版 `/memory` 记忆仍走原路径，需要逐步纳入统一的候选与停用机制。
+5. **自动熔断**：本版能拒绝未批准插件并回滚已保存版本，运行中的版本尚未按目标故障变化自动停用。
+
+因此 `1.4.5-beta.1` 应称为**自进化试运行基础版**。它降低了未经检查的变化直接生效的风险，但尚不能自动、可靠地判断每次变化是否让用户体验变好。
+
+### 50.6 如何人工验收
+
+在已经配置好模型的测试项目中启动 **1.4.5-beta.1**，先运行 `/evolve status`，应看到偏好数量和故障建议数量。输入「以后每次回答第一行写【验证标记】。请回答收到。」；用 `/evolve preference list` 查看，应出现 `active (explicit)` 和对应 ID。新开同一项目的会话，问一个无关问题，检查回复首行及列表里的暴露任务数。执行 `/evolve preference drop <id>` 后再开新会话，列表应变为 `dropped`，回复不应继续沿用标记；`restore <id>` 会恢复为 `canary`。
+
+普通任务执行两次后，`/evolve trends 2` 应列出两条运行记录。没有工具调用的任务只证明“没有观察到工具失败”，不证明质量提升。对重复错误生成的 `prompt_rule`，`/evolve rule list` 应先显示 `proposed`；执行 `accept <id>` 后才会进入未来提示词。空白 `fix-*` 脚手架运行 `/evolve verify <name>` 应报“registered no tools…”；编写并注册贡献后再验证。
+
+插件门禁可运行 `npm test -- tests/evolve/service.test.ts tests/evolve/verification.test.ts tests/plugins/host.test.ts`。这些测试覆盖未验证版本拒绝加载、测试后改动失效、名称不一致拒绝加载、快照校验和回滚失败报告。测试通过只证明门禁按设计工作，**不证明插件修复了目标故障**；后者仍需要专门的故障回归用例与前后对照。
+
+### 50.7 长期记忆如何减少噪声
+
+过去自动提取器会给每条候选自行打四项分数，合计达到默认 11/12 就直接写入。分数高不代表事实有来源；任务中助手回答很长时，也容易触发提取。`/forget-cold` 只能按近期召回情况清理，不能判断记忆内容是否有益。
+
+现在自动提取的**项目约定和外部引用**先放进 `.flavor/memory/review-inbox.json`，不会因为模型给满分就保存。队列最多 20 条，默认不计时消失，下一条任务和重启也不会清除。审核卡显示候选内容及核对过的用户原话；如果没有用户原话，会明确提示“无可核对引文”，需要人判断。`Ctrl+Y` 保存、`Ctrl+N` 忽略；`/memory` 显示待审核条数、提出/采纳/忽略次数，以及已存记忆中从未召回和 cold 的数量。明确 `/remember` 仍直接写入。
+
+同一类型、同一主题出现不同结论时，系统不会把两条都悄悄保存。审核确认会给出旧记忆 ID；用户可先 `/memory` 查看，再决定是否 `/forget <id>` 并确认新候选。引文只认任务中用户消息的原文，模型引用自己回答的文字不会被当成用户证据。
+
+这些改动把“模型自评”从写入通行证改成筛选参考。采纳率、召回数也都只是观察值：真正的质量仍要用一批任务检查候选是否正确、以后召回时是否相关，以及用户是否纠正或删除。现有历史记忆不会被自动批量删除；`/forget-cold` 依旧按冷热规则操作，使用前应查看 `/memory` 的概况。
+
+手工验收可以用一个全新测试项目：完成一项包含项目约定的普通任务，然后运行 `/memory`，应看到待审核数量增加，而已存数量不变；退出再启动同一项目，候选仍在。用 `Ctrl+N` 忽略一条，待审核减少、忽略次数增加，长期记忆不增加。再产生一条候选并用 `Ctrl+Y` 保存，已存数量增加。若模型没有找到能在用户消息中逐字核对的引文，卡片会提醒人工核实；这类候选不能因为分数高就自动保存。
+
+### 50.8 本地结果记录与对照评测
+
+这一步没有增加平台或数据库。原有 `.flavor/evolve/reflections.jsonl` 保留运行趋势；新的 `outcome-events.jsonl` 追加“哪条偏好在什么任务实际注入、任务怎样结束、用户之后对哪条偏好给出明确反馈”。事件只保存 ID、结果和计数，不复制提示词或工具参数；文件超过 5 MB 时保留最近 5000 条。`/evolve outcomes` 可直接查看最近事件。
+
+原有 `flavor eval <spec>` 仍能单独运行一条评测。加上 `--baseline <另一个工作区>` 后，同一题先在基线、再在候选工作区运行，使用相同提示和验证命令。两边的工作区必须不同，且都会被 Agent 修改，因此应事先准备可丢弃的测试副本。CLI 输出完整报告；候选工作区的 `.flavor/evolve/comparisons.jsonl` 只保存通过情况、检查通过数、耗时、token 与改善/退化/持平判定，最多保留 100 次，`/evolve comparisons` 可查看。运行顺序固定，但模型输出可能波动，一次“改善”只是这道题的一次观察，不自动触发晋级。
+
+长期记忆写入也补上了确定性去重：忽略引号、空格等标点差异，并把“Always address user as 亚川”与“用户称呼为亚川”这类同一称呼识别为同一事实；若称呼值改变，则提示冲突，不静默叠加。历史重复项仍需审查后合并，不能靠一个相似度阈值自动删除所有近似文字。