Context Engineering

wiki/ai/concepts/Context-Engineering.md

分类：ai / concepts · 更新：2026-08-03 09:06 最近更新

Context Engineering（上下文工程）

定义

系统性提升 AI 可消费上下文质量的工程实践。不是每次手动补 prompt，而是建立一次投入、持续生效的上下文基建。

核心公式

代码产出 = AI 能力 × 上下文质量

上下文质量是比模型能力更高效的杠杆，因为它完全掌握在团队手中。

五类上下文缺口

隐性规范 — 团队约定但未文档化的规则
历史决策 — 为什么选了A不选B
服务契约 — IDL 字段冻结状态、下游依赖
跨服务依赖 — 同一需求涉及的服务拓扑
演进轨迹 — 上次大改的坑和灰度策略

QQ音乐的三层知识体系

团队级 context/team/（所有项目遵循）
框架工程级 context/harness-framework/（所有需求研发遵循）
服务级 context/project/{project}/{module}/（特定服务）

与 LLM-Wiki 的关系

LLM Wiki 是个人层面的 Context Engineering——把知识编译一次、持续复用。QQ音乐的实践是企业级版本——团队层面的上下文工程。

2026-06-30 补充：AGENTS.md 作为仓库级上下文

AGENTS.md-Context-Files 代表一种轻量仓库级上下文标准：把 setup、测试、代码风格、约束和验证门禁放在 coding agents 可预测读取的位置。它符合 Context Engineering 的基本思想：把隐性规则变成版本化、可复用、可审查的上下文资产。

但 [[agents-md-context-files-paper Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?]] 提醒：context file 的效果需要实证评估。一个过长、过期或泛化的 AGENTS.md 可能只是在增加噪音。好的做法是短、准、可验证，并链接到更深的 wiki/spec/skill，而不是把所有知识塞进一个文件。

2026-07-02 补充：上下文工程的插件化

[[context-engineering-kit

Context Engineering Kit]] 展示了上下文工程从“写一份长规则”走向“按需加载插件”的趋势。关键不是 skills 数量，而是 token-efficient、granular、quality-focused：每个 plugin 只在相关任务中加载对应 agents、commands、skills，避免把无关知识常驻上下文。

这补充了本页的定义：Context Engineering 不只是整理上下文内容，也包括上下文的加载策略、粒度边界、标准化格式和反思/记忆闭环。对 Hermes 来说，好的 skill 应该像小型 workflow package：触发条件清晰、引用深入资料、可验证、可卸载，而不是一段泛化 prompt。

2026-07-03 补充：上下文应分为确定性结构、经验 playbook 与来源证据

[[enola-deterministic-codebase-architecture-graph

Enola]] 和 ACE/自学习 playbook 类项目共同提示：Context Engineering 不应只有一类“长文档”。更稳的分层是：确定性结构图负责代码事实；经验 playbook 负责可编辑策略；raw/source/wiki 负责来源证据；eval/harness 负责验证。

对 Hermes 来说，这意味着 skill 不应把所有上下文塞进 prompt，而应声明自己需要哪类上下文 provider：wiki 语义检索、仓库结构图、命令输出、用户偏好、历史决策或安全边界。

2026-07-04 补充：上下文层要测 adoption、determinism 与 token efficiency

[[agent-context-workshop

Agent Context Workshop]] 把 Context Engineering 进一步具体化为可实验的上下文 provider：同一组代码问题下，graph agent 与 grep agent 的单次准确率差距不大，但 graph 在重复运行确定性、关系问题稳定性、token efficiency 和 tool adoption 上更有价值。

这对本页定义很关键：上下文工程不是“准备了很多上下文”就结束，而是要回答三件事：agent 是否真的采用了该上下文；采用后是否减少重复推理和 token；多次运行是否更稳定。对 Hermes / llm-wiki 来说，wiki-vquery、wikilinks、raw provenance 和 index/log 都应被视为 context provider，并在任务报告里留下使用证据。

2026-07-06 补充：上下文治理层

[[contextnest-verifiable-context-governance

ContextNest / ContextNext]] 提醒：检索相关性不是上下文工程的全部。Agent 使用知识库前，还需要判断材料是否被批准、是否当前有效、版本和 hash 是否可追踪、输出到底消费了哪一版上下文。

对 llm-wiki 来说，这把 raw sha256、index/log、category selector、vector index 范围和 query evidence 都提升为治理对象。下一步不一定是重型企业系统，而是轻量 context manifest：记录一次重要回答或 ingest 实际使用了哪些页面、版本/mtime/hash 是什么、是否来自允许范围。

2026-07-07 补充：持久记忆要能证明自己减少重复探索

[[greplica-persistent-coding-agent-memory

Greplica]] 把 persistent repository memory 变成了可评测的 context provider：用 prior sessions 构建记忆，在未来 held-out session 的 planning task 上比较 baseline 与 memory arm，并衡量 plan quality、tokens、tool calls、时间和成本。

这对 Context Engineering 的定义很关键：上下文系统不是“资料越多越好”，而是要在任务开始时提供最小高信号历史，减少重复 grep/read/探索，并能通过对照实验证明自己 load-bearing。对 llm-wiki 来说，_index、wikilinks、raw provenance、wiki-vquery 和 ConversationSpec 也应该接受类似评估：是否真的帮助新 session 更快定位证据、减少重复搜索、降低幻觉。

2026-07-10 补充：workflow/context snapshot 也应成为知识对象

[[workflow-as-knowledge-semantic-persistence

Workflow as Knowledge]] 把 context engineering 的边界从“提供材料给模型”扩展到“记录 workflow 使用了哪些上下文、哪些步骤是确定性 derive、哪些步骤是 LLM infer”。对长期知识库而言，缺少 context snapshot 的回答很难复盘：即使结论正确，也不知道它消费了哪些页面、raw、搜索结果和工具证据。

这对 llm-wiki 的直接启发是：重要 ingest/query 不应只更新最终 page，还应在 log 或优化文章中留下最小 context manifest。hash、文件存在、wikilink 检查、向量重建是 derive；深度判断、概念综合、晋升/拒绝理由是 infer。把二者分开记录，能让未来的 Harness-Engineering 更容易验证、恢复和演化。

2026-07-11 补充：上下文压缩是 rate-distortion 决策

[[memory-compaction-rate-distortion-agents

What to Keep, What to Forget]] 把 KV cache、prompt pruning、architectural state 和 agent long-term memory 统一为 rate-distortion 问题：在预算下保留哪些上下文衍生信息、以什么保真度保留，以最小化未来任务损失。

这对 Context Engineering 很关键：上下文系统的目标不是“记得更多”，而是用有限 token/latency/storage/维护成本保留对未来任务最有用、最可追溯、最可恢复的信息。对 llm-wiki 而言，raw/source/concept/index/log/vector index 是不同保真度的 memory layers；每日雷达的“只深挖少数高价值材料”就是一种有意识的 compaction policy。

2026-07-12 补充：工具/技能 schema 也是上下文预算

[[ratel-context-engineering-tool-selection

Ratel]] 提醒：Context Engineering 不只管理文档、wiki 和 long-term memory，也管理工具与 skill schema 的加载。随着 agent 可用工具变多，全量注入会带来 token 成本、工具混淆和选择错误；更稳的做法是把能力放进 catalog，每轮只检索并暴露相关工具。

对 llm-wiki / Hermes 来说，skill 应逐步从“长 prompt 文档”升级为可索引 manifest：触发条件、输入输出、风险等级、验证方式、相关 wiki 页面。wiki-vquery 也可以从内容检索扩展到 capability retrieval，帮助 agent 决定下一步该加载哪个 skill 或工具。

2026-07-14 补充：仓库上下文需要可路由边界，而不是更长说明书

[[aigx-context-format AIGX]] 把仓库上下文组织成 .aigx/ genome 与 per-file boundary index，强调规则、禁止导入、gotchas 和模块边界应可被工具定位，而不是堆在一份长文档里。这补充了 AGENTS.md-Context-Files 的线性上下文模式：AGENTS.md 适合入口说明，AIGX 类结构更适合细粒度路由。

[[seta-scaling-environments-terminal-agents

SETA]] 和 [[execute-code-tool-surface-ablation

execute_code 工具面限制实验]] 也提示：上下文质量必须和任务环境、工具面一起评估。一个 context format 如果只在某种 harness/tool surface 下有效，就不能被当成通用改进。对 llm-wiki 来说，下一步可考虑给重要页面/skill 增加轻量 manifest：触发条件、边界、验证方式、相关页面。

2026-07-15 补充：上下文应由知识缺口驱动，而不只是关键词检索

[[acquire-qa-driven-repository-knowledge

ACQUIRE]] 把 coding-agent 的仓库理解显式拆成 question-driven knowledge acquisition：先问机制/行为、设计/用法、位置/结构、生态/标准四类问题，再用只读探索形成 evidence-grounded QA，最后才进入修复。它补充了本页的核心定义：Context Engineering 不只是“给 agent 更多上下文”，而是让每段上下文回答一个明确知识缺口。

对 llm-wiki 来说，这可以转化为 deep ingest 的前置合同：正式写页面前，先确认材料回答了什么机制问题、补充了哪个已有概念、证据来自哪里、哪些问题仍未回答。否则，检索命中和摘要流畅都可能只是低信号上下文。

2026-07-18 补充：上下文质量应作为独立 preflight 指标

[[context-fails-first

AI Agents Do Not Fail Alone]] 把 context quality 拆成七个可评分维度：role clarity、guardrail coverage、instruction consistency、tool schema quality、grounding sufficiency、injection hardening、token efficiency。它的价值在于把上下文质量从事后解释变成独立 leading indicator：先评价运行环境，再评价行为结果。

对 llm-wiki 来说，这可以转成页面/skill/cron prompt 的轻量 preflight：是否说明适用角色与边界，是否有足够来源和 wikilinks，工具 schema 是否清楚，是否避免把未验证/不可信材料混进执行上下文，是否控制 token footprint。

2026-07-19 补充：长期 wiki 需要任务级 Purpose Bundle

[[okfy-purpose-shaped-knowledge-bundles

OKFy]] 把 Context Engineering 的一个关键张力讲清楚：长期知识库为了 compounding 会不断变大，但具体任务需要的是按 Purpose 裁剪后的高信号工作集。上下文工程因此不只是检索 top-k，而是先定义“本次知识服务什么决策/任务”，再把相关概念、当前状态、已废弃内容、矛盾和来源证据压缩成 agent 可消费的 bundle。

对 llm-wiki 来说，_index.md、wikilinks 和 wiki-vquery 是发现层；正式回答或复杂 ingest 还应形成轻量 context manifest：本次使用了哪些页面/原始来源，哪些结论来自 deterministic check，哪些来自 LLM synthesis，哪些材料因过期/低相关被排除。这样可以减少 attention dilution，也让未来的 Harness-Engineering 更容易复盘。

2026-07-21 补充：上下文应通过只读委托与 fresh-context worker 控制噪音

[[fastcontext-read-only-repository-exploration

FastContext]] 提供了一个窄而实用的上下文模式：主 coding agent 不直接消费大量 grep/read 噪音，而是通过 bash 把问题委托给只读探索 agent，后者返回短、带文件路径和行号 citation 的答案。[[flow-next-agentic-engineering-workflow

Flow-Next]] 的 fresh-context worker 则说明，长程任务不应让一个 agent 带着所有历史上下文一路推进，而应按 task 重新锚定 spec、task 和 git state。

二者共同补充了 Context Engineering 的边界：上下文质量不仅取决于材料内容，还取决于探索噪音是否隔离、证据是否可定位、每个 worker 是否只加载当前任务需要的最小上下文。对 llm-wiki 来说，正式页面也应尽量从 raw/source 中提取 cited compact claims，而不是把所有原文摘要塞入概念页。

2026-07-23 补充：上下文仓库需要 routing map 与成熟度证据

[[harness-engineering-anthology Harness Engineering Anthology]] 展示了把方法论仓库做成 agent context bundle 的模式：README、AGENTS.md、docs、playbooks、sources 共同构成可路由上下文，而不是把全部内容一次性放进 prompt。对 llm-wiki 来说，_index.md 是人类导航入口，但还可以增加面向 agent 的 routing map：按任务说明该读哪些 concept/source/playbook、哪些页面只是背景、哪些需要验证 receipt。

[[akm-eval-agentic-knowledge-management

AKM Eval]] 则提醒，上下文工程的成熟度不能只看检索命中率或页面数量，而要看 agent 是否能找到适量正确知识，并有 artifact evidence 证明 context 被使用、验证和改进。未来 llm-wiki 的 context manifest 应能回答：本次任务用了哪些页面/raw，哪些结论有来源，哪些材料被排除，是否减少了重复探索。

2026-07-26 补充：上下文应由事实路由、代码图和预算证据共同控制

[[agent-graph-fact-routed-skill-workflows

Agent Graph]] 提醒，上下文加载顺序应从“先把规则塞进 prompt”改为“先读 host facts，选择当前 route，再加载该 route 需要的资源”。[[contextiq-ast-code-graph-agent-context

ContextIQ]] 则展示代码仓库侧的结构化上下文层：AST/code graph、task-specific context pack、auto-refresh、verify-plan/verify-output 与 savings ledger。

二者共同说明：Context Engineering 的下一步不是更多文档，而是更强的 context routing 和 adoption evidence。对 llm-wiki 来说，wiki-vquery 命中、页面读取、raw 来源、未读 dropped items、index/log/vector 更新，都应逐步进入轻量 context manifest；这样才能证明知识库真的减少重复探索，而不是只扩大可搜索内容。

2026-07-28 补充：上下文图谱要从页面列表升级为关系与任务拓扑

[[graph-engineering-agent-topology

Graph Engineering]] 提醒，Context Engineering 不只是把材料放进仓库，而是要管理实体、关系、事件、来源、融合和服务给 LLM 的路径。对 llm-wiki 来说，当前 markdown + wikilink + vector search 已经解决“能找到页面”，但还没有充分解决“为什么这些页面应该一起读、哪些关系是事实依赖、哪些只是宽泛相关”。

这给上下文工程增加一个轻量方向：不要急着引入重型图数据库，而是在 source/concept frontmatter、wikilinks 和 log 中更清楚地记录 candidate → source → concept → decision 的关系。任务层也应记录 split、verifier、stop rule 和 human gate，让复杂回答或 ingest 的 context topology 可复盘。

2026-07-31 补充：工程决策层与上下文预算

contexer-engineering-decision-layer 提醒上下文工程不只是文档检索，还包括“已决策事实”的捕获、批准、版本化和跨 agent 注入。对 coding agent，项目真正稀缺的上下文常常是为什么不能用某种方案、某个事故教训、某条团队约定的适用范围；这些不应每个 session 重新推理。

contextforge-deterministic-context-budget 则把 context window 明确当作预算：Shadow Index、tier routing、filesystem memory、failure ledger 和 output compression 都是在保护工作寄存器。对 llm-wiki 来说，全局知识库、repo-local decision store、raw/source provenance、任务级 context manifest 应分层使用；否则长期 wiki 会从复利资产退化为 attention dilution。

2026-08-01 补充：scope 是上下文治理的产品边界

qm-multiplayer-agent-harness 提醒，上下文工程不只是“把知识组织得更好”，还包括“谁在什么 scope 下能看到什么”。person、room、project 级 memory/files/keychain/permissions 把上下文从全局池拆成可治理工作区。forgeos-skill-intelligence-control-plane 的 isolated ContextPack 则提供了任务级版本：每个 work unit 只加载当前 route 需要的最小上下文，并把 deterministic steps 与 evidence ledger 分开。

agentdoctor-coding-agent-config-audit 从反面说明 context hygiene：.env、private key、stale instruction、过宽 MCP 都可能把错误材料或敏感材料推入 agent 工作记忆。对 llm-wiki 来说，category、raw/source/concept、ConversationSpec、wiki-vquery 查询范围和 cron prompt 都应显式成为 context boundary；每日 radar 应记录哪些材料进入正式页面、哪些只留 raw、哪些因来源/深度不足被排除。

2026-08-02 补充：长期记忆、事实路由与轨迹上下文

optmem-permanent-agent-memory 提醒，上下文工程的长期记忆层应是 append-only、可重建、可反查的，而不是把所有 session 经验直接混进常驻 prompt。agent-graph-fact-routed-skill-workflows 则把加载策略从“累积上下文”改为“由 host facts 选择当前 route 和资源”。axisagentic-runtime-trajectory-framework 补上 runtime trace：模型可见上下文、工具事件、评测 artifact 和 provenance 应成为可恢复/可回放的事实层。

对 llm-wiki 来说，这三者合起来给出一个更清晰的分层：raw/log 是 append-only 证据，source/concept 是可重构综合，wiki-vquery/index 是检索层，radar 报告是当前 route 的输出。每日任务应继续少量深挖，并记录候选为何晋升/拒绝，避免把检索噪音压缩成长期知识。

2026-08-03 补充：示范轨迹与 catalog rubric 也是上下文

record-and-replay-skill 提醒，上下文不只有文档和代码；用户演示产生的事件流、DOM snapshot、selector candidates、截图和 replay 结果，是描述 workflow intent 的高保真上下文。awesome-agentic-devops 则提醒，catalog rubric 本身也是 context：approval、trace、maturity 和 risk label 会影响 agent 是否应该加载某个工具。

对 llm-wiki 来说，正式页面可以继续压缩为概念综合，但 raw 层应保留高保真证据；雷达报告则应记录候选为何晋升或拒绝。这样可以把“材料内容”和“材料如何被选择/使用”都变成可复盘上下文。

写入记录

2026-08-03 09:00 CST：补充 Awesome Agentic DevOps、ultracodex、record-and-replay-skill、Claude Starter Kit 对 operator-safety catalog、agent-as-function、示范到 skill、tool-level gates 的启发。

2026-08-02 09:01 CST：补充 OptMem、AxisAgentic、Agent Graph、SimpleEnglish 对长期记忆、轨迹证据、事实路由 skill 和受控语言评测的启发。

2026-08-01 09:06 CST：补充 QM、ForgeOS、AgentDoctor 对 scope、ContextPack、context hygiene 和 llm-wiki context boundary 的启发。
2026-07-31 09:01 CST：补充 Contexer 与 ContextForge 对工程决策层、上下文预算、repo-local decision store 和 context manifest 分层的启发。
2026-07-28 09:00 CST：补充 Graph Engineering 对知识图谱、任务图、上下文关系质量和 llm-wiki candidate/source/concept/decision 链的启发。
2026-07-26 09:00 CST：补充 Agent Graph 与 ContextIQ 对 fact-routed context、AST code graph、context pack 和 adoption/savings evidence 的启发。
2026-07-23 09:00 CST：补充 Harness Engineering Anthology 与 AKM Eval 对 agent routing map、context bundle 和上下文成熟度证据的启发。
2026-07-21 09:01 CST：补充 Flow-Next、Harness Score、NeMo Relay、FastContext 对 agent workflow、harness scoring、runtime trajectory 或只读上下文探索的启发。

2026-07-19 09:04 CST：补充 OKFy 对 Purpose-shaped context bundle、context manifest 与 attention dilution 控制的启发。
2026-07-18 09:00 CST：补充今日 radar 对证据门控、上下文质量、技能安全或控制原语的启发。

2026-07-02 09:00 CST：补充 Context Engineering Kit 对插件化、按需加载和 token footprint 的启发。
2026-07-03 09:00 CST：补充 Enola/ACE 类项目对上下文 provider 分层的启发。
2026-07-04 09:00 CST：补充 Agent Context Workshop 对上下文 adoption、determinism 与 token efficiency 的评测启发。
2026-07-06 09:00 CST：补充 ContextNest/ContextNext 对上下文治理、版本身份、hash 和 consumption trace 的启发。
2026-07-07 09:00 CST：补充 Greplica 对持久仓库记忆、held-out planning benchmark 和 llm-wiki context-provider 评测的启发。
2026-07-10 09:00 CST：补充 Workflow as Knowledge 对 context snapshot、derive/infer 边界和 workflow 知识对象化的启发。
2026-07-11 09:00 CST：补充 memory compaction 的 rate-distortion 视角，明确上下文工程的预算、保真度和未来任务效用权衡。
2026-07-12 09:00 CST：补充 Ratel 对 tool/skill context footprint、按需工具选择和 capability retrieval 的启发。
2026-07-14 09:00 CST：补充 SETA、execute_code 工具面实验与 AIGX 对环境生成、工具面、仓库上下文格式的启发。
2026-07-15 09:02 CST：补充 ACQUIRE 对问题驱动上下文、知识缺口显式化和 deep ingest 前置合同的启发。