第 1.8.4 节：把异常、日志、测试和 README 做成交接证据
本节围绕“把异常、日志、测试和 README 做成交接证据”展开，先建立直观判断，再进入工程细节。完成本节后，你应该能够把异常、日志、测试和 README整理成证据材料、复核标准和可展示检查项。
权限、状态和日志
Python（编程语言）工程底座里的权限、状态和日志不只是安全章节才讲的内容。本章要先建立基本口径。
权限
| 权限对象 | 本章处理方式 | 客服工作台例子 |
|---|---|---|
| 配置权限 | 不同 env_profile（环境配置） 使用不同配置 | 开发环境不能误连生产工单系统。 |
| 密钥权限 | 代码只使用 secret_ref（密钥引用） | 开发者不需要知道生产模型 API Key（接口密钥）明文。 |
| 工具权限 | 工具客户端执行前依赖上层权限判断 | 普通用户不能查询他人订单。 |
| 日志权限 | 日志不记录密钥和敏感原文 | 排查时可看错误类型，不泄露用户隐私。 |
| 任务权限 | 高影响任务要标明环境和影响范围 | 资料重建索引不能误跑到生产环境。 |
状态
| 状态对象 | 推荐状态 | 用途 |
|---|---|---|
| 配置状态 | 已加载、缺失、格式错误、密钥不可用 | 启动时快速发现环境问题。 |
| 依赖状态 | 已锁定、未锁定、版本冲突、待升级 | 判断问题是否来自依赖变化。 |
| 文件任务状态 | 待处理、处理中、成功、失败、可重试、已跳过 | 管理资料解析和索引任务。 |
| 工具调用状态 | 待调用、成功、超时、无权限、业务拒绝、异常 | 支撑订单查询和工单创建兜底。 |
| 测试状态 | 未运行、通过、失败、跳过 | 交付前知道验证边界。 |
日志
| 日志内容 | 记录什么 | 不记录什么 |
|---|---|---|
| 请求日志 | trace_id（追踪编号）、project_id（项目编号）、入口、耗时 | 用户完整隐私原文和密钥。 |
| 模块日志 | module_name（模块名称）、task_name（任务名称）、关键状态 | 大量无意义调试噪声。 |
| 错误日志 | error_type（错误类型）、可读错误、是否可重试 | 真实密钥、完整内部凭证。 |
| 配置日志 | env_profile（环境配置）、缺失的 config_key（配置键） | 配置值中的敏感内容。 |
| 测试日志 | test_entry（测试入口）、通过/失败、验证范围 | 让人误以为未覆盖部分也已验证。 |
日志的目标是让问题可复盘，不是把所有内容都打印出来。客服工作台尤其要注意：用户隐私、企业内部资料、API Key（接口密钥）和数据库凭证都不能进入普通日志。
失败场景与兜底
真实项目一定会失败。Python（编程语言）工程底座的价值就在于：失败时系统能给出清楚状态，而不是突然崩掉或沉默。
| 失败场景 | 表现 | 可能原因 | 兜底策略 | 验收方式 |
|---|---|---|---|---|
| 虚拟环境不一致 | 本地运行缺库或版本冲突 | 未使用独立环境或依赖未锁定 | README（项目说明文件）说明环境要求，保留依赖锁定 | 新环境能按说明复现。 |
| 依赖升级破坏接口 | 模型调用或数据校验突然失败 | SDK（软件开发工具包）或框架版本变化 | 锁定依赖，升级前先跑测试入口 | 能定位到依赖变化。 |
| 配置缺失 | 启动失败或模型调用失败 | 缺少 config_key（配置键） | 启动时检查配置并给出可读错误 | 错误日志包含缺失键，不包含密钥。 |
| 密钥失效 | 外部模型或系统返回认证失败 | secret_ref（密钥引用） 指向失效密钥 | 返回认证错误类型，提醒更新密钥 | 日志不泄露密钥值。 |
| 订单系统超时 | 用户查不到订单状态 | 外部 HTTP（超文本传输协议）接口无响应 | 有限重试，失败后转人工或提示稍后 | 不让模型编造订单结果。 |
| 文件解析失败 | 知识库资料无法进入索引 | 文件损坏、格式复杂、依赖缺失 | 标记资料失败状态，记录错误和可重试信息 | 失败资料不会进入正式回答。 |
| 异步任务部分失败 | 批量任务只成功一部分 | 某些文件或接口失败 | 记录每个子任务状态，允许重试失败项 | 成功和失败范围清楚。 |
| 日志缺少追踪编号 | 无法还原用户问题链路 | 入口未生成 trace_id（追踪编号） | 请求和任务入口统一生成追踪编号 | 任一错误能按追踪编号检索。 |
| 测试入口缺失 | 改动后只能手动试 | 没有模块级验证 | 为关键模块补测试入口 | 能单独验证配置、客户端和工具。 |
| README（项目说明文件）过期 | 新成员无法启动项目 | 文档未随工程更新 | 把 README（项目说明文件）列入交付检查 | 文档与当前模块结构一致。 |
兜底原则很简单：失败可以发生，但失败必须有状态、有日志、有下一步。
不适合展开语法学习的场景
本章不是说语法不重要，而是说下面这些场景不适合把重点放在语法细节上。
| 场景 | 为什么不适合讲语法 | 本章应该讲什么 |
|---|---|---|
| 解释客服工作台项目结构 | 语法不能决定模块边界 | 讲模块职责、输入输出、测试入口。 |
| 设计配置和密钥 | 重点不是如何读取字符串 | 讲配置键、密钥引用、环境隔离和日志脱敏。 |
| 封装模型客户端 | 重点不是请求语法 | 讲超时、重试、错误类型、供应商替换边界。 |
| 处理企业资料文件 | 重点不是文件读取方法 | 讲资料状态、解析失败、重试和引用追踪。 |
| 引入异步 I/O（输入输出） | 语法容易掩盖业务顺序 | 讲 I/O（输入输出）密集场景、超时、取消、部分失败和日志。 |
| 设计测试入口 | 重点不是测试框架语法 | 讲验证范围、失败样例和交付边界。 |
| 写 README（项目说明文件） | 不是文档格式问题 | 讲项目如何交接、配置、运行和排查。 |
真正需要系统学 Python（编程语言）语法时，可以单独找语法课程。本章只讲 AI Agent（人工智能体）项目最先用得上的工程能力。
工程检查清单
- 是否明确本项目负责的客服工作台范围和不负责的高风险动作？
- 是否有清晰项目结构，区分应用入口、模型客户端、工具客户端、文件处理、配置、任务、测试和文档？
- 是否使用独立虚拟环境，避免和其他项目依赖混用？
- 是否有依赖锁定，并能说明当前验证过的依赖版本组合？
- 是否区分普通配置、敏感密钥和密钥引用？
- 是否避免把真实 API Key（接口密钥）、数据库凭证和客户资料写进代码或日志？
- 是否设计
project_id（项目编号）、module_name（模块名称）、env_profile（环境配置）和trace_id（追踪编号）？ - 是否把模型服务、订单系统、物流系统和工单系统封装成客户端模块？
- 是否为文件处理设计状态、失败原因和重试策略？
- 是否只在合适的 I/O（输入输出）密集场景引入异步，并保留错误收集和日志？
- 是否定义
error_type（错误类型）和log_level（日志等级）？ - 是否为关键模块准备
test_entry（测试入口）？ - 是否为资料索引、批量导入、健康检查等操作设计
task_name（任务名称）？ - 是否让 README（项目说明文件）覆盖项目简介、结构、环境、配置、密钥、任务、测试、日志和风险？
- 是否能向面试官说明 Python（编程语言）在本项目里承担的工程职责，而不是只讲语法？