maxc-cli 0.8.2__tar.gz → 0.9.0__tar.gz

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.8.2
+Version: 0.9.0
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -70,7 +70,7 @@ maxc agent doctor --online --json
 |------|------|------|
 | **query** | `query [run]`, `query cost`, `query explain` | SQL 执行、成本估算、执行计划 |
 | **job** | `submit`, `status`, `wait`, `result`, `cancel`, `diagnose`, `list` | 异步任务全生命周期 |
-| **meta** | `list-tables`, `describe`, `search`, `search-columns`, `partitions`, `latest-partition`, `freshness`, `list-projects`, `list-schemas`, `semantic set/get/clear/list-missing` | 元数据发现与语义管理 |
+| **meta** | `list-tables`, `describe`, `list-functions`, `describe-function`, `search`, `search-columns`, `partitions`, `latest-partition`, `freshness`, `list-projects`, `list-schemas`, `semantic set/get/clear/list-missing` | 元数据发现与语义管理 |
 | **data** | `sample`, `profile`, `upload`, `download` | 数据采样、画像与 CSV/TSV 传输 |
 | **auth** | `login`, `login-external`, `logout`, `whoami`, `can-i` | 认证与权限 |
 | **session** | `set`, `show`, `unset` | 项目/Schema 切换 |
@@ -81,6 +81,18 @@ maxc agent doctor --online --json
 使用 `--json`；CSV/NDJSON 行流和 `job wait --stream` 生命周期流是明确例外，
 不会为每条记录重复封装 Envelope。
 
+0.9.0 起支持已注册函数的目录与详情查询：
+
+```bash
+aliyun maxc meta list-functions --project <project> --prefix <prefix> --limit 20 --json
+aliyun maxc meta describe-function <alias> --project <project> --json
+```
+
+三层项目可加 `--schema`；详情参数使用裸函数别名。列表有界分页，详情保留
+类名和原始资源引用，不下载资源内容，也不推断签名或 Python 版本。
+按作者文档确定调用契约后，复用现有 SQL 成本、执行和作业命令引用函数。
+具体流程见 [已注册函数](src/maxc_cli/skills/references/registered-functions.md)。
+
 ## Agent 集成
 
 ### 方式 1：公共 Skill（主路径）

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/README.md

@@ -48,7 +48,7 @@ maxc agent doctor --online --json
 |------|------|------|
 | **query** | `query [run]`, `query cost`, `query explain` | SQL 执行、成本估算、执行计划 |
 | **job** | `submit`, `status`, `wait`, `result`, `cancel`, `diagnose`, `list` | 异步任务全生命周期 |
-| **meta** | `list-tables`, `describe`, `search`, `search-columns`, `partitions`, `latest-partition`, `freshness`, `list-projects`, `list-schemas`, `semantic set/get/clear/list-missing` | 元数据发现与语义管理 |
+| **meta** | `list-tables`, `describe`, `list-functions`, `describe-function`, `search`, `search-columns`, `partitions`, `latest-partition`, `freshness`, `list-projects`, `list-schemas`, `semantic set/get/clear/list-missing` | 元数据发现与语义管理 |
 | **data** | `sample`, `profile`, `upload`, `download` | 数据采样、画像与 CSV/TSV 传输 |
 | **auth** | `login`, `login-external`, `logout`, `whoami`, `can-i` | 认证与权限 |
 | **session** | `set`, `show`, `unset` | 项目/Schema 切换 |
@@ -59,6 +59,18 @@ maxc agent doctor --online --json
 使用 `--json`；CSV/NDJSON 行流和 `job wait --stream` 生命周期流是明确例外，
 不会为每条记录重复封装 Envelope。
 
+0.9.0 起支持已注册函数的目录与详情查询：
+
+```bash
+aliyun maxc meta list-functions --project <project> --prefix <prefix> --limit 20 --json
+aliyun maxc meta describe-function <alias> --project <project> --json
+```
+
+三层项目可加 `--schema`；详情参数使用裸函数别名。列表有界分页，详情保留
+类名和原始资源引用，不下载资源内容，也不推断签名或 Python 版本。
+按作者文档确定调用契约后，复用现有 SQL 成本、执行和作业命令引用函数。
+具体流程见 [已注册函数](src/maxc_cli/skills/references/registered-functions.md)。
+
 ## Agent 集成
 
 ### 方式 1：公共 Skill（主路径）

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.8.2"
+__version__ = "0.9.0"

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli/_samples.py

@@ -85,6 +85,14 @@ SAMPLES: dict[str, str] = {
         "maxc meta describe default.orders --project my_proj\n"
         "maxc meta describe default.orders --project my_proj --full --json"
     ),
+    "meta.list-functions": (
+        "maxc meta list-functions --project my_proj --prefix normalize_ --limit 20 --json\n"
+        "maxc meta list-functions --project my_proj --schema default --limit 20 --json"
+    ),
+    "meta.describe-function": (
+        "maxc meta describe-function normalize_phone --project my_proj --json\n"
+        "maxc meta describe-function normalize_phone --project my_proj --schema default --json"
+    ),
     "meta.search": (
         "maxc meta search orders\n"
         "maxc meta search user --project my_proj --json"

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli/app.py

@@ -44,6 +44,7 @@ from .exceptions import (
     TwoTierNamespaceError,
     ValidationError,
 )
+from .function_metadata import function_cursor, function_offset
 from .helpers import (
     build_odps_identity_payload,
     build_task_summary,
@@ -2023,6 +2024,73 @@ class MaxCApp:
         self.log("job.list", envelope.status, envelope.metadata)
         return envelope
 
+    def meta_list_functions(
+        self,
+        *,
+        schema: 'str | None' = None,
+        project: 'str | None' = None,
+        prefix: 'str | None' = None,
+        limit: int = 50,
+        cursor: 'str | None' = None,
+    ) -> Envelope:
+        if type(limit) is not int or not 1 <= limit <= 1000:
+            raise ValidationError("Function list limit must be between 1 and 1000.")
+        target_project = project or self.config.default_project
+        effective_schema = schema or self.config.default_schema
+        offset = function_offset(cursor, project=target_project, schema=effective_schema, prefix=prefix)
+        rows, has_more = self.backend.list_functions(
+            project=target_project, schema=effective_schema, prefix=prefix, limit=limit, offset=offset,
+        )
+        data = {
+            "functions": [dict(row, project=target_project, schema_name=effective_schema) for row in rows],
+            "pagination": {
+                "returned_count": len(rows),
+                "has_more": has_more,
+                "limit": limit,
+                "offset": offset,
+                "next_cursor": function_cursor(
+                    offset + len(rows), project=target_project, schema=effective_schema, prefix=prefix,
+                ) if has_more else None,
+            },
+        }
+        metadata = {"project": target_project, "schema": effective_schema, "prefix": prefix}
+        envelope = Envelope(
+            command="meta.list-functions", status="success", data=data, metadata=metadata,
+            agent_hints=AgentHints(warnings=[
+                "Catalog pages are live and not a snapshot; registrations can change between calls.",
+                "Function aliases are metadata names, not SQL-qualified references. Verify namespace settings before constructing SQL.",
+            ]),
+        )
+        self.log(envelope.command, envelope.status, metadata)
+        return envelope
+
+    def meta_describe_function(
+        self,
+        function_name: str,
+        *,
+        schema: 'str | None' = None,
+        project: 'str | None' = None,
+    ) -> Envelope:
+        if not function_name or any(char.isspace() or char in ".:/\\" for char in function_name):
+            raise ValidationError(
+                "Pass a bare registered function alias.",
+                suggestion="Select the function's project and schema with --project and --schema.",
+            )
+        target_project = project or self.config.default_project
+        effective_schema = schema or self.config.default_schema
+        detail = self.backend.describe_function(function_name, project=target_project, schema=effective_schema)
+        detail = dict(detail, project=target_project, schema_name=effective_schema)
+        metadata = {"project": target_project, "schema": effective_schema}
+        envelope = Envelope(
+            command="meta.describe-function", status="success", data={"function": detail}, metadata=metadata,
+            agent_hints=AgentHints(warnings=[
+                "Registration metadata does not establish the input/output signature or runtime version. Use the function owner's documentation or verified user context; do not infer them from class or resource names.",
+                "Metadata Read and SQL Execute are separate permissions. A failed describe is not proof that an already-known function cannot be executed.",
+            ]),
+        )
+        self.log(envelope.command, envelope.status, metadata)
+        return envelope
+
     def meta_list_tables(
         self,
         *,

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli/backend/meta.py

@@ -20,6 +20,100 @@ from ..helpers import (
 class MetaMixin:
     """Mixin providing metadata methods."""
 
+    def list_functions(
+        self,
+        *,
+        project: 'str | None' = None,
+        schema: 'str | None' = None,
+        prefix: 'str | None' = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> 'tuple[list[dict[str, Any]], bool]':
+        """Read a bounded catalog window without per-function metadata GETs.
+
+        Args:
+            project: Function project, or the configured project.
+            schema: Explicit function schema, when applicable.
+            prefix: Server-side alias prefix filter.
+            limit: Maximum returned functions.
+            offset: Number of earlier matching catalog entries to skip.
+
+        Returns:
+            Parsed collection rows and whether another matching entry exists.
+        """
+        try:
+            iterator = iter(self.client.list_functions(
+                project=project or self.project, schema=schema, prefix=prefix,
+            ))
+            window = list(islice(iterator, offset, offset + limit + 1))
+            # PyODPS models lazily reload missing fields. Read only parsed
+            # collection fields here so List does not also require Read.
+            rows = [{
+                "function_name": object.__getattribute__(item, "name"),
+                "class_type": object.__getattribute__(item, "class_type"),
+                "owner": object.__getattribute__(item, "_owner"),
+            } for item in window[:limit]]
+            return rows, len(window) > limit
+        except Exception as exc:
+            raise translate_odps_error(exc, "list_functions") from exc
+
+    def describe_function(
+        self,
+        function_name: str,
+        *,
+        project: 'str | None' = None,
+        schema: 'str | None' = None,
+    ) -> 'dict[str, Any]':
+        """Read registration metadata without loading resource contents.
+
+        Args:
+            function_name: Bare registered function alias.
+            project: Function project, or the configured project.
+            schema: Explicit function schema, when applicable.
+
+        Returns:
+            Registration metadata with exact resource references and unknown
+            signature/runtime fields. Implementation code is excluded.
+        """
+        try:
+            function = self.client.get_function(
+                function_name, project=project or self.project, schema=schema,
+            )
+            # get_function is lazy: reload explicitly so missing aliases fail
+            # even when the SDK already knows the requested name.
+            function.reload()
+
+            def read(key: str) -> Any:
+                try:
+                    return object.__getattribute__(function, key)
+                except AttributeError:
+                    # Older supported PyODPS releases omit optional flags.
+                    return None
+
+            return {
+                "function_name": read("name"),
+                "class_type": read("class_type"),
+                "resource_names": list(read("_resources") or []),
+                "owner": read("_owner"),
+                "creation_time": _dt_to_iso(read("creation_time")),
+                "program_language": read("program_language"),
+                "is_sql_function": self._function_boolean(read("is_sql_function")),
+                "is_embedded_function": self._function_boolean(read("is_embedded_function")),
+                "file_name": read("file_name"),
+                "signature": None,
+                "runtime_version": None,
+            }
+        except Exception as exc:
+            raise translate_odps_error(exc, "describe_function") from exc
+
+    @staticmethod
+    def _function_boolean(value: Any) -> 'bool | None':
+        if value is True or str(value).lower() == "true":
+            return True
+        if value is False or str(value).lower() == "false":
+            return False
+        return None
+
     def list_tables(
         self,
         *,

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli/cli.py

@@ -455,6 +455,22 @@ def build_parser() -> argparse.ArgumentParser:
     meta_describe.add_argument("--full", action="store_true", help="Show full column list (default is summary mode)")
     meta_describe.set_defaults(handler=_handle_meta_describe)
 
+    meta_functions = _make_parser(meta_subparsers, "list-functions", "meta.list-functions", help="List registered functions")
+    meta_functions.add_argument("--project", help="Target MaxCompute project")
+    meta_functions.add_argument("--schema", help="Schema name (overrides session default)")
+    meta_functions.add_argument("--prefix", help="Function alias prefix filter")
+    meta_functions.add_argument("--limit", type=positive_int, default=50, help="Maximum functions to return (1-1000; default 50)")
+    meta_functions.add_argument("--cursor", help="Scope-bound cursor returned by the previous function list")
+    meta_functions.add_argument("--json", action="store_true", help="Output as JSON envelope")
+    meta_functions.set_defaults(handler=_handle_meta_list_functions)
+
+    meta_function = _make_parser(meta_subparsers, "describe-function", "meta.describe-function", help="Describe a registered function")
+    meta_function.add_argument("function_name", help="Bare registered alias; select scope with --project / --schema")
+    meta_function.add_argument("--project", help="Target MaxCompute project")
+    meta_function.add_argument("--schema", help="Schema name (overrides session default)")
+    meta_function.add_argument("--json", action="store_true", help="Output as JSON envelope")
+    meta_function.set_defaults(handler=_handle_meta_describe_function)
+
     meta_search = _make_parser(meta_subparsers, "search", "meta.search", help="Search tables")
     meta_search.add_argument("keyword", help="Search keyword")
     meta_search.add_argument("--schema", help="Schema name (overrides session default)")
@@ -2121,6 +2137,18 @@ def _handle_meta_list_tables(app: MaxCApp, args: argparse.Namespace, stdout: Tex
     _emit_envelope(envelope, args=args, stdout=stdout, default_format="table")
 
 
+def _handle_meta_list_functions(app: MaxCApp, args: argparse.Namespace, stdout: TextIO) -> None:
+    envelope = app.meta_list_functions(
+        project=args.project, schema=args.schema, prefix=args.prefix, limit=args.limit, cursor=args.cursor,
+    )
+    _emit_envelope(envelope, args=args, stdout=stdout, default_format="table")
+
+
+def _handle_meta_describe_function(app: MaxCApp, args: argparse.Namespace, stdout: TextIO) -> None:
+    envelope = app.meta_describe_function(args.function_name, project=args.project, schema=args.schema)
+    _emit_envelope(envelope, args=args, stdout=stdout, default_format="table")
+
+
 def _handle_meta_describe(app: MaxCApp, args: argparse.Namespace, stdout: TextIO) -> None:
     # When --json is used, always return full schema (agents need all columns)
     full = args.full or _is_json_mode(args)
@@ -2966,6 +2994,8 @@ def _manifest_effects(command: str) -> list[dict[str, Any]]:
         ),
     ]
     effects_by_command: dict[str, list[dict[str, Any]]] = {
+        "meta.list-functions": [_manifest_effect("remote", "read", "maxcompute_function_catalog")],
+        "meta.describe-function": [_manifest_effect("remote", "read", "maxcompute_function_metadata")],
         "agent.context": [
             _manifest_effect("local", "read", "config_and_runtime_readiness"),
         ],
@@ -4527,6 +4557,12 @@ def _render_human(envelope: Envelope) -> str:
     if command == "meta.list-tables":
         return render_table(data.get("tables", []))
 
+    if command == "meta.list-functions":
+        return render_table(data.get("functions", []))
+
+    if command == "meta.describe-function":
+        return render_key_values(data.get("function", {}))
+
     if command == "meta.describe":
         # Render schema/partition_columns as nested sub-tables instead of
         # JSON-stringifying them into a single cell.
@@ -4593,6 +4629,7 @@ _RECORD_COLLECTION_KEYS: dict[str, tuple[str, str]] = {
     "meta.list-projects": ("projects", "project"),
     "meta.list-schemas": ("schemas", "schema"),
     "meta.list-tables": ("tables", "table"),
+    "meta.list-functions": ("functions", "function"),
     "meta.partitions": ("partitions", "partition"),
     "meta.search": ("matches", "match"),
     "meta.search-columns": ("matches", "match"),
@@ -4605,6 +4642,7 @@ _RECORD_DEFAULT_COLUMNS: dict[str, list[str]] = {
     "job.list": ["job_id", "status", "progress", "project", "submitted_at"],
     "meta.list-projects": ["name"],
     "meta.list-schemas": ["name"],
+    "meta.list-functions": ["function_name", "project", "schema_name", "class_type", "owner"],
     "meta.list-tables": [
         "table_name",
         "schema_name",

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli/exceptions.py

@@ -101,6 +101,20 @@ class MaxCError(Exception):
                 prefix += f" --user-agent {rendered_user_agent}"
             return f"{prefix} {' '.join(parts)}"
 
+        if (self.context or {}).get("metadata_kind") == "function":
+            if self.error_code == "PERMISSION_DENIED":
+                return [
+                    "Verify the selected project, schema, alias, and the operation named in the server error.",
+                    "Use a known function contract for SQL execution only when that task is authorized.",
+                    "Ask the function owner for missing metadata access; keep the current credentials.",
+                ]
+            if self.error_code == "NOT_FOUND":
+                return [
+                    "List functions in the verified scope: " + command("meta", "list-functions", "--project", "<project>", "--json"),
+                    "Add --schema only when the verified function scope requires it.",
+                    "Verify local project and schema: " + command("session", "show", "--json", cloud=False),
+                ]
+
         steps: dict[str, list[str]] = {
             "PERMISSION_DENIED": [
                 "Check the exact object and operation: "

maxc_cli-0.9.0/src/maxc_cli/function_metadata.py

@@ -0,0 +1,36 @@
+"""Scope-bound pagination for registered function discovery."""
+
+import base64
+import json
+from typing import Any
+
+from .exceptions import ValidationError
+
+
+def function_cursor(offset: int, *, project: str, schema: 'str | None', prefix: 'str | None') -> str:
+    payload = {"v": 1, "offset": offset, "project": project, "schema": schema, "prefix": prefix}
+    return base64.urlsafe_b64encode(json.dumps(payload, separators=(",", ":")).encode()).decode()
+
+
+def function_offset(cursor: 'str | None', *, project: str, schema: 'str | None', prefix: 'str | None') -> int:
+    if not cursor:
+        return 0
+    try:
+        if len(cursor) > 8192:
+            raise ValueError("oversized cursor")
+        payload: Any = json.loads(base64.b64decode(cursor, altchars=b"-_", validate=True))
+        if not isinstance(payload, dict) or payload.get("v") != 1:
+            raise ValueError("invalid version")
+        offset = payload.get("offset")
+        if type(offset) is not int or offset < 0:
+            raise ValueError("invalid offset")
+        if any(payload.get(key) != value for key, value in {
+            "project": project, "schema": schema, "prefix": prefix,
+        }.items()):
+            raise ValueError("scope mismatch")
+        return offset
+    except (ValueError, TypeError, UnicodeError) as exc:
+        raise ValidationError(
+            "Invalid function cursor or cursor scope mismatch.",
+            suggestion="Use the returned next_cursor with the same project, schema, and prefix.",
+        ) from exc

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli/helpers.py

@@ -978,9 +978,14 @@ def translate_odps_error(exc: Exception, context: str = "") -> MaxCError:
             return err
         if context in {"job", "get_instance", "instance"} or "instance" in message.lower():
             suggestion = "Verify the job ID with `maxc job list`. Job history may have aged out of the server window."
+        elif context in {"list_functions", "describe_function"}:
+            suggestion = "Verify the registered alias and exact project/schema with `maxc meta list-functions --json`."
         else:
             suggestion = "Run `maxc meta list-tables` or `maxc meta search` to verify the object exists."
-        err = NotFoundError(message, suggestion=suggestion)
+        err = NotFoundError(
+            message, suggestion=suggestion,
+            context={"metadata_kind": "function"} if context in {"list_functions", "describe_function"} else None,
+        )
         err.suggestion = _append_request_id(err.suggestion, exc)
         return err
 
@@ -1134,6 +1139,17 @@ def _build_permission_error(
     """
     dev_hint = _dev_project_hint(project_name)
 
+    if context in {"list_functions", "describe_function"}:
+        operation = "project List" if context == "list_functions" else "Function Read"
+        return PermissionDeniedError(
+            message,
+            suggestion=(
+                f"Verify {operation} permission in the selected project/schema. "
+                "Metadata access and Function Execute are separate; keep the current identity."
+            ),
+            context={"metadata_kind": "function", "operation": operation},
+        )
+
     if context == "list_projects" and project_name:
         suggestion = f"Verify that your account has `odps:Read` on project {project_name}, or contact the project owner."
         if dev_hint:

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli/models.py

@@ -22,11 +22,13 @@ _CLOUD_ACTION_IDS = frozenset({
     "auth.whoami",
     "cache.build",
     "meta.describe",
+    "meta.describe-function",
     "meta.freshness",
     "meta.latest-partition",
     "meta.list-projects",
     "meta.list-schemas",
     "meta.list-tables",
+    "meta.list-functions",
     "meta.partitions",
     "meta.search",
     "meta.search-columns",
@@ -498,9 +500,11 @@ _ACTION_TITLES: 'dict[str, str]' = {
     "job.diagnose": "Diagnose job",
     "job.list": "List jobs",
     "meta.describe": "Describe table",
+    "meta.describe-function": "Describe registered function",
     "meta.search": "Search tables",
     "meta.search-columns": "Search columns",
     "meta.list-tables": "List tables",
+    "meta.list-functions": "List registered functions",
     "meta.list-projects": "List projects",
     "meta.list-schemas": "List schemas",
     "meta.partitions": "List partitions",

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli/skills/SKILL.md

@@ -15,7 +15,7 @@ standalone console script is unavailable<!-- @endif -->.
 
 Use this Skill when the user wants to:
 
-- find a project, schema, table, column, or partition;
+- find a project, schema, table, column, partition, or registered function;
 - look up documented MaxCompute behaviour, SQL syntax, hints, flags, or error-code
   meaning with a citable source;
 - inspect or profile table data;
@@ -156,6 +156,7 @@ Important data paths:
 | auth whoami | `data.identity` |
 | auth can-i | `data.authorization` |
 | meta describe | `data.table` |
+| meta list-functions / describe-function | `data.functions`, `data.pagination` / `data.function` |
 | data sample / profile | `data.sample` / `data.profile` |
 | async submission | `metadata.job_id` |
 
@@ -236,6 +237,16 @@ only with values verified from the user, context, or prior command output.
 {{cli}} data profile <table> --partition <spec> --user-agent "$UA" --json
 ```
 
+### Use An Already Registered Function
+
+Read [registered-functions.md](references/registered-functions.md) when a SQL
+task references a user UDF, UDAF, or UDTF. Use `meta list-functions` for scoped
+discovery and `meta describe-function` for registration metadata. Obtain the
+call signature, function kind, and runtime requirements from verified user
+context or the owner's documentation before composing SQL. Execute through
+the existing `query cost`, `query`, and `job` workflow with the same SQL and
+settings; this workflow does not upload resources or register functions.
+
 ### Knowledge Base Lookup
 
 `kb ask` answers a natural-language MaxCompute question; `kb search` returns
@@ -338,7 +349,8 @@ For substantial SQL generation, load only the reference matching the task:
 ## Capability Boundaries
 
 - The CLI does not grant permissions or enumerate a complete permission graph.
-- It does not provide lineage, resource artifact upload, dedicated UDF
+- It provides registered function metadata, but not automatic signature or
+  runtime-version discovery, lineage, resource artifact upload, dedicated UDF
   lifecycle commands, or an active mock data backend. A supported, exact SQL
   function DDL remains subject to the one-statement `--force` boundary.
 - Tunnel upload/download is single-process and primitive-type oriented; use a

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli/skills/references/command-patterns.md

@@ -74,6 +74,8 @@ pipelines, redirections, and shell substitutions are not supported.
 {{cli}} meta freshness your_table --json
 {{cli}} meta list-projects --json
 {{cli}} meta list-schemas --project your_project --json
+{{cli}} meta list-functions --project your_project --prefix normalize_ --limit 20 --json
+{{cli}} meta describe-function normalize_phone --project your_project --json
 {{cli}} data sample your_table --rows 5 --partition ds=2026-03-20 --columns id,ds --json
 {{cli}} data profile your_table --partition ds=2026-03-20 --json
 {{cli}} data upload your_table --file ./rows.csv --partition ds=2026-03-20 --overwrite --json
@@ -83,6 +85,11 @@ pipelines, redirections, and shell substitutions are not supported.
 - All meta and data commands accept `--project` for one-off cross-project access without switching session.
 - Most meta commands support `--schema` to override the session default.
 
+For function references in SQL, follow [registered-functions.md](registered-functions.md).
+`meta list-functions` is bounded and accepts a scope-bound `--cursor`;
+`meta describe-function` takes a bare alias with explicit project/schema flags.
+Neither reads resource contents or infers a call signature.
+
 ### Bulk CSV Upload / Download
 
 `data upload` and `data download` move CSV/TSV between local files and an existing table or partition via the PyODPS Tunnel API (no SQL CU consumed).

maxc_cli-0.9.0/src/maxc_cli/skills/references/registered-functions.md

@@ -0,0 +1,78 @@
+# Reference already registered functions
+
+Use this workflow for an existing MaxCompute function. Registration and resource
+publication belong to a separately authorized task. Commands require MaxC 0.9.0
+or later. Reuse the session User-Agent from SKILL.md.
+
+## Resolve the function and its contract
+
+1. Establish the SQL execution project separately from the function's project.
+   Use verified project/schema values. `meta list-schemas` can establish the
+   namespace model; a denied schema lookup is not evidence of a two-tier project.
+2. If the registered alias is known, describe it directly. Otherwise, list a
+   bounded page in the relevant scope with an optional alias prefix:
+
+   ```bash
+   {{cli}} meta list-functions --project <function-project> --prefix <prefix> --limit 20 --user-agent "$UA" --json
+   {{cli}} meta describe-function <function-alias> --project <function-project> --user-agent "$UA" --json
+   ```
+
+   Add `--schema <verified-schema>` for a schema-scoped function. Describe takes
+   a bare alias, not a SQL-qualified reference. List returns `data.functions`
+   and `data.pagination`; reuse `next_cursor` with the same project, schema,
+   and prefix. Limit is 1–1000 (default 50). Pages are live catalog windows,
+   not a snapshot; offset pagination can rescan earlier entries. A list reads
+   collection metadata only, without per-function Read requests or resource
+   downloads. Missing fields remain null. An empty page establishes no visible
+   matching functions in that scope, not global absence.
+3. Describe returns `data.function`: alias, implementation class, exact resource
+   references, owner, creation time, and additional registration flags if the
+   service supplies them. It excludes implementation code and resource contents.
+   `signature` and `runtime_version` remain null: class names, filenames, and
+   creation times do not establish a signature, Python version, function kind,
+   business definition, or immutable implementation version.
+4. Obtain UDF/UDAF/UDTF kind, overload/input/output types, output column names
+   for UDTF, NULL behavior when relevant, and required settings from the owner's
+   documentation, a trusted semantic definition, or verified user SQL. Ask only
+   for missing facts that affect the call. Disambiguate same-name candidates.
+   A user with known SQL and Function Execute can proceed even if Function Read
+   or project List is denied. Preserve the permission error; do not relabel it
+   as an absent function or switch credentials.
+
+## Generate and execute the SQL
+
+The function's namespace creation mode must match the execution mode.
+Two-tier cross-project calls use `project:function(...)`. Three-tier objects
+use `project.schema.function(...)`, or `schema.function(...)` within one
+project. Verify the syntax in the actual project; do not mechanically rewrite
+colon references into dotted references. Never enable schema mode merely
+because the default schema is named `default`.
+
+Preserve author-required leading SET statements in the SQL file for both cost
+and execution. For example, a Python 3.11 function can require
+`SET odps.sql.python.version=cp311;`. Do not apply that version to every Python
+function. Conflicting Python or namespace requirements need resolution before
+submission. See the official [schema operations](https://help.aliyun.com/zh/maxcompute/schema-related-operations)
+and [Python 3 UDF documentation](https://help.aliyun.com/zh/maxcompute/python-3-udfs).
+
+Use a scalar UDF as an expression, UDAF in the correct aggregation grain, and
+UDTF with the correct output shape (often `LATERAL VIEW`). Use explicit casts
+only when the contract supports them. For a newly integrated function, prefer
+constant inputs or a known small partition for a first check; `LIMIT` alone
+does not bound scan work or UDF invocations.
+
+```bash
+{{cli}} query cost --file <verified-query.sql> --project <execution-project> --user-agent "$UA" --json
+{{cli}} query --file <verified-query.sql> --project <execution-project> --wait 0 --user-agent "$UA" --json
+{{cli}} job wait <job-id> --project <execution-project> --user-agent "$UA" --json
+```
+
+Apply the existing cost/authorization gates. Cost or EXPLAIN success is a
+planning check, not proof that the UDF runs correctly. Wait for the job's
+terminal state and verify result values, types, and cardinality. If another
+result page is needed, use the returned cursor without resubmitting the SQL.
+Retain the submitted SQL, settings, function scope, contract source, instance
+ID, and actual result in the requested delivery. Function Execute and dependent
+resource access are decided by MaxCompute under the configured caller identity.
+Report permission, signature, missing dependency, namespace, and runtime errors
+as distinct failures; do not repair them by registering a replacement function.

{maxc_cli-0.8.2 → maxc_cli-0.9.0}/src/maxc_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.8.2
+Version: 0.9.0
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -70,7 +70,7 @@ maxc agent doctor --online --json
 |------|------|------|
 | **query** | `query [run]`, `query cost`, `query explain` | SQL 执行、成本估算、执行计划 |
 | **job** | `submit`, `status`, `wait`, `result`, `cancel`, `diagnose`, `list` | 异步任务全生命周期 |
-| **meta** | `list-tables`, `describe`, `search`, `search-columns`, `partitions`, `latest-partition`, `freshness`, `list-projects`, `list-schemas`, `semantic set/get/clear/list-missing` | 元数据发现与语义管理 |
+| **meta** | `list-tables`, `describe`, `list-functions`, `describe-function`, `search`, `search-columns`, `partitions`, `latest-partition`, `freshness`, `list-projects`, `list-schemas`, `semantic set/get/clear/list-missing` | 元数据发现与语义管理 |
 | **data** | `sample`, `profile`, `upload`, `download` | 数据采样、画像与 CSV/TSV 传输 |
 | **auth** | `login`, `login-external`, `logout`, `whoami`, `can-i` | 认证与权限 |
 | **session** | `set`, `show`, `unset` | 项目/Schema 切换 |
@@ -81,6 +81,18 @@ maxc agent doctor --online --json
 使用 `--json`；CSV/NDJSON 行流和 `job wait --stream` 生命周期流是明确例外，
 不会为每条记录重复封装 Envelope。
 
+0.9.0 起支持已注册函数的目录与详情查询：
+
+```bash
+aliyun maxc meta list-functions --project <project> --prefix <prefix> --limit 20 --json
+aliyun maxc meta describe-function <alias> --project <project> --json
+```
+
+三层项目可加 `--schema`；详情参数使用裸函数别名。列表有界分页，详情保留
+类名和原始资源引用，不下载资源内容，也不推断签名或 Python 版本。
+按作者文档确定调用契约后，复用现有 SQL 成本、执行和作业命令引用函数。
+具体流程见 [已注册函数](src/maxc_cli/skills/references/registered-functions.md)。
+
 ## Agent 集成
 
 ### 方式 1：公共 Skill（主路径）