Skip to content

代码地图与维护守卫区分 ​

以下目录职责与关键符号导航直接复用自仓库源码指南 repo-docs/code-map.md,并经由 .vitepress/guide-links.mts 将仓库相对路径自动转换为可查阅的文件位置标注,确保静态文档站无失效链接。

先通过一次真实工具写入判定理解主路径上的阶段交接,再按本页的目录职责与专题模块快速定位具体源码。

路径职责关键代码与主流程的关系
hooks/Claude Code 事件包装、读路径保护、动态名单刷新、单名解析与存量审计双层钩子包装与交互契约、动态私有名单刷新机制截获工具调用并做快速离线阻断,或在会话启动/联网层刷新名单
hooks/git/Git 客户端强制钩子入口(预提交、预合并、提交信息、推送复查)双层钩子包装与交互契约带 --net 对真实 Git 对象、作者署名与 SSH 签名做最终强制门禁
policy/统一策略引擎、静态规则集、部署铺设、设置注入、凭证编译辅助与一键自检策略引擎判据、部署安装与自检机制承担唯一规则裁决,并负责将包内模板路径改写并接线到宿主和 Git
tools/本仓库自身的离线维护安全守卫(对象扫描、Conventional Commits 校验、精确哈希白名单)repo_maintenance_guard.py(仓库文件:tools/repo_maintenance_guard.py)仅保护维护本仓库自身提交,独立于分发部署的产品防泄漏套件

hooks/ ​

重要代码功能关键符号调用方 / 使用方
hooks/_lib.sh(仓库文件:hooks/_lib.sh)公共环境设置(PYTHONUTF8=1)、安静放行 pass、deny JSON 输出与命令读取pass、deny、get_cmd、engine_content各 .sh 包装脚本
hooks/forbid-content.sh(仓库文件:hooks/forbid-content.sh)拦截 Write / Edit / NotebookEdit 工具写入payload并委托 check.py contentPreToolUse、__PARSE_ERROR__Claude Code 设置模板
hooks/forbid-commit.sh(仓库文件:hooks/forbid-commit.sh)阻断 --no-verify、-n、--no-gpg-sign、篡改配置、提供商邮箱及命令违规词get_cmd、engine_contentClaude Code Bash(git *)
hooks/forbid-push.sh(仓库文件:hooks/forbid-push.sh)阻断推送到 agent_branch_prefixes 分支及绕过标志,并扫描推送命令文本agent_branch_prefixes、engine_contentClaude Code Bash(git *)
hooks/forbid-read-secret.sh(仓库文件:hooks/forbid-read-secret.sh)提醒级拦截读取本地令牌文件、env、os.environ、process.env、gh auth status -t 等暴露命令get_cmd、denyClaude Code Bash
hooks/forbid-read-path.sh(仓库文件:hooks/forbid-read-path.sh)针对 Read / Grep 对绝对路径做 realpath 与 Windows 反斜杠归一,放行公钥白名单并拦截敏感文件file_path、path、SENSITIVEClaude Code Read|Grep
hooks/forbid-tamper.sh(仓库文件:hooks/forbid-tamper.sh)拦截改动 core.hooksPath、disableAllHooks 与删改 $GUARD 目录或 settings.jsonBASE、HOMEDIRSClaude Code Bash
hooks/refresh-private.py(仓库文件:hooks/refresh-private.py)聚合本机种子、主托管平台 API 与可选 GitHub 来源,执行完整性校验后原子写缓存collect、all_tokens、failSessionStart、check.py --net、bootstrap.sh
hooks/resolve-private.py(仓库文件:hooks/resolve-private.py)对缓存外 xxx-xxx 与已知 owner 候选按成功来源即时查询,并维护 24 小时正负缓存resolve_github、merge、maincheck.py --net、scan-repo.py
hooks/scan-repo.py(仓库文件:hooks/scan-repo.py)基于动态缓存与二进制嗅探对当前树或 --scan-history 全历史树做存量审计scanbytes、is_text、keep人工显式审计与基线清理

hooks/git/ ​

重要代码功能关键符号调用方 / 使用方
hooks/git/pre-commit(仓库文件:hooks/git/pre-commit)强制 commit.gpgsign=true、gpg.format=ssh 与非通用指纹,扫描 ACMR 暂存路径及 + 新增行check.py content --net、ssh-keygenGit 全局 core.hooksPath
hooks/git/pre-merge-commit(仓库文件:hooks/git/pre-merge-commit)直接 exec 转发到同目录 pre-commit,补齐 git merge 触发缺口execGit pre-merge-commit
hooks/git/commit-msg(仓库文件:hooks/git/commit-msg)提交信息与作者检查入口,传递提交消息文件并强制三态 fail-closedcheck.py commit --netGit commit-msg
hooks/git/pre-push(仓库文件:hooks/git/pre-push)把 remote 名与标准输入 refs 交给引擎核查未推送提交与分支规则check.py push --netGit pre-push

policy/ ​

重要代码功能关键符号调用方 / 使用方
policy/check.py(仓库文件:policy/check.py)唯一策略引擎:提供 content / commit / push 三模式、R1–R7 规则、SSH 验签与重签豁免full_check、private_check、resolve_unknown、commit_signature、known_content、cmd_pushClaude 包装脚本、Git 钩子、scan-repo.py
policy/policy.json(仓库文件:policy/policy.json)可分发静态策略配置:定义 forbidden_patterns、secret_regexes、agent_branch_prefixes、指纹、邮箱与 TTL 参数R1–R7 参数、resolve_budgetcheck.py、doctor.py、forbid-*.sh
policy/bootstrap.sh(仓库文件:policy/bootstrap.sh)解包到 $GUARD、保护本机私有文件、用 sed 改写模板路径并配置 Git 与 Claude 设置PKG_URL_DEFAULT、HOOK_PACKAGE_URL、GUARD_REPOS本机终端与云端容器 Setup Script
policy/install-settings.py(仓库文件:policy/install-settings.py)向 ~/.claude/settings.json 或仓库设置幂等合并 6 个 PreToolUse、1 个 SessionStart 与 attribution.sessionUrl=falseHOOKS、ATTRIB、git_exclude_if_untrackedbootstrap.sh 与手动设置接线
policy/doctor.py(仓库文件:policy/doctor.py)从自身位置推算 $GUARD,只读检查设置接线、Git 钩子、名单健康与 SSH 签名配置Overall、ok、warnbootstrap.sh 末尾及人工排错
policy/build-secure-token.py(仓库文件:policy/build-secure-token.py)读取令牌源码模板并注入 $GUARD_PKG_URL,生成 32 字节随机会话密钥 XOR 混淆的 C++ 源码enc、DEFAULT_PKG_URL构建本机 token-helper ELF 时使用
policy/token-helper.cpp(仓库文件:policy/token-helper.cpp)仅作本机编译用的凭证数据源模板,运行时解密写入环境变量并 exec 子进程TOKENS配合 build-secure-token.py 交叉编译
policy/msgcb-hygiene.py(仓库文件:policy/msgcb-hygiene.py)git filter-repo --message-callback 历史消息中性化回调,依赖本机 sanitize-map.jsonsanitize-map.json历史清理迁移工作流

tools/ ​

重要代码功能关键符号调用方 / 使用方
tools/repo_maintenance_guard.py(仓库文件:tools/repo_maintenance_guard.py)本仓库专用离线安全扫描与提交标题格式检查器,支持按对象与精确 SHA-256 白名单审计staged、message_problems、pushed、blocked_path、install仅维护本仓库的本地维护钩子
tools/repo_maintenance_hooks仓库内本地安装目录,包含 pre-commit(仓库文件:tools/repo_maintenance_hooks/pre-commit)、commit-msg(仓库文件:tools/repo_maintenance_hooks/commit-msg) 与 pre-push(仓库文件:tools/repo_maintenance_hooks/pre-push) 启动器repo_guard_python执行 install 后由本克隆局部 core.hooksPath 调用

修改入口与常见陷阱 ​

  • 需要增减静态禁止正则、凭据正则或 Agent 分支前缀:先改策略配置(仓库文件:policy/policy.json),并在策略引擎(仓库文件:policy/check.py)的 scan 或 cmd_push 中核对匹配方式(例如 R2 受 in_b64_run 影响而 R7 不受影响)。
  • 需要调整 Claude Code 工具拦截与 JSON 契约:同步核对配置模板(仓库文件:settings.json)、设置注入脚本(仓库文件:policy/install-settings.py)(去重依赖脚本文件名)与公共辅助(仓库文件:hooks/_lib.sh),避免新包装脚本因复用旧文件名而被 install-settings.py 跳过。
  • 需要排查本仓库自身提交为什么被拒:注意区分tools/repo_maintenance_guard.py(检查提交标题是否符合 Conventional Commits 及本地对象)与$GUARD/hooks/git/*(已安装产品的全局防泄漏钩子);本仓库的自检脚本(仓库文件:policy/doctor.py)会在启用了本地 tools/repo_maintenance_hooks 时明确提示全局钩子被局部覆盖。

覆盖范围 ​

本指南已覆盖仓库中除文档载体以外的全部核心运行源码,包括配置模板(仓库文件:settings.json)中的 6 个 PreToolUse + 1 个 SessionStart 接线定义;根目录的项目元数据(仓库文件:meta.json)仅作为个人主页展示索引未作业务修改。

以下边界不在本仓库源码中直接分发或未在本轮执行:

  • 运行时本地隐私文件($GUARD/private-seed.json、$GUARD/sanitize-map.json、private-repos.json、.resolve.json 与编译产物 token-helper)只存在于部署侧,绝不进入仓库。
  • docs-site/ 为 VitePress 文档发布载体,.github/workflows/ 负责发布工作流,均不参与防泄漏拦截判定。
  • 本轮验证边界为源码核对、validate_repo_docs.py 与 VitePress 静态构建;未在本机执行 bootstrap.sh 安装、远端 API 刷新或 Git 历史改写。完整源码依据见源码证据审计,关键术语定义见项目术语表。

证据状态:除特别标注外,本页基于当前源码已确认。