Skip to content

module-system.md

Latest commit

 

History

History
382 lines (280 loc) · 9.96 KB

module-system.md

File metadata and controls

382 lines (280 loc) · 9.96 KB
Raw

AIOX 模块系统架构

🌐 EN | PT | ES | ZH-CN

Synkra AIOX v4.2 模块化架构完整指南。

版本: 2.1.0 上次更新: 2025-12-01

概览

为什么要模块化架构？

v4.2 模块化架构解决了 v2.0 扁平结构的几个挑战：

挑战 v2.0 问题 v4.2 解决方案
发现 200+ 文件混乱在目录中 按责任组织
维护 所有权不清楚 模块边界定义所有权
依赖 隐含的、循环的 显式的、单向的
可扩展性 总是加载所有文件 按模块延迟加载
测试 仅完整系统测试 模块级隔离

设计原则

  1. 单一职责 - 每个模块有明确的目的
  2. 显式依赖 - 模块声明所需内容
  3. 松耦合 - 一个模块的变化不会传播
  4. 高内聚 - 相关功能保持在一起
  5. 延迟加载 - 仅加载必要内容

模块结构

Synkra AIOX 将 .aiox-core/ 目录组织为四个主要模块：

.aiox-core/
├── core/              # 框架基础
├── development/       # 开发制品
├── product/           # 用户导向模板
└── infrastructure/    # 系统配置

模块图

graph TB
    subgraph "AIOX v4 框架"
        CLI[CLI / 工具]

        subgraph "产品模块"
            Templates[模板]
            Checklists[检查表]
            Data[PM 数据]
        end

        subgraph "开发模块"
            Agents[代理]
            Tasks[任务]
            Workflows[工作流]
            Scripts[开发脚本]
        end

        subgraph "核心模块"
            Registry[服务注册表]
            Config[配置系统]
            Elicit[询问]
            Session[会话管理]
            QG[质量门槛]
            MCP[MCP 系统]
        end

        subgraph "基础设施模块"
            InfraScripts[基础设施脚本]
            Tools[工具配置]
            PM[PM 适配器]
        end
    end

    CLI --> Agents
    CLI --> Registry
    Agents --> Tasks
    Agents --> Templates
    Tasks --> Workflows
    Development --> Core
    Product --> Core
    Infrastructure --> Core

    style Core fill:#e1f5fe
    style Development fill:#e8f5e9
    style Product fill:#fff3e0
    style Infrastructure fill:#f3e5f5
Loading

核心模块

路径: .aiox-core/core/ 目的: 框架基础 - 配置、会话、询问和本质运行时组件。

内容

目录 内容 描述
config/ config-cache.js、config-loader.js 带 TTL 缓存的配置管理
data/ aiox-kb.md、workflow-patterns.yaml 框架知识库
docs/ 内部文档 组件指南、故障排除
elicitation/ elicitation-engine.js、session-manager.js 交互式提示系统
session/ context-detector.js、context-loader.js 会话上下文管理
utils/ output-formatter.js、yaml-validator.js 常用实用程序
registry/ service-registry.json、registry-loader.js 服务发现系统
quality-gates/ quality-gate-manager.js、层配置 3 层质量门槛系统
mcp/ global-config-manager.js、os-detector.js 全局 MCP 配置
manifest/ manifest-generator.js、manifest-validator.js 项目清单系统
migration/ migration-config.yaml、module-mapping.yaml 迁移配置

主要 API

// 配置
const { loadAgentConfig, globalConfigCache } = require('./.aiox-core/core');

// 会话
const { ContextDetector, SessionContextLoader } = require('./.aiox-core/core');

// 询问
const { ElicitationEngine, ElicitationSessionManager } = require('./.aiox-core/core');

// 注册表
const { getRegistry, loadRegistry } = require('./.aiox-core/core/registry/registry-loader');

// 质量门槛
const QualityGateManager = require('./.aiox-core/core/quality-gates/quality-gate-manager');

依赖项

  • 外部: js-yaml、fs-extra
  • 内部: 无（基础模块）

开发模块

路径: .aiox-core/development/ 目的: 代理相关资产 - 代理定义、任务、工作流和开发脚本。

内容

目录 内容 描述
agents/ 11 个代理定义 dev.md、qa.md、architect.md 等
agent-teams/ 5 个团队配置 预定义代理组
tasks/ 115+ 任务定义 可执行任务工作流
workflows/ 7 个工作流定义 多步开发工作流
scripts/ 24 个脚本 代理支持实用程序

代理

代理 ID 责任
AIOX 主代理 aiox-master 框架编排
开发者 dev 代码实现
QA qa 质量保证
架构师 architect 技术架构
产品经理 po 产品待办
产品经理 pm 产品策略
Scrum 主管 sm 过程协调
分析师 analyst 业务分析
数据工程师 data-engineer 数据工程
DevOps devops CI/CD 和操作
UX 专家 ux-design-expert 用户体验

代理团队

团队 代理 用例
team-all 全部 11 个代理 完整开发团队
team-fullstack dev、qa、architect、devops 全栈项目
team-ide-minimal dev、qa 最小 IDE 设置
team-no-ui dev、architect、devops、data-engineer 后端/API 项目
team-qa-focused qa、dev、architect 质量关注工作

依赖项

  • 内部: core/（配置、会话、询问）

产品模块

路径: .aiox-core/product/ 目的: PM/PO 资产 - 模板、检查表和文档生成参考数据。

内容

目录 内容 描述
templates/ 52+ 模板 PRD、故事、架构、IDE 规则
checklists/ 11 个检查表 质量验证检查表
data/ 6 个数据文件 PM 知识库和参考

主要模板

模板 目的
story-tmpl.yaml v2.0 故事模板
prd-tmpl.yaml 产品需求文档
architecture-tmpl.yaml 架构文档
qa-gate-tmpl.yaml 质量门槛模板
ide-rules/ 9 个 IDE 特定规则文件

检查表

  • architect-checklist.md - 架构审查
  • pm-checklist.md - PM 验证
  • po-master-checklist.md - 主 PO 验证
  • story-dod-checklist.md - 故事完成定义
  • pre-push-checklist.md - 推送前验证
  • release-checklist.md - 发布验证

依赖项

  • 内部: core/（模板引擎、验证器）
  • 外部: 无（静态资产）

基础设施模块

路径: .aiox-core/infrastructure/ 目的: 系统配置 - 脚本、工具和外部集成。

内容

目录 内容 描述
scripts/ 55+ 脚本 基础设施实用程序
tools/ 工具配置 CLI、MCP、本地工具配置
integrations/ PM 适配器 ClickUp、Jira、GitHub 适配器
tests/ 模块测试 基础设施验证

主要脚本

脚本 目的
git-wrapper.js Git 操作包装器
backup-manager.js 备份/恢复系统
template-engine.js 模板处理
security-checker.js 安全验证
performance-analyzer.js 性能分析

工具配置

tools/
├── cli/           # CLI 工具配置 (gh, railway, supabase)
├── mcp/           # MCP 服务器配置
└── local/         # 本地工具配置

依赖项

  • 内部: core/（配置、实用程序）
  • 外部: 多个工具 API

模块边界

依赖规则

graph LR
    CLI[CLI/工具] --> D[开发]
    CLI --> P[产品]
    CLI --> I[基础设施]

    D --> C[核心]
    P --> C
    I --> C

    style C fill:#e1f5fe
    style D fill:#e8f5e9
    style P fill:#fff3e0
    style I fill:#f3e5f5
Loading

规则:

  1. core/ 没有内部依赖项
  2. development/、product/、infrastructure/ 仅依赖于 core/
  3. 禁止循环依赖
  4. CLI/工具可以访问任何模块

模块间通信

模块通过以下方式通信：

  1. 服务注册表 - 发现可用的工作者和服务
  2. 配置系统 - 共享设置和首选项
  3. 事件系统 - 发布/订阅实现松耦合
  4. 文件系统 - 共享数据目录

模块边界检查表

添加新功能时：

  • 属于现有模块？
  • 引入新依赖项？
  • 维持单向依赖流？
  • 与模块目的相聚合？
  • 可以独立测试？

文件组织

命名约定

类型 约定 示例
脚本 kebab-case.js config-loader.js
代理 agent-id.md dev.md、qa.md
任务 agent-prefix-task-name.md dev-develop-story.md
模板 name-tmpl.yaml story-tmpl.yaml
检查表 name-checklist.md pre-push-checklist.md

添加新文件

文件类型 位置 模块
代理定义 development/agents/ 开发
任务定义 development/tasks/ 开发
工作流 development/workflows/ 开发
模板 product/templates/ 产品
检查表 product/checklists/ 产品
实用脚本 infrastructure/scripts/ 基础设施
配置加载器 core/config/ 核心
注册表 core/registry/ 核心

从 v2.0 迁移

对于从扁平 v2.0 结构升级的项目：

# 预演显示变化
aiox migrate --dry-run

# 执行迁移
aiox migrate --from=2.0 --to=2.1

# 验证迁移
aiox migrate --validate

详见 迁移指南 了解详细说明。

相关文档

Synkra AIOX v4 模块系统架构