@caesarloo/dsh-skill-audit 0.1.0 → 0.1.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 (2) hide show
  1. package/README.md +128 -68
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,107 +1,167 @@
1
1
  # @caesarloo/dsh-skill-audit
2
2
 
3
- 让 **DSH 技能一改就自动被审核** 的插件：监听 `tools/post-execute`，在技能文件被 `write`/`edit`/shell 改动之后、或在 `dsh_config_git_backup` 的 `restore`/`backup` 之后，跑一遍技能审核，并把结论作为上下文回传给模型。同时注册 `skill_audit` 工具供按需调用。
3
+ [English](#english) | [中文](#中文)
4
4
 
5
- ## 为什么需要插件（而不是 hooks.json）
5
+ ---
6
6
 
7
- DSH 自带的 Claude Code 钩子桥接（`@deepseek-ai/dsh-hooks-claude-code`）通过 **`ctx.shell`** 执行钩子命令。当宿主没有可用的沙箱 runner 时（Windows 上 ACL 后端未挂载时的实测情形），执行器按设计 **fail-closed**：命令根本不会启动，会话日志里只留下
7
+ ## English
8
8
 
9
- ```
10
- hook/invoked PostToolUse ...
11
- hook/result decision=pass stderr=sandbox mode "workspace-write" is requested
12
- but no sandbox backend is usable on this host; refusing to run the command unconfined
13
- ```
9
+ A DeepSeek Harness plugin that **audits your skills the moment they change**: after a skill file is written or edited, or after skills are restored from a backup repository, it runs the skill audit and feeds the findings back to the model. It also registers a `skill_audit` tool for on-demand runs.
10
+
11
+ ### What it does
14
12
 
15
- —— 也就是说 `hooks.json` 配置得再正确也没用。同类第三方 hooks 插件（如 `dsh-hooks-plugin`、`dsh-plugin-hooks`）同样走 `ctx.shell`，会撞同一堵墙。
13
+ The audit rules live in the `skill-audit` skill's engine: frontmatter contract (`name` / `description` / `whenToUse` / `version`), script usability (UTF-8 BOM + parseable by Windows PowerShell 5.1), `SKILL.md` reference integrity, credential leakage, machine-specific paths and dangerous command patterns.
16
14
 
17
- 本插件在 **harness 进程内**用 `ctx.subprocess`（host 层）直接跑审核脚本，**不经过 `ctx.shell`**，因此不受沙箱策略限制；这也是官方对"没有 Claude Code 对应物的定制行为"给出的推荐形态。
15
+ - **Automatic** — audits after skill files are written or edited, and after `dsh_config_git_backup`'s `restore` / `backup`;
16
+ - **Speaks only when there is something to act on** — findings are injected as context only when `fail` / `warn` exist; a clean run stays silent and just writes a log;
17
+ - **Never blocks** — an audit cannot fail your tool call. The file is already written, so surfacing the problem to the model is the right move;
18
+ - **On demand** — the `skill_audit` tool.
18
19
 
19
- ## 安装
20
+ ### Install
21
+
22
+ Prerequisite: the `skill-audit` skill (the audit engine) must be installed — this plugin only triggers it and relays the results.
20
23
 
21
24
  ```sh
22
- # 从 npm（推荐）
23
25
  dsh plugin --profile web add @caesarloo/dsh-skill-audit
24
-
25
- # 本地开发（link 到工作副本）
26
- dsh plugin --profile web add C:\workspace\dsh-skill-audit
27
26
  ```
28
27
 
29
- 装完**重启 dsh**（bundle 层变更无 HMR；`dsh --profile web --dump-config` 应能看到 `id: tool-skill-audit`）。
28
+ Restart dsh afterwards (bundle-level change, not hot-reloaded). Verify:
30
29
 
31
- ## 前置
30
+ ```powershell
31
+ dsh --profile web --dump-config | Select-String tool-skill-audit
32
+ ```
33
+
34
+ ### Usage
32
35
 
33
- 审核逻辑不在本插件内（**单一真源**），默认调用：
36
+ Nothing to do after installing — audits run automatically whenever you change skills. To re-check on demand:
34
37
 
35
38
  ```
36
- <DSH_HOME>/skills/skill-audit/scripts/audit-skills.ps1
39
+ skill_audit() # audit every skill
40
+ skill_audit({ skill: 'a,b' }) # audit specific skills (comma separated)
37
41
  ```
38
42
 
39
- 即 `skill-audit` 技能的静态审核引擎（frontmatter 契约、脚本 UTF-8 BOM + PowerShell 5.1 可解析、SKILL.md 引用完整性、凭据泄漏、机器专属路径、危险命令）。该脚本不存在时：`skill_audit` 工具返回明确错误，自动触发**静默跳过**（不会因为审核引擎缺失而干扰正常写文件）。
40
-
41
- ## 配置
42
-
43
- ```yaml
44
- - insert:
45
- - id: tool-skill-audit
46
- name: '@caesarloo/dsh-skill-audit'
47
- config:
48
- skillsRoot: 'C:\Users\me\.dsh\skills' # 可选，缺省 <DSH_HOME>/skills
49
- auditScript: '...\audit-skills.ps1' # 可选，缺省 <skillsRoot>/skill-audit/scripts/audit-skills.ps1
50
- autoAudit: true # 可选，false = 只保留工具、不做自动触发
51
- powershell: 'C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe'
52
- timeoutMs: 120000 # 可选，单次审核超时
53
- maxContextChars: 2000 # 可选，回传上下文的字符上限
54
- ```
43
+ Trigger scope:
55
44
 
56
- 正常使用无需任何配置（路径从 `DSH_HOME` 推导）。
45
+ | Your action | Audit scope |
46
+ |---|---|
47
+ | `write` / `edit` on a skill file | that skill only (fast) |
48
+ | `dsh_config_git_backup` `restore` / `backup` | everything (bulk overwrite / pre-commit check) |
49
+ | a shell command rewriting the skills directory | everything |
57
50
 
58
- ## 自动触发规则
51
+ Reporting is tiered by scenario:
59
52
 
60
- | 工具调用 | 审核范围 |
61
- | --- | --- |
62
- | **写入类**文件工具（`write`/`edit`/`multi_edit`/`notebook_edit`/`apply_patch` …），目标路径落在 `<skillsRoot>/<技能>/` 下 | **只审该技能**（快，约 1 秒） |
63
- | 只读工具（`read`/`glob`/`grep`） | **不触发** —— 它们同样携带 `file_path` 却不修改内容；不加这条白名单，每读一次技能文件就会注入一次审核上下文 |
64
- | `dsh_config_git_backup`，`mode` 为 `restore` 或 `backup` | **全量**（整批覆盖 / 入库前体检） |
65
- | `pwsh` / `bash` 等 shell，命令行同时含 `skills` 与写操作迹象（`Set-Content`/`Copy-Item`/`Remove-Item`/`robocopy`/`git checkout` …） | **全量**（shell 里改了哪个文件无法精确判定，宁可全量） |
66
- | 其它工具、或路径不在技能目录内 | 不触发，静默 `next()` |
53
+ - single-skill edit → lists `fail` and `warn` in detail;
54
+ - bulk scope → lists only `fail`, with `warn` collapsed into one summary line;
55
+ - bulk scope with no `fail` → **completely silent** (background noise should not interrupt you).
67
56
 
68
- - 审核在 **`tools/post-execute`（写入之后）** 执行，因此审的是**新内容**（对比：`pre-execute` 时文件还没落盘，只能审到旧版本）。
69
- - **上下文分级**：定向单技能（`write`/`edit`）时详列 `fail` + `warn`；**全量场景**（restore/backup、shell 批量改写）只详列 `fail`，`warn` 压成一行汇总 —— 本机 11 个技能里 9 个各有 1~3 条元数据类 warn，逐条列出会把上下文挤爆并失去焦点。**全量且只有 warn 时完全不注入**（背景噪音不该打断写入）；全部通过时同样保持安静，只写 `<DSH_HOME>/vet/skill-audits/`。
70
- - 自动触发**永远不会**影响工具调用本身：任何异常都被吞掉并委托 `next()`。
57
+ Logs go to `<DSH_HOME>/vet/skill-audits/` (`latest.json` plus timestamped files, last 40 kept).
71
58
 
72
- ## `skill_audit` 工具
59
+ ### Configuration
73
60
 
74
- ```
75
- skill_audit() # 审计 skillsRoot 下全部技能
76
- skill_audit({ skill: 'a,b' }) # 只审指定技能（逗号分隔）
77
- ```
61
+ Usually none. To customize, add `config` to the entry in the profile's `cordis.patch.yml`:
62
+
63
+ | Key | Default | Meaning |
64
+ |---|---|---|
65
+ | `skillsRoot` | `<DSH_HOME>/skills` | Skills root directory |
66
+ | `auditScript` | `<skillsRoot>/skill-audit/scripts/audit-skills.ps1` | Audit engine script |
67
+ | `autoAudit` | `true` | `false` disables automatic audits (the `skill_audit` tool stays available) |
68
+ | `powershell` | Windows PowerShell / `pwsh` | PowerShell executable |
69
+ | `timeoutMs` | `120000` | Per-audit timeout |
70
+ | `maxContextChars` | `2000` | Cap on injected context length |
71
+
72
+ ### Dependencies
73
+
74
+ `@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-subprocess` and `@deepseek-ai/dsh-llm` are declared as **optional peerDependencies** and provided by the host; the package bundles none of them. This is deliberate: a second copy inside the profile would create two module instances and break tool registration. `dsh-llm` is used only to build the context message — if it is unavailable, the audit still runs and only the context injection is skipped.
75
+
76
+ ### Boundaries
77
+
78
+ - Does not implement the audit rules themselves (they live in the `skill-audit` skill);
79
+ - Does not rewrite tool input and never blocks a tool call;
80
+ - Does not hook non-tool events (`SessionStart` / `Stop`);
81
+ - Does not watch the skills directory — it triggers after tool calls only.
82
+
83
+ ### License
84
+
85
+ MIT
86
+
87
+ ---
88
+
89
+ ## 中文
78
90
 
79
- 返回逐技能的通过/注意/失败与逐条发现，并把同样的 JSON 结论写入 `<DSH_HOME>/vet/skill-audits/`（`latest.json` + 时间戳档，保留最近 40 份）。
91
+ 让 **DSH 技能一改就自动被审核** 的插件：技能文件被改动、或技能从备份仓库恢复之后，自动跑一遍技能审核，并把结论回传给模型；另提供 `skill_audit` 工具供随时复验。
80
92
 
81
- ## 依赖约定
93
+ ### 功能
82
94
 
83
- `@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-subprocess`、`@deepseek-ai/dsh-llm` 一律声明为 **optional peerDependencies**，由宿主提供，本包不打包它们。这是刻意的：这两个包若与主包各装一份，会形成**两个模块实例**，而 `TOOL_RUNTIME_SCHEDULER` 是 `Symbol()`（非 `Symbol.for`），跨实例注册失败会导致**所有工具调用崩**。`dsh-llm` 仅用于构造回传上下文消息，缺失时插件降级为"审核照跑、不注入上下文"。
95
+ 审核规则由 `skill-audit` 技能的引擎执行，包含：frontmatter 契约（`name` / `description` / `whenToUse` / `version`）、技能内脚本的可用性（UTF-8 BOM + Windows PowerShell 5.1 可解析）、`SKILL.md` 引用完整性、凭据泄漏、机器专属路径与危险命令模式。
84
96
 
85
- ## 开发
97
+ - **自动** —— 技能文件被写入 / 编辑之后，或 `dsh_config_git_backup` 的 `restore` / `backup` 之后自动审核；
98
+ - **有发现才提示** —— 只在存在 `fail` / `warn` 时把结论作为上下文回传给模型；全部通过时保持安静，只写审核日志；
99
+ - **不阻塞** —— 审核不会让你的工具调用失败。文件已经写入，把问题摆到模型面前才是正确做法；
100
+ - **可主动调用** —— `skill_audit` 工具。
101
+
102
+ ### 安装
103
+
104
+ 前置：本机已安装 `skill-audit` 技能（审核引擎在它里面，插件只负责触发与回传）。
86
105
 
87
106
  ```sh
88
- pnpm install
89
- pnpm run build # tsc → dist/
90
- pnpm test # node test/smoke.mjs：假 ctx + 真实审核引擎，端到端
91
- pnpm run typecheck
107
+ dsh plugin --profile web add @caesarloo/dsh-skill-audit
108
+ ```
109
+
110
+ 装完**重启 dsh**（插件属于 bundle 层变更，不随热重载生效）。验证：
111
+
112
+ ```powershell
113
+ dsh --profile web --dump-config | Select-String tool-skill-audit
114
+ ```
115
+
116
+ ### 使用
117
+
118
+ 装好之后**无需任何操作**——改动技能时会自动审核。需要主动复验时调用工具：
119
+
92
120
  ```
121
+ skill_audit() # 审核全部技能
122
+ skill_audit({ skill: 'a,b' }) # 只审指定技能（逗号分隔）
123
+ ```
124
+
125
+ 自动审核的触发范围：
126
+
127
+ | 你的操作 | 审核范围 |
128
+ |---|---|
129
+ | 用 `write` / `edit` 改某个技能的文件 | 只审**该技能**（快） |
130
+ | `dsh_config_git_backup` 的 `restore` / `backup` | **全量**（整批覆盖 / 入库前体检） |
131
+ | 用 shell 命令改写技能目录 | **全量** |
132
+
133
+ 提示强度按场景分级：
134
+
135
+ - 定向单技能改动 → 详列 `fail` 与 `warn`；
136
+ - 全量场景 → 只详列 `fail`，`warn` 压成一行汇总；
137
+ - 全量且只有 `warn` → **完全不提示**（背景噪音不打断你的操作）。
138
+
139
+ 审核日志写在 `<DSH_HOME>/vet/skill-audits/`（`latest.json` 加时间戳档，保留最近 40 份）。
140
+
141
+ ### 配置
142
+
143
+ 一般无需配置。需要定制时在 profile 的 `cordis.patch.yml` 里给该条目加 `config`：
144
+
145
+ | 配置键 | 缺省值 | 含义 |
146
+ |---|---|---|
147
+ | `skillsRoot` | `<DSH_HOME>/skills` | 技能根目录 |
148
+ | `auditScript` | `<skillsRoot>/skill-audit/scripts/audit-skills.ps1` | 审核引擎脚本 |
149
+ | `autoAudit` | `true` | `false` 关闭自动审核（`skill_audit` 工具仍可用） |
150
+ | `powershell` | Windows PowerShell / `pwsh` | PowerShell 可执行文件 |
151
+ | `timeoutMs` | `120000` | 单次审核超时 |
152
+ | `maxContextChars` | `2000` | 回传上下文的字符上限 |
93
153
 
94
- 冒烟测试在临时目录里造两个技能（一个只有 warn、一个含 fail），用假 `ctx`（`tools.register` 捕获工具、`subprocess.spawn` 委托 `node:child_process`、`on()` 捕获 waterfall 处理器）驱动真实实现，断言：工具注册、`planAudit` 的六类范围判定、`parseReport` 的容错、定向/全量审核输出、上下文注入与静默路径、引擎缺失时的 fail-closed。
154
+ ### 依赖约定
95
155
 
96
- > `SMOKE_PLUGIN_DIST` 可指向另一份构建产物，但该副本必须位于**能解析 `@deepseek-ai/dsh-tools` 的树**中；不要指向 dsh 安装树（`~/.dsh/profiles/web/node_modules/...`）——裸 node 在那里会解析到版本不匹配的 `dsh-llm` 副本。
156
+ `@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-subprocess`、`@deepseek-ai/dsh-llm` 声明为 **optional peerDependencies**，由宿主提供，本包不打包。这是刻意的：它们若与主包各装一份会形成两个模块实例，导致工具注册失败。`dsh-llm` 仅用于构造回传消息，缺失时插件降级为「审核照跑、不注入上下文」。
97
157
 
98
- ## 边界（明确不做）
158
+ ### 边界（明确不做）
99
159
 
100
- - 不实现审核规则本身（在 `skill-audit` 技能的脚本里，此处只负责触发与回传）；
101
- - 不改写工具输入、不阻塞工具调用（`fail` 也只在上下文里告知模型）；
102
- - 不覆盖 `SessionStart`/`Stop` 等非工具事件；
103
- - 不做技能目录的文件系统监视（`dsh-skill-filesystem` 已有 watcher；本插件只在工具调用后触发）。
160
+ - 不实现审核规则本身（规则在 `skill-audit` 技能里）；
161
+ - 不改写工具输入、不阻塞工具调用；
162
+ - 不覆盖 `SessionStart` / `Stop` 等非工具事件；
163
+ - 不监视技能目录的文件变化（只在工具调用后触发）。
104
164
 
105
- ## License
165
+ ### License
106
166
 
107
167
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@caesarloo/dsh-skill-audit",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Audit DSH skills automatically: a host-layer tools/post-execute plugin that runs the skill-audit engine after skill files change (write/edit/shell) or after a dsh_config_git_backup restore, feeding findings back to the model as context; also registers the skill_audit tool.",
5
5
  "keywords": [
6
6
  "dsh",