dsh-my-agent-preset

给 DSH 的 Agent 做「预设」：把人设、提示词、技能、工具、运行时上下文打包成一套可复用的能力组合。一个任务，只装它需要的东西。

DSH（DeepSeek Harness）原生的 Agent 是「全量装备」：所有工具、所有技能、全部运行时上下文，一股脑进每一轮请求。这个插件让你为不同任务定义不同的 Agent 形态——写文档的只拿写作工具和写作技能，做 PPT 的只拿幻灯片工具，做审查的只有只读权限。模型看到的世界变小了，反而更容易把事做对。

安装后，在 设置 → 自定义预设模式 中管理预设；新建会话时选择预设即可生效。

---

目录

• 它解决什么问题
• 一个预设由什么组成
• 功能
• 优点
• 快速开始
• 与 dsh-session-bridge 组合：把大任务拆给不同预设
• 安装
• 数据与兼容
• 已知限制
• 致谢
• 开发与测试

---

它解决什么问题

默认的「通用 Agent」在简单任务上并不经济，也不安全：

问题	表现
上下文被无关能力挤占	每个工具的 schema、每个技能的描述、每段运行时上下文都会随请求重复发送。真正用于任务的窗口被大量「可能用得上」的能力吃掉。
工具滥用	模型同时看到几十上百个工具，简单任务也会反复试探、绕路，甚至调用破坏性工具。
越权风险	只要能写文件、能执行命令、能联网，就有在你没授权的范围动手的可能。
人设稀释	一个通用助手很难同时是严格的审稿人、克制的文档写手和激进的调试工程师。
不可复用	每次换任务都靠临时写一段提示词，配置散落、无法审计、无法分享。

预设的本质是能力的最小可行集：只给这个任务需要的工具、技能、上下文，以及一段只属于这个任务的人设。

一个预设由什么组成

组成	作用	本插件怎么管
人设 / 提示词	定义它是谁、做什么、不做什么	三种注入方式：追加、完全替换、只屏蔽官方；可自动附带当前工作区
技能	按需加载的专业能力	白名单，按来源分组勾选；未勾选的技能退出模型上下文，调用也会被拒
工具	它实际能执行的动作	全部 / 仅白名单 / 排除名单；隐藏、拒绝调用、从提示词剔除三层生效
运行时上下文	工作区、沙箱策略、审批策略等每轮环境信息	逐项白名单；必需项默认保留，可高级强制屏蔽
元信息	名称、描述、启用状态、顺序、稳定 id	卡片网格管理，可复制、可导出、可停用

功能

预设管理

• 卡片网格：显示名称、描述、启用/异常状态、是否有提示词、技能数量、工具模式与稳定 id（custom-xxxxxxxx）。
• 新增 / 编辑 / 删除 / 启停：删除为两段式内联确认；停用后立即从注册表移除，新建会话不再可选，配置本身保留。
• 复制预设：一键生成完全副本——提示词、注入方式、附带工作区、运行时上下文勾选、技能、工具名单原样带过；id 全新生成，名字自动编号（原名（复制 1）），副本紧跟在源预设之后，启用状态跟随源。
• 导出预设列表：把 id / name / description 复制为 JSON，便于在别处引用、对照或分享名称清单。提示词、技能、工具不会外泄。
• 顺序稳定：卡片的 order 与「新建会话」时的预设列表顺序一致。

人设：三种注入方式

方式	行为	适合
追加	用你的文字替换人设前缀，保留 DSH 的其它系统提示词（含工具指导）	大多数场景：定制角色，但继续享受官方工具指导
完全替换	只用你的文字，移除所有其它提示词	彻底重定义 Agent：自定义工作流、自定义输出协议。注意官方工具指导也会消失，需要你在提示词里写清工具用法
只屏蔽官方	用你的文字作为人设，只移除 DSH 官方系统提示词，保留第三方插件与外部 MCP 注入的提示词	想要完全自定义的角色，但仍需要 MCP / 第三方工具说明

「只屏蔽官方」下还可以配置三栏官方段规则（命名空间前缀、精确段名、保留例外），应对 DSH 升级新增的官方段。

附带工作区（默认开启）：在提示词末尾追加 当前任务工作区：<会话 cwd>，每次组装实时读取。模型不会因为换了会话而猜错路径。

技能：按来源选择，勾选即注入

• 技能目录来自 DSH 的 skills.list()，按来源分组（如 agent-trae、agent-opencode、agent-agents），每个来源一个折叠菜单，菜单头显示「已选 / 总数」，支持「全选此来源 / 清空此来源」。
• 白名单语义：勾上 = 注入并允许调用；没勾 = 不注入，且在该预设内调用会被拒绝。
• 空白名单 = 没有任何技能，不是「全部技能」。
• 勾选技能后会自动保留 skill 工具，技能与工具名单相互独立。
• 未勾选的技能会做目录级裁剪：覆盖为不可被模型调用，从模型上下文中退出——这是省 token 的关键一环。

工具：三种名单，三层生效

工具范围有三种模式：

模式	含义
全部	继承该预设可用的全部工具（默认）
仅白名单	只允许勾选的工具
排除名单	允许全部，但排除勾选的工具

名单在三个层面同时生效：

1. 可见性：tools.restrict({ allow }) / ({ deny }) 过滤可隐藏的全局工具。
2. 调用级：tools.guard() 拒绝名单外工具的调用，覆盖该预设继承的内置工具与 per-Agent 工具（如 subagent）。
3. 提示词卫生：system-prompt/assemble 过滤把注定被拒的工具 schema 与其 tool: guidance 段从组装结果中剔除。模型看到的工具清单里不会出现「调了也会被拒」的工具。

工具分三类，名单的效力不同：

类别	例子	能否隐藏	能否拒绝调用
全局工具	config_backup、tool_list、session_search	✅	✅
继承的内置工具	read、bash、skill、glob	❌（同层注册）	✅
per-Agent 工具	subagent、list_subagent_models	❌（每个 Agent 自己注册）	✅

设置页的候选清单是完整继承面并标注来源，不会漏掉只有活着的 Agent 才能暴露的 per-Agent 工具。

运行时上下文：逐项白名单

模型每轮看到的 Current runtime context… 那段不是提示词，而是独立的 assembly.contexts。本插件把它做成逐项勾选：

• 勾上 = 注入，未勾 = 屏蔽；支持全选、取消全选与计数。
• 字段缺失（旧预设）= 不管理，原样全量注入，升级瞬间行为不变。
• 数组为空 = 只剩必需项注入。
• working-directory:current、team:identity 这类官方必需项默认强制注入，主复选框只读；需要时打开高级 · 强制屏蔽（默认关闭）才会真正关闭。该功能依赖实现细节，DSH 升级后可能失效，且屏蔽「当前工作区」会让模型失去位置感——页面会就地警告。

运行时自检

编辑器最后一组是运行时自检面板，直接回答「这个预设现在到底有什么」：

• 继承工具面有多少个、可用工具多少个、被名单拒绝多少个；
• 哪些名字写进了名单但不在继承面内（多半是拼写错误或对应插件没装）；
• 缺失的技能、技能工具是否启用；
• 快照保留 / 屏蔽的计数与两个名单。

排错时先看这里，比猜快。

其他

• 原子写入：临时文件 + rename，避免写一半损坏配置。

优点

优点	为什么成立
节省上下文 token	工具 schema、技能描述、运行时上下文都会随请求重复发送。预设把工具面收窄、把未选技能裁出模型上下文、把不需要的上下文项过滤掉，重复开销随之变小。窗口留给任务本身。
模型不滥用工具	名单外的工具要么看不见，要么调了被拒，连提示词里的 guidance 段也被剔除。模型没有「顺手试一下」的选项，路径更短、更直接。
降低越权风险	没给写文件工具就改不了文件，没给 bash 就执行不了命令；两者都不给，就没有本地执行面。这是能力层的最小权限，与 DSH 的沙箱、审批策略叠加使用。
专事专办，完成得更好	单一角色 + 单一技能集 + 窄工具面，减少角色冲突和工具诱导；提示词、技能、工具都为同一类任务服务，输出更稳定。
彻底重新定义人设	「完全替换」会移除所有其它提示词，「只屏蔽官方」保留第三方/MCP 说明；配合附带工作区，可以构造一个与官方助手完全不同的角色。
可复用、可审计	预设是数据文件里的显式配置：能复制、能停用、能导出、能看自检。团队里可以直接分享一套「工种预设」。

说明：这是能力层的收敛，不替代沙箱与审批。工具名单只决定「模型能不能调用」，不决定「调用后系统允不允许」。

快速开始

1. 打开 设置 → 自定义预设模式。
2. 点「+ 新建预设模式」。
3. 填名称与描述（描述会显示在卡片上，也用于导出）。
4. 写人设，选择注入方式；不确定就先用「追加」。
5. 勾选这个任务需要的技能。
6. 选择工具范围：先用「仅白名单」，只勾真正需要的工具。
7. 按需勾选运行时上下文；不确定就全选。
8. 保存并启用，然后在新建会话时选择该预设。
9. 打开「运行时自检」确认工具面与技能符合预期。

两个容易踩的点：

• 技能名单为空 = 没有技能，不是全部。
• 工具名单为空会被归一为「全部」：选了「仅白名单」却一个都不勾，保存后会变成「全部」。配置时留意这一点。

与 dsh-session-bridge 组合：把大任务拆给不同预设

dsh-session-bridge 提供 session_bridge_* 系列工具：创建主会话、发送消息、等待回复、读取输出、监控、恢复、取消、归档。它的 session_bridge_create 支持 agentPreset 参数——这正是预设的最佳搭档：把一个大任务拆成多个会话，每个会话用不同的预设。

它创建的是独立的顶层会话（会出现在会话列表里），不是 subagent；这里按用途称为「子会话」。

为什么值得拆

一个预设再精简，也很难同时容纳「编排 + 写作 + PPT + 调研 + 代码」的全部技能；而且所有中间产物、工具输出、试错过程都会堆在同一个上下文里。拆开之后：

• 编排者的上下文只装调度所需：只有会话桥接工具，不被上百个工具 schema 和无关技能挤占。
• 执行者只加载本工种的技能：写文档的预设不会加载 PPT 技能，做 PPT 的预设不会加载代码技能；技能描述的 token 只付给需要它的人。
• 子会话历史独立：子会话里的工具输出、失败重试不会回流到主会话，主会话只读结论。
• 人设单一，行为可预测：每个预设只做一件事。
• 失败隔离：某一步跑偏，重开一个子会话重跑即可，不污染其它步骤。
• 可并行：互不依赖的子任务可以同时开。

推荐拓扑：一个「调度台」+ 若干「工种」

调度台（只开 session_bridge_*）
   ├─ 文档写作预设   → 产出 md / docx
   ├─ PPT 制作预设   → 产出 pptx
   ├─ 资料调研预设   → 产出调研笔记
   ├─ 代码实现预设   → 产出代码与测试
   └─ 审阅预设       → 只读，产出审查结论

调度台预设怎么配

配置项	建议
人设	只做拆解、分发、等待、验收、汇总；明确写「不亲自写正文、不改文件」
注入方式	「只屏蔽官方」或「追加」均可；要让调度规则绝对优先就用「完全替换」，但需自己写清工具用法
技能	不勾（调度不需要专业技能）
工具	只勾 session_bridge_create、session_bridge_send、session_bridge_wait、session_bridge_read、session_bridge_segments、session_bridge_status、session_bridge_find、session_bridge_resume、session_bridge_cancel；需要向用户澄清时再加 ask_user_question，需要亲自核对文件时再加 read / glob
运行时上下文	保留工作区与审批/沙箱策略即可

不要给调度台 write、edit、bash。它一旦能写，就会忍不住自己动手，拆解和汇总的职责随之瓦解。

监控与归档工具（session_bridge_monitor_*、session_bridge_archive 等）按需再加：长任务、需要自动催办或循环检测时给监控；归档只在收尾时用。

执行预设怎么配

预设	人设要点	技能	工具	典型产出
文档写作	只写文档，按大纲与风格要求交付；不跑命令、不改代码	写作类技能	read write edit glob grep	Markdown、文档稿
PPT 制作	只做幻灯片；先给结构再生成，遵守模板与页数约束	幻灯片 / PPT 相关技能	read write edit（需要脚本生成时再加 bash）	.pptx 与素材
资料调研	只查资料、只给有来源的结论；不写最终稿	搜索 / 调研类技能	搜索类工具或 MCP、read write（笔记）	调研笔记、来源清单
代码实现	只改指定范围，改完自测；不擅自重构	按需	read write edit bash glob grep	代码与测试
代码审阅	只读，不改；逐文件给结论与风险	不勾	read grep glob	审查报告

要点：

• 执行预设不要勾 session_bridge_*，否则执行者会继续分裂，任务层级失控。确实需要二级分发时，再单独设计。
• 工具按「最小可用」给：文档预设不需要 bash，PPT 预设不需要联网，审阅预设不需要写权限。
• 技能只勾本工种需要的；空白名单就是没有技能。

创建子会话时指定预设

session_bridge_create 的 agentPreset 接受预设卡片上显示的稳定 id：

await session_bridge_create({
  title: '文档：产品白皮书初稿',
  cwd: '/root/work/docs',                 // 子会话的工作区
  agentPreset: 'custom-1a2b3c4d',         // 换成你卡片上的 id
  prompt: [
    '任务：根据 outline.md 写白皮书初稿。',
    '要求：3000 字左右；先列三级提纲再写；只输出文档，不做其他事。',
  ].join('\n'),
  waitForReply: true,
})

• 不传 agentPreset 时，新会话沿用调用方（调度台）的预设组合——于是子会话也只会调度，不会干活。这是最常见的坑：每个子会话都要显式指定工种预设。
• 预设必须处于启用状态，否则挂载不到新会话。
• provider / model / reasoningEffort 可按子任务覆盖；不传则继承当前会话。
• 需要并行时，连续创建多个子会话并分别指定预设，再用 session_bridge_wait / session_bridge_read 收集。

一条完整工作流

1. 调度台接收目标，拆成步骤，决定每步用哪个预设、哪个 cwd。
2. 逐个 session_bridge_create，为每步指定 agentPreset，记录返回的会话 id。
3. 用 session_bridge_wait（waitFor=reply 或 waitFor=segment）等待完成；长任务用 session_bridge_status 看进度。
4. 某步失败：session_bridge_read 看输出，session_bridge_resume 恢复，必要时 session_bridge_cancel 后重开。
5. 收齐各步结论，调度台汇总；需要交叉检查时再开一个「审阅」预设。
6. 收尾：归档子会话，让会话列表保持干净。

这样做省在哪里

• 调度台每一轮只携带十来个会话桥接工具的 schema，而不是上百个工具。
• 每个执行预设只携带本工种的技能描述，PPT 技能不会出现在写文档的会话里。
• 中间过程留在子会话，主会话只保留任务书与最终结论，长任务也不会把主窗口撑爆。
• 每个子会话的人设单一，模型不需要在「我是谁」上做取舍。

安装

本插件以 DSH bundle 插件形式加载：cordis.patch.yml 会插入 Host 行，package.json 的 dsh 字段声明 Client 入口与依赖的官方设置页包。

将插件目录安装或链接到 DSH 当前 profile 的 node_modules，然后重启 DSH。例如本机验证过的布局：

ln -s /path/to/dsh-my-agent-preset \
  ~/.dsh/profiles/web/node_modules/dsh-my-agent-preset

重启后打开 设置 → 自定义预设模式。若没有出现，检查 DSH 日志中是否有 my-agent-preset 相关报错。

数据与兼容

默认数据文件：$DSH_HOME/my-agent-preset/presets.json；未设置 DSH_HOME 时落在 ~/.dsh/my-agent-preset/presets.json。可用 bundle 行 config 的 dataFile 覆盖。

改名前的 $DSH_HOME/agent-preset-studio/presets.json 不再读取；如需保留旧预设，请手工把文件移动到新路径。

{
  "version": 2,
  "presets": [
    {
      "id": "custom-1a2b3c4d",
      "name": "只读分析模式",
      "description": "只阅读与总结，不修改任何文件",
      "instructions": "你是一名只读分析助手……",
      "instructionMode": "append",
      "includeWorkspace": true,
      "contexts": ["sandbox:policy", "approval:policy", "harness:source"],
      "requiredSuppressed": [],
      "skills": ["pdf"],
      "tools": { "mode": "allow", "names": ["read", "grep"] },
      "enabled": true,
      "order": 0
    }
  ]
}

• contexts 字段缺失 = 不管理快照；数组 = 严格白名单；空数组 = 只剩必需项。
• requiredSuppressed 单独记录被强制屏蔽的必需项，与 contexts 各管一半。
• 文件使用「临时文件 + rename」原子写入。

已知限制

1. 工具管理只能有一个所有者。tools.restrict() 的契约是「限制取交集」：本插件与 dsh-tool-manager 同时管理同一 Agent 时，两边的 allow/deny 会互相抵消，可能把工具面清空。用本插件管理预设工具范围时，请禁用 dsh-tool-manager；反之亦然。自检里的「名单中有工具不在继承面内」就是这类冲突的信号。
2. 高级强制屏蔽依赖实现细节。它通过同名 scoped context 遮蔽 + prepend 过滤器实现，不是公开契约；DSH 升级后可能悄悄失效且不报错。默认关闭。
3. 屏蔽不回改历史。已经注入到会话历史里的旧快照消息不会被修改，只影响之后的组装。
4. 技能名单为空 = 无技能；工具名单为空 = 全部（保存时归一）。配置时注意。
5. 「完全替换」会移除官方工具指导。如果你的预设仍要用工具，建议在提示词里写清使用规则，或改用「只屏蔽官方」。
6. 预设只决定模型可见的能力，不替代沙箱与审批策略。

致谢

本插件的技能与工具管理机制，参考了下面两个成熟实现，感谢作者：

• @michengai/dsh-skills-manager 参考了技能目录按来源分组、分层 skills 注册表（预设 scoped context 注册 provider）、mtime 缓存读取源文件、control 接入（abort signal + invalidate）、结构化 locator（get 校验路径防 stale）等做法。

• dsh-tool-manager 参考了 agentPresets.acquireScope(id) → tools.schemas(scope.key) 的工具面读取、per-Agent 观测表（standing scope 读不到的 subagent 等）、baseline 预挂载与固定 mount 顺序、tools/change 触发的范围重装、restrict 失败按错误文本交集重试、system-prompt/assemble 过滤被拒工具 schema 等做法。

技能与工具两条链路的详细机制、根因分析与验证记录，见 docs/README.technical.md。

开发与测试

node test/verify-export-clipboard.mjs
node test/verify-copy-and-contexts-ui.mjs
node test/verify-official-only.mjs
node test/verify-complete-workspace.mjs
node test/verify-context-snapshot.mjs
node test/verify-context-registry-truth.mjs
node test/verify-official-rules-ui.mjs
node test/verify-builtin-skill-gap.mjs
node test/verify-default-data-path.mjs
node test/regression-scope-lifecycle.mjs

test/_studio-harness.mjs 是共享的浏览器桩 + React shim + Host API 录制，其余脚本各自驱动一个功能面，直接运行即可。

文件	职责
index.js	Host 半：数据读写、预设注册、技能目录、上下文过滤、工具范围、运行时自检、HTTP API
capability.js	预设内挂载的能力行：提示词 section、技能 provider、官方段规则
client.js	Client 半：设置页（列表 + 编辑器 + 自检），自带样式
cordis.patch.yml	bundle 补丁：插入 Host 行
locale/*.json	插件清单中的中英文标题与描述
docs/specs/*.md	设计规范与决策链
docs/README.technical.md	完整技术说明（原 README 全文）
test/*.mjs	回归测试