dsh-agent-extension

dsh-agent-extension

English README

一个 DeepSeek Harness (DSH) 插件，用于从项目目录和当前用户的配置目录中发现可复用的 Markdown 斜杠命令、技能与按路径生效的规则。

功能

• 发现项目级和用户级的命令、技能与规则。
• 同时兼容 .dsh 与 .agents 目录约定。
• 按明确的优先级处理重名定义。
• 将 Markdown 命令注册为 DSH 斜杠命令。
• 通过 DSH Skills Provider API 提供技能。
• 在相关工作区文件操作后注入匹配的路径规则。
• 在每个发现根目录下最多递归六层。

前置条件

• 已安装带 web Profile 的 DeepSeek Harness。
• 已安装 pnpm，DSH 使用它管理 Profile 插件。

安装

使用 DSH 原生插件命令直接从 GitHub 安装：

dsh plugin --profile web add github:SugarFatFree/dsh-agent-extension

该插件的 package.json 声明了 dsh.bundle.patch，DSH 会将其识别为插件，安装到指定 Profile 中，并自动加入 dsh.profile.bundles。

安装后请重启 DSH Web 进程并刷新浏览器页面。新建或恢复一个会话后，斜杠命令目录会重新建立。

发布状态

当前项目仅通过 GitHub 分发，尚未发布到 npm。GitHub 安装路径是完整受支持的，不需要 npm 账号：

dsh plugin --profile web add github:SugarFatFree/dsh-agent-extension

后续可能会提供更短的 npm 包名安装方式，但 npm 发布是可选项，不影响 DSH 兼容性或插件目录收录。

本地开发安装

在本仓库目录中执行：

dsh plugin --profile web add .

修改本地 file: 依赖后，请在 Web Profile 目录执行 pnpm install --force，以刷新已安装的 node_modules 副本，然后重启 DSH Web。

发现目录

对于每个会话，项目根目录为最近的包含 .git 的父目录；不存在 .git 时，则使用会话工作目录。

定义最多可位于上述根目录之下六层。例如，.agents/skills/team/review/SKILL.md 和 .dsh/commands/release/prepare.md 都会被发现。

优先级

同类定义发生冲突时，按以下顺序优先使用第一个结果：

1. 项目 .dsh
2. 项目 .agents
3. 用户 ~/.dsh
4. 用户 ~/.agents

命令以命令名作为冲突键，技能以技能名作为冲突键，规则以各自 rules 根目录下的相对路径作为冲突键。

命令

commands 目录下的每个 Markdown 文件都会成为一个斜杠命令。名称依次取自 YAML frontmatter 的 name、形如 # /release - Release 的一级标题、文件名。

---
name: release
description: Prepare a release
---

Read the release checklist and prepare the release notes.

输入 /release optional arguments 后，DSH 会启动一个普通 Agent 回合，并将命令正文与参数作为任务指令传入。

命令根目录会监听 Markdown 文件的新增、修改、删除以及嵌套目录变化。新增 .agents/commands/aa.md 后，已打开的会话会获得 /aa，无需重启 DSH Web；命令菜单通过 DSH 的实时命令变更事件更新。仅当浏览器连接中断时才需要刷新页面。

技能

技能可以是单个 Markdown 文件，也可以是包含 SKILL.md 的目录包。技能必须使用标准 YAML frontmatter，并提供 kebab-case 格式的 name 与 description。

---
name: api-review
description: Review API compatibility
whenToUse: Before publishing a changed API
---

Review the changed API surface.

可选 frontmatter 字段 disable-model-invocation、user-invocable 与 metadata 会透传给 DSH。技能通过 DSH 的 Skills 目录及 / 的技能来源显示，而不是仅命令来源；某个发现目录内不可读的文件会被跳过，不会隐藏其他目录中的技能。

按路径生效的规则

规则是 rules 目录下的 Markdown 文件，且 YAML frontmatter 中必须包含非空的 paths 列表。没有 paths 的 Markdown 文件，包括 README.md，都会被忽略。

---
name: frontend-conventions
paths:
  - "code/frontend/**"
  - "web/**"
---

Use the established component and accessibility conventions.

Agent 成功读取、写入或编辑匹配的工作区文件后，匹配规则会在下一次模型执行前注入一次。路径模式相对于项目根目录判断。

验证安装

在 Agent 会话中运行内置命令：

/dsh-extension-status

该命令会输出调用该命令的会话工作目录，以及已发现的命令、技能和规则。已发现的项目命令会注册到会话命令目录并显示在 / 菜单中。

许可证

MIT