kurihada/ai-workflow

Fork 0

Files

T

kurihada 24871e213a chore(repo): reinitialize repository

2026-03-18 12:15:53 +08:00

6.2 KiB

Raw Permalink Blame History

AGENTS.md

本文档为在此仓库中工作的 AI 编码代理（Codex、Cursor、Copilot 等）提供指导。

第一性原理

请使用第一性原理思考。你不能总是假设我非常清楚自己想要什么和该怎么得到。请保持审慎,从原始需求和问题出发,如果动机和目标不清晰,停下来和我讨论。

方案规范

当需要你给出修改或重构方案时必须符合以下规范:

不允许给出兼容性或补丁性的方案
不允许过度设计,保持最短路径实现且不能违反第一条要求
不允许自行给出我提供的需求以外的方案,例如一些兜底和降级方案，这可能导致业务逻辑偏移问题
必须确保方案的逻辑正确,必须经过全链路的逻辑验证

这是什么

这是一个多代理 AI 编排系统。

关键命令

Inbox CLI（核心工具）

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）

cd dashboard && npm install && npm run dev   # Vite 开发服务器
cd dashboard && npm run build                # 生产构建 → dist/

开发模式下，Dashboard 会将 /api 代理到 http://localhost:3000。

Apps

# 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 为中心：

inbox server 启动 Inbox API。
inbox api ... 或 Dashboard 调用 /api/v2/*。
HTTP 层通过 internal/store/sqlite 直接写入 SQLite。
运行时角色解析从数据库读取，并快照到 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 行为。
新模块就位后，优先删除废弃代码。

6.2 KiB Raw Permalink Blame History Unescape Escape