136 lines
6.2 KiB
Markdown
136 lines
6.2 KiB
Markdown
# AGENTS.md
|
||
|
||
本文档为在此仓库中工作的 AI 编码代理（Codex、Cursor、Copilot 等）提供指导。
|
||
|
||
## 第一性原理
|
||
|
||
请使用第一性原理思考。你不能总是假设我非常清楚自己想要什么和该怎么得到。请保持审慎,从原始需求和问题出发,如果动机和目标不清晰,停下来和我讨论。
|
||
|
||
|
||
## 方案规范
|
||
|
||
当需要你给出修改或重构方案时必须符合以下规范:
|
||
|
||
- 不允许给出兼容性或补丁性的方案
|
||
- 不允许过度设计,保持最短路径实现且不能违反第一条要求
|
||
- 不允许自行给出我提供的需求以外的方案,例如一些兜底和降级方案，这可能导致业务逻辑偏移问题
|
||
- 必须确保方案的逻辑正确,必须经过全链路的逻辑验证
|
||
|
||
## 这是什么
|
||
|
||
这是一个多代理 AI 编排系统。
|
||
|
||
## 关键命令
|
||
|
||
### Inbox CLI（核心工具）
|
||
|
||
```bash
|
||
cd inbox && go build -o /tmp/inbox-host ./cmd/inbox
|
||
export INBOX_WORKSPACE=/Users/xd/project/ai-workflow-v2
|
||
|
||
/tmp/inbox-host server --workspaces-dir /Users/xd/project/ai-workflow-v2/inbox-worktrees --port 3000
|
||
/tmp/inbox-host api GET /api/v2/projects
|
||
/tmp/inbox-host api POST /api/v2/topics --data '{"workspace_id":"ws_1","title":"Signup Flow","space":"workflow","status":"execution"}'
|
||
```
|
||
|
||
### Dashboard（React UI）
|
||
|
||
```bash
|
||
cd dashboard && npm install && npm run dev # Vite 开发服务器
|
||
cd dashboard && npm run build # 生产构建 → dist/
|
||
```
|
||
|
||
开发模式下，Dashboard 会将 `/api` 代理到 `http://localhost:3000`。
|
||
|
||
### Apps
|
||
|
||
```bash
|
||
# phonesite（Next.js 静态站点）
|
||
cd apps/phonesite && npm install && npm run dev
|
||
cd apps/phonesite && npm test # Vitest
|
||
cd apps/phonesite && npx playwright test # E2E
|
||
|
||
# redbook（全栈：Go + Next.js）
|
||
cd apps/redbook/backend && go run ./cmd/server # :8080
|
||
cd apps/redbook/backend && go test ./...
|
||
cd apps/redbook/frontend && npm install && npm run dev
|
||
cd apps/redbook/frontend && npm test
|
||
```
|
||
|
||
## 架构
|
||
|
||
### 当前流程
|
||
|
||
当前激活的流程以 HTTP 为中心：
|
||
|
||
1. `inbox server` 启动 Inbox API。
|
||
2. `inbox api ...` 或 Dashboard 调用 `/api/v2/*`。
|
||
3. HTTP 层通过 `internal/store/sqlite` 直接写入 SQLite。
|
||
4. 运行时角色解析从数据库读取，并快照到 workflow run 中。
|
||
|
||
### 运行时目录结构
|
||
|
||
```
|
||
<repo>/.runtime/inbox.db # Inbox V2 SQLite 存储
|
||
```
|
||
|
||
### Inbox CLI（Go，`inbox/`）
|
||
|
||
单个二进制文件，提供两个命令：
|
||
- `server`：启动 HTTP API
|
||
- `api`：通用的、面向 AI 的 HTTP 包装器
|
||
|
||
关键模块区域：
|
||
- `internal/base/`：通用基础原语
|
||
- `internal/domain/`：稳定的业务实体与规则
|
||
- `internal/app/`：运行时配置与 workflow-run 服务
|
||
- `internal/httpapi/`：`/api/v2/*` 处理器
|
||
- `internal/store/sqlite/`：SQLite schema 与仓储实现
|
||
|
||
### 角色系统
|
||
|
||
角色是数据库驱动的运行时配置，而不是文件驱动的事实来源。
|
||
|
||
- `leader` 负责用户对话、任务拆解、链路编排，以及宿主机上的最终执行决策
|
||
- `worker` 在隔离的 worktree/container 中执行分配的链路任务，并向 `leader` 回传证据
|
||
- `user` 是仅供人类使用的运行时角色，永远不会由 AI 运行时自动执行
|
||
|
||
### Dashboard（`dashboard/`）
|
||
|
||
基于 React 19 + TypeScript + Vite + Tailwind + Framer Motion。页面包括：Timeline、Topics、Roles、Executions、Merges。通过轮询 inbox web API 获取更新。
|
||
## 工程规则
|
||
|
||
### 最高优先级：修复根因，而不是增加回退逻辑
|
||
|
||
- 默认直接修复根因。除非用户明确要求这种权衡，否则不要添加 fallback 逻辑、ignore 规则、兼容性分支、防御性特判或“以防万一”的条件分支。
|
||
- 如果真正的问题是糟糕的历史状态、陈旧的运行时产物、脏 worktree 或畸形数据，应通过迁移、清理步骤、修复脚本或定向数据修正直接修复状态，而不是让应用逻辑静默容忍这些问题。
|
||
- 不要把运维残留吸收到产品逻辑中。运行时文件、缓存文件、生成产物、临时目录以及本地 OS 噪音，都应在源头被隔离、迁移或显式清理。
|
||
- 在考虑“增强韧性”的补丁之前，先问自己：“为什么会出现这个坏状态？”以及“能不能直接移除这个坏状态的来源？”优先做源头治理。
|
||
- 如果 fallback 看起来不可避免，先停下来，把这个权衡显式告知用户，再决定是否实现。不要为了短期方便，悄悄加入长期分支逻辑。
|
||
- 优先选择一条干净、易解释的路径，而不是堆叠逻辑去保留旧错误。
|
||
|
||
### 不要添加遗留兼容层
|
||
|
||
- 不要为旧数据、旧字段值、旧路由、旧目录布局、旧分支命名或旧运行时行为添加兼容代码。
|
||
- 不要保留双路径逻辑，例如 `new flow || old flow`、fallback-to-legacy 分支、针对历史数据的静默运行时协调，或把 cleanup-by-ignore 规则塞进核心逻辑里。
|
||
- 如果旧数据或运行时残留有问题，应通过显式迁移、修复脚本、定向 DB 更新或一次性清理直接修正。不要把问题藏进应用逻辑里。
|
||
- 如果旧实现正在被替换，就删除旧路径，而不是长期同时支持两套。
|
||
- 不要留下没有移除计划的“临时” fallback 分支。在这个仓库里，临时兼容逻辑通常就是错误方向。
|
||
|
||
### 清晰的模块归属
|
||
|
||
- 新行为必须放进职责单一、边界明确的模块中。
|
||
- 不要把一个特性零散地分布在 handler、service、helper 和 infra 文件中，而没有清晰的模块边界。
|
||
- HTTP handler 应保持轻量：解析请求、调用 application service、写回响应。
|
||
- Application service 应负责编排和业务流程。
|
||
- git、container、filesystem、process execution 等基础设施细节应封装在职责明确、接口收敛的专用模块之后。
|
||
- 做重构时，优先先提取模块，再把逻辑迁移进去，而不是让部分逻辑继续散落在旧文件中。
|
||
|
||
### 处理破坏性变更的首选方式
|
||
|
||
- 优先干净替换，而不是渐进兼容。
|
||
- 优先 schema/data migration，而不是运行时分支。
|
||
- 优先显式清理，而不是用 ignore 掩盖问题。
|
||
- 优先显式失败，而不是隐藏 fallback 行为。
|
||
- 新模块就位后，优先删除废弃代码。
|