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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.9.5
+Version: 0.9.7
 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`) |
@@ -339,6 +339,7 @@ discover every subcommand.
 | `config completion [bash\|zsh\|fish] [--install]` | Enable `<Tab>` completion |
 | `config language [LANG]` | Switch UI language (`en` / `zh-Hans`, or `auto` to follow the account language) |
 | `config update [auto\|notify\|off]` | Self-upgrade mode; `notify` only reports, `off` never checks |
+| `config auto-login [on\|off]` | Renew an expired login in the browser (one click on Authorize) and carry on; `off` stops with "not logged in" |
 | `config log on / off / status` | Toggle and inspect API logging |
 | `config log level LEVEL` | `DEBUG / INFO / WARNING / ERROR / CRITICAL` |
 | `config log view [--lines N] [--no-follow]` | Tail the log file |

{hap_cli-0.9.5/hap_cli → hap_cli-0.9.7}/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`) |
@@ -310,6 +310,7 @@ discover every subcommand.
 | `config completion [bash\|zsh\|fish] [--install]` | Enable `<Tab>` completion |
 | `config language [LANG]` | Switch UI language (`en` / `zh-Hans`, or `auto` to follow the account language) |
 | `config update [auto\|notify\|off]` | Self-upgrade mode; `notify` only reports, `off` never checks |
+| `config auto-login [on\|off]` | Renew an expired login in the browser (one click on Authorize) and carry on; `off` stops with "not logged in" |
 | `config log on / off / status` | Toggle and inspect API logging |
 | `config log level LEVEL` | `DEBUG / INFO / WARNING / ERROR / CRITICAL` |
 | `config log view [--lines N] [--no-follow]` | Tail the log file |

{hap_cli-0.9.5 → hap_cli-0.9.7/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`) |
@@ -310,6 +310,7 @@ discover every subcommand.
 | `config completion [bash\|zsh\|fish] [--install]` | Enable `<Tab>` completion |
 | `config language [LANG]` | Switch UI language (`en` / `zh-Hans`, or `auto` to follow the account language) |
 | `config update [auto\|notify\|off]` | Self-upgrade mode; `notify` only reports, `off` never checks |
+| `config auto-login [on\|off]` | Renew an expired login in the browser (one click on Authorize) and carry on; `off` stops with "not logged in" |
 | `config log on / off / status` | Toggle and inspect API logging |
 | `config log level LEVEL` | `DEBUG / INFO / WARNING / ERROR / CRITICAL` |
 | `config log view [--lines N] [--no-follow]` | Tail the log file |

{hap_cli-0.9.5 → hap_cli-0.9.7}/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 — 行政区划
 
@@ -289,6 +289,7 @@ hap --json worksheet record list WORKSHEET_ID
 | `config completion [bash\|zsh\|fish] [--install]` | 启用 `<Tab>` 补全 |
 | `config language [LANG]` | 切换显示语言（`en` / `zh-Hans`；`auto` 跟随登录账号的语言） |
 | `config update [auto\|notify\|off]` | 自动升级开关；`notify` 只提示不安装，`off` 不检查 |
+| `config auto-login [on\|off]` | 登录过期时自动打开浏览器授权页，点一下「授权」命令继续执行；`off` 则直接报未登录 |
 | `config log on / off / status` | 日志开关与状态 |
 | `config log level LEVEL` | 设置日志级别（`DEBUG/INFO/WARNING/ERROR/CRITICAL`） |
 | `config log view [--lines N] [--no-follow]` | 跟踪日志文件 |

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

@@ -3,7 +3,7 @@
 import sys as _sys
 import types as _types
 
-__version__ = "0.9.5"
+__version__ = "0.9.7"
 
 # 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.5 → hap_cli-0.9.7}/hap_cli/commands/config_cmd.py

@@ -126,6 +126,7 @@ def config_completion(shell, install):
 @pass_context
 def config_show(ctx):
     """Display current harness configuration."""
+    from hap_cli.core.relogin import get_mode as get_auto_login_mode
     from hap_cli.core.update import get_update_mode
 
     log_cfg = load_logging_config()
@@ -136,6 +137,7 @@ def config_show(ctx):
             "file": str(resolve_log_path(log_cfg)),
         },
         "update": get_update_mode(),
+        "auto_login": get_auto_login_mode(),
     }
 
     def _human(d):
@@ -144,6 +146,7 @@ def config_show(ctx):
         click.echo(f"  level   : {d['logging']['level']}")
         click.echo(f"  file    : {d['logging']['file']}")
         click.echo(f"update    : {d['update']}")
+        click.echo(f"auto-login: {d['auto_login']}")
 
     ctx.output(data, _human)
 
@@ -253,6 +256,45 @@ def config_update(ctx, mode):
         click.echo(f"Self-update set to: {mode}")
 
 
+# ── `hap config auto-login` ───────────────────────────────────────────────
+
+
+@config.command("auto-login")
+@click.argument("mode", required=False, type=click.Choice(["on", "off"]))
+@pass_context
+def config_auto_login(ctx, mode):
+    """Control whether an expired login is renewed in the browser.
+
+    \b
+      on   when a command finds your login expired, open the browser
+           authorization page, wait for you to click Authorize, then
+           carry on (default)
+      off  stop with a "not logged in" error instead
+
+    Without an argument, shows the current setting. It never applies over
+    SSH, in CI, or where no browser can be shown. Setting the environment
+    variable HAP_AUTO_LOGIN=0 turns it off for one shell.
+    """
+    from hap_cli.core.relogin import CONFIG_KEY, get_mode
+    from hap_cli.core.session import save_config
+
+    if mode is None:
+        current = get_mode()
+        if ctx.json_mode:
+            from hap_cli.utils.formatting import output_json
+            output_json({"auto_login": current})
+        else:
+            click.echo(f"Auto-login: {current}")
+        return
+
+    save_config({CONFIG_KEY: mode})
+    if ctx.json_mode:
+        from hap_cli.utils.formatting import output_json
+        output_json({"status": "ok", "auto_login": mode})
+    else:
+        click.echo(f"Auto-login set to: {mode}")
+
+
 # ── `hap config language` ─────────────────────────────────────────────────
 
 

{hap_cli-0.9.5 → hap_cli-0.9.7}/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.5 → hap_cli-0.9.7}/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 [aid]<accountId>[/aid] mentions 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,13 @@ 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": 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 +824,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,
@@ -871,8 +918,9 @@ def post_comment(ctx, post_id, message, reply_id, reply_account_id, files):
     """Add a comment to a post, optionally with files attached."""
     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.5 → hap_cli-0.9.7}/hap_cli/context.py

@@ -20,6 +20,27 @@ NOT_LOGGED_IN_HINT = (
 )
 
 
+def _relogin_notice(login_url: str, timeout: int) -> None:
+    """Tell the user an authorization page is waiting for one click.
+
+    Written to stderr so ``--json`` output on stdout stays parseable; the
+    desktop notification is for callers (AI agents) whose terminal output
+    the user only sees after the command ends.
+    """
+    from hap_cli.core.relogin import desktop_notify
+    from hap_cli.i18n import t
+
+    click.echo(
+        t("Your HAP login has expired. A browser page is open — click "
+          "Authorize (授权) to continue (waiting up to {seconds}s).").format(
+            seconds=timeout),
+        err=True,
+    )
+    click.echo(f"  {login_url}", err=True)
+    desktop_notify(t("Login expired — click Authorize (授权) in the browser "
+                     "to let the command continue."))
+
+
 class Context:
     """Shared CLI context."""
 
@@ -43,6 +64,7 @@ class Context:
         """
         if self.session is None:
             self.session = Session.load(self.profile)
+            self.session.relogin_notice = _relogin_notice
             # One-time migration for sessions logged in before account_id
             # was persisted. Some HAP controllers (notably
             # Invitation/InviteUser) silently degrade when the AccountId
@@ -55,7 +77,10 @@ class Context:
             ):
                 self.session._lazy_resolve_account_id()
         if require_auth and not self.session.auth_token:
-            raise SessionError("Not logged in. Run 'hap auth login' first.")
+            # A saved environment without a token: authorize it again in
+            # the browser rather than stopping the command.
+            if not (self.session.login_url and self.session.recover_auth()):
+                raise SessionError("Not logged in. Run 'hap auth login' first.")
         return self.session
 
     def output(self, data, table_fn=None):

{hap_cli-0.9.5 → hap_cli-0.9.7}/hap_cli/core/chat.py

@@ -48,26 +48,43 @@ def _chatmq_get(
     # mirror the other transport hooks.
     from hap_cli.core import cli_access
 
+    from hap_cli.core.session import AuthenticationError
+
     cli_access.ensure_before_request(session, url)
-    headers = {
-        "Authorization": f"md_pss_id {session.auth_token}",
-        "X-Requested-With": "XMLHttpRequest",
-        "User-Agent": hap_user_agent(),
-    }
-    auth_for_log = redact_authorization(headers["Authorization"])
-    logger.info(
-        "HAP GET %s params=%s Authorization=%s",
-        url,
-        format_body_for_log(params) or "{}",
-        auth_for_log,
-    )
-    response = requests.get(url, params=params, headers=headers, timeout=timeout)
-    logger.info(
-        "HAP GET %s -> %d %s",
-        url,
-        response.status_code,
-        format_response_for_log(getattr(response, "text", "") or ""),
-    )
+
+    def _send():
+        headers = {
+            "Authorization": f"md_pss_id {session.auth_token}",
+            "X-Requested-With": "XMLHttpRequest",
+            "User-Agent": hap_user_agent(),
+        }
+        auth_for_log = redact_authorization(headers["Authorization"])
+        logger.info(
+            "HAP GET %s params=%s Authorization=%s",
+            url,
+            format_body_for_log(params) or "{}",
+            auth_for_log,
+        )
+        response = requests.get(url, params=params, headers=headers, timeout=timeout)
+        logger.info(
+            "HAP GET %s -> %d %s",
+            url,
+            response.status_code,
+            format_response_for_log(getattr(response, "text", "") or ""),
+        )
+        return response
+
+    response = _send()
+    # An expired login gets the same one-shot browser re-authorization as
+    # the main transport (Session._post); the read is then resent once.
+    if response.status_code == 401:
+        if not session.recover_auth():
+            raise AuthenticationError(
+                "Authentication failed (HTTP 401). "
+                "Your session token is missing, invalid, or expired.",
+                status_code=401,
+            )
+        response = _send()
     response.raise_for_status()
     return response.json()
 

{hap_cli-0.9.5 → hap_cli-0.9.7}/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.5 → hap_cli-0.9.7}/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,78 @@ 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). 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.
+_TOPIC_RE = re.compile(r"[#＃]([^#＃\n]+?)[#＃]")
+_MENTION_RE = re.compile(r"\[aid\]([^\[\]]+?)\[/aid\]")
+
+
+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 written as ``[aid]<id>[/aid]`` in a post body, 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:
+            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,