dsh-procedures 0.0.0-stage → 1.0.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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,51 @@
1
+ # Changelog
2
+
3
+ ## 1.0.1
4
+
5
+ - Docs: add a self-hosted plugin market index (`index.json`) and an install-from-market section to both READMEs.
6
+ - No runtime changes.
7
+
8
+ ## 1.0.0
9
+
10
+ - Release candidate: publishable package metadata (`private` removed, `engines.dsh`, author/homepage, publishConfig).
11
+ - Row id namespaced to `dsh-procedures` to avoid collisions in a shared market.
12
+ - **Market-safe default**: `autoInbox` is now `false`; autosaving raw errors is opt-in.
13
+ - Portable kit for non-DSH agents (`portable/setup.mjs`, `bin/hint.mjs`).
14
+ - English README summary.
15
+
16
+ ## 0.6.0
17
+
18
+ - Portable local kit: AGENTS snippet, setup script, generic `bin/hint.mjs` adapter.
19
+ - `buildHint` moved to `lib/hint.mjs` so non-DSH harnesses can reuse it.
20
+
21
+ ## 0.5.0
22
+
23
+ - Post-hint effect metric: `repeated` / `no_repeat` within a 5-result / 120 s window.
24
+ - `audit` reports `repeat-after-hint`; `list` shows rep/clear.
25
+
26
+ ## 0.4.0
27
+
28
+ - Global hit stats aggregated in `~/.dsh/procedures/global-stats.json`.
29
+ - `audit --global-dir` reviews global cards and reports `stale-global`.
30
+ - Global-only workspaces attach even without a local `procedures/`.
31
+
32
+ ## 0.3.1
33
+
34
+ - Fix: global-only workspaces (no local `procedures/`) now attach.
35
+ - `globalPenalty` (default 1) for merged local/global ranking.
36
+
37
+ ## 0.3.0
38
+
39
+ - Search cache (mtime/size signature + 750 ms TTL); 2000-card warm ~6 ms.
40
+ - `_stats.json` hit counts, rarity (`rare` ≤3 KB), global card library.
41
+ - LICENSE, .gitignore, package metadata.
42
+
43
+ ## 0.2.0
44
+
45
+ - Spell cards (`type: spell`, `actionable_code` / fenced block); suggest-only, never auto-execute.
46
+ - LLM-assisted `synthesize --llm` (draft-only, `_drafts/`).
47
+ - `requires` / `excludes` matching, strict auto-hints, 800-char error cap.
48
+
49
+ ## 0.1.0
50
+
51
+ - Initial DSH bundle: conditional hook, failure hints, auto inbox, card engine, CLI, audit.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 MiHjy12138
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/PRO.md ADDED
@@ -0,0 +1,47 @@
1
+ # dsh-procedures Pro(开放核心 · 规划)
2
+
3
+ 免费核心 = 单机经验卡(本地卡、钩子、CLI、Skill)。Pro = 把经验资产变成“团队的、跨机器的、可看的”。
4
+
5
+ ## 免费 vs Pro
6
+
7
+ | 能力 | 免费核心 | Pro |
8
+ |---|---|---|
9
+ | 本地经验卡 + 条件钩子 + 失败提示 | ✅ | ✅ |
10
+ | search / audit / list / synthesize CLI | ✅ | ✅ |
11
+ | 本地 `_stats.json`(hits / repeated / no_repeat) | ✅ | ✅ |
12
+ | 只读 `globalDir`(手动填路径) | ✅ | ✅ |
13
+ | DSH 原生 Skill(`~/.dsh/skills`) | ✅ | ✅ |
14
+ | **跨机器自动同步卡库 + stats** | ❌ | ✅ |
15
+ | **团队共享卡库(成员 / 只读 / 版本)** | ❌ | ✅ |
16
+ | **用量 / 复发 / 候选 Web 面板** | ❌ | ✅ |
17
+ | **按席位订阅** | ❌ | ✅ |
18
+
19
+ ## 为什么 Pro 有付费点
20
+
21
+ 个人用经验卡,免费工具已经够用;但“团队共享一套踩坑库、多台机器自动同步、看到谁在反复踩什么坑”,是团队真正愿意付钱的点——它正好落在现有 `globalDir`(共享只读卡库)的延伸上。
22
+
23
+ ## 技术形态
24
+
25
+ - 后端:一个轻量同步服务。登录先用 GitHub OAuth;存储先用对象存储 / 私有仓库,不自己造数据库。
26
+ - 插件侧:加 `procedures sync` 命令 + `sync` 配置,把卡库和 stats 同步到远端;本地照旧工作,离线也完整。
27
+ - 面板:只读 Web(命中 top、复发 top、promotion-candidate、stale-global、成员贡献)。
28
+ - 计费:Stripe / 支付宝 / 爱发电升级码;按月或按年,按席位。
29
+
30
+ ## 分阶段
31
+
32
+ - **P0(现在)**:免费核心上市场,攒用户、收反馈。
33
+ - **P1**:`procedures sync` + 最简后端(GitHub OAuth + 私有仓库当存储,最省服务器)。
34
+ - **P2**:团队共享卡库 + 成员/权限。
35
+ - **P3**:用量/复发面板 + 计费上线。
36
+
37
+ ## 定价思路(先不定死)
38
+
39
+ - 个人 Pro:低价(¥10–20/月)或免费引流。
40
+ - 团队:按席位(¥30–50/席位/月)。
41
+ - 原则:**Pro 只加“多机 / 团队 / 可见性”,不锁核心**;核心永远 MIT 免费。
42
+
43
+ ## 守住开源承诺(红线)
44
+
45
+ - 核心功能不加收费墙;Pro 是独立的闭源服务/同步层。
46
+ - 已经 MIT 公开的代码不回收。
47
+ - README 明确标注“免费核心 + Pro 规划中”,不误导。
package/README.en.md ADDED
@@ -0,0 +1,106 @@
1
+ # dsh-procedures
2
+
3
+ File-based experience cards for DeepSeek Harness (DSH) and other agents.
4
+
5
+ > Turn repeated agent mistakes into small per-workspace cards. When a matching tool error appears, inject only a one-line pointer — never the whole card.
6
+
7
+ [中文 README](README.md) | [Portable kit](portable/README.md) | [Changelog](CHANGELOG.md) | [Pro (planned)](PRO.md)
8
+
9
+ ## Positioning & Pro
10
+
11
+ - **Free core**: single-machine experience cards (hook, failure hints, CLI, skills) — MIT, free forever.
12
+ - **Pro (planned, not shipped)**: cross-machine sync, team-shared card library, usage/recidivism dashboard. The core is never paywalled; Pro is a separate service layer.
13
+
14
+ ## What it does
15
+
16
+ - **Conditional hook**: a ~1 KB system-prompt section only when the workspace has `procedures/` or a configured `globalDir`; zero cost otherwise.
17
+ - **Strict failure hints**: match `anchors` / `triggers` (+ `requires` / `excludes`), inject one line with the card path, never the card body.
18
+ - **Auto inbox** (opt-in, default **off**): unmatched tool errors can be appended to `procedures/_inbox.md`; raw errors may contain paths or secrets.
19
+ - **Stats**: local hits in `procedures/_stats.json`, global hits in `~/.dsh/procedures/global-stats.json`; `repeated` / `no_repeat` within a short window.
20
+ - **Rarity / global library**: `rare` cards may reach 3 KB; global cards are read-only and workspace cards win on id conflicts.
21
+ - **CLI**: `search`, `audit`, `list`, `inbox`, `synthesize` (optional LLM drafts).
22
+ - **Portable kit**: `AGENTS.md` hook + CLI + `bin/hint.mjs` for non-DSH agents.
23
+
24
+ Not included: tool registration, vector search, full-card injection, auto-promotion, auto-execution of spell code.
25
+
26
+ ## Install from the market
27
+
28
+ DSH has no official store; its plugin market works by adding an index. Add this index URL in the plugin market to discover and install `dsh-procedures`:
29
+
30
+ ```text
31
+ https://raw.githubusercontent.com/fubai-fenzhi/dsh-procedures/main/index.json
32
+ ```
33
+
34
+ Or install from npm directly:
35
+
36
+ ```bash
37
+ npm i dsh-procedures
38
+ ```
39
+
40
+ Market entry: `dsh-procedures@1.0.1`, `engines.dsh >= 0.2.1-rc.3`, MIT.
41
+
42
+ ## Install (DSH)
43
+
44
+ The package is a DSH bundle (`dsh.bundle.patch` in `package.json`). Install `dsh-procedures@1.0.0` through Plugin Manager or a market index. It declares `engines.dsh >= 0.2.1-rc.3`.
45
+
46
+ The bundle inserts row id `dsh-procedures` with `autoInbox: false` and `hintOnError: true`.
47
+
48
+ To enable auto-inbox in one profile, add to the profile's `cordis.patch.yml`:
49
+
50
+ ```yaml
51
+ - id: dsh-procedures
52
+ config:
53
+ autoInbox: true
54
+ ```
55
+
56
+ Then disable/enable the plugin row (or restart DSH).
57
+
58
+ ## Portable (non-DSH agents)
59
+
60
+ ```powershell
61
+ node portable/setup.mjs --workspace E:\YourProject --write
62
+ ```
63
+
64
+ This creates `procedures/` templates and appends the hook to `AGENTS.md` (use `--agent-file CLAUDE.md` for another instruction file). For a post-tool hook, send `{tool,error}` to:
65
+
66
+ ```powershell
67
+ echo '{"tool":"pwsh","error":"..."}' | node bin/hint.mjs --stdin --dir procedures
68
+ ```
69
+
70
+ stdout is the one-line hint, or empty when nothing matches (exit code 0). Add `--inbox` to capture unmatched errors.
71
+
72
+ ## Config (common keys)
73
+
74
+ | Key | Default | Meaning |
75
+ |---|---|---|
76
+ | `dir` | `procedures` | Workspace data directory |
77
+ | `autoInbox` | `false` | Append unmatched errors to `_inbox.md` |
78
+ | `hintOnError` | `true` | Inject a one-line hint on a card hit |
79
+ | `maxHintsPerSession` | `5` | Hint budget per session |
80
+ | `globalDir` | `""` | Read-only global card library |
81
+ | `globalPenalty` | `1` | Score penalty for global cards |
82
+ | `stats` / `globalStats` | `true` | Hit counters |
83
+ | `resolutionWindow` / `resolutionSeconds` | `5` / `120` | Post-hint repeat window |
84
+
85
+ ## CLI
86
+
87
+ ```powershell
88
+ node bin/procedures.mjs search "app.asar ENOENT" --dir procedures
89
+ node bin/procedures.mjs audit --dir procedures
90
+ node bin/procedures.mjs list --dir procedures
91
+ node bin/procedures.mjs synthesize --dir procedures
92
+ ```
93
+
94
+ Requires Node >= 18.
95
+
96
+ ## Limits
97
+
98
+ - Hints are literal anchor/keyword matches; no semantic search.
99
+ - `no_repeat` means "the same card did not fire within the window", not proof that the problem is solved.
100
+ - Auto-inbox is off by default because raw error text may contain sensitive data.
101
+ - Spell cards are suggested, never executed automatically.
102
+ - No official DSH market exists; Discover reads index URLs the user adds.
103
+
104
+ ## License
105
+
106
+ MIT.
package/README.md CHANGED
@@ -1,3 +1,370 @@
1
- # Temporary Holding Version
1
+ # dsh-procedures
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > 给 agent 开一个“抽卡”外挂:踩过的坑变成卡,失败时自动抽一张,卡库按需读。
4
+
5
+ 文件化经验卡 + DSH 条件钩子。目标只有一个:让 agent 不再重复踩同一个坑,同时不把卡片常驻进上下文。
6
+
7
+ [English](README.en.md) | [Changelog](CHANGELOG.md)
8
+
9
+ 当前版本:**1.0.0**(DSH 插件 + 通用本地版;市场候选版)。
10
+
11
+ ## 30 秒上手
12
+
13
+ 1. 工作区里建 `procedures/`(本工作区已有模板和 3 张种子卡)。
14
+ 2. 安装插件(本机已装,entry `include:dsh-procedures`)。
15
+ 3. 跑一次 `procedures audit`,确认 0 issue。
16
+ 4. 故意触发一次含卡片锚点的失败,看是否出现 `[procedures] 命中经验卡 …`。
17
+ 5. 踩到新坑就往 `_inbox.md` 记一行;够格的照模板升成正式卡。
18
+
19
+ ## 它做什么
20
+
21
+ - **条件钩子**:工作区存在 `procedures/`,或配置了可用的 `globalDir` 时,才给该 agent 注入约 1.0 KB 的约定;两者都没有的工作区零成本。
22
+ - **严格匹配**:自动提示只认 `anchors` / `triggers`(字面匹配),并用 `requires`(全中才算)和 `excludes`(命中即跳过)压误报;不会因为标题里碰巧有 `Desktop` 就弹卡。
23
+ - **检索缓存**:目录 mtime/size 签名 + 750 ms TTL,2000 张卡 warm 约 6 ms/查询(见 `bench/search.mjs`)。
24
+ - **失败提示**:工具报错时,命中 trap 给一行指针;命中 spell 额外提示语言和“确认后再执行”,**不自动执行代码**。
25
+ - **自动收件箱(默认关)**:报错没有命中任何卡时,向 `procedures/_inbox.md` 追加一行(同 session 同错误只记一次);global-only 模式不写。公开版默认关闭,因为原始报错可能含路径/密钥;需要时在 profile 覆盖 `autoInbox: true`。
26
+ - **命中统计**:本地卡命中写 `procedures/_stats.json`;全局卡命中写全局 sidecar(默认 `~/.dsh/procedures/global-stats.json`)。不碰卡片 YAML;`audit` 在 3 次命中后报 `promotion-candidate`。
27
+ - **命中后效果**:命中后开一个窗口(默认 5 个工具结果 / 120 秒);同一张卡再触发记 `repeated`,窗口内没再触发记 `no_repeat`。`audit` 在复发 ≥2 次且不少于未复发时报 `repeat-after-hint`。这是“有没有再犯”的代理指标,不是“有没有读懂卡”的证明。
28
+ - **稀有度**:`rarity: rare` 允许 3 KB,`common` 仍 2 KB;不自动升级,audit 只给候选。
29
+ - **全局卡库**:配置 `globalDir` 后合并只读全局卡;同 id 工作区优先,命中提示显示 `global:<文件名>`。**只有全局库、没有本地 `procedures/` 的工作区也会挂载**(global-only 模式;只提示,不写本地 inbox/stats)。
30
+ - **全局治理**:`audit --global-dir` 会审全局卡 + 全局 stats,报 `[global]` 的 `stale-global`(超过 `--stale-days` 没活动)和 `promotion-candidate`;只出清单,不删卡。
31
+ - **只读 CLI**:`search` / `audit` / `list` / `synthesize`,不注册成模型工具,不占 tool schema。
32
+ - **通用本地版**:非 DSH agent 用 `portable/`:AGENTS.md 钩子 + CLI + `bin/hint.mjs` 适配器;卡片/检索/审计完全一样。
33
+ - **可选自动抽卡**:`synthesize --llm` 调 OpenAI 兼容接口写草稿;只写 `_drafts/`,不自动转正。
34
+
35
+ 不做:向量检索、自动升卡、整卡注入、全库扫描、自动执行技能卡代码。
36
+
37
+ ## 定位与 Pro
38
+
39
+ - **免费核心**:单机经验卡(本地卡、条件钩子、失败提示、CLI、Skill),永远 MIT 免费。
40
+ - **Pro(规划中,未发布)**:跨机器同步、团队共享卡库、用量/复发面板。核心不设收费墙,Pro 是独立服务层。详见 [PRO.md](PRO.md)。
41
+
42
+ ## 从市场安装(DSH)
43
+
44
+ DSH 没有官方商店,市场是“添加索引源”的模式。把下面这个索引 URL 加进插件市场,就能搜到并安装 `dsh-procedures`:
45
+
46
+ ```text
47
+ https://raw.githubusercontent.com/fubai-fenzhi/dsh-procedures/main/index.json
48
+ ```
49
+
50
+ 也可以直接用 npm:
51
+
52
+ ```bash
53
+ npm i dsh-procedures
54
+ ```
55
+
56
+ 市场条目:`dsh-procedures@1.0.1`,`engines.dsh >= 0.2.1-rc.3`,MIT。
57
+
58
+ ## 当前安装状态
59
+
60
+ - 已安装到 profile `desktop`:entry `include:dsh-procedures`,bundle `dsh-procedures@1.0.0`。
61
+ - 本工作区 `procedures/` 有 9 张卡;钩子已在当前会话生效。
62
+ - 默认 `autoInbox: false`;要恢复自动写入,在 profile 的 `cordis.patch.yml` 里覆盖 `autoInbox: true`(见“配置”)。
63
+ - 安装方式:`plugin_manager` 的 `install_bundle`。本地目录以 junction 链进 profile,改工作区文件即改安装内容(重启/重载后生效);**`dsh-procedures/` 目录必须保留,删掉它等于删掉插件代码**。
64
+
65
+ ## 给其他 agent 用
66
+
67
+ 非 DSH 的 agent(Claude Code / Codex / Cursor / Gemini CLI / OpenClaw / 自研 agent):
68
+
69
+ ```powershell
70
+ node portable/setup.mjs --workspace E:\YourProject --write
71
+ ```
72
+
73
+ - 创建 `procedures/` 模板,并把钩子追加到该项目的 `AGENTS.md`(`--agent-file CLAUDE.md` 可换)。
74
+ - 之后用 `bin/procedures.mjs` 检索/审计;harness 有 post-tool hook 时,把 `{tool,error}` 交给 `bin/hint.mjs --stdin`,把 stdout 追加到上下文。
75
+ - **通用版没有自动拦截/注入**;自动提示、自动 inbox、stats、复发统计仍是 DSH 插件专属。详见 [portable/README.md](portable/README.md)。
76
+ - 分享:压缩整个 `dsh-procedures/` 目录给对方,只需 Node ≥ 18,不需要 DSH。
77
+
78
+ ## 目录
79
+
80
+ ```
81
+ 工作区/
82
+ procedures/
83
+ INDEX.md 只放易混现象的消歧,不逐卡列
84
+ _模板.md trap 卡骨架
85
+ _模板-spell.md spell 卡骨架
86
+ _inbox.md 踩坑/失败自动收件箱
87
+ _stats.json 命中统计(运行时生成,不提交)
88
+ _drafts/ synthesize 生成的草稿(不自动升卡)
89
+ cards/
90
+ <分类>-<现象>.md 正式卡,单卡 ≤ 2 KB(rare ≤ 3 KB)
91
+ ```
92
+
93
+ ## 卡片格式
94
+
95
+ YAML front matter 负责机器匹配与生命周期,正文保持人/agent 可读:
96
+
97
+ ```yaml
98
+ ---
99
+ id: tool-app-asar-files
100
+ title: DSH Desktop 的包与 skill 文件在 app.asar 内,shell / ripgrep 读不到
101
+ type: trap
102
+ rarity: common
103
+ triggers:
104
+ - skill 文件读不到
105
+ anchors:
106
+ - app.asar
107
+ - dsh-agent-preset
108
+ - ENOENT
109
+ requires: []
110
+ excludes:
111
+ - out of range
112
+ valid_until: 2027-12-31
113
+ environment: DSH Desktop / Windows
114
+ created: 2026-11-06
115
+ last_hit: null
116
+ hits: 0
117
+ ---
118
+ ```
119
+
120
+ - `anchors`:任务/报错里会**原样出现**的英文或符号,3–8 个;匹配优先级最高。
121
+ - `triggers`:任务里会出现的说法,可写正则 `/.../`。
122
+ - `requires`:所有词都出现才命中;`excludes`:任一出现就跳过。用来压“锚点太宽”的误报。
123
+ - `valid_until`:到期后不再参与匹配,`audit` 会报出来;`null` 表示不过期。
124
+ - `type`:`trap`(陷阱/反面清单)或 `spell`(可复用的修复动作)。
125
+ - `rarity`:`common`(默认,≤2 KB)或 `rare`(≤3 KB)。不自动升级;`audit` 在命中 3 次后给候选。
126
+ - 正文保留六段:触发 / 首选 / 被挡时 / 别再来 / 注意 / 证据;spell 还要有「可执行」「验证」。
127
+ - 旧卡(无 front matter)仍按 `> **触发**:` 和 `> **锚点**:` 行兼容。
128
+
129
+ ## 技能卡(spell)
130
+
131
+ `type: spell` 的卡可以带一段代码,但**插件不会执行它**——命中时只提示卡路径、语言和“确认安全后再执行”。
132
+
133
+ ````markdown
134
+ ---
135
+ id: spell-check-json
136
+ title: 用 node 校验 JSON 文件
137
+ type: spell
138
+ language: powershell
139
+ triggers: [json 坏了]
140
+ anchors: [ConvertFrom-Json, JSON]
141
+ valid_until: null
142
+ environment: Windows
143
+ created: 2026-11-06
144
+ last_hit: null
145
+ hits: 0
146
+ ---
147
+ # 技能-校验 JSON
148
+
149
+ ## 触发
150
+ 需要确认一个 JSON 文件是否合法。
151
+
152
+ ## 可执行
153
+ ```powershell
154
+ Get-Content .\data.json -Raw | ConvertFrom-Json | Out-Null
155
+ ```
156
+
157
+ ## 验证
158
+ 退出码 0 且没有异常。
159
+
160
+ ## 首选
161
+ none
162
+
163
+ ## 别再来
164
+ none
165
+
166
+ ## 注意
167
+ - 只校验语法,不校验业务字段。
168
+
169
+ 证据:会话 id / commit
170
+ ````
171
+
172
+ 写卡用 `procedures/_模板-spell.md`;`audit` 会检查 spell 必须有代码块和「验证」段。
173
+
174
+ ## 匹配精度
175
+
176
+ - 自动提示走 `strict` 模式:只认锚点/触发器,不再用标题、文件名、正文兜底;CLI 的 `search` 仍保留兜底,方便人找卡。
177
+ - 报错文本截到 800 字再匹配,避免超长报错的尾部噪声。
178
+ - 锚点太宽时用 `excludes` 拦掉常见误报。例:桌面卡加了 `excludes: [out of range]`,`read` 的 offset 越界不会再误报“桌面不存在”。
179
+
180
+ ## 规模、统计与全局库
181
+
182
+ - **基准**:`node dsh-procedures\bench\search.mjs`(加 `--quick` 只跑 500 张)。本机实测:500 张 cold 60 ms / warm 2.5 ms,2000 张 cold 209 ms / warm 6.0 ms。缓存后已经够快,没有再引入 `rg` 子进程。
183
+ - **缓存**:目录 mtime/size 签名 + 750 ms TTL。编辑卡片后最多 750 ms 生效;`loadCards(dir, { refresh: true })` 可强制刷新,`clearCardCache()` 可清空。
184
+ - **本地 `_stats.json`**:本地卡命中并注入提示时 +1;`audit` 读它,`hits >= 3` 报 `promotion-candidate`;`list` 显示 hits / rep / clear。统计只写 sidecar,不改卡片 YAML。
185
+ - **命中后效果**:命中后开一个窗口(默认 5 个工具结果 / 120 秒)。同一张卡再触发记 `repeated`,窗口内没再触发记 `no_repeat`;`audit` 在复发 ≥2 且不少于未复发时报 `repeat-after-hint`。这是“有没有再犯”的代理指标,不是“有没有读懂卡”的证明。
186
+ - **全局 `global-stats.json`**:global 卡命中写全局 sidecar(默认 `~/.dsh/procedures/global-stats.json`),跨工作区聚合;`--global-stats` 可覆盖路径。global-only 模式也能记。
187
+ - **`rarity`**:`rare` 允许 3 KB,`common` 仍 2 KB;`rare` 但 hits < 3 给 warn。升级由人改 YAML,不自动改卡。
188
+ - **`globalDir`**:合并只读全局卡;同 id 工作区优先;命中提示显示 `global:<文件名>`。只有全局库、没有本地 `procedures/` 的工作区也能挂载(global-only;只提示,不写本地 inbox/stats)。`globalPenalty`(默认 1)给全局卡降权,避免弱全局命中压过本地卡。默认关闭。
189
+ - **全局 audit**:`audit --global-dir DIR --global-stats FILE --stale-days 90` 同时审本地和全局;输出带 `[global]`,`stale-global` 表示超过 N 天没活动,`promotion-candidate` 表示命中够多。只出清单,不删卡。
190
+
191
+ ## CLI
192
+
193
+ 需要 Node。DSH 自带运行时的路径(本机):
194
+
195
+ ```powershell
196
+ $node = "C:\Users\Administrator\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe"
197
+ ```
198
+
199
+ ```powershell
200
+ # 按报错/任务词检索
201
+ & $node dsh-procedures\bin\procedures.mjs search "app.asar ENOENT" --dir procedures
202
+
203
+ # 结构、体积、过期、重复 id、spell 完整性检查;有 error 时退出码 1
204
+ & $node dsh-procedures\bin\procedures.mjs audit --dir procedures
205
+
206
+ # 同时审全局卡 + 全局 stats(默认 ~/.dsh/procedures/global-stats.json)
207
+ & $node dsh-procedures\bin\procedures.mjs audit --dir procedures --global-dir D:\shared\procedures --stale-days 90
208
+
209
+ # 列出现有卡
210
+ & $node dsh-procedures\bin\procedures.mjs list --dir procedures
211
+
212
+ # 手动记一行 inbox
213
+ & $node dsh-procedures\bin\procedures.mjs inbox add "只拿到 SPA 外壳" --tool web_fetch --dir procedures
214
+
215
+ # 无模型:把 inbox 每行生成 TODO 草稿骨架
216
+ & $node dsh-procedures\bin\procedures.mjs synthesize --dir procedures
217
+
218
+ # 合并只读全局卡库检索(默认给全局卡 -1 分)
219
+ & $node dsh-procedures\bin\procedures.mjs search "app.asar" --global-dir D:\shared\procedures --global-penalty 1
220
+
221
+ # 检索基准(合成卡,不碰真实卡库)
222
+ & $node dsh-procedures\bench\search.mjs --quick
223
+ ```
224
+
225
+ ## 自动抽卡(可选)
226
+
227
+ ```powershell
228
+ # 只打印 prompt,不联网、不需要 key
229
+ & $node dsh-procedures\bin\procedures.mjs synthesize --llm --dry-run --dir procedures
230
+
231
+ # 真正调用:DeepSeek 默认
232
+ $env:DEEPSEEK_API_KEY = "sk-..."
233
+ & $node dsh-procedures\bin\procedures.mjs synthesize --llm --max 3 --dir procedures
234
+
235
+ # 带会话上下文,生成更准
236
+ & $node dsh-procedures\bin\procedures.mjs synthesize --llm --context chat.md --dir procedures
237
+ ```
238
+
239
+ - 默认 `https://api.deepseek.com` / `deepseek-chat`;可用 `--base-url` / `--model` 或环境变量 `DSH_PROCEDURES_BASE_URL` / `DSH_PROCEDURES_MODEL` 覆盖。
240
+ - key 读 `DEEPSEEK_API_KEY` 或 `DSH_PROCEDURES_API_KEY`;本地 Ollama 这类 `http://127.0.0.1:...` 端点允许不带 key。
241
+ - 合格草稿写 `_drafts/draft-*.md`;不合格写 `*.rejected.md` 并保留原因。
242
+ - **永远不写 `cards/`,永远不自动转正。** 入卡前仍要人审。
243
+
244
+ ## 配置
245
+
246
+ 默认值写在 `dsh-procedures/cordis.patch.yml`:
247
+
248
+ | 键 | 默认 | 作用 |
249
+ | --- | --- | --- |
250
+ | `dir` | `procedures` | 相对工作区的数据目录 |
251
+ | `autoInbox` | `false` | 未命中卡时自动写 `_inbox.md`(公开版默认关,需显式开启) |
252
+ | `hintOnError` | `true` | 命中卡时注入一行指针 |
253
+ | `maxCards` | `3` | 每次失败最多参与匹配的卡数 |
254
+ | `maxHintsPerSession` | `5` | 每个 session 最多提示次数 |
255
+ | `minErrorChars` | `8` | 太短的报错不处理 |
256
+ | `sectionOrder` | `800` | 钩子 section 在系统提示中的排序 |
257
+ | `ignoreTools` | `[]` | 不处理的工具名 |
258
+ | `hookText` | `""` | 覆盖默认钩子文案 |
259
+ | `debug` | `false` | 输出 attach / hint / inbox 调试日志 |
260
+ | `stats` | `true` | 命中并提示时写 `_stats.json` |
261
+ | `globalDir` | `""` | 只读全局卡库目录;空=关闭,支持 `~` |
262
+ | `globalPenalty` | `1` | 全局卡匹配后的降权分数(0=不降权) |
263
+ | `globalStats` | `true` | global 卡命中时写全局 stats |
264
+ | `globalStatsFile` | `""` | 全局 stats 路径;空=`~/.dsh/procedures/global-stats.json` |
265
+ | `resolutionWindow` | `5` | 命中后观察多少个工具结果 |
266
+ | `resolutionSeconds` | `120` | 命中后观察多少秒 |
267
+
268
+ 要覆盖配置,在 profile 的 `cordis.patch.yml` 里加一条同 id 行(注意:匹配的 override 会替换**整个** config,没写的键会回落到默认值,不会继承 bundle 里的值):
269
+
270
+ ```yaml
271
+ - id: dsh-procedures
272
+ config:
273
+ autoInbox: true
274
+ hintOnError: true
275
+ ```
276
+
277
+ 改完在 Plugin Manager 里禁用再启用 `dsh-procedures`,或重启 DSH。
278
+
279
+ ## 验证
280
+
281
+ ```powershell
282
+ # 1) 检索
283
+ & $node dsh-procedures\bin\procedures.mjs search "app.asar ENOENT" --dir procedures
284
+
285
+ # 2) 结构检查(应无 error)
286
+ & $node dsh-procedures\bin\procedures.mjs audit --dir procedures
287
+
288
+ # 3) 命中提示:触发一个含 chat.deepseek.com 的失败,下一轮应看到
289
+ # [procedures] 命中经验卡 ...(锚点:...)...
290
+ # 4) spell 提示:触发一个含技能卡锚点的失败,下一轮应看到
291
+ # [procedures] 命中技能卡 ...,语言:...。先读卡,确认安全后再执行...
292
+ # 5) 未命中:触发一个不含任何锚点的失败,procedures/_inbox.md 应多一行
293
+ ```
294
+
295
+ 单测(DSH 沙箱下 `node --test` 会因 spawn 受限失败,直接跑文件即可):
296
+
297
+ ```powershell
298
+ & $node dsh-procedures\test\cards.test.mjs
299
+ & $node dsh-procedures\test\plugin.test.mjs
300
+ & $node dsh-procedures\test\llm.test.mjs
301
+ & $node dsh-procedures\test\stats.test.mjs
302
+ & $node dsh-procedures\test\cache.test.mjs
303
+ & $node dsh-procedures\test\global.test.mjs
304
+ & $node dsh-procedures\test\rarity.test.mjs
305
+ & $node dsh-procedures\test\attach.test.mjs
306
+ & $node dsh-procedures\test\global-audit.test.mjs
307
+ ```
308
+
309
+ ## 发布
310
+
311
+ 当前是 **1.0.0 发布候选版**,还没有执行 npm publish / GitHub push / 市场提交。
312
+
313
+ - 包名 `dsh-procedures` 在 npm 未被占用;`private` 已移除,`engines.dsh >= 0.2.1-rc.3`、`author`、`homepage`、`publishConfig` 已补。
314
+ - `npm pack` 实测 25 个文件、约 36 KB;`portable/`、`bin/hint.mjs`、locale/icon、CHANGELOG 都在包里。
315
+ - 市场没有“官方商店”:DSH 的 Discover 只读用户添加的 index URL;发布 = 上 npm(或 Git)+ 进第三方索引。
316
+
317
+ 发布步骤(需要你的 npm 账号):
318
+
319
+ ```powershell
320
+ cd dsh-procedures
321
+ npm login
322
+ npm publish --access public
323
+ ```
324
+
325
+ 然后:
326
+
327
+ 1. 把 `dsh-procedures/` 同步到 GitHub 仓库根目录(当前仓库还是旧的方法论 + tools;本机没 git,需要你 push 或用 API)。
328
+ 2. 提交到第三方索引(dpharness / dshmarket 等),或在自有 index JSON 里加一条 `dsh-procedures@1.0.0`。
329
+ 3. 用 `npm pack` 解压后的目录做一次干净 `install_bundle` 冒烟测试(发布前已在本机执行)。
330
+
331
+ ## 关闭与回滚
332
+
333
+ - 只关某个工作区:删掉该工作区的 `procedures/`。如果 profile 配了 `globalDir`,该工作区会切到 global-only(仍提示,但不写 inbox/stats);要彻底不挂载,把 `globalDir` 也清空。
334
+ - 关自动写入:`autoInbox: false`。
335
+ - 关失败提示:`hintOnError: false`。
336
+ - 临时禁用:Plugin Manager 或 `plugin_manager` → `set_plugin`,target `include:dsh-procedures`,enabled `false`。
337
+ - 卸载:`plugin_manager` → `remove_bundle`,target `dsh-procedures`。
338
+
339
+ ## 已知限制
340
+
341
+ - 钩子只在 agent 创建时检测本地 `procedures/` 或 `globalDir`;目录是后来新建的,要新会话或重载插件才生效。agent 中途切换工作目录也不会重新挂载。
342
+ - global-only 模式只提示,不写本地 `_inbox.md`、不记本地 `_stats.json`;全局命中会写全局 stats。
343
+ - 全局 stats 默认在 `~/.dsh/procedures/global-stats.json`(工作区外),需要该目录可写;它是派生数据,删了只丢命中数。
344
+ - `stale-global` 是启发式:按 `last_hit`(没有则 `created`)超过 `--stale-days` 判定,只提示,不自动删卡/降级。
345
+ - `no_repeat` 只表示“窗口内同一张卡没再触发”,不证明 agent 读懂了卡或问题真解决了。
346
+ - 每个 agent 只跟踪一个 pending:新命中会把上一个 pending 记 `no_repeat`;session 结束仍未结算的不计数。
347
+ - `repeat-after-hint` 是启发式(复发 ≥2 且不少于未复发),只提示,不自动改卡/删卡。
348
+ - `globalPenalty` 只影响排序,不是硬隔离;全局卡仍可能在高分时压过本地弱命中。
349
+ - 钩子是约定不是强制;模型仍可能不读卡。
350
+ - 自动 inbox 记的是原始报错,不是解法;整理成卡仍要人/agent 做。
351
+ - 注入提示是 user 角色消息,会出现在会话记录里。
352
+ - 匹配是字面锚点/关键词,不做语义检索;锚点写不好就匹配不上。
353
+ - spell 卡不自动执行;需要人/agent 读卡后自行决定。
354
+ - 自动抽卡需要 key(本地端点除外),且输出要经过结构校验;不保证一次就合格。
355
+ - `_stats.json` 是派生缓存,不是卡片真值;删了只丢命中数,不影响匹配。
356
+ - `globalDir` 默认关闭;全局卡只读,不会写全局 `_inbox.md`。
357
+ - 未引入 `rg`:基准显示缓存后 2000 张 warm 约 6 ms;卡库到上万张再回来加。
358
+ - 缓存 TTL 750 ms:刚改完卡立刻触发失败,可能仍用旧卡;重载或 `refresh` 可强制刷新。
359
+ - 本插件与仓库 `docs/QUALITY-BUDGET.md` 的“不自动捕获、不自动写回、不加全局钩子”三条约束冲突。本次按用户选择默认全开,可用上表逐项关闭。
360
+
361
+ ## 设计取舍
362
+
363
+ - 不把读卡包成 tool:tool schema 常驻 system prompt,等于把“按需目录”变成“每轮目录”,是反模式。
364
+ - 不注入整卡:只给路径和锚点,保持“索引常驻、卡按需读”的成本结构。
365
+ - 不自动升卡:`synthesize` 只写 `_drafts/`,正式卡由人审后移动;删卡同样由人决定。
366
+ - 统计写 sidecar:`_stats.json` / `global-stats.json` 只记命中,不改卡片 YAML;升级/退役仍由人决定。
367
+ - rarity 只给候选:不自动把卡改成 `rare`,避免命中数一够就放宽体积。
368
+ - 全局卡只读:`globalDir` 只参与检索和提示,不写全局 inbox、不自动改全局卡。
369
+ - 不自动执行 spell:从 Markdown 卡里自动跑代码是安全漏洞;先提示,让人/agent 确认。
370
+ - 提示去重:同一 session 同一张卡只提示一次;同一错误只记一次 inbox。
@@ -0,0 +1,74 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Compare cold and warm search cost on a synthetic card library.
4
+ * Run: node bench/search.mjs [--quick]
5
+ */
6
+ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
7
+ import { tmpdir } from 'node:os';
8
+ import { join } from 'node:path';
9
+ import { performance } from 'node:perf_hooks';
10
+
11
+ import { clearCardCache, searchCards } from '../lib/cards.mjs';
12
+
13
+ function makeLibrary(count) {
14
+ const root = mkdtempSync(join(tmpdir(), 'dsh-procedures-bench-'));
15
+ mkdirSync(join(root, 'cards'), { recursive: true });
16
+ for (let index = 0; index < count; index += 1) {
17
+ const id = `bench-${String(index).padStart(4, '0')}`;
18
+ const body = `---
19
+ id: ${id}
20
+ title: 基准卡 ${index}
21
+ type: trap
22
+ rarity: common
23
+ anchors: [probe-${index}, benchmark.example, ENOENT]
24
+ triggers: [基准 ${index}]
25
+ valid_until: 2030-01-01
26
+ ---
27
+ # 工具-基准 ${index}
28
+
29
+ ## 首选
30
+ none
31
+
32
+ ## 别再来
33
+ | 弯路 | 为什么不通 |
34
+ | --- | --- |
35
+ | x | y |
36
+
37
+ ## 注意
38
+ - ${'说明文字'.repeat(80)}
39
+
40
+ 证据:bench
41
+ `;
42
+ writeFileSync(join(root, 'cards', `${id}.md`), body, 'utf8');
43
+ }
44
+ return root;
45
+ }
46
+
47
+ function measure(count) {
48
+ const dir = makeLibrary(count);
49
+ const queries = Array.from(
50
+ { length: 20 },
51
+ (_, index) => `probe-${(index * 97) % count} not found`,
52
+ );
53
+
54
+ clearCardCache();
55
+ const coldStart = performance.now();
56
+ searchCards(dir, queries[0], { max: 3, strict: true });
57
+ const cold = performance.now() - coldStart;
58
+
59
+ const warmStart = performance.now();
60
+ for (const query of queries) searchCards(dir, query, { max: 3, strict: true });
61
+ const warm = (performance.now() - warmStart) / queries.length;
62
+
63
+ rmSync(dir, { recursive: true, force: true });
64
+ return { count, cold, warm };
65
+ }
66
+
67
+ const quick = process.argv.includes('--quick');
68
+ const counts = quick ? [500] : [500, 2000];
69
+ for (const count of counts) {
70
+ const result = measure(count);
71
+ console.log(
72
+ `${result.count} cards: cold ${result.cold.toFixed(1)} ms, warm ${result.warm.toFixed(2)} ms/query`,
73
+ );
74
+ }