vaws-coordinator

为什么需要 mindie-coordinator？

在多人共用的昇腾（Ascend）NPU 服务器上改 vllm / vllm-ascend、调算子或跑评测时，开发者和 AI Agent 最头疼三件事：

1. 代码同步乱：手动 rsync 或在服务器上直接改代码，跑着跑着就不知道刚才那个分数到底是哪版代码跑出来的，还经常把别人的目录覆盖掉。

2. 抢卡撞车：几个人同时往 0 号卡上起服务，显存瞬间 OOM；或者任务崩了但子进程还占着卡和端口不放。

3. 环境每次重配太慢：每次切分支都要重新编译算子、重新检查 torch_npu 能不能 import，白白浪费十几分钟。

mindie-coordinator 作为运行在你本机的轻量级协调守护进程，通过 remote-dev 帮你把整套流程管得井井有条：

• 本地改代码，远端自动隔离同步：提交任务那一刻自动锁定你本地 Git 工作树（连同未提交的修改和子模块），增量同步到远端你专属的持久化容器（mindie-<你的用户名>）里的独立目录中，完全不动你本地的 HEAD 和暂存区。

• 宿主机统一排队分卡，跑完立即释放：通过部署在宿主机上的零依赖协调脚本统一分配物理 NPU 卡和服务端口（30000–45999）。既支持独占多卡，也支持显式指定单张卡跟别人共享调试（allow_external_busy=True）；任务结束或停止时自动清理整个进程树并归还 NPU 租约。

• 编译好的算子与环境智能复用：只要底层依赖和 C++/Ascend 算子没变、只改了 Python 代码，下次启动秒级复用已验证过的运行环境，省去重复编译和漫长的导入检查。

• 一套后台，三种用法：同时提供 5 个标准 MCP 工具（给 AI 编程助手用）、mindie 命令行工具（给终端用）和 Python TaskClient SDK（给脚本用）。

flowchart LR
    Dev["👩‍💻 本地 Git 代码库 & AI Agent"]
    Daemon["⚙️ mindie-coordinator<br/>(本机单用户守护进程)"]
    Container["🐳 远端专属容器 mindie-&lt;user&gt;<br/>(独立代码目录 + 算子缓存复用)"]
    HostQueue["🎛️ 宿主机 NPU 与端口队列<br/>(独占分卡 / 单卡共享 / 自动释放)"]

    Dev -->|"1. 提交任务 (mindie_run / mindie run)"| Daemon
    Daemon -->|"2. 增量同步 Git 快照 & 准备环境"| Container
    Daemon -->|"3. 申请物理 NPU 卡与空闲端口"| HostQueue
    HostQueue -->|"4. 注入设备租约启动 & 结束自动回收"| Container

Related MCP server: GRACE Orchestrator MCP

快速开始

方式一：直接把链接发给你的 Agent 自动安装/接入（推荐）

复制下面这句话发给你的 Claude Code、Codex、Kimi Code 或 Cursor，让它自动完成安装和 MCP 接入：

帮我安装并配置 https://github.com/mindie-agent/coordinator

如果你是收到上述指令的 AI Agent，请按以下步骤为当前用户完成 mindie-coordinator 的安装与 MCP 配置：

1. 检查环境要求：确认本机具备 Python >= 3.11、git、ssh 以及 uv（pyproject.toml 已锁定匹配的 remote-dev 与 mindie-diagnostics 版本，无需单独手动找版本）。

2. 在当前宿主客户端注册 MCP Server：

   • Claude Code（写入 .mcp.json 或直接运行命令）：

     claude mcp add mindie-coordinator -- uvx --from git+https://github.com/mindie-agent/coordinator@main mindie-coordinator task-server

   • Cursor（写入 .cursor/mcp.json）或通用 .mcp.json：

     {
       "mcpServers": {
         "mindie-coordinator": {
           "type": "stdio",
           "command": "uvx",
           "args": [
             "--from",
             "git+https://github.com/mindie-agent/coordinator@main",
             "mindie-coordinator",
             "task-server"
           ]
         }
       }
     }

   • Kimi Code（写入 .kimi-code/mcp.json，不要包含 type 字段）：

     {
       "mcpServers": {
         "mindie-coordinator": {
           "command": "uvx",
           "args": [
             "--from",
             "git+https://github.com/mindie-agent/coordinator@main",
             "mindie-coordinator",
             "task-server"
           ],
           "startupTimeoutMs": 30000,
           "toolTimeoutMs": 600000
         }
       }
     }

   • OpenAI Codex（追加到 .codex/config.toml）：

     [mcp_servers.mindie_coordinator]
     command = "uvx"
     args = ["--from", "git+https://github.com/mindie-agent/coordinator@main", "mindie-coordinator", "task-server"]

3. 验证命令可用：

   uvx --from git+https://github.com/mindie-agent/coordinator@main mindie --help

4. 告知用户：提示用户重启/新开对话后，即可直接使用 mindie_session、mindie_run、mindie_execution、mindie_finish、mindie_message 调度远端昇腾任务。

方式二：终端手动一行安装（适合人类开发者）

# 安装 mindie 与 mindie-coordinator 命令行工具到当前环境
uv pip install git+https://github.com/mindie-agent/coordinator@main

# 或者免安装直接通过 uvx 启动 MCP Task Server
uvx --from git+https://github.com/mindie-agent/coordinator@main mindie-coordinator task-server

真实使用场景

场景 1：把本地正在修改的 vllm 和 vllm-ascend 同步到远端 NPU 跑测试

不用手动传文件，也不用担心弄乱本地分支——直接指定本地源码目录和需要的 NPU 卡号，跑完自动释放卡：

from mindie_coordinator.task_client import TaskClient

client = TaskClient("/local/task-context.json")
run = client.run(
    '"$MINDIE_PYTHON" -c "import torch_npu; print(torch_npu.npu.device_count())"',
    sources={"vllm": "/local/vllm", "vllm-ascend": "/local/vllm-ascend"},
    resources={"devices": [0]},
    topology={"host": "npu-host"},
    wait_until="released",
    wait_timeout_seconds=180,
)
print(run["execution_id"], run["state"], run["resources_released"], run.get("stdout", ""))

场景 2：在终端直接提交本地 Shell 脚本并等待结果

写好了一个复杂的启动或评测脚本 business.sh？用 mindie run --script-file 一键推到远端受管执行：

# 提交本地脚本，同步 /local/app 源码，等待执行结束并释放资源
mindie run --script-file business.sh --source app=/local/app --wait released --wait-timeout-seconds 180

# 随时查看某个正在跑的任务状态或继续等待它结束
mindie execution --execution-id <EXECUTION_ID> --wait released --wait-timeout-seconds 180

# 查验该次执行实际用到的 Git 代码快照、环境准备耗时或编译回执
mindie execution --execution-id <EXECUTION_ID> --action evidence --section build --path kernel_name

场景 3：卡上已经有别人的服务，想显式跟他在同一张卡上共享调试

默认情况下分配器只挑完全空闲的 NPU 卡。如果你明确知道 0 号卡显存还够、想跟上面的外部进程共用这张卡跑个小实验，只需加上 allow_external_busy=True：

run = client.run(
    '"$MINDIE_PYTHON" test_small_op.py',
    resources={"devices": [0], "allow_external_busy": True},
    topology={"host": "npu-host"},
    wait_until="released",
)
# 任务结束时只会清理你自己的进程和租约，绝不会误杀卡上别人的原进程！

MCP 工具与 CLI 一览

1. 远端 SSH 环境、容器与 NPU 算力管理（无需前置会话即可直接调用）

SSH 认证统一由 remote-dev 管理。首次可用 remote-dev auth setup --host HOST --port 22 --user USER --prompt 录入一次密码，或在 mindie_hosts(action="bootstrap_key") 中传 password_env。默认尝试安装公钥并用实际密钥验证；如果密码已验证可用而公钥安装失败，保留密码认证并返回失败原因。后续聊天、coordinator 和 remote-dev 共享同一用户级凭据，不需要再次把密码交给 Agent。

密码默认保存在共享的 ~/.mindie/ssh/credentials.json；REMOTE_DEV_AUTH_DIR 可调整认证目录，REMOTE_DEV_CREDENTIAL_FILE 可指定凭据文件。此流程不调用系统钥匙串，也不请求系统账户密码。

machines.json 和 endpoints.json 仅保存 auth_ref 与验证后的 identity_file。宿主机上的 docker exec 使用宿主机认证；独立容器 SSH 端口使用自己的认证范围，可在绑定时指定 container_auth_ref / container_identity_file。同步 npu-top 时只传认证引用，npu-top 必须能够访问同一个用户级凭据库；监控注册失败不会改变已经成功的 SSH 认证结果。

2. 受管源码快照与任务执行生命周期

3. 编译槽、独占进程组与构建缓存复用机制

• 编译与跑卡分离（两阶段租约与 CPU 编译槽）：宿主机 HostQueue 将 CPU 编译槽（compile slots）与物理 NPU 执行租约分开管理——多个任务可以同时在后台拉代码、编扩展，互不阻塞；只有真正上卡跑测试或起服务时才按独占租约分配物理 NPU。

• 独占进程组与干净退出回收：每次受管执行都在独立的进程组中启动，任务自然结束、超时或收到 stop 指令时，协调器会排空整个子进程树并校验宿主机 /proc 与设备占用，确保不留僵尸进程、不漏端口，随后立即归还 NPU 租约。

• 跨任务原生构建缓存复用（native_cache_pool）：按 sha256(csrc 源码树 + CANN 版本 + SoC 型号 + Python ABI + 编译参数) 对编译产物做内容寻址缓存并记录 native_cache_receipt，相同源码与环境直接秒级复用（注：当前实机并行构建池验收覆盖 torch.utils.cpp_extension CPU C++ 扩展；完整 AscendC 算子工程的编译池复用正在持续扩展中）。

• 可追溯的执行清单（RunManifest）：mindie_coordinator/run_manifest.py 为每次运行记录完整的 Git 源码快照身份（source_head 与 snapshot_commit），并按需附带硬件遥测（hardware_telemetry）、缓存命中回执（native_cache_receipt）、活跃执行证明（active_execution_proof）与性能剖析引用（profile_summary_ref），方便随时复盘某次实验到底跑的是哪版代码和环境。

文档导航

仓库目录结构

本地开发与测试

共享认证开发版本需要同级目录的 remote-dev 源码；一起交给依赖解析器安装，不跳过依赖检查。

uv venv
uv pip install -e ../remote-dev -e ".[test]"
HOME="$(mktemp -d)" .venv/bin/python -m pytest

许可证

本项目采用 MIT License 开源。