hap-cli-app-editor

HAP App Editor (fine-grained element CRUD)

You make precise local modifications to anexistingHAP app: add, delete, or modify a single element (worksheet / field / view / role permission / custom action / workflow and nodes / custom page and components / app and group). If you need to create, delete, or update business data, follow the hap-cli main Skill and directly call the hap command.

Core model: two entry points, split by risk level

The default entry point is the bare hap command — the vast majority of element edits are just one command:

hap worksheet view update <ws_id> <view_id> --name "进行中的订单"
hap workflow publish <process_id>
hap app role add-member <role_id> --user-ids <account_id> -a <app_id>

Only three types of edits go through edit-spec (hap app-editor）, because their safe way of writing is "read the whole thing → change one place → write the whole thing back", and doing it by hand easily loses data silently:

Edit target	edit-spec op	Why it cannot be done bare
Existing fields' modification/deletion/reordering	field.update / field.delete / field.reorder	The entire table control set must be written back, otherwise system reverse controls will be silently dropped
Page componentsadd/delete/modify	component.add / component.update / component.delete	The page layout is a single components array as a whole, and must be read-modify-written
Action buttonscreate/modify	custom-action.create / custom-action.update	The high-level action_spec is automatically translated into button configuration and the associated process is wired up

(Adding a field field.add is also in edit-spec, using the same writing style as other field ops.) All other elements — worksheets, views, roles, workflows, nodes, pages themselves, apps and groups —use commands directly, and the commands and parameter dictionaries for each module are in the index below.

Prerequisites

1. Login：hap auth whoami Confirm that you are logged in and have selected an organization; if not logged in, have the user first hap auth login。
2. Administrator permission (hard prerequisite): editing app elements requires the current user to have administrative permission for that app. Before starting, use hap app list-managed to confirm the target app is in the list; if it is not,do not force it, and tell the user they need administrator authorization or to log in with a different account.
3. When there is no appId in the context, have the user provide the app name or appId.

General workflow (4 steps)

1. Inspect：hap app-editor inspect <appId或应用名> Print the app's full "logical name → id" structure (worksheets, views, roles, workflows, pages, groups...). All the various ids needed by subsequent commands are obtained from here; for finer-grained ids, use each module's list/info commands.
2. Read(required before changing complex values):First use read commands to export the current state, modify on the real structure, then write back。
   • Views:hap --json worksheet view info <ws_id> <view_id>
   • Nodes:hap --json workflow node get <process_id> <node_id>
   • Fields:hap --json worksheet fields <ws_id> --raw
   • Pages:hap --json custom-page info <page_id>(the parameter is the page id) For keys not covered by the dictionary, go by the actual structure you read — rewriting according to the shape is always safe.
3. Edit: Execute the command according to the module documentation's invocation pattern; or for the three types of edit-spec edits: write the spec → hap app-editor validate <spec.json>(purely local) → plan(dry-run rehearsal) → apply。
4. Verify: use the corresponding read command to confirm the change took effect.

🚨 Six pitfalls of "returns success but actually didn't do it right"

HAP's write interfaces are full of cases where "it still returns success, but the data is wrong", so step 4 Verify is not optional:

1. update-fields is a full-table replacement—columns not passed in are deleted along with their data; entries without id are treated as new columns and rebuilt. To add columns to an existing table, always use add-fields or field.add. Before saving, first --check, and after saving, check the automatic read-back report.
2. Self-invented controlId will create a blank column whose value can never be read in the table or in related controls. Always omit it when creating a new field.
3. Passing a nonexistent value for an option/regionwill not report an error; it will write an invalid value, and the interface will display it as blank (see hap guide record）。
4. --view-id Withdraw action buttonis only effective for buttons that "have a specified display view"; all-view buttons will explicitly report an error and will not pretend to be withdrawn.
5. Creating a workflow does not mean it is set up correctly—the trigger is not bound,fill_in has no editable fields, and only workflow publish will tell you. After adding nodes, send it once as a quick check.
6. Copy worksheetwhen related/subtable/cascade columns not named by --keep-relation become plain text, with no prompt at all.

Value form conventions (when reading dictionary tables)

The "value form" column of each module's dictionary table has three tiers:

• Scalar/enum: possible values are written directly in the cell, e.g. "1"=显示 "2"=隐藏；
• Simple structure: one-line description, e.g. controlId 的 JSON 数组；
• Complex structure: links to the type definition under scripts/types/ (schema + examples that can be applied directly); each structure is defined only once in the whole skill:

Type	Where used
FilterCondition	View filters, business rules, button enableWhen, chart filters, page filter components' storage form (what you see when reading back); when writing, prefer the unified filter syntax {logic, items:[{field, op, value}]}, see hap guide record filter
SortItem	View multi-sort, workflow node sorts
WireControl	Field's raw control object (universal currency for read/write)
OperateCondition	Workflow node/branch conditions (not FilterCondition, the field name is filedId）
WorkflowAccounts	Workflow recipients (type semantics are counterintuitive, must-read)
WorkflowFieldWrite	Data node field writing ($nodeId-fieldId$ dynamic template)

A typical HAP worksheet view page URL:/app/<app_id>/<section_id>/<worksheet_id>/<view_id>. A typical HAP worksheet row record page URL:/app/<app_id>/<worksheet_id>/<view_id>/row/<rowid>。

Module documentation index

By the element to operate onread only the corresponding one(each = invocation paradigm + data dictionary):

• references/worksheets-and-fields.md — worksheets, fields (including field edit-spec syntax)
• references/views.md — views (full dictionary of editAttrs / advancedSetting)
• references/roles.md — roles, permissions, members
• references/workflows.md — automated workflows and node basics
• references/nodes.md — in-depth node configuration dictionary (8 high-frequency node types)
• references/custom-actions.md — action buttons (action_spec / wire two syntaxes)
• references/custom-pages.md — custom pages and components (including component edit-spec syntax)
• references/application.md — the app itself and navigation grouping
• references/charts.md — statistics charts (modify existing charts; for the spec proper see hap guide chart）
• references/edit-spec.md — the edit-spec envelope and the complete semantics of the three op types

Multi-element interaction scenarios(one target requires chaining multiple commands) see references/scenarios/, one document per scenario, containing the command order and id passing. Ready-to-use examples of the three edit-spec types are in examples/(one each per field / component / custom-action).

Boundaries and discipline

• Only modify the elements the user explicitly requested.
• Destructive operations: the delete-type ops of edit-spec must carry "confirm": true; the delete type of bare commands must always carry --yes/-y for a second confirmation; if -y is not passed, it will ask interactively (and abort directly in a non-interactive environment).-y only skips the prompt; it does not equal authorization — obtain the user's explicit consent before any deletion. After deleting, use hap app trash -a <appId> to verify: worksheets / custom pages / AI assistant all go to the app recycle bin by default, and only seeing it in the recycle bin means the deletion succeeded.
• Do not guess parameters: the dictionary + the current state exported by read commands is the only basis; when the two conflict, the read one prevails.
• hap-cli upgrades automatically, and commands and options will change. The dictionary of this skill is verified against 0.9.0 and is only an accelerator, not authoritative: before acting, use hap <命令> --help to verify the exact parameters, and use hap guide worksheet / hap guide workflow / hap guide chart / hap guide record to verify value shapes and pitfalls — they follow the version installed on this machine and will never go stale. When they conflict with this skill, they prevail.
• Generating an entire app from scratch is not part of this skill — use hap-mcp-app-builder.