#Skill 与 MCP 接入

#安装并启用官方 MCP Server

先确认已安装灵构 UI 1.0.1，并在 Halo 插件管理中安装、启用 Halo 官方 MCP Server。支持的版本为 1.3.0 或更高的 1.x，即 >=1.3.0 & <2.0.0。

启用后，灵构工具会加入官方工具目录。MCP Server 是可选依赖；不使用外部 AI 时，无需安装它，工作台、内置 AI 和项目功能仍可使用。

#创建官方访问密钥并选择工具

使用超级管理员账号打开 Halo 「工具 → MCP 服务」（/console/mcp）。也可以从灵构 「MCP 管理 → 打开官方 MCP 服务」 进入。

为外部 AI 客户端创建访问密钥，按需选择「灵构 UI」下的工具：

新建作品通常需要查询、规则和校验工具；修改已保存作品时再选中读取工具，希望 AI 把结果送到工作台时再选中草稿提交工具。

已有官方密钥也需要手动加入新工具。 灵构工具出现在目录中，不代表每个访问密钥都自动获得授权。密钥后续在官方 MCP 服务中管理和撤销。

灵构还会检查密钥所属 Halo 账号的实际权限：账号需要灵构 MCP 使用权限，读取或修改已有作品时还需要目标作品的读取权限。账号被停用、删除或撤销相应权限后，工具调用也会被拒绝。

#配置外部 AI 客户端

优先复制官方 MCP 服务页面生成的客户端配置。统一服务地址为：

https://你的站点/mcp

传输方式为 Streamable HTTP，认证方式为 Authorization: Bearer <官方访问密钥>。这里使用上一步生成的官方 MCP 访问密钥。

[mcp_servers.halo]
url = "https://你的站点/mcp"
bearer_token_env_var = "HALO_MCP_TOKEN"

{
  "mcpServers": {
    "halo": {
      "type": "http",
      "url": "https://你的站点/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HALO_MCP_TOKEN}"
      }
    }
  }
}

将 URL 填入远程 HTTP 服务字段；本地「Command / stdio」用于启动程序，不能直接执行 HTTP 地址。

本地服务示例为 http://127.0.0.1:8090/mcp，端口按实际 Halo 配置填写。同机客户端可以访问该地址；云端 AI 中的 localhost 指向云端自身，需改用客户端能够访问的 Halo 域名。

#连接并读取创作 Skill

保存客户端配置，重新连接，再获取工具清单（tools/list）。应能看到密钥已授权的 plugin-lingui__ 工具。客户端可能再添加服务别名前缀，以客户端实际提供的可调用名称为准。

让 AI 先调用：

plugin-lingui__get_guidance(topic="skill")

这会读取当前版本的创作 Skill。布局、主题、交互和数据规则通过同一工具的其他 topic 按需获取。

可以直接发送下面这段需求：

请使用已配置的 halo MCP，先获取工具清单，
再调用 plugin-lingui__get_guidance(topic="skill") 读取创作 Skill。
制作一个三道题的 JVM 内存测验，选择答案后显示解析，支持重新作答。
按需查询真实组件参数，生成后调用 plugin-lingui__validate_design 校验。
若已授权 plugin-lingui__submit_design_draft，请提交组件草稿，等我在工作台确认。

仅复制这段文字不会安装 MCP 或增加密钥权限。工具缺失时，先回官方 MCP 服务为密钥补充工具，再让客户端重新获取清单。

#新建作品或修改已保存作品

新建作品可以直接提出创作需求，无需读取空项目。修改已有作品前，先在 Halo 保存最新版本，再向 AI 提供准确的 作品资源名称 workName。工作台的「连接外部 AI」接入指引会显示该名称；它不是作品的显示标题，也不能由 AI 猜测当前浏览器打开的项目。

例如，在指令中把下面的占位内容替换为实际资源名称：

请调用 plugin-lingui__get_current_work(workName="<作品资源名称>") 读取已保存作品。
保留原有题目和交互，只调整配色和间距。
校验通过后提交组件草稿，带上相同的 workName，
并把读取结果中的 revision 作为 baseRevision。

MCP 读取的是最近保存的作品快照，无法读取浏览器中尚未保存的编辑。如果保存了新版本，应让 AI 重新读取并基于新版本修改。

提交组件草稿时，AI 使用 kind="component"、完整设计和简短 summary。修改已有作品需要带上 workName 与 baseRevision；新作品省略这两项。每份新草稿使用新的 submissionId，同次提交重试保持该 ID，避免重复生成草稿。

只设计主题时，先读取 plugin-lingui__get_guidance(topic="theme")，使用 kind="theme" 提交完整 lingui.theme/1 主题；主题不调用仅校验作品的 plugin-lingui__validate_design。

未授权草稿提交时，可以让 AI 输出校验后的完整标准设计 JSON，回工作台「导入 JSON」预览；主题则使用「导入 AI 主题」。

#在工作台预览、载入并保存

用与官方访问密钥所属账号相同的 Halo 账号打开灵构，在「MCP 管理 → 草稿与操作记录」，或工作台「更多 → 外部 AI 草稿」查看结果。

先检查修改摘要、差异和预览，再载入编辑器，测试交互，最后手动保存项目。修改已有作品时，若工作台已有新版本，可检查逐项合并结果；基准版本不可用时可作为新作品载入。主题草稿载入主题工作室后，也需要确认保存。

草稿窗口的静态预览不会直接执行业务 API 或宿主回调。MCP 提交成功表示草稿已送达；最终交互仍需在工作台验证，项目保存、投稿和文章发布由你操作。

#查看草稿与操作记录

切换「操作记录」，可查看当前账号通过灵构工具进行的 Skill 读取、组件查询、作品读取、校验和提交等实际调用，以及时间和结果。官方 MCP 服务也提供统一的工具调用记录。

灵构的草稿和操作记录按所属账号隔离，不显示外部 AI 的私有思考或模型内部生成过程。每个账号最多保留最近 300 条操作、100 份草稿；草稿达到上限后需清理再提交。页面会定期刷新，也可手动刷新。