Skip to content

Commit 7192f3f

Browse files
committed
docs: chorography M0 实现计划(P1–P7 决策)、CHANGELOG 条目与模块图行
1 parent 547fc92 commit 7192f3f

3 files changed

Lines changed: 61 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ dsh-mneme 是 DSH 宿主的记忆插件(蒸馏 / 注入 / 检索 / 巩固 / sc
5151
| 外来行判据 | `src/memory-source.js` | 「本库不巩固别人导入的原文」这条契约的唯一实现(`isImportedRow`),挂在 saveWithDedupe 汇流口与巩固/睡眠/整理的九个行池上([docs/SHARE.md](dsh-mneme/docs/SHARE.md)) |
5252
| 分享包(出与收) | `src/share.js` + `src/share-http.js` + `src/share-import.js` | 出包口径与入包闸门(`buildSharePack` / `validateSharePack`,一条不合格整包拒)、两张皮共用的解析与答复(`shareReply` / `receiveReply` / `undoReply` 各只有一份——**「两张皮只许剩鉴权与路径不同」这条纪律归 `share-http.js`**,它同时承诺「这一层从不抛」)、收侧入库与整包退出(一个事务、按 `share_external_id` 幂等、物删不归档)。面板三件(分享弹层 / 接收弹层 / 外来区筛选与整包退出)在 `lib/client.js`,出包口径、入包闸门、错误码→状态全在那里读、不在那里复述;唯一的例外是外来说的那个字面量 `"imported"`(独立 bundle 不能 `import src/memory-source.js`),它由 `test/client-share.test.js` 的跨文件镜像锁钉回 `IMPORTED_SOURCE` 那一份 |
5353
| 实体 | `src/entities/extractor.js`(存储侧在 store 三表) | 写入时 LLM 抽取实体/属性/关系 |
54+
| 仓库地志(chorography) | `src/wiki/{plan,scan,partition,render,t0}.js` + `bin/dsh-mneme-choro.mjs`(表在 store 五张 `choro_*`) | 仓库 → 确定性骨架页(T0 零模型)+ plan.yaml 正面控制;**wiki 行永不进记忆行池 / dream / 质量过滤**,消费面(检索/注入/面板)M1+ 接。spec:[docs/specs/2026-11-04-chorography-design.md](docs/specs/2026-11-04-chorography-design.md) |
5455
| 检索辅助 | `src/search/{bm25,adaptive}.js`、`src/vector-index.js`、`src/embedding.js`、`src/local-embedder.js`、`src/reranker.js` | BM25 / 自适应阈值 / 向量索引 / 嵌入 / 重排 |
5556
| 热度 | `src/heat.js` | 纯函数遗忘曲线(opt-in) |
5657
| 复用统计 | `src/recall-stats.js` | recall_runs 只读聚合(#217,Top-N 召回 + 僵尸率) |
Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# chorography M0 实现计划(车道 choro / 分支 feat/chorography-m0)
2+
3+
对应 spec:`docs/specs/2026-11-04-chorography-design.md`(本车道首个 commit 5fa0f12)。
4+
范围只到 spec §10 的 M0 档:**T0 确定性骨架 + 表 + plan.yaml 校验 + CLI 入口,无面板、无模型、无注入**。
5+
M1+(面板、只读工具、T1 headless 轮、注入)不在本计划内。
6+
7+
## 已定实现决策(spec 之外的补口)
8+
9+
| # | 决策 | 理由 | 被否备选 |
10+
| --- | --- | --- | --- |
11+
| P1 | 新增运行时依赖 `yaml`(唯一一个) | plan.yaml 是用户手写的正面控制面,spec 降级表要求「未知键整轮不跑 + 报出键名与允许列表」——手写 YAML 子集解析器会在注释/锚点/多行字符串上静默错解,错解直接违背 D7 的存在理由 | 手写子集解析器:省一个依赖,换来用户配置被静默错解的永续风险 |
12+
| P2 | 表是五张不是四张:spec §5 的四张 + `choro_repos` | spec 的 `choro_modules.repo_id` 必须指向一个仓库登记行;多仓库共存(消费面 §7「按工作目录匹配已登记仓库」)也要求登记表 | 把 root_path 反规范化进 modules:多仓库唯一性与改名都要靠约定 |
13+
| P3 | T0 前端 frontmatter 不含生成时刻列,`generatedAt` 只进 state.json 并由下次 run 沿用 | spec §9 的字节稳定不变量(同状态两次生成逐字节相同)与「每页记生成时刻」直接冲突;把时刻收进 state.json(失败不推进,红线 5)两头都成立 | 放弃字节稳定不变量:那是对齐 document 索引可重建性的锚,不能放 |
14+
| P4 | CLI 独立成 `bin/dsh-mneme-choro.mjs`,不动 `bin/cli.mjs` | CONTRIBUTING「The CLI is dependency-free by contract」禁止给 cli.mjs 加 import;T0 可离线(零 LLM、不开 daemon),循 `dsh-mneme-serve` 的独立 bin 先例 | 挂 cli.mjs 子命令:违约;走 standalone API:把「可离线」变成「必须先起服务」 |
15+
| P5 | CLI 缺省 dry-run,`--apply` 才写 | 仓库纪律(`dsh-mneme reclaim` 同款):会写盘的东西先给数字再执行;T0 幂等可重跑,dry-run 零成本 | 直接写:与「产出物能 git diff」的人工复核流冲突 |
16+
| P6 | 保留区(`<!-- CHORO:HUMAN -->` 块)回填位置 = 页尾按原相对顺序 | 重生成后的新正文里,旧块的原锚点位置可能已不存在;「页尾 + 原顺序」是唯一不需要猜测位置的确定性规则 | 原位回填:需要位置映射,模板一改就对不上 |
17+
| P7 | DB 写入是「整仓替换」不是逐行 upsert | 「重跑必须幂等」(红线 5)在替换语义下是删了重插一个事务,不用逐行对账 | 逐行 upsert:模块划分一变就留下孤儿行,还要写清理逻辑 |
18+
19+
## 里程碑内步骤
20+
21+
1. `store.js`:五张 `choro_*` 表进 SCHEMA(幂等,`CREATE TABLE IF NOT EXISTS`;唯一性走独立索引,本仓惯例)+ 三个方法(查/登仓库、整仓替换图)。
22+
2. `src/wiki/plan.js`:plan.yaml 加载 + 严格校验(未知键/类型错/缺 path 全部收集后一次报出;无 plan.yaml 用默认启发式)。
23+
3. `src/wiki/scan.js`:文件清单(默认排除目录 + gitignore 子集匹配 + 二进制跳过)+ import 图(ESM 静态/动态、CJS require、Vue SFC `<script>`、workspace/exports;解析失败记 skipped 不中断)。
24+
4. `src/wiki/partition.js`:目录初稿 → 兄弟组交叉边合并 → 超 `max_files_per_page` 逐级下切;slug 稳定生成;父子关系按目录包含。
25+
5. `src/wiki/render.js`:骨架页 + index.md 渲染(全排序、零时间戳于正文;`generatedAt` 从 state.json 沿用);保留区抽取/回填(字节级)。
26+
6. `src/wiki/t0.js`:编排(git 基线 → plan → 扫描 → 划分 → 渲染 → dry-run 报告 / apply 写盘 + 落库 + state.json 收尾);所有写路径断言在 `.chorography/` 前缀内(红线 1 的机械面)。
27+
7. `bin/dsh-mneme-choro.mjs` + `package.json` bin 注册。
28+
8. 测试(`node --test`):
29+
- `wiki-plan.test.js`:未知键拒绝且报键名与允许列表、默认启发式、pages 形状错。
30+
- `wiki-scan.test.js`:ESM/CJS/动态/Vue SFC/workspace 六类 fixture、外部依赖聚合、unresolved 计数、exclude 匹配。
31+
- `wiki-partition.test.js`:同输入两次划分逐项相同、合并与下切、slug 稳定。
32+
- `wiki-t0.test.js`:dry-run 零写入(树快照对比);apply 后**仓库里除 `.chorography/` 外一个字节不变**(红线 1 的契约测试);两次 apply 字节相同(可重建不变量);保留区逐字节存活;非 git 拒绝。
33+
- `wiki-store.test.js`:表存在性(新库)、整仓替换幂等(跑两遍行数不翻倍、唯一索引生效)。
34+
35+
## 明确不做(M0 边界内)
36+
37+
向量写入(`choro_vectors` 空壳建表不灌数据,embedder 是 M1/M2 的事)、
38+
evidence/ 文件(T0 零 claims,M2 才有)、stale 检测(M3)、面板与只读工具(M1)、
39+
任何配置键与行为开关(M0 不碰宿主运行时行为,故 AGENTS.md 自查清单第 1/2 条不适用)、
40+
README(readme-claims 锁的存在使新增能力声明要配证据,M1 一起写)。
41+
42+
## 待实测回填
43+
44+
V2(import 图在三个真实仓库上的模块划分准不准)跑法:M0 收尾后对
45+
dsh-baleen / dsh-study-desk / 本仓各跑一次 `--apply`,人判划分;结果记回本文件。

‎dsh-mneme/CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22

33
## [Unreleased]
44

5+
- **chorography(仓库地志)M0:T0 确定性骨架 + `choro_*` 五表 + `dsh-mneme-choro` CLI**:对标 Qoder 知识库/Repo Wiki 的 mneme 子系统第一批(spec:仓库根 `docs/specs/2026-11-04-chorography-design.md`,实现计划与 P1–P7 决策:仓库根 `docs/plans/2026-11-04-chorography-m0.md`)。读一个 JS/TS 仓库,把文件树 + import 图(ESM 静态/副作用/动态、CJS require、Vue SFC `<script>`、workspace/exports)编译成模块划分与仓库内 `<repo>/.chorography/` 的骨架页(frontmatter 带源文件清单与 git 基线),全程零模型零网络可离线;语义段落(架构/约定/技术栈)由 M2 的 headless 生成轮补。「生成吃宿主模型额度、不要求额外模型商 key」是整条线成立的前提(用户 2026-11-04 拍板),T0 这一步刻意一分钱不花。
6+
7+
- **与记忆行物理隔离是硬边界不是实现细节**:wiki 行永不进 saveWithDedupe / dream / 质量过滤的任何池子——autoDream 的「对核心知识库长期参考价值较低」归档理由一旦够得着 wiki 行,机器生成页就会被巩固流程自己归档掉(`dream-archive-guardrail` 测的正是这个语义)。五张 `choro_*` 表在 store.js 独立成段,`replaceChoroGraph` 整仓替换(重跑幂等 = 单事务删了重插,划分变了不留孤儿行)。
8+
- **保留区机制**:页面里 `CHORO:HUMAN` 标记对包住的内容跨重生成逐字节存活(抽整块、按原相对顺序回填页尾),块外手改不保留是明说语义不是事故。可重建不变量(同状态两次生成逐字节相同)由「`generatedAt` 只进 state.json、失败不推进、下次沿用」撑住——spec §4 的 frontmatter 字段清单与 §9 的字节稳定要求表面冲突,在实现计划 P3 拆掉。渲染层有一条自反雷已排:页面说明行不得出现成对的标记字面量,否则下一轮抽取会把说明行当成保留区(回归锁在 `test/wiki-t0.test.js` 的字节稳定用例里)。
9+
- **plan.yaml 是正面控制**(D7):include/exclude(gitignore 子集:无斜杠模式任意层级、前导斜杠锚定、反选、目录尾斜杠)+ pages 白名单(未列出的模块不建页,模板与笔记原文进页)+ `max_files_per_page`;**未知键整轮拒绝**并报出键名与允许列表——拼错的键等于失效的控制,不能静默忽略。
10+
- **CLI 独立成 bin**(CONTRIBUTING「cli.mjs 零依赖契约」禁止加 import,循 `dsh-mneme-serve` 先例):`dsh-mneme-choro <repo> [--apply] [--db <path>] [--json]`,缺省 dry-run(reclaim 同款纪律);非 git 仓库整轮拒绝(锚点无法核验);写路径断言 `.chorography/` 前缀,契约测试对整仓做树快照——apply 后除 `.chorography/**` 外一个字节都不变、不得出现 `.github/`、`.gitignore`、`AGENTS.md`(openwiki 那两个坏习惯在这里判死)。新增唯一运行时依赖 `yaml`(plan.yaml 是用户手写的配置面,手写子集解析器会静默错解,实现计划 P1)。
11+
- **验证**:39 例新测试(`test/wiki-{plan,scan,partition,store,t0}.test.js`:单元 + 字节稳定 + 红线契约 + 库幂等);V2(import 图在三个真实仓库上的划分质量要人判)待人跑,跑法记在实现计划「待实测回填」。M1(面板 + 只读工具 + 检索)、M2(T1 生成轮)、M3(注入)不在本批次。
12+
513
- **状态页热力右侧那块常年空着的 220px 补上「8 周沉淀」图:新增 vs 巩固两根柱并排、归档给总量(用户 2026-11-04 提的)**:热力图 56 格 × 11px 只有约 745px 宽,而这块容器可用宽 968px,右边一直空着——**空白不是某个空 div,是「三块图各自独占整行」造成的**,所以改的是布局(热力与沉淀并成两列,窄容器回落单列),而不是往某个槽里塞图。新图要回答的是面板此前答不了的那个问题:库是在巩固,还是只在膨胀。
614

715
- **口径不许复用 `dream_runs.applied`**:那一列在 degraded 轮里也是非零(实测 2026-11-03 两轮分别 14、16,而当日 receipt_chain 总共 19 行),拿它当「今天沉淀了多少」会把失败轮算成成果。逐条真源只有 `receipt_chain`:`kind IN ('merge','update') AND verdict='live'`。**这一条正是「跑了很多轮但看起来没沉淀」假象的来源**,也是这套图存在的理由。
@@ -12,6 +20,13 @@
1220
- **未到 / 已知为空必须分开**:`sinkStats === null` 时既不画柱也不画图例(否则加载态先画 8 根零高柱子再「长出来」,用户看到的是一次假抖动);`{}` 且三总量全 0 才画空态那句话。`days` 缺省 56(正好 8 周,与热力同窗),钳 1..365,`days=0` 回落缺省而不是钳到 1(与 `llm-audit/stats` 同一套写法,两条曲线对同一个参数给同样的窗口)。
1321
- **两根柱的颜色进图形锁**:柱高差就是结论本身(新增高、巩固矮 = 库在膨胀),掉回浅灰等于把结论擦掉。`.mneme-sinkbar--added` / `--merged` 用 `--mneme-chart-3` / `--mneme-chart-2`,并加进 `test/contrast.test.js` 的 GRAPHICS 表按 3:1 审(不引入任何新字面量色)。
1422
- **验证**:`npm test` 2719 tests / 2718 pass / 0 fail / 1 skipped;`check-sync` 85 文件一致。变异自证六处,全部当场变红:`merged` 退回数行数 → 红「同一 record_id 的两条 receipt 只能算 1 条巩固」;`added` 去掉 imported 排除 → 红;前端把 `if (!sinkStats) return null` 改成 `return []` → 红;删掉 `@container (max-width:960px)` 回落 → 红;把全零空态分支改成 `false` → 红;柱子改回 `--dsw-alias-label-tertiary` → 红(对比度锁 + 语义层锁双杀)。
23+
- **chorography(仓库地志)M0:T0 确定性骨架 + `choro_*` 五表 + `dsh-mneme-choro` CLI**:对标 Qoder 知识库/Repo Wiki 的 mneme 子系统第一批(spec:仓库根 `docs/specs/2026-11-04-chorography-design.md`,实现计划与 P1–P7 决策:仓库根 `docs/plans/2026-11-04-chorography-m0.md`)。读一个 JS/TS 仓库,把文件树 + import 图(ESM 静态/副作用/动态、CJS require、Vue SFC `<script>`、workspace/exports)编译成模块划分与仓库内 `<repo>/.chorography/` 的骨架页(frontmatter 带源文件清单与 git 基线),全程零模型零网络可离线;语义段落(架构/约定/技术栈)由 M2 的 headless 生成轮补。「生成吃宿主模型额度、不要求额外模型商 key」是整条线成立的前提(用户 2026-11-04 拍板),T0 这一步刻意一分钱不花。
24+
25+
- **与记忆行物理隔离是硬边界不是实现细节**:wiki 行永不进 saveWithDedupe / dream / 质量过滤的任何池子——autoDream 的「对核心知识库长期参考价值较低」归档理由一旦够得着 wiki 行,机器生成页就会被巩固流程自己归档掉(`dream-archive-guardrail` 测的正是这个语义)。五张 `choro_*` 表在 store.js 独立成段,`replaceChoroGraph` 整仓替换(重跑幂等 = 单事务删了重插,划分变了不留孤儿行)。
26+
- **保留区机制**:页面里 `CHORO:HUMAN` 标记对包住的内容跨重生成逐字节存活(抽整块、按原相对顺序回填页尾),块外手改不保留是明说语义不是事故。可重建不变量(同状态两次生成逐字节相同)由「`generatedAt` 只进 state.json、失败不推进、下次沿用」撑住——spec §4 的 frontmatter 字段清单与 §9 的字节稳定要求表面冲突,在实现计划 P3 拆掉。渲染层有一条自反雷已排:页面说明行不得出现成对的标记字面量,否则下一轮抽取会把说明行当成保留区(回归锁在 `test/wiki-t0.test.js` 的字节稳定用例里)。
27+
- **plan.yaml 是正面控制**(D7):include/exclude(gitignore 子集:无斜杠模式任意层级、前导斜杠锚定、反选、目录尾斜杠)+ pages 白名单(未列出的模块不建页,模板与笔记原文进页)+ `max_files_per_page`;**未知键整轮拒绝**并报出键名与允许列表——拼错的键等于失效的控制,不能静默忽略。
28+
- **CLI 独立成 bin**(CONTRIBUTING「cli.mjs 零依赖契约」禁止加 import,循 `dsh-mneme-serve` 先例):`dsh-mneme-choro <repo> [--apply] [--db <path>] [--json]`,缺省 dry-run(reclaim 同款纪律);非 git 仓库整轮拒绝(锚点无法核验);写路径断言 `.chorography/` 前缀,契约测试对整仓做树快照——apply 后除 `.chorography/**` 外一个字节都不变、不得出现 `.github/`、`.gitignore`、`AGENTS.md`(openwiki 那两个坏习惯在这里判死)。新增唯一运行时依赖 `yaml`(plan.yaml 是用户手写的配置面,手写子集解析器会静默错解,实现计划 P1)。
29+
- **验证**:39 例新测试(`test/wiki-{plan,scan,partition,store,t0}.test.js`:单元 + 字节稳定 + 红线契约 + 库幂等);V2(import 图在三个真实仓库上的划分质量要人判)待人跑,跑法记在实现计划「待实测回填」。M1(面板 + 只读工具 + 检索)、M2(T1 生成轮)、M3(注入)不在本批次。
1530

1631
- **记忆库从「侧栏 footer 挤一个入口 + 居中浮层」改成宿主原生面板位:侧栏一颗图标进 `sidebar.panellist`,正文落 `main` 整页(参照 dsh-baleen,用户 2026-11-04 提的)**:此前唯一的完整入口是 `sidebar.footer.action`,点开是一个 `createPortal` 到 `document.body` 的居中浮层——它不是宿主的面板,占着屏幕中央却不参与宿主的布局与导航状态,Esc/焦点环/背板点击都得自己实现一遍,而截图里它看起来又很像「一个新窗口」。宿主早就给了成对的座位:`sidebar.panellist`(侧栏面板列表,list 槽)与 `main`(正文区,keyed 槽),侧栏一行的点击由宿主 `PanelRow` 自己调 `layout.selectPanel(id)`,插件只交一颗图标和一片内容。**main 的 `key` 必须与侧栏的 `id` 逐字相同**(两者都取 `dsh-mneme`)——宿主按 `options.key` 在 keyed 槽里找 entry,对不上会抛 `layout.selectPanel: main panel "…" is not registered`;这条不是防御性写作,是宿主 `layout.js` 里真会抛的那一行。
1732

0 commit comments

Comments
 (0)