douglasmonsky/agent-maintainer

# Agent 维护者 [](https://github.com/douglasmonsky/agent-maintainer/actions/workflows/verify.yml) [](https://pypi.org/project/agent-maintainer/) [](https://pypi.org/project/agent-maintainer/) [](LICENSE) 面向 AI 辅助 Python 代码库的可维护性检查与修复循环诊断。 Agent Maintainer 旨在帮助 Python 代码库在 AI 辅助开发中保持良好的可维护性。它将低干扰验证、变更预算、抑制控制、覆盖率门槛、类型检查、架构检查、安全检查以及结构化诊断整合为一个工作流，供人类和编程 Agent 共同使用。 ## 这是什么 Agent Maintainer 是一个针对 AI 辅助代码变更的代码库维护控制层。它用于检查变更是否小到易于审查、是否有测试支撑、是否通过类型检查、是否被覆盖、是否可诊断，以及是否与代码库结构保持一致。 ## 这不是什么 Agent Maintainer 不是运行时的 AI 安全系统。它不会审核模型输出、过滤提示词、拦截越狱操作或验证聊天机器人回复。它也不是一个提示词/输出审核框架。Agent Maintainer 仅专注于 AI 辅助软件开发过程中的代码库健康状况。 ## 快速开始 安装核心工具集： ``` python -m pip install "agent-maintainer[core]" ``` 初始化代码库： ``` agent-maintainer init --track core ``` 将 `config/pyproject.agent-maintainer.toml` 合并到你的 `pyproject.toml` 中，根据你的代码库调整路径，然后检查配置健康状况： ``` agent-maintainer doctor agent-maintainer verify --profile precommit ``` ## 首次成功运行 健康配置的输出应当十分简洁： ``` PASS ``` `doctor` 会为每项配置检查输出一行简明的 `PASS`、`WARN` 或 `FAIL` 结果。如果验证失败，请在调整阈值或抑制配置之前，先检查生成的诊断信息： ``` cat .verify-logs/LAST_FAILURE.md ``` 失败提示中包含了未通过的检查项、相关的产物路径，以及精确的重跑命令。 控制台命令非常适合本地使用。但对于已提交的自动化流程，应使用模块入口点，因为它在可编辑的本地源码环境中能更稳定地运行： ``` python3 -m agent_maintainer verify --profile precommit ``` ## 引入路径 `init` 会为三个引入级别生成初始文件： | 路径 | 适用场景 | 生成内容 | |---|---|---| | `core` | 你希望使用最基础且实用的维护循环。 | 初始配置、`config/dev-dependencies.txt`、pre-commit 配置、CI 工作流。 | | `agent` | 编程 Agent 正在积极修改该代码库。 | 核心文件，外加 `AGENTS.md` 和 Codex 钩子文件。 | | `hardening` | 你希望提升文档/配置规范度，并关注安全相关的方面。 | Agent 文件，外加基于 Node 的工具元数据。 | 在修改代码库之前，你可以先预览将要生成的内容： ``` python3 -m agent_maintainer init --track agent --dry-run ``` 除非传入 `--force` 参数，否则不会覆盖现有文件。 ## 常用命令 ``` python3 -m agent_maintainer bootstrap python3 -m agent_maintainer doctor --strict python3 -m agent_maintainer guidance python3 -m agent_maintainer guidance --check python3 -m agent_maintainer verify --profile fast python3 -m agent_maintainer verify --profile precommit python3 -m agent_maintainer verify --profile full python3 -m agent_maintainer verify --profile ci python3 -m agent_maintainer verify --profile security python3 -m agent_maintainer verify --profile manual python3 -m archguard tach-config --strict-root-module python3 -m archguard decision-check --base-ref HEAD ``` Profile 在设计上是刻意保持稳定的： | Profile | 用途 | |---|---| | `fast` | 适合在编辑后执行的、对钩子友好的检查。 | | `precommit` | 本地完成度门槛。 | | `full` | 在大型合并前执行的深度审查门槛。 | | `ci` | GitHub Actions 门槛。 | | `security` | 面向安全扫描的 Profile。 | | `manual` | 需手动启用的耗时工具，例如变异测试和 Semgrep。 | ## 工具检查内容 | 关注点 | 执行方式 | |---|---| | 过大的 Python 文件 | `agent_maintainer.checks.file_lengths` | | 过大或过于分散的变更 | `agent_maintainer.checks.change_budget` | | 范围过广的抑制配置 | `agent_maintainer.checks.suppression_budget` | | 要求的代码库结构 | Verifier 结构检查 | | 代码风格与简单缺陷 | Ruff | | 类型规范 | Pyright | | 测试覆盖率 | Pytest, pytest-cov, coverage, diff-cover | | 复杂度 | Radon 报告和 Xenon 门槛 | | 架构边界与策略治理 | Tach 或 Import Linter；使用 Archguard 进行 Tach 策略变更决策 | | 依赖规范 | deptry | | 无用代码 | vulture | | 安全检查 | Bandit, pip-audit, Gitleaks 以及（启用时的）Semgrep | | 供应链产物 | （启用时的）CycloneDX Python SBOM 和 pip-licenses | | GitHub Actions 检查 | （存在工作流时的）actionlint 和 zizmor | | 文档/配置规范 | （启用时的）markdownlint-cli2, yamllint, Taplo, check-jsonschema | | Agent 反馈 | `AGENTS.agent-maintainer.md` 和 `.verify-logs` 诊断信息 | ## 配置说明 配置项存放在 `pyproject.toml` 中： ``` [tool.agent_maintainer] mode = "custom" architecture_tool = "import-linter" source_roots = ["src"] test_roots = ["tests"] package_paths = ["src"] coverage_source = ["src"] require_tests = true coverage_fail_under = 80 diff_cover_fail_under = 90 [tool.agent_maintainer.diagnostics] enabled = true log_dir = ".verify-logs" ``` `mode = "fresh-strict"` 适用于可以在第一天就实施严格检查的全新代码库。`mode = "legacy-ratchet"` 适用于现有代码库，在逐步加强变更代码规范的同时，较重的检查门槛应保持可选状态。与初始模板相比，本代码库自身执行了更严格的设置，包括 90% 的总测试覆盖率。 环境变量覆盖使用 `AGENT_MAINTAINER_*` 前缀： ``` AGENT_MAINTAINER_SOURCE_ROOTS=src,tests python3 -m agent_maintainer doctor ``` ## Agent 指南 生成的辅助配置文件可以在无需将长篇指令复制到每个提示词的情况下，为编程 Agent 提供当前的代码库策略： ``` python3 -m agent_maintainer guidance python3 -m agent_maintainer guidance --check ``` 此操作会根据 `[tool.agent_maintainer]` 的配置生成 `AGENTS.agent-maintainer.md`。请先更新配置，然后再重新生成该辅助文件。 ## 可选工具 根据引入级别安装扩展依赖： ``` python -m pip install "agent-maintainer[core]" python -m pip install "agent-maintainer[hardening]" python -m pip install "agent-maintainer[manual]" python -m pip install "agent-maintainer[all]" ``` 当代码库选择启用加固路径时，诸如 `markdownlint-cli2` 和 Taplo 等基于 Node 的工具将通过 `package.json` 进行管理： ``` npm ci ``` ## 从源码安装 如果要在本地对 Agent Maintainer 本身进行开发，请克隆代码库并运行： ``` python -m pip install -e ".[core]" agent-maintainer --help ``` 普通的下游代码库应使用包优先的初始化流程，而不是直接将 `src/agent_maintainer` 复制到应用程序源码目录中。 ## 本地开发 针对此代码库： ``` PYTHONPATH=src python3 -m agent_maintainer bootstrap PYTHONPATH=src python3 -m agent_maintainer doctor --strict PYTHONPATH=src python3 -m agent_maintainer verify --profile precommit PYTHONPATH=src python3 -m agent_maintainer verify --profile full ``` 在更改 `config/dev-dependencies.txt` 之后，请刷新锁定的开发依赖版本： ``` PYTHONPATH=src python3 -m agent_maintainer bootstrap .venv/bin/python -m pip freeze --exclude-editable | sort > config/dev-lock.txt ``` ## 延伸阅读 - [MIT License](LICENSE) - [更新日志](CHANGELOG.md) - [工具映射表](docs/tool-map.md) - [首次运行指南](docs/onboarding-first-run.md) - [Fresh-strict 模式](docs/fresh-strict.md) - [Legacy-ratchet 模式](docs/legacy-ratchet.md) - [Codex 钩子](docs/codex-hooks.md) - [发布检查清单](docs/release-checklist.md) - [故障排除](docs/troubleshooting.md) - [结构内聚性](docs/structure-cohesion.md) 初始示例项目： - [Fresh-strict 示例](examples/fresh-strict) - [Legacy-ratchet 示例](examples/legacy-ratchet)

标签：AI辅助开发, Python, SOC Prime, 云安全监控, 开发工具, 开源框架, 持续集成, 无后门, 逆向工具, 静态分析