Architecture

Lately, I’ve been cleaning up my own download tools, and one recurring need is YouTube downloading. While there are plenty of tools out there, YouTube’s increasing restrictions on n-sig have caused many open-source projects to fail when fetching high-quality audio tracks. After writing code for many years, I care most about whether a tool is maintainable when it fails. I cleaned up the old setup with three goals: it should run, expose useful logs, and make failures easier to locate. ...

Following our previous discussion on the RoleEngine Core, it’s time to bridge the gap between a raw CLI “brain” and a real-world communication platform: WeChat. In VisAgent, we don’t believe in heavy, bloated frameworks. Instead, we use a CLI-Native Bridge pattern. This post explores how we connected the “Clawbot” (our WeChat interface) to a hand-rolled Gemini CLI kernel. The Request Flow: From Chat to CLI The architecture is a chain of specialized tools, each doing one thing well. Here’s how a message travels from your phone to the AI: ...

[!TIP] Objective: Enable multi-modal (vision/files) perception via CLI parameters and build a dynamically-loaded plugin-based skill system. 1. Letting the CLI “See” the World Multi-modal capabilities don’t necessarily require complex SDKs. In VISAGENT, we leverage the native support for file paths in the gemini CLI (@path) to achieve sensory integration at the RoleEngine layer: def _do_raw_invoke(self, message, files=None): # Construct multi-modal suffix mm_suffix = "" if files: mm_suffix = "\n" + "\n".join([f"@{f}" for f in files]) # Append to final Prompt full_input = f"{message}{mm_suffix}" # ... execute subprocess Field Experience: To handle complex visual tasks, we encapsulated a dedicated vision_expert skill. By using the DEEP reasoning mode, we guide the AI through Chain-of-Thought thinking, enabling precise identification of screenshots and UI components. ...

[!TIP] Objective: Evolve from single-step prompts to a “Plan-Simulate-Execute” closed-loop, introducing YAML-based DAG asynchronous orchestration. 1. From “Chatting” to “Execution”: The AX (Architect-Executive) Paradigm The watershed between a simple Chatbot and an Agent is the ability to decompose vague goals into actionable steps. In VISAGENT, we implemented the AX Planner logic: Architect: Receives requirements and outputs a TODO.json. Execution is forbidden; only planning is allowed. Simulation: Before execution, a “Security Expert” role performs a risk assessment on the plan. Executive: Executes each step via execute_step. This “think before you act” mechanism is easily implemented on any CLI using simple Prompt constraints: ...

[!TIP] Objective: Build an Agent engine with state management and isolation by wrapping a CLI (e.g., gemini CLI) without framework reliance. 1. Why CLI Over Frameworks? VISAGENT’s philosophy is CLI-Native. Directly wrapping a CLI (like gemini CLI) offers superior control and transparency: Atomicity: Each call is a single inference step. State Transparency: Session resume/suspension is strictly controlled by paths and the Resume flag. Isolation: Permission sandboxing is achieved through native OS tools. 2. Core Wrapper: RoleEngineBase Execution is triggered via subprocess. To prevent Shell parameter overflow from long Prompts, we use stdin for transmission: ...

[!IMPORTANT] Core Pain Point: In fast-paced projects, the high cost of manual documentation updates leads to persistent “drifting” or loss of synchronization between code and architectural documentation (README, ARCHITECTURE.md). The Solution: Offload the cognitive burden of “documentation maintenance” from human developers to AI Agents with semantic reasoning capabilities, enabling “metabolic” renewal of architectural maps. After multiple rounds of conversation with AI regarding documentation governance, I’ve distilled a concept for “AI-Native Metabolic Governance V3.0.” This is not just an automation script, but a governance logic designed to make code architecture “come alive.” ...

In the AI era, raw coding skills are devaluing, while system design, cross-domain coordination, and the ability to master complexity are becoming core competencies. This post explores how to transition from executor to coordinator with the help of AI.