Merge remote-tracking branch 'origin/master' into feat/msg-queue-to-rust

docs/project-memory/shared-memory/pitfalls.md

@@ -59,8 +59,17 @@
 - **处理**：两侧都补了保留上限。服务端：`production-api-deploy.sh` 新增 `--keep-releases`（默认 `2`），发布成功后保留 `current` 目标与最近 1 个历史 release，只删除同时含 `api-server` 或 `web` 标记的旧目录，清理失败只告警、不改变发布结论。CI 侧：`Genarrative-Api-Deploy` / `Genarrative-Web-Deploy` / `Genarrative-Stdb-Module-Publish` 在各自部署 / 发布步骤成功后只保留最近 2 个 `build/<version>/`，失败时不清理以便诊断和重跑。`npm run check:production-api-deploy` 增加默认值、显式值和非法值三类夹具，`npm run check:production-ops` 增加对应合同。
 - **不要踩的坑**：直接按 mtime 排序删除会连带删掉发布根目录下不属于发布产物的目录（例如 `dev-mcp-host-*`），必须用 `api-server`/`web` 标记筛选；脚本里的 `mv -T`、`find -printf` 都是 GNU 语义，`npm run check:production-api-deploy` 需要 `sha256sum` 和 `/usr/bin/cp`，Windows 本地跑不了，只在 Linux CI / Linux 检出上有效（本地最低限度用 `bash -n` + `npm run check:production-ops`）。
 - **写 Jenkins 内联 shell 的两个坑**：① Groovy 会处理 `sh '''…'''` / `sh """…"""` 里的反斜杠转义——`\n` 到 shell 手上会变成真实换行（`Jenkinsfile.production-stdb-module-build` 里必须写 `printf "\\r"` 就是同一件事），所以内联片段要么完全不用 `\`，要么写 `\\`；`"""` 是 GString，shell 变量必须写 `\$name`，而 `'''` 不插值、保持 `${name}`。② `set -euo pipefail` 下 `ls build/*/` 在 glob 不匹配时会因 pipefail 把整个部署步骤判失败（实测：`build/` 为空时清理步骤会把一次成功发布判成失败），必须用 `if [ -d build ]` 守卫 + `|| true` 兜底。
+- **GString 里的命令替换同样要转义**：`sh """…"""` 内的 shell 命令替换必须写 `\$(...)`。写成裸 `$(...)` 时 Jenkins/Groovy 会在加载 Jenkinsfile 时直接报 `illegal string body character after dollar sign`，构建不会进入任何 stage；`npm run check:production-ops` 现已钉住 Stdb Publish 的暂存清理命令。
 - **关联**：`scripts/deploy/production-api-deploy.sh`、`scripts/check-production-api-deploy.mjs`、`scripts/check-production-ops-guardrails.mjs`、`jenkins/Jenkinsfile.production-api-deploy`、`jenkins/Jenkinsfile.production-web-deploy`、`jenkins/Jenkinsfile.production-stdb-module-publish`。
 
+## 2026-09-30 AGC macOS 包内容门禁必须识别随包 Claude Agent SDK
+
+- **现象**：`Genarrative-Agc-MacOS-Build #80` 已成功生成并核对 `陶泥儿开发版.app` 的身份与版本，却在 `check-macos-bundle.mjs` 的 resources 白名单断言处失败，Jenkins 只打印一条无文件名的 `AssertionError`。
+- **原因**：新增 Claude Agent SDK sidecar 后，构建会把 SDK 与匹配平台的 Claude runtime 放到 `claude-agent/node_modules/@anthropic-ai/`；macOS 包内容门禁仍按旧口径把除 Node runtime npm 以外的所有 `node_modules` 都判为禁止。
+- **处理**：把包内容策略抽成纯函数，只放行 `game-runtime/node/node_modules/npm` 和 `claude-agent/node_modules/@anthropic-ai/claude-agent-sdk[-darwin-*]` 两棵明确子树；同时显式要求 sidecar 入口、SDK 与平台 runtime 存在，并让违规时输出具体相对路径。
+- **验证**：`node --test apps/ai-game-creator-shell/scripts/macos-release-identity.test.mjs apps/ai-game-creator-shell/scripts/prepare-macos-codex.test.mjs`；macOS 实包再由 `check-macos-bundle.mjs` 复核。
+- **关联**：`apps/ai-game-creator-shell/scripts/macos-bundle-policy.mjs`、`apps/ai-game-creator-shell/scripts/check-macos-bundle.mjs`、`apps/ai-game-creator-shell/scripts/macos-release-identity.test.mjs`、`apps/ai-game-creator-shell/src-tauri/build.rs`、`jenkins/Jenkinsfile.ai-game-creator-shell-macos-build`。
+
 ## 2026-09-29 dev 上的 JNLP inbound agent 是历史残留，会在死端口上无限重连刷爆 syslog
 
 - **现象**：dev 的 `/var/log/syslog` 约 250MB/天，内容是 `jenkins-inbound-agent-start[pid]` 反复输出指向 `http://127.0.0.1:18080/tcpSlaveAgentListener/` 的 `Connection refused` 完整栈（2.6 天 61 万行，其中 `genarrative-release-deploy-01` 占 53 万行）。

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -6,11 +6,14 @@
 
 ### 清智创游官网独立域名路由
 
-清智创游官网 `tsingnovagames.com` / `www.tsingnovagames.com` 的首页静态资源位于同一 Web 根目录的 `/home/`，首页“游戏引擎”入口按同源请求 `/api/client-downloads`。生产 Nginx 必须让这两个域名进入包含 `/api` 反代的主站 `server block`，并把该域名根路径重写到 `/home/`；否则页面可以打开，但接口会被静态站点直接返回 HTML 404，前端显示“暂时无法获取下载信息，请稍后重试”。
+清智创游官网 `tsingnovagames.com` / `www.tsingnovagames.com` 使用独立的 Nginx 配置 `/etc/nginx/conf.d/tsingnova-games.conf`，静态根目录是 `/srv/genarrative/corporate-site-current`；主站模板 `deploy/nginx/genarrative.conf` 不应重复声明这两个域名。官网首页按同源请求 `/api/client-downloads`，因此应在现役官网 HTTPS `server` 中 include `deploy/nginx/snippets/tsingnova-client-downloads.conf`，只代理这个精确路径到 `genarrative_api`，不要把整个 `/api` 交给官网静态站点兜底。
 
-`Genarrative-Server-Provision` 在 `SERVER_NAME=genarrative.world`（或 `www.genarrative.world`）且使用 `production-https` 时会自动补入这两个官网别名，并渲染 `/home/` 根路径兼容规则。修改后需重新执行一次正式服务器配置发布并 reload Nginx，不要只重启 api-server：
+线上修复或排障后必须确认的是**生效配置**而不是仓库模板：
 
 ```bash
+sudo nginx -T | grep -n -A45 -B5 'server_name tsingnovagames.com'
+sudo nginx -t
+sudo systemctl reload nginx
 curl -fsS -D ~/data/tmp/tsingnova-client-download.headers \
   https://tsingnovagames.com/api/client-downloads \
   -o ~/data/tmp/tsingnova-client-download.json
@@ -18,7 +21,7 @@ jq . ~/data/tmp/tsingnova-client-download.json
 grep -i '^cache-control: no-store' ~/data/tmp/tsingnova-client-download.headers
 ```
 
-验收必须同时满足：接口返回 `200 application/json`，响应包含 `downloads` 与 `unavailablePlatforms`，并带 `Cache-Control: no-store`；`https://tsingnovagames.com/` 仍返回官网首页。若接口仍返回 Nginx 404，优先检查 `nginx -T` 中 `server_name` 是否包含上述两个域名以及 `/api` location 是否指向 `genarrative_api`。
+验收必须同时满足：接口返回 `200 application/json`，响应包含 `downloads` 与 `unavailablePlatforms`，并带 `Cache-Control: no-store`；`https://tsingnovagames.com/` 仍返回官网首页。若 API 直连 `http://127.0.0.1:8082/api/client-downloads` 是 `200`、官网域名仍是 `404`，说明官网 vhost 没有 include 下载 snippet，不能靠 reload 旧配置解决。
 
 ## 构建回归的隔离与发布文件权限