@mycodemap/mycodemap 0.1.1 → 0.3.4

package/docs/archive/myclaude.md

@@ -0,0 +1,1084 @@
+
+
+# myclaude 多智能体协作系统深度技术解析
+
+## 1. 系统核心定位与功能概览
+
+### 1.1 项目本质定义
+
+#### 1.1.1 多智能体编排工作流引擎
+
+myclaude 的核心定位是一个**多智能体编排工作流引擎**，其设计哲学源于对现代软件开发复杂性的深刻认知：单一 AI 模型难以同时胜任战略规划与战术执行的双重角色。该系统通过**分层协作架构**将"思考"与"行动"物理分离——Claude Code 作为 Orchestrator（协调器）专注于上下文理解、复杂推理、任务规划和用户交互；而 Codex、Gemini、OpenCode 等后端作为 Executor（执行器）专注于代码生成、测试执行等具体任务 。这种分离并非简单的功能模块化，而是基于对不同 AI 后端能力边界的精准把握：Claude 的 100K+ token 上下文窗口和推理深度适合处理依赖分析和架构决策，而 Codex 在代码生成速度和 IDE 集成方面具有显著优势。
+
+该引擎支持四种主要工作流模式：**Dev Workflow**（标准六阶段开发流程）、**BMAD Agile Workflow**（六角色企业敏捷方法论）、**Requirements-Driven Workflow**（轻量级需求到代码管道）以及 **Development Essentials**（11 个核心开发命令）。这些模式覆盖了从快速原型验证到大规模企业级项目的全场景需求，用户可通过 `npx github:stellarlinkco/myclaude` 进行交互式安装，并根据项目特征动态启用或禁用特定模块 。工作流的编排并非静态脚本执行，而是具备**自适应调整能力**——Orchestrator 会根据执行过程中的中间结果、异常反馈和资源状态，动态优化任务分配策略和执行路径。
+
+#### 1.1.2 统一AI后端接入层
+
+myclaude 的第二个核心定位是**统一 AI 后端接入层**，这一设计直接回应了当前 AI 开发工具生态的碎片化痛点。开发者面临的现实困境是：不同后端在特定场景下各有优势，但切换成本极高——需要重写适配代码、重新调优提示工程、重新建立质量基准。myclaude 通过 `codeagent-wrapper` 组件实现了**真正的零成本切换**：用户只需修改 `--backend codex|claude|gemini` 参数或环境变量，即可更换底层 AI 引擎，而上层工作流逻辑完全无需改动 。
+
+统一接入的技术实现依赖于三层抽象：**Backend 接口抽象**定义了所有后端必须实现的核心操作（`Name()`、`Command()`、`BuildArgs()`）；**配置驱动实例化**通过后端的唯一标识符从工厂方法获取对应实现；**统一响应格式**将所有后端的流式输出转换为标准化的 JSON Stream 格式。以 Codex 后端为例，`CodexBackend.BuildArgs()` 方法会自动构建包含 `--json`、`-C`（工作目录）、`resume`（会话恢复）等 Codex 特有参数的完整命令行；而 `ClaudeBackend.BuildArgs()` 则会构建包含 `--output-format stream-json`、`-r`（允许读取文件）等 Claude 特有参数的命令行 。这种参数构建的差异化处理完全封装在各自的后端实现中，对上层透明。
+
+| 后端类型        | 核心优势                         | 关键 CLI 参数                                                                                                                                                   | 典型应用场景               |
+|-----------------|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
+| **Claude Code** | 长上下文推理、复杂规划、安全对齐   | `--output-format stream-json`、`-r`、`-p`、`-d`、`-v`、`-t`、`-c`、`-m`、`-s`、`-n`、`-y`、`-f`、`-o`、`-e`、`-a`、`-l`、`-u`、`-i`、`-g`、`-b`、`-k`、`-w`、`-z`、`-x`、`-q`、`-j`、`-h` | 架构设计、需求分析、代码审查 |
+| **Codex**       | 代码生成速度、测试覆盖率、IDE 集成 | `e`（编辑模式）、`--json`、`-C`（工作目录）、`--skip-git-repo-check`、`resume`                                                                                          | 功能实现、单元测试生成、重构 |
+| **Gemini**      | 长上下文、多模态、成本效益         | `-o stream-json`、`-y`（自动确认）、`-r`（会话恢复）、`-p`（提示输入）                                                                                                   | 大规模代码库分析、文档生成  |
+| **OpenCode**    | 开源可控、本地部署、隐私保护       | 社区驱动，参数持续演进                                                                                                                                           | 敏感代码处理、离线环境      |
+
+#### 1.1.3 跨平台代码开发自动化框架
+
+myclaude 的第三个核心定位是**跨平台代码开发自动化框架**，其设计充分考虑了现代开发环境的多样性需求。安装系统提供了三种入口：**`install.py`**（Python 跨平台安装器，支持环境检测和依赖管理）、**`install.sh`**（Unix/Linux shell 脚本，支持 bash/zsh/fish）、**`install.bat`**（Windows 批处理脚本，支持 PowerShell 集成），确保不同环境的用户都能便捷部署 。安装后的目录结构标准化为 `~/.claude/`，包含 `bin/codeagent-wrapper` 可执行文件、`CLAUDE.md` 默认文档、`commands/` 命令目录、`agents/` 智能体目录、`skills/` 技能目录、`hooks/` 钩子目录以及 `settings.json` 和 `installed_modules.json` 配置文件 。
+
+跨平台特性的深层体现是对**终端交互的精细处理**。`codeagent-wrapper` 的 `main.go` 中专门检测 `CODEAGENT_ASCII_MODE` 环境变量，用于控制是否使用 ASCII 模式输出，以兼容不同终端的字符集支持能力 。进程管理层面，系统针对 Windows 和 Unix 分别实现了 `process_check_windows.go` 和 `process_check_unix.go`，确保跨平台的进程生命周期管理一致性——包括子进程的创建、监控、信号处理和优雅终止 。这种对边缘场景的周全考虑，使得 myclaude 能够在从个人笔记本到云服务器、从本地开发到 CI/CD 管道的全谱系环境中稳定运行。
+
+### 1.2 核心能力矩阵
+
+#### 1.2.1 多后端AI并行调度（Claude Code/Codex/Gemini/OpenCode）
+
+myclaude 的多后端并行调度能力是其技术架构中最具竞争力的特性之一，实现了**智能路由**与**并行执行**的双重策略。智能路由基于任务特征进行后端选择，决策维度包括：任务类型（代码生成优先 Codex、架构设计优先 Claude、原型验证优先 Gemini）、目标语言（不同后端在不同语言上的训练数据分布差异）、代码库规模（超长上下文需求触发 Gemini 或 Claude）、质量要求（关键路径使用最强后端）、成本约束（批量任务使用经济型后端）以及延迟要求（即时响应场景优化）。
+
+并行执行模式通过 `codeagent-wrapper --parallel` 参数启用，支持**依赖感知的任务分解**。系统会将大型任务拆分为多个可并行子任务，分发到不同后端同时处理，最后聚合结果。这种"分而治之"的策略不仅缩短总体执行时间，还支持 **A/B 测试式的多后端结果对比**——同时向 Codex 和 Gemini 发送相同任务，由 Orchestrator 选择最优结果或合并差异。`executor_concurrent_test.go` 的存在表明该并发执行逻辑经过了专门的测试验证，包括并发安全性、资源竞争检测和性能基准测试 。
+
+#### 1.2.2 专业化智能体角色分工
+
+myclaude 引入了**六角色专业化智能体体系**，这是其区别于通用代码生成工具的关键差异化特性。在 **BMAD（Business-Model-Architecture-Development）工作流**中，六个智能体分别承担：Product Owner（产品负责人，输出 PRD.md）、Architect（架构师，输出 DESIGN.md）、Tech Lead（技术负责人，输出 SPRINT.md）、Developer（开发者，输出代码实现）、Code Reviewer（代码审查者，输出 REVIEW.md）以及 QA Engineer（质量保证工程师，输出 TEST.md）。这种设计直接借鉴了敏捷软件开发方法论中的最佳实践，将人类团队协作的模式映射到 AI 智能体系统中。
+
+角色分工的深层价值在于**认知负载的优化分配**。单一 AI 模型在处理复杂任务时，需要在需求理解、技术决策、实现细节、质量保障等多个维度同时保持高度关注，容易导致"注意力稀释"和输出质量下降。通过角色分离，每个智能体可以使用针对其任务优化的模型配置和提示词策略——Architect 角色可能启用更长的上下文窗口和更强的推理参数，Developer 角色则可能使用经过代码库微调的模型，QA Engineer 角色集成静态分析工具和覆盖率检测。这种专业化不仅提升了各环节输出质量，还使得整个过程**更可审计、可回溯**——每个角色的输出都有明确的文档载体，便于团队协作和知识沉淀。
+
+#### 1.2.3 全生命周期开发流程覆盖
+
+myclaude 的设计目标是覆盖软件开发的完整生命周期，这一覆盖在 **Dev Workflow** 中体现为六个明确的阶段：**需求澄清**（交互式 Q&A 明确范围）→ **Codex 深度分析**（代码库探索与架构决策）→ **开发计划生成**（结构化任务分解与测试要求）→ **并行执行**（Codex 并发处理多个任务）→ **覆盖率验证**（强制 ≥90% 测试覆盖率门槛）→ **完成总结**（报告文件变更与覆盖率统计）。这种端到端的自动化不仅提高了单个任务的完成质量，更重要的是建立了**可重复、可度量的开发流程**。
+
+全生命周期覆盖的深层设计是**质量门禁的强制性嵌入**。90% 测试覆盖率门槛并非可选项，而是系统拒绝合并代码的硬性标准——未达标的实现会被标记为需要补充测试或调整验收标准。这种设计体现了 myclaude 对软件工程最佳实践的坚持：即使在 AI 自动化生成的场景下，也不牺牲质量底线。对于需要快速迭代的场景，系统提供了 **Requirements-Driven Workflow** 作为轻量级替代，将流程压缩为需求生成、实现规划、代码生成、审查测试四个步骤，在敏捷性和规范性之间取得平衡 。
+
+#### 1.2.4 跨终端实时协作支持
+
+跨终端实时协作是 myclaude 针对现代分布式团队需求设计的高级特性，基于 **WebSocket 全双工通信协议**实现。该特性的核心应用场景是：团队成员在不同地理位置、使用不同设备同时参与同一个开发任务，系统通过三层机制保障协作体验：**实时同步层**（操作状态、代码变更、执行结果的毫秒级广播）、**冲突解决层**（OT 或 CRDT 算法处理并发编辑，优先自动合并，复杂场景标记人工介入）、以及**会话管理层**（持久化的协作会话，支持随时加入/离开和历史状态同步）。
+
+跨终端架构的设计挑战在于**网络不稳定性的韧性处理**。myclaude 通过本地队列缓冲机制应对瞬时断网——终端离线期间的操作被暂存到本地队列，网络恢复后自动执行增量同步；通过断点续传机制处理长时间任务的连续性——任务执行状态定期持久化，终端重连后从最近检查点恢复；通过最终一致性机制保障多终端状态的收敛——采用版本向量（Version Vector）算法检测并发操作的因果关系，确保所有终端最终达到一致状态。这些机制的组合使得协作体验对网络波动具有**感知上的透明性**，用户无需关心底层复杂性。
+
+### 1.3 典型应用场景
+
+#### 1.3.1 企业级敏捷软件开发
+
+myclaude 的 **BMAD Agile Workflow** 专为**企业级敏捷软件开发**场景设计，其典型特征是：项目规模大、涉及多个模块和服务、需要跨职能团队协作、对代码质量和可维护性有严格要求、需要完整的审计追踪满足合规要求。在这种场景下，六角色智能体体系能够模拟完整的敏捷团队结构，AI 化的角色执行使得团队可以在不增加人力成本的情况下，获得更规范、更一致的流程执行 。
+
+企业级应用的关键价值在于**文档驱动的可审计性**。PRD.md、DESIGN.md、SPRINT.md、REVIEW.md、TEST.md 等标准化文档不仅是 AI 协作的载体，也是人类团队沟通的基础和合规审计的依据。这种"AI 生成、人类审核"的模式显著提升了文档的及时性和一致性——传统开发中常见的"代码更新了但文档过时"问题得到系统性缓解。同时，结构化的执行报告（v5.4.0 引入）为管理层提供了项目进展的可视化度量，包括任务完成率、测试覆盖率趋势、缺陷密度分布等关键指标 。
+
+#### 1.3.2 复杂系统架构设计
+
+对于**复杂系统架构设计**场景，myclaude 的 Architect 智能体和配套的设计文档模板提供了专门支持。该场景的核心挑战是在多个相互冲突的目标之间进行权衡：性能 vs. 可维护性、灵活性 vs. 一致性、短期交付压力 vs. 长期技术债务。Architect 智能体通过系统化的分析流程应对这些挑战：**现有系统深度分析**（如果是演进式架构，基于 AST 解析和符号分析构建完整依赖图谱）→ **关键架构决策点识别**（ADR 候选集生成）→ **多维度方案评估**（功能需求满足度、质量属性得分、约束条件符合性）→ **权衡优化与文档输出**（包含上下文、决策、后果和合规性考量的完整 DESIGN.md）。
+
+AI 辅助架构设计的价值定位是**"增强而非替代"**——Architect 智能体的输出作为"建议草案"，由人类架构师审核、调整、确认，形成最终决策。这种人机协作模式既发挥了 AI 的信息处理能力（快速分析大规模代码库、检索相关模式、生成候选方案），又保留了人类的价值判断和创造性思维（业务优先级权衡、组织约束考量、创新突破）。对于已有系统的架构演进，系统还支持通过代码分析**反向生成架构视图**，识别技术债务和架构腐化区域，为重构决策提供数据支持。
+
+#### 1.3.3 多语言代码生成与审查
+
+myclaude 的**多语言代码生成与审查**能力源于其底层多后端架构和统一的执行抽象层。不同 AI 后端在不同编程语言上有各自的优势领域：Codex 在 Python、JavaScript/TypeScript、Go 等主流语言上训练数据丰富；Claude Code 在处理复杂语言特性（如 Rust 生命周期、C++ 模板元编程）时更为稳健；Gemini 的长上下文能力使其在处理跨文件依赖时表现优异。系统的**智能路由机制**可以根据目标语言、任务复杂度和代码库规模自动选择最优后端，或者在并行执行模式下同时调用多个后端，通过结果投票或差异分析提高生成质量 。
+
+代码审查场景是 myclaude 的另一优势领域。Code Reviewer 智能体的审查维度远超传统静态分析工具：除了代码风格和潜在缺陷，还能够**验证业务逻辑正确性**（通过需求追溯和测试用例分析）、**评估性能影响**（识别算法复杂度和资源使用模式）、**识别安全漏洞**（基于已知漏洞模式和项目特定安全策略）、以及**提供重构建议**（结合代码异味检测和最佳实践库）。审查结果以结构化的 REVIEW.md 文档输出，包含问题分类、严重程度、具体位置、修复建议和学习参考，使得代码审查不再是瓶颈，而是持续改进的驱动力。
+
+#### 1.3.4 分布式团队协同编程
+
+**分布式团队协同编程**是 myclaude 跨终端实时协作特性的典型应用场景，其设计回应了全球化团队和远程工作普及带来的协作挑战：时区差异导致的实时沟通困难、代码风格和理解的不一致、知识传递的延迟和损耗、代码合并冲突的频繁发生。myclaude 通过**时区感知的工作流调度**优化任务分配——根据团队成员的时区分布，自动将需要实时协作的活动（如架构评审、复杂调试）安排在重叠工作时间窗口，将独立执行的任务（如代码生成、测试运行）安排在非重叠时段 。
+
+文化差异和语言障碍的缓解是另一重要价值点。myclaude 的多语言支持不仅体现在代码生成，还体现在**文档编写和沟通协作中**——系统可以自动将技术文档翻译为团队成员的母语，同时在关键术语处保留原文对照，确保技术准确性。沟通风格的自适应调整使得不同文化背景的团队成员能够以舒适的方式接收信息：对于高语境文化成员提供更丰富的背景说明和关系建立，对于低语境文化成员则突出行动项、决策点和明确的时间承诺。这种**文化智能**显著提升了分布式团队的协作效率和成员满意度。
+
+## 2. 差异化竞争优势分析
+
+### 2.1 架构层面独特性
+
+#### 2.1.1 双智能体核心架构（Orchestrator-Executor分离）
+
+myclaude 最具架构创新性的设计是其**双智能体核心架构**，将 Orchestrator（协调器）和 Executor（执行器）进行明确的职责分离。这一设计的深层逻辑在于**认知资源优化**：Claude Code 的上下文窗口和推理能力最适合处理复杂的规划任务，而将其用于简单的文件读写操作则是一种浪费；反之，Codex 等后端在代码生成上效率高，但缺乏长期规划和跨任务协调能力。通过分离，系统实现了"好钢用在刀刃上"的资源配置 。
+
+Orchestrator 的核心职责包括：意图理解（自然语言→结构化任务）、上下文管理（项目背景、历史操作、相关文档）、计划生成（任务分解、依赖分析、并行识别）、智能体调度（任务-能力匹配、负载均衡）、结果验证（质量检查、异常处理）、以及用户交互（关键决策点确认、进度反馈）。Executor 的核心职责则是：计划执行（具体的代码编辑、文件操作、命令执行）、资源管理（临时文件、网络连接、子进程）、以及结果收集（输出解析、格式化、报告生成）。这种分离带来的工程价值包括：**可测试性**（独立测试，mock 接口隔离依赖）、**可扩展性**（新增后端只需实现接口）、**可观测性**（清晰边界便于瓶颈定位）、以及**可降级性**（后端故障时自动切换）。
+
+#### 2.1.2 可插拔后端设计实现零成本切换
+
+myclaude 的**可插拔后端设计**使得用户可以在不同 AI 后端之间实现近乎零成本的切换。从用户视角，切换后端只需修改 `--backend` 参数或环境变量配置，无需更改工作流定义或任务描述。从实现视角，这种"零成本"来自于三层抽象：**Backend 接口抽象**（定义 `Name()`、`Command()`、`BuildArgs()` 三个核心方法）、**配置驱动实例化**（通过标识符从工厂获取实现）、以及**统一响应格式**（流式 JSON 标准化）。
+
+实际应用场景包括：**成本优化**（根据各后端定价选择最经济选项）、**性能优化**（特定任务选择响应更快或质量更高的后端）、**风险分散**（避免单一供应商依赖）、以及**合规要求**（特定场景使用特定地区部署的模型或开源模型）。`selectBackendFn` 钩子的存在使得切换可以动态进行，甚至基于任务特征自动决策——例如，架构设计类任务路由到 Claude Code，代码生成类任务路由到 Codex，原型验证类任务路由到 Gemini 。
+
+#### 2.1.3 六角色专业化智能体体系（BMAD工作流）
+
+**BMAD 六角色智能体体系**是 myclaude 在企业级场景的核心差异化特性，其设计直接映射敏捷软件开发的最佳实践。六个角色的职责边界和输出物规范如下：
+
+| 角色              | 核心职责                            | 输入文档                   | 输出文档                 | 关键能力配置                            |
+|-------------------|-------------------------------------|----------------------------|--------------------------|-----------------------------------------|
+| **Product Owner** | 需求澄清、用户故事编写、优先级排序    | 用户原始需求、市场/业务背景 | **PRD.md**（产品需求文档） | 利益相关者分析、INVEST 原则、验收标准定义 |
+| **Architect**     | 系统设计、技术决策、非功能性设计      | PRD.md、现有系统分析        | **DESIGN.md**（设计文档）  | 架构模式库、权衡分析框架、ADR 编写        |
+| **Tech Lead**     | 迭代规划、任务分解、依赖管理、风险评估 | DESIGN.md、团队能力评估     | **SPRINT.md**（迭代计划）  | 工作量估算、关键路径识别、资源分配        |
+| **Developer**     | 代码实现、测试编写、文档注释          | SPRINT.md、设计规范         | **Code**（源代码+测试）    | 多语言精通、TDD、重构模式、调试技巧        |
+| **Code Reviewer** | 代码质量检查、缺陷识别、最佳实践验证  | 代码变更、编码规范          | **REVIEW.md**（审查报告）  | 静态分析规则、安全漏洞模式、代码异味检测  |
+| **QA Engineer**   | 测试策略、用例设计、执行验证、质量评估 | 代码实现、验收标准          | **TEST.md**（测试报告）    | 测试覆盖分析、边界条件设计、缺陷根因分析  |
+
+这种角色分工的强制性体现在**流程门禁设计**上：Architect 被禁止直接修改代码文件，必须输出设计文档供 Developer 执行；Code Reviewer 只能添加审查评论而不能直接修改代码；QA Engineer 的 90% 覆盖率门槛未达标时代码无法进入下一阶段。这种**职责分离**模拟了真实开发团队的制衡机制，避免了角色混淆和责任真空 。
+
+### 2.2 技术实现独特性
+
+#### 2.2.1 codeagent-wrapper统一执行抽象层
+
+`codeagent-wrapper` 是 myclaude 技术实现的核心组件，作为**统一执行抽象层**连接上层工作流与底层 AI 后端。该组件采用 Go 语言实现（v5.4.0，505 行代码，12.3 KB），具有高性能、低资源占用、跨平台编译的优势 。其核心设计目标是将所有与后端交互的复杂性——进程管理、I/O 重定向、信号处理、日志记录、超时控制——封装在一个可靠的、可测试的、可复用的组件中。
+
+`codeagent-wrapper` 的模块文件组织体现了清晰的职责分离：
+
+| 文件          | 行数 | 核心职责                           | 关键设计                                                                        |
+|---------------|------|------------------------------------|---------------------------------------------------------------------------------|
+| `main.go`     | 505  | 程序入口、命令解析、主循环协调       | 环境变量检测（`CODEAGENT_ASCII_MODE`）、钩子注入（`selectBackendFn`）、信号处理       |
+| `backend.go`  | 135  | Backend 接口定义、工厂方法、通用适配 | `Backend` 接口三方法、`NewBackend()` 工厂、`buildCodexArgs()`/`buildClaudeArgs()` |
+| `executor.go` | —    | 任务执行引擎、并发控制、生命周期管理 | `Executor` 接口、`Execute()`/`ExecuteParallel()`、goroutine+channel 并发模型      |
+| `config.go`   | —    | 配置加载、验证、动态更新             | `Config` 结构体、`LoadConfig()`、`Validate()`、环境变量注入                        |
+| `logger.go`   | —    | 结构化日志、级别控制、多输出目标     | `Logger` 接口、`JSONLogger`、`FileLogger`、毫秒级时间戳                            |
+| `parser.go`   | —    | 命令行参数解析、自然语言指令分词    | `Parser` 结构体、`ParseCommand()`、`ExtractContext()`                             |
+| `filter.go`   | —    | 输出过滤和清理                     | 敏感信息脱敏、格式标准化                                                         |
+| `utils.go`    | —    | 通用工具函数                       | `Min()`/`Max()`、`ReadFileSafe()`、`WriteFileAtomic()`                            |
+
+测试覆盖方面，`codeagent-wrapper` 目录包含 11 个测试文件，形成完整的测试金字塔：单元测试（`*_test.go`）、集成测试（`main_integration_test.go`）、并发压力测试（`concurrent_stress_test.go`）和基准测试（`bench_test.go`）。这种测试密度体现了对可靠性的高度重视——特别是 `parser_token_too_long_test.go` 专门测试 `bufio.Scanner` token 过长问题修复，`log_writer_limit_test.go` 验证日志写入大小限制，`logger_suffix_test.go` 处理多后端并行日志的 PID 混乱问题，表明该组件经过了严格的边缘情况检验。
+
+#### 2.2.2 智能路由与负载均衡机制
+
+myclaude 的**智能路由与负载均衡机制**是其多后端架构的高级特性。智能路由的决策因素包括：任务类型、目标语言、代码库规模、质量要求、成本约束、延迟要求、历史性能、当前负载。路由算法的实现通过 `selectBackendFn` 钩子函数，支持从简单规则到复杂机器学习模型的灵活替换 。
+
+负载均衡在并发执行场景下发挥作用，将大规模任务分解为多个子任务，分发到不同后端实例执行。`executor_concurrent_test.go` 验证了并发执行的正确性和性能，包括资源竞争、死锁预防、性能退化等场景 。并发执行不仅提高吞吐量，还支持 **A/B 测试式的多后端结果对比**——同时向 Codex 和 Gemini 发送相同任务，然后选择最优结果或合并差异，这种策略可以在不增加延迟的情况下提升输出质量。
+
+#### 2.2.3 结构化执行报告与版本追溯
+
+**v5.4.0 结构化执行报告特性**是 `codeagent-wrapper` 的重要演进，将输出从自由格式文本规范化为 JSON Schema，包含：`task_id`（唯一标识）、`status`（执行状态）、`steps`（执行步骤数组）、`changes`（文件变更列表）、`metrics`（质量指标）、`artifacts`（产物列表）、`cost`（成本信息）、`errors`（错误列表）。结构化报告使得执行结果可以被程序解析，支持：自动化后续处理（CI/CD 集成、项目管理平台同步）、历史执行的高效查询和分析、以及基于质量的自动化决策（如根据覆盖率决定是否合并）。
+
+**版本追溯能力**通过日志系统和配置管理共同实现。`logger.go` 的毫秒级时间戳确保事件顺序的精确重建；`config.go` 的配置解析记录每次执行的完整参数；`installed_modules.json` 跟踪模块版本信息 。这些机制共同支持"可复现性"——给定任务 ID，可以完整重建执行时的环境状态，对于问题排查和合规审计至关重要。
+
+### 2.3 生态集成独特性
+
+#### 2.3.1 模块化技能系统（do/omo/sparv/course）
+
+myclaude 的**模块化技能系统**是其生态扩展性的核心机制。技能（Skill）是对特定领域能力或工具集成的封装，遵循统一接口规范，可动态加载和组合。主要模块包括：
+
+| 模块             | 类型   | 核心功能                                            | 适用场景                 |
+|------------------|--------|-----------------------------------------------------|--------------------------|
+| **do**           | 执行类 | 5 阶段标准开发工作流（需求→设计→实现→测试→部署）      | 大多数常规开发任务       |
+| **omo**          | 编排类 | 多智能体编排与智能路由                              | 需要动态决策的复杂任务   |
+| **bmad**         | 流程类 | 6 角色完整敏捷方法论                                | 大型功能和企业项目       |
+| **requirements** | 执行类 | 轻量级需求到代码管道                                | 快速原型和明确定义的功能 |
+| **essentials**   | 工具类 | 11 个核心开发命令（/code, /debug, /test, /review 等） | 简单任务和日常开发       |
+| **sparv**        | 流程类 | SPARV 五阶段工作流（Specify→Plan→Act→Review→Vault）   | 快速迭代和实验探索       |
+| **course**       | 复合类 | 课程开发（开发+PRD+测试用例生成）                     | 教育内容生产             |
+
+技能的安装和管理通过 `.claude/skills/` 目录和 `skill-rules.json` 配置文件实现，支持从官方仓库、GitHub、或私有源安装。模块间的依赖关系通过 `config.json` 管理，用户可以编辑该文件启用或禁用特定模块 。
+
+#### 2.3.2 钩子机制扩展点（claudekit）
+
+**钩子机制（Hooks）**是 myclaude 提供的底层扩展点，允许用户在关键执行节点插入自定义逻辑。钩子类型包括：`pre-bash`（bash 执行前，用于环境检查、安全扫描、审计日志）、`inject-spec`（规范注入，用于企业规范、项目知识、动态数据的提示词注入）、`log-prompt`（提示词日志，用于调试、优化、合规审计）。钩子的实现可以是 shell 脚本、Python 脚本或任何可执行程序，通过标准输入输出与主流程交互。
+
+`claudekit` 是钩子生态的工具集，提供了常用的钩子模板、调试工具和发布机制。这种设计使得 myclaude 能够在保持核心稳定的同时，适应各种定制化需求——从简单的日志记录到复杂的企业级集成（如与 Jira、Confluence、GitLab 等工具的对接）都可以实现，而无需 fork 和修改核心代码。
+
+#### 2.3.3 命令行与IDE无缝嵌入
+
+myclaude 的**命令行与IDE无缝嵌入**能力体现在两个层面。命令行层面，斜杠命令体系设计直观：`/dev`（完整开发工作流）、`/omo`（多智能体编排）、`/bmad-pilot`（BMAD 工作流引导）、`/requirements-pilot`（需求驱动工作流）、`/code`（直接代码生成）、`/debug`（调试辅助）、`/test`（测试生成）、`/review`（代码审查）、`/optimize`（性能优化）、`/refactor`（代码重构）、`/docs`（文档生成）。每个命令都有清晰的语义和一致的参数风格，学习成本低。
+
+IDE 集成层面，系统通过 **Language Server Protocol（LSP）** 或专用插件与主流编辑器对接，支持：代码补全（基于上下文的智能建议）、内联提示（类型推断、潜在问题、优化机会）、差异视图（AI 生成代码与现有代码的对比）、一键触发工作流（选中代码直接请求审查或重构）。特别值得关注的是对 **Claude Code 原生体验的保留**——当用户在 VS Code 中使用 Claude Code 插件时，myclaude 的工作流可以无缝嵌入，用户无需切换上下文即可享受增强的多智能体能力 。
+
+## 3. 系统架构设计详解
+
+### 3.1 宏观架构层次
+
+#### 3.1.1 用户交互层（CLI/WebSocket/API Gateway）
+
+myclaude 的**用户交互层**设计了三种互补的接入模式。**CLI 模式**通过终端直接调用斜杠命令，支持丰富的标志选项、智能自动补全、彩色输出格式化和详细帮助文档，适合熟练开发者和自动化脚本场景。**WebSocket 模式**提供全双工通信通道，支持操作状态的实时推送、多终端同步、以及代码差异的可视化展示，面向实时协作场景。**API Gateway 模式**提供 RESTful 或 gRPC 接口，允许将 myclaude 能力嵌入现有开发工具链、CI/CD 流水线或自定义应用，面向系统集成场景 。
+
+三种模式共享底层业务逻辑，通过适配器模式进行协议转换。CLI 模式通过 `main.go` 的命令解析逻辑实现；WebSocket 模式需要独立的服务端组件（在提供的代码片段中未完全展现，但从跨终端协作需求可推断其存在）；API Gateway 模式通过标准化的请求/响应格式和认证机制实现。这种设计确保了功能一致性和维护便利性，同时允许各模式针对特定场景进行优化。
+
+#### 3.1.2 协调编排层（Orchestrator核心）
+
+**协调编排层**是系统的"大脑"，由 Claude Code 驱动的 Orchestrator 组件实现。核心职责包括：**意图理解**（自然语言→结构化任务定义）、**上下文管理**（项目背景、历史操作、相关文档的智能选择与压缩）、**计划生成**（任务分解、依赖分析、并行机会识别）、**智能体调度**（任务-能力匹配、负载均衡、动态优化）、**结果验证**（质量检查、异常处理、重试决策）、以及**用户交互**（关键决策点确认、进度透明反馈）。
+
+Orchestrator 的设计挑战在于**长期规划的稳定性**。AI 模型在单次调用中表现良好，但在多步骤、多轮交互场景下容易出现"遗忘"或"偏离目标"。myclaude 通过三种机制缓解这一问题：**显式状态机管理**（每个任务有清晰的状态定义和转换规则）、**结构化中间产物**（PRD.md、DESIGN.md 等作为"外部记忆"）、以及**定期目标重校准**（关键节点回顾原始需求，检测偏离）。`memorys` 目录的存在（在 `feat/intelligent-backend-selection` 分支中可见）暗示了专门的内存/状态管理模块，可能包括短期工作记忆（当前会话上下文）和长期语义记忆（项目知识库）的分离管理 。
+
+#### 3.1.3 执行代理层（Executor集群）
+
+**执行代理层**以 `codeagent-wrapper` 为核心，支持单实例和多实例（集群）两种部署模式。单实例模式下，一个进程顺序或并发处理多个任务，适合个人开发者；集群模式下，多个实例分布在不同计算节点，通过消息队列接收任务，实现水平扩展和高可用。核心设计原则包括：**无状态性**（每个任务独立执行，便于故障恢复和负载均衡）、**幂等性**（同一任务多次执行产生相同结果，便于重试和去重）、以及**可观测性**（详细执行日志、性能指标、资源使用监控）。
+
+Executor 与 Backend 的交互采用**连接池模式**，维护与各 AI 后端的持久连接，减少连接建立开销，同时支持连接健康检查和动态重建。`executor.go` 中的并发模型基于 goroutine 和 channel 实现，`ExecuteParallel()` 方法支持依赖感知的任务并行执行——通过分析任务依赖图，识别可并行子集，分发到不同后端，最后聚合结果 。
+
+#### 3.1.4 后端接入层（Multi-Backend Adapters）
+
+**后端接入层**遵循**适配器模式**，为每个 AI 后端实现统一的 `Backend` 接口。以 Codex 后端为例，适配器处理：CLI 命令构造（`codex e --json --skip-git-repo-check -C <workdir>`）、环境变量注入（API 密钥、组织 ID）、流式 JSON 输出解析、会话 ID 管理（用于恢复）、以及错误码映射。适配器实现需要考虑**后端演进兼容性**——当后端 CLI 更新时，通过版本检测和降级策略平滑处理 。
+
+后端接入层还负责**成本追踪和配额管理**，记录每个后端的调用次数、token 消耗、费用支出，支持预算告警和用量限制。这种设计使得企业用户能够精细控制 AI 使用成本，避免意外超支。
+
+#### 3.1.5 基础设施层（Shared Knowledge Base/消息队列）
+
+**基础设施层**提供通用基础服务能力。**Shared Knowledge Base** 采用分层存储策略：热数据（当前会话上下文）存内存，温数据（近期执行历史）存本地文件系统或嵌入式数据库，冷数据（完整归档）存对象存储。查询接口支持向量相似度搜索（基于代码嵌入）、结构化条件查询、以及混合模式。**消息队列**（RabbitMQ 或 Redis Streams）用于任务分发、事件广播、状态持久化和流量削峰，设计考虑消息的可靠性（至少一次投递、去重）、顺序性保证（同一任务有序处理）、以及延迟控制（优先级队列、超时处理）。
+
+### 3.2 核心组件静态结构
+
+#### 3.2.1 Orchestrator组件职责与边界
+
+##### 3.2.1.1 任务规划与上下文管理
+
+Orchestrator 的**任务规划**采用分层分解策略：识别主要阶段（分析、设计、实现、测试）→ 分解为具体子任务 → 确定执行参数（目标文件、相关上下文、质量要求）。优化技术包括：**基于案例的推理**（检索相似历史任务作为参考）、**约束满足求解**（确保计划满足资源、依赖、时间约束）、以及**蒙特卡洛树搜索**（在候选计划中选择最优）。
+
+**上下文管理**的挑战在于 AI 模型的上下文窗口有限，而实际代码库往往远超限制。myclaude 采用**智能上下文选择策略**：通过代码依赖分析识别最相关文件和符号、使用代码摘要技术压缩大文件表示、维护多层次上下文缓存（项目级、模块级、函数级）、以及支持用户显式指定（`@file` 或 `@symbol` 语法）。这种策略使得系统能够在有限的上下文窗口内，最大化相关信息的价值密度。
+
+##### 3.2.1.2 智能体调度与状态监控
+
+**智能体调度**的输入包括：待执行任务队列（含优先级、截止时间、资源需求）、可用智能体状态（当前负载、专长领域、历史表现）、以及系统全局约束（并发限制、成本预算、质量目标）。调度算法包括：**最短作业优先（SJF）**、**最早截止时间优先（EDF）**、**加权公平队列（WFQ）**、以及**基于学习的调度**（根据历史数据预测优化）。
+
+**状态监控**为调度决策提供实时信息：智能体心跳检测（健康状态、当前任务、预计完成时间）、任务执行进度（已完成步骤、中间产出、遇到的阻塞）、以及系统资源使用（CPU、内存、网络、后端配额）。监控数据通过事件流实时更新，支持调度的动态调整和异常的快速响应。
+
+##### 3.2.1.3 结果验证与用户交互
+
+**结果验证**分为多个层次：语法验证（代码可编译性）、语义验证（功能正确性、边界条件处理）、风格验证（编码规范符合度）、安全验证（漏洞检测、安全策略遵循）、以及性能验证（基准满足度、回归检测）。验证方式包括：静态分析工具、自动化测试、以及 AI 辅助审查。验证不通过时，可触发自动修复、请求重试、或升级处理 。
+
+**用户交互**遵循**最小侵入原则**——只在必要时打断用户，提供清晰上下文和建议选项，支持快速决策。交互时机包括：任务启动前参数确认、计划生成后方案选择、重要变更前影响评估、以及验证失败后处理决策。
+
+#### 3.2.2 codeagent-wrapper组件解剖
+
+##### 3.2.2.1 模块文件组织（main.go/config.go/executor.go/backend.go/logger.go等）
+
+`codeagent-wrapper` 的模块组织已在 2.2.1 节详细呈现。此处补充关键设计细节：`main.go` 中的信号处理实现了**优雅退出机制**——接收到 SIGINT/SIGTERM 时，先尝试取消正在执行的任务，等待超时后强制终止；`backend.go` 中的工厂方法支持**运行时后端注册**，新后端可通过 `registerBackend()` 动态加入；`logger.go` 的多输出目标设计支持**日志分级路由**——调试日志写文件，错误日志同时输出控制台和告警系统 。
+
+##### 3.2.2.2 版本演进轨迹（v5.4.0结构化报告特性）
+
+版本演进的关键节点：早期版本（v1.x-v2.x）聚焦基础功能和 Claude Code 集成；中期版本（v3.x-v4.x）引入多后端支持和配置系统重构；**v5.4.0 里程碑**引入结构化执行报告；v5.5.0 优化流式输出稳定性；v5.6.0 引入执行缓存机制；v5.7.x 聚焦安全性和企业级特性（密钥服务集成、沙箱隔离、审计日志）。版本管理遵循语义化版本控制，发布流程自动化（变更日志生成、版本号递增、构建签名、多平台分发）。
+
+##### 3.2.2.3 安全优化与并发压力测试覆盖
+
+**安全优化**包括：输入验证（白名单校验，防止命令注入）、权限最小化（仅授予必要权限，`--dangerously-skip-permissions` 需显式启用）、敏感信息保护（凭证通过环境变量或密钥服务注入，日志脱敏）、以及沙箱隔离（可选容器化执行环境）。**并发压力测试**覆盖场景：大量短任务快速提交、少量长任务并发执行、后端故障模拟、以及内存泄漏检测。典型配置下（4核8GB，10个并发执行器）可稳定处理每秒 50+ 任务提交，P99 延迟 5 秒以内，故障恢复时间 10 秒以内 。
+
+#### 3.2.3 BMAD六智能体角色体系
+
+六角色的详细职责已在 2.1.3 节的表格中呈现。此处强调**协作协议设计**：角色间的信息流动通过标准化文档实现，每个文档都有明确的 Schema 定义和验证规则。例如，PRD.md 必须包含用户故事列表（每个故事有唯一 ID、优先级、验收标准），DESIGN.md 中的每个架构决策必须引用 PRD.md 中的相关需求 ID，SPRINT.md 中的每个任务必须链接到 DESIGN.md 中的相关组件。这种**可追溯的文档链**确保了需求-设计-实现-验证的完整闭环，是质量保障和合规审计的基础 。
+
+### 3.3 数据流与状态管理
+
+#### 3.3.1 文档驱动工作流（PRD.md→DESIGN.md→SPRINT.md→Code→REVIEW.md→TEST.md）
+
+文档驱动设计的价值已在多处阐述。此处补充**文档生成自动化**的技术实现：每个智能体角色都有专门的提示词模板（`AGENT.md` 配置文件），定义了该角色的输出格式规范。系统通过模板引擎将执行上下文填充到模板中，生成符合 Schema 的 Markdown 文档。文档的渲染和展示通过内置的 Markdown 处理器实现，支持代码高亮、差异对比、以及交互式折叠 。
+
+#### 3.3.2 知识库持久化机制
+
+知识库的数据模型包括：**代码语义索引**（文件、函数、类的向量化表示，支持相似度搜索）、**执行历史记录**（任务定义、参数、结果、反馈的完整序列）、**模式库**（成功的代码模式、架构模式、以及对应的上下文条件）、以及**用户偏好**（常用后端、工作流配置、自定义提示模板）。持久化触发时机：任务完成后即时持久化、定期批量持久化（优化性能）、以及优雅关闭时全量持久化（保证一致性）。
+
+#### 3.3.3 执行状态机转换
+
+任务状态包括：`PENDING`（等待调度）、`ANALYZING`（分析中）、`PLANNING`（规划中）、`EXECUTING`（执行中）、`VERIFYING`（验证中）、`COMPLETED`（已完成）、`FAILED`（失败）、`CANCELLED`（已取消）、`RETRYING`（重试中）。状态转换规则：大多数转换为单向，但失败后可转移到 `RETRYING` 或 `FAILED`，用户可在多数状态下触发 `CANCELLED`。状态机采用事件驱动架构，状态变更触发相应事件处理器 。
+
+## 4. 多智能体通信机制深度剖析
+
+### 4.1 通信模式分类
+
+#### 4.1.1 同步请求-响应模式（API/gRPC）
+
+同步模式适用于需要即时结果、低延迟要求的场景。实现技术支持 **RESTful API**（HTTP/1.1 或 HTTP/2，JSON 序列化，易于调试）和 **gRPC**（HTTP/2，Protocol Buffers，性能更高，支持流式调用）。典型场景：CLI 单次代码生成任务、Orchestrator 查询 Executor 状态、智能体间快速协商。设计挑战在于**超时和错误处理**——AI 后端响应时间从秒级到分钟级不等，需要分级超时策略（初始超时、重试超时、最大超时）和清晰的错误分类（网络错误、后端错误、业务错误）。
+
+#### 4.1.2 异步消息队列模式（RabbitMQ/Redis）
+
+异步模式适用于解耦生产者和消费者、处理峰值流量、需要可靠投递的场景。技术支持 **RabbitMQ**（复杂路由、事务、死信队列）和 **Redis Streams**（轻量级、高性能、集成简单）。典型场景：大规模任务批量提交、长时间运行任务、事件驱动架构（代码提交触发自动审查）。设计关键：**消息格式标准化**（JSON Schema，含消息类型、版本、时间戳、追踪 ID）、**投递语义选择**（至少一次、至多一次、恰好一次）、以及**消费者组管理**（负载均衡、故障转移）。
+
+#### 4.1.3 实时流模式（WebSocket全双工）
+
+WebSocket 模式是跨终端实时协作的基础，提供**全双工通信通道**，支持：操作状态的实时推送（毫秒级延迟）、多终端广播（一对多消息分发）、以及富媒体交互（代码差异可视化、协作光标、语音/视频同步）。协议设计包括：连接建立时的认证和会话恢复、心跳机制检测连接健康、以及断线重连时的状态同步。WebSocket 服务器通常作为独立组件部署，与核心 Orchestrator 通过内部 API 通信 。
+
+### 4.2 codeagent-wrapper内部通信设计
+
+#### 4.2.1 进程内通信架构
+
+##### 4.2.1.1 Backend接口抽象与多实现（CodexBackend/ClaudeBackend）
+
+`Backend` 接口是 `codeagent-wrapper` 的核心抽象，定义三方法：
+
+```go
+type Backend interface {
+    Name() string           // 后端唯一标识，如 "codex"、"claude"
+    Command() string        // 可执行命令名称，如 "codex"、"claude"
+    BuildArgs(cfg *Config, targetArg string) []string  // 根据配置构建完整命令行参数
+}
+```
+
+`CodexBackend` 实现构建包含 `codex e`（编辑模式）、`--json`（JSON 输出）、`-C`（工作目录）、`resume`（会话恢复）等参数的完整命令行。`ClaudeBackend` 实现构建包含 `--output-format stream-json`（流式 JSON）、`-r`（允许读取文件）等参数的命令行。这种设计使得新增后端极为简单——只需实现三方法即可，无需修改其他代码 。
+
+##### 4.2.1.2 Executor并发执行模型
+
+`Executor` 采用 **goroutine + channel** 的 Go 惯用并发模式。`Execute()` 方法处理单任务顺序执行；`ExecuteParallel()` 方法处理多任务并发执行，通过 `sync.WaitGroup` 协调 goroutine 生命周期，通过带缓冲的 channel 收集结果，通过 `context.Context` 实现超时和取消。并发安全通过互斥锁保护共享状态（如日志文件句柄）、通过原子操作更新计数器、通过 channel 传递数据避免共享内存来实现 。
+
+##### 4.2.1.3 Logger结构化日志管道
+
+`Logger` 设计为**多输出目标的管道架构**，支持：`ConsoleLogger`（实时输出到终端，带颜色格式化）、`FileLogger`（持久化到文件，JSON 格式，便于解析）、以及可扩展的 `RemoteLogger`（发送到日志服务，如 ELK、Datadog）。日志事件通过 channel 异步分发到各输出目标，避免 I/O 阻塞影响执行性能。毫秒级时间戳（v5.4.0 引入）支持精确的时序分析和分布式追踪 。
+
+#### 4.2.2 配置驱动通信参数
+
+##### 4.2.2.1 环境变量注入机制（CODEAGENT_ASCII_MODE等）
+
+`main.go` 中检测的关键环境变量：
+
+| 环境变量               | 功能                                  | 默认值    | 典型使用场景                 |
+|------------------------|---------------------------------------|-----------|------------------------------|
+| `CODEAGENT_ASCII_MODE` | 强制 ASCII 输出模式，禁用 Unicode 字符 | `false`   | 终端字符集受限的远程服务器   |
+| `CODEAGENT_BACKEND`    | 指定默认后端                          | `"codex"` | 项目级后端偏好设置           |
+| `CODEAGENT_PARALLEL`   | 启用并行执行模式                      | `"false"` | 大规模批量任务处理           |
+| `CODEAGENT_TIMEOUT`    | 设置执行超时（秒）                      | `"300"`   | 网络不稳定或后端响应慢的环境 |
+| `CODEAGENT_LOG_LEVEL`  | 日志级别（debug/info/warn/error）       | `"info"`  | 调试和问题排查               |
+
+环境变量的加载优先级：命令行参数 > 环境变量 > 配置文件 > 编译时默认值。`loadMinimalEnvSettings()` 函数专门从 `~/.claude/settings.json` 提取环境变量配置，支持字符串类型的键值对注入 。
+
+##### 4.2.2.2 动态后端选择策略
+
+动态后端选择通过 `selectBackendFn` 钩子实现。默认实现 `selectBackend()` 基于简单规则：检查 `--backend` 参数 → 检查 `CODEAGENT_BACKEND` 环境变量 → 使用配置文件中的默认设置 → 回退到 `"codex"`。该钩子可被替换为复杂实现，例如基于任务特征、历史性能、当前负载的机器学习模型。测试代码中通过替换 `selectBackendFn` 为 mock 函数，实现了可测试性 。
+
+##### 4.2.2.3 超时与重试策略配置
+
+超时策略分层设计：**连接超时**（建立与后端进程连接的最大等待）、**执行超时**（单次任务执行的最大时长）、以及**总超时**（含重试的完整流程最大时长）。重试策略包括：固定间隔重试、指数退避重试、以及自适应重试（根据错误类型动态调整）。配置通过 `Config` 结构体的 `ConnectTimeout`、`ExecuteTimeout`、`RetryPolicy` 等字段指定，可在命令行、环境变量、配置文件中设置 。
+
+#### 4.2.3 跨进程通信边界
+
+##### 4.2.3.1 子进程生命周期管理
+
+`codeagent-wrapper` 作为父进程，通过 `os/exec` 包创建和管理 AI 后端子进程。生命周期管理包括：创建时设置环境变量和工作目录、执行中通过 `io.Pipe` 连接标准输入输出、监控中通过 `Process.Wait()` 或信号检测状态、终止时先发送取消信号（SIGINT）允许优雅退出，超时后强制终止（SIGKILL）。`process_check_unix.go` 和 `process_check_windows.go` 提供了平台特定的进程存在性检测和信号发送实现 。
+
+##### 4.2.3.2 标准流重定向与截获
+
+子进程的标准流重定向设计：**stdin** 用于发送用户输入和上下文数据；**stdout** 用于接收正常输出（流式 JSON 或文本）；**stderr** 用于接收错误信息和调试日志。`codeagent-wrapper` 通过 `io.MultiWriter` 实现输出的多路复用——既传递给父进程（Orchestrator），又写入本地日志文件。流式输出的处理采用 `bufio.Scanner` 逐行读取，配合 goroutine 实现实时转发，避免阻塞 。
+
+##### 4.2.3.3 信号处理与优雅退出
+
+`main.go` 中的信号处理逻辑：
+
+```go
+sigChan := make(chan os.Signal, 1)
+signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
+
+go func() {
+    sig := <-sigChan
+    log.Printf("Received signal %v, initiating graceful shutdown...", sig)
+    
+    // 1. 取消正在执行的上下文
+    cancel()
+    
+    // 2. 等待活跃任务完成或超时
+    if !waitForActiveTasks(shutdownTimeout) {
+        log.Println("Graceful shutdown timeout, forcing termination")
+        forceTerminate()
+    }
+    
+    // 3. 刷新日志、关闭文件句柄
+    logger.Close()
+    
+    os.Exit(0)
+}()
+```
+
+这种设计确保在接收到终止信号时，系统有机会保存状态、完成进行中的任务、释放资源，而非突然崩溃导致数据丢失 。
+
+### 4.3 跨终端通信实现
+
+#### 4.3.1 终端接入层设计
+
+##### 4.3.1.1 WebSocket前端代理模式
+
+WebSocket 前端代理是跨终端协作的核心组件，职责包括：连接管理（维护客户端连接池，处理连接建立、认证、心跳、断开）、消息路由（根据消息类型和目标终端进行转发）、以及协议转换（将内部事件格式转换为 WebSocket 帧格式）。部署模式可以是独立服务（与 Orchestrator 同机或分离），或通过反向代理（如 Nginx）集成。性能优化包括：连接复用（HTTP/2 多路复用）、消息压缩（permessage-deflate 扩展）、以及二进制帧（减少 JSON 序列化开销）。
+
+##### 4.3.1.2 HTTP长轮询降级方案
+
+对于不支持 WebSocket 的环境（某些企业防火墙、旧版浏览器），系统提供 **HTTP 长轮询**降级方案。客户端发起请求后，服务器保持连接打开直到有新数据或超时，然后客户端立即发起新请求。这种模拟全双工的方式延迟较高（秒级），但兼容性更好。自动降级机制：连接建立时尝试 WebSocket，失败后自动切换到长轮询，同时提示用户性能影响。
+
+##### 4.3.1.3 统一认证与会话保持
+
+跨终端认证采用 **JWT（JSON Web Token）** 机制：用户首次登录时验证凭证，颁发包含用户 ID、权限、过期时间的签名令牌；后续请求携带令牌，服务器验证签名和有效期；令牌过期前可通过刷新令牌获取新令牌，无需重新登录。会话保持通过会话 ID 实现，多终端使用相同会话 ID 时，服务器将其关联到同一会话状态，实现操作同步。会话状态持久化到 Redis 或数据库，支持服务器重启后的恢复 。
+
+#### 4.3.2 多设备状态同步
+
+##### 4.3.2.1 操作日志实时广播
+
+操作日志是状态同步的基础数据单元，包含：操作类型（编辑、创建、删除、执行）、目标对象（文件路径、任务 ID）、操作内容（差异、参数、结果）、时间戳（毫秒精度）、以及发起者标识。日志通过 WebSocket 广播到所有连接的终端，终端接收后更新本地状态。广播策略：关键操作（如文件保存、任务提交）立即广播；高频操作（如光标移动、输入中）批量或节流广播，减少网络负载 。
+
+##### 4.3.2.2 代码变更增量同步
+
+代码变更采用 **增量 diff 同步**而非完整文件传输，显著减少带宽消耗。diff 算法基于 Myers 算法或类似技术，生成最短的编辑脚本（插入、删除、替换）。对于大文件，采用分块 diff——将文件划分为固定大小的块，仅传输变更的块。冲突检测基于版本号：每个文件有单调递增的版本号，终端提交变更时携带基于的版本号，服务器检测到版本号不匹配时触发冲突解决流程。
+
+##### 4.3.2.3 冲突检测与自动合并
+
+冲突检测采用 **版本向量（Version Vector）** 算法，识别并发操作的因果关系：如果操作 A 的版本向量在所有组件上都小于等于操作 B 的版本向量，则 A 发生在 B 之前（happens-before）；否则为并发（concurrent），需要冲突解决。自动合并策略：对于非重叠区域的编辑（如不同函数），执行三路合并；对于重叠区域的编辑，标记为冲突需人工介入。合并结果广播到所有终端，确保最终一致性 。
+
+#### 4.3.3 离线能力与最终一致性
+
+##### 4.3.3.1 本地队列缓冲机制
+
+终端离线时，操作被暂存到 **本地队列**（通常基于 IndexedDB 或本地文件实现）。队列设计为持久化的、事务性的、支持优先级排序的。操作入队时分配全局唯一 ID 和本地时间戳；队列定期尝试同步，成功则从队列移除，失败则保留并指数退避重试。队列大小限制防止无限增长，超限后提示用户或丢弃低优先级操作。
+
+##### 4.3.3.2 断点续传与状态恢复
+
+长时间任务（如大规模代码库分析）支持 **断点续传**：任务执行状态定期持久化（检查点），包括已完成步骤、中间结果、下一步计划。终端重连后，从最近检查点恢复，而非从头开始。状态恢复还包括：会话上下文的重建（从服务器获取或从本地缓存恢复）、UI 状态的恢复（滚动位置、展开/折叠状态）、以及未读通知的同步。
+
+##### 4.3.3.3 版本向量冲突解决
+
+版本向量的具体实现：每个终端维护一个向量，记录该终端已知的各终端的最新操作计数。操作携带发送者的完整版本向量，接收者通过比较向量判断因果关系。例如，终端 A 的向量 `[A:3, B:2, C:1]` 表示 A 知道 A 有 3 个操作，B 有 2 个，C 有 1 个。如果收到来自 B 的操作，向量 `[A:2, B:3, C:1]`，比较可知 B 的操作 3 与 A 的当前状态并发（A:3 > A:2，但 B:2 < B:3），需要冲突检测。这种算法是分布式系统中实现最终一致性的经典方案 。
+
+## 5. 任务管理与调度系统设计
+
+### 5.1 任务生命周期管理
+
+#### 5.1.1 任务创建与元数据标注
+
+任务创建时，系统生成**全局唯一标识符（UUID）**，并附加丰富的元数据：创建时间戳、发起者标识、任务类型（代码生成、审查、重构等）、关联的项目/代码库、优先级（紧急/高/中/低）、截止时间、预估工作量、以及自定义标签。元数据用于后续的调度决策、资源分配、以及报表分析。任务对象采用不可变设计，状态变更通过创建新实例实现，便于审计和回滚。
+
+#### 5.1.2 任务分解与依赖分析
+
+复杂任务通过**递归分解**转化为可管理的子任务。分解策略基于任务类型：功能实现任务按模块/组件分解；重构任务按影响范围分解；测试任务按覆盖维度分解。依赖分析构建**有向无环图（DAG）**，识别：数据依赖（子任务 B 需要子任务 A 的输出）、资源依赖（两个子任务不能同时使用同一文件）、以及时序依赖（业务逻辑上的先后顺序）。DAG 的拓扑排序确定执行顺序，识别可并行子集。
+
+#### 5.1.3 任务分配与优先级调度
+
+任务分配考虑**多维匹配**：任务所需能力 vs. 智能体专长、任务优先级 vs. 智能体当前负载、任务截止时间 vs. 预计执行时间、以及用户偏好（成本优先 vs. 速度优先 vs. 质量优先）。优先级调度采用**多级反馈队列**：高优先级任务进入短队列，获得更快响应；低优先级任务进入长队列，可能被高优先级任务抢占；同优先级内采用轮转或最短作业优先。饥饿预防机制确保低优先级任务最终得到执行。
+
+#### 5.1.4 任务执行监控与心跳检测
+
+执行监控通过**心跳机制**实现：智能体定期（如每 30 秒）发送心跳消息，包含当前任务、执行进度、资源使用。心跳超时（如 90 秒未收到）触发故障检测，标记智能体为不可用，将其任务重新调度。进度监控通过流式输出解析实现，识别关键里程碑（如"分析完成"、"代码生成中"、"测试运行中"），更新任务状态供用户查看。
+
+#### 5.1.5 任务完成确认与结果归档
+
+任务完成时，系统执行**多维度验证**：输出格式符合预期、关键文件存在且非空、质量指标达标（如覆盖率）、以及无未处理的错误。验证通过后，结果**原子性归档**：代码变更提交到版本控制、文档写入知识库、执行报告持久化、以及通知相关订阅者。归档后任务进入只读状态，支持查询和审计，但不可修改。
+
+### 5.2 智能体协作调度策略
+
+#### 5.2.1 角色感知路由算法
+
+角色感知路由是 BMAD 工作流的核心调度逻辑。算法输入：任务描述（含隐含或显式的角色需求）、可用智能体列表（含角色配置、当前状态、历史表现）。算法步骤：解析任务所需角色（如"设计系统架构"→ Architect）、筛选具备该角色的智能体、按能力匹配度排序（考虑专长领域、历史成功率、当前负载）、以及选择最优智能体或智能体组合。动态角色切换：任务执行过程中，如发现需要其他角色能力（如 Developer 遇到架构问题），可动态请求 Architect 介入。
+
+#### 5.2.2 负载均衡与资源预留
+
+负载均衡在**多个维度**进行：智能体级别（均匀分配任务到各智能体实例）、后端级别（均匀分配负载到各 AI 后端）、以及资源级别（CPU、内存、网络带宽的均衡使用）。资源预留为关键任务保障：高优先级任务可预留特定智能体或后端资源，避免被低优先级任务挤占；预留未使用时自动释放，避免资源浪费。弹性伸缩：负载持续高位时，自动启动新的智能体实例；负载持续低位时，自动释放实例以节约成本。
+
+#### 5.2.3 故障转移与智能体重启
+
+故障检测通过**多指标综合判断**：心跳超时、错误率突增、响应时间异常、以及输出质量下降。故障响应分级：轻微故障（偶发错误）→ 自动重试；中等故障（智能体无响应）→ 任务迁移到备用智能体；严重故障（后端服务不可用）→ 切换到备用后端，通知运维。智能体重启采用**优雅重启**模式：新实例启动并就绪后，旧实例停止接收新任务，完成进行中的任务后退出，实现零停机更新。
+
+#### 5.2.4 流水线并行与批处理优化
+
+流水线并行将任务分解为**多个阶段**，各阶段由不同智能体处理，形成流水线。例如：需求分析 → 架构设计 → 代码生成 → 测试验证，各阶段可重叠执行（阶段 N+1 在阶段 N 输出部分结果时即开始）。批处理优化将多个相似任务合并，共享上下文和预处理，减少重复开销。例如：多个文件的代码审查任务，可共享代码库分析结果，仅针对各文件特定部分生成审查意见。
+
+### 5.3 工作流编排引擎
+
+#### 5.3.1 声明式工作流定义
+
+工作流采用**声明式 YAML 格式**定义，描述"做什么"而非"怎么做"。核心元素：步骤（step，原子操作）、序列（sequence，顺序执行）、并行（parallel，并发执行）、条件（condition，分支选择）、以及循环（loop，迭代执行）。示例片段：
+
+```yaml
+workflow:
+  name: dev-feature
+  steps:
+    - name: clarify-requirements
+      role: product-owner
+      output: PRD.md
+    
+    - name: design-architecture
+      role: architect
+      input: PRD.md
+      output: DESIGN.md
+    
+    - name: implement
+      parallel:
+        - name: backend
+          role: developer
+          tasks: ${DESIGN.md.backend_tasks}
+        - name: frontend
+          role: developer
+          tasks: ${DESIGN.md.frontend_tasks}
+      output: Code
+    
+    - name: review-and-test
+      sequence:
+        - name: code-review
+          role: code-reviewer
+        - name: qa-validation
+          role: qa-engineer
+      condition: coverage >= 90%
+```
+
+#### 5.3.2 条件分支与动态跳转
+
+条件分支基于**运行时数据**动态选择执行路径。条件表达式支持：比较运算（数值、字符串、版本）、逻辑运算（与、或、非）、以及内置函数（文件存在、测试通过、覆盖率达标）。动态跳转允许工作流在执行过程中，根据中间结果跳转到预定义的步骤或子工作流。例如：代码审查发现严重问题，跳转到修复流程；测试覆盖率不足，跳转到补充测试生成。
+
+#### 5.3.3 循环迭代与递归控制
+
+循环用于**批量处理**相似任务，语法支持：for-each（遍历集合）、while（条件循环）、以及 retry（重试直到成功或达上限）。递归控制防止无限循环：最大迭代次数、最大递归深度、以及超时限制。循环变量作用域隔离，避免迭代间的状态污染。
+
+#### 5.3.4 人工审核介入点设计
+
+人工审核点（Human-in-the-Loop, HITL）是工作流中的**强制暂停点**，等待人类决策后继续。设计原则：最小必要（仅在关键决策点设置）、上下文完整（提供决策所需的全部信息）、选项清晰（预定义的选择和后果说明）、以及超时处理（超时后默认行为或升级通知）。典型 HITL 场景：架构方案选择、重大变更确认、质量门禁失败后的处理决策、以及安全敏感操作授权。
+
+## 6. 代码设计与功能映射关系
+
+### 6.1 核心功能-代码文件对应表
+
+| 核心功能           | 主要代码文件                                         | 关键类型/函数                                                          | 设计模式            |
+|--------------------|------------------------------------------------------|------------------------------------------------------------------------|---------------------|
+| **多后端统一接入** | `backend.go`                                         | `Backend` 接口、`CodexBackend`、`ClaudeBackend`、`NewBackend()`           | 策略模式            |
+| **任务执行调度**   | `executor.go`                                        | `Executor` 接口、`Execute()`、`ExecuteParallel()`、`Task` 结构体          | 工作池模式          |
+| **配置解析管理**   | `config.go`                                          | `Config` 结构体、`LoadConfig()`、`Validate()`、`loadMinimalEnvSettings()` | 单例模式            |
+| **结构化日志记录** | `logger.go`                                          | `Logger` 接口、`JSONLogger`、`FileLogger`、`ConsoleLogger`                | 观察者模式、管道模式 |
+| **命令参数解析**   | `parser.go`                                          | `Parser` 结构体、`ParseCommand()`、`ExtractContext()`                    | 解释器模式          |
+| **通用工具函数**   | `utils.go`                                           | `Min()`/`Max()`、`ReadFileSafe()`、`WriteFileAtomic()`                   | 工具类              |
+| **进程生命周期**   | `main.go`                                            | `main()`、`runLoop()`、信号处理逻辑                                      | 主循环模式          |
+| **平台特定处理**   | `process_check_unix.go` / `process_check_windows.go` | `processExists()`、`terminateProcess()`                                 | 桥接模式            |
+
+### 6.2 关键设计模式应用
+
+#### 6.2.1 策略模式（Backend接口多实现）
+
+**策略模式**是 `codeagent-wrapper` 最核心的设计模式。`Backend` 接口定义了所有后端必须实现的策略，不同的后端（Codex、Claude、Gemini、OpenCode）作为具体策略实现。客户端代码（`Executor`）通过 `Backend` 接口调用，无需知道具体后端类型，实现了算法（后端调用方式）与使用算法的代码的解耦。新增后端时，只需添加新的策略实现，符合**开闭原则**。
+
+#### 6.2.2 工厂模式（后端实例化）
+
+**工厂模式**通过 `NewBackend(name string)` 函数实现后端实例的创建。该函数根据名称字符串返回对应的 `Backend` 实现，将实例化逻辑集中管理，便于统一处理错误、缓存实例、以及添加创建时的初始化逻辑。`registerBackend()` 函数支持运行时的后端注册，扩展了工厂的灵活性。
+
+#### 6.2.3 观察者模式（日志事件订阅）
+
+**观察者模式**在 `Logger` 实现中体现：多个输出目标（`ConsoleLogger`、`FileLogger` 等）作为观察者订阅日志事件，日志消息作为事件被广播到所有观察者。这种设计支持动态添加/移除输出目标，以及不同目标的独立配置（格式、级别、过滤条件）。
+
+#### 6.2.4 装饰器模式（执行器包装增强）
+
+**装饰器模式**可用于 `Executor` 的功能增强，例如：添加缓存装饰器（缓存相同任务的结果）、添加重试装饰器（自动重试失败任务）、添加度量装饰器（收集执行指标）。虽然提供的代码片段中未明确展示装饰器实现，但 `Executor` 接口的设计支持这种扩展模式。
+
+### 6.3 测试覆盖策略
+
+| 测试类型         | 文件                        | 覆盖目标         | 关键场景                     |
+|------------------|-----------------------------|------------------|------------------------------|
+| **单元测试**     | `*_test.go`（11 个文件）      | 各模块的独立功能 | 正常路径、边界条件、错误处理   |
+| **集成测试**     | `main_integration_test.go`  | 端到端流程       | 完整命令执行、多模块协作      |
+| **并发压力测试** | `concurrent_stress_test.go` | 并发正确性和性能 | 资源竞争、死锁预防、吞吐量基准 |
+| **基准测试**     | `bench_test.go`             | 性能指标         | 执行延迟、内存分配、CPU 使用   |
+
+测试设计的亮点：**针对性边缘 case 测试**（`parser_token_too_long_test.go` 测试 `bufio.Scanner` token 过长、`log_writer_limit_test.go` 测试日志大小限制、`logger_suffix_test.go` 测试多后端并行日志的 PID 隔离）体现了对生产环境复杂场景的深入思考 。
+
+## 7. 动态行为可视化
+
+### 7.1 代码执行流程图
+
+#### 7.1.1 主程序入口初始化序列
+
+```
+[操作系统] → 加载 codeagent-wrapper 可执行文件
+    ↓
+[main.go:main()] 解析命令行参数（--backend, --parallel, --timeout 等）
+    ↓
+[main.go:loadConfig()] 加载配置文件（~/.claude/settings.json）
+    ↓
+[config.go:LoadConfig()] 合并配置来源（默认值 ← 配置文件 ← 环境变量 ← 命令行参数）
+    ↓
+[main.go:initLogger()] 初始化日志系统（控制台 + 文件输出）
+    ↓
+[main.go:selectBackend()] 选择 AI 后端（参数指定 → 环境变量 → 配置默认 → "codex"）
+    ↓
+[backend.go:NewBackend()] 工厂方法创建具体后端实例（CodexBackend / ClaudeBackend / ...）
+    ↓
+[main.go:runLoop()] 进入主循环，等待用户输入或任务提交
+```
+
+#### 7.1.2 命令解析与路由分发
+
+```
+[用户输入] → "implement user authentication with JWT"
+    ↓
+[parser.go:ParseCommand()] 分词和语义分析
+    ↓
+识别命令类型：直接代码生成 / 完整工作流 / 特定技能调用
+    ↓
+[上下文提取] → 当前目录、相关文件、历史操作、用户偏好
+    ↓
+[路由决策] → 简单任务：直接调用 Executor
+           → 复杂任务：请求 Orchestrator 协调
+    ↓
+[任务封装] → 创建 Task 结构体，填充参数、上下文、回调
+```
+
+#### 7.1.3 后端选择与任务封装
+
+```
+[任务对象] → 分析任务特征（类型、语言、规模、质量要求）
+    ↓
+[selectBackendFn 钩子] → 动态选择最优后端
+    ↓
+[backend.go:BuildArgs()] 构建后端特定的命令行参数
+    ↓
+CodexBackend: ["codex", "e", "--json", "-C", "/project", "implement user auth..."]
+ClaudeBackend: ["claude", "--output-format", "stream-json", "-r", "-p", "implement user auth..."]
+    ↓
+[任务封装完成] → 包含：后端实例、参数列表、超时配置、结果回调
+```
+
+#### 7.1.4 子进程创建与I/O桥接
+
+```
+[executor.go:Execute()] 接收封装好的任务
+    ↓
+[os/exec.Command()] 创建子进程，设置：
+    - Cmd: 后端命令 + 参数
+    - Dir: 工作目录
+    - Env: 环境变量（含 API 密钥）
+    - Stdin/Stdout/Stderr: 管道连接
+    ↓
+[goroutine 1] 逐行读取 stdout → 解析 JSON 流 → 实时转发到 Orchestrator
+[goroutine 2] 读取 stderr → 记录日志 → 错误检测
+    ↓
+[I/O 多路复用] → io.MultiWriter：终端显示 + 文件日志 + 网络发送（WebSocket 模式）
+```
+
+#### 7.1.5 结果收集与报告生成
+
+```
+[子进程结束] → 收集退出码、最终输出、资源使用统计
+    ↓
+[结果解析] → 提取生成的代码、测试报告、覆盖率数据
+    ↓
+[质量验证] → 语法检查、测试运行、覆盖率达标检测
+    ↓
+[结构化报告生成]（v5.4.0+）→ JSON 格式，包含：
+    {
+        "task_id": "...",
+        "status": "success|failed|partial",
+        "changes": [{"file": "...", "operation": "create|modify|delete"}],
+        "metrics": {"coverage": 92.5, "lines_added": 150, "lines_removed": 30},
+        "artifacts": ["src/auth.js", "tests/auth.test.js", "docs/auth.md"],
+        "cost": {"backend_calls": 3, "tokens": 15000, "estimated_usd": 0.45}
+    }
+    ↓
+[结果归档] → 知识库更新、通知发送、后续任务触发
+```
+
+### 7.2 关键时序场景
+
+#### 7.2.1 单次代码生成请求完整时序
+
+##### 7.2.1.1 用户输入→Orchestrator接收
+
+| 时间 | 参与者       | 动作                                    | 数据                    |
+|------|--------------|-----------------------------------------|-------------------------|
+| T0   | 用户         | 在终端输入 `/code "implement JWT auth"` | 自然语言指令            |
+| T1   | CLI 模块     | 解析命令，识别为代码生成请求             | 结构化命令对象          |
+| T2   | CLI 模块     | 调用 Orchestrator API                   | HTTP POST /api/v1/tasks |
+| T3   | Orchestrator | 接收请求，创建任务对象，分配 UUID         | 任务元数据              |
+| T4   | Orchestrator | 加载项目上下文（CLAUDE.md、相关文件）      | 上下文数据              |
+
+##### 7.2.1.2 上下文组装→Backend选择
+
+| 时间 | 参与者       | 动作                 | 决策依据                                |
+|------|--------------|----------------------|-----------------------------------------|
+| T5   | Orchestrator | 分析任务特征         | 类型：代码生成，语言：JavaScript，规模：中等 |
+| T6   | Orchestrator | 调用 selectBackendFn | 优先级：速度 > 成本，推荐：Codex           |
+| T7   | Orchestrator | 检查 Codex 健康状态  | 心跳正常，负载：30%，可用                  |
+| T8   | Orchestrator | 组装完整上下文       | 需求描述 + 项目规范 + 相关代码片段      |
+
+##### 7.2.1.3 codeagent-wrapper调用→AI后端交互
+
+| 时间 | 参与者            | 动作                   | 技术细节                                             |
+|------|-------------------|------------------------|------------------------------------------------------|
+| T9   | Orchestrator      | 调用 codeagent-wrapper | 通过 gRPC/HTTP API                                   |
+| T10  | codeagent-wrapper | 创建 CodexBackend 实例 | 工厂模式                                             |
+| T11  | codeagent-wrapper | 构建命令行参数         | `codex e --json -C /project "implement JWT auth..."` |
+| T12  | codeagent-wrapper | 创建子进程，启动 Codex  | os/exec.Command                                      |
+| T13  | Codex CLI         | 加载模型，解析提示词    | 本地或远程模型服务                                   |
+| T14  | Codex             | 流式生成代码           | 逐 token 输出，JSON 格式                              |
+
+##### 7.2.1.4 流式响应→实时输出渲染
+
+| 时间 | 参与者            | 动作                | 用户体验                            |
+|------|-------------------|---------------------|-------------------------------------|
+| T15  | Codex             | 输出代码片段 1      | codeagent-wrapper 解析并转发        |
+| T16  | codeagent-wrapper | 通过 WebSocket 推送 | 终端实时显示，带语法高亮             |
+| T17  | 用户              | 观察生成过程        | 看到代码逐步构建，可提前发现方向偏差 |
+| T18  | Codex             | 输出代码片段 N      | 完整实现生成完毕                    |
+| T19  | codeagent-wrapper | 检测流结束标记      | 关闭连接，收集最终输出               |
+
+##### 7.2.1.5 结果持久化→知识库更新
+
+| 时间 | 参与者            | 动作                    | 持久化内容                       |
+|------|-------------------|-------------------------|----------------------------------|
+| T20  | codeagent-wrapper | 生成结构化报告          | 代码变更、测试建议、覆盖率预估     |
+| T21  | codeagent-wrapper | 返回结果给 Orchestrator | gRPC/HTTP 响应                   |
+| T22  | Orchestrator      | 验证结果质量            | 语法检查、规范符合度              |
+| T23  | Orchestrator      | 更新知识库              | 执行记录、生成的代码、用户反馈     |
+| T24  | Orchestrator      | 通知用户完成            | 终端输出 + 可选的邮件/Slack 通知 |
+
+#### 7.2.2 多智能体协作开发时序
+
+##### 7.2.2.1 需求分析阶段（Product Owner主导）
+
+```
+[触发] 用户启动 /bmad-pilot "build e-commerce checkout"
+    ↓
+[Product Owner 智能体]
+    ├── 加载角色配置（AGENT.md）
+    ├── 交互式澄清：支付方式？库存检查？优惠券支持？
+    ├── 生成 PRD.md（用户故事、验收标准、优先级）
+    └── 输出：PRD.md v1.0
+    ↓
+[人工审核点] 用户确认或修改 PRD
+    ↓
+[状态更新] 任务标记为"需求已确认"，触发下一阶段
+```
+
+##### 7.2.2.2 架构设计阶段（Architect主导）
+
+```
+[触发] PRD.md 确认事件
+    ↓
+[Architect 智能体]
+    ├── 加载 PRD.md，提取功能和非功能需求
+    ├── 代码库分析（现有支付模块、数据库模型）
+    ├── 技术选型：支付网关（Stripe/PayPal）、数据库事务策略、缓存设计
+    ├── 生成候选架构方案（2-3 个）
+    ├── 权衡分析（性能、成本、可维护性、团队技能）
+    ├── 生成 DESIGN.md（组件图、接口契约、数据流、ADR）
+    └── 输出：DESIGN.md v1.0
+    ↓
+[人工审核点] 技术评审会议，确认架构方案
+    ↓
+[状态更新] 任务标记为"设计已确认"，触发下一阶段
+```
+
+##### 7.2.2.3 迭代规划阶段（Tech Lead主导）
+
+```
+[触发] DESIGN.md 确认事件
+    ↓
+[Tech Lead 智能体]
+    ├── 加载 DESIGN.md，识别实现组件
+    ├── 任务分解：支付 API、订单服务、库存检查、优惠券应用、前端集成
+    ├── 依赖分析：库存检查 ← 订单服务 ← 支付 API
+    ├── 工作量估算（基于历史数据和复杂度）
+    ├── 生成 SPRINT.md（迭代目标、任务清单、里程碑、风险登记）
+    └── 输出：SPRINT.md v1.0
+    ↓
+[状态更新] 任务标记为"计划已确认"，触发并行开发
+```
+
+##### 7.2.2.4 并行开发阶段（多Developer并发）
+
+```
+[触发] SPRINT.md 确认事件
+    ↓
+[并行执行启动]
+    ├── [Developer A] 领取"支付 API"任务
+    │       ├── 加载设计规范（接口契约）
+    │       ├── 生成实现代码（src/payment/api.js）
+    │       ├── 生成单元测试（tests/payment/api.test.js）
+    │       └── 提交：代码 + 测试 + 覆盖率报告
+    │
+    ├── [Developer B] 领取"订单服务"任务（依赖支付 API）
+    │       ├── 等待支付 API 接口定义（或基于 mock 开发）
+    │       ├── 生成实现代码（src/order/service.js）
+    │       ├── 生成集成测试（测试与支付 API 的交互）
+    │       └── 提交：代码 + 测试 + 覆盖率报告
+    │
+    ├── [Developer C] 领取"前端集成"任务（依赖后端 API）
+    │       ├── 基于 OpenAPI 规范生成客户端代码
+    │       ├── 实现 UI 组件和状态管理
+    │       └── 提交：代码 + 组件测试 + 截图
+    │
+    └── [并发协调] Orchestrator 监控各任务进度
+            ├── 检测阻塞（如 Developer B 等待 A 的接口）
+            ├── 触发早期集成（接口定义完成后即通知 B）
+            └── 聚合部分结果，生成整体进度报告
+    ↓
+[状态更新] 所有开发任务完成，触发审查验证
+```
+
+##### 7.2.2.5 审查验证阶段（Reviewer+QA串联）
+
+```
+[触发] 开发任务完成事件
+    ↓
+[Code Reviewer 智能体]（可并行审查多个提交）
+    ├── 加载编码规范和历史审查模式
+    ├── 静态分析：代码风格、复杂度、潜在缺陷
+    ├── 语义分析：业务逻辑正确性、边界条件处理
+    ├── 安全扫描：已知漏洞模式、注入风险
+    ├── 生成 REVIEW.md（问题分类、严重程度、修复建议）
+    └── 输出：REVIEW.md（有条件通过，3 个建议修复）
+    ↓
+[Developer 响应] 修复建议问题，更新代码
+    ↓
+[QA Engineer 智能体]
+    ├── 加载验收标准（来自 PRD.md）
+    ├── 生成测试用例（覆盖功能、边界、异常场景）
+    ├── 执行测试套件（单元 + 集成 + E2E）
+    ├── 覆盖率验证：强制 ≥90%
+    ├── 性能基准测试（响应时间、吞吐量）
+    ├── 生成 TEST.md（测试报告、缺陷分析、质量结论）
+    └── 输出：TEST.md（通过，覆盖率 94%）
+    ↓
+[状态更新] 任务标记为"已完成"，触发部署或归档
+```
+
+#### 7.2.3 跨终端实时协作时序
+
+##### 7.2.3.1 终端A操作→WebSocket上行
+
+| 时间 | 终端A                      | WebSocket 客户端                                                                                         | WebSocket 服务器            |
+|------|----------------------------|----------------------------------------------------------------------------------------------------------|-----------------------------|
+| T0   | 用户编辑文件 `src/auth.js` | 捕获编辑器事件                                                                                           | -                           |
+| T1   | -                          | 生成操作日志：`{type: "edit", file: "src/auth.js", diff: "...", timestamp: 1699123456789, clientId: "A"}` | -                           |
+| T2   | -                          | 发送 WebSocket 帧（文本，压缩）                                                                             | 接收帧，解析 JSON            |
+| T3   | -                          | -                                                                                                        | 验证认证令牌，确认会话权限   |
+| T4   | -                          | -                                                                                                        | 更新会话状态，持久化到 Redis |
+
+##### 7.2.3.2 服务端广播→多终端下行
+
+| 时间 | WebSocket 服务器                                     | 终端B（在线）           | 终端C（离线） |
+|------|------------------------------------------------------|-----------------------|-------------|
+| T5   | 查询同会话的所有连接（A、B）                            | -                     | -           |
+| T6   | 向 B 发送广播帧                                      | 接收帧，解析操作       | -           |
+| T7   | -                                                    | 更新本地状态，渲染变更 | -           |
+| T8   | 检测到 C 离线（连接不存在）                            | -                     | -           |
+| T9   | 将操作加入 C 的离线队列（Redis Stream）                | -                     | -           |
+| T10  | 发送确认给 A（操作已同步到 1 在线终端，1 终端离线队列） | -                     | -           |
+
+##### 7.2.3.3 终端B接收→本地状态合并
+
+| 时间 | 终端B WebSocket 客户端 | 本地状态管理器                      | UI 渲染层                              |
+|------|------------------------|-------------------------------------|----------------------------------------|
+| T6   | 接收广播帧             | -                                   | -                                      |
+| T11  | 解析操作，提取版本向量  | -                                   | -                                      |
+| T12  | -                      | 比较版本向量，检测因果关系           | -                                      |
+| T13  | -                      | 操作并发检测：与本地待发送操作无冲突 | -                                      |
+| T14  | -                      | 应用操作到本地状态（三路合并）        | -                                      |
+| T15  | -                      | 触发状态变更事件                    | -                                      |
+| T16  | -                      | -                                   | 重新渲染编辑器，显示 A 的变更           |
+| T17  | -                      | -                                   | 显示协作提示："用户 A 正在编辑 auth.js" |
+
+##### 7.2.3.4 冲突检测→自动/人工解决
+
+**场景：终端 A 和 B 同时编辑同一文件的同一区域**
+
+| 时间 | 终端A                        | 终端B                                   | 服务器        |
+|------|------------------------------|-----------------------------------------|---------------|
+| T0   | 编辑行 10-15                 | 编辑行 12-18                            | -             |
+| T1   | 发送操作 A                   | 发送操作 B                              | 接收 A，广播   |
+| T2   | -                            | 接收 A 的广播，检测到与本地待发送 B 冲突 | 接收 B        |
+| T3   | -                            | 版本向量分析：A 和 B 并发                | -             |
+| T4   | -                            | 尝试自动合并：重叠区域（12-15），标记冲突   | -             |
+| T5   | 接收 B 的广播，同样检测到冲突 | -                                       | 广播 B        |
+| T6   | 显示冲突标记，暂停自动同步    | 显示冲突标记，暂停自动同步               | -             |
+| T7   | 用户选择：接受 A 的版本       | 用户选择：接受 A 的版本                  | -             |
+| T8   | 发送冲突解决：采用 A          | -                                       | 接收，广播解决 |
+| T9   | -                            | 接收解决，应用，恢复同步                  | -             |
+| T10  | 双方状态一致，继续协作        | -                                       | -             |
+
+## 8. 部署与扩展指南
+
+### 8.1 安装后目录结构
+
+#### 8.1.1 ~/.claude/根目录组织
+
+```
+~/.claude/
+├── bin/
+│   └── codeagent-wrapper          # 核心可执行文件（Go 编译，v5.4.0）
+├── CLAUDE.md                      # 默认项目文档模板
+├── commands/                      # 斜杠命令实现
+│   ├── dev.js                     # /dev 工作流
+│   ├── omo.js                     # /omo 多智能体编排
+│   ├── bmad-pilot.js              # /bmad-pilot 敏捷工作流
+│   └── ...
+├── agents/                        # 智能体角色配置
+│   ├── bmad/                      # BMAD 六角色
+│   │   ├── product-owner/
+│   │   ├── architect/
+│   │   ├── tech-lead/
+│   │   ├── developer/
+│   │   ├── code-reviewer/
+│   │   └── qa-engineer/
+│   └── ...
+├── skills/                        # 可复用技能模块
+│   ├── browser/                   # 浏览器自动化
+│   ├── codeagent/                 # codeagent-wrapper 调用
+│   ├── codex/                     # 直接 Codex 后端
+│   ├── dev/                       # 轻量级开发工作流
+│   └── ...
+├── hooks/                         # 扩展钩子
+│   ├── pre-bash/                  # bash 执行前钩子
+│   ├── inject-spec/               # 规范注入钩子
+│   └── log-prompt/                # 提示词日志钩子
+├── memorys/                       # 状态与记忆管理（实验性）
+├── settings.json                  # 用户级配置（环境变量、偏好）
+├── installed_modules.json         # 已安装模块清单
+└── logs/                          # 执行日志归档
+    ├── 2024-11/
+    │   └── codeagent-20241104-143052.123.log
+    └── ...
+```
+
+#### 8.1.2 bin/codeagent-wrapper可执行文件
+
+`codeagent-wrapper` 是系统的核心执行引擎，技术特征：Go 语言实现，单二进制文件，无运行时依赖；跨平台编译（Linux/macOS/Windows）；支持多种调用模式（独立进程、库调用、gRPC 服务）；内置健康检查和指标端点（`--metrics` 启用 Prometheus 格式）。升级方式：通过 `npx github:stellarlinkco/myclaude --update` 自动检测并下载最新版本；或手动替换二进制文件 。
+
+#### 8.1.3 agents/与skills/模块挂载点
+
+`agents/` 目录包含**智能体角色配置**，每个子目录对应一个角色，包含：`AGENT.md`（角色定义、系统提示词、能力边界）、`tools/`（专用工具脚本）、以及 `templates/`（输出文档模板）。`skills/` 目录包含**可复用技能模块**，每个技能是自包含的功能单元，包含：`skill.json`（元数据、依赖、入口点）、`index.js` 或 `main.py`（实现代码）、以及 `README.md`（使用文档）。模块的加载采用**动态发现机制**：系统启动时扫描目录，解析元数据，注册到内部模块管理器 。
+
+#### 8.1.4 配置文件与钩子目录
+
+**`settings.json`** 用户级配置示例：
+
+```json
+{
+  "env": {
+    "OPENAI_API_KEY": "sk-...",
+    "ANTHROPIC_API_KEY": "sk-ant-...",
+    "CODEAGENT_DEFAULT_BACKEND": "codex",
+    "CODEAGENT_PARALLEL": "true"
+  },
+  "preferences": {
+    "editor": "vscode",
+    "theme": "dark",
+    "language": "zh-CN"
+  },
+  "hooks": {
+    "pre-bash": ["~/.claude/hooks/security-scan.sh"],
+    "inject-spec": ["~/.claude/hooks/company-standards.js"]
+  }
+}
+```
+
+**`hooks/` 目录**支持三级钩子：全局钩子（`~/.claude/hooks/`，所有项目生效）、项目钩子（`<project>/.claude/hooks/`，当前项目生效）、以及临时钩子（命令行 `--hook` 指定）。钩子执行顺序：全局 → 项目 → 临时，同一级别的钩子按字典序执行 。
+
+### 8.2 模块化扩展机制
+
+#### 8.2.1 新Backend接入规范
+
+实现新 Backend 需遵循以下步骤：
+
+1. **创建实现文件**：`backends/<name>_backend.go`
+2. **定义结构体**：实现 `Backend` 接口的三方法
+3. **注册到工厂**：在 `init()` 中调用 `registerBackend()`
+4. **添加测试**：`<name>_backend_test.go`
+5. **更新文档**：README 中说明后端特性、参数、使用场景
+
+示例代码框架：
+
+```go
+package main
+
+type MyBackend struct {
+    name string
+    // 后端特定配置
+}
+
+func (b *MyBackend) Name() string { return "mybackend" }
+
+func (b *MyBackend) Command() string { return "mybackend-cli" }
+
+func (b *MyBackend) BuildArgs(cfg *Config, targetArg string) []string {
+    args := []string{"--format", "json"}
+    if cfg.WorkDir != "" {
+        args = append(args, "--workdir", cfg.WorkDir)
+    }
+    // ... 其他参数
+    args = append(args, targetArg)
+    return args
+}
+
+func init() {
+    registerBackend("mybackend", func() Backend { return &MyBackend{} })
+}
+```
+
+#### 8.2.2 自定义Skill开发模板
+
+Skill 开发模板结构：
+
+```
+my-skill/
+├── skill.json          # 元数据
+├── index.js            # 主入口（或 main.py）
+├── lib/                # 内部模块
+├── templates/          # 输出模板
+├── tests/              # 测试文件
+└── README.md           # 文档
+
+# skill.json
+{
+  "name": "my-skill",
+  "version": "1.0.0",
+  "description": "Custom skill for ...",
+  "entry": "index.js",
+  "runtime": "node18",
+  "dependencies": ["other-skill"],
+  "config": {
+    "param1": {"type": "string", "required": true},
+    "param2": {"type": "number", "default": 100}
+  }
+}
+```
+
+发布方式：推送到 GitHub 仓库，通过 `/skill-install github:user/repo` 安装；或提交到官方 Skill 市场审核 。
+
+#### 8.2.3 钩子插件注册流程
+
+钩子开发步骤：
+
+1. **创建钩子脚本**：可执行文件（shell/python/node），接收标准输入（JSON 格式的事件数据），输出到标准输出（处理结果或修改后的事件）
+2. **放置到 hooks 目录**：全局或项目级别
+3. **配置激活**：在 `settings.json` 中注册，或命令行 `--hook` 临时启用
+4. **测试验证**：使用 `/hook-test <hook-name>` 测试执行
+
+钩子事件数据格式：
+
+```json
+{
+  "event": "pre-bash",
+  "timestamp": "2024-11-04T14:30:52.123Z",
+  "context": {
+    "workdir": "/project",
+    "command": "npm test",
+    "env": {"NODE_ENV": "test"}
+  },
+  "data": {...}
+}
+```
+
+### 8.3 性能调优建议
+
+#### 8.3.1 并发执行参数优化
+
+| 参数                       | 说明           | 默认值  | 调优建议                                |
+|----------------------------|----------------|---------|-----------------------------------------|
+| `CODEAGENT_PARALLEL`       | 启用并行执行   | `false` | 多核环境设为 `true`，IO 密集型任务收益大 |
+| `CODEAGENT_MAX_CONCURRENT` | 最大并发任务数 | `4`     | 根据 CPU 核心数和后端速率限制调整       |
+| `CODEAGENT_QUEUE_SIZE`     | 任务队列大小   | `100`   | 突发流量大时增大，避免任务丢弃           |
+| `CODEAGENT_TASK_TIMEOUT`   | 单任务超时（秒） | `300`   | 复杂任务（如大规模重构）适当增大          |
+
+#### 8.3.2 后端连接池配置
+
+连接池减少后端 CLI 进程的创建开销：
+
+```json
+// settings.json
+{
+  "backendPool": {
+    "codex": {
+      "minIdle": 2,        // 最小空闲连接
+      "maxActive": 10,     // 最大活跃连接
+      "maxWait": "30s",    // 获取连接最大等待
+      "idleTimeout": "5m"  // 空闲连接回收
+    },
+    "claude": {
+      "minIdle": 1,
+      "maxActive": 5,
+      "maxWait": "60s",
+      "idleTimeout": "10m"
+    }
+  }
+}
+```
+
+#### 8.3.3 日志级别与存储策略
+
+| 场景       | 建议配置                              | 说明                        |
+|------------|---------------------------------------|-----------------------------|
+| 开发调试   | `CODEAGENT_LOG_LEVEL=debug`，保留 7 天 | 详细日志便于问题排查        |
+| CI/CD 集成 | `CODEAGENT_LOG_LEVEL=info`，结构化输出 | 与日志平台集成，关注关键事件 |
+| 生产运行   | `CODEAGENT_LOG_LEVEL=warn`，保留 30 天 | 减少存储，关注异常           |
+| 合规审计   | `CODEAGENT_LOG_LEVEL=info`，归档 1 年  | 完整记录，支持审计追溯       |
+
+日志清理策略：`codeagent-wrapper` 内置 `cleanupOldLogs` 函数，扫描日志目录，删除超期文件，保留统计信息（扫描数、删除数、保留数、释放空间）[ ^43^]。
+