Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/zwyin/paoding-skills --skill paoding-github-safe-publishAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
GitHub Safe Publish
将本地 Git 项目安全地发布到 GitHub 公开仓库。
参数
/paoding-github-safe-publish # 核心流程(脱敏+发布)
/paoding-github-safe-publish --seo # 核心 + SEO 优化
/paoding-github-safe-publish --ci # 核心 + CI 生成
/paoding-github-safe-publish --seo --ci # 全部
/paoding-github-safe-publish --scan # 只做脱敏扫描,输出报告,不修复不发布
/paoding-github-safe-publish --dry-run # 模拟完整流程:扫描+模拟修复建议,但不做任何实际修改参数互斥与冲突处理:
--scan和--dry-run不能与--seo/--ci组合(SEO 和 CI 只对已推送的仓库有意义,扫描模式不推送)--scan和--dry-run不能同时使用--seo和--ci可以同时使用(完整功能模式)- 无效组合直接报错并退出
- `--scan` 与 `--dry-run` 的区别:
--scan:只告诉你有什么问题。输出扫描报告(命中规则、文件位置、严重等级),不提修复方案。--dry-run:告诉你有什么问题 + 打算怎么修。在扫描报告基础上,为每个发现项展示推荐修复方案(如"将此密钥替换为REPLACE_ME_AWS"),但不执行任何修改。
流程控制矩阵:
| 步骤 | 完整流程 | --scan | --dry-run |
|---|---|---|---|
| Step 1: 前置检查+参数确认 | 执行 | 执行 | 执行 |
| Step 2: 创建备份分支 | 执行 | 跳过 | 跳过 |
| Step 3: 脱敏扫描 | 执行 | 执行 | 执行 |
| Step 4: 自动修复+用户确认 | 执行 | 跳过 | 输出修复建议但不执行 |
| Step 5: 仓库决策+推送 | (迭代 2) | 跳过 | 跳过 |
| Step 6: 验证+报告 | (迭代 2) | 仅扫描报告 | 仅扫描报告+修复建议 |
前提
- 当前目录是 Git 仓库,至少有一个 commit
ghCLI 已安装并登录(可选,支持手动推送)- 用户确认项目可以公开(已过脱敏)
版本检查
在执行任何步骤之前,检查是否有新版本可用。
bash ../../../scripts/check_update.sh如果脚本输出了升级提醒,告知用户:"检测到新版本,你可以继续使用当前版本,或运行 claude plugin update paoding-skills@paoding-skills 升级。" 版本检查有 24 小时缓存,不会每次调用都查网络。检查失败时静默跳过,不阻塞主流程。
Step 1: 前置检查 + 参数确认(集中交互 #1)
所有前置检查和参数决策集中在一次交互中完成。任何一项阻断条件不满足则停在当前步骤。
1.1 自动检查(无交互)
按顺序执行以下检查,仅记录结果,不做交互:
检查项:
1. 当前目录是 git 仓库?
命令:git rev-parse --is-inside-work-tree
├── 成功 → is_git_repo = true,继续
└── 失败 → is_git_repo = false,标记"需要在 1.2 中询问初始化"
2. git 仓库至少有 1 个 commit?
命令:git rev-parse HEAD
├── 成功 → has_commit = true,继续
└── 失败 → 阻断:输出"仓库没有任何 commit,需要至少一次 commit 才能创建备份分支和回滚",停止流程
3. gh CLI 是否可用?
命令:gh auth status 2>&1
├── 成功 → gh_available = true,提取用户名(gh api user --jq .login)
└── 失败 → gh_available = false,记录原因(未安装 / 未登录)
注意:gh CLI 可用不是必须条件,用户可以选择手动推送自动检查结果汇总格式:
前置检查结果:
Git 仓库:✓
至少 1 个 commit:✓(42 commits on master)
gh CLI:✓(已登录 as zwyin)
或
gh CLI:✗(未安装。可选:手动推送模式)参数冲突校验(在进入任何交互前先执行,冲突直接报错退出):
无效组合检测:
--scan + --seo → 报错:"--scan 不能与 --seo 组合。SEO 优化只对已推送的仓库有意义,扫描模式不推送。请使用完整流程模式。"
--scan + --ci → 报错:"--scan 不能与 --ci 组合。CI 生成只对已推送的仓库有意义,扫描模式不推送。请使用完整流程模式。"
--dry-run + --seo → 报错:"--dry-run 不能与 --seo 组合。SEO 优化需要实际推送,模拟模式不做推送。请使用完整流程模式。"
--dry-run + --ci → 报错:"--dry-run 不能与 --ci 组合。CI 生成需要实际推送,模拟模式不做推送。请使用完整流程模式。"
--scan + --dry-run → 报错:"--scan 和 --dry-run 不能同时使用。--scan 只输出扫描报告;--dry-run 在报告基础上还展示推荐修复方案。"1.2 集中交互确认
将以下决策合并为一次或连续的 AskUserQuestion 调用。问题数量根据上下文动态调整(最多 3 个问题)。
问题 1:工作模式(必问)
AskUserQuestion: 请确认工作模式
A) 完整流程:脱敏扫描 → 自动修复 → 发布到 GitHub
(适合准备公开发布的项目)
B) 仅扫描:只做脱敏检查,输出扫描报告,不修复不发布(--scan)
(适合先了解项目中哪些内容需要处理)
C) 模拟运行:扫描出报告,展示推荐修复方案,但不做任何实际修改(--dry-run)
(适合预览完整流程,确认修复策略)如果用户在问题 1 选择了完整流程(选项 A),且调用时带了 --seo 或 --ci 参数,追加确认:
AskUserQuestion: 附加模块确认
检测到参数:--seo --ci
A) 完整流程 + SEO 优化(README 优化、topics、badges)
B) 完整流程 + CI 生成(自动检测并生成 .github/workflows/test.yml)
C) 完整流程 + SEO + CI(全部功能)
D) 仅完整流程,不加附加模块问题 2:推送方式(仅完整流程模式下显示)
情况 A — gh CLI 可用:
AskUserQuestion: 推送方式
A) 使用 gh CLI 自动创建仓库并推送(推荐)
自动完成:创建仓库 → 添加 remote → git push
B) 我自己手动推送,只帮我做好脱敏和本地准备
完成脱敏后输出手动推送指引,不执行任何推送操作情况 B — gh CLI 不可用:
AskUserQuestion: 推送方式(gh CLI 不可用:未安装/未登录)
A) 我自己手动推送
完成脱敏后输出手动推送指引
B) 我先去安装/登录 gh CLI,等会再来
中止当前流程,提示安装命令:
macOS: brew install gh && gh auth login
Linux: https://github.com/cli/cli/blob/trunk/docs/install_linux.md问题 3:非 git 目录的处理(仅在 isgitrepo = false 时显示)
AskUserQuestion: 当前目录不是 Git 仓库
A) 帮我初始化后继续
执行:git init → 生成标准 .gitignore(覆盖 Python/Node/macOS/IDE 常见忽略项)→ git add . → git commit -m "init: initial commit"
B) 我先自己备份和初始化,回来再用
中止当前流程,提示用户准备好后重新调用标准 .gitignore 模板(选项 A 时生成):
# Python
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
.venv/
venv/
*.egg
# Node
node_modules/
# macOS
.DS_Store
.AppleDouble
.LSOverride
# IDE
.vscode/
.idea/
*.swp
*.swo
# 环境变量和密钥
.env
.env.*
!.env.example
*.pem
*.key
# 数据库
*.db
*.sqlite
*.sqlite31.3 交互结果汇总
所有问题确认完成后,输出配置摘要:
━━━ 配置确认 ━━━
工作模式:完整流程
推送方式:gh CLI 自动推送(zwyin)
附加模块:SEO + CI
───────────────
目标仓库:待扫描后确认(Step 5)
备份分支:pre-publish-backup(Step 2 创建)
报告文件:safe-publish-report-YYYYMMDD-HHMM.md(项目根目录)
━━━━━━━━━━━━━━━
⚠️ 报告文件包含扫描到的敏感信息摘要,请勿提交到公开仓库。
建议扫描完成后删除,或确认 .gitignore 已包含 safe-publish-report-*.md。
确认以上配置,开始执行?用户确认后进入 Step 2。用户否定则回到 1.2 重新选择。
Step 2: 创建备份分支
在任何修改之前创建回滚点。仅在完整流程模式下执行(--scan 和 --dry-run 跳过此步骤)。
跳过原因:--scan 和 --dry-run 设计为纯只读操作,不修改任何源文件或分支,子 agent 不被授予写入工具权限,因此无需备份。唯一例外:Step 6.3 的报告文件写入(输出到项目根目录)和 .gitignore 追加,不涉及源代码变更。
2.1 创建流程
# 删除已有的同名备份分支(重新运行会覆盖上次备份,这是预期行为)
git branch -D pre-publish-backup 2>/dev/null || true
# 检查工作区是否有未提交内容
if git diff --quiet HEAD && git diff --quiet --cached; then
# 工作区干净,直接在 HEAD 上创建备份分支
git branch pre-publish-backup HEAD
else
# 有未提交内容,先 stash 再创建分支
git stash push -m "pre-publish-stash-$(date +%Y%m%d%H%M%S)" --include-untracked
git branch pre-publish-backup HEAD
# 恢复工作区
git stash pop || {
echo "WARNING: stash pop 产生冲突,无法自动恢复工作区。"
echo "冲突文件已保留在 stash 中(git stash list 查看)。"
echo ""
echo "备份分支 pre-publish-backup 已基于 HEAD 创建(不含未提交内容)。"
echo "请手动处理冲突:"
echo " 1. 解决冲突文件后 git add . && git stash drop"
echo " 2. 或放弃未提交改动:git checkout -- . && git stash drop"
echo ""
echo "处理完毕后继续后续步骤。"
# 不自动丢弃 stash,等待用户手动处理
return 1
}
fi2.2 验证
# 确认备份分支存在且指向正确的 commit
git rev-parse --verify pre-publish-backup
echo "备份分支 pre-publish-backup 指向: $(git log -1 --oneline pre-publish-backup)"2.3 规则
- 分支名固定:
pre-publish-backup,不可自定义 - 删除后重建:如果该分支已存在(上次运行的残留),先删除再创建
- 不推送:备份分支仅存在于本地,不推送到任何远程仓库
- 覆盖提醒:重新运行会覆盖上次的备份点。备份的是"最近一次发布前的状态",非累积
- 回滚方式:
git reset --hard pre-publish-backup(硬回滚到备份点的完整状态) - 清理时机:推送完成并验证后(Step 6),告知用户可以安全删除该分支
2.4 输出
备份分支已创建:pre-publish-backup → <commit-hash> <commit-message>
如需回滚:git reset --hard pre-publish-backupStep 3: 脱敏扫描(两层架构)
采用两层架构:第 1 层确定性规则扫描覆盖已知模式,第 2 层 AI 语义扫描补充规则无法覆盖的语义泄露。 两层独立运行,结果合并后输出统一报告。
第 1 层:确定性规则扫描
扫描范围:
# 获取所有 git 跟踪文件
git ls-files
# 排除规则:
# 1. 二进制文件(图片/视频/编译输出/字体)— 无法以 UTF-8 解码的文件跳过
# 2. .git 目录内部
# 3. 子模块(由用户自行处理)
# 4. 单文件 > 10MB 跳过(避免性能问题)
# 可选警告:检查 .gitignore 中列出但仍存在于工作区的敏感文件
git ls-files --others --ignored --exclude-standard | grep -iE '\.env$|\.pem$|\.key$|\.db$|credentials'六个扫描维度:
| 维度 | 代号 | 说明 | 规则数 |
|---|---|---|---|
| A. 密钥/凭证 | KEY | API Key、Token、Secret 等确定性模式 + 熵值辅助 | 100 |
| A2. 数据库连接字符串 | DB | 含密码的数据库连接字符串 | 5 |
| B. PII(个人身份信息) | PII | 邮箱、手机号、身份证号、银行卡号等 | 8 |
| C. 内部基础设施 | INF | 内网 IP、内部域名、本地文件路径、VPN 配置 | 6 |
| D. 文件黑名单 | FILE | .env、.pem、.key、.db 等不应公开的文件类型 | 12 |
| E. Git 历史 | GIT | 历史中的敏感文件残留、大文件、author email 泄露 | 4 |
完整正则定义见 docs/scanning-rules.md。以下为各维度概要。A. 密钥/凭证(正则 + 熵值)
覆盖 100 条规则,主要服务商包括:
- 云服务:AWS(access token / secret key / Bedrock)、Azure(AD client secret)、GCP(API key / Service Account)、DigitalOcean、Cloudflare(API / Global / Origin CA)
- 代码平台:GitHub(PAT / App Token / Fine-grained PAT / OAuth / Refresh Token)、GitLab(PAT / Deploy / Runner / CI Job / Feed / K8s Agent)、Bitbucket(Client ID / Secret)
- AI 服务:OpenAI、Anthropic、HuggingFace、Cohere、Perplexity、Google Gemini、DeepSeek、xAI、Replicate
- 通信:Slack(Bot / User / Webhook)、Twilio、SendGrid、Telegram、Discord、Sendinblue、Mattermost、MS Teams
- 支付:Stripe、Square、Plaid、Flutterwave、Shopify(Access / Shared Secret)
- 运维:Datadog、Sentry(Access / DSN)、New Relic、Grafana、Snyk、Databricks、Dynatrace、Pulumi、Artifactory、HashiCorp(Terraform / Vault)
- 部署平台:Vercel、Netlify、Supabase、Fly.io、Deno、PlanetScale
- 其他:npm、PyPI、RubyGems、Heroku、Postman、Notion、Atlassian(Jira/Confluence)、Linear、Mailchimp、Okta、Mailgun、Algolia、Facebook、Dropbox、Confluent、Fastly、LaunchDarkly、Codecov、Doppler、ClickHouse、Contentful、Scaleway、ngrok
熵值检测(Shannon entropy):阈值 4.5,仅在已知密钥关键字附近触发,不全局扫描所有字符串以避免 Base64/哈希值误报。generic-api-key 规则匹配后,熵值 >= 4.5 升级为 CRITICAL,< 4.5 降为 WARNING。
A2. 数据库连接字符串(正则)
覆盖 5 条规则:PostgreSQL、MySQL、MongoDB、Redis、JDBC 通用格式。检测连接字符串中嵌入的密码。本地开发连接(localhost + 无密码)降为 WARNING。
B. PII(正则)
- 邮箱:非 GitHub noreply / placeholder 的个人邮箱
- 中国大陆手机号:
1[3-9]\d{9} - 身份证号:18 位格式(CRITICAL)
- 银行卡号:中国银行卡号前缀(CRITICAL)
- 美国社保号 SSN(CRITICAL)
- 信用卡号:含 Luhn 校验(CRITICAL)
- IPv4 地址:公网 IP 检测(内网 IP 由 C 维度的 internal-ip-address 覆盖)(WARNING)
- 硬编码密码:password/passwd/pwd 赋值语句(WARNING)
C. 内部基础设施(正则)
- 内网 IP:
10.x.x.x、172.16-31.x.x、192.168.x.x - 内部域名:
.local、.internal、.lan、.corp、.intra、.office、.home、.nas后缀 - 硬编码本地路径:
/Users/xxx/、C:\Users\xxx\、/home/xxx/ - 内部服务 URL:含 nas/vpn/internal 关键字的 URL
- VPN/Proxy 配置
D. 文件黑名单
按文件路径匹配,包含:
- 凭证文件:
.env、.pem、.key、.p12、.pfx、.jks、credentials.*、.netrc、.pypirc - 数据文件:
.sql、.db、.sqlite、.dump - IDE 配置:
.idea/、.vscode/settings.json - 系统文件:
.DS_Store、Thumbs.db - 日志/缓存:
.log、__pycache__/、node_modules/ - Terraform 状态:
.tfstate
同时检查 .gitignore 充分性:对黑名单中的文件类型检查是否有对应忽略规则。
E. Git 历史扫描
- Author email 泄露:
git log --all --format='%ae' | sort -u,排除 GitHub noreply 地址 - 历史中添加过的敏感文件:
git log --all --diff-filter=A --summary搜索.env、.pem、.key等 - 已删除的敏感文件残留:
git log --all --diff-filter=D --summary,内容仍可通过 git 历史恢复 - 大文件:
git rev-list --objects --all | git cat-file --batch-check筛选 > 1MB 的 blob
规则扫描执行命令:
# 获取扫描文件列表(排除常见二进制扩展名)
files=$(git ls-files | grep -v -E '\.(png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|mp4|mp3|zip|tar|gz|exe|dll|so|dylib|pdf)$')
# 对每个文件逐行应用规则扫描(伪代码,实际由 agent 读取文件内容后用正则匹配)
for file in $files; do
# 检查文件大小
size=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)
if [ "$size" -gt 10485760 ]; then
echo "SKIP: $file (> 10MB)"
continue
fi
# 应用维度 A-D 的规则扫描
done
# Git 历史扫描(维度 E)
git log --all --format='%ae' | sort -u
git log --all --diff-filter=A --summary
git log --all --diff-filter=D --summary输出格式:
结构化报告,每项包含:
[维度] 文件:行号 | 严重级别 | 规则名 | 匹配内容(脱敏显示)
示例:
[KEY] src/config.py:42 | CRITICAL | github-pat | ghp_****************************
[PII] README.md:15 | WARNING | email-address | zhang***@company.com
[INF] deploy.sh:8 | WARNING | internal-ip-address | 192.168.1.***
[FILE] .env | CRITICAL | env-files | .env 文件存在
[GIT] (历史) | WARNING | author-email-leak | zhangwei@internal.corp第 2 层:AI 语义扫描(1-2 轮,独立子 agent 执行)
通过独立子 agent 执行(不共享主对话上下文,隔离敏感信息),补充规则无法覆盖的语义泄露。
扫描内容(规则扫描无法覆盖的语义维度):
- 业务数据泄露:内部项目代号、真实用户数据、订单号、财务数据
- 可溯源叙事:可通过搜索引擎定位到个人/组织的描述(如"在 XX 公司的 YY 项目中")
- 间接推断:文件路径推断内部组织结构、时间戳推断工作节奏、注释推断技术栈
- 规则扫描误报排除:对第 1 层 WARNING 项进行二次判断,降低误报率
执行方式:
使用 Agent 工具启动独立子 agent,每个子 agent 接收自包含的扫描 prompt(不依赖主对话上下文)。子 agent 仅被授予 Read、Grep、Glob、Bash(只读命令)权限,不可修改任何文件。
子 agent Prompt 模板:
你是一个代码安全审计 agent。你的任务是扫描一个即将公开的 Git 项目,
找出可能泄露敏感信息的语义内容。这是纯只读任务,不要修改任何文件。
=== 项目路径 ===
{PROJECT_PATH}
=== 你的任务 ===
1. 用 Glob 和 Read 工具浏览项目文件结构
2. 重点阅读以下文件类型:
- README、CHANGELOG、CONTRIBUTING 等文档
- 配置文件(YAML/TOML/JSON/INI)
- 注释密集的源代码文件
- Git commit message(运行 git log --oneline -50)
3. 识别以下类别的语义泄露:
A. 内部项目代号或内部系统名称
B. 真实用户数据(姓名、订单号、交易记录)
C. 可溯源叙事(能通过搜索引擎定位到具体个人/组织的描述)
D. 文件路径中暴露的内部组织结构
E. 注释中的内部链接、内部同事姓名
F. 时间模式暴露的工作节奏信息
=== 输出格式 ===
每项发现一行,格式:
[FINDING] 类别 | 文件:行号 | 严重级别(CRITICAL/WARNING) | 内容摘要 | 推荐处理方式
=== 已知排除项(第 1 层已覆盖,你不需要重复检查)===
- API Key / Token / Secret 的格式化模式
- 邮箱 / 手机号 / 身份证号等 PII 的标准格式
- .env / .pem 等文件黑名单
- 内网 IP / 内部域名等基础设施模式
=== 注意 ===
- 只报告你确信有泄露风险的内容,宁可漏报不要误报
- 如果某个内容你觉得可能是敏感的但不确定,标为 WARNING
- 如果没有发现任何问题,输出:[CLEAN] 未发现语义层面的敏感信息泄露收敛判定:
- 第 1 轮扫描后,将发现项与第 1 层结果合并去重
- 如果第 1 轮发现新问题,启动第 2 轮(使用不同的子 agent 实例,聚焦第 1 轮发现项的关联区域)
- 第 2 轮无新发现,或已完成 2 轮,停止扫描
- 最多 2 轮 AI 扫描
v1 → v2 架构变更说明:
v1 采用 5 轮纯 AI 自由扫描,存在两个问题:(1) 每轮 AI 扫描结果不可复现;(2) 规则可覆盖的模式(如 API Key 格式)不应由 AI 判断。v2 改为"规则确定性扫描 + 1-2 轮 AI 语义补充"两层架构,规则层可复现且覆盖率高(100 条密钥规则 + 5 条数据库连接字符串 + 8 条 PII 规则),AI 只负责规则无法覆盖的语义部分,因此收敛更快,最多 2 轮即可。
两层结果合并:
扫描完成。合并第 1 层 + 第 2 层结果:
第 1 层(规则扫描):
CRITICAL: N 项
WARNING: M 项
第 2 层(AI 语义扫描):
新增 CRITICAL: X 项
新增 WARNING: Y 项
误报排除(WARNING → SAFE): Z 项
合并后总计:
CRITICAL: N+X 项
WARNING: M+Y-Z 项
详细报告见上方输出。
准备进入 Step 4 处理。Step 4: 自动修复 + 用户确认
根据 Step 3 扫描结果分类处理。--scan 模式跳过此步骤;--dry-run 模式输出修复建议但不执行任何修改。
结果分类
| 级别 | 含义 | 默认动作 |
|---|---|---|
| CRITICAL | 真实密钥、凭证、敏感 PII(身份证、银行卡) | 必须处理,阻塞推送 |
| WARNING | 可能敏感但不确定(内部 IP、个人邮箱、硬编码路径) | 列出给用户判断 |
| SAFE | 示例占位符(your_xxx、REPLACE_ME)、README 通用描述、example.com | 无需处理 |
SAFE 项自动跳过,不进入修复流程。
CRITICAL 修复选项
对每个 CRITICAL 项,使用 AskUserQuestion 逐项询问用户:
AskUserQuestion: 发现 CRITICAL 敏感内容
[KEY] src/config.py:42 | github-pat | ghp_****************************
修复方式:
A) 自动替换 — 将敏感内容替换为泛化占位符
B) 手动修复 — 你自己在编辑器里改,改完后我会重新扫描验证
C) 删除文件 — 从 git 中移除整个文件(git rm)
D) 确认安全 — 确认该内容实际不敏感(需输入理由)用户选择处理方式后,执行对应操作。
自动替换规则
用户选择 A(自动替换)时,按以下规则替换:
| 原始内容类型 | 替换为 | 示例 |
|---|---|---|
| 真实密钥/Token | REPLACE_ME_<类型> | REPLACE_ME_API_KEY、REPLACE_ME_GITHUB_TOKEN |
| 个人邮箱 | user@example.com | 或用户指定的 GitHub 公开邮箱 |
| 内部 IP | 192.168.x.x | 保持格式一致性 |
| 内部域名 | internal.example.com | — |
| 真实姓名 | FIRST_NAME / LAST_NAME | — |
| 手机号 | 1XX-XXXX-XXXX | — |
| 可溯源叙事 | 泛化为通用描述 | "在 XX 公司的 YY 项目中" → "在某个项目中" |
| 本地文件路径 | 泛化路径 | /Users/zhangsan/project → /path/to/project |
替换后自动使用 Edit 工具修改文件内容。
WARNING 修复选项
对 WARNING 项,批量展示后由用户统一决策:
AskUserQuestion: 发现 WARNING 级别内容
以下 N 项内容可能敏感,请选择处理方式:
1. [INF] deploy.sh:8 | internal-ip-address | 192.168.1.100
2. [PII] README.md:15 | email-address | dev@company.com
3. ...
对每一项:
A) 按自动替换规则处理(同 CRITICAL 选项 A 的替换规则)
B) 接受风险 — 标记为已知,继续(不修改)Git 历史中的敏感信息(特殊处理)
Git 历史中的敏感信息无法通过简单的文件编辑修复,需要特殊处理。
Step 1:评估影响范围
# 查找包含敏感字符串的所有 commit
git log --all -S "敏感字符串" --oneline
# 查看特定文件的历史变更
git log --all --follow -- "path/to/sensitive/file"
# 统计影响的 commit 数量
git log --all -S "敏感字符串" --oneline | wc -lStep 2:处理方式选择
AskUserQuestion: Git 历史中发现敏感信息
以下内容存在于 Git 历史中(即使当前文件已删除/修改):
[GIT] commit abc1234 | .env 文件曾被提交后删除
[GIT] commit def5678 | config.yml 包含真实 API key
影响范围:3 个 commit 包含敏感内容
处理方式:
A) 重写历史 — 使用 git filter-repo 清除敏感内容(推荐,仅限未推送到公共远程的仓库)
执行前已有 Step 2 的 pre-publish-backup 分支保护原始历史
B) 新建干净仓库 — 将当前工作区复制到新目录后 git init,保留原仓库完整不动
注意:不删除原 .git 目录,而是 cp -r 工作区文件到新目录再 git init
C) 接受风险 — 历史中的敏感内容将通过 git 历史公开Option A 详细步骤(重写历史):
# 确认 git-filter-repo 可用
pip install git-filter-repo 2>/dev/null || pip3 install git-filter-repo
# 对每个敏感字符串执行替换
git filter-repo --invert-paths --path .env --force
git filter-repo --replace-text <(echo 'REAL_API_KEY==>REPLACE_ME_API_KEY') --force
# 重写后重新检查
git log --all -S "敏感字符串" --oneline # 应该无结果Option B 详细步骤(新建干净仓库):
# 1. 创建临时目录
CLEAN_DIR=$(mktemp -d)/$(basename "$(pwd)")
mkdir -p "$CLEAN_DIR"
# 2. 复制工作区文件(排除 .git)
# 注意:不删除原 .git 目录,原仓库保持不动
rsync -av --exclude='.git' ./ "$CLEAN_DIR/"
# 3. 在新目录初始化
cd "$CLEAN_DIR"
git init
git add -A
git commit -m "Initial commit: clean history for public publish"
echo "原仓库未受影响,仍在:$(pwd)"
echo "新干净仓库位于:$CLEAN_DIR"Option B 的安全说明:
- 明确:不删除原
.git目录,原仓库保持完整 - Step 2 创建的
pre-publish-backup分支保护了原始历史,即使选择 Option A 也可以通过该分支恢复 - 新建干净仓库后,后续的 Step 5 推送操作在干净仓库目录中执行
修复后验证循环(Fix-Verify Loop)
每轮修复完成后,重新运行验证:
# 重新运行第 1 层规则扫描(完整扫描,非增量)
# 对所有 CRITICAL 和 WARNING 修复过的文件重新检查
# 同时运行 1 轮 AI 抽检(仅扫描修复过的文件及其关联文件),确认修复没有引入新问题循环规则:
- 修复后重新扫描确认
- 如果仍有未通过的项,进入下一轮修复
- 最多 3 次(3 轮)修复-验证循环
- 超过 3 次仍有失败项 → 阻塞推送,输出失败项清单供用户手动处理
修复验证第 N/3 轮:
已修复:X 项
仍有问题:Y 项
- [KEY] src/config.py:42 | CRITICAL | github-pat(第 2 次出现)
[Y = 0] → 全部通过,进入 Step 5
[Y > 0 且 N < 3] → 继续下一轮修复
[N = 3 且 Y > 0] → 阻塞推送
阻塞输出:
以下 Y 项经 3 轮修复仍存在,请手动处理后重新运行:
1. [KEY] src/config.py:42 | github-pat
2. ...--dry-run 模式行为
--dry-run 模式下,Step 4 不执行任何实际修改,仅输出修复建议:
[DRY-RUN] 以下为建议修复方案,未执行任何修改:
CRITICAL 项(N 项,必须处理):
1. [KEY] src/config.py:42 | github-pat
建议操作:自动替换为 REPLACE_ME_GITHUB_TOKEN
2. [FILE] .env | env-files
建议操作:删除文件并添加到 .gitignore
WARNING 项(M 项,建议处理):
1. [INF] deploy.sh:8 | internal-ip-address | 192.168.1.100
建议操作:替换为 192.168.x.x
2. ...
Git 历史问题(K 项):
1. [GIT] commit abc1234 | .env 曾被提交
建议操作:git filter-repo --invert-paths --path .env
要执行这些修复,请使用完整流程模式(不带 --dry-run)。Step 5: 仓库决策确认 + 创建推送(集中交互 #2)
仅完整流程模式执行。--scan/--dry-run跳过此步骤。
脱敏通过后,在推送之前集中确认仓库属性。这些决策不可逆或难以逆转。
5.1 集中交互确认
问题 1:仓库可见性(不可逆——公开后搜索引擎会索引)
AskUserQuestion: 仓库可见性
A) Public — 任何人可见,搜索引擎可索引
⚠️ 推送后无法完全撤回,搜索引擎会保留快照
B) Private — 仅自己和协作者可见问题 2:仓库名称(重命名会破坏所有链接)
AskUserQuestion: 仓库名称
A) project-name(当前目录名)
推送后重命名会导致 clone URL、badge、引用全部失效
B) 自定义名称:________问题 3:仓库描述(可选)
AskUserQuestion: 仓库描述(显示在 GitHub About 区域)
A) 使用 README 第一段自动提取
B) 自定义描述:________
C) 暂不设置交互结果汇总:
即将发布到 GitHub:
仓库:USERNAME/REPO_NAME
可见性:Public / Private
描述:...
分支:CURRENT_BRANCH
Commits:N
脱敏状态:passed(N items reviewed, N auto-fixed)
备份分支:pre-publish-backup(如需回滚:git reset --hard pre-publish-backup)
确认推送?用户确认后,执行推送。
5.2 占位链接替换
推送前扫描代码中的占位用户名/链接,替换为实际 GitHub 用户名:
# 获取当前 GitHub 用户名
gh api user --jq '.login'扫描以下模式并替换(仅限 README.md 和 Markdown 文件):
yourname/→USERNAME/your-username/→USERNAME/YOUR_GITHUB_USERNAME/→USERNAME/https://github.com/yourname/→https://github.com/USERNAME/
替换后如有改动,提交:
git add -A
git commit -m "chore: replace placeholder URLs with actual GitHub username"5.3 执行推送
A. 自动推送(gh CLI 可用且用户选择自动)
gh repo create创建仓库(使用确认的名称和可见性)- 如果
gh repo create返回名称冲突(HTTP 422):
AskUserQuestion: 仓库 USERNAME/REPO_NAME 已存在
A) 推送到现有仓库(仅添加 remote)
B) 换一个名称
C) 取消- 添加 remote(命名
github,保留origin):git remote add github URL 2>/dev/null || git remote set-url github URL git push github CURRENT_BRANCH- 设置默认 remote:
git config branch.CURRENT_BRANCH.remote github
B. 手动推送
- 已完成占位链接替换和提交
- 输出推送指引:
脱敏检查已通过。接下来请手动操作:
1. 在 GitHub 上创建仓库:REPO_NAME(Public/Private)
https://github.com/new
2. 添加 remote:
git remote add github https://github.com/USERNAME/REPO_NAME.git
3. 推送:
git push github CURRENT_BRANCH
完成后建议:
git config branch.CURRENT_BRANCH.remote githubStep 6: 验证 + 输出报告
完整流程模式:验证仓库 + 完整报告。--scan:仅扫描报告。--dry-run:扫描报告 + 修复建议。
6.1 仓库验证(仅自动推送模式)
# 验证仓库可访问
gh repo view --json url,visibility,defaultBranchRef
# 验证远程分支与本地一致
git fetch github
git log github/CURRENT_BRANCH --oneline -1如验证失败,输出排查指引,不自动重试。
6.2 输出报告
完整流程报告:
=== GitHub Safe Publish Report ===
Published to GitHub:
URL: https://github.com/USERNAME/REPO
Branch: BRANCH
Commits: N
Visibility: public / private
Description: ...
Desensitization:
Status: passed
Items reviewed: N
Auto-fixed: N
Manual confirmed: N
AI semantic scan rounds: 1-2
Backup:
Branch: pre-publish-backup
Rollback: git reset --hard pre-publish-backup
Cleanup: git branch -d pre-publish-backup (when ready)
Next steps:
- Verify repository at the URL above
- Set up branch protection (Settings → Branches)
- Add collaborators if needed
- Consider enabling GitHub Actions for CI
- Delete pre-publish-backup branch when confident--scan 报告:
=== Scan Report ===
Repository: LOCAL_PATH
Branch: BRANCH
Files scanned: N
Layer 1 (Rule-based):
CRITICAL: N items
WARNING: N items
Layer 2 (AI Semantic):
Additional findings: N items
Detailed findings:
[CRITICAL] file:line | rule-name | ghp...xyz (前后各显示3字符,中间用...替代)
[WARNING] file:line | rule-name | ghp...xyz (前后各显示3字符,中间用...替代)
...
Recommendation: Fix CRITICAL items before publishing. Run without --scan to auto-fix.--dry-run 报告:
在 --scan 报告基础上,追加每个发现项的建议修复方案:
Suggested fixes:
[CRITICAL] file:line | rule-name
→ Auto-replace with REPLACE_ME
→ Or remove the file from tracking
[WARNING] file:line | rule-name
→ Confirm as safe (no action needed)
→ Or replace with placeholder6.3 报告文件
将上述报告内容写入文件。每次运行生成独立文件,不覆盖历史报告。
文件路径: safe-publish-report-YYYYMMDD-HHMM.md(项目根目录,与 .git 同级)
多轮扫描不覆盖:文件名包含精确到分钟的时间戳,重复运行生成新文件。同一分钟内再次运行会覆盖上次报告(此时第二次结果更完整,属预期行为)。
报告内容按模式区分:
- 完整流程:扫描结果 + 修复记录(每项:原内容 → 替换内容)+ 仓库 URL + 备份回滚指引
--scan:扫描结果 + 发现列表(CRITICAL / WARNING 分类,含文件路径和行号)--dry-run:扫描结果 + 发现列表 + 每项推荐修复方案
自动更新 .gitignore:
if ! grep -q "safe-publish-report-" .gitignore 2>/dev/null; then
echo "safe-publish-report-*.md" >> .gitignore
fi仅在 .gitignore 不包含该模式时追加,避免重复。
写入失败降级:如果报告文件写入失败(磁盘满/权限不足),输出警告但不阻塞流程,将报告内容直接打印到终端作为降级方案。
📄 报告已保存至 safe-publish-report-20260526-1430.md
⚠️ 此文件包含敏感信息摘要,请勿提交到公开仓库。可选模块
--seo 模块
推送成功后执行。不可与--scan/--dry-run组合。
SEO-1: Description 优化
通过 gh repo edit --description 设置仓库描述:
- 120 字符以内,主关键词开头
- 包含核心技术关键词(如 Python、Claude Code skill、secret scanning)
- 从 README 第一段提取,人工确认后应用
AskUserQuestion: 仓库描述
A) {自动提取的 description}
B) 自定义:________SEO-2: Topics 标签
通过 gh repo edit --add-topic 添加标签:
- 6-20 个标签
- 三类均衡分布:用途(what)/ 技术栈(how)/ 领域(domain)
- 不用项目主语言做标签(GitHub 自动检测语言)
- 推荐标签:根据项目内容自动推断,人工确认后应用
SEO-3: Badges(shields.io 静态 badge)
在 README.md 顶部添加静态 badge(不依赖 CI):


Badge 规则:
- License badge:从 LICENSE 文件检测
- Version badge:从 SKILL.md frontmatter 读取
- Platform badge:固定为 Claude Code
- Tests badge:如果 tests/ 存在则添加
- 手动 URL,不依赖 CI 状态 API
SEO-4: README 结构检查
检查 README.md 是否包含以下结构,缺少则建议补充:
- 是什么:一句话描述项目功能
- 给谁用:目标用户和使用场景
- 怎么用:安装和使用步骤
- 技术栈:关键技术说明
关键词自然分布在正文和标题中,不写 Keywords 段落。
SEO-5: 提交并推送
git add README.md docs/images/ 2>/dev/null
git commit -m "docs: SEO optimization for GitHub visibility"
git push github CURRENT_BRANCH--ci 模块
推送成功后执行。不可与--scan/--dry-run组合。
CI-1: 项目类型检测
自动检测项目类型和测试框架:
# 检测语言
ls *.py setup.py pyproject.toml requirements*.txt 2>/dev/null # Python
ls package.json tsconfig.json 2>/dev/null # Node.js
find . -name "*.sh" -not -path "./.git/*" | head -5 # Bash
# 检测测试框架
grep -rl "pytest\|unittest" tests/ 2>/dev/null # Python test
grep -rl "jest\|mocha\|vitest" . --include="*.json" 2>/dev/null # JS test
# 检测系统依赖
grep -rl "tmux\|selenium\|chromium" . --include="*.py" --include="*.sh" --include="*.js" 2>/dev/nullCI-2: 平台矩阵决策
| 项目类型 | 系统依赖 | 平台矩阵 |
|---|---|---|
| Bash/tmux 项目 | tmux 等 | ubuntu-latest + macos-latest |
| 纯 Python | 无 | 三平台(注意 PYTHONUTF8: "1") |
| 纯 Python | tmux/selenium | 按依赖选平台 |
| Node.js | 无 | 三平台 |
| 跨平台 GUI | — | ubuntu-latest + macos-latest + windows-latest |
CI-3: 生成 .github/workflows/test.yml
根据检测结果生成 CI 配置。模板包含:
Python 项目模板:
name: Tests
on:
push:
branches: [master, main]
pull_request:
branches: [master, main]
jobs:
test:
strategy:
matrix:
os: [ubuntu-latest, macos-latest] # 按检测结果调整
python-version: ['3.10', '3.12']
runs-on: ${{ matrix.os }}
env:
PYTHONUTF8: "1"
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: pip install -r requirements-dev.txt
- name: Run tests
run: pytest tests/ -v --tb=shortBash 项目模板:
name: Tests
on:
push:
branches: [master, main]
pull_request:
branches: [master, main]
jobs:
test:
strategy:
matrix:
os: [ubuntu-latest, macos-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- name: Run tests
run: bash scripts/run_tests.shCI-4: 确认并推送
AskUserQuestion: CI 配置已生成
A) 直接推送
B) 我先看看再决定
C) 不需要 CI确认后:
git add .github/workflows/test.yml
git commit -m "ci: add GitHub Actions test workflow"
git push github CURRENT_BRANCH注意事项
- 不删除
originremote(通常是内部 NAS Git) - 不改变当前分支名
- 不 force push
- 脱敏发现的真实密钥必须处理,不能跳过
- 备份分支
pre-publish-backup不推送到远程 - SEO 模块只修改 README.md 和 metadata,不修改源代码
- CI 模块检测已有
.github/workflows/下文件,已存在时不覆盖,改为询问用户