Repository navigation
Releases: ROBOHAPPYIY/dsh-zh-review-guard
Release list
v0.2.2 — 通道 2 减重：AGENTS.md 默认写精简兜底版
dsh-zh-review-guard v0.2.2
主题：通道 2 减重 —— AGENTS.md 默认只写精简兜底版，每轮护栏开销降约 1/3。
为什么改
本插件用两条独立通道注入同一份护栏：
- 系统提示词 section（
system-prompt/assemble）—— 主通道，完整正文； $DSH_HOME/AGENTS.md（由@deepseek-ai/dsh-agent-instructions在会话首个 pre-step 注入）—— 兜底通道。
v0.2.1 及之前，两条通道写的是逐字相同的全文（617 字符 / 14 行）。一次请求里它就会出现两遍，按本机标定（539 tokens / 618 字符）折算约 1076 tokens/请求；对"每轮都要付"的常驻注入来说，这份重复是纯开销。
为什么不能干脆关掉通道 2：主通道是 system-prompt/assemble 瀑布的一环，上游 router 的 standard 档在重建 sections 时会整体替换（取证见 router-bootstrap.mjs:105-118、:131-136 与其上方注释 :100-102），插件段会被静默丢弃 —— 这正是兜底通道存在的理由。所以本版的选择是减重而不是关闭。
改了什么
- 新增配置
agentsDigestLines（默认2）：写进AGENTS.md的内置规则条数。0= 写整份正文（v0.2.1 的行为）。 AGENTS.md默认内容变为精简兜底版：标记 +# 用户全局护栏（精简兜底版）+ 一行说明 + 前 N 条内置规则，约 459 字节 / 7 行。- 新增结构识别
isPluginDigestText()：只要文件是"标记 + 标题 + 说明 + 编号规则 1..N"的形状，就认定为本插件所有。因此条数随配置变化时，插件不会把自己上次写的文件误判成用户手写内容（实现时踩过这个坑）。 status.json的agentsFile新增digestLines/digestChars，一眼能看出这次写的是全文还是兜底版。- 通道 1 的正文、接管判据、覆盖前备份、磁盘卫生、暴露面控制全部不变。
开销对比（本机标定，539 tokens / 618 字符）
| 配置 | 通道 1 | 通道 2 | 合计/请求 | 相对 v0.2.1 |
|---|---|---|---|---|
| v0.2.1（双全文） | 538 | 538 | 1076 | — |
v0.2.2 默认（agentsDigestLines: 2） |
538 | 183 | 721 | 省 33% |
agentsDigestLines: 1 |
538 | 113 | 651 | 省 40% |
| 关闭通道 2（不支持） | 538 | 0 | 538 | 省 50%，但有静默失效风险 |
注意：兜底版只含内置规则；rules.md 里追加的自定义规则只进通道 1。要让兜底也覆盖自定义规则，把 agentsDigestLines 设为 0。
升级行为
升级到 v0.2.2 后，旧的全文本 AGENTS.md（哪怕是 v0.2.0 写的、只差版本号）会在下一次同步时被认领 → 先备份到 zh-review-guard\backups\ → 再改写为精简兜底版。想继续保留整份正文，把 agentsDigestLines 设为 0：
# cordis.patch.yml / profile 配置里
zh-review-guard:
agentsDigestLines: 0验证
node test/selftest.mjs→ 75/75 passed（v0.2.1 是 67 项）；- 独立场景脚本
audit\zhg-verify-fix.mjs→ VERIFY OK 13/13：用户手写文件逐字节保留、只差版本号的旧文被认领升级、备份命中、状态哈希一致、默认写兜底版、设0切回全文； - 用真机
AGENTS.md（1562 字节 / 14 行 / 首行 v0.2.0）在临时DSH_HOME重放：认领 → 备份（原样 1562 字节）→ 改写为 459 字节 / 7 行 / 首行 v0.2.2。
已知边界
- 兜底版是结构性识别，不做模糊匹配；如果你手工改动了兜底版里的规则文字，插件会把它当成"用户内容"而不再同步（这是刻意的保守行为，README 里有说明）。
- 双实例并存（loader.create 与 patch insert 两条路径）时两条通道仍会各自注入，本版只减少单次注入的体积，不改变实例数量。
完整校验和与安装方式见本 Release 附件与 INSTALL.md。
v0.2.1 - dsh-zh-review-guard
v0.2.1 —— 把"能覆盖"收窄成"只覆盖自己的"，而且动了手先备份
这一版来自一次独立审计（漏洞 / API 写入面 / token 开销三个角度）。审计结论是：运行时零网络、零子进程、零第三方依赖；真正的问题只有一个 —— 通道 2 写 AGENTS.md 的判据过宽。
修了什么
- 接管判据收紧（中高危）：v0.2.0 只要文件里出现
<!-- managed-by: dsh-zh-review-guard这段前缀，就被判定为"本插件所有"，随后整份覆盖。用户自己的AGENTS.md里若恰好有这一行（从文档里复制过规则片段、或从别的机器拷来），内容会被无声抹掉。v0.2.1 改为三种情形之一才写入：①文件不存在或只有空白；②内容与zh-review-guard/agents-state.json记录的哈希一致；③全文就是本插件的规则文本（仅managed-by里的版本号不同）。 - 覆盖前备份：真要改写时先把原文件存到
zh-review-guard/backups/AGENTS.md.<时间戳>.bak，默认保留 5 份（backupAgentsFile/agentsBackupKeep）。 - 所有权证据：新增
zh-review-guard/agents-state.json（记录本插件上次写入内容的哈希）。这一个文件同时解决两个问题：收紧判据后插件仍认得自己写的文件，规则改了照样能就地更新；而用户手写文件永远不会被误认为"自己的"。 - 磁盘卫生：
assemblies.jsonl超过maxLogBytes（默认 2 000 000 字节）轮转为assemblies.jsonl.1（只留一代）；instances/按instancesTtlMs（默认 7 天）与instancesMaxFiles（默认 20）清理，当前实例永不删。 - 降低暴露面：装配日志默认只记
sectionCount与sectionNamesHash，不再把每轮的 system prompt 段名清单逐条落盘（要恢复就把recordSectionNames设为true）；status.json同步换成lastSectionCount/lastSectionNamesHash。 - 自测 57 → 67 项：新增"含标记片段的用户文件必须保留""仅版本号不同的旧文本应升级并备份""纯函数判定矩阵""日志轮转""instances 清理"等用例。
未改动（审计已确认，无需改）
- 运行时不联网、不起子进程、无第三方依赖（
lib/index.js只 importnode:fs/node:crypto/node:os/node:path）。 - 注入的 token 开销：单通道约 538 tokens/轮；双实例双通道时同一文本被注入两遍，约 1076 tokens/轮。这一项没有在本版改动 —— 关掉通道 2 会牺牲"上游整体替换
sections时的兜底"，取舍留给你。
资产
| 文件 | 大小 | SHA256 |
|---|---|---|
| dsh-zh-review-guard-0.2.1.tgz | 35 197 字节（34.4 KB） | A6805A63C8CA3A7216C9E1E7BE8A72DB9F9116C7E728352B8764DFEBEC7F77DB |
文件清单与 v0.2.0 一致（7 项）：package/{LICENSE, lib/index.js, package.json, INSTALL.md, README.md, test/selftest.mjs, cordis.patch.yml}。
解包后 node test/selftest.mjs → 67/67 passed。
已发布：https://github.com/ROBOHAPPYIY/dsh-zh-review-guard/releases/tag/v0.2.1（2026-10-02，Release 列表中标记为 Latest）。
附件 dsh-zh-review-guard-0.2.1.tgz（35 197 字节）从 Release 下载回来后复验 SHA256 = A6805A63C8CA3A7216C9E1E7BE8A72DB9F9116C7E728352B8764DFEBEC7F77DB，与本地产物逐字节一致。
从 v0.2.0 升级
# 本地 tgz（发布前）
dsh plugin --profile desktop add "D:\AGENTCREATE\dist\dsh-zh-review-guard-0.2.1.tgz"
# 发布后：把 tag 换成新版本号
# dsh plugin --profile desktop add github:ROBOHAPPYIY/dsh-zh-review-guard#v0.2.1
# 然后完全退出并重启 DSH App旧 AGENTS.md（带 v0.2.0 标记）会被认领并就地升级，升级前会先备份到 zh-review-guard/backups/。
文档同步
README.md：接管规则、配置表（新增 6 个键）、观测字段、FAQ、自测项数INSTALL.md：status.json示例、文件写入判据表、版本表、升级说明、v0.2.1 复检记录- 本文件：
RELEASE-NOTES-v0.2.1.md
维护者发布步骤（2026-10-02 已执行完毕）
本机 profile 里 dsh-zh-review-guard 是 link:D:\AGENTCREATE\dsh-zh-review-guard（junction），所以本机不需要 dsh plugin add：源码目录就是安装源，重启 App 即生效。
重做一次时最容易踩的三个坑（本次全部踩过）：
| 坑 | 绕法 |
|---|---|
PATH 里的 gh 登录失效：The token in keyring is invalid |
改用 dsh 自带那份：C:\Users\<你的用户名>\.dsh\bin\gh.exe（同一账号、token 有效、scopes 含 repo） |
git 直连 github.com:443 不通：Failed to connect to github.com:443 after 21114 ms |
加 -c http.proxy=http://127.0.0.1:7897 走本地代理 |
全局 url.…ghfast.top….insteadOf https://github.com/ 把直连 URL 重写回镜像域名，而凭据是按 host 查找的 → 认证失败 |
让 GIT_CONFIG_GLOBAL 指向空配置去掉重写，再用 -c credential.helper= 重置 helper 链并接上 gh 的 auth git-credential |
若 PATH 里的 gh 已恢复登录，下面这套（走 publish-github.ps1）最省事：
gh auth refresh -h github.com # 1) 恢复登录
# 把产物放回惯例目录（沙箱内写不进 release\，你自己的终端可以）
Copy-Item D:\AGENTCREATE\dist\dsh-zh-review-guard-0.2.1.tgz D:\AGENTCREATE\release\
cd D:\AGENTCREATE\dsh-zh-review-guard
git add -A
git commit -m "release: v0.2.1 - ownership-hash claim + pre-overwrite backup; log rotation; section names hashed by default"
git tag -a v0.2.1 -m "dsh-zh-review-guard v0.2.1"
# 2) 推送 + 建 Release（-NoRewrite 避开全局 ghfast.top 重写，同时保留 gh 凭据助手）
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
& .\publish-github.ps1 -Owner ROBOHAPPYIY -Tag v0.2.1 -Notes RELEASE-NOTES-v0.2.1.md `
-Tgz D:\AGENTCREATE\release\dsh-zh-review-guard-0.2.1.tgz -NoRewrite脚本最后会把 Release 附件重新下载回来比对 SHA256，出现 OK: release asset matches the local tgz byte for byte 才算发布成功。
实际执行记录（2026-10-02）
PATH 里的 gh 登录失效，所以没有用脚本，而是按脚本的等价步骤手动执行：
$px = 'http://127.0.0.1:7897'
$ghHelper = "credential.helper=!'C:\Users\<你的用户名>\.dsh\bin\gh.exe' auth git-credential"
$url = 'https://github.com/ROBOHAPPYIY/dsh-zh-review-guard.git'
Copy-Item D:\AGENTCREATE\dist\dsh-zh-review-guard-0.2.1.tgz D:\AGENTCREATE\release\ -Force
Set-Content -Path "$env:TEMP\git-empty.cfg" -Value '' -Encoding ASCII
$env:GIT_CONFIG_GLOBAL = "$env:TEMP\git-empty.cfg" # 去掉 url.insteadOf 重写
$env:GIT_TERMINAL_PROMPT = '0'
# 提交与标签（本地）
git add -A
git commit -m "release: v0.2.1 - ownership-hash claim + pre-overwrite backup for AGENTS.md; log rotation and instances pruning; section names hashed by default"
git tag -a v0.2.1 -m "dsh-zh-review-guard v0.2.1"
# 推送（直连 github.com + 本地代理 + dsh 自带的 gh 凭据助手）
git -c http.proxy=$px -c credential.helper= -c $ghHelper push $url main
git -c http.proxy=$px -c credential.helper= -c $ghHelper push $url refs/tags/v0.2.1
# 建 Release（用 dsh 自带那份 gh）
$env:HTTPS_PROXY = $px
& 'C:\Users\<你的用户名>\.dsh\bin\gh.exe' release create v0.2.1 D:\AGENTCREATE\release\dsh-zh-review-guard-0.2.1.tgz `
--repo ROBOHAPPYIY/dsh-zh-review-guard --title 'v0.2.1 - dsh-zh-review-guard' `
--notes-file D:\AGENTCREATE\dsh-zh-review-guard\RELEASE-NOTES-v0.2.1.md结果：提交 5879249 → main；标签 v0.2.1 → dba8c47；Release 创建成功并标记为 Latest，附件 35 197 B，下载回来 SHA256 与本地产物一致。
发布后收尾（2026-10-02 已完成）：
- ✅
README.md（第 58/61/70 行）与INSTALL.md（第 78/81/89/98/111/122/130/133/317/360/527/528/529 行）里的一键安装与下载引用已切到#v0.2.1；历史复检记录里的v0.2.0原样保留 - ✅ 附件与本地 tgz 逐字节一致，SHA256 无需回填
- ✅ 本节与资产节「尚未发布」的说明已改为 Release 直链
许可证
MIT © 2026 ROBOHAPPYIY
v0.2.0 - configurable rules + main-channel health check
v0.2.0 —— 让"主通道悄悄失效"看得见，让规则可以自己改
这一版回答两个真实顾虑：上游一改事件名或瀑布契约，插件是不是就静默死掉了？ 以及 规则能不能不写死在代码里？
这一版多了什么
- 主通道健康检查：每个心跳周期扫一次
$DSH_HOME/sessions。如果"加载之后出现了新会话"（世界确实在动）却"一次装配都没发生"，就判定stale，写进$DSH_HOME/zh-review-guard/health.json，并在 App 日志里console.warn一次。ok心跳新鲜 /idle还没有会话活动 /warming启动宽限期内 —— 后两种都不算失效，刚装完还没人用 DSH 的机器不会误报。- 弱证据：有会话活动、但心跳滞后超过
staleLagMs（默认 2 小时）同样判stale。
- 契约自检：
ctx.on('system-prompt/assemble', …)的注册被包在 try/catch 里；失败也不崩，而是把contract.registerOk=false与error写进status.json。另有 best-effort 的事件名探测contract.eventKnown（true/null，null只表示"没探到"）。 - 规则可配置：新增
rulesMode（append/replace/off）、rulesFile（默认$DSH_HOME/zh-review-guard/rules.md）、rulesMaxChars（默认 12000）。append（默认）= 内置 7 条 + 你的「本机追加规则」；replace= 只用你的文件；off= 只用内置。- 规则文件改了不用重启：心跳检查文件 mtime，有变化就重新解析（
status.json的rulesReloads计数），通道 1 与通道 2 同时换成新文本。 - 超出
rulesMaxChars会截断，并在status.json记rules.truncated与原因。
- 升级安全：
AGENTS.md的归属标记改为按前缀认领（<!-- managed-by: dsh-zh-review-guard）。v0.1.x 写下的v0.1.1标记在升级后仍被认领，会就地升级为新文本；你手写的AGENTS.md依旧永远不会被覆盖。 - 自测 57 项（v0.1.1 是 31 项）：新增规则解析 6 项、健康判定 5 项、会话扫描 4 项、契约自检 1 项、真实 tick 集成 6 项（含"改了 rules.md 真的热更新"与"零装配真的判 stale"）。
从 v0.1.x 升级（两步）
dsh plugin --profile desktop add github:ROBOHAPPYIY/dsh-zh-review-guard#v0.2.0
# 然后完全退出并重启 DSH App旧的 AGENTS.md 规则段会被就地升级（靠前缀认领），不需要手工清理。
资产
| 文件 | 大小 | SHA256 |
|---|---|---|
| dsh-zh-review-guard-0.2.0.tgz | 28 166 字节（27.5 KB） | 9345A147858623DEAAA92FB843CAD001946909FE3E4F72EEA4E5476D673548A6 |
下载后核对：
Invoke-WebRequest "https://github.com/ROBOHAPPYIY/dsh-zh-review-guard/releases/download/v0.2.0/dsh-zh-review-guard-0.2.0.tgz" -OutFile .\dsh-zh-review-guard-0.2.0.tgz
Get-FileHash .\dsh-zh-review-guard-0.2.0.tgz -Algorithm SHA256许可证
MIT © 2026 ROBOHAPPYIY
v0.1.1 - LICENSE + step-by-step install guide
v0.1.1 — 文档与许可证发版
这是一个只动文档与元数据的补丁版本（lib/index.js 除了版本号常量与归属标记的前缀判定外没有行为变化），把 v0.1.0 之后在仓库里补齐的东西正式打进可分发的 tgz。
这一版比 v0.1.0 多了什么
LICENSE（MIT）：正式授权 —— 可自由使用、修改、再分发（含商用、含二次封装），保留版权声明即可。INSTALL.md重写为保姆级分步教程：从「Win + X打开 PowerShell」开始，到下载（含网络不通时的三条替代路）、核对 SHA256、选 profile、安装、重启、逐项验证、卸载，外加故障排查 A–G ——dsh命令找不到及绝对路径兜底、profilepackage.json带 BOM 导致SyntaxError: ... is not valid JSON的成因与修法、装完没生效的五步排查、tgz 路径失效、下载失败、双实例属正常、如何用assemblies.jsonl证明真的注入 —— 以及手动安装方案。这份教程在 tgz 包内自带，离线也能照做。- README 面向外部访客重写：徽章、痛点→后果对照、装上之后的变化、规则原文、三步安装、两条通道原理、配置与可观测性、折叠 FAQ。
- 自测从 26 项扩到 31 项：新增覆盖「通道 2」的 AGENTS.md 同步契约 —— 老版本（v0.1.0）写下的标记在升级后仍被认领并就地升级、用户手写的
AGENTS.md绝不被覆盖、文件不存在时创建。运行node test/selftest.mjs→31/31 passed。 - 归属标记前缀跨版本稳定：认领判定改为匹配
<!-- managed-by: dsh-zh-review-guard这个前缀，因此从 v0.1.0 升级上来的用户，其已有的AGENTS.md会继续被接管（不会因为版本号变化而"掉线"，也不会重复追加一份规则）。
安装
最快是一条命令（机器能访问 GitHub 就行，不用先下载；完整步骤见包内 INSTALL.md，在线版 https://github.com/ROBOHAPPYIY/dsh-zh-review-guard/blob/main/INSTALL.md ）：
# 走 git 源，pin 住 tag（要求机器上装了 git）
dsh plugin --profile desktop add github:ROBOHAPPYIY/dsh-zh-review-guard#v0.1.1
# 没有 git / 不想走 git：直接拉本页附件
dsh plugin --profile desktop add https://github.com/ROBOHAPPYIY/dsh-zh-review-guard/releases/download/v0.1.1/dsh-zh-review-guard-0.1.1.tgz两种写法都会让 dsh plugin add 自动把包名写进 dsh.profile.bundles，装完重启 App 生效。
离线安装（先下载、核对哈希、再装）：
# 1. 下载附件
Invoke-WebRequest "https://github.com/ROBOHAPPYIY/dsh-zh-review-guard/releases/download/v0.1.1/dsh-zh-review-guard-0.1.1.tgz" -OutFile .\dsh-zh-review-guard-0.1.1.tgz
Get-FileHash .\dsh-zh-review-guard-0.1.1.tgz -Algorithm SHA256 # 对照下面「资产」表里的值
# 2. 装进你的 profile（Web GUI 用 web，桌面端用 desktop），装完重启 App
dsh plugin --profile desktop add .\dsh-zh-review-guard-0.1.1.tgz从 v0.1.0 升级：先移除旧版，再装新包即可（remove 会同时清掉 profile package.json 里的 dependencies 与 dsh.profile.bundles 两项）：
dsh plugin --profile desktop remove dsh-zh-review-guard
dsh plugin --profile desktop add .\dsh-zh-review-guard-0.1.1.tgz资产
| 文件 | 大小 | SHA256 |
|---|---|---|
dsh-zh-review-guard-0.1.1.tgz |
18 272 B（约 17.9 kB） | A688F80945295B8D803C9FE1211D301D844770691EFE02215CBF0CE0D2E0E453 |
（本表由 npm pack 产物的实际字节数与 Get-FileHash -Algorithm SHA256 填入。校验方式：下载后 Get-FileHash .\dsh-zh-review-guard-0.1.1.tgz -Algorithm SHA256。）
兼容性
engines：node >= 22、dsh >= 0.0.1-rc- 实测环境：DSH 0.2.0-rc.2 / Windows / profile
desktop
许可证
MIT © 2026 ROBOHAPPYIY —— 可自由使用、修改、再分发（含商用、含二次封装），保留版权声明即可。
v0.1.0 - first distributable release
v0.1.0 — 首个可分发版本
dsh-zh-review-guard：把「内部思考视为用户可见、需要审阅」和「面向用户的内容用简体中文」从一份可能被忘记、被覆盖的文档约定，变成 DSH 的底层机制——每个会话每次装配系统提示词时都会被调用，规则常驻，不受上下文压缩影响。
这一版包含什么
- 通道 1（主）：
ctx.on('system-prompt/assemble', ...)瀑布注入常驻 section{ name: 'zh-review-guard', order: 4, text: RULES_TEXT }；同名段就地替换，幂等。 - 通道 2（备）：同一份
RULES_TEXT同步到$DSH_HOME/AGENTS.md，由@deepseek-ai/dsh-agent-instructions在会话首个 pre-step 作为持久基线注入；只接管文件不存在或带<!-- managed-by: dsh-zh-review-guard v0.1.0 -->标记的文件，用户手写的AGENTS.md绝不覆盖。两条通道独立，任一条即可让规则生效（首轮被上游预设整体替换sections时靠通道 2 兜底）。 - 可观测性：
$DSH_HOME/zh-review-guard/assemblies.jsonl（每次装配一行：会话 id / 是否新会话 / 动作 / 段名清单 / 规则哈希）、status.json、instances/<id>.json。 - 零依赖、无编译：只用
node:内置模块，lib/index.js即可运行的 ESM 源码。 - 26 项离线自测：
node test/selftest.mjs，不需要 DSH 运行时。
安装（在目标电脑上，约 30 秒）
# 1. 下载附件（或在浏览器里点本页下方的 dsh-zh-review-guard-0.1.0.tgz）
Invoke-WebRequest "https://github.com/ROBOHAPPYIY/dsh-zh-review-guard/releases/download/v0.1.0/dsh-zh-review-guard-0.1.0.tgz" -OutFile .\dsh-zh-review-guard-0.1.0.tgz
Get-FileHash .\dsh-zh-review-guard-0.1.0.tgz -Algorithm SHA256 # 对照下面「资产」表里的值
# 2. 装进你的 profile（Web GUI 用 web，桌面端用 desktop）
dsh plugin --profile desktop add .\dsh-zh-review-guard-0.1.0.tgzadd 会自动把包名写进 profile 的 dsh.profile.bundles（dependencies 记 file:...tgz，bundles 从 [] 变 ["dsh-zh-review-guard"]），装完重启 App 生效。完整步骤、验证方法与实测踩到的坑（profile package.json 不能带 BOM、tgz 路径不能删等）见 INSTALL.md —— 已重写为保姆级分步教程（开始之前 → 下载 → 核对哈希 → 选 profile → 安装 → 重启 → 验证 → 卸载 → 故障排查 A–G），在线版：https://github.com/ROBOHAPPYIY/dsh-zh-review-guard/blob/main/INSTALL.md 。
资产
| 文件 | 大小 | SHA256 |
|---|---|---|
dsh-zh-review-guard-0.1.0.tgz |
11 228 B（约 11.0 kB） | 8708BD708D7364C72F1B6376301B8BD5CA4ECC0D7623563FD93A1D31A68D2B91 |
（本表由 npm pack 产物的实际字节数与 Get-FileHash -Algorithm SHA256 填入。校验方式：下载后 Get-FileHash .\dsh-zh-review-guard-0.1.0.tgz -Algorithm SHA256。）
兼容性
engines：node >= 22、dsh >= 0.0.1-rc- 实测环境：DSH 0.2.0-rc.2 / Windows / profile
desktop
许可证
MIT © 2026 ROBOHAPPYIY —— 可自由使用、修改、再分发（含商用、含二次封装），保留版权声明即可。