Agent/cyber_agent/docs/application-framework-m1.md

M1 应用框架设计基线

受众：框架团队内部

状态：M1 已批准设计基线；[CURRENT] 表示当前代码事实，[M2 TARGET] / [M3 TARGET] 表示尚未实现的后续目标

代码基线：dev_lsh@98713f26（2026-07-17）

1. 目标与边界

M1 解决的不是“马上发布一套新 SDK”，而是先回答三个问题：

1. 当前框架已经可靠地提供什么，真实缺什么。
2. 框架与业务应用分别拥有哪些状态和责任。
3. M2、M3 应在现有 Runner、Trace 和 Recursive 协议上增加什么，而不是重新实现什么。

最终目标是让业务团队只实现业务目标、资料、角色、工具、候选存储和质量规则，不修改 AgentRunner、Recursive 协议、TraceStore、Validator 或恢复机制。

M1 本身只交付文档和决策，不新增 Python 类型、运行时分支或公共导出。面向业务团队的接口仍是草案，见 Application API 0.1 草案。

本阶段明确不做：

• 脚本段落、账号人设、Pattern、脚本元素或 SQL branch 等业务模型。
• 第二个 Agent Loop、Workflow DSL 或同步 EventBus。
• 多租户、分布式运行、多 Worker 写入或远程 Recursive Agent。
• 在真实应用验证前冻结公共 API。

2. 当前能力就绪矩阵

状态含义：

• 已有：核心语义、持久化和关键门禁均已实现，并有专项测试。
• 部分：存在可复用实现，但尚未形成应用级装配合同，或缺少隔离/公共入口/专项测试。
• 缺失：没有可作为该能力权威来源的实现。

状态	能力	权威代码证据	自动化测试证据	当前持久化与限制	责任与后续
已有	Trace 生命周期与恢复	Trace、AgentRunner._prepare_new_trace/_prepare_existing_trace、RunConfigSnapshotV1	test_runtime_hardening.py、test_agent_mode.py	Trace meta、消息和带 hash 的运行快照落盘；Recursive 旧 Trace 无快照时拒绝不可靠恢复	框架权威；M3 将应用身份加入同一恢复合同
已有	Recursive 任务树	AgentPolicy、GoalTree、agent 调度	test_recursive_child_scheduling.py、test_recursive_subtree_cancellation.py	深度、每父孩子数、并发和父子 Trace 关系固化；Recursive revision 2 禁止 remote	框架权威；应用只决定业务任务内容
已有	TaskBrief / TaskReport / TaskReview	task_protocol.py、task_protocol 工具	test_task_protocol.py、test_recursive_replan_context.py	Trace.context.task_protocol 保存 Brief 版本、报告、审核、action 和 replan；Goal 只是投影	框架权威；M2 在同一协议状态中补 TaskProgress
缺失	Task 内部推进状态	当前只有 Brief、最终 Report 和父级 Review；new_task_protocol() 没有中间推进模型	无	没有可版本化的 blocker、question、finding、hypothesis、work item 或 candidate 状态	[M2 TARGET] 框架提供 TaskProgress 和结构化命令；应用填写业务内容
已有	Context 授权与逐边转授	ContextSnapshot/ContextRef 策略、read_context_ref	test_recursive_context_policy.py、test_recursive_context_integration.py	内容寻址快照绑定 root、uid、来源和版本；只允许父级已授权引用继续转授	框架执行授权；应用级资料枚举 Provider 仍缺失
部分	业务资料装配	TaskBrief.context/context_refs 和 ContextSnapshot 可承载资料，但资料仍由调用方手工组装	同上，只覆盖授权和限额，不覆盖 Provider 合同	没有来源目录、优先级、继承声明或应用版本入口	[M3 TARGET] 应用实现 TaskContextProvider，框架做授权、去重、裁剪和预算
部分	Agent 角色	AgentPreset/AGENT_PRESETS、AgentRunner._build_system_prompt	无独立角色目录/隔离测试	Preset 是进程全局可变字典；同名角色会跨应用污染；无应用归属和配置 hash	[M3 TARGET] 应用声明 AgentRole，内部 Runtime 解析并固化角色快照
已有	工具白名单与执行门禁	ToolRegistry、Recursive capability 交集和 Runner 的 runtime tool 计算	test_recursive_tool_capabilities.py、test_runtime_hardening.py	模型 Schema 与 dispatch 使用同一 allowlist；URL policy 和参数 hash 在执行前复核	框架权威；M3 的 ToolSet 只负责应用级声明，不新建执行器
已有	人工确认	ToolApprovalBatchV1、Runner 审批状态机和 Trace Run API	test_runtime_hardening.py、test_local_api_boundary.py	tool_approvals.json 持久化批次；整批等待；执行中崩溃标记 unknown，不自动重试	框架权威；应用只声明工具是否需确认及可编辑字段
已有	Artifact 引用与可信解析	ArtifactRef/ArtifactResolver、Validator 材料解析	test_recursive_validation_artifacts.py	引用包含 version/hash/kind；Resolver 校验 root 和 uid；框架不读取任意业务路径	框架保管引用和校验；应用实现 Resolver 与真实存储
部分	Artifact 应用接入	AgentRunner 构造函数可注入单个 artifact_resolver	Artifact 解析有测试，但没有应用注册或多应用隔离测试	Resolver 与某个 Runner 实例绑定，无法由持久化应用身份恢复	[M3 TARGET] 通过 ApplicationBinding 注入，继续复用现有 ArtifactResolver 名称
缺失	候选生命周期	ArtifactRef 能引用产物，但没有 candidate 身份、血缘、采用、暂存或放弃语义	无	无候选权威状态或审计事件	[M3 TARGET] 框架定义 CandidateRef 与生命周期；应用实现 CandidateRepository 的内容、fork/merge 和写回
已有	分层 Validator	ValidationPolicy/Plan/Result、Runner Validator 生命周期	test_recursive_validation_core.py、test_recursive_validator_lifecycle_complex.py、test_recursive_validator_web.py	Policy、settings、plan hash 和 Scope checkpoint 固化；结果必须覆盖计划内全部 check_id	框架权威调度和聚合；父级通过 TaskReview 决定去向
部分	确定性业务质量规则	编译器只对材料硬错误产生确定性检查；业务 completion criteria 仍是 LLM 检查	Validator 测试覆盖当前计划完整性，不存在业务规则 Provider 测试	无可注册的业务确定性执行器、版本或输入声明	[M3 TARGET] 应用实现 QualityCheckProvider；框架编译、固化版本并执行
部分	Trace 事件	TraceStore.append_event/get_events、events.jsonl、WebSocket 重放	test_runtime_hardening.py、test_local_api_boundary.py	事件有单 Trace 单调 event_id，但 event type/payload 仍是开放字典；没有应用投影 cursor	[M3 TARGET] 规范业务可消费事件并提供幂等 RunEventProjector；不引入 EventBus
已有	Recursive 树级预算	ResourceBudget/ResourceBudgetController	test_recursive_resource_budget.py	根 Trace 固化预算和累计用量；停止、回溯不退还已消耗资源	框架权威；M3 用 RunLimits 形成应用声明和框架硬上限的交集
部分	Memory / Knowledge	MemoryConfig、DreamScope、KnowledgeConfig	test_dream_security.py、Recursive runtime tests	Memory 以 uid/agent_type/memory_identity 隔离；Knowledge 仍通过 RunConfig/工具配置	框架可选能力；M3 只允许应用选择配置，不把业务数据库伪装成 Memory
缺失	应用注册与恢复	RunConfig 快照只有 project_name，Runner 直接持有 policy/resolver/registry 等依赖	只有 project runner 与快照恢复测试	无 application_id/version/config_hash，无法从 Trace 确定性恢复应用装配	[M3 TARGET] 内部 ApplicationRegistry/ApplicationBinding/ApplicationRuntime
缺失	应用接入合规测试	当前测试直接构造 Runner、Trace 或内置模型	无	没有业务实现必须通过的黑盒合同套件	[M3 TARGET] 先建立内部 contract tests；后续 M8 打包成业务接入套件

3. 状态权威

Recursive 任务存在多种“状态”，但每种状态只能回答一个问题。

对象	唯一回答的问题	权威写入者	禁止承担的职责
Trace.status	这次执行现在是否运行、等待确认、完成、失败或停止？	Runner / Run API	不表示业务 Task 是否被父级接受
Goal.status	当前 UI 和调度投影显示在哪个任务位置？	框架从协议动作投影	不作为 Recursive 协议真相，不自行级联父级或切换兄弟
RootTaskAnchor	整棵任务树最终要达成什么、有哪些根约束？	根 Run 创建者，框架固化	子 Agent 不得改写或重新概括
TaskBrief	当前 Task 被委派了什么、为何产生、交付和验收要求是什么？	直接父级提出，框架规范化和版本化	不记录执行中的变化
TaskProgress [M2 TARGET]	当前 Task 卡在哪里、确认了什么、准备尝试什么、有哪些候选？	当前 Task 通过框架命令更新	不拥有 completed/passed/failed 终态，不复制其他权威结果
TaskReport	子 Agent 正式提交了什么结果和未解决问题？	子 Agent 提交，框架注入 trace identity	执行者自检不能替代 Validator
ValidationResult	权威材料是否满足本次 ValidationPlan？失败应从哪一层重试？	Validator	不直接修改 TaskProgress，不决定父级最终动作
TaskReview	父级接受、修订、再拆分、重规划、上行还是失败？	直接父级，框架按决策矩阵校验	不伪造或覆盖 Validator 的 retry_from
RunConfigSnapshot	这个 Run 应按哪套行为配置恢复？	框架在新 Run 创建时固化	续跑请求不得覆盖行为字段

3.1 TaskProgress 的约束输入

M2 实现时必须遵守：

• 字段使用 phase，不使用含糊的 status。
• 通过 task_brief_version 引用当前 TaskBrief，不复制 target/objective。
• 通过结果引用关联 ValidationResult 和 TaskReview，不复制 review_result/next_action。
• 版本与 effective_at_sequence、消息 head 和回溯分支绑定；回溯产生新版本，不改写旧历史。
• Agent、工具、Validator 和父级只能通过各自获授权的命令写入，业务代码不得直接修改 Trace.context.task_protocol。
• 只保存问题、证据引用、Finding、方案、候选和简短 decision rationale；不保存模型原始思维链或隐藏推理文本。

4. 框架与应用责任边界

领域	框架负责	应用负责
任务	Task identity、父子关系、协议状态转换、版本和权限	业务目标、拆分理由、交付内容和验收标准
Context	引用授权、逐边转授、hash、去重、裁剪和 Token 预算	枚举可用业务资料，提供来源、版本、优先级和继承建议
角色	解析、校验、隔离、固化角色配置，执行模型与资源门禁	Prompt、Skill、业务角色定义和可创建的子角色关系
工具	Schema、allowlist、URL policy、确认、执行、结果和审计	工具实现、副作用声明、幂等性和业务输入输出 schema
Artifact	ArtifactRef、hash/归属校验和 Validator 安全读取	内容存储、ACL、上传、索引和 Resolver 实现
Candidate	identity、Run/Task 归属、血缘、生命周期和审计	内容、fork、merge、冲突处理、采用后的业务写回
Quality	计划编译、规则版本固化、调度、结果完整性和聚合	业务确定性规则、rubric 和规则所需业务材料
Event	规范事件 envelope、顺序、重放和投影 checkpoint	业务 DB/UI/通知/分析的幂等投影
Run	停止、恢复、回溯、配置快照、预算和错误语义	输入、最终输出解释和应用级默认限制

判断标准：替换为广告创作、游戏剧情或研究报告仍成立的是框架机制；只对脚本构建成立的是应用实现。

5. 内部 Application Runtime 目标形态

ApplicationRuntime 是现有 Runner 前的装配层，不是新的执行引擎：

业务入口
  → ApplicationRegistry 按 application_id + version 解析 AgentApplication
  → ApplicationBinding 校验并计算 config_hash
  → ApplicationRuntime 把角色、工具、Provider、规则和限制编译为现有依赖
  → AgentRunner 执行现有 Agent Loop
  → TraceStore 保存权威状态和事件
  → RunEventProjector 异步、幂等地投影业务视图

装配层必须遵守：

• AgentApplication 是不可变声明；Provider 是有行为的 Protocol 端口。
• ApplicationBinding 是本次 Run 解析后的内部快照，不允许业务代码在运行中替换。
• 新 Run 将 application_id/application_version/config_hash、角色 hash 和解析后的行为配置写入恢复快照。
• 续跑只解析相同应用版本；缺失或 hash 不一致时失败关闭。
• Provider 凭证、连接池、客户端对象和其他不可序列化运行时依赖不进入 config hash。
• ToolSet 编译进现有 ToolRegistry 权限计算；Artifact 继续使用现有 ArtifactResolver。
• 应用事件基于现有 append-only Trace events 投影；本设计不恢复历史 Decision 4 所反对的同步 EventBus。

6. 统一术语

名称	层级	决策
ApplicationRef	公共草案	应用 ID、版本和配置 hash 的不可变引用
AgentApplication	公共草案	应用声明，不是 Runner
AgentRole	公共草案	应用命名空间内的角色配置
TaskProgress	框架模型目标	M2 的任务推进状态，业务只读视图、命令式更新
TaskContextProvider	应用端口	枚举业务资料，框架执行授权策略
ToolSet	应用声明	编译进现有 ToolRegistry，不形成第二注册表
ArtifactResolver	已有应用端口	保留现名，不新增 ArtifactReader
CandidateRef	框架模型目标	不可变候选身份、归属和血缘
CandidateRepository	应用端口	替代 CandidateStore，强调内容存储由应用实现
QualityCheckProvider	应用端口	提供版本化的确定性业务规则
RunEventProjector	应用端口	按 cursor 幂等投影，替代含糊的同步 Handler
RunLimits	公共草案	应用声明限制，与框架硬上限取更严格值
ApplicationRegistry / ApplicationBinding / ApplicationRuntime	框架内部	M3 装配层，不进入首版公共 API

公共类名不带 V1；所有需要落盘、跨进程或恢复的结构和事件必须带 schema_version。Application API 在 M6 发布前均标记为 0.1 Draft，不承诺兼容。

7. 后续工程输入

M2：TaskProgress

• 在现有 task_protocol 权威状态内增加 sequence-bound、revisioned 的 TaskProgress。
• 定义 phase、问题、Finding、假设、WorkItem 和提交准备度；M2 只引用现有 ContextRef/ArtifactRef，CandidateRef 属于 M3B。
• 提供结构化命令和写入权限，不允许直接修改 context。
• 接入停止、续跑、回溯、Context 注入和 Validator 输入。
• 保持 ValidationResult 与 TaskReview 为独立权威结果。

M3A：Application Runtime 主干

• 建立应用身份、Registry、Binding 和 Runtime 装配。
• 实现应用命名空间内的 AgentRole、ToolSet、TaskContextProvider、QualityCheckProvider 和 RunLimits。
• 将应用身份和角色 hash 加入严格恢复快照。
• 建立应用 A/B 隔离和恢复 contract tests。

M3B：候选和事件投影

• 建立 CandidateRef 生命周期、权限和审计事件。
• 定义 CandidateRepository 端口，fork/merge 保留为业务语义。
• 稳定业务可消费的事件 envelope 和 RunEventProjector cursor。
• 投影失败不得破坏 Trace；支持重放和幂等恢复。

M4—M5：组装与参考应用

• 先用 reference example 合同 做 walking skeleton。
• 再完成包含停止、重启、回溯、局部失败和候选采用的完整业务链路。
• 只有真实应用不改内核即可运行后，才进入 Application API 0.1 的实现与冻结。

8. 外部实践如何转化为本项目决策

• OpenAI Agents SDK 和 Anthropic Building Effective Agents 都强调少量、可组合原语；因此不新增第二个 Runner 或通用 Workflow DSL。
• Google ADK App pattern 用 App 组合 root agent、plugins 和服务；本项目采用应用声明 + Provider 端口，但保留现有 AgentRunner 为唯一执行引擎。
• LangGraph Persistence 将状态变化保存为新 checkpoint；本项目沿用 message sequence/head 和协议 revision，不原地覆盖回溯历史。
• Microsoft Agent Framework Checkpoints 将存储做成可替换协议；本项目继续以 TraceStore 为边界，本轮不引入数据库。
• OpenAI HITL RunState 要求长期等待任务绑定定义版本；本项目将应用版本和 config hash 纳入恢复合同。

9. M1 完成标准

M1 完成时，框架团队必须能从本文逐项回答：

• 当前能力是真有、部分有还是没有，证据在哪里。
• 某个状态冲突时以哪个对象为准，谁有写入权限。
• 业务团队要实现哪些 Provider，哪些内核绝对不应修改。
• M2、M3 的实现边界和 reference example 验收依赖是什么。

本文不构成可导入 API。业务接入视角和草案接口见 Application API 0.1 草案，后续示例的业务验收见 reference example 合同。