# Add

> git add 前的敏感信息预检与分流：gitleaks 工具确定性扫描（内置约 200 种密钥格式 + 全局自定义规则）+ AI 语义扫描（财务状况、个人隐私标识、敏感叙述类无固定格式内容）双层把关，预检干净的文件直接加入暂存区，含疑似敏感内容块的文件留在工作区并输出精确到内容块（行号 + 片段）的人工过目清单——需要肉眼过目的内容少而精。MUST USE 当用户输入 /add，或说「add 一下」「预检一下」「扫一下再 add」「把改动加进暂存区」「这些能提交吗」「哪些文件能 add」时，即使用户没明说 add 也要触发；或由 bump skill 改完版本号文件后自动衔接；或发现工作区 / 暂存区有待提交内容时自动发起（常设授权：有待提交内容就直接走本 skill，预检完全干净则自动衔接 commit；主工作区的 main 分支上有改动时自动建 worktree（`worktree-adopt.py`）把改动搬过去、再在 worktree 分支上自动发起，不询问不汇报（2026-11-05 用户立）；**worktree 的功能分支属正常自动触发范围**；被 add-mode 暂停的项目除外，被 commit-mode 暂停的项目仍可 add 但不衔接 commit）。**worktree 场景**：会话 cwd 通常停在 main 主工作区、任务在 AI 建的 worktree 里做——此时检测入口与全部 git 命令都必须带 `git -C <worktree 绝对路径>`（禁止 cd），候选集读 worktree 而不是 cwd。用户触发即授权当次对预检通过的文件执行 git add（全局 AGENTS.md「Git 暂存区禁止 AI 自主增删改」的授权例外）；对暂存区已有内容只增不改、绝不删除或修改。NOT for：gitleaks 自定义词表维护（~/.gitleaks.toml 手工维护）。

- Skill: `xhqing/add` (Agent Skill)
- Install (CLI): `npx get-skill add xhqing/add`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xhqing/add/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: xhqing (https://skillmd.com/u/xhqing)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/xhqing/add

---


# add — git add 前的敏感信息预检分流

## 定位：解决什么问题

在文件进入暂存区**之前**把敏感信息拦住。两层扫描引擎分工：

- **gitleaks（工具层，确定性）**：已知格式的密钥（API key、token、私钥约 200 种）+ 自定义规则（公网 IPv4 字面量、服务商标识词表等，配置在本机 `~/.gitleaks.toml`）。规则命中即拦，不受 AI 注意力影响。
- **AI 语义扫描（语义层）**：无固定格式的敏感内容——财务状况（收入目标、本金、资产、负债、财务紧迫性、投入状态）、个人隐私标识（账户号、证件、真实联系方式、连接串实值）、敏感叙述（身份 + 网络出口 + 绕行手段的故事线、合规拒单报文引用、服务商节点代号）。这类内容任何正则都抓不到，只能靠语义判断。

分流结果：**干净文件自动进暂存区，可疑文件留在工作区等人工过目**——用户肉眼过目的量从「全部改动」缩到「机器拿不准的少数」。预检完全干净（无人工过目、无不建议入库）时更进一步：**自动衔接 commit skill 完成提交推送**（2026-10-01 立），用户只输入一次 `/add` 即走完「预检 → 提交」全链路。

## 授权边界（硬性，不可越过）

1. **用户触发 `/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`）。两个开关完全独立（不同命令、不同状态文件、不同扩展），可以单独或同时开启。
2. **只增不改**：本 skill 绝不触碰暂存区已有内容——不执行 `git restore --staged`、`git rm --cached`、`git reset`、`git mv` 等任何会改动暂存区现有内容的命令。发现暂存区里已有可疑内容时只报告，不动它（留给用户处理）。
3. **预检完全干净时自动衔接 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、不要提交」时也不衔接。
4. 用户口头确认「这几个没问题，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）

```bash
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）整个文件都是新内容、按逻辑段落或配置项分块——逐块判断三类无格式敏感内容：

1. **财务状况**：收入目标与实际收入、本金、资产、负债、存款、财务紧迫程度、职业投入状态等描述；
2. **个人隐私标识**：券商 / 银行账户号、证件号、真实姓名 + 联系方式、真实 IP / SSH 连接串、密钥实值;
3. **敏感叙述**：把「身份 + 网络出口地域 + 绕行手段」串成故事线的叙述、合规拒单报文原文引用、服务商节点代号系列。

判断纪律：**拿不准的块就按可疑处理**——宁可多留一个块给人工看，不可放过一个。这类内容一旦进公开仓库就是永久明文。

### 第 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` 追加一行：

```markdown
<!-- 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. 本次预检**至少 1 个文件**加入了暂存区（含用户确认后加入的）——候选集为空（工作区无待处理改动）、或全部被拦无一入库的场景不衔接（没有任何预检成果可供提交）；
2. 「👁 需人工过目」清单为空（0 个文件）；
3. 「🚫 不建议入库」清单为空（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 之后的又一道工具防线。

