Files
Agent-Workbench/docs/RESEARCH.md
2026-10-29 11:23:43 +08:00

69 lines
6.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 统一机制报告:从 Claude Code 与 Cursor 到本地 Agent 工作台
Claude Code 的工具循环、上下文与恢复机制,以及 Cursor 的工具契约、执行记录与文本改动机制,已集中到同一个独立产品:Agent Workbench。本产品使用自己的 React/Node 代码,把项目、任务对话、工具结果、终端确认与文件差异放在一个工作台中。
## 研究身份与方法
| 目标 | 固定版本 | 工件依据 | 深入核对范围 |
| --- | --- | --- | --- |
| Claude Code | 2.1.312,Windows x64 | 官方 npm 包;SHA512 integrity 校验;EXE SHA256 `6099672ebe5dcb518b67d1d32dde1e3360bc6bee1dae7f8d28a69c49acc7c865` | Bun 模块表指针/编码/范围验证,2,581 个 JS/入口模块;工具循环 27 个选段、上下文与恢复 32 个位置 |
| Cursor | 3.16.29 | 本机分发代码;commit `6246455961129c32969845e00aa25d87ae926ec0`;执行器与 worker 原文件散列 | 19 个关键位置、9 个精确 AST 切片 |
研究采用 REA 静态分析与人工 AST/原字节核对。Claude 工具循环的五份摘录解析成功,所有选段均与 EXE 载体字节一致。原 Bun 虚拟绝对 imports 和部分动态绑定仍未自动解析;自动关系图中的 partial/ambiguous 与人工核对的位置在各报告中分别说明。
没有运行 Claude Code/Cursor,没有读取它们的个人会话或凭据。报告支持所选客户端代码的局部机制,不能证明原版全部运行行为、远端服务或完整源码的恢复。
## 两边互补的机制
| 问题 | Claude Code 静态证据 | Cursor 静态证据 | 本产品 1.0.0 的独立实现 |
| --- | --- | --- | --- |
| 工具身份与输入 | 调用 ID 关联结果;schema 校验;权限改写后再次校验 | 当前工具名映射;缺失工具生成原 ID 错误结果 | 六种固定工具,含本机会话诊断;输入校验;拒绝重复调用 ID;错误结果按 ID 配对 |
| 执行与权限 | 非 allow 分支可早于主要调用返回;权限不是所有模式下都要求人工确认 | 执行包装与 MCP hooks 有条件分支 | 文件读取/搜索直接完成;每条终端命令独立确认,并绑定会话、运行、完整命令与工作目录 |
| 并发 | 只有新项与全部执行项均声明安全时才并发;独占队列形成屏障 | 工具集与执行契约决定可执行范围 | 按返回顺序串行执行;模型请求有限重试,已完成工具不重放 |
| 修改文件 | 工具调用与其结果分别处理 | `cte.apply_patch` 构造文本与引用,本方法自身没有写盘 | 完整文本提案与差异;审核前不写项目;应用时核对 SHA256 基线并备份原字节 |
| 上下文整理 | 预算、有效摘要校验、hooks、连续失败保护与快速回填保护 | 研究未完整追踪其上下文压缩服务 | 保留完整磁盘历史;请求使用提取式投影;保留近期用户指令及工具 ID 配对;记录估算与服务 usage |
| 中断与恢复 | UUID/parentUuid 构链、残缺记录和未完成调用识别 | 重建当前工具集;恢复执行契约可选,缺失时回退当前集合 | 重启把执行/等待项标为暂停或中断;保留提案;补齐未完成调用结果;继续任务时重新请求终端确认 |
| 前端重连 | 本研究未证明全部跨进程持久性 | worker 身份、安装/spec 校验及本地连接复用 | 浏览器与本地任务服务分离;关闭页面不自动停止服务;SSE 与 revision 同步当前会话 |
## 一次真实的产品流程
```mermaid
flowchart LR
Task[项目任务] --> Model[兼容模型服务]
Model --> Tools[校验工具调用]
Tools --> Read[读取与搜索]
Tools --> Proposal[文件提案]
Proposal --> Review[查看差异]
Review --> Baseline[核对文件基线]
Baseline --> Apply[备份并写入]
Tools --> Ask[确认完整命令]
Ask --> Command[在本机执行]
Read --> Result[按调用 ID 保存结果]
Command --> Result
Result --> Model
```
提案的“已保存”表示建议保存在会话里。只有“已应用”才表示项目文件已经写入。调用进入执行阶段,也不能单凭这个标记证明系统副作用发生;中断后应查看实际文件与输出。
默认离线演示是固定脚本,依次调用真实项目列表、文件读取、提案和 `node --version`,用于体验整个流程。它不进行模型推理。连接支持 Chat Completions 工具契约的服务后,工具调用由所选模型产生。
## 已验证的产品行为
- 34项行为测试通过:工具循环、命令确认/拒绝/取消、提案/冲突、原字节备份、路径、Key不落盘、崩溃恢复,以及会话诊断、中文管道、分类请求错误/重试和原进程升级。
- 10组基础UI、9组异常UI及可运行包验收结果见 [VALIDATION.md](VALIDATION.md)。
- 用户真实gpt-6.1-sol已通过文件读取/提案/应用,并在1.0.0原会话通过inspect_session解释历史错误与当前applied状态;受控fixture结果分别记录。
## 当前本地版边界
当前版本包含本地项目与会话、文本工具、完整内容提案、逐次命令确认、历史与恢复、模型设置、分类错误与诊断、会话/建议导出和研究报告。MCP动态注册、并发调度、语义检索、多文件事务、模型生成摘要和原生桌面壳仍是后续设计空间。
终端工作目录是所选项目,命令确认后以当前系统用户权限运行,最长 60 秒;它不是操作系统沙箱。读取/搜索/提案/应用则在服务端校验项目范围和真实链接位置。
## 详细报告与来源
- [Claude Code:工具循环、权限与结果](research/TOOL-LOOP.md),索引 `research/TOOL-LOOP.evidence.json`。
- [Claude Code:上下文压缩与会话恢复](research/CONTEXT-RECOVERY.md),索引 `research/CONTEXT-RECOVERY.index.json`。
- [Cursor:工具执行与恢复](research/CURSOR-MECHANISMS.md),索引 `research/CURSOR.evidence-index.json`。
完整 REA Evidence 和研究工件仍保留在原工作区的 `Claude-Code-REA` 与 `investigations/cursor-agent`。产品发行包包含这些报告和小索引,不包含第三方客户端原二进制、完整提取源码或大体积分析切片。