这份文档给维护 InferMatrixCopilot 本身的人。普通安装和使用请看 README。
不要递归读取整棵 knowledge/。先按任务选一个入口，命中具体 owner 后停止导航。
| 正在做什么 | 通用入口 | vLLM-Omni 补充 |
|---|---|---|
| Code review | review contract | review |
| 写代码或改接口 | code taste | 先从下面的 owner 表定位组件 |
| CI 和测试 | general/ci | vLLM-Omni CI |
| 文档和 RFC | general/docs | vLLM-Omni docs |
| 调试 | general/debug | vLLM-Omni debug |
| Git、PR、rebase | general/git | Git / rebase |
| Benchmark | general/benchmark | vLLM-Omni benchmark |
| 远端验证 | general/remote | vLLM-Omni remote |
| 新增或整理知识 | knowledge/CONTRIBUTING | 先确定最近的 owner |
vLLM-Omni 的代码 owner：
| 改动内容 | Owner 规则 |
|---|---|
| PipelineConfig、YAML、registry、default、deploy | configuration |
| HTTP/OpenAI request、response、endpoint、engine lifecycle | serving |
| checkpoint、tokenizer、processor、stage handoff | model executor |
| diffusion pipeline、denoise、VAE、DiT、图像生成 | diffusion |
| connector、collective、跨 stage 通信 | distributed |
| queue、token budget、prefix cache、调度 | scheduler |
| 明确的模型或 registry key | models |
完整知识入口仍在 知识树地图。只有 owner 不明确时才看
组件职责表；不要默认打开事故记录、
history、results 或所有 _index.md。
plugins/、skills/、integrations/ Agent 安装入口和 /imreview、/imupdate
src/infermatrix_copilot/
thin_mcp_server.py 默认 MCP：Direct 路由和 Strict 入口
mcp_server.py Strict 后台任务、状态和结果
config.py、llm.py 配置及 Anthropic/OpenAI 后端
intent.py、task_spec.py 用户意图和任务协议
engine/ playbook 执行器及步骤
adapters/ 仓库适配层
playbooks/ Strict/Autonomous 工作流定义
adapters/ 发布包中的仓库配置
knowledge/ 通用、仓库、组件和模型知识
doc/architecture/SPEC/ 与 src 文件对应的约束和职责
test/ 离线测试
整体架构先看 CODE_TOUR，修改具体源码前再看 file-level SPEC 中对应文件。
| 要改什么 | 主要位置 | 最少验证 |
|---|---|---|
| Direct 返回内容或路由 | thin_mcp_server.py、Direct Skill |
test_thin_mcp_server.py、test_imreview_output_contract.py |
| Strict 启动、轮询、发布门禁 | mcp_server.py、mcp_policy.py |
test_mcp.py |
| 模型、Key、Base URL | config.py、llm.py |
test_llm_providers.py、test_tier_split.py |
| 工作流步骤 | playbooks/*.yaml、engine/steps/ |
对应 step 测试和 playbook 加载测试 |
| 新仓库支持 | adapters/<repo>/、knowledge/repos/<repo>/ |
adapter 测试和知识检查 |
| 更新 vLLM-Omni 知识 | /imupdate 维护流程 |
release maintenance |
| 安装或发布包 | scripts/install_mcp.py、pyproject.toml |
installer 测试和 wheel 内容检查 |
python -m pip install -e ".[dev,mcp]" ruff build
$env:PYTHONPATH = "src"
python -m pytest
python -m ruff check .
git diff --check知识文件有改动时额外运行：
python knowledge/tools/check_knowledge_tree.py
python knowledge/tools/check_wiki_lint.py发布包有改动时：
python -m build --wheel确认 wheel 中包含 knowledge/、_runtime/playbooks/、_runtime/adapters/ 和
_runtime/skills/，不能只验证源码 checkout。
.github/workflows/test.yml 在每次 push 与 PR 上跑上面这些检查：整套 pytest、
--help / doctor 冒烟、把 wheel 装进干净 venv 验证四棵数据树确实随包发布
（test_packaged_runtime.py 只断言 pyproject 的文本，证明不了这件事），
以及两个知识树 linter。
它目前只是信号，不是合并门禁。 要让它真正挡住合并，需要在
Settings → Branches（或 repository ruleset）里把 suite 这个 job 设为
required status check —— 这是仓库设置，任何一次提交都做不到。
- Direct 使用宿主 Agent 的模型，不在 MCP 内再次调用模型。
- Strict 使用 InferMatrixCopilot 配置的模型和本地仓库 checkout。
knowledge/是数据面；仓库、组件或模型规则不要硬编码进通用执行引擎。
运行产物默认在 ~/.infermatrix-copilot/runs/。密钥、机器路径和本地 checkout
配置只放 ~/.infermatrix-copilot/.env，不要提交。