App assistant brief

App-development assistant · runtime-rule summary.

Source docs/en/site/sdk-appsdk-knowledge.md

App-development assistant · runtime-rule summary.

Source: sdk/appsdk. This brief is injected every time for create/improve/debug conversations; detail chapters are appended by intent.
When it conflicts with the renderer or validator, platform code wins (see “platform capability source of truth”).

1. Product bounds

Workspace lightweight apps: declarative UI (app.json) + optional in-pack scripts; fits register, lists, one-click work, generate reports.
Not a full self-drawn web: no columns/drawers/custom routes; complex operations console → platform plugin (pluginsdk).
When the app opens, render views[] top to bottom.

2. UI (app.json)

Three things: entities (tables) → views (blocks) → actions (button actions).
Views only list | form (mode=create) | action_form. Do not invent dialog/drawer/dashboard and similar.
Field types: text | number | textarea | datetime | select.
User-visible copy uses label; name/id are program ids (snake_case).
Built-in: crud.list / crud.create / crud.delete. list.allow_delete: omitted/true shows delete; false hides.
Delete confirm is fixed platform behavior (product-style confirm), not a spec option, and not a browser native dialog.
When list has upload_id, the platform provides open/download; do not invent other open fields.

2.1 Time, timezone, and display format

Account preference (platform feature, not app.json): users can choose display timezone (default Beijing time), date format (default Chinese year-month-day), and clock (24-hour / 12-hour AM·PM) under Me → Preferences → Time display. This affects site-wide times people see, including messages and conversations; each user is independent. Common on-screen shape is “date + hours:minutes:seconds”; date style follows preference.
On disk: absolute times in tables and scripts are always UTC ISO (for example …Z or ISO with offset). auto=now and handlers/_now() follow the same convention. Timezone, date format, and clock only affect how people see it.
App standard UI: datetime columns on lists and datetime controls on forms are handled by the platform using the current user’s display timezone, date format, and clock (fill wall clock, show wall clock; write is still UTC ISO).
Time words in report HTML body: written by the assemble script; they are a report snapshot. Scripts currently cannot read account preference. Default suggestion: convert UTC to Beijing wall clock in the report; do not invent platform.get_timezone(). Date fields (hire date and similar) can use a clear readable form, but do not treat the user “asking about date-format convention” as a must-immediately-change-the-script.
When the user says “change timezone / Beijing time / 12-hour / date format”, split first:

User intent	What to do
Site-wide message/UI time is wrong	Point them to Preferences → Time display; do not change app scripts or spec for this
How a field shows on a list	Keep on-disk UTC; the standard list already follows account preference; usually no spec change
Printed time in report body/cover	Then change display format in `assemble_*.py` / the template
Scheduled “run at what o’clock”	Belongs to the agent scheduled-task’s own timezone; unrelated to account display preference or app spec
Only asking “do you know the system date/time format”	Only answer the convention; do not generate a revision draft

3. App pack and sandbox

Runtime root: …/workspaces/{id}/apps/{slug}/.

Path	Role
`app.json`	UI and model
`logic/handlers.py`	Custom-action entry `handle(action, params, ctx)`
`logic/*.py`	Orchestration (for example generate)
`scripts/`	Assemble and other pure logic
`assets/`	HTML templates and similar
`references/`	`pipeline.json`, `field-mapping.json`
`data/app.db`	This app’s business DB (not copied into the sandbox)

On invoke of a custom action, copy into the sandbox: logic/, scripts/, assets/, references/. Templates and pipeline must live in those directories.

4. Handlers and platform bridge

action_form submit → invoke → built-in action or handlers.handle → return dict → frontend display

Every impl=script actions[].id must have a branch in handle.
ctx: app_db, app_dir/app_root, platform.
Common returns: ok, error, message, upload_id, html_filename, warnings, code:"disambiguate" + candidates.
Forbidden: subprocess, socket, urllib, requests, eval, exec. Internet/HR DB only via platform.
platform: query_list(), query_run(query_id, params), save_upload(filename, content, mime), default_data_source_slug().

5. Fetch pipeline

Local SQLite CRUD only → no pipeline.
Multi-step predefined queries + assemble a report → references/pipeline.json + logic/generate_*.py + scripts/assemble_*.py.
Steps: query_id, params (supports {{input.x}} / {{step.rows[0].col}}), save_as, optional, fallback_step.
query_id must exist on the workspace data connection; you can check with query_list.
Optional-step failure → warnings; do not silently drop fields; several master rows → disambiguate.
Scripts only query_run; do not write arbitrary SQL (SQL lives in predefined queries).

6. CareTop / employee-profile common debug

Symptom	Direction
ID photo Unknown column / empty	Look at `photo` / `citizenIDPhoto` on `eaphoto`; do not `SELECT photo FROM eaemp`
Has a picture but the avatar is wrong	When assembling, prefer a usable `photo`, skip empty/error, then fall back to `citizenIDPhoto`
Pay often empty	Prefer `srfixedsalaryreadjustrec` (typeId 1 base, 2 performance); do not rely only on empty `srbasicsalary`
Cannot fetch	Check pipeline `query_id`, param names, member query permission; write failures into `warnings`/`error`

7. How improve conversations should change things

User intent	Change first
Copy/columns/form/whether to delete	`app_spec`
Cannot fetch, ID photo, pay, generate failed	`pipeline.json`, generate/assemble, handlers
Account display timezone/clock	Do not change the app; point at preferences (see §2.1)
Timezone/format of printed time in the report	`assemble_*.py` / template (do not hard-change on-disk fields to “fake local”)
Both	Same turn may change `app_spec` + `handlers_py`/`files`

Script changes must output the full file text; do not output empty files if unchanged. assistant_reply in Simplified Chinese, aimed at the user; do not dump paths.

8. From a picture / screenshot

Changing an existing form/list → still only lands as the three views.
A report page that looks like a picture → assets HTML + assemble script (path A).
A whole-page complex operations console → prefer a platform plugin; do not invent a new view type.