dsh-brain/docs/skills.md

72 lines
4.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 技能同步与管理
> 云端技能中心与本机技能目录的双向同步、内置技能管理、按软件来源的技能树。
---
## 技能同步
自 0.3.0 起,插件在记忆之外还双向同步技能:云端技能中心是总汇,本机
技能目录(默认 `$DSH_HOME/skills`)是工作副本,本地的浏览、启停、分类
仍归 DSH 技能管理器。插件启动 5 秒后首跑,之后每 15 分钟对账一次;
结果与冲突列表见 `GET /cloud-memory/status` 的 `skills` 字段,聊天里
也可以用 `skill_list` 工具查看云端清单。
- **下行**:云端技能按平台自己的规矩落地——先验整包清单哈希、再逐
文件验 sha256,原子写入,并留下 `.manifest.json` 交付记录;云端标
记了「脚本已变更待确认」的包不会自动安装,先在看板里确认。
- **上行**:本地原创技能(管理器安装、导入或手写的)自动发布到云
端;之后的修改以新修订发布,带 `expected_revision` 守卫,云端被
别人先改过就报冲突、不强行覆盖。
防事故的规矩:先比内容,本地与云端逐字节一致时直接补交付记录,不传
不覆盖;内容不同时按时间自动取较新的一边——云端 `updated_at` 更新就
先备份本地再覆盖,本地文件 mtime 更新就发布新修订;只有时间相同或缺
失时才报冲突(`locally_modified` / `name_collision` / `cloud_newer`),
等面板里逐项确认。本地删除不删云端,且同版本不会被重新拉回(云端出
了新版才会再下来)。面板里可逐项处理,也可用「全部保留本地 / 全部采用
云端」批量处理(有二次确认,失败项会逐条汇总)。云端只接受固定布局(根目录只有 `SKILL.md`,
其余文件进 `references/`、`scripts/`、`assets/`,扩展名有白名单,
单文件 ≤512 KiB、整包 ≤2 MiB、≤100 个文件),不符合的本地技能报
`unsupported_layout`,不会为了迁就而裁剪文件。
验证:`node verify-skills-sync.mjs`(对本地 stub 技能中心跑通
下行安装、上行发布与修订、按时间自动上行/下行、内容一致自动认领、
同名同时间保留冲突、脚本待审、布局拒绝、删除不传播全流程)。
## 技能管理(内置)
自 0.4.0 起,常用的本地管理也长在插件里,页面在 `/cloud-memory/skills`
(配置页有链接进入):
- **列表**:本机全部技能,标注来源(云端交付 / 本地已传云端 / 本地)
与云端修订号;
- **启停**:停用是把技能文件夹挪到 `$DSH_HOME/skills-disabled/` 暂存
——DSH 看不见它,自然不会加载;启用再挪回来。不碰 DSH 内部机制,
可靠且可逆。同步引擎认识暂存区:停用的云端技能不会被拉回技能目
录,云端出了新版会在暂存区里原地更新;
- **删除**:真删,文件夹直接删除、不可恢复(页面上会先弹确认)。
只删本地:云端副本不动,删掉的同版本也不会被同步重新拉回来;
- **从 git 安装**:粘贴 https:// 或 file:// 仓库地址,浅克隆后把仓
库里所有带 `SKILL.md` 的文件夹装进技能目录;不执行仓库里的任何
代码,同名技能跳过不覆盖。
范围就到 DSH 技能目录这一处:技能市场的发现中心、扫描其它工具
(Codex、Cursor 等)的技能目录不在内置范围——还需要那些的话继续
留着第三方管理器,两边不冲突;不需要的话现在可以卸掉它了。
验证:`node verify-skill-admin.mjs`(列表与来源判定、启停、真删、
git 安装与同名跳过、以及停用技能与同步引擎的配合共 15 项)。
### 技能来源树
「技能管理」按软件来源分组(DSH / 公共 Agent / Codex / WorkBuddy / Claude Code / OpenCode),
每个来源下是分类,分类下是技能:
- 分类只记在 `$DSH_HOME/cloud-memory-skill-groups.json` 里,**不移动文件**;删除分类只是把技能放回「未分类」。
- 只有 DSH 来源的开关是真的(目录移入/移出 `skills-disabled`,新会话生效);其他软件的目录本卡只读,开关标记为「仅本卡」。
- 来源行提供「+ 新建分类」「打开目录」「来源开关」;分类行提供「+ 加入技能 / 改名 / 删除 / 分类开关」;技能行提供详情、启停、卸载。
- 预览(真实数据、光照/暗色):`node preview-card.mjs` 生成 `_preview/skill-tree*.png`。