Metax CodeImprover

Metax CodeImprover 是一个面向开源维护者和项目开发者的本地代码审查与 AI 协作工具。

它把远端模型和本地 Agent 分成两个明确角色：

远端模型是大脑，读取完整项目规则、源码和 Git diff，一次性返回详细任务。
本地 Agent 是“执行者”，按任务直接修改代码、补充测试并验证结果。

本项目主要由 Gitee.AI 沐曦算力驱动,完全支持giteeai的模型接入。

演示视频

百度网盘：https://pan.baidu.com/s/1KqKhAZ2VSrkdGeEZd6839A?pwd=6666
提取码：6666

核心架构

+-------------------------+
| 用户 / 维护者           |
+------------+------------+
             |
             v
+-------------------------+
| Codex / Claude Code     |
| 识别固定动作与参数      |
+------------+------------+
             |
             v
+-------------------------+
| metax-codeimprover-action |
| request.json 参数校验   |
+------------+------------+
             |
       +-----+------+
       |            |
       v            v
+-------------+  +------------------+
| 项目规则    |  | 源码 / Git diff |
| .codeimprover |  | scope / files   |
+------+------+  +---------+--------+
       |                   |
       +---------+---------+
                 |
                 v
+-----------------------------------+
| 规划：远端一次性返回完整任务      |
+----------------+------------------+
                 |
                 v
+-----------------------------------+
| 修改：本地 Agent 直接编辑与验证   |
+----------------+------------------+
                 |
        +--------+---------+
        |                  |
        v                  v
 无需反馈，结束       反馈远端复核
                           |
                    纠正任务或结束

安装

第一步：安装 Agent 工具

先在对应的编辑器或终端中安装并登录一个本地 Agent 工具：

Codex
Claude Code

后续操作都通过 Codex 或 Claude Code 的自然语言对话完成，不需要用户手工编写任务 JSON，也不需要手工应用 patch。

第二步：安装 Metax CodeImprover Skill

仓库包含两套可移植 Skill：

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

在本仓库根目录安装 Codex 版本：

mkdir -p ~/.codex/skills
rm -rf ~/.codex/skills/metax-codeimprover
cp -r skills/codex/metax-codeimprover ~/.codex/skills/
chmod +x ~/.codex/skills/metax-codeimprover/bin/metax-codeimprover-action

安装 Claude Code 版本：

mkdir -p ~/.claude/skills
rm -rf ~/.claude/skills/metax-codeimprover
cp -r skills/claude/metax-codeimprover ~/.claude/skills/
chmod +x ~/.claude/skills/metax-codeimprover/bin/metax-codeimprover-action

安装完成后，重新开启一次 Codex 或 Claude Code 会话，使新 Skill 生效。

可选：创建全局命令入口。

mkdir -p ~/.local/bin
ln -sfn ~/.codex/skills/metax-codeimprover/bin/metax-codeimprover-action ~/.local/bin/metax-codeimprover-action

使用教程

进入需要处理的目标项目，在 Codex 或 Claude Code 中直接使用自然语言描述需求。Agent 会识别 Metax CodeImprover 的固定动作，准备 .codeimprover/request.json，调用对应动作并继续完成后续流程。

首次接入一个项目时，推荐按以下顺序使用：

骨架搭建：创建四份项目规则文档骨架。
自动填充：让远端模型结合仓库内容生成规则草案。
维护者确认并修正规则文档。
规则检查：确认规则完整、具体且可执行。
使用 审核 检查代码，或使用 规划 生成修改任务。
使用 修改 让本地 Agent 按任务直接编辑代码和测试。
需要远端确认时使用 反馈 完成闭环。
使用 测试运行 执行规则中声明的白名单测试 profile。

支持以下自然语言指令。

指令 1：骨架搭建

为当前项目创建 .codeimprover/ 规则骨架，不扫描仓库，也不自动填写规则。

请使用 metax-codeimprover 为当前项目搭建规则骨架。

指令 2：自动填充

读取当前仓库，让远端模型生成待维护者确认的规则草案。

请使用 metax-codeimprover 自动填充当前项目的规则文档。

指令 3：规则检查

检查四份规则文档是否缺少章节、包含占位内容或描述过于空泛。

请检查当前项目的 metax-codeimprover 规则是否完整可用。

指令 4：审核

按照已确认的项目规则审核指定范围或当前工作区。审核只输出问题和建议，不修改代码。

请使用 metax-codeimprover 审核 src/parser 当前工作区的修改。

也可以审核指定提交：

请审核提交 abcdef123 中 src/parser 的改动。

指令 5：规划

把规则、源码和 Git diff 交给远端模型，由远端一次性返回完整任务列表。规划阶段不会修改代码。

请使用 metax-codeimprover 规划 src/parser 的代码修改任务。

需要额外上下文时，可以直接点名文件：

请规划 src/parser 的修改，并同时参考 include/parser_api.h。

指令 6：修改

让本地 Agent 按当前 tasks.json 的任务顺序直接编辑代码、补充测试并执行任务要求的验证。

请按照刚才的 metax-codeimprover 规划执行全部修改和测试。

本地 Agent 不会要求远端返回代码 diff，也不会通过脚本执行 git apply。

指令 7：反馈

将任务完成情况、当前源码和最新 Git diff 交给远端复核。远端可以确认完成，也可以一次性返回新的纠正任务。

请把当前 metax-codeimprover 任务的执行结果反馈给远端模型。

当任务出现 blocked、failed，或计划要求远端复核时，必须执行反馈。

指令 8：测试运行

只运行 RUNTIME_ENVIRONMENT.md 中已经声明的白名单 profile。

请使用 metax-codeimprover 运行 unit-test 测试 profile。

未在规则中声明的命令不会被执行。

模型配置

.codeimprover/.env 支持：

METAX_MODEL_BASE_URL=https://ai.gitee.com/v1
METAX_MODEL_API_KEY=
METAX_MODEL_NAME=MiniMax-M2.7
METAX_MODEL_PROVIDER=gitee-ai
METAX_MODEL_TIMEOUT_SECONDS=600
METAX_MODEL_STREAM=true
METAX_MODEL_BYPASS_PROXY=true
METAX_MODEL_MAX_RETRIES=2
METAX_MODEL_MAX_TOKENS=10000
METAX_MODEL_TEMPERATURE=0.7
METAX_MODEL_RESPONSE_FORMAT=json_schema
METAX_MODEL_LOOP_LIMIT=10
METAX_MODEL_LOOP_MAX_FILE_CHARS=20000
METAX_MODEL_LOOP_MAX_TOTAL_CHARS=120000

.codeimprover/.env 优先于进程环境变量。API Key 不得打印或提交。

输出与日志

主要产物：

.codeimprover/outputs/tasks.json
.codeimprover/outputs/task-state/{plan_id}.json
.codeimprover/outputs/review-summary.md
.codeimprover/outputs/review-detail.md
.codeimprover/outputs/test-run.md
.codeimprover/calllog/YYYYMMDD/{sessionid}/model-calls.jsonl
.codeimprover/calllog/YYYYMMDD/{sessionid}/performance.json
.codeimprover/calllog/YYYYMMDD/{sessionid}/log.txt
.codeimprover/calllog/YYYYMMDD/{sessionid}/loop-state.json

规划和反馈记录远端模型统计。
修改不调用远端模型，统计明确显示未调用模型。
日志包含完整 prompt、模型响应、延迟和 token，但会隐藏 API Key。

License

Apache-2.0