版本: 2.1.0 最后更新: 2025-01-24
答案: 我们推荐使用 npx @synkra/aiox-core install 而不是全局安装，原因如下：
- 始终最新版本: npx 自动获取最新版本
- 无全局污染: 不会添加到全局 npm 包
- 项目隔离: 每个项目可以拥有自己的版本
- 无权限问题: 避免常见的全局 npm 权限问题
- CI/CD 友好: 在自动化管道中无缝工作
如果您更喜欢全局安装：
npm install -g @synkra/aiox-core
@synkra/aiox-core install答案:
| 组件 | 最小版本 | 推荐版本 |
|---|---|---|
| Node.js | 18.0.0 | 20.x LTS |
| npm | 9.0.0 | 10.x |
| 磁盘空间 | 100 MB | 500 MB |
| RAM | 2 GB | 8 GB |
| OS | Windows 10, macOS 12, Ubuntu 20.04 | 最新版本 |
检查您的系统：
node --version # 应为 18+
npm --version # 应为 9+答案: 可以！AIOX 为绿地和棕地项目设计。
对于现有项目：
cd /path/to/existing-project
npx @synkra/aiox-core install安装程序将：
- 创建
.aiox-core/目录（框架文件） - 创建 IDE 配置（
.claude/、.cursor/等） - 不修改您的现有源代码
- 不覆盖现有文档，除非您选择
重要: 如果您有现有的 .claude/ 或 .cursor/ 目录，安装程序会在修改前询问。
答案:
| 场景 | 时间 |
|---|---|
| 首次安装 | 2-5 分钟 |
| 更新现有安装 | 1-2 分钟 |
| 仅安装启动 Squad | 30-60 秒 |
影响安装时间的因素：
- 互联网连接速度
- npm 缓存状态
- 选中的 IDE 数量
- 选中的启动 Squad 数量
答案: AIOX 创建以下结构：
your-project/
├── .aiox-core/ # 框架核心（200+ 文件）
│ ├── agents/ # 11+ 个代理定义
│ ├── tasks/ # 60+ 个任务工作流
│ ├── templates/ # 20+ 个文档模板
│ ├── checklists/ # 验证清单
│ ├── scripts/ # 实用脚本
│ └── core-config.yaml # 框架配置
│
├── .claude/ # Claude Code（如果选中）
│ └── commands/AIOX/agents/ # 代理斜杠命令
│
├── .cursor/ # Cursor（如果选中）
│ └── rules/ # 代理规则
│
├── docs/ # 文档结构
│ ├── stories/ # 开发故事
│ ├── architecture/ # 架构文档
│ └── prd/ # 产品需求
│
└── Squads/ # （如果安装）
└── hybrid-ops/ # HybridOps 包
答案:
# 通过 npx 更新（推荐）
npx @synkra/aiox-core update
# 或重新安装最新版本
npx @synkra/aiox-core install --force-upgrade
# 检查当前版本
npx @synkra/aiox-core status更新的内容：
.aiox-core/文件（代理、任务、模板）- IDE 配置
- 启动 Squad（如果安装）
保留的内容：
core-config.yaml中的自定义修改- 您的文档（
docs/） - 您的源代码
答案: 我们建议：
| 更新类型 | 频率 | 命令 |
|---|---|---|
| 安全补丁 | 立即 | npx @synkra/aiox-core update |
| 次要更新 | 每月 | npx @synkra/aiox-core update |
| 主要版本 | 每季度 | 先查看变更日志 |
检查更新：
npm show @synkra/aiox-core version
npx @synkra/aiox-core status答案: 可以，有多个选项：
选项 1：重新安装特定版本
npx @synkra/aiox-core@1.1.0 install --force-upgrade选项 2：使用 Git 恢复
# 如果 .aiox-core 在 git 中跟踪
git checkout HEAD~1 -- .aiox-core/选项 3：从备份恢复
# 安装程序创建备份
mv .aiox-core .aiox-core.failed
mv .aiox-core.backup .aiox-core答案: 可以，但需要一些准备：
初始设置（需要互联网）：
# 联网时安装一次
npx @synkra/aiox-core install
# 打包以供离线使用
tar -czvf aiox-offline.tar.gz .aiox-core/ .claude/ .cursor/在隔离机器上：
# 解压软件包
tar -xzvf aiox-offline.tar.gz
# AIOX 代理可在没有互联网的情况下工作
# （它们不需要外部 API 调用）没有互联网的限制：
- 无法更新到新版本
- MCP 集成（ClickUp、GitHub）将不工作
- 无法获取库文档（Context7）
答案:
-
在联网机器上：
# 安装并打包 npx @synkra/aiox-core install cd your-project tar -czvf aiox-transfer.tar.gz .aiox-core/ .claude/ .cursor/ docs/
-
通过 USB、安全传输等转移归档文件
-
在隔离机器上：
cd your-project tar -xzvf aiox-transfer.tar.gz -
如果需要，手动配置 IDE（路径可能不同）
答案:
| IDE | 状态 | 代理激活 |
|---|---|---|
| Claude Code | 完全支持 | /dev、/qa 等 |
| Cursor | 完全支持 | @dev、@qa 等 |
| Gemini CLI | 完全支持 | 在提示中提及 |
| GitHub Copilot | 完全支持 | 聊天模式 |
为新 IDE 添加支持: 使用 IDE 的代理/规则规范打开 GitHub 问题。
答案: 可以！在安装过程中选择多个 IDE：
交互式：
? Which IDE(s) do you want to configure?
❯ ◉ Cursor
◉ Claude Code
命令行：
npx @synkra/aiox-core install --ide cursor,claude-code每个 IDE 获得其自己的配置目录：
.cursor/rules/用于 Cursor.claude/commands/用于 Claude Code
答案:
如果 .aiox-core/ 已提交到您的仓库：
# 新团队成员只需克隆
git clone your-repo
cd your-repo
# 可选择配置他们喜欢的 IDE
npx @synkra/aiox-core install --ide cursor如果 .aiox-core/ 未提交：
git clone your-repo
cd your-repo
npx @synkra/aiox-core install最佳实践: 将 .aiox-core/ 提交到您的仓库以共享一致的代理配置。
答案: AIOX 包括 11+ 个专门代理：
| 代理 | 角色 | 最适合的工作 |
|---|---|---|
dev |
全栈开发者 | 代码实现、调试 |
qa |
QA 工程师 | 测试、代码审查 |
architect |
系统架构师 | 设计、架构决策 |
pm |
项目经理 | 规划、跟踪 |
po |
产品所有者 | 积压工作、需求 |
sm |
Scrum 主管 | 便利化、冲刺管理 |
analyst |
业务分析师 | 需求分析 |
ux-expert |
UX 设计师 | 用户体验设计 |
data-engineer |
数据工程师 | 数据管道、ETL |
devops |
DevOps 工程师 | CI/CD、部署 |
db-sage |
数据库架构师 | 模式设计、查询 |
答案:
-
复制现有代理：
cp .aiox-core/agents/dev.md .aiox-core/agents/my-agent.md
-
编辑 YAML 前置：
agent: name: MyAgent id: my-agent title: My Custom Agent icon: 🔧 persona: role: Expert in [your domain] style: [communication style]
-
添加到 IDE 配置：
npx @synkra/aiox-core install --ide claude-code
-
激活:
/my-agent或@my-agent
答案: Yolo 模式是自主开发模式，其中代理：
- 不需分步确认即可实现故事任务
- 根据故事需求自主做出决策
- 在
.ai/decision-log-{story-id}.md中记录所有决策 - 可随时停止
启用 yolo 模式：
/dev
*develop-yolo docs/stories/your-story.md何时使用：
- 对于需求明确、接受条件清晰的故事
- 当您信任代理的决策制定时
- 对于重复性任务
何时不使用：
- 对于复杂的架构变更
- 当需求模糊时
- 对于生产关键代码
答案: 启动 Squad 是可选的扩展，用于扩展 AIOX 功能：
| 包 | 功能 |
|---|---|
| hybrid-ops | ClickUp 集成、流程自动化、专门工作流 |
安装 Squad：
npx @synkra/aiox-core install --Squads hybrid-ops列出可用的 Squad：
npx @synkra/aiox-core install答案: 可以！启动 Squad 遵循此结构：
my-expansion/
├── pack.yaml # 包清单
├── README.md # 文档
├── agents/ # 自定义代理
│ └── my-agent.md
├── tasks/ # 自定义任务
│ └── my-task.md
├── templates/ # 自定义模板
│ └── my-template.yaml
└── workflows/ # 自定义工作流
└── my-workflow.yaml
pack.yaml 示例：
name: my-expansion
version: 1.0.0
description: My custom Squad
dependencies:
aiox-core: ">=1.0.0"
agents:
- my-agent
tasks:
- my-task答案:
GitHub Actions 示例：
name: CI with AIOX
on: [push]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: "18"
- run: npx @synkra/aiox-core install --full --ide claude-code
- run: npm testGitLab CI 示例：
test:
image: node:18
script:
- npx @synkra/aiox-core install --full
- npm test答案: core-config.yaml 文件控制框架行为：
# 文档分片
prd:
prdSharded: true
prdShardedLocation: docs/prd
# 故事位置
devStoryLocation: docs/stories
# dev 代理加载的文件
devLoadAlwaysFiles:
- docs/framework/coding-standards.md
- docs/framework/tech-stack.md
# Git 配置
git:
showConfigWarning: true
cacheTimeSeconds: 300
# 代理问候语中的项目状态
projectStatus:
enabled: true
showInGreeting: true编辑后，重启 IDE 以应用更改。
答案:
-
创建功能分支：
git checkout -b feature/my-feature
-
按照编码标准做出更改：
- 阅读
docs/framework/coding-standards.md - 为新功能添加测试
- 更新文档
- 阅读
-
提交 pull request：
- 描述您的更改
- 链接到相关问题
- 等待审查
欢迎的贡献类型：
- 错误修复
- 新代理
- 文档改进
- 启动 Squad
- IDE 集成
答案:
| 资源 | 链接 |
|---|---|
| 文档 | docs/ 在您的项目中 |
| 故障排除 | troubleshooting.md |
| GitHub Issues | https://github.com/SynkraAI/aiox-core/issues |
| 源代码 | https://github.com/SynkraAI/aiox-core |
在寻求帮助之前：
- 检查此 FAQ
- 检查 故障排除指南
- 搜索现有 GitHub 问题
- 在您的问题中包含系统信息和错误消息