手搓系列

[!NOTE] 初心：为了帮儿子在学习时更好地进入状态，我用纯 HTML 手搓了一个极其轻量的“专注力工具箱”。它没有复杂的后台，只有三个最原始、最直接的模块。 在这篇文章中，我将分享这个工具的设计逻辑。你可以直接在导航栏点击 专注力工具 体验。 1. 为什么是“手搓”？ 市面上有很多专注力 App，但它们往往： 功能太重：容易引起孩子在 App 内部的二次分心。 缺乏针对性：我需要的是一个能够配合学习节奏（15-20 分钟一节）的纯净环境。 于是我写了这个不到 400 行代码的 HTML 页面。 2. 三个核心模块 A. 视觉热身 (Visual Warmup) 在进入正式学习前，大脑需要一个“启动仪式”。 原理：盯着屏幕中央的圆点持续 30 秒，尽量不眨眼。这能锻炼眼部肌肉，强迫神经系统从发散状态收束到一点。 色彩选择：默认使用 Tiffany Blue (蒂芙尼蓝)，这种颜色能给人带来宁静、克制的视觉心理暗示。 B. 极致专注计时 (Focus Timer) 我们不崇尚长时间苦学，而是强调高效的“短周期推演”。 15/20 分钟闭环：配合孩子的专注时长，设置了扇形和网格两种视觉反馈。 视觉化流逝：看着红色扇面一点点缩减，比抽象的数字更能让孩子感知时间的宝贵。 C. 状态反馈 (Brain Check-in) 学习不只是输入，还需要“元认知”监控。 状态卡片：在计时结束或开始前，让孩子选择自己是“充电状态”还是“棉花大脑”。 自省回路：这种简单的交互能帮孩子建立起“我现在状态如何？”的自我觉察，这是长期专注的基础。 总结 这个工具是 VisAgent/Claw 哲学的一个分支：工具不一定要复杂，但一定要顺手。 如果你也面临孩子学习坐不住的问题，欢迎点击上方导航栏体验。 手搓快乐！🦾

[!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 配置： ...