proxycast/docs/roadmap/agentruntime/implementation-plan.md

Lime AgentRuntime Profile 分阶段落地计划

状态：implementation-audited 更新时间：2026-05-12 作用：把 AgentRuntime Profile 从标准文档推进到 Lime current runtime、证据导出和 GUI 展示。 完成审计：见 ./completion-audit.md。本文件保留阶段计划与退出条件，实际落地证据以完成审计为准。

相邻标准边界同步纳入本计划：AgentContext 负责上下文 owner facts，AgentPolicy 负责策略/审批 owner facts，AgentEvidence 负责证据与 completeness owner facts，AgentUI 负责只读投影。详细合同见 ./adjacent-protocols.md。

1. 固定实施原则

1. 先做主链闭环，再做全量事件族。
2. 先补 correlation ids，再补漂亮展示。
3. 先让 evidence/replay/review 读同源事实，再做 dashboard 聚合。
4. 先保守收紧 Lime Profile schema，不收紧公开 schema。
5. 每阶段都要有可运行的结构测试或 GUI smoke。
6. 全球本地化必须在 presentation 层完成：profile facts 保持 stable value，AgentUI/Workspace/Evidence Markdown 通过 i18n key 或导出 locale 渲染。

2. 阶段总览

阶段	目标	关键产物	退出条件
P0	文档与 profile 冻结	本 roadmap、PRD、架构图、AgentRuntime v0.4.0 Lime Profile	团队对主链、owner、非目标无歧义
P1	Identity 与事件最小闭环	runtimeId/sessionId/threadId/turnId/taskId/runId 贯穿 submit turn	submit turn fixture 能映射真实 runtime
P2	ThreadReadModel 与 Context 收口	read model 消费 runtime events，不由 GUI 拼状态；Context refs 进入 read model	Workspace/Harness 只读 read model
P3	Evidence 同源导出	evidence/replay/review 消费同一 runtime facts，并保留 context/policy refs	evidence pack 含 runtime correlation spine
P4	Task / routing / permission 扩展	task retry、routing single candidate、tool approval / policy fixtures 落地	核心 fixtures 全部有实现测试
P5	子代理 / job / remote channel	parent-child graph、channel resume、job item retry	断线/重试/关闭可恢复可审计
PX	全球本地化守卫	profile facts 与用户可见 presentation 分层	新增 UI 文案有 locale resources，profile fixture 不含 locale 文案状态值

3. P0：文档与 profile 冻结

已完成目标：

1. agentruntime 标准项目新增 Lime AgentRuntime Profile。
2. Lime 主仓库新增 docs/roadmap/agentruntime/。
3. 固定 current / compat / deprecated / dead 分类。

后续如果改 Profile，必须同步：

• docs/roadmap/agentruntime/prd.md
• docs/roadmap/agentruntime/architecture.md
• docs/aiprompts/harness-engine-governance.md，仅当事实源规则改变时

4. P1：Identity 与事件最小闭环

目标：

• 任一 agent_runtime_submit_turn 都能生成 AgentRuntime Profile 需要的核心关联键。

关键工作：

1. 在 runtime turn 创建点统一生成或读取：
   • runtimeId
   • sessionId
   • threadId
   • turnId
   • taskId，如果该 turn 属于目标任务
   • runId，如果该 task 有执行尝试
2. 事件 envelope 统一携带：
   • eventId
   • timestamp
   • sequence
   • schemaVersion
   • payload
3. 输出最小事件：
   • turn.submitted
   • turn.started
   • model.requested
   • model.completed 或 model.failed
   • turn.completed 或 turn.failed
4. AgentUI 对 schemaVersion = lime-profile-0.4.0 的 dotted profile event 保持 stream 活跃且不告警，不把它转换成 UI-owned truth。
5. AgentUI 对 profile event 的展示必须通过 i18n key 映射，不把 type/status/message 原样当作用户可见主文案。

退出条件：

• 本地结构测试能用真实 runtime 输出构造 submit-turn-event.json 等价 fixture。
• 无 session/thread/turn 的 runtime 主路径事件不能进入 current read model。
• 前端未知事件控制器能识别 Lime Profile 事件为已知旁路事实，不污染用户可见 projection。
• AgentUI projection presentation mapper 支持用 key-based i18n 渲染 event type、phase/status、control、surface；Team Workbench、Harness、可靠性诊断和 Artifact timeline 这类 current projection 入口不得退回中文 fallback，不把 stable facts 翻译回写到 runtime/read model。
• turn.submitted / model.failed / task.failed 等 profile fixtures 的 type/status/failureCategory 在不同 locale 下保持不变。

5. P2：ThreadReadModel 与 Context 收口

目标：

• GUI 不再从散落状态推断 thread 状态。
• AgentContext facts 只以 refs/summary 进入 read model，不复制大上下文。

关键工作：

1. AgentRuntimeThreadReadModel 增加或统一字段：
   • status
   • profileStatus
   • activeTurnId
   • turns
   • pendingRequests
   • queuedTurns
   • incidents
   • toolCalls
   • modelRouting
   • limitState
   • evidenceSummary
   • telemetrySummary
   • contextSummary
   • missingContext
   • compactionSummary
   • contextRefs / policyRefs，只存 owner refs 或短 summary
2. Workspace / Harness 只消费 read model。
3. 旧 GUI 状态路径标记为 compat 并只做映射。
4. 现有 turn_context、context_trace、memory budget、context compaction metadata 收敛为 context.* facts 或 read model summary。
5. Context 侧必须保留 selected / omitted / budget / assembly / injection / compaction / missing context 的 owner refs；Runtime 不复制大 context payload。

退出条件：

• 主路径 GUI smoke 能展示 preparing/running/waiting_permission/completed/failed。
• 搜索不到新增 UI-only runtime truth builder。
• context.resolved/context.compaction.* 可 join 到 session/thread/turn，且 omitted / missing context 不被静默丢弃。

6. P3：Evidence 同源导出

目标：

• evidence pack、replay、analysis、review 共享 runtime facts。

关键工作：

1. agent_runtime_export_evidence_pack 加入 runtime correlation spine。
2. agent_runtime_export_replay_case 复用 evidence pack。
3. analysis handoff 和 review template 不再重建 observability summary。
4. known gaps 只从适用信号覆盖表导出。
5. evidence pack 引用 AgentContext source/selection refs 与 AgentPolicy decision/grant refs，不复制完整 owner payload。

退出条件：

• evidence fixture 包含 session/thread/turn/task/run/evidence/trace。
• replay/review/analysis 均能指向同一 evidence pack ref。
• completeness 按 runtime/telemetry/sources/claims/artifacts/verification/privacy/replay 分类声明，缺失事实标为 unknown/unavailable/not_collected 等，不推断成功。

7. P4：Task / routing / permission 扩展

目标：

• 让 Profile 覆盖 Lime 当前最关键的复杂运行态。
• 让 AgentPolicy 的 allow/deny/ask/defer/escalate/waive/not_applicable/indeterminate 结果成为可测试 runtime facts。

关键工作：

1. Task retry：
   • task.created
   • task.attempt.started
   • task.attempt.failed
   • task.retrying
   • task.completed / task.failed
2. Routing single candidate：
   • task.profile.resolved
   • routing.single_candidate
   • routing.not_possible
   • routing.decided
   • cost.estimated
   • limit.changed
3. Tool approval：
   • permission.evaluated
   • action.required
   • action.resolved
   • tool.started
   • tool.result / tool.failed
   • 真实 stream hook 以 RuntimeAgentEvent::ToolStart / ToolEnd 为首选事实源，ItemStarted / ItemCompleted(ToolCall) 只作同一执行流 fallback，并按 toolCallId 去重。
4. Policy linkage：
   • policy.decision.created owner ref
   • approvalRequestId
   • permissionGrantId
   • riskLevel
   • reasonCodes
   • obligations / constraints

退出条件：

• tool-approval-action-required-event.json、task-retry-attempt-failed-event.json、routing-single-candidate-event.json、routing-not-possible-event.json、routing-decided-multi-candidate-event.json 都有对应实现测试。
• runtime_tool_profile_should_follow_real_tool_start_and_end_once、runtime_tool_profile_should_fallback_to_item_tool_call_failure 必须通过，证明 tool facts 已从 read-model 反推前移到真实执行事件 hook，且不会被 ToolStart/ItemStarted 双路重复写入。
• ask 必须产生 action.required，deny/indeterminate 不能继续执行工具，defer/escalate 不能被 UI 当作允许，allow/waive 必须保留 obligations/constraints/scope refs。

8. P5：Subagent / Job / Remote Channel

目标：

• 把并行、后台和远程工作接入同一 profile。

关键工作：

1. subagent.spawned / subagent.status / subagent.completed / subagent.failed / subagent.closed
2. job.created / job.item.started / job.item.failed / job.completed
3. channel.connected / channel.disconnected / channel.resumed / snapshot.repaired
4. parent-child graph 写入 TaskSnapshot。

退出条件：

• subagent-parent-child-event.json 有对应实现测试，且 profile event 能回挂 parentSessionId/parentThreadId/parentTaskId/createdFromTurnId。
• job-owner-run-event.json 有对应实现测试，且 automation owner run 能输出 job.created/job.status/job.item.started/job.item.failed/job.completed|job.failed。
• remote-channel-resume-event.json 有对应实现测试，且 remote task owner run 能输出 channel.connected/channel.disconnected/channel.resumed/snapshot.repaired。
• 子代理失败能回挂 parent task。
• remote reconnect 后先读 snapshot，再补 replay 或标记 stale。

9. 测试计划

详细测试矩阵见 ./test-cases.md。本节只保留阶段级测试口径。

9.1 结构测试

• 校验 Lime Profile fixtures。
• 校验 runtime 输出事件 required ids。
• 校验 snapshot 必含 thread/task/evidence/routing/telemetry summary。

9.2 Contract 测试

• Tauri command、frontend gateway、catalog、mock 与 profile control plane 映射一致。
• safeInvoke(...) / Rust handler / command catalog / mocks 同步。

9.3 Replay 测试

• 从 runtime event stream 重建 ThreadReadModel。
• 从 ThreadReadModel + evidence pack 生成 review/replay。

9.4 GUI smoke

• submit turn。
• tool approval。
• failed tool / denied permission。
• routing single candidate 展示。
• evidence export 展示。

10. 风险与缓解

风险	等级	缓解
改动面扩散到所有 runtime 模块	高	每阶段只收一个主链切片。
UI 状态短期双轨	高	compat 只允许委托，并写退出条件。
Profile schema 过早收紧	中	public schema 宽松，Lime profile 只约束 current core。
Evidence 与 GUI 迁移不同步	中	evidence 先修事实，GUI 后读 read model。
子代理/job 复杂度过早进入	中	P5 后置，P1-P4 先证明主链。

11. PX / Markdown 本地化收口

2026-05-12 补记：

1. Evidence summary.md 保持 facts JSON 稳定，presentation copy 已按应用语言支持 zh-CN / zh-TW / en-US / ja-JP / ko-KR。
2. Replay grader.md 已接 RuntimeReplayMarkdownCopy，artifact title、主标题、读取顺序、评分原则、通过条件、阻塞检查和输出模板可按 locale 渲染。
3. Analysis analysis-brief.md 与 copyPrompt 已接 RuntimeAnalysisMarkdownCopy，外部分析标题、证据覆盖、读取顺序、文件分组、人工审核清单和关键摘录标题可按 locale 渲染。
4. Review review-decision.md 已接 RuntimeReviewMarkdownCopy，不再用标题替换后处理作为主方案，审核上下文、验证摘要、决策状态、风险、回归、后续动作等结构标题与核心标签由 locale copy 输出。
5. Runtime facts、runtime.json、analysis-context.json、review-decision.json 的 schema key 与 stable value 不随 locale 改变；locale 只影响 Markdown / copy prompt presentation。

退出条件：

• Rust 定向测试覆盖 Evidence / Replay / Analysis / Review Markdown locale。
• cargo check -p lime --lib 不出现 presentation copy unused warning。
• 未新增 Tauri command、前端 gateway、mock 或 request shape。

12. 实施后的下一刀

P1-P5/PX 的 current MVP 已按 ./completion-audit.md 完成审计。Evidence service 已先拆出 request telemetry、profile projection、completion audit / controlled GET evidence、modality contract、auxiliary runtime、verification / artifact validator、observability / signal coverage、known gaps、pack output renderer、Markdown locale copy、artifact index、JSON/path/tool helper 与单测 fixture 模块；后续不再从 P1 重走，而是优先收这些非阻塞弱项：

1. 继续把 Replay / Analysis / Review Markdown 的正文段落、验证摘要和 review checklist 做细粒度 copy 化；当前已完成结构标题与核心标签 locale-aware。
2. 把文档 fixture 名补成真实 JSON fixtures，或在测试用例文档中明确“结构测试等价覆盖”的映射表。
3. 继续收敛超大测试 fixture，优先拆 runtime_evidence_pack_service_tests.rs 的 artifact / telemetry / approval 场景 fixture builder。
4. 用 Playwright 补一个最小 tool approval approve/deny 和 remote resume 产品级 E2E。