hap-cli 0.8.26__tar.gz → 0.8.28__tar.gz

{hap_cli-0.8.26 → hap_cli-0.8.28}/PKG-INFO

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

{hap_cli-0.8.26 → hap_cli-0.8.28}/hap_cli/__init__.py

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

{hap_cli-0.8.26 → hap_cli-0.8.28}/hap_cli/commands/chat_cmd.py

@@ -274,8 +274,11 @@ def chat_send_to_one(ctx, to, message, files, dry_run):
     \b
       hap chat send-to-one -t <accountId> -m "spec attached" -f ./spec.pdf
 
-    Text and each file arrive as separate messages, in that order. You
-    cannot message yourself — your own account is skipped.
+    Text and each file arrive as separate messages, in that order.
+
+    To message yourself, send to the file-transfer assistant with
+    -t file-transfer. Your own account id is not a valid target and is
+    skipped.
     """
     if not to:
         ctx.handle_error(click.UsageError(
@@ -302,9 +305,20 @@ def chat_send_to_one(ctx, to, message, files, dry_run):
         return
     try:
         session = ctx.get_session()
+        # The file-transfer assistant is a conversation id, not an account
+        # id, so the account-addressed endpoint drops it silently. It goes
+        # over the socket path the chat panel uses instead.
+        socket_targets = [t for t in to if t == chat_mod.FILE_TRANSFER_ID]
+        account_targets = [t for t in to if t != chat_mod.FILE_TRANSFER_ID]
         if not sources:
-            data = chat_mod.send_message(session, list(to), message)
-            ctx.output(data, lambda d: click.echo("Message sent."))
+            results = {}
+            if account_targets:
+                results["accounts"] = chat_mod.send_message(
+                    session, account_targets, message)
+            for target in socket_targets:
+                results[target] = chat_mod.send_user_message(
+                    session, target, message)
+            ctx.output(results, lambda d: click.echo("Message sent."))
             return
         descriptors = chat_mod.upload_chat_files(session, sources)
         acks = chat_mod.send_files(session, list(to), descriptors, message)
@@ -430,3 +444,65 @@ def chat_card_detail(ctx, task, post, calendar, kcfile, worksheet, worksheetrow)
     except Exception as e:
         ctx.handle_error(e)
 
+
+
+@chat.command("recall")
+@click.argument("message_id")
+@click.option("--group-id", "group_id", default="", help="Group id the message is in")
+@click.option("--with-user", "with_user", default="",
+              help="Peer accountId for a 1-on-1 message")
+@click.option("--time", "msg_time", default="",
+              help="Send time of the message. Looked up from the conversation "
+                   "when omitted.")
+@click.option("--as-admin", is_flag=True,
+              help="Recall as a group admin. Admins may recall another "
+                   "member's message; ordinary recall only covers your own.")
+@click.option("--dry-run", is_flag=True,
+              help="Show which message would be recalled, without recalling it.")
+@pass_context
+def chat_recall(ctx, message_id, group_id, with_user, msg_time, as_admin, dry_run):
+    """Recall a message you sent.
+
+    You can recall your own message within 5 minutes of sending it; a group
+    admin can recall another member's message with no time limit. A recall
+    cannot be undone.
+    """
+    if bool(group_id) == bool(with_user):
+        raise click.UsageError("Pass exactly one of --group-id or --with-user.")
+    try:
+        session = ctx.get_session()
+        found = None
+        if not msg_time:
+            # The recall payload carries the message's send time; look it
+            # up so the caller only needs the message id.
+            history = (
+                chat_mod.get_group_messages(session, group_id, num=50)
+                if group_id else
+                chat_mod.get_user_messages(session, with_user, num=50)
+            ) or []
+            for m in history:
+                if str(m.get("id")) == str(message_id):
+                    found = m
+                    msg_time = m.get("time", "")
+                    break
+        if dry_run:
+            ctx.output(
+                {"messageId": message_id,
+                 "groupId": group_id, "withUser": with_user,
+                 "time": msg_time,
+                 "preview": ((found or {}).get("msg") or {}).get("con"),
+                 "recalled": False},
+                lambda d: click.echo(
+                    f"Would recall {d['messageId']}"
+                    + (f" ({d['preview']!r})" if d.get("preview") else "")),
+            )
+            return
+        admin_id = session.account_id if as_admin else ""
+        data = chat_mod.withdraw_message(
+            session, message_id,
+            group_id=group_id, to_user=with_user,
+            time=msg_time, admin_account_id=admin_id,
+        )
+        ctx.output(data, lambda d: click.echo("Message recalled."))
+    except Exception as e:
+        ctx.handle_error(e)

{hap_cli-0.8.26 → hap_cli-0.8.28}/hap_cli/commands/instance_cmd.py

@@ -6,6 +6,11 @@ import click
 
 from hap_cli.context import pass_context
 from hap_cli.core import instance as inst_mod
+from hap_cli.core import record as rec_mod
+from hap_cli.commands.record_cmd import (
+    _fields_json_to_raw as _rec_fields_json_to_raw,
+    _parse_fields as _rec_parse_fields,
+)
 from hap_cli.utils.formatting import output_json, output_table, output_kv
 from hap_cli.i18n import t
 
@@ -165,15 +170,110 @@ def instance_sign(ctx, instance_id, sign_to, before, work_id, opinion):
         ctx.handle_error(e)
 
 
+def _unwritten_fields(session, worksheet_id, row_id, controls):
+    """Names of controls whose non-empty write did not land on the record.
+
+    A fill-in node only accepts the fields on its own form; anything else is
+    dropped silently. Only non-empty writes are checked, so deliberately
+    clearing a field is never reported.
+    """
+    intended = [
+        c["controlId"] for c in controls
+        if str(c.get("value") or "").strip() not in ("", "[]")
+    ]
+    if not intended:
+        return []
+    row = rec_mod.get_record(session, worksheet_id, row_id) or {}
+    # get_record returns the cell values as a JSON *string* under rowData.
+    values = row.get("rowData") or {}
+    if isinstance(values, str):
+        try:
+            values = _json.loads(values)
+        except ValueError:
+            return []          # unreadable read-back: don't block on a guess
+    if not isinstance(values, dict):
+        return []
+    return [cid for cid in intended
+            if str(values.get(cid) or "").strip() in ("", "[]")]
+
+
 @instance.command("submit")
 @click.argument("instance_id")
 @click.option("--work-id", "-w", default="", help="Work item ID")
 @click.option("--opinion", "-o", default="", help="Submit comment")
+@click.option("--field", "-f", multiple=True,
+              help="Field value to fill in before submitting: FIELD=VALUE "
+                   "(repeatable). FIELD is a field id, alias or name.")
+@click.option("--fields-json", default="",
+              help="Field values to fill in before submitting, as one JSON "
+                   "array: [{\"id\": \"<field id or alias>\", \"value\": ...}, ...]. "
+                   "Use either this or -f, not both. Value formats per field "
+                   "type are in `hap guide record`.")
+@click.option("--dry-run", is_flag=True,
+              help="Resolve the task's record and show what would be written, "
+                   "without filling anything in or submitting.")
 @pass_context
-def instance_submit(ctx, instance_id, work_id, opinion):
-    """Submit a fill-in task."""
+def instance_submit(ctx, instance_id, work_id, opinion, field, fields_json, dry_run):
+    """Submit a fill-in task, optionally filling in its form first.
+
+    The fields of a fill-in task are writable only while you hold the task,
+    so pass them here rather than editing the record separately. Working
+    through todos end to end is covered in `hap guide approval`.
+    """
+    if field and fields_json:
+        raise click.UsageError("Pass exactly one of -f or --fields-json.")
     try:
         session = ctx.get_session()
+        raw = None
+        if field or fields_json:
+            raw = (_rec_fields_json_to_raw(fields_json) if fields_json
+                   else _rec_parse_fields(field))
+        # Read-only resolution first: a fill-in task carries the record it
+        # writes to, which the caller should not have to look up.
+        target = None
+        if raw is not None:
+            target = inst_mod.get_work_item(session, instance_id, work_id=work_id)
+            if not (target or {}).get("worksheetId"):
+                raise click.ClickException(
+                    "Could not resolve the record behind this task, so there "
+                    "is nothing to fill in. Check the instance and work id.")
+        if dry_run:
+            ctx.output(
+                {"instanceId": instance_id, "workId": work_id,
+                 "target": target, "fields": raw, "submitted": False},
+                lambda d: click.echo(
+                    f"Would fill {len(raw or [])} field(s) on "
+                    f"{(target or {}).get('worksheetId', '-')}/"
+                    f"{(target or {}).get('rowId', '-')} and submit."),
+            )
+            return
+        if raw is not None:
+            ws_id, row_id = target["worksheetId"], target.get("rowId", "")
+            controls = rec_mod.encode_controls_by_id(
+                session, ws_id, raw, for_update=True)
+            # The record itself may be read-only outside the task; the
+            # instance/work pair is what grants the write.
+            rec_mod.update_record(
+                session, ws_id, row_id, controls,
+                instance_id=instance_id, work_id=work_id,
+            )
+            # A field the task's form does not contain is dropped by the
+            # server without any error, so the write must be read back
+            # before the task is submitted — otherwise the value is lost
+            # and the task is gone with it.
+            dropped = _unwritten_fields(session, ws_id, row_id, controls)
+            if dropped:
+                # Report the names the caller typed, not internal ids.
+                labels = dict(zip(
+                    [c.get("controlId") for c in controls],
+                    [str(r.get("controlId")) for r in raw],
+                )) if len(controls) == len(raw) else {}
+                shown = [labels.get(cid, cid) for cid in dropped]
+                raise click.ClickException(
+                    "These values were not saved, so the task was NOT "
+                    "submitted: " + ", ".join(shown) + ". A fill-in task "
+                    "only accepts the fields on its own form; fill the rest "
+                    "separately, or drop them and submit again.")
         data = inst_mod.submit(session, instance_id, work_id, opinion)
         ctx.output(data, lambda d: click.echo("Submitted."))
     except Exception as e:

{hap_cli-0.8.26 → hap_cli-0.8.28}/hap_cli/commands/post_cmd.py

@@ -644,25 +644,74 @@ def post_get(ctx, post_id):
     help="Post type: 0=text, 3=link, 5=vote, 7=file",
 )
 @click.option(
-    "--share-group",
+    "--to-group",
     "share_group_ids",
     multiple=True,
-    help="Also share to this group id (repeatable)",
+    help="Audience: members of this group can see the post (repeatable). "
+         "Naming a group does not also publish to the organization.",
 )
 @click.option(
-    "--share-org",
+    "--to-org",
     "share_org_ids",
     multiple=True,
-    help=(
-        "Share to this organization id (repeatable). If omitted, the post "
-        "goes only to --org-id."
-    ),
+    help="Audience: everyone in this organization can see the post "
+         "(repeatable). This is the company-wide feed.",
 )
+@click.option("--share-group", "legacy_group_ids", multiple=True, hidden=True)
+@click.option("--share-org", "legacy_org_ids", multiple=True, hidden=True)
+@click.option("--card-to-group", "card_group_ids", multiple=True,
+              help="After publishing, also send a card linking to the post "
+                   "into this group chat (repeatable). This is a chat "
+                   "message and does not change who can see the post.")
+@click.option("--dry-run", is_flag=True,
+              help="Show the audience and what would be sent, without publishing.")
 @pass_context
-def post_create(ctx, org_id, message, post_type, share_group_ids, share_org_ids):
-    """Create a new post in the given organization."""
+def post_create(ctx, org_id, message, post_type, share_group_ids, share_org_ids,
+                legacy_group_ids, legacy_org_ids, card_group_ids, dry_run):
+    """Create a new post in the given organization.
+
+    Audience is set with --to-group / --to-org and defaults to everyone in
+    --org-id when neither is given. Who can see a post, and sending a card
+    about it to a group chat, are covered in `hap guide post`.
+    """
     try:
+        share_group_ids = tuple(share_group_ids) + tuple(legacy_group_ids)
+        share_org_ids = tuple(share_org_ids) + tuple(legacy_org_ids)
+        if dry_run:
+            audience = (
+                [f"group:{g}" for g in share_group_ids]
+                + [f"org:{o}" for o in share_org_ids]
+            ) or [f"org:{org_id or '<current>'} (everyone, default)"]
+            ctx.output(
+                {"audience": audience, "cardToGroups": list(card_group_ids),
+                 "message": message, "published": False},
+                lambda d: click.echo(
+                    "Would publish to: " + ", ".join(d["audience"])
+                    + (f"; card to groups: {', '.join(d['cardToGroups'])}"
+                       if d["cardToGroups"] else "")),
+            )
+            return
         session = ctx.get_session()
+        # Only a group with the feed turned on can be a post audience. The
+        # server rejects the rest with "选择了没有加入的群组" (you picked a
+        # group you have not joined), which is misleading when you are in
+        # the group — it is a plain chat group with no feed. Check first so
+        # the message names the real reason.
+        if share_group_ids:
+            from hap_cli.core import group as group_mod
+            no_feed = []
+            for gid in share_group_ids:
+                info = group_mod.get_group_info(session, gid) or {}
+                if isinstance(info.get("data"), dict):
+                    info = info["data"]
+                if not info.get("isPost"):
+                    no_feed.append(info.get("name") or gid)
+            if no_feed:
+                raise click.ClickException(
+                    "These groups cannot receive a post because they are chat "
+                    "groups with no feed enabled: " + ", ".join(no_feed)
+                    + ". Pick a group whose feed is on, or send a card to the "
+                      "chat instead with --card-to-group.")
         pid = require_api_project_id(session, org_id)
         raw = post_mod.add_post(
             session,
@@ -674,10 +723,21 @@ def post_create(ctx, org_id, message, post_type, share_group_ids, share_org_ids)
         )
         post_obj = raw.get("post") if isinstance(raw, dict) else None
         summary = _simplify_post(post_obj) if post_obj else {"raw": raw}
+        if card_group_ids and summary.get("id"):
+            from hap_cli.core import chat as chat_mod
+            sent = []
+            for gid in card_group_ids:
+                chat_mod.send_group_post_card(
+                    session, gid, summary["id"], message,
+                    post_type=post_type)
+                sent.append(gid)
+            summary["cardSentToGroups"] = sent
         def _render(d):
             click.echo(f"Post created: {d.get('id')}")
             if d.get("text"):
                 click.echo(f"  {d['text']}")
+            if d.get("cardSentToGroups"):
+                click.echo(f"  Card sent to: {', '.join(d['cardSentToGroups'])}")
         ctx.output(summary, _render)
     except Exception as e:
         ctx.handle_error(e)

{hap_cli-0.8.26 → hap_cli-0.8.28}/hap_cli/commands/record_cmd.py

@@ -162,8 +162,17 @@ def _fields_json_to_raw(fields_json):
     "--app-id", "-a", default="",
     help="Application ID. Optional — the worksheet id is enough on its own; this only scopes the field lookup.",
 )
+@click.option("--instance-id", default="",
+              help="Workflow instance the edit belongs to. Pass together with "
+                   "--work-id to fill in the form of a fill-in task, whose "
+                   "fields are only writable while you hold that task. To fill "
+                   "a task and submit it in one step use `approval submit -f`; "
+                   "see `hap guide approval`.")
+@click.option("--work-id", default="",
+              help="Workflow work-item the edit belongs to. Use with --instance-id.")
 @pass_context
-def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow, app_id):
+def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow, app_id,
+                  instance_id, work_id):
     """Update a record.
 
     Pass values either as repeated -f CONTROL_ID=VALUE pairs or as one
@@ -193,6 +202,7 @@ def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow, ap
         data = rec_mod.update_record(
             session, worksheet_id, row_id, controls,
             trigger_workflow=not no_workflow, app_id=app_id,
+            instance_id=instance_id, work_id=work_id,
         )
         ctx.output(data, lambda d: click.echo(f"Updated: {d}"))
     except Exception as e:

{hap_cli-0.8.26 → hap_cli-0.8.28}/hap_cli/core/chat.py

@@ -438,6 +438,159 @@ def send_group_message(
     return ack_data
 
 
+# The file-transfer assistant (文件传输助手) is a real 1-on-1 conversation
+# with a fixed pseudo-account id, not a shortcut for your own account
+# (pd-openweb src/pages/chat/utils/constant.js `FILE_TRANSFER.id`). It is
+# how the web client lets you message yourself.
+FILE_TRANSFER_ID = "file-transfer"
+
+
+def send_user_message(
+    session: Session,
+    to_user: str,
+    message: str,
+) -> Any:
+    """Send a 1-on-1 chat message over the socket, as the chat panel does.
+
+    ``send_message`` posts to the main-site ``Message.SendMessageToAccountIds``,
+    which addresses real *account ids* and silently drops anything else —
+    the caller's own id, and the file-transfer assistant, both come back
+    as ``successCount: 0`` with nothing stored.
+
+    The chat panel never uses that endpoint: it emits the socket.io event
+    ``'send message'`` with ``touser`` set to the conversation id
+    (``src/pages/chat/utils/socket.js`` ``Message.send`` USER branch;
+    ``containers/ChatPanelSession/index.js:152,334,357`` set
+    ``sendMsg.touser = session.id``). Because the target is a
+    conversation id rather than an account id, this path also reaches
+    :data:`FILE_TRANSFER_ID`, which is what "send to myself" means in the
+    web client.
+    """
+    import uuid
+
+    if not to_user:
+        raise ValueError("to_user is required")
+    if not message:
+        raise ValueError("message must not be empty")
+    payload = {
+        "type": MSGTYPE_TEXT,
+        "msg": message,
+        "touser": to_user,
+        "waitingid": str(uuid.uuid4()),
+    }
+    ack = _socket_emit(session, "send message", payload, strict=True)
+    if isinstance(ack, tuple) and len(ack) >= 2:
+        return ack[1]
+    return ack
+
+
+def withdraw_message(
+    session: Session,
+    message_id: str,
+    *,
+    group_id: str = "",
+    to_user: str = "",
+    time: str = "",
+    admin_account_id: str = "",
+) -> Any:
+    """Recall (撤回) a message you sent, in a group or a 1-on-1 chat.
+
+    Recall has no REST endpoint — pd-openweb emits a socket.io event
+    (``src/pages/chat/utils/socket.js`` ``Message.sendWithdrawMessgae``):
+    ``'withdraw group message'`` for a group, ``'withdraw user message'``
+    for a 1-on-1. The parameter object is built by
+    ``containers/Message/index.js::handleWithdrawMessage`` as
+    ``{messageId, groupid | touser, time}`` — note the lowercase
+    ``groupid`` / ``touser`` keys — plus ``adminid`` when a group admin
+    recalls somebody else's message.
+
+    Server-side limits, surfaced by the UI rather than by us: an author
+    can only recall within 5 minutes of sending
+    (``components/Message/MessageToolbar/index.js:285``), while a group
+    admin may recall another member's message with no time limit
+    (``:275-276``). A recall past the window is refused by the server.
+
+    Exactly one of ``group_id`` / ``to_user`` identifies the conversation.
+    """
+    if not message_id:
+        raise ValueError("message_id is required")
+    if bool(group_id) == bool(to_user):
+        raise ValueError("pass exactly one of group_id or to_user")
+    param: dict[str, Any] = {"messageId": message_id, "time": time or ""}
+    if group_id:
+        param["groupid"] = group_id
+        event = "withdraw group message"
+    else:
+        param["touser"] = to_user
+        event = "withdraw user message"
+    if admin_account_id:
+        param["adminid"] = admin_account_id
+    ack = _socket_emit(session, event, param, strict=True)
+    if isinstance(ack, tuple) and len(ack) >= 2:
+        return ack[1]
+    return ack
+
+
+def send_group_post_card(
+    session: Session,
+    group_id: str,
+    post_id: str,
+    title: str,
+    *,
+    post_type: int = 0,
+    server_url: str = "",
+) -> Any:
+    """Send a card linking to a post into a group chat.
+
+    This is a chat message about a post; it does not change who can see
+    the post itself (that is the post's own audience — see
+    ``hap_cli.core.post.add_post``).
+
+    Wire shape mirrors ``pd-openweb/src/pages/chat/utils/cardSender.js``
+    (``_initPost``): message ``type`` 5 (``Constant.MSGTYPE_CARD``) with a
+    ``card`` of ``{md, entityid, url, title, text}``, where ``md`` is
+    ``vote`` for a vote post (postType 7) and ``post`` otherwise, and the
+    url is ``/feeddetail?itemID=<postId>``. The title is capped at 300
+    characters, as the frontend does.
+
+    The ``msg`` line is the conversation-list summary, built the way
+    ``ChatPanelSession/index.js:277-278`` builds it: ``[<kind>] <title>``,
+    where the kind comes from the *localized* card name
+    (``cardDisposeName`` → ``_l('动态')`` / ``_l('投票')``). It is read by
+    other people in the chat, so it goes through the content-default
+    catalog rather than being hardcoded in one language.
+    """
+    import uuid
+
+    from hap_cli.i18n import content_default
+
+    if not group_id:
+        raise ValueError("group_id is required")
+    if not post_id:
+        raise ValueError("post_id is required")
+    card_title = (title or "")[:300]
+    is_vote = str(post_type) == "7"
+    kind = content_default("chat.vote" if is_vote else "chat.post")
+    base = (server_url or getattr(session, "server_url", "") or "").rstrip("/")
+    payload = {
+        "type": 5,
+        "msg": f"{kind} {card_title}",
+        "card": {
+            "md": "vote" if is_vote else "post",
+            "entityid": post_id,
+            "url": f"{base}/feeddetail?itemID={post_id}",
+            "title": card_title,
+            "text": "",
+        },
+        "togroup": group_id,
+        "waitingid": str(uuid.uuid4()),
+    }
+    ack = _socket_emit(session, "send group message", payload, strict=True)
+    if isinstance(ack, tuple) and len(ack) >= 2:
+        return ack[1]
+    return ack
+
+
 def send_group_files(
     session: Session,
     group_id: str,

{hap_cli-0.8.26 → hap_cli-0.8.28}/hap_cli/core/post.py

@@ -207,19 +207,35 @@ def add_post(
 ) -> dict[str, Any]:
     """Create a post via ``Post.AddPost``.
 
-    ``scope`` is a ``PostShareScopeReq`` object — not an int. The
-    frontend (``pd-openweb/src/pages/feed/components/createFeed/index.js``)
-    posts ``{radioProjectIds, shareGroupIds, shareProjectIds}``. When
-    the caller doesn't pass ``scope`` we default to "share with the
-    given org only", which matches the UI's default for org-wide posts.
+    ``scope`` is a ``PostShareScopeReq`` object — not an int — and it is
+    what decides **who can see the post**. The frontend
+    (``pd-openweb/src/pages/feed/components/createFeed/index.js``) posts
+    ``{radioProjectIds, shareGroupIds, shareProjectIds}``:
+
+    * ``shareProjectIds: [<orgId>]`` — everyone in that organization.
+      This is the org-wide feed (index.js:267-270).
+    * ``shareGroupIds: [<groupId>]`` with ``shareProjectIds: []`` — only
+      that group's members. Posting into a group builds exactly this
+      (index.js:647-650).
+
+    ``project_id`` is the organization the post belongs to and is always
+    sent as ``projectId``; on its own it is *not* an audience. Audience
+    defaults to the whole organization only when the caller names no
+    audience at all — naming a group must never silently widen the post
+    to everyone, which is what an unconditional ``or [project_id]``
+    fallback used to do.
 
     Returns the raw ``{post, success}`` envelope.
     """
     if scope is None:
+        groups = list(share_group_ids or [])
+        orgs = list(share_project_ids or [])
+        if not groups and not orgs:
+            orgs = [project_id]
         scope = {
             "radioProjectIds": radio_project_ids,
-            "shareGroupIds": list(share_group_ids or []),
-            "shareProjectIds": list(share_project_ids or [project_id]),
+            "shareGroupIds": groups,
+            "shareProjectIds": orgs,
         }
     return session.api_call(
         "Post", "AddPost",

{hap_cli-0.8.26 → hap_cli-0.8.28}/hap_cli/core/record.py

@@ -965,6 +965,8 @@ def update_record(
     controls: list[dict[str, Any]],
     trigger_workflow: bool = True,
     app_id: str = "",
+    instance_id: str = "",
+    work_id: str = "",
 ) -> dict[str, Any]:
     """Update an existing record.
 
@@ -973,6 +975,14 @@ def update_record(
     AddWorksheetRow, UpdateWorksheetRow's schema has no ``appId``, and
     inventing one would diverge from the frontend.
 
+    ``instance_id`` / ``work_id`` identify a workflow step the caller is
+    acting inside. A fill-in node (填写节点) grants write permission on the
+    fields of its own form for the duration of that step; the record itself
+    may well be read-only otherwise, in which case a plain update answers
+    "权限不足". Passing the pair makes the write happen under the node's
+    permission, exactly as the web form does (UpdateWorksheetRow's
+    ``instanceId`` / ``workId`` params).
+
     Args:
         session: Active session
         worksheet_id: Worksheet ID
@@ -980,21 +990,24 @@ def update_record(
         controls: List of {controlId, value} dicts
         trigger_workflow: Whether to trigger workflows
         app_id: Optional application ID (metadata scope only)
+        instance_id: Workflow instance ID the write belongs to
+        work_id: Workflow work-item ID the write belongs to
 
     Returns:
         Update result
     """
     _reject_workflow_suppression(trigger_workflow)
+    payload: dict[str, Any] = {
+        "worksheetId": worksheet_id,
+        "rowId": row_id,
+        "newOldControl": controls,
+    }
+    if instance_id:
+        payload["instanceId"] = instance_id
+    if work_id:
+        payload["workId"] = work_id
     return _raise_on_failed_write(
-        session.api_call(
-            "Worksheet",
-            "UpdateWorksheetRow",
-            {
-                "worksheetId": worksheet_id,
-                "rowId": row_id,
-                "newOldControl": controls,
-            },
-        ),
+        session.api_call("Worksheet", "UpdateWorksheetRow", payload),
         "update",
     )