Sim 开发规范深度指南: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 核心原则
- 单一职责:每个组件、hook、store 只有一个清晰目的。
- 组合优于复杂:把复杂逻辑拆成更小的片段。
- 类型安全优先:所有 props、state、返回类型都用 TypeScript 接口。
- 可预测的状态:全局状态用 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 规则
- 禁止
any,使用恰当类型或unknown+ 类型守卫; - 组件必须定义 props 接口;
- 常量对象/数组使用
as const; - 显式 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、公开执行。
defineInternalJsonRoute定义于 apps/sim/lib/api/server/routes/internal-json-route.ts;defineV2JsonRoute定义于 apps/sim/lib/api/server/routes/v2-json-route.ts。
路由绝不 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 端到端新增一个边界特性
- 先写契约:在
apps/sim/lib/api/contracts/<domain>.ts(大领域用子目录:knowledge/、selectors/、tools/),为每个请求切片(params/query/body/headers)与响应各定义一个 schema,用defineRouteContract包裹,导出命名类型别名(输入用z.input,输出用z.output)。 - 定义语义操作与应用用例:在
apps/sim/lib/<domain>/application/下,用例负责规范加载、断言作用域检查、当前授权、业务行为、语义审计与共享领域效应。 - 实现路由适配器:在
apps/sim/app/api/<path>/route.ts用合适的共享构建器,声明 auth、operation、限流策略、错误策略、输入映射、用例与 presenter。认证永远先于解析;只有明确的特殊路由才用裸withRouteHandler,受保护工作留在应用用例内。 - 添加 React Query hook:在
apps/sim/hooks/queries/<domain>.ts,调用用requestJson(contract, input)。构建层级化 query-key 工厂(all→lists()→list(workspaceId)→details()→detail(id)),让失效可以按前缀定位。 - 在组件中使用 hook:mutation 的
data与error完全由契约推导类型;直接展示error.message(requestJson已从响应体的error或message字段提取)。
5.4 Schema Review 清单(像读 DB migration 一样读契约 diff)
CI 能抓结构性违规(路由内的 Zod 导入、裸 request.json()、双重转换、缺失注解),但抓不住这些 schema 质量判断——它们是人类 PR 评审的职责:
requiredvsoptionalvsnullable必须正确: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 文档。两条硬规则:
- 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…)。 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 与工具函数则共享一套经过验证的基础设施。