dsh-skill-dossier

Readme

# dsh-skill-dossier

[English](./README.en.md) · 中文

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

给 [DeepSeek Harness](https://github.com/deepseek-ai/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/`。不去用就只是一块没人点的面板，不影响技能与档案。

### 数据从哪来

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

```md
---
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` 跑过一次即可）。

```sh
# 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` 取详细档案——不需要再做一层词法匹配（早期版本的 `skill_match` / `skill_route` / `skill_usage` / `skill_eval` 已移除：DSH 把技能目录（名称+描述）直接放进系统提示，由模型自己选，插件再叠一层词法路由没有实测收益——调用分布显示它几乎从未被模型选中。数据仍照记，只是不再单开面板与工具。）

## 配置

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

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

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

## 从源码重建

```sh
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` 防漂移）。

## 平台支持

Windows / Linux / macOS。文件生命周期操作按平台生成 pwsh（Windows，用原生 `MoveFileExW`）或 bash（POSIX）命令；`tests/windows-runtime.spec.ts` 在 Windows runner 上真机调用验证。

## 已知边界

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

## 许可

MIT