Tambo AI Monorepo 开发规范与 AI Agent 协作指南从仓库结构到工程实践的完整解读【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai本指南基于 Tambo AI 开源仓库根目录的 AGENTS.mdClaude Code 等 AI Agent 与人类开发者共同遵循的工程规范文档系统梳理这个同时承载 Tambo AI 框架与 Tambo Cloud 平台的 Turborepo 单仓库的架构布局、编码标准、开发工作流与协作纪律。读完本文你将掌握该仓库的模块划分与端口规划、Node.js 22 环境下的开发命令体系、TypeScript/前端/后端/数据库的硬性规范以及提交 PR 前必须通过的验证检查项能够以符合项目预期的方式在此仓库中独立开发与协作。一、仓库全景一个 Monorepo两大产品线Tambo AI 采用 Turborepo 组织整个代码库根目录 package.json 通过workspaces字段声明了全部工作区react-sdk、showcase、docs、cli、create-tambo-app、packages/*与apps/*。整个仓库被划分为两个层次Tambo AI 框架包面向开源 SDK 使用者与Tambo Cloud 平台SaaS 云服务。1.1 框架包Turborepo 根级包名称定位react-sdk/tambo-ai/reactReact 官方 SDK提供核心 hooks、providers、类型支持组件注册与线程管理同时输出 CommonJSdist/与 ESMesm/双格式packages/client/tambo-ai/client框架无关的核心客户端引擎TamboClient类提供getState()/subscribe()TamboStream异步可迭代对象用于流式响应既被tambo-ai/react复用也可独立在 Node.js、Vue、Svelte 等环境使用cli/tambo命令行工具负责项目脚手架、组件生成与开发辅助showcase/tambo-ai/showcase演示应用端口 8262展示全部 Tambo 组件与模式兼具文档与测试场职能docs/tambo-ai/docsFumadocs 文档站端口 8263MDX 内容 交互式示例create-tambo-app/create-tambo-app应用引导器负责从模板初始化新项目、处理 git 初始化与依赖安装community/—社区资源与活动物料值得注意的两个工程约束showcase 组件由 CLI 注册表自动同步showcase/中的组件来源于 CLI registry代码结构上对应cli/dist/registry/的生成产物修改时应改 CLI 注册表而非直接编辑 showcase 组件docs 组件以 cli 包为源文档站中的 UI 组件源自cli/包任何组件改动都应先在 cli 包完成再复制到 docs 包避免双份代码漂移。从 react-sdk/package.json 可以看到 SDK 包的构建脚本build由build:cjstsc -p tsconfig.cjs.json与build:esmtsc -p tsconfig.esm.json tsc-esm-fix --targetesm组成这正是“双格式输出”的实现方式其exports字段还通过tambo-ai/source条件导出指向./src/index.ts方便消费方直接引用源码。1.2 Tambo Cloud 平台包定位apps/webNext.js 前端端口 8260apps/apiNestJS OpenAPI 服务端端口 8261packages/dbDrizzle ORM schema 迁移 数据库辅助packages/core纯工具库不访问数据库packages/backendLLM/Agent 侧辅助与流式工具packages/eslint-config、packages/typescript-config共享工具链配置1.3 环境前提与工具版本管理Node.js 22npm 11根 package.json 的devEngines字段直接声明不满足会报错运行时与测试代码可直接使用crypto.randomUUID()无需降级 polyfill官方推荐使用 mise大多数工具与.node-versionNode.js.nvmrc保持同步以兼容 nvm这些文件由 Renovate 自动更新。从 mise.toml 可以看到工具清单cspell、gh、jq、shellcheck并通过npm:corepack管理 npm/yarn/pnpm 版本postinstall corepack enable corepack enable npm同时禁用了顶层包管理器安装避免版本漂移环境变量中还默认关闭了 Turbo 与 Next.js 的遥测TURBO_TELEMETRY_DISABLED、NEXT_TELEMETRY_DISABLED。mise 的日常用法mise install # 安装/更新工具到正确版本 mise exec -- command # 脚本/CI/非交互 shell 推荐用法 eval $(mise activate) # 仅交互式 shell 使用变更工具版本的流程提交 PR 修改权威版本文件涉及 Node.js 时必须同时更新.node-version与.nvmrc随后运行mise install并用npm run lint npm run check-types npm test验证。本地临时覆盖使用.mise.local.toml已 gitignore且只允许增量或补丁级变更不允许覆盖 Node.js 版本或使用不兼容版本。二、核心开发原则快速迭代与高标准的平衡AGENTS.md 用一组哲学原则约束所有代码产出快速推进但保持高标准清晰与可维护性优先于“聪明”的写法先读代码再动手遵循既有模式与命名小而简单函数优先于类避免不必要的抽象持续简化激进地移除复杂度能工作的最简单设计通常最好偏好不可变不修改入参返回新值多用const、toSorted、对象/数组展开前置错误处理用 guard clause 与 early return 尽早返回。关注点分离业务逻辑必须与 UI 组件分离计算、数据转换等逻辑抽取到独立文件utils/、services/、lib/UI 组件只做编排而不实现复杂逻辑。这样既易于测试也提升复用性。Fail-Fast禁止静默兜底条件不满足时立即失败静默回退会掩盖 bug 并制造不可预测的系统行为出错时用清晰错误信息终止执行说明“什么失败了、期望什么”例如throw new Error(Required model ${modelName} not found);数据映射如枚举/联合类型转换必须显式处理所有已知值遇到未知值直接抛错禁止用 catch-all 默认值掩盖数据完整性问题确需跳过无效数据时要记日志告警。命名规范文件/目录kebab-case类PascalCase变量/函数/方法camelCase环境变量UPPER_SNAKE_CASE使用英文与公认缩写API、URL、ctx、req、res、next布尔值以is/has/can/should开头函数用动词命名返回布尔值用isX/hasX/canX返回void倾向executeX/saveXReact 专属命名遵循 devdocs/NAMING_CONVENTIONS.md组件TamboXxx、hooksuseTamboXxx、Props 接口TamboXxxProps、事件 props 以onX开头、内部处理器用handleX。该文档还给出 Props 一律使用ReadonlyT包裹的约定export const TamboMessage: React.FCReadonlyTamboMessageProps () { /* ... */ };以及“动作最后置”的 hook 命名检查useTamboMessage()与useTamboMessageState()是正确写法useMessageTambo()则是错误前缀顺序。代码组织函数短小单一职责理想 20 条语句文件聚焦合理规模理想 200–300 行避免let——用返回新值的函数替代避免深层嵌套优先提前退出与提取辅助函数用map/filter迭代偏好不可变数据适用处用readonly与as const组合优于继承如确需类保持小规模200 语句、10 属性/方法并在内部校验不变量。避免过度抽象DRY 有度——有时少量重复优于错误的抽象三次法则出现 3 处相似代码后再提取共享工具过早抽象制造耦合、加大改动成本事后提取共性远比撤销糟糕抽象容易。导出规范偏好具名导出关联符号可一起导出如组件 相关类型避免默认导出内部模块不要建index.tsbarrel直接从源文件导入例外是包入口如packages/core/src/index.ts迁移符号时同步更新所有消费方不向后兼容重导出禁止用动态import()做常规导入含类型导入一律顶部静态导入动态导入仅用于特定场景的代码分割如懒加载路由。三、TypeScript 标准严格类型与可推断优先类型安全默认严格 TypeScript不用any、不强制类型断言除非不可避免类型不确定时用unknown再做收窄而不是any键值对象优先Recordstring, unknown而非object或{ [key: string]: unknown }除非明确要求禁止关闭 ESLint 规则或 TypeScript 报错——修复根因泛型用extends约束T extends SomeType避免宽泛T互斥状态用可辨识联合discriminated union如{ success: true; data: T } | { success: false; error: Error }用as const保留字面量类型数组应保持元组复用内置工具类型Pick、Omit、Partial、Required、ReturnType、Parameters不要重复造轮子避免{}类型——它表示“任意非空值”包含原始类型应选用unknown、object或Recordstring, unknown。type-fest 工具类型复杂派生类型优先查type-fest包PartialDeep、ReadonlyDeep、RequiredDeep、Merge、ValueOf、SetOptional等。type-fest已装于仓库根但各包使用时必须显式声明被包公开导出类型引用则放入dependencies仅内部代码或测试使用则放入devDependencies。类型推断值容易推断时不要加冗余类型标注事件处理器参数、显而易见的返回值、局部变量让 TypeScript 推断明显可推断的返回类型不要为内部函数创建一次性中间辅助类型优先使用数据库 schema、tRPC schema 等“事实来源”推断出的类型除非必要否则避免类型转换as优先调整函数签名/类型让代码无需转换通过unknown转换通常是坏味道确需在互操作边界使用时先做运行时校验如 Zod并保持转换局部化用satisfies在保留推断的同时检查对象字面量是否符合类型仅编译期它不校验运行时数据不可信输入仍需 schema 校验器类型守卫必须做真实运行时检查来收窄仅当值真正未知JSON 反序列化、用户输入时才用unknown作为入参类型避免“伪造守卫”——只断言不校验。类型转换避免不必要的构造器/强制转换。必须转换时字符串用${value}、布尔用!!value、数字用value。异步与控制流返回 Promise 的函数必须声明async调用 async 函数必须await大多数情况避免.catch()/.then()用async/awaittry/catch让错误自然传播.catch()仅用于确实无法await的场景如useEffect清理并用void显式标记有意的 fire-and-forget 调用避免 IIFE尤其不要用它规避 async 调用避免嵌套/链式三元表达式用if/else或switch多值判断用switch利用 TypeScript 穷尽性检查尽量不用default。函数式模式与正则克制多用map、filter、find、some、every避免reduce()除非心智模型确实需要累加如求和避免复杂方法链拆成具名中间步骤正则能不用就不用优先str.includes()、str.startsWith()、str.split()、str.replace()避免全局标志/glastIndex残留导致隐蔽 bug与多行标志/m平台换行差异实在无法避免时保持简单、加注释解释模式、充分测试边界。四、前端开发规范React Next.js组件架构与状态管理不要在apps/web新增/api端点使用应用私有 tRPC API 与服务端工具优先函数式、声明式组件全站 TypeScript对象形态用 interface优先React.FC按需使用PropsWithChildren与ComponentProps[WithRef|WithoutRef]本地 UI 状态用useState跨组件共享用 React Context但仅传 1–2 层时优先 props 而非新建 context静态不变配置用户 ID、API Key不要建 context直接 props 传递最小化useEffect能派生状态就派生、能记忆就记忆传给子组件的回调用useCallback网络请求优先用 tRPC/React Query 的 loading 状态而非手维护 loading 标志参考 devdocs/LOADING_STATES.md该文档指出分析类查询若超过 200ms 会造成 UI 闪烁要求同时解构data与isLoading并用 Skeleton 组件或禁用态替代纯 spinner例如const { data: totalUsage, isLoading: isLoadingMessageUsage } api.project.getTotalMessageUsage.useQuery( { period: messagesPeriod }, { enabled: !!session }, );布局、样式与排版Tailwind shadcn 体系布局用 flex/grid间距用gap-*与内边距p-*、pt-*等避免修改元素外边距m-*、mt-*等与space-x-*/space-y-*超长文本用text-ellipsis截断Tailwind 用量保持克制避免临场 CSS字体体系标题用 Sentientfont-heading/font-sentient、正文用 Geist Sansfont-sans、代码用 Geist Monofont-mono配置见 apps/web/lib/fonts.ts。JSX 模式与可访问性避免手工改字符串大小写——若内部 key如agent_mode需要展示给用户应单独提供英文文案Agent Mode而非靠代码转写避免超长 JSX复杂 JSX 拆成独立组件简单显隐用避免三元嵌套map()内层 JSX 保持几行之内JSX 内出现if/else、switch语句时需要给 JSX 加大括号就是应拆分组件的信号全组件遵循可访问性规范可点击元素用 button 而非 div/span合理使用 aria 标签与角色适当使用语义化 HTML。五、后端开发规范NestJS模块化结构每个主路由/域一个模块每个路由一个主 controller输入用 DTOclass-validator输出用简单类型Service 封装业务逻辑尽量保持纯函数守卫/过滤器/拦截器通过核心模块提供共享工具放共享模块错误处理即使 controller 内也尽量保持逻辑纯净、不存状态边界处controller/service适时转换为 HTTP/Nest 异常测试公开函数做单元测试controller/模块做集成或 e2e 测试工具为 Jest supertest对应 apps/api/test 下的app.e2e-spec.ts等。六、数据库规范Drizzle ORMSchema 事实来源是 packages/db/src/schema.ts禁止手改生成的 SQL迁移必须用npm run db:generate生成禁止手工编写迁移不要反范式化可由关系推导的外键例如runs.threadId已存在且 threads 有projectId就不要给runs加projectId数据库操作必须下沉到 packages/db/src/operations/apps/api的 Service 应调用 operation 函数而非内联写 DB 查询并从packages/db/src/operations/index.ts导出新操作以促进复用、集中管理 DB 逻辑。数据库命令从仓库根执行需带-w packages/dbnpm run db:generate -w packages/db # 根据 schema 变更生成迁移 npm run db:migrate -w packages/db # 应用迁移 npm run db:check -w packages/db # 检查状态 npm run db:studio -w packages/db # 打开 Drizzle Studio从 packages/db/src/schema.ts 可以看到平台核心表sessions、projects、projectMembers、apiKeys、threads、runs、messages、projectMessageUsage、deviceAuthCodes等与 packages/db/migrations/ 下按序号排列的迁移文件0000_init_setup.sql至0094_stiff_sentinel.sql一一对应。七、共享包与工具的分层约定packages/core纯工具校验、JSON、加密、线程、工具函数禁止访问数据库不应有任何数据库依赖packages/backendLLM/Agent 侧辅助与流式工具复用优先禁止重复实现跨包有用的工具放 coreLLM 专属放 backend数据库相关放 db共享配置ESLint、TypeScript config集中在packages/跨包依赖使用 workspace 协议*tambo-ai/typescript-sdk是外部依赖——它由apps/api的 OpenAPI spec 经stlcCLI 生成CI 中运行工作区在stainless/详见 RELEASING.md。八、开发工作流命令体系与热重载机制常用命令# 开发注意这是两个不同的应用体系 npm run dev:cloud # 启动 Tambo Cloudweb API- 端口 8260 8261 - 使用 turbo watch npm run dev # 启动 React SDKshowcase docs npm run dev:sdk # React SDK watch 模式 showcaseSDK 开发用 npm run build:sdk # 一次性构建 React SDK # 质量检查 npm run lint # 全仓库 lint npm run lint:fix # 自动修复 lint 问题 npm run check-types # TypeScript 类型检查 npm test # 运行全部测试 npm run format # Prettier 格式化 # 单个包开发从包目录或使用 -w 标志 npm run dev -w cli # 启动指定 workspace npm run dev:showcase # 仅启动 showcase npm run build -w react-sdk # 构建指定包热重载机制按应用类型区分Next.js 应用web、showcase、docs通过transpilePackages配置直接编译 workspace 的 TypeScript 源码workspace 包core、backend、db、react的改动会自动触发 HMR无需手动重建。NestJS API使用turbo watch配合interruptible: true自动重启并监控 workspace 输入目录packages/core/src/**、packages/backend/src/**、packages/db/src/**workspace 包变化时 API 服务自动重启。这一架构可以从 turbo.json 的tambo-ai-cloud/api#dev任务定义中得到印证它声明了persistent: true、interruptible: true及上述inputs监听路径根 package.json 的dev:cloud脚本正是turbo watch dev --filtertambo-ai-cloud/web --filtertambo-ai-cloud/api。效果是编辑任意 workspace 包文件Next.js 立即 HMR、NestJS 立即重启全程无需人工干预。Turbo 命令替代方案与构建系统turbo dev # 以开发模式启动所有包 turbo build # 构建所有包 turbo lint # 全仓库 lint turbo test # 跨包运行测试 turbo check-types # 全仓库类型检查构建系统由 Turborepo 编排共享依赖在根级管理各包依赖在包内管理。构建产物按包类型区分React SDK 双 CJS/ESM、CLI 为 ESM 可执行文件、应用为 Next.js 构建产物。跨包开发时的协作检查点react-sdk 改动用npm run dev:sdk/build:sdk并跑测试与 showcase 集成验证cli 改动要测试组件生成、验证注册表更新并同步 showcaseshowcase 改动走 CLI 注册表自动同步docs 改动要确保示例与当前 API 一致。关键配置文件与知识库turbo.jsonTurborepo 任务流水线与缓存package.jsonworkspace 配置与脚本各包 package.json包级配置知识库编码标准、命名规范、加载状态等详细指南见 devdocs/新增解决方案知识时写入 devdocs/solutions/ 对应目录。九、测试与质量保障测试策略各包内单元测试用 Jest集成测试经 showcase 应用完成CLI 测试通过模板生成与安装流程验证文档测试通过示例代码校验完成后端 e2e 测试controller/module用 Jest supertest。测试文件布局文件命名所有测试必须以.test.ts或.test.tsx结尾不接受.spec等后缀单元测试与被测文件同目录存放foo.ts旁放foo.test.ts不放进__tests__集成测试是唯一允许放在__tests__目录中的测试且文件名必须描述场景不能只是另一个文件名的镜像Fixtures 与 mocks共享辅助统一放在包源码根目录的__fixtures__或__mocks__目录如 apps/web/mocks严禁嵌套在功能目录内。Mocking 纪律避免过度 mock——测试应尽可能走真实代码路径如果为了隔离单元而 mock 内部函数很可能是在测实现细节而非行为只在系统边界 mock外部 API、数据库、文件系统、网络调用及其他带副作用的 I/O不 mock 自己拥有的代码纯且快的辅助函数直接调用mock 自家代码会把测试与实现耦合。提交/PR 前验证清单npm run check-types # 全 workspace TS 类型检查 npm run lint:fix # ESLint 自动修复 npm run format # Prettier 写入 npm test # 单元/集成测试十、Git 工作流与 PR 规范分支命名格式为userid/feature-name例如alecf/add-dark-mode、jane/fix-login-bug。Conventional Commits所有 PR 标题必须遵循type(scope): description格式例如feat(api): add transcript export fix(web): prevent duplicate project creation chore(db): reorganize migration filestype 集合包括 feat、fix、perf、deps、revert、docs、style、chore、refactor、test、build、ci常用 scopeapi、web、core、db、deps、ci、config、react-sdk、cli、showcase、docs。PR 要求适用时在 PR 描述中写明 Fixes #123GitHub或 Fixes TAM-123Linear。十一、Agent 开发规则与约束必须做提交前在根目录运行npm run lint、npm run check-types、npm run test跨包改动必须一起测试文档同步三件套开发者文档变更必须同步到 docs 站点先读 docs/AGENTS.md检查并更新包根 README更新包树中的 AGENTS.md 反映变更包版本遵循语义化版本新逻辑必须补测试测试失败时不要改代码硬凑测试两条路① 让代码改动向后兼容既有测试优先② 请用户修改测试。除非用户明确要求不做破坏性变更且必须提前警告。禁止做未经明确要求不得引入依赖或修改工具配置eslint、tsconfig 等由人类负责不提交密钥一律使用 env 文件。何时询问用户任何涉及 lint 或 TypeScript 规则的改动都必须先征求用户同意。十二、Agent 行为准则与代码注释纪律AGENTS.md 对 AI Agent 的行为姿态也做了明确规定直接、坦率不奉承用户指令含糊时追问细节但不过度请求确认每段代码都被视为“关键任务”。具体到代码产出编写 JSDoc 时务必补充returns描述函数返回值不写类型类型由 TS 推断代码注释禁止引用规划文档、提案或设计文档如// See plans/foo.md——这些产物生命周期短而注释永久存在注释必须自包含规划文档、提案、设计文档存入devdocs/解决方案放devdocs/solutions/、头脑风暴放devdocs/brainstorms/等唯一例外是plans/保留在仓库根以便可见注释与文档中的 Tambo 自有 URL 一律使用tambo.co域名不用旧.ai域名遇到旧域名链接优先在相关改动中一并更新外部非 Tambo链接不受限。结语让规范成为协作的地基Tambo AI 的 AGENTS.md 本质上是一份“人与 AI 共写”的工程宪法它用 Turborepo 单仓承载 SDK 框架与云平台两条产品线用 Node.js 22 mise 固化工具链用 turbo watch HMR 消除跨包开发的等待成本再以严格但可执行的 TypeScript、前端、后端、数据库规范守住代码质量下限。无论你是人类开发者还是 AI Agent只要遵循本文梳理的结构、命令与纪律——尤其是提交前的四项验证check-types、lint:fix、format、test与“Fail-Fast、不静默兜底”的核心哲学——就能在这个仓库中高效、低摩擦地推进功能同时保持整个框架与平台的一致性。【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Tambo AI Monorepo 开发规范与 AI Agent 协作指南：从仓库结构到工程实践的完整解读
Tambo AI Monorepo 开发规范与 AI Agent 协作指南从仓库结构到工程实践的完整解读【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai本指南基于 Tambo AI 开源仓库根目录的 AGENTS.mdClaude Code 等 AI Agent 与人类开发者共同遵循的工程规范文档系统梳理这个同时承载 Tambo AI 框架与 Tambo Cloud 平台的 Turborepo 单仓库的架构布局、编码标准、开发工作流与协作纪律。读完本文你将掌握该仓库的模块划分与端口规划、Node.js 22 环境下的开发命令体系、TypeScript/前端/后端/数据库的硬性规范以及提交 PR 前必须通过的验证检查项能够以符合项目预期的方式在此仓库中独立开发与协作。一、仓库全景一个 Monorepo两大产品线Tambo AI 采用 Turborepo 组织整个代码库根目录 package.json 通过workspaces字段声明了全部工作区react-sdk、showcase、docs、cli、create-tambo-app、packages/*与apps/*。整个仓库被划分为两个层次Tambo AI 框架包面向开源 SDK 使用者与Tambo Cloud 平台SaaS 云服务。1.1 框架包Turborepo 根级包名称定位react-sdk/tambo-ai/reactReact 官方 SDK提供核心 hooks、providers、类型支持组件注册与线程管理同时输出 CommonJSdist/与 ESMesm/双格式packages/client/tambo-ai/client框架无关的核心客户端引擎TamboClient类提供getState()/subscribe()TamboStream异步可迭代对象用于流式响应既被tambo-ai/react复用也可独立在 Node.js、Vue、Svelte 等环境使用cli/tambo命令行工具负责项目脚手架、组件生成与开发辅助showcase/tambo-ai/showcase演示应用端口 8262展示全部 Tambo 组件与模式兼具文档与测试场职能docs/tambo-ai/docsFumadocs 文档站端口 8263MDX 内容 交互式示例create-tambo-app/create-tambo-app应用引导器负责从模板初始化新项目、处理 git 初始化与依赖安装community/—社区资源与活动物料值得注意的两个工程约束showcase 组件由 CLI 注册表自动同步showcase/中的组件来源于 CLI registry代码结构上对应cli/dist/registry/的生成产物修改时应改 CLI 注册表而非直接编辑 showcase 组件docs 组件以 cli 包为源文档站中的 UI 组件源自cli/包任何组件改动都应先在 cli 包完成再复制到 docs 包避免双份代码漂移。从 react-sdk/package.json 可以看到 SDK 包的构建脚本build由build:cjstsc -p tsconfig.cjs.json与build:esmtsc -p tsconfig.esm.json tsc-esm-fix --targetesm组成这正是“双格式输出”的实现方式其exports字段还通过tambo-ai/source条件导出指向./src/index.ts方便消费方直接引用源码。1.2 Tambo Cloud 平台包定位apps/webNext.js 前端端口 8260apps/apiNestJS OpenAPI 服务端端口 8261packages/dbDrizzle ORM schema 迁移 数据库辅助packages/core纯工具库不访问数据库packages/backendLLM/Agent 侧辅助与流式工具packages/eslint-config、packages/typescript-config共享工具链配置1.3 环境前提与工具版本管理Node.js 22npm 11根 package.json 的devEngines字段直接声明不满足会报错运行时与测试代码可直接使用crypto.randomUUID()无需降级 polyfill官方推荐使用 mise大多数工具与.node-versionNode.js.nvmrc保持同步以兼容 nvm这些文件由 Renovate 自动更新。从 mise.toml 可以看到工具清单cspell、gh、jq、shellcheck并通过npm:corepack管理 npm/yarn/pnpm 版本postinstall corepack enable corepack enable npm同时禁用了顶层包管理器安装避免版本漂移环境变量中还默认关闭了 Turbo 与 Next.js 的遥测TURBO_TELEMETRY_DISABLED、NEXT_TELEMETRY_DISABLED。mise 的日常用法mise install # 安装/更新工具到正确版本 mise exec -- command # 脚本/CI/非交互 shell 推荐用法 eval $(mise activate) # 仅交互式 shell 使用变更工具版本的流程提交 PR 修改权威版本文件涉及 Node.js 时必须同时更新.node-version与.nvmrc随后运行mise install并用npm run lint npm run check-types npm test验证。本地临时覆盖使用.mise.local.toml已 gitignore且只允许增量或补丁级变更不允许覆盖 Node.js 版本或使用不兼容版本。二、核心开发原则快速迭代与高标准的平衡AGENTS.md 用一组哲学原则约束所有代码产出快速推进但保持高标准清晰与可维护性优先于“聪明”的写法先读代码再动手遵循既有模式与命名小而简单函数优先于类避免不必要的抽象持续简化激进地移除复杂度能工作的最简单设计通常最好偏好不可变不修改入参返回新值多用const、toSorted、对象/数组展开前置错误处理用 guard clause 与 early return 尽早返回。关注点分离业务逻辑必须与 UI 组件分离计算、数据转换等逻辑抽取到独立文件utils/、services/、lib/UI 组件只做编排而不实现复杂逻辑。这样既易于测试也提升复用性。Fail-Fast禁止静默兜底条件不满足时立即失败静默回退会掩盖 bug 并制造不可预测的系统行为出错时用清晰错误信息终止执行说明“什么失败了、期望什么”例如throw new Error(Required model ${modelName} not found);数据映射如枚举/联合类型转换必须显式处理所有已知值遇到未知值直接抛错禁止用 catch-all 默认值掩盖数据完整性问题确需跳过无效数据时要记日志告警。命名规范文件/目录kebab-case类PascalCase变量/函数/方法camelCase环境变量UPPER_SNAKE_CASE使用英文与公认缩写API、URL、ctx、req、res、next布尔值以is/has/can/should开头函数用动词命名返回布尔值用isX/hasX/canX返回void倾向executeX/saveXReact 专属命名遵循 devdocs/NAMING_CONVENTIONS.md组件TamboXxx、hooksuseTamboXxx、Props 接口TamboXxxProps、事件 props 以onX开头、内部处理器用handleX。该文档还给出 Props 一律使用ReadonlyT包裹的约定export const TamboMessage: React.FCReadonlyTamboMessageProps () { /* ... */ };以及“动作最后置”的 hook 命名检查useTamboMessage()与useTamboMessageState()是正确写法useMessageTambo()则是错误前缀顺序。代码组织函数短小单一职责理想 20 条语句文件聚焦合理规模理想 200–300 行避免let——用返回新值的函数替代避免深层嵌套优先提前退出与提取辅助函数用map/filter迭代偏好不可变数据适用处用readonly与as const组合优于继承如确需类保持小规模200 语句、10 属性/方法并在内部校验不变量。避免过度抽象DRY 有度——有时少量重复优于错误的抽象三次法则出现 3 处相似代码后再提取共享工具过早抽象制造耦合、加大改动成本事后提取共性远比撤销糟糕抽象容易。导出规范偏好具名导出关联符号可一起导出如组件 相关类型避免默认导出内部模块不要建index.tsbarrel直接从源文件导入例外是包入口如packages/core/src/index.ts迁移符号时同步更新所有消费方不向后兼容重导出禁止用动态import()做常规导入含类型导入一律顶部静态导入动态导入仅用于特定场景的代码分割如懒加载路由。三、TypeScript 标准严格类型与可推断优先类型安全默认严格 TypeScript不用any、不强制类型断言除非不可避免类型不确定时用unknown再做收窄而不是any键值对象优先Recordstring, unknown而非object或{ [key: string]: unknown }除非明确要求禁止关闭 ESLint 规则或 TypeScript 报错——修复根因泛型用extends约束T extends SomeType避免宽泛T互斥状态用可辨识联合discriminated union如{ success: true; data: T } | { success: false; error: Error }用as const保留字面量类型数组应保持元组复用内置工具类型Pick、Omit、Partial、Required、ReturnType、Parameters不要重复造轮子避免{}类型——它表示“任意非空值”包含原始类型应选用unknown、object或Recordstring, unknown。type-fest 工具类型复杂派生类型优先查type-fest包PartialDeep、ReadonlyDeep、RequiredDeep、Merge、ValueOf、SetOptional等。type-fest已装于仓库根但各包使用时必须显式声明被包公开导出类型引用则放入dependencies仅内部代码或测试使用则放入devDependencies。类型推断值容易推断时不要加冗余类型标注事件处理器参数、显而易见的返回值、局部变量让 TypeScript 推断明显可推断的返回类型不要为内部函数创建一次性中间辅助类型优先使用数据库 schema、tRPC schema 等“事实来源”推断出的类型除非必要否则避免类型转换as优先调整函数签名/类型让代码无需转换通过unknown转换通常是坏味道确需在互操作边界使用时先做运行时校验如 Zod并保持转换局部化用satisfies在保留推断的同时检查对象字面量是否符合类型仅编译期它不校验运行时数据不可信输入仍需 schema 校验器类型守卫必须做真实运行时检查来收窄仅当值真正未知JSON 反序列化、用户输入时才用unknown作为入参类型避免“伪造守卫”——只断言不校验。类型转换避免不必要的构造器/强制转换。必须转换时字符串用${value}、布尔用!!value、数字用value。异步与控制流返回 Promise 的函数必须声明async调用 async 函数必须await大多数情况避免.catch()/.then()用async/awaittry/catch让错误自然传播.catch()仅用于确实无法await的场景如useEffect清理并用void显式标记有意的 fire-and-forget 调用避免 IIFE尤其不要用它规避 async 调用避免嵌套/链式三元表达式用if/else或switch多值判断用switch利用 TypeScript 穷尽性检查尽量不用default。函数式模式与正则克制多用map、filter、find、some、every避免reduce()除非心智模型确实需要累加如求和避免复杂方法链拆成具名中间步骤正则能不用就不用优先str.includes()、str.startsWith()、str.split()、str.replace()避免全局标志/glastIndex残留导致隐蔽 bug与多行标志/m平台换行差异实在无法避免时保持简单、加注释解释模式、充分测试边界。四、前端开发规范React Next.js组件架构与状态管理不要在apps/web新增/api端点使用应用私有 tRPC API 与服务端工具优先函数式、声明式组件全站 TypeScript对象形态用 interface优先React.FC按需使用PropsWithChildren与ComponentProps[WithRef|WithoutRef]本地 UI 状态用useState跨组件共享用 React Context但仅传 1–2 层时优先 props 而非新建 context静态不变配置用户 ID、API Key不要建 context直接 props 传递最小化useEffect能派生状态就派生、能记忆就记忆传给子组件的回调用useCallback网络请求优先用 tRPC/React Query 的 loading 状态而非手维护 loading 标志参考 devdocs/LOADING_STATES.md该文档指出分析类查询若超过 200ms 会造成 UI 闪烁要求同时解构data与isLoading并用 Skeleton 组件或禁用态替代纯 spinner例如const { data: totalUsage, isLoading: isLoadingMessageUsage } api.project.getTotalMessageUsage.useQuery( { period: messagesPeriod }, { enabled: !!session }, );布局、样式与排版Tailwind shadcn 体系布局用 flex/grid间距用gap-*与内边距p-*、pt-*等避免修改元素外边距m-*、mt-*等与space-x-*/space-y-*超长文本用text-ellipsis截断Tailwind 用量保持克制避免临场 CSS字体体系标题用 Sentientfont-heading/font-sentient、正文用 Geist Sansfont-sans、代码用 Geist Monofont-mono配置见 apps/web/lib/fonts.ts。JSX 模式与可访问性避免手工改字符串大小写——若内部 key如agent_mode需要展示给用户应单独提供英文文案Agent Mode而非靠代码转写避免超长 JSX复杂 JSX 拆成独立组件简单显隐用避免三元嵌套map()内层 JSX 保持几行之内JSX 内出现if/else、switch语句时需要给 JSX 加大括号就是应拆分组件的信号全组件遵循可访问性规范可点击元素用 button 而非 div/span合理使用 aria 标签与角色适当使用语义化 HTML。五、后端开发规范NestJS模块化结构每个主路由/域一个模块每个路由一个主 controller输入用 DTOclass-validator输出用简单类型Service 封装业务逻辑尽量保持纯函数守卫/过滤器/拦截器通过核心模块提供共享工具放共享模块错误处理即使 controller 内也尽量保持逻辑纯净、不存状态边界处controller/service适时转换为 HTTP/Nest 异常测试公开函数做单元测试controller/模块做集成或 e2e 测试工具为 Jest supertest对应 apps/api/test 下的app.e2e-spec.ts等。六、数据库规范Drizzle ORMSchema 事实来源是 packages/db/src/schema.ts禁止手改生成的 SQL迁移必须用npm run db:generate生成禁止手工编写迁移不要反范式化可由关系推导的外键例如runs.threadId已存在且 threads 有projectId就不要给runs加projectId数据库操作必须下沉到 packages/db/src/operations/apps/api的 Service 应调用 operation 函数而非内联写 DB 查询并从packages/db/src/operations/index.ts导出新操作以促进复用、集中管理 DB 逻辑。数据库命令从仓库根执行需带-w packages/dbnpm run db:generate -w packages/db # 根据 schema 变更生成迁移 npm run db:migrate -w packages/db # 应用迁移 npm run db:check -w packages/db # 检查状态 npm run db:studio -w packages/db # 打开 Drizzle Studio从 packages/db/src/schema.ts 可以看到平台核心表sessions、projects、projectMembers、apiKeys、threads、runs、messages、projectMessageUsage、deviceAuthCodes等与 packages/db/migrations/ 下按序号排列的迁移文件0000_init_setup.sql至0094_stiff_sentinel.sql一一对应。七、共享包与工具的分层约定packages/core纯工具校验、JSON、加密、线程、工具函数禁止访问数据库不应有任何数据库依赖packages/backendLLM/Agent 侧辅助与流式工具复用优先禁止重复实现跨包有用的工具放 coreLLM 专属放 backend数据库相关放 db共享配置ESLint、TypeScript config集中在packages/跨包依赖使用 workspace 协议*tambo-ai/typescript-sdk是外部依赖——它由apps/api的 OpenAPI spec 经stlcCLI 生成CI 中运行工作区在stainless/详见 RELEASING.md。八、开发工作流命令体系与热重载机制常用命令# 开发注意这是两个不同的应用体系 npm run dev:cloud # 启动 Tambo Cloudweb API- 端口 8260 8261 - 使用 turbo watch npm run dev # 启动 React SDKshowcase docs npm run dev:sdk # React SDK watch 模式 showcaseSDK 开发用 npm run build:sdk # 一次性构建 React SDK # 质量检查 npm run lint # 全仓库 lint npm run lint:fix # 自动修复 lint 问题 npm run check-types # TypeScript 类型检查 npm test # 运行全部测试 npm run format # Prettier 格式化 # 单个包开发从包目录或使用 -w 标志 npm run dev -w cli # 启动指定 workspace npm run dev:showcase # 仅启动 showcase npm run build -w react-sdk # 构建指定包热重载机制按应用类型区分Next.js 应用web、showcase、docs通过transpilePackages配置直接编译 workspace 的 TypeScript 源码workspace 包core、backend、db、react的改动会自动触发 HMR无需手动重建。NestJS API使用turbo watch配合interruptible: true自动重启并监控 workspace 输入目录packages/core/src/**、packages/backend/src/**、packages/db/src/**workspace 包变化时 API 服务自动重启。这一架构可以从 turbo.json 的tambo-ai-cloud/api#dev任务定义中得到印证它声明了persistent: true、interruptible: true及上述inputs监听路径根 package.json 的dev:cloud脚本正是turbo watch dev --filtertambo-ai-cloud/web --filtertambo-ai-cloud/api。效果是编辑任意 workspace 包文件Next.js 立即 HMR、NestJS 立即重启全程无需人工干预。Turbo 命令替代方案与构建系统turbo dev # 以开发模式启动所有包 turbo build # 构建所有包 turbo lint # 全仓库 lint turbo test # 跨包运行测试 turbo check-types # 全仓库类型检查构建系统由 Turborepo 编排共享依赖在根级管理各包依赖在包内管理。构建产物按包类型区分React SDK 双 CJS/ESM、CLI 为 ESM 可执行文件、应用为 Next.js 构建产物。跨包开发时的协作检查点react-sdk 改动用npm run dev:sdk/build:sdk并跑测试与 showcase 集成验证cli 改动要测试组件生成、验证注册表更新并同步 showcaseshowcase 改动走 CLI 注册表自动同步docs 改动要确保示例与当前 API 一致。关键配置文件与知识库turbo.jsonTurborepo 任务流水线与缓存package.jsonworkspace 配置与脚本各包 package.json包级配置知识库编码标准、命名规范、加载状态等详细指南见 devdocs/新增解决方案知识时写入 devdocs/solutions/ 对应目录。九、测试与质量保障测试策略各包内单元测试用 Jest集成测试经 showcase 应用完成CLI 测试通过模板生成与安装流程验证文档测试通过示例代码校验完成后端 e2e 测试controller/module用 Jest supertest。测试文件布局文件命名所有测试必须以.test.ts或.test.tsx结尾不接受.spec等后缀单元测试与被测文件同目录存放foo.ts旁放foo.test.ts不放进__tests__集成测试是唯一允许放在__tests__目录中的测试且文件名必须描述场景不能只是另一个文件名的镜像Fixtures 与 mocks共享辅助统一放在包源码根目录的__fixtures__或__mocks__目录如 apps/web/mocks严禁嵌套在功能目录内。Mocking 纪律避免过度 mock——测试应尽可能走真实代码路径如果为了隔离单元而 mock 内部函数很可能是在测实现细节而非行为只在系统边界 mock外部 API、数据库、文件系统、网络调用及其他带副作用的 I/O不 mock 自己拥有的代码纯且快的辅助函数直接调用mock 自家代码会把测试与实现耦合。提交/PR 前验证清单npm run check-types # 全 workspace TS 类型检查 npm run lint:fix # ESLint 自动修复 npm run format # Prettier 写入 npm test # 单元/集成测试十、Git 工作流与 PR 规范分支命名格式为userid/feature-name例如alecf/add-dark-mode、jane/fix-login-bug。Conventional Commits所有 PR 标题必须遵循type(scope): description格式例如feat(api): add transcript export fix(web): prevent duplicate project creation chore(db): reorganize migration filestype 集合包括 feat、fix、perf、deps、revert、docs、style、chore、refactor、test、build、ci常用 scopeapi、web、core、db、deps、ci、config、react-sdk、cli、showcase、docs。PR 要求适用时在 PR 描述中写明 Fixes #123GitHub或 Fixes TAM-123Linear。十一、Agent 开发规则与约束必须做提交前在根目录运行npm run lint、npm run check-types、npm run test跨包改动必须一起测试文档同步三件套开发者文档变更必须同步到 docs 站点先读 docs/AGENTS.md检查并更新包根 README更新包树中的 AGENTS.md 反映变更包版本遵循语义化版本新逻辑必须补测试测试失败时不要改代码硬凑测试两条路① 让代码改动向后兼容既有测试优先② 请用户修改测试。除非用户明确要求不做破坏性变更且必须提前警告。禁止做未经明确要求不得引入依赖或修改工具配置eslint、tsconfig 等由人类负责不提交密钥一律使用 env 文件。何时询问用户任何涉及 lint 或 TypeScript 规则的改动都必须先征求用户同意。十二、Agent 行为准则与代码注释纪律AGENTS.md 对 AI Agent 的行为姿态也做了明确规定直接、坦率不奉承用户指令含糊时追问细节但不过度请求确认每段代码都被视为“关键任务”。具体到代码产出编写 JSDoc 时务必补充returns描述函数返回值不写类型类型由 TS 推断代码注释禁止引用规划文档、提案或设计文档如// See plans/foo.md——这些产物生命周期短而注释永久存在注释必须自包含规划文档、提案、设计文档存入devdocs/解决方案放devdocs/solutions/、头脑风暴放devdocs/brainstorms/等唯一例外是plans/保留在仓库根以便可见注释与文档中的 Tambo 自有 URL 一律使用tambo.co域名不用旧.ai域名遇到旧域名链接优先在相关改动中一并更新外部非 Tambo链接不受限。结语让规范成为协作的地基Tambo AI 的 AGENTS.md 本质上是一份“人与 AI 共写”的工程宪法它用 Turborepo 单仓承载 SDK 框架与云平台两条产品线用 Node.js 22 mise 固化工具链用 turbo watch HMR 消除跨包开发的等待成本再以严格但可执行的 TypeScript、前端、后端、数据库规范守住代码质量下限。无论你是人类开发者还是 AI Agent只要遵循本文梳理的结构、命令与纪律——尤其是提交前的四项验证check-types、lint:fix、format、test与“Fail-Fast、不静默兜底”的核心哲学——就能在这个仓库中高效、低摩擦地推进功能同时保持整个框架与平台的一致性。【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
