Sim 开发规范深度指南:AI Agent 工作台开源仓库的工程准则与实践

原创2026-09-09 19:44:031,988 阅读
文章标签:AI Agent人工智能工作流自动化后端前端浏览器控制

Sim 开发规范深度指南:AI Agent 工作台开源仓库的工程准则与实践

本文是面向 Sim 开源仓库(collaborative workspace for building, deploying, and monitoring AI agents and workflows)贡献者的工程规范深度指南。它以仓库根目录的 CLAUDE.md 为核心骨架,逐条解析 Sim 在 API 契约、应用操作边界、状态管理、测试与缓存上的强制性工程约束,并辅以源码佐证。读完本文,你将掌握在 Sim 仓库中编写合规 API 路由、React Query 数据层、Zustand 状态与集成模块的完整套路,以及每一类规则背后的架构动机。

一、全局工程标准:从提交到合并的硬性门槛

Sim 的开发规范首先以一组"全局标准"确立贡献门槛,这些标准由 CI 脚本强制执行,而非仅靠 Code Review 自觉。

1.1 包管理器与类型检查

  • 一律使用 bun 与 bunx,不使用 npm 与 npx。根目录 package.json 声明 "packageManager": "bun@1.4.1",全部脚本均以 bun run 驱动。
  • 类型检查在各自 workspace 内执行 bun run type-check,全局执行 bunx turbo run type-check。
  • 不得移除根 devDependencies 中的 @typescript/native 别名——它保证裸 tsc 解析到原生 TypeScript 7 编译器,而不是被 @typescript/typescript6 间接拉入、慢约 10 倍的 JS 版 TypeScript 6。该约束由 bun run check:native-typecheck 强制(见 scripts/check-native-typecheck.ts)。

1.2 日志:@sim/logger 是唯一入口

规范禁止直接使用 console.log,必须从 @sim/logger 导入 createLogger,使用 logger.info / logger.warn / logger.error。

从 packages/logger/src/index.ts 的实现可以看到这套日志体系的能力边界:

  • 提供 DEBUG / INFO / WARN / ERROR 四个 LogLevel,按 NODE_ENV 决定默认阈值:development 为 DEBUG,production 与 test 为 ERROR,可用 LOG_LEVEL 环境变量覆盖(getMinLogLevel)。
  • Logger 类支持 withMetadata(metadata) 派生子 logger,并可通过 LoggerConfig 覆盖 logLevel、colorize、enabled。
  • 生产环境输出结构化 JSON 行,源码注释明确指出"CloudWatch Log Insights 可自动解析 JSON 行";同时通过 @opentelemetry/api-logs 把每条日志扇出为 OTel Log Record,携带 log.module、error.message、log.args 等属性,实现 span → logs 关联(见 emitOtelLogRecord)。
  • 序列化永不抛错:循环引用走 tolerantReplacer,最坏情况退化为仅含 timestamp/level/module/message 的 minimalEntry,"logger 绝不能击穿调用方"。
  • 关键点:被 withRouteHandler 包裹的 API 路由内,日志会自动携带 request ID,无需手工 withMetadata({ requestId })——这来自 getRequestContext() 与 request-context.ts 的协作。

1.3 通用工具函数复用清单

规范明确禁止内联重造轮子,统一使用 @sim/utils 的共享助手(packages/utils/src):

场景 推荐用法 禁止的内联写法
延迟 sleep(ms)(@sim/utils/helpers) new Promise(resolve => setTimeout(resolve, ms))
错误归一化 toError(e)(@sim/utils/errors) 手写类型判断
错误信息提取 getErrorMessage(e, fallback?) e instanceof Error ? e.message : 'fallback'
深拷贝 structuredClone(value) JSON.parse(JSON.stringify(...))
对象裁剪 omit / filterUndefined(@sim/utils/object) Object.fromEntries(Object.entries(...).filter(...))
字符串截断 truncate(str, maxLength, suffix?)(@sim/utils/string) 内联 slice + 省略号
重试退避 backoffWithJitter / parseRetryAfter(@sim/utils/retry) 内联指数退避

1.4 ID 生成:为什么不用 crypto.randomUUID()

规范禁止使用 crypto.randomUUID()、nanoid 或 uuid 包,统一改用 @sim/utils/id 的 generateId()(UUID v4)与 generateShortId()(紧凑型)。

阅读 packages/utils/src/id.ts 可理解其动机:crypto.randomUUID() 要求安全上下文(HTTPS 或 localhost),自托管部署走纯 HTTP 时会抛 TypeError: crypto.randomUUID is not a function。generateId() 优先尝试 randomUUID,失败则退回 crypto.getRandomValues() 手工构造 v4 UUID;generateShortId(size = 21, alphabet?) 则完全基于 getRandomValues() 实现,替代 nanoid,同样兼容非安全上下文。

1.5 部署标志:浏览器端必须走 useDeploymentShape

客户端代码读取 hosted、billingEnabled、chatEnabled 及企业特性集时,必须通过 useDeploymentShape()(组件内)或 getDeploymentShape()(block 条件、stores、helpers)读取,禁止从 env-flags 直接读 isHosted/isBillingEnabled。原因在规范中解释得很清楚:这些常量在模块初始化时从根 layout 的 NEXT_PUBLIC_* 传输中冻结,而 Next 的裸 404 shell 与 global-error 从不发射这些值,读取器改为从服务端解析的 workspace host 上下文注入。服务端代码则继续直接读 env-flags。

1.6 其他硬性规则

  • 注释:使用 TSDoc,禁止 ==== 分隔符与非 TSDoc 注释。
  • 样式:永不修改全局样式,样式全部局部化到组件。
  • Lint/Audit:PR 必须通过 bun run check:api-validation,不得引入路由局部的边界 Zod schema、直接的路由 Zod 导入或临时的客户端 wire 类型。

二、架构原则与应用操作边界

2.1 核心原则

  1. 单一职责:每个组件、hook、store 只有一个清晰目的。
  2. 组合优于复杂:把复杂逻辑拆成更小的片段。
  3. 类型安全优先:所有 props、state、返回类型都用 TypeScript 接口。
  4. 可预测的状态:全局状态用 Zustand,纯 UI 状态用 useState。

2.2 Application Operation Boundary(应用操作边界)

这是 Sim 架构中最核心的安全模型,规范用四条边界划分职责:

  • 应用用例(Application Use Case):所有受保护读、写、规范资源查找、授权敏感引用解析都必须进入授权的应用用例。每个用例定义唯一的语义操作,声明最小角色、workspace-key 策略、允许的 principal 种类与委托服务。Internal API、v2 API、Copilot 与受信工具在领域行为相同时调用同一用例。受保护的复合变更必须归属一个顶层语义操作,禁止在 route 或 tool 适配器中串行执行多个独立提交的变更。
  • 表面适配器(Surface Adapter):负责认证并构造 Principal、应用请求速率策略、解析契约、映射输入、呈现结果。它绝不查询受保护数据、不裁决资源授权、不实现业务事务、不记录语义审计。
  • 应用用例内部职责:加载规范上下文、比对断言的作用域、授权当前访问、执行 managers/repositories、投影语义审计、触发共享领域效应。Managers 只接受规范 ID 和作用域,绝不接收凭据或 principal。
  • Copilot 是表面适配器:必须使用 createCopilotApplicationAdapter 与领域注册的操作对象,禁止创建 Copilot 专属的授权或业务实现。

规范还强调:绝不能用计费所有者、上传者、创建者或 API-key 所有者顶替行为 principal;当身份模型或操作策略无法表达调用者时必须快速失败。新增或迁移受保护端点、工具命令、资源方法时,使用 migrate-application-operation skill。

2.3 仓库根结构

apps/
├── sim/                    # Next.js app(UI + API 路由 + 工作流编辑器)
│   ├── app/                # Next.js App Router(页面、API 路由)
│   ├── blocks/             # Block 定义与注册表
│   ├── components/         # 共享 UI(emcn/、ui/)
│   ├── executor/           # 工作流执行引擎
│   ├── hooks/              # 共享 hooks(queries/、selectors/)
│   ├── lib/                # 应用级工具
│   ├── providers/          # LLM provider 集成
│   ├── stores/             # Zustand stores
│   ├── tools/              # 工具定义
│   └── triggers/           # 触发器定义
└── realtime/               # Bun Socket.IO 服务(协作画布)

packages/
├── audit/                  # @sim/audit
├── auth/                   # @sim/auth — 共享 Better Auth 验证器
├── db/                     # @sim/db — drizzle schema + client
├── logger/                 # @sim/logger
├── platform-authz/         # @sim/platform-authz — workspace + workflow 授权
├── realtime-protocol/      # @sim/realtime-protocol — socket 操作常量 + zod schemas
├── security/               # @sim/security — safeCompare
├── tsconfig/               # 共享 tsconfig 预设
├── utils/                  # @sim/utils
├── workflow-persistence/   # @sim/workflow-persistence
└── workflow-types/         # @sim/workflow-types — 纯 BlockState/Loop/Parallel 类型

2.4 包边界

  • 只允许 apps/* → packages/*,包永远不得反向导入 apps/*。
  • apps/realtime 刻意不依赖 Next.js、React、block/tool 注册表、provider SDK 与 executor;不得向任何被 apps/realtime 消费的包添加 @/lib/webhooks/providers/*、@/executor/*、@/blocks/*、@/tools/* 的导入。CI 通过 scripts/check-monorepo-boundaries.ts 与 scripts/check-realtime-prune-graph.ts 强制。
  • 认证通过 Better Auth "Shared Database Session" 模式在两个应用间共享(同一 BETTER_AUTH_SECRET、同一 @sim/db 数据库)。

2.5 命名约定

类别 约定 示例
组件 PascalCase WorkflowList
Hooks use 前缀 useWorkflowOperations
文件 kebab-case workflow-list.tsx
Stores stores/feature/store.ts —
常量 SCREAMING_SNAKE_CASE ENTITY_LIST_STALE_TIME
接口 PascalCase 加后缀 WorkflowListProps

三、导入规范与 TypeScript 约束

3.1 绝对导入与导入顺序

永远使用绝对导入,禁止相对导入:

// ✓ Good
import { useWorkflowStore } from '@/stores/workflows/store'

// ✗ Bad
import { useWorkflowStore } from '../../../stores/workflows/store'

文件夹导出达 3 个及以上时使用 barrel 文件(index.ts);不要在非 barrel 文件里做再导出。导入顺序固定为:React/核心库 → 外部库 → UI 组件(@sim/emcn、@/components/ui)→ 工具(@/lib/...)→ Stores(@/stores/...)→ 特性导入 → CSS 导入。类型专用导入使用 import type { X }。

3.2 TypeScript 规则

  1. 禁止 any,使用恰当类型或 unknown + 类型守卫;
  2. 组件必须定义 props 接口;
  3. 常量对象/数组使用 as const;
  4. 显式 ref 类型:useRef<HTMLDivElement>(null)。

3.3 组件写法

'use client' // 仅在使用 hooks 时

const CONFIG = { SPACING: 8 } as const

interface ComponentProps {
  requiredProp: string
  optionalProp?: boolean
}

export function Component({ requiredProp, optionalProp = false }: ComponentProps) {
  // 顺序:refs → 外部 hooks → store hooks → 自定义 hooks → state → useMemo → useCallback → useEffect → return
}

抽取时机:超过 50 行、被 2+ 文件使用、或自带 state/logic 时抽取;少于 10 行、单次使用、纯展示时保持内联。规范还点名了几条保持渲染性能的惯用法:懒初始化对象 ref、把无闭包的常量/函数提升到模块作用域、用 Map/Set 预索引重复查找、绝不原地修改共享数组。特别警告:尽管 tsconfig 的 lib 包含 ES2023,toSorted/toReversed 在客户端渲染路径上不安全——SWC 不 polyfill 原型方法,应改用 [...arr].sort()。

四、API 契约体系:前后端共享的唯一事实源

4.1 契约文件布局

apps/sim/app/api/** 下所有路由的边界 HTTP 请求/响应形状都集中在 apps/sim/lib/api/contracts,按资源族一个文件(folders.ts、chats.ts、knowledge/、selectors/、tools/、v2/ 等)。路由绝不定义路由局部边界 Zod schema,客户端绝不定义临时 wire 类型——两侧消费同一契约。

需要特别注意 contracts/index.ts 顶部注释揭示的设计决策:./tools、./selectors、./v1、./demo-requests 刻意不从 barrel 再导出。因为这些契约的 Zod schema 构造代码约有 60 KB gzip,schema 对象在模块作用域构建,export * 会破坏 tree-shaking,把所有路由拖下水。因此消费者必须从具体契约文件直接导入。

4.2 契约的构建方式

每个契约用 defineRouteContract({ method, path, params?, query?, body?, headers?, response: { mode: 'json', schema } }) 构建,该函数定义在 apps/sim/lib/api/contracts/types.ts,是一个纯类型透传的构造器——它不运行任何校验,只让 TS 推断出完整的契约泛型。

import { defineRouteContract } from '@/lib/api/contracts'
import { z } from 'zod'

export const createFolderBodySchema = z.object({
  name: z.string().min(1, 'Folder name cannot be empty').max(255),
})

export const createFolderContract = defineRouteContract({
  method: 'POST',
  path: '/api/workspaces/:workspaceId/folders',
  params: { workspaceId: workspaceIdSchema },
  body: createFolderBodySchema,
  response: { mode: 'json', schema: createFolderResponseSchema },
})

规范要求契约同时导出命名 schema(如 createFolderBodySchema)与命名类型别名(export type CreateFolderBody = z.input<typeof createFolderBodySchema>)。客户端只导入命名类型别名,永远不自写 z.input<...> / z.output<...>。共享标识符 schema(如 workspaceIdSchema、workflowIdSchema)集中在 contracts/primitives.ts,必须复用而不是重定义基于字符串的 ID schema。

契约规则是边界专属的:非 HTTP 边界的领域校验器(tools、blocks、triggers、connectors、realtime handlers、内部助手)仍可直接使用 Zod。

4.3 v2 路由的 query 声明规则

/api/v2/ 契约必须声明 query。原因是 parseRequest 只在声明了 query 切片时才校验查询串——省略 query 意味着"从不查看查询串",此时 ?bogus=1 会对一个服务器根本没理会的请求返回 200。确实没有查询参数时用 query: noInputSchema(z.object({}).strict(),定义于 primitives.ts)显式声明。该规则由 contracts/v2/__tests__ 下的 query-declaration 扫描强制。

4.4 边界注解(Boundary Annotations)

少数合法例外通过注解容忍,审计脚本识别四种形式:

注解 放置位置 适用场景
// boundary-raw-fetch: <reason> 客户端 hook 中裸 fetch( 调用的上一行;以及 apps/sim/** 下 API 路由处理器之外任何同源 /api/... fetch 流式响应、二进制下载、multipart 上传、签名 URL 流程、OAuth 重定向、外部源请求
// double-cast-allowed: <reason> 测试文件之外 as unknown as X 转换的上一行 需要双重转换的少数场景
// boundary-raw-json: <reason> 路由处理器中裸 await request.json() 读取的上一行 JSON-RPC 信封、容忍的 .catch(() => ({})) 解析、无法走 parseRequest 的 body
// untyped-response: <reason> 契约文件中 schema: z.unknown() 声明上一行 响应体真正不透明(用户提供数据、第三方透传)

放置规则:注解必须紧邻调用或转换,允许至多三行非空前置注释,reason 修剪后必须非空(空 reason 在严格模式触发 annotationsMissingReason)。整文件豁免走 scripts/check-api-validation-contracts.ts 的 INDIRECT_ZOD_ROUTES 白名单,而不是逐行注解。

// boundary-raw-fetch: streaming SSE chunks must be processed as they arrive
const response = await fetch(`/api/copilot/chat/stream?chatId=${chatId}`, { signal })
// double-cast-allowed: legacy provider type lacks the discriminator field we need
const provider = config as unknown as LegacyProvider

五、API 路由模式:声明式构建器

5.1 路由必须跑在 withRouteHandler 内

每个路由方法必须在 withRouteHandler 内执行。普通 internal 与 v2 JSON/二进制路由使用 defineInternalJsonRoute、defineV2JsonRoute 或对应的 binary/stream 构建器——这些构建器已经应用了 withRouteHandler,绝不能再包一层。裸 withRouteHandler 只用于明确的协议或生命周期例外:流式、multipart 控制、大 body 准入、OAuth、公开执行。

路由绝不 import { z } from 'zod',绝不定义路由局部边界 schema。声明式构建器接管认证、准入、解析、用例执行、响应校验与错误投影。特殊路由消费同一契约,并用 @/lib/api/server 的规范助手在校验与廉价准入之后校验:

  • parseRequest(contract, request, context, options?):一次性解析 params、query、body、headers;无路由参数时 context 传 {},有路由参数时传路由的 context 参数。返回判别联合,检查 parsed.success,失败时返回 parsed.response。
  • validationErrorResponse(error) 与 getValidationErrorMessage(error, fallback):从 ZodError 产生 400 响应。
  • validationErrorResponseFromError(error):处理可能是也可能不是 ZodError 的未知捕获错误。
  • isZodError(error):类型守卫,路由绝不使用 instanceof z.ZodError。

5.2 普通受权 JSON 路由样板

export const PATCH = defineInternalJsonRoute({
  contract: renameWidgetContract,
  auth: internalSessionAuth,
  operation: widgetOperations.rename,
  rateLimit: internalRateLimits.none({ reason: 'Preserve existing internal behavior' }),
  errorPolicy: internalWidgetErrorPolicy,
  mapInput: ({ params, body }) => ({
    widgetId: params.widgetId,
    assertedWorkspaceId: params.workspaceId,
    name: body.name,
  }),
  useCase: renameWidget,
  present: ({ widget }) => ({ success: true, widget }),
})

执行顺序要点:认证与请求速率准入发生在解析之前;规范加载与授权发生在应用用例内;presenter 只返回表面成功体。契约、操作与用例必须在定义时保持一致。apps/sim/app/api/v1/** 下的路由使用 apps/sim/app/api/v1/middleware.ts 的共享中间件处理 auth、限流与 workspace 访问,契约校验在中间件内组合,绝不逐路由重实现 auth/限流。永远不要导出裸的 async function GET/POST/...,而是导出共享构建器的结果或(对文档化的特殊路由)withRouteHandler(...)。

5.3 端到端新增一个边界特性

  1. 先写契约:在 apps/sim/lib/api/contracts/<domain>.ts(大领域用子目录:knowledge/、selectors/、tools/),为每个请求切片(params/query/body/headers)与响应各定义一个 schema,用 defineRouteContract 包裹,导出命名类型别名(输入用 z.input,输出用 z.output)。
  2. 定义语义操作与应用用例:在 apps/sim/lib/<domain>/application/ 下,用例负责规范加载、断言作用域检查、当前授权、业务行为、语义审计与共享领域效应。
  3. 实现路由适配器:在 apps/sim/app/api/<path>/route.ts 用合适的共享构建器,声明 auth、operation、限流策略、错误策略、输入映射、用例与 presenter。认证永远先于解析;只有明确的特殊路由才用裸 withRouteHandler,受保护工作留在应用用例内。
  4. 添加 React Query hook:在 apps/sim/hooks/queries/<domain>.ts,调用用 requestJson(contract, input)。构建层级化 query-key 工厂(all → lists() → list(workspaceId) → details() → detail(id)),让失效可以按前缀定位。
  5. 在组件中使用 hook:mutation 的 data 与 error 完全由契约推导类型;直接展示 error.message(requestJson 已从响应体的 error 或 message 字段提取)。

5.4 Schema Review 清单(像读 DB migration 一样读契约 diff)

CI 能抓结构性违规(路由内的 Zod 导入、裸 request.json()、双重转换、缺失注解),但抓不住这些 schema 质量判断——它们是人类 PR 评审的职责:

  • required vs optional vs nullable 必须正确:optional() 允许省略,nullable() 允许 null,两者串联会产生几乎从不需要的三态。
  • 响应 schema 必须匹配路由实际 JSON 输出:最常见的漂移 bug——路由发出 schema 未声明的字段,或漏掉必填字段。把每个 NextResponse.json(...) 调用点与 schema 对照一遍。
  • 错误信息要有描述性:'fileName cannot be empty' 优于 'Required'。用 min(1, '...')、nonempty('...') 的第二参数;跨字段 refine 用带 path 与点名失败字段消息的 superRefine。
  • 设置边界:数组 .min(1) / .max(N),字符串(ID/名称).min(1).max(N),数字(limits/sizes).min().max()。
  • z.unknown() 是异味,除非数据真正任意(provider 透传、用户定义工具结果、JSON-RPC 信封);保留时必须在 schema: 槽标注 // untyped-response: <具体原因>。
  • 线上有判别字段时用判别联合而非普通联合,给客户端穷尽式收窄。

六、Hooks、Zustand 与 React Query 数据层

6.1 Hooks 样板

interface UseFeatureProps { id: string }

export function useFeature({ id }: UseFeatureProps) {
  const idRef = useRef(id)
  const [data, setData] = useState<Data | null>(null)

  useEffect(() => { idRef.current = id }, [id])

  const fetchData = useCallback(async () => { ... }, []) // 使用 refs 时空依赖

  return { data, fetchData }
}

6.2 Zustand Stores

Store 放在 stores/,复杂 store 拆成 store.ts + types.ts:

import { create } from 'zustand'
import { devtools } from 'zustand/middleware'

const initialState = { items: [] as Item[] }

export const useFeatureStore = create<FeatureState>()(
  devtools(
    (set, get) => ({
      ...initialState,
      setItems: (items) => set({ items }),
      reset: () => set(initialState),
    }),
    { name: 'feature-store' }
  )
)

规则:使用 devtools 中间件;只有数据需要跨刷新存活时才用 persist,并用 partialize 只持久化必要状态。

6.3 React Query:全部服务端状态必须走 React Query

所有 React Query hooks 位于 hooks/queries/。组件内禁止用 useState + fetch 做数据获取或变更——服务端状态必须全部经过 React Query。

客户端边界:hook 与路由消费同一契约。所有同源 JSON 调用必须走 @/lib/api/client/request 的 requestJson(contract, ...),而不是裸 fetch。requestJson 出发时按契约解析 params、query、body、headers,返回时校验 JSON 响应;hook 必须始终转发 signal 以便取消。裸 fetch 的文档化例外(流式、二进制下载、multipart 上传、签名 URL、OAuth 重定向、外部源请求)需要 TSDoc 注释说明,且 // boundary-raw-fetch 注解在 apps/sim/** 下任何非路由处理器的同源 fetch 处都是强制的。

import { keepPreviousData, useQuery } from '@tanstack/react-query'
import { requestJson } from '@/lib/api/client/request'
import { listEntitiesContract, type EntityList } from '@/lib/api/contracts/entities'

export const ENTITY_LIST_STALE_TIME = 60 * 1000

async function fetchEntities(workspaceId: string, signal?: AbortSignal): Promise<EntityList> {
  const data = await requestJson(listEntitiesContract, {
    query: { workspaceId },
    signal,
  })
  return data.entities
}

export function useEntityList(workspaceId?: string) {
  return useQuery({
    queryKey: entityKeys.list(workspaceId),
    queryFn: ({ signal }) => fetchEntities(workspaceId as string, signal),
    enabled: Boolean(workspaceId),
    staleTime: ENTITY_LIST_STALE_TIME,
    placeholderData: keepPreviousData,
  })
}

Query Key 工厂:每个文件必须有层级化 key 工厂,含 all 根键与中间复数键以便前缀失效:

export const entityKeys = {
  all: ['entity'] as const,
  lists: () => [...entityKeys.all, 'list'] as const,
  list: (workspaceId?: string) => [...entityKeys.lists(), workspaceId ?? ''] as const,
  details: () => [...entityKeys.all, 'detail'] as const,
  detail: (id?: string) => [...entityKeys.details(), id ?? ''] as const,
}

Query Hooks 规则:

  • 每个 queryFn 必须转发 signal 以便取消请求;
  • 每个 query 必须有显式 staleTime,赋值为命名导出常量而非内联数字字面量——服务端 prefetch 水合同一 query key 时必须导入并复用该常量,避免两者漂移;
  • keepPreviousData 只用于参数可变的 query,绝不用于静态 key。

Mutation Hooks 规则:

  • 优先定向失效(entityKeys.lists())而非宽泛失效(entityKeys.all);
  • 乐观更新用 onSettled(成功与失败都会触发)而非 onSuccess 做缓存对账;
  • useCallback 依赖中不要包含 mutation 对象——TanStack Query v5 中 .mutate() 是稳定的。
export function useUpdateEntity() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: async (variables) => { /* ... */ },
    onMutate: async (variables) => {
      await queryClient.cancelQueries({ queryKey: entityKeys.detail(variables.id) })
      const previous = queryClient.getQueryData(entityKeys.detail(variables.id))
      queryClient.setQueryData(entityKeys.detail(variables.id), /* optimistic */)
      return { previous }
    },
    onError: (_err, variables, context) => {
      queryClient.setQueryData(entityKeys.detail(variables.id), context?.previous)
    },
    onSettled: (_data, _error, variables) => {
      queryClient.invalidateQueries({ queryKey: entityKeys.lists() })
      queryClient.invalidateQueries({ queryKey: entityKeys.detail(variables.id) })
    },
  })
}

七、URL 状态、列表排序与样式规范

7.1 URL / Query-Param 状态

可分享的客户端视图状态(激活 tab/panel、过滤器、搜索词、分页、选中实体 id、视图模式、深链抽屉/弹窗)放在 URL 中,通过 nuqs 管理——而不是用与 effects 同步的 store,也绝不用 useSearchParams().get(...) / new URLSearchParams(window.location.search) 读取。远程数据留在 React Query;高频/大/短暂/socket 同步的状态留在 Zustand(画布平移缩放、光标、拖拽、resize 宽度、实时协作选择)。

每个特性旁放置 search-params.ts 导出解析器 map(唯一事实源),供客户端 useQueryStates/useQueryState 与服务端 createSearchParamsCache 共享。客户端参数解析禁止 import { z }——使用 nuqs parsers。

7.2 列表与菜单排序

一条列表按"用户在其他地方读同一事物的方式"排序:资源菜单(+ 附加、@ 提及、资源标签 +)镜像侧边栏自上而下;行或根上下文菜单镜像该表面的工具栏,从左到右变成自上而下;标签条镜像其导航。平台专属条目(桌面 Browser、Terminal)排在共享集合之后。

顺序编码进一个导出常量并按它排序(RESOURCE_MENU_ORDER / byResourceMenuOrder,位于 home/components/mothership-view/components/resource-registry),禁止每个菜单手维护字面量。混合条目类型必须在一次有序遍历中渲染——先发所有子菜单族再发所有扁平项,会把每个子菜单静默钉在顶部。

分组:DropdownMenuSeparator 标记操作对象的变化——点击项(无规则)、页面过滤器或新同级(有规则)、销毁(有规则)。多数行菜单只有销毁转换,在 Delete/Leave/Close/Hide 前携带一条规则;同时过滤页面或插入同级的菜单携带两条。禁止按动词分组(导航/状态/编辑/复制)——工具栏是扁平的,该分类在其他任何表面都不存在。每个分隔符的 guard 必须由两侧条目精确的渲染条件构建。

7.3 样式与 EMCN 组件

只用 Tailwind,不用内联样式;条件类用 @sim/emcn 的 cn():

<div className={cn('base-classes', isActive && 'active-classes')} />

等高宽用 size-* 简写(默认图标 size-[14px]),禁止 h-[Npx] w-[Npx]。chip 组件通过 props 驱动 chrome(error、icon/endAdornment、inputClassName),className 只携带布局/尺寸——绝不重写规范 chrome(border、fill、radius、height、文字/图标色)或添加 focus ring。

EMCN 组件从 @sim/emcn barrel 导入组件、cn 与 tokens,图标从 @sim/emcn/icons 子路径导入,CSS modules 从文件路径导入,禁止深导入其他子路径。只有存在 2+ 个真实变体时才用 CVA,否则普通 cn()。chip 家族是规范 UI chrome:ChipInput 取代 Input、ChipTextarea 取代 Textarea、ChipModal/ChipModalField 取代 Modal、ChipSelect/ChipCombobox/ChipDropdown 取代 Select/Combobox、ChipSwitch 取代 Switch、ChipDatePicker 取代裸日期字段、Chip/ChipLink 做胶囊按钮/链接、ChipTag 做内联标签。上下文/操作菜单的标准控件是 DropdownMenu。

ChipModalBody 内每个带标签字段必须是 ChipModalField:ChipModalBody 应用 px-2 + gap-4,ChipModalField 再叠加 px-2,使每个字段落在有效 px-4,与 ChipModalHeader/ChipModalFooter(px-4)精确对齐。手写行会跳过字段 gutter 落在 px-2,与头部/底部明显错位。ChipModalField 未覆盖的控件(ChipCombobox、ChipSelect、DatePicker、TimePicker、ButtonGroup、任意 JSX)用 ChipModalField type='custom' 配 title。

设计系统整合原则:共享 chrome 只有一个规范事实源,组合它而不是逐消费者重新推导;props 驱动 API 优于 className 覆盖;多模式用判别联合 props(如 ChipDropdown multiple)而非近似重复组件;迁移后删除遗留变体;单错误/状态切换用普通 cn(),真正多变体才用 CVA;对齐规范默认值(常规字重、--text-body 文本、--text-icon 图标);确认引用的 CSS 变量存在——未定义变量会静默回退到 currentColor(黑字 bug)。

八、测试规范:Vitest 与性能红线

使用 Vitest,测试文件命名 feature.ts → feature.test.ts。

全局 Mock(vitest.setup.ts):@sim/db、@sim/db/schema、drizzle-orm、@sim/logger、@sim/platform-authz/workflow、@/blocks/registry、@/lib/auth、@/lib/auth/hybrid、@/lib/core/utils/request、@trigger.dev/sdk 与 store mocks 已全局提供,不要重复 mock(除非覆盖行为)。

标准测试模式:

/**
 * @vitest-environment node
 */
import { createMockRequest } from '@sim/testing'
import { beforeEach, describe, expect, it, vi } from 'vitest'

const { mockGetSession } = vi.hoisted(() => ({
  mockGetSession: vi.fn(),
}))

vi.mock('@/lib/auth', () => ({
  auth: { api: { getSession: vi.fn() } },
  getSession: mockGetSession,
}))

import { GET } from '@/app/api/my-route/route'

describe('my route', () => {
  beforeEach(() => {
    vi.clearAllMocks()
    mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
  })
  it('returns data', async () => { ... })
})

性能红线(这些是明确禁止项):

  • 绝不用 vi.resetModules() + vi.doMock() + await import()——用 vi.hoisted() + vi.mock() + 静态导入;
  • 绝不用 vi.importActual()——显式 mock 一切;
  • 绝不用 @sim/testing 的 mockAuth()、mockConsoleLogger()、setupCommonApiMocks()——它们在内部使用 vi.doMock();
  • 不需要重依赖的测试要 mock 重型依赖(@/blocks、@/tools/registry、@/triggers);
  • 除非需要 DOM API(window、document、FormData),一律用 @vitest-environment node;
  • 避免真实计时器——用 1ms 延迟或 vi.useFakeTimers()。

优先使用 @sim/testing 的 mocks/factories 而非本地测试数据。

九、缓存规则:永远别手写 TTL

规范禁止手写 TTL 算术——Map + Date.now() - fetchedAt < TTL 会糟糕地重实现过期、上限与合并。必须用直接依赖 lru-cache,并且总是设置 max:ttl 单独不约束内存,租户键控缓存没有上限会随进程生命周期无限增长。

首选 fetchMethod + cache.fetch(key) 做异步 read-through——一个原语同时获得 TTL、合并与拒绝时驱逐;只有挂起的生产者会把调用者卡满整个 TTL 时,才在 LRUCache 外层组合 coalesceLocally。

关键判断:先确认它到底是不是缓存——生命周期 map(被追踪事物结束时删除条目,如 activeStreams、pendingChildRuns)是普通 Map,给它加 TTL 或上限会引入与生命周期竞态的过期。缓存门禁,绝不缓存凭据——权限可容忍安全方向的有界陈旧,密钥材料必须保鲜以便撤销即时生效。

十、Utils 规则与新增集成

Utils 规则:单一消费者的 utils.ts 不要创建——内联;2+ 文件需要同一助手时才创建 utils.ts;在 lib/ 中检查既有来源,不要重复实现。

新增集成顺序:Tools → Block → Icon →(可选)Trigger,先查服务商 API 文档。两条硬规则:

  1. Tool ID 用 snake_case(service_action),必须在 tools/registry.ts 注册;block 在 blocks/registry-maps.ts 注册——BLOCK_REGISTRY 配置 map 与 BLOCK_META_REGISTRY 目录元数据 map(按字母序)。blocks/registry.ts 只放访问器函数(getBlock、getAllBlocks…)。
  2. tools.config.tool 在序列化阶段执行(变量解析之前)——绝不要在那里做 Number() 等类型转换,否则动态引用如 <Block.output> 会被破坏。所有类型转换放在 tools.config.params,它在执行阶段、变量解析完成后运行。

十一、Tables 列类型注册表

表列类型是 apps/sim/lib/table/column-types 中的注册表条目——每个类型一个文件,拥有自己的标签、图标、存储转换、强制转换、校验、转换兼容性、格式化与编辑器。registry.ts 与 registry.server.ts 上的 Record<ColumnType, …> 是编译期完整性闸门:向联合类型添加类型后,两个条目缺失任一都会报错。

禁止在 column-types/ 之外添加 case 'sometype':——缺失的分支会静默失败(错误的 jsonbCast 会破坏该列上的每个过滤器)。如果消费者需要按类型知识,就添加注册表字段。完整流程用 /add-column-type skill。

十二、与 AGENTS.md 的分工

CLAUDE.md 是面向人类工程师与 AI 协作者的工程规范主体。仓库中另有 AGENTS.md(根级)与各子目录的 AGENTS.md(如 apps/sim/AGENTS.md、blocks/AGENTS.md),它们按目录组织更细粒度的指导。若你正在阅读本指南并打算提交代码,建议将 CLAUDE.md 中的 API 契约、路由构建器与测试红线作为最优先遵循项——它们是 CI(bun run check:api-validation:strict、check-monorepo-boundaries、check-react-query 等)直接背书的强制规范。

结语

Sim 的开发规范文档将"可执行的工程纪律"写成了代码:契约先行、边界注解化、路由声明式、状态分层、测试性能红线——每一类规则都能在根目录 package.json 的脚本(check:* 系列)与 scripts 目录中找到对应的强制工具。对贡献者而言,理解这套规范不仅是满足 CI 的通过条件,更是进入一个大型 AI Agent 工作台代码库的正确姿势:契约是前后端的唯一事实源,应用用例是授权的唯一入口,而缓存、日志、ID 与工具函数则共享一套经过验证的基础设施。

登录后查看全文
sim