cs-rag-architecture-guideline
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCS-RAG 架构总规范
CS-RAG Architecture General Specification
CS-RAG 项目专用架构总规范。已无损合并与architecture-cognition的规则内容，可在原 skill 删除后独立使用。architecture-design
General Architecture Specification for CS-RAG Project. The rules fromandarchitecture-cognitionhave been merged losslessly, and it can be used independently after deleting the original skills.architecture-design
⚠️ 核心强制要求
⚠️ Core Mandatory Requirements
统一三层架构约束
Unified Three-Layer Architecture Constraints
- 前端层 → 业务层 → 基础设施层（单向依赖）
- 禁止反向依赖：基础设施层不能依赖业务层或前端层
- 禁止跨层访问：前端层不能直接访问基础设施层
- 基础设施层不得夹带业务逻辑
- Frontend Layer → Business Layer → Infrastructure Layer (one-way dependency)
- Prohibit reverse dependencies: Infrastructure Layer cannot depend on Business Layer or Frontend Layer
- Prohibit cross-layer access: Frontend Layer cannot directly access Infrastructure Layer
- Infrastructure Layer must not contain business logic
认知与设计的组合治理顺序
Combined Governance Sequence of Cognition and Design
- 先执行架构认知检查：层级位置、组件关系、数据流影响
- 再执行架构设计检查：接口契约、依赖注入、可插拔设计
- 最后执行合规复核：跨层、反向依赖、循环依赖、兼容性
- First perform architecture cognition inspection: layer position, component relationships, data flow impact
- Then perform architecture design inspection: interface contracts, dependency injection, pluggable design
- Finally perform compliance review: cross-layer, reverse dependencies, circular dependencies, compatibility
升级给用户决策的场景
Scenarios Requiring User Decision for Upgrade
- 涉及跨层依赖修改
- 涉及核心组件接口变更（尤其破坏性变更）
- 涉及数据流向/主路径改变
- 涉及全局策略、性能、资源消耗或数据一致性风险
- Involving cross-layer dependency modifications
- Involving core component interface changes (especially breaking changes)
- Involving data flow/main path changes
- Involving global strategy, performance, resource consumption or data consistency risks
AI Agent 行为要求
AI Agent Behavior Requirements
阶段 A：架构认知（原 architecture-cognition
全量迁入）
architecture-cognitionPhase A: Architecture Cognition (full migration from original architecture-cognition
)
architecture-cognition修改代码前必须回答：
- 位置识别：属于哪一层？影响哪些组件？有跨层依赖风险？
- 影响范围：影响哪些数据流？有组件依赖此接口？需更新测试？
- 架构约束：是否违反三层架构？是否引入循环依赖？
创建新组件时必须明确：
- 职责定位：属于哪一层？单一职责是什么？与现有组件关系？
- 接口设计：需要抽象基类/Protocol？需要工厂模式？
- 依赖管理：依赖哪些组件？是否可依赖注入？是否违反依赖方向？
快速参考（项目上下文）：
| 层 | 核心组件 | 职责 |
|---|---|---|
| 前端层 | | 用户交互、UI 展示 |
| 业务层 | | 业务逻辑、流程编排 |
| 基础设施层 | | 技术实现、无业务逻辑 |
Before modifying code, you must answer:
- Position Identification: Which layer does it belong to? Which components are affected? Is there a cross-layer dependency risk?
- Impact Scope: Which data flows are affected? Do any components depend on this interface? Do tests need to be updated?
- Architecture Constraints: Does it violate the three-layer architecture? Does it introduce circular dependencies?
When creating new components, you must clarify:
- Responsibility Positioning: Which layer does it belong to? What is the single responsibility? What is the relationship with existing components?
- Interface Design: Is an abstract base class/Protocol required? Is the factory pattern required?
- Dependency Management: Which components does it depend on? Can dependency injection be used? Does it violate the dependency direction?
Quick Reference (Project Context):
| Layer | Core Components | Responsibilities |
|---|---|---|
| Frontend Layer | | User interaction, UI display |
| Business Layer | | Business logic, process orchestration |
| Infrastructure Layer | | Technical implementation, no business logic |
阶段 B：架构设计（原 architecture-design
全量迁入）
architecture-designPhase B: Architecture Design (full migration from original architecture-design
)
architecture-design设计变更时检查项：
- 标注影响到的层级与上下游模块
- 确认无循环依赖
- 确认无跨层访问
接口设计要求：
- 以抽象基类或 Protocol 定义契约
- 新接口默认向后兼容
- 使用构造函数依赖注入，禁止静态单例
可插拔设计要求：
- 使用工厂或注册表模式注册新实现
- 所有可切换组件通过配置项启用
新模块规划时：
- 每个模块/类仅负责单一领域
- 命名遵循 结构
src/<layer>/<role>/module.py
Check items during design changes:
- Mark the affected layers and upstream/downstream modules
- Confirm no circular dependencies
- Confirm no cross-layer access
Interface Design Requirements:
- Define contracts with abstract base classes or Protocol
- New interfaces are backward compatible by default
- Use constructor-based dependency injection, prohibit static singletons
Pluggable Design Requirements:
- Use factory or registry pattern to register new implementations
- All switchable components are enabled via configuration items
When planning new modules:
- Each module/class is responsible for only a single domain
- Naming follows the structure
src/<layer>/<role>/module.py
阶段 C：合规复核
Phase C: Compliance Review
- 复核是否引入跨层访问或反向依赖
- 复核接口变更是否具备兼容策略
- 复核是否出现循环依赖
- Review whether cross-layer access or reverse dependencies are introduced
- Review whether interface changes have compatibility strategies
- Review whether circular dependencies occur
判断标准
Judgment Criteria
- 是否完成“认知 + 设计 + 复核”三阶段检查
- 是否保持三层依赖方向正确且无循环依赖
- 是否保留接口兼容性与实现可替换性
- Whether the three-stage inspection of "cognition + design + review" is completed
- Whether the three-layer dependency direction is correct and no circular dependencies exist
- Whether interface compatibility and implementation replaceability are retained
无损合并声明
Lossless Merge Declaration
- 本 skill 已承载两套原始规则的内容级迁移，不是仅链接跳转。
- 原始 文本已复制到：
SKILL.mdreferences/architecture-cognition-skill.mdreferences/architecture-design-skill.md
- 原始 references 文本已全量复制到本 skill 的 。
references/ - 详细映射见 。
references/lossless-merge-routing.md
- This skill has carried out content-level migration of two sets of original rules, not just link jumps.
- The original text has been copied to:
SKILL.mdreferences/architecture-cognition-skill.mdreferences/architecture-design-skill.md
- The original reference texts have been fully copied to the directory of this skill.
references/ - For detailed mapping, see .
references/lossless-merge-routing.md
删除源 skill 就绪说明
Readiness Instructions for Deleting Source Skills
- 删除 与
architecture-cognition后，本 skill 仍可独立运行。architecture-design - 删除前后仅路径变化，不会丢失规则内容。
- After deleting and
architecture-cognition, this skill can still run independently.architecture-design - Only the path changes before and after deletion, and no rule content will be lost.
参考资料
Reference Materials
- - 无损合并路由与原文映射
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
- - Lossless merge routing and original text mapping
references/lossless-merge-routing.md - - Full text of original
references/architecture-cognition-skill.mdarchitecture-cognition - - Original cognition reference: system positioning
references/architecture-cognition-system-overview.md - - Original cognition reference: three-layer architecture
references/architecture-cognition-three-layer-architecture.md - - Original cognition reference: component map
references/architecture-cognition-component-map.md - - Original cognition reference: data flow
references/architecture-cognition-data-flow.md - - Full text of original
references/architecture-design-skill.mdarchitecture-design - - Original design reference: layered guidelines
references/architecture-design-layer-guidelines.md - - Original design reference: module planning
references/architecture-design-module-planning.md - - Original design reference: interface design
references/architecture-design-interface-design.md