renaissance-mind/showai/use-showai

使用 ShowAI

Agent 通过 MCP 操作 ShowAI。App、网页、CLI 和 MCP 共用内容核心；CLI 保留服务启动、诊断与脚本用途，不作为 Agent 的另一套文档创作流程。用户只问用法时正常解释，不因本技能自动创建页面。

选择路径

先按用户要的结果选择路径，再做后面的连接与归属核对。

判断依据是结果是否需要留存、继续编辑或交给别人，不是内容复杂度或组件数量。没有留存信号、也不是续改已有 Page 时，可视化按对话展示处理。展示不写入任何内容库，内容归属只在保存时确定。文档路径的连接或保存失败不改用展示，展示失败也不自动建项目。

核对连接和归属

首次实际操作时，先读当前 ShowAI 连接的 guide() 入口说明，再调用 showai_capabilities。工具可能带宿主前缀，使用实际暴露的名称。检查 agentProtocol、transport、projects.access、projects.available 和展示能力；调用 project_context 或 projects_list 核对目标。不能仅凭“Codex”“ChatGPT”判断连接或显示能力。

• library 本机连接：project_context 返回固定内容库。纯查询用 projects_list、pages_list、library_search，不创建项目。新正式内容未指定项目时，project_resolve({sourceDirectory}) 使用宿主提供的绝对项目目录；首次映射可创建项目。不要使用插件、预览或临时输出目录。宿主当前工作目录是用户的项目或代码仓库、且内容与之相关时可以作为可信目录；对话整理、与当前目录无关的内容或没有可信目录时询问归属。用户要求独立命名项目时才用 project_create。
• project 绑定连接：project_context 返回固定项目。沿用它，不能用另一个 projectId 越过绑定。
• authorized 远程连接：projects_list 返回授权项目与当前权限。所有私有操作使用返回的 projectId；不要查询本机内容库或向远程传本机路径。用户明确要求新项目时用 project_create，授权、重试、登录和本机项目可见性见 连接配置的远程部分。

项目操作显式传 projectId。进入页面制作或组件制作任务时，用 project_context({projectId}) 取得 componentCatalog：完整内置＋项目索引、目录 revision 和两条工作流说明。项目解析回执也包含该索引；内置 Agent 由宿主在启动时注入。已持有当前连接、当前项目的完整索引时可传 knownCatalogRevision；回执 unchanged=true 时沿用已持有索引，不将省略的 items 当作空目录。没有完整索引时不传该参数。目录变化或切换项目后更新。页面身份来自真实结果中的 document.id 或页面列表；会话 ID 用于来源记录，不代替项目或页面身份。远程与本机 ID 不可自行互换。

连接错误、项目不匹配或工具缺失时，先报告缺项并按 连接配置 核实宿主配置；只看到 showai_connection_problem 时调用它并转述原因与修复步骤。完全没有 ShowAI 工具（宿主报 Connection closed 等）时按 连接中断或没有工具 处理。工具报错时按 错误码与下一步 判断能否自行修正；无法恢复时，按 无法恢复的失败与反馈 告诉用户失败的步骤和错误码，并指向「设置 → 关于与反馈」。保存或创作失败时，把用户要保存的内容留在对话中，便于修复后重试。用户说页面里的组件报错、显示不出来时，按 组件显示异常 处理。继续沿用当前连接和内容库：把失败原因告诉用户，内容留在对话中，等连接恢复后在同一项目里完成。库切换由宿主重新连接明确的 home，不通过文档工具修改全局库配置。已有可信连接、项目和页面身份时直接继续，不重复发现。

明确要求边写边画、多端配对、运行位置、会话隔离或位置参考时，继续读 collaborate-canvas。

内容模型

源 Page 包含结构化内容树、稳定节点 ID、布局与组件数据。Page 按顺序阅读，Board 表达空间关系，两者可以嵌套。组件负责把数据渲染成图形与交互；模板提供复用结构。页面引用精确组件版本与指纹。

内容库与代码目录不同。本机默认库是 ~/.showai，以实际连接为准。HTML 是阅读交付物；HTML 所在目录不证明有无源 Page。正式文档默认在已选项目中保存为一份 Page，再按需要展示。对话中看一眼的组件用 show_component；需要一份完整独立文件但不入库时才用 render_document。两者都返回 savedToProject=false，必须如实说明。

模板阶段与会话

呈现任务使用 show-document 中的必读系统基线；没有本机 skill 的网页客户端先读 guide({topic:"presentation"})。检查 templateWorkflow.protocol 为 showai-template-workflow-v2，template_context 选择本轮模板并返回固定引用、README 和组件索引；template_guide 只读当前阶段，四阶段为 intent（理解意图）、material（收集与处理材料）、logic（呈现逻辑）、design（呈现设计稿），制作与评审按设计稿执行。启动时 --templates 只固定该项目绑定 MCP 会话的默认选择，不修改全局模板或库配置。续改读取 Page.templateContext；目录或引用已知时复用，knownHash 只用于本轮确实持有的内容。模板组件索引按 componentPage 分页，实现源码只在开发或明确导出时读取。组件 guide 返回 authoringReference 时，可按其精确引用读取制作索引及相关指南、输入和工具；这些制作资源属于正常组件使用。

根据任务继续