PowerContext 入门：理解上下文如何保存与复用
发布于
PowerContext 入门：理解上下文如何保存与复用
PowerContext 可以先用一句话理解：把 Agent 工作中值得保留的信息保存、整理起来，在后续工作需要时，再取出相关部分交给 Agent。
这里的“上下文”，就是理解和继续一项工作所需要的背景，例如项目约定、已经做出的决定、当前进度和待办。这篇笔记从一个具体场景开始，介绍这些信息怎样进入系统、怎样保存，又怎样回到 Agent。
1. 从一次跨会话工作开始
假设你正在让 Agent 开发一个订单系统。第一天，你们确定了两个约定：
-
金额统一使用整数分保存。
-
导入失败时，需要保留原始行号。
Agent 完成了 CSV 解析，金额校验还没有写。第二天，你打开一个新会话，说：“继续完成昨天的订单导入功能。”
要继续工作，新会话至少需要知道：这是哪个项目、之前确定了什么，以及现在做到哪里。如果这些信息只留在旧对话中，就需要你重新说明，或者让 Agent 重新翻找记录。
接入 PowerContext 后，可以把项目约定保存下来，把进度整理成交接内容。新会话通过同一个工作范围取回相关信息，再结合当前代码继续开发。
PowerContext 提供的是这条保存与复用的通路。实际采集什么、何时处理、何时取回，由所用集成、配置和调用方式决定，并不是接入后每段对话都会自动变成记忆。
2. 一套系统里，谁负责什么
常见用法是：Agent 通过客户端连接 PowerContext 服务端，服务端访问数据库，并按需调用模型。
| 角色 | 负责什么 | 在订单系统中的例子 |
| ------------------- | ------------------------------------ | -------------------------------------- |
| Agent | 理解任务、调用工具、执行工作 | 阅读代码，实现金额校验 |
| 客户端／插件 | 提交材料、发起操作、接收上下文 | 提交项目约定，请求与金额相关的背景 |
| PowerContext 服务端 | 接收和处理材料，管理制品，提供上下文 | 保存约定、维护版本、选择本次需要的内容 |
| 数据库 | 持久保存材料、制品、索引和处理状态 | 会话结束后仍保留已提交的信息 |
| 模型服务 | 按需提炼、总结，或生成检索向量 | 从一段工作记录中提取有用信息 |
3. 信息怎样进入系统
先把这四个概念放在一起看：Scope 管范围，Source 留材料，Artifact 存成果，PreparedContext 把相关成果带回本次任务。下面先从范围和信息入口讲起。
3.1 先确定工作范围：Scope
Scope 是上下文的隔离边界，通常可以对应一个项目、仓库、客户空间或长期任务。可以把它理解为一个项目档案空间：Source 和 Artifact 都归入相应范围，保存和读取之前，先确定“这次操作的是哪一份项目档案”。
同一个词，在不同项目里可以有不同含义。 假设国内订单和海外订单各自有一条金额约定：
Scope A（国内订单）：currency = CNY，金额单位为人民币分
Scope B（海外订单）：currency = USD，金额单位为美分
在没有配置跨 Scope 引用的情况下，对 A 查询 currency，取回的是国内订单的约定；对 B 查询同一个词，取回的是海外订单的约定。查询词相同，不会让两个项目的内容自动混在一起。
系统靠什么区分 Scope？ 服务端创建 Scope 后，会返回一个稳定的 scope_id。客户端保存这个 ID，后续用它指定工作范围。
一个 Scope 的核心信息可以这样看：
| 字段 | 含义 | 理解重点 |
| ---------------------- | -------------------- | -------------------------- |
| scope_id | 服务端生成的稳定身份 | 后续操作用它选择范围 |
| title | 给人看的名称 | 可以改名，不承担唯一身份 |
| summary | 范围说明 | 说明这里保存哪类工作背景 |
| parent_scope_id | 可选的组织父级 | 表示层级，不自动继承上下文 |
| context_references | 显式上下文引用 | 用于声明需要复用的其他范围 |
| version | Scope 元数据的版本 | 更新范围信息时用于并发控制 |
回到跨会话场景：会话可以更换，Scope 可以保持一致。 第二天的客户端继续使用同一个 scope_id，就能在有权限的前提下请求这个项目已保存的上下文，而不是从一份空白档案开始。
3.2 采集 Source：先保留原始材料
Source 为后续整理保存原始依据。 以常见的文本采集为例，客户端把工作中产生的内容提交给服务端，服务端在选定的 Scope 中保存这些材料。
提交的内容可以是什么？ 在订单开发过程中，可以提交：
| 材料 | 内容示例 | 后续可能用来做什么 |
| ------------ | -------------------------------------- | ---------------------- |
| 用户输入 | “金额统一使用整数分保存。” | 整理项目约定 |
| 任务结果记录 | 完成情况、代码变更说明、测试结果和待办 | 整理进度与交接内容 |
| 文档 | 订单接口文档中的字段说明 | 为理解字段含义提供依据 |
任务结果可以包含代码片段、命令输出和测试日志。具体保存多少细节，取决于客户端实际提交了什么。
提交一段文本，需要提供哪些信息？ 除了指定工作范围的 scope_id，常见的文本采集请求还包括：
| 字段 | 示例 | 作用 |
| ------------- | ------------------------------------------------ | -------------------------------- |
| source_id | orders-note-001 | 标识这份材料 |
| content | 金额使用整数分。CSV 解析已完成，金额校验待实现。 | 实际提交的正文 |
| metadata | {"origin": "user-input"} | 可选的附加信息，例如材料来自哪里 |
metadata 中的 origin 只是接入方约定的示例，不是系统要求的固定字段。
客户端负责取得并提交材料，服务端负责接收和持久化。Source 保存成功，表示材料已经入库；后续是否形成 Artifact，由相应的处理流程决定。
3.3 显式写入：直接保存明确的成果
有时你已经知道要保存什么，例如：“请记住，订单金额使用整数分。”调用方可以通过对应接口直接保存这条约定，不必先自动分析整段对话。
因此，信息进入系统有两条常见路径：
两条路径的关系是“从材料整理出成果”和“直接提交明确的成果”。不同制品支持的操作不同，不能假定每种类型都能手工创建或更新。
4. 信息怎样整理保存：Artifact
4.1 从材料到可复用成果
一段对话可能同时包含问题、尝试、失败和最终决定。后续工作通常只需要其中的某些信息。PowerContext 把具有明确用途、可以管理和复用的成果称为 Artifact（制品）。
例如，同一段订单开发记录，可以支持整理出两种成果：
-
项目约定：“金额使用整数分。”
-
交接信息：“CSV 解析已完成，下一步实现金额校验。”
前者适合长期记住，后者帮助接手当前任务。它们用途不同，因此属于不同的 Artifact 类型。
4.2 它不是“一个文件”
Artifact 可以导出为文件供其他工具使用，但在 PowerContext 中，它表示一份可复用成果的某个不可变版本快照。可以把它想成一份工作记录的某次正式提交：内容后来可以更新，已经提交的这一版仍然保留。
以交接记录为例，可以用下面的形式表示它的身份和版本：
family / artifact_id @ revision
handoff / handoff_123 @ 1
| 信息 | 含义 | 在这个例子中 |
| --------------- | -------------------------- | ------------------------------------- |
| family | 制品类型 | handoff，表示交接记录 |
| artifact_id | 同一份制品的稳定身份 | handoff_123，更新后仍是这一份记录 |
| revision | 这份制品的版本号 | 1，表示第一版 |
| content | 这一版的结构化内容 | 当前进度、待办等交接信息 |
| lineage | 形成这一版所依据的来源关系 | 相关 Source 或其他 Artifact 的引用 |
假设第一版记录“金额校验待实现”，后来这项工作完成了，更新同一份交接记录时，就会形成新版本：
同一份交接记录：handoff_123
revision 1：CSV 解析已完成，金额校验待实现。
revision 2：金额校验已完成，下一步补充边界测试。
artifact_id 没变，revision 从 1 前进到 2。第二版不会改写第一版，因此系统既能提供当前进度，也能按精确版本找回当时的记录。这些身份和版本信息都要放在相应 Scope 中理解。
4.3 几种主要类型
| 类型 | 主要回答的问题 |
| ------------ | ---------------------------- |
| Memory | 后续应该记住什么？ |
| Topic Memory | 一个长期主题发展到了哪里？ |
| Experience | 哪些经验值得复用？ |
| Skill | 下次可以怎样操作？ |
| Handoff | 工作做到哪里，接下来做什么？ |
| Profile | 有哪些相对稳定的背景？ |
这些类型共用 Artifact 的版本和引用基础，但内容结构、生成规则与使用方式各有区别。
4.4 服务端怎样组织处理
从 Source 生成 Artifact 时，Runtime 会按配置和触发条件组织处理：读取符合条件的材料，按需调用模型，校验输出，再按该类型的规则提交成果。
部分生成结果还需要审核。例如，生成的 Experience、Skill 提案会先进入 Candidate（候选提案），审核通过后才提交为正式成果。显式创建则走对应接口的校验与提交规则。
处理可以在后台发生。因此，“材料已接收”“成果已生成”“成果已获批”是不同状态，需要分别确认。
5. 信息怎样返回 Agent
5.1 新会话根据当前任务请求上下文
第二天，你打开新会话，说：“继续实现金额校验。”客户端可以围绕当前问题，在订单系统的 Scope 中请求相关上下文。
服务端会检索可用内容，再根据本次请求的选择规则和大小预算组织输出。数据库里保存的内容可能很多，但这次只需要与金额校验相关的部分。
这里要区分“找到相关内容”和“准备好给 Agent 的内容”：搜索命中之后，还需要选择、组织，并控制输出大小。
5.2 PreparedContext：本次任务的资料包
PreparedContext 是服务端为一次请求准备的临时上下文。 可以把它想成从项目档案中挑出来的一份任务资料包，包含选中的历史材料及其引用。
客户端收到资料包后，按宿主的接入方式把它提供给 Agent。Agent 再结合你的当前要求、现有代码和工具结果开展工作。
PreparedContext 有三个容易混淆的地方：
-
它是一次请求的临时输出，不会因此创建新的长期 Artifact。
-
大小预算限制本次返回的内容，不会删除原始材料或已保存的成果。
-
没有合适内容时，可以返回空结果；这不一定表示系统出错。
也不是所有 Artifact 都通过同一种方式使用。Memory、Experience 等可以参与上下文准备，Profile 需要显式选择；Handoff 通过交接流程读取，Skill 可以导出到宿主供其发现和使用。
5.3 把两天的工作接起来
现在可以把整个过程串起来：
这套系统由两个相连的过程组成：工作产生材料，材料形成可复用成果；新任务提出需求，相关成果再回到 Agent。
理解这条主线后，就能区分三个不同的问题：材料有没有保存，成果有没有形成，以及本次任务有没有取到并实际使用这些内容。
参考与源码入口
本文依据本地仓库的架构文档和实现整理。不同集成的采集与消费能力，以对应集成文档和实际配置为准。
-
管理上下文的架构与职责：各类内容的形成与消费方式。
-
选择接入接口：客户端、HTTP、MCP 与进程内 SDK。
-
Core 组合入口：Source、Artifact、Trigger 的基本组合。
-
Runtime 组装：运行组件和资源生命周期。
-
PreparedContext 组装：有界上下文的生成。