DECISIONS.md

DECISIONS.md — 技术决策记录

最后更新：2026-07-03

---

决策模板

### DEC-00X：决策标题

- **日期**：YYYY-MM-DD
- **状态**：Proposed / Accepted / Rejected / Superseded
- **背景**：为什么需要做这个决策
- **方案对比**：
  | 方案 | 优点 | 缺点 |
  |---|---|---|
  | A | ... | ... |
  | B | ... | ... |
- **决策**：选择方案 X
- **理由**：...
- **影响**：...

---

已做决策

DEC-001: Executa Tool 使用 CommonJS 模块系统

• 日期：2026-07-03
• 状态：Accepted
• 背景：TypeScript 编译 ESM 模块时，import 语句不带 .js 扩展名，Node.js 运行时无法解析（ERR_MODULE_NOT_FOUND）。
• 方案对比：

  方案	优点	缺点
  CommonJS (module: "CommonJS")	Node.js 原生支持，无需扩展名	moduleResolution=node10 已被弃用
  ESM + .js 扩展名	现代标准	需要在所有 import 中加 .js，TS 体验差
  tsx / ts-node 直接运行	开发方便	不适合生产环境

• 决策：选择 CommonJS（module: "CommonJS", moduleResolution: "node10"）
• 理由：Executa Tool 是本地 Node.js 进程，不需要 ESM 的 tree-shaking 等特性。CommonJS 提供了最简单的模块解析体验。
• 影响：Executa 的 tsconfig 使用 node10 解析。未来 TypeScript 7.0 弃用 node10 时需迁移。

DEC-002: invoke 响应使用 dispatcher contract envelope

• 日期：2026-07-03
• 状态：Accepted
• 背景：Anna Executa 协议要求 invoke 响应使用 dispatcher contract 格式。
• 决策：采用 { success: true, data: { summary: "..." } } / { success: false, error: "..." } 格式
• 理由：与 Anna 平台 Python 模板一致，Harness 正确解析。
• 影响：前端在收到 tools.invoke 结果后需要检查 success 字段。

DEC-003: pnpm workspace monorepo

• 日期：2026-07-03
• 状态：Accepted
• 背景：前端 ui/ 和 Executa executas/* 需要独立构建。
• 决策：pnpm workspace，packages 指向 ui 和 executas/*
• 理由：一个 pnpm build 构建所有项目，依赖统一管理。

---

待决策事项

待定-1：Executa Tool 的 Binary 打包方案

• 优先级：🔴 高（阻塞阶段 6）
• 候选方案：

  方案	优点	缺点
  Node.js SEA	Node 官方方案，稳定	需要 Node 20+，产物体积大
  bun build --compile	产物体积小	bun 生态不够成熟
  pkg (Vercel)	成熟	已停止维护
  Go 重写	天然跨平台，单 binary，体积小	需要用两种语言

• 状态：待调研

待定-2：前端是否使用 UI 组件库

• 优先级：🟢 低
• 候选方案：不用组件库（纯手写 CSS）/ Tailwind CSS / 轻量组件库
• 倾向：Tailwind CSS（开发快，产物体积小，不影响 Anna App bundle）
• 状态：倾向 Tailwind，阶段 3 实施时确定

待定-3：pnpm workspace 还是 npm workspaces

• 优先级：🟢 低
• 倾向：pnpm（更快，磁盘效率高，题目示例也用 pnpm）
• 状态：已倾向于 pnpm