技能档案与汇报 JeffreySuen-x/dsh-skill-dossier

dsh-skill-dossier

English · 中文

你是不是下载过很多 skills，但到用的时候却总是缺漏？
你是不是坐拥几百种 skills，却忘了它们究竟是用来做什么的？

给 DeepSeek Harness（DSH）用的技能档案与工作汇报插件：把散在 ~/.dsh/skills、.dsh/skills、~/.agents/skills 里的技能收成一份可读、可核对、可保鲜的档案，并把每天的工程简报汇成日报/周报/月报。

一个包，三个板块：

| 板块 | 做什么 |
| 技能 | 浏览、搜索、按方向分类筛选（与档案页同轴）、看详情、一键把 /name 填进输入框；文件夹技能的停用（进 trash，可逆）· 重装 · 删除（一步到位，带二次确认） |
| 档案 | 每个技能的档案：方向（10 类）、使用范围、能力边界、应用场景、来源标注、调用统计、实测成败、目录 token 成本、保鲜复审、评测结论 |
| 汇报 | 只读三个视图：日报（明细）、周报（本周一~周日）、月报（当月）。周报/月报 = 贡献图（一格一天，越深＝当天做得越多）+ 每个项目四行，数据源是 reporter/brief/YYYY-MM-DD.md |

汇报

把工作区里散落的每日简报读成三个视图：日报 / 周报 / 月报。

它只读——不改你的任何文件、不留状态、不需要调度器。插件不做复盘、不做导出、不做运行记录：复盘是 agent 该干的事（让它直接读 brief），导出是复制粘贴能替代的，运行记录是给一个不存在的调度器准备的。三者都要额外状态、额外写盘、额外失败面，而日报与区间汇总本身只需要读。

汇报是可选模块：dataRoot / briefDir 可配置，默认读工作区里的 reporter/brief/。不去用就只是一块没人点的面板，不影响技能与档案。

数据从哪来

//YYYY-MM-DD.md，由 brief skill 负责写。每个 ## 项目名 一个区块，字段名就是解析契约，五个名字不能改：

date: 2026-09-11

项目名

- 作用：一句话说明它是什么
- 实现：技术形态
- 今日进度：
- 一条现状（覆盖写，不是追加流水）
- 待办：
- 最多 3 条
- 问题：
- 只写真卡点

日期取 frontmatter 的 date:，缺失时退回文件名。

三个视图

| 视图 | 区间 | 给什么 |
| 日报 | 今天；今天没有简报就回退到最近有数据的一天 | 每个项目的完整明细：作用 / 实现 / 当天全部进度条目 / 待办 / 问题，外加一行统计（N 个项目 · N 条进度 · N 条待办 · N 条问题） |
| 周报 | 本周一 ~ 周日；本周无数据就回退到最近有数据的那一周 | 贡献图 + 每个项目四行 |
| 月报 | 当月 1 号 ~ 今天 | 同上，横轴为整月，而不是挤在一周里 |

回退会明说：用到回退时会标出数据实际来自哪一天 / 哪一周，不会假装今天有记录。

贡献图怎么读

一格一天，颜色越深 ＝ 那天做得越多。

- 深浅口径 = 当天所有项目的进度条目数合计，四档：≤9 / ≤29 / ≤59 / >59
- 底色取 DSH 原生蓝令牌（--dsw-alias-state-business-primary），用 color-mix 与背景混合出四档
- 悬停能看到那天涉及哪些项目
- 未来的日子不画——那不是「没记录」，是「还没到」
- 区间里没写简报的日历日照样占一格，但是空白：空白 = 那天没写，不是读取失败

为什么区间视图只有四行

作用：这个项目是什么进度：最后一天写下的那句现状待办：最后一天记的待办难点：最后一天记的问题

取「最后一天」而不是「区间内所有」，是刻意的：简报里的 今日进度 本身就是覆盖写的现状，所以区间视图回答的是「这些项目现在各自到哪了」，不是「这周做了什么」——后者翻日报。

为什么是「档案」

建档的目的只有一个：让 AI 和人明白现有 skill 是干什么的。

技能目录里只有名称和描述，看不出边界、场景与新鲜度——人要靠翻文件，模型只能靠猜。本插件给每个技能写一份档案，两边都读得懂：

- 人：档案页按方向筛选，每张卡写清使用范围 / 能力边界 / 应用场景 / 来源 / 调用记录
- AI：模型用 skill_dossier 工具按名读档案，在决定加载某个技能全文之前就知道它管什么、不管什么

同类插件大多止步于「列出来、开/关」。本插件多走一步：给技能建档，并且用实测而不是模型自述来核对它。

- 档案字段：方向 / 使用范围 / 能力边界 / 应用场景 / 来源（自创·外来·系统·未标注）/ 建档时间 / 复审时间 / 正文哈希
- 实测成败：监听 DSH 官方的 tools/result 事件，skill 工具加载成功记 ✅、失败记 ❌ 并留下错误原因——不是「模型说它有用」，而是「它到底跑起来没有」
- 目录成本：估算每个技能名称+描述常驻系统提示的 ≈token 数，回答「谁最占上下文」
- 保鲜复审：按「易变方向 + 长期未用 + 久未复审」排序，直接告诉模型或人「该复审哪几个」

安装

前置：Node ^22.19.0 || >=24.0.0，已装 DSH（npx @deepseek-ai/dsh web 跑过一次即可）。

npm
dsh plugin --profile web add dsh-skill-dossier

GitHub
dsh plugin --profile web add github:JeffreySuen-x/dsh-skill-dossier

本地目录（开发用）
dsh plugin --profile web add link:/绝对路径/dsh-skill-dossier

本仓库已提交 lib/ 构建产物，git 安装即装即用，不需要授权构建脚本。

模型侧工具

| 工具 | 作用 |
| skill_dossier | 读某个技能的档案（方向/使用范围/能力边界/应用场景/调用与实测），加载全文前先判断合不合适 |
| skill_archive | 为技能写档案（方向/使用范围/能力边界/应用场景/来源） |
| skill_review | 列出待复审技能（保鲜信号排序） |

读档案是按名读的：模型在技能目录里拿到名字，再用 skill_dossier 取详细档案，不需要插件再做一层词法匹配——DSH 已经把技能目录（名称+描述）直接放进系统提示，由模型自己选。

配置

插件 config 全部有默认值，不配置 = 旧行为。写在 profile 的 cordis.patch.yml 里按 id: skill-dossier 覆盖：

- id: skill-dossier
config:
report:
dataRoot: reporter # 汇报数据根目录 briefDir: brief # 每日简报目录

注意：DSH 的 patch 层是整体替换 config 而不是合并，所以覆盖时请把要改的键写全（未写的键会走代码里的默认值）。

从源码重建

pnpm install # 拉构建工具 + 类型依赖（@deepseek-ai/* 为公开包）
pnpm run build # tsc 产出 lib/types + tsdown 打包 lib/index.js、lib/client.js
pnpm run test # 单元 + 集成测试
node qa/gates.mjs # test / typecheck / build / pack 四闸

改完 src/ 后运行 pnpm run build 并提交 lib/，保证仓库自洽（CI 用 git diff --exit-code -- lib 防漂移）。

平台支持

macOS / Linux。文件生命周期操作生成 bash/POSIX 命令，CI 在 macOS 与 Ubuntu × Node 22/24 上跑全套闸门。

不支持 Windows。 2026-09-17 明确撤除：这条支线（pwsh 命令、MoveFileExW 原生移动）从未在真机上被验证过，却让 CI 长期挂着两条红腿——而一个常红的门会吃掉它后面所有门的信号（当时真实的失败藏在它后面 5 天没人看见）。要恢复 Windows 支持，先准备真机验证，别只把分支加回来。

已知边界

- 仅 web profile：host 半硬依赖 webServer 服务，headless 装不了。
- 调用统计是观察数据：只统计插件运行期间发生的调用，历史调用无法回溯补记。埋点写盘失败不会打断技能本身，但不再静默——面板顶部会显示「调用统计写盘失败」及原因。
- 删除是两步的封装，不是第二条路径：先移入 trash、再递归删除，两步各自的路径校验与失败回滚都复用；rm 失败时技能还留在 trash 里，仍可重装。非文件系统技能拒绝删除。
- 生命周期移动要求同文件系统：技能条目与 trash 目录跨挂载点时会在改文件前安全拒绝，不做非原子的 copy-delete。
- 平台支持面：macOS / Linux（见上节，Windows 已撤除）；CI 的全套闸门只有在 GitHub Actions 真绿之后才算「实跑通过」。

许可

MIT