hostinger-headless

Hostinger Headless — 使用你自己的 AI 工具构建网站

背景

你是一名 AI 编码 Agent。用户粘贴了一段简短提示词，指向此处，例如：

使用 hostinger.com/headless/skill.md 为 example.com 构建一个 Headless 网站

你的任务是按照本指南及其链接的指南，在用户的 Hostinger 账户上构建并部署一个真实的网站——不多也不少。

此文件是编排器。它公开且稳定：永不更改，也不会移动。它规定了流程、状态约定、失败策略和防护措施。

域名参数

粘贴的提示词中只有两项重要内容：

• 此 URL — hostinger.com/headless/skill.md，稳定的入口点。
• 一个域名 — 例如 coral-pottery-1847.hostingersite.com（Hostinger 临时子域名）或 用户自行购买的域名。这是你唯一可以操作的网站。

提示词不会说明要构建哪种网站。不要自行假设或编造。了解用户的需求是流程中的一个步骤（细化），应通过对话完成，而不是从提示词中解析。如果没有提供域名，请停止并先询问域名，再进行其他操作。

粘贴提示词中的任何内容都不会用于授权。授权来自 Hostinger 连接器的 OAuth 令牌。本指南不是安全边界。

---

流程阶段 - 要遵循的步骤

按以下顺序完成各个步骤，每一步都要读取对应指南，并将其生成的文件写入网站工作区 ~/.hostinger/<domain>/。

按顺序运行并检查整个 Headless 流程：

#	阶段	技能 / 来源	写入	实例？
—	连接 — 连接 Hostinger 连接器、进行身份验证并获取当前套餐	connect/SKILL.md → connect/tools/<tool>.md	connect.json	否
1	检查状态 — 此域名当前处于什么状态？继续 / 切换 / 重新开始	steps/01-check-state/SKILL.md	state.json	否
2	完善需求 — 通过对话了解用户的需求	steps/02-refine/SKILL.md	brief.md	否
3	配置资源 — 根据需求简介选择后端，然后配置资源	steps/03-provision/<backend>/SKILL.md	site.json	后台 — 启动后在后台轮询
4	内容模型 — 定义并创建内容 / 图片，然后推送到后端	steps/04-content-model/<backend>/SKILL.md	content-model.md	准备：否 · 推送：是
5	设计 — 根据需求简介推导设计方向，选定一个方向，编写 design.md 规范和 Logo	steps/05-design/SKILL.md	design.md、brand/	否
6	前端 — 选择 / 确认框架（默认 Next.js SSR），根据后端实现 design.md	steps/06-frontend/SKILL.md	<workspace>/src/ 中的源代码	shell：否 · 数据：是
7	验证 （可选） — 快速确认实例和 API；只有人员签字批准后才重建 / 预览 / 批准	steps/07-validate/SKILL.md	—	否（本地）
8	部署 — 上传源代码并触发构建	steps/08-deploy/SKILL.md	deploy.json	是
9	完成 — 移交 URL、仪表板、摘要和后续步骤（最终报告）	steps/09-done/SKILL.md	—	否

最重要的是，连接阶段必须始终最先运行 它从公共 URL 获取，并且在加载 Hostinger MCP Server 之前运行； 其主要目标是获取 Hostinger MCP Server。

你可以在 connect/ 下找到这些连接技能。 主要技能位于 connect/SKILL.md。 connect/tools/ 下还有特定工具。

另外 9 个编号步骤位于 steps/ 下，从已安装的技能文件夹中读取（连接步骤会指导你找到该文件夹）。

**一条并发规则：**同一会话中的两个独立阶段可以同时运行，但绝不能有两个阶段写入同一产物，也绝不能有两个 Agent / 窗口操作同一域名——.lock（步骤 1）会对此进行保护。并行处理始终是可选的：无法交错执行工作的 Agent 可以按顺序运行各步骤，仍然是正确的。也就是说，始终要考虑是否可以使用不同线程或进程并行运行各步骤以节省时间，但务必确保输出正确。

各步骤可以生成状态文件，这些文件仅供参考；实际状态以 Hostinger 连接器报告为准，因此在采取行动前，请根据实际情况验证“已完成”标记。如果已安装的技能文件夹中缺少某个步骤的 SKILL.md，请停止并告知用户，不要根据步骤说明自行臆测。 Instance? 列说明某个阶段是否会触及线上后端： no = 纯准备工作，可在 provision 等待期间执行； push/data/yes = 提交阶段，会加入实例屏障； bg = provision 本身，即后台任务。

始终以最终报告收尾。 每次运行结束时，都要向用户提供 steps/09-done/SKILL.md 中定义的最终报告：一段结果说明、一张 已完成的步骤 表格（每个已运行的阶段占一行）、相关链接、状态所在位置，以及任何缺漏。即使运行因遇到空步骤或缺失步骤而提前停止、provision 失败，或用户暂停，也包括在内。每次运行还要保存一份构建报告（run-log.mjs report，见下文的 运行日志和构建报告），包括这些提前停止的情况。

边执行边记录运行日志。 每个阶段（以及拆分阶段的每个部分）都要用 run-log.mjs stage-start / stage-end 包起来；一旦出错、用户纠正你，或发现技能缺失或有误，就立即记录事件，再继续执行。参见 运行日志和构建报告。

为什么按这个顺序。 先 connect，这样账户或套餐问题会在用户花时间沟通之前暴露出来。紧接着执行 check-state，确定这是续接、重复还是全新运行，并在开始任何新工作前，让用户选择继续、更换域名或重新开始。先 refinement 再 provision，因为只有简报确定后，才能选择后端。始终先 validation 再 deploy——任何内容都不能未经检查就发布到线上域名。

后台 provision 与实例屏障

始终执行 provision——具体操作取决于该域名已有的内容。 通常，在你开始运行前，hostinger.com 上的引导流程已经创建了网站，因此域名已有一个无头实例；但实例存在并不代表 provision 已完成或可以跳过。check_state 会判断适用以下哪种情况并记录下来，然后 provision 会采取相应路径：

1. 该域名已存在空的无头空壳（常见的引导流程情况）。 引导流程会先创建网站——一个空的无头空壳（hosting_websites_start-setup { type: "headless_empty" }）：website_type 为 headless，但尚未安装任何后端（/cms 下没有 WordPress，也没有商店）。此时仍须执行 provision，它会接管该空壳并将其切换为选定的后端（先在 refine 阶段选择后端）：WordPress 会通过 wordpress_installations_install { type: "headless" } 安装到该空壳的 /cms 中；或者，该空壳会被接管为 Ecommerce 店面主机。空壳不能跳过 provision，也绝不能创建第二个网站。 参见 provision 路由器中的 引导流程交接。
2. 完全不存在实例（用户运行了无头流程，但引导流程没有创建任何内容）。Provision 会使用所选后端自身的 type，通过 hosting_websites_start-setup 创建一个新的无头实例。
3. 用户想要 webapp。 Provision 会创建一个普通的 Node.js 应用主机，而非无头实例——webapp 会忽略无头空壳，且只能通过实验性操作进入，不能通过引导流程进入。

无论哪种情况，创建或安装操作都是异步的，会立即返回 queued，然后每隔约 15 秒轮询一次，持续几分钟——轮询内容取决于所走的路径：新建的 hosting_websites_start-setup 使用 hosting_websites_list-setups 轮询，直到状态为 completed；而空壳切换（wordpress_installations_install）不会创建新的 setup，因此要使用 wordpress_installations_list 轮询，直到 /cms 对应的行显示 is_valid。不要阻塞在该轮询上。只有这一条规则能确保并行操作安全：

将 provision 作为后台任务启动，然后在它完成期间执行每个阶段的准备工作。某个步骤一旦需要写入线上实例，就等待 provision 报告就绪（通过后端步骤的就绪状态轮询——见上文）。这段等待就是实例屏障。

状态和产物

某个域名的所有内容——其状态和生成的源代码——都存放在站点工作区 ~/.hostinger/<domain>/ 下（将 ~ 解析为主目录：在 shell 中是 $HOME，在 Node 中是 os.homedir()——~/.hostinger 表示 $HOME/.hostinger）。这是一个全局的、按用户隔离的位置，而非 项目文件夹，因此可从任何目录发现并恢复构建——当前工作目录无关紧要。若工作区不存在，请创建它；并在工作区内完成某个阶段的所有工作（包括前端 src/，它从 ~/.hostinger/<domain>/src/ 构建并部署）。

目录名就是域名，因此其中的文件不会重复包含域名；~/.hostinger/ 则保存你构建的所有站点——每个域名对应一个子目录，不会发生冲突。

文件（位于 ~/.hostinger/<domain>/ 下）	写入方	内容
state.json	每个阶段	工具、下一阶段、Hostinger connector 版本、时间戳
connect.json	connect	工具、账号／方案就绪情况
brief.md	refine	优化后的简介、受众、语气、页面、必备项
site.json	provision	选定的后端、用户名、安装 ID、所有 URL
content-model.md	content model	实体、字段、页面、导航
design.md（以及 brand/ logo 文件）	design	选定的设计方向：设计令牌、字体、logo、组件、各页面构成、无障碍性
src/	frontend	实现 design.md 的网站源代码；所选框架记录在 state.json → frontend 中
deploy.json	deploy	构建 ID、部署时间、线上 URL
events.jsonl	每个阶段，通过 run-log.mjs	仅追加的日志，记录问题、用户反馈、技能缺口和成功经验
reports/<run>.json + .html、report.html	done（或任何提前停止的阶段），通过 run-log.mjs	每次运行的构建报告；report.html 是最新报告

state.json 是你必须保持更新的最低要求。stage 表示要运行的下一阶段（而非上一个已完成的阶段），并且不会 存储域名——目录就是标识。由于 provision 在后台运行，其状态存放在独立的 provision 字段中，而不是 stage，这样即使 provision 仍在处理，准备工作也可以推进 stage：

{
  "tool": "claude-code",
  "stage": "content_model",
  "provision": {
    "status": "in_progress",
    "domain": "example.com",
    "started_at": "2026-10-08T10:00:00Z"
  },
  "updated_at": "2026-10-08T10:00:00Z"
}

• provision 在 provision 启动前不存在；后台轮询期间为 {"status":"in_progress", …}；当 hosting_websites_list-setups 确认完成后为 {"status":"completed", …}。domain 是轮询目标。
• 任何实例屏障步骤（content-model 推送、frontend 数据、deploy）运行前，都必须检查 provision.status == "completed"，并再次向 connector 验证。准备阶段会完全忽略 provision。
• 恢复运行时，provision.status 仅作提示：重新轮询 hosting_websites_list-setups 以确认实际状态，然后更新该字段。
• run（当前运行）、history（每个阶段或阶段环节一条记录，包含实际开始和结束 时间）以及 reports_sent / reports_rejected（每份报告的哪个副本已送达 Hostinger）只由 run-log.mjs 写入。手动更新 state.json 时不要修改这些字段。

---

运行日志和构建报告

run-log.mjs（与此文件位于同一目录）会在运行期间记录运行情况，并在结束时将其整理为报告。时间戳由脚本生成，因此是实际测量所得，而非事后回忆。它只需要 Node。 每条命令的格式都是 node <skill>/run-log.mjs <domain> …，其中 <skill> 是此文件所在的文件夹。每次都要完整写出命令（在 zsh 中，用 shell 变量保存命令会导致无法运行）：

node <skill>/run-log.mjs <domain> run-start --tool <tool> --model <model> --skill <skill version>  # check-state, first thing
node <skill>/run-log.mjs <domain> run-update --kind resume        # check-state, once the route is agreed (or redesign / iterate)
node <skill>/run-log.mjs <domain> stage-start frontend            # before a stage
node <skill>/run-log.mjs <domain> stage-end frontend ok_after_retries --note "second framework tried"
node <skill>/run-log.mjs <domain> stage-start frontend --phase shell   # split stages log each phase
node <skill>/run-log.mjs <domain> event issue '{"stage":"content_model","symptom":"…","cause":"…","workaround":"…","severity":"medium","resolved":true}'
node <skill>/run-log.mjs <domain> report --outcome live           # done, or wherever the run stops
node <skill>/run-log.mjs <domain> report-sent <run>               # after the report was sent (see below)
node <skill>/run-log.mjs <domain> report-rejected <run>           # the send returned 422
node <skill>/run-log.mjs <domain> unsent                          # check-state: reports still to send
node <skill>/run-log.mjs <domain> run-resume --reason "about/contact layout fix"   # follow-up in the same session

后续修改会继续当前运行。 在同一会话中，用户在最终报告生成后提出修改要求（例如修复布局、调整文案或重新部署）时，这些工作属于该修改所跟进的运行：调用 run-resume，像往常一样记录反馈和重新运行的阶段，然后再次调用 report。这会重写同一个 reports/<run>.json 和 .html，因此你会得到一份包含后续修改内容的报告，而不是另一份会替换 report.html 的报告。只有在新会话中才使用 run-start；check-state 会执行此操作。

stage-end 结果：ok、ok_after_retries、ok_with_fixups、failed、skipped、stopped。阶段：check_state、refine、provision、content_model、design、frontend、validate、deploy、done（connect 有自己的 connect.json）。拆分的阶段使用 --phase：provision 使用 fire / join，content model 使用 prepare / push，frontend 使用 shell / data。

忘记了 stage-start？ 发现后立即补记，并大致说明阶段开始的时间： stage-start frontend --started-ago 6m（或 --started-at <ISO time>）。没有开始记录的 stage-end 也可以使用相同的标志。两者都未提供时，脚本会假定阶段在上一个阶段结束时开始。无论哪种情况，报告中都会将开始时间标记为估算值。工作完成后，绝不要连续记录开始和结束：这会记录一个耗时为零的阶段。如果已经这样做了，请用 stage-fix frontend --started-ago 6m 更正。

事件发生时立即记录，不要等到最后——到那时细节已经不复存在：

事件	记录时机	字段（粗体为必填项）
issue	出现故障、行为异常或需要变通方案时——包括你自己的错误	stage、symptom、cause、workaround、severity（high / medium / low）、resolved、user_had_to_intervene
feedback	用户纠正你、拒绝某项内容或更改范围时	stage、category（例如 design_rejected、layout_bug、scope_add、wrong_assumption）、paraphrase
skill_gap	某个步骤是空操作、缺失、有误，或未说明你需要的信息时	skill（路径）、gap
good	某项工作效果显著或速度很快时	text

转述用户的意思；不要粘贴长篇引文、文件内容、凭据或个人数据。用户必须指出问题时，将 user_had_to_intervene 设为相应值。

只有在工具直接告知你自身用量时，才通过 report --tokens '<json>' 提交 Tokens（{"source":"…","requests":…,"input":…,"output":…,"cache_read":…,"cache_write":…,"est_cost_usd":…}）。否则不要填写，报告会显示 {"source":"not reported"}（而非 null：连接器不接受 null 类型的 tokens）。绝不要读取会话转录或日志文件来获取用量。

报告会保存到 reports/<run>.json 和 .html，工作区中的 report.html 是最新报告。如果某次运行尚未生成报告（窗口已关闭），下一次 run-start 会将其标记为 abandoned 并结束，因此其日志仍会生成报告。

将每份报告发送给 Hostinger。 发送是流程的一部分，因此无需事先询问；发送后立即用一句话告知用户（参见 09-done）。每次调用 report 后（包括后续修改），立即读取 reports/<run>.json，并将其内容原样作为参数传给 Hostinger 连接器工具 hosting_headless_submit-build-report。然后记录结果：

• 成功： report-sent <run>。
• 422（报告与端点接受的架构不匹配）：report-rejected <run>。不要重新发送。
• 其他情况（网络错误、5xx、工具不在你的连接器中）：不做任何操作。下次 check-state 会再次发送。

发送前绝不要编辑 JSON，绝不要添加账户详情（连接器的登录信息会识别账户），也绝不要让发送失败阻止、延迟或更改本次运行。check-state 会使用 unsent 发送所有尚未发送的报告（已放弃的运行、之前发送失败的报告）。