# 智念AIGC平台

[完整中文说明](./README.zh-CN.md)

这是 `智念AIGC平台` 的 Web 极简 MVP。当前产品只保留核心闭环：统一创作图片/视频、查看结果、局部重绘、智能超清和必要设置。

运维部署与 API 对接：

- [部署说明](./docs/DEPLOYMENT.md)
- [开放 API 对接说明](./docs/API.md)
- OpenAPI：`GET /api/v1/openapi.json`

## 启动

服务器一键部署：

```bash
bash scripts/deploy.sh
```

开发环境：

```bash
cd /Users/inmanx/Documents/zhinian-creation-assistant
npm install
npm run dev -- --hostname 127.0.0.1 --port 3000
```

默认访问：

```text
http://127.0.0.1:3000
```

常用命令：

```bash
npm start
npm run start:server
npm run worker
npm run build
npm test
npm run health
npm run info
```

`npm start` 会自动先执行一次生产构建，再启动 `http://127.0.0.1:3000`；开发调试建议继续使用 `npm run dev`。

Docker 部署默认使用 `docker-compose.yml` 同时启动 Web 服务和 `zhinian-worker` 任务 Worker，访问 `http://服务器IP:3000`。如需修改端口，调整 `.env.local` 中的 `APP_PORT` 和 `NEXT_PUBLIC_APP_URL` 后重新执行 `bash scripts/deploy.sh`。

## Web MVP 信息架构

- `/` 自动跳转到 `/create`
- `/create` 创作，合并图片、视频、局部重绘、智能超清
- `/assets` 结果，保留历史资产和历史生成任务
- `/image-edit` 兼容旧入口，自动跳转到创作页的局部重绘
- `/settings` 设置

主导航只保留创作、结果、设置，不包含工作台、项目、模板中心、Billing 或桌面端入口。

## 账户登录 / SSO

发布环境默认要求账户登录。Web 登录支持两种方式：一是 OAuth2 Authorization Code，用户跳转到认证中心登录，本服务在 `/api/auth/callback` 后端换 token；二是在本项目登录页直接输入账号、密码和图形验证码，由本服务后端调用 `${AUTH_BASE}/oauth2/token` 的 password grant。两种方式都会通过 `${AUTH_BASE}/oauth2/jwks` 本地验签 JWT，再写入 HttpOnly 会话 cookie。

需要在认证中心客户端配置中加入回调地址：

```text
https://你的域名/api/auth/callback
```

关键环境变量：

- `ZHINIAN_AUTH_REQUIRED=auto`：生产默认启用；本地可信开发可设为 `0`
- `ZHINIAN_AUTH_BASE_URL=https://<gateway-domain>/auth`
- `ZHINIAN_AUTH_CLIENT_ID=customPC`
- `ZHINIAN_AUTH_CLIENT_SECRET`
- `ZHINIAN_AUTH_SCOPE=server`
- `ZHINIAN_AUTH_ISSUER=https://pig4cloud.com`
- `ZHINIAN_AUTH_PASSWORD_ENC_KEY`：按 AgentBus 方式对 password grant 的密码做 AES-CFB 加密；留空则透传明文
- `ZHINIAN_AUTH_SESSION_SECRET`：长随机字符串，用于签名本地登录态

`/create`、`/assets`、`/settings`、第一方生成/资产 API、以及本地上传和生成结果文件都会受登录态保护。`/api/v1/*` 继续使用 `ZHINIAN_API_KEYS`，不走浏览器 SSO。

如果认证中心客户端未加入 `security.ignore-clients`，登录页的账号密码方式会要求图形验证码；验证码图片由 `/api/auth/captcha` 代理 `${AUTH_BASE}/code/image` 获取。

## 图片创作引擎

图片生成和局部重绘支持在设置页「状态」里按功能切换创作引擎：

- `jimeng`：默认引擎，走火山 Visual 即梦能力。
- `evolink`：走 EvoLink GPT Image 2 中转站，提交任务后轮询 EvoLink task 结果。

智能超清仍走即梦超清能力。

## 即梦图片能力

V1 接入三类能力：

- `image.generate`：即梦图片生成 4.6，默认 `req_key=jimeng_seedream46_cvtob`
- `image.inpaint`：交互编辑 inpainting，默认 `req_key=jimeng_image2image_dream_inpaint`
- `image.upscale`：智能超清，默认 `req_key=jimeng_i2i_seed3_tilesr_cvtob`

后端统一走火山 Visual 异步任务：

- 提交：`CVSync2AsyncSubmitTask`
- 查询：`CVSync2AsyncGetResult`

未配置火山密钥时，`JIMENG_VISUAL_MOCK=auto` 会自动使用 mock 图，方便先跑通产品流。

## EvoLink 图片能力

设置 `IMAGE_GENERATE_ENGINE=evolink` 或 `IMAGE_INPAINT_ENGINE=evolink` 后，对应功能会使用 EvoLink：

- 提交：`POST /v1/images/generations`
- 查询：`GET /v1/tasks/{task_id}`
- 默认模型：`gpt-image-2`

未配置 `EVOLINK_API_KEY` 且 `EVOLINK_MOCK=auto` 时，会自动使用 mock 图。

## AI 生成台与提示词编排

`/create` 是新的统一生成入口，按即梦“图片/视频能力在同一个创作产品内切换”的方式组织：

- 一个提示词框：图片和视频都在同一创作面板内编辑最终提示词。
- 模式切换：图片模式走即梦图片生成 4.6；视频模式走 Seedance 视频生成。
- 素材统一上传：一个入口上传图片、视频或音频，不再拆分参考图、主体、分镜等栏目。
- `@素材` 引用：上传后自动绑定为 `@图片1`、`@视频1`、`@音频1`，chip 和 @ 候选项都显示缩略图。
- 提示词校验：通过 `/api/prompt/assemble` 检查提示词中引用的素材是否已绑定。
- 工作台只负责生成输入和提交，不展示任务列表或最近结果。
- 结果保存：图片和视频生成结果会写入资产记录，并在 `/assets` 保留历史任务与历史资产。

未配置 `SEEDANCE_API_KEY` 时，`SEEDANCE_MOCK=auto` 会自动使用旧模板样片作为 mock 成品，方便先验收工作流。

## 环境变量

复制配置样例：

```bash
cp .env.example .env.local
```

核心配置：

- `ZHINIAN_AUTH_REQUIRED=auto`
- `ZHINIAN_AUTH_BASE_URL`
- `ZHINIAN_AUTH_CLIENT_ID=customPC`
- `ZHINIAN_AUTH_CLIENT_SECRET`
- `ZHINIAN_AUTH_SCOPE=server`
- `ZHINIAN_AUTH_ISSUER=https://pig4cloud.com`
- `ZHINIAN_AUTH_SESSION_SECRET`
- `IMAGE_GENERATE_ENGINE=jimeng` 或 `evolink`
- `IMAGE_INPAINT_ENGINE=jimeng` 或 `evolink`
- `VOLCENGINE_ACCESS_KEY_ID`
- `VOLCENGINE_SECRET_ACCESS_KEY`
- `VOLCENGINE_REGION=cn-north-1`
- `VOLCENGINE_SERVICE=cv`
- `VOLCENGINE_VISUAL_ENDPOINT=https://visual.volcengineapi.com`
- `EVOLINK_API_KEY`
- `EVOLINK_BASE_URL=https://api.evolink.ai`
- `EVOLINK_IMAGE_MODEL=gpt-image-2`
- `EVOLINK_IMAGE_QUALITY=medium`
- `EVOLINK_IMAGE_RESOLUTION=2K`
- `EVOLINK_MOCK=auto`
- `SEEDANCE_API_KEY`
- `SEEDANCE_BASE_URL`
- `SEEDANCE_MODEL`
- `SEEDANCE_RATIO`：支持 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`
- `SEEDANCE_DURATION`：Seedance 2.0 支持 `4` 到 `15` 的整数秒，或 `-1` 让模型自动选择
- `SEEDANCE_RESOLUTION`：支持 `480p`、`720p`、`1080p`；Seedance 2.0 fast 不支持 `1080p`
- `SEEDANCE_MOCK`
- `ALI_OSS_*`：用于上传素材和生成结果转存
- `NEXT_PUBLIC_SUPABASE_URL`
- `NEXT_PUBLIC_SUPABASE_ANON_KEY`
- `SUPABASE_SERVICE_ROLE_KEY`

如果 Supabase 未配置，应用会使用 `.runtime/data/web-app-state.json` 做本地开发数据层。如果 OSS 未配置，上传和 mock 结果会保存到 `.runtime/uploads` 和 `.runtime/generated-results`，并通过 Web 路由提供访问。

## 数据库

Supabase/Postgres 表结构在：

```text
supabase/schema.sql
```

当前仍保留必要数据表，供上传、生成任务和用量记录使用：

- `assets`
- `generation_jobs`
- `usage_events`

## 任务管理与开放 API

平台支持服务端任务管理：页面和 `/api/v1` 创建任务后只入队，Worker 统一提交供应商、轮询、转存结果、失败重试和 Webhook 回调。生产部署建议配置 Supabase/Postgres；本地开发可继续使用 `.runtime/data/web-app-state.json`。

开放 API 使用 API Key：

```env
ZHINIAN_API_KEYS=demo-agent:change-me-public-api-key
ZHINIAN_INTERNAL_WORKER_TOKEN=change-me-worker-token
```

主要接口：

- `GET /api/v1/capabilities`
- `POST /api/v1/assets`
- `GET /api/v1/assets`
- `POST /api/v1/jobs`
- `GET /api/v1/jobs`
- `GET /api/v1/jobs/[id]`
- `POST /api/v1/jobs/[id]/cancel`
- `GET /api/v1/openapi.json`

任务创建支持 `Idempotency-Key` 幂等键和 `webhookUrl` 完成回调。Worker 可用 `npm run worker` 常驻运行，或 `npm run worker:once` 单次处理。

## API

核心图片 API：

- `POST /api/generations/image`
- `GET /api/generations/image`
- `GET /api/generations/image/[id]`
- `POST /api/generations/image/[id]/retry`
- `POST /api/assets/[id]/inpaint`
- `POST /api/assets/[id]/upscale`
- `POST /api/generations/video`
- `GET /api/generations/video`
- `GET /api/generations/video/[id]`
- `POST /api/prompt/assemble`
- `GET /api/assets`
- `POST /api/assets`
- `POST /api/assets/upload`

健康检查：

- `GET /api/health`

## 验证

当前已覆盖：

- 即梦能力矩阵：4.6/inpainting/upscale 启用
- 即梦请求参数构造
- 分镜提示词与 `@素材` 引用编排
- 火山 Visual 签名 canonical request
- Next.js 生产构建

```bash
npm test
npm run build
npm run health
```