# AI 创作工作室 Agent

> 周期建议：7–10 天。默认只使用本地 Mock Provider，不需要、也不得提交任何真实模型凭证。

## 项目背景

一个小型内容团队每天要把零散想法变成可交付的图文素材。目前创作者通常直接在聊天框里反复改 Prompt：需求没有结构、版本无法比较、生成失败后不知道发生了什么，最终素材也无法回答“由哪个需求、哪版 Prompt、哪个模型产生”。

团队需要一个本地可运行的“AI 创作工作室”。它不追求接入最多模型，而是把一次创作从意图澄清、Prompt 版本、异步生成到资产留痕走完整。

## 项目目标

交付一个可演示的 Web 产品：用户填写创作 Brief，系统形成可编辑且有版本的 Prompt，按规则选择 Mock Provider，异步产生模拟素材，并在资产详情中保留完整来源证据。

完成后，陌生人应能只按 `README.md` 在本地启动系统，走通一条成功路径和一条失败恢复路径。

## 用户故事

- 作为创作者，我希望把受众、渠道、风格和限制写成 Brief，从而减少遗漏和反复沟通。
- 作为创作者，我希望保存每版 Prompt 并比较差异，从而知道修改产生了什么影响。
- 作为运营人员，我希望看见任务状态、失败原因和重试记录，从而判断交付是否可靠。
- 作为审核者，我希望从素材追溯到 Brief、Prompt 版本和 Provider，从而核验内容来源。

## 功能要求

### 必须完成

1. **结构化 Brief**
   - 至少包含：创作目标、目标受众、投放渠道、内容形式、风格关键词、必须出现内容、禁止出现内容。
   - 对必填项、长度和非法值给出明确错误，不得静默丢字段。
2. **Prompt 版本**
   - 能从 Brief 生成一版确定性的建议 Prompt，也允许用户编辑后保存新版本。
   - 已保存版本不可被原地覆盖；列表能显示版本号、创建时间和变更摘要。
3. **Provider Adapter 与路由**
   - 至少提供两个行为可区分的本地 Mock Provider。
   - 路由规则必须写入文档，并在任务详情展示实际选择及原因。
4. **异步生成任务**
   - 任务至少包含 `queued`、`running`、`succeeded`、`failed` 状态。
   - 前端或 API 能观察状态变化；失败时返回稳定错误码和可理解信息。
5. **失败恢复**
   - 可通过受控输入稳定触发一次 Mock 失败。
   - 重试必须形成新的尝试记录，不能抹掉原失败事实，也不能重复创建成功资产。
6. **创作资产与追溯**
   - 成功任务产生一个模拟资产，可以是本地占位图、文本文件或结构化结果。
   - 资产详情至少关联 Brief、Prompt 版本、Provider、任务、生成时间和参数摘要。
7. **最小工作台**
   - 提供 Brief/Prompt 编辑、任务列表、任务详情和资产详情。
   - 空状态、加载中、失败和成功状态均可辨认。

### 可选增强

- Prompt 版本差异视图。
- 资产草稿、发布、撤回状态；这里的“发布”只能是本地状态变化，不得自动发送到外部平台。
- 基于标签的资产检索或创作模板复用。
- 在 Mock 之外增加真实 Provider Adapter 的接口设计，但验收仍必须能在无凭证时完整运行。

## 非功能要求

- **可运行性**：提供一条清晰的本地启动路径和种子数据；默认路径不得依赖付费服务。
- **可靠性**：相同重试请求不得产生重复资产；未知任务、非法状态迁移和 Provider 失败均有稳定处理。
- **性能**：除模拟生成等待外，本地常规读写接口在 30 条任务规模下应在 2 秒内返回。
- **可维护性**：领域状态、Provider 适配和 UI/API 不得全部混在一个巨型函数中；关键边界有测试。
- **安全与隐私**：日志和页面不得显示凭证、Cookie 或完整敏感请求头；用户输入不能被当作系统配置执行。
- **无障碍**：核心流程可通过键盘完成，表单控件有可识别标签，状态不能只靠颜色表达。

## 范围与限制

### 范围内

- 单用户、本地运行的创作工作台。
- 文本或图片类模拟创作中的一种。
- Brief、Prompt 版本、任务状态、Mock 路由、失败恢复和资产追溯。
- 为验收准备的合成示例数据。

### 范围外

- 真实社交媒体发布、内容分发或版权采购。
- 真实支付、计费、账号体系、多人协作权限。
- 训练或微调模型，以及判断生成内容具有法律意义上的版权。
- 复制任何现有参考项目的源码或内部数据。

### 技术与时间限制

- 周期为 7–10 天；先完成主路径与证据，再考虑增强项。
- 技术栈可自选，但必须提供 Web UI，并提供可自动测试的服务层或 API。
- 数据可使用 SQLite、嵌入式数据库或本地文件；需说明一致性与并发假设。
- 默认必须使用本地 Mock Provider。不得要求组织者或学员提供个人 API Key。
- 不要求公网部署；若自行部署，仍必须保留无外部依赖的本地验收路径，且不得产生费用或公开测试数据。

## 澄清机制

在“澄清 Issue”中提问，并写明：背景、具体歧义、候选方案、你的推荐、不同选择的影响，以及未回复时准备采用的可逆假设。

例如“建议 Prompt 是否允许覆盖旧版本”属于必须先识别的产品歧义。若问题只影响展示细节，可记录假设后继续；若会扩大核心范围、引入费用、调用外部平台或处理敏感数据，必须等待组织者确认。遇到题面未覆盖的 D/or 情况，不要强行塞进现有选项，应记录新的合理路径及验证办法。

## 交付物与证据

- 可运行源码、依赖锁文件和安全的配置示例。
- `README.md`：架构概览、安装、启动、种子数据、成功演示、失败演示、测试命令和已知限制。
- `docs/PRD.md`：需求优先级、状态流转、范围、验收映射和澄清决策。
- `docs/PLAN.md`：里程碑、模块边界、数据流、风险和提交计划。
- 自动化测试：至少覆盖 Prompt 不可变版本、任务状态、路由选择、失败重试和防重复资产。
- `docs/TEST_EVIDENCE.md`：命令、结果、验收标准映射，以及成功与失败路径的脱敏证据。
- `docs/AI_COLLABORATION.md`：AI 参与点、本人核验、采纳和拒绝的关键建议；不要粘贴私人会话全文。
- `docs/RETROSPECTIVE.md`、阶段 Issue、PR 和可解释的提交历史。

## 公开可测试验收标准

| ID | Given / 前置条件 | When / 操作 | Then / 可观察结果 | 验证方式 |
|---|---|---|---|---|
| AC-01 | 本地系统为空 | 填写有效 Brief 并保存 | 系统返回唯一 Brief 标识，重新打开后字段完整一致 | 自动化测试 + UI/API 复现 |
| AC-02 | 已有一个 Brief 和 Prompt v1 | 修改 Prompt 并保存 | 产生 v2，v1 内容不变，版本列表包含变更摘要 | 自动化测试 |
| AC-03 | 两个 Mock Provider 可用，路由条件已写明 | 分别提交满足两种条件的任务 | 两个任务选择不同 Provider，详情展示选择原因 | 自动化测试 + 运行证据 |
| AC-04 | 已提交正常任务 | 轮询或刷新任务详情 | 可观察 `queued → running → succeeded`，且只产生一个资产 | 集成测试 |
| AC-05 | 使用文档约定的失败输入 | 生成失败后执行重试 | 原尝试保留失败码；新尝试可成功；最终没有重复资产 | 自动化测试 + 失败证据 |
| AC-06 | 已有成功资产 | 打开资产详情 | 能追溯到 Brief、确切 Prompt 版本、Provider、任务和参数摘要 | UI/API 复现 |
| AC-07 | Brief 缺少必填项或包含超长字段 | 提交 Brief | 请求被拒绝并定位具体字段，服务不产生半成品数据 | 自动化测试 |
| AC-08 | 全新本地环境且无任何模型凭证 | 按 README 启动并运行测试 | 主路径、失败路径和自动化测试均可复现，不访问付费外部服务 | 人工复现 + 命令证据 |

## 技术讲解与追问准备

请准备在不依赖 AI 代答的情况下讲清：Brief 如何变成 Prompt；为什么版本不可变；任务状态机和失败重试如何避免重复资产；Provider 路由与业务逻辑如何解耦；哪些内容由 AI 建议、你如何核验。

验收会任选一个关键提交追问，并可能给出一项临时新增需求。你需要先澄清、评估影响、创建新分支，实现后补充回归证据，而不是现场无条件照做。

## 安全与合规

- 只能使用合成 Brief、原创占位素材或明确授权素材。
- 不得提交真实客户内容、未授权图片、雇主代码、生产日志、个人信息或商业秘密。
- 不得提交、分享或中转 Codex/模型账号、会话、Token、API Key、Cookie 或私钥。
- 不得把 Mock 输出描述成真实模型效果，也不得承诺生成内容一定合规或可商用。
- 本活动用于项目实践和能力反馈，不承诺就业、录用、薪资或面试结果。