# 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 行为。
- 新模块就位后，优先删除废弃代码。