Files
Agent-Workbench/docs/ARCHITECTURE.md
T
2026-10-29 21:09:50 +08:00

5.8 KiB

独立产品架构

产品使用本地 Node 服务和 React 工作台。客户端负责项目选择、对话、工具轨迹、差异审核与设置;服务端负责模型连接、工具调用、会话存储和恢复。

一次任务

用户消息进入会话后,执行器构造上下文并调用兼容模型服务。模型返回工具调用时,执行器按调用 ID 记录 started 与结果。项目读取和检索直接完成;文件改动先生成带原文 SHA256 的提案;终端命令进入确认状态。结果以 tool_call_id 关联回模型,直到得到最终答复或达到步数限制。

改动与权限

提案只保存建议,不修改项目。用户应用改动时重新检查当前文件是否仍与基线一致,原文保存在应用数据目录后再原子替换。读取、检索、提案与应用路径限制在所选项目内,并解析 junction/symlink 的真实位置。

终端命令每次确认后以当前 Windows 用户权限执行;工作目录为所选项目,但这不是操作系统沙箱。界面显示完整命令。停止任务会中止工作台启动的进程树。

持久化与恢复

1.1.0使用SQLite同步事务保存Task/Run/Step/Tool/Check/Event/Artifact记录,状态、追加事件与outbox一同提交,成功提交后再发布会话更新。旧JSON迁移保留原字节备份,旧Store接口通过兼容层保存新契约。大型工具结果与检查日志保存在独立SHA256工件中,读取和恢复均核对归属与字节。

服务重启后把仍在运行或等待确认的任务标为暂停;未完成tool_call按ID写入中断或实际保存的结果以保持消息配对。已开始命令的结果未知时保留需核对状态。执行宿主使用持久owner限制同一数据目录并发写入,停止时释放owner。SSE按持久seq补发,客户端不会因重连重放工具。

工程检查与审核后继续

ProjectInspector识别有界工程文件、语言、规则、npm脚本及当前工程自身的Git基线。CheckRunner将脚本和源码指纹固定为plan;执行前再次核对,在用户确认后创建独立job,保留真实退出码、统计与日志工件。模型通过read_artifact读取已有失败信息。没有实际测试、日志不能识别或源码已变化时,verification不记通过。

应用提案后原Run保留needs_review或明确step_limit暂停历史。continue-reviewed要求当前Task已有应用、无剩余提案/冲突/未知工具,只接续这两种状态;先校验模型配置,再将review-action与新Run一同提交,保留原始目标、用量和resumeOf。主动取消、其他预算和重启暂停通过各自恢复入口处理。

多文件变更集

1.4.0的ChangeSetManager把同Task提案、Git基线和原/新字节快照封存为带SHA256指纹的记录。写入前全批预检,逐文件持久保存意图、同步暂存文件、同目录替换和实际结果;结果未知时启动只标状态,用户显式核对或回退。外部编辑内容按当前哈希保护,临时恢复文件只有类型/大小/哈希一致时复用;详见恢复契约。

模型只准备批次,文件应用/回退由独立审查动作执行。运行、检查、Git和旧逐项应用共享项目互斥与未核对批次检查,界面不能绕过服务端规则。报告记录批次身份/指纹/状态并核对快照完整性。

上下文

1.5.0的RequestContextPlanner固定Task目标、全部追加要求、项目/会话身份和最后用户消息,按原字节选择完整assistant/tool协议组。省略的原组保存为SHA256工件,超大Unicode记录按合法边界分片;有界通知提供实际索引与结果引用。原providerMessages不改写,缺失或损坏的封存证据不会静默重建。

预算以实际请求JSON正文估算,包含系统、工具定义、历史、model/tool_choice/stream及输出预留,工作输入目标最多16000估算tokens。持久保存正文、冻结计划与context_plan记录成功后才联网;Provider核对正文SHA256/字节。实际usage另行保存,重启将未完成计划标interrupted而不重放。API及任务面板可查看历史运行、发送内容和分页原记录;报告深度核对正文、索引、原组、分片和结果归属。详细边界见上下文契约。

模型与凭据

支持 OpenAI 兼容的 Chat Completions 工具契约,服务 URL 和模型由用户配置。API Key 仅在服务内存或专用环境变量中使用,不写入会话、导出或配置文件。默认离线演示明确标记,不连接第三方账户。

工作台诊断与模型错误

每轮系统上下文加入工作台保存的最新执行快照。inspect_session只读取当前会话的错误来源、近期工具、提案状态与终端环境;项目内容和历史工具输出按数据处理。最新审核状态独立于历史助手的措辞。旧fetch failed明确归为模型请求失败,同时保留旧版未记录底层原因的限制。

模型请求记录请求阶段和尝试次数,分类认证、限额、服务、网络、DNS、证书、超时和协议错误。最多三次请求,退避受Retry-After和总时长约束。重试只作用于当前模型请求,已完成工具不再执行;用户停止会取消请求与退避。模型响应验证可以使用临时参数,不改变当前连接。

本地原进程升级

1.0.0升级模块保留现有store/provider/runtime及HTTP服务对象,通过实例原型和请求处理器切换实现。升级前核对本地PID与工件路径并要求无活跃任务,升级后验证配置/项目/会话;Key仍在原provider对象中。原版工件作为源码内置fixture支持独立迁移测试。

验证

使用独立测试项目与本地兼容 API 测试服务验证工具循环、审批、差异冲突、停止和重启恢复。浏览器测试覆盖真实本地界面。真实大模型的效果与用户服务连通性单独记录。