maxc-cli 0.4.5__tar.gz → 0.4.7__tar.gz

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.4.5
+Version: 0.4.7
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -61,7 +61,7 @@ maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
 | **cache** | `build`, `build-status`, `status`, `clear` | 元数据缓存管理 |
 | **agent** | `context`, `skill install`, `skill list` | Agent 集成与 SKILL 安装 |
 
-所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。支持 `--format json|markdown|brief`（全局标志）。
+所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。对 Agent 而言，应始终使用 `--json`。
 
 ## Agent 集成
 
@@ -128,12 +128,10 @@ maxc agent skill --json     # SKILL.md 路径与 min_cli_version
 
 ### 输出格式
 
-`--format` 是全局标志，适用于所有命令：
+对 Agent，统一使用 `--json`：
 
 ```bash
-maxc --format json meta describe my_table      # 结构化 JSON（默认，等价于 --json）
-maxc --format markdown meta describe my_table  # 人类可读 markdown
-maxc --format brief meta describe my_table     # 最小化单行输出（低 token 场景）
+maxc meta describe my_table --json
 ```
 
 ### safety 块

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/README.md

@@ -39,7 +39,7 @@ maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
 | **cache** | `build`, `build-status`, `status`, `clear` | 元数据缓存管理 |
 | **agent** | `context`, `skill install`, `skill list` | Agent 集成与 SKILL 安装 |
 
-所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。支持 `--format json|markdown|brief`（全局标志）。
+所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。对 Agent 而言，应始终使用 `--json`。
 
 ## Agent 集成
 
@@ -106,12 +106,10 @@ maxc agent skill --json     # SKILL.md 路径与 min_cli_version
 
 ### 输出格式
 
-`--format` 是全局标志，适用于所有命令：
+对 Agent，统一使用 `--json`：
 
 ```bash
-maxc --format json meta describe my_table      # 结构化 JSON（默认，等价于 --json）
-maxc --format markdown meta describe my_table  # 人类可读 markdown
-maxc --format brief meta describe my_table     # 最小化单行输出（低 token 场景）
+maxc meta describe my_table --json
 ```
 
 ### safety 块

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/setup.py

@@ -9,7 +9,7 @@ README = ROOT / "README.md"
 
 setup(
     name="maxc-cli",
-    version="0.4.5",
+    version="0.4.7",
     description="Agent-native MaxCompute CLI for external coding agents",
     long_description=README.read_text(encoding="utf-8"),
     long_description_content_type="text/markdown",

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.4.5"
+__version__ = "0.4.7"

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli/app.py

@@ -126,6 +126,12 @@ class _PickerInputs:
     reselect: 'bool' = False
 
 
+class ProjectPickerPending(Exception):
+    """Raised when non-TTY auth login can list projects but needs the caller to pick one."""
+    def __init__(self, projects: list):
+        self.projects = projects
+
+
 class MaxCApp:
     def __init__(
         self,
@@ -1262,7 +1268,7 @@ class MaxCApp:
 
         if use_catalog and self.backend is not None:
             catalog_matches = self.backend.catalog_search_tables(
-                keyword, schema=effective_schema,
+                keyword, schema=effective_schema, project=project,
             )
             if catalog_matches is not None:
                 matches = catalog_matches
@@ -1735,7 +1741,7 @@ class MaxCApp:
                 }
             )
 
-        all_tables, _ = self.backend.list_tables(schema=schema_name)
+        all_tables, _ = self.backend.list_tables(schema=schema_name, project=target_project)
         tables = all_tables
 
         if progress_callback is not None:
@@ -1830,13 +1836,16 @@ class MaxCApp:
                 }
             )
 
+        write_schema = schema_name or "default"
+
         def fetch_and_cache(
             table_name: 'str',
-            table_schema: 'str' = "default",
         ) -> 'tuple[str, str | None]':
             try:
-                full_table = self.backend.describe_table(table_name)
-                existing = self.cache.get_cached_table(project, full_table.name, table_schema)
+                full_table = self.backend.describe_table(
+                    table_name, project=project, schema=schema_name,
+                )
+                existing = self.cache.get_cached_table(project, full_table.name, write_schema)
                 columns = [
                     {"name": c.name, "type": c.type, "comment": c.comment}
                     for c in full_table.columns
@@ -1847,7 +1856,7 @@ class MaxCApp:
                     description=full_table.description,
                     columns=columns,
                     partitions=full_table.partitions,
-                    schema_name=table_schema,
+                    schema_name=write_schema,
                 )
                 return ("updated" if existing else "created"), None
             except Exception as exc:
@@ -2615,29 +2624,63 @@ class MaxCApp:
 
         # Project / endpoint / region / tunnel — try the interactive Catalog
         # picker when the user did not pin a project explicitly.
-        (
-            picked_project,
-            derived_endpoint,
-            derived_region,
-            derived_tunnel,
-            picker_warnings,
-        ) = self._resolve_project_via_picker(
-            _PickerInputs(
-                provided_project=project,
-                provided_endpoint=endpoint,
-                provided_region=region_name,
-                provided_tunnel=tunnel_endpoint,
-                access_id=resolved_access_id,
-                secret=resolved_secret,
-                security_token=resolved_token,
-                catalog_endpoint=catalog_endpoint,
-                no_picker=no_picker,
-                from_env=from_env,
-                env_settings=env_settings,
-                existing_auth=existing_auth,
-                reselect=reselect,
+        try:
+            (
+                picked_project,
+                derived_endpoint,
+                derived_region,
+                derived_tunnel,
+                picker_warnings,
+            ) = self._resolve_project_via_picker(
+                _PickerInputs(
+                    provided_project=project,
+                    provided_endpoint=endpoint,
+                    provided_region=region_name,
+                    provided_tunnel=tunnel_endpoint,
+                    access_id=resolved_access_id,
+                    secret=resolved_secret,
+                    security_token=resolved_token,
+                    catalog_endpoint=catalog_endpoint,
+                    no_picker=no_picker,
+                    from_env=from_env,
+                    env_settings=env_settings,
+                    existing_auth=existing_auth,
+                    reselect=reselect,
+                )
+            )
+        except ProjectPickerPending as exc:
+            projects_data = [
+                {
+                    "project_id": p.project_id,
+                    "region": p.region,
+                    "endpoint": _catalog_bootstrap.region_to_endpoint(p.region),
+                    "owner": p.owner,
+                    "schema_enabled": p.schema_enabled,
+                    "description": p.description,
+                }
+                for p in exc.projects
+            ]
+            return Envelope(
+                command="auth.login",
+                status="pending",
+                data={
+                    "reason": "project_selection_required",
+                    "projects": projects_data,
+                    "count": len(projects_data),
+                },
+                agent_hints=AgentHints(
+                    actions=[
+                        SuggestedAction(
+                            id="auth.login",
+                            title="Complete login with selected project",
+                            command="maxc auth login --project <project_id> --json",
+                            executable=False,
+                            placeholders={"project_id": "<project_id>"},
+                        ),
+                    ],
+                    warnings=[],
+                ),
             )
-        )
 
         resolved_auth = AuthConfig(
             access_id=resolved_access_id,
@@ -3086,8 +3129,30 @@ class MaxCApp:
                 [],
             )
 
-        # 2. Picker not viable → today's behavior (prompt or fail).
+        # 2. Picker not viable (non-TTY or --no-picker).
         if inputs.no_picker or not sys.stdin.isatty():
+            # Non-TTY + picker not disabled: list projects for structured output
+            catalog_warning: str | None = None
+            if not inputs.no_picker and not from_env:
+                try:
+                    bootstrap_odps = _catalog_bootstrap.build_bootstrap_odps(
+                        access_id=inputs.access_id,
+                        secret_access_key=inputs.secret,
+                        security_token=inputs.security_token,
+                        endpoint=inputs.catalog_endpoint or provided_endpoint,
+                    )
+                    projects = _catalog_bootstrap.list_all_projects(bootstrap_odps)
+                    if projects:
+                        raise ProjectPickerPending(projects)
+                except ProjectPickerPending:
+                    raise
+                except Exception as exc:
+                    catalog_warning = (
+                        f"Could not list projects via Catalog API "
+                        f"({type(exc).__name__}: {exc}). "
+                        f"Falling back to saved/env config."
+                    )
+
             prompted = self._resolve_login_value(
                 provided=None,
                 env_value=env_settings.get("project"),
@@ -3097,12 +3162,15 @@ class MaxCApp:
                 secret=False,
                 use_env=from_env,
             )
+            warnings_out: list[str] = []
+            if catalog_warning:
+                warnings_out.append(catalog_warning)
             return (
                 prompted,
                 provided_endpoint,
                 provided_region,
                 provided_tunnel,
-                [],
+                warnings_out,
             )
 
         # 3. Try the catalog picker.

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli/backend/catalog.py

@@ -192,6 +192,7 @@ class CatalogMixin:
         keyword: str,
         *,
         schema: 'str | None' = None,
+        project: 'str | None' = None,
         page_size: int = 50,
     ) -> 'list[dict[str, Any]] | None':
         """Search tables via Catalog API server-side full-text search.
@@ -199,6 +200,8 @@ class CatalogMixin:
         Args:
             keyword: Search term — matched against table name (substring).
             schema: Optional schema to scope the search.
+            project: Optional project to scope the search; default = config's
+                default_project.
             page_size: Results per page (max 100).
 
         Returns:
@@ -225,7 +228,7 @@ class CatalogMixin:
             #   type=TABLE      — required filter
             #   project={proj}  — scope to project
             parts = ["type=TABLE"]
-            project = self.config.default_project
+            project = project or self.config.default_project
             if project:
                 parts.append(f"project={project}")
             if keyword:

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli/backend/data.py

@@ -38,18 +38,27 @@ def _serialize_value(value: 'Any') -> 'Any':
 class DataMixin:
     """Mixin providing data sampling and profiling methods."""
 
-    def _table_tunnel(self):
-        """Return a TableTunnel for the current ODPS client.
+    def _table_tunnel(self, project: 'str | None' = None):
+        """Return a TableTunnel bound to ``project`` (or the client default).
 
         Real PyODPS `ODPS` instances do not expose a `.tunnel` attribute,
         so we construct `odps.tunnel.TableTunnel(odps=self.client)` lazily.
-        Test doubles (FakeODPS) DO expose `.tunnel` directly — honor that
-        so existing FakeTunnel infrastructure keeps working.
+        The tunnel resolves tables against its own project, so a cross-project
+        download/upload (e.g. `--project other_proj`) MUST construct the tunnel
+        with that project — `create_*_session()` takes no project argument.
+
+        Test doubles (FakeODPS) DO expose `.tunnel` directly — honor that so
+        existing FakeTunnel infrastructure keeps working, and surface the
+        requested project on the instance for assertions.
         """
         existing = getattr(self.client, "tunnel", None)
         if existing is not None:
+            if project is not None:
+                existing.requested_project = project
             return existing
         from odps.tunnel import TableTunnel
+        if project:
+            return TableTunnel(odps=self.client, project=project)
         return TableTunnel(odps=self.client)
 
     def _resolve_partition_for_sample(
@@ -340,7 +349,7 @@ class DataMixin:
             create_session_kwargs["create_partition"] = True
         if schema:
             create_session_kwargs["schema"] = schema
-        upload_session = self._table_tunnel().create_upload_session(
+        upload_session = self._table_tunnel(project=project or self.project).create_upload_session(
             definition.name, **create_session_kwargs,
         )
 
@@ -491,7 +500,7 @@ class DataMixin:
             download_kwargs: dict[str, Any] = {"partition_spec": partition}
             if schema:
                 download_kwargs["schema"] = schema
-            session = self._table_tunnel().create_download_session(
+            session = self._table_tunnel(project=project or self.project).create_download_session(
                 definition.name, **download_kwargs,
             )
             total = session.count

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli/cli.py

@@ -1667,7 +1667,7 @@ def _handle_cache_build(app: MaxCApp, args: argparse.Namespace, stdout: TextIO)
     stdout.write("Fetching table list...\n")
     stdout.flush()
     
-    tables, _ = app.backend.list_tables()
+    tables, _ = app.backend.list_tables(project=target_project, schema=schema_name)
     total = len(tables)
     
     if total == 0:
@@ -1698,7 +1698,7 @@ def _handle_cache_build(app: MaxCApp, args: argparse.Namespace, stdout: TextIO)
         def _do_fetch():
             # Use a simpler approach: only get table metadata without sample rows
             # to avoid potential hangs on table.head() or iterate_partitions()
-            table = app.backend._get_table(table_name)
+            table = app.backend._get_table(table_name, project=target_project, schema=schema_name)
             # Force reload to get full schema info
             if hasattr(table, 'reload'):
                 table.reload()

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli/output.py

@@ -84,6 +84,42 @@ def _stringify(value: Any) -> str:
 # ---------------------------------------------------------------------------
 
 
+def _render_pending_md(envelope: Envelope) -> str:
+    """Render a pending/async envelope so the user sees status and how to wait."""
+    parts: list[str] = ["## Pending", ""]
+    parts.append("The query has not finished yet — it is still running asynchronously.")
+    parts.append("")
+
+    data = envelope.data or {}
+    metadata = envelope.metadata or {}
+    kv: dict[str, Any] = {}
+    job_id = data.get("job_id") or metadata.get("job_id")
+    if job_id:
+        kv["Job ID"] = job_id
+    if metadata.get("project"):
+        kv["Project"] = metadata["project"]
+    if metadata.get("wait_seconds") is not None:
+        kv["Waited"] = f"{metadata['wait_seconds']}s"
+    if metadata.get("logview"):
+        kv["Logview"] = metadata["logview"]
+    if kv:
+        parts.append(render_key_values(kv))
+        parts.append("")
+
+    parts.append("Wait for it to complete with:")
+    parts.append("")
+    hints = envelope.agent_hints
+    if hints is None or not hints.actions:
+        if job_id:
+            parts.append(f"- `maxc job wait {job_id} --json`")
+            parts.append(f"- `maxc job status {job_id} --json`")
+        else:
+            parts.append("- `maxc job wait <job_id> --json`")
+        parts.append("")
+        return "\n".join(parts)
+    return _append_agent_hints_md(parts, envelope)
+
+
 def render_markdown(envelope: Envelope) -> str:
     """Render an Envelope as human-readable markdown."""
     parts: list[str] = []
@@ -100,6 +136,10 @@ def render_markdown(envelope: Envelope) -> str:
         parts.append("")
         return _append_agent_hints_md(parts, envelope)
 
+    # --- Pending / async envelopes --------------------------------------
+    if envelope.status == "pending":
+        return _render_pending_md(envelope)
+
     command = envelope.command
     data = envelope.data
     metadata = envelope.metadata or {}
@@ -249,6 +289,16 @@ def render_brief(envelope: Envelope) -> str:
 
     data = envelope.data
 
+    # --- pending / async ------------------------------------------------
+    if envelope.status == "pending":
+        job_id = data.get("job_id") or (envelope.metadata or {}).get("job_id") or "?"
+        line = f"{command} | pending | job {job_id}"
+        if next_cmd:
+            line += f" | next: {next_cmd}"
+        elif job_id != "?":
+            line += f" | next: maxc job wait {job_id} --json"
+        return line
+
     # --- query ----------------------------------------------------------
     if envelope.command in {"query", "job.wait", "job.result"}:
         total = data.get("total_rows", "?")

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli/skills/SKILL.md

@@ -40,7 +40,7 @@ in SKILL.md alone.
 
 These are non-negotiable. See [references/red-lines.md](references/red-lines.md) for the full list including common mistakes, anti-patterns, and error recovery.
 
-1. **Always use `--json`** for machine work. Use `--format markdown` for user-facing output, `--format brief` in token-tight contexts. `--json` is shorthand for `--format json`. **`--format` is a top-level flag — it must come before the subcommand**: `{{cli}} --format markdown query "SELECT 1"` (✓), not `{{cli}} query "SELECT 1" --format markdown` (✗). `--json` may appear anywhere because each subcommand also accepts it.
+1. **Always use `--json`**. Agents should use JSON output consistently.
 2. **Never invent names** — table, schema, project, or endpoint. Verify with `meta` commands and `auth whoami`.
 3. **Default to `--project` for the user's target project.** The configured project (in `~/.maxc/config.yaml`) is the user's **dev project** — the data they actually want to query usually lives in a *different* project (often the corresponding production one). When the user mentions a table/project without specifying which environment, **ask first**, then pass `--project <name>` on every meta/data command and use `project.table` in SQL.
 4. **Project naming convention is a fixed pair:** `<name>_dev` is the dev project; the same `<name>` **without** the `_dev` suffix is its corresponding **production** project. Together they form one DataWorks workspace. They share metadata structure but hold different data and different permissions. See Dev vs Production Projects below.
@@ -52,10 +52,11 @@ These are non-negotiable. See [references/red-lines.md](references/red-lines.md)
 
 ## Bootstrap Flow
 
-When `auth whoami --json` returns `configured=false` (no auth set up), follow [references/bootstrap-flow.md](references/bootstrap-flow.md) step by step. Three principles:
+When `auth whoami --json` returns `configured=false` (no auth set up), follow [references/bootstrap-flow.md](references/bootstrap-flow.md) step by step. Key principles:
 
 1. **Never pick the auth method yourself** — always ask the user to choose between AK/SK and environment variables.
 2. **If `auth whoami` shows `auth_type=external`, the user is on an externally-managed credential provider — do NOT modify the auth config.** Treat the bootstrap as already done. Only `project`/`endpoint`/`schema` are safe to change (via `session set` or by re-running `auth login-external` with the same `--process-command`).
+3. **For AK/SK login, omit `--project` to discover available projects** — the CLI returns a `status="pending"` envelope listing all projects visible to the AK/SK (with endpoint/region pre-computed). Pick a project from the list (ask the user if ambiguous), then re-run with `--project <id>`. Skip this when the user already knows the target project.
 
 ## First Pass
 
@@ -124,11 +125,10 @@ Use `--project` to read metadata from the production project without switching s
 {{cli}} data sample my_table --project my_project --json
 ```
 
-When writing SQL, use `project.table` format to reference tables in another project:
+When querying production data from a dev project, use a fully qualified table name in SQL and pass the dev project explicitly:
 
-```sql
--- From dev project, query a production table
-SELECT * FROM my_project.my_table WHERE ds = '20260418' LIMIT 100
+```bash
+{{cli}} query "SELECT * FROM my_production_project.my_table WHERE ds = '20260418' LIMIT 100" --project my_dev_project
 ```
 
 Do NOT use bare table names (`FROM my_table`) when the target table lives in a different project — the query will fail with `TABLE_NOT_FOUND`.
@@ -209,6 +209,7 @@ For full command syntax and options, see [references/command-patterns.md](refere
 | Check who I am and where I'm pointed | `{{cli}} auth whoami --json` |
 | Set up auth from scratch | See Bootstrap Flow above |
 | Switch project/schema for this session | `{{cli}} session set --project P --schema S --json` |
+| Re-select project (list available projects) | `{{cli}} auth login --reselect --json` → pick from `data.projects` → re-run with `--project` |
 | List tables | `{{cli}} meta list-tables --schema S --json` |
 | Get full schema of a table | `{{cli}} meta describe T --json` |
 | Find tables by keyword | `{{cli}} meta search KW --json` |

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli/skills/references/bootstrap-auth.md

@@ -76,16 +76,13 @@ Then follow the matching section below.
 
 If `auth whoami` shows `auth_type=external` (or the saved config has `provider: external`), the user is on an externally-managed credential provider set up by another tool. **Do not run Step 2 or write a new auth block.** Treat the auth as already valid. Only `project`/`endpoint`/`schema` may be changed — via `{{cli}} session set ...` or by re-running `auth login-external` with the *same* `--process-command` and the new project/endpoint values.
 
-### Always ask for project and endpoint
+### Project and endpoint selection
 
-**Regardless of auth method, always ask the user for `project` and `endpoint` explicitly.** Do not silently reuse values from an existing config file or environment variables.
+**Path A (AK/SK):** omit `--project` — the CLI queries the Catalog API and returns a `status="pending"` envelope listing all projects visible to the AK/SK, with endpoint/region pre-computed per project. Pick one from the list (ask the user if ambiguous), then re-run with `--project <id>` to complete login.
 
-If a current value is visible in the config or env, present it as a default option — but the user must confirm or change it:
+**Path B (env vars):** `--from-env` reads `MAXCOMPUTE_PROJECT` and `MAXCOMPUTE_ENDPOINT` from the shell environment. If either is missing, the command fails with a clear error — ask the user to set them.
 
-> "Which MaxCompute project would you like to use? (current config shows: `<existing_project>`)"
-> "Which endpoint? (current config shows: `<existing_endpoint>`)"
-
-Never assume the existing project/endpoint is still correct.
+**Explicit override:** if the user already knows the target project, pass `--project` and `--endpoint` directly to skip project discovery.
 
 ---
 
@@ -97,23 +94,33 @@ Use when the user has a long-lived AK/SK pair.
 
 - `access_key_id`
 - `access_key_secret`
-- `project` (MaxCompute project name)
-- `endpoint` (e.g. `http://service.cn-shanghai.maxcompute.aliyun.com/api`)
-- `region` (optional, e.g. `cn-shanghai`)
 
-### Login command
+The Catalog API provides `project`, `endpoint`, `region`, and `tunnel_endpoint` automatically. Only ask the user for these if they pass `--no-picker` or already know the target project.
+
+### Login command — Step 1: discover projects (recommended)
 
 ```bash
 {{cli}} auth login \
   --access-id "<access_key_id>" \
   --secret-access-key "<access_key_secret>" \
-  --project "<project>" \
-  --endpoint "<endpoint>" \
-  --region "<region>" \
   --json
 ```
 
-Add `--no-validate` to save config without a remote identity check:
+Returns `status="pending"` with `data.projects` — a list of `{project_id, region, endpoint, owner, schema_enabled, description}`. Pick a project from the list and proceed to Step 2.
+
+### Login command — Step 2: complete login
+
+```bash
+{{cli}} auth login \
+  --access-id "<access_key_id>" \
+  --secret-access-key "<access_key_secret>" \
+  --project "<project_id>" \
+  --json
+```
+
+Returns `status="success"` with the configured identity. Endpoint/region are auto-derived from the project when omitted.
+
+### Login command (explicit — when user knows the target)
 
 ```bash
 {{cli}} auth login \
@@ -121,10 +128,23 @@ Add `--no-validate` to save config without a remote identity check:
   --secret-access-key "<access_key_secret>" \
   --project "<project>" \
   --endpoint "<endpoint>" \
-  --no-validate \
+  --region "<region>" \
   --json
 ```
 
+Add `--no-validate` to either form to save config without a remote identity check.
+
+### Picker flags
+
+| Flag | Effect |
+|------|--------|
+| (omit `--project`) | Return pending envelope with project list from Catalog API (non-TTY) or interactive picker (TTY) |
+| `--no-picker` | Disable project discovery; fall back to manual prompt for project/endpoint (CI escape hatch) |
+| `--reselect` | Force project discovery even when a project is already saved in config (no effect with `--project` or `--no-picker`) |
+| `--catalog-endpoint <url>` | Override the Catalog API URL (for non-China regions where auto-routing is unavailable) |
+
+Fallback: if the Catalog API call fails (network, permissions, etc.), the CLI falls back to a manual prompt (TTY) or returns project=None (non-TTY).
+
 ### What it saves
 
 ```yaml

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli/skills/references/bootstrap-flow.md

@@ -51,9 +51,11 @@ Then jump to the matching path in [bootstrap-auth.md](bootstrap-auth.md):
 
 If `auth whoami --json` shows `auth_type=external` (or `provider: external` in the saved config), the user is on an externally-managed credential provider. **Do not run Phase 2.** The auth is already set up — only `project`/`endpoint`/`schema` are safe to change via `session set` or by re-running the original `auth login-external` with updated `--project`/`--endpoint`. Treat bootstrap as complete and move to Phase 3.
 
-### Always confirm project and endpoint
+### Project and endpoint
 
-Regardless of method, ask the user explicitly for `project` and `endpoint`. If a value is already in the config or env, present it as a default but require confirmation. See [bootstrap-auth.md](bootstrap-auth.md) §"Always ask for project and endpoint".
+**Path A (AK/SK):** do NOT ask for project or endpoint upfront. Omit `--project` from `auth login` — the CLI returns a `pending` envelope listing available projects with pre-computed endpoints. Pick one (ask the user if ambiguous), then re-run with `--project <id>`. See [bootstrap-auth.md](bootstrap-auth.md) §"Project and endpoint selection".
+
+**Path B (env vars):** `--from-env` reads project and endpoint from the shell. If either is missing, ask the user to export them before re-running.
 
 ### Dev vs production project check
 

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli/skills/references/command-patterns.md

@@ -140,7 +140,7 @@ Async pattern for long queries:
 
 ```bash
 # Step 1: submit
-{{cli}} query "SELECT * FROM my_schema.big_table WHERE ds = '20260418'" --wait 0 --json
+{{cli}} query "SELECT * FROM my_production_project.my_table WHERE ds = '20260418'" --project my_dev_project --wait 0 --json
 # Returns: { "status": "pending", "metadata": { "job_id": "<job_id>" } }
 
 # Step 2: extract metadata.job_id (e.g. 2026042011_abc123) and wait

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/src/maxc_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.4.5
+Version: 0.4.7
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -61,7 +61,7 @@ maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
 | **cache** | `build`, `build-status`, `status`, `clear` | 元数据缓存管理 |
 | **agent** | `context`, `skill install`, `skill list` | Agent 集成与 SKILL 安装 |
 
-所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。支持 `--format json|markdown|brief`（全局标志）。
+所有命令支持 `--json` 输出 Envelope v2.0 结构化响应。对 Agent 而言，应始终使用 `--json`。
 
 ## Agent 集成
 
@@ -128,12 +128,10 @@ maxc agent skill --json     # SKILL.md 路径与 min_cli_version
 
 ### 输出格式
 
-`--format` 是全局标志，适用于所有命令：
+对 Agent，统一使用 `--json`：
 
 ```bash
-maxc --format json meta describe my_table      # 结构化 JSON（默认，等价于 --json）
-maxc --format markdown meta describe my_table  # 人类可读 markdown
-maxc --format brief meta describe my_table     # 最小化单行输出（低 token 场景）
+maxc meta describe my_table --json
 ```
 
 ### safety 块

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/tests/test_agent_hints_and_cli.py

@@ -194,7 +194,13 @@ class _StubMetaBackend:
             return tables[:limit], len(tables) > limit
         return tables, False
 
-    def describe_table(self, table_name: 'str', *, project: 'str | None' = None) -> 'TableDefinition':
+    def describe_table(
+        self,
+        table_name: 'str',
+        *,
+        project: 'str | None' = None,
+        schema: 'str | None' = None,
+    ) -> 'TableDefinition':
         time.sleep(0.01)
         return _table(table_name)
 

{maxc_cli-0.4.5 → maxc_cli-0.4.7}/tests/test_backend_data_serialization.py

@@ -134,7 +134,7 @@ class _UploadHarness:
     def describe_table(self, *args, **kwargs) -> TableDefinition:
         return self._definition
 
-    def _table_tunnel(self) -> _FakeTunnel:
+    def _table_tunnel(self, project: 'str | None' = None) -> _FakeTunnel:
         return self._tunnel
 
     def upload(self, *args, **kwargs):