Synkra AIOX：通用AI代理框架与自进化开发系统

Synkra AIOX：通用AI代理框架 🚀

将AI从代码生成工具进化为完整的开发团队伙伴

Synkra AIOX是一个革命性的通用AI代理框架，基于“代理驱动的敏捷开发”理念，提供了一个多智能体协作环境。它不仅适用于软件开发，更能通过创建专用AI代理（智能体），将AI能力注入任何领域——从创意写作、商业策略到个人健康管理。

AIOX的核心创新在于其两阶段开发流程：由专业代理进行深度规划，再由执行代理基于完整上下文进行精确实现。这一方法彻底解决了AI开发中常见的“上下文丢失”和“规划不一致”两大痛点。

✨ 功能特性

🧠 多智能体协作生态

• 12+专业预置代理：包括@pm(产品经理)、@architect(架构师)、@dev(开发者)、@qa(质量保证)、@devops(运维)等，每个代理拥有明确的职责边界和权威
• 自定义代理创建：通过引导式交互(elicitation)轻松创建新代理，扩展团队能力
• 代理权威隔离：严格限定每个代理的权限（如仅@devops可执行git push），保障项目安全

📜 代理驱动的两阶段开发

• 规划阶段：@analyst、@pm、@architect等代理协作，通过人机交互，生成高质量的PRD、架构决策记录(ADR)等文档
• 执行阶段：@sm将规划转化为包含完整上下文的“故事”（Story），@dev代理在一个隔离的、包含完整上下文的执行环境中完成编码、测试，从根本上避免上下文丢失

🔍 智能代码洞察 (Code Intelligence)

• 多源数据提供者：内建RegistryProvider（基于本地实体注册表）和可选的CodeGraphProvider（基于MCP，提供AST级分析）
• 跨代理共享：@dev、@qa、@pm等代理均可通过DevHelper、QaHelper等工具获取代码影响范围分析、重复功能检测、测试覆盖率评估，实现数据驱动的决策
• 渐进式能力：无外部API时回退至关键字搜索，有OpenAI Key时可启用语义搜索

🔒 CLI优先 & 可观测性

• CLI是第一公民：所有核心功能均通过aiox命令实现，UI（仪表盘）仅作观察，绝不控制
• 事件驱动仪表盘：内置DashboardEmitter，将代理激活、命令执行、故事状态等高阶事件推送给监控服务器，实现实时透明化开发

🛡️ 内置质量与安全门禁 (Quality Gates)

• 三层质量门禁：aiox qa run命令自动执行三层检查——Layer1（代码风格、类型、单元测试）、Layer2（自动化PR审查模拟）、Layer3（人工审批清单）
• 指标收集：aiox metrics命令记录每次门禁运行结果，跟踪项目质量趋势
• 环境健康检查：aiox doctor命令一键诊断项目环境，并支持--fix自动修复常见问题（如缺失的规则文件、代理内存文件等）

📦 安装指南

系统要求

• Node.js >= 20.0.0
• npm 或 yarn
• Git
• GitHub CLI (gh) (可选，用于团队协作)

分步安装

1. 在全新项目中安装

# 创建一个新项目并初始化AIOX
npx aiox-core@latest init my-awesome-project
cd my-awesome-project

2. 在现有项目中安装

# 进入你的项目目录
cd your-existing-project
# 运行AIOX安装向导
npx aiox-core@latest install

安装向导会自动检测项目环境，创建必要的目录结构（.aiox-core/、.claude/），并生成核心配置文件。

3. 验证安装

# 查看系统信息
aiox info

# 运行健康检查
aiox doctor

🚀 使用说明

激活你的第一个AI代理

AIOX的设计核心是与AI代理（如Claude、Gemini）进行对话。激活代理的方式取决于你使用的IDE或CLI：

# 在 Claude Code 中
/architect          # 激活架构师代理

# 在 Gemini CLI 中
/aiox-menu          # 打开AIOX菜单，然后选择 /aiox-<agent-name>

# 在 Codex CLI 中
/skills             # 打开技能菜单，选择 aiox-<agent-id>

成功激活后，代理会发送一条问候语并列出其主要命令。

核心工作流：创建并完成一个故事 (Story)

AIOX的“故事驱动开发”流程：

1. 与@pm或@analyst对话：描述你希望实现的功能。

   @pm 我们想在登录页面增加“记住我”功能。
   

   @pm代理会引导你细化需求，并生成一个产品需求文档(PRD)。

2. 与@architect协作：当PRD就绪后，激活@architect进行技术设计。

   @architect 请为“记住我”功能设计技术方案。
   

   架构师会分析现有代码（通过代码智能），输出架构决策记录(ADR)和详细的技术任务。

3. @sm生成故事：@sm（Scrum Master）代理会自动将规划和设计分解为一个个可执行的“故事”（Story），并创建对应的Markdown文件在docs/stories/目录下。

4. @dev执行故事：激活@dev代理，并指定要执行的故事ID。

   @dev 开始执行 story STORY-123
   

   @dev代理会读取故事文件中的完整上下文、验收标准和文件列表，然后在一个隔离的“工作树”中开始编码，直到所有验收标准通过。

命令行工具概览 (aiox CLI)

AIOX提供了丰富的命令行工具，用于管理框架本身。

# 管理智能代理
aiox workers search "数据转换"          # 搜索具备特定能力的代理或工作器
aiox workers list                       # 列出所有可用的代理

# 质量与指标
aiox qa run --layer 1                   # 运行第一层质量门禁（本地快速检查）
aiox metrics show --trends              # 显示项目质量趋势

# 环境与配置
aiox doctor --fix                        # 诊断并修复环境问题
aiox mcp status                          # 查看模型上下文协议(MCP)服务器状态
aiox config show                          # 查看当前配置

# 文档生成
aiox generate prd --title "新功能规划"    # 生成产品需求文档(PRD)模板
aiox generate adr                         # 生成架构决策记录(ADR)模板

高级功能：MCP配置共享

AIOX支持通过MCP（Model Context Protocol）集成外部工具，并允许你将MCP配置全局化，在所有项目中共享。

# 创建全局MCP配置（仅需一次）
aiox mcp setup --with-defaults

# 在项目目录中链接到全局配置
cd your-project
aiox mcp link

现在，所有配置在~/.aiox/mcp/global-config.json中的MCP服务器都将对该项目可用。

💻 核心代码

1. 代理权威宪法 (constitution.md)

AIOX的核心原则被明文写入“宪法”，由所有代理共同遵守。以下节选了关于“代理权威”的关键规则。

# Synkra AIOX Constitution

> **Version:** 1.0.0

## Core Principles

### II. Agent Authority (NON-NEGOTIABLE)

Cada agente tem autoridades exclusivas que não podem ser violadas.

**Regras:**
- MUST: Apenas @devops pode executar `git push` para remote
- MUST: Apenas @devops pode criar Pull Requests
- MUST: Apenas @devops pode criar releases e tags
- MUST: Agentes DEVEM delegar para o agente apropriado quando fora de seu escopo
- MUST: Nenhum agente pode assumir autoridade de outro

**Exclusividades:**

| Autoridade        | Agente Exclusivo   |
| ----------------- | ------------------ |
| git push          | @devops            |
| PR creation       | @devops            |
| Release/Tag       | @devops            |
| Story creation    | @sm, @po           |
| Architecture decisions | @architect    |
| Quality verdicts  | @qa                |

2. 智能代码洞察客户端 (code-intel-client.js)

此模块是所有代码智能功能的核心入口，它实现了断路器模式和多提供者自动发现，确保框架的健壮性。

// aiox-core/core/code-intel/code-intel-client.js
'use strict';

const { CodeGraphProvider } = require('./providers/code-graph-provider');
const { RegistryProvider } = require('./providers/registry-provider');

// --- Constants ---
const CIRCUIT_BREAKER_THRESHOLD = 3;
const CIRCUIT_BREAKER_RESET_MS = 60000;
const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes

// Circuit breaker states
const CB_CLOSED = 'CLOSED';
const CB_OPEN = 'OPEN';
const CB_HALF_OPEN = 'HALF-OPEN';

/**
 * CodeIntelClient — Central entry point for code intelligence.
 *
 * Features:
 * - Provider auto-detection and registry
 * - Circuit breaker pattern (threshold 3, reset 60s)
 * - Session cache (Map-based, TTL 5min)
 * - Graceful fallback (returns null without throw when no provider available)
 */
class CodeIntelClient {
  constructor(options = {}) {
    this._providers = [];
    this._activeProvider = null;
    this._options = options;

    // Circuit breaker state
    this._cbState = CB_CLOSED;
    this._cbFailures = 0;
    this._cbOpenedAt = null;

    // Session cache
    this._cache = new Map();

    // Metrics
    this._cacheHits = 0;
    this._cacheMisses = 0;

    // Auto-register default providers
    this._registerDefaultProviders(options);
  }

  /**
   * Register default providers based on configuration.
   * Provider priority: RegistryProvider FIRST (native, T1), then CodeGraphProvider (MCP, T3).
   * First provider with isAvailable() === true wins.
   * @private
   */
  _registerDefaultProviders(options) {
    // RegistryProvider — native, T1, always available when registry exists
    const registryProvider = new RegistryProvider({
      registryPath: options.registryPath || null,
      projectRoot: options.projectRoot || null,
    });
    this._providers.push(registryProvider);

    // Code Graph MCP — T3, available when mcpCallFn is configured
    // ... (CodeGraphProvider registration)
  }

  // ... (other methods like findDefinition, findReferences, etc.)
}

3. 质量门禁运行器 (qa/run.js)

展示了AIOX如何通过CLI命令编排一个可靠的多步骤质量检查流程。

// aiox-core/cli/commands/qa/run.js
const { Command } = require('commander');
const { QualityGateManager } = require('../../../core/quality-gates/quality-gate-manager');

/**
 * Create the run subcommand
 */
function createRunCommand() {
  const run = new Command('run');

  run
    .description('Execute quality gate pipeline')
    .option('-l, --layer <number>', 'Run specific layer only (1, 2, or 3)')
    .option('-v, --verbose', 'Show detailed output', false)
    .option('-s, --story <id>', 'Story ID for reporting')
    .option('--save-report', 'Save detailed report to file', false)
    .option('--no-fail-fast', 'Continue on Layer 1 failures')
    .action(async (options) => {
      try {
        const manager = await QualityGateManager.load();

        const context = {
          verbose: options.verbose,
          storyId: options.story,
          failFast: options.failFast !== false,
        };

        let result;

        if (options.layer) {
          // Run specific layer
          const layerNum = parseInt(options.layer, 10);
          if (![1, 2, 3].includes(layerNum)) {
            console.error('Error: Layer must be 1, 2, or 3');
            process.exit(1);
          }
          result = await manager.runLayer(layerNum, context);
          printLayerResult(result, context.verbose);
        } else {
          // Run full pipeline
          result = await manager.orchestrate(context);
          if (!context.verbose) {
            printSummary(result);
          }
        }

        // Save status
        await manager.saveStatus();

        // Exit with appropriate code
        process.exit(result.exitCode || (result.pass ? 0 : 1));
      } catch (error) {
        console.error(`\n❌ Error: ${error.message}`);
        process.exit(1);
      }
    });

  return run;
}

4. 环境健康检查器 (doctor/index.js)

aiox doctor命令的实现，展示了其模块化、可修复的诊断架构。

// aiox-core/doctor/index.js
/**
 * AIOX Doctor — Environment Health Check Orchestrator
 *
 * Runs 12+ modular checks against the AIOX environment and returns
 * structured results with optional --fix, --json, and --dry-run support.
 */
const path = require('path');
const { loadChecks } = require('./checks');
const { formatText } = require('./formatters/text');
const { applyFixes } = require('./fix-handler');

const DOCTOR_VERSION = '2.0.0';

/**
 * Run all doctor checks
 */
async function runDoctorChecks(options = {}) {
  const {
    fix = false,
    json = false,
    dryRun = false,
    quiet = false,
    projectRoot = process.cwd(),
  } = options;

  const context = {
    projectRoot,
    frameworkRoot: path.resolve(__dirname, '..', '..', '..'),
    options: { fix, json, dryRun, quiet },
  };

  // Load and run all checks
  const checks = loadChecks();
  const results = [];

  for (const checkModule of checks) {
    try {
      const result = await checkModule.run(context);
      results.push(result);
    } catch (error) {
      results.push({
        check: checkModule.name || 'unknown',
        status: 'FAIL',
        message: `Check threw error: ${error.message}`,
        fixCommand: null,
      });
    }
  }

  // Apply fixes if requested
  let fixResults = null;
  if (fix || dryRun) {
    fixResults = await applyFixes(results, context);
  }

  // Build summary
  const summary = {
    pass: results.filter((r) => r.status === 'PASS').length,
    warn: results.filter((r) => r.status === 'WARN').length,
    fail: results.filter((r) => r.status === 'FAIL').length,
    info: results.filter((r) => r.status === 'INFO').length,
  };

  const output = {
    version: DOCTOR_VERSION,
    timestamp: new Date().toISOString(),
    summary,
    checks: results,
    fixResults,
  };

  // Format output
  if (json) {
    return { formatted: JSON.stringify(output, null, 2), data: output };
  }

  return { formatted: formatText(output, { quiet }), data: output };
}

module.exports = { runDoctorChecks, DOCTOR_VERSION };

---

立即开始您的自进化开发之旅：

npx aiox-core@latest init my-first-aiox-project
cd my-first-aiox-project
aiox doctor

与您的AI团队一起，探索前所未有的开发体验！ luQCeSQJCz+70vCVC3iFWia0wMMsWoRIdVb6eO7J/zw=