From da702a4fd18091be0e22128e9e26fbdc4c14fa9b Mon Sep 17 00:00:00 2001 From: Ink-dark <209977110+Ink-dark@users.noreply.github.com> Date: Wed, 8 Jul 2026 23:48:23 +0000 Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E8=A1=A5=E5=85=A8=E4=B8=AD?= =?UTF-8?q?=E8=8B=B1=E5=8F=8C=20README=20+=20AiDriven=207=20=E5=B1=82?= =?UTF-8?q?=E6=9E=B6=E6=9E=84=E5=9B=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md 改为英文版（主），新增 AiDriven + 7 层架构图与逐层职责表 - 新增 README.zh-CN.md 中文版，结构与英文版对齐 - 两版顶部互链语言切换 - 7 层自上而下：IM 平台 / Adapter / Gateway / AI 驱动调度 / Sub-Agent / 沙箱与工具 / 存储与历史 --- README.md | 275 ++++++++++++++++++++++++++++++++-------------- README.zh-CN.md | 281 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 478 insertions(+), 78 deletions(-) create mode 100644 README.zh-CN.md diff --git a/README.md b/README.md index 935af3e..03a88ef 100644 --- a/README.md +++ b/README.md @@ -2,171 +2,290 @@ > Let the Orcha play. -在飞书 @Orcha 发一句话任务，AI 自主拆解、执行、测试、审核，把改动推到 Git 新分支。 +**English** · [简体中文](README.zh-CN.md) -## 它能做什么 +Orcha is an AI-driven coding agent triggered from Feishu IM: @-mention the bot +with one sentence, and it autonomously plans, codes, tests, reviews, and pushes +the change to a new `orcha/*` git branch — no public URL, no manual context +switching. -``` -你 @Orcha：在 utils/mod.rs 末尾追加 reverse_string 函数 +--- + +## What it does -Orcha： - 1. 鉴权入队 - 2. AI 自主调度 6 个 Sub-Agent（Observer→Planner→Worker→Tester→Reviewer→Exit） - 3. Worker 写文件前推审批卡片 → 你点 [批准] - 4. Tester 跑 cargo test 验证 - 5. 改动 commit 并推到 orcha/add-reverse-string 分支 - 6. 飞书卡片回报：分支名 + commit hash + commit message ``` +You @Orcha: append a reverse_string function at the end of utils/mod.rs + +Orcha: + 1. Authenticates and enqueues the task + 2. AI autonomously schedules 6 Sub-Agents (Observer → Planner → Worker → Tester → Reviewer → Exit) + 3. Before Worker writes a file, push an approval card → you click [Approve] + 4. Tester runs `cargo test` to verify + 5. Commit the change and push to branch `orcha/add-reverse-string` + 6. Feishu card reports back: branch name + commit hash + commit message +``` + +## Core capabilities + +- **Feishu trigger** — long-lived connection into Feishu; @-mention the bot to + start a task, no public URL required. +- **AI-driven scheduling** — an LLM decides at every step which Sub-Agent to + call next, when to exit, and how to recover from failure (max 10 rounds). +- **GitWorktree isolation** — each task edits code in its own worktree, the + source repo is never touched. +- **Human-in-the-loop approval** — before writing a file, running a command, or + deleting a file, Orcha pushes a Feishu approval card and waits for the + button callback. +- **Auto branch landing** — on success the change is committed and pushed to a + fresh `orcha/*` branch. +- **Circuit breakers** — max 10 rounds + 3 retries per step, no infinite loops. -## 核心能力 +--- -- **飞书触发** — 长连接接入飞书，@机器人一句话发起任务，无需公网 URL -- **AI 自主调度** — LLM 决定每一步调谁、何时结束、失败怎么重试（最多 10 轮） -- **GitWorktree 隔离** — 每个任务在独立 worktree 改代码，原 repo 不被污染 -- **人工审批** — 写文件 / 跑命令 / 删文件前推飞书审批卡片，按钮回调 -- **自动落分支** — 任务成功后自动 commit 并推到 `orcha/*` 新分支 -- **熔断保护** — 最多 10 轮 + 每步 3 次重试，防止死循环 +## Architecture — AiDriven + 7 layers -## 架构 +Orcha is a multi-process ensemble. The **AI-Driven Scheduler** (Layer 4) is the +brain: an LLM picks the next Sub-Agent at every step instead of following a +hard-coded pipeline. The 7 layers below isolate concerns from the IM edge down +to persistent storage. ``` -飞书 IM ──→ feishu-adapter ──IPC──→ orcha-gateway ──→ orcha-core - (鉴权/队列/审批) (AiDrivenCycleround) - │ - ▼ - GitWorktree 隔离工作区 - 改动 commit → orcha/* 分支 +┌──────────────────────────────────────────────────────────────────────────┐ +│ L1 IM Platform Layer Feishu / QQ (official SDK long connection) │ +│ ── user @-mentions bot, events flow in over WebSocket ────────────── │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ WS events (im.message.receive_v1, + │ card.action.trigger) +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L2 Adapter Layer orcha-feishu-adapter (Node.js / TS process) │ +│ ── fork of larksuite/openclaw-lark; protocol translation & reconnect │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ IPC (Unix Socket / Named Pipe / TCP, + │ JSON-line + 30s heartbeat) +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L3 Gateway Layer orcha-gateway (Rust process, first-class) │ +│ auth · whitelist · task queue · worker pool · approval orchestrator │ +│ watchdog: 35s read timeout, 3 misses → disconnect │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ Trigger + RoundEvent stream + │ (mpsc::Receiver) +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L4 AI-Driven Scheduler AiDrivenCycleround ◀── the brain │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ scheduler LLM sees task + all prior StepResult summaries │ │ +│ │ → decides next agent via `decide_next_agent` tool call │ │ +│ │ → calls SubAgent.run() → feeds result back → decides again │ │ +│ │ → emits `exit` when QA passes │ │ +│ │ circuit breakers: max_rounds (total decision steps) │ │ +│ │ max_retries (same-agent consecutive failures) │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ invokes one of +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L5 Sub-Agent Layer Observer · Planner · Worker · Tester · │ +│ Reviewer · Fixer · Exit │ +│ each implements SubAgent { name, run(&StepContext) -> StepOutput } │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ all fs / exec goes through +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L6 Sandbox & Tool Layer GitWorktree · FsSandbox · PathGuard · │ +│ ApprovalHook · Audit log │ +│ PathGuard: canonicalize + prefix-check, deny .git/.env/*.key, │ +│ 1MB read cap, binary detection │ +│ ApprovalHook: WriteFile / DeleteFile / RunCommand → Feishu card │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ persist +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L7 Storage & History Layer SQLite (WAL) · History JSONL · Memory JSONL │ +│ TaskStore · HistoryStore · MemoryStore │ +│ Gateway = sole writer, Shell = read-only connection │ +└──────────────────────────────────────────────────────────────────────────┘ ``` -## 仓库结构 +### Why AI-driven (not a fixed pipeline) + +The earlier `Cycleround` hard-coded `Observer → Planner → Worker → Tester → +Reviewer → Fixer`. `AiDrivenCycleround` (M7, feature-gated) hands scheduling +to an LLM: + +```rust +loop { + let decision = ai_decide_next_step(&task, &prior_steps); // { agent, reason } + match decision.agent.as_str() { + "observer" | "planner" | "worker" | "tester" | + "reviewer" | "fixer" => agent.run(&ctx), + "exit" => break, // QA passed + _ => /* unknown */, + } + if circuit_breaker_tripped() { break; } +} +``` + +Because the scheduler sees **all prior step summaries** every iteration, it +naturally avoids repeating the same mistake (solves the "Reviewer has no +cross-round memory" gap — AI cannot pass review just by rewriting the same +broken code in a different style). + +### Layer responsibilities at a glance + +| Layer | Crate / Process | Owns | +| :--- | :--- | :--- | +| L1 IM Platform | (external) Feishu / QQ | user-facing messaging | +| L2 Adapter | `orcha-feishu-adapter` (TS) | WS reconnect, event parse, IPC client | +| L3 Gateway | `orcha-gateway` (Rust) | auth, queue, worker pool, approval, IPC server | +| L4 AI Scheduler | `orcha-core` `AiDrivenCycleround` | per-step LLM decision, circuit breakers, event stream | +| L5 Sub-Agent | `orcha-core` `sub_agents` / `llm_agents` | Observer/Planner/Worker/Tester/Reviewer/Fixer | +| L6 Sandbox & Tool | `orcha-core` `sandbox` / `path_guard` / `approval` | worktree, path safety, human approval, audit | +| L7 Storage | `orcha-core` `store` / `history` / `memory` | SQLite + JSONL persistence | + +--- + +## Repository layout ``` packages/ -├── orcha-sdk/ 数据模型（Task / Artifact / Event / Step） -├── orcha-core/ 大脑：Cycleround 调度 + Sub-Agent + GitWorktree -├── orcha-llm/ LLM 客户端（OpenAI 兼容，含 tool calling） -├── orcha-gateway/ Gateway：IPC server + 鉴权 + 任务队列 + 审批 -├── orcha-shell/ Web UI + HTTP API（可视化面板） -├── orcha-cli/ CLI 入口（init / fix / shell / history） -└── orcha-feishu-adapter/ 飞书 Adapter（TypeScript，长连接 + IPC） +├── orcha-sdk/ Data models (Task / Artifact / Event / Step) +├── orcha-core/ Brain: Cycleround + Sub-Agent + GitWorktree (L4–L7) +├── orcha-llm/ LLM client (OpenAI-compatible, with tool calling) +├── orcha-gateway/ Gateway: IPC server + auth + task queue + approval (L3) +├── orcha-shell/ Web UI + HTTP API (visualization panel, read-only) +├── orcha-cli/ CLI entry (init / fix / shell / history) +└── orcha-feishu-adapter/ Feishu adapter (TypeScript, long connection + IPC) (L2) scripts/ start.ps1 / stop.ps1 / dev-env.ps1.example docs/ ROADMAP.md / SPEC.md / ARCHITECTURE_ANALYSIS.md ``` -## 快速开始 +--- + +## Quick start -### 前置依赖 +### Prerequisites - Rust 1.75+ - Node.js 20+ - Git -- PowerShell 5.1+（Linux/macOS 参考 [docs/LOCAL_RUN.md](docs/LOCAL_RUN.md)） +- PowerShell 5.1+ (Linux/macOS: see [docs/LOCAL_RUN.md](docs/LOCAL_RUN.md)) -### 1. 配置 +### 1. Configure ```powershell copy scripts\dev-env.ps1.example scripts\dev-env.ps1 notepad scripts\dev-env.ps1 ``` -填入 LLM API key 和飞书凭证： +Fill in the LLM API key and Feishu credentials: + ```powershell -$env:ORCHA_LLM_API_KEY = "sk-..." -$env:ORCHA_FEISHU_APP_ID = "cli_xxx" +$env:ORCHA_LLM_API_KEY = "sk-..." +$env:ORCHA_FEISHU_APP_ID = "cli_xxx" $env:ORCHA_FEISHU_APP_SECRET = "..." -$env:ORCHA_ADAPTER_MOCK = "0" # 0=真实飞书 +$env:ORCHA_ADAPTER_MOCK = "0" # 0 = real Feishu ``` -### 2. 飞书应用 +### 2. Feishu app -1. 飞书开放平台 → 创建企业自建应用 -2. 事件订阅 → 选「使用长连接接收事件」（无需公网 URL） -3. 订阅事件：`im.message.receive_v1` + `card.action.trigger` -4. 权限：`im:message` / `im:message:send_as_bot` / `im:chat:readonly` -5. 应用发布并加到群聊 +1. Feishu Open Platform → create an enterprise self-built app +2. Event subscription → choose "Use long connection to receive events" (no public URL) +3. Subscribe to: `im.message.receive_v1` + `card.action.trigger` +4. Permissions: `im:message` / `im:message:send_as_bot` / `im:chat:readonly` +5. Publish the app and add it to a group chat -### 3. 配置 config.toml +### 3. Edit `config.toml` + +Edit `.orcha/config.toml`, key entries: -编辑 `.orcha/config.toml`，关键项： ```toml [llm] api_key_env = "ORCHA_LLM_API_KEY" -base_url = "https://api.deepseek.com/v1" -model = "deepseek-chat" +base_url = "https://api.deepseek.com/v1" +model = "deepseek-chat" [[auth.whitelist]] platform = "feishu" -group = "*" # 开发调试用通配，生产改具体 chat_id +group = "*" # wildcard for dev; use a real chat_id in production [workspace] -repo = "D:/YourRepo" # 飞书触发任务的默认 repo -worktree = true +repo = "D:/YourRepo" # default repo for Feishu-triggered tasks +worktree = true [approval] -timeout_secs = 1800 # 30 分钟审批超时 +timeout_secs = 1800 # 30-minute approval timeout ``` -完整配置参考 [docs/SPEC.md](docs/SPEC.md)。 +Full config reference: [docs/SPEC.md](docs/SPEC.md). -### 4. 启动 +### 4. Start ```powershell .\scripts\start.ps1 ``` -### 5. 发任务 +### 5. Send a task + +In a Feishu group or DM, @-mention Orcha: -飞书群或私聊 @Orcha： ``` -@Orcha 在 utils/mod.rs 末尾追加 reverse_string 函数 +@Orcha append a reverse_string function at the end of utils/mod.rs ``` -任务完成后飞书卡片显示： +On completion the Feishu card shows: + ``` -✅ 完成 -共 7 轮，分支: orcha/add-reverse-string (ed4fc73) +✅ Done +7 rounds, branch: orcha/add-reverse-string (ed4fc73) feat(utils): add reverse_string function ``` -### 6. 查看结果 +### 6. Inspect the result ```powershell git -C D:/YourRepo branch --list 'orcha/*' git -C D:/YourRepo show orcha/add-reverse-string ``` -## 运维 +--- + +## Operations ```powershell -# 实时日志 +# Tail logs Get-Content D:\orcha\logs\gateway.log.err -Wait -Tail 20 -Encoding UTF8 -Get-Content D:\orcha\logs\adapter.log -Wait -Tail 20 -Encoding UTF8 +Get-Content D:\orcha\logs\adapter.log -Wait -Tail 20 -Encoding UTF8 -# 停止 / 重启 +# Stop / restart .\scripts\stop.ps1 .\scripts\start.ps1 -Restart ``` -## 开发 +## Development ```powershell cargo fmt --all -cargo test # 全 workspace +cargo test # whole workspace cargo clippy --all-targets -- -D warnings ``` -## 文档 +Feature flags: + +- **`llm`** — opt-in for `orcha-core`, default-on for `orcha-gateway`. Enables + `LlmPlanner` / `LlmWorker` / `LlmReviewer` / `AiDrivenCycleround`. Without + it, all agents are deterministic (no network) — CI-safe. +- **`sqlite`** — opt-in. Swaps `FileTaskStore` for `SqliteTaskStore` (rusqlite + with bundled SQLite, WAL mode + cross-process locking). + +## Documentation -- [docs/SPEC.md](docs/SPEC.md) — 系统规范（v0.1） -- [docs/ROADMAP.md](docs/ROADMAP.md) — M0→M8 开发路线图 -- [docs/ARCHITECTURE_ANALYSIS.md](docs/ARCHITECTURE_ANALYSIS.md) — 架构分析 -- [docs/DEPLOYMENT_TOPOLOGY.md](docs/DEPLOYMENT_TOPOLOGY.md) — 部署拓扑 -- [docs/LOCAL_RUN.md](docs/LOCAL_RUN.md) — 本地运行指南 +- [docs/SPEC.md](docs/SPEC.md) — system specification (v0.1) +- [docs/ROADMAP.md](docs/ROADMAP.md) — M0 → M9 roadmap +- [docs/ARCHITECTURE_ANALYSIS.md](docs/ARCHITECTURE_ANALYSIS.md) — architecture analysis +- [docs/DEPLOYMENT_TOPOLOGY.md](docs/DEPLOYMENT_TOPOLOGY.md) — deployment topology +- [docs/LOCAL_RUN.md](docs/LOCAL_RUN.md) — local run guide -## 里程碑 +## Milestones -M0-M7 已完成，M8 Self-Evolve 进行中。详见 [docs/ROADMAP.md](docs/ROADMAP.md)。 +M0–M7 are complete, M8 Plugin system is in progress. See +[docs/ROADMAP.md](docs/ROADMAP.md). ## License diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..e106486 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,281 @@ +# Orcha + +> Let the Orcha play. + +[English](README.md) · **简体中文** + +Orcha 是一个由 AI 驱动、经飞书 IM 触发的编码 Agent：在飞书 @ 机器人发一句话任务， +它自主拆解、规划、写码、测试、审核，把改动推到 `orcha/*` 新分支——无需公网 URL， +无需手动切换工具。 + +--- + +## 它能做什么 + +``` +你 @Orcha：在 utils/mod.rs 末尾追加 reverse_string 函数 + +Orcha： + 1. 鉴权入队 + 2. AI 自主调度 6 个 Sub-Agent（Observer → Planner → Worker → Tester → Reviewer → Exit） + 3. Worker 写文件前推审批卡片 → 你点 [批准] + 4. Tester 跑 cargo test 验证 + 5. 改动 commit 并推到 orcha/add-reverse-string 分支 + 6. 飞书卡片回报：分支名 + commit hash + commit message +``` + +## 核心能力 + +- **飞书触发** — 长连接接入飞书，@ 机器人一句话发起任务，无需公网 URL。 +- **AI 驱动调度** — LLM 在每一步决定下一步调哪个 Sub-Agent、何时结束、失败怎么 + 重试（最多 10 轮）。 +- **GitWorktree 隔离** — 每个任务在独立 worktree 改代码，原 repo 不被污染。 +- **人工审批** — 写文件 / 跑命令 / 删文件前推飞书审批卡片，按钮回调。 +- **自动落分支** — 任务成功后自动 commit 并推到 `orcha/*` 新分支。 +- **熔断保护** — 最多 10 轮 + 每步 3 次重试，防止死循环。 + +--- + +## 架构 — AiDriven + 7 层 + +Orcha 是一个多进程协作的 ensemble。**AI 驱动调度层**（Layer 4）是大脑：LLM 在 +每一步选择下一个 Sub-Agent，而非走硬编码流水线。下面 7 层从 IM 边缘到持久化存储 +逐层隔离关注点。 + +``` +┌──────────────────────────────────────────────────────────────────────────┐ +│ L1 IM 平台层 飞书 / QQ（官方 SDK 长连接） │ +│ ── 用户 @ 机器人，事件经 WebSocket 流入 ───────────────────────────── │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ WS 事件（im.message.receive_v1、 + │ card.action.trigger） +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L2 Adapter 层 orcha-feishu-adapter（Node.js / TS 进程） │ +│ ── fork 自 larksuite/openclaw-lark；协议翻译 + 自动重连 │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ IPC（Unix Socket / Named Pipe / TCP， + │ JSON line + 30s 心跳） +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L3 Gateway 层 orcha-gateway（Rust 进程，一等公民） │ +│ 鉴权 · 白名单 · 任务队列 · worker 池 · 审批编排 │ +│ watchdog：35s 读超时，连续 3 次未心跳 → 断开 │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ Trigger + RoundEvent 事件流 + │ (mpsc::Receiver) +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L4 AI 驱动调度层 AiDrivenCycleround ◀── 大脑 │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ 调度 LLM 看到 task + 全部前序 StepResult 摘要 │ │ +│ │ → 通过 `decide_next_agent` 工具调用决定下一步调谁 │ │ +│ │ → 调 SubAgent.run() → 把结果回喂 → 再决策 │ │ +│ │ → QA 通过后产出 `exit` 结束调度 │ │ +│ │ 熔断：max_rounds（总决策步数） │ │ +│ │ max_retries（同一 agent 连续失败次数） │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ 调用其中一个 +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L5 Sub-Agent 层 Observer · Planner · Worker · Tester · │ +│ Reviewer · Fixer · Exit │ +│ 每个实现 SubAgent { name, run(&StepContext) -> StepOutput } │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ 所有 fs / exec 都经过 +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L6 沙箱与工具层 GitWorktree · FsSandbox · PathGuard · │ +│ ApprovalHook · Audit 日志 │ +│ PathGuard：canonicalize + 前缀校验，拒 .git/.env/*.key， │ +│ 读 1MB 上限，二进制检测 │ +│ ApprovalHook：WriteFile / DeleteFile / RunCommand → 飞书卡片 │ +└──────────────────────────────────┬───────────────────────────────────────┘ + │ 持久化 +┌──────────────────────────────────▼───────────────────────────────────────┐ +│ L7 存储与历史层 SQLite (WAL) · History JSONL · Memory JSONL │ +│ TaskStore · HistoryStore · MemoryStore │ +│ Gateway 独占写，Shell 只读连接 │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +### 为什么 AI 驱动（而非固定流水线） + +早期 `Cycleround` 硬编码 `Observer → Planner → Worker → Tester → Reviewer → +Fixer` 顺序。`AiDrivenCycleround`（M7，feature gate）把调度权交给 LLM： + +```rust +loop { + let decision = ai_decide_next_step(&task, &prior_steps); // { agent, reason } + match decision.agent.as_str() { + "observer" | "planner" | "worker" | "tester" | + "reviewer" | "fixer" => agent.run(&ctx), + "exit" => break, // QA 通过 + _ => /* 未知 */, + } + if circuit_breaker_tripped() { break; } +} +``` + +由于调度 LLM 每次迭代都能看到**全部前序步骤摘要**，自然不会重蹈覆辙 +（解决"Reviewer 无跨轮记忆"的 gap——AI 无法靠换种写法蒙混过同一拒绝理由）。 + +### 各层职责一览 + +| 层 | Crate / 进程 | 负责的事 | +| :--- | :--- | :--- | +| L1 IM 平台 | （外部）飞书 / QQ | 用户侧消息收发 | +| L2 Adapter | `orcha-feishu-adapter` (TS) | WS 重连、事件解析、IPC 客户端 | +| L3 Gateway | `orcha-gateway` (Rust) | 鉴权、队列、worker 池、审批、IPC 服务端 | +| L4 AI 调度 | `orcha-core` `AiDrivenCycleround` | 每步 LLM 决策、熔断、事件流 | +| L5 Sub-Agent | `orcha-core` `sub_agents` / `llm_agents` | Observer/Planner/Worker/Tester/Reviewer/Fixer | +| L6 沙箱与工具 | `orcha-core` `sandbox` / `path_guard` / `approval` | worktree、路径安全、人工审批、审计 | +| L7 存储 | `orcha-core` `store` / `history` / `memory` | SQLite + JSONL 持久化 | + +--- + +## 仓库结构 + +``` +packages/ +├── orcha-sdk/ 数据模型（Task / Artifact / Event / Step） +├── orcha-core/ 大脑：Cycleround + Sub-Agent + GitWorktree（L4–L7） +├── orcha-llm/ LLM 客户端（OpenAI 兼容，含 tool calling） +├── orcha-gateway/ Gateway：IPC server + 鉴权 + 任务队列 + 审批（L3） +├── orcha-shell/ Web UI + HTTP API（可视化面板，只读） +├── orcha-cli/ CLI 入口（init / fix / shell / history） +└── orcha-feishu-adapter/ 飞书 Adapter（TypeScript，长连接 + IPC）（L2） +scripts/ start.ps1 / stop.ps1 / dev-env.ps1.example +docs/ ROADMAP.md / SPEC.md / ARCHITECTURE_ANALYSIS.md +``` + +--- + +## 快速开始 + +### 前置依赖 + +- Rust 1.75+ +- Node.js 20+ +- Git +- PowerShell 5.1+（Linux/macOS 参考 [docs/LOCAL_RUN.md](docs/LOCAL_RUN.md)） + +### 1. 配置 + +```powershell +copy scripts\dev-env.ps1.example scripts\dev-env.ps1 +notepad scripts\dev-env.ps1 +``` + +填入 LLM API key 和飞书凭证： + +```powershell +$env:ORCHA_LLM_API_KEY = "sk-..." +$env:ORCHA_FEISHU_APP_ID = "cli_xxx" +$env:ORCHA_FEISHU_APP_SECRET = "..." +$env:ORCHA_ADAPTER_MOCK = "0" # 0=真实飞书 +``` + +### 2. 飞书应用 + +1. 飞书开放平台 → 创建企业自建应用 +2. 事件订阅 → 选「使用长连接接收事件」（无需公网 URL） +3. 订阅事件：`im.message.receive_v1` + `card.action.trigger` +4. 权限：`im:message` / `im:message:send_as_bot` / `im:chat:readonly` +5. 应用发布并加到群聊 + +### 3. 配置 config.toml + +编辑 `.orcha/config.toml`，关键项： + +```toml +[llm] +api_key_env = "ORCHA_LLM_API_KEY" +base_url = "https://api.deepseek.com/v1" +model = "deepseek-chat" + +[[auth.whitelist]] +platform = "feishu" +group = "*" # 开发调试用通配，生产改具体 chat_id + +[workspace] +repo = "D:/YourRepo" # 飞书触发任务的默认 repo +worktree = true + +[approval] +timeout_secs = 1800 # 30 分钟审批超时 +``` + +完整配置参考 [docs/SPEC.md](docs/SPEC.md)。 + +### 4. 启动 + +```powershell +.\scripts\start.ps1 +``` + +### 5. 发任务 + +飞书群或私聊 @Orcha： + +``` +@Orcha 在 utils/mod.rs 末尾追加 reverse_string 函数 +``` + +任务完成后飞书卡片显示： + +``` +✅ 完成 +共 7 轮，分支: orcha/add-reverse-string (ed4fc73) + +feat(utils): add reverse_string function +``` + +### 6. 查看结果 + +```powershell +git -C D:/YourRepo branch --list 'orcha/*' +git -C D:/YourRepo show orcha/add-reverse-string +``` + +--- + +## 运维 + +```powershell +# 实时日志 +Get-Content D:\orcha\logs\gateway.log.err -Wait -Tail 20 -Encoding UTF8 +Get-Content D:\orcha\logs\adapter.log -Wait -Tail 20 -Encoding UTF8 + +# 停止 / 重启 +.\scripts\stop.ps1 +.\scripts\start.ps1 -Restart +``` + +## 开发 + +```powershell +cargo fmt --all +cargo test # 全 workspace +cargo clippy --all-targets -- -D warnings +``` + +Feature flag： + +- **`llm`** — `orcha-core` 可选开启，`orcha-gateway` 默认开启。启用 + `LlmPlanner` / `LlmWorker` / `LlmReviewer` / `AiDrivenCycleround`。不开启时 + 所有 agent 都是确定性实现（无网络调用），CI 友好。 +- **`sqlite`** — 可选开启。把 `FileTaskStore` 换成 `SqliteTaskStore` + （rusqlite + bundled SQLite，WAL 模式 + 跨进程锁）。 + +## 文档 + +- [docs/SPEC.md](docs/SPEC.md) — 系统规范（v0.1） +- [docs/ROADMAP.md](docs/ROADMAP.md) — M0 → M9 开发路线图 +- [docs/ARCHITECTURE_ANALYSIS.md](docs/ARCHITECTURE_ANALYSIS.md) — 架构分析 +- [docs/DEPLOYMENT_TOPOLOGY.md](docs/DEPLOYMENT_TOPOLOGY.md) — 部署拓扑 +- [docs/LOCAL_RUN.md](docs/LOCAL_RUN.md) — 本地运行指南 + +## 里程碑 + +M0–M7 已完成，M8 Plugin 子代理体系进行中。详见 [docs/ROADMAP.md](docs/ROADMAP.md)。 + +## License + +MIT