AI Maturity ScannerAI 编程成熟度本地 CLI
中文EN

Docs

安装、运行、导出报告。

AI Maturity Scanner 是独立 Node.js CLI。需要 Node 22+，并且本机可以访问 git。

常用工作流

按报告用途选择命令：图片适合分享，Markdown 适合文档和 PR，JSON 适合自动化流程。

默认生成图片报告

# 扫描当前目录，并生成 ./ai-maturity-report.png
ai-maturity-scanner

扫描指定仓库

# 扫描 ./my-repo，并生成默认 PNG 图片报告
ai-maturity-scanner ./my-repo

导出 Markdown 报告

# 适合复制到文档、Issue 或 PR 评论
ai-maturity-scanner ./my-repo --format md --out report.md

导出 JSON 给自动化流程

# 适合 CI、看板或阈值检查
ai-maturity-scanner ./my-repo --format json --out report.json

生成英文报告

# 报告内容使用英文
ai-maturity-scanner ./my-repo --lang en

Spec 文件配置

扫描器默认把仓库内 specs/ 目录下的 Markdown 文件识别为 spec 文档。如果你的 spec 放在别的位置（如 docs/specs/、design/），可以用仓库根目录的配置文件或 --spec-glob 参数自定义匹配规则。优先级：--spec-glob 参数 > 配置文件 > 默认值。

在仓库根目录放置 .ai-maturity-scanner.json，用 specGlobs 指定一个或多个 glob：

{
  "specGlobs": [
    "docs/specs/**/*.md",
    "design/**/*.md"
  ]
}

或用 --spec-glob 参数临时指定（可重复，会覆盖配置文件）：

# 只把 docs/specs 下的 Markdown 当作 spec
ai-maturity-scanner ./my-repo --spec-glob 'docs/specs/**/*.md'

未提供任何配置时使用默认 glob **/specs/**/*.md（任意深度的 specs/ 目录，仅 Markdown：.md/.mdx/.mdc）。

  • glob 使用正斜杠 / 作为路径分隔符（与 .gitignore、tsconfig 等一致），Windows 上也请用 /。
  • 配置文件解析失败或字段类型不符时，扫描器会打印警告并回退到默认值，不会中断扫描。
  • spec 配置只影响报告里的文件分组归类，不影响 AMI 分数与等级。

MCP 支持边界

MCP 配置在不同代码助手之间没有统一的仓库级格式，因此当前识别能力仍不完善。现阶段只把 Claude Code 的项目级 .mcp.json / mcp.json 和 Codex 的项目级 .codex/config.toml 作为明确支持的 MCP 配置来源。

  • Claude Code: .mcp.json / mcp.json
  • Codex: .codex/config.toml

其他工具也可能支持 MCP，但配置路径、字段和优先级差异较大，公开文档完整度也不一致。为避免误报，扫描器不会把这些格式当作稳定支持项。

评分参考

这一节保留算法细节，方便核对实现和阈值。只想理解报告含义时，可以直接阅读 Metrics 页面。

归一化

raw metric 通过线性饱和映射到 0–100 分：未达 cap 时按比例线性增长，达到或超过 cap 即 100 分。

score = min(raw, cap) / cap × 100

封顶值（caps）

指标封顶 cap
skill_count30
skill_line_count15000
advanced_skill_count10
skill_resource_count30
agent_count10
agent_line_count2000
command_count10
command_line_count2000
mcp_count3
ai_instruction_files1
specs_file_count50
specs_line_count5000
subproject_coverage5

特殊归一化

instruction_max_line_count

按分段计分（非线性）：0 行→10 分，0–20 行→10–30，20–50 行→30–100，50–400 行→100（最佳区间），400–1000 行→100–30，超过 1000 行→10。

skill_engineering_rate

rate = advanced_skill_count / skill_count（skill_count 为 0 时记 0）；rate 达到 0.50 即 100 分。

AMI 加权

归一化后的指标先汇总成三个维度，再加权得到 0–100 的 AMI 分数（保留两位小数）。

维度汇总

configuration_depth60%

skill、agent、command、mcp 四个 subscore 的均值。

context_richness30%

ai_instruction_files、instruction_max_line_count、specs_file_count、specs_line_count 的均值。

integration_breadth10%

normalized subproject_coverage。

configuration_depth 的 subscore 分组

  • skill subscore = skill_count、skill_line_count、advanced_skill_count、skill_engineering_rate、skill_resource_count 的均值
  • agent subscore = agent_count、agent_line_count 的均值
  • command subscore = command_count、command_line_count 的均值
  • mcp subscore = mcp_count

AMI 公式

AMI = configuration_depth × 0.6 + context_richness × 0.3 + integration_breadth × 0.1
L0–L4 等级算法

以下 5 个指标参与 L0–L4 判定。其中 ability_applied 与 skill_engineering_rate 由其他 raw metrics 派生得到，需要先单独计算；其余三个是扫描时直接统计的原始计数。

派生指标

ability_applied= skill + skill_resource + agent + command + mcp

已应用的能力资产总数，config 与 hook 不计入。

例: skill=3、skill_resource=2、agent=1、command=1、mcp=0 → ability_applied = 3+2+1+1+0 = 7

skill_engineering_rate= advanced_skill_count / skill_count

advanced skill 占全部 skill 的比例；skill_count 为 0 时记为 0。

例: advanced_skill=3、skill=10 → skill_engineering_rate = 3/10 = 0.30

原始计数

advanced_skill

目录中带有脚本的 skill 数量。

specs_files

被识别为 spec 的 Markdown 文件数量。

ai_instruction_files

仓库中 AI instruction file 的数量。

成熟度等级由一组阈值级联判定：先检查 L0 这个门槛，再从 L4 向下逐级比较，命中第一个全部满足的等级即返回，都不满足则落到 L1。各指标含义见上一节「等级判定指标」。

等级判定条件（自上而下，首个满足即返回）
L0
ai_instruction_files<1
L4
ability_applied≥25且skill_engineering_rate≥0.40且specs_files≥20
L3
ability_applied≥15且advanced_skill≥2且skill_engineering_rate≥0.15且specs_files≥10
L2
ability_applied≥8且advanced_skill≥1
L1
默认：以上条件均不满足时返回 L1。

Repository profile

协作画像说明

协作画像描述仓库中最突出的 AI 协作资产形态。它不是新的成熟度等级，也不评价开发者能力、实际使用频率或代码质量。

Primary（主画像）

每份报告恰好有一个主画像；它是当前最强、最能代表仓库的协作形态。

静待启程

unstarted

中性起点：尚未发现 AI 指令文件。

ai_instruction_files = 0

协作萌芽

early-collaboration

已经出现基础协作信号，尚未形成更突出的资产形态。

存在 AI 指令文件，但没有 specialized primary 合格

AI 协作中枢

ai-operating-system

广度和均衡性都很强的协作系统。

configuration_depth、context_richness、integration_breadth 均 ≥ 60，且四类能力中至少三类非零

技能工坊

skill-workshop

可复用且工程化的 skills 是最突出的可见资产。

skill_score ≥ 50，且 skill_engineering_rate ≥ 0.15

多代理剧团

agent-troupe

明确分工的多个 agent 角色构成了显著协作模式。

agent_count ≥ 3，且 agent_type_distinct ≥ 3

命令指挥台

command-center

可复用命令是主要的交互入口。

command_score ≥ 40，且 command_count ≥ 3

上下文图书馆

knowledge-library

规格与实质性 AI 上下文共同构成最突出的协作资产。

specs_file_count ≥ 20，context_richness ≥ 65，instruction_max_line_count ≥ 50，且 spec_library_score ≥ 50

Traits（特征）

每个特征按程度（0–100）计算 degree，再用统一的 40/70 门槛划分为 高/中/低 三档；报告展示 degree 最高的三个特征，与主画像语义重复的特征会被抑制。完全没有相关资产的特征记为「低」。

能力工程化

engineered-skills

若主画像为 skill-workshop 则不重复显示。

degree = mean(advanced_skill_count, skill_engineering_rate)

多代理协作

multi-agent

若主画像为 agent-troupe 则不重复显示。

degree = mean(agent_count, agent_role_score)

工具深连

tool-connected

MCP 信号始终作为特征，不会成为主画像。

degree = mcp_count

上下文成册

structured-context

若主画像为 knowledge-library 则不重复显示。

degree = mean(instruction_max_line_count, specs_file_count)

跨项目覆盖

cross-project

跨子项目覆盖始终作为特征，不会成为主画像。

degree = subproject_coverage

如何选择并解释画像

  1. 仅复用报告已有的 raw metrics、normalized metrics 和三个维度；不会采集或推断新的行为数据。
  2. 没有 AI instruction file 时，主画像固定为 unstarted；其余仓库先判断各 specialized primary 是否满足资格条件。
  3. 合格主画像候选按超出资格门槛后的 strength 比较，强度四舍五入到两位小数，相同强度才按固定顺序决胜；每个特征按 degree 排序取前三展示，degree 用统一 40/70 门槛分为 高/中/低。
  4. 报告会保留匹配 rule ID、metric facts、候选的 headroom components、rounded strength 与 selected 状态，便于比较主画像和备选项。

和 AMI、L0–L4 的关系

AMI 与 L0–L4 继续回答“沉淀了多少 AI 协作基础设施”和“成熟度处于哪个门槛”。协作画像回答“最显著的协作形态是什么”。它是附加信息，不会改变 raw metrics、normalized metrics、三个维度、AMI 分数或 L0–L4 结果。

命令行参考

格式、输出路径、语言、隐私模式和 spec 匹配规则都在这里统一说明。报告格式不再单独成段，避免和参数表重复。

FlagValuesDefault说明
[path]repository path.要扫描的 git 仓库路径；省略时扫描当前目录。
-f, --format <format>png | terminal | md | jsonpng选择报告格式：图片、终端文本、Markdown 或 JSON。
-o, --out <file>file pathPNG 为 ai-maturity-report.png；文本为 stdout把报告写入指定文件。文本格式未设置 --out 时输出到 stdout。
-l, --lang <lang>zh | enzh选择报告语言。
-V, --versionbooleanfalse输出当前包版本号后退出，不扫描仓库。
--redactedbooleanfalse隐私模式：PNG 报告隐藏仓库地址显示字段。
--verbosebooleanfalse当主输出写入文件时，同时在 stdout 打印 terminal 报告。
-g, --spec-glob <glob>glob (repeatable)**/specs/**/*.md自定义 spec 文件匹配规则；可重复，优先级高于配置文件。

子命令

verify-image <file>

校验生成的 PNG 报告中隐藏的图片指纹元数据。