Skip to content

Commit 952f307

Browse files
authored
Merge pull request #570 from slow-stack/feat/chorography-m1
feat(choro): M1——仓库地志面板(浏览)+ 三个只读工具 + 关键词检索
2 parents 8768fc2 + cbbb8a0 commit 952f307

28 files changed

Lines changed: 1663 additions & 17 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +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) |
54+
| 仓库地志(chorography) | `src/wiki/{plan,scan,partition,render,t0,queries}.js` + `bin/dsh-mneme-choro.mjs`(表在 store 六张 `choro_*`) | 仓库 → 确定性骨架页(T0 零模型)+ plan.yaml 正面控制;**wiki 行永不进记忆行池 / dream / 质量过滤**。消费面 M1 已接:面板第二座位 `dsh-mneme-wiki` + 三只读工具 + `/choro/*` 读路由(`chorographyEnabled` 闸,关 = 工具不注册 / 路由 409);M2 T1 生成轮、M3 注入未动。spec:[docs/specs/2026-11-04-chorography-design.md](docs/specs/2026-11-04-chorography-design.md) |
5555
| 检索辅助 | `src/search/{bm25,adaptive}.js`、`src/vector-index.js`、`src/embedding.js`、`src/local-embedder.js`、`src/reranker.js` | BM25 / 自适应阈值 / 向量索引 / 嵌入 / 重排 |
5656
| 热度 | `src/heat.js` | 纯函数遗忘曲线(opt-in) |
5757
| 复用统计 | `src/recall-stats.js` | recall_runs 只读聚合(#217,Top-N 召回 + 僵尸率) |

‎SECURITY.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ The token is a lock on the **write** surface, not a wall around the whole API.
153153

154154
- **The real boundary is loopback + the DSH host listener.** The host-side routes (`/api/dsh-mneme/*`) are mounted on the DSH port, which binds `127.0.0.1` and is fenced by the host against DNS rebinding and cross-site browser requests. That fence does **not** establish identity: any local process, and any page running in the host's own origin, is inside the perimeter.
155155
- **Authentication is opt-in and fail-open.** `apiToken` defaults to empty; while it is empty, `isAuthorized()` returns true for every request — reads *and* writes. Setting a token gates the write routes and the sensitive reads; it does not gate plain reads.
156-
- **Open reads (no token even when one is configured)**: `GET /`, `/info`, `/version-check`, `/list`, `/recall-stats`, `/search`, `/semantic`, `/semantic/llm-audit`, `/semantic/llm-audit/stats`, `/semantic/consolidation-stats`, `/semantic/graph/*`, `/entities`, `/memories/entities`, `/dream-status`, `/inject-status`, `/inject-preview`, `/pipeline`, `/candidates`, `/llm-providers`, `/config-keys`, plus the `GET`/`HEAD` branches of `/profile`, `/rules`, `/persona`, `/mode`, `/features`, `/commands`, `/nudge`, and of the two share-receive routes `/receive` and `/receive/undo`. Treat them as readable by anything local. `/receive` and `/receive/undo` belong on this list even though they write: under the `token-write` policy, `needsToken()` exempts `GET`/`HEAD` from the token, so the only thing genuinely open on those two paths is a `405` — no read branch exists. This section mirrors the policy declarations rather than anyone's intent, which is why a write route shows up under "open reads"; `dsh-mneme/test/security-doc.test.js` compares both lists against the routes actually mounted, in both directions.
156+
- **Open reads (no token even when one is configured)**: `GET /`, `/info`, `/version-check`, `/list`, `/recall-stats`, `/search`, `/semantic`, `/semantic/llm-audit`, `/semantic/llm-audit/stats`, `/semantic/consolidation-stats`, `/semantic/graph/*`, `/entities`, `/memories/entities`, `/dream-status`, `/inject-status`, `/inject-preview`, `/pipeline`, `/candidates`, `/llm-providers`, `/config-keys`, plus the `GET`/`HEAD` branches of `/profile`, `/rules`, `/persona`, `/mode`, `/features`, `/commands`, `/nudge`, of the two share-receive routes `/receive` and `/receive/undo`, and of the four chorography read routes `/choro/repos`, `/choro/modules`, `/choro/page`, `/choro/search` (M1: they read repo-local wiki pages and `choro_*` index tables — not memory rows; with `chorographyEnabled` off they uniformly answer `409 disabled`, the #497 mount-anyway-gate-in-logic pattern). Treat them as readable by anything local. `/receive` and `/receive/undo` belong on this list even though they write: under the `token-write` policy, `needsToken()` exempts `GET`/`HEAD` from the token, so the only thing genuinely open on those two paths is a `405` — no read branch exists. This section mirrors the policy declarations rather than anyone's intent, which is why a write route shows up under "open reads"; `dsh-mneme/test/security-doc.test.js` compares both lists against the routes actually mounted, in both directions.
157157
- **Gated routes (when a token is configured)**: every write — `/create`, `/update`, `/delete`, `/import`, `/bootstrap`, `/vector-config`, `/vector-reindex`, `/runtime/provision`, `/maintenance/reclaim`, `/test-model`, `/conflicts/resolve`, `/profile/extract` (POST-only: one host-LLM call that returns a profile **draft**; other methods get 405 before any side effect), `/receive`, `/receive/undo` (the two share-receive routes write into *this* machine's library, which is why they are `token-write`), and the non-`GET` branches of `/profile`, `/rules`, `/persona`, `/mode`, `/features`, `/commands`, `/nudge` — plus six reads: `/export`, `/external-api`, `/conflicts`, `/health`, `/share`, `/memory/provenance`. `/share` is gated because the share pack is a whole-library read delivered over POST, and it answers 405 to GET — no open read path exists. `/memory/provenance` is gated because it returns the **verbatim raw text** of distilled conversation windows (opt-in via `distillRecords.enabled`); chained with the open list route it would otherwise let any local process enumerate ids and then pull that text back, which reaches the same result as `/export` in a different shape.
158158
- **The standalone data plane** (`127.0.0.1:8790`) is the opposite shape: every route except `GET /health` requires its own Bearer token. Pointing `externalApiHost` at a non-loopback address therefore turns it into a plaintext, token-only HTTP surface — an explicit operator decision.
159159
- **Consequence**: if you expose the plugin beyond loopback (reverse proxy, non-loopback bind), set `apiToken` *and* check that the plain reads above are acceptable to expose — they are not covered by it.
@@ -539,7 +539,7 @@ Token 是**写**面上的锁,不是把整个 API 围起来的墙。
539539

540540
- **真正的边界是回环 + 宿主监听器。** 宿主侧路由(`/api/dsh-mneme/*`)挂在 DSH 端口上,该端口绑 `127.0.0.1`,并由宿主挡掉 DNS rebinding 与跨站浏览器请求。这道围栏**不建立身份**:任何本地进程、以及任何跑在宿主同源页面里的脚本,都在这道围栏之内。
541541
- **鉴权是 opt-in 且 fail-open。** `apiToken` 默认为空;为空期间 `isAuthorized()` 对每个请求都返回 true——读和写都放行。配了 token 之后,它守的是写路由与敏感读,不守普通读。
542-
- **开放读(即使配了 token 也不需要)**:`GET /`、`/info`、`/version-check`、`/list`、`/recall-stats`、`/search`、`/semantic`、`/semantic/llm-audit`、`/semantic/llm-audit/stats`、`/semantic/consolidation-stats`、`/semantic/graph/*`、`/entities`、`/memories/entities`、`/dream-status`、`/inject-status`、`/inject-preview`、`/pipeline`、`/candidates`、`/llm-providers`、`/config-keys`,以及 `/profile`、`/rules`、`/persona`、`/mode`、`/features`、`/commands`、`/nudge`、`/receive`、`/receive/undo` 的 `GET`/`HEAD` 分支。把它们当作「本地任何东西都能读」。`/receive`、`/receive/undo` 明明是写路由也出现在这一串里,这不是笔误:`token-write` 下 `needsToken()` 对 `GET`/`HEAD` 免 token,所以这两条路径上真正「开放」的只有一个 `405`,压根没有可读分支。这一节照 policy 声明抄、不照意图写,`dsh-mneme/test/security-doc.test.js` 会拿真实装配出来的路由双向比对这两行。
542+
- **开放读(即使配了 token 也不需要)**:`GET /`、`/info`、`/version-check`、`/list`、`/recall-stats`、`/search`、`/semantic`、`/semantic/llm-audit`、`/semantic/llm-audit/stats`、`/semantic/consolidation-stats`、`/semantic/graph/*`、`/entities`、`/memories/entities`、`/dream-status`、`/inject-status`、`/inject-preview`、`/pipeline`、`/candidates`、`/llm-providers`、`/config-keys`,以及 `/profile`、`/rules`、`/persona`、`/mode`、`/features`、`/commands`、`/nudge`、`/receive`、`/receive/undo`、`/choro/repos`、`/choro/modules`、`/choro/page`、`/choro/search` 的 `GET`/`HEAD` 分支。把它们当作「本地任何东西都能读」。`/receive`、`/receive/undo` 明明是写路由也出现在这一串里,这不是笔误:`token-write` 下 `needsToken()` 对 `GET`/`HEAD` 免 token,所以这两条路径上真正「开放」的只有一个 `405`,压根没有可读分支。`/choro/*` 四条(chorography 仓库地志读侧,M1)读的是**仓库里的 MD 页与 choro_* 索引表**,不是记忆行——内容是代码仓库的公开文档面,`chorographyEnabled` 关着时四条统一回 409 disabled(路由挂着、逻辑层挡,#497 先例),不因为开放读而绕过这个闸。这一节照 policy 声明抄、不照意图写,`dsh-mneme/test/security-doc.test.js` 会拿真实装配出来的路由双向比对这两行。
543543
- **受门控的路由(配了 token 之后)**:全部写操作——`/create`、`/update`、`/delete`、`/import`、`/bootstrap`、`/vector-config`、`/vector-reindex`、`/runtime/provision`、`/maintenance/reclaim`、`/test-model`、`/conflicts/resolve`、`/profile/extract`(只收 POST:花一次宿主 LLM 产一段画像**草稿**,其它方法在产生任何副作用之前就 405)、`/receive`、`/receive/undo`(这两条写的是**本机自己的库**,所以归 `token-write`),以及 `/profile`、`/rules`、`/persona`、`/mode`、`/features`、`/commands`、`/nudge` 的非 `GET` 分支——外加六条读:`/export`、`/external-api`、`/conflicts`、`/health`、`/share`(分享包是「用 POST 递出来的全库读取」,GET 一律 405,没有开放的读分支)、`/memory/provenance`(它回的是蒸馏窗口的**逐字会话原文**,并自 #512 起按窗口带出 `distill_run_id` / `run_type` / `trigger_source` / `run_status` 的运行归因;`distillRecords.enabled` 打开才有;否则把它和上面那个开放的列表路由串起来,任何本地进程都能先枚举 id、再按 id 把那些原文捞回去——可达结果与 `/export`(一次拿全库)同量级,只是换了形状)。
544544
- **独立数据面**(`127.0.0.1:8790`)是反过来的形状:除 `GET /health` 外每条路由都要自己的 Bearer token。因此把 `externalApiHost` 指向非回环地址,就等于把它变成一个「明文、只靠 token」的 HTTP 面——这是运营者的显式决定。
545545
- **推论**:如果你把插件暴露到回环之外(反代、绑非回环地址),请设 `apiToken`,**并**核对上面那串开放读是否也能被看到——它们不受 token 保护。

‎docs/plans/2026-11-04-chorography-m0.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,20 @@ README(readme-claims 锁的存在使新增能力声明要配证据,M1 一起
4343

4444
V2(import 图在三个真实仓库上的模块划分准不准)跑法:M0 收尾后对
4545
dsh-baleen / dsh-study-desk / 本仓各跑一次 `--apply`,人判划分;结果记回本文件。
46+
47+
### V2 结果(2026-11-05 实测,临时 DB,三仓 `.chorography/` 已落盘待人判)
48+
49+
- **dsh-baleen**(175 文件):默认启发式 15 模块——代码模块形状正确
50+
(lib-adapters 7 文件 6 边 / src-client 16 文件 21 边 / test 40 文件),
51+
但 9 个是会话产物目录(superpowers-sdd-* ×5、docs×2、.qoder-credits)。
52+
写 plan.yaml(include: src/lib/test*/package.json)重跑 → **8 模块全代码**,
53+
正控演示成立(D7 的存在理由被证实:目录初稿没有能力分辨「代码」与「躺在
54+
仓库里的会话产物」)。
55+
- **dsh-study-desk**(58 文件):5 模块里 3 个是 .shots / .v2c / .qoder-credits
56+
——同理收口。点开头目录默认不排除(.shots 可能是截图资产,属用户资产不是
57+
垃圾),是否把「明显会话产物的 dot 目录」进默认排除表**留给维护者拍**。
58+
- **mneme 本仓**(460 文件 → 38 模块):lib/ 与 src/ 互为 sync 副本,默认扫描
59+
全部翻倍(lib 40+29 续、src 40+28 续)——本仓用 plan.yaml 必须排除 lib/
60+
(或 src/);超限切块(-2 续)是字典序不是语义,靠 include 收窄或调
61+
max_files_per_page。结论:**文档没有发现划分算法错误,发现的是默认启发式
62+
的固有边界——正面控制(plan.yaml)就是为这个边界存在的**。
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# chorography M1 实现计划(分支 feat/chorography-m1,叠在 feat/chorography-m0 上)
2+
3+
spec §10 M1 档:**面板浏览 + 三个只读工具 + 关键词检索**。生成 UI 不在本档(M2/M3)。
4+
5+
| # | 决策 | 理由 | 被否备选 |
6+
| --- | --- | --- | --- |
7+
| P8 | 新增 `choro_edges` 表(repo_id, from_slug, to_slug, weight) | spec §7 的 `choro_module_map` 要依赖边,M0 schema 漏了这张;replaceChoroGraph 顺手多删多插一段,幂等语义不变 | 从页面正文反向解析边:脆弱且要二次约定格式 |
8+
| P9 | `chorographyEnabled` 配置键(opt-in 默认关),管**工具暴露**;lightMode 不强制关 | 工具描述常驻模型上下文 = 新增成本,按仓库纪律必须 opt-in + settings 白名单 + 旗标计数锁;choro 无每轮注入物、无热路径挂载,故不进 LIGHT_MODE_OFF(注释写明) | 无开关直接注册:违背自查清单第 1 条 |
9+
| P10 | 检索 = 关键词子串(大小写不敏感,按 `## ` 分节返回命中与行号) | spec §7 的 choro_search 本来就定义成「关键词 + 模块过滤」;向量留给 embedder 接入(V4)后再加 | M1 就上向量:embedder 模型版本绑定问题(V4)未解 |
10+
| P11 | 面板座位**无条件注册**(挂在 #562 的 panellist inject 块内,id/key `dsh-mneme-wiki`),内容层按 features 空态 | inject 同名二次注册的 cordis 语义未知,不赌;开关生效走既有「重启生效」纪律;座位常挂的收敛形态就是 D2 拆双 Cordis 条目 | 独立二次 inject 同名槽:语义没验证过 |
11+
| P12 | 页面正文真源读盘(root_path + rel_path),slug 只从 DB 白名单解析 | 磁盘是唯一真源(spec §4);路径拼装零用户输入 = 零穿越面 | 把正文塞 DB:违反所有权模型 |
12+
| P13 | MD 渲染用 ~80 行手写只读渲染器(先转义再格式化,无原始 HTML 通道) | 面板 bundle 零依赖;知识库阅读体验需要标题/列表/代码块 | 引 marked:破零依赖;裸 `<pre>`:没法读 |
13+
14+
路由四条全 `policy: "open"`(宿主围栏统一鉴权,读操作;SECURITY.md 表同步):GET `/choro/repos`、`/choro/modules?repoId`、`/choro/page?repoId&slug`、`/choro/search?repoId&q&module&limit`。开关关时一律 409 disabled(#497 先例:路由挂着、逻辑层挡)。
15+
16+
工具三个走 tools.js 的 hiddenTools 闸(`chorographyEnabled !== true` → 不注册,同 organizeEnabled 反向语义):`choro_search` / `choro_read_page` / `choro_module_map`,**零写工具**(红线 3)。
17+
18+
面板:左侧模块树(父链缩进)+ 右侧正文 + 顶部搜索框(结果列表 → 点开即页);样式全部复用 `.mneme-panel` 渲染根与 `--mneme-*` 语义色层,不新增渲染根(contrast 五根锁不动)。
19+
20+
待实测回填:V3(宿主 systemPrompt 注入先后与体积)是 M3 的事;本档跑完顺手对三个真实仓库各 `--apply` 一轮给 V2 人判。

0 commit comments

Comments
 (0)