maxteam-daemon

简体中文 · English

一个在你自己终端里前台运行的小进程，把你的机器变成一台 MaxTeam 本地计算机。它通过 弹性 WebSocket 连接 MaxTeam 后端，为每个本地 agent 驱动一个按框架区分的子进程，并通过 环回凭证代理向该子进程暴露一个面向 agent 的 mt CLI —— 让工具调用能抵达后端， 却始终不把你的机器凭证交给 agent。

独立 clean-room 实现。对接一套通用的 agent-runtime 协议；不含从任何其他 daemon 复制的源码。专有软件（Proprietary），非开源，保留所有权利 —— 见 LICENSE； 其中随附的第三方开源依赖仍归其各自许可，见 THIRD_PARTY_NOTICES.md。

快速开始

npm install
npm run build
node dist/index.js --server-url https://backend.example.com --api-key <机器凭证>

选项：

| 标志 | 默认 | 含义 | |---|---|---| | --server-url <url> | (必填) | 后端 URL；http(s)→ws(s) 自动规范化。 | | --api-key <key> | (必填) | 机器凭证。只留在 daemon 内。 | | --backend-url <url> | 由 --server-url 推导 | 用于 agent-tool 转发的 HTTPS 基址。 | | --claude-command <cmd> | claude | 要 spawn 的 Claude Code 可执行程序。 | | --cursor-command <cmd> | cursor-agent | Cursor Agent 可执行程序。 | | --codex-command <cmd> | codex | Codex CLI 可执行程序。 | | --python-command <cmd> | python3 | AgentScope/Hermes 桥的 Python 解释器。 | | --agentscope-bridge <module> | mt_bridge.agentscope | AgentScope 桥的 Python 模块。 | | --hermes-bridge <module> | mt_bridge.hermes | Hermes 桥的 Python 模块。 | | --log-level <level> | info | debug\|info\|warn\|error（每行都脱敏）。 |

多框架 agent

后端通过 turn.start 帧的 agent_kind 字段按回合选择框架 （claude | cursor | codex | agentscope | hermes；省略时默认 claude）。 AgentScope 与 Hermes 是 Python 原生框架，需随你使用的框架一起安装桥包：

pip install -e ./python[agentscope]   # 或 [hermes]

桥（python/mt_bridge/）从 stdin 读取规范化的 {"type":"user","text":…} JSON 行， 并在 stdout 发出 message/delta/session/result 行；stdout 专供协议使用， 所有日志走 stderr。它只继承 MT_AGENT_PROXY_*，因此框架的工具调用经环回代理抵达 后端 —— 机器凭证绝不出现在它的环境里。

状态保存在 ~/.maxteam 下（可用 MAXTEAM_HOME 覆盖），仅属主可读 （目录 0700 / 文件 0600）。

架构

        MaxTeam 后端 (云端)
   wss://…/api/local-runtime/ws?key=<cred>   https://…/api/agent-tools/*
                │ 控制帧                              ▲ Bearer <cred> + X-MT-* 身份
                ▼                                     │
 ┌───────────────────────────────────────────────────────────────────────┐
 │ DAEMON  (持有机器凭证 —— 唯一存放它的地方)                              │
 │  WsClient ──onFrame──► RuntimeManager ──turn──► AgentDriver             │
 │   握手/ping/                      │ skills.*        (按 agent_kind)     │
 │   看门狗/退避                      ▼                 子进程             │
 │                        CredentialProxy (127.0.0.1:临时端口)             │
 │                        token → 能力校验 → 注入真实凭证                  │
 │                                    ▲ Bearer mtproxy_… (环回)            │
 │  ┌──────────────────────────────────────────────────────────────────┐ │
 │  │ AGENT 子进程  env = {…env, MT_AGENT_PROXY_URL, MT_AGENT_PROXY_...} │ │
 │  │ PATH 前置 <agentDir>/bin → `mt <verb>` → 环回代理                 │ │
 │  │ env 中无机器凭证 (只有一个 token 文件路径)                        │ │
 │  └──────────────────────────────────────────────────────────────────┘ │
 │  状态: ~/.maxteam 0700/0600 · MachineLock · 每行日志都过 Redactor      │
 └───────────────────────────────────────────────────────────────────────┘

文档

| 简体中文 | English | |---|---| | 架构文档 —— 图、子系统、设计思路 | Architecture | | 安装与使用 —— 各框架接入 | Install & Usage | | 更新日志 | Changelog |

子系统 (src/)

• transport/ —— 弹性 WS 客户端：端点规范化、ready 握手（一次性 resolve）、 30s ping / 90s 入站看门狗、退避+抖动、socket 世代守卫、致命关闭码分类、 有损不抛异常的 send。
• protocol/ —— 入站帧的 Zod 判别联合 + 出站 builder。
• manager/ —— 入站帧类型分发、工作区 realpath 校验（拒绝受保护根目录内的路径）、 agent 惰性物化。
• drivers/ —— 位于同一个 AgentDriver 接口之后的可插拔各框架 driver， 通过 drivers/registry.ts 按 agent_kind 分发：
  • claude —— 常驻 claude 子进程（stream-json）、会话 id 持久化 + --resume、一次性过期恢复。
  • cursor —— Cursor Agent；复用 Claude stream-json driver，命令换为 cursor-agent。
  • codex —— 每回合一次性 codex exec --json（不支持回合中途注入）、 线程恢复、透传 model_reasoning_effort。
  • agentscope / hermes —— Python 原生框架，经通用 BridgeDriver 用一套 规范化换行分隔 JSON 协议驱动随包发布的小桥（python/mt_bridge/）。 它们共享活动提取器 + 批处理器与启动/进度/截止计时器，并都继承同一套凭证隔离 环境（只有代理 URL + token 文件路径 —— 绝不含机器凭证）。
• credproxy/ —— 环回 HTTP 服务器；在可信侧做 verb→能力鉴权；转发时构建全新 请求头集合并注入凭证。
• toolcli/ —— 面向 agent 的 mt CLI（无 WS、无凭证）+ 每 agent 的 launcher/shim 生成器。
• state/ —— 仅属主可读的安全 fs 原语、home 布局、config/session 存储、基于 mkdir 的机器锁（过期自动清除，Linux start-token PID 复用守卫）、机器指纹。
• skills/ —— 在 <cwd>/.claude/skills/<slug>/ 上做盘点/移除，带 slug 校验与 路径穿越/符号链接逃逸拒绝。
• obs/ —— redactor（密钥、token、auth 头、?key=、home→~）与一个把每一行 都过它的 logger。

安全模型

agent 以绕过权限检查的方式运行，因此凭证代理是唯一信任边界：

• 机器凭证绝不出现在 agent 环境里 —— 只导出代理基址 URL 和一个 token 文件 路径。token 本身是一个 0600 文件，在 exec 时读取。
• 凭证只在代理的出站转发时注入，用全新构建的请求头集合（入站的 Authorization/Host/X-MT-* 绝不复制 —— 无身份伪造、无凭证走私）。
• 能力强制（verb → group）发生在代理里，而非 CLI。
• 环回目标绝不经 HTTP CONNECT 代理发送；SOCKS/PAC 被拒绝。
• 仅属主可读状态被创建、重新 chmod、并 stat 校验；任何 group/other 位都被拒绝。
• 致命 WS 关闭码停止重连循环（不产生凭证重试风暴）。

测试

npm test

含单元测试（redactor、path-guard、鉴权）与两个端到端集成测试：用假后端 + 假 agent 断言凭证由代理注入、agent 进程绝不可见 —— 一个走 Claude stream-json 路径， 一个走桥（AgentScope/Hermes）路径。

状态

v0.2.0 —— 在 M1–M10 核心（连接、协议、状态、锁、脱敏、凭证代理 + 工具 CLI、 带恢复的 driver、runtime manager、skills 盘点/移除）之上加入了可插拔多框架 driver 层（claude / cursor / codex / agentscope / hermes）。skills 安装/上传与 Windows ACL 加固是 M11 剩余项。见 CHANGELOG.md。