服务器与任务队列
hipmmcode serve 运行直连 HTTP + WebSocket 服务器,让远端客户端 —— 网页应用、手机、其他机器 —— 驱动完整的智能体会话。它说与 SDK 宿主相同的 stream-json 控制协议,并额外提供即发即忘的异步任务队列。
hipmmcode serve # 127.0.0.1:7777,自动生成 auth token
hipmmcode serve --port 9000 --auth-token S3CR3T
hipmmcode serve --host 0.0.0.0 --port 7777 # 非回环绑定会打印安全警告启动时写发现锁文件 ~/.hipmmcode/direct-connect.json(host、port、token),本机客户端可自动发现。所有请求用 Authorization: Bearer <token> 认证。
交互会话(WebSocket)
POST /sessions → { "session_id": "…", "workspace_id": "…", "ws_url": "…" }
GET /sessions/{id} → 会话状态 + work_dir + workspace_id
DELETE /sessions/{id} → 删除会话并终止其名下所有交互式终端
WS /sessions/{id}/subscribe → 双向 stream-json
POST /threads/{id}/review → 排队执行只读结构化审查
GET /threads/{id} → Thread 摘要
GET /threads/{id}/items → 游标分页的 Turn/Item 事件
GET /health → 服务器状态 + 任务计数WebSocket 上发送用户回合与控制请求(set_model、interrupt、权限应答),接收流式事件 —— 文本增量、工具卡片、结果 —— 与 stdio SDK 宿主完全一致。断线后可重连续接同一会话。同一 thread 只有一个执行 owner：第二个并发订阅返回 409，同一 tenant/workspace/thread 的脱离式回合按 FIFO 执行。
POST /threads/{id}/review 支持可选 focus、provider、model、max_turns、max_budget_usd。审查只暴露读类工具；变更型 Bash 仍进入正常审批桥并失败关闭。生成的 reviewOutput item 带规范化 finding、优先级、置信度、绝对路径和行号范围。
每个会话有一个 workspace_id,用来圈定它的长生命周期资源(主要是 exec_command 的 PTY 会话)。空闲回收、删除、任务结束时会自动终止其 PTY;DELETE /sessions/{id} 会返回终止了几个。
异步任务队列
提交任务、挂断、稍后取结果 —— 为"手机上发个任务,有空再看答案"而生:
# 提交(连接可以立刻断开)
curl -X POST http://127.0.0.1:7777/tasks \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"prompt": "审计仓库里的 TODO 并把报告写到 todos.md"}'
# → { "task_id": "task_…", "status": "queued" }
# 随时查进度 / 结果
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7777/tasks/task_…
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7777/tasks # 全部列出提交字段
| 字段 | 说明 |
|---|---|
prompt (必填) | 任务内容 |
work_dir | 运行的工作目录 |
provider / model | 本任务覆盖渠道/模型 |
max_turns | 限制工具迭代次数 |
max_budget_usd | 本任务硬性花费上限 |
webhook | 完成时收到完整任务记录 POST 的 URL |
dangerously_skip_permissions | 无人值守允许变更工具(见下) |
任务记录
GET /tasks/{id} 返回:status(queued → running → completed / error / interrupted)、result(最终文本)、is_error、实时进度(steps —— 已完成工具调用数 —— 加 last_activity 及其时间戳)、created_at / finished_at、生效配置。
值得了解的语义
- Detached —— 任务在后台跑,与你的连接无关。
- 持久化 —— 任务落盘,服务器重启后重载(保留 7 天)。重启时正在跑的任务重载为
interrupted。 - 失败关闭的权限 —— 无人在场时,任何权限弹窗默认拒绝;拒绝记录在任务记录里可见。传
dangerously_skip_permissions: true才有自主工具权 —— 仅限端到端可信的服务器。 - Webhook —— 完成时把完整记录 POST 到你的
webhook,不用轮询。
会员网关
把主机上的一条上游凭据(如 Codex 或 xAI OAuth)共享给队友,每人独立配额,而不分发原始 API Key:
# 主机:开启会员端点
hipmmcode serve --gateway --auth-token S3CR3T
# 或纯网关(仅会员):
hipmmcode serve --gateway-only
# 管理端:创建成员 + 一次性加入码
hipmmcode member create --name alice --quota 1000000
# 把激活码交给 Alice
# 成员机:
hipmmcode join <activation-code>
# 之后正常使用 hipmmcode;请求会签名到网关常用管理子命令:member list、member show、member set-quota、member disable、member delete。成员加入后可查自己的用量。完整表面见 hipmmcode member --help / hipmmcode join --help。
Claude 订阅桥(anthropic-claude)不能作为网关上游 —— 仅支持可复用 HTTP 凭据的渠道。
安全提示
- 默认绑定回环。要暴露,优先 SSH 隧道或带 TLS 的反向代理;裸
--host 0.0.0.0意味着任何持 token 的人都能以你的身份跑 shell 命令。 - auth token 守着每个路由。换 token = 带新
--auth-token重启。 - 工作区收敛:设置
HIPMMCODE_WORKSPACE_ROOT=/path后,请求的cwd超出该目录(含软链接逃逸,已做 canonicalize)一律拒绝。不设则保持本地任意 cwd 的历史行为。 - 多租户身份:
HIPMMCODE_TENANT_ID标记本服务器创建的所有资源(默认local-server);交互式终端会话只有所属 tenant/workspace/session 能访问,并按层级施加配额(HIPMMCODE_PTY_PER_AGENT/_PER_THREAD/_PER_WORKSPACE/_PER_TENANT/HIPMMCODE_MAX_PTY_SESSIONS)。 - 作用域持久化:应用事件通过
ThreadStore保存；本地实现按 tenant/workspace/thread 分目录，并用 advisory lock 保证跨进程序号单调。旧无作用域 JSONL 仍可读取。 - 加密凭据:设置高熵且至少 32 字符的
HIPMMCODE_MASTER_KEY后，MCP OAuth 凭据写入按作用域隔离的加密后端；首次读取时会迁移旧的属主只读 JSON token。