摘要

我用 Codex 开发 Agent 完成了一个名为“博士猫”的 AI 个人知识库 MVP。它可以导入 PDF、EPUB、Markdown 和 Word 文档，进行中文全文与语义混合检索，再让用户自行配置的大模型基于检索证据回答问题。回答中的重要观点必须带有真实引用，证据不足时系统会拒绝作答。最后，项目被封装成了普通用户可以安装和双击运行的 macOS 应用。

这次经历让我认识到，开发 Agent 的价值并不只是“帮我写代码”，而是帮助一个人把模糊构想逐步转化为产品边界、技术方案、测试标准和可以交付的应用。但前提是，人不能只给它一句“帮我做个软件”，然后等待一个完美结果。

真正有效的人机协作，需要目标拆解、阶段确认、技术质疑、真实环境验收，以及对 Agent 输出保持判断力。这篇文章记录我在整个开发过程中的方法、踩坑和反思。

Codex、开发 Agent、AI 编程、个人知识库、RAG、FastAPI、React、PyInstaller、产品开发

---

一、我为什么想做“博士猫”

博士猫最初只是一个已经完成视觉设计的知识型 IP。它戴着眼镜、穿着类似研究者的服装，定位与读书、知识和成长有关。

我当时产生了一个想法：

能不能让用户把读过的书和写过的笔记放进一个知识库，然后像和 AI 对话一样与博士猫交流？博士猫的回答不是来自泛泛的互联网知识，而是优先来自用户真正读过的内容。

如果只是“上传 PDF 后聊天”，这个想法并不新鲜。但我真正关心的是另外几个问题：

• AI 能不能告诉我答案来自哪本书、哪一段？
• 它能不能区分作者原文、跨资料归纳和自己的推断？
• 如果我的判断有问题，它能不能提出质疑，而不是一直顺着我说？
• 如果知识库里根本没有答案，它能不能坦率地说不知道？
• 讨论结束后，能不能进一步形成一个可执行、可复盘的小行动？

所以，这个产品要解决的并不是“生成更多答案”，而是：

找回知识 → 连接观点 → 核对证据 → 形成判断 → 推动行动 → 复盘结果

这也是我和 Codex 的第一次重要讨论：先确认产品到底在解决什么问题，而不是马上开始写代码。

---

二、我一开始对开发 Agent 的误解

在真正使用 Codex 之前，我对开发 Agent 的想象比较接近：

我描述一个产品，它自动把产品做完。

实际使用后，我发现这种理解既高估了 Agent，也低估了 Agent。

说高估，是因为一句模糊需求不可能直接产生一个边界清楚、体验合理、数据安全、可以交付的产品。Agent 可以快速写出大量代码，但它不知道我真正看重什么，也不知道哪些取舍对我更重要。

说低估，是因为如果把它当成一个长期协作的开发伙伴，而不是一次性的代码生成器，它能够完成的工作远远超过“补全函数”：

• 阅读和理解已有项目；
• 与我讨论产品边界；
• 编写产品和技术设计；
• 拆分开发阶段；
• 修改前后端代码；
• 运行测试和构建；
• 读取日志并追踪故障根因；
• 封装桌面应用；
• 整理安装说明和开发文档；
• 在连续多轮对话中保持项目上下文。

我后来形成了一个更准确的认识：

Codex 不是一个“许愿机”，而是一个能够读项目、动手实现、运行验证并持续协作的开发 Agent。

人仍然要负责产品目标、价值判断和最终验收。

---

三、最有效的一步：先讨论产品，不要急着写代码

整个开发过程中，最有价值的一步不是某段代码，而是最开始对产品进行第一性原理拆解。

我们先讨论了一个可信回答需要满足什么条件，最后得到四层判断：

1. 找得到：相关资料必须进入候选结果。
2. 找得准：排在前面的片段必须真正回答问题。
3. 引得对：引用必须指向真实原文位置。
4. 说得住：结论不能超过证据可以支持的范围。

这个拆解直接改变了技术优先级。

如果目标只是做一个“看起来像 AI”的产品，我可能会先开发漂亮的聊天界面。但在明确“结论与证据关系”才是核心后，开发顺序变成了：

资料导入
→ 解析预览
→ 用户确认
→ 全文与语义检索
→ 引用式回答
→ 本地验证
→ 行动与复盘

这给我一个很深的体会：

开发 Agent 写代码很快，因此更需要在写代码前确定什么值得写。否则，它只会更快地把错误方向做得更完整。

---

四、把模糊想法拆成可验收的 MVP

我没有让 Codex 一次性实现所有构想，而是先明确 MVP 的功能边界。

第一版必须完成：

• 导入文本型 PDF、EPUB、Markdown 和 DOCX；
• 预览解析结果，确认后才进入正式知识库；
• 中文全文检索与本地语义检索；
• 检索结果融合和重排；
• 基于证据的结构化回答；
• 点击引用查看原文位置；
• 没有证据时拒绝作答；
• 支持 OpenAI、DeepSeek、Qwen 和兼容中转接口；
• 保存最小行动或反思卡片；
• 最终封装成普通用户可以安装的 macOS 应用。

同时明确不做：

• 扫描 PDF 的 OCR；
• 微信读书、Notion 等自动同步；
• 手机端和跨设备同步；
• 多用户、社区和付费系统；
• 自动知识图谱；
• 复杂多 Agent 辩论；
• 大量博士猫动画和角色表演。

这一步非常重要。开发 Agent 的执行能力越强，越容易出现“顺便再做一点”的范围膨胀。明确不做什么，可以减少无效开发，也方便每个阶段验收。

我的经验是，每一个功能都要能回答三个问题：

1. 为什么 MVP 现在就需要它？
2. 完成以后怎样验证？
3. 如果先不做，会不会破坏核心闭环？

如果第三个问题的答案是否定的，它通常就可以延后。

---

五、Codex 实际完成了什么

最后实现的博士猫并不是一个演示页面，而是一个具备完整本地闭环的应用。

1. 文档导入与解析

系统支持：

• 文本型 PDF；
• EPUB；
• Markdown；
• Word .docx。

导入时会计算文件哈希，避免完全重复的资料。文件解析后不会直接进入知识库，而是先让用户查看预览。确认后，系统才为资料建立全文和向量索引。

这一设计看起来多了一步，但它体现了产品的知识边界：没有经过用户确认的解析结果，不应该自动成为可信知识。

2. 混合检索

当前检索由几部分组成：

• Jieba 中文分词；
• SQLite FTS5 全文检索；
• 本地确定性向量检索；
• Reciprocal Rank Fusion 排名融合；
• 词项重叠轻量重排；
• 资料类型和文档过滤；
• 来源位置保留。

这里有一个很实际的产品设计：单独做了“检索实验室”。

用户可以先不调用大模型，只看博士猫到底找到了哪些片段。如果证据本身就不对，就应该优化检索，而不是把希望寄托在更贵的大模型上。

3. 引用式对话

对话流程不是把整个文件交给模型，而是：

问题
→ 本地检索
→ 选择少量证据片段
→ 调用用户配置的模型
→ 返回结构化回答
→ 本地验证引用
→ 前端展示

每个重要观点都需要引用本次证据包中的真实片段 ID。前端展示的书名、页码、行号和原文来自本地数据库，不允许模型自行编写。

如果知识库没有召回证据，系统不会调用云端模型，而是直接回答：当前知识库不足以支持这个回答。

4. 多模型接口

开发中加入了设置页面，用户可以自己填写：

• API Key；
• Base URL；
• 模型名称；
• Responses 或 Chat Completions 协议；
• json_schema 或 json_object 模式。

因此，博士猫不绑定某一家模型平台。OpenAI、DeepSeek、Qwen 以及多数兼容接口都可以根据平台能力配置。

5. 本地数据和桌面应用

用户的原始资料、数据库、索引、对话和设置默认保存在自己的 macOS 上。调用第三方模型时，只发送当前问题和回答所需的少量证据片段。

最终，Codex 还把项目封装成了 Apple Silicon macOS 应用。用户下载 DMG、拖入“应用程序”后即可双击打开，不需要安装 Python、Node.js 或 pnpm。

这一步让我第一次真正感觉到：项目从“代码”变成了“产品”。

---

六、真正困难的并不是让 Agent 写出代码

回顾整个过程，写功能代码反而不是最困难的部分。真正耗费时间的是那些只有在真实环境中才会出现的问题：

• 配置保存了，却没有真正生效；
• OpenAI 兼容接口并不完全兼容；
• JSON 返回了，但结构不符合引用要求；
• 开发模式可以启动，普通用户不会启动；
• 测试目录可以运行，从 Finder 双击却失败；
• 应用提示查看日志，但日志文件是空的；
• 第二次启动成功，第一次启动却超时；
• 打包应用时可能意外包含开发机的配置或数据。

这些问题让我看到开发 Agent 的另一种价值：它不仅能生成代码，还能执行命令、读取日志、建立假设、编写回归测试并追踪根因。

但这也有一个前提：我不能只对它说“还是打不开，你再改一下”。更有效的要求是：

先不要修改。先解释为什么会出现这个现象，收集证据，判断当前方案是否真的能奏效，再开始修复。

当我开始这样要求后，排障质量明显提高。

---

七、几个最有代表性的踩坑

1. .env、.env.example 和设置页面互相打架

早期配置模型主要依靠 .env，但项目里同时有 .env.example。两个文件内容相似，用户很容易混淆：到底应该修改哪一个？设置页面保存以后，是不是会写回 .env？运行中的模型到底使用了哪个值？

最后我们把职责重新分开：

• .env.example 只是可公开提交的字段模板；
• .env 只用于源码开发中的私密配置；
• 桌面版设置写入用户目录中的本地设置文件；
• 设置页同时显示“已保存配置”和“当前实际生效配置”；
• 如果环境变量覆盖了设置，会明确列出覆盖字段。

这件事给我的启发是：

“保存成功”不是一个充分的产品状态，用户真正需要知道的是“现在到底用的是什么”。

2. 设置保存成功，但模型必须重启才生效

最初，回答模型 Provider 在服务启动时创建一次。设置页面虽然把新配置写进文件，但对话仍然使用内存中的旧 Provider。

解决方法不是简单提示用户重启，而是实现一个线程安全的 Provider Manager：

• 每次回答读取当前 Provider；
• 设置保存后重新创建 Provider；
• 原子替换运行中的 Provider；
• 新请求立即使用新配置；
• 正在进行的请求不被中途破坏。

这个问题让我认识到，运行时配置包含两层：

持久化状态 + 内存中的实际运行状态

只修改其中一层，功能就不算完成。

3. “OpenAI 兼容”并不等于真的完全兼容

我一度以为，只要一个平台声称兼容 OpenAI，填写 Key、地址和模型名就可以使用。实际情况复杂得多。

有的平台支持 Chat Completions，但不支持 Responses；有的平台支持 JSON Object，但拒绝 JSON Schema；有的平台 /models 可以访问，真正回答时仍返回错误。

最后系统把能力拆成两层：

API Style: responses / chat_completions_json
JSON Mode: schema / json_object

并且只在服务端明确表示不支持 Schema 时降级一次。鉴权失败、模型不存在、限流和超时不会被误判为协议问题。

这让我明白：

接口兼容不能只看文档名称，而要验证鉴权、模型、协议和结构化输出的完整链路。

4. 为了兼容 JSON，不能牺牲引用安全

部分平台能够返回 JSON，但字段结构并不符合博士猫的回答契约。最简单的兼容方法，是让本地程序猜测字段，甚至把第一段证据自动补成引用。

但这样会直接破坏产品最核心的可信边界。

最终方案是允许模型进行一次“只修复结构、不能新增事实”的修复调用。修复后仍然不合法，就安全拒绝。程序绝不猜测引用。

这是我很认可的一次取舍：

兼容更多平台不是最高目标，保持产品可信才是。

5. 开发者能启动，不代表用户能使用

早期项目的启动方式是进入项目目录，运行开发脚本，再访问本地网页。这对于开发者没有问题，但对于普通用户，安装 Python、Node.js、pnpm，理解前后端和端口，已经足以劝退大多数人。

我明确提出：这不能算一个可以交付的 MVP。

后来 Codex 使用以下方案完成桌面封装：

• React 构建为生产静态资源；
• FastAPI 同时提供 API 和前端文件；
• Uvicorn 在随机本地端口启动；
• pywebview 创建原生窗口；
• PyInstaller 打包 Python、依赖和资源；
• hdiutil 生成 DMG。

这让我形成一个新的产品标准：

对非技术用户来说，“可以启动”不是文档中的一条命令，而是双击应用。

6. 日志文件存在，但一个字都没有

第一次测试桌面应用时，界面提示“博士猫启动失败，请查看日志”，但日志文件大小是 0。

Codex 追踪后发现，问题不是没有调用日志，而是多个框架会重新配置 Python 日志：basicConfig 可能因为根日志已经初始化而不生效，Alembic 的 fileConfig 还会默认禁用已有日志器。

最终修复包括：

• 为桌面应用安装独立文件 Handler；
• 程序化迁移时禁止 Alembic 重置全局日志；
• 保留 Uvicorn 与应用日志；
• 记录启动、迁移、随机端口、就绪、退出和异常。

这件事说明：

GUI 应用没有可见终端，日志不是“以后再加”的功能，而是产品能否排障的基础设施。

7. 从终端启动成功，从 Finder 双击却失败

这是整个开发中让我印象最深的一个问题。

测试时，应用从项目目录或临时目录启动都成功。但复制到“应用程序”后，从 Finder 双击却出现启动超时。

日志完善以后，终于看到真正异常：程序尝试在系统根目录创建 /user-data，而根目录是只读的。

根因是 Finder 启动应用时，当前工作目录可能是 /。Alembic 迁移脚本又额外加载了默认配置，将相对路径 ./user-data 解析成 /user-data。

最终解决方案是：

• 迁移只使用桌面启动器传入的数据库地址；
• 移除迁移对默认 Settings 和当前工作目录的依赖；
• 增加只读工作目录回归测试；
• 最后真的从 /Applications、以 / 为工作目录启动验收。

如果只做单元测试或一直从终端运行，这个问题可能永远不会出现。

它让我牢牢记住：

真实环境验收不能被模拟测试完全替代。

---

八、我与 CodeX 的具体协作方式

经过这个项目，我逐步形成了一套比较稳定的协作方式。

1. 先让它复述和拆解，不要直接实现

面对新功能，我会先问：

• 这个想法的核心用户价值是什么？
• 用第一性原理怎样拆？
• 最小可行范围是什么？
• 可能遇到哪些问题？
• 有哪些不同实现方案？

只有方向确认后，才让它写设计文档和实施计划。

2. 大任务按阶段确认

我会把开发拆成连续阶段，每完成一段就测试和确认，例如：

资料入库
→ 检索
→ 对话
→ 多模型设置
→ 卡片
→ UI
→ 桌面封装

阶段确认的好处是，一旦方向偏了，调整成本还很低。

3. 要求它先思考故障原因

遇到问题时，我不会马上接受第一个修复建议，而是要求：

修改之前先判断这种方法能否奏效，是否可能带来其他问题，并先找到根因。

这会迫使排障从“试试看”变成“证据驱动”。

4. 要求真实验证，不接受“应该可以”

我特别关注 codex 是否真的运行了：

• 自动化测试；
• Lint；
• 生产构建；
• dmg 挂载；
• 安装目录启动；
• 随机端口健康检查；
• 应用退出和端口释放；
• 安装包敏感文件扫描。

只有真实输出能够证明状态。代码看起来正确，不代表产品真的可以使用。

5. 让它记录项目状态

开发中我曾暂停，再继续。为了衔接，我要求 CodeX 记住当前进度、已完成内容、待处理问题和下一步。

长周期项目中，上下文管理与写代码同样重要。设计文档、实施计划、问题复盘和测试结果，就是人与 Agent 共同的长期记忆。

---

九、哪些事情不能完全交给 Agent

虽然 CodeX 承担了大量开发工作，但以下事情仍然需要我决定。

1. 产品到底为什么存在

Agent 可以帮助拆解，但无法替我决定“博士猫最重要的价值是什么”。如果我只追求功能数量，它也可以继续增加动画、知识图谱、同步和社交功能，但这些不一定对当前产品有价值。

2. 哪些体验算合格

“运行一个脚本后访问本地网页”在工程上是成功的，但我认为对普通用户不合格。把它封装成可安装 App，是产品判断，而不是单纯技术判断。

3. 风险和边界是否可以接受

例如：

• 是否允许系统猜测引用？
• 是否为了兼容接口而放松结构要求？
• 是否把用户资料发送到第三方？
• 是否允许未确认的 AI 内容进入长期知识库？

这些取舍不能只由 Agent 根据“更容易实现”来决定。

4. 真实使用后的主观判断

检索结果是否有用、博士猫的质疑是否合理、行动卡是否真的推动改变，需要真实用户使用后判断。自动化测试不能完全替代产品体验。

我的理解是：

人负责方向、价值、取舍和最终判断；Agent 负责实现、分析、验证和保持工程一致性。

---

十、从“代码能运行”到“产品能交付”

这个项目让我重新理解了“完成”的含义。

在开发阶段，“完成”可能意味着接口返回 200、页面能打开、测试通过。但在产品阶段，还要继续问：

• 用户需要安装开发环境吗？
• 第一次打开会发生什么？
• 配置填错时能看懂错误吗？
• 数据保存在哪里？
• 删除应用会不会误删资料？
• 安装包里有没有开发者的 key 和数据库？
• 出现故障时有没有日志？
• 更新应用会不会丢数据？
• 系统支持哪些 mac？
• 未签名应用如何首次打开？

Codex 最终不仅生成了 .app 和 .dmg，还完成了安装包扫描、独立用户目录启动、DMG 挂载、架构检查、应用关闭和端口释放验证。

最终修复版的自动化验证包括：

• 121 项服务端测试通过；
• 13 项 Web 测试通过；
• Python 静态检查通过；
• TypeScript 编译与 Vite 生产构建通过；
• PyInstaller 构建通过；
• DMG 和真实安装位置启动通过。

这让我看到，一个开发 Agent 真正有价值的交付不是“我改了这些文件”，而是：

我修改了什么、为什么修改，以及用什么证据证明它现在可以工作。

---

十一、我总结的十条 CodeX 开发经验

1. 先定义问题，再定义功能

不要从“我要一个聊天页面”开始，而要从“用户为什么需要它”开始。

2. 先写 MVP 边界，再让 Agent 开发

同时写清楚“必须做”和“明确不做”，防止范围膨胀。

3. 让 agent 提供多个方案和取舍

不要只问“怎么实现”，还要问“还有什么方案，风险分别是什么”。

4. 大项目采用阶段验收

每完成一个闭环就运行和体验，不要等所有功能都写完才第一次打开。

5. 故障修复前先找根因

要求收集日志、进程、端口、文件状态和真实错误，不要连续试错式修改。

6. 不接受没有证据的完成声明

测试、构建、真实启动和用户操作，分别证明不同层次的正确性。

7. 用真实运行环境验收

从终端运行成功，不代表从 Finder、安装目录或另一台电脑也成功。

8. 把隐私和安全写进验收标准

尤其是 AI 和本地知识库产品，要检查安装包、日志、API 响应和第三方传输范围。

9. 允许技术方案在验证后变化

早期计划并不是承诺。博士猫从考虑 LanceDB、Tauri 等方案，最终收敛为 SQLite 向量表和 pywebview，是为了更快验证核心闭环。

10. 让文档成为长期记忆

设计、实施计划、问题根因、安装说明和开发文档，可以让下一次开发不必重新理解整个项目。

---

十二、我现在会怎样向 Codex 提需求

如果重新开始一个类似项目，我不会只说：

帮我做一个 AI 个人知识库。

我会这样描述：

先不要写代码。

请从第一性原理分析这个产品真正解决什么问题，给出两到三个方案，
明确 MVP 必须做什么、不做什么、最大风险是什么，以及每个阶段如何验收。

我最看重的是：
1. 回答必须基于用户自己的资料；
2. 引用可以回到原文；
3. 证据不足时拒答；
4. 普通用户最终能够安装和双击使用；
5. 任何完成结论都必须有测试或真实运行证据。

方案确认后再写设计文档和实施计划，然后分阶段开发。

遇到故障时，我会这样要求：

先不要修改代码。

请先复现问题，读取日志和运行状态，解释可能的数据流，定位根因，
说明当前修复方案为什么会奏效，以及它可能带来的副作用。

然后先写能够复现问题的测试，再实施最小修复，最后运行完整验证。

这种提问方式的本质不是使用某种“神奇提示词”，而是把成熟的软件开发方法带入与 Agent 的协作中。

---

十三、这次开发也让我看到 Agent 的局限

开发 Agent 很强，但它并不会自动保证以下事情：

• 一开始就理解真正的产品目标；
• 永远选择最合适的技术方案；
• 自动知道哪些视觉和功能没有必要；
• 在没有要求时完成真实环境测试；
• 替用户承担 API 服务商、隐私和发布合规责任；
• 判断产品是否真的有人愿意长期使用。

它也可能：

• 根据早期方案过度设计；
• 把局部测试通过误认为产品完成；
• 为了兼容而放松关键约束；
• 在修改一个问题时引入新的配置或生命周期问题；
• 给出技术上成立、但普通用户无法操作的交付方式。

所以，与 Agent 协作不是放弃思考，而是提高了思考的杠杆。

如果人没有清楚的目标，Agent 会把模糊放大；如果人能够持续判断、验证和取舍，Agent 会把执行能力放大。

---

十四、结语：Agent 改变的不是写代码速度，而是个人实现产品的能力

“博士猫 AI 个人知识库”从一个关于 IP 和阅读的想法，最终变成了一个可以安装、导入资料、检索、引用、对话和复盘的本地应用。

这次开发当然提高了写代码的速度，但对我影响更大的，是它降低了一个人把复杂想法变成产品的门槛。

过去，一个人需要同时掌握产品设计、前端、后端、数据库、检索、模型接口、测试、打包和文档，才能完成类似项目。现在，Codex 可以承担其中大量实现与验证工作，而人把更多精力放在：

• 这个产品是否值得做；
• 它真正解决了什么问题；
• 哪些原则不能妥协；
• 什么才算完成；
• 用户是否真的能用起来。

所以，我现在不会把开发 Agent 理解成“自动写代码的工具”。

我更愿意把它理解为：

一个能够持续阅读项目、执行任务、运行验证、帮助排障的技术协作者。

但最终，产品方向仍然来自人，验收标准仍然由人提出，价值仍然要由真实用户证明。

这可能就是我在 Codex 开发 Agent 中得到的最重要经验：

不要把思考外包给 Agent，而要用 Agent 放大自己的思考和行动能力。

---

附：博士猫 MVP

博士猫api接口文档
https://my.feishu.cn/wiki/Qri9wNaXrihnCBkeP80cMVaGnxd

博士猫安装与使用说明
https://my.feishu.cn/wiki/HTT0wFI0bifCSakJwXYcdTaenhe?from=from_copylink

博士猫个人ai知识库开发完整文档
https://my.feishu.cn/wiki/ADiZwoGFpiF04XktcU5crQF9nYc