手工搭建指南（读完能搭一个 App）

目标：不依赖「对话创建」，仅凭本目录文档 + 模板对照，手工做出可打开、可点、可取数（可选）的工作区应用。 建议阅读顺序见 README。

---

0. 你将搭出什么

两条路径任选：

复杂视觉操作台 → 先读 视图与布局，通常应走 pluginsdk。

---

1. 准备

1. 本地或测试环境已能打开 Cadau，并进入某工作区。
2. 知道运行时应用目录（创建应用后）：

{RUNTIME_DIR}/workspaces/{workspaceId}/apps/{appSlug}/

1. 若要取数：工作区已配置数据连接，并有可用的预定义查询。
2. 编辑文件后刷新应用页；自定义脚本以下一次 invoke 为准（勿另起冲突后端）。

也可用「应用开发助手」改草案再发布；手工改包与助手改的是同一套文件约定。

---

2. 路径 A：最小记事本（30 分钟）

2.1 创建壳

在应用桌面用模板创建空白/记事类应用，或复制已有最小应用包。确保已有 app.json、data/app.db、logic/handlers.py（可为桩）。

2.2 写 app.json

要求：

• version: 1
• ≥1 个 entities（字段带 label/type）
• views：一个 form（mode: "create"）+ 一个 list
• 不要自定义 actions（除非你马上做路径 B）

完整字段规则：界面描述规范 §7 记事示例。

2.3 校验心理清单

• 实体名、字段名：小写 + 下划线
• form/list 的 entity 指向真实实体
• 列表 columns 使用已有字段名

2.4 验证

打开应用 → 提交一条 → 列表出现 → 删除（若未关 allow_delete）。 整条链路只走内置 CRUD，handlers 可以不写业务。

---

3. 路径 B：加一个「办事」动作

在路径 A 基础上增加「输入参数 → 脚本 →（可选）附件/历史」。

3.1 改界面描述

1. actions 增加一项：id、label、impl: "script"、params（表单控件来源）。
2. views 增加 action_form，action = 该 id。
3. 若要历史：实体增加 status、upload_id 等字段；list 的 columns 跟上。

注意：动作表单控件 = actions[].params，不是 views[].fields。

3.2 改 logic/handlers.py

实现 handle，分支处理该 action：

• 校验参数
• 需要取数 → ctx["platform"].query_run（或调用你的 generate_*.py）
• 需要报告 → save_upload，返回 upload_id
• 需要历史 → 写 ctx["app_db"]

模板级说明：动作与handlers。

3.3 可选：流水线取数

1. 在数据连接中准备好 query_id。
2. 添加 references/pipeline.json。
3. 添加 logic/generate_*.py 按步执行。
4. 需要版式时加 assets/*.html + scripts/assemble_*.py。

详见：取数与流水线。 对照实现：工作区「员工画像」应用包，或内置模板 backend/internal/skillfromchat/bundled/employee-profile/。

3.4 验证

• 提交动作：成功提示 / 错误文案符合预期
• 有 upload_id：能打开或下载
• 列表状态与备注更新
• 故意写错 query_id：应看到明确错误或 warnings，而不是空白成功

---

4. 「按一张图片做界面」怎么落在手工搭建里？

---

5. 从零检查表（完整 App）

界面

• [ ] 只有 list / form / action_form
• [ ] 每个 action_form 能在 actions 找到 id
• [ ] 动作表单字段写在 params
• [ ] 用户可见文案都在 label

包

• [ ] app.json 合法（可对照平台保存/发布是否报错）
• [ ] 有 script 动作时 handlers.handle 覆盖全部 id
• [ ] 脚本只用平台桥访问外部数据
• [ ] 模板/流水线放在 assets / scripts / references / logic

取数（若需要）

• [ ] 预定义查询与 pipeline 一致
• [ ] 主步骤失败有明确错误；可选步骤进 warnings
• [ ] 返回值含前端约定字段

体验

• [ ] 应用桌面能打开
• [ ] 主路径手工点通一遍
• [ ] （可选）对话技能是否需同步 profile.register 类登记动作

---

6. 文档地图

---

7. 常见卡点