# Real Solution Plan

> 当用户使用「给出方案、实现方案、解决方案、怎么实现、如何做、方案设计、技术方案、plan、solution plan」等词触发。产出详细的真实实现方案。要求基于真实项目环境和先验分析结论，结合网络检索的真实方法论和工程实践产出可执行方案。无先验分析时必须检索真实案例参考。不接受臆测、独立视角分析或无证据方案。

- Skill: `ruosong320/real-solution-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ruosong320/real-solution-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruosong320/real-solution-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Ruosong320 (https://skillmd.com/u/ruosong320)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ruosong320/real-solution-plan

---


# Real Solution Plan

产出详细的、可执行的真实实现方案，基于真实项目环境、先验分析结论和网络检索的真实方法论。

## 核心原则

1. **真实性优先**：方案必须基于真实的技术栈、真实的方法论、真实的工程实践，不接受纯理论或臆测方案。
2. **证据驱动**：每个技术选型、每个实现细节都必须有依据（先验分析结论、网络检索结果、项目现有实现）。依据里引用的文件与行号必须真实存在于当前项目——**本 skill 示例代码块中出现的路径、行号全是虚构的格式演示，照抄进真实方案等于编造依据**；写不出真实行号就只写文件路径，或标「估」。
3. **可执行性**：方案必须足够详细，能直接指导实现，包含具体的代码结构、数据流、API 调用方式。
4. **环境适配**：方案必须适配当前项目的技术栈、依赖版本、代码风格、架构模式。

## 工作流程

### 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. 技术选型与对比

对每个关键技术决策：

1. 列出 2-3 个候选方案
2. 对比各方案的优劣（性能、复杂度、维护性、生态）
3. 结合项目实际情况推荐一个
4. 标注依据来源（先验分析 / 项目现有 / 检索来源 URL）

候选方案之间对比不出实质差异 → 取「方案写不下去时的兜底」表中以 *2-3 个候选方案对比不出实质差异* 开头的那一行处理；用户已有明确选型与检索结果冲突 → 取同表中以 *用户已有明确技术选型，与检索到的最佳实践冲突* 开头的那一行处理。

> 以下示例中的 `requirements.txt:12`、`cache/manager.py:45-67` 等路径与行号是**虚构的**，只演示格式。真实方案里每一处依据都要指向当前项目真实存在的文件与行号。

示例格式：
```markdown
#### 技术选型：数据持久化方案

**候选方案：**
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 核心实现步骤

按执行顺序列出，每步包含：
- 步骤目标
- 具体操作（伪代码或关键代码片段）
- 预期输出
- 依据来源

示例：
```markdown
**步骤 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 供后续复用