工作区应用

文档版本：3.0 状态：声明式元数据驱动（app.json + 平台标准 UI 渲染器） 表述：面向产品、运营、对接与管理员；用户可见文案以 用户表达 为准，实现名见 实现对照。

关联：

• 产品规格.md §4.2.4（平台插件模块 — 与本机制互补）
• 工作区能力包.md
• 技能组成规范.md
• 帮助动作链接.md
• 用户侧说明：help/product-features/workspace-apps.md
• 报表场景专项：技能对话生成报表应用对齐指南.md

---

1. 结论先说

工作区应用是本工作区内可独立运行的轻量业务软件：自有 SQLite 数据文件、声明式界面描述（app.json）、可选 Python 自定义动作 与 自动生成的技能说明（供智能体对话调用）。

Cadau 主库不存业务明细，只存应用元数据；业务数据在 {RUNTIME_DIR}/workspaces/{workspaceId}/apps/{appSlug}/data/app.db。

界面不由 LLM 生成 HTML，而由 Web 端 标准渲染器 根据 app.json 中的实体、视图、动作定义绘制列表与表单。

平台提供：

---

2. 用户能感受到什么

1. 顶栏 「应用」 进入 应用桌面；已发布的工作流 与自建业务应用一同展示。
2. 工作流 在顶栏功能菜单中，用于从模板创建流程、发布到桌面、查看待办。
3. 新建应用：选名称、程序集、模板（简易入库 / 空白记事）。
4. 导入应用包：管理侧栏可上传 zip；打开应用后可 导出应用包（跨工作区迁移界面与逻辑，不含业务数据；若依赖预定义查询会尽量附带定义，导入时可合并进目标数据连接）。
5. 消息 中对 工作智能体 描述轻量需求，可自动创建应用并给出 打开应用 链接。
6. 界面按钮与（后续）对话操作共用同一 invoke 契约。

---

3. 与平台插件的分工

| | 工作区应用 | 平台插件模块（§4.2.4） | |--|-----------|------------------------| | 创建 | 模板 / 对话生成 app.json | 独立工程 + manifest | | 数据 | 每应用一个 SQLite | 自有 DB（可 PostgreSQL 等） | | UI | 平台标准渲染器 | 完整 Web 框架 | | 适用 | 部门小工具、登记类场景 | 审批流、合规、跨系统、长期运维 | | 演进 | 可导出/升级为插件 | 可提供程序集模板 |

对话创建时若检测到 审批流 / 跨工作区 / ERP 对接 等复杂需求，会提示改用 平台插件。

---

4. 应用包结构（运行时）

RUNTIME_DIR/workspaces/{workspaceId}/apps/{appSlug}/
  manifest.json       # 清单：名称、程序集、ui_mode=metadata、intents
  app.json            # 声明式 spec：entities、views、actions
  data/app.db         # 业务 SQLite（与 mindlink.db 分离）
  schema/001_init.sql # 由 entities 自动生成
  logic/handlers.py   # 仅 impl=script 的自定义动作
  skills/SKILL.md     # 由 spec 自动生成（对话操作说明）

平台主库表 workspace_apps：id、workspace_id、app_slug、display_name、suite、icon、status、created_by_user_id、时间戳。

---

5. app.json 契约（v1）

完整手写规范（字段级说明、校验清单、员工画像对照）：../../sdk/appsdk/界面描述规范.md

目录说明：../../sdk/appsdk/README.md

{
  "version": 1,
  "entities": [{
    "name": "inventory_items",
    "label": "库存项",
    "fields": [
      { "name": "name", "label": "商品名", "type": "text", "required": true },
      { "name": "quantity", "label": "数量", "type": "number", "required": true, "min": 1 }
    ]
  }],
  "views": [
    { "type": "action_form", "action": "inbound.create", "label": "入库登记" },
    { "type": "list", "entity": "inventory_items", "label": "库存列表", "columns": ["name", "quantity", "note"] }
  ],
  "actions": [
    { "id": "inbound.create", "label": "商品入库", "impl": "script", "params": [...] }
  ]
}

视图类型（摘要）：

字段类型：text | number | textarea | datetime | select

---

6. HTTP API（契约）

均需登录；路径中 {id} 为工作区 id；校验 工作区成员。

invoke 请求体：

{
  "action": "inbound.create",
  "params": { "name": "A 商品", "quantity": 20 }
}

---

7. invoke 动作

7.1 内置动作

7.2 自定义动作（impl=script）

未命中内置时加载应用包内 logic/handlers.py（及同包 scripts/、assets/ 等），经安全检查后在沙箱执行。

invoke 会注入通用 平台桥（ctx["platform"]）：脚本可 query_run / query_list 预定义查询、save_upload 保存附件，无需在后台为某一业务写死流水线——业务逻辑留在创建应用时写入的 Python 里。

inventory 模板提供 inbound.create；employee_profile 模板提供完整生成脚本：创建时写入与技能同源的 references/pipeline.json + 组装脚本，提交后按 pipeline 逐步取数并组装 HTML；若某步取数失败会在结果中返回 warnings（不再静默丢字段）。

「依据技能 @xxx 做一个员工画像应用」时，会用该技能的 scripts/、assets/、references/ 覆盖模板文件，保证应用与对话技能共用同一套取数步骤。

「依据技能做 HTML 报表应用」时：技能计算脚本进应用包，或生成应用自有的 scripts/build_report.py（规则内联）。后续各种报表技能各自带各自的填充规则，互不共用平台通用计算引擎。

---

8. 前端：应用桌面与标准渲染器

不再使用 iframe / 自定义 HTML / postMessage 桥。

---

9. 对话创建应用（appfromchat）

9.1 流程

• FastRoute：入库关键词 → inventory 模板；「员工画像」→ employee_profile 模板
• HTML 报表（参考技能）：用户要「生成应用」且能解析到 HTML/ECharts 报表技能时，不经整应用 LLM：

- 无 @ 时，可从本会话近期 skill_read 继承刚用过的技能 - 计算一律在应用包内：优先同步技能自带 scripts/*（含 build_report） - 若技能无计算脚本（常见：统计在对话 LLM里完成、仅 file_write 落 HTML）：由 LLM 根据技能正文 + 本会话对话摘要，生成该应用的 scripts/build_report.py（对等对话中的归类/填表）；handlers 只取数并调用该脚本 - LLM 生成失败且正文归类表可解析时，才回退确定性内联；再否则失败提示 @ 技能重试 - 非忠实路径才回退平台通用 assemble_html_report.py

• LLM：其它轻量场景输出 app_spec + 可选 handlers_py
• PersistApp：校验 spec → 生成 schema/SKILL → 写目录；同步 @/继承技能的 scripts/assets/references

复杂需求（审批、跨系统等）返回提示，建议使用平台插件。

---

10. 实现对照

应用开发助手（对话改进应用）：面向完整应用开发与迭代（界面/数据模型 + 取数/逻辑/流程）。模型上下文含 ../../sdk/appsdk 运行规则摘要，并按意图追加章节；改进时另附当前应用包快照。输入框可用 @ 引用工作区技能：后端把该技能的 scripts/、assets/、references/ 作为「参考技能」摘要注入提示（借鉴思路，默认不整包覆盖当前应用）。生成过程（进度步骤、可折叠推理与模型输出）显示在对话时间线内，无独立过程窗。POST .../improve/draft/stream（SSE：start / progress / done / error）生成草案，请求可带 skill_ids；POST .../improve/publish 应用，并返回应用前 previous 快照供回滚。可修订路径以 workspaceapp.ImproveCoreRelPaths 为真值。Web 端支持进度心跳、停止、排队、附件/粘贴截图、@ 参考技能、上下文占用圆环与本会话「回滚上一版」。

应用包面板：打开应用后顶栏「应用包」可浏览包内文件树并预览；白名单路径可编辑保存（GET/PUT .../package/file）。app.json 只读，界面改动仍走助手或规范。

---

11. 后续（P2+）

• [ ] 工作智能体对话 直接 invoke（召回 SKILL + FastRoute intents）
• [x] 程序集一等对象 + 混合桌面（程序集图标 ∪ 固定应用）+ 工作区应用模板（创建/发布/下架/删除）
• [ ] 跨工作区 模板市场、应用版本与回滚
• [x] 应用包 zip 导入 / 导出（界面与逻辑；不含业务数据；可附带并合并预定义查询依赖）
• [ ] 应用导出为 平台插件 骨架