ForgeFlow: Tự động hóa CLI AI mạnh mẽ trong tmux

ForgeFlow là một công cụ tự động hóa mạnh mẽ cho các CLI AI tương tác như Gemini và Codex, hoạt động trong phiên tmux. Với kiến trúc "adapter + rules" sạch sẽ, ForgeFlow phát hiện các prompt và trạng thái xử lý, gửi các lệnh phù hợp và tiếp tục cho đến khi hoàn thành nhiệm vụ — kèm theo ghi log, khả năng mở rộng và hành vi phục hồi hợp lý.

Mục tiêu của hướng dẫn này

Hướng dẫn này sẽ giúp bạn:

• Cài đặt và sử dụng ForgeFlow một cách hiệu quả.
• Hiểu rõ về kiến trúc, các giao diện chính và hỗ trợ ANSI.
• Tìm hiểu cách mở rộng với các quy tắc và adapter tùy chỉnh.
• Theo dõi một sơ đồ luồng đơn giản trong Markdown.

Đối tượng sử dụng

• Các lập trình viên làm việc chủ yếu trong terminal và sử dụng CLI AI.
• Các nhóm cần một công cụ lặp lại cho các nhiệm vụ dài hạn, lặp đi lặp lại.
• Bất kỳ ai cần ghi log và khả năng mở rộng đơn giản mà không phải tái tạo lại quy trình.

Yêu cầu hệ thống

• macOS/Linux
• Python 3.9 trở lên
• tmux đã được cài đặt và có trong PATH

Cài đặt và chạy ForgeFlow

Cài đặt cho phát triển (công cụ đã được cố định):

pip install -e .[dev] -c constraints-dev.txt

Cài đặt Runtime:

pip install -e .

Các công cụ hỗ trợ từ Makefile:

• make dev-install — cài đặt các phụ thuộc phát triển với các ràng buộc.
• make lint / make fmt / make test
• make setup-hooks — Git hooks tùy chọn.

Chạy ForgeFlow

forgeflow \  
--session qwen_session \  
--workdir "/abs/path/to/your/project" \  
--ai-cmd "qwen --proxy http://localhost:7890 --yolo" \  
--cli-type gemini \  
--poll 10 \  
--timeout 2000 \  
--log-level INFO \  
--log-file forgeflow.log

Chuyển đổi adapter:

• Sử dụng --cli-type gemini hoặc --cli-type codex (claude_code là một placeholder).

Sử dụng quy tắc dựa trên dự án:

• Thêm {project}_rules.py hoặc {project}.py vào thư mục gốc của dự án hoặc trong thư mục examples/
• Chạy với --project myproject

forgeflow \  
--session qwen_session \  
--workdir "/abs/path/to/your/project" \  
--ai-cmd "qwen --proxy http://localhost:7890 --yolo" \  
--project myproject \  
--cli-type gemini

Ghi log:

• --log-file forgeflow.log sẽ ghi log vào file.
• --no-console sẽ tắt ghi log trên console.
• --log-level hỗ trợ DEBUG/INFO/WARNING/ERROR.

API Python

from forgeflow.core.automation import Config, run_automation

cfg = Config(  
session="qwen_session",  
workdir="/abs/path/to/your/project",  
ai_cmd="qwen --proxy http://localhost:7890 --yolo",  
cli_type="gemini",  
poll_interval=10,  
input_prompt_timeout=2000,  
log_file="forgeflow.log",  
log_to_console=True,  
project="myproject", # optional  
log_level="INFO",  
)  
run_automation(cfg)

Quy tắc: Tùy chỉnh cấp dự án

• Tên file:
  • {project}_rules.py hoặc {project}.py
• Tên hàm (khuyến nghị):
  • build_rules() -> list[Rule]

Ví dụ tối thiểu:

# examples/myproject_rules.py
from forgeflow.core.rules import Rule

def build_rules() -> list[Rule]:  
    def done(output: str) -> bool:  
        return "Tất cả nhiệm vụ đã hoàn thành." in output
    return [
        Rule(check=done, command=None),  # dừng
        Rule(check=lambda out: "Lỗi API" in out, command="continue"),
        Rule(check=lambda out: True, command="continue"),
    ]

Hành vi quy tắc:

• Các quy tắc được đánh giá theo thứ tự, quy tắc khớp đầu tiên sẽ trả về lệnh của mình.
• Nếu lệnh là None, tự động hóa sẽ dừng lại.

Tổng quan về kiến trúc

• Vòng lặp chính (forgeflow/core/automation.py)
  • Tạo/đính kèm phiên tmux.
  • Xác định adapter theo --cli-type.
  • Bắt đầu đầu ra tmux, kiểm tra "prompt vs. processing", đánh giá quy tắc.
  • Khôi phục thời gian chờ: ESC → backspace tiến bộ cho đến khi prompt → gửi tiếp tục.
  • Mức ghi log có thể cấu hình; hỗ trợ đầu ra file và console.
• I/O tmux (forgeflow/core/tmux_ctl.py)
  • Bao encapsulates các thao tác tmux: tạo phiên, gửi phím, bắt đầu pane.
  • capture_output(include_ansi=False) hỗ trợ bắt ANSI thô khi cần.
• Adapters (forgeflow/core/cli_adapters/*)
  • Giao diện CLIAdapter:
    • is_input_prompt(output) -> bool
    • is_input_prompt_with_text(output) -> bool
    • is_task_processing(output) -> bool
    • is_ai_cli_exist(output) -> bool
    • wants_ansi() -> bool — yêu cầu tự động hóa bắt pane với mã ANSI.
  • Các cài đặt: gemini.py, codex.py (placeholder của claude).
  • Giải quyết adapter thông qua get_cli_adapter(cli_type).
• Quy tắc (forgeflow/core/rules.py)
  • Rule(check: Callable[[str], bool], command: str | None).
  • Quy tắc mặc định và next_command(output, rules).
• Tải quy tắc (forgeflow/core/rule_loader.py)
  • Tải động {project}_rules.py hoặc {project}.py từ workdir hoặc examples/

Tiện ích ANSI cho phát hiện thông minh hơn

Một số CLI hiển thị các màu hoặc thuộc tính prompt khác nhau. Bạn có thể chọn bắt ANSI và phân tích nó trong adapter của mình:

• Adapter opt-in: def wants_ansi(self) -> bool: return True
• Tiện ích (forgeflow/core/ansi.py):
  • strip_ansi(text) -> str — loại bỏ tất cả các chuỗi thoát ANSI.
  • parse_ansi_segments(text) -> list[Segment]
    • Chia văn bản thành các đoạn kiểu (theo dõi các thuộc tính SGR).
    • Hỗ trợ in đậm, mờ, nghiêng, gạch chân, nhấp nháy, ngược, gạch chéo.
    • Hỗ trợ cơ bản FG/BG (30–37/90–97/40–47/100–107), 256-color, truecolor.
  • split_segments_lines(segments) -> list[list[Segment]]
    • Chia theo dòng trong khi vẫn giữ nguyên kiểu.

Ví dụ sử dụng trong adapter:

from forgeflow.core.ansi import parse_ansi_segments

class MyAdapter(CLIAdapter):  
    def wants_ansi(self) -> bool:  
        return True

    def is_input_prompt(self, output: str) -> bool:
        # Heuristic ví dụ: tìm kiếm một dấu hiệu màu đỏ ở cuối màn hình
        segments = parse_ansi_segments(output)
        text = ''.join(seg.text for seg in segments)
        return text.rstrip().endswith('>')  # kết hợp với kiểm tra màu sắc

Điều này giữ nguyên hành vi mặc định trong khi cho phép các quy tắc nhận biết màu sắc khi hữu ích.

Sơ đồ luồng đơn giản

flowchart TD  
A[Start forgeflow] --> B[Create/attach tmux session]  
B --> C[Ensure AI CLI running]  
C --> D{Capture output  
(ANSI optional)}  
D --> |prompt & idle| E[Evaluate rules -> command]  
E --> F[Send text + Enter]  
F --> G[Sleep 2s]  
G --> D  
D --> |prompt has text| H[Send Enter]  
H --> G  
D --> |processing| I[Wait poll interval]  
I --> D  
D --> |timeout| J[ESC + progressive backspace]  
J --> K[Send "continue"]  
K --> D  
E --> |None| L[Stop]

Khắc phục sự cố

• “tmux là yêu cầu nhưng không tìm thấy”
  • Cài đặt tmux và đảm bảo tmux -V thành công.
• CLI không được phát hiện là đang chạy
  • Kiểm tra --ai-cmd và cho phép một vài giây sau khi khởi động.
• Không có quy tắc dự án
  • Sử dụng các quy tắc mặc định; thêm quy tắc tùy chỉnh để có kết quả tốt hơn.

Kho lưu trữ và giấy phép

• Repo: https://github.com/kingson4wu/ForgeFlow
• Giấy phép: MIT

Các thực tiễn tốt nhất

• Thực hiện kiểm tra đầu ra thường xuyên để đảm bảo tự động hóa hoạt động đúng cách.
• Sử dụng logging để theo dõi và xử lý lỗi.
• Tùy chỉnh quy tắc cho phù hợp với từng dự án cụ thể.

Cạm bẫy thường gặp

• Không cấu hình chính xác các quy tắc có thể dẫn đến kết quả không như mong đợi.
• Quá nhiều logging có thể làm chậm quá trình tự động hóa.

Mẹo hiệu suất

• Giảm thời gian polling nếu bạn có thể nhận được phản hồi nhanh hơn từ AI CLI.
• Tinh chỉnh các quy tắc để tránh hành vi không cần thiết trong quá trình tự động hóa.

Kết luận

ForgeFlow là một công cụ mạnh mẽ cho việc tự động hóa các CLI AI, giúp cho các lập trình viên tối ưu hóa quy trình làm việc của họ trong tmux. Hãy bắt đầu tích hợp ForgeFlow vào dự án của bạn và trải nghiệm sự khác biệt mà nó mang lại!

Nếu bạn thấy bài viết này hữu ích, hãy chia sẻ với cộng đồng lập trình viên khác và cùng nhau khám phá sức mạnh của ForgeFlow!