Merge pull request #3460 from bobleer/feat/desktop-cards

feat(desktop-cards): show persistent glanceable cards outside the main window

Author: bobleer

design-system/apps/design-lab/src/i18n/semanticToolMessages.ts

@@ -19,6 +19,7 @@ export const semanticToolEn = {
   "flowChat.builtin.tools.PublishMiniApp": "Submit Mini App",
   "flowChat.builtin.tools.PublishAppearance": "Submit Skin",
   "flowChat.builtin.tools.Playbook": "Read operation guide",
+  "flowChat.builtin.tools.DesktopCard": "Desktop card",
   "flowChat.builtin.fields.results": "Results",
   "flowChat.builtin.fields.objective": "Objective",
   "flowChat.builtin.fields.state": "State",
@@ -120,6 +121,9 @@ export const semanticToolEn = {
   "flowChat.builtin.fields.checksPending": "Checks pending",
   "flowChat.builtin.fields.author": "Author",
   "flowChat.builtin.fields.lastOutcome": "Last transaction outcome",
+  "flowChat.builtin.fields.card": "Card ID",
+  "flowChat.builtin.fields.dataSource": "Data source",
+  "flowChat.builtin.fields.visibility": "Visibility",
   "flowChat.builtin.states.active": "Active",
   "flowChat.builtin.states.running": "Running",
   "flowChat.builtin.states.complete": "Done",
@@ -159,13 +163,15 @@ export const semanticToolEn = {
   "flowChat.builtin.states.managed": "Managed worktree",
   "flowChat.builtin.states.permanent": "Permanent worktree",
   "flowChat.builtin.states.external": "External worktree",
+  "flowChat.builtin.states.cardCreated": "Created and shown",
   "flowChat.builtin.rawResult": "Recorded result details",
   "flowChat.builtin.directChildren": "Direct child agents",
   "flowChat.builtin.deleteAgentScope": "Deletes the selected agents and their descendants, including their sessions and pending results. Active work is cancelled.",
   "flowChat.builtin.portMoved": "The requested local port was occupied. Use the actual address shown above.",
   "flowChat.builtin.runtimeNotified": "Open Mini App runtimes were notified to reload.",
   "flowChat.builtin.reviewPending": "The submission is awaiting marketplace review. Follow its status in My submissions.",
   "flowChat.builtin.playbookInstructions": "These are the resolved instructions. Their steps are executed through subsequent tool calls.",
+  "flowChat.builtin.desktopCard.visible": "Shown on desktop",
   "flowChat.builtin.samples.goal": "Improve keyboard navigation",
   "flowChat.builtin.samples.analysis": "The page contains a navigation rail, a summary and a results table.",
   "flowChat.builtin.samples.error": "The host could not finish this operation. Recorded details remain available.",
@@ -181,7 +187,8 @@ export const semanticToolEn = {
   "component.FrontendWorkbenchToolCard.description": "Frontend customization",
   "component.MiniAppFinalizeToolCard.description": "Update Mini App",
   "component.MarketplacePublishToolCard.description": "Submit Mini App",
-  "component.PlaybookToolCard.description": "Read operation guide"
+  "component.PlaybookToolCard.description": "Read operation guide",
+  "component.DesktopCardToolCard.description": "Desktop card"
 } as const;
 
 export const semanticToolZhCN = {
@@ -205,6 +212,7 @@ export const semanticToolZhCN = {
   "flowChat.builtin.tools.PublishMiniApp": "提交小应用审核",
   "flowChat.builtin.tools.PublishAppearance": "提交皮肤审核",
   "flowChat.builtin.tools.Playbook": "读取操作流程",
+  "flowChat.builtin.tools.DesktopCard": "小卡片",
   "flowChat.builtin.fields.results": "结果",
   "flowChat.builtin.fields.objective": "目标",
   "flowChat.builtin.fields.state": "状态",
@@ -306,6 +314,9 @@ export const semanticToolZhCN = {
   "flowChat.builtin.fields.checksPending": "待完成检查数",
   "flowChat.builtin.fields.author": "作者",
   "flowChat.builtin.fields.lastOutcome": "上次事务结果",
+  "flowChat.builtin.fields.card": "卡片 ID",
+  "flowChat.builtin.fields.dataSource": "数据来源",
+  "flowChat.builtin.fields.visibility": "显示状态",
   "flowChat.builtin.states.active": "进行中",
   "flowChat.builtin.states.running": "运行中",
   "flowChat.builtin.states.complete": "已完成",
@@ -345,13 +356,15 @@ export const semanticToolZhCN = {
   "flowChat.builtin.states.managed": "托管工作树",
   "flowChat.builtin.states.permanent": "永久工作树",
   "flowChat.builtin.states.external": "外部工作树",
+  "flowChat.builtin.states.cardCreated": "已创建并显示",
   "flowChat.builtin.rawResult": "原始结果详情",
   "flowChat.builtin.directChildren": "直属子代理",
   "flowChat.builtin.deleteAgentScope": "删除所选子代理及其后代的会话和待处理结果，并取消进行中的工作。",
   "flowChat.builtin.portMoved": "请求的本地端口已被占用，请使用上方显示的实际地址。",
   "flowChat.builtin.runtimeNotified": "已通知打开的小应用重新加载。",
   "flowChat.builtin.reviewPending": "投稿正在等待市场审核，可在“我的投稿”查看进度。",
   "flowChat.builtin.playbookInstructions": "这里显示的是已载入的操作步骤，实际执行由后续工具调用完成。",
+  "flowChat.builtin.desktopCard.visible": "显示在桌面",
   "flowChat.builtin.samples.goal": "完善键盘导航",
   "flowChat.builtin.samples.analysis": "页面包含导航栏、摘要和结果表格。",
   "flowChat.builtin.samples.error": "主机未能完成此操作，仍可查看已记录的详情。",
@@ -367,7 +380,8 @@ export const semanticToolZhCN = {
   "component.FrontendWorkbenchToolCard.description": "界面定制",
   "component.MiniAppFinalizeToolCard.description": "更新小应用",
   "component.MarketplacePublishToolCard.description": "提交小应用审核",
-  "component.PlaybookToolCard.description": "读取操作流程"
+  "component.PlaybookToolCard.description": "读取操作流程",
+  "component.DesktopCardToolCard.description": "小卡片"
 } as const;
 
 export const semanticToolZhTW = {
@@ -391,6 +405,7 @@ export const semanticToolZhTW = {
   "flowChat.builtin.tools.PublishMiniApp": "提交小應用程式審核",
   "flowChat.builtin.tools.PublishAppearance": "提交外觀審核",
   "flowChat.builtin.tools.Playbook": "讀取操作流程",
+  "flowChat.builtin.tools.DesktopCard": "小卡片",
   "flowChat.builtin.fields.results": "結果",
   "flowChat.builtin.fields.objective": "目標",
   "flowChat.builtin.fields.state": "狀態",
@@ -492,6 +507,9 @@ export const semanticToolZhTW = {
   "flowChat.builtin.fields.checksPending": "待完成檢查數",
   "flowChat.builtin.fields.author": "作者",
   "flowChat.builtin.fields.lastOutcome": "上次交易結果",
+  "flowChat.builtin.fields.card": "卡片 ID",
+  "flowChat.builtin.fields.dataSource": "資料來源",
+  "flowChat.builtin.fields.visibility": "顯示狀態",
   "flowChat.builtin.states.active": "進行中",
   "flowChat.builtin.states.running": "執行中",
   "flowChat.builtin.states.complete": "已完成",
@@ -531,13 +549,15 @@ export const semanticToolZhTW = {
   "flowChat.builtin.states.managed": "受管理工作樹",
   "flowChat.builtin.states.permanent": "永久工作樹",
   "flowChat.builtin.states.external": "外部工作樹",
+  "flowChat.builtin.states.cardCreated": "已建立並顯示",
   "flowChat.builtin.rawResult": "原始結果詳細資料",
   "flowChat.builtin.directChildren": "直屬子代理",
   "flowChat.builtin.deleteAgentScope": "刪除所選子代理及其後代的工作階段和待處理結果，並取消進行中的工作。",
   "flowChat.builtin.portMoved": "要求的本機連接埠已被占用，請使用上方顯示的實際位址。",
   "flowChat.builtin.runtimeNotified": "已通知開啟的小應用程式重新載入。",
   "flowChat.builtin.reviewPending": "投稿正在等待市集審核，可在「我的投稿」檢視進度。",
   "flowChat.builtin.playbookInstructions": "此處顯示已載入的操作步驟，實際執行由後續工具呼叫完成。",
+  "flowChat.builtin.desktopCard.visible": "顯示在桌面",
   "flowChat.builtin.samples.goal": "完善鍵盤導覽",
   "flowChat.builtin.samples.analysis": "頁面包含導覽列、摘要與結果表格。",
   "flowChat.builtin.samples.error": "主機未能完成此操作，仍可檢視已記錄的詳情。",
@@ -553,5 +573,6 @@ export const semanticToolZhTW = {
   "component.FrontendWorkbenchToolCard.description": "介面自訂",
   "component.MiniAppFinalizeToolCard.description": "更新小應用程式",
   "component.MarketplacePublishToolCard.description": "提交小應用程式審核",
-  "component.PlaybookToolCard.description": "讀取操作流程"
+  "component.PlaybookToolCard.description": "讀取操作流程",
+  "component.DesktopCardToolCard.description": "小卡片"
 } as const;

design-system/apps/design-lab/src/preview/FlowChatMockTools.tsx

@@ -14,6 +14,7 @@ const groupForTool = {
   ListMCPResources: 'execution', ReadMCPResource: 'execution', ListMCPPrompts: 'execution', GetMCPPrompt: 'execution',
   Worktree: 'files', PortForward: 'execution', ReviewPlatform: 'collaboration', FrontendWorkbench: 'web',
   FinalizeMiniApp: 'web', PublishMiniApp: 'web', PublishAppearance: 'web', Playbook: 'execution',
+  DesktopCard: 'collaboration',
   Read: 'files', Write: 'files', Edit: 'files', Delete: 'files', Grep: 'files', Glob: 'files', LS: 'files',
   GetFileDiff: 'files', view_image: 'files',
   ListModels: 'execution', ControlHub: 'web',

design-system/apps/design-lab/src/preview/SemanticToolCardPreview.tsx

@@ -1,9 +1,10 @@
 import { useState } from 'react';
-import { Target, Users, History, ScanEye, Clock, FolderSearch, GitBranch, Route, GitPullRequest, PanelsTopLeft, RefreshCw, Upload, Workflow } from 'lucide-react';
+import { Target, Users, History, ScanEye, Clock, FolderSearch, GitBranch, Route, GitPullRequest, PanelsTopLeft, RefreshCw, Upload, Workflow, AppWindow } from 'lucide-react';
 import {
   GoalToolCard, AgentRosterToolCard, SessionHistoryToolCard, ImageAnalysisToolCard, TimeToolCard,
   McpResourceToolCard, WorktreeToolCard, PortForwardToolCard, ReviewPlatformToolCard,
   FrontendWorkbenchToolCard, MiniAppFinalizeToolCard, MarketplacePublishToolCard, PlaybookToolCard,
+  DesktopCardToolCard,
   type SemanticToolCardProps,
 } from '@openbitfun/ui/flow-chat';
 import { toolsForComponent } from '@openbitfun/flow-chat-presentation/registry';
@@ -12,20 +13,21 @@ import type { FlowChatPreviewDefinition } from './FlowChatPreviewRegistry';
 
 const views = { GoalToolCard, AgentRosterToolCard, SessionHistoryToolCard, ImageAnalysisToolCard, TimeToolCard,
   McpResourceToolCard, WorktreeToolCard, PortForwardToolCard, ReviewPlatformToolCard,
-  FrontendWorkbenchToolCard, MiniAppFinalizeToolCard, MarketplacePublishToolCard, PlaybookToolCard };
+  FrontendWorkbenchToolCard, MiniAppFinalizeToolCard, MarketplacePublishToolCard, PlaybookToolCard, DesktopCardToolCard };
 type Name = keyof typeof views;
 const icons = { GoalToolCard: Target, AgentRosterToolCard: Users, SessionHistoryToolCard: History,
   ImageAnalysisToolCard: ScanEye, TimeToolCard: Clock, McpResourceToolCard: FolderSearch, WorktreeToolCard: GitBranch,
   PortForwardToolCard: Route, ReviewPlatformToolCard: GitPullRequest, FrontendWorkbenchToolCard: PanelsTopLeft,
-  MiniAppFinalizeToolCard: RefreshCw, MarketplacePublishToolCard: Upload, PlaybookToolCard: Workflow };
+  MiniAppFinalizeToolCard: RefreshCw, MarketplacePublishToolCard: Upload, PlaybookToolCard: Workflow,
+  DesktopCardToolCard: AppWindow };
 
 function SemanticPreview({ component, interactive, specimen, state }: Parameters<FlowChatPreviewDefinition['render']>[0] & { component: Name }) {
   const { t } = useI18n();
   const [expanded, setExpanded] = useState(state === 'expanded' || state === 'error');
   const text = (key: string) => t(`flowChat.builtin.${key}` as MessageKey);
   const tool = specimen?.tool ?? toolsForComponent(component)[0] ?? component;
   const prominent = ['create_goal', 'update_goal', 'AgentDelete', 'Worktree', 'PortForward', 'ReviewPlatform',
-    'FrontendWorkbench', 'FinalizeMiniApp', 'PublishMiniApp', 'PublishAppearance'].includes(tool);
+    'FrontendWorkbench', 'FinalizeMiniApp', 'PublishMiniApp', 'PublishAppearance', 'DesktopCard'].includes(tool);
   const props: SemanticToolCardProps = {
     action: text(`tools.${tool}`), status: state === 'loading' ? 'running' : state === 'error' ? 'error' : 'completed',
     attention: prominent ? 'prominent' : 'ambient', isExpanded: expanded,
@@ -75,6 +77,11 @@ function SemanticPreview({ component, interactive, specimen, state }: Parameters
     case 'PlaybookToolCard':
       props.summary = 'Review'; props.ordered = true; props.recordsLabel = text('fields.steps'); props.notice = text('playbookInstructions');
       props.records = [{ key: '1', title: 'browser.snapshot' }, { key: '2', title: 'browser.read_article' }]; break;
+    case 'DesktopCardToolCard':
+      props.summary = 'PR #42 · checks';
+      props.fields = [field('card', 'pr-42-checks'), field('template', 'metrics'),
+        field('dataSource', 'https://api.github.com/repos/openbitfun/app/pulls/42'), field('visibility', text('desktopCard.visible'))];
+      props.outcome = { label: text('states.cardCreated'), tone: 'success' }; break;
   }
   if (props.status !== 'completed') props.outcome = undefined;
   if (component === 'AgentRosterToolCard') return <AgentRosterToolCard {...props} deleting={tool === 'AgentDelete'} />;
@@ -99,5 +106,5 @@ export const semanticToolCardPreviews = {
   WorktreeToolCard: definition('WorktreeToolCard'), PortForwardToolCard: definition('PortForwardToolCard'),
   ReviewPlatformToolCard: definition('ReviewPlatformToolCard'), FrontendWorkbenchToolCard: definition('FrontendWorkbenchToolCard'),
   MiniAppFinalizeToolCard: definition('MiniAppFinalizeToolCard'), MarketplacePublishToolCard: definition('MarketplacePublishToolCard'),
-  PlaybookToolCard: definition('PlaybookToolCard'),
+  PlaybookToolCard: definition('PlaybookToolCard'), DesktopCardToolCard: definition('DesktopCardToolCard'),
 } satisfies Record<Name, FlowChatPreviewDefinition>;

design-system/packages/ui/src/flow-chat/tool-cards/SemanticToolCards.meta.ts

@@ -80,4 +80,9 @@ export const semanticToolCardMetas = [
     description: "Resolved operation guides and ordered steps, independent of execution.",
     props, states, tokens,
   },
+  {
+    category: "flow-chat", name: "DesktopCardToolCard", maturity: "stable",
+    description: "Desktop card creation, visibility, refresh and preset results.",
+    props, states, tokens,
+  },
 ] as const satisfies readonly ComponentMeta[];

design-system/packages/ui/src/flow-chat/tool-cards/SemanticToolCards.tsx

@@ -200,3 +200,6 @@ export function MarketplacePublishToolCard({ appearance = false, ...props }: Sem
 export function PlaybookToolCard(props: SemanticToolCardProps) {
   return <SemanticToolCard {...props} identity="playbook" iconName="workflow" />;
 }
+export function DesktopCardToolCard(props: SemanticToolCardProps) {
+  return <SemanticToolCard {...props} identity="desktop-card" iconName="floating-window" />;
+}

design-system/packages/ui/src/flow-chat/tool-cards/index.ts

@@ -2,6 +2,7 @@ export {
   GoalToolCard, AgentRosterToolCard, SessionHistoryToolCard, ImageAnalysisToolCard, TimeToolCard,
   McpResourceToolCard, WorktreeToolCard, PortForwardToolCard, ReviewPlatformToolCard,
   FrontendWorkbenchToolCard, MiniAppFinalizeToolCard, MarketplacePublishToolCard, PlaybookToolCard,
+  DesktopCardToolCard,
   type SemanticToolCardProps, type SemanticToolCardAction, type SemanticToolCardRecord, type SemanticToolCardSection, type SemanticToolCardField,
 } from "./SemanticToolCards";
 export {

design-system/packages/ui/tests/registry.test.mjs

@@ -14,6 +14,7 @@ test("registry exposes only the formal stable components", () => {
       "GoalToolCard", "AgentRosterToolCard", "SessionHistoryToolCard", "ImageAnalysisToolCard", "TimeToolCard",
       "McpResourceToolCard", "WorktreeToolCard", "PortForwardToolCard", "ReviewPlatformToolCard", "FrontendWorkbenchToolCard",
       "MiniAppFinalizeToolCard", "MarketplacePublishToolCard", "PlaybookToolCard",
+      "DesktopCardToolCard",
       "ActionCard",
       "ActionItem",
       "ActivityItem",