@caesarloo/dsh-skill-audit 0.1.0 → 0.1.1

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 +45 -71
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,106 +1,80 @@
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
+ 让 **DSH 技能一改就自动被审核** 的插件：技能文件被改动、或技能从备份仓库恢复之后，自动跑一遍技能审核，并把结论回传给模型；另提供 `skill_audit` 工具供随时复验。
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
+ 审核内容由 `skill-audit` 技能的引擎执行，包含：frontmatter 契约（`name`/`description`/`whenToUse`/`version`）、技能内脚本的可用性（UTF-8 BOM + PowerShell 5.1 可解析）、`SKILL.md` 引用完整性、凭据泄漏、机器专属路径与危险命令模式。
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
- ```
14
-
15
- —— 也就是说 `hooks.json` 配置得再正确也没用。同类第三方 hooks 插件（如 `dsh-hooks-plugin`、`dsh-plugin-hooks`）同样走 `ctx.shell`，会撞同一堵墙。
16
-
17
- 本插件在 **harness 进程内**用 `ctx.subprocess`（host 层）直接跑审核脚本，**不经过 `ctx.shell`**，因此不受沙箱策略限制；这也是官方对"没有 Claude Code 对应物的定制行为"给出的推荐形态。
9
+ - **自动**：技能被写入/编辑、或 `dsh_config_git_backup` 的 `restore`/`backup` 之后自动审核；
10
+ - **有发现才提示**：只在存在 `fail`/`warn` 时把结论作为上下文回传给模型；全部通过时保持安静，只写审核日志；
11
+ - **不阻塞**：审核不会让工具调用失败——文件已经写入，把问题摆到模型面前才是正确做法；
12
+ - **可主动调用**：`skill_audit` 工具。
18
13
 
19
14
  ## 安装
20
15
 
16
+ 前置：本机已安装 `skill-audit` 技能（审核引擎在它里面，插件只负责触发与回传）。
17
+
21
18
  ```sh
22
- # 从 npm（推荐）
23
19
  dsh plugin --profile web add @caesarloo/dsh-skill-audit
24
-
25
- # 本地开发（link 到工作副本）
26
- dsh plugin --profile web add C:\workspace\dsh-skill-audit
27
20
  ```
28
21
 
29
- 装完**重启 dsh**（bundle 层变更无 HMR；`dsh --profile web --dump-config` 应能看到 `id: tool-skill-audit`）。
22
+ 装完**重启 dsh**（插件属于 bundle 层变更，不随热重载生效）。验证：
30
23
 
31
- ## 前置
32
-
33
- 审核逻辑不在本插件内（**单一真源**），默认调用：
34
-
35
- ```
36
- <DSH_HOME>/skills/skill-audit/scripts/audit-skills.ps1
24
+ ```powershell
25
+ dsh --profile web --dump-config | Select-String tool-skill-audit
37
26
  ```
38
27
 
39
- 即 `skill-audit` 技能的静态审核引擎（frontmatter 契约、脚本 UTF-8 BOM + PowerShell 5.1 可解析、SKILL.md 引用完整性、凭据泄漏、机器专属路径、危险命令）。该脚本不存在时：`skill_audit` 工具返回明确错误，自动触发**静默跳过**（不会因为审核引擎缺失而干扰正常写文件）。
28
+ ## 使用
40
29
 
41
- ## 配置
30
+ 装好之后**无需任何操作**——改动技能时自动审核。需要主动复验时调用工具：
42
31
 
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 # 可选，回传上下文的字符上限
32
+ ```
33
+ skill_audit() # 审核全部技能
34
+ skill_audit({ skill: 'a,b' }) # 只审指定技能（逗号分隔）
54
35
  ```
55
36
 
56
- 正常使用无需任何配置（路径从 `DSH_HOME` 推导）。
57
-
58
- ## 自动触发规则
59
-
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()` |
37
+ 自动审核的触发范围：
67
38
 
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()`。
39
+ | 你的操作 | 审核范围 |
40
+ |---|---|
41
+ | 用 `write` / `edit` 改某个技能的文件 | 只审**该技能**（快） |
42
+ | `dsh_config_git_backup` 的 `restore` / `backup` | **全量**（整批覆盖 / 入库前体检） |
43
+ | 用 shell 命令改写技能目录（命令行同时含 `skills` 与写操作） | **全量** |
71
44
 
72
- ## `skill_audit` 工具
45
+ 提示强度是按场景分级的：
73
46
 
74
- ```
75
- skill_audit() # 审计 skillsRoot 下全部技能
76
- skill_audit({ skill: 'a,b' }) # 只审指定技能（逗号分隔）
77
- ```
47
+ - 定向单技能改动 → 详列 `fail` 与 `warn`；
48
+ - 全量场景 → 只详列 `fail`，`warn` 压成一行汇总；
49
+ - 全量且只有 `warn` → **完全不提示**（背景噪音不打断你的操作）。
78
50
 
79
- 返回逐技能的通过/注意/失败与逐条发现，并把同样的 JSON 结论写入 `<DSH_HOME>/vet/skill-audits/`（`latest.json` + 时间戳档，保留最近 40 份）。
51
+ 审核日志写在 `<DSH_HOME>/vet/skill-audits/`（`latest.json` 加时间戳档，保留最近 40 份）。
80
52
 
81
- ## 依赖约定
82
-
83
- `@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-subprocess`、`@deepseek-ai/dsh-llm` 一律声明为 **optional peerDependencies**，由宿主提供，本包不打包它们。这是刻意的：这两个包若与主包各装一份，会形成**两个模块实例**，而 `TOOL_RUNTIME_SCHEDULER` 是 `Symbol()`（非 `Symbol.for`），跨实例注册失败会导致**所有工具调用崩**。`dsh-llm` 仅用于构造回传上下文消息，缺失时插件降级为"审核照跑、不注入上下文"。
53
+ ## 配置
84
54
 
85
- ## 开发
55
+ 一般无需配置。需要定制时在 profile 的 `cordis.patch.yml` 里给该条目加 `config`：
86
56
 
87
- ```sh
88
- pnpm install
89
- pnpm run build # tsc → dist/
90
- pnpm test # node test/smoke.mjs：假 ctx + 真实审核引擎，端到端
91
- pnpm run typecheck
57
+ ```yaml
58
+ - id: tool-skill-audit
59
+ config:
60
+ skillsRoot: '<技能根目录>' # 缺省 <DSH_HOME>/skills
61
+ auditScript: '<审核脚本路径>' # 缺省 <skillsRoot>/skill-audit/scripts/audit-skills.ps1
62
+ autoAudit: true # false = 关闭自动审核，只保留 skill_audit 工具
63
+ powershell: '<PowerShell 路径>' # 缺省 Windows 内置 powershell，其它平台 pwsh
64
+ timeoutMs: 120000 # 单次审核超时
65
+ maxContextChars: 2000 # 回传上下文的字符上限
92
66
  ```
93
67
 
94
- 冒烟测试在临时目录里造两个技能（一个只有 warn、一个含 fail），用假 `ctx`（`tools.register` 捕获工具、`subprocess.spawn` 委托 `node:child_process`、`on()` 捕获 waterfall 处理器）驱动真实实现，断言：工具注册、`planAudit` 的六类范围判定、`parseReport` 的容错、定向/全量审核输出、上下文注入与静默路径、引擎缺失时的 fail-closed。
68
+ ## 依赖约定
95
69
 
96
- > `SMOKE_PLUGIN_DIST` 可指向另一份构建产物，但该副本必须位于**能解析 `@deepseek-ai/dsh-tools` 的树**中；不要指向 dsh 安装树（`~/.dsh/profiles/web/node_modules/...`）——裸 node 在那里会解析到版本不匹配的 `dsh-llm` 副本。
70
+ `@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-subprocess`、`@deepseek-ai/dsh-llm` 声明为 **optional peerDependencies**，由宿主提供，本包不打包。这是刻意的：它们若与主包各装一份会形成两个模块实例，导致工具注册失败。`dsh-llm` 仅用于构造回传消息，缺失时插件降级为"审核照跑、不注入上下文"。
97
71
 
98
72
  ## 边界（明确不做）
99
73
 
100
- - 不实现审核规则本身（在 `skill-audit` 技能的脚本里，此处只负责触发与回传）；
101
- - 不改写工具输入、不阻塞工具调用（`fail` 也只在上下文里告知模型）；
102
- - 不覆盖 `SessionStart`/`Stop` 等非工具事件；
103
- - 不做技能目录的文件系统监视（`dsh-skill-filesystem` 已有 watcher；本插件只在工具调用后触发）。
74
+ - 不实现审核规则本身（规则在 `skill-audit` 技能里）；
75
+ - 不改写工具输入、不阻塞工具调用；
76
+ - 不覆盖 `SessionStart` / `Stop` 等非工具事件；
77
+ - 不监视技能目录的文件变化（只在工具调用后触发）。
104
78
 
105
79
  ## License
106
80
 
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.1",
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",