mac@MacBookAir npm_yuangs % codebuddy ╭─── CodeBuddy Code v2.41.0 ─────────────────────────────────────────────────────────────────────────────────╮ │ │ Tips for getting started │ │ │ Press / to use commands, @ to mention files. │ │ │ Press Cmd + V to paste URLs, file paths, or images. │ │ ████ ████ │ Run /init to create a CODEBUDDY.md or AGENTS.md file with instruction… │ │ ████████████████ │ ────────────────────────────────────────────────────────────────────── │ │ ████ ████ │ Recent activity │ │ ████ ██ ██ ████ │ /model │ │ ████ ██ ██ ████ │ 我当前的模型路径是否可用,请测试yuangs router │ │ ████ ████ │ ────────────────────────────────────────────────────────────────────── │ │ ████████████████ │ GPT-5.1-Codex-Mini · external Usage Billing │ │ │ /Users/ygs/npm_yuangs │ │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─── CodeBuddy Code v2.41.0 ─────────────────────────────────────────────────────────────────────────────────╮ │ │ Tips for getting started │ │ │ Press / to use commands, @ to mention files. │ │ │ Press Cmd + V to paste URLs, file paths, or images. │ │ ████ ████ │ Press Esc twice to reset the input box. │ │ ████████████████ │ ────────────────────────────────────────────────────────────────────── │ │ ████ ████ │ Recent activity │ │ ████ ██ ██ ████ │ /model │ │ ████ ██ ██ ████ │ 我当前的模型路径是否可用,请测试yuangs router │ │ ████ ████ │ ────────────────────────────────────────────────────────────────────── │ │ ████████████████ │ GPT-5.1-Codex-Mini · external Usage Billing │ │ │ /Users/ygs/npm_yuangs │ │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ > /model ⎿ Switch model to gemini-3.0-pro > 详细分析@src/commands/git ⎿ Listed directory src/commands/git ● Explore I'll perform a detailed analysis of the src/commands/git directory. Let me start by exploring the structure and reading the key files. ● Explore Search(pattern: "src/commands/git/**/*") ⎿ Found 15 files (ctrl+o to expand) ● Explore Bash(ls -la /Users/ygs/npm_yuangs/src/commands/git) ⎿ total 248 drwxr-xr-x 17 mac staff 544 1 29 02:27 . drwxr-xr-x 21 mac staff 672 1 29 02:27 .. ...+16 line (ctrl+o to expand) ● Explore Now let me read all the key files to understand their functionality: ● Explore Read(src/commands/git/README.md) ⎿ Read 80 lines (ctrl+o to expand) ● Explore Read(src/commands/git/exec.ts) ⎿ Read 217 lines (ctrl+o to expand) ● Explore Read(src/commands/git/errors.ts) ⎿ Read 154 lines (ctrl+o to expand) ● Explore Read(src/commands/git/constants.ts) ⎿ Read 88 lines (ctrl+o to expand) ● Explore Read(src/commands/git/utils.ts) ⎿ Read 119 lines (ctrl+o to expand) ● Explore Now let me read the main command files: ● Explore Read(src/commands/git/auto.ts) ⎿ Read 320 lines (ctrl+o to expand) ● Explore Read(src/commands/git/commit.ts) ⎿ Read 92 lines (ctrl+o to expand) ● Explore Read(src/commands/git/smartCommit.ts) ⎿ Read 113 lines (ctrl+o to expand) ● Explore Read(src/commands/git/status.ts) ⎿ Read 75 lines (ctrl+o to expand) ● Explore Read(src/commands/git/semanticDiff.ts) ⎿ Read 54 lines (ctrl+o to expand) ● Explore Now let me read the remaining important files: ● Explore Read(src/commands/git/review.ts) ⎿ Read 573 lines (ctrl+o to expand) ● Explore Read(src/commands/git/plan.ts) ⎿ Read 298 lines (ctrl+o to expand) ● Explore Read(src/commands/git/resolve.ts) ⎿ Read 111 lines (ctrl+o to expand) ● Explore Read(src/commands/git/branch.ts) ⎿ Read 172 lines (ctrl+o to expand) ● Explore Read(src/commands/git/historySemantic.ts) ⎿ Read 69 lines (ctrl+o to expand) ● Explore Now I have a comprehensive understanding of the src/commands/git directory. Let me create a detailed analysis report in Chinese. --- src/commands/git 目录详细分析报告 一、整体架构概述 src/commands/git 目录是一个完整的 Git 智能化工具集，基于 AI 能力构建了一套现代化的 Git 工作流增强系统。该模块采用了关注点分离的设计原则，将命令逻辑、配置管理、工具函数和错误处理进行了清晰的模块化划分。 架构设计特点： 1. 命令与核心逻辑分离：命令文件（.ts）负责 CLI 交互，核心业务逻辑封装在 core/git/ 中 2. 共享模块复用：constants、utils、errors 作为横切关注点被所有命令共享 3. AI 驱动：深度集成 LLM 能力，实现代码审查、提交信息生成、冲突解决等智能化功能 4. 类型安全：使用 TypeScript 和自定义错误类型保证代码健壮性 5. 渐进式增强：支持从基础 Git 操作到高级 AI 辅助的平滑过渡 --- 二、文件结构与职责分析 1. 基础设施文件 /Users/ygs/npm_yuangs/src/commands/git/constants.ts 职责：集中管理模块配置常量 核心配置项： - DIFF_ESTIMATION：代码变更行数估算配置 - LINES_PER_FILE_DEFAULT: 50 - 基于统计的默认每文件估算行数 - LINES_PER_FILE_FALLBACK: 100 - numstat 失败时的后备估算值 - 数据来源：基于 100+ 真实项目的统计分析（2024-2025） - SECURITY_SCAN：安全扫描配置 - MAX_SCAN_FILES: 50 - 最大扫描文件数（性能优化） - MAX_CONCURRENT: 5 - 并发扫描数 - MAX_FILE_SIZE: 1MB - 最大文件大小限制 - CAPABILITY_LEVEL_DISPLAY：能力等级显示映射 - 支持 SEMANTIC、STRUCTURAL、LINE、TEXT、NONE 五个级别 设计亮点： - 支持通过环境变量覆盖默认值（如 YUANGS_DIFF_LINES_DEFAULT） - 包含数据来源和适用范围说明 - 实现参数验证（范围检查、类型检查） --- /Users/ygs/npm_yuangs/src/commands/git/utils.ts 职责：提供通用工具函数 核心函数： 1. cleanLLMOutput(content, strategy) - 清理 LLM 输出中的 Markdown fence 和对话式文本 - 支持保守模式（CONSERVATIVE）和宽松模式（LENIENT） - 适用场景：LLM 返回被包裹在 markdown ... 中的内容 2. deduplicateFiles(files) - 对文件列表去重，避免 staged 和 unstaged 重复计数 - 实现：基于 Set 数据结构 3. getCapabilityLevelDisplay(level) - 获取能力等级的显示名称 - 提供 fallback 处理（未知等级返回 UNKNOWN(N)） 设计亮点： - 清晰的注释说明适用场景和限制 - 预留扩展点（如 JSON/XML 格式检测） --- /Users/ygs/npm_yuangs/src/commands/git/errors.ts 职责：自定义错误类型，实现类型安全的错误处理 错误类层次： GitError (基类) ├── NoChangesFoundError - 未找到变更 ├── CommitNotFoundError - Commit 不存在 └── NoReviewContentError - 无审查内容 关键特性： - 携带结构化上下文（context、timestamp） - 提供类型保护函数（isGitError、isNoChangesFoundError 等） - getDetailedMessage() 格式化输出错误信息 - 修复原型链（Object.setPrototypeOf）确保 instanceof 正常工作 使用示例： throw new NoChangesFoundError('No staged changes', { commitRef: 'HEAD', files: ['src/index.ts'] }); --- 2. 核心命令文件 /Users/ygs/npm_yuangs/src/commands/git/exec.ts 职责：根据 todo.md 自动生成代码并执行任务 核心流程： 1. 解析 todo.md 中的未完成任务（- [ ] 格式） 2. 跳过元数据行（以 > 开头） 3. 构建 AI 提示，包含项目上下文和当前任务 4. 调用 LLM 生成代码实现 5. 解析生成的代码（通过 CodeGenerator） 6. 询问用户确认后写入文件 7. 更新 todo.md 任务状态（- [x]） 关键选项： - -f, --fromfile <file> - 指定 todo 文件路径 - -t, --task <number> - 执行指定编号的任务 - -m, --model <model> - 指定 AI 模型 设计亮点： - 保存原始 AI 输出（通过 saveRawOutput） - 支持任务编号选择 - 交互式确认机制 --- /Users/ygs/npm_yuangs/src/commands/git/commit.ts 职责：智能生成 commit message 并提交 核心流程： 1. 检查 Git 仓库和变更状态 2. 可选：暂存所有变更（--all） 3. 使用 CommitMessageGenerator 生成 message 4. 显示生成的 message 和变更统计 5. 执行 commit（支持 --dry-run） 关键选项： - -a, --all - 暂存所有变更 - -d, --detailed - 生成详细的 commit message - -t, --type <type> - 指定 commit 类型（feat/fix/docs 等） - --no-ai - 不使用 AI，使用规则生成 设计亮点： - 支持传统规则和 AI 两种生成模式 - 显示变更统计和提交哈希 --- /Users/ygs/npm_yuangs/src/commands/git/smartCommit.ts 职责：智能识别工作区逻辑块并进行分步提交 核心概念： - CommitGroup：逻辑相关的文件组，包含 id、title、files、suggestedMessage 核心流程： 1. 使用 SmartCommitManager 分析工作区变更 2. 基于逻辑相关性将文件分组 3. 为每个组生成独立的提交消息 4. 支持三种执行模式： - 全自动（-y）：直接执行所有提交 - 交互式（i）：逐个确认每个提交 - 取消（默认）：仅显示计划 关键选项： - -m, --model <model> - AI 模型选择 - -y, --yes - 自动执行所有提交 设计亮点： - 将大型变更拆分为多个原子提交 - 支持编辑提交消息（交互模式下） - 显示未分配文件的警告 --- /Users/ygs/npm_yuangs/src/commands/git/status.ts 职责：增强的 Git 状态显示 显示内容： 1. 分支信息： - 当前分支、上游分支 - 领先/落后提交数（↑/↓） 2. 变更统计： - 修改/新增/删除/未跟踪文件数量 - 工作区状态（干净/有变更） 3. 最近提交： - 最近 5 次提交的哈希、消息、作者、时间 设计亮点： - 彩色输出（绿色=正常，黄色=警告，红色=删除） - 使用 emoji 增强可读性（🌿 分支，📝 变更，📜 提交） - 并发获取数据（Promise.all） --- /Users/ygs/npm_yuangs/src/commands/git/semanticDiff.ts 职责：分析 Git 变更的语义级别差异（函数/类/接口） 核心能力： - 检测函数、类、接口、类型的增删 - 识别破坏性变更（Breaking Changes） - 按文件分组显示语义变更 显示内容： - 变更类型（+ 添加，- 删除） - 语义分类（FUNCTION、CLASS、INTERFACE 等） - 破坏性变更标记（红色 BREAKING 标签） 关键选项： - -u, --unstaged - 分析未暂存的变更 设计亮点： - 跳过纯行级修改，只显示显著的语义变更 - 自适应终端宽度 - 红色醒目标记破坏性变更 --- /Users/ygs/npm_yuangs/src/commands/git/review.ts 职责：AI 代码审查 核心流程： 1. 工作区审查模式（默认）： 1. 执行安全扫描（SecurityScanner） - 检测硬编码密钥、密码、令牌 - 并发扫描（限制 5 个） - 文件大小/数量限制（避免性能问题） 2. 调用 CodeReviewer 执行 AI 审查 3. 显示审查报告： - 评分（0-100）+ 置信度 - 问题列表（INFO/WARNING/ERROR/CRITICAL） - 优点和建议 4. 保存结果到 git_reviews.md 2. Commit 审查模式（--commit <hash>）： - 获取 commit 信息并审查其变更 - 跳过安全扫描（假设已提交代码已过审） 关键选项： - -l, --level <level> - 审查级别（quick/standard/deep） - -f, --file <file> - 审查特定文件 - -u, --unstaged - 审查未暂存变更 - -c, --commit <commit> - 审查指定 commit - --no-security - 跳过安全扫描 - --force - 忽略安全警告继续执行 审查级别降级机制： - 如果变更过多，自动从 deep 降级为 standard 设计亮点： - 双层防护（安全扫描 + AI 审查） - 结构化错误处理（使用自定义错误类型） - Markdown 格式保存审查历史 - 友好的用户提示（staged vs unstaged） --- /Users/ygs/npm_yuangs/src/commands/git/plan.ts 职责：AI 驱动的开发规划（双智能体协作） 核心创新：使用架构师 + 审查员双 AI 模型协作 核心流程： 1. 解析用户需求（优先级：CLI > todo.md > 默认值） 2. 获取 Git 上下文（最近 10 次提交） 3. 双智能体协作循环（默认 2 轮）： - 架构师起草初稿（Assistant 模型） - 审查员评审（gemini-2.5-flash-lite 模型） - 架构师修订方案（根据审查意见） 4. 生成最终 todo.md： - 计算任务复杂度（基于 diff 行数） - 添加能力等级元数据 - 使用 Markdown Checkbox 格式（- [ ]） 关键选项： - -r, --rounds <number> - 对话轮数（默认 2） - -m, --model <model> - 架构师模型 - --reviewer-model <model> - 审查员模型 元数据示例： > 📅 Generated by Yuangs Git Plan at 2026-01-29 > 🎯 Context: 添加用户认证功能 > 🔧 Capability Level: SEMANTIC > ⚙️ Estimated Time: 15000ms > 📊 Estimated Tokens: 5000 设计亮点： - 双模型博弈提升方案质量 - 使用 cleanLLMOutput 清理输出 - 元数据驱动的能力需求评估 - 去重文件列表（deduplicateFiles） --- /Users/ygs/npm_yuangs/src/commands/git/auto.ts 职责：自动执行 todo.md 中的任务（全流程自动化） 核心流程： 1. 初始化： - 解析 todo.md 中的所有任务 - 显示总体进度条 2. 任务执行循环（最多执行 N 个任务）： - 获取下一个未完成任务（getNextTask） - 采集项目上下文（ContextGatherer） - AI 生成代码（executeTask） - 备份文件（backupFiles） - 写入代码（writeGeneratedCode） - AI 质量审查（CodeReviewer） - 重试机制（最多 3 次尝试）： - 如果审查不通过，将反馈传递给下一次尝试 3. 完成后自动提交（可选，--commit）： - 生成 commit message（CommitMessageGenerator） - 执行 git commit 关键选项： - -n, --max-tasks <number> - 最大任务数（默认 5） - -m, --model <model> - AI 模型 - -s, --min-score <number> - 最低审查评分 - -l, --review-level <level> - 审查级别 - --skip-review - 跳过审查 - -o, --save-only - 只保存代码，不写入文件 - -c, --commit - 完成后自动提交 重试机制： - 最大尝试次数：3 次（MAX_RETRY_ATTEMPTS） - 将上一次的审查问题作为反馈传递给 AI 设计亮点： - 完整的 DevOps 闭环（规划 → 执行 → 审查 → 提交） - 任务状态管理（in_progress、done、failed） - 进度可视化（ProgressBar、ProgressManager） - 备份和回滚机制 - 上下文感知代码生成（ContextGatherer） --- /Users/ygs/npm_yuangs/src/commands/git/resolve.ts 职责：使用 AI 自动解决 Git 合并冲突 核心流程： 1. 检测冲突文件（getConflictedFiles） 2. 并发解决冲突（pLimit 限流） 3. 对每个文件： - 读取冲突内容 - 调用 ConflictResolver 使用 AI 生成解决方案 - 可选：生成备份文件（.bak） - 可选：自动执行 git add（--auto-add） 4. 显示解决结果统计 关键选项： - -m, --model <model> - AI 模型（需验证格式和白名单） - -a, --auto-add - 解决后自动 git add - --dry-run - 预览分析结果，不修改文件 - --no-backup - 不生成备份文件 - -c, --concurrency <number> - 并发处理数量（默认 2） 安全机制： - 模型名称校验（正则 + 白名单） - 备份文件生成 - Dry-run 模式 设计亮点： - 并发处理提升效率 - 生成备份文件保障安全 - 彩色输出显示处理进度 --- /Users/ygs/npm_yuangs/src/commands/git/branch.ts 职责：智能分支管理 子命令： 1. branch list（默认命令）： - 显示所有分支及元信息 - 当前分支标记（绿色 *） - 上游同步状态（↑/↓） - 工作区状态（dirty/clean） - 最新提交信息 2. branch switch <branch>： - 安全切换分支 - 校验： - 分支名称合法性（使用 Git 原生校验） - 分支是否存在 - 工作区是否干净（有未提交变更时拒绝切换） 3. branch suggest： - 使用 AI 分析当前 Git 上下文 - 提供分支操作建议： - stay：保持当前分支 - switch：切换到指定分支 - create：创建新分支 - 显示建议原因和置信度 安全机制： - 动态导入路径白名单（ALLOWED_IMPORTS） - 防止任意路径导入攻击 设计亮点： - 彩色输出增强可读性 - 统一的错误处理 - AI 辅助决策（BranchAdvisor） --- /Users/ygs/npm_yuangs/src/commands/git/historySemantic.ts 职责：结合代码结构分析 Git 提交历史，生成语义化报告 核心能力： - 解析最近 N 次提交 - 为每个提交生成： - 原始消息：Git commit message - 语义总结：AI 生成的描述 - 影响级别：low/medium/high/breaking - 结构变更：函数/类/接口的增删 - 生成整体趋势概览 关键选项： - -n, --count <number> - 分析的提交数量（默认 5） - -m, --model <model> - AI 模型 输出示例： a3b7f9c [BREAKING] 原始: fix: update API response 语义: 修改了 API 响应格式，破坏向后兼容性 结构: + function(handleResponse), - class(ResponseHandler) 设计亮点： - 使用 SemanticCommitParser 统一解析逻辑 - 彩色输出区分影响级别 - 显示前 3 个结构变更（避免输出过长） --- 三、核心设计模式与工具使用 1. exec.ts 的使用 exec.ts 不是一个工具函数文件，而是一个命令文件，负责实现 git exec 命令。它的核心作用是： - 解析 todo.md 中的任务 - 调用 AI 生成代码实现 - 解析并写入生成的代码 - 更新任务状态 关键依赖： - ../../agent/llm - LLM 调用 - ../../core/git/CodeGenerator - 代码解析和写入 - ../../core/git/TodoManager - 任务管理 --- 2. errors.ts 的错误处理模式 使用场景示例： // review.ts 中的使用 try { const result = await reviewer.review(level, !options.unstaged); } catch (error) { if (isNoReviewContentError(error)) { // 特定错误处理：未找到审查内容 const diff = await gitService.getDiff(); if (!options.unstaged && diff.files.unstaged.length > 0) { // 提示用户使用 --unstaged 选项 } } else if (isNoChangesFoundError(error)) { // 处理无变更错误 } else { // 通用错误处理 } } 优势： - 避免字符串匹配（如 error.message.includes('no changes')） - 类型安全（TypeScript 类型推断） - 携带结构化上下文 --- 3. 通用工具和库的使用 并发控制（p-limit） // review.ts 中的安全扫描 const limit = pLimit(SECURITY_SCAN.MAX_CONCURRENT); const scanPromises = files.map(file => limit(async () => { // 扫描逻辑 }) ); 进度显示（ora） const spinner = ora('正在分析...').start(); // ... 执行操作 spinner.succeed('分析完成'); spinner.fail('分析失败'); 彩色输出（chalk） console.log(chalk.green('✅ 成功')); console.log(chalk.yellow('⚠️ 警告')); console.log(chalk.red('❌ 错误')); --- 四、特定模式识别 1. 双智能体协作模式（plan.ts） 这是该模块的一个创新设计： // 架构师起草初稿 const draftRes = await runLLM({ model: ARCHITECT_MODEL, ... }); // 循环打磨 for (let i = 1; i <= maxRounds; i++) { // 审查员评审 const reviewRes = await runLLM({ model: REVIEWER_MODEL, ... }); // 架构师修正 const refineRes = await runLLM({ model: ARCHITECT_MODEL, ... }); } 优势： - 提升方案质量（通过多轮迭代） - 模拟真实团队协作 - 不同模型扮演不同角色（如 GPT-4 做架构师，Gemini 做审查员） --- 2. 重试 + 反馈循环（auto.ts） let attempts = 0; while (attempts <= MAX_RETRY_ATTEMPTS && !taskCompleted) { attempts++; // 获取上一次的审查反馈 const previousFeedback = attempts > 1 && nextTask.reviewIssues ? nextTask.reviewIssues.join('\n') : undefined; // 执行任务（带反馈） const { code } = await executeTask(nextTask, context, model, previousFeedback); // 审查 const review = await reviewCode(level); // 判断是否通过 if (review.score >= minScore) { taskCompleted = true; } } 优势： - 自动修复失败任务 - 将审查问题作为反馈传递给 AI --- 3. 安全扫描 + AI 审查双重防护（review.ts） // 1. 安全扫描（并发扫描，限流） const scanResult = await performSecurityScan(gitService, securityScanner, files, options); if (scanResult.hasIssues && !scanResult.shouldContinue) { return; // 发现安全问题，中止 } // 2. AI 代码审查 const result = await reviewer.review(level, !options.unstaged); 优势： - 第一层：检测硬编码密钥（静态分析） - 第二层：检测代码质量问题（AI 审查） --- 五、模块能力总结 核心能力清单： 1. 智能提交管理： - 自动生成 commit message（commit.ts） - 分步提交（smartCommit.ts） - 语义化提交历史分析（historySemantic.ts） 2. AI 驱动开发： - 双智能体规划（plan.ts） - 自动执行任务（auto.ts） - 代码生成（exec.ts） 3. 代码质量保障： - AI 代码审查（review.ts） - 安全扫描（SecurityScanner） - 语义级 diff 分析（semanticDiff.ts） 4. 冲突解决： - AI 自动解决合并冲突（resolve.ts） 5. 分支管理： - 增强的分支列表（branch.ts list） - 安全切换（branch.ts switch） - AI 分支建议（branch.ts suggest） 6. 状态监控： - 增强的 Git 状态显示（status.ts） --- 技术栈： CLI 框架： - commander - 命令行解析 - ora - 进度显示 - chalk - 彩色输出 - readline - 交互式输入 并发控制： - p-limit - 限流 AI 集成： - ../../agent/llm - 统一 LLM 调用接口 - 支持多模型（Assistant、Gemini 等） 核心服务： - GitService - Git 操作封装 - CodeReviewer - 代码审查 - SecurityScanner - 安全扫描 - CommitMessageGenerator - 提交消息生成 - SmartCommitManager - 分步提交管理 - ConflictResolver - 冲突解决 --- 六、最佳实践与设计原则 1. 关注点分离： - 命令文件负责 CLI 交互 - 核心逻辑封装在 core/ 中 - 共享模块（constants、utils、errors）横向复用 2. 可维护性： - 常量集中管理（constants.ts） - 避免魔法数字 - 详细的注释和文档 3. 可复用性： - 提取通用逻辑为工具函数（utils.ts） - 自定义错误类型（errors.ts） 4. 类型安全： - 使用 TypeScript - 自定义错误类型保证类型推断 5. 可测试性： - 函数职责单一 - 依赖注入（如传递 gitService） 6. 性能优化： - 并发处理（p-limit） - 文件大小/数量限制 - 使用 Promise.all 并行获取数据 7. 用户体验： - 彩色输出和 emoji - 进度条和 spinner - 友好的错误提示 - Dry-run 模式 --- 七、扩展性分析 已实现的扩展点： 1. 环境变量覆盖（constants.ts）： - YUANGS_DIFF_LINES_DEFAULT - YUANGS_SCAN_MAX_FILES - 等... 2. LLM 输出清理策略（utils.ts）： - CleanStrategy.CONSERVATIVE - CleanStrategy.LENIENT 3. 审查级别（review.ts）： - ReviewLevel.QUICK - ReviewLevel.STANDARD - ReviewLevel.DEEP 4. 能力等级（plan.ts）： - SEMANTIC - STRUCTURAL - LINE - TEXT - NONE 未来可扩展方向： 1. utils.ts： - 添加 JSON/XML 格式清理 - 支持自定义清理规则 2. errors.ts： - 添加更多特定错误类型 - 错误统计和日志 3. review.ts： - 支持自定义审查规则 - 集成更多安全扫描器 4. auto.ts： - 支持任务依赖关系 - 并行执行独立任务 --- 八、总结 src/commands/git 目录是一个设计精良、功能完整的 Git 智能化工具集。它通过 AI 能力深度增强了 Git 工作流，实现了从规划、开发、审查到提交的全流程自动化。 核心优势： - 🎯 双智能体协作：架构师 + 审查员模式提升方案质量 - 🔒 双重安全防护：静态扫描 + AI 审查 - 🔄 重试 + 反馈循环：自动修复失败任务 - 📊 进度可视化：实时显示执行进度 - 🛡️ 类型安全：自定义错误类型 + TypeScript - 🚀 高性能：并发处理 + 限流控制 代码质量： - ✅ 关注点分离 - ✅ 高度模块化 - ✅ 详细注释 - ✅ 统一错误处理 - ✅ 友好的用户体验 该模块可作为 AI 驱动 CLI 工具的最佳实践参考。 ● Explore Now I have a comprehensive understanding of the src/commands/git directory. Let me create a detailed analysis report in Chinese. --- src/commands/git 目录详细分析报告 一、整体架构概述 src/commands/git 目录是一个完整的 Git 智能化工具集，基于 AI 能力构建了一套现代化的 Git 工作流增强系统。该模块采用了关注点分离的设计原则，将命令逻辑、配置管理、工具函数和错误处理进行了清晰的模块化划分。 架构设计特点： 1. 命令与核心逻辑分离：命令文件（.ts）负责 CLI 交互，核心业务逻辑封装在 core/git/ 中 2. 共享模块复用：constants、utils、errors 作为横切关注点被所有命令共享 3. AI 驱动：深度集成 LLM 能力，实现代码审查、提交信息生成、冲突解决等智能化功能 4. 类型安全：使用 TypeScript 和自定义错误类型保证代码健壮性 5. 渐进式增强：支持从基础 Git 操作到高级 AI 辅助的平滑过渡 --- 二、文件结构与职责分析 1. 基础设施文件 /Users/ygs/npm_yuangs/src/commands/git/constants.ts 职责：集中管理模块配置常量 核心配置项： - DIFF_ESTIMATION：代码变更行数估算配置 - LINES_PER_FILE_DEFAULT: 50 - 基于统计的默认每文件估算行数 - LINES_PER_FILE_FALLBACK: 100 - numstat 失败时的后备估算值 - 数据来源：基于 100+ 真实项目的统计分析（2024-2025） - SECURITY_SCAN：安全扫描配置 - MAX_SCAN_FILES: 50 - 最大扫描文件数（性能优化） - MAX_CONCURRENT: 5 - 并发扫描数 - MAX_FILE_SIZE: 1MB - 最大文件大小限制 - CAPABILITY_LEVEL_DISPLAY：能力等级显示映射 - 支持 SEMANTIC、STRUCTURAL、LINE、TEXT、NONE 五个级别 设计亮点： - 支持通过环境变量覆盖默认值（如 YUANGS_DIFF_LINES_DEFAULT） - 包含数据来源和适用范围说明 - 实现参数验证（范围检查、类型检查） --- /Users/ygs/npm_yuangs/src/commands/git/utils.ts 职责：提供通用工具函数 核心函数： 1. cleanLLMOutput(content, strategy) - 清理 LLM 输出中的 Markdown fence 和对话式文本 - 支持保守模式（CONSERVATIVE）和宽松模式（LENIENT） - 适用场景：LLM 返回被包裹在 markdown ... 中的内容 2. deduplicateFiles(files) - 对文件列表去重，避免 staged 和 unstaged 重复计数 - 实现：基于 Set 数据结构 3. getCapabilityLevelDisplay(level) - 获取能力等级的显示名称 - 提供 fallback 处理（未知等级返回 UNKNOWN(N)） 设计亮点： - 清晰的注释说明适用场景和限制 - 预留扩展点（如 JSON/XML 格式检测） --- /Users/ygs/npm_yuangs/src/commands/git/errors.ts 职责：自定义错误类型，实现类型安全的错误处理 错误类层次： GitError (基类) ├── NoChangesFoundError - 未找到变更 ├── CommitNotFoundError - Commit 不存在 └── NoReviewContentError - 无审查内容 关键特性： - 携带结构化上下文（context、timestamp） - 提供类型保护函数（isGitError、isNoChangesFoundError 等） - getDetailedMessage() 格式化输出错误信息 - 修复原型链（Object.setPrototypeOf）确保 instanceof 正常工作 使用示例： throw new NoChangesFoundError('No staged changes', { commitRef: 'HEAD', files: ['src/index.ts'] }); --- 2. 核心命令文件 /Users/ygs/npm_yuangs/src/commands/git/exec.ts 职责：根据 todo.md 自动生成代码并执行任务 核心流程： 1. 解析 todo.md 中的未完成任务（- [ ] 格式） 2. 跳过元数据行（以 > 开头） 3. 构建 AI 提示，包含项目上下文和当前任务 4. 调用 LLM 生成代码实现 5. 解析生成的代码（通过 CodeGenerator） 6. 询问用户确认后写入文件 7. 更新 todo.md 任务状态（- [x]） 关键选项： - -f, --fromfile <file> - 指定 todo 文件路径 - -t, --task <number> - 执行指定编号的任务 - -m, --model <model> - 指定 AI 模型 设计亮点： - 保存原始 AI 输出（通过 saveRawOutput） - 支持任务编号选择 - 交互式确认机制 --- /Users/ygs/npm_yuangs/src/commands/git/commit.ts 职责：智能生成 commit message 并提交 核心流程： 1. 检查 Git 仓库和变更状态 2. 可选：暂存所有变更（--all） 3. 使用 CommitMessageGenerator 生成 message 4. 显示生成的 message 和变更统计 5. 执行 commit（支持 --dry-run） 关键选项： - -a, --all - 暂存所有变更 - -d, --detailed - 生成详细的 commit message - -t, --type <type> - 指定 commit 类型（feat/fix/docs 等） - --no-ai - 不使用 AI，使用规则生成 设计亮点： - 支持传统规则和 AI 两种生成模式 - 显示变更统计和提交哈希 --- /Users/ygs/npm_yuangs/src/commands/git/smartCommit.ts 职责：智能识别工作区逻辑块并进行分步提交 核心概念： - CommitGroup：逻辑相关的文件组，包含 id、title、files、suggestedMessage 核心流程： 1. 使用 SmartCommitManager 分析工作区变更 2. 基于逻辑相关性将文件分组 3. 为每个组生成独立的提交消息 4. 支持三种执行模式： - 全自动（-y）：直接执行所有提交 - 交互式（i）：逐个确认每个提交 - 取消（默认）：仅显示计划 关键选项： - -m, --model <model> - AI 模型选择 - -y, --yes - 自动执行所有提交 设计亮点： - 将大型变更拆分为多个原子提交 - 支持编辑提交消息（交互模式下） - 显示未分配文件的警告 --- /Users/ygs/npm_yuangs/src/commands/git/status.ts 职责：增强的 Git 状态显示 显示内容： 1. 分支信息： - 当前分支、上游分支 - 领先/落后提交数（↑/↓） 2. 变更统计： - 修改/新增/删除/未跟踪文件数量 - 工作区状态（干净/有变更） 3. 最近提交： - 最近 5 次提交的哈希、消息、作者、时间 设计亮点： - 彩色输出（绿色=正常，黄色=警告，红色=删除） - 使用 emoji 增强可读性（🌿 分支，📝 变更，📜 提交） - 并发获取数据（Promise.all） --- /Users/ygs/npm_yuangs/src/commands/git/semanticDiff.ts 职责：分析 Git 变更的语义级别差异（函数/类/接口） 核心能力： - 检测函数、类、接口、类型的增删 - 识别破坏性变更（Breaking Changes） - 按文件分组显示语义变更 显示内容： - 变更类型（+ 添加，- 删除） - 语义分类（FUNCTION、CLASS、INTERFACE 等） - 破坏性变更标记（红色 BREAKING 标签） 关键选项： - -u, --unstaged - 分析未暂存的变更 设计亮点： - 跳过纯行级修改，只显示显著的语义变更 - 自适应终端宽度 - 红色醒目标记破坏性变更 --- /Users/ygs/npm_yuangs/src/commands/git/review.ts 职责：AI 代码审查 核心流程： 1. 工作区审查模式（默认）： 1. 执行安全扫描（SecurityScanner） - 检测硬编码密钥、密码、令牌 - 并发扫描（限制 5 个） - 文件大小/数量限制（避免性能问题） 2. 调用 CodeReviewer 执行 AI 审查 3. 显示审查报告： - 评分（0-100）+ 置信度 - 问题列表（INFO/WARNING/ERROR/CRITICAL） - 优点和建议 4. 保存结果到 git_reviews.md 2. Commit 审查模式（--commit <hash>）： - 获取 commit 信息并审查其变更 - 跳过安全扫描（假设已提交代码已过审） 关键选项： - -l, --level <level> - 审查级别（quick/standard/deep） - -f, --file <file> - 审查特定文件 - -u, --unstaged - 审查未暂存变更 - -c, --commit <commit> - 审查指定 commit - --no-security - 跳过安全扫描 - --force - 忽略安全警告继续执行 审查级别降级机制： - 如果变更过多，自动从 deep 降级为 standard 设计亮点： - 双层防护（安全扫描 + AI 审查） - 结构化错误处理（使用自定义错误类型） - Markdown 格式保存审查历史 - 友好的用户提示（staged vs unstaged） --- /Users/ygs/npm_yuangs/src/commands/git/plan.ts 职责：AI 驱动的开发规划（双智能体协作） 核心创新：使用架构师 + 审查员双 AI 模型协作 核心流程： 1. 解析用户需求（优先级：CLI > todo.md > 默认值） 2. 获取 Git 上下文（最近 10 次提交） 3. 双智能体协作循环（默认 2 轮）： - 架构师起草初稿（Assistant 模型） - 审查员评审（gemini-2.5-flash-lite 模型） - 架构师修订方案（根据审查意见） 4. 生成最终 todo.md： - 计算任务复杂度（基于 diff 行数） - 添加能力等级元数据 - 使用 Markdown Checkbox 格式（- [ ]） 关键选项： - -r, --rounds <number> - 对话轮数（默认 2） - -m, --model <model> - 架构师模型 - --reviewer-model <model> - 审查员模型 元数据示例： > 📅 Generated by Yuangs Git Plan at 2026-01-29 > 🎯 Context: 添加用户认证功能 > 🔧 Capability Level: SEMANTIC > ⚙️ Estimated Time: 15000ms > 📊 Estimated Tokens: 5000 设计亮点： - 双模型博弈提升方案质量 - 使用 cleanLLMOutput 清理输出 - 元数据驱动的能力需求评估 - 去重文件列表（deduplicateFiles） --- /Users/ygs/npm_yuangs/src/commands/git/auto.ts 职责：自动执行 todo.md 中的任务（全流程自动化） 核心流程： 1. 初始化： - 解析 todo.md 中的所有任务 - 显示总体进度条 2. 任务执行循环（最多执行 N 个任务）： - 获取下一个未完成任务（getNextTask） - 采集项目上下文（ContextGatherer） - AI 生成代码（executeTask） - 备份文件（backupFiles） - 写入代码（writeGeneratedCode） - AI 质量审查（CodeReviewer） - 重试机制（最多 3 次尝试）： - 如果审查不通过，将反馈传递给下一次尝试 3. 完成后自动提交（可选，--commit）： - 生成 commit message（CommitMessageGenerator） - 执行 git commit 关键选项： - -n, --max-tasks <number> - 最大任务数（默认 5） - -m, --model <model> - AI 模型 - -s, --min-score <number> - 最低审查评分 - -l, --review-level <level> - 审查级别 - --skip-review - 跳过审查 - -o, --save-only - 只保存代码，不写入文件 - -c, --commit - 完成后自动提交 重试机制： - 最大尝试次数：3 次（MAX_RETRY_ATTEMPTS） - 将上一次的审查问题作为反馈传递给 AI 设计亮点： - 完整的 DevOps 闭环（规划 → 执行 → 审查 → 提交） - 任务状态管理（in_progress、done、failed） - 进度可视化（ProgressBar、ProgressManager） - 备份和回滚机制 - 上下文感知代码生成（ContextGatherer） --- /Users/ygs/npm_yuangs/src/commands/git/resolve.ts 职责：使用 AI 自动解决 Git 合并冲突 核心流程： 1. 检测冲突文件（getConflictedFiles） 2. 并发解决冲突（pLimit 限流） 3. 对每个文件： - 读取冲突内容 - 调用 ConflictResolver 使用 AI 生成解决方案 - 可选：生成备份文件（.bak） - 可选：自动执行 git add（--auto-add） 4. 显示解决结果统计 关键选项： - -m, --model <model> - AI 模型（需验证格式和白名单） - -a, --auto-add - 解决后自动 git add - --dry-run - 预览分析结果，不修改文件 - --no-backup - 不生成备份文件 - -c, --concurrency <number> - 并发处理数量（默认 2） 安全机制： - 模型名称校验（正则 + 白名单） - 备份文件生成 - Dry-run 模式 设计亮点： - 并发处理提升效率 - 生成备份文件保障安全 - 彩色输出显示处理进度 --- /Users/ygs/npm_yuangs/src/commands/git/branch.ts 职责：智能分支管理 子命令： 1. branch list（默认命令）： - 显示所有分支及元信息 - 当前分支标记（绿色 *） - 上游同步状态（↑/↓） - 工作区状态（dirty/clean） - 最新提交信息 2. branch switch <branch>： - 安全切换分支 - 校验： - 分支名称合法性（使用 Git 原生校验） - 分支是否存在 - 工作区是否干净（有未提交变更时拒绝切换） 3. branch suggest： - 使用 AI 分析当前 Git 上下文 - 提供分支操作建议： - stay：保持当前分支 - switch：切换到指定分支 - create：创建新分支 - 显示建议原因和置信度 安全机制： - 动态导入路径白名单（ALLOWED_IMPORTS） - 防止任意路径导入攻击 设计亮点： - 彩色输出增强可读性 - 统一的错误处理 - AI 辅助决策（BranchAdvisor） --- /Users/ygs/npm_yuangs/src/commands/git/historySemantic.ts 职责：结合代码结构分析 Git 提交历史，生成语义化报告 核心能力： - 解析最近 N 次提交 - 为每个提交生成： - 原始消息：Git commit message - 语义总结：AI 生成的描述 - 影响级别：low/medium/high/breaking - 结构变更：函数/类/接口的增删 - 生成整体趋势概览 关键选项： - -n, --count <number> - 分析的提交数量（默认 5） - -m, --model <model> - AI 模型 输出示例： a3b7f9c [BREAKING] 原始: fix: update API response 语义: 修改了 API 响应格式，破坏向后兼容性 结构: + function(handleResponse), - class(ResponseHandler) 设计亮点： - 使用 SemanticCommitParser 统一解析逻辑 - 彩色输出区分影响级别 - 显示前 3 个结构变更（避免输出过长） --- 三、核心设计模式与工具使用 1. exec.ts 的使用 exec.ts 不是一个工具函数文件，而是一个命令文件，负责实现 git exec 命令。它的核心作用是： - 解析 todo.md 中的任务 - 调用 AI 生成代码实现 - 解析并写入生成的代码 - 更新任务状态 关键依赖： - ../../agent/llm - LLM 调用 - ../../core/git/CodeGenerator - 代码解析和写入 - ../../core/git/TodoManager - 任务管理 --- 2. errors.ts 的错误处理模式 使用场景示例： // review.ts 中的使用 try { const result = await reviewer.review(level, !options.unstaged); } catch (error) { if (isNoReviewContentError(error)) { // 特定错误处理：未找到审查内容 const diff = await gitService.getDiff(); if (!options.unstaged && diff.files.unstaged.length > 0) { // 提示用户使用 --unstaged 选项 } } else if (isNoChangesFoundError(error)) { // 处理无变更错误 } else { // 通用错误处理 } } 优势： - 避免字符串匹配（如 error.message.includes('no changes')） - 类型安全（TypeScript 类型推断） - 携带结构化上下文 --- 3. 通用工具和库的使用 并发控制（p-limit） // review.ts 中的安全扫描 const limit = pLimit(SECURITY_SCAN.MAX_CONCURRENT); const scanPromises = files.map(file => limit(async () => { // 扫描逻辑 }) ); 进度显示（ora） const spinner = ora('正在分析...').start(); // ... 执行操作 spinner.succeed('分析完成'); spinner.fail('分析失败'); 彩色输出（chalk） console.log(chalk.green('✅ 成功')); console.log(chalk.yellow('⚠️ 警告')); console.log(chalk.red('❌ 错误')); --- 四、特定模式识别 1. 双智能体协作模式（plan.ts） 这是该模块的一个创新设计： // 架构师起草初稿 const draftRes = await runLLM({ model: ARCHITECT_MODEL, ... }); // 循环打磨 for (let i = 1; i <= maxRounds; i++) { // 审查员评审 const reviewRes = await runLLM({ model: REVIEWER_MODEL, ... }); // 架构师修正 const refineRes = await runLLM({ model: ARCHITECT_MODEL, ... }); } 优势： - 提升方案质量（通过多轮迭代） - 模拟真实团队协作 - 不同模型扮演不同角色（如 GPT-4 做架构师，Gemini 做审查员） --- 2. 重试 + 反馈循环（auto.ts） let attempts = 0; while (attempts <= MAX_RETRY_ATTEMPTS && !taskCompleted) { attempts++; // 获取上一次的审查反馈 const previousFeedback = attempts > 1 && nextTask.reviewIssues ? nextTask.reviewIssues.join('\n') : undefined; // 执行任务（带反馈） const { code } = await executeTask(nextTask, context, model, previousFeedback); // 审查 const review = await reviewCode(level); // 判断是否通过 if (review.score >= minScore) { taskCompleted = true; } } 优势： - 自动修复失败任务 - 将审查问题作为反馈传递给 AI --- 3. 安全扫描 + AI 审查双重防护（review.ts） // 1. 安全扫描（并发扫描，限流） const scanResult = await performSecurityScan(gitService, securityScanner, files, options); if (scanResult.hasIssues && !scanResult.shouldContinue) { return; // 发现安全问题，中止 } // 2. AI 代码审查 const result = await reviewer.review(level, !options.unstaged); 优势： - 第一层：检测硬编码密钥（静态分析） - 第二层：检测代码质量问题（AI 审查） --- 五、模块能力总结 核心能力清单： 1. 智能提交管理： - 自动生成 commit message（commit.ts） - 分步提交（smartCommit.ts） - 语义化提交历史分析（historySemantic.ts） 2. AI 驱动开发： - 双智能体规划（plan.ts） - 自动执行任务（auto.ts） - 代码生成（exec.ts） 3. 代码质量保障： - AI 代码审查（review.ts） - 安全扫描（SecurityScanner） - 语义级 diff 分析（semanticDiff.ts） 4. 冲突解决： - AI 自动解决合并冲突（resolve.ts） 5. 分支管理： - 增强的分支列表（branch.ts list） - 安全切换（branch.ts switch） - AI 分支建议（branch.ts suggest） 6. 状态监控： - 增强的 Git 状态显示（status.ts） --- 技术栈： CLI 框架： - commander - 命令行解析 - ora - 进度显示 - chalk - 彩色输出 - readline - 交互式输入 并发控制： - p-limit - 限流 AI 集成： - ../../agent/llm - 统一 LLM 调用接口 - 支持多模型（Assistant、Gemini 等） 核心服务： - GitService - Git 操作封装 - CodeReviewer - 代码审查 - SecurityScanner - 安全扫描 - CommitMessageGenerator - 提交消息生成 - SmartCommitManager - 分步提交管理 - ConflictResolver - 冲突解决 --- 六、最佳实践与设计原则 1. 关注点分离： - 命令文件负责 CLI 交互 - 核心逻辑封装在 core/ 中 - 共享模块（constants、utils、errors）横向复用 2. 可维护性： - 常量集中管理（constants.ts） - 避免魔法数字 - 详细的注释和文档 3. 可复用性： - 提取通用逻辑为工具函数（utils.ts） - 自定义错误类型（errors.ts） 4. 类型安全： - 使用 TypeScript - 自定义错误类型保证类型推断 5. 可测试性： - 函数职责单一 - 依赖注入（如传递 gitService） 6. 性能优化： - 并发处理（p-limit） - 文件大小/数量限制 - 使用 Promise.all 并行获取数据 7. 用户体验： - 彩色输出和 emoji - 进度条和 spinner - 友好的错误提示 - Dry-run 模式 --- 七、扩展性分析 已实现的扩展点： 1. 环境变量覆盖（constants.ts）： - YUANGS_DIFF_LINES_DEFAULT - YUANGS_SCAN_MAX_FILES - 等... 2. LLM 输出清理策略（utils.ts）： - CleanStrategy.CONSERVATIVE - CleanStrategy.LENIENT 3. 审查级别（review.ts）： - ReviewLevel.QUICK - ReviewLevel.STANDARD - ReviewLevel.DEEP 4. 能力等级（plan.ts）： - SEMANTIC - STRUCTURAL - LINE - TEXT - NONE 未来可扩展方向： 1. utils.ts： - 添加 JSON/XML 格式清理 - 支持自定义清理规则 2. errors.ts： - 添加更多特定错误类型 - 错误统计和日志 3. review.ts： - 支持自定义审查规则 - 集成更多安全扫描器 4. auto.ts： - 支持任务依赖关系 - 并行执行独立任务 --- 八、总结 src/commands/git 目录是一个设计精良、功能完整的 Git 智能化工具集。它通过 AI 能力深度增强了 Git 工作流，实现了从规划、开发、审查到提交的全流程自动化。 核心优势： - 🎯 双智能体协作：架构师 + 审查员模式提升方案质量 - 🔒 双重安全防护：静态扫描 + AI 审查 - 🔄 重试 + 反馈循环：自动修复失败任务 - 📊 进度可视化：实时显示执行进度 - 🛡️ 类型安全：自定义错误类型 + TypeScript - 🚀 高性能：并发处理 + 限流控制 代码质量： - ✅ 关注点分离 - ✅ 高度模块化 - ✅ 详细注释 - ✅ 统一错误处理 - ✅ 友好的用户体验 该模块可作为 AI 驱动 CLI 工具的最佳实践参考。 ● 我已完成对 src/commands/git 目录的详细分析。以下是核心要点： 📋 模块概述 这是一个完整的 Git 智能化工具集，通过 AI 能力深度增强了开发工作流，涵盖从规划、开发、审查到提交的全生命周期。 🗂️ 核心文件职责 基础设施 - constants.ts: 配置管理（diff 估算、安全扫描、能力等级等） - utils.ts: 通用工具（LLM 输出清理、去重、显示名称映射） - errors.ts: 自定义错误类型体系（GitError、NoChangesFoundError 等） 核心命令 - commit.ts: 智能生成 commit message 并提交 - smartCommit.ts: 将变更拆分为多个逻辑提交组 - status.ts: 增强的状态显示（分支/变更/最近提交） - semanticDiff.ts: 语义级 diff 分析（函数/类/接口变更） - review.ts: 双重防护（安全扫描 + AI 代码审查） AI 驱动功能 - plan.ts: 🌟 双智能体协作（架构师+审查员）生成开发规划 - exec.ts: 根据 todo.md 自动生成代码 - auto.ts: 🚀 全自动化流程（执行→审查→重试→提交） - resolve.ts: AI 自动解决 Git 合并冲突 - branch.ts: 智能分支管理（列表/切换/AI 建议） - historySemantic.ts: 语义化历史分析 🎯 核心设计模式 1. 双智能体协作（plan.ts） 架构师起草初稿 → 审查员评审 → 架构师修订 → 循环迭代 2. 重试+反馈循环（auto.ts） 执行任务 → AI审查 → 失败？→ 将问题反馈给AI → 重新执行（最多3次） 3. 双重安全防护（review.ts） 第一层：静态扫描（硬编码密钥） → 第二层：AI代码审查（质量问题） ⚡ 技术亮点 - 并发控制: 使用 p-limit 限流（如安全扫描、冲突解决） - 类型安全: 自定义错误类型 + TypeScript - 进度可视化: ora spinner + ProgressBar - 友好交互: chalk 彩色输出 + emoji - 性能优化: Promise.all 并行获取数据，文件大小/数量限制 💡 使用场景示例 # 智能提交 yuangs git commit --all --detailed # 双智能体规划（2轮迭代） yuangs git plan -r 2 # 全自动执行（最多5个任务，完成后自动提交） yuangs git auto -n 5 --commit # 双重防护代码审查（深度级别） yuangs git review -l deep # AI 解决冲突（并发处理3个文件） yuangs git resolve -c 3 --auto-add 完整分析报告已包含架构设计、核心流程、安全机制、扩展性分析等内容。 > 分析 core/git 目录的实现细节 ● Explore I'll perform a detailed analysis of the src/core/git directory. Let me start by exploring the structure and then analyzing the key files. ● Explore Search(pattern: "src/core/git/**/*") ⎿ Found 18 files (ctrl+o to expand) ● Explore Bash(find /Users/ygs/npm_yuangs/src/core/git -type f -name "*.ts" -o -name "*.js" -o -name "*.json" | head -50) ⎿ /Users/ygs/npm_yuangs/src/core/git/ContextGatherer.ts /Users/ygs/npm_yuangs/src/core/git/CodeReviewer.ts /Users/ygs/npm_yuangs/src/core/git/CommitMessageGenerator.ts ...+16 line (ctrl+o to expand) ● Explore Now let me read all the key service files: ● Explore Read(src/core/git/GitService.ts) ⎿ Read 572 lines (ctrl+o to expand) ● Explore Read(src/core/git/CodeReviewer.ts) ⎿ Read 499 lines (ctrl+o to expand) ● Explore Read(src/core/git/CommitMessageGenerator.ts) ⎿ Read 275 lines (ctrl+o to expand) ● Explore Read(src/core/git/constants.ts) ⎿ Read 40 lines (ctrl+o to expand) ● Explore Read(src/core/git/ConflictResolver.ts) ⎿ Read 146 lines (ctrl+o to expand) ● Explore Now let me read more key files: ● Explore Read(src/core/git/GitContextAggregator.ts) ⎿ Read 76 lines (ctrl+o to expand) ● Explore Read(src/core/git/BranchAdvisor.ts) ⎿ Read 233 lines (ctrl+o to expand) ● Explore Read(src/core/git/SmartCommitManager.ts) ⎿ Read 156 lines (ctrl+o to expand) ● Explore Read(src/core/git/TodoManager.ts) ⎿ Read 358 lines (ctrl+o to expand) ● Explore Read(src/core/git/ProgressManager.ts) ⎿ Read 210 lines (ctrl+o to expand) ● Explore Now let me read the remaining important files: ● Explore Read(src/core/git/ContextGatherer.ts) ⎿ Read 235 lines (ctrl+o to expand) ● Explore Read(src/core/git/CodeGenerator.ts) ⎿ Read 287 lines (ctrl+o to expand) ● Explore Read(src/core/git/ErrorHandler.ts) ⎿ Read 224 lines (ctrl+o to expand) ● Explore Read(src/core/git/GitConfigManager.ts) ⎿ Read 315 lines (ctrl+o to expand) ● Explore Read(src/core/git/semantic/types.ts) ⎿ Read 34 lines (ctrl+o to expand) ● Explore Read(src/core/git/semantic/SemanticDiffEngine.ts) ⎿ Read 167 lines (ctrl+o to expand) ● Explore Read(src/core/git/semantic/SemanticCommitParser.ts) ⎿ Read 97 lines (ctrl+o to expand) ● Explore Read(src/core/git/semantic/historyTypes.ts) ⎿ Read 17 lines (ctrl+o to expand) ● Explore Perfect! Now I have a comprehensive understanding of the src/core/git directory. Let me compile a detailed analysis report in Chinese. --- src/core/git 目录详细分析报告 1. 文件结构清单 src/core/git/ ├── GitService.ts # Git 核心服务层 ├── CodeReviewer.ts # AI 代码审查器 ├── CommitMessageGenerator.ts # 提交消息生成器 ├── ConflictResolver.ts # 冲突智能解决器 ├── GitContextAggregator.ts # Git 上下文聚合器 ├── BranchAdvisor.ts # 分支建议顾问 ├── SmartCommitManager.ts # 智能提交管理器 ├── TodoManager.ts # Todo 任务管理器 ├── ProgressManager.ts # 工作流进度管理器 ├── ContextGatherer.ts # 项目上下文采集器 ├── CodeGenerator.ts # 代码生成与解析模块 ├── ErrorHandler.ts # 错误处理与重试机制 ├── GitConfigManager.ts # Git 工作流配置管理 ├── constants.ts # 模块常量定义 └── semantic/ # 语义分析子模块 ├── types.ts # 语义类型定义 ├── SemanticDiffEngine.ts # 语义差异分析引擎 ├── SemanticCommitParser.ts # 语义提交解析器 └── historyTypes.ts # 历史分析类型 --- 2. 核心服务类详细分析 2.1 GitService.ts - Git 底层操作服务 核心职责：封装所有 Git 命令行操作，提供类型安全的 API 关键算法与实现： 2.1.1 安全执行机制 private async exec(command: string): Promise<string> async execSafe(command: string): Promise<string | null> - 双模式执行：exec 抛出异常，execSafe 返回 null - 缓冲区优化：maxBuffer: 10MB 处理大型 diff - 统一错误处理：包装为 GitError 并附带修复建议 2.1.2 Diff 统计算法 async getDiffNumstat(): Promise<GitNumstat> - 使用 git diff --numstat 获取精确的行数统计 - 分别处理 staged 和 unstaged 的变更 - 正确解析包含空格的文件名（使用 parts.slice(2).join(' ')） 2.1.3 分支信息获取 async getBranches(): Promise<{...}> - 使用 git for-each-ref 获取详细信息 - 自定义格式字符串解析 upstream tracking 关系 - 正则提取 ahead/behind 数量：track.match(/ahead (\d+)/) 2.1.4 安全提交机制 async commit(message: string): Promise<string> - 关键设计：使用 spawn + stdin 而非命令行参数传递消息 - 原因：避免 shell escaping 问题，支持多行消息 - 流程：git commit -F - + pipe message via stdin 2.1.5 语义 Diff 集成 async getSemanticDiff(staged: boolean): Promise<SemanticDiffResult | null> - 集成 SemanticDiffEngine 进行结构化分析 - 识别函数、类、接口级别的变更 设计模式： - Facade 模式：统一封装 Git 命令行接口 - 依赖注入：通过构造函数接收 cwd 参数 --- 2.2 CodeReviewer.ts - AI 代码审查器 核心职责：使用 AI 模型对代码变更进行质量审查 关键算法与实现： 2.2.1 审查级别策略 export enum ReviewLevel { QUICK = 'quick', // 快速扫描 STANDARD = 'standard', // 标准审查 DEEP = 'deep' // 深度分析 } 2.2.2 动态 Prompt 构建 private buildReviewPrompt(diff: string, level: ReviewLevel, capabilityLevel: CapabilityLevel): string - Diff 截断：限制为 15000 字符避免超出 context window - 能力自适应：根据 CapabilityLevel 调整审查深度 - 结构化输出：强制要求 JSON 格式响应 2.2.3 降级决策机制 const degradationDecision = this.degradationPolicy.decide(decisionInput, minCapability); - 监控指标：timeElapsed（响应时间）、confidence（置信度） - 降级链：SEMANTIC → STRUCTURAL → LINE → TEXT → NONE - 阈值策略：使用 ThresholdDegradationPolicy 自动决策 2.2.4 响应解析算法 private parseReviewResult(content: string): Partial<ReviewResult> - 多格式支持： - JSON 代码块：/```json\n([\s\S]*?)\n```/ - 裸 JSON：/{[\s\S]*}/ - 纯文本：回退到 parseTextReview - 容错处理：解析失败时返回默认评分 70 2.2.5 保护性限制 if (level === ReviewLevel.DEEP && files.length > 20) { throw new Error('Deep review is not recommended for more than 20 files'); } 集成点： - 与 ModelRouter 协作进行模型路由 - 支持 commit、file、staged 三种审查模式 --- 2.3 CommitMessageGenerator.ts - 提交消息生成器 核心职责：基于代码变更智能生成符合规范的 commit message 关键算法与实现： 2.3.1 Diff 分析算法 private analyzeDiff(diff: string): { insertions, deletions, files } - 正则匹配文件路径：/[ab]\/(.*)/ - 排除 /dev/null 防止误计 - 统计新增/删除行数 2.3.2 项目上下文注入 const pkgPath = path.join(cwd, 'package.json'); if (fs.existsSync(pkgPath)) { ... } - 动态读取 package.json 提供项目元信息 - 非阻塞设计：读取失败不影响主流程 2.3.3 AI 生成 + 规则回退 try { if (this.router) { message = await this.generateWithAI(diffContent, config); } else { message = this.generateRuleBased(diffContent, config); } } catch (error) { message = this.generateRuleBased(diffContent, config); } 2.3.4 规则引擎实现 private generateRuleBased(diff: string, config: CommitMessageConfig): string - Type 推断： - 包含 test → test - 包含 .md → docs - insertions > deletions * 2 → feat - deletions > insertions → refactor - Scope 推断：提取一级目录名 2.3.5 Conventional Commits 强制格式 `${type}${scope ? `(${scope})` : ''}: ${subject}` Policy 集成： const { GitContextAggregator } = await import('./GitContextAggregator'); aggregator.ensureStaged(ctx); // 确保有暂存变更 --- 2.4 ConflictResolver.ts - 冲突智能解决器 核心职责：使用 AI 自动解决 Git merge 冲突 关键算法与实现： 2.4.1 冲突检测 if (!content.includes('<<<<<<<') || !content.includes('>>>>>>>')) { return { success: false, error: '未检测到冲突标记' }; } 2.4.2 AI Prompt 设计 system: `你是资深软件工程师，擅长解决 Git 合并冲突。 要求： 1. 识别冲突部分 2. 语义化合并两个版本 3. 绝对不要遗漏必要逻辑 4. 移除所有冲突标记 5. 直接输出文件内容（不要 Markdown 容器）` 2.4.3 五层校验机制 // 1. 空内容校验 if (!resolvedContent || resolvedContent.trim().length === 0) { ... } // 2. 长度偏差校验 if (content.length > 300 && resolvedContent.length < content.length * 0.3) { ... } // 3. 冲突标记残留校验 if (resolvedContent.includes('<<<<<<<') || ...) { ... } // 4. 语法完整性校验 const syntaxError = this.validateSyntax(filePath, resolvedContent); // 5. 备份保护 if (backup) { backupFile = `${fullPath}.bak`; await fs.promises.writeFile(backupFile, content, 'utf8'); } 2.4.4 语法校验器 private validateSyntax(filePath: string, content: string): string | null - JSON 校验：JSON.parse(content) - 括号匹配：{ vs } 和 ( vs ) 数量对比 - 支持扩展：.js/.ts/.jsx/.tsx/.json/.c/.cpp/.java 安全设计： - dryRun 模式：仅生成不写入 - 强制备份：默认创建 .bak 文件 - 校验失败立即中止 --- 2.5 GitContextAggregator.ts - 上下文聚合器 核心职责：并行收集 Git 状态并提供统一的上下文快照 关键算法与实现： 2.5.1 并行 I/O 优化 async collect(): Promise<GitContext> { const [diff, status, branches, commits, repoRoot] = await Promise.all([ this.gitService.getDiff(), this.gitService.getStatusSummary(), this.gitService.getBranches(), this.gitService.getRecentCommits(5), this.gitService.getRepoRoot() ]); } - 性能优化：5 个独立的 Git 操作并行执行 - 单一快照：确保所有数据来自同一时间点 2.5.2 Policy 强制执行 ensureStaged(context: GitContext): void { if (!context.diff.staged) { if (context.diff.unstaged) { throw new Error(`Found ${count} unstaged file(s) [...], but nothing is staged.`); } throw new Error('No changes to commit (working tree clean).'); } } - 职责边界：仅处理 Git 层事实，不包含 AI 或业务逻辑 - 友好提示：包含 git add . 和 yuangs git commit -a 建议 --- 2.6 BranchAdvisor.ts - 分支建议顾问 核心职责：基于 AI 分析当前工作区状态，提供分支操作建议 关键算法与实现： 2.6.1 决策选项 export interface BranchSuggestion { action: 'stay' | 'switch' | 'create'; targetBranch?: string; // for switch newBranch?: { // for create name: string; from: string; type: 'feature' | 'fix' | 'chore' | 'docs' | 'refactor' | 'test'; }; confidence: number; } 2.6.2 上下文简化策略 branchList: ctx.branches.all.slice(0, 20) // 限制分支列表避免 token 爆炸 2.6.3 判断原则（优先级） 1. 主分支保护：main/master/develop → 必须 create 2. 主题一致性：分支名与变更文件相关 → stay 3. 混合变更风险：多个不相关改动 → create (拆分) 4. 已有分支匹配：变更对应现有分支 → switch 2.6.4 响应校验 private isValidSuggestion(x: any): x is BranchSuggestion { if (!['stay', 'switch', 'create'].includes(x.action)) return false; if (x.action === 'create' && !x.newBranch?.name) return false; if (x.action === 'switch' && !x.targetBranch) return false; return true; } 2.6.5 Fallback 机制 - Schema Guard：AI 响应不合法时自动回退到 stay - 清理 Markdown：replace(/```json/g, '').replace(/```/g, '') --- 2.7 SmartCommitManager.ts - 智能提交管理器 核心职责：将混合的工作区变更智能分组为独立的逻辑提交 关键算法与实现： 2.7.1 语义摘要增强 const fileSummaries = await Promise.all(changedFiles.map(async (file) => { const diff = await this.gitService.getFileDiff(file.path, false); const semantic = SemanticDiffEngine.analyze(diff || ''); return { path: file.path, summary: semantic.overallSummary, details: semantic.files[0]?.changes.map(...).join(', ') }; })); - 为每个文件生成语义级摘要 - 帮助 AI 理解变更类型（而非仅文件名） 2.7.2 AI 分组策略 const prompt = { system: `将变更归类为逻辑独立的提交组，规则： - 绝对必须包含所有文件 - 确保路径与输入完全一致 - 逻辑相关的变更必须在一起` } 2.7.3 路径校验与纠错 const checkedFiles = g.files.map((f: string) => { if (actualPaths.has(f)) return f; // 启发式纠错：AI 可能丢失 's' 前缀 if (f.startsWith('rc/') && actualPaths.has('s' + f)) return 's' + f; return f; }); 2.7.4 Remaining 文件跟踪 const plannedFiles = new Set(groups.flatMap(g => g.files)); const remainingFiles = changedFiles.map(...).filter(p => !plannedFiles.has(p)); - 确保没有遗漏文件 - UI 可以警告用户未分组的文件 --- 2.8 TodoManager.ts - Todo 任务管理器 核心职责：解析和管理 todo.md 文件中的任务及其依赖关系 关键算法与实现： 2.8.1 任务解析 const TASK_REGEX = /^[\s]*-\s*\[([x\s])\]\s*(.+?)(?:\s*<!--\s*(.+?)\s*-->)?$/; - Checkbox 状态：[x] 表示完成 - HTML 注释元数据：<!-- exec:done, review:85, attempts:1 --> 2.8.2 依赖解析 const DEPENDENCY_REGEX = /\[depends:\s*(.+?)\]/i; // 示例：- [ ] Task 3 [depends: 1, 2] 2.8.3 执行顺序算法 export function getExecutionOrder(tasks: TaskStatus[]): number[] { // 深度优先遍历，先访问依赖 function visit(index: number) { if (visited.has(index)) return; visited.add(index); if (task.dependsOn) { for (const depIndex of task.dependsOn) { visit(depIndex); } } order.push(index); } } 2.8.4 循环依赖检测 function hasCircularDependency( tasks: TaskStatus[], from: number, to: number, visited: Set<number> ): boolean { if (visited.has(to)) return true; // 已访问过 → 循环 visited.add(to); for (const dep of toTask.dependsOn) { if (dep === from || hasCircularDependency(...)) return true; } return false; } 2.8.5 下一任务选择 export function getNextTask(tasks: TaskStatus[]): TaskStatus | null { const availableTasks = pendingTasks.filter(task => { return task.dependsOn.every(depIndex => tasks[depIndex].completed); }); // 按优先级排序：high > medium > low availableTasks.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]); return availableTasks[0]; } --- 2.9 ProgressManager.ts - 进度管理器 核心职责：管理工作流状态，支持暂停/恢复 关键算法与实现： 2.9.1 状态持久化 private stateFilePath = path.join(baseDir, '.yuangs', 'progress', 'workflow-state.json'); - 存储位置：.yuangs/progress/ 目录 - 格式：JSON 包含 sessionId、tasksExecuted、options 等 2.9.2 会话 ID 生成 const sessionId = Date.now().toString(36) + Math.random().toString(36).substr(2, 9); - 时间戳 + 随机字符串，确保唯一性 2.9.3 恢复检测 async hasIncompleteWorkflow(): Promise<boolean> { const state = await this.load(); if (!state) return false; const todoPath = path.join(this.baseDir, 'todo.md'); if (!fs.existsSync(todoPath)) return false; return true; } 2.9.4 进度报告导出 async exportReport(todoMetadata: TodoMetadata): Promise<string> { const reportPath = path.join(..., `report-${state.sessionId}.md`); // Markdown 格式包含会话信息、配置、执行进度 } --- 2.10 ContextGatherer.ts - 项目上下文采集器 核心职责：为 AI 提供项目结构和相关文件的真实快照 关键算法与实现： 2.10.1 文件树获取 private async getFileTree(cwd: string): Promise<string> { const { stdout } = await execAsync('git ls-files', { cwd }); // 全局黑名单过滤 const noiseExtension = /\.(png|jpe?g|gif|svg|ico|pdf|zip|tar|gz|exe|dll|so|bin|pyc|woff2?|ttf|eot)$/i; files = files.filter((f: string) => !noiseExtension.test(f)); // Token 保护：截断到 150 个文件 if (files.length > 150) { return files.slice(0, 150).join('\n') + `\n... (已截断其余 ${files.length - 150} 个文件)`; } } 2.10.2 相关文件启发式搜索 private async getRelevantFiles(description, repoRoot, fileList, isDocTask, packageJson) - 精准匹配：从描述中提取路径（如 src/core/git/GitService.ts） - 智能探测： - 文档任务：优先 README.md, docs/index.md, meta.yaml - 代码任务：优先 package.json.main, src/index.ts, src/cli.ts - 内容截断：单文件 10KB，总计 50KB 上限 2.10.3 置信度评估 let confidence = 0.5; if (packageJson) confidence += 0.2; if (relevantFiles.length > 0) confidence += 0.2; if (fileTree.length > 0 && !fileTree.includes('无法获取')) confidence += 0.1; if (totalFiles > 150) confidence -= 0.05; // 截断扣分 2.10.4 ContextMeta 审计 metaBuilder.setProvenance('ContextGatherer', 'git:files'); metaBuilder.setClipped('Context size limit exceeded', droppedItems); metaBuilder.setConfidence(confidence, confidenceReasons.join('; ')); const meta = metaBuilder.build(); --- 2.11 CodeGenerator.ts - 代码生成与解析 核心职责：解析 AI 输出的代码并写入文件系统 关键算法与实现： 2.11.1 多格式解析器 export function parseGeneratedCode(llmOutput: string): GeneratedCode 支持 6 种 Markdown 格式： 1. ```filepath\npath\n``` ```code\ncode\n``` 2. `### 文件: path/to/file.ts\ntypescript\ncode\n 3. `**path/to/file.ts**\ntypescript\ncode\n 4. ## 📄 文件：filename.ext`\ncode\ncode\n 5. ### 📄 文件：filename.ext`\nhtml\ncode\n 6. ## 📄 文件：filename.ext`\n说明\nhtml\ncode\n 2.11.2 去重机制 if (!files.some(f => f.path === filePath)) { files.push({ path: filePath, content, action: 'create' }); } 2.11.3 安全写入 export async function writeGeneratedCode(generated, baseDir) - 自动创建目录：await fs.promises.mkdir(dir, { recursive: true }) - 异常隔离：单个文件失败不阻塞其他文件 - 日志输出：✓ 创建: ${file.path} / ⚠ 跳过: ${file.path} 2.11.4 备份系统 export async function backupFiles(files, baseDir): Promise<BackupInfo> - 备份 ID：crypto.randomBytes(8).toString('hex') - Manifest：JSON 文件记录备份内容和时间戳 - 恢复：restoreFromBackup(backupId) 从 manifest 还原 2.11.5 备份清理 export async function cleanOldBackups(keepCount = 5, baseDir) - 按时间戳排序 - 保留最新 N 个备份 - 递归删除：fs.promises.rm(backupPath, { recursive: true }) --- 2.12 ErrorHandler.ts - 错误处理框架 核心职责：提供重试机制和错误分类 关键算法与实现： 2.12.1 重试包装器 export async function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T> - 指数退避：delay * Math.pow(2, attempt - 1) - 条件重试：shouldRetry(error, attempt) - 回调支持：onRetry(error, attempt) 用于日志 2.12.2 可重试错误识别 export function isRetryableError(error: any): boolean { // 网络错误 if (message.includes('network') || message.includes('timeout') || ...) return true; // HTTP 5xx / 429 if (error.statusCode >= 500 || error.statusCode === 429) return true; // Git lock if (message.includes('git') && message.includes('lock')) return true; return false; } 2.12.3 错误类型分类 export enum ErrorType { NETWORK, TIMEOUT, GIT, FILESYSTEM, VALIDATION, PERMISSION, UNKNOWN } export function identifyErrorType(error: any): ErrorType { const message = error.message?.toLowerCase() || ''; if (message.includes('network') || message.includes('econn')) return ErrorType.NETWORK; if (message.includes('timeout')) return ErrorType.TIMEOUT; ... } 2.12.4 建议生成 export function getSuggestion(error: any): string | null { switch (identifyErrorType(error)) { case ErrorType.NETWORK: return '请检查网络连接，稍后重试'; case ErrorType.GIT: return '请检查 Git 仓库状态，确保没有锁定'; ... } } --- 2.13 GitConfigManager.ts - 配置管理器 核心职责：加载、合并和验证工作流配置 关键算法与实现： 2.13.1 配置文件查找 findConfigFile(): string | null { // 当前目录 for (const filename of CONFIG_FILENAMES) { ... } // 向上递归 5 层 let parentDir = path.dirname(this.baseDir); let depth = 0; while (depth < 5) { ... } } 2.13.2 配置合并策略 private mergeConfig(base, override): GitWorkflowConfig { return { auto: { ...base.auto, ...override.auto }, plan: { ...base.plan, ...override.plan }, review: { ...base.review, ...override.review } }; } 2.13.3 优先级层次 CLI 选项 > 配置文件 > 默认值 2.13.4 配置验证 validateConfig(): { valid: boolean; errors: string[] } { if (minScore < 0 || minScore > 100) errors.push('minScore 必须在 0-100 之间'); if (maxTasks < 1 || maxTasks > 100) errors.push('maxTasks 必须在 1-100 之间'); ... } --- 2.14 Semantic 子模块分析 2.14.1 SemanticDiffEngine.ts - 语义差异引擎 核心算法： 文件块拆分： private static splitDiffIntoFiles(diff: string): string[] { // 以 "diff --git " 为分隔符 } 正则匹配识别： const funcRegex = /(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z0-9_]+)\s*\(/; const arrowFuncRegex = /(?:export\s+)?(?:const|let|var)\s+([a-zA-Z0-9_]+)\s*=\s*(?:async\s+)?(?:\(?.*?\)?)\s*=>/; const classRegex = /(?:export\s+)?class\s+([a-zA-Z0-9_]+)/; const interfaceRegex = /(?:export\s+)?interface\s+([a-zA-Z0-9_]+)/; Breaking Change 检测： isBreaking: type === ChangeType.DELETION // 删除即 Breaking 局限性： - 基于正则，无法处理复杂嵌套 - 注释干扰可能导致误判 - 未来演进方向：TypeScript Compiler API（AST 分析） 2.14.2 SemanticCommitParser.ts - 语义提交解析器 核心算法： 影响等级判断： let impactLevel = 'low'; if (structuralChanges.isBreaking) impactLevel = 'breaking'; else if (files.length > 5 || changes.length > 3) impactLevel = 'high'; else if (files.length > 2 || changes.length > 0) impactLevel = 'medium'; 语义摘要生成： // 结合原始消息 + 结构化变更 → AI 生成技术意图总结 const prompt = `原始消息: ${commit.message}\n结构化变更:\n${structuralDesc}`; 历史趋势分析： // 总结最近 N 个提交 → 识别开发阶段/趋势 const historyData = explanations.map(e => `- [${e.impactLevel}] ${e.semanticSummary}`); --- 3. 设计模式与架构原则 3.1 分层设计 ┌─────────────────────────────────────┐ │ CLI Command Layer (src/cli) │ ├─────────────────────────────────────┤ │ Business Logic Layer │ │ - BranchAdvisor │ │ - SmartCommitManager │ │ - CodeReviewer │ ├─────────────────────────────────────┤ │ Core Service Layer │ │ - GitService (Git Wrapper) │ │ - GitContextAggregator (Policy) │ │ - ModelRouter (AI Abstraction) │ ├─────────────────────────────────────┤ │ Utility Layer │ │ - ErrorHandler, ConfigManager │ │ - TodoManager, ProgressManager │ └─────────────────────────────────────┘ 3.2 关键设计模式 3.2.1 Facade Pattern - GitService 封装所有 Git 命令 - 提供类型安全的高级 API - 隐藏 child_process 细节 3.2.2 Strategy Pattern - ReviewLevel 枚举定义审查策略 - DegradationPolicy 动态降级策略 - 规则引擎与 AI 生成的双模式 3.2.3 Template Method - withRetry 定义重试流程骨架 - 子类通过 shouldRetry 自定义条件 3.2.4 Builder Pattern - ContextMetaBuilder 构建审计元数据 - 分步设置 provenance、confidence、clipping 3.2.5 Policy Object - GitContextAggregator.ensureStaged 强制规则 - 分离事实采集与业务约束 3.3 架构原则 3.3.1 单一职责 - GitService：仅负责 Git 操作 - CodeReviewer：仅负责审查逻辑 - ContextGatherer：仅负责上下文采集 3.3.2 依赖注入 constructor( private gitService: GitService, private router?: ModelRouter ) - 通过构造函数注入依赖 - 便于测试和模块替换 3.3.3 防御性编程 - Null 安全：execSafe 返回 null 而非抛异常 - 输入校验：配置验证、语法校验、Schema Guard - 容错设计：AI 解析失败时的回退机制 3.3.4 性能优化 - 并行 I/O：Promise.all 并行执行 Git 命令 - Token 保护：Diff 截断、文件树截断 - 缓冲区调优：maxBuffer: 10MB --- 4. 与 CLI 命令的集成关系 4.1 yuangs git commit 调用链： CLI: commit.action ↓ CommitMessageGenerator.generate() ↓ GitContextAggregator.collect() → 获取上下文 ↓ ModelRouter.route() → 选择模型 ↓ generateWithAI() / generateRuleBased() → 生成消息 ↓ GitService.stageFiles() + commit() → 执行提交 4.2 yuangs git review 调用链： CLI: review.action ↓ CodeReviewer.review(level, staged) ↓ GitService.getDiff() → 获取变更 ↓ buildReviewPrompt() → 构建 Prompt ↓ ModelRouter.executeTask() → AI 审查 ↓ parseReviewResult() → 解析结果 ↓ degradationPolicy.decide() → 降级决策 4.3 yuangs git branch 调用链： CLI: branch.action ↓ BranchAdvisor.suggest() ↓ GitContextAggregator.collect() → 收集状态 ↓ buildPrompt() → 构建决策上下文 ↓ ModelRouter.executeTask() → AI 分析 ↓ parseResponse() + isValidSuggestion() → 校验建议 ↓ CLI: 展示建议或自动执行 4.4 yuangs git conflict 调用链： CLI: conflict.action ↓ GitService.getConflictedFiles() → 检测冲突 ↓ ConflictResolver.resolveFile(file, options) ↓ runLLM() → AI 生成解决方案 ↓ validateSyntax() → 五层校验 ↓ writeFile() + 备份 → 写入解决方案 4.5 yuangs git smart-commit 调用链： CLI: smart-commit.action ↓ SmartCommitManager.planCommits() ↓ SemanticDiffEngine.analyze() → 语义摘要 ↓ runLLM() → AI 分组 ↓ 路径校验与纠错 → 确保完整 ↓ CLI: 用户选择分组 ↓ executeCommitGroup() → 逐组提交 4.6 yuangs git auto 调用链（最复杂）： CLI: auto.action ↓ GitConfigManager.loadConfig() → 加载配置 ↓ ProgressManager.load() → 检测未完成工作流 ↓ TodoManager.parseTodoFile() → 解析任务 ↓ getNextTask() → 选择任务（考虑依赖） ↓ ContextGatherer.gather() → 采集项目上下文 ↓ ModelRouter.executeTask() → AI 生成代码 ↓ parseGeneratedCode() → 解析输出 ↓ backupFiles() → 备份现有文件 ↓ writeGeneratedCode() → 写入代码 ↓ CodeReviewer.review() → 审查生成的代码 ↓ updateTaskStatus() → 更新 todo.md ↓ ProgressManager.save() → 保存进度 ↓ Loop: 继续下一个任务或完成 --- 5. 共享接口与类型系统 5.1 核心类型定义 5.1.1 GitService 导出类型 export interface GitDiff { staged: string | null; unstaged: string | null; files: { staged: string[]; unstaged: string[] }; } export interface GitBranchInfo { current: string; upstream?: string; ahead: number; behind: number; } export interface GitCommitInfo { hash: string; author: string; date: string; message: string; } export interface GitNumstat { added: number; deleted: number; files: string[]; } 5.1.2 CodeReviewer 导出类型 export enum ReviewLevel { QUICK, STANDARD, DEEP } export enum IssueSeverity { INFO, WARNING, ERROR, CRITICAL } export interface ReviewIssue { severity: IssueSeverity; file: string; line?: number; message: string; suggestion?: string; snippet?: string; } export interface ReviewResult { score: number; summary: string; issues: ReviewIssue[]; strengths: string[]; recommendations: string[]; filesReviewed: number; confidence: number; degradation?: { applied, originalLevel, targetLevel, reason }; } 5.1.3 Semantic 类型 export enum ChangeType { ADDITION, DELETION } export enum SemanticCategory { FUNCTION, CLASS, INTERFACE, TYPE, CONSTANT, UNKNOWN } export interface SemanticChange { type: ChangeType; category: SemanticCategory; name: string; details?: string; isBreaking: boolean; } export interface SemanticDiffResult { files: FileSemanticDiff[]; overallSummary: string; isBreaking: boolean; } 5.1.4 TodoManager 类型 export interface TaskStatus { index: number; description: string; completed: boolean; execStatus?: 'pending' | 'in_progress' | 'done' | 'failed'; reviewScore?: number; attempts?: number; backupId?: string; dependsOn?: number[]; priority?: 'high' | 'medium' | 'low'; } export interface TodoMetadata { generatedAt?: string; context?: string; progress?: { completed: number; total: number }; currentTask?: number; } 5.2 常量定义（constants.ts） export const METADATA_PREFIX = '>'; export const TODO_FILENAME = 'todo.md'; export const DEFAULT_PLAN_PROMPT = '分析项目现状并规划下一步开发任务'; export const DEFAULT_AI_MODEL = 'Assistant'; export const MAX_RETRY_ATTEMPTS = 2; export const MIN_REVIEW_SCORE = 85; export const REVIEW_FAILURE_SCORE = 60; export const GIT_CONFLICT_CODES = ['UU', 'AA', 'DD', 'AU', 'UD', 'UA', 'DU']; export const SUPPORTED_AI_MODELS = [ 'gpt-4o', 'gpt-4o-mini', 'claude-3.5-sonnet', 'gemini-2.0-flash', 'Assistant' ]; --- 6. 总结与亮点 6.1 架构亮点 1. 清晰的职责划分： - GitService 专注 Git 底层封装 - GitContextAggregator 统一上下文采集 - 业务逻辑层（Reviewer/Generator/Advisor）独立可测试 2. AI 集成策略： - 通过 ModelRouter 解耦具体模型 - 支持降级策略和容错处理 - 规则引擎 + AI 的双模式设计 3. 安全性保障： - 多层校验（ConflictResolver 的 5 层机制） - 备份系统（CodeGenerator 的增量备份） - 防御性编程（Null 检查、异常隔离） 4. 性能优化： - 并行 I/O（Promise.all） - Token 保护（截断策略） - 缓存机制（配置文件查找） 5. 可扩展性： - 插件化设计（可替换 AI 模型） - 配置驱动（JSON/JS 配置文件） - 类型安全（完善的 TypeScript 接口） 6.2 核心算法总结 ┌────────────────────┬────────────────────────┬────────┬────────────────────────┐ │ 模块 │ 核心算法 │ 复杂度 │ 特点 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ GitService │ Git 命令封装 │ O(1) │ Spawn + stdin 避免转义 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ SemanticDiffEngine │ 正则匹配解析 │ O(n) │ 基于行级扫描 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ TodoManager │ 依赖图遍历 │ O(V+E) │ DFS + 循环检测 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ BranchAdvisor │ AI 决策 + Schema Guard │ O(1) │ 三选一决策树 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ ConflictResolver │ 五层校验机制 │ O(n) │ 逐层验证 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ SmartCommitManager │ 路径校验 + 纠错 │ O(n²) │ Set 查找 + 启发式修复 │ └────────────────────┴────────────────────────┴────────┴────────────────────────┘ 6.3 与 CLI 的协同 - 命令层：负责参数解析和用户交互 - 业务层：负责 Git 逻辑和 AI 集成 - 服务层：负责底层操作和状态管理 每个 CLI 命令都通过清晰的调用链连接到核心服务，形成完整的功能闭环。 --- 文件统计： - 核心服务：14 个主要模块 - 代码行数：约 3500 行（不含注释） - 类型定义：20+ 接口，5+ 枚举 - 设计模式：6 种（Facade, Strategy, Template, Builder, Policy, Dependency Injection） 技术栈： - TypeScript - Node.js child_process - Git CLI - Chalk (终端美化) - Crypto (备份 ID) 这是一个设计精良、职责清晰、可扩展性强的 Git 工作流自动化核心层。 ● Explore Perfect! Now I have a comprehensive understanding of the src/core/git directory. Let me compile a detailed analysis report in Chinese. --- src/core/git 目录详细分析报告 1. 文件结构清单 src/core/git/ ├── GitService.ts # Git 核心服务层 ├── CodeReviewer.ts # AI 代码审查器 ├── CommitMessageGenerator.ts # 提交消息生成器 ├── ConflictResolver.ts # 冲突智能解决器 ├── GitContextAggregator.ts # Git 上下文聚合器 ├── BranchAdvisor.ts # 分支建议顾问 ├── SmartCommitManager.ts # 智能提交管理器 ├── TodoManager.ts # Todo 任务管理器 ├── ProgressManager.ts # 工作流进度管理器 ├── ContextGatherer.ts # 项目上下文采集器 ├── CodeGenerator.ts # 代码生成与解析模块 ├── ErrorHandler.ts # 错误处理与重试机制 ├── GitConfigManager.ts # Git 工作流配置管理 ├── constants.ts # 模块常量定义 └── semantic/ # 语义分析子模块 ├── types.ts # 语义类型定义 ├── SemanticDiffEngine.ts # 语义差异分析引擎 ├── SemanticCommitParser.ts # 语义提交解析器 └── historyTypes.ts # 历史分析类型 --- 2. 核心服务类详细分析 2.1 GitService.ts - Git 底层操作服务 核心职责：封装所有 Git 命令行操作，提供类型安全的 API 关键算法与实现： 2.1.1 安全执行机制 private async exec(command: string): Promise<string> async execSafe(command: string): Promise<string | null> - 双模式执行：exec 抛出异常，execSafe 返回 null - 缓冲区优化：maxBuffer: 10MB 处理大型 diff - 统一错误处理：包装为 GitError 并附带修复建议 2.1.2 Diff 统计算法 async getDiffNumstat(): Promise<GitNumstat> - 使用 git diff --numstat 获取精确的行数统计 - 分别处理 staged 和 unstaged 的变更 - 正确解析包含空格的文件名（使用 parts.slice(2).join(' ')） 2.1.3 分支信息获取 async getBranches(): Promise<{...}> - 使用 git for-each-ref 获取详细信息 - 自定义格式字符串解析 upstream tracking 关系 - 正则提取 ahead/behind 数量：track.match(/ahead (\d+)/) 2.1.4 安全提交机制 async commit(message: string): Promise<string> - 关键设计：使用 spawn + stdin 而非命令行参数传递消息 - 原因：避免 shell escaping 问题，支持多行消息 - 流程：git commit -F - + pipe message via stdin 2.1.5 语义 Diff 集成 async getSemanticDiff(staged: boolean): Promise<SemanticDiffResult | null> - 集成 SemanticDiffEngine 进行结构化分析 - 识别函数、类、接口级别的变更 设计模式： - Facade 模式：统一封装 Git 命令行接口 - 依赖注入：通过构造函数接收 cwd 参数 --- 2.2 CodeReviewer.ts - AI 代码审查器 核心职责：使用 AI 模型对代码变更进行质量审查 关键算法与实现： 2.2.1 审查级别策略 export enum ReviewLevel { QUICK = 'quick', // 快速扫描 STANDARD = 'standard', // 标准审查 DEEP = 'deep' // 深度分析 } 2.2.2 动态 Prompt 构建 private buildReviewPrompt(diff: string, level: ReviewLevel, capabilityLevel: CapabilityLevel): string - Diff 截断：限制为 15000 字符避免超出 context window - 能力自适应：根据 CapabilityLevel 调整审查深度 - 结构化输出：强制要求 JSON 格式响应 2.2.3 降级决策机制 const degradationDecision = this.degradationPolicy.decide(decisionInput, minCapability); - 监控指标：timeElapsed（响应时间）、confidence（置信度） - 降级链：SEMANTIC → STRUCTURAL → LINE → TEXT → NONE - 阈值策略：使用 ThresholdDegradationPolicy 自动决策 2.2.4 响应解析算法 private parseReviewResult(content: string): Partial<ReviewResult> - 多格式支持： - JSON 代码块：/```json\n([\s\S]*?)\n```/ - 裸 JSON：/{[\s\S]*}/ - 纯文本：回退到 parseTextReview - 容错处理：解析失败时返回默认评分 70 2.2.5 保护性限制 if (level === ReviewLevel.DEEP && files.length > 20) { throw new Error('Deep review is not recommended for more than 20 files'); } 集成点： - 与 ModelRouter 协作进行模型路由 - 支持 commit、file、staged 三种审查模式 --- 2.3 CommitMessageGenerator.ts - 提交消息生成器 核心职责：基于代码变更智能生成符合规范的 commit message 关键算法与实现： 2.3.1 Diff 分析算法 private analyzeDiff(diff: string): { insertions, deletions, files } - 正则匹配文件路径：/[ab]\/(.*)/ - 排除 /dev/null 防止误计 - 统计新增/删除行数 2.3.2 项目上下文注入 const pkgPath = path.join(cwd, 'package.json'); if (fs.existsSync(pkgPath)) { ... } - 动态读取 package.json 提供项目元信息 - 非阻塞设计：读取失败不影响主流程 2.3.3 AI 生成 + 规则回退 try { if (this.router) { message = await this.generateWithAI(diffContent, config); } else { message = this.generateRuleBased(diffContent, config); } } catch (error) { message = this.generateRuleBased(diffContent, config); } 2.3.4 规则引擎实现 private generateRuleBased(diff: string, config: CommitMessageConfig): string - Type 推断： - 包含 test → test - 包含 .md → docs - insertions > deletions * 2 → feat - deletions > insertions → refactor - Scope 推断：提取一级目录名 2.3.5 Conventional Commits 强制格式 `${type}${scope ? `(${scope})` : ''}: ${subject}` Policy 集成： const { GitContextAggregator } = await import('./GitContextAggregator'); aggregator.ensureStaged(ctx); // 确保有暂存变更 --- 2.4 ConflictResolver.ts - 冲突智能解决器 核心职责：使用 AI 自动解决 Git merge 冲突 关键算法与实现： 2.4.1 冲突检测 if (!content.includes('<<<<<<<') || !content.includes('>>>>>>>')) { return { success: false, error: '未检测到冲突标记' }; } 2.4.2 AI Prompt 设计 system: `你是资深软件工程师，擅长解决 Git 合并冲突。 要求： 1. 识别冲突部分 2. 语义化合并两个版本 3. 绝对不要遗漏必要逻辑 4. 移除所有冲突标记 5. 直接输出文件内容（不要 Markdown 容器）` 2.4.3 五层校验机制 // 1. 空内容校验 if (!resolvedContent || resolvedContent.trim().length === 0) { ... } // 2. 长度偏差校验 if (content.length > 300 && resolvedContent.length < content.length * 0.3) { ... } // 3. 冲突标记残留校验 if (resolvedContent.includes('<<<<<<<') || ...) { ... } // 4. 语法完整性校验 const syntaxError = this.validateSyntax(filePath, resolvedContent); // 5. 备份保护 if (backup) { backupFile = `${fullPath}.bak`; await fs.promises.writeFile(backupFile, content, 'utf8'); } 2.4.4 语法校验器 private validateSyntax(filePath: string, content: string): string | null - JSON 校验：JSON.parse(content) - 括号匹配：{ vs } 和 ( vs ) 数量对比 - 支持扩展：.js/.ts/.jsx/.tsx/.json/.c/.cpp/.java 安全设计： - dryRun 模式：仅生成不写入 - 强制备份：默认创建 .bak 文件 - 校验失败立即中止 --- 2.5 GitContextAggregator.ts - 上下文聚合器 核心职责：并行收集 Git 状态并提供统一的上下文快照 关键算法与实现： 2.5.1 并行 I/O 优化 async collect(): Promise<GitContext> { const [diff, status, branches, commits, repoRoot] = await Promise.all([ this.gitService.getDiff(), this.gitService.getStatusSummary(), this.gitService.getBranches(), this.gitService.getRecentCommits(5), this.gitService.getRepoRoot() ]); } - 性能优化：5 个独立的 Git 操作并行执行 - 单一快照：确保所有数据来自同一时间点 2.5.2 Policy 强制执行 ensureStaged(context: GitContext): void { if (!context.diff.staged) { if (context.diff.unstaged) { throw new Error(`Found ${count} unstaged file(s) [...], but nothing is staged.`); } throw new Error('No changes to commit (working tree clean).'); } } - 职责边界：仅处理 Git 层事实，不包含 AI 或业务逻辑 - 友好提示：包含 git add . 和 yuangs git commit -a 建议 --- 2.6 BranchAdvisor.ts - 分支建议顾问 核心职责：基于 AI 分析当前工作区状态，提供分支操作建议 关键算法与实现： 2.6.1 决策选项 export interface BranchSuggestion { action: 'stay' | 'switch' | 'create'; targetBranch?: string; // for switch newBranch?: { // for create name: string; from: string; type: 'feature' | 'fix' | 'chore' | 'docs' | 'refactor' | 'test'; }; confidence: number; } 2.6.2 上下文简化策略 branchList: ctx.branches.all.slice(0, 20) // 限制分支列表避免 token 爆炸 2.6.3 判断原则（优先级） 1. 主分支保护：main/master/develop → 必须 create 2. 主题一致性：分支名与变更文件相关 → stay 3. 混合变更风险：多个不相关改动 → create (拆分) 4. 已有分支匹配：变更对应现有分支 → switch 2.6.4 响应校验 private isValidSuggestion(x: any): x is BranchSuggestion { if (!['stay', 'switch', 'create'].includes(x.action)) return false; if (x.action === 'create' && !x.newBranch?.name) return false; if (x.action === 'switch' && !x.targetBranch) return false; return true; } 2.6.5 Fallback 机制 - Schema Guard：AI 响应不合法时自动回退到 stay - 清理 Markdown：replace(/```json/g, '').replace(/```/g, '') --- 2.7 SmartCommitManager.ts - 智能提交管理器 核心职责：将混合的工作区变更智能分组为独立的逻辑提交 关键算法与实现： 2.7.1 语义摘要增强 const fileSummaries = await Promise.all(changedFiles.map(async (file) => { const diff = await this.gitService.getFileDiff(file.path, false); const semantic = SemanticDiffEngine.analyze(diff || ''); return { path: file.path, summary: semantic.overallSummary, details: semantic.files[0]?.changes.map(...).join(', ') }; })); - 为每个文件生成语义级摘要 - 帮助 AI 理解变更类型（而非仅文件名） 2.7.2 AI 分组策略 const prompt = { system: `将变更归类为逻辑独立的提交组，规则： - 绝对必须包含所有文件 - 确保路径与输入完全一致 - 逻辑相关的变更必须在一起` } 2.7.3 路径校验与纠错 const checkedFiles = g.files.map((f: string) => { if (actualPaths.has(f)) return f; // 启发式纠错：AI 可能丢失 's' 前缀 if (f.startsWith('rc/') && actualPaths.has('s' + f)) return 's' + f; return f; }); 2.7.4 Remaining 文件跟踪 const plannedFiles = new Set(groups.flatMap(g => g.files)); const remainingFiles = changedFiles.map(...).filter(p => !plannedFiles.has(p)); - 确保没有遗漏文件 - UI 可以警告用户未分组的文件 --- 2.8 TodoManager.ts - Todo 任务管理器 核心职责：解析和管理 todo.md 文件中的任务及其依赖关系 关键算法与实现： 2.8.1 任务解析 const TASK_REGEX = /^[\s]*-\s*\[([x\s])\]\s*(.+?)(?:\s*<!--\s*(.+?)\s*-->)?$/; - Checkbox 状态：[x] 表示完成 - HTML 注释元数据：<!-- exec:done, review:85, attempts:1 --> 2.8.2 依赖解析 const DEPENDENCY_REGEX = /\[depends:\s*(.+?)\]/i; // 示例：- [ ] Task 3 [depends: 1, 2] 2.8.3 执行顺序算法 export function getExecutionOrder(tasks: TaskStatus[]): number[] { // 深度优先遍历，先访问依赖 function visit(index: number) { if (visited.has(index)) return; visited.add(index); if (task.dependsOn) { for (const depIndex of task.dependsOn) { visit(depIndex); } } order.push(index); } } 2.8.4 循环依赖检测 function hasCircularDependency( tasks: TaskStatus[], from: number, to: number, visited: Set<number> ): boolean { if (visited.has(to)) return true; // 已访问过 → 循环 visited.add(to); for (const dep of toTask.dependsOn) { if (dep === from || hasCircularDependency(...)) return true; } return false; } 2.8.5 下一任务选择 export function getNextTask(tasks: TaskStatus[]): TaskStatus | null { const availableTasks = pendingTasks.filter(task => { return task.dependsOn.every(depIndex => tasks[depIndex].completed); }); // 按优先级排序：high > medium > low availableTasks.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]); return availableTasks[0]; } --- 2.9 ProgressManager.ts - 进度管理器 核心职责：管理工作流状态，支持暂停/恢复 关键算法与实现： 2.9.1 状态持久化 private stateFilePath = path.join(baseDir, '.yuangs', 'progress', 'workflow-state.json'); - 存储位置：.yuangs/progress/ 目录 - 格式：JSON 包含 sessionId、tasksExecuted、options 等 2.9.2 会话 ID 生成 const sessionId = Date.now().toString(36) + Math.random().toString(36).substr(2, 9); - 时间戳 + 随机字符串，确保唯一性 2.9.3 恢复检测 async hasIncompleteWorkflow(): Promise<boolean> { const state = await this.load(); if (!state) return false; const todoPath = path.join(this.baseDir, 'todo.md'); if (!fs.existsSync(todoPath)) return false; return true; } 2.9.4 进度报告导出 async exportReport(todoMetadata: TodoMetadata): Promise<string> { const reportPath = path.join(..., `report-${state.sessionId}.md`); // Markdown 格式包含会话信息、配置、执行进度 } --- 2.10 ContextGatherer.ts - 项目上下文采集器 核心职责：为 AI 提供项目结构和相关文件的真实快照 关键算法与实现： 2.10.1 文件树获取 private async getFileTree(cwd: string): Promise<string> { const { stdout } = await execAsync('git ls-files', { cwd }); // 全局黑名单过滤 const noiseExtension = /\.(png|jpe?g|gif|svg|ico|pdf|zip|tar|gz|exe|dll|so|bin|pyc|woff2?|ttf|eot)$/i; files = files.filter((f: string) => !noiseExtension.test(f)); // Token 保护：截断到 150 个文件 if (files.length > 150) { return files.slice(0, 150).join('\n') + `\n... (已截断其余 ${files.length - 150} 个文件)`; } } 2.10.2 相关文件启发式搜索 private async getRelevantFiles(description, repoRoot, fileList, isDocTask, packageJson) - 精准匹配：从描述中提取路径（如 src/core/git/GitService.ts） - 智能探测： - 文档任务：优先 README.md, docs/index.md, meta.yaml - 代码任务：优先 package.json.main, src/index.ts, src/cli.ts - 内容截断：单文件 10KB，总计 50KB 上限 2.10.3 置信度评估 let confidence = 0.5; if (packageJson) confidence += 0.2; if (relevantFiles.length > 0) confidence += 0.2; if (fileTree.length > 0 && !fileTree.includes('无法获取')) confidence += 0.1; if (totalFiles > 150) confidence -= 0.05; // 截断扣分 2.10.4 ContextMeta 审计 metaBuilder.setProvenance('ContextGatherer', 'git:files'); metaBuilder.setClipped('Context size limit exceeded', droppedItems); metaBuilder.setConfidence(confidence, confidenceReasons.join('; ')); const meta = metaBuilder.build(); --- 2.11 CodeGenerator.ts - 代码生成与解析 核心职责：解析 AI 输出的代码并写入文件系统 关键算法与实现： 2.11.1 多格式解析器 export function parseGeneratedCode(llmOutput: string): GeneratedCode 支持 6 种 Markdown 格式： 1. ```filepath\npath\n``` ```code\ncode\n``` 2. `### 文件: path/to/file.ts\ntypescript\ncode\n 3. `**path/to/file.ts**\ntypescript\ncode\n 4. ## 📄 文件：filename.ext`\ncode\ncode\n 5. ### 📄 文件：filename.ext`\nhtml\ncode\n 6. ## 📄 文件：filename.ext`\n说明\nhtml\ncode\n 2.11.2 去重机制 if (!files.some(f => f.path === filePath)) { files.push({ path: filePath, content, action: 'create' }); } 2.11.3 安全写入 export async function writeGeneratedCode(generated, baseDir) - 自动创建目录：await fs.promises.mkdir(dir, { recursive: true }) - 异常隔离：单个文件失败不阻塞其他文件 - 日志输出：✓ 创建: ${file.path} / ⚠ 跳过: ${file.path} 2.11.4 备份系统 export async function backupFiles(files, baseDir): Promise<BackupInfo> - 备份 ID：crypto.randomBytes(8).toString('hex') - Manifest：JSON 文件记录备份内容和时间戳 - 恢复：restoreFromBackup(backupId) 从 manifest 还原 2.11.5 备份清理 export async function cleanOldBackups(keepCount = 5, baseDir) - 按时间戳排序 - 保留最新 N 个备份 - 递归删除：fs.promises.rm(backupPath, { recursive: true }) --- 2.12 ErrorHandler.ts - 错误处理框架 核心职责：提供重试机制和错误分类 关键算法与实现： 2.12.1 重试包装器 export async function withRetry<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T> - 指数退避：delay * Math.pow(2, attempt - 1) - 条件重试：shouldRetry(error, attempt) - 回调支持：onRetry(error, attempt) 用于日志 2.12.2 可重试错误识别 export function isRetryableError(error: any): boolean { // 网络错误 if (message.includes('network') || message.includes('timeout') || ...) return true; // HTTP 5xx / 429 if (error.statusCode >= 500 || error.statusCode === 429) return true; // Git lock if (message.includes('git') && message.includes('lock')) return true; return false; } 2.12.3 错误类型分类 export enum ErrorType { NETWORK, TIMEOUT, GIT, FILESYSTEM, VALIDATION, PERMISSION, UNKNOWN } export function identifyErrorType(error: any): ErrorType { const message = error.message?.toLowerCase() || ''; if (message.includes('network') || message.includes('econn')) return ErrorType.NETWORK; if (message.includes('timeout')) return ErrorType.TIMEOUT; ... } 2.12.4 建议生成 export function getSuggestion(error: any): string | null { switch (identifyErrorType(error)) { case ErrorType.NETWORK: return '请检查网络连接，稍后重试'; case ErrorType.GIT: return '请检查 Git 仓库状态，确保没有锁定'; ... } } --- 2.13 GitConfigManager.ts - 配置管理器 核心职责：加载、合并和验证工作流配置 关键算法与实现： 2.13.1 配置文件查找 findConfigFile(): string | null { // 当前目录 for (const filename of CONFIG_FILENAMES) { ... } // 向上递归 5 层 let parentDir = path.dirname(this.baseDir); let depth = 0; while (depth < 5) { ... } } 2.13.2 配置合并策略 private mergeConfig(base, override): GitWorkflowConfig { return { auto: { ...base.auto, ...override.auto }, plan: { ...base.plan, ...override.plan }, review: { ...base.review, ...override.review } }; } 2.13.3 优先级层次 CLI 选项 > 配置文件 > 默认值 2.13.4 配置验证 validateConfig(): { valid: boolean; errors: string[] } { if (minScore < 0 || minScore > 100) errors.push('minScore 必须在 0-100 之间'); if (maxTasks < 1 || maxTasks > 100) errors.push('maxTasks 必须在 1-100 之间'); ... } --- 2.14 Semantic 子模块分析 2.14.1 SemanticDiffEngine.ts - 语义差异引擎 核心算法： 文件块拆分： private static splitDiffIntoFiles(diff: string): string[] { // 以 "diff --git " 为分隔符 } 正则匹配识别： const funcRegex = /(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z0-9_]+)\s*\(/; const arrowFuncRegex = /(?:export\s+)?(?:const|let|var)\s+([a-zA-Z0-9_]+)\s*=\s*(?:async\s+)?(?:\(?.*?\)?)\s*=>/; const classRegex = /(?:export\s+)?class\s+([a-zA-Z0-9_]+)/; const interfaceRegex = /(?:export\s+)?interface\s+([a-zA-Z0-9_]+)/; Breaking Change 检测： isBreaking: type === ChangeType.DELETION // 删除即 Breaking 局限性： - 基于正则，无法处理复杂嵌套 - 注释干扰可能导致误判 - 未来演进方向：TypeScript Compiler API（AST 分析） 2.14.2 SemanticCommitParser.ts - 语义提交解析器 核心算法： 影响等级判断： let impactLevel = 'low'; if (structuralChanges.isBreaking) impactLevel = 'breaking'; else if (files.length > 5 || changes.length > 3) impactLevel = 'high'; else if (files.length > 2 || changes.length > 0) impactLevel = 'medium'; 语义摘要生成： // 结合原始消息 + 结构化变更 → AI 生成技术意图总结 const prompt = `原始消息: ${commit.message}\n结构化变更:\n${structuralDesc}`; 历史趋势分析： // 总结最近 N 个提交 → 识别开发阶段/趋势 const historyData = explanations.map(e => `- [${e.impactLevel}] ${e.semanticSummary}`); --- 3. 设计模式与架构原则 3.1 分层设计 ┌─────────────────────────────────────┐ │ CLI Command Layer (src/cli) │ ├─────────────────────────────────────┤ │ Business Logic Layer │ │ - BranchAdvisor │ │ - SmartCommitManager │ │ - CodeReviewer │ ├─────────────────────────────────────┤ │ Core Service Layer │ │ - GitService (Git Wrapper) │ │ - GitContextAggregator (Policy) │ │ - ModelRouter (AI Abstraction) │ ├─────────────────────────────────────┤ │ Utility Layer │ │ - ErrorHandler, ConfigManager │ │ - TodoManager, ProgressManager │ └─────────────────────────────────────┘ 3.2 关键设计模式 3.2.1 Facade Pattern - GitService 封装所有 Git 命令 - 提供类型安全的高级 API - 隐藏 child_process 细节 3.2.2 Strategy Pattern - ReviewLevel 枚举定义审查策略 - DegradationPolicy 动态降级策略 - 规则引擎与 AI 生成的双模式 3.2.3 Template Method - withRetry 定义重试流程骨架 - 子类通过 shouldRetry 自定义条件 3.2.4 Builder Pattern - ContextMetaBuilder 构建审计元数据 - 分步设置 provenance、confidence、clipping 3.2.5 Policy Object - GitContextAggregator.ensureStaged 强制规则 - 分离事实采集与业务约束 3.3 架构原则 3.3.1 单一职责 - GitService：仅负责 Git 操作 - CodeReviewer：仅负责审查逻辑 - ContextGatherer：仅负责上下文采集 3.3.2 依赖注入 constructor( private gitService: GitService, private router?: ModelRouter ) - 通过构造函数注入依赖 - 便于测试和模块替换 3.3.3 防御性编程 - Null 安全：execSafe 返回 null 而非抛异常 - 输入校验：配置验证、语法校验、Schema Guard - 容错设计：AI 解析失败时的回退机制 3.3.4 性能优化 - 并行 I/O：Promise.all 并行执行 Git 命令 - Token 保护：Diff 截断、文件树截断 - 缓冲区调优：maxBuffer: 10MB --- 4. 与 CLI 命令的集成关系 4.1 yuangs git commit 调用链： CLI: commit.action ↓ CommitMessageGenerator.generate() ↓ GitContextAggregator.collect() → 获取上下文 ↓ ModelRouter.route() → 选择模型 ↓ generateWithAI() / generateRuleBased() → 生成消息 ↓ GitService.stageFiles() + commit() → 执行提交 4.2 yuangs git review 调用链： CLI: review.action ↓ CodeReviewer.review(level, staged) ↓ GitService.getDiff() → 获取变更 ↓ buildReviewPrompt() → 构建 Prompt ↓ ModelRouter.executeTask() → AI 审查 ↓ parseReviewResult() → 解析结果 ↓ degradationPolicy.decide() → 降级决策 4.3 yuangs git branch 调用链： CLI: branch.action ↓ BranchAdvisor.suggest() ↓ GitContextAggregator.collect() → 收集状态 ↓ buildPrompt() → 构建决策上下文 ↓ ModelRouter.executeTask() → AI 分析 ↓ parseResponse() + isValidSuggestion() → 校验建议 ↓ CLI: 展示建议或自动执行 4.4 yuangs git conflict 调用链： CLI: conflict.action ↓ GitService.getConflictedFiles() → 检测冲突 ↓ ConflictResolver.resolveFile(file, options) ↓ runLLM() → AI 生成解决方案 ↓ validateSyntax() → 五层校验 ↓ writeFile() + 备份 → 写入解决方案 4.5 yuangs git smart-commit 调用链： CLI: smart-commit.action ↓ SmartCommitManager.planCommits() ↓ SemanticDiffEngine.analyze() → 语义摘要 ↓ runLLM() → AI 分组 ↓ 路径校验与纠错 → 确保完整 ↓ CLI: 用户选择分组 ↓ executeCommitGroup() → 逐组提交 4.6 yuangs git auto 调用链（最复杂）： CLI: auto.action ↓ GitConfigManager.loadConfig() → 加载配置 ↓ ProgressManager.load() → 检测未完成工作流 ↓ TodoManager.parseTodoFile() → 解析任务 ↓ getNextTask() → 选择任务（考虑依赖） ↓ ContextGatherer.gather() → 采集项目上下文 ↓ ModelRouter.executeTask() → AI 生成代码 ↓ parseGeneratedCode() → 解析输出 ↓ backupFiles() → 备份现有文件 ↓ writeGeneratedCode() → 写入代码 ↓ CodeReviewer.review() → 审查生成的代码 ↓ updateTaskStatus() → 更新 todo.md ↓ ProgressManager.save() → 保存进度 ↓ Loop: 继续下一个任务或完成 --- 5. 共享接口与类型系统 5.1 核心类型定义 5.1.1 GitService 导出类型 export interface GitDiff { staged: string | null; unstaged: string | null; files: { staged: string[]; unstaged: string[] }; } export interface GitBranchInfo { current: string; upstream?: string; ahead: number; behind: number; } export interface GitCommitInfo { hash: string; author: string; date: string; message: string; } export interface GitNumstat { added: number; deleted: number; files: string[]; } 5.1.2 CodeReviewer 导出类型 export enum ReviewLevel { QUICK, STANDARD, DEEP } export enum IssueSeverity { INFO, WARNING, ERROR, CRITICAL } export interface ReviewIssue { severity: IssueSeverity; file: string; line?: number; message: string; suggestion?: string; snippet?: string; } export interface ReviewResult { score: number; summary: string; issues: ReviewIssue[]; strengths: string[]; recommendations: string[]; filesReviewed: number; confidence: number; degradation?: { applied, originalLevel, targetLevel, reason }; } 5.1.3 Semantic 类型 export enum ChangeType { ADDITION, DELETION } export enum SemanticCategory { FUNCTION, CLASS, INTERFACE, TYPE, CONSTANT, UNKNOWN } export interface SemanticChange { type: ChangeType; category: SemanticCategory; name: string; details?: string; isBreaking: boolean; } export interface SemanticDiffResult { files: FileSemanticDiff[]; overallSummary: string; isBreaking: boolean; } 5.1.4 TodoManager 类型 export interface TaskStatus { index: number; description: string; completed: boolean; execStatus?: 'pending' | 'in_progress' | 'done' | 'failed'; reviewScore?: number; attempts?: number; backupId?: string; dependsOn?: number[]; priority?: 'high' | 'medium' | 'low'; } export interface TodoMetadata { generatedAt?: string; context?: string; progress?: { completed: number; total: number }; currentTask?: number; } 5.2 常量定义（constants.ts） export const METADATA_PREFIX = '>'; export const TODO_FILENAME = 'todo.md'; export const DEFAULT_PLAN_PROMPT = '分析项目现状并规划下一步开发任务'; export const DEFAULT_AI_MODEL = 'Assistant'; export const MAX_RETRY_ATTEMPTS = 2; export const MIN_REVIEW_SCORE = 85; export const REVIEW_FAILURE_SCORE = 60; export const GIT_CONFLICT_CODES = ['UU', 'AA', 'DD', 'AU', 'UD', 'UA', 'DU']; export const SUPPORTED_AI_MODELS = [ 'gpt-4o', 'gpt-4o-mini', 'claude-3.5-sonnet', 'gemini-2.0-flash', 'Assistant' ]; --- 6. 总结与亮点 6.1 架构亮点 1. 清晰的职责划分： - GitService 专注 Git 底层封装 - GitContextAggregator 统一上下文采集 - 业务逻辑层（Reviewer/Generator/Advisor）独立可测试 2. AI 集成策略： - 通过 ModelRouter 解耦具体模型 - 支持降级策略和容错处理 - 规则引擎 + AI 的双模式设计 3. 安全性保障： - 多层校验（ConflictResolver 的 5 层机制） - 备份系统（CodeGenerator 的增量备份） - 防御性编程（Null 检查、异常隔离） 4. 性能优化： - 并行 I/O（Promise.all） - Token 保护（截断策略） - 缓存机制（配置文件查找） 5. 可扩展性： - 插件化设计（可替换 AI 模型） - 配置驱动（JSON/JS 配置文件） - 类型安全（完善的 TypeScript 接口） 6.2 核心算法总结 ┌────────────────────┬────────────────────────┬────────┬────────────────────────┐ │ 模块 │ 核心算法 │ 复杂度 │ 特点 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ GitService │ Git 命令封装 │ O(1) │ Spawn + stdin 避免转义 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ SemanticDiffEngine │ 正则匹配解析 │ O(n) │ 基于行级扫描 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ TodoManager │ 依赖图遍历 │ O(V+E) │ DFS + 循环检测 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ BranchAdvisor │ AI 决策 + Schema Guard │ O(1) │ 三选一决策树 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ ConflictResolver │ 五层校验机制 │ O(n) │ 逐层验证 │ ├────────────────────┼────────────────────────┼────────┼────────────────────────┤ │ SmartCommitManager │ 路径校验 + 纠错 │ O(n²) │ Set 查找 + 启发式修复 │ └────────────────────┴────────────────────────┴────────┴────────────────────────┘ 6.3 与 CLI 的协同 - 命令层：负责参数解析和用户交互 - 业务层：负责 Git 逻辑和 AI 集成 - 服务层：负责底层操作和状态管理 每个 CLI 命令都通过清晰的调用链连接到核心服务，形成完整的功能闭环。 --- 文件统计： - 核心服务：14 个主要模块 - 代码行数：约 3500 行（不含注释） - 类型定义：20+ 接口，5+ 枚举 - 设计模式：6 种（Facade, Strategy, Template, Builder, Policy, Dependency Injection） 技术栈： - TypeScript - Node.js child_process - Git CLI - Chalk (终端美化) - Crypto (备份 ID) 这是一个设计精良、职责清晰、可扩展性强的 Git 工作流自动化核心层。 ✷ Celebrating… (63s · ↓ 178 tokens · esc to interrupt · Task running for a while) ⎿ Tip: Use /memory to view and manage CodeBuddy memory ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── > ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── ? for shortcuts