构建智能体，
掌控每次执行。

01 / THE AGENT PLATFORM

平台概览

以 DeepAgents 为执行引擎，将智能体定义、协作与治理连接起来。

Agent Studio 是可以独立部署的智能体（Agent）平台，下文统一称 Agent。它以 DeepAgents 为唯一执行引擎，提供从 Agent 定义、资源配置与草稿测试，到发布、运行、审批、评测和观测的完整工作流。

你在控制台维护 Agent，你的应用通过运行时 API 或 SDK 调用已发布的版本，Worker 在服务端执行。模型、工具、Skills 与上下文管理被组织在同一套有权限和版本边界的运行系统中。

从构建到运行

平台提供什么

选择阅读路径

适用场景

适用于知识助手、研究流程、内容处理、内部业务协作等需要多步推理和工具调用的应用。平台内核保持领域无关；领域数据、计算与外部动作由你的工具或服务提供。

本版文档对应 DeepAgents 1.15.1 的平台集成与 Python SDK 0.0.2。具体实例的可用能力以能力协商接口和部署配置为准。

02 / PRINCIPLES BEFORE FEATURES

设计理念

先建立清晰的边界，再让智能体在边界内完成复杂任务。

让智能推理与执行约束各司其职

模型适合理解意图、组织步骤、选择工具和解释结果。业务事实、计算规则、访问权限与写入决定，应由具有明确契约的服务和代码负责。

Studio 将这条分界落实为资源授权、输入输出 Schema、运行快照、审批与结果校验。工具输出可以帮助 Agent 推理，但不能替它获得新的权限。

配置可演进，运行须稳定

草稿允许迭代。发布生成不可变版本，并通过生产指针选择新请求使用的版本。每个 Run 在创建时冻结定义、资源和输入；之后修改草稿或工具，不改变已经开始的执行。

这让一次结果有可追溯的配置依据，也让测试、发布和回滚分别拥有清晰的边界。配置可复现并不意味着语言模型会逐字返回相同答案。

将复杂目标交给受约束的协作

规划帮助 Agent 维护待办与进度；子 Agent 提供专门职责和独立上下文。每个组件拥有明确的模型、工具、Skills 与结果要求，不能因为被委派就继承未授权的能力。

平台限制并发、步骤、工具调用与执行时长，并在副作用需要用户决定时暂停执行。协作能力与治理能力一起配置，见规划与子 Agent。

为中断和未知状态设计

连接中断、等待审批、工具失败和 Worker 重启属于运行生命周期的一部分。平台记录有序事件、检查点与待处理请求，以可查询的状态处理恢复。

数据未提供就保持为空；事件缺口明确报告；结果校验失败就返回失败。用量估算、模型报告与最终结果各自保留来源与边界，避免把“看起来成功”当作“已完成”。

保持平台领域无关

Studio 不嵌入某个业务产品的数据或桌面能力。你的应用通过版本化工具和运行时契约接入，SDK 负责传输和消费结果，服务端承担运行权威。这样，同一套执行和治理机制可以服务不同领域。

03 / FROM DEFINITION TO RUN

构建第一个 Agent

从模型配置和草稿测试开始，发布一个可被应用调用的 Agent。

开始前准备

需要一个可访问的 Studio 实例、控制台账号，以及可以调用的模型来源。自部署方式见部署指南。模型凭证由平台或部署环境管理，不放进 Agent 提示词或应用前端。

1. 创建项目并配置模型

进入控制台创建项目。在模型配置中添加来源，填写服务端点、凭证与模型，并运行连接测试。自定义端点还需要满足部署者配置的出站白名单。

连接测试检查模型和工具调用适配；它不等于你的业务任务已经通过质量评测。后续可以为具体 Agent 建立评测集。

2. 创建 Agent

填写清楚的任务指令，选择模型，按需要添加工具、Skills、MCP 或子 Agent。运行输入与结果输出构成流程边界；主／子 Agent 的资源在各自配置中管理。

一个入门任务可以是“根据用户提供的会议记录，整理结论、待办和待确认事项”。先用简单配置验证模型回复，再逐步引入有明确 Schema 的工具和结构化结果。

3. 保存并测试草稿

保存草稿后执行配置检查，修复缺失模型、未发布资源或权限问题，然后输入测试消息。查看真实回复、工具事件、状态和用量。

草稿测试使用服务端已保存的定义，生成独立的测试 Run。它不会发布 Agent，也不会改变生产指针。涉及审批时，通过待处理请求面板提交真实用户决定。

4. 发布版本

测试通过后发布。若项目设置了评测门禁，应先完成当前定义对应的评测。发布版本不可修改，后续变更通过新草稿与新版本进入生产。

复制 Agents 列表中的短 ID 或 Agent UUID，供外部应用使用。仅创建了草稿但尚未发布的 Agent，不能作为外部运行接口的默认调用目标。

5. 接入你的应用

项目所有者创建 API Key，至少授予 runs:write 和 runs:read。在你自己的后端使用 SDK，并用已认证用户的稳定 ID 作为 actor。

从SDK 快速开始复制完整示例。控制台的 SDK 调用记录可查看外部调用；草稿测试、评测与内部任务使用各自运行入口，避免混淆执行来源。

04 / THE EXECUTION FOUNDATION

为什么基于 DeepAgents

规划、协作与上下文管理来自引擎，治理和产品边界由 Studio 补齐。

采用 Agent Harness

DeepAgents 在 LangChain 和 LangGraph 的基础上，组合文件上下文、子任务委派、Skills、记忆与人工介入等执行原语。它为多步任务提供可扩展的 Agent Harness。

Studio 将这些原语接入项目资源、发布版本、持久状态和控制台，使它们成为可以配置和治理的平台能力。

从框架原语到平台能力

规划是可选的执行能力

Studio 为启用规划的主 Agent 或子 Agent 显式装配待办中间件，而不是仅在提示词中写“请列出计划”。任务不需要规划时，可以保持更简单的调用路径。

文件系统承载上下文，而非宿主权限

Skills、附件、长期记忆和工作区通过后端与文件权限共同提供。Studio 默认拒绝未授权路径；开启工作区只允许操作该作用域的虚拟文件，不自动开放服务器文件、网络或 Shell。

这是平台对DeepAgents 定制能力的明确选择：将引擎能力放入项目、用户与组件的资源边界中。

框架能力与平台开放范围

当前平台使用 DeepAgents 1.15.1。已接入的能力见本指南与项目能力接口 GET /v1/projects/{projectId}/capabilities；动态子 Agent、Interpreter、ACP、AG-UI 和 A2A 当前未接入运行包。

Studio 的后台子任务由平台排队与治理，不应等同于框架的任意远程 Agent 协议。框架后续新增功能，也需要完成契约、资源授权、运行时和界面的整合后才能开放。

05 / CONTROL & RUNTIME

系统架构

控制面定义如何执行，运行面负责执行并记录真实过程。

三个应用与一个数据库

API 和 Worker 可以使用同一镜像、不同启动命令。控制台只调用 API；SDK 也通过 API 接入，不直接操作数据库或 Worker。

一次执行的数据流

应用后端 / 控制台
        ↓ 身份、参数、资源与预算检查
Studio API → 冻结 Run 快照 → PostgreSQL 队列
                                     ↓ 领取租约
                            Studio Worker / DeepAgents
                                     ↓
                    模型 · 工具 · 子 Agent · 检查点
                                     ↓
                    公开事件 → 最终结果 → API / SSE

创建 Run 时，平台解析已发布版本或测试草稿，并冻结模型配置、工具和 Skill 版本、子 Agent、结果规范、输入与客户端能力。Worker 以这个快照为执行依据。

PostgreSQL 作为协调层

队列领取和租约由 PostgreSQL 协调；通知用于唤醒消费者，持久记录才是状态依据。事件按递增 seq 追加，运行状态与相关事件在同一事务内更新。

检查点支持审批恢复和中断续接；租约支持 Worker 失效后的任务回收。平台不需要额外的 Redis 或 Kafka 才能建立这条执行链路。

资源适配保持边界

模型适配器负责服务端点、参数、凭证解析和用量观测。工具适配器区分内置、远程、客户端及隔离计算。文件后端区分工作区、记忆、知识与只读材料。

资源可用性需要在定义检查、Run 创建与调用时分别核验；运行中撤销权限，不能仅凭旧快照继续获得新的授权。

06 / DEFINE, TEST, RELEASE

Agent 与版本

为每次执行保留稳定定义，为后续变更保留明确的发布边界。

Agent 定义

一个 Agent 由指令、模型引用、工具与 Skill 版本、MCP 选择、子 Agent 和执行设置组成。它是资源与行为的组合，不是一个孤立的提示词。

控制台默认在画布中编辑 Agent 草稿。点击主 Agent 或子 Agent 节点打开属性侧栏，再点击右上角的放大图标进入整页配置；顶部可以保存并返回画布。放大页面与画布共享当前编辑，返回时保留修改，保存失败也不会丢弃修改。放大期间使用手动保存，返回画布后恢复自动保存。画布当前采用受约束的执行结构，不是允许任意连线、任意代码节点的通用流程编排器。

草稿、测试与发布

放大配置页按「基础配置」「中间件」「运行与发布」分区。子 Agent 的最后一项为「运行设置」；所有分区和画布共用同一份草稿，切换分区不会丢失修改。

先保存再测试；修改模型、工具或结果规范后，重新检查并评测。设置发布门禁时，旧定义的评测结果不能为新定义放行。

每个 Agent 保留最近 10 个可回滚、可定点调试的发布版本；更早版本的定义与快照会被清理，其版本号、哈希、发布时间与操作人等记录保留在发布历史中。发布版本号使用三段式数字（例如 1.2.3），由发布者选择且必须大于当前最大版本；未指定时在当前最大版本上递增补丁位，既有历史版本从 0.0.1 起顺延。

画布右上角的「历史版本」进入独立的发布版本页，并可返回画布。页面可查看版本与当前草稿的差异、以历史版本创建新发布版，并对可用版本导出 SDK 或删除。删除仅适用于非当前生产版本、且未被其他版本作为回滚来源引用的版本；删除后该版本不能再回滚、定点调试或导出，发布历史记录与已有 Run 的冻结快照保留。只有项目所有者可以恢复、导出或删除发布版本。

执行中间件与身份访问

在主／子 Agent 的「中间件」分区，选择服务端已经注册的固定版本并填写配置。当前提供 identity_access@1：允许全部已认证调用者或指定 actorRef 白名单，要求凭据具备指定 scopes，并为工具设置默认行为或单独的调用者规则。单独工具规则的调用者留空表示全部拒绝。

此模式面向可信业务后端：业务后端验证登录用户后，使用服务端 SDK 的 actorRef 传递主体；项目 API Key 留在后端。普通运行 context 中自报的角色或权限不参与授权。常规项目 Key 当前可以申请 runs:read、runs:write；填写所需权限只会检查，不会授予权限。

主 Agent 的中间件也限制子 Agent；子 Agent 的规则只能进一步收窄。工具限制同时用于模型可见工具列表和实际执行前检查。中间件不替代项目资源授权、设备审批、远程 API 数据权限，也不按身份裁剪 Skill 内容或项目共享记忆。

「权限预览」以当前编辑中的规则计算模拟结果，不会保存、创建 Run 或执行工具。修改规则或模拟身份后，旧结果失效；模拟允许不代表该用户已经真实认证或上游资源可访问。viewer 可以查看配置和目录，不能修改或提交预览。

控制台草稿测试使用当前登录用户的 console:<用户 ID>，同样受白名单约束；界面会显示该测试身份。业务身份的真实运行应通过可信后端 SDK 发起，不能用普通 context 字段切换为另一位用户。预览工具数量最多为 256 项，超出时明确提示；实际执行仍逐项检查所有工具。

修改规则后先保存草稿，再测试和发布。已有 Run 保留启动策略。带有启用中间件的会话在访问策略或凭据权限变化后返回 409 middleware_thread_policy_changed，请新建会话后调用，避免继续使用旧权限下的历史内容。工具拒绝事件为 tool.access_denied；准入失败使用 middleware_actor_denied、middleware_scope_denied 等终止错误码。

自定义实现由部署维护者随服务注册，版本和配置 Schema 在目录中展示；页面不接受任意中间件源码、模块路径或密钥。终端直连凭证交换与外部业务角色在线撤权不在此功能范围内。

画布 JSON 导入与导出

画布右上角的「更多」菜单提供「导出草稿 JSON」「导入 JSON」和「下载 JSON Schema」。导出包含当前主、子 Agent 配置、资源引用与节点位置，包括尚未保存的配置编辑；尚未绑定资源的本机占位节点不包含在文件中。模型源、MCP 连接凭据、资源内容、运行记录与项目授权不随文件复制。分享前仍需检查指令、启动规则等用户编写的内容。

导入支持选择文件或粘贴 JSON，上限 2 MB。检查后预览名称、资源数量与布局信息，确认替换当前草稿。导入会替换当前配置与未保存编辑，不修改 Agent 名称；保存成功后才恢复布局，可以在当前画布会话中撤销。导入失败保留原配置与布局；草稿修订冲突时关闭导入，重新加载并检查后再试。只读成员可以导出，不能导入；历史回放时导入和草稿导出均不可用。

文件使用独立的 formatVersion，definition 遵循平台 Agent 定义，layout 可省略。以下是可导入的最小配置，模型留空，导入后需选择当前项目可用的模型才能测试或发布：

{
  "format": "agent-studio.canvas",
  "formatVersion": 1,
  "name": "资料助手",
  "definition": {
    "definitionVersion": 1,
    "engine": "deepagents",
    "workflowNodes": ["agent", "model"],
    "modelRef": null,
    "instructions": "根据提供的资料整理要点，并说明依据。",
    "toolRefs": [],
    "skillRefs": [],
    "subagents": []
  }
}

让 AI 生成或扩展画布时，将下载的 JSON Schema、已有导出文件和目标项目可用的资源引用一起提供给 AI，要求返回完整 JSON；不要让 AI 编造模型源 ID、工具/技能版本或 MCP ID。可省略 layout 交给画布自动排布。导入会拒绝未知格式版本和配置字段，主、子 Agent 的模型、工具、技能、MCP 引用均由服务端按目标项目重新校验。文件不会授予资源权限；保存草稿后仍需配置检查、测试与显式发布。

可选判断阶段

流程可在主 Agent 前添加一个前置判断节点（控制台中显示为 Jev 节点），由外部判断服务对本次输入给出是非概率、候选分类或等级评分，结果作为辅助数据交给主 Agent。先在模型模块的 Jev 分类配置连接并授权给项目，再在画布的 Jev 节点选择模型、设置判断类型与问题。它固定位于输入与主 Agent 之间，不做条件分支，不替代 DeepAgents 执行，也不构成资源授权或自动审批。

部署者需要为 Worker 配置判断服务的 API Key（.env.example 中的 STUDIO_SECRET_JEV_API_KEY）。未配置或服务不可用时 Run 明确失败，不会用默认判断代替真实结果。

标识与调用

Agents 列表提供稳定的随机短 ID，例如 wf-2a73c48b91e6。它不随名称改变；旧 slug 和 UUID 保持兼容。运行接口始终按凭证所属项目查找，不允许跨项目寻址。

实例声明 agentSlug 能力时，Python SDK 可以直接用短 ID 寻址 Agent；独立 JavaScript / TypeScript SDK 在当前平台使用 { agentId } 或 { agentSlug }，字符串 workflowId 仅用于支持该协议的服务端，见客户端差异。

回滚的作用范围

切换生产指针影响之后创建的默认运行。已经创建的 Run 继续使用其冻结快照，不能通过回滚草稿去改变正在执行的资源组合。

固定发布版本的外部调用能力，应以 /v1/meta 的实际声明为准。SDK 具有某个参数，并不代表当前实例已开放相应能力。

07 / PLAN & DELEGATE

规划与子 Agent

将多步目标拆成计划，让专门的子 Agent 在独立资源边界内完成子任务。

为职责拆分子任务

主 Agent 负责目标理解和综合结果。子 Agent 适合承担检索、审阅、整理或验证等明确子任务。为每个子 Agent 配置名称、委派说明、模型、工具与 Skills，避免只复制主 Agent 的全部资源。

在发布和测试前，Studio 验证各组件的资源，并将主 Agent 与子 Agent 的定义一起冻结。控制台画布中的子 Agent 节点，只有保存进草稿定义并随快照冻结后才会实际参与委派。

独立上下文或继承上下文

选择最少且充分的上下文，可以减少任务之间相互干扰。共享上下文不是共享所有权限。

配置规划与并发

主 Agent 和子 Agent 可分别启用规划。启用后产生真实待办状态；控制台展示计划进度与执行事件。

平台限制同步委派的并发数量，主 Agent 与子 Agent 的调用共享当前 Run 的预算。达到预算或取消父 Run 时，委派需要遵守同一条停止边界。

单独测试与后台任务

可以单独测试已保存的子 Agent 配置，验证模型、工具和结果规范，再放入主 Agent 的完整任务中测试。

需要后台委派时启用平台异步子任务配置，并选择适用的隔离子 Agent。后台任务拥有独立状态与预算，同时保留父子运行关系，详见触发器与后台任务。

08 / MODEL CONFIGURATION

模型与 Harness

管理模型来源与参数，让主 Agent 和子 Agent 使用适合各自职责的配置。

配置模型来源

模型来源将服务端点、模型目录、凭证引用与联网方式集中管理。Agent 保存来源和模型引用；运行时冻结所选适配配置，密钥由服务端解析。

模型页面按 LLM、Embedding、Jev 分类，新增时沿用当前分类；已有模型源不能直接更改分类。三类资源都需要向使用项目显式授权。

专用模型不会成为项目的默认聊天模型。没有对应分类的模型时，先添加连接并在模型列表配置项目使用权限。连接测试会产生真实服务用量，成功只证明当前连接与协议可用，不代表业务质量已经评测通过。

Embedding 默认不发送 dimensions 参数；只有服务商支持时才开启，并填写实际输出维度（1–4096）。模型或维度改变后，在知识页重新应用配置以建立新索引；已有 Run 和旧索引保留冻结配置。Jev 使用固定官方 HTTPS 端点，旧定义的服务端直接引用保持兼容，新配置统一从模型模块选择。

主 Agent 与子 Agent 可以使用不同模型。按任务所需的推理、延迟、工具调用和结果格式选择，并用实际任务评测验证配置。

验证连接与功能

连接测试通过 DeepAgents 检查调用和工具适配。模型列表发现、连接测试与业务评测是不同步骤；目录中存在某个模型不等于它支持全部能力。

参数、代理与出站

在执行设置中维护模型选项和用量单价。自定义端点必须满足出站白名单；选择代理联网时，部署环境必须配置相应代理，不能在配置缺失时静默退回直连。

模型密钥明文不写入定义、Run 快照或事件；内部快照只保存受限密钥引用。你的 SDK 应用也不需要获取平台使用的模型密钥。

模型出口身份与计费上下文

需要按最终用户鉴权或计费时，可在模型源「高级配置」开启「转发运行身份与计费上下文」。开启后 Worker 只对该模型源追加 x-studio-model-identity，值为 Studio 用服务签名密钥签发的 60 秒 EdDSA JWT：iss 为 Studio 公开地址，aud 为 model:<模型源 ID>，声明包含 project、run、actor、component、modelCall、purpose、attempt、source。

默认关闭；普通模型服务商不会收到主体标识。受信任网关应从 /.well-known/jwks.json 取 studio-v1 公钥，校验签名、iss、aud 和 kid 后，再按 actor/run 鉴权、配额和结算。JWT 不含用户资料、权限 scope、密钥、提示词或工具内容。缺少签名密钥或公开地址时运行失败并返回 model_identity_unavailable，不会退化为未签名头。

思考模式与思考过程

主 Agent 与子 Agent 可在执行设置中分别开启思考模式，并选择思考强度和参数格式。参数格式必须与模型端点一致：

启用内置网页搜索时请求走 Responses API，使用 reasoning 对象表达强度与摘要。设置随 Run 快照冻结；未开启思考模式的旧定义和旧快照不发送任何思考参数。标题生成、会话摘要等辅助调用不启用思考。部分端点对思考模式的输出上限另有约束（例如 Qwen 在思考模式下要求 max_tokens 不超过 32768），应按端点文档设置输出 Token 上限。

开启后，端点实际返回的思考内容通过 message.reasoning.delta 和 message.reasoning.completed 公开事件输出，并随会话消息展示；单条消息最多 20,000 字符，超出会截断并标记。思考过程与最终回复分开显示，默认折叠，可在会话页、运行详情和事件记录中查看。平台只展示端点真实返回的内容，不采集端点未暴露的内部推理；思考内容与回复文本同样属于不可信模型输出，不改变工具授权、审批、预算或结果校验。

部分端点要求携带工具时回传历史思考（例如 DeepSeek 要求在助手消息中保留 reasoning_content，否则返回 400）。Worker 从检查点中的真实助手消息回填；在此功能升级前产生的历史助手消息没有该字段，改用新会话或关闭思考模式可避免该限制。

Harness 配置

受控 Harness 设置可补充系统指令或工具描述，让执行更符合任务。它们会随配置被冻结，但不会改变工具授权、审批或文件权限。

提示词中“允许执行某动作”不能替代真实资源授权。来自网页、附件和工具结果的文本，始终作为不可信上下文处理。

09 / TOOLS WITH CONTRACTS

工具与执行边界

以明确的输入、输出、版本和执行位置连接业务能力。

用契约连接业务能力

工具定义包含稳定标识、版本、模型可见名称、描述、输入 Schema、输出 Schema 和执行位置。Agent 只引用已发布且有权使用的工具版本。

创建、测试、发布

在工具页面创建自定义工具，填写输入输出 Schema，选择语言并编写函数。保存后测试，检查结果和失败信息，再发布不可变版本。然后在 Agent 中引用这个版本。

当前自定义工具计算环境没有网络、宿主目录或应用密钥。它不是工作流中的任意代码节点，也不提供宿主 Shell。未准备好容器运行环境时，测试明确失败。

远程工具与权限

远程工具使用明确的 Provider 端点、服务身份与授权。请求受出站白名单和地址限制；工具结果需要满足输出契约。接入方应对有副作用的请求实现自己的幂等处理。

工具目录中可见某项资源，并不等于任意项目可以执行它。Studio 在运行创建和调用过程中核验资源权限。

客户端工具回传

声明设备与可执行工具后，服务端可以产生 client_tool 请求。应用展示具体操作，由设备执行或拒绝，再带回原始请求 ID、参数哈希（HTTP 字段 argsHash，Python 为 args_hash）与结果。

重复提交相同结果可被接受，不同内容返回冲突；设备不符、过期或已取消的请求拒绝执行。回传幂等不自动保证本地副作用幂等，设备还需持久化自己的执行记录。

安装 DSH 插件

首页「插件」可从公开 npm 精确版本、GitHub 固定完整提交及子目录，或预构建 .tgz 安装 DSH Bundle。先检查兼容性，确认导出清单后安装；在详情页测试工具，再授权项目，并在 Agent 中明确选择工具、技能或 MCP。安装成功不会自动修改 Agent 或发布版本。

当前适配器固定 DSH 0.2.1-rc.2，支持静态 insert patch、普通 JSON 配置、无状态离线工具及文本结果。工具代码在独立临时容器中运行，DeepAgents 仍是唯一 Agent 引擎。依赖 Session、UI、Agent Loop、PTC、联网或宿主目录的插件不在支持范围；不执行包的安装脚本。检查结果分别说明格式、加载和调用状态，单次测试通过不表示全部 DSH 生态兼容。

配置按 patch 行 ID 填写；变化会生成新版本。不要在配置中填写凭据。包可用 agentStudio.formatVersion=1 显式映射静态技能和 HTTPS MCP；这是 Studio 扩展字段。MCP 密钥、发现和只读过滤沿用原 MCP 管理，凭据不会传入插件容器。

升级保留旧资源版本和已有 Agent 引用。推荐版本决定详情默认选择和批量授权目标，Agent 仍显式选版本；新资源默认无授权。单资源授权与插件批量授权保持同步，修订冲突会拒绝覆盖。停用阻止新调用并取消在途调用。仍有项目授权、草稿、发布版或历史 Run 引用时不能卸载，可以先停用。插件暂不支持独立部署导出。

插件功能默认关闭，需要管理员完成隔离执行器部署。执行器未就绪、依赖缺失、加载失败或输出不支持时显示失败，不回退为应用宿主执行。

10 / REUSABLE KNOWLEDGE & TOOLS

Skills 与 MCP

复用任务方法，选择工具连接，并为每个 Agent 明确可见资源。

Skills 包装可复用方法

Skill 用 SKILL.md 描述任务方法、知识和使用条件，并可附带文本参考材料。控制台支持草稿、版本与发布；Agent 引用固定版本，运行时以只读文件提供这些材料。

Skills 按需读取，避免把所有资料一次放入启动上下文。它们提供任务知识，不会自动授予工具、网络或宿主执行权限。

添加技能

控制台的「添加技能」提供两种方式：从链接读取完整技能，或上传指定格式的 .zip 压缩包。

从链接添加支持 owner/repo、GitHub 仓库/目录链接、单个 SKILL.md 链接，以及白名单内的 HTTPS 技能文件地址。点击「读取并添加」，仓库或目录内的全部技能会整体保存为一个技能包草稿，不再逐个选择，也不会分别创建技能。默认标识为 owner-repo（目录链接追加目录名）；标识冲突时保留读取结果，可修改标识后重试保存。单个文件链接仍导入该技能，压缩包仍先检查再确认。

技能包自动生成根入口与技能目录；原始 SKILL.md（含 frontmatter）、参考资料、脚本文本等统一放在 repository/ 下，保留来源内的相对目录关系。隐藏目录、依赖和构建目录不导入；图片、PDF 等二进制文件不保存，并在读取结果和技能包入口中记录。最多 256 个文本文件，单文件最多 131072 个字符，材料总计最多 1500000 个字符，入口及材料合计最多 2 MiB。文件树截断、文本超限或读取失败会使本次整体读取失败，不将不完整文本包保存为成功；可改用范围更小的目录链接。整体文件收集最多 90 秒，单次读取仍受超时限制。

添加成功会自动打开详情页的「技能与文件」，可搜索路径并查看任一技能说明或材料；草稿正文与材料仍可编辑。发布后整个包按一个版本引用并冻结，Worker 只发现包入口，再按需读取包内文件；不会把子技能额外注册成独立资源。第三方 frontmatter 的工具、宿主和执行设置只保留为来源文本，不自动启用。

GitHub 仓库导入需要放行 api.github.com 和 raw.githubusercontent.com；匿名接口每小时 60 次，部署可配置只读 STUDIO_GITHUB_TOKEN 提高额度。私有仓库当前不保证可读。服务端拒绝重定向、内网地址和超限内容；读取成功后整体保存为草稿；链接内容不会直接发布。

「添加技能 → 从链接添加」与首页「环境变量」均提供 GitHub 导入凭证 入口。点击「配置个人 Token」，填入专用最小权限 GitHub Token 后保存；变量名固定为 STUDIO_GITHUB_TOKEN，类型固定为密钥。保存、轮换与删除立即影响后续导入，无需重启。页面仅显示保存状态，标注未验证，不回显密钥。个人配置优先于服务端同名环境变量；个人配置删除后恢复服务端后备，没有后备时使用匿名请求。个人配置损坏或不可读取时返回错误，不静默换用其他身份。

服务端仅从当前用户独立的首页资源空间读取此密钥，并仅附加到 GitHub API 请求。业务项目中的同名变量、其他用户变量和资源关联均不会提供此凭证；GitHub 仓库树缓存按凭证隔离。普通技能文件链接、Agent/Run、Worker、工具、MCP 与沙箱不消费此变量，页面配置不改变其他环境变量的管理面边界。

新增或更换此密钥时，表单提供 GitHub 生成入口及权限说明。公开仓库导入使用 Fine-grained Token 默认的公开仓库只读访问，无需额外仓库、账号、组织或写入权限；入口预填 30 天有效期。生成后复制到「值」并以密钥保存。私有仓库树 API 需要 Contents: Read-only 及目标仓库访问权，但当前私有文件导入不保证可用，参见 Token 官方说明及仓库树接口权限。

Token 仅用于 GitHub 身份认证和额度，不解决网络、DNS 或代理故障。仓库树读取遇到瞬时连接错误时最多重试一次，两次读取合计最多 12 秒；权限、无效令牌、白名单、证书错误及限流不自动重试。控制台分别提示网络错误、读取超时、无效 Token、权限拒绝和限流；Token 无效或权限拒绝需修正配置，限流需等待后重试，不会要求重新登录 Studio。

部署时在 STUDIO_PROVIDER_ALLOWED_HOSTS 中加入 api.github.com,raw.githubusercontent.com，保留已有域名，然后重启 API。若透明隧道将这两个域名解析为 198.18.0.0/15 虚拟地址，优先配置 STUDIO_PROVIDER_PROXY；没有显式代理时可设置 STUDIO_SKILL_GITHUB_ALLOW_FAKE_IP=true（默认关闭）。此开关仅供技能导入访问这两个固定 GitHub 域名，仍检查白名单、HTTPS 证书并拒绝其他私网地址，不影响普通技能链接、工具或 MCP。

如果技能包含脚本或外部工具，读取结果会记录可能需要的工具和脚本文件；需要确认的导入预览会显示这些提示。平台只把脚本作为文本材料保存，不会执行，也不会自动安装这些工具；安装说明后续补充。

压缩包方式接受 8 MB 以内的 .zip：根目录或唯一顶层目录必须包含且只包含一个 SKILL.md，其余文本文件作为材料读取；选择文件后自动检查并生成预览。建议在 frontmatter 提供 name 和 description，缺失时可在预览中补全。

推荐目录：

my-skill.zip
└── my-skill/
    ├── SKILL.md
    ├── references/
    ├── assets/
    ├── rules/
    └── scripts/

两种方式创建同一套草稿，仍需检查并在发布后供 Agent 引用固定版本。

技能依赖

技能详情的草稿编辑器提供「技能依赖」区域，显示所需工具、MCP、检测来源和关联状态。可添加或移除依赖、关联已有资源，并进入工具/MCP 管理页面。关联编辑应用到草稿后，需点击技能的「保存」；发布后声明与关联随固定版本冻结。

• 已配置：已显式关联到当前账号同组织可维护的资源，工具有发布版本，MCP 满足启用、必需密钥与只读工具等基本配置条件。此状态不验证上游连接。
• 缺失：未关联、关联资源已删除或不可访问，或 MCP/插件已停用、缺少基本配置。查看原因后可更换关联或到管理页面补齐。
• 待保存／待检查：编辑尚未保存，或资源目录加载中/失败；不会把无法检查的状态当作已配置。

自动检测只针对实际导入或已保存的正文与材料，识别部分工具声明、命令、脚本类型及 MCP 配置名称，不采集配置值或凭证；被排除的隐藏文件与二进制不参与检测。结果仅供提示，可人工补充、纠正或移除，最多 64 项。「从已保存内容检测」合并新提示并保留人工声明和关联。

技能关联不自动授予运行权限。 不会安装工具、连接 MCP、配置密钥或将资源注入 Agent。项目仍需获资源授权，主/子 Agent 仍需分别选择工具和 MCP。依赖缺失不阻止保存或发布，运行前请按实际任务核对。

技能来源与历史兼容

平台不再提供预设内置技能。请从链接或压缩包导入所需技能，检查后发布，并分别配置给主 Agent 或子 Agent。

已有 Agent 草稿如果引用已移除的内置技能，保存、测试或重新发布前需移除引用或替换为可用的自定义技能版本；服务端会拒绝不存在的版本。已有发布版本与 Run 中冻结的技能正文保留，继续按原有权限校验执行，不会被自动改写。

Skill 的使用过程

1. 编写清晰的描述与正文，说明何时使用和输出要求；从链接或压缩包导入后检查识别结果。
2. 添加需要的参考材料，保存并检查内容。
3. 发布版本，将该版本分配给主 Agent 或子 Agent。
4. 运行测试，观察材料是否被读取、任务结果是否满足要求。

附带的脚本只作为文本材料提供，不会在宿主上执行；需要计算时，使用已授权的工具，例如自定义隔离计算工具。

MCP 连接已有工具服务

MCP 连接提供标准化的工具发现和调用。配置服务后，按工具选择 Agent 可以使用的资源；主 Agent 与子 Agent 的选择分别进入运行快照。

Worker 按 Run 管理 MCP 会话，在需要时建立连接，完成或取消时释放。会话失效会有限恢复，不使用无限重试隐藏服务不可用。

保留不完整状态

MCP 返回的非文本内容或过大结果可能受当前适配路径限制。省略或截断应保留不完整标记；不能把部分结果描述成全部数据。

连接凭证保留在服务端。工具输出中的文字不能修改权限、绕过审批或要求披露凭证。

11 / CONTEXT THAT PERSISTS

工作区与记忆

用会话工作区、长期记忆与只读知识材料管理不同生命周期的上下文。

按生命周期组织上下文

这些是虚拟路径，不是宿主目录。工作区与长期记忆需要在组件配置中启用，文件读写同时受路径权限、作用域、配额与运行状态约束。

文件维护与冲突

控制台可查看适用范围的文件，进行编辑、下载或删除。更新使用版本冲突检查，避免并发编辑静默覆盖。未保存的修改应先处理，再切换文件或作用域。

主 Agent 与子 Agent 的工作区相互隔离，保留各自的任务边界。持久记忆跨 Thread 使用时，应选择符合业务需求的用户、Agent 或项目范围，而不是默认共享所有上下文。

启动规则与长期记忆

启动规则文件会随定义冻结，在开始执行时读取；长期记忆通过数据库后端保存。前者保证当前执行的规则依据，后者承载允许跨会话延续的信息。

记忆内容仍然不能授予权限，也不应保存凭证。删除用户数据时，遵循平台的主体与数据保留边界。

摘要、大结果与知识检索

达到配置的上下文阈值时，摘要中间件压缩历史并保留回读路径；大工具结果可以卸载到工作区，给 Agent 提供文件引用。

项目知识检索支持多个关键词、中文问句自动拆词、不区分大小写匹配和上下文片段；按词项覆盖、完整短语、标题及有上限的词频排序，减少重复词噪声。资料在 PostgreSQL 中分块；预装 pg_trgm 并建立正文及标题索引后使用 trigram 索引，否则使用分块扫描。配置 Embedding 和 pgvector、完成索引后，可按 Agent 开启关键词与语义融合的混合检索。拆词和本地排序不调用模型，也不提供同义词理解或答案正确性保证。

项目知识库

项目所有者可以维护资料和向量配置；项目成员可只读查看并进行关键词试检索。知识页显示容量、每个文件的分块状态和实际索引方式。试检索与 Worker 共用检索实现，不创建 Run；关键词试检索不调用模型，混合试检索会调用 Embedding 并产生上游用量，需要控制台运行权限。正常零命中、部分结果和检索不可用分别展示。

导入支持 UTF-8 的 TXT、Markdown、CSV、JSON，每批最多 32 个、单文件最多 2 MiB。先预览完整内容和虚拟路径，再确认导入；同名文件返回冲突，不自动覆盖。项目总上限为 256 个文件、16 MiB。部署方启用隔离文档转换后，还支持普通 PDF（最多 200 页）和 DOCX；转换文本保留页码或段落标记。扫描页需要先完成 OCR，加密、损坏、压缩展开超限及正文超过 2 MiB 会明确拒绝。转换失败不会写入知识库。二进制附件能存储不代表能被知识检索。

主、子 Agent 分别配置知识开关、路径范围、最多返回片段数和上下文行数。表单和画布编辑同一份草稿；修改须保存后再测试或发布。关闭知识访问会同时关闭搜索工具和知识文件读取。旧定义未设置开关时保持只读访问。知识节点是配置入口，资料仍在知识页统一维护。

检索返回 sourceId、文件版本、内容哈希和行区间。要求结构化引用时，可在 Result Profile 的对象 Schema 中声明 citations 数组，元素包含 sourceId，并可包含 revision、contentHash、lineStart、lineEnd。Worker 检查引用是否来自本次 Run 的证据；来源、版本或行范围不符时报 citation_not_in_evidence，不发布结构化结果。纯文本回答不强制校验；来源存在也不等于结论一定受到原文支持。

新来源链接包含文件 ID，打开该修订原文并定位行号，历史视图只读，可单独打开当前资料。更新前正文与文件更新在同一事务归档；每文件最多保留 20 个旧版本、项目历史正文合计最多 64 MiB，超过时清理最早版本。历史不计入当前 16 MiB 资料配额，也不参与检索。删除资料或项目会同时删除相应历史；升级前未归档或已清理的版本明确提示缺失，旧链接仍显示版本变化提示。知识内容属于运行时项目数据，不随 Agent 定义冻结；异步子 Run 的证据不会自动归入父 Run。

部署时先执行包含 0050_knowledge_file_revisions、0051_knowledge_document_imports 和 0052_knowledge_heading_index 的迁移，再启动 API/Worker 并核对 /readyz。存量资料在 Worker 空闲维护周期分批补建，未完成时扫描回退并标记部分结果。需要 trigram 时，由数据库管理员预装 pg_trgm，确认中文可用的数据库 locale，再用已确认目标的迁移角色执行：

STUDIO_MIGRATION_DATABASE_URL='<已确认目标的迁移连接>' pnpm --filter @agent-studio/db knowledge:index

该命令不安装扩展；运行时角色不获得 DDL 权限。API 与 Worker 的 STUDIO_KNOWLEDGE_SEARCH_TIMEOUT_MS（默认 5000）和 STUDIO_KNOWLEDGE_MAX_SNIPPET_BYTES（默认 20000）应一致。检索结果还受 Agent 的工具响应总大小限制。

启用 PDF 与 DOCX 转换

1. 在受控 Docker 执行节点构建 docker build -t studio-knowledge-parser:1 deploy/knowledge-parser。将 STUDIO_KNOWLEDGE_PARSER_IMAGE 指向该节点已存在的镜像；生产可使用镜像摘要。运行时禁止自动拉取镜像。
2. API 与 Worker 同时设置 STUDIO_KNOWLEDGE_DOCUMENTS_ENABLED=true，并保证 Worker 的 Docker 控制命令可访问上述执行节点。Compose 可叠加 deploy/compose/docker-compose.knowledge.yml：配置 STUDIO_PARSER_DOCKER_HOST 为独立执行节点的 TLS Docker 地址，证书目录中提供 ca.pem、cert.pem、key.pem，通过 STUDIO_PARSER_DOCKER_CERT_DIR 与 STUDIO_PARSER_DOCKER_CERT_GID 只读提供给 Worker。此覆盖文件不挂载宿主 Docker socket；API 不持有 Docker 控制身份。
3. 上传文件后等待转换，在预览中核对正文、页码/段落及目标路径，再确认保存。每个 Worker 最多同时处理一个转换任务，临时容器无网络、无宿主目录和 Studio 密钥，限制为 256 MiB、30 秒。每项目最多 8 个待处理/待预览任务，临时输入与预览最多保留 30 分钟；取消或预览读取完成后清理临时正文。任务租约可恢复，服务暂不可用最多尝试 3 次。

转换默认关闭；只打开 API 开关不代表 Worker 或镜像已经就绪。部署后用真实文件验证转换、取消和故障反馈。未提供 OCR、旧版 .doc、网页抓取或外部文档同步。

启用语义与混合检索

1. 选择云端 Embedding API，或自行部署提供兼容 /embeddings 接口的服务。在模型模块的 Embedding 分类维护 HTTPS 地址、密钥、模型名称、版本标识、维度（1–4096）、超时及可选价格，并授权给使用项目；知识页只选择并应用该模型源。只有服务支持缩减维度时才开启“发送维度参数”。自托管服务同样遵守域名白名单、私网拦截和代理规则；不会因为选择自托管就开放任意内网地址。
2. 在现有 PostgreSQL 安装 pgvector。Compose 可显式设置 STUDIO_POSTGRES_IMAGE=pgvector/pgvector:pg16；已有数据库保持 PostgreSQL 主版本一致，更换镜像前备份并验证数据卷。无需新增向量数据库或单独的知识服务。
3. 由数据库管理员在目标数据库执行 CREATE EXTENSION IF NOT EXISTS vector;。应用包含 0038_knowledge_vectors 的迁移；如果迁移早于扩展安装，再显式执行：

bash STUDIO_MIGRATION_DATABASE_URL='<已确认目标的迁移连接>' pnpm --filter @agent-studio/db knowledge:vector

1. 启动更新后的 API 和 Worker，检查 /readyz 及知识页的向量存储状态。保存向量配置后，Worker 先验证模型连接和实际返回维度，再对资料增量生成向量。每个 Worker 的 STUDIO_KNOWLEDGE_VECTOR_CONCURRENCY 默认为 1，可设为 1–4；可暂停、恢复或重试失败项。最多自动尝试三次，连续失败会进入冷却。未知用量或价格显示未知。
2. 索引就绪后，用相同问题分别试验关键词和混合检索，检查来源、延迟与提供方费用，再在主/子 Agent 的知识设置中各自选择混合检索，保存、测试并发布。默认仍是关键词。Run 冻结索引、模型、版本、维度与价格，查询向量计入本 Run 的模型/Token/时长预算；后台建索引用量单独统计。

更换模型或维度会建立新索引，不混合不同向量空间。已有 Agent 保留保存时的索引引用，可在设置中改用当前索引；修改上游模型别名指向时应更新版本标识并重建，Studio 无法冻结提供方内部权重。资料更新或删除后，旧向量立即被检索条件排除。

向量索引不完整或服务超时、暂停、冷却时回退到关键词，响应标记为部分可用。取消、权限撤销、预算超限和有 Token 上限时的未知用量会明确终止，不作为普通降级隐藏。索引和查询的幂等身份用于恢复去重；实际重复计费是否避免仍取决于上游服务的幂等支持。

当前仅实现 pgvector 存储，使用精确余弦召回与 RRF 融合；未提供其他向量数据库或 rerank。PDF/DOCX 通过上文的可选隔离转换生成文本后入库，不提供 OCR 或旧版 .doc 解析。真实提供方的语义质量和生产性能需要用目标资料另行评测。

项目资料和向量索引不随独立部署包导出。主或子 Agent 启用混合检索时会明确阻止导出，避免丢失冻结配置后生成无法按原配置运行的副本；独立部署的知识服务可通过远程只读工具接入。

首页环境变量

在工作台的“环境变量”模块统一创建普通配置或密钥，并选择关联的工具、技能、MCP 或模型。名称创建后不能修改；同一变量可以关联多个你有维护权的资源。普通配置可查看和复制，密钥保存后不回显，编辑时留空可保留原值。

新变量保存在当前维护者的独立资源空间，不随业务项目切换。项目内已移除环境变量入口，旧链接会跳转首页；原记录保留供来源所有者管理。同名旧记录按来源区分。名称在新资源空间内唯一，不同资源若需要同名但不同值，当前须采用不同变量名称。

资源关联只是管理配置：不会授予项目使用权，也不会注入 Run、Worker、工具容器、Skill 或 MCP 请求。模型和 MCP 的现有认证设置仍独立生效。删除资源后变量保留，可编辑并移除失效关联；删除变量会同时移除关联并清理其托管密钥。

12 / A DURABLE EXECUTION

运行、事件与恢复

一次运行拥有身份、状态、检查点和有序事件，可以被查询、取消和恢复。

Thread 与 Run

Thread 是一个会话；同一 Thread 的多次 Run 共享上下文。Run 是一次执行，包含冻结配置、输入、身份、状态与结果。一个 Thread 同时只能有一个未结束的 Run。

queued → running → completed / failed / cancelled
             ↓
       waiting_client → 重新入队 → running

失败与取消也是终态。HTTP 请求已被接受，不等于 Agent 已执行完成；应用应持续观察 Run 状态或事件。

公开事件

每个事件都有 Run、Thread、时间与递增 seq。服务端可以新增同一主版本内的类型和字段；客户端应容忍未知类型。

SSE 与恢复

SSE 的 id 使用事件序号，连接定期发送心跳。客户端以 Last-Event-ID 续接；慢消费者超过缓冲上限时断开，再按游标恢复，而不是无限积累内存。

事件记录受保留期影响，不能保证任意旧游标永远可读。检测到缺口时，应明确报告历史不完整，并查询当前 Run，不补造遗漏过程。

检查点、租约与取消

Worker 以租约领取 Run，并定期续期。检查点保留执行上下文；Worker 失效后由队列与租约机制回收。需要审批的运行持久化等待请求，释放执行资源，决定被接受后恢复。

取消是显式的服务端操作。取消等待中的 Run 会使相关请求失效；取消已终态 Run 返回原状态。断开 SSE、关闭网页或取消本地异步任务不自动等同于取消服务端执行。

分支与事件重放

事件重放读取已发生的公开记录。检查点分支创建新的会话分支，保留可用的上下文和工作区边界，支持从历史继续调试；它们不应被用于重复触发源运行中已完成的副作用。

13 / HUMAN IN THE LOOP

审批与人工介入

在关键工具动作前暂停，把真实用户决定带回原来的执行上下文。

在工具动作前暂停

为需要用户决定的工具配置审批策略。DeepAgents 中断会转成持久化的待处理请求，Run 进入 waiting_client；控制台或应用展示工具、参数、期限和允许的决定。

等待状态不占用 Worker 并发槽位。提交决定后，平台校验请求与参数，将 Run 重新入队，并从原检查点恢复。

批准、拒绝与修改

以请求的允许决定列表为准（HTTP 字段 allowedDecisions，Python 为 allowed_decisions）。请求 ID、参数哈希、期限、Run 状态和用户身份共同限定该决定的作用范围。

客户端设备请求

client_tool 请求还绑定创建 Run 时声明的设备。普通审批决定不能替代设备的执行与批准协议；绑定设备回传执行结果，服务端再校验输出 Schema 和请求一致性。

结果一致的重复提交返回首次响应；不同内容冲突，设备不匹配或请求已过期会被拒绝。设备应在执行前确认请求仍有效，并对自己的副作用做幂等记录。

使用 SDK 处理等待

Python 中自行消费 run.events()，收到等待事件后查询 run.pending()，将实际用户决定提交给 run.decide()。客户端工具使用 submit_client_tool_result()。

wait() 只等待终态，不提供自动审批。不能以模型判断替代真实用户对有副作用动作的决定。完整调用模式见SDK 会话与事件。

14 / OUTPUTS YOU CAN CONSUME

结果规范与多模态

将模型回复变成应用可检查、可处理的结果，并保留缺失与截断状态。

定义 Result Profile

Result Profile（结果规范）用 JSON Schema 描述应用需要的结构化结果。设置在 Agent 或子 Agent 的执行配置中，并以版本化资源进入当前 Run。

例如，应用可以要求结果包含总结、待办列表与待确认事项，而不是在业务代码中从自然语言回复猜测字段。

{
  "type": "object",
  "properties": {
    "summary": {"type": "string"},
    "actions": {"type": "array", "items": {"type": "string"}},
    "openQuestions": {"type": "array", "items": {"type": "string"}}
  },
  "required": ["summary", "actions", "openQuestions"],
  "additionalProperties": false
}

这是结果 Schema 示例，配置时请按业务需要调整。

最终输出必须校验

Studio 将结果规范连接到模型的结构化输出策略，并在发布最终结果前再次校验。无效结果以 result_profile_invalid 等明确失败状态终止，不能作为有效业务对象使用。

Run 响应包含文本 result、可空的 structuredResult、错误码和截断信息。Python 模型对应 structured_result 与 result_truncated。

输出策略

Result Profile 的 strategy 决定结构化输出方式：

策略随 Profile 版本不可变保存，并在 Agent 快照中冻结。旧 Profile 未设置策略时按 provider 解析；最终结果仍会重新校验 Schema 与引用，不因切换策略跳过校验。

证据与来源

远程工具可在来源记录中返回有界 metadata（最多 32 个键、深度 4、序列化长度 8 KiB），用于数据日期、报告期、提供方、覆盖范围、内容摘要或警告等业务信息。元数据不能承载正文、凭据或密钥，也不能作为指令。

{
  "sourceId": "quote:600519:2026-09-30",
  "sourceType": "finance.quote",
  "retrievedAt": "2026-09-30T08:00:00.000Z",
  "metadata": {"dataAsOf": "2026-09-30", "provider": "astock", "coverage": "full", "unit": "CNY"}
}

按 Run 查询来源：GET /v1/projects/:projectId/runs/:runId/evidence。响应包含 sourceId、sourceType、retrievedAt、availability 和 metadata；只返回当前项目、当前主体可见的来源索引，不返回工具输出正文。知识检索的 fileId、版本、哈希与行号仍用于平台内部引用校验，不作为公开 Evidence 字段返回。

附件与多模态

附件引用由 API 在创建 Run 时解析并冻结，执行时挂载为只读材料。后续修改或删除原文件不应改写已经创建的输入。

图片、PDF 或其他多模态内容能否被模型理解，取决于具体模型和适配路径。当前平台不保证对任意文件执行 OCR 或解析；不支持、截断或省略必须保留明确状态。

Python SDK 的 attachments 参数引用服务端已有文件 ID；当前 Python SDK 没有文件上传包装。独立 JavaScript / TypeScript SDK 同样只引用已有文件 ID；上传与文件操作使用 HTTP 文件接口，见接口参考。

首轮对话标题

在 Agent 的「结果输出」中开启「自动生成对话标题」，保存后参与草稿测试，发布后用于新的正式调用。只在新对话的首轮回答成功后，根据第一条用户消息和首轮回答总结一次；后续追问沿用该标题。既有对话、失败或取消的首轮不会由后续对话补生成，分支与子 Agent 测试不生成主对话标题。

标题复用当前 Run 冻结的 Agent 模型，独立进行一次无工具总结，最多 10 秒、最多输出 128 Token，并计入运行用量。预算不足、标题调用失败或空标题不影响正常回答。为避免重复调用，生成步骤一旦开始，即使 Worker 恢复也不会重发；极端情况下可能没有标题。

Run 查询、运行历史和线程列表通过可空的 threadTitle 返回标题；未生成时为 null。SSE 的 thread.title_generated 事件包含 payload.threadTitle，成功的 message.completed 也包含该字段。标题失败时发送 thread.title_failed，错误码为 thread_title_unavailable。标题独立于正文 result 与结构化结果 structuredResult，不需要修改结果 Schema。外部 SDK 是否暴露新增字段取决于其版本，可直接使用 HTTP 或 SSE 读取。

聊天中的部分回复与来源

Playground 与画布草稿测试使用相同的回复展示：正文、主 Agent 公开思考、任务计划、工具调用摘要及来源链接。失败或取消后，已经进入公开事件的正文会保留并标记为“未完成的回复”，不改写 Run 的失败或取消状态，也不作为有效的结构化结果。

重新进入会话时，服务端从公开事件恢复多轮主 Agent 思考，以及没有最终结果的部分正文。单轮文本和思考沿用 20,000 字符上限；每个 Run 最多回放 4,096 条展示事件、32 个模型消息，来源最多 32 个。超出上限或增量存在缺口时，界面提示历史不完整；完整已保存事件可在运行事件页查看。未保存到公开事件的内容不能恢复。

原生网页搜索实际返回的引用和来源经 message.sources 事件公开。payload.sources 包含 url、title 和 kind（citation 表示引用，search 表示搜索来源）；仅允许无凭证的 HTTP(S) 链接，标题按纯文本展示。没有来源的响应不生成模拟引用。会话消息可选携带 sources、partial、reasoningTruncated 和 historyTruncated；旧消息与客户端继续兼容，客户端应忽略未知事件和可选字段。

15 / QUALITY BEFORE RELEASE

评测与发布门禁

用版本化评测集验证变更，把质量要求落实到服务端发布流程。

使用版本化评测集

将典型输入、结果判断规则与通过率要求整理为评测集。发布后版本不可变；变更样本通过新版本进行，避免评测口径被静默改变。

评测产生可查询的样例 Run 和评分结果。受阻、失败和已取消的样例需要保持可见，不能通过缩小分母让质量结果看起来更好。

建议的验证流程

1. 为常见任务与重要失败情形准备样本。
2. 对已保存的当前定义运行评测。
3. 查看样例回复、结构化结果、错误和评分，而不只看汇总通过率。
4. 修复配置并重新评测，再提交发布。

外部数据变化较大的工具，可以在评测环境使用固定数据快照，同时保留少量真实服务联调；两类结果分别记录。

服务端发布门禁

门禁绑定评测集版本、定义和编译资源快照依据。修改模型配置、工具或执行设置后，旧评测不能继续为新发布放行。

配置门禁后，发布动作在服务端核验要求，而不是仅靠界面禁用按钮。门禁受阻时，应展示具体原因并重新完成评测。

可复现的含义

平台保留定义、模型与工具配置、样本版本和判断规则。语言模型仍可能产生不同措辞，甚至不同策略；因此验收条件应面向任务要求，而不是默认逐字比较。

16 / AUTOMATION WITH LIMITS

触发器与后台任务

按明确触发条件启动已发布 Agent，观察有界后台委派的状态。

触发已发布的 Agent

触发器按固定间隔、日历计划或已鉴权的 Webhook，为本项目已发布的 Agent 创建普通 Run。每次新建独立会话并冻结当时的生产版本与输入，草稿变更不直接参与执行；新的生产发布影响后续触发，不改变已有 Run。

新建任务默认关闭。选择 Agent、填写输入及运行策略后，可以先检查配置，再保存并启用。间隔最短 60 秒，最长 31 天；页面支持秒、分钟、小时和天。保存、编辑或恢复启用后，从当前时间重新计算下一次触发。服务恢复时最多处理一个已到期周期，错过的多个周期不累计补发。固定间隔不等于每天指定时间；如需按当地时间运行，请选择日历定时。

日历计划与时区

日历定时支持每天、每周指定星期、指定日期仅一次，以及开始/结束日期（含当天）。选择 IANA 时区，如 Asia/Shanghai，再填写当地时间；预览列出未来最多十次，使用所选时区展示。时区由服务端校验，计划计算不依赖浏览器时区。

夏令时开始时不存在的本地时刻跳过；结束时重复时刻只执行第一次。如果第一次已错过，不在第二次重复时刻执行。一次计划或结束日期耗尽后没有后续计划，页面明确显示；手动运行仍遵守启用状态和原有权限。保存、编辑、恢复时重新计算，不补发离线期间的多次计划。

配置示例：

{"kind":"calendar","intervalSeconds":null,"calendar":{"frequency":"weekly","timeZone":"Asia/Shanghai","time":"09:00","weekdays":[1,2,3,4,5],"startDate":null,"endDate":null,"date":null}}

星期为 0（星期日）至 6（星期六）。once 使用 date；所有日期均为所选时区的当地日期，格式 YYYY-MM-DD。

检查与手动验证

“检查配置”只检查生产快照、项目与资源授权、沙箱授权和无人值守客户端能力，不调用模型或工具，不验证真实上游连通性，也不创建 Run。主、子 Agent 中包含必须依赖客户端的工具时不能无人值守执行。

“运行一次”适用于已启用的固定间隔、日历和 Webhook 任务，会产生真实 Run、用量及正常工具副作用。确认框展示生产版本及本次输入；输入覆盖只影响这次运行，不改变已保存配置或下次计划。控制台携带检查时的版本 ID；生产版本在确认期间变化时返回 409 production_changed，需要重新检查。人工审批仍须由用户正常处理，触发器不会替用户批准。

管理、检查、手动运行、通知和审计仅向项目所有者开放。运行详情与触发历史继续按项目、执行主体隔离；拥有触发器维护权不代表能读取其他主体的执行输入或结果。触发器默认不延续前次会话。

运行与失败策略

还可设置更严格的 Token、步骤及工具调用上限。Token 或费用信息不可获得时显示不可用；费用为估算，不能当成精确账单或硬性费用预算。

这里只重试创建 Run 前的暂时性故障，遵守平台的终止类及可重试类状态码。已启动的任务不会整任务自动重跑，避免重复工具副作用。Run 内部已有的模型/工具重试与创建重试分别计数。重试状态与冻结配置持久化，调度器重启不丢失；编辑或暂停任务会取消尚未入队的旧重试，已有 Run 继续使用原快照。

暂停停止后续触发及待创建重试，已有运行继续。独立的“暂停并取消我的活跃运行”只请求取消当前所有者自己的活跃 Run，不能撤销已经发生的工具副作用。删除任务也不会隐式取消已有 Run，历史按保留期保留。原执行所有者失效时停止调度，不隐式转移执行身份。

Webhook 接入

调用方在自己的后端保存项目 API Key。使用具有 runs:write 权限的 Key、有效的 X-Studio-Actor 和 Idempotency-Key：

curl -X POST 'https://studio.example.com/v1/projects/PROJECT_ID/triggers/TRIGGER_ID/fire' \
  -H 'Authorization: Bearer PROJECT_API_KEY' \
  -H 'X-Studio-Actor: service:example' \
  -H 'Idempotency-Key: event-20261017-001' \
  -H 'Content-Type: application/json' \
  -d '{"input":"处理本次事件"}'

input 可省略，沿用配置输入；提供时是最长 20000 字符的非空文本。此接口只接受启用的 Webhook 触发器。返回 202 和普通 { "run": ... }，表示已入队而非任务已完成；通过原有运行接口或 SSE 跟踪结果。

同一主体的相同事件重试必须复用幂等键与相同输入；不同输入返回 409 idempotency_conflict。暂时创建失败返回 429/503，调用方按退避重新鉴权并使用同一幂等键重试。后台不保存或复用项目 Key；没有再次鉴权的外部创建重试不会自动执行，超过有效期后释放占位；未设置排队有效期时，此类待创建重试最多保留 24 小时。每个触发器每分钟最多接收 60 个新的逻辑触发，超限返回 429 trigger_rate_limited；幂等重放不额外占用额度。并发或每日次数超限记录为跳过，fire 返回终止类 409。

原 /fire 继续采用项目 Key 鉴权；结构化事件另用下述签名入口。脚本表达式与外部结果回调不在此能力范围内。

结构化 JSON 与签名事件

Webhook 配置可启用签名事件入口。定义最多 30 个字段，使用 JSON Pointer（如 /issue/title、/items/0/name，~1 表示 /、~0 表示 ~），选择 string/number/boolean 与是否必填。正文必须是 JSON 对象，最多 64 KiB；字段只读取自有属性，不执行代码或表达式。缺失可选字段替换为空字符串，类型错误或缺失必填字段返回 400 trigger_event_invalid。输入模板使用 {{ title }} 等配置的名称；映射结果最多 20000 字符，未知名称返回 400 trigger_event_mapping_invalid。先用示例 JSON 预览，不会创建 Run。

配置 event.secretRef 指向 env:STUDIO_SECRET_...、file:/run/secrets/... 或当前项目的 managed: 引用。密钥由部署环境或既有密钥管理提供，使用至少 32 字节的随机密钥，不能把明文写进配置。发送到：

POST /v1/projects/{projectId}/triggers/{triggerId}/events
Content-Type: application/json
X-Studio-Timestamp: <Unix 秒>
X-Studio-Event-Id: <8-128 字符的稳定事件 ID>
X-Studio-Signature: sha256=<小写十六进制 HMAC-SHA256>

签名消息为 timestamp + "." + eventId + "." + 原始请求体字节，前后五分钟内有效，签名后不能重新序列化正文。第三方服务需要按此协议发送，或由接入方后端验证其原生协议后转签；此入口不会自动兼容每一家服务的原生签名头。签名失败/过期返回 401；同事件 ID 与完全相同正文返回同一 {delivery}；正文变化返回 409 idempotency_conflict。成功返回 202 {delivery}，可能是已入队、重试等待或配额跳过，不能当作执行完成。

签名入口按触发器原执行所有者创建 Run，后台创建重试仍重新检查其权限、资源与队列有效期。与 /fire 的外部主体历史隔离。签名密钥不可用返回 503 trigger_secret_unavailable；停用入口返回 404。每分钟限额和执行策略与原接口一致。

历史、通知与接口

详情通过 ?trigger=TRIGGER_ID 深链接访问。触发历史分别展示触发结果与 Run 状态，记录计划、接收、入队、开始/结束、创建次数、版本、重试时间、错误原因与可获得的用量。支持来源、状态、日期筛选和有界游标分页。没有实际执行的记录不伪造版本或用量。日期筛选使用 UTC 日期；显示时间使用浏览器本地时区。

原配置接口保留；新增接口如下，路径均以 /v1/projects/{projectId} 为前缀：

控制台写操作遵守现有 CSRF、项目权限、修订冲突与资源撤销规则。API Key 可调用原 fire 接口，不能管理任务或使用控制台接口。签名事件入口使用上述专用 HMAC 协议，不使用控制台 Cookie。通知只含任务名和错误码，不包含运行正文、密钥或请求体。外部调用异常通知给任务原所有者，执行历史仍属于外部主体。可另外配置本项目所有者接收通知及外部渠道，见下文。

运行正文与检查点沿用现有保留期清理；新增触发元数据、通知和审计按项目保留期分批清理。主体隐私删除会停止该主体的调度与待创建重试，并删除其触发记录、通知及审计。

通知接收人与外部渠道

启用异常通知后，可选最多 20 位本项目有效所有者接收站内信和邮件；留空默认执行人，外部项目 Key 调用默认原任务所有者。异常、自动暂停、等待人工处理和恢复通知沿用去重规则。企业 Webhook 使用 notifications.webhookRef，引用中保存完整机器人 URL，避免 URL 内的令牌进入数据库。消息只有任务名、状态码及投递 ID，不发送运行正文或结果。

邮件使用部署方配置的 HTTPS 邮件网关，接受 POST {from,to:[email],subject,text}、Bearer 鉴权及 Idempotency-Key。Worker 配置：

STUDIO_TRIGGER_NOTIFICATION_ALLOWED_HOSTS=mail.example.com,bot.example.com
STUDIO_TRIGGER_EMAIL_URL=https://mail.example.com/emails
STUDIO_TRIGGER_EMAIL_FROM=studio@example.com
STUDIO_TRIGGER_EMAIL_SECRET_REF=env:STUDIO_SECRET_TRIGGER_EMAIL_TOKEN

实际令牌由环境安全提供。Webhook 消息使用 {"msgtype":"text","text":{"content":"..."}}，支持返回 errcode:0 的企业文本机器人协议；其他协议需接入方网关适配。HTTP 错误和非零 errcode 均记录失败。出站仅 HTTPS 公网域名白名单，禁止重定向和私网目标，每次请求最多十秒。

通知使用 PostgreSQL 持久队列及 60 秒租约，进程中断后可重新领取；总计最多五次，退避 30/60/120/240 秒。永久错误（未配置网关、目标不允许、HTTP 终止类错误等）不重试；暂时故障重试。每次使用稳定投递 ID 作为幂等键，外部网关需提供幂等支持，否则响应丢失时可能重复通知。配置修订、接收人资格或执行人权限变化会取消尚未领取的旧投递；外部请求开始后可能已送达，不能保证撤回。

任务详情显示最近 50 条投递的渠道、状态、次数、错误及下次时间。只有配置和测试通过不代表真实邮箱或企业群已送达，部署后需使用自己的网关进行实际验收。

统计与用量覆盖

详情提供最近 7、30、90 天按 UTC 触发日期汇总的总计及每日趋势。区分触发次数、实际 Run、完成、失败、取消、跳过及创建失败。成功率为完成数量除以完成与失败数量之和；排队、执行中、取消和未创建的触发不进入分母。平均时长只使用有有效开始/结束时间的运行。

输入/输出 Token 与估算美元费用只汇总实际 Run 已上报的数据，并显示 Token、费用与耗时各自覆盖的 Run 数；无数据为 —，不伪造零费用或零 Token。统计按项目、当前执行主体、任务隔离，已超过保留期的数据不在范围内；估算费用不代表上游账单。

后台子任务

启用异步委派后，已登记的隔离子 Agent 可以由平台创建后台任务。父任务得到任务标识，后台执行保留独立状态、预算和父子链接。取消父运行时，子任务遵守既有级联取消规则。

这是 Studio 的平台任务机制，不代表动态创建任意子 Agent，也不表示接入了 A2A、ACP 等远程协议。独立部署实例的调度、固定发布版本及会话延续仍需各自的运行与权限设计。

17 / UNDERSTAND EACH RUN

预算与可观测性

观察计划、调用树、用量、耗时与错误，并以预算限制执行范围。

从运行结果追到调用过程

控制台提供 Run 状态、文本与结构化结果、公开事件、计划和调用树。主 Agent、子 Agent、模型与工具使用明确调用身份，帮助将耗时和失败归因到具体组件。

外部应用调用进入项目的 SDK 调用记录；草稿测试、评测与内部任务保留执行来源。查看记录需要符合当前项目与主体权限。

预算限制

项目与 Agent 的执行设置进入运行限制。超过预算以明确错误终止，不通过无限重试继续执行。同步的主 Agent 与子 Agent 调用共用 Run 的预算，后台任务按自己的预算治理。

用量与费用

上游返回的 token、缓存用量和耗时会用于观测。未报告的字段保持为空；配置单价计算的费用属于估算，不等于模型服务的最终账单。

模型没有报告用量时，平台不会推算 token 或把它记为零。对成本敏感的业务应结合服务商账单与自己的预算策略。

日志

API 与 Worker 输出结构化 JSON 日志，并按脱敏规则移除凭证等敏感字段，可由部署者的日志系统收集。当前版本未内置 OpenTelemetry Trace 导出或指标端点。凭证、业务正文与敏感文件路径不应进入日志。

公开事件用于产品展示，内部观测用于排查与运行管理；不要把内部实现细节或未经授权的数据直接暴露给终端用户。

18 / TRUST BOUNDARIES

身份、权限与数据

以项目、用户、设备和资源授权建立完整的运行边界。

信任层次

控制台会话、项目 API Key、终端用户 actor 和客户端设备具有不同责任。你的应用先验证用户，再用可信 actor 调用 Studio；Studio 将访问限制到凭证项目、当前用户和对应设备。

项目资源可见性、分配和执行授权分别校验。归属其他 actor 的 Thread 或 Run 不应因知道 ID 就可以被读取。

密钥与出站

API Key 明文只在创建时返回，数据库保存哈希。模型与 Provider 凭证通过服务端引用管理，不写入 Agent 定义、Run 快照、事件、检查点或提示词。

自定义模型与 Provider 端点需要满足出站白名单及地址限制。本地开发例外由部署者显式开启，生产不应把该例外当作默认授权。

不可信内容

网页、工具、Skill、附件和知识材料提供任务数据，不能成为修改权限、绕过审批或披露凭证的依据。应用展示回复时仍应转义 HTML 等不可信内容。

客户端工具的执行要求绑定设备、有效请求、参数一致性和用户决定。SDK 不替接入方建立用户身份，也不自动批准工具。

数据保留与删除

项目保留设置约束运行历史和事件可用期。删除 Thread 或 actor 数据需要相应权限；存在未结束 Run 时，先按平台流程取消并等待终态。

如果应用提供用户数据删除功能，需要结合业务数据范围、平台数据与备份保留政策设计流程，不能仅删除界面中的一条会话记录就宣称全部数据已清除。

项目成员与角色

在“首页 → 工作空间 → 团队”管理协作，使用页面顶部的项目选择器切换团队。成员页地址为 /console/members?project=<项目 ID>，原“项目 → 设置 → 成员与角色”链接自动跳转并保留原项目。账号属于 Studio 实例，成员资格属于项目，加入一个项目不会获得其他项目或同事个人资源目录的维护权。

完整成员邮箱只对所有者和本人显示。编辑者不能正式发布、管理成员、修改共享资料或写项目共享记忆；使用共享记忆时需为只读。普通运行和会话始终按当前主体隔离，项目所有者也不会因此得到同事的私有会话；外部 SDK 调用记录仍仅向所有者提供只读观测。

邀请与加入

所有者为单个邮箱选择编辑者或查看者，点击“生成邀请链接”，再自行交给对应收件人。链接绑定项目、邮箱和角色，7 天有效；生成链接不会发送邮件。明文只显示一次，关闭后需要在邀请列表明确重新生成，旧链接随即失效。撤销、过期或邀请人失去所有权都会使邀请失效；失权后重新成为所有者也不会恢复旧邀请。

打开邀请页后，核对项目和权限。已有账号需要以受邀邮箱登录，再明确确认加入；错误账号可切换。尚无账号时，可以凭有效邀请填写名称和至少 12 位密码，在加入项目的同时创建本地账号。使用 Google 登录的实例，也可以先完成 Google 登录再接受邀请。邮箱已有账号时必须正常登录，邀请不能覆盖原密码；账号恢复需要联系实例管理员。平台没有无邀请的公开注册入口：Google 登录只在配置的域名白名单内自动开通账号，且不会授予任何项目权限，未获邀请时只显示“尚未获得项目访问权限”。

邀请凭据从地址 fragment 读取后立即清除，不写持久缓存。预览只换取 15 分钟加入上下文，且不会消费邀请；加入同时校验定向凭据、登录身份和独立 CSRF。预览过期后请重新打开有效链接。

撤权与所有权交接

角色变化和移除使用版本检查，冲突时需要刷新后重新确认。移除或编辑者降为查看者，会取消该成员的活动控制台运行：排队和等待确认的运行进入取消状态，执行中运行收到取消请求，由 Worker 停止机制处理。事件连接会重新鉴权并因权限变化关闭，项目界面随后刷新访问能力。已完成的外部操作不能撤回，历史数据和其他项目权限保留。

项目必须保留至少一位有效所有者。转移给已经加入的编辑者时，发起人和接任者都要验证自己的当前密码；接任者须在 24 小时内确认。在移除或交接前，查看个人资源依赖、启用的自动任务、活动运行和待审查凭证数量。仍有个人资源授权时，先准备替代资源、显式授权、更新 Agent 并测试发布，最后撤销旧授权；启用的原所有者自动任务需先停用，再由接任者重新配置。服务端在最终提交时再次核对，条件变化会阻止交接。

交接不复制个人目录、密钥或私有运行，也不改变历史主体。项目 API Key 属于独立服务身份，人员退出不会使其自动失效或取消外部 SDK 运行。所有者需要审查并撤销、轮换离职者曾掌握的凭证。成员邀请、角色调整和交接保留项目级变更记录。

19 / RUN YOUR OWN STUDIO

自部署与运维

分别启动 API 与 Worker，以 PostgreSQL 保存队列、事件和检查点。

开发环境启动

需要 Node.js 22+、pnpm 11、PostgreSQL 16。使用仓库的开发 Compose 可以启动本地数据库：

git clone https://github.com/blublu1101/agent-studio.git
cd agent-studio
pnpm install
cp .env.example .env
# 在 .env 配置初始管理员邮箱和至少 12 位密码
docker compose -f deploy/compose/docker-compose.dev.yml up -d postgres
pnpm db:migrate
pnpm dev

默认 API 为 http://localhost:8788，控制台开发入口为 http://localhost:5173/console/。这是本地开发配置；模型凭证、工具 Provider 和出站允许域名还需要按实际环境准备。

单机部署

仓库提供 API / Worker 共用镜像与 Compose 部署脚本：

./deploy/deploy.sh

首次执行生成 deploy/compose/.env 的随机数据库密码并启动服务。按环境设置公开 HTTPS 地址、初始管理员、模型与 Provider 配置，再重新应用部署。控制台构建后由 API 的 /console/ 提供。

生产应在反向代理后使用 HTTPS，并明确存储卷、数据库、身份文件和模型凭证的持久化位置。镜像与包的发布地址由部署者自己的发行流程决定。

常用配置

完整变量以发行版本的 .env.example 为准。需要自定义工具隔离执行时，准备允许的镜像与专用容器执行环境；默认部署不自动开放宿主 Docker socket。

升级与健康检查

/healthz 检查进程；/readyz 检查所有应用迁移及校验和、检查点迁移、四张表的必需结构和运行权限。Worker 启动复用同一检查，未就绪时退出且不领取任务。升级前备份数据库和持久卷，按需要执行 pnpm db:migrate，再启动匹配的 API 与 Worker。

当前依赖组合为 DeepAgents 1.15.1、LangGraph 1.5.1、checkpoint 1.2.0 和 checkpoint-postgres 1.1.0。由旧检查点组合升级时，排空并停止旧写入后，使用目标镜像的迁移身份执行 pnpm --filter @agent-studio/worker checkpoint:setup（镜像中为 node apps/worker/dist/checkpoint-setup.js）。初始化锁最多等待 30 秒，上游 setup() 新增迁移 v5 和 checkpoint_writes.task_path TEXT NOT NULL DEFAULT ''，重复执行幂等；不要手写重复迁移或授予运行身份 DDL。/readyz 同时核对新列的类型、非空和默认值；只写迁移记录不能通过。新版本已写入状态后不承诺通用降级，旧运行时无法还原 delta-only 消息历史；保留新列与全部迁移，按已验证状态范围决定回退或向前修复。

DeepAgents 跨版本更新先封闭新运行、测试、评测和触发入口，保留现有审批、工具回传、查询与取消，记录并暂停原启用触发器。执行 ./deploy/upgrade-preflight.sh watch --timeout-ms 600000 只读观察全部任务与租约；连续两次空闲才通过，退出码 0/2/1 分别表示通过、未排空或超时、检查错误。它不会封闭入口或修改任务，也不自动加载开发 .env。Worker 收到 SIGTERM 会中止当前执行，应先排空再停止旧进程、协调备份并切换镜像。不能只执行部署脚本就假定旧检查点可恢复或回退。

仅看到进程启动不能代替就绪验证。资源接口异常时，先检查完整迁移与版本匹配，再检查模型、Provider 和网络。保留前向迁移数据，避免用删库来处理升级问题。

导出工作流独立部署

在工作流画布右上角选择「导出部署」，选择已发布版本，再下载 .tar.gz。只有项目所有者可以导出，且须拥有所有引用资源的维护权；仅获使用授权的共享资源不能复制。原环境资源已撤权或 MCP 已停用时，导出会拒绝。旧快照缺少资源归属时，先重新发布。

包内包含冻结的发布定义、DeepAgents 执行代码、API、Worker、独立 PostgreSQL、监测控制台以及零依赖 Node.js SDK 和 TypeScript 类型。它不依赖原 Studio 执行服务。当前草稿和未保存修改不会进入部署包；模型、MCP 和远程 Provider 仍需其上游服务。构建时需要联网下载锁定的依赖与 Docker 基础镜像。

解压到独立目录，准备 Node.js 22+、Docker 与 Compose：

node setup.mjs
# 填写 runtime.env 中的模型/MCP/Jev 密钥。
# 在 .env 中配置 STUDIO_PUBLIC_URL，线上使用 HTTPS。
docker compose up --build -d
docker compose ps
curl --fail http://localhost:8788/readyz
node --env-file=.env example.mjs

setup.mjs 在本机生成新的管理员密码、项目 API Key、专用控制凭据、数据库密码，并保存到权限 0600 的 .env；重复运行不会覆盖。模型和 MCP 密钥在 runtime.env 重新填写，原密钥及其托管引用不会导出。这两个环境文件不会进入镜像。默认仅绑定 127.0.0.1:8788；通过反向代理暴露服务时配置 .env 中的公开地址和 STANDALONE_BIND_HOST。迁移/init 使用独立 DDL 角色，API 与 Worker 使用无 DDL 权限的角色；数据库不暴露宿主端口。

回到当前 Studio 应用 → 项目 → 部署实例，点击「接入部署」，选择来源工作流，填写独立服务根地址和部署目录 .env 中的 STANDALONE_CONTROL_KEY。服务端核对原 Agent、发布版本和冻结快照身份后保存连接。可从工作流画布「更多 → 部署实例」或导出对话框第三步进入。

当前应用 API 需配置 STUDIO_DEPLOYMENT_ALLOWED_HOSTS=workflow.example.com 并重启；多个域名以逗号分隔。仅支持公开 HTTPS 地址、固定控制协议，不跟随重定向，不允许私网地址。本机联调可显式配置 STUDIO_DEPLOYMENT_ALLOWED_HOSTS=127.0.0.1,localhost 和 STUDIO_DEPLOYMENT_ALLOW_LOCAL_DEV=true，此例外只允许回环地址。容器内的 localhost 指当前容器，线上应使用服务公开的 HTTPS 地址。Compose 配置使用相同环境变量。

页面提供实例状态计数、发起调用、结果、运行事件、状态筛选和分页。状态接口每 10 秒刷新，最新一页记录每 5 秒刷新，选中运行每 2 秒刷新至终态。页面调用新建独立会话，使用实例冻结版本；提交失败重试沿用原请求标识。断连会展示错误及上次成功读取时间，过期数据不显示为当前成功状态。页面可读取此实例的正式运行，包含 SDK 和控制台调用；只有自己通过此接入发起的调用可取消或审批，外部 SDK 调用仅供查看。

只有当前项目所有者可以管理、调用和监测连接；专用控制凭据不返回浏览器，不进入浏览器持久存储，当前应用数据库仅存项目隔离的托管密钥引用。独立实例只存凭据哈希。接入凭据失效不会登出当前应用；编辑连接可轮换凭据、修改地址并重新验证版本，移除连接会清理当前应用的凭据，独立服务和数据保留。STANDALONE_API_KEY 继续用于普通 SDK，不能代替控制凭据。独立服务自带 /console/ 可供部署管理员管理账号及撤销凭据，接入后的调用和监测入口位于当前应用。

其他 Node.js 服务可直接导入包内 SDK（API Key 仅放服务端）：

import { WorkflowClient } from "./sdk.mjs";

const workflow = new WorkflowClient({
  baseUrl: process.env.STUDIO_PUBLIC_URL,
  apiKey: process.env.STANDALONE_API_KEY,
  actor: "user-42",
  agentSlug: "your-agent-slug", // 见 workflow.json 的 agent.slug
});
const started = await workflow.start("请介绍你的能力。");
const completed = await workflow.wait(started.id);
console.log(completed.status, completed.result);

get、events、cancel 分别读取状态、按游标读取事件和取消。wait 有超时并接受 AbortSignal，遇到 waiting_client 返回等待状态，调用方通过运行 API 处理审批。调用方需要重放创建请求时，保留 threadId 和原 idempotencyKey。现有平台 SDK 也可连接独立服务，但须使用独立服务创建的 Key 和 Agent 标识。

首版阻止依赖宿主设备的客户端工具与需要容器控制面的自定义工具。远程 Provider 需要信任新部署的 issuer 与 /.well-known/jwks.json；命名模型代理须在 runtime.env 的 STUDIO_MODEL_PROXIES 中配置。包内不复制原会话、历史、附件、项目知识、长期记忆数据或首页环境变量绑定。

这是独立副本：原 Studio 的后续发布和撤权不会同步，接入后的监测按需读取独立实例数据，不复制到原项目的 Run/SDK 调用记录；原应用离线不影响独立 SDK 执行。下载成功不表示服务已经部署。升级时导出新包，部署为新的 Compose 项目及数据库，验证后切换调用地址；保留旧卷以便回滚。初始化拒绝向其他已有项目的数据库导入，也拒绝覆盖不同快照。持久数据迁移需单独安排。

当前应用升级前应用前向迁移 0031_standalone_deployments.sql，它只新增连接表。旧导出包没有专用控制凭据和来源身份时需重新导出部署；不能仅填写普通 SDK Key。回退可保留新增表与托管凭据，停止使用部署实例入口，既有 SDK/Run 协议保持兼容。

可选 DSH 插件执行器

插件默认关闭。启用时增加独立的 apps/plugin-runtime 可信控制器，安装 DSH 代码的临时容器不获得数据库、网络、应用凭据、宿主目录或 Docker socket。生产运行节点需 Node.js 22+、Docker 与已配置的 gVisor runsc；控制器通过 PostgreSQL 队列与 Worker 通信，无新增中间件或内部 HTTP 白名单。

先应用迁移 0042_plugins.sql（随完整迁移流程执行），构建匹配版本 API、Worker、控制台和执行器。构建宿主镜像 docker build -t studio-dsh-host:0.2.1-rc.2-v1 deploy/plugin-host，通过 docker image inspect 获取实际 digest，预装到执行节点。设置执行器的 STUDIO_DATABASE_URL、STUDIO_PLUGINS_ENABLED=true、STUDIO_PLUGIN_RUNTIME_IMAGE（固定 digest）、STUDIO_PLUGIN_ARTIFACT_DIR（私有持久目录）、STUDIO_PLUGIN_CONTAINER_RUNTIME=runsc。可选并发 STUDIO_PLUGIN_RUN_CONCURRENCY=2，范围 1–8。代码仓库提供 deploy/plugin-runtime.service 模板，需按实际节点路径和用户安装。

API 同时设置 STUDIO_PLUGINS_ENABLED=true。默认 Compose 文件只透传开关，不在应用主机自动挂载插件执行器的 Docker socket。控制器单独持有数据库连接；模型和身份密钥不需要提供给它。安装前检查控制器 heartbeat，再以测试包走通安装、调用、项目授权与 Agent 测试。

备份数据库、产物目录和固定镜像；多执行器需要共享或同步产物。旧 Release 只能由相同镜像 digest 的执行器处理，镜像升级时需保留旧执行器，不可替换历史产物。回退先关闭新安装/绑定，逐插件停用并排空在途任务，再停执行器。仅关闭安装开关不等于撤销既有插件权限。

本地可显式使用 STUDIO_PLUGIN_ALLOW_RUNC_DEV=true 配合 runc；这只适用于开发验收，不构成生产 gVisor 隔离验证。插件依赖安装始终禁用 lifecycle 脚本，容器始终无网络。

20 / CONNECT YOUR APPLICATION

SDK 快速开始

用 Python 或 JavaScript / TypeScript SDK 接入已发布 Agent。

安装 Python SDK

Python 3.10+ 可安装已发布的 agent-studio-client：

pip install agent-studio-client
# 或在 uv 项目中
uv add agent-studio-client

当前参考版本为 0.0.2，导入名为 agent_studio，运行时依赖 HTTPX 与 Pydantic v2。SDK 负责接入，Agent 在 Studio 服务端执行。

准备连接信息

发布 Agent，复制短 ID，并创建包含 runs:write 与 runs:read 的项目 API Key。在应用后端配置：

export STUDIO_BASE_URL="https://studio.example.com"
export STUDIO_API_KEY="sk_studio_替换为项目密钥"
export STUDIO_AGENT_ID="替换为已发布Agent的短ID"

actor_ref 取自后端已验证的用户身份。以下 user-42 是示例值。支持 projectlessRuntime 的实例可省略项目；短 ID 需要 agentSlug 能力。

第一次调用

import os
from agent_studio import StudioClient

with StudioClient(
    base_url=os.environ["STUDIO_BASE_URL"],
    api_key=os.environ["STUDIO_API_KEY"],
    actor_ref="user-42",
) as studio:
    run = studio.agent(os.environ["STUDIO_AGENT_ID"]).run(
        "请介绍你可以完成的任务", stream=True,
    )
    final = run.wait()
    print()
    print(final.thread_id, final.status)
    if final.status != "completed":
        print(final.error_code)

import asyncio
import os
from agent_studio import AsyncStudioClient

async def main():
    async with AsyncStudioClient(
        base_url=os.environ["STUDIO_BASE_URL"],
        api_key=os.environ["STUDIO_API_KEY"],
        actor_ref="user-42",
    ) as studio:
        run = await studio.agent(os.environ["STUDIO_AGENT_ID"]).run(
            "请介绍你可以完成的任务", stream=True,
        )
        final = await run.wait()
        print()
        print(final.thread_id, final.status)
        if final.status != "completed":
            print(final.error_code)

asyncio.run(main())

run() 创建运行并返回句柄；wait() 消费事件到终态，再读取最终结果。stream=True 仅让 wait() 实时打印片段，不是请求体字段。它不自动添加换行，也不自动处理审批。

常用配置

传入自定义 HTTPX 客户端时，由你设置其普通请求超时并关闭连接池；事件流仍使用 SDK 的流超时配置。API Key 以 sk_studio_ 开头，actor 为 1–128 位且首位为字母或数字，其余允许 :._- 与字母数字。

SDK 范围与差异

Python 提供同步、异步与高层句柄。独立 JavaScript / TypeScript SDK 提供工作流句柄、Promise / AsyncGenerator 与有限重试，不要求项目 ID；当前平台使用显式 { agentId } / { agentSlug } 寻址。

查看JavaScript / TypeScript 指南、Python API和HTTP 能力协商，不要将两种客户端的示例或发行状态混用。

21 / THREADS, STREAMS, ACTIONS

SDK 会话与事件

管理多轮会话、消费事件、处理审批，并在应用重启后恢复调用。

以下 Python 片段续接快速开始的 studio、agent 或 run。异步网络方法需要 await，事件和文本使用 async for；agent() 与 with_actor() 是同步句柄操作。

多轮对话与结果

agent = studio.agent(agent_ref)
first = agent.run("请记住我的学习方向是 Python")
first.wait()
second = agent.run("给我下一步学习建议", thread_id=first.thread_id)
final = second.wait()
if final.status == "completed":
    print(final.result, final.structured_result)
else:
    print(final.status, final.error_code)

保存 thread_id 续接下一轮。同一 Thread 同时只能有一个未结束 Run；不同业务会话使用独立 Thread。structured_result 与 usage 可以为空，结果与费用缺失不能用默认内容补造。

消费流式文本

run = agent.run("总结用户提供的会议记录")
for chunk in run.text():
    send_to_frontend(chunk)  # 你的应用回调
final = run.refresh()

手动消费后使用 refresh()；再次 wait() 会从默认游标重读事件，可能重复文本。stream=True 适合终端打印，网页转发使用自己的回调或 SSE 响应。

事件与游标恢复

for event in studio.stream_events(saved_run_id, after=saved_seq):
    if event.type == "message.delta":
        send_to_frontend(event.payload.get("text", ""))
    process_event(event)
    persist_cursor(event.seq)  # 业务处理成功后保存

SDK 自动重连并过滤重复事件；发现序号缺口抛出 StudioStreamGapError。跨进程可靠消费仍需业务处理幂等，不能以单连接去重替代事务。未知事件应忽略或透传。

审批与客户端工具

for event in run.events():
    if event.type != "run.waiting_client":
        continue
    for action in run.pending():
        if action.kind == "approval":
            decision, edited_args = ask_real_user(action)
            run.decide(action, decision, args=edited_args)
final = run.refresh()

ask_real_user 是你实现的界面逻辑，必须遵循 allowed_decisions；只有 edit 才能且必须传替换参数。

客户端工具先声明 ClientCapabilities(device_id=..., tools=["tool_id@1"])，用原始 action 回传结果。批准执行时 result 必须是字典；拒绝时 approved=False。需要本地副作用时，设备自行做授权与幂等记录。

幂等、重试与取消

created = studio.create_run(
    saved_thread_id,
    saved_input,
    idempotency_key="queue-message-000042",
)

跨重启保存 Thread、请求内容和幂等键。键需为 8–128 位字母数字或 ._:-；相同键与不同内容产生冲突。创建 Run 的内部重试复用键，但创建 Thread 不带幂等键，重试可能多建空会话。

Python 对网络及契约定义的可重试错误有限重试，遵守有界 Retry-After。调用 run.cancel() 明确取消服务端运行；取消本地 Python 任务不会自动取消它。

多用户后端与代理

user_client = studio.with_actor(authenticated_user_id)

共享连接池，由原始客户端统一关闭。actor 取自后端认证，不信任前端任意值。需要代理、CA 或绕开本地环境代理（trust_env=False）时，传入自定义 httpx.Client / httpx.AsyncClient；本地服务可设置 NO_PROXY=localhost,127.0.0.1,::1。

完整业务示例见 Python SDK 示例目录。FastAPI 示例的认证逻辑是演示骨架，接入生产前替换为真实认证。

22 / THE NODE.JS SDK

JavaScript / TypeScript SDK

在 Node.js 服务端调用 Agent、消费事件流，并处理会话与人工审批。

安装独立 SDK

JavaScript / TypeScript SDK 使用 npm 包 agent-studio-client@0.0.2，要求 Node.js 22+，支持 ESM、CommonJS 和 TypeScript 类型声明，不依赖平台工作区或 Python。

npm install agent-studio-client@0.0.2

SDK 源码与后续发布目标已迁到 @yxtec/agent-studio-client。截至 2026-10-14，公共 npm 查询 scoped 包返回 404；旧无 scope 包 agent-studio-client@0.0.2 仍可获取，因此本章可直接安装的示例使用旧包名。Python 包仍为 agent-studio-client。平台内的 @agent-studio/client 是内部 workspace 客户端。

使用当前 scoped 源码时，先由 SDK 维护者提供构建包，再在应用安装：

npm install ./yxtec-agent-studio-client-0.0.2.tgz

对应导入为 import { StudioClient } from "@yxtec/agent-studio-client"；CommonJS 使用 require("@yxtec/agent-studio-client")。scoped 包发布到公共 npm 后可使用 npm install @yxtec/agent-studio-client，应先确认目标版本可获取。两种分发采用相同调用接口，安装与导入名必须配套。

配置与首次调用

先发布 Agent，再创建含 runs:read、runs:write 权限的项目 API Key。Key 决定项目，不需要传 projectId。从 Agent 编辑页面地址获取 UUID，并设置以下服务端环境变量；API 地址不包含 /console 或 /v1。

STUDIO_BASE_URL="https://studio.example.com"
STUDIO_API_KEY="<API_KEY>"
STUDIO_AGENT_ID="<AGENT_UUID>"

将以下代码保存为 quickstart.mjs，配置环境变量后用 node quickstart.mjs 执行。生产环境应校验配置，并从后端认证结果获取 actorRef。

import { StudioClient } from "agent-studio-client";

const studio = new StudioClient({
  baseUrl: process.env.STUDIO_BASE_URL,
  apiKey: process.env.STUDIO_API_KEY,
  actorRef: "user-42",
});

try {
  const agent = studio.workflow({ agentId: process.env.STUDIO_AGENT_ID });
  const run = await agent.run("总结提供的笔记");
  for await (const text of run.text()) process.stdout.write(text);
  const final = await run.wait();
  console.log(final.threadId, final.status, final.result, final.structuredResult);
} finally {
  studio.close();
}

TypeScript 使用相同接口，需先校验环境变量为字符串；CommonJS 使用 const { StudioClient } = require("agent-studio-client")，调用仍是异步的。wait() 返回失败或取消状态时不会自动抛出业务错误，应检查 status 和 errorCode。

服务端协议与寻址

SDK 使用 /v1/threads、/v1/runs 等免项目路径，不会在请求失败后自动切换寻址方式。当前平台 CreateThreadRequest 接受 agentId / agentSlug，尚不接受 workflowId。SDK 的字符串工作流寻址已由夹具覆盖，但不能据此推断当前平台或生产部署支持。每次运行使用服务端生产版本，独立 SDK 当前不提供版本固定。

会话、幂等与版本记录

const agent = studio.workflow({ agentSlug: "assistant" });
const first = await agent.run("我叫小王");
await first.wait();
const second = await agent.run("我叫什么？", { threadId: first.threadId });
console.log((await second.wait()).result);

同一 Thread 同时只能有一个未结束的 Run。createRun() 自动生成幂等键并在重试中复用；跨进程恢复需同时保存 threadId 和幂等键，然后调用 studio.createRun(threadId, input, { idempotencyKey })。未传 threadId 的两次高层调用会创建不同会话，不能只靠同一幂等键恢复。

clientVersion 可指定接入应用版本，通过 X-Studio-Client-Version 上报；SDK 版本通过 Studio-Sdk 单独上报。项目所有者可在“SDK 调用记录”查看外部调用。

事件、取消与人工处理

run.events() 产出完整事件，run.text() 产出文本增量；同一 RunHandle 保留已交付游标，消费结束后可用 wait() 读取最终状态。studio.streamEvents(runId, { after: savedSeq }) 支持跨进程续传，序号缺口抛出 StudioStreamGapError，事件 Schema 主版本不兼容抛出 StudioCompatibilityError。未知事件与新增响应字段保留。

AbortSignal 与 studio.close() 只关闭本地连接；服务端取消需显式 run.cancel() 或 studio.cancelRun(runId)。本地中止抛出 AbortError。

run.pending() 查询人工处理请求；应用根据真实用户操作调用 run.decide(action, "approve" | "edit" | "reject")。客户端工具由接入方执行并通过 submitClientToolResult() 回传，SDK 不自动审批或执行工具。wait() 在等待人工处理时可能持续阻塞到请求处理或过期。

低层接口与边界

普通请求对网络错误、超时、429、5xx 有限重试，遵守 Retry-After；400/401/403/404/409/410 不重试。创建 Thread 与删除 actor 数据不自动重试。默认单请求超时 30 秒、最多 3 次重试；SSE 心跳超时 45 秒、最多 5 次失败重连，均可配置。

独立 SDK 不包含文件上传、虚拟文件管理、评测或触发器接口，也不包含 agentVersion 参数。attachments 仅引用已有文件 ID。其他平台操作请使用对应 HTTP 契约。API Key 始终保存在后端，前端通过自己的服务接入。

23 / AGENTS AS MCP TOOLS

以 MCP 工具接入

把已发布 Agent 配置到 Claude Code、Cursor 等 MCP 客户端中直接调用。

适用场景

已发布的 Agent 可以作为 MCP 工具，直接配置到 Claude Code、Cursor 等支持 Streamable HTTP 的 MCP 客户端中，无需编写桥接服务。每次工具调用都会创建一个普通 Run，与 SDK 调用共用授权、版本快照、预算和审计规则。

需要处理客户端设备工具、人工审批或细粒度事件流时，继续使用 SDK 或 HTTP API。

开启端点

1. 部署方设置 STUDIO_MCP_ENABLED=true 并重启 API。未开启时端点返回 404 mcp_endpoint_disabled，项目能力清单中的 mcp_server 为 unconfigured。
2. 项目所有者在 Agent 编辑器顶部打开“MCP 端点”，开启“对 MCP 客户端公开”，并填写工具描述后保存。客户端模型根据描述判断何时调用，应写明用途、输入要求和返回内容。
3. 发布该 Agent。只有“已公开 + 已发布 + 未归档”的 Agent 会出现在工具列表中，客户端始终调用生产版本。

连接客户端

端点地址为 {STUDIO_PUBLIC_URL}/v1/projects/{projectId}/mcp，同一项目内所有已公开的 Agent 共用这个地址。请求必须携带项目 API Key 与调用方标识：

• Authorization: Bearer <API Key>，Key 需要 runs:read 与 runs:write；
• X-Studio-Actor，标识最终用户或调用方，Thread 按该标识隔离。

Claude Code：

claude mcp add --transport http agent-studio https://studio.example.com/v1/projects/<projectId>/mcp \
  --header "Authorization: Bearer $AGENT_STUDIO_API_KEY" \
  --header "X-Studio-Actor: user:<your-id>"

支持 JSON 配置的客户端：

{
  "mcpServers": {
    "agent-studio": {
      "type": "http",
      "url": "https://studio.example.com/v1/projects/<projectId>/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>",
        "X-Studio-Actor": "user:<your-id>"
      }
    }
  }
}

不要把 API Key 写进提交到代码仓库的配置文件；按客户端支持的方式从环境变量或本机密钥存储读取。

工具约定

• 工具名为 Agent 的 slug，标题为 Agent 名称，描述为公开时填写的工具描述。
• 输入参数：input（必填，1–20000 字符）与 threadId（可选）。省略 threadId 时新建会话；传入此前返回的 threadId 可在同一会话中继续，只能延续当前调用方、同一 Agent 的会话。
• Agent 配置了对象类型的结果规范时，工具声明 outputSchema，成功结果附带 structuredContent。

成功结果的第一段文本为 Agent 的最终回复，第二段为 [agent-studio] threadId=… runId=…，同样的 ID 也放在 _meta 的 agent-studio/threadId 与 agent-studio/runId 中。

结果与错误

执行类问题以 isError: true 的工具结果返回，便于客户端模型读到原因；文本末尾括号内为错误码。

协议与鉴权问题返回 HTTP 错误或 JSON-RPC 错误：缺少或无效凭证为 401，scope 不足为 403，请求带 Origin 且与 STUDIO_PUBLIC_URL 不同源为 403 origin_forbidden，不支持的 MCP-Protocol-Version 为 400，未知工具或参数结构错误为 JSON-RPC -32602。

行为与限制

• 端点为无状态的 Streamable HTTP，支持协议版本 2025-06-18 与 2025-03-26，提供 initialize、ping、tools/list 和 tools/call。不签发会话 ID，不支持批量消息、服务端主动请求、resources 或 prompts；GET 与 DELETE 返回 405。
• 请求头 Accept 包含 text/event-stream 时，tools/call 以 SSE 返回：等待期间每 15 秒发送心跳，请求带 _meta.progressToken 时附带 notifications/progress，最后发送结果并关闭。
• 客户端断开或超时只停止等待，不取消 Run。
• MCP 客户端不提供幂等键，客户端重试会创建新的 Run。有副作用的 Agent 应在工具描述中提示调用方避免重复调用。
• MCP 调用与外部 SDK 调用一起出现在控制台的“SDK 调用记录”中，并标注为 MCP 客户端。

24 / WHAT TO EXPECT

常见问题与能力边界

了解当前边界，避免把框架能力、平台能力和部署条件混为一谈。

常见问题

版本与支持

本版对应 DeepAgents 1.15.1、API 1.1.0 / 事件 Schema 1.0 与 Python SDK 0.0.2。Python SDK 在 PyPI 提供；JavaScript / TypeScript SDK 在 npm 提供 agent-studio-client@0.0.2，要求 Node.js 22+。

生产模型效果、上游账单、远程服务可用性及实际设备操作，仍由部署与接入环境联调。平台自动化或本地测试不能替代这些验证。

25 / BUILD & CONTRIBUTE

开发与文档贡献

理解契约、执行与验证的边界，维护与当前实现一致的文档。

本地开发与检查

pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm contracts:check
pnpm build

跨服务 Schema 以 packages/contracts 为唯一来源，服务端再次校验。数据库与多 Worker 集成测试需要测试数据库；模型与容器执行还需要各自环境。分别记录实际运行与跳过范围。

代码职责

维护对外文档

中文和英文正文分别维护，章节 ID 和能力范围保持一致。文案应面向使用者，说明操作、实际行为、结果与限制；不将内部验收记录、私有环境或待确认部署选择直接写入发布页面。

uv run --no-project --with 'Markdown>=3.7,<4' --with 'Pygments>=2.18,<3' python scripts/build-public-docs.py
uv run --no-project --with 'Markdown>=3.7,<4' --with 'Pygments>=2.18,<3' python scripts/build-public-docs.py --check

发布输出为 docs/site/，包含文档、API、更新日志三个页面，中文与英文 /en/ 各一套，并内嵌搜索、样式和交互。此目录可独立托管；文档源文件与内部设计文档保留在仓库，不属于站点输出。

提交问题

问题描述包括平台 / SDK 版本、同步或异步方式、最小复现输入、脱敏的错误 code 与验证环境。不要提供密钥或完整敏感内容。

参考上游 DeepAgents 文档理解框架，参考本平台指南理解开放范围。两者发生版本差异时，以发行版本与实例能力为准。