Archon 一键 Web UIarchon serve的设计调研与源码实现解析【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本文以仓库调研文档 .claude/PRPs/issues/issue-978.mdIssue #978ENHANCEMENT 类调研为骨架围绕“一条命令安装并启动 Web UI”这一目标完整梳理问题背景、关键设计决策、7 步实施计划并结合当前仓库源码逐项核对落地现状。读完你可以掌握archon serve的完整调用链从 CLI 命令分发、Web UI 下载与校验、原子解压到startServer()库化重构与 Release CI 打包发布并了解每处设计背后的安全与健壮性考量。一、问题背景为什么需要一个archon serve命令调研文档给出的问题陈述非常明确编译后的 Archon CLI 二进制只打包了packages/cli/src/cli.ts一个入口既不包含 server也不包含 Web UI更没有archon serve命令。想要使用 Web UI 的用户必须克隆整个 monorepo安装 Bun 运行时执行bun install一次性安装约 2274 个依赖包再执行bun dev启动开发服务器。也就是说Web UI 是产品中“最容易被发现”的部分却恰好位于“安装摩擦最大”的路径上。对只想快速体验的用户而言克隆、装依赖、跑开发服务器这一整套动作显然不是理想路径。调研文档对这项改动给出的评估结论如下MetricValueReasoningPriorityMEDIUM用户价值高消除了克隆 构建的摩擦但现有 Docker 路径和克隆路径可用不阻塞其他工作ComplexityHIGH涉及 CLI、server、CI、构建脚本等 8 个文件server 重构是难点——main()约 600 行且没有可复用的库 APIConfidenceHIGH代码库分析清晰所有集成点均已映射下载/解压路径无未知项server 重构范围可控目标体验是brew install archon archon serve一步到位。实现思路则是延迟拉取lazy-fetch首次执行archon serve时从 GitHub Releases 下载预构建的 Web UI tarball 并缓存。这样 CLI 二进制对纯命令行用户保持小巧同时 Web UI 用户获得一条命令的安装体验。二、关键设计决策Server 作为库还是嵌入式迷你服务器调研文档指出当时 server 的现状是packages/server/src/index.ts是一个 721 行的脚本核心是一个庞大的main()函数文档记录其在 129-718 行没有导出startServer()无法作为库被 import。文档因此对比了两个方案Option A完整 server 重构——把main()抽取为导出的startServer(opts)函数让archon/server成为archon/cli的依赖把完整 server 编译进二进制。二进制体积从约 50MB 增长到约 65MB所有平台适配器Slack、Telegram、GitHub、Discord都会被编译进去。Option B最小嵌入式 server——在packages/cli/src/commands/serve.ts里新建一个轻量 Hono server只注册 API 路由 静态文件服务不包含平台适配器二进制体积更接近当前水平。核心构件复用packages/server/src/routes/api.ts中已导出的registerApiRoutes()。调研结论推荐 Option A完整重构理由如下Option B 会重复 server 初始化逻辑并随时间推移与主 server 产生分叉平台适配器只有在对应环境变量存在时才会被实例化全部是条件判断见packages/server/src/index.ts中 296-459 行附近的适配器初始化区块——未配置时零成本二进制体积增加约 15MB 可以接受用户获得的是完整 server 体验而不是功能子集。从当前源码看这个决策已经被执行packages/server/src/index.ts第 221-231 行定义了导出的ServerOptions接口第 233 行就是export async function startServer(opts: ServerOptions {})第 1092 行有if (import.meta.main)守卫保证脚本模式仍然可用。后续章节会逐项核对。三、受影响文件与集成点全景调研文档用一张表圈定了改动范围文件动作说明packages/cli/src/commands/serve.ts新建archon serve命令下载 web-dist、启动 serverpackages/cli/src/cli.ts修改将serve加入noGitCommands新增case serve分发packages/cli/package.json修改新增archon/server、archon/adapters依赖packages/server/src/index.ts修改把main()抽取为导出的startServer(opts)packages/server/src/index.ts修改接受webDistPath参数替代从import.meta.dir计算.github/workflows/release.yml修改新增 Web UI 构建 tarball 上传步骤scripts/build-binaries.sh无改动bun build --compile会自动跟随 import无需显式处理packages/paths/src/archon-paths.ts修改新增getWebDistDir(version)路径助手测试新建覆盖下载、校验、解压、CLI 启动 server文档同时标注了五个关键集成点便于后续实施时精确落点packages/cli/src/cli.ts在 dotenv 初始化后集中 import 所有命令packages/server/src/routes/api.ts导出的registerApiRoutes(app, webAdapter, lockManager)是 server 唯一可复用的构件当前源码中位于该文件 1589 行packages/paths/src/bundled-build.ts提供BUNDLED_VERSION用于构造 Release 下载 URLpackages/paths/src/archon-paths.ts提供getArchonHome()作为缓存根目录packages/server/src/index.ts中webDistPath的解析逻辑文档记录在 581-593 行需要参数化。四、七步实施计划详解含当前源码落地状态Step 1从 server 的main()抽取startServer(opts)这是整个方案中“最硬”的一步。文档给出了重构前后的关键代码形态重构前简化async function main(): Promisevoid { // 600 行初始化、适配器创建、路由注册、Bun.serve() } main().catch(error { ... process.exit(1); });重构后export interface ServerOptions { /** Override the web dist path (for CLI binary with downloaded web-dist) */ webDistPath?: string; /** Override the port */ port?: number; /** Skip platform adapter initialization (CLI serve mode) */ skipPlatformAdapters?: boolean; } export async function startServer(opts: ServerOptions {}): Promisevoid { // Move entire main() body here // Replace webDistPath computation with: opts.webDistPath ?? 默认值 // Replace port with: opts.port ?? getPort() // Wrap platform adapter blocks with: if (!opts.skipPlatformAdapters) { ... } } // Keep backward compat: script entry point still works if (import.meta.main) { startServer().catch(error { ... process.exit(1); }); }这一步的成败关键在于import.meta.main守卫它保证packages/server/src/index.ts在被当作脚本直接运行时bun dev场景行为不变同时让startServer可以被其他模块以库的方式 import。对照当前源码重构已经完成ServerOptions接口带完整的 JSDoc 注释webDistPath仅在生产模式生效、port取值范围 1-65535、skipPlatformAdapters用于 web-only 模式startServer()是正式导出且第 1092 行的import.meta.main守卫保留了脚本入口。静态文件服务也按文档设想参数化了——packages/server/src/index.ts864-873 行附近使用opts.webDistPath ?? getSourceWebDistDir()通过hono/bun的serveStatic提供/assets/*、/favicon.png与 SPA fallbackapp.get(*, ...)返回index.html。Step 2新增getWebDistDir()路径助手文档设计的路径缓存规则是版本键控的~/.archon/web-dist/version/。对应函数/** * Returns the path to the cached web UI distribution for a given version. * Example: ~/.archon/web-dist/v0.3.2/ */ export function getWebDistDir(version: string): string { return join(getArchonHome(), web-dist, version); }当前源码中该函数已落地于 packages/paths/src/archon-paths.ts与文档示例几乎逐字一致。值得注意两点它复用了getArchonHome()同文件 145 行因此自动继承ARCHON_HOME环境变量覆盖、~展开、Docker 环境/.archon等既有路径语义保持与整个项目一致的目录模型同文件还新增了配套的getSourceWebDistDir()495-497 行返回packages/web/dist源码构建产物目录供开发模式使用——这是落地过程中对文档方案的补充源码检出环境直接使用本地构建产物而不是去下载一个不存在的dev版本 Release。Step 3创建archon serve命令文档给出了命令的完整骨架核心逻辑是判断是否为编译二进制 → 检查缓存 → 下载校验 → 启动 server。落地后的 serve.ts 在文档设计的基础上做了多处强化下面结合源码逐段拆解。命令主流程serveCommand47-104 行export async function serveCommand(opts: ServeOptions): Promisenumber { if ( opts.port ! undefined (!Number.isInteger(opts.port) || opts.port 1 || opts.port 65535) ) { console.error(Error: --port must be an integer between 1 and 65535, got: ${opts.port}); return 1; } // 源码检出使用本地构建产物而不是下载 if (!BUNDLED_IS_BINARY) { ... } const version BUNDLED_VERSION; const webDistDir getWebDistDir(version); if (!existsSync(webDistDir)) { await downloadWebDist(version, webDistDir); // 失败则返回 1 } else { log.info({ webDistDir }, web_dist.cache_hit); } if (opts.downloadOnly) { ... return 0; } return startServerUntilSignal(webDistDir, opts.port); }其中几个关键设计点开发模式拒绝下载BUNDLED_IS_BINARY为 false 时源码检出命令改用getSourceWebDistDir()指向本地packages/web/dist若该目录不存在会提示先执行bun run build:web。--download-only在开发模式下直接报错——源码检出“无物可下载”。这避免了文档“Edge Cases”一节预判的“二进制 v0.3.2 但 Release 不存在”类问题在 dev 环境发生。动态 import 保持 CLI 启动速度startServerUntilSignal内部使用await import(archon/server)延迟加载 server 模块正是文档“Risks”表中“archon/serverimport 增加 CLI 启动时间”的缓解手段——其他命令不受影响。前台运行 信号等待Bun.serve()本身会让事件循环保持活跃但 CLI 的process.exit(exitCode)会把它杀掉所以命令在 server 启动后挂起一个只在SIGINT/SIGTERM时 resolve 的 Promise确保 server 持续运行直到操作者主动中断。下载与校验downloadWebDist139-358 行const tarballUrl https://github.com/${GITHUB_REPO}/releases/download/v${version}/archon-web.tar.gz; const checksumsUrl https://github.com/${GITHUB_REPO}/releases/download/v${version}/checksums.txt;文档设计为“先下载 checksums.txt再解析archon-web.tar.gz的期望哈希然后下载 tarball 并校验”。落地实现在此基础上做了安全升级——校验源双轨制首选构建期嵌入的哈希BUNDLED_WEB_DIST_SHA256。该常量定义于 packages/paths/src/bundled-build.ts编译二进制前由scripts/build-binaries.sh写入真实哈希、构建结束后通过 EXIT trap 恢复占位值。这是独立的信任锚点独立于 Release 内容本身比“从同一来源下载校验文件再校验下载内容”的强度更高兜底远程 checksums.txt。当内嵌哈希为空如旧二进制或 dev 构建时并行下载 checksums.txt 与 tarball再通过parseChecksum()392-404 行兼容sha256sum的hash filename与hash filename两种格式解析期望哈希。无论哪种来源最终都用Bun.CryptoHasher(sha256)对下载内容计算实际哈希并做严格比对不一致即抛出Checksum mismatch错误——这正是文档强调的“防止供应链攻击”。原子解压211-358 行是落地实现中健壮性最强的部分对文档“tmp 目录 原子 rename”的方案做了显著细化先清理{targetDir}.tmp残留解压到临时目录最后renameSync(tmpDir, targetDir)原子落位——并发archon serve时不会出现半成品目录tarball 先落盘再喂给 tarBun.write(tarballPath, ...)stdin: Bun.file(tarballPath)文档原方案是把字节直接作为tar的 stdin但 Windows 上这种“父进程持有管道并持续泵送”的方式可能无界阻塞源码注释引用 #2924改为文件描述符继承后父进程不再拥有需要维护的通道60 秒超时兜底EXTRACTION_TIMEOUT_MS 60_00026 行父进程自持定时器超时则proc.kill()并区分“自己的超时”与“被外部信号杀死”两种失败原因给出不同的诊断信息stderr 边读边等proc.exited与new Response(proc.stderr).text()并行等待避免 tar 写满 stderr 管道造成双向死锁解压布局校验解压后检查index.html是否存在防止“解压成功但内容不对”全程通过web_dist.*系列结构化日志分阶段打点download_started→checksum_resolved→tarball_verified→archive_staged→extract_spawned→extract_process_exited→installed每个阶段携带独立durationMs便于排查卡点。Windows 下的 tar 选择resolveTarBin372-381 行是落地时发现的平台坑Windows 自带System32\tar.exebsdtar接受盘符操作数而 Git for Windows 会把 GNU tar无法处理-C C:\Users\...放进 PATH——同一台机器上 cmd 解压成功、Git Bash 解压失败。因此实现将平台与探测函数注入化便于在非 Windows CI 上覆盖两个分支Windows 上优先使用系统自带 tar。Step 4把serve接入 CLI 命令分发文档为 packages/cli/src/cli.ts 规划了五处修改逐一核对当前源码导入命令在命令文件头部 importserveCommand加入noGitCommands当前源码 298-310 行的noGitCommands数组已包含serve——这意味着archon serve不需要在 git 仓库内执行与version、setup、chat等同属“无需 git 校验”的命令新增case serve分发解析--port字符串转数字与--download-only透传给serveCommandparseArgs选项注册port: { type: string }与download-only: { type: boolean, default: false }帮助文案printUsage中补充serve用法默认端口为 3090。Step 5把archon/server加入 CLI 依赖文档要求在packages/cli/package.json的dependencies中加入archon/server: workspace:*, archon/adapters: workspace:*理由CLI 需要 importarchon/server的startServerarchon/adapters虽是archon/server的传递依赖但显式声明更稳妥。使用workspace:*协议则与 monorepo 内其他包间的依赖方式保持一致。Step 6Release CI 构建并发布 Web UI tarball文档规划了在.github/workflows/release.yml中新增“构建 Web UI → 打包 → 生成 checksums → 随 Release 发布”的步骤。当前工作流已实现且打包命令做了确定性处理.github/workflows/release.yml 38-48 行tar --sortname --owner0 --group0 --numeric-owner --mtime0 \ -czf dist/archon-web.tar.gz -C packages/web/dist .--sortname消除文件系统顺序差异、--mtime0钳制时间戳、--owner/--group/--numeric-owner归零身份信息——保证从源码独立重建也能产出字节级一致、SHA-256 相同的归档。这正是 Step 3 中“内嵌校验哈希”可信的前提如果每次构建产物哈希漂移嵌入的期望值就没有意义。产物流转如下web-distjob 打包后经actions/upload-artifactv4上传为archon-web-dist工件buildjob 下载该工件最终 Release 步骤发布dist/archon-*、dist/archon-web.tar.gz与dist/checksums.txt283-284 行生成 checksums305-306 行列入发布清单后者覆盖全部产物。Step 7测试覆盖文档规划了packages/cli/src/commands/serve.test.ts列出 8 组测试用例覆盖非二进制开发模式下拒绝执行并返回退出码 1web-dist 未缓存时触发下载并解压到正确路径已缓存时跳过下载验证零 fetch 调用校验和不匹配时失败且不留.tmp残留网络失败时给出可操作的错误信息--download-only只下载不启动 serverparseChecksum对已知格式的提取与缺失文件名抛错。当前仓库中 serve.test.ts 已存在与实现同目录遵循 CLI 包“实现 同名测试”的组织惯例。五、边界情况与风险清单调研文档给出的风险与缓解措施表是理解这套设计取舍的最佳入口风险/边界情况缓解措施Server 重构破坏bun devimport.meta.main守卫保留脚本模式两条路径都要测试二进制体积膨胀server 并入监控当前约 50MB预期约 65MB为价值可接受tarball 解压失败权限、磁盘空间原子解压.tmp→ rename失败清理清晰错误信息GitHub Release 限流fetch返回 403——暴露错误并建议重试离线/内网环境--download-only允许预缓存后续可扩展--web-dist path离线路径版本不匹配二进制 v0.3.2 但 Release 尚不存在报 “release not found”——仅当有人用错误版本从源码构建时发生系统无tarmacOS/Linux 均自带Windows 用 Bun 内置 tar 或decompress首次下载时并发执行archon serve原子 rename 防止损坏第二个进程看到完整目录或重试archon/serverimport 增加 CLI 启动时间仅 serve 命令内动态await import()——其他命令不受影响对照源码表中多项已进一步落地加固Windows 的tar问题通过resolveTarBin精确定位而非笼统的“Bun 内置 tar”解压卡死通过 60 秒父进程定时器终结下载/解压全程有分阶段日志用于事后定位#2924 的经验沉淀内嵌 SHA-256 则把“离线环境校验可信度”提升到了独立信任锚点的级别。六、验证与回归策略文档规划了两层验证均可直接复用自动化检查bun run type-check bun run test bun run lint bun run validate # 提交前完整校验手动验证清单bun run dev——server 仍可正常启动脚本模式保留VERSIONtest scripts/build-binaries.sh构建二进制——确认可编译运行二进制archon serve——验证下载 解压 server 启动archon serve --download-only——验证只下载不启动再次运行archon serve——验证命中缓存无重复下载archon workflow list——验证无 server 依赖带来的启动时间回归archon serve --port 4000——验证端口覆盖生效。七、范围边界文档明确划定了改动边界避免方案蔓延IN SCOPEserver 库化重构抽取startServer()archon serve命令下载 校验 解压--port与--download-only标志Release CI 构建发布archon-web.tar.gzweb-dist 缓存路径助手下载/解压/校验逻辑测试。OUT OF SCOPE明确不碰bun dev开发工作流对贡献者保持不变Docker 镜像正交、不受影响CDN 镜像GitHub Releases 已够用--web-versionlatest推迟到未来 issue--offline --web-dist./path可后续补充Homebrew formula 变更只改文档即可缓存 web-dist 的自动更新版本键控目录天然解决废弃“克隆 bun dev”路径保留给贡献者平台适配器懒加载优化适配器本就由环境变量条件实例化。八、实施顺序严格依赖链文档强调各步骤存在严格依赖关系这是并行开发时必须遵守的顺序Step 2路径助手——无依赖可最先做Step 1server 重构——最难部分尽早做Step 5CLI 依赖声明——Step 3 的前置条件Step 3serve 命令——依赖 Step 1、2、5Step 4CLI 接线——依赖 Step 3Step 7测试——依赖 Step 3、4Step 6CI 变更——独立可与 3-7 并行。结语从调研文档到落地的闭环回看整份调研文档与当前仓库源码archon serve的路线图已经完整走通调研先行评估优先级/复杂度/置信度→明确设计决策Option A 完整重构→圈定文件范围8 文件与 5 个集成点→分步实施7 步带严格依赖链→风险预判9 项边界与缓解→双轨验证自动化 手动清单。而源码现状显示计划中的每一步都已落地并且在落地过程中针对 Windows 平台差异bsdtar vs GNU tar、下载卡死60 秒超时 分阶段日志、校验可信度构建期内嵌 SHA-256等真实问题做了超出原方案的加固。对想要深入研究的读者推荐按如下路径阅读源码先看 packages/cli/src/commands/serve.ts 掌握命令全貌再读 packages/server/src/index.ts 的ServerOptions/startServer理解库化接口接着看 packages/paths/src/archon-paths.ts 的路径模型与 packages/paths/src/bundled-build.ts 的构建期常量最后对照 .github/workflows/release.yml 的确定性打包理解“可复现产物 → 可信校验”的完整链路。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Archon 一键 Web UIarchon serve的设计调研与源码实现解析【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本文以仓库调研文档 .claude/PRPs/issues/issue-978.mdIssue #978ENHANCEMENT 类调研为骨架围绕“一条命令安装并启动 Web UI”这一目标完整梳理问题背景、关键设计决策、7 步实施计划并结合当前仓库源码逐项核对落地现状。读完你可以掌握archon serve的完整调用链从 CLI 命令分发、Web UI 下载与校验、原子解压到startServer()库化重构与 Release CI 打包发布并了解每处设计背后的安全与健壮性考量。一、问题背景为什么需要一个archon serve命令调研文档给出的问题陈述非常明确编译后的 Archon CLI 二进制只打包了packages/cli/src/cli.ts一个入口既不包含 server也不包含 Web UI更没有archon serve命令。想要使用 Web UI 的用户必须克隆整个 monorepo安装 Bun 运行时执行bun install一次性安装约 2274 个依赖包再执行bun dev启动开发服务器。也就是说Web UI 是产品中“最容易被发现”的部分却恰好位于“安装摩擦最大”的路径上。对只想快速体验的用户而言克隆、装依赖、跑开发服务器这一整套动作显然不是理想路径。调研文档对这项改动给出的评估结论如下MetricValueReasoningPriorityMEDIUM用户价值高消除了克隆 构建的摩擦但现有 Docker 路径和克隆路径可用不阻塞其他工作ComplexityHIGH涉及 CLI、server、CI、构建脚本等 8 个文件server 重构是难点——main()约 600 行且没有可复用的库 APIConfidenceHIGH代码库分析清晰所有集成点均已映射下载/解压路径无未知项server 重构范围可控目标体验是brew install archon archon serve一步到位。实现思路则是延迟拉取lazy-fetch首次执行archon serve时从 GitHub Releases 下载预构建的 Web UI tarball 并缓存。这样 CLI 二进制对纯命令行用户保持小巧同时 Web UI 用户获得一条命令的安装体验。二、关键设计决策Server 作为库还是嵌入式迷你服务器调研文档指出当时 server 的现状是packages/server/src/index.ts是一个 721 行的脚本核心是一个庞大的main()函数文档记录其在 129-718 行没有导出startServer()无法作为库被 import。文档因此对比了两个方案Option A完整 server 重构——把main()抽取为导出的startServer(opts)函数让archon/server成为archon/cli的依赖把完整 server 编译进二进制。二进制体积从约 50MB 增长到约 65MB所有平台适配器Slack、Telegram、GitHub、Discord都会被编译进去。Option B最小嵌入式 server——在packages/cli/src/commands/serve.ts里新建一个轻量 Hono server只注册 API 路由 静态文件服务不包含平台适配器二进制体积更接近当前水平。核心构件复用packages/server/src/routes/api.ts中已导出的registerApiRoutes()。调研结论推荐 Option A完整重构理由如下Option B 会重复 server 初始化逻辑并随时间推移与主 server 产生分叉平台适配器只有在对应环境变量存在时才会被实例化全部是条件判断见packages/server/src/index.ts中 296-459 行附近的适配器初始化区块——未配置时零成本二进制体积增加约 15MB 可以接受用户获得的是完整 server 体验而不是功能子集。从当前源码看这个决策已经被执行packages/server/src/index.ts第 221-231 行定义了导出的ServerOptions接口第 233 行就是export async function startServer(opts: ServerOptions {})第 1092 行有if (import.meta.main)守卫保证脚本模式仍然可用。后续章节会逐项核对。三、受影响文件与集成点全景调研文档用一张表圈定了改动范围文件动作说明packages/cli/src/commands/serve.ts新建archon serve命令下载 web-dist、启动 serverpackages/cli/src/cli.ts修改将serve加入noGitCommands新增case serve分发packages/cli/package.json修改新增archon/server、archon/adapters依赖packages/server/src/index.ts修改把main()抽取为导出的startServer(opts)packages/server/src/index.ts修改接受webDistPath参数替代从import.meta.dir计算.github/workflows/release.yml修改新增 Web UI 构建 tarball 上传步骤scripts/build-binaries.sh无改动bun build --compile会自动跟随 import无需显式处理packages/paths/src/archon-paths.ts修改新增getWebDistDir(version)路径助手测试新建覆盖下载、校验、解压、CLI 启动 server文档同时标注了五个关键集成点便于后续实施时精确落点packages/cli/src/cli.ts在 dotenv 初始化后集中 import 所有命令packages/server/src/routes/api.ts导出的registerApiRoutes(app, webAdapter, lockManager)是 server 唯一可复用的构件当前源码中位于该文件 1589 行packages/paths/src/bundled-build.ts提供BUNDLED_VERSION用于构造 Release 下载 URLpackages/paths/src/archon-paths.ts提供getArchonHome()作为缓存根目录packages/server/src/index.ts中webDistPath的解析逻辑文档记录在 581-593 行需要参数化。四、七步实施计划详解含当前源码落地状态Step 1从 server 的main()抽取startServer(opts)这是整个方案中“最硬”的一步。文档给出了重构前后的关键代码形态重构前简化async function main(): Promisevoid { // 600 行初始化、适配器创建、路由注册、Bun.serve() } main().catch(error { ... process.exit(1); });重构后export interface ServerOptions { /** Override the web dist path (for CLI binary with downloaded web-dist) */ webDistPath?: string; /** Override the port */ port?: number; /** Skip platform adapter initialization (CLI serve mode) */ skipPlatformAdapters?: boolean; } export async function startServer(opts: ServerOptions {}): Promisevoid { // Move entire main() body here // Replace webDistPath computation with: opts.webDistPath ?? 默认值 // Replace port with: opts.port ?? getPort() // Wrap platform adapter blocks with: if (!opts.skipPlatformAdapters) { ... } } // Keep backward compat: script entry point still works if (import.meta.main) { startServer().catch(error { ... process.exit(1); }); }这一步的成败关键在于import.meta.main守卫它保证packages/server/src/index.ts在被当作脚本直接运行时bun dev场景行为不变同时让startServer可以被其他模块以库的方式 import。对照当前源码重构已经完成ServerOptions接口带完整的 JSDoc 注释webDistPath仅在生产模式生效、port取值范围 1-65535、skipPlatformAdapters用于 web-only 模式startServer()是正式导出且第 1092 行的import.meta.main守卫保留了脚本入口。静态文件服务也按文档设想参数化了——packages/server/src/index.ts864-873 行附近使用opts.webDistPath ?? getSourceWebDistDir()通过hono/bun的serveStatic提供/assets/*、/favicon.png与 SPA fallbackapp.get(*, ...)返回index.html。Step 2新增getWebDistDir()路径助手文档设计的路径缓存规则是版本键控的~/.archon/web-dist/version/。对应函数/** * Returns the path to the cached web UI distribution for a given version. * Example: ~/.archon/web-dist/v0.3.2/ */ export function getWebDistDir(version: string): string { return join(getArchonHome(), web-dist, version); }当前源码中该函数已落地于 packages/paths/src/archon-paths.ts与文档示例几乎逐字一致。值得注意两点它复用了getArchonHome()同文件 145 行因此自动继承ARCHON_HOME环境变量覆盖、~展开、Docker 环境/.archon等既有路径语义保持与整个项目一致的目录模型同文件还新增了配套的getSourceWebDistDir()495-497 行返回packages/web/dist源码构建产物目录供开发模式使用——这是落地过程中对文档方案的补充源码检出环境直接使用本地构建产物而不是去下载一个不存在的dev版本 Release。Step 3创建archon serve命令文档给出了命令的完整骨架核心逻辑是判断是否为编译二进制 → 检查缓存 → 下载校验 → 启动 server。落地后的 serve.ts 在文档设计的基础上做了多处强化下面结合源码逐段拆解。命令主流程serveCommand47-104 行export async function serveCommand(opts: ServeOptions): Promisenumber { if ( opts.port ! undefined (!Number.isInteger(opts.port) || opts.port 1 || opts.port 65535) ) { console.error(Error: --port must be an integer between 1 and 65535, got: ${opts.port}); return 1; } // 源码检出使用本地构建产物而不是下载 if (!BUNDLED_IS_BINARY) { ... } const version BUNDLED_VERSION; const webDistDir getWebDistDir(version); if (!existsSync(webDistDir)) { await downloadWebDist(version, webDistDir); // 失败则返回 1 } else { log.info({ webDistDir }, web_dist.cache_hit); } if (opts.downloadOnly) { ... return 0; } return startServerUntilSignal(webDistDir, opts.port); }其中几个关键设计点开发模式拒绝下载BUNDLED_IS_BINARY为 false 时源码检出命令改用getSourceWebDistDir()指向本地packages/web/dist若该目录不存在会提示先执行bun run build:web。--download-only在开发模式下直接报错——源码检出“无物可下载”。这避免了文档“Edge Cases”一节预判的“二进制 v0.3.2 但 Release 不存在”类问题在 dev 环境发生。动态 import 保持 CLI 启动速度startServerUntilSignal内部使用await import(archon/server)延迟加载 server 模块正是文档“Risks”表中“archon/serverimport 增加 CLI 启动时间”的缓解手段——其他命令不受影响。前台运行 信号等待Bun.serve()本身会让事件循环保持活跃但 CLI 的process.exit(exitCode)会把它杀掉所以命令在 server 启动后挂起一个只在SIGINT/SIGTERM时 resolve 的 Promise确保 server 持续运行直到操作者主动中断。下载与校验downloadWebDist139-358 行const tarballUrl https://github.com/${GITHUB_REPO}/releases/download/v${version}/archon-web.tar.gz; const checksumsUrl https://github.com/${GITHUB_REPO}/releases/download/v${version}/checksums.txt;文档设计为“先下载 checksums.txt再解析archon-web.tar.gz的期望哈希然后下载 tarball 并校验”。落地实现在此基础上做了安全升级——校验源双轨制首选构建期嵌入的哈希BUNDLED_WEB_DIST_SHA256。该常量定义于 packages/paths/src/bundled-build.ts编译二进制前由scripts/build-binaries.sh写入真实哈希、构建结束后通过 EXIT trap 恢复占位值。这是独立的信任锚点独立于 Release 内容本身比“从同一来源下载校验文件再校验下载内容”的强度更高兜底远程 checksums.txt。当内嵌哈希为空如旧二进制或 dev 构建时并行下载 checksums.txt 与 tarball再通过parseChecksum()392-404 行兼容sha256sum的hash filename与hash filename两种格式解析期望哈希。无论哪种来源最终都用Bun.CryptoHasher(sha256)对下载内容计算实际哈希并做严格比对不一致即抛出Checksum mismatch错误——这正是文档强调的“防止供应链攻击”。原子解压211-358 行是落地实现中健壮性最强的部分对文档“tmp 目录 原子 rename”的方案做了显著细化先清理{targetDir}.tmp残留解压到临时目录最后renameSync(tmpDir, targetDir)原子落位——并发archon serve时不会出现半成品目录tarball 先落盘再喂给 tarBun.write(tarballPath, ...)stdin: Bun.file(tarballPath)文档原方案是把字节直接作为tar的 stdin但 Windows 上这种“父进程持有管道并持续泵送”的方式可能无界阻塞源码注释引用 #2924改为文件描述符继承后父进程不再拥有需要维护的通道60 秒超时兜底EXTRACTION_TIMEOUT_MS 60_00026 行父进程自持定时器超时则proc.kill()并区分“自己的超时”与“被外部信号杀死”两种失败原因给出不同的诊断信息stderr 边读边等proc.exited与new Response(proc.stderr).text()并行等待避免 tar 写满 stderr 管道造成双向死锁解压布局校验解压后检查index.html是否存在防止“解压成功但内容不对”全程通过web_dist.*系列结构化日志分阶段打点download_started→checksum_resolved→tarball_verified→archive_staged→extract_spawned→extract_process_exited→installed每个阶段携带独立durationMs便于排查卡点。Windows 下的 tar 选择resolveTarBin372-381 行是落地时发现的平台坑Windows 自带System32\tar.exebsdtar接受盘符操作数而 Git for Windows 会把 GNU tar无法处理-C C:\Users\...放进 PATH——同一台机器上 cmd 解压成功、Git Bash 解压失败。因此实现将平台与探测函数注入化便于在非 Windows CI 上覆盖两个分支Windows 上优先使用系统自带 tar。Step 4把serve接入 CLI 命令分发文档为 packages/cli/src/cli.ts 规划了五处修改逐一核对当前源码导入命令在命令文件头部 importserveCommand加入noGitCommands当前源码 298-310 行的noGitCommands数组已包含serve——这意味着archon serve不需要在 git 仓库内执行与version、setup、chat等同属“无需 git 校验”的命令新增case serve分发解析--port字符串转数字与--download-only透传给serveCommandparseArgs选项注册port: { type: string }与download-only: { type: boolean, default: false }帮助文案printUsage中补充serve用法默认端口为 3090。Step 5把archon/server加入 CLI 依赖文档要求在packages/cli/package.json的dependencies中加入archon/server: workspace:*, archon/adapters: workspace:*理由CLI 需要 importarchon/server的startServerarchon/adapters虽是archon/server的传递依赖但显式声明更稳妥。使用workspace:*协议则与 monorepo 内其他包间的依赖方式保持一致。Step 6Release CI 构建并发布 Web UI tarball文档规划了在.github/workflows/release.yml中新增“构建 Web UI → 打包 → 生成 checksums → 随 Release 发布”的步骤。当前工作流已实现且打包命令做了确定性处理.github/workflows/release.yml 38-48 行tar --sortname --owner0 --group0 --numeric-owner --mtime0 \ -czf dist/archon-web.tar.gz -C packages/web/dist .--sortname消除文件系统顺序差异、--mtime0钳制时间戳、--owner/--group/--numeric-owner归零身份信息——保证从源码独立重建也能产出字节级一致、SHA-256 相同的归档。这正是 Step 3 中“内嵌校验哈希”可信的前提如果每次构建产物哈希漂移嵌入的期望值就没有意义。产物流转如下web-distjob 打包后经actions/upload-artifactv4上传为archon-web-dist工件buildjob 下载该工件最终 Release 步骤发布dist/archon-*、dist/archon-web.tar.gz与dist/checksums.txt283-284 行生成 checksums305-306 行列入发布清单后者覆盖全部产物。Step 7测试覆盖文档规划了packages/cli/src/commands/serve.test.ts列出 8 组测试用例覆盖非二进制开发模式下拒绝执行并返回退出码 1web-dist 未缓存时触发下载并解压到正确路径已缓存时跳过下载验证零 fetch 调用校验和不匹配时失败且不留.tmp残留网络失败时给出可操作的错误信息--download-only只下载不启动 serverparseChecksum对已知格式的提取与缺失文件名抛错。当前仓库中 serve.test.ts 已存在与实现同目录遵循 CLI 包“实现 同名测试”的组织惯例。五、边界情况与风险清单调研文档给出的风险与缓解措施表是理解这套设计取舍的最佳入口风险/边界情况缓解措施Server 重构破坏bun devimport.meta.main守卫保留脚本模式两条路径都要测试二进制体积膨胀server 并入监控当前约 50MB预期约 65MB为价值可接受tarball 解压失败权限、磁盘空间原子解压.tmp→ rename失败清理清晰错误信息GitHub Release 限流fetch返回 403——暴露错误并建议重试离线/内网环境--download-only允许预缓存后续可扩展--web-dist path离线路径版本不匹配二进制 v0.3.2 但 Release 尚不存在报 “release not found”——仅当有人用错误版本从源码构建时发生系统无tarmacOS/Linux 均自带Windows 用 Bun 内置 tar 或decompress首次下载时并发执行archon serve原子 rename 防止损坏第二个进程看到完整目录或重试archon/serverimport 增加 CLI 启动时间仅 serve 命令内动态await import()——其他命令不受影响对照源码表中多项已进一步落地加固Windows 的tar问题通过resolveTarBin精确定位而非笼统的“Bun 内置 tar”解压卡死通过 60 秒父进程定时器终结下载/解压全程有分阶段日志用于事后定位#2924 的经验沉淀内嵌 SHA-256 则把“离线环境校验可信度”提升到了独立信任锚点的级别。六、验证与回归策略文档规划了两层验证均可直接复用自动化检查bun run type-check bun run test bun run lint bun run validate # 提交前完整校验手动验证清单bun run dev——server 仍可正常启动脚本模式保留VERSIONtest scripts/build-binaries.sh构建二进制——确认可编译运行二进制archon serve——验证下载 解压 server 启动archon serve --download-only——验证只下载不启动再次运行archon serve——验证命中缓存无重复下载archon workflow list——验证无 server 依赖带来的启动时间回归archon serve --port 4000——验证端口覆盖生效。七、范围边界文档明确划定了改动边界避免方案蔓延IN SCOPEserver 库化重构抽取startServer()archon serve命令下载 校验 解压--port与--download-only标志Release CI 构建发布archon-web.tar.gzweb-dist 缓存路径助手下载/解压/校验逻辑测试。OUT OF SCOPE明确不碰bun dev开发工作流对贡献者保持不变Docker 镜像正交、不受影响CDN 镜像GitHub Releases 已够用--web-versionlatest推迟到未来 issue--offline --web-dist./path可后续补充Homebrew formula 变更只改文档即可缓存 web-dist 的自动更新版本键控目录天然解决废弃“克隆 bun dev”路径保留给贡献者平台适配器懒加载优化适配器本就由环境变量条件实例化。八、实施顺序严格依赖链文档强调各步骤存在严格依赖关系这是并行开发时必须遵守的顺序Step 2路径助手——无依赖可最先做Step 1server 重构——最难部分尽早做Step 5CLI 依赖声明——Step 3 的前置条件Step 3serve 命令——依赖 Step 1、2、5Step 4CLI 接线——依赖 Step 3Step 7测试——依赖 Step 3、4Step 6CI 变更——独立可与 3-7 并行。结语从调研文档到落地的闭环回看整份调研文档与当前仓库源码archon serve的路线图已经完整走通调研先行评估优先级/复杂度/置信度→明确设计决策Option A 完整重构→圈定文件范围8 文件与 5 个集成点→分步实施7 步带严格依赖链→风险预判9 项边界与缓解→双轨验证自动化 手动清单。而源码现状显示计划中的每一步都已落地并且在落地过程中针对 Windows 平台差异bsdtar vs GNU tar、下载卡死60 秒超时 分阶段日志、校验可信度构建期内嵌 SHA-256等真实问题做了超出原方案的加固。对想要深入研究的读者推荐按如下路径阅读源码先看 packages/cli/src/commands/serve.ts 掌握命令全貌再读 packages/server/src/index.ts 的ServerOptions/startServer理解库化接口接着看 packages/paths/src/archon-paths.ts 的路径模型与 packages/paths/src/bundled-build.ts 的构建期常量最后对照 .github/workflows/release.yml 的确定性打包理解“可复现产物 → 可信校验”的完整链路。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
