snowflow

今日宜吃 / today food 的架构设计

Wed, 08 Jul 2026 00:00:00 GMT

今日宜吃 / today food 是我做的一个小项目：基于黄历的 AI 开运菜单生成器，每天给你一签、一菜、一份干饭宜忌，搭配幸运三件套（口味/颜色/方位）。小程序竖屏布局，所有内容当日固定，凌晨 0 点按北京时间切换。

这篇复盘它的架构设计。

整体架构

┌─────────────┐   /api/*   ┌─────────────┐
│  frontend   │ ─────────▶ │  backend    │
│  (Vue 3)    │            │  (FastAPI)  │
└─────────────┘            └──────┬──────┘
       │                          │ 内嵌
       │                          ▼
       │                  ┌─────────────┐
       │                  │ admin 模块  │
       │                  │ (router/db) │
       │                  └─────────────┘
       │                          │
       │                          ▼
       │                  ┌─────────────┐
       └─────────────────▶│   SQLite    │
                          └─────────────┘

前端纯静态，后端跑 FastAPI，两者通过 /api/* 通信。后端内嵌了 admin 管理模块，共享同一个数据库。

Monorepo 组织

仓库是 monorepo，包含三个工程：

目录	技术栈	说明
`frontend/`	Vue 3 + Vite	用户侧 H5 应用（食历 / 择食 / 关于）
`backend/`	FastAPI + openai-agents	业务 API + AI 接入 + 后台管理（内嵌）
`admin/`	FastAPI + 单文件 HTML	后台管理界面（可独立部署）

之所以放一起而不是拆三个仓库，是因为这三个工程耦合很紧：admin 和 backend 共享数据库 schema，frontend 的 API 契约直接对 backend。拆开反而增加同步成本。

前端几个关键决策

API 前缀统一为 `/api`

// frontend/src/config.js
const API_BASE = import.meta.env.VITE_API_BASE || '/api'
export const API = {
  TODAY: `${API_BASE}/fortune/today`,
  DRAW: `${API_BASE}/fortune/draw`,
}

开发环境由 Vite 代理 /api 到后端，生产环境由 nginx 反代。前后端前缀一致，切换环境零改动。

摇签动画的最小时长

AI 调用耗时不确定，但用户体验上摇签动画不能"一调就停"或"卡死等"。所以设了一个最小时长：

export const DRAW_MIN_DURATION = 2500

不管走不走 AI 调用，摇签动画至少持续 2.5 秒；若 AI 调用耗时更长，则摇动状态一直保持到后端返回。这是个很小的细节，但对体验影响很大。

后端为什么用 openai-agents

一开始后端就是普通的 FastAPI + 直接调 OpenAI SDK。后来迁到 openai-agents，主要图两点：

Agent 抽象：菜单生成涉及多步推理（看黄历 → 定宜忌 → 选食材 → 组菜谱），用 Agent 比手写 prompt 拼装清晰
工具调用规范：Agent 框架对 function calling 的生命周期管理更稳

部署

后端用 systemd 常驻，监听 9081 端口；前端 vite build 出静态文件，nginx 托管并反代 /api。这个组合在 VPS 上零成本、足够稳。

小结

这个项目体量不大，但把"前端静态 + 后端 API + AI 接入 + 后台管理"这套常见组合走了一遍。monorepo 组织、API 前缀统一、动画最小时长这些细节，都是小决策但经得起复用。

四款 Agent 编程工具使用心得：Codex / Claude Code / Trae Work / ZCode

Mon, 06 Jul 2026 00:00:00 GMT

2026 年这波 agentic coding 浪潮，终端 agent 和 AI IDE 两派都在狂奔。我把手上能用的几款都过了一遍：OpenAI 的 Codex、Anthropic 的 Claude Code、字节的 Trae Work、智谱的 ZCode。这篇记一下各自的脾性和适合的场景。

为什么放在一起比

这四款有个共同点：都是 agentic 工具，不是"IDE 里塞个聊天框"那种补全插件。它们能读目录、改代码、跑命令、看结果再迭代，区别在于形态和取舍：

工具	厂商	形态	底层模型
Codex	OpenAI	终端 CLI（开源，Rust）	GPT 系
Claude Code	Anthropic	终端 CLI	Claude 系
Trae Work	字节跳动	AI IDE 的 Work 模式	多模型
ZCode	智谱	桌面可视化 Agent	GLM-5.2

下面逐个说。

Codex：终端原教旨主义者的选择

OpenAI 出的终端 coding agent，开源、Rust 写的，跑在命令行里。

用着最舒服的地方是它和终端工作流无缝——我在项目目录里敲一行需求，它自己读文件、改代码、跑测试、看报错再修。整个过程透明，每一步都能看到在干什么，想接管随时可以打断。开源这点也很加分，能看清楚它到底对代码做了什么。

不太适应的地方：纯 CLI 对不熟悉终端的人门槛偏高，没有可视化，长任务跑到一半想回看上下文得翻终端历史。另外它对项目结构的理解有时候会比较"直"，复杂重构容易钻牛角尖。

适合：终端重度用户、喜欢掌控每一步、开源党。

Claude Code：推理和长任务的强项

Anthropic 的终端 agent，形态上和 Codex 类似，都是 CLI。

最深的印象是推理质量。同样一个需求，Claude Code 经常能先想清楚再动手，尤其在涉及多文件改动、需要理解业务上下文的任务上，它规划的步骤明显更合理。长任务（比如跨模块重构）它扛跑能力很强，不容易中途跑偏。

短板：和 Codex 一样是纯终端，可视化和易用性不如 IDE 派。另外它对工具链的覆盖面我觉得没有 Codex 那么广，跑一些偏门命令偶尔要自己兜。

适合：复杂任务多、看重推理质量、愿意在终端里干活的人。

Trae Work：中文场景和 IDE 派的代表

字节跳动的 Trae IDE 里有个 Work 模式（原来叫 Solo），是国内 AI 原生 IDE 里我最常用的一款。

最大的优势是中文场景。需求用中文写、文档中文、报错解读中文，整个交互链路对中文开发者友好得不行，这点是前面两个国外工具比不了的。IDE 形态降低了门槛，不用记命令，左边文件树右边编辑器，可视化 diff，改了什么一目了然。多模型协同也是个亮点，不同任务能切不同模型。

需要注意的地方：因为是 IDE 形态，相比纯 CLI 的 agent，"轻量"不起来，开一个项目就得开整个 IDE。复杂 agentic 任务上，它的自主性和 Codex/Claude Code 那种纯 agent 还是有差距，更像"强化的 IDE 助手"而非"放手让它干"的 agent。

适合：中文开发场景、IDE 重度用户、团队协作、不想折腾终端的人。

ZCode：自研内核的国产 agentic 新选手

智谱的 ZCode，3.0 之后全面切了自研 Agent 内核，深度适配 GLM-5.2，定位是"GLM-5.2 的 agentic 开发环境"。

和 Codex、Claude Code 是同层面的 agentic 工具，不是补全插件。但它走了条不一样的路：用桌面可视化解决终端 agent 操作门槛高的问题。命令行 agent 那一套（读改跑看）它都有，但套了层友好的 GUI，不用盯着黑框框。

实际用下来的亮点是国产模型 agentic 能力的成熟度。GLM-5.2 配自研内核，在常见 coding 任务上已经能打，而且因为模型和 agent 内核同源，配合比"第三方内核套第三方模型"更紧。免费这点对个人开发者也很实在。

不足：生态和沉淀还比不上前面几家，社区教程、踩坑文档偏少，遇到边界情况得自己摸索。可视化界面在追求效率的老手看来，有时反而比 CLI 多几步操作。

适合：想要 agentic 能力但嫌 CLI 难用、想用国产模型、个人开发者。

怎么选

没有银弹，看你卡在哪条短板上：

终端重度 + 想要掌控感 → Codex
任务复杂、看重推理 → Claude Code
中文场景 + IDE 工作流 + 团队 → Trae Work
想要 agentic 又嫌 CLI 难用 + 国产模型 → ZCode

我自己的实际用法是混着来：日常小改和中文项目用 Trae Work，复杂重构和长任务交给 Claude Code，想看 agent 透明执行过程时用 Codex，ZCode 用来体验国产 agentic 的进展。工具是手的延伸，多几只手不亏。

一点感受

这一轮 agent 工具的核心进步，不是模型变聪明了多少，而是 agent 内核这件事独立出来了——读改跑看的循环、工具调用、上下文管理，这些从模型里拆出来做成专门的工程。Codex 开源、ZCode 自研内核，都说明大家意识到：光有好模型不够，得有好的 agent 工程把模型的能力稳定释放出来。

这对开发者是好事：模型层卷模型，agent 层卷工程，我们坐收渔利。