Context-Engineering 仓库结构全景:从 Prompt Engineering 到 Context Engineering 的完整实践地图
Context-Engineering 仓库结构全景:从 Prompt Engineering 到 Context Engineering 的完整实践地图
这是一份围绕开源仓库 Context-Engineering 的"结构地图"(STRUCTURE.md)展开的技术指南。它回答了三个核心问题:这个仓库为什么要存在、它如何组织知识与代码、以及你该如何按图索骥从零基础走到前沿。读完本文,你将掌握一条从原子提示词(Atoms)一路延伸到神经场(Neural Fields)、协议壳(Protocol Shells)与元递归(Meta-Recursion)的完整学习路径,并能把仓库中每一层目录当作可直接复用的工程资产。
一、为什么会有这个仓库:Prompt Engineering 之外的"一切"
仓库的立身之本是 Karpathy 那句广为人知的定义:
"Context engineering is the delicate art and science of filling the context window with just the right information for the next step." — Andrej Karpathy
换句话说,Prompt Engineering 关心的是"你说什么"(单条指令),而 Context Engineering 关心的是"模型看到的其他一切"——示例、记忆、检索结果、工具、状态、控制流。仓库在 README.md 中用一个对比图把这个分野讲得很清楚:
Prompt Engineering │ Context Engineering
↓ │ ↓
"What you say" │ "Everything else the model sees"
(Single instruction) │ (Examples, memory, retrieval,
│ tools, state, control flow)
因此 STRUCTURE/STRUCTURE.md 作为这份仓库的"结构地图"(structural overview),定位是让读者以最快速度建立对整个知识体系的全局认知:它定义了目录的职责分工、规划了从入门到进阶的学习路径、并用一套"生物隐喻"把抽象概念具象化。本文将以这份结构文档为骨架,逐一展开每个模块,并结合仓库中的真实源码与配置进行印证。
二、领域地图:十个目录,各司其职
STRUCTURE.md 的第一张表定义了仓库的"版图"。以下是对照当前仓库实际内容核验后的目录职责表:
| 目录 | 职责(白话) | 第一性原理隐喻 |
|---|---|---|
| 00_foundations | 理论直觉,独立成篇的小型读物 | Atoms → Molecules → Cells → Organs → Neural Systems → Fields |
| 10_guides_zero_to_hero | 可运行、可修改、可拆坏的上手指南 | 化学实验台 |
| 20_templates | 可复制粘贴的即插即用片段 | 乐高积木 |
| 30_examples | 端到端迷你应用,逐个递增难度 | 模式生物 |
| 40_reference | 深度专题与评测手册 | 教科书附录 |
| 50_contrib | 社区贡献空间 | 开放实验台 |
| 60_protocols | 协议壳、Schema 与框架 | DNA 序列 |
| 70_agents | 使用协议的自包含 Agent 演示 | 干细胞培养 |
| 80_field_integration | 使用场协议的端到端项目 | 完整生物体 |
| cognitive-tools | 高级认知框架与架构 | 扩展神经系统 |
这张表的阅读价值在于:它不是一份随意的文件夹清单,而是一条"从理论到实现再到系统"的生产链。前四层(foundations → guides → templates → examples)构成主学习通道,后四层(protocols → agents → field_integration → cognitive-tools)构成进阶与前沿通道。
需要说明的是,STRUCTURE.md 作为架构文档,个别条目与实际仓库存在细微出入(例如指南目录中的文件实为 .py 脚本而非 .ipynb 笔记本、30_examples 当前仅落地了 00_toy_chatbot 一个示例)。本文一律以当前仓库实际内容为准,并会在相应小节给出修正。
三、学习路径:从 0 到 Zero 再到 Hero
STRUCTURE.md 规划了一条"理论 → 动手 → 应用 → 进阶"的四段式路径,这也是全仓库最有实操价值的导航。
3.1 理论基础:理解"上下文"到底是什么
- 通读 README.md(约 2 分钟):理解 context 超越 prompt 的含义。README 中给出了来自 1400+ 篇论文综述的定义:"Context 是推理时提供给 LLM 的完整信息载荷,包含模型完成给定任务所需的所有结构化信息组件。"
- 阅读 00_foundations/01_atoms_prompting.md(约 5 分钟):理解"原子"——一条独立的指令或示例,以及为什么单靠原子常常表现不佳。
- 沿生物隐喻链条继续阅读:
- 00_foundations/02_molecules_context.md:Few-shot 组合
- 00_foundations/03_cells_memory.md:记忆与日志
- 00_foundations/04_organs_applications.md:多步控制流
- 00_foundations/05_cognitive_tools.md:心智模型扩展
- 00_foundations/06_advanced_applications.md:真实世界实现
- 00_foundations/07_prompt_programming.md:类代码推理模式
- 00_foundations/08_neural_fields_foundations.md:上下文作为连续场
- 00_foundations/09_persistence_and_resonance.md:场动力学与吸引子
- 00_foundations/10_field_orchestration.md:协调多个场
从 00_foundations/README.md 可以看到,理论层实际已扩展到 14 个模块,超出 STRUCTURE.md 所列的 10 个,后续还包括 11_emergence_and_attractor_dynamics.md(涌现与吸引子动力学)、12_symbolic_mechanisms.md(符号机制)、13_quantum_semantics.md(量子语义)与 14_unified_field_theory.md(统一场论)。
3.2 动手实践:在做中学
-
打开 10_guides_zero_to_hero/01_min_prompt.py:运行、修改、观察 token 数量。该脚本中的每个实验节都在演示"多一行上下文为什么有帮助(或有害)"。注意:STRUCTURE.md 中将其写作
01_min_prompt.ipynb,实际仓库落地为.py脚本,可用python 01_min_prompt.py或 Jupyter 中%run 01_min_prompt.py运行。脚本内部定义了一个
SimpleLLM类作为演示接口,并规划了 5 组实验:- 实验 1(原子提示):
"Write a short poem about programming.",统计 token 数; - 实验 2(添加约束):对比原版、加行数约束版、加格式与词汇约束版(haiku、只用简单词),测量 token 与延迟;
- 实验 3(ROI 曲线):以占位质量分
[3, 6, 8]绘制 token-质量曲线; - 实验 4(最小上下文增强):给提示附加一句 haiku 定义与主题引导,观察质量提升;
- 实验 5(一致性测量):对基础与增强提示各采样 3 次,用占位一致性分做对比。
这个脚本的价值在于它示范了仓库一贯的方法论:用可量化指标(token、延迟、质量、一致性)驱动上下文设计决策。
- 实验 1(原子提示):
-
逐级实验进阶:
- 10_guides_zero_to_hero/02_expand_context.py:基本上下文操控
- 10_guides_zero_to_hero/03_control_loops.py:控制流与推理模式
- 10_guides_zero_to_hero/04_rag_recipes.py:检索增强策略
- 10_guides_zero_to_hero/05_prompt_programs.py:提示编程技术
- 10_guides_zero_to_hero/06_schema_design.py:Schema 设计原则
- 10_guides_zero_to_hero/07_recursive_patterns.py:递归上下文模式
3.3 应用技能:搭建真实系统
-
从 20_templates 复制模板作为项目起点:
- 20_templates/minimal_context.yaml:基础项目的最小上下文结构;
- 20_templates/control_loop.py:交互系统的控制循环;
- 20_templates/scoring_functions.py:评测打分函数;
- 20_templates/prompt_program_template.py:推理任务的程序化模板;
- 20_templates/schema_template.yaml:结构化数据的 Schema 定义;
- 20_templates/recursive_context.py:自改进系统的递归上下文(STRUCTURE.md 写作
recursive_framework.py,实际文件名以仓库为准); - 20_templates/neural_field_context.yaml:基于场的方法。
以 minimal_context.yaml 为例,它展示了"最小可用上下文"的完整解剖:
metadata(含token_budget: 800的目标 token 预算)、system(角色 + 能力 + 约束)、memory(enabled、max_turns: 3、pruning_strategy: "drop_oldest"及可选summarize/prioritize策略)、examples(few-shot 交换对,默认关闭)、evaluation(relevance/conciseness/accuracy 三类指标)、token_management(降本策略与内容优先级)、assembly(组装顺序与最终模板)。这一 YAML 本身就是一张"上下文工程的最小完备清单",任何项目都可以从复制它开始。 -
研读 30_examples/00_toy_chatbot:当前仓库落地的示例是完整的玩具聊天机器人,包含
chatbot_core.py.md、context_field.py.md、protocol_shells.py.md、meta_recursive_demo.py.md等带完整讲解的实现文件,展示了带上下文管理的完整系统。STRUCTURE.md 中规划的 data annotator、multi-agent orchestrator、cognitive assistant、minimal RAG、neural field orchestrator 等示例可作为后续扩展方向理解。
3.4 进阶主题:掌握这门手艺
-
探索认知工具与协议:
- cognitive-tools 中的高级推理框架;
- 60_protocols 中的协议壳与 Schema;
- 70_agents 中的 Agent 演示(当前仓库为 README 概览,STRUCTURE.md 规划的 residue scanner 与 self-repair loop 尚在演进中);
- 80_field_integration 中的完整场集成项目。
-
回馈社区:
- 查看 50_contrib/README.md 的贡献说明;
- 提交 PR 前对照 40_reference/eval_checklist.md 的评测清单自查。
四、生物隐喻演进:从原子到神经场的复杂度阶梯
仓库的组织核心是一套延展的生物隐喻,它把抽象概念具象化,并展示简单组件如何组装成复杂系统。STRUCTURE.md 给出了如下演进图:
┌───────────────────┐
│ Neural Fields │ 08_neural_fields_foundations.md
│ (Continuous │ 09_persistence_and_resonance.md
│ Context Medium) │ 10_field_orchestration.md
└───────┬───────────┘
│
▲
│
┌───────┴───────────┐
│ Neurobiological │ 05_cognitive_tools.md
│ Systems │ 06_advanced_applications.md
│ (Cognitive Tools) │ 07_prompt_programming.md
└───────┬───────────┘
│
▲
│
┌─────────────┴─────────────┐
│ Organs │ 04_organs_applications.md
│ (Multi-Agent Systems) │
└─────────────┬─────────────┘
│
▲
│
┌─────────────┴─────────────┐
│ Cells │ 03_cells_memory.md
│ (Memory Systems) │
└─────────────┬─────────────┘
│
▲
│
┌─────────────┴─────────────┐
│ Molecules │ 02_molecules_context.md
│ (Few-Shot Examples) │
└─────────────┬─────────────┘
│
▲
│
┌─────────────┴─────────────┐
│ Atoms │ 01_atoms_prompting.md
│ (Single Prompts) │
└───────────────────────────┘
这条演进路线与生物系统的复杂度递进一致,也对应了上下文工程方法论的成熟度:
- Atoms(原子):单条提示,是最小单元。参考 01_atoms_prompting.md 中的解剖:
ATOMIC PROMPT = [TASK] + [CONSTRAINTS] + [OUTPUT FORMAT]。它的局限也很明确——无记忆、演示能力有限、无复杂推理脚手架、易歧义、输出方差高。 - Molecules(分子):Few-shot 示例包,通过"给例子再提问"显著提升可靠性与控制力。
- Cells(细胞):记忆与日志,使交互具备状态与连续性。
- Organs(器官):多步控制流与多 Agent 系统。
- Neural Systems / Cognitive Tools(神经系统/认知工具):认知工具与提示程序(prompt programs)。
- Neural Fields(神经场):上下文作为连续语义介质,引入共振、吸引子、边界与涌现。
在 00_foundations/README.md 中,这套隐喻还被进一步扩展到三个互补视角:场视角(连续语义景观,关注吸引子/共振/持久性/边界)、符号视角(LLM 内部的符号抽象与归纳)、量子视角(意义作为观察者依赖的叠加与坍缩)。
五、三大高级框架:协议壳、认知工具与神经场
STRUCTURE.md 的第 4 节给出了仓库前沿部分的三大支柱。这一节是理解"这个仓库不止是教程"的关键。
5.1 协议壳框架(Protocol Shell Framework)
协议为编排复杂上下文操作提供了结构化外壳,定义在 60_protocols 目录中。STRUCTURE.md 给出的核心示例是递归场定义:
/recursive.field{
intent="Define field properties and operations",
input={
field_state=<current_state>,
new_information=<incoming_data>
},
process=[
/field.measure{resonance, coherence, entropy},
/pattern.detect{across="field_state"},
/attractor.form{where="pattern_strength > threshold"},
/field.evolve{with="new_information"}
],
output={
updated_field=<new_state>,
metrics={resonance_score, coherence_delta}
}
}
在 60_protocols/README.md 中,这种格式被正式命名为 Pareto-lang,标准结构包含 intent、input、process、output、meta(版本与时间戳)五个部分。仓库已落地的协议壳(60_protocols/shells 目录下均为 .shell.md 文件)包括:
attractor.co.emerge.shell:多吸引子协同涌现,关键操作含吸引子扫描、残渣浮现(residue surfacing)、协同涌现算法、场审计、边界坍缩;recursive.emergence.shell:递归场涌现与自主自提示,含自提示循环、残渣压缩、涌现检测、中止检查;recursive.memory.attractor.shell:通过吸引子动力学创建与维护记忆;field.resonance.scaffold.shell:共振脚手架,放大相干模式、抑制噪声;field.self_repair.shell:场的自修复机制;context.memory.persistence.attractor.shell:长程上下文持久化。
协议壳支持四种能力:声明式定义上下文操作、递归自改进模式、基于场的上下文操控、通过显式过程步骤实现可审计性。与之配套的是 60_protocols/schemas/protocolShell.v1.json 与 60_protocols/schemas/symbolicResidue.v1.json 等 Schema 文件,可用于对协议壳做 JSON Schema 校验;60_protocols/digests/attractor.co.emerge.digest.md 则提供了简化版说明。
以 attractor.co.emerge.shell 为例(shell 全文共 1116 行),它从两滴水珠合并的直觉讲起(Approach → Contact → Merge),引出语义场中吸引子协同涌现的概念,然后给出完整的操作流程、Schema 定义与使用场景。协议层的标准操作命名空间还包括吸引子操作(/attractor.scan、/attractor.strengthen、/attractor.create、/attractor.merge、/attractor.project)、残渣操作(/residue.surface、/residue.compress、/residue.integrate、/residue.echo)、边界操作(/boundary.collapse、/boundary.adapt、/boundary.tune、/boundary.reconstruct)、场操作(/field.audit、/field.partition、/field.snapshot、/field.evolution)与代理操作(/agency.activate、/agency.self-prompt、/agency.evolve、/agency.initiate)。
5.2 认知工具框架(Cognitive Tool Framework)
认知工具提供可复用的推理模式,用于扩展模型能力,集中在 cognitive-tools 目录。STRUCTURE.md 给出的目录骨架如下(已按实际仓库修正):
cognitive-tools/
├── cognitive-templates/ # 不同推理模式的模式模板
├── cognitive-programs/ # 类代码模式的结构化提示程序
├── cognitive-schemas/ # 知识表示格式
└── cognitive-architectures/ # 完整推理系统
实际仓库中:
- cognitive-templates:包含
understanding.md(理解操作)、reasoning.md(分析操作)、verification.md(校验操作)、composition.md(多工具组合); - cognitive-programs:
basic-programs.md、advanced-programs.md,以及program-examples.py、program-library.py两个 Python 实现; - cognitive-schemas:
user-schemas.md、domain-schemas.md、task-schemas.md、field-schemas.md与schema-library.yaml; - cognitive-architectures:
solver-architecture.md、tutor-architecture.md、research-architecture.md等完整推理系统架构。
该框架支持模块化推理组件、领域特定推理模式、与检索/记忆系统集成,以及推理质量评测指标。其研究背景是 IBM Zurich 的"cognitive tools"工作(以结构化提示模板作为工具调用来封装推理操作),仓库 README 中引用了其将 GPT-4.1 在 AIME2024 上 pass@1 从 26.7% 提升至 43.3% 的结果。
5.3 神经场框架(Neural Field Framework)
神经场把上下文表示为连续介质而非离散 token。STRUCTURE.md 给出的实现分布:
- 00_foundations/08_neural_fields_foundations.md:概念基础;
- 00_foundations/09_persistence_and_resonance.md:场动力学;
- 00_foundations/10_field_orchestration.md:多场协调;
- 20_templates/neural_field_context.yaml:实现模板;
- 以及模板目录中的 20_templates/field_protocol_shells.py 与 20_templates/field_resonance_measure.py(场属性测量)。
关键概念包括:上下文作为连续语义场、通过共振实现信息持久化、吸引子的形成与动力学、面向复杂任务的场编排。
六、Quiet Karpathy 风格指南:仓库的"风格 DNA"
STRUCTURE.md 总结了一套贯穿全仓库的写作与设计原则,称为 Keep it atomic → build up(保持原子化 → 逐步构建):
- 最小优先(Minimal first pass)——从最小可行上下文开始;
- 迭代追加(Iterative add-on)——只添加模型确实缺失的内容;
- 度量一切(Measure everything)——token 成本、延迟、质量分、场共振;
- 果断删除(Delete ruthlessly)——剪枝优于填充;
- 代码胜于幻灯片(Code > slides)——每个概念都有可运行的单元;
- 递归思考(Recursive thinking)——让上下文自我进化。
这套原则不是口号,而是可执行的工程纪律。举例来说,10_guides_zero_to_hero/01_min_prompt.py 的结论部分正是这条纪律的落地:即使向提示中做很小的追加,也能显著影响输出质量;token 数与质量之间存在 ROI 曲线;最小但战略性(minimal but strategic)的上下文能提升一致性;"最好"的提示是清晰、简洁、提供恰到好处上下文的提示。而在模板层,minimal_context.yaml 中 token_management.reduction_strategies(剪掉最旧对话轮、压缩详细示例、移除可选上下文段)与 priority 排序(当前用户查询 > 系统指令 > 最近对话历史 > few-shot 示例)就是"度量一切、果断删除"的可配置实现。
七、仓库结构细节:一份按当前仓库核验的目录树
STRUCTURE.md 第 6 节提供了完整目录树,但其中若干文件名与当前仓库实际不一致。以下是按当前仓库实际内容核验修正后的结构树(节选关键路径):
Context-Engineering/
├── LICENSE # MIT license
├── README.md # 快速上手总览
├── STRUCTURE/STRUCTURE.md # 本文所依据的结构地图
│
├── 00_foundations/ # 第一性原理理论(14 个模块)
│ ├── 01_atoms_prompting.md # 原子指令单元
│ ├── 02_molecules_context.md # Few-shot 示例与上下文
│ ├── 03_cells_memory.md # 有状态会话层
│ ├── 04_organs_applications.md # 多步控制流
│ ├── 05_cognitive_tools.md # 心智模型扩展
│ ├── 06_advanced_applications.md # 真实世界实现
│ ├── 07_prompt_programming.md # 类代码推理模式
│ ├── 08_neural_fields_foundations.md # 上下文作为连续场
│ ├── 09_persistence_and_resonance.md # 场动力学与吸引子
│ ├── 10_field_orchestration.md # 多场协调
│ ├── 11_emergence_and_attractor_dynamics.md
│ ├── 12_symbolic_mechanisms.md
│ ├── 13_quantum_semantics.md
│ └── 14_unified_field_theory.md
│
├── 10_guides_zero_to_hero/ # 上手指南(.py 脚本)
│ ├── 01_min_prompt.py # 最小提示实验
│ ├── 02_expand_context.py # 上下文扩展技术
│ ├── 03_control_loops.py # 流控机制
│ ├── 04_rag_recipes.py # 检索增强模式
│ ├── 05_prompt_programs.py # 结构化推理程序
│ ├── 06_schema_design.py # Schema 创建模式
│ └── 07_recursive_patterns.py # 自指上下文
│
├── 20_templates/ # 可复用组件
│ ├── minimal_context.yaml # 基础上下文结构
│ ├── control_loop.py # 编排模板
│ ├── scoring_functions.py # 评测指标
│ ├── prompt_program_template.py # 程序结构模板
│ ├── schema_template.yaml # Schema 定义模板
│ ├── recursive_context.py # 递归上下文模板
│ ├── neural_field_context.yaml # 基于场的上下文模板
│ ├── field_protocol_shells.py # 场操作模板
│ └── field_resonance_measure.py # 场属性测量
│
├── 30_examples/ # 落地示例
│ └── 00_toy_chatbot/ # 带上下文管理的对话 Agent
│
├── 40_reference/ # 深度文档
│ ├── token_budgeting.md # Token 优化策略
│ ├── retrieval_indexing.md # 检索系统设计
│ ├── eval_checklist.md # PR 评测清单
│ ├── cognitive_patterns.md # 推理模式目录
│ ├── schema_cookbook.md # Schema 模式合集
│ ├── latent_mapping.md / advanced_latent_mapping.md
│ ├── attractor_dynamics.md / field_mapping.md
│ └── emergence_signatures.md / symbolic_residue_types.md
│
├── 50_contrib/ # 社区贡献
│ └── README.md # 贡献指南
│
├── 60_protocols/ # 协议壳与框架
│ ├── shells/ # 协议壳定义(.shell.md)
│ ├── digests/ # 简化协议文档
│ └── schemas/ # 协议 Schema(JSON)
│ ├── protocolShell.v1.json
│ └── symbolicResidue.v1.json
│
├── 70_agents/ # Agent 演示
│ └── README.md # Agent 概览
│
├── 80_field_integration/ # 完整场项目
│ └── README.md # 集成概览
│
├── cognitive-tools/ # 高级认知框架
│ ├── cognitive-templates/ # 推理模式模板
│ ├── cognitive-programs/ # 结构化提示程序
│ ├── cognitive-schemas/ # 知识表示
│ └── cognitive-architectures/ # 完整推理系统
│
├── 00_COURSE/ # 在建的系统课程
│ ├── 00_mathematical_foundations/ # 数学基础
│ ├── 01_context_retrieval_generation/
│ ├── 02_context_processing/
│ ├── 03_context_management/
│ ├── 04_retrieval_augmented_generation/
│ ├── 05_memory_systems/
│ ├── 06_tool_integrated_reasoning/
│ ├── 07_multi_agent_systems/
│ ├── 08_field_theory_integration/
│ ├── 09_evaluation_methodologies/
│ └── 10_orchestration_capstone/
│
├── context-schemas/ # 上下文 Schema 演进(v1.0 → v7.0)
└── NOCODE/ PODCASTS/ SECURITY_RESEARCH/ 等附加内容
从这份树可以清晰看到仓库的三条主线:理论线(00_foundations)、实践线(10_guides → 20_templates → 30_examples)、前沿线(60_protocols → 70_agents → 80_field_integration → cognitive-tools),外加在建的 00_COURSE 系统课程与 context-schemas 的 Schema 演进序列(context.json → context_v7.0.json,每版都扩展了新的上下文维度)。
八、如何参与贡献
STRUCTURE.md 对贡献流程的约定非常简洁:
- 在 50_contrib 打开一个 PR;
- 提交前先跑 40_reference/eval_checklist.md 中列出的评测清单。
贡献时应遵循五条要求:
- 遵守 Quiet Karpathy 风格指南;
- 包含可运行的代码示例;
- 度量 token 使用与性能;
- 保持生物隐喻的一致性;
- 为新功能添加测试。
九、License 与归属
仓库采用 MIT 许可(见 LICENSE),无门禁:可复制、可再混合、可再分发。STRUCTURE.md 特别致谢 Andrej Karpathy 提出 "context engineering" 这一框架;文档中也写明:"所有错误归于我们,改进永远欢迎。"
结语:把结构地图变成你的工程起点
STRUCTURE.md 的真正价值不在于"展示目录",而在于给出了一条可执行的上下文工程成长曲线:先用 01_atoms_prompting.md 理解最小单元,再用 01_min_prompt.py 亲手测量 token 与质量的 ROI 曲线,随后用 minimal_context.yaml 快速搭建自己的上下文结构,最终借助 60_protocols 与 cognitive-tools 走向协议化、场化与自进化的前沿。沿着这张地图,你将从"设计提示词"进阶到"设计模型看到的整个世界"。