lineup/agent_ops
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

初始化 agent_ops 文档治理体系

Browse Source
This commit is contained in:
kyugao
2026-08-07 16:56:51 +08:00
commit 10840909ab
75 changed files with 15750 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03.迭代规划/01.总览与路线/01.迭代总览与阶段结论.md
+32
View File
@@ -0,0 +1,32 @@
# 迭代总览与阶段结论
**版本：** 2026-08-07 整合版
**范围：** `lineup-app/迭代/` 的主定义、计划、设计评审与验收评审
## 1. 总体判断
当前迭代体系已经从“客户端内部阶段记录”演进成“跨项目能力闭环推进”。
最重要的阶段事实是：
- `00.base` 已完成并验证最小客户端闭环；
- `01.kernel` 明确了应用工作区与运行时编排方向；
- `03.sdk_and_coreapp` 已完成并冻结 MiniApp SDK v1 的关键边界；
- `04.runtime_workspace` 已于 2026-08-06 完成最终验收；
- `04A.agent_tool_route` 已于 2026-08-07 完成当前定义下的联合验收。
## 2. 当前阶段地图
| 阶段 | 状态 | 作用 |
|---|---|---|
| `00.base` | 已完成 | 最小 Runtime 闭环基线 |
| `01.kernel` | 目标设计 | 应用工作区与编排骨架 |
| `03.sdk_and_coreapp` | 已完成 | SDK v1 与内置参考 MiniApp |
| `04.runtime_workspace` | 已完成 | 工作区与 Pomodoro 主闭环 |
| `04A.agent_tool_route` | 已完成 | Agent Tool 通路与 Hermes 兼容层 |
## 3. 当前主优先级
1. 以 `04.runtime_workspace` 与 `04A.agent_tool_route` 为已完成样板，启动下一轮跨项目迭代。
2. 继续按统一四步法推进后续阶段。
3. 逐步清理旧来源目录和历史入口。
03.迭代规划/01.总览与路线/02.后续路线与阶段优先级.md
+28
View File
@@ -0,0 +1,28 @@
# 后续路线与阶段优先级
**版本：** 2026-08-07 整合版
**依据：** `lineup-app/迭代/plan.md`
## 1. 当前北极星
LineUp 的目标是成为面向 Agent 的协议化交互运行时，而不是某个固定 channel 的 UI 外壳。
## 2. 当前推荐路线
```text
已完成 Runtime 工作区闭环
→ 已补齐 Agent Tool 通路
→ 下一步推进下一类真正可用的隔离 MiniApp
```
## 3. 当前不宜提前拉入主线的事项
- 应用市场
- 第三方远程下载与发布
- 多 Agent 连接与切换
- 真实音视频能力
- 复杂任务管理膨胀
## 4. 与新迭代主目录的关系
今后这份路线文档在 `agent_ops/03.迭代规划/` 维护，作为所有跨项目迭代的总路线入口，而不再只放在 `lineup-app/迭代/plan.md`。
03.迭代规划/01.总览与路线/原始来源/lineup-app后续迭代计划.md
+422
View File
@@ -0,0 +1,422 @@
# LineUp App 后续迭代计划
**更新时间：** 2026-08-07
**计划状态：** 已确认，作为后续迭代拆分和排期依据
## 1. 产品北极星
LineUp 的最终目标，不是做一个“把 Agent 接到某个聊天 channel 上”的客户端，也不是做一个只能展示固定卡片格式的
Agent IM 外壳；它要成为一个 **面向 Agent 的协议化交互运行时**。
这意味着：
- Agent 不只输出文本，还能基于标准协议选择更合适的交互形态；
- 用户与 Agent 的核心交互方式仍然是 `IM`、`voice`、`video conference` 等主交互模式；
- Runtime、SDK、Tool、MiniApp、Surface、Capability 和标准交互原语，是这些主交互模式在任务过程中可调用、可组合、可恢复的工具与组件；
- LineUp 的核心资产，不是某一个具体小程序，而是“Agent 如何知道该用什么形式表达任务，以及宿主如何稳定执行这种表达”的标准协议与运行时。
可以将目标结构收敛为：
```text
主交互模式
= IM / Voice / Video Conference / 未来其他模式
任务过程中的可用工具
= 标准交互原语 + Runtime Tool + MiniApp Workspace + Host Capability
LineUp 的核心职责
= 让 Agent 基于统一协议，在这些交互模式中选择、调用、编排合适的工具和组件
```
因此，LineUp 与当前常见 Agent channel 方案的本质区别在于：
- 普通 channel 方案主要解决“Agent 内容如何适配某个平台已有的固定展示格式”；
- LineUp 要解决的是“Agent 如何在一个统一运行时里，按协议动态组织文本、卡片、工具调用和微型工作区，与用户完成真实任务协作”。
这里的 MiniApp 往往不需要很大。像 Pomodoro 这样的能力，本质上不是一个独立产品线，而是 Agent 在任务过程中临时拉起的、
最适合当前目标的一个受控交互载体。未来这类载体可以是番茄钟、白板、选择器、安排器、表单、确认器或其他小型工作区。
本计划后续所有迭代，都应围绕这条北极星判断优先级：
- 是否在强化协议和运行时，而不是回退成某个 channel 的格式适配；
- 是否在增强 Agent 对“该用什么交互形态”的可选择能力；
- 是否在让 IM / Voice / Video 等主交互模式能够共享同一套 Runtime、SDK 和 Tool 语义；
- 是否在让工具与组件成为交互过程中的标准能力，而不是散落的页面特判。
## 2. 计划结论
前三个阶段已经建立了 LineUp App 的基础：Runtime 托管 IM、Runtime 具备应用编排能力、MiniApp SDK v1
和两个内置 MiniApp 参考实现已经完成验证。
下一步不建设应用市场，也不马上扩展多 Agent、语音或视频。下一阶段先把已有的 Runtime、SDK 和 MiniApp
契约做成用户真正可以使用的“应用工作区”。
当前推荐路线：
```text
Runtime 工作区与应用闭环
→ 第一个真正可用的 MiniApp（番茄时钟）
→ 本地 App 管理与签名 Bundle
→ 再评估应用分发和市场
```
## 3. 已完成的基础
### 3.1 Runtime 托管 IM
`00.base` 已建立客户端基础闭环：
- Runtime 独占网络连接、同步循环、消息存储、outbox 和 App Inbox；
- 登录、同步、本地回显、Markdown 和 Agent 状态保持稳定；
- 入站消息经过作用域校验、去重和恢复；
- Chat 只能通过 SDK 和 Runtime Action 工作。
### 3.2 Runtime 应用编排基础
Runtime 已具备应用实例、焦点和生命周期的核心模型：
- App Registry；
- App Instance Manager；
- App Focus Manager；
- App Lifecycle Manager；
- Tool Router 和 App Orchestrator；
- App 子会话、前后台切换、关闭和恢复的契约。
### 3.3 MiniApp SDK v1 与参考实现
`03.sdk_and_coreapp` 已完成并通过自动化测试和浏览器验收：
- Interact 是唯一的 `system` MiniApp；
- Task Dashboard 和 Whiteboard 都是普通 `bundled` MiniApp 的参考实现；
- MiniApp 通过 SDK 接收 Inbox、Tool、进度、结果、生命周期、Surface 和 Capability 请求；
- 标准 `notice / choice / confirm / input` 属于 Interact 的人与 Agent 交互，不是 MiniApp 内部表单；
- App 子会话、交互归属、关闭收口、继续处理和重启恢复已有明确规则；
- 当前单 Agent MVP 边界保持不变。
需要注意：当前完成主要证明了 Runtime 契约和参考实现正确，用户可见的完整应用工作区仍需下一阶段收敛。
## 4. 第四次迭代：Runtime 工作区与应用闭环
**设计状态：** 已冻结，待实施；冻结基线为
[04.runtime_workspace.md](04.runtime_workspace/04.runtime_workspace.md)、
[05.technical_implementation_spec.md](04.runtime_workspace/05.technical_implementation_spec.md) 及其
[03.design_review.md](04.runtime_workspace/03.design_review.md)、[06.technical_implementation_spec_review.md](04.runtime_workspace/06.technical_implementation_spec_review.md)、
[07.技术实施规范评审（二）.md](04.runtime_workspace/07.技术实施规范评审（二）.md)。当前没有未解决的 P0～P3；
TIS2-06 是未来多入口 session data 协作写入的 P4 延续项，不阻塞第 04 次实施。
建议迭代目录：
```text
迭代/04.runtime_workspace/
```
### 4.1 目标
把 Runtime 的生命周期和会话模型接到真实 Web/Tauri 界面，跑通一条完整的用户流程：
```text
进入 Interact IM
→ Agent 请求启动 Pomodoro 番茄时钟
→ Runtime 创建 App instance、App 子会话和 deadline operation
→ 番茄时钟进入前台，Interact 进入后台
→ 用户进行写作业、看书或冥想等固定时长专注；自动暗屏/锁屏不终止本轮
→ 到时间完成，或用户主动离开 Pomodoro 工作区而中断
→ Runtime 回传唯一结果并关闭 App
→ 子会话结束并在 IM 中折叠保存
→ Interact 恢复
→ 用户查看历史或继续开始下一轮
```
### 4.2 主要工作
1. **接通 App 工作区界面**
- 显示当前前台 App；
- 支持由 `pomodoro.start` 从 Interact 进入 Pomodoro，以及用户明确返回 Interact；
返回/切换会中断当前专注，不把 Pomodoro 作为通用后台计时器继续运行；
- 显示后台、挂起、关闭和恢复状态；
- App 启动失败时恢复 Interact；
- 刷新或重启后恢复工作区。
Whiteboard 在第 04 次只保持第 03 次已有的 SDK/隔离回归，不接入本轮工作区切换或新的完整流程。
2. **接通 App 生命周期**
- 将 `AppLifecycleManager`、`AppFocusManager` 和 `AppOrchestrator` 接入真实 Host；
- 区分自动暗屏/锁屏、Surface 重载、工作区切换和真正关闭；前两者不终止专注，后两者中断专注；
- Runtime 使用持久化 `ends_at` 的 deadline operation，而不是 MiniApp UI 定时器；
- 关闭后停止新 Tool 投递；
- 用户退出专注时先将 `pomodoro.start` 终结为 `interrupted`；其他未终态普通 Tool 才收敛为
`cancelled(app_closed)`；
- 已提交结果继续通过 outbox 发送；
- 关闭后恢复前一个有效前台 App。
3. **完成 App 子会话展示**
- 主 IM 显示 App 子会话折叠卡片；
- 支持展开已结束子会话；
- 已结束子会话只读；
- “继续处理”创建新 instance 和新子会话；
- 不把 App 内部按钮、表单和编辑动作写入 IM。
4. **完成 Interact 交互覆盖层**
- Interact 前台时，在 IM 中以内联卡片显示标准交互；
- bundled MiniApp 前台时，可以在其上方显示 Interact 的交互层；
- 展示位置变化不改变交互归属；
- App 关闭不自动取消未回答的标准交互；
- Agent 可以通过 `interaction.dismiss` 远程取消交互。
5. **让 Pomodoro 成为第一条完整用户流程**
- 用户在 IM 中以自然语言要求 Agent 开始或结束写作业、看书或冥想等专注；MiniApp 是 Agent 的业务工具，
而不是由用户自行操作业务状态的独立应用。未来 Voice 复用相同意图和 Tool 语义，但不属于本轮实现或验收；
- Agent 以 `pomodoro.start({ duration_seconds, activity? })` 创建长期 Tool operation，并以
`pomodoro.interrupt({})` 请求结束当前专注；
- 同一会话已有 `focusing` 专注时，不同调用的第二次 `pomodoro.start` 稳定拒绝为
`active_focusing_operation`，不创建新的 App、子会话或 deadline operation；
- Runtime 创建 Pomodoro instance、App 子会话和 deadline operation，Pomodoro 直接进入专注界面；
- 到时间得到 `completed`；Agent 调用 `pomodoro.interrupt`，或用户切回 Interact、切到其他 MiniApp、关闭
Pomodoro 时得到 `interrupted`；后者由 Runtime 的生命周期处理，不伪造 Agent Tool；不支持暂停、继续或恢复；
- 自动暗屏、锁屏与 Surface 重载不终止专注；刷新或重启后根据 `ends_at` 恢复或结算一次；
- 到时间后 Runtime 回传一次结果并立即关闭 Pomodoro，完成结果由 Interact / Agent 呈现；
- 完成记录和子会话可以在 Interact 中查看。
第一版只保留这些状态和数据：
```text
state = focusing | completed | interrupted
operation_id
source_tool_call_id
activity?
duration_seconds
started_at
ends_at
ended_at?
interruption_reason?
```
最小 Agent Tool：
```text
pomodoro.start({ duration_seconds, activity? })
pomodoro.interrupt({})
```
Pomodoro 使用 `app.instance-state.v1` 保存严格 schema v1、最大 4 KiB 的展示快照；关闭后采用
`retain_readonly`，旧快照只用于历史展示，不能再次写入或恢复为运行中的专注。
番茄钟到点后不保留 App 内完成提醒：Runtime 关闭 Pomodoro 并恢复 Interact，由 Interact / Agent 呈现
完成结果。如果以后需要系统通知，再通过 Runtime 的 Capability 请求，不能让 MiniApp 直接调用 Tauri
或操作系统接口。Agent 询问用户是否开始下一轮时，仍然必须使用 Interact 的标准交互。
6. **补充端到端验收**
- Web Reference Host 完整验收；
- Tauri Desktop Host 至少完成一条代表性流程；
- 验证刷新、断线、重启、关闭、恢复和重复提交；
- 检查 Runtime 生命周期、交互、Tool 和恢复日志。
### 4.3 不在本迭代范围
- 应用市场和服务端 App Catalog；
- 远程下载、第三方发布和在线更新；
- 多 Agent 连接、切换和多 Agent 会话列表；
- Audio Mode 的真实媒体能力；
- Video Mode 的真实媒体能力；
- Whiteboard 的工作区接入、切换、多人协作和复杂绘图能力；第 04 次只保持其已有回归；通用 mutation queue 与
Agent Tool、UI Action 共同修改同一 App 子会话数据的协作协议同样延期，首次实现此类双入口写入功能前必须专项设计；
- Task Dashboard 的完整项目管理功能；
- Pomodoro 的统计报表、多个计时器、日历和复杂提醒计划。
### 4.4 完成标准
```text
用户可以在 IM 中请求 Agent 立即开始或停止 Pomodoro 专注；未来 Voice 只复用相同 Tool 语义；
Runtime 可以正确创建、运行、中断、关闭和恢复 Pomodoro App；
App 子会话能在 IM 中折叠、展开和继续处理；
标准交互在不同前台 App 下仍归 Interact；
到点/中断竞争唯一终态，Tool 和 outbox 收口正确；
到点后立即关闭 Pomodoro 并由 Interact / Agent 呈现完成结果；
Pomodoro 关闭后的业务快照保留为只读历史，不能复活旧 instance；
刷新/重启后 App、焦点、子会话、`ends_at` 专注状态和待处理交互按规则恢复；
Web/Tauri 代表性流程通过端到端验收；
Whiteboard 保持第 03 次回归，但不属于第 04 次工作区闭环或完成范围；
所有 P0～P3 评审问题清零。
```
## 5. 第五次迭代：第二个真正可用的隔离 MiniApp
建议迭代目录：
```text
迭代/05.first_isolated_miniapp/
```
第四次迭代完成工作区和 Pomodoro 后，再把另一个 MiniApp 从“参考实现”推进为“真实隔离运行的应用”。
### 5.1 推荐顺序
优先选择 Whiteboard 作为第二条安全和 Surface 验证流程；Task Dashboard 留到后续，避免任务管理业务影响 Runtime 核心设计。
### 5.2 Whiteboard 方向
- 受限 Surface 中的画布状态；
- 状态 patch；
- Artifact 导出；
- Artifact 元数据校验；
- 重启恢复；
- 验证不能访问 Host DOM、Tauri、认证状态、任意网络和其他 MiniApp 数据。
暂时不做多人协作、云端同步和复杂绘图工具。
### 5.3 Task Dashboard 的后续定位
Task Dashboard 仍然保留为后续普通 `bundled` MiniApp，但不作为 Runtime 的第一条验证流程。
等工作区、SDK、生命周期和 Surface 边界稳定后，再单独定义任务、项目、状态和历史等业务模型。
## 6. 第六次迭代：Agent 平台适配与原生命令兼容层
建议迭代目录：
```text
迭代/06.agent_platform_adapter/
```
`04A.agent_tool_route` 已经证明：Hermes 这类 Agent 平台与 LineUp 之间，真正需要稳定下来的不是某个平台的单次补丁，而是一个可扩展的“平台私有命令 / 交互 -> LineUp 标准能力”兼容机制。
这一轮的目标不是把 Runtime 变成各家 Agent 的命令执行器，而是冻结三层分工，并为 Hermes、未来 Open Claw 等平台提供统一承接面：
```text
Agent Native Command / Prompt
-> Agent Adapter Compatibility Layer
-> LineUp Standard Action / Interaction
-> Runtime / App / Host Capability
```
### 6.1 分层原则
1. **LineUp Standard Ability**
- 由 LineUp 自己定义并长期稳定维护；
- 只包含 Runtime Tool、标准交互与 Host capability 等通用协议：
- `lineup.v1.tool.invoke`
- `lineup.v1.tool.call`
- `lineup.v1.tool.result`
- `lineup.v1.app.call`
- `lineup.v1.app.result`
- 不直接暴露 Hermes、Open Claw 等平台私有 slash / prompt 语义。
2. **Agent Adapter Compatibility Layer**
- 位于各平台自己的 adapter / plugin；
- 负责把平台私有 command、approval、clarify、confirm、update prompt 等交互，映射到 LineUp 标准协议；
- 维护平台内部 request / callback token 与 LineUp `call_id` / option id 的受控映射；
- 未来 Hermes、Open Claw 等都复用同一套分层原则，而不是继续把兼容逻辑下沉到 Runtime。
3. **Runtime / App Implementation Layer**
- 只实现 LineUp 自己的业务能力和受控宿主能力；
- 例如 `pomodoro.start`、`pomodoro.interrupt`、打开 surface、文件选择、剪贴板、artifact 保存等；
- 不直接理解 `/model`、`/reload-mcp`、`/reset`、`/approve` 之类 Agent-native command。
### 6.2 本迭代拟解决的问题
- 冻结“Agent Native Command 不等于 LineUp Runtime Ability”的架构边界；
- 抽象统一的 `command-to-action` 与 `prompt-to-interaction` 转换模型；
- 为多个 Agent 平台定义一致的 adapter 承接面，而不是每个平台都重新发明一套私有兼容逻辑；
- 明确哪些交互由 adapter 收口，哪些能力才允许进入 Runtime / Host；
- 为 `slash_confirm`、`update_prompt` 这类当前在 ACP 路径下缺少稳定触发源的 contract，定义后续 bridge / trigger 承接方案。
### 6.3 不在本迭代范围
- 把各家 Agent 平台的原生命令直接下沉到 Runtime；
- 让 `lineup-app-server` 理解平台私有 command / prompt 语义；
- 一次性实现所有第三方 Agent 平台；
- 扩展多 Agent 会话编排或平台市场能力。
### 6.4 完成标准
```text
形成一份权威分层设计：Agent Native Command、Adapter Compatibility Contract、LineUp Standard Action 三层边界清晰；
Hermes 适配结论可被抽象为平台无关的兼容模型，而不是 Hermes 特判；
未来 Open Claw 等新平台能够按同一 adapter contract 接入，不要求先改 Runtime；
明确 slash / confirm / approval / clarify / update prompt 等 contract 的归属与映射原则；
为需要 bridge / trigger 的平台原生交互，给出单独的小迭代承接口径。
```
## 7. 第七次迭代：本地 App 管理和签名 Bundle
建议迭代目录：
```text
迭代/07.local_app_management/
```
这一阶段仍然不建设在线应用市场，只解决本机的应用管理和安全运行边界：
- App Registry 管理界面；
- 本地安装记录；
- App enable / disable / remove；
- 版本记录和回滚；
- 本地签名 Bundle；
- Bundle 完整性和签名校验；
- 验证失败不污染当前可运行缓存；
- Inventory 更新和 Agent 可见性变化；
- App 删除时实例、焦点、Inbox、Surface 和私有数据的收口。
## 8. 第八次迭代之后：再评估应用分发和市场
只有在 Runtime 工作区、本地 App 管理、SDK、Surface 和签名 Bundle 都稳定之后，才评估：
- 服务端 App Catalog；
- 应用搜索和详情；
- 下载和更新；
- 发布者身份；
- 第三方 MiniApp；
- 审核、撤回和安全策略。
应用市场不是当前阶段的基础设施，而是建立在前面几层都稳定之后的分发能力。
## 7. 更后面的方向
### Runtime Core 的 Rust 演进
在 Runtime 工作区已跑通并积累 Web / Tauri 两个 Host 的性能数据后，单独评估是否将部分**无 UI 的 Runtime
Core** 下沉到 Rust，以改善状态处理和原子收口的效率与一致性。这不是第 04 次迭代的工作，也不等于把整个
MiniApp SDK 改写成 Rust：Web Reference Host、sandbox iframe、postMessage Bridge、DOM 和 UI 仍须保持在
TypeScript / 浏览器侧。
潜在的 Rust 候选范围：
- instance state 的持久化、schema 校验和 revision 比较；
- deadline operation 调度；
- Tool / outbox 的原子终态裁决；
- lifecycle 收口和审计。
只有在 profiling 显示上述路径存在明确热点时，才建立独立设计与迁移迭代。评估必须同时测量状态快照读写、
deadline / Tool 吞吐、主线程阻塞、Tauri IPC 往返、JSON 序列化成本，以及 Web / Tauri Host 的实际差异；
并证明收益覆盖跨语言实现、测试、调试和错误边界所增加的复杂度。
### 多 Agent
在单 Agent 工作区稳定后再设计：
- Agent 列表和切换；
- 多 Agent 会话；
- 多 Agent outbox；
- App 子会话归属；
- Inventory 和权限隔离。
### Audio Mode 与 Video Mode
语音和视频应复用当前 Runtime SDK、Tool、Capability、Artifact 和会话模型，不建立独立的 Agent
通信链路。它们需要单独处理媒体权限、设备选择、实时连接、中断和恢复，因此不进入当前两次迭代。
## 8. 当前排期原则
```text
先完成“真实可用的应用工作区”
再完成“一个真正隔离的 MiniApp”
再完成“本地安装和签名管理”
最后才评估“远程分发和应用市场”
```
任何新增功能都应先回答三个问题：
1. 它是否依赖 Runtime 已经稳定的生命周期和会话模型？
2. 它是否能通过现有 MiniApp SDK、Surface、Capability 和 Artifact 边界实现？
3. 它是否会把应用业务逻辑、网络通信或系统权限重新塞回 Interact 或 `main.ts`？
如果前两个问题没有准备好，或者第三个问题答案为“会”，就不应提前进入应用市场或新的 App 类型建设。