dsh-skill-manager

DeepSeek Harness 原生技能管理插件，基于 TypeScript 与 Cordis 运行。插件提供技能使用追踪、反馈归因、质量审计，以及带安全门禁的自动维护闭环。

默认运行在 read-only 模式，只记录和分析，不修改技能文件。只有显式启用 writeMode: automatic 后，插件才会在快照、静态校验、双阶段模型复审和原子写事务保护下更新技能。

组成

packages/
├─ engine/  @skill-ops/engine       评分、相似度、描述、反馈与变更门禁
├─ dsh/     @skill-ops/dsh          DSH host 插件、命令、工具与维护协调器
└─ client/  @skill-ops/dsh-client   Web 工具卡片

overlays/
├─ skill-ops.cordis.yml             默认只读配置
└─ skill-ops.automatic.example.yml  automatic 配置示例

公开 npm 包名、Cordis 条目名和命令前缀继续使用 skill-ops；dsh-skill-manager 是该插件工作区的名称。

能力

运行时追踪

• 模型通过 DSH skill 工具成功加载技能后，累计使用次数和使用间隔。
• 用户通过 /name 手势调用技能时，同样记录使用。
• 将同一 turn 中已加载的技能与后续 assistant 消息建立确定性归因。
• 将逐消息反馈映射为 correction、praise、clarification 信号；反馈修改或删除时撤销旧计数。
• 广播 skill-ops/usage 与 skill-ops/signal Cordis 事件。

审计与查询

• 混合评分排行：频率、新鲜度和重要性。
• TF-IDF 重复技能候选。
• 描述质量、kebab-case 名称和 DSH frontmatter 调用控制审计。
• 渐进遗忘候选；当前只提供建议，不执行压缩或删除。
• automatic 操作历史、门禁、快照和错误查询。

automatic 维护

• merge：根据安全条件执行 keep、specialize 或 composite。
• optimize-instructions：使用尚未消费的 correction 反馈优化指令正文。
• repair-descriptions：从正文确定性修复缺失或过弱的 description。
• 每个 Agent 空闲窗口最多应用一个需要模型的操作；没有当前 Agent 模型时只排队。

命令与模型工具

入口	用途
/skill-ops status [n]	查看技能评分、使用和反馈统计
/skill-ops duplicates [threshold]	查看疑似重复技能
/skill-ops forget	查看只读遗忘候选
/skill-ops descriptions	审计描述质量和不可见技能文件
/skill-ops names	审计名称与调用控制键
/skill-ops operations [n|id]	查看 automatic 操作
/skill-ops run <all|merge|optimize|descriptions>	立即触发一次扫描，仅 automatic
/skill-ops retry <id>	重试待定或失败操作，仅 automatic
/skill-ops rollback <id>	按快照显式回滚已应用操作
skill_ops	只读模型查询工具
skill_ops_maintain	仅 automatic 注册，只允许 run 和 retry

写入安全

• 模型只能返回固定 JSON 槽位中的策略、描述和正文，不能指定文件路径。
• 生成与独立复审使用同一 Agent 路由的两个独立上下文，置信度均须不低于 0.90。
• automatic 根必须存在、可读写、不是符号链接或 junction，且彼此不重叠。
• 每个根使用跨进程锁，并在写入前创建完整快照、逐文件 SHA-256 manifest 和 journal。
• 候选先在 staging 完整副本中校验名称、frontmatter、正文、调用控制、资源闭包和路径边界。
• 提交只处理实际差异；新技能完整出现后才退役合并源，现有 SKILL.md 通过同目录临时文件和 rename 原子替换。
• 中断恢复和显式回滚复用已验证快照；提交后的完整活动根必须匹配 afterDigest。

详细设计见架构说明。

接入 DeepSeek Harness

1. 前置条件

• Node.js 22 或更高版本。
• 一个已构建的 DeepSeek Harness checkout。
• DSH 组合提供 storage-domain、skill、tool-skill、commands 和 tools；启用反馈归因时还需要 message-feedback。

开发脚本默认从 D:\deepseek-harness 读取 Harness，也可覆盖：

$env:DSH_CHECKOUT = 'D:\path\to\deepseek-harness'

2. 构建

node scripts/build.mjs

3. 让 DSH 解析工作区包

将三个包链接到 profile 的依赖回退目录：

$pluginRoot = (Resolve-Path '.').Path
$scopeRoot = Join-Path $env:DSH_HOME 'profiles\node_modules\@skill-ops'
New-Item -ItemType Directory -Force -Path $scopeRoot
cmd /c mklink /J "$scopeRoot\dsh" "$pluginRoot\packages\dsh"
cmd /c mklink /J "$scopeRoot\engine" "$pluginRoot\packages\engine"
cmd /c mklink /J "$scopeRoot\dsh-client" "$pluginRoot\packages\client"

也可以将包链接到 Harness checkout 的 node_modules/@skill-ops/。

4. 挂载只读 overlay

dsh web --patch "$PWD/overlays/skill-ops.cordis.yml"

需要持久化时，将 overlay 的 insert 条目合并到 $DSH_HOME/cordis.patch.yml 或对应 profile 的 cordis.patch.yml。

5. 验证

/skill-ops help
/skill-ops status 10
/skill-ops descriptions

让 Agent 加载任一技能后再次执行 status，应能看到 usage 更新。Web 侧加载 @skill-ops/dsh-client 后会显示专用工具卡片；未加载 client 不影响 host 功能。

配置

默认只读配置见 skill-ops.cordis.yml：

- id: skill-ops
  name: '@skill-ops/dsh'
  config:
    trackingEnabled: true
    feedbackAttributionEnabled: true
    pairThreshold: 0.3
    writeMode: read-only
    skillRoots:
      - 'D:/path/to/skills'

启用 automatic 前，从示例复制配置并核对技能根：

writeMode: automatic
automaticActions:
  - merge
  - optimize-instructions
  - repair-descriptions
correctionThreshold: 3
correctionAgeDays: 7
snapshotRetentionDays: 30
# 无反馈消息的归因记录保留天数（默认 90；有反馈的归因不受影响）
attributionRetentionDays: 90
skillRoots:
  - 'D:/path/to/skills'

正式 overlay 始终保持 read-only。

开发与验证

node scripts/typecheck.mjs
node scripts/test.mjs
node scripts/test.mjs --vitest
node scripts/integration.mjs
node scripts/build.mjs

• typecheck.mjs 检查 engine、host 和 client 三个包。
• test.mjs 默认使用 Node 原生 TypeScript 类型剥离运行测试；--vitest 使用真实 Vitest。
• integration.mjs 在进程内启动真实 Cordis/DSH 组合，使用隔离磁盘目录和脚本 LLM，不访问外部 API。
• 发布门禁可运行 pnpm run release。

文档

• 架构说明：运行模式、维护策略、事务、恢复和存储接口。
• 真实环境测试指南：read-only 与 automatic 验收流程。
• 自动化测试审查：覆盖范围和当前门禁结果。
• CHANGELOG：版本变更。

已知边界

• message-feedback 没有变更事件，反馈归因在后续 turn/end 对账。
• 无反馈的消息归因记录超过 attributionRetentionDays（默认 90 天）会被清理；有反馈的归因 与优化证据永久保留。超过保留期后才出现的反馈将不再归因到技能（防止 attribution 表无界增长）。
• 文件级描述审计依赖 skillRoots，并镜像 DSH skill-filesystem 的浅层发现规则。
• forget 当前只报告候选，不执行智能遗忘。
• 浏览器包已覆盖构建、入口和摘要逻辑，但仍需真实浏览器视觉与交互回归。
• 集成测试使用脚本 LLM；外部模型的结构化输出稳定性需要按 provider 单独验证。

发布

工作区包含三个 MIT 许可的 npm 包：@skill-ops/engine、@skill-ops/dsh 和 @skill-ops/dsh-client。

# 一次性：登录 npm（发布一律走官方 registry，脚本已强制）
npm login

# 预览（不发布、不联网）
node scripts/publish.mjs --dry-run all

# 按 engine → dsh → client 顺序发布
node scripts/publish.mjs all

发布辅助脚本（scripts/publish.mjs）负责全部细节：

• 顺序强制：发布 dsh 前校验 @skill-ops/engine 同版本已在 registry（E404 直接阻止； 校验网络失败只警告不阻止；--skip-engine-check 可显式跳过）。
• 源文件零触碰：dsh 对 engine 的 workspace:^ 协议无法被 npm/pnpm 直接发布， 脚本把 lib 与改写后的 package.json 复制到独立临时目录再发布——源 manifest 从头到尾 不变，进程被任何方式中断（Ctrl+C、断电）都不会在仓库里留下残留（engine → ^0.3.1 的替换只发生在临时副本中）。不要手工改 manifest 或改用 npm publish（npm 不理解 workspace: 协议，而 pnpm 要求依赖经过 install 才能解析该协议，本仓库开发流程 不运行 pnpm install）。
• 网络重试：publish 失败自动重试 3 次（10s/20s 退避），应对 npmjs.org 偶发连接中断。 未登录时的 PUT 404 属于认证问题，不会因重试成功，请先 npm login； pnpm 连续 3 次无法启动时给出安装诊断。
• registry 固定：强制 --registry=https://registry.npmjs.org（npmmirror 是只读镜像， 不接受 publish）。国内网络需要 registry 命令时（如查看包版本）可临时使用 --registry=https://registry.npmmirror.com，不影响发布。

@skill-ops/dsh 与 @skill-ops/dsh-client 的 @deepseek-ai/* peer 依赖为 optional；实际运行时由 DeepSeek Harness 提供，消费者安装不会因 peer 缺失失败。

lockfile 说明：pnpm-lock.yaml 锁定直接依赖（yaml/zod 与 workspace 链接）。DSH 的 @deepseek-ai/* 是 optional peer，其 registry 上的 rc 版本集残缺（dsh-type-meta 等从未发布）， 完整 pnpm install 会因上游 404 失败——本项目的构建/测试流程不依赖 pnpm install （DSH 依赖由 checkout junction 提供，见「接入 DeepSeek Harness」），CI 无需运行 install。