对 Synkra AIOX 做出贡献

葡萄牙語版本

欢迎来到 AIOX！感谢您对贡献的兴趣。本指南将帮助您了解我们的开发工作流程、贡献流程以及如何提交更改。

快速开始

1. Fork 并克隆

# 通过 GitHub UI Fork，然后克隆您的 fork
git clone https://github.com/YOUR_USERNAME/aiox-core.git
cd aiox-core

# 添加 upstream 远程
git remote add upstream https://github.com/SynkraAI/aiox-core.git

2. 设置开发环境

先决条件：

Node.js >= 20.0.0
npm
Git
GitHub CLI (gh) - 可选但推荐

# 安装依赖
npm install

# 验证设置
npm test
npm run lint
npm run typecheck

3. 创建功能分支

git checkout -b feature/your-feature-name

分支命名约定：

前缀	用于
`feature/`	新功能、代理、任务
`fix/`	错误修复
`docs/`	文档更新
`refactor/`	代码重构
`test/`	测试添加/改进

4. 进行更改

按照以下相关指南进行操作以进行您的贡献类型。

5. 运行本地验证

npm run lint      # 代码风格
npm run typecheck # 类型检查
npm test          # 运行测试
npm run build     # 验证构建

6. 推送并创建 PR

git push origin feature/your-feature-name

然后在 GitHub 上创建针对 main 分支的 Pull Request。

贡献类型

贡献	描述	难度
文档	修复拼写错误、改进指南	简单
错误修复	修复报告的问题	简单-中等
任务	添加新的任务工作流	中等
代理	创建新的 AI 代理角色	中等
Squads	代理 + 任务 + 工作流的包	高级
核心功能	框架改进	高级

开发工作流程

提交约定

我们使用 Conventional Commits：

<type>: <description>

<optional body>

类型： feat, fix, docs, style, refactor, test, chore

示例：

git commit -m "feat(agent): add security-auditor agent"
git commit -m "fix: resolve memory leak in config loader"
git commit -m "docs: update contribution guide"

Pull Request 流程

创建 PR 针对 main 分支
自动检查运行（lint、typecheck、test、build）
CodeRabbit 审查 - 提供 AI 驱动的反馈
维护者审查 - 至少需要 1 个批准
合并所有检查通过后

贡献代理

代理是具有特定专业知识和命令的 AI 角色。

代理文件位置

.aiox-core/development/agents/your-agent.md

所需的代理结构

agent:
  name: AgentName
  id: agent-id # kebab-case，唯一
  title: 描述性标题
  icon: emoji
  whenToUse: '何时激活此代理'

persona_profile:
  archetype: Builder | Analyst | Guardian | Operator | Strategist

  communication:
    tone: pragmatic | friendly | formal | analytical
    emoji_frequency: none | low | medium | high

    vocabulary:
      - domain-term-1
      - domain-term-2

    greeting_levels:
      minimal: '简短问候'
      named: '具有个性的命名问候'
      archetypal: '完整的原型问候'

    signature_closing: '签名短语'

persona:
  role: "代理的主要角色"
  style: '通信风格'
  identity: "代理的身份描述"
  focus: '代理关注的内容'

  core_principles:
    - 原则 1
    - 原则 2

commands:
  - help: 显示可用命令
  - custom-command: 命令描述

dependencies:
  tasks:
    - related-task.md
  tools:
    - tool-name

代理贡献检查清单

代理 ID 是唯一的并使用 kebab-case
persona_profile 完成，包括原型和沟通
所有命令都有描述
依赖关系列出所有必需的任务
没有硬编码的凭证或敏感数据
遵循代码库中的现有模式

代理的 PR 模板

创建 PR 时使用代理贡献模板。

贡献任务

任务是代理可以运行的可执行工作流。

任务文件位置

.aiox-core/development/tasks/your-task.md

所需的任务结构

# 任务名称

**描述：** 此任务做什么
**代理：** @dev, @qa, 等
**询问：** true | false

---

## 先决条件

- 先决条件 1
- 先决条件 2

## 步骤

### 第 1 步：第一步

描述要做什么。

**询问点（如果询问为 true）：**

- 要问用户的问题
- 提供的选项

### 第 2 步：第二步

继续进行更多步骤...

## 可交付成果

- [ ] 可交付成果 1
- [ ] 可交付成果 2

## 错误处理

如果发生 X，做 Y。

---

## 依赖关系

- `dependency-1.md`
- `dependency-2.md`

任务贡献检查清单

任务有明确的描述和目的
步骤是顺序的且合乎逻辑
询问点很清楚（如果适用）
可交付成果明确定义
包括错误处理指导
依赖关系存在于代码库中

任务的 PR 模板

创建 PR 时使用任务贡献模板。

贡献 Squads

Squads 是相关代理、任务和工作流的包。

Squad 结构

your-squad/
├── manifest.yaml       # Squad 元数据
├── agents/
│   └── your-agent.md
├── tasks/
│   └── your-task.md
└── workflows/
    └── your-workflow.yaml

Squad 清单

name: your-squad
version: 1.0.0
description: 此小队做什么
author: 您的名字
dependencies:
  - base-squad (可选)
agents:
  - your-agent
tasks:
  - your-task

Squad 资源

Squads 指南 - 完整文档
Squad 模板 - 从工作模板开始
Squad 讨论 - 分享想法

代码审查流程

自动检查

当您提交 PR 时，以下检查会自动运行：

检查	描述	必需
ESLint	代码风格和质量	是
TypeScript	类型检查	是
Build	构建验证	是
Tests	Jest 测试套件	是
Coverage	最少 80% 覆盖率	是

CodeRabbit AI 审查

CodeRabbit 自动审查您的 PR 并提供以下反馈：

代码质量和最佳实践
安全问题
AIOX 特定模式（代理、任务、工作流）
性能问题

严重级别：

级别	所需操作
关键	必须在合并前修复
高	强烈建议修复
中	考虑修复或记录为技术债务
低	可选改进

对 CodeRabbit 的回应：

在请求审查前解决关键和高问题
可以记录中等问题以供后续跟进
低问题是信息性的

维护者审查

自动检查通过后，维护者将：

验证更改符合项目标准
检查安全隐含
确保文档已更新
批准或请求更改

合并要求

验证系统

AIOX 实施了 深度防御策略，有 3 个验证层：

第 1 层：提交前（本地）

性能： < 5 秒

ESLint 带缓存
TypeScript 增量编译
IDE 同步（自动暂存 IDE 命令文件）

第 2 层：推送前（本地）

性能： < 2 秒

故事复选框验证
状态一致性检查

第 3 层：CI/CD（云）

性能： 2-5 分钟

完整的 lint 和类型检查
完整的测试套件
覆盖率报告
故事验证
分支保护规则

代码标准

JavaScript/TypeScript

ES2022 功能
优先使用 const 而不是 let
使用 async/await 而不是 promises
为公开 API 添加 JSDoc 注释
遵循现有代码风格

文件组织

.aiox-core/
├── development/
│   ├── agents/      # 代理定义
│   ├── tasks/       # 任务工作流
│   └── workflows/   # 多步工作流
├── core/            # 核心实用工具
└── product/
    └── templates/   # 文档模板

docs/
├── guides/          # 用户指南
└── architecture/    # 系统架构

ESLint & TypeScript

扩展：eslint:recommended, @typescript-eslint/recommended
目标：ES2022
启用严格模式
生产中没有 console.log（警告）

测试要求

覆盖率要求

最少： 80% 覆盖率（分支、函数、行、语句）
单元测试： 所有新函数均需要
集成测试： 工作流均需要

运行测试

npm test                    # 运行所有测试
npm run test:coverage       # 包含覆盖率报告
npm run test:watch          # 监视模式
npm test -- path/to/test.js # 特定文件

编写测试

describe('MyModule', () => {
  it('should do something', () => {
    const result = myFunction();
    expect(result).toBe(expected);
  });
});

常见问题

Q: 审查需要多长时间？

A: 我们的目标是在 24-48 小时内进行首次审查。复杂的更改可能需要更长时间。

Q: 我可以在不进行测试的情况下贡献吗？

A: 强烈建议进行测试。对于仅文档的更改，可能不需要测试。

Q: 如果我的 PR 有冲突怎么办？

A: 在最新的 main 上重新合并您的分支：

git fetch upstream
git rebase upstream/main
git push --force-with-lease

Q: 我可以用葡萄牙语贡献吗？

A: 是的！我们接受葡萄牙语的 PR。见 CONTRIBUTING-PT.md。

Q: 我如何成为维护者？

A: 随着时间的推移，持续的高质量贡献。从小的修复开始，逐步进入更大的功能。

Q: 我的 CI 检查失败了。我该怎么办？

A: 检查 GitHub Actions 日志：

gh pr checks  # 查看 PR 检查状态

常见修复：

为样式问题运行 npm run lint -- --fix
运行 npm run typecheck 以查看类型错误
在推送前确保测试在本地通过

获得帮助

GitHub Issues： 打开一个 issue
讨论： 开始讨论
社区： COMMUNITY.md

使用 Pro

AIOX 使用 Open Core 模型，带有私人 pro/ git 子模块（见 ADR-PRO-001）。

对于开源贡献者

您不需要 pro/ 子模块。 标准克隆完美运行：

git clone https://github.com/SynkraAI/aiox-core.git
cd aiox-core
npm install && npm test  # 所有测试都通过了，没有 pro/

pro/ 目录在您的克隆中将不存在——这是预期的，所有功能、测试和 CI 都在没有它的情况下通过。

对于有 Pro 访问权限的团队成员

# 使用子模块克隆
git clone --recurse-submodules https://github.com/SynkraAI/aiox-core.git

# 或添加到现有克隆
git submodule update --init pro

推送顺序： 始终先推送 pro/ 更改，然后是 aiox-core。

未来：CLI 设置

# 将在未来版本中发布
aiox setup --pro

有关完整的开发者工作流程指南，见 Pro 开发者工作流程。

其他资源

社区指南 - 如何参与
Squads 指南 - 创建代理团队
架构 - 系统设计
路线图 - 项目方向

感谢您对 Synkra AIOX 的贡献！

FilesExpand file tree

contributing.md

Latest commit

History