Quickstart

目标：在你自己的仓库里跑通第一个端到端任务，≤ 5 分钟。

1. 启动 headless 服务器

cd /path/to/your/repo
opencorvus serve

默认监听 127.0.0.1:7878。常用 flag：

flag	说明
--hostname 0.0.0.0	对外监听；设置 OPENCORVUS_SERVER_PASSWORD 后启用 HTTP Basic Auth
--port 7878	改端口
--project-dir <path>	指定工作仓库
--mdns	启用 mDNS 服务发现

如果暴露到 localhost 以外且没有设置 OPENCORVUS_SERVER_PASSWORD，server 会启动，但会打印 server is unsecured，并且不会启用 HTTP Basic Auth。

2. 打开 UI（可选）

浏览器访问 http://127.0.0.1:7878/ui/ 即可看到 Overlay 面板。也可另开一个 Tauri 原生窗：

bun run dev:overlay   # repo root

3. 创建一个任务（HTTP）

curl -X POST http://127.0.0.1:7878/task \
  -H "content-type: application/json" \
  -H "x-opencorvus-directory: $PWD" \
  -d '{
    "request": "为 src/foo.ts 新增单元测试，覆盖 happy path 与 2 条错误路径。"
  }'

响应：202 + { "task_id": "tsk_..." }。

4. 监听进度（SSE）

curl -N http://127.0.0.1:7878/task/<task_id>/events

你会看到 orchestrator 和各阶段事件，例如 requirements、architect、goal.running、integrity、acceptance_running、done。

失败时会看到 replan.triggered 或 retry.triggered，然后回到执行阶段。

5. 常用任务端点

端点	用途	目录
GET /tasks	项目任务列表	需要
GET /task/<id>	单任务状态	不需要
GET /task/<id>/board	Kanban 视图	不需要
POST /task/<id>/message	追加用户消息（follow-up）	需要
POST /task/<id>/retry	保持 plan，重试执行	需要
POST /task/<id>/replan	丢弃当前 plan，重新规划	需要
POST /task/<id>/cancel	取消任务	需要

6. 通过 Slack 创建任务

export SLACK_BOT_TOKEN=xoxb-...
export SLACK_APP_TOKEN=xapp-...
bun run --cwd packages/channel-runtime dev

在任何 Slack 频道里 at 机器人发第一条消息即创建任务；后续同 thread 内的回复会作为 follow-up 注入任务循环。完整配置见 channels/slack。

常见陷阱

1. 任务卡在 spec 阶段：多半是 LLM provider 连不通。opencorvus doctor 检查。
2. integrity review 一直不通过：仓库里可能没有可执行的 build/test 命令。Build / integrity 会从 owned_paths 向上找最近的 package.json。
3. permission 无限等待：默认权限模式是 Full access。如果项目显式选择了 Ask me，请在 UI 中回复，或把项目切换为 Full access。

下一步：架构总览。