YoavLax/AI-Repo-Analyzer

# AI Readiness Analyzer **为 GitHub Copilot 和 Claude Code 仓库配置提供确定性的 AI 就绪度评分。** 将其指向某个仓库，即可获得可复现的分数、字母等级，以及按优先级排序的具体修复建议列表——所有结果完全通过静态分析计算，评分路径中不包含任何模型调用。输入相同的 commit，每次都会输出字节级完全一致的报告。 [](https://github.com/YoavLax/AI-Repo-Analyzer/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) ## 为什么开发此工具 如今的仓库通常会内置专为 AI 编程 agent 设计的配置——例如 `copilot-instructions.md`、`CLAUDE.md`、`AGENTS.md`、`SKILL.md` 文件、自定义 agent、路径作用域指令、hooks 以及 MCP server。然而，这些配置是否真正*起作用*往往无从得知，直到 agent 悄无声息地无法加载某个 skill、忽略了一份长达 900 行的指令文件，或者因其描述过于模糊而根本未触发该 skill。 AI Readiness Analyzer 旨在回答“这个仓库真的准备好迎接 AI agent 了吗？”这一问题，就像 linter 回答“这段代码能否编译通过”一样——具有确定性、完全离线，并且为每一个问题提供具体的文件和行号。 ## 检查内容 八大支柱，94 条规则（[完整目录](docs/RULES.md)）： | 支柱 | 权重 | 覆盖范围 | |---|---|---| | Foundation（基础） | 20 | 入口点存在且可解析；`AGENTS.md`↔`CLAUDE.md` 桥接；长度与结构；章节覆盖率；`@import` 解析 | | Instruction quality（指令质量） | 15 | 具体、有理有据、有示例的指令；无样板内容、陈旧标记或形似凭据的字符串；命令与链接可解析 | | Context scoping（上下文作用域） | 12 | 路径作用域的 `*.instructions.md`；缺失 `applyTo` 导致的静默失效；无效 glob；单体检测 | | Skills（技能） | 15 | 完整的 [Agent Skills](https://agentskills.io) 验证集：frontmatter、目录名不匹配导致静默丢失的陷阱、描述质量（0–100）、token 预算、CWE-59 引用转义、渐进式披露 | | Agents & prompts（Agent 与提示词） | 10 | 自定义 agent 的 frontmatter、描述质量、最小权限 `tools`、prompt→agent 引用解析 | | Verification（验证） | 12 | 已记录且**可解析**的测试/构建/lint 命令；CI；“迭代至通过”与“出示证据”的指令；hooks schema | | Tooling（工具链） | 8 | MCP 配置的有效性与密钥间接访问；安装脚本；devcontainer；版本锁定 | | Safety（安全性） | 8 | 已提交的个人文件；绕过权限的设置；settings/MCP 中的密钥；`curl \| sh` 注入面 | ## 快速开始 ``` git clone https://github.com/YoavLax/AI-Repo-Analyzer.git cd AI-Repo-Analyzer python -m venv .venv # Windows: .venv\Scripts\activate | macOS/Linux: source .venv/bin/activate pip install -e . airx analyze /path/to/some/repo ``` PATH 也可以是远程仓库——GitHub 的 `owner/repo` 简写或任何 git clone URL（`https://`、`ssh://`、`git@host:...`）。它会以浅克隆方式被克隆到临时目录进行分析，并在分析完成后删除；要求在 PATH 中存在 `git`。 ``` airx analyze YoavLax/AI-Repo-Analyzer airx analyze https://github.com/YoavLax/AI-Repo-Analyzer.git --ref main ``` ``` AI Readiness Analyzer — /path/to/some/repo Overall score: 61.1/100 Grade: D Platforms: copilot 62.5 claude 61.1 parity delta 1.4 Pillars: foundation 86.4% (presence 100.0%, quality 77.3%, weight 20, 9 rules) skills 99.8% (presence 100.0%, quality 99.6%, weight 15, 37 rules) ... Findings (20): [error ] skills.name.dirname-match .github/skills/deploy/SKILL.md Name 'deployer' does not match parent directory 'deploy'. VS Code/Copilot silently fails to load this skill. Top fixes (estimated score gain): 1. +4.8 [additive ] verify.test-command.documented Document the repository's test command in an entry point so agents can verify their work. ``` ### CI 用法 ``` airx analyze . --format json -o report.json # canonical machine output airx analyze . --format sarif -o airx.sarif # GitHub code scanning airx analyze . --format md # PR comment / job summary airx analyze . --min-score 70 --fail-on error # quality gate airx compare baseline.json report.json # exit 1 on regression ``` 退出代码：`0` 通过 · `1` 门控失败 · `2` 输入/配置错误 · `3` 内部错误。 ### 配置（`.airx.yml`） `airx init` 会构建基础配置： ``` profile: standard # or: minimal, enterprise (weight profiles) min_score: 70 fail_on: error ignore: - skills.compat.unverified waivers: - rule: skills.present reason: "Domain knowledge lives in an internal plugin marketplace." expires: "2027-01-01" approved_by: platform-team ``` 被豁免的规则会按满足要求计分，但在报告中保持可见。豁免期只会根据显式指定的日期（`--today 2026-07-29` 或 `AIRX_TODAY`）进行评估——评分路径从不读取系统时钟，因此输出结果始终保持可复现性。 ## AgentCompass — Web UI **AgentCompass** —— 您探寻“AI Agent 就绪”仓库的指南针。在浏览器中粘贴公开的 GitHub 仓库 URL，即可获得完整的报告：总体得分与等级、Copilot/Claude 平台进度条、按支柱划分的细分数据、可筛选的检查结果，以及按优先级排序的首要修复建议。 **Copilot / Claude Code / All** 切换开关可将报告限定在某个特定 agent 框架内，这样仅使用 Claude Code（或仅使用 Copilot）的团队就不会因为不使用的框架规则而被扣分。此选择会在重新分析时保留，并体现在可分享的 URL 中（`?platform=claude`）。 扫描是**免克隆**的：一次 GitHub Trees API 调用即可列出仓库中的所有文件，且只会获取规则真正需要读取的文件（分类的 AI 制品、四个探测文件、skill 目录）——数量是 KB 级别，而不是整个仓库。仅通过名称判断的规则会查看完整列表，内容规则则会查看真实文件，并且整个快照都被固定在单一的 commit SHA 上。数据不会被持久化保存；每个请求都是独立的。 ### 运行 ``` docker compose up # then open http://localhost:8080 ``` 或者不使用 Docker： ``` pip install -e ".[dev]" # server deps (or ".[web]" for runtime only) cd web && npm install && npm run build # → web/dist cd .. && STATIC_DIR=web/dist uvicorn airx_server.app:app --port 8080 ``` ### 服务器配置 所有配置均通过环境变量指定： | 变量 | 默认值 | 用途 | |---|---|---| | `GITHUB_TOKEN` | 未设置 | 用于在线扫描 GitHub API 调用的 token（将速率限制从 60 次请求/小时提高到 5,000 次/小时）；仅发送至 `api.github.com` | | `ALLOW_LOCAL_PATHS` | `false` | 启用对挂载在服务器上的仓库进行分析（local-path 模式） | | `LOCAL_REPOS_ROOT` | 未设置 | local-path 分析被严格限制的根目录 | | `STATIC_DIR` | 未设置 | 构建好的 SPA（`web/dist`）所在的待服务目录 | | `MAX_CONCURRENT_ANALYSES` | `4` | 同时分析数量的上限 | | `MAX_FETCH_FILES` | `400` | 在线扫描时每个仓库抓取的分类 AI 制品文件上限；调高此值可分析更大的仓库（无需 local-path 模式） | | `MAX_FILE_BYTES` | `2097152` (2 MB) | 在线扫描的单文件大小上限（以字节为单位） | | `MAX_TOTAL_BYTES` | `20971520` (20 MB) | 在线扫描的总抓取大小上限（以字节为单位） | ### API - `POST /api/analyze`（参数 `{"source": "", "ref": null}`） ——或者在 local-path 模式下使用 `{"path": ""}`——返回标准的 JSON 报告以及一个 `meta` 块（`source`、`ref`、`resolved_sha`、`listed_files`、`fetched_files`、`duration_ms`）。错误将以 `{"error": {"code", "message"}}` 的形式返回，并带有 `400`/`404`/`413`/`422`/`429` 状态码。 可选的 `"platform": "copilot"|"claude"|"all"` 字段可将评分范围限定在特定平台的规则上（默认 `"all"`），与 CLI 的 `--platform` 标志作用相同；应用的值将作为报告顶层的 `platform` 键回显。 - `GET /api/health` —— 存活检查。`GET /api/version` —— 返回 `{version, local_mode}`。 ### 私有仓库 在线扫描仅能访问公开的 GitHub。对于私有代码，请在您的仓库旁自托管 AgentCompass：将它们以只读方式挂载到容器中，设置 `ALLOW_LOCAL_PATHS=true` 和 `LOCAL_REPOS_ROOT`，并通过相对路径进行分析——分析过程本身绝不接触网络。用于 Kubernetes 部署的 Helm chart 位于 `deploy/helm/agentcompass`；有关这两种设置方式，请参见 [`deploy/README.md`](deploy/README.md)。 ## 工作原理 ``` path → fs.scan deterministic, symlink-free traversal → discovery declarative artifact patterns (skills, agents, prompts, instructions, hooks, MCP, settings — see src/airx/patterns.py) → probe repo facts: test/build/lint evidence, CI, hygiene → rules/* 94 pure functions, one per check, in a versioned registry → scoring presence/quality split per pillar, platform sub-scores, profiles, waivers, grade banding → report/* terminal | json | markdown | sarif + ranked remediation plan ``` 每一条规则都是其输入的纯函数。在整个评分路径中，没有模型调用、没有网络访问，也不依赖任何系统时间或环境因素——请参阅 [`plan.md`](plan.md) §3 了解确定性契约，以及 `tests/test_determinism.py` 了解其强制执行方式。 ## 评分模型简介 每个支柱都分为**存在性**得分（相关制品是否存在？）和**质量**得分（质量如何？），计算公式为 `0.4 × 存在性 + 0.6 × 质量`。这使得得分能够抵御双向作弊：删除所有 skill 的得分比拥有一个有缺陷的 skill 得分*更糟*，而复制平庸的 skill 并不会虚高分数（因为这是平均值，而不是求和）。不适用的规则会从分子和分母中同时移除；一个完全没有适用内容的支柱将被排除在加权总分之外，而不是获得空洞的 100% 满分。 **任何具有错误严重程度的检查结果都会将总评级限制在最高 C**，不管算术得分如何——而且“错误”严重程度仅保留给客观的、可通过规范验证的失败情况（例如 skill 静默加载失败、提交了凭据），绝不会用于风格启发式评估。这种限制永远不会*提高*已经较差的评级。 | 得分 | 等级 | 含义 | |---|---|---| | 90–100 | A | 原生适配 Agent | | 80–89 | B | 准备就绪 | | 70–79 | C | 具备能力 | | 55–69 | D | 部分配置 | | 35–54 | E | 最低配置 | | 0–34 | F | 尚未就绪 | 每条规则都带有平台标签，因此报告还会包含单独的 `copilot` 和 `claude` 分数以及它们的**平价差异**——如果没有 `CLAUDE.md` 桥接，内容丰富的 `AGENTS.md` 将直接显示为 Copilot/Claude 之间的差距，而不仅仅是一条被埋没的警告。 ## 命令 ``` airx analyze PATH [--format terminal|json|md|sarif] [-o FILE] [--html [FILE]] [--profile minimal|standard|enterprise] [--platform copilot|claude|all] [--min-score N] [--fail-on error|warning|never] [--ignore PREFIX]... [--no-waivers] [--today YYYY-MM-DD] [--ref BRANCH|TAG|COMMIT] # remote PATH only airx rules [--format terminal|json|md] # the catalog; generates docs/RULES.md airx compare OLD.json NEW.json # regression diff for CI airx init [--force] # scaffold .airx.yml ``` `PATH` 可以是本地目录、GitHub 的 `owner/repo` 简写或任何 git clone URL——远程仓库会被浅克隆到临时目录，并在分析完成后清理掉。 `--html [FILE]` 额外生成一份独立、离线的 HTML 报告，其中包含可折叠的章节（支柱、按严重程度排列的检查结果、首要修复建议、豁免、清单）——如果未提供 `FILE`，默认路径为 `airx-report.html`。 ## 尚未实现的功能 复合 GitHub Action、`airx fix`、重复检测以及嵌套 monorepo 聚合——请参阅 [`plan.md`](plan.md) §12 和 [`plan-v2-fable.md`](plan-v2-fable.md) §1 了解开发时序。 ## 安全 请参阅 [`SECURITY.md`](SECURITY.md) 了解威胁模型以及如何报告漏洞。 ## 致谢 `SKILL.md` 的验证规则及其阈值源自 [AgentEval](https://github.com/YoavLax/AgentEval)（MIT 许可证）。规则目录提取自已发布的 [Agent Skills 规范](https://agentskills.io)、[Claude Code 文档](https://code.claude.com/docs/en/best-practices) 以及 [GitHub Copilot 自定义指令指南](https://github.blog/ai-and-ml/github-copilot/5-tips-for-writing-better-custom-instructions-for-copilot/)——完整的参考文献请参阅 [`plan.md`](plan.md) §15。 ## 许可证 [MIT](LICENSE) © 2026 Yoav Lax

标签：AI辅助编程, Python, SOC Prime, 云安全监控, 开发工具, 无后门, 请求拦截, 逆向工具, 静态分析