AGENTS.md

文档目的与状态

本文件记录项目所有者于 2026-10-28 明确的产品目标、交互约束，以及据此评审设计和实现的方法。

这些目标是设计基准，不表示现有实现已经满足全部要求。阅读代码时必须区分「目标」「当前实际行为」「提议中的改造」；发现冲突应明确指出，不能用现状反向改写目标。

本次架构评审聚焦 SDK 与 Runtime。Mobile、Agent Driver 和其他模块的内部实现不在本轮范围内；可以定义 SDK/Runtime 对外必须提供的集成契约。本段仅记录此次任务范围，不限制后续任务涉及其他模块。

一、产品目标

1. 使用 AgentOrientedText-basedUI（AOTUI）构建的 Application，主要服务对象是 LLM Agent。
2. AOTUI SDK 的核心应用开发者也是 Agent。人类需要能够理解、审查和维护，但不能只用人类开发者对某种框架的熟悉度评价 SDK。
3. 项目希望成为可被不同 LLM Agent 系统复用的基础设施。重点是稳定的应用交互语义、可验证的运行行为，以及 Agent 构建正确应用的能力。
4. AOTUI 之于 Agent，类似 GUI 之于人类：它为使用者维护当前工作对象、可见状态和可用操作。

二、已经确认的交互约束

呈现方式、动态操作、最新快照与数据分离来自项目所有者的明确要求；下文关于所有权、授权和发布状态的说明是对这些要求的工程解释，不表示某种具体机制已经被批准。

2.1 View 是进入上下文的应用页面

• Application 通过 View 向 Agent 呈现当前应用状态。
• 当前呈现格式是 XML + Markdown；View 被包装为 LLM 上下文 Messages 数组中的 User Message。
• Agent 可以通过应用提供的操作，控制 View 的打开、更新、关闭及其他明确支持的状态转换。
• 不应把视觉布局或 DOM 机制本身当作产品目标；采用何种内部渲染技术，需要以这些交互语义为依据。

2.2 应用管理 Agent 的当前工作记忆

• Agent 通过操作应用，间接增删改 Messages 中由应用维护的工作状态。因此，View 生命周期也是应用工作记忆的生命周期。
• 对同一个逻辑 View，当前上下文中只呈现其最新有效快照。更新不能持续追加多份看似都代表当前状态的旧快照。
• 「只保留最新 View」针对当前状态投影，不等于要求删除全部用户对话、操作收据或审计历史。
• 工程上应区分应用拥有的动态内容、真实用户指令、操作历史及其他来源的上下文。应用通过明确的所有权边界管理自己的部分；不能由此推导出任意改写整个 Messages 数组的权限。
• Messages 是本项目关注的工作记忆载体；不能据此假定 Agent 不存在其他历史、持久化状态或长期记忆。

2.3 View 与可用行为共同构成充血模型

• View 不只是数据文本，也承载当前工作对象及其适用操作。
• Tool 会随着 Agent 打开 View、进入某个对象上下文或发生状态转换而逐渐暴露。
• 例如，尚未打开任何文件时，不暴露针对已打开文件的编辑能力；文件打开后，其 FileDetailView 才提供相应编辑操作。
• 操作的可发现性、当前可用性、执行时授权和业务前置条件是需要分别说明的概念。仅隐藏 Tool 不能代替执行时校验。
• 动态可用性是产品语义。是否使用原生 Tool、CLI 或其他调用入口表达它，仍属于待评估的实现选择。

2.4 操作与数据呈现分离

• 项目采用类似 CQRS（Command Query Responsibility Segregation）的职责分离思路：Tool 发起操作；具体业务数据及其变化通过 View 呈现。
• Tool 返回操作结果、必要提示及恢复操作所需的信息；文件正文、查询结果集合等主要业务数据应进入对应 View。
• 不应在 Tool Result 与 View 中同时维护两份独立的「当前数据真相」。
• 这条约束并不自动要求采用 Event Sourcing、独立读写数据库或分布式事务。
• 操作已受理、业务已完成、结果已进入可观察 View，是需要区分的事实。实现不能仅凭 handler 返回，就宣称新的 View 已经可见。

2.5 SDK 与 Runtime 的职责边界

• SDK 与 Runtime 的目标是服务好 AOTUI 开发者，构建简单、强大、稳定的内核。
• 应用层应自行承担自己的业务职责。SDK 与 Runtime 不应为了替应用兜底而接管业务规则、推断业务依赖或进行过度设计。
• 工程评审应区分框架拥有的交互机制与应用、宿主拥有的策略：框架对自己管理的提交、身份、绑定、调用和资源生命周期负责；业务数据是否正确、外部操作是否成功、何时更新业务状态由对应应用或资源适配器负责。
• 常见需求可以通过可选 SDK helper、环境适配器或示例支持；是否进入必需的内核路径，应以跨应用通用性、框架能否独立判断以及资源所有权为依据。
• 简化应优先消除重复解释、历史兼容和模糊接口；不能把框架应有的一致性、隔离、清理和失败反馈责任转嫁给每个应用作者。

三、规范性示例：打开并编辑 test.txt

1. Agent 打开 aotui-ide。此时没有打开文件，也没有针对文件的 edit file 操作。
2. Agent 调用 read file（其语义是打开/展示文件）打开 test.txt。该操作产生操作收据与必要提示，以及包含文件内容和相应操作的 FileDetailView(test.txt)。
3. FileDetailView(test.txt) 以 XML + Markdown 包装后进入 Messages，并提供当前对象的 edit file 等可用操作。test.txt 正文统一通过该 View 呈现，不在 Tool Result 中重复返回。
4. Agent 调用 edit file，应用执行编辑。该操作产生操作收据与必要提示，更新后的正文通过 FileDetailView(test.txt) 呈现。
5. 下一次呈现当前应用状态时，旧快照退出，最新快照按明确规则进入 Messages；不能同时存在两份均自称当前状态的 FileDetailView(test.txt)。
6. View 被关闭后，其当前状态内容退出应用工作记忆；属于该 View 实例的执行绑定需要遵守关闭/失效契约。

read file / edit file 在这里表示交互语义，不要求保留这些字面 API 名称。操作收据与 View 的发布顺序及下一轮观察保证由公共契约明确；本例不预先规定 IPC 或消息发送时序。快照排序、关闭后的重新打开等细节，也应由具体公共契约明确，而不是由各应用自行猜测。

四、评审 SDK 与 Runtime 时必须回答的问题

以下是从目标推导的评审维度，不表示某个具体技术方案已经被批准或实现。

SDK：让 Agent 容易生成语义正确的应用

• Agent 能否仅根据公共文档、类型和示例完成应用，而不需要阅读 Runtime 内部协议？
• 示例是否遵守「操作返回收据、业务数据通过 View 呈现」？不能只检查示例能否编译。
• 是否能从同一份声明得到一致的 View 内容、对象引用、当前操作和输入校验？哪些同步职责仍由应用作者承担？
• 相同名字或相似签名是否隐含不同的生命周期、目标范围或执行语义？
• 错误是否提供稳定 code、具体位置和可行动的修复信息？面向应用作者的诊断与面向应用使用者的收据应有合适边界。
• 应以 Agent 生成应用的契约符合率、修复轮次、依赖私有 API 的比例和迁移成功率评价 SDK，而不只比较代码行数。

Runtime：维护可信的当前工作环境

• 一次观察得到的 View、Ref 和可用操作是否来自兼容的已提交状态？
• 调用是否能追溯到 Agent 实际观察到的目标，而不会因同名 View 重开或绑定变化而误作用于其他对象？
• 操作完成与结果投影可见之间有什么明确保证？后台任务、失败和外部变化如何表达？
• 只保留最新快照时，是否仍保留足够的操作因果信息与恢复依据？
• View 打开、关闭、摘要、分页和刷新如何影响上下文预算、能力可见性与资源生命周期？
• 是否诚实区分未执行、失败、部分副作用、已受理、结果未知和资源已释放？
• 当前状态、操作发现和执行验证是否遵守同一语义来源？

广泛复用：可替换实现，稳定语义

• 不同宿主、渲染方式和调用入口，应能够实现同一组交互不变量。
• 将领域数据与权限、条件写入等业务保证放在能实际承担它们的层；不能用 UI 可见性或普通进程隔离代替。
• 定义支持范围、版本兼容、诊断、持久化与关闭行为；不要把单一 Demo 成功等同于通用 Infra 成熟。
• 评估上下文总量、实际模型输入成本、刷新延迟和任务成功率；不能仅凭「删除旧 View」推导出成本必然降低。

五、改造与验证原则

• 先阅读既有架构决策。rfcs/0003-sdk-runtime-architecture-route.zh-CN.md 记录已接受的 RD 总体路线：复用现有 Core、保留 Preact 默认开发模型、用 DOM 与普通 TypeScript 两种 Producer 验证。该文统一公共术语为 Tool，实验中的 Action 是对应概念，不另建平行体系。
• 本次明确的产品目标是新的评审基准；如需改变既有技术路线，应说明被调整的决策与理由。本文件不将既有已接受路线改写为「从未决定」，也不把 RFC 中的目标接口或历史验收状态当成当前已实现能力。
• 可以提出 Breaking Change，包括替换公共 API、默认执行路径或内部实现。实施范围以当前具体任务为准。
• 重构应保留已被证明有价值的语义保证。减少代码或采用新技术本身，不是丢弃一致性、生命周期、授权、资源边界和失败语义的理由。
• CLI 替换原生 Tool、改变默认 authoring 技术、替换内部库或调整包边界，均属于可重新评估的设计选择；本文件不批准这些替代方案，也不取消既有路线。
• 用代码与测试核对文档；历史验收记录、当前运行结果和架构推断需要分别说明。
• 优先验证打开文件后能力出现、编辑后仅最新 View 可见、关闭后旧绑定失效、外部修改被识别、长任务保持有界、失败能被 Agent 理解和恢复等场景。
• Agent 使用应用和 Agent 开发应用是两类评测，应分别设计。
• 修改本文件时保留既有仓库指导，并清楚区分项目所有者确认的目标与尚未决定的建议。

六、Semantic 收敛与 Legacy 退出

本节记录项目所有者于 2026-10-28 补充的清理方向和退出条件。

已确认的方向与条件

• 在项目所有者本人完成新 Semantic 路径的测试并验收后，Legacy 可以下线，SDK 与 Runtime 以唯一的 Semantic 路径为维护目标。
• 当前优先级是清理和收敛内核，以及 SDK、Runtime 内未使用、被替代、实验遗留和过时未删除的代码；清理以减法为主，不借此扩展业务职责或增加新的框架体系。
• 上述条件不表示验收已经完成。内部测试、历史交付签署或名称中的 semantic 均不能代替项目所有者此次验收事实。
• 验收后的目标不包含长期维护 Legacy 兼容包、旧入口回退或新旧双轨。已有明确验收后，不为同一退出决定追加重复审批。

清理方法与边界

• 从保留的 Semantic 入口追踪提交、观察、调用、投影和关闭依赖，按剩余职责判断去留；不能仅凭目录名或 legacy、experimental、shadow 等字符串批量删除。
• 属于已验收 Semantic 能力的实验实现应收敛为正式入口；没有保留职责的实验实现及其专属包装应删除；有真实需求且属于应用或宿主的能力才外移，不建立“以后可能有用”的代码保存区。
• 下线时同步处理实现、公共导出、类型、配置、仅为双轨比较存在的机制、构建产物、示例和当前使用文档。协议身份、来源检查和必要能力校验不因去掉实验标签而自动删除。
• 只验证已退出接口或实现的测试可以删除；仍证明 Semantic 契约的测试应保留或迁移。不得通过弱化现存契约测试掩盖清理回归，也不要求已明确删除的旧 API 继续通过兼容测试。
• 当前主链共用的身份、来源绑定、参数合同、调用记录、容量限制和资源释放保证继续保留。删除旧包装不等于删除其底层仍被使用的能力。
• 检查导出、静态与动态入口、调用方、构建脚本和初始化/订阅副作用。公共 API 的历史兼容身份不构成永久保留理由，但仍承诺支持的 Semantic 消费方式必须得到迁移和验证。
• CODE_CLEANUP_PLAN.zh-CN.md 与 CODE_CLEANUP_COMPATIBILITY.zh-CN.md 中“保持公共接口稳定”“保留兼容项”等要求属于原清理批次；它们不限制本节约定的验收后 Breaking Change。保留历史验收事实，当前方向以本节和项目所有者最新指令为准。