agens-studio 0.1.0

package/README-CLI.md

@@ -0,0 +1,167 @@
+# Agens 创作工作台 CLI
+
+命令行版 AI 图片/视频创作工具，集成 Agnes AI 生成引擎 + MiMo 大模型提示词优化。
+
+## 功能
+
+| 编号 | 功能 | 说明 |
+|------|------|------|
+| 1 | 文生图 | 文字描述 → AI 优化提示词 → 生成图片 |
+| 2 | 图生图 | 上传参考图 + 描述修改 → 基于原图生成 |
+| 3 | 文生视频 | 文字描述 → 生成视频 |
+| 4 | 图生视频 | 参考图 + 描述动画效果 → 生成视频 |
+| 5 | 多图生视频 | 多张图 → 生成过渡视频 |
+| 6 | 关键帧动画 | 首帧/尾帧/中间帧 → 生成过渡动画 |
+| 7 | 素材库 | 查看/搜索/管理生成的图片和视频 |
+| 8 | 查看配置 | 查看当前 API 和模型配置 |
+| 9 | 配置 API Key | 重新配置 API 密钥 |
+
+## 快速安装
+
+### Windows（推荐）
+
+1. 下载项目压缩包并解压
+2. 双击 `install.bat`
+3. 安装完成后双击 `agens.bat` 启动
+
+### macOS / Linux
+
+```bash
+# 下载并解压后
+chmod +x install.sh
+./install.sh
+./agens
+```
+
+### 已有 Node.js 环境
+
+```bash
+# 克隆或下载项目后
+npm install
+npm run cli
+```
+
+## 首次运行
+
+首次启动会进入 **Setup Wizard**，引导你配置 API Key：
+
+```
+╔══════════════════════════════════════════╗
+║    欢迎使用 Agens 创作工作台 CLI！       ║
+║    首次运行需要配置 API Key               ║
+╚══════════════════════════════════════════╝
+
+── Agnes AI API Key ──
+用于图片生成和视频生成
+Agnes API Key：sk-xxxxxxxxxxxx
+
+── MiMo 大模型 API Key ──
+用于 AI 提示词优化和识图（可选）
+MiMo API Key (tp- 开头)：tp-xxxxxxxxxxxx
+```
+
+配置保存在 `~/.agens-cli/config.json`，后续启动自动加载。
+
+## API Key 获取
+
+| 服务 | 用途 | 获取地址 |
+|------|------|----------|
+| Agnes AI | 图片/视频生成（必需） | https://agnes-ai.com |
+| MiMo | 提示词优化/识图（可选） | https://xiaomimimo.com |
+
+## 配置文件
+
+位置：`~/.agens-cli/config.json`
+
+```json
+{
+  "agens_api_key": "sk-xxxxxx",
+  "mimo_api_key": "tp-xxxxxx",
+  "agens_image_base_url": "https://apihub.agnes-ai.com/v1",
+  "mimo_base_url": "https://token-plan-cn.xiaomimimo.com/v1"
+}
+```
+
+优先级：配置文件 > 环境变量 > 内置默认值
+
+### 环境变量（替代配置文件）
+
+```bash
+# Windows cmd
+set AGENS_IMAGE_API_KEY=sk-xxxxxx
+set AGENS_VIDEO_API_KEY=sk-xxxxxx
+set MIMO_API_KEY=tp-xxxxxx
+node cli.js
+
+# macOS / Linux
+AGENS_IMAGE_API_KEY=sk-xxx node cli.js
+```
+
+## 使用示例
+
+### 文生图
+
+```
+请选择功能：1
+描述你想生成的画面：一个穿着汉服的少女站在樱花树下
+是否用 AI 优化提示词 (Y/n)：Y
+[...] 正在优化提示词...
+
+═══ 优化结果 ═══
+  [主体] 一位身穿白色汉服的年轻少女
+  [场景] 满开的樱花树下，花瓣飘落
+  [风格] 电影级写实
+  ...
+
+比例 (1:1 / 3:4 / 4:3 / 16:9 / 9:16)：9:16
+风格：[1] 写实摄影
+开始生成 (Y/n)：Y
+
+[...] 正在生成图片（Agnes agnes-image-2.1-flash）...
+[...] 正在保存到本地...
+
+═══ 生成完成！═══
+  文件：C:\...\assets\images\xxxx.png
+  大小：2.3 MB
+```
+
+### 图生视频
+
+```
+请选择功能：4
+参考图片路径：C:\Users\...\my_image.png
+描述动画效果：人物轻微呼吸，头发随风轻摆
+
+[...] 正在优化提示词...
+分辨率 (720p / 1080p)：720p
+时长（秒，3-10）：5
+
+[...] 正在提交视频任务...
+  任务 ID：abc123
+  轮询进度...
+
+  ████████████████░░░░░░░░░░░░░░  53%
+
+═══ 生成完成！═══
+  文件：C:\...\assets\videos\xxxx.mp4
+```
+
+## 常见问题
+
+**Q: 中文显示乱码？**
+在 cmd 中先执行 `chcp 65001` 切换到 UTF-8 编码。
+
+**Q: 图片生成后保存卡住？**
+可能是 CDN URL 下载超时。已内置 60s 超时 + 自动重试机制。如果持续失败，检查网络连接或换用代理。
+
+**Q: 如何修改默认配置？**
+编辑 `~/.agens-cli/config.json`，或在菜单中选 [9] 重新配置。
+
+**Q: 生成的文件保存在哪里？**
+默认保存在项目目录下的 `assets/images/` 和 `assets/videos/`。
+
+## 要求
+
+- Node.js v18+
+- 网络连接（调用 Agnes / MiMo API）
+- Windows 10+ / macOS 12+ / Ubuntu 20.04+

package/README.md

@@ -0,0 +1,173 @@
+# agens 创作工作台
+
+一个**本地运行**的即梦风格 AI 创作网页，支持生图、四种视频生成模式，以及内置资产库。
+
+- 🖼 **生图**：文生图
+- 🎬 **文生视频**：纯文本生成视频
+- 🎞 **图生视频**：单张图片 + 文本生成视频
+- 📚 **多图生视频**：多张图片融合生成视频
+- ⏯ **关键帧动画**：首帧 + 尾帧（可选中间帧）生成过渡动画
+- 🗂 **资产库**：所有生成物自动保存到本地磁盘，可预览 / 保留标记 / 备注 / 删除
+
+> 通过 Node 后端代理调用 agens 的视频/生图 API，**API Key 不暴露在浏览器**，大文件直接写入本地磁盘。
+
+---
+
+## 🚀 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install
+```
+
+### 2. （可选）配置 agens API
+
+打开 `config.js`，填写你的 agens 接入信息：
+
+```js
+agens: {
+  baseUrl: 'https://api.agens.xxx.com/v1',  // 你的 API base URL
+  apiKey: 'your-api-key-here',              // 你的 API Key
+  endpoints: {
+    generateImage: '/images/generations',
+    generateVideo: '/videos/generations',
+    taskStatus: '/tasks/{id}',
+  },
+}
+```
+
+也可以用环境变量：
+```bash
+# Windows cmd
+set AGENS_BASE_URL=https://api.agens.xxx.com/v1
+set AGENS_API_KEY=your-key
+npm start
+```
+
+> ⚠️ 如果不配置，应用会进入 **Mock 模式**：用占位图片和示例视频模拟整个流程，方便你先体验 UI 和功能，配好 API 后自动切换为真实调用。
+
+### 3. 启动
+
+```bash
+npm start
+```
+
+浏览器打开 **http://localhost:5173** 即可使用。
+
+开发模式（改文件自动重启）：
+```bash
+npm run dev
+```
+
+---
+
+## 🧭 使用说明
+
+### 创作页
+1. 顶部选择模式（生图 / 文生视频 / 图生视频 / 多图生视频 / 关键帧动画）
+2. 填写提示词
+3. 按需上传参考图（图生 / 多图 / 关键帧模式）—— 支持点击或拖拽
+4. 调整参数（比例、时长、分辨率、风格等）
+5. 点 **生成**，右侧任务队列实时显示进度
+6. 完成后可直接预览，结果自动存入资产库
+
+**关键帧动画**：至少上传 2 张图（首帧 + 尾帧），第 3 张及之后会作为中间帧。
+
+### 资产库
+- 按 **全部 / 图片 / 视频** 筛选
+- 搜索提示词或备注
+- 鼠标悬停视频卡片自动播放预览
+- 点击卡片打开详情弹窗：下载 / 标为保留（⭐）/ 编辑备注 / 删除
+- "只看保留" 可过滤出重点资产
+
+---
+
+## 📁 项目结构
+
+```
+agens/
+├── server.js                    # Express 入口
+├── config.js                    # API Key、端口、路径配置
+├── package.json
+├── src/
+│   ├── routes/
+│   │   ├── generate.js          # POST /api/generate 生成接口
+│   │   ├── task.js              # GET  /api/task/:id 任务状态
+│   │   └── assets.js            # 资产 CRUD + 图片上传
+│   └── services/
+│       ├── agensClient.js       # ★ agens API 适配层（接入真实 API 改这里）
+│       ├── taskManager.js       # 异步任务轮询管理
+│       └── assetStore.js        # 资产落盘 + 索引
+├── public/                      # 前端（原生 HTML/CSS/JS）
+│   ├── index.html
+│   ├── css/style.css
+│   └── js/{api,create,assets,app}.js
+├── assets/{images,videos}/      # 生成物（自动创建）
+├── data/
+│   ├── index.json               # 资产元数据索引
+│   └── uploads/                 # 用户上传的参考图
+└── test/e2e.js                  # 端到端测试
+```
+
+---
+
+## 🔌 API 端点
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET  | `/api/health` | 健康检查，返回是否 Mock 模式 |
+| POST | `/api/generate` | 提交生成任务，立即返回 `{taskId}` |
+| GET  | `/api/task/:id` | 查询任务状态 |
+| GET  | `/api/task` | 最近任务列表 |
+| GET  | `/api/assets` | 列资产（支持 type/search/keptOnly/page/pageSize） |
+| GET  | `/api/assets/:id` | 单个资产详情 |
+| PUT  | `/api/assets/:id` | 更新（kept 保留标记 / note 备注） |
+| DELETE | `/api/assets/:id` | 删除资产（文件 + 索引） |
+| POST | `/api/assets/upload` | 上传参考图（multipart） |
+
+---
+
+## 🛠 接入真实 agens API（阶段 3）
+
+整个项目里**只有一个文件**需要根据 agens 文档修改：`src/services/agensClient.js`。
+
+需要实现三个函数（已留好 TODO 注释和示例）：
+
+1. **`generateImage({prompt, params})`** → 返回 `{url, mime, meta}`
+2. **`generateVideo({mode, prompt, imageUrls, params})`** → 返回 `{remoteTaskId}`
+3. **`getTaskStatus(remoteTaskId)`** → 返回 `{status, result}`，status 必须映射为 `pending | processing | success | failed`
+
+填好 `config.js` 的 `baseUrl` 和 `apiKey` 后，Mock 模式会自动失效，应用改用真实调用。
+
+---
+
+## 🧪 测试
+
+```bash
+# 先启动服务
+npm start
+# 另开终端跑端到端测试（Mock 模式下验证全部 5 种生成模式 + 上传 + 校验）
+node test/e2e.js
+```
+
+---
+
+## 📝 技术栈
+
+- **后端**：Node.js (v18+) + Express 5
+- **前端**：原生 HTML + CSS + JavaScript（无构建步骤、无框架）
+- **存储**：本地磁盘 + 单个 JSON 索引文件（无需数据库）
+
+---
+
+## ❓ 常见问题
+
+**Q：为什么顶部显示 "Mock 模式"？**
+A：`config.js` 里没配置 `baseUrl` / `apiKey`。配好后重启即可。
+
+**Q：重启后任务队列空了？**
+A：任务状态存在内存里（单机够用）。但**资产库是持久化的**，生成物不会丢。
+
+**Q：资产存在哪里？**
+A：`assets/images/` 和 `assets/videos/`，元数据在 `data/index.json`，可以直接在文件管理器里查看原始文件。