maestro-agent 0.0.1 → 0.0.3

package/README.md

@@ -1,3 +1,317 @@
-# maestro-agent
+# Maestro
 
-Placeholder package for maestro-agent.
+> The Conductor for AI Agents — 多智能体编排与执行系统
+
+Maestro 是一个本地优先的多 AI Agent 协作平台。它像一个乐团指挥，将多个 AI 编程助手（Claude Code、Codex、Gemini、Kiro、Aider 等）组织成一支协作团队，通过角色分工、任务调度和自动化流水线，让它们协同完成复杂的软件工程任务。
+
+## 设计理念
+
+### 角色优先，而非 Agent 优先
+
+传统的多 Agent 系统直接管理 Agent 实例。Maestro 引入了 **Role（角色）** 作为中间抽象层：
+
+```
+Task → Role → Agent → Runtime
+```
+
+- **Task** 描述要做什么（需求、验收标准）
+- **Role** 描述谁来做（能力、职责、提示词）
+- **Agent** 是执行者（绑定到某个 Role 的运行实例）
+- **Runtime** 是底层引擎（claude-code、codex、gemini 等 CLI 工具）
+
+这意味着你可以定义一个 `engineer` 角色，背后可以是 Claude Code 也可以是 Codex —— 系统根据可用性和能力自动调度。角色"永远在线"，Agent 可以来去自如。
+
+### 本地运行，零依赖外部服务
+
+Maestro Hub 运行在你的开发机上，使用 SQLite 存储，不需要 Docker、Redis 或任何云服务。一个 `maestro start` 就能启动整个系统。
+
+### 自动发现，即插即用
+
+启动时 Maestro 会扫描 PATH，自动发现已安装的 AI CLI 工具并注册为可用 Runtime。无需手动配置每个 Agent 的连接方式。
+
+### 渐进式自动化
+
+从手动分配任务开始，逐步开启 Autopilot：
+1. 手动创建任务、手动分配 → 熟悉系统
+2. 开启自动调度 → 系统自动将任务分配给空闲 Agent
+3. 开启 Chief → AI 项目经理自动拆解需求、创建任务、监控进度
+4. 配置 Cron/Hook → 事件驱动的全自动流水线
+
+## 核心概念
+
+### Workspace（工作区）
+
+顶层组织单元，代表一个目标或项目群。包含多个 Project。
+
+### Project（项目）
+
+属于某个 Workspace，有自己的工作目录和工作流定义。
+
+### Task（任务）
+
+最小工作单元。具有：
+- 状态流转：`open → claimed → review → done`
+- 优先级（P0-P3）
+- 依赖关系（DAG）
+- 验收标准（`done_when`）
+- 讨论线程
+
+### Role（角色）
+
+逻辑上的职能定义，用 Markdown 文件描述：
+
+```markdown
+---
+name: engineer
+extends: base/agent.md
+capabilities: [code, test, debug, deploy]
+headcount: 3
+---
+
+你是一名软件工程师，负责编写、测试和交付代码...
+```
+
+内置角色：
+| 角色 | 职责 |
+|------|------|
+| `engineer` | 编码、测试、部署 |
+| `researcher` | 调研、分析、方案设计 |
+| `writer` | 文档、内容创作 |
+| `critic` | Code Review、QA、测试 |
+| `chief` | 自主项目管理（AI PM） |
+
+### Agent（代理）
+
+绑定到 Role 的执行实例。一个 Role 可以有多个 Agent（水平扩展）。
+
+### Runtime（运行时）
+
+底层 AI CLI 工具。支持自动发现：
+
+| Runtime | CLI |
+|---------|-----|
+| claude-code | `claude` |
+| codex | `codex` |
+| gemini | `gemini` |
+| opencode | `opencode` |
+| aider | `aider` |
+| kiro | `kiro` |
+| cursor | `cursor` |
+| 更多... | 持续扩展 |
+
+## 架构概览
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Web Dashboard                      │
+│            (React + Tailwind + xterm.js)             │
+└──────────────────────┬──────────────────────────────┘
+                       │ HTTP / WebSocket
+┌──────────────────────▼──────────────────────────────┐
+│                    Hub Server                         │
+│  ┌─────────┐ ┌──────────┐ ┌───────────┐ ┌───────┐  │
+│  │ REST API│ │ EventBus │ │ Autopilot │ │ Chief │  │
+│  └─────────┘ └──────────┘ └───────────┘ └───────┘  │
+│  ┌──────────────┐ ┌────────────┐ ┌──────────────┐  │
+│  │Role Dispatch │ │ Workflows  │ │   Skills     │  │
+│  └──────────────┘ └────────────┘ └──────────────┘  │
+│  ┌──────────────────────────────────────────────┐   │
+│  │              SQLite (WAL mode)                │   │
+│  └──────────────────────────────────────────────┘   │
+└──────────────────────┬──────────────────────────────┘
+                       │ Transport (PTY / SSH / HTTP)
+┌──────────────────────▼──────────────────────────────┐
+│              Agent Runtimes                           │
+│  ┌─────────┐ ┌───────┐ ┌────────┐ ┌─────────────┐  │
+│  │ Claude  │ │ Codex │ │ Gemini │ │ OpenCode... │  │
+│  └─────────┘ └───────┘ └────────┘ └─────────────┘  │
+└─────────────────────────────────────────────────────┘
+```
+
+## 使用方式
+
+### CLI 命令
+
+```bash
+maestro init              # 初始化 .hub/ 目录
+maestro start             # 启动 Hub 服务
+maestro start --daemon    # 后台守护进程模式
+maestro start --port 8080 # 指定端口
+maestro stop              # 停止守护进程
+maestro doctor            # 系统诊断（检查 DB、运行时、角色等）
+maestro inbox             # Agent 收件箱操作
+maestro chat              # 工作区消息通信
+```
+
+### Web 控制台
+
+启动 Hub 后访问 `http://localhost:7423`，提供：
+
+- **看板视图** — Kanban 风格的任务面板
+- **甘特图** — 任务时间线与依赖关系可视化
+- **实时终端** — 通过 xterm.js 查看 Agent 的实时输出
+- **聊天面板** — 与 Agent 实时对话，支持 @mention
+- **运行时管理** — 查看和管理已连接的 Agent Runtime
+- **技能库** — 浏览和管理自动提取的可复用技能
+
+### API 驱动
+
+所有功能都通过 REST API 暴露，方便集成到你自己的工具链：
+
+```bash
+# 创建任务
+curl -X POST http://localhost:7423/api/tasks \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "实现用户认证模块",
+    "role": "engineer",
+    "priority": 1,
+    "done_when": "JWT 认证中间件通过所有测试"
+  }'
+
+# 查看所有 Agent
+curl http://localhost:7423/api/agents
+
+# 查看任务状态
+curl http://localhost:7423/api/tasks
+
+# WebSocket 事件流
+wscat -c ws://localhost:7423/space/events
+```
+
+### 实时事件
+
+通过 WebSocket 订阅系统事件，支持 glob 模式过滤：
+
+```javascript
+const ws = new WebSocket('ws://localhost:7423/space/events');
+ws.send(JSON.stringify({ subscribe: 'task.*' }));
+// 收到: task.created, task.claimed, task.completed ...
+```
+
+## Autopilot（自动驾驶）
+
+Autopilot 是 Maestro 的自动化引擎，统一管理：
+
+| 功能 | 说明 |
+|------|------|
+| 自动调度 | 将 open 状态的任务自动分配给匹配角色的空闲 Agent |
+| Cron 任务 | 定时触发的自动化操作 |
+| 计划任务 | 按计划自动创建任务实例 |
+| Webhook 路由 | 将外部事件（GitHub、Linear 等）路由到 Hook 处理器 |
+| 技能提取 | 从完成的会话中自动提取可复用的操作模式 |
+
+```bash
+# 通过 API 启动 Autopilot
+curl -X POST http://localhost:7423/api/autopilot/start
+
+# 查看状态
+curl http://localhost:7423/api/autopilot/status
+
+# 手动触发一次调度
+curl -X POST http://localhost:7423/api/autopilot/tick
+```
+
+## Chief（AI 项目经理）
+
+Chief 是一个可选的自主 Agent，充当 AI 项目经理的角色：
+
+- 定期审视全局状态（工作区、项目、任务、Agent 负载）
+- 自动拆解高层需求为具体任务
+- 发现阻塞并尝试解决
+- 调整 Agent 编制（扩缩容）
+- 向人类升级无法自主决策的问题
+
+Chief 的所有重大决策（创建项目、调整角色）都会发送到 Inbox 等待人类审批，不会擅自行动。
+
+配置：
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+# 或通过 API 配置
+curl -X PUT http://localhost:7423/api/config \
+  -H "Content-Type: application/json" \
+  -d '{"chief_model": "claude-sonnet-4-6", "chief_interval_min": 15}'
+```
+
+## 工作流引擎
+
+任务状态流转通过可定制的状态机管理：
+
+```
+open → claimed → review → done
+  ↓       ↓        ↓
+  └───────┴────→ blocked
+  └───────┴────→ abandoned
+```
+
+你可以为不同项目定义不同的工作流：
+
+```bash
+curl -X POST http://localhost:7423/api/workflows \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "strict-review",
+    "scope": "project",
+    "scope_id": "proj_xxx",
+    "statuses": ["open", "claimed", "review", "approved", "done"],
+    "actions": [
+      {"name": "claim", "from": ["open"], "to": "claimed"},
+      {"name": "submit", "from": ["claimed"], "to": "review"},
+      {"name": "approve", "from": ["review"], "to": "approved", "requires": ["critic"]},
+      {"name": "ship", "from": ["approved"], "to": "done"}
+    ]
+  }'
+```
+
+## 技能系统
+
+Maestro 会从 Agent 的工作会话中自动提取可复用的技能模式，存储为 Markdown 文件：
+
+```
+.hub/skills/
+├── deploy-to-production.md
+├── setup-jest-config.md
+└── database-migration.md
+```
+
+技能会在后续任务分配时注入到 Agent 的提示词中，让团队的经验得以积累和传承。
+
+## 通信集成
+
+| 渠道 | 说明 |
+|------|------|
+| Web Chat | 内置工作区聊天 |
+| Telegram | Bot 网关，支持斜杠命令 |
+| Lark/飞书 | Webhook 通知 |
+| Webhook | 通用入站 Webhook（GitHub、Linear 等） |
+
+```bash
+# 配置 Telegram Bot
+export MAESTRO_TELEGRAM_BOT_TOKEN=your-bot-token
+```
+
+## 传输层
+
+Agent 可以通过三种方式连接：
+
+| 方式 | 场景 |
+|------|------|
+| `local-pty` | 本地进程（默认，自动发现的 CLI） |
+| `ssh` | 远程开发机上的 Agent |
+| `http-api` | 通过 HTTP API 代理的远程 Agent |
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `ANTHROPIC_API_KEY` | Chief Agent 的 API Key | — |
+| `MAESTRO_CHIEF_MODEL` | Chief 使用的模型 | `claude-sonnet-4-6` |
+| `MAESTRO_CHIEF_BASE_URL` | 自定义 API 端点 | Anthropic 官方 |
+| `MAESTRO_TELEGRAM_BOT_TOKEN` | Telegram Bot Token | — |
+| `MAESTRO_HUB_URL` | Hub 地址（Agent 侧） | `http://localhost:7423` |
+| `MAESTRO_<RUNTIME>_PATH` | 指定 Runtime CLI 路径 | 自动发现 |
+| `MAESTRO_<RUNTIME>_MODEL` | 指定 Runtime 使用的模型 | Runtime 默认 |
+
+## License
+
+本项目为私有软件，保留所有权利。未经授权不得复制、修改或分发。

package/bin/maestro.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+
+import { main } from "../src/core/cli";
+
+main(process.argv.slice(2));

package/dist/web/assets/Connections-BMA04Ycg.js

@@ -0,0 +1,11 @@
+import{q as p,z as a,v as e,a as g,s as y,x as u}from"./index-C7kx39S9.js";import{R as j}from"./refresh-cw-BWX04Hg3.js";import{A as N}from"./activity-CIA8bIA4.js";/**
+ * @license lucide-react v1.16.0 - ISC
+ *
+ * This source code is licensed under the ISC license.
+ * See the LICENSE file in the root directory of this source tree.
+ */const k=[["path",{d:"M12 20v2",key:"1lh1kg"}],["path",{d:"M12 2v2",key:"tus03m"}],["path",{d:"M17 20v2",key:"1rnc9c"}],["path",{d:"M17 2v2",key:"11trls"}],["path",{d:"M2 12h2",key:"1t8f8n"}],["path",{d:"M2 17h2",key:"7oei6x"}],["path",{d:"M2 7h2",key:"asdhe0"}],["path",{d:"M20 12h2",key:"1q8mjw"}],["path",{d:"M20 17h2",key:"1fpfkl"}],["path",{d:"M20 7h2",key:"1o8tra"}],["path",{d:"M7 20v2",key:"4gnj0m"}],["path",{d:"M7 2v2",key:"1i4yhu"}],["rect",{x:"4",y:"4",width:"16",height:"16",rx:"2",key:"1vbyd7"}],["rect",{x:"8",y:"8",width:"8",height:"8",rx:"1",key:"z9xiuo"}]],w=p("cpu",k);/**
+ * @license lucide-react v1.16.0 - ISC
+ *
+ * This source code is licensed under the ISC license.
+ * See the LICENSE file in the root directory of this source tree.
+ */const M=[["path",{d:"m21 21-4.34-4.34",key:"14j7rj"}],["circle",{cx:"11",cy:"11",r:"8",key:"4ej97u"}]],C=p("search",M);function E(){const[i,v]=a.useState([]),[l,c]=a.useState(!0),[o,r]=a.useState(""),[d,h]=a.useState(null),n=()=>{c(!0),y("/runtimes").then(s=>{v(s),r("")}).catch(s=>r(s.message)).finally(()=>c(!1))};a.useEffect(()=>{n()},[]);const f=s=>{h(s),u(`/runtimes/${s}/healthcheck`,{}).then(()=>n()).catch(t=>r(t.message)).finally(()=>h(null))},b=()=>{u("/runtimes/discover",{}).then(()=>n()).catch(s=>r(s.message))};return e.jsxs("div",{className:"flex flex-col h-full overflow-hidden",children:[e.jsxs("div",{className:"h-[52px] border-b border-[hsl(var(--border))] flex items-center justify-between px-6 shrink-0 bg-[hsl(var(--card))/0.92] backdrop-blur-xl",children:[e.jsx("h1",{className:"text-lg font-semibold tracking-tight",children:"运行时"}),e.jsxs("div",{className:"flex items-center gap-2",children:[e.jsxs("button",{onClick:b,className:"inline-flex items-center gap-1.5 px-3 py-1.5 rounded-md border border-[hsl(var(--border))] bg-[hsl(var(--card))] text-xs font-medium hover:border-[hsl(var(--muted-foreground))] transition-colors",children:[e.jsx(C,{className:"w-3.5 h-3.5"}),"发现"]}),e.jsxs("button",{onClick:n,disabled:l,className:"inline-flex items-center gap-1.5 px-3 py-1.5 rounded-md border border-[hsl(var(--border))] bg-[hsl(var(--card))] text-xs font-medium hover:border-[hsl(var(--muted-foreground))] transition-colors disabled:opacity-50",children:[e.jsx(j,{className:`w-3.5 h-3.5 ${l?"animate-spin":""}`}),"刷新"]})]})]}),e.jsxs("div",{className:"flex-1 overflow-y-auto p-6",children:[o&&e.jsx("div",{className:"mb-4 p-3 rounded-lg bg-[hsl(var(--destructive))/0.08] border border-[hsl(var(--destructive))/0.2] text-sm text-[hsl(var(--destructive))]",children:o}),l?e.jsx("div",{className:"text-center py-12 text-sm text-[hsl(var(--muted-foreground))]",children:"加载中..."}):i.length===0?e.jsxs("div",{className:"text-center py-16 text-[hsl(var(--muted-foreground))]",children:[e.jsx(g,{className:"w-10 h-10 mx-auto mb-3 opacity-40"}),e.jsx("p",{className:"text-sm",children:"暂无运行时"}),e.jsx("p",{className:"text-xs mt-1 opacity-70",children:"点击「发现」来查找本地 Agent 运行时"})]}):e.jsx("div",{className:"space-y-3",children:i.map(s=>{var x;const t=((x=s.waterline)==null?void 0:x.utilization)??0,m=Math.round(t*100);return e.jsxs("div",{className:"bg-[hsl(var(--card))] border border-[hsl(var(--border))] rounded-xl p-4",children:[e.jsxs("div",{className:"flex justify-between items-start",children:[e.jsxs("div",{className:"flex-1",children:[e.jsxs("div",{className:"flex items-center gap-2 mb-1",children:[e.jsx(w,{className:"w-4 h-4 text-[hsl(var(--muted-foreground))]"}),e.jsx("span",{className:"font-medium text-sm",children:s.type||"unknown"}),e.jsx("span",{className:"text-[10px] font-mono px-1.5 py-0.5 rounded bg-[hsl(var(--muted))] text-[hsl(var(--muted-foreground))]",children:s.transport||"—"}),e.jsx("span",{className:`inline-flex items-center px-2 py-0.5 rounded-full text-[10px] font-mono font-medium ${s.status==="healthy"?"pill-success":s.status==="degraded"?"pill-warning":"pill-danger"}`,children:s.status||"unknown"})]}),e.jsxs("div",{className:"text-xs text-[hsl(var(--muted-foreground))] font-mono ml-6",children:[s.cmd&&e.jsx("span",{className:"truncate block max-w-md",children:s.cmd}),e.jsxs("span",{children:["容量: ",s.capacity??"—"]}),s.waterline&&e.jsxs("span",{className:"ml-3",children:["运行中: ",s.waterline.running]})]})]}),e.jsxs("button",{onClick:()=>f(s.id),disabled:d===s.id,className:"inline-flex items-center gap-1.5 px-3 py-1.5 rounded-md border border-[hsl(var(--border))] text-xs font-medium hover:border-[hsl(var(--muted-foreground))] transition-colors disabled:opacity-50 shrink-0",children:[e.jsx(N,{className:`w-3 h-3 ${d===s.id?"animate-pulse":""}`}),d===s.id?"检查中...":"健康检查"]})]}),s.capacity&&s.capacity>0&&e.jsxs("div",{className:"mt-3 ml-6",children:[e.jsxs("div",{className:"flex justify-between text-[11px] text-[hsl(var(--muted-foreground))] mb-1 font-mono",children:[e.jsx("span",{children:"利用率"}),e.jsxs("span",{className:"tabular-nums",children:[m,"%"]})]}),e.jsx("div",{className:"h-1.5 bg-[hsl(var(--muted))] rounded-full overflow-hidden",children:e.jsx("div",{className:`h-full rounded-full transition-all ${t>.8?"bg-[hsl(var(--destructive))]":t>.5?"bg-[hsl(var(--warning))]":"bg-[hsl(var(--success))]"}`,style:{width:`${Math.min(100,m)}%`}})})]})]},s.id)})})]})]})}export{E as default};