@morehao/dsh-skills-console 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +54 -64
  2. package/client.js +2537 -1227
  3. package/icon.svg +2 -1
  4. package/lib/core/cli.js +3 -1
  5. package/lib/core/links.js +1 -1
  6. package/lib/core/service.js +340 -66
  7. package/lib/core/updates.js +12 -0
  8. package/lib/routes.js +26 -2
  9. package/package.json +10 -4
package/README.md CHANGED
@@ -1,36 +1,50 @@
1
- # dsh-skills-console
1
+ <img src="icon.svg" width="64" height="64" alt="技能控制台图标" align="right" />
2
2
 
3
- DeepSeek Harness（dsh）的**技能控制台**：**装 / 更新 / 删除 / 接入其他 Agent / 启停**，配一个订阅列表。
3
+ # 技能控制台 · dsh-skills-console
4
4
 
5
- > 与 `skills` CLI 的分工：CLI 是技能的唯一写者（供应链 + lock），本插件是 DSH 侧的控制台（可见性 + 接线 + 事务）。它不搬技能，它管「哪些技能、对谁、在哪一层可见」。
5
+ [![npm version](https://img.shields.io/npm/v/@morehao/dsh-skills-console.svg)](https://www.npmjs.com/package/@morehao/dsh-skills-console)
6
+ [![check](https://github.com/morehao/dsh-skills-console/actions/workflows/check.yml/badge.svg)](https://github.com/morehao/dsh-skills-console/actions/workflows/check.yml)
7
+ [![license](https://img.shields.io/npm/l/@morehao/dsh-skills-console.svg)](LICENSE)
6
8
 
7
- ## 定位
9
+ DSH（DeepSeek Harness）的**技能控制台**：装、更新、删除、接入其他 Agent、随时启停，外加一份订阅清单。
8
10
 
9
- - **技能真身只认 `skills` CLI**：下载、解析、落盘到 canonical（`~/.agents/skills`）、写 lock，全部交给 [`skills`](https://www.npmjs.com/package/skills) CLI。本插件不代理来源、不写 lock、不克隆仓库。
10
- - **DSH 侧只靠原生根**：往原生 `user-dsh` 根（`~/.dsh/skills`，rank 400）建软链让 DSH 发现；项目维度写 `project-dsh` 根（rank 100）。不注册自有 provider、不改 DSH 配置。
11
- - **其他 Agent 靠软链分发**：Claude Code / Cursor / Codex … 各自 `skills` 目录里放指向 canonical 的软链。
12
- - **启停 = DSH 侧链接的有/无**：不动 `SKILL.md`（`add` 会整份覆盖，改文件还会让更新被锁死）。
11
+ 它不搬技能。技能真身始终由 [`skills`](https://www.npmjs.com/package/skills) CLI 写进 `~/.agents/skills`；本插件只在 DSH 这一侧做控制台：决定**哪些技能、对谁、在哪一层可见**，并把每次改动做成可回滚的事务。
13
12
 
14
- ## 状态
13
+ ## 为什么需要它
15
14
 
16
- P0–P2 已实现并通过单测（62 个用例）：
15
+ - **两份目录，一个真身**：技能装在 `~/.agents/skills`，DSH 只读 `~/.dsh/skills`。插件负责在两边建软链，不复制文件、不产生第二份真相。
16
+ - **一份技能，多个 Agent**：Claude Code / Cursor / Codex … 各自只认自己的 `skills` 目录。勾一次，分别建链，之后装新技能也能按偏好自动接入。
17
+ - **装完不是结束**：上游仓库一直在动。插件按 commit 比对，先给出「会影响哪些技能」的计划，再让你决定更新。
18
+ - **看不见 ≠ 删掉**：临时不想让模型用到某个技能，关掉 DSH 侧链接即可；文件和其他 Agent 的接入原样保留。
19
+ - **删错还能救**：删除前先快照进回收站（保留 7 天），更新失败自动回滚上一版。
20
+
21
+ ## 功能
17
22
 
18
23
  | 能力 | 说明 |
19
24
  | --- | --- |
20
- | 清单 | canonical 扫描 + CLI lock 对账 + `ctx.skills.snapshot` 可见性对账（模型可见 vs 本地账本）；canonical 里已有的技能首次读取自动纳入追踪，不必逐个「接管」 |
21
- | 接入 | 软链四态判定（`managed` / `managed-external` / `foreign-link` / `real`），**绝不覆盖**非本插件创建的东西；可接入的 Agent 只列本机已装目录，「自动链接」按 Agent 多选 |
22
- | 入口 | 默认在设置页「技能控制台」分区；页内可切到左侧栏独立面板，切换立即生效；主页右上角提供 GitHub 仓库入口 |
23
- | 安装 | `skills add <owner/repo#commit> --skill … -a universal -g -y --json --full-depth`，装完断言 lock 的 `skillFolderHash` 与快照 tree SHA 一致 |
24
- | 更新 | GitHub Trees API 检测 → 计划（commit 区间 + token）→ 应用（先备份、后重建、失败回滚） |
25
- | 删除 | 体检（真实目录/外部链接即中止）→ 快照进回收站（7 天）→ `skills remove -s … -g -y`（**不带 `-a`**）→ 清自家链接与记账 |
26
- | 启停 | `mode: on/off` 只摘 DSH 侧链接，文件与其他 Agent 链接不动 |
27
- | 作用范围 | 全局，或仅 `project-dsh` 根；项目可直接勾选 DSH 已登记的工作区 |
28
- | 订阅 | `owner/repo` + ref + 子目录，只记快照不安装 |
25
+ | 清单 | canonical 扫描 + CLI lock 对账 + DSH 实际可见性对账；canonical 里已有的技能首次读取自动纳入追踪，不必逐个「接管」 |
26
+ | 安装 | 填 `owner/repo`（可只装其中几个技能），下载、落盘、写 lock 全部交给 CLI；来自订阅快照时核对 lock 哈希，不一致会提示 |
27
+ | 更新 | GitHub Trees 检测上游新 commit → 计划（commit 区间 + 影响范围 + 防抖 token）→ 应用前备份，失败自动回滚上一版 |
28
+ | 删除 | 先体检（真实目录 / 外部链接直接中止）→ 快照进回收站 → 只删本插件建的链接与记账，CLI 的 `remove` 不带 `-a` |
29
+ | 接入 | 软链四态判定（`managed` / `managed-external` / `foreign-link` / `real`），**绝不覆盖**别人创建的东西；只列本机已安装目录，已删的 Agent 自动从列表消失 |
30
+ | 启停 | `mode: on/off` 只摘或重建 DSH 侧链接，不动 `SKILL.md`，其他 Agent 的链接也不受影响 |
31
+ | 作用范围 | 全局 `~/.dsh/skills`，或仅指定项目；项目可直接勾选 DSH 已登记的工作区，也可手动选目录 |
32
+ | 订阅 | 关注 `owner/repo`（可指定 ref / 子目录；ref 缺省时跟随仓库默认分支，`master` 仓库也能用），只记快照、不装技能；上游读不到快照时直接报错，不会留下空订阅 |
33
+
34
+ ## 界面
35
+
36
+ - **两个入口**：默认在「设置 → 技能控制台」；页头 ⚙ 里可切到左侧栏独立面板，切换立即生效。
37
+ - **一页两 tab**：已安装 / 订阅。页头右侧是「自动接入」（多选 Agent）与「添加技能 / 添加订阅」。
38
+ - **每行四个动作**：开关（启停）、更新、接入设置、删除；状态标签覆盖最新 / 可更新 / 本地已改 / 上游已移除 / 软链断裂等。
39
+ - **Agent 多了不挤**：每行最多展示 3 个，其余折成 `+n`，悬浮或聚焦即可看全。
40
+ - **找得到**：支持按名称 / 来源 / Agent 搜索，按「可更新 / 待检查 / 已停用」筛选，平铺或按 Agent 分组。
29
41
 
30
42
  ## 安装
31
43
 
44
+ 在 Harness 里装本地 link：
45
+
32
46
  ```bash
33
- # 在 Harness 里：plugin_manager install_bundle(target = 本仓库绝对路径)
47
+ plugin_manager install_bundle(target = <本仓库绝对路径>)
34
48
  ```
35
49
 
36
50
  或写进 profile 的 `cordis.patch.yml`：
@@ -41,53 +55,25 @@ P0–P2 已实现并通过单测（62 个用例）：
41
55
  name: '@morehao/dsh-skills-console'
42
56
  ```
43
57
 
44
- > ⚠️ 本机 profile 里可能还装着 `@michengai/dsh-skills-manager`（显示名「技能管理」）。两者互不干扰（路由前缀 `/api/morehao/skills-console/*`、状态目录 `$DSH_HOME/skills-console/` 均不同），但会各出一个设置分区；只想留一个时把另一个 `plugin_manager set_plugin enabled:false` 即可。
45
-
46
- ## 从 `dsh-skills-manager` 迁移
47
-
48
- `v0.2.0` 起包名、插件 id、路由前缀与状态目录都换成 `skills-console`，**不提供兼容读旧值**：
49
-
50
- | 层面 | 旧 | 新 |
51
- | --- | --- | --- |
52
- | npm 包 / 模块标识符 | `@morehao/dsh-skills-manager` | `@morehao/dsh-skills-console` |
53
- | 插件 id（配置树键） | `dsh-skills-manager` | `dsh-skills-console` |
54
- | 路由前缀 / 鉴权头 | `/api/morehao/skills-manager` · `x-dsh-skills-manager` | `/api/morehao/skills-console` · `x-dsh-skills-console` |
55
- | 状态目录 | `$DSH_HOME/skills-manager/` | `$DSH_HOME/skills-console/` |
56
- | 环境变量 | `DSH_SKILLS_MANAGER_*` | `DSH_SKILLS_CONSOLE_*` |
57
-
58
- **保住现有账本**（订阅、回收站、链接记录、版本缓存）只需把旧目录搬过去：
59
-
60
- ```bash
61
- mv ~/.dsh/skills-manager ~/.dsh/skills-console
62
- ```
63
-
64
- 不搬也能用：软链四态判定会把已有链接读成 `managed-external`（指向 canonical 但账本无记录），在设置页点一次「接管」即可恢复接管，**不会误删也不会覆盖**；代价是订阅列表、回收站快照与「已停用」状态会丢失。
65
-
66
- 安装侧：profile 的 `package.json` 依赖键要从 `@morehao/dsh-skills-manager` 换成新名（`link:` 本地接入时同步改路径），否则 bundle 不会加载。
67
-
68
- ## 开发
69
-
70
- ```bash
71
- npm test # node --test，临时 HOME / DSH_HOME，不碰真实目录
72
- npm run check # 语法自检 + 命名/导出接线 + 打包白名单 + Release 说明投影冒烟
73
- npm run sync:agents -- <skills/dist/cli.mjs> # 重新导出 agent 目录表（默认写回 lib/agent-table.json）
74
- ```
58
+ 客户端 half 只注册 `platform: web`，面板出现在 DSH Web 的设置页 / 侧栏。
75
59
 
76
- 目录结构、测试策略（离线 / stub CLI / 各用例覆盖什么）与调试手段见 [docs/development.md](docs/development.md)；
77
- 在本仓工作的 AI agent 请先读 [AGENTS.md](AGENTS.md)（硬约束与任务路由）。
60
+ ## 快速上手
78
61
 
79
- ## 发布
62
+ 1. **添加技能**：点右上角「添加技能」，填 `owner/repo` 或 GitHub URL，点「检测技能」；仓库里有多个技能时勾选要装的（支持多选，默认全选，列表带每个技能的说明），只有一个会默认勾上。检测不到时可以直接手填技能名，留空则装仓库内全部。
63
+ 2. **接到别的 Agent**：点行内「接入设置」，勾选目标 Agent；需要限定项目时改选「仅以下项目」并勾工作区。之后新装技能默认接哪些 Agent，用它旁边的「自动接入」设定。
64
+ 3. **检查更新**：点列表头上的刷新图标；有更新的行会亮起「更新」，也可以一次「全部更新」。本地改过的技能会先要求确认。
65
+ 4. **临时停用**：关掉行内开关。DSH 看不到它，但文件和其他 Agent 的接入都还在；再打开就恢复。
80
66
 
81
- 打注记 tag `vX.Y.Z` → GitHub Actions（OIDC / Trusted Publishing）自动发布到 npm → 用 tag 注记正文建 GitHub Release；不需要任何 npm token。完整流程、一次性建包配置与排障清单见 [docs/publishing.md](docs/publishing.md)。
67
+ ## 可靠性
82
68
 
83
- ```bash
84
- # 升版本走分支 + PR；合并后在 main 最新提交上打注记 tag（正文就是 Release body）
85
- git tag -a v0.2.0 -m "release: v0.2.0
86
- <变更说明>"
87
- git push origin v0.2.0
88
- ```
69
+ - **canonical 与 CLI lock 只读**：`~/.agents/skills`、`~/.agents/.skill-lock.json` 的增删改只经 `skills` CLI，插件不直接写、不克隆仓库、不代理来源。
70
+ - **只动自己的东西**：只处理本插件创建的 `managed` 链接，以及已记账的 `managed-external`；`real` 目录和 `foreign-link` 永不改写，删除前体检直接中止。
71
+ - **启停不改正文**：`mode` 只增删 DSH 侧链接，避免本地修改被下一次 `add` 覆盖。
72
+ - **可回滚**：删除进回收站（7 天）；更新前快照到 `backups/`，失败自动还原（接口另提供手动回滚）。
73
+ - **状态坏了就只读**：`state.json` 是坏 JSON 或版本未知时，插件降级为只读并让写接口返回 409，不猜结构、不自动修复。
74
+ - **不做任意路径**：请求里的目标一律走注册表反查，软链目标恒为 canonical 下同名目录。
89
75
 
90
- ## 数据位置
76
+ ## 数据与配置
91
77
 
92
78
  | 项 | 路径 | 归属 |
93
79
  | --- | --- | --- |
@@ -98,11 +84,15 @@ git push origin v0.2.0
98
84
  | 备份 / 回收站 | `$DSH_HOME/skills-console/{backups,trash}` | 本插件 |
99
85
  | 事件日志 | `$DSH_HOME/skills-console/dsh-skills-console.log` | 本插件（JSONL，1MB 滚动） |
100
86
 
101
- 环境变量：`DSH_SKILLS_CONSOLE_HOME`、`DSH_SKILLS_CONSOLE_CLI`、`DSH_SKILLS_CONSOLE_NPX_SPEC`、`DSH_SKILLS_CONSOLE_TIMEOUT_MS`、`GITHUB_TOKEN`/`GH_TOKEN`。
87
+ 环境变量：`DSH_SKILLS_CONSOLE_HOME`、`DSH_SKILLS_CONSOLE_CLI`、`DSH_SKILLS_CONSOLE_NPX_SPEC`、`DSH_SKILLS_CONSOLE_TIMEOUT_MS`、`GITHUB_TOKEN` / `GH_TOKEN`。
88
+
89
+ ## 开发与发布
90
+
91
+ 源码结构、测试策略与调试手段见 [docs/development.md](docs/development.md)（含本地 `link:` 验证与回退步骤）；发布流程与排障清单见 [docs/publishing.md](docs/publishing.md)。在本仓工作的 AI agent 请先读 [AGENTS.md](AGENTS.md)。
102
92
 
103
93
  ## 边界（明确不做）
104
94
 
105
- - 不做技能市场/搜索，不接管 CLI 已有的 agent 分发，不给 CLI 打补丁。
95
+ - 不做技能市场 / 搜索，不接管 CLI 已有的 Agent 分发，不给 CLI 打补丁。
106
96
  - 不编辑技能正文（`add` 会整份重建，本地改写必然被覆盖）。
107
97
  - 不做文件级差异预览：只给 commit 区间与受影响技能；要看具体行，终端跑 `git diff <from>..<to> -- <skillDir>`。
108
98
  - 不做跨机器同步，不落盘任何 token。