/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}
React 现代化 Web 应用开发：把经验沉淀成下一次的规则
前端团队在重构基于 Next.js 的 AI 检索增强系统（RAG）时，往往会踩入同样的坑：第一期为了快速上线，把向量检索、上下文拼接、提示词工程和流式渲染全都塞在同一个组件或 API 路由里。三个月后再次拓展功能时，没人敢动里面的几百行代码。复杂大模型 Web 应用开发如果缺乏持续的项目复盘与上下文管理决策记录（ADR），项目很快就会滑向“一次性工程”的深渊。
解决这个问题的办法不是继续堆砌抽象层，而是建立一套标准化上下文编排引擎，并把每次遇到的边界故障沉淀为可复用的结构化规则。
AI 上下文编排与客户端渲染架构
现代化 Next.js Web 应用必须在 React Server Components (RSC) 与 Client Components 之间划分清晰的上下文界限。Server 端专注于多源检索（如 Pinecone / Qdrant）与上下文裁剪，Client 端专注于状态管理与流式 Chunk 拼接。
通过将“上下文拼接”独立成离线可单测的编排管道，可以随时针对 Prompt 规则进行回归测试，而无需依赖复杂的端到端 UI 自动化。
生产级上下文编排与 Next.js 流式响应实现
下面提供一个标准的 Next.js Server Action 编排器实现，展示了上下文窗口截断、历史纪录压缩与自定义 Stream 吐出机制。
// app/actions/orchestrator.ts
'server-only';
import { createCustomEncoder } from './tokenizer-utils';
export interface MessageContext {
role: 'system' | 'user' | 'assistant';
content: string;
}
export interface SearchChunk {
id: string;
text: string;
score: number;
}
const MAX_CONTEXT_TOKENS = 3000; // 给 Prompt 上下文保留的硬 Token 上限
export class ContextOrchestrator {
/**
* 编排提示词上下文：合并系统规则、高相关度知识块与历史对话
*/
public async buildOrchestratedPrompt(
userQuery: string,
searchResults: SearchChunk[],
history: MessageContext[]
): Promise<MessageContext[]> {
const systemInstruction = `你是一个严谨的技术知识助手。
规则：
1. 优先根据参考知识回答。
2. 如果参考知识不足，直接告知不知道，严禁虚构事实。
3. 返回格式必须为 Markdown 且排版清晰。`;
let currentTokenCount = this.estimateTokens(systemInstruction) + this.estimateTokens(userQuery);
const selectedKnowledge: string[] = [];
// 1. 按相关度得分降序填入知识块，直到耗尽 Token 预算
const sortedChunks = […searchResults].sort((a, b) => b.score – a.score);
for (const chunk of sortedChunks) {
const chunkTokens = this.estimateTokens(chunk.text);
if (currentTokenCount + chunkTokens > MAX_CONTEXT_TOKENS) {
break;
}
selectedKnowledge.push(chunk.text);
currentTokenCount += chunkTokens;
}
// 2. 构造增强后的 System 提示词
const augmentedSystemPrompt = `${systemInstruction}\\n\\n[参考知识库]:\\n${selectedKnowledge.join(
'\\n—\\n'
)}`;
// 3. 筛选并截断历史对话
const prunedHistory = this.pruneHistory(history, MAX_CONTEXT_TOKENS – currentTokenCount);
return [
{ role: 'system', content: augmentedSystemPrompt },
…prunedHistory,
{ role: 'user', content: userQuery },
];
}
private pruneHistory(history: MessageContext[], maxTokensLeft: number): MessageContext[] {
const result: MessageContext[] = [];
let accumulated = 0;
// 逆序压入最近的历史，保证优先保留最新上下文
for (let i = history.length – 1; i >= 0; i–) {
const msg = history[i];
const tokens = this.estimateTokens(msg.content);
if (accumulated + tokens > maxTokensLeft) {
break;
}
result.unshift(msg);
accumulated += tokens;
}
return result;
}
private estimateTokens(text: string): number {
// 粗粒度估算：中文字符与英文 Word 换算比率
return Math.ceil(text.length * 1.2);
}
}
React 客户端流式渲染与状态消费组件
前端客户端通过 useRunner 式的自定义 Hook 处理 Chunk 追加与实时渲染，保证即使网络出现波动或 Chunk 乱序，UI 界面也不会产生闪烁。
// components/AIResponsePanel.tsx
'use client';
import React, { useState, useCallback } from 'react';
interface PanelProps {
onSearch: (query: string) => Promise<ReadableStream<Uint8Array>>;
}
export const AIResponsePanel: React.FC<PanelProps> = ({ onSearch }) => {
const [query, setQuery] = useState('');
const [output, setOutput] = useState('');
const [isStreaming, setIsStreaming] = useState(false);
const handleSubmit = useCallback(
async (e: React.FormEvent) => {
e.preventDefault();
if (!query.trim() || isStreaming) return;
setIsStreaming(true);
setOutput('');
try {
const stream = await onSearch(query);
const reader = stream.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunkText = decoder.decode(value, { stream: true });
setOutput((prev) => prev + chunkText);
}
} catch (err) {
setOutput((prev) => prev + '\\n[系统错误：数据接收中断，已尝试自动重连]');
} finally {
setIsStreaming(false);
}
},
[query, isStreaming, onSearch]
);
return (
<div className="w-full max-w-4xl mx-auto p-6 space-y-4">
<form onSubmit={handleSubmit} className="flex gap-2">
<input
type="text"
value={query}
onChange={(e) => setQuery(e.target.value)}
placeholder="请输入技术检索目标…"
className="flex-1 px-4 py-2 border rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500"
/>
<button
type="submit"
disabled={isStreaming}
className="px-6 py-2 bg-blue-600 text-white rounded-lg disabled:opacity-50"
>
{isStreaming ? '生成中…' : '检索'}
</button>
</form>
<div className="p-4 border rounded-lg bg-gray-50 min-h-[200px] whitespace-pre-wrap font-mono text-sm">
{output || '等待发起检索…'}
</div>
</div>
);
};
架构决策记录（ADR）复盘模版
将经验沉淀为工程规则的关键，在于每次发布后填写可复用的 ADR 文件。以下是一份生产环境复盘决策模板：
# ADR-20260816: AI 检索上下文裁剪与 Token 溢出处理规则
## 状态
已通过 (Accepted)
## 关联问题
– 生产环境中当向量数据库匹配到超过 5 篇长文本时，LLM API 频频报出 `400 Context Length Exceeded` 异常。
– 客户端在网络恶劣情况下极易丢失最后一个 Chunk 的数据终止符。
## 决策选项
1. **方案 A**：在客户端拦截过长 Query，截断用户输入。
2. **方案 B**：在 Server Action 层增加 Token 预算分配器，强行按优先级划分（System 规则 > 最新用户 Query > 向量知识块 > 历史对话）。
## 最终结论
选择 **方案 B**。用户输入必须保持完整性，在服务端通过预估算法按优先级装载知识块，确保任何情况下都不超过 3000 Tokens 硬边界。
## 规则变更记录
– 每次检索返回知识块限制为 Top-5。
– 历史对话只保留最后 3 轮交互。
项目推进速度不取决于临时写了多少新功能，而取决于之前踩过的坑有没有转化为当下可遵循的校验规范。
