Files
Agent-Workbench/README.md
T

135 lines
19 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 将 Claude Code 与 Cursor 的机制研究整合为独立的本地 AI 编程工作台,并内置模型池、项目记忆、Skills/MCP、REA 工件研究、受控DeepSeek Harness工程引擎、实际页面验收和有依赖的执行计划。工程索引、精确补丁、多文件整批审查、Node/Python实际检查、浏览器交互、本地Git提交及交付报告可以在同一个Task中完成。
1.15.0桌面阶段已实现并通过A–E专项验收:Windows宿主身份/单实例、可选择的本机加密连接、Electron窗口与本机项目入口、安装/更新/回退/卸载、分页历史工件巡检,以及桌面Node/React/Python工程交付。窗口关闭后后台宿主继续保留任务,重开恢复同一记录。最终独立发行与正式部署正在F验收,当前正式服务仍为1.14.0;见[1.15验收与实际范围](docs/QA-1.15.md)、[桌面使用说明](docs/DESKTOP.md)。
1.14.0已正式本地交付固定版本的受控引擎与工具/模型桥,原生prompt、审批、预算、原结果和停止进入所属Task/Run;独立工作区成果由父工程审查、检查及Git交付。Purge两版本来源锁定的提示实验默认关闭。三个真实功能工程13节点、23类178组UI、独立源码445/445及最终源码/便携验收通过;原PID、模型连接和全部历史保持,部署后14页复验通过。当前[本地工作台](http://127.0.0.1:4318/?release=1.14.0)、发行身份与具体结果见[QA-1.14](docs/QA-1.14.md)。真实模型推理收益按原选择独立待验。
1.13.0已本地交付[隔离协作](docs/WORKERS.md):父目标与两个受限Git工作区、累计预算/停止恢复、当前成果核对、具体冲突和父工程审查/检查/Git交付。独立源码404/404、完整界面21类160组与三个真实功能工程通过,父Node8/8、React9/9、Python10/10及构建/编译/Git,React内置Edge两视口各10项断言。正式[本地工作台](http://127.0.0.1:4318/?release=1.13.0)已保持原进程/模型连接/全部历史升级,验收与部署见[QA-1.13](docs/QA-1.13.md)。
模型中心支持多连接、轮询/权重、故障冷却与请求账本,并可预览导入已验证的CCSwitch/工作台配置。项目记忆按来源复核后进入有界上下文;任务检查点保留全部要求和原工具结果;Skills按版本读取,MCP按实际契约和逐次确认执行。运行中心提供不发送模型请求的本地巡检,发行验收与限制见[1.12记录](docs/QA-1.12.md)。
任务记录中的「执行计划」固定步骤、依赖和通过条件,用原操作及当前文件核验。未完成或失效步骤会保留在同一Task,并阻止用模型文字或旧Git预览直接交付。模型可使用相同的计划与核验工具;原计划、通过/失败证明和交付报告均能查看。契约见[任务计划](docs/TASK-PLANS.md),桌面/390px、源码与实际模型结果分别见[1.11验收](docs/QA-1.11.md)。
1.10.1修复保留旧SQLite宿主升级后页面工件读取失败的问题。独立源码、发行与真实配置模型结果各自登记,当前状态见[1.10验收](docs/QA-1.10.md)。
1.10.0在任务记录中增加「页面验收」:封存构建目录、桌面或手机视口和检查步骤,审查后使用独立Edge实际填写、选择、点击与断言。原页面、请求、步骤和PNG截图绑定当前任务;失败原值保留,构建变化后重新检查。配置了页面验收的Task必须取得当前构建断言通过记录才能Git交付。使用范围见[页面验收契约](docs/BROWSER-CHECKS.md),发行与验收状态见[1.10记录](docs/QA-1.10.md)。
1.9.0新增「本地代理引擎」入口:填写已有DeepSeek Harness 0.2.1-rc.2目录、检测安装并核验启动/连接/停止,原记录保存在当前Task,可分页或完整下载。261项独立源码、108组完整界面、不可变发行及保留原Provider的正式升级已完成,见[1.9记录](docs/QA-1.9.md)。本切片不捆绑第三方Harness,不发送外部模型任务。
1.8.0已完成最终244项独立源码回归、98组界面与随包REA实际分析,正式本地服务保留原模型连接升级。真实配置模型在原Task完成四模块修复、14项测试/构建、整批审查和工作台Git交付,见[1.8交付记录](docs/QA-1.8.md)。外部代理引擎与总体自主工程完成率继续分别验证。
每次运行保留模型与预算、已完成工具和日志工件。多文件变更集封存同Task的原/新字节、Git基线与审查指纹,应用前核对整批文件;中断后显式核对或回退,保留外部修改。应用改动后可点击「继续检查与交付」,沿用原目标进行实际测试与修复。提交前查看实际文件、diff、署名和检查结果,确认后生成本地提交及可下载的JSON/Markdown报告。版本改动见 [CHANGELOG](CHANGELOG.md),编辑范围见[索引与补丁](docs/CODE-INDEX-AND-PATCHES.md)和[变更集恢复契约](docs/CHANGE-SETS.md)。
## 后续产品与能力建设
1.12包含模型中心/池路由、[项目记忆](docs/PROJECT-MEMORY.md)、[任务恢复检查点](docs/TASK-CHECKPOINTS.md)、[Skills](docs/SKILLS.md)和[项目MCP](docs/MCP.md)。记忆只在来源复核、脱敏且请求预算允许时使用;恢复检查点绑定完整要求和原结果,核对后显式续接同一任务。1.13两个受限worker与1.14受控引擎/提示实验均已完成发行;1.15桌面和本机加密A–E已验收,最终发行/部署以[QA-1.15](docs/QA-1.15.md)为准;下一[1.16手机伴随端](docs/PLAN-1.16.md)先实现一次性配对、设备权限与断线恢复,再推进更多模型协议和多模态。
当前Git项目可以先预览已提交版本,再创建独立目录和分支;来源已有暂存、未提交及未跟踪文件保留在原项目。子工作区有自己的项目、会话和实际执行目录,创建中断后显式核对。模型准备Git交付预览后停止请求,确认这份预览后由内核完成提交和报告。具体范围见[独立工作区](docs/WORKSPACES.md)及[1.6验收](docs/QA-1.6.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`;后续按独立小步检查并及时提交。
1.6.2优先保留当前Task的实际代码与执行依据,再补近期历史;同版本较完整的读取优先于后来的小页,原工件引用可继续分页。发送视图的完整来源仍可核验,1.6.1历史视图按原版本保留。已应用前的旧代码和失效检查不计入当前依据。请求面板可查看实际发送内容、工作依据和完整原历史,具体范围与验收状态见[1.6.2记录](docs/QA-1.6.2.md)。沿用1–32文件的封存变更集与可恢复应用;部分执行会明确显示需核对。改名/删除、任务依赖图、语义引用、工作区合并/归档、多类工程检查器、外部引擎、REA执行及桌面/手机配对继续按后续阶段建设。
1.7.0在完整工具组过大时仍保留有原结果来源的最新状态反馈;相同工程状态连续三次未推进会保存并暂停。Python支持unittest、pytest与源码语法编译,保存实际解释器、输入、结构化统计和日志,检查结果进入既有Git/报告核对。混合项目可以在界面「选择检查范围」中选Python,再重新识别并确认新计划。Python需本机安装;pytest工程需在所选环境安装pytest。具体范围见[Python检查契约](docs/PYTHON-CHECKS.md)及[1.7验收](docs/QA-1.7.md)。
## 直接运行
Windows x64 1.15桌面/便携包自带Node.js 24.22.1、npm、Electron 45.2.0、REA 6.8.0、Playwright 1.64.1及锁定生产依赖。页面验收使用本机Microsoft Edge。安装版双击安装目录的AgentWorkbench.exe,便携版双击Start-Desktop.cmd打开桌面;Start-Workbench.cmd仍可打开浏览器入口http://127.0.0.1:4318。最终1.15安装/发行状态见[QA-1.15](docs/QA-1.15.md)。
启动不需要安装 npm 依赖或管理员权限。窗口关闭后本地服务仍运行,任务与会话继续保存。再次打开相同地址即可查看记录。
1. 打开自带示例项目,或点击项目栏的「+」输入本机项目文件夹路径。
2. 输入任务并发送。默认「离线演示」使用固定脚本调用真实本地工具,不进行模型推理。
3. 终端请求会显示完整命令、用途和工作目录,确认后才运行。
4. 文件建议先成为提案。跨文件改动在「改动」面板选择「组合审查」,封存并查看整批差异,再确认应用全部文件;模型也可准备批次。独立提案仍可逐项审核,已封存提案通过批次处理。
5. 点击「模型连接」,选择兼容模型服务,填写接口根地址、模型和按需填写的 Key;可先「验证模型响应」,再保存连接。
6. 遇到请求失败,点击错误卡片的「查看运行诊断」。可在同一会话提问,助手通过本地 `inspect_session` 核对错误来源、近期工具和文件实际状态。
7. 点击「查看任务记录」查看目标、各轮运行、累计用量与工件。识别工程后可选择检查范围,核对npm脚本或Python执行环境,再确认执行;查看实际测试数量、日志和原统计依据。应用全部提案后,用「继续检查与交付」继续同一目标。
8. 检查通过后,在任务记录中「预览Git提交」,核对已审核路径、差异、署名和说明,再「确认创建本地提交」。工作台保留其他暂存与工作区改动,结果未知时提供「核对提交结果」;报告可直接查看和下载。Git需要本机安装,具体范围见[Git交付契约](docs/GIT-DELIVERY.md)。
9. 右侧「索引」按函数、类、路径或导入查找代码,结果可定位原文件行。文件在索引后变化时打开当前内容并提示刷新;Python声明候选与局部模块文件候选显示各自范围。长文件差异可直接「定位首处改动」。
10. 批次中断或部分失败时,在所属任务打开「审查变更集」,先核对实际文件,再按当前哈希回退或明确保留外部内容。结果待核对期间同项目的新运行、写入、检查与提交会暂停。
11. 任务记录中的「请求上下文」可查看当前或历史运行的实际发送内容、请求计划和分页完整历史。读取原记录不会执行工具;预算不足时保存同Task检查点,通过明确续接操作继续。
12. 点击顶部「REA 工件研究」,登记ASAR、EXE或DLL的本地绝对路径与研究问题。选择JavaScript/Electron、PE导入或资源分析后,可查看原字段、限制、连接记录和完整Evidence Bundle。完成的同版本结果先核验再复用;新版本需重新登记,未完成分析由用户明确重新发起。
13. Web工程构建完成后,在任务记录「页面验收」中选构建目录、页面路径和视口,添加填写、点击或断言并封存计划,核对后运行。步骤为空时先观察页面与实际元素,再准备有断言的新计划。可查看原步骤结果、分页JSON及原始PNG;构建或源码变化后准备新计划。
REA首批为静态分析,研究工件不会自动运行。原结果与项目、Task、Run和目标SHA256绑定,模型只能分析已登记工件。具体范围见[REA集成契约](docs/REA-INTEGRATION.md);桌面安装端、手机配对及其他外部引擎按后续阶段继续建设。
## 模型连接
支持 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默认只在执行宿主内存中使用。1.15可在「模型中心」对新填写或本次确认导入的连接选择本机加密保存,使用当前Windows用户的DPAPI密文,与连接登记同一SQLite事务提交;可关闭启动加载、删除本机保存或单独清除内存。临时连接重启后需重新填写。既有内存Key不会因升级自动写盘,公开配置、会话和导出不包含明文Key。格式导入只处理用户明确选定的来源,见[桌面与连接说明](docs/DESKTOP.md)。
接口契约已由本地 HTTP 测试服务及浏览器验证。用户随后配置的 `gpt-6.1-sol` 已通过真实读取、提案与应用验证,见[模型连接实测](docs/MODEL-CONNECTION.md)。
## 文件、命令与恢复
读取与搜索仅处理项目范围内的 UTF-8 文本,并限制文件体积/搜索数量,跳过依赖目录、链接与常见凭据文件。文件提案保留原文 SHA256;应用时发现外部改动会拒绝覆盖。原文备份保存在数据目录的 `backups` 下,保留原字节。
终端命令逐次确认,最长 60 秒,有输出上限,确认后以当前系统用户权限执行。项目工作目录不是操作系统沙箱。停止任务会中止工作台启动的进程树。
数据默认保存在 `%LOCALAPPDATA%\AgentWorkbench`。1.1.0将任务、运行、工具、检查与事件保存到`workbench.sqlite`;旧JSON在有备份的事务迁移后保留。大型结果和检查日志另存为SHA256校验工件。服务意外退出后保留提案和完成结果;结果未知的副作用需要核对,不自动重放。暂停后可「继续任务」;已应用的审核任务可「继续检查与交付」。
工程检查当前支持已识别的npm test/typecheck/check/lint/build脚本,计划绑定源码与Git快照。执行前展示脚本与npm生命周期钩子,实际job保留退出码、测试统计及日志。零测试、跳过、未识别日志、取消或源码过期均不记为任务验证通过。
Windows 终端使用 PowerShell 5.1,通过 UTF-8 stdin 传入经确认的完整脚本,同时设置输入、输出和 `$OutputEncoding`。多条命令用换行组织,不能使用 `&&` 或 `||`;原生命令的 `$LASTEXITCODE` 会成为执行结果。
完整历史保存在本地。模型请求按完整assistant/tool组选择近期内容,省略组保存为SHA256工件;任务目标、全部追加要求和最后用户消息完整保留。发送前持久保存实际JSON正文与请求计划,估算包含系统、工具定义、历史和输出预留。服务实际usage另行记录,估算不能当成准确费用;详见[上下文契约](docs/CONTEXT-PLANS.md)。
## 研究与验证
- [统一机制报告](docs/RESEARCH.md):原版静态证据与本产品实现逐项对照。
- [详细报告与证据索引](docs/research):Claude Code 工具循环、上下文/恢复,以及 Cursor 工具执行/编辑。
- [验收记录](docs/VALIDATION.md):逐版本保留实际结果、失败与部署身份。
- [本轮验收清单](docs/QA-1.5.1.md)、[封存四模块工程基准](benchmarks/node-delivery-v1/README.md)与[保留连接的升级说明](docs/UPGRADE.md)。
- [独立架构](docs/ARCHITECTURE.md)与[界面设计](DESIGN.md)。
原版研究没有执行 Claude Code/Cursor,报告不表示恢复了全部源码或验证了远端服务。完整分析工件保留在原研究工作区;本产品包不包含第三方客户端原二进制、完整提取源码或大体积代码切片。
## 源码开发
使用 Node.js 24;依赖版本由 `package-lock.json` 固定。1.15源码包包含固定Electron、Node及npm运行文件。解压后的Windows源码包可直接使用随包运行器,并用独立端口和数据目录启动开发窗口:
```powershell
$awbSourceRuntime = Join-Path ((Get-Location).Path) 'runtime'
$awbSourceNode = Join-Path $awbSourceRuntime 'node.exe'
$awbSourceNpm = Join-Path $awbSourceRuntime 'node_modules\npm\bin\npm-cli.js'
$env:Path = $awbSourceRuntime + [IO.Path]::PathSeparator + $env:Path
& $awbSourceNode $awbSourceNpm ci --ignore-scripts
& $awbSourceNode $awbSourceNpm run build
& $awbSourceNode $awbSourceNpm run desktop -- -Port 4319 -DataRoot .qa\desktop-data
```
已有锁定依赖下载缓存时,`ci`可加`--offline`;本轮独立源码离线回归使用本机已有npm缓存。首次无缓存需要联网准备锁定依赖。源码仓库首次开发需先取得固定Electron 45.2.0发行运行文件,再使用已核对的Node24:
```powershell
npm.cmd ci --ignore-scripts
npm.cmd run build
npm.cmd test
```
启动构建结果可运行 `npm.cmd start` 或双击启动脚本。前端开发使用 `npm.cmd run dev`,另开终端运行构建后的本地服务。
UI 验收先启动独立测试服务,依次运行基础、诊断、任务、Git交付和索引脚本;`node scripts/verify-change-sets-ui.mjs`及`node scripts/verify-context-ui.mjs`自行启动独立宿主。默认地址为 `http://127.0.0.1:4319`,索引脚本需用 `AGENT_WORKBENCH_URL` 明确指定独立端口。验证器使用本机Edge、离线演示和未配置Key的宿主,在 `.qa` 创建自有项目。真实模型批次样本使用 `node scripts/verify-live-delivery.mjs --batch`,具体证据见[验收记录](docs/VALIDATION.md)。
```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/`。本工程原创代码的对外许可由项目持有人决定。