Agentaily Docs

外观

DEVELOPMENT —— 本地开发指南 ​

「怎么在本地把这个 monorepo 跑起来、改起来、验证、上线」的开发者手册。 「这个项目是什么 / 仓库地图」看 README.md;设计与契约真相源看 ARCHITECTURE.md · SPEC.md;能力进度看 ROADMAP.md。

🌳 推进模型 = git worktree + PR:每个 agent / 终端从 main 开自己的 worktree(.claude/worktrees/<slug>)+ 分支,在里面改、窄提交、开 PR 合并回 main(见文末「推进模型」与 CLAUDE.md 的「🌳 推进模型」)。

环境要求 ​

工具版本说明
Node≥ 24(实测 v26)见根 package.json
pnpm11.7.0packageManager 已钉版本,corepack enable 即自动用对
Turbo随 devDeps 装(^2.9)任务编排,无需全局装
wrangler随各 app devDeps 装(^4.x)本地跑 Cloudflare Workers/Pages、D1、部署
bash
corepack enable          # 让 pnpm 走仓库钉死的 11.7.0
pnpm install             # 一次性装全工作区依赖

根级常用命令(在仓库根跑) ​

命令作用
pnpm install装 / 同步全工作区依赖
pnpm devturbo run dev —— 并行起所有包的 dev(重;日常多用下面的单包 --filter)
pnpm testvitest run —— 全工作区单测(分层见 TESTING.md)
pnpm typecheckturbo run typecheck —— 全工作区 tsc --noEmit
pnpm buildturbo run build —— 各包各自构建(app 前端是零构建 VFS,沙箱直跑,无汇入步)
pnpm formatprettier --write .

跑单个包 用 pnpm --filter <包名> <脚本>,例:pnpm --filter @agentaily/web dev。也可 cd 进该包目录直接 pnpm dev。

跑各个应用(端口速查) ​

应用 / 包命令(仓库根)本地地址
主应用 web(ChatApp 聊天造 app + 预览工作台 + 市场弹窗)pnpm --filter @agentaily/web devhttp://localhost:4173
官网 website(双语落地页)pnpm --filter @agentaily/website devhttp://localhost:5173
Storybook(组件库预览)pnpm --filter @agentaily/design-system storybookhttp://localhost:6006
发布 Worker(UGC 子域运行时)pnpm --filter @agentaily/publish devwrangler dev(默认 :8787)
反馈 Worker(评审 widget 后端)pnpm --filter @agentaily/feedback exec wrangler dev --port 8790http://127.0.0.1:8790

反馈 Worker 配 @agentaily/feedback-widget:在 apps/web/.env.local 写 VITE_FEEDBACK_ENDPOINT=http://127.0.0.1:8790,主应用就会挂出评审 widget(没配则不挂)。要本地真开 PR 需 apps/feedback/.dev.vars 里给 GITHUB_TOKEN(gitignored),否则提交返回清晰 503。详见 skill agentaily-feedback-widget。

端口已在各自 vite.config 写死(web=4173、Storybook=6006);官网走 vite 默认 5173,若 5173 被占会自动顺延到 5174。本机若同时在跑别的项目(如 form-design 用 --strictPort 占 5173),注意区分。app 前端是零构建 VFS,沙箱内联预览,不再有单独的 Studio dev server。

看主应用的最短路径 ​

bash
pnpm --filter @agentaily/web dev          # → http://localhost:4173(ChatApp:聊天造 app → 预览工作台 → 市场弹窗 → 发布)

后端 / Pages Functions / D1 ​

apps/web 是 Vite SPA + Cloudflare Pages Functions(apps/web/functions/** = /api/*,数据落 D1)。

  • vite dev 只托管前端 SPA,/api/* 不会被 vite 接管 → 直接请求会 404。要本地连带 Functions + D1,用 wrangler 跑 Pages:
    bash
    pnpm --filter @agentaily/web build                       # 先产出 dist/
pnpm --filter @agentaily/web exec wrangler pages dev dist # D1 绑定见 wrangler.toml
  • 数据层正在收敛到 @agentaily/db(Drizzle schema = 单一真相源,迁移搬到 db/migrations)。绑定 / 迁移以 apps/web/wrangler.toml 与 @agentaily/db 为准,别照搬旧的 apps/web/migrations/**。
  • 发布运行时 @agentaily/publish(apps/publish)是按 Host 路由的独立 Worker(UGC 子域 + 自带域名),pnpm --filter @agentaily/publish dev 本地起,… deploy 上线。域名方案见 DOMAINS.md。

测试 ​

  • 跑全量:pnpm test(根 vitest run)。单包:pnpm --filter <包> test,watch:… test:watch。
  • 分层 / 框架选型 / 护栏 是 TESTING.md 的真相源 —— 写测试前先对它(内环单测 + 外环 BDD *.feature)。
  • 坑:jsdom 默认 navigator.language=en-US,测 locale 检测要显式 pin(见 @agentaily/i18n 测试)。

UI / 设计开发 ​

  • 做或改任何 UI,直接消费组件库 @agentaily/design-system —— 不手搓底层、不 re-vendor。缺组件 / 缺 seam 时往组件库仓补齐(下游定契约、上游照做)。
  • 改组件时先 pnpm --filter @agentaily/design-system storybook 起 Storybook(:6006)在 story 里验证。评审组件时可点工具栏「● 评审」用 addon @agentaily/storybook-addon-review 在预览里选元素 + 写评论 + 一键开评审 PR(本地 dev;见 skill agentaily-storybook-addon-review)。
  • 规范两份(动手前先对):视觉 / 品牌 → skill agentaily-design + DESIGN.md;交互 / 行为(鉴权守卫、加载 / 空 / 错态、跳转)→ skill interaction-design-spec。
  • 组件库构建:pnpm --filter @agentaily/design-system build:lib(gen:barrel → build:js/css/types/assets);开发态增量 watch 用其 dev 脚本。

构建与产物 ​

bash
pnpm build   # turbo run build(各包并行)

app 前端是零构建 VFS(index.html 入口 + 按需 css/js,沙箱 iframe 直跑、无转译 / 打包步),所以 build 即各包各自 tsc / vite build,无 studio 汇入步。push main 触发 CD 部署(主应用 + 官网),所以 push 的每个提交都要自洽可构建。

抽出的基建包(均已注册进 workspace) ​

@agentaily/design-system 之外,这几个跨切面基建包已从 DS / 旧 web-kit 抽成独立工作区包,都已进 pnpm-workspace.yaml:

目录包状态
i18n/@agentaily/i18n(国际化机制)✅ 已注册
aml/@agentaily/aml(数据建模 DSL,参考 Prisma 不重名)✅ 已注册
theme/@agentaily/theme(主题切换抽包,riding on @agentaily/persistence)✅ 已注册
persistence/@agentaily/persistence(跨子域偏好持久化原语,零依赖)✅ 已注册

这几个包都消费为 TypeScript 源码(无构建步)、自带 vitest.config.ts。带 DOM 的测试已按各自 config 接进根 vitest.config.ts 的 projects(机制见 TESTING.md)。

🌳 推进模型(git worktree + PR)——动手前必读 ​

每个 agent / 终端在自己的 git worktree 里干活、提 PR 合并 —— 不再多 session 共用同一个工作树。 物理隔离,各干各的,不互相踩。完整规矩见 CLAUDE.md 的「🌳 推进模型」,要点:

  1. 开自己的 worktree —— 从 main 开 .claude/worktrees/<slug>(被 .gitignore)+ 分支,在里面改、提交到自己的分支(起独立终端用全局 skill spawn-terminal)。
  2. 窄暂存,永不 -A —— 只 git add <你明确的路径>;绝不 git add -A/./commit -am。git commit 前 git diff --cached --name-only 自检。
  3. 集成走 PR —— 改完 push 分支 → 开 PR → 合并回 main(合并会触发 CD,见 RELEASE.md)。
  4. 绝不 force-push —— 被拒(non-fast-forward)→ git pull --rebase 再推。
  5. 进 main 的每个提交都自洽可构建 —— 别让 CD 红。

旧的「多 session 共用同一工作树 + COLLAB.md 协作板 + TODO.md 指令板 + session-collab skill」模型已退役 —— worktree 物理隔离后不需要协作板 / 指令板。

真相源 / 根文档索引 ​

文档是什么
README.md项目简介 + 仓库地图
ARCHITECTURE.md架构设计与理由
SPEC.md精确契约(协议 / 数据形状 / op 语义 / 不变量)
ROADMAP.md能力地图 + 当前进度
TESTING.md测试分层 / 框架选型 / 护栏
DESIGN.md设计规范入口(指向 skill + 上游 DS)
DOMAINS.md域名方案(官网 / 应用 / 发布子域)
DEVELOPMENT.md本地开发指南(本文)
REFACTOR.md架构收敛重构蓝图 + 工单(当前重构真相源)
CLAUDE.md项目级 Agent 指引
</content>
</invoke>