# Brainstorming: Tích Hợp Đa Tác Tử (Multi-Agent CLI Pipeline) để Tối Ưu Chi Phí và Hiệu Năng trong AWKit > **Tác giả:** Antigravity Orchestrator > **Ngày cập nhật:** 2026-06-22 > **Phiên bản:** v1.0 > **Trạng thái:** Thảo luận / Ý tưởng thiết kế --- ## 1. Mục tiêu (Objective) Tối ưu hóa chi phí API và nâng cao hiệu suất làm việc bằng cách định tuyến thông minh (Smart Routing) các tác vụ phát triển phần mềm trong framework AWKit đến ba nhóm CLI agents khác nhau: 1. **Claude Code CLI (`claude`)** — Nhóm siêu trí tuệ (Premium Model). 2. **Codex CLI (`codex`)** — Nhóm kiểm thử & thẩm định (Intermediate/Audit Model). 3. **Qwen Code CLI (`qwen-code` hoặc runner tương đương)** — Nhóm mã nguồn mở hiệu năng cao, chi phí rẻ (Cost-optimized Open-Source). --- ## 2. Phân tích Thế mạnh & Định vị Vai trò (Agent Capabilities & Roles) Dựa trên đặc điểm kỹ thuật và chi phí của từng mô hình, ta phân chia vai trò như sau: | CLI Agent | Model Phía Sau | Thế mạnh Đặc trưng | Vai trò trong Hệ thống | Chiến lược Chi phí | | :---------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- | :------------------------------------------------------------ | | **Claude Code** | Claude 3.5 Sonnet / Opus | - Suy luận logic phức tạp cực tốt.
- Lập kế hoạch kiến trúc chính xác.
- Khả năng giải quyết bug khó tốt nhất. | **Architect (Kiến trúc sư)** & **Complex Solver (Giải quyết sự cố lớn)** | Hạn chế số lần gọi (chỉ dùng cho Gate 2 & Gate 4 Complex). | | **Codex CLI** | GPT-4o / Codex custom | - Review code khách quan với [$code-review](~/.agents/skills/code-review/SKILL.md).
- Thiết kế UI & Character assets chuyên sâu bằng [$hatch-pet](~/.codex/skills/hatch-pet/SKILL.md) và [$generate-gui-assets](~/.agents/skills/generate-gui-assets/SKILL.md).
- Tạo UI Shell tĩnh, HTML/CSS, Mockup nhanh.
- Sinh unit/integration tests chuẩn xác. | **Inspector (Kiểm định viên)** & **UI/Asset Builder (Tạo giao diện & Asset)** | Sử dụng trung bình (Gate 2.5 & Gate 5). | | **Qwen Code CLI** | Qwen 2.5 Coder (32B/72B) | - Viết code boilerplate rất nhanh.
- Hiểu tốt nhiều ngôn ngữ lập trình.
- Tốc độ phản hồi cực nhanh, chi phí siêu rẻ hoặc miễn phí (tự host). | **Boilerplate Generator (Sinh mã nền)** & **Local Executor (Thực thi cục bộ)** | Sử dụng tối đa cho các task đơn giản, viết code thô ở Gate 4. | | **Gemini (IDE)** | Gemini 3.5 Flash | - Context window khổng lồ (2M+).
- Tổng hợp và phân tích log/dữ liệu cực lớn.
- Phân tích codebase toàn diện. | **Central Orchestrator (Điều phối viên trung tâm)** & **Context Sync** | Chạy nền liên tục (chi phí cực rẻ). | --- ## 3. Quy trình Điều phối Đa Tác tử theo Hệ thống 7-Gate (7-Gate Routing Pipeline) Để tối ưu hóa chi phí, quy trình xử lý một Task (đi qua các Gate) sẽ được định tuyến tự động như sau: ```mermaid graph TD A[Bắt đầu Task] --> B{Phân loại độ khó Task} B -->|Trivial / Simple| C[Qwen Code / Gemini Flash] B -->|Moderate| D[Phối hợp Qwen & Codex] B -->|Complex| E[Claude Code CLI] subgraph Gate_2 [Gate 2: Spec & Architecture Planning] E -->|Lập kế hoạch chính| F[Claude Code: claude-plan.js] F --> G[Tạo implementation_plan.md] end subgraph Gate_2.5 [Gate 2.5: UI Shell & Assets] G --> H[Codex CLI: codex exec GUI asset] end subgraph Gate_4 [Gate 4: Code Implementation] H --> I{Phân rã Component} I -->|Core Logic phức tạp| J[Claude Code CLI] I -->|Boilerplate / Simple UI| K[Qwen Code CLI] end subgraph Gate_5 [Gate 5: Verification & QA] J & K --> L[Codex CLI: Chạy Test & Code Review] L --> M[Hoàn thành Task] end ``` ### Chi tiết Phân phối theo từng Gate: 1. **Gate 1 & 1.5 (Brainstorm & Module Spec)**: - **Tác tử**: Gemini Flash (Tích hợp sẵn trong IDE) làm việc trực tiếp với User. - **Lý do**: Cần context lớn để hiểu toàn bộ yêu cầu của User và đọc tài liệu cũ. Chi phí cực thấp. 2. **Gate 2 (Spec & Architecture Planning)**: - **Tác tử**: **Claude Code CLI** (`node scripts/claude-plan.js`). - **Lý do**: Lập kế hoạch sai sẽ dẫn đến viết code sai, gây lãng phí lớn chi phí API sau đó. Claude sẽ tạo ra `implementation_plan.md` cực kỳ chuẩn xác và hạn chế tối đa rủi ro regression. 3. **Gate 2.5 (Visual Design & Asset Generation)**: - **Tác tử**: **Codex CLI** (`codex exec`). - **Lý do**: Codex thực hiện xuất sắc việc sinh UI shell/mockup và thiết kế UI & Character assets thông qua tích hợp các kỹ thuật chuyên sâu như [$hatch-pet](~/.codex/skills/hatch-pet/SKILL.md) (cho nhân vật/thú cưng) và [$generate-gui-assets](~/.agents/skills/generate-gui-assets/SKILL.md) (cho các thành phần giao diện). 4. **Gate 4 (Execution - Viết Code)**: - **Task Trivial (Dưới 3 files / Boilerplate)**: Định tuyến 100% qua **Qwen Code CLI** hoặc Gemini Flash. - **Task Moderate/Complex**: - **Qwen Code CLI** sẽ viết các file cấu trúc, helper, boilerplate và shell UI (Phase A + Phase B). - **Claude Code CLI** sẽ được gọi để chèn logic cốt lõi (Core Business Logic) và giải quyết các phần tích hợp phức tạp (Phase C). 5. **Gate 5 (Verification & QA)**: - **Tác tử**: **Codex CLI** (phục vụ thẩm định chất lượng cao). - **Lý do**: Codex có kỹ năng rà soát chất lượng code xuất sắc nhờ kỹ thuật [$code-review](~/.agents/skills/code-review/SKILL.md). Nó cũng rà soát sự tuân thủ các quy tắc coding (như Ponytail rules) và tự động sinh unit/integration tests để giảm thiểu rủi ro regression trước khi tích hợp vào nhánh chính. --- ## 4. Giải pháp Tích hợp Kỹ thuật vào AWKit (Technical Integration) Để triển khai ý tưởng này vào AWKit hiện tại, chúng ta cần thực hiện các bước sau: ### Bước 4.1: Bổ sung cấu hình điều hướng trong `.project-identity` Thêm cấu hình điều phối đa tác tử để dễ dàng chuyển đổi chế độ hoạt động: ```json "automation": { "multiAgent": { "enabled": true, "routingMode": "cost-optimized", // "cost-optimized" hoặc "quality-first" "audioAlerts": true, // Bật/tắt âm thanh thông báo cấp độ project (override) "runners": { "codex": "codex" } } } ``` ### Bước 4.1.2: Cấu hình cấp độ Global (`~/.awkit_config.json`) Để bật/tắt hoặc tinh chỉnh các tính năng CLI (như âm thanh thông báo) trên toàn bộ thiết bị (global), ta sử dụng tệp cấu hình `~/.awkit_config.json` thông qua lệnh CLI: ```bash # Xem toàn bộ cấu hình global hiện tại awkit config-global list # Bật hoặc tắt âm thanh thông báo hệ thống awkit config-global set audioAlerts false awkit config-global set audioAlerts true # Lấy giá trị của một cấu hình cụ thể awkit config-global get audioAlerts ``` *Ghi chú:* Cấu hình `audioAlerts` cục bộ trong `.project-identity` của dự án sẽ được ưu tiên cao hơn cấu hình global này. ### Bước 4.2: Xây dựng Qwen CLI Wrapper (`scripts/qwen-plan.js` hoặc `scripts/qwen-exec.js`) Do Qwen CLI có thể chạy thông qua Ollama (local) hoặc qua API của các nhà cung cấp giá rẻ (OpenRouter, TogetherAI, v.v.), ta có thể viết một script trung gian để gọi: ```javascript // scripts/qwen-exec.js const { execSync } = require("child_process"); // Ví dụ: gọi Ollama chạy local model qwen2.5-coder:32b const prompt = process.argv[2]; try { const output = execSync(`ollama run qwen2.5-coder "${prompt}"`, { encoding: "utf8", }); console.log(output); } catch (e) { // Fallback sang API hoặc Gemini Flash } ``` ### Bước 4.3: Cập nhật Multi-Model Pipeline (`scripts/multi-model-pipeline.js`) Chỉnh sửa pipeline hiện tại để tích hợp tác tử Qwen vào giai đoạn Code Step: - **Trước đây**: Chỉ dùng `gemini-2.5-flash` hoặc `claude-opus`. - **Mới**: Định tuyến thông minh: ```javascript if (taskDifficulty === "trivial" || routingMode === "cost-optimized") { runQwenCodeStep(featureName); } else { runClaudeCodeStep(featureName); } ``` --- ## 5. Đánh giá Hiệu quả Chi phí (Cost-Benefit Analysis) Giả sử một task phát triển tính năng trung bình tiêu tốn khoảng **100,000 input tokens** và **10,000 output tokens**: | Chiến lược | Chi tiết phân phối | Chi phí ước tính (USD/Task) | Tỷ lệ Tiết kiệm | | :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------- | :---------------------------------------------------------------------------------------------------- | | **Chỉ dùng Claude 3.5** | 100% sử dụng Claude | ~$0.45 | 0% (Mốc chuẩn) | | **Chỉ dùng Gemini Flash** | 100% sử dụng Gemini Flash | ~$0.012 | 97% (Nhưng chất lượng logic phức tạp có thể giảm) | | **Đa Tác tử (Multi-Agent Pipeline)** | - **Claude** (10% tokens cho Planning)
- **Qwen Coder** (80% tokens cho Boilerplate & Coding - Local/Free)
- **Codex** (10% tokens cho Review & Test) | **~$0.07** | **~85% Tiết kiệm** mà vẫn giữ được chất lượng kiến trúc của Claude và chất lượng kiểm định của Codex. | --- ## 6. Cơ Chế Hoạt Động Chi Tiết (How it Works) Cơ chế điều phối sub-agent CLI trong AWKit hoạt động theo 6 bước tuần tự: 1. **Nhận diện và Kích hoạt (Trigger Detection)**: Dựa trên Gate hiện tại (Gate 2, 2.5, 4, 5) hoặc độ phức tạp của task (Trivial, Moderate, Complex), Central Agent (Gemini Flash) xác định CLI agent cần dùng. 2. **Thu thập Ngữ cảnh (Context Gathering)**: Central Agent tự động đóng gói các tài liệu liên quan (`.project-identity`, `implementation_plan.md`, `git diff`...) thành một prompt có cấu trúc. 3. **Chạy Trực Tiếp / Ủy quyền (Execution Delegation)**: Chạy CLI qua terminal bằng lệnh `run_command` hoặc thông qua các wrapper script chuyên dụng (như `scripts/multi-model-pipeline.js`, `scripts/claude-plan.js`). 4. **Cơ chế Dự phòng (Graceful Fallback)**: Nếu CLI không được cài đặt (Exit code `127`) hoặc gặp lỗi xác thực (Exit code `2`), hệ thống sẽ tự động chuyển sang mô hình mặc định trong IDE mà không làm gián đoạn luồng làm việc. 5. **Ghi nhận & Tiêu thụ Báo cáo (Result Consumption)**: Kết quả từ CLI được lưu dưới dạng file báo cáo (`.md` hoặc `.json`) trong thư mục `codex-reports/` hoặc `brain/`. Central Agent sẽ đọc báo cáo này để cập nhật ngữ cảnh và tiếp tục thực hiện mã nguồn. 6. **Thông Báo Hoàn Tất Bằng Âm Thanh (Audio Notification)**: Đối với các tác vụ chạy nền (background tasks) tốn thời gian, hệ thống tự động phát âm thanh hệ thống (ví dụ: `afplay /System/Library/Sounds/Glass.aiff`) và thông báo bằng giọng nói (ví dụ: `say "Done"`) trên macOS để thông báo cho người dùng khi quy trình hoàn thành. --- ## 7. Khảo Sát Môi Trường Thực Tế & Thử Nghiệm (Environment Audit & Prototype) Kết quả khảo sát môi trường tại máy local `/Users/trungkientn/Dev/NodeJS/main-awf`: * **Codex CLI**: ✅ Đã được cài đặt tại `/Users/trungkientn/.nvm/versions/node/v22.22.0/bin/codex`. * **agy CLI (Gemini)**: ✅ Đã được cài đặt tại `/Users/trungkientn/.local/bin/agy` (Version 1.0.0). * **Claude Code CLI**: ✅ Đã cài đặt dưới dạng alias, trỏ trực tiếp đến `/Users/trungkientn/.claude/local/claude` (Sử dụng đường dẫn tuyệt đối này trong các script tự động hóa). * **Qwen Code CLI**: ✅ Đã được cài đặt với tên lệnh `qwen` tại `/Users/trungkientn/.nvm/versions/node/v22.22.0/bin/qwen`. ### Kết Quả Thử Nghiệm Thực Tế (Test Run Results - 2026-06-22): #### 1. Kiểm thử đơn lẻ (Unit Test Run): - **agy CLI (Gemini)**: ✅ Thành công phản hồi câu hỏi lý thuyết sau `20,195ms`. - **Codex CLI (OpenAI - Model: `gpt-5.5`)**: ✅ Thành công review mã nguồn cứng API key sau `10,182ms`. #### 2. Kiểm thử phối hợp chuỗi (Multi-Agent Pipeline Test Run): Đã chạy thành công kịch bản lập kế hoạch, sinh mã nguồn và rà soát tự động cho hàm Fibonacci memoization thông qua script `run_multi_agent_pipeline.js`: - **Bước 1: Claude CLI (Architect)**: ✅ Thành công thiết kế sơ đồ logic và kế hoạch memoization lưu tại [test_plan.md](file:///Users/trungkientn/.gemini/antigravity-ide/brain/c843a673-f692-4562-a065-0000e76bff71/scratch/test_plan.md). - **Bước 2: Qwen CLI (Executor)**: ✅ Thành công đọc kế hoạch của Claude và viết mã nguồn JavaScript tương thích 100%, lưu tại [test_code.js](file:///Users/trungkientn/.gemini/antigravity-ide/brain/c843a673-f692-4562-a065-0000e76bff71/scratch/test_code.js) (`21,237ms`). - **Bước 3: Codex CLI (Inspector)**: ✅ Thành công đối chiếu `test_code.js` với `test_plan.md`, chỉ ra 2 cảnh báo độ ưu tiên Medium (tràn số khi `n >= 79` và lỗi call stack đệ quy sâu) kèm 2 nhận xét Low, lưu tại [test_review.md](file:///Users/trungkientn/.gemini/antigravity-ide/brain/c843a673-f692-4562-a065-0000e76bff71/scratch/test_review.md) (`23,250ms`). - **Kết luận**: Quy trình hoạt động đồng bộ hoàn hảo. Sự phối hợp giúp phân tách trách nhiệm rõ rệt: thiết kế cao cấp (Claude) -> lập trình cơ bản (Qwen) -> rà soát chi tiết (Codex). Log đầy đủ tại [pipeline_run_log.json](file:///Users/trungkientn/.gemini/antigravity-ide/brain/c843a673-f692-4562-a065-0000e76bff71/scratch/pipeline_run_log.json). --- ## 8. Các Bước Tiếp Theo Đề Xuất (Next Steps) 1. **Tạo kịch bản thử nghiệm thực tế (Test Run Script)**: Viết script `test_sub_agents.js` trong thư mục `scratch/` để gọi thử `codex` và `agy` kiểm tra logic review/plan thô. 2. **Cập nhật wrapper script gọi Claude và Qwen**: Thiết lập đường dẫn tuyệt đối `/Users/trungkientn/.claude/local/claude` cho Claude và tên lệnh `qwen` cho Qwen trong hệ thống multi-model routing của AWKit. 3. **Đóng gói Skill**: Phát triển `skills/qwen-conductor/SKILL.md` để tự động hóa định tuyến.