架构全景与主流程走读
分层设计概览
Agent 工具调用 (Write / Edit / Bash / Read / Grep)
└─▶ Claude Code PreToolUse(无 --net,30s–120s 超时窗口内快速阻断)
├─ 解析失败 / 违规 / 缓存缺失过期 ──▶ permissionDecision: deny JSON + exit 2
└─ 精确 pass ────────────────────────▶ exit 0 安静放行(交回宿主权限流转)
Git 生命周期 (pre-commit / pre-merge-commit / commit-msg / pre-push)
└─▶ Git 客户端钩子(带 --net,联网懒刷新 + 单名即时查询)
└─▶ 统一策略引擎 policy/check.py (R1–R7 三态裁决 + ssh-keygen 验签)
├─ pass ──────────────────────▶ exit 0 允许提交或推送
└─ violation / error ─────────▶ exit 1 并输出脱敏原因或签名指引主工作流走读
以下核心走读直接复用自仓库维护的源码指南 repo-docs/walkthroughs/one-real-run.md:
当 Agent 准备通过文件写入工具落盘内容时,内容包装脚本会在落盘之前把新增正文送进本地策略引擎,确保疑似凭证、私有仓名或禁用标记不会先写入工作区再事后清理。整条快速检查路径必须在工具超时窗口内结束,因此绝不发起网络请求,并严格区分“确认干净”和“无法完成检查”。
这条操作路径输入 Claude Code 的工具事件 JSON,输出只有两种可能:安静允许宿主继续权限流转,或者立刻以违规理由拒绝调用;难点在于把超时、解析失败与缓存过期一律收敛成明确阻断。
Step 1: 从工具事件取出真正的新增内容
宿主触发 PreToolUse 事件后,内容拦截包装(仓库文件:hooks/forbid-content.sh)从标准输入读取工具事件 JSON,依次提取 content、new_string 或 new_source,分别覆盖 Write、Edit 与 NotebookEdit 三类文件修改动作,同时取出目标路径仅作提示上下文。
若输入 JSON 解析失败,脚本直接进入拒绝分支而不视作空内容(fail-closed);若待写内容确实为空,则调用公共辅助(仓库文件:hooks/_lib.sh)里的 pass 安静放行。注意该步骤只检查本次新增载荷,不负责审计仓库原有历史;各类包装脚本与 Git 钩子的分工见双层钩子包装与交互契约。
Step 2: 在部署配置下运行同一个引擎
确认存在待检正文后,包装脚本把提取到的文本写入临时文件,经由公共辅助(仓库文件:hooks/_lib.sh)定位已安装的策略引擎(仓库文件:policy/check.py),以 content 模式启动检查:
- 该路径刻意不传
--net参数,因为工具钩子在宿主超时窗口(默认为120s/30s)被终止后会被宿主按“无决策”放行,所以联网刷新被完全隔离到会话启动阶段与 Git 钩子层。 - 仓库模板中的路径占位符必须先经过铺设脚本(仓库文件:
policy/bootstrap.sh)改写为实际部署目录$GUARD;未安装克隆中直接调用会因找不到已部署配置与缓存而报错退出。部署细节与路径改写流程见部署安装、路径改写与本机自检。
Step 3: 结合静态规则与动态缓存完成 R1–R7 判定
策略引擎(仓库文件:policy/check.py)的 cmd_content 入口调用 full_check,按顺序完成两层扫描:
工具新增文本 ──▶ scan() 静态扫描(R2 型号/会话正则 + R7 凭据正则)
├─ 命中 ──▶ violation + 脱敏理由(exit 1)
└─ 未中 ──▶ private_check() 动态缓存检查(R1/R4)
├─ 缓存缺失或超过 6h TTL ──▶ error(exit 1)
├─ 命中私有仓名或业务正则 ──▶ violation(exit 1)
└─ 全部干净 ──────────────▶ pass(exit 0)引擎在 R2 模型正则中通过 in_b64_run 跳过长度 ≥ 24 且混杂大小写字母与数字的无分隔符编码串,避免内嵌媒体或数据 URI 误报;但在 R7 凭据正则中不启用该豁免,并在命中后通过 mask 仅截取前 8 个字符输出,避免完整凭证回显到会话日志。规则细节见策略引擎判据,动态名单聚合与校验逻辑见动态私有名单刷新机制。
Step 4: 安静放行与拒绝输出映射
包装脚本读取引擎在标准输出打印的三态关键词(pass / violation / error):只有当结果精确等于 pass 时才调用 pass 函数以 0 安静退出——绝不输出 permissionDecision: allow,以免在 Claude Code 中连带跳过宿主原本的用户权限确认弹窗。
只要引擎返回 violation、error 或其它异常输出,包装脚本立即调用 deny,向标准输出写入包含 permissionDecision: deny 与脱敏说明的 JSON、向标准错误打印原因并以退出码 2 终止,同时提示刷新指令供人工或独立会话钩子更新缓存。当最终进入 Git commit 或 push 阶段时,Git 钩子层会带着 --net 对实际对象树、SSH 签名与新增历史做最终强校验。
Step 5: 只读自检与验证边界
可在仓库根目录执行一条只读自检命令核对当前机器的接线与缓存状态:
python3 policy/doctor.py在未运行铺设脚本的源码克隆中,该命令预期报告 FAIL 与 Overall: DEGRADED,这说明本机尚未完成安装接线,不能将只读自检或文档构建当作运行时防护已生效的证据。若需要按模块查找源码位置与改动入口,继续阅读代码地图;若要核对源码证据范围与未执行验证边界,查看源码证据审计。