图中以 Telegram 为例，飞书链路完全一致。请求下行执行、结果回推到聊天——前台调用数秒内返回，后台 worker 跑完任务后自己把结果推回。
Hermes 只是消息入口 + 路由，真正的编码由本机的 claude CLI 完成。mobile-code
是中间的胶水层：解析项目、强制权限分级、在隔离分支上跑任务、再把结果汇报回来。
通勤路上、躺在沙发上，只要能发消息，就能让 Mac 上的 Claude Code 帮你改代码、跑测试、看结果。
以下能力均已实现并通过端到端实跑验收（Telegram / 飞书双通道、claude / codex 双后端）。 对应需求与验收文档见
docs/specs/。
- ✅ 远程编码 — 手机发自然语言消息，任务在 Mac 上的目标仓库执行，结果自动回推。
- ✅ 双 IM 通道，均为双向 — Telegram 与飞书都能「发消息触发 + 结果回推」。飞书走 自建应用：入站经 Hermes 网关（websocket、支持 @ 触发与发送者白名单），出站走应用消息 API。
- ✅ 双执行后端 —
--backend claude|codex自由切换，权限分级对后端无关，由各后端自己映射到 flags/sandbox。 - ✅ 手机端意图快捷词 —
看/查/分析走只读，改/修/实现走可编辑；脚本仍可用-t 1/-t 2。 - ✅ 权限分级白名单（默认拒绝） — tier 2 不放行裸
Bash，git commit/push、rm、sudo、curl、ssh、node -e等一律隐式拒绝。是护栏，不是沙箱。 - ✅ 分支隔离 — 每个任务独占
mobile/<job>分支，便于隔离与一键回滚。 - ✅ 提交 / 推送需显式确认 —
run只改文件，无权提交；你从手机上分别确认提交与推送。 - ✅ 结果必达 — worker 绝不静默失败，成功 / 失败 / 超时 / 异常每种结局都恰好推回一条消息。
- ✅ 项目别名外置化 —
mobile-code 注册 <别名> <路径>写入~/.mobile-code/projects.json，免改源码、免 rebuild。 - ✅ 通用 Agent Skill — 一份
SKILL.md可装到 Hermes / Claude Code / Agent SDK，教编排型 agent 如何调用本 CLI。
npm install
npm run build
mkdir -p ~/.local/bin
ln -sf "$PWD/dist/mobile-code.js" ~/.local/bin/mobile-code # 放到 `claude` 所在的目录
mobile-code --help然后创建 ~/.mobile-code/config，至少配置一个推送通道（Telegram 和/或飞书），并配好
Hermes 网关。完整步骤——bot/应用创建、权限、launchd 的 PATH 注意事项——见
docs/SETUP.md。
⚠️ dist/是生成的、已被 git 忽略。改完src/后要重新npm run build（~/.local/bin的符号链接指向编译产物，而非 TypeScript 源码）。
mobile-code ping # 健康检查
mobile-code <别名> "<任务>" # 跑任务（默认 tier 2）
mobile-code -t 1 <别名> "<任务>" # 显式指定分级（1 = 只读，2 = 可编辑）
mobile-code --backend codex <别名> "<任务>" # 选择执行后端（claude | codex）
mobile-code commit <别名> "<msg>" # 提交任务改动（独立、需显式确认）
mobile-code push <别名> # 推送任务分支（独立、需显式确认）
mobile-code log [job] # 打印某次 job 的日志（不传则取最新）
mobile-code projects # 列出项目别名
mobile-code register <别名> <路径> # 新增项目别名比数字分级更顺手——这才是你在手机上真正会打的：
| 快捷词 | 同义词 | 分级 | 能力 |
|---|---|---|---|
看 |
查 读 分析 总结 / read ask plan |
1 | 只读 |
改 |
修 做 实现 新增 / edit work fix |
2 | 可编辑，不能提交/推送 |
mobile-code 看 test 找出入口文件并总结
mobile-code 改 test 修复 sum 的 bug，跑 npm test
mobile-code 提交 test "fix: 修复 sum 计算错误"
mobile-code 推送 test
- 权限分级是白名单（默认拒绝）而非黑名单。 tier 2 传入显式
--allowedTools列表，且不放行裸Bash，因此git commit/push、rm、sudo、curl、ssh被隐式拒绝。这是一道护栏，不是沙箱。 - commit 与 push 是独立、需显式确认的步骤。
run任务只改文件，agent 无权提交或推送，你从手机上逐一确认。 - 每个任务跑在自己的
mobile/<job>分支上，便于隔离与轻松回滚。 - worker 绝不静默失败——成功、失败、超时、异常每种结局都会推回恰好一条消息。
mobile-code run 解析项目和权限分级、拿到按仓库的锁后，分离出一个后台 worker 并在数秒
内返回，因此网关调用永远不会阻塞。worker 跑任务、并自己把结果推回聊天——所以即使前台
调用早已返回，结果依然能送达。
完整设计见 CLAUDE.md 与 docs/mvp-spec.md。
下面是参考任务生命周期 + 验收闭环补的方向，优先级与方案待讨论：
- 任务绑定 Issue —
--issue 1234，结果摘要回写 issue 评论，获得持久 ID / 可追踪 / 可累积上下文。 - 开工前确认范围 — tier 2 detach 前先推一条「我要做 X、验收 Y，回复 y 继续」，避免跑偏空转。
- 任务迭代回流 —
--on <job>复用同一mobile/<job>分支接着改，不必每次新建 job。 - 在线看 diff / 预览 — worker 把 diff 生成静态 HTML / 临时链接推回 IM，手机点开看完整改动。
- git worktree 解串行 — 每个 job 独立工作区，lock 收窄到只保护 commit/push。
- 收尾延伸到 PR —
mobile-code pr <alias>把mobile/<job>开成 PR，而非直接 push。
| 路径 | 说明 |
|---|---|
src/cli.ts |
commander 入口：run / commit / push / log / register / projects |
src/backends/ |
执行后端（claude.ts、codex.ts）+ 分级→flags 映射 |
src/worker.ts |
分离出去的后台 worker |
src/notify.ts src/telegram.ts src/feishu.ts |
多通道结果推送 |
src/tiers.ts src/jobs.ts src/lock.ts src/config.ts |
分级、job 元数据、锁、配置 |
skills/.../mobile-code/SKILL.md |
给编排型 agent 用的通用 Agent Skill 契约 |
docs/specs/ |
功能需求文档与验收清单 |
运行时状态存在仓库之外的 ~/.mobile-code/（config、projects.json、logs/、jobs/、locks/）。
docs/SETUP.md— 安装、配置、Hermes/Telegram/飞书 设置CLAUDE.md— 架构、约定与安全模型详解docs/mvp-spec.md— 权威需求与设计docs/architecture.md— 架构图docs/acceptance.md— 验证清单
MIT