Files
Agent-Workbench/docs/TIANSHU-HARNESS-SOURCE-REVIEW.md
2026-11-04 10:03:32 +08:00

31 KiB
Raw Permalink Blame History

Tianshu Harness 深度源码审查:对 Agent Workbench 的启发

结论:有很大参考价值,最值得学习的是长任务的运行管理、证据状态和上下文工程。应将这些机制接到我们已有内核上,分项验证;没有依据整套替换工作台,也没有依据把提示策略当成模型权重能力提升。

本报告根据固定公开源码独立分析,不改编作者另行许可的理念文档或实证报告。源码索引、原探针与采用计划见文末。产品仍为 1.24.8,本轮没有产品代码变更、服务升级或真实模型请求。

1. 研究对象与结论可信度

项目 本轮实际核对
仓库 https://github.com/huiliyi37/Tianshu-harness.git
固定提交 2d0b22e0b3554686e1e4131f8bdc568ef768e060,非浮动 main
提交说明 sync: from dev repo (v3.37.4 stable rev45)
包版本与运行环境 3.37.4;TypeScript / ESM;Node `^24.22.1
可复核规模 Git 跟踪 4599 文件;src 下 TS/TSX 3772 文件;按测试路径/命名排除后,1709 源码文件、338689 行;测试文件 2063;hooks 源码文件 75
已封存索引 63 个第三方关键文件及 14 个工作台对照文件,包含 SHA-256、字节、行数、固定提交链接
代码许可 Apache-2.0 S02;两份文档单独声明 CC BY-NC-ND 4.0,见第 13 节
公开边界 有 CLI/TUI、服务端、VS Code 扩展及多种工具代码;公开树没有 desktop/、src/pro/
实际执行 只运行了五个已读纯模块的隔离探针,六个输入;没有启动第三方应用、安装依赖或跑完整测试集

这里区分四种证据:源码可见、调用链已核对、纯函数实际执行、作者公布的效果数据。前两项证明机制存在及如何接线,纯探针证明指定输入的行为;它们都不能单独证明完整系统的工程交付率。

源码量按 git ls-files 和 UTF-8 splitlines() 统计,不等于复杂度、质量或测试通过数。README 的“2.3 万测试”属于作者指标,本轮没有运行这些测试。S03

2. 系统到底是什么

这是一个独立的编程代理运行时。CLI 命令 tianshu 与兼容命令 rivet 指向同一个入口;入口再进入主程序、装配模型客户端、会话、提示引擎、工具和 AgentLoop。S01S63

它把五类东西放在模型之外管理:任务目标、工具权限、上下文预算、行为进展、成果与证据。模型仍然决定下一步读什么、改什么、如何回答;运行时负责构造输入、执行受控工具、记账、取消和判断状态。

下面是依据实际模块整理的简化链路,并非所有分支的完整控制流图:

flowchart TD
    U[用户输入或继续追问] --> T[任务边界与 TaskContract]
    T --> P[preTurn 与感知]
    P --> A[afterPerception:状态、约束、建议]
    A --> C[PromptEngine:冻结块与增量附录]
    C --> B[最终请求预览:上下文与图像体积预算]
    B --> M[已选 Provider / 模型客户端]
    M --> Q{是否请求工具}
    Q -->|是| G[模式、权限、参数、审批与所有权检查]
    G --> E[冻结参数、取消信号、实际执行]
    E --> R[原始结果、工件、验证证据与结果预算]
    R --> H[postTool 与后续回合状态]
    H --> K[postTurn:收敛、提醒回读、进展]
    K --> P
    Q -->|准备结束| F[结束候选与未决证据状态]
    F --> Z[答复 / 阻塞披露 / 有界纠偏]
    Z --> S[postSession:知识准入、技能草稿等条件钩子]
    G -.派发子任务.-> W[工单、固定模型策略、只读或写工工作区]
    W --> V[主控复验与派发目标对账]
    V --> R

五阶段接口定义在 runtime-hooks.ts,具体组装在 create-runtime-hooks.ts,由 loop-factory.ts 实际创建。感知、工具执行、回合编排分别在自己的模块中消费,不能只看类名就假定所有机制都启用。S04S06S08

3. 任务契约与用户验收:目标独立保存,但语义判断仍有边界

TaskContract 保存 objective、scope、constraints、successCriteria 和状态。短追问被区分为聊天、继续原任务或新任务,“继续”可保留原目标,追加限制可以合入原契约。S10

这能解释它怎样应对长对话:不要求模型从几百轮历史中重新猜“最初要做什么”。不过分类依赖关键词、正则和长度等启发式;它不是完整的用户意图理解器,更不是权限来源。

更有价值的是 EvidenceObligation:按断言类型记录 open、attempted、satisfied、blocked、superseded,并用稳定 ID 与单调状态版本跟踪变化。模型说“完成了”、工具运行成功和要求被满足是不同状态。S11

在 loop.ts 的 captureAcceptance() 中,用户可观察验收独立于测试结果:单元测试通过不会自动关闭 acceptance;需要显式回写每项“用户做什么、应该看到什么、实际证据是什么”。S13

需要补强的边界:decideAcceptanceOutcome()(evidence-obligation.ts:545)对已满足项的 evidence 只检查非空文字。这并不核验它来自哪个真实浏览器结果、Task、源码 SHA 或用户操作。RED 编辑门也按同一义务只强制拦一次,重复请求可通过;当前验证/验收缺口主要披露,不自动续轮。S11

对我们:直接接续 1.25 任务要求与交付复核。我们已有 Task/Run、计划修订、证据工件和 SHA 绑定,应增加“要求 → 当前成果 → 证据 → 仍未验证事项”的对应关系,而不是重新引入一套靠自由文本证明完成的状态。

4. 五阶段 hooks:值得学习的装配结构,不是 75 个硬门

RuntimeHookPipeline.runPhase() 按注册顺序串行执行,每个 hook 有超时、取消信号、运行状态和耗时。超时后封锁其 effects 通道,迟到的结果不能继续通过这个通道写共享状态。下一 hook 获得新的作用域。S04

具体意义有三点:监督逻辑可以分模块关闭;一次慢提醒有独立归因;取消后继续回写的竞态可以被限制。串行执行也意味着总延迟可能是多个 hook 延迟相加,不能只检查每个 hook 的上限。

但普通异常记录后会继续;HookCleanupUnconfirmedError 才特殊传播。effects 的封锁也不等于能强制终止任意已经发起的外部副作用。装配还受依赖和环境条件影响,并非 75 个文件全部常驻。S04

对我们应分两条链:权限、预算、SHA、归属和实际执行检查由确定性硬门负责;建议、提醒和行为观察由可失败的监督模块负责。 两条链都要有 Task/Run 归属、总时限和明确的故障结果,不能把权限判断交给“提醒模型遵守”。

5. 收敛检测:思路可用,已实测发现一个反例

检测器综合近期工具目标的新颖度、工具分布、写入、错误、输出效率、振荡和重复文本,并按任务阶段、上下文窗口、真实进展信号调整。等待验证可以避免被误判成空转;没有任何工具的多轮行为另有硬停止条件。S16S18

这比“连续读 N 次就要求写代码”合理:研究任务可以长期只读;一次测试等待也不等于停滞。我们尤其需要区分同文件不同偏移的新页、相同 SHA 的重复页、真实新增失败证据与重复查询。

已执行的纯检测器探针

仅装载五个已读模块,使用现有 TypeScript 转译后调用 evaluateConvergence,模块及调用均设超时。未暴露 process、require、fetch、定时器或文件系统全局;这只用于受审查纯模块的执行限制,不宣称是可运行恶意代码的通用安全沙箱。

输入 返回原 score level abort
上游 W4 测试的高错误率 fixture 0.5164603 L1 false
六次重复读取同一文件 0.082125 L2 false
同上,额外传错误率 0.5 0.082125 L2 false
六次相同失败读取,错误率 1 0 L2 false
重复读取,但正在等待验证 0.082125 L1 false
连续五轮无工具,错误率 0.8 0.0485567 L3 true

convergence-detector.ts:1087 的实际公式为:

const effectiveScore = (input.recentToolErrorRatio ?? 0) >= 0.4
  ? Math.min(score, 0.41)
  : score

附近注释称高错误率要把纠偏降到 L1;但分数越低纠偏越强,1177–1182 又以 <=0.4 触发 L2、较低阈值触发 L3。min 无法将低分抬出 L2 区间。上游 W4 fixture 本来分数较高,不能覆盖“低分且高错误”的组合,新增纯输入复现了反例。S16

这是指定检测器输入的逻辑反例。完整运行时还有 veto、阶段及发射条件,本轮没有运行完整应用,不推断所有生产场景一定出现提醒洪流。也没有修改第三方源码或向作者发送 issue。

另一个避免误读的例子:exploration-stall.ts 写了 12/15 次阈值,但当前生产源码检索没有找到调用点,只能列为未发现接线的实现,不能算已生效能力。S20

对我们应先以 shadow 模式记录判断,人工与固定样本核对误报,再启用少量提示。不能把这个评分公式直接接成停止或强制编辑门。

6. AdvisoryBus:让提醒有预算、有效性和退出条件

它把多个提醒源合流,按 key 去重,带优先级、类别、TTL、观察期和通道。普通提醒每轮最多三条,另有类别额度;建议可以先观察,条件已自然满足时撤销,减少反复打扰。S14

提醒还可携带 expect:后续工具行为满足某个可观察条件就记 adopted,否则 ignored。连续忽略会升级、冷却或静音;低采纳提示不会永远占着每轮输入。S14

runtime-advice-facts.ts 只引用当前实际工具及新鲜的预算快照,没有事实就承认未知。这与我们此前“答复与当前工程脱节”的问题直接相关。S15

边界也要看到:高等级提醒存在预算豁免;出现过某工具不等于问题被解决;采纳相关性不等于提醒造成收益。我们的实现应给提示总字节和总 tokens 设上限,禁止建议绕过审批,并统计“送达后是否增加真实成果”,而不只统计模型是否服从。

7. 前缀缓存与压缩:最可迁移的工程能力之一

PromptEngine 将相对稳定的系统/工具块冻结,把变化信息放到尾部增量附录,减少每轮重建长前缀。用户消息按实例冻结,不能把相同文本的两次“继续”当同一条。旁路构造也不能污染主会话的冻结状态。S29

缓存和上下文容量是两个问题:缓存命中可以降低计费,但很大的缓存输入仍占上下文和上游处理资源。因此应同时看实际输入、输出、缓存命中、总 tokens、延迟和交付结果。

当前真正的容量入口是 RequestContextController.prepare() → prepareContextRequest()。先使用 provider 的请求预览,再量实际规范化请求;超限时尝试压缩,重新测量,仍不满足就拒绝。S30S33

历史图像整理和压缩采用事务思路:归档原历史、保护真实用户边界、写入前检查源历史是否变化、提交后更新冻结状态。不能只在内存删几条消息就声称解决容量问题。S30

**文档漂移:**旧 architecture-overview.md 仍写“只在 turn0 边界压缩”及旧压缩链。当前 CompactBoundaryCoordinator.runCompaction() 已只观察取消、返回 compacted:false,真实压缩转到请求预算流程;照旧文档理解当前代码会出错。S58

对我们:U 已修复同 SHA 片段聚合和当前事实保留,不能为了缓存再次丢掉已读页、原检查或完整用户要求。先测每轮实际请求中哪些前缀字节变化及其原因,再做稳定性优化;保持现行 16K/2048/1600 预算,不用扩大窗口掩盖问题。

8. 工具 surface:注册、可见、可执行是三种状态

describeToolSurface() 分别记录 registered、visible、cold、unavailable、unregistered 等状态,以及定义的实际字符和字节。工具 preset 在会话装配期决定,新配置不直接改已运行会话的冻结前缀。S34

不要照抄“最多 26 个工具”:当前 preset 注释列的是 minimal 36 注册/26 主控可见、frontend 37/27、orchestration 36/30,另有 MCP、桌面或强制额外工具。默认档和旧局部注释也不完全一致,应看实际过滤后的 schema。S34

对我们最实用的是保存本次实际送到模型的工具清单、schema 摘要、字节数与 generation。模型说没有浏览器能力时,就能查清是未挂载、没有当前 tab、无权限、工具被过滤,还是模型没有使用。冻结描述不能冻结撤权:真正执行前仍须读取最新权限。

9. 工具流水线:审批的是具体输入,执行前还要复核

公开 tool-pipeline.ts 包含模式与 deny 检查、风险判断、运行预览、审批、所有权、实际执行及证据归账。S27

值得迁移的是顺序:审批允许用户修改参数,修改后重查 deny 和风险;等待期间状态可能变化,实际派发前再次核对;然后冻结输入、组合父取消与工具超时信号,再执行 registry 工具。不能审批 A 参数后悄悄执行 B 参数。

超时提示明确:停止等待不代表底层执行一定结束;先核对原任务、日志和已发生的文件副作用,不直接重复发命令。我们已有所属作业、停止和 unknown 状态,这种语义应持续保留。

这条管线也相当复杂。适合提炼小接口与不变量,不适合将两千多行模块原样搬进我们 runtime。

10. 交付门:必须保留我们的完成定义

DeliveryGateV2 区分自有修改与外部修改,核对验证快照和输入指纹,评估测试范围、过期证据及 GREEN/YELLOW/RED。它回答的是当前修改对应的验证情况。S22S25

但当前 deliver-task.ts:403–405 明确:commit 用于保存成果,验证走 run_tests,审查走 review_changes,三者分开。 验证缺口披露,不因此阻止所有权限定的提交。跨会话冲突、版本、索引锁等是另一些提交门。S23

由此有两个容易误判的点:没有自有修改时 gate 可以 GREEN,不等于用户目标已完成;README 顶部对比图的 alt 仍说“RED 拒绝交付”,与 README 正文 55/273 及当前实现矛盾。应以固定源码和当前正文语义为准。S03

我们 GitDelivery.plan() 当前要求源码一致、日志完整、测试数量明确的通过记录,另核验已配置的浏览器和任务计划。这个契约应继续保持。未来若增加“保存工作快照”,应独立命名、状态和权限,不能把尚未验证的保存当成已交付。

11. 多智能体与模型线路:值得学固定身份和回收对账

WorkOrder 记录 objective、scope、文件、constraints、profile、authority 和 budget;只读工具与写工工具分层。写工可使用独立 worktree,也存在显式共享工作区模式,不能一概称所有写工都物理隔离。S37

运行时实际接线已核对:

  • createWorkerRuntimeFactory() 每个工单冻结一次模型策略;新设置仅影响新工单。S38
  • worker 恢复要求完整历史、冻结快照与 prefix proof;当前 maxRetries=0,单次执行客户端禁止隐式重试。S39
  • 回合数按工单与 runtime 较小值限制;墙钟超时、父取消和一次软收尾都有实际处理。maxTokens 的报告输出档位不能等同我们全任务累计 token 额度。S37S39
  • hands-session 对真实工作区执行主控复验,0 项测试不能冒充通过;当前复验失败/阻塞即终态,repairCount=0,不是自动再修一轮。S40
  • coordinator 确实调用 reconcileWithObjective(),把派发侧 objective 盖回结果。空壳、验证工没验证及部分写工越界有不同处理;没有 transcript 的部分判断降为 risk,不能称完全证明目标达成。S42

模型连接支持 provider 下多个 key 和各自模型清单;显式 provider/keyId/model 有用,但未指定 key 时撞名首个命中,多个 key 并不自动证明实现了轮询号池。S44

FallbackStreamClient 支持部分错误后的备用线,但已有主前缀证明或 singleAttempt 时直接抛错,防止执行身份悄悄变更。这提醒我们区分默认模型选择、新工单角色路由和已运行任务身份。S46

我们已有模型池、协议、身份快照、用量与 Retry-After 记录,以及 worker 父工程审查。接下来应补可解释的选择与连续性,不应为借鉴它反而丢掉既有轮询、冷却和错误原文。

12. 记忆、Skills 与“自我迭代”的真实含义

统一记忆支持 observed/claimed/verified/rejected/expired、来源、有效期和替代链;召回时排除已失效条目。此处核心 recallMemoryEntries() 采用关键词命中、标签和 confidence 排序,并非可以不加限定地称作向量语义检索。S49

EssenceGate 将候选交给侧路模型,要求可迁移范围、失败素材淘汰原因及有效替代对象;LLM 失败或无效输出就不写。自动形成/整合默认关闭,有明确开关。S47S50

但获准记录会写成 status:verified,这表示知识准入判断,不等于该条经验经过独立源码/测试验证。我们应分开“模型建议”“已核对来源”“工程验证”“用户确认”,继续保留当前项目记忆的来源 SHA 和失效规则。

skill-distill 从成功且有验证的轨迹确定性整理技能草稿,放在 _drafts,经 review/approve 才进入发现流程。它不是训练模型权重,也不是自动重写自身系统。S51

Skills 采用发现摘要与按需全文两层;MCP 有连接审批和工具清单指纹;插件入口会动态 import,具有实际代码执行能力。生态能力要有来源、版本、关闭/撤销、权限和 schema 变更记录,不能只做“一键安装”。S53S55

对我们,最合适的自我迭代路线是:真实失败/成功轨迹 → 经验草稿 → 独立复核 → 候选模块 → 固定评测 → 审查采纳 → 独立发行 → 可回滚。 现有 evaluation 与自身模块受控采纳应继续使用,多模型参与也不跳过这些环节。

13. 哪些宣传与边界不能直接采用

项目 本轮结论
99.3–99.6% 前缀命中、刊例价约 ¥880→¥20 README/观测文档公布的 5 个 DeepSeek 长会话、2001 请求数据。未独立取得完整日志重算;刊例估算不等于实际账单或我们的收益。S03
5 任务 A/B 行为改善 README 自述为单模型、小样本、LLM 审查;不足以证明通用交付率、Purge 收益或所有模型改进。S03
75 hooks / 2.3 万测试 文件/作者统计不等于当前全部启用、全部硬门或本轮全测通过。
完整桌面、离线语音、手机与电脑操控 可以看到文档和桥接;公开树缺 desktop/src/pro,computer-use 执行实现移至闭源目录。不能从接口推出完整实现已审计。S56
超过模型本身能力的“破甲” 本轮可观察的是提示、工具、状态和执行策略,未训练权重,未证明权重能力提高。应独立测交付收益。
全量源码照搬 会引入不同提交语义、默认策略、复杂度与许可义务,风险高于按模块独立实现。

许可范围也必须准确:代码总体 Apache-2.0;docs/CVM运行时对Agent模型的实证影响.md 与 docs/reference/cvm-cognitive-runtime.md 单独声明 CC BY-NC-ND 4.0。本研究仅登记其许可并提供原文链接,不复制、摘编或改编两份文档用于工作台材料。S60

14. 和我们现有系统对照,避免重复造轮子

方向 Agent Workbench 已有 本次值得补的增量 保留的约束
长任务目标 Task/Run、任务契约、计划修订与要求哈希 1.25 每项业务要求和证据覆盖 原话/修订来源,推断不是授权
工作记忆 U 同 SHA 真实片段聚合、原来源与当前失败/检查事实 需求覆盖和每轮证据变化摘要 不丢已读页,不造未读信息
防空转 跨 Run 无进展保护、读取进度暂停 单轮语义变化/错误分类,先 shadow 合法只读、等待与阻塞保护
上下文 实际请求计划、预算、配对和工件哈希 工具 surface / 前缀漂移测量 16K/2048/1600 保持,主线不被侧路污染
模型池 连接选择、池路由、身份/用量/原错误 工单角色选择与身份连续性解释 不静默换型号、保留未知消费
工具执行 审批、实际作业、取消/恢复 统一监督生命周期与提示反馈 硬权限与软建议分开
项目交付 真实检查、日志/源码 SHA、浏览器/计划与范围 Git 用户可观察要求的完成度 不用提交快照冒充交付
多智能体 隔离 worker、预算、父工程审查 派发目标和回收结果对账 子工不能独立发布或接管权限
经验积累 有来源项目记忆、Skills/MCP、受控候选评测 成功轨迹草稿与失效反馈 默认不自动生效,不把 LLM 评价当测试
桌面/手机/浏览器 已有各自发行与实际验收路径 工具当前可用性与错误可解释 不因第三方文档重复扩大本阶段范围

对照入口:src/server/runtime.mjs、src/core/context/{working-set,request-plan,delivery-progress}.mjs、src/core/tasks/{task-plan-manager,worker-manager}.mjs、src/core/git-delivery.mjs、src/core/models/model-hub.mjs、src/core/memory/project-memory.mjs、src/core/evaluation/evaluation-manager.mjs。具体字节身份在 source-index 的 productFiles 中。

15. 采用顺序与可复核材料

建议先做 1.25 要求与证据复核 + 单轮进展 shadow;再测工具 schema 与前缀漂移,接入有预算的提醒;其后做经验草稿和角色路由。每个切片先离线固定场景,再独立真实模型样本,不能以提示数量代替任务成功。

详细模块、完成门槛、回顾点与真实实验规则见 采用计划。原有真实 Node 交付、React/Python 和 Purge 实验继续单列;V 已按其冻结规则结束,不续跑旧失败样本。

证据目录 tianshu-research-evidence 包含源码身份、原始纯探针输出、原驱动惰性文本和封存清单。验证器 verify-tianshu-research.mjs 默认只做本地文件校验;指定源码目录后核对固定提交、源码 SHA、行号和工作台对照文件,不启动服务或访问模型。

固定源码引用