企业官网建设流程全解析

1. 这不是模型“看错了”，是输入链路上的静默失血

你刚跑完一轮 Agent 测试，日志里清清楚楚写着“源端输入 50 条结构化数据”，可模型推理时的 prompt 里只塞进了前 20 条——中间那 30 条呢？没报错、没警告、没超时，连个 warning 都没打出来，就像被空气吞掉了一样。这种现象在当前主流 Agent 框架（LangChain、LlamaIndex、AutoGen、Hermes）中高频出现，业内管它叫“静默截断”（Silent Truncation），不是 bug，而是设计使然；不是故障，而是配额约束下的默认妥协。它不抛异常，不中断流程，却悄悄把你的业务逻辑切掉一大块，导致 Agent 做出明显违背常识的决策：比如用前 20 条用户投诉记录总结“服务满意度极高”，而漏掉了后 30 条集中爆发的支付失败反馈。我去年在给某银行做智能投顾 Agent 时，就因这个细节在线上环境连续三天给出错误资产配置建议，直到运维同学翻查 token 统计埋点才定位到问题。核心关键词Agent、静默截断、模型输入、上下文截断、配额其实指向同一个底层事实：LLM 的上下文窗口是物理铁律，而 Agent 框架在数据组装阶段的截断策略，往往比模型本身更早、更隐蔽地决定了你能“喂”给模型什么。它不发生在 model.generate() 那一刻，而藏在你调用 add_documents()、build_prompt() 或 run_agent() 的毫秒级内部。适合正在调试 Agent 行为、排查输出失真、或准备上线高可靠金融/医疗类 Agent 的工程师——尤其当你发现模型“似乎理解不到位”，但日志又一片太平时，这大概率就是静默截断在作祟。

2. 静默截断的三层发生位置与根本动因

静默截断绝非单一环节的问题，它像一层薄冰，覆盖在 Agent 输入链路的三个关键断面：数据预处理层、框架编排层、模型调用层。每一层的截断逻辑不同，触发条件各异，但共同特点是“不报错、不告警、不中断”。下面我结合 LangChain v0.1.18 和 LlamaIndex v0.10.42 的实际源码路径，拆解这三层如何联手制造“50 条变 20 条”的幻觉。

2.1 数据预处理层：分块器（TextSplitter）的隐性瘦身

这是最容易被忽略的第一道关卡。当你把一份含 50 条客户评论的 CSV 文件丢进 Agent，框架第一步通常是用 TextSplitter 将其切分成 chunks，再向量入库或拼入 prompt。但多数开发者没意识到：TextSplitter 本身就有默认 chunk_size 限制，且该限制独立于后续模型的 context window。以 LangChain 的 RecursiveCharacterTextSplitter 为例，其默认 chunk_size=1000（字符数），chunk_overlap=200。假设每条评论平均 300 字，50 条共 15,000 字。按默认参数，它会切成约 15 个 chunk（15,000 ÷ (1000-200) ≈ 18.75 → 向上取整为 19，再减去 overlap 冗余后实际有效 chunk 约 15）。但如果你在后续检索中设置了 top_k=10，那就只取前 10 个 chunk —— 对应约 30 条原始评论。而你代码里写的“加载全部 50 条”，其实从这一步起就已失真。更隐蔽的是，某些 Splitter（如 MarkdownHeaderTextSplitter）会因标题层级跳过无标题段落，导致部分数据直接被过滤。我曾遇到一个案例：客户上传的 Excel 表格里第 32 行是空行+注释，Splitter 将其识别为无效 section 并丢弃，结果下游永远收不到那条关键的“退款政策变更说明”。

2.2 框架编排层：检索器（Retriever）与提示词构建器（PromptBuilder）的双重截断

进入 Agent 的核心编排逻辑，截断开始变得系统化。这里有两个主力“裁缝”：

• Retriever 的 top_k 截断：无论你用 Chroma、FAISS 还是 PGVector，检索器返回结果时都强制指定 top_k 参数。LangChain 的 VectorStoreRetriever 默认 top_k=4，LlamaIndex 的 VectorIndexRetriever 默认 top_k=10。注意：这个 k 是检索返回的 chunk 数量，不是原始数据条数。一个 chunk 可能包含多条原始记录（如合并的 JSON 对象），也可能只含半条（被 split 切断）。当你设置 top_k=10，而每个 chunk 平均承载 2 条原始数据时，理论最大值是 20 条——这正是标题中“50 条变 20 条”的典型来源。但问题在于，框架不会告诉你“这 10 个 chunk 覆盖了原始数据的哪几条”，它只返回向量相似度最高的片段。你看到的 prompt 里只有 20 条，却不知道它们来自原始 50 条中的哪些索引。

• PromptBuilder 的长度硬截断：即使检索器返回了 10 个 chunk，最终拼装 prompt 时还有第二道闸门。LangChain 的 ChatPromptTemplate 在 format() 时会调用 get_num_tokens() 计算当前 prompt 长度，若超过模型声明的 max_context_length（如 gpt-3.5-turbo 的 16k），它会启动 _truncate_messages() 方法——从 message 列表末尾开始逐条删除，直到满足长度要求。这个过程完全静默，不 log、不 warn、不 raise。更致命的是，它删除的是整个 message（即整个 chunk），而非按 token 精确裁剪。所以你可能看到 prompt 里只剩前 3 个 chunk（对应 6 条数据），而后面 7 个 chunk 被整条丢弃。我在调试一个电商客服 Agent 时发现，当用户问题涉及“近三个月订单对比”，框架检索出 15 个订单 chunk，但 prompt 构建时因总 token 超限，直接砍掉最后 12 个，只剩最早的 3 笔订单——Agent 自然得出“用户消费频次极低”的错误结论。

2.3 模型调用层：Tokenizer 与 API 层的终极物理墙

最后一道防线是模型自身的 token 限制。但这里的关键认知是：API 层的截断发生在请求发送前，且由 SDK 自动完成，你甚至看不到原始请求体。OpenAI Python SDK 的 chat.completions.create() 方法，在序列化 messages 参数时，会调用 tiktoken 库计算 total_tokens。若 total_tokens > model_max_tokens（如 gpt-4-turbo 的 128k），SDK 会触发 _truncate_to_max_tokens() —— 它不是删 message，而是对每个 message.content 进行 token 级截断，从末尾开始削掉超出部分。这意味着：你传入的第 20 条数据，可能只被保留了前 50 个 token（约 35 字），后半句关键信息（如“但需提供发票原件”）被无声抹去。而日志里只显示 “request_id: xxx, status_code: 200”，仿佛一切完美。Anthropic 的 SDK 同理，只是截断算法略有差异。这层截断无法绕过，它是 LLM 服务的物理边界，但它的静默性让开发者误以为“数据完整送达”，实则已在网关处被肢解。

提示：静默截断的“静默”本质，源于各层设计哲学——框架优先保障服务可用性（不 crash）、响应速度（不超时）、资源可控（不 OOM）。因此，所有截断逻辑都被封装为“安全兜底”，而非“异常预警”。作为开发者，你必须主动在每个环节植入可观测性，而不是等待错误发生。

3. 四步定位法：从现象到根因的精准归因

面对“源端 50 条，模型只看到 20 条”，别急着改模型或换框架。先用这套四步法，像外科医生一样逐层探查，90% 的问题能在 15 分钟内定位到具体断点。以下步骤基于真实线上排查经验，已验证于 LangChain + OpenAI、LlamaIndex + Anthropic、自研 Agent 框架三类场景。

3.1 第一步：锁定截断发生位置——在关键节点埋点打日志

不要依赖框架默认日志，它们通常只记录“成功”事件。你需要在数据流经的四个黄金节点手动插入 token 计数和数据快照：

1. 数据加载后：在loader.load()返回 documents 后，立即打印len(documents)和sum(len(d.page_content) for d in documents)。确认原始数据是否真的 50 条、总字符数是否符合预期。曾有团队因 CSV 编码问题（BOM 头被误读为数据），实际只加载了 48 条，却以为是截断。

2. 分块后：在text_splitter.split_documents(documents)后，打印len(chunks)和max(len(c.page_content) for c in chunks)。检查 chunk 数量是否异常（如 50 条变 15 chunk），以及单 chunk 是否过大（>5000 字符易触发后续截断）。

3. 检索后：在retriever.invoke(query)后，打印len(retrieved_chunks)和[(c.metadata.get('source_row', 'N/A'), len(c.page_content)) for c in retrieved_chunks[:5]]。这是最关键的一步！它能直接告诉你：框架认为哪些原始数据条目被选中，以及它们的文本长度。如果这里就只有 20 条，说明问题在检索层；如果这里有 50 条，但下一步骤变少，则问题在 prompt 构建层。

4. Prompt 构建后：在prompt_template.format(...)返回 final_prompt 后，调用tokenizer.encode(final_prompt)获取 token 数，并打印len(tokenizer.encode(final_prompt))和model_max_tokens。若前者 > 后者，说明模型层截断已触发。

注意：tiktoken 的 tokenizer 选择必须与模型严格匹配。gpt-3.5-turbo 用cl100k_base，gpt-4 用cl100k_base，Claude 用claude。用错 tokenizer 会导致 token 计数偏差高达 30%，让你误判截断位置。

3.2 第二步：量化截断损失——用 token 映射反推原始数据覆盖度

一旦定位到截断节点（如检索后只剩 20 条），下一步是量化“丢了什么”。不能只看数量，要看语义权重。我的做法是：为每条原始数据生成唯一 token fingerprint。

• 对每条原始记录（如 CSV 中第 i 行），提取其核心字段（如用户 ID、时间戳、关键词），拼接成短字符串f"{uid}_{ts}_{keyword}"，用同一 tokenizer 编码，取前 5 个 token 作为 fingerprint。
• 在检索返回的 chunks 中，对每个 chunk 的 page_content 执行同样操作，生成 fingerprint。
• 建立 fingerprint 映射表，统计哪些原始记录的 fingerprint 出现在检索结果中。

这样你就知道：丢失的 30 条里，有 15 条是高频关键词（如“退款”、“故障”），7 条是最近 24 小时数据，8 条是 VIP 用户反馈。这比单纯说“丢了 30 条”有价值百倍——它指导你调整检索策略（如加时间衰减权重、提升 VIP 用户权重），而非盲目扩大 top_k。

3.3 第三步：验证框架默认参数——逐项检查 7 个关键配置项

90% 的静默截断源于未显式覆盖框架默认值。以下是必须核查的 7 个参数，它们分散在不同模块，极易被遗漏：

特别提醒：similarity_top_k在 LlamaIndex 中常与 retriever.top_k 同时存在，若两者都设为 10，实际返回 100 个 chunk（10×10），远超预期。务必统一管理，只在一个地方控制。

3.4 第四步：复现与隔离——构造最小可复现案例（MRE）

当以上三步仍无法定位，就进入终极手段：剥离业务逻辑，构建 MRE。这不是为了“证明框架有 bug”，而是为了排除环境干扰。我的标准 MRE 模板如下：

# minimal_reproducible_example.py from langchain_community.document_loaders import CSVLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain.retrievers import VectorStoreRetriever # 1. 构造确定性数据：50 行 CSV，每行格式 "id,text"，text 固定为 "record_{i}_content" data = [{"id": i, "text": f"record_{i}_content"} for i in range(50)] import csv with open("test_50.csv", "w", newline="") as f: writer = csv.DictWriter(f, fieldnames=["id","text"]) writer.writeheader() writer.writerows(data) # 2. 严格控制所有参数 loader = CSVLoader("test_50.csv") docs = loader.load() # 应得 50 docs print(f"Loaded {len(docs)} docs") splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50) chunks = splitter.split_documents(docs) # 应得 ~60 chunks print(f"Split into {len(chunks)} chunks") embeddings = OpenAIEmbeddings(model="text-embedding-3-small") vectorstore = Chroma.from_documents(chunks, embeddings) retriever = VectorStoreRetriever(vectorstore=vectorstore, search_kwargs={"k": 20}) # 显式设 k=20 query = "get all records" results = retriever.invoke(query) print(f"Retrieved {len(results)} chunks") # 若此处 <20，问题在检索层 # 3. 构建 prompt 并计数 from langchain_core.prompts import ChatPromptTemplate prompt = ChatPromptTemplate.from_messages([ ("system", "You are a data analyst."), ("user", "Here are {n} records: {data}. Summarize key patterns.") ]).format(n=len(results), data="\n".join([c.page_content for c in results])) import tiktoken enc = tiktoken.encoding_for_model("gpt-3.5-turbo") token_count = len(enc.encode(prompt)) print(f"Prompt tokens: {token_count}, Model limit: 16384")

运行此脚本，观察哪一行输出与预期不符。MRE 的价值在于：它能快速区分是你的业务代码问题（如自定义 retriever 逻辑），还是框架底层行为。我曾用此法 3 分钟内确认是客户自研的 hybrid_retriever 在 score 排序时误用了降序，导致 top_k 取到了最不相关的 chunk。

4. 五种实战解决方案与落地细节

定位到根因后，解决方案不能停留在“调大 top_k”这种粗暴操作。真正的工程实践需要兼顾效果、成本、可维护性。以下是我在 12 个 Agent 项目中验证过的五种方案，附带参数计算、性能影响和适用场景。

4.1 方案一：动态 top_k + 语义保真度加权（推荐用于高价值数据场景）

核心思想：不盲目增加 top_k，而是让有限的 k 个 slot 承载更高信息密度。适用于金融风控、医疗问诊等容错率极低的场景。

实现步骤：

1. 为每条原始数据计算语义重要性分数：

   • 使用轻量级 embedding 模型（如all-MiniLM-L6-v2）对每条记录编码，得到 384 维向量。
   • 计算该向量与 query embedding 的余弦相似度，作为基础相关分。
   • 叠加业务权重：如订单数据中，“支付失败”关键词出现则 +0.3 分，“VIP 用户”标签则 +0.2 分。
   • 最终分数 = 相关分 × 业务权重系数。

2. 检索时启用重排序（Rerank）：
   LangChain 支持ContextualCompressionRetriever，LlamaIndex 支持CohereRerank。但更轻量的做法是：先用 vector store 检索 top_k×2（如 k=20，则取 40），再用上述分数排序，取前 k 个。

3. 动态确定 k 值：
   根据 query 复杂度调整。简单 query（如“查余额”）用 k=5；复杂 query（如“对比近三个月退款率变化趋势”）用 k=20。可通过 query 中动词数量、时间范围词（“月”、“季度”）数量自动判定。

参数计算示例：
假设每条记录平均 200 字符，embedding 模型 token 效率 1:1.2（1 字符 ≈ 1.2 token），则 20 条记录约 4800 tokens。gpt-3.5-turbo 的 16k 上下文，扣除 system prompt（200 tokens）、output space（512 tokens），剩余约 15.3k tokens。4800 tokens 占比 31%，留有充足空间。若强行扩到 50 条，则达 12k tokens，占比 78%，极易触发后续截断。

实操心得：

• 业务权重系数必须通过 A/B 测试校准。我们曾将“VIP 用户”权重设为 0.5，结果导致普通用户投诉被严重低估，后下调至 0.15。
• Rerank 步骤增加约 120ms 延迟（CPU 服务器），但准确率提升 37%（F1-score），ROI 显著。

4.2 方案二：分层摘要 + 原始数据锚点（推荐用于长周期、多维度分析）

当数据量远超上下文限制（如分析一年 10 万条日志），硬塞不现实。此时应放弃“全量原文”，转向“摘要+溯源”。

实现架构：

• Layer 1（宏观摘要）：用 LLM 对全部 50 条做一次 batch summarization，生成 300 字全局洞察（如“投诉集中于支付环节，占比 68%”）。
• Layer 2（关键样本）：从 50 条中按聚类（如 K-means on embedding）选出 5 个代表性样本，确保覆盖主要主题。
• Layer 3（锚点引用）：在 prompt 中明确标注：“以下为摘要（Layer 1）和 5 个关键样本（Layer 2）。如需查看某样本原始上下文，请回复‘DETAIL-{id}’，我将加载其完整记录。”

技术细节：

• Batch summarization 可用map_reduce链，LangChain 内置支持。关键是要控制 map 阶段的 chunk size，避免单 chunk 超限。
• 代表性样本选取：不用随机，而用MaxMarginalRelevance（MMR）算法，平衡相关性与多样性。LlamaIndex 的NodeWithScore支持开箱即用。
• 锚点机制需 Agent 框架支持多轮状态管理。我们在 AutoGen 中通过groupchat的send方法实现，用户回复DETAIL-32后，Agent 自动触发新检索，只加载第 32 条的完整内容。

性能数据：

• 全量 50 条原文 token：≈ 12,000
• Layer 1 摘要 + Layer 2 5 样本 token：≈ 2,800
• 节省 76% token，且保留可追溯性。某物流客户采用此方案后，投诉分析报告生成时间从 8.2s 降至 1.9s，同时支持深度钻取。

4.3 方案三：客户端预过滤 + 服务端精排（推荐用于高并发、低延迟场景）

当 QPS > 100，且每条 query 都需处理海量数据时，把过滤逻辑下沉到客户端（如前端、移动端）能极大减轻服务端压力。

实施流程：

• 客户端预过滤：前端根据用户筛选条件（如时间范围、产品线、状态）生成 filter query，只请求符合条件的数据子集。例如，用户勾选“近 7 天”+“APP 端”，则前端向 Agent 服务发送{"filters": {"date_range": "last_7_days", "platform": "app"}}。
• 服务端精排：Agent 收到已过滤的子集（如 50 条变 15 条）后，再执行高精度 rerank 和 prompt 构建。

关键技术点：

• Filter query 必须与向量库 schema 严格对齐。我们使用 Pydantic 模型定义FilterRequest，并自动生成 OpenAPI 文档，确保前后端契约一致。
• 为防止客户端恶意请求全量数据，服务端需校验 filter 结果数量。若len(filtered_docs) > 50，则拒绝请求或强制启用方案一的动态 top_k。

实测效果：

• 某电商 App 的客服 Agent，QPS 从 45 峰值升至 210，P99 延迟稳定在 320ms。
• 关键收益：95% 的请求在客户端完成 80% 的数据过滤，服务端只需处理“精炼后”的数据。

4.4 方案四：流式分块 + 渐进式推理（推荐用于超长文档解析）

针对单条记录本身超长（如一份 50 页 PDF 合同），传统分块会将其切成 50+ chunks，导致检索碎片化。此时应采用流式处理。

工作流：

• Step 1（定位）：用 keyword + embedding 混合检索，快速定位合同中“违约责任”章节的起始页码。
• Step 2（流式加载）：不加载全文，而是按需读取该章节所在页及相邻 2 页（共 3 页），转为文本。
• Step 3（渐进推理）：将这 3 页文本送入 LLM，生成初步结论；若结论需验证其他条款，则发起第二次流式加载（如“争议解决”章节）。

工具链：

• PDF 解析用pymupdf（比 PyPDF2 快 3 倍，支持精准页码定位）。
• 流式加载逻辑封装为DocumentStreamer类，暴露load_section(page_start, page_end)方法。
• Agent 的 memory 需支持跨轮次缓存已加载的 section，避免重复解析。

优势：

• 单次推理 token 控制在 3k 内，响应极速。
• 用户感知为“智能跳转”，而非“全文扫描”，体验更自然。某律所 SaaS 产品采用后，合同审查平均耗时从 14 分钟降至 2.3 分钟。

4.5 方案五：混合存储 + 查询路由（推荐用于异构数据源场景）

当数据来自多个源头（数据库、API、文件），且质量/时效性差异大时，统一向量化效率低下。应按数据特性分层存储。

架构设计：

• Hot Layer（热数据）：近 24 小时订单、实时日志，存于内存向量库（如 RedisVL），支持毫秒级检索。
• Warm Layer（温数据）：近 30 天历史数据，存于 Chroma/PGVector，检索延迟 <200ms。
• Cold Layer（冷数据）：归档数据，存于对象存储（S3），仅提供关键词搜索，命中后触发异步摘要生成。

查询路由逻辑：

• Agent 解析 query 时，先识别时间关键词（“刚刚”、“今天”→ Hot；“上个月”→ Warm；“2022 年”→ Cold）。
• 根据识别结果，自动路由到对应存储层，并设置不同的 top_k：Hot 层 k=5（高精度），Warm 层 k=15（平衡），Cold 层 k=3（摘要导向）。

落地要点：

• 时间关键词识别用 spaCy 的 rule-based matcher，比 LLM 更快更稳。
• Cold 层的异步摘要需有 fallback：若摘要未生成，返回“该数据已归档，预计 2 分钟内生成摘要”。
• 我们在某 IoT 平台部署此方案，设备告警分析的平均响应时间从 1.8s 降至 0.45s，且冷数据查询不再拖慢整体 SLA。

5. 静默截断的 7 个致命误区与避坑清单

即便掌握了定位方法和解决方案，工程师仍常因思维惯性踩坑。以下是我在 12 个项目中总结的 7 个高频误区，每个都附带真实事故案例和纠正动作。

5.1 误区一：认为“模型支持 128k 就能塞 128k”

事故案例：某客户用 gpt-4-turbo（128k）处理 10 万行日志，自信满满设top_k=1000，结果 prompt 构建时报TokenLimitExceededError。
根因：忽略了 prompt 的固定开销：system message（约 200 tokens）、few-shot examples（约 1500 tokens）、output formatting instructions（约 300 tokens）。真正可用空间 ≈ 128,000 - 2,000 = 126,000 tokens。而 1000 条日志，每条平均 150 字符 × 1.2 token/char ≈ 180 tokens，总计 180,000 tokens，远超上限。
纠正动作：

• 永远用available_tokens = model_max_tokens - fixed_overhead计算可用空间。
• 固定开销必须实测：用空 query 调用一次，log 出usage.prompt_tokens。
• 在代码中硬编码MAX_AVAILABLE_TOKENS = 126000，并在数据加载时做守卫：if total_data_tokens > MAX_AVAILABLE_TOKENS: raise ValueError("Data exceeds available context")。

5.2 误区二：用字符数代替 token 数做截断判断

事故案例：开发者写if len(text) > 16000: text = text[:16000]，结果模型仍报错。
根因：中文字符、标点、emoji 的 token 化效率不同。一个中文字符平均 1.3~1.8 tokens，一个 emoji 可能占 4 tokens。len(text)为 16000 的字符串，token 数可能达 25000。
纠正动作：

• 所有长度判断必须用tiktoken.encode()。
• 封装工具函数：

  def safe_truncate(text: str, max_tokens: int, model: str = "gpt-3.5-turbo") -> str: enc = tiktoken.encoding_for_model(model) tokens = enc.encode(text) if len(tokens) <= max_tokens: return text truncated_tokens = tokens[:max_tokens] return enc.decode(truncated_tokens)

5.3 误区三：在检索层调大 top_k，却不优化 chunk 粒度

事故案例：为解决“50 条变 20 条”，将top_k=50，结果 prompt 超限，模型返回context_length_exceeded。
根因：top_k=50检索出 50 个 chunks，但每个 chunk 因chunk_size=1000过大，总 token 爆炸。
纠正动作：

• top_k与chunk_size必须协同优化。公式：expected_total_tokens ≈ top_k × chunk_size × token_ratio。
• 设定目标：expected_total_tokens ≤ 0.7 × available_tokens（留 30% 余量）。
• 若top_k=50，available_tokens=15000，则chunk_size应 ≤15000 × 0.7 / 50 / 1.2 ≈ 175字符。

5.4 误区四：忽略 metadata 对检索的影响

事故案例：某客服 Agent 总是漏掉 VIP 用户的投诉，尽管其文本相似度很高。
根因：metadata（如{"is_vip": True}）未参与向量化，检索仅基于 page_content，VIP 标签被无视。
纠正动作：

• 将关键 metadata 拼入 page_content：doc.page_content = f"[VIP] {doc.page_content}"。
• 或使用支持 metadata filtering 的 vector store（如 Chroma 的where参数），在检索时显式过滤：vectorstore.similarity_search(query, k=10, filter={"is_vip": True})。

5.5 误区五：认为“静默”等于“安全”，不加监控告警

事故案例：线上 Agent 运行 3 个月，某天突然大量输出“数据不足，无法判断”，才发现过去 2 周因数据源变更，chunk_size实际失效，90% 的检索返回空。
根因：无截断监控，问题长期潜伏。
纠正动作：

• 在生产环境埋点：retrieved_count,prompt_token_count,model_input_token_count。
• 设置告警规则：retrieved_count < expected_min（如预期 50 条，告警阈值设 40）；prompt_token_count > 0.9 × available_tokens（高风险截断预警）。
• 我们用 Prometheus + Grafana 实现，阈值告警准确率 99.2%。

5.6 误区六：在 prompt 中硬编码数据，而非用变量注入

事故案例：开发者写prompt = f"基于以下{len(data)}条记录：{data_str}，回答..."，当data_str过长，f-string 直接崩溃。
根因：Python 字符串拼接有内存限制，且无法做 token 级控制。
纠正动作：

• 永远用ChatPromptTemplate的format()方法，它内置 token 计算和安全截断。
• 若必须手动拼，用safe_truncate()处理data_str后再注入。

5.7 误区七：只关注输入截断，忽视输出截断对 Agent 状态的影响

事故案例：Agent 需生成 JSON 格式报告，但因max_tokens=512过小，JSON 被截断在{ "summary": "..."，下游解析失败。
根因：输出截断导致 Agent 的 internal state（如 memory、tool call 参数）损坏。
纠正动作：

• 为 output 设置足够 buffer：max_tokens = expected_output_tokens × 1.5。
• 强制 JSON 输出时，用response_format={"type": "json_object"}（OpenAI）或json_mode=True（Anthropic），模型会优先保证 JSON 完整性。
• 在 Agent 的 parse step 加校验：if not response.strip().endswith("}") or not response.strip().startswith("{"): raise ParseError("Incomplete JSON")。

注意：这 7 个误区，每一个都曾在我的项目中造成 P1 级故障。它们不是理论风险，而是血泪教训。把这份清单贴在团队 Wiki 首页，每次 code review 都对照检查，能避免 80% 的静默截断引发的线上事故。

6. 工程化防御体系：从被动排查到主动免疫

静默截断的本质是 LLM 生态的固有约束，无法根除，但可以构建一套工程化防御体系，让问题在发生前就被拦截，或在发生时被精准捕获。这套体系已在我们交付的