code-style

name	code-style
description	IoT AI Platform 的 TypeScript 严格模式、错误处理、测试策略、依赖管理、Git commit 规范、安全编码守则。编写任何代码前先读本 Skill。

代码风格与工程规范

TypeScript 严格模式

• strict: true, noUncheckedIndexedAccess: true, exactOptionalPropertyTypes: true
• 不允许 any。必须用 unknown + zod/runtime 校验
• 所有公开导出函数必须显式标注返回类型
• Discriminated union 优于 boolean flag

错误处理

• 所有 async 函数 await 必须有 try-catch 或被显式上游包裹
• Error 必须带可诊断上下文（eventId, tenantId, accountId, status, response body）
• 外部 API 错误不要原样上抛，转换为业务 Error 并附加上下文
• 绝不静默吞错误——任何 catch 块如果不向上抛，必须有日志 + 说明

测试

• Vitest，文件与源文件同目录或 tests/，命名 *.test.ts
• 每个 Agent/Tool/Workflow 至少 happy path + error path
• LLM 调用用 MockLanguageModelV1 mock；无网络依赖的单元测试
• Solution Pack manifest 配 golden-file 测试（声明式制品的回归网，ADR-0007）
• 补 docs/AUDIT.md 指出的测试空洞（workflow / fact-extraction / runtime 模块）

依赖管理

• 版本固定 minor (^x.y.z)；devDependencies 与 dependencies 严格区分
• 复用外部成熟件、不重造（ADR-0009）；但不引入与既有选型重复功能的包

Git Commit

• Conventional Commits: feat(scope):, fix(scope):, docs(scope):, refactor(scope):, test(scope):, chore(scope):, perf(scope):
• PR ≤ 500 行，含 What/Why/How tested
• 偏离架构决策的 PR 必须链接 ADR

安全（ADR-0014）

• 所有用户输入用 zod 校验；SQL 必须参数化
• 密钥走 Infisical（逐 Tenant 命名空间）——不进源码、不进 Git、不进 Pack manifest
• 租户上下文只从服务端取（tenant+account），绝不信客户端传入（防串号/防跨租户模型变体泄露）
• Pack manifest 只引用白名单工具、不内联代码；加载前 Zod 强校验
• 生产 Postgres 必须 SSL