hap-cli 0.9.7__tar.gz → 0.9.9__tar.gz

{hap_cli-0.9.7 → hap_cli-0.9.9}/PKG-INFO

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

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/__init__.py

@@ -3,7 +3,7 @@
 import sys as _sys
 import types as _types
 
-__version__ = "0.9.7"
+__version__ = "0.9.9"
 
 # The command tree used to live in hap_cli/hap_cli.py. A module named
 # after the package it sits in shadows that package: run python with the

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/commands/chat_cmd.py

@@ -1,6 +1,8 @@
 """CLI commands for chat and messaging management."""
 
+import html
 import json
+import re
 
 import click
 
@@ -73,6 +75,103 @@ def _output_chat_list_table(rows):
     )
 
 
+def _one_line(text: str) -> str:
+    """Visible text of a message on one line: tags dropped, entities
+    decoded, runs of whitespace collapsed."""
+    text = html.unescape(re.sub(r"<[^>]*>", "", text or ""))
+    return " ".join(text.split())
+
+
+def _conversation_preview(msg: dict) -> str:
+    body = msg.get("msg") or {}
+    text = _one_line(str(body.get("con") or ""))
+    files = body.get("files")
+    if isinstance(files, dict):
+        name = f"{files.get('originalFileName') or ''}{files.get('fileExt') or ''}"
+        label = "[image]" if msg.get("type") == 2 else "[file]"
+        text = " ".join(x for x in (label, name, text) if x)
+    return text
+
+
+def _output_conversation_table(rows):
+    """One row per message of a 1-on-1 or group chat, in the order the
+    server returns them (newest first)."""
+    output_table(
+        [
+            {
+                "time": str(m.get("time") or "")[:19],
+                "from": (m.get("fromAccount") or {}).get("name") or m.get("from", ""),
+                "message": _conversation_preview(m),
+                "id": m.get("id", ""),
+            }
+            for m in rows or []
+            if isinstance(m, dict)
+        ],
+        ["time", "from", "message", "id"],
+        ["Time", "From", "Message", "Message ID"],
+    )
+
+
+def _output_inbox_table(data):
+    rows = (data or {}).get("list") or []
+    output_table(
+        [
+            {
+                "time": r.get("createTime", ""),
+                "from": (r.get("sender") or {}).get("name")
+                or (r.get("app") or {}).get("name", ""),
+                "message": _one_line(str(r.get("message") or "")),
+            }
+            for r in rows
+            if isinstance(r, dict)
+        ],
+        ["time", "from", "message"],
+        ["Time", "From", "Message"],
+    )
+
+
+def _output_messages(data):
+    if isinstance(data, dict) and "list" in data:
+        _output_inbox_table(data)
+    else:
+        _output_conversation_table(data)
+
+
+def _output_chat_files(data):
+    rows = (data or {}).get("list") or []
+    output_table(
+        [
+            {
+                "time": r.get("time", ""),
+                "name": r.get("name", ""),
+                "size": _file_size(r.get("size")),
+                "from": (r.get("createAccount") or {}).get("fullname", ""),
+                "fileId": r.get("fileId", ""),
+            }
+            for r in rows
+            if isinstance(r, dict)
+        ],
+        ["time", "name", "size", "from", "fileId"],
+        ["Time", "Name", "Size", "From", "File ID"],
+    )
+    total = (data or {}).get("allCount")
+    if isinstance(total, int) and total > len(rows):
+        click.echo(f"Showing {len(rows)} of {total} files. Use -p for the "
+                   f"next page.", err=True)
+
+
+def _file_size(value) -> str:
+    try:
+        size = float(value)
+    except (TypeError, ValueError):
+        return ""
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024 or unit == "GB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return ""
+
+
 @click.group(help=t(
     'Chat and messaging management.\n\n'
     'To follow a notification back to the app record it belongs to, see '
@@ -97,7 +196,8 @@ def chat_list(ctx, page_size, page):
 
 
 @chat.command("files")
-@click.option("--with-user", "with_user", help="Peer accountId for 1-on-1 files")
+@click.option("--account-id", "--with-user", "with_user",
+              help="Account id of the person, for the files of your 1-on-1 chat")
 @click.option("--group-id", "group_id", help="Group id for group chat files")
 @click.option("--page-size", "-n", default=20, help="Items per page")
 @click.option("--page", "-p", default=1, help="Page number")
@@ -114,11 +214,11 @@ def chat_list(ctx, page_size, page):
 def chat_files(ctx, with_user, group_id, page_size, page, keywords, file_type, start, end):
     """List files shared in a 1-on-1 or group chat.
 
-    Provide exactly one of --with-user or --group-id.
+    Provide exactly one of --account-id or --group-id.
     """
     if bool(with_user) == bool(group_id):
         ctx.handle_error(click.UsageError(
-            "Provide exactly one of --with-user or --group-id."
+            "Provide exactly one of --account-id or --group-id."
         ))
         return
     try:
@@ -145,13 +245,14 @@ def chat_files(ctx, with_user, group_id, page_size, page, keywords, file_type, s
                 start=start,
                 end=end,
             )
-        ctx.output(data, lambda d: output_json(d))
+        ctx.output(data, _output_chat_files)
     except Exception as e:
         ctx.handle_error(e)
 
 
 @chat.command("messages")
-@click.option("--with-user", "with_user", help="Peer accountId for 1-on-1 messages")
+@click.option("--account-id", "--with-user", "with_user",
+              help="Account id of the person, for your 1-on-1 chat with them")
 @click.option("--group-id", "group_id", help="Group id for group chat messages")
 @click.option(
     "--category",
@@ -202,7 +303,9 @@ def chat_messages(
     """Fetch chat message history.
 
     Provide exactly one of:
-      --with-user      1-on-1 chat with a user
+
+    \b
+      --account-id     1-on-1 chat with a person
       --group-id       a group chat
       --category       inbox category (system / post / task / calendar /
                        kc / hr / app / workflow)
@@ -211,7 +314,7 @@ def chat_messages(
     sources = [bool(with_user), bool(group_id), bool(category), bool(inbox_type)]
     if sum(sources) != 1:
         ctx.handle_error(click.UsageError(
-            "Provide exactly one of --with-user / --group-id / --category / --inbox-type."
+            "Provide exactly one of --account-id / --group-id / --category / --inbox-type."
         ))
         return
     try:
@@ -250,13 +353,14 @@ def chat_messages(
             )
             if mark_read and category:
                 chat_mod.mark_inbox_read(session, category)
-        ctx.output(data, lambda d: output_json(d))
+        ctx.output(data, _output_messages)
     except Exception as e:
         ctx.handle_error(e)
 
 
 @chat.command("send-to-one")
-@click.option("--to", "-t", multiple=True, help="Target user account ID (can repeat)")
+@click.option("--account-id", "--to", "-t", "to", multiple=True,
+              help="Account id of the person to message (repeatable)")
 @click.option("--message", "-m", default="", help="Message text")
 @click.option(
     "--file", "-f", "files", multiple=True,
@@ -282,7 +386,7 @@ def chat_send_to_one(ctx, to, message, files, dry_run):
     """
     if not to:
         ctx.handle_error(click.UsageError(
-            "Provide at least one --to <accountId>."
+            "Provide at least one --account-id."
         ))
         return
     if not message and not files:
@@ -446,8 +550,9 @@ def chat_card_detail(ctx, task, post, calendar, kcfile, worksheet, worksheetrow)
 @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("--account-id", "--with-user", "with_user", default="",
+              help="Account id of the person, for a message in your 1-on-1 "
+                   "chat with them")
 @click.option("--time", "msg_time", default="",
               help="Send time of the message. Looked up from the conversation "
                    "when omitted.")
@@ -465,7 +570,7 @@ def chat_recall(ctx, message_id, group_id, with_user, msg_time, as_admin, dry_ru
     cannot be undone.
     """
     if bool(group_id) == bool(with_user):
-        raise click.UsageError("Pass exactly one of --group-id or --with-user.")
+        raise click.UsageError("Pass exactly one of --group-id or --account-id.")
     try:
         session = ctx.get_session()
         found = None

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/commands/post_cmd.py

@@ -778,8 +778,8 @@ def post_create(ctx, org_id, message, post_type, files, share_group_ids,
     Files given with --file are uploaded and attached to the post.
 
     In the message, #name# files the post under the category (topic) of
-    that name, and [aid]<accountId>[/aid] mentions a person — get the id
-    with `hap contact resolve <name>`. --dry-run lists both, with the
+    that name, and user:<accountId> followed by a space mentions and
+    notifies a person — get the id with `hap contact resolve <name>`. --dry-run lists both, with the
     mentioned names, before anything is published. Details in
     `hap guide post tags`.
     """
@@ -796,7 +796,8 @@ def post_create(ctx, org_id, message, post_type, files, share_group_ids,
             ) or [f"org:{org_id or '<current>'} (everyone, default)"]
             preview = {"audience": audience,
                        "cardToGroups": list(card_group_ids),
-                       "message": message, "files": list(files),
+                       "message": post_mod.mention_syntax(message),
+                       "files": list(files),
                        "categories": post_mod.extract_topics(message),
                        "mentions": _preview_mentions(ctx, org_id, message),
                        "published": False}
@@ -915,7 +916,11 @@ def post_delete(ctx, post_id, yes):
 )
 @pass_context
 def post_comment(ctx, post_id, message, reply_id, reply_account_id, files):
-    """Add a comment to a post, optionally with files attached."""
+    """Add a comment to a post, optionally with files attached.
+
+    Mention someone with user:<accountId> followed by a space; they are
+    notified. Get the id with `hap contact resolve <name>`.
+    """
     try:
         session = ctx.get_session()
         attachments = (post_mod.upload_post_files(

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/core/post.py

@@ -262,14 +262,36 @@ def upload_post_files(
 
 
 # What the feed composer writes into a post body (MDPublic
-# src/components/MentionsInput/index.jsx). The post composer opens it
-# without a sourceType, so a person is `[aid]<accountId>[/aid]`
-# (mentionItemSyntax, :75-76) and a topic is `#name#`, half- or full-width
-# `#` (categoryLetterArr, :19; :308). The server files the post under the
-# category of that name, creating it when new, and reads it back as
-# `categories` — there is no category field on AddPost itself.
+# src/components/MentionsInput/index.jsx). A topic is `#name#`, half- or
+# full-width `#` (categoryLetterArr, :19; :308). The server files the post
+# under the category of that name, creating it when new, and reads it back
+# as `categories` — there is no category field on AddPost itself.
+#
+# A person is `user:<accountId>`: posts and post comments open the
+# composer with sourceType POST, whose mentionItemSyntax is
+# `<type>:<id>` (:75-78), and a captured AddPost / AddPostComment from the
+# web feed (2026-10-12) carries exactly `user:<id> `. The server turns that
+# into the stored `[aid]<id>[/aid]` marker *and* notifies the person.
+# Sending `[aid]…[/aid]` directly renders as a mention but notifies nobody,
+# so callers that learned the stored form are rewritten — the post editor
+# does the same when it loads a post back (EditPostDialog.jsx:94).
 _TOPIC_RE = re.compile(r"[#＃]([^#＃\n]+?)[#＃]")
-_MENTION_RE = re.compile(r"\[aid\]([^\[\]]+?)\[/aid\]")
+_MENTION_RE = re.compile(r"(?<![0-9A-Za-z_])user:([0-9A-Za-z-]+)")
+_STORED_MENTION_RE = re.compile(r"\[aid\]\s*([0-9A-Za-z-]+)\s*\[/aid\]")
+
+
+def mention_syntax(message: str) -> str:
+    """Rewrite stored-form ``[aid]<id>[/aid]`` mentions to ``user:<id>``.
+
+    A space follows each rewritten mention unless whitespace already does,
+    matching the composer, which leaves one after the picked name."""
+    text = message or ""
+
+    def _sub(m: "re.Match[str]") -> str:
+        follow = text[m.end():m.end() + 1]
+        return f"user:{m.group(1)}" + ("" if not follow or follow.isspace() else " ")
+
+    return _STORED_MENTION_RE.sub(_sub, text)
 
 
 def extract_topics(message: str) -> list[str]:
@@ -283,11 +305,11 @@ def extract_topics(message: str) -> list[str]:
 
 
 def extract_mentions(message: str) -> list[str]:
-    """Account ids written as ``[aid]<id>[/aid]`` in a post body, unique."""
+    """Account ids mentioned in a post body (``user:<id>``, or the stored
+    ``[aid]<id>[/aid]`` form), in order, unique."""
     seen: list[str] = []
-    for account_id in _MENTION_RE.findall(message or ""):
-        account_id = account_id.strip()
-        if account_id and account_id not in seen:
+    for account_id in _MENTION_RE.findall(mention_syntax(message)):
+        if account_id not in seen:
             seen.append(account_id)
     return seen
 
@@ -363,7 +385,7 @@ def add_post(
     data: dict[str, Any] = {
         "projectId": project_id,
         "postType": post_type,
-        "postMsg": message,
+        "postMsg": mention_syntax(message),
         "scope": scope,
     }
     if attachments:
@@ -384,7 +406,7 @@ def edit_post(
     doesn't have the previous text we omit it (the server accepts
     either shape, but the frontend always sends the old text).
     """
-    data: dict[str, Any] = {"postId": post_id, "postMsg": message}
+    data: dict[str, Any] = {"postId": post_id, "postMsg": mention_syntax(message)}
     if old_message:
         data["oldPostMsg"] = old_message
     return _require_post_success(
@@ -413,7 +435,7 @@ def add_comment(
     string form as on a post (MDPublic src/pages/feed/components/post/
     comment/postCommentInput.jsx:181-192; pd-openweb identical).
     """
-    data: dict[str, Any] = {"postID": post_id, "message": message}
+    data: dict[str, Any] = {"postID": post_id, "message": mention_syntax(message)}
     if reply_id:
         data["replyID"] = reply_id
     if reply_account_id:

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/core/upload.py

@@ -28,7 +28,7 @@ import re
 import time
 from datetime import datetime, timezone
 from typing import Any, Callable, Optional
-from urllib.parse import parse_qs, quote, urlparse
+from urllib.parse import parse_qs, quote, unquote, urlparse
 
 import requests
 
@@ -267,6 +267,17 @@ def _encode_original_name(stem: str) -> str:
     return quote(stem, safe="")
 
 
+def _decode_original_name(echoed: Any, fallback: str) -> str:
+    """The store echoes ``x:originalFileName`` exactly as posted — still
+    percent-encoded — and the uploader decodes it before handing the file
+    on (MDPublic createUploader.js:452). Passing the echo through as-is
+    left names like "HDP-%E5%B9%BF%E5%91%8A40s" on posts, chat files and
+    record attachments."""
+    if not echoed:
+        return fallback
+    return unquote(str(echoed))
+
+
 def _name_and_ext(source: str, *, name: str = "") -> tuple[str, str]:
     """Derive (originalName-without-ext, ext-with-dot) from a name or path/url.
 
@@ -368,7 +379,7 @@ def upload_bytes(
         "filePath": up.get("filePath"),
         "fileName": up.get("fileName"),
         "fileExt": up.get("fileExt"),
-        "originalFileName": up.get("originalFileName"),
+        "originalFileName": _decode_original_name(up.get("originalFileName"), original),
         "key": up.get("key") or token.get("key"),
         "url": token.get("url"),
         # The signed URL above stops working at this instant — see

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/guide/en/messages.md

@@ -30,7 +30,7 @@ hap --json chat messages --category app        # or workflow, etc.
   with `viewId`, `comment.recordName` and `comment.entityName`.
 - Workflow **cc / participant** notifications have the `appId` / `worksheetId` / `rowId`
   resolved out of the record link for you.
-- One-to-one and group chats do not use `--category`; use `--with-user <accountId>` or
+- One-to-one and group chats do not use `--category`; use `--account-id <accountId>` or
   `--group-id <groupId>` (the id is the conversation's `value`).
 
 **3. Read the record and its discussion**

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/guide/en/post.md

@@ -92,19 +92,20 @@ remove it too, recall that message with
 minutes of sending; a group admin can recall a member's message with no limit).
 
 ## 3. Categories and mentions in the body
-<!-- hook: #name# in the body sets the post's category; [aid]accountId[/aid] mentions a person; --dry-run previews both. -->
+<!-- hook: #name# in the body sets the post's category; user:<accountId> mentions and notifies a person; --dry-run previews both. -->
 <!-- alias: tags -->
 
 There is no category option: **the category comes from the body.** Writing
 `#name#` (for example `#今日工作#`) files the post under the category of that
 name, creating it if it is new. List existing ones with `hap post topics`.
 
-To mention someone, write `[aid]<accountId>[/aid]` where the `@name` should
-go. Get the id from the person's name first:
+To mention someone, write `user:<accountId>` followed by a space where the
+`@name` should go — the person is notified. The same works in
+`hap post comment`. Get the id from the person's name first:
 
 ```bash
 hap contact resolve 刘禹            # candidates[].id is the accountId
-hap post create -m "#今日工作# 今天和 [aid]<accountId>[/aid] 对齐了方案" --dry-run
+hap post create -m "#今日工作# 今天和 user:<accountId> 对齐了方案" --dry-run
 ```
 
 A published post's audience cannot be changed, so check with `--dry-run`

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/guide/index.json

@@ -51,8 +51,8 @@
         "zh-Hans": "发动态与发布范围"
       },
       "summary": {
-        "en": "Audience decides who can see a post, and you cannot read it back off an existing one; #name# in the body sets the category, [aid]…[/aid] mentions someone.",
-        "zh-Hans": "发布范围决定谁能看到，且无法从旧动态读出来；正文 #名称# 决定分类，[aid]…[/aid] 提及某人。"
+        "en": "Audience decides who can see a post, and you cannot read it back off an existing one; #name# in the body sets the category, user:<accountId> notifies a person.",
+        "zh-Hans": "发布范围决定谁能看到，且无法从旧动态读出来；正文 #名称# 决定分类，user:<accountId> 提及并通知某人。"
       }
     },
     {

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/guide/zh-Hans/messages.md

@@ -29,7 +29,7 @@ hap --json chat messages --category app        # 或 workflow 等
   `comment.recordName`、`comment.entityName`。
 - 工作流**抄送 / 参与者**类通知会把记录链接里的 `appId` / `worksheetId` / `rowId`
   一并解析出来。
-- 单聊 / 群聊不走 `--category`，用 `--with-user <accountId>` 或 `--group-id <groupId>`
+- 单聊 / 群聊不走 `--category`，用 `--account-id <accountId>` 或 `--group-id <groupId>`
   （id 取会话的 `value`）。
 
 **3. 拿三元组直接读记录和讨论**

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/guide/zh-Hans/post.md

@@ -80,17 +80,18 @@ hap post create -m "内容" --to-group 9ccde712-xxxx --card-to-group 7f694ec7-xx
 撤回那条卡片消息（自己的消息限发送后 5 分钟内，群管理员撤回他人消息不限时）。
 
 ## 3. 正文里的分类与 @提及
-<!-- hook: 正文 #名称# 定分类，[aid]id[/aid] 提及某人，--dry-run 可预览 -->
+<!-- hook: 正文 #名称# 定分类，user:id 提及并通知某人，--dry-run 可预览 -->
 <!-- alias: tags -->
 
 没有设置分类的选项：**分类由正文决定。** 正文里写 `#名称#`（例如 `#今日工作#`），
 动态就会归到同名分类下，分类不存在时会自动新建。已有分类用 `hap post topics` 查。
 
-要 @ 某人，在想出现「@姓名」的位置写 `[aid]<accountId>[/aid]`。先用姓名查出 id：
+要 @ 某人，在想出现「@姓名」的位置写 `user:<accountId>`，后面跟一个空格，对方会收到提醒。
+`hap post comment` 里写法相同。先用姓名查出 id：
 
 ```bash
 hap contact resolve 刘禹            # candidates[].id 就是 accountId
-hap post create -m "#今日工作# 今天和 [aid]<accountId>[/aid] 对齐了方案" --dry-run
+hap post create -m "#今日工作# 今天和 user:<accountId> 对齐了方案" --dry-run
 ```
 
 动态发出后范围无法再改，所以先用 `--dry-run` 检查：它会列出分类，以及每个

{hap_cli-0.9.7 → hap_cli-0.9.9}/hap_cli/locale/messages.json

@@ -3015,6 +3015,30 @@
       "en": "Output in JSON format",
       "zh-Hans": "以 JSON 格式输出"
     },
+    "attachment download": {
+      "en": "Download a file attached to a worksheet record.\n\nFILE_ID is listed in an attachment field or a record operation log.\nExisting local files are never overwritten.",
+      "zh-Hans": "下载工作表记录里的附件。\n\nFILE_ID 可以在附件字段或记录操作日志中找到。不会覆盖本地已有的文件。"
+    },
+    "attachment download --control-id": {
+      "en": "Attachment field containing the file.",
+      "zh-Hans": "附件所在的附件字段。"
+    },
+    "attachment download --json": {
+      "en": "Output in JSON format",
+      "zh-Hans": "以 JSON 格式输出"
+    },
+    "attachment download --output": {
+      "en": "Save as this path. By default, uses the attachment name.",
+      "zh-Hans": "保存到此路径。默认使用附件原名。"
+    },
+    "attachment download --row-id": {
+      "en": "Record containing the attachment.",
+      "zh-Hans": "附件所在的记录。"
+    },
+    "attachment download --worksheet-id": {
+      "en": "Worksheet containing the record.",
+      "zh-Hans": "记录所在的工作表。"
+    },
     "attachment share": {
       "en": "Create a link to a stored file that you can pass on.\n\n\b\n  hap attachment share https://doc.example.com/doc/20260830/abc.html\n  hap attachment share doc/20260830/abc.html --hours 168\n  hap attachment share --file-id <id>\n\nADDRESS is the file's link — a link that has already stopped working\nis fine, paste it as-is — or just the path part of it.",
       "zh-Hans": "为已存储的文件创建可转发的链接。\n\n\b\n  hap attachment share https://doc.example.com/doc/20260830/abc.html\n  hap attachment share doc/20260830/abc.html --hours 168\n  hap attachment share --file-id <id>\n\nADDRESS 是文件的链接——已经失效的链接也可以，原样粘贴即可——或者只传链接中的路径部分。"
@@ -3432,8 +3456,12 @@
       "zh-Hans": "工作表记录，格式 'wsId>rowId'，以 '|' 分隔"
     },
     "chat files": {
-      "en": "List files shared in a 1-on-1 or group chat.\n\nProvide exactly one of --with-user or --group-id.",
-      "zh-Hans": "列出单聊或群聊中共享的文件。\n\n--with-user 与 --group-id 必须且只能提供一个"
+      "en": "List files shared in a 1-on-1 or group chat.\n\nProvide exactly one of --account-id or --group-id.",
+      "zh-Hans": "列出单聊或群聊中共享的文件。\n\n--account-id 与 --group-id 必须且只能提供一个。"
+    },
+    "chat files --account-id": {
+      "en": "Account id of the person, for the files of your 1-on-1 chat",
+      "zh-Hans": "对方的账号 ID，列出你和此人单聊中的文件"
     },
     "chat files --end": {
       "en": "End timestamp (inclusive)",
@@ -3467,10 +3495,6 @@
       "en": "Start timestamp (inclusive)",
       "zh-Hans": "开始时间戳（含）"
     },
-    "chat files --with-user": {
-      "en": "Peer accountId for 1-on-1 files",
-      "zh-Hans": "单聊文件的对方 accountId"
-    },
     "chat list": {
       "en": "List recent chat sessions.",
       "zh-Hans": "列出最近的聊天会话"
@@ -3488,8 +3512,12 @@
       "zh-Hans": "每页条数"
     },
     "chat messages": {
-      "en": "Fetch chat message history.\n\nProvide exactly one of:\n  --with-user      1-on-1 chat with a user\n  --group-id       a group chat\n  --category       inbox category (system / post / task / calendar /\n                   kc / hr / app / workflow)\n  --inbox-type     raw inbox type code for advanced filters",
-      "zh-Hans": "获取聊天消息历史。\n\n以下选项必须且只能提供一个：\n  --with-user      与某用户的单聊\n  --group-id       群聊\n  --category       收件箱分类（system / post / task / calendar /\n                   kc / hr / app / workflow）\n  --inbox-type     原始收件箱类型代码，用于高级筛选"
+      "en": "Fetch chat message history.\n\nProvide exactly one of:\n\n\b\n  --account-id     1-on-1 chat with a person\n  --group-id       a group chat\n  --category       inbox category (system / post / task / calendar /\n                   kc / hr / app / workflow)\n  --inbox-type     raw inbox type code for advanced filters",
+      "zh-Hans": "获取聊天消息历史。\n\n以下选项必须且只能提供一个：\n\n\b\n  --account-id     与某人的单聊\n  --group-id       群聊\n  --category       收件箱分类（system / post / task / calendar /\n                   kc / hr / app / workflow）\n  --inbox-type     原始收件箱类型代码，用于高级筛选"
+    },
+    "chat messages --account-id": {
+      "en": "Account id of the person, for your 1-on-1 chat with them",
+      "zh-Hans": "对方的账号 ID，查看你和此人的单聊"
     },
     "chat messages --category": {
       "en": "Inbox category: system, post, task, calendar, kc, hr, app, workflow",
@@ -3531,14 +3559,14 @@
       "en": "Anchor timestamp, e.g. '2026-04-07 19:06:53.038' (paginate around this)",
       "zh-Hans": "锚点时间戳，例如 '2026-04-07 19:06:53.038'（以此为基准分页）"
     },
-    "chat messages --with-user": {
-      "en": "Peer accountId for 1-on-1 messages",
-      "zh-Hans": "单聊消息的对方 accountId"
-    },
     "chat recall": {
       "en": "Recall a message you sent.\n\nYou can recall your own message within 5 minutes of sending it; a group\nadmin can recall another member's message with no time limit. A recall\ncannot be undone.",
       "zh-Hans": "撤回自己发送的消息。自己的消息限发送后 5 分钟内撤回；群管理员撤回其他成员的消息不限时间。撤回后无法恢复。"
     },
+    "chat recall --account-id": {
+      "en": "Account id of the person, for a message in your 1-on-1 chat with them",
+      "zh-Hans": "对方的账号 ID，撤回你和此人单聊中的消息"
+    },
     "chat recall --as-admin": {
       "en": "Recall as a group admin. Admins may recall another member's message; ordinary recall only covers your own.",
       "zh-Hans": "以群管理员身份撤回。管理员可撤回其他成员的消息；普通撤回只能撤回自己的。"
@@ -3559,10 +3587,6 @@
       "en": "Send time of the message. Looked up from the conversation when omitted.",
       "zh-Hans": "消息的发送时间。省略时自动从会话记录中查找。"
     },
-    "chat recall --with-user": {
-      "en": "Peer accountId for a 1-on-1 message",
-      "zh-Hans": "单聊消息的对方 accountId"
-    },
     "chat send-to-group": {
       "en": "Send a message, optionally with files, to a group chat.\n\n\b\n  hap chat send-to-group -g <groupId> -m \"spec attached\" -f ./spec.pdf\n\nText and each file arrive as separate messages, in that order. An\n@-mention applies to the text line, so it needs --message.",
       "zh-Hans": "向群聊发送消息，可附带文件。\n\n\b\n  hap chat send-to-group -g <groupId> -m \"spec attached\" -f ./spec.pdf\n\n文本和每个文件会依次作为独立消息送达。@提及作用于文本行，因此需要 --message"
@@ -3599,6 +3623,10 @@
       "en": "Send a message, optionally with files, to one or more users (1-on-1).\n\n\b\n  hap chat send-to-one -t <accountId> -m \"spec attached\" -f ./spec.pdf\n\nText and each file arrive as separate messages, in that order.\n\nTo message yourself, send to the file-transfer assistant with\n-t file-transfer. Your own account id is not a valid target.",
       "zh-Hans": "向一个或多个用户发送消息（单聊），可附带文件。\n\n  hap chat send-to-one -t <accountId> -m \"spec attached\" -f ./spec.pdf\n\n文本和每个文件会依次作为独立消息送达。\n\n给自己发消息请发到文件传输助手：-t file-transfer。自己的账号 ID 不是有效目标。"
     },
+    "chat send-to-one --account-id": {
+      "en": "Account id of the person to message (repeatable)",
+      "zh-Hans": "接收消息的人的账号 ID（可重复）"
+    },
     "chat send-to-one --dry-run": {
       "en": "Show what would be sent, without uploading or sending anything.",
       "zh-Hans": "仅显示将要发送的内容，不上传也不发送"
@@ -3615,10 +3643,6 @@
       "en": "Message text",
       "zh-Hans": "消息文本"
     },
-    "chat send-to-one --to": {
-      "en": "Target user account ID (can repeat)",
-      "zh-Hans": "目标用户账号 ID（可重复）"
-    },
     "completion": {
       "en": "Alias of `hap config completion`.",
       "zh-Hans": "`hap config completion` 的别名"
@@ -4468,8 +4492,8 @@
       "zh-Hans": "以 JSON 格式输出"
     },
     "post comment": {
-      "en": "Add a comment to a post, optionally with files attached.",
-      "zh-Hans": "为动态添加评论，可同时附带文件。"
+      "en": "Add a comment to a post, optionally with files attached.\n\nMention someone with user:<accountId> followed by a space; they are\nnotified. Get the id with `hap contact resolve <name>`.",
+      "zh-Hans": "为动态添加评论，可同时附带文件。\n\n要 @ 某人，写 user:<accountId> 并在后面跟一个空格，对方会收到提醒。用 `hap contact resolve <姓名>` 查 id。"
     },
     "post comment --file": {
       "en": "Attach a file: a local path or an http(s) address. Repeat for several. Videos, pictures and documents all work.",
@@ -4512,8 +4536,8 @@
       "zh-Hans": "以 JSON 格式输出"
     },
     "post create": {
-      "en": "Create a new post in the given organization.\n\nAudience is set with --to-group / --to-org and defaults to everyone in\n--org-id when neither is given. Who can see a post is covered in\n`hap guide post audience`; the group-chat card is `hap guide post card`.\nFiles given with --file are uploaded and attached to the post.\n\nIn the message, #name# files the post under the category (topic) of\nthat name, and [aid]<accountId>[/aid] mentions a person — get the id\nwith `hap contact resolve <name>`. --dry-run lists both, with the\nmentioned names, before anything is published. Details in\n`hap guide post tags`.",
-      "zh-Hans": "在指定组织中发布一条新动态。\n\n发布范围用 --to-group / --to-org 指定，都不给时默认发给 --org-id 组织的全体同事。谁能看到动态见 `hap guide post audience`；群聊卡片见 `hap guide post card`。用 --file 指定的文件会上传并附加到动态上。\n\n正文里写 #名称# 会把动态归到同名分类（话题）下，写 [aid]<accountId>[/aid] 会提及某人——用 `hap contact resolve <姓名>` 查 id。--dry-run 会在发布前列出这两项以及被提及人的姓名。详见 `hap guide post tags`。"
+      "en": "Create a new post in the given organization.\n\nAudience is set with --to-group / --to-org and defaults to everyone in\n--org-id when neither is given. Who can see a post is covered in\n`hap guide post audience`; the group-chat card is `hap guide post card`.\nFiles given with --file are uploaded and attached to the post.\n\nIn the message, #name# files the post under the category (topic) of\nthat name, and user:<accountId> followed by a space mentions and\nnotifies a person — get the id with `hap contact resolve <name>`. --dry-run lists both, with the\nmentioned names, before anything is published. Details in\n`hap guide post tags`.",
+      "zh-Hans": "在指定组织中发布一条新动态。\n\n发布范围用 --to-group / --to-org 指定，都不给时默认发给 --org-id 组织的全体同事。谁能看到动态见 `hap guide post audience`；群聊卡片见 `hap guide post card`。用 --file 指定的文件会上传并附加到动态上。\n\n正文里写 #名称# 会把动态归到同名分类（话题）下，写 user:<accountId> 并在后面跟一个空格会提及并提醒某人——用 `hap contact resolve <姓名>` 查 id。--dry-run 会在发布前列出这两项以及被提及人的姓名。详见 `hap guide post tags`。"
     },
     "post create --card-to-group": {
       "en": "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.",