aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/apps/cli/commands/business_workflow_cmds.py

@@ -0,0 +1,379 @@
+"""BusinessWorkflowCommandsMixin — research, earnings, realty, ops workflow commands."""
+
+from __future__ import annotations
+
+from aria_code.apps.cli.i18n import ui_text
+
+from ._business_render import p, print_realty_result, print_risk_scan
+
+
+import json
+import asyncio
+import datetime
+import time
+import shlex
+from typing import Dict, Any, Optional
+
+
+import json
+import asyncio
+import datetime
+import time
+import shlex
+import sys
+import os
+from typing import Dict, Any, Optional
+
+
+import json
+import asyncio
+import datetime
+import time
+import shlex
+import sys
+import os
+from typing import Dict, Any, Optional
+
+
+class BusinessWorkflowCommandsMixin:
+    """Mixin: financial research and realty/operations workflow commands."""
+
+    async def cmd_research(self, args: str):
+        sym = args.strip().upper() or "AAPL"
+        # Route research through the deterministic team workflow so data
+        # fetching, rendering, and artifact saving happen in one service path.
+        await self.cmd_team(f"{sym} --full")
+
+    async def cmd_earnings_workflow(self, args: str):
+        """/earnings SYMBOL — the earnings themselves; --report writes the Markdown report."""
+        parts = args.strip().split()
+        sym = next((t.upper() for t in parts if not t.startswith("--")), "AAPL")
+        if "--report" in parts:
+            period = " ".join(t for t in parts[1:] if not t.startswith("--")) or "最近一个季度"
+            report_type = "deep" if any(k in period.lower() for k in ("deep", "深度", "全年", "年报", "10-k")) else "standard"
+            await self.cmd_report(f"{sym} --format md --type {report_type}")
+            return
+        from aria_code.apps.cli.earnings_view import fetch_earnings, render_earnings
+
+        lang = "zh" if str(self.terminal.config.get("ui_lang", "en")).lower().startswith("zh") else "en"
+        status = ui_text(self, f"获取 {sym} 财报数据", f"Fetching {sym} earnings")
+        if self.context.has_rich:
+            with self.context.console.status(f"[dim]{status}…[/dim]", spinner="dots"):
+                data = await asyncio.get_event_loop().run_in_executor(None, fetch_earnings, sym)
+        else:
+            data = await asyncio.get_event_loop().run_in_executor(None, fetch_earnings, sym)
+        if not data.get("success"):
+            from ._ui import print_error
+            print_error(self.context, data.get("error", "No earnings data"),
+                        ui_text(self, f"可以试试 /report {sym}", f"Try /report {sym} instead"))
+            return
+        if self.context.has_rich:
+            render_earnings(data, self.context.console, lang)
+        else:
+            for row in data.get("history", []):
+                print(f"  {row['date']}  est {row.get('estimate')}  actual {row['reported']}  "
+                      f"surprise {row.get('surprise_pct')}")
+
+    async def cmd_asset_diag(self, args: str):
+        asset_id = args.strip()
+        if not asset_id:
+            p(self.context, "用法: /asset-diag <资产ID或名称>  例: /asset-diag asset_000001", "dim")
+            return
+        asset_info = {}
+        api_url = self.terminal.config.get("api_url", "http://localhost:8000")
+        try:
+            import aiohttp
+            async with aiohttp.ClientSession(trust_env=True) as sess:
+                async with sess.get(
+                    f"{api_url}/api/realty/assets/{asset_id}",
+                    timeout=aiohttp.ClientTimeout(total=5)
+                ) as resp:
+                    if resp.status == 200:
+                        body = await resp.json()
+                        raw = body.get("data", {})
+                        asset_info = {
+                            "area": raw.get("area_sqm", 0),
+                            "location": raw.get("address", asset_id),
+                            "vacancy_days": raw.get("vacancy_days", 0),
+                            "expected_rent": raw.get("monthly_rent_market", 0),
+                            "allowed_business": raw.get("allowed_business_types", []),
+                            "property_state": raw.get("property_state", "正常"),
+                            "floor_height": raw.get("floor_height", 0),
+                        }
+                        p(self.context, f"已从 API 加载资产: {raw.get('name', asset_id)}", "ok")
+        except Exception:
+            pass
+        if not asset_info:
+            self._realty_needs(asset_id, "Usage: /asset-diag <asset_id>")
+            return
+        await self._run_realty_agent("asset_diagnosis", asset_id, {"asset_info": asset_info})
+
+    async def cmd_contract_draft(self, args: str):
+        parts = args.split() if args else []
+        project_id = parts[0] if parts and not parts[0].startswith("--") else ""
+        nego = {"guaranteed_amount": 0, "revenue_share_pct": 0}
+        for i, p in enumerate(parts):
+            if p == "--guaranteed" and i + 1 < len(parts):
+                try:
+                    nego["guaranteed_amount"] = float(parts[i + 1])
+                except ValueError:
+                    pass
+            elif p == "--share" and i + 1 < len(parts):
+                try:
+                    nego["revenue_share_pct"] = float(parts[i + 1])
+                except ValueError:
+                    pass
+        if not project_id or not (nego["guaranteed_amount"] or nego["revenue_share_pct"]):
+            from ._ui import print_error
+            print_error(self.context,
+                        ui_text(self, "起草合同需要项目 ID 和至少一项条款。", "A draft needs a project ID and at least one term."),
+                        "Usage: /contract-draft <project_id> --guaranteed 30000 --share 10")
+            return
+        await self._run_realty_agent("contract_rules", project_id, {
+            "negotiation": nego,
+            "asset_info": {"name": project_id},
+            "operator_info": {},
+        })
+
+    async def cmd_revenue_calc(self, args: str):
+        parts = args.split() if args else []
+        if len(parts) < 2:
+            p(self.context, "用法: /revenue-calc <project_id> <总流水> [退款]  例: /revenue-calc proj_001 200000", "dim")
+            return
+        project_id = parts[0]
+        try:
+            gross = float(parts[1])
+            refunds = float(parts[2]) if len(parts) > 2 else 0.0
+        except ValueError:
+            p(self.context, "流水金额必须为数字", "error")
+            return
+        api_url = self.terminal.config.get("api_url", "http://localhost:8000")
+        rules = {}
+        try:
+            import aiohttp
+            async with aiohttp.ClientSession(trust_env=True) as sess:
+                async with sess.get(f"{api_url}/api/realty/contracts/{project_id}",
+                                    timeout=aiohttp.ClientTimeout(total=5)) as resp:
+                    if resp.status == 200:
+                        body = await resp.json()
+                        rules = body.get("data", {})
+        except Exception:
+            pass
+        if not rules:
+            self._realty_needs(project_id, "Usage: /revenue-calc <project_id> <gross> [refunds]")
+            return
+        await self._run_realty_agent("revenue_share", project_id, {
+            "contract_rules": rules,
+            "transaction_data": {"gross_revenue": gross, "refunds": refunds},
+        })
+
+    async def cmd_realty_risk_scan(self, args: str):
+        project_id = args.strip()
+        if not project_id:
+            self._realty_needs(None, "Usage: /risk-scan <project_id>")
+            return
+        if self.context.has_rich:
+            self.context.console.print(f"\n  [bold]{ui_text(self, '风险扫描', 'Risk scan')}[/bold]  "
+                                       f"{ui_text(self, '项目', 'project')}: [cyan]{project_id}[/cyan]")
+        api_url = self.terminal.config.get("api_url", "http://localhost:8000")
+        try:
+            import aiohttp
+            async with aiohttp.ClientSession(trust_env=True) as sess:
+                async with sess.get(
+                    f"{api_url}/api/realty/risks/scan/{project_id}",
+                    timeout=aiohttp.ClientTimeout(total=10)
+                ) as resp:
+                    if resp.status == 200:
+                        data = await resp.json()
+                        print_risk_scan(self.context, data)
+                        return
+        except Exception:
+            pass
+        # Running the team on {} produced findings about a project it knew
+        # nothing of.
+        self._realty_needs(project_id, "Usage: /risk-scan <project_id>")
+
+    async def cmd_ops_report(self, args: str):
+        project_id = args.strip()
+        if not project_id:
+            self._realty_needs(None, "Usage: /ops-report <project_id>")
+            return
+        api_url = self.terminal.config.get("api_url", "http://localhost:8000")
+        project_info = {"name": project_id, "area": 0, "business_type": "未知"}
+        performance_data = {}
+        marketing_data = {}
+        try:
+            import aiohttp
+            async with aiohttp.ClientSession(trust_env=True) as sess:
+                async with sess.get(
+                    f"{api_url}/api/realty/assets/{project_id}",
+                    timeout=aiohttp.ClientTimeout(total=5)
+                ) as resp:
+                    if resp.status == 200:
+                        raw = (await resp.json()).get("data", {})
+                        project_info = {
+                            "name": raw.get("name", project_id),
+                            "area": raw.get("area_sqm", 0),
+                            "business_type": raw.get("current_business_type", "未知"),
+                            "open_date": raw.get("open_date", ""),
+                        }
+                async with sess.get(
+                    f"{api_url}/api/realty/revenue/splits?project_id={project_id}&page_size=3",
+                    timeout=aiohttp.ClientTimeout(total=5)
+                ) as resp2:
+                    if resp2.status == 200:
+                        splits = (await resp2.json()).get("data", {}).get("splits", [])
+                        if splits:
+                            revenues = [s["split_result"].get("gross_revenue", 0) for s in splits]
+                            avg_rev = sum(revenues) / len(revenues)
+                            performance_data = {"monthly_revenue": avg_rev, "daily_visits": 0}
+                            p(self.context, f"已加载近 {len(splits)} 期分账数据，月均流水 {avg_rev:,.0f}元", "ok")
+        except Exception:
+            pass
+        if not performance_data:
+            self._realty_needs(project_id, "Usage: /ops-report <project_id>")
+            return
+        await self._run_realty_agent("ops_optimize", project_id, {
+            "project_info": project_info,
+            "performance_data": performance_data,
+            "marketing_data": marketing_data,
+            "peer_benchmarks": {"revenue_per_sqm": 300},
+        })
+
+    async def cmd_exit_calc(self, args: str):
+        parts = args.split() if args else []
+        project_id = parts[0] if parts and not parts[0].startswith("--") else ""
+        if not project_id:
+            self._realty_needs(None, "Usage: /exit-calc <project_id> [--reason …]")
+            return
+        contract_loaded = False
+        reason = "到期终止"
+        for i, p in enumerate(parts):
+            if p == "--reason" and i + 1 < len(parts):
+                reason = " ".join(parts[i + 1:])
+                break
+        api_url = self.terminal.config.get("api_url", "http://localhost:8000")
+        project_info = {"name": project_id}
+        financials = {"deposit_amount": 0, "unpaid_invoices": 0,
+                      "guaranteed_monthly": 0, "exit_penalty_months": 3,
+                      "prepayment_received": 0, "renovation_cost": 0}
+        try:
+            import aiohttp
+            async with aiohttp.ClientSession(trust_env=True) as sess:
+                async with sess.get(
+                    f"{api_url}/api/realty/contracts/{project_id}",
+                    timeout=aiohttp.ClientTimeout(total=5)
+                ) as resp:
+                    if resp.status == 200:
+                        ctr = (await resp.json()).get("data", {})
+                        from datetime import date
+                        start = ctr.get("start_date", "")
+                        used_months = 0
+                        if start:
+                            try:
+                                from dateutil.relativedelta import relativedelta
+                                d0 = date.fromisoformat(start)
+                                delta = relativedelta(date.today(), d0)
+                                used_months = delta.years * 12 + delta.months
+                            except Exception:
+                                pass
+                        project_info.update({
+                            "contract_years": ctr.get("contract_years", 1),
+                            "used_months": used_months,
+                            "contract_end": ctr.get("end_date", ""),
+                        })
+                        financials.update({
+                            "deposit_amount": ctr.get("deposit_amount", 0),
+                            "guaranteed_monthly": ctr.get("guaranteed_monthly", 0),
+                            "exit_penalty_months": ctr.get("exit_penalty_months", 3),
+                        })
+                        contract_loaded = True
+                        p(self.context, f"已加载合同规则: 保底 {ctr.get('guaranteed_monthly',0):,}元/月", "ok")
+                async with sess.get(
+                    f"{api_url}/api/realty/invoices?project_id={project_id}&status=unpaid",
+                    timeout=aiohttp.ClientTimeout(total=5)
+                ) as resp2:
+                    if resp2.status == 200:
+                        body2 = await resp2.json()
+                        summary = body2.get("data", {}).get("summary", {})
+                        unpaid = summary.get("total_amount", 0) - summary.get("paid_amount", 0)
+                        financials["unpaid_invoices"] = unpaid
+                        if unpaid > 0:
+                            p(self.context, f"发现未结账单合计: {unpaid:,.2f}元", "ok")
+        except Exception:
+            pass
+        if not contract_loaded:
+            self._realty_needs(project_id, "Usage: /exit-calc <project_id> [--reason …]")
+            return
+        await self._run_realty_agent("exit_settlement", project_id, {
+            "project_info": project_info,
+            "financials": financials,
+            "asset_condition": {},
+            "exit_reason": reason,
+        })
+
+    def _realty_needs(self, project_id: str | None, usage: str) -> bool:
+        """Say what is missing and return True when a realty command has nothing to work on.
+
+        These commands ran their agents on "demo_project", zeros or a made-up
+        contract (30,000 a month, 10% share) when the Arthera realty backend
+        had nothing, and the agent then gave a verdict: /ops-report called a
+        project with no data "very high risk" with "member repurchase rate
+        is low".
+        """
+        if project_id:
+            msg = ui_text(self, f"没有找到 {project_id} 的数据：这项功能读取 Arthera 不动产后端里的项目数据，"
+                                f"没有数据就不做分析。",
+                          f"No data found for {project_id}: this reads project data from the Arthera realty "
+                          f"backend and does not analyse without it.")
+        else:
+            msg = ui_text(self, "需要项目 ID。", "A project ID is needed.")
+        from ._ui import print_error
+        print_error(self.context, msg, usage)
+        return True
+
+    async def _run_realty_agent(self, agent_name: str, project_id: str, input_data: dict):
+        if self.context.has_rich:
+            with self.context.console.status(f"[dim]{ui_text(self, f'运行 {agent_name} Agent', f'Running the {agent_name} agent')}...[/dim]", spinner="dots"):
+                result = await self._call_realty_agent(agent_name, project_id, input_data)
+        else:
+            print(f"Running {agent_name}...")
+            result = await self._call_realty_agent(agent_name, project_id, input_data)
+        if result:
+            print_realty_result(self.context, result, agent_name)
+
+    async def _run_realty_team(self, agents: list, project_id: str, input_data: dict):
+        import asyncio
+        if self.context.has_rich:
+            _names = ', '.join(agents)
+            with self.context.console.status(f"[dim]{ui_text(self, f'并行扫描 {_names}', f'Scanning {_names} in parallel')}...[/dim]", spinner="dots"):
+                tasks = [self._call_realty_agent(n, project_id, input_data) for n in agents]
+                results = await asyncio.gather(*tasks, return_exceptions=False)
+        else:
+            tasks = [self._call_realty_agent(n, project_id, input_data) for n in agents]
+            results = await asyncio.gather(*tasks, return_exceptions=False)
+        for res, name in zip(results, agents):
+            if res:
+                print_realty_result(self.context, res, name)
+
+    async def _call_realty_agent(self, agent_name: str, project_id: str, input_data: dict):
+        try:
+            from agents.registry import get_registry
+            cls = get_registry().get(agent_name)
+            if not cls:
+                p(self.context, f"Agent '{agent_name}' 未注册", "error")
+                return None
+            llm = None
+            try:
+                from providers.llm.registry import list_available_providers, get_provider
+                avail = [p for p in list_available_providers() if p.get("available")]
+                if avail:
+                    llm = get_provider(avail[0]["name"])
+            except Exception:
+                pass
+            agent = cls(llm_provider=llm)
+            result = await agent.analyze(project_id, input_data)
+            return result
+        except Exception as e:
+            p(self.context, f"Agent {agent_name} 执行失败: {e}", "error")
+            return None

aria_code/apps/cli/commands/canvas_cmds.py

@@ -0,0 +1,77 @@
+"""CanvasCommandsMixin — /canvas command (live artifact preview server).
+
+Extracted following the same convention as broker_cmds.py/backtest_cmds.py:
+module globals (self.context.has_rich, self.context.console, etc.) are imported lazily inside each
+method body to avoid circular imports at load time.
+"""
+
+from __future__ import annotations
+
+from ._ui import print_error
+
+
+import json
+import asyncio
+import datetime
+import time
+import shlex
+import sys
+import os
+from typing import Dict, Any, Optional
+
+
+import json
+import asyncio
+import datetime
+import time
+import shlex
+import sys
+import os
+from typing import Dict, Any, Optional
+
+
+class CanvasCommandsMixin:
+    """Mixin providing the /canvas live-preview-server command.
+
+    Off by default — nothing in preview_server.py runs until this command
+    is explicitly typed. See preview_server.py's module docstring for why
+    this stays opt-in rather than auto-starting.
+    """
+
+    async def cmd_canvas(self, args: str):
+        """实时预览面板: /canvas [stop] —— 启动/停止本地预览服务器，报告和图表生成后会自动在浏览器里实时更新。"""
+
+
+        sub = args.strip().lower()
+        import preview_server
+
+        if sub == "stop":
+            session = preview_server.get_active_session()
+            if session is None:
+                msg = "预览服务器未在运行"
+                self.context.console.print(f"[yellow]{msg}[/yellow]") if self.context.has_rich else print(msg)
+                return
+            await preview_server.stop_session()
+            msg = "✓ 已停止预览服务器"
+            self.context.console.print(f"[green]{msg}[/green]") if self.context.has_rich else print(msg)
+            return
+
+        existing = preview_server.get_active_session()
+        if existing is not None and existing.url:
+            msg = f"预览服务器已在运行: {existing.url}"
+            self.context.console.print(f"[cyan]{msg}[/cyan]") if self.context.has_rich else print(msg)
+            return
+
+        try:
+            session = await preview_server.start_session()
+        except Exception as exc:
+            print_error(self.context, f"预览服务器启动失败: {exc}", "换个端口范围或检查网络配置后重试")
+            return
+
+        preview_server.open_in_browser(session.url)
+        msg = (
+            f"✓ 预览服务器已启动: {session.url}\n"
+            f"之后生成的报告/图表会自动在这个浏览器标签里实时更新，无需手动刷新。\n"
+            f"/canvas stop 可以随时关闭。"
+        )
+        self.context.console.print(f"[green]{msg}[/green]") if self.context.has_rich else print(msg)

aria_code/apps/cli/commands/catalog.py

@@ -0,0 +1,189 @@
+"""Shared CLI command metadata.
+
+This module is intentionally UI-free so future channel adapters such as Feishu
+or a local gateway can reuse the same command categories without importing the
+large terminal implementation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import FrozenSet, Tuple
+
+
+@dataclass(frozen=True)
+class DirectCommandSpec:
+    name: str
+    method_name: str
+    async_method: bool = False
+    watchable: bool = False
+    aliases: Tuple[str, ...] = ()
+
+    @property
+    def names(self) -> Tuple[str, ...]:
+        return (self.name, *self.aliases)
+
+
+DIRECT_COMMANDS: Tuple[DirectCommandSpec, ...] = (
+    DirectCommandSpec("quote", "cmd_quote", async_method=True, watchable=True),
+    DirectCommandSpec("backtest", "cmd_backtest", async_method=True),
+    DirectCommandSpec("health", "cmd_health", async_method=True, watchable=True),
+    DirectCommandSpec("doctor", "cmd_doctor"),
+    DirectCommandSpec("tools", "cmd_tools"),
+    DirectCommandSpec("skills", "cmd_skills"),
+    DirectCommandSpec("sessions", "cmd_sessions"),
+    DirectCommandSpec("watch", "cmd_watch", aliases=("watchlist",)),
+    DirectCommandSpec("export", "cmd_export", async_method=True),
+    DirectCommandSpec("tv", "cmd_tv", async_method=True),
+    DirectCommandSpec("ashare", "cmd_ashare", async_method=True, aliases=("a-share",)),
+    DirectCommandSpec("markets", "cmd_markets"),
+    DirectCommandSpec("orchestrate", "cmd_orchestrate"),
+)
+
+
+DIRECT_COMMAND_MAP = {
+    alias: spec
+    for spec in DIRECT_COMMANDS
+    for alias in spec.names
+}
+
+
+WATCHABLE_DIRECT_COMMANDS: FrozenSet[str] = frozenset(
+    alias
+    for spec in DIRECT_COMMANDS
+    if spec.watchable
+    for alias in spec.names
+)
+
+
+# Commands shown by default in /help. Other slash commands remain executable but
+# are hidden to keep the startup surface compact.
+VISIBLE_SLASH_COMMANDS: FrozenSet[str] = frozenset({
+    # Session
+    "/help", "/clear", "/compact", "/cost", "/status", "/health",
+    "/regen", "/undo", "/rewind", "/copy", "/recap", "/btw",
+    # Sessions
+    "/save", "/load", "/sessions", "/recall", "/export",
+    # Config
+    "/model", "/thinking", "/config", "/permissions", "/privacy",
+    # Setup & discovery
+    "/setup", "/apikey", "/doctor", "/architecture", "/mcp", "/skills", "/tools", "/packages", "/markets",
+    # Auth
+    "/login", "/logout", "/whoami",
+    # Persistent data (direct writes)
+    "/alert", "/journal", "/watch", "/note", "/todo", "/memory",
+    # Broker
+    "/broker", "/account", "/positions", "/orders", "/paper", "/trade",
+    # Code & project
+    "/project", "/init", "/review", "/code", "/plan", "/orchestrate", "/run", "/task", "/tasks", "/impact", "/workflow", "/delegate",
+    "/diff", "/commit", "/pr", "/checkpoint", "/worktree", "/graph", "/agents", "/test", "/build", "/sim", "/consult", "/fix", "/canva", "/completions", "/lsp",
+    # Research
+    "/team", "/warehouse", "/deep",
+    # Quant
+    "/backtest", "/wf", "/tv", "/ashare",
+    # UI generation
+    "/ui",
+    # Other
+    "/artifacts", "/vision", "/upload-image", "/file", "/strategy", "/accuracy",
+})
+
+
+# ── What "/" shows ────────────────────────────────────────────────────────────
+# The "/" popup listed every command — 167 of them plus 14 skills, 92 without
+# a category — and /help printed about 90 lines. Codex lists only session
+# controls under "/", shows eight rows, and takes tasks in plain language.
+# Aria keeps every command runnable by name; the popup opens on these two
+# tiers, and typing narrows it over everything.
+
+# Session and setup controls, in popup order.
+CORE_SLASH_COMMANDS: Tuple[str, ...] = (
+    "/help", "/model", "/review", "/plan", "/init", "/status", "/sessions", "/clear",
+    "/compact", "/copy", "/rewind", "/permissions", "/config", "/doctor", "/login",
+)
+
+# One way into each capability: building code, financial analysis, logistics.
+ENTRY_SLASH_COMMANDS: Tuple[str, ...] = (
+    "/code", "/ta", "/backtest", "/team", "/report", "/portfolio", "/inventory", "/carriers",
+)
+
+# Second names for a command; the popup lists the command once.
+COMMAND_ALIASES = {"/upload-image": "/vision"}
+
+
+@dataclass(frozen=True)
+class HelpTopic:
+    key: str
+    title_en: str
+    title_zh: str
+    commands: Tuple[str, ...]
+
+
+HELP_TOPICS: Tuple[HelpTopic, ...] = (
+    HelpTopic("code", "Code and projects", "代码与项目", (
+        "/code", "/project", "/init", "/review", "/plan", "/run", "/read", "/write", "/edit", "/ls",
+        "/search", "/verify", "/scaffold", "/apply", "/changes", "/git",
+        "/diff", "/commit", "/pr", "/test", "/build", "/sim", "/consult", "/fix", "/graph", "/impact", "/agents", "/task", "/worktree", "/checkpoint")),
+    HelpTopic("market", "Market research", "市场研究", (
+        "/quote", "/analyze", "/ta", "/chart", "/tv", "/deep", "/team", "/report", "/news", "/markets",
+        "/watch", "/alert")),
+    HelpTopic("quant", "Quant and portfolios", "量化与组合", (
+        "/backtest", "/wf", "/compare", "/auto-strategy", "/execution", "/portfolio", "/risk",
+        "/optimize", "/stress", "/factors")),
+    HelpTopic("logistics", "Logistics", "物流", ("/inventory", "/carriers", "/warehouse")),
+    HelpTopic("data", "Notes, files and artifacts", "笔记、文件与产物", (
+        "/journal", "/note", "/todo", "/memory", "/artifacts", "/strategy", "/accuracy", "/file",
+        "/vision", "/ui")),
+    HelpTopic("broker", "Broker and trading", "券商与交易", (
+        "/broker", "/paper", "/trade", "/account", "/positions", "/orders")),
+    HelpTopic("session", "Session", "会话", (
+        "/clear", "/compact", "/cost", "/status", "/health", "/regen", "/undo", "/rewind", "/copy",
+        "/recap", "/btw", "/save", "/load", "/sessions", "/export", "/export-pdf")),
+    HelpTopic("config", "Setup", "设置", (
+        "/model", "/thinking", "/config", "/permissions", "/privacy", "/local", "/update", "/setup",
+        "/apikey", "/doctor", "/mcp", "/login", "/logout", "/skills", "/tools", "/packages")),
+)
+
+HELP_TOPIC_MAP = {topic.key: topic for topic in HELP_TOPICS}
+
+
+def popup_rank(name: str) -> int:
+    """0 for a core command, 1 for an entry point, 2 for everything else."""
+    if name in CORE_SLASH_COMMANDS:
+        return 0
+    if name in ENTRY_SLASH_COMMANDS:
+        return 1
+    return 2
+
+
+def short_description(description: str) -> str:
+    """The description without its usage tail: "Technical indicators: /ta AAPL …" → "Technical indicators"."""
+    text = str(description or "")
+    cut = text.find(": /")
+    return (text[:cut] if cut > 0 else text).strip()
+
+
+# What /help and the "/" popup say about the commands they show, in the Chinese
+# UI: the descriptions in the command table are English, so a Chinese session
+# read "Show commands and examples" under 命令.
+COMMAND_DESCRIPTIONS_ZH = {
+    "/help": "命令与示例", "/model": "切换模型", "/review": "代码审查", "/plan": "起草计划",
+    "/init": "为当前项目生成 ARIA.md", "/status": "运行状态：引擎 · 模型 · 工具 · 上下文",
+    "/sessions": "查看与搜索会话", "/clear": "清空对话", "/compact": "压缩上下文",
+    "/copy": "复制上一条回答", "/rewind": "恢复代码或对话", "/permissions": "工具权限",
+    "/config": "查看与修改配置", "/doctor": "诊断安装、模型与 API Key", "/login": "登录",
+    "/code": "生成并运行代码", "/ta": "技术指标", "/backtest": "回测并生成 HTML 报告",
+    "/team": "多智能体研究团队", "/report": "研究报告", "/portfolio": "投资组合",
+    "/diff": "查看改动：摘要或补丁", "/commit": "提交所有改动", "/pr": "当前分支的 Pull Request",
+    "/checkpoint": "检查点与回合还原点", "/worktree": "编码任务的工作树", "/graph": "项目图谱与改动影响",
+    "/agents": "项目智能体与后台任务", "/test": "运行项目测试", "/build": "运行项目构建",
+    "/fix": "定位原因、最小改动、验证", "/sim": "运行项目声明的仿真", "/consult": "向另一个模型征求第二意见",
+    "/inventory": "3PL 库存策略：补货点、安全库存、ABC/XYZ、呆滞库存",
+    "/carriers": "3PL 承运商评分：按线路排名、成本异常与节省",
+}
+
+
+def describe(name: str, description: str, lang: str = "en") -> str:
+    """The short description to show for a command, in the UI language."""
+    if str(lang).lower().startswith("zh") and name in COMMAND_DESCRIPTIONS_ZH:
+        return COMMAND_DESCRIPTIONS_ZH[name]
+    return short_description(description)