Skip to content

getting-started.md

Latest commit

 

History

History
317 lines (226 loc) · 8.84 KB

getting-started.md

File metadata and controls

317 lines (226 loc) · 8.84 KB
Raw

Synkra AIOX 入门指南

🌐 EN | PT | ES | ZH

欢迎使用 Synkra AIOX。本指南针对 10 分钟内实现首次价值进行了优化。

目录

  1. 10 分钟快速路径
  2. 安装
  3. 您的第一个项目
  4. 基本命令
  5. IDE 兼容性
  6. 棕地项目：现有项目
  7. 高级路径
  8. 故障排除
  9. 后续步骤

10 分钟快速路径

如果您是新手，请使用以下确切流程：

步骤 1：安装 AIOX

# 新项目
npx aiox-core init my-first-project
cd my-first-project

# 现有项目
# cd existing-project
# npx aiox-core install

步骤 2：选择您的 IDE 激活路径

  • Claude Code：/agent-name
  • Gemini CLI：/aiox-menu 然后 /aiox-<agent>
  • Codex CLI：/skills 然后 aiox-<agent-id>
  • Cursor/Copilot/AntiGravity：遵循 docs/ide-integration.md 中的约束

步骤 3：验证首次价值

当满足以下 3 个条件时，即实现首次价值：

  1. 您激活了一个 AIOX 代理。
  2. 您收到了有效的问候/激活响应。
  3. 您运行了一个启动命令（*help 或等效命令）并获得了有用的输出。

通过规则：在 <= 10 分钟内完成所有 3 个条件。

安装

前置要求

  • Node.js 版本 18.0.0 或更高（推荐 v20+）
  • npm 版本 9.0.0 或更高
  • Git（可选，但推荐）

快速安装

# 创建新项目
npx aiox-core init my-first-project

# 导航到您的项目
cd my-first-project

# 在您的 IDE 中开始使用 AIOX 代理
# （请参阅上面的步骤 2 了解 IDE 特定的激活方式）

安装选项

# 1. 使用自定义模板创建新项目
npx aiox-core init my-project --template enterprise

# 2. 在现有项目中安装
cd existing-project
npx aiox-core install

# 3. 在非空目录中强制安装
npx aiox-core init my-project --force

# 4. 跳过依赖安装（稍后手动安装）
npx aiox-core init my-project --skip-install

您的第一个项目

项目结构

安装后，您的项目将包含：

my-first-project/
├── .aiox-core/                 # AIOX 框架核心
│   ├── core/                   # 编排、内存、配置
│   ├── data/                   # 知识库、实体注册表
│   ├── development/            # 代理、任务、模板、脚本
│   └── infrastructure/         # CI/CD 模板、验证脚本
├── .claude/                    # Claude Code 集成（如果启用）
├── .codex/                     # Codex CLI 集成（如果启用）
├── .gemini/                    # Gemini CLI 集成（如果启用）
├── docs/                       # 文档
│   └── stories/                # 开发故事
├── packages/                   # 共享包
├── tests/                      # 测试套件
└── package.json                # 项目依赖

配置

AIOX 配置位于 .aiox-core/core/config/。安装程序处理初始设置。要验证您的安装：

npx aiox-core doctor

基本命令

代理激活

AIOX 代理通过您的 IDE 激活。激活后，代理响应以 * 为前缀的命令：

# 通用命令（在任何代理中都有效）
*help                    # 显示此代理的可用命令
*guide                   # 显示详细使用指南
*session-info            # 显示当前会话详情
*exit                    # 退出代理模式

# 代理特定示例
@dev *help               # 开发者代理命令
@qa *review STORY-42     # QA 代理审查故事
@pm *create-epic         # PM 代理创建 Epic
@sm *draft               # Scrum Master 起草故事

可用代理

代理 名称 专注领域
@dev Dex 代码实现、bug 修复、重构
@qa Quinn 测试、质量门控、代码审查
@architect Aria 系统设计、技术决策
@pm Bob PRD、战略、路线图
@po Pax 待办事项、故事验证、优先级排序
@sm River 故事创建、冲刺计划
@analyst Alex 研究、竞争分析
@data-engineer Dara 数据库设计、迁移
@ux-design-expert Uma UI/UX 设计、无障碍访问
@devops Gage Git 操作、CI/CD、部署

典型工作流

1. @pm 创建 PRD              → *create-epic
2. @sm 起草故事              → *draft
3. @po 验证故事              → *validate-story-draft
4. @dev 实现                 → （从故事文件工作）
5. @qa 审查                  → *review STORY-ID
6. @devops 推送              → *push（唯一具有推送权限的代理）
7. @po 关闭故事              → *close-story STORY-ID

IDE 兼容性

并非所有 IDE 都同等支持 AIOX 功能。请参阅 docs/ide-integration.md 中的完整比较。

摘要：

IDE/CLI 总体状态 如何激活
Claude Code 可用 /agent-name 命令
Gemini CLI 可用 /aiox-menu 然后 /aiox-<agent>
Codex CLI 有限 /skills 然后 aiox-<agent-id>
Cursor 有限 @agent + 同步规则
GitHub Copilot 有限 聊天模式 + 仓库指令
AntiGravity 有限 工作流驱动激活
  • 可用：完全推荐新用户使用。
  • 有限：可使用，有文档化的变通方法。

棕地项目：现有项目

已有代码库？AIOX 通过专用工作流处理棕地项目。

快速棕地项目设置

# 导航到您的现有项目
cd my-existing-project

# 安装 AIOX（非破坏性，保留您的配置）
npx aiox-core install

# 运行 doctor 验证兼容性
npx aiox-core doctor

首次运行时发生的事情

当您首次在现有项目中激活 AIOX 代理时：

  1. 检测：AIOX 检测到代码但没有 AIOX 文档
  2. 提议："我可以分析您的代码库。这需要 4-8 小时。"
  3. 发现：多代理技术债务评估（可选）
  4. 输出：系统架构文档 + 技术债务报告

棕地项目工作流选项

您的情况 推荐工作流
向现有项目添加主要功能 @pm → *create-doc brownfield-prd
审计遗留代码库 brownfield-discovery.yaml（完整工作流）
快速增强 @pm → *brownfield-create-epic
单个 bug 修复 @pm → *brownfield-create-story

安全保证

  • 非破坏性：AIOX 创建文件，从不覆盖现有文件
  • 回滚：git checkout HEAD~1 -- . 恢复 AIOX 之前的状态
  • 配置保留：您的 .eslintrc、tsconfig.json 等保持不变

资源

高级路径

对于想要深入了解的有经验用户：

同步和验证

# 将代理同步到所有配置的 IDE
npm run sync:ide

# 验证跨 IDE 一致性
npm run validate:parity

# 运行所有质量检查
npm run lint && npm run typecheck && npm test

故事驱动开发

所有 AIOX 开发都遵循 docs/stories/ 中的故事。每个故事包含：

  • 带复选框的验收标准
  • 映射到特定 AC 的任务
  • CodeRabbit 集成用于自动审查
  • 质量门控分配

请参阅用户指南了解完整工作流。

小队扩展

小队将 AIOX 扩展到软件开发之外的任何领域。请参阅小队指南。

故障排除

安装问题

# 检查 Node.js 版本
node --version  # 应该 >= 18.0.0

# 运行诊断
npx aiox-core doctor

# 自动修复常见问题
npx aiox-core doctor --fix

代理无响应

  1. 验证您的 IDE 是否受支持（请参阅 IDE 兼容性）。
  2. 运行 npm run sync:ide 刷新代理文件。
  3. 重启您的 IDE/CLI 会话。

同步问题

# 预览将要更改的内容
npm run sync:ide -- --dry-run

# 强制重新同步
npm run sync:ide

# 同步后验证
npm run validate:parity

后续步骤

Synkra AIOX 入门指南 v4.2.11