hap-cli 0.8.23__tar.gz → 0.8.24__tar.gz

{hap_cli-0.8.23 → hap_cli-0.8.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.8.23
+Version: 0.8.24
 Summary: CLI harness for Mingdao HAP - Enterprise no-code platform
 Author: hap-cli
 License: Apache-2.0

{hap_cli-0.8.23 → hap_cli-0.8.24}/hap_cli/__init__.py

@@ -1,3 +1,3 @@
 """CLI harness for Mingdao HAP (hap-cli)."""
 
-__version__ = "0.8.23"
+__version__ = "0.8.24"

{hap_cli-0.8.23 → hap_cli-0.8.24}/hap_cli/commands/record_cmd.py

@@ -84,8 +84,12 @@ def record_get(ctx, worksheet_id, row_id, view_id):
                    "list of option names or keys; member/relation fields a "
                    "list of ids). Use either this or -f, not both.")
 @click.option("--no-workflow", is_flag=True, help="Don't trigger workflows")
+@click.option(
+    "--app-id", "-a", default="",
+    help="Application ID. Optional — the worksheet id is enough on its own; this only scopes the field lookup.",
+)
 @pass_context
-def record_create(ctx, worksheet_id, field, fields_json, no_workflow):
+def record_create(ctx, worksheet_id, field, fields_json, no_workflow, app_id):
     """Create a new record.
 
     Pass values either as repeated -f CONTROL_ID=VALUE pairs or as one
@@ -112,10 +116,11 @@ def record_create(ctx, worksheet_id, field, fields_json, no_workflow):
                 raise click.UsageError(str(exc))
         else:
             raw = _parse_fields(field)
-        controls = rec_mod.encode_controls_by_id(session, worksheet_id, raw)
+        controls = rec_mod.encode_controls_by_id(
+            session, worksheet_id, raw, app_id=app_id)
         data = rec_mod.create_record(
             session, worksheet_id, controls,
-            trigger_workflow=not no_workflow,
+            trigger_workflow=not no_workflow, app_id=app_id,
         )
         ctx.output(data, lambda d: click.echo(f"Created: {d}"))
     except Exception as e:
@@ -153,8 +158,12 @@ def _fields_json_to_raw(fields_json):
                    "list of option names or keys; member/relation fields a "
                    "list of ids). Use either this or -f, not both.")
 @click.option("--no-workflow", is_flag=True, help="Don't trigger workflows")
+@click.option(
+    "--app-id", "-a", default="",
+    help="Application ID. Optional — the worksheet id is enough on its own; this only scopes the field lookup.",
+)
 @pass_context
-def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow):
+def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow, app_id):
     """Update a record.
 
     Pass values either as repeated -f CONTROL_ID=VALUE pairs or as one
@@ -180,10 +189,10 @@ def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow):
         else:
             raw = _parse_fields(field)
         controls = rec_mod.encode_controls_by_id(
-            session, worksheet_id, raw, for_update=True)
+            session, worksheet_id, raw, for_update=True, app_id=app_id)
         data = rec_mod.update_record(
             session, worksheet_id, row_id, controls,
-            trigger_workflow=not no_workflow,
+            trigger_workflow=not no_workflow, app_id=app_id,
         )
         ctx.output(data, lambda d: click.echo(f"Updated: {d}"))
     except Exception as e:

{hap_cli-0.8.23 → hap_cli-0.8.24}/hap_cli/core/record.py

@@ -29,12 +29,36 @@ def _option_field_label(ctrl: dict[str, Any]) -> str:
     return str(ctrl.get("controlName") or ctrl.get("controlId") or "option field")
 
 
+# The colour pd-openweb stamps on an option created this way
+# (src/components/Form/core/utils.js:224).
+_NEW_OPTION_COLOR = "#1677ff"
+_NEW_OPTION_PREFIX = "add_"
+
+
+def _new_option_payload(text: str) -> str:
+    """Wire form of "create this option and select it".
+
+    ``add_<text>`` is the form's own marker, never a wire value: pd-openweb
+    rewrites it in ``formatControlToServer`` (cases 10/11) into a JSON
+    string ``{"color", "value"}``, and that is what the server reads as a
+    new option. Passing the marker through untranslated is what used to
+    store ``{"key": "add_<text>", "value": null}`` — a blank cell, and no
+    option added to the field.
+
+    The frontend rewrites on ``indexOf('add_') > -1``; a prefix test is
+    used here so a genuine label containing ``add_`` still resolves to its
+    own key.
+    """
+    return json.dumps({"color": _NEW_OPTION_COLOR, "value": text},
+                      ensure_ascii=False)
+
+
 def _reject_relation_shaped_option(ctrl: dict[str, Any], item: Any) -> None:
     """Fail loudly when a select cell is handed a relation/member/sub-table
     *object* shape instead of an option value.
 
     A single/multi-select cell legitimately carries only an option key, a
-    known label, or an ``add_<text>`` new-option directive — never a
+    known label, or an ``add_<text>`` marker for a new option — never a
     ``[{"sid": rowId}]`` / ``{...}`` structure. When such a value slips
     through (e.g. row data maps a relation value to the wrong child field),
     the old code passed it straight to the server, which then failed
@@ -53,8 +77,9 @@ def _reject_relation_shaped_option(ctrl: dict[str, Any], item: Any) -> None:
     if looks_object:
         raise ValueError(
             f"Field '{_option_field_label(ctrl)}' is a select field and "
-            f"expects an option key, a label, or an 'add_<text>' new-option "
-            f"value, but got a relation/object-shaped value: {item!r}. "
+            f"expects an option key, an exact option label, or "
+            f"'add_<text>' to create a new option, but got a "
+            f"relation/object-shaped value: {item!r}. "
             f"This value belongs to a relation or member field, not this "
             f"select field — check the field mapping."
         )
@@ -86,8 +111,15 @@ def _resolve_option_keys(ctrl: dict[str, Any], raw: Any) -> list[str]:
             by_label[str(opt.get("value", ""))] = key
     out: list[str] = []
     for it in items:
-        _reject_relation_shaped_option(ctrl, it)
         s = str(it)
+        # A known label wins over the marker, so an option literally named
+        # "add_something" still resolves to its own key.
+        if (isinstance(it, str) and s not in valid_keys and s not in by_label
+                and s.startswith(_NEW_OPTION_PREFIX)
+                and len(s) > len(_NEW_OPTION_PREFIX)):
+            out.append(_new_option_payload(s[len(_NEW_OPTION_PREFIX):]))
+            continue
+        _reject_relation_shaped_option(ctrl, it)
         out.append(s if s in valid_keys else by_label.get(s, s))
     return out
 
@@ -387,7 +419,7 @@ def _legacy_cell_value(ctrl: dict[str, Any], value: Any) -> str:
 
 
 def _controls_for_write(
-    session: Session, worksheet_id: str,
+    session: Session, worksheet_id: str, app_id: str = "",
 ) -> list[dict[str, Any]]:
     """Fetch the worksheet's controls for a write, refusing an empty list.
 
@@ -406,7 +438,8 @@ def _controls_for_write(
     always has controls, so an empty list means "we could not read the
     fields", never "this worksheet has none". Abort before writing.
     """
-    controls = ws_mod.get_worksheet_controls(session, worksheet_id)
+    controls = ws_mod.get_worksheet_controls(
+        session, worksheet_id, app_id=app_id)
     if not controls:
         logger.warning(
             "GetWorksheetControls returned no fields for worksheet %s; "
@@ -427,6 +460,7 @@ def encode_controls_by_id(
     raw_controls: list[dict[str, Any]],
     *,
     for_update: bool = False,
+    app_id: str = "",
 ) -> list[dict[str, Any]]:
     """Type-encode ``-f CONTROL_ID=VALUE`` cells for create/update.
 
@@ -457,7 +491,7 @@ def encode_controls_by_id(
     (in-place edits keyed by ``rowid``, fresh adds, and deletes — see
     :func:`_sublist_update_value`).
     """
-    controls = _controls_for_write(session, worksheet_id)
+    controls = _controls_for_write(session, worksheet_id, app_id)
     by_id: dict[str, dict[str, Any]] = {
         c.get("controlId"): c for c in controls if c.get("controlId")
     }
@@ -860,32 +894,68 @@ def _reject_workflow_suppression(trigger_workflow: bool) -> None:
     )
 
 
+def _raise_on_failed_write(result: Any, action: str) -> Any:
+    """Turn a rejected write into an error instead of a printed success.
+
+    ``AddWorksheetRow`` / ``UpdateWorksheetRow`` answer HTTP 200 with a
+    ``resultCode`` that says whether the row was actually saved: 1 means
+    saved, anything else means it was not. Nothing used to look at it, so
+    a validation failure — most often a missing required field, which
+    comes back as ``{"resultCode": 31, "badData": [<control ids>]}`` and
+    stores nothing — was printed as ``Created: {...}`` and exited 0.
+
+    Responses with no ``resultCode`` are left alone: not every endpoint
+    carries one, and absence is not failure.
+    """
+    if not isinstance(result, dict) or "resultCode" not in result:
+        return result
+    code = result.get("resultCode")
+    if code == 1:
+        return result
+    bad = result.get("badData")
+    detail = (f" It rejected these fields: {', '.join(map(str, bad))}."
+              if bad else " Check the record still exists and that each value "
+                          "matches its field type.")
+    raise APIError(
+        f"The record was not saved — the server refused the {action} "
+        f"(resultCode {code}).{detail}",
+        code=code if isinstance(code, int) else None,
+    )
+
+
 def create_record(
     session: Session,
     worksheet_id: str,
     controls: list[dict[str, Any]],
     trigger_workflow: bool = True,
+    app_id: str = "",
 ) -> dict[str, Any]:
     """Create a new record.
 
+    ``worksheet_id`` identifies the worksheet on its own — a write does not
+    depend on which app is currently selected (verified against a worksheet
+    while an unrelated app was the default). ``app_id`` is optional and is
+    forwarded as ``appId``, which this endpoint's schema carries.
+
     Args:
         session: Active session
         worksheet_id: Worksheet ID
         controls: List of {controlId, value} dicts
         trigger_workflow: Whether to trigger workflows
+        app_id: Optional application ID
 
     Returns:
         Created record info
     """
     _reject_workflow_suppression(trigger_workflow)
-    return session.api_call(
-        "Worksheet",
-        "AddWorksheetRow",
-        {
-            "worksheetId": worksheet_id,
-            "receiveControls": controls,
-        },
-    )
+    data: dict[str, Any] = {
+        "worksheetId": worksheet_id,
+        "receiveControls": controls,
+    }
+    if app_id:
+        data["appId"] = app_id
+    return _raise_on_failed_write(
+        session.api_call("Worksheet", "AddWorksheetRow", data), "create")
 
 
 def update_record(
@@ -894,28 +964,38 @@ def update_record(
     row_id: str,
     controls: list[dict[str, Any]],
     trigger_workflow: bool = True,
+    app_id: str = "",
 ) -> dict[str, Any]:
     """Update an existing record.
 
+    ``app_id`` is accepted for a consistent command surface and is used to
+    scope the field-metadata lookup, but it is NOT sent: unlike
+    AddWorksheetRow, UpdateWorksheetRow's schema has no ``appId``, and
+    inventing one would diverge from the frontend.
+
     Args:
         session: Active session
         worksheet_id: Worksheet ID
         row_id: Record/row ID
         controls: List of {controlId, value} dicts
         trigger_workflow: Whether to trigger workflows
+        app_id: Optional application ID (metadata scope only)
 
     Returns:
         Update result
     """
     _reject_workflow_suppression(trigger_workflow)
-    return session.api_call(
-        "Worksheet",
-        "UpdateWorksheetRow",
-        {
-            "worksheetId": worksheet_id,
-            "rowId": row_id,
-            "newOldControl": controls,
-        },
+    return _raise_on_failed_write(
+        session.api_call(
+            "Worksheet",
+            "UpdateWorksheetRow",
+            {
+                "worksheetId": worksheet_id,
+                "rowId": row_id,
+                "newOldControl": controls,
+            },
+        ),
+        "update",
     )
 
 

{hap_cli-0.8.23 → hap_cli-0.8.24}/hap_cli/guide/en/overview.md

@@ -35,8 +35,9 @@ generated live rather than copied. Expand any of them with `hap <command> --help
 - `--json` and `--profile` are **global options and go between `hap` and the
   subcommand**: `hap --json chat list` ✅, `hap chat list --json` ❌ ("No such option").
 - To see a worksheet's fields use `hap worksheet fields WS_ID` — not get / structure.
-- `record create/update/delete` **do not accept `--app-id`**; they use the default app.
-  Set it once with `hap app select <appId>` before writing.
+- Writing records **does not depend on the selected app** — a `worksheetId` locates the
+  worksheet on its own and `-a/--app-id` is optional. A failing write is never "I forgot
+  to select the app".
 - Field value shapes differ a lot and **a wrong one still reports success** —
   read `hap guide record` before writing.
 - Before touching workflow nodes run `hap workflow structure PROCESS_ID` and use the

{hap_cli-0.8.23 → hap_cli-0.8.24}/hap_cli/guide/en/record.md

@@ -34,8 +34,11 @@ hap worksheet record create <WS_ID> --fields-json '[{"id":"<field>","value":...}
 They **cannot be mixed**. With `-f`, multiple values (multi-select, several members or
 relations) are comma-separated.
 
-> `record create/update/delete` **do not accept `-a/--app-id`**. Run
-> `hap app select <APP_ID>` first.
+> **About `-a/--app-id`**: `create` / `update` / `delete` all accept it, but none of
+> them *needs* it — a `worksheetId` identifies the worksheet on its own. Verified by
+> setting an entirely unrelated app as the default: all three writes still succeeded.
+> So a failing write is never "I forgot to select the app". Passing it is harmless: it
+> scopes the field-metadata lookup, and create forwards it as `appId`.
 
 ### 1.3 Update replaces; only sub-tables merge
 
@@ -72,7 +75,38 @@ The `_id` alongside it (24 hex chars) is a different internal id. **Passing it t
 `record get` reports that the row does not exist or is not permitted**, and it can
 never be used in a relation field.
 
-## 2. By field type
+### 1.7 "Created" does not mean it worked — check `resultCode`
+
+The server uses `resultCode` to say whether the row was actually saved: **only 1 is
+success.**
+
+```
+Created: {'resultCode': 1, 'data': {...'rowid': '...'}}   <- saved; the rowid is in data
+```
+
+Anything else means nothing was written, and the CLI raises it as an error and exits
+non-zero:
+
+```
+Error: The record was not saved — the server refused the update (resultCode 4).
+```
+
+When the reply carries `badData`, it names the field ids that were rejected.
+
+> Note: **"required" is a form-level constraint and the API does not necessarily
+> enforce it.** Omitting a `required: true` field still came back as `resultCode: 1`
+> with the row saved. Do not rely on the API to catch a missing required value — look
+> them up yourself:
+>
+> ```bash
+> hap --json worksheet fields <WS_ID> | python3 -c "
+> import json,sys
+> for f in json.load(sys.stdin):
+>     if f.get('required'): print(f['id'], f['name'], f['type'])
+> "
+> ```
+
+## 2. By field type## 2. By field type
 
 ### Text and numbers
 
@@ -130,9 +164,26 @@ hap --json worksheet fields <WS_ID>      # options[].key on that field
 >   (`-f "<field>=high,priority"` splits into two invalid values)
 > - the option simply does not exist
 >
-> Keys have none of these problems. To add an option, change the field definition
-> first (see `hap guide skills`); the CLI does **not** support `add_<text>` to create
-> options on the fly.
+> Keys have none of these problems.
+
+**Creating an option as you write**
+
+When the option does not exist yet, prefix it with `add_` and the server mints it and
+selects it:
+
+```bash
+hap worksheet record create <WS_ID> -f "<select field>=add_Urgent"
+```
+
+Verified: the field went from `[Pending, Done]` to `[Pending, Done, Urgent]`, and the
+record holds the freshly minted key. Multi-selects and dropdowns behave the same, and it
+mixes with existing values: `-f "<field>=Pending,add_Urgent"`.
+
+> Only a leading `add_` is treated as the marker — an option genuinely named
+> `add_something` still resolves to its own key rather than creating a duplicate.
+>
+> To change the field definition itself (reorder options, set colours, delete one), use
+> the app-editor skill from `hap guide skills`.
 
 ### Members, departments, org roles
 
@@ -233,18 +284,127 @@ field's `dataSource`, linked back through the reverse relation field (`sourceFie
 
 | Type | typeId | Pass |
 | --- | --- | --- |
-| `Attachment` | 14 | a fixed envelope, as a JSON string |
+| `Attachment` | 14 | a fixed envelope, as a **JSON string** |
+
+This is the only accepted shape, and it works with both `-f` and `--fields-json`:
+
+```json
+{"attachmentData":[],"attachments":[<descriptor from hap upload>, ...],"knowledgeAtts":[]}
+```
+
+**The whole flow (creating a record with attachments)**
 
 ```bash
-# 1) upload and keep the descriptor
-hap --json upload ./demo.txt --worksheet-id <WS_ID> -a <APP_ID>
+hap app select <APP_ID>
+
+# 1) Upload. Several files at once is fine; it returns an array of
+#    descriptors. Passing --worksheet-id / -a is recommended (see below).
+hap --json upload ./a.txt ./b.pdf --worksheet-id <WS_ID> -a <APP_ID> > up.json
 
-# 2) put the descriptor into the attachments array as-is
---fields-json '[{"id":"<attachment field>","value":"{\"attachmentData\":[],\"attachments\":[<descriptor>],\"knowledgeAtts\":[]}"}]'
+# 2) Put the whole array in attachments, wrap the envelope, serialize it
+python3 -c "
+import json
+env={'attachmentData':[],'attachments':json.load(open('up.json')),'knowledgeAtts':[]}
+print(json.dumps([{'id':'<attachment field id>','value':json.dumps(env,ensure_ascii=False)}],ensure_ascii=False))
+" > cell.json
+
+# 3) Write
+hap worksheet record create <WS_ID> --fields-json "$(cat cell.json)"
+```
+
+> **The two detours everyone takes, both answered with an unexplained
+> server error:**
+>
+> - passing the array `hap upload` returned **directly** (no envelope)
+> - passing just the file's `url` string
+>
+> It must be the full `attachmentData` / `attachments` / `knowledgeAtts`
+> envelope, **serialized to a string as a whole**.
+
+> **Do not hand-write that envelope in a shell.** Nested quotes plus escaping is
+> almost guaranteed to go wrong. Generate it with Python into a file and pass
+> `--fields-json "$(cat cell.json)"`, as above.
+
+**What `--worksheet-id` / `-a` change**
+
+They decide where the file lands in the store:
+
+| | `filePath` |
+| --- | --- |
+| without | `pic/20260902/`, `doc/20260902/` (a shared directory per file type) |
+| with | `<orgId>/<appId>/<worksheetId>/20260902/` (filed under org / app / worksheet) |
+
+**Pass them** — it is what the web UI does and it keeps files attributable. Writes also
+succeed without them (verified for `.txt` and `.png`: written, read back, downloaded
+intact), so they are not the first thing to suspect when a write fails.
+
+**The `file_id` changes once the record is saved**
+
+The `fileID` you get from the upload is a client-generated temporary id starting with
+`o_`. Once the record is saved the server assigns a GUID, and that is what you read
+back. **This is normal, not a sign the write went wrong.**
+
+**Clearing an attachment field** (it does not follow the general rule)
+
+| Pass | Result |
+| --- | --- |
+| `""`, or `-f "<field>="` | clears it |
+| the empty envelope `{"attachmentData":[],"attachments":[],"knowledgeAtts":[]}` | clears it |
+| `[]` | rejected: attachment save failed, bad parameter |
+| `null` | same rejection |
+
+`[]` and `null` clear other field types. **They do not clear attachments.**
+
+**Update replaces, and there is no append switch**
+
+New attachments drop whatever was there. The envelope's `attachmentData` **cannot** be
+used to keep the existing ones: feeding it the `record get` read-back, and separately a
+camelCase object carrying the stored `fileID`, both dropped the old file. (The CLI
+passes attachment JSON through untouched, so this is the server's behaviour.)
+
+**To append, build the full list yourself — but do not re-upload.** The bytes are
+already in the store and a descriptor is only metadata pointing at them, so it can be
+rebuilt from what you read back:
+
+| Key from `record get` | Rebuilds which descriptor field |
+| --- | --- |
+| `file_path` (`https://host/doc/20260902/`) | `serverName` (`https://host/`) + `filePath` (`doc/20260902/`) |
+| `file_name` (`xxxx.txt`) | `fileName` (`xxxx`) + `fileExt` (`.txt`) |
+| `original_file_name` (`att1.txt`) | `originalFileName` (`att1`) |
+| `file_size` | `fileSize` |
+| `filePath` + `file_name` | `key` |
+| — | `fileID`: any fresh client-side id will do |
+
+```python
+import json, os
+def rebuild(a):
+    """Turn one record-get read-back entry into a writable descriptor."""
+    scheme, rest = a["file_path"].split("//", 1)
+    host, _, path = rest.partition("/")
+    stem, ext = os.path.splitext(a["file_name"])
+    orig, _ = os.path.splitext(a["original_file_name"])
+    return {"fileID": "o_" + os.urandom(8).hex(), "fileSize": a["file_size"],
+            "serverName": f"{scheme}//{host}/", "filePath": path,
+            "fileName": stem, "fileExt": ext,
+            "originalFileName": orig, "key": path + a["file_name"]}
+
+old = [rebuild(a) for a in record_get_result["<attachment field id>"]]
+new = json.load(open("up.json"))
+env = {"attachmentData": [], "attachments": old + new, "knowledgeAtts": []}
 ```
 
-> **Passing the array `hap upload` returns fails** with a parameter error. The
-> `attachmentData` / `attachments` / `knowledgeAtts` envelope is required.
+Both the rebuilt and the newly uploaded files download correctly afterwards.
+
+**Three read shapes, none of them the write shape**
+
+| Read from | Shape | Keys |
+| --- | --- | --- |
+| `record get` | array | snake_case: `file_id` / `file_name` / `file_path` / `file_size` / `original_file_name` / `preview_url` … |
+| `record list` | array | only `fileName` + `downloadUrl` |
+| the return of `record create/update` | **a JSON string** | camelCase: `fileID` / `originalFilename` / `ext` / `filesize` / `viewUrl` / `downloadUrl` |
+
+So **you cannot write back what you read**. Either keep the descriptors `hap upload`
+gave you — they stay reusable — or rebuild them per the table above.
 
 ## 3. Filtering records
 
@@ -278,12 +438,18 @@ and pivots see `hap guide skills`.
 Every one of these returns success while storing something wrong, or nothing:
 
 1. **Misspelled field identifier** → the value is ignored.
-2. **Display text instead of an option key, not matching exactly** → stored as an invalid key, blank in the UI.
+2. **Display text instead of an option key, not matching exactly** → stored as an
+   invalid key, blank in the UI. To add an option deliberately, use the `add_` prefix.
 3. **A place name in a region field** → stored as `{"code":"<name>","path":""}`.
 4. **A number beyond the field's precision** → silently rounded.
 5. **A title instead of a rowid in a relation** → nothing is linked.
 6. **A value on a read-only field** → ignored (except `DynamicLink`, which fails the
    whole write).
 7. **A multi-value update that omits existing values** → they are gone (sub-tables aside).
+8. **Clearing an attachment with `[]` or `null`** → rejected, and the field still holds
+   the old files (use `""`).
+9. **Relying on `attachmentData` to append** → the existing attachments are dropped.
+10. **Omitting a required field** → the API may accept it anyway, saving the row with
+    that value empty (see 1.7).
 
 So: **always read back after writing.** Do not trust the success alone.

{hap_cli-0.8.23 → hap_cli-0.8.24}/hap_cli/guide/zh-Hans/overview.md

@@ -32,8 +32,8 @@
 - `--json` / `--profile` 是**全局选项，必须放在 `hap` 和子命令之间**：
   `hap --json chat list` ✅，`hap chat list --json` ❌（报 "No such option"）。
 - 看工作表字段用 `hap worksheet fields WS_ID`，**不是** get / structure。
-- `record create/update/delete` **不接受 `--app-id`**，只走默认应用；
-  改数据前先 `hap app select <appId>` 设一次。
+- 写记录**不依赖默认应用**——`worksheetId` 就能定位工作表，`-a/--app-id` 可传可不传。
+  写入失败时别往「是不是没 select 对应用」上想。
 - 写记录的取值格式差别很大且**写错不报错** —— 动手前先看 `hap guide record`。
 - 操作工作流节点前先 `hap workflow structure PROCESS_ID` 看真实结构，别编造节点 ID。
 - 排查问题开日志：`hap config log on`，日志在 `~/.hap-cli/hap-cli.log`（已对凭证脱敏）。