.

.env.example

@@ -1,3 +1,12 @@
 # 火山方舟 — 复制为 .env，勿提交 .env
 ARK_API_KEY=
 ARK_ENDPOINT=
+
+# 可选：OpenAI-compatible ASR
+ASR_BASE_URL=
+ASR_MODEL=
+ASR_TRANSCRIBE_PATH=/audio/transcriptions
+ASR_API_KEY=
+
+# 可选：Pexels stock footage
+PEXELS_API_KEY=

.gitignore

@@ -2,6 +2,7 @@ node_modules/
 dist/
 out/
 uploads/
+apps/api/data/
 .env
 .env.local
 *.log

README.md

@@ -101,7 +101,7 @@
 | 代码仓库      | 可运行的完整项目            |
 | 演示视频      | 展示核心流程与亮点           |
 | 视频产物 case | 样例迁移前后的对比案例         |
-| 项目说明文档    | 含整体 AI 架构、工具协议、安全边界 |
+| 项目说明文档    | [`项目说明文档.md`](项目说明文档.md)，含整体 AI 架构、工具协议、安全边界 |
 
 
 详细设计与实现计划见 `[docs/DESIGN.md](docs/DESIGN.md)`。
@@ -346,15 +346,50 @@
 | -------- | ---------------------------------- |
 | 模型       | Doubao-Seed-2.0-lite               |
 | Endpoint | 见团队内部配置                            |
-| API Key  | **勿写入仓库**；使用环境变量，参考 `.env.example` |
+| API Key  | **勿写入仓库**；使用环境变量，参考 `apps/api/.env.example` |
 
 
 ```bash
-# .env（本地，勿提交）
+# apps/api/.env（本地，勿提交）
 ARK_API_KEY=your_key_here
 ARK_ENDPOINT=your_endpoint_here
 ```
 
+可选运行时配置：
+
+```bash
+# ASR：OpenAI-compatible audio transcription endpoint；不配置则跳过转写
+ASR_BASE_URL=
+ASR_MODEL=
+ASR_TRANSCRIBE_PATH=/audio/transcriptions
+ASR_API_KEY=
+
+# 缺口补全：Pexels stock video；不配置则回退 text_card / reused_clip
+PEXELS_API_KEY=
+```
+
+## 本地运行与验证
+
+```bash
+# API
+cd apps/api
+npm install
+npm test
+npm run typecheck
+npm run gen:schema
+npm run regression:case
+npm start
+
+# Web
+cd apps/web
+npm install
+npm run build
+npm run dev
+```
+
+默认 API 端口 `3001`，Web 端口 `5173`，Web 会把 `/api` 代理到 `http://127.0.0.1:3001`。
+`npm run regression:case` 会生成固定 smoke case 的 MP4 和 `apps/api/out/regression/report.json`，用于检查迁移、渲染、QC 和音频质量。
+
 ---
 
 ## 项目文档
@@ -366,6 +401,4 @@ ARK_ENDPOINT=your_endpoint_here
 | `[docs/knowledge/00-项目总览.md](docs/knowledge/00-项目总览.md)` | Obsidian-style 活知识库 / project tracker：模块进展、概念解释、架构与决策记录 |
 | `[docs/PROJECT_TRACKER.md](docs/PROJECT_TRACKER.md)`     | 旧 tracker 入口，已指向 `docs/knowledge/`                      |
 | `[docs/DESIGN.md](docs/DESIGN.md)`                       | 架构、数据模型、实现阶段与里程碑                                        |
-| `docs/ARCHITECTURE.md`                                   | （待写）AI 架构、工具协议、安全边界（交付用）                                |
-
-
+| [`项目说明文档.md`](项目说明文档.md)                         | 项目交付说明：AI 架构、工具协议、安全边界、AI 工具使用与自主实现边界                 |

apps/api/.env.example

@@ -12,3 +12,13 @@ ARK_ENDPOINT=
 
 # 样例 / 用户素材上传大小上限（MB），默认 200；需与 Fastify multipart 一致
 # MAX_UPLOAD_MB=500
+
+# 可选：OpenAI-compatible ASR 转写端点。未配置时 analyze / asr endpoint 会优雅跳过转写。
+# ASR_BASE_URL=https://example.com/v1
+# ASR_MODEL=whisper-1
+# ASR_TRANSCRIBE_PATH=/audio/transcriptions
+# ASR_API_KEY=
+
+# 可选：Pexels 免费视频检索（用真实素材补齐缺口）。无 key 时缺口回退 text_card 占位。
+# 注册免费 key：https://www.pexels.com/api/
+PEXELS_API_KEY=