工程与交付知识

这份文档关注 React / TypeScript 开发者从“调用成功”走向“稳定交付”需要补齐的能力。

1. 技术栈选择与职责

初期沿用熟悉的 React、TypeScript 和 Node.js。数据库、界面框架和部署方式选择自己能维护的方案，不为学习而一次引入多个新框架。

先通过所选供应商的官方 SDK 或接口理解请求、响应、错误和流式事件，再判断是否需要抽象框架。框架选择按实际需求验证，不将具体版本固定为长期必修。

React 客户端
  ↓ 用户输入、任务操作
Node.js 服务端
  ├─ 身份和权限检查
  ├─ 输入与输出校验
  ├─ 模型、检索与工具编排
  ├─ 数据库和任务状态
  └─ 日志、耗时与费用记录
       ↓
模型供应商 / 文档索引 / 业务接口

模型密钥留在服务端。客户端传来的用户标识、文档标识和“已确认”字段都不能直接作为可信授权依据。

2. 流式交互与异步任务

需要区分请求建立、首段结果、持续生成和最终完成。部分文字已经展示，不代表整个任务成功。

学习重点：

• 流式事件的解析与顺序，不假设每个网络块都是完整 JSON。
• 取消、断开、超时后的状态和已生成内容如何保留。
• 明确区分“正在生成”和“正在执行外部操作”。
• 较长任务使用持久化状态，页面刷新后可查询进展。
• 客户端取消连接不一定停止服务端或供应商执行，需检查支持情况并记录最终状态。

验收场景：连续点击提交、中途离开页面、生成时取消、网络断开、刷新查看旧任务。

3. Node.js 基础补齐

知识点	必须能处理的问题
Promise 与异步错误	不遗漏异步失败，不让任务永久停在处理中
超时与取消	为外部调用设置边界，并区分取消和失败
并发与限流	多用户同时调用时不无限堆积
环境配置	开发和生产配置分离，日志不暴露密钥
SQL 与持久化	保存用户、任务、结果、文档版本和运行记录
后台任务	长任务可查询状态，失败后能恢复或重做

不需要提前建设复杂基础设施。先解决项目真实出现的问题。

4. 可靠性：超时、重试、幂等

重试应区分临时错误、无效输入、权限不足和业务失败，并设置次数上限及等待策略。不要对所有异常无条件重复请求。

幂等意味着同一业务动作重复提交，也不会重复产生业务结果。例如创建待办应有业务请求标识，并在存储或下游服务中落实去重。

尤其注意“超时但实际已执行”：若保存操作没有及时返回，不能立即假设失败并重新创建。应查询状态或使用支持幂等的接口。

验收：模拟工具成功后响应丢失，确认重试不会产生两条相同记录。

5. 身份、权限和不可信内容

• 登录确认用户是谁，授权确认用户能访问什么或执行什么。
• 检索结果、历史记录和缓存都要遵守相同的数据隔离规则。
• 文档、网页和工具返回值可能包含不可信指令，不能用来扩大权限。
• 写入类工具仅暴露必要参数，服务端绑定当前用户和资源范围。
• 用户确认应对应具体操作和具体参数；参数变更后不能复用旧确认。
• 测试公开或已授权的数据，上传到模型服务前了解数据处理约定。

验收：用户 A 无法通过修改标识读取用户 B 的文档、任务、缓存或历史结果。

6. 可观测性

建议每次运行记录：

字段	用途
runId、taskId	串起整次任务和子步骤
模型、配置和提示词版本	复现与比较
检索文档版本及标识	追查答案依据
阶段耗时和最终状态	定位瓶颈与故障
输入/输出用量	费用估算
工具名称、状态和错误类型	排查执行问题
用户反馈与人工修改情况	判断真实质量

不要默认把所有原始输入和工具结果写进日志。对敏感内容脱敏，明确保留周期和访问权限。错误日志也可能泄露业务数据。

7. 费用与性能

一次任务费用可能包含多次模型调用、检索、向量生成、重排、工具服务和基础设施。重试与 Agent 循环也应计算。

一种估算形式：

单次模型费用 ≈ 输入计费用量 × 输入单价 + 输出计费用量 × 输出单价。

实际单位、缓存、推理用量等收费规则以供应商文档为准。不要把不同模型或平台的计费单位直接混用。

性能区分首段响应时间与全部完成时间。优化顺序是先记录瓶颈，再减少无关上下文、不必要调用和重复工作。缓存需要考虑用户权限、数据版本与失效规则。

验收：能估算一批任务的资源消耗，知道最慢和最贵的步骤，并设定运行上限。

8. 评测与测试的分工

方法	检查什么	例子
单元与接口测试	确定性程序行为	参数校验、权限、幂等、状态转换
端到端测试	完整用户流程	提交、编辑、确认、导出
AI 效果评测	模型输出质量	是否准确、有依据、遗漏关键信息
用户试用	是否真正有用	能否完成任务，复核和修改花多久

初始可建立约 50 条样例，例如 35 条用于开发、15 条留作验收。这个规模只适合早期发现问题，不足以保证生产可靠性。查看验收集并据此调优后，需要补充新的未见样例。

常用指标：

• 格式通过率 = 符合结构约定的输出数 / 评测输出总数。
• 任务通过率 = 满足预定义验收规则的任务数 / 评测任务总数。
• 引用支持率 = 经核查被引用支持的结论数 / 被检查的引用结论数。
• 人工处理耗时 = 检查、修正和最终完成任务的实际时间。

必须说明分母、样本构成和评分方式。平均数会隐藏极慢请求；样本充足后再看分位数，并说明样本量。不能把自测数字写成业务承诺。

9. 发布与维护

上线前至少具备：配置说明、权限检查、关键测试、异常处理、日志、费用边界、反馈入口和回退方式。

提示词、模型配置和知识库更新也是变更，应该有版本和回归记录。用户能继续使用旧功能，往往比一次增加很多 AI 能力更重要。

10. 本轮不强求

不要求同时掌握多种向量数据库、复杂队列、分布式架构、多个 Agent 框架和私有模型部署。随着容量、合规或性能需求出现，再选择性深入。