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

name, description

name	description
deploy-publish-check	当 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。
• 没有回滚或恢复说明。

没有明确许可和清晰目标时，不要对外发布。

交接

如果被阻塞，把准确缺失项交回负责角色。如果已准备好，提供最终发布说明和证据。