在研项目交接：把提示词、调用配置和 key 上下文完整交给接手的人

为什么 LLM 项目的交接特别容易断档

传统项目的交接往往围绕代码仓库展开，但 LLM 应用有一大块关键资产活在代码之外：提示词的迭代历史、为什么选这个模型、温度与最大输出为什么是这个值、key 放在谁的账户下、计费方式是什么。这些东西如果只留在原开发者脑子里，接手的人能跑通代码，却复现不了行为。

交接的目标不是"把代码给出去"，而是让接手者在没有你的情况下，能改一个提示词、换一个场景、解释一次费用波动。下面按资产类别拆开讲。

资产一：提示词要有版本和理由

提示词是最容易被当成一次性文本的部分，但它其实是产品逻辑。交接时至少要做到：

• 集中存放：提示词不要散落在多个文件、多个服务里，也不要有只存在于某个平台后台的手改版本。把它们放进仓库或一份明确的文档中，标明哪个是当前生产版本。
• 记录变更理由：每条重要提示词旁边写清楚它解决什么问题、试过哪些被否掉的方向。比如"这里强调输出为 JSON，是因为下游要解析"这类信息，比提示词本身更有价值。
• 标注变量占位：模板里的变量、拼接顺序、转义要求要写清楚，避免接手者替换变量后破坏了原有结构。
• 区分系统提示与用户输入：说明哪些内容由系统侧固定下发，哪些来自终端用户，这直接关系到安全边界和注入风险的处理方式。

资产二：模型选择要有依据

在支持一个 key 调用多家模型（如 Claude、GPT、DeepSeek、Qwen、GLM、Kimi 等）的聚合接入方式下，模型名是可替换的配置项，因此"为什么选它"必须显式写下来，否则接手者会随意改动。

需要记录的包括：

• 每个任务场景对应的模型，以及选择它的原因（能力要求、输出长度、响应速度、成本考虑等）。
• 哪些场景做过替换测试、结果如何，哪些场景尚未验证。
• 是否有降级或备用模型，触发条件是什么。

这样接手者在更换模型时有判断依据，而不是靠猜。

资产三：调用参数要连同含义一起交

调用参数是最容易"照抄但不懂"的部分。交接文档里应把每个非默认参数与它的业务含义绑定：

• 温度、top_p 等采样参数：说明调高或调低是为了什么效果，改动会影响哪些下游环节。
• 最大输出长度：说明这个上限是被什么约束的（展示区域、下游解析、响应时间）。
• 流式与非流式：当前用的是哪种，为什么，切换会影响前端的哪些逻辑。
• 超时与重试：重试次数、退避策略、哪些错误值得重试、哪些应当直接失败。
• 结构化输出约定：如果依赖 JSON 模式或特定格式，写清楚解析失败时的兜底逻辑。

把这些写成一份可执行的配置说明，而不是散落在代码注释里的片段。

资产四：key 与账户上下文

聚合接入的一个实际好处是 key 管理相对集中：一个 key 可以调用多个模型，不必为每家厂商分别开账户。但交接时仍需把账户层面的事讲清楚，否则接手者会遇到"能调用但不知道为什么扣费"的情况。

需要在交接材料中说明的内容：

• key 由谁持有、在哪个账户下、通过什么方式充值（例如使用 Base 上的 USDC 充值、无需 KYC 的流程），以及余额不足时的处理路径。
• 计费口径：用户侧按官方价乘以固定系数扣费，贡献 key 的一方按另一套系数获得返还。把这两个系数和结算方式写进文档，避免接手者误判成本或对账。
• key 的存放位置与轮换方式：不要明文提交到仓库，说明使用环境变量或密钥管理的方式，以及在人员变动时如何更换。
• 调用额度与并发相关的实际约束，以你所在接入方的说明为准，不要凭印象写在文档里。

资产五：一份可运行的交接清单

把以上内容落成一份清单，交接双方逐项确认：

1. 提示词仓库位置、当前生产版本标识、变更记录入口。
2. 场景与模型对照表，含选择理由与已验证的替换结论。
3. 调用参数说明，每个非默认值都附业务含义。
4. key 归属、充值方式、计费系数、轮换流程。
5. 一个能跑通的最小示例：从读取配置到发出一次请求再到解析结果。
6. 已知问题与待验证项，明确写出"这些我们还没搞定"。

交接完成后怎么验证

最有说服力的验收方式是让接手者在不问你的前提下完成一件小事：修改一条提示词并说明影响范围，或者把一个场景换到另一个模型上跑通。能做到，说明资产是完整的；做不到，缺的通常就是上面某一类没有写下来的上下文。

LLM 项目的交接本质上是把隐性知识显性化。代码会过期，模型会更新，但一份写清楚"为什么这么做"的资产文档，能让接手者在变化发生时做出合理判断。