⚠️ 已弃用: 本文件仅为向后兼容性而维护。官方版本: docs/framework/tech-stack.md
本文件将在 2026 Q2 完成
docs/framework/整合后移除。
版本: 1.1
最后更新: 2025-12-14
状态: 已弃用 - 参见 docs/framework/tech-stack.md
迁移通知: 本文档将在 2026 Q2 迁移到 SynkraAI/aiox-core 仓库 (参见决策 005)
AIOX 构建在现代 JavaScript/TypeScript 和 Node.js 运行时上，优化用于开发具有交互式 UX 和代理编排功能的跨平台 CLI。
理念:
- 尽可能使用成熟技术 (经过验证和稳定的依赖)
- 仅在必要时选择创新技术 (性能、DX 改进)
- 最小化依赖 (降低供应链风险)
- 优先跨平台 (Windows、macOS、Linux)
版本: 18.0.0+
LTS: 是 (LTS 有效期至 2025 年 4 月)
原因: 稳定的 async/await 支持、fetch API、ES2022为什么选择 Node.js 18+:
- ✅ 原生
fetch()API (无需 axios/node-fetch) - ✅ 对 ES2022 模块的支持 (顶级 await)
- ✅ V8 10.2+ (性能改进)
- ✅ 活跃的 LTS 支持 (安全补丁)
- ✅ 跨平台 (Windows/macOS/Linux)
包管理器:
主要: npm 9.0.0+
备选: yarn/pnpm (用户选择)
锁定文件: package-lock.json标准: ES2022
模块系统: CommonJS (require/module.exports)
未来: 计划迁移到 ESM (故事 6.2.x)为什么选择 ES2022:
- ✅ 类字段和私有方法
- ✅ 顶级 await
- ✅ 错误 cause
- ✅ 数组 Array.at() 方法
- ✅ Object.hasOwn()
版本: 5.9.3
用途: 仅类型定义 (.d.ts 文件)
编译: 不使用 (纯 JS 运行时)
未来: 考虑完全迁移到 TypeScript (Q2 2026)当前的 TypeScript 用途:
// index.d.ts - API 公开的类型定义
export interface AgentConfig {
id: string;
name: string;
enabled: boolean;
dependencies?: string[];
}
export function executeAgent(agentId: string, args: Record<string, any>): Promise<any>;TypeScript 配置:
{
"compilerOptions": {
"target": "ES2022",
"module": "commonjs",
"lib": ["ES2022"],
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"declaration": true,
"outDir": "./dist"
}
}目的: 现代化的 CLI 提示，具有优雅的 UX 用途: 交互式向导、用户输入收集 优势: 世界级的 UX、微调动画、进度条
import { select, confirm, spinner } from '@clack/prompts';
const agent = await select({
message: '选择代理:',
options: [
{ value: 'dev', label: '💻 Developer' },
{ value: 'qa', label: '🧪 QA Engineer' },
],
});目的: 终端字符串样式化 用途: 彩色输出、格式化 优势: 跨平台、零依赖、API 稳定
const chalk = require('chalk');
console.log(chalk.green('✅ 代理激活成功'));
console.log(chalk.red('❌ 任务失败'));目的: 轻量级颜色库 (比 chalk 更快的替代品) 用途: 性能关键的彩色输出 优势: 比 chalk 小 14 倍，快 2 倍
const pc = require('picocolors');
console.log(pc.green('✅ 快速输出'));目的: 终端加载动画 用途: 加载指示器、异步操作 优势: 美观的加载动画、可定制、广泛使用
const ora = require('ora');
const spinner = ora('加载代理中...').start();
await loadAgent();
spinner.succeed('代理已加载');目的: 改进的文件系统操作
用途: 文件复制、目录创建、JSON 读/写
优势: 基于 Promise、相对于原生 fs 的额外工具
const fs = require('fs-extra');
await fs.copy('source', 'dest');
await fs.ensureDir('path/to/dir');
await fs.outputJson('config.json', data);目的: 文件模式匹配
用途: 按模式查找文件 (例: *.md、**/*.yaml)
优势: 快速、支持 gitignore 模式
const { glob } = require('glob');
const stories = await glob('docs/stories/**/*.md');目的: YAML 解析和序列化 用途: 代理配置、工作流、模板 优势: 快速、符合规范、保留注释
const YAML = require('yaml');
const agent = YAML.parse(fs.readFileSync('agent.yaml', 'utf8'));目的: 替代 YAML 解析器 (旧版支持) 用途: 解析旧的 YAML 文件 优势: API 不同、用于旧代码
const yaml = require('js-yaml');
const doc = yaml.load(fs.readFileSync('config.yaml', 'utf8'));迁移说明: 整合为单个 YAML 库 (故事 6.2.x)
目的: 将 markdown 解析为 AST 用途: 故事解析、文档结构分析 优势: 轻量级、快速、支持 GFM
const { parseMarkdown } = require('@kayvan/markdown-tree-parser');
const ast = parseMarkdown(markdownContent);目的: 改进的 child_process 用途: 执行 git、npm、外部 CLI 工具 优势: 跨平台、基于 Promise、更好的错误处理
const { execa } = require('execa');
const { stdout } = await execa('git', ['status']);目的: CLI 框架 用途: 命令行参数解析、子命令 优势: 行业标准、功能丰富、TypeScript 支持
const { Command } = require('commander');
const program = new Command();
program
.command('agent <name>')
.description('激活一个代理')
.action((name) => {
console.log(`激活代理: ${name}`);
});目的: 交互式命令行提示 用途: 用户输入收集、向导 优势: 丰富的提示类型、验证支持
const inquirer = require('inquirer');
const answers = await inquirer.prompt([
{
type: 'list',
name: 'agent',
message: '选择代理:',
choices: ['dev', 'qa', 'architect'],
},
]);目的: V8 隔离区用于沙箱 JavaScript 执行 用途: 安全执行用户脚本、任务执行 优势: 安全隔离、内存限制、超时控制
const ivm = require('isolated-vm');
const isolate = new ivm.Isolate({ memoryLimit: 128 });
const context = await isolate.createContext();目的: 字符串验证和清理 用途: 输入验证 (URL、邮箱等) 优势: 全面、测试充分、无依赖
const validator = require('validator');
if (validator.isURL(url)) {
// URL 有效
}目的: 语义版本解析和比较 用途: 版本检查、依赖解析 优势: NPM 标准、充分测试
const semver = require('semver');
if (semver.satisfies('1.2.3', '>=1.0.0')) {
// 版本兼容
}目的: JavaScript/TypeScript 代码检查
配置: .eslintrc.json
插件:
@typescript-eslint/eslint-plugin(^8.46.2)@typescript-eslint/parser(^8.46.2)
主要规则:
{
"rules": {
"no-console": "off", // CLI 中允许 console
"no-unused-vars": "error",
"prefer-const": "error",
"no-var": "error",
"eqeqeq": ["error", "always"]
}
}目的: 代码格式化
配置: .prettierrc
{
"printWidth": 100,
"tabWidth": 2,
"useTabs": false,
"semi": true,
"singleQuote": true,
"trailingComma": "es5"
}目的: YAML 文件检查 用途: 验证代理配置、工作流、模板
目的: Git hooks 管理 用途: 提交前 linting、推送前测试
{
"husky": {
"hooks": {
"pre-commit": "lint-staged",
"pre-push": "npm test"
}
}
}目的: 在暂存文件上运行 linters 配置:
{
"lint-staged": {
"**/*.md": ["prettier --write"],
"**/*.{js,ts}": ["eslint --fix", "prettier --write"]
}
}目的: 测试框架 用途: 单元测试、集成测试、覆盖率
// 测试示例
describe('AgentExecutor', () => {
it('should load agent configuration', async () => {
const agent = await loadAgent('dev');
expect(agent.name).toBe('developer');
});
});配置:
{
"jest": {
"testEnvironment": "node",
"coverageThreshold": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": 80
}
}
}
}目的: Jest 的 TypeScript 类型定义 用途: 使用类型安全的方式编写测试
目的: 自动化的语义版本化和发布 用途: 自动发布到 NPM、生成 changelog
插件:
@semantic-release/changelog(^6.0.3) - 生成 CHANGELOG.md@semantic-release/git(^10.0.1) - 提交发布资源
{
"release": {
"branches": ["main"],
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
"@semantic-release/npm",
"@semantic-release/git"
]
}
}# 包构建
npm run build # 构建所有包
npm run build:agents # 仅构建代理
npm run build:teams # 仅构建团队
# 版本化
npm run version:patch # 增加补丁版本
npm run version:minor # 增加次要版本
npm run version:major # 增加主要版本
# 发布
npm run publish:dry-run # 测试发布
npm run publish:preview # 发布为 preview 标签
npm run publish:stable # 发布为 latest 标签AIOX 与 Model Context Protocol (MCP) 服务器集成:
MCP 服务器:
- clickup-direct: ClickUp 集成 (任务管理)
- context7: 文档查找
- exa-direct: Web 搜索
- desktop-commander: 文件操作
- docker-mcp: Docker 管理
- ide: VS Code/Cursor 集成配置: .claude.json 或 .cursor/settings.json
代理使用的外部 CLI 工具:
GitHub CLI (gh):
版本: 2.x+
用途: 仓库管理、PR 创建
安装: https://cli.github.com
Railway CLI (railway):
版本: 3.x+
用途: 部署自动化
安装: npm i -g @railway/cli
Supabase CLI (supabase):
版本: 1.x+
用途: 数据库迁移、schema 管理
安装: npm i -g supabase
Git:
版本: 2.30+
用途: 版本控制
必需: 是Railway:
目的: 应用部署
API: Railway CLI
Supabase:
目的: PostgreSQL 数据库 + 身份验证
API: Supabase CLI + REST API
GitHub:
目的: 仓库托管、CI/CD
API: GitHub CLI (gh) + Octokit
CodeRabbit:
目的: 自动化代码审查
API: GitHub App 集成计划于 2026 Q2-Q4 (仓库重组后):
// 当前: CommonJS
const agent = require('./agent');
module.exports = { executeAgent };
// 未来: ES Modules
import { agent } from './agent.js';
export { executeAgent };// 从 JS + .d.ts 迁移到完整的 TypeScript
// 优势: 类型安全、更好的重构、改进的 DXBundler: esbuild 或 tsup
原因: 快速构建、树摇晃、最小化
目标: 单个 CLI 可执行文件 (可选)E2E 测试: Playwright (浏览器自动化测试)
性能测试: Benchmark.js (工作流计时)# 运行安全审计
npm audit
# 自动修复漏洞
npm audit fix
# 检查过期的包
npm outdated主要更新: 季度审查 (Q1, Q2, Q3, Q4)
安全补丁: 立即 (48 小时内)
次要更新: 月度审查
依赖减少: 持续工作# 查看依赖树
npm ls --depth=2
# 查找重复的包
npm dedupe
# 分析 bundle 大小
npx cost-of-modules| 组件 | 版本 | 兼容性 | 说明 |
|---|---|---|---|
| Node.js | 18.0.0+ | 必需 | 活跃 LTS |
| npm | 9.0.0+ | 必需 | 包管理器 |
| TypeScript | 5.9.3 | 推荐 | 类型定义 |
| ESLint | 9.38.0 | 必需 | Linting |
| Prettier | 3.5.3 | 必需 | 格式化 |
| Jest | 30.2.0 | 必需 | 测试 |
| Git | 2.30+ | 必需 | 版本控制 |
| GitHub CLI | 2.x+ | 可选 | 仓库管理 |
| Railway CLI | 3.x+ | 可选 | 部署 |
| Supabase CLI | 1.x+ | 可选 | 数据库管理 |
# 生产 bundle 大小 (最小化)
总计: ~5MB (包括所有依赖)
# 关键依赖 (总是加载):
- commander: 120KB
- chalk: 15KB
- yaml: 85KB
- fs-extra: 45KB
# 可选依赖 (延迟加载):
- inquirer: 650KB (仅交互模式)
- @clack/prompts: 180KB (仅向导模式)冷启动: ~200ms (初始加载)
热启动: ~50ms (模块缓存)
Yolo 模式: ~100ms (跳过验证)
优化策略:
- 延迟加载重型依赖
- 缓存解析的 YAML 配置
- 有条件地使用 require()基线: 30MB (Node.js + AIOX core)
代理执行: +10MB (每个代理)
故事处理: +20MB (markdown 解析)
峰值: ~100MB (典型工作流)路径分隔符: 反斜杠 (\) - 规范化为正斜杠 (/)
行尾: CRLF - Git 配置自动转换
Shell: PowerShell 或 CMD - execa 处理跨平台
Node.js: 来自 nodejs.org 的 Windows 安装程序路径分隔符: 正斜杠 (/)
行尾: LF
Shell: zsh (默认) 或 bash
Node.js: Homebrew (brew install node@18) 或 nvm路径分隔符: 正斜杠 (/)
行尾: LF
Shell: bash (默认) 或 zsh
Node.js: nvm、apt、yum 或官方二进制文件# AIOX 配置
AIOX_DEBUG=true # 启用调试日志
AIOX_CONFIG_PATH=/custom/path # 自定义配置位置
AIOX_YOLO_MODE=true # 强制 yolo 模式
# Node.js
NODE_ENV=production # 生产模式
NODE_OPTIONS=--max-old-space-size=4096 # 增加内存限制
# 外部服务
CLICKUP_API_KEY=pk_xxx # ClickUp 集成
GITHUB_TOKEN=ghp_xxx # GitHub API 访问
RAILWAY_TOKEN=xxx # Railway 部署
SUPABASE_ACCESS_TOKEN=xxx # Supabase CLI 身份验证| 版本 | 日期 | 更改 | 作者 |
|---|---|---|---|
| 1.0 | 2025-01-15 | 初始技术栈文档 | Aria (architect) |
| 1.1 | 2025-12-14 | 更新对 SynkraAI/aiox-core 的迁移通知、semantic-release 到 v25.0.2 [故事 6.10] | Dex (dev) |
这是 AIOX 框架的官方模式。所有技术选择应与本栈保持一致。