Experience 与 Skill

模型写得好，不等于已经上线。先过 Review，再谈导出和执行。

任务完成后，通常能提炼出两类东西。一类是下次遇到类似情况时该怎么判断。另一类是可以交给 Agent 重复执行的做法。

PowerContext 把前者保存为 Experience，把后者保存为托管 Skill。两者都不能从模型输出直接变成已批准 Artifact。

两类对象的 Review 问题也不同。审核 Experience 时，要判断经验结论能否由引用的结果支持，以及它是否适用于相似情形。审核 Skill 时，要检查另一位 Agent 能否安全执行步骤，包括验证方法和权限边界。

​

Experience 与 Skill 的区别

​

Experience 保存判断

Experience 包含四部分。

situation
→ action
→ outcome
→ lesson

还是那道 OpenAPI 例题。

Situation: the public OpenAPI contract changed
Action: regenerate and inspect the checked-in client before tests
Outcome: the generated transport matched the contract
Lesson: inspect generated drift before running contract tests

它的用途是帮助后续请求在相似情境中做判断。已批准当前 Experience 可以作为 cited 证据进入 PreparedContext。

​

Skill 保存操作指导

托管 Skill 包含名称、供宿主判断何时发现它的 description、指令和校验检查。

Skill 不是普通 Memory。它不会进入 PreparedContext，也不会因为批准就出现在 Agent 的 Skill 目录。

​

共同的 Candidate 生命周期

两边都要先变成提案，再等人审。Candidate 先进入 Review。改提案看 version。批准后才出现 Artifact Revision。

Candidate 有自己的生命周期。pending 可以 inspect、修订、批准或拒绝。approved 是终态，必须有 result_artifact。rejected 也是终态，必须有拒绝原因，并且不产生结果 Artifact。

所有 Candidate 至少要引用一条精确 Source 或 Artifact 证据。Source 与 Artifact 引用合计当前最多 32 条。

​

Propose 与生成

提案可以从你手里交上去，也可以让模型根据证据起草。

​

类型化提案

你已经知道内容时，可以直接提交结构化提案。常用接口是 propose_experience 和 propose_skill。

这条路径不需要生成模型。结果仍然是待处理 Candidate。

​

模型驱动生成

模型可以基于有界证据生成 Candidate。常用接口是 generate_experience 和 generate_skill。

生成可能返回待处理 Candidate，也可能返回明确无变更。没有生成模型提供方时，操作在持久化 Candidate 前失败。

无论模型写得多好，都不会自动批准。

​

Candidate 版本不是 Artifact Revision

每次修订会创建 Candidate 的新提案版本。Review 写入必须提供 expected_version，确保决定的是刚才检查过的版本。

假设审核者读取 Candidate v1，另一个人先修订到 v2。

approve(expected_version=1) → conflict

正确处理方式是重新读取 v2，比较完整提案，再决定批准或拒绝。不要把预期版本机械加一。

修订是完整替换内容，不是局部更新。这样每个提案版本都可以独立审计。

​

批准是一笔事务

批准会在一个数据库事务中完成。它先锁当前待处理 Candidate，再验证 expected_version 和证据链，接着创建或修订 Artifact。对 Experience 还会更新 approved-head 搜索投影。最后把 Candidate 标为已批准，并记录精确 result_artifact。

最后一步失败时，Artifact 提交也回滚，不会留下“Artifact 已创建但 Candidate 仍待处理”的半个结果。

拒绝不创建 Artifact。它只记录终态决定和 reason。

“人工 Review”是产品治理契约，不是身份认证机制。Server 无法证明 API 调用者在生物意义上是人。部署方仍要通过认证、宿主权限和流程控制决定谁能调用批准或拒绝。

​

Experience 怎样进入召回

只有同时满足这些条件的 Experience 才能进入 PreparedContext。Candidate 已批准。它是该 Experience Artifact 的当前头版本。它与请求使用同一 Scope。搜索和 PreparedContext 构建器认为它与查询相关。

待处理、已拒绝和历史 Experience Revisions 都不会自动进入召回。

批准一个替换内容 Experience 后，旧 Revision 仍可精确读取，但默认召回只看新头版本。

​

Skill 的来源信息

模型驱动 Skill 生成有三类来源。

来源	直接证据
experience	一个或多个已批准 Experience Revision，可附加 Source
source	一个或多个精确 Source，并且 artifact_refs 必须为空
usage	精确目标 Skill Revision，加至少一条 Source。审核者负责确认 Source 是否真的记录了使用情况

新托管 Skill 批准对证据链有额外限制。Artifact 证据应来自 Experience，而不是另一个 Skill。

Skill 替换内容必须包含目标 Skill，并至少带一条有界 Source。Server 只校验引用形状，不判断 Source 文本能否支持关于使用效果的结论。这项判断留给审核者。模型不能只看旧 Skill 文本就自我改写成下一版。

​

批准、导出、执行

这三个动作必须分开。

approve Candidate
→ managed Skill Artifact Revision
→ explicit export or managed publish
→ host-local projection
→ host/user decides whether to execute

​

批准

批准只创建精确 Skill Revision，例如 skill/SKILL_ID@1。这时宿主文件系统没有变化。

​

导出

CLI 读取精确已批准 Revision，再生成 host-local 软件包。

SKILL.md
powercontext.json

powercontext.json 保存 agent 类型、精确 ArtifactRef 和渲染后 SKILL.md 的 SHA-256。托管 Artifact 仍是权威来源。目录只是可重建副本。

当前 CLI 导出目标只有 codex 和 claude_code。

不要从这两个目标推断 Hermes、OpenClaw、DSH、OpenCode 或 Pi 也支持托管 Skill 导出。

​

执行

PowerContext 不执行导出的 Skill，也不授予工具权限。宿主决定何时发现 Skill，用户或宿主策略决定是否允许运行其中的操作。

​

两种发布范围

CLI 直接导出是仅创建。目标目录已存在时拒绝覆盖。

Server-managed safe 发布是另一条路径。它只在投影仍由 PowerContext 管理、内容未漂移，并且状态为 unpublished 或 update_available 时允许创建或更新。

常见投影状态包括 unpublished、current、update_available、conflict、drifted 和 incompatible。

外部目录、本地手改内容、同 Artifact 多个投影，或比目标更新的已发布 Revision，都不能被静默覆盖。

​

托管、外部和内置 Skill

这三个名字容易混在一起。

类型	权威来源	如何进入宿主
托管 Skill	PowerContext 已批准 Artifact Revision	显式导出或托管发布
外部 Skill	宿主文件系统或 registry 软件包	扫描、resolve、导入或分支后进入 Candidate 流程
内置 Skill	某个集成随插件一起安装的静态 Skill	宿主安装配置安装

OpenCode、Pi、Codex 或 Claude Code 插件里自带 project-context Skill，不代表它们都支持托管 Skill 导出。两件事无关。

外部 Skill 导入或分支也不会自动获得已批准状态。它会生成新的托管 Candidate，等待 Review。软件包中的任意 scripts 或 assets 也不会跟着自动执行。

​

用 OpenAPI 案例走完生命周期

​

1. 准备证据

捕获契约测试结果 Source，并保留精确 SourceRef。

​

2. Experience Candidate

提交或生成下面这样的判断。

Situation: OpenAPI contract changed
Action: regenerate and inspect the client, then run contract tests
Outcome: generated transport matched the contract
Lesson: inspect generated drift before tests

​

3. Review

读取 Candidate v1，修订 lesson 得到 v2。故意用 expected_version=1 批准，应得到冲突。重新读取 v2 后再批准，得到 experience/EXPERIENCE_ID@1。

下一次相关 prepare_context 可以召回这个已批准 Experience。

​

4. Skill Candidate

以 Experience Revision 为来源生成。

name: powercontext-openapi-change
validation:
  - api generation check passes
  - contract tests pass

批准后得到 skill/SKILL_ID@1。

PreparedContext 仍然不包含它。这是正确行为。

​

5. 导出

把精确 @1 分别导出到支持的宿主目录。检查 SKILL.md 内容，并确认 powercontext.json 引用同一个精确 ArtifactRef。

手工修改 SKILL.md 后再 inspect，状态应变成 drifted，safe 发布不得覆盖。

​

常见错误

​

生成成功后，Review 收件箱是空的

操作可能返回无变更。检查响应，不要假设每次生成都创建 Candidate。

​

已批准 Experience 没被召回

检查 Scope、是否为当前头版本、查询相关性和 PreparedContext 字节预算。

​

Skill 已批准，但 Agent 看不到

批准不导出。确认你使用精确 Revision 导出到了当前宿主实际扫描的目录。

​

导出报目标目录 exists

CLI 直接导出不覆盖。先检查目录是外部、托管当前、update 可用还是发生漂移的，再选择保留、换目录或使用受控托管发布。

​

替换内容 Candidate 一直冲突

目标 Skill 可能已经推进到新头版本。重新读取当前目标和 Candidate，不要修改预期版本后盲重试。

​

怎么知道分清了

1. Candidate 版本和 Artifact Revision 是两套号。
2. 提案和生成都停在待处理或无变更。
3. 批准和拒绝都绑定已检查的 expected_version。
4. Experience 召回只看已批准当前头版本。
5. Skill 始终不进入 PreparedContext。
6. 批准、导出、执行是三步。
7. 当前导出目标只写 Codex 和 Claude Code。
8. 本地漂移和冲突会阻止覆盖。

心智模型到这里已经完整。下一步进入安装并运行 Server，用真实 ID、Citation 和 Revision 练习这些对象。

​

下一步

启动本地 Server

先写出一条 Memory，搜到它，再拿到带 Citation 的 PreparedContext。

开始第一条闭环

走完一次 Review

用精确证据提交 Candidate，核对 version，再决定批准或拒绝。

开始 Experience / Skill Review