Skip to content

architecture: validate the agent delivery journey and native interaction recipes #314

Closed
Closed
architecture: validate the agent delivery journey and native interaction recipes#314

Description

@turinglambdaai
turinglambdaai
opened on Oct 22, 2026

Interaction review — 2026-10-23

P1 · 已有指导方向正确；需要用真实产品的失败场景验证手册和脚手架。

Observed evidence and scope

agent-native.md already assigns product interaction meaning to products and mechanisms/evidence to Rivet. Consumer inspection now provides concrete cases: Payback save/draft lifetime, Autarx/Threadly selection-bound asynchronous details, and RegexMate keyboard result inspection. These belong in the clean-room journey validation before proposing new shared UI abstractions.

Source snapshot: 1ced9e9e898173d9b95a9fdd0e746ef822b6c51a. Central policy read: d32f8400264c3b6dddd613d207331934e2d7694e; Rivet interaction guide read at 1ced9e9e898173d9b95a9fdd0e746ef822b6c51a.

Product decision

  • Validate taskboard, then one actual product, with a narrow task brief, interaction table and native acceptance.
  • Use two consumer proofs before extracting a reusable mechanism/recipe. Product form policy, brands, layouts and paywalls remain outside Rivet.
  • Keep stable diagnostics/discovery and existing CI; no claim that RPC or screenshot success alone proves interaction parity.

Acceptance before closing

  • A fresh agent can implement/review one keyboard/focus/draft/error-recovery scenario using documented inputs only.
  • Required native legs report source/pins/artifact and persisted effects. Missing OS evidence stays pending; no new selector language or theme engine is introduced.

Handoff boundary

This is an architect review and implementation contract, not a runtime fix. Refresh the repository, relevant open PRs and current policies before taking one bounded slice; record starting SHA, owned files and native evidence. Preserve active writers and existing release/security gates. A paused product is not automatically restarted. Source findings and required failure-injection scenarios above are not claimed as three-platform runtime validation. Use synthetic data; do not access real keys, publish content or operate real hardware for this review.

Shared baseline: product experience contract.

Earlier issue context (retained)

Policy discovery follow-through (2026-10-23)

The default-branch AGENTS now directly links the family delivery, documentation-language and portfolio policies (638539577d489765c0ed454eb48777421413ad48). Each bounded slice must refresh/read these inputs and record the repository and policy revision actually read. The 25 audited repositories now expose these inputs from their default-branch AGENTS. Link coverage is not proof that a running agent has acknowledged them. Existing mobile/desktop implementation ownership stays in the current handoff; the clean-room newcomer journey and native interaction evidence below remain required.

审查结论（P1，2026-10-23）

现有 inspect/doctor/schema/acceptance/matrix 已覆盖开发主线，不需要再造编排层。跨宿主交互规则应在产品契约中；Rivet 提供机制和可验证的脚手架。现有 #310（pin 误报）、#311（无消费者 Kotlin 生成）、#312（设备网关后续）优先沿原 issue 处理。

实施顺序与范围

先完成 #310/#311 的可复现诊断修正；再用 taskboard 从干净安装开始演练一个不看源代码的用户简报→脚手架→交互契约→打包验收闭环。记录失败时稳定原因码与下一步，列出必须由人判断的产品/安全边界。第二个真实产品重复后才上收通用 recipe 或最小 scaffold 改进。不要借此引入 UI DSL、跨平台 selector、主题引擎或支付依赖。

这是产品/架构路线入口。每次仅认领一个可验收切片，开工记录 starting SHA、owned files、命令与回滚；活动共享层切片完成后再进入，不重叠写入，不重写已有实现。

完成标准

干净目录、固定依赖与 source SHA 能复现；开发模式和已打包应用证据分别记录；三桌面要求未跑不算成功；交互场景验证焦点、草稿、取消/恢复而非只有 RPC 输出；设备 companion 不标成独立移动产品交付。

固定审查证据

本轮是源码、文档、主页与公开发布资产的静态审查，未声称已经运行所有原生平台、硬件或真实支付。执行时重新核对当前状态。

沿用的工作

家族规范入口

产品交付标准、完整审查与主页规划 PR。依赖图仍以 Keel family architecture 为准。具体实现与证据留在本仓已有 canonical 文档；不要另建平行规范。

Activity

  1. turinglambdaai commented on Oct 25, 2026

    @turinglambdaai
    turinglambdaai
    on Oct 25, 2026
    OwnerAuthor

    进度更新（2026-10-25，macOS 腿会话）

    按本 issue 的实施顺序，前置诊断修正已全部落地：

    下一个可验收切片（按本 issue 定义，未开工）

    干净目录的 taskboard 闭环演练：fresh agent 仅凭文档输入完成一个 keyboard/focus/draft/error-recovery 场景的简报→脚手架→交互契约→打包验收，记录 starting SHA、owned files、命令与回滚。macOS 腿可先行，三桌面证据未齐前本 issue 不关；不引入 UI DSL、跨平台 selector、主题引擎。

    当前 main：03b3a35 之后（含 #322 DMG 背景修复，PR #323 已合并）。

  2. turinglambdaai commented on Oct 25, 2026

    @turinglambdaai
    turinglambdaai
    on Oct 25, 2026
    OwnerAuthor

    切片完成：taskboard 干净房闭环演练（macOS 腿，2026-10-25）

    执行方式：按本 issue 验收标准「A fresh agent can implement/review one scenario using documented inputs only」——由一个无上下文的 fresh agent（无 rivet 内部知识）仅凭 docs/、生成的项目 AGENTS.md、参考驱动 macos-ax.swift 和 CLI help 完成实现与验收；产品 owner 只提供用户简报，验收官独立重跑复核。

    结果

    • 场景端到端绿：raco rivet acceptance --json exit=0（验收官独立重跑确认可复现）
      • schema-contract：schema 基线兼容门禁
      • add-task-contract：4 组 RackUnit——空标题不动 State/存储、真实 JSON 持久化、fresh-namespace 重启模拟、手写 LE 编解码的真 RVT1 回环（Hello/Record 线上形状/$state 事件/Error 帧）
      • macos-add-task-ui：打包产物上 AX 驱动真实键入 + Return + Esc 全交互断言 → 有序关窗 → 同数据根重启校验持久化
      • 8 份证据（4 AX 快照含 error/restart 态 + 2 截图 + 2 trace）真实且 kind 钉定
    • 交互契约七列表落地（scenario-add-task.md）；合成数据 + 临时数据根，真实用户目录零写入；rivet 仓库全程只读（working tree 零改动）。
    • 演练产物（简报、日志、验收报告存档、完整项目）：本地 ~/Codes/taskboard-journey/。

    Fresh-agent 判定（对验收标准第一条）

    主体足够，四处必须自由发挥（详见演练日志第 3 节 G1–G10）：Record 值 Racket 侧语义（record-ref 靠黑盒枚举发现）、Optional null = (void)、backend 测试路径（serve 进程内驱动零指南）、native-ui 启动编排与键盘注入（macOS 侧全自行设计）。这些知识只落在了演练项目的代码注释里，未回流上游——已立独立 issue 跟进。

    本切片不声称

    三桌面 parity（仅 macOS 腿）、第二个产品重复、无新抽象引入（无 UI DSL/selector/主题引擎）。

    下一切片（按本 issue 顺序）

    1. 上游文档补齐 G1–G5（独立 issue 已建）→ 重复本演练验证文档修复有效；
    2. 第二个真实产品重复演练 → 之后才讨论通用 recipe 上收。

  3. turinglambdaai commented on Oct 25, 2026

    @turinglambdaai
    turinglambdaai
    on Oct 25, 2026
    OwnerAuthor

    切片完成：文档修复复验演练（2026-10-25 晚）

    按本 issue 切片顺序「补齐 G1–G5 → 重复演练验证」执行完毕：

    五项判定（对照第一轮演练的「必须自由发挥」）

    方面 第一轮（docs 修复前） 复验（docs 修复后）
    Record 构造/字段访问 黑盒探针发现 record-ref ✅ 文档直接可答
    Optional null 表示 三候选探针实验 ✅ 文档直接可答
    进程内驱动 backend 手写 LE 编解码 + 自设计回环 ⚠️ 90% 文档可答（phase 1 逐字照抄即绿；fresh-namespace 重启回环仍有两处小发明）
    macOS native-ui 启动编排 全自行设计 ✅ 文档直接可答
    AX 键盘输入 自行发明 CGEvent 注入 ✅ 文档直接可答（参考驱动 helper 一次跑通）

    结论：docs 修复有效。fresh agent 从「四处越线」收敛到「一处局部 + 若干小缺口」。

    剩余缺口（复验新录，均已记录在 #325 讨论）

    进程内配方的 fresh-namespace 细节、rivet/protocol 完整名面、零参 RPC 语法、Error 帧 payload 编码二义、数据目录指南（第一轮 G7，仍未文档化）等中小缺口——见 #325 的复验评论。

    本切片不声称

    三桌面 parity、第二个真实产品重复。下一切片：#325 中小缺口收尾（数据目录指南优先）→ 第二个产品演练 → recipe 上收讨论。

  4. turinglambdaai commented on Oct 26, 2026

    @turinglambdaai
    turinglambdaai
    on Oct 26, 2026
    OwnerAuthor

    切片完成：第二真实产品演练 · RegexMate 键盘结果检视（2026-10-25 深夜）

    本 issue 实施顺序的「真实产品」第一步完成（review 腿）。执行方式同前：无上下文 fresh agent + 仅文档输入 + 产品简报；验收官复核（工作区零残留、CI 全绿、PR 已合并）。

    交付（regexmate PR #7，已合并，main @ 3f0b558）

    • 交互契约表（docs/interaction-contract.md）：每列经实现源码 + 实跑双向核实。骨架两处被实证修正：初始焦点是窗口本身（非模式字段）；修复前「Tab 到匹配列表」不成立（SwiftUI 不为工具栏字段/NSView representable 建 key-view loop，而旧代码注释声称可达）——已最小修复（RegexKeyLoop 显式环 field→table→editor→field，仅 macos-host/）。
    • 键盘全路径验收：真 keycode 键入（含负探针证明键入不触发引擎）→ Tab 逐步走焦点 → 方向键走表 + 编辑器选区同步（AXSelectedRows 断言）→ ⌘R → [a- 错误态（内联错误 + 草稿保留）→ 恢复。证据 9 项（4 AX 快照含错误态 + 4 按窗截图 + trace 31 actions/22 assertions）。本机 acceptance 5/5、run-tests 81/81、CI 三平台 8/8。
    • 文档充分性判定（第二产品轮）：架构/验收框架层充分（Manifest、证据分类、启动编排、数据目录、值模型逐条可执行）；键盘配方在真实桌面不充分——见下。

    新发现的真实桌面缺口（rivet 侧，已立独立 issue）

    1. 键入配方失效：工具栏字段 AX 焦点假真（field editor 不启动）；第三方输入法（拼音）吞 CGEvent unicode 事件——需 TIS 切 ASCII 布局 + 真 keycode 注入，文档只字未提。
    2. AX 元素生命周期：结果列表过空态时 NSTableView 重建、捕获的 AXUIElement 变僵尸——文档只要求语义名稳定，未警示驱动需从活树重获元素。
    3. 共享 manifest 无本地校验入口（手写 rktd 少括号直到全套件跑时才爆）——建议 CLI 提供 --dry-run/清单 lint。

    并行会话事故处置记录

    演练中撞上另一会话的 pin bump 切走了分支——agent 按跨设备纪律把 commit 迁回短命分支、main 复位 origin、未 push main，全程记录在 journey-log。教训：同机多会话并行同一仓库必须 git worktree 隔离（AGENTS 已有此规，实际执行又验证了一次）。

    #314 剩余路径

    真实产品证明 #1（RegexMate）✅ → 真实产品证明 #2（Payback save/draft 生命周期）已启动（后台演练中） → 齐后进入 recipe 上收讨论（哪些机制值得上游化：key-view loop 修复模式？契约表模板？e2e 驱动骨架？）。

  5. turinglambdaai commented on Oct 26, 2026

    @turinglambdaai
    turinglambdaai
    on Oct 26, 2026
    OwnerAuthor

    结案：agent 交付旅程验证完成（两个消费者证明齐备，2026-10-26）

    本 issue 的实施顺序已全部执行完毕，按其自身完成标准结案（「Missing OS evidence stays pending」条款如实适用）。

    执行轨迹（全部有合并交付或 issue 承接）

    1. 前置诊断修正：doctor --release: env-mediated pins read as empty refs, historical changelog refs compared against the installed release #310（PR doctor: resolve mediated pins and stop judging changelog history (#310) #316）、Kotlin client is generated for every project, so the freshness gate fails on trees that ignore .rivet/ #311（PR codegen: emit the Kotlin client only for projects with a companion API (#311) #317）、follow-ups from the RVT1 device gateway review (#305) #312（PR fix(device): sweep wedged dispatches, bound the rvt1 hello, and pin the state deny surface (#312) #324）——合并关闭。
    2. 参考产品闭环演练（fresh agent implement 腿，taskboard 脚手架）：端到端绿（schema-contract / 真 RVT1 回环 contract / AX 驱动 native-ui + 重启持久化）。执行 2 轮：第一轮暴露 5 项高影响文档缺口 → docs: document the Racket-side value model and the backend/native-ui testing paths (taskboard journey findings) #325；文档修复（PR docs: document the racket value model, in-process backend testing, and macos native-ui orchestration (#325) #326/docs: close out the journey gap list - data directories, fresh-namespace recipe, and protocol surface details (#325) #327）后复验轮 4/5「文档直接可答」——修复被证明有效。
    3. 真实产品证明 feat: add shared state and embedded runtime verification #1（RegexMate 键盘结果检视）：交互契约表 + key-view loop 修复 + 键盘全路径验收，regexmate#7 合并（CI 8/8）。契约表实证修正骨架两处（含「Tab 可达」旧注释为假）。
    4. 真实产品证明 feat: add typed shared state and embedded round-trip verification #2（Payback 保存/草稿生命周期）：契约表 docs/save-lifecycle.md + e2e 套件重写（spin 检测、frontmost 校验、TIS 输入源切换、quit Apple Event 退出、HOME 覆盖）+ 一个产品修复（sheet 锚点拆分），payback#29 合并（CI 11/11 三平台打包验收全绿）。演练中挖出并定位一个用户可命中的真实 bug（失败态编辑即失焦，payback#30 承接）。
    5. 真实桌面配方缺口（两次演练共同产出）→ native-ui: make the documented keyboard/AX recipes hold on real desktops (regexmate journey findings) #328（IME/TIS、AX 焦点假真、AX 元素僵尸、manifest dry-run）+ embedded runtime: intermittent startup spin (window never renders) and packaged-app orderly-exit semantics contradict the docs #329（embedded runtime 启动 spin heisenbug、打包 app 有序退出语义与文档相反——仅 quit Apple Event 可靠）。

    Recipe 上收候选（两个产品证明了同一边界，上收门槛已满足）

    以下模式在两个真实产品上重复出现，值得写进 rivet 的参考驱动与文档（#328/#329 的实现载体）：

    • 交互契约七列表模板（两产品各落一份：interaction-contract.md / save-lifecycle.md）
    • SwiftUI 工具栏字段的显式 key-view loop 模式（AX 焦点假真的唯一可靠解）
    • e2e 驱动骨架：活树重探（防 AX 僵尸）、spin 签名检测 + 有界重启、每键前 frontmost 校验、TIS 切 ASCII 布局 + 退出恢复、quit Apple Event 有序退出、disposable HOME 整体覆盖

    如实声明（pending 项）

    fresh agent 亲笔的交互场景腿在 macOS 完成；Linux/Windows 的 native-ui 验收格由两产品各自的既有套件在 CI 三平台矩阵证明（全绿）。演练产物（4 份 journey-log）在原机器本地 ~/Codes/*-journey/，未入库。

    状态

    入口 issue 的排序使命完成；残留工作全部有独立 issue 承接（#328、#329、payback#30）。关闭本 issue。

  6. turinglambdaai
    closed this as completedon Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions