5.8 KiB
description, kind
| description | kind |
|---|---|
| 面向用户与维护者的 agent（智能体）平面呈现选择器说明，用于选择、配置或调试 agent preset 的模型看到其工具的哪种形态。 | package-reference |
@deepseek-ai/dsh-agent-tool-presentation
English | 中文
已弃用： 新配置请直接挂载
@deepseek-ai/dsh-tool-executor-native或@deepseek-ai/dsh-tool-executor-ptc。现有配置仍受支持。迁移时，将本选择器条目替换为对应的 executor 条目，并移除config.mode；不要在同一作用域同时加载两者。
概述
现有 agent preset 可以继续使用 dsh-agent-tool-presentation，选择模型看到全部原生工具 schema，还是只有带生成 SDK 的 run_code。每个 preset 可独立选择，因此 native 与 PTC agent 可以共享同一进程，而不共享工具目录。选择 ptc 需要兼容的 PTC 运行时。使用本包时 mode 字段为必填；省略本包则沿用部署默认值。
目录
使用本包
把这一行加入 agent preset，以固定每个加入该 preset 的 agent 看到其工具的方式。native 以函数定义的形式呈现每个可见工具 schema；ptc 只呈现 run_code 传输、一份生成的 SDK 以及「只有 run_code 可被直接调用」这条规则。未作声明的 agent 继承组合中最近的执行器。
把这一行加入 preset
- name: '@deepseek-ai/dsh-agent-tool-presentation'
config:
mode: ptc
| 字段 | 默认值 | 含义 |
|---|---|---|
mode |
必填 | native——每个 schema；ptc——run_code 加生成 SDK |
生成的配置目录是每个受支持字段的穷尽式真源。mode 是必填而非有默认值，因为不带这一行的 preset 会继承部署默认值。
PTC 模式需要什么
选择 ptc 需要已组合的 PTC 运行时（ctx.ptcRuntime），且其语言有已注册的 SDK 渲染器——TypeScript 运行时经 dsh-ptc-runtime-node 交付，TypeScript 与 Python 的 SDK 渲染器都内置在 dsh-tool-executor-ptc 中。在运行时首次可用之前，此兼容选择器会保留继承的执行器。若需要在 preset 激活时拒绝缺少运行时的配置，请直接挂载 dsh-tool-executor-ptc。
每个 agent 只声明一次呈现方式
一个 agent 只声明一次呈现方式。同一份组装里的第二次声明会被拒绝而不是合并：对「模型看到哪种形态」给出两个答案是矛盾，不是覆盖。
理解实现
实现细节——点击展开
本节解释该包如何实现上述行为；可观察约定已在使用本包中完整说明。
设计理念
工具注册表搬不进 preset：它的消费方全在宿主平面——agent loop（智能体循环）读它的调度器，API proxy 读它的展示转换器，每个工具插件都往里注册——而一个服务只有在所有消费方一起下沉时才能下沉。preset 能拥有的是这份注册表的呈现方式。ctx.tools.setExecutor() 为挂载作用域声明它，而挂载作用域就是 preset 的常驻挂载，因此该声明覆盖每个加入该 preset 的 agent，一个 PTC mode preset 可以与多个 native preset 同进程并存。每个组合一行，而不是每个会话一行。
源码地图
| 文件 | 职责 |
|---|---|
src/index.ts |
插件入口：mode 配置、把 ctx.tools.setExecutor 接到挂载作用域的 apply |
行为说明
选中的子插件在所需服务可用时注册执行器。注册后，卸载子插件或其运行时会使选中的执行器不可用，直到替代执行器完成注册；调用不会回退到继承的执行器。
进一步探索
包级约定对大多数消费方已经足够；需要周边领域时再阅读以下页面。
- tools 包——工具呈现模式与
setExecutorAPI。 - agent-presets 包——preset 如何组合 agent 及其常驻挂载。
- Node ptc-runtime 包——PTC 模式所需的 TypeScript 运行时。
- 历史PTC mode 执行器塌缩 note——通告面与可调用面为何保持一致。
- core 分组地图——core 各包如何组合。
模型体验
通过在 dsh-tools 中选择的工具呈现方式间接影响——这一行只在 dsh-tools 拥有的两种投影之间选择，本身不注册任何提示词、schema 或结果。
KV Cache 影响
没有直接的失效影响；呈现方式在 agent 组装时即固定，因此其请求前缀在该会话的整个生命周期内保持稳定。
已知限制与延期工作
这些限制说明这一行何时需要特别留意。它们是当前包约束，不是任务积压。
- 运行时仍在宿主平面——preset 可以选择 PTC mode，却无法自带它所需的 TypeScript 运行时；在部署提供运行时之前，PTC 选择会保持等待状态。
开发备注
维护者的工作上下文——点击展开
无。