agent-trellis 0.19.0 → 0.21.0

package/docs/self-evolution.md

@@ -1,11 +1,11 @@
 # 自我进化:Trellis 的第二个子系统(想法沉淀)
 
-> **状态:整合草案,尚未实现。** 记录于 2026-10-20,来自一轮对 google-research/harness2 的调研与讨论;同日已整合为 `openspec/changes/trellis-evolve/`(一份草案、两个解耦的 capability)。
-> 本文是**想法与取舍**:是什么、为什么、边界在哪、已核实什么、还没定什么。可验证的行为约束在 change 的 `specs/` 里,**二者冲突时以 `specs/` 为准**。
+> **状态:阶段一已交付(2026-10-26),默认 `off` 未对用户开启。** 2026-10-20 初稿按"借 harness2 方法论自设形态"起草;**2026-10-24 用户裁决改为直接做 harness2 的 TS 版本——移植引擎,而非再造形态**,同日定下打包两阶段(内部包先行);2026-10-24–26 按 `openspec/changes/trellis-evolve/tasks.md` 完成阶段一实现。可验证的行为约束在 change 的 `specs/` 里,**二者冲突时以 `specs/` 为准**。
+> 本文是**想法与取舍**:是什么、为什么、边界在哪、已核实什么、还没定什么。
 
 ## 接手指南
 
-**一句话现状**:方向、边界、评测方法与护栏已定并写成可校验的草案;没有一行实现代码;下一步是先做三项只读前置验证,再做托管扩展点。
+**一句话现状**:阶段一(tasks 第 1–14 组)已交付:引擎移植为 workspace 内部包 `packages/evolve-engine/`(golden 对照 175/175)、托管扩展点、TrellisSubstrate 适配层、observe/触发、L4 治理与 fixture 端到端,宿主测试 1216/1216、`tsc` 干净、`openspec validate --strict` 通过、真机冒烟确认默认 `off` 零副作用。**生产接线已补齐(2026-10-26 收口)**:enable/disable 同步扩展清单、`activate` 订阅者包装(recorder + 触发器)、作业体 rule-based 治理流水(引擎内核 golden 锚定、生产未消费,随 L2/探针任务集接入)。后续是 `auto-A` 准入、L2/探针任务集、阶段二公开包。
 
 **文档地图(各管什么,避免重复维护)**
 
@@ -19,13 +19,13 @@
 | `…/tasks.md` | 实施顺序与逐项验证方式 | 实施中勾选 |
 | `docs/roadmap.md` | 一段指针 | 阶段变化时 |
 
-**建议阅读顺序**:本文"一句话"与"核心原则" → `design.md` 的 Context(已核实表)与 Open Questions → `tasks.md` 前三组 → 需要细节再读 `specs/`。
+**建议阅读顺序**:本文"一句话"与"核心原则" → `design.md` 的 Context(已核实表)与 Open Questions → 本文"生产接线"与 `tasks.md` 全貌 → 需要细节再读 `specs/`。
 
-**接手后第一步(tasks 第 1 组,全部只读)**:① 真机采样元数据事件能产生什么信号;② 核实 skills/instructions provider 是实时读取还是启动时缓存;③ 定下扩展加载机制与状态目录路径。这三项会决定 `host-extension-points` 的具体接口,**不要在它们之前开始写实现**。
+**接手后第一步**:读 `tasks.md`(阶段一全部完成)与 `spec-test-mapping.md`(58 场景→测试映射,创建 PR 时并入 PR 描述),然后看下文"生产接线"的边界说明(editor 通道未接、发现面=观察面等)。golden 对照集与复现方式在 `packages/evolve-engine/golden/`,是引擎后续改动的正确性锚。
 
 **需要接手人特别留意的三件事**
 
-1. **解耦是硬约束**:依赖只能是进化 → 托管。`src/evolve/` 只允许 import `src/host/*`,有测试强制。任何让托管"知道"进化的改动都是方向性错误。
+1. **解耦是硬约束**:依赖只能是进化 → 托管。`packages/evolve-engine/`(引擎)不 import 任何 Trellis 代码;`src/evolve/`(适配+治理)只允许 import 引擎包与 `src/host/*`,有测试强制。任何让托管"知道"进化的改动都是方向性错误。
 2. **带外批准目前不是完全可靠的**:有 shell 能力的 agent 理论上能执行管理面命令,TTY 检测只是启发式。`auto-A` 开启之前必须再评估(见 design 的 Risks 与 Open Questions)。
 3. **覆盖范围有边界**:事件只来自经 gateway/runtime 投递的 agent,仅走原生渲染的 agent 没有工具调用事件。不要在文档或 doctor 输出里假装全覆盖。
 
@@ -35,6 +35,18 @@
 
 Trellis 由两个**解耦**的部分组成:**托管**(让配置被正确投递并保持一致)和**自我进化**(让被托管的内容随使用变得更好)。进化是挂在 runtime 底座上的环境式能力,跑在其上的 agent 自己持续进化,可选安装、分级开启;它**不是**一条要用户去敲的命令。
 
+## 北极星(2026-10-27 定稿,两层)
+
+**引擎层(原样继承 harness2,不许动):**
+
+> 一个 agent 的 harness 应当仅凭自身的执行证据自我改进——无分数、无答案键、无 ground truth——只做可追溯到具体执行时刻的、上下文廉价的、可复用的编辑;宁可不改,不可白改;盲判交付物、以用户的请求为标尺;花费被严格记账;经验按域向前携带,让每一个未见任务都从更好的起点开始。
+
+**适配层(Trellis 侧,本次工作的星):**
+
+> 用户用 claude code / codex / pi 干的真实任务就是任务域;观察真实任务,蒸馏出考题(含标准答案),harness2 引擎原样跑考题做验证;被进化的 harness 就是托管的配置面(指令/skills/工具编排/记忆);人批与备份回滚是落地的安全壳。**进化的是 harness 不是模型;证据是任务执行对比不是配置体检;判效以用户的请求为标尺,含过程质量(少纠错、少报错、不越权);宁可不改不可改坏。**
+
+反目标(防漂移):不追分数(报告数字永不进选择回路);不改模型、不改交付物契约;不合成配置健康分(L1 差集只是 `validate_tree` 级施工检查);不为进化而进化;引擎不绑宿主(method/substrate/benchmark 三轴分离是 harness2 自己的架构纪律)。
+
 ## 为什么要做
 
 托管已经覆盖 skills、MCP、指令、scope、memory,但托管内容的**改进完全靠人**。信号其实一直存在,缺的是把"信号 → 提案 → 验证 → 采纳 → 教训沉淀"闭环起来的机制。2026-10 的两个真实事故说明了这一点:
@@ -54,21 +66,21 @@ Trellis 由两个**解耦**的部分组成:**托管**(让配置被正确投递
 | 缺席时 | 完全正常 | (本来就可选) |
 
 - **依赖方向只有一条:进化 → 托管,绝不反向。** 卸载进化,托管行为逐字节不变。这比"功能开关"更强:它是**可选安装**。
-- **进化自己声明它需要的 `HostPort`,托管去实现**,和 harness2 的 `Substrate` 协议同构(方法只依赖协议,不 import 具体框架)。好处:进化可以用 fake host 独立测试;托管的 `scope.yaml`(怎么渲染)与进化的"可编辑表面"声明(哪些能改、有什么静默失效坑)各管各的;架构上不堵死将来对接别的宿主。
-- 早期进化放在同仓库独立目录(`src/evolve/` 只允许 import 托管的公开 `host` 子路径,用测试强制边界),接口稳定后再考虑拆独立包。
+- **引擎是移植的 harness2 core**(`packages/evolve-engine/`,阶段一内部包):只依赖 `Substrate` 协议(5 方法,83 行原样翻译),对 Trellis 零感知。`src/evolve/` 的 **TrellisSubstrate 实现协议**并经托管的 `host` 门面落盘。好处:引擎可用 fake substrate 独立测试、golden 对照不被宿主污染、将来换宿主(如 agent-framework)只重写适配层。
+- 原自设的 `HostPort` 接口**作废**——harness2 已有验证过的协议签名,不自造接口。托管的 `scope.yaml`(怎么渲染)与适配层的"可编辑表面"声明(surface)各管各的,不合并。
 
 ```
-进化(只依赖这个接口)                  托管(实现它)
-HostPort {
-  readSurface(layer)        ───────→  loadCanonicalSource(只读,已有)
-  stage(edits)              ───────→  scratch HOME + 临时 workspace(测试夹具模式已有)
-  check(staged|live)        ───────→  doctor + sync --check + secrets audit
-  apply(edits, session)     ───────→  backup session 写入(已有,未公开)
-  rollback(session)         ───────→  trellis rollback(已有,未公开)
-  subscribe(events)         ───────→  会话事件流(新增,通用)
-  remember(lesson)          ───────→  memory 管道(已有)
-  delegate(task)            ───────→  agent-bridge(进行中)
-}
+TS 引擎(packages/evolve-engine,移植自 harness2 core,对 Trellis 零感知)
+  schedule / recursion / selection / proposer / judge / context
+  prompts / tree / runmark / ledger        ← 只认识这个协议 ↓
+Substrate 协议(5 方法,83 行原样翻译)
+  surface()          ───────→  Trellis 可编辑树 schema(能改什么、静默失效模式)
+  materialise()      ───────→  staging 渲染(host 门面:scratch HOME + 临时 workspace)
+  execute()          ───────→  探针会话(穷人沙盒 + 一次性 CLI 会话)
+  read_trajectory()  ───────→  会话记录/轨迹 → 共享语法
+  preflight()        ───────→  doctor 级花钱前自检
+TrellisSubstrate(src/evolve,适配 + L4 治理)→ 托管
+  host 门面(检查 / 备份会话写入 / 回滚 / staging)· 事件流 · memory 管道(通用扩展点)
 ```
 
 ## 环境式运行:触发、观察、通知、生效
@@ -76,7 +88,7 @@ HostPort {
 Trellis 的 gateway 是按会话拉起的 stdio 进程,规范明确 **"without a resident daemon"**,所以进化也**不引入常驻进程**,靠事件驱动:
 
 1. **观察**:被动加主动并行。被动 = gateway 路由层记录元数据(工具/skill/记忆的调用、耗时、错误类别);主动 = agent 在用户纠正时自己调用 `trellis.evolve.note` 上报。主动信号最贵、质量最高(例如一次"配置改反方向"的纠正)。
-2. **触发**:会话结束(provider 的 `close()` 钩子)时判断信号量/严重度/冷却期,满足则 detached 拉起**一次性**后台作业,单实例锁。
+2. **触发**:会话结束(provider 的 `close()` 钩子)时判断信号量/冷却期(严重度加权留待后续变更,本期信号无严重度字段),满足则 detached 拉起**一次性**后台作业,单实例锁。
 3. **提案 → 验证 → 过门**:见下节,即原五环的 Propose / Probe / Compose。
 4. **通知**:pending 提案经 provider 暴露给 agent(`pending` 工具或 resource),agent 在会话里告知用户;doctor 与 GUI 也可查看。
 5. **生效**:runtime 模式下 skills / instructions 由 provider 从 canonical 实时提供,采纳后**下个会话自然读到新版本,无需 sync**;只用原生渲染的 agent,采纳后触发 sync。
@@ -92,7 +104,7 @@ Observe → Propose → Probe → Compose → Apply+Reflect
           lesson 回流为下次 Propose 的上下文 ┘
 ```
 
-- **Propose**:经 agent-bridge `runDelegatedCall` 委派 editor,产出结构化 `proposal.yaml`。editor 是**不可信输出**:机械校验器复核 kind/target 白名单与证据要求,错误写成可执行散文喂回重试一次,再错丢弃。**没有 evidence 链接的提案直接丢弃。**
+- **Propose**:引擎 proposer 拉起 improver 会话(本机 CLI spawn;agent-bridge 为可选委派通道),产出结构化树编辑。editor 是**不可信输出**:引擎 `validate_tree` 机械复核,错误写成可执行散文喂回重试一次,再错丢弃;证据要求与 Class C 排除由 L4 治理层与 `surface()` schema 双重强制。**没有 evidence 链接的提案直接丢弃。**
 - **Probe**:提案先写入 staging 候选(scratch HOME,按需加临时 workspace root),不动真配置。
 - **Compose**:风险门,见下。采纳铁律:任何验收器结果不得差于 baseline,宁可不进化。
 - **Apply+Reflect**:写入走一个备份会话,单点 `trellis rollback` 整体回滚;被采纳的编辑蒸馏成 lesson `{cue, lesson, evidence, confidence?}` 进 `memories/`,作为下次提案上下文(harness2 的 improvement harness)。
@@ -102,9 +114,9 @@ Observe → Propose → Probe → Compose → Apply+Reflect
 harness2 的评分是**两段式且互相隔离**:选择(匿名对比、无 ground truth)与评分(checklist,选择承诺之后才跑)物理分离,选择器永远看不到评分材料。我们按"有无现成 oracle"分层:
 
 - **L1 配置类 — 确定性差集,零 LLM**:baseline 与 staging 候选各跑 doctor / `sync --check` / secrets audit,可采纳 ⟺ 无新 finding ∧ 目标 finding 已消除 ∧ 其余不变。配置类的检查本身就是 ground truth,比 LLM 选择器更强也更便宜。两个事故都属这一类。
-- **L2 内容类 — 沙盒执行 + 匿名 A/B**:同一道探针任务在 base 与 candidate 下各跑一次,交付物冻结后,以种子匿名 id 呈现给独立选择器(不给 verdict、不含评分字样、不标明哪臂是新)。选择器失败 / 任一臂未交付 / 选中 base ⟹ 一律不采纳。**一处刻意反转**:harness2 把 base 排除出候选池("构造上无法弃权",因为它必须进化);我们把 base **留在池里**,因为我们不能退化。
-- **L3 成绩单**:一小组带显式 checklist 的探针,定期对已采纳修改跑 `n_passed/n_criteria` 看趋势。评分失败记 `None`,不计入分母,**永不记 0 分**;结果只给人看,不给选择器看。
-- **缺口**:内容类(L2)缺**探针任务集**,这是真正的前置资产,比代码更难。来源优先级:真实事故复现题 > 用户纠正转化题 > 按 skill 领域合成题。因此路线先做 L1。
+- **L2 内容类 — 沙盒执行 + 匿名 A/B**:同一道考题在 base 与 candidate 下各跑一次,交付物冻结后,以种子匿名 id 呈现给独立选择器(不给 verdict、不含评分字样、不标明哪臂是新)。选择器失败 / 任一臂未交付 / 选中 base ⟹ 一律不采纳。**一处刻意反转**:harness2 把 base 排除出候选池("构造上无法弃权",因为它必须进化);我们把 base **留在池里**,因为我们不能退化。
+- **L3 成绩单**:一小组带显式 checklist 的考题,定期对已采纳修改跑 `n_passed/n_criteria` 看趋势。评分失败记 `None`,不计入分母,**永不记 0 分**;结果只给人看,不给选择器看。
+- **任务域与判分定案(2026-10-27,方向重校)**:L2 的题目不自造——**观察用户真实任务蒸馏出考题**(task.md + 源材料 + 标准答案/rubric)。rubric 从"用户请求 + 被接受的结果"沉淀,harness2 的 judge 原样可用(`n_passed/n_criteria`、失败=None 不记 0、答案键锁后台防泄漏,proposer/selector 永远看不到)。**铁律:用户的原始任务只观察、永不重放**——真实任务带副作用("发邮件"重放就真发出去了);重放只跑蒸馏考题(沙盒内、可评分、无真实副作用)。纠正率/错误率是观察层找问题的输入,**不是判分器**。考题来源优先级:真实事故复现 > 用户纠正转化 > 合成变体。此前"缺探针任务集"的缺口由蒸馏器补上——真正的前置资产从"题库"变成"蒸馏器 + 质量线"。
 
 执行隔离:本机用"穷人沙盒"——`mkdtemp` workspace + staging 渲染配置 + 重定向的 agent 配置 HOME + 一次性会话,**沙盒保证每次执行干净可复现,对比本身发生在冻结的产物上,不在沙盒里**。容器(本机有 OrbStack)后置,等探针要跑不可信代码或需并行 K 候选时再上。
 
@@ -154,23 +166,27 @@ harness2 的评分是**两段式且互相隔离**:选择(匿名对比、无 grou
 | 穷人沙盒 | `substrate/codex.py:149-185` | probe workspace 边界 |
 | 校验错误即 prompt(原样喂回作重试反馈) | `validate_tree` | editor 重试 |
 
-**没有可直接用的 SDK**:无 PyPI 包、`harness2/__init__.py` 为空(无公开 API)、7 个 console script、仅 Linux、Python 3.12、绑 Vertex AI 与 Docker、与三个 benchmark 耦合。**移植方法论,不移植代码。**
+**移植决定(2026-10-24 修订)**:无 PyPI 包、`harness2/__init__.py` 为空(无公开 API)意味着移植只能由我们做;但 `dependencies = []`(core 纯标准库)、无平台门控、Vertex 只是 spawn 子进程的环境变量,意味着 **core ≈5,650 行可整体直译为 TS**。Linux/Docker/benchmark 属评测资产侧,不移植;benchmarks 的对应物是自建探针任务集。~~移植方法论,不移植代码~~ → **移植引擎,再造宿主**。打包两阶段:阶段一内部包(不发 npm),阶段二等第二个消费者出现(与 agent-framework 整合是同一动作)。
 
 ## 已核实 / 未核实
 
 | 已核实(读过代码或 spec;位置见 design.md Context) | 未核实 / 假设 |
 |---|---|
-| gateway 无常驻进程,client 断开即释放上游 | 观察元数据是否足以支撑有价值的信号(需真机采样,tasks 1.1) |
-| **所有工具调用(内建与上游)汇入同一咽喉点** `BuiltinRegistry.callTool`,由 `tools/call` handler 调用——事件可在此一处挂载 | skills / instructions provider 是实时读取还是启动时缓存(tasks 1.2),决定"会话快照"是否需要 |
-| `RuntimeContext` 只有 `{agentId, homeDir}`,**无会话标识**——须由事件层生成 | 扩展加载机制与状态目录路径(tasks 1.3) |
-| 关闭路径只处理 stdin `end`/`close` 与 SIGTERM/SIGINT/SIGHUP;**SIGKILL/崩溃不触发 `close()`**——因此必须有"下次启动补偿检查" | 全局记忆未启用时,lesson 回流的实际效果 |
-| `openBackupSession` 与 `collectDoctorReport` 存在,但**都未经 SDK 公开**;SDK 根入口只导出 `loadCanonicalSource`/`ALL_AGENTS`/`resolveScope`,且 spec 禁止导出 adapters/commands 内部 | 带外批准在 agent 有 shell 能力时的强度(TTY 检测只是启发式) |
-| `TrellisProvider` 含 `close()` 与 skill 条目接口 | |
+| gateway 无常驻进程,client 断开即释放上游 | 全局记忆未启用时 lesson 回流的实际效果(本机记忆未开,`recordLesson` 报 `skipped` 而非 `failed`) |
+| **所有工具调用(内建与上游)汇入同一咽喉点** `BuiltinRegistry.callTool`——事件总线已在此挂载(8.3) | 带外批准在 agent 有 shell 能力时的强度(TTY 检测只是启发式;`auto-A` 前必须再评估) |
+| `RuntimeContext` 只有 `{agentId, homeDir}`,**无会话标识**——已由事件层生成,同进程一致(8.2/8.3) | L2 探针任务集来源与归属(真实事故复现 > 用户纠正转化 > 合成;canonical 还是 per-workspace 待决) |
+| 关闭路径只处理 stdin `end`/`close` 与 SIGTERM/SIGINT/SIGHUP;**SIGKILL/崩溃不触发 `close()`**——下次启动补偿检查已实现(11.6) | `auto-A` 准入:需要多少次有人监督的运行才算"证明不误报" |
+| 扩展加载机制与状态目录路径已定案并实现(8.1/8.6):清单 `~/.trellis/mcp/extensions.yaml` + `activate` 契约(阶段一:绝对路径/文件 URL),状态目录 `~/.trellis/evolve`;失败按 `manifest`/`invalid`/`import`/`activate` 阶段隔离,无清单零装载 | |
+| 观察字段已定(9.4①):事件只含白名单元数据,载荷不入库,secrets 擦除后按进程分文件追加 | |
+| skills/instructions provider 读取路径已核实(9.4②),结论入 design | |
+| `TrellisProvider` 含 `close()` 与 skill 条目接口;host 门面已公开检查/备份会话/回滚/staging(8.5),SDK 根入口仍只导出只读面 | |
 | harness2 各机制的行为(见上表) | |
+| **发布配置(14.4)**:`packages/evolve-engine` 为 `private: true`、`version 0.0.0`、files 仅 `dist`+`NOTICE`;根 tarball `files` 不含 `packages/`,引擎只在 `devDependencies`,cli.ts 静态 import 链(112 文件)零触达引擎包——**阶段二启动条件未满足前不进任何 npm 发布配置**。注意差异:根 `prepublishOnly` 是 typecheck+build+test,**不含** `verify-pack`(独立 script,pack 真 tarball 装进无 devDependencies 的 scratch 冒烟) | |
 
 ## 已定倾向 / 待决
 
-- **倾向(未最终确认)**:Class B 批准带外为主;后台作业由会话结束拉起而不靠外部调度器;进化先同仓库独立目录;先做 L1。
+- **已定(2026-10-24)**:移植 harness2 引擎为 TS;打包两阶段(阶段一 `packages/evolve-engine/` 内部包、不发 npm,阶段二等第二个消费者、与 agent-framework 整合同一动作);prompt 模板原样保留英文(默认)。Class B 批准带外为主;后台作业由会话结束拉起而不靠外部调度器;先做 L1。
+- **已定(同日,8.1/9.4)**:扩展加载机制(清单 + `activate` 契约,provider 与订阅者同面)与状态目录路径;观察元数据字段白名单(9.4①);provider 读取路径(9.4②)。
 - **待决**:用户纠正的采集形态(手工 `note` vs 从会话收割);探针任务集放 canonical 还是 per-workspace;`auto-A` 之前需要多少次有人监督的运行才算"证明不误报";运行档案的轮转策略。
 
 ## 前置依赖
@@ -184,11 +200,12 @@ harness2 的评分是**两段式且互相隔离**:选择(匿名对比、无 grou
 | 阶段 | 内容 | 状态 |
 |---|---|---|
 | P0 | doctor oracle、backup/rollback、memory 管道、agent-bridge 委派原语 | 已就位 |
-| P1 | **托管扩展点**(事件流、`host` 子路径、provider 外部注册) | 先做;进化侧一切依赖它 |
-| P2 | 进化 Observe + Propose,仅配置类、人审批 | |
-| P3 | Probe:L1 verdict 差集;`auto-A` | |
-| P4 | 内容类:L2 匿名 A/B,依赖探针任务集;lesson 回流提质 | |
-| P5 | 递归预算(K 候选 parallel / K 步 sequential)、容器化 probe | |
+| P1 | **引擎移植**(阶段一内部包:golden 基线 → 按依赖图 6 层移植 → 对照验收);托管扩展点 | 已完成(引擎 175/175;扩展点 8.1–8.7) |
+| P2 | TrellisSubstrate 适配层 + Observe/触发:环境式接入,`off`/`observe` | 已完成(第 9–11 组;默认 `off`;生产接线见"生产接线"节) |
+| P3 | `propose` 端到端:L4 治理(证据提案、L1 前闸、带外批准、单会话写入) | 已完成(第 12–14 组;fixture E2E + 真机冒烟) |
+| P4 | `auto-A`;内容类 L2(依赖探针任务集);lesson 回流提质 | 未开始(`auto-A` 准入门槛待决) |
+| P5 | 递归预算(K 候选 parallel / K 步 sequential)、容器化 probe | 未开始 |
+| 阶段二 | 引擎提升公开 npm 包 = agent-framework 整合(同一动作) | 等第二个真实消费者;发布配置已确认不夹带(见上表) |
 
 ## 明确不做
 
@@ -197,13 +214,90 @@ harness2 的评分是**两段式且互相隔离**:选择(匿名对比、无 grou
 - 绕过目标 agent 的审批 / 沙盒机制。
 - 在没有现成 oracle 的类别上抢跑自动采纳(内容类必须等探针任务集)。
 
-## 下一步
+## 生产接线(2026-10-26 收口)
+
+阶段一任务按各自验证标准通过后,14.4 核实时曾记录三处生产接线未连通,**已全部补齐并配测试**(宿主 1216/1216):
+
+1. **`evolve enable|disable` 同步扩展清单**(design 8.1):级别升至 `observe` 及以上时向 `~/.trellis/mcp/extensions.yaml` 幂等写入条目(`id: evolve`,`load` 指向 `src/evolve/extension.ts` 的 activate 模块,dist/tsx 两种运行形态同款解析),置回 `off` 时移除;任一粒度(default/agent/workspace)仍有 observe+ 时条目保留(any-of 规则,细粒度闸在订阅者逐会话判定)。
+2. **`activate(ctx)` 订阅者包装**(`src/evolve/extension.ts`):`off` 零订阅;`observe` 只挂 recorder(事件 → 信号,含 secrets 擦除与层归属);`propose`/`auto-A` 另挂触发器订阅者(会话结束判定拉起作业、会话启动补偿)。与真实清单 loader(`loadHostExtensions`)的结构契约兼容有集成测试。
+3. **作业体治理流水(rule-based)**(`src/evolve/jobRun.ts`,`jobMain` 调用):可选源探测 → 信号合并(自上次作业结束)→ runChecks 发现 → rule-based 提案 → 机械校验 → L1 前闸 → 风险分类 → 采纳门(A 仅 auto-A 且闸通过自动采纳并通知)→ pending 呈现/自动采纳 → 应用阶段(全部已批准编辑同一备份会话 + 按 delivery 分类对原生渲染 agent 触发同步)→ lesson(记忆启用走记忆管道,否则只留档案)。fixture E2E 的同链流水现由生产入口承载。**口径澄清(review 纠偏)**:这是 rule-based 治理流水,不是引擎循环——移植引擎的 schedule/recursion/proposer/selection/judge golden 锚定但生产未经此消费,接入随 L2/探针任务集一并启动。
+
+接线后仍要知晓的边界(如实记录,不是缺口):
+
+- **editor/spawn 提案通道未接**:`runDelegatedCall` 就绪前作业只走 rule-based 兜底(design D7 的降级路径);harness2 引擎的 proposer spawn 面在引擎包内已移植并 golden 锚定,生产接入随 L2/探针任务集一并启动。
+- **发现面=观察面**:作业只扫描信号层归属出现过、或级别策略声明过的 workspace;没进过观察面的 workspace 不会被发现(与"信号是观察记录"一致)。
+- **批准即应用与降级边界**(trellis-evolve-review-fixes):`approve` 成功即在同一命令内经备份会话应用(单飞锁互斥;锁忙/失败时如实告知、提案保持 approved)。滞留的已批准提案经 `trellis evolve apply` 随时消化(显式管理面命令,执行用户已批准的决策,不属循环触发、不写信号),或由下次 propose+ 作业的应用阶段消费;`trellis evolve status` 显示 approved 未应用计数。
+- **生效侧判定**:`triggerRenderSync` 只在存在原生渲染 agent 且本次有编辑被应用时触发一次;`isMemoryDeliveryEnabled` 按 memory MCP server 的显式配置(`staticEnv.MEMORY_FILE_PATH`)判定记忆管道开关。
+- **agent 粒度只闸观察与触发**:提案产出按提案目标层粒度(workspace > default)判定——发现来自 doctor 检查面,不归属某个 agent 的行为;只设 `agents: {x: propose}` 时作业会被拉起但不产提案(spec 已就此澄清)。
+- **agent 接口面 transport 后置**:`agentView.listPendingSummaries` 与 `reportUserCorrection` 函数与约束(只读、无批准能力、secrets 擦除)已交付并有测试,但本期不进 MCP/CLI/provider——真实会话中的 agent 尚无可达通道,接入随 editor/spawn 通道一并启动。
+- **`secrets-policy-fix` 的 Class A 归属待 editor 通道接通时复审**:当前 rule-based 通道只产 workspace-toml 修复(恒 B),该规则不可达;接通 editor 通道前评估是否降为 B。
+
+## 可视化(2026-10-27,trellis-evolve-visualization)
+
+进化过程对用户可见的三段呈现(只读消费,查看零副作用):
+
+- **数据出口**:`trellis evolve report [--json]` 与 `status --json` —— 单一聚合函数 `src/evolve/reportView.ts`(`buildEvolveReport`)从档案/pending/级别策略计算,CLI 文本、JSON、GUI 三副渲染壳同源,不维护第二份计算。
+- **GUI 仪表盘**(`packages/gui` Evolution 页):趋势(真实测量,含口径)、优化内容卡(前后 finding 差集 + 编辑清单)、提案时间线(发现→提案→verdict→决策→应用→lesson 全链,含备份会话回滚入口)。
+- **指标诚实性原则**(spec 约束):只展示可从档案重算的真实测量(累计发现解决数、采纳率/拒绝率、作业运行/失败次数);**不合成数值评分**,分数轴等 L2 探针任务集落地后另起变更。空态/未开启是一等状态,不画误导性的空图。
+
+## 审查修复轮(2026-10-26,子 Agent 四路审查后)
 
-已完成:整合为 `openspec/changes/trellis-evolve/`(一份草案、两个 capability:`host-extension-points` 与 `self-evolution`),并已 `openspec validate --strict`;gateway 咽喉点与 `close()` 覆盖范围已核实(见上表)。
+阶段一收口后做了一轮四路只读审查(spec 符合性/正确性/安全/测试覆盖),随后修复:
 
-待做(按 `tasks.md` 顺序):
+- **崩溃循环链**:spawn 失败收容(`error` 监听,pid 缺失记 `spawn-failed` 而非假 launch);作业体抛错也落 job-run 档案(endedAtMs 推进冷却,error 留审计,不再无限重拉);apply 部分失败落 failed 标记档案且 `remove-symlink` 幂等重放。
+- **信号水位线**:job-run 档案记"信号合并时刻"(signalsMergedAtMs),触发计数与作业合并以它为界——作业运行期间到达的信号不再永久丢失。
+- **staging 凭据排除**:`.trellis` 复制剔除 `mcp/oauth`、`backups`、`evolve`(`TRELLIS_STAGING_EXCLUDES`),凭据不离开真实 home。
+- **纵深防御**:应用阶段对每条 approved 记录重跑机械校验(`validateProposal`),pending 磁盘漂移/伪造编辑到不了写入面;死锁清理改 compare-and-delete。
+- **写路径加固**:`evolve.yaml`/`extensions.yaml`/pending 记录全部原子写(tmp+rename);进化状态目录 0700、信号/档案/pending 文件 0600;`extensions` 键非数组硬抛而非静默吞;`enable` 建状态目录骨架并在 dotfiles 仓库场景把 `evolve/` 加入 .gitignore。
+- **自治升级门**:`enable --level propose|auto-A` 与 approve 同级 TTY 闸门(非交互 agent 会话不得自行提升自治级别);`disable` 不再接受 `--level`,存在非 off 覆盖时明确提示仍生效。
+- **spec 措辞对齐**:触发判定去掉"严重度"(本期按计数);补充 agent 粒度语义;`trellis evolve status` 展示最近自动采纳通知(原只落档案)。
+
+## 手动触发与历史回填(2026-10-27,trellis-evolve-run-backfill)
+
+两个真实入口补齐(动机:手动立刻跑一次;开启之前的会话是宝贵财富):
+
+- **手动触发 `trellis evolve run [--dry-run]`**(唯一命令行触发入口):门语义 = 阈值/冷却豁免(用户明确意图),**单飞锁与预算护栏照旧**(日提案上限/editor 预算超限仍跳过并记因,不排队);observe 及以下作业体零副作用早退并说明级别与调整方法;`--dry-run` 只预览(将消费信号数/护栏判定),不拉起、不写入。前台跑与事件触发同一作业壳(`runJobShell`),job-run 档案记触发来源 `manual`。
+- **补跑语义(单槽 coalesce,不是队列)**:运行期间到达的触发请求(手动或事件)塌缩为至多一个 `evolve/run-request.json` 标记(count 仅审计);任何作业启动即清标记(请求已被满足),作业收尾释锁后消费标记并链起至多一次补跑(`trigger: chain`,同受预算护栏,skip 照记因)。崩溃残留的标记由下次作业启动清掉(至多多跑一次,提案去重兜底),丢失至多一次请求(下次事件/手动自然补)。全程无常驻进程,系统保持 daemon-less。
+- **历史回填 `trellis evolve import <path>... [--workspace <root>]`**:导入边界 = 仅显式选定路径、对源只读;按观察信号同一字段白名单抽元数据(时间戳/agent/会话/工具名/耗时/结果类别,入参与正文一律不入库),字符串写入前一律 secrets 擦除;台账幂等(`evolve/imports/<sha256>.json`,重复导入为空操作);stableId `import:<digest12>:<行号>` 确定性,重复消费不产生重复提案;整批先校验后写入(任何源不可解析即零写入收口);导入不触发作业,信号待后续作业按水位线消费。适配器契约 `{ sniff, extract }` 先行,首个适配器 `claude-code-jsonl`(Kimi/Codex/ZCode 源后置)。
+
+## 方向定案(2026-10-27,任务域重校)
+
+实现走线曾把"配置体检(L1)"当成了主循环驱动——观察配置、以 finding 消除为效果判据,引擎内核被搁置旁路。经对照 harness2 源意图复核,确认这是结构性偏差:**主循环的驱动信号是任务,不是配置体检**;L1 的位置是 `validate_tree`(施工合法性硬闸),不是 `score`(效果判据)。定案后完整管线:
+
+```
+观察层(只读,永不执行用户的活)    用户用 claude/codex/pi 真实干的任务 → 任务分析(要什么/哪里不顺/结果)
+   ↓ 蒸馏(适配层核心新部件)
+考题库(任务域)                   task.md + 源材料 + 标准答案/rubric(从被接受的结果沉淀)+ 可安全重跑
+   ↓ 以下与 harness2 逐字一致,引擎零改动
+harness2 循环                     base rollouts → 提案 → 候选跑考题 → 盲选 → judge 对 rubric 打分 → 经验库
+   ↓ 采纳
+应用安全壳(宿主职责)              人批 B 类 + 备份会话写回配置 + 一步回滚
+```
+
+| 部件 | 状态 |
+|---|---|
+| 任务来源 | **变**:题库作者 → 从真实任务观察蒸馏 |
+| 真实任务的执行 | **永不重放**(副作用铁律);只被动观察 |
+| 考题(task+源材料+rubric) | **不变**——蒸馏出的考题就是 harness2 意义上的 benchmark 题 |
+| 提案/递归重试/validate_tree | **不变** |
+| 盲选/KEEP_BASE/judge/None≠0 | **不变** |
+| 经验库/账本/防泄漏 | **不变**(蒸馏 rubric 同为答案键,防泄漏纪律原样适用) |
+| 应用安全壳(人批/备份/回滚) | **保留**(写真实配置是引擎外的宿主职责) |
+| L1 配置体检 | 降级为 `validate_tree` 级施工检查,永不当效果分 |
+
+**考题六要素**(2026-10-27 补):`task.md`(只描述工作、不描述度量——harness2 禁词规则照搬)+ 源材料(脱敏、最小化)+ 参考交付物(用户被接受的结果)+ rubric(二值判据集,形态参照 harness2 LAB;**含过程判据**——少纠错/少报错/不越权类,如"发送前有确认""未执行破坏性命令")+ 副作用声明(重放时必须 mock 的动作:"发邮件"变"写邮件")+ 过程注记(蒸馏自真实过程的错误点/纠正点/绕路点)。无明确接受结果的任务(用户中途放弃)不产考题,产观察教训。
+
+**过程数据三层保留**(同日补):① 真实任务过程**原地保留**(用户机器上的会话文件不搬不动),蒸馏时只提炼过程注记;② 验证 rollout 的过程按 harness2 同款**完整轨迹**保留(证据文件、不截断)——"改动能指认到具体轨迹时刻,指认不出即投机";③ 过程质量进 rubric 成为可判分判据(判据里没有的,循环不会优化它)。
+
+**细节裁决(2026-10-27,四项已定)**:
+① **考题库归属 = per-workspace**:每个 workspace 的配置不同,优化对象常是 workspace 配置而非全局;通用题晋升 canonical 用**自动保守规则**(同一题跨 ≥2 个 workspace 复现才晋升),不设人工审核。
+② **蒸馏质量线 = 全自动质检,不设人工过目**(减少人工参与):自动闸 = 可重跑性 / rubric 二值可判 / 脱敏扫描 / 禁词扫描 / 副作用声明完备。错误考题的爆炸半径两层兜底——沙盒隔离(烧的只是预算)+ 应用前 B 类人批(坏改动到不了真配置)。人工点收敛到只剩 B 类批准一个**决策**(auto-A 成熟后再减)。
+③ **隐私边界 = 保结构去内容 + 工具调用永不重放**:观察侧只蒸馏工具调用元数据(白名单字段)与过程注记,原会话原地不动;验证侧重放**考题**而非原任务,副作用工具按副作用声明生成 mock 表(发邮件→mock outbox、部署/删除/外呼 API 一律 mock、出网默认封锁),安全工具沙盒内正常执行;过程判据(少纠错/少报错/不越权)作用于**新轨迹**,不重放原过程。"证据是数据不是指令"防注入照挂。
+④ **预算与模型均可配置**:`evolve.yaml` 增执行配置段——单轮沙盒会话上限、USD 上限、proposer/executor/judge 三角色模型各自可配(缺省保守:≤8 会话/轮);账本恒等式照 harness2 硬约束;花钱动作只由手动触发/人批准时机执行(事件触发只做观察+蒸馏,零花费)。
+
+## 下一步
 
-1. **前置验证(第 1 组,只读)**:真机采样元数据信号质量;核实 skills/instructions provider 读取路径;定下扩展加载机制与状态目录路径。
-2. **托管扩展点(第 2 组)**:事件总线、`host` 子路径门面、外部 provider 注册、"托管不依赖消费者"构建测试。纯增量、默认零行为变化,可单独发版。
-3. **进化 `off`/`observe` → `propose` → `auto-A`**(第 3–8 组),`auto-A` 之前须再评估带外批准的强度。
-4. L2 执行、探针任务集、递归预算为后续独立变更。
+1. **OpenSpec 提案**:任务域接入变更(蒸馏层 + harness2 式考题循环 + substrate 执行/mock 层),四项细节裁决见"方向定案"节;同步精读 harness2 自带 benchmark 适配实现作 Trellis 适配参照(源 checkout 只读、保持原样)。
+2. **`auto-A` 准入评估**:带外批准强度(见 design Risks)、需要多少次有人监督的运行才算"证明不误报"(待决);此后才谈真实开启 `auto-A`。
+3. **lesson 回流提质**(全局记忆启用后才有真实载体)、editor/spawn 提案通道接入(等 `runDelegatedCall`)。
+4. **阶段二**:引擎提升公开 npm 包 = agent-framework 整合(同一动作),等第二个真实消费者;递归预算、容器化 probe 为后续独立变更。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",
@@ -18,7 +18,11 @@
       "types": "./dist/sdk.d.ts",
       "import": "./dist/sdk.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./host": {
+      "types": "./dist/host/index.d.ts",
+      "import": "./dist/host/index.js"
+    }
   },
   "files": [
     "dist",
@@ -53,6 +57,7 @@
     "agents.md"
   ],
   "devDependencies": {
+    "@trellis/evolve-engine": "*",
     "@types/node": "^22.0.0",
     "esbuild": "^0.28.2",
     "tsx": "^4.19.0",
@@ -64,6 +69,7 @@
     "@modelcontextprotocol/client": "^2.3.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@modelcontextprotocol/server": "^2.3.1",
+    "@morphixai/mxenv-core": "^0.12.2",
     "smol-toml": "^1.9.1",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"

package/schema/secrets.policy.example.yaml

@@ -12,6 +12,11 @@
 # whose own native MCP client resolves `${VAR}` in its own process), so it
 # already has to read a value into memory to hand to that subprocess.
 #
+# Prefer `mxenv://<profile>/<KEY>` references in servers.yaml `env` /
+# `envAliases` entries where possible: they resolve from the encrypted
+# mxenv store at consumption time and need neither ambient env nor a
+# plaintext env_file (mx-env-secret-source).
+#
 # env_file (optional) narrows *where* the bridge reads those values from —
 # a dotenv-format file (KEY=VALUE per line, no quoting/interpolation), never
 # merged with ambient process env once set: a name absent from it resolves

package/schema/servers.example.yaml

@@ -1,7 +1,11 @@
 # .trellis/mcp/servers.yaml — canonical MCP server definitions.
 #
 # Rules (see docs/architecture.md and docs/research.md §"Secrets"):
-#   - `env` values are variable NAMES only. Never a literal secret.
+#   - `env` values are variable NAMES only, or `mxenv://<profile>/<KEY>`
+#     references resolved from the mxenv store at consumption time and
+#     delivered under the `KEY` segment (mx-env-secret-source). A
+#     reference gives this file value-free, machine-independent
+#     provenance; prefer it over relying on ambient process env.
 #   - Real values come from whatever already populates process env
 #     (a plain `.env`-style file, 1Password's `op run`, etc.) — Trellis
 #     does not store or transport secret values itself.