umtandClaude Fable 5.1
b22c440139
- pnpm workspace: apps/{web,server}, packages/{contracts,db,domain,adapters,tasks,agent,testkit}
- server: Hono + zod-openapi, API Key auth with scopes, redacting pino logger, SSE event bus with replay, worker heartbeat
- db: Kysely + pg, file migrator, 0001_init (settings/api_key/audit_event/outbox_event)
- web: React Router 7 SPA console shell with 12 workspace placeholders, uhd_web tokens/ui/guard scripts
- docs: ADR-001 (Node over Deno), dev runbook, design system rules
Co-Authored-By: Claude Fable 5.1 <[email protected]>
1.9 KiB
1.9 KiB
ADR-001:运行时采用 Node.js 24 LTS + pnpm workspace,而非 Deno
- 状态:已采纳(2026-09-27)
- 关联:REQ §9(技术架构选择)、docs/plan/00-first-version-plan.md §1
背景
需求文档 v0.7 的技术方向是"TypeScript + 最新稳定版 Deno(部署固定版本)+ PostgreSQL + Pi"。REQ §9 同时允许:在有明确依赖障碍时评估替代方案,并记录代价。
决定
v0.1 使用 Node.js 24 LTS + pnpm workspace + TypeScript 5.9 strict。前端沿用 /opt/uhd_web 的 React Router 7 + Vite 7 + Tailwind v4 + shadcn 技术栈,后端用 Hono 4(@hono/node-server)。
理由
- 用户指定沿用 uhd_web 技术栈。 设计系统、组件、token 守卫脚本、构建与 CI 习惯都直接复用,前后端同一套工具链(pnpm、vitest、tsc)。
- 开发机没有安装 Deno。 引入第二套运行时会增加环境成本,且 uhd_web 相关脚本均基于 Node。
- 候选依赖以 Node 为主要目标。 OpenWorkflow(peer 依赖 postgres.js)与 Pi(
@earendil-works/pi-*)的文档与测试以 Node 为主,在 Deno 下需要额外兼容性验证;用 Node 可以把 W0 spike 集中在业务语义(恢复/信号/取消/重试)上。 - REQ §9 允许记录代价后替代,产品行为要求不受运行时影响。
代价
- 失去 Deno 的默认权限沙箱(
--allow-net等)。REQ §10.2 要求的"进程权限、容器挂载、网络白名单"须在部署层(容器只读挂载、出站白名单)和业务层(能力注册中心显式白名单)落实,不能依赖运行时。 - 失去 Deno 内置的 fmt/lint/test,改用 biome + vitest,需要自行锁版本。
- npm 依赖面更大,需锁定
pnpm-lock.yaml,并对 install 脚本做白名单(pnpm-workspace.yaml的allowBuilds)。
复议条件
若后续部署要求强制运行时级权限隔离,或 Pi / OpenWorkflow 转为 Deno 优先,再评估迁移;领域包(packages/domain)保持无 IO,迁移成本主要在 adapters 与 server。