Agent Preset

agent preset 是一个目录，其中放置一份 agent.cordis.yml。把它挂载到某个 agent（智能体）的 scope 上下文之下，该会话就获得自己的工具与提示词段落，而其他正在运行的会话各自保持不变——因此一个进程可以同时运行多个组装方式不同的 agent。

一份组合长什么样

agent.cordis.yml 是一份顶层插件行列表，与宿主组合使用相同的 Loader 方言（包括 !!js）。它承载的是单个 agent 对全局注册表的贡献：工具、提示词段落、变量、限制，以及 persona（人设）行。注册表与跨会话设施仍是进程单例，留在宿主组合中；preset 只负责"这一个会话"的组装。

preset 可以携带 preset.yml 提供展示文本，但仅此而已：

name: 极简模式
description: 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。

id 是目录名，trust 来自发现它的根目录，两者都不能在这里写入。展示元数据不是能力：name 损坏的 preset 仍然可以挂载。

preset 存在哪里

部署随附的 preset 位于已安装应用的配置目录 apps/cli/config/agent-presets/，一个 preset 一个目录。用户自己的 preset 放在 <dshHome>/.agent-presets（默认 $DSH_HOME/.agent-presets 或 ~/.dsh/.agent-presets）下，作为 user 信任根被自动发现。发现不缓存：进程运行期间新建的 preset 立即可见，删除的也会在下一次读取时消失。

随附的 minimal（极简模式）preset 固定系统提示词为 You are a helpful software engineer assistant.，只组合持久 bash 与 str_replace_editor 两个工具，其余提示词段落与面向模型的插件一概不出现。

选择与切换

新建 Web 会话时可选择 preset；未指定时使用默认 preset。默认值是用户设置，由 agent-presets 命名空间下的 default 字段决定：

agent-presets:
  default: minimal

该值在每次解析时读取，热重载的设置在下一个会话创建时生效，而每个正在运行的会话仍保持它被组装时所依据的 preset。清除该字段会重新继承组合层的默认值。

创作：复制，而非手写

创作只支持"复制"。新建 preset 是对一个已有 preset 的整目录复制（组合、元数据、技能目录、资源），落到第一个 user 根目录下；复制只接收两个 id 与可选显示名，绝不接收组合文本。复制前会拒绝三件事：

• 不是合法 preset id 的 id——id 会成为目录名，只接受 [a-z0-9][a-z0-9-]*，../escape、a/b、绝对路径都会被拒绝；
• 已被占用的 id——复制永不覆盖；
• 不存在的源——失败时回滚半成品目录。

复制出的 preset.yml 会保留源的 description 供你就地编辑，但丢弃其 name 与排序 order，以免副本与源在清单中无法区分。

preset 中的行如何解析

• 行里的包名从宿主组合解析，而非从 preset 目录解析——本地 preset 位于用户 home 下，Node 向上查找 node_modules 永远到不了 harness，因此挂载会把宿主 base 记录下来并把裸 specifier 送过去；
• 相对路径仍从 preset 自己的目录解析，所以 preset 自带的插件文件与技能目录随它一起移动；
• 绝对路径保持原位，挂载时转换为 file: URL 再交给 ESM import。

挂载会拒绝什么

• 无 scope 的目标：在没有 agent scope 的上下文里挂载，会把 preset 的工具注册成全局、对所有 agent 可见；
• 永远无法就绪的行：等待一个组合永不提供的服务的行会被审计点名；
• 向根领域发布服务的行：这类服务是进程级的，两个 preset 发布同名服务会冲突。preset 若确实拥有某服务，应放到 isolate 领域，或把服务上移到宿主组合。

下一步

• 组合语法见开发者指南的 Cordis 入门。
• 想给 preset 附带可复用指令，见技能与目标。