前言¶
在 DeepSeek Harness（DSH）里做智能体工作流时，常见做法是手写 slash 命令、维护技能清单，或在对话里反复粘贴同一套规范。若规范分散在仓库的 .dsh / .agents 目录和用户主目录下，DSH 默认并不会自动扫描并注册它们。维护者 SugarFatFree 提供的 dsh-agent-extension 是一个工作流类 DSH 插件：从项目与用户配置目录发现可复用的 Markdown slash 命令、skills，以及按路径生效的 rules，并按文档约定的优先级去重后挂到 DSH 上。
下面介绍它的定位、能力、安装步骤和典型写法。事实以 GitHub 仓库 README 为准；社区目录页见 SkillHub 插件页。
这是什么¶
dsh-agent-extension 是面向 DSH web profile 的插件（当前版本 0.1.5，许可证 MIT）。一句话：DeepSeek Harness plugin for workspace commands, skills, and path-scoped rules.
它解决的是「定义已在磁盘上，但未进入 DSH 会话」的问题：把 commands、skills、rules 目录下的 Markdown 发现出来，注册为 slash 命令、通过 DSH skills 提供方暴露技能，并在匹配的工作区文件被读写改之后注入路径规则。
核心功能¶
已核实能力如下（摘自官方 README）：
- 同时扫描项目级与用户级的 commands、skills、rules。
- 兼容
.dsh与.agents两套目录约定。 - 重复定义按文档优先级解析，行为可预期。
- Markdown 命令注册为 DSH slash 命令；skills 走 DSH skills provider API；匹配的路径规则在相关文件活动后注入。
- 每个发现根下支持最多 六层嵌套目录。
会话中的项目根：向上找到最近包含 .git 的祖先；若没有 Git 仓库，则用会话工作目录。
| 类型 | 项目根 | 用户根 |
|---|---|---|
| Commands | <project>/.dsh/commands/**、<project>/.agents/commands/** |
~/.dsh/commands/**、~/.agents/commands/** |
| Skills | <project>/.dsh/skills/**、<project>/.agents/skills/** |
~/.dsh/skills/**、~/.agents/skills/** |
| Rules | <project>/.dsh/rules/**、<project>/.agents/rules/** |
~/.dsh/rules/**、~/.agents/rules/** |
冲突时先命中者优先，顺序为：
- 项目
.dsh - 项目
.agents - 用户
~/.dsh - 用户
~/.agents
命令以命令名、技能以 skill 名、规则以 rules 目录下的相对路径作为冲突键。
安装与启用¶
环境要求：
- 已安装 DeepSeek Harness，并启用
webprofile。 - pnpm（DSH 用其管理 profile 插件）。
插件目前仅从 GitHub 分发，未发布到 npm；用 DSH 原生命令安装即可，无需 npm 账号：
dsh plugin --profile web add github:SugarFatFree/dsh-agent-extension
DSH 因 package.json 中声明的 dsh.bundle.patch 识别该包；安装会写入所选 profile，并自动加入 dsh.profile.bundles。
安装后需要重启 DSH Web 进程并刷新浏览器；新建会话或恢复已有会话，以刷新 slash 命令目录。
本地开发时可在仓库根目录执行：
dsh plugin --profile web add .
若修改了本地 file: 依赖，需在 Web profile 目录执行 pnpm install --force 刷新 node_modules，再重启 DSH Web。
典型用法¶
Slash 命令¶
commands 根下每个 Markdown 文件对应一条 slash 命令。名称解析顺序：YAML frontmatter 的 name → 形如 # /release - Release 的 H1 → 文件名。
---
name: release
description: Prepare a release
---
Read the release checklist and prepare the release notes.
在会话中输入 /release optional arguments 会开启一轮普通 agent turn，命令正文与参数作为任务说明。
命令目录会被监听；新增例如 .agents/commands/aa.md 后，已打开会话可在不重启 DSH Web 的情况下获得 /aa（命令菜单通过 DSH 的 live command-change 事件更新）。
Skills¶
技能可以是单个 Markdown 文件，或含 SKILL.md 的目录包。需要标准 frontmatter：name（kebab-case）、description。
---
name: api-review
description: Review API compatibility
whenToUse: Before publishing a changed API
---
Review the changed API surface.
可选字段 disable-model-invocation、user-invocable、metadata 会透传给 DSH。Skills 出现在 DSH Skills 目录与 / 的 skill 来源，而非仅 command 来源；某一发现根内不可读的文件会被跳过，避免挡住其他根下的技能。
路径规则（path-scoped rules）¶
规则是 rules 根下的 Markdown，且 frontmatter 中 paths 非空；无 paths 的文件（含 README.md）会被忽略。
---
name: frontend-conventions
paths:
- "code/frontend/**"
- "web/**"
---
Use the established component and accessibility conventions.
匹配的规则在 agent 成功读、写或编辑匹配的工作区文件之后、下一次模型步之前注入一次。模式相对项目根计算。
验证安装¶
在 agent 会话中执行内置命令：
/dsh-extension-status
输出包含当前会话工作目录，以及已发现的 commands、skills、rules；项目命令会注册到会话命令目录并出现在 / 菜单中。
适用场景与注意¶
适合谁： 已在仓库或 ~/.dsh、~/.agents 里用 Markdown 维护命令、技能与团队规范，希望在 DSH Web 会话里自动生效的开发者；需要 .dsh 与 .agents 混用、或项目与用户层叠加且需明确优先级时。
注意：
- 插件在 DSH 进程权限下运行，安装前请自行审阅 源码与 LICENSE，确认符合你的安全与合规要求。
- 依赖
@deepseek-ai/dsh-llm（peer，^0.1.5-rc.2）与chokidar；行为以当前 DSH 与插件版本为准。 - SkillHub 等社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系；安装命令以 README 为准，勿凭插件名自行拼接。
结尾¶
dsh-agent-extension 把分散在项目与用户目录里的 Markdown 工作流定义接到 DSH：命令进 / 菜单，技能进 Skills 目录，路径规则在编辑相关文件时自动注入。若你正在用 Harness 的 web profile 做团队智能体工作流，可按上文命令安装，用 /dsh-extension-status 核对发现结果。
