xixifusi1213-gif/ai-project-maintainer

# AI Project Maintainer    [](https://www.npmjs.com/package/ai-project-maintainer) [](https://github.com/xixifusi1213-gif/ai-project-maintainer/actions/workflows/ci.yml) [](https://github.com/xixifusi1213-gif/ai-project-maintainer/actions/workflows/security.yml) **专为 AI 编写的项目打造的发布就绪把关工具。** AI 能够快速生成代码。该工具旨在帮助你在代码生成后保持项目的可维护性：收集项目证据、规划审计、运行确定性检查关卡、生成 AI agent 修复任务，并不断重试，直到发布理由充分且经得起考验。 [查看演示](docs/DEMO.md) | [中文演示](docs/DEMO.zh-CN.md) | [真实 OSS 案例](docs/CASE-STUDIES.md) | [项目画像](docs/PROJECT-PROFILES.md) | [AI agent 风险检查](docs/AGENT-RISK.md) | [AI 修复包](docs/REPAIR-PACK.md) | [为何信任此工具？](TRUST.md) | [发布信任](docs/RELEASE-TRUST.md) | [设计说明](DESIGN.md) | [标准对照](docs/STANDARDS-CROSSWALK.md) 这不是又一个简单的扫描器封装。它将 AI 编码维护转化为一个可重复的闭环流程： ``` project profile -> audit plan -> local/CI gate -> evidence report -> AI fixes -> rerun ``` ## 为什么需要此工具 AI 编码让发布看似完整、实则暗藏生产级缺陷的代码变得轻而易举： - 缺乏业务流测试 - 没有 secret/dependency/security 关卡 - 没有数据库 migration 审查 - 没有发布审批或回滚证据 - 没有监控/日志/告警证明 - 没有明确的所有者批准的例外情况 `ai-project-maintainer` 能够在这些隐患演变成生产环境事故之前将其暴露出来。 ## 30秒快速入门 需要 Node.js 20+。 ``` npx ai-project-maintainer doctor --no-trivy-db npx ai-project-maintainer init ".\my-project" --profile auto --ci github npx ai-project-maintainer agent-risk ".\my-project" npx ai-project-maintainer init-audit ".\my-project" --wizard --dry-run npx ai-project-maintainer init-audit ".\my-project" --wizard npx ai-project-maintainer gate ".\my-project" --profile auto --production --agent-risk --strict --release --output reports/security-report.json npx ai-project-maintainer repair-pack reports/security-report.json --project ".\my-project" --output reports ``` `PASS_WITH_GAPS` 表示没有阻塞性检查失败，但发布就绪证据仍然缺失，或者在生产前需要所有者批准。 ## 3分钟流程 需要 Node.js 20+。 ``` # 1. 添加本地和 CI guardrails npx ai-project-maintainer init "E:\my-project" --profile auto --ci github # 2. 回答引导式 production audit 接收问题 npx ai-project-maintainer init-audit "E:\my-project" --wizard # 3. 生成特定于项目的 audit plan npx ai-project-maintainer audit-plan "E:\my-project" --profile auto --output reports/audit-plan.json # 4. 运行 production gate npx ai-project-maintainer gate "E:\my-project" --profile auto --production --agent-risk --strict --release --output reports/security-report.json # 5. 将报告转换为 AI-agent 修复任务 npx ai-project-maintainer repair-pack "E:\my-project\reports\security-report.json" --project "E:\my-project" --output "E:\my-project\reports" ``` GitHub Actions 模板可以使用 npm 包，也可以直接克隆此代码库。 ## 如何建立发布信任 从 v1.0.0 版本开始，项目的发布设计为通过 GitHub Actions 和 npm Trusted Publishing 进行，而不是通过维护者的本地计算机发布。 发布链条如下： ``` Git tag -> GitHub Actions gate -> npm provenance -> SBOM -> release manifest -> GitHub Release assets ``` 每次发布都应包含 tarball、`sbom.cdx.json`、`release-manifest.json` 以及用于发布决策的安全报告。请参阅[发布信任](docs/RELEASE-TRUST.md)、[报告 schema](docs/REPORT-SCHEMA.md)和[安全策略](SECURITY.md)。 可以使用以下命令检查已发布版本的一致性： ``` node ai-project-maintainer/scripts/verify-release.mjs --published --version 1.2.1 --tag v1.2.1 --manifest dist/release-manifest.json ``` ## 画像感知关卡 v1.1.0 添加了项目类型规则包。默认的 `--profile auto` 会检测主要风险面，并应用相应的审查重点： - `electron-desktop`：IPC/preload、本地文件访问、shell/openExternal、更新、打包发布信任 - `nextjs-web`：auth middleware、API routes、Server Actions、公共环境变量、CORS/uploads、部署证据 - `node-api`：authz、输入验证、速率限制、CORS、日志脱敏、API 测试 - `database-prisma`：Prisma schema、migrations、破坏性变更、备份、回滚、事务 - `oss-library`：包元数据、许可证、CI、Scorecard、SBOM、provenance、SemVer 如有需要，可覆盖自动检测结果： ``` npx ai-project-maintainer gate "E:\my-project" --profile database-prisma --production --strict --release ``` 请参阅[项目画像](docs/PROJECT-PROFILES.md)和[中文说明](docs/PROJECT-PROFILES.zh-CN.md)。 ## 真实演示 此代码库在 `examples/demo-ai-app` 中包含一个可运行的示例项目。  ``` npm test --prefix .\examples\demo-ai-app npm run build --prefix .\examples\demo-ai-app node .\examples\demo-ai-app\scripts\run-demo-gate.mjs ``` 演示展示了预期的工作流程： - 健康的业务测试和发布构建通过 - 报告中呈现了 Gitleaks、Trivy、Semgrep、OSV、Syft、Grype、Scorecard 和 CI 检查 - 对于发布审批、监控、日志、指标和告警，生产就绪方面的差距依然可见 要在不提交不安全测试用例的情况下查看“修复前”的状态： ``` node .\examples\demo-ai-app\scripts\create-before-state.mjs ``` 它会在操作系统临时目录下写入一个损坏的副本，其中的业务测试将会失败。 ## 修复闭环演示 v1.2.1 在不调用外部 AI 模型的情况下，对完整的修复闭环进行了 dogfood 测试： ``` npm run smoke:repair-loop ``` 该脚本会创建一个损坏的 `examples/demo-ai-app` 临时副本，运行关卡以获得 `FAIL`，生成 `agent-tasks.json` 和 `codex-tasks.json`，应用确定性的“模拟 AI 修复”，运行 `npm test`，然后再次运行关卡。预期的最终状态是 `PASS_WITH_GAPS`：阻塞性问题已确定性地修复，而生产证据的缺失依然可见。 更多演示资料： - [修复前后案例](docs/demo-output/before-after-case.md) - [90秒浏览器演示](docs/demo-output/90-second-demo.html) - [动态 SVG 故事板](assets/demo-90s-storyboard.svg) ## 真实 OSS 案例研究 演示的规模故意设置得很小。案例研究使用了真实的开源安全公告、发布版本和补丁提交： - [SiYuan Electron RCE](docs/cases/electron-oss-before-after.md)：展示了为何修复公告后在发布前仍可能需要对 Electron runtime 进行安全加固。 - [Ghost SQL injection](docs/cases/ghost-sql-injection-before-after.md)：展示了在上游应用参数化绑定补丁后，数据库查询拦截器状态如何从 `FAIL` 变为 `PASS_WITH_GAPS`。 运行案例研究验证器： ``` npm run cases:verify ``` 该代码库仅存储链接、元数据和生成的报告。它不包含第三方源码树，也不提供 exploit 代码。 ## 检查内容 | 领域 | 生成的证据 | | --- | --- | | 测试和发布脚本 | test/E2E/build/dist 失败情况 | | Secrets | Gitleaks 发现 | | Dependencies | npm/pnpm/yarn audit, Trivy, OSV-Scanner | | 静态安全 | Semgrep 阻塞性发现 | | 供应链 | Syft SBOM, Grype 扫描 | | CI 安全 | actionlint, zizmor | | AI agent 风险 | MCP 权限、Codex/Claude/Cursor 指令、prompt 注入内容、危险的 agent 可执行脚本 | | IaC | Checkov, Trivy config | | Electron 应用 | 危险的 webPreferences、preload/IPC/file-read 风险 | | 数据库项目 | migration、备份、回滚、审查工具缺失 | | 生产就绪 | 监控、日志、指标、告警、发布审批、事件处理手册 | ## 生产级审计，而非仅仅是扫描 V3 添加了基于信息收集的审计层： ``` .ai-maintainer/project-profile.yml .ai-maintainer/evidence-sources.yml .ai-maintainer/business-flows.yml .ai-maintainer/risk-policy.yml .ai-maintainer/intake-summary.md .ai-maintainer/threat-model.md .ai-maintainer/release-checklist.yml .ai-maintainer/incident-runbook.md .ai-maintainer/db-migration-policy.yml .ai-maintainer/observability-checklist.yml ``` v0.6.0 添加了引导式信息收集向导： ``` npx ai-project-maintainer init-audit "E:\my-project" --wizard npx ai-project-maintainer init-audit "E:\my-project" --wizard --lang zh-CN npx ai-project-maintainer init-audit "E:\my-project" --wizard --dry-run ``` CLI 会提出确定性的问题并写入 YAML。它不调用 OpenAI API。当在 Codex 中使用时，`ai-project-maintainer` skill 可以解释每个问题，进行追问，然后让 CLI 写入相同的文件。 ## 可选的生产证据连接器 默认情况下，该工具无需账号，且不会调用生产平台。v0.7.0 为希望获得更强有力生产证据的项目添加了可选的只读连接器： ``` npx ai-project-maintainer connectors doctor "E:\my-project" npx ai-project-maintainer evidence "E:\my-project" --output reports/evidence-report.json npx ai-project-maintainer gate "E:\my-project" --production --connectors --strict --release --output reports/security-report.json ``` v0.7.0 实现了对 GitHub Environments、Sentry、Vercel、Grafana、Prometheus、Bytebase、Atlas 本地 migration lint、Cloudflare Pages、Render 和 Fly 的支持。每个连接器均为可选启用且只读。默认情况下，缺失 token 或 API 无法读取会被标记为 `GAP`，而不会伪装为成功。 token 保留在环境变量中，绝不会出现在 `.ai-maintainer/connectors.yml` 中： ``` connectors: github: enabled: true token_env: GITHUB_TOKEN owner: your-org repo: your-repo environment: production grafana: enabled: true token_env: GRAFANA_TOKEN base_url: https://grafana.example.com atlas: enabled: true migrations_dir: migrations dev_url_env: ATLAS_DEV_URL ``` 连接器仅读取证据。它们不会进行部署、回滚、更改环境变量、修改数据库或创建告警。除非您的风险策略明确禁止缺失生产证据，否则默认情况下，缺失 token 或 API 不可用都会被记录为 `GAP`。 ## AI agent 风险检查 v0.9.0 添加了一个仅限本地运行的关卡，用于检查因授予 AI agent 代码库访问权限而带来的风险： ``` npx ai-project-maintainer agent-risk "E:\my-project" npx ai-project-maintainer gate "E:\my-project" --agent-risk --strict --release --output reports/security-report.json ``` 它会检查 MCP 配置、Codex/Claude/Cursor 指令、类似于 prompt 注入的代码库文本、敏感文件名、包生命周期脚本以及可运行的项目脚本。它绝不启动 MCP 服务器，绝不调用 OpenAI/Codex API，也绝不会将 token 值写入报告。 ## AI agent 修复包 v1.2.0 能够将关卡报告转换为可供任何 AI 编码助手使用的修复任务。尽管通过兼容性文件支持 Codex，但其主要格式是通用的： ``` npx ai-project-maintainer repair-pack "E:\my-project\reports\security-report.json" --project "E:\my-project" --output "E:\my-project\reports" ``` 它会写入： ``` reports/fix-plan.md reports/agent-tasks.json reports/codex-tasks.json reports/recheck-commands.ps1 reports/recheck-commands.sh ``` 任务被划分为 `auto_fix_candidate`、`needs_maintainer_decision`、`manual_review_required` 和 `recheck_only`，从而确保 AI agent 能够修复正确的问题，同时将业务风险的接受权交还给维护者。请参阅[AI 修复包](docs/REPAIR-PACK.md)。 用户负责提供业务事实和证据位置。该工具会决定适用哪些检查，并为每个条目明确打上标签： ``` PASS checked and OK FAIL checked and failed WARN risky but not blocking by default GAP missing evidence N/A not applicable to this project USER_DECISION maintainer judgment required ``` 默认情况下，报告 `GAP` 不会导致关卡失败。如果要让缺失生产证据成为硬性的发布阻塞项： ``` production: block_on_coverage_gaps: true ``` ## 报告 每次运行都会写入： ``` reports/security-report.json reports/security-report.md reports/security-report.sarif reports/sbom.cdx.json reports/agent-risk-report.json reports/agent-risk-report.md reports/fix-plan.md reports/agent-tasks.json reports/codex-tasks.json reports/recheck-commands.ps1 reports/recheck-commands.sh ``` 报告包含： - PASS/FAIL 摘要 - `overallStatus`：`FAIL`、`PASS_WITH_GAPS`、`PASS_WITH_WARNINGS` 或 `PASS` - `evidenceLevel`：`TOOL_VERIFIED`、`PLATFORM_VERIFIED`、`USER_REPORTED`、`INFERRED` 或 `GAP` - `standardRefs` 和顶层 `standards` 交叉对照数据 - 阻塞项和警告 - 生产证据缺失 - AI agent 和 MCP 风险发现 - 仍需用户做出的决策 - 工具版本和命令 - 例外情况使用记录 - 用于 GitHub Code Scanning 的 SARIF - 开源维护评分 默认情况下，SARIF 仅会将可操作的代码/安全发现上传到 GitHub Code Scanning。非阻塞性的生产缺失将保留在 Markdown/JSON 报告和 Actions Summary 中，这样公共的 Security 页面就不会因为日志或告警的缺失而显示得像一面漏洞墙。 v0.8.0 增加了基于标准的信任元数据。这种映射关系解释了哪些检查是由公共框架支持的，例如 NIST SSDF、OWASP SAMM、SLSA、OpenSSF Scorecard、Google SRE、CIS Control 11、NIST SP 800-34 和 DORA 研究。这并非一种认证或安全保证。 ## 配合 Codex 使用 作为 Codex skill 安装： ``` git clone https://github.com/xixifusi1213-gif/ai-project-maintainer.git cd .\ai-project-maintainer Copy-Item -Recurse .\ai-project-maintainer "$env:USERPROFILE\.codex\skills\ai-project-maintainer" ``` 然后询问 Codex： ``` $ai-project-maintainer help me run the AI-assisted project intake interview. $ai-project-maintainer generate a production audit plan for this project, run the production gate, fix blockers, and rerun until it passes. ``` ## 源码检出命令 如果您直接使用此代码库而不是 npm： ``` node .\ai-project-maintainer\scripts\doctor.mjs node .\ai-project-maintainer\scripts\init-project.mjs "E:\my-project" --profile auto --ci github node .\ai-project-maintainer\scripts\init-audit.mjs "E:\my-project" --wizard node .\ai-project-maintainer\scripts\audit-plan.mjs "E:\my-project" --output reports/audit-plan.json node .\ai-project-maintainer\scripts\agent-risk.mjs "E:\my-project" --output reports/agent-risk-report.json node .\ai-project-maintainer\scripts\run-local-gate.mjs "E:\my-project" --production --agent-risk --strict --release --output reports/security-report.json node .\ai-project-maintainer\scripts\run-local-gate.mjs "E:\my-project" --production --connectors --agent-risk --strict --release --output reports/security-report.json node .\ai-project-maintainer\scripts\repair-pack.mjs "E:\my-project\reports\security-report.json" --project "E:\my-project" --output "E:\my-project\reports" node .\ai-project-maintainer\scripts\report-summary.mjs "E:\my-project\reports\security-report.json" ``` ## 本工具不包含的作用 本工具不能证明绝对的安全，不能替代人类对风险的责任归属，也不能免除高风险系统所需的最终审计。 它专为务实的中间地带而设计：使用 AI 编码的个人开发者或小型团队，拥有足够的流程来维护一个严肃的项目，而无需从零开始手动检查每一个细节。 ## 文档 - [演示](docs/DEMO.md) - [中文演示](docs/DEMO.zh-CN.md) - [真实 OSS 案例研究](docs/CASE-STUDIES.md) - [信任模型](TRUST.md) - [设计说明](DESIGN.md) - [发布信任](docs/RELEASE-TRUST.md) - [报告 schema](docs/REPORT-SCHEMA.md) - [安全策略](SECURITY.md) - [AI 修复包](docs/REPAIR-PACK.md) - [标准对照](docs/STANDARDS-CROSSWALK.md) - [生产证据连接器](docs/CONNECTORS.md) - [生产证据连接器](docs/CONNECTORS.zh-CN.md) - [实时连接器验证](docs/LIVE-CONNECTOR-VALIDATION.zh-CN.md) - [修复前后案例](docs/demo-output/before-after-case.md) - [安全工作流](docs/SECURITY-WORKFLOW.md) - [生产审计工作流](docs/PRODUCTION-AUDIT.zh-CN.md) - [Intake schema](docs/INTAKE-SCHEMA.zh-CN.md) - [安装指南](docs/INSTALL.zh-CN.md) - [GitHub Actions 指南](docs/CI-GITHUB-ACTIONS.zh-CN.md) - [策略与例外](docs/POLICY-AND-EXCEPTIONS.zh-CN.md) - [推广套件](docs/PROMOTION.md) ## 开发 ``` npm install npm test npm run check npm pack --dry-run ```

标签：AI辅助开发, GNU通用公共许可证, MITM代理, Node.js, 代码审查, 发布审核, 暗色界面, 自定义脚本