Skip to content

Commit caee25a

Browse files
committed
docs(readme): the tool table was missing two tools, and nothing could see it
The review found the count fix left a worse conflict behind: the package README has a 模型工具 table, and it lists 10 tools while tools.js registers 12 (set_scope_state from #471 and memory_organize from #231 were never added). So "11/12" in the prose and a 10-row table contradict each other in the same file — a fixed number on top of a stale list. Both rows added in registration order, each opt-in row naming the switch it needs (organizeEnabled), and the discard/archive distinction the review flagged is spelled out where a reader will hit it: discard writes nothing at all and only touches the receipt, archive retires an existing row the report matched, recoverably. The real fix is the guard. readme-claims.test.js existed but only policed one historical lie (the offline claim), which is why the table drifted twice without a single failing test. It now derives the expected set from tools.js: names from the registrations, opt-in membership from the `!== true` hiddenTools polarity (`=== true` means default-on and user-disableable, so counting those as opt-in would understate the default set), and requires the heading's numbers to match both the default count and the full count. Mutation-checked against the actual past breakage: heading back to "10 个" and the two rows removed reddens the new test with the "table must map one-to-one" message; restoring it is green.
1 parent 7720ffb commit caee25a

3 files changed

Lines changed: 43 additions & 2 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ dsh-mneme 是 DSH 宿主的记忆插件(蒸馏 / 注入 / 检索 / 巩固 / sc
4343
| 服务层 | `src/service.js` | saveWithDedupe(去重键 type+title+scope 三元组)、fuseRecall 检索融合(keyword/vector/bm25/entity)、注入候选、镜像同步、冲突队列 |
4444
| 写入准入 | `src/write-admission.js` | 写入前的会话写入预算与同话题冷却(#254)。第 1 级确定性判据(空白 / 噪声 / 密钥 PII)只在三个条件同时成立时才跑:有 `sessionKey`、`llmAudit.enabled` 未被显式关、`writeAdmission.enabled === true`;都成立且**命中**时,再由 `writeAdmission.enforce` 决定是否真拒绝(`ADMISSION_DECISION_DENY`)。只开 `enforce` 不跑判据、也不拦写入。默认只计量,测量点落 `llm_audit_logs` |
4545
| 注入 | `src/inject.js` + `src/user-settings.js` | 注入位构造、内容截断、跨轮轮换;「用户设置」块(人格 → 画像 → 规则)的渲染与寻址住在 user-settings.js,**面板预览共用这一份**(前端不自己拼第二份) |
46-
| 整理与画像草稿 | `src/organize.js` + `src/profile-extract.js` | agent 主动整理(dryRun 比对报告 → agent 判断 → apply,筛除只归档不删,复用 `dream_runs` 回执);从活跃记忆提取「助手眼中的用户」**草稿**(只回草稿,绝不写 `user_settings`)。两个入口都 opt-in 默认关(`organizeEnabled` / `profileExtractEnabled`) |
46+
| 整理与画像草稿 | `src/organize.js` + `src/profile-extract.js` | agent 主动整理(dryRun 比对报告 → agent 判断 → apply)与从记忆提取画像草稿(只回草稿,绝不写 `user_settings`)。整理里有两种「不要它」,别混:**`discard`** = 这条候选不写,任何东西都不动(只进回执);**`archive`** = 把报告标为被取代的那条既有行归档——可恢复,绝不物理删除。两个入口都 opt-in 默认关(`organizeEnabled` / `profileExtractEnabled`) |
4747
| 蒸馏 | `src/summarize.js` + `src/quality-filter.js` | 会话 → 记忆;质量打分与处置(归档/降权) |
4848
| 巩固与睡眠 | `src/dream.js` + `src/dream/{decisions,clustering,sleep}.js` | LLM 巩固决策、dream_runs 审计回执 |
4949
| 实体 | `src/entities/extractor.js`(存储侧在 store 三表) | 写入时 LLM 抽取实体/属性/关系 |

‎dsh-mneme/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,8 @@ dsh web
4949
- 逐 type 记录 `committed / failed / pending` 回执,健康端点区分 `ok / degraded / unknown`
5050
- 状态写失败不静默:同步失败落日志并留债务,重启自动收敛
5151

52-
### 模型工具(10 个)
52+
### 模型工具(默认注册 11 个;开 `organizeEnabled` 后 12 个)
53+
5354

5455
| 工具 | 功能 |
5556
|------|------|
@@ -61,7 +62,9 @@ dsh web
6162
| `memory_delete` | 删除记忆(按记忆 ID 精确删除) |
6263
| `memory_forget` | 抑制注入(降权不删除,可恢复) |
6364
| `memory_archive` | 归档/恢复记忆(v0.2.5;归档后隐藏于列表/搜索/注入/整理,`archived=false` 可恢复) |
65+
| `set_scope_state` | 按下/松开某个作用域的**可逆闸门**(#471:政策轴。暂停期间该作用域的记忆照旧存着,只是不注入、不参与巩固,松开即原样回来;不改任何一条记忆的标注,与上面逐条操作的 `memory_forget` / `memory_archive` 是两根不同的轴)。两级开关 `scopeState.enabled` / `.enforce` 默认都关,没开时按下不产生拦截效果 |
6466
| `memory_register_document` | 登记 agent 产长文档的指针行(#230:摘要 + `doc_path` + evidence 落 `document` 类型;正文留在磁盘、由 agent 自管,注册口唯一,旁路写入被拒) |
67+
| `memory_organize` | 主动整理(#231,**要 `organizeEnabled` 打开才注册**):`mode=dryRun` 先出比对报告(每条候选 `exact` / `near` / `new` + 命中行,**不写一行库**、只留审计回执),agent 判断后 `mode=apply` 引用那份报告的 `run_id` 落地。两种「不要它」要分清——**`discard`** = 这条候选不写,什么都不动(只进回执);**`archive`** = 把报告标为被取代的那条**既有行**归档(可恢复,绝不物理删除)。没有比对过的候选写不进库,一份报告也只许落地一次 |
6568
| `memory_runtime` | 本地推理运行时的状态 / 供给 / 校验(v0.7.32,自管运行时三档取件) |
6669

6770
### 工作流(M.O.,v0.9 beta)

‎dsh-mneme/test/readme-claims.test.js‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,3 +66,41 @@ test("隐私节必须写出「巩固与摘要走宿主模型」这个出站事
6666
"English Privacy section should disclose that consolidation uses the host model",
6767
);
6868
});
69+
70+
// 「模型工具」表是代码的投影,不是愿望清单(AGENTS.md 给 SECURITY.md 定的那条规矩,
71+
// 这张表一直没有)。它已经跑偏两次:#471 加 set_scope_state、#231 加 memory_organize,
72+
// 两次都没人回头改表或改那个数字——因为没人核过。所以这里全部**从代码反推**:
73+
// 工具集从 tools.js 的 name: "…" 取,opt-in 从 hiddenTools 的 `!== true` 判据取
74+
// (`=== true` 那种是「默认在、用户可关」,不能算进 opt-in,否则默认注册数会算少)。
75+
test("包 README 的「模型工具」表与 tools.js 注册表一致", () => {
76+
const toolsSrc = readFileSync(path.join(pkgRoot, "src/tools.js"), "utf8");
77+
const declared = [...toolsSrc.matchAll(/^ {6}name: "((?:memory_|set_scope)[a-z_]*)",/gm)].map((m) => m[1]);
78+
assert.ok(declared.length >= 10, `tools.js 的工具名解析失败(只看到 ${declared.length} 个)——先修这条守卫,别改表`);
79+
const optIn = [...toolsSrc.matchAll(/if \(config\?\.(\w+) !== true\) hiddenTools\.add\("([a-z_]+)"\)/g)]
80+
.map((m) => ({ key: m[1], tool: m[2] }));
81+
const defaultCount = declared.length - optIn.length;
82+
83+
const heading = pkgReadme.match(/^### 模型工具(([^)]*))$/m);
84+
assert.ok(heading, "包 README 应有「### 模型工具(N 个)」这一节标题(标题格式变了就同步改这条守卫)");
85+
const bodyStart = pkgReadme.indexOf(heading[0]);
86+
const bodyRest = pkgReadme.slice(bodyStart + heading[0].length);
87+
const nextSection = bodyRest.search(/\r?\n#{2,3} /);
88+
const body = nextSection === -1 ? bodyRest : bodyRest.slice(0, nextSection);
89+
const rows = [...body.matchAll(/^\| `([a-z_]+)` \|/gm)].map((m) => m[1]);
90+
91+
assert.deepEqual(
92+
[...new Set(declared)].sort(),
93+
[...new Set(rows)].sort(),
94+
"表与注册表必须一一对应:少了是漏文档,多了是文档写了不存在的东西"
95+
);
96+
assert.equal(rows.length, new Set(rows).size, "表里不许有重复行(重复行会让数量核对失效)");
97+
for (const n of [defaultCount, declared.length]) {
98+
assert.ok(heading[1].includes(String(n)), `标题里的数字要含 ${n}(opt-in 工具默认不注册,两个数都要对得上)`);
99+
}
100+
// opt-in 工具那一行必须点名它的开关:读者看到表里有它,得知道默认是不出现的。
101+
for (const { key, tool } of optIn) {
102+
const row = body.match(new RegExp(`^\\| \`${tool}\` \\|(.*)$`, "m"));
103+
assert.ok(row, `${tool} 必须在表里`);
104+
assert.ok(row[1].includes(key), `${tool} 那行要写明它需要 ${key} 才注册`);
105+
}
106+
});

0 commit comments

Comments
 (0)