AI 软件项目的核心矛盾在于：模型能力快速变化，而工程结构需要长期稳定。本规范的目标是建立一套模块自治、接口契约、渐进增强的项目结构标准，让团队能够在不牵动全局的前提下替换、升级或新增任何单个模块。

适用范围

本规范适用于所有包含 AI 能力的软件项目，涵盖模型推理服务、数据处理管道、应用业务逻辑及对外接口。无论项目采用单体还是微服务架构，模块层面的设计约定一致。

核心设计哲学

模块化不是把代码拆到不同目录，而是让系统在结构上具备独立替换的能力。以下六条原则贯穿从设计到实现的每个决策。

分层依赖，单向流转

系统按职责分层，上层依赖下层，同层之间通过接口通信。依赖方向自上而下单向流转，MUST NOT 出现下层反向引用上层的循环依赖。分层的意义在于：修改下层实现时，上层接口不变即无需改动。

flowchart TD
    subgraph 接口层
        GW["API Gateway"]
        UI["UI / BFF"]
    end
    subgraph 应用层
        BIZ["业务编排"]
        AUTH["认证鉴权"]
    end
    subgraph AI 能力层
        MODEL["模型管理"]
        PROMPT["Prompt 管理"]
        INFER["推理服务"]
        EVAL["评估体系"]
    end
    subgraph 数据层
        PIPE["数据管道"]
        STORE["存储服务"]
    end
    subgraph 基础设施层
        CFG["配置中心"]
        LOG["日志 / 追踪"]
        MQ["消息队列"]
    end
    GW --> UI
    UI --> BIZ
    BIZ --> AUTH
    BIZ --> INFER
    INFER --> MODEL
    INFER --> PROMPT
    INFER --> EVAL
    BIZ --> PIPE
    PIPE --> STORE
    MODEL --> STORE
    BIZ -.-> CFG
    INFER -.-> LOG
    BIZ -.-> MQ

高内聚，功能闭环

一个模块内的所有代码围绕同一个业务能力组织。判断标准：如果移除这个模块，系统失去的是一个完整功能而非零散片段。模块内部的数据结构、工具函数、配置项不暴露给外部。

接口先行，实现随后

新增或修改模块时，先产出接口定义文件（OpenAPI / Protobuf / TypeScript interface / Protocol），评审通过后才开始编写实现。接口是模块间的合约，实现是合约的履行——合约变更的成本远低于实现重构，因此接口设计值得花更多时间打磨。

单一职责，粒度适中

一个模块只承担一个明确的业务职责。判断粒度是否合适的方法：用一句话描述模块的功能，如果需要”和”连接两个不同动词，说明粒度过大需拆分；如果描述词过于泛化（如”工具模块”），说明职责不清需重新界定。

无状态优先，状态外置

模块的逻辑层不持有运行时状态。会话状态、缓存、任务队列等持久化数据外置到数据层或基础设施层。无状态模块可以水平扩展、独立部署、随时重启，这些特性在 AI 推理服务的高并发场景下尤为关键。

失败隔离，优雅降级

单个模块的故障不阻断整个系统。模块间的调用 SHOULD 设置超时、熔断和降级策略。AI 模型推理服务宕机时，应用层 SHOULD 能回退到规则引擎或缓存结果，而非直接报错。

模块是本规范的核心调度单位。一个标准的模块包含四个组成部分：接口契约（对外声明的能力和数据格式）、实现逻辑（内部如何履行契约）、测试套件（验证实现符合契约）、运行清单（依赖、配置、版本信息）。

模块分类

按依赖层级和职责类型，模块分为四类：

依赖规则

模块间的依赖遵循以下约束：

• 核心模块 MAY 依赖服务模块和数据模块
• 服务模块 MAY 依赖数据模块和工具模块
• 数据模块 MAY 依赖工具模块
• 工具模块 MUST NOT 依赖任何非工具模块
• 同层模块之间 MAY 通信，但 MUST 通过接口契约，不直接引用内部实现
• 任何模块 MUST NOT 形成循环依赖（A → B → A）

flowchart TD
    CORE["核心模块"] --> SVC["服务模块"]
    SVC --> DATA["数据模块"]
    DATA --> UTIL["工具模块"]
    CORE --> DATA
    SVC --> UTIL
    CORE --> UTIL
    UTIL -.->|"禁止依赖"| CORE
    DATA -.->|"禁止反向"| SVC
    SVC -.->|"禁止反向"| CORE

接口契约三要素

每个对外暴露的接口 MUST 包含三部分声明：

1. 数据契约 —— 输入输出的数据结构，使用语言无关的 schema 描述（OpenAPI / Protobuf / JSON Schema），字段含义、类型约束、必选/可选均有明确定义。
2. 行为契约 —— 接口的前置条件（调用方需满足什么前提）、后置条件（调用完成后系统处于什么状态）、以及异常场景（输入不合法、依赖不可用时返回什么）。
3. 版本契约 —— 接口的语义版本号，以及当前版本的状态（草案 / 稳定 / 废弃中）。

模块注册与发现

项目维护一份模块清单文件（modules.yaml），记录每个模块的名称、版本、路径、接口文件位置、依赖声明和当前状态。新模块加入或旧模块废弃时，同步更新此文件。这份清单是整个系统的”地图”，CI 管道 SHOULD 校验清单与实际代码的一致性。

统一的目录结构让任何开发者在任何模块中都能快速定位代码。以下约定适用于使用 TypeScript / Python 的 AI 软件项目，其他语言遵循等价原则。

顶层目录

# 标准项目顶层结构
project-root/
├── modules/              # 所有业务模块
│   ├── inference/       # 推理服务模块
│   ├── model-manager/   # 模型管理模块
│   ├── prompt-engine/   # Prompt 管理模块
│   ├── data-pipeline/   # 数据管道模块
│   └── ...
├── packages/            # 可复用的工具包
│   ├── types/           # 共享类型定义
│   ├── utils/           # 通用工具函数
│   └── config/          # 配置管理工具
├── gateway/             # API 网关 / 入口层
├── infra/               # 基础设施配置
│   ├── docker/          # 容器化定义
│   ├── k8s/             # 编排配置
│   └── terraform/       # 基础设施即代码
├── tools/               # 开发工具与脚本
│   ├── cli/             # 项目专用 CLI
│   └── scripts/         # 运维脚本
├── docs/                # 项目文档
├── modules.yaml         # 模块清单（依赖地图）
├── CONTRACT.md          # 模块间接口契约汇总
└── CHANGELOG.md         # 变更日志

模块内目录

每个模块内部遵循统一结构，让跨模块协作时无需重新适应：

# 单个模块的标准内部结构
modules/inference/
├── interface/         # 接口契约（对外暴露）
│   ├── openapi.yaml    # REST API 定义
│   └── types.ts        # TypeScript 类型
├── src/               # 实现代码
│   ├── handler/        # 请求处理
│   ├── service/        # 核心逻辑
│   └── adapter/       # 外部依赖适配器
├── tests/             # 测试套件
│   ├── unit/          # 单元测试
│   ├── integration/   # 集成测试
│   └── fixtures/      # 测试数据
├── config/            # 模块级配置
├── README.md          # 模块说明
├── module.yaml        # 模块元信息
└── CHANGELOG.md       # 模块变更日志

命名约定

AI 能力层是本规范与普通软件项目规范的主要差异点。这一层包含四个核心模块，它们的协作方式决定了 AI 功能的质量和迭代速度。

模型管理模块

模型管理模块负责模型的注册、版本控制、加载与卸载。每个模型在注册时 MUST 记录以下元信息：

• 模型标识符（name + version，如 gpt-classifier/v2.1.0）
• 模型来源（训练任务 ID / 外部下载地址 / 基座模型 + 微调配置）
• 输入输出 schema（字段名、类型、维度、取值范围）
• 资源需求（GPU 型号、显存、CPU、内存）
• 性能基线（准确率、延迟 P99、吞吐量，及评估数据集标识）
• 生命周期状态（draft → staging → production → deprecated → retired）

模型加载采用延迟加载 + 预热机制：模块启动时仅加载配置元信息，实际模型权重在首次请求或定时预热任务触发时加载到内存。卸载时 MUST 等待正在进行的推理请求完成，然后释放资源。

Prompt 管理模块

Prompt 是 AI 系统中的”源代码”，需要与代码同级的管理待遇。Prompt 管理模块 MUST 提供以下能力：

推理服务模块

推理服务模块是 AI 能力层的对外窗口，接收请求、调度模型、返回结果。它的设计核心是将模型选择逻辑与推理执行逻辑分离。

# 推理请求标准结构
{
  "request_id": "uuid",
  "model": "gpt-classifier/v2.1.0",      # 指定模型，或使用 "auto" 让路由器选择
  "inputs": {
    "text": "待推理内容",
    "context": { ... }              # 可选上下文
  },
  "params": {                     # 推理参数，有默认值
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  },
  "metadata": {
    "caller": "service-x",
    "trace_id": "..."
  }
}

推理服务 SHOULD 支持三种调用模式：同步请求（低延迟场景）、异步批处理（高吞吐场景）、流式返回（生成式任务）。三种模式共用同一套模型加载和 Prompt 渲染逻辑，仅在外层处理调度差异。

评估体系模块

评估体系模块是 AI 能力层的质量保障。它独立于推理服务运行，定期对模型和 Prompt 的输出质量进行回归测试。评估 MUST 覆盖三个维度：

1. 质量指标 —— 准确率、F1、BLEU、ROUGE 等领域相关指标，按评估数据集分组统计。
2. 性能指标 —— 延迟分布（P50 / P95 / P99）、吞吐量、资源占用。
3. 安全指标 —— 有害内容检测率、PII 泄露检测、越狱攻击防御成功率。

评估结果 SHOULD 接入可视化看板，历史趋势可追溯。当指标低于设定阈值时自动触发告警，阻止相关模型版本进入 production 状态。

RAG 模块（如适用）

检索增强生成（RAG）能力拆分为三个子模块独立管理：索引模块负责文档解析、分块、向量化、索引写入；检索模块负责查询改写、向量检索、混合排序；重排模块负责对检索结果做二次排序和过滤。三个子模块各有独立版本，可分别迭代而不影响其他环节。

数据层管理 AI 系统中所有数据的生命周期：采集、清洗、标注、存储、版本控制。数据的正确性和可追溯性直接决定模型效果，因此数据层规范的核心是不可变 + 可版本化 + 可审计。

数据管道模块

数据管道模块以 DAG（有向无环图）方式编排数据处理流程。每个处理节点是一个独立的函数或服务，接收输入数据集，输出处理后的数据集。管道设计遵循以下规则：

• 每个节点 MUST 记录输入数据的哈希值和输出数据的哈希值，用于追溯数据血缘
• 节点的处理逻辑 MUST 是确定性的——同一输入永远产出同一输出，不依赖随机状态
• 引入随机性的节点（如数据增强）MUST 显式传入随机种子，种子与输出一起记录
• 管道执行失败时 MAY 从失败节点重试，不重新执行已成功的前置节点

数据版本管理

每次数据集变更（新增、修改、删除记录） MUST 产生一个新的数据版本。版本记录包含变更时间、变更人、变更类型、变更前后的数据量。数据版本与模型版本关联：模型的评估结果 MUST 标注使用的数据版本号，确保结果可复现。

数据集的版本控制不同于代码的 Git 版本控制。数据量大、二进制格式多、变更频繁，SHOULD 使用专门的数据版本工具（如 DVC / LakeFS）而非直接存入 Git。

存储策略

数据安全与隐私

含 PII（个人身份信息）的数据 MUST 在进入数据管道前完成脱敏处理。脱敏规则在配置文件中声明，不硬编码在处理逻辑中。数据访问 MUST 经过认证授权，访问日志记录操作人、时间、数据范围。模型训练使用的数据 MUST 可追溯到数据来源和授权状态。

接口是模块间的合约。一份好的接口定义让消费方无需阅读实现代码即可正确调用，让提供方在不破坏消费方的前提下重构实现。

API 设计原则

• 资源导向 —— URL 表达资源而非动作，动词由 HTTP method 表达：GET /models/:id 而非 GET /getModel?id=
• 幂等性 —— GET 请求 MUST 幂等，PUT 请求 SHOULD 幂等，POST 请求不要求幂等但 SHOULD 返回幂等键
• 分页 —— 列表接口 MUST 支持分页，默认使用游标分页（cursor-based）而非偏移分页（offset-based），在数据量增长后性能更稳定
• 字段筛选 —— 列表接口 SHOULD 支持 fields 参数，让调用方按需获取字段，减少不必要的数据传输
• 批量操作 —— 批量接口 SHOULD 接受数组输入，返回逐条结果和状态，而非整体成功或失败

错误处理标准

所有接口 MUST 使用统一的错误响应格式：

# 错误响应标准结构
{
  "error": {
    "code": "MODEL_NOT_FOUND",          # 机器可读的错误码
    "message": "Model 'gpt-x/v3' not found",  # 人类可读的描述
    "target": "model",                # 出错的字段或资源
    "details": {                      # 可选的补充信息
      "available_models": ["gpt-x/v2", "gpt-y/v1"]
    },
    "request_id": "uuid",           # 用于追踪的请求 ID
    "trace_id": "..."               # 分布式追踪 ID
  }
}

HTTP 状态码使用约定：

接口版本策略

接口在 URL 路径中标注主版本号：/api/v1/models/:id。主版本号变更意味着存在不向后兼容的 breaking change，消费方需要适配。次版本号和修订号在响应头或响应体中返回，不体现在 URL 中。

接口废弃流程：标记为 deprecated 后 MUST 保持至少 2 个次版本周期的可用期，响应头中返回 Deprecation 和 Sunset 字段告知消费方迁移时间。废弃期结束后移除接口，移除操作记录在 CHANGELOG 中。

模块化架构的最终价值体现在迭代效率上。当系统能够在不牵动全局的情况下替换或升级单个模块，迭代速度就从”系统级”降低到了”模块级”。本章定义模块从创建到退役的全流程。

模块生命周期

每个模块经历五个阶段，阶段转换需满足该阶段的准入条件和退出条件：

stateDiagram-v2
    [*] --> Draft : 提案通过
    Draft --> Dev : 接口定义评审通过
    Dev --> Stable : 测试覆盖率达标 + 文档完成
    Stable --> Maintenance : 进入维护期（不新增功能）
    Maintenance --> Deprecated : 标记废弃
    Deprecated --> Retired : 迁移完成 + 废弃期满
    Retired --> [*]
    Stable --> Refactor : 技术债触发重构
    Refactor --> Stable : 重构完成

语义版本控制

每个模块遵循 SemVer（Semantic Versioning）规范，版本号格式为 MAJOR.MINOR.PATCH：

• MAJOR —— 接口存在不向后兼容的变更（删除接口、修改参数类型、修改返回结构）。MAJOR 变更 MUST 产出迁移文档。
• MINOR —— 新增功能或接口，向后兼容。消费方不升级也能继续工作，升级后可使用新能力。
• PATCH —— Bug 修复或性能优化，不改变接口契约。

版本号记录在模块的 module.yaml 中，模块清单 modules.yaml 同步更新。CI 管道 SHOULD 校验版本号变更与实际 diff 的一致性——如果接口发生了 breaking change但版本号只升了 MINOR，CI SHOULD 发出警告。

迭代工作流

一个典型的功能迭代按以下步骤推进：

flowchart LR
    A["需求分析"] --> B["模块影响评估"]
    B --> C["接口变更评审"]
    C --> D["开发实现"]
    D --> E["测试验证"]
    E --> F["集成测试"]
    F --> G["灰度发布"]
    G --> H["全量发布"]
    G --> I["回滚"]
    I --> D

模块影响评估是迭代流程中容易被跳过但最关键的环节。评估的产出是一份影响范围清单：本次变更涉及哪些模块、哪些接口、哪些数据格式，下游消费方有哪些，需要什么适配。影响范围超出单个模块的变更 MUST 升级为跨模块评审。

技术债务管理

技术债不是需要消灭的敌人，而是需要管理的资源。每个模块维护一份技术债清单，记录已知的设计缺陷、待优化的实现、硬编码的临时方案。技术债条目 SHOULD 包含：

• 描述：什么问题，为什么当初这样处理
• 影响：不处理的后果（性能、可维护性、安全性）
• 优先级：按影响范围和严重程度排序
• 偿还方案：预期的修复方向和预估工作量

每个迭代周期 SHOULD 预留 15-20% 的容量用于偿还高优先级技术债。技术债清单在每季度的架构评审中重新审视和排序。

工程实践规范覆盖代码到部署之间的全部环节。这些约定不是风格偏好，而是保证模块化架构在团队协作中不退化的约束条件。

代码风格

项目使用统一的代码格式化工具（Biome / Prettier + ESLint for TS, Ruff + Black for Python），配置文件提交到仓库根目录。格式化在提交前自动执行，CI 管道校验格式一致性，不符合的 PR MUST NOT 合并。

代码注释遵循”只解释为什么，不解释是什么”的原则。函数和类型的命名 SHOULD 足以表达意图，注释用于补充命名无法传达的上下文：业务约束、外部依赖的限制、历史决策的原因。自动生成的文档（如 JSDoc / docstring） SHOULD 覆盖所有对外暴露的接口和公共类型。

测试策略

测试分为三层，各有不同的关注点和覆盖率要求：

AI 相关模块的测试 MUST 额外包含模型回归测试：使用固定的评估数据集，对比当前版本与基线版本的输出。模型输出的回归测试不要求逐字匹配，而是评估指标在容差范围内——延迟变化不超过基线的 10%，质量指标波动不超过 2 个百分点。

CI/CD 管道

CI 管道在每次代码推送时执行以下检查，按顺序串行：

1. Lint & Format —— 代码风格和格式校验，失败即阻断
2. Unit Tests —— 单元测试，失败即阻断
3. Build —— 编译和构建，验证类型正确性
4. Integration Tests —— 集成测试，验证模块间接口兼容
5. Security Scan —— 依赖漏洞扫描和敏感信息检测

CD 管道在 CI 全部通过后执行，部署策略取决于模块类型：核心模块使用灰度发布（先 5% → 25% → 50% → 100%），工具模块可直接全量发布。每个部署批次 MUST 设置自动回滚触发条件：错误率超过阈值或延迟超过基线 150%。

环境管理

项目维护四套环境，各有明确用途和隔离要求：

• local —— 开发者本地，用于开发和单元测试。使用 mock 依赖，不连接真实模型服务。
• staging —— 预发布环境，使用脱敏后的真实数据，连接 staging 版本的模型和依赖服务。集成测试在此执行。
• production —— 生产环境，连接真实的模型和数据。变更 MUST 经过灰度流程。
• benchmark —— 性能基准环境，配置与 production 一致但隔离流量。用于模型评估和性能回归测试。

环境之间的配置差异通过环境变量注入，MUST NOT 在代码中通过 if env === 'production' 分支处理。配置管理使用专门的配置中心或环境变量文件，敏感信息（API Key、数据库密码）MUST 使用密钥管理服务，不提交到代码仓库。

模块化架构的长期健康取决于团队协作纪律。本章定义代码从编写到发布到生产的过程中，团队需要共同遵守的流程约定。

分支策略

项目采用 Trunk-Based Development，所有人向主分支（main）提交代码，不维护长期的功能分支。功能开发在短期分支（存活不超过 3 天）上进行，完成后合并回 main。发布从 main 的标记版本切出 release 分支，release 分支仅用于修复发布阻塞的 bug。

代码审查

所有代码变更 MUST 经过至少 1 人的审查后合并。涉及接口变更的 PR MUST 由模块负责人或架构师审查。PR 审查关注以下维度：

• 接口合规 —— 变更是否符合接口契约，版本号是否正确
• 模块边界 —— 是否引入了越层依赖或循环依赖
• 测试覆盖 —— 新增代码是否有对应的测试覆盖
• 文档同步 —— 接口变更是否同步更新了文档和契约文件

PR 描述 MUST 包含变更摘要、影响范围、测试方法和关联的 issue/任务。大型 PR（超过 500 行变更）SHOULD 拆分为多个小 PR 依次提交，降低审查难度和合并风险。

发布流程

发布流程标准化为五个步骤：

1. 发布准备 —— 冻结新功能合并，创建 release 分支，运行完整 CI 套件
2. 灰度部署 —— 部署到 production 的 5% 流量，监控错误率和延迟指标 30 分钟
3. 扩大灰度 —— 指标正常则扩大到 25% → 50% → 100%，每阶段观察 30 分钟
4. 发布确认 —— 全量部署后观察 24 小时，确认无异常后标记发布完成
5. 发布归档 —— 更新 CHANGELOG，归档 release 分支，记录发布摘要

灰度期间的监控指标和回滚阈值：

变更日志

每个模块维护独立的 CHANGELOG.md，项目根目录维护汇总的 CHANGELOG.md。变更日志遵循 Keep a Changelog 格式，按版本倒序排列：

# CHANGELOG.md

## [Unreleased]

### Added
- 推理服务支持流式返回（modules/inference）

### Changed
- 模型管理接口返回增加 `lifecycle_status` 字段（modules/model-manager）

### Fixed
- Prompt 模板渲染时变量类型校验失效（modules/prompt-engine）

### Deprecated
- `GET /api/v1/models` 的 `verbose` 参数，使用 `fields` 替代

## [1.2.0] - 2026-08-15
### Added
- RAG 重排模块（modules/reranker）
- 数据管道支持增量更新模式（modules/data-pipeline）

事故响应

生产事故按严重程度分级响应。P0（服务不可用）要求 15 分钟内响应、1 小时内恢复或回滚；P1（核心功能降级）要求 1 小时内响应、4 小时内恢复。事故处理完成后 MUST 在 3 个工作日内产出事故复盘文档，包含时间线、根因分析、影响范围和改进措施。改进措施录入相关模块的技术债清单，在下一次迭代中安排处理。