# dsh-plugin-dev-skills

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

## Metadata

- Author: [@zimodzh](https://github.com/zimodzh)
- Repo: <https://github.com/zimodzh/dsh-plugin-dev-skills.git>
- GitHub: [zimodzh/dsh-plugin-dev-skills](https://github.com/zimodzh/dsh-plugin-dev-skills)
- Stars: 38
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://github.com/zimodzh/dsh-plugin-dev-skills>
- Topics: `agent`, `agent-skill`, `agent-skills`, `ai`, `ai-agent`, `awesome-dsh-plugin`, `claude-code`, `codex`, `deepseek`, `deepseek-harness`, `dsh`, `dsh-plugin`, `llm-agent`, `skill`, `skills`
- Forks: 1
- Open Issues: 0
- Last push: 2026-08-18T07:33:42.000Z
- Added: 2026-08-19T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
这是 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 依赖 |

## 安装方式
```bash
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）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-plugin-dev-skills](https://deepseek-plugin.org/plugins/zimodzh/dsh-plugin-dev-skills/examples/greet-tool)
Wiki generated by AI (model: `MiniMax-M3`)