# Application API 0.1 草案

> **受众**：业务应用团队
>
> **状态**：`[TARGET / DRAFT]`，尚未实现，不可 import，暂无兼容承诺
>
> **目标里程碑**：M3A 提供最小装配能力，M3B 补齐候选和事件投影；真实 reference example 通过后再讨论冻结 API

## 1. 先说明：现在能做什么，本文又是什么

当前框架已经能直接运行 Agent，并提供 Recursive 任务树、TaskProtocol、Context 授权、工具门禁、Artifact 解析、Validator、预算以及停止和恢复。业务也可以通过构造 `AgentRunner` 注入工具注册表、验证策略和 `ArtifactResolver`。

当前尚没有“应用”这一层稳定接口：没有应用 ID/版本、应用级角色隔离、Provider 注册、候选生命周期，也不能只凭一个 Trace 精确找回当初的业务装配。因此本文不是使用手册，而是业务团队和框架团队共同评审的接口合同草案。

本文所有类型都分为三类：

- `[CURRENT]`：代码中已经存在，可按现有文档使用。
- `[M2 TARGET]`：M2 计划实现的 TaskProgress 能力。
- `[M3 TARGET]`：M3 计划实现的应用装配、候选或投影能力。

本文中的结构示例是**设计记法**，不是 Python 代码。现在创建同名文件或执行 `from cyber_agent import AgentApplication` 都不会工作。

框架团队的代码证据、状态权威和责任边界见 [M1 应用框架设计基线](./application-framework-m1.md)。

## 2. 业务接入的心智模型

一套应用由一个不可变描述和若干可替换 Provider 组成：

```text
AgentApplication（声明“这是什么应用”）
  ├─ ApplicationRef（身份和版本）
  ├─ AgentRole[]（角色、Prompt、Skill、模型和子角色边界）
  ├─ ToolSet[]（允许使用哪些业务工具）
  ├─ TaskContextProvider（有哪些业务资料可供授权）
  ├─ ArtifactResolver [CURRENT]（如何可信地读取产物）
  ├─ CandidateRepository（候选内容如何存储、分叉和合并）
  ├─ QualityCheckProvider（有哪些确定性业务规则）
  ├─ RunEventProjector（如何投影业务数据库和 UI）
  └─ RunLimits（应用允许的资源上限）
```

应用只描述业务能力。框架负责校验描述、把它编译成现有 Runner/ToolRegistry/Validator 能理解的配置、固化本次运行的解析结果，并在恢复时验证完全一致。

应用不创建第二个 Runner，不接管 TaskProtocol，不直接修改 Trace，也不通过回调绕过工具确认或 Validator。

## 3. 公共草案对象

### 3.1 `ApplicationRef` `[M3 TARGET]`

应用版本的不可变引用，也是启动、恢复和审计时的身份。

| 字段 | 含义 | 约束 |
|---|---|---|
| `application_id` | 稳定应用 ID，例如 `creative.reference` | 由组织命名，不能依赖本地目录名 |
| `application_version` | 可部署、可解析的应用版本 | 同一版本的行为声明不可被原地改写 |
| `config_hash` | 解析后行为配置的 SHA-256 | 新 Run 由框架计算；续跑必须精确匹配 |

公共名称不带 `V1`。当它随 Trace 落盘时，序列化对象必须额外包含 `schema_version`。

### 3.2 `AgentApplication` `[M3 TARGET]`

不可变应用描述对象，回答“这个应用允许框架装配什么”。它不是 Runner，也不保存连接池、Token 或运行时客户端。

草案字段：

| 字段 | 含义 |
|---|---|
| `application_id` / `application_version` | 应用稳定身份 |
| `root_role` | 新 Run 的根角色 ID |
| `roles` | 应用命名空间内的 `AgentRole` 目录 |
| `tool_sets` | 可被角色引用的 `ToolSet` 目录 |
| `context_provider` | 业务资料枚举端口及其版本描述 |
| `artifact_resolver` | 现有只读 Artifact 解析端口 |
| `candidate_repository` | 候选内容和合并端口 |
| `quality_provider` | 确定性业务规则端口及其版本描述 |
| `event_projector` | 可选业务投影端口 |
| `run_limits` | 应用整体资源上限 |

应用描述在注册后不可变。要修改 Prompt、工具能力、规则或资源边界，应发布新的 `application_version`，不能替换相同版本的内容。

### 3.3 `AgentRole` `[M3 TARGET]`

角色属于应用命名空间，不再写入进程全局的同名 Preset。

| 字段 | 含义 |
|---|---|
| `role_id` | 应用内唯一角色 ID |
| `description` | 给装配器和根角色理解的职责说明 |
| `model` / `model_parameters` | 模型及影响行为的生成参数 |
| `prompt` / `prompt_hash` | 版本化 Prompt 引用及解析后 hash |
| `skills` | Skill ID、版本和顺序 |
| `tool_sets` | 角色可见的 ToolSet ID；子 Task 仍受父级能力交集限制 |
| `allowed_child_roles` | 此角色允许创建的子角色集合 |
| `default_validation_scopes` | 默认要求 Validator 检查的范围 |
| `run_limits` | 角色级限制，与应用和框架上限取最严格值 |

角色不能通过 Prompt 放宽工具、Context、预算、Artifact 或子角色门禁。Prompt hash 必须基于框架真正发送给模型的解析后内容，而不是只 hash 文件路径。

### 3.4 `ToolSet` `[M3 TARGET]`

应用级工具声明。它最终编译进现有 `ToolRegistry`，不会形成第二套注册表或执行器。

每项工具声明至少需要：

- 稳定工具名和输入 schema。
- 实现绑定的版本标识。
- 是否需要人工确认、哪些参数允许确认时编辑。
- URL policy；声明 URL pattern 时，调用上下文必须有匹配的 `page_url`。
- 副作用分类和幂等说明，供审计与崩溃恢复判断。
- 工具分组和可被哪些角色引用。

最终可执行集合仍由框架计算：应用声明、角色声明、父级转授、Run 级精确白名单和框架硬禁用项取交集。业务工具实现不得直接调用注册表的内部 dispatch 绕过这一步。

### 3.5 `TaskContextProvider` `[M3 TARGET]`

业务实现的资料枚举端口。Provider 回答“当前 Task 有哪些候选资料”，框架决定“哪些资料被授权、继承和放入模型上下文”。

Provider 的输入至少包含只读的应用引用、root/trace/task identity、当前 TaskBrief revision、父级已授权 ContextRef 和预算视图。输出的是资料描述，不是直接拼接后的 Prompt：

| 元数据 | 用途 |
|---|---|
| `source_id` / `source_version` | 稳定来源和版本 |
| `content_hash` | 内容寻址、去重和恢复校验 |
| `kind` / `mime_type` | 裁剪和渲染策略 |
| `inheritance` | 建议仅本 Task、允许逐边转授或禁止继承 |
| `priority` / `estimated_tokens` | 预算裁剪输入 |
| `authorization_metadata` | 供框架策略判断的业务归属，不等于已授权 |

框架把获准资料固化为现有 ContextSnapshot/ContextRef。Provider 不直接写 `TaskBrief.context_refs`，也不能返回另一个 root 或未获授权 Task 的引用。

### 3.6 `ArtifactResolver` `[CURRENT]`

继续使用现有名称和协议，不新增 `ArtifactReader`。业务实现可信、只读解析；框架负责校验引用、归属和 hash，并把合法材料交给 Validator。

当前权威签名位于 [`cyber_agent/core/artifacts.py`](../core/artifacts.py)：

```text
async resolve(
    ref: ArtifactRef,
    root_trace_id: str,
    uid: str | None,
) -> ValidationMaterial
```

业务 Resolver 必须：

- 以 `artifact_id + version` 读取不可变版本，不把“最新内容”冒充指定版本。
- 校验 root 和 uid 的访问权；越权使用确定性拒绝语义。
- 返回内容的 hash 与 ArtifactRef 完全一致。
- 区分不存在、暂时不可用和越权，不把所有错误吞成空内容。

上传、ACL 管理、索引和删除仍是业务存储职责，不进入 Resolver。

### 3.7 `CandidateRef` `[M3 TARGET]`

框架持有的不可变候选引用。候选内容仍在业务存储中。

草案最小信息包括：candidate identity、所属 application/root/trace/task、来源 ArtifactRef、parent candidate、revision、创建原因和生命周期阶段。每次内容变化产生新 revision 或新候选，不覆盖已被 Validator 或 TaskReview 引用的历史版本。

候选阶段只描述业务工作流中的 `draft / proposed / adopted / discarded` 等生命周期，不替代 Trace.status、ValidationResult 或 TaskReview。

### 3.8 `CandidateRepository` `[M3 TARGET]`

业务实现的候选内容端口，替代含义模糊的 `CandidateStore`。框架通过它执行以下受控能力：

- 创建不可变候选版本并返回内容 hash/ArtifactRef。
- 读取某个 CandidateRef 指定的精确版本。
- 从一个候选 fork 新候选并保留血缘。
- merge 候选，返回冲突而不是静默覆盖。
- 将已被父级采用的版本写回业务目标；写回必须幂等。

Repository 必须校验框架传入的 application/root/task 归属，不能仅凭 candidate_id 读写。框架负责 CandidateRef 和生命周期动作的合法性，Repository 负责内容、存储事务、冲突和业务写回。

### 3.9 `QualityCheckProvider` `[M3 TARGET]`

业务实现的确定性质量规则端口。它声明规则和可执行检查，框架把规则编译进现有 ValidationPlan 并统一调度。

每条规则至少声明：稳定 `check_id`、规则版本、适用 scope、所需材料类型、确定性执行器、失败说明模板和建议的 `retry_from`。例如“候选正文仍含 `{placeholder}`”可以是确定性规则，但“表达是否有感染力”仍应由 LLM Validator 评价。

约束：

- Provider 不直接写 ValidationResult；框架统一生成完整结果。
- Provider 不直接修改 TaskProgress 或 Candidate 生命周期。
- 回退建议只是 Validator 结果的一部分，父级仍通过 TaskReview 决定修订、重拆或上行。
- 新 Run 固化规则 ID、版本和配置 hash；续跑不能加载当前默认的新规则替换旧规则。

### 3.10 `RunEventProjector` `[M3 TARGET]`

业务实现的异步投影端口。它从现有 Trace 事件流按 cursor 消费，把权威状态投影到业务数据库、UI、通知或分析系统。

投影器必须满足：

- 以 application/root/trace 和 event_id 作为幂等键。
- 只提交连续 cursor；同一事件重复投递不能产生重复业务写入。
- 能在进程重启后从最后 cursor 重放。
- 对未知的新事件类型安全忽略或存入待升级队列。
- 投影失败只影响业务视图新鲜度，不回滚 Agent Trace，不阻塞已经完成的协议动作。

它不是同步 EventBus。业务不能把“投影成功”当作 Trace 状态转换的前置条件；确实需要参与事务的业务动作应建模为受门禁工具或 Repository 写回。

### 3.11 `RunLimits` `[M3 TARGET]`

应用可声明：模型轮次、递归深度、孩子数、并发孩子数、Token、成本、墙钟时间和单类资料大小上限。

有效限制为以下各层中最严格的一项：

```text
框架硬上限 ∩ 部署策略 ∩ AgentApplication ∩ AgentRole ∩ 本次 Run 请求可收紧值
```

本次 Run 只能收紧，不能放宽已经注册的限制。解析后的限制进入恢复快照；停止、重启和回溯不能重置已消耗资源。

## 4. M2 的 `TaskProgress` 如何被业务使用

`TaskProgress` 是 `[M2 TARGET]`，不是应用 Provider。业务 UI 可读，Agent 通过框架命令更新，业务代码不能直接写协议 context。

它只记录当前 Task 的推进事实，例如：

- `phase`：理解问题、收集证据、形成方案、生成候选、准备提交等推进阶段。
- `questions` / `blockers`：待确认问题和阻塞因素。
- `findings` / `hypotheses`：带 ContextRef/ArtifactRef 的结构化发现与假设。
- `work_items`：已经尝试、待尝试或放弃的工作项。
- `candidate_refs`：本 Task 当前产生或引用的候选。
- `decision_rationale`：简短、可审计的选择理由。

它不拥有 `completed/passed/failed` 终态，不复制 TaskBrief.target、ValidationResult 或 TaskReview.next_action，也不保存模型原始思维链。

## 5. 新 Run 与恢复合同

### 5.1 新 Run

框架按以下顺序创建应用 Run：

1. 按 `application_id + application_version` 解析不可变 AgentApplication。
2. 校验根角色、子角色图、工具、Provider 版本和 RunLimits。
3. 解析 Prompt/Skill、工具 schema、质量规则和行为配置。
4. 对规范化后的行为声明计算 `config_hash`。
5. 将完整 ApplicationRef、根角色/角色目录 hash 和解析后的行为配置加入 RunConfigSnapshot。
6. 创建 Trace 后才允许 Runner 进入模型循环。

### 5.2 续跑、人工确认、回溯和 compact

所有恢复入口都必须：

1. 先读取 Trace 中固化的 ApplicationRef 和 RunConfigSnapshot。
2. 从内部 Registry 解析完全相同的 `application_version`。
3. 重新计算并比对 config hash、角色 hash、工具和规则版本。
4. 一致后恢复 Provider 运行时对象，再进入现有恢复流程。

以下情况失败关闭：应用不存在、版本不存在、hash 不匹配、角色或规则缺失、Provider 无法恢复。框架不得用当前默认应用、最新 Prompt 或新规则继续执行。

业务请求在续跑时不能覆盖已固化角色、工具、模型、质量规则或 RunLimits。一次性的框架动作（例如现有 reflect/compact 的 side branch）仍由框架恢复协议控制。

### 5.3 config hash 包含与排除

必须进入 hash 的行为配置：

- 应用 ID/版本和规范化声明 schema 版本。
- 解析后的角色图、Prompt hash、Skill 版本和模型参数。
- 工具名、schema、实现版本、确认/可编辑参数和 URL policy。
- Provider 的稳定 ID、协议版本和影响行为的公开配置。
- 确定性规则 ID、版本、输入声明和配置。
- RunLimits、默认 validation scopes 和资料继承策略。

不得进入 hash 的运行时秘密：

- API key、密码、访问令牌和临时签名 URL。
- 数据库连接池、HTTP client、线程锁和进程对象。
- Provider 当前健康状态、缓存内容和监控指标。

秘密虽不进入 hash，但恢复时凭证缺失仍应启动失败，不能降级成另一数据源。

## 6. 内部装配概念，不是首版公共 API

下列名称用于框架实现和设计沟通，业务代码不应 import：

| 名称 | 内部职责 |
|---|---|
| `ApplicationRegistry` | 按 ID/版本定位不可变应用声明 |
| `ApplicationBinding` | 保存一次解析后的应用依赖、hash 和恢复材料 |
| `ApplicationRuntime` | 把 Binding 编译成现有 AgentRunner 的 RunConfig、ToolRegistry、ValidationPolicy 和 Resolver |

业务入口只需要提交应用引用和业务输入。内部结构未来可以重构，不作为 0.1 公共兼容面。

## 7. 失败语义

| 场景 | 预期行为 |
|---|---|
| 应用或版本不存在 | 新 Run 拒绝创建；恢复 Run 失败关闭 |
| config hash 或角色 hash 不匹配 | 拒绝恢复，报告不匹配对象，不自动迁移 |
| Context Provider 暂不可用 | 资料标记 unknown 或 Run 暂停/失败，不能返回伪空资料 |
| Artifact 不存在、暂不可用、越权 | 继续使用现有 failed/unknown/error 确定性映射 |
| Candidate 归属不匹配 | 拒绝访问并记录审计事件 |
| merge 冲突 | 返回结构化冲突，由 Agent/父级决定下一步，不静默覆盖 |
| 确定性质量检查异常 | ValidationResult 保持计划完整并失败关闭 |
| Event Projector 失败 | 保留 cursor，稍后重放；不修改权威 Trace |
| Provider 凭证缺失 | 应用装配失败，不切换到匿名或默认 Provider |

## 8. 业务团队的最小实现面

M3 能力完成后，一套新业务应用预计只需提供：

1. 一个版本化 AgentApplication 描述。
2. 根角色和必要的子角色 Prompt/Skill。
3. 业务工具及其 ToolSet 声明。
4. 一个 TaskContextProvider，将业务资料描述给框架。
5. 一个 ArtifactResolver，让 Validator 可信读取产物。
6. 需要多候选时实现 CandidateRepository。
7. 可确定执行的业务质量规则及 QualityCheckProvider。
8. 可选 RunEventProjector，将 Trace 投影到业务数据库和 UI。
9. 业务入口、最终写回和面向用户的输出解释。

业务团队不应：

- 修改 `AgentRunner`、TaskProtocol、TraceStore、Validator 或 ResourceBudgetController。
- 直接读写 `Trace.context.task_protocol` 或伪造 ValidationResult。
- 用全局 `AGENT_PRESETS` 动态注册多个应用的同名角色。
- 把真实业务数据塞进框架 Trace 来替代业务 Repository。
- 绕过 ToolRegistry 直接执行有副作用的工具。
- 将 Projector 当作同步事务钩子。

## 9. 从当前代码迁移到草案接口

| 当前做法 | 目标做法 | 里程碑 |
|---|---|---|
| 调用方直接构造 Runner 并注入依赖 | 用 ApplicationRef 解析应用并由内部 Runtime 构造现有 Runner | M3A |
| `AGENT_PRESETS` 全局注册角色 | AgentApplication 内的命名空间角色目录 | M3A |
| 手工把业务资料塞入 TaskBrief | TaskContextProvider 枚举，框架生成 ContextRef | M3A |
| 直接注册一组工具 | ToolSet 声明后编译进 ToolRegistry | M3A |
| RunConfigSnapshot 只保存 `project_name` | 同一快照固化 ApplicationRef、角色和解析配置 | M3A |
| ArtifactRef 只表示验证材料 | 原协议不变；ApplicationBinding 负责找到对应 Resolver | M3A |
| 没有候选权威模型 | CandidateRef + CandidateRepository | M3B |
| Validator 主要执行 LLM checks | QualityCheckProvider 增加版本化确定性规则 | M3A/M3B |
| 业务订阅开放字典事件 | 稳定事件 envelope + cursor Projector | M3B |

## 10. 接口进入实现前的评审清单

- 同一进程注册应用 A/B 时，角色、工具、Resolver、规则和候选是否完全隔离？
- 停止并重启进程后，能否只凭 Trace 解析到同一应用版本和行为配置？
- Provider 是否只描述业务资料/规则，所有授权、计划和结果是否仍由框架控制？
- CandidateRef 是否能证明 root/task 归属和血缘，Repository 是否校验这些边界？
- 确定性规则失败时，是否能只回退产物层而保留已验证证据？
- Projector 重放相同事件时，业务数据库是否保持一次效果？
- 业务应用是否无需修改 Runner、TaskProtocol、TraceStore 和 Validator？

用于证明这些问题的后续场景见 [reference example 验收合同](./application-reference-contract.md)。在该合同变成可运行测试前，本草案不构成兼容承诺。