源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)
Publish Claude Code Binaries / Stage and publish binaries (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-arm64 (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build linux-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build windows-amd64 (push) Canceled after 0s
Sync Tutti Agent Skills / sync (push) Canceled after 0s
Windows Agent Adapters / Test Windows agent adapters (push) Canceled after 0s
Windows Daemon Adapters / Test Windows daemon adapters (push) Canceled after 0s
Publish Tutti App Runtime / Publish runtime catalog (push) Canceled after 0s

This commit is contained in:
agent-radar committed 2026-09-01 20:17:27 +08:00
commit 2ed3415fb7
8018 files changed
+1936476

No files matched your search

@@ -0,0 +1,332 @@
---
goal: "Add a device-local quick-prompt library to the Agent composer using only existing Tutti UI System primitives."
version: "1.0"
date_created: "2026-07-20"
last_updated: "2026-07-20"
owner: "Tutti Agent GUI"
status: "Implemented"
tags: [feature, agent-gui, composer, quick-prompt, tuttid, ui-system]
---
# Introduction
![Status: Implemented](https://img.shields.io/badge/status-Implemented-brightgreen)
实现已在 `codex/feature-quick-prompt-library` 完成,并通过 changed-aware checks、daemon build、
定向竞态/冲突测试和三路独立代码审查。TASK-033 中涉及真实桌面窗口的视觉与双窗口人工验收仍应在
合并前由桌面环境执行;其余实现和自动化验证项已完成。
本文基于 `origin/main` 的提交 `deed78c73ce9c5b3da1cd3223a81805dffc6bfea`
设计。目标是在 Agent 输入框底部、Handoff/Provider 入口之后加入“快捷提示词”入口:
用户从固定高度的 Popover 中搜索并选择提示词,选择后把正文插入当前输入框选区;用户也可以新增、
编辑和删除提示词。该能力作为开发者功能交付,`agent.quickPromptLibrary` 默认关闭;用户必须先在
“设置 → 开发者”显式开启,入口才会出现。
交互采用“选择与管理分层”的方案:Popover 只承担浏览、搜索、选择和管理入口;新增/编辑使用
Dialog,删除使用 ConfirmationDialog。这样既保留高频选择动作的轻量感,又避免在 400px 左右的
Popover 中放入长文本表单、键盘和错误状态,降低焦点管理与误操作风险。
所有浮层、表单、按钮、滚动容器、菜单和图标必须复用现有 `@tutti-os/ui-system` 公共导出。
本功能不新增 UI primitive,不深层导入 UI System 源文件,也不使用原生 `button`、自制 overlay、
自制 scroll container 或新图标替代已有组件。
推荐的数据流如下:
```mermaid
flowchart LR
UI["AgentQuickPromptPopover / Dialog"] --> Host["AgentHostQuickPromptsApi"]
Host --> Desktop["DesktopAgentQuickPromptService"]
Desktop --> Client["Generated Tuttid client"]
Client --> API["tuttid quick-prompt API"]
API --> Service["agentquickprompt service"]
Service --> Store["SQLite agent_quick_prompts"]
Service --> Event["agent.quickprompt.updated"]
Event --> Desktop
UI --> Editor["TipTap insertPlainTextAtSelection"]
```
提示词库是设备级、与 workspace 和会话无关的用户数据。它由 tuttid 持久化;
`AgentGUIRuntime` 继续只管理 Session/Turn/Interaction 等 canonical activity,不接收提示词库状态。
## 1. Requirements & Constraints
- **REQ-001**: 在 Composer Footer 左侧组内,把快捷提示词入口放在 Handoff/Provider 入口之后、
Plan/Goal 等状态徽标之前,与截图标注位置一致;宿主没有 quick-prompts capability 或开发者功能开关关闭时隐藏入口。
- **REQ-002**: 入口使用 UI System `Button`、`Tooltip` 和现有 `FileTextIcon`;普通宽度显示图标和
“提示词”,紧凑布局只显示图标但保留可访问名称和 Tooltip。
- **REQ-003**: 选择器使用 UI System `Popover`,向上打开并左对齐;内容宽度 400px、高度 420px,
同时受 Radix available-height 约束,在小窗口中允许整体缩短但不越出视口。
- **REQ-004**: Popover 的标题、搜索框和新增按钮固定,只有列表区域使用 UI System `ScrollArea`
滚动;列表按 `updatedAtUnixMs DESC, id ASC` 稳定排序,搜索在已加载的最多 100 条记录中匹配标题和正文。
- **REQ-005**: 每条记录的主区域用于选择;右侧独立的 UI System `DropdownMenu` 提供编辑和删除,
避免交互元素嵌套。加载、空列表、无搜索结果和失败重试都要有明确状态。
- **REQ-006**: 新增和编辑使用 UI System `Dialog`、`Input`、`Textarea`、`Button`;标题和正文均为必填,
表单不自动保存。新增与编辑共用一个表单组件,编辑时载入实体快照和版本号。
- **REQ-007**: 删除使用 UI System `ConfirmationDialog` 的 destructive tone,确认文案包含提示词标题;
删除前后不得把提示词正文写入日志、Toast、事件或分析埋点。
- **REQ-008**: Popover 与新增/编辑/删除 Dialog 互斥。进入管理 Dialog 时保留搜索词、滚动位置和来源记录;
Dialog 关闭后返回原 Popover,上次新增或编辑成功的记录获得焦点但不会自动插入。
- **REQ-009**: 选择提示词时,用 TipTap 当前 selection 替换被选文本或在光标处插入纯文本,保留原有
mention、附件和其他富文本节点;完成后关闭 Popover、恢复编辑器焦点且不自动发送。
- **REQ-010**: 快捷提示词为设备级数据,不绑定 workspace、项目、provider、Agent target 或会话;
所有 Workspace AgentGUI 和 standalone Agent window 通过同一个宿主 capability 使用它。
- **REQ-011**: tuttid 提供 list/create/update/delete API;标题 trim 后 1–80 个 Unicode code point,
正文保持换行和内部空白但 trim 后不得为空,UTF-8 最大 32 KiB,设备最多 100 条。
- **REQ-012**: 每条记录包含 `id`、`title`、`content`、`version`、`createdAtUnixMs` 和
`updatedAtUnixMs`;服务端生成稳定 UUID,版本从 1 开始,每次成功编辑加 1。
- **REQ-013**: 编辑和删除携带 `expectedVersion`。实体不存在返回 404,版本过期返回 409;客户端保留
Dialog 中的草稿,刷新最新列表并提示用户重新确认,不静默覆盖其他窗口的修改。
- **REQ-014**: 成功写操作发布全局 `agent.quickprompt.updated` 失效事件,事件只包含 `promptId`、
`changeKind`、`version` 和 `occurredAtUnixMs`,不包含标题或正文;其他窗口收到后合并/coalesce 一次 list 刷新。
- **REQ-015**: 所有用户可见文案加入 AgentGUI 的 `en` 和 `zh-CN` locale,由现有 label projection 注入;
不在组件和桌面 adapter 中硬编码文案,中文 UI 文案末尾不加句号。
- **REQ-016**: 键盘路径完整:入口可聚焦,Popover 打开后聚焦搜索框,上下键移动列表,Enter 选择,
Escape 逐层关闭,Dialog 保存后焦点返回管理来源;每个 icon-only action 有可访问名称。
- **REQ-017**: 在现有“设置 → 开发者”增加“快捷提示词”UI System `Switch`。feature flag key 固定为
`agent.quickPromptLibrary`,catalog default 为 `false`;key 缺失、旧版 preferences 或读取失败都按关闭处理。
- **REQ-018**: 开关通过现有 desktop preferences 保存并订阅 `preferences.desktop.updated`;开启后当前窗口即时显示入口并在首次打开时 lazy load,
关闭后所有窗口即时关闭已打开的 Popover/Dialog、隐藏入口并禁止新的 list/mutation,但保留已存提示词数据。
- **SEC-001**: 提示词正文视为潜在敏感数据,只存在于 SQLite、HTTP 响应和当前 renderer 内存;
不进入 event stream payload、诊断日志、analytics、错误 developer message 或 crash breadcrumb。
- **SEC-002**: API 复用 daemon 现有本地认证/监听边界和标准错误响应;服务层在持久化前完成长度、
空白、数量与版本校验,不能只依赖前端校验。
- **SEC-003**: desktop Host adapter 在 feature flag 关闭时 fail closed:不触发 quick-prompt list/create/update/delete;
UI 中已经排队但尚未发出的 mutation 必须取消,已经提交到 daemon 的请求按 authoritative response 收口但不重新显示入口。
- **CON-001**: 使用 UI System 公共入口 `@tutti-os/ui-system` 和 `@tutti-os/ui-system/icons`;
采用现有 `Popover`、`Dialog`、`ConfirmationDialog`、`ScrollArea`、`Input`、`Textarea`、`Button`、
`DropdownMenu`、`Tooltip`、`Spinner`、`FileTextIcon`、`AddIcon`、`EditIcon`、`DeleteIcon`、
`MoreHorizontalIcon` 和 `SearchIcon`,不得 DIY 同类能力。
- **CON-002**: 业务布局可通过 `className` 设定 400×420 尺寸和 flex/min-height,但颜色、边框、阴影、
圆角、焦点态和 destructive tone 必须来自 UI System 语义 token/variant。
- **CON-003**: 不修改 `packages/ui/system` 源码、metadata 或 storyboard;若实现时发现既有组件缺少
必要能力,先停下并单独评审 UI System 扩展,不能在 AgentGUI 内复制 primitive。
- **CON-004**: 不把提示词库放入 `AgentGUIRuntime`、workspace engine、Session/Turn、
desktop preferences、localStorage 或组件 module-global cache。
- **CON-005**: 第一版不包含目录/标签/拖拽排序、变量模板、团队/云同步、导入导出、默认内置提示词、
快捷键、自动发送和提示词使用统计。
- **CON-006**: 延续仓库分层:OpenAPI 与 event definition 先行;tuttid 负责业务规则和 durable state;
desktop 只做 transport/capability adapter;AgentGUI 负责呈现和编辑器交互。
- **CON-007**: feature flag 复用现有 `desktop_preferences.feature_flags_json`、DesktopFeatureFlags map、
`setFeatureFlags()` 和 preferences event;不得为该开关新增 SQLite column/table、单独 migration 或 localStorage key。
## 2. Implementation Steps
### Implementation Phase 1 — 固化领域、OpenAPI 与事件契约
- **GOAL-001**: 先建立设备级 quick-prompt 的唯一领域语言和生成式协议,避免 UI、desktop 与 daemon
各自定义不兼容 DTO。
| Task | Description | Completed | Date |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---- |
| TASK-001 | 在 `services/tuttid/biz/agentquickprompt/model.go` 定义实体、create/update/delete input、稳定排序规则和共享 sentinel errors;实体正文不实现 `Stringer`,错误中不拼接 content。 | | |
| TASK-002 | 在 `services/tuttid/api/openapi/tuttid.v1.yaml` 增加设备级 `/v1/agent-quick-prompts` GET/POST 与 `/v1/agent-quick-prompts/{promptId}` PUT/DELETE。List 返回 `{ prompts }`,create 返回 201 entity,update 返回 200 entity,delete 返回 204;mutation body 带完整 title/content 或 `expectedVersion`。 | | |
| TASK-003 | 为 400/404/409/503 定义并复用现有标准 API error response;把 malformed body/ID、field/limit validation、not found、version conflict 和 service unavailable 映射为稳定错误码与字段参数。 | | |
| TASK-004 | 新增 `packages/events/protocol/definitions/agent/quickprompt.updated.event.json`,声明 topic `agent.quickprompt.updated`、version 1、server-to-client、global scope 和不含正文的失效 payload;在 eventstream catalog 中注册对应 topic/validator。 | | |
| TASK-005 | 运行 `pnpm generate:api` 与 `pnpm generate:event-protocol`,提交生成的 Go server types、TypeScript client types/operations、event TypeScript validators/types 和 Go protocol;生成文件只由脚本更新。 | | |
### Implementation Phase 2 — 实现 tuttid 持久化、服务与 API
- **GOAL-002**: 让 quick-prompt 成为 tuttid 独立、可并发保护、可测试的 durable product state。
| Task | Description | Completed | Date |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ---- |
| TASK-006 | 在 workspace SQLite migrations 中加入 `agent_quick_prompts` 表:`id TEXT PRIMARY KEY`、`title TEXT NOT NULL`、`content TEXT NOT NULL`、`version INTEGER NOT NULL CHECK(version >= 1)`、created/updated timestamps,并为 `updated_at_unix_ms DESC, id ASC` 建索引。 | | |
| TASK-007 | 在 `services/tuttid/data/workspace/store.go` 增加窄 `AgentQuickPromptStore` contract,并在 `sqlite_agent_quick_prompts.go` 实现 list/count/create/update/delete。Update/Delete 使用 `WHERE id = ? AND version = ?`,事务内区分 not-found 与 conflict。 | | |
| TASK-008 | 为 migration、排序、100 条上限边界、Unicode 标题、32 KiB 正文、版本递增、冲突、删除和数据库 reopen 持久性增加 SQLite tests;不得在失败输出中打印 content fixture。 | | |
| TASK-009 | 新增 `services/tuttid/service/agentquickprompt/service.go`,注入 Store、Clock、ID generator 与窄 Publisher;集中执行 trim/长度/数量/version 规则,数据库 commit 成功后再发布失效事件,publisher 失败只记录不含正文的结构化 warning,不能回滚已提交数据。 | | |
| TASK-010 | 新增 `services/tuttid/service/eventstream/agent_quick_prompt.go` publisher,并扩展 catalog/parity tests;event 只作为 refresh hint,HTTP/SQLite entity 仍是 authoritative state。 | | |
| TASK-011 | 新增 `services/tuttid/api/daemon_agent_quick_prompts.go` 与 handler tests,完成 generated DTO 与 domain 的显式映射、nil body/service guard、标准状态码和敏感数据错误测试。 | | |
| TASK-012 | 在 `services/tuttid/api/daemon.go` 的 `DaemonAPI` 增加窄 service interface,在 `services/tuttid/wiring.go` 从 workspace store 构建 service/publisher 并注入 API;保持 desktop、HTTP、eventstream 细节在 service 领域之外。 | | |
### Implementation Phase 3 — 建立 desktop service 与 AgentHost capability
- **GOAL-003**: 为所有 AgentGUI surface 提供同一份可订阅快照,同时保持 shared AgentGUI 不依赖
generated tuttid client 或 Electron。
| Task | Description | Completed | Date |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ---- |
| TASK-013 | 在 `packages/agent/gui/host/agentHostApi.ts` 增加可选 `AgentHostQuickPromptsApi`:`ensureLoaded`、`getSnapshot`、`subscribe`、`create`、`update`、`remove`;把 capability 从 `AgentHostInputApi` 明确投影到 `AgentHostRuntimeApi`,不经 legacy agentSessions。 | | |
| TASK-014 | Snapshot 使用 `idle/loading/ready/error` 状态、immutable prompts、error、revision 和 pending mutation IDs;shared contract 只表达产品能力,不导入 tuttid generated types。 | | |
| TASK-015 | 新增 feature-local `DesktopAgentQuickPromptService` 及接口,使用 generated `TuttidClient` 完成 HTTP CRUD,用 `useSyncExternalStore` 兼容的 subscribe/getSnapshot 发布 committed snapshot;首次打开 lazy load,重复打开复用内存快照,显式 retry 强制刷新。 | | |
| TASK-016 | desktop service 订阅 `agent.quickprompt.updated`,忽略本窗口已应用的等价 mutation,其他/未知 mutation 以 single-flight 方式 coalesce 列表刷新;dispose 时释放事件订阅,错误时保留最后成功列表并标记 refresh error。 | | |
| TASK-017 | 在 `registerWorkspaceAgentServices.ts` 注册/返回 quick-prompt service,在 workspace window service registry 中创建每个 renderer window 的单例;它不按 workspaceId 分库。把实例传给 `createDesktopAgentHostApi.ts` 并投影为 optional quickPrompts capability。 | | |
| TASK-018 | 更新 `createDesktopAgentGUIWorkbenchHostInput.ts`、workbench contribution factory、workspace contribution 与 standalone Agent window 的 host-input composition 和相应 tests,从同一 registry service 注入 capability;preview/test host 未提供 capability 时保持原行为且入口不渲染。 | | |
| TASK-019 | 在 `apps/desktop/src/shared/featureFlags/catalog.ts` 导出 `AGENT_QUICK_PROMPT_LIBRARY_FLAG = "agent.quickPromptLibrary"`,加入 `FEATURE_FLAG_DEFINITIONS` 的 `developer` group 且 default `false`;扩展 catalog tests,验证 missing/false/true 三种解析。 | | |
| TASK-020 | 在 `WorkspaceDeveloperSettingsSection.tsx` 按现有 developer flag row 复用 UI System `Switch`,从 pending feature flags 读取值并调用 `settingsService.changeFeatureFlags` 保存;在 shared `en`/`zh-CN` locale 添加 label、description 和保存失败文案。 | | |
| TASK-021 | 让 `DesktopAgentQuickPromptService` 组合 desktop preferences 可观察状态:Host snapshot 增加 `enabled`,同时订阅 preferences 与 quick-prompt data;disabled 时不加载/不 mutation,true→false 时发布 snapshot 使 AgentGUI 关闭 disclosure,false→true 时只显示入口、保持首次打开 lazy load。 | | |
### Implementation Phase 4 — 实现 Composer 选择、管理与插入体验
- **GOAL-004**: 用既有 UI System primitive 完成固定高度选择器和独立管理 Dialog,并把选择结果安全写回 TipTap。
| Task | Description | Completed | Date |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---- |
| TASK-022 | 在 Composer 下创建 `quickPrompts/` 垂直模块,增加 `useAgentQuickPromptLibrary.ts` controller,统一管理 capability snapshot、feature-enabled gate、search、popover/dialog mode、return focus、selected entity/version、pending state 和 toast/error translation。 | | |
| TASK-023 | 实现 `AgentQuickPromptPopover.tsx`:UI System `PopoverContent` 使用 `side="top" align="start" sideOffset={8}`、`w-[400px] h-[420px] max-h-[var(--radix-popover-content-available-height)]`;header/search 固定,`ScrollArea` 使用 `min-h-0 flex-1`。 | | |
| TASK-024 | Popover row 使用独立 UI System selection `Button` 与 `DropdownMenu` trigger `Button`,避免 button-in-button;菜单复用 system icons,删除项使用 destructive variant。补齐 loading、empty、no-result、stale/error-with-retry 和 mutation-disabled 状态。 | | |
| TASK-025 | 实现 `AgentQuickPromptEditorDialog.tsx`,复用 Dialog/Input/Textarea/Button;宽度不超过 560px,正文编辑区最小高度 240px,显示 80 code-point 与 32 KiB 校验,提交中锁定重复 mutation,API 失败保留草稿。 | | |
| TASK-026 | 用 `ConfirmationDialog` 实现删除确认。controller 保证 Popover/Dialog 互斥,并在管理完成或取消后恢复原 search/scroll/focus;409 时保留草稿、刷新实体并显示冲突说明。 | | |
| TASK-027 | 给 `ComposerFooter.tsx` 增加 `quickPromptControl?: ReactNode` 组合槽并放在 Handoff/Provider 之后,业务状态留在 `AgentComposer` 垂直模块中,避免把 CRUD props 铺满 Footer;补充 composition test 保护位置、公共 UI imports 和 trigger nesting。 | | |
| TASK-028 | 扩展 `AgentRichTextEditorHandle` 与 `useAgentRichTextEditorHandle.ts`,增加 `insertPlainTextAtSelection(text)`;用现有 `plainTextToAgentRichTextInlineContent` 和 TipTap chain 替换 selection,设置 skip-user-content-event meta,并返回新的 prompt text 供 controlled composer 同步。 | | |
| TASK-029 | 打开 quick-prompt Popover 前关闭 slash/mention palette、status/review disclosure;选择后插入、不发送、关闭 disclosure 并 focus editor。开关变为 disabled 时同步关闭 quick-prompt disclosure。为 selection replacement、换行、emoji、mention/attachment preservation 和 disabled composer 编写 editor/controller tests。 | | |
| TASK-030 | 在 `AgentGUINode.labels.ts` 与 `en.agentGui.ts`、`zh-CN.agentGui.ts` 增加入口、标题、搜索、空态、表单、删除、冲突、重试和成功/失败文案;所有 quick-prompt 组件只消费 labels。 | | |
### Implementation Phase 5 — 验证边界、文档与回归
- **GOAL-005**: 验证 API、跨窗口同步、UI System 合规、焦点和现有 Composer disclosure 不回归。
| Task | Description | Completed | Date |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---- |
| TASK-031 | 更新 `docs/architecture/agent-gui-node.md` 和 `docs/architecture/agent-activity-packages.md`:quick-prompts 是 developer-gated optional Host capability 与 daemon product state,不属于 ActivityRuntime;记录 shared GUI、desktop adapter、preferences gate、tuttid 的所有权边界。 | | |
| TASK-032 | 先运行 `pnpm check:changed -- --dry-run` 检查 changed-aware lanes;实现稳定后仅运行一次最终 `pnpm check:changed`,并只为 dry-run 未覆盖的 OpenAPI/event generation check 或定向 package tests 增补命令。 | | |
| TASK-033 | 人工验证默认关闭、设置即时开关、workspace 与 standalone 两种 Agent window、窄窗口 available-height、长列表滚动、键盘导航、Dialog 往返、跨窗口 create/edit/delete、daemon 重启持久性和 conflict 恢复;确认选择永不自动发送。 | | |
| TASK-034 | 审计变更:AgentGUI 新代码不得出现深层 UI System imports、Radix 直引、原生交互元素或正文日志;`packages/ui/system` 应保持无 diff,feature flag 不新增 DB schema,生成文件与 schema 校验保持一致。 | | |
## 3. Alternatives
- **ALT-001**: 在 Popover 内直接新增/编辑。拒绝:长正文、校验、异步错误和键盘软输入会挤压固定高度列表,
也让 Popover 同时承担瞬时选择与持久编辑两种焦点模型。
- **ALT-002**: 所有操作都放进一个大型管理 Dialog。拒绝:高频“选一个并填入”需要额外一步,偏离输入框附近的
快捷入口目标;Dialog 适合低频管理,不适合作为每次选择的必经路径。
- **ALT-003**: 使用 inline editable list。拒绝:行内 Textarea、保存/取消、行菜单和滚动焦点互相竞争,
且在 400px 宽 Popover 中很难满足长文本编辑与可访问性。
- **ALT-004**: 存到 localStorage。拒绝:生命周期绑定 renderer/profile,无法由 tuttid 统一持久化和多窗口一致更新,
也绕过仓库对 durable product state 的所有权规则。
- **ALT-005**: 扩展 desktop preferences JSON。拒绝:提示词正文可能较大且敏感,整对象读写会扩大冲突与事件 payload,
无法提供实体级 version/CRUD。
- **ALT-006**: 把提示词放进 AgentGUIRuntime。拒绝:它不是 Session/Turn/Interaction canonical activity,
会污染 workspace engine 并让设备级数据错误地按 workspace 复制。
- **ALT-007**: 为本功能新增 PromptPicker/Modal/VirtualList primitive。拒绝:现有 Popover、Dialog、
ConfirmationDialog、ScrollArea 和表单组件已经覆盖需求;第一版最多 100 条,不需要 virtualization。
- **ALT-008**: 选择后自动发送。拒绝:提示词可能需要补变量、附上下文或修改;填入后由用户确认更安全且符合请求。
- **ALT-009**: 把入口默认开放,或放进面向所有用户的通用设置。拒绝:第一版仍需验证数据模型、编辑器插入与多窗口行为;
先用默认关闭的 developer flag 控制暴露,稳定后再通过删除 gate 正式发布,避免形成长期双重设置。
## 4. Dependencies
- **DEP-001**: `@tutti-os/ui-system` 保持现有 Popover、Dialog、ConfirmationDialog、ScrollArea、
DropdownMenu、Input、Textarea、Button、Tooltip、Spinner 与 system icons 公共导出。
- **DEP-002**: Agent rich-text editor 继续使用 TipTap,并保留 `plainTextToAgentRichTextInlineContent` 和
controlled `onChange` 同步路径。
- **DEP-003**: tuttid workspace SQLite store 是设备级 daemon 数据库,启动时会执行 append-only migrations。
- **DEP-004**: `pnpm generate:api` 根据 `tuttid.v1.yaml` 生成 Go/TypeScript bindings,
`pnpm generate:event-protocol` 生成 event TypeScript/Go contracts。
- **DEP-005**: desktop 的 `TuttidEventStreamClient` 支持订阅新的 global server-to-client topic,并能在
workspace 与 standalone renderer host composition 中复用。
- **DEP-006**: 现有 AgentHost provider/context 会把 optional `AgentHostInputApi` 通过
`toAgentHostRuntimeApi` 投影给 AgentGUI,缺失 capability 的 hosts 可继续工作。
- **DEP-007**: desktop preferences 已提供 `feature_flags_json`、`DesktopFeatureFlags`、`setFeatureFlags()`、
optimistic store 和 `preferences.desktop.updated` 跨窗口同步,能够承载默认关闭的 developer flag 而不改 schema。
## 5. Files
- **FILE-001**: `services/tuttid/biz/agentquickprompt/model.go` — 领域实体、inputs、校验常量和 errors。
- **FILE-002**: `services/tuttid/data/workspace/migrations_agent_quick_prompts.go` — 新表与索引 migration。
- **FILE-003**: `services/tuttid/data/workspace/migrations.go` — 注册 append-only migration。
- **FILE-004**: `services/tuttid/data/workspace/store.go` — 窄 store interface。
- **FILE-005**: `services/tuttid/data/workspace/sqlite_agent_quick_prompts.go` — SQLite CRUD 与并发 fence。
- **FILE-006**: `services/tuttid/data/workspace/sqlite_agent_quick_prompts_test.go` — 数据与 migration tests。
- **FILE-007**: `services/tuttid/service/agentquickprompt/service.go` — 业务规则、CRUD orchestration 与 publish-after-commit。
- **FILE-008**: `services/tuttid/service/agentquickprompt/service_test.go` — service validation/conflict/publisher tests。
- **FILE-009**: `services/tuttid/service/eventstream/agent_quick_prompt.go` — 失效事件 publisher。
- **FILE-010**: `services/tuttid/service/eventstream/catalog.go` — topic/validator 注册。
- **FILE-011**: `services/tuttid/service/eventstream/agent_quick_prompt_test.go` — payload privacy 与 catalog tests。
- **FILE-012**: `packages/events/protocol/definitions/agent/quickprompt.updated.event.json` — event source contract。
- **FILE-013**: `packages/events/protocol/src/generated/*` 与 `services/tuttid/api/events/generated/protocol.gen.go` — 脚本生成 event contracts。
- **FILE-014**: `services/tuttid/api/openapi/tuttid.v1.yaml` — quick-prompt REST schema/paths/errors。
- **FILE-015**: `services/tuttid/api/generated/*` 与 `packages/clients/tuttid-ts/src/generated/*` — 脚本生成 API bindings。
- **FILE-016**: `packages/clients/tuttid-ts/src/tuttidClient.ts` — 如生成器未提供 façade,则增加窄 CRUD methods。
- **FILE-017**: `services/tuttid/api/daemon_agent_quick_prompts.go` — HTTP/domain mapping。
- **FILE-018**: `services/tuttid/api/daemon_agent_quick_prompts_test.go` — handler/error/privacy tests。
- **FILE-019**: `services/tuttid/api/daemon.go` — service port。
- **FILE-020**: `services/tuttid/wiring.go` — store/service/publisher/API wiring。
- **FILE-021**: `packages/agent/gui/host/agentHostApi.ts` — optional shared Host capability and DTOs。
- **FILE-022**: `apps/desktop/src/renderer/src/features/workspace-agent/services/agentQuickPromptService.interface.ts` — desktop DI contract。
- **FILE-023**: `apps/desktop/src/renderer/src/features/workspace-agent/services/internal/desktopAgentQuickPromptService.ts` — snapshot、CRUD、event refresh。
- **FILE-024**: `apps/desktop/src/renderer/src/features/workspace-agent/services/internal/desktopAgentQuickPromptService.test.ts` — state/event/conflict tests。
- **FILE-025**: `apps/desktop/src/renderer/src/features/workspace-agent/services/registerWorkspaceAgentServices.ts` — service registration/lifecycle。
- **FILE-026**: `apps/desktop/src/renderer/src/features/workspace-agent/services/createDesktopAgentHostApi.ts` — Host projection。
- **FILE-027**: `apps/desktop/src/renderer/src/features/workspace-agent/services/createDesktopAgentHostApi.test.ts` — projection tests。
- **FILE-028**: `apps/desktop/src/renderer/src/features/workspace-agent/services/createDesktopAgentGUIWorkbenchHostInput.ts` — workbench composition。
- **FILE-029**: `apps/desktop/src/renderer/src/app/windows/workspace/createWorkspaceWindowContainer.ts`、`features/workspace-workbench/services/internal/contributions/agentGuiWorkbenchContributionFactory.ts`、`features/workspace-workbench/services/internal/workspaceAgentGuiContribution.ts` 与 `features/workspace-workbench/ui/StandaloneAgentWindow.tsx` — 同一 DI 实例的 workspace/standalone 接线与 dispose。
- **FILE-030**: `packages/agent/gui/agent-gui/agentGuiNode/composer/quickPrompts/useAgentQuickPromptLibrary.ts` — UI controller。
- **FILE-031**: `packages/agent/gui/agent-gui/agentGuiNode/composer/quickPrompts/AgentQuickPromptPopover.tsx` — 选择/搜索/列表管理入口。
- **FILE-032**: `packages/agent/gui/agent-gui/agentGuiNode/composer/quickPrompts/AgentQuickPromptEditorDialog.tsx` — 新增/编辑表单。
- **FILE-033**: `packages/agent/gui/agent-gui/agentGuiNode/composer/quickPrompts/AgentQuickPromptPopover.spec.tsx` — UI System、键盘与状态 tests。
- **FILE-034**: `packages/agent/gui/agent-gui/agentGuiNode/composer/ComposerFooter.tsx` 与 composition spec — trigger slot 与布局保护。
- **FILE-035**: `packages/agent/gui/agent-gui/agentGuiNode/composer/AgentComposer.tsx`、`AgentComposerView.tsx`、相关 types — controller/slot/disclosure composition。
- **FILE-036**: `packages/agent/gui/agent-gui/agentGuiNode/agentRichText/AgentRichTextEditor.types.ts` 与 `useAgentRichTextEditorHandle.ts` — selection insertion API。
- **FILE-037**: `packages/agent/gui/agent-gui/agentGuiNode/agentRichText/AgentRichTextEditor.spec.tsx` — 富文本保留与插入 tests。
- **FILE-038**: `packages/agent/gui/agent-gui/agentGuiNode/AgentGUINode.labels.ts` — typed UI labels。
- **FILE-039**: `packages/agent/gui/app/renderer/i18n/locales/en.agentGui.ts` 与 `zh-CN.agentGui.ts` — 本地化文案。
- **FILE-040**: `docs/architecture/agent-gui-node.md` 与 `docs/architecture/agent-activity-packages.md` — ownership/data-flow 文档。
- **FILE-041**: `apps/desktop/src/shared/featureFlags/catalog.ts` 与现有 catalog test — 新 developer flag、默认值和解析测试。
- **FILE-042**: `apps/desktop/src/renderer/src/features/workspace-workbench/ui/WorkspaceDeveloperSettingsSection.tsx` 与相关 settings test — UI System Switch、pending/disabled/save 路径。
- **FILE-043**: `apps/desktop/src/shared/i18n/locales/en.ts` 与 `zh-CN.ts` — 开发者设置的快捷提示词 flag 文案。
- **FILE-044**: `apps/desktop/src/renderer/src/features/desktop-preferences/services/internal/desktopPreferencesService.test.ts` — flag 持久化、optimistic rollback 与 preferences event 后的 authoritative state 测试;无需修改 SQLite migration 文件。
## 6. Testing
- **TEST-001**: OpenAPI/event generation check 成功,生成文件无手工差异,新增 topic 在 TypeScript 和 Go catalog 中一致。
- **TEST-002**: Go unit/integration tests 覆盖 list/create/update/delete、validation、100 条上限、UUID/时间注入、版本冲突、
publish-after-commit、publisher failure 和 SQLite reopen。
- **TEST-003**: API handler tests 覆盖 201/200/204、empty body、malformed ID、field/limit validation、404、409、503;断言响应错误与日志
不包含提示词正文。
- **TEST-004**: desktop service tests 覆盖 lazy load、single-flight、optimistic pending marker、成功快照、失败保留旧数据、
自窗口去重、跨窗口 event coalescing、dispose 和 conflict refresh。
- **TEST-005**: AgentGUI component tests 覆盖 capability 缺失隐藏、入口位置、420px/available-height 布局、ScrollArea、搜索排序、
行按钮不嵌套、Dialog 往返、删除确认、retry 与 disabled states。
- **TEST-006**: Rich editor tests 覆盖空输入插入、光标中间插入、替换选区、多行/emoji、existing mention/attachment preservation、
focus restore、controlled change 和不触发 submit。
- **TEST-007**: Accessibility tests 覆盖入口/行菜单/编辑/删除的 accessible name、Tab 顺序、Arrow/Enter/Escape、Dialog focus trap
和 destructive confirmation;鼠标与键盘均可完成完整流程。
- **TEST-008**: Disclosure regression 覆盖 quick-prompt、slash、mention、status 和 review 同时最多打开一个,Popover/Dialog portal
不被 composer overflow 裁切。
- **TEST-009**: 人工双窗口测试:窗口 A 新增/编辑/删除后窗口 B 自动刷新;并发编辑触发冲突且不丢草稿;daemon 重启后数据仍在。
- **TEST-010**: 运行 changed-aware dry-run 后执行所选定向 lanes,并以一次最终 `pnpm check:changed` 收口;确认
`packages/ui/system` 无 diff,package business files 均小于 800 行。
- **TEST-011**: Feature gate tests 覆盖 key 缺失默认关闭、显式 false、显式 true、保存失败回滚、跨窗口 preferences event、
无重启即时显示/隐藏,以及关闭时 Popover/Dialog 被关闭且不再发出 list/mutation。
- **TEST-012**: Database migration audit 断言 feature flag 仅写入现有 `desktop_preferences.feature_flags_json`,
quick-prompt 数据表 migration 之外没有新增 preference column/table;关闭与重新开启不会删除已保存提示词。
## 7. Risks & Assumptions
- **RISK-001**: Radix Popover 与 Dialog 连续切换可能造成焦点跳回 trigger 或触发 outside-dismiss。通过单一 controller 状态机、
互斥 mode 和显式 return-focus target 解决,并用键盘 tests 固化。
- **RISK-002**: 编辑器 selection 在用户打开 Popover 后可能因焦点迁移而丢失。打开前捕获 TipTap selection bookmark,选择时校验
editor 仍可用并恢复该 selection;若文档在期间改变,则退化为当前光标处插入而不是错误覆盖。
- **RISK-003**: 多窗口事件与本地 mutation response 可能造成重复刷新或旧响应覆盖新快照。desktop service 使用 request generation、
single-flight invalidation 和 committed revision,只提交最新 generation 的结果。
- **RISK-004**: 420px 固定高度在小窗口或输入法候选区附近不可用。以固定目标高度配合 Radix available-height max 降级,列表仍是唯一滚动区。
- **RISK-005**: 32 KiB×100 的极端列表响应约 3.2 MiB,首次打开可能有延迟。第一版数量可控并 lazy load;若真实数据证明有性能问题,
后续再引入摘要 list + detail fetch,而不是预先增加协议复杂度。
- **RISK-006**: 提示词可能包含秘密,renderer 内存和本地 SQLite 仍有暴露面。第一版遵循现有本地 daemon 信任边界,禁止 telemetry/log/event;
数据库加密或 OS credential storage 不在本功能内暗示提供。
- **RISK-007**: 共享 AgentGUI 可能运行在不支持新 API 的 host。capability 为 optional,组件 fail-closed 隐藏;desktop version skew 通过
503/404 capability probe 进入 unavailable 状态,不影响 Composer 基础功能。
- **RISK-008**: 用户在编辑 Dialog 中关闭 feature flag 时可能误以为草稿已保存。监听 gate transition 后先取消未发 mutation、关闭 Dialog,
使用不含正文的提示说明功能已关闭;已经收到 daemon 成功响应的数据仍保留,下次开启可见。
- **ASSUMPTION-001**: “快捷提示词”是用户自建的设备级个人库,不需要账户级或团队级同步。
- **ASSUMPTION-002**: 第一版最大 100 条足以支持固定高度搜索选择,不需要分页或虚拟列表。
- **ASSUMPTION-003**: 选择语义是替换当前文本 selection;没有 selection 时在当前/捕获光标处插入,不覆盖整个 Composer 草稿。
- **ASSUMPTION-004**: 入口在所有支持 quickPrompts capability 的 provider/permission mode 下可用,但当 composer hard-disabled 时入口 disabled。
- **ASSUMPTION-005**: Developer flag 只控制桌面端能力暴露和网络调用,不删除 API/schema 或已有 quick-prompt rows;正式发布时通过移除 gate
将默认行为切为开启,而不是迁移每个用户的 flag 值。
## 8. Related Specifications / Further Reading
- `AGENTS.md`
- `packages/agent/gui/AGENTS.md`
- `apps/desktop/AGENTS.md`
- `services/tuttid/AGENTS.md`
- `packages/ui/system/agent/tutti-ui-system/SKILL.md`
- `packages/ui/system/agent/tutti-ui-system/references/use-existing-component.md`
- `docs/architecture/agent-gui-node.md`
- `docs/architecture/agent-activity-packages.md`
- `docs/conventions/testing.md`
- `packages/agent/gui/agent-gui/agentGuiNode/composer/ComposerFooter.tsx`
- `packages/agent/gui/host/agentHostApi.ts`
- `apps/desktop/src/renderer/src/features/workspace-agent/services/createDesktopAgentHostApi.ts`
- `services/tuttid/api/openapi/tuttid.v1.yaml`
- `services/tuttid/service/eventstream/catalog.go`
+194
View File
@@ -0,0 +1,194 @@
---
goal: "Move desktop stable and RC update discovery to the existing CloudFront static release feed so Draft RC packages remain updateable."
version: "1.0"
date_created: "2026-07-13"
last_updated: "2026-07-13"
owner: "Tutti desktop"
status: "In progress"
tags: [refactor, desktop, electron-updater, release, s3, cloudfront, rc]
---
# Introduction
![Status: In%20progress](https://img.shields.io/badge/status-In%20progress-yellow)
The desktop release workflow already uploads signed assets and updater YAML to
CloudFront-backed S3 paths. Stable writes `<base>/latest.json`; RC writes
`<base>/channels/rc/latest.json`; each immutable `<base>/<tag>/` directory
contains the channel YAML and ZIP required by `electron-updater`.
The desktop application still uses GitHub as its updater provider. Its custom
fallback reads the public GitHub Releases Atom feed for legacy
`tutti-desktop-v*` tags, but Draft RC releases are intentionally absent from
that feed. This refactor makes the static release metadata the single runtime
discovery source without making RC GitHub Releases public or changing release
ordering.
Implementation is complete in the accompanying change set. The remaining
release-environment verification is the Draft RC and stable acceptance path in
TEST-005 and TEST-006, which can run only after a signed release is produced.
## 1. Requirements & Constraints
- **REQ-001**: Resolve stable update metadata from `<base>/latest.json`.
- **REQ-002**: Resolve RC update metadata from
`<base>/channels/rc/latest.json`, independently of GitHub Draft visibility.
- **REQ-003**: Before every `electron-updater` check, set a generic provider
URL to the validated immutable version directory, then let the updater read
`latest-mac.yml` for stable or `rc-mac.yml` for RC.
- **REQ-004**: Preserve the current update IPC state model, update policy,
scheduled checks, manual/automatic download behavior, and macOS support
guard.
- **REQ-005**: Surface invalid static metadata as the existing update error
state; do not fall back to GitHub Releases.
- **SEC-001**: Accept only HTTPS metadata whose normalized base URL equals the
packaged CloudFront release prefix; require the selected channel, tag, and
semantic version to agree before setting a feed URL.
- **CON-001**: Support only existing application channels `stable` and `rc`.
Beta metadata remains producer-only until the settings contract exposes it.
- **CON-002**: Keep concrete stable releases and the `stable` alias public;
keep RC and beta GitHub Releases as Draft.
- **CON-003**: Do not change GitHub Release ordering, Feishu notification,
asset direct-download links, or the floating `stable` alias in this work.
- **CON-004**: Treat `latest.json` as a locator only. Download integrity and
code-signing verification remain `electron-updater` responsibilities.
- **CON-005**: The production CloudFront prefix is a public packaged
compatibility endpoint, not a user-supplied runtime environment variable.
## 2. Implementation Steps
### Implementation Phase 1 — Define the static-feed resolver
- **GOAL-001**: Create a validated, deterministic mapping from the selected
application channel to its metadata pointer and immutable generic feed URL.
| Task | Description | Completed | Date |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---- |
| TASK-001 | Add `apps/desktop/src/main/update/desktopReleaseFeed.ts`. Export one production CloudFront base URL constant, normalize it without a trailing slash, and map `stable` to `/latest.json` and `rc` to `/channels/rc/latest.json`. | | |
| TASK-002 | In `desktopReleaseFeed.ts`, implement a resolver using `outboundFetch` that parses the producer schema `tutti.desktop.release.latest.v1` emitted by `apps/desktop/scripts/build-release-latest.mjs`. Return `{ feedUrl, updaterChannel, version, tag, releasedAt }`, where `feedUrl` is `<base>/<encoded-tag>` and `updaterChannel` is `latest` or `rc`. | | |
| TASK-003 | Reject non-object JSON, an unknown schema, empty tag/version, a non-HTTPS or different base URL, a selected-channel mismatch, and a tag/version semantic-version mismatch before any feed configuration occurs. | | |
| TASK-004 | Add `apps/desktop/src/main/update/desktopReleaseFeed.test.ts` with fixtures for stable/RC resolution, URL normalization/encoding, malformed JSON, invalid schema, wrong origin, wrong channel, and invalid tag/version pairs. | | |
### Implementation Phase 2 — Configure Electron before checking
- **GOAL-002**: Replace GitHub discovery with the static-feed resolver while
retaining the existing user-visible update lifecycle.
| Task | Description | Completed | Date |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---- |
| TASK-005 | Extend the internal `AppUpdateDriver` in `apps/desktop/src/main/update/appUpdateService.ts` with `setFeedUrl(url: string): void`. Implement it in `createElectronAppUpdateDriver` using `autoUpdater.setFeedURL({ provider: "generic", url })`; extend the fake driver in the companion test to capture calls. | | |
| TASK-006 | Replace the `prefixedReleaseResolver` option and `activeCheckCanUsePrefixedFallback` state with an injectable static-feed resolver. In the existing single-flight `checkForUpdates` path, resolve metadata and invoke `setFeedUrl` before `resolvedDriver.checkForUpdates()`. Preserve the configured updater channel, prerelease permission, auto-download flags, and `forceDevUpdateConfig`. | | |
| TASK-007 | Route resolver errors through `applyUpdaterError`, clear the single-flight promise, and return/throw consistently with current failed checks. Do not invoke GitHub after a static pointer failure and do not preserve a stale `available` result. | | |
| TASK-008 | Remove `apps/desktop/src/main/update/prefixedDesktopReleaseResolver.ts`, its test file, the Atom parsing/version comparison helpers used only by it, and the special “No published versions on GitHub” logger suppression. | | |
| TASK-009 | Update `apps/desktop/src/main/update/appUpdateService.test.ts` to assert stable and RC feed URLs are configured before `checkForUpdates`, resolver failure produces `error`, concurrent checks share one resolver call, and no legacy GitHub fallback runs. | | |
### Implementation Phase 3 — Align packaged configuration and release contract
- **GOAL-003**: Ensure packaged updater configuration, workflow publication,
and operator documentation describe the same static-feed architecture.
| Task | Description | Completed | Date |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---- |
| TASK-010 | Change the `build.publish` entry in `apps/desktop/package.json` from GitHub to the production generic CloudFront base. The generated `app-update.yml` must describe the same provider that runtime checks override to an immutable tag directory. | | |
| TASK-011 | Extend `tools/scripts/desktop-release-config.test.mjs` to assert the release workflow uploads immutable assets and generated updater YAML before publishing stable `latest.json` or RC `channels/rc/latest.json`, and retains the RC pointer publication path. | | |
| TASK-012 | Modify `.github/workflows/desktop-release.yml` only if TASK-011 exposes a missing ordering guarantee; preserve its existing asset upload and 60-second pointer-cache behavior otherwise. | | |
| TASK-013 | Update `docs/conventions/desktop-release.md` to state that the desktop runtime consumes the stable/RC static pointers, that Draft RC is expected, and that operators must validate the pointer, YAML, and ZIP before announcing a release. | | |
## 3. Alternatives
- **ALT-001**: Publish RC GitHub Releases. Rejected because it conflicts with
the deliberately private prerelease policy and recreates the public release
list ordering problem.
- **ALT-002**: Keep the GitHub Atom/API fallback. Rejected because Draft
releases are not a reliable public discovery source and current tags no
longer match its legacy prefix.
- **ALT-003**: Mirror `rc-mac.yml` at the mutable CloudFront root. Rejected
because it introduces cache and channel-collision risk; a short-lived JSON
pointer followed by an immutable tag directory is auditable and safe.
- **ALT-004**: Build a new update backend service. Deferred because existing
CloudFront storage, release metadata, updater YAML, and signed artifacts
already satisfy the discovery requirement.
- **ALT-005**: Use GitHub for stable and static discovery only for RC.
Rejected because two discovery systems produce different availability and
error behavior.
## 4. Dependencies
- **DEP-001**: The public production CloudFront release prefix remains
available over HTTPS and backward compatible for installed clients.
- **DEP-002**: `.github/workflows/desktop-release.yml` continues to upload
versioned assets and `*-mac.yml` before mutating a channel pointer.
- **DEP-003**: `electron-updater` supports a generic provider configured with
`setFeedURL`; the currently pinned package version is `^6.8.3`.
- **DEP-004**: macOS release packaging continues to generate signed ZIP and
channel-specific updater YAML files.
## 5. Files
- **FILE-001**: `apps/desktop/src/main/update/desktopReleaseFeed.ts` — new
resolver, metadata type, validation, pointer URL mapping, and feed URL
construction.
- **FILE-002**: `apps/desktop/src/main/update/desktopReleaseFeed.test.ts` —
new unit tests for resolver behavior and validation failures.
- **FILE-003**: `apps/desktop/src/main/update/appUpdateService.ts` — driver
feed operation, resolver integration, and removal of GitHub fallback.
- **FILE-004**: `apps/desktop/src/main/update/appUpdateService.test.ts` —
integration tests for feed-before-check and update-state errors.
- **FILE-005**: `apps/desktop/src/main/update/prefixedDesktopReleaseResolver.ts`
— delete obsolete GitHub Atom resolver.
- **FILE-006**: `apps/desktop/src/main/update/prefixedDesktopReleaseResolver.test.ts`
— delete obsolete resolver tests.
- **FILE-007**: `apps/desktop/package.json` — change packaged publish provider
from GitHub to generic static feed.
- **FILE-008**: `tools/scripts/desktop-release-config.test.mjs` — assert static
release publication ordering.
- **FILE-009**: `.github/workflows/desktop-release.yml` — only change if the
workflow test identifies a missing producer guarantee.
- **FILE-010**: `docs/conventions/desktop-release.md` — document consumer
behavior and release verification.
## 6. Testing
- **TEST-001**: Run narrowed desktop tests for `desktopReleaseFeed` and
`appUpdateService`; verify static pointer resolution and feed-before-check
behavior for both channels.
- **TEST-002**: Run `pnpm --filter @tutti-os/desktop typecheck` after changing
the driver and resolver interfaces.
- **TEST-003**: Run `node --test tools/scripts/desktop-release-latest.test.mjs tools/scripts/desktop-release-config.test.mjs` to verify producer schema and workflow invariants.
- **TEST-004**: Run `pnpm lint` and the repository’s changed-aware validation
lane for affected desktop/workflow files.
- **TEST-005**: Publish a Draft RC in the release environment and verify HTTP
200 for `channels/rc/latest.json`, `<tag>/rc-mac.yml`, and the referenced ZIP;
install the preceding RC and confirm it discovers, downloads, and installs
without GitHub Releases access.
- **TEST-006**: Publish a stable build and repeat TEST-005 using `latest.json`
and `latest-mac.yml`; use an invalid-pointer test fixture to confirm the UI
enters `error` rather than falling back to GitHub or accepting an arbitrary
URL.
## 7. Risks & Assumptions
- **RISK-001**: The mutable pointer can be visible briefly before a CDN edge
observes its newly uploaded dependencies. Mitigate by publishing immutable
assets/YAML first, retaining the current 60-second pointer cache, and relying
on scheduled retries.
- **RISK-002**: Moving the CloudFront prefix would strand already-installed
clients. Treat it as a compatibility endpoint; keep the old endpoint or ship
a bridge release before any move.
- **RISK-003**: A malformed pointer could select an unintended feed. Validate
HTTPS, exact base prefix, selected channel, and tag/version consistency;
retain platform signing verification for binaries.
- **ASSUMPTION-001**: The first build containing this refactor may need to be
installed by RC testers from the existing direct-download/Feishu route,
because older installed clients still use GitHub discovery.
- **ASSUMPTION-002**: macOS is the active release target. The resolver is
platform-neutral, but Windows/Linux acceptance must wait until those updater
YAML and artifact paths are published.
## 8. Related Specifications / Further Reading
- `docs/conventions/desktop-release.md`
- `.github/workflows/desktop-release.yml`
- `apps/desktop/scripts/build-release-latest.mjs`
- `apps/desktop/src/main/update/appUpdateService.ts`
- [electron-updater AppUpdater API](https://www.electron.build/docs/api/electron-updater.class.appupdater/)