#常见问题

项目列表默认不自动添加作品。可以自己创建、导入 文档配套文件，或从市场下载。截图中的已有项目是演示环境保存过的内容。

普通聊天与组件创作的工作量不同。工作台可能需要查询组件、读取交互规则、生成完整作品并校验，涉及多轮工具调用。请展开执行过程，判断时间耗在服务商响应、工具循环还是长篇设计输出。

优先尝试：确认模型支持工具调用 → 把需求缩成一个核心组件 → 先配置真实 API 和响应示例 → 成功后逐步补充样式与交互。若持续报错，保留诊断编号、时间、插件版本和复现需求。

先打开「查看问题详情」，区分工作台接口状态和 AI 服务商状态。

不要仅凭一条通用错误反复重试。先核对详情，再决定更换模型或调整需求。失败不会自动把残缺设计应用到当前项目。

先查看按钮旁的说明、禁用原因或错误详情。当前作品状态、账号权限、AI 是否配置完成，以及宿主是否注册对应回调都会影响可用性。

配置一个 JS 回调的名称不等于已经实现函数。由主题或宿主注册同名处理器后，在目标页面验证，见 事件、回调与调试。

浏览器地址栏打开 URL 与页面内跨域请求受不同规则约束。检查目标 API 是否允许本站跨域、HTTPS 页面是否调用 HTTP、接口是否需要登录或鉴权、返回内容是否为预期 JSON。

先在「接口与回调 → 测试接口」查看错误，再看「交互调试」中的方法、状态和结果。模拟成功只能证明前端能处理该模拟数据，不能证明真实接口已经接通。

天气演示下载版 默认手动请求。需要自动取数时，在按钮点击事件中勾选「打开作品时自动执行」，保存事件配置，再保存项目新版本。按钮之后可以保留为「刷新天气」。

自动执行是实例打开时运行一次，不是定时轮询。市场缩略图等位置为避免批量请求，可能不启用自动执行。

核对结果写入路径和展示读取路径是否一致。例如结果存 /response，温度读取 /response/current_weather/temperature。再检查初始值、条件显示、字段大小写、数字和字符串类型。

如果仍启用了「API 测试场景」，先恢复原始接口。字段结构变化提示需检查，但新增字段本身不等于请求失败。

确认点击的是「保存项目 / 保存新版本」，而不是仅保存接口、事件或本地投稿草稿。然后刷新目标页面。已经打开的实例不会实时替换成新版本。

主题工作室的试色、临时预览参数以及载入旧版本，也不会直接更新公开项目。相关结果需要在作品中确认并保存。

按顺序确认：

1. 标签位于安装并启用灵构 UI 的同一 Halo 站点。
2. 当前主题的该位置允许输出原始 HTML，标签没有被转义或过滤。
3. 使用从项目复制的完整项目 ID，而不是节点 title、btn_fetch 等。
4. 项目仍存在，并开启了公开嵌入。
5. 页面没有阻止插件加载器或相关资源；加载失败后可重试或刷新。

不需要把整个作品 JSON、脚本和样式再次粘贴进去，见 项目管理与嵌入。

文章和主题原有引用将无法加载该项目。删除项目也会导致引用失效。处理前应确认文章、侧边栏和页脚是否仍在使用该 ID。

默认只在当前实例的运行状态中保存，不上传，不跨读者共享。刷新页面或重新打开实例后从初始状态开始。需要跨设备进度时，应通过自己的 API 或宿主回调保存和恢复。

创作历史和未提交草稿先保存在当前浏览器，并按账号区分。正式保存的项目位于 Halo 工作空间；已提交市场的作品可以查询其审核记录。重要作品应保存项目并导出备份。

识别 CSS 成功不代表字体文件都能加载。检查源 URL、相对路径、CORS、HTTPS、字重和 unicode-range。还要在主题中选择字体，并把主题应用到作品后保存，详见 主题与字体。

1.0.1 已移除灵构自建 MCP 服务，旧地址、专用密钥和按项目授权配置不再生效，也不会自动迁移。

按顺序重新接入：

1. 安装并启用 Halo 官方 MCP Server >=1.3.0 & <2.0.0。
2. 超级管理员打开「工具 → MCP 服务」，创建官方访问密钥并选择「灵构 UI」工具。
3. 用官方页面提供的配置替换旧配置，地址为 https://你的站点/mcp，认证为 Authorization: Bearer <官方访问密钥>。
4. 更新客户端工具列表，再调用 plugin-lingui__get_guidance(topic="skill") 获取创作规则。

详细配置见 Skill 与 MCP 接入。

先打开 Halo「工具 → MCP 服务」，检查当前访问密钥是否选中了所需工具。所有灵构工具都需要逐项选择，新增工具不会自动加入已有密钥。

保存工具选择后，让客户端重新获取工具列表。客户端可能为工具添加服务别名前缀，请使用它实际提供的调用名称。

工具已选中仍被拒绝时，再检查访问密钥所属的 Halo 账号：账号必须存在且未停用，并具有「使用 MCP 创作工具」权限。读取作品或提交针对已有作品的修改草稿，还需要该账号对目标作品的读取权限；工具授权不能扩大账号本身的权限。

读取时必须提供作品资源名称 workName，不能使用作品标题或浏览器当前打开的项目代替。MCP 只能读取最近保存的版本；需要未保存的修改时，先回工作台保存。草稿提交成功后仍需你预览、载入并确认保存，见 MCP 接入。