• 人工智能
• AI 应用
• 交互助手
• AI Agent

【免费下载链接】ironclaw

IronClaw is an Agent OS focused on privacy, security and extensibility

项目地址： https://gitcode.com/gh_mirrors/iro/ironclaw

点击查看 免费下载

导读：本文以 IronClaw 仓库中 docs/internal/design/oobe/CHECKLIST.md 为骨架，完整解读 OOBE（Out-Of-Box Experience，开箱即用体验）与首次引导（Onboarding）工作的验收清单体系。该清单是 OOBE 项目的"完成即合格"判定标准——每个方框都是一条可验证的结果，所有代码框都隐含其配套测试必须全绿。读者读完后，将能理解 Foundational（基础轨）与 Vision（愿景轨）两条交付轨道的阶段划分、每条任务的验收口径、退出闸门（Exit Gate）的成功指标，以及仓库中与清单对应的源码与契约证据，可直接用于同类 first-run 引导功能的拆解与验收实践。

---

一、CHECKLIST 是什么：OOBE 项目的"挑战性工件"

在 IronClaw 的 OOBE 文档包（位于 docs/internal/design/oobe/）中，CHECKLIST.md 扮演着"完成定义（Definition of Done）"的角色。它与同目录下的其他文档构成一套完整的设计治理链：

文档	角色
README.md	执行摘要（Executive Overview），给出双轨模型与评审决策点
PROPOSAL.md	完整规格：问题陈述、shipped-vs-net-new 范围盘点、依赖清单（§5）、安全模型、测试策略、风险与开放决策（§10）
PLAN.md	执行计划：阶段、闸门、PR 粒度、决策时点
IMPLEMENTATION.md	已过时的 v1 实现计划（Foundational 已被裁剪，保留作决策记录）
CHECKLIST.md	完成定义：按阶段分组，每个方框一条可验证结果
AUTOMATION-TASKS-CONTRACT.md	自动化任务接线契约（§1–§3 已被 PR #7694 取代，保留作设计意图记录）
VISION-RECONCILIATION.md	治理文档（governs）：与已落地的持久化后端建议契约对齐
SUGGESTION-ICONS.md	建议卡片图标语义枚举契约

按 README 的说明："Challenge CHECKLIST.md: it is the definition of done — anything missing goes there"，即任何人若认为交付内容有缺失，应该把缺失项写进 CHECKLIST。方框在落地它们的 PR 中被打勾（ticked）。这使其成为评审时最值得质疑的单一工件。

清单使用统一图例：[ ] 未开始 · [~] 进行中 · [x] 已完成。并且有一条贯穿性原则——每个代码框都隐含其测试必须全绿（对应 .claude/rules/testing.md 与 PROPOSAL §8 的测试策略）。

关键背景：Foundational 被裁剪，Vision 成为目标

CHECKLIST 中大量 F0–F5 条目标注为已完成（[x]），而 F1–F4 的多数条目仍是 [ ]。要正确理解这份清单，必须知道 VISION-RECONCILIATION.md 记录的范围转向：PR #7694（feat: add durable backend suggestions）已把"持久化后端建议契约"落地到 main，即原计划中属于 Vision-tier 的 agent 驱动建议生成器已经上线。因此程序不再先做 Foundational，而是直接基于已落地的建议契约构建 Vision；README、PROPOSAL、PLAN、IMPLEMENTATION 中所有关于"双轨"和"Foundational"的表述均属历史记录，以 VISION-RECONCILIATION.md 为准。

这也解释了 CHECKLIST 的独特状态：F0 全部打勾（去风险与解阻完成），F1–F4 尚未完成（后端契约已由 #7694 以另一种形态替代，见下文），F5 可选并行。

---

二、F0 — 去风险与解阻（De-risk & unblock）：已完成项拆解

F0 是所有后续阶段的前置，其完成情况全部为 [x]，是清单中信息密度最高的一组，逐条拆解如下：

1. 原型回滚、设计返工（§2A）：SuggestedTaskCard 表面现在无条件挂载在持久化建议信息流（durable suggestion feed）之上。背景是早期原型（PR #6994）曾在评审中被回滚——它把 mock 自动化渲染给了真实用户，违反数据安全底线。
2. 分支与 main 同步（post-#6918 family-folder reorg）：AUTOMATION-TASKS-CONTRACT.md 保留在规范路径 docs/internal/design/oobe/ 下。#6918 是已落地的家族文件夹重组，将事件相关 crate 归入 crates/events/ 等家族目录。
3. Carousel 数据安全（D-F5）：表面只读取持久化投影（durable projection），绝不再向真实用户返回 MOCK_COMPLETED_TASKS。这是整个 OOBE 工作的数据安全红线，也是早期原型被回滚的根本原因。
4. 契约与 post-#6918 命名对齐：事件日志 ironclaw_event_log + 持久化存储 ironclaw_event_store 位于 crates/events/ 下；facade RebornServicesApi 位于 ironclaw_assistant（见 reborn_services.rs）；路由位于 src/webui_v2/（已确认当前有效）。
5. 决策轮 #1 已记录：PROPOSAL §10 的第 2、4 项已解决；第 5 项于 2026-08-21 定案（设计治理归属 design-system 项目）。
6. D-F6 定案：DESIGN.md、设计令牌与组件工作台归属于 docs/internal/reborn/design-system/（PR #7257），OOBE 不在本地另起炉灶（PROPOSAL §5.6）。

F0 的工程启示：去风险阶段专门处理"会让后续阶段全部返工"的问题——数据安全、契约命名、治理归属。这是可迁移的实践：先消除结构性风险，再开始功能建设。

---

三、F1 — 自动化任务后端（D-F1）：契约已由 #7694 取代

F1 原本要建设 AutomationTask 的后端源数据，包含 11 个验收条目。重要前提：按照 AUTOMATION-TASKS-CONTRACT.md 顶部警告与 VISION-RECONCILIATION.md §4.3，这些条目已被 PR #7694 的实现取代，不应再按原样建设，但它们完整记录了原设计意图，仍是理解 OOBE 数据模型的教科书：

验收项	原设计内容	现状
AutomationTask 模型 + AutomationTaskId newtype	镜像 TS 形状，逐字段对齐	被 RebornSuggestion 形状取代
5 个事件（Proposed/Modified/Automated/Reverted/Cancelled）	每个均需 redacted、可重放、经持久化 sink 追加	被 typed store over ScopedFilesystem 取代
逐事件测试	持久化 · 重放 · 投影可见性 · 脱敏 · 排序 · 传输序列化	测试维度清单仍有效
AutomationTaskProjection	(tenant, user) 范围过滤 + 重放游标	被建议信息流取代
⚠ 跨用户隔离回归测试	用户 A 的任务绝不进入用户 B 的投影	非协商项，一直有效
5 条路由 + webui_v2_routes() 描述符行	描述符契约测试必须通过	路由已以 suggestions.* 形态落地
5 个 facade 方法（RebornServicesApi）	返回服务端确认记录，不做乐观回显	已以 suggestions.list/generate/start/dismiss 落地
Approve/Revert 走能力托管宿主	不引入第二条出站 HTTP 路径；成功仅从 provider 证据 + 读回确认	设计约束仍有效
Modify 按状态分支	suggested = 就地编辑；automated = 用新证据重跑	设计约束仍有效
list 缝 mock→fetch	无组件变更	已由契约实现

当前真实契约（冻结于 ironclaw_product_contracts，路由描述符可见于 webui_v2/descriptors.rs）：

方法	路由	产品操作
GET	/api/webchat/v2/suggestions	suggestions.list
POST	/api/webchat/v2/suggestions/generate	suggestions.generate
POST	/api/webchat/v2/suggestions/{id}/start	suggestion.start
DELETE	/api/webchat/v2/suggestions/{id}	suggestion.dismiss

对应响应形状（VISION-RECONCILIATION §1.1）：

RebornSuggestionsResponse {
  status: "empty" | "generating" | "ready" | "failed",
  generation_id?: string,
  retry_after_seconds?: number,
  suggestions: RebornSuggestion[]
}
RebornSuggestion { id, title, description, suggested_prompt, 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_id, user_id) 唯一，新一次生成会清空上一组。卡片数量限制为 1–5 张，title ≤ 80、description ≤ 240、suggested_prompt ≤ 2000 字符（schemas/suggestions.output.v1.json）。

---

四、F2 — 首次运行建议生成器（D-F2）：已由 #7694 完成

F2 原本要求"为全新用户产出首批建议卡"，CHECKLIST 中列出 4 条验收项。结合 README 与 PLAN，该阶段已被 PR #7694 的持久化生成器完成：

• 生成器是一个规范的无界运行（canonical unbounded run），携带只读能力白名单（memory search/read/tree、extension search、tool search/describe），最终以零工具推理（zero-tool inference）配合原生结构化输出 schema 定稿。
• prompts/suggestion_generation.md 对生成器有明确约束："没有证据表明账户、扩展、凭据或能力可用时，不得声称其可用"，并倾向 "助手在普通对话中即可完成的工作"。
• 卡片不携带工具身份（icon 仅为语义任务枚举、sources 为 1–5 条人类可读来源标签，均为展示性质），这一设计决策详见 SUGGESTION-ICONS.md。

CHECKLIST 中"新账户在第一步从真实事件看到建议卡"这一里程碑，对应前端 empty-state.tsx 中建议表面的挂载点，其消费逻辑在 useSuggestions.ts 中实现。

为什么原设计的 F1 事件/投影契约被放弃（VISION-RECONCILIATION §4.3）：#7694 改用 ScopedFilesystem 之上的 typed store，带受限 CAS、无 SQL 迁移，而不是五事件 + 投影。原契约 §1–§3 只作为设计意图记录保留。

---

五、F3 — Connect 接线 + Agent 模式（D-F3 + D-F4）

F3 的验收条目在 Vision 转向后发生重大变化，需对照两代设计理解：

原 Foundational 设计（已被取代）：

• 卡片 Connect 动作经由共享的 extension_name resolver 进入现有扩展授权流——不新增认证路径、无前端-only 回退（CLAUDE.md 不变式：凭据身份与扩展身份必须区分）。
• 测试必须在调用方（card→authorize handler）层面执行，而非只测 resolver 辅助函数。
• 授权成功后卡片从未连接态 → suggested 态。
• Agent 模式端点 + 会话水合（mirror global_auto_approve 的机制）。
• suggest/plan/auto 接入 resolve_gate；auto 是 global_auto_approve 的按类型泛化（typed per-kind generalization）。
• 门控抑制测试 + auto 的审计轨迹断言（auto 是提权行为）。
• 模式持久化并在加载时水合。

Vision 转向后的实际结论（VISION-RECONCILIATION §3–§4）：

• Connect 不再是卡片状态。卡片存在即可启动（startable），绝不因连接状态门控。
• 若启动的运行需要未连接的工具，agent 会发出既有的 AuthRequired 门控帧，线程渲染 AuthOauthCard——这是已上线的路径，保持不变（此假设需在 QA 中验证）。
• Vision 冷启动连接面板是独立的落地表面，由扩展目录（useExtensions）驱动，而非建议卡驱动；支持批量 OAuth 走查（选择 → 队列 → 逐工具授权 → 确认），且不新增后端认证路径。
• resolveConnectExtension 被弃用（其职责是卡片 app id → 目录扩展；目录驱动面板直接读目录）。
• 单活跃锁被移除：suggestion.start 为每条建议创建独立线程，因此无后端约束需要反映，卡片可并行运行。
• "+ Automation" 被移除：卡片 schema 无 automation_prompt 字段、#7694 无自动化路由，无从构建；动作整体从卡片删除。
• Agent 模式（Suggest/Plan/Auto/Bypass）仍是 net-new，未受 #7694 影响，需要持久化载体 + 类型化门控接线（PROPOSAL §7 / 契约 §7）。

契约 §7 中的模式门控语义表是理解整个权限模型的钥匙：

模式	门控行为
suggest	每个动作都触发审批门（当前默认）
plan	agent 发出批量计划，一次审批解决整组
auto	已审批的任务类型跳过逐动作门控；其他仍门控。即 global_auto_approve 的类型化泛化
bypass	完全不触发门控（全自动化）

auto/bypass 均为提权行为，需要显式的门控抑制路径测试 + 每次自动运行动作的审计轨迹。这一安全模型在 PROPOSAL.md §7 中有系统阐述。

---

六、F4 — 端到端 + 关键用户旅程（CUJ）

F4 是 Foundational 的功能收尾验收，包含 4 条：

1. TaskActionBar 决策模型（Approve/Modify/Cancel · Modify/Revert）经 facade 接线；剩余 seam 方法从 mock→fetch 翻转。原契约 §6 中 facade 方法语义为：modify 在 suggested 态就地编辑提案、在 automated 态重跑并提供新证据。
2. 首次运行引导 CUJ 加入回归基线：新用户 → 卡片 → 连接 → 审批 → 完成 → 出现在 /automations。
3. Carousel 门控（D-F5）退役：投影即真相，不再需要门控。
4. 全新账号上的端到端可演示。

结合 VISION-RECONCILIATION §2 的对照表，Vision 转向后 F4 的形态变为：Approve → suggestion.start 返回 {thread_id, run_id} 并导航进入线程；卡片获得持久的 thread_id/run_id 绑定，回归用户可以展示真实状态（这正是原 IMPLEMENTATION.md slice 2b 因"缺少持久化逐任务记录"而退役、现被 #7694 重新激活的能力）。Dismiss 变为持久的 DELETE。

---

七、F5 — 设计轨试点（D-F6）：可选、并行

F5 的核心结论是治理归属边界（2026-08-21 定案，PR #7257）：

• DESIGN.md、令牌系统、Storybook 工作台全部归属 docs/internal/reborn/design-system/（Phase 1 在 Epic #7038 下、以 PR #7750 发布；Phase 2–3 在 Epic #7781 下，issue #7042 跟踪 Phase-2 DESIGN.md 治理工作）。
• OOBE 的贡献是试点而非治理：把卡片分类法（taxonomy）与无障碍底线（a11y floors）贡献进该项目的 DESIGN.md，不在本地另立章程（PROPOSAL §5.6）。
• 验收项包括：卡片/操作栏/抽屉/模式胶囊的故事加入 Phase-1 目录（冒烟试玩 + 令牌/CSS 检查 + 每状态一个故事）；OOBE 组件通过设计验证门（与 mockup 1:1 对齐、令牌、亮暗双主题、无障碍）。

---

八、Foundational 退出闸门（Exit Gate）与成功指标

清单为 Foundational 定义了不可妥协的出口条件：

• 所有 F0–F4 方框关闭（F5 可选）。
• 真实用户在 landing/onboarding 路径上任何位置都接触不到 mock 数据。
• Onboarding CUJ 在真实构建上全绿。
• PROPOSAL §10 的 Foundational 决策（2、3、4、5）全部关闭。

同时从 epic #7044 继承了三条业务成功指标：

指标	定义
Time to first automation	登录 → 在该 epic 设定的目标时间内产生一个可用自动化
First-session activation	新用户在第一会话中接受 ≥1 个自动化的比例达到目标
Suggestion quality	首条建议的接受率 vs 驳回率达标（作为画像质量的代理指标）

注意：这些指标是验收成功与否的度量，不是实现细节——它们回答了"做完了"之后的"做得对了吗"。

---

九、Vision 阶段（V1–V4）与 Vision 退出闸门

Vision 是 Foundational 的超集，每条都是对应 Foundational 能力的增量，没有任何部分需要重做：

阶段	能力	超集自	要点
V1	Reveal + 预判状态（D-V2 + D-V3）	静态首卡	AutomationTaskAutomated（或 generating → ready 转换）驱动的 ai-spark 首自动化揭示；尊重 prefers-reduced-motion；"还没有自动化" / "正在生成第一个"投影状态经流路径呈现
V2	冷启动连接面板（D-V1）	逐卡连接	基于既有 pairing 基建的批量多工具 OAuth 编排（选择 → 队列 → 逐工具授权 → 确认）；不引入新后端认证路径
V3	停靠抽屉框架（D-V4）	朴素 pills-collapse 抽屉	停靠在 composer 上的带边框抽屉组件；复用 Foundational 抽屉状态机
V4	命名问候 + Bypass（D-V5 + V6）	匿名问候 + 三模式	用户名派生需记录来源优先级 + 无姓名回退（决策 §10.6，开放）；bypass 模式接线（无门控），带门控抑制测试 + 审计轨迹

Vision 退出闸门：

• 所有 V1–V4 方框关闭。
• 收敛验证：一旦自动化存在，Vision 与 Foundational 渲染出相同的已填充 carousel。

这最后一条是"设计一致性"的验收——两条轨道的卡片语言与渲染结果必须收敛于同一数据源，防止分叉。

---

十、从 CHECKLIST 到仓库：实现证据与落点对照

清单中的每条验收在仓库中都有对应落点（部分是已落地契约、部分是设计意图记录），对照如下：

已落地（main 当前状态）：

契约/组件	仓库路径
建议路由描述符	webui_v2/descriptors.rs（webui.v2.suggestions.list / .generate / suggestion.start / suggestion.dismiss）
建议表面挂载点	empty-state.tsx
建议卡片组件	suggested-task-card.tsx 及其测试 suggested-task-card.test.ts
建议表面组件	suggested-task-surface.tsx 及其测试 suggested-task-surface.test.ts
数据 hook	useSuggestions.ts 及其测试 useSuggestions.test.ts
facade 宿主	reborn_services.rs（RebornServicesApi）

设计意图记录（被 #7694 取代，勿按原样建设）：5 事件 + AutomationTaskProjection + 5 路由 + 5 facade 方法，见 AUTOMATION-TASKS-CONTRACT.md §1–§6；其"shipped-vs-net-new"范围表见 PROPOSAL.md §3–§4。

仍在路线图上的 net-new（未受 #7694 影响）：Agent 模式选择器及其类型化门控接线、pills-collapse 交互、命名问候（用户名派生源仍是开放决策）、ai-spark 揭示动画（需不绕过 app.css 静态动效策略的获批方案）。

---

十一、工程方法总结：这份清单为什么值得借鉴

CHECKLIST.md 的价值不在于条目本身，而在于它所体现的验收方法论：

1. 完成定义必须可验证：每个方框都指向一个可断言的结果（测试全绿、契约测试通过、隔离测试存在、CUJ 在回归基线中），而非模糊的"做完"。
2. 数据安全前置：F0 就把"真实用户接触不到 mock 数据"固化为结构性约束，而非事后检查；D-F5 的退役（F4）标志着数据源彻底切换为投影真相。
3. 文档治理链：README（概述）→ PROPOSAL（证据化规格）→ PLAN（时序）→ CHECKLIST（完成定义），外加 VISION-RECONCILIATION（治理文档）——新事实出现时，治理文档负责吸收变化、旧文档保留为决策记录，不互相覆盖。
4. 安全与提权显式化：auto/bypass 这类提权路径必须伴随门控抑制测试与审计轨迹，验收条目中明确列出。
5. 双轨收敛：Foundational 与 Vision 用"超集关系"保证不返工，用"同一已填充 carousel"的收敛验证保证不分叉。

对于任何要在自己的项目中落地"首次运行引导"的团队，这份清单提供了可直接复用的验收模板：先消除数据安全与治理归属风险（F0），再建设持久化数据源（F1），随后接线现有能力而非新建平行路径（F3），最后以关键用户旅程与业务指标收口（F4/退出闸门）。而 IronClaw 仓库中已落地的 suggestions.* 契约、useSuggestions hook 与 SuggestedTaskCard 组件，正是这份完成定义从纸面走向代码的最佳注脚。

• 人工智能
• AI 应用
• 交互助手
• AI Agent

【免费下载链接】ironclaw

IronClaw is an Agent OS focused on privacy, security and extensibility

项目地址： https://gitcode.com/gh_mirrors/iro/ironclaw

点击查看 免费下载