FocusGuard 聚焦护栏

ZCode 原生硬拦截 + DSH 经官方桥硬拦截 · 零依赖 · 钩子层 AI 行为治理

FocusGuard 不是另一把 Hook 枪，它是 AI 行为治理的完整体系：立法（法条定标准）→ 执法（引擎机械执行）→ 监察（全程留痕可复核）。日常对话零打扰，一旦出现未取证就改、结论无锚点、整读大文件烧上下文、无限空转等失控行为，立刻按梯度处罚——打回、强制取证、熔断、记档、降权、上报，人类随时可复核。

它不是提示词里的一句"请不要乱来"，而是把失控行为变成钩子层可机械拦截的事件。

30 秒速览

失控现象	机械拦截	人类看到
没调查就改文件 / 执行变更命令	触发① → L1 打回	一条拒绝原因
结论没有 `[文件:行号]` 证据	触发② → 收尾打回	一条打回理由
整读 50KB 大文件、裸 cat 刷屏	触发③ 体积三闸	一行"分段读或交子代理"
反复无效调用、无限空转	触发④ 预算+停滞 → L3 熔断	熔断出口 + 三行降级方案
查无实据还硬凑	触发⑤ → 熔断	同上
拿到授权不吭声就绕过护栏	授权识别核验（引原文+法条）	越权 → L3 熔断
顺手 `rm -rf` / `git push` / `npm publish`	高危命令闸：一行审批单	`y` 放行本次 / `n` 彻底阻断
上下文被巨量输出撑爆	污染检测 + 卷宗免重读	记档 + 复用已有取证
反复读同一个没变的文件	卷宗指纹 + TTL	拦截本次 Read（`offset` 增量读永远放行）
大搜索/大文档主会话硬扛	强制委派场景 + 委派法典	KPI 计分，收尾结算委托池奖惩（3.0）
表现只有记分牌没有后果	KPI 兑现闭环（3.0）	收尾即结算：等次 → 委托池 ±5/±2，跨任务累计
出了事日志是一笔糊涂账	因果链留痕 seq/chain/ref（3.0）	`npm run chain` 渲染因果树/因果图
经验库被 AI 自己写坏	资料分层 + 派生积木（3.0）	`.ai/library/` 只同步外部原文；积木由 library-build 派生，两区均禁直写
云端判定贵且离线不可用	本地零成本哨兵（3.0）	`FG_SENTINEL=1` 启用，Needle 2 可插拔外判
高危操作事前没有审核，出事才拦	资格审核六层 + `fg_apply` 申请通道（3.0.5）	无授权 → 拒，理由指向申请入口
被引用的危险命令字符串被误拦	绝对红线上下文豁免：引号内 / 数据标记 / 只读命令三判据（3.0.6）	降级到语义预判，不再直接拒
拦错了没有程序可走，只能绕过	`fg_appeal` 误伤申辩（司法救济，3.0.6）	人类一次性裁决：批准即豁免本次红线
大小模型一刀切，贵的模型被过度打扰	模型画像五份 + 按画像跳层（3.0.5）	审核强度随模型调整
本机习惯用 `rg`/`fd`，AI 老写 `grep`/`find`	环境指纹 + 命令硬校验（3.0.5）	一行替代提示，不依赖模型自觉

为什么需要它

AI 智能体最常见的三种失控：

思考失控：没有证据就开猜，越查越偏，停不下来；
资源失控：整读大文件、未过滤刷屏，上下文和 token 被无意义输出撑爆；
权限失控：拿不准也硬改，先斩后奏，出了问题无法追溯。

"立法 → 执法 → 监察"三件套把这三类失控变成可拦截的行为事件：法条（packages/core/docs/RULES.md）定标准，引擎机械执行，留痕（.focus-guard/AUDIT.log）接受人类复核。

引擎按"母版层 → 适配层 → 宿主缝"三层组织（《资料与代码分层总规范》）：

层	位置	职责
母版层	`packages/core/src/core/`	零依赖、宿主无关的判定逻辑：六层资格审核 / 模型画像 / 绝对红线与上下文豁免 / 申辩 / 卷宗状态。不得反向依赖适配层（有验收用例锁定）
适配层	`packages/core/src/adapters/dsh/`	把母版接进 DSH：`fg_apply` / `fg_appeal` 工具注册 + 资格闸
宿主缝	`packages/core/src/dsh/pipeline.mjs`	DSH 原生插件的三条缝：pre-execute / system-prompt / post-execute
ZCode 执行壳	`packages/core/hooks/guard.mjs`	六事件钩子入口。已封存——ZCode 兼容层，版本号独立、不随主版本更新，改动须谨慎

快速开始

核心版与扩展版的关系：focus-guard（packages/core/）是零依赖范本包——引擎钩子、技能、核心工具、法条文档，所有人从这里开始；focus-guard-extended（packages/extended/）是扩展衍生包，依赖核心包，承载重型外接集成（OpenViking 同步桥 / Needle 2 本地模型外判 / Semantica 图谱导出）。核心版是范本，可衍生无数扩展变体；下载核心版时不需要也不会拉取任何扩展依赖。

npm install focus-guard           # 核心版：零依赖，装完即用
npm install focus-guard-extended  # 扩展版：按需启用外接集成（自动带上核心版）

ZCode 插件（推荐）：克隆本仓库 → 插件市场 → 添加市场（选择含 marketplace.json 的仓库根目录）→ 插件列表安装 → 新开会话。

DSH 有两条路，二选一、互斥（同缝双监听 = 双跑）：

路径	装什么	拿到什么
原生插件（3.0.5 起，推荐）	`dsh plugin --profile <name> add <本仓库 packages/core 目录>`	三条宿主缝全开：资格审核 + `fg_apply`/`fg_appeal` + 模型画像 + 命令硬校验 + 红线上下文豁免
官方桥	`@deepseek-ai/dsh-hooks-claude-code` 挂载 `packages/core/hooks/hooks.json`	与 ZCode 同级的六事件硬拦截（exit 2 阻断、stderr 原文透传、Stop 打回），但不含原生插件独有的资格审核与申辩

⚠ 两条路同时挂载会双跑；都不装则 DSH 端没有拦截。挂桥/装插件的逐行步骤与卸载见 INSTALL.md 第二、四节。

验证生效：新会话开头出现 <focus-guard AI履职执法模型v3.0 …> 注入，且工作区出现 .ai/CASE_FILE.md 与 .focus-guard/AUDIT.log。

逐行可复制的命令、DSH profile 挂桥、卸载与 FAQ（含"升级后版本没变"的部署漂移排查）：见 INSTALL.md。

核心机制

空气层（日常零打扰）

对话、分析、讨论、解释：不查、不拦、不提醒。执法只看行为，不查词。

触发层（行为五条，违规即罚）

#	触发条件	判定
①	未取证就改	本回合 0 次调查（读文件/Grep/搜索/只读命令）就 Write/Edit/改动类 Bash
②	无锚点结论	回合内调用 ≥5 次后收尾无 `[文件:行号]`/`[日志原文]`/工具结果，也未标【假设】
③	体积刺客	整读 >50KB 文件、Grep content 无 head_limit、裸 cat/type 刷屏（批示含"审计/盘点/审查"时，取证对象整读留痕不罚——2.5.3）
④	动态预算超限	有效调用超任务预算，或连续 3 次无效调用（真失控）
⑤	硬凑不熔断	查无实据仍强行猜测；连续 2 次未知声明同样熔断

梯度处罚（L1–L6）

L1 打回重写 → L2 强制取证 → L3 熔断 → L4 记档 → L5 降权 → L6 上报人类

同回合违规数累加自动爬升。熔断期只读调查类仍可用、改动类全拒、非只读放行的高危命令同样拒绝（2.5.2 修复）。人类新指令即"批示"、全部解除；唯「停止/熔断」批示本身就是熔断，不会被解除。

预算与进度检测（三预算池）

初始预算按批示关键词核定：审计/红队/重构/全量/批量/探索/遍历/升级/补丁 → 50；修复/添加/修改/重命名/删除 → 15；其他 → 10。首轮可声明【任务规模】上调，只升不降，硬上限 200；
三池分立：侦查池（只读，独立 15 次）／执行池（Write/Edit/变更命令）／委托池（子代理，独立 20 次），互不挤占；短指令『追加额度』执行/侦查/委托三池各 +10；
有效调用（返回内容有变化/产生文件变更/出现新报错）满阈值自动续杯 +10；
无效调用（重复读同一内容/同命令同返回/失败调用）连续 3 次 → 判真失控直接熔断；停滞 2 次可申请【信用延期】，由人类批示。

卷宗体系（四册，总纲见 docs/MASTER-PLAN-2.0.0.md）

工作区档案 <工作区>/.ai/CASE_FILE.md：

册	内容	维护方
【一】环境声明	OS / Shell / 编码 / 路径分隔符 / 大小写敏感 / BSD 工具 / 可用命令	引擎（会话级一次检测，结果直接落卷可查阅）
【二】项目依赖声明	依赖名 / 版本 / 安装路径 / 信任 TTL（如游戏本体 60 天）	人工填写
【三】侦查取证记录	文件名 / 读取时间 / mtime / size / SHA-256 / 变更历史 / TTL / 验证方式	引擎自动追加
【四】工作额度台账	初始额度 / 已用 / 剩余 / 有效 / 无效调用 / KPI	引擎（回合末落卷）

环境检测一次全程复用：SessionStart 检测一次，UserPromptSubmit 不重检，仅在探测到 shell 变化时重检；
跨回合取证指纹：mtime + size + SHA-256（≤200KB）+ git 脏态，指纹一致且 TTL 未超 → 免重读放行（拦截本次 Read，复用已有取证）；不一致或超时 → 放行真重读并更新卷宗。时间戳伪造（touch -d/cp -p/git checkout）无法绕过 SHA 内容校验；免重读限同一会话内——跨会话继承的卷宗指纹只提示不拦，首读永远放行（2.5.3）；
- 边界（别读成"任何尺寸都防伪"）：SHA-256 只对 ≤200KB 的文件计算。超过 200KB 退回 mtime+size+git；工作区没有 git 时（gitDirty 为 null），"同尺寸改写 + 还原 mtime"无法被察觉。大文件请依赖版本库或单独做内容校验；
自适应 TTL：首次 4 小时 → 7 天内有变 2 小时 → 7–30 天未变 24 小时 → 30 天未变 7 天；优先级 依赖声明 > 人工标注（【三】TTL 列手填）> 自适应；
免重读豁免：offset 增量读永远放行；熔断/强制取证期豁免（降级重建证据需要真重读）；
跨平台命令拦截（按检出 shell 适配）：PowerShell 会话禁 bash 管道（\| head、&&）与裸 Get-Content，改用 Select-String/Measure-Object/-TotalCount；macOS 禁 sed -i 无后缀、grep -P、readlink -f；大小写不敏感文件系统禁仅大小写不同的重名文件；Linux 标准 GNU 无特殊限制。

监察与留痕

盲写拦截：写"本回合没读过的已存在文件"100% 拦截；
风险文件留痕：package.json、lock、CI 配置、.env、.csproj 等修改 100% 记录；
抽查A：每 5 次写操作全量审计 1 次（确定性节奏，不是随机抽样）；
上下文污染检测：工具输出与指令矛盾（单条语句的 head 行数超限 / 清单路径重复；复合命令不整段对账——2.5.3）→ 立即停用该输出，用带标记的小命令隔离核实并报告人类；
回合卫生：回合开始核验上一回合计数/熔断/取证/降权残留（43条），异常记档后清理；新会话发现 HANDOFF.md 注入交叉巡视提醒（36条）；引擎与工作区源码版本不一致告警（42条）；
一切执法行为（触发/处罚/抽查/特赦/预算伸缩）写入 <工作区>/.focus-guard/AUDIT.log（JSONL）：时间 / 会话 / 动作 / 触发条件 / 级别 / 证据 / 是否特赦。

授权与高危命令审批

授权识别：凡声称依人类授权绕过护栏（熔断/锚点/预算/体积），必须先出【授权识别】引人类指令原文 + 指明法条依据；引擎核验引文确实出现在本回合指令且含授权语义。伪造/事后补 → L3 熔断；意图明显但未明说 → 出【授权待确认】暂停并提问；
高危命令闸：即使完全访问（yolo/自动批准）模式，六类不可逆命令仍须实时审批—— 破坏性删除（rm -r、rm --recursive、shutil.rmtree、find -delete、rimraf、DROP TABLE）、强制推送与历史覆盖（git push、git reset --hard、git clean -fd）、系统权限与配置（chmod 777、chown、reg add/delete、net user）、全局依赖安装（npm i -g、pnpm add -g、yarn global add、apt-get install、docker run --privileged）、对外发送与发布（npm publish、docker push、curl -X POST/-d、wget --post-data）、数据库影响（无 where 的 DELETE/UPDATE、DROP DATABASE）；
审批单是唯一通道：命中 → 拒绝并要求一行 【高危申请】命令：<真实命令> | 真实目的：<一句话> | 影响范围：<具体文件/表/系统> | 回滚方案：<可否回滚> | 允许执行？(y/n)；收尾没带单 → Stop 打回补交（一次性，不无限重复）；
y 放行本次（一次性，改一个字符都要重新申请）；n 彻底阻断（会话内不得重发）。中文同样有效：同意/批准 = y，不/拒绝 = n；
预授权隔离：任务指令里的「最后上传 github」只是目标预授权（goal），不解锁任何执行；执行级授权只认人类当下对审批单的短批示；
严禁脚本包装：被拒后写 push.sh 再执行 = 对抗审查（从重记档）；高危脚本的写入本身也要走审批单；
不设卡：普通单文件 rm、构建、测试、本地 commit、常规 curl GET——零打断。放松日常 + 刚性高危。

事前资格审核与司法救济（3.0.5 / 3.0.6 / 3.0.7）

高危命令闸管的是事后拦截（命中即拒，再交人类审批）。3.0.5 起在其之前加一道事前资格审核：高危工具先申请、后执行，无授权直接拒。

六层判定（packages/core/src/core/checkEligibility.mjs，母版层、依赖注入、不反向依赖适配层）：

层	判什么
L0	申请完整性——`purpose` / `scope` 空白即拒
L1	状态——熔断 / 降权 / 预算耗尽
L2	绝对红线（命中即拒，且不进 L3）
L3	高危资格——命中 `HIGH_RISK_TOOLS` 且本会话无授权 → 转人工审批
L4	前置条件——改动类目标须已取证；系统路径 / 特殊目录（`.git`、`node_modules`）加严
L5	语义信号——模型探针的 `mismatch` / 高风险分
L6	授权并留痕

双入口闭环：fg_apply（申请 → 审核 → 按 session 授权）与 pre-execute 的 gateToolCall（无授权 → deny，理由指向 fg_apply）。审核期临时授权、未通过立即收回，避免申请通道被自己的 L3 挡死。
模型画像：src/profiles/ 五份纯参数画像（deepseek-flash / deepseek-pro / glm / gpt-astra / default），按画像跳层并把跳过项写入 trace 与审计。不传画像时与 3.0.4 行为一致。画像不能关闭审批层（profileLoader.mjs 的 FORCED_ON_SWITCHES 强制启用 approvalGate），也不能放行红线层；approvalGate.scope 只决定"哪些类别需审批"（irreversible 时非不可逆高危放行、不可逆类仍须审批）。
环境指纹与命令硬校验：packages/core/tools/env-fingerprint.mjs 探测平台 / shell / 工具并产出 .ai/env-fingerprint.json；pipeline 第 1.5 层据其 map 表做命令硬校验（grep→rg、find→fd 等替代提示），不依赖模型自觉。
绝对红线上下文豁免（3.0.6）：红线在文本层匹配，分不清"要执行的命令"与"被引用的命令字符串"。三条判据把后者降级到第 2 层语义预判（绝不直接放行）：① 命中片段完整落在引号字面量内；② 片段前有显式数据标记（示例：/例如：/测试数据/prompt:/【假设】/代码围栏）且命令非变更类；③ 首 token 属只读输出命令。执行外壳一律不豁免（bash -c / cmd /c / eval / iex / 解释器 -e·-c）——那些引号里的内容是真执行。豁免写 AUDIT.log（action:"redline-exempt" + 判据名 + 命中片段）。
误伤申辩（司法救济通道，3.0.6）：fg_appeal 让被拦方能当场申辩，不必等修法。参数携带被拦命令原文，故 pipeline 在所有闸之前处理它（否则会被同一规则再拦一次），转成 {kind:"ask"} 交人类一次性裁决：批准 → 开通该工具一次授权（ttl=turn）+ 豁免本次命中红线；拒绝 → 维持拦截。全程留痕 appeal-filed / appeal-granted / appeal-denied。法条依据见 RULES.md 第八十三条(四)。

子代理委派（v2.3.0：高产出、低污染）

机制	规则	机械化
委托池独立核算	默认 20 次/任务，不占执行池；用尽批示『追加额度』三池各 +10	每次委派记 `delegate-used`；用尽拒绝并请示
摘要强制格式	主会话只收【子代理摘要】四字段（任务/结果/异常/文件线索），≤200 字	超长或缺字段 → 拒收要求压缩（KPI-3）
强制委派场景	全库搜索 ≥3 目录或 ≥10 文件 / 大文档 >50KB 或 >2000 行 / 批量 ≥5 文件	未委派 → 未尽职提醒（KPI-5）；已委派 +5
独立并行任务	两个任务互不依赖	自申明：引擎无机械特征，不判罚也不加分，AI 不得据此声称"已尽职"
合法委派边界	正常委派放行不计违规	仅熔断期启动子代理 = 越权绕行（L4+L5）

正面指引（告诉 AI 怎么干活）

负面清单管下限，正面指引给标准动作（法条第十五章之一，74–79 条；运行时镜像 packages/core/skills/focus-thinking/SKILL.md §10）：

树杈	标准动作	机械化
环境适配	环境不主动探测，行为暴露后自动适配；有 `.git` 用 `git restore`，没有用 `.ai/backup/`	每次 Write/Edit 前自动备份到 `.ai/backup/`（保留最近 100 份；>200KB 跳过；`.env`/私钥不落明文副本）
返工与提交	只回滚出错文件；重试带"失败包裹"（报错行号 + 堆栈尾 30 行 + 限定范围）；本地 commit 测试全绿 AI 可做	高危审批单：`git push` 命中特征库须【高危申请】，`--dry-run` 例外
污染与日志	参数-输出矛盾 → 标记可疑；改文件前先出【污染核实】声明；超大日志只取统计 + 堆栈尾 30 行	污染核实闸：污染检出后首个改动类先拦一次
任务编排	第一句话声明"通过条件"（可测 = 退出码 0；不可测 = 编译 + 不崩溃 + 《人类验收清单》）；机械任务优先内置库与既有预制脚本（`.ai/tools/`，存在则用）	结案以机器退出码为准
人类交互	提交前固定一行：`【提交申请】修改:<文件> (+n,-m) \| 测试:n/n 绿 \| 允许提交？(y/n)`；仅不可逆操作请示	其余全自动
经验固化	L2/L3 或回滚后往 `.ai/PATTERNS.md` 追加 `[环境:x] [任务:y] 以后遇到 X 必须先做 Y`；新任务不预读，卡点时 Grep 检索	熔断出口提示经验固化（触发熔断时引擎确保该文件存在）

配置

所有阈值集中在 packages/core/hooks/guard.mjs 顶部常量区：

常量	默认	说明
`OUTPUT_GATE_BYTES`	50KB	体积刺客闸值（整读/刷屏拦截线）
`BUDGET_DEFAULT`	10	默认任务预算
`BUDGET_CAP`	200	有效调用硬上限
`REFILL`	10	续杯步长
`STALL_FUSE`	3	连续无效调用熔断线
`MERCY_SHORT`	30	特赦短语仅认短指令的长度上限
`RANDOM_AUDIT_EVERY`	5	每 N 次写操作全量审计 1 次（确定性节拍）
`INV_POOL_DEFAULT`	15	侦查池独立额度
`DELEGATE_DEFAULT`	20	委托池默认额度（不占执行池）
`SHA_LIMIT`	200KB	卷宗 SHA-256 校验上限（超过则用 mtime+size+git 脏态）
`CASE_MAX_ROWS`	200	卷宗【三】最大行数（超出淘汰最旧）
`BACKUP_KEEP`	100	`.ai/backup/` 最大保留份数
`TTL_FIRST/RECENT/WEEK/STABLE`	4h / 2h / 24h / 7天	卷宗自适应 TTL 四级
`ENGINE_VERSION`	3.0.6	42条部署版本核验基准。版本面共 8 处（根 `package.json` / 根 `marketplace.json` / `.zcode-plugin/plugin.json` / `.claude-plugin/plugin.json` / `.claude-plugin/marketplace.json` / `packages/core/package.json` / `packages/extended/package.json` / `ENGINE_VERSION`），由断言锁定"彼此相等且等于 CHANGELOG 最新条目"。引擎头注释例外：`guard.mjs` 已封存、版本号独立，断言只锁"封存标注存在"

工作原理

SessionStart       → 环境检测一次 + 卷宗载入（重建取证缓存与 TTL 表）+ 注入执法模型
UserPromptSubmit   → 批示识别（关键词预算 / 信用延期 / 特赦 / 追加额度 / y-n）+ 重置任务态（保留侦查缓存）+ shell 变化重检 + 任务链起新链
PreToolUse         → 平台命令拦截 + 本地哨兵（opt-in）+ 图书馆直写拦截 + 高危审批闸 + 熔断白名单 + 未取证拦截 + 污染核实闸 + 体积三闸 + 盲写拦截 + 卷宗免重读 + 改动前备份
PostToolUse        → 进度检测引擎（三池 / 续杯 / 停滞熔断）+ 卷宗取证记录 + 污染检测 + 抽查 + 委派 KPI 计分
PostToolUseFailure → 失败计入停滞
Stop               → 回合边界 + 证据锚点检查 + 授权识别核验 + 审批单格式校验 + KPI 兑现结算 + 额度台账落卷

拦截协议：PreToolUse 以退出码 2 拒绝工具调用（原因走 stderr，原文透传给模型）；Stop / PostToolUse 返回 {"decision":"block","reason":...} 打回重写。所有打回路径都有一次性保护（stopBlocked + 宿主的 stop_hook_active），不会因强制续跑变成死循环。

DSH 原生插件（src/dsh/pipeline.mjs）在同一条 PreToolUse 缝上按序叠加（各段独立 fail-open，异常一律放行或原样透传）：

申辩入口(fg_appeal) → 第3层状态/取证校验 → 绝对红线(+上下文豁免/申辩凭据) → 第1.5层命令硬校验
→ 资格审核闸(fg_apply) → 第2层语义预判(哨兵) → next

第 3 层取证校验只对已存在文件的修改要求先读；新建文件无目标可读，直接放行（否则死锁）；
L3 不接红线上下文豁免（闸接、L3 不接）：闸是"无授权即 deny"、无人类环节，必须自判豁免；L3 是"转人工审批"、人类环节本身就是裁决。若 L3 也豁免，"数据形态的高危命令"会无人审批直接放行——风险不对称。判定写在 checkEligibility.mjs 第 3 层注释里，防后人当缺陷改回。

留痕协议：AUDIT.log（JSONL）每条带 seq（事件唯一号）/ chain（任务链，委派派生 /dN 子链）/ ref（父事件）三字段——流水账可随时重组为因果树：node packages/core/tools/audit-chain.mjs <AUDIT.log> [--mermaid]。

落盘全图（写入面共 9 处）：AUDIT.log、卷宗【一】环境声明、【三】侦查记录、【四】额度台账（同 CASE_FILE.md）、会话状态（%TEMP%）、改动前备份（.ai/backup/）、PATTERNS.md 经验库、TEMP 陈旧清扫、派生积木与索引（仅 library-build 写到 .ai/output/library/）。

常驻注入的体量

常驻注入 SESSION_RULES 运行期实测 425 字（246 全角 + 179 半角，≤500 字立法上限；3.0.0 因果链提示 +14 字）。典型长会话的执法可见开销加权实测 3404 字 ≈ 2269 tokens（2.5.3 实测值，3.0 新增报文：哨兵拦截 175 字级、图书馆隔离 40 字级、KPI 结算 0 字——仅落档不打扰）：

场景	引擎实测字符	会话内次数	加权
SessionStart 常驻注入	531	×1	531
卷宗免重读放行（最高频）	145 / 次	×10	1450
触发③体积三闸（三连拦场景合计）	278	×1	278
熔断出口（拒绝 + 打回）	268	×1	268
动态预算续杯	73 / 次	×3	219
高危审批闸拦截	175	×1	175
强制场景未委派提醒	131	×1	131
触发①未取证就改	56 / 次	×2	112
委派摘要超长拒收	107	×1	107
上下文污染检出	93	×1	93
盲写拦截	40	×1	40
加权合计			3404 字 ≈ 2269 tokens（1 token ≈ 1.5 中文字符，区间 1702–2837）

复测：npm run bench。v2.2.0 曾对报文做电报体压缩（当时相对更早版本 -31.6%，对比基线已失效，只作历史记录）；2.4.0 起审批单与委派报文变长，故当前总量高于那次优化后的数值。报文只保留"标签 + 动作指令"，规则细节由技能与法典承载。

测试与质量闸

npm test                                             # 验收 101 用例（含版本一致性 / 版本追赶 / 文档-实现口径对齐）
npm run test:eligibility                             # 资格审核 45 用例（六层 + 红线豁免 + 申辩）
node --test packages/core/tests/integration.test.mjs  # 端到端 27 用例（画像→审核→授权→闸→取证闸）
node --test packages/core/tests/profile.test.mjs      # 画像加载 8 用例
npm run eval                                         # 对抗评测：61 条高危写法 + 34 条良性命令，有漏检或误报即 exit 1
npm run bench                                        # 报文体量基准
npm run check                                        # test + eval（pre-push 钩子跑的就是它）
npm run library                                      # 派生积木构建（默认 --src .ai/library --out .ai/output/library，幂等）
npm run chain -- <AUDIT.log路径> [--mermaid]         # 执法档案因果树渲染
npm run sentinel -- --check "<命令>"                  # 本地哨兵单条预判
npm run test:bridges                                 # 扩展包桥测试（单独跑）

双包架构（3.0.6）：范本 + 衍生

本仓是 npm monorepo，一个项目、两个包：

包	路径	定位
`focus-guard`	`packages/core/`	零依赖范本——引擎钩子、技能、核心工具、法条文档、DSH 原生插件。`npm install focus-guard` 只下载本包，不拉任何外接依赖。主分支即从此包发版，可衍生无数变体。DSH 挂载的正是这个包——它的 `package.json` 版本就是 GUI 里显示的那个。
`focus-guard-extended`	`packages/extended/`	扩展衍生包——依赖 core（`"dependencies": {"focus-guard": "^3.0.6"}`），承载重型外接三件套：OpenViking 积木同步桥（`viking-bridge.mjs`）、Needle 2 外判运行器（`needle2-sentinel.mjs`）、Semantica LPG 图谱导出（`audit-chain-semantica.mjs`）。

衍生纪律（详见 packages/extended/bridges/README.md）：桥只依赖主分支契约（审计 JSONL 格式、哨兵外判协议、积木 INDEX 格式），禁止 import 主分支源码，禁止被主分支引用（验收用例锁定零反向依赖）；桥故障一律静默回退核心默认行为。新增外接 = 在 extended 包加一个自包含文件 + 一条桥测试。

CI：每次推送/PR 自动跑验收 + 对抗评测（.github/workflows/ci.yml）。Windows 必过；Linux/macOS 为观察项（验收里仍有数处 Windows shell 检测用例未平台化），Node 18.20 / 20 / 22 矩阵；
本地质量闸（pre-push 钩子，GitHub Actions 不可用环境的主闸）：.githooks/pre-push 在每次 git push 前强制 npm run check（验收 + 对抗评测），不过即阻止推送，结果留痕 AUDIT.log（ci-pre-push 事件）。克隆后启用一次：git config core.hooksPath .githooks；强行绕过（--no-verify）按法规须先批示——钩子留痕只在正常触发时写入，绕过即失察；
覆盖范围（101 用例）：动态预算与三池分池、进度检测与信用延期、触发①②③④⑤（含审计豁免）、梯度处罚与熔断只读放行、卷宗体系（环境检测 / 环境声明落卷 / 免重读含会话内限定 / SHA 防伪 / TTL 三级覆盖 / 台账落卷 / caseCache 裁剪）、跨平台命令拦截、盲写与抽查A、上下文污染与污染核实闸（含复合命令不误报）、授权识别（伪造引文 → L3 / 合规声明 → 特赦 / 待确认 → 暂停）、高危命令闸（特征库 / 审批单 / y-n 一次性 / 预授权隔离 / 脚本包装端到端 / 熔断期拒绝 / 超长命令）、子代理委派与委托池、极限场景（80KB 命令行、2MB 响应、损坏状态、奇异会话 ID、中文路径）、DSH 桥接自适应，以及工程自检（七处清单版本一致性 / 版本追赶 / 五处说明互不重复 / 文档-实现口径对齐 / RULES 注入逐字镜像 / hooks.json ↔ 引擎映射 / 部署漂移核验 / 61条陈旧清理）；
对抗评测样本按"同一危险动作的多种写法"组织（别名、长旗标、传参穿插）并配良性反例，避免用误报换检出。

设计取舍与已知边界

回合边界双保险：实测 UserPromptSubmit 不保证触发，回合计数由可靠的 Stop 事件兜底清零，reset 仅作尽力而为的提前重置；
钩子读取的是安装副本：改源码不会自动生效，需同步安装缓存或经市场更新——"源码已升级但引擎没变"是这套系统最常见的部署事故，INSTALL.md FAQ 4 有排查步骤；
平台受限暂缓条款：第 21 条 Token 成本核算、第 37 条思考链监管（钩子层不可见 token 用量与思考时长）、第 64 条(二)(三)(四)限流（无对应信号）；第 48 条子代理继承以留痕方式实现。完整"未机械化条款清单"见 packages/core/docs/RULES.md 附注——凡清单所列，AI 不得声称已由引擎自动执行；
>200KB 文件没有内容级防伪：见上文卷宗体系边界说明；
引号内的危险字样：按上下文分级（3.0.6）——echo "git push"、grep -rn "delete from users" 这类被引用的数据经三条判据（引号内 / 数据标记 / 只读命令）降级到语义预判，不再直接拒；执行外壳内的一律不豁免（bash -c "…"、node -e "…"、eval "…"），因为那是真执行。仍未覆盖的形态：无引号又无数据标记的裸引用、rm${IFS}-rf 类拼接。判据名与命中片段写入 AUDIT.log 可复核；
特征库不可能堵完：rm${IFS}-rf、base64 管道、shell 别名等在射程之外，护栏治的是"顺手失控"，不是定向对抗；
免重读的边界：指纹一致但会话上下文已被压缩时，用 offset 增量读或请批示；【二】依赖声明与【三】TTL 列人工标注可按需放宽/收紧；
行业对照（2026-10 系统提示词研究，详见 docs/analysis/）：各大厂商把 Agent 持久性推到极致（"persist until complete"）且提示词层无一设预算机制。FocusGuard 的定位由此清晰：坚持性交给模型自判（厂商已做好），成本台账与破坏性关卡由宿主侧硬约束承担——熔断随模型进化从常开保险丝退为断路器，但断路器不拆；
违禁词扫描已废弃（v3.0 起"不查词"）：空气层允许口语与主观语气，执法只看行为。

版本与变更

当前 v3.0.6。完整历史见 CHANGELOG.md。近期版本：

3.0.6 绝对红线上下文豁免与司法救济：redlineExempt() 三判据（引号内 / 数据标记 / 只读命令）把"被引用的危险命令字符串"降级到语义预判，执行外壳一律不豁免；新增 误伤申辩程序 fg_appeal（司法救济通道，补齐"只有立法救济、没有个案当场申辩"的结构缺口）；画像接入真实 pre-execute 链路 + 画像/豁免在真实入口失效的 4 项修复；审批层不可被画像关闭；approvalGate.scope 由死配置变真判定；闸接入红线豁免、红线判据 span 稳定化、取证闸对新建文件不再死锁；条款清理 91→87；版本面补全为 8 处（此前漏了 monorepo 子包，导致"清单齐 3.0.4 而代码已 3.0.6"）；
3.0.5 事前资格审核与模型画像：checkEligibility 六层判定（L0 申请完整性 / L1 状态 / L2 绝对红线 / L3 高危资格 / L4 前置条件 / L5 语义信号 / L6 授权留痕）+ fg_apply 双入口闭环（申请 → 审核 → 按 session 授权）；src/profiles/ 五份纯参数模型画像 + profileLoader 按画像跳层；环境指纹与命令硬校验（grep→rg、find→fd）；guard.mjs 三次拆出 src/core/ 九个模块与 src/adapters/dsh/protocol.mjs（1707 → 1142 行）；
3.0.4 双包 monorepo：packages/core（focus-guard 零依赖范本包）+ packages/extended（focus-guard-extended 扩展包，承载外接三件套）；npm install focus-guard 永不拉取扩展依赖；中心蜂群强化——调度三分法、派单给目标不给方法脚本、跨任务授权不对称、模型分层蜂群、对抗验证三怀疑者（第八十条增订七～十、第八十一条增订四）；library-build 幂等键改纯内容指纹；
3.0.3 主分支精简版：外接三件套移出主分支（迁 packages/extended），主分支保留哨兵本体与外判契约；
3.0.2 外接三件套：viking-bridge（OpenViking 积木同步）/ audit-chain --semantica（Semantica 图谱导出）/ needle2-sentinel（Needle 2 外判运行器）+ 批示词尾置容错；
3.0.1 合并审批：多条高危待批合并出示、一次 y 放行全部（各一次性消费）；批示词容错（"y，顺带把文档也改了"）；写入闸对抗审查同源判定；
3.0.0 协作治理版：按 3.0 规划（十大原则）将治理面从单会话扩展到多代理协作与知识资产——中心调度与蜂群委派法典（第八十条）、去中心化验证（八十一）、静态积木图书馆 .ai/library/（八十二）、本地零成本哨兵 tools/sentinel.mjs（八十三，Needle 2 可插拔）、KPI 兑现闭环（八十四，收尾结算等次→委托池奖惩）、提问漏斗（八十五）、因果链留痕 seq/chain/ref + tools/audit-chain.mjs（八十六）；新增 tools/library-build.mjs 积木构建器；修复 deep-review 遗留：FG-D1 引文核验窗口 500→4000 字符、FG-D2 原子写、FG-D3 tmp 残片、FG-D4 降级防御、解释器 eval 不再判只读侦查；法典增第十五章之二（第八十～八十六条）；
2.5.3 实测误伤修复版：卷宗继承指纹只提示不拦（跨会话首读不再被拦）；58 条对账限单条语句（复合命令误报清零）；审计任务体积闸豁免；卷宗【一】/PATTERNS.md 写失败告警；61 条落地（启动清扫 30 天未动临时文件）；法典 v1.1 修法（SKILL 效力条款改为"暂停机械执行＋报请裁决"、废止 19/24四/44/45/46 条、47 条限定同机跨运行时）；仓库迁移 irisblackwood；验收 86 → 90；
2.5.2 对抗审查版：修 P0——熔断期白名单先 exit 0，导致 npm publish/shutil.rmtree/reg add 等不在变更表里的高危命令在熔断期绕过审批；修中文批示（同意/批准/不/拒绝 因正则 \b 不认 CJK 全部失效）、止停令被写回 false、超 300 字符命令 y/n 永不匹配、Stop 部分打回缺一次性保护、sudo mv/xargs mv/cp/sed -i 被当只读侦查、bash↔zsh 切换永不重检；.env/私钥不再落明文备份、状态原子落盘；补 CI 与 CHANGELOG，验收 63 → 86；
2.5.1 盘点修复版：五处清单 + 引擎号 + 头注释全链一致并由用例锁定；假留痕防线（AUDIT/卷宗/备份写失败一律上 stderr）；卷宗【一】环境声明落卷；58 条路径查重判定修正；五处插件说明去重；

文档索引

文件	给谁看
README.md	人类：这是什么、怎么装、边界在哪（本文件）
INSTALL.md	逐行安装（ZCode / DSH 两条路）/ FAQ / 卸载
docs/HANDOFF-TO-EXTERNAL.md	外部接手模型：现状依据、任务书、纪律陷阱、环境事实
packages/core/docs/RULES.md	法条原文 + 技术映射明细 + 未机械化条款清单（永不自动加载）
packages/core/skills/focus-thinking/SKILL.md	AI 运行时镜像：聚焦方法 + 纪律条款
packages/core/docs/MASTER-PLAN-2.0.0.md	卷宗体系工程总纲
packages/core/docs/MASTER-PLAN-3.0.0.md	协作治理工程总纲（十大原则 → 十项机制）+ 分层总规范
packages/core/docs/LEGISLATION-LAW.md	立法法：规则怎么立、怎么改、怎么备案
packages/core/docs/deepseek-pricing-audit.md	峰谷价目核对（成本台账口径来源）
packages/core/tools/	积木图书馆构建 / 因果链渲染 / 本地哨兵 / 环境指纹
packages/extended/bridges/README.md	外接三件套的契约与衍生纪律
CHANGELOG.md	版本变更
packages/core/tests/	验收用例、对抗评测、报文基准

focus-guard (core)

설치

README