AI 编程智能体的本地调度台
派活 · 排队 · 验证 · 接力 · 合并 —— 一个进程搞定
快速开始 · 核心能力 · 编排模式 · 任务接力 · 实时预览 · 多人模式 · 部署文档
Ash 是一个自托管的编排控制台，用来管理本地的 AI 编程智能体 CLI（Claude Code、Codex、Gemini 等）。它不替代这些工具，也不需要你的 API key —— 它负责的是调度：把任务分配给 agent，在隔离的 worktree 中执行，自动验证结果，最终合并回主干。
一个 Node 进程，一个端口，数据全在本地磁盘。
前置条件：Node.js >= 22.16、git，至少一个已安装并登录过的 agent CLI。
# 安装 agent CLI（至少一个）
npm install -g @anthropic-ai/claude-code && claude
npm install -g @openai/codex && codex# 安装并启动 Ash
git clone https://github.com/noroot777/ash.git && cd ash
npm run setup # 环境检查 → 依赖安装 → 构建 → MCP 接入
npm start # http://localhost:4317启动后：新建项目（填 git 仓库绝对路径，或直接从 Git URL 检出）→ 创建任务 → 选择执行器 → 运行。
Important
MCP 接入不可跳过。 agent 通过 MCP 工具 complete_task 提交完成状态。未接入 MCP 的 agent 无法交卷，所有任务将显示为失败。
验证：claude mcp list 中应显示 ash: … ✔ Connected。
手动接入方法见 docs/install.md。
🎯 智能体随意切换 — 任务运行中可随时切换不同的智能体、模型和智能水平，下一轮回复立即生效，因为上下文会跨智能体共享。
🔗 队列编排 — 串行队列按序推进，并行分组同时运行。失败任务自动跳过，重新排队时按规则归位。
🔍 自动验证 — 任务完成后触发验证轮（可配置多轮复审），在同一会话中运行。未通过则打回修复，上下文完整保留。
🖥️ 实时预览 — agent 改了前端代码，一键启动预览服务查看效果。项目设置中可配置多个预览服务（最多 8 个同时运行），自动检测仓库中的常见框架脚本，端口从专用池分配。多人模式下自动挂载认证反代，外部可安全访问。预览可随任务生命周期自动管理：重新运行时关旧起新，验收后自动清理。
✅ 一键验收 — 确认通过后自动合并到主干、清理 worktree 和临时分支。遇到冲突会唤醒来源任务处理。
📝 随手记 — 项目级别的快速笔记，列表内直接新建，多人模式下按人隔离。
💬 多智能体聊天 — 项目下的持久群聊频道，可拉入任意数量、任意类型的智能体成员（不限 Claude），用 @成员名 点名提问。被点名的 agent 可以读取项目文件后给出简短建议（咨询），也可以创建标准任务去真正执行修改（委派）。聊天上下文自动管理——后台预压缩长历史为摘要，不会因对话变长而丢失早期决策。/clear 重新开始上下文，旧消息仍可查看。
🗂️ 任务模式 — 跨项目鸟瞰所有在跑和待验收的任务，按项目分组，一键展开会话。
🤖 助手 — 侧栏底部打开，选择智能体后直接对话，无需项目也能用。可按描述检索历史任务、生成起手式草案、委派工作到其它项目。对话跨项目保留，/clear 重置上下文。
🔎 全局搜索 — ⌘K 搜任务标题、正文、会话内容，边打边出结果，毫秒级响应。
📲 移动端 — Expo 构建的 iOS/Android 客户端，查看任务、回复消息、操作团队，随时随地。
♻️ 重启存活 — agent 进程与 server 解耦。npm run restart 会自动检测在跑的任务：能接管的无感接管，不能接管的拦住不重启。在 macOS/Linux 上，单飞任务的 agent 进程完全不受重启影响（输出写文件而非管道）；团队调度台自动 --resume 接回。
Note
Windows 上重启会打断正在运行的单飞任务。 输出落盘的 detached 机制依赖 POSIX shell 重定向（/bin/sh -c），Windows 上没有等价实现，因此退化为管道模式 —— server 一重启管道断开，agent 进程随之终止。被打断的任务标记为 failed，可手动重试续跑。npm run restart 的安全闸在 Windows 上同样生效：它会提示有多少任务将被打断，不加 FORCE=1 不会动手。
单任务 — 一个任务指派一个 agent，最基础的使用方式。
串行队列 — 多个任务按序编排，前一个完成后自动启动下一个，适用于有依赖关系的工作流。
并行分组 — 一批无关联的任务同时运行，各自在独立 worktree 中工作。
团队模式 — 指派一个 agent 担任调度台（常驻会话），由它自行拆分子任务、分派执行者、汇总结果。支持团队预设和执行者配置。
讨论 — 两个不同的智能体（如 Claude + Codex）围绕同一议题轮番发言，各自独立思考、互相质疑，形成共同结论。中间设有人工闸口（可关闭），轮数可限制或不限。讨论结束后输出合稿，可一键转交给团队模式继续执行。讨论者 A / B 各自独立配置执行器、模型和智能水平。
验证循环 — 实现 → 验证 → 打回 → 修复 → 再验证，轮数可配，循环至通过后由用户验收合并。
跨机器任务迁移：把一台 Ash 上的任务——连同代码进度、对话历史和附件——接力到另一台 Ash 继续。
- git 状态 — 任务分支上的提交打成增量 bundle，未提交改动先做 WIP 提交
- CLI 会话 — claude / codex 的会话文件物理迁移，对端续跑时保留完整对话上下文
- 附件和产物 — 上传的图片、会话 trace、定时计划一并迁移，路径自动改写
- 审查历史 — 验证轮次和验收落账跟着任务走
- 设置 → 默认规则 → 添加目标机器地址（如
http://192.168.1.50:4317） - 打开任务 → 输入框上方 → 「接力到另一台机器」（支持批量接力）
- 预检通过后确认发送，可选到达后自动续跑
每台 Ash 实例有独立的 ed25519 密钥对。接力前校验目标机器指纹，首次配对核对一次即可。多人模式下接力按人授权（对端账号 key），传输可选加密。
| 情况 | 结果 |
|---|---|
| 会话文件迁移失败 | agent 全新起跑，任务正文嵌入首条消息，git 进度仍在 |
| 对端不是 git 仓库 | 退化为共享目录运行，代码不迁移 |
| 网络中断 | 本机标记「接力未确认」，重试幂等不重复导入 |
| 目标机换了机器 | 指纹对不上，打包之前就拒绝 |
| 对端没批准本机 | 预检如实报出，接力按钮按住不放 |
| 需要回到本机 | 横幅 → 「在本机继续」移除标记即可 |
完整的流程说明与故障排查见 docs/handoff.md。
任务改了前端或 Web 服务的代码后，可以直接在 Ash 里启动预览服务查看效果，不必离开界面手动起开发服务器。
- 脚本模式 — 填一条启动命令（如
npm run dev），Ash 从端口池分配空闲端口注入$PORT，启动后自动探测服务就绪并生成预览链接。 - 服务列表模式 — 配置多个预览服务（最多 8 个同时运行），分别标记为
web（面向浏览器）或service（后端依赖），Ash 并行启动并独立管理各自的生命周期。支持自动检测仓库中的常见框架脚本。
多人模式下（或手动开启），预览链接自动挂载认证反代——带一次性 token 的 URL 可安全分享给外部访问，无需额外配置。
预览随任务走：重新运行任务时自动关闭旧预览、启动新的；任务验收合并后自动清理预览进程和相关软链。启动过程中（依赖安装 + 服务就绪）用户随时可以取消。
开启多人模式后，一台 Ash 可以供多人使用，各有独立的账号、CLI 环境、项目可见性和资源隔离。
- 角色体系 — 管理员 / 成员，实例级与项目级双层权限
- CLI 额度隔离 — 可选「隔离」或「共用」两档，首次启动时选一次，设置里随时改
- 按人派发 — 跨人回合按「谁点的」跑，换执行器前显式确认
- 接力授权 — 接力凭对端账号 key 认人，不是认机器
- 可见性过滤 — 任务、随手记、搜索结果均按归属过滤
Warning
默认监听 0.0.0.0 且无鉴权（终端 API 本身就是个 shell）。请仅在可信网络中使用，或自行在前端部署反向代理进行认证。
内置 15 个 CLI 执行器配置，机器上安装了哪些就能使用哪些：
claude | codex | gemini | cursor | copilot |
opencode | qwen | grok | kimi | trae |
kiro | kilo | qoder | antigravity | pi |
通过「设置 → 执行器」可为每个 CLI 创建 profile（固定模型与智能水平）。任务级别可在三段式胶囊中逐项覆盖：先选执行器，再选模型，最后选智能水平——任务运行中也能随时切换，下一轮回复立即生效。添加新 CLI 只需一个 TypeScript 文件 — 见 catalog/README.md。
Ash 通过 Model Context Protocol 向 agent 暴露 28 个工具，覆盖任务全生命周期：
| 类别 | 工具 |
|---|---|
| 项目 / 分组 | resolve_project create_group resolve_group list_groups |
| 任务管理 | create_task_chain batch_create_tasks get_task list_tasks patch_task |
| 队列 | create_queue get_queue queue_insert queue_remove queue_reorder requeue_task |
| 生命周期 | run_task run_group stop_task complete_task pause_task accept_task |
| 协作 | ask_question answer_question report_stage dispatch dispute_review debate_reply |
| 旁观 | read_task_transcript |
read_task_transcript 读的是别的任务说过的话：拿到一个任务 id 就能看到它当时的指令、回复和结论，与界面上同一份语料。没有它时，agent 只能从工具清单得出「ash 不提供这个能力」，转去翻各家 CLI 自己的落盘文件 —— 那条路只对单一执行器成立。
server/ Hono 后端 — API、任务编排、进程管理、前端托管
web/ React + Vite + Tailwind 前端
shared/ 前后端共享类型
mcp/ MCP server — 28 个工具供 agent 调用
mobile/ Expo 移动端（iOS / Android）
scripts/ setup / restart / package（.mjs，跨平台）
技术选型
- SQLite — Node 22 内置的
node:sqlite，零原生编译依赖。代价是 Node 最低版本要求 22.16。 - Drizzle — 管理 schema，启动时自动补列，无需手动迁移。
- SSE — 替代 WebSocket。数据流为服务端单向推送（任务状态、输出、trace），对反代透明。
- 单实例锁 — 粒度是 DB 文件路径，不是端口。锁文件（
*.ash.lock）由 server 写入，restart 脚本读取以识别进程归属。 - 平台差异 — 收敛在
server/src/platform.ts一个文件。进程表、进程树击杀、端口查询按平台分发实现。Windows 能力缺口在文件头部标注。
| 变量 | 默认值 | 说明 |
|---|---|---|
PORT |
4317 |
服务端口（界面与 API 共用） |
ASH_DB |
./data/ash.db |
SQLite 数据库路径 |
所有持久化数据存放在 data/ 目录（数据库、运行记录、上传文件），该目录不入 git。备份迁移只需拷贝此目录。
npm run dev # 后端 :4317 + 前端 :5173（HMR，/api 代理到后端）
npm run build # 全量构建（shared → web → server → mcp）
npm run restart # 构建 + 后台常驻（自动检测任务安全）
npm run package # 生成分发包（仅入库文件，不含 data/）Restart 不是盲目的 kill + start。它会先问服务端「重启会真正打断几个任务」：
| 情况 | 行为 |
|---|---|
| 无任务 / 全部可接管 | 直接重启，全程无感 |
| 有会被打断的任务 | 拒绝重启，列出受影响任务 |
WAIT=1 |
等所有任务跑完再重启 |
FORCE=1 |
强制重启，被打断的标 failed |
| MCP 通道被占 | 默认跳过 MCP 刷新，不掐断交卷 |
前端修改后仅需 npm run build，server 从磁盘读取 web/dist，无需重启。
build / restart 只做「约定检查 → 类型 → 打包」，不再跑测试；回归自己显式跑：
npm run test:web # 前端全量回归（改完 web/ 交付前跑）
npm run test:web-gate # 上面那道 pre-push 闸自己的回归
npm -w server run test:queue # 队列推进与排序
npm -w server run test:accept-merge # 验收合并与冲突处理
npm -w server run test:review # 验证轮与证据落盘
npm -w server run test:detached # agent 重启存活
npm -w server run test:handoff # 跨机器接力Caution
端到端测试会实际启动 agent CLI，消耗真实 API 额度。
前端回归还有一道自动兜底：.githooks/pre-push 会在 push 前检查这批提交有没有碰 web/ 或 shared/，碰了才跑 npm run test:web（约 4 分钟），没碰直接放行。git push --no-verify 或 SKIP_WEB_TEST=1 git push 可跳过；worktree 里没装依赖时它只警告不拦。这道闸要 git config core.hooksPath .githooks（npm run setup 会自动配）。
所有任务运行后均显示 failed
MCP 未接入，agent 无法调用 complete_task。运行 claude mcp list 确认 ash 状态为 Connected。
界面空白或样式异常
前端产物未构建或已过期。执行 npm run build，无需重启 server。
派发任务时报 ENOENT
目标 CLI 未安装，或未在 server 进程的 PATH 中。建议从终端（而非 GUI 应用）启动 server。
claude 类任务 0 秒退出，报 --dangerously-skip-permissions cannot be used with root/sudo privileges
以 root 跑 ash 时所有 claude 执行器必然 0 秒失败。三条出路：
- 换非 root 用户跑 ash（推荐）
- 启动环境设
IS_SANDBOX=1（代价：agent 以 root 无确认地操作整台机器） - 在 bubblewrap 沙箱中跑 ash
Windows 上报 Filename too long
触发 260 字符路径限制。管理员 PowerShell 中启用 LongPathsEnabled，并执行 git config --global core.longpaths true。npm run setup 会自动检测。
📦 部署与运维 · 🔄 任务接力指南 · 🔌 供应商转发诊断 · 📋 事故与踩坑记录 · 🪟 Windows 测试基线