IronClaw 自动化任务接线契约：从 AutomationTask 事件模型到持久化 Suggestions 契约的设计演进

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载导读本文围绕 IronClaw 仓库中 docs/internal/design/oobe/AUTOMATION-TASKS-CONTRACT.md 展开完整梳理了自动化任务这一 OOBE首次运行体验核心概念的后端接线契约它最初以AutomationTask领域模型五个持久事件 投影 五条 HTTP 路由 五个 facade 方法被提出后因 PR #7694 落地的持久化 Suggestions 契约而部分被取代。读完本文你将掌握原始设计契约的完整骨架领域模型、事件表、投影规则、传输帧、路由表、Agent 模式门控语义、实际落地契约的四路由细节suggestions.list/suggestions.generate/suggestion.start/suggestion.dismiss以及从ironclaw_product_contracts到ironclaw_webui再到前端 SPA 的源码级实现证据。一、文档定位一份被记录在案、部分被取代的设计参考AUTOMATION-TASKS-CONTRACT.md自身在开头就明确标注了状态design reference (proposed wiring)即设计参考提议的接线方案。它的历史角色是为 WebChat v2 的两个 OOBE 概念提供可评审的接线路径——包括持久事件、投影、传输帧、HTTP 表面和 facade 方法供后续 PR 落地实现已完成的自动化轮播Completed-automations carousel位于落地页 composer 上方原设计中的components/automation-carousel.tsx线程内联日历改期富预览Inline calendar reschedule rich-preview位于线程内部的日历改期卡片原设计中的components/calendar-reschedule-card.tsx。两者共享同一个动作模型suggested已建议状态支持 Approve / Modify / Cancel 三种操作automated已自动化状态支持 Modify / Revert 两种操作。需要特别强调文档顶部那条醒目的警示§1–§3 已被 PR #7694 取代。实际落地的后端改用基于ScopedFilesystem的 typed store带边界 CAS、无 SQL 迁移和四条 product-surface 路由契约而非原始的五个事件 投影方案。因此阅读本文时应把原契约视为设计意图的记录把 docs/internal/design/oobe/VISION-RECONCILIATION.md §1.1 视为真实契约两者对照阅读才能获得完整认知。文档还交代了代码归属背景#6918 家族文件夹重组后的命名事件日志在ironclaw_event_log、持久存储在ironclaw_event_store均位于crates/events/facadeRebornServicesApi在crates/product/ironclaw_assistant路由在crates/product/ironclaw_webui/src/webui_v2/。这些与当前仓库结构完全吻合是理解整个接线路径的地图。二、原始设计意图 §1领域模型原契约规定一个自动化任务是持久的、可投影的记录其 Rust 类型形状是前端 TSAutomationTask的镜像标识符使用crates/ironclaw_common的 newtypepub struct AutomationTaskId(String); // newtype, validated (types.md) pub enum AutomationApp { // #[serde(rename_all snake_case)] Gmail, GoogleCalendar, GoogleDocs, Slack, Notion, } pub enum AutomationTaskKind { // snake_case EmailTriage, CalendarAccept, CalendarReschedule, DocInsights, } pub enum AutomationTaskState { // snake_case Suggested, InProgress, Automated, Reverted, Cancelled, }三个设计要点值得展开标识符 newtype 化AutomationTaskId不是裸String而是经过校验的 newtype这与 Reborn 的types.md规则一致——所有跨层标识符都要有类型边界避免字符串散落各处。枚举统一 snake_caseAutomationApp、AutomationTaskKind、AutomationTaskState均通过 serderename_all snake_case序列化保证 wire 层与 TS 前端命名一致。Payload 默认敏感Kind 相关的 payload如CalendarReschedule、TriagedEmail与 TS 接口lib/automation-tasks.ts逐字段对齐且默认视为敏感数据——邮件正文、与会者列表都属于敏感信息在任何日志写入、持久化追加、投影输出、传输帧、模型可见结果之前调用方都背负脱敏义务对应.claude/rules/safety-and-sandbox.md。仓库提示原文档引用的lib/automation-tasks.ts、hooks/useAutomationTasks.ts等 mock seam 代码已按文档记载被回滚rolled back so the branch stays code-free当前仓库中对应的是下文第七、八节介绍的 suggestions 系列文件两者不要混淆。三、持久事件源真相与投影3.1 五个持久事件原契约要求在 Reborn 运行时事件枚举上新增五个 typed 变体属主 crate 为ironclaw_event_log经由ironclaw_event_store的 durable sink 追加绝不通过 handler 直接广播EventWhen触发时机Carries携带内容AutomationTaskProposedagent 提出任务Suggest/Plan 模式或 Auto 模式实际运行之前完整任务状态为suggestedAutomationTaskModified用户编辑一个 suggested 或 automated 任务任务 id 校验过的 patchAutomationTaskAutomated任务运行完成已批准或 Auto/Bypass 模式直接运行任务 id provider 出具的 evidence见 §6AutomationTaskReverted用户撤销一个 automated 任务任务 id revert evidenceAutomationTaskCancelled用户关闭一条建议任务 id每个变体都必须满足脱敏redacted、可重放replayable并针对持久化 / 重放 / 投影可见性 / 脱敏 / 排序 / 传输序列化分别编写测试。这体现了 Reborn 事件系统的硬性纪律事件是唯一的源真相任何 UI 状态都不是权威。3.2 投影Projection在ironclaw_event_projections中扩展AutomationTaskProjection核心约束有四条按(tenant, user)作用域过滤——调用方只能看到自己的任务携带投影游标projection cursor——支持重放与断点续传replay/resume把上述事件折叠成当前的AutomationTaskState读取语义分两种轮播读取state ∈ {automated, reverted}的任务集合内联卡片按 id 读取单个任务。同时要求一个专门的跨用户隔离回归测试为用户 A 提出的任务绝不能出现在用户 B 的投影里。这条最小隔离断言在后续落地契约中同样以(tenant, user)scope 的形式保留了下来见第七节。四、传输层内联富预览的帧设计内联日历卡片是持久的 UI 状态因此它复用已有的projection → EventStreamManager → SSE/WebSocket通道events.md规则不引入定制消息。具体做法是新增一个脱敏的WebChatV2EventFrame变体capability_display_preview{ kind: automation_task, task: redacted AutomationTask }前端MessageList已经具备渲染非消息子元素的能力例如 gates、onboarding因此它把这一帧映射到CalendarRescheduleCard以及未来的其他 kind即可。重连时从重放恢复绝不依赖前端乐观状态——这是 Reborn 事件驱动 UI 的一条总原则浏览器可以乐观渲染但持久事实只能来自服务端投影。五、HTTP 表面与 facade 方法§5–§65.1 五条路由原契约规定在ironclaw_webui的src/webui_v2/增加五条路由同时必须在webui_v2_routes()描述符表中登记对应行——否则tests/webui_v2_descriptors_contract.rs会失败这正是当前仓库对路由描述符表的强制锁定机制Route IDMethodPatternEffect pathwebui.v2.list_automation_tasksGET/api/webchat/v2/automations/tasksProjectionOnlywebui.v2.approve_automation_taskPOST/api/webchat/v2/automations/tasks/{id}/approveTurnCoordinatorwebui.v2.modify_automation_taskPATCH/api/webchat/v2/automations/tasks/{id}ProductWorkflowwebui.v2.cancel_automation_taskPOST/api/webchat/v2/automations/tasks/{id}/cancelProductWorkflowwebui.v2.revert_automation_taskPOST/api/webchat/v2/automations/tasks/{id}/revertTurnCoordinator这些是认证调用方路由tenant/user 作用域而非 operator 门控路由handler 只消费RebornServicesApi错误统一走WebUiV2HttpError当前仓库中该错误类型正是 handler 返回错误的唯一通道见 crates/product/ironclaw_webui/CONTRACT.md。5.2 五个 facade 方法与真实第三方效应RebornServicesApi位于ironclaw_assistant新增五个方法每个都返回服务端确认的任务记录绝不返回乐观回显events.md规则list_automation_tasks(caller) - VecAutomationTaskapprove_automation_task(caller, id) - AutomationTaskmodify_automation_task(caller, id, patch) - AutomationTaskcancel_automation_task(caller, id) - AutomationTaskrevert_automation_task(caller, id) - AutomationTask两个要点决定了这套接线的安全性Approve/Revert 是真实的第三方效应Gmail 发送/归档、Calendar 移动/恢复必须经由 mediated capability host product adaptersironclaw_host_api中的ProductAdapter表面通过 composition 接线执行——绝不允许第二条 outbound HTTP 路径。成功只能由 provider 出具的 evidencemessage id / event id / revision加上一次最小化 read-back 来确认AutomationTaskAutomated/AutomationTaskReverted事件携带这份 evidence。Modify 语义按状态分叉修改suggested任务 原地编辑提案不执行任何效应直到 Approve修改已 automated任务 携带修改重新执行对 provider 的真实再执行返回带新 evidence 的全新 automated 记录。前端将后者建模为rerunModified刷新完成状态 重算派生字段如邮件发送计数。因此modify_automation_task必须在服务端按当前状态分支。六、Agent 模式composer pill§7原契约第七节定义了落地页 composer 上的模式选择器原设计中的components/mode-selector.tsx storelib/agent-mode.ts当前持久化到 scoped localStorage并规划了持久化 homeGET /api/webchat/v2/settings/agent-mode→{ mode: AgentMode }POST /api/webchat/v2/settings/agent-mode{ mode }→ 确认后的{ mode }在 sessionsession.features/settings上暴露agent_mode使 pill 在加载时水合——与既有的global_auto_approve特性完全一致。语义接入现有审批系统ApprovalCard、resolve_gate路径、global_auto_approve特性四种模式的 gate 行为如下ModeGate behaviorsuggest每个动作都触发审批 gate今天的默认行为planagent 输出一揽子待办任务计划一次审批解决整个集合auto已获批的任务类型邮件整理、邀请接受、文档洞察跳过逐动作 gate其他任务仍走 gate。这是global_auto_approve的 typed 泛化bypass完全不触发 gate全自动化auto/bypass是特权升级模式需要为 gate 抑制路径编写显式测试并为每个自动运行的动作留下审计轨迹。七、实际落地契约持久化 Suggestions 四路由正如第一节所述原契约 §1–§3 已被 PR #7694 取代。真实的契约冻结在ironclaw_product_contracts中由 docs/internal/design/oobe/VISION-RECONCILIATION.md §1.1 记录并与当前仓库源码完全一致MethodWebUI 路由Product 操作GET/api/webchat/v2/suggestionssuggestions.listPOST/api/webchat/v2/suggestions/generatesuggestions.generatePOST/api/webchat/v2/suggestions/{id}/startsuggestion.startDELETE/api/webchat/v2/suggestions/{id}suggestion.dismiss其 wire 类型定义在 crates/contracts/ironclaw_product_contracts/src/product_wire.rs产品面描述符在 crates/contracts/ironclaw_product_contracts/src/suggestions.rsRebornSuggestionsResponse { status: empty | generating | ready | failed, generation_id?: string, retry_after_seconds?: number, suggestions: RebornSuggestion[], } RebornSuggestion { id, title, description, suggested_prompt, icon, sources, thread_id?, run_id? } RebornSuggestionStartResponse { suggestion_id, thread_id, run_id } RebornSuggestionDismissResponse { suggestion_id, dismissed }关键行为均有源码佐证生成是异步的POST generate携带client_action_id作为幂等键返回202、status: generating和retry_after_seconds提示客户端轮询GET suggestions直到终态。每 (tenant, user) 只有一套卡片新一次生成会清除上一套replace-only。卡片数量有界 1–5且字段有硬约束。需要指出的是产品侧校验crates/product/ironclaw_assistant/src/suggestions.rs实际执行的是title ≤ 48、description ≤ 240、suggested_prompt ≤ 2000、sources 1–5 条且每条 ≤128、icon ≤128并拒绝控制字符与重复 source提示词文件prompts/suggestion_generation.md同样写明 titleis 48 characters or fewer。存储模型正如契约警示所述落地实现不是事件投影而是基于ScopedFilesystem的 typed store 边界 CAS 无 SQL 迁移生成以 30 秒租约GENERATION_LEASE_DURATION_SECONDS 30保护崩溃可安全恢复源码 crates/product/ironclaw_assistant/src/suggestions.rs。八、源码级验证路由描述符与 handler当前仓库中这四条路由是真实存在且始终开启的。在 crates/product/ironclaw_webui/src/webui_v2/descriptors.rs 中每个路由都在webui_v2_routes()描述符表登记了精确的 method、pattern、body 限制、限速与 Effect pathsuggestions_list_descriptor()GET走read_policyEffect path 为ProductSurface无流式suggestions_generate_descriptor()POSTbody_limit_kib(4)限速rate_limit_per_caller(10, 60)每 60 秒 10 次——注释明确指出每个被接受的请求都可能启动一次 provider 支撑的 agent 运行因此需要限速suggestion_start_descriptor()POSTNoBody走通用 mutation 限速suggestion_dismiss_descriptor()DELETENoBody同样 mutation 限速。handler 实现位于 crates/product/ironclaw_webui/src/webui_v2/handlers.rs统一经由query_product_view/invoke_product_command走ProductSurface错误收敛到WebUiV2HttpErrorlist_suggestions调用SUGGESTIONS_LIST_VIEW.descriptor()投影视图generate_suggestions解析client_action_id后调用SUGGESTIONS_GENERATE_COMMAND当响应status Generating时返回202 并设置 HTTPRetry-After头否则返回 200retry_after_seconds会被钳制到SUGGESTIONS_MAX_RETRY_AFTER_SECONDS之内start_suggestion调用SUGGESTION_START_COMMAND返回{suggestion_id, thread_id, run_id}dismiss_suggestion调用SUGGESTION_DISMISS_COMMAND返回{suggestion_id, dismissed: true}。产品面编排在 crates/product/ironclaw_assistant/src/suggestions.rs 中几个实现细节与契约精神高度吻合scope 按用户suggestion_scope以tenant_id user_id为主键注释明确 /suggestionsis a per-user mount by designagent/project 仍携带用于文件系统授权与审计上下文start不在浏览器注入 promptstart_suggestion服务端先create_thread再以suggested_prompt作为消息submit_turn——线程和运行都由服务端通过正常 ProductSurface 路径创建thread_action_id/turn_action_id由tenant:user:suggestion_id的 UUIDv5 派生保证幂等生成冲突返回 409GenerationInProgress映射为409 Conflict前端据此收敛到胜出的生成见第九节生成器本身是零工具推断submit_suggestion_generation声明tools: Vec::new()、require_no_approval: true以suggestion_generation.md作为 system prompt按schemas/suggestions.output.json结构化输出——即一个只读的、边界内的 canonical run。九、生产者的行为约束suggestion_generation.md生成器的提示词 crates/product/ironclaw_assistant/prompts/suggestion_generation.md 是这条契约的灵魂它定义了好建议的标准值得逐条理解先看再建议Look before you suggest模型被允许读用户已连接的工具与记忆一条基于真实读取的建议胜过五条凭空想象如果读完无事可做宁少勿滥。具体优于泛泛Reply to Dana about the contract question from Tuesday优于Check your email.。只读是绝对的生成期间只 read / list绝不 draft / modify / send / postSuggesting an action is your job; taking it is not——建议可以写进suggested_prompt但执行必须由用户触发。只主张亲眼所见不得声称某个账号/扩展/能力可用除非有证据扩展以installation_phase active为唯一可用判据suggested_prompt以用户第一人称书写、可独立成立接收方看不到这张列表。这些约束解释了为什么卡片天然工具无关模型能看到扩展但输出 schema 不声明扩展身份——这直接导向第十一节connect 去耦的决策。十、icon / sources 语义契约卡片上两个必填字段的契约由 docs/internal/design/oobe/SUGGESTION-ICONS.md 单独定义icon必填、provider 中立的任务类别语义枚举email/calendar/document/storage/spreadsheet/presentation/code/messaging/notes/web/memory/generic只控制卡片字形不是扩展/厂商/能力身份generic是保证兜底——未知、缺失、遗留值一律映射到generic保证卡片永远可渲染。sources1–5 条简洁的人类可读来源标签如Gmail、GitHub是展示字符串而非扩展 ID前端绝不从它们推导 icon 或 setup 路由。Rust wire 层刻意把icon存为普通String使 schema 演进无需持久化迁移前端渲染由pages/chat/lib/suggestion-icons.tsx负责位于懒加载的 suggestion surface chunk 中避免给/chat的 eager bundle 增重。十一、前端消费层API 客户端、数据 hook 与落地表面落地契约的前端一半在crates/product/ironclaw_webui/frontend/src/pages/chat/下与第七、八节的服务端一一对应lib/suggestions-api.ts四个 typed 调用fetchSuggestions/generateSuggestions/startSuggestion/dismissSuggestion文件头注释明确后端拥有生成、持久化与 suggestion → thread/run 绑定浏览器从不臆造卡片状态。pollDelayMs把retry_after_seconds钳制在 1–30 秒防止缺失值造成热循环、敌意值造成无限挂起。hooks/useSuggestions.ts浏览器中 suggestion 状态的唯一 owner。轮询只在status generating时按后端节奏运行终态即停生成冲突另一 tab/设备先 claim 的 409触发invalidateQueries重新读取权威状态start成功后同时刷新 suggestions 与 threads 两个查询键dismiss成功后本地立即移除卡片服务端已提交。components/suggested-task-surface.tsx四种生成状态驱动四种呈现——empty→ 生成 CTA生成消耗真实模型运行必须用户主动请求generating→ 品牌化进行指示器 静态 skeleton 瓦片尊重 motion policyready→ 横向滚动卡片条failed→ 重试按钮。start成功后通过返回的thread_id导航到对应线程。前端细节中还包含两个超出基础契约的入口issue #7815 F1/F2抽屉头部的refresh重新执行 generate因后端是 replace-only所以刷新即诚实刷新与connect链接到既有/extensions表面作为连接流程的第一段而非卡片内的 connect 状态。十二、从设计冲突中沉淀的三个关键决策VISION-RECONCILIATION.md 记录了契约落地过程中三个已拍板的关键决策它们直接塑造了当前实现卡片并行运行——单一活动锁被移除。原PROPOSAL.md §2A.3以submit_turn返回DeferredBusy/RejectedBusy为据限制同一时刻一个活动任务但suggestion.start为每条建议创建独立线程后端不存在并行约束Vision 的多卡片抽屉天然并行。Automation 被移除。卡片 schema 没有automation_prompt字段、也没有 automation 路由——与其保留一个无持久化背书的客户端合成 prompt 注入入口不如直接从卡片上去掉该动作未来若要做循环自动化需要单独的契约而不是在此打补丁。事件/投影契约被取代。即本文 §1–§3 的AutomationTask领域模型被 typed store overScopedFilesystem取代作为原始设计意图的记录保留。另一个值得注意的取舍是connect 与卡片的解耦卡片不携带工具身份、不设 connect 状态、不依赖连接即可启动如果启动的运行需要未连接的工具agent 会发出既有的AuthRequiredgate 帧线程内渲染AuthOauthCard——这是一条已上线且无需改动的路径。连接面板独立为由扩展目录驱动的落地表面Connect panel ← extensions catalog与建议抽屉成为两个并列表面。十三、当前状态什么是 stub、什么是 shipped最后厘清本文两个契约的实现真相避免把设计文档误当实现文档AutomationTask契约§2–§7全部未实现原文档明确 Everything in §§2–7 isnot implemented。当时前端基于 mock 数据 localStorage 模式 store 运行Rust 事件/投影/路由桩有意不写——零警告 clippy gate 会把未使用的脚手架类型判为告警必须与首次实现 测试一起落地。Suggestions 契约已 shipped 且始终开启服务端ironclaw_product_contracts描述符、ironclaw_assistant编排、ironclaw_webui四路由与前端suggestions-api.ts、useSuggestions.ts、suggested-task-surface.tsx均已上线路由无 feature flag 保护。前端表面保持懒加载其卡片与图标代码不进入/chat的 eager bundle。尚未构建的 Vision 后续项见 VISION-RECONCILIATION §5.1live card status订阅绑定run_id反映运行中/完成/失败、V1 冷启动连接面板批量 OAuth、Agent 模式选择器Suggest / Plan / Auto / Bypass仍无持久化 home、输入时卡片折叠为 pill 行、命名问候V5等。结语一份契约的两种命运AUTOMATION-TASKS-CONTRACT.md的价值不在于它是最终实现而在于它是一份完整、可评审的接线蓝图它把自动化任务拆解为领域模型、持久事件、投影、传输帧、HTTP 表面、facade 方法与 Agent 门控语义任何一步都有明确的属主 crate 与纪律约束脱敏、可重放、服务端确认、无第二 outbound 路径。而 PR #7694 的 Suggestions 契约则证明了同一套纪律在更轻量的存储模型上同样成立——typed store CAS 取代事件投影四条路由取代五条但浏览器从不臆造状态、成功只由 provider evidence 确认、卡片不携带工具身份这些原则原封不动地延续了下来。对于要在 IronClaw 上新增产品表面的开发者这份文档连同 VISION-RECONCILIATION.md、SUGGESTION-ICONS.md 以及上文列出的源码构成了从设计到实现最完整的参照系。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw 进程生命周期契约基于 row-native Journal 的 ProcessJournalStore 持久化权威设计解析IronClaw 进程生命周期契约基于 row native Journal 的 ProcessJournalStore 持久化权威设计解析 导读 本文以人工智能AI 应用交互助手AI AgentIronClaw Reborn 事件与审计契约RuntimeEvent、AuditEnvelope 双观测面、脱敏不变量与 JSONL 持久化语义IronClaw Reborn 事件与审计契约RuntimeEvent、AuditEnvelope 双观测面、脱敏不变量与 JSONL 持久化语义 IronC人工智能AI 应用交互助手AI AgentThorium浏览器完整指南老机器和隐私用户该装哪个 Chromium 分支Thorium浏览器完整指南老机器和隐私用户该装哪个 Chromium 分支 Thorium 浏览器是一个以放射性元素 90 号钍命名的 Chromiu桌面应用跨平台上一篇Wand-Enhancer 本地补丁完整指南不下载 exe、3 步打好 Wand 客户端并解锁手机远程面板下一篇炉石传说HsMod终极指南免费解锁32倍速和200皮肤定制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考