Open-Science ACP 代理协议完整指南：plan/execute/tool-call 循环如何让科研任务可复现-港品优选

Open-Science ACP 代理协议完整指南：plan/execute/tool-call 循环如何让科研任务可复现

【免费下载链接】open-scienceAIPOCH Open-Science is an open-source, local-first, model-agnostic AI research workbench for macOS, Windows, and Linux, with scientific agents, Python/R notebooks, data connectors, and reproducible provenance.项目地址: https://gitcode.com/GitHub_Trending/open/open-science

Open-Science（AIPPOH）是一款开源、本地优先、模型无关的 AI 科研工作台，它通过 ACP 代理协议（Agent Client Protocol）把"计划（plan）→ 执行（execute）→ 工具调用（tool-call）"串成一个可审批、可追溯的循环。本文带你快速看懂这个循环的三层结构：Agent 如何先产出待审批的研究计划、如何在批准后逐轮执行、以及如何通过 MCP 工具服务器完成读文献、跑笔记本等真实操作。无需阅读源码，也能建立完整的心智模型。

为什么科研 Agent 需要"计划-执行"循环

普通聊天式 AI 拿到问题就立刻动手，但在科研场景里，一个任务往往要跨多个阶段：清洗数据、写分析代码、生成图表、输出报告。Open-Science 的做法是先让 Agent 停下来交一份计划，用户批准后才开始执行。这样做带来三个直接好处：

可审批：你在任何一步之前都能看懂 Agent 打算做什么；
可干预：计划卡片上的任何文字反馈都会作为普通消息返回，Agent 会据此修订计划而不是擅自开工；
可复现：每次执行都与计划产物（artifact）绑定，来源信息完整留痕。

循环第一步 plan：生成一份"待审批"的研究计划

计划机制的核心是一份结构化的Session Plan 文档，由四个字段组成，定义在 contract.ts：

字段	含义
`task_summary`	多阶段目标的一句话摘要
`phases`	有序的工作阶段，每阶段包含若干独立工作轨道（delegation）和步骤
`desired_outputs`	期望的最终交付物，如"PDF 报告"、"清洗后的 CSV"
`feasibility`	可行性评估，含置信度（高/中/低）和理由

Agent 并不会随意生成计划。系统在 guidance.ts 中通过系统提示词明确约束：只有真正多阶段、值得用户过目的任务才生成计划，简单的查询或单步计算直接做即可。计划通过名为generate_plan的工具（由open-science-planMCP 服务器提供，见 plan-mcp-server.ts）提交。

关键设计在于：工具调用不会立刻返回。Agent 调用generate_plan后会"挂起"在工具调用内部等待你的审批——此时 Provider 的回合被暂停，界面进入waiting-plan-approval状态。计划的状态机有六种生命周期（见 contract.ts）：

awaiting_approval → approved → in_progress → completed ↓ ↓ rejected blocked

只有approval: approved的计划才算"生效"。即使反馈文字听起来像同意，只要审批没有落定，Agent 也绝不调用状态更新工具。这条规则由 formatPlanProtectedContext 生成的受保护上下文反复注入，防止模型"自作主张"。

循环第二步 execute：按轮次推进并汇报步骤状态

计划批准后，执行进入prompt turn（提示回合）流程，由 prompt-turn-workflow.ts 编排。每一轮会先做"准入"检查——确认当前会话没有未决的计划审批、工具可用性正常——再分发给具体的 Provider 适配器（Claude、Codex、OpenCode 等各有独立的 turn-adapter，位于 src/main/acp/ 目录）。

执行期间，Agent 被要求在工作开始和完成/受阻/跳过两个时刻调用update_step_status工具，并精确使用步骤标题。于是你在界面里看到的进度，不是模型的"口述"，而是与计划文档严格对账的结构化状态：每个步骤的状态、备注、整体计数（阶段数/轨道数/步骤数/已完成数）都来自计划投影，而不是自由文本。

如果执行中目标发生变化（改需求、换输出），系统要求生成一份替换版计划并重新等待审批；而批准范围内的例行进展汇报则不需要再审批。这个"何时该问、何时别烦你"的边界同样写在系统提示词里。

循环第三步 tool-call：MCP 工具服务器与权限闸门

计划里承诺的工作最终要落到真实操作上，这靠一组MCP（Model Context Protocol）工具服务器完成。以科研任务为例，Agent 可能调用：

文献库工具：搜索、读取摘要、导出引用（literature/mcp-server.ts）；
笔记本工具：在受控环境中执行 Python/R 单元格（notebook/mcp-server.ts）；
技能导入工具：加载可复用的分析方法（skills/mcp-server.ts）；
计划工具：generate_plan与update_step_status。

每次工具调用都不"畅通无阻"。ACP 运行时的权限体系（permission-policy.ts、permission-broker.ts）会把敏感操作拦截下来，弹出审批卡片由你决定"允许一次"还是"始终允许"。换句话说：计划审批解决"做不做这件事"，权限审批解决"这一步能不能碰这个资源"，两道闸门相互独立。

工具调用产生的产物（图表、报告、数据文件）会作为带校验和的 artifact 写入会话，并保留完整来源链路，你可以在溯源视图中回看"这个数字是哪一次工具调用产出的"（见 shared/artifact-provenance.ts）。

想深入源码？三条路径看懂循环全貌

想看什么	去哪里
ACP 运行时总控（会话、事件、计划投递）	runtime.ts
每一轮执行如何编排（计划准入、技能、产物）	prompt-turn-workflow.ts
计划文档结构与状态机	contract.ts
计划的生成、审批、反馈落库	plan-service.ts
ACP 与渲染进程共享的类型契约	acp.ts
给 Agent 的计划行为规则（提示词）	guidance.ts

如果你使用 VS Code 打开仓库，从 runtime.ts 跳到sessionPlanWorkflow的组装处（composeAcpRuntimePlanWorkflow），再顺藤摸到 runtime-plan-composition.ts，基本就能把 plan/execute/tool-call 三层串起来。相关的产品需求与设计文档可参考 docs/PRD.md 和 docs/design.md。

小结：一张图记住这个循环

plan：Agent 评估任务是否值得规划 → 调用generate_plan提交四字段计划 → 挂起等待你的审批；
execute：批准后逐轮执行，每个步骤开始/结束时调用update_step_status更新结构化进度；
tool-call：通过 MCP 工具服务器操作文献、笔记本、技能，敏感操作经权限审批，产物带溯源留档。

对新手来说，这套 ACP 代理协议的价值不在于技术细节多炫，而在于它把 AI 科研工作变成了先立计划、再干活、留证据的工程流程——这正是科研场景最需要的确定性。🔬

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析