Metax CodeImprover

Metax CodeImprover 是一个面向开源维护者和项目开发者的本地代码审查、规范化和测试生成 Skill。它把维护者写在目标仓库 .codeimprover/ 下的 ARCHITECTURE.md、CODING_STANDARDS.md、TEST_REQUIREMENTS.md、RUNTIME_ENVIRONMENT.md 转成可执行的 AI 协作流程：先检查规则是否完整，再按指定 scope 审查代码，输出中文报告，必要时生成规范化 patch、测试 patch，并只运行白名单测试命令。

本项目主要由Gitee.AI 沐曦算力驱动

项目简介

Metax CodeImprover 解决的问题是让 AI 在维护者明确规则下工作：

规则先行：项目架构、编码规范、测试要求、运行环境必须先写清楚。
审查收敛：审查必须指定模块、目录、文件或 commit，不默认扩大范围。
修改保守：默认只生成报告和 patch，用户确认后才应用修改。
测试可控：测试生成依赖测试规则，测试运行只能使用白名单 profile。
日志可交付：模型调用日志、延迟、吞吐和测试日志可用于开发者查看。

Skill 功能说明

初始化规则文档：生成四个中文规则骨架，让维护者填写项目规则。
检查规则完整性：发现缺失、占位、空泛或关键章节不足时停止审查。
本地代码审查：审查当前工作区或指定 commit 的指定 scope。
规范化 patch：按规则生成代码整理建议和 patch，默认不落盘。
测试生成 patch：按测试要求生成测试代码 patch，默认不落盘。
白名单测试运行：读取 RUNTIME_ENVIRONMENT.md 中的 profile 并保存日志。
模型服务封装：通过 Gitee.AI / 沐曦 OpenAI 兼容接口调用大模型。
性能记录：默认记录模型调用延迟、成功率、字符吞吐等数据。

安装与部署

仓库内提供两套可安装 Skill：

Codex：skills/codex/metax-codeimprover/
Claude Code：skills/claude/metax-codeimprover/

安装到 Codex：

mkdir -p ~/.codex/skills
cp -r skills/codex/metax-codeimprover ~/.codex/skills/

安装到 Claude Code：

mkdir -p ~/.claude/skills
cp -r skills/claude/metax-codeimprover ~/.claude/skills/

安装后，普通用户优先用自然语言或 /metax-codeimprover 指令。底层 CLI 是 Skill 的执行细节，不作为主要使用入口。

如何使用?：1.自然语言

使用 Metax CodeImprover，帮我初始化这个仓库的规则文档。

使用 Metax CodeImprover，检查这个仓库的规则文档是否已经足够具体。

使用 Metax CodeImprover，审查当前工作区的 src/parser 模块，只给出审查报告，不要修改代码。

使用 Metax CodeImprover，按照项目规则审查最近这个 commit 的 src/parser 模块。

使用 Metax CodeImprover，根据刚才的审查建议生成规范化 patch，但先不要应用。

使用 Metax CodeImprover，根据 TEST_REQUIREMENTS.md 为 src/parser 生成测试代码 patch，不要越出这个模块。

使用 Metax CodeImprover，运行 RUNTIME_ENVIRONMENT.md 里声明的 unit-test 测试，并保存完整日志。

如何使用?：2.`/` 指令

/metax-codeimprover 初始化规则文档

/metax-codeimprover 检查规则文档

/metax-codeimprover 审查当前工作区 scope=src/parser

/metax-codeimprover 审查 commit=abcdef123 scope=src/parser

/metax-codeimprover 生成规范化 patch scope=src/parser dry-run

/metax-codeimprover 生成测试代码 scope=src/parser dry-run

/metax-codeimprover 运行测试 profile=unit-test

规则创建与填写

目标仓库根目录的 .codeimprover/ 目录需要四个规则文档：

.codeimprover/ARCHITECTURE.md：全局架构、局部模块架构、耦合接受度、兼容性边界、禁止设计。
.codeimprover/CODING_STANDARDS.md：命名、文件头注释、函数注释、函数内注释、防御性编程、Helper 拆分规则、编译脚本规范。
.codeimprover/TEST_REQUIREMENTS.md：测试环境、测试代码位置、测试类型要求、测试编排、性能测试、失败标准。
.codeimprover/RUNTIME_ENVIRONMENT.md：运行环境、测试 profiles、允许命令、日志要求、命令限制。

init-instructions 只生成纯骨架，并会把 .codeimprover/ 写入目标仓库 .gitignore。骨架不会扫描 README、源码、构建文件或测试入口；自动填充必须由用户单独明确触发。

规则必须具体到项目本身，不能只有“代码要清晰”“测试要充分”这类空泛描述。规则缺失、仍含占位内容、过短或关键章节未填写时，Metax CodeImprover 会停止审查并要求用户补全。

架构规则示例

## 局部模块架构

- 模块：`src/parser`
  - 职责：解析文本输入、归一化空白字符、返回稳定的数据结构。
  - 入口：公开 parse 函数、命令行输入适配层。
  - 出口：结构化解析结果、显式错误或空结果。
  - 允许依赖：标准库字符串处理、项目内错误类型、轻量工具函数。
  - 禁止依赖：网络、shell、全局可变状态、测试辅助代码。
  - 关键不变量：相同输入必须得到相同输出；空输入和非法输入必须有明确行为。

## 耦合接受度

兼容入口可以调用新实现，但新实现不得反向依赖兼容层。底层解析模块不得依赖上层业务流程。跨模块 helper 只有在两个以上生产调用方共享同一语义时才允许提升为公共 helper。

代码规范示例

## 文件头注释

只有承担模块入口或跨模块职责的文件需要文件头注释。文件头写文件职责、主要使用场景和重要注意事项；没有特殊注意事项就不写。

## 函数注释

公开函数、复杂函数、危险函数需要写函数注释。函数注释写函数作用、参数含义、返回值和调用注意事项。

## 函数内注释

for/while 循环只用一小行说明循环目的。复杂分支说明条件意义。锁、资源释放和边界修复必须说明安全前提。不要写大段复述代码的注释。

## 命名规则

Python 函数和变量使用 snake_case，类名使用 PascalCase，常量使用 SCREAMING_SNAKE_CASE。名字必须能表达语义，除项目内已有领域缩写外，不新增短缩写。

## Helper 拆分规则

简单流程保留在一个主函数中，用短注释分区。只有逻辑被两个以上生产调用方复用、或单段逻辑影响安全不变量时，才抽成命名明确的 helper。

测试规则示例

## 测试环境

普通单元测试在主机运行。需要隔离环境时使用容器或 CI profile。CI 只运行无网络、无外部服务依赖的 profile。

## 测试代码位置

parser 模块测试放在 `tests/parser/` 或项目既有测试目录。跨 CLI 行为测试放在 `tests/cli/`。生成测试不得放到生产路径外的临时目录。

## 测试类型要求

缺陷修复必须有回归测试。安全路径必须有负向测试。性能优化必须有 benchmark 或明确说明无法自动测量的原因。

## 测试编排

先运行编译检查，再运行模块单元测试；涉及性能改动时再运行 benchmark profile。所有 profile 必须来自 RUNTIME_ENVIRONMENT.md。

运行环境示例：

## 测试 Profiles

- unit-test: `python -m unittest discover -s tests`
  - 适用范围：默认单元测试
  - 超时：120 秒
  - 允许网络：否
  - 允许写文件：仅测试缓存和日志
  - 日志路径：runs/unit-test.log

## 日志要求

完整 stdout/stderr 写入日志文件。最终报告只展示结论、耗时、失败摘要和日志路径。性能测试需要额外记录样本规模、均值、波动范围和基线差异。

审查与修改流程

正式审查前先检查规则：

使用 Metax CodeImprover，检查规则文档是否完整、具体、可执行。

审查指定模块：

使用 Metax CodeImprover，审查当前工作区的 src/parser 模块，只输出报告。

审查报告会包含：

总体结论：pass、manual_review 或 fail。
审查范围和变更文件数。
规则章节逐项结论：按四份规则文档的二级标题输出 通过、不通过 或 需人工确认，并说明原因。
架构、兼容性、编码规范、错误处理、测试缺口等具体发现。
每个问题的路径、原因和建议。
是否建议修改，以及修改范围应该限制在哪里。

例如 CODING_STANDARDS.md 中写了 命名规则、目录和文件命名、类型和接口命名、Helper 拆分规则 等章节，报告会逐项给出类似结论：

命名规则：通过。当前 scope 未发现违反命名规则的新增证据。
目录和文件命名：通过。变更没有新增越界目录或不符合规则的文件。
Helper 拆分规则：需人工确认。新增 helper 调用链变长，但复用收益需要维护者判断。

如果代码已经足够好，报告会明确说明不建议修改。需要修改时，用户先要求生成 patch：

使用 Metax CodeImprover，根据刚才的审查结果，为 src/parser 生成规范化 patch，不要应用。

用户确认后再应用。适合自动规范化的内容包括清理行尾空白、移除占位注释、补充必要边界说明、小范围命名或格式调整。架构边界变化、兼容性语义变化、公开 API 行为变化必须人工确认。

测试生成与运行

生成测试代码前，TEST_REQUIREMENTS.md 必须写清楚测试范围、测试位置、测试框架、失败标准和禁止生成范围。

使用 Metax CodeImprover，根据 TEST_REQUIREMENTS.md，为 src/parser 生成测试代码 patch。先说明测试范围、测试思路和测试内容，不要直接应用。

测试运行只能使用 RUNTIME_ENVIRONMENT.md 中声明的白名单 profile：

使用 Metax CodeImprover，运行 unit-test 测试，并保存完整测试日志。

最终测试报告包含 profile 名称、白名单命令、成功状态、退出码、耗时、stdout/stderr 摘要、失败关键错误和日志路径。

模型与算力环境

项目使用 Gitee.AI / 沐曦模型服务。API Key 只通过环境变量或目标仓库本地 .codeimprover/.env 传入，不写入报告、不写入模型日志。

环境变量设置：

METAX_MODEL_API_KEY：Gitee.AI API Key。
METAX_MODEL_BASE_URL：默认 https://ai.gitee.com/v1。
METAX_MODEL_NAME：默认 MiniMax-M2.7。
METAX_MODEL_PROVIDER：默认 gitee-ai-muxi。
METAX_MODEL_STREAM：默认 true，使用 Gitee.AI chat/completions 流式输出，适合大上下文审查。
METAX_MODEL_TIMEOUT_SECONDS：模型请求超时秒数，默认 600，用于大上下文审查和测试生成。

也可以写入目标仓库本地 .codeimprover/.env。该文件中的 METAX_MODEL_* 会覆盖进程环境变量，适合不同仓库使用不同模型配置；.codeimprover/ 默认写入 .gitignore，避免 API Key 被提交。大仓库审查建议保留默认流式输出和 600 秒超时，或按模型服务稳定性继续调大。工具内部不会默认传入 max_tokens，除非开发者显式覆盖调用参数。

远端模型上下文边界

本地 agent 只向 Metax CodeImprover 脚本传入仓库路径、scope、commit/worktree 和文件路径。正式发送给远端模型的规则文件全文、被审查文件全文和 Git 行级 patch 必须由脚本按路径自动读取，不能由本地 agent 手动粘贴。

模型 prompt 会严格分成四块：

规则文件全量上下文：来自 .codeimprover/ 四个规则文档。
被审查文件全量上下文：来自用户指定 scope 内的实际文件。
Git 行级 Patch 上下文：来自当前工作区或指定 commit 的 diff。
本地模型补充区域：只允许承载用户本轮明确给出的额外目标或限制。

本地模型补充区域 不能粘贴规则全文、源码全文或 patch 全文，也不能替代前三类上下文。规则文件或被审查文件读取失败时，工具会 fail closed 并输出中文失败报告。

除 help 外，核心动作默认先调用 Gitee.AI / 沐曦模型；只有模型真实调用失败时才回退本地 agent，并在报告中写清失败原因。模型调用日志默认开启，会记录：

model-calls.jsonl：请求时间、响应时间、延迟、模型名、endpoint、成功/失败、截断 prompt、截断 response、错误信息。
performance.json：总调用次数、成功/失败次数、总延迟、平均延迟、最小/最大延迟、prompt 字符数、response 字符数、总字符数、字符吞吐。

每个固定动作结束时都会在报告末尾输出本轮模型调用信息，便于维护者排查：

## 模型调用统计

- 实际模型：`MiniMax-M2.7`
- 调用次数：`1`
- 成功 / 失败：`1` / `0`
- 平均延迟：`4810 ms`
- 本轮总 token：`175`

如果一次工作流连续执行多个动作，例如规则检查、审查、规范化、测试生成和测试运行，每个动作都会独立输出自己的调用统计；同时 model-calls.jsonl 和 performance.json 会保留可审计的完整调用记录。help 动作不会调用模型，统计中会显示 未调用模型、调用次数 0、总 token 0。

模型不可用、返回非法 JSON 或远端失败时，工具输出中文失败报告，并保留失败调用日志和性能统计。

示例输入输出

示例输入：

使用 Metax CodeImprover，审查当前工作区的 src/parser 模块，只给出审查报告，不要修改代码。

示例输出摘要：

结论：manual_review
范围：src/parser
发现：2 个中风险问题，1 个测试缺口

主要问题：
- src/parser/tokenizer.py：新增分支没有说明空输入行为，违反 ARCHITECTURE.md 的兼容性边界。
- src/parser/normalizer.py：helper 拆分过细，调用链增加但没有复用收益，违反 CODING_STANDARDS.md 的 Helper 拆分规则。

建议：
- 先补充空输入回归测试。
- 规范化 patch 可以只覆盖注释和 helper 命名，不建议自动调整公开 API。

测试生成示例输出：

测试范围：src/parser
测试思路：覆盖空输入、非法参数、分隔符边界和回归样例
生成文件：tests/parser/test_tokenizer_regression.py
状态：dry-run patch 已生成，等待用户确认应用

测试运行示例输出：

profile：unit-test
命令：来自 RUNTIME_ENVIRONMENT.md 白名单
状态：通过
退出码：0
耗时：4.31s
完整日志：runs/unit-test.log

测试过程

真实模型验证过程：

创建临时日志目录。
通过环境变量配置 METAX_MODEL_API_KEY、METAX_MODEL_BASE_URL、METAX_MODEL_NAME、METAX_MODEL_PROVIDER。
调用 Gitee.AI MiniMax-M2.7 的 chat/completions 接口完成一次真实响应。
检查 /tmp 下生成的 model-calls.jsonl 和 performance.json。
确认日志包含延迟和吞吐指标。

安全边界

规则文档不完整时停止，不进行自由发挥。
默认只生成报告和 patch，不直接改代码。
用户明确确认后才应用 patch。
所有代码修改必须限制在用户指定 scope 内。
运行命令只能来自 RUNTIME_ENVIRONMENT.md 白名单。
模型不能发明 shell 命令，也不能越权运行命令。
模型调用失败时输出中文失败报告，不编造测试代码。
API Key 不写入仓库、报告、日志样例或最终提交。