Prompt file imported from zhaowendao2005/Prisim-PaperLib---ProjectFolder (
.windsurf/workflows/make-a-detail-plan.md). Copyright stays with the author.
AI 设计任务输出规范
适用场景：架构设计、技术方案、系统规划等需要分离"设计"与"实施"的任务
核心原则
1. 职责分离
- 高级 AI（策划者）：输出技术设计方案，定义"做什么"和"如何做"
- 低级 AI/实施者（执行者）：根据设计方案编写完整代码实现
2. 零自由发挥空间
设计方案必须精确到不给实施者任何理解偏差的空间，但又不陷入完整代码实现。
3. 高信息密度
每个字都应承载关键决策信息，严禁冗余描述、示例性的完整代码、或模糊的"建议性"表述。
强制输出结构
📋 第一部分：设计概览（必需）
【目标】：用一句话说明本次设计要解决的核心问题
【范围】：明确哪些在范围内，哪些不在范围内
【技术栈决策】：列出关键技术选型及选择理由（一行一个）
【架构模式】：采用的架构模式（如 MVC/MVVM/微服务/事件驱动等）
【核心约束】：技术约束、性能要求、兼容性要求（具体数值）
示例（正确）：
【目标】：实现小说搜索刮取模块的高级批处理功能
【范围】：在范围内：批量URL处理、进度追踪、错误重试；不在范围内：单URL刮取逻辑（已有）
【技术栈决策】：
- 队列管理：使用 Promise.allSettled（原因：需要容错的并发控制）
- 状态管理：Pinia store（原因：需要跨组件共享进度）
- 持久化：IndexedDB（原因：大量中间结果需本地缓存）
【架构模式】：生产者-消费者模式（主线程生产任务，Worker 消费）
【核心约束】：
- 并发数：可配置 1-10，默认 3
- 单任务超时：30s
- 内存占用：<200MB（处理 1000 条 URL 时）
反例（错误，过于模糊）：
目标：做一个批处理功能
技术栈：用 Vue 和一些工具库
要求：尽量快，不要出错
🏗️ 第二部分：模块划分与职责（必需）
格式：
模块树（用树形结构表示）：
<模块名>（职责：一句话）
├─ <子模块A>（职责：...）
│ ├─ 输入：<精确的数据结构名>
│ ├─ 输出：<精确的数据结构名>
│ └─ 关键逻辑：<核心算法/流程的伪代码或关键步骤>
└─ <子模块B>（职责：...）
├─ 依赖：<依赖哪些其他模块>
└─ 错误处理：<如何处理失败情况>
示例（正确）：
批处理管理器（职责：协调批量任务的生命周期）
├─ 任务队列管理器（职责：维护待处理/进行中/已完成的任务队列）
│ ├─ 输入：Array<{ url: string, priority: number }>
│ ├─ 输出：TaskQueue { pending, running, completed, failed }
│ └─ 关键逻辑：
│ 1. 按 priority 降序排序 pending 队列
│ 2. 从 pending 取任务填充 running（最多 concurrency 个）
│ 3. 任务完成后移至 completed/failed，回到步骤2
│
├─ 进度追踪器（职责：计算并广播实时进度）
│ ├─ 输入：订阅 TaskQueue 的状态变化事件
│ ├─ 输出：Progress { total, completed, failed, percentage, estimatedTime }
│ └─ 关键逻辑：
│ percentage = (completed + failed) / total * 100
│ estimatedTime = (total - completed - failed) * avgTimePerTask
│
└─ 错误重试控制器（职责：根据策略重试失败任务）
├─ 依赖：任务队列管理器
├─ 输入：失败任务 + 重试策略（maxRetries, backoff）
└─ 错误处理：
- 如果 retryCount < maxRetries：延迟 backoff^retryCount 秒后重新入队
- 否则：标记为永久失败，记录到 failedTasks
关键点：
- 必须明确输入输出的数据结构（用 TypeScript 风格描述）
- 必须说明关键逻辑，但用伪代码/流程步骤，而非完整实现
- 必须定义错误处理策略，不留模糊
🔌 第三部分：关键接口定义（必需）
格式：
// 仅提供类型签名 + JSDoc 注释，不提供实现
/**
* <接口用途的一句话描述>
* @注意事项 <关键约束/副作用/性能考量>
*/
interface/type/class 名称 {
属性: 类型 // <用途说明>
方法(参数: 类型): 返回类型 // <行为说明>
}示例（正确）：
/**
* 批处理任务配置
* @注意事项 concurrency 超过 10 会导致浏览器卡顿，需在 UI 层限制
*/
interface BatchTaskConfig {
urls: string[] // 待处理的 URL 列表，去重后传入
concurrency: number // 并发数，范围 1-10
retryStrategy: RetryStrategy // 重试策略，见 RetryStrategy 定义
onProgress: (progress: Progress) => void // 进度回调，每 500ms 触发一次
onComplete: (results: TaskResult[]) => void // 完成回调，包含成功和失败
}
/**
* 批处理管理器核心类
* @注意事项 单例模式，全局仅一个实例，通过 getInstance() 获取
*/
class BatchProcessor {
/** 启动批处理，返回可取消的 Promise */
start(config: BatchTaskConfig): CancellablePromise<BatchResult>
/** 暂停当前批处理（已运行的任务会完成） */
pause(): void
/** 恢复暂停的批处理 */
resume(): void
/** 取消批处理，清理所有资源 */
cancel(): void
/** 获取当前状态快照 */
getSnapshot(): BatchSnapshot
}禁止：
- ❌ 提供完整的方法实现
- ❌ 提供示例代码（除非是演示关键算法）
- ❌ 使用模糊类型（如
any,object），必须精确定义
📊 第四部分：数据流与状态机（必需）
格式：
数据流向：
[起点] --(数据描述)--> [处理节点] --(数据描述)--> [终点]
状态机（如果有）：
初始状态 -> [事件/条件] -> 目标状态
示例（正确）：
数据流向：
[用户输入 URLs]
--(原始字符串数组)-->
[URL 验证器]
--(ValidatedURL[])-->
[任务队列管理器]
--(Task[])-->
[并发执行器]
--(Promise<TaskResult>[])-->
[结果聚合器]
--(BatchResult)-->
[UI 展示层/持久化层]
批处理状态机：
IDLE（空闲）
-> [调用 start()] -> RUNNING（运行中）
RUNNING（运行中）
-> [调用 pause()] -> PAUSED（暂停）
-> [所有任务完成] -> COMPLETED（已完成）
-> [调用 cancel()] -> CANCELLED（已取消）
PAUSED（暂停）
-> [调用 resume()] -> RUNNING（运行中）
-> [调用 cancel()] -> CANCELLED（已取消）
COMPLETED/CANCELLED（终态）
-> [调用 start()] -> RUNNING（重新开始）
⚠️ 第五部分：关键决策点与实施注意事项（必需）
格式：
决策点 N：<问题描述>
选择：<采用的方案>
理由：<为什么这样选>
实施要点：
- <具体做法 1>
- <具体做法 2>
反模式：<明确禁止的做法>
示例（正确）：
决策点 1：并发控制如何实现？
选择：使用信号量模式（Semaphore）而非简单的 Promise.all
理由：需要动态控制并发数，且支持暂停/恢复
实施要点：
- 维护一个 runningCount 变量，范围 [0, concurrency]
- 每次启动任务前检查 runningCount < concurrency
- 使用 async/await + while 循环实现队列消费
- 暂停时设置 isPaused 标志，消费循环检查此标志
反模式：
❌ 不要用 Promise.all（无法动态控制）
❌ 不要用 setInterval 轮询（性能差）
决策点 2：失败任务如何重试？
选择：指数退避 + 最大重试次数
理由：避免瞬时错误导致任务失败，同时防止无限重试
实施要点：
- 初始延迟 1s，每次重试翻倍（1s, 2s, 4s, 8s...）
- maxRetries 默认 3，可配置
- 使用 setTimeout + Promise 实现延迟
- 重试时需重新获取新的 scraper 实例（避免状态污染）
反模式：
❌ 不要立即重试（可能是服务端限流）
❌ 不要无限重试（浪费资源）
🧪 第六部分：验收标准（必需）
格式：
功能验收：
✓ <具体的可验证行为 1>
✓ <具体的可验证行为 2>
性能验收：
✓ <具体的性能指标 + 测试条件>
边界条件验收：
✓ <异常情况的预期行为>
示例（正确）：
功能验收：
✓ 输入 100 个 URL，concurrency=5，所有任务完成后 completed + failed = 100
✓ 运行中调用 pause()，当前运行的任务会完成，新任务不启动
✓ 暂停后调用 resume()，队列从上次位置继续消费
✓ 失败任务重试 3 次后仍失败，最终标记为永久失败
性能验收：
✓ 处理 1000 个 URL（concurrency=3）时，内存占用 < 200MB（Chrome DevTools 测量）
✓ 进度回调触发频率 = 500ms ± 50ms（10 次测量的平均值）
✓ 单任务处理时间 < 5s（mock 数据测试）
边界条件验收：
✓ 输入空数组 []，立即触发 onComplete([])
✓ 输入包含重复 URL，自动去重后处理
✓ 所有任务失败（网络断开），onComplete 返回全部失败结果，不抛异常
✓ 运行中刷新页面，任务中断，不会有僵尸进程
代码片段使用规范
✅ 允许的代码片段类型
-
类型定义（TypeScript interface/type）：完整提供
-
关键算法伪代码：简化的逻辑表达，如：
// 伪代码：信号量控制并发 while (queue.hasPending() && !isPaused) { if (runningCount < concurrency) { task = queue.dequeue() runningCount++ executeTask(task).finally(() => runningCount--) } else { await waitForSlot() // 等待有空闲槽位 } } -
关键数据结构示例：
// 示例：任务队列的内部结构 { pending: [{ id, url, priority, retryCount }, ...], running: Map<id, Promise>, completed: [{ id, result, duration }, ...], failed: [{ id, error, finalRetryCount }, ...] } -
配置对象示例：
// 示例：默认配置 const DEFAULT_CONFIG = { concurrency: 3, timeout: 30000, retryStrategy: { maxRetries: 3, backoff: 'exponential' } }
❌ 禁止的代码片段类型
- 完整的函数实现（超过 10 行的具体逻辑）
- UI 组件的模板代码（除非是演示关键的响应式绑定）
- 详细的错误处理代码（只需说明策略，不要写 try-catch 块）
- 导入语句、初始化代码（这些是实施细节）
输出检查清单
在输出设计方案前，高级 AI 必须自查：
- 是否包含了六个必需部分？
- 所有接口的输入输出类型是否精确定义？
- 关键决策点是否给出了明确的实施要点和反模式？
- 是否存在模糊的"建议性"表述（如"可以考虑"、"尽量"）？
- 代码片段是否仅限于类型定义、伪代码、配置示例？
- 验收标准是否可量化、可验证？
- 总字数是否控制在合理范围（通常 1500-3000 字）？
反面案例警示
❌ 错误示例 1：过于详细（变成了代码实现）
// 错误：这是完整实现，不是设计
class BatchProcessor {
async start(config: BatchTaskConfig) {
this.config = config
this.queue = new TaskQueue(config.urls)
while (this.queue.hasPending()) {
if (this.runningCount < config.concurrency) {
const task = this.queue.dequeue()
this.executeTask(task)
.then(result => this.handleSuccess(result))
.catch(error => this.handleError(error))
// ... 30 行具体代码
}
}
}
}正确做法：只给接口签名 + 关键逻辑的伪代码步骤。
❌ 错误示例 2：过于模糊（实施者无法执行）
需要做一个批处理功能，支持并发和重试。
建议使用队列模式，可以考虑用 Promise 或 async/await。
错误处理方面尽量做好，性能尽量优化。
正确做法：明确技术选型、数据结构、算法步骤、性能指标。
❌ 错误示例 3：信息密度低（大量废话）
批处理是一个非常重要的功能，在现代 Web 应用中广泛使用。
我们需要仔细设计这个模块，确保它具有良好的扩展性和可维护性。
首先，我们来看一下什么是批处理...（500 字背景介绍）
正确做法：直接进入技术要点，每句话都承载决策信息。
总结
这个规则的本质目标：
- 让高级 AI 输出的是"建筑设计图"，而不是"砖块"
- 让实施者只需翻译成代码，而不需要做架构决策
- 通过高信息密度，降低高级 AI 的 token 消耗
- 通过精确约束，避免实施阶段的理解偏差
验证标准： 一个合格的设计方案，应该让一个初级开发者（或低级 AI）能够：
- 不需要问任何澄清性问题
- 严格按照设计实现后，通过所有验收标准
- 实现过程中不需要做任何架构级的决策
