AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

docs(runtime): align M1 API task and execution evidence contracts

Aberta
#479 0 comentários 0 reações 1 responsável Reivindicada por @LichKing-2234 Ver no GitHub
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.

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.