Sema Code:把 AI 编码代理解耦为可编程、可嵌入的基础设施

把 AI 编码能力从产品形态中解耦,做成无 UI 的 npm 引擎库。

前置知识

AI 编码代理 (AI Coding Agent)

以 LLM 为核心、能自主读写文件、执行命令、调用工具来完成软件工程任务的系统,如 Claude Code、Cursor、GitHub Copilot、SWE-agent 等。它们通常把推理循环、工具编排、UI 渲染绑定在同一个应用里。

Sema Code 的所有设计动机都来自这类代理"能力被产品形态锁死"的问题,理解 Claude Code/CLI、Cursor/VSCode 等典型绑定关系,才能体会为什么需要把它重新设计成引擎。

ReAct (Reason + Act) 范式

让 LLM 在每一轮交替地输出"思考-行动-观察"的范式:模型先产生推理(Reason),再产出工具调用(Action),收到环境反馈(Observation)后继续推理。Yao et al. (2023) 提出,目前主流 agent 系统几乎都基于它。

Sema Code 的工具调度策略(只读操作并行、写操作串行)是对 ReAct 在调度层的扩展;Todo 状态机、子代理隔离等设计也都是对 ReAct 主循环的工程化加固。

AsyncLocalStorage (ALS, Node.js)

Node.js 提供的"异步上下文本地存储"机制,基于 async_hooks 实现跨 await/Promise 边界的"调用链局部变量"。在没有显式传参的情况下,任意深处回调都能拿到入口处绑定的上下文,常用于 traceId、租户隔离、日志上下文。

Sema Core 的多租户隔离完全依赖 ALS:每个 engine 实例在创建时把"事件总线+状态管理器+工具编排器"绑到 ALS context,任何异步调用栈里都能零成本取出本实例资源,不需要手工逐层传 context 对象。

MCP (Model Context Protocol) 与 Skill/Plugin

MCP 是 Anthropic 2024 年提出的标准化协议,把数据库/浏览器/API 网关等外部系统包装成统一工具;Skill 指 Markdown+YAML 描述的能力文件,重塑推理行为;Plugin 是更重的命令/钩子扩展,编排工作流。三者粒度从轻到重,本文明确分层。

Sema Code 把 MCP/Skill/Plugin 分成"基础设施-行为-工作流"三层生态而非合并为一层,理由是它们的权限模型与生命周期完全不同,合并会过度赋权或能力不足。理解这种粒度划分才能读懂 5.3 节。

上下文窗口压缩与 MemGPT

LLM 上下文窗口是有限资源,长任务里消息历史会不断累积直至超出。MemGPT (Packer et al., 2023) 借鉴 OS 虚拟内存做分页,但每次跨页都要额外一轮推理。Sema Code 走另一条路:利用 API 返回的累计 token 数做零成本监测,触发压缩。

自适应上下文压缩是 Sema Code 的核心机制之一,涉及 75% 阈值、8000 token forward buffer、双路径(语义摘要/安全截断)等具体参数,这些数字必须先理解上下文窗口有限性才能体会其工程价值。

研究动机

过去两年 AI 编码代理从实验室走向商用:Claude Code 把 agentic loop 锁死在 CLI 里、Cursor 深度定制 VSCode 分叉、Copilot 受限于编辑器插件形态。Copilot 月活开发者已破 100 万,对照实验显示任务完成速度提升 55.8%,AI 编码已是工程生产力核心倍增器。但当企业想把能力嵌入后端、替换模型私有部署,或让同一内核服务 IDE/Web App/机器人多端入口时,结构性矛盾立刻暴露:核心推理与前端深度耦合,既不能复用也不能替换。SWE-agent、Agentless 这类自主编码工具虽能在 SWE-bench 解真实 GitHub issue,能力同样被锁在运行环境里。换句话说,这些系统把 AI 编码能力打包成"待使用的产品",而非"可嵌入的引擎"。SQLite 被数十亿设备嵌入、Chromium 同时驱动浏览器和 Electron,正因为它们一开始就被设计为引擎。本文问题由此产生:AI 编码的核心推理引擎,能否也走同一条路?

本文的目标是本文的具体目标是提出一个轻量、可插拔、framework-first 的开源 AI 编码框架 Sema Code,把核心代理引擎与所有客户端彻底解耦,以无 UI 的独立 npm 库形式发布,使"驱动一个 AI 编码代理"与"连接数据库"一样简单。为达到这一目标,论文系统性回答四个工程问题:多租户隔离、上下文生命周期、多代理协同调度、权限安全与生态兼容。最终验证手段是让同一个 Sema Core 引擎同时支撑一个 VSCode 插件(单用户长会话)和一个多通道消息平台 SemaClaw(50 人团队并发),证明引擎层零修改即可服务形态完全不同的产品。

与已有工作不同的是，现有工作存在三类明确空缺:第一类是 Claude Code、Cursor、Copilot 这类产品系统,核心能力锁死在交付形态里无法被第三方编程复用;第二类是 OpenHands、MetaGPT、ChatDev、AutoGen、LangChain 这类通用框架,虽然开放但要么针对研究场景(OpenHands 生产级关注不足),要么用 SOP/角色严格编排协作(MetaGPT、ChatDev),与交互式编码助手的临时性任务不匹配,且都缺少跨语言集成接口;第三类是 SWE-agent、Agentless 这类自主编码范式,在 agent 自主性光谱两端走极端,核心能力仍然锁在各自运行环境里。Sema Code 的独特切入角度是"把 AI 编码能力定位为引擎而非应用":既不像产品系统那样预设交付形态,也不像通用框架那样只解决算法层问题,而是从多租户隔离、上下文生命周期到权限管理、生态集成提供全栈工程化方案,做到 production-ready。

核心方法

Sema Code 的整体思路是"三层分离 + 八大机制":客户端层(负责 UI/消息路由)、核心引擎层(Sema Core,无 UI、作为独立 npm 包)、服务层(跨语言 WebSocket/gRPC 接口)。所有推理、工具调用、状态管理都在 Sema Core 中完成,客户端只需订阅引擎的事件流即可做渲染或转发,事件流天然承载文本片段、工具结果、权限请求、进度更新等异构输出。围绕这一架构,论文设计了 8 个相互耦合的核心机制:多租户隔离(用 Node.js AsyncLocalStorage 隔离每实例资源)、层次化状态切分(本地/全局双层)、FIFO 输入队列 + 安全 session 重建、自适应上下文压缩、双路径降级、多代理协同调度(共享中断信号 + 隔离子代理)、Todo 状态机(防 UI 闪烁)、后台任务执行(执行/观察权分离)、四层异步权限(三态决策)、三层生态(MCP/Skill/Plugin)。直觉上,这套系统等价于把 Claude Code 的"应用+CLI"整体拆解成一个事件驱动的内核库,任何客户端只要能订阅事件流、发送请求,就能复用全部 agent 能力。

本文的核心创新在于架构层面而非算法层面:把 AI 编码代理的"应用形态"与"推理内核"彻底分离,使引擎变成可被任意运行时编程调用的库。本质区别有四点:(1) 与 Claude Code/CLI、Cursor/VSCode 等产品系统不同,Sema Core 不绑定任何交付形态,新形态只需"订阅事件流+实现呈现逻辑"即可复用全部能力;(2) 与 MetaGPT/ChatDev 的固定角色 SOP 不同,Sema Code 的子代理采用"隔离状态空间 + 共享中断控制器"范式,只允许一级委托,避免无界调用深度,适配交互式编码任务的临时性特征;(3) 与 MemGPT 的显式分页不同,Sema Core 利用 API 返回的累计 token 字段做 O(1) 监测,通过"75% 阈值 + 8000 token forward buffer + 双路径降级"实现无 LLM 开销的上下文管理;(4) 与单层 allow/deny 不同,四层权限针对文件编辑/Shell/Skill/MCP 四类风险画像分别设计决策规则,Shell 层额外引入 LLM 静态分析防止命令注入混淆。

方法步骤详情

实现分五阶段。第一阶段建连:客户端经 WebSocket/gRPC 与 Sema Core 建连,引擎为实例 $E_i$ 在 AsyncLocalStorage 绑资源束(事件总线+状态管理器+工具编排器)。第二阶段状态切分: $S_{session} = \langle S_{local}, S_{global} \rangle$,本地 $S_{local}(a_i) = \langle e_i, H_i, T_i, F_i \rangle$ 私有,全局 $\{g_{edit}, C_{abort}\}$ 让一次取消终止整棵树。第三阶段输入分派:按 $S_{state}$ 决定执行或入队,语义批处理合并非命令消息。第四阶段压缩:累计 token 超 $0.75 \cdot L$ 触发,优先 LLM 摘要 $H^* = \arg\max_{H'} I(H'; H_{hist})$ s.t. $|H'|_{token} \ll |H_{hist}|_{token}$,失败按 usage metadata 截断到 $L/2$。第五阶段权限: $P: O \times C \to \{allow, deny, request\}$ 路由到 L1-L4,L2 Shell 先白名单 fast-pass,失败调 LLM 注入分类。

技术新颖性

技术新颖性体现在三个工程维度。第一,多租户隔离给出清晰数学刻画:传统单例下 $A_i \xrightarrow{w} S$ 与 $A_j \xrightarrow{r} S$ 共享全局 $S$ 必然污染,Sema Core 利用 ALS 让 $n$ 个实例在同一进程内严格隔离。第二,状态空间显式拆为 $S_{local}(a_i) = \langle e_i, H_i, T_i, F_i \rangle$ 与 $S_{global} = \{g_{edit}, C_{abort}\}$,子代理深度严格限制为 1,既保留多代理收益又规避递归爆炸。第三,上下文管理利用 API 内嵌的累计 input_tokens 做 $O(1)$ 监测,叠加 8000 token forward buffer 与 75% 阈值,使压缩管线在常规交互中零额外 LLM 开销;摘要路径用信息论视角建模并施加三条确定性修正(剥离 thinking block、重校 usage、重注 Todo),降级路径以"恰好截到一半 $L$"保证 Anthropic API 的 role-alternation 约束不被破坏。

**Figure 2**: Sema Code three-layer architecture. The core engine layer contains no UI code and ships as a standalone npm package. The client layer interacts with the engine exclusively through event-driven public APIs.

**Figure 3**: Overview of agent runtime, illustrating three core parts: (a) the background task execution system, which asynchronously manages long-running Bash and Agent processes with timeout recovery; (b) the multi-agent coordination framework, featuring isolated state spaces, strict lifecycle management, and shared abort signals; (c) the adaptive context compression module, which triggers dual-path token reduction upon reaching a high-pressure threshold.

实验结果

论文采用"架构验证"而非基准打榜方式组织实验。第一个发现是"零引擎修改":VSCode Extension 直接 npm 引入 Sema Core 跑在 Extension Host 进程内,集成实时 diff 预览+一键回滚、Todo 任务板、后台任务面板、会话历史、模型热切换;SemaClaw 作为服务端 Node.js 进程同样引入同版本 npm 包,加 Telegram/Feishu 通道适配器与多会话管理器。两者代码库无任何 engine 修改,差异完全发生在 client 层,直接验证三层分离设计目标。第二个发现是"互补机制覆盖":VSCode 端验证自适应压缩与四层权限(原生 VSCode 对话框);SemaClaw 端验证多租户隔离、FIFO 输入队列(吸收消息突刺)、异步审批协议(消息内联按钮)。八个机制在两种部署中恰好各占一半,合并覆盖全部设计。GitHub 仓库 https://github.com/midea-ai/sema-code-core 与 sema-code-vscode-extension 完全开源,Open VSX 可下载。

**Table 1**: Four-layer permission decision matrix.

查看结构化数据

任务	指标	本文	基线	提升
架构通用性:同一引擎支持 VSCode 与 SemaClaw 双产品	Sema Core 源码修改次数 + 部署形态覆盖	0 行核心引擎修改,8/8 机制在两种部署中被分别或联合验证	Claude Code (CLI 单形态)、Cursor (VSCode 单形态)、GitHub Copilot (插件单形态) 均需独立维护核心代码	把核心能力与交付形态解耦,使一份引擎代码同时服务交互式 IDE 与多通道消息平台
多租户并发隔离	单进程并发 session 数 + 状态污染事件数	SemaClaw 单进程支撑 50 人团队并发会话,AsyncLocalStorage 隔离保证跨用户历史/工具权限不串扰	传统全局单例架构下 $n$ 个实例共享 $S$,任意 $A_i$ 写入可被 $A_j$ 读取,存在不可预测污染	用 ALS 在零参数传递成本下实现 instance-level 严格隔离,并保留 fallback 到全局单例的兼容路径
自适应上下文压缩	监测复杂度 + 触发阈值 + 摘要/截断双路径	$O(1)$ 监测(读累计 input_tokens)、75% 阈值触发、8000 token forward buffer、双路径(LLM 摘要 + 安全截断)	MemGPT:每次跨页需显式 LLM page-in/page-out;naive truncation:灾难性遗忘;naive halving:违反 role-alternation 约束	常规交互中零额外 LLM 开销,摘要失败时自动降级到按 usage metadata 精准截断到 $L/2$
FIFO 输入队列在消息突刺下的稳定性	消息丢失率 + session 重建残留	Semantic Batching + Safe Session Reconstruction(pendingSession + finally 块彻底 purge $S_{local}$)	逐条 deque 导致碎片化上下文与冗余 API 调用;force-kill 中途任务易留下残留文件	非命令消息自动合并,系统命令严格隔离;中断时通过 abort + pending flag 保证零状态残留
四层权限决策 (L1-L4)	决策状态空间 + 注入检测准确率	$P: O \times C \to \{allow, deny, request\}$,L2 Shell 层用白名单 fast-pass + LLM 静态分析识别反引号替换/进程替换/链式破坏等注入模式	NeMo Guardrails 等通用安全栏粒度停留在对话层,缺乏对文件/Shell/Skill/MCP 的细粒度控制	针对四类操作不同风险画像分别设计,Shell 层 2 阶段评估在白名单失败时升级到 LLM 分类以对抗混淆

局限与改进

作者在 6.4 节坦承五点局限:第一,部署验证只覆盖两种产品形态(IDE + 消息平台),是否可推广到 CI/CD pipeline 集成、Jupyter notebook 嵌入等其他形态仍待证明。第二,当前部署未做大规模压力测试,数百并发用户下的性能瓶颈尚未暴露。第三,上下文压缩质量高度依赖底层 LLM 的摘要能力,代码片段密集的技术性对话可能在压缩中丢失关键细节,且降级路径(truncation)以牺牲一致性换取可用性。第四,WebSocket/gRPC 跨语言接口虽功能完整,但未做流式吞吐与对抗网络条件下的错误恢复基准测试。第五,所有部署均采用单 Sema Core 进程,横向扩展到多引擎实例会引入状态同步难题,当前架构尚未处理。从我们观察看,还有两点值得补充:L2 Shell 层 LLM 静态分析本身继承基模型漏报率,误判漏过恶意 payload 时无任何二次防线;而 pendingSession 的 finally 块 purge 策略虽保证一致性,但若 purge 过程中抛错可能留下半清理状态,工程实现上需要 idempotent guard。

独立分析的弱点

独立分析可见四个可改进方向。第一,L2 Shell 权限依赖 LLM 做反混淆分类,本身继承 base model 漏报率,构造落在训练分布外的 payload 会绕过二次审查。改进方向是叠加确定性规则引擎(如 tree-sitter shell grammar + 污点追踪)作为前置过滤器,LLM 仅做高难度判例的最终裁决。第二,Todo 状态机"至多一个 active"虽避免 UI 闪烁,但在多代理并行阶段(一个子代理在跑、另一个写代码)会强制人为排序,损失并行性。改进方向是允许"per-agent-active set",呈现层做并行渲染,调度层保持独立计数。第三,FIFO 语义批处理把所有非命令消息合并,用户在合并窗口内追加高优先级指令会被延迟到下个 tick。改进方向是引入优先级通道或抢占式 dequeue,允许显式插队。第四,后台任务 reactive takeover 把超时进程移交后台管理器后,用户立刻查询需等额外 poll 周期才看到首批结果,可在 takeover 时主动 snapshot 一次内存中的部分输出,保证查询即时可见。

未来方向

作者在第 7 节明确提出三条未来方向:(1) 基于向量检索的上下文管理,绕过摘要的信息瓶颈,实现细粒度历史回溯;(2) 扩展多代理协调,从单纯委托走向 inter-agent 状态共享与消息传递的真正协作;(3) 跨引擎实例的分布式任务调度,支撑弹性生产部署。结合成果可延伸的方向还包括:把四层权限推广为可插拔 policy engine,允许企业自定义 L5-L6 层级(如网络出站、Docker exec);把 event-driven 接口标准化为社区协议(类似 LSP),让任何 IDE/CLI/Web UI 都能成为一等客户端;把自适应压缩的 75%/8000 token 参数做成可学习/可调节的 hyperparameter,根据任务类型(对话 vs 长任务)动态切换;以及把 SemaClaw 的多通道抽象沉淀为"Agent Gateway"模式,让其它 agent 框架(如 LangGraph、AutoGen)也能复用同一套通道适配层。

复现评估

复现评估整体偏高:Sema Core 开源在 https://github.com/midea-ai/sema-code-core,VSCode 扩展在 https://github.com/midea-ai/sema-code-vscode-extension,插件已上架 Open VSX。复现需:(1) Anthropic + OpenAI-compatible API key 验证双适配器;(2) Telegram Bot Token + Feishu Webhook 复现 SemaClaw 多通道场景;(3) 大规模并发验证需自行准备模拟流量。引擎本身只是 Node.js 编排层,推理成本取决于所选 LLM,可接 Code Llama、DeepSeek-Coder、V3/R1、GLM-5、Qwen3-235B、Gemini 2.5 Pro 等,经 customBaseUrl 路由。复现难度中等偏下:架构清晰、依赖成熟(ALS、Anthropic/OpenAI SDK、MCP 协议),但缺统一端到端 benchmark 脚本,需按 README 自拼。

Sema Code:把 AI 编码代理解耦为可编程、可嵌入的基础设施 Sema Code: Decoupling AI Coding Agents into Programmable, Embeddable Infrastructure