3.4 源码安装与 Poetry 工具链
3.4 源码安装与 Poetry 工具链
本节摘要：源码安装让你绕过发行包，直接在框架代码上运行与调试，代价是自担同步与升级负担。本节讲清哪三类需求才值得走这条路，演示从代码获取、依赖安装到源码启动的完整流程，并顺带把 Poetry 的核心用法讲到位。读完本节，你能判断自己是否需要这份"改装版"实验台，需要时能一次装好。
什么时候值得拆开机器
源码安装不是进阶仪式，而是一个需求驱动的选择。下面三类需求里，你命中了才值得走这条路：
第一类，调试框架本身。你怀疑记忆工具的行为与预期不符，想在框架源码里下断点，看请求在内部如何流转——发行包装出来的服务没法这么玩。第二类，参与共建。你想提交修复或扩展，或者想第一时间用上未发版的功能，源码是唯一的入口。第三类，锁定或改造版本。生产环境出于稳定考虑需要钉死某个版本并自维护补丁，源码加私有构建是标准做法。
如果你的需求只是"用框架做应用"，发行包完全够用，源码路线的维护负担（每次上游发版要手动同步）纯属白付。判断口诀：读源码的需求出现之前，不用装源码。
Poetry 是什么，为什么是它
Python 项目的依赖管理有段历史包袱，Poetry 是目前社区的主流解法之一：它用一个声明文件集中管理依赖与版本约束，自动创建与维护虚拟环境，并把"可复现安装"做成默认行为——同一份声明文件在任何机器上装出的依赖组合完全一致。Letta 项目本身用 Poetry 管理依赖，沿用同一工具意味着你的环境与项目作者的预期一致，省掉大量"在我机器上明明是好的"式扯皮。
对使用者而言，Poetry 的日常使用收敛为四个动作，本节全部会用到：初始化或克隆项目、安装全部依赖、在项目环境里执行命令、新增或移除依赖。它把 pip 加虚拟环境加依赖清单三件事合成了一件事，学习成本半小时，回报是长期的环境秩序。
源码安装四步走
完整流程四步，每步的意图都值得看清：
# 1. 获取代码：把仓库克隆到本地工作目录 git clone https://github.com/letta-ai/letta.git cd letta # 2. 安装全部依赖：Poetry 自动创建虚拟环境并按锁定文件精确安装 poetry install # 3. 环境变量照旧：源码运行与发行包运行读取同一套配置 export OPENAI_API_KEY="sk-..." export LETTA_PG_URI="postgresql+pg8000://letta:password@localhost:5432/letta" # 4. 以源码方式启动服务：入口与发行包一致 poetry run letta server
四步里最值得咀嚼的是第二步与第四步的配合。poetry install 依据锁定文件安装，保证你拿到的依赖组合正是项目当前版本验证过的组合——比手工 pip 安装再解决冲突可靠得多。poetry run 则把后续所有命令锚定在项目环境里执行，不污染系统，也不依赖你记得激活哪个虚拟环境。装完之后，验证方式依旧是那条老仪式：起服务、发请求、看响应。
源码环境的日常：改、跑、验
源码实验台的真正价值在使用它调试的时刻。一个典型的工作循环长这样：在源码里找到存疑的模块（比如记忆工具的执行逻辑），加上日志或断点；用 poetry run 起服务，发一条能触发该逻辑的消息；观察日志或断点处的实际行为，与预期比对；改完代码重启服务再验。循环里没有任何发行包无法替代的魔法，只有一样东西——你能看到框架内部。
举个具体例子：2.3 节讲到记忆编辑的四道闸门，读文档你知道它们存在，在源码环境里你可以逐行看到每次校验的真实执行顺序，甚至临时在闸门处打印参数与拒绝原因——模型某次编辑为何被拒，从"推测"变成"亲见"。这种确定性的提升，会让你后面写 persona 策略、设计记忆结构时的判断明显更准。
三个实用提醒。其一，保持上游同步的节奏：定期拉取上游更新并重装依赖，拖得越久，合并冲突越痛。其二，实验与生产分离：源码环境用来回答"框架为什么这样"，生产环境继续跑发行包——把自改源码直接上生产，等于签下无限期维护合同。其三，改动留痕：在源码上做的每一处修改，记录在案（哪怕只是一个本地补丁文件），升级时才知道自己背了哪些私有差异。
卸载与回退
源码实验台的可逆性很好：它的一切都活在项目目录与独立虚拟环境里，不碰系统全局。想退回发行包路线，删除项目目录、注销虚拟环境即可，此前积累的数据库数据完全不受影响——存储在数据库服务里，与框架代码的安装方式无关。这份"进出自由"也是敢于尝试源码路线的底气：最坏情况无非是删目录重来。
版本升级：源码环境最大的长期成本
源码路线的账单主要在升级环节，值得单独讲清。上游发新版本后，源码环境的升级流程是：拉取最新代码、poetry install 同步依赖、跑你自己的验证脚本确认行为、处理你私有改动与上游代码的冲突。前两步是命令，后两步是工作——工作量与两件事成正比：私有改动的数量、落后上游的距离。
控制成本的两条做法：私有改动数量最小化——能用配置、persona、自定义工具解决的需求，绝不改框架源码；同步节奏固定化——按固定周期同步上游，冲突在小时级范围内解决，拖成月级就是合并地狱。如果发现自己在源码上越改越多，先停下来想：我是在使用框架，还是在无意识地维护一个私有分支？这两个角色的成本结构天差地别。
关于源码安装的常见疑问
问：源码环境和发行包可以共存吗？ 可以且推荐。源码环境在独立目录与独立虚拟环境里，与发行包安装互不干扰；两者的服务不同时起（端口冲突）即可。常见分工是：日常实验用发行包，深挖框架行为时才起源码环境。
问：读源码需要先装源码吗？ 不需要。在线浏览仓库源码足够满足大多数阅读需求，只有要下断点、加日志、跑内部测试时才值得本地安装。把"装源码"当成阅读的前提，会平白多付一套环境的维护费。
问：Poetry 装依赖很慢或失败怎么办？ 多与网络环境有关。为包管理配置国内镜像源是最常见的解法；若个别依赖编译失败，先确认 Python 版本在支持区间，再查该依赖的系统级前置组件是否安装。这类问题与框架本身无关，属于 Python 生态的通用功课。
本节要点回顾
- 需求驱动：调试框架、参与共建、锁定改造版本三类需求才值得源码安装，否则发行包更划算。
- Poetry 四动作：克隆项目、安装依赖、环境内执行、增删依赖，一份声明文件换来可复现的环境。
- 安装四步：克隆、安装、配环境、源码启动，配置与发行包完全同源。
- 调试循环：改源码、起服务、发消息、验行为——源码路线的核心价值是看见框架内部。
- 三条纪律：定期同步上游、实验与生产分离、私有改动留痕。
- 进出自由：删除目录即回退，数据库数据与安装方式无关。
第 3 章至此收官。实验台已就绪——下一章我们给它装上观测仪表，第一次"看见"智能体的记忆长什么样。