Makelore 2.0 initial clean snapshot

.opencode/skills/deploy-publish-check/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: deploy-publish-check
+description: 当 NianCode 发布部署角色检查学习者软件项目的构建准备、Docker 部署、项目 zip 打包、根目录 works-publish.json、部署与上传页面交接、发布步骤、回滚计划、作品广场提交准备和部署报告时使用。
+---
+
+# 部署发布检查
+
+使用这个 skill，判断学习者项目是否已经准备好通过 Docker 发布。
+
+## 给学生看的说话规则
+
+必须使用 `youth-plain-language`。讲 Docker、zip、上传接口时，先说明它们在作品发布里分别做什么，再给具体下一步。
+
+## 工作流程
+
+1. 确认发布目标，以及是否明确允许外部发布。
+2. 检查代码、Demo、素材、宣传文案和构建命令。
+3. 创建或维护 `Dockerfile`，确保项目可以构建为 Docker 镜像。
+4. 创建或维护 `docker-compose.yml`，确保项目可以通过 Docker Compose 启动。
+5. 检查 `niancode.yml` 使用 `runtime: compose`，并声明公开服务和 `8080` 端口；同时确认公开服务进程监听容器内 `0.0.0.0:8080`。
+6. 在合适时运行 Docker Compose 配置检查、构建、启动或冒烟检查。
+7. 发布获准时，把当前项目打成 `.zip` 包，并检查 zip 根目录包含 `niancode.yml`、`docker-compose.yml` 和 compose 构建引用到的 Dockerfile。
+8. 执行结构化机器检查：manifest、Compose services/public service/端口/build context、volume、禁止的运行时安装/构建、Dockerfile 构建阶段、Node/Python 锁文件、Vite `base: "./"`、构建入口资源路径、浏览器存储降级、环境变量安全默认值、密钥/缓存/路径/大小/文件数量；游戏或画布项目额外检查根节点全屏和响应式画布布局。
+9. 如果本机有 Docker，运行 `docker compose config`、`build --pull=false`、`up -d`、动态端口检查、HTTP smoke、日志检查和清理；解压到全新目录后再重复一遍。如果本机没有 Docker，逐项写 `status: BLOCKED`、`execution: unavailable` 和原因，不要把未执行写成 PASS，也不要要求用户去服务器接管。
+10. 如果本机有浏览器，在不带 `allow-same-origin` 的 sandbox iframe 中执行浏览器 smoke；任何白屏、未捕获 `SecurityError` 或启动失败都标为 BLOCKED。游戏或画布项目必须再执行桌面、移动和一次 resize/全屏变化 smoke，检查主画布是否达到最大等比尺寸。浏览器不可用时同样写 `execution: unavailable`，不能伪造画布证据。
+11. 在项目根目录创建或更新 `works-publish.json`，写清作品信息、版本信息和 zip 路径。
+12. 在项目根目录创建 `works-deploy-check.json`，绑定当前 zip 的 SHA-256，并用 `PASS`、`SKIPPED`、`BLOCKED` 记录所有必填机器检查项；真实执行成功写 PASS，环境能力缺失写 SKIPPED，或在明确云端交接时写 BLOCKED + `execution: unavailable`，确定性失败写 BLOCKED；总状态按 `BLOCKED > SKIPPED > PASS` 聚合。
+13. 把 `works-publish.json`、`works-deploy-check.json` 和 zip 路径交给“部署与上传”页面读取；如果“构建产品”已登记 `works-cloud-deploy.json`，交给 Main 云端部署协调器，它会在静态复核通过和登录态有效时自动调用 Works Square 远端构建接口；如果没有登录态，记录下一步。
+14. 准备发布步骤和回滚步骤。
+15. 产出部署报告。
+
+## 发布保护规则
+
+- 在发布目标和权限明确前，不要判定为可发布。
+- 必须使用 Docker 部署。不能把本地开发服务器、直接打开 HTML 文件或手工命令当作最终部署方式。
+- 使用最新构建、冒烟检查、预览或文件检查作为证据。
+- 记录准确命令和观察结果。
+- 检查密钥、私有路径、个人数据或未完成占位内容。
+- 缺少 `Dockerfile` 或 `docker-compose.yml` 时，不能判定为可发布；应先创建或要求补齐这两个文件。
+- 交给 Main 的云端部署协调器提交时，`.zip` 包必须在根目录包含 `niancode.yml` 和 `docker-compose.yml`，并包含 compose 构建引用到的 `Dockerfile` 或其它 Dockerfile。
+- zip 根目录必须直接包含 `niancode.yml` 和 `docker-compose.yml`，不能是 `project/niancode.yml` 或其它外层目录套壳。
+- 最小 `niancode.yml` 必须声明 `runtime: compose`、`compose.file: docker-compose.yml`、`compose.public_service` 和 `compose.public_port: 8080`。
+- `docker-compose.yml` 的公开服务必须发布容器端口 `8080`，服务进程必须监听 `0.0.0.0:8080`，并使用 `127.0.0.1::8080` 动态宿主机端口；固定宿主机端口和非 loopback 发布都不能判定为可发布。
+- 不能只准备 `Dockerfile`。作品广场 builder 和 runner 会按 Docker Compose 路径构建、启动和清理项目。
+- 所有服务禁止 bind mount、Docker socket、`privileged`、host network、host pid、host ipc 和固定宿主机端口；只允许顶层声明的命名卷保存运行数据。
+- Compose `command` / `entrypoint` 不得安装依赖、同步依赖或构建项目；这些动作必须写在 Dockerfile 的 build 阶段。
+- Compose 只能使用非敏感环境变量或 `${NAME:-safe-default}` 安全默认值；不得依赖宿主机未明确注入的业务变量，不得使用 `env_file: .env`。真实 `.env*` 文件全部排除，`.env.example` 只允许无敏感示例。
+- 如果项目是游戏或画布项目，`html`、`body`、`#app`/`#game-container` 必须占满 iframe，Phaser 使用 `FIT`/`CENTER_BOTH` 或等价缩放，其他引擎必须在 viewport/全屏变化后重新布局；桌面或移动任一实际 canvas 尺寸比最大等比预期小超过 5% 就是 BLOCKED。
+- 实际成功才写 `PASS`；仅因当前环境没有 Docker、Playwright、Puppeteer 或浏览器自动化而未执行时写 `SKIPPED`，或在明确云端交接时写 `BLOCKED` + `execution: unavailable`，保留原命令和缺失能力；命令执行失败或项目检查发现问题写 `BLOCKED`。`SKIPPED` 允许上传但必须提示未验证风险；云端模式只能把明确 unavailable 的动态检查交给 Works Square 远端复核。
+- 上传文件名必须以 `.zip` 结尾；zip 原始大小最大 `50MB`，解压后总大小最大 `200MB`，文件数量最大 `2000`。
+- 打包时默认排除 `.git/`、`node_modules/`、`.venv/`、`venv/`、`.next/cache/`、`.pytest_cache/`、真实 `.env`、证书、私钥和无关本地构建产物。
+- 缺少项目根目录 `works-publish.json`、缺少必填字段或 `zip_file_path` 不是 `.zip` 时，不能判定为可发布。
+- 缺少 zip 包路径或项目根目录 `works-publish.json` 时，不能判定为可交接；应先打包并写好交接文件。
+- 缺少 `works-deploy-check.json`、schema 不支持、zip SHA-256 不匹配、静态检查失败或任一确定性必填 check 为 `BLOCKED`，不能判定为可交接；仅环境能力缺失的 `SKIPPED` 或明确 unavailable 可交接但必须提示风险并交给云端复核。
+- Works Square 远端提交失败、缺少访问令牌或缺少登录态时，不要宣称发布完成；保留交接文件，记录 `waiting_for_login`/`failed` 和原因，Main 会在登录态恢复后继续。
+- 发布部署角色负责准备 zip 包、`works-publish.json` 和 `works-deploy-check.json`；“部署与上传”页面的“构建产品”负责明确授权一次云端提交，Main 负责正式提交，不要要求用户手动填写字段、SSH 或服务器。
+- 标记为可发布前，必须包含回滚或恢复步骤。
+
+## 云端部署与交接规则
+
+- “部署与上传”页面的“构建产品”按钮会登记一次 `works-cloud-deploy.json` 云端部署意图；页面只展示状态，Main 负责正式提交。
+- “远程上传”在本项目中特指 Works Square 后端 HTTP 上传接口，不是 SSH、SFTP、rsync 或自备服务器部署。
+- Main 会通过受控边界先确保项目元数据存在，再调用上游接口：`POST /api/projects/{appId}/versions/upload`。
+- Agent 不接触 `accessToken`，不能在 shell、聊天或报告中打印令牌。
+- `works-cloud-deploy.json` 的 `submitted` 只表示远端已接受并返回 `version_id`；`queued`、`building`、`reviewing` 都不等于已公开。
+- 不要询问 SSH 主机、用户名、端口或目标路径。
+- 如果没有云端部署意图，完成文件后说明需要从“部署与上传”页面点击“构建产品”授权一次提交；如果暂时没有登录态，保留交接文件并等待 Main 自动重试，不要让用户去服务器接管。
+
+## 根目录发布信息文件
+
+- 打包完成后，必须在项目根目录创建或更新 `works-publish.json`。
+- 文件必须是 JSON 对象，字段包括：`app_id`、`title`、`summary`、`category`、`age_band`、`difficulty`、`version_name`、`change_log`、`zip_file_path`。
+- `zip_file_path` 必须指向已经生成的 `.zip` 包。
+- Main 云端部署协调器读取 `works-publish.json`；页面仍可展示文件内容和历史版本，但不再让用户手动填写这些字段。
+- `works-publish.json` 是桌面页面交接文件，不是服务端校验 zip 的必填项，也不替代 zip 根目录的 `niancode.yml` 和 `docker-compose.yml`。
+- 不要要求用户手动填写这些字段；部署工程师要根据项目事实和交付物写入文件。
+- 缺少 `works-publish.json`、缺少必填字段或 `zip_file_path` 不是 `.zip` 时，不能云端交接。
+
+## zip 包结构和安全检查
+
+- 创建 zip 时，让项目根目录内容直接进入 zip 根目录；不要把整个项目目录再包一层，不能是 `project/niancode.yml`。
+- 重新打开 zip，检查根目录是否直接存在 `niancode.yml` 和 `docker-compose.yml`。
+- 检查 zip 是否包含 Compose build context 实际需要的源码、资源、锁文件和 Dockerfile。
+- 检查 zip 是否排除了真实密钥、本地依赖目录、缓存目录、符号链接、绝对路径、`..` 路径和不安全 volume / build 路径。
+
+## 必须输出
+
+返回部署报告，包含：
+
+1. 发布目标
+2. 是否允许发布
+3. 准备情况
+4. `Dockerfile` 路径和关键内容说明
+5. `docker-compose.yml` 路径、服务名和端口映射
+6. `niancode.yml` 路径和 `runtime: compose` / 公开服务 / `8080` 端口说明
+7. Docker Compose 配置、构建、启动和检查命令结果
+8. Compose 包结构检查：zip 根目录、外层目录、build context、Dockerfile、排除项、大小和文件数量
+9. 项目根目录 `works-publish.json` 路径和关键字段
+10. 程序包 zip 路径
+11. `works-cloud-deploy.json` 路径、当前状态、version_id/review_status（如已返回）和 Main 自动提交说明
+12. 发布步骤
+13. 回滚步骤
+14. 作品广场提交清单（页面会读取的字段）
+15. 游戏/画布适用时的逻辑分辨率、桌面/移动 viewport、实际 canvas、最大等比预期和 resize 复测
+16. 阻塞项
+
+## 纠偏清单
+
+出现这些情况时纠偏：
+
+- 发布目标不清楚，但要求发布。
+- 缺少构建/测试状态。
+- 宣传素材没有准备好。
+- 可能暴露密钥、私有路径或不安全文件。
+- 上传包缺少 `niancode.yml`、`docker-compose.yml`、compose 构建引用到的 Dockerfile 或清晰 zip 路径。
+- zip 根目录没有直接包含 `niancode.yml` 和 `docker-compose.yml`，或者把项目套成 `project/niancode.yml` 时，不能判定为可发布。
+- `works-deploy-check.json` 必须把 `compose_config`、`compose_build`、`compose_up`、`container_port`、`http_smoke`、`fresh_directory_smoke`、`sandbox_browser_smoke` 逐项写清楚；每项要有 `status`、`detail`、`command`，动态项还要有 `execution: executed` 或 `execution: unavailable`。本机环境不可用时写 BLOCKED + unavailable，不得伪造 PASS；存在云端部署意图时由 Main cloud 模式继续提交前复核。
+- 游戏或画布项目必须额外写 `game_canvas_smoke`；只有浏览器真实执行成功才提供 `canvas_evidence.logical_resolution`、`desktop_viewport`、`mobile_viewport`、`desktop_canvas`、`mobile_canvas`、`expected_max_canvas` 和 `resize_verified`。浏览器不可用时写 BLOCKED + `execution: unavailable`，普通网站不需要伪造此项。
+- 缺少 `Dockerfile` 或 `docker-compose.yml` 时，不能判定为可发布。
+- `niancode.yml` 仍使用 `runtime: docker` 或没有声明 `compose.public_service` / `compose.public_port: 8080` 时，不能判定为可发布。
+- `docker-compose.yml` 没有公开服务、没有发布容器端口 `8080`、写死宿主机端口，或不是 `127.0.0.1::8080` 这类 loopback 动态映射时，不能判定为可发布。
+- 容器内服务没有监听 `0.0.0.0:8080`，或 Compose 依赖未明确注入的宿主机环境变量、真实 `.env*`、`env_file: .env` 时，不能判定为可发布；`${NAME:-safe-default}` 才是允许的安全默认形式。
+- 游戏或画布项目根节点没有占满 iframe、主画布固定在逻辑分辨率、缺少响应式缩放/resize 重新布局、桌面或移动 canvas 比最大等比预期小超过 5%，或缺少 `game_canvas_smoke` 真实证据时，不能判定为可发布。
+- 缺少项目根目录 `works-publish.json`、缺少必填字段或 `zip_file_path` 不合法时，不能判定为可发布。
+- 缺少 zip 包路径或项目根目录 `works-publish.json` 时，不能判定为可交接。
+- 没有说明 Main 如何读取交接文件并自动提交，或远端提交失败但报告里没有失败原因。
+- zip 包超过大小/文件数量限制，或者包含真实密钥、本地依赖目录、缓存目录、不安全路径、符号链接、Docker socket、host network / privileged 配置时，不能判定为可发布。
+- 没有 Docker 构建、Docker Compose 启动或等价检查证据时，必须明确写 unavailable/阻塞原因；不能把缺少证据说成 PASS。
+- 没有回滚或恢复说明。
+
+没有明确许可和清晰目标时，不要对外发布。
+
+## 交接
+
+如果被阻塞，把准确缺失项交回负责角色。如果已准备好，提供最终发布说明和证据。