dsh-agent-studio

深浅色

功能详解 ​

面板分左右两栏：左边是 Agent 池与三个集库（提示词集 / 工具集 / 技能集），右边是选中对象的详情；顶栏管平台预设（切换、新建、删除）、主代理绑定与导入导出，底栏是注册到主页面与突破 PTC 120 秒限制两个开关，以及保存。

提示词集 ​

  • 段清单：一个提示词集就是一份有序的段清单，顺序可调。
  • 两种段：
    • 平台预设：引用平台自己注册的段（如 persona、工具说明），正文跟着平台升级走，面板里只读；
    • 自定义：自己写正文，支持平台注册的 {{变量}} 插值。写了平台没注册的变量名，这次请求会直接失败，所以保存时写入端点会把这种变量名拦下来。
  • 白名单语义：清单就是这一轮投递的全部内容，没列进来的平台段不会进上下文。
  • PTC 专属标记：tools:ptc-only 与 tools:sdk 是每个提示词集的常驻段——不能取消勾选、也不能移除（顺序可调），标出来避免配错。
  • 预设钉死时的提示：少数平台预设声明了 complete: true（段清单由平台写死），这类预设的提示词集卡片会置灰并写明原因。这不是坏了，是平台的规定。

工具集 ​

  • 收窄语义：勾选你要留下的工具，其余收起来。清单里既有插件工具也有 MCP 工具。
  • 按来源分组：候选按来源分组显示，可折叠，也可以整组勾选。
  • 候选直读：打开面板就直接读该预设此刻的工具面（GET /api/dsh-agent-studio/tools?preset=），不必先对话；读不到时（工具服务缺席、预设破损）退回该预设在磁盘上的观察缓存。
  • 必备项 skill：每个工具集常驻 skill 一项，勾选锁死、顺序可调。没有它，AI 无法自主调用技能目录。
  • 工具集是唯一真相：不在装载的工具集里的工具，模型既看不到声明也调不动——官方 subagent 这类也在同一条规则里。

技能集 ​

  • 可见性收窄：勾哪些 skill 就暴露哪些；没勾的对模型隐藏，你仍能在输入框手动调用。
  • 候选直读：打开面板就直接问官方技能服务拿候选，不必先发一条消息触发装配。候选来自两条路的并集：
    • 活 agent 视角：每个正在跑的 agent 用它自己的 scoped 技能服务 + 它会话的工作目录读——按 agent 注册的技能、项目级技能目录由此读到；
    • 预设视角：平台全部预设逐个解析 scope 后读（没有会话时走这条）。 两条路都读不到时回落磁盘缓存。
  • 按来源分组：候选的来源就是扫描根，组头显示来源标识：<项目>/.dsh/skills、<项目>/.agents/skills、自定义技能目录、~/.dsh/skills、~/.agents/skills、内置技能、CC Switch。
  • 同名优先级：跨来源同名 skill 的优先级直接写在条目下方（数字小的赢，被遮蔽的候选平台不报，这里也看不到）。

Agent 身份与备注 ​

每个代理有一栏备注（可空）。备注不只是给自己看的：代理被当子代理时，模型先调 studio_list_subagents 拿名册，每一行就是「id — 名称：备注（模型 … · 后台 …）」，派活给谁全靠它。所以写清「这个代理是干什么的」。

子代理名册 ​

每个代理可以挂一份子代理名册，为其中每个子代理单独配置：

  • 模型与思考强度：走子代理的启动参数；
  • 工具面：在创建窗口收窄；
  • 提示词与技能面：装配期生效；
  • 后台模式：不阻塞 / 阻塞两档。老配置里的第三档「AI 决定」（model-decides）读出来一律当「不阻塞」，界面不再提供这一档；
  • PTC 选择：子代理走原生还是 PTC，由它自己那档 Agent 模式定，不跟随主代理。

派活走插件自带的 studio_delegate（按代理 id 派），身份由此确定。官方 subagent 工具派出的子代理没有角色登记，只能按「绑定给该预设的主代理」那套面走，拿不到这里配的独立设置。

阻塞批（整批里至少一项是「阻塞」档）的结果会整批写进系统临时目录下的一个 .md，同时把全文内联在返回里——首行报行数与字符数及文件路径，末行写「全文完」。文件里是成功项的正文，按原序号分节；写盘失败时首行改报原因，正文照旧全文。这些文件插件不主动清理。

Agent 模式与快照开关 ​

  • Agent 模式三档：跟随预设 / 原生 / 强制 PTC。
  • 运行时快照：官方按 step 动态注入的环境快照（沙箱与审批状态、工具失败统计等），代理级开关可关——关掉的是其中「可选」的部分；平台标为必需的项（如当前工作目录）仍会照投。声明了 includeRuntimeContext: false 的预设，开关会置灰并给出说明。
  • 突破 PTC 120 秒限制（保存行上「注册到主页面」右边，默认开）：把 PTC 模式 run_code 程序的预算从默认 120 秒抬到平台计时器上限（约 24.8 天）；点一下即时落盘、不进草稿。三点要记住：① 只对 PTC 模式生效，而且是进程级全局——主代理、子代理、所有程序一起放开；② 等后台 job、等嵌套工具的时间也算在这份预算里；③ 打开后写坏的死循环几乎不会自己停，只能手动中断。默认开是因为「阻塞」档的派活经常要等超过 120 秒。

模型自动降级 ​

给代理配一条备用候选链之后，主选失败会按链依次顶上。不配备用候选 = 完全不接管，重试行为与平台默认一致。

怎么配（「模型与后台」卡里）：

  • 重试次数：每个候选各自的上限，默认 5（与平台默认对齐）。
  • 主模型：供应商 / 模型 / 思考强度三级联动。设为主代理时以对话界面选择的为准——这里是后备形态，对话里选的模型接连失败后才轮到它。
  • 备用模型：一列候选，可添加、调序（↑↓）、移除；顺序就是降级顺序。

失败怎么走：

错误行为
可重试（空响应 / 限流 / 服务端错误 / 超时 / 传输错误）在当前候选上重试到上限，才换下一个
不可重试（额度耗尽 / 凭据失效……）不重试，直接换下一个
全链走完这次请求彻底失败（与平台一致）

链的排布：子代理 = 启动时给的路由（没配模型就是继承）→ 备用候选；主代理 = 对话界面选的模型 → 主模型配置 → 备用候选。

会话里的表现：重试写进会话（聊天界面的「正在重试模型请求（N/M）」就是它），换候选会给模型留一条通知。换候选后当次会话不自动切回；你在对话界面手动换模型，插件让位。

预设管理 ​

  • 顶栏是预设的切换处：一排预设 tab，右侧是「新建预设」「删除预设」，下面一行是「这个预设绑定的主代理」下拉。
  • 新建：把选中的来源预设的构成声明（提示词组合、技能、资源）原样搬运成一份新预设注册上去——源预设不动，调用方给不了构成文本。显示名与描述可选，填了就用你的、留空继承来源预设。
  • 删除：弹窗确认后删除；随部署提供的预设删除按钮置灰。插件侧的引用（绑定、子代理名册）会跟着清掉，不留悬空配置。
  • 绑定与解绑：绑定在顶栏的下拉里选（解绑 = 选「未绑定」），解绑即恢复原样。

可改的 id 与引用同步 ​

集与代理的 id 都能改。改之前面板会列出所有引用者，改的时候把全部引用一并同步，绝不留悬空引用。

导入导出与保存 ​

  • 顶栏：导入 / 导出都开同一棵勾选树——导出在树里挑池与项（导出的是草稿，含未保存的改动），导入先选文件、再在树里勾要并进草稿的项。
  • 底栏：注册到主页面与突破 PTC 120 秒限制两个开关、保存态与保存改动。
  • 导出只含四个池：文件里是 version / exportedAt / agents / promptSets / toolSets / skillSets，只装勾中的项；预设绑定与各开关不进文件。
  • 撞 id 的规矩在树弹窗里（那个**「是否覆盖」**开关）：
    • 关（默认）：文件里的项与现有项撞 id 就整批拒绝，并报出撞在哪一对上——与老版本行为一致；
    • 开：撞 id 的项就地覆盖（保持原来的位置），其余照常并入。
  • 导入的永远是 JSON（导出文件即 agent-studio-config.json）；老版本导出的池级文件（items 带池名）仍能导入。
  • 导入只并入草稿，只有点了保存才落盘。保存之后，新开一个对话即生效。