CS-RAG 架构总规范

CS-RAG 项目专用架构总规范。已无损合并 architecture-cognition 与 architecture-design 的规则内容，可在原 skill 删除后独立使用。

---

⚠️ 核心强制要求

统一三层架构约束

• 前端层 → 业务层 → 基础设施层（单向依赖）
• 禁止反向依赖：基础设施层不能依赖业务层或前端层
• 禁止跨层访问：前端层不能直接访问基础设施层
• 基础设施层不得夹带业务逻辑

认知与设计的组合治理顺序

1. 先执行架构认知检查：层级位置、组件关系、数据流影响
2. 再执行架构设计检查：接口契约、依赖注入、可插拔设计
3. 最后执行合规复核：跨层、反向依赖、循环依赖、兼容性

升级给用户决策的场景

• 涉及跨层依赖修改
• 涉及核心组件接口变更（尤其破坏性变更）
• 涉及数据流向/主路径改变
• 涉及全局策略、性能、资源消耗或数据一致性风险

---

AI Agent 行为要求

阶段 A：架构认知（原 architecture-cognition 全量迁入）

修改代码前必须回答：

1. 位置识别：属于哪一层？影响哪些组件？有跨层依赖风险？
2. 影响范围：影响哪些数据流？有组件依赖此接口？需更新测试？
3. 架构约束：是否违反三层架构？是否引入循环依赖？

创建新组件时必须明确：

1. 职责定位：属于哪一层？单一职责是什么？与现有组件关系？
2. 接口设计：需要抽象基类/Protocol？需要工厂模式？
3. 依赖管理：依赖哪些组件？是否可依赖注入？是否违反依赖方向？

快速参考（项目上下文）：

层	核心组件	职责
前端层	frontend/main.py	用户交互、UI 展示
业务层	RAGService, QueryEngine	业务逻辑、流程编排
基础设施层	IndexManager, Embedding, LLM	技术实现、无业务逻辑

阶段 B：架构设计（原 architecture-design 全量迁入）

设计变更时检查项：

• 标注影响到的层级与上下游模块
• 确认无循环依赖
• 确认无跨层访问

接口设计要求：

• 以抽象基类或 Protocol 定义契约
• 新接口默认向后兼容
• 使用构造函数依赖注入，禁止静态单例

可插拔设计要求：

• 使用工厂或注册表模式注册新实现
• 所有可切换组件通过配置项启用

新模块规划时：

• 每个模块/类仅负责单一领域
• 命名遵循 src/<layer>/<role>/module.py 结构

阶段 C：合规复核

• 复核是否引入跨层访问或反向依赖
• 复核接口变更是否具备兼容策略
• 复核是否出现循环依赖

---

判断标准

• 是否完成“认知 + 设计 + 复核”三阶段检查
• 是否保持三层依赖方向正确且无循环依赖
• 是否保留接口兼容性与实现可替换性

---

无损合并声明

• 本 skill 已承载两套原始规则的内容级迁移，不是仅链接跳转。
• 原始 SKILL.md 文本已复制到：
  • references/architecture-cognition-skill.md
  • references/architecture-design-skill.md
• 原始 references 文本已全量复制到本 skill 的 references/。
• 详细映射见 references/lossless-merge-routing.md。

删除源 skill 就绪说明

• 删除 architecture-cognition 与 architecture-design 后，本 skill 仍可独立运行。
• 删除前后仅路径变化，不会丢失规则内容。

---

参考资料

• references/lossless-merge-routing.md - 无损合并路由与原文映射
• references/architecture-cognition-skill.md - 原 architecture-cognition 全文
• references/architecture-cognition-system-overview.md - 原认知参考：系统定位
• references/architecture-cognition-three-layer-architecture.md - 原认知参考：三层架构
• references/architecture-cognition-component-map.md - 原认知参考：组件地图
• references/architecture-cognition-data-flow.md - 原认知参考：数据流
• references/architecture-design-skill.md - 原 architecture-design 全文
• references/architecture-design-layer-guidelines.md - 原设计参考：分层指南
• references/architecture-design-module-planning.md - 原设计参考：模块规划
• references/architecture-design-interface-design.md - 原设计参考：接口设计