merge: promote beta release 2026-04-27

# Conflicts:
#	README.md
#	docs/releases/release-notes.md

Author: wnagchi

.env.example

@@ -9,8 +9,20 @@ PORT=3000
 HOST=localhost
 ALLOW_LAN=false
 CORS_ORIGIN=http://localhost:5173
-DATABASE_URL=file:./dev.db
+# 默认使用 SQLite；如需 PostgreSQL，取消下一行注释并填写连接串。
+# DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/ai_novel
 API_JSON_LIMIT=20mb
+
+# 图片资产存储：默认使用 beta 本地文件存储。仅在显式选择 s3/minio 时启用 MinIO/S3。
+# IMAGE_STORAGE_DRIVER=local
+# IMAGE_STORAGE_ROOT=storage/generated-images
+# IMAGE_STORAGE_DRIVER=minio
+# IMAGE_STORAGE_S3_ENDPOINT=http://127.0.0.1:9000
+# IMAGE_STORAGE_S3_REGION=us-east-1
+# IMAGE_STORAGE_S3_BUCKET=ai-novel-images
+# IMAGE_STORAGE_S3_ACCESS_KEY_ID=
+# IMAGE_STORAGE_S3_SECRET_ACCESS_KEY=
+# IMAGE_STORAGE_S3_FORCE_PATH_STYLE=true
 BOOK_ANALYSIS_LLM_TIMEOUT_MS=90000
 
 OPENAI_API_KEY=

AGENTS.md

@@ -55,25 +55,35 @@
 ## Development Branch Workflow
 
 - When developing a new feature that may affect the end-to-end product flow, default workflow, shared contracts, or other major system links, do not develop directly on `main`.
-- In these cases, first create or switch to a dedicated `dev` branch for that feature, complete implementation and functional verification there, and merge back to `main` only after the feature is tested and stable enough.
-- After the feature branch has been successfully merged back into `main`, clean up that development branch so old feature branches do not accumulate indefinitely.
+- In these cases, first create or switch to a dedicated feature development branch, complete implementation and functional verification there, then merge into the pre-release `beta` branch for integration verification. Merge back to `main` only after `beta` has been tested and stable enough for release.
+- After the feature branch has been successfully merged into `beta` and no longer needs follow-up work, clean up that development branch so old feature branches do not accumulate indefinitely.
 - This rule applies in particular to changes that touch cross-stage workflows, shared runtime/prompting/context contracts, automatic director chains, chapter execution chains, data migration behavior, or other changes that can impact the overall chain.
-- Small isolated fixes, copy changes, low-risk UI polish, or documentation-only updates can still be handled without requiring a separate feature `dev` branch unless the user explicitly asks otherwise.
-
-### Temporary Desktop Branch Policy
-
-- Until desktopization work is completed and `desktop-dev` has been merged back into `main`, treat `desktop-dev` as the long-lived integration branch for desktop-related development.
-- During this temporary phase, `main` remains the stable branch for already verified work, small isolated fixes, documentation changes, and low-risk updates that do not need to wait for desktopization to finish.
-- Do not merge every new `main` commit into `desktop-dev` immediately by default. Sync in batches when it is actually useful, instead of creating unnecessary merge noise.
-- You must sync `main` into `desktop-dev` when any of the following is true:
-  - `main` changed shared contracts, shared runtime/state logic, build/dependency setup, or any other code that `desktop-dev` also depends on;
-  - a new `desktop-dev` work slice is about to start and it should build on the latest stable base;
-  - `desktop-dev` is about to enter integration testing, release verification, or merge-back into `main`;
-  - `desktop-dev` has drifted far enough from `main` that conflict risk is starting to rise.
-- If `main` only contains clearly unrelated small fixes, copy edits, or other low-risk changes that do not affect desktopization, it is acceptable to delay the sync and merge them into `desktop-dev` later as a batch.
-- If a new change is expected to affect both the normal web flow and the ongoing desktopization work, prefer implementing it on a dedicated short-lived feature branch or directly on `desktop-dev`, instead of landing it on `main` first and forcing immediate back-merges.
-- When syncing `main` into `desktop-dev`, prefer `merge` if the branch is shared by multiple collaborators. Only use `rebase` when the branch is effectively single-owner and history rewriting will not disrupt anyone else.
-- Once desktopization has been completed, merged into `main`, and the `desktop-dev` branch has been retired, this temporary policy should be considered expired and the repository should fall back to the normal feature-branch workflow above.
+- Small isolated fixes, copy changes, low-risk UI polish, or documentation-only updates can still be handled without requiring a separate feature development branch unless the user explicitly asks otherwise. If the change is release-facing, still prefer passing through `beta` before `main`.
+
+### Pre-release Beta Branch Workflow
+
+- Use `beta` as the stable pre-release integration branch between feature development branches and `main`.
+- The normal release path is: feature branch -> self-test / targeted verification -> merge into `beta` -> integration testing / regression checks / packaging verification -> merge into `main` -> public release or packaging upload.
+- `main` is the stable release branch. Do not merge a feature branch directly into `main` when the change affects product flow, shared contracts, runtime behavior, data migration, desktop packaging, or other end-to-end links.
+- `beta` should represent the next candidate release. Keep it buildable, runnable, and suitable for acceptance testing; do not use it as a dumping ground for unfinished experiments.
+- If multiple feature branches are merged into `beta`, test the combined behavior on `beta` before promoting the batch to `main`, especially around automatic director flow, chapter execution, prompt/runtime contracts, migrations, and desktop startup or packaging.
+- If `beta` validation fails, fix the issue on the original feature branch when the fault is isolated, or on a short-lived `beta-fix` branch when the failure is caused by integration between multiple features. Merge the fix back into `beta` and rerun the failed checks before promoting.
+- Only promote `beta` to `main` when the release candidate has passed the required functional checks, build checks, and any packaging verification relevant to the release. After promotion, keep `beta` aligned with `main` so the next pre-release cycle starts from the released state.
+- For urgent production hotfixes, it is acceptable to branch from `main`, verify narrowly, merge back to `main`, and then immediately merge or cherry-pick the hotfix into `beta` so the pre-release branch does not lose the production fix.
+- Public desktop packaging and release upload should be performed from `main` or from a release tag created after `beta` has been promoted to `main`, not directly from a feature branch or an unverified `beta` state.
+- The branch name is `beta`. Do not create a separate `bate` branch; if such a typo branch appears, migrate any useful work to `beta` and remove the typo branch after confirming nothing is lost.
+
+### Desktop Branch Completion Workflow
+
+- Desktop feature development on `desktop-dev` is considered complete. Do not start new desktop feature work directly on `desktop-dev` unless the user explicitly reopens desktopization as an active development phase.
+- Treat `desktop-dev` as a completion candidate that must move through stabilization, pre-release verification, and branch retirement.
+- Before promoting desktop work, sync any required stable changes from `main` into `desktop-dev` when they affect shared contracts, runtime/state logic, build/dependency setup, desktop startup, packaging, or release verification.
+- Run desktop-focused verification on `desktop-dev` first, including development startup, first-run configuration, core web flow compatibility, build checks, and packaging checks relevant to the target release.
+- After `desktop-dev` passes its focused verification, merge it into `beta` for combined pre-release testing with the rest of the next release candidate.
+- Do not promote desktop work from `desktop-dev` directly to `main`. `beta` must pass integration testing and release packaging verification before the desktop work reaches `main`.
+- If `beta` exposes desktop integration failures, fix them on a short-lived desktop stabilization branch or directly on `desktop-dev` if the desktop branch has not yet been retired, then merge the fix back into `beta` and rerun the failed checks.
+- Once `beta` has been promoted to `main` and the released `main` contains the completed desktop work, retire `desktop-dev` so future desktop changes follow the normal feature branch -> `beta` -> `main` workflow.
+- After retirement, `desktop-dev` should not be reused as a long-lived integration branch. Create short-lived feature branches for future desktop fixes or improvements, and promote them through `beta`.
 
 ## Desktop Packaging Upload Rules
 

Dockerfile.api

@@ -0,0 +1,64 @@
+ARG NODE_IMAGE=node:20-bookworm-slim
+FROM ${NODE_IMAGE} AS base
+ENV PNPM_HOME=/pnpm
+ENV PATH=${PNPM_HOME}:${PATH}
+ENV NODE_ENV=development
+USER root
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends python3 make g++ openssl \
+    && rm -rf /var/lib/apt/lists/* \
+    && corepack enable
+
+FROM base AS deps
+WORKDIR /app
+RUN rm -rf /app/* /app/.[!.]* /app/..?* || true
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json .npmrc ./
+COPY client/package.json ./client/package.json
+COPY server/package.json ./server/package.json
+COPY shared/package.json ./shared/package.json
+RUN pnpm install --frozen-lockfile
+
+FROM deps AS build
+WORKDIR /app
+ENV AI_NOVEL_DATABASE_MODE=postgresql
+COPY shared/package.json shared/tsconfig.json ./shared/
+COPY shared/*.ts ./shared/
+COPY shared/types ./shared/types
+COPY server/package.json server/tsconfig.json server/prisma.config.ts ./server/
+COPY server/src ./server/src
+RUN pnpm --filter @ai-novel/shared build \
+    && pnpm --filter @ai-novel/server prisma:generate \
+    && pnpm --filter @ai-novel/server build
+
+FROM base AS prod-deps
+WORKDIR /app
+RUN rm -rf /app/* /app/.[!.]* /app/..?* || true
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json .npmrc ./
+COPY client/package.json ./client/package.json
+COPY server/package.json ./server/package.json
+COPY shared/package.json ./shared/package.json
+COPY server/prisma.config.ts ./server/prisma.config.ts
+COPY server/src/config/database.ts ./server/src/config/database.ts
+COPY server/src/prisma ./server/src/prisma
+ENV AI_NOVEL_DATABASE_MODE=postgresql
+RUN pnpm install --frozen-lockfile \
+    && pnpm --filter @ai-novel/server prisma:generate
+
+ARG NODE_IMAGE
+FROM ${NODE_IMAGE} AS runtime
+USER root
+WORKDIR /app
+ENV NODE_ENV=production
+RUN rm -rf /app/* /app/.[!.]* /app/..?* || true
+COPY --from=build --chown=node:node /app/package.json ./package.json
+COPY --from=build --chown=node:node /app/pnpm-workspace.yaml ./pnpm-workspace.yaml
+COPY --from=prod-deps --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/server ./server
+COPY --from=build --chown=node:node /app/shared ./shared
+RUN mkdir -p /app/storage/generated-images /app/node_modules/.bin \
+    && printf '%s\n' '#!/bin/sh' 'exec node /app/server/node_modules/prisma/build/index.js --config /app/server/prisma.config.ts "$@"' > /app/node_modules/.bin/prisma \
+    && chmod +x /app/node_modules/.bin/prisma \
+    && chown -R node:node /app
+USER node
+EXPOSE 3000
+CMD ["node", "./server/dist/app.js"]

Dockerfile.web

@@ -0,0 +1,37 @@
+ARG NODE_IMAGE=node:20-bookworm-slim
+ARG NGINX_IMAGE=nginxinc/nginx-unprivileged:1.27-alpine
+FROM ${NODE_IMAGE} AS base
+ENV PNPM_HOME=/pnpm
+ENV PATH=${PNPM_HOME}:${PATH}
+ENV NODE_ENV=development
+USER root
+RUN corepack enable
+
+FROM base AS deps
+WORKDIR /app
+RUN rm -rf /app/* /app/.[!.]* /app/..?* || true
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json .npmrc ./
+COPY client/package.json ./client/package.json
+COPY shared/package.json ./shared/package.json
+RUN pnpm install --frozen-lockfile --filter @ai-novel/shared --filter @ai-novel/client
+
+FROM deps AS build
+WORKDIR /app
+ARG VITE_API_BASE_URL=
+ENV VITE_API_BASE_URL=${VITE_API_BASE_URL}
+COPY shared/package.json shared/tsconfig.json ./shared/
+COPY shared/*.ts ./shared/
+COPY shared/types ./shared/types
+COPY client/package.json client/tsconfig.json client/vite.config.ts client/tailwind.config.ts client/postcss.config.js client/components.json client/index.html ./client/
+COPY client/public ./client/public
+COPY client/src ./client/src
+RUN pnpm --filter @ai-novel/shared build \
+    && pnpm --filter @ai-novel/client build
+
+FROM ${NGINX_IMAGE} AS runtime
+USER root
+RUN rm -rf /usr/share/nginx/html/*
+COPY --from=build --chown=101:101 /app/client/dist/ /usr/share/nginx/html/
+COPY --chown=101:101 infra/nginx/ai-novel-web.conf /etc/nginx/conf.d/default.conf
+USER 101
+EXPOSE 8080

README.md

@@ -32,22 +32,7 @@
 - 最新版本页：[Latest Release](https://github.com/ExplosiveCoderflome/AI-Novel-Writing-Assistant/releases/latest)
 - 建议优先下载 `Setup.exe` 安装版；如果你不想安装，或者想放在 U 盘 / 临时目录里直接运行，再选择 `portable` 版本
 
-## Beta 预发体验
 
-新功能会优先发布到 `beta` 分支，完成预发验证并稳定后再合入 `main`。如果你想提前体验最新能力，可以切换到 `beta` 分支运行源码版；如果你更看重稳定使用，建议继续使用 `main` 分支或 Releases 中的正式版本。
-
-```bash
-git fetch origin
-git switch beta
-git pull
-```
-
-如果本地还没有 `beta` 分支，可以使用：
-
-```bash
-git fetch origin
-git switch -c beta origin/beta
-```
 
 ## 项目定位
 
@@ -139,13 +124,12 @@ git switch -c beta origin/beta
 
 完整历史更新见 [docs/releases/release-notes.md](./docs/releases/release-notes.md)。
 
-### 2026-04-26
+### 2026-04-27
 
-项目授权口径已调整为 AGPLv3 + 商业授权说明。
+自动导演前三章连续生成和接管配置继续补稳。新手把小说交给 AI 自动推进时，章节正文与配套资产会更稳地保存，恢复任务或重新打开弹窗时也更不容易被配置回跳打断。
 
-- 项目默认采用 GNU AGPLv3 授权，继续保留可学习、可修改、可按开源协议合规使用的路径。
-- 服务型商用口径已明确：将本项目或修改版本作为后端，以 SaaS、托管或其他形式向第三方提供服务，需要先取得作者商业授权。
-- 贡献者许可协议已补齐，外部贡献者提交 PR 时可以明确确认自己有权提交内容，并同意贡献可用于项目开源版本和维护者另行提供的商业授权版本。
+- 自动导演连续生成前三章的链路更稳，章节正文和配套资产同步会避开重复保存，并在本地数据库短暂繁忙时自动等待重试。
+- 开书和已有项目接管弹窗里的模型选择、自动审批偏好更稳定，恢复任务或重新打开弹窗时会减少重复刷新和配置回跳。
 
 ## 功能预览
 ### 功能概览中的95%以上编写都是AI完成

TASK.md

@@ -1,6 +1,6 @@
 # AI 长篇成书当前执行计划（小白用户导向）
 
-更新时间：2026-04-18
+更新时间：2026-04-26
 适用范围：当前 `AI-Novel-Writing-Assistant2` 代码库现状  
 目标用户：完全不懂写作、希望通过 AI 引导或全自动规划完成整本小说创作的用户  
 当前定位：强辅助型 AI 小说工作台  
@@ -1036,4 +1036,54 @@ P2 重点解决：
 - 2026-04-10 00:45 [已计划] 已记录后续优化方向：先做常见错误预修复，再增强 AI 修复失败原因分类与模型切换提示。
 - 2026-04-24 10:51 [开发中] 已吸收 PR #22 中可安全并入主线的部分：对“对象 schema + 单元素数组包裹”增加 schema-aware 本地解包，对中转站 / Relay 返回的 HTML 错页改判为 `transport_error`，并补充 markdown fenced JSON、字段缺失、AI 修复后仍缺字段、HTML 错页与单元素数组包裹的 targeted regression tests；更细粒度的字段缺失提示合同仍待继续收口。
 <!-- task-md-sync:item:task-3b8c9c2f4a:end -->
+<!-- task-md-sync:item:task-65a7562c11:start -->
+### 角色资源账本与背包系统
+- 标识：`task-65a7562c11`
+- 状态：已完成
+- 最近更新：2026-04-25 08:41
+- 概要：完成角色背包剩余闭环：任务抽屉待确认入口、卷级资源承诺视图、旧项目最近章节资源回填，以及资源复查/回填的独立提交路径。
+
+计划清单：
+- [x] 小说任务抽屉展示资源变更待确认，并支持来源跳转、确认、忽略
+- [x] 卷战略页展示本卷关键资源承诺，帮助规划本卷行动边界和后续兑现
+- [x] 角色准备页提供最近章节资源回填入口，用于已有正文或旧项目轻量补账
+- [x] 资源复查/回填跳过通用章节事实提取，只提交角色资源 proposal
+- [x] 完成 shared/server/client build 与 targeted tests 验证
+
+进度记录：
+- 2026-04-25 08:41 [已完成] 2026-04-25: 完成角色背包剩余闭环；待确认资源进入小说任务抽屉，卷战略可查看本卷资源承诺，旧项目可手动回填最近章节资源。
+<!-- task-md-sync:item:task-65a7562c11:end -->
+<!-- task-md-sync:item:task-a9206e4ae1:start -->
+### 预发 beta 分支发布流程规则
+- 标识：`task-a9206e4ae1`
+- 状态：已完成
+- 最近更新：2026-04-25 00:35
+- 概要：已在 AGENTS.md 写入 beta 预发分支规则，并将已完成的 desktop-dev 调整为收尾验证、合入 beta/main、退休分支的流程。
+
+计划清单：
+- [ ] 确认 AGENTS.md 现有开发分支、desktop-dev、打包发布规则之间的关系
+- [ ] 新增 beta 预发分支工作流，明确功能分支、自测、预发集成、发布回 main 的顺序
+- [ ] 将 desktop-dev 从长期集成分支调整为已完成功能的收尾验证、合入 beta/main、退休流程
+- [ ] 补充发布与桌面打包前必须基于 beta 验证稳定的约束
+
+进度记录：
+- 2026-04-25 00:35 [已完成] 已完成 AGENTS.md 分支规则更新：功能分支先入 beta 预发验证，desktop-dev 作为完成候选进入 beta/main 后退休。
+<!-- task-md-sync:item:task-a9206e4ae1:end -->
+<!-- task-md-sync:item:task-3ae84511d6:start -->
+### 角色库与小说角色同步系统
+- 标识：`task-3ae84511d6`
+- 状态：开发中
+- 最近更新：2026-04-26 14:27
+- 概要：首轮后端闭环已落地，并补充角色系统长期升级文档：后续围绕角色叙事岗位、关系张力和章节角色上下文包继续推进。
+
+计划清单：
+- [ ] 第一期开发角色叙事岗位 MVP：为小说角色生成本书职责、读者收益、剧情发动方式和红线
+- [ ] 第一期开发章节角色上下文包 MVP：让章节生成、审稿、修复消费角色任务而不是只读角色列表
+- [ ] 第一期接入关系张力摘要：输出本章需要推进或避免写崩的核心关系变化
+- [ ] 为角色同步工作台接入前端入口：角色库引入、保存到角色库、同步建议列表
+- [ ] 扩展端到端测试，覆盖同一角色被多本小说引用时的应用、忽略、分叉路径
+
+进度记录：
+- 2026-04-26 14:27 [开发中] 已新增角色系统升级长期方案文档和第一期开发方案，并与角色资源账本文档建立互链
+<!-- task-md-sync:item:task-3ae84511d6:end -->
 <!-- task-md-sync:end -->