hap-cli 0.9.6__tar.gz → 0.9.8__tar.gz

{hap_cli-0.9.6 → hap_cli-0.9.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.9.6
+Version: 0.9.8
 Summary: CLI harness for Mingdao HAP - Enterprise no-code platform
 Author: hap-cli
 License: Apache-2.0
@@ -289,7 +289,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `group list` | List open groups you have joined (`--org-id`, `--keywords`, and pagination options) |
+| `group list` | List open groups you have joined (`--org-id`, `--keywords`, pagination; `has_more`/`next_page` when more exist, `--all` for every group, `--feed-only` for groups that can receive a post) |
 | `group info GROUP_ID` | Group metadata |
 | `group create` | Create a new group (`--name`, `--org-id`, optional `--member`) |
 | `group add-member` | Add one or more members (`--group-id`, `--account-id`) |

{hap_cli-0.9.6/hap_cli → hap_cli-0.9.8}/README.md

@@ -260,7 +260,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `group list` | List open groups you have joined (`--org-id`, `--keywords`, and pagination options) |
+| `group list` | List open groups you have joined (`--org-id`, `--keywords`, pagination; `has_more`/`next_page` when more exist, `--all` for every group, `--feed-only` for groups that can receive a post) |
 | `group info GROUP_ID` | Group metadata |
 | `group create` | Create a new group (`--name`, `--org-id`, optional `--member`) |
 | `group add-member` | Add one or more members (`--group-id`, `--account-id`) |

{hap_cli-0.9.6 → hap_cli-0.9.8/hap_cli}/README.md

@@ -260,7 +260,7 @@ discover every subcommand.
 
 | Command | Description |
 |---|---|
-| `group list` | List open groups you have joined (`--org-id`, `--keywords`, and pagination options) |
+| `group list` | List open groups you have joined (`--org-id`, `--keywords`, pagination; `has_more`/`next_page` when more exist, `--all` for every group, `--feed-only` for groups that can receive a post) |
 | `group info GROUP_ID` | Group metadata |
 | `group create` | Create a new group (`--name`, `--org-id`, optional `--member`) |
 | `group add-member` | Add one or more members (`--group-id`, `--account-id`) |

{hap_cli-0.9.6 → hap_cli-0.9.8}/hap_cli/README_CN.md

@@ -243,7 +243,7 @@ hap --json worksheet record list WORKSHEET_ID
 
 | 命令 | 说明 |
 |---|---|
-| `group list` | 分页列出当前用户已加入的正常群组（可用 `--org-id`、`--keywords` 筛选） |
+| `group list` | 分页列出当前用户已加入的正常群组（可用 `--org-id`、`--keywords` 筛选；还有更多时返回 `has_more`/`next_page`；`--all` 取全部；`--feed-only` 只列能发动态的群） |
 
 ### region — 行政区划
 

{hap_cli-0.9.6 → hap_cli-0.9.8}/hap_cli/__init__.py

@@ -3,7 +3,7 @@
 import sys as _sys
 import types as _types
 
-__version__ = "0.9.6"
+__version__ = "0.9.8"
 
 # 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.6 → hap_cli-0.9.8}/hap_cli/commands/group_cmd.py

@@ -18,37 +18,71 @@ def group():
 
 
 def _output_group_list(data):
-    rows = [
-        {
-            "groupId": row.get("groupId", ""),
-            "name": row.get("name") or row.get("groupName", ""),
-            "groupMemberCount": row.get("groupMemberCount", ""),
-        }
-        for row in (data or {}).get("list", [])
-    ]
+    rows = (data or {}).get("list", [])
+    with_feed = any("isPost" in row for row in rows)
+    columns = ["groupId", "name", "groupMemberCount"]
+    headers = ["Group ID", "Name", "Members"]
+    if with_feed:
+        columns.append("isPost")
+        headers.append("Feed")
     output_table(
-        rows,
-        ["groupId", "name", "groupMemberCount"],
-        ["Group ID", "Name", "Members"],
+        [
+            {
+                "groupId": row.get("groupId", ""),
+                "name": row.get("name") or row.get("groupName", ""),
+                "groupMemberCount": row.get("groupMemberCount", ""),
+                "isPost": "yes" if row.get("isPost") else "no",
+            }
+            for row in rows
+        ],
+        columns,
+        headers,
     )
+    if data.get("has_more"):
+        click.echo(
+            f"Showing {len(rows)} of {data.get('allCount')} groups. Next page: "
+            f"-p {data.get('next_page')}, or --all for every group.",
+            err=True,
+        )
 
 
 @group.command("list")
 @org_id_option()
 @click.option("--keywords", "-k", default="", help="Filter groups by name")
 @pagination_options
+@click.option("--all", "all_pages", is_flag=True,
+              help="Return every group instead of one page.")
+@click.option("--feed-only", is_flag=True,
+              help="Only groups with the feed on, which are the ones a post "
+                   "can be published to. Checks every group, so it is slower.")
 @pass_context
-def group_list(ctx, org_id, keywords, page_size, page):
-    """List open chat groups you have joined."""
+def group_list(ctx, org_id, keywords, page_size, page, all_pages, feed_only):
+    """List open chat groups you have joined.
+
+    One page at a time by default; when more exist the output says so
+    (has_more / next_page) — use --all to get every group at once.
+    """
     try:
         session = ctx.get_session()
-        data = group_mod.get_groups(
-            session,
-            project_id=require_api_project_id(session, org_id),
-            keywords=keywords,
-            page_index=page,
-            page_size=page_size,
-        )
+        project_id = require_api_project_id(session, org_id)
+        if all_pages or feed_only:
+            data = group_mod.get_all_groups(session, project_id, keywords=keywords)
+        else:
+            data = group_mod.get_groups(
+                session,
+                project_id=project_id,
+                keywords=keywords,
+                page_index=page,
+                page_size=page_size,
+            ) or {}
+            total = data.get("allCount")
+            shown = (page - 1) * page_size + len(data.get("list") or [])
+            data["has_more"] = isinstance(total, int) and shown < total
+            if data["has_more"]:
+                data["next_page"] = page + 1
+        if feed_only:
+            rows = group_mod.mark_feed_groups(session, data.get("list") or [])
+            data["list"] = [row for row in rows if row.get("isPost")]
         ctx.output(data, _output_group_list)
     except Exception as e:
         ctx.handle_error(e)

{hap_cli-0.9.6 → hap_cli-0.9.8}/hap_cli/commands/post_cmd.py

@@ -683,6 +683,50 @@ def post_get(ctx, post_id):
         ctx.handle_error(e)
 
 
+def _upload_progress(event: str, info: dict[str, Any]) -> None:
+    """One line per file on stderr, so --json output stays parseable."""
+    size = info.get("size")
+    size_text = f" ({size / 1048576:.1f} MB)" if size else ""
+    where = f"[{info['index']}/{info['total']}]"
+    if event == "start":
+        click.echo(f"Uploading {where} {info['name']}{size_text} ...", err=True)
+    elif event == "done":
+        click.echo(f"Uploaded  {where} {info['name']}{size_text} in "
+                   f"{info.get('seconds', 0):.1f}s", err=True)
+
+
+def _preview_mentions(ctx, org_id: str, message: str) -> list[dict[str, Any]]:
+    """Who a --dry-run message would mention, looked up by account id.
+
+    Only signs in when the message actually mentions someone, so a plain
+    dry run stays offline."""
+    ids = post_mod.extract_mentions(message)
+    if not ids:
+        return []
+    session = ctx.get_session()
+    names = post_mod.resolve_accounts(
+        session, require_api_project_id(session, org_id), ids)
+    return [{"accountId": i, "name": names.get(i), "found": i in names}
+            for i in ids]
+
+
+def _render_dry_run(d: dict[str, Any]) -> None:
+    line = "Would publish to: " + ", ".join(d["audience"])
+    if d["cardToGroups"]:
+        line += f"; card to groups: {', '.join(d['cardToGroups'])}"
+    if d["files"]:
+        line += f"; files: {', '.join(d['files'])}"
+    click.echo(line)
+    if d["categories"]:
+        click.echo("Categories: " + ", ".join(d["categories"]))
+    for m in d["mentions"]:
+        if m["found"]:
+            click.echo(f"Mentions: {m['name']} ({m['accountId']})")
+        else:
+            click.echo(f"Warning: no one in this organization has account id "
+                       f"{m['accountId']}; that mention will not notify anyone.")
+
+
 @post.command("create")
 @org_id_option()
 @click.option("--message", "-m", required=True, help="Post content")
@@ -732,6 +776,12 @@ def post_create(ctx, org_id, message, post_type, files, share_group_ids,
     --org-id when neither is given. Who can see a post is covered in
     `hap guide post audience`; the group-chat card is `hap guide post card`.
     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 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`.
     """
     try:
         if post_type == post_mod.POST_TYPE_ATTACHMENT and not files:
@@ -744,17 +794,14 @@ def post_create(ctx, org_id, message, post_type, files, share_group_ids,
                 [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, "files": list(files),
-                 "published": False},
-                lambda d: click.echo(
-                    "Would publish to: " + ", ".join(d["audience"])
-                    + (f"; card to groups: {', '.join(d['cardToGroups'])}"
-                       if d["cardToGroups"] else "")
-                    + (f"; files: {', '.join(d['files'])}"
-                       if d["files"] else "")),
-            )
+            preview = {"audience": audience,
+                       "cardToGroups": list(card_group_ids),
+                       "message": post_mod.mention_syntax(message),
+                       "files": list(files),
+                       "categories": post_mod.extract_topics(message),
+                       "mentions": _preview_mentions(ctx, org_id, message),
+                       "published": False}
+            ctx.output(preview, _render_dry_run)
             return
         session = ctx.get_session()
         # Only a group with the feed turned on can be a post audience. The
@@ -778,8 +825,9 @@ def post_create(ctx, org_id, message, post_type, files, share_group_ids,
                     + ". 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)
-        attachments = (post_mod.upload_post_files(session, list(files))
-                       if files else None)
+        attachments = (post_mod.upload_post_files(
+            session, list(files), progress=_upload_progress)
+            if files else None)
         raw = post_mod.add_post(
             session,
             project_id=pid,
@@ -868,11 +916,16 @@ 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(session, list(files))
-                       if files else None)
+        attachments = (post_mod.upload_post_files(
+            session, list(files), progress=_upload_progress)
+            if files else None)
         raw = post_mod.add_comment(
             session, post_id, message,
             reply_id=reply_id, reply_account_id=reply_account_id,

{hap_cli-0.9.6 → hap_cli-0.9.8}/hap_cli/core/group.py

@@ -1,10 +1,13 @@
 """Group management for Mingdao HAP."""
 
 import json
+import logging
 from typing import Any, Optional
 
 from hap_cli.core.session import Session
 
+logger = logging.getLogger("hap_cli.group")
+
 
 def get_groups(
     session: Session,
@@ -36,6 +39,46 @@ def get_groups(
     )
 
 
+def get_all_groups(
+    session: Session,
+    project_id: str,
+    keywords: str = "",
+    page_size: int = 100,
+) -> dict[str, Any]:
+    """Every page of :func:`get_groups`, as one ``{list, allCount}``.
+
+    Stops on a short page or once ``allCount`` rows are in, whichever
+    comes first, so a server that miscounts cannot loop forever.
+    """
+    rows: list[dict[str, Any]] = []
+    total = None
+    page = 1
+    while True:
+        data = get_groups(session, project_id, keywords=keywords,
+                          page_index=page, page_size=page_size) or {}
+        batch = data.get("list") or []
+        rows.extend(batch)
+        if total is None:
+            total = data.get("allCount")
+        if len(batch) < page_size or (isinstance(total, int) and len(rows) >= total):
+            break
+        page += 1
+    logger.info("group: fetched %d group(s) over %d page(s)", len(rows), page)
+    return {"list": rows, "allCount": total if total is not None else len(rows)}
+
+
+def mark_feed_groups(session: Session, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Add ``isPost`` (feed on, so the group can be a post audience) to
+    each row. ``GetGroups`` rows do not carry it — only ``GetGroupInfo``
+    does — so this costs one request per group."""
+    for row in rows:
+        info = get_group_info(session, row.get("groupId", "")) or {}
+        if isinstance(info.get("data"), dict):
+            info = info["data"]
+        row["isPost"] = bool(info.get("isPost"))
+    return rows
+
+
 def get_group_info(
     session: Session,
     group_id: str,

{hap_cli-0.9.6 → hap_cli-0.9.8}/hap_cli/core/post.py

@@ -26,7 +26,8 @@ Response envelopes (from a live probe on SaaS):
 
 import json
 import logging
-from typing import Any, Optional
+import re
+from typing import Any, Callable, Optional
 
 from hap_cli.core.session import APIError, Session
 
@@ -238,22 +239,100 @@ def _attachment_fields(attachments: list[dict[str, Any]]) -> dict[str, str]:
     }
 
 
-def upload_post_files(session: Session, sources: list[str]) -> list[dict[str, Any]]:
+def upload_post_files(
+    session: Session,
+    sources: list[str],
+    progress: Optional[Callable[[str, dict[str, Any]], None]] = None,
+) -> list[dict[str, Any]]:
     """Upload local paths / http(s) addresses and return attachment items
     for :func:`add_post` / :func:`add_comment`.
 
     No organization is named for the upload credential: the feed mounts
     its uploader without a projectId (MDPublic createFeed/
     CreateFeedContent.jsx:124-136), same as chat does here.
+    ``progress`` is handed to ``upload.upload_files`` unchanged.
     """
     from hap_cli.core import upload as upload_mod
 
     descriptors = upload_mod.upload_files(
-        session, upload_mod.source_descriptors(list(sources)))
+        session, upload_mod.source_descriptors(list(sources)),
+        progress=progress)
     logger.info("post: uploaded %d attachment(s)", len(descriptors))
     return upload_mod.attachment_items(descriptors)
 
 
+# What the feed composer writes into a post body (MDPublic
+# 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"(?<![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]:
+    """Topic names written as ``#name#`` in a post body, in order, unique."""
+    seen: list[str] = []
+    for name in _TOPIC_RE.findall(message or ""):
+        name = name.strip()
+        if name and name not in seen:
+            seen.append(name)
+    return seen
+
+
+def extract_mentions(message: str) -> list[str]:
+    """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(mention_syntax(message)):
+        if account_id not in seen:
+            seen.append(account_id)
+    return seen
+
+
+def resolve_accounts(
+    session: Session, project_id: str, account_ids: list[str],
+) -> dict[str, str]:
+    """Map account ids to display names via ``User.GetUserListByAccountId``
+    (MDPublic src/api/user.js:12). ``projectId`` is mandatory — the server
+    answers "组织编号不能为空" without it. Ids it does not know are simply
+    missing from the result."""
+    if not account_ids:
+        return {}
+    raw = session.api_call("User", "GetUserListByAccountId", {
+        "projectId": project_id, "accountIds": list(account_ids)})
+    rows = raw.get("list") if isinstance(raw, dict) else raw
+    names: dict[str, str] = {}
+    for row in rows or []:
+        if isinstance(row, dict) and row.get("accountId"):
+            names[row["accountId"]] = str(row.get("fullname") or "")
+    return names
+
+
 def add_post(
     session: Session,
     project_id: str,
@@ -306,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:
@@ -327,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(
@@ -356,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.6 → hap_cli-0.9.8}/hap_cli/core/upload.py

@@ -27,7 +27,7 @@ import random
 import re
 import time
 from datetime import datetime, timezone
-from typing import Any, Optional
+from typing import Any, Callable, Optional
 from urllib.parse import parse_qs, quote, urlparse
 
 import requests
@@ -404,11 +404,30 @@ def upload_files(
     project_id: str = "",
     bucket: Optional[int] = None,
     server_name: str = "",
+    progress: Optional[Callable[[str, dict[str, Any]], None]] = None,
 ) -> list[dict[str, Any]]:
     """Upload a list of ``{name?, url}`` / ``{name?, path}`` descriptors and
-    return one uploaded-file descriptor per file (order preserved)."""
+    return one uploaded-file descriptor per file (order preserved).
+
+    ``progress(event, info)`` is called with ``"start"`` before each file
+    and ``"done"`` after it; ``info`` carries ``index`` (1-based),
+    ``total``, ``name``, ``size`` (bytes, ``None`` for a URL not yet
+    fetched) and, on ``"done"``, ``seconds``. Large videos take a while
+    and the caller has nothing else to show in the meantime.
+    """
     out: list[dict[str, Any]] = []
-    for f in files:
+    total = len(files)
+    for index, f in enumerate(files, start=1):
+        label = f.get("name") or os.path.basename(f.get("path") or f.get("url") or "")
+        size = None
+        if f.get("path") and not f.get("url"):
+            try:
+                size = os.path.getsize(f["path"])
+            except OSError:
+                size = None
+        info = {"index": index, "total": total, "name": label, "size": size}
+        _report(progress, "start", info)
+        started = time.monotonic()
         url = f.get("url")
         path = f.get("path")
         if url:
@@ -424,9 +443,20 @@ def upload_files(
             session, content=content, name=name, worksheet_id=worksheet_id,
             app_id=app_id, project_id=project_id, bucket=bucket,
             server_name=server_name))
+        _report(progress, "done", {**info, "name": name, "size": len(content),
+                                   "seconds": time.monotonic() - started})
     return out
 
 
+def _report(progress, event: str, info: dict[str, Any]) -> None:
+    if progress is None:
+        return
+    try:
+        progress(event, info)
+    except Exception as exc:
+        logger.warning("Upload progress callback failed: %s", exc)
+
+
 def attachment_items(descriptors: list[dict[str, Any]]) -> list[dict[str, Any]]:
     """Uploaded-file descriptors as the attachment items the uploader hands
     to whatever it is attached to — the ``formatResponseData`` shape

{hap_cli-0.9.6 → hap_cli-0.9.8}/hap_cli/guide/en/post.md

@@ -41,7 +41,8 @@ audience. Naming a `--to-group` does **not** additionally publish company-wide.
 A plain chat group cannot receive a post. The server refuses with
 "选择了没有加入的群组" (you picked a group you have not joined), which is
 **misleading** — you are in the group; it simply has no feed. The CLI checks
-first and names the group instead. To check one: `hap group info <groupId>`
+first and names the group instead. To list every group that can receive a
+post: `hap group list --feed-only`. To check one: `hap group info <groupId>`
 and look at `isPost`. To merely drop a link into such a group, use
 `--card-to-group` below.
 
@@ -90,12 +91,26 @@ remove it too, recall that message with
 `hap chat recall <messageId> --group-id <groupId>` (your own messages within 5
 minutes of sending; a group admin can recall a member's message with no limit).
 
-## 3. Topic tags
-<!-- hook: Writing #tag# in the body registers a topic; hap post topics lists what is available. -->
+## 3. Categories and mentions in the body
+<!-- hook: #name# in the body sets the post's category; user:<accountId> mentions and notifies a person; --dry-run previews both. -->
 <!-- alias: tags -->
 
-Writing `#tag#` in the body registers a topic (for example `#今日工作#`), which
-shows up in the post's categories. List available topics with `hap post topics`.
+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 `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 "#今日工作# 今天和 user:<accountId> 对齐了方案" --dry-run
+```
+
+A published post's audience cannot be changed, so check with `--dry-run`
+first: it lists the categories and each mention with the person's name, and
+warns about an id that matches nobody in the organization.
 
 ## 4. Other common commands
 <!-- hook: Listing, searching, reading, commenting on and deleting posts, plus what post search --scope accepts. -->

{hap_cli-0.9.6 → hap_cli-0.9.8}/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.",
-        "zh-Hans": "发布范围决定谁能看到，且无法从旧动态读出来。"
+        "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.6 → hap_cli-0.9.8}/hap_cli/guide/zh-Hans/post.md

@@ -37,6 +37,7 @@ hap post create -m "内容" --to-org fe288386-xxxx
 
 纯聊天群不能接收动态。服务端对此的报错是「选择了没有加入的群组」，**具有误导性**
 ——你明明在群里，真实原因是这个群没开启动态功能。CLI 会先行检查并直接报出群名。
+列出所有能发动态的群：`hap group list --feed-only`。
 想查某个群是否可用：`hap group info <群组ID>`，看 `isPost` 是否为 true。
 只是想在这种群里贴个链接，用下面的 `--card-to-group`。
 
@@ -78,12 +79,23 @@ hap post create -m "内容" --to-group 9ccde712-xxxx --card-to-group 7f694ec7-xx
 指向一条已不存在的动态。要一并清掉，用 `hap chat recall <消息ID> --group-id <群组ID>`
 撤回那条卡片消息（自己的消息限发送后 5 分钟内，群管理员撤回他人消息不限时）。
 
-## 3. 话题标签
-<!-- hook: 正文里写 #标签# 会登记话题，可用话题用 hap post topics 看 -->
+## 3. 正文里的分类与 @提及
+<!-- hook: 正文 #名称# 定分类，user:id 提及并通知某人，--dry-run 可预览 -->
 <!-- alias: tags -->
 
-正文里写 `#标签#` 会被识别为话题（例如 `#今日工作#`），发布后出现在动态的
-分类里。可用的话题用 `hap post topics` 查。
+没有设置分类的选项：**分类由正文决定。** 正文里写 `#名称#`（例如 `#今日工作#`），
+动态就会归到同名分类下，分类不存在时会自动新建。已有分类用 `hap post topics` 查。
+
+要 @ 某人，在想出现「@姓名」的位置写 `user:<accountId>`，后面跟一个空格，对方会收到提醒。
+`hap post comment` 里写法相同。先用姓名查出 id：
+
+```bash
+hap contact resolve 刘禹            # candidates[].id 就是 accountId
+hap post create -m "#今日工作# 今天和 user:<accountId> 对齐了方案" --dry-run
+```
+
+动态发出后范围无法再改，所以先用 `--dry-run` 检查：它会列出分类，以及每个
+提及对应的姓名；某个 id 在组织里找不到人时会给出警告。
 
 ## 4. 其它常用
 <!-- hook: 动态的列表、搜索、读取、评论、删除，以及 search --scope 接受哪些值 -->