web-presentation-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: web-presentation-cli
-Version: 0.2.1
+Version: 0.3.0
 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
@@ -66,14 +66,14 @@ wp profile use production
 
 ## Agent Skill 管理
 
-CLI 内置 `web-presentation` Skill，可离线安装到受支持 Agent。交互式终端省略参数时会按实际安装目录分组选择：共用 `.agents/skills` 的五个兼容 Agent 作为一组，Claude Code 和 Qoder 各自一组；脚本、管道或 JSON 模式必须显式传入参数。
+CLI 内置 `web-presentation` Skill，可离线安装到受支持 Agent。交互式终端省略参数时会按实际安装目录分组选择：共用 `.agents/skills` 的兼容 Agent 作为一组，Claude Code、MiMo、WorkBuddy 各自一组；脚本、管道或 JSON 模式必须显式传入参数。
 
 ```bash
 # 当前用户全局安装
 wp skill install --scope global --agent all
 
 # 当前项目安装；默认解析 Git 根目录，也可用 --project-dir 指定
-wp skill install --scope project --agent codex --agent qoder
+wp skill install --scope project --agent codex --agent mimo --agent workbuddy
 
 # 状态与卸载
 wp skill status --scope global --agent all
@@ -84,7 +84,26 @@ wp skill install --scope project --agent all --dry-run
 wp skill export web-presentation
 ```
 
-首次使用建议进入智能体将要工作的项目目录，直接运行 `wp skill install`，然后选择 `2. 项目`。项目级安装会进入项目根目录的 `.agents/skills`、`.claude/skills` 或 `.qoder/skills`，不是安装到 Python 包目录。安装后重新加载智能体窗口或新建会话。
+获取短期预览地址：
+
+```bash
+wp preview get --project-id <project_id>
+wp preview get --project-id <project_id> --route /overview
+wp preview get --page-id <page_id>
+```
+
+项目和页面目标共用同一个预览命令与 API Client 方法；页面模块入口由 Backend 解析。
+
+JSON 输出模式：
+
+```bash
+wp --json project list
+wp --raw project list
+```
+
+`--json` 输出面向 Agent 的稳定字段；`--raw` 输出 Backend 原始 JSON，二者不能同时使用。预览地址是短期 Preview Artifact 地址，不等同于正式发布地址。
+
+首次使用建议进入智能体将要工作的项目目录，直接运行 `wp skill install`，然后选择 `2. 项目`。项目级安装会进入项目根目录下对应 Agent 的 Skill 目录（如 `.agents/skills`、`.claude/skills`、`.mimocode/skills`、`.workbuddy/skills`），不是安装到 Python 包目录。安装后重新加载智能体窗口或新建会话。
 
 目录映射：
 
@@ -92,13 +111,14 @@ wp skill export web-presentation
 | --- | --- | --- |
 | Codex、Cursor、GitHub Copilot、Gemini CLI、OpenCode | `.agents/skills` | `~/.agents/skills` |
 | Claude Code | `.claude/skills` | `~/.claude/skills` |
-| Qoder | `.qoder/skills` | `~/.qoder/skills` |
+| MiMo | `.mimocode/skills` | `~/.config/mimocode/skills` |
+| WorkBuddy | `.workbuddy/skills` | `~/.workbuddy/skills` |
 
 Skill 与 CLI 一起发布，但使用独立版本。`wp skill status` 会识别缺失、过期、较新、不兼容、用户修改和未受管理等状态；普通升级不会覆盖用户修改，`--force` 会先保留同级备份。CLI 升级不会隐式改写已安装 Skill，需要重新运行 `wp skill install` 完成同步。
 
-当前版本关系：CLI `0.2.1` 内置 `web-presentation` Skill `1.2.0`，Skill 声明的 CLI 兼容范围为 `>=0.2.1,<0.3.0`。构建时会把这组关系与规范化内容 SHA-256 写入 manifest。
+当前版本关系：CLI `0.3.0` 内置 `web-presentation` Skill `1.3.1`，Skill 声明的 CLI 兼容范围为 `>=0.3.0,<0.4.0`。构建时会把这组关系与规范化内容 SHA-256 写入 manifest。
 
-Windsurf 和 WorkBuddy 不属于本地目录安装目标。`wp skill export` 生成的标准 ZIP 可用于 WorkBuddy 等支持本地上传的产品；CLI 不从 URL 或第三方仓库下载 Skill。
+Windsurf 不属于本地目录安装目标。`wp skill export` 生成的标准 ZIP 可用于支持本地上传的产品；CLI 不从 URL 或第三方仓库下载 Skill。
 
 ## 复制给智能体：安装 CLI 和 Skill
 
@@ -138,6 +158,10 @@ wp job wait <job_id>
 写入命令支持 `--idempotency-key <key>`；网络超时后需要重放同一业务请求时复用原 key，不要把同一个 key 用于不同请求。
 
 
+### 0.3.0 行为变更
+
+`--json` 现在输出面向 Agent 的稳定字段投影；`--raw` 输出完整 Backend 原始 JSON，二者不能同时使用。Project、Page、Component、Asset、Theme、Style、Validation 和 Preview 命令按场景区分列表、详情、源码和诊断字段；成功响应不再注入 `_client` 元数据。预览地址通过 `wp preview get` 获取，属于短期 Preview Artifact。
+
 ### 0.2.1 行为变更
 
 契约叶子帮助失败立即退出 1；`--json` 错误输出在 stderr。Doctor 独立检查全部已注册 OpenAPI 契约，存在 error 时退出 1，仅 warning 仍退出 0。自动化必须检查退出码。顶层与本地配置帮助仍可离线使用。

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/README.md

@@ -51,14 +51,14 @@ wp profile use production
 
 ## Agent Skill 管理
 
-CLI 内置 `web-presentation` Skill，可离线安装到受支持 Agent。交互式终端省略参数时会按实际安装目录分组选择：共用 `.agents/skills` 的五个兼容 Agent 作为一组，Claude Code 和 Qoder 各自一组；脚本、管道或 JSON 模式必须显式传入参数。
+CLI 内置 `web-presentation` Skill，可离线安装到受支持 Agent。交互式终端省略参数时会按实际安装目录分组选择：共用 `.agents/skills` 的兼容 Agent 作为一组，Claude Code、MiMo、WorkBuddy 各自一组；脚本、管道或 JSON 模式必须显式传入参数。
 
 ```bash
 # 当前用户全局安装
 wp skill install --scope global --agent all
 
 # 当前项目安装；默认解析 Git 根目录，也可用 --project-dir 指定
-wp skill install --scope project --agent codex --agent qoder
+wp skill install --scope project --agent codex --agent mimo --agent workbuddy
 
 # 状态与卸载
 wp skill status --scope global --agent all
@@ -69,7 +69,26 @@ wp skill install --scope project --agent all --dry-run
 wp skill export web-presentation
 ```
 
-首次使用建议进入智能体将要工作的项目目录，直接运行 `wp skill install`，然后选择 `2. 项目`。项目级安装会进入项目根目录的 `.agents/skills`、`.claude/skills` 或 `.qoder/skills`，不是安装到 Python 包目录。安装后重新加载智能体窗口或新建会话。
+获取短期预览地址：
+
+```bash
+wp preview get --project-id <project_id>
+wp preview get --project-id <project_id> --route /overview
+wp preview get --page-id <page_id>
+```
+
+项目和页面目标共用同一个预览命令与 API Client 方法；页面模块入口由 Backend 解析。
+
+JSON 输出模式：
+
+```bash
+wp --json project list
+wp --raw project list
+```
+
+`--json` 输出面向 Agent 的稳定字段；`--raw` 输出 Backend 原始 JSON，二者不能同时使用。预览地址是短期 Preview Artifact 地址，不等同于正式发布地址。
+
+首次使用建议进入智能体将要工作的项目目录，直接运行 `wp skill install`，然后选择 `2. 项目`。项目级安装会进入项目根目录下对应 Agent 的 Skill 目录（如 `.agents/skills`、`.claude/skills`、`.mimocode/skills`、`.workbuddy/skills`），不是安装到 Python 包目录。安装后重新加载智能体窗口或新建会话。
 
 目录映射：
 
@@ -77,13 +96,14 @@ wp skill export web-presentation
 | --- | --- | --- |
 | Codex、Cursor、GitHub Copilot、Gemini CLI、OpenCode | `.agents/skills` | `~/.agents/skills` |
 | Claude Code | `.claude/skills` | `~/.claude/skills` |
-| Qoder | `.qoder/skills` | `~/.qoder/skills` |
+| MiMo | `.mimocode/skills` | `~/.config/mimocode/skills` |
+| WorkBuddy | `.workbuddy/skills` | `~/.workbuddy/skills` |
 
 Skill 与 CLI 一起发布，但使用独立版本。`wp skill status` 会识别缺失、过期、较新、不兼容、用户修改和未受管理等状态；普通升级不会覆盖用户修改，`--force` 会先保留同级备份。CLI 升级不会隐式改写已安装 Skill，需要重新运行 `wp skill install` 完成同步。
 
-当前版本关系：CLI `0.2.1` 内置 `web-presentation` Skill `1.2.0`，Skill 声明的 CLI 兼容范围为 `>=0.2.1,<0.3.0`。构建时会把这组关系与规范化内容 SHA-256 写入 manifest。
+当前版本关系：CLI `0.3.0` 内置 `web-presentation` Skill `1.3.1`，Skill 声明的 CLI 兼容范围为 `>=0.3.0,<0.4.0`。构建时会把这组关系与规范化内容 SHA-256 写入 manifest。
 
-Windsurf 和 WorkBuddy 不属于本地目录安装目标。`wp skill export` 生成的标准 ZIP 可用于 WorkBuddy 等支持本地上传的产品；CLI 不从 URL 或第三方仓库下载 Skill。
+Windsurf 不属于本地目录安装目标。`wp skill export` 生成的标准 ZIP 可用于支持本地上传的产品；CLI 不从 URL 或第三方仓库下载 Skill。
 
 ## 复制给智能体：安装 CLI 和 Skill
 
@@ -123,6 +143,10 @@ wp job wait <job_id>
 写入命令支持 `--idempotency-key <key>`；网络超时后需要重放同一业务请求时复用原 key，不要把同一个 key 用于不同请求。
 
 
+### 0.3.0 行为变更
+
+`--json` 现在输出面向 Agent 的稳定字段投影；`--raw` 输出完整 Backend 原始 JSON，二者不能同时使用。Project、Page、Component、Asset、Theme、Style、Validation 和 Preview 命令按场景区分列表、详情、源码和诊断字段；成功响应不再注入 `_client` 元数据。预览地址通过 `wp preview get` 获取，属于短期 Preview Artifact。
+
 ### 0.2.1 行为变更
 
 契约叶子帮助失败立即退出 1；`--json` 错误输出在 stderr。Doctor 独立检查全部已注册 OpenAPI 契约，存在 error 时退出 1，仅 warning 仍退出 0。自动化必须检查退出码。顶层与本地配置帮助仍可离线使用。

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/_skill_sources/catalog.toml

@@ -2,6 +2,6 @@ schema_version = 1
 
 [[skills]]
 name = "web-presentation"
-version = "1.2.0"
+version = "1.3.1"
 path = "web-presentation"
-requires_cli = ">=0.2.1,<0.3.0"
+requires_cli = ">=0.3.0,<0.4.0"

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/_skill_sources/web-presentation/SKILL.md

@@ -5,7 +5,7 @@ description: Use the wp CLI to configure Web Presentation access and create or r
 
 # Web Presentation Agent
 
-Web Presentation 是面向 AI 的演示内容创作平台，不是单文件幻灯片生成器。通过 `wp` CLI 操作 Backend 中的真实平台对象：演示内容组织在项目和路由中，每一页是 Backend 保存、Runtime 在固定画布编译渲染的 Vue SFC；组件、资源、主题、样式和字体在工作空间内复用。临时 JSON、Vue 和截图文件只是 CLI 的输入输出载体，不是平台内容的事实源。
+Web Presentation 是面向 AI 的演示内容创作平台，不是单文件幻灯片生成器。通过 `wp` CLI 操作 Backend 中的真实平台对象：演示内容组织在项目和路由中，每一页是 Backend 保存、Runtime 在固定画布编译渲染的 Vue SFC；组件、资源、主题、样式和字体在工作空间内复用。临时 JSON、Vue 和截图文件只是 CLI 的输入输出载体，不是平台内容的事实源；统一放在当前工作目录下的 `.tmp/web-presentation/`（截图用其 `shot/` 子目录），见 [CLI 工作流](./references/cli-usage.md)。
 
 ## 先理解平台再操作
 
@@ -16,7 +16,7 @@ Web Presentation 是面向 AI 的演示内容创作平台，不是单文件幻
 - 交付目标：新建一组演示页面、补充/修改现有页面、统一视觉体系，还是只做分析或截图；
 - 对象落点：目标工作空间、项目、页面及是否涉及路由和共享资产；
 - 运行基线：项目画布与样式配置、当前版本、可复用组件、资源和 Runtime Kit 能力；
-- 完成证据：Backend 成功响应、Mutation Job 终态、最新对象版本和必要的截图复核。
+- 完成证据：Backend 成功响应、Mutation Job 终态、最新对象版本；用户要求交付链接时还要包含短期预览地址，视觉任务再进行截图复核。
 
 ## 按任务加载参考
 
@@ -38,7 +38,7 @@ Web Presentation 是面向 AI 的演示内容创作平台，不是单文件幻
 2. 确认 Profile、工作空间和目标对象的真实 ID，读取最新 configuration、路由、源码、版本、draft hash、依赖及必要资产。
 3. 把内容目标转换成页面 brief 和固定画布构图，再选择满足目标的最小对象变更；不凭名称或记忆猜字段、资源和 import path。
 4. 轻量字段使用对应 update，页面/组件创建和源码编辑走 Mutation 命令；写入使用幂等键和最新版本基线。
-5. 等待任务终态。成功后重新读取对象并按需截图；失败时依据错误码和诊断修正，不盲目重试。
+5. 等待任务终态。成功后重新读取对象；用户要求查看效果或交付链接时获取短期预览地址，视觉任务再按需截图；失败时依据错误码和诊断修正，不盲目重试。
 6. 汇报真实 ID、版本、Job、校验、截图和未完成事项；没有成功响应不得声称已写入或验证通过。
 
 ## 不可越过的边界

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/_skill_sources/web-presentation/references/cli-usage.md

@@ -49,7 +49,35 @@ wp component update --help
 
 契约失败先运行 `wp doctor`，区分健康、契约和认证结果；任一 error 使 doctor 退出 1。HTML 响应应检查网关是否返回前端入口，路径/方法/引用缺失应检查服务端与 CLI 契约。修复后重新读取帮助，不猜字段、不以试探写入寻找 Schema，也不读取内部源码绕过公开契约。没有缓存、离线 Schema 或自动重试。
 
-`--json` 用于稳定解析表格型输出，复杂响应默认已经是 JSON。不要解析 Rich 表格文案来获取 ID、版本或状态。
+`--json` 用于稳定解析面向 Agent 的精简业务字段，复杂响应默认已经是 JSON。`--raw` 输出 Backend 原始 JSON，并自动启用 JSON 输出；二者不能同时使用。不要解析 Rich 表格文案来获取 ID、版本或状态。
+
+## 获取短期预览地址
+
+用户要求查看效果、交付链接或最终汇报时，先确认目标对象已成功写入并重新读取最新版本，再按目标调用：
+
+```bash
+wp --json preview get --project-id <project_id>
+wp --json preview get --project-id <project_id> --route /overview
+wp --json preview get --page-id <page_id>
+```
+
+项目预览支持 `--route`，页面预览不支持 `--route`；项目和页面目标只能选择一种。响应中的 `preview_url` 是短期 Preview Artifact 地址，不是正式发布地址。
+
+## 临时文件目录
+
+本地 JSON、Vue SFC 和截图只是 CLI 的输入输出载体，不是平台内容的事实源。统一写在当前会话工作目录下，不要写入 Skill 安装目录、Python 包目录或其它系统路径：
+
+```text
+.tmp/web-presentation/
+.tmp/web-presentation/shot/
+```
+
+约定：
+
+- 输入载体（payload、edits、候选/写出的 SFC、route tree、资源文本与元数据）写在 `.tmp/web-presentation/` 下；文件名尽量带对象类型与 ID，例如 `page-42.vue`、`edits-42.json`、`component-7.vue`、`route-tree.json`、`asset.json`；
+- 截图等输出证据写在 `.tmp/web-presentation/shot/`，例如 `shot/page-42.png`；
+- 用户提供的原始素材保持其真实路径；智能体自行生成或落盘的中间文件一律进入上述目录；
+- 汇报时给出相对路径即可；这些文件可随时删除，交付事实以 Backend 对象、Job 终态和重新读取结果为准。
 
 ## 文件参数
 
@@ -62,7 +90,7 @@ wp component update --help
 - `--route-file`：完整路由树 JSON；
 - `--ids-file`：只含正整数的 JSON 数组。
 
-具体根节点、字段、枚举和参数组合只以对应命令 `--help` 中的当前 OpenAPI Schema 为准。
+具体根节点、字段、枚举和参数组合只以对应命令 `--help` 中的当前 OpenAPI Schema 为准。示例路径默认相对于 `.tmp/web-presentation/`。
 
 ## 写入、幂等与任务
 

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/_skill_sources/web-presentation/references/component-standards.md

@@ -37,11 +37,11 @@
 ```bash
 wp component get <component_id>
 wp component dependencies <component_id>
-wp component validate <component_id> --mode content --source-file ./Component.vue
+wp component validate <component_id> --mode content --source-file .tmp/web-presentation/component-<component_id>.vue
 wp component edit <component_id> \
   --base-version-no <base_version_no> \
   --base-draft-hash <draft_hash> \
-  --edits-file ./edits.json \
+  --edits-file .tmp/web-presentation/edits-<component_id>.json \
   --idempotency-key <key>
 wp component publish <component_id> --idempotency-key <key>
 ```

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/_skill_sources/web-presentation/references/design-system-and-assets.md

@@ -29,10 +29,15 @@
 
 ```bash
 wp --json asset list
-wp asset create --payload-file ./asset.json --content-file ./asset-content.txt --idempotency-key <key>
-wp asset upload ./image.png --type image --name hero-image --idempotency-key <key>
+wp asset create \
+  --payload-file .tmp/web-presentation/asset.json \
+  --content-file .tmp/web-presentation/asset-content.txt \
+  --idempotency-key <key>
+wp asset upload .tmp/web-presentation/hero-image.png --type image --name hero-image --idempotency-key <key>
 ```
 
+用户直接提供的原始文件保持其真实路径；智能体生成或落盘的 payload、文本和待上传文件写入 `.tmp/web-presentation/`。
+
 文本资源创建前查询是否已有 active 同名资源。可创建的文本类型包括 SVG 图标/图片、Draw.io、Mermaid、Chart 和 Formula；内容必须是完整 UTF-8 文本，并按命令帮助和 Backend Schema 满足扩展名及安全约束。图标 SVG 不得包含 script、事件属性、`foreignObject` 或远程引用，优先使用 `currentColor`。
 
 非 SVG 位图、video、font 等使用 `asset upload`；不要用 `asset create` 伪造二进制内容，也不要把 URL、本地路径或 base64 当成可信上传附件参数。生成或上传后用返回的真实 name/ID 和 render_type。

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/_skill_sources/web-presentation/references/page-generation.md

@@ -88,19 +88,21 @@ import DefaultContainer from '@runtime-kit/public/components/page/layout/Default
 修改已有页面时，先读取最新源码并生成基于真实片段的结构化 edits，再使用当前版本：
 
 ```bash
-wp page validate <page_id> --mode content --source-file ./Page.vue
+wp page validate <page_id> --mode content --source-file .tmp/web-presentation/page-<page_id>.vue
 wp page edit <page_id> \
   --base-version-no <current_version_no> \
-  --edits-file ./edits.json \
+  --edits-file .tmp/web-presentation/edits-<page_id>.json \
   --idempotency-key <key>
 ```
 
-`edits.json` 必须使用当前 `wp page edit --help` 显示的结构化编辑 Schema；匹配片段来自最新源码且必须唯一命中。
+`edits-<page_id>.json` 必须使用当前 `wp page edit --help` 显示的结构化编辑 Schema；匹配片段来自最新源码且必须唯一命中。
 
 新建页面使用完整 SFC：
 
 ```bash
-wp page create --project-id <project_id> --name "核心结论" --file ./Page.vue --idempotency-key <key>
+wp page create --project-id <project_id> --name "核心结论" \
+  --file .tmp/web-presentation/page-new.vue \
+  --idempotency-key <key>
 ```
 
 页面标题、摘要、演讲者备注等轻量字段使用 `wp page update`；不要用 metadata 更新命令承载源码。页面创建和源码编辑会自动执行编译、渲染和布局校验；独立 `page validate` 用于候选预检或需要更多诊断，不是绕过平台写入校验的办法。
@@ -112,7 +114,7 @@ wp page create --project-id <project_id> --name "核心结论" --file ./Page.vue
 ```bash
 wp --json page get <page_id>
 wp --json page source <page_id>
-wp page screenshot <page_id> --output .tmp/page.png
+wp page screenshot <page_id> --output .tmp/web-presentation/shot/page-<page_id>.png
 ```
 
 检查截图中的画布尺寸、底部裁切、文字换行、视觉重心、资源加载、空态/缺图和真实内容密度。发现问题时优先做局部 edits，不要无证据地重写整页。

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/_skill_sources/web-presentation/references/platform-model.md

@@ -17,6 +17,7 @@ Web Presentation 的核心边界是“当前工作空间”。所有资源归属
 | 字体 | 注册的字体族/字体文件声明 | 只读查询；先有资源，再由平台注册/下发 | `font list` |
 | Runtime Kit | 版本化公开运行时能力目录 | 不是工作空间资产，也不是通用 UI 库；只用真实返回的 `.vN` import path | `runtime-kit list/get` |
 | Mutation Job | 页面/组件重任务的持久化执行记录 | 状态是 `pending/running/succeeded/failed/canceled` | `job get/wait/cancel/retry` |
+| Preview Artifact | 项目或页面的短期交互预览 | 必须基于成功写入后的最新对象创建；`preview_url` 不代表正式发布 | `preview get` |
 
 ## 归属、引用和快照不要混淆
 
@@ -26,6 +27,7 @@ Web Presentation 的核心边界是“当前工作空间”。所有资源归属
 - 页面/组件 `dependencies` 是当前版本源码真实依赖，不能用名称搜索结果替代。
 - 组件草稿不是稳定公共能力；引用前查询发布版本和真实 `import_path`。
 - 归档对象退出默认查询与操作边界；首版没有永久删除和 Restore。项目归档不会级联归档其页面、路由或共享资产。
+- Preview Artifact 是临时交付证据，不是项目或页面的持久化发布版本；用户要求预览或交付链接时才创建，截图仍单独作为视觉验证证据。
 
 ## 读取基线
 

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/_skill_sources/web-presentation/references/platform-overview.md

@@ -30,7 +30,9 @@ Backend Mutation Job（权限、版本、编译、渲染、布局校验）
         ↓
 Runtime 固定画布结果
         ↓
-读取最新版本并截图复核，必要时局部修正
+读取最新版本
+        ↓
+按需获取短期预览地址并截图复核，必要时局部修正
 ```
 
 这条链路决定了操作顺序：先读上下文和配置，再构图和写源码；先等写入任务成功，再用截图评价视觉结果。不能只生成一份看似合理的 Vue 文件便声称页面已经完成。
@@ -92,7 +94,7 @@ Runtime Kit 提供页面容器、资源渲染、主题、页码、路由目录
 | “让整套页面风格一致” | 优先检查项目配置、主题和页面组件，再决定是否局部改页 | 配置快照、主题、样式、已发布页面组件、现有页面 |
 | “替换图片/图标/字体” | 查询或创建工作空间资源，再更新引用它的页面或组件 | 真实资源 name/ID、render type、依赖和目标源码 |
 | “做一个以后能复用的版式” | 创建或修改页面组件，维护 preview schema，并发布稳定版本 | 组件 standards、现有组件、草稿/发布版本、依赖 |
-| “看看效果/导出一张预览图” | 对已有成功版本发起截图并检查输出 | 目标页面 ID、最新版本与截图结果 |
+| “看看效果/获取交互链接” | 对已有成功版本获取项目或页面短期预览地址，必要时再截图 | 目标项目/页面 ID、最新版本与预览响应 |
 | “只评估怎么做” | 只读查询并给出对象级方案，不提交写入 | 足以支撑结论的平台事实 |
 
 用户没有提供 ID 时，先通过列表和详情发现真实对象；名称不能唯一定位时再请用户选择。用户明确要求新建一套演示时，可以创建新项目和页面，但仍要先确认工作空间及现有资产，避免重复建设。

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/_skill_sources/web-presentation/references/route-and-navigation.md

@@ -12,7 +12,7 @@
 {"routes":[{"route_type":"page","route":"cover","order":0,"hidden":false,"page_id":1},{"route_type":"group","route":"chapter-1","group_title":"第一章","order":1,"children":[{"route":"overview","order":0,"hidden":false,"page_id":2}]}]}
 ```
 
-`wp project route replace <project_id> --route-file ./route-tree.json --idempotency-key <key>` 是整树替换，遗漏的节点会被移除。GET 响应包含 id、page_code、display_title 等只读字段，不能原样回写；按当前写入 Schema 构造请求。
+`wp project route replace <project_id> --route-file .tmp/web-presentation/route-tree.json --idempotency-key <key>` 是整树替换，遗漏的节点会被移除。GET 响应包含 id、page_code、display_title 等只读字段，不能原样回写；按当前写入 Schema 构造请求。
 
 替换前重新读取整树并保留任务范围外的节点。当前接口没有版本条件，读取后仍可能发生并发覆盖；幂等键不能解决并发冲突。不要并行修改同一项目路由，发现基线变化应重新协调，而非盲目覆盖。
 

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/_skill_sources/web-presentation/references/validation-and-delivery.md

@@ -1,15 +1,15 @@
 # 校验与交付
 
-页面和组件写入由 Backend 的 Mutation Job 负责编译、渲染和布局检查。外部 Agent 的职责是提交正确基线、等待终态、读取结果并用截图验证真实视觉。
+页面和组件写入由 Backend 的 Mutation Job 负责编译、渲染和布局检查。外部 Agent 的职责是提交正确基线、等待终态、重新读取最新对象；用户要求交付链接时获取短期预览地址，并用截图验证真实视觉。
 
 ## 候选校验和写入校验
 
 独立校验适用于：写入前检查一份候选 SFC、结构化 edits，或失败后请求详细诊断：
 
 ```bash
-wp --json page validate <page_id> --mode content --source-file ./Page.vue --detail
-wp --json page validate <page_id> --mode edits --edits-file ./edits.json --detail
-wp --json component validate <component_id> --mode content --source-file ./Component.vue --detail
+wp --json page validate <page_id> --mode content --source-file .tmp/web-presentation/page-<page_id>.vue --detail
+wp --json page validate <page_id> --mode edits --edits-file .tmp/web-presentation/edits-<page_id>.json --detail
+wp --json component validate <component_id> --mode content --source-file .tmp/web-presentation/component-<component_id>.vue --detail
 ```
 
 `current` 检查当前内容，`content` 检查完整候选源码，`edits` 检查基于当前对象的结构化编辑；具体参数以命令帮助为准。校验不通过是诊断结果，不是写入成功。
@@ -31,10 +31,20 @@ wp --json job wait <job_id> --timeout 120
 
 ## 视觉复核
 
+用户要求查看可交互效果或交付链接时，获取短期预览地址：
+
+```bash
+wp --json preview get --project-id <project_id>
+wp --json preview get --project-id <project_id> --route /overview
+wp --json preview get --page-id <page_id>
+```
+
+`preview_url` 只用于当前 Preview Artifact 的短期访问，不代表正式发布；项目入口可通过 `--route` 指定，页面入口由 Backend 解析。预览地址用于交互检查，截图用于固定画布的视觉证据，两者不能互相替代。
+
 成功后获取最新截图：
 
 ```bash
-wp page screenshot <page_id> --output .tmp/page.png
+wp page screenshot <page_id> --output .tmp/web-presentation/shot/page-<page_id>.png
 ```
 
 检查：

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "web-presentation-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "Web Presentation CLI - 面向 AI 演示文稿创作平台的命令行与 Agent 工具包"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/src/wp/__init__.py

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

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/src/wp/cli.py

@@ -13,6 +13,7 @@ from wp.commands.doctor import doctor_cmd
 from wp.commands.job import job_group
 from wp.commands.page import page_group
 from wp.commands.profile import profile_group
+from wp.commands.preview import preview_group
 from wp.commands.project import project_group
 from wp.commands.skill import skill_group
 from wp.commands.style import style_group
@@ -29,14 +30,28 @@ from wp.commands.system import standards_group, system_group
     is_flag=True,
     help="让支持表格视图的命令输出 JSON；复杂响应默认也输出 JSON。",
 )
+@click.option(
+    "--raw",
+    is_flag=True,
+    help="输出 Backend 原始 JSON；与 --json 互斥，并自动启用 JSON 输出。",
+)
 @click.option("--profile", help="指定使用的 Profile 名称 (默认 default)")
 @click.option("--workspace", "-w", "workspace_id", type=int, help="覆盖当前操作的目标工作空间 ID")
 @click.pass_context
-def main(ctx: click.Context, as_json: bool, profile: str | None, workspace_id: int | None) -> None:
+def main(
+    ctx: click.Context,
+    as_json: bool,
+    raw: bool,
+    profile: str | None,
+    workspace_id: int | None,
+) -> None:
     """Web Presentation 官方命令行工具 (wp) - 面向 AI 演示文稿创作平台。"""
 
+    if as_json and raw:
+        raise click.UsageError("--json 与 --raw 不能同时使用。")
     ctx.ensure_object(dict)
-    ctx.obj["as_json"] = as_json
+    ctx.obj["as_json"] = as_json or raw
+    ctx.obj["raw"] = raw
     ctx.obj["profile"] = profile
     ctx.obj["workspace_id"] = workspace_id
 
@@ -58,6 +73,7 @@ main.add_command(font_group)
 main.add_command(workspace_group)
 main.add_command(project_group)
 main.add_command(page_group)
+main.add_command(preview_group)
 main.add_command(component_group)
 main.add_command(asset_group)
 main.add_command(theme_group)

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/src/wp/commands/asset.py

@@ -43,7 +43,7 @@ def list_assets_cmd(ctx: click.Context, page: int, page_size: int, asset_type: s
     try:
         result = get_client(ctx).get("/assets", params={key: value for key, value in params.items() if value is not None})
         if ctx.obj.get("as_json"):
-            output_result(ctx, result)
+            output_result(ctx, result, profile="asset_list")
             return
         rows = [[item.get("id"), item.get("name", "-"), item.get("asset_type", "-"), item.get("status", "-")] for item in result.get("items", [])]
         print_table("资源列表", ["ID", "名称", "类型", "状态"], rows)
@@ -58,7 +58,7 @@ def get_asset_cmd(ctx: click.Context, asset_id: int) -> None:
     """获取资源详情。"""
 
     try:
-        output_result(ctx, get_client(ctx).get(f"/assets/{asset_id}"))
+        output_result(ctx, get_client(ctx).get(f"/assets/{asset_id}"), profile="asset_detail")
     except ApiClientError as err:
         handle_api_error("获取资源详情失败", err)
 
@@ -67,7 +67,9 @@ def get_asset_cmd(ctx: click.Context, asset_id: int) -> None:
     asset_group,
     "upload",
     contract("POST", "/api/v1/assets"),
-    examples=("wp asset upload ./hero.png --type image --name hero-image --idempotency-key asset-hero-image",),
+    examples=(
+        "wp asset upload .tmp/web-presentation/hero-image.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, help="上传资源类型")
@@ -95,7 +97,9 @@ def upload_asset_cmd(ctx: click.Context, file_path: str, asset_type: str, name:
     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",),
+    examples=(
+        "wp asset create --payload-file .tmp/web-presentation/asset.json --content-file .tmp/web-presentation/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 的文本文件")
@@ -223,7 +227,7 @@ def archive_asset_cmd(ctx: click.Context, asset_id: int | None, ids_file: str |
         if ids_file:
             ids = require_ids(read_json_file(ids_file, label="归档 ID"))
             confirm_archive(ids, yes=yes, label="资源")
-            output_result(ctx, client.post("/assets/batch-archive", json_data={"ids": ids}))
+            output_result(ctx, client.post("/assets/batch-archive", json_data={"ids": ids}), profile="archive")
             return
         if asset_id is None:
             raise click.UsageError("必须提供 asset_id 或 --ids-file。")

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/src/wp/commands/common.py

@@ -11,6 +11,7 @@ import click
 from wp.client import ApiClient, ApiClientError
 from wp.config import get_profile, load_config
 from wp.formatter import print_error, print_json
+from wp.output_profiles import project_response
 
 
 def get_client(ctx: click.Context) -> ApiClient:
@@ -101,9 +102,11 @@ def require_ids(value: Any, *, label: str = "ID 列表") -> list[int]:
     return items
 
 
-def output_result(ctx: click.Context, value: Any) -> None:
-    """输出命令结果；复杂响应统一使用 JSON，保证 CLI 与 Agent 消费一致。"""
+def output_result(ctx: click.Context, value: Any, *, profile: str | None = None, detail: bool = False) -> None:
+    """输出原始或稳定投影后的 JSON，保证 CLI 与 Agent 消费一致。"""
 
+    if profile and not ctx.obj.get("raw"):
+        value = project_response(value, profile, detail=detail)
     print_json(value)
 
 

{web_presentation_cli-0.2.1 → web_presentation_cli-0.3.0}/src/wp/commands/component.py

@@ -45,7 +45,7 @@ def list_components_cmd(ctx: click.Context, page: int, page_size: int, keyword:
     try:
         result = get_client(ctx).get("/components", params={key: value for key, value in params.items() if value is not None})
         if ctx.obj.get("as_json"):
-            output_result(ctx, result)
+            output_result(ctx, result, profile="component_list")
             return
         rows = [
             [item.get("id"), item.get("import_name", "-"), item.get("name", "-"), item.get("component_type", "-"), item.get("status", "-")]
@@ -63,7 +63,7 @@ def get_component_cmd(ctx: click.Context, component_id: int) -> None:
     """获取组件详情。"""
 
     try:
-        output_result(ctx, get_client(ctx).get(f"/components/{component_id}"))
+        output_result(ctx, get_client(ctx).get(f"/components/{component_id}"), profile="component_detail")
     except ApiClientError as err:
         handle_api_error("获取组件失败", err)
 
@@ -72,7 +72,9 @@ def get_component_cmd(ctx: click.Context, component_id: int) -> None:
     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',),
+    examples=(
+        'wp component create --name "指标卡" --import-name MetricCard --file .tmp/web-presentation/component-new.vue --type content --idempotency-key component-metric-card',
+    ),
 )
 @click.option("--name", help="组件显示名称；直接参数模式必填")
 @click.option("--import-name", help="稳定导入标识；直接参数模式必填")
@@ -133,7 +135,9 @@ def create_component_cmd(
     "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",),
+    examples=(
+        "wp component update 15 --payload-file .tmp/web-presentation/component-15-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, help="组件元数据 JSON 请求体；复杂字段会自动进入异步任务")
@@ -176,7 +180,9 @@ def update_component_cmd(
     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",),
+    examples=(
+        "wp component edit 15 --base-version-no 2 --base-draft-hash <hash> --edits-file .tmp/web-presentation/edits-15.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, help="结构化编辑 JSON 数组；完整字段以当前 OpenAPI Schema 为准")
@@ -247,7 +253,9 @@ def component_dependencies_cmd(ctx: click.Context, component_id: int) -> None:
     component_group,
     "validate",
     contract("POST", "/api/v1/validate/entity"),
-    examples=("wp --json component validate 15 --mode content --source-file ./MetricCard.vue --detail",),
+    examples=(
+        "wp --json component validate 15 --mode content --source-file .tmp/web-presentation/component-15.vue --detail",
+    ),
 )
 @click.argument("component_id", type=int)
 @click.option("--mode", type=click.Choice(["current", "content", "edits"]), default="current", show_default=True, help="校验当前草稿、完整候选源码或结构化 edits")
@@ -271,7 +279,7 @@ def validate_component_cmd(ctx: click.Context, component_id: int, mode: str, sou
     if preview_schema_file:
         payload["preview_schema"] = require_object(read_json_file(preview_schema_file, label="Preview Schema"), label="Preview Schema")
     try:
-        output_result(ctx, get_client(ctx).validate_entity(payload))
+        output_result(ctx, get_client(ctx).validate_entity(payload), profile="validation", detail=detail)
     except ApiClientError as err:
         handle_api_error("组件校验失败", err)
 
@@ -310,7 +318,7 @@ def archive_component_cmd(ctx: click.Context, component_id: int | None, ids_file
         if ids_file:
             ids = require_ids(read_json_file(ids_file, label="归档 ID"))
             confirm_archive(ids, yes=yes, label="组件")
-            output_result(ctx, client.post("/components/batch-archive", json_data={"ids": ids}))
+            output_result(ctx, client.post("/components/batch-archive", json_data={"ids": ids}), profile="archive")
             return
         if component_id is None:
             raise click.UsageError("必须提供 component_id 或 --ids-file。")