Add feature design

添加功能设计

核心目标

在现有代码库中添加功能时，先理解既有架构和边界，在当前项目的 docs/ 下输出计划文档，等待用户确认后再改代码。实现阶段必须以可扩展代码为目标，通过面向对象设计实现新功能：把一个大功能拆成一组职责清晰的类，并把这些类放到能表达抽象层级、模块边界和依赖方向的目录结构中，通过对象协作和编排完成完整流程。优先复用项目已有模式；当既有过程式写法会承载新功能复杂度时，必须提炼类、接口、依赖注入点、状态模型或新的目录/子目录边界。

可扩展设计约束

新增功能代码必须满足这些可扩展设计要求；除非用户明确二次覆盖，否则不要降级为过程式实现：

• 必须用第一性原理分析功能本质：先识别业务对象、职责、约束、状态、协作关系和不变量，再决定类模型。
• 必须把完整功能拆成多个职责单一的类；每个类只拥有一个清晰变化原因。
• 必须把文件目录结构也当作设计抽象：类拆分后要同步设计文件归属，按领域、应用编排、基础设施、适配器、状态、策略、工厂、组合根或项目既有分层放入相应目录、子目录，必要时放到其他既有模块，而不是默认堆在同一个文件夹。
• 必须强调子目录的抽象含义：父目录承载主抽象、主流程或主业务能力；当主抽象依赖一组可替换接口、策略族、状态族、供应商实现或适配器时，用子目录承载该变化点的接口和具体实现。例如 context_compression/ 放上下文压缩主流程和协作对象，context_compression/feedback_memory/ 放上下文压缩依赖的反馈记忆策略接口与实现。
• 必须让目录层级表达依赖方向和变化边界：核心领域规则不依赖框架/I/O 细节，编排层依赖抽象，基础设施和适配层在边界实现抽象。
• 必须通过编排类完成完整功能；主流程只负责协调对象，不承载大量规则、状态判断或外部访问细节。
• 必须让高层业务依赖抽象，不直接依赖具体实现；通过构造函数、容器、模块装配或项目已有机制注入依赖。
• 必须把领域规则、状态转换、外部访问、数据适配、流程编排分离到不同对象或层级。
• 禁止为了方便把新抽象全部放进同一个目录、单个 services/、单个 utils/、单个 handlers/ 或单个 models/ 下；只有当项目既有架构明确如此且功能很小，才可沿用，并在计划中说明取舍。
• 禁止把新功能主要写成一个大函数、一个大组件、一个大 service 方法、散落的 if/else 堆叠或全局脚本。
• 禁止为了“少改代码”牺牲对象边界；如果既有代码不支持对象协作，要做服务于本功能的最小重构。

图示要求

所有输出中的图示必须使用 Mermaid 绘制，使用 Markdown fenced code block：

```mermaid
flowchart TD
  A["开始"] --> B["处理"]
```

• 类图、流程图、状态图、时序图、模块依赖图、数据流图都必须使用 Mermaid。
• 需要表达类模型时，优先使用 classDiagram；需要表达对象协作或调用顺序时，优先使用 sequenceDiagram；需要表达业务流程、依赖关系或数据流时，优先使用 flowchart；需要表达状态转换时，优先使用 stateDiagram-v2。
• Mermaid 节点文本包含中文、括号、标点或空格时，用引号包裹。
• 不要输出 ASCII 图、字符框图或用纯文本箭头拼出的图。

输入要求

开始实现前，收集并确认这些信息；如果仓库中能读到，就自行推断，不要为显而易见的信息停下来询问：

• 功能目标：用户可感知的行为、入口、输出结果。
• 变化点：当前需求中可能继续扩展的规则、策略、供应商、状态或流程。
• 影响范围：需要修改的模块、接口、数据模型、配置、测试和文档。
• 约束条件：兼容性、性能、安全、错误处理、迁移成本、已有编码规范。
• 验收方式：可运行的测试、手动验证路径、关键边界用例。

执行流程

1. 阅读目标目录的仓库规则和相关代码，识别当前分层、依赖方向、命名风格、测试方式和已有扩展点。
2. 描述功能的业务流程、数据流和状态流；把稳定流程与可变规则分开。
3. 从第一性原理推导对象模型：列出核心业务对象、对象职责、对象之间的消息或调用关系、状态归属和不变量。
4. 选择最小面向对象设计：优先使用既有抽象；需要新抽象时，用接口、协议、基类、策略对象、服务类、工厂、编排器或组合根表达变化点。
5. 设计目录结构和文件归属：先读取项目既有分层，再决定新类放在现有目录、子目录、新建目录或其他模块中；目录命名必须使用项目语言和领域词汇表达抽象，不用临时杂物目录承接复杂度。
6. 设计子目录职责：当一个抽象依赖另一个可变抽象时，优先在父目录下创建以被依赖抽象命名的子目录，集中放置该接口、策略实现、工厂或适配器；在计划中说明父目录和子目录分别表达什么变化边界。
7. 在当前项目的 docs/ 下创建计划文档；如果存在 docs/AGENTS.md，先遵循其中的分类、命名和维护规则。
8. 写完计划文档后停止，不直接修改业务代码；向用户给出计划文档路径并等待确认。
9. 用户确认后再进入实现：让高层业务依赖抽象，不直接依赖具体实现；通过构造函数、容器、模块装配或项目已有机制注入依赖。
10. 保持关注点分离：编排、领域规则、外部访问、状态转换、展示或传输适配分别落在合适位置和目录层级。
11. 对复杂状态优先建模：状态少时使用清晰的枚举和转换对象；状态多或转换受约束时考虑状态机对象；无状态计算可以作为类的私有方法或独立策略对象。
12. 实现时减少默认值、魔法值和隐式兜底；缺少必需输入时显式失败，让错误暴露在边界处。
13. 控制分支、循环和跳转复杂度；用提前返回、策略映射、对象组合或状态转换表让主流程可读。
14. 增加或调整测试，覆盖成功路径、关键失败路径、边界值、状态转换、对象协作、目录边界和依赖替换点。
15. 如果新增或调整日志，按 references/logging-guidelines.md 落实结构化日志、链路标识、级别边界、敏感信息保护和异常日志位置。
16. 验证并复盘代码是否仍符合项目风格；只做服务于本功能的重构。

计划文档要求

计划文档必须先于代码变更创建，位置必须在当前项目的 docs/ 下。文件名使用能表达功能主题的短横线命名，例如 docs/features/add-xxx.md；具体目录优先服从项目已有文档规则。

计划文档至少包含：

• 背景与目标：用户要解决的问题和可感知结果。
• 现状分析：相关模块、既有流程、可复用能力和限制。
• 第一性原理分析：业务对象、核心职责、不变量、状态归属、协作关系和变化点。
• 类模型设计：新增或复用的类、接口、抽象基类、策略对象、编排器、工厂、组合根和依赖注入方式。
• 目录结构设计：新增或调整的目录、子目录、跨模块文件归属、每个目录承载的抽象职责、依赖方向，以及为什么不能把类放在同一个文件夹；特别说明父目录承载的主抽象，以及子目录承载的接口族、策略族、状态族、供应商实现或适配器。
• 状态与数据流：关键状态、转换规则、输入输出和错误边界。
• Mermaid 图示：按需包含类图、流程图、状态图、时序图、模块依赖图或数据流图；不得使用 ASCII 图。
• 日志设计：如功能涉及日志，说明业务事件、JSON 字段、trace_id 传递、日志级别、敏感信息保护和异常日志记录位置。
• 实施步骤：按可验证的小步骤拆分。
• 测试与验收：自动化测试、手动验证、边界用例。
• 风险与回滚：兼容性、迁移、性能、安全或协作风险。

如果用户明确要求“直接实现”或“不写计划”，也要先说明该 skill 的约束是先写 docs/ 计划文档；只有用户再次明确覆盖该约束时，才可以跳过。

参考资料

按需读取，不要一次性加载全部参考文件：

• 需要判断抽象、目录结构、模块分层、依赖倒置、IoC、关注点分离、状态建模、默认值和魔法值时，读取 references/design-principles.md。
• 需要识别代码臭味或决定是否顺手重构时，读取 references/code-smells-and-refactoring.md。
• 需要新增、调整或评审日志时，读取 references/logging-guidelines.md。

输出要求

完成后向用户说明：

• 计划阶段：计划文档的路径、核心设计选择、等待确认的事项。
• 实现了哪些用户可感知行为。
• 第一性原理如何推导出对象模型。
• 新增或复用了哪些关键类、接口和编排对象，以及为什么需要它们。
• 新增或调整了哪些目录/子目录/模块归属，目录结构如何表达抽象层级、职责边界和依赖方向。
• 如输出图示，确认使用 Mermaid 而不是 ASCII。
• 如新增或调整日志，说明如何满足结构化 JSON、请求链路、级别边界、业务事件、敏感信息保护和异常日志规约。
• 运行了哪些验证；如果没有运行，说明原因。
• 剩余风险或后续扩展点，只有确实存在时才提。