SemaClaw:通过工具工程(Harness Engineering)迈向通用个人AI智能体的一步 SemaClaw: A Step Towards General-Purpose Personal AI Agents through Harness Engineering

SemaClaw 的方法步骤可以按层次分解为若干可独立部署的工程步骤。第一步是搭建双层架构基础:团队先发布 sema-code-core(基于事件门面模式暴露会话初始化、工具调用、压缩触发等类型化事件),再发布 semaclaw 应用层订阅这些事件并在其上实现频道、消息路由、智能体池管理。第二步是实现三层上下文管理:工作记忆由 sema-code-core 拥有并通过事件对外暴露,压缩阈值设在上下文长度的 75%、预留 8000 token 余量给下一条用户消息和提醒注入,压缩失败时回退到 50% 截断;外部记忆位于 agentDataDir 下的 MEMORY.md(人工或智能体维护的索引)和 memory/YYYY-MM-DD.md(自动日志,FIFO 50 天),检索采用 hybridSearch 三级降级策略(向量+FTS5→仅 FTS5→token 关键词扫描),向量与 FTS 双命中时使用 vec_score × 0.7 + fts_score × 0.3 的合并权重,而纯 FTS 或纯向量命中使用统一的基础因子 0.7,以保证跨语言场景下 FTS 不会被系统性地压低;人格分区由 SOUL.md(身份目录下的固定文档)与 workspace(动态可切换的当前工作目录)组成,两者通过不同的标题注入到上下文,并可在不重启会话的情况下切换 workspace。第三步是构建 PermissionBridge:在全局设立一个跨所有会话共享的桥实例,采用唯一请求标识符多路复用并发审批,内部工具(记忆检索、工作区管理、inter-agent 调度)预授权无需交互,外部工具默认每次调用都需用户通过频道内联按钮或 Web UI 显式同意,session 的 timeout 采用『last active』模式使得任何审批交互都能延长会话寿命。第四步是搭建 DAG Teams 编排:智能体团队在系统初始化时通过 ensureAgentDirs() 注册为持久化的人格(创建 SOUL.md 与目录树),协调器通过 create_parent 一次性提交 goal + tasks 数组(每项含 agentName、prompt、dependsOn),detectCycle() 在提交时校验无环,DispatchBridge 进程以 300ms 周期扫描 processPending() 并发派发可执行任务,worker 完成时通过 JSON 状态文件加锁文件回传,协调器用 500ms 间隔的 dispatch_task 轮询等待;失败的上游任务按 terminal 处理使下游不被永久阻塞,启动时把上次留下的活跃 parent 标记为 done 并把进行中任务记为 interrupted。第五步是四模式定时任务:pure notification(纯通知,零 token)、pure script(纯脚本,无模型调用)、pure agent(纯智能体,完整 ReAct)、hybrid script-plus-agent(脚本预处理后再交给智能体推理),按任务复杂度匹配模式以保持 token 消耗与推理工作量成正比。第六步是 Wiki 知识基础设施:用户在本地文件系统维护一棵 Markdown 文件树,YAML frontmatter 记录 tags 与 source 元数据,智能体通过 CLI(inspect/create category/save/organize)操作该树,save 时智能体判断内容是否归属已有分类、是否需要新建分类、或暂存到 inbox/;检索层面 knowledge 层维持独立的检索接口,与 memory_search 严格区分(『记忆』索引『说过什么』,知识层索引『学到什么』);Web UI 直接渲染同一棵文件树,用户的任何编辑立即对下一次智能体检索可见。

SemaClaw 的技术新颖性不在于任何一个单独的算法突破,而在于把若干工程原则系统化地落到一个可发布的开源框架中。在编排层面,DAG Teams 的『LLM 声明 + 确定性调度』两阶段分离在原理上对应论文 2.4.4 节提出的开放问题——一种协调动态推理与显式 DAG 的复合方案,论文把它实现为生产级机制而非停留在提议阶段,并通过显式持久化人格的字符串精确匹配(无向量检索)使得路由既灵活又可审计。在安全层面,PermissionBridge 把权限检查视为运行时一等原语而非应用层附加件,这点与现有『应用级配置』或『工具级包装』的做法有质的区别;『last active』超时模式与渠道原生审批界面(把审批直接嵌入用户当前对话)都是面向真实部署的设计选择,而非教科书式的安全模型。在记忆层面,把知识沉淀为用户拥有的 Markdown 文件(而非数据库或专有索引)是一个有意识的设计取舍——它牺牲了部分检索效率换来版本可控、可迁移、用户可编辑的产权属性,使知识基础设施同时成为人类与智能体的共享界面,这是 RAG 文献中很少被强调但有深远影响的取向。在上下文生命周期层面,把 SOUL.md(身份)、MEMORY.md(记忆索引)、workspace(任务环境)作为三个独立治理的分区注入,而不是全部塞进一个未分化的窗口,是论文中被称为 『cognitive density』(认知密度)概念的具体体现——解决的不是存储问题,而是『在每一个推理步骤上,哪些信息以何种形态到达智能体』这个更深层的结构问题。在插件生态层面,把扩展机制按其操作所在的工程阶段(MCP 工具→Action、子代理→Prompt、skill→Context、hook→Harness)划分为四层并形成对照表,使整个扩展面获得一个有纪律的分类法,这是先前讨论 agent 扩展性的工作较少明确给出的。

从独立分析视角,SemaClaw 的弱点可以归纳为五个相互关联的工程面。第一是人格漂移缺乏检测机制:SOUL.md 作为路由的语义锚点,其修改历史与语义漂移目前完全无审计,一个名为 『code-reviewer』 的智能体可能逐渐偏离其原始角色而路由匹配仍然成功——改进方向是引入 SOUL.md 版本日志与『语义一致性体检』hook,在调度前对当前 SOUL.md 与路由理由做轻量相似度检查。第二是 PermissionBridge 的权限分层粒度过粗:目前只区分内部/外部两类,但真实部署中 『允许读 /data 但禁止写』 之类的细粒度策略常被需要——改进方向是引入基于声明式策略文件(类似 AWS IAM 的 deny-by-default 规则集),把工具 + 参数模式 + 工作目录作为授权决策的三元组。第三是 Wiki 检索与外部记忆检索分裂:目前 knowledge_search 与 memory_search 是两个独立工具,导致一次跨源推理至少需要两次调用且合并逻辑落在智能体推理里——改进方向是构建统一的混合索引与统一的 memory_search 工具,把两类语料作为同一种带 source 标签的对象参与同一向量空间与 FTS 索引。第四是 DAG Teams 的串行 parent 策略限制了多任务吞吐量:同一 admin 智能体一次只能有一个活跃 parent group,虽然消除了状态争用但与个人智能体『同时处理多条用户事务』的实际场景冲突——改进方向是引入 parent group 命名空间隔离,使不同 group 在 worker 池分配与上下文隔离上互不干扰,并允许并发执行。第五是压缩提示对通用对话场景的适配差:目前压缩质量在代码任务上验证较好,在对话场景下容易丢失早会话约束——改进方向是让压缩提示随任务类型自适应,把『代码任务』与『对话任务』分别配以不同的保留策略(如对话任务优先保留用户显式声明的偏好与承诺)。

论文在第 4 节显式提出了五个开放方向,值得展开延伸。第一,持久人格 vs 临时虚拟智能体的架构选择:目前 SemaClaw 把这一选择硬绑定为架构承诺,但作者邀请社区探索两者结合的形态——例如『常驻专家核心 + 任务时临时实例化通才』的混合,需要路由层区分注册身份与临时实例,记忆系统规定临时智能体可写入的边界。第二,harness 工程与模型能力的互补关系:论文提出一个可检验假设——对大部分个人生产力场景(结构化研究、周期性工作流、领域特定辅助、知识积累),一个精心构建的 harness 可以让中端模型达到无 harness 的前沿模型相当的表现——这一假设值得系统化的对照基准验证,作者也明确邀请社区贡献基准、失败案例与反例。第三,记忆作为个人资本:长期使用产生的记忆本身是高保真度的用户画像,论文主张本地部署作为一种架构上的隐私原语,并提出『知识中枢』(knowledge hub)的设想——允许用户选择性地发布自己 Wiki 知识库的部分内容,形成从完全开放到商业化的谱系,但 provenance(来源归属)、containment(信息泄露)、trust(质量信号)等问题都没有现成答案。第四,有状态 harness 插件作为新的扩展形式:区别于无状态工具,有状态插件会修改智能体的持久基础设施(SOUL.md、记忆、共享知识),论文提出了四类尚未实现的具体形态——persona evolution plugin、cross-agent knowledge plugin、evaluation and self-correction plugin、shared template publishing——并指出其权限模型必须区分『会话范围』与『持久基础设施』两类写入,这是 PermissionBridge 未来需要扩展的方向。第五,超越个体的社区形态:从 ClawHub 的技能共享到 Moltbook 的智能体社交网络,论文认为最有价值的社区形态(跨运营商的智能体间通信、共享智能体模板、领域专业智能体社区、协作式知识共同体)在工程上最不可行,这是个人 AI 智能体领域最具长远意义的开放问题。基于成果可延伸的方向还包括:把 Wiki 知识库与 RAG 文献中的 late chunking、结构化检索融合;在 DAG 调度器之上引入预算感知的 token 限额路由;把 SOUL.md 的版本历史与 Git 式审计链结合,使人格漂移可回滚;以及把 LangChain 那类 harness-only 增益的对照实验范式推广到个人智能体任务集,系统验证论文的中端模型假设。

SemaClaw 在复现性方面有相当强的可读性,但也存在若干需要谨慎评估的因素。开源方面:代码已在 GitHub 上发布(github.com/midea-ai/SemaClaw),并采用 sema-code-core + semaclaw 的双项目结构,语义边界清晰;插件系统采用行业标准的 MCP 协议,生态可组合。文档方面:论文对每个机制都给出了具体的代码路径(如 detectCycle()、create_parent、processPending()、MemoryManager.hybridSearch)与运行参数(75% 压缩阈值、8000 token buffer、300ms/500ms/2min 时序参数、50 天日志保留、0.7/0.3 权重),读者可以据此直接对照源码实现。数据方面:核心记忆语料来自用户本地 MEMORY.md 与每日日志,Wiki 知识库是用户本地的 Markdown 文件树,不存在外部数据集依赖问题。算力方面:论文明确主张用中端模型即可获得与前沿模型相当的表现,并设计了纯通知、纯脚本模式以彻底绕开模型调用,这与『可在消费级硬件上运行』的部署目标一致;但论文同时坦率承认尚未产出严格的实证验证,目前依赖 LangChain Terminal Bench 2.0 这一外部证据。复现难度方面:对于熟悉 Claude Code 与 MCP 协议的开发者,基础设施层的搭建应属中等难度;但要完整复现论文提出的『个人 AI 智能体』协作体验,需要为每个 worker 智能体编写有意义的 SOUL.md、设计一套 Wiki 分类法、并积累足够的对话与记忆语料——这些是无法仅靠代码获得的、需要真实部署才能显现效果的部分。论文在第 4 节明确标注了未验证的假设(中端模型可达前沿模型表现的等价性),这种诚实标注本身就是复现性资产。