MaClaw（码卡龙）是 RapidAI 在 GitHub 上开源的一个通用可自进化智能体平台，代码以 Go 为主体、前端用 React，桌面端基于 Wails 打包。它不是又一个聊天壳子，而是把工作流、知识库、长期记忆、技能系统、多通道接入都做进了同一个运行时。
本文只谈技术实现，不吹概念。所有细节都能在仓库的 README 与 docs/ 目录里逐条核对，文末附了实际参考的文件清单。
一、一套内核，七种入口
很多 Agent 项目卡在"只能在某个界面里用"。MaClaw 的做法是把内核和入口解耦，同一套能力对外暴露成桌面 GUI 面板、终端 TUI、IM 通道（微信/飞书/QQ/Telegram/蓝信）、自托管 Hub、VS Code ACP、本机 HTTP 设备网关（默认 127.0.0.1:18777）以及多租户 REST 服务 MaClawSrv。
这种分层的价值在于复用：数字员工、IM 绑定、远程会话用的都是同一个 agent loop，而不是为每个入口重写一遍编排逻辑。MaClawSrv 侧再按 tenant → user 两级隔离，同一用户下的多个 instance 共享配置、记忆、Skill 与 MCP 状态。
二、工作流引擎 V2：把六七层拦截器收成一个决策点
这是我在仓库里看到的最"反直觉"的一处设计取舍。旧链路上，一条用户消息要穿过 QuickFilter、UIC、IUM、GateIntentClassifier、SteeringDetector 等一串拦截器才能决定去向；V2 的做法是只留一个 WorkflowRouter 作为唯一决策点，然后二选一：进普通 AgentLoop，还是进工作流状态机。
配套的四条原则写得很克制：一条路径、状态机驱动、路径即数据、测试隔离。所谓"路径即数据"，是指 projectPath 在工作流创建时写入状态机后只读，不再从 config、全局变量、ownerID 多路推断------这一条直接消灭了一类难查的串项目 bug。状态流转也被压到最小集合：pending → running → waiting_confirm → completed，没有 PendingReviewPhaseID、PhaseFormSubmitted 这类层层叠加的子状态。
工程收益是模块数从 30 多个文件收敛成 5 个模块，且状态机不写生产库，测试用内存 store、生产用 SQLite，两边互不干扰。模板层面内置 38 种结构化工作流，覆盖商业计划、竞品分析、合同审查、基金申请、专利撰写到运维变更。
三、Agent 动态 UI：让模型只敢碰 schema
企业软件的老问题是固定菜单、固定页面、固定表单。MaClaw 的解法不是让模型生成前端代码，而是让模型"申请界面"：Agent 输出一个 Agent View 描述，类型限定在 form、wizard、approval、progress、table_editor 这几种，由运行时用注册组件和 schema 白名单渲染。
关键约束有三条：adapter 是非侵入式 sidecar，标准 Skill 不用改格式就能被自动推断出 UI；是否弹界面、何时打断用户，由 runtime 的 trigger policy 决定，模型说了不算；任何写库、提交审批、发送消息、覆盖数据的动作，必须先过校验与策略引擎。
这条边界划得很清醒------模型负责理解和抽取候选字段，用户负责确认，系统负责校验和审计。落库侧由 MaClawDataSrv 承接，内置 30 多个企业 MIS 模板，提供业务操作目录、业务视图、审批流与全链路审计，本地 SQLite 与 PostgreSQL 走同一套 API。
四、工具路由：从"关键词命中"到"任务范围快照"
工具路由那段文档开头就自我校正了一句：关键词命中无法可靠表达任务范围，否定句、引用内容、示例代码和中文同义表达都会误分类。于是他们把召回依据换成了 Task Scope 对象，里面明确写出 intent、objective、resources、allowed_actions、forbidden_actions 和 risk_ceiling。
这份范围对象带来两个实际好处。一是工具集合在任务生命周期内保持稳定快照，不会在多轮对话里忽然冒出来又消失；二是权限不会被语义路由悄悄放大------只读任务不会因为后面出现"执行"两个字就升级成写操作。
架构上，路由器只负责生成计划，执行器才负责能力、权限、连接状态、审批和幂等校验，两者不靠字符串约定隐式传递授权。工具元数据里连 alternatives、preconditions、availability_probe 都登记了，缺工具时能自动补齐，不可用时返回结构化能力错误而不是静默失败。
五、远程控制：桌面是宿主，Hub 是控制面
MaClaw 的远程链路分工很明确。桌面端是会话宿主，负责用 PTY/ConPTY 托管编码工具、管理会话生命周期、采集输出并生成压缩状态；Hub 是工作控制面，管身份、机器、会话，存压缩后的状态，并提供 PWA 和远程指令路由；Hub Center 只是入口目录，做 hub 注册与发现、按企业邮箱域名路由，既不是认证服务器，也不转发实时会话。
值得抄的是"压缩状态优先"这一条：Hub 存的是 summary、重要事件和 preview，而不是原始 transcript。手机端因此不需要做成终端镜像，只展示当前状态、当前任务、上一条结果和下一步建议。存储上用 SQLite 默认开 WAL、读写分离，再套一层 repository 抽象，后续换库不动业务代码。
六、记忆与知识库：内脑和外脑分开建
MaClaw 把知识库叫"外脑"，长期记忆叫"内脑"，两者独立建库、协同检索。知识库走三层结构：原始文档 → 保留标题/段落/表格/页码层级的 DocumentNode → 知识卡片 Card → 事实三元组 Fact，检索上叠了 SQLite FTS5 全文与向量嵌入双通道，还提供 Context Pack 在 Agent 工作时自动注入相关上下文。
记忆侧同样是 BM25 加向量双索引，会话历史做全文索引，支持跨会话检索与关键词高亮。更值得一提的是 docs/memory-architecture-audit.md：那是一份对自家记忆体系的架构审计，逐条列出"两条路径做同一件事但预算不一致"的问题，比如三套对话压缩路径职责重叠、其中一条因为带 tool_calls 就整体跳过、实际上几乎从不执行，还有导出版本与 GUI 版本重复实现。这种把死代码和设计债写进仓库文档的做法，比任何架构图都更能说明工程成熟度。
七、Computer Use：按模型有没有视觉分两条路
桌面操作这块的感知路径是分流的。模型支持视觉时，直接截图交给模型，模型回像素坐标；模型不支持视觉时，走文本优先------本地 OmniParser YOLO 检测可交互区域，OCR 贴文字标签，再叠加前台窗口的 Accessibility 树，生成 e0...eN 的文本 SoM，截图根本不出本机。
执行侧的细节也很实：ref 解析时会带上屏幕 origin 和 DPI 换算成中心坐标，优先走 UIA/AX 语义操作，失败才回落到 InputSimulator；默认只裁前台窗口（四周约 8 像素边距），动作后等 80 毫秒 settle；如果前台窗口族和 observe 时的裁剪对不上，直接作废所有 ref，要求重新观测。这几条合起来，才让"点错窗口"这类事故不容易发生。
八、技能自进化，但把刹车装在前面
技能系统的闭环是：执行 → 使用追踪 → 失败分类 → 自修复或降权或沉淀 → 定期治理 → 下一轮加载最新能力记忆。Curator 默认只生成只读的维护计划，动作类型限定在 mark_needs_review、attempt_repair、merge_duplicate、archive_stale、refresh_lifecycle、refresh_index、improve_contract 这几种。
真正值得学的是它的收敛条件：只有可修复错误才进自修复，限流和网络这类外部错误只提示重试或降权；文件型技能一律只出 patch draft，必须人审后才写回 skill.yaml 或 SKILL.md；所有自动建议都要带 reason、evidence、risk、recommended_action。自动化和可控性在这里不是对立面，而是靠"先计划、后执行"的顺序拆开的。
九、几个可以直接搬走的工程习惯
第一，把决策点收敛成一个函数，而不是靠拦截器层层叠加。第二，把隐式状态改成显式数据，projectPath、Task Scope、WorkflowState 都是这么处理的。第三，给自动行为设只读计划和人工审批两级闸门。第四，用仓库内的审计文档记录设计债，而不是让它烂在 issue 里。
MaClaw 采用双许可：开源项目可自由使用（GPL 方向），商业用途需联系作者获取授权。仓库地址：https://github.com/RapidAI/MaClaw
参考资料（均取自该仓库 main 分支）：README.md、docs/00-overview.md、docs/workflow-engine-v2-architecture.md、docs/agent-dynamic-ui-runtime-design-zh.md、docs/maclaw-semantic-tool-routing-improvement.md、docs/memory-architecture-audit.md、docs/computer-use.md、docs/skill-self-evolution-technical-design-zh.md。