Vai al contenuto principale
I

focus-guard

irisblackwood/focus-guard

司会(Keepward)核心包:给 AI 编码智能体(ZCode / DSH 双端原生硬拦截)装上的履职纪律与监察系统。三件事:① 硬拦截——六条钩子覆盖会话启动到收尾,三预算池、L1-L6 梯度处罚、高危命令审批单、KPI 兑现;② 长期记忆——反复出现的动作自动沉淀,TTL 到期即遗忘;③ 前缀稳定——观测 system-prompt 装配的前缀抖动,缓存断开即告警。日常零打扰、只查行为,全程因果链留痕,含积木图书馆。零依赖(Node.js ≥18),是所有人下载的范本包——外接集成见 focus-g

Installazione

dsh plugin --profile web add github:irisblackwood/focus-guard

README

司会 Keepward

状态:权威 · 适用版本 3.5.1 · 最后核对 2026-11-17

English · 中文

旧名:FocusGuard / 聚焦护栏(3.5.0 起更名)。包名 focus-guard、插件 id focus-guard、 状态目录 .focus-guard/、环境变量 FG_* 一律不变——更名只动展示层,不动技术契约。 新名取《周礼·天官》「司会」,掌邦国财政考核,读 sī kuài(会计之会,非 huì)。

CI version License: AGPL v3 Node

版本口径:对外展示一律以 GitHub main 为准(PUBLISHED_MAX);npm registry 已发 3.5.1(2026-11-17,OIDC 受信发布 + provenance)。 本地开发版本可以领先已发布版本,领先不等于已发布。此页显示的版本号由 docs:lint 对着 PUBLISHED_MAX 校验。

AGPL-3.0-only + 商业双授权:按 AGPLv3 使用,商业使用同样允许;不愿承担 AGPL 义务(尤其第 13 条网络开源)的,可另购商业许可——那是替代路径,不是对商用的限制。商标 司会 / Keepward 保留,衍生版本不得沿用;旧名 FocusGuard / 聚焦护栏 作为历史别名同样保留。细节见 LICENSE / NOTICE。

30 秒速览

失控现象机械拦截人类看到
没调查就改文件 / 跑变更命令触发① → L1 打回一条拒绝原因
结论没有 [文件:行号] 证据触发② → 收尾打回一条打回理由
整读大文件、裸 cat 刷屏体积三闸 + 检索提示一行"分段读或交子代理"
反复无效调用、无限空转预算 + 停滞 → 熔断熔断出口 + 三行降级方案
顺手 rm -rf / git push / npm publish高危命令闸 + 资格审核审批卡片:批准本次 / 阻断
上下文被巨量输出撑爆污染检测 + 卷宗免重读记档 + 复用已有取证
反复读同一个没变的文件卷宗指纹 + TTL拦本次 Read(offset 增量读永远放行)
模糊需求上来就改代码第 1.3 层动笔闸先加载方法论,再动笔

为什么需要它

AI 智能体的三类失控:思考失控(没证据就猜)、资源失控(整读与刷屏烧上下文)、权限失控(先斩后奏、无法追溯)。

"立法 → 执法 → 监察"把三类失控变成可拦截的行为事件:法条(RULES.md)定标准,引擎机械执行,留痕(.focus-guard/AUDIT.log)接受人类复核。

引擎按四层组织,依赖方向由验收用例锁定(core → adapter → seam 单向):

层位置职责
母版层packages/core/src/core/零依赖判定逻辑:资格审核 / 画像 / 红线与豁免 / 申辩 / 状态 / 审计写入器。不得反向依赖适配层
适配层packages/core/src/adapters/dsh/把母版接进 DSH:fg_apply / fg_appeal 注册 + 资格闸
宿主缝packages/core/src/dsh/三条缝的注册与编排(pipeline.mjs);各层判定在 guard/
ZCode 执行壳packages/core/hooks/guard.mjs已封存:版本独立、只做兼容,不随主版本演进

机制细节(触发/处罚/预算/卷宗/监察/审批/资格/委派/配置/工作原理):ARCHITECTURE.md。能力状态与缺口:ARCH-MAP.md。

快速开始

# 核心版:零依赖。npm 已发布(版本以 npm view focus-guard version 为准)
npm install focus-guard

装到 DSH(首选):原生插件与官方桥二选一、互斥(同缝双挂 = 双跑):

路径命令 / 挂载拿到什么
原生插件(推荐)dsh plugin --profile <name> add focus-guard8 事件 / 12 监听:拦截判定、规则与成本注入、turn/step 留痕、熔断结算、压缩监察
官方桥@deepseek-ai/dsh-hooks-claude-code 挂 packages/core/hooks/hooks.json与 ZCode 同级六事件硬拦截,不含资格审核与申辩

装插件三种写法,差别只在版本来源:add focus-guard(npm 最近发版)/add github:irisblackwood/focus-guard#path:/packages/core(main 未发布改动,monorepo 必须指到子目录)/add <路径>/packages/core(本地开发)。详见 INSTALL.md §2A。

装到 ZCode:仓库根目录 → 插件市场 → 添加市场 → 安装 → 新开会话(并存,非首选)。

验证生效:新会话出现执法模型注入,且工作区生成 .ai/CASE_FILE.md 与 .focus-guard/AUDIT.log。逐行步骤、卸载、FAQ 见 INSTALL.md。

首次安装会自清洁:发布物里不该有审计日志、脑索引、私有面目录。万一哪天打包配置被改错带了出去, postinstall 会把这些误打包的运行期产物清掉,脑从 0 开始长(法条随文档重新读入)。 判据是 .git——开发副本里的私有产物是数据,一律不动;只有安装副本才清。手动跑:npm run privacy:sweep。

看一眼你的脑(3D,可选)

把审计事件摊成一个体积:实体是位置,共现是连线,强度是大小。时间轴告诉你「发生了什么」, 它告诉你「什么东西在长、什么东西正在被忘掉」。

npm run brain                # 仓库里:增量重算 → 渲染 → 打开
npm run brain:build          # 仓库里:同上,不打开(脚本 / 无桌面环境用)
npm run brain -- --rebuild   # 仓库里:丢掉索引,从头重算
npx focus-guard-brain        # 装了包:读**当前目录**的 .focus-guard/AUDIT.log,生成后打开

数据根跟着工作区走:cwd 下有 .focus-guard/ 或 .ai/ 就用它,否则退回包的安装位置。 所以插件用户在自己项目里跑,看的是自己的足迹,不是包目录里那份空的。

产物固定在 .focus-guard/brain.html(引擎的隐藏状态目录里)。跑完终端会打出 file:// 的绝对地址, 点一下就能开;不想记路径就用 npm run brain / npx focus-guard-brain,它们会自己打开。产出是单个 HTML 文件,双击即开。它只读审计:不写 AUDIT.log、不碰状态、不在任何工具调用路径上——跑不跑都不影响拦截。

渲染分三档,入口只有一个。 包里带一份皮层资产(packages/core/assets/cortex.bin, pial 表面降采样点云,约 2.8 万点),clone 和 npm i 都能拿到,脑壳就是真皮层; 把 assets/ 删掉才退回程序化沟回。跑完看终端那行「脑壳:…」就知道自己用的是哪一档,不猜。 真 PLY 全网格只在本地:npm run brain:cosmic(强制皮层版,没资产会明说并退出)。

皮层资产是 CC BY-SA 3.0、代码是 AGPL-3.0-only,两者按并列分发处理, 条款各自约束各自部分——署名与条款全文见 assets/NOTICE.md,再分发请保留该文件。

第一次跑是空的,这是对的:新装没有足迹,脑的形状由沟回 + 法线光照撑住,不靠记忆点亮。 跑几次让 guard 记下动作,足迹与连线才长出来。头部如实报「实读几份文档、缺几份」—— self-improvement/ 与 .ai/ 是私有面,别人 clone 下来本来就没有,缺是正常的。

背景是程序化生成的星空(恒星 / 银河带 / 星云 / 两台黑洞),零外部资源、纯着色器。 怎么画的、为什么这么画、?stars=0 是干什么用的,见 BRAIN-VIZ.md。

文档地图

想知道读
全部文档入口(权威/参考/台账/归档)docs/INDEX.md
法条原文 + 未机械化条款清单RULES.md
机制怎么运作(触发/处罚/预算/卷宗/审批/资格/委派)ARCHITECTURE.md
能力状态、代码锚点、缺口ARCH-MAP.md
3.3 → 4.0 排期(3.5=文档完成态,4.0=Hook 完全态)VERSION-PLAN.md
发版计数与受众口径RELEASE-POLICY.md
基准跑法与数字快照BENCH.md
变了什么CHANGELOG.md

版本

当前 v3.5.1,完整历史见 CHANGELOG.md。下一版规划见 VERSION-PLAN.md。

License

AGPL-3.0-only + 商业双授权(详见 LICENSE / NOTICE)。贡献条款见 CONTRIBUTING.md。

Plugin correlati