From 7e1c8ea2bee21c7128a5d45a8dabf4f6394f9417 Mon Sep 17 00:00:00 2001 From: tzhouam Date: Tue, 25 Aug 2026 11:16:39 +0800 Subject: [PATCH 1/6] docs: rewrite README as project intro with three quick starts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructure the README from a Direct-skill catalog into a project introduction plus quick starts for the three core workflows: - Review: Direct (imreview) and Strict CLI side by side, with the snapshot-freeze flow and the post/ALLOW_POST double gate. - Rebase: previously absent from the README entirely — PR rebase via the CLI (conflict escalation, push double gate, with-lease only) and the locked repo-rebase nightly playbook. - Knowledge update: imupdate release audit, manual contributions via CONTRIBUTING plus the two validators, and the profile/skills candidate channels. The Direct-vs-Strict table, safety defaults, doc map, and the MCP tool reference (kept in compact form — doc/guide/mcp.md only covers installation) survive; imdesign/imcifix move to a short "other capabilities" list. The repo-neutrality claim is stated as enforced by the guardrail test with a shrink-only leak cap, not as an absolute. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EFomsSerZ41AX1kajBK13g --- README.md | 302 ++++++++++++++++++++++-------------------------------- 1 file changed, 122 insertions(+), 180 deletions(-) diff --git a/README.md b/README.md index b47b0e12b..f0a1871da 100644 --- a/README.md +++ b/README.md @@ -1,257 +1,199 @@ # InferMatrixCopilot -让 Codex、Claude Code、Cursor 等 Coding Agent 按 **vLLM-Omni 的项目知识** -审查代码，并在上游版本变化后更新这套知识。 +**Playbook 驱动的仓库维护 copilot**：用一条自然语言命令审查 PR、rebase 分支、 +调试 CI、回答 issue，并维护一套随上游发版持续更新的仓库知识。vLLM-Omni 是 +第一个目标仓库（adapter zero），但核心与仓库解耦——新仓库通过 +`adapters//` 与 `knowledge/` 接入，不需要改 `src/`（仓库中立由护栏 +测试强制，已知遗留泄漏被清单封顶且只能变少）。 -它主要解决两个问题： +一个仓库，两种形态，共享同一套知识与治理： -- `imreview`：审查 PR 或本地改动时，让 Agent 知道相关模型、组件和维护者规则， - 不只做一遍通用代码检查。 -- `imdesign`：写代码前先围绕 issue、PR 或粗略需求做协同设计，产出方案、边界和验证计划。 -- `imcifix`：从 GitHub issue 出发，让 Agent 在本地复现、修复并验证补丁。 -- `imupdate`：vLLM-Omni 发版或目录变化后，对比新旧版本，更新 - InferMatrixCopilot 中容易过期的模型清单、registry、deploy、路径路由和 source pin。 +| | **Direct（默认）** | **Strict / CLI** | +|---|---|---| +| 谁读代码 | 你当前 Coding Agent（Codex / Claude Code / Cursor）自己的模型 | InferMatrixCopilot 配置的模型 | +| 入口 | `/imreview` `/imdesign` `/imcifix` `/imupdate` | `infermatrix-copilot -p "…"` | +| 服务端跑模型 | 否（零模型、零状态，同步返回知识路由与审查门禁） | 是（隔离子进程跑完整工作流） | +| 需要模型 Key | 否 | 是（或订阅制 harness 后端） | -默认使用 **Direct 模式**：代码仍由你当前 Agent 的模型读取和判断； -InferMatrixCopilot 提供知识入口和审查门禁，不运行第二个模型，不自动发布 GitHub -评论，也不推送代码。 - -开发或维护 InferMatrixCopilot 本身，请直接看 -[开发者入口](DEVELOPMENT.md)。 +安全模型贯穿两种形态：**默认一切 dry-run**（`ALLOW_PUSH=0` / +`ALLOW_POST=0`），权限由任务类型推导、自然语言永远无法扩权，force push 只有 +`--force-with-lease`，保护分支无论如何不会被推送。 ## 安装 -私有仓库过渡期： +**Direct（在 Coding Agent 里用，最常用）：** -```text +```bash git clone git@github.com:JiusiServe/InferMatrixCopilot.git cd InferMatrixCopilot -# Windows：双击也可以 -install.cmd - -# 同时配置 Strict 使用的本地 vLLM-Omni checkout -install.cmd --repo-path D:\path\to\vllm-omni - -# macOS / Linux -./install-mcp.sh -./install-mcp.sh --repo-path /path/to/vllm-omni +./install-mcp.sh --repo-path /path/to/vllm-omni # macOS / Linux +install.cmd --repo-path D:\path\to\vllm-omni # Windows（双击也可以） ``` -安装器会识别本机的 Codex、Claude Code 和 Cursor，并安装 MCP、`imreview`、 -`imdesign`、`imcifix` 和 `imupdate` Skill。未识别到已知 Agent 时，会生成标准 -`infermatrix-copilot.mcp.json` 供其他 MCP 客户端导入。 - -Codex 重启后用 `$imreview` / `$imdesign` / `$imcifix` / `$imupdate`，也可以先运行 `/skills` 查找； -`/imreview` 不是 Codex 的 Slash Command。Claude Code 和 Cursor 仍使用 -`/imreview` / `/imdesign` / `/imcifix` / `/imupdate`。 - -安装器还会创建 `~/.infermatrix-copilot/.env`。Direct 不需要模型密钥；使用 -Strict 时，任选一种填写： +安装器识别本机的 Codex / Claude Code / Cursor，注册 MCP 与四个 Skill，并创建 +`~/.infermatrix-copilot/.env`。装完**重启 Agent**：Codex 用 `$imreview`， +Claude Code / Cursor 用 `/imreview`。Direct 不需要模型密钥。对话中 Agent +没有主动调用时，直接说： ```text -# Anthropic -ANTHROPIC_API_KEY=... -ANTHROPIC_BASE_URL= # 可选，代理或兼容网关地址 - -# 或 OpenAI -OPENAI_API_KEY=... -OPENAI_BASE_URL= # 可选，代理或兼容网关地址 +Use InferMatrixCopilot in Direct mode to review this PR. ``` -只填一种 Key 时会自动选择后端。两种都填时，用 -`LLM_PROVIDER=anthropic` 或 `LLM_PROVIDER=openai` 指定。安装时没有传 -`--repo-path` 的，还要填写 `REPO_PATHS`。然后重启 Agent。 +**Strict / CLI（独立运行）：** -## 确认安装成功 - -在 Agent 的 MCP 页面确认 `infermatrix-copilot` 已连接。Codex 也可以运行： - -```powershell -codex mcp list +```bash +bash install.sh # venv + editable 安装 + ./infermatrix-copilot 包装器 +./infermatrix-copilot doctor # 预检：每个 ✗ 都打印确切的修复命令 ``` -看到 `infermatrix-copilot` 后即可使用。如果对话中 Agent 没有调用它，直接说： +Strict 需要在 `.env` 里填一种模型 Key（`ANTHROPIC_API_KEY` 或 +`OPENAI_API_KEY`，各自支持可选 `*_BASE_URL`）和 `REPO_PATHS`。完整配置、 +常用 flag 与排查见 [`QUICKSTART.md`](QUICKSTART.md)。 -```text -Use InferMatrixCopilot in Direct mode to review this PR. -``` +## 快速上手 1 · 审查（review） -## 审查代码：`imreview` +Direct——在你的 Agent 里： ```text -# Codex -$imreview https://github.com/vllm-project/vllm-omni/pull/5172 -$imreview - -# Claude Code / Cursor -/imreview https://github.com/vllm-project/vllm-omni/pull/5172 -或者说 -“帮我审核一下这个pr xxxx，用知识库” +$imreview https://github.com/vllm-project/vllm-omni/pull/5172 # Codex +/imreview # Claude Code / Cursor：当前 PR 或本地改动 +或者直接说：帮我审核一下这个 pr 5172，用知识库 ``` -- 传 PR URL：读取该 PR 的当前 head、diff、CI 和 mergeability。 -- 不传参数：审查当前 PR；没有 PR 时审查当前本地改动。 -- 默认只在当前对话输出带文件和行号的审查意见，不发布到 GitHub。 +过程：固定 PR 快照并先报告 head / CI / mergeability → +`review(mode="direct")` 返回至多 3 条精确知识路由 + 审查门禁 → Agent 并行读 +源码、跑验证 → 完成门 `validate_direct_review` → 单条带文件行号的结论。 +默认只在当前对话输出，**不发布 GitHub 评论**。 -工作过程： +Strict——完整后台工作流（多 lens ensemble 评审，跑在 pin 到 PR head 的 +PR-time checkout 上）： -```text -你发起 imreview - → Agent 固定 PR 快照并在当前对话报告 head、CI 和 mergeability - → Agent 把 title、body 和 changed files 传给 review(..., mode="direct") - → MCP 返回至多 3 个相关知识入口及精简 quick map - → Agent 并行读取代码、执行相关验证 - → Agent 输出带文件和行号的审查结论 +```bash +./infermatrix-copilot -p "review pr 5172" +./infermatrix-copilot -p "review pr 5172" --plan-only # 只看计划不执行 +./infermatrix-copilot -p "review pr 5172" --performance # 用高能力模型档 ``` -Agent 会先确认 PR 版本和 CI 状态，再继续读代码。审查结果只显示在当前对话， -不会自动发到 GitHub。 +产物落在 `~/.infermatrix-copilot/runs/run-*/RUN_REPORT.md`。发布到 GitHub 是 +双闸：请求显式带 post 意图**且** `ALLOW_POST=1`，缺一不可。在 MCP 宿主里也 +可以跑 Strict：说 "Use InferMatrixCopilot in Strict mode to review …"，拿到 +`run_id` 后用 `get_review_status` / `get_review_result` 轮询。 -## 协同设计：`imdesign` +## 快速上手 2 · rebase -```text -# Codex -$imdesign https://github.com/JiusiServe/InferMatrixCopilot/issues/46 -$imdesign 支持 co-design skill，并提供便捷入口 +把单个 PR rebase 到最新 base（fork-aware checkout → rebase → 逐模块验证 → +patch review 门 → with-lease push）： -# Claude Code / Cursor -/imdesign +```bash +./infermatrix-copilot -p "rebase pr 5134" +./infermatrix-copilot -p "rebase pr 5134, then review it" # 复合命令自动排队 ``` -`imdesign` 会先读取 issue、PR 或本地相关代码，只产出协同设计包：问题、现状、 -方案、接口或配置变化、实施步骤、验证计划和风险。它不自动改代码；确认方案后再让 -Agent 继续实现。 - -## 修复 Issue：`imcifix` +冲突先交给受治理的 agent 解决，解不开就 abort 并升级（`ESCALATION.md`， +退出码 3），绝不留下半成品树。push 同样双闸：PushPolicy 允许**且** +`ALLOW_PUSH=1`，否则是一次 dry-run，准确显示"本来会做什么"；force 只有 +`--force-with-lease`，且只针对 PR 的 head 分支。 -```text -# Codex -$imcifix https://github.com/vllm-project/vllm-omni/issues/5023 -$imcifix issue 5023 +全仓库 rebase（夜跑）： -# Claude Code / Cursor -/imcifix +```bash +./infermatrix-copilot --playbook repo-rebase --yes ``` -`imcifix` 会读取 issue、检查当前 checkout、尽量复现或缩小问题，然后在本地做最小修复 -并跑针对性验证。它默认不 commit、不 push、不开 PR、不发评论；需要发布时要明确说。 +`repo-rebase` playbook 是 **locked** 状态：委托给已验证的外部 5 阶段编排器， +copilot 负责监控、进度事件与失败升级，永不改编。`repo-rebase-native` 是并排 +验证中的原生分解候选，对 planner 不可见，只能 `--playbook` 点名运行。 -## 更新知识：`imupdate` +## 快速上手 3 · 更新知识库 -上游仓库会不断增加模型、调整 registry、移动文件或修改 deploy。`imupdate` -用于把这些**结构事实**同步到 InferMatrixCopilot，避免以后按旧路径和旧清单审查。 -它更新的是 InferMatrixCopilot 知识，不会修改传入的 vLLM-Omni 仓库。 +上游发版或目录变化后，用 `imupdate` 把**结构事实**（模型清单、registry、 +deploy、路径路由、source pin）同步进知识库——只改 InferMatrixCopilot 的 +知识，不动目标仓库： ```text -# Codex：本地 checkout，baseline 对比当前 HEAD -$imupdate D:\path\to\vllm-omni - -# 仓库名或别名 -$imupdate vllm-omni -$imupdate vllmomni - -或者直接说 - -帮我更新一下 vllmomni仓库最新到知识库 - -# URL；可选指定目标 tag 或 SHA -$imupdate https://github.com/vllm-project/vllm-omni v0.26.0rc1 +$imupdate vllm-omni # Codex：仓库名或别名 +/imupdate /path/to/vllm-omni # Claude Code / Cursor：本地 checkout +$imupdate https://github.com/vllm-project/vllm-omni v0.26.0rc1 # URL + 目标 tag/SHA +或者直接说：帮我更新一下 vllmomni 仓库最新到知识库 ``` -它接受本地 Git 路径、仓库名、别名或 URL，第二个参数可选填目标 tag 或 SHA。 +流程：从 `release_baseline.yaml` 的 `audited_sha` 对比目标版本 → 只读机器 +审计（Git 对象、registry、pipeline、deploy、路径路由、source pin）→ Agent +只更新审计报告能证明的结构事实 → enforce、知识检查与相关测试验收。它不会 +根据一次 diff 自动编造 owner 规则，也不自动 commit、push 或开 PR。审计项 +明细见 [`doc/contributing/release-maintenance.md`](doc/contributing/release-maintenance.md)。 -本地路径的流程： +手工贡献知识（新增规则页、调整路由）遵循 +[`doc/knowledge/CONTRIBUTING.md`](doc/knowledge/CONTRIBUTING.md)，整批改完 +跑两个校验器： -```text -release_baseline.yaml 的 audited_sha - → 对比目标仓库 HEAD（或指定 tag/SHA） - → 只读审计 Git 对象、registry、pipeline、deploy、路径路由和 source pin - → Agent 只更新报告能够证明的结构事实 - → enforce、知识检查和相关测试确认更新完整 +```bash +python knowledge/tools/check_knowledge_tree.py +python knowledge/tools/check_wiki_lint.py ``` -仓库名、别名或 URL 的流程： - -```text -解析权威仓库和目标版本 - → 优先使用已配置或当前工作区中的 checkout - → 否则尽量建立临时 checkout，运行同一套机器审计 - → 无法运行机器审计时，只做有来源的模型分析，并明确标记验证不完整 -``` +另外两条知识通道由 run 自动积累、人工晋升：仓库 profile +（`-p "profile the repo"` 建立，fact 必须引证据）与 skills / debug memory +（agent 只能提案 candidate，人类晋升）。 -`imupdate` 不会根据一次 diff 自动编造 owner 规则，也不会自动 commit、push 或开 PR。 -详细的审计项和底层命令见 -[`doc/contributing/release-maintenance.md`](doc/contributing/release-maintenance.md)。 +## 其它能力 -## Skill 命令和 MCP 接口不是一回事 +- `imdesign` —— 写代码前的协同设计包（问题 / 方案 / 接口变化 / 验证计划）， + 不自动改代码。 +- `imcifix` —— 从 GitHub issue 出发：本地复现 → 最小修复 → 针对性验证； + 默认不 commit、不 push、不发评论。 +- CI 调试与 issue：`-p "debug pr 5134, report only"`、 + `-p "answer issue 4842, do not post"`、`-p "triage recent open issues"`。 +- 新仓库接入：`-p "profile the repo"` 建立 draft profile，零 `src/` 改动。 -平时直接用 `imreview`、`imcifix` 和 `imupdate` 即可，下面的接口由 Agent 调用： +## MCP 接口（由 Agent 调用，平时用 Skill 命令即可） - `review(target, repo="vllm-omni", mode="direct", post=false, review_depth="", title="", body="", changed_files=[], repo_path="")`： - Direct 根据 PR 描述返回至多 3 个精确知识路由和审查门禁；Strict 返回 - `run_id`。`repo_path` 可临时指定 Strict 使用的本地 checkout。 + Direct 返回至多 3 条精确知识路由和审查门禁；Strict 返回 `run_id`。 + `repo_path` 可临时指定 Strict 使用的本地 checkout。 - `validate_direct_review(subtraction_signal, subtraction?, minimality_proof?, final_comment_count=1, evidence_head_sha)`：Direct 最终 - 输出前的完成检查。`evidence_head_sha` 必须是本次审查固定的 head 提交， - 证明引用的源码和验证结果都读取自该版本而非本地工作区的其他分支。 - 普通小修改传 `subtraction_signal="none"`；存在新增或扩张结构时传 - `"triggered"`，并提供减法项或最小性证明。 -- `get_review_status(run_id)`：查看 Strict 后台任务的步骤和进度。 -- `get_review_result(run_id, offset=0)`：轮询 Strict 结果；报告较长时按 - `next_offset` 继续读取。 + 输出前的完成门。`evidence_head_sha` 必须是本次审查固定的 head 提交；普通 + 小修改传 `subtraction_signal="none"`，存在新增或扩张结构时传 + `"triggered"` 并提供减法项或最小性证明。 +- `get_review_status(run_id)` / `get_review_result(run_id, offset=0)`： + 查看 Strict 后台任务进度、轮询结果（长报告按 `next_offset` 续读）。 - `update_knowledge(repo="vllm-omni")`：只返回知识贡献入口 - `doc/knowledge/CONTRIBUTING.md`。它不是 `imupdate` 的发版审计器。 -- `doc_search(query, repo="vllm-omni", limit=20)`：搜索模型或组件知识。 -- `doc_read(path, repo="vllm-omni", offset=0)`：读取搜索到的知识页面。 - -## Direct 和 Strict 是同一个 MCP - -`imreview` 默认使用 Direct；需要完整后台工作流时，可以明确要求 Strict。 -两者都通过同一个 `infermatrix-copilot-mcp` 的 `review` 接口调用，不需要再安装一个 -Strict MCP。 - -```text -Use InferMatrixCopilot in Strict mode to review -https://github.com/vllm-project/vllm-omni/pull/5172. -``` - -Strict 会返回 `run_id`，Agent 再用 `get_review_status` 查看进度，并用 -`get_review_result` 取得最终报告。它默认也不会发布评论；发布仍需用户明确要求、 -调用传入 `post=true`，并且服务端配置 `ALLOW_POST=1`。 - -发布包已经包含 Strict 所需的 playbook、adapter 和 skill，不需要另外下载源码版。 -安装器会创建统一配置文件 `~/.infermatrix-copilot/.env`，并可通过 `--repo-path` -写入目标 checkout。模型密钥不会被安装器猜测或复制；使用 Strict 前填写 -`ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY` 即可。Anthropic 和 OpenAI 都支持各自的 -可选 `*_BASE_URL`。配置不完整时，`review` 会直接返回缺少的项目，不会启动一个 -注定失败的后台任务。 + `doc/knowledge/CONTRIBUTING.md`，**不是** `imupdate` 的发版审计器。 +- `doc_search(query, repo="vllm-omni", limit=20)` / + `doc_read(path, repo="vllm-omni", offset=0)`：搜索并阅读模型/组件知识页。 -## 独立执行器 +## 安全默认值一览 -Autonomous workflow 不是 `imreview` 的第三种模式，而是同一工作流引擎的独立 -CLI/MCP 入口。默认安装器不会注册它；只有需要独立执行 issue、CI、rebase 等任务时 -才需要阅读 -[`doc/guide/autonomous-workflow.md`](doc/guide/autonomous-workflow.md)。 +| 行为 | 默认 | 打开它需要 | +|---|---|---| +| git push | dry-run | `ALLOW_PUSH=1` 且 PushPolicy 允许 且 非保护分支 | +| 发 PR 评论 / issue 回复 | 关 | `ALLOW_POST=1` 且 请求显式带 post 意图 | +| force push | 仅 `--force-with-lease` | 无法放宽 | +| 未知仓库 | 生成 DRAFT adapter 后停下 | 人工审核后激活 | +| 高风险 manifest 段（`repo`/`upstream`/`push`） | agent 写入被拒 | 只能人工改 | ## 更多文档 -**[`doc/README.md`](doc/README.md) 是文档地图**——一行一条，按你要做的事挑一篇。 -下面只列最常用的四条路： +**[`doc/README.md`](doc/README.md) 是文档地图**——一行一条，按你要做的事挑一篇： | 你要做什么 | 看这篇 | |---|---| +| CLI 完整上手（配置、命令、排查） | [`QUICKSTART.md`](QUICKSTART.md) | | 完整了解它是什么、能做什么 | [指南](doc/GUIDE.md)（概览 / 功能 / 使用 / 开发 / playbook / step / tool / 性能） | | 在 Codex / Claude Code / Cursor 里装上用 | [宿主端](doc/guide/hosts/README.md) | +| 安装细节，或接入其他 MCP 客户端 | [MCP 安装](doc/guide/mcp.md) | | 让 Strict 跑在订阅或别的模型上 | [后端](doc/guide/backends.md) | +| 独立执行 issue / CI / rebase 任务 | [autonomous workflow](doc/guide/autonomous-workflow.md) | | 维护这个仓库本身 | [开发者入口](DEVELOPMENT.md) | > **宿主 ≠ 后端**：`claude-code` / `codex` / `cursor` 这三个名字两边都出现， -> 方向相反。宿主提供模型给你用（Direct），后端是 copilot 拿去用的模型（Strict）。 +> 方向相反。宿主提供模型给你用（Direct），后端是 copilot 拿去用的模型 +> （Strict）。 -其余：[MCP 接口](doc/guide/mcp.md) · -[发版漂移审计](doc/contributing/release-maintenance.md) · +其余：[发版漂移审计](doc/contributing/release-maintenance.md) · [知识库贡献规范](doc/knowledge/CONTRIBUTING.md) · [知识维护示例](doc/knowledge/maintainer-walkthrough.md) · [评测结论](doc/evaluation/README.md) From 9efdc276d3ae487a9e5e7ed2579aed89c1861b13 Mon Sep 17 00:00:00 2001 From: tzhouam Date: Tue, 25 Aug 2026 13:48:08 +0800 Subject: [PATCH 2/6] docs: restore benefit-led intro, tighten README (Codex revision) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Maintainer feedback on the previous commit: the introduction read worse than the original — it opened with abstract architecture language instead of what the tool does for the reader. Revision by Codex (gpt-5.6-sol), reviewed before commit: - Intro restored to the original's concrete form: what it does for your coding agent, then the four skills each tied to the problem it solves; the Direct-vs-Strict table follows immediately. - Quick starts tightened; arrow-chain process notation replaced with prose; install section split per platform. - MCP completion-gate description now carries the exact contract (none must carry no subtraction evidence, triggered needs a subtraction item or minimality proof, exactly one final comment). - Dirty-worktree row added to the safety defaults table. - The absolute repo-neutrality claim is dropped entirely; new-repo onboarding states adapters/ + knowledge/repos/ with no src/ changes. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EFomsSerZ41AX1kajBK13g --- README.md | 176 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 102 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index f0a1871da..61ee990f4 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,55 @@ # InferMatrixCopilot -**Playbook 驱动的仓库维护 copilot**：用一条自然语言命令审查 PR、rebase 分支、 -调试 CI、回答 issue，并维护一套随上游发版持续更新的仓库知识。vLLM-Omni 是 -第一个目标仓库（adapter zero），但核心与仓库解耦——新仓库通过 -`adapters//` 与 `knowledge/` 接入，不需要改 `src/`（仓库中立由护栏 -测试强制，已知遗留泄漏被清单封顶且只能变少）。 +让 Codex、Claude Code、Cursor 等 Coding Agent 按 +**vLLM-Omni 的项目知识**审查和维护代码，而不只是做一遍通用检查。上游发版或 +目录变化后，还能更新这套知识，避免 Agent 继续按旧路径和旧清单工作。 -一个仓库，两种形态，共享同一套知识与治理： +它提供四个常用 Skill： + +- `imreview`：审查 PR 或本地改动时，找到相关模型、组件和维护者规则，让审查 + 不只停留在通用检查。 +- `imdesign`：写代码前理清问题、方案、接口边界和验证计划。 +- `imcifix`：从 GitHub issue 出发，在本地复现、最小修复并针对性验证。 +- `imupdate`：上游变化后更新模型清单、registry、deploy、路径路由和 + source pin，避免继续按旧知识工作。 + +先选使用方式： | | **Direct（默认）** | **Strict / CLI** | |---|---|---| -| 谁读代码 | 你当前 Coding Agent（Codex / Claude Code / Cursor）自己的模型 | InferMatrixCopilot 配置的模型 | -| 入口 | `/imreview` `/imdesign` `/imcifix` `/imupdate` | `infermatrix-copilot -p "…"` | -| 服务端跑模型 | 否（零模型、零状态，同步返回知识路由与审查门禁） | 是（隔离子进程跑完整工作流） | -| 需要模型 Key | 否 | 是（或订阅制 harness 后端） | +| 谁读代码 | 当前 Coding Agent 自己的模型 | InferMatrixCopilot 配置的模型 | +| 入口 | `$imreview` 等宿主 Skill | `infermatrix-copilot -p "…"` | +| 模型凭据 | 不需要 API Key | 模型 API Key，或订阅制 harness 后端 | +| GitHub 写入 | 结果留在当前对话，不发布 | 默认关闭，相关请求和安全闸均允许后才执行 | -安全模型贯穿两种形态：**默认一切 dry-run**（`ALLOW_PUSH=0` / -`ALLOW_POST=0`），权限由任务类型推导、自然语言永远无法扩权，force push 只有 -`--force-with-lease`，保护分支无论如何不会被推送。 +Direct 是最常用的默认方式：InferMatrixCopilot 只提供知识路由和审查门禁， +不启动第二个模型。Strict 则在隔离子进程中运行完整工作流，可审查 PR、调试 CI、 +rebase 分支和处理 issue。两种方式共享同一套知识和安全规则；对外 push 与发布 +评论默认关闭。 ## 安装 -**Direct（在 Coding Agent 里用，最常用）：** +**Direct（在 Coding Agent 里使用）：** ```bash git clone git@github.com:JiusiServe/InferMatrixCopilot.git cd InferMatrixCopilot -./install-mcp.sh --repo-path /path/to/vllm-omni # macOS / Linux -install.cmd --repo-path D:\path\to\vllm-omni # Windows（双击也可以） +# macOS / Linux +./install-mcp.sh +./install-mcp.sh --repo-path /path/to/vllm-omni + +# Windows +install.cmd +install.cmd --repo-path D:\path\to\vllm-omni ``` -安装器识别本机的 Codex / Claude Code / Cursor，注册 MCP 与四个 Skill，并创建 -`~/.infermatrix-copilot/.env`。装完**重启 Agent**：Codex 用 `$imreview`， -Claude Code / Cursor 用 `/imreview`。Direct 不需要模型密钥。对话中 Agent -没有主动调用时，直接说： +Windows 也可以直接双击 `install.cmd`。`--repo-path` 可选，用于同时写入 Strict +使用的本地 checkout。安装器会识别本机的 Codex、Claude Code 和 Cursor，注册 +MCP 与四个 Skill，并创建 `~/.infermatrix-copilot/.env`。 + +安装后重启 Agent。Codex 使用 `$imreview`，Claude Code 和 Cursor 使用 +`/imreview`；Direct 不需要 API Key。若 Agent 没有主动调用，直接说： ```text Use InferMatrixCopilot in Direct mode to review this PR. @@ -43,31 +58,37 @@ Use InferMatrixCopilot in Direct mode to review this PR. **Strict / CLI（独立运行）：** ```bash -bash install.sh # venv + editable 安装 + ./infermatrix-copilot 包装器 +# 创建 venv、editable 安装和 ./infermatrix-copilot 包装器 +bash install.sh ./infermatrix-copilot doctor # 预检：每个 ✗ 都打印确切的修复命令 ``` -Strict 需要在 `.env` 里填一种模型 Key（`ANTHROPIC_API_KEY` 或 -`OPENAI_API_KEY`，各自支持可选 `*_BASE_URL`）和 `REPO_PATHS`。完整配置、 -常用 flag 与排查见 [`QUICKSTART.md`](QUICKSTART.md)。 +`install.sh` 会在仓库根从模板生成 `.env`（已被 git 忽略，永不覆盖已有的）； +Strict 还要在其中配置 `REPO_PATHS`。使用 API 后端时，填写 +`ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY`，各自支持可选的 `*_BASE_URL`； +也可以改用订阅制 harness 后端。API 配置、常用 flag 与排查见 +[`QUICKSTART.md`](QUICKSTART.md)，订阅后端配置见 +[后端指南](doc/guide/backends.md)。 -## 快速上手 1 · 审查（review） +## 快速上手 1 · 审查 Direct——在你的 Agent 里： ```text -$imreview https://github.com/vllm-project/vllm-omni/pull/5172 # Codex -/imreview # Claude Code / Cursor：当前 PR 或本地改动 -或者直接说：帮我审核一下这个 pr 5172，用知识库 +# Codex：审查指定 PR +$imreview https://github.com/vllm-project/vllm-omni/pull/5172 + +# Claude Code / Cursor：审查当前 PR 或本地改动 +/imreview + +或者直接说：帮我审核一下这个 PR 5172，用知识库 ``` -过程：固定 PR 快照并先报告 head / CI / mergeability → -`review(mode="direct")` 返回至多 3 条精确知识路由 + 审查门禁 → Agent 并行读 -源码、跑验证 → 完成门 `validate_direct_review` → 单条带文件行号的结论。 -默认只在当前对话输出，**不发布 GitHub 评论**。 +Agent 会先固定 PR 快照并报告 head、CI 和 mergeability，再取得至多 3 条相关 +知识路由和审查门禁，读取源码、运行验证，最后在当前对话输出一条带文件和行号的 +审查结论。Direct 不发布 GitHub 评论。 -Strict——完整后台工作流（多 lens ensemble 评审，跑在 pin 到 PR head 的 -PR-time checkout 上）： +Strict——运行完整 CLI 工作流： ```bash ./infermatrix-copilot -p "review pr 5172" @@ -75,24 +96,24 @@ PR-time checkout 上）： ./infermatrix-copilot -p "review pr 5172" --performance # 用高能力模型档 ``` -产物落在 `~/.infermatrix-copilot/runs/run-*/RUN_REPORT.md`。发布到 GitHub 是 -双闸：请求显式带 post 意图**且** `ALLOW_POST=1`，缺一不可。在 MCP 宿主里也 -可以跑 Strict：说 "Use InferMatrixCopilot in Strict mode to review …"，拿到 -`run_id` 后用 `get_review_status` / `get_review_result` 轮询。 +Strict 在固定到 PR head 的 checkout 上运行，并按改动规模和风险选择审查深度。报告写入 +`~/.infermatrix-copilot/runs/run-*/RUN_REPORT.md`。也可以在 MCP 宿主中说 +“Use InferMatrixCopilot in Strict mode to review …”；拿到 `run_id` 后，用 +`get_review_status` 和 `get_review_result` 轮询。 ## 快速上手 2 · rebase -把单个 PR rebase 到最新 base（fork-aware checkout → rebase → 逐模块验证 → -patch review 门 → with-lease push）： +把单个 PR rebase 到最新 base。工作流会识别 fork，检出 PR 分支，完成 rebase、 +逐模块验证和 patch review；推送另经安全闸： ```bash ./infermatrix-copilot -p "rebase pr 5134" ./infermatrix-copilot -p "rebase pr 5134, then review it" # 复合命令自动排队 ``` -冲突先交给受治理的 agent 解决，解不开就 abort 并升级（`ESCALATION.md`， -退出码 3），绝不留下半成品树。push 同样双闸：PushPolicy 允许**且** -`ALLOW_PUSH=1`，否则是一次 dry-run，准确显示"本来会做什么"；force 只有 +冲突先交给受治理的 Agent 解决；解不开就 abort 并升级，写出 +`ESCALATION.md`，以退出码 3 结束。push 需要 PushPolicy 允许并且 +`ALLOW_PUSH=1`；否则只显示“本来会做什么”。force 只使用 `--force-with-lease`，且只针对 PR 的 head 分支。 全仓库 rebase（夜跑）： @@ -101,9 +122,9 @@ patch review 门 → with-lease push）： ./infermatrix-copilot --playbook repo-rebase --yes ``` -`repo-rebase` playbook 是 **locked** 状态：委托给已验证的外部 5 阶段编排器， -copilot 负责监控、进度事件与失败升级，永不改编。`repo-rebase-native` 是并排 -验证中的原生分解候选，对 planner 不可见，只能 `--playbook` 点名运行。 +`repo-rebase` 是 **locked** playbook：它委托给已验证的 5 阶段编排器，必须 +原样复用，永不改编或重新生成。`repo-rebase-native` 是与它并排验证的原生分解 +候选，对 planner 不可见，只能用 `--playbook` 点名运行。 ## 快速上手 3 · 更新知识库 @@ -112,17 +133,23 @@ deploy、路径路由、source pin）同步进知识库——只改 InferMatrixC 知识，不动目标仓库： ```text -$imupdate vllm-omni # Codex：仓库名或别名 -/imupdate /path/to/vllm-omni # Claude Code / Cursor：本地 checkout -$imupdate https://github.com/vllm-project/vllm-omni v0.26.0rc1 # URL + 目标 tag/SHA +# Codex：仓库名或别名 +$imupdate vllm-omni + +# Claude Code / Cursor：本地 checkout +/imupdate /path/to/vllm-omni + +# URL + 目标 tag/SHA +$imupdate https://github.com/vllm-project/vllm-omni v0.26.0rc1 + 或者直接说：帮我更新一下 vllmomni 仓库最新到知识库 ``` -流程：从 `release_baseline.yaml` 的 `audited_sha` 对比目标版本 → 只读机器 -审计（Git 对象、registry、pipeline、deploy、路径路由、source pin）→ Agent -只更新审计报告能证明的结构事实 → enforce、知识检查与相关测试验收。它不会 -根据一次 diff 自动编造 owner 规则，也不自动 commit、push 或开 PR。审计项 -明细见 [`doc/contributing/release-maintenance.md`](doc/contributing/release-maintenance.md)。 +流程：从 `release_baseline.yaml` 的 `audited_sha` 对比目标版本，执行只读机器 +审计（Git 对象、registry、pipeline、deploy、路径路由、source pin）；Agent +只更新审计报告能证明的结构事实，再以 `enforce` 模式审计、知识检查和相关测试 +验收。它不会根据一次 diff 自动编造 owner 规则，也不自动 commit、push 或开 PR。 +审计项明细见[发版维护](doc/contributing/release-maintenance.md)。 手工贡献知识（新增规则页、调整路由）遵循 [`doc/knowledge/CONTRIBUTING.md`](doc/knowledge/CONTRIBUTING.md)，整批改完 @@ -133,21 +160,20 @@ python knowledge/tools/check_knowledge_tree.py python knowledge/tools/check_wiki_lint.py ``` -另外两条知识通道由 run 自动积累、人工晋升：仓库 profile -（`-p "profile the repo"` 建立，fact 必须引证据）与 skills / debug memory -（agent 只能提案 candidate，人类晋升）。 - ## 其它能力 -- `imdesign` —— 写代码前的协同设计包（问题 / 方案 / 接口变化 / 验证计划）， +- `imdesign`：写代码前生成协同设计包（问题、方案、接口变化和验证计划）， 不自动改代码。 -- `imcifix` —— 从 GitHub issue 出发：本地复现 → 最小修复 → 针对性验证； +- `imcifix`：从 GitHub issue 出发，在本地复现、最小修复并针对性验证； 默认不 commit、不 push、不发评论。 -- CI 调试与 issue：`-p "debug pr 5134, report only"`、 +- Strict 还可调试 CI 和处理 issue：`-p "debug pr 5134, report only"`、 `-p "answer issue 4842, do not post"`、`-p "triage recent open issues"`。 -- 新仓库接入：`-p "profile the repo"` 建立 draft profile，零 `src/` 改动。 +- 新仓库接入：`-p "profile the repo"` 建立 DRAFT profile；接入内容放在 + `adapters//` 和 `knowledge/repos//`，不需要修改 `src/`。 + +## MCP 接口 -## MCP 接口（由 Agent 调用，平时用 Skill 命令即可） +平时使用 Skill 命令即可；以下接口由 Agent 调用： - `review(target, repo="vllm-omni", mode="direct", post=false, review_depth="", title="", body="", changed_files=[], repo_path="")`： @@ -155,15 +181,16 @@ python knowledge/tools/check_wiki_lint.py `repo_path` 可临时指定 Strict 使用的本地 checkout。 - `validate_direct_review(subtraction_signal, subtraction?, minimality_proof?, final_comment_count=1, evidence_head_sha)`：Direct 最终 - 输出前的完成门。`evidence_head_sha` 必须是本次审查固定的 head 提交；普通 - 小修改传 `subtraction_signal="none"`，存在新增或扩张结构时传 - `"triggered"` 并提供减法项或最小性证明。 -- `get_review_status(run_id)` / `get_review_result(run_id, offset=0)`： - 查看 Strict 后台任务进度、轮询结果（长报告按 `next_offset` 续读）。 + 输出前的完成门。`subtraction_signal="none"` 时不得附带减法证据；传 + `"triggered"` 时必须提供减法项或最小性证明。最终评论必须恰好一条， + `evidence_head_sha` 必须是本次审查固定的 head 提交。 +- `get_review_status(run_id)`：查看 Strict 后台任务的步骤和进度。 +- `get_review_result(run_id, offset=0)`：轮询 Strict 结果；长报告按 + `next_offset` 继续读取。 - `update_knowledge(repo="vllm-omni")`：只返回知识贡献入口 `doc/knowledge/CONTRIBUTING.md`，**不是** `imupdate` 的发版审计器。 -- `doc_search(query, repo="vllm-omni", limit=20)` / - `doc_read(path, repo="vllm-omni", offset=0)`：搜索并阅读模型/组件知识页。 +- `doc_search(query, repo="vllm-omni", limit=20)`：搜索模型或组件知识。 +- `doc_read(path, repo="vllm-omni", offset=0)`：读取搜索到的知识页。 ## 安全默认值一览 @@ -172,21 +199,22 @@ python knowledge/tools/check_wiki_lint.py | git push | dry-run | `ALLOW_PUSH=1` 且 PushPolicy 允许 且 非保护分支 | | 发 PR 评论 / issue 回复 | 关 | `ALLOW_POST=1` 且 请求显式带 post 意图 | | force push | 仅 `--force-with-lease` | 无法放宽 | +| 脏工作树 | 拒绝启动 | 先清理 | | 未知仓库 | 生成 DRAFT adapter 后停下 | 人工审核后激活 | -| 高风险 manifest 段（`repo`/`upstream`/`push`） | agent 写入被拒 | 只能人工改 | +| 高风险 manifest 段（`repo`/`upstream`/`push`） | Agent 写入被拒 | 只能人工改 | ## 更多文档 -**[`doc/README.md`](doc/README.md) 是文档地图**——一行一条，按你要做的事挑一篇： +**[`doc/README.md`](doc/README.md) 是文档地图**——按你要做的事挑一篇： | 你要做什么 | 看这篇 | |---|---| | CLI 完整上手（配置、命令、排查） | [`QUICKSTART.md`](QUICKSTART.md) | -| 完整了解它是什么、能做什么 | [指南](doc/GUIDE.md)（概览 / 功能 / 使用 / 开发 / playbook / step / tool / 性能） | +| 完整了解它是什么、能做什么 | [指南](doc/GUIDE.md) | | 在 Codex / Claude Code / Cursor 里装上用 | [宿主端](doc/guide/hosts/README.md) | | 安装细节，或接入其他 MCP 客户端 | [MCP 安装](doc/guide/mcp.md) | | 让 Strict 跑在订阅或别的模型上 | [后端](doc/guide/backends.md) | -| 独立执行 issue / CI / rebase 任务 | [autonomous workflow](doc/guide/autonomous-workflow.md) | +| 独立执行 issue / CI / rebase 任务 | [独立工作流](doc/guide/autonomous-workflow.md) | | 维护这个仓库本身 | [开发者入口](DEVELOPMENT.md) | > **宿主 ≠ 后端**：`claude-code` / `codex` / `cursor` 这三个名字两边都出现， From 0807e35e03f7935dc0ff6c234722b47818b7375b Mon Sep 17 00:00:00 2001 From: tzhouam Date: Tue, 25 Aug 2026 13:58:24 +0800 Subject: [PATCH 3/6] docs: state repo neutrality in the README intro MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The intro framed the copilot as a vLLM-Omni-specific tool. Verified against code and docs, it is repo-invariant: playbooks match any repo by capability (repo-profile declares `repos: []`), per-repo knowledge lives in adapters// and knowledge/repos//, and a second adapter (afd-plugin, active, human-reviewed) already exists alongside adapter zero. - Intro now says "目标仓库的项目知识" and adds a short paragraph: onboarding a new repo needs no core-code change; vLLM-Omni is adapter zero and the example repo throughout; afd-plugin is the second onboarded repo. - MCP section notes that the `repo` parameter defaults to adapter zero (matching the actual signature defaults in thin_mcp_server.py) and accepts any onboarded repo's short name, alias, or owner/name. - Remaining vllm-omni mentions are examples or real code defaults, left as is. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01EFomsSerZ41AX1kajBK13g --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 61ee990f4..7d86d00da 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # InferMatrixCopilot -让 Codex、Claude Code、Cursor 等 Coding Agent 按 -**vLLM-Omni 的项目知识**审查和维护代码，而不只是做一遍通用检查。上游发版或 -目录变化后，还能更新这套知识，避免 Agent 继续按旧路径和旧清单工作。 +让 Codex、Claude Code、Cursor 等 Coding Agent 按**目标仓库的项目知识** +审查和维护代码，而不只是做一遍通用检查。上游发版或目录变化后，还能更新 +这套知识，避免 Agent 继续按旧路径和旧清单工作。 它提供四个常用 Skill： @@ -13,6 +13,12 @@ - `imupdate`：上游变化后更新模型清单、registry、deploy、路径路由和 source pin，避免继续按旧知识工作。 +copilot 本身与具体仓库无关：每个仓库的知识住在自己的 adapter +（`adapters//`）和知识切片（`knowledge/repos//`）里，playbook +按能力匹配任意仓库，接入新仓库不需要改核心代码（见「其它能力」的新仓库 +接入）。vLLM-Omni 是第一个接入的仓库（adapter zero），也是本文全部示例； +afd-plugin 已按同样方式作为第二个仓库接入。 + 先选使用方式： | | **Direct（默认）** | **Strict / CLI** | @@ -173,7 +179,8 @@ python knowledge/tools/check_wiki_lint.py ## MCP 接口 -平时使用 Skill 命令即可；以下接口由 Agent 调用： +平时使用 Skill 命令即可；以下接口由 Agent 调用。`repo` 参数默认 adapter +zero（`vllm-omni`），可传任何已接入仓库的短名、别名或 owner/name： - `review(target, repo="vllm-omni", mode="direct", post=false, review_depth="", title="", body="", changed_files=[], repo_path="")`： From a0afa22353950f5cb9934448c010656d4e06a83a Mon Sep 17 00:00:00 2001 From: tzhouam Date: Tue, 25 Aug 2026 14:06:04 +0800 Subject: [PATCH 4/6] docs: correct the README rebase quick start to the merged v3 pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The section still presented `repo-rebase` (the locked playbook that delegates to the external 5-phase orchestrator) as THE full-repo rebase, and named a `repo-rebase-native` candidate that does not exist under that name. Since the rebase-merge completion unit landed, the actual pipeline is `repo-rebase-v3` — rebase_engine end to end inside the playbook (wheel pin, per-module waves, local test loop, push gate, remote-CI monitoring), proven on the live vLLM v0.28.0 rebases. Now documented: the two invocations (report_only probe and the end-to-end full mode with last_rebase_commit), the four rebase_mode tiers, the push double gate, remote CI's schedule-build adoption plus the adapter-gated direct build creation on schedule-only pipelines (rebase.ci.ignore_branch_filters), and the real three-playbook status: repo-rebase-v3 / repo-rebase-native-v1 as planner-invisible candidates, repo-rebase still locked until the §8 gate promotes v3. Docs-only; no code touched. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01CD4ifoCtkdQXxEyfCPyzLV --- README.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 7d86d00da..d2c6030b7 100644 --- a/README.md +++ b/README.md @@ -122,15 +122,32 @@ Strict 在固定到 PR head 的 checkout 上运行，并按改动规模和风险 `ALLOW_PUSH=1`；否则只显示“本来会做什么”。force 只使用 `--force-with-lease`，且只针对 PR 的 head 分支。 -全仓库 rebase（夜跑）： +全仓库 rebase：当前管线是 `repo-rebase-v3` —— rebase_engine 全量合并后的 +原生实现，wheel pin、按模块分波验证、本地测试环、push 闸、远端 CI 监控都在 +playbook 内完成，不再委托外部编排器： ```bash -./infermatrix-copilot --playbook repo-rebase --yes +# 只读评估 +./infermatrix-copilot --yes --playbook repo-rebase-v3 \ + --task-param rebase_mode=report_only + +# 端到端：wheel → 模块波次 → 本地测试 → push 闸 → 远端 CI +./infermatrix-copilot --yes --playbook repo-rebase-v3 \ + --task-param rebase_mode=full \ + --task-param last_rebase_commit=<上次对齐到的 upstream sha> ``` -`repo-rebase` 是 **locked** playbook：它委托给已验证的 5 阶段编排器，必须 -原样复用，永不改编或重新生成。`repo-rebase-native` 是与它并排验证的原生分解 -候选，对 planner 不可见，只能用 `--playbook` 点名运行。 +`rebase_mode` 有四档：`report_only`（只读）、`local_ci`（本地测试环，不 +push）、`remote_ci`（push + 远端 CI 监控，需要 +`--task-param upstream_commit=`）、`full`（端到端）。push 仍受双闸 +（push 闸裁决 + `ALLOW_PUSH=1`）。远端 CI 会优先领养同 commit 的 schedule +构建；对 schedule-only 的流水线，也能按 adapter 声明 +（`rebase.ci.ignore_branch_filters`）直接创建构建。 + +三个 playbook 并存：`repo-rebase-v3` 与 `repo-rebase-native-v1` 都是 +**candidate**——对 planner 不可见，只能用 `--playbook` 点名运行； +`repo-rebase` 仍是 **locked** 的旧委托入口（转交已验证的 5 阶段编排器， +必须原样复用），在 §8 验证闸通过、由人工促升 v3 之前保持不变。 ## 快速上手 3 · 更新知识库 From 4d54ffcdf4f4f4dedaceab091a7d1deff61055a1 Mon Sep 17 00:00:00 2001 From: tzhouam Date: Tue, 25 Aug 2026 14:39:36 +0800 Subject: [PATCH 5/6] =?UTF-8?q?docs:=20README=20rebase=20quick=20start=20?= =?UTF-8?q?=E2=80=94=20cutover=20status=20+=20full=20parameters?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tracks the 2026-08-25 cutover (main 012e900): repo-rebase-v3 is now locked and planner-recalled, the delegating v2 and native-v1 are deleted, so the "three playbooks coexist" paragraph is gone. The quick start now documents where every input comes from: the target repo (--repo / DEFAULT_REPO via the REPO_PATHS mapping and its adapters// requirement), the target branch (adapter manifest upstream.target_branch, resolved to the branch tip with the wheel probe), the upstream-checkout/venv path variables, the full --task-param table (rebase_mode tiers, last_rebase_commit, upstream_commit, force_upstream_commit, main_ci_idx, the halt/push strictness knobs) and the .env gates (ALLOW_PUSH double gate, GITHUB_TOKEN, BUILDKITE_API_TOKEN, REBASE_CI_TIMEOUT_SEC). Docs-only. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01CD4ifoCtkdQXxEyfCPyzLV --- README.md | 47 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index d2c6030b7..24f1ca673 100644 --- a/README.md +++ b/README.md @@ -122,33 +122,50 @@ Strict 在固定到 PR head 的 checkout 上运行，并按改动规模和风险 `ALLOW_PUSH=1`；否则只显示“本来会做什么”。force 只使用 `--force-with-lease`，且只针对 PR 的 head 分支。 -全仓库 rebase：当前管线是 `repo-rebase-v3` —— rebase_engine 全量合并后的 -原生实现，wheel pin、按模块分波验证、本地测试环、push 闸、远端 CI 监控都在 -playbook 内完成，不再委托外部编排器： +全仓库 rebase：引擎是 `repo-rebase-v3` —— rebase_engine 全量合并后的原生 +playbook（wheel pin、按模块分波验证、本地测试环、push 闸、远端 CI 监控全部 +在内，无外部编排器）。2026-08-25 起为 **locked**（L0 原样复用，planner 直接 +召回）；旧的委托版 `repo-rebase` v2 与 `repo-rebase-native-v1` 已删除。 ```bash # 只读评估 -./infermatrix-copilot --yes --playbook repo-rebase-v3 \ +./infermatrix-copilot --repo vllm-omni --yes --playbook repo-rebase-v3 \ --task-param rebase_mode=report_only # 端到端：wheel → 模块波次 → 本地测试 → push 闸 → 远端 CI -./infermatrix-copilot --yes --playbook repo-rebase-v3 \ +./infermatrix-copilot --repo vllm-omni --yes --playbook repo-rebase-v3 \ --task-param rebase_mode=full \ --task-param last_rebase_commit=<上次对齐到的 upstream sha> ``` -`rebase_mode` 有四档：`report_only`（只读）、`local_ci`（本地测试环，不 -push）、`remote_ci`（push + 远端 CI 监控，需要 -`--task-param upstream_commit=`）、`full`（端到端）。push 仍受双闸 -（push 闸裁决 + `ALLOW_PUSH=1`）。远端 CI 会优先领养同 commit 的 schedule -构建；对 schedule-only 的流水线，也能按 adapter 声明 +**目标从哪里来** + +| 目标 | 来源 | 说明 | +| --- | --- | --- | +| 目标仓库 | `--repo <名字>`（缺省 `DEFAULT_REPO`） | 名字经 `.env` 的 `REPO_PATHS`（JSON）映射到本地 checkout；仓库必须有 `adapters//` 适配器 | +| 上游分支 | 适配器 manifest 的 `upstream.target_branch`（如 `releases/v0.28.0`） | 管线在上游 checkout 上解析该分支 tip 作为 rebase 目标，并校验预编译 wheel 可用 | +| 上游 checkout / 目标 venv | manifest 声明的路径变量，经 `.env` 展开（vllm-omni：`VLLM_UPSTREAM_REPO`、`VLLM_OMNI_VENV`） | full 模式要求两者就绪 | + +**task 参数**（`--task-param k=v`，可重复） + +| 参数 | 适用模式 | 说明 | +| --- | --- | --- | +| `rebase_mode` | 必填 | `report_only`（只读）/ `local_ci`（本地测试环，不 push）/ `remote_ci`（push + 远端 CI 监控）/ `full`（端到端） | +| `last_rebase_commit` | full | 上次对齐到的 upstream sha（基线；run state 已有记录时可省略） | +| `upstream_commit` | remote_ci 必填 | 要推送并监控的目标 upstream sha | +| `force_upstream_commit` | full | 跳过分支 tip 解析，强制指定目标 sha | +| `main_ci_idx` | remote_ci / full | 多条 CI 流水线时选主流水线（缺省 0） | +| `halt_on_module_failure` | full | 模块失败即停（缺省 false：wave 门只清空 wave 2） | +| `halt_on_phase3_failures` | full | 本地测试环失败即停（缺省 false） | +| `push_with_failures` | remote_ci / full | 允许带失败推送（缺省 false） | +| `strict_push_gate` | remote_ci / full | 更严的 push 闸（缺省 false） | + +**环境闸（`.env`）**：push 受双闸 —— push 闸裁决**且** `ALLOW_PUSH=1`；push +认证走 `GITHUB_TOKEN`，远端 CI 需要 `BUILDKITE_API_TOKEN`；CI 监控预算 +`REBASE_CI_TIMEOUT_SEC`（缺省 3h）。远端 CI 优先领养同 commit 的 schedule +构建；对 schedule-only 流水线，按 adapter 声明 （`rebase.ci.ignore_branch_filters`）直接创建构建。 -三个 playbook 并存：`repo-rebase-v3` 与 `repo-rebase-native-v1` 都是 -**candidate**——对 planner 不可见，只能用 `--playbook` 点名运行； -`repo-rebase` 仍是 **locked** 的旧委托入口（转交已验证的 5 阶段编排器， -必须原样复用），在 §8 验证闸通过、由人工促升 v3 之前保持不变。 - ## 快速上手 3 · 更新知识库 上游发版或目录变化后，用 `imupdate` 把**结构事实**（模型清单、registry、 From a36b8824276e013287366e301d15b066dbcaeea5 Mon Sep 17 00:00:00 2001 From: tzhouam Date: Tue, 25 Aug 2026 14:51:12 +0800 Subject: [PATCH 6/6] =?UTF-8?q?docs:=20README=20=E2=80=94=20.env=20setup?= =?UTF-8?q?=20section,=20imcifix=20quick=20start,=20real=20v0.28.0=20examp?= =?UTF-8?q?le?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Owner feedback, three additions: 1. New "配置 .env" section between install and the quick starts: the three-layer minimal config (Direct needs only the repo mapping; Strict/CLI adds the model backend; rebase remote CI adds the tokens), a filled example block covering REPO_PATHS/DEFAULT_REPO/ REPO_FULL_NAMES, the vllm-omni path variables incl. VLLM_OMNI_VENV, the ALLOW_PUSH/ALLOW_POST gates, GITHUB_TOKEN/BUILDKITE_API_TOKEN/ REBASE_CI_TIMEOUT_SEC, and the doctor / doctor --probe verification step. Never-commit rule stated up front. 2. imcifix promoted from an "other capabilities" bullet to quick start 4 with Direct examples (issue URL / number / natural language) and the Strict debug/answer/triage commands moved in; imdesign keeps an invocation example in the remaining list. 3. The repo-rebase quick start now carries the real v0.28.0 campaign commands: full mode from baseline 1af5a386cd43 chasing releases/v0.28.0 (tag v0.28.0 = 2cf0a691, resolved by the pipeline from the manifest's target_branch), plus the remote_ci variant with the exact upstream_commit sha. Docs-only. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01CD4ifoCtkdQXxEyfCPyzLV --- README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 88 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 24f1ca673..a5075e00f 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,46 @@ Strict 还要在其中配置 `REPO_PATHS`。使用 API 后端时，填写 [`QUICKSTART.md`](QUICKSTART.md)，订阅后端配置见 [后端指南](doc/guide/backends.md)。 +## 配置 .env + +`install.sh` / `install-mcp.sh` 会从 [`.env.template`](.env.template) 生成 +`.env`（CLI 用仓库根的 `.env`，Direct/MCP 宿主用 +`~/.infermatrix-copilot/.env`）。`.env` 已被 git 忽略——**绝不提交**，token +和机器本地的绝对路径只放这里。 + +最小可用配置分三层：Direct 只需要仓库映射；Strict/CLI 加模型；rebase 的 +远端 CI 再加 token： + +```bash +# 模型（Strict/CLI）：Anthropic 或 OpenAI 二选一；*_BASE_URL 可选代理 +ANTHROPIC_API_KEY=sk-... +AGENT_MODEL=claude-sonnet-5 +STRICT_BACKEND=api # 或 cursor / claude-code / codex（订阅制 CLI） + +# 仓库映射：名字 -> 本地 checkout +REPO_PATHS={"vllm-omni": "/data/me/vllm-omni"} +DEFAULT_REPO=vllm-omni +REPO_FULL_NAMES={"vllm-omni": "vllm-project/vllm-omni"} # GitHub URL 路由 + +# adapter manifest 的路径变量（vllm-omni）：上游 checkout 与目标 venv +VLLM_OMNI_REPO=/data/me/vllm-omni +VLLM_UPSTREAM_REPO=/data/me/vllm +VLLM_OMNI_VENV=/data/me/vllm-omni-venv + +# 安全闸：默认全关；打开是显式动作 +ALLOW_PUSH=0 # push 双闸的环境端（另一半是 push 闸裁决） +ALLOW_POST=0 # 发 PR / issue 评论 + +# rebase 远端 CI（rebase_mode=remote_ci / full 才需要） +GITHUB_TOKEN=ghp_... # push 走 header 认证 +BUILDKITE_API_TOKEN=bkua_... # 需要 write_builds scope +REBASE_CI_TIMEOUT_SEC=18000 # CI 监控预算（缺省 10800 = 3h） +``` + +改完跑 `./infermatrix-copilot doctor`——每个 ✗ 都打印确切修复命令； +`doctor --probe` 再做 1-token 真连线校验（唯一的付费检查）。完整变量清单 +（模型分档、订阅后端、邮件通知等）见 [`.env.template`](.env.template)。 + ## 快速上手 1 · 审查 Direct——在你的 Agent 里： @@ -128,14 +168,26 @@ playbook（wheel pin、按模块分波验证、本地测试环、push 闸、远 召回）；旧的委托版 `repo-rebase` v2 与 `repo-rebase-native-v1` 已删除。 ```bash -# 只读评估 +# 只读评估：不动工作树，产出 RUN_REPORT ./infermatrix-copilot --repo vllm-omni --yes --playbook repo-rebase-v3 \ --task-param rebase_mode=report_only +``` + +真实示例——把 vllm-omni 追到 vLLM **v0.28.0**（adapter manifest 已设 +`upstream.target_branch: releases/v0.28.0`；管线在上游 checkout 解析该分支 +tip，即 tag `v0.28.0` = `2cf0a691`，并校验预编译 wheel 可用）： -# 端到端：wheel → 模块波次 → 本地测试 → push 闸 → 远端 CI +```bash +# 端到端：从上次对齐的 1af5a386c 追到 releases/v0.28.0 tip —— wheel pin → +# 模块波次 → 本地测试环 → push dev/vllm-align → 自建 Buildkite 构建并监控 ./infermatrix-copilot --repo vllm-omni --yes --playbook repo-rebase-v3 \ --task-param rebase_mode=full \ - --task-param last_rebase_commit=<上次对齐到的 upstream sha> + --task-param last_rebase_commit=1af5a386cd43695b23a1f7a63b0646bbf043fc9c + +# 树已推送、只需要 CI 验证指定 commit 时：remote_ci + 精确 sha +./infermatrix-copilot --repo vllm-omni --yes --playbook repo-rebase-v3 \ + --task-param rebase_mode=remote_ci \ + --task-param upstream_commit=2cf0a6915ce544dc493a0990f2ea38d81601128a ``` **目标从哪里来** @@ -200,16 +252,42 @@ python knowledge/tools/check_knowledge_tree.py python knowledge/tools/check_wiki_lint.py ``` +## 快速上手 4 · CI 修复（imcifix） + +从 GitHub issue 出发：本地复现、最小修复、针对性验证；默认不 commit、 +不 push、不发评论： + +```text +# Codex：issue 号或 URL +$imcifix https://github.com/vllm-project/vllm-omni/issues/5100 + +# Claude Code / Cursor +/imcifix 5100 + +或者直接说：帮我修一下 issue 5100，先本地复现 +``` + +Agent 会解析 issue（标题、正文、标签、评论一律按不可信证据处理），先报告 +issue 号、分支、脏树状态和初始假设，再用最小命令复现，做最小修复并针对性 +验证。只有明确要求发布时才建 `fix/-` 分支，只加增量提交， +永不 force-push。 + +Strict 对应的 CI / issue 工作流： + +```bash +./infermatrix-copilot -p "debug pr 5134, report only" # CI 失败诊断 +./infermatrix-copilot -p "answer issue 4842, do not post" # 起草 issue 回复 +./infermatrix-copilot -p "triage recent open issues" # 批量分诊 +``` + ## 其它能力 - `imdesign`：写代码前生成协同设计包（问题、方案、接口变化和验证计划）， - 不自动改代码。 -- `imcifix`：从 GitHub issue 出发，在本地复现、最小修复并针对性验证； - 默认不 commit、不 push、不发评论。 -- Strict 还可调试 CI 和处理 issue：`-p "debug pr 5134, report only"`、 - `-p "answer issue 4842, do not post"`、`-p "triage recent open issues"`。 -- 新仓库接入：`-p "profile the repo"` 建立 DRAFT profile；接入内容放在 - `adapters//` 和 `knowledge/repos//`，不需要修改 `src/`。 + 不自动改代码。例：`/imdesign 给 scheduler 加抢占开关，先理清接口边界`， + Codex 用 `$imdesign …`。 +- 新仓库接入：`./infermatrix-copilot -p "profile the repo"` 建立 DRAFT + profile；接入内容放在 `adapters//` 和 `knowledge/repos//`， + 不需要修改 `src/`。 ## MCP 接口