chore(repo): reinitialize repository

2026-03-18 11:29:54 +08:00
commit 24871e213a
288 changed files with 44369 additions and 0 deletions
@@ -0,0 +1,135 @@
+# 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 行为。
+- 新模块就位后，优先删除废弃代码。