子应用

子应用（Sub-App）是 SparkWork 里唯一允许你把界面装进平台的机制： 一段 HTML/JS（V1）或一个受管多文件项目（V2），可以跑在内容区、侧面板、悬浮层里， 数据和文件长期保存，与会话无关。管理入口是侧栏的「我的应用」（视图 id sub-apps，带 Beta 标记）， 但创建与改代码主要在对话里由 Agent 完成。

这一页按真实代码讲清五件事：V1 与 V2 的区别、五个展示面里哪几个真的能跑、 能力与运行时开关的实际强制力、归档为什么不可逆、 以及 39 个 spark_app_* 工具分别做什么。

1. 定位与入口

子应用是「长期资源」而不是会话内容：源码、发布版本、应用数据、文件空间都存在本机， 删掉会话不会影响它。

1.1 真实入口与文案

• 侧栏「我的应用」：导航项 id sub-apps、文案键 nav.subApps（值为「我的应用」）、图标 Icons.Grid（apps/desktop/src/renderer/App.tsx:287、design/i18n/locales.ts:324）。
• 它是测试期功能：BETA_NAV_IDS 只含 workflows 与 sub-apps， 导航文字后渲染 Beta 小标签（App.tsx:297、:519； 标签文案 locales.ts:327 = Beta）。
• 该视图渲染 <SubAppsView />（App.tsx:1971-1972）； 点「打开」后切到 view === 'sub-app'，渲染 <SubAppRunView />（App.tsx:1973-1974），这才是应用的运行页。
• 管理页头部有三个动作：刷新、导入、通过 Agent 创建（design/views/SubAppsView.tsx:412-434）； 工具栏是「搜索应用名称 / 描述」+ 状态筛选（全部 / 已发布 / 草稿）+「显示已归档的应用」开关 （SubAppsView.tsx:437-482）。
• 「通过 Agent 创建」弹窗标题是「让 Agent 创建子应用」， 正文明确写出强制命令：/spark-app-create 记账工具（SubAppsView.tsx:808-831）。该命令在命令注册表里是builtin:spark-app-create（packages/agent-runtime/src/core/command-registry.ts:1304-1312）， 同一族还有 /spark-app、/spark-app-list、/spark-app-publish（command-registry.ts:1388）。
• 空态文案是「还没有子应用 — 在任意对话中让 Agent 帮你创建，例如「帮我做一个读书打卡子应用」」 （SubAppsView.tsx:507-511），和上面那句一起说明产品意图：管理页不做代码编辑。

1.2 别和另外两个「应用/扩展」搞混

子应用卡片上的「发布到团队」走的是第三套（TeamAssetPublishModal，SubAppsView.tsx:837-849）。它发布的是包，不是运行实例： V2 应用发到团队后以「新草稿」安装，连接槽绑定与发布版本不随包迁移 （SubAppsView.tsx:842 的 hint）。

2. 数据模型：V1 单文件与 V2 受管多文件

两种格式共用同一批表和同一个 appId，靠 format / draft_format区分。V1 是「一条源码字符串」，V2 是「一个目录 + 不可变制品」。

2.1 V1 的四个结构体

定义在 packages/protocol/src/sub-app.ts，字段与可选性如下 （format 缺省 v1，见 sub-app.ts:53-56）。

2.2 V2 的 spark-app.json

V2 是「受管项目」：草稿是一个磁盘目录下的多文件树，发布时校验并打包成按内容寻址的制品。 包清单固定叫 spark-app.json（packages/storage/src/sub-app-package.service.ts:27）， 由 SubAppPackageManifestSchema 校验（packages/protocol/src/sub-app-v2.ts:347-392，.strict()，多一个字段就报错）。

包体积三道上限是硬编码常量：SUB_APP_PACKAGE_MAX_FILES = 1000、SUB_APP_PACKAGE_MAX_BYTES = 20 MB、SUB_APP_PACKAGE_MAX_FILE_BYTES = 5 MB（sub-app-v2.ts:6-8），在 validatePackageFiles 里逐条判定 （sub-app-package.service.ts:749-768）。

路径规则共用 packagePath：相对路径、≤ 240 字符、无盘符与协议前缀、 分段中不得出现空串 / . / ..（sub-app-v2.ts:311-320）；落盘侧遍历时还会拒绝符号链接并二次校验 （sub-app-package.service.ts:900-916）。

2.3 两种格式的差异对照

V1 侧「发布即启用」写在 sub-app.repository.ts:325-329，注释也解释了原因 （菜单只显示「已发布 + 已启用」，否则用户还得再开一次开关）。 V2 侧相反，sub-app-platform.repository.ts:215-217 明确写 enabled = 0， 与 spark_app_project_publish 的文档口径一致： 「每次 V2 发布后都保持禁用，需用户查看 OS effects 后显式重新启用」。 这是两套格式里最容易踩反的一条。

3. 五个展示面里，只有三个真的能跑

SUB_APP_SURFACES 声明了五个值 （packages/protocol/src/sub-app.ts:17-23），但渲染路径只覆盖其中三个。 这一节把「声明」和「实际」分开写，避免你按枚举去猜行为。

3.1 每个面的真实宿主

判定依据：kindOfSurface() 只对 overlay 与 panel 返回类型， 其余一律返回 null（design/sub-app/SubAppSurfaceHost.tsx:171-174）； 主进程里没有任何为子应用创建 BrowserWindow 的代码 （在 apps/desktop/src/main/services/SubApp*.ts 与相关 IPC 文件中检索BrowserWindow 为空）。global-window 与 desktop-pet只出现在协议枚举、建库 CHECK 约束、MCP 工具枚举、SUB_APP_SURFACE_CONTRACTS（sub-app-developer-contract.mjs:30-51）、 一处 CSS 类和一个 switch 标签分支里。 写应用时如果把 surface 设成这两个值，发布不会报错，但用户点「打开」看不到窗口。

3.2 一个真实的标签 bug：panel 显示成英文

管理页的 surfaceLabel() 分支写的是 case 'sidebar'， 但合法枚举里没有 sidebar，只有 panel（SubAppsView.tsx:64-78 vs sub-app.ts:17-23）。 于是 surfaceLabel('panel') 命中 default，卡片上直接显示英文panel；而 sidebar 那个分支永远不会被执行。 这是显示层的小瑕疵，不影响运行，但你会以为它应该是「侧栏」。

3.3 实例上限与入口

• content：一次只运行一个，因为它就是当前视图本身。
• overlay / panel：这两类不进侧栏菜单， 统一入口是主窗口右下角的胶囊启动器（design/sub-app/SubAppSurfaceLauncher.tsx:59-69）： 任何视图（含画布模式）都常驻，指针移入即展开菜单、移出延迟收起， 胶囊本体可拖动摆放位置且用 localStorage 记忆。
• 同时运行的实例数有上限：MAX_OVERLAY_INSTANCES = 3、MAX_PANEL_INSTANCES = 1（SubAppSurfaceHost.tsx:31-32， 在 :255 处按 kind 取用）。
• 管理页卡片的「更多操作 → 以浮层运行 / 以侧栏运行」只对这两类面出现 （SubAppsView.tsx:558-571），文案按 surface 二选一。

3.4 沙箱与 CSP

应用不直接加载你的 HTML，而是被宿主合成一份运行文档再注入 CSP （design/sub-app/appRuntimeDocument.ts:34-62）。关键指令：

V1 的源码长度在合成文档时判定：source.length > SUB_APP_SOURCE_HARD_LIMIT直接抛错（appRuntimeDocument.ts:134-140）；设置里的sourceLengthLimit 是另一层更早的校验（见 §4.5）。 V1 文档通过 sub-app:runtime:put-doc 登记到主进程后以capability-asset://subapp-runtime/<token> 加载， 原因是 srcdoc 会继承 renderer 的 CSP 而拦掉应用内联脚本 （sub-app.ts:497-508 的注释）。

4. 能力与权限：哪里有真强制力

4.1 17 个能力名

SUB_APP_CAPABILITIES 共 17 个 （sub-app.ts:30-48）：

4.2 权限检查发生在哪一层

唯一的能力闸门在宿主 renderer 的 Bridge 里 （design/sub-app/bridgeHost.ts:396-411），顺序是：

1. 如果该实例 trusted === true，直接放行—— manifest 的 permissions 只作为旧数据兼容字段保留。
2. 否则 runtime 与 theme（只读宿主信息）免声明。
3. 其余能力必须出现在 runtimeInfo.permissions 里，否则返回PERMISSION_DENIED，提示是 「应用未声明 "<capability>" 权限，请在应用 manifest permissions 中申请后重新发布。」

MCP 工具侧也有一句必须对齐的口径：spark_app_create 的permissions 参数说明写着它是「兼容旧版本的 manifest 字段…… 当前 SparkWork 子应用按平台核心内部应用运行，宿主不会用它裁剪平台 IPC、MCP、 Plugin、Skill、Provider 或模型能力」 （sub-app-mcp-server.mjs:208-209）。 也就是说：别把 permissions 当成安全边界来推理， 它只影响非 trusted 实例的能力裁剪。

那你的应用到底算不算 trusted？判定条件是格式，界面上没有任何开关： 两个运行入口都写死 trusted: !isV2（useSubAppRunner.ts:240、:319），即V1 单 HTML 应用默认 trusted（permissions 不再裁剪能力， 但宿主未实现的域仍会落到 CAPABILITY_NOT_IMPLEMENTED），V2 受管多文件应用默认非 trusted。 V2 的能力清单来自 spark-app.json 的permissions.sparkCapabilities，由存储层映射为运行时的permissions（sub-app-package.service.ts:120）； 漏声明不会在启动时报错，而是在第一次调用该能力时返回PERMISSION_DENIED。因此同一份界面上，一个 V1 应用和一个 V2 应用 可以表现出完全不同的权限行为——这是本节最容易踩空的一点。

过了权限检查但宿主没实现的域，会落到兜底的CAPABILITY_NOT_IMPLEMENTED（bridgeHost.ts:710-711）。clipboard 与 notifications 就走这条路—— 连 SDK 符号都被标成 reserved（sub-app-developer-contract.mjs:337-346）， V2 发布时还会被 CAPABILITY_RESERVED 直接拦下。

4.3 V2 的三类权限分开声明

• sparkCapabilities：平台能力，取值同上面 17 个枚举。
• osEffects：network / filesystem / process。 这是告知性字段，不参与运行时拦截；它的作用是让启用前能向用户展示 「这个应用会碰系统」。spark_app_set_enabled 的说明要求： 含 service 或 OS effects 时必须先向用户展示「以当前用户权限运行且非安全沙箱」， 得到同意才传 confirmTrustedLocal=true。
• connections：连接槽名列表，每个名字都要在 connections 里有声明对象， 否则 CONNECTION_DECLARATION_MISSING。
• 另外：声明了 service 却不给 backend 能力会报BACKEND_PERMISSION_MISSING；声明 ipc 会报RAW_IPC_FORBIDDEN（两个校验都在sub-app-package.service.ts:809-842）。

4.4 设置里的三个运行时开关

位置：设置 → 子应用 → 运行时限制（分类键 sub-app，卡片组件design/sub-app/SubAppRuntimeSettingsCard.tsx， 在 views/SettingsView.tsx:544 注册）。 三个开关的默认值都是「放行」 （appRuntimeDocument.ts:28-32），卡片底部的说明区也直接写明「默认放行」。

这三项存在双层存储里：localStorage（键spark-settings-sub-app，用于首屏同步读取）+ 主进程settings:get/set（category sub-app、key data，权威源）。 改动会广播 spark-settings-updated，正在运行的实例会按新设置重建运行文档（sub-appRuntimeSettings.ts:1-10、SubAppRuntimeSettingsCard.tsx:22-24）。

注意上限是两层，别只记得一层：sourceLengthLimit 是用户可调的那层，SUB_APP_SOURCE_HARD_LIMIT = 5_000_000（5 MB）是 IPC/存储边界的硬上限， 即使把设置调成「不限制」也不会消失 （sub-app.ts:5-12）。协议注释还留了历史值 200_000， 说明这个默认值被刻意放开过。

5. 生命周期：归档是一条单行道

5.1 两个维度：发布状态 + enabled

publicationStatus 取 draft / published / archived（sub-app.ts:25，建库侧同样有 CHECK 约束，migrations/083_sub_apps.sql:14-15）；enabled 是独立布尔量，建库缺省 0。

「出现在应用入口」的判定是两个条件同时成立：list({ menuOnly: true }) 会加上publication_status = 'published' 且enabled = 1（sub-app.repository.ts:205-208）。 所以「草稿但已启用」不会出现在菜单里；反过来，禁用只影响可见性、不动版本。

另一个刻意的设计：setEnabled 不限制「仅已发布可启用」。 代码注释解释了原因——若只允许已发布启用，草稿态应用一旦禁用就再也恢复不了， 会形成状态死角（sub-app.repository.ts:342-345）。

5.2 归档之后没有回头路（重要）

这是本篇最需要你知道的一条：代码里不存在「取消归档 / 恢复」的路径。 归档后应用会变成永久只读，所有能改状态的入口都会被同一条守卫拦下：

为什么说「没有回头路」：全仓只有三处写publication_status 的 SQL——归档写 'archived'， V1 发布与 V2 发布写 'published'，而这两处发布都被上面的守卫挡住。 也就是说没有任何代码会把 archived 改回 draft 或published。

更要注意两处口径与代码不符，别被它们误导：

• spark_app_archive 的工具说明写「这是可逆的低风险收尾操作」 （sub-app-mcp-server.mjs:781-783）——按代码它不可逆。
• 管理页的归档二次确认只提示「归档后从列表主视图隐藏，可在此页开启「归档」筛选后查看」 （SubAppsView.tsx:297-301），没有提示从此不能再改。

唯一的「复活」办法是覆盖导入：importApp 会先删掉同 id 应用的 关联行、再整条重插，并按包内是否有发布版本写成 published 或 draft、enabled = 1（sub-app.repository.ts:606-635）。 代价是版本历史、数据、连接槽绑定都会被包内内容整体替换。 所以顺序上要先把应用「分享导出」成 .sparkapp（导出不检查归档状态）， 归档后悔了再覆盖导入回来。 结论：归档适合「确实不要了但想留个存档」； 如果是暂时不用，用「禁用」（enabled=0）而不是归档。

5.3 删除是真删

管理页的删除确认写得很清楚：「将永久删除源码、全部版本与应用数据，不可恢复。」 （SubAppsView.tsx:310-315）。 数据库侧靠外键级联：sub_app_releases、sub_app_data 等 都是 ON DELETE CASCADE；仓储层还显式补删一次， 以兼容旧库没开 foreign_keys pragma 的情况 （sub-app.repository.ts:424-440）。 删除历史版本另有约束，见 §6.2。

6. 版本与回滚

6.1 版本号怎么涨

两种格式都是取当前最大值 +1：V1 在sub-app.repository.ts:293-299，V2 在sub-app-platform.repository.ts:190-196，语句都是SELECT COALESCE(MAX(version), 0) …。 数据库对 (app_id, version) 有唯一约束 （083_sub_apps.sql:43），所以并发发布不会产生重复版本号。

发布同时是一次 CAS 写：WHERE id = ? AND draft_revision = ?， 影响行数不是 1 就抛 SubAppConflictError（sub-app.repository.ts:331-332）。这意味着Agent 在对话里改了草稿之后，你手上的旧 revision 发布会失败， 需要重新读一次草稿。

V1 发布还有一道拦截：草稿源码 trim() 后为空直接拒绝， 注释说明「空源码发布出去必然白屏」 （sub-app.repository.ts:288-291）。

6.2 当前生效版本不能删

deleteRelease 先找出应用行与目标版本，若release.id === app.published_release_id 就抛错 「当前生效版本不能删除，请先发布其他版本后再删除。」 （sub-app.repository.ts:404-418）。 界面上也一致：版本历史抽屉里当前生效那一条不显示删除按钮，改成「当前生效」标记 （SubAppsView.tsx:779-793）； 删除非当前版本的确认文案是「删除后不能恢复，但不会影响当前生效版本。」SubAppsView.tsx:781-786。

6.3 回滚不是切换指针

两套格式的回滚都把目标版本的内容写回草稿，而不是直接把published_release_id 指过去：

• V1：读出该 release 的 source/config/manifest/entry/surface，走一次updateDraft 语义把草稿整体替换，draft_revision + 1（sub-app.repository.ts:455-492）。
• V2：把该 release 的制品目录文件全部拷回草稿项目， 写成新的 projectRevision，再markDraftAsV2（sub-app-package.service.ts:548-580）。

所以界面上「回滚」之后还要再发布一次才会生效；回滚本身不改publishedVersion。管理页的发布确认文案也从侧面说明这条链路： 「将以草稿 revision N 生成新版本，发布后不可修改。」 （SubAppsView.tsx:694-699）。

6.4 V2 制品按内容去重

发布 V2 时会算一次目录摘要（digestFiles：把路径、字节数、内容按路径排序后 哈希进同一个 sha256，sub-app-package.service.ts:871-880）， 落库时写 ON CONFLICT(sha256) DO NOTHING 再回查真实 id （sub-app-platform.repository.ts:154-170）—— 同样内容的包只存一份。运行时会再校验一次摘要， 不匹配直接抛「子应用发布制品完整性校验失败，已拒绝运行。」 （sub-app-package.service.ts:733-738）。 无引用的制品会被清理，sub_app_release_artifacts.artifact_id 用的是ON DELETE RESTRICT（097_sub_app_platform_v2.sql:26）， 防止误删仍被引用的制品。

7. 数据、文件与分享包

7.1 应用数据：KV + revision CAS

存储是 sub_app_data，主键 (app_id, namespace, key)（083_sub_apps.sql:47-56）。 约定与限制：

• 命名空间与键都是 text(120) / text(240)： trim 后非空（sub-app.ts 的 IPC schema）。 Agent 侧工具的默认命名空间是 app（sub-app-mcp-server.mjs:199）。
• 值必须是可序列化 JSON 且序列化后 ≤ 512 KB， 否则抛 SubAppDataValidationError（sub-app.repository.ts:546-552）。
• 每条记录有 revision（建库 CHECK > 0）。 写入可传 expectedRevision 做乐观锁：键不存在却传了期望值会SubAppDataConflictError，版本不匹配同样冲突 （sub-app.repository.ts:554-580）。
• 删除必须带 expectedRevision， IPC schema 里它是必填（sub-app.ts 的'sub-app:data:delete'），Agent 工具spark_app_data_delete 同样要求先 get 拿 revision。

7.2 文件空间

与 KV 互补的一套「应用专属目录」：根目录是<userData>/sub-app-files/<appId>/（apps/desktop/src/main/ipc/registerSubAppIpc.ts:28； V2 侧同样在 registerSubAppPlatformIpc.ts:20 构造）。 路径由主进程规范化校验，越界抛PERMISSION_DENIED「文件路径超出应用专属目录。」 （SubAppFileStore.ts:27）。

• 路径规则：正斜杠分隔、非空、≤ 240 字符、无 .. 段、无盘符或协议前缀 （sub-app.ts 的 filePath），主进程还会再做一次 join+resolve 二次校验（协议注释里明确写了这一点）。
• 单文件写入上限 2 MB 文本（IPC schema 的content: z.string().max(2_000_000)），与分享包的导出上限一致。
• 适合放导出快照、生成的 markdown、素材这类文件型内容；结构化小状态应该用 KV。

7.3 分享包 .sparkapp

分享是全量语义：manifest + 草稿 + 全部发布版本 + 全命名空间 data + 文件空间，导入即可用，不做差量或选择性导入 （协议注释 sub-app.ts:222-236）。 格式常量 SUB_APP_SHARE_FORMAT_VERSION = 1。

冲突处理有两种：包内 appId 在本机已存在是 same-id， 可以覆盖导入，覆盖前会自动把本机当前应用备份成.sparkapp 并回报 backupPath（sub-app.ts 的 SubAppShareImportApplyResponse）； 只是同名不同 id 属于 same-name， 界面提示「本机有同名但不同身份的应用：默认作为新应用导入，名称会自动加后缀以区分。」 （SubAppShareModals.tsx:342）。 覆盖导入后宿主会关掉该应用的运行中实例， 避免旧源码继续跑在旧数据结构上（SubAppShareModals.tsx:209-212）。

导入前会先做一次能力与兼容性体检，检查码是固定枚举：FORMAT_VERSION、PLATFORM_VERSION、INTEGRITY、IPC_CHANNELS、SOURCE_RUNTIME_LIMIT、SECRET_HINT、DATA_LIMIT、FILE_LIMIT、DRAFT_EMPTY、V2_BUNDLE（sub-app.ts 的 SubAppShareImportCheck）。formatVersion 不识别时会直接拦下导入。

V1 应用导出时还会静态扫一遍源码，产出capabilities 报告：可解析的宿主 IPC 通道、Provider 引用、 疑似明文密钥的位置（只记位置不记内容）。 V2 另有可选的 v2 段承载受管项目、全部制品与连接槽绑定； 老版本平台解析时忽略该字段，导入会退化成「空壳 V1 草稿」。

8. V2 后台服务与持久任务

这两个能力只有 V2 有，也是 V2 相对 V1 的主要增量。 它们共用一个前提：能力声明要对得上，否则发布就被拦。

8.1 受管 Node 服务

在 spark-app.json 里声明 service 即启用，字段见 §2.2。 运行时行为由主进程管理（apps/desktop/src/main/services/SubAppServiceManager.ts）：

• lifecycle: 'application'：应用启用后就常驻，重启平台时 由 restoreEnabledServices() 重新拉起 （SubAppServiceManager.ts:65）； 崩溃/退出在计数 nextCount <= 3 时仍按常驻处理（:403）。
• lifecycle: 'on-demand'：有请求才起，空闲后按idleTimeoutSeconds 回收；缺省 300 秒（SubAppServiceManager.ts:273 的(published.manifest.service.idleTimeoutSeconds ?? 300) * 1_000）。
• 未启用时启动会被拒：PERMISSION_DENIED「子应用未启用，不能启动后台服务。」 （SubAppServiceManager.ts:231）。
• 状态枚举 stopped / starting / running / degraded / crashed（sub-app-v2.ts 的 SubAppServiceRuntimeStatus）， 建库侧同集合并带 CHECK（097_sub_app_platform_v2.sql:47-49）。
• 服务日志是有界内存日志，不落库、不分片： 查询上限 limit ≤ 500（IPC schema）， 管理界面的「开发与运维」抽屉读它渲染成 <pre>（SubAppOperationsDrawer.tsx:203-213）。

服务入口模块的约定形态在脚手架里能直接看到： 默认导出一个 invoke(action, input, context)，用context.progress(...) 报进度、未知 action 抛错 （sub-app-package.service.ts 的 scaffoldService()）。

8.2 持久任务固定在 release 上

任务表 sub_app_jobs，状态枚举queued / running / succeeded / failed / cancelled / interrupted（SUB_APP_JOB_STATUSES，sub-app-v2.ts:255-263），progress 是 0..1 的实数并带 CHECK （097_sub_app_platform_v2.sql:63-69）。

• release_id 是 NOT NULL 且外键ON DELETE RESTRICT，这就是「release pinning」： 任务绑在具体某个发布版本上，只要还有任务就不允许删掉那个版本。
• cancelRequested 是单独标志位：取消先置位， 由执行侧在检查点把状态收敛成 cancelled； 排队中取消会直接写成 cancelled（SubAppJobManager.ts:49-60）。
• 平台启动时 restore() 会把上次残留的 running 任务 统一标成 interrupted（SubAppJobManager.ts:19-20 → interruptRunningJobs()）。 所以「重启后任务还在跑」是不成立的，需要你自己按 checkpoint 续做。
• 发布前会检查是否有排队/运行中的任务，有就直接拒绝： 「子应用存在排队中或运行中的持久任务，为保持 release 一致性， 请等待任务结束或取消后再发布。」 （sub-app-package.service.ts:494-503）。 这条最容易在「刚触发一次长任务就想去点发布」时撞上。

8.3 联合诊断

spark_app_diagnose / sub-app:diagnose 会把包校验结果、 服务状态与运行时上报合并成一份结论，带一个correlationId，字段还包括runtimeObservation（最近一次运行上报的 status / errors / audit） （sub-app-v2.ts 的 SubAppDiagnosticResult）。 管理页的「开发与运维」抽屉最后一节「联合诊断」展示的就绪/需处理状态、 Correlation ID 与诊断条目就是它 （SubAppOperationsDrawer.tsx:229-245）。 排障时先看这里的 correlationId，再对照日志，能少绕很多路。

9. 连接槽与受管网络

9.1 声明与绑定是两件事

先在 spark-app.json 的 connections 里声明槽位， 再在运行时把槽位绑定到本机已有的 API Connection 或 Provider Profile。 绑定记录存在 sub_app_connection_bindings， 主键 (app_id, slot)（097_sub_app_platform_v2.sql:34-45）。

origin 的校验函数叫 origin，注释写明「必须是 http(s) origin， 不得包含路径、查询或片段」（sub-app-v2.ts:322-338）。 绑定越界时主进程报PERMISSION_DENIED「授权 origin 超出 manifest 声明范围。」 （apps/desktop/src/main/ipc/subAppBackend.ts:374）。

9.2 受管请求的五道检查

sparkApp.network.request / sparkApp.provider.request都走同一个网关（apps/desktop/src/main/services/SubAppNetworkGateway.ts）， 依次校验：

1. 应用必须已启用，否则 PERMISSION_DENIED「子应用未启用，不能发起受管网络请求。」 （:126）。
2. slot 必须在 manifest 里声明过，否则「应用未声明连接权限：<slot>」（:133）。
3. 授权 origin 不能为空，否则「连接没有可用的授权 origin。」（:146）。
4. 目标 URL 不得内嵌凭据，否则「受管请求仅允许无内嵌凭据的 HTTP(S) URL。」（:211）。
5. 目标 origin 必须在授权集合内（:214）， 且解析到本地/私网地址时必须已获私网授权（:221）。

这套检查的价值在于：密钥由宿主注入，不返回给子应用（sub-app-developer-contract.mjs 对sparkApp.network.request 的说明）。 所以应用可以调用第三方 API 而自己看不到 Key—— 这是「受管请求」和「设置里直接开外网」的本质区别，后者是裸 fetch。 请求还有容量治理：timeoutMs 限制在 1~30 秒 （IPC schema，sub-app-v2.ts 的 'sub-app:network:request'）。

10. 用 Agent 创建与维护

这是产品的主路径：管理页只管展示与生命周期，写代码靠对话。

10.1 工具从哪来

会话会把子应用 MCP server 以 spark_app 这个名字挂上 （packages/agent-runtime/src/services/session.service.ts:4481-4482）， 所以模型看到的工具名是 mcp__spark_app__spark_app_*。 服务实现是 packages/agent-runtime/src/tools/sub-app-mcp-server.mjs， 共 39 个工具。

两个对使用方式影响很大的工具说明值得原文记住：spark_app_create 明确写了「仅当用户明确要求平台内置子应用时」 才调用，用户只是想开发个工具/网页时应走外部项目；拿不准要先问 （sub-app-mcp-server.mjs:531-535）。 另外 MCP 描述里有一条设计先行流程： 新建或大改必须先出界面预览给用户确认，确认前不要落地，更不要发布 （sub-app-mcp-server.mjs:206-209 的 DESIGN_PREVIEW_WORKFLOW_GUIDE）。

10.2 开发契约与 19 个查询主题

spark_app_developer_guide 不带参数只返回主题目录； 要拿具体内容得按 topic / symbol / surface /query 精确查（工具 schema 里 includeExamples 默认 true）。 主题共 19 个 （sub-app-developer-contract.mjs:431-465）：overview、surfaces、runtime-sdk、theme、data、files、network、provider、backend、jobs、agent、media、canvas、browser、security、lifecycle、publishing、troubleshooting、recipes。

契约里每个 SDK 符号都带 status：implemented /legacy / reserved，符号集合导出为IMPLEMENTED_SPARK_APP_SYMBOLS 与 RESERVED_SPARK_APP_SYMBOLS（sub-app-developer-contract.mjs:481-489），校验器就是拿这两集合判对错的。 legacy 一族是原始 IPC 通道：sparkApp.ipc.invoke、sparkApp.ipc.on、sparkApp.platform.ipc/invoke/on/trusted， 契约里明确写了「参数契约不能从 channel 名推断」， 并且 ipc.on 的 stream channel 必须以 stream: 开头、 卸载时必须调用异步取消函数。

10.3 spark_app_validate 的 17 条诊断

写完之后先跑校验比直接发布省事得多。校验器在packages/agent-runtime/src/tools/sub-app-validator.mjs， 可产出的诊断码有：

注意这些都是静态提示，不是发布闸门——真正的发布阻断在 §2.2 那套 PACKAGE_* / MANIFEST_* 校验里。 两边代码不同、码表也不通用，别把 spark_app_validate 当发布预检通过来看。

10.4 V1 → V2 迁移

spark_app_migration_report 先扫一遍 V1 应用，列出迁移前要处理的依赖 （原始 IPC、Provider 明文密钥、相对资源、浏览器存储）；spark_app_migrate_v1 再把当前 V1 单文件草稿显式转成同appId 的 V2 多文件草稿。两者都不自动发布， 原 V1 历史 release 也保留 （仓储侧就是 SubAppPackageService.migrateV1，sub-app-package.service.ts:127）。 迁移是显式操作（要求传当前 expectedRevision），不会在你不知情时发生。

11. 数据库与落盘位置

11.1 八张表

迁移 083 的开头有一句设计说明值得引用：子应用故意没有 session 外键——会话只是操作入口， 删会话不应影响应用（083_sub_apps.sql:1-4）。

11.2 磁盘目录

删除应用后 cleanupDeletedApp 会删掉该项目目录并清理无引用制品 （sub-app-package.service.ts:613-621）；cleanupOrphanedArtifacts 也能单独清理孤儿制品 （:623-628）。

12. 排查表