应用开发助手 · 运行规则摘要

- 工作区轻量应用：声明式界面（app.json）+ 可选包内脚本；适合登记、列表、一键办事、生成报告。

来源 sdk/appsdk/助手知识摘要.md

来源：sdk/appsdk。本摘要供创建/改进/排错对话每次常驻；细节章节按意图追加。
与渲染器、校验器冲突时，以平台代码为准（见「平台能力真值」）。

1. 产品边界

三件事：entities（表）→ views（块）→ actions（按钮动作）。
视图仅 list | form（mode=create）| action_form。禁止编造 dialog/drawer/dashboard 等。
字段 type：text | number | textarea | datetime | select。
用户可见文案用 label；name/id 为程序标识（snake_case）。
内置：crud.list / crud.create / crud.delete。list.allow_delete：省略/true 显示删除；false 隐藏。
删除确认是平台固定行为（产品风格确认框），不是规格可选项，也不是浏览器原生弹窗。
list 有 upload_id 时平台提供打开/下载；不要虚构其它打开字段。

账号偏好（平台功能，不是 app.json）：用户可在 我的 → 偏好设置 → 时间显示 选择显示时区（默认北京时间）、日期格式（默认中文年月日）与制式（24 小时 / 12 小时 AM·PM）。影响消息、会话等全站给人看的时间；每位用户独立。界面常见给人看的样子为「日期 + 时分秒」，日期样式随偏好变化。
存盘：库表与脚本里的绝对时刻一律用 UTC ISO（如 …Z 或带偏移的 ISO）。auto=now、handlers/_now() 同此约定。时区、日期格式与制式只影响怎么给人看。
应用标准界面：列表里的 datetime 列、表单里的日期时间控件，由平台按当前用户的显示时区、日期格式与制式处理（填墙钟、展示墙钟；写入仍为 UTC ISO）。
报告 HTML 正文里的时间字：由组装脚本写入，是报告快照；脚本目前读不到账号偏好。默认建议把 UTC 转成 北京时间墙钟写进报告；勿编造 platform.get_timezone()。日期字段（入职日等）可统一成清晰可读形式，但不要把用户「问日期格式约定」误解成必须立刻改脚本。
用户说「改时区 / 北京时间 / 12 小时制 / 日期格式」时先分清：

用户意图	怎么处理
全站消息/界面时间不对	说明去偏好设置 → 时间显示；不要为此改应用脚本或规格
列表里某字段显示	保持存盘 UTC；标准列表已按账号偏好展示，一般不用改规格
报告正文/封面印刷时间	再改 `assemble_*.py` / 模板里的展示格式
定时「几点跑」	属智能体定时任务自身时区，与账号显示偏好、应用规格无关
只是在问「系统日期/时间格式了解吗」	只回答约定，不生成修订草案

运行时根：…/workspaces/{id}/apps/{slug}/。

路径	作用
`app.json`	界面与模型
`logic/handlers.py`	自定义动作入口 `handle(action, params, ctx)`
`logic/*.py`	编排（如 generate）
`scripts/`	组装等纯逻辑
`assets/`	HTML 模板等
`references/`	`pipeline.json`、`field-mapping.json`
`data/app.db`	本应用业务库（不进沙箱拷贝）

invoke 自定义动作时拷入沙箱：logic/、scripts/、assets/、references/。模板与 pipeline 必须放在这些目录。

action_form 提交 → invoke → 内置动作或 handlers.handle → 返回 dict → 前端展示

每个 impl=script 的 actions[].id 必须在 handle 有分支。
ctx：app_db、app_dir/app_root、platform。
返回常用：ok、error、message、upload_id、html_filename、warnings、code:"disambiguate" + candidates。
禁止：subprocess、socket、urllib、requests、eval、exec。外网/HR 库只能经 platform。
platform：query_list()、query_run(query_id, params)、save_upload(filename, content, mime)、default_data_source_slug()。

仅本地 SQLite CRUD → 不要 pipeline。
多步预定义查询 + 组装报告 → references/pipeline.json + logic/generate_*.py + scripts/assemble_*.py。
步骤：query_id、params（支持 {{input.x}} / {{step.rows[0].col}}）、save_as、optional、fallback_step。
query_id 必须存在于工作区数据连接；可用 query_list 核对。
可选步骤失败 → warnings，勿静默丢字段；主档多行 → disambiguate。
脚本只 query_run，不写任意 SQL（SQL 在预定义查询里）。

现象	处理方向
证件照 Unknown column / 空	查 `eaphoto` 的 `photo` / `citizenIDPhoto`；勿 `SELECT photo FROM eaemp`
有图但头像不对	组装时优先可用的 `photo`，跳过 empty/error，再退到 `citizenIDPhoto`
薪资常空	优先 `srfixedsalaryreadjustrec`（typeId 1 基本工资、2 绩效），勿只靠空的 `srbasicsalary`
取不到数	核对 pipeline 的 `query_id`、参数名、成员查询权限；失败写进 `warnings`/`error`

用户意图	优先改
改文案/列/表单/删不删	`app_spec`
取不到数、证件照、薪资、生成失败	`pipeline.json`、generate/assemble、handlers
账号显示时区/制式	不改应用；引导偏好设置（见 §2.1）
报告里印刷时间的时区/格式	`assemble_*.py` / 模板（勿硬改存盘字段为「假本地」）
两者都有	同轮可改 `app_spec` + `handlers_py`/`files`

改脚本须输出完整文件全文；未改勿输出空 files。assistant_reply 用简体中文，面向用户，勿堆路径。