dsh-spider

Readme

# dsh-spider · DSH 技能自动注入 + 全网技能采集插件

> 🕷️ 在 DeepSeek Harness (DSH) 会话中**自动注入所选技能**——每轮提示注入，或仅在会话开始时注入一次。
> 还会把 `~/.claude`、`~/.codex`、`~/.workbuddy` 等**其他 agent 工具目录下的技能自动采集进 DSH**。
> 设置页 + 输入区指示条，即点即存，重启保留。

[![dsh-plugin](https://img.shields.io/badge/dsh--plugin-0.1.3--alpha.1_verified-4c8dff)](#-兼容性)
[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![tests](https://img.shields.io/badge/tests-11%2F11_pass-22c55e)](tests/helpers.test.mjs)

**English** | 简体中文（本文档）

---

## ✨ 它解决什么问题

**问题一：技能是惰性的。** DSH 的技能平时只有手动 `/ponytail` 或模型自己调用时才加载。想让某个技能**常驻生效**就得每轮手动敲。这个插件让你**勾选一次，永久生效**。

**问题二：技能散落各处。** 你在 Claude Code、Codex、WorkBuddy、OpenCode 等各 agent 的目录（`~/.claude/skills`、`~/.codex/skills`、`~/.workbuddy/skills`…）里攒了一堆技能，DSH 默认只看 `~/.agents/skills` 和 `~/.dsh/skills`。本插件的 **spider 采集器**自动发现并注册这些目录，不用手动拷贝任何文件。

```
设置页勾选 ponytail + i-have-adhd
        │ 即时写入 settings 传输层（无保存按钮，点下即存盘）
宿主半块
        ├─ each-prompt 模式：技能正文进系统提示，每次请求重新渲染
        └─ start-only 模式：会话开始时盖一条持久消息（按会话日志去重，绝不重复）
        │
spider 采集器（新增）
        └─ 扫描 ~/.<任意目录>/skills + extraDirs，注册为独立 skill provider
        │
浏览器半块
        ├─ 设置 → DSH Spider：勾选列表 + 注入方式单选 + 缺失技能提示
        └─ 输入框下方指示条：技能：ponytail, i-have-adhd · 每轮（5s 刷新）
```

## 🕷️ spider 采集器怎么发现技能

纯目录驱动，**不硬编码任何工具名单**，跨平台自动适配：

| 平台 | 扫描位置 |
|---|---|
| **macOS / Linux** | `~/.<name>/skills`（点目录）+ `~/.config/<name>/skills` |
| **Windows** | `%APPDATA%\<Name>\skills` + `%LOCALAPPDATA%\<Name>\skills` |

发现逻辑：
1. 根据平台扫描上述位置下**所有一级子目录**，每个子目录若包含 `skills/` 则纳入
2. 自动覆盖 Claude Code、Codex、WorkBuddy、OpenCode、Gemini、Cursor 等任何 agent 工具——装了哪个采哪个，新工具出现无需更新插件
3. `cordis.yml` 里 `extraDirs` 可追加任意额外目录
4. **自动去重**：同一目录被多个路径引用时（如 Windows `APPDATA` 与 `LOCALAPPDATA` 指向同一位置）只采集一次
5. 只读不写：不改名、不移动、不删除任何其他 agent 的技能文件

支持的文件形态与官方 provider 一致：

- 目录包 `<root>/<skill>/SKILL.md`
- 扁平文件 `<root>/<skill>.md`
- YAML frontmatter：`name`（kebab-case）+ `description` 必填；可选 `whenToUse`、`disable-model-invocation`、`user-invocable`、`metadata`

**去重规则**：spider 的 rank (550) 低于项目级 / `~/.dsh` / `~/.agents` 的官方 rank，同名技能官方来源优先——本机的 `~/.agents/skills/ponytail` 永远压过 `~/.workbuddy/skills/ponytail` 的拷贝。

## 📋 功能

| 功能 | 说明 |
|---|---|
| ⚙️ **设置页** | 设置 → DSH Spider：技能勾选列表（含 spider 采集来的技能，带描述）、注入方式单选、缺失技能提示 |
| 🪧 **输入区指示条** | 聊天输入框下方一行，实时显示当前生效的技能与模式 |
| 🔁 **两种注入模式** | `each-prompt`（系统提示 section，每轮重渲染）/ `start-only`（会话开始盖戳一次） |
| 🕷️ **spider 采集** | 自动发现并注册 `~/.<任意agent>/skills` 目录与 `extraDirs` 里的技能，零拷贝 |
| 📚 **活注册表** | 技能正文从 `ctx.skills` 实时读取，**不拷贝文件**——改技能立即生效，删技能优雅降级 |
| 🧩 **子代理一致** | 注入同样作用于 subagent，全 agent 树语气统一 |
| 🌏 **中英双语** | 设置页与指示条跟随界面语言（zh/en） |
| ♨️ **重启保留** | 真实 profile 插件：装一次，每次 DSH 启动自动加载 |

## ⚠️ 缺点与限制（读清楚再装）

- **兼容范围窄**：只在 **DSH 0.1.3-alpha.1（源码版）** 上验证过。DSH 是 developer preview，API 随时可能变。
- **token 成本是线性的**：选中的技能正文**每轮请求都会发送**。只勾真正想常驻的。
- **`start-only` 不追溯旧会话**：只对之后新开的会话生效。
- **技能列表依赖会话目录**：设置页"可用技能"来自当前会话的技能目录；进入会话后才是完整的。
- **同名技能官方优先**：spider 采集的技能在官方来源（项目/`~/.dsh`/`~/.agents`）有同名时会被遮蔽（设计如此，防止拷贝版本盖掉正主）。
- **无遥测/自动更新**：装了就是装了，DSH 升级后需要你自己回来检查兼容性。

## 🔧 兼容性

| 环境 | 状态 |
|---|---|
| DSH 0.1.3-alpha.1（源码 checkout 运行） | ✅ 实测通过 |
| DSH 0.1.2-rc.x（npm 发布版） | ⚠️ 未验证 |

## 🚀 安装

### 方式 A：从 GitHub 直装（推荐）

```bash
dsh plugin --profile web add github:countossbot/dsh-spider
```

pnpm ≥10 第一次会拒绝运行 git 依赖的构建脚本。在 profile 目录的 `pnpm-workspace.yaml` 加：

```yaml
allowBuilds:
  dsh-spider: true
```

（不授权也不影响使用——`prepare` 会回退到仓库里已提交的 `lib/` 产物。）

**安全建议**：锁定 commit：

```bash
dsh plugin --profile web add github:countossbot/dsh-spider#<commit-sha>
```

### 方式 B：本地路径

```bash
git clone https://github.com/countossbot/dsh-spider.git
cd dsh-spider && npm install
dsh plugin --profile web add /path/to/dsh-spider
```

**装好后**：重启 DSH → 设置 → DSH Spider → 勾选技能 → 开**新会话**生效。

### 验证安装

```bash
# 路由探针
curl -s http://127.0.0.1:3080/dsh-spider/api | python3 -m json.tool
# available 列表应包含 ~/.claude/skills 等采集来的技能

# 持久化探针
grep -A5 dsh-spider ~/.dsh/settings.yaml
```

## ⚙️ 配置

设置页操作存于 `dsh-spider` settings 命名空间；spider 采集器的 `extraDirs` 在 `cordis.yml` 配置：

| 键 | 位置 | 默认 | 说明 |
|---|---|---|---|
| `mode` | 设置页 | `each-prompt` | `each-prompt` / `start-only` |
| `selected` | 设置页 | `[]` | kebab-case 技能名，最多 16 个，自动去重 |
| `extraDirs` | cordis.yml | `[]` | spider 额外扫描的技能根目录 |

cordis.yml 示例：

```yaml
plugin:
  dsh-spider:
    extraDirs:
      - /Volumes/work/shared-skills
```

## 🔒 安全

- 对所有技能目录（含其他 agent 的）**只读**：不写、不改名、不删除。
- 注入内容是本地受信 markdown；不访问网络、无遥测。
- `each-prompt` 路径对技能正文做 `{{` 转义；`start-only` 消息保留原文。

## 🧱 架构

```
dsh-spider/
├── src/
│   ├── index.ts            # 宿主半块：settings、技能缓存、注入逻辑、HTTP 路由
│   ├── extra-skills.ts     # spider 采集器：目录发现 + provider 注册
│   ├── helpers.ts          # 纯函数（零 dsh import）：校验/转义/渲染
│   └── client/
│       ├── index.tsx       # 浏览器半块：settings.section + composer.dock
│       └── locales.ts      # zh/en 字典
├── scripts/build.mjs       # esbuild 双产物
├── scripts/prepare.mjs     # git 安装安全钩子
├── tests/                  # node:test 单测
├── cordis.patch.yml        # dsh.bundle patch
└── package.json            # dsh.bundle + dsh.client 声明
```

## 🙏 致谢

- [Zenjibad/skill-injector-plugin](https://github.com/Zenjibad/skill-injector-plugin) —— 功能蓝本
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) —— 插件运行时

## 📄 许可

[MIT](LICENSE)