AgentKit Studio
入门

第一次对话

一次运行里界面上具体会出现什么——工具调用卡片、审批请求、文件改动、用量与耗时,以及失败轮次和刷新后的历史。

这一页只讲一件事:你按下发送之后,界面上到底发生了什么。

前置条件

已经装好并能打开 Studio,并且在 设置 → 模型与凭证 里配置了至少一个模型。没配好时,总览顶部会显示「先配置一个模型凭证,即可开始对话」。

发送第一条消息

选中一个 Agent

从 智能体 面板的「本地」标签里选一个。还没创建过的话,用总览的 手动配置 或 从模板开始。

没绑定 Agent 会直接报错

在会话里发消息时如果没绑定 Agent,会拿到 STUDIO_AGENT_REQUIRED(「请先绑定 Agent,再发送消息」,src/providers/dsh-runtime.mjs:604)。

输入并发送

输入一句话,按发送。空输入会被拦下并提示 STUDIO_INPUT_REQUIRED(「请输入文字或添加图片后发送」,src/providers/dsh-runtime.mjs:605)。

看着它跑

接下来的内容全部由 DSH 原生会话事件驱动。Studio 不另存一份会话——它只是把 DSH 的事件投影成界面(src/dsh-history-display.mjs:1)。

一次运行的时序

DSH 会发出一组固定的事件类型(src/host/dsh-session-contract.mjs:2-19,共 16 种)。界面上你实际能看到的是这几种:

事件你看到什么
turn/start新一轮开始,过程区出现
user/message你的输入落到对话里
tool/call出现一张工具调用卡片(默认折叠)
tool/result卡片摘要不再显示「正在执行」,可以展开看结果
approval/asked弹出审批请求,等你点允许或拒绝
approval/decided审批结果写回,卡片继续
assistant/message最终回答
turn/end本轮结束

公开序号 = 原生序号 + 1

Studio 投影历史时把 DSH 原生序号整体加一,0 保留为空历史的哨兵值(src/frozen-session-history.mjs:2-3)。所以你看到的序号从 1 开始,这是刻意的。

工具调用卡片

每张卡片是一个 <details>(src/client/dsh/native-tool-view.mjs:33-40):

区域内容
摘要行中文工具名 · 关键参数(path / query / name / directory 之一,截断到 180 字符)· 失败时追加「· 未完成」
展开后「调用参数」原始 JSON + 「执行结果」文本(最高 360px,超出可滚动)
无输出时结果区显示「无文本结果」
还没结束时结果区显示「正在执行」

工具名有固定的中文标题映射,例如 read_workspace_file → 读取文件、write_workspace_file → 写入文件、apply_workspace_patch → 应用文件补丁、rewind_workspace_files → 恢复文件(完整 16 项见 native-tool-view.mjs:1-10)。

工具没成功时

错误码会被翻译成一句可读的话,同时用 role="alert" 呈现(native-tool-view.mjs:11-17,37):

工具返回的错误码界面文案
permission_denied未获准执行此操作,请检查 Agent 规则和会话权限。
invalid_path路径超出可访问范围或不可用,请选择工作区内的文件。
tool_not_found当前 Agent 未绑定此工具。
deferred_tool_not_loaded_or_not_deferred该工具尚未加载或未绑定。请使用已绑定的工具;需要更多能力时编辑 Agent 配置。
artifact_not_available当前任务没有此工件的读取授权,请通过产生结果的原工具继续读取。
其它工具未成功执行,请展开查看原始结果。

审批请求

当 Agent 要执行需要授权的操作,会弹出原生审批(src/client/dsh/native-approval.mjs):

元素说明
标题「原生待审批:[工具名]」
授权范围「请求一次性授权」——只对这一次生效
确认勾选「我已核对这次操作及其影响」
按钮「确认允许一次」/「拒绝」/「返回」

审批失败不会静默

读取失败会提示「原生审批状态读取失败,请刷新。」;请求已过期会提示「审批请求已失效,请刷新后核对。」;决定没送达会提示「审批决定未送达,请刷新核对原生运行状态。」

文件改动

Agent 改文件走的是工作区工具:write_workspace_file、edit_workspace_file、apply_workspace_patch、delete_workspace_file 等。它们和别的工具一样以卡片形式出现,展开能看到参数与结果。

一轮结束时,只要有文件改动就会在对话末尾出现变更卡片:单个文件显示为一行卡片,多个文件显示为可折叠的列表(默认展开前 4 行),右侧标注新增/删除行数。点卡片标题会在右侧边栏打开该轮的 review,逐文件查看 diff;鼠标悬停 500 ms 也会预览第一处差异。

卡片与工具结果的分工

变更卡片只回答「这一轮改了什么」,不替代工具卡片。要追某个改动是怎么发生的(谁调的、参数是什么、失败重试了几次),展开对应的工具卡片。

用量与耗时

单轮对话里不显示 token 明细。要按运行看统计,去 运行中心 → 观测:

指标位置
平均耗时观测总览卡「平均耗时」,单位毫秒(src/client/pages/observability.mjs:108)
Token 用量观测总览卡「Token 用量」,输入与输出合计(observability.mjs:109)
每次运行的耗时 / TokensTrace 列表的「耗时」「Tokens」两列(observability.mjs:167,168)

字符数不是 Token 数

观测页明确写着:字符数反映请求体大小,不等于 Token 用量;这里只保存统计,不保存原始请求体。

失败轮次

一轮失败时,运行时会给出一个稳定的失败摘要:

DSH_TURN_FAILED
运行时本次任务未完成,请重试;若仍失败,请检查模型和工具连接。

(src/dsh-history-display.mjs:6)

失败的轮次不会从历史里消失,也不会被重写成成功。重新发起时是一轮新的、带新序号的运行。按错误码定位见排障。

刷新后历史还在吗

在。历史由 DSH 宿主持久化,Studio 每次只做有界的只读投影(src/frozen-session-history.mjs:1-3),从不写第二份存储。

投影会做几件事:

行为说明
白名单事件只投影 turn/*、user/message、assistant/message、tool/call、tool/result 等公开事件
按轮分组以 turn/start 和 turn/end 为一组,空轮次不返回
脱敏私钥、Bearer/Basic 令牌、sk-*、AKIA*、Cookie、各类 *_key/token/password 字段一律替换成 [已隐藏凭据](src/dsh-history-display.mjs:10-21)
附件只展示 ID、大小、文件名与尺寸,不自动访问附件内容

对话回退

跑歪了可以回退。会话里的「对话回退」折叠区(src/client/dsh/native-conversation.mjs):

  1. 展开后读取可回退的用户输入列表。
  2. 选一条,点「回退到这条输入之前」——后续对话移出当前分支,工作区文件保留。
  3. 想连文件一起回退,点「预览同时回退文件」,会列出「删除:」和「恢复:」的文件清单。
  4. 确认「确认回退对话和文件」。

有任务在跑时会先提示「回退将先停止需要移除的任务」;存在不安全文件时以 role="alert" 单独列出,不会静默跳过。

下一步

跑通一次之后,去核心概念理解为什么改配置不影响正在跑的会话;要绑定企业资源,看资源与绑定。

本页导航