# 决策记录 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。 ## 记录格式 ```md ## YYYY-MM-DD 决策标题 - 背景：为什么需要这个决策 - 决策：最终决定是什么 - 影响范围：涉及哪些模块/文档/流程 - 验证方式：如何确认决策仍有效 - 关联文档：相关 PRD、技术文档、提交或 Issue ``` --- ## 2026-06-22 编辑器生成模型默认定价调整 - 背景：图片画布生成按钮、后端 `priceMudPoints` 校验和后台定价页需要统一使用新的模型默认泥点。 - 决策：`audio1.0` 默认按次 `5` 泥点，`chirp-v5` 默认按次 `12` 泥点，`gpt-image-2` 默认 `1K=3`、`2K=5` 泥点；运行态仍允许后台 override 覆盖，前端兜底必须与后端默认 JSON 保持一致。 - 影响范围：`editor-generation-pricing.default.json`、`ImageCanvasGenerationModel.ts`、后台定价页 fixture、后端价格校验和编辑器定价文档。 - 验证方式：运行 `editor_generation_config`、公开定价路由、图标素材价格校验、图片画布定价模型和后台定价页相关测试。 - 关联文档：`docs/【编辑器】模型定价配置管理方案-2026-06-22.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。 ## 2026-06-22 AGENTS.md 收敛为入口导航 - 背景：`AGENTS.md` 同时承载项目记忆、RAG、Issue、UI、Git、后端、SpacetimeDB 和文档图谱等细则，入口过重，复杂任务启动成本高。 - 决策：`AGENTS.md` 只保留最高优先级规则、任务路由、后端红线、验证提交要求和文档图谱；新增 `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md` 承接完整执行细则。复杂任务阅读顺序固定为 `AGENTS.md` -> Agent 执行准则 -> `docs/project-memory/` -> `docs/README.md` 和专题文档。 - 影响范围：`AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`、`docs/README.md`、`docs/project-memory/README.md` 和共享记忆索引。 - 验证方式：执行 `npm run check:encoding`、`git diff --check`，并检查入口文档不再重复承载专题细则。 - 关联文档：`AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`。 ## 2026-06-22 图片画布角色动作主媒体改为透明序列帧 - 背景：角色动作生成后端已经在视频生成后抽取透明 PNG 帧并完成绿幕去背；画板继续把 `previewVideoPath` 当主媒体会让用户看到未扣绿幕视频，下载也拿不到可直接用于游戏素材的帧序列。 - 决策：`/api/editor/character-animations/generations` 的上游预览视频继续保留为来源信息，但画板落层主类型固定为 `mediaType="image-sequence"`、`assetKind="character-animation"`；图层 `src` / `thumbnailSrc` 使用首帧，完整 `frames` 保存到 `imageSequenceFrames`，画布展示使用序列帧播放器循环播放。单图层下载生成序列帧 ZIP，画布素材 ZIP 中角色动作写入 `sequences/<编号-标题>/frames/`，不再把预览视频作为角色动作下载产物。 - 影响范围：图片画布角色动作生成、画布图层快照、序列帧播放器、素材导出、角色动作设计文档和排障记忆。 - 验证方式：运行角色动作图层工厂、画布展示、画布持久化、生成提交和素材导出相关前端测试，执行 `npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。 - 关联文档：`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。 ## 2026-06-21 图片画布生成完成态由后端写入画布布局 - 背景：图片画布角色形象等长耗时生成在服务端完成后，如果浏览器已刷新或原 HTTP 回调丢失，前端无法再把生成结果图层和 `generation-dialog` 完成态写回 `editor_canvas.layers_json`，用户会继续看到“生成中”卡片。 - 决策：图片生成请求在有项目上下文时携带 `canvasCompletion`（生成器 `dialogId`、结果标题和占位框）；`api-server` 在生成成功并创建 `editor_project_resource` / `editor_asset` 后，直接读取当前项目布局，只有当前布局仍存在对应生成器时才插入轻量结果图层，把生成器标记为 `idle` 并写入 `generatedLayerId`，沿用后端当前 viewport 保存 layout 后返回最新项目快照。前端只应用后端快照刷新显示，不再把生成完成态作为正式业务真相，也不在项目加载时根据资源行推断完成态。 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、图片画布生成提交工作流、项目快照 hydrate / persistence、图片画布技术方案和排障记录。 - 验证方式：`cargo test -p api-server editor_canvas_generation_completion --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx -- --runInBand`、`npm run check:encoding`、`git diff --check`。 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。 ## 2026-06-21 图片画布参考图元数据只保存项目内行引用 - 背景：参考图如果把 Data URL、signed URL 或 `objectKey` 写入 `generationInputs` 或生成器布局快照，会撑大资源 / 素材 / 画布 JSON，也无法稳定索引到项目内用户可见行数据。 - 决策：`generationInputs.references` 只保存 `{ title, label, refType, refId }`，其中 `refType="project-resource"` 指向 `editor_project_resource.resourceId`，`refType="asset"` 指向 `editor_asset.assetId`。生成器 `itemType="generation-dialog"` 布局快照中的参考图也只保存 `resourceId/sourceAssetId` 和展示 label，不保存图片 Data URL、signed URL 或 `objectKey`；提交生成请求前的内存态可以临时持有 `src/objectKey`，刷新恢复时从 `editor_project_resource` / `editor_asset` 行补回请求所需图片源。不兼容旧 `src` 型参考图元数据。 - 影响范围：图片画布生成输入快照、生成器布局保存 / 恢复、参考图上传工作流、元数据弹窗和图片画布技术文档。 - 验证方式：运行图片画布生成模型、生成提交、上传工作流、项目持久化、元数据弹窗相关前端测试，执行 `npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。 ## 2026-06-19 外部 OpenAPI 与 API Key 管理走 server-rs 正式链路 - 背景：外部调用方需要稳定调用图片画布项目创建、画布布局保存和编辑器美术生图能力，同时需要可撤销的开发者凭据，不能依赖前端临时状态或人工分发密钥。 - 决策：外部 API 固定放在 `/api/external/v1` 命名空间，v1 暴露素材直传凭证 / asset object 确认 / 签名读取、项目列表 / 最近 / 创建 / 读取 / 重命名 / 删除、默认画布保存、账号级素材库、项目资源记录、编辑器图片 / 视频 / 音频生成和 `/api/external/v1/openapi.json`。API Key 管理走登录态 `/api/profile/api-keys`，外部调用使用 `Authorization: Bearer tnr_sk_xxx`；后端只保存 `key_hash` 和 `key_prefix`，明文只在创建响应返回一次。外部 API 鉴权、项目 / 画布 / 素材写回全部经 `api-server -> spacetime-client -> spacetime-module`，生成素材成功后按请求写入账号级 `editor_asset`，带 `projectId` 时写入 `editor_project_resource`；外部确认 asset object 时 owner 固定为 API Key 所属账号。API Key 管理接口不进入外部 OpenAPI JSON。 - 影响范围：`server-rs/crates/api-server/src/external_*`、`server-rs/crates/api-server/src/modules/external_api.rs`、`server-rs/crates/spacetime-module/src/external_api_key_storage.rs`、`server-rs/crates/spacetime-client/src/external_api_key.rs`、`docs/openapi/genarrative-external-v1.openapi.json` 和后端数据契约文档。 - 验证方式：`cargo test -p api-server external_api --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server external_editor_api --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、`npm run check:encoding`、`git diff --check`。 - 关联文档：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。 ## 2026-06-19 图片画布素材生成元数据上移到资源和素材 - 背景：角色、图标、UI 设计图、视频和音频等生成结果会在图片信息页展示用户可见输入快照；此前这些 `assetKind/generationInputs` 主要保存在画布 layer JSON 中，素材进入账号级素材库后跨项目复用和刷新恢复都依赖画布布局，不符合素材库作为账号级事实源的边界。 - 决策：普通图层的新保存不再把 `assetKind/generationInputs` 写入 `editor_canvas.layers_json`。`editor_project_resource` 保存项目画布资源快照的 `asset_kind/generation_inputs_json`，`editor_asset` 保存账号级素材的同名元数据；图片 / 图标 / UI 提取等生成 BFF 在请求携带 `projectId` / `assetFolderId` 时由后端创建新 resource / asset 并把快照回传前端，前端只用回包更新画布图层和素材栏，不再把同一生成结果二次调用保存接口。前端加载时优先从 resource / asset 恢复素材类别和生成输入快照，旧 layout 中的同名字段只作为历史兼容兜底。生成器对象本身仍作为 `itemType="generation-dialog"` 保存在画布布局中。 - 影响范围：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/spacetime-client/src/mapper/editor_project.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`src/services/image-editor/editorProjectClient.ts`、图片画布 hydrate / serialize / project persistence / asset library 代码和后端数据契约文档。 - 验证方式：运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`，并按需补充 `cargo check -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`。 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。 ## 2026-06-19 图片画布生成按钮价格统一绑定模型定价配置 - 背景：图片画布的生成图片、生成视频、生成规范、生成角色、生成素材、生成 UI、宣发素材、快速编辑、重绘和音频生成入口都在按钮内显示泥点；如果按钮文案、前端提交和后端校验各自写固定数值，后续调整模型价格会出现展示价、提交价和扣费价不一致。 - 决策：所有画板生成按钮价格必须从 `src/components/image-editor/ImageCanvasGenerationModel.ts` 的模型定价配置函数计算；需要提交 `priceMudPoints` 的视频、角色动作、图标素材、音效和背景音乐也使用同一函数。后端默认配置独立放在 `server-rs/crates/api-server/config/editor-generation-pricing.default.json`，运行时 override 默认写入 `.app/editor-generation-pricing.override.json`，可用 `GENARRATIVE_EDITOR_GENERATION_PRICING_OVERRIDE_PATH` 指定可写路径；后台“模型定价”通过 `/admin/api/editor-generation-pricing` 读取和保存完整 `models` 配置，主站通过 `/api/editor/generation-pricing` 动态下发。后端提交校验 / 扣费仍以 `AppState` 当前运行时配置为准，前端内置定价只作为接口失败兜底。模型定价不再按图片 / 规范、视频 / 动作用途拆分，只按模型区分：图片模型按尺寸单次计价，`gemini-3.1-flash-image-preview` 必须配置 `0.5K / 1K / 2K`，`gpt-image-2` 必须配置 `1K / 2K`，规范固定读取 `gpt-image-2` 的 `2K`；视频和角色动作共用视频模型分辨率每秒价格，角色动作仍固定 `seedance2.0-fast`。后台管理页必须显示定价单位“按次 / 按秒”。画板 UI 统一显示 `nanobanana2`，历史输入或旧布局中的 `nano-banana` 必须归一到真实模型 ID 后再提交和计费。 - 影响范围：图片画布生成类面板、生成提交模型、编辑器图片 / 视频 / 音频 BFF、`editor_generation_config`、后台管理端和 Lovart 生成类面板文档。 - 验证方式：运行 `cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_generation_config::tests editor_generation_pricing_route -- --nocapture`、`npx vitest run src/components/image-editor/ImageCanvasGenerationModel.test.ts src/services/image-editor/editorProjectClient.test.ts apps/admin-web/src/pages/AdminEditorGenerationPricingPage.test.tsx apps/admin-web/src/app/adminRoutes.test.ts --reporter verbose`、`npm run admin-web:typecheck`、`npm run check:encoding`、`git diff --check`。 - 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/【编辑器】模型定价配置管理方案-2026-06-22.md`。 ## 2026-06-18 图片画布 UI 设计图提取素材保留图集 - 背景：UI 设计图需要从成图中继续抽取可复用独立素材；原图标素材生成只把拆分后的图标放入画布，spritesheet 原图没有保留，后续追溯和二次切图不方便。 - 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和提示词 `仅提取被红色框框选的素材并整理成spritesheet`，返回结构复用图标 spritesheet 响应。图标生成与 UI 提取都必须把 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放拆分后的 `assetKind="icon"` 素材。 - 影响范围：图片画布浮动工具栏、编辑器图片生成 BFF、`platform-image` 图集连通域拆分、画布图层类型和编辑器文档。 - 验证方式：运行图片画布工具栏 / 图集落层 / 生成提交相关前端测试，`cargo test -p platform-image generated_asset_sheets --manifest-path server-rs/Cargo.toml`，以及 `cargo test -p api-server editor_ui_design_asset_extraction_prompt_is_fixed --manifest-path server-rs/Cargo.toml`。 - 关联文档：`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。 ## 2026-06-18 `/creation` 独立为陶泥儿创作工具主页 - 背景：图片画布项目已经成为独立项目资产，旧“创作”站内 Tab 和一级“草稿”入口不能清晰表达桌面端创作工具主页与项目管理入口。 - 决策：桌面端新增独立 `/creation` 创作工具主页，桌面端直接打开站点首页 `/` 时也默认展示新版创作主页；顶级“创作”入口跳转 `/creation`，原“草稿”入口替换为“项目”并跳转 `/project`。移动端首页 `/` 继续保持原推荐首页，移动端隐藏“创作”和“项目”入口；移动端直达 `/creation` 时不加载创作主页，显示桌面端打开引导，`/creation/` 玩法工作台直达仍按原链路进入。页面文案统一使用“陶泥儿”，外部品牌只作为设计参考，不进入用户可见 UI、测试名、产品文案或验收口径。`陶泥儿精选` 是用户素材瀑布流，不展示玩法入口列表；创作入口事实源继续来自 `/api/creation-entry/config`，项目入口通过 `createEditorProject` 和 `/editor/canvas?projectid=xxx` 链路进入画布。 - 影响范围：平台入口导航、`SelectionStage` 路由、`/creation` 首页、`/project` 项目入口、`/editor/canvas` 项目打开链路、“我的”页快捷入口和创作入口相关测试。 - 验证方式：桌面 `/` 初始阶段和 `/creation` 解析为创作主页，移动端 `/` 仍是推荐首页，`/creation/` 仍进入对应玩法工作台；桌面导航显示“创作 / 项目”且不显示“草稿”；移动端底部不显示“创作 / 项目”；页面不出现外站品牌或 `Discord` 字样；新建项目进入 `/editor/canvas?projectid=xxx`。 - 关联文档：`docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 ## 2026-06-18 图片画布 Seedance 2.0 参考媒体提交边界 - 背景：`/editor/canvas` 生成视频需要严格对齐火山 Seedance 2.0 多模态参考输入；参考视频若继续走 Base64 / `data:video` 会超过请求体并被上游拒绝，参考音频单独输入和非 Seedance 模型携带参考字段也会违反文档契约。 - 决策：仅 `seedance2.0-fast` / `seedance2.0` 可提交参考图片、参考视频、参考音频；图片 0~9、视频 0~3、音频 0~3，音频必须搭配图片或视频。参考视频只能提交公网 URL、`asset://` 或画板资源 `objectKey`，禁止 `data:video/*`；视频 / 音频上传先走 OSS 直传和 asset_object confirm，前端保存 signed URL 预览但提交优先 `objectKey`，后端统一重新签名给 Ark。Ark body 按 `image_url` / `video_url` / `audio_url` + `reference_*` role 构造，并显式发送 `generate_audio:false`。 - 影响范围：图片画布生成视频面板、参考媒体上传工作流、`editorReferenceUploadClient`、`ImageCanvasGenerationSubmissionModel`、`shared-contracts`、`api-server` 编辑器视频 BFF、Lovart 生成类面板文档。 - 验证方式：运行 `npx vitest run src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/services/image-editor/editorReferenceUploadClient.test.ts --reporter verbose`、`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`、`cargo test -p shared-contracts editor_video_request_supports_seedance_multimodal_references --manifest-path server-rs/Cargo.toml`，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。 - 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、火山 Seedance 2.0 任务创建文档。 ## 2026-06-21 图片画布生成视频参数扩展 - 背景：编辑器画布生成视频需要开放更多 Lovart 式参数，同时保留模型能力边界；`seedance2.0-fast` 不支持 `1080p`，联网搜索暂没有可确认的 Ark 视频生成 body 字段。 - 决策：生成视频参数面板支持比例 `16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9`，时长为 4 到 15 秒整数 slider，清晰度支持 `480p / 720p / 1080p`；`seedance2.0-fast` 不展示可用 `1080p`，从其它模型的 `1080p` 切回 Fast 时自动降到 `720p`，后端也拒绝 `seedance2.0-fast + 1080p`。静音只作为一个 toggle 展示，默认有声并映射 `sound=on` / Ark `generate_audio=true`；关闭静音时传 `sound=off` / `generate_audio=false`。`webSearchEnabled` 默认随请求提交为 `true`，但前端不展示联网搜索开关，后端当前只接收契约字段，不向 Ark 透传未知参数。 - 影响范围：图片画布生成视频面板、生成提交模型、画布项目快照恢复、`editorProjectClient`、`shared-contracts`、`api-server` 编辑器视频 BFF、编辑器技术文档。 - 验证方式：运行 `npm run test -- src/components/image-editor/ImageCanvasGenerationModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts`、`cargo test -p shared-contracts editor_video --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`，并执行 `npm run typecheck`、`npm run check:encoding`。 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。 ## 2026-06-18 图片画布生成音乐入口作为音频图层接入 - 背景：图片画布底部生成工具需要补齐游戏音效和游戏背景音乐生成，既要复用现有 Lovart 式画布生成器快照、占位避让和持久化，又不能把音频能力并入图片素材库或视觉小说专用音频开关。 - 决策：`/editor/canvas` 新增底部 `生成音乐` 入口，点击后先弹出“生成游戏音效 / 生成游戏背景音乐”选项框，再分别创建 `audio-sound-effect` 或 `audio-background-music` 生成器；生成结果作为 `mediaType="audio"` 的画布音频卡保存，`assetKind` 分别为 `sound-effect` / `background-music`。音效请求字段固定映射 Vidu `prompt/model/duration`，模型固定 `audio1.0`、时长严格 `2-10` 秒；背景音乐请求字段固定映射 `gpt_description_prompt` 且 `make_instrumental=true`。 - 影响范围：图片画布生成工作流、前端 editorProjectClient、`shared-contracts`、`platform-audio`、`api-server` 编辑器音频 BFF、图片画布技术方案和音乐生成入口设计文档。 - 验证方式：运行编辑器生成入口 / 提交 / 音频图层相关前端测试，`platform-audio` 请求体测试，`shared-contracts` editor audio 序列化测试，`api-server` editor audio 归一化测试，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。 - 关联文档：`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。 ## 2026-06-17 图片画布生成占位统一避让落点 - 背景：图片画布的普通图片、规范、角色、图标、视频和 UI 设计图生成入口都会先在画布中新建“即将生成”的占位图；若各入口直接使用当前视口中心，容易压住已有图片或已有生成占位，Lovart 式连续创作体验不稳定。 - 决策：所有会新建画布生成占位的入口统一经过 `ImageCanvasGenerationPlacementModel` 计算落点。模型以当前视口世界中心为目标，避让所有未隐藏画布图层和 active / inactive generation dialog placeholder，按 32px 画布世界坐标间距外扩阻挡矩形，选择距离当前屏幕中心对应画板位置最近且不重叠的位置。选定后立即调用 `centerViewportOnPlacement(...)`，保持当前缩放比例不变，只平移画布 viewport，让屏幕中心移动到新占位中心。 - 影响范围：`/editor/canvas` 图片画布生成入口、`useImageCanvasGenerationWorkflow`、`ImageCanvasGenerationPlacementModel`、图片画布技术方案和 Lovart 生成类面板文档。 - 验证方式：运行 `npm run test -- src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。 ## 2026-06-13 Pingora 低端口直连只通过显式 systemd drop-in 启用 - 背景：`genarrative-pingora-gateway.service` 默认以 `genarrative` 非 root 用户运行，shadow 阶段只监听本机高端口；如果正式评估让 Pingora 直接绑定公网 `80/443`，需要低端口绑定能力，但不能让 Server-Provision 或默认 service 自动改变接流边界。 - 决策：主 systemd service 保持 shadow 口径，不携带 `CAP_NET_BIND_SERVICE`。仓库提供 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf` 作为人工启用 drop-in 模板，Server-Provision 只安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 备查和手动覆盖；正式切换窗口从 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 执行时默认读取 current release 随包的 `/opt/genarrative/current/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，不依赖 `/etc` 参考模板、Jenkins 工作区或源码 checkout。直连切换前先用 `npm run plan:pingora-direct-cutover -- --require-direct ...` 生成 JSON runbook，逐条审阅 Host 与回退巡检入口确认、current release preflight、启用前基础门禁、direct enable dry-run、direct enable apply（通过命令证据脚本归档 stdout / stderr / 退出码）、切换后 health patrol 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后 `--require-direct` 复核、rollback dry-run、rollback apply（通过命令证据脚本归档 stdout / stderr / 退出码）、回退后 health patrol 切回 `nginx` 并恢复切换前 public base URL / Host、回退后 health patrol env Nginx 模式复核；启用前基础门禁不带 `--require-direct`，因为 systemd drop-in 尚未生效，启用后复核必须带 `--require-direct`。正式切换 runbook 中 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同，避免 redirect 和回退 smoke 分别验证到不同入口；还必须显式传 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，切换前 Nginx 巡检需要 Host 覆盖时再传 `--rollback-health-patrol-public-host <切换前Host>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退 runbook 覆盖现场原有巡检入口。若需把回退后 Pingora shadow 探针复核纳入 runbook，追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，JSON 输出会隐藏 token 原文并把参数传给 rollback dry-run / apply。只有切换窗口通过 `pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名>` 先跑 current release 自审，确认发布包自包含、`pingora-gateway` 可执行且 systemd `ExecStart` 指向随包网关，失败时不安装 drop-in；随后跑 direct preflight，确认当前执行用户和 `genarrative-pingora-gateway.service` 的 `User=` 服务用户都可读取证书链 / 私钥，确认 service 模板与 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含本次 `/etc/genarrative/pingora-gateway.env`，并确认 service `ExecStart=` 指向的 current release `pingora-gateway` 存在且可执行，再安装到 `/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf`、执行 `systemctl daemon-reload`、重启 Pingora，并用 `systemctl cat` 核验 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已生效、用 `systemctl is-active` 确认服务 active、用 direct live smoke 验证 HTTPS / HTTP redirect / ACME / WSS 101 后，才视为授予低端口能力成功。启用前还必须显式配置 TLS / redirect env 和真实证书，并确认 current release 已落盘可执行 `pingora-gateway`、Nginx 或其它进程已释放 `80/443`；启用后仍必须跑 release readiness 门禁；验证失败时统一执行 `pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body ''` 回到 shadow / Nginx 入口，回退脚本会先运行 `nginx -t`，通过后移除 direct-entry drop-in、重启 Pingora，再用 `systemctl cat` 确认两条低端口 capability 均已从最终 unit 配置中移除，用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，并 reload Nginx、确认 Nginx service 仍为 `active`，最后用 curl smoke URL 证明 Nginx 入口真实可访问；回退 smoke URL/body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`。回退脚本 `--apply` 必须同时带 `--reload-nginx` 和 `--nginx-smoke-url`，避免只撤掉 Pingora 低端口能力却没有证明 Nginx 已重新接流；本机打 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 必须带 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免命中默认 vhost。回退后必须复核 health patrol env 已切回 `nginx` 且 public base URL / Host 恢复为切换前记录值；如果 env 已预先修正，rollback 脚本可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 自动执行这项复核，切换前 Nginx 巡检需要 Host 覆盖时把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`。若需证明 Pingora 仍以 shadow 高端口存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token `，脚本会隐藏 token 并要求响应包含 `gateway=pingora-shadow`。 - 决策补充：health patrol env 的直连/回退切换不再靠人工编辑三行变量；正式 runbook 使用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply`，只更新 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE`、`GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL`、`GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST` 并立即调用随包 `check-production-health-patrol-env.mjs` 复核。Pingora direct 使用本机 public base URL 时脚本必须带 `--public-host <域名>`；回退到 Nginx 时根据切换前记录传 `--clear-public-host` 或 `--public-host <切换前Host>`。生产巡检、health patrol env 复核和 env 切换脚本读取的布尔 env 必须严格解析，非法值直接失败，不得静默按 false 继续；env 复核脚本的 `--env-file` 与 env 切换脚本的 `--env-file` / `--check-script` 必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL；env 切换脚本写入的 public base URL / Host 同样不能包含换行或 NUL。Node 22 已内置 `--env-file` 启动参数，凡是用 Node 启动项目脚本且要把业务 `--env-file` 传给脚本时，必须写成 `node --