web-presentation-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{web_presentation_cli-0.1.0 → web_presentation_cli-0.1.1}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.5
 Name: web-presentation-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Web Presentation CLI - 面向 AI 演示文稿创作平台的命令行与 Agent 工具包
 Project-URL: Homepage, https://github.com/LLMxPM/web-presentation-agent-kit
 Project-URL: Repository, https://github.com/LLMxPM/web-presentation-agent-kit
 Project-URL: Issues, https://github.com/LLMxPM/web-presentation-agent-kit/issues
+License: Apache-2.0
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1.7
 Requires-Dist: httpx>=0.27.0
@@ -55,10 +56,11 @@ wp component list --scope suggested --project-id <project_id>
 wp asset content get <asset_id>
 wp theme list
 wp style list
-wp --json guide list
 wp job wait <job_id>
 ```
 
 复杂写入参数使用 `--payload-file`、`--edits-file`、`--content-file`、`--route-file` 和 `--ids-file`。Build、产物下载、Agent 运行、图片能力、Restore 和 MCP 不属于当前 CLI。
 
+叶子命令的 `--help` 会从当前 Profile 的 Backend `/openapi.json` 加载请求参数和完整 Schema；服务不可达时仍返回本地语法帮助，不缓存 Schema。
+
 写入命令支持 `--idempotency-key <key>`；网络超时后需要重放同一业务请求时复用原 key，不要把同一个 key 用于不同请求。

{web_presentation_cli-0.1.0 → web_presentation_cli-0.1.1}/README.md

@@ -41,10 +41,11 @@ wp component list --scope suggested --project-id <project_id>
 wp asset content get <asset_id>
 wp theme list
 wp style list
-wp --json guide list
 wp job wait <job_id>
 ```
 
 复杂写入参数使用 `--payload-file`、`--edits-file`、`--content-file`、`--route-file` 和 `--ids-file`。Build、产物下载、Agent 运行、图片能力、Restore 和 MCP 不属于当前 CLI。
 
+叶子命令的 `--help` 会从当前 Profile 的 Backend `/openapi.json` 加载请求参数和完整 Schema；服务不可达时仍返回本地语法帮助，不缓存 Schema。
+
 写入命令支持 `--idempotency-key <key>`；网络超时后需要重放同一业务请求时复用原 key，不要把同一个 key 用于不同请求。

{web_presentation_cli-0.1.0 → web_presentation_cli-0.1.1}/pyproject.toml

@@ -4,9 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "web-presentation-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Web Presentation CLI - 面向 AI 演示文稿创作平台的命令行与 Agent 工具包"
 readme = "README.md"
+license = { text = "Apache-2.0" }
 requires-python = ">=3.11"
 dependencies = [
     "click>=8.1.7",

{web_presentation_cli-0.1.0 → web_presentation_cli-0.1.1}/src/wp/__init__.py

@@ -1,3 +1,3 @@
 """Web Presentation 官方命令行工具包。"""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{web_presentation_cli-0.1.0 → web_presentation_cli-0.1.1}/src/wp/cli.py

@@ -17,7 +17,7 @@ from wp.commands.project import project_group
 from wp.commands.style import style_group
 from wp.commands.theme import theme_group
 from wp.commands.workspace import workspace_group
-from wp.commands.system import guide_group, standards_group, system_group
+from wp.commands.system import standards_group, system_group
 
 
 @click.group()
@@ -48,7 +48,6 @@ main.add_command(doctor_cmd)
 main.add_command(profile_group)
 main.add_command(system_group)
 main.add_command(standards_group)
-main.add_command(guide_group)
 main.add_command(runtime_kit_group)
 main.add_command(font_group)
 

{web_presentation_cli-0.1.0 → web_presentation_cli-0.1.1}/src/wp/client.py

@@ -19,7 +19,7 @@ class ApiClient(SharedApiClient):
             endpoint=profile.endpoint,
             token=profile.token,
             workspace_id=workspace_id or profile.default_workspace_id,
-            user_agent="web-presentation-cli/0.1.0",
+            user_agent="web-presentation-cli/0.1.1",
             idempotency_key=idempotency_key,
         )
 

{web_presentation_cli-0.1.0 → web_presentation_cli-0.1.1}/src/wp/commands/asset.py

@@ -15,11 +15,11 @@ from wp.commands.common import (
     output_result,
     read_json_file,
     read_text_file,
-    require_array,
     require_ids,
     require_object,
 )
 from wp.formatter import print_table
+from wp.openapi_help import contract, openapi_command
 
 
 ASSET_TYPES = ["image", "icon", "font", "video", "drawio", "mermaid", "chart", "formula"]
@@ -30,11 +30,11 @@ def asset_group() -> None:
     """工作空间静态资源管理。"""
 
 
-@asset_group.command("list")
-@click.option("--page", default=1, type=int)
-@click.option("--page-size", default=50, type=int)
-@click.option("--type", "asset_type", type=click.Choice(ASSET_TYPES))
-@click.option("--keyword")
+@openapi_command(asset_group, "list", contract("GET", "/api/v1/assets"))
+@click.option("--page", default=1, type=int, show_default=True, help="结果页码")
+@click.option("--page-size", default=50, type=int, show_default=True, help="每页返回数量")
+@click.option("--type", "asset_type", type=click.Choice(ASSET_TYPES), help="按资源业务类型筛选")
+@click.option("--keyword", help="按资源名称、说明或标签搜索")
 @click.pass_context
 def list_assets_cmd(ctx: click.Context, page: int, page_size: int, asset_type: str | None, keyword: str | None) -> None:
     """查询工作空间资源。"""
@@ -51,7 +51,7 @@ def list_assets_cmd(ctx: click.Context, page: int, page_size: int, asset_type: s
         handle_api_error("获取资源列表失败", err)
 
 
-@asset_group.command("get")
+@openapi_command(asset_group, "get", contract("GET", "/api/v1/assets/{asset_id}"))
 @click.argument("asset_id", type=int)
 @click.pass_context
 def get_asset_cmd(ctx: click.Context, asset_id: int) -> None:
@@ -63,11 +63,16 @@ def get_asset_cmd(ctx: click.Context, asset_id: int) -> None:
         handle_api_error("获取资源详情失败", err)
 
 
-@asset_group.command("upload")
+@openapi_command(
+    asset_group,
+    "upload",
+    contract("POST", "/api/v1/assets"),
+    examples=("wp asset upload ./hero.png --type image --name hero-image --idempotency-key asset-hero-image",),
+)
 @click.argument("file_path", type=click.Path(exists=True, dir_okay=False))
-@click.option("--type", "asset_type", type=click.Choice(ASSET_TYPES), required=True)
-@click.option("--name")
-@click.option("--description")
+@click.option("--type", "asset_type", type=click.Choice(ASSET_TYPES), required=True, help="上传资源类型")
+@click.option("--name", help="平台逻辑名；默认使用文件名主干")
+@click.option("--description", help="资源内容、来源和使用场景说明")
 @idempotency_key_option
 @click.pass_context
 def upload_asset_cmd(ctx: click.Context, file_path: str, asset_type: str, name: str | None, description: str | None) -> None:
@@ -86,8 +91,13 @@ def upload_asset_cmd(ctx: click.Context, file_path: str, asset_type: str, name:
         handle_api_error("上传资源失败", err)
 
 
-@asset_group.command("create")
-@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@openapi_command(
+    asset_group,
+    "create",
+    contract("POST", "/api/v1/assets/content"),
+    examples=("wp asset create --payload-file ./asset.json --content-file ./diagram.mmd --idempotency-key asset-diagram",),
+)
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True, help="文本资源创建 JSON 请求体")
 @click.option("--content-file", type=click.Path(exists=True, dir_okay=False), help="覆盖 JSON 中 content 的文本文件")
 @idempotency_key_option
 @click.pass_context
@@ -108,7 +118,7 @@ def asset_content_group() -> None:
     """可编辑文本资源内容。"""
 
 
-@asset_content_group.command("get")
+@openapi_command(asset_content_group, "get", contract("GET", "/api/v1/assets/{asset_id}/content"))
 @click.argument("asset_id", type=int)
 @click.pass_context
 def get_asset_content_cmd(ctx: click.Context, asset_id: int) -> None:
@@ -120,10 +130,10 @@ def get_asset_content_cmd(ctx: click.Context, asset_id: int) -> None:
         handle_api_error("读取资源内容失败", err)
 
 
-@asset_content_group.command("update")
+@openapi_command(asset_content_group, "update", contract("PUT", "/api/v1/assets/{asset_id}/content"))
 @click.argument("asset_id", type=int)
-@click.option("--content-file", type=click.Path(exists=True, dir_okay=False), required=True)
-@click.option("--change-note")
+@click.option("--content-file", type=click.Path(exists=True, dir_okay=False), required=True, help="要写入的完整 UTF-8 文本内容")
+@click.option("--change-note", help="本次完整内容替换的变更说明")
 @idempotency_key_option
 @click.pass_context
 def update_asset_content_cmd(ctx: click.Context, asset_id: int, content_file: str, change_note: str | None) -> None:
@@ -135,9 +145,9 @@ def update_asset_content_cmd(ctx: click.Context, asset_id: int, content_file: st
         handle_api_error("更新资源内容失败", err)
 
 
-@asset_content_group.command("preview")
+@openapi_command(asset_content_group, "preview", contract("POST", "/api/v1/assets/{asset_id}/content/preview"))
 @click.argument("asset_id", type=int)
-@click.option("--content-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@click.option("--content-file", type=click.Path(exists=True, dir_okay=False), required=True, help="用于生成差异且不会写入的候选 UTF-8 文本")
 @click.pass_context
 def preview_asset_content_cmd(ctx: click.Context, asset_id: int, content_file: str) -> None:
     """预览资源文本内容差异。"""
@@ -153,8 +163,8 @@ def asset_tags_group() -> None:
     """资源标签。"""
 
 
-@asset_tags_group.command("list")
-@click.option("--type", "asset_type", type=click.Choice(ASSET_TYPES))
+@openapi_command(asset_tags_group, "list", contract("GET", "/api/v1/assets/tags"))
+@click.option("--type", "asset_type", type=click.Choice(ASSET_TYPES), help="只返回指定资源类型使用的标签")
 @click.pass_context
 def list_asset_tags_cmd(ctx: click.Context, asset_type: str | None) -> None:
     """列出工作空间资源标签。"""
@@ -166,9 +176,9 @@ def list_asset_tags_cmd(ctx: click.Context, asset_type: str | None) -> None:
         handle_api_error("获取资源标签失败", err)
 
 
-@asset_group.command("update")
+@openapi_command(asset_group, "update", contract("PATCH", "/api/v1/assets/{asset_id}"))
 @click.argument("asset_id", type=int)
-@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True, help="资源元数据更新 JSON 请求体")
 @idempotency_key_option
 @click.pass_context
 def update_asset_cmd(ctx: click.Context, asset_id: int, payload_file: str) -> None:
@@ -180,9 +190,9 @@ def update_asset_cmd(ctx: click.Context, asset_id: int, payload_file: str) -> No
         handle_api_error("更新资源失败", err)
 
 
-@asset_group.command("copy")
+@openapi_command(asset_group, "copy", contract("POST", "/api/v1/assets/{asset_id}/copy"))
 @click.argument("asset_id", type=int)
-@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True, help="资源副本名称、说明等 JSON 请求体")
 @idempotency_key_option
 @click.pass_context
 def copy_asset_cmd(ctx: click.Context, asset_id: int, payload_file: str) -> None:
@@ -194,14 +204,19 @@ def copy_asset_cmd(ctx: click.Context, asset_id: int, payload_file: str) -> None
         handle_api_error("复制资源失败", err)
 
 
-@asset_group.command("archive")
+@openapi_command(
+    asset_group,
+    "archive",
+    contract("POST", "/api/v1/assets/{asset_id}/archive", "提供 ASSET_ID 时"),
+    contract("POST", "/api/v1/assets/batch-archive", "提供 --ids-file 时"),
+)
 @click.argument("asset_id", type=int, required=False)
-@click.option("--ids-file", type=click.Path(exists=True, dir_okay=False))
-@click.option("--yes", is_flag=True)
+@click.option("--ids-file", type=click.Path(exists=True, dir_okay=False), help="批量归档的正整数 ID JSON 数组")
+@click.option("--yes", is_flag=True, help="仅在用户已明确授权归档时跳过交互确认")
 @idempotency_key_option
 @click.pass_context
 def archive_asset_cmd(ctx: click.Context, asset_id: int | None, ids_file: str | None, yes: bool) -> None:
-    """归档单个或一批资源。"""
+    """归档单个资源或 JSON 数组指定的一批资源；两种目标输入只能选一种。"""
 
     try:
         client = get_client(ctx)

{web_presentation_cli-0.1.0 → web_presentation_cli-0.1.1}/src/wp/commands/catalog.py

@@ -6,6 +6,7 @@ import click
 
 from wp.client import ApiClientError
 from wp.commands.common import get_client, handle_api_error, output_result
+from wp.openapi_help import contract, openapi_command
 
 
 @click.group("runtime-kit")
@@ -13,13 +14,13 @@ def runtime_kit_group() -> None:
     """Runtime Kit 公开能力目录。"""
 
 
-@runtime_kit_group.command("list")
-@click.option("--keyword")
-@click.option("--category")
-@click.option("--kind")
-@click.option("--base-name")
-@click.option("--version-no", type=int)
-@click.option("--include-all-versions", is_flag=True)
+@openapi_command(runtime_kit_group, "list", contract("GET", "/api/v1/runtime-kit"))
+@click.option("--keyword", help="按名称、说明或导入路径搜索")
+@click.option("--category", help="按服务端返回的能力分类筛选")
+@click.option("--kind", help="按能力类型筛选，例如 component、composable、util 或 type")
+@click.option("--base-name", help="按不含版本号的能力基础名称筛选")
+@click.option("--version-no", type=int, help="筛选指定公开版本号")
+@click.option("--include-all-versions", is_flag=True, help="返回所有公开版本；默认只返回推荐版本")
 @click.pass_context
 def runtime_kit_list_cmd(
     ctx: click.Context,
@@ -50,7 +51,7 @@ def runtime_kit_list_cmd(
         handle_api_error("获取 Runtime Kit 目录失败", err)
 
 
-@runtime_kit_group.command("get")
+@openapi_command(runtime_kit_group, "get", contract("GET", "/api/v1/runtime-kit/{item}"))
 @click.argument("item")
 @click.pass_context
 def runtime_kit_get_cmd(ctx: click.Context, item: str) -> None:
@@ -67,10 +68,10 @@ def font_group() -> None:
     """工作空间注册字体目录。"""
 
 
-@font_group.command("list")
-@click.option("--page", default=1, type=int)
-@click.option("--page-size", default=50, type=int)
-@click.option("--keyword")
+@openapi_command(font_group, "list", contract("GET", "/api/v1/fonts"))
+@click.option("--page", default=1, type=int, show_default=True, help="结果页码")
+@click.option("--page-size", default=50, type=int, show_default=True, help="每页返回数量")
+@click.option("--keyword", help="按字体名称或逻辑名搜索")
 @click.pass_context
 def font_list_cmd(ctx: click.Context, page: int, page_size: int, keyword: str | None) -> None:
     """查询工作空间注册字体。"""

{web_presentation_cli-0.1.0 → web_presentation_cli-0.1.1}/src/wp/commands/component.py

@@ -21,6 +21,7 @@ from wp.commands.common import (
 )
 from wp.config import get_profile, load_config
 from wp.formatter import print_table
+from wp.openapi_help import contract, openapi_command
 
 
 @click.group("component")
@@ -28,12 +29,12 @@ def component_group() -> None:
     """工作空间组件管理与 Mutation 任务。"""
 
 
-@component_group.command("list")
-@click.option("--page", default=1, type=int)
-@click.option("--page-size", default=50, type=int)
-@click.option("--keyword")
-@click.option("--scope", type=click.Choice(["all", "suggested"]), default="all")
-@click.option("--project-id", type=int)
+@openapi_command(component_group, "list", contract("GET", "/api/v1/components"))
+@click.option("--page", default=1, type=int, show_default=True, help="结果页码")
+@click.option("--page-size", default=50, type=int, show_default=True, help="每页返回数量")
+@click.option("--keyword", help="按名称、导入标识或摘要搜索")
+@click.option("--scope", type=click.Choice(["all", "suggested"]), default="all", show_default=True, help="查询全部组件或指定项目的建议组件")
+@click.option("--project-id", type=int, help="scope=suggested 时必填的项目 ID")
 @click.pass_context
 def list_components_cmd(ctx: click.Context, page: int, page_size: int, keyword: str | None, scope: str, project_id: int | None) -> None:
     """查询工作空间组件或项目建议组件。"""
@@ -55,7 +56,7 @@ def list_components_cmd(ctx: click.Context, page: int, page_size: int, keyword:
         handle_api_error("获取组件列表失败", err)
 
 
-@component_group.command("get")
+@openapi_command(component_group, "get", contract("GET", "/api/v1/components/{component_id}"))
 @click.argument("component_id", type=int)
 @click.pass_context
 def get_component_cmd(ctx: click.Context, component_id: int) -> None:
@@ -67,16 +68,21 @@ def get_component_cmd(ctx: click.Context, component_id: int) -> None:
         handle_api_error("获取组件失败", err)
 
 
-@component_group.command("create")
-@click.option("--name")
-@click.option("--import-name")
-@click.option("--file", "file_path", type=click.Path(exists=True, dir_okay=False))
-@click.option("--type", "component_type", default="content")
-@click.option("--description")
-@click.option("--preview-schema-file", type=click.Path(exists=True, dir_okay=False))
-@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False))
-@click.option("--wait/--no-wait", default=True)
-@click.option("--timeout", type=float, default=120.0, show_default=True)
+@openapi_command(
+    component_group,
+    "create",
+    contract("POST", "/api/v1/components"),
+    examples=('wp component create --name "指标卡" --import-name MetricCard --file ./MetricCard.vue --type content --idempotency-key component-metric-card',),
+)
+@click.option("--name", help="组件显示名称；直接参数模式必填")
+@click.option("--import-name", help="稳定导入标识；直接参数模式必填")
+@click.option("--file", "file_path", type=click.Path(exists=True, dir_okay=False), help="完整 Vue 3 SFC 文件；直接参数模式必填")
+@click.option("--type", "component_type", default="content", show_default=True, help="组件类型：content、page、atomic 或服务端兼容别名")
+@click.option("--description", help="组件用途和复用边界说明")
+@click.option("--preview-schema-file", type=click.Path(exists=True, dir_okay=False), help="覆盖请求体 preview_schema 的 JSON 对象")
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), help="完整组件创建 JSON 请求体；提供后忽略其它内容参数")
+@click.option("--wait/--no-wait", default=True, help="等待任务终态；--no-wait 只返回入队结果")
+@click.option("--timeout", type=float, default=120.0, show_default=True, help="等待任务终态的最长秒数")
 @idempotency_key_option
 @click.pass_context
 def create_component_cmd(
@@ -91,7 +97,7 @@ def create_component_cmd(
     wait: bool,
     timeout: float,
 ) -> None:
-    """提交组件创建 Mutation Job。"""
+    """提交组件创建 Mutation Job；直接参数模式必须提供名称、导入标识和完整 SFC。"""
 
     profile = get_profile(load_config(), ctx.obj.get("profile"))
     workspace_id = ctx.obj.get("workspace_id") or profile.default_workspace_id
@@ -122,12 +128,18 @@ def create_component_cmd(
         handle_api_error("提交组件创建失败", err)
 
 
-@component_group.command("update")
+@openapi_command(
+    component_group,
+    "update",
+    contract("PATCH", "/api/v1/components/{component_id}", "仅更新 name 或 summary 时"),
+    contract("POST", "/api/v1/jobs/mutations/components/metadata", "包含 import_name、component_type 或 preview_schema 时"),
+    examples=("wp component update 15 --payload-file ./component-update.json --idempotency-key component-15-metadata",),
+)
 @click.argument("component_id", type=int)
-@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True)
+@click.option("--payload-file", type=click.Path(exists=True, dir_okay=False), required=True, help="组件元数据 JSON 请求体；复杂字段会自动进入异步任务")
 @click.option("--preview-schema-file", type=click.Path(exists=True, dir_okay=False), help="覆盖 payload 中的 Preview Schema JSON")
-@click.option("--wait/--no-wait", default=True)
-@click.option("--timeout", type=float, default=120.0, show_default=True)
+@click.option("--wait/--no-wait", default=True, help="复杂字段更新时等待任务终态；轻量更新忽略此选项")
+@click.option("--timeout", type=float, default=120.0, show_default=True, help="等待复杂字段更新任务的最长秒数")
 @idempotency_key_option
 @click.pass_context
 def update_component_cmd(
@@ -160,13 +172,18 @@ def update_component_cmd(
         handle_api_error("更新组件失败", err)
 
 
-@component_group.command("edit")
+@openapi_command(
+    component_group,
+    "edit",
+    contract("POST", "/api/v1/components/{component_id}/edits"),
+    examples=("wp component edit 15 --base-version-no 2 --base-draft-hash <hash> --edits-file ./edits.json --idempotency-key component-15-edit",),
+)
 @click.argument("component_id", type=int)
-@click.option("--edits-file", type=click.Path(exists=True, dir_okay=False), required=True)
-@click.option("--base-version-no", type=int, required=True)
-@click.option("--base-draft-hash", required=True)
-@click.option("--wait/--no-wait", default=True)
-@click.option("--timeout", type=float, default=120.0, show_default=True)
+@click.option("--edits-file", type=click.Path(exists=True, dir_okay=False), required=True, help="结构化编辑 JSON 数组；完整字段以当前 OpenAPI Schema 为准")
+@click.option("--base-version-no", type=int, required=True, help="component get 返回的最新发布版本基线")
+@click.option("--base-draft-hash", required=True, help="component get 返回的最新草稿哈希基线")
+@click.option("--wait/--no-wait", default=True, help="等待任务终态；--no-wait 只返回入队结果")
+@click.option("--timeout", type=float, default=120.0, show_default=True, help="等待任务终态的最长秒数")
 @idempotency_key_option
 @click.pass_context
 def edit_component_cmd(ctx: click.Context, component_id: int, edits_file: str, base_version_no: int, base_draft_hash: str, wait: bool, timeout: float) -> None:
@@ -189,7 +206,7 @@ def component_version_group() -> None:
     """组件历史发布版本。"""
 
 
-@component_version_group.command("list")
+@openapi_command(component_version_group, "list", contract("GET", "/api/v1/components/{component_id}/versions"))
 @click.argument("component_id", type=int)
 @click.pass_context
 def list_component_versions_cmd(ctx: click.Context, component_id: int) -> None:
@@ -201,7 +218,7 @@ def list_component_versions_cmd(ctx: click.Context, component_id: int) -> None:
         handle_api_error("获取组件版本失败", err)
 
 
-@component_version_group.command("get")
+@openapi_command(component_version_group, "get", contract("GET", "/api/v1/components/{component_id}/versions/{version_no}"))
 @click.argument("component_id", type=int)
 @click.argument("version_no", type=int)
 @click.pass_context
@@ -214,7 +231,7 @@ def get_component_version_cmd(ctx: click.Context, component_id: int, version_no:
         handle_api_error("获取组件版本内容失败", err)
 
 
-@component_group.command("dependencies")
+@openapi_command(component_group, "dependencies", contract("GET", "/api/v1/components/{component_id}/dependencies"))
 @click.argument("component_id", type=int)
 @click.pass_context
 def component_dependencies_cmd(ctx: click.Context, component_id: int) -> None:
@@ -226,13 +243,18 @@ def component_dependencies_cmd(ctx: click.Context, component_id: int) -> None:
         handle_api_error("获取组件依赖失败", err)
 
 
-@component_group.command("validate")
+@openapi_command(
+    component_group,
+    "validate",
+    contract("POST", "/api/v1/validate/entity"),
+    examples=("wp --json component validate 15 --mode content --source-file ./MetricCard.vue --detail",),
+)
 @click.argument("component_id", type=int)
-@click.option("--mode", type=click.Choice(["current", "content", "edits"]), default="current")
-@click.option("--source-file", type=click.Path(exists=True, dir_okay=False))
-@click.option("--edits-file", type=click.Path(exists=True, dir_okay=False))
-@click.option("--preview-schema-file", type=click.Path(exists=True, dir_okay=False))
-@click.option("--detail", is_flag=True)
+@click.option("--mode", type=click.Choice(["current", "content", "edits"]), default="current", show_default=True, help="校验当前草稿、完整候选源码或结构化 edits")
+@click.option("--source-file", type=click.Path(exists=True, dir_okay=False), help="content 模式必填的完整候选 SFC")
+@click.option("--edits-file", type=click.Path(exists=True, dir_okay=False), help="edits 模式必填的结构化编辑 JSON 数组")
+@click.option("--preview-schema-file", type=click.Path(exists=True, dir_okay=False), help="可选的候选 preview_schema JSON 对象")
+@click.option("--detail", is_flag=True, help="返回完整编译、渲染和布局诊断")
 @click.pass_context
 def validate_component_cmd(ctx: click.Context, component_id: int, mode: str, source_file: str | None, edits_file: str | None, preview_schema_file: str | None, detail: bool) -> None:
     """校验组件当前或候选源码。"""
@@ -254,10 +276,10 @@ def validate_component_cmd(ctx: click.Context, component_id: int, mode: str, sou
         handle_api_error("组件校验失败", err)
 
 
-@component_group.command("publish")
+@openapi_command(component_group, "publish", contract("POST", "/api/v1/components/{component_id}/publish"))
 @click.argument("component_id", type=int)
-@click.option("--release-name")
-@click.option("--change-note")
+@click.option("--release-name", help="本次发布版本的可读名称")
+@click.option("--change-note", help="本次发布的变更说明")
 @idempotency_key_option
 @click.pass_context
 def publish_component_cmd(ctx: click.Context, component_id: int, release_name: str | None, change_note: str | None) -> None:
@@ -269,14 +291,19 @@ def publish_component_cmd(ctx: click.Context, component_id: int, release_name: s
         handle_api_error("发布组件失败", err)
 
 
-@component_group.command("archive")
+@openapi_command(
+    component_group,
+    "archive",
+    contract("POST", "/api/v1/components/{component_id}/archive", "提供 COMPONENT_ID 时"),
+    contract("POST", "/api/v1/components/batch-archive", "提供 --ids-file 时"),
+)
 @click.argument("component_id", type=int, required=False)
-@click.option("--ids-file", type=click.Path(exists=True, dir_okay=False))
-@click.option("--yes", is_flag=True)
+@click.option("--ids-file", type=click.Path(exists=True, dir_okay=False), help="批量归档的正整数 ID JSON 数组")
+@click.option("--yes", is_flag=True, help="仅在用户已明确授权归档时跳过交互确认")
 @idempotency_key_option
 @click.pass_context
 def archive_component_cmd(ctx: click.Context, component_id: int | None, ids_file: str | None, yes: bool) -> None:
-    """归档单个或一批组件。"""
+    """归档单个组件或 JSON 数组指定的一批组件；两种目标输入只能选一种。"""
 
     try:
         client = get_client(ctx)

{web_presentation_cli-0.1.0 → web_presentation_cli-0.1.1}/src/wp/commands/job.py

@@ -12,6 +12,7 @@ from wp.commands.common import (
     output_result,
     require_success_job,
 )
+from wp.openapi_help import contract, openapi_command
 
 
 @click.group("job")
@@ -19,7 +20,7 @@ def job_group() -> None:
     """异步任务管理。"""
 
 
-@job_group.command("get")
+@openapi_command(job_group, "get", contract("GET", "/api/v1/jobs/mutations/{job_id}"))
 @click.argument("job_id")
 @click.pass_context
 def get_job_cmd(ctx: click.Context, job_id: str) -> None:
@@ -31,9 +32,14 @@ def get_job_cmd(ctx: click.Context, job_id: str) -> None:
         handle_api_error("查询 Job 失败", err)
 
 
-@job_group.command("wait")
+@openapi_command(
+    job_group,
+    "wait",
+    contract("GET", "/api/v1/jobs/mutations/{job_id}"),
+    examples=("wp --json job wait <job_id> --timeout 120",),
+)
 @click.argument("job_id")
-@click.option("--timeout", default=120.0, type=float, show_default=True)
+@click.option("--timeout", default=120.0, type=float, show_default=True, help="等待终态的最长秒数")
 @click.pass_context
 def wait_job_cmd(ctx: click.Context, job_id: str, timeout: float) -> None:
     """等待 Mutation Job 进入终态。"""
@@ -46,7 +52,7 @@ def wait_job_cmd(ctx: click.Context, job_id: str, timeout: float) -> None:
         handle_api_error("等待 Job 失败", err)
 
 
-@job_group.command("cancel")
+@openapi_command(job_group, "cancel", contract("POST", "/api/v1/jobs/mutations/{job_id}/cancel"))
 @click.argument("job_id")
 @idempotency_key_option
 @click.pass_context
@@ -65,7 +71,7 @@ def cancel_job_cmd(ctx: click.Context, job_id: str) -> None:
         handle_api_error("取消 Job 失败", err)
 
 
-@job_group.command("retry")
+@openapi_command(job_group, "retry", contract("POST", "/api/v1/jobs/mutations/{job_id}/retry"))
 @click.argument("job_id")
 @idempotency_key_option
 @click.pass_context