controlmesh 0.41.0__tar.gz → 0.41.2__tar.gz

{controlmesh-0.41.0 → controlmesh-0.41.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlmesh
-Version: 0.41.0
+Version: 0.41.2
 Summary: ControlMesh brings official coding CLIs into Telegram, Matrix, and Feishu with persistent workspaces, long-running jobs, and production-friendly bot operations.
 Project-URL: Homepage, https://github.com/muqiao215/ControlMesh
 Project-URL: Repository, https://github.com/muqiao215/ControlMesh

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/__init__.py

@@ -1,3 +1,3 @@
 """ControlMesh public package and CLI entrypoint surface."""
 
-__version__ = "0.41.0"
+__version__ = "0.41.2"

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/__main__.py

@@ -434,12 +434,12 @@ def _validate_feishu_config(config: AgentConfig) -> None:
     if not fs.app_id:
         _console.print("Feishu transport requires an existing Feishu self-built app.")
         _console.print("Missing field: feishu.app_id.")
-        _console.print("Run `controlmesh auth feishu setup` for zero-app onboarding guidance.")
+        _console.print("Run `controlmesh feishu native setup` to start the official scan-create registration flow.")
         sys.exit(1)
     if not fs.app_secret:
         _console.print("Feishu transport requires an existing Feishu self-built app.")
         _console.print("Missing field: feishu.app_secret.")
-        _console.print("Run `controlmesh auth feishu setup` for zero-app onboarding guidance.")
+        _console.print("Run `controlmesh feishu native setup` to start the official scan-create registration flow.")
         sys.exit(1)
 
 

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/cli/init_wizard.py

@@ -156,7 +156,7 @@ def _show_disclaimer(console: Console) -> None:
 
 
 def _ask_transport(console: Console) -> str:
-    """Prompt for the messaging transport (Telegram or Matrix)."""
+    """Prompt for the messaging transport."""
     console.print(
         Panel(
             t_rich("wizard.transport.body"),
@@ -168,10 +168,12 @@ def _ask_transport(console: Console) -> str:
 
     selected: str | None = questionary.select(
         t_rich("wizard.transport.prompt"),
-        choices=["Telegram", "Matrix"],
+        choices=["Feishu native", "Telegram", "Matrix"],
     ).ask()
     if selected is None:
         _abort()
+    if selected == "Feishu native":
+        return "feishu"
     return "matrix" if selected == "Matrix" else "telegram"
 
 
@@ -557,9 +559,20 @@ def _load_existing_config(config_path: Path) -> dict[str, object]:
 
 def _apply_transport_config(merged: dict[str, object], cfg: _WizardConfig) -> None:
     """Write transport-specific keys into *merged*."""
-    if cfg.get("transport", "telegram") == "telegram":
+    transport = cfg.get("transport", "telegram")
+    if transport == "telegram":
         merged["telegram_token"] = cfg.get("telegram_token", "")
         merged["allowed_user_ids"] = cfg.get("allowed_user_ids") or []
+    elif transport == "feishu":
+        feishu_section = merged.get("feishu")
+        if not isinstance(feishu_section, dict):
+            feishu_section = {}
+            merged["feishu"] = feishu_section
+        feishu_section.setdefault("mode", "bot_only")
+        feishu_section.setdefault("brand", "feishu")
+        feishu_section["runtime_mode"] = "native"
+        feishu_section["progress_mode"] = "card_stream"
+        feishu_section.setdefault("domain", "https://open.feishu.cn")
     else:  # matrix
         matrix_section = merged.get("matrix")
         if not isinstance(matrix_section, dict):
@@ -644,6 +657,19 @@ def run_onboarding() -> bool:
         console.print()
         allowed_user_ids = _ask_user_id(console)
         console.print()
+    elif transport == "feishu":
+        console.print(
+            Panel(
+                "Feishu native setup uses the official scan-create flow.\n\n"
+                "After this wizard writes the base config, run:\n\n"
+                "  controlmesh feishu native setup\n\n"
+                "That command prints the Feishu QR/link and auto-completes config writeback after approval.",
+                title="Feishu Native",
+                border_style="blue",
+                padding=(1, 2),
+            )
+        )
+        console.print()
     else:  # matrix
         matrix_homeserver = _ask_matrix_homeserver(console)
         console.print()
@@ -704,6 +730,11 @@ def run_onboarding() -> bool:
             + "\n"
             + t_rich("wizard.complete.logs", path=paths.logs_dir)
             + "\n\n"
+            + (
+                "Feishu next step: run `controlmesh feishu native setup` to scan-create the app bot.\n\n"
+                if transport == "feishu"
+                else ""
+            )
             + action,
             title=t_rich("wizard.complete.title"),
             border_style="green",

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/cli_commands/auth.py

@@ -872,8 +872,8 @@ def _render_feishu_setup_guidance(config: AgentConfig) -> None:
     _console.print(f"Feishu Open Platform app console: {_FEISHU_APP_CONSOLE_URL}")
     _console.print(f"Feishu self-built app guide: {_FEISHU_APP_DEV_GUIDE_URL}")
     _console.print("Required setup for a new user with no Feishu bot:")
-    _console.print("1. Preferred native path: run `controlmesh auth feishu register-begin` and scan the official QR flow.")
-    _console.print("2. Then run `controlmesh auth feishu register-poll --device-code <code>` until credentials are returned.")
+    _console.print("1. Preferred native path: run `controlmesh feishu native setup` and scan the official QR flow.")
+    _console.print("2. ControlMesh saves a pending registration and auto-completes config writeback after approval.")
     _console.print("3. That path writes `runtime_mode=native` and enables CardKit streaming by default.")
     _console.print("4. Manual bridge fallback: create a Feishu self-built app in the app console.")
     _console.print("5. Put the app_id/app_secret into config.json and keep `runtime_mode=bridge`.")
@@ -883,6 +883,7 @@ def _render_feishu_setup_guidance(config: AgentConfig) -> None:
     _console.print("9. Subscribe to message receive events such as im.message.receive_v1.")
     _console.print("10. Add the bot to a chat and send a first message to validate inbound/reply wiring.")
     _console.print("Manual fallback remains valid if the official scan-to-create flow is unavailable in your environment.")
+    _console.print("Advanced/manual commands remain available under `controlmesh auth feishu register-begin|register-poll`.")
     _console.print("After app credentials exist, `controlmesh auth feishu login` only performs optional device-flow user auth.")
     _console.print("It does not create a new app or bot.")
 

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/cli_commands/feishu.py

@@ -18,32 +18,49 @@ Commands:
 """
 _FEISHU_NATIVE_USAGE = """Usage:
   controlmesh feishu native bootstrap
+  controlmesh feishu native setup
   controlmesh feishu native doctor
   controlmesh feishu native probe
   controlmesh feishu native register-begin
+  controlmesh feishu native complete
 
 Commands:
   bootstrap       Start the Feishu native bootstrap flow.
+  setup           Begin scan-create registration and arm auto-complete.
   doctor          Run Feishu auth/runtime doctor checks.
   probe           Probe current Feishu runtime readiness.
   register-begin  Begin Feishu app registration flow.
+  complete        Complete a pending scan-create registration.
 """
 _FEISHU_NATIVE_BOOTSTRAP_USAGE = """Usage:
   controlmesh feishu native bootstrap
 
 Start the product-friendly Feishu native bootstrap flow.
 """
+_FEISHU_NATIVE_SETUP_USAGE = """Usage:
+  controlmesh feishu native setup [--no-start-service]
+
+Start the stable Feishu-native setup flow:
+  1. create the official scan-create registration session,
+  2. print the QR/link and user code,
+  3. save a pending registration file,
+  4. auto-complete config writeback after the QR flow is approved.
+"""
 _NATIVE_AUTH_COMMANDS = {
     "bootstrap": ["auth", "feishu", "setup"],
+    "setup": ["auth", "feishu", "register-begin"],
     "doctor": ["auth", "feishu", "doctor"],
     "probe": ["auth", "feishu", "probe"],
     "register-begin": ["auth", "feishu", "register-begin"],
+    "complete": ["auth", "feishu", "register-complete"],
 }
 _NATIVE_COMMAND_USAGE = {
     "bootstrap": _FEISHU_NATIVE_BOOTSTRAP_USAGE,
+    "setup": _FEISHU_NATIVE_SETUP_USAGE,
     "doctor": "Usage:\n  controlmesh feishu native doctor\n",
     "probe": "Usage:\n  controlmesh feishu native probe\n",
     "register-begin": "Usage:\n  controlmesh feishu native register-begin\n",
+    "complete": "Usage:\n  controlmesh feishu native complete\n",
 }
 
 
@@ -87,7 +104,7 @@ def _cmd_feishu_native(args: Sequence[str]) -> None:
 
     auth_args = _NATIVE_AUTH_COMMANDS.get(action)
     if auth_args:
-        cmd_auth(auth_args)
+        cmd_auth([*auth_args, *args[1:]])
         return
 
     raise SystemExit(1)

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/cli_commands/install.py

@@ -67,6 +67,7 @@ def _install_extra(name: str) -> None:
 
 def print_install_help() -> None:
     """Show available extras."""
+    console = Console()
     table = Table(show_header=True, header_style="bold")
     table.add_column(t_rich("install.col_extra"))
     table.add_column(t_rich("install.col_description"))
@@ -80,7 +81,12 @@ def print_install_help() -> None:
         )
         table.add_row(name, desc, status)
 
-    Console().print(Panel(table, title="controlmesh install <extra>"))
+    console.print(Panel(table, title="controlmesh install <extra>"))
+    console.print()
+    console.print("After installing ControlMesh, choose a chat setup path:")
+    console.print("  Feishu native: controlmesh feishu native setup")
+    console.print("  Telegram wizard: controlmesh setup")
+    console.print("  Optional extras: controlmesh install matrix | controlmesh install api")
 
 
 def cmd_install(args: list[str]) -> None:

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/messenger/feishu/auth/native_auth_all_runner.py

@@ -221,11 +221,12 @@ def _render_app_scope_missing_text(*, unavailable_scopes: list[str], permission_
     scope_lines = "\n".join(f"- {scope}" for scope in unavailable_scopes)
     return (
         "批量授权需要先补齐应用权限。\n\n"
-        "请打开下面的飞书快捷授权页。页面会直接带上这次缺少的权限，不用再去开发者后台慢慢找：\n"
-        f"{permission_url}\n\n"
+        "我会发一张权限申请卡。请点卡片里的“去申请权限”，它会打开飞书一键补充权限页，"
+        "并自动预选这次缺少的权限。\n\n"
         "缺少的应用权限：\n"
         f"{scope_lines}\n\n"
-        "权限保存后，点卡片里的继续，或重新发 `/feishu_auth_all`。"
+        "申请并审核通过后，回到卡片点“已完成，继续”，或重新发 `/feishu_auth_all`。\n\n"
+        f"如果卡片按钮打不开，可复制这个同款一键补权限链接：\n{permission_url}"
     )
 
 

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/messenger/feishu/auth/native_auth_useful_runner.py

@@ -11,6 +11,7 @@ from typing import Any
 from controlmesh.config import AgentConfig
 from controlmesh.integrations.feishu_auth_kit import run_feishu_auth_kit_json
 from controlmesh.messenger.feishu.auth.app_info import AppInfoAccessError, FeishuAppInfoCache
+from controlmesh.messenger.feishu.auth.brand import build_permission_url
 from controlmesh.messenger.feishu.auth.token_store import FeishuTokenStore
 from controlmesh.messenger.feishu.native_tools import all_native_user_auth_scopes
 
@@ -74,12 +75,13 @@ def filter_useful_user_auth_scopes(
 
 
 class FeishuNativeAuthUsefulRunner:
-    """Authorize all currently granted user scopes except excluded enterprise domains."""
+    """Authorize useful native scopes while excluding heavy enterprise domains."""
 
     def __init__(
         self,
         config: AgentConfig,
         *,
+        start_app_permission_flow: Callable[..., Awaitable[None]],
         start_user_auth_flow: Callable[..., Awaitable[None]],
         text_reply: Callable[[str, str, str | None], Awaitable[None]],
         session_factory: Callable[[], Awaitable[Any]] | None = None,
@@ -91,8 +93,10 @@ class FeishuNativeAuthUsefulRunner:
         token_store: FeishuTokenStore | None = None,
         batch_size: int = 100,
         excluded_scope_keywords: Iterable[str] = _DEFAULT_EXCLUDED_SCOPE_KEYWORDS,
+        target_scopes: Iterable[str] | None = None,
     ) -> None:
         self._config = config
+        self._start_app_permission_flow = start_app_permission_flow
         self._start_user_auth_flow = start_user_auth_flow
         self._text_reply = text_reply
         self._session_factory = session_factory
@@ -105,6 +109,7 @@ class FeishuNativeAuthUsefulRunner:
         self._batch_size = batch_size
         self._excluded_scope_keywords = tuple(excluded_scope_keywords)
         self._preserve_scopes = all_native_user_auth_scopes()
+        self._target_scopes = tuple(target_scopes or all_native_user_auth_scopes())
 
     async def handle_message(self, message: FeishuIncomingText) -> bool:
         if self._config.feishu.runtime_mode != "native":
@@ -112,9 +117,8 @@ class FeishuNativeAuthUsefulRunner:
         if not is_native_auth_useful_command(message.text):
             return False
 
-        app_scopes = await self._load_app_scopes()
         requested_scopes = filter_useful_user_auth_scopes(
-            app_scopes,
+            self._target_scopes,
             excluded_scope_keywords=self._excluded_scope_keywords,
             preserve_scopes=self._preserve_scopes,
         )
@@ -126,12 +130,32 @@ class FeishuNativeAuthUsefulRunner:
             )
             return True
 
+        app_scopes = await self._load_app_scopes()
         user_scopes = self._load_user_scopes(message.sender_id)
         plan = await self._plan_scopes(
             requested_scopes=requested_scopes,
             app_scopes=app_scopes,
             user_scopes=user_scopes,
         )
+        unavailable_scopes = _string_list(plan.get("unavailable_scopes"))
+        if unavailable_scopes:
+            permission_url = _permission_url(self._config, unavailable_scopes)
+            await self._text_reply(
+                message.chat_id,
+                _render_app_scope_missing_text(
+                    unavailable_scopes=unavailable_scopes,
+                    permission_url=permission_url,
+                ),
+                message.message_id if self._config.feishu.reply_to_trigger else None,
+            )
+            await self._start_app_permission_flow(
+                message,
+                required_scopes=unavailable_scopes,
+                permission_url=permission_url,
+                retry_text=message.text,
+            )
+            return True
+
         batches = _list_of_string_lists(plan.get("batches"))
         next_batch = batches[0] if batches else _string_list(plan.get("missing_user_scopes"))
         if next_batch:
@@ -162,7 +186,7 @@ class FeishuNativeAuthUsefulRunner:
         if self._get_app_scopes is not None:
             return _string_list(await _maybe_await(self._get_app_scopes()))
         if self._session_factory is None or self._get_tenant_access_token is None:
-            return []
+            return list(self._target_scopes)
         try:
             session = await self._session_factory()
             tenant_access_token = await _maybe_await(self._get_tenant_access_token())
@@ -174,8 +198,8 @@ class FeishuNativeAuthUsefulRunner:
                 token_type="user",
             )
         except AppInfoAccessError:
-            logger.warning("Feishu auth-useful could not inspect app scopes")
-            return []
+            logger.warning("Feishu auth-useful could not inspect app scopes; falling back to optimistic planning")
+            return list(self._target_scopes)
 
     def _load_user_scopes(self, user_open_id: str) -> list[str]:
         if self._get_user_scopes is not None:
@@ -214,6 +238,16 @@ async def _maybe_await(value: Any) -> Any:
     return value
 
 
+def _permission_url(config: AgentConfig, scopes: list[str]) -> str:
+    return build_permission_url(
+        app_id=config.feishu.app_id,
+        scopes=scopes,
+        brand=config.feishu.brand,
+        token_type="user",
+        op_from="controlmesh-feishu-auth-useful",
+    )
+
+
 def _string_list(value: Any) -> list[str]:
     if not isinstance(value, list):
         return []
@@ -234,11 +268,24 @@ def _list_of_string_lists(value: Any) -> list[list[str]]:
 
 def _render_no_scopes_text() -> str:
     return (
-        "当前应用里没有需要补的非黑名单用户权限。\n\n"
+        "当前 useful 目标里没有需要补的非黑名单用户权限。\n\n"
         "这个命令会自动跳过邮件、HR、Payroll、Minutes、OKR、Tasks 这些重域。"
     )
 
 
+def _render_app_scope_missing_text(*, unavailable_scopes: list[str], permission_url: str) -> str:
+    scope_lines = "\n".join(f"- {scope}" for scope in unavailable_scopes)
+    return (
+        "飞书 useful 授权需要先补齐应用权限。\n\n"
+        "我会发一张权限申请卡。请点卡片里的“去申请权限”，它会打开飞书一键补充权限页，"
+        "并自动预选这次缺少的权限。\n\n"
+        "缺少的应用权限：\n"
+        f"{scope_lines}\n\n"
+        "申请并审核通过后，回到卡片点“已完成，继续”，或重新发 `/feishu_auth_useful`。\n\n"
+        f"如果卡片按钮打不开，可复制这个同款一键补权限链接：\n{permission_url}"
+    )
+
+
 def _render_user_scope_batch_text(*, scopes: list[str], batch_index: int, total_batches: int) -> str:
     scope_lines = "\n".join(f"- {scope}" for scope in scopes)
     return (

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/messenger/feishu/auth/orchestration_runner.py

@@ -386,8 +386,9 @@ def _feishu_card_from_auth_kit(card: object) -> dict[str, Any]:
     if card.get("type") == "permission_missing":
         message = (
             f"{message}\n\n"
-            "This is an app-level boundary handled by the app owner/admin, not user OAuth.\n"
-            "After the app permissions are approved, come back here and tap continue / retry."
+            "这是应用权限申请步骤，不是用户 OAuth 授权。\n"
+            "请先点“去申请权限”打开飞书一键补充权限页，缺失权限会自动预选；"
+            "申请并审核通过后，回到这张卡点“已完成，继续”。"
         )
     operation_id = str(card.get("operation_id") or "")
     fields = card.get("fields") if isinstance(card.get("fields"), dict) else {}
@@ -411,7 +412,7 @@ def _feishu_card_from_auth_kit(card: object) -> dict[str, Any]:
                     {
                         "tag": "button",
                         "type": "primary",
-                        "text": {"tag": "plain_text", "content": "Open permission page"},
+                        "text": {"tag": "plain_text", "content": "去申请权限"},
                         "multi_url": {
                             "url": link_url,
                             "pc_url": link_url,
@@ -422,7 +423,7 @@ def _feishu_card_from_auth_kit(card: object) -> dict[str, Any]:
                     {
                         "tag": "button",
                         "type": "default",
-                        "text": {"tag": "plain_text", "content": "I have granted permissions"},
+                        "text": {"tag": "plain_text", "content": "已完成，继续"},
                         "value": {
                             "action": "permissions_granted_continue",
                             "operation_id": operation_id,

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/messenger/feishu/bot.py

@@ -1994,6 +1994,7 @@ class FeishuBot:
                 self._config,
                 session_factory=self._ensure_session,
                 get_tenant_access_token=self._get_tenant_access_token,
+                start_app_permission_flow=self._ensure_auth_orchestration_runner().start_permission_flow,
                 start_user_auth_flow=self._ensure_card_auth_runner().start_retryable_auth_flow,
                 text_reply=self._reply_card_auth_text,
             )

{controlmesh-0.41.0 → controlmesh-0.41.2}/controlmesh/messenger/feishu/command_center_card.py

@@ -180,7 +180,7 @@ def build_command_guide_text(
         "常用命令:",
         *controlmesh_lines,
         "/feishu_auth_all — 批量补齐飞书原生权限",
-        "/feishu_auth_useful — 除黑名单外批量补齐应用已开放权限",
+        "/feishu_auth_useful — 补齐常用飞书原生权限, 自动跳过重企业域",
         "",
         "Native Commands 提示:",
         "/compact — native compact context",
@@ -205,7 +205,7 @@ def _command_center_markdown(
         + "\n".join(command_lines)
         + "\n\n**Feishu**\n"
         + "- `/feishu_auth_all` narrow native auth path\n"
-        + "- `/feishu_auth_useful` bulk auth excluding heavy enterprise domains\n\n"
+        + "- `/feishu_auth_useful` useful native auth path excluding heavy enterprise domains\n\n"
         + "Use `/cm` to open Native Commands for the current CLI.\n\n"
         + runtime_note
     )

{controlmesh-0.41.0 → controlmesh-0.41.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlmesh"
-version = "0.41.0"
+version = "0.41.2"
 description = "ControlMesh brings official coding CLIs into Telegram, Matrix, and Feishu with persistent workspaces, long-running jobs, and production-friendly bot operations."
 readme = "README.md"
 requires-python = ">=3.11"