AI Agent

继我们之前讨论过的 RoleEngine 核心 之后，是时候填补原生 CLI “大脑”与现实世界通信平台——微信之间的鸿沟了。 在 VisAgent 中，我们不迷信臃肿的重量级框架。相反，我们采用 CLI 原生桥接 (CLI-Native Bridge) 模式。本文将探讨我们如何将 “Clawbot”（我们的微信接口）连接到手搓的 Gemini CLI 内核。 请求流：从聊天到 CLI 该架构是一系列专用工具组成的链条，每个工具只做一件事并做到极致。以下是消息如何从手机传递到 AI 的过程： sequenceDiagram participant User as 📱 微信用户 participant Daemon as ⚙️ WeClaw (Go) participant Bridge as 🌉 visagent_invoke.py participant Engine as 🧠 RoleEngine (Python) participant CLI as 🐚 Gemini CLI (Binary) User->>Daemon: 发送消息 Daemon->>Bridge: 生成进程 (JSON) Bridge->>Engine: 初始化角色 Engine->>CLI: subprocess.run(stdin=prompt) CLI-->>Engine: 原始 AI 输出 Engine->>Engine: 过滤 Agent 噪音 Engine-->>Bridge: OK + 清净输出 Bridge-->>Daemon: JSON 事件 Daemon-->>User: 回复微信 1. 桥梁：visagent_invoke.py 由于我们的微信守护进程 (WeClaw) 是用 Go 编写的，而我们的 Agent 逻辑是用 Python 编写的，我们需要一个轻量化、高性能的桥梁。我们没有采用复杂的 RPC 系统，而是使用了 CLI 桥接。 ...

[!TIP] 目标：实现“零侵入”的架构文档同步与 AI 自驱动的系统修复闭环。 1. 零侵入代谢 (Metabolic Governance) 在手搓 Agent 的过程中，维护 ARCHITECTURE.md 和路由表通常是开发者的噩梦。我们的方案是 Metadata-Free 的“新陈代谢”机制： 感知变更：挂载于 Git 钩子，通过 Git Diff 捕获代码变动。 语义推演：AI 自动分析代码意图，更新机器可读的 .anti_bot_map.md (RAG 路由表) 和人类可读的 ARCHITECTURE.md (架构心法)。 强一致性：彻底消除人工维护文档的成本，文档即代码，代码即地图。 2. 系统的脉搏：Heartbeat 引擎 为了保证 Agent 在无人值守下的稳定性，我们配置了独立的 Heartbeat 进程。它不负责“思考”，只负责定期检查几个容易出问题的状态： def probe_heartbeat_checklist(): """让 AI 定期审计自己的运行状态""" with open(HEARTBEAT_FILE, "r") as f: content = f.read() if "[ ]" in content: # 发现待办或异常 engine = RoleEngine("heartbeat") # 触发 AI 进行自我诊断并更新状态 result = engine.invoke(f"Audit this checklist:\n{content}") 3. 自愈闭环：Self-Repair Agent 当 Heartbeat 探测到网关假死或日志中出现 Traceback 时，会瞬间唤醒 Self-Repair Agent： ...

[!TIP] 目标：通过 CLI 传参实现多模态（视觉/文件）感知，并构建动态加载的插件式技能系统。 1. 让 CLI “看见”世界 多模态能力不一定非要复杂的 SDK。在 VISAGENT 中，我们利用 gemini CLI 对文件路径的天然支持（@path），在 RoleEngine 层实现了感知接入： def _do_raw_invoke(self, message, files=None): # 构造多模态后缀 mm_suffix = "" if files: mm_suffix = "\n" + "\n".join([f"@{f}" for f in files]) # 拼接到最终 Prompt full_input = f"{message}{mm_suffix}" # ... 执行 subprocess 实战经验：为了处理复杂的视觉任务，我们专门封装了 vision_expert 技能，通过 DEEP 模式引导 AI 进行 Chain-of-Thought 推演，从而实现对截图、UI 组件的精确识别。 2. 动态技能树：SkillHandler 手搓系统的灵活性在于 插件化。我们设计了 SkillHandler 模块，它能自动发现 skills/ 目录下的所有能力： 自动化发现：启动时扫描目录。 Manifest 规范：每个技能自带 manifest.json，定义其功能描述与 权限主权 (Sovereignty)。 Sovereignty-Aware：在 Prompt 注入时，系统会明确告知 AI 它被授权访问的 FS 路径和网络域，实现安全约束。 3. 灵活的 Hooks 机制 为了在 AI 调用前后插入逻辑，我们实现了一组 Python Hooks： ...

[!TIP] 目标：从单步对话进化为“计划-模拟-执行”的闭环，并引入基于 YAML 的 DAG 异步编排。 1. 从“聊天”到“执行”：AX (Architect-Executive) 范式 Agent 与普通 Chatbot 的分水岭在于：它是否能将模糊的目标拆解为可操作的步骤。在 VISAGENT 中，我们实现了一套 AX Planner 逻辑： Architect (架构师)：接收需求，输出 TODO.json。此时严禁执行，只准规划。 Simulation (心理演操)：在执行前，让另一个“安全专家”角色对计划进行风险评估。 Executive (执行官)：逐一调用 execute_step 完成任务。 这种“先想后做”的机制，通过简单的 Prompt 约束即可在任意 CLI 上实现： # AX_PLANNING_MODE 核心指令 plan_prompt = ( "You are a specialized Task Architect. Output ONLY valid JSON.\n" "Schema: { 'goal': '...', 'steps': [ {'id': 1, 'desc': '...', 'type': 'EXECUTION'} ] }" ) 2. 线性落后：为什么需要 DAG？ 早期的 AX Planner 是线性的。但现实中，复杂的工程任务往往是拓扑结构：有的步骤可以并行，有的则必须等待前序结果。这就是我们引入 Flow Architect 的原因。 ...

[!TIP] 目标：不依赖框架，通过封装 CLI (如 gemini CLI) 构建具备状态管理与隔离能力的 Agent 引擎。 1. 为什么选择 CLI 而非框架？ VISAGENT 的核心设计哲学是 CLI-Native。相比于黑盒框架，直接封装 CLI (如 gemini CLI) 具有更高的可控性和透明度： 原子性：单次调用即单次推演。 状态透明：Session 的恢复与挂起完全由路径和 Resume 标志控制。 环境隔离：利用系统级工具即可实现权限沙箱。 2. 底层封装：RoleEngineBase 核心逻辑通过 subprocess 触发。为了处理长 Prompt 导致的 Shell 参数溢出，我们坚持使用 stdin 传输： def _do_raw_invoke(self, message: str, context: str = "", files: List[str] = None) -> dict: cmd = [AI_BIN, "--resume", "latest"] if self._get_turns() > 0 else [AI_BIN] # 应对超长 Prompt 使用 stdin use_stdin = len(message + context) > 2000 if use_stdin: cmd += ["-p", "-"] result = subprocess.run( cmd, input=f"{message}\n\n{context}" if use_stdin else None, capture_output=True, text=True, encoding='utf-8' ) if result.returncode == 0: self._inc_turns() return {"ok": True, "output": result.stdout} 3. 隔离与会话管理 凭证沙箱 (Symlink) 为了实现多角色、多项目并发而不产生凭证污染，我们利用 软链接 (Symlink) 动态注入 .gemini 配置： ...