ScienceDiscovery
English GitHub

内置工具清单（模型可见）

本文列出 Agent 循环中模型可见的全部工具。工具由 packages/workspace 的 createWorkspaceTools 构建，并由 packages/tools 注册和调度：实现全部在 Node 控制面，模型请求里只带名称、描述与 JSON Schema（见 agent-backend.md）。除标注「恒有」外，工具是否出现取决于会话配置；最终列表还会经 toolPolicy 过滤（子 Agent 可被限制为白名单子集）。

下表描述产品自有工具及 native executor 的可见名称。默认 JiuwenSwarm 后端会用自己的网页工具替换 web_search/web_fetch，用 todo 工具替换 update_plan，子代理默认仍通过平台 task 桥接；还可能出现其它 Swarm 工具。开关和边界见 Agent 后端。

基础工具（恒有）

工具 参数 行为与边界
list_files 无 递归列出会话工作区文件（路径/大小/修改时间），跳过符号链接，最多 500 个
read_file path，可选 offset、limit 分页读工作区文本：单次最多 2000 行或 40 KiB，用 offset 续读；路径经工作区逃逸校验。二进制文件只返回媒体类型与大小，正文与 base64 都不进入模型输入
get_file_provenance path 返回后端已记录的文件身份、当前来源、修订历史、执行上下文、上游来源链和关联产物版本；origin: unknown 表示来源不可证实，Agent 不得自行推断
list_artifacts 无 列出当前 Project 中跨 Session 的用户可见产物，包含来源、创建 Session 快照和最新版本元数据
read_artifact artifact_id 或 name，可选 version、offset、limit 按 Project 产物身份分页读取指定版本：文本返回 UTF-8，单页最多 2000 行或 40 KiB，并给出行范围与下一 offset；二进制版本只返回 binary: true 与媒体类型、大小，不返回正文或 base64
declare_artifact path 或 paths（1–50 项），可选 name、description 将当前 Agent 可写工作区内的文件显式声明为 Project 产物。单 path 保留原返回，name 默认等于规范化后的工作区相对 path，可显式覆盖为其它安全逻辑路径；paths 优先且逐项返回 ok/error，成功项不回滚，每项使用自身完整相对 path 并忽略顶层 name/description；name 中的 / 在产物侧边栏显示为虚拟目录，不创建或移动物理文件；预览 kind 由服务端内部推断，最终报告也必须声明
run_shell command 或 scriptPath 二选一，可选 arguments、runner_id、environment_id、wait_ms、background Agent × Runner Workspace 中的新沙箱进程；按环境 ID 使用最新版，无跨调用 cd/export/解释器内存；等待到期不停止进程
execution_status / execution_logs / execution_cancel Execution ID；状态支持列举/等待，日志支持 cursor 独立管理通道，不另起 Shell、不取 Workspace 写锁
workspace_transfer workspaces/start/list/status/cancel；显式 Workspace ID 与文件映射 复制已提交快照，记录逐文件结果与部分成功，不自动声明 Artifact
timer_create / timer_list / timer_cancel after_ms 与 at 二选一，message，可选 execution_id；取消用 timer_id 所属 Agent 的一次性提醒；Stop/Archive 禁止自动唤醒并取消待触发提醒
read_tool_output ref；可选且互斥的行范围（offset、limit）、字符范围（charOffset、charLimit）或文本搜索（query、contextChars、maxMatches、caseSensitive） 从已存工具结果中恢复一个明确缺失的事实；重复或累计读取过多会提示收敛，但不会阻止合理读取

所有工具结果在进入模型输入前经过同一个边界：普通的非自限界结果超过 8 KiB 时原样落盘并在消息元数据中附结构化 ref，保证后续压缩可恢复；超过 2000 行或 50 KiB 时，首次展示即改为 head/tail 预览 + ref。完整正文按 Session 保存在 <dataDir>/tool-outputs/<sessionId>/。read_tool_output 应优先用 query 做普通文本搜索，常规文本使用行范围，只有单行过宽时才使用字符范围；三种模式的返回都限制在约 40 KiB。工具在单次 AgentRun 内按 ref 统计读取，重复范围/查询或累计约 64/96 KiB 时会提醒模型只为明确缺失信息继续读取，但不会阻断合理操作。阈值可通过 .env.example 中的 SCIENCE_AGENT_TOOL_OUTPUT_* 环境变量调整。

run_shell 首次执行会触发 code 类权限卡片（见运行时行为参考）。执行产生的文件仍保留 diff 与 derivation 审计，但不会仅因出现在工作区就进入产物目录；Agent 必须调用 declare_artifact，用户上传与 MCP 下载由控制面在入口处注册；远程文件必须先显式复制到本地 Workspace，再声明 Artifact，复制本身不自动声明。

产品 Web 工具（native 默认可见；JiuwenSwarm 可使用自有工具）

工具 参数 行为与边界
web_search query（1-2000 字符） 自动聚合搜索：先试已配置 key 的付费 Provider，再试开启的免费引擎，取第一个出结果的；返回片段与 URL，不代表已读全文
web_fetch url（完整 http(s) URL） 抽取指定公开网页；拒绝凭证 URL、内网/环回地址；不做跨 Provider 降级

选择这两个产品工具时，由 Node 发起权限检查、写 CAS 快照和 WebInvocation 审计，并在进程内调用厂商。详见 web-tools.md。

编排工具

工具 出现条件 参数要点
update_plan native Agent run，或设置 SCIENCE_AGENT_JIUWENSWARM_PLANNING=update_plan 的 JiuwenSwarm run 完整替换的 plan 快照（0–20 项，每项包含 step 与状态），以及可选 explanation；空列表表示清空计划
task 主运行注入（子 Agent 内不可再派生） description（≤80 字符）、prompt（≤20000）、可选 brief（Brief v1 契约，见 subagent-orchestration.md）、inputPaths（≤50）、max_turns（≤300）、timeout_seconds（≤3600）、specialistId、tools（白名单，≤32）；同轮多次调用可并行
query_graph 在 System Settings 中启用 ScienceMemory query：跨会话记忆图的大小写不敏感子串搜索，返回 {hits, total, truncated}

update_plan 是 run 范围内的轻量进度快照，不是审批门禁，也不是治理实体。每次调用都会完整替换计划，因此新增、删除、重排和状态更新共用一个接口。同一 LLM step 声明多个 update_plan 时，只提交模型声明顺序中的最后一次；此前调用以 superseded 成功结束。成功提交的 plan.updated 写入 run event stream，并折叠后注入下一次模型调用；主 Agent 与各子 Agent 分别维护自己的快照。

面向模型的契约要求 Agent 在实质性工具调用前检查计划，在语义步骤开始、完成、阻塞或调整时更新，而不是每次工具调用后机械更新；不得事后批量补记完成项；证据改变路径时应修订计划；最终回答前应完成或明确调整未完成项。这些是行为提示，不是执行门禁。开启 context trace 后，planProgress 会记录最近一次更新之后、当前可见历史中经过的模型步骤数和已完成的非 Plan 工具结果数，但不会强制模型继续运行。

计划更新是否及时，最终取决于所选模型的指令遵从能力。即使上述提示存在于每次请求中，模型仍可能偶发延迟更新，或在后续快照中一次性补记多个已完成步骤。Harness 有意将其视为可观测的模型行为，而不是运行时一致性错误：框架负责校验快照结构、持久化模型的最新声明并提供进度观测，但不会按固定 LLM 轮数或工具调用数强制更新，不会从工具输出猜测某个语义步骤已经完成，也不会因为仍有未完成项而拦截最终回答。这类限制会增加控制调用、误判领域相关的步骤边界，并可能打断原本有效的任务执行；如确有需要，应先根据真实轨迹评估具体模型的遵从表现，再增加范围明确的策略。

科学环境工具

出现条件：科学环境已启用且完成 setup（executeScientific + 环境列表注入）。

工具 参数 说明
Python / R 统一经 run_shell 原地更新环境、Revision 仅追溯；详见 执行与 Workspace 生命周期
environment_list 可选 runner_id 列出该 Runner 共享的只读 base 与命名环境；Revision 仅追溯，执行选择 Environment ID 的最新版
environment_create name、language: python|r，可选 baseEnvironmentId 从对应只读 base（或指定 base）克隆命名环境；首次显式创建 R 环境时按需准备 R base
environment_delete environmentId 删除命名环境；base 拒绝删除
environment_install environmentId、packages[]，可选 manager / channels[] / indexUrl manager 默认 conda；Python 环境可选 pip 安装一个或多个 PyPI 规格或当前 Session workspace 相对 .whl。仅 manager=pip 可传独立 HTTPS indexUrl，效果等价于单次 pip --index-url 并覆盖全局 pip 源。包规格不接受远程 URL；本地 wheel 按 SHA-256 持久保存并写入 revision snapshot。conda 渠道仍须在白名单或内置镜像预设内
environment_uninstall environmentId、packages[] 使用 conda package spec 卸载；成功产生新 revision

四个 mutation 工具使用独立的 code / scientific-environments 权限资源；base 始终只读。Agent 系统提示明确要求通过这些工具治理托管前缀，不把 run_shell 中直调 conda/mamba/micromamba/pip 作为支持路径。系统设置中的 pip 源可选 Official upstream、Tsinghua TUNA、USTC 或 Huawei Cloud，其中 Huawei Cloud 使用 https://mirrors.huaweicloud.com/repository/pypi/simple；conda 源可选前三项，不提供 Huawei Cloud 预设。设置页只显示来源名称，不附加地区描述。源优先级为“单次显式源 > 全局选择 > 官方上游”。设置页没有 Session workspace 上下文，因此 pip 只能使用 PyPI 名称规格，不能提交本地 wheel 路径。indexUrl 仅在 manager=pip 时有效，必须是符合实现校验的 HTTPS 且不得含凭据、query 或 fragment（长度 ≤2048、无空白/控制字符，首尾空白会被裁剪）。离线缓存模式仍校验该字段，但安装命令会静默忽略网络 index，改用 --no-index --find-links。pip 自定义源应通过结构化的 indexUrl 表达，不要用 run_shell 直调 pip 拼参数。等价于 pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu 的受控调用示例：

{
  "environmentId": "<named-python-env-id>",
  "manager": "pip",
  "packages": ["torch", "torchvision"],
  "indexUrl": "https://download.pytorch.org/whl/cpu"
}

科研 MCP 工具（动态）

出现条件：会话启用了对应 MCP 来源。命名 mcp__<source>__<tool>（如 mcp__pubmed__search），描述与输入 schema 来自来源 manifest，按需发现（deferred: true，模型初始只见工具名，schema 经 tool_search 晋升后暴露），返回内容视为不可信外部数据。注入链路、逐层过滤与模型可见性见 science-connectors.md 第 3 节。

配套的文件工具：

工具 出现条件 参数与边界
artifact_download 任一 MCP 来源启用 mcpInvocationId + candidateId（来自此前 MCP 调用返回的 ArtifactCandidate），可选 destinationPath；等待权限与下载终态，不解析 PDF
paper_extract_pdf 论文抽取接线 artifactJobId（必须是已完成的下载任务）或 path（工作区里已有的 PDF，例如用户上传的文件），二选一；触发有界 PDF 抽取（见 ../developer-docs/paper-worker.md）

下载与抽取必须分属不同模型回合——同回合工具并行执行，没有 dependsOn 机制。

其他条件工具

工具 出现条件 参数要点
run_npu_job Runner 启用 SCIENCE_AGENT_NPU_BROKER=1 且加载到 NPU workload 白名单 operation=list_workloads|submit|status|logs|result|cancel；workload_id 来自白名单，config_path 为 Workspace 相对路径；environment_id 选择环境最新版，省略时使用 Session 所选环境；内置 workload 为 npu.smoke_test 与 antibody.protenix.v1
create_evolve_run 部署注册了演进能力 提交搜索方案 —— 起点、打分模式、分片划分、预算与算法（puct 或 openevolve）。服务端负责校验、跑判别力探针并掌握预算；Agent 只负责提交。启动前会弹出审批卡片，搜索随后运行数分钟到数小时，并有自己的实时面板
get_evolve_run 部署注册了演进能力 读取某次搜索的状态与结果。不是等待机制 —— 面板会自行流式显示进度，轮询它只会花掉搜索需要的预算
read_skill 本次运行至少选择一个技能 skillId（枚举限定为本次运行选中的技能）；按需读取冻结 revision 的完整 SKILL.md instructions，并列出可选 supporting resources
read_skill_resource 选中的技能中至少一个带文本资源 skillId（枚举限定为本次运行选中的技能）+ path；读取 read_skill 后按需加载 supporting resource，返回有界 UTF-8 内容，从不执行或安装
create_skill 主 Agent 本次运行选中且已通过 read_skill 加载 skill-creator 从用户明确描述生成持久化但未激活的 Skill 草稿；同名待审 Skill 的再次修改会更新同一个审核项，并与上一次 Agent 提案做 Diff；对话中提供审核入口，用户确认后把审核内容发布为 Skill Library 的新不可变版本

技能加载流程见 skill-progressive-disclosure.md。本次运行已选技能的完整冻结包在沙箱启动前就已放入只读的 $SCIENCEDISCOVERY_SKILLS_DIR/<skillId>，Prompt 逐个给出包路径和包 hash。引用时用该变量而不是它展开后的值——/skills 只在 bubblewrap 下成立。read_file 与 list_files 可直接分页读取包内文件，并接受 $SCIENCEDISCOVERY_SKILLS_DIR/...、${SCIENCEDISCOVERY_SKILLS_DIR}/... 和裸 bind 路径三种写法；run_shell 的 scriptPath 也可以直接指向包内脚本并用 arguments 传显式 argv，无需先复制到工作区。$SCIENCEDISCOVERY_SKILL_EXTENSIONS_DIR 是为后续自演进预留的可写目录，默认为空。放入技能包不等于自动执行或安装其中的 scripts/；执行必须由 Agent 显式发起。read_skill / read_skill_resource 作为兼容通道保留。

run_npu_job 是独立、显式启用的 Host NPU Broker，不是通用宿主 Shell。Broker 只启动白名单固定入口并校验 Session 归属。Agent 传 environment_id，API 将其最新版转换为 Broker 内部审计字段；旧 Revision ID 不能作为环境选择项。通过 environment_list 和受控环境工具准备依赖后传入环境 ID。NPU 硬件可用性和特定 workload 验证与常规沙箱 Shell 分开管理。

一致性说明

相关文档