内容
# 通用上下文包（UCP）
**一种开放的格式，将庞大的问题讨论线程转化为小型、可验证的上下文包，供LLM代理使用。**
[](https://github.com/ucpcore/ucp/actions/workflows/validate.yml)
[](https://pypi.org/project/pyucp/)
[](https://pypi.org/project/ucp-mcp/)
[](https://pypi.org/project/ucp-gen/)
[](https://www.npmjs.com/package/@ucpcore/core)
[](./LICENSE)
版本：`0.1.0-draft` · 状态：草案 · [ucpcore.org](https://ucpcore.org)
---
## 30秒了解UCP
LLM不知道您的工作上下文，将一个596条评论的线程粘贴到提示框中并不是知识转移。UCP是一个JSON文档，包含了人员或代理当前需要了解的任务信息，包括引用的来源、哈希值和确定性渲染：
```
task.ucp.json
├── summary 当前情况，附带引用的来源
├── must_know 事实，按照重要性排名
├── decisions 已做出的决定，时间，状态
├── conflicts 矛盾，保持可见而不是合并
├── context_diff 自上次访问以来发生的变化
└── sources 每个声明都引用一个；每个声明都有SHA256哈希值
```
## 30秒体验UCP
运行一个自托管的服务器（REST + MCP over Streamable HTTP）：
```bash
docker run --rm -p 8080:8080 -e GITHUB_TOKEN=ghp_yourtoken \
ghcr.io/ucpcore/ucp-server:latest
# 或不使用Docker：uvx --from ucpcore-server ucp-server
```
将Cursor / Claude Code指向`http://localhost:8080/mcp`，或使用REST API（`POST /v1/generate`）；详见[`libs/server`](./libs/server/)。部署到localhost以外？设置`UCP_SERVER_API_KEY`并将其作为`Bearer`头部发送 - 参见[服务器安全说明](./libs/server/#security)。
或使用CLI直接生成一个包 - 默认情况下不涉及LLM，只涉及结构：
```bash
pip install ucp-gen
# JSON包：声明、决定、时间线、哈希来源
ucp-gen github pallets/flask#5961 -o task.ucp.json
ucp-gen jira PROJ-123 -o task.ucp.json # 需要JIRA_BASE_URL + token
# 或规范的LLM渲染，限制在1500个token内
ucp-gen github pallets/flask#5961 --markdown --token-budget 1500
# 可选：通过任何OpenAI兼容的端点添加语义理解
ucp-gen github pallets/flask#5961 --llm -o task.ucp.json
```
通过stdio MCP服务器将生成的包目录提供给代理：
```bash
pip install ucp-mcp
ucp-mcp --dir . # 暴露list_contexts / get_context / get_context_markdown
```
## 实测数据
在真实问题上的测量结果
相同的token估计器在两侧（~4 chars/token）；“原始线程”是您通常会粘贴到模型中的文本 - 标题、正文、评论、链接的PR正文。使用 [`tools/benchmark_context.py`](./tools/benchmark_context.py) 重现：
| 问题 | 评论 | 原始线程 | UCP |
|---|---|---|---|
| `microsoft/vscode#519` | 前596条评论中的200条 | ~18,500 | **~1,200** |
| `rust-lang/rust#158622` | 12 | ~4,450 | **~1,450** |
| `pallets/flask#5961` | 4 | ~800 | **~700** |
| `pallets/flask#5948` | 0 | ~500 | **~330** |
优势随着线程大小的增加而增长 - 一个长达十年的讨论可以压缩 ~15 倍，同时保留决定、冲突和出处。对于小问题，token计数相似，但包仍然是结构化的、哈希的，并且面向受众，而不是一堵文字墙。使用 `ucp-gen` 0.1.1，2026-07-05 生成。
## `--llm` 添加的内容
默认管道纯粹是结构性的：快速、确定性、不涉及模型。可选的 `--llm` 标志通过对任何OpenAI兼容端点的单次调用添加语义层 - `summary` 成为整个线程的综合，而不是其开头段落；模型标记为关键的评论将获得显著性提升；仅在文本中存在的决定和冲突将被提取到其结构化字段中。
在 `microsoft/vscode#519` 上测量 - 596 条评论，历时十年，其中 200 条适合该包（17 个来源，~1,623 个渲染 token）- 丰富的包捕获了 GitHub 没有的结构化字段。摘要解释了 *为什么* 功能从未构建：VS Code 团队拒绝了，因为列表和树高是硬编码的，社区依赖变通方法（缩放、自定义CSS），并且社区PR未被接受。冲突记录了关于 Electron 或 VS Code 硬编码样式的争议，双方都引用了特定的哈希评论。状态为 `rejected` 的决定记录了请求不在路线图上 - 仅在文本中声明的信息，对结构模式不可见。
保证不变。包仍然根据模式验证；每个LLM添加的声明必须引用包中存在的源ID（删除虚构的引用）；`generator.llm_model` 记录生成增强的模型；如果端点无法访问，生成器会降级为结构包，并带有警告。
## 问题
在AI能够帮助完成任务之前，某人（人类或管道）必须从Jira、Confluence、GitHub、Drive、CRM和ERP等处收集相关的文档、决定、约束和风险，并将它们粘贴到提示框中。
现有的标准解决了相邻的问题：
- **MCP** （模型上下文协议）规范了*访问*数据源。
- **RAG** 管道检索*相似*的块。
- **UCP** 规范了*理解*：一个可验证的、具有权限意识的、时间感知的包，包含了人员（或代理）当前需要了解的任务信息。
> MCP是管道，UCP是流动的内容。
## UCP的结构
```json
{
"ucp_version": "0.1.0",
"id": "urn:uuid:7f9c2e14-...",
"generated_at": "2026-07-05T13:40:00Z",
"generator": { "name": "context-os", "version": "0.2.0" },
"profiles": ["ucp-core", "ucp-temporal", "ucp-secure"],
"entity": {
"ref": { "system": "jira", "type": "issue", "id": "PAY-482",
"url": "https://acme.atlassian.net/browse/PAY-482" },
"title": "Migrate payment webhooks to v2 API"
},
"summary": { "text": "…", "sources": ["src-1", "src-2"] },
"must_know": [
{
"id": "mk-1",
"text": "Webhook signatures must use HMAC-SHA256; v1 keys are revoked on Aug 1.",
"salience": 0.97,
"confidence": 0.9,
"sources": ["src-3"],
"valid_from": "2026-06-12T00:00:00Z"
}
],
"decisions": [
{
"id": "dec-1",
"decision": "Keep idempotency keys in Redis, not Postgres",
"status": "accepted",
"decided_at": "2026-05-20T09:00:00Z",
"sources": ["src-4"]
}
],
"conflicts": [],
"context_diff": { "since": "2026-07-01T08:00:00Z", "changes": [] },
"sources": {
"src-1": { "system": "jira", "type": "issue", "title": "PAY-482",
"url": "…", "content_hash": "sha256:…" }
}
}
```
## 设计原则
1. **出处是强制性的。** 每个声明都链接到其来源。没有来源的声明在每个配置文件中都是无效的。
2. **时间是一等公民。** 声明带有有效性窗口；过时的事实与当前事实是可区分的。矛盾是可表示的，而不是被默默合并。
3. **具有权限意识。** 包声明其受众，并声明在组装过程中是否强制执行访问控制。包按受众设计。
4. **与LLM无关。** 规范的渲染算法将任何UCP转换为任何模型的确定性提示。显著性分数定义了在token预算下的截断顺序。
5. **向前兼容。** 消费者必须忽略未知字段。扩展使用命名空间键。模式在semver下演化。
## UCP为您提供什么
**结构。** 每个消费者 - 一个LLM，一个代理，任何应用程序 - 接收相同的可预测部分：正在发生什么（`summary`），您需要知道什么（`must_know`），为什么做出决定（`decisions`），什么与什么相矛盾（`conflicts`），自上次访问以来发生了什么变化（`context_diff`）。模型不会从文档转储中提取意义；意义已经布局。
**Token经济。** 一个任务的原始检索转储可能需要50-100K token；而UCP包在1-2K token内携带相同的可操作知识。在包内，每个声明的`salience`定义了确定性的截断顺序，因此在任何token预算下，噪声首先被丢弃，核心（摘要、冲突、差异）存活。
**可验证性。** 没有来源的声明在模式上是无效的。来源携带内容哈希。您可以审计的AI摘要是您可以信任的AI摘要。
**访问安全。** 包声明了谁组装了它，并证明每个源都经过了访问控制检查。
## 集成
**MCP（Cursor，Claude Code，任何支持MCP的代理）。** 自托管服务器使用Streamable HTTP；将其添加到 `mcp.json`:
```json
{
"mcpServers": {
"ucp": { "url": "http://localhost:8080/mcp" }
}
}
```
代理获得 `generate_context`, `list_contexts`, `get_context` 和 `get_context_markdown`，以及 `ucp_context` / `ucp_catchup` MCP提示 - 在Claude Code中，它们显示为 `/mcp__ucp__ucp_context` 斜杠命令。Cursor和Claude Code的 `/ucp` 命令文件位于 [`libs/server/clients`](./libs/server/clients/)。对于基于文件的workflow，`ucp-mcp` 通过stdio提供一个`.ucp.json`文件目录。
**REST.** `POST /v1/generate` with `{"source": "github", "ref": "owner/repo#123"}` 返回包JSON；`GET /v1/packages/{id}/markdown?token_budget=1500` 返回规范的渲染。参见 [`libs/server`](./libs/server/)。
**库。** 在您自己的代码中验证、解析和渲染包：
```bash
pip install pyucp # Python: import ucp
npm install @ucpcore/core # TypeScript
```
```python
import ucp
pkg = ucp.load("task.ucp.json") # 验证 + 解析
prompt = ucp.render(pkg, token_budget=1500)
```
## 行业中立的设计
理解任务的结构在任何地方都是相同的；只有内容不同。律师打开一个案件，工厂工程师打开一个工作订单，银行分析师打开一个应用程序，都需要相同的部分 - 事实、约束、决定、冲突、变化。UCP保持词汇表开放（`system: 1c`，`scada`，`ehr`，...），将特定于系统的字段放在`attributes`/`extensions`中，并保持强制性的核心（出处、时间、受众）与领域无关。
诚实的边界：**格式是通用的；构建器不是。** UCP定义了理解的产物是什么。从特定行业的系统中组装它 - 连接器、领域实体提取、排名 - 是生产者（如Context OS）竞争的地方。这是故意的：标准是开放的，工艺是市场的。
## 仓库布局
| 路径 | 内容 |
|---|---|
| [`SPEC.md`](./SPEC.md) | 规范性规格 |
| [`schema/ucp.schema.json`](./schema/ucp.schema.json) | JSON Schema（草案2020-12） |
| [`examples/`](./examples/) | 完整的示例包 |
| [`conformance/`](./conformance/) | 一致性测试套件（有效/无效包） |
| `libs/python` | `pyucp` - 模型、验证、规范渲染 |
| `libs/typescript` | `@ucpcore/core` - 类型、验证、规范渲染 |
| `libs/mcp-server` | `ucp-mcp` - 通过MCP提供包 |
| `libs/gen` | `ucp-gen` - 从GitHub问题和Jira票据生成包 |
| `libs/server` | `ucpcore-server` - 自托管生成服务（REST + MCP） |
## 一致性配置文件
| 配置文件 | 保证 |
|---|---|
| `ucp-core` | 有效的结构、实体、摘要、来源、每个声明的出处 |
| `ucp-temporal` | 有效性窗口、`context_diff`、`conflicts`在检测时填充 |
| `ucp-secure` | 声明受众、访问控制证明、审计参考存在 |
最小的生产者可以只提供`ucp-core`。参见 [SPEC.md §5](./SPEC.md)。
## 治理和贡献
规范在公开中演化：参见 [`GOVERNANCE.md`](./GOVERNANCE.md) 了解更改如何提出和接受，以及 [`CONTRIBUTING.md`](./CONTRIBUTING.md) 了解如何参与。
## 文档状态
这是发布给社区审查的**草案**。在 1.0.0 之前，预期会有破坏性更改。欢迎通过问题和拉取请求提供反馈。
