人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载IronClaw 的 OOBEOut-of-Box Experience开箱体验方案解决的是 WebChat v2 的首次运行真空问题全新用户落地时落地页只有一个 hero 标题、输入框和三个静态建议 chip没有任何这个 Agent 能替你做什么的第一时刻价值。本文基于仓库中 OOBE 集成提案总览 及其治理文档 VISION-RECONCILIATION 展开完整还原这套建议卡片体系的设计决策、后端持久化建议契约PR #7694 落地、前端消费实现与源码级证据读完你可以掌握 IronClaw 首次运行体验从契约到组件的全链路实现方式。问题起点冷启动状态是未设计的提案对现状的描述非常具体WebChat v2 的落地视图由empty-state.tsx承载即 hero 标题 composer 三个静态建议 chip。而自动化相关表面Done for you 轮播、内联日历改期卡片、Plan 卡片、agent 模式 pill都假设自动化任务已经存在——新账号什么都没有于是冷启动cold start与第一张卡片出现这两个时刻处于未设计状态见 设计简报 的 Goal 一节。这个缺口就是 OOBE 要填的用 Agent 在首次运行时生成的建议任务卡片suggested task cards——每张卡片是一个具体提案用户可以批准approve为其单独开一个 thread/run 并导航过去或忽略dismiss。两阶段模型已成历史为什么现在直接构建 Vision原始方案把工作切成两条轨道见 PROPOSAL.md 第 2 节Foundational近期v2 忠实——建议卡片 复用已 shipped 的扩展授权/审批门/忙碌态在 main 现有功能之上的一薄层Vision北极星——Foundational 全部 冷启动批量 OAuth 连接面板、贴靠 composer 的抽屉框架、首次自动化 reveal 动画、命名问候、第四种模式Bypass。关键转折是PR #7694 直接 shipped 了 Foundational 阶段最需要的那个后端能力——持久化的、Agent 驱动的建议生成器durable backend suggestions producer。因此 VISION-RECONCILIATION.md 宣布Foundational 轨道被裁撤程序直接对着 #7694 的契约构建 Vision而 OOBE 前端分支PR #6994则成为该契约的消费者。该文档明确声明Where this document differs from PROPOSAL / PLAN / IMPLEMENTATION / AUTOMATION-TASKS-CONTRACT,this governs——即它是本包当前唯一有效计划其余文档作为决策记录保留。后端建议契约四条路由与一个状态机路由与产品操作契约冻结在ironclaw_product_contracts中见 VISION-RECONCILIATION §1.1方法WebUI 路由产品操作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这些操作声明可以直接在源码中验证suggestions.rs以ProductView/ProductSurfaceCommandDescriptor声明了suggestions.list、suggestions.generate、suggestion.start、suggestion.dismiss四个操作 ID路由侧router.rs将list_suggestionsGET与generate_suggestionsPOST挂到 WebUI v2 路由树上。线型Wire Types一个四态状态机响应体是一个围绕生成状态的四态机定义在product_wire.rspub struct RebornSuggestion { pub id: String, pub title: String, pub description: String, pub suggested_prompt: String, pub icon: String, // 语义任务分类见 SUGGESTION-ICONS pub sources: VecString, // 1–5 个人类可读的来源标签 pub thread_id: OptionString, // 批准后绑定 pub run_id: OptionString, // 批准后绑定 } pub enum RebornSuggestionGenerationStatus { Empty, Generating, Ready, Failed, } pub struct RebornSuggestionsResponse { pub status: RebornSuggestionGenerationStatus, pub generation_id: OptionString, pub retry_after_seconds: Optionu32, pub suggestions: VecRebornSuggestion, }配套的契约约束来自 VISION-RECONCILIATION §1.1 与 schema 文件生成是异步的POST generate带client_action_id做幂等返回202status: generatingretry_after_seconds提示客户端轮询GET suggestions。测试suggestions.rs恰好固化了这个序列化的形状{status:generating,generation_id:generation-1,retry_after_seconds:1,suggestions:[]}。一组卡片对应一个(tenant_id, user_id)新的生成整体替换上一组replace-only。卡片数量 1–5字段长度上限title≤ 80、description≤ 240、suggested_prompt≤ 2000 字符对应schemas/suggestions.output.v1.json。suggestion.start返回{ suggestion_id, thread_id, run_id }——批准即创建独立 thread 并返回 run 绑定这是卡片可以携带持久thread_id/run_id状态的基础。生产者本身canonical run 只读能力白名单#7694 的生产者是一个canonical 无界运行 只读能力 allowlistmemory search/read/tree、extension search、tool search/describe 零工具推理对原生结构化输出 schema 定型的流程。值得注意的是 生成提示词 中写死的克制原则Do not claim that an account, extension, credential, or capability is available when you have not been given evidence that it is——模型能看到扩展extension search 在白名单里但输出 schema 不给它声明具体工具的地方。这条提示词约束直接决定了后文连接与卡片解耦的架构决策。图标枚举presentation 与 provenance 的双字段契约卡片上的视觉与来源信息由两个必填字段承载独立文档 SUGGESTION-ICONS.md 定义了完整语义词汇12 个值schema 与前端共用同一有序枚举enum 值任务概念enum 值任务概念email邮件工作code源代码calendar日程安排messaging会话与消息document文档notes笔记与写作storage文件与存储web网络调研spreadsheet表格memory持久上下文presentation幻灯片generic未分类/兜底两条硬边界icon只控制卡片字形不是扩展、厂商或能力身份sources是 1–5 个人类可读来源标签由发现的扩展/工具元数据翻译而来是展示字符串而非扩展 ID——前端绝不从它们推导图标或 setup 路由。Schema 侧icon为 string enum、sources为minItems: 1, maxItems: 5的字符串数组每项 1–128 字符Rust 线契约故意把icon存为字符串以便 schema 演进不需要持久化迁移。兼容性上带着已退役品牌值的旧记录仍可加载、仍可启动未知图标值渲染中性generic字形不改写、不删除任何行。前端映射逻辑在suggestion-icons.tsxresolveIconId、SuggestionIcon未知/缺失/遗留值一律落到generic。前端消费者always-on、lazy-loaded 的表面VISION-RECONCILIATION 明确了前端交付原则路由与表面 always-on无 feature flag但表面保持 lazy-load使卡片与图标代码不进入/chat的 eager bundle且不渲染任何 mock 数据——早期 UI 原型#6994 中的 mock 自动化渲染在 review 中被整体回滚因为向真实用户渲染 mock 卡片是明确反模式。当前代码库中的消费者构成文件职责useSuggestions.ts数据 hook挂载时listempty→ 生成 CTAgenerating→ 按retry_after_seconds轮询ready→ 渲染卡片failed→ 重试入口suggestions-api.ts四个类型化 API 调用apiFetchclientActionId()约定suggested-task-surface.tsx表面壳层贴靠 composer 的抽屉框架 头部刷新、/extensions入口suggested-task-card.tsx展示型卡片Approve →POST /{id}/start→ 导航到返回的thread_idDismiss →DELETE /{id}oobe-restore-pill.tsx忽略后的恢复入口切片计划与完成度VISION-RECONCILIATION §5.1文档以勾选表形式记录了 10 个切片的真实状态这是理解哪些已落地、哪些是后续工作最权威的清单✅ 建议 API client 类型✅ 表面消费真实数据含empty/generating/ready/failed四态处理✅ start dismiss✅ 剥离 connect 模型删除unconnected卡片状态、resolver 及chat.oobe.connectUnavailablei18n key共 11 个语言文件✅ V3 预期态空态 CTA / 生成中骨架 / 失败重试生成中在静态.v2-skeleton瓦片上叠加品牌 NEAR 指示器✅ V2 reveal——克制的卡片入场动画.oobe-card-reveal复用已批准的v2-page-in关键帧受prefers-reduced-motion抑制不是mockup 里那个 ad-hoc 的 conic-gradient ai-spark 边框扫光后者会绕过app.css的静态动效策略⏳ 卡片实时状态——订阅绑定的run_id以反映 running/completed/failed未构建⏳ V1 冷启动批量 OAuth 连接面板未构建✅ V4 贴靠 drawer 框架Suggested for you · approve to run, or tweak first 头部未做的是与 composer 的真实边框合并——为避免触碰已 shipped 的ChatInput保留了圆角框架 紧凑间距✅ 刷新 connect 入口issue #7815——头部刷新控件重跑generate进行中禁用refresh 是诚实的刷新因为后端生成是 replace-only在获得增量补充top-up状态迁移前没有更多语义关键决策Connect 与卡片解耦这是整个方案里最有架构含量的一组决策全部由契约无工具身份这一事实推导而来。冲突的由来生成卡片原本不携带工具身份与连接状态{ id, title, description, suggested_prompt, thread_id?, run_id? }这是刻意的而非疏漏。但这与 PORProduct on Record中每张卡片带 Connect Tool CTA卡片以 connect 态开始的主线矛盾。最终裁定VISION-RECONCILIATION §3.1Landing ├── Connect panel ← 扩展目录useExtensions批量 OAuth 走查 └── Suggestion drawer ← GET /suggestions工具无关的卡片Connect 不再是卡片状态而是由扩展目录驱动的独立落地表面。由此推出四条后果卡片永不被连接状态 gate——卡片存在即可启动Just-in-time 认证仍然工作若启动的 run 需要未连接工具Agent 在 thread 中发出现有的AuthRequiredgate 帧、前端渲染AuthOauthCard已 shipped 路径不变。文档诚实标注了待 QA 验证项AuthRequired在 suggestion 启动的 run 上是否触发同一 agent loop理应触发但未测面板失去 per-card 语境为什么这个工具有用作为接受的权衡面板只能泛化地讲价值resolveConnectExtension被孤儿化并删除卡片appid → 目录扩展的解析器但它验证的复用模式保留lazy-load 真实的ConfigureModal而非克隆useOauthSetup约 250 行的弹窗/轮询状态机——这正是 V1 面板未来成本低的原因。契约顺带解决的其他决策VISION-RECONCILIATION §4卡片并行运行single-active 锁被移除原方案以submit_turn在 thread 上活跃时返回DeferredBusy/RejectedBusy为依据锁住多卡片但suggestion.start为每张卡片创建独立 thread后端本无此约束——批准一张卡永不使其他卡失效这正是 Vision 多卡抽屉想要的。 Automation 被移除卡片 schema 没有automation_prompt字段、#7694 也没有自动化路由没有可构建的对象若未来重复自动化成为首跑目标需要它自己的后端契约而不是这里 bolt-on。事件/投影契约被取代见下一节。被取代的历史设计AutomationTask 五事件模型AUTOMATION-TASKS-CONTRACT.md 规格化了一个AutomationTask域模型5 个持久事件AutomationTaskProposed/Modified/Automated/Reverted/Cancelled 按(tenant, user)scope 过滤的AutomationTaskProjection 5 条/api/webchat/v2/automations/tasks/*路由 RebornServicesApi上的 5 个 facade 方法approve/modify/revert 为真实三方效应必须走 mediated capability host product adapters成功仅凭 provider 证据 最小回读承认。#7694 的实际实现选择不同基于ScopedFilesystem的类型化 store 有界 CAS无 SQL 迁移外加四路由产品表面契约。因此该文档 §§1–3 作为实现目标已过期只保留为原始设计意图的记录——文档头部有醒目的do not build against them警告。它仍有参考价值的部分是安全不变量事件 payload默认敏感、承载 redaction 义务投影跨用户隔离必须有专门回归测试auto/bypass这类压制审批门的行为必须配套 gate-suppression 测试与审计轨迹。仍开放的决策与后续工作从文档可以整理出截至当前仓库状态的开放项VISION-RECONCILIATION §6 §5.1 未勾选切片AuthRequired在 suggestion-started run 上的行为——依赖 just-in-time auth 作为 connect 故事前必须 QA 验证Agent 模式选择器Suggest / Plan / Auto / Bypasscomposer 内——未被 #7694 触及仍属净新增需要持久化落点 类型化 gate 接线auto是global_auto_approve的类型化泛化不属于建议契约Pills-collapse 交互——用户开始输入时抽屉收敛为可滚动 pill 行 忽略 / composer 内恢复命名问候V5——Welcome to IronClaw, name 需要确定性的用户名来源admin 预配 vs 邮件 vs Slack profile 的优先级以及无来源时的无名回退已显式推迟替换 UX——新生成清除旧集合时用户正在阅读中的抽屉如何表现。设计系统治理归属一个跨切面的变更值得记录DESIGN.md宪法、--v2-*token 架构与 Storybook workbench 的所有权已移交给 WebUI 设计系统计划docs/internal/reborn/design-system/OOBE不再自建任何设计治理设施只把卡片/抽屉/动作栏组件族作为该系统的**试点pilot**编目进去。若卡片先于设计系统 Phase 1 生产化则按普通 token 驱动组件交付其 stories 随后补上——绝不 fork 第二个工作台。文档地图如何继续深入OOBE 包遵循executive README → 有证据的 PROPOSAL → 排序的 PLAN → definition-of-done CHECKLIST的文档框架完整索引如下文档角色README.md执行总览本文主体VISION-RECONCILIATION.md治理文档与 shipped 后端契约的对齐记录PROPOSAL.md完整规格phasing、shipped-vs-net-new 范围、依赖清单PLAN.md / IMPLEMENTATION.md / CHECKLIST.md执行计划 / 构建计划 / 完成定义AUTOMATION-TASKS-CONTRACT.md历史设计参考已被取代勿照建SUGGESTION-ICONS.md图标语义枚举契约mockup.html自包含交互 mockup浏览器直接打开integration-review.html可视化 review5 层集成图、依赖图、阶段时间线oobe.md设计简报what/why源码侧的阅读顺序建议先读契约suggestions.rs、product_wire.rs再看路由挂载router.rs与 handlerhandlers.rs最后沿前端数据链useSuggestions.ts→suggestions-api.ts→suggested-task-surface.tsx→suggested-task-card.tsx走一遍状态机。每个前端组件旁边都有同名.test.ts(x)测试文件如useSuggestions.test.ts、suggestions-api.test.ts是契约形状的最直接验证依据。适用前提说明本文描述的是当前仓库中的实现状态——后端建议契约与前端消费者 1–6、9、10 号切片已落地卡片实时状态slice 7、冷启动批量 OAuth 面板slice 8、Agent 模式选择器与 pills-collapse 为明确跟踪的未构建项。文档中引用的 PR 编号#6994、#7694、#7693 等指该仓库上游的合并记录本文以当前仓库实际存在的契约类型、路由与组件代码为准。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐Vector 0.45.0 升级指南VRL 0.22.0 引入的 truncate 参数移除与 slice 类型推断增强Vector 0.45.0 升级指南VRL 0.22.0 引入的 truncate 参数移除与 slice 类型推断增强 Vector 0.45.0 随附的人工智能AI 应用交互助手AI AgentIronClaw OOBE 首启引导设计解析两阶段提案、已发货建议契约与 WebChat v2 冷启动方案IronClaw OOBE 首启引导设计解析两阶段提案、已发货建议契约与 WebChat v2 冷启动方案 IronClaw 的 OOBEOut of Bo人工智能AI 应用交互助手AI AgentIronClaw OOBE 首次体验工程实录执行计划、阶段门禁与持久化建议契约IronClaw OOBE 首次体验工程实录执行计划、阶段门禁与持久化建议契约 本文基于 IronClaw 仓库中的 OOBEOut Of Box Expe人工智能AI 应用交互助手AI Agent上一篇如何优化Nemotron-Cascade-2-30B-A3B推理速度5个关键技巧下一篇AngularUI - AngularJS 的配套套件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 IronClaw OOBE 首次运行引导：从空白落地页到 Agent 驱动的建议卡片全链路解析
人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载IronClaw 的 OOBEOut-of-Box Experience开箱体验方案解决的是 WebChat v2 的首次运行真空问题全新用户落地时落地页只有一个 hero 标题、输入框和三个静态建议 chip没有任何这个 Agent 能替你做什么的第一时刻价值。本文基于仓库中 OOBE 集成提案总览 及其治理文档 VISION-RECONCILIATION 展开完整还原这套建议卡片体系的设计决策、后端持久化建议契约PR #7694 落地、前端消费实现与源码级证据读完你可以掌握 IronClaw 首次运行体验从契约到组件的全链路实现方式。问题起点冷启动状态是未设计的提案对现状的描述非常具体WebChat v2 的落地视图由empty-state.tsx承载即 hero 标题 composer 三个静态建议 chip。而自动化相关表面Done for you 轮播、内联日历改期卡片、Plan 卡片、agent 模式 pill都假设自动化任务已经存在——新账号什么都没有于是冷启动cold start与第一张卡片出现这两个时刻处于未设计状态见 设计简报 的 Goal 一节。这个缺口就是 OOBE 要填的用 Agent 在首次运行时生成的建议任务卡片suggested task cards——每张卡片是一个具体提案用户可以批准approve为其单独开一个 thread/run 并导航过去或忽略dismiss。两阶段模型已成历史为什么现在直接构建 Vision原始方案把工作切成两条轨道见 PROPOSAL.md 第 2 节Foundational近期v2 忠实——建议卡片 复用已 shipped 的扩展授权/审批门/忙碌态在 main 现有功能之上的一薄层Vision北极星——Foundational 全部 冷启动批量 OAuth 连接面板、贴靠 composer 的抽屉框架、首次自动化 reveal 动画、命名问候、第四种模式Bypass。关键转折是PR #7694 直接 shipped 了 Foundational 阶段最需要的那个后端能力——持久化的、Agent 驱动的建议生成器durable backend suggestions producer。因此 VISION-RECONCILIATION.md 宣布Foundational 轨道被裁撤程序直接对着 #7694 的契约构建 Vision而 OOBE 前端分支PR #6994则成为该契约的消费者。该文档明确声明Where this document differs from PROPOSAL / PLAN / IMPLEMENTATION / AUTOMATION-TASKS-CONTRACT,this governs——即它是本包当前唯一有效计划其余文档作为决策记录保留。后端建议契约四条路由与一个状态机路由与产品操作契约冻结在ironclaw_product_contracts中见 VISION-RECONCILIATION §1.1方法WebUI 路由产品操作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这些操作声明可以直接在源码中验证suggestions.rs以ProductView/ProductSurfaceCommandDescriptor声明了suggestions.list、suggestions.generate、suggestion.start、suggestion.dismiss四个操作 ID路由侧router.rs将list_suggestionsGET与generate_suggestionsPOST挂到 WebUI v2 路由树上。线型Wire Types一个四态状态机响应体是一个围绕生成状态的四态机定义在product_wire.rspub struct RebornSuggestion { pub id: String, pub title: String, pub description: String, pub suggested_prompt: String, pub icon: String, // 语义任务分类见 SUGGESTION-ICONS pub sources: VecString, // 1–5 个人类可读的来源标签 pub thread_id: OptionString, // 批准后绑定 pub run_id: OptionString, // 批准后绑定 } pub enum RebornSuggestionGenerationStatus { Empty, Generating, Ready, Failed, } pub struct RebornSuggestionsResponse { pub status: RebornSuggestionGenerationStatus, pub generation_id: OptionString, pub retry_after_seconds: Optionu32, pub suggestions: VecRebornSuggestion, }配套的契约约束来自 VISION-RECONCILIATION §1.1 与 schema 文件生成是异步的POST generate带client_action_id做幂等返回202status: generatingretry_after_seconds提示客户端轮询GET suggestions。测试suggestions.rs恰好固化了这个序列化的形状{status:generating,generation_id:generation-1,retry_after_seconds:1,suggestions:[]}。一组卡片对应一个(tenant_id, user_id)新的生成整体替换上一组replace-only。卡片数量 1–5字段长度上限title≤ 80、description≤ 240、suggested_prompt≤ 2000 字符对应schemas/suggestions.output.v1.json。suggestion.start返回{ suggestion_id, thread_id, run_id }——批准即创建独立 thread 并返回 run 绑定这是卡片可以携带持久thread_id/run_id状态的基础。生产者本身canonical run 只读能力白名单#7694 的生产者是一个canonical 无界运行 只读能力 allowlistmemory search/read/tree、extension search、tool search/describe 零工具推理对原生结构化输出 schema 定型的流程。值得注意的是 生成提示词 中写死的克制原则Do not claim that an account, extension, credential, or capability is available when you have not been given evidence that it is——模型能看到扩展extension search 在白名单里但输出 schema 不给它声明具体工具的地方。这条提示词约束直接决定了后文连接与卡片解耦的架构决策。图标枚举presentation 与 provenance 的双字段契约卡片上的视觉与来源信息由两个必填字段承载独立文档 SUGGESTION-ICONS.md 定义了完整语义词汇12 个值schema 与前端共用同一有序枚举enum 值任务概念enum 值任务概念email邮件工作code源代码calendar日程安排messaging会话与消息document文档notes笔记与写作storage文件与存储web网络调研spreadsheet表格memory持久上下文presentation幻灯片generic未分类/兜底两条硬边界icon只控制卡片字形不是扩展、厂商或能力身份sources是 1–5 个人类可读来源标签由发现的扩展/工具元数据翻译而来是展示字符串而非扩展 ID——前端绝不从它们推导图标或 setup 路由。Schema 侧icon为 string enum、sources为minItems: 1, maxItems: 5的字符串数组每项 1–128 字符Rust 线契约故意把icon存为字符串以便 schema 演进不需要持久化迁移。兼容性上带着已退役品牌值的旧记录仍可加载、仍可启动未知图标值渲染中性generic字形不改写、不删除任何行。前端映射逻辑在suggestion-icons.tsxresolveIconId、SuggestionIcon未知/缺失/遗留值一律落到generic。前端消费者always-on、lazy-loaded 的表面VISION-RECONCILIATION 明确了前端交付原则路由与表面 always-on无 feature flag但表面保持 lazy-load使卡片与图标代码不进入/chat的 eager bundle且不渲染任何 mock 数据——早期 UI 原型#6994 中的 mock 自动化渲染在 review 中被整体回滚因为向真实用户渲染 mock 卡片是明确反模式。当前代码库中的消费者构成文件职责useSuggestions.ts数据 hook挂载时listempty→ 生成 CTAgenerating→ 按retry_after_seconds轮询ready→ 渲染卡片failed→ 重试入口suggestions-api.ts四个类型化 API 调用apiFetchclientActionId()约定suggested-task-surface.tsx表面壳层贴靠 composer 的抽屉框架 头部刷新、/extensions入口suggested-task-card.tsx展示型卡片Approve →POST /{id}/start→ 导航到返回的thread_idDismiss →DELETE /{id}oobe-restore-pill.tsx忽略后的恢复入口切片计划与完成度VISION-RECONCILIATION §5.1文档以勾选表形式记录了 10 个切片的真实状态这是理解哪些已落地、哪些是后续工作最权威的清单✅ 建议 API client 类型✅ 表面消费真实数据含empty/generating/ready/failed四态处理✅ start dismiss✅ 剥离 connect 模型删除unconnected卡片状态、resolver 及chat.oobe.connectUnavailablei18n key共 11 个语言文件✅ V3 预期态空态 CTA / 生成中骨架 / 失败重试生成中在静态.v2-skeleton瓦片上叠加品牌 NEAR 指示器✅ V2 reveal——克制的卡片入场动画.oobe-card-reveal复用已批准的v2-page-in关键帧受prefers-reduced-motion抑制不是mockup 里那个 ad-hoc 的 conic-gradient ai-spark 边框扫光后者会绕过app.css的静态动效策略⏳ 卡片实时状态——订阅绑定的run_id以反映 running/completed/failed未构建⏳ V1 冷启动批量 OAuth 连接面板未构建✅ V4 贴靠 drawer 框架Suggested for you · approve to run, or tweak first 头部未做的是与 composer 的真实边框合并——为避免触碰已 shipped 的ChatInput保留了圆角框架 紧凑间距✅ 刷新 connect 入口issue #7815——头部刷新控件重跑generate进行中禁用refresh 是诚实的刷新因为后端生成是 replace-only在获得增量补充top-up状态迁移前没有更多语义关键决策Connect 与卡片解耦这是整个方案里最有架构含量的一组决策全部由契约无工具身份这一事实推导而来。冲突的由来生成卡片原本不携带工具身份与连接状态{ id, title, description, suggested_prompt, thread_id?, run_id? }这是刻意的而非疏漏。但这与 PORProduct on Record中每张卡片带 Connect Tool CTA卡片以 connect 态开始的主线矛盾。最终裁定VISION-RECONCILIATION §3.1Landing ├── Connect panel ← 扩展目录useExtensions批量 OAuth 走查 └── Suggestion drawer ← GET /suggestions工具无关的卡片Connect 不再是卡片状态而是由扩展目录驱动的独立落地表面。由此推出四条后果卡片永不被连接状态 gate——卡片存在即可启动Just-in-time 认证仍然工作若启动的 run 需要未连接工具Agent 在 thread 中发出现有的AuthRequiredgate 帧、前端渲染AuthOauthCard已 shipped 路径不变。文档诚实标注了待 QA 验证项AuthRequired在 suggestion 启动的 run 上是否触发同一 agent loop理应触发但未测面板失去 per-card 语境为什么这个工具有用作为接受的权衡面板只能泛化地讲价值resolveConnectExtension被孤儿化并删除卡片appid → 目录扩展的解析器但它验证的复用模式保留lazy-load 真实的ConfigureModal而非克隆useOauthSetup约 250 行的弹窗/轮询状态机——这正是 V1 面板未来成本低的原因。契约顺带解决的其他决策VISION-RECONCILIATION §4卡片并行运行single-active 锁被移除原方案以submit_turn在 thread 上活跃时返回DeferredBusy/RejectedBusy为依据锁住多卡片但suggestion.start为每张卡片创建独立 thread后端本无此约束——批准一张卡永不使其他卡失效这正是 Vision 多卡抽屉想要的。 Automation 被移除卡片 schema 没有automation_prompt字段、#7694 也没有自动化路由没有可构建的对象若未来重复自动化成为首跑目标需要它自己的后端契约而不是这里 bolt-on。事件/投影契约被取代见下一节。被取代的历史设计AutomationTask 五事件模型AUTOMATION-TASKS-CONTRACT.md 规格化了一个AutomationTask域模型5 个持久事件AutomationTaskProposed/Modified/Automated/Reverted/Cancelled 按(tenant, user)scope 过滤的AutomationTaskProjection 5 条/api/webchat/v2/automations/tasks/*路由 RebornServicesApi上的 5 个 facade 方法approve/modify/revert 为真实三方效应必须走 mediated capability host product adapters成功仅凭 provider 证据 最小回读承认。#7694 的实际实现选择不同基于ScopedFilesystem的类型化 store 有界 CAS无 SQL 迁移外加四路由产品表面契约。因此该文档 §§1–3 作为实现目标已过期只保留为原始设计意图的记录——文档头部有醒目的do not build against them警告。它仍有参考价值的部分是安全不变量事件 payload默认敏感、承载 redaction 义务投影跨用户隔离必须有专门回归测试auto/bypass这类压制审批门的行为必须配套 gate-suppression 测试与审计轨迹。仍开放的决策与后续工作从文档可以整理出截至当前仓库状态的开放项VISION-RECONCILIATION §6 §5.1 未勾选切片AuthRequired在 suggestion-started run 上的行为——依赖 just-in-time auth 作为 connect 故事前必须 QA 验证Agent 模式选择器Suggest / Plan / Auto / Bypasscomposer 内——未被 #7694 触及仍属净新增需要持久化落点 类型化 gate 接线auto是global_auto_approve的类型化泛化不属于建议契约Pills-collapse 交互——用户开始输入时抽屉收敛为可滚动 pill 行 忽略 / composer 内恢复命名问候V5——Welcome to IronClaw, name 需要确定性的用户名来源admin 预配 vs 邮件 vs Slack profile 的优先级以及无来源时的无名回退已显式推迟替换 UX——新生成清除旧集合时用户正在阅读中的抽屉如何表现。设计系统治理归属一个跨切面的变更值得记录DESIGN.md宪法、--v2-*token 架构与 Storybook workbench 的所有权已移交给 WebUI 设计系统计划docs/internal/reborn/design-system/OOBE不再自建任何设计治理设施只把卡片/抽屉/动作栏组件族作为该系统的**试点pilot**编目进去。若卡片先于设计系统 Phase 1 生产化则按普通 token 驱动组件交付其 stories 随后补上——绝不 fork 第二个工作台。文档地图如何继续深入OOBE 包遵循executive README → 有证据的 PROPOSAL → 排序的 PLAN → definition-of-done CHECKLIST的文档框架完整索引如下文档角色README.md执行总览本文主体VISION-RECONCILIATION.md治理文档与 shipped 后端契约的对齐记录PROPOSAL.md完整规格phasing、shipped-vs-net-new 范围、依赖清单PLAN.md / IMPLEMENTATION.md / CHECKLIST.md执行计划 / 构建计划 / 完成定义AUTOMATION-TASKS-CONTRACT.md历史设计参考已被取代勿照建SUGGESTION-ICONS.md图标语义枚举契约mockup.html自包含交互 mockup浏览器直接打开integration-review.html可视化 review5 层集成图、依赖图、阶段时间线oobe.md设计简报what/why源码侧的阅读顺序建议先读契约suggestions.rs、product_wire.rs再看路由挂载router.rs与 handlerhandlers.rs最后沿前端数据链useSuggestions.ts→suggestions-api.ts→suggested-task-surface.tsx→suggested-task-card.tsx走一遍状态机。每个前端组件旁边都有同名.test.ts(x)测试文件如useSuggestions.test.ts、suggestions-api.test.ts是契约形状的最直接验证依据。适用前提说明本文描述的是当前仓库中的实现状态——后端建议契约与前端消费者 1–6、9、10 号切片已落地卡片实时状态slice 7、冷启动批量 OAuth 面板slice 8、Agent 模式选择器与 pills-collapse 为明确跟踪的未构建项。文档中引用的 PR 编号#6994、#7694、#7693 等指该仓库上游的合并记录本文以当前仓库实际存在的契约类型、路由与组件代码为准。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐Vector 0.45.0 升级指南VRL 0.22.0 引入的 truncate 参数移除与 slice 类型推断增强Vector 0.45.0 升级指南VRL 0.22.0 引入的 truncate 参数移除与 slice 类型推断增强 Vector 0.45.0 随附的人工智能AI 应用交互助手AI AgentIronClaw OOBE 首启引导设计解析两阶段提案、已发货建议契约与 WebChat v2 冷启动方案IronClaw OOBE 首启引导设计解析两阶段提案、已发货建议契约与 WebChat v2 冷启动方案 IronClaw 的 OOBEOut of Bo人工智能AI 应用交互助手AI AgentIronClaw OOBE 首次体验工程实录执行计划、阶段门禁与持久化建议契约IronClaw OOBE 首次体验工程实录执行计划、阶段门禁与持久化建议契约 本文基于 IronClaw 仓库中的 OOBEOut Of Box Expe人工智能AI 应用交互助手AI Agent上一篇如何优化Nemotron-Cascade-2-30B-A3B推理速度5个关键技巧下一篇AngularUI - AngularJS 的配套套件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考