# 方案实施原则

> **本文约定：AI（及协作者）在执行用户需求时，应如何理解、选型与落地。**  
> 适用于本仓库 / 个人 Wiki 及相关开发协作。  
> 不限于某一功能（如端口、布局、渲染等）；**所有需求默认遵循本文。**

---

## 1. 核心原则（按优先级）

### 1.1 需求第一

- 先准确理解用户要什么、成功标准是什么、明确不做什么。  
- **不得**在未说明的情况下，用「行业标准」「框架习惯」「更优雅」等理由，擅自削弱、替换或取消用户已确认的需求。  
- 仅当需求存在明显矛盾、安全风险、不可维护或成本与收益严重失衡时，才提出调整建议；**默认先按需求落地。**

### 1.2 同需求下，现成方案优先

针对**用户已经提出的同一需求**，实现时应：

1. 先检索：**官方文档 / 成熟开源库 / 主流脚手架与社区常见做法**；  
2. **尽量直接使用或薄封装**现成能力；  
3. **避免从零造轮子**（重复实现已有成熟方案已覆盖的能力）。

「自研」在这里的正确含义是：

- **自己定义产品规则与组装方式**；  
- 底层尽量用开源与成熟工具；  
- **不是**一切从零手写。

### 1.3 行业标准 = 参考怎么做，不是否定要做什么

| 应该用行业标准的地方 | 不应该用行业标准干的事 |
|----------------------|------------------------|
| 命名、目录、命令习惯（在不损害需求时对齐） | 用「别人不这么做」否决合理需求 |
| 选型灵感：别人怎么实现同类需求 | 把需求削成「只剩标准能力」 |
| 文档与工程结构便于维护 | 未说明就静默改需求行为 |

有成熟方案能满足需求 → **用成熟方案**。  
成熟方案盖不全、但需求仍成立 → **允许最小必要自写**，并说明现成方案差在哪里。

### 1.4 需求不合理时才反馈

反馈的条件应是需求本身有问题，而不是「实现稍微麻烦」或「和某框架默认不一致」。

---

## 2. AI 执行用户需求的默认工作流

对**任意**用户需求（功能、改 bug、重构、文档、配置等），默认按序执行：

```text
1. 确认需求
   - 做什么 / 不做什么
   - 成功标准（如何算完成）
   - 边界与约束（环境、兼容、安全等）

2. 检索成熟方案
   - 官方能力是否已支持
   - 有无主流库 / 工具 / 公认模式
   - 同需求下常见实现是什么

3. 选型落地
   - 能直接用 → 直接用
   - 差一点 → 配置或薄封装现成方案
   - 现成无法满足 → 最小自写，并简要说明原因

4. 实现与验证
   - 按选定方案实现
   - 按成功标准自检（能跑通、能复现用户场景）

5. 说明（必要时）
   - 用了什么现成方案
   - 若有自写，为何现成不够
   - 如何使用 / 如何验证

6. 仅当需求本身有问题时
   - 再与用户反馈，提出可选调整
   - 不擅自用「标准答案」替换用户目标
```

---

## 3. 「自研」允许与禁止（通用）

| 鼓励 | 应避免 |
|------|--------|
| 产品规则、信息架构、交互约定 | 从零实现已有成熟库覆盖的能力（解析器、通用搜索引擎内核等），除非有明确理由 |
| 业务胶水、壳层编排、与业务强绑定的逻辑 | 为「显得独特」另起非必要框架 |
| 现成方案缺口上的**小范围**补全（需说明） | 大量重复造轮子且无收益 |
| 在开源方案上的配置、组合、文档化 | 未调研就开写 |

---

## 4. 对 AI 的明确要求（清单）

1. **先对齐需求，再谈实现与标准。**  
2. **选型前先找现成方案**；需要时说明选用了什么、为何。  
3. **禁止**未说明就用「行业标准」替换用户已确认的行为。  
4. 自写前先自问：是否已有库/官方选项？差在哪？能否薄封装？  
5. 在不损害需求的前提下，命名、目录、命令等尽量对齐常见工程习惯，便于维护。  
6. 文档与代码一致：重要约定写进仓库（如本文、`docs/`、配置注释），避免只存在于对话里。  
7. 大改动前，若存在多种成熟路线，可简要对比后推荐，但**以用户最终选择的需求为准**。

---

## 5. 反面示例与正面示例（通用，非绑定某一功能）

### 反面（错误）

- 用户要 A 行为 → AI 认为「标准只做 B」→ 只做了 B，且不说明。  
- 未检索是否有成熟库 → 直接从零实现一整套。  
- 用「更专业」「更优雅」静默改变产品行为。

### 正面（正确）

- 用户要 A → 检索到库 X / 官方选项 Y 能覆盖 → 使用 X/Y 落地 A。  
- 用户要 A → 现成方案只能覆盖 A 的一部分 → 用现成方案 + 最小补全，并说明缺口。  
- 用户要 A → A 本身有安全/逻辑问题 → **先反馈**，再等用户决定是否改需求。

---

## 6. 一句话（贴在协作约定里）

> **需求第一。**  
> **同一需求下，优先成熟、现成的方案，尽量直接用，少造轮子。**  
> **行业标准用来参考「别人怎么实现」，不是用来否定「用户要什么」。**  
> **只有需求不合理时才反馈；现成不够时再最小自写，并说明原因。**

---

## 7. 修订

| 版本 | 说明 |
|------|------|
| v1.0 | 初版（含原则与示例方向） |
| v1.1 | 明确为**通用 AI 执行用户需求**规范；不限定某一技术点 |

本文位于 `content/AI/`，作为本站可浏览的协作规范；工程侧也可在 `docs/` 引用本文链接。