@a9i5k4/dsh-auto-memory 2.4.1 → 2.5.0

package/docs/internal/GROUP-DIGEST-SETUP.md

@@ -0,0 +1,62 @@
+# 群同步日报(GROUP-DIGEST)部署说明
+
+> 2026-09-12 搭建。每天北京时间 **12:00 / 21:00** 由 **GitHub Actions** 自动统计仓库
+> issues / PRs / commits / release,生成中文摘要投递到 QQ 群「dsh-auto-memory交流群」。
+> 跑在 GitHub 云端,**本机电脑关机也照常执行**;本机从未登录任何 QQ 协议端。
+
+## 文件清单
+
+| 文件 | 作用 |
+| --- | --- |
+| `.github/workflows/group-digest.yml` | 定时(UTC 4:00/13:00)+ 手动触发入口;凭据走 secrets/vars |
+| `.github/scripts/group-digest.mjs` | 统计 + 生成 + 多通道投递,零依赖;`--print` 本机试跑 |
+| `.github/scripts/qq-capture-openid.mjs` | 一次性工具:连官方 WS 网关抓群 `group_openid`(仅本机跑) |
+| `.github/digest/NOTES.md` | 人工备注区:写了什么,群消息「备注」栏就带什么(改完要上 main 才生效) |
+| `.github/digest/PREVIEW.md` | 「下版本前瞻」板块文案:网页编辑,写几行就整块出现在日报里,留空隐藏 |
+| `tools/release.mjs` | 复制白名单已加 `.github` → 以后每次发版自动带到 REL 树,不会被发版清掉 |
+
+**窗口口径**=上一次「成功」的 workflow run → 现在;错过一次自动并进下一次,封顶 7 天。
+**发送失败**的 run 记为失败(不重置窗口);**未配置通道**时 run 成功,消息只归档到 run 页面。
+
+## 通道配置(仓库 Settings → Secrets and variables → Actions)
+
+先设仓库**变量** `DIGEST_CHANNEL`(variables 区,非 secret),再按下表配 secrets:
+
+| 通道 | DIGEST_CHANNEL 值 | 需要的 secrets | 说明 |
+| --- | --- | --- | --- |
+| QQ 官方机器人(推荐) | `qq_official` | `QQ_APP_ID` / `QQ_APP_SECRET` / `QQ_GROUP_OPENID` | 零服务器、零封号风险;QQ 群消息**禁止 URL**,脚本自动剥链接 |
+| NapCat(OneBot11) | `napcat` | `NAPCAT_HTTP_URL` / `NAPCAT_GROUP_ID` /(`NAPCAT_TOKEN`) | 功能最全,可加「群内反馈」采集(见下);需一台常开设备 |
+| Telegram | `telegram` | `TG_BOT_TOKEN` / `TG_CHAT_ID` | 最简单,2 分钟配完 |
+| Discord / 飞书 / 钉钉 / 自定义 | `discord` / `feishu` / `dingtalk` / `generic` | 对应 `*_WEBHOOK_URL` | 备用/转发用 |
+
+### A. QQ 官方机器人(推荐路径)
+
+1. [q.qq.com](https://q.qq.com) 注册开发者 → **个人身份证认证**(主动消息频控:认证后 60 条/分钟、单群 1000 条/天,每天 2 条绰绰有余;未认证 30/分钟也够)。
+2. 创建机器人(名字建议 `auto-memory 助手`),拿到 AppID / AppSecret。
+3. 群主把机器人添加进群(机器人管理页 → 添加到群聊)。
+4. 本机抓 `group_openid`(开放平台不直接展示,只随「@机器人」事件下发):
+   ```
+   QQ_APP_ID=xxx QQ_APP_SECRET=xxx node .github/scripts/qq-capture-openid.mjs
+   # 然后在群里发一条「@机器人 你好」,脚本会打印 group_openid
+   ```
+5. 配 secrets + 变量 → Actions 页手动触发 `group-digest` 验证。
+
+### B. NapCat(顺带把"群内问题反馈"带进日报)
+
+在任一常开设备(旧安卓手机 Termux / 学生机 / NAS)Docker 跑 [NapCat](https://napneko.github.io),
+开 OneBot11 HTTP 服务(如 `http://IP:3000`,建议配 access_token)。
+之后把采集地址填到 secret `FEEDBACK_URL`(relay 提供 `GET /feedback?hours=N` 返回
+`{"items":[{"user","text"}]}`),日报自动多一栏「群内反馈」。relay 可后补,不阻塞日报上线。
+
+### C. 其他平台 webhook
+
+TG / Discord / 飞书 / 钉钉按表配即可,适合"先进别的群/推给自己,再转发 QQ 群"的过渡期。
+
+## 测试与运维
+
+- **手动试跑**:GitHub 仓库 → Actions → group-digest → Run workflow(可填 `since_hours=24`)。
+  消息全文写在 run 的 Summary 里,发送结果看日志最后一行。
+- **临时改备注**:直接在 GitHub 网页编辑 main 的 `.github/digest/NOTES.md`,下次统计生效。
+- **已知限制**:GitHub schedule 可能有 5~30 分钟调度延迟(照常按窗口统计,不丢数据);
+  首次运行窗口=过去 12 小时;secret 没配齐时该通道报错,run 页面能直接看到原因。
+- **改文案/格式**:`group-digest.mjs` 的 `compose()`;改动要走 pre 树 + 发版流程,或直接网页改 main(下次发版前会被 pre 版本覆盖,注意同步)。

package/docs/internal/GROUP-LISTENER-SETUP.md

@@ -0,0 +1,49 @@
+# 群反馈闭环(GROUP-REPORT)部署说明
+
+> 2026-09-13 搭建。日报(见 `GROUP-DIGEST-SETUP.md`)之外的第二条链路:**群员在 QQ 群里汇报问题
+> → 自动建 GitHub issue → 状态回执「收到 ✅ / 正在处理 🔧 / 处理完毕 ✅」双端同步(QQ 群一句话 + issue 结构化评论)**。
+> 修理工可以是 Copilot(把 issue 分配给 @copilot),也可以是人。
+
+## 状态词汇表(和群主口头回复一致)
+
+| 状态 | 触发点 | QQ 群播报 | GitHub issue |
+| --- | --- | --- | --- |
+| 收到 ✅ | 群反馈建单 | `收到 ✅ 群反馈已建单 #N「…」,处理进度会同步` | 「收到 ✅」评论 |
+| 正在处理 🔧 | PR 开出且引用该 issue | `正在处理 🔧 群反馈 #N → PR #M「…」` | 「正在处理 🔧」评论 |
+| 处理完毕 ✅ | issue 关闭(合并自动关单也算) | `处理完毕 ✅ 群反馈 #N「…」已解决` | 「处理完毕 ✅」评论 |
+
+## 组成
+
+| 文件 | 作用 |
+| --- | --- |
+| `.github/workflows/group-report-status.yml` | 状态机:issues opened/labeled/closed + PR opened/reopened → 双端同步 |
+| `.github/scripts/report-sync.mjs` | 状态判定 + issue 评论 + QQ 播报(云端) |
+| `.github/scripts/qq-send.mjs` | QQ 发送共享模块 |
+| `.github/scripts/group-listener.mjs` | 「耳朵」:常开设备上连官方网关收群消息 → 建单 → 群里回收到 |
+
+## 群员怎么报问题(两种都通)
+
+1. **在群里说**(需要耳朵在跑):@机器人 并带触发词,如「@automemory 反馈助手 反馈 导出按钮点了没反应」→ 自动建单;
+2. **直接提 GitHub issue**:标题随意,打上 `group-report` 标签 → 同样进入状态闭环(适合贴日志/截图)。
+
+## 耳朵部署(旧安卓手机 Termux)
+
+1. Termux(F-Droid 版)里:`pkg install nodejs-lts git`;
+2. `git clone https://github.com/Aik358/dsh-auto-memory && cd dsh-auto-memory/.github/scripts`;
+3. 建 `.env`(模板见 `group-listener.mjs` 头注释;GH_TOKEN 用**仅 issues:write 的细粒度 PAT**,别复用推送 PAT);
+4. `node group-listener.mjs` → 看到「已上线,监听触发词」即可;
+5. 常驻:关闭 Termux 电池优化 + `termux-wake-lock`;进阶用 Termux:Boot 开机自启。
+
+**约束**:同一机器人同时只允许一个网关连接——耳朵在跑时,勿再跑 `qq-capture-openid.mjs` 或绑定 WorkBuddy(二者互踢)。
+
+## Copilot 当修理工
+
+1. 前提:仓库 Settings → Copilot 开启 coding agent;账号需 Copilot 付费档(GitHub 学生包通常自带 Copilot Pro);
+2. 在群反馈 issue 里 assign `@copilot` → 它开工并开出草稿 PR(正文引用本 issue)→ 状态机自动播「正在处理 🔧」;
+3. 人审合并 → issue 自动关闭 → 自动播「处理完毕 ✅」。
+
+## 测试方法(需先 push 到 main)
+
+1. 建一个测试 issue 打上 `group-report` → 群里应出现「收到 ✅」+ issue 出现评论;
+2. 开个 PR 正文写 `fixes #<测试issue号>` → 群里「正在处理 🔧」;
+3. 关闭测试 issue → 群里「处理完毕 ✅」。

package/docs/internal/GROUP-WEBHOOK-SETUP.md

@@ -0,0 +1,60 @@
+# 群反馈云端耳朵(Webhook)部署说明
+
+> 2026-09-13 搭建(同日改为 AI 归纳路线):**不再自动建 GitHub issue**。云端耳朵把群里命中
+> 反馈词/问题关键词的消息静默收进一个**秘密 Gist**;每天 12:00/21:00 的日报(group-digest)读取
+> gist、调用大模型归纳成带标题的「群内反馈(AI 归纳)」清单随日报发群,并清空 gist 防重复。
+> 前置阅读:状态闭环词汇表见 `GROUP-LISTENER-SETUP.md`(issue 状态机保留但处于休眠,当前无建单方)。
+
+## 组成
+
+| 文件 | 作用 |
+| --- | --- |
+| `.github/cloud/qq-webhook/index.js` | Webhook 接收端(Web 函数,零依赖,任何 Node>=18 环境可跑) |
+| `.github/scripts/group-listener.mjs` | WS 版耳朵(备用:有常开设备时的等价实现,二选一) |
+
+## 部署步骤(腾讯云函数 · Web 函数)
+
+1. 注册腾讯云并完成实名认证 → 控制台搜「函数服务 SCF」;
+2. 新建函数:函数类型选 **Web 函数**,运行环境 **Node.js 18 或 20**,地域就近(如广州/上海);
+3. 函数代码:把 `.github/cloud/qq-webhook/index.js` 打成 zip(就一个文件)上传,执行方法保持默认(`index.main_handler` 不适用 Web 函数,Web 函数看监听端口);
+4. 环境变量(函数配置里加):
+   ```
+   QQ_APP_ID=1905260114
+   QQ_APP_SECRET=<机器人secret>
+   QQ_GROUP_OPENID=D4D52BA3A7412F88E9192011CD4B935A
+   GH_TOKEN=<细粒度PAT,Account permissions → Gists: Read and write(收集用,不碰仓库)>
+   GIST_ID=<秘密 gist 的 32 位 id,文件名 group-feedback.jsonl>
+   REPO=Aik358/dsh-auto-memory
+   ROUTE_TOKEN=<自造一段随机字符串,防扫描>
+   FEEDBACK_KEYWORDS=问题,bug,报错,error,异常,失效,崩溃,闪退,不能用,出错了,坏了,修复  <可选,收集关键词>
+   LLM_API_KEY=<可选;配了才启用「@ 消息大模型应答」(DeepSeek key 或任意 OpenAI 兼容端点)>
+   LLM_MODEL=deepseek-chat            <可选,默认 deepseek-chat>
+   LLM_BASE_URL=https://api.deepseek.com  <可选,换其他 OpenAI 兼容服务时改>
+   ```
+5. 部署后,函数详情页拿「**访问服务 URL**」(默认公网域名,HTTPS),在末尾拼上 `/<ROUTE_TOKEN>/`;
+6. QQ 新版控制台 → 开发设置 → 「事件订阅与回调地址」→ 接收方式切换 **Webhook** → 粘贴上面的 URL;
+   平台立刻发 op=13 验证请求,我们的服务会自动应答(用 AppSecret 派生 Ed25519 密钥签名),通过即绑定;
+7. 真实验证:群里发「反馈 这是一条测试」→ 应出现:新建 issue(带 group-report 标签)+ 群里「收到 ✅」。
+
+## 关键事实(来自官方文档,2026-09 核对)
+
+- 回调只要求 **HTTPS + 端口 80/443/8080/8443**;文档未要求 ICP 备案(腾讯云函数默认域名可直用;若校验被拒,改用 API 网关触发器或 CloudBase 云接入的默认域名,再不行换 VPS 跑同一份代码);
+- **签名**:seed = AppSecret 自我拼接补足 32 字节 → 派生 Ed25519 密钥对;op=13 用私钥签 `event_ts+plain_token` 回 `{plain_token, signature}`;事件推送用公钥验 `X-Signature-Ed25519`(原文 = 时间戳+原始 body);
+- **切换即生效**:Webhook 与 WebSocket 互斥——切过去后,`qq-capture-openid.mjs`/`group-listener.mjs` 这类 WS 工具就收不到事件了(切回来同理);
+- 建议在函数配置里把 `STRICT_VERIFY=1`(验签严格模式)等真实验证跑通后再开。
+
+## 与 Copilot/修理工的关系
+
+建出的 issue 分配给 @copilot(需 Copilot 付费档,学生包免费)或自行认领;PR 引用 issue 自动播「正在处理 🔧」,关闭自动播「处理完毕 ✅」——由 `group-report-status.yml` 负责,与本耳朵解耦。
+
+## 按需报告接口(给 DeepSeek Harness / 人工用)
+
+```
+GET https://<函数URL>/<ROUTE_TOKEN>/?report=N      # 最近 N 小时(1-48)群反馈
+GET ...?report=12&raw=1                            # 只要原文不要 AI 总结
+```
+返回 JSON:`{ window_hours, total, items:[{t,u,w,m}], summary?, v }`。
+- items=带时间戳的原始反馈;配了云函数 LLM_API_KEY 时附 summary(AI 分诊:问题清单+修复优先级),没配则只有原文——harness 的模型可直接读原文自己分析。
+- 注意:每次日报(11:40/20:40)读完后会清空收集区,所以可查范围≈「自上次日报以来收集的反馈」(与 12h 窗口天然对齐)。
+- DeepSeek Harness 用法:直接 GET 该 URL(浏览器/curl/任意 HTTP 工具),把返回 JSON 交给模型出修复方案;或固化成 auto-memory 的 procedure。
+

package/docs/internal/HANDOFF-TO-ZCODE.md

@@ -0,0 +1,168 @@
+# 交接说明 · 给 ZCode（dsh-auto-memory）
+
+> 写于 2026-09-11 21:4x（UTC+8）· 交接方：DSH 主对话（DeepSeek Harness）
+> **本文件自包含**：ZCode 看不到写这份文档的那个会话的上下文与记忆，读完这一份 + 文末「关键路径表」里的文件即可开工。
+> 一句话项目：**DeepSeek Harness Web GUI 的「主动联想记忆 + 上下文管理」插件**（npm 公开包，1 万+ 下载），当前 **v2.4.2 已发布**。
+
+---
+
+## 0. 现在的状态（先对账，别信旧文档）
+
+| 事项 | 值 |
+| --- | --- |
+| npm 包 | `@a9i5k4/dsh-auto-memory` · latest = **2.4.2**（发布包 218 files / 10.9 MB） |
+| pre 线（开发） | `D:\dsh-auto-memory`，HEAD = `f83e144`（docs 收编）· 已跟踪文件**无未提交改动** |
+| REL 线（发布基座） | `D:\dsh_debug\_publish_dsh-auto-memory`，HEAD = `243dee1`（= tag `v2.4.2` = GitHub main） |
+| GitHub | https://github.com/Aik358/dsh-auto-memory（main = 243dee1） |
+| 本机运行形态 | 插件以**符号链接**挂载：`~/.dsh/profiles/web/node_modules/@a9i5k4/dsh-auto-memory` → `D:\dsh-auto-memory` |
+| 宿主 | 官方 `dsh` **0.1.5-rc.1**，Web GUI 在 `http://127.0.0.1:3080` |
+
+**两条线是平行历史**：pre 线有 `-pre` 后缀（`lib/*-pre.js`、配置 `dsh-auto-memory-pre.json`、路由前缀 `/api/dsh-auto-memory-pre/`），`tools/release.mjs` 会在发布时把它们**裸名化**并重建 REL 树。
+👉 **严禁把 pre 直接 push 到远端 main**；发布只能走下面的固定流程。
+
+---
+
+## 1. 代码结构（没有构建步骤）
+
+| 文件 | 作用 | 规模 |
+| --- | --- | --- |
+| `lib/index.js` | **宿主半边**：记忆引擎 + 配置表 + 全部 HTTP 路由 + 工具注册 | ~8,200 行 |
+| `lib/client.js` | **界面半边**：浏览器 bundle（手写 `__ModuleLoader__`，React + 原生 DOM，零依赖） | ~4,600 行 |
+| `lib/*-pre.js` | 其余宿主模块（检索/水位/接续/语义/Python 侧车…），多数有对应的裸名孪生文件 | — |
+| `python/` | 可选 Python 语义引擎（BGE-M3 int8）+ worker，随包发布 | — |
+| `tests/smoke/*.mjs` | **69 个**冒烟套件（全量回归就是逐个 `node` 跑） | — |
+| `tools/release.mjs` | 发布构建器（pre→正式转换 + 校验闸门） | — |
+| `docs/` | 会被打进 npm 包（**注意**：内部文档目前也在里面） | — |
+
+**关键结构约束**：两个半边是**独立 bundle**，`client.js` 不能 `import` 宿主模块 → 「同一份事实」只能靠**测试锁**保证（已有 `tests/smoke/smoke-test-api-paths-pre.mjs`）。
+
+---
+
+## 2. 怎么验证改动（发版前置门）
+
+```powershell
+cd D:\dsh-auto-memory
+# 全量回归（约 2-3 分钟，必须 0 失败）
+Get-ChildItem tests\smoke -File -Filter *.mjs | ForEach-Object { node $_.FullName > $null 2>&1; if ($LASTEXITCODE -ne 0) { "FAIL: " + $_.Name } }
+# 语法 + 编码
+node --check lib\index.js; node --check lib\client.js
+# 写文件必须 UTF-8 无 BOM（用户硬性规则，BOM 会让 dsh web 起不来）
+```
+
+- **路由数（46）与工具数（14）被多个用例硬锁**；加减路由/工具必须同步改测试。
+- `smoke-test-autocont-host-pre.mjs` 用「方法白名单」式夹具：给被抽方法新增 `this.xxx()` 调用要同步加进白名单，否则 TypeError 被外层 `try/catch` 吞成"没反应"。
+- 单跑原则：个别套件（如 `m53`）在批量连跑时会受机器负载影响，历史上是**单跑**确认。
+
+---
+
+## 3. 发版固定流程（10 步，唯一检查表 `docs/internal/RELEASE-PROCESS.md`）
+
+1. **前置门**：全量回归 0 失败 + **脏树范围核实**（`release.mjs` 的源就是工作区，**脏树会整体进包且不可回溯**）。
+2. 定版本号（纯修复 patch / 有新行为 minor）。
+3. **必改 `CHANGELOG.md`**：新增 `## [<ver>] — <日期> · <主题>` 小节。
+4. **必同步软件内版本标识**：①应用内更新说明字典 `lib/client.js` 的 `var CHANGELOG = { '<ver>': { zh: [...], en: [...] } }` ②界面指纹行 `console.log('[dsh-auto-memory] client v<ver> fingerprint: ...')` ③`package.json.version`（由 release.mjs 自动回写开发树）。
+5. pre 线提交：`git add lib tests CHANGELOG.md tools/release.mjs`（+ 视情况 docs）→ commit（身份 `Aik358 <aik358@users.noreply.github.com>`）。
+6. `node tools\release.mjs <ver> --dry-run` —— 验闸门（应输出 `版本标识一致性: OK(CHANGELOG / 应用内更新说明 / 界面指纹行)`）。
+7. `node tools\release.mjs <ver>` —— 真构建（写 REL 树 + 回写开发树版本）。
+8. REL：`git add -A` → commit → `git tag -f v<ver>`。
+9. push（**必须带 PAT 行内 URL**，见 §5）→ `npm publish`。
+10. **三处复核**：registry `/latest`、`git ls-remote ... refs/heads/main`、`refs/tags/v<ver>` 三者一致。
+
+**第 3、4 步已做成机制**：`tools/release.mjs` §5.05「版本标识一致性闸门」——三项任一不符即 `process.exit(1)` **拒绝构建**（防止"检测更新"一直拿旧版本号比对）。
+
+---
+
+## 4. 环境、凭据与两个坑
+
+- **本机 `~/.npmrc` 指向 npmmirror** → 查询与发布都必须显式 `--registry=https://registry.npmjs.org`，否则会查到旧版本、误判发布失败。
+- **`npm view` 会命中本地缓存**：发布成功后可能仍回读上一版（v2.4.2 发布后回读 2.4.1）。判定用权威接口：
+  `Invoke-RestMethod 'https://registry.npmjs.org/@a9i5k4%2Fdsh-auto-memory/latest' | Select-Object -ExpandProperty version`
+- **凭据不在本仓库**：GitHub PAT 与 npm token 存在另一个工作区的记忆文件里 ——
+  `~/.dsh/memory/workspaces/--D--dsh_debug--/MEMORY.md`（该文件明确标注"只存本地，**严禁写入任何会上传 GitHub/npm 的文件**"）。
+  npm 发布需带 bypass-2FA 的那个 token；推送用 `git -c credential.helper= push https://x-access-token:<PAT>@github.com/Aik358/dsh-auto-memory.git main --tags --force`。
+- **发布后生效**：宿主半边（`lib/index.js`）改动需**用户自己重启 dsh web**；界面半边刷新页面即可。
+
+---
+
+## 5. 不可碰的契约 & 用户硬性规则
+
+- **后端冻结（用户明确要求，大排期期间生效）**：记忆引擎逻辑、**46 条路由**契约、**85 个配置键**语义与默认值、prompt 层、Python worker、14 个工具名 —— 改外观/文档时**一律不动**。
+- **未经明确同意，严禁停止/重启 dsh web 宿主进程**（会截断工具调用）；host 改完只改文件并提示用户重启。
+- **未经明确要求，不要 `npm publish` / push GitHub / 打 tag**。
+- **写任何文件严禁 BOM**（保持 UTF-8 无 BOM；写完可用前三字节校验）。
+- 界面文案与文档的**文风**遵循 `docs/PROMO-STYLE-GUIDE.md`（产品拟人称"她"、厂商腔黑名单、母比喻=一本书）。
+
+---
+
+## 6. 下一版要做的三件事（已记录，未开工）
+
+完整清单（含行号、改法、验收）在 **`docs/internal/NEXT-VERSION-TODO.md`**。摘要：
+
+1. **水位判据口径**：现在触发用的是「可用额度」分母 `effectiveWin = win − reserve`（`lib/index.js:1900`，本机 1,048,576 − 384,000 = 664,576），导致**上下文刚过半就触发接续**，比官方压缩点（≈80% ≈ 83.9 万）**早约 45%**，用户判定太浪费。
+   **改法**：正常触发线改用官方声明窗口为分母（或 `min(win, hardWin)`），阈值 0.75–0.78；`reserve` **不再参与分母**，只保留"距硬墙余量"展示 + 硬判据（`estTokens + reserve > win` 才硬触发）。补反向锁：断言"不得把 reserve 计入分母"。
+2. **接续序号**：`contSeq = handoff 目录里 prev-session-*.md 文件数 + 1`（`lib/index.js:2646-2648`），在落盘失败 / 跨工作区（handoffDir 按工作区解析）/ carry 复用缓存时会**不递增、重复或为空**（为空即不 rename → 标题退回自动生成，用户已两次观察到"新窗口序号不对"）。
+   **改法**：改**持久计数器** `handoff/cont-seq.json`（键 = workspaceId），缺失时从现有 `接续 #N` 标题/包名解析最大值 +1 兼容老数据；序号分配与包落盘做成同序事务；三条入口（面板一键 / 宿主兜底 / 重启后）全覆盖。
+3. **固定流程外包给子代理**（用户提出的想法）：发版这类已固化的流程**不由主对话逐步执行**（主对话上下文最贵）→ 交给子代理（思考强度不必高），它做完/出错后只回结构化结论，主对话只做三件事：开闸前确认前置门 / 放行或中止 / 失败时处置。
+   落地物：`docs/prompts/RELEASE-AGENT.md`（自包含任务书）+ `RELEASE-PROCESS.md` 顶部「角色分工」段 + 同类流程（全量回归 / 双语对账 / 痕迹巡检）各配任务书。回报格式 `{ ok, version, pre_sha, rel_sha, tag, npm_latest, failed_step, error_tail }`。
+
+> 现状补充：**v2.4.2 已把 `autoContinueEnabled` 出厂默认改为 `false`**（并加反向锁 `smoke-test-autocont-host-pre.mjs` 断言默认必须为 false）。用户本机也已关闭。所以上述 ① 是"改好再考虑翻回默认开"的前置。
+
+---
+
+## 7. 待开工的大排期（界面 × 文档 × 首页）
+
+用户已拍板方向，**设计优先、功能说明最后核对**，**后端冻结**：
+
+- 排期与现状硬数据：`docs/internal/DESIGN-OVERHAUL-PRE-RESEARCH.md`（含诊断、P0-P6 排期、5 条验收判据、6 个待用户拍板点）
+- 美术方向与动效规格：`docs/internal/ART-DIRECTION-WIREFRAME.md`（线框稿 + EVA 式克制线描色板 + 线宽四档 + 工程图元素 + **24fps 动效时序表** + 性能预算 + **可直接转发给 Astra 的交付契约**）
+- 三条线：①界面与设置页大改（12 页签塞进 440×560 浮层 = 容器错配；DSH 有 ~58 个原生插槽可用，`slots.inject/register` 是通用 API，挂原生位**不需要改后端**）②README/用户说明书/项目文档大改 ③`docs/landing/index.html` 首页大改（现为 1,745 行自包含单文件，靠 `preview` 分支 + `htmlpreview` 第三方代理发布；无 `.github/`、无 Pages）
+- 设计主张：面板向 **DSH 原生 `--dsw-*` 令牌**靠（DSH 自己的 UI 包是打包后 CSS Modules，类名私有**不可复用**，只有公开 CSS 变量 + 插槽位可用）；首页保留现代主义品牌色（暖纸 `#F4F1EB` / 墨 `#17171A` / 信号橙 `#E9470C`）。
+- 角色动画（24 帧逐帧）**交给 Astra**：`ART-DIRECTION-WIREFRAME.md` §5 是完整交付契约（画布 1200×1200@1x、锚点 `(600,1080)`、PNG-24 + alpha、命名 `hero_0000.png`、分层导出、7 条验收）。
+
+---
+
+## 8. 血泪坑清单（照着躲）
+
+1. **脏树进包**：`release.mjs` 的 DEV 源就是 `D:\dsh-auto-memory` 工作区 —— 发版前必须核实 `git status` 范围（本机曾两次发现工作区混有其他会话的未发布改动）。
+2. **两半边独立 bundle**：`client.js` 是手写 `__ModuleLoader__`，不能用相对 `import`；跨半边一致性只能靠测试锁。
+3. **同一文件一次消息发两个 edit 会丢前者**（实测过）→ 同文件改动串行，或写「替换清单 JSON + 计数断言脚本」一次做（不符即整体不写盘）。
+4. **`edit` 工具会被全角引号/缩进差异绊住** → 大文件批量改推荐脚本 + 动态识别缩进（别写死空格数）。
+5. **JS 正则不支持 `(?m)` 内联标志**（要用 `/.../m`；写进测试会直接 SyntaxError）。
+6. **水位/接续相关**：判据优先级 = provider 错误文本 > 官方 `request/context.contextWindow` > 本地 tokenMeter > 启发式估算；本地估算在"中文+代码+大工具输出"会话里**偏乐观约 2×**。撞墙报错原文含 `CONTEXT_WINDOW_EXCEEDED`，是本机校准的唯一权威来源。
+7. **接续有两条路径且行为不同**：宿主 `hostAutoContinue()`（无刷新仪式）与面板 `runContinueFlow()`（注入刷新仪式）。改任一侧要同步评估另一侧。排查"接续没反应"先看 `~/.dsh/dsh-auto-memory-pre-diagnose.log`。
+8. **`docs/` 会被打进 npm 包**，而 README/USER-GUIDE 的图片走相对路径 `docs/screenshots/…` → 想收窄 `files` 必须**分层**（保留 screenshots + 论文 + 架构图），不能整目录删。
+9. **`npm view` 命中本地缓存** + **本机 .npmrc 是 npmmirror**（见 §4）。
+10. **凭据只走行内 URL / 环境变量**，绝不写进任何会上传 GitHub 或 npm 的文件。
+
+---
+
+## 9. 建议 ZCode 的第一件事
+
+```powershell
+cd D:\dsh-auto-memory
+git log --oneline -5                 # 确认在 pre 线
+git status --short                   # 确认没有别人的未提交改动
+Get-ChildItem tests\smoke -File -Filter *.mjs | ForEach-Object { node $_.FullName > $null 2>&1; if ($LASTEXITCODE -ne 0) { "FAIL: " + $_.Name } }   # 回归基线
+```
+然后二选一：**A. 深改**（照 `docs/internal/NEXT-VERSION-TODO.md` 从改点 ① 开始）或 **B. 大排期**（照 `docs/internal/DESIGN-OVERHAUL-PRE-RESEARCH.md`，但需先向用户取三样：官方 DSH 网页 URL/截图、角色基准图、风格探针许可）。
+
+**别做**：不要 `npm publish`/push/tag（除非用户明确要求）；不要重启 dsh web；不要改 §5 冻结清单里的任何契约。
+
+---
+
+## 10. 关键路径表
+
+| 路径 | 用途 |
+| --- | --- |
+| `docs/internal/RELEASE-PROCESS.md` | 发版 10 步唯一检查表（含凭据纪律、npm 缓存坑） |
+| `docs/internal/NEXT-VERSION-TODO.md` | 下一版三点待改（水位口径 / 接续序号 / 流程外包）+ 验收 |
+| `docs/internal/DESIGN-OVERHAUL-PRE-RESEARCH.md` | 界面×文档×首页大排期预研（诊断 + P0-P6 + 判据） |
+| `docs/internal/ART-DIRECTION-WIREFRAME.md` | 美术方向 + 24fps 规格 + Astra 交付契约 |
+| `docs/PROMO-STYLE-GUIDE.md` | 文风守则（README/landing/公告必须遵循） |
+| `docs/UI-INVENTORY-RAW.md` | 界面逐条盘点（12 页签 / 85 键 / 46 端点，带行号） |
+| `docs/USER-GUIDE.{en,zh-CN}.md` · `README{,.zh-CN}.md` | 面向用户的四份文档（待大改） |
+| `docs/landing/index.html` | 首页（单文件、双语） |
+| `tools/release.mjs` | 发布构建器 + 版本标识闸门（§5.05） |
+| `tests/smoke/smoke-test-api-paths-pre.mjs` | 路径表一致性锁（客户端 ⊆ 宿主） |
+| `~/.dsh/dsh-auto-memory-pre-diagnose.log` | 插件诊断日志（接续/水位/降级线索都在这） |
+| `~/.dsh/dsh-auto-memory-pre.json` | **pre 线**实际配置文件（别读成非 `-pre` 的那个） |

package/docs/internal/NEXT-VERSION-TODO.md

@@ -0,0 +1,95 @@
+# 下一版待改（用户 2026-09-10 19:0x 指定）
+
+> 来源：用户实机观察 —— 「自动接续又触发了，而且确实才刚过半，太浪费；你现在依靠那个 max output 来算，但官方压缩也是等到上下文真正占到 80% 才开始；新窗口依旧没有按正确序号排序。接续流程我已经关掉了，只要记着下一版怎么改就行。」
+> 状态：**✅ 三项已于 v2.5.0（2026-09-13）落地**：①分母=官方声明窗口（reserve 退出分母，新增预测性硬墙 estTokens+reserve>判定窗）②cont-seq.json 持久计数器（全局单调/失败回滚/标题扫描兜底，smoke-test-contseq-pre.mjs）③docs/prompts/RELEASE-AGENT.md 等四份任务书 + RELEASE-PROCESS.md 角色分工。`autoContinueEnabled` 出厂默认仍为 false，是否翻回待用户实机验证后定夺。
+
+---
+
+## 改点 1 · 水位判据口径：不要把「预留输出」当成分母
+
+### 现状（取证到行）
+| 位置 | 事实 |
+| --- | --- |
+| `lib/index.js:1884-1886` | `win = sessModel.contextWindow`（官方声明窗口，本机 deepseek-flash = 1,048,576） |
+| `lib/index.js:1899` | `reserve = sessModel.maxTokens`（该路由预留输出，实测 384,000） |
+| `lib/index.js:1900` | `effectiveWin = (reserve > 0 && reserve < win*0.9) ? win - reserve : win` → 本机 **664,576** |
+| `lib/index.js:1967` | `waterLevelRing = estTokens / win`（声明窗口口径） |
+| `lib/index.js:1971` | `waterLevelWall = max(0, hardWin − reserve)`（距硬墙余量） |
+| 触发判据 | 走**可用额度口径**（`estTokens / effectiveWin`）：实测阈值落在 ≈46 万 token，而**官方压缩要等到约 80% ≈ 83.9 万**才动手 → **早触发约 45%** |
+
+### 根因
+把「单次请求的最大可用额度」（`win − reserve`）当成了水位分母。它确实是**单请求硬失败**的边界，但不是**官方压缩**的坐标系 —— 于是水位数被系统性放大，接续在"刚过半"时就触发。
+
+### 下一版改法（两条线并行，别只改一半）
+1. **正常接续触发线与官方压缩同坐标系**：分母改用**官方声明窗口 `win`**（或 provider 自报硬限 `hardWin`，取能得到的最小可信值），阈值默认 **0.75–0.78**（略早于官方 0.80，好在压缩丢细节之前完成一次干净交接）。
+2. **保留硬墙保护，但降级为"真会失败才触发"**：仅当 `estTokens + reserve > min(win, hardWin)`（下一次请求就会被拒）时才硬触发。**不要把 reserve 从分母里扣掉** —— reserve 只用于"距硬墙余量"展示与这条硬判据。
+3. **展示与判据解耦**：面板继续显示双口径（本会话水位 / 官方小圈读数 / 距硬墙余量），但**触发只认第 1 条的坐标**；`CONTEXT_WINDOW_EXCEEDED` 与 compaction 事件继续作硬触发（不变）。
+4. 迁移注意：老配置里已落盘的 `autoContinueThreshold`（0.75）在新坐标系下语义等价于"窗口的 75% ≈ 78.6 万"，正好落在合理位置；**不需要强制迁移**，但要在设置页 hint 里改口径说明（"按官方窗口计，官方在 80% 压缩"）。
+
+### 验收
+- 本机 deepseek-flash 路由：阈值 0.75 时，触发点 ≈ 78.6 万 token（而非 46 万）；`waterLevelRing` 与触发比例**同分母**。
+- 单请求硬失败保护仍在：构造一条 `estTokens + reserve > win` 的场景，应走硬触发而不是等到比例线。
+- 回归：`water-window-pre` / `water-hard-trigger` / `autocont-host` / `water-step` 四个套件全绿（含新增"不得把 reserve 计入分母"的反向锁）。
+
+---
+
+## 改点 2 · 接续序号（新窗口没按正确序号）
+
+### 现状（取证到行）
+| 位置 | 事实 |
+| --- | --- |
+| `lib/index.js:2646-2648` | `contSeq = (handoff 目录里 /^prev-session-.*\.md$/ 的文件数) + 1` |
+| `lib/index.js:2533` | 转写包落盘名：`prev-session-<sid8>-<stamp>.md` |
+| `lib/index.js:2182-2187` | 宿主兜底路径补的 `sc.rename({sessionId, title: '接续 #' + contSeq + ' · ' + wsBase})`（2026-09-10 才补，此前只有浏览器路径有） |
+
+### 疑似根因（下版按序排除）
+1. **计数来源不稳**：序号来自**文件枚举**，而包是"接续时/之后"才落盘的 → 落盘失败、被清理、或写到**别的工作区的 handoffDir**（`p.handoffDir` 是按工作区解析的）时，计数不递增或**跨工作区重复**。
+2. **取数时机**：`contSeq` 在 `buildContinueCarry` 里算，若该次 carry 复用了缓存/旧 pack，`contSeq` 可能为空 → `if (d.contSeq ...)` 不成立 → **不 rename**，标题退回自动生成的"接续上一会话的任务。材料已…"（此现象早前出现过一次）。
+3. **路径覆盖不全**：三条入口（面板一键接续 / 宿主兜底接续 / 重启后接续）是否都拿到了 `contSeq` 并成功 rename，需逐一核对 diag 日志。
+
+### 下一版改法
+1. **序号改持久计数器**：`handoff/cont-seq.json`（键 = workspaceId，值 = 已发出的最大序号），取数即 `++`；若文件缺失则回退为"从现有 `接续 #N` 标题/`prev-session-*` 包名里解析最大值 + 1"（兼容老数据）。
+2. **rename 兜底**：把 `contSeq` 为空的情况改为"用持久计数器兜底值"而不是跳过；rename 失败写 diag（现状只有 catch 里一条 diag，需确认两条入口都写）。
+3. **会话列表排序依据**：若侧栏排序仍不按序号，检查是否需要在 rename 后同步排序字段（sequence/title 排序键），不要只改标题。
+4. **落盘顺序**：确认"写包 → 算序号"还是"算序号 → 写包"，把序号分配与包落盘做成**同一次事务的顺序**（先分配序号、再写包、失败回滚计数器）。
+
+### 验收
+- 连续接续 3 次：标题依次为 `接续 #N`、`#N+1`、`#N+2`；换到另一个工作区接续**不重复**已有序号。
+- 三条入口各测一次，diag 里都能看到 rename 成功记录。
+- 新增 smoke：计数器持久化 + 跨工作区不重复 + 包落盘失败时不跳号。
+
+---
+
+## 关联现状（改这两个点之前要知道）
+
+- 用户**已手动关闭自动接续**（`autoContinueEnabled = false`）以免浪费 token；改完需用户自行开启并重启 dsh web 验证。
+- `v2.4.1` 已含「已接续闩锁」（`~/.dsh/memory/auto-continue-done.json`），本次"又触发"是在**该闩锁之前就已 arm 的会话**上发生的，不代表闩锁失效；下版验证时要区分"闩锁没拦住"与"口径太早"。
+- 相关 diag：`~/.dsh/dsh-auto-memory-pre-diagnose.log`（`auto-continue armed / deferred / deadline reached / rejected at edge / host-executed` 全在这条线上）。
+
+---
+
+## 改点 3 · 固定流程外包给子代理（主对话只做决策）
+
+> 用户 2026-09-10 提出：「这种固定流程（尤其是已经多次固化成 skill 的），比如发版本，不应该由主对话来处理，主对话太耗上下文了，应该丢给一个 sub agent，思考强度不用特别高。他做完了或者出错了就扔回主对话，让主对话决定怎么解决。」
+
+### 目标形态
+- **主对话只做三件事**：①开闸前确认前置门（脏树范围核实 + 全量回归结果）②收到回报后判定放行/中止 ③失败时决定处置方向。**不逐步执行流程**。
+- **子代理执行**：按检查表全跑，**出错即停**，回报一个结构化结论：
+  `{ ok, version, pre_sha, rel_sha, tag, npm_latest, failed_step, error_tail(≤20 行) }`
+- **凭据不进提示词**：子代理自行从 `--D--dsh_debug--/MEMORY.md` 读（该处明确「只存本地，严禁写入任何会上传 GitHub/npm 的文件」）。
+
+### 落地形态（下版做）
+1. **`docs/prompts/RELEASE-AGENT.md`** —— 给子代理的完整任务书：照 `docs/internal/RELEASE-PROCESS.md` 逐条展开 + 回报格式 + 出错即停规则 + 禁止事项（无 PAT 不得 push、未过闸门不得发布、除版本标识与 CHANGELOG 外不得改文件）。
+2. **`RELEASE-PROCESS.md` 顶部加「角色分工」段**：主对话=决策者 / 子代理=执行者，并写明「主对话不得逐步执行本清单」。
+3. **同类流程一并外包**：全量回归、docs 双语对账、子代理痕迹巡检，各写一份任务书（`docs/prompts/*-AGENT.md`）。
+
+### 已知约束（先记下来，免得下版踩）
+- **当前工具面无法给 `subagent` 指定思考强度**：`subagent` 只接受 `description/prompt/run_in_background`，`workflow` 的 `agent()` 会**显式拒绝** `effort`/`agentType`。要真压到 low/off 只有两条路：①在 DSH 侧给该路由/预设配默认推理强度；②**由插件自己 spawn** —— 插件已有 `subagentReasoningEffort: off|low|high|max`，经 `ctx.subagents.start({ agentOptions })` 下发。
+- **子代理看不到主对话**：任务书必须自包含（路径、命令、判据、回报格式全写死）。
+- **不得并发**：同一工作区的写盘流程（尤其发版）必须串行。
+- 子代理同样受「不重启宿主」约束：需要重启才生效的事只能回报给用户，不能自己动手。
+
+### 验收
+- 主对话跑一次发版：其上下文增量只含「开闸判断 + 子代理回报 + 三处复核」三块；
+- 故意造一次失败（如抽掉 CHANGELOG 的 `## [<ver>]` 小节）：子代理回报 `failed_step=5.05` 且 `error_tail` 含闸门原文，主对话据此给处置；
+- 子代理输出里不出现凭据明文（除命令行本身；不落盘、不入 git）。

package/docs/internal/RELEASE-PROCESS.md

@@ -0,0 +1,99 @@
+# 发版固定流程（dsh-auto-memory）
+
+> 2026-09-10 固化。本文件是发版的唯一检查表；`tools/release.mjs` 已内置**版本标识一致性闸门**（缺任一项即拒绝构建），所以下面第 2、3 步不是"记得做"，而是"不做就发不出去"。
+
+## 角色分工（2026-09-13 固化，改点3）
+
+- **任务书流向**：主对话读本检查表 → 角色分工指向任务书 → **主对话填入版本号后原文派发给执行子代理**。用户不必、也不要绕过主对话直接投喂子代理（两条入口并存=并发冲突之源）。
+- **主对话 = 决策者，只做三件事**：①开闸前确认前置门（第 0 节：全量回归结果 + 脏树范围核实）②收到子代理回报后**放行或中止** ③失败时决定处置方向。**主对话不得逐步执行本清单**——发版这类固化流程交给子代理执行（主对话上下文最贵）。
+- **子代理 = 执行者**：投喂 [`docs/prompts/RELEASE-AGENT.md`](../prompts/RELEASE-AGENT.md)（自包含任务书，填入版本号），按本清单全跑、**出错即停**，只回结构化结论 `{ ok, version, pre_sha, rel_sha, tag, npm_latest, failed_step, error_tail }`。
+- **不得并发（冲突防线）**：主对话**派活后等待回报**，期间对同一工作区**只读**（看日志/读状态可以；改文件、git 写操作、跑发版命令、再派第二个执行子代理都不行）；只读类任务书（回归/对账/巡检）之间可并行，但**不与发版执行并发**（回归占满 CPU 会污染计时敏感套件）。
+- 凭据不经主对话转手：子代理按任务书自行从 `--D--dsh_debug--` 记忆文件读取，回报中一律 `<redacted>`。
+- 同类固化流程的任务书：全量回归=[`REGRESSION-AGENT.md`](../prompts/REGRESSION-AGENT.md) · 双语对账=[`DOCS-AUDIT-AGENT.md`](../prompts/DOCS-AUDIT-AGENT.md) · 痕迹巡检=[`TRACE-PATROL-AGENT.md`](../prompts/TRACE-PATROL-AGENT.md)。
+
+## 0. 前置门（不满足不许开工）
+
+- [ ] 全量回归：`cd D:\dsh-auto-memory; Get-ChildItem tests\smoke -File -Filter *.mjs | ForEach-Object { node $_.FullName }` → **0 失败**
+- [ ] `node --check lib/index.js` 与 `lib/client.js` 通过；改动文件无 BOM
+- [ ] **脏树范围核实**：`git status --short` 里只有本次要发布的文件（`release.mjs` 的源就是工作区，脏树会整体进包且不可回溯）
+
+## 1. 定版本号
+
+- 纯修复 → patch；有新行为/新键 → minor。写在 `CHANGELOG.md` 与下文各处。
+
+## 2. 必改 CHANGELOG（第 1 笔）
+
+- [ ] `CHANGELOG.md` 顶部新增 `## [<ver>] — <日期> · <一句话主题>` 小节，含：覆盖范围 / 缺陷修复 / 内部重构（若有）/ 流程（若有）/ 验证
+- 闸门校验：文件里必须出现 `## [<ver>]`，否则 `release.mjs` 拒绝构建
+
+## 3. 必同步软件内版本标识（第 2 笔）
+
+- [ ] **应用内更新说明字典**：`lib/client.js` 的 `var CHANGELOG = { ... }` 顶部新增 `'<ver>': { zh: [...], en: [...] }`（这是弹窗里的"更新说明"，缺了用户升级后看不到本版说明）
+- [ ] **界面指纹行**：`lib/client.js` 第 10 行 `console.log('[dsh-auto-memory] client v<ver> fingerprint: ...')`
+- [ ] `package.json.version`：**由 `release.mjs` 自动回写开发树**（面板徽标与「检测更新」读的就是它），构建后复核输出里有 `开发树版本回写: x.y.z → <ver>`
+- 闸门校验：以上三项任一与新版本号不一致 → **拒绝构建**（防止检测更新一直拿旧版本号去比对）
+
+## 4. pre 线提交
+
+```powershell
+cd D:\dsh-auto-memory
+git add lib tests CHANGELOG.md tools/release.mjs
+git -c user.name="Aik358" -c user.email="aik358@users.noreply.github.com" commit -m "v<ver>: <一句话>"
+```
+
+## 5. 先 dry-run 验闸门
+
+```powershell
+node tools\release.mjs <ver> --dry-run     # 走临时 staging,不碰发布基座
+```
+期望看到：`版本标识一致性: OK(CHANGELOG / 应用内更新说明 / 界面指纹行)` + `语法 ✓ BOM ✓ 无 pre/dev 残留 ✓` + `python/ 运行时完整 ✓ bench 已排除 ✓`
+
+## 6. 真构建
+
+```powershell
+node tools\release.mjs <ver>               # 写 D:\dsh_debug\_publish_dsh-auto-memory + 回写开发树版本
+```
+
+## 7. REL 提交 + 打 tag
+
+```powershell
+cd D:\dsh_debug\_publish_dsh-auto-memory
+git add -A
+git -c user.name="Aik358" -c user.email="aik358@users.noreply.github.com" commit -m "v<ver>: <一句话>"
+git tag -f v<ver>
+```
+
+## 8. push（必须带 PAT 行内 URL）
+
+```powershell
+git -c credential.helper= push https://x-access-token:<PAT>@github.com/Aik358/dsh-auto-memory.git main --tags --force
+```
+
+## 9. npm publish（单向门，最后一步）
+
+```powershell
+cd D:\dsh_debug\_publish_dsh-auto-memory
+npm publish . --registry=https://registry.npmjs.org/ --//registry.npmjs.org/:_authToken=<token> --access public
+```
+
+## 10. 三处复核（缺一不算发完）
+
+```powershell
+npm view @a9i5k4/dsh-auto-memory version --registry=https://registry.npmjs.org   # 必须显式指定官方 registry
+git ls-remote https://github.com/Aik358/dsh-auto-memory.git refs/heads/main
+git ls-remote https://github.com/Aik358/dsh-auto-memory.git refs/tags/v<ver>
+```
+三处 sha/版本必须一致。
+
+**坑（2026-09-10 实测）**：`npm view` 会命中本地 npm 缓存 —— 刚发布后可能仍回读到**上一个版本**（本次 v2.4.2 发布成功后仍回读 2.4.1）。判定以 **registry 权威接口**为准：
+
+```powershell
+Invoke-RestMethod 'https://registry.npmjs.org/@a9i5k4%2Fdsh-auto-memory/latest' | Select-Object -ExpandProperty version
+npm view @a9i5k4/dsh-auto-memory version --registry=https://registry.npmjs.org --prefer-online
+```
+
+## 纪律
+
+- **凭据只走行内 URL / 环境变量，严禁写进任何会上传 GitHub 或 npm 的文件**（本文件亦不写）。
+- 本机 `~/.npmrc` 指向 npmmirror → 查询与发布都必须显式 `--registry=https://registry.npmjs.org`，否则会查到旧版本、误判发布失败。
+- 发布后实机生效：宿主 `lib/index.js` 需重启；界面半边刷新页面即可。`update-check` 有落盘缓存（`~/.dsh/memory/update-check-pre.json`），需要时用「检查更新」强制刷新。