三周、三个 Agent、一个读书工具——一个 PM 的架构决策实录

一位产品经理用三周做出 8500 行代码的 AI 读书助手 Read-Box，复盘发现最大的收获不是代码，而是那些”选 A 还是选 B”的架构决策瞬间——并主张 AI 时代的产品经理必须读懂这些技术权衡。

基本信息

来源类型：文章（人人都是产品经理）
原文位置：raw/articles/2026-07-09-135914-tg-1e5fd9.md
原文 URL：https://www.woshipm.com/pd/6427117.html
作者：王耑（微信公众号：职场产品人）
消化日期：2026-07-09

核心观点

三个 Agent 用共享存储层协作，而不是链式调用或事件总线：读书助手拆成提炼 Agent、问答 Agent、陪练 Agent。三者不直接互相调用，而是都读写同一个 SQLite 数据库，互不感知对方存在。判断标准很朴素——“加需求时要不要改已有的代码”。后来加陪练 Agent 时问答 Agent 完全不受影响，加高亮模块时改动量极小，验证了这个选择是对的。
LLM Provider 抽象层是”不可商议”的宪法原则：需求从一开始就要求支持多模型（DeepSeek、Ollama 等用户可配置）。若三个 Agent 各写一套 API 调用，换模型要改三处、错误处理复制三遍。解法是所有 AI 调用必须经过统一 Provider 接口，核心就一句 async def chat(messages: list[dict]) -> str。三个 Agent 只跟抽象基类打交道，加新模型只需写一个新类 + 工厂方法加一行。
配置方案迭代三次才跑通，根因是”存储位置和读取时机不一致”：v1 从环境变量读（用户体验差）；v2 前端存 SQLite 但 Agent 仍从环境变量读（配了等于没配）；v3 路由层在请求时从数据库读配置、创建 Provider 后注入 Agent 才成功。启示：用户配置这个”小功能”涉及”存哪里、什么时候读、谁负责读”三个问题，很多小功能做不好是因为这三点没想清楚。
Spec Kit 规格驱动开发：宪法 + 写规格是最花时间也最有价值的步骤：项目定了 5 条宪法原则（含”LLM Provider 抽象层不可商议""核心逻辑测试优先 pytest 80% 覆盖”），v1.0 写了 5 个 Spec。写规格把”我以为想清楚了”的地方揪出来，此时发现问题的修复成本远低于写代码时。同时保持灵活：v1.1 首页 CSS 优化直接写代码，不走完整五步——流程是工具不是教条。
打包 Python 后端进桌面应用是最大的技术难点，“坑”占了 30-40% 的项目时间：不是 AI Agent 也不是架构，而是用 PyInstaller 把 Python 打成 exe，经历 4 次方案变更。关键教训：--onefile 看着整洁但解压到临时目录后 sys.path 路径不对，--onedir 路径问题少得多。功能性需求约占 60%，其余全是环境、配置、打包、兼容性问题——排期必须给非功能性事项留 buffer。

实操内容保留

代码/配置

统一的 LLM Provider 接口（宪法级不可商议原则）：

async def chat(messages: list[dict]) -> str

Provider 结构（抽象基类 + 具体实现，加模型只加一个类 + 工厂方法一行）：

LLMProvider（抽象基类）
├── OpenAIProvider（兼容 DeepSeek 等）
├── ClaudeProvider（预留）
└── OllamaProvider（预留）

四层架构：

前端展示层：Vue 3 + Tauri 桌面壳
  ↓ HTTP / SSE
API 路由层：FastAPI（接收请求 → 调度 Agent）
  ↓
Agent 层：提炼 Agent / 问答 Agent / 陪练 Agent
  ↓
存储层：SQLite（书籍数据 / Agent 产出 / 用户配置）

配置最终方案（v3）的数据流：

用户配置 → SQLite app_config 表
  ↓
路由层读取数据库 → 创建 ProviderConfig → 调用 create_provider() → 注入 Agent
  ↓
Agent 调用 provider.chat() —— 不关心配置来源

pnpm 11 构建失败报错与真实观测：

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.25.12

（试过 .npmrc、package.json 配置无效，最终在 pnpm-workspace.yaml 里找到正确解法。）

Prompt 模板

提炼 Agent 的 Prompt 三版演进（最有用的改进是明确写”不要做什么”）：

初版：“给我总结这章。” → 结果太长、结构随意第二版：加 system prompt 约束长度和风格。“200-500 字，保留核心观点，不要写’本章介绍了’这类冗余开头。” 最终版：要求 LLM 输出 JSON 格式便于解析入库；高亮内容在 prompt 中前置加权。

操作步骤

Spec Kit 规格驱动开发五步流程 + v1.0 的 5 个 Spec：

宪法（5 条核心原则，如”LLM Provider 抽象层不可商议""核心逻辑测试优先 pytest 80% 覆盖”）
写规格（每个功能写 Spec：需求描述 → 验收标准 → 数据模型）
→ 后续实现。v1.0 的 5 个 Spec：项目脚手架、书籍解析引擎、AI 提炼 Agent、问答 Agent、陪练 Agent

CORS 配置三次迭代（教训：开发阶段怎么简单怎么来，生产再收紧）：

allow_origins=["*"] + allow_credentials=True → 部分浏览器报错
显式列出所有端口 → 端口一换就崩
allow_origins=["*"] 不加 credentials → 开发阶段够用

关键概念

Read-Box — 本文复盘的桌面端 AI 读书助手（三 Agent + 四层架构）
Spec Kit — 本文采用的规格驱动开发工具（宪法 → 规格 → 实现五步流程）
LLM Provider 抽象层 — 本文”不可商议”的宪法原则，统一 AI 调用接口
多Agent架构 — 三个 Agent 用共享存储层协作，是”以数据交换代替直接调用”的具体案例
AI产品经理 — 本文核心主张：PM 应理解架构决策背后的 trade-off
提炼 Agent / 问答 Agent / 陪练 Agent — Read-Box 的三个协作角色
PyInstaller 打包 — 桌面应用最大技术难点（—onefile vs —onedir）

与其他素材的关联

与本地化AI阅读助手的关系：两者都是”AI 读书助手”主题的实现，但形态不同——本地化AI阅读助手是 Trae IDE + Skill 的双层偏好建模个性化阅读方案，Read-Box 是 Vue+Tauri+FastAPI 的桌面 App，核心在三 Agent 协作架构与工程决策。可互为对照。
与 2026-06-17-ai-agent-工程完全指南的关系：都讨论多 Agent 拆分。工程完全指南给出”以上下文为中心拆分、避免分布式单体”的原则，本文用 Read-Box 的”共享存储层让 Agent 互不感知”提供了一个具体落地案例，判断标准都归到”加需求要改几处代码”。
与 2026-06-17-ai-knowledge-base-product-design 的关系：都是产品经理从个人痛点出发跑通 0→1 的实战复盘，都强调”行动大于完美""技术选型看约束而非先进”。
与 2026-07-01-woshipm-multi-agent-coding-pipeline 的关系：都讲多智能体协作，但侧重不同——流水线一文强调子智能体不得自行召唤、文件交接协议；本文强调用共享存储层解耦，让每个 Agent 可独立开发测试部署。

原文精彩摘录

对 PM 来说，判断架构好坏的标准不是”多先进”，而是”加需求时要不要改已有的代码。”

判断”什么东西该抽象”的标准很简单：问自己”这个东西未来会不会变？变了需要改几处？“如果一个变化要改多处，那就该抽出来。

整个项目最大的技术难点不是 AI Agent，不是架构设计，而是——把 Python 后端打包进桌面应用。……如果你想知道这些”坑”占了多少时间——大概占了项目总时间的 30-40%。

“你不会被 AI 取代，你会被更会用 AI 的人取代。“但我想补一句——“会用 AI”不是指会用 ChatGPT 写周报，而是能理解 AI 应用是怎么搭起来的，知道架构决策背后的 trade-off。

个人知识库

探索

2026-07-09-woshipm-pm-architecture-decisions-read-box