企业官网建设流程全解析

上下文组件工程实战：System Prompt、工具定义、检索文档与消息历史的系统化设计（Agent-Skills-for-Context-Engineering）

【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering

上下文（Context）是 Agent 在推理时可用的完整状态，它由系统提示词、工具定义、检索文档、消息历史与工具输出五类组件构成。本文基于 Agent-Skills-for-Context-Engineering 仓库中 context-components.md 这一核心技术参考文档，逐一拆解每个组件的设计要点：从系统提示词的分区结构与指令"高度"校准，到工具 Schema 与描述工程、检索文档的标识符设计与语义分块、消息历史的摘要注入、工具输出的观测掩码，再到上下文预算估算与渐进式披露落地。读完你将掌握一套可直接复用的上下文组件设计规范，并能借助仓库中 context_manager.py 与 description_generator.py 等源码把规范变成可运行的工具。

一、系统提示词工程：分区结构与指令高度校准

系统提示词是会话中最稳定、贯穿全程的上下文组件，它的组织方式直接影响 Agent 定位信息的速度与推理质量。

分区结构：用清晰的边界组织提示词

将系统提示词按明确边界划分为若干独立分区，是一种被广泛验证的组织方式。推荐的五段式结构如下：

<BACKGROUND_INFORMATION> Context about the domain, user preferences, or project-specific details </BACKGROUND_INFORMATION> <INSTRUCTIONS> Core behavioral guidelines and task instructions </INSTRUCTIONS> <TOOL_GUIDANCE> When and how to use available tools </TOOL_GUIDANCE> <OUTPUT_DESCRIPTION> Expected output format and quality standards </OUTPUT_DESCRIPTION>

这一结构有两个直接收益：一是让 Agent 能快速定位相关信息，避免在扁平长文本中反复检索；二是在高级实现中支持"选择性上下文加载"——例如按分区惰性注入，只把当前任务需要的分区放入上下文。仓库中 context-fundamentals/SKILL.md 进一步给出了一个完整示例：BACKGROUND_INFORMATION描述角色与项目背景、INSTRUCTIONS罗列编码规范类硬约束、OUTPUT_DESCRIPTION声明输出格式要求。注意，由于注意力呈 U 形曲线分布（中间位置的召回精度比两端低 10%–40%），安全约束、输出格式要求、行为护栏等关键内容应锚定在提示词的头部或尾部，绝不能放在长提示词的中段。

高度校准：在脆弱与含糊之间找到启发式平衡

"高度"（altitude）指指令的抽象层级。高度过低会硬编码脆弱逻辑，一旦条件变化指令即失效；高度过高则含糊到无法给出具体行为信号。文档给出了三种典型形态的对照。

过低（脆弱）：

If the user asks about pricing, check the pricing table in docs/pricing.md. If the table shows USD, convert to EUR using the exchange rate in config/exchange_rates.json. If the user is in the EU, add VAT at the applicable rate from config/vat_rates.json. Format the response with the currency symbol, two decimal places, and a note about VAT.

过高（含糊）：

Help users with pricing questions. Be helpful and accurate.

最优（启发式驱动）：

For pricing inquiries: 1. Retrieve current rates from docs/pricing.md 2. Apply user location adjustments (see config/location_defaults.json) 3. Format with appropriate currency and tax considerations Prefer exact figures over estimates. When rates are unavailable, say so explicitly rather than projecting.

最优形态提供了清晰的执行步骤，同时给每一步留出判断空间。仓库 SKILL.md 还补充了两条迭代原则：从最小集起步，根据实际观察到的失败模式增量补充指令，而不是预先堆砌所有边界情况；精选多样化的规范 few-shot 示例来示范期望行为，而非枚举每一种可能场景。此外要避免在同一提示词中混用不同高度的指令——"总是恰好用 3 个要点"这类超具体规则与"要友好"这类模糊指令并存会形成冲突信号，应按高度分层组织每个分区并保持内部一致。

二、工具定义规范：Schema 结构与描述工程

工具定义是连接确定性代码与不确定性 Agent 的契约层。Agent 只能通过描述文本来推断工具意图并生成调用，任何歧义都会成为提示词工程无法修复的失败模式。

Schema 结构：五个必填字段

每个工具应定义 name、description、parameters、returns 四类信息：

{ "name": "tool_function_name", "description": "Clear description of what the tool does and when to use it", "parameters": { "type": "object", "properties": { "param_name": { "type": "string", "description": "What this parameter controls", "default": "reasonable_default_value" } }, "required": ["param_name"] }, "returns": { "type": "object", "description": "What the tool returns and its structure" } }

描述工程：回答"做什么、何时用、返回什么"

工具描述必须回答三个问题：工具做什么、何时使用、产出什么——这三问恰好是 Agent 在工具选择时逐条评估的内容。应包含使用上下文、示例与边界情况。

弱描述：

Search the database for customer information.

强描述：

Retrieve customer information by ID or email. Use when: - User asks about a specific customer's details, history, or status - User provides a customer identifier and needs related information Returns customer object with: - Basic info (name, email, account status) - Order history summary - Support ticket count Returns null if customer not found. Returns error if database unreachable.

仓库在 tool-design/SKILL.md 中将此上升为四项原则：描述要精确陈述工具行为（避免 "helps with" 这类含糊用语）；给出直接触发条件与间接信号；逐参说明类型、约束、默认值与格式示例；文档化返回结构、成功示例与错误条件。工具命名遵循动词-名词模式（get_customer、create_order），跨工具保持参数名一致（始终用customer_id，不要有时id有时identifier）。还应在描述中为可恢复错误提供纠正格式示例、重试指引与缺失字段说明——一句只有 "failed" 的错误信息对 Agent 的恢复信号为零。

源码落地：从 Schema 生成到自动评分

tool-design/scripts/description_generator.py 将描述工程固化为可执行流水线，核心工作流是"定义 → 渲染 → 评分 → 生成错误模板"：

builder = ToolSchemaBuilder("get_customer") builder.set_description("Retrieve customer record", "Full details...") builder.add_parameter("customer_id", "string", "CUST-######", required=True) schema = builder.build() desc = generate_tool_description(schema) scores = ToolDescriptionEvaluator().evaluate(desc, schema)

ToolSchemaBuilder以链式 API 声明参数（支持required、default、enum）、返回值 schema 与错误码（如NOT_FOUND、INVALID_INPUT、RATE_LIMITED）。ToolDescriptionEvaluator则按五项准则自动打分：clarity（检测 "help/assist/thing" 等含糊词与 "it/this" 等指代词）、completeness（检查 Parameters/Returns/Errors 分区是否齐全）、accuracy（核对工具名与参数名是否出现在描述中，捕捉描述腐化）、actionability（检查 "Use when/Returns/Errors" 等可执行信号）、consistency（惩罚 camelCase 与 snake_case 混用）。ErrorMessageGenerator则生成结构化、可被 Agent 解析并据以纠正调用的错误消息。这套工具可直接用于工具集上线前的自动审计。

三、检索文档管理：标识符设计与语义分块

检索文档常是上下文中最大的消费者，其管理核心是"维护索引而非副本"——保持轻量标识符，用即时检索（just-in-time）按需把数据装入上下文。

标识符设计：让文件名本身承载语义

标识符应传达含义并支持高效检索。弱标识符如data/file1.json、ref/ref.md、2024/q3/report无法传达任何语义；强标识符如customer_pricing_rates.json、engineering_onboarding_checklist.md、2024_q3_revenue_report.pdf让 Agent 即使在无搜索工具的情况下也能直接定位相关文件，避免不必要的加载。

语义分块：在自然边界处切分

大文档的分块应保留语义连贯性，在章节标题、段落分隔、逻辑断点等自然语义边界处切分，而不是用任意字符数硬切导致概念被拦腰截断：

# Pseudocode for semantic chunking def chunk_document(content): """Split document at natural semantic boundaries.""" boundaries = find_section_headers(content) boundaries += find_paragraph_breaks(content) boundaries += find_logical_breaks(content) chunks = [] for i in range(len(boundaries) - 1): chunk = content[boundaries[i]:boundaries[i+1]] if len(chunk) > MIN_CHUNK_SIZE and len(chunk) < MAX_CHUNK_SIZE: chunks.append(chunk) return chunks

四、消息历史管理：轮次表示与摘要注入

消息历史是 Agent 的草稿板内存：追踪进度、维护任务状态、跨轮次保留推理。但对长任务而言它可能膨胀到主导上下文，必须在它挤占活跃指令前实施压缩。

轮次表示：结构化保留关键信息

每条历史消息应按统一结构表示，以便下游做摘要、截断或压缩：

{ "role": "user" | "assistant" | "tool", "content": "message text", "reasoning": "optional chain-of-thought", "tool_calls": [list if role="assistant"], "tool_output": "output if role="tool"", "summary": "compact summary if conversation is long" }

摘要注入模式：按固定间隔维持长程记忆

长对话按固定间隔注入摘要，以压缩中间轮次的低信号体量：

def inject_summaries(messages, summary_interval=20): """Inject summaries at regular intervals to preserve context.""" summarized = [] for i, msg in enumerate(messages): summarized.append(msg) if i > 0 and i % summary_interval == 0: summary = generate_summary(summarized[-summary_interval:]) summarized.append({ "role": "system", "content": f"Conversation summary: {summary}", "is_summary": True }) return summarized

文档强调应"循环式地精炼历史"：深层对话中已被调用的工具结果很少需要原样保留，应将陈旧的工具输出替换为紧凑摘要或引用，去除低信号体量。仓库实现 context_manager.py 中的truncate_messages展示了结构化截断策略：始终保留 system prompt、保留已有 summary 消息、用剩余预算装最新的消息（从尾部倒序填充）；estimate_message_tokens则按"内容 token + 每条约 10 token 的角色/格式开销"估算历史成本，用于决定是否触发压缩。

五、工具输出优化：响应格式与观测掩码

工具输出在 Agent 轨迹中常占据最大比例（仓库 claims/index.jsonl 中claim-context-optimization-tool-output-dominance记录了这一观察），因此优化工具输出往往带来最大的容量收益。

响应格式：用格式选项控制 token 用量

向工具提供"简洁/详细"双格式选项，由 Agent 按需选择：

def get_customer_response_format(): return { "format": "concise | detailed", "fields": ["id", "name", "email", "status", "history_summary"] }

简洁格式只返回关键字段（适合确认类场景），详细格式返回完整对象（适合需要完整上下文驱动决策的场景）。描述中应说明何时用哪种格式，让 Agent 学会自主选择。

观测掩码：用紧凑引用替换冗长输出

对冗长工具输出实施掩码，用紧凑引用替换完整内容，同时保留信息可访问性：

def mask_observation(output, max_length=500): """Replace long observations with compact references.""" if len(output) <= max_length: return output reference_id = store_observation(output) return f"[Previous observation elided. Full content stored at reference {reference_id}]"

context-optimization/SKILL.md 给出了三条选择性掩码规则：永不掩码当前任务关键观测、最近一轮的观测、活跃推理链中使用的观测、以及调试进行中的错误输出；3 轮之后掩码已把要点抽取进对话流的冗长输出，替换为[Obs:{ref_id} elided. Key: {summary}. Full content retrievable.]形式；立即掩码重复输出、样板头尾、已被摘要的内容。掩码的关键是保持可检索性——完整内容存储于外部，上下文中只留引用 ID，Agent 需要时可回取原文。

六、上下文预算估算与分配

Token 估算近似

规划阶段可用"英语每 token 约 4 字符"的粗估：

1000 words ≈ 7500 characters ≈ 1800-2000 tokens

这是粗糙近似，实际分词随模型与内容类型变化。仓库实现estimate_token_count（见 context_manager.py）直接采用len(text) // 4，其文档字符串明确警告：该启发式对代码（2–3 字符/token）、URL 与文件路径（每个斜杠、点、冒号都是独立 token）、非英文文本（常为 1–2 字符/token）会显著漂移。任何预算关键计算都必须使用厂商真实分词器（OpenAI 模型用 tiktoken，Anthropic 用其 token 计数 API），estimate_token_count仅用于开发期快速检查与日志。

预算分配：跨组件的典型区间

按组件分配上下文预算的参考表：

开发期应持续监控实际用量，建立各组件的基线分配。尤其注意工具定义在 JSON 序列化后通常膨胀 2–3 倍（括号、引号、冒号、逗号都各占 token）——10 个中等 Schema 的工具在发出第一条消息前就可能消耗 5,000–8,000 token，审计时应统计序列化后的 token 数而非源码行数。

源码落地：优先级感知的 ContextBuilder

仓库的ContextBuilder类实现了优先级感知的预算管理：add_section(name, content, priority, category)注册分区，build(max_tokens)按优先级降序装入分区直到预算耗尽。get_usage_report()输出总用量、利用率与状态，状态阈值与 context-optimization/SKILL.md 的压缩触发建议一致——利用率超过 70% 进入warning，超过 90% 进入critical，对应"在 70%–80% 利用率时触发压缩"的实践准则。高层入口build_agent_context组合了完整流水线：system（优先级 10）→ task（优先级 9）→ 即时检索文档（优先级 5），随后调用validate_context_structure检查空分区、超长、缺失 system/task 分区与重复内容。

七、渐进式披露实现：技能激活与引用加载

渐进式披露是"上下文是有限注意力预算"这一心智模型的直接落地：启动时只加载技能名与摘要，任务激活时才加载完整内容。

技能激活模式

def activate_skill_context(skill_name, task_description): """Load skill context when task matches skill description.""" skill_metadata = load_all_skill_metadata() relevant_skills = [] for skill in skill_metadata: if skill_matches_task(skill, task_description): relevant_skills.append(skill) # Load full content only for most relevant skills for skill in relevant_skills[:MAX_CONCURRENT_SKILLS]: skill_context = load_skill_content(skill) inject_into_context(skill_context)

引用加载模式

def get_reference(file_reference): """Load reference file only when explicitly needed.""" if not file_reference.is_loaded: file_reference.content = read_file(file_reference.path) file_reference.is_loaded = True return file_reference.content

引用加载模式保证文件只加载一次并在会话内缓存。仓库实现ProgressiveDisclosureManager（context_manager.py）正是这套模式的工程化：load_summary先加载摘要，load_detail按需加载细节文件（force=True可绕过缓存重读），get_contextual_info依据引用对象上的need_detail标志决定返回摘要还是全文。

SKILL.md 将渐进式披露落地为三个层级：技能选择——启动时只加载名称与描述，按需激活完整技能内容；文档加载——先加载摘要，任务需要时再取细节分区；工具结果保留——近期结果完整保留，旧结果压缩或淘汰。同时强调边界必须干脆：一旦技能或文档被激活就完整加载，而不是加载一半——部分加载产生的信息空洞会降低推理质量。还要警惕加载过度的反向陷阱：在每个"可能相关"的信号下都加载全部候选技能/文档，等于复现上下文塞满问题。应设置严格的激活阈值——技能只在任务明确匹配其触发条件时加载，而不是主题"近似相关"就加载。

八、常见陷阱清单

将上述设计原则落到实践中，需要特别警惕以下失败模式（详见 context-fundamentals/SKILL.md 的 Gotchas 章节）：

1. 名义窗口 ≠ 有效容量：宣称大窗口的模型在复杂检索/推理任务上可能远早于极限就退化。在自有退化测试证明之前，预算应低于名义窗口。
2. 基于字符的 token 估算会静默漂移：~4 字符/token 的启发式对代码、URL、非英文文本失效，预算关键计算必须用厂商真实分词器。
3. 工具 Schema 序列化后膨胀 2–3 倍：应审计序列化后的 token 数而非源码行数。
4. Agentic 循环中消息历史静默膨胀：每次工具调用都会把请求与完整响应追加进历史，20–30 轮迭代后历史可能吞掉窗口的 70%–80%。应为历史设置硬性 token 上限并主动触发压缩。
5. 中段关键指令丢失：U 形注意力曲线使中间位置的召回精度低于两端 10%–40%，安全约束与输出格式要求务必锚定首尾。
6. 渐进式披露加载过急：加载每个"可能相关"的候选会复现塞满问题，应设置严格激活阈值。
7. 指令高度混用：超具体规则与模糊指令并存会制造冲突信号，按高度分层组织分区。

九、与仓库其他技能的分工

上下文组件设计是概念层工作，仓库通过技能路由把操作层工作分派给专门的技能（详见 SKILL.md 的 Integration 章节）：诊断注意力失败、lost-in-middle、中毒与分心归 context-degradation；掩码、分区、前缀缓存与预算等 token 效率战术归 context-optimization；长会话压缩与交接摘要归 context-compression；大输出落盘与持久草稿板归 filesystem-context；工具描述与 Schema 编写归 tool-design。当需要验证压缩或掩码策略是否保真时，可参考 compression_evaluator.py 的探针式评估方法，按 accuracy、context_awareness、artifact trail、completeness 等维度量化信息保留程度。

本仓库还提供了可直接运行的验证工具：python skills/context-fundamentals/scripts/context_manager.py会构建一个示例上下文并打印 usage report（总 token、利用率、状态、逐分区 breakdown 与结构校验结果），是观察上下文预算分配与校验逻辑的最快入口。

【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering