dsh-plugin-dev-skills/examples/greet-tool

38Star1Fork0Issue0Watching

DSH 插件开发技能包中的最小工具示例，向模型注册一个 greet 工具演示 defineTool 标准用法。

zimodzhzimodzh
·zimodzh/dsh-plugin-dev-skills.git·github.com/zimodzh/dsh-plugin-dev-skills
License
MIT
分支
master
agentagent-skillagent-skillsaiai-agentawesome-dsh-pluginclaude-codecodex

安装

$ dsh plugin --profile web add github:zimodzh/dsh-plugin-dev-skills/examples/greet-tool

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

一句话定位

这是 dsh-plugin-dev-skills 仓库自带的一个最小可运行示例，向 DSH 的模型注册一个名为 greet 的问候工具，用于演示 defineTool 的标准写法。它不是一个生产功能插件，而是给想学习 DSH 插件开发的用户的参考样板。

核心能力

  • 向 DSH 工具注册表注册一个名为 greet 的工具，供大模型在对话过程中调用
  • 接收一个必填字符串参数 name，返回 "Hello, {name}!" 形式的问候字符串
  • 在 output.schema 中声明返回类型为字符串，并在 output.render 中把值渲染成模型可消费的内容块
  • 演示 inject: ['tools'] 的写法，让 Cordis 容器在执行 apply 之前先准备好工具注册表
  • 作为 dsh-plugin-dev 技能 references/tools.md 文档配套的可复制运行示例

技术实现

  • 语言: JavaScript（ESM，"type": "module"）
  • 关键依赖: @deepseek-ai/dsh-tools（由 DSH 安装目录自带，无需在 package.json 中声明）
  • 架构模式: Cordis 插件模型，apply(ctx) 中通过 ctx.tools.register 注册工具；inject: ['tools'] 让 Cordis 等待依赖就绪
  • 入口文件: examples/greet-tool/index.js

适用场景

适合正在学习 DSH 插件开发、想跑通"自定义模型工具"完整链路的开发者。当你读完 references/tools.md 文档想要一份能直接 dsh plugin add 跑起来的最小例子时，安装这个示例插件并让 agent 调用一次 greet 工具，就能直观看到 parameters/execute/output 三段式的真实运行效果。生产场景请基于该示例自行扩展。

前置依赖与兼容性

依赖最低版本说明
DSH未声明仅依赖宿主自带的服务，未在 package.json 中声明 engines
Node未声明仅使用 ESM 语法，未在 package.json 中声明 engines
平台跨平台纯 JavaScript 实现，无原生模块
原生模块无package.json 中无 native 依赖

安装方式

dsh plugin --profile web add github:zimodzh/dsh-plugin-dev-skills/examples/greet-tool

配置项

本插件无需额外配置。所有行为（问候语前缀、参数 schema、返回值）都直接写在 index.js 源码里，没有暴露任何配置项。

常见问题

Q: 安装后在终端里能直接调用 greet 命令吗？

A: 不能。greet 不是 CLI 子命令，而是一个模型可调用的 tool。你需要在 dsh 对话里让 agent 主动调用它，比如对 agent 说 "Use the greet tool to greet Ada."，它就会调用工具并把 "Hello, Ada!" 回复给你。

Q: 安装这个插件需要额外安装 @deepseek-ai/dsh-tools 吗？

A: 不需要。该包由 DSH 安装目录自带，插件 index.js 里直接 import { defineTool } from '@deepseek-ai/dsh-tools' 即可使用，无需在 package.json 的 dependencies 中声明。

Q: 这个示例和同仓库的 hello-plugin 示例有什么区别？

A: hello-plugin 是最简生命周期示例，只演示 Cordis 插件的启动与自动清理；greet-tool 是模型可调用的工具示例，演示 defineTool 的 parameters、execute、output 三段式写法。两者侧重点不同，建议一起读。

Q: 可以把问候语改成可配置吗？

A: 可以，但需要改源码。当前实现把 "Hello, " 前缀硬编码在 execute 里。你可以修改 index.js 把它抽到 ctx.config，或者参考上游 dsh-plugin-dev 技能的 references/config.md 文档按标准写法改。

Q: 插件里的 inject: ['tools'] 是什么意思？

A: 它告诉 Cordis 容器在执行 apply(ctx) 之前先把 tools 服务注册好，避免在 ctx.tools.register 时注册表还没就绪而抛错。这是写工具类插件的标准约定。

Q: 安装后只在当前 profile 生效吗？

A: 是的。--profile web 指定了目标 profile，插件只会被加入该 profile 的插件列表，不会影响其他 profile。

上手难度

入门 — 示例本身只有 24 行代码，一个 defineTool 调用加一个 cordis.patch.yml，跑通即代表已经掌握了 DSH 工具插件的标准骨架。

已知问题与限制

  • 问候语格式 "Hello, " 与返回值模板都直接写在 index.js 的 execute 函数里，源码中没有任何配置读取或环境变量分支，想要修改前缀或拼接逻辑只能改源码（evidence: examples/greet-tool/index.js:21）
  • cordis.patch.yml 中 id: greet-tool 和 name: dsh-greet-tool 都是硬编码字符串，如果用户环境里已有同名插件 id 会产生命名冲突（evidence: examples/greet-tool/cordis.patch.yml:2-3）
  • 源码中未声明任何 engines、peerDependencies、os、cpu 字段，DSH 版本兼容性需由宿主侧校验（evidence: examples/greet-tool/package.json:1-8）
返回插件目录