[设计备忘] JIT 式优化与官方插件接入边界：思路指导 + 能力印证 + 参考引用

[Te-River]

---

AIGC:
Label: "1"
ContentProducer: 001191440300708461136T1XGW3
ProduceID: 4ffcc5c951a3e4b06573f26a68e0a743_9ec73485ab6a11f18039525400461939
ReservedCode1: DrbMnjMNI7CseALgAHwLv/rYo1qneyJ1WS1/vjwqHLkTncQrFU08jnlcR71rkIc/0rPerDNLX0PHyFUSBEjpDyyQYHmVa8Ui8je/ToRuSCPPGiaF/bGyZ4hLwMy+pOcdLmyw1XgZHfrzxxv9BqPxnwf/UoCanl11DwJHjKhkLDb1H8+BgHaVe380Dhg=
ContentPropagator: 001191440300708461136T1XGW3
PropagateID: 4ffcc5c951a3e4b06573f26a68e0a743_9ec73485ab6a11f18039525400461939
ReservedCode2: DrbMnjMNI7CseALgAHwLv/rYo1qneyJ1WS1/vjwqHLkTncQrFU08jnlcR71rkIc/0rPerDNLX0PHyFUSBEjpDyyQYHmVa8Ui8je/ToRuSCPPGiaF/bGyZ4hLwMy+pOcdLmyw1XgZHfrzxxv9BqPxnwf/UoCanl11DwJHjKhkLDb1H8+BgHaVe380Dhg=

[设计备忘] JIT 式优化与官方插件接入边界：v1.5.1 实现对照 + 思路指导 + 参考引用（2026-09-10 修订版 v3）

本 Issue 是设计备忘 / 思路沉淀，非 bug 报告。目标：为 TeamMode 的"JIT 式优化"做方向性指导，并对照已发布的 v1.5.1 源码逐项标注落地状态——哪些机制已经代码化、哪些仍是设计/待办，全部收敛在纯官方插件 API 约束下（不破坏性修改 OpenCode 桌面版）。

修订说明 v3（本次）：在 v2（基于 anomalyco/opencode dev 分支 2026-09-10 源码）基础上，对照 Te-River/Opencode-TeamMode v1.5.1 实际实现（main 分支 2026-09-09 最新提交，含 pt07 harness 修复）逐项核验，新增"落地状态对照"章节。核心结论：运行时层 JIT 从"设计/近似"升级为"已代码化落地"——tm_* 工具层 + R6 环境保护 + PT-07 基线均已进入源码。

---

一、背景（更新）

TeamMode 通过官方插件机制（V1 server() + config hook）注入多 agent 角色与 slash 命令。v1.5.1 已把 JIT 运行时层的核心——阈值卸载 + 句柄取回 + 只读治理——做成代码级实现，并配套 PT-07 基线套件用于 A/B 验证。本备忘记录：

1. 哪些 JIT 机制已在 v1.5.1 落地（附源码位置）；
2. 哪些仍是设计 / 待办（附原因）；
3. 纯官方插件 API 下不可绕过的结构性边界（不变）。

二、落地状态对照（v1.5.1 源码核验，main 2026-09-09）

2.1 已代码化落地（✅）

JIT 机制	v1.5.1 实现位置	说明
中间结果瘦身（防上下文爆炸）	src/tm/tools.ts（govern() / shouldOffload）、src/tm/config.ts	结果 ≥ TM_OFFLOAD_THRESHOLD（默认 2000 tokens，chars/4 估算，等于阈值也卸载）→ 全量落盘 run store，回传句柄；低于阈值才内联
按需上下文 / 惰性取回	tm_fetch（tools.ts）+ src/tm/store.ts	句柄分页取回：mode:"structure"（~100-token TOC/键树）+ offset/limit 翻页（上限 TM_FETCH_MAX_LINES 2000）
内容感知预览（防止句柄本身膨胀）	src/tm/preview.ts	JSON/CSV/log/code/binary 五分支；硬上限 TM_PREVIEW_MAX_TOKENS（80 tokens），clue + hint 优先保活
句柄鉴权（防伪造/跨 run）	src/tm/refs.ts（HMAC-SHA256 + timingSafeEqual）	access_token = HMAC(进程随机 key, run_id)；跨 run / 篡改 / 过期一律拒绝，固定话术提示重跑
只读治理 R1	src/tm/guard.ts（P2 路径 + P3 命令白名单）	P2 realpath 防 ../symlink 越界；P3 白名单 + 重定向/命令替换/find -delete/tail -f/awk system() 等硬化
环境变量读取保护 R6	src/envprotect.ts + tool.execute.before hook	代码级拦截 env dump / $env: / env 文件路径；tm_* 别名映射到内置工具，双重防绕过；审计只记工具名+类别，不记值
运行载荷存储 + Trajectory	src/tm/store.ts	.blackboard/（index.jsonl + step 文件，append-only）、.trajectory/（steps.jsonl 严格 append-only）；启动期 TTL 清扫（TM_BLACKBOARD_TTL 默认 7 天）
团队黑板 + 自动清理	src/blackboard.ts	.git/opencode-team/ 会话分区；启动 + 每小时 TTL 清扫（默认 5 天），唯一清理路径
插件安装脚本	scripts/install.sh / install.ps1	字符串/注释感知的 plugin 数组注入（修复空数组/尾注释坏 JSON），幂等，8/8 夹具验证
A/B 验证基础设施	pt07/（runner/judge/generate/tasks）	8 任务 6 类固定夹具；GLM 5.3-Flash 基线 8/8 PASS（模式 b，见 §2.3）
确定性路由 + 审批门 + reply skeleton	src/agents.ts / src/commands.ts（v1.4.7 起）	路由表查表、≥2 计划派发审批门、STATUS/CHANGES/FINDINGS/EVIDENCE/HANDOFF 骨架

2.2 仍是设计 / 待办（⏳）

JIT 机制	现状	阻塞点 / 建议
会话级熔断	未落地	experimental.compaction.autocontinue=false + Context Epoch 快照（上游 dev 有入口），需实测后再接
PGO 动态路由（反馈驱动）	未落地	pt07 复测（tm_* 启用态）未跑；需先完成 A/B 拿到返工率/失败率样本
结果级缓存（memoization）	未落地	已批准方案 / 数据契约 / 调研输出按 key 复用；需先定义缓存 key 与失效语义
强制并行子任务	未落地	官方 general subagent（parallel）+ AgentAttachment 结果注入可用，但并发受平台调度约束，待吞吐实测
内置工具（非 tm_*）的输出裁剪	未落地	官方 tool.execute.after 改写 output + TOOL_OUTPUT_MAX_CHARS 可对内置 read/bash 输出瘦身；当前只有 tm_* 走卸载路径
Hot agent 状态常驻	不可行	session 生命周期平台控制，只能结果级缓存（结构性）

2.3 PT-07 基线现状（关键事实）

• 模式 (b)（装有插件、tm_* 零调用、R6 拦截 6 次全部正确绕行）已被采纳为 v1 基线，GLM 5.3-Flash 全量 8/8 PASS（pt07/HANDOFF-GLM.md）。
• 复测（tm_ 启用态）尚未执行* —— 这是证明"JIT 卸载是否真的降 token/降失败率"的决定性实验，是下一步优先级最高的实测。
• harness 已修复：generate.mjs 输出 workspace/package.json（type:commonjs，修复 judge 的 require 检查）、不再向 stdout 打印 ground-truth；judge.mjs 支持 --task 单题模式。

三、纯官方插件 API 能力矩阵（与 v2 一致，不重复展开）

关键结论沿用 v2：多 agent 注册（V2 ctx.agent.transform / V1 config）、slash 命令、工具执行拦截（tool.execute.before/after）、按需上下文（V1 experimental.chat.messages.transform）、会话级熔断（experimental.compaction.autocontinue）均有官方入口；结构性边界不变：

1. 无 agent-to-agent 实时通信通道 → reply skeleton + blackboard 文件是唯一解（已落地）；
2. server 侧插件 API 碰不到桌面版渲染层；
3. 中间结果回流是组装层行为（to-llm-message.ts 全量拼接 + compaction checkpoint 回流）→ 插件只能在发送前拦截裁剪，tm_ 卸载路径是目前唯一能在源头瘦身的方案*（v1.5.1 已落地）；
4. experimental.* hooks 签名可能变化，每条需"失效即降级"兜底。

四、提示词膨胀控制原则（关键红线，不变）

决策逻辑进代码，数据按需读取，提示词只保留本次执行的最小必要信息。

策略内容	错误做法（膨胀）	正确做法
路由表 / pipeline 选择	写进 Team Lead 提示词	代码选路（v1.4.7 已落地：确定性路由表）
评审维度 / 分档规则	写进 system prompt	代码判定档位，只通知本次维度
PGO 历史统计	常驻注入	持久化文件（.trajectory/ 已备），代码读摘要决策
reply skeleton 协议	每次派发重复粘贴全文	固定文本单次注入（REPLY_CONTRACT 已落地）
大输出	全量拼进会话	tm_* 阈值卸载 + 句柄分页（v1.5.1 已落地）

五、参考引用

项目源码（本次核验，main 2026-09-09）：

• src/index.ts：V1 插件入口（server/config/tool.execute.before/tool 段）
• src/tm/{config,refs,store,guard,preview,tools,index}.ts：JIT 层 2 工具全链路
• src/envprotect.ts：R6 环境变量读取保护
• src/blackboard.ts：团队黑板 + TTL 清理
• src/agents.ts / src/commands.ts：多 agent 与 slash 命令定义
• pt07/：基线套件（README/HANDOFF-GLM/generate/judge/runner/tasks）

上游 opencode（anomalyco/opencode，dev 分支 2026-09-10 核验）：

• packages/plugin/src/index.ts：V1 Hooks 全清单（含 experimental.*）
• packages/core/src/plugin/{internal,host,agent,command}.ts：V2 define/PluginContext/内置 agent
• packages/core/src/session/{compaction,context-epoch}.ts、session/runner/to-llm-message.ts
• packages/core/src/tool/registry.ts、packages/schema/src/prompt.ts

社区实证： oh-my-opencode（bunx oh-my-opencode install 纯插件多 agent 编排，与 TeamMode 目标同构）

六、待实测 / 开放问题（更新版）

1. pt07 复测（tm_ 启用态）* —— 最高优先级：与 v1 基线（模式 b，8/8）做 A/B，量化 token 消耗与失败率变化。
2. experimental.chat.messages.transform 相对 to-llm-message.ts 的生效时机：能否在组装后覆盖 compaction checkpoint。
3. V2 ctx.agent.transform 注册的 subagent 在桌面版 UI 呈现/切换方式；与 V1 config 注入的兼容性。
4. V2 ctx.aisdk.sdk 能否在请求出网前拦截改写（决定 JIT 请求级注入可行性）。
5. experimental.compaction.autocontinue=false 后压缩产物与会话恢复的实际行为。
6. 三端（Desktop / CLI-TUI / headless server）experimental hooks 覆盖面核对。
7. general 并行子任务在真实限流下的吞吐。
8. client.session.prompt() 并行/中断语义（AbortSignal）。
9. V1 permission.ask 与自定义审批门控是否双重弹窗。
10. 内置工具（read/bash）走 tool.execute.after 输出裁剪的收益与回归风险。

---

本备忘由 Marvis 协助起草，供项目后续实现时对照执行。2026-09-10 修订（v3，对照 v1.5.1 源码）。
（内容由AI生成，仅供参考）

[Te-River]

仍需注意
1.模型在工作结束后应当自行删除临时写入的脚本