name: specstory-guard description: 安装一个预提交钩子，在提交前扫描 .specstory/history 中的秘密。当用户说“设置秘密扫描”、“安装 specstory guard”、“保护我的历史”或“检查秘密”时运行。 license: Apache-2.0 metadata: author: SpecStory, Inc. version: “1.0.0” argument-hint: “[install|scan|check|uninstall] [–root PATH]” allowed-tools: Bash, Read, Write

SpecStory 防护

一个预提交防护栏，扫描 .specstory/history 中的潜在秘密，并在它们被移除或编辑前阻止提交。

工作原理

安装一个 git 预提交钩子到您的仓库
扫描每次提交时的 .specstory/history 文件
检测常见秘密模式（API 密钥、令牌、私钥）
阻止提交如果发现秘密
报告发现，并提供安全预览供审核

为什么使用防护？

AI 编码会话可能无意中捕获敏感数据：

您粘贴到聊天中的 API 密钥
命令输出中的环境变量
错误消息中的私钥或令牌
配置示例中的凭据

防护可防止意外提交这些秘密。

使用方式

斜杠命令

用户说	动作
`/specstory-guard`	安装预提交钩子
`/specstory-guard install`	安装预提交钩子
`/specstory-guard scan`	运行手动扫描而不安装
`/specstory-guard check`	扫描的别名
`/specstory-guard uninstall`	移除预提交钩子

直接脚本使用

# 安装预提交钩子
python skills/specstory-guard/scripts/guard.py install

# 运行手动扫描
python skills/specstory-guard/scripts/guard.py scan --root .

# 卸载钩子
python skills/specstory-guard/scripts/guard.py uninstall

# 使用自定义允许列表扫描
SPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*' \
  python skills/specstory-guard/scripts/guard.py scan --root .

输出

扫描有发现：

SpecStory 防护 - 安全扫描
===============================

扫描 .specstory/history/...

警报：发现潜在秘密！

文件： .specstory/history/2026-01-22_19-20-56Z-api-setup.md
  第 142 行： AWS_SECRET_ACCESS_KEY=AKIA...已编辑...XYZ
  第 289 行： private_key: "-----BEGIN RSA PRIVATE KEY-----..."

文件： .specstory/history/2026-01-20_10-15-33Z-debug-auth.md
  第 56 行： Authorization: Bearer eyJhbG...已编辑...

总计： 2 个文件中发现 3 个潜在秘密

提交被阻止。请在提交前编辑或移除这些秘密。

清洁扫描：

SpecStory 防护 - 安全扫描
===============================

扫描 .specstory/history/...

全部清除！在 47 个文件中未检测到秘密。

安装成功：

SpecStory 防护 - 设置
=======================

预提交钩子已安装到 .git/hooks/pre-commit

钩子现在会在每次提交前扫描 .specstory/history/。
测试： python skills/specstory-guard/scripts/guard.py scan --root .

检测模式

防护扫描这些常见秘密模式：

模式	示例
AWS 密钥	`AKIA...`, `aws_secret_access_key`
API 令牌	`Bearer ...`, `token: ...`
私钥	`-----BEGIN RSA PRIVATE KEY-----`
GitHub 令牌	`ghp_...`, `github_pat_...`
通用秘密	`password=`, `secret=`, `api_key=`

使用允许列表调整

如果有误报（示例密钥、占位符），使用允许列表：

# 环境变量（逗号分隔的正则表达式模式）
SPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*,test-token' \
  python skills/specstory-guard/scripts/guard.py scan --root .

补救

当发现秘密时：

打开文件 - 从报告中找到行号
编辑秘密 - 替换为 [已编辑] 或移除该行
重新运行扫描 - 通过另一次扫描验证修复
提交 - 预提交钩子将通过

向用户呈现结果

运行防护命令后：

对于安装 - 确认钩子已安装并解释其功能
对于扫描有发现 - 列出发现并帮助编辑它们
对于清洁扫描 - 确认未发现秘密

示例响应（有发现）

我在您的 SpecStory 历史中发现了 3 个潜在秘密：

1. **AWS 凭据** 在 `2026-01-22_19-20-56Z-api-setup.md` 中（第 142 行）
2. **私钥** 在同一个文件中（第 289 行）
3. **Bearer 令牌** 在 `2026-01-20_10-15-33Z-debug-auth.md` 中（第 56 行）

您想让我帮助编辑这些吗？我可以用 `[已编辑]` 替换它们，同时保留对话上下文的其他部分。

备注

无外部依赖（纯 Python）
钩子在 git commit 时自动运行
扫描快速 - 通常数百个文件不到 1 秒
允许列表模式是正则表达式