Files
Agent-Workbench/README.md
T
2026-10-29 11:52:04 +08:00

88 lines
7.5 KiB
Markdown
Raw 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.
# 本地 Agent 工作台
Agent Workbench 1.0.0 将 Claude Code 与 Cursor 的机制研究整合为一个独立的本地 AI 编程工作台。一个页面内完成项目选择、任务对话、文件读取/搜索、工具轨迹、差异审查、命令确认、运行诊断与会话恢复。这是已验证的基础里程碑,持续完成真实工程任务的能力按后续方案逐步建设。
本次正式版补充工作台自身的错误诊断与当前执行状态,使助手可以区分模型连接失败、终端失败和文件审核状态。版本改动见 [CHANGELOG](CHANGELOG.md)。
## 后续产品与能力建设
目标是自有Harness核心、用户选择的大模型、REA研究工具和可选外部代理引擎共同完成“需求→工程理解→代码变更→实际测试与修复→审查→Git交付”。研究对象为Codex、Claude Code、Cursor、DeepSeek Harness、WorkBuddy与DSH-purge;研究结论、独立实现和实际验收分别登记。Purge是Harness插件,其工程收益需要版本锁定和同题对照验证。
- [完整产品与执行方案](docs/PRODUCT-PLAN.md):M0–M6阶段、模块、真实任务和Electron/PWA分工。
- [24项能力与验收矩阵](docs/CAPABILITIES.md):当前基础、待开发目标、来源和完成证据。
- [研究路线](docs/RESEARCH-ROADMAP.md)与[目标来源登记](research/targets.json):版本、来源、SDK限制及未解决问题。
- [本地Git流程](docs/GIT-WORKFLOW.md)与[项目执行规范](AGENTS.md):源码仓库已建立,main基线`bac87da`、标签`v1.0.0-baseline`;后续按独立小步检查并及时提交。
高级任务图、工程索引、patch/ChangeSet、用户工程Git/worktree、结构化测试修复、多worker、外部引擎、REA执行和桌面/手机配对仍在规划中。下一轮先建设可靠任务状态与真实工程交付切片。
## 直接运行
Windows x64 便携包自带 Node.js 24.22.1。解压后双击 `Start-Workbench.cmd`,浏览器打开 `http://127.0.0.1:4318`。双击 `Stop-Workbench.cmd` 可停止服务及它正在运行的任务。
启动不需要安装 npm 依赖或管理员权限。窗口关闭后本地服务仍运行,任务与会话继续保存。再次打开相同地址即可查看记录。
1. 打开自带示例项目,或点击项目栏的「+」输入本机项目文件夹路径。
2. 输入任务并发送。默认「离线演示」使用固定脚本调用真实本地工具,不进行模型推理。
3. 终端请求会显示完整命令、用途和工作目录,确认后才运行。
4. 文件建议先成为提案;查看右侧差异,点击「应用这项改动」才写入项目。
5. 点击「模型连接」,选择兼容模型服务,填写接口根地址、模型和按需填写的 Key;可先「验证模型响应」,再保存连接。
6. 遇到请求失败,点击错误卡片的「查看运行诊断」。可在同一会话提问,助手通过本地 `inspect_session` 核对错误来源、近期工具和文件实际状态。
## 模型连接
支持 Chat Completions 的 `tools/tool_calls/tool_call_id` 契约。填写服务实际提供的接口根地址:例如 Ollama `http://127.0.0.1:11434/v1`、vLLM `http://127.0.0.1:8000/v1`;部分兼容服务直接使用域名根地址。工作台在其后请求 `/models` 或 `/chat/completions`,不会强制添加 `/v1`。所选模型和服务需支持工具调用,可以读取模型列表或直接填写模型名。
模型网络故障、DNS、证书、超时、身份、限额和接口响应错误分别记录。可恢复请求最多尝试三次,尊重服务的 Retry-After,并限制总时长;401/403 和无效或过大的 JSON 不自动重试。停止任务会取消请求和退避。错误卡片的「重试模型请求」沿用已完成工具结果。
API Key 只在当前服务内存中使用,不写入配置、会话或导出。重启服务后需重新填写;也可在启动前设置专用环境变量 `AGENT_WORKBENCH_API_KEY`。工作台不读取其他应用的登录信息。
接口契约已由本地 HTTP 测试服务及浏览器验证。用户随后配置的 `gpt-6.1-sol` 已通过真实读取、提案与应用验证,见[模型连接实测](docs/MODEL-CONNECTION.md)。
## 文件、命令与恢复
读取与搜索仅处理项目范围内的 UTF-8 文本,并限制文件体积/搜索数量,跳过依赖目录、链接与常见凭据文件。文件提案保留原文 SHA256;应用时发现外部改动会拒绝覆盖。原文备份保存在数据目录的 `backups` 下,保留原字节。
终端命令逐次确认,最长 60 秒,有输出上限,确认后以当前系统用户权限执行。项目工作目录不是操作系统沙箱。停止任务会中止工作台启动的进程树。
数据默认保存在 `%LOCALAPPDATA%\AgentWorkbench`。会话 JSON 原子替换并保留 `.bak`;服务意外退出后保留待审查提案,将未完成调用标为中断,不自动重放命令。暂停后可「继续任务」,沿用已保存的模型消息;待审查状态显示「审核 N 项」,已完成状态可以发送新的任务内容。
Windows 终端使用 PowerShell 5.1,通过 UTF-8 stdin 传入经确认的完整脚本,同时设置输入、输出和 `$OutputEncoding`。多条命令用换行组织,不能使用 `&&` 或 `||`;原生命令的 `$LASTEXITCODE` 会成为执行结果。
完整历史保存在本地,模型请求使用提取式上下文投影。工作台显示 token 估算,服务返回的实际 usage 另外记录。
## 研究与验证
- [统一机制报告](docs/RESEARCH.md):原版静态证据与本产品实现逐项对照。
- [详细报告与证据索引](docs/research):Claude Code 工具循环、上下文/恢复,以及 Cursor 工具执行/编辑。
- [验收记录](docs/VALIDATION.md):34 项行为测试、10 组基础界面与9组异常专项流程、便携包测试与截图。
- [正式版验收清单](docs/QA-1.0.md)与[保留连接的升级说明](docs/UPGRADE.md)。
- [独立架构](docs/ARCHITECTURE.md)与[界面设计](DESIGN.md)。
原版研究没有执行 Claude Code/Cursor,报告不表示恢复了全部源码或验证了远端服务。完整分析工件保留在原研究工作区;本产品包不包含第三方客户端原二进制、完整提取源码或大体积代码切片。
## 源码开发
使用 Node.js 24;依赖版本由 `package-lock.json` 固定。
```powershell
npm.cmd ci
npm.cmd run build
npm.cmd test
```
启动构建结果可运行 `npm.cmd start` 或双击启动脚本。前端开发使用 `npm.cmd run dev`,另开终端运行构建后的本地服务。
UI 验收先启动独立测试服务(指定不同数据目录),然后依次运行 `npm.cmd run verify:ui` 和 `npm.cmd run verify:diagnostics`。脚本默认检查 `http://127.0.0.1:4319`,使用本机 Edge;可用 `AGENT_WORKBENCH_URL` 指定其他独立测试地址。验证器要求测试服务为离线演示且未配置 Key,防止覆盖用户连接。它会创建工作区内的 `.qa` 测试项目。
```powershell
$env:AGENT_WORKBENCH_DATA_DIR = Join-Path (Get-Location) '.qa\browser-data'
$env:AGENT_WORKBENCH_PORT = '4319'
npm.cmd start
```
端口默认 4318;`AGENT_WORKBENCH_PORT` 与 `AGENT_WORKBENCH_DATA_DIR` 可覆盖。不同服务实例应使用不同数据目录。
构建后运行 `npm.cmd run package` 生成便携和源码 ZIP。打包脚本优先使用相邻 `tools/node-v24.22.1-win-x64/node.exe`;也可指定 `AGENT_WORKBENCH_NODE_PATH`,须同时存在对应的 Node LICENSE。
第三方许可见 `THIRD_PARTY_NOTICES.txt` 与 `licenses/`。本工程原创代码的对外许可由项目持有人决定。