DiAL/openspec/changes/archive/2026-05-09-cleanup-project-artifacts/design.md

Context

当前项目根目录存在三项冗余：

1. index.ts — 仅包含 import "./src/server/dev.ts"，与 package.json 的 "start" 脚本功能完全重复，无任何其他文件或脚本引用它
2. "module": "src/server/dev.ts" — private: true 项目不会被发布，ESM 入口字段无消费者；且指向一个启动服务器的副作用文件本身就不合理
3. .build/ 目录 — 由 scripts/build.ts 在每次构建时生成，包含 server-entry.ts 和 static-assets.ts 两个中间文件。构建完成后这些文件残留在磁盘上，虽已被 .gitignore 忽略但不必要地占用空间

项目构建流程为：vite build → 生成 .build/ 中间文件 → Bun.build() 编译为单可执行文件 → 输出到 dist/gateway-checker。

Goals / Non-Goals

Goals:

• 移除无实际作用的文件和配置，减少项目结构噪音
• 构建成功后自动清理中间产物，保持项目目录整洁
• 构建失败时保留中间产物以便排查问题

Non-Goals:

• 不改变构建产物本身（输出路径、可执行文件行为不变）
• 不引入新的构建步骤或依赖
• 不调整 RuntimeMode 或开发/生产模式的区分逻辑

Decisions

Decision 1: 直接删除 index.ts

选择：删除文件 备选：保留但添加注释说明用途 理由：无任何脚本、文件或构建流程引用它，保留只会增加困惑。package.json 的 "start" 脚本已直接指向 src/server/dev.ts。

Decision 2: 移除 "module" 字段

选择：从 package.json 中删除 "module" 字段 备选：改为 "main" 字段 理由：private: true 意味着不会被 npm 发布，任何入口字段都没有消费者。改为 "main" 同样无意义，因为这不是一个库。完全移除最简洁。

Decision 3: 构建成功后清理 .build/

选择：在 Bun.build() 成功后调用 await rm(buildDir, { recursive: true, force: true }) 备选：

• 始终保留 .build/（当前行为）
• 使用临时目录（os.tmpdir()）

理由：build.ts 开头已导入 rm 且已在构建开始时执行清理，只需在成功路径末尾复用同一行代码。构建失败时 .build/ 自然保留，兼顾排查需求。不使用临时目录是因为 Bun.build() 的 import ... with { type: "file" } 需要相对路径引用 dist/web/ 下的实际文件，临时目录增加路径复杂度。

具体修改位置：scripts/build.ts 第 53 行 console.log(...) 之后。

Risks / Trade-offs

• [极低风险] 删除 index.ts 影响外部工具：如果 CI/CD 或其他自动化流程通过 bun index.ts 启动，会中断。→ 检查确认无此类用法。package.json 中 "start": "bun src/server/dev.ts" 是标准入口。
• [极低风险] 移除 module 字段影响 IDE 解析：某些 IDE 可能依赖 module 字段进行跳转。→ 实际指向 dev.ts，对代码导航无帮助。
• [低风险] 清理 .build/ 后无法排查偶现构建问题：→ 构建失败时 .build/ 保留，只有成功时才清理，排查路径完整。