dr-gareth-roberts/context-engineering

 [](https://github.com/dr-gareth-roberts/context-engineering/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://nodejs.org) [](https://www.python.org) **大多数 LLM 应用将其 30–50% 的上下文窗口浪费在冗余、过时或无关的内容上。** 本工具包将上下文视为一个一流的工程问题——决定_哪些内容进入窗口_，并提供评分、缓存、质量监控、对抗性测试和多模型编排。 一个包含 **17 个 TypeScript 包（与 Python 完全对等）**、2,200 多个测试以及一个交互式浏览器内检查器的工作区。[浏览 Wiki →](./docs/wiki/Home.md) ``` flowchart LR IN([Items + Budget]) --> SCORE[Score] SCORE --> PLACE[Place] PLACE --> PACK[Pack] PACK --> GATE{Quality Gate} GATE --> TRACE([Trace]) ADAPT[Adaptive weights] -. learned .-> SCORE CACHE[Cache topology] -. ordering .-> PLACE MEM[(Memory / Providers)] --> IN GATE -. monitor .-> WATCH[Drift · Immune · Council] WATCH -. feedback .-> SCORE ``` 绿色路径 —— **打分 (score) → 放置 (place) → 装填 (pack) → 质量门禁 (quality gate) → 追踪 (trace)** —— 是 `ce-core` 中的核心流水线。虚线边代表为其提供输入并进行观察的子系统：学习到的权重会调整打分，缓存拓扑会对条目进行排序以实现前缀复用，而漂移/免疫/委员会层会监控输出并闭环。 ## 目录 - [问题所在](#the-problem) · [创新功能](#novel-features) · [包](#all-packages) - [快速开始](#quick-start) · [Context Inspector](#context-inspector-web-app) · [示例](#examples) - [安装](#installation) · [Python](#python) · [架构与文档](#architecture--docs) - [开发](#development) · [安全性](#security) · [贡献](#contributing) · [许可证](#license) ## 问题所在 每次 LLM 调用都有一个有限的上下文窗口。系统提示词、检索到的文档、对话历史、工具定义和用户查询都要争夺空间。天真的方法——截断最旧的消息——会不可避免地失败： - 在足够的轮次后丢失系统提示词 - 随机丢弃高价值的文档 - 将预算浪费在过时或冗余的条目上 本工具包提供了**决定装入什么内容的算法**：相关性和优先级评分、跨内容类型的预算分配、缓存感知排序、冗余消除、质量评分，以及之上的商议/监控层。 ## 创新功能 这些并不是对现有 API 的简单封装——它们是管理上下文的新功能： **专家委员会 (Council of Experts)** — 具有不同视角（批评者、架构师、用户拥护者）的多个 LLM 模型通过 [4 种结构化策略](./docs/wiki/Deliberation-Strategies.md)对问题进行商议：并行、辩论、阶梯式（防止锚定偏差）和德尔菲法（匿名并带有收敛检测）。 **对抗性上下文测试器** — 使用 [6 种攻击类型](./docs/wiki/Adversarial-Testing.md)对您的上下文流水线进行红队测试：矛盾注入、噪声泛滥、细微错误突变、权威欺骗、时间中毒和相关性稀释。在生产环境之前捕获漏洞。 **上下文免疫系统** — 将失败模式记录为指纹，并开发可在未来的 pack 中进行筛选的[抗体](./docs/wiki/Context-Immune-System.md)。单独的条目可能没问题，但某些_组合_是有毒的——免疫系统会学习这些。 **上下文编译器** — [声明您想要什么](./docs/wiki/Context-Compilation.md)，而不是如何安排它。为 Claude、GPT-5.4 和 Gemini 2.5 提供槽位、约束和针对特定模型的优化传递。就像针对不同架构的 C 编译器一样。 **上下文纠缠** — 用于多智能体系统的[发布/订阅网格](./docs/wiki/Multi-Agent-Entanglement.md)。当智能体 A 发现了某件事时，智能体 B 的下一次 `pack()` 会自动包含它——具有作用域传播、TTL 过期和预算感知注入功能。 **漂移检测器** — 在滑动窗口中监控 [6 个质量维度](./docs/wiki/Drift-Detection.md)（相关性、冗余度、多样性、密度、新鲜度、利用率）。当您的上下文在模型开始产生幻觉之前悄悄退化时发出警报。 **上下文时间旅行** — [上下文状态的 Git](./docs/wiki/Context-Time-Travel.md)。使用 5 种策略（并集、交集、最高质量、最高优先级、手动）进行检查点、回退、分支、比较和合并。 **语义边界分割** — 在语义边界（主题切换、结构标记、困惑度峰值）而不是任意的 token 限制处分割文档。混合分割器结合了结构、语义和困惑度信号以及边界保护。 **缓存拓扑优化** — 按波动性（静态/会话/请求）对条目进行排序，以便稳定的前缀在不同请求中保持不变。使用 Anthropic 的前缀缓存可减少高达 90% 的成本。 **因果图压缩** — 使用 [BEADS 任务图](./docs/causal-compaction.md)通过因果关系（而非新旧程度）来修剪对话历史。保护根本目标和任务结果，同时积极地从已关闭的任务中删除过程噪声。 ## 所有包 每个包都作为 [`packages/`](./packages/) 下的独立模块发布，并带有自己的测试，此外在 [`python/context_engineering/`](./python/context_engineering/) 下还有一个 1:1 的 Python 实现。 | 类别 | 包 | 用途 | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | **Core** | [core](./packages/ce-core/) · [providers](./packages/ce-providers/) · [memory](./packages/ce-memory/) · [cli](./packages/ce-cli/) | Pack、打分、diff、放置、质量、成本、缓存拓扑、BEADS 交接 | | **Multi-Model** | [council](./packages/ce-council/) · [entangle](./packages/ce-entangle/) · [router](./packages/ce-router/) | 专家辩论；智能体共享上下文；路由到最便宜的模型 | | **Quality** | [adversarial](./packages/ce-adversarial/) · [immune](./packages/ce-immune/) · [debugger](./packages/ce-debugger/) · [drift](./packages/ce-drift/) | 红队测试；从失败中学习；诊断输出；监控退化 | | **Optimisation** | [compiler](./packages/ce-compiler/) · [adaptive](./packages/ce-adaptive/) · [time-travel](./packages/ce-time-travel/) | 声明式编译；学习权重；检查点/分支/合并 | | **Integration** | [sdk-interceptors](./packages/ce-sdk-interceptors/) · [frameworks](./packages/ce-frameworks/) · [rag](./packages/ce-rag/) | OpenAI/Anthropic 封装；LangChain 中间件；信息增益检索 | | **Web** | [web-client](./packages/ce-web-client/) · [web-server](./packages/ce-web-server/) | [Context Inspector](#context-inspector-web-app) 应用 + Express 主机 | ## 快速开始 **将条目打包到预算中** —— 一切构建所基于的原语： ``` import { pack } from "@context-engineering/core"; const result = pack( [ { id: "system", content: "You are a helpful assistant.", priority: 10 }, { id: "docs", content: "API reference documentation...", priority: 7 }, { id: "history", content: "Previous conversation...", priority: 3 }, { id: "query", content: "How do I authenticate?", priority: 9 }, ], { maxTokens: 4096 } ); // result.selected — items that fit, scored and sorted // result.dropped — items that didn't make the cut ``` **组合完整的流水线** —— 按类型分配，优化缓存拓扑，基于质量进行门控： ``` import { pipeline } from "@context-engineering/core"; const result = pipeline(8000) .add(systemPrompt, tools, documents) .allocate([ { kind: "system", targetRatio: 0.15 }, { kind: "retrieval", targetRatio: 0.55 }, { kind: "conversation", targetRatio: 0.3 }, ]) .cacheTopology({ provider: "anthropic" }) .qualityGate({ minOverall: 0.5 }) .build(); ``` **召开专家委员会** —— 多个模型进行商议，然后进行综合： ``` import { createCouncil, ROLE_PRESETS } from "@context-engineering/council"; const council = createCouncil({ members: [ { id: "arch", name: "Architect", ...ROLE_PRESETS.pragmatist, provider: anthropic, }, { id: "sec", name: "Security", ...ROLE_PRESETS.critic, provider: openai }, ], strategy: "debate", rounds: 2, synthesizer: { provider: anthropic }, }); const result = await council.deliberate({ query: "Microservices or monolith?", }); ``` Python API 与此 1:1 对应 —— 请参阅 [Python](#python)。 ## Context Inspector (Web 应用) 一个交互式、**完全客户端**的检查器，构建于该工具包本身之上（React + Vite，在生产环境中由强化版的 Express 主机提供服务）。粘贴条目和预算，然后观察打包决策的展开： - **Token 预算栏** —— 准确查看哪些内容合适，哪些被丢弃，按类型分类 - **追踪时间线** —— 单步调试每个评分和放置决策 - **差异视图 (Diff view)** —— 逐项比较两个包 - **因果演练场** —— 直观地探索 BEADS 任务图压缩 ``` pnpm install pnpm dev # http://localhost:3000 — runs entirely in the browser, no API keys ``` `pnpm build && pnpm start` 通过位于 [`packages/ce-web-server/`](./packages/ce-web-server/) 中的 Express 主机提供生产构建版本，该主机添加了安全标头、速率限制、优雅关闭以及到后端的可选 `/api` 代理。 ## 示例 可运行的演示 —— 无需 API 密钥： | 示例 | 展示内容 | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | [RAG 聊天机器人](./examples/rag-chatbot/) | 检索 + 信息增益过滤 + 流水线打包 | | [代码审查委员会](./examples/code-review-council/) | 3 位专家通过收敛打分对 PR 进行辩论 | | [生产级智能体](./examples/production-agent/) | 漂移检测 + 时间旅行恢复 + 免疫系统 | | [因果压缩](./examples/causal-compaction/) | BEADS 任务图压缩 | | [上下文编译器](./examples/context-compiler/) | 声明式槽位、约束、针对特定模型的编译 | | [自适应权重](./examples/adaptive-weights/) | 从质量反馈中学习评分权重 | | [多智能体纠缠](./examples/multi-agent-entanglement/) | 智能体之间的发布/订阅上下文共享 | | [完整流水线](./examples/full-pipeline/) | 具有分配 + 质量门禁的完整流水线 | | [Webhook 遥测](./examples/webhook-telemetry/) | 将打包遥测流式传输到外部 endpoint | | [Node 基础](./examples/node-basic/) | 最小化的 Node.js 设置 | | [Python 基础](./examples/python-basic/) · [Python 流水线](./examples/python-full-pipeline/) | 最小化及完整的 Python 设置 | ``` npx tsx examples/rag-chatbot/index.ts npx tsx examples/code-review-council/index.ts npx tsx examples/production-agent/index.ts ``` ## 安装 该工具包目前**从源码**运行。注册表包（npm 上的 `@context-engineering/*`，PyPI 上的 `context-engineering-toolkit`）是预期的分发方式，并将在第一个标记的版本发布——在此之前，请克隆并构建。 **要求：** Node ≥ 20（`.nvmrc` 固定为 22） · pnpm ≥ 10 · Python ≥ 3.11 ``` git clone https://github.com/dr-gareth-roberts/context-engineering.git cd context-engineering # TypeScript workspace pnpm install pnpm build:all # Python (仅核心为 pydantic-only；以下为可选附加项) cd python pip install -e ".[dev]" ``` Python 核心仅依赖于 `pydantic`。可选的附加功能会拉取每个功能所需的内容：`providers` (httpx, tiktoken)、`server` (fastapi, uvicorn)、`cli` (jsonschema)、`logging` (structlog)、`redis`、`postgres` 或 `all`。请参阅 [`python/README.md`](./python/README.md)。 ## Python 该存储库附带了**同一工具包的两个实现**，保持了功能对等，以便您可以使用适合您技术栈的任意一种： | 位置 | 是什么 | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | [`packages/`](./packages/) | **TypeScript** 工作区 —— 17 个包 + Context Inspector Web 应用。参考源码。 | | [`python/context_engineering/`](./python/context_engineering/) | 这些包的 **1:1 Python 移植版** —— 相同的 API 和算法。这是发布的包。 | | [`python/context_framework/`](./python/context_framework/) | 基于该移植版构建的**应用型 Python 运行时** —— 领域流水线，不是已发布包的一部分。 | 相同的打包、打分、委员会、漂移、免疫、时间旅行和编译算法同时存在于两个技术栈中，因此下面介绍的概念和 API 形态可以在它们之间直接转换。 ``` from context_engineering import pack, ContextItem, Budget result = pack( [ ContextItem(id="system", content="You are a helpful assistant.", priority=10), ContextItem(id="query", content="How do I authenticate?", priority=9), ], Budget(max_tokens=4096), ) # result.selected / result.dropped ``` 除了对等层之外，[`python/context_framework/`](./python/context_framework/) 还提供了**应用型领域运行时** —— 将核心工具包连接到实际工作流中的参考流水线（安全运营、理赔处理、供应链、临床运营、药物警戒、电网停电、反洗钱、合同谈判等）。这些仅作为源码参考，不是已发布包的一部分。 ## 架构与文档 - **[Wiki](./docs/wiki/Home.md)** —— 架构概述和各功能的深入探讨 - **[Roadmap](./docs/roadmap/)** · **[Plans](./docs/plans/)** —— 未来的计划及原因 - **[Schemas](./schemas/)** —— 用于上下文条目、pack 和 BEADS 问题的 JSON Schema（由 `ce lint` 使用） - **[因果压缩](./docs/causal-compaction.md)** —— BEADS 任务图设计 ## 开发 ``` pnpm install && pnpm build:all # build all TypeScript packages + the app pnpm test:packages # all TypeScript unit tests pnpm check:all && pnpm lint # type-check + ESLint pnpm format # Prettier cd python pip install -e ".[dev]" python -m pytest # all Python tests ruff check . && pyright # lint + type-check ``` CI 在 Node 20/22 和 Python 3.11/3. 上运行完整矩阵，包含 ESLint、Prettier、ruff 以及一个阻断式的 pyright 门禁。Husky 的 pre-commit 钩子会对暂存文件进行格式化和 lint。请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 安全性 输入使用 Zod (TypeScript) 和 Pydantic (Python) 进行验证；文件存储使用原子写入和参数化 SQLite 查询；Web 主机设置安全标头和速率限制。要报告漏洞，请参阅 [SECURITY.md](./SECURITY.md)。 ## 贡献 欢迎 Issue 和 PR —— 请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 和[行为准则](./CODE_OF_CONDUCT.md)。在深入了解之前，请浏览 [Wiki](./docs/wiki/Home.md) 以获取架构上下文。 ## 许可证 [MIT](./LICENSE) © Dr Gareth Roberts

标签：DLL 劫持, LLM应用框架, Python, TypeScript, 上下文工程, 多智能体, 大语言模型, 安全插件, 无后门, 逆向工具