mirror of
https://github.com/iflytek/skillhub.git
synced 2026-10-13 03:58:34 +00:00
6a89832bb7
* feat(cli): add DeepSeek Harness agent profile Signed-off-by: dongmucat <1127093059@qq.com> * docs(dsh): fix custom install troubleshooting command Signed-off-by: dongmucat <1127093059@qq.com> --------- Signed-off-by: dongmucat <1127093059@qq.com>
83 lines
3.5 KiB
Markdown
83 lines
3.5 KiB
Markdown
# DeepSeek Harness 集成指南
|
||
|
||
本文说明如何把 SkillHub 中的技能安装到
|
||
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（CLI 名为 `dsh`）。
|
||
|
||
## 已验证范围
|
||
|
||
本文依据 DeepSeek Harness 提交
|
||
[`ddefc45`](https://github.com/deepseek-ai/deepseek-harness/tree/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/skill/skill-filesystem)
|
||
中的 `@deepseek-ai/dsh-skill-filesystem` 行为编写，验证日期为 2026-09-20。
|
||
该版本仍处于 `0.1.x` developer preview；升级 dsh 后请重新核对技能根目录约定。
|
||
|
||
## 安装到 dsh 原生目录
|
||
|
||
dsh 的原生项目级和用户级技能根分别是 `<仓库>/.dsh/skills` 与
|
||
`$DSH_HOME/skills`（默认 `~/.dsh/skills`）。使用默认目录时：
|
||
|
||
```bash
|
||
# 用户级：安装到 ~/.dsh/skills/<skill-slug>/
|
||
skillhub install my-skill --agent dsh --scope user
|
||
|
||
# 项目级：从仓库根目录执行，安装到 .dsh/skills/<skill-slug>/
|
||
cd "$(git rev-parse --show-toplevel)"
|
||
skillhub install my-skill --agent dsh --scope project
|
||
```
|
||
|
||
省略 `--scope` 时，显式的 `--agent dsh` 默认选择用户级目录。安装后可用
|
||
SkillHub CLI 核对记录：
|
||
|
||
```bash
|
||
skillhub list --agent dsh
|
||
```
|
||
|
||
dsh 会监听已配置的技能根；新增、重命名或删除技能后，无需重启进程即可在后续技能目录
|
||
刷新中看到变化。
|
||
|
||
## 使用共享 `.agents/skills`
|
||
|
||
dsh 也原生扫描项目级 `.agents/skills` 和用户级 `~/.agents/skills`。因此在尚未升级到
|
||
含 `dsh` profile 的 SkillHub CLI 时，或需要与其他 Agent 共享同一份技能时，可以使用：
|
||
|
||
```bash
|
||
# 用户级共享目录
|
||
skillhub install my-skill --dir "$HOME/.agents/skills"
|
||
|
||
# 项目级共享目录；仍建议从仓库根目录执行
|
||
skillhub install my-skill --dir "$(git rev-parse --show-toplevel)/.agents/skills"
|
||
```
|
||
|
||
## 自定义 DSH_HOME
|
||
|
||
SkillHub CLI 的 `dsh` profile 对应默认的 `~/.dsh/skills`。如果 dsh 使用了自定义
|
||
`DSH_HOME`，请显式指定实际目录：
|
||
|
||
```bash
|
||
skillhub install my-skill --dir "${DSH_HOME:-$HOME/.dsh}/skills"
|
||
```
|
||
|
||
## 项目根目录差异
|
||
|
||
dsh 会向上查找最近的 `.git` 祖先作为项目根目录；SkillHub CLI 的项目级 profile
|
||
则以当前工作目录为根。如果在仓库子目录执行 `--scope project --agent dsh`，SkillHub
|
||
CLI 会写入子目录下的 `.dsh/skills`，而 dsh 不会把它当作项目根。项目级安装前应先
|
||
切换到 `git rev-parse --show-toplevel` 返回的目录。
|
||
|
||
## 兼容性边界
|
||
|
||
- SkillHub 安装目录采用 `<skill-slug>/SKILL.md`，符合 dsh 对根目录一级技能包的发现规则。
|
||
- dsh 还支持根目录中的单文件 `<name>.md`；SkillHub 包仍以根级 `SKILL.md` 为规范入口。
|
||
- `SKILL.md` 至少需要合法的 kebab-case `name` 和非空 `description` frontmatter。
|
||
- 格式兼容不代表运行时能力完全相同。技能依赖的 Agent 专用工具、命令、MCP server、
|
||
环境变量和操作系统能力仍需单独验证。
|
||
- 安装前应审查技能内容和 SkillHub 安全报告；Registry Token 不应写入技能包。
|
||
|
||
## 故障排查
|
||
|
||
如果 dsh 未发现已安装技能：
|
||
|
||
1. 运行 `skillhub list`，确认安装目录和状态。
|
||
2. 确认目录结构为 `<技能根>/<skill-slug>/SKILL.md`，没有额外嵌套层级。
|
||
3. 检查 `SKILL.md` 的 `name` 与 `description` frontmatter。
|
||
4. 项目级安装确认位于最近的 `.git` 祖先下，而不是仓库子目录。
|
||
5. 自定义 `DSH_HOME` 或 `DSH_AGENTS_HOME` 时，确认安装命令使用了对应实际路径。
|