# AIOX 编码标准 > 🌐 [EN](../../architecture/coding-standards.md) | [PT](../../pt/architecture/coding-standards.md) | **ZH** --- > ⚠️ **已弃用**: 此文件仅为向后兼容性而保留。 > > **官方版本**: [docs/framework/coding-standards.md](../framework/coding-standards.md) > > 此文件将在 Q2 2026 后在 `docs/framework/` 完全合并后被移除。 --- # AIOX 编码标准 **版本**: 1.1 **最后更新**: 2025-12-14 **状态**: 已弃用 - 请查看 docs/framework/coding-standards.md **迁移通知**: 此文档将在 Q2 2026 迁移到 `SynkraAI/aiox-core` 存储库 (见决策 005) --- ## 📋 目录 - [概述](#概述) - [JavaScript/TypeScript 标准](#javascripttypescript-标准) - [文件组织](#文件组织) - [命名约定](#命名约定) - [代码质量](#代码质量) - [文档模式](#文档模式) - [测试标准](#测试标准) - [Git 约定](#git-约定) - [安全模式](#安全模式) --- ## 概述 本文档定义了 AIOX 框架开发的官方编码标准。所有代码贡献必须遵守这些标准以确保一致性、可维护性和质量。 **应用**: - ESLint (自动) - Prettier (自动) - CodeRabbit 审查 (自动) - 人工审查 (手动) --- ## JavaScript/TypeScript 标准 ### 语言版本 ```javascript // 目标: ES2022 (Node.js 18+) // TypeScript: 5.x // ✅ 好的: 现代语法 const data = await fetchData(); const { id, name } = data; // ❌ 不好: 过时语法 fetchData().then(function (data) { var id = data.id; var name = data.name; }); ``` ### TypeScript 配置 ```json // tsconfig.json { "compilerOptions": { "target": "ES2022", "module": "commonjs", "lib": ["ES2022"], "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "resolveJsonModule": true, "declaration": true, "outDir": "./dist", "rootDir": "./src" } } ``` ### 代码风格 #### 缩进和格式化 ```javascript // ✅ 好的: 2 空格缩进 function processAgent(agent) { if (agent.enabled) { return loadAgent(agent); } return null; } // ❌ 不好: 4 空格或制表符 function processAgent(agent) { if (agent.enabled) { return loadAgent(agent); } return null; } ``` **Prettier 配置**: ```json { "printWidth": 100, "tabWidth": 2, "useTabs": false, "semi": true, "singleQuote": true, "trailingComma": "es5", "bracketSpacing": true, "arrowParens": "always" } ``` #### 行长度 ```javascript // ✅ 好的: 最多 100 个字符 const result = await executeTask(taskName, taskArgs, { timeout: 5000, retry: 3 }); // ❌ 不好: 超过 100 个字符 const result = await executeTask(taskName, taskArgs, { timeout: 5000, retry: 3, failureCallback: onFailure, }); ``` #### 引号 ```javascript // ✅ 好的: 字符串使用单引号 const agentName = 'developer'; const message = `Agent ${agentName} activated`; // ❌ 不好: 双引号 (JSON 除外) const agentName = "developer"; ``` ### 现代 JavaScript 模式 #### Async/Await (优先) ```javascript // ✅ 好的: async/await async function loadAgent(agentId) { try { const agent = await fetchAgent(agentId); const config = await loadConfig(agent.configPath); return { agent, config }; } catch (error) { console.error(`Failed to load agent ${agentId}:`, error); throw error; } } // ❌ 不好: Promise 链 function loadAgent(agentId) { return fetchAgent(agentId) .then((agent) => loadConfig(agent.configPath).then((config) => ({ agent, config }))) .catch((error) => { console.error(`Failed to load agent ${agentId}:`, error); throw error; }); } ``` #### 解构 ```javascript // ✅ 好的: 解构 const { name, id, enabled } = agent; const [first, second, ...rest] = items; // ❌ 不好: 手动提取 const name = agent.name; const id = agent.id; const enabled = agent.enabled; ``` #### 箭头函数 ```javascript // ✅ 好的: 箭头函数用于回调 const activeAgents = agents.filter((agent) => agent.enabled); const agentNames = agents.map((agent) => agent.name); // ❌ 不好: 传统函数用于简单回调 const activeAgents = agents.filter(function (agent) { return agent.enabled; }); ``` #### 模板字面量 ```javascript // ✅ 好的: 模板字面量用于字符串插值 const message = `Agent ${agentName} loaded successfully`; const path = `${baseDir}/${agentId}/config.yaml`; // ❌ 不好: 字符串连接 const message = 'Agent ' + agentName + ' loaded successfully'; const path = baseDir + '/' + agentId + '/config.yaml'; ``` ### 错误处理 ```javascript // ✅ 好的: 具体错误处理和上下文 async function executeTask(taskName) { try { const task = await loadTask(taskName); return await task.execute(); } catch (error) { console.error(`Task execution failed [${taskName}]:`, error); throw new Error(`Failed to execute task "${taskName}": ${error.message}`); } } // ❌ 不好: 静默失败或通用错误 async function executeTask(taskName) { try { const task = await loadTask(taskName); return await task.execute(); } catch (error) { console.log('Error:', error); return null; // 静默失败 } } ``` --- ## 文件组织 ### 目录结构 ``` .aiox-core/ ├── agents/ # 代理定义 (YAML + Markdown) ├── tasks/ # 任务工作流 (Markdown) ├── templates/ # 文档模板 (YAML/Markdown) ├── workflows/ # 多步工作流 (YAML) ├── checklists/ # 验证清单 (Markdown) ├── data/ # 知识库 (Markdown) ├── utils/ # 实用脚本 (JavaScript) ├── tools/ # 工具集成 (YAML) └── elicitation/ # 启发引擎 (JavaScript) docs/ ├── architecture/ # 项目特定架构决策 ├── framework/ # 官方框架文档 (迁移到 REPO 1) ├── stories/ # 开发故事 ├── epics/ # Epic 规划 └── guides/ # 实用指南 ``` ### 文件命名 ```javascript // ✅ 好的: kebab-case 文件名 agent - executor.js; task - runner.js; greeting - builder.js; context - detector.js; // ❌ 不好: camelCase 或 PascalCase 文件名 agentExecutor.js; TaskRunner.js; GreetingBuilder.js; ``` ### 模块结构 ```javascript // ✅ 好的: 清晰的模块结构 // 文件: agent-executor.js // 1. Imports const fs = require('fs').promises; const yaml = require('yaml'); const { loadConfig } = require('./config-loader'); // 2. 常数 const DEFAULT_TIMEOUT = 5000; const MAX_RETRIES = 3; // 3. 辅助函数 (私有) function validateAgent(agent) { // ... } // 4. 主要 Exports (公共 API) async function executeAgent(agentId, args) { // ... } async function loadAgent(agentId) { // ... } // 5. Exports module.exports = { executeAgent, loadAgent, }; ``` --- ## 命名约定 ### 变量和函数 ```javascript // ✅ 好的: camelCase 用于变量和函数 const agentName = 'developer'; const taskResult = await executeTask(); function loadAgentConfig(agentId) { // ... } async function fetchAgentData(agentId) { // ... } // ❌ 不好: snake_case 或 PascalCase const agent_name = 'developer'; const TaskResult = await executeTask(); function LoadAgentConfig(agentId) { // ... } ``` ### 类 ```javascript // ✅ 好的: PascalCase 用于类 class AgentExecutor { constructor(config) { this.config = config; } async execute(agentId) { // ... } } class TaskRunner { // ... } // ❌ 不好: camelCase 或 snake_case class agentExecutor { // ... } class task_runner { // ... } ``` ### 常数 ```javascript // ✅ 好的: SCREAMING_SNAKE_CASE 用于常数 const MAX_RETRY_ATTEMPTS = 3; const DEFAULT_TIMEOUT_MS = 5000; const AGENT_STATUS_ACTIVE = 'active'; // ❌ 不好: camelCase 或小写 const maxRetryAttempts = 3; const defaulttimeout = 5000; ``` ### 私有成员 ```javascript // ✅ 好的: 下划线前缀表示私有 (惯例) class AgentManager { constructor() { this._cache = new Map(); this._isInitialized = false; } _loadFromCache(id) { // 私有辅助 return this._cache.get(id); } async getAgent(id) { // 公共 API return this._loadFromCache(id) || (await this._fetchAgent(id)); } } ``` ### 布尔变量 ```javascript // ✅ 好的: is/has/should 前缀 const isEnabled = true; const hasPermission = false; const shouldRetry = checkCondition(); // ❌ 不好: 模糊名称 const enabled = true; const permission = false; const retry = checkCondition(); ``` --- ## 代码质量 ### ESLint 配置 ```json { "env": { "node": true, "es2022": true }, "extends": ["eslint:recommended"], "parserOptions": { "ecmaVersion": 13, "sourceType": "module" }, "rules": { "no-console": "off", "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }], "prefer-const": "error", "no-var": "error", "eqeqeq": ["error", "always"], "curly": ["error", "all"], "brace-style": ["error", "1tbs"], "comma-dangle": ["error", "es5"], "quotes": ["error", "single"], "semi": ["error", "always"] } } ``` ### 代码复杂性 ```javascript // ✅ 好的: 低环路复杂度 (< 10) function processAgent(agent) { if (!agent.enabled) return null; const config = loadConfig(agent.configPath); const result = executeAgent(agent, config); return result; } // ❌ 不好: 高环路复杂度 function processAgent(agent) { if (agent.type === 'dev') { if (agent.mode === 'yolo') { if (agent.hasStory) { // ... 嵌套逻辑 } else { // ... 更多嵌套逻辑 } } else { // ... 更多分支 } } else if (agent.type === 'qa') { // ... 更多分支 } // ... 仍然更多复杂性 } ``` **重构复杂函数**: ```javascript // ✅ 好的: 提取辅助函数 function processAgent(agent) { if (!agent.enabled) return null; if (agent.type === 'dev') { return processDevAgent(agent); } if (agent.type === 'qa') { return processQaAgent(agent); } return processDefaultAgent(agent); } ``` ### DRY 原则 ```javascript // ✅ 好的: 可重用函数 function validateAndLoad(filePath, schema) { const content = fs.readFileSync(filePath, 'utf8'); const data = yaml.parse(content); if (!schema.validate(data)) { throw new Error(`Invalid schema: ${filePath}`); } return data; } const agent = validateAndLoad('agent.yaml', agentSchema); const task = validateAndLoad('task.yaml', taskSchema); // ❌ 不好: 重复代码 const agentContent = fs.readFileSync('agent.yaml', 'utf8'); const agentData = yaml.parse(agentContent); if (!agentSchema.validate(agentData)) { throw new Error('Invalid agent schema'); } const taskContent = fs.readFileSync('task.yaml', 'utf8'); const taskData = yaml.parse(taskContent); if (!taskSchema.validate(taskData)) { throw new Error('Invalid task schema'); } ``` --- ## 文档模式 ### JSDoc 注释 ```javascript /** * 加载并执行 AIOX 代理 * * @param {string} agentId - 代理的唯一标识符 * @param {Object} args - 代理执行参数 * @param {boolean} args.yoloMode - 启用自主模式 * @param {string} args.storyPath - 故事文件路径 (可选) * @param {number} [timeout=5000] - 执行超时 (毫秒) * @returns {Promise