kelly-app-skill-creator

Kelly App Skill Creator

将人类与 Agent 反复执行的操作转化为由 Busabase 支撑的技能，并使用规范的 Hono 项目，其常规交付目标为 Busabase AirApp。负责产品工作流和 App-in-Skill 工件契约；将 Busabase 资源实现和 AirApp 部署机制委派出去。

责任边界

此技能是格式层之上的品味层，这种分工能让两者各司其职：

• $busabase-app-creator（也以 busabase-skill-creator 和 busabase-template-creator 发布——一个技能，三个名称）负责所有确保工件有效的事项：技能／模板／软件包格式、AirApp 运行时语言、框架、服务端形态、依赖项和 SDK 限制、安全边界、验证、同步及部署机制。其自身契约称其关注“格式和正确性，而非品味”——它刻意不包含任何视觉偏好，因此这一层可以负责这些内容。
• 此技能负责所有使工件成为 Kelly 风格的事项：产品行为、信息架构、可见 UI、布局、交互模式、响应式行为、无障碍设计、帮助与设置、哈希路由，以及每个生成应用的视觉验收。底层工件通过该技能的“先软件包”路径（见其中的“Two Ways In”一节）创建，并叠加此技能的 UI 契约。
• $kelly-app-skill-creator-tests 负责生成应用的仓库级一致性、流程、响应式浏览器、开源 Busabase、Cloud OAuth、持久化及 AirApp 对等性测试。
• 不要将 Kelly UI 决策委派给 $busabase-app-creator，也不要让运行时脚手架取代或弱化此技能的桌面端或手机端外壳。
• 不要在此处重述 AirApp 运行时限制。若某条运行时规则会影响 UI 实现，应在 UI 契约内满足，而不是另立一套相互竞争的运行时契约。

强制依赖项

创建或更改应用前：

1. 阅读并遵循 $busabase 中关于连接、目标 Space、节点发现、ChangeRequests、审核、合并和可信变更的说明。
2. 阅读并遵循 $busabase-app-creator 中关于资源建模、原生 Views、Vault 边界、AirApp 限制、脚手架、验证、同步和部署的说明。创建 app-skill 时应采用其先软件包路径——该技能自身的指南已将技能引导至此路径，因为包含应用的技能就是模板。工件应作为模板软件包编写，并通过安装进行验证；应用的外观则由此技能的 UI 契约规定。

如果某项依赖不可用，请保留此技能的本地工件和产品契约，在执行不可用的 Busabase 操作前停止，并准确报告缺失的依赖项。不要另行编造数据后端。

在声明生成的应用已完成之前，请阅读并遵循 $kelly-app-skill-creator-tests。将应用自有的单元测试放在 <app-root>/test/，并将共享测试框架、外部 Busabase、OAuth、响应式浏览器和 AirApp 对等性验收交由该测试技能处理。如果该技能不可用，请运行应用的确定性本地检查，并报告缺失的一致性测试套件，而不要声称已完全完成。

参考资料索引

每次创建应用或更改 UI 前，都要完整阅读这三份 UI 参考资料—— 先读 editorial-visual-system.md，因为另外两份资料的所有视觉标记都以它为准。采取行动前，还要完整阅读选定的其他参考资料：

需求	参考资料
Busabase SDK、节点选择、配置、状态、锁、就绪状态、密钥	references/busabase-data-contract.md
运行时就绪状态、产品引导、设置 UX、重新配置	references/setup-onboarding.md
人类判定、Agent 修订、声明、外部执行、演练、恢复	references/review-and-execution-contract.md
产品形态选择	references/app-types.md
Research/Plan/Action/Retrospective 模式	references/workflow-patterns.md
字体、颜色系列、布局登记表、深色模式、交付就绪规则	references/editorial-visual-system.md
注意力 UI、审核操作、路由、设置、i18n	references/ui-workflow-patterns.md
桌面端和移动端外壳实现	references/mobile-shell-layout.md
大型零构建前端模块拆分	references/frontend-modules.md
使用级联层拆分大型样式表	references/css-modules.md
请求的屏幕截图或演示录制	references/demo-recording.md

应用内技能契约

• 每个生成的技能都包含一个完整、规范的 AirApp 项目，其中有自己的 package.json、锁文件、服务入口、浏览器文件和检查项。它位于 <skill-root>/content/<name>-app/——这就是 busabase 模板布局，也就是应用技能的形态：同一个目录既是技能，也是模板和可安装的软件包，不会有第二份副本。 kelly-email 是这种结构的参考示例。
• 项目仍位于 <skill-root>/app/ 的技能早于这种布局，尚待迁移——整个技能集正在转换中。请保持这类技能的现状；不要因无关工作而移动它，因为迁移还会改写测试套件路径、根脚本及脚本自身的相对导入，并且每项都需要重新运行测试套件。迁移应作为独立任务处理，而不是其他工作的副产品。
• 无论哪种根目录，都必须能通过 pnpm --dir <that-root> dev 在本地运行，但除非用户明确要求本地预览或本地调试，否则不要启动它。本文其余部分将适用的目录称为应用根目录。
• 当用户要求启动、打开或运行现有本地应用时，请打开不带 ?demo=1 或其他 Demo 选择器的正式 URL。常规启动路径必须经过 Busabase 连接和 OAuth 验证。只有在用户明确要求演示、截图、录制或单独的 UI 验收时，才选择 Demo；绝不要把 Demo URL 当作常规启动的应用地址。
• 运行时语言、框架、依赖项、SDK 包、服务器、Nodepod、验证规则和可部署文件规则，均遵循 $busabase-app-creator。不要在此处或生成的领域技能中重述或覆盖这些规则。
• 将已提交的本地源代码视为规范版本。基于该源代码构建并同步 AirApp；远程 AirApp 上的任何修改都必须回移到本地，不得遗漏。
• 本地和 AirApp 中使用相同的 UI、路由、领域逻辑、验证逻辑和 Busabase 资源映射。仅隔离运行时引导和传输适配器。
• 将 busabase-sdk 作为应用数据边界。持久化的领域配置、工作流状态、用户决策、锁定／声明和领域记录应存放在 Busabase 中，而不是本地 JSON、app/.data/、SQLite 或浏览器存储中。
• 环境变量仅用于连接引导，例如 BUSABASE_BASE_URL、BUSABASE_API_KEY 和 BUSABASE_SPACE_ID。它们不能作为并行的领域配置系统。
• 绝不要向浏览器代码、UI 状态、日志、演示或截图暴露 API 密钥或 Vault 值。只能在 Hono 服务端或受信任的 AirApp 执行边界内访问机密。
• 外部副作用必须在 AirApp 之外处理。AirApp 可以提交会生成 ChangeRequest 的决策或提案；只有受信任的 Agent 或 Workflow 才能在获得其所需授权后，使用 Vault 集成向外部系统发送、发布、删除、收费、转账或执行其他变更。
• 仅当本地存储中的浏览器展示状态可随时丢弃，且不会影响行为、授权、工作流或跨设备预期时，才使用本地存储。若操作员偏好应随操作员同步，则应将其存储在 Busabase 中。
• 不要提供服务提供方选择。无论是在本地开发环境、Cloud 还是可自托管的 Busabase 上，连接方式都必须遵循相同的 SDK 契约。

默认交付模式

除非用户明确要求使用 pnpm dev、本地 URL、本地预览或本地调试，否则使用 airapp-first。

• 在 airapp-first 模式下，将应用根目录作为规范来源并保留，运行确定性检查，然后将同一份已审核的目录树作为 Busabase AirApp ChangeRequest 提交。不要仅仅因为项目支持独立本地服务器，就启动它。
• 具备明确授权后，在指定的 AirApp CR 合并后，在所选 Busabase 中运行 AirApp，并在那里进行产品、桌面、手机、环境会话、资源和真实数据验收。返回准确的可点击 AirApp URL；不要用 localhost URL 替代。
• 仅在用户明确要求后使用 local-preview。然后启动 pnpm dev，应用 Connection UX Contract，将不带 Demo 的本地 URL 作为面向用户的主要 URL，并明确说明该进程是独立运行的，尚未上传或部署 AirApp。如果验收还要求 Demo，则将其作为单独的验证途径进行，而不是默认启动方式。
• 在 Busabase 中创建 Folder 或 Base 并不能证明 AirApp 已存在。声称 AirApp 已上传、已部署或正在 Busabase 中运行之前，请确认存在实际的 airapp 节点及其已合并的版本。
• 本地预览绝不会成为第二种实现。无论是否启动本地预览，同一份应用根目录树始终是提交给 AirApp 的唯一来源。

连接 UX 契约

当用户明确要求使用 local-preview 时，每个独立运行的 App-in-Skill 都必须无需 CLI 登录或粘贴 API key 即可使用。仅在此独立运行环境下，当不存在连接时，显示一个专注的设置屏幕，其中包含：

• 选中使用规范 Cloud URL 的 Busabase Cloud 选项；
• 一个 Custom server 选项，展开后显示一个 URL 输入字段，用于自托管或企业版 Busabase；
• 一个用于启动浏览器 OAuth 的主要操作 Connect Busabase；
• 当应用有确定性 Demo provider 时，提供一个视觉上较弱的次要 Demo 操作。

不要要求用户提供 API key、设备代码、终端命令、provider 选择或密钥存储选项。Cloud/custom 是托管目标选项，不是数据 provider 选项。所选服务器仅作为连接引导信息保留；所有产品配置仍通过 busabase-sdk 从 Busabase 节点获取。

OAuth 返回后，应区分身份验证成功、Space 选择和资源就绪状态。不带 Space 标头调用 Busabase 身份验证验证，以获取所有可访问的 Space。当 Cloud 或企业主机返回多个 Space 时，显示原生 Space 选择器，列出名称和安全 ID；在操作员确认选择之前，不要检查、初始化或修复应用资源。当只返回一个 Space 时，自动选择该 Space。开源 Busabase 会报告其唯一的 local Space，且不会显示此选择器。

仅将已验证的 Space ID 作为本地连接引导信息持久化，并与领域配置分开保存；同时在每个代理的 SDK 请求中注入 x-busabase-space。更改服务器或退出登录时，清除该选择。之后在设置和帮助屏幕中显示所选 Space 的名称/ID。会话过期或被撤销时，返回连接屏幕并显示简洁的重试消息。Demo 绝不能冒充成功连接，并且必须明确标记为只读。

使用 busabase-sdk/airapp-node 导出的规范 createBusabaseAirAppLocalGateway()；不要将 PKCE、令牌刷新、Space 持久化或代理代码复制到每个 server.js 中。浏览器提供的 x-busabase-space 不可信，绝不能覆盖网关已验证的服务端选择。将 SPACE_SELECTION_REQUIRED 和 SPACE_NOT_ALLOWED 视为稳定原因；绝不要解析人类可读的错误句子来决定要显示哪个设置屏幕。

“独立运行”是宿主声明的事实，不是应用推断的结果

复制 assets/runtime-detection/——不要重新推导。 共三个文件，每个生成的 App 都必须包含这三个文件：

资产	放置位置	作用
runtime.js	app/js/runtime.js	唯一负责回答“我在哪里”的模块
server-route.js	放入 server.js，与 /health 并列	将注入的事实传递给浏览器
check-rules.mjs	放入 scripts/check.mjs 断言	如果规则被破坏，则构建失败

这里复制的是资产，而不是说明文字，因为说明文字无法解决问题：65 个生成的 App 各自重新实现了相同的环回主机名测试，而且有一个 App 自己的检查脚本甚至将其设为必需条件。

Busabase 会在其托管的每个运行环境中启动 App 自己的进程，并注入一个 非空的 BUSABASE_AIRAPP_RUNTIME。其他任何人都不会设置它，因此该变量不存在这一事实就表明“独立运行”。server.js 必须重新暴露 describeBusabaseAirAppRuntime() 的结果——浏览器无法读取环境变量，而且 SDK 会兼容重命名后的运行环境值及未来新增的值。

绝不要根据 URL 推断这一点——无论是主机名、window.self !== window.top，还是 /api/airapp-preview/ 路径前缀。这类测试都会在两个方向上出错。Busabase 托管的 App 在 Desktop 和 OSS 上通过 localhost 提供服务（http://localhost:15419），所以“环回 ⇒ 独立运行”是错误的；而独立运行的 pnpm dev 通常可通过 LAN IP 或已签名的开发隧道访问，例如 https://3111-t14e66e832aa5e6a.dev.budaapps.com，因此“非环回 ⇒ 托管”也是错误的。第二种错误的危害更大：App 会隐藏自己的连接入口，未经凭据便调用 /api/v1，然后报告操作员无法处理的错误。

浏览器代码应当使用相对路径探测 __airapp/runtime（不带前导斜杠—— 托管的 App 可能从 Busabase 来源的子路径提供服务）， 并且必须验证响应是否为 JSON，因为托管来源的兜底路由可能会以 200 状态码返回 HTML 外壳。

runtime.js 使用**顶层 await**解析探测结果，因此两个谓词在各自的调用位置都保持同步。当一个模块既重新导出其中一个谓词，又调用它时，应使用 import + export，绝不要使用 export { … } from "./runtime.js"——重新导出不会在本地绑定名称，App 会在运行时因 shouldUseLocalGateway is not defined 而崩溃，尽管所有静态检查都会通过。

解析为三个状态，而非两个——hosted、standalone、unknown——并让每项决策在运行环境无法确定时都采用各自的安全默认值：

决策	unknown 时的安全默认值	原因
显示连接入口	显示	多余的入口可由操作员关闭；缺少入口则会让操作员陷入困境。
合并写入，而不是创建 ChangeRequest	不要合并	可供审查的写入仍可获批；自动合并的写入则已经越过了审查边界。

scripts/check.mjs 必须在检测到 location.hostname 和 iframe 嵌套测试时失败， 并且必须断言服务器暴露了 /__airapp/runtime。

完成身份验证后，应用 references/setup-onboarding.md。 基础设施就绪和产品引导是两回事：已连接且已物化的 AirApp 可能仍需要操作员提供上下文、策略、来源、阈值、计划或审批规则，工作流才能执行。

绝不要让操作员创建 Nodes/Bases、审批一份未命名的 ChangeRequests 清单，或将已物化的 ID 复制到部署配置中。对于已批准的延迟配置蓝图，只有在选择 Space 后才显示一个 Initialize workspace 操作，并在 $busabase-app-creator 于该 Space 中提交精确声明结构的幂等 ChangeRequest 时，显示简洁的进度信息。结构物化后自动继续。如果查看者没有写入权限，则显示唯一待处理的 CR ID 或所需的确切权限；操作员只需审查该请求，无须手动编写架构方案。 此屏幕必须遵循与主应用相同的手机端要求：在 390px 和 360px 宽度下，服务器选项按单列排列，主要操作按钮占满宽度，不出现水平溢出，也不显示终端操作说明。已部署的 AirApp 使用环境中的 Busabase 会话，不得显示本地 OAuth 身份验证门槛、调用 /auth/status 或 /auth/start，也不得导航到 Busabase OAuth 端点。

将 PKCE、回调验证、仅限所有者的本地凭据注册、刷新／撤销行为、代理注入以及 AirApp 环境会话规则交由 $busabase-app-creator 处理。浏览器 JavaScript 绝不能接收 OAuth 访问令牌、刷新令牌、PKCE 验证器或 Vault 值。

强制 UI 要求

为一个工作流打造一张编辑式工作台——不要做成落地页，也不要做成通用仪表板。将 references/editorial-visual-system.md、references/ui-workflow-patterns.md 和 references/mobile-shell-layout.md 作为强制实施与验收标准。

复制 assets/editorial-theme/——不要重新推导。 每个生成的 App 都必须包含这 4 个文件：

资源	放置位置	用途
editorial.css	app/styles/editorial.css，在 base-ui.css 之后、应用样式之前加载	在共享的 base-ui 令牌之上应用编辑式视觉配置；唯一允许定义颜色、字号、圆角或时长的文件
check-editorial.mjs	将其断言添加到 scripts/check.mjs	当其他样式表中出现原始值时，让构建失败
style-picker.css / style-picker.js	app/styles/style-picker.css + 一个 <script type="module"> 标签	“帮助与设置”控件，让操作员能够更改字体系列／字重——请参阅 ui-workflow-patterns.md 中的“样式：字体系列、字重、强调色”

之所以要复制这些资源，与 runtime-detection/ 的原因相同：仅靠文字说明无法奏效。在现有应用群中，每个已声明字号有 67% 落在 8–12.5px 范围内，实际使用了 31 种不同字号，而且没有一个应用通过变量定义字号——每个应用都根据同一段文字自行重新推导了字号比例。

• editorial.css 是基于整套产品共享的 scripts/base-ui.css 构建的主题，而非其替代品。共享组件仍由 base-ui 负责；主题只重新定义这些组件读取的令牌。
• 为每个应用从资源中定义的 7 种配色主题（data-theme）和 3 种布局风格（data-editorial）中各选一种。默认的 ink-paper——暖中性色纸张、墨色、一种克制的靛蓝，以及近似墨色的主按钮——适用于大多数工作场景；更醒目的主题应经过主动选择，而非继承。不要在某个应用的样式表中另创第 8 种主题；应说明哪种主题最接近，以及它的问题所在。
• 如果主题内容不适合衬线标题，可通过一个 data-display="sans" 属性关闭衬线标题。视觉风格由字号比例和规则支撑；不必依赖字体本身。
• 展示用衬线字体仅用于展示文本，即 --text-xl 及以上字号。在正文尺寸下，CJK 衬线字体比它替代的无衬线字体更难阅读，而且这些应用会提供本地化文案。
• 将录制界面视为一等界面：承载关键信息的内容不得小于 15px；查看者必须注意到的状态变化使用 --ease-state；已持久化的判定使用一次性的 --ease-flash；不要用 1px 的近白色线条承载结构。
• 将品牌标识、供人查看的摘要、工作流导航以及 Help & Settings 放在固定的桌面侧边栏中。收起时改为带面板图标的图标栏；品牌图标始终保持可见。
• 用行动导向的语言说明人工任务，并在工作流导航上方显示主要待关注数量。审核队列使用稳定的行引用。
• 对于以条目为中心的工作，使用桌面端列表/详情分栏，例如 minmax(360px, 38%) minmax(0, 1fr)。列表和详情内容应分别在各自面板内滚动。
• 对有实际意义的视图、选择状态以及 Help & Settings 使用原生哈希路由，以便刷新和浏览器前进/后退能够恢复上下文。
• 在宽度不超过 720px 时，切换为真正的手机布局：紧凑顶部栏、带遮罩层的画布外侧边栏、独立的全高列表和详情面板、固定的返回列表控件，以及在工作流包含主要详情操作时固定显示该操作。不要只是缩小桌面界面。
• 触控目标保持在 36-44px，长值应换行，并避免页面级水平溢出。将 Help & Settings 设为响应式模态框，并在手机上改为全屏面板。
• 在约 1280x820、1280x720（录制视口——垂直方向相差 100 像素，就会导致可见三行与列表被折叠隐藏的区别）、390x844 和 360x740 分别验证。交付前测试侧边栏收起/抽屉、遮罩层、导航、行选择、返回详情、模态框标签页、浏览器历史记录和溢出问题。至少截取两种配色主题的屏幕，其中一种为深色主题；否则硬编码颜色的问题会无从察觉。

Busabase 资源规范

根据节点的原生优势进行选择，而不是把所有内容都塞进一个 JSON 块：

• 使用 Folder 和 Node 树管理应用根目录、资源发现、层级结构、稳定归属和导航；
• 使用 Base 管理结构化配置、策略、工作流行、审核项、声明、指标和关联关系；
• 使用 Vault 管理机密和机密引用；只呈现就绪状态；
• 使用 Doc 管理长篇说明、研究模板、操作手册和可编辑的叙述性内容；
• 使用 Drive 和 File 管理导入项、附件、导出项和大型制品；
• 使用原生 Views 承载日常表格、图库、看板、日历和甘特图工作；
• 使用 AirApp 进行跨资源综合分析、优先级排序、引导和聚焦命令。

实施前创建明确的资源映射。记录稳定的节点 ID 或 slug、用途、架构/版本、读写行为、变更路径，以及使用各资源的屏幕或任务。参见 references/busabase-data-contract.md。

产品循环

默认采用以下四阶段工作循环。

研究

按计划或按需收集证据。按周期键更新幂等报告，并记录来源时效性、覆盖范围、不确定性和发现。

规划

将证据转化为具体且去重的工作项，并关联回其来源。允许用户选择退出、阻止、调整优先级、重新安排或请求修订。使用待处理队列，而不是强迫用户逐行检查。

执行

以原子方式领取符合条件的工作，创建可供审核的交付物或 ChangeRequests，记录进度和失败，并确保影响重大的副作用须经过可信的审批／执行路径。

回顾

将结果与原始证据和决策进行比较。将对提示词、技能、阈值、来源、计划安排、资源架构或 UI 的改进建议作为新的规划项提出；不要根据单次结果悄悄改写生产规则。

并非每个阶段都需要单独的界面。说明每个阶段在哪里进行，或为何有意省略。

发现

一次只问一个问题。充分了解以下信息：

• 谁负责操作应用、操作频率如何，以及他们负责达成什么结果；
• 什么会触发研究，以及如何定义一个报告周期；
• 证据如何转化为去重的规划项；
• 哪些项目默认符合条件，以及人们可以停止或修订哪些项目；
• 执行会产出什么、在哪里审核，以及哪些影响会作用于外部；
• 什么能让回顾有用；
• 哪些状态需要人工关注；
• 哪些操作应在原生 Views 中进行，哪些应由 AirApp 负责；
• 哪些现有 Busabase Folder、Base、Doc、Drive、File、Skill 或 Vault 节点应重复使用，哪些必须提议创建。

不要询问用户选择提供商、框架、架构机制、本地配置路径或密钥存储方式。

产品叠加说明

创建前，为 $busabase-app-creator 提供这份简洁的叠加说明：

# Product Overlay

User and outcome: ...
App type: ...

Research: trigger, period key, evidence, freshness, idempotency
Plan: issue/recommendation rule, traceability, default eligibility, opt-out
Action: atomic claim, deliverable, review point, external side effects
Retrospective: outcome signals, cadence, skill/process feedback

Human attention states: ...
Agent responsibilities: ...
Product onboarding: required operating context and completion/version rule
Native Views needed: ...
AirApp screens and focused actions: ...
Busabase resource map: Folder/Node root, Bases, Docs, Drives/Files, Vault refs
Delivery mode: airapp-first unless the user explicitly requested local-preview
Guide copy in plain language: ...
Explicit exclusions: ...

叠加说明描述产品行为。$busabase-app-creator 会将其转化为完整的资源图谱、能力矩阵、安全模型、规范的应用根目录脚手架、兼容 AirApp 的实现、验证、同步和部署。

创建工作流

1. 阅读相关参考资料，并检查附近基于 App 的技能，再选择结构。
2. 建立 Busabase 连接，并明确指定目标 Space。
3. 探索目标 Node 树，并起草资源映射。
4. 商定 Product Overlay，并让 $busabase-app-creator 验证技术蓝图。
5. 让 $busabase-app-creator 在 App 根目录创建或更新完整的规范项目。不要在此技能中另行设计第二套运行时布局。
6. 在 busabase-sdk 上实现一个 Busabase 仓库／服务边界。浏览器代码调用 Hono/AirApp 路由，不持有凭据。
7. 实现运行时／产品引导状态，以及 Overlay 要求的每个审核／执行生命周期。应用 references/setup-onboarding.md 和 references/review-and-execution-contract.md；不要自行发明本地标记、锁或第二个提供方。
8. 让 setup、seed、refresh、migration、validation 和 sync 脚本保持为共享模块上的轻量入口。除非领域适配器严格要求，否则避免使用 Python、原生二进制文件、子进程编排和基于文件系统的工作流状态，并确保兼容 AirApp。
9. 运行 App 自有的 lint/typecheck/tests/build，不要启动持久运行的本地服务；然后使用 $kelly-app-skill-creator-tests 执行仓库级合约、浏览器、OSS 和可用的 Cloud 测试套件。仅当用户明确选择了 local-preview 时，才运行 pnpm --dir <app-root> dev，并在继续前完成本地连接、工作流、恢复、桌面端和手机端验收。
10. 默认情况下，通过 $busabase-app-creator 直接将同一份规范源代码提交为可审核的 AirApp CR；返回可点击的 Busabase 审核 URL，并等待指定的合并授权。
11. 合并后，在 Busabase 中运行 AirApp，并验证同一份资源映射、代表性数据、环境会话、主工作流、恢复状态以及强制要求的桌面／手机端外壳行为。报告规范 AirApp URL。只有在明确请求 local-preview 时才报告本地 URL。

入门引导与就绪状态

遵循 references/setup-onboarding.md。即使 Busabase 尚未就绪，应用也必须能在明确指定的本地预览模式下启动；托管的 AirApp 必须呈现一个设置/入门引导关卡，而不是静默切换到本地数据或 Demo 数据。区分运行时就绪状态与产品入门引导。

运行时就绪状态包括：

• 缺少连接初始化信息；
• 未通过身份验证或无法访问 Busabase；
• Space 不明确或无法访问；
• 缺少应用 Folder/资源；
• 需要进行架构迁移；
• 缺少 Vault 引用；
• 已就绪。

产品入门引导单独涵盖此工作流所需的持久化运行上下文、策略、来源、计划、阈值和审批规则。将其字段及完成状态/版本持久化到 Busabase。在产品前置条件未完成时，不得启用外部读取或影响重大的操作。

在 Product Overlay 和机器可读蓝图中声明入门引导契约，包含正整数 version、明确的必填字段、各字段所属的 Base/Doc 资源键、验证规则，以及每个字段所解锁的操作。没有入门引导要求的产品必须明确声明空契约并说明理由；省略不等同于“无要求”。在指定的 Busabase 资源中持久化 onboarding_version、完成状态和实际完成时间。版本不匹配时，应进入 needs_review 或 migration_needed 状态，不得标记为 complete。

对于缺失或已过期的身份验证，遵循上文的 Connection UX Contract；不得用 CLI 指令或凭据输入框替代其中的 OAuth 操作。

显示经过脱敏的连接和资源标识符，以及可执行的恢复步骤。切勿在浏览器中接收或回显密钥值。必要时，通过经审核的 ChangeRequests 配置或修复资源。恢复步骤可以要求操作员初始化、重试、选择 Space 或检查一个指定的 CR；不得让操作员负责构建 Node/Base 或连接 ID。

完成标准

仅当满足以下条件时才算完成：

• 技能包含完整的规范应用根目录项目，并且无论是否请求本地预览，pnpm --dir <app-root> dev 都受支持；
• $busabase-app-creator 的运行时、SDK、安全、验证和部署检查均通过，且不存在冲突的本地运行时约定；
• $kelly-app-skill-creator-tests 要求的本地和 OSS 套件均通过；当其声明的环境可用时，Cloud/AirApp 套件也通过；明确报告跳过的外部套件；
• Busabase 连接、目标 Space、应用根目录和资源映射均明确；
• 所有持久化配置、状态、决策、声明和领域数据均使用 busabase-sdk 和适当的 Busabase 节点；
• Vault 值和 API 凭据绝不会出现在浏览器可见界面中；
• 本地设置提供 Cloud/自定义 URL OAuth 以及明确的 Demo 路径，而已部署的 AirApp 使用其环境会话；
• 本地 OAuth 会验证可访问的 Spaces，自动选择唯一的 Space 或开源 Space；存在多个 Spaces 时，要求用户明确选择；在选择之前不进行任何资源初始化；
• 本地 Hono 边界使用 busabase-sdk/airapp-node，忽略传入的 Space 标头，并根据稳定的 Space 原因进行分支处理；
• Research、Plan、Action 和 Retrospective 均有体现，或已明确决定省略；
• 人工关注、退出、审核和 Agent 认领规则均明确无歧义；
• 运行时就绪状态、产品引导、审核结论、Agent 修订、外部执行和恢复均遵循所选参考约定；
• 蓝图声明引导版本、必填字段、Busabase 存储、验证和解锁规则，或提供明确的空契约及其理由；
• 本地和 AirApp 运行使用相同的应用源代码和资源约定；
• 默认交付已生成合并且验证通过的 AirApp，并提供可点击的目标 URL；仅在明确请求本地预览时才报告本地 URL；
• 在适用情况下，已实现 Kelly 桌面端侧边栏、关注事项、工作流导航、列表/详情、哈希路由以及 Help & Settings 契约；
• editorial.css 是应用的第一个样式表，editorialAssertions 位于 scripts/check.mjs 中并通过检查，且已说明声明的 data-theme / data-editorial 默认值；
• 已对概览和工作区进行截图，涵盖至少两个配色系列，其中包括一个深色系列；另有一段 10 秒的审批视频片段展示状态变化，无需事先知道要关注什么；
• 1280x820 和 1280x720 桌面端、390px 手机端及 360px 窄屏手机端的工作流均通过视觉、交互和水平溢出检查；
• 依赖技能要求的验证、部署和真实数据检查均已通过，并按照“A Green Suite Is Not An Acceptance”中的说明完成验证。

测试全绿不等于验收通过

测试通过只能说明你想到的用例都成立。在报告变更已验证之前，请像真实调用方那样实际测试：

• 在真实实例上运行实际命令，而不只是运行单元用例。对集成进行纯断言检查，只能说明你的假设成立。
• 确认新增的回归测试在没有修复时会失败。 诊断问题后才编写的测试通常无论如何都会通过；无法失败的测试毫无证明力。撤销修复，观察测试变红，再恢复修复。
• 确认现有测试实际覆盖了哪个变体。 一个保留服务端自有 ID 的往返测试，在一个会清空作用域内所有密钥的错误存在时仍然通过，因为出错的路径是没人编写测试的那个变体。
• 先怀疑环境，再下诊断结论。 过期的本地数据库、缺失的加密密钥或缺少 node_modules，都可能导致看起来和待审查变更引入的回归一模一样的失败。在得出任何结论前，先确认到底是哪种情况。
• 更改共享接口后，重新检查下游假设。 修复一条此前返回 404 的路由后，每个客户端未经测试的错误处理路径都会变成实际执行路径。应一并发布客户端侧的后续修复，而不是等用户发现后再处理。

报告实际执行了什么，以及跳过了什么。不说明测试在哪个环境中运行，只说“测试通过”不算结果。

停止条件

如果下一项必需操作所需的依赖不可用、目标 Space 或应用根目录不明确、node 能力无法支持预期模型、密钥会泄露到浏览器、某项副作用缺少经过审查的可信执行路径，或者本地实现与 AirApp 实现需要采用不同的业务逻辑，就应停止。