@furongjun1999/dsh-memory 0.5.0 → 0.6.0

package/docs/eval//345/217/221/345/270/20306_/344/270/200/351/224/256/351/205/215/347/275/256/344/270/216DSH0172_v1.0.md

@@ -0,0 +1,171 @@
+# 0.6.0 发布准备报告 v1.0 —— 一键配置 init · DSH 0.17.2 声明 · 版本发布准备
+
+> 批次：0.6.0 发布准备 ｜ 报告：v1.0 ｜ 环境：win32，仓库 `dsh-memory-main`（工作区 HEAD `d7c6e347`）
+> 本报告所引全部检查为本会话（报告撰写会话）**实跑复验**的结果；引用行号均经读取核对。未跑项在第四节与自查双清单中如实声明。
+
+---
+
+## 一、总览
+
+本次 0.6.0 发布准备含三个任务，全部落在工作区未提交改动中（编排会话负责 git commit）：
+
+| # | 任务 | 交付物 | 本会话复验 |
+|---|---|---|---|
+| 1 | **init 一键配置** | 新增 `src/init.ts`（lingshu-init CLI）、`src/cli.ts`（lingshu 主命令分发）、`test/init.test.ts`（6 用例）；`package.json` 补 bin 字段；README 快速开始头部加「一键配置（推荐）」节；WORKSPACE_INDEX.md 重生成 | build/单测/E2E/gate 全过（见第四节） |
+| 2 | **README DSH 0.17.2 声明** | README.md:14 徽章换为「DSH 适配-0.17.2 已验证」；README.md:106 前置行追加「已验证至 DSH 0.17.2」 | 徽章解码 + grep 双计数核过（见第三节） |
+| 3 | **版本 0.6.0 发布准备** | 发布清单就绪（第五节）；`package.json` version 当前仍为 0.5.1（`package.json:3`），0.6.0 bump 属编排待执行动作 | 未执行 version bump / pack / publish（如实声明） |
+
+git 工作区快照（`git status --short` 实测）：` M README.md`、` M WORKSPACE_INDEX.md`、` M package.json`、` A src/cli.ts`、` A src/init.ts`、` A test/init.test.ts`（intent-to-add 登记，与「git add -N」口径一致）、`?? lingshu-mcp-snippet.json`（见第六节第 6 条）。
+
+---
+
+## 二、init 命令设计与实现
+
+### 2.1 目标
+
+一键配置命令：`npx @furongjun1999/dsh-memory init`。新增 `src/init.ts`（lingshu-init CLI 主实现）、`src/cli.ts`（lingshu 主命令分发）、`test/init.test.ts`；`package.json` 补 bin 字段；README.md 快速开始节头部加「一键配置（推荐）」小节；WORKSPACE_INDEX.md 重生成。**未动** `src/index.ts`（DSH 插件入口）与 `src/lib/`（仅 import 复用）。未 git commit（编排会话负责；三个新文件已登记进 git 索引面）。
+
+### 2.2 实现要点（行号均经本会话读取核对）
+
+**src/init.ts（新增，348 行）**：导出 `runInit(argv, opts)`（src/init.ts:239）、`buildSnippet`（src/init.ts:106）、`defaultMemoryRoot`（src/init.ts:101）。文件尾 `import.meta === pathToFileURL(resolve(process.argv[1]))` 判定直跑，win32 下做大小写兜底比对（src/init.ts:328-338）。
+
+- **交互模式**（无参数/参数不全且 stdin TTY，src/init.ts:256-288）：`node:readline/promises` 三问——①接入端 1=DSH 插件 2=Claude Code 3=Codex CLI 4=通用 MCP ②记忆根目录（缺省 `<home>/.lingshu/memory`，src/init.ts:101-103）③Python 解释器（缺省 `defaultPython()` 按平台 python/python3，src/lib/python_path.ts:42-49）。
+- **非交互**：`--end/--root/--python` 齐即跳过问答；解析容忍 `--flag value` 与 `--flag=value`、跳过一个前导 `--` 分隔符（src/init.ts:216,221）；非 TTY 缺参报错退出 1、点名缺失 flag（src/init.ts:259-266），不挂死。
+- **产出**：①打印所选端 mcp.json 片段——`command`=解释器、`args=['-m','md_cg.mcp_server']`、env 含 `MDCG_ROOT`、`MDCG_PYTHON`、`PYTHONPATH`=包根（`repoRoot()`，src/init.ts:118）、`PYTHONIOENCODING`/`PYTHONUTF8` 编码硬约束、`MDCG_MCP_SURFACE=kernel`、`MDCG_ACTOR` 按端（src/init.ts:109-129）②写 `<cwd>/lingshu-mcp-snippet.json`（src/init.ts:297-298）③后续步骤指引（片段各端放哪、令牌签发 `python -m md_cg.tokens issue ...` 与 README「写入凭据」对应，src/init.ts:136-144、大脑自检、PYTHONPATH 换常驻仓库的提示 src/init.ts:312）。
+- **边界**：不创建目录/不启动服务/不写库（src/init.ts:11-16 头注；输出尾行如实声明 src/init.ts:313）；无时间戳类易变内容（幂等）。零运行时依赖：仅 `node:fs`/`node:os`/`node:readline/promises`/`node:path`/`node:url` + 包内 lib 模块（src/init.ts:29-36 import 清单）。
+- **各端口径**：dsh 端诚实标注「DSH 无全局 mcp.json——推荐走插件形态；下方 JSON 为 MCP 直挂等价形态」（src/init.ts:58），并给出 cordis.yml 对应关系 `config.python` / `config.mdcg.root`（src/init.ts:152-154）。
+
+**src/cli.ts（新增，66 行）**：`lingshu <cmd>` 分发——`'init'` → `runInit`（src/cli.ts:35-38）；无/未知命令打印用法退出 1（src/cli.ts:39-43）；导出 `main` 供测试（src/cli.ts:33）。头注说明三 bin 设计动机（src/cli.ts:5-10）。
+
+**package.json**：`bin = { lingshu→./lib/cli.js, lingshu-init→./lib/init.js, dsh-memory→./lib/cli.js }`（package.json:8-12）。第三个 bin 是 npx 硬要求——包有多 bin 时 npx 只自动运行与包名末段（dsh-memory）同名的 bin，缺它则 `npx @furongjun1999/dsh-memory init` 直接报错（npm npx 多 bin 同名匹配规则）。`files` 数组已含 `lib/` 与 `md_cg/`（package.json:19-29），未改。git diff 实测 package.json 仅 +5 行（bin 块）。
+
+**test/init.test.ts（新增，6 用例，src 行号 :41/:82/:102/:128/:151/:173）**：非交互四端端到端（各端 MDCG_ROOT/MDCG_PYTHON/command/args/actor/编码键逐条断言 + snippet 落盘可 JSON.parse 且与返回一致 + 输出含令牌指引 + 记忆根目录未被创建）；幂等（同参重跑 stdout 逐字节一致 + 文件一致）；交互 mock stdin（PassThrough）走通 DSH 分支与缺省分支；非 TTY 缺参报错点名缺失 flag。测试注释记录 readline 预缓冲坑的实测结论（test/init.test.ts:97-100）。
+
+**README.md:48-66**：「### 一键配置（推荐）」置于「按宿主选择入口」引用块（README.md:68，即原手工三步）之前：npx 命令（:51）、三问与三项产出说明（:54-58）、非交互直跑形态（:63）、init 边界与幂等（:66）、「或继续阅读下方手工步骤」（:66）。
+
+**WORKSPACE_INDEX.md**：`scripts/workspace_index.py --write` 重生成（`--check` 过，见第四节⑤⑥）。快照行实测：HEAD `d7c6e347` · 追踪 1998 件（WORKSPACE_INDEX.md:8），`src/` 14 件（WORKSPACE_INDEX.md:20）。
+
+### 2.3 前 / 后对比
+
+- **前**：部署灵枢需手工多步——读 README 选流程、自己定记忆根目录、手写各端 mcp.json 的 env（README 各端样例里 PYTHONPATH 是 REPLACE_WITH_ABSOLUTE_PATH_TO_dsh-memory 占位符）、自行理解令牌签发；无任何 bin，包不可执行。
+- **后**：一条命令三问即产出所选端可直接复制的 mcp.json 片段 + 落盘文件 + 后续步骤（含按端 actor 的令牌签发命令）；参数齐可非交互直跑；重跑输出一致。DSH 端诚实标注「无全局 mcp.json，JSON 为直挂等价形态，推荐插件形态三步」并给出 cordis.yml 对应关系（config.python / config.mdcg.root）。
+
+### 2.4 语义注记（口径对齐，均已读取核对）
+
+1. 片段 env 口径与 `mdcgChildEnv()`（src/lib/mdcg_client.ts:115-129）对齐——`PYTHONIOENCODING`/`PYTHONUTF8` 是硬约束非可选（中文记忆场景，该函数头注 2026-09-20 读线程崩溃现场）；`MDCG_MCP_SURFACE=kernel` 与既有直挂样例同口径——kernel 面无 `mdcg_*` 细粒度工具，直挂端写入走 `cg(op=write)`+凭据，与插件端「必须 full」的场景（src/lib/mdcg_client.ts:68-74：唯一写入通道是 `mdcg_remember`，kernel 面下写入静默失败）不同，**刻意不跟插件对齐**。
+2. 缺省记忆根 `~/.lingshu/memory` 是本命令的显式缺省并写进 MDCG_ROOT，与插件运行时缺省（`~/.dsh/.dsh-memory`，src/lib/datapath.ts stateRoot()）不同源——片段显式指定即无歧义，两套默认各安其位。
+3. `PYTHONPATH=repoRoot()`（import.meta 向上找 package.json，src/lib/datapath.ts:41-56）：npx 场景指向 npx 缓存中的包根（files 含 md_cg/ 故随包可用），输出含「建议换 git clone 常驻仓库路径（免疫 npx 缓存清理）」的诚实提示（src/init.ts:312）。
+4. `MDCG_PYTHON` 键对直挂端是文档性（解释器由 command 决定），对 DSH 插件端真实生效（`defaultPython()` 读 env 覆盖，src/lib/python_path.ts:46-47）——输出文案如实区分（src/init.ts:122）。
+5. readline 对「attach 前预缓冲且不 end」的 PassThrough 只消费第一行（隔离实验结论：首问 OK 次问 ERR_USE_AFTER_CLOSE/question 永久 pending），可靠形态是先启动 runInit 再逐问 write——该结论已写进测试注释（test/init.test.ts:97-100），后来者不必重踩。
+
+---
+
+## 三、README 更新（DSH 0.17.2 声明）
+
+### 3.1 改动（两处）
+
+1. **README.md:14 徽章行**：DSH 适配徽章 URL 由 `badge/DSH%20%E9%80%82%E9%85%8D-%3E%3D0.1.2--rc.1-4E9BF1` 换为 `badge/DSH%20%E9%80%82%E9%85%8D-0.17.2%20%E5%B7%B2%E9%AA%8C%E8%AF%81-4E9BF1`。
+2. **README.md:106 前置行**：「DSH 内核 ≥ 0.1.2-rc.1」后插入「· **已验证至 DSH 0.17.2**」。
+
+- 前：`![DSH 适配](https://img.shields.io/badge/DSH%20%E9%80%82%E9%85%8D-%3E%3D0.1.2--rc.1-4E9BF1)` ／ 后：`![DSH 适配](https://img.shields.io/badge/DSH%20%E9%80%82%E9%85%8D-0.17.2%20%E5%B7%B2%E9%AA%8C%E8%AF%81-4E9BF1)`
+- 前置行 前：`- **前置**：Node ≥ 22.19 · DSH 内核 ≥ 0.1.2-rc.1 · **大脑零安装**…` ／ 后：`- **前置**：Node ≥ 22.19 · DSH 内核 ≥ 0.1.2-rc.1 · **已验证至 DSH 0.17.2** · **大脑零安装**…`
+
+### 3.2 行号勘误与兼容性小节说明
+
+- **行号勘误**：任务书写「:86 前置行」，实际前置行在 README.md:106（:86 现为 cordis.yml 示例的 `mdcg:` 配置行，本会话读取核实）——系工作区已有未提交的「一键配置」init 段（+20 行）导致行号漂移，已按文案「DSH 内核 ≥ 0.1.2-rc.1」精确定位修改。
+- **兼容性/版本对照小节**：README 全文检索无独立小节（仅文档导航表指向外部历史文档），按任务书第 3 条未新建。
+- 语义上「≥ 0.1.2-rc.1」的最低要求声明**保留不动**，仅追加「已验证至 0.17.2」的上界事实；徽章与前置行两处表述一致（徽章版本表述与正文一致性纪律）。
+- **未触碰**：Release 历史段与 COGMAP 标记段——git diff 实测 README.md 全部 3 个 hunk 为：①`@@ -11,7` 徽章行 ②`@@ -45,6` 一键配置段（+20 行，会话开始前工作区已有的 init 功能未提交改动，非本任务所改）③`@@ -83,7` 前置行。两目标行各在其 hunk 内，无越界改动。
+
+### 3.3 本会话复验输出
+
+- `node -e "console.log(decodeURIComponent('DSH%20%E9%80%82%E9%85%8D-0.17.2%20%E5%B7%B2%E9%AA%8C%E8%AF%81-4E9BF1'))"` → **`DSH 适配-0.17.2 已验证-4E9BF1`**——徽章文字与颜色逐一核对无误。
+- `grep -n "0\.1\.2" README.md` → 仅 README.md:106 一行（最低要求项；旧徽章形态 `>=0.1.2--rc.1` 已消失）；`grep -n "0\.17\.2" README.md` → 恰为 README.md:14 与 README.md:106 两处。
+- `grep -c "COGMAP:BEGIN" README.md` → **1**，标记段完好。
+- `python scripts/cogmap_sync.py check`（gate 内实跑）→「cogmap check: 通过（cg 36 op / stg 4 op / whitebox 6 action / mdcg_* 31 个…全部一致）」——gate 未因本次修改报错。
+- **未做**：真机 DSH 0.17.2 配合验证（任务书声明用户已实测，本任务只做文档声明）。
+
+---
+
+## 四、验证（本会话全部实跑复验）
+
+| # | 检查 | 命令 | 实测结果 | 判定 |
+|---|---|---|---|---|
+| ① | build | `npm run build` | exit=0；`ls` 确认 lib/init.js、lib/cli.js 生成；`head -1` 两文件均为 `#!/usr/bin/env node`（shebang 保留） | **通过** |
+| ② | init 单测 | `node --import tsx --test --test-timeout=15000 test/init.test.ts` | tests 6 / pass 6 / fail 0（四端 E2E、幂等、交互 DSH 分支、交互缺省分支、非 TTY 缺参、缺省根口径） | **通过** |
+| ③ | 全量测试 | `npm test` | exit 0；tests 59 = pass 58 + skipped 1 + fail 0（skip 为既有 python-utf8-mode 环境性用例「内层 locale 已是 utf-8，无从构造 gbk 现场」，与本次改动无关） | **通过** |
+| ④ | init E2E 真跑 | 临时目录实跑（见下） | 编译产物直跑全链 | **通过** |
+| ⑤ | gate | `npm run gate` | exit 0：check_unreachable VERDICT=PASS（FAIL 规则=0）/ cogmap check 通过 / link_check 228 OK·0 BROKEN / workspace_index --check [OK] 顶层 20·追踪 1998 / verify_discipline 结论 9/9 目标一致 | **通过** |
+| ⑥ | 索引守卫单跑 | `python scripts/workspace_index.py --check` | `[OK ] 工作区索引与仓库一致（顶层目录 20 · 追踪 1998 件）`，exit 0 | **通过** |
+
+**④ E2E 细节**（临时目录，测毕已清理，不触真实 `~/.lingshu` 与在役库）：
+
+- `node lib/init.js --end claude --root <tmp>/mem --python python3` → exit=0；stdout 含 MDCG_ROOT×2、`md_cg.tokens issue`、`README「写入凭据」`、「建议换成 git clone」提示；`lingshu-mcp-snippet.json` 落临时目录且 `JSON.parse` 通过（MDCG_ROOT 指向 `<tmp>/mem`、ACTOR=claude-code）；`<tmp>/mem` **未创建**（test 判定）。
+- 同参数重跑 → `diff run1.txt run2.txt` 为空（**stdout 幂等**）。
+- `node lib/cli.js init -- --end dsh --root <tmp>/mem2 --python python` → exit=0（分发 + `--` 分隔符 + dsh 端 `MDCG_ACTOR: "dsh-memory"` 与令牌 actor dsh-memory 实测）。
+- `node lib/cli.js`（无命令）→ 打印用法 exit=1；`node lib/cli.js badcmd` → exit=1。
+- `node lib/init.js`（非 TTY 缺参）→ exit=1，stderr：`lingshu-init：非交互环境（stdin 非 TTY）必须给齐参数：--end --root --python。示例：…`。
+
+**未验证（如实声明）**：
+
+- a) `npx @furongjun1999/dsh-memory init` **联网安装全链路未跑**——需发布含 bin 的新版本后 npx 才可能从 registry 拉到；本会话验证的是其依赖的机制（bin 声明 + lib/cli.js、lib/init.js 直跑行为）与 npm npx 多 bin 同名匹配规则。
+- b) **真实 TTY 下人工交互问答未跑**（本会话无交互终端），由单测 mock stdin 覆盖同一代码路径（DSH 分支 + 缺省分支，test/init.test.ts:102/:128）。
+- c) `npm version 0.6.0` / `npm pack --dry-run` / `npm publish` **未执行**——属第五节编排待执行清单。
+
+**另注（WORKSPACE_INDEX 陈化）**：索引重生成把此前的陈化欠账一并刷新（快照 HEAD `2e9bfe8`→`d7c6e347`、追踪 1828→1998 件，src/ 12→14 中本次贡献 2 件）——该陈化在本次改动前已存在（此前提交未重生成索引），不回滚（回滚会使 gate 的索引守卫在当前树上亮红）。
+
+---
+
+## 五、发布清单（编排待执行）
+
+以下动作**本会话未执行**，按序待编排/使用者完成：
+
+1. `npm version 0.6.0`——当前 version 仍为 0.5.1（package.json:3 实读）。
+2. `npm pack --dry-run`——核对 files 集合（lib/、md_cg/、skills/ 等，package.json:19-29）与 bin 三键（package.json:8-12）入包形态。
+3. `npm publish`——需使用者终端凭据；`prepublishOnly` 钩子（package.json:88）将自动串联 `npm run build && npm test && npm run gate`（三者本会话均已预验通过）。
+4. 发布后补验：`npx @furongjun1999/dsh-memory init`（清 npx 缓存后）——registry 拉到含 bin 版本后的一键配置全链路终验。
+5. git commit 由编排会话统一负责（本会话未 commit，遵守纪律）。
+
+---
+
+## 六、纪律合规声明
+
+1. **零运行时依赖**：init/cli 仅 import `node:fs`/`node:os`/`node:readline/promises`/`node:path`/`node:url` + 包内 lib 模块（src/init.ts:29-36、src/cli.ts:14-16 实读），未加 prompts/inquirer 等第三方依赖。
+2. **实验只在临时目录**：E2E 全部落 `mktemp -d` 临时目录并以 `--root` 指向临时路径，未触真实 `~/.lingshu`、未触在役库；测毕 `rm -rf` 并复核不存在。单测同口径（test/init.test.ts:14-15 头注「不 spawn python、不触碰 ~/.lingshu、不触真实记忆库」）。
+3. **不写本机绝对路径**：本报告路径一律仓库相对形态（临时目录以 `<tmp>` 代指）。
+4. **未 git commit**：工作区保持编排会话负责提交的形态。
+5. **诚实报告**：第四节列出全部未验证项（npx 联网链路/真 TTY 交互/version+pack+publish/真机 DSH 0.17.2 配合验证），无一项填充为「已通过」。
+6. **现场遗留说明**：仓库根有一份前会话遗留的未跟踪 `lingshu-mcp-snippet.json`（MDCG_ROOT 指向 `.lingshu-init-e2e-root`，该目录确认不存在）。本会话复验时曾因在仓库根直跑 init 被 `process.cwd()` 语义覆盖此文件（init 按设计把片段写到当前目录），已当即用同参数重跑恢复（恢复后 MDCG_ROOT 实读核对为 `.lingshu-init-e2e-root`）。该文件属前会话 E2E 遗留产物、未跟踪，是否清理由编排会话决定——**注意**：其 MDCG_ROOT 指向的仓库内路径不可作为真实记忆根使用（勿把记忆写进插件包目录，README cordis.yml 示例同此警示）。
+
+---
+
+## 附：自查双清单
+
+### 清单一：已验证清单（本会话实跑，全部有命令+输出）
+
+| 检查 | 命令/方式 | 结果 |
+|---|---|---|
+| 构建 | `npm run build` | exit 0；lib/init.js + lib/cli.js 生成，shebang 保留 |
+| init 单测 | `node --import tsx --test --test-timeout=15000 test/init.test.ts` | 6/6 pass，0 fail |
+| 全量测试 | `npm test` | exit 0；59 = 58 pass + 1 skip（既有环境性）+ 0 fail |
+| E2E 非交互 | `node lib/init.js --end claude --root <tmp>/mem --python python3`（临时目录） | exit 0；片段+落盘+JSON 可解析+记忆根未创建 |
+| E2E 幂等 | 同参重跑 `diff run1.txt run2.txt` | 空（逐字节一致） |
+| E2E 分发 | `node lib/cli.js init -- --end dsh --root <tmp>/mem2 --python python` | exit 0；端=DSH 插件；actor=dsh-memory |
+| E2E 用法/错误 | `node lib/cli.js`、`badcmd`、`node lib/init.js`（非 TTY 缺参） | 各 exit 1；报错点名 --end --root --python |
+| gate | `npm run gate` | exit 0；五守卫全绿 |
+| 索引守卫 | `python scripts/workspace_index.py --check` | [OK] exit 0 |
+| 徽章文字 | `node -e decodeURIComponent(...)` | 「DSH 适配-0.17.2 已验证-4E9BF1」 |
+| README 计数 | `grep -n "0\.1\.2"` / `"0\.17\.2"` / `grep -c "COGMAP:BEGIN"` | 仅 :106 最低要求项 ／ 恰 :14+:106 两处 ／ 标记段=1 |
+| diff 范围 | `git diff README.md` hunk 清点 | 3 hunks：徽章 / 一键配置段（会话前已有）/ 前置行 |
+| 引用行号 | 读取 src/init.ts、src/cli.ts、test/init.test.ts、package.json、README、src/lib 三件 | 全部核对一致 |
+
+### 清单二：未验证与欠账清单（如实声明，编排可循）
+
+| 项 | 状态 | 原因 / 后续 |
+|---|---|---|
+| `npx @furongjun1999/dsh-memory init` 联网全链路 | 未跑 | registry 需发布含 bin 版本；发布后按第五节 4 补验 |
+| 真实 TTY 人工交互问答 | 未跑 | 本会话无交互终端；单测 mock stdin 覆盖同一代码路径 |
+| `npm version 0.6.0` / `npm pack --dry-run` / `npm publish` | 未执行 | 编排待执行；publish 需使用者终端凭据；当前 version=0.5.1 |
+| 真机 DSH 0.17.2 配合验证 | 未跑 | 任务书声明用户已实测，本次仅文档声明 |
+| python-utf8-mode 1 例 skip | 维持 skip | 既有环境性用例（内层 locale 已是 utf-8），与本次改动无关 |
+| 仓库根遗留 `lingshu-mcp-snippet.json` | 待编排决定 | 前会话 E2E 遗留、未跟踪；本会话已恢复原内容；MDCG_ROOT 指向路径不可作真实记忆根 |