east-true/agent-config-inspector

# Agent Config 检查器 Agent Config Inspector 是一个离线 CLI，用于预测 Claude Code、Codex CLI 和 Gemini CLI 在目标路径下会接收到哪些仓库指令，然后在不执行仓库代码的情况下解释配置漂移（configuration drift）。 ## 为什么需要这个工具 编程 Agent 使用不同的文件名、层级规则、导入机制和路径作用域。因此，一个仓库可能看起来配置得很一致，但其 Agent 实际接收到的指导却各不相同。Agent Config Inspector 通过提供来源信息和保守的发现结果，让这种差异变得可见。 当前的来源注册表包含： - `anthropic-claude-code/cli`（别名 `claude`） - `google-gemini/cli`（别名 `gemini`） - `openai-codex/cli`（别名 `codex`） Kimi、Grok、Copilot 和其他 Agent 仍然是计划中的独立适配器。当前对它们的请求会因不支持而失败，而不是进行猜测。 ## 当前功能 - 解析根目录和嵌套的 `CLAUDE.md`、`CLAUDE.local.md`、`.claude/CLAUDE.md`、递归的 `.claude/rules/**/*.md`、路径 glob 以及有界的 `@imports`。 - 解析根目录和嵌套的 `AGENTS.override.md`、`AGENTS.md`、Codex 回退文件名以及合并后的项目指令字节预算。 - 解析 Gemini CLI v0.50.0 的分层上下文、已配置的上下文文件名、内存边界、特定于目标的 JIT 上下文以及有界的 `@imports`。 - 在不调用 LLM 或进行网络请求的情况下比较标准化的指令单元。 - 解释包含和排除的来源、优先级、证据、token 估算和置信度。 - 默认拒绝工作区逃逸（workspace escapes）和外部导入。 - 在文本和 JSON 输出中隐藏指令内容和工作区的绝对路径。 - 仅在使用 `--include-user-context` 时读取已知的用户级指令位置，随后对路径、内容、摘要、大小和 token 估算进行脱敏处理。 - 固定（Pin）确定性的仅限仓库的 lockfile，并验证 pull-request 漂移。 - 输出兼容 GitHub 的 SARIF 2.1.0，不包含外部或用户来源的位置。 ## 构建 需要 Go 1.25 或更高版本。 ``` git clone git@github.com:east-true/agent-config-inspector.git cd agent-config-inspector go build -o bin/agent-config-inspector ./cmd/agent-config-inspector ``` 当前核心功能不需要任何第三方 Go module。 ## 快速开始 扫描当前仓库的所有受支持的 provider： ``` ./bin/agent-config-inspector scan . ``` 解释单个文件的 Codex 解析过程： ``` ./bin/agent-config-inspector explain . \ --provider codex \ --target backend/src/users.go ``` 以 JSON 格式比较 Claude Code 和 Codex CLI： ``` ./bin/agent-config-inspector diff . \ --providers claude,codex \ --target backend/src/users.go \ --format json ``` 在发现警告或错误时使 CI 失败： ``` ./bin/agent-config-inspector scan . --fail-on warning ``` 固定（Pin）当前由仓库拥有的指令状态，并在稍后进行验证： ``` ./bin/agent-config-inspector pin . ./bin/agent-config-inspector verify . ``` 默认的 lockfile 是 `agent-config-inspector.lock.json`。它仅包含相对于仓库的路径和摘要。请参阅 [快照格式](docs/snapshot-format.md)。 在本地生成 SARIF： ``` ./bin/agent-config-inspector verify . --format sarif > agent-config-inspector.sarif ``` 在检出（check out）仓库后使用复合 GitHub Action： ``` permissions: contents: read security-events: write steps: - uses: actions/checkout@v7.0.1 - uses: east-true/agent-config-inspector@v0.3.0 with: command: verify snapshot: agent-config-inspector.lock.json fail-on: warning version: v0.3.0 upload-sarif: "true" ``` 该 Action 会下载选定的 GitHub Release，从 `checksums.txt` 验证其 SHA-256 条目，然后运行它。当工作流需要固定版本的二进制文件时，请将 `version` 输入设置为确切的发布标签。 查看确切的 provider 注册表： ``` ./bin/agent-config-inspector providers list ./bin/agent-config-inspector providers show gemini ``` ## 退出代码 | 代码 | 含义 | |---:|---| | 0 | 完成运行，且未达到配置的发现阈值 | | 1 | 发现结果达到了 `--fail-on` 设定的条件 | | 2 | 无效的 CLI 用法或配置 | | 3 | 内部错误或不完整的结果 | | 4 | 不支持的 provider、表面（surface）、版本或预览命令 | | 5 | 安全策略拒绝了请求 | 默认情况下，警告不会导致失败。使用 `--fail-on warning` 可采用更严格的 CI 策略，或使用 `--fail-on never` 进行仅作参考的信息展示运行。 ## 隐私模型 默认扫描是本地的、离线的、只读的、限定于仓库范围的，并且不会执行 provider CLI、hooks、构建脚本、MCP 服务器或仓库命令。输出包含仓库拥有来源的元数据和内容摘要，绝不包含指令文本。 除非提供 `--include-user-context`，否则用户级指令将被排除。在该模式下，只会清点已记录的用户指令位置，并且输出标识符仍将保持不透明状态。在发布使用本地上下文生成的报告之前，请参阅[隐私](docs/privacy.md)和[安全策略](SECURITY.md)。 `pin` 和 `verify` 特意拒绝使用 `--include-user-context`。一个准备好提交的 lockfile 不能代表用户来源的存在、路径、内容、指纹或 token 数量。 ## 准确性边界 适配器基于当前的官方发现文档，并特意报告了其检查日期。运行时标志、信任决策、托管策略、版本漂移和 Agent 行为可能会改变实际结果。请参阅[支持矩阵](docs/support-matrix.md)和[局限性](docs/limitations.md)。 主要语义参考： - [Claude Code 内存和指令发现](https://code.claude.com/docs/en/memory) - [Codex `AGENTS.md` 指南](https://developers.openai.com/codex/guides/agents-md) - [Gemini CLI 适配器契约](docs/gemini-cli.md) - [Gemini CLI 上下文文件](https://geminicli.com/docs/cli/gemini-md/) - [Gemini CLI 内存导入处理器](https://geminicli.com/docs/reference/memport/) ## 开发 ``` go test ./... go vet ./... go build ./cmd/agent-config-inspector git diff --check ``` 详细的架构和路线图请参阅 [docs/initial-design.md](docs/initial-design.md)。欢迎贡献代码；请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 Apache License 2.0。请参阅 [LICENSE](LICENSE)。

标签：AI代码助手, EVTX分析, Go, Ruby工具, SOC Prime, 云安全监控, 开发工具, 日志审计, 静态分析