Ruosong320 Real Solution Plan
产出详细的、可执行的真实实现方案，基于真实项目环境、先验分析结论和网络检索的真实方法论。
核心原则
- 真实性优先：方案必须基于真实的技术栈、真实的方法论、真实的工程实践，不接受纯理论或臆测方案。
- 证据驱动：每个技术选型、每个实现细节都必须有依据（先验分析结论、网络检索结果、项目现有实现）。依据里引用的文件与行号必须真实存在于当前项目——本 skill 示例代码块中出现的路径、行号全是虚构的格式演示，照抄进真实方案等于编造依据；写不出真实行号就只写文件路径，或标「估」。
- 可执行性：方案必须足够详细，能直接指导实现，包含具体的代码结构、数据流、API 调用方式。
- 环境适配：方案必须适配当前项目的技术栈、依赖版本、代码风格、架构模式。
工作流程
1. 理解需求与约束
明确：
- 要解决的核心问题（用户需求）
- 项目现有技术栈和架构
- 已有的先验分析结论（如果有）
- 必须满足的约束条件（性能、兼容性、安全性等）
- 验收标准
需求本身不清楚，或用户给不出验收标准 → 不得凭猜往下写，取「方案写不下去时的兜底」表中以 需求本身不清楚，或用户给不出验收标准 开头的那一行处理。
2. 收集真实依据
按优先级收集：
优先级 1：先验分析结论
- 检查是否有相关的 analyze-only 产出
- 检查项目 memory/recoder 记录
- 检查相关 issue、文档、注释中的决策记录
没有先验分析结论（无 analyze-only 产出），且方案要定选型或架构 → 取「方案写不下去时的兜底」表中以 没有先验分析结论（无 analyze-only 产出），且方案要定选型或架构 开头的那一行处理。
优先级 2：项目现有实现
- 搜索项目中类似功能的实现方式
- 读取相关模块的代码，理解现有模式
- 检查依赖清单（package.json, requirements.txt, go.mod 等）确认可用库
项目内找不到同类功能的现有实现 → 取「方案写不下去时的兜底」表中以 项目内找不到同类功能的现有实现（新项目、空仓库、无关模块） 开头的那一行处理。
优先级 3：网络检索真实方法论
- 检索目标技术栈的官方文档和最佳实践
- 检索 GitHub 上真实项目的实现案例（优先 star 数高、近期活跃的）
- 检索 Stack Overflow、技术博客中的真实工程经验
- 对比至少 2-3 个不同来源的实现方式
禁止行为：
- 不做任何检索直接凭记忆产出方案
- 只参考单一来源
- 引用过时的方法（超过 2 年且有更新替代方案）
- 臆测 API 用法或参数
检索能力不可用，或该技术栈搜不到任何真实案例 → 取「方案写不下去时的兜底」表中以 检索能力不可用，或该技术栈搜不到任何真实案例 开头的那一行处理。
3. 技术选型与对比
对每个关键技术决策：
- 列出 2-3 个候选方案
- 对比各方案的优劣（性能、复杂度、维护性、生态）
- 结合项目实际情况推荐一个
- 标注依据来源（先验分析 / 项目现有 / 检索来源 URL）
候选方案之间对比不出实质差异 → 取「方案写不下去时的兜底」表中以 2-3 个候选方案对比不出实质差异 开头的那一行处理；用户已有明确选型与检索结果冲突 → 取同表中以 用户已有明确技术选型，与检索到的最佳实践冲突 开头的那一行处理。
以下示例中的
requirements.txt:12、cache/manager.py:45-67等路径与行号是虚构的，只演示格式。真实方案里每一处依据都要指向当前项目真实存在的文件与行号。
示例格式：
#### 技术选型：数据持久化方案
**候选方案：**
1. SQLite + SQLAlchemy ORM
- 优势：轻量、零配置、事务支持
- 劣势：并发写入受限
- 依据：项目已使用 SQLAlchemy（requirements.txt:12）
2. JSON 文件 + 自定义序列化
- 优势：简单直接、易于调试
- 劣势：无查询能力、并发不安全
- 依据：现有 cache/ 目录使用此方式（cache/manager.py:45-67）
**推荐：** SQLite + SQLAlchemy ORM
**理由：** 项目已依赖 SQLAlchemy，复用现有模式成本最低，且需求涉及关系查询。
4. 产出详细实现方案
方案必须包含以下所有部分：
4.1 架构设计
- 模块划分与职责
- 数据流向图（输入 → 处理 → 输出）
- 关键接口定义（函数签名、类结构）
- 依赖关系（模块间、外部依赖）
4.2 核心实现步骤
按执行顺序列出，每步包含：
- 步骤目标
- 具体操作（伪代码或关键代码片段）
- 预期输出
- 依据来源
示例：
**步骤 2：初始化数据库连接**
目标：创建 SQLAlchemy engine 和 session factory
具体操作：
```python
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
engine = create_engine('sqlite:///data.db', echo=False)
SessionLocal = sessionmaker(bind=engine)
预期输出：可用的 session factory，供后续 CRUD 使用
依据：SQLAlchemy 官方文档 - Engine Configuration 项目现有 db/connection.py 中相同模式
#### 4.3 关键代码结构
给出主要文件的结构框架（不是完整代码，但比伪代码更具体）：
```markdown
**文件：services/data_processor.py**
```python
class DataProcessor:
def __init__(self, config: dict):
# 依据：项目统一使用 config dict 注入（见 config/loader.py）
self.config = config
self.session = SessionLocal()
def process(self, input_data: list[dict]) -> ProcessResult:
# 核心处理逻辑
# 1. 数据验证（使用 pydantic，项目已依赖）
# 2. 业务逻辑
# 3. 持久化
pass
def _validate_input(self, data: dict) -> bool:
# 依据：网络检索 - pydantic BaseModel validation pattern
pass
#### 4.4 数据结构定义
明确所有关键数据结构：
- 输入输出格式（JSON schema / TypedDict / dataclass）
- 数据库表结构（如果涉及）
- 中间数据结构
#### 4.5 错误处理与边界情况
列出：
- 可预见的异常类型
- 每种异常的处理策略
- 边界条件（空输入、超大输入、网络超时等）
- 回退方案
#### 4.6 测试验证方案
给出：
- 单元测试用例设计（至少 3 个：正常、边界、异常）
- 集成测试场景
- 手动验证步骤
- 验收标准检查清单
#### 4.7 依赖清单
列出所有新增依赖：
- 库名 + 版本号
- 用途说明
- 选择该版本的依据（兼容性、稳定性）
#### 4.8 潜在风险与缓解
识别：
- 性能瓶颈点
- 兼容性风险
- 安全风险
- 每个风险的缓解措施
### 5. 质量自检
产出方案后，必须自问：
- [ ] 每个技术选型都有明确依据吗？（先验分析 / 项目现有 / 检索来源）
- [ ] 方案中的 API、库用法是否经过验证？（读过文档或看过真实代码）
- [ ] 是否参考了至少 2 个不同来源的真实实现？
- [ ] 代码结构是否符合项目现有风格？
- [ ] 数据流是否完整清晰（输入到输出全链路）？
- [ ] 错误处理是否覆盖主要异常场景？
- [ ] 测试方案是否可执行？
- [ ] 是否有任何"我觉得"、"应该"、"可能"这类不确定表述？如果有，必须补充依据或检索验证。
未通过自检的部分必须补充依据后再输出。
**🔴 CHECKPOINT — 输出方案前逐条过上面这张自检表。任一条 ✗ 都不许静默带过：落在「方案写不下去时的兜底」表某一行上的，按那一行处理；不在表内的，按上一条补齐依据后再输出。**
**🛑 STOP — 用户确认方案之前，不得把它交给 ship-it-for-real / ship-solution 执行。未确认的方案只是提案，不是实现依据。**
## 方案写不下去时的兜底
以上流程假设检索可用、有先验依据、项目里能找到对照实现。下列情况按表处理，不得静默降级。
**本节是上述流程的例外条款：与正文规则冲突时——例如「禁止行为」清单、核心原则 1「不接受纯理论或臆测方案」、核心原则 2「证据驱动」的绝对要求、第 2 步的先验/项目内/检索三档优先级顺序——以本表为准——但仅在该表某行的一线修复与正文规则确实冲突时生效。同一情形命中多行时，取一线修复最保守的那一行——停下、询问、不写入，一律优先于继续推进。但每一处例外都必须在方案首段显式标出，不得静默降级。**
| 触发条件 | 一线修复 | 仍失败兜底 |
|---|---|---|
| 需求本身不清楚，或用户给不出验收标准 | 停下先厘清（回到 initer，或直接问用户），不带着模糊需求往下写 | 用户不回答 → 冻结「需求与约束」一节，逐条列出待确认项，其余部分标「待需求确认后重出」 |
| 检索能力不可用，或该技术栈搜不到任何真实案例 | 该处不写确定性结论：耗时标「估」，选型标「按项目现有实现与本机先验推断」，并写明检索失败 | 若关键选型普遍无来源 → 「质量自检结果」把「多源参考」判 ✗，并在方案首段写明哪些结论靠推断 |
| 没有先验分析结论（无 analyze-only 产出），且方案要定选型或架构 | 先调用 analyze-only 产出结论，再回到第 2 步 | 用户要求跳过 → 照做，但方案首段写明「无先验分析」，「依据来源」的先验分析栏标「无」 |
| 项目内找不到同类功能的现有实现（新项目、空仓库、无关模块） | 在「依据来源」写「无项目内先例」，选型主依据改为检索到的真实案例 | 检索到的案例也构不成对照 → 让用户提供参考项目或一段可对照的代码，不得凭印象编项目现状 |
| 2-3 个候选方案对比不出实质差异 | 明说它们等价，改给选择判据（维护成本 / 生态活跃度 / 团队熟悉度），并指名推荐一个 | 仍定不了 → 列为「待用户裁决项」，方案照出但标注该决策未定，不得假装已推荐 |
| 用户已有明确技术选型，与检索到的最佳实践冲突 | 以用户选型为准，在方案里列出被放弃的做法及其代价 | 冲突涉及已知的安全或兼容缺陷 → **🛑 输出前先取得用户对该风险的明示接受，并在方案首段写明** |
## 输出格式
```markdown
# 实现方案：[需求简述]
## 1. 需求与约束
- 核心问题：
- 验收标准：
- 技术约束：
- 先验分析结论：[引用/无]
## 2. 方案依据来源
- 先验分析：[文件路径 / 无]
- 项目参考：[相关文件:行号]
- 网络检索：[关键来源 URL 或总结]
## 3. 技术选型
[每个关键决策的对比与推荐，附依据]
## 4. 架构设计
- 模块划分：
- 数据流向：
- 接口定义：
## 5. 实现步骤
[按顺序，每步含目标/操作/预期/依据]
## 6. 关键代码结构
[主要文件的框架代码]
## 7. 数据结构定义
[输入/输出/中间结构]
## 8. 错误处理
[异常类型/处理策略/边界情况]
## 9. 测试验证
- 单元测试用例：
- 集成测试场景：
- 手动验证步骤：
- 验收检查清单：
## 10. 依赖清单
[库名 + 版本 + 用途 + 依据]
## 11. 风险与缓解
[风险点/影响/缓解措施]
## 12. 质量自检结果
- 依据完整性：✓/✗
- API 验证：✓/✗
- 多源参考：✓/✗
- 风格一致：✓/✗
- 数据流完整：✓/✗
- 错误处理覆盖：✓/✗
- 测试可执行：✓/✗
- 不确定表述：✓/✗
常见失败模式
- 臆测方案：未经检索直接凭印象写方案，API 用法、参数名称可能错误。
- 单源依赖：只看一篇博客或一个示例就产出方案，未交叉验证。
- 脱离项目：方案技术栈、代码风格与项目现有实现不一致。
- 细节缺失：只有高层设计，缺少可执行的代码结构和数据定义。
- 忽略边界：只考虑正常路径，未处理异常和边界情况。
- 无法验证：测试方案空泛，没有具体用例和验收步骤。
- 过时方案：引用已废弃的 API 或过时的最佳实践。
遇到以上情况，必须补充检索、读取项目代码或先验分析后重新产出。
与其他 Skill 的协作
- 前置：initer - 命中兜底表首行 需求本身不清楚，或用户给不出验收标准 时按那一行处理，本 skill 不自行降级
- 前置：analyze-only - 没有先验分析结论且方案要定选型或架构时，先调用 analyze-only 产出分析结论，再基于结论产出方案
- 后续：ship-it-for-real - 方案产出并用户确认后，调用 ship-it-for-real 执行实现与验证
- 记录：recoder - 重要方案和实现路径记录到 recoder 供后续复用