add — git add 前的敏感信息预检分流
定位:解决什么问题
在文件进入暂存区之前把敏感信息拦住。两层扫描引擎分工:
- gitleaks(工具层,确定性):已知格式的密钥(API key、token、私钥约 200 种)+ 自定义规则(公网 IPv4 字面量、服务商标识词表等,配置在本机
~/.gitleaks.toml)。规则命中即拦,不受 AI 注意力影响。 - AI 语义扫描(语义层):无固定格式的敏感内容——财务状况(收入目标、本金、资产、负债、财务紧迫性、投入状态)、个人隐私标识(账户号、证件、真实联系方式、连接串实值)、敏感叙述(身份 + 网络出口 + 绕行手段的故事线、合规拒单报文引用、服务商节点代号)。这类内容任何正则都抓不到,只能靠语义判断。
分流结果:干净文件自动进暂存区,可疑文件留在工作区等人工过目——用户肉眼过目的量从「全部改动」缩到「机器拿不准的少数」。预检完全干净(无人工过目、无不建议入库)时更进一步:自动衔接 commit skill 完成提交推送(2026-10-01 立),用户只输入一次 /add 即走完「预检 → 提交」全链路。
授权边界(硬性,不可越过)
- 用户触发
/add(或当轮明确要求 add)= 授权当次对预检通过的文件执行git add;bump skill 改完版本号文件后的自动衔接同此授权(用户 2026-10-02 立「bump 后自动 /add」规则即预授权);发现工作区 / 暂存区有待提交内容时的自动发起亦同此授权(2026-10-04 用户立的常设授权:「有待提交内容就直接触发 /add 或 /commit 提交,不用问我」)——主工作区的 main 分支上不直接发起 add,而是自动搬运后再发起(2026-11-03 用户立;2026-11-05 用户改为全自动):主工作区停在 main 时不在 main 上 add,也不要停在原地等用户——直接跑python3 ~/.pi/agent/patch/worktree-adopt/worktree-adopt.py --repo <主工作区>,脚本会把改动搬进新 worktree 功能分支(校验一致后才清理主工作区,失败回滚),然后就在那个 worktree 上自动发起本 skill,不询问、不汇报(main-wip-guard.ts在agent_settled时自动兜底提醒)。脚本拒绝执行时(暂存区有内容 / 冲突未解决 / add-mode 或 commit-mode 为手动)就停下按提示处理,不得绕过(工具强制:git-main-guard.ts拦 main 上的git add,逃生门# AI_AUTHORIZED_ADD_MAIN仅限用户当轮授权)。- 「主工作区 main」与「worktree 功能分支」要分清(2026-11-04 用户 clarify):用户的常规工作流是在 main 分支的主工作区开 pi 会话 → 会话里让 AI 建 worktree → 任务全程在 worktree 里完成并提交。所以「不在 main 上直接 add」这条限制,指的是主工作区停在 main 时不直接 add(先自动搬运到 worktree,见上条),不是禁止在 worktree 里触发——worktree 的分支是
feat/xxx/fix/xxx/chore/xxx,属正常自动触发范围,本 skill 在那里正常工作。这是全局 AGENTS.md「Git 暂存区禁止 AI 自主增删改」条款的授权例外(2026-09-22 立;常设授权形式 2026-10-04 增;main 分支限制 2026-11-03 增;worktree 适用范围 2026-11-04 明确)。 - add-mode / commit-mode 两个独立开关的边界(2026-10-31 用户立):
add-mode manual暂停自动 add 的项目 → 不要自行发起本 skill,只有用户当轮明确要求 add / 提交时才走(add-mode-guard.ts硬拦无意图的git add);commit-mode manual暂停自动 commit 的项目 → add 照常自动执行,但预检完全干净后不自动衔接 commit(第 7 步的衔接暂停,只 add 不提交;commit-mode-guard.ts硬拦无意图的git commit)。两个开关完全独立(不同命令、不同状态文件、不同扩展),可以单独或同时开启。
- 「主工作区 main」与「worktree 功能分支」要分清(2026-11-04 用户 clarify):用户的常规工作流是在 main 分支的主工作区开 pi 会话 → 会话里让 AI 建 worktree → 任务全程在 worktree 里完成并提交。所以「不在 main 上直接 add」这条限制,指的是主工作区停在 main 时不直接 add(先自动搬运到 worktree,见上条),不是禁止在 worktree 里触发——worktree 的分支是
- 只增不改:本 skill 绝不触碰暂存区已有内容——不执行
git restore --staged、git rm --cached、git reset、git mv等任何会改动暂存区现有内容的命令。发现暂存区里已有可疑内容时只报告,不动它(留给用户处理)。 - 预检完全干净时自动衔接 commit skill(2026-10-01 用户立,全局 AGENTS.md 授权形式③):本次预检结果满足「至少 1 个文件加入暂存区 + 需人工过目 0 个 + 不建议入库 0 个」时,
/add的授权自动延伸到当次提交推送——直接进入 commit skill 的完整流程(git commit+git push及其全部固有步骤与检测),衔接命令的git commit照常带# AI_AUTHORIZED_COMMIT标记放行。该完整流程含 commit skill 第 10 步的自动发版衔接——满足发版条件时会继续自动进入/release完成发版(2026-10-02 起;2026-10-13 起发版条件收紧:仅自最新 tag 含 fix / feat 类改动时触发,纯文档 / 杂事类不发版——详见 commit skill 第 10 步)。任一条件不满足(有需人工过目的文件 / 有不建议入库的文件 / 本次无文件入库)→ 停在本 skill 报告阶段、不衔接。用户当轮明确说「只 add、不要提交」时也不衔接。 - 用户口头确认「这几个没问题,add 吧」= 当轮授权 add 这几个文件;确认后文件若有新改动,须重新扫描再 add。确认后重新扫描干净并入暂存区 → 同样按第 3 条判定是否自动衔接(全部干净则衔接)。
worktree 场景(2026-11-04 用户立:会话在 main 开、任务在 worktree 做)
用户不会自己去 worktree 里操作——他在 main 分支的主工作区开 pi 会话,worktree 是会话里让 AI 建的,任务也在 AI 手里完成。所以本 skill 必须能在「会话 cwd 停在 main 主工作区、实际操作对象是另一个 worktree」的上下文里正确工作:
- 两个工作区要分清:主工作区(会话 cwd,通常在 main,只负责生成 worktree 与被快进同步)/ 任务工作区(worktree,分支是 feat / fix / chore 类)。
- 先解析目标工作区:
git -C <任务工作区> rev-parse --show-toplevel、git -C <任务工作区> rev-parse --abbrev-ref HEAD。 - 全部 git 命令带
-C <任务工作区绝对路径>,禁止cd:git-main-guard.ts不跟踪cd(只认-C与进程 cwd),cd <worktree> && git add会被误判成「在 main 上 add」而拦下;反过来,漏写-C的git status读的是主工作区、看不到 worktree 的任何改动(worktree 的工作区与 index 与主仓库完全独立,实测互不可见)。 - 检测入口也是 worktree:判「有没有待提交内容」用
git -C <任务工作区> status --porcelain,不许拿会话 cwd 的git status当结论。 - 闸门看任务工作区的分支:worktree 分支非 main → 属自动发起的正常范围;主工作区 main 上的改动才需要新建 worktree 再走。
执行流程
第 0 步:确定候选集
先确定目标工作区(worktree 场景见上节):git -C <目标工作区> rev-parse --show-toplevel 确认是哪个工作区;worktree 场景下本 skill 的每条 git 命令都以该路径 -C 前缀执行。
- 用户指定了文件 / 目录 → 只处理指定的。
- bump skill 自动衔接时 → 以 bump 传入的「改动文件清单」为候选(只处理 bump 改动的版本号载体文件,不扫工作区其它改动)。
- 未指定 → 处理目标工作区的全部未提交改动:
git -C <目标工作区> status --porcelain(会话 cwd 在主工作区时,cwd 的 status 看不到 worktree 的改动)。 .gitignore已忽略的文件不进候选。- 删除类改动(D 状态):直接 add(删除动作本身无敏感内容可泄)。
- 重命名(R)与修改(M)、新增(??/A):进入扫描。
第 1 步:不入库检测(先于敏感扫描,便宜先做)
候选中出现以下任一情况 → 不 add,归入「🚫 不建议入库」并附 .gitignore 建议(与 commit skill 的 cache 检测口径一致,把拦截提前到 add 阶段):
- 名字含 cache 的文件 / 目录(
__pycache__/、.cache/、*.cache、cache/)——例外:项目根.commit-cache.md是 commit skill 的状态文件(本就应入库),不算 cache、不拦; - 二进制文件、本地数据库文件(
.db、.sqlite); - 超大文件(> 5MB,先问用户是否真要入库)。
第 2 步:工具层扫描(gitleaks)
gitleaks dir <候选文件或目录> --config ~/.gitleaks.toml --no-banner -v
- 一次只传一个路径(2026-09-25 实测):
gitleaks dir的用法是gitleaks dir [flags] [path]、只接受单个路径——多个路径拼在一条命令里会让扫描范围失控(实测会扫描远超指定路径的内容,既慢、又可能混入无关命中);候选多时逐个跑。 - 命中输出含 File / Line / RuleID / Finding——命中文件一律进人工清单,附 RuleID 与行号。
- gitleaks 未安装或执行失败 → 降级为 AI 正则扫描(私钥头
-----BEGIN、token 特征串、公网 IPv4 正则等),并在报告开头标注「⚠️ 工具层未生效,本次仅 AI 扫描,强度降级」。
第 3 步:AI 语义扫描(以内容 change block 为判断单位)
先读白名单:项目根 .commit-cache.md 若含「敏感扫描白名单」段(由 commit skill 维护,格式见该文件),先把条目读进来——用户此前明确确认「可公开」的内容块不再进人工过目清单,只在报告里列一行「白名单跳过」(不静默省略)。白名单只覆盖条目描述的范围(哪个文件 + 哪类内容),范围外或拿不准的块照常进清单;gitleaks 命中不适用白名单(真实格式的密钥不该靠白名单绕过);白名单段自身的条目文字不重复报命中(它是确认记录;其中出现凭证类实值仍照常拦截)。
对候选中的文本文件逐个读内容(不是抽样),以内容 change block 为最小判断单位——修改类(M/R)看 diff 的 hunk,新增类(??/A)整个文件都是新内容、按逻辑段落或配置项分块——逐块判断三类无格式敏感内容:
- 财务状况:收入目标与实际收入、本金、资产、负债、存款、财务紧迫程度、职业投入状态等描述;
- 个人隐私标识:券商 / 银行账户号、证件号、真实姓名 + 联系方式、真实 IP / SSH 连接串、密钥实值;
- 敏感叙述:把「身份 + 网络出口地域 + 绕行手段」串成故事线的叙述、合规拒单报文原文引用、服务商节点代号系列。
判断纪律:拿不准的块就按可疑处理——宁可多留一个块给人工看,不可放过一个。这类内容一旦进公开仓库就是永久明文。
第 4 步:过目与否以内容块为单位,文件类型不触发人工(2026-09-22 用户定)
是否需要人工过目,判断依据是具体内容块有没有疑似敏感信息,不是文件 / 文档的类型:
- 新增文档类(
*.md新文件、docs/下新文件)、配置类(*.json/*.yaml/*.toml/*.env*)、记录类(*.log、笔记、导出数据)文件,扫描之后所有内容块都没有敏感信息 → 直接进暂存区,不需要人工过目——「它是新增文档」这个类型本身不构成过目理由。 - 触发人工过目的唯一理由是具体内容块疑似敏感:语义扫描拿不准的块、gitleaks 命中的行。报告理由必须精确到块(行号 + 内容片段),让用户看的是「这一块为什么可疑」,不是「这个文件是什么类型」。
- 这些类型仍是敏感叙述高发区,第 3 步对它们逐块扫描时要格外仔细(宁可慢),但把关强度落在扫描质量上,不再落在类型一刀切的强制人工上——「扫得细」取代「必须过目」。
第 5 步:分流执行
- 干净文件(工具 + 语义双通过,所有内容块均无敏感信息)→ 一条命令批量 add:
git -C <目标工作区> add -- <文件清单> - 验证:
git -C <目标工作区> diff --cached --name-only核对已入该工作区的暂存区(worktree 的 index 与主仓库各自独立,别去主工作区看)。 - 含可疑内容块的文件 → 留在工作区,等用户过目。
第 6 步:输出报告(三段式)
✅ 已加入暂存区(N 个文件)
- 文件1、文件2、…
👁 需人工过目(M 个文件,已留在工作区)
- 文件A —— 理由:gitleaks 命中 [rule-id] 第 X 行:<片段>
- 文件B —— 理由:第 X-Y 行内容块语义疑似财务状况描述:<片段>
🚫 不建议入库(K 个,附 .gitignore 建议)
- 文件D —— cache 目录
♻️ 白名单跳过(X 处,用户已确认可公开;没有则省略此行)
- 文件E 第 X-Y 行 —— 命中白名单条目「<摘要>」
第 6b 步:写扫描审计(2026-11-08 立——让「扫过没有」事后可查)
为什么:以前一次 /add 到底扫了哪些文件、gitleaks 有没有真跑、语义判断结论是什么,事后完全不可考——只能靠 AI 当时的自述。一旦出事(敏感内容进了公开仓库),无法回答「当时为什么没拦住」。所以每次预检结束都在项目根 .commit-cache.md 里留一行审计。
怎么做:在 .commit-cache.md 末尾维护一个审计段(不存在就新建),每次 /add 追加一行:
<!-- commit-skill: scan-audit -->
## 预检审计(每次 /add 追加一行,不改旧行)
- 2026-11-08 23:05 | 候选 3 | gitleaks 3/3 通过(0 命中) | 语义逐块扫描 3/3 通过(0 可疑块) | 入暂存 3 | 人工过目 0 | 不建议入库 0
- 2026-11-08 22:40 | 候选 2 | gitleaks 未安装(降级 AI 正则) | 语义 1 可疑块(config.md:12 疑似账户号) | 入暂存 1 | 人工过目 1 | 不建议入库 0
字段固定:时间(精确到分钟)、候选文件数、工具层结果(通过 / 降级 / 命中条数)、语义层结果(可疑块数 + 位置)、入暂存 / 人工过目 / 不建议入库 的数量。降级(gitleaks 未跑成)必须如实写「降级 AI 正则」,不许只写「通过」。
审计行只追加、不改已有行;文件本身是被跟踪的普通文件,随下次提交一起入库。
报告末尾按场景给指引:自动衔接场景(见第 7 步的三条判定全满足)写「预检完全干净,已自动衔接 commit skill 继续提交推送」;未衔接场景写「过目没问题 → 回复『没问题,add』即可;有问题 → 改完文件再说『重新预检』」。
第 7 步:自动衔接 commit skill(2026-10-01 用户立——预检完全干净时不停下等用户)
判定条件(三条全部满足才衔接):
- 本次预检至少 1 个文件加入了暂存区(含用户确认后加入的)——候选集为空(工作区无待处理改动)、或全部被拦无一入库的场景不衔接(没有任何预检成果可供提交);
- 「👁 需人工过目」清单为空(0 个文件);
- 「🚫 不建议入库」清单为空(0 个文件)。
「♻️ 白名单跳过」不构成阻断:那些内容块是用户此前明确确认过可公开的,视为干净。
满足 → 直接进入 commit skill 的完整流程,不停下等用户输入 /commit——把目标工作区路径一起交过去(worktree 场景下 commit skill 的全部命令同样以 git -C <目标工作区> 执行,见其「worktree 场景」节)——远端 main 对齐检测(0a)→ 分支感知 → 暂存区敏感扫描 → cache 检测 → git commit && git push → 分支 / PR 处理 → 第 9 步标配检测 → 9z 等待对齐 → 第 10 步自动发版链(未就绪时自动走 /bump → /add → /commit)等全部固有步骤一步不省(含其所有终止 / 暂停规则)。git commit 命令照常带 # AI_AUTHORIZED_COMMIT 标记(全局 AGENTS.md 授权的第三种场景)。这是预检干净场景的默认行为,不需要也不应再向用户确认「要不要提交」。
不满足 → 停在报告阶段:输出第 6 步报告与指引,等用户处理需要过目的文件 / 不建议入库的文件,不衔接。
逃生口:用户当轮明确说「只 add、不要提交」→ 只完成 add 部分、输出报告,不衔接。
报告组织:衔接场景的回复 = add 三段式报告(照常输出,指引句按上方自动衔接场景写)+ 紧接 commit skill 的完整汇报(含其第 10 步的自动发版链条结果——版本未就绪时会先自动走 /bump → /add → /commit → /release,以及第 11 步 >> git status 代码块收尾照常执行)。用户在一轮回复里看到「预检 → 提交推送 → 自动发版(未就绪先自动 bump)」完整链路。
降级与异常
- gitleaks 缺失:见第 2 步降级逻辑(同时提示
brew install gitleaks); - 候选为空:直接报告「工作区无待处理改动」;
- 用户确认 add 时文件又被改过:重扫该文件后再 add(防止确认与执行之间的窗口期写入敏感内容)。
与其他 skill 的衔接
- commit skill:
/add管工作区 → 暂存区;/commit管暂存区 → 仓库 → 远程。预检完全干净时本 skill 自动衔接 commit skill(2026-10-01 立,见第 7 步)——用户只输入一次/add即完成「预检 → 提交推送」全链路(满足发版条件时链条继续自动衔接/release完成发版;版本未就绪时先自动走/bump链条——2026-10-02 起);有需人工过目 / 不建议入库的文件时停在 add 阶段、不衔接。commit skill 的暂存区敏感扫描原样保留(最后防线,纵深防御),其暂存区来源现在有两种:经/add预检加入、用户手动 add(自动衔接时提交的是当时暂存区全量内容,commit skill 的扫描对全量生效)。 - bump skill:bump 改完版本号文件后自动衔接本 skill(2026-10-02 立,见第 0 步候选集——候选为 bump 改动的文件);本 skill 预检完全干净时再自动衔接 commit skill,形成
bump → add → commit →(未就绪时自动 bump)→ release自动链(用户主动/bump与 commit skill 检测出「需要 bump」两种入口共用此链)。 - gitleaks pre-commit hook(全局 hooks 目录):commit 时对暂存区再扫一道,是本 skill 之后的又一道工具防线。