AgoraIO-Extensions / AgoraIO-Extensions/agent-infra
docs(runtime): align M1 API task and execution evidence contracts
- Linguagem predominante
- TypeScript
- Estrelas
- 0
- Forks
- 0
- Merge médio
- 8h 51min
- PRs com merge (30d)
- 99
Descrição
## Problem
M1 用户/应用 API、运行可观测、Eval 与审计已完成产品决定,平台 PRD #475 与工程 Spec #477 已形成独立评审候选且当前提交 CI 通过。Runtime HLD 仍只描述 Web/企微消息、唯一 Platform fallback 事件与 Tool Gateway,缺少 API 受理等待、主体授权、实际模型/工具事实及必要审计衔接,无法作为新增范围的完整实现输入。
本票承接 #150 已列明的 Runtime HLD 文档差额。#437/PR #478 负责 Claude Native、共享模型 profile/传输与上游复用条款;#441 是既有 Platform 遥测实现,#432 负责 Connection 内部身份/MCP/API/Grant 与新 DAG。上述范围不覆盖本票的公共任务与执行事实文档增量。
## Scope
- 仅修改 `docs/architecture/HLD-agent-runtime-M1.md`,基于工程 Spec #477 的 `d67550fa4dfcb9d5532dc75822ee385fc58cacba` 起草,产品范围服从同基线的平台 PRD。
- 明确用户/应用提交主体、原受理授权边界、当前授权与 Runtime Execution Grant 的传递;凭证失效不取消原任务,主体禁用/Agent 使用权撤销阻止后续受控操作并系统取消;任务查询/流/取消按提交主体隔离。
- 将 API 有界受理/等待、同会话串行、不同会话按经验证容量运行、稳定幂等、取消确认及重启/未知结果恢复映射到既有 Conversation/Execution/outbox/RuntimeHost;Platform Dispatch 负责等待,Driver 不另建任务队列;Web 补充指令/繁忙语义保留。
- 补齐平台任务状态事件与真实模型/工具事实的来源、稳定引用、时间/状态/用量、规范化、持久确认/重放/去重、缺失与失败边界。运行采集失败不能伪造业务结果,必要审计与执行前意图遵守工程 Spec 的可靠性要求。
- 定义 Eval 对既有任务与 Runtime 能力的复用;数据授权、评分与汇总留在 Platform,Runtime 不新增 Eval 状态权威。四模板的任务/真实观测能力必须验证,自定义与 self-managed 不因声明自动获得能力。
- 移除 HLD 内旧 Tool Gateway/Connection 双重授权与状态投影职责,仅引用独立直连、真实调用关联和两侧分别授权的上位契约;不设计 Connection OAuth/LDAP/MCP/Grant 内部协议或重排 DAG。
- 保留现有 Runtime Native/ACP/Pi、fence/cancellation barrier、Session 代次隔离、模型与部署安全约束;不引入新服务、消息基础设施、通用调度、优先级、定时任务、逐任务执行时限参数或新的模型配置协议。
- 使用独立 worktree/分支形成单文件 Draft PR,base 为 `docs/476-m1-engineering`。不修改其他 owner 的 worktree,不吸收 #478 的模型/Claude/复用条款;回读其当前 HLD patch 并检查文本兼容。
- 本票交付文档候选;在平台 PRD、工程 Spec、Connection 文档和共享 Runtime 修改完成适用评审及串行合流前保持 Draft。本票不修改代码、Schema 产物、PRD、Spec、ADR、迁移或部署,不启动产品 Pilot、不合并、不发布;功能实施归属继续由 #150 在上位契约对齐后确定。
## Acceptance criteria
- [ ] **AC-1:** HLD 对用户/应用、凭证与主体失效、提交主体隔离和 Runtime Grant 的约束与候选 PRD/Spec 一致,不创建 Runtime 身份或授权权威。
- [ ] **AC-2:** API 等待与活跃 Turn 区分、受理/幂等、调度/取消竞态、恢复和未知结果有明确持久状态与唯一归属;Web 语义、原 Session、fence 和 barrier 约束保持。
- [ ] **AC-3:** 平台任务事件与真实模型/工具事实可映射到正式 Schema 的生产/消费边界,持久确认和去重完整;必要审计、实际外部意图、采集故障及正文/凭证排除语义准确。
- [ ] **AC-4:** Eval 复用、四模板与自定义能力边界明确;HLD 不再要求 Tool Gateway、Connection assertion/policy 或状态/审计投影,关联不替代授权。
- [ ] **AC-5:** 现有验证矩阵补齐 API、权限、取消/恢复、真实模型/工具采集、审计故障与 Eval 复用的正负向和真实验证入口;不以 Fake、CI 或局部 Driver 交付替代完整 M1。
- [ ] **AC-6:** 完成独立 Standards/Spec 评审、完整仓库验证与真实结果记录、相对链接及当前 #478 HLD patch 兼容检查;PR 是单文件 Draft,并披露剩余跨文档合流条件。
## Validation
- 对照平台 PRD §7.3/§9/§10.4/§13–16 与工程 Spec §8–9/§11–13/§18–19,逐项核对权威、任务状态、实际采集、授权、审计及故障语义。
- 核对 HLD 的原有 Web 幂等、补充指令、停止、租约/fence、代次隔离和事件游标,API 增量不能破坏原不变量;扫描旧 Gateway/Connection 投影与唯一 fallback 事件残留。
- 仅读取 PR #478 当前提交的 HLD patch,保持模型/传输及上游复用条款不被覆盖;差额在 Draft PR 中明确。
- 按 AGENTS.md 执行 frozen install、check、check-types、test、build、smoke、docker:build、Markdown lint/link、workflow policy、actionlint 和 git diff --check。已知本机 PostgreSQL/Docker 容量及网络限制如实记录,远端 CI 必须绑定本票准确 head。
- 提交前独立 Standards/Spec 评审;发布后回读唯一 primary Issue、单文件范围、Draft/base/head、正文与实际检查结果。既有其他 Issue 的 Scope/AC、负责人和依赖不变。
## Blocked by
None
Guia de contribuição
Nenhum guia de contribuição indexado para este repositório
Avaliação
Esta issue ainda não foi avaliada.