safe-change：AI Agent 工具实践指南

真正理解safe-change，要从它处理的任务开始：集中管理 AI 编码工具配置，可复用 Claude Code、OpenCode、Codex 等工具的配置、MCP 服务、插件和命令。对安全分析任务来说，授权边界、证据完整性和误报需要同时控制往往决定它能否落地，不能只用安装成功来判断。落地前可以在明确授权的样例或离线靶场中验证，用输入边界、证据链、误报率和安全中止机制判断它是否真的省事。它更像给具备授权环境和复核能力的安全人员准备的可审查方案，是否长期使用应由试跑数据决定。

为什么存在安全变更

自主 AI 编码代理正在以前所未有的速度重写生产代码库。当您将任务委派给 AI 代理时，它会涉及数十个文件、改变依赖关系并重构关键架构边界。该应用程序可能仍然可以编译并启动，但微妙的逻辑已被颠倒，授权保护被删除，或者默默地引入回归 - 让开发人员猜测什么出了问题以及原因。

没有权威的基线和可验证的执行门：

• 回归成为法医噩梦：您不知道哪个代理操作破坏了通过不变检查。
• AST 语义漂移未被检测到：颠倒的逻辑条件、移除的安全防护以及吞没的错误绕过了表面的差异。
• 并发多代理写入损坏状态：不协调的代理操作相互竞争以及您的工作树。
• 企业出处无法证明：谁授权、执行和验证更改的加密证据为零。

safe-change是自主AI开发的可验证执行哨兵和高保证安全平面。

它在 AI 代理接触您的代码之前锁定加密基线，隔离 OS- 支持的沙箱内的执行，验证 AST 语义完整性，强制执行企业变更预算，并生成完整的 RFC 8785 Ed25519 签名证明 - 完全气隙，零云依赖，100% 确定性。

它是如何运作的

# Step 1 — Before the agent: lock in a verified baseline
safe-change save "auth and dashboard both passing"

# Step 2 — Let your agent do its work
# ...

# Step 3 — After the agent: detect what regressed
safe-change check

# Step 4 — See which files were touched
safe-change diff

Baseline: auth and dashboard both passing

Check             Before    Now       Result
─────────────────────────────────────────────
build             pass      pass      ok
unit-tests        pass      fail      REGRESSION
e2e-auth          pass      pass      ok

Files changed since baseline:
  Modified:  8
  Added:     2
  Deleted:   0

Exit 1 — 1 new regression detected.
Previously passing check now fails: unit-tests

哪些文件被跟踪和散列？

安全更改记录 SHA-256 加密哈希，用于代码库验证，同时尊重存储库边界：

• 包括： Git (git ls-files) 跟踪的所有文件以及 Git (git status -uall) 识别的未跟踪工作树文件。
• 排除： .gitignore（e.g.、node_modules/、dist/、构建工件、缓存文件夹）匹配的任何内容都将被完全忽略，并且永远不会被散列。 .safe-change/ 目录始终被排除。
• 二进制文件： 作为原始二进制流读取并直接使用 SHA-256 进行哈希处理，无需失真或字符解码。
• 符号链接： 使用 lstat 检查并按其链接目标字符串 (readlink) 进行哈希处理，无需跟踪或取消引用存储库外部的路径。

安装

npm install -g safe-change

# Verify
safe-change --version

Node.js ≥ 18。无构建步骤。没有编译器。没有云帐户。

快速启动

1. 1 秒初始化您的项目

safe-change init

自动检查您的存储库（Node.js、Rust、Go、Python、Makefile），使用检测到的测试运行程序生成 .safe-change.json，并可选择在指定 --update-gitignore 时更新 --update-gitignore。

2.在代理启动之前保存基线

safe-change save "before refactor"

3.代理完成后检查回归

safe-change check

4.检查更改的内容（文件和行数）

safe-change diff --stat

命令

所有命令都接受 --json 以获取结构化输出，并接受 --help 以获取使用详细信息。 安装程序命令接受 --scope <project|全局>, --dry-run, and --overwrite.

支持代理

# Detect which agents are installed and set up all of them at once
safe-change install all

有关验证状态的说明： 目前，所有代理均附带 filesystem-validated 状态，这意味着安全更改已被验证可以在每个代理的预期路径上正确安装、读取和删除技能文件。每个代理都会跟踪完整的运行时验证（确认每个代理在实时会话期间主动发现并调用技能），并将在后续版本中进行跟踪。如果您遇到代理无法获取已安装的技能，请 打开问题。

企业技能政策

每个安装都确定性地将规范安全合同与所选代理的经过验证的配置文件结合起来。该策略包括标准、高保证和事件模式；微观语法边界审查；失败关闭证据规则；即时注射边界；并发漂移检测；测试完整性控制；释放门；以及所需的验证报告。

所有权清单记录规范、配置文件和组合的 SHA-256 值。因此，safe-change status 检测共享策略或特定于代理的配置文件中的偏差。请参见 docs/enterprise-skill-policy.md。

MCP 服务器

支持模型上下文协议的代理可以将安全更改作为本机工具调用 - 无需 SKILL.md，无需手动设置，无需 PATH 配置。

safe-change mcp

将其添加到代理的 MCP 配置中：

{
  "mcpServers": {
    "safe-change": {
      "command": "safe-change",
      "args": ["mcp"]
    }
  }
}

暴露的工具：

docs/mcp-setup.md 中的完整每个代理设置。

安全规则

自动在每个 safe-change check 上强制实施护栏。

safe-change rules add no-delete-migrations
safe-change rules add no-modify-lockfile
safe-change rules add max-files-changed
safe-change rules add require-tests-pass

severity: error 的规则违规设置退出代码 1，与回归相同。内置规则提供生产默认值。可以通过编辑 .safe-change/rules.json 或通过 safe-change rules add <file.json> 传递 JSON 规则文件来配置自定义阈值、自定义目标模式或自定义检查名称。有关完整规则条件规范，请参阅 docs/rules.md。

本地仪表板

safe-change dashboard
# Dashboard running at http://localhost:4242
# Press Ctrl+C to stop.

完全离线。仅绑定到 127.0.0.1 — 从未暴露于网络。

端口配置：

# Override via CLI flag
safe-change dashboard --port 8080

// Or set in .safe-change.json
{ "dashboardPort": 8080 }

如果配置的端口已被使用，服务器将退出并出现错误。选择一个可用的端口并重试。

企业架构及特点：

• 品牌标记 /SAFE-CHANGE：极简开发级排版，与 Apple Liquid Glass 设计系统相匹配。
• 6 个英雄指标卡：实时系统状态、监控基线、企业风险和模式（0-100 分）、更改预算范围、主动写租赁以及防篡改审计和信任链。
• 6 个交互式分段选项卡：
  • Overview & Baseline：基线状态、活动规则、交互式回归时间线和持久日志历史记录。
  • Enterprise Risk & Budget：风险评分计量表、实时信号分类和差异边界检查。
  • AST Semantic Security：深层 AST 语法检查、破坏导出检测和公共 API 表面保护。
  • Verifiable Replay & Attestations：RFC 8785 Ed25519 签名的证明信封和确定性重播会话简介。
  • Identity & Trust Registry：授权批准者身份、公钥和多重签名仲裁状态。
  • Tamper-Evident Audit Chain：SHA-256 密码链完整性验证和不可变审计事件流。
• 离线遥测 API：只读 JSON 端点（/api/status、/api/log、/api/config、/api/rules、/api/enterprise、 /api/lease、/api/audit、/api/identity、/api/verifiable）。
• 完整的仪表板文档位于 docs/dashboard.md。

安全模型

safe-change 的构建永远不会成为回归的原因。

安全警告 - 配置信任边界： .safe-change.json 指定在 save 和 check 期间安全更改调用的可执行命令和参数。虽然 safe-change 使用直接进程生成而无需 shell 扩展（减轻 shell 注入），但命令会以您当前的用户权限执行。对 .safe-change.json 进行与 Makefile、package.json 脚本或 CI 工作流程相同的审查 — 切勿在来自第三方拉取的不受信任或未经审核的配置上运行 safe-change save 或 safe-change check请求。

有关信任边界和漏洞报告，请参阅 SECURITY.md。

退出代码

文档