DeepSeek 发布了第一款 Agent 产品

作者：chino，腾讯WXG 微信小店前端开发工程师

DeepSeek 发布了第一款 Agent 产品，DeepSeek Harness。这次的重点放在了运行时架构上，官方给的关键词是"everything is a plugin"，模型接入、工具执行、会话记录、循环本身、界面，全部走插件机制。

这篇文章跳过 agent 领域已经成为共识的那部分——检测工具调用、执行、回填、循环，这套流程眼下几乎每个框架都长一个样，不值得再讲一遍。重点放在 DeepSeek Harness 真正跟别人不一样的几处设计：Cordis 这套插件运行时具体怎么管生命周期，preset 的 scope 继承链为什么拆成两层，Code Mode 为什么选了一个听起来不太"安全"的隔离方案，工具注册的遮蔽算法怎么写。顺带会跟 Codex 的几个具体工程决策做对比，只挑不一样的地方讲。

一、为什么是 Cordis

"everything is a plugin" 的基础是 Shigma 的开源项目 Cordis。定位是"Meta-Framework for Modern JavaScript Applications"，一个通用的插件框架，处理依赖注入、作用域服务、生命周期清理这几件事，与 agent、与 LLM 都没有直接关系，在 DeepSeek Harness 出现之前就已经存在。

Cordis 在开源社区有实际的使用者。最典型的是 Koishi，一个跨平台聊天机器人框架（QQ / Discord / Telegram / 微信都接）。聊天机器人场景天然是"几十个插件拼在一起、热插拔、随时改配置"，与 agent 的场景几乎相同，只是没有 LLM。DeepSeek Harness 把整个框架的源码 vendor 进自己的仓库，改了个 scope 叫 @deepseek-ai/cordis，然后把公司自己写的每一个包，都设成对它的 peer dependency。这比"使用一个第三方库"更进一步：整个产品都构建在 cordis 之上。

先对比几种常见的插件形态：传统 DI 容器、轻量钩子方案、Cordis。这三种方案各有取舍，值得摆在一起看。

传统 DI 容器的三个缺口。 "主流"方案是一个 DI 容器加生命周期注解。你 bind 了一个 service，谁来负责 unbind 和 cleanup？传统 DI 要么不管（泄漏），要么要求你手写 lifecycle hook。LLM provider 热替换了，依赖它的 ToolRegistry 应该自动重启，传统 DI 做不到这种"依赖驱动的重载"。配置上，传统 DI 的配置在启动时读一次；而 cordis.yml 里一行就是一个插件实例，改配置直接触发 HMR。

Pi也是Agent界的明星产品了，但Pi 的 Extension 走的是另一条路。 Pi 的自我定位是 "self extensible coding agent"，它的插件叫 Extension（扩展），基于 TS，在扩展点上通过钩子塞逻辑：没有依赖注入，没有插件间依赖管理（加载顺序即优先级），也不能卸载。Cordis 的插件是带依赖声明、生命周期、可逆副作用的"组件"：有依赖注入，有反应性 coeffects，插件间可以声明依赖，卸载时能完整逆转副作用。

这最后一点——"可逆副作用"——是整篇文章的地基。Cordis 的设计论文把这件事上升到理论层面，核心问题问得很直接：

有没有一种 programming model，能让动态本身具备类似进程那样的生命周期隔离？

进程和容器的好处在于：kill 掉再启动，状态就清空了。代价是重启会丢掉进程内的 cache、connection、partial computation。插件系统希望不用重启，也能完成同样的清理。论文为此给了两个定义：

• 时间可组合性

  ：卸载组件时，组件对共享环境所做的修改必须被完整、安全地逆转——这要求追踪组件执行的每一次资源分配、事件注册和状态变更。

• 空间可组合性

  ：依赖变化时，相关组件自动激活或停用。

时间可组合性是这篇文章的主线。剩下的事情——Fiber、effect、系统边界、preset、Code Mode——都在回答同一个问题：怎么在工程上实现"卸载 = 完整逆转"。

Cordis 生态还带了几个配套包，随项目一起 vendor 进来：一个配置文件加载器（负责解析 cordis.yml 这类声明式配置），一个 include 插件（负责把一份配置当成子树挂载进来，preset 机制用的就是它改名后的版本），一个 HMR 模块（支持插件热替换），外加日志和定时器这两个基础设施插件。这几块拼起来，才能真正理解"everything is a plugin"。

二、Fiber 与 effect：可逆副作用的地基

Cordis 里，插件的类型定义是一个联合类型：

type Plugin<T> = Plugin.Function<T> | Plugin.Constructor<T> | Plugin.Object<T>

裸函数、类、带 apply 方法的对象，三种写法最终都被解析成一个统一的回调。挂载一个插件调用 ctx.plugin(plugin, config)，内部先找有没有已经存在的 Runtime 记录（按回调函数身份做 key，同一个插件多次挂载共享同一条 Runtime），没有就新建，再造一个 Fiber，塞进这条 Runtime 的 fibers 列表里。

Fiber 是插件实例的生命周期状态机，六个状态：PENDING、LOADING、ACTIVE、FAILED、DISPOSED、UNLOADING。插件声明了 inject: ['tools', 'shell']，对应的 Fiber 会停在 PENDING，直到这两个服务都在依赖链上出现，才真正跑这个插件的代码，进入 ACTIVE。这套等待机制是 Cordis 自己实现的依赖解析，插件作者不需要手写"等对方准备好"的轮询逻辑。这对应空间可组合性：依赖出现后，组件自动激活。

卸载一个插件是否安全，由 effect 机制决定。插件注册的任何东西——事件监听、服务、定时器——都通过 ctx.effect() 登记。登记时立刻执行一次，返回的撤销函数被推进一个 disposables 列表。论文 5.1.1 指出：Cordis 中每一次上下文变更都通过唯一原语 ctx.effect 完成——提供服务、实例化组件、所有修改上下文的操作都归约成一次 ctx.effect 调用。用法长这样：

ctx.effect(() => {
  // 做副作用：注册监听、开定时器、提供服务……
  return () => { /* 逆：撤销上面的操作 */ }   // 返回 disposer
})

callback 可以返回一个 disposer 函数、一个 Promise，或者一个（异步）迭代器，逐段 yield disposer——每做一步副作用就交一个撤销函数。

在这里，"副作用"的定义是：任何通过 Context 对共享环境进行的修改。这张表把日常操作都覆盖了：

Koishi 里 ctx.command(...) 注册命令、ctx.router.get(...) 注册 HTTP 路由；DSH 里注册工具、挂 HMR 监听、起调度器——全是副作用。"怎么逆转"，实现上很直接：每个副作用都带着自己的撤销函数，运行时把它们按 LIFO 叠起来，卸载时整体执行一遍：

disposables.splice(0).reverse().forEach(dispose => dispose())

按注册的相反顺序逐个撤销，类似退栈。子 Fiber 的销毁函数本身也是通过 parent.fiber.effect(...) 挂在父 Fiber 上注册的——在源码里就是 Fiber 构造函数末尾这一行：

this.dispose = parent.fiber.effect(() => { /* 注册插件 */ 
  return async () => { /* 注销插件 */ }
})

也就是说，一个插件本身 = 父 fiber 上的一个 effect：插件的启动逻辑就是副作用，卸载逻辑就是逆。子组件的逆会被 prepend 到父上下文的累加器上，形成递归结构（论文里叫 twisted composition，记作 𝜕²Γ）。所以卸载一个插件，会连带把它下面挂的子插件一起按栈的顺序拆干净，不需要单独维护一张"谁依赖谁"的清理表。

这个机制还有两个细节保证可靠性。一是幂等：dispose() 首次调用把 armed 标志置 false，之后再次调用直接返回——每个逆最多执行一次。"执行两次会在从未产生过该效应的状态上应用逆，无从还原。"二是中断：如果 callback 返回的是迭代器，每一步之前会查 guard，一旦失效立即停止，只执行已累积的逆——热重载、卸载中途失败都能安全停住。事件监听器也遵循同样的可逆机制：ctx.on(...) 返回 unsubscribe 函数，监听器登记在 fiber 的 hook 表里，fiber 卸载时统一移除。_unload() 跑完所有撤销函数后，如果发现依赖又重新满足了，会立刻调 _reload() 重新拉起来——"换掉某个服务的实现"在运行时层面就是一次自动的卸载再加载。

一个插件的写法大致是这样（在UI界面上添加一个时钟）：

// 会话日志插件：注册一个事件监听 + 一个定时器，卸载时自动清理
export const name = 'session-logger'
export function apply(ctx: Context) {
  // effect 回调在注册时立即执行
  ctx.effect(() => {
    // 副作用 1：订阅事件总线，把事件追加进日志
    const off = ctx.on('tool/result', (event) => appendToLog(event))
    // 副作用 2：开一个定时器，定期把缓冲刷到磁盘
    const timer = setInterval(flushBuffer, 1000)
    // 返回撤销函数：卸载时按注册的相反顺序执行
    return () => {
      clearInterval(timer) // 后注册，先撤销
      off()                // 再退订监听
    }
  })
}

挂载这个插件时，ctx.effect 的回调立即执行：监听器挂上、定时器启动，返回的撤销函数被推进 disposables 列表。卸载时（插件被移除、会话结束、HMR 重载），disposables.splice(0).reverse() 按逆序逐个执行——先 clearInterval，再 off()。撤销逻辑写在注册逻辑旁边，作者不需要在别处维护一份"哪里注销"的清单。

这个写法真的很像 React。useEffect 的形状几乎一样：useEffect(() => { subscribe(); return () => unsubscribe() }, deps)——回调里做副作用，返回清理函数，组件卸载时自动调用。两边共享同一个核心约定：副作用和它的逆写在一起，销毁由框架触发。差异也清楚：React 的 effect 在渲染后执行，依赖变化时先清理再重建；Cordis 的 effect 在注册时立即执行，卸载时统一撤销，清理顺序有明确的 LIFO 保证（后注册的先撤销，子插件随父插件逆序级联）。

那"逆转"为什么值得花这么大篇幅？论文把"自进化 Agent Harness"列为两大动机之一，原文非常尖锐：

未来的 harness 会在持续服务请求的同时生成并部署对自己组件的修改……没有时间可组合性，每次自我修改都迫使完整重启，丢弃所有进程内累积状态；更糟的是，一个有缺陷的自我修改可能废掉唯一能用来恢复的那个进程。

这是"自进化"的前提：Agent 自己写插件/工具，运行时装进自己。装了坏的能回滚，而且回滚机制本身（宿主进程）不能被新组件弄坏。普通插件系统做不到这一点，因为重启宿主意味着丢失当前进程的所有状态。对照一下现有生态：VSCode 的扩展宿主无法卸载单个扩展，禁用/卸载必须重启整个宿主；Koishi 社区里，改完配置 reload daemon 是很常见的操作。Cordis 的逆转让"卸载"成为与"加载"对称的一等操作——服务不中断，其他插件不受影响。

这套机制顺带解决了两个常见工程问题。一是失败原子性：插件初始化中途抛错（配置校验失败、依赖缺失），fiber 进入 FAILED 状态并 dispose——已经应用的一半效应被逆序清掉，不会残留部分初始化状态。二是级联清理，作者不用写卸载代码。论文 5.3 的关键论断是：

因为通过 context 的效应被自动追踪、逆自动复合，即使是没经验的作者，也能为一个插件的 context 介导效应获得有序清理，而不用写卸载路径——正确性从依赖每个作者的自觉，变成由抽象层一次性承担。

卸载一个插件 → 逆序级联卸载它的子插件、释放它的定时器/监听器/HTTP server/DB 连接。清理正确性从"每个作者写对 deactivate"变成"框架结构保证"。VSCode 模型在这里有一个短板：它的 deactivate 钩子和 activate 分离，"效应清理与创建分离，违背关注点局部性，完整清理难以验证"。

逆转机制的关键作用可以归纳为四点：① 开发期 HMR（改代码不重启、出错可事务回滚）；② 生产期运行时插件装卸（服务零中断）；③ 自进化 Agent（改自己、坏了能自救）；④ 失败原子性与级联清理（坏插件不残留影响、作者不用写卸载代码）。它把"卸载"从手动善后变成框架保证的结构性操作，这是"一切皆插件、插件可热插拔"能成立的前提。

三、四条约束与系统边界：框架怎么保证 effect 被执行

看到这里可能有人会问：如果作者把副作用写在 effect 外面，比如直接给 globalThis.foo 赋值，这套机制还有效吗？论文正面回答了这个问题。框架的处理分两边：一边在 API 层面约束，上下文修改只能通过 effect 完成；一边明确声明系统边界，边界外的操作不受追踪。

框架从四个层面约束 effect 的用法。

第一，API 入口唯一。想用框架的任何能力——事件 ctx.on、服务 ctx.provide、挂插件 ctx.plugin、配服务 ctx.use——都只有 ctx 这一个入口，而 ctx 上的每个操作内部都是 ctx.effect 的封装。API 设计上不存在绕过 effect 使用框架功能的路径。

第二，Context 是 Proxy。源码里就是一行：const self = new Proxy<this>(this, ReflectService.handler)。对 ctx 的属性 get/set 全部走代理，这也是反应性 coeffect（"访问即通知"）和 interception 的机制来源。所以 ctx.foo = x 这种直接赋值也会被拦截并记录。

第三，生命周期状态机。每个 fiber 有状态机，ctx.effect() 第一行是 this.assertActive()，在已卸载的 fiber 上创建 effect 会直接抛 CordisError INACTIVE_EFFECT。卸载之后再注册副作用会被框架拒绝，从时间上消除了这类泄漏。

第四，事务性 HMR。即使作者的逆写得有问题，新代码 import 失败（比如语法错误）时，Algorithm 10 的 backup/restore 会让整个重载回滚到旧版本，系统不会停留在部分加载的状态。这是机制层面的最后一道保障。

边界外的操作，框架明确不追踪。 论文 §6.1 把环境分成两半：边界内（inside）是系统能独占修改、且能恢复原状的位置，操作记录在 Γ，可以 recover；边界外（outside）二者缺一，操作表现为 idΓ，既不追踪也不恢复。注意边界按位置划分，与介质无关：私有路径的 scratch 文件、只有本系统写的内存属于边界内；公共文件、别的进程也在写的东西属于边界外。直接改全局变量、monkey-patch、写公共文件，都是边界外的操作。框架不会追踪这些操作，也不会声称能恢复它们。这是设计上明确声明的边界。

更细的一层是获取/发射两阶段：获取阶段（open/malloc/fork）在边界内、可逆；发射阶段（write/send 的数据离开系统）在边界外、不可逆——恢复只能靠 withholding（暂缓发射，直到状态确定）或 compensation（补偿动作：删除创建的文件、退还收到的款项）。补偿也按 LIFO 组合，但元理论不再保证。

工程上怎么处理边界外的资源？论文 §6.1 给了一个手段：coeffect 通过物化外部位置来移动边界——把所有对该位置的访问限制在一组操作内，其中每个操作都提供逆，于是原本表现为 idΓ 的操作变得可追踪、可恢复。在工程上，这就是服务（service）抽象：开发者通过 ctx.database、ctx.assets 访问这些资源，不直接接触数据库连接、文件句柄、子进程。资源生命周期被关进服务自己的 effect 里，服务提供者负责写对的逆，消费者只面对高层接口。副作用从插件代码各处集中到服务实现内部，作者义务集中到少数服务实现者身上。

还有最后一个问题：逆写得对不对，怎么判定？论文 §3.3.2 不要求"物理复原"，因为那做不到（free 不会还原堆布局，生成式名字不会再生）。恢复保证读作观察等价：

两个状态相关，当没有任何观察者能区分它们。比较行为而非表示……等价关系由 coeffect 各自携带的等价组装而成。

"逆转"的含义是观察层面的还原：恢复前后的状态，没有任何观察者能区分。这就是逆的正确性标准。堆布局没有还原也没关系，只要没有任何 coeffect 操作能察觉差异，就算恢复成功。

这一章的保证可以分层整理成一张表：

总结一下。框架把"必须通过 ctx.effect 修改上下文"变成唯一路径，把"逆是否正确"留给作者义务，并明确声明系统边界。工程上的落点是服务物化：副作用集中在服务实现内部，义务从"每个插件作者"收敛到"少数服务实现者"。论文还有一句很诚实的话："回调提供了逆，但该逆是否真的恢复了伴随它的效应，是组件作者的责任（obligation），而不是运行时验证的性质（property）"。运行时保证"逆会被调用"（结构性），不保证"逆写得对"（语义性）。

顺带一个观察：这套设计在 TS/JS 里落地最直接。 大多数编译语言的类型系统基于类，类型布局在编译期固定，无法通过动态加载新的编译结果来覆盖；加载进内存的类型信息通常也无法卸载。TS/JS 是原型系统，类型结构可以动态调整：Agent 造一个新工具，直接挂在原型上，所有子组件立即感知并调用；撤销时从原型链切断，系统状态立即恢复。Proxy 提供"逻辑上极度解耦、语法上完全透明"的动态路由——代码写下 ctx.tool 时，Proxy 完成动态寻址与权限检查，静态语言很难实现这一点。Module Augmentation 让插件能动态修改全局 Context 的类型定义，agent 生成的新工具，类型提示和安全检查瞬时同步给整个系统，实现"动态演化"与"类型安全"并存。另外，JS 有程序化的模块注册表，可以卸载模块并让垃圾回收回收相关对象；在像 Swift 这种语言里，彻底清理已加载的类型元数据几乎不可能。

四、ctx.<service> 怎么解析：一个 Proxy 加一条 Fiber 链

插件之间怎么互相拿到对方提供的能力，值得单独说一下，这是"everything is a plugin"能落地的另一半。

根上下文被包了一层 Proxy：new Proxy(this, ReflectService.handler)。访问 ctx.tools、ctx.llm、ctx.session 这类属性时，走的是 Proxy 的 get 陷阱。自身已有的属性直接走原生的 Reflect.get，遇到没见过的属性名，先查一下有没有注册过的访问器，没有就沿着当前 Fiber 往上找：

let fiber = ctx.fiber
while (true) {
  const impl = fiber.store?.[prop]
  if (impl) return impl.value
  if (prop in fiber.inject) throw new Error('service not active')
  if (!fiber.runtime) throw new Error('unknown service')
  fiber = fiber.parent.fiber
}

一路往父 Fiber 走，直到找到提供这个服务的那一层，或者确认真的没人提供，抛错。

真正把一个服务"发布"出去的地方是 Service 这个基类，构造时调用 self.ctx.reflect.provide(name, self, check)。provide() 本身也包在 ctx.fiber.effect(...) 里：往当前 Fiber 的 store 里塞一条 {name, value, fiber, check} 记录，再唤醒等着这个服务的依赖方。返回的撤销函数负责把这条记录从 store 里摘掉，并重新通知一遍。一个服务被移除，走的是跟插件卸载完全一样的那套 effect 撤销机制，没有另开一条特殊路径。系统里没有一个专门的"服务注册中心"类。ctx.<name> 这种写法背后就是一次 Proxy 拦截加一次沿 Fiber 链的查找。谁在哪一层注册了什么，直接决定了谁能看到什么。

这套设计带来一个直接后果：作用域隔离是天然的。子 Fiber 能看到父 Fiber 注册的服务，反过来不行。想让某个插件的服务只在特定范围内生效（比如某个 preset 专属的文件系统实现），不需要额外的可见性控制逻辑，把这个插件挂在对应层级的 Fiber 下面，查找链条自然会把它限制在那个范围里。

这套机制的价值在一个真实场景里能看清楚。DeepSeek Harness 定义了一份"llm"服务接口（packages/llm/llm），只规定"怎么发一次流式调用、怎么处理重试"，不关心具体是哪家模型。系统里同时挂着两个实现这份接口的插件：dsh-llm-deepseek，专门适配自家模型；dsh-llm-pi-ai，内部包了一个第三方 npm 库 @earendil-works/pi-ai，专门做多家模型厂商的协议转换（这个"pi"和外界拿来对比的那个 Pi agent harness 是两个不相关的东西，撞了名字）。官方近 40 家可选模型厂商，大部分由后面这个插件支持。两个插件互不知道对方存在，装哪个、换哪个，上层 agent loop 的调用方式不用改一行，因为它调的是接口本身。官方文档管这种搭配叫"设计验证双胞胎"：两套完全独立的实现都能满足同一份定义，从侧面证明这份接口写得足够通用。

五、Agent Loop 里真正值得说的几处设计

Loop 的整体形态跟眼下大多数框架差不多，模型输入输出、检测工具调用、执行、回填，不重复讲。挑几处具体做法值得展开。

第一，轮次的结束条件有多种来源。除了"没有新的工具调用"，工具执行结果本身可以带一个 concludesTurn: true 标记。工具的执行逻辑用这个标记声明"这一轮该停了"，不需要等模型再说一句"好了"。

第二，max-tokens 状态是粘性的：

if (turnEnds === null || turnEnds.kind !== 'max-tokens') turnEnds = stepEnd

一旦某个 step 因为撑满输出上限被截断，即便后续的 step 正常完成，轮次最终报告的结束原因也不会被覆盖为"正常完成"。上层（统计、日志展示）看到的"这轮被截断过"的信号，不会因为后续步骤正常完成而被覆盖。

第三，轮次真正关闭前会广播一个 agent/turn-stopping 事件，这是一个可以被插件截住的钩子。插件调用 agent.steer(...) 塞一条新消息，轮次会继续跑下去；什么都不做，默认就真的结束。"什么时候真正收尾"这件事从 loop 内部移到了外部，任何插件都能在最后一刻决定"还没完，我还要说点什么"，loop 本身不需要预先知道有多少种"还没完"的理由。

第四，工具调度这块，每次实际调用前都会向工具询问能否并行，判断不依赖静态白名单：

executionMode(exec): ToolExecutionMode {
  const tool = this.resolveExecution(exec.name, exec.agent)
  if (!tool?.isConcurrencySafe) return { kind: 'exclusive' }
  return tool.isConcurrencySafe(exec.arguments) === true
    ? { kind: 'parallel' }
    : { kind: 'exclusive' }
}

同一个工具，不同的参数组合能给出不同的答案（读文件永远并行安全，写文件只有目标路径不冲突才安全）。调度器组队执行时，会在启动下一个调用之前重新判定一次模式。并行组里如果混进了一个当下判定为互斥的调用，会就此截断这一组，不会把互斥调用硬塞进并行批次。结果按模型原始给出的调用顺序提交，与调度完成顺序无关。

第五，工具执行前后的检查是独立的、可插拔的阶段，各自单独注册，不写在工具执行函数内部。tools/pre-execute 是一个 waterfall 事件，任何插件都能在这里拦截或者要求审批；通过后才进入内置的防护检查（比如同一个工具带同样参数被连续调用太多次会被提醒）；然后才是真正调用工具体；跑完还有 tools/post-execute 让插件对结果做二次处理。这四段是固定顺序、彼此独立注册的插件挂载点。新增一种审批策略或者防护规则，不需要改动执行链路本身，挂一个新的事件监听就行。

六、Preset 的两层 Scope 链：真实继承与影子路由表

Preset 的挂载机制解决了一个具体问题：怎么让同一份配置被多个会话复用，又不用每次都重新解析一遍配置文件。

一份预设是一个目录，核心是一份 agent.cordis.yml，按顺序列出要挂载的插件和参数。挂载这份文件用的是一个复用自 cordis 生态的 Include 插件，改名叫 PresetTree：

const handle = agentCtx.plugin(PresetTree, { path: pathToFileURL(preset.path).href })
await handle.await()

PresetTree 重写了两个方法：解析裸模块名时，查找基于系统自己的 baseUrl，预设目录不参与解析；写回配置被直接禁用，预设源文件不会被意外修改。挂载完成后还会核对两件事：有没有哪一行插件配置停在不可用的状态，有没有哪个服务在挂载过程中"泄漏"到预设作用域之外。任何一项不满足，都会整体回滚。

scope 链的构造方式值得细看。从全局到某个预设，是一次真实的上下文派生：createScope() 内部调 ctx.plugin(scope) 拿到一个 Fiber，再 fiber.ctx.extend({[kScope]: key})，这一步在 Cordis 的上下文树里真实存在一个节点。从预设到具体某个会话，则使用另一种方式：

this.bindings.set(agentKey, bindScopeParent(agentKey, standing.key))

bindScopeParent 往一张 WeakMap 里记一条"逻辑上级"关系，不在 Cordis 的 Fiber 树里新开任何节点。

这么拆开的动机很直接：一份预设的"标准挂载实例"只建一次（ensureStanding()），后续任意多个会话——写作的、编码的、调研的——都可以复用同一份实例，靠的就是往这张 WeakMap 里追加一条绑定，不用每接一个新会话就重新跑一遍插件加载。子 agent 要继承父 agent 当前挂的预设，调用的 composeFrom(childCtx, parentCtx) 也只是这张表上的一次查找加绑定，是同步操作，不会重新触发任何插件的挂载流程。子 agent 拿到的是跟父 agent 完全同一份插件实例，包括同一批已经注册好的工具和提示词片段。

会话当前生效的是哪个预设，判定逻辑是倒着扫事件日志，找最新一条 agent-preset/selected：

for (let index = session.events.length - 1; index >= 0; index -= 1) {
  const event = session.events[index]
  if (event?.type === 'agent-preset/selected') return event.data.agentPreset
}
return session.header.agentPreset

完全没有这类事件才回退到会话创建时的默认值。理论上，一个会话中途换预设是架构允许的操作，查找逻辑天然支持这种情况，实际用不用是产品层面的决定。

预设的发现机制也值得一提。扫描一个预设根目录时，只认目录名匹配特定命名规则、且内部有 agent.cordis.yml 的子目录。逐个校验 YAML 是否能解析、结构是否合法，损坏的条目标记出来，不会中断整个扫描。多个根目录合并时，按顺序先出现的 id 优先，后面根目录里同名的预设被忽略——这给了"用户自定义预设覆盖官方预设"（或反过来）的空间，取决于根目录的注册顺序。

七、Code Mode 的隔离方案：worker_threads

让模型写代码去编排多个工具调用，这个思路眼下不算新鲜，Codex 也做了一套。值得细看的是隔离方案的选型和落地方式。

DeepSeek Harness 跑这段代码用的是 node:worker_threads，一个普通的 Node 工作线程，与常见的 V8 隔离环境或者 vm2 是不同类型的方案。选这条路有一个明确考量：node:vm 那类基于同进程的沙箱，原型链可以逃逸到主环境，热循环也无法从外部真正打断，被认为不可靠。换成独立的工作线程，代价是每次跑代码都要开一个新线程，换来的是一个真正独立的 V8 堆，以及一个可以从外部强制终止的执行环境。

模型写的代码，先过一遍 stripTypeScriptTypes 把类型标注剥掉，剥的时候用一层包装前后缀撑住位置：

const stripped = stripTypeScriptTypes(prefix + program + suffix)

保证剥完之后代码原本的行列号不变，报错定位对得上。剥完的代码被塞进一个动态构造的异步函数：

const AsyncFunction = (async () => {}).constructor
const fn = new AsyncFunction(...bindingNames, ...errorClassNames, 'console', code)
const value = await fn(...bindings, ...errorClasses, consoleShim)

每个工具命名空间、每个约定好的错误类、还有一个替换用的 console，都变成这个函数的形参和实参。模型写的代码里可以直接用顶层 await，也能直接 return 一个值出来。

工作线程本身有资源上限，resourceLimits.maxOldGenerationSizeMb 限制堆内存。另外有两道独立的超时：一道拿事件循环利用率轮询，计算这段代码占了多少 CPU 时间；一道是一个简单的 setTimeout，兜底总耗时。任意一道触发都会强制中断。

代码里调用工具，通过消息通道完成，不直接引用函数：

{ type: 'call', id, global: 'tools', name, args }   // worker → host
{ type: 'reply', id, ok: true, value }              // host → worker

宿主收到调用请求后，把它当成一次正常的工具调用，推进第五章讲的那条 pre-execute/防护/dispatch/post-execute 流水线，与模型直接发起的结构化工具调用共用同一套执行内核，只是入口不同。通道两端都手动校验每一条收到的消息字段。宿主侧查找绑定函数用 Object.hasOwn() 精确判断自有属性，构造暴露给代码的 tools 命名空间时，用 Object.create(null) 起手，再逐个 Object.defineProperty 挂载。这些做法都是为了同一个目的：防止代码里塞进 __proto__ 或 constructor 这类字段，绕过原型链产生意料之外的行为。代码注释里直接写"把 worker 当成敌对的另一方来处理"，这个信任假设是明确声明的。

Codex 那套做法的核心差异在隔离层：用一个独立的 V8 isolate，工具挂在一个全局的 tools 对象上，官方描述是"在一个全新的 V8 隔离环境里执行这段 JavaScript"。两边解决的是同一个问题——用代码编排多个工具调用、减少往返——隔离技术选型不同，背后权衡的是"每次新建一个 isolate 的开销"和"每次开一个工作线程的开销"哪个更划算，以及各自生态里现成的隔离原语是什么。

八、工具注册的分层遮蔽算法

工具怎么在不同作用域之间"就近覆盖"，是插件化设计里容易被忽略但很关键的一块，决定了 preset 能否真正替换工具。

每个作用域维护一份自己的 ToolLayer，内部是一份按名字索引的表。决定"当前 agent 能看到哪些工具"的，是 view() 这一步：先加载全局层的工具，作为基础；再让每一层祖先 scope 依次覆盖同名条目，越靠近当前 scope 的祖先优先级越高——这一步只处理继承来的那部分。限制规则（比如某个 preset 明确禁掉了某个工具）在这之后筛一遍。最后，当前 scope 自己直接注册的工具，覆盖前面所有继承来的同名条目，即使限制规则禁用了这个名字。这一步的顺序很关键：自己注册的工具优先于继承和限制规则。

注册这一步本身也有硬校验：

register(definition: ToolDefinition): () => void {
  if (definition.name === RUN_CODE_NAME) {
    throw new Error(`tool name "${RUN_CODE_NAME}" is reserved for the Code Mode transport`)
  }
  assertSupportedJsonSchema(definition.output.schema)
  return this.layers.effect(this.ctx, layer => layer.tools.insert(definition.name, definition))
}

run_code 这个名字被硬编码保留，任何插件都不能注册或者覆盖它。理由写在代码注释里：任何 agent 都可能给自己选一个代码模式，一个在默认部署下看似空闲的名字，一旦某个 preset 挂载进来，随时可能跟 Code Mode 的调用入口产生冲突，所以无条件预留。

注册动作本身也走 effect()：调用 register() 拿到的撤销函数，插进当前 Fiber 的 disposables 列表。一个插件注册的工具，会随着这个插件被卸载自动从层里摘掉，不需要额外写一段"卸载时记得把工具删掉"的清理代码——这跟第二章讲的效果撤销机制是同一条路径，工具注册只是众多"注册即副作用"里的一种。

工具执行本身也复用了这套调度器的并发契约。Code Mode 里模型代码调用工具时，调用会进入宿主侧同一个 TOOL_RUNTIME_SCHEDULER 的待处理队列，与模型直接发起的结构化工具调用共享同一份并发控制、同一套前置检查——这也是上一章说 Code Mode 与普通工具调用"共用同一套执行内核，只是入口不同"的原因。

九、跟 Codex 比，几个工程决策的差异

核心循环的可替换性。 Codex 的工具接口、审批策略、沙箱策略都能配置，但驱动"采样-执行-反馈"这条循环的代码固定在核心中，无法作为独立单元替换。DeepSeek Harness 里这条循环的具体实现（ReactLoopAgent）注册为一个工厂，理论上可以被另一套完全不同的循环实现替换掉。目前只有这一个实现挂在系统里，工厂只允许注册一次。

沙箱的位置。 Codex 把 Linux 下的 bwrap/Landlock、macOS 下的 Seatbelt，直接编译进核心执行路径，属于基础设施。DeepSeek Harness 把沙箱做成一层能力插件，Linux 上通过一个独立的原生 Node 扩展调用 Landlock，走的是前面几章讲的同一条服务注册路径，理论上可以换成别的隔离实现，调用它的工具代码不需要改动。

代码规模的拆分粒度。 Codex 的 Rust 代码分成大约上百个 crate；DeepSeek Harness 的 TypeScript 代码分成两百多个包。两边都不是单体架构，但 Codex 拆出来的模块最终都服务于同一个不可替换的核心循环；DeepSeek Harness 拆出来的模块（包括循环本身）理论上都处在同一个可替换层级上，没有哪一个模块的地位特殊。

代码编排工具调用的隔离选型。 两边独立得出了同一个功能判断：工具调用除了单个结构化请求之外，还应该支持用代码编排。落地时隔离技术不同：Codex 选了独立的 V8 isolate，DeepSeek Harness 选了 worker_threads。第七章已经展开过这个差异背后的取舍。

工具暴露方式的粒度。 Codex 的工具接口里，暴露方式（DIRECT/DEFERRED/CODE_MODE/Hidden）是工具自己声明的一个静态标记。DeepSeek Harness 里，一个工具在某个 scope 下可见还是被覆盖，是运行时按 scope 链实时计算出来的，同一个工具在不同会话里的可见性可以完全不同，取决于挂载了哪些 preset。

附：从进程启动到一次工具调用，整条链路走一遍

进程启动，先看用的是哪个启动档（Profile），决定整个进程要装哪些插件包，交给 Cordis 的加载器逐个挂载，每个插件对应一个 Fiber。装完，host 这一层准备好模型接入、凭据管理、沙箱这些运行时基础设施。

一个会话开始，agent 注册表分配一个具体实例，这个实例挂在"全局-预设-会话"这条 scope 链下面。能看到哪些工具、哪些提示词，取决于它在这条链上的位置，以及第八章讲的那套遮蔽规则。

Agent Loop 接管这个会话的运转：读取当前上下文，请求模型，检测工具调用，交给统一的工具流水线走一遍前置检查、执行、后置处理。

每一步发生的事，不管是模型的输出还是工具的结果，都作为一条事件追加进这个会话的日志里，不删除、不覆盖。这份日志同时是持久化的来源、下一次请求的上下文来源、网页界面的展示来源，三条用途都从同一份日志投影出来。网页界面本身也是挂在这套体系里的一组插件。

这篇文章讲了不少具体机制：Cordis 的 Fiber 生命周期和 effect 撤销栈，ctx.<service> 的 Proxy 解析，agent loop 里几处细节设计，preset 的两层 scope 链，Code Mode 的隔离选型，工具注册的分层遮蔽算法。这些机制拼在一起，解决的是做 agent 产品、或者深度使用 agent 时会反复遇到的几个具体问题。

第一个问题是加能力和改能力的风险。常见的做法是在一个核心循环外面挂插件，核心本身很少改动，因为改动一次要担心影响面，回归测试也要重新跑。DeepSeek Harness 把风险控制粒度做到了插件级：一个插件注册的所有东西都通过 effect 登记，卸载时按注册的反顺序原样撤销。新增或者替换一个能力，影响范围被框定在这个插件自己的边界里，验证范围也缩小到这个边界。

第二个问题是，想让同一套 agent 服务不同场景，又不想每次都重新搭一遍环境。preset 的两层 scope 链解决的是这个：一份预设的插件树只挂载一次，写作、编码、调研几种不同用途的会话共享同一份已经跑起来的实例，靠一张逻辑父子表分流复用。

第三个问题是多步骤任务里，一次一个工具调用的来回成本。Code Mode 把这类任务的编排逻辑交给模型自己写代码解决，减少了"说一句、等一下"的往返次数。这块 DeepSeek Harness 和 Codex 几乎同时给出了同一个判断，只是隔离方案选得不一样。

第四个问题是工具的可见性和权限，在不同场景下常常只有两种状态：一个工具要么全局可用，要么全局不可用。分层遮蔽算法把可见性变成运行时按 scope 链实时计算的结果，同一个工具在不同预设、不同会话里可以有完全不同的可见性，工具代码里不需要写一堆条件判断。

这几处设计共同指向一个更大的判断：agent 产品的竞争力，除了模型效果，还取决于运行时这一层。运行时怎么组织、扩展成本有多高、换一个组件要付出多大代价，这些工程决策同样会影响一个 agent 产品用起来顺不顺手。DeepSeek Harness 把重点放在这一层，用 Cordis 这套现成的插件框架，以及"可逆副作用"这套设计哲学，把这一判断落实到具体的代码结构上。效果怎么样，还得看这套架构在真实使用里能撑多久，能不能撑住更复杂的场景。

P.S. 在写这篇文章中提到的那个示例插件的时候还把UI给搞崩了，看来HMR的稳定性还有待提升啊

展望：一个能对自己热更新的运行时，会走到哪

社区里已经有人给 DSH 做了连接通讯工具的插件了，比如把 Telegram、Discord 上的消息接进来。当年 Koishi 靠 Cordis 把 QQ、Discord、Telegram、微信的几十个插件拼在一起，成了聊天机器人圈的现象级项目，也留下了"改完配置 reload daemon"的日常。如今同一个运行时内核被搬进 agent 产品，通讯工具插件开始出现——当年那条路正在 DSH 上重演，只是这一回，底层自带一条 agent loop。

另一条路也在同时进行。Hermes、OpenClaw 这类个人 AI 助手的成长方式，是往技能库里不断加 skill：能力变多，运行时的结构基本不动。DSH 的成长方式在另一个维度：插件可以热装卸，界面是插件、会话记录是插件、循环本身是插件，连 webui 都能在持续服务的同时被换掉。论文里那句"未来的 harness 会在持续服务请求的同时生成并部署对自己组件的修改"，在这件事上已经开始兑现了。

所以问题值得认真问一遍：那个整天 reload daemon 的"龙虾"，动不动就把自己给搞炸，这次是不是真的可以下班了？DSH 会成为旧一代"插件机器人框架 + 手动配置"工作流的 AI 上位替代吗？

现在没有答案，但 webui 即插件，意味着产品形态本身可以热更新：改界面、换交互、加新视图，不需要重启宿主，也不需要发布新版本。要替代的如果是一种工作方式，那它就是"拼插件、写配置、重启验证"这个循环本身被压缩了。

对个人开发者来说，想做一个 AI 产品，以前要写前端、配后端、搭 agent 框架，三块互不相通；在 DSH 上，这三层都是插件，挂进同一个运行时，界面还能直接热更新。一个想法到可用的原型，甚至到能交付的成品，中间的距离正在被明显压缩。原型阶段跑通的东西，加一个 preset、配一个插件，就可能直接变成产品的一部分。

不过，从"偏开发者"走到"面向普通开发者"，中间还有一段路。现在跑 DSH 需要装 Node 环境，开终端手动敲命令启动 server。这套用法对写代码的人是日常，对普通开发者来说确实算不上优雅。技术复杂度不降下来，"个人快速做出 AI 产品"就只对少数人成立。好在插件化的好处恰恰在这里：宿主怎么启动、界面怎么呈现，都是可以替换的插件。把这层复杂度包进安装包、包进一键启动，属于产品化的问题，架构上已经有位置放它了。

它能不能成为这个家族里下一代的现象级项目，最后取决于几件事：生态里长出来的插件够不够多，真实场景撑不撑得住，面向普通开发者那层使用复杂度什么时候能被包起来。

目前 DeepSeek Harness 还是一个偏向开发者的产品，但相信距离其发展成一个“Agent 界的 VSCode”这一天已经不远了。

推荐插件：生态建设飞快！

这篇文章写到这里，GitHub 上 #dsh-plugin 这个 topic 下已经有 1000+ 个仓库了（检索时 API 统计 1008 个）。官方本体 deepseek-ai/deepseek-harness 之外，第三方插件、客户端、教程都在长。要翻全量清单，从几个精选索引入手最快：

• awesome-dsh-plugin/awesome-dsh-plugin（256⭐）— 插件精选列表，中英双语

• AdamPlatin123/awesome-dsh-plugins（507⭐）— 自动扫描索引所有 dsh 插件候选

• 0xsline/awesome-deepseek-harness（227⭐）— DSH 生态精选：插件、工具、基础设施

• Electricitysheep/dsh-handbook（74⭐）— 从 0 到 1 的 DSH 深度手册，含插件开发

Web UI 增强 ：

• zhu1090093659/dsh-web-ui（922⭐）— 任务面板、Git 图、皮肤中心合集

• omdsh-dev/DSH-better-sidebar（371⭐）— 侧边栏工作台：文件、终端、Git、子代理

• Small-tailqwq/dsh-deep-whale（237⭐）— 鲸鱼娘皮肤系列

• lhh010/dsh-minigames（10⭐）— 右侧 18 款小游戏摸鱼面板

视觉 / 多模态

• liustack/modlens（857⭐）— 第一个视觉插件：OCR、布局、语义结构化证据

• Anionex/dsh-vision-toolkit（232⭐）— 图片问答、长截图 OCR、UI 还原

终端与桌面端——"把复杂度包进安装包"已经有社区在做：

• ccch1mneyyy/dsh-TUI（487⭐）— Claude Code 风格全屏终端 UI

• Ruler4396/dsh-launcher（40⭐）— Windows 轻量启动器

• bruc3van/dsh-desktop（10⭐）— 社区第三方桌面客户端

记忆 / 上下文——让会话跨过 session 的边界。

• csyangwen/dsh-memory-evolve（24⭐）— 跨会话长期记忆 + 自我进化

• Anionex/dsh-turn-rewind（25⭐）— 对话 / 代码状态回退

多 Agent / 工作流——把 agent 编排成团队。

• NanmiCoder/dsh-agent-teams（142⭐）— AgentTeams 插件

• icetomoyo/dsh_workflow（42⭐）— 把一次性调度升级为可治理的 Workflow 层

通讯与通知

• PlutoKeating/dsh-lark-bot（4⭐）— 飞书机器人

• sliverp/DeepSeek-harness-qqbot — QQ 机器人

• LoserFox/telegram — Telegram

• omdsh-dev/dsh-notification（26⭐）— 桌面通知

开发配套——做插件的人先给自己做了工具。

• omdsh-dev/dsh-genui（36⭐）— 对话内生成式 UI

• omdsh-dev/dsh-at-file（62⭐）— Codex 风格 @file 引用

• vlln/plugin-registry（21⭐）— 插件生态基建 + 开发引导

star数为写文时参考值，具体以实际为准。完整清单，可以查看 github.com/topics/dsh-plugin 。

撰文的参考资料，感谢大佬们分析：

• 为什么用 Cordis 做 AI Agent 运行时：从 QQ 机器人框架到 DeepSeek Harness（CSDN）

• DeepSeek Harness 背后的秘密，Cordis 的设计哲学深度解读（知乎）

• Cordis 88 页设计论文：一个运行中的 Agent，能不能"换零件"而不重启？

今晚19:00直播DeepSeek Harness 拆解，不见不散～

跳转微信打开

这是一份 WorkBuddy 的「从入门到精通」完整指南

作者：孔德远，WorkBuddy  产品经理

这是一份 WorkBuddy 的「从入门到精通」完整指南，从下载安装到基础使用，再到进阶玩法与效率技巧，3 万字带你一步步摸清 WorkBuddy 的核心能力。无论你是第一次接触，还是已经用过一段时间、想进一步解锁更多玩法，都可以在这里找到答案。

温馨提示：WorkBuddy 仍在持续迭代中，本文部分章节及操作界面可能会随产品功能更新有所调整，具体功能及使用方式请以 WorkBuddy 最新版本为准。

接下来，就从安装 WorkBuddy 开始。

安装WorkBuddy

1.1 Windows 安装

1.1.1 下载

首先安装WorkBuddy，点击登录网址https://www.codebuddy.cn/work/，选择WorkBuddy，点击立即下载WorkBuddy

1.1.2 安装

下载之后，双击安装

点击我同意此协议

点击完成

1.1.3 登录（用户）

点击登录

选择微信登录

扫码登录

登录之后，在头像处点击，选择语言，可以切换语言：

1.1.4 更新

单击头像，单击检查更新

这个表示是最新版本，没有的话它会自动下载安装更新

1.2 Mac 安装

1.2.1 下载

访问WorkBuddy官网：WorkBuddy - AI Agent 办公新范式

点击“下载WorkBuddy”，电脑搭载M系列处理器（M1，M2或以上版本）选择“Mac ARM64”，老款英特尔处理器选择“Mac X64”。

允许下载

1.2.2 安装

双击浏览器下载内容或访达-下载目录下的WorkBuddy安装包，打开安装程序

拖动图标至Applications

等待安装

“推出”WorkBuddy安装程序，清理桌面

1.2.3 登录（用户）

在程序坞启动软件，或使用Command+空格检索WorkBuddy启动

启动界面如图，点击登陆按钮

跳转网页登陆，阅读并勾选服务条款和隐私协议，微信扫码即可登陆，若电脑已登陆微信可选微信快捷登陆

登陆成功后返回WorkBuddy即可开始使用

1.2.4 更新

点击左下角个人中心，选择检查更新即可检查是否有新版本，并且更新

功能篇

你可能用过 ChatGPT 等 AI 聊天工具——你问它一个问题，它给你一段回答，然后就没有然后了，剩下的事还得你自己动手。

WorkBuddy 不一样，它不只是跟你聊天，而是真的能动手帮你做事，它可以直接读取你电脑上的文件，理解里面的内容，然后按你的要求去操作——整理文件夹、生成报告、制作 PPT、分析数据、批量处理表格，甚至帮你写代码、搭建网站。

你只需要用一句普通话告诉它你想做什么，它就会像一个坐在你旁边的同事一样，自己规划步骤、自己动手执行，最后把做好的成果交给你。

这里是一个 All in One 的 AI 工作台

2.1 新建任务栏：本地日常 AI 工作台

在新建任务中可以看到左侧是我们的功能区，右侧对话框是我们的产品功能

2.1.1 页面介绍

2.1.1.1 选择适合你的工作模式

WorkBuddy 提供了三种工作模式，对应不同的"放权程度"。

你可以把 WorkBuddy 想象成你新招来的一个助手，这三种模式就是你给他划定的权限范——是只让他回答问题，还是让他直接上手帮你干活，又或者让他先出个方案你审批后再动手。

问一问（Ask 模式）

在这个模式下，WorkBuddy 只能看你的文件、回答你的问题，不会对你电脑上的任何东西做修改。

比如你想问"这份合同里有没有提到违约金条款"、"帮我总结一下这个表格里的数据"，它会认真看完之后给你答复，但绝不会动你的文件。就像你问同事一个问题，他只会口头回答你，不会去翻你桌上的东西。

Ask 模式不会直接执行操作，仅作为对话聊天，适合先问清楚怎么做，再切换 Craft Agent 模式执行。

做一做（默认Craft 模式）

这个模式下，WorkBuddy 拥有最大的权限，可以直接帮你操作文件——整理文件夹、生成文档、做 PPT、处理表格，说一句话就帮你干完，最适合日常使用。

比如"帮我把桌面上这堆文件按月份分好类"、"根据这份数据做一个汇报用的PPT"，它就会自己动手完成。就像你把钥匙交给了助手，让他放手去干，效率最高，体验也最顺畅。建议在指定好工作文件夹、做好备份之后使用。

想一想（Plan 模式）

这个模式是 Craft Agent 模式的增强版。WorkBuddy 可以查看你的文件，但不会直接修改，而是先给你写一份详细的执行计划——打算分几步做、每一步做什么、会动到哪些文件。

等你看过计划觉得没问题了，再让它去执行。就像装修房子之前先看设计图纸，你点头了师傅才开工。适合任务比较复杂、或者你希望对过程有更多掌控的时候使用。

新手建议：刚开始使用可以先从"Ask"模式入手，熟悉之后再切换到"Plan"或"Craft"，逐步放开权限。重要文件记得提前备份，用起来更安心。

2.1.1.2 切换模型

WorkBuddy 内置了多个主流 AI 大模型，你可以根据手头的任务随时切换。

这就像你手边有好几支不同的笔——签字笔写得正式、彩笔画得好看、铅笔方便修改——你可以根据需要随时换一支，也可以让 WorkBuddy 帮你挑。

下面简单介绍几个可选的模型，帮你在需要的时候做出选择：

MiniMax M2.5

擅长处理办公类任务，比如整理 Excel 表格、做数据分析、生成 PPT 等。如果你的日常工作主要和文档、表格打交道，选它比较合适。速度也很快，干活利索。

智谱 GLM-5

综合能力很强的一个模型，尤其擅长处理需要多步骤、长流程的复杂任务。比如你让 WorkBuddy 做一个完整的市场调研报告，需要先搜集资料、再分析整理、最后输出成文档，GLM-5 在这种"连环任务"上表现不错。

Kimi K2.5

最大的特点是"能看图"。你可以直接把截图、照片甚至录屏丢给它，它能看懂图里的内容并据此完成任务。比如你拍了一张纸质表格的照片，让它帮你录入成电子版，或者截图一个网页让它照着做一份类似的文档，Kimi 在这类"看图干活"的场景下很拿手。

DeepSeek V3.2

以性价比著称，日常对话、文案撰写、知识问答都很在行，响应速度快，消耗的额度也相对较少。如果你的任务不算特别复杂，用它既省钱又好使，是个实用的"万金油"选手。

2.1.1.3 设置工作目录

在开始使用 WorkBuddy 之前，有一个很重要的步骤：告诉它你要在哪个文件夹里干活。这就是"设置工作目录"。

打个比方，你请了一个助手到公司帮忙，你总得先告诉他："你的办公桌在这儿，要用的资料都在这个柜子里。"工作目录就是你给 WorkBuddy 指定的那个"柜子"——它默认会从这个文件夹里读取文件，生成的新文件也会放在这里面。

当然，如果你在对话中明确告诉它去别的地方找文件（比如"帮我把桌面上那个表格也拿过来处理一下"），它也能做到。但如果你什么都不说，它就只在这个文件夹里活动。

什么是文件路径？

这里需要解释一个概念：路径。路径就是一个文件或文件夹在你电脑里的"地址"，就像现实中的门牌号一样。

比如你在桌面上有一个叫"工作资料"的文件夹，它的路径大概长这样：

Windows 电脑：C:\Users\你的用户名\Desktop\工作资料

Mac 电脑：/Users/你的用户名/Desktop/工作资料

看起来有点复杂？不用担心，你完全不需要手动去拼这串地址。在 WorkBuddy 里设置工作目录时，你只需要点击选择按钮，然后像平时找文件一样，一层一层点进去，找到你想要的文件夹，选中它就行了。就跟你用微信发文件时选择文件是一样的操作。

如果图方便，不需要在特定文件夹下工作，直接点击新建任务，WorkBuddy 也会在每一个任务开始的时候新建一个文件夹来作为默认工作环境，实现和其他文件隔离。

怎么选一个合适的工作目录？

建议你为每一类任务单独建一个文件夹。比如：

要整理发票 → 建一个"发票整理"文件夹，把发票都丢进去，然后把它设为工作目录；

要写周报 → 建一个"周报"文件夹，把相关素材放进去；

要处理一批照片 → 建一个"待处理照片"文件夹；

或者偷懒，让 WorkBuddy 帮你创建和整理文件夹。

这样做的好处是：WorkBuddy 不会误碰到你其他的文件，你的东西井井有条，万一出了问题也只影响这一个文件夹。

2.1.1.4 选择技能

WorkBuddy 刚装好的时候，它已经能帮你做不少事了——写文档、整理文件、回答问题。但就像一个新员工，虽然脑子聪明，手边的工具还不够多。技能（Skills） 就是给它"配装备"的。

打个比方：WorkBuddy 本身是一个聪明的大脑，但光有大脑还不够。你想让它做海报，就给它装一个"海报设计"的技能；想让它做 PPT，就装一个"PPT制作"的技能；想让它帮你上网查资料，就装一个"联网搜索"的技能。每装一个技能，它就多长出一双"手"，能多干一类活。

怎么使用技能？

在对话框里，你可以直接选择想要启用的已安装的技能。选中之后，WorkBuddy 在执行任务时就会调用对应的技能来完成工作。

比如：

你选了"PPT 制作"技能，然后说"帮我把这份销售数据做成一个汇报 PPT"——它就能直接生成一份排版好的演示文稿。

你选了"海报生成"技能，然后说"帮我做一张中秋节活动海报"——它就能帮你设计出来。

你选了"自动化报表"技能，然后说"把这几张 Excel 表合并，生成一份图表报告"——它就能一步到位。

WorkBuddy 目前内置了超过 20 种技能包，覆盖了文档处理、数据报表、海报设计、文件整理等常见办公场景，而且完全兼容 OpenClaw 社区的上万个技能，可以按需导入。你也可以自己创建新技能，不需要写代码，用自然语言描述就行。

一句话总结：WorkBuddy 本身是大脑，Skills 是它的工具箱。你根据要干的活，往工具箱里放对应的工具，它就能帮你把活干了。工具越多，它能做的事就越多。

2.1.2 新建任务

在 WorkBuddy 里，每一个对话就是一个"任务"。你可以把任务理解为一条独立的工作线——每条线上有一个 AI 助手在帮你处理一件事，它们之间互不打扰。

打个比方：你去银行办事，只开一个窗口的话，必须排队等一件事办完才能办下一件。

但如果同时开了好几个窗口，你就可以一边在 1 号窗口办转账，一边在 2 号窗口办信用卡，一边在 3 号窗口打流水。

WorkBuddy 的多任务就是这个意思——你可以同时开好几个"窗口"，让 AI 同时帮你做不同的事。

而且，每个任务都有自己独立的工作空间。1 号任务在处理你的财务报表，2 号任务在帮你写方案，3 号任务在整理文件夹——它们各干各的，不会互相影响，也不会把文件搞混。

如何新建任务？操作很简单：在 WorkBuddy 的主界面，点击"新建任务"，就可以新建一个任务了。若未指定文件夹，则默认为你创一个Claw 的工作目录。

在输入框输入你想让 AI 做的事，选好工作目录和模型，按回车发送就行了，一个新的任务就跑起来了。这时候你不用等它做完，可以再点"新建任务"，开第二个、第三个任务，让它们同时干活。

所有正在运行的任务都会显示在左侧的侧边栏里，就像手机上的聊天列表一样，你可以随时点击切换，查看每个任务的进度和结果。

一句话总结：一个任务就是一个独立的 AI 工作台。多开几个任务，就像同时请了好几个助手，各干各的，互不打扰。WorkBuddy 就是你的 All-in-One 工作平台——编程、写文档、做报表、整理文件，全都可以在一个软件里同时进行。

2.2 助理页面：远程遥控的"监控室"

简单来说，Claw 页面是专门服务于远程遥控场景的，你可以通过手机远程给龙虾发指令，它在本地接收指令并执行，然后你可以在本地查看执行结果。

2.2.1 助理页面是什么？

前面我们提到，WorkBuddy 可以通过微信、企业微信、QQ、飞书、钉钉等手机上的聊天工具远程下达指令。

你在手机上给"龙虾"发一条消息，它就会在你的电脑上自动干活。

那问题来了：你人不在电脑旁，怎么知道龙虾干得怎么样了？

这就是助理页面的用途。

它就像一个"监控室"，你回到电脑前打开这个页面，就能看到龙虾在远程工作时的完整记录：它是怎么思考的、做了哪些操作、生成了什么文件、最终结果是什么，一目了然。

点击“助理”后的文件夹图案，可以看到其工作目录

和普通任务有什么不同？

助理页面虽然看起来也像一个对话窗口，但它有几点和普通任务不一样：

工作目录是固定的：它默认使用一个叫 "Claw" 的专属文件夹作为工作空间，不能像普通任务那样自由指定目录。

不能新建对话：普通任务可以随时在当前工作空间下开新的，助理页面只有这一个，所有远程指令都在这里进行，也无法并行开多个任务。

没办法清空上下文：普通任务可以清除之前的对话记录重新开始，助理页面不行，它会保留完整的对话历史。

建议：如果你人就在电脑前，想让 AI 帮你干活，还是直接在主界面新建任务更方便——可以自由选择工作目录，开多个任务，随时清空重来。Claw 页面更适合"人在外面，活在电脑上"的远程办公场景。

2.2.2 如何配置助理远程连接

点击左下角个人中心中的“设置”。

选择“助理设置”，后续可以配置企业微信集成、企微AIBot集成、微信客服号集成等等功能，具体配置方法详见下文。

2.2.2.1 接入QQ

点击“QQ机器人集成”的配置按钮

方案一：扫码绑定

选择“扫码绑定”，使用手机QQ扫描二维码

手机界面出现确认连接界面。

1）若存在机器人，可直接点击连接。

2）若不存在机器人，点击创建新机器人，选中创建的机器人，点击连接，点击同意，则连接成功。

方案二：WebSocket长连接

1.登录 QQ 开放平台

通过以下链接访问QQ开放平台。QQ开放平台

使用QQ或者邮箱方式登录QQ开放平台。

若之前没有使用过QQ开放平台，请点击立即注册并注册账号。

按照要求填写邮箱地址，设置登录密码，并完成实名认证后，完成账号注册。

2.配置超级管理员、主体及认证信息

设置超级管理员。

填写相关信息，可为自己或他人设置超级管理员。

填写主体信息。

包括企业、个体户、个人，请根据实际情况按需选择。

下图以个人为主体为例，表单填写完成后点击继续。

信息审核成功且通过人脸识别后，即可入驻 QQ 开放平台。

3.创建 QQ 机器人

打开https://q.qq.com/#/网站，扫码登录。

选择类型进行创建资源，选择机器人后，点击创建QQ机器人。

然后点击创建机器人，即可完成创建。

可以修改机器人的名称，头像及介绍，点击确认即可。

提交后，可以看到修改后的机器人。

4.获取 AppID 和 AppSecret 信息进行连接

复制AppID、查看 AppSecret 并复制。

注意：当第二次复制 AppSecret 时需要重置。

在 WorkBuddy 中填写刚刚获得的 AppID、AppSecret。

此处选择 Web Socket 长连接，配置简单，连接稳定。

点击注册即可开始使用

方案三：使用URL回调

1.选择“使用URL回调”，复制粘贴获得的 AppID、AppSecret，点击注册

2.从“助理设置”中获得QQ集成的 Webhook

返回WorkBuddy复制得到的 Webhook。

3. 在QQ 开发平台配置回调地址

点击机器人后台https://q.qq.com/#/apps?tab=1，选择需要配置的机器人，点击高级设置（⚠️注意如有多个机器人，请选择对应的机器人配置Webhook）。

在回调配置请求地址，粘贴复制上述 Webhook，保存此WebHook。

https://q.qq.com/qqbot/#/developer/webhook-setting

⚠️注意由于 Claw 中默认带有https ，粘贴的地址需要去掉 https:// 后进行复制到请求地址中。

确认配置 WebHooks 回调地址。

在回调配置栏添加所有单聊权限。

4.开始使用 WorkBuddy Claw

完成配置后， QQ 扫码进行聊天https://q.qq.com/qqbot/openclaw/index.html

首先点击沙箱配置后，点击在消息列表配置处的二维码。

回到 QQ 中与 WorkBuddy 互动，发送一个需求。

实时执行效果预览。

2.2.2.2 接入元宝

方案一：扫码接入

在“助理设置”中找到元宝扫码绑定

打开手机“元宝”APP，选择“我们”，点击“我的Bot”。

选择“关联已有OpenClaw”，点击“扫描二维码”，扫描桌面端二维码即可

手机端需点击“授权关联元宝”，即可连接成功

方案二：配置集成

在“助理设置”中找到“元宝机器人集成”，点击右侧的“配置”按钮

打开手机“元宝”APP，选择“我们”，点击“我的Bot”。

选择“关联已有OpenClaw”，在这里可以看到App Id和App Secret

回到桌面端，中对应位置输入App Id和App Secret，点击注册

连接成功

2.2.2.3 接入企业微信

前提条件

在开始之前，请确保您已满足以下条件：

已在电脑上安装 WorkBuddy，并开启了 Claw 远程控制功能。

拥有一个可创建智能机器人的企业微信账号。

提示：

如您尚未在企业微信中拥有企业，可以参考创建&注册企业来创建一个新企业。

使用长连接接入

推荐优先使用长连接模式。它的配置步骤更少，也不需要回填 Webhook URL。

打开 WorkBuddy，在「助理设置」里找到「企微助理集成」，点击「配置」。

在弹窗中选择「WebSocket 长连接」，选择快捷绑定接入。

使用手机企业微信APP扫描弹出的二维码。

手机完成授权与确认。

回到客户端，点击「注册」完成绑定。

编辑机器人信息

机器人创建完成后，可按路径「智能机器人」→「管理」→「编辑」修改相关配置项。

主要配置项 | 说明

机器人名称 | 建议填写容易识别的名字，如「WorkBuddy 助手」

可见范围 | 选择哪些员工、部门或标签可以使用这个机器人

使用 URL 回调接入

创建企业微信智能机器人

可根据您的账号角色选择不同入口：

管理员：前往企业微信管理后台，扫码登录。进入「安全与管理」→「管理工具」→「智能机器人」→「创建机器人」→「手动创建」。

普通成员：在企业微信客户端依次点击「工作台」→「智能机器人」→「创建机器人」→「手动创建」。

填写基本信息

根据实际情况填写机器人名称，科技范围，简介等。

在企业微信中生成回调凭据

随机获取Token 和 Encoding-AESKey并保存，此字段是用户户企微与WorkBuddy 通信时进行加解密密钥。

重要

您需要用 Token 和 Encoding-AESKey 在 WorkBuddy 设置页中换取 URL，请务必保存好。

** WorkBuddy 中生成 Webhook URL**。

打开 WorkBuddy 的 Claw 配置菜单，进入「集成（BETA）」→「企微 AIBot 集成」→「配置」。

在注册弹窗中切换到「使用 URL 回调」。

填写c中获取到的 Token 和 Encoding-AESKey。

注册成功后，复制生成的 Webhook URL。

回填URL并保存

回到企业微信机器人创建页面，填入刚才复制的 Webhook 地址粘贴到 URL 输入框并保存。

使用企微机器人

添加完成后，即可在企业微信聊天窗中与机器人直接进行对话。

发送一条简单消息（例如“你好”）进行联通测试。如果配置正确，WorkBuddy 会接收到消息并在企业微信中返回回复。

恭喜

如果机器人能够正常回复，说明您已成功完成 WorkBuddy 与企业微信的对接！

2.2.2.4 接入微信客服号

进入助理设置打开微信客服号集成。

点击右侧的「配置」按钮。

等待绑定初始化

点击配置后，WorkBuddy 会先创建一条用于绑定的客服会话，按钮会短暂显示为「绑定中...」。

使用微信扫描二维码

初始化完成后，页面会展示一个二维码。使用手机微信扫描该二维码，即可将当前微信账号

与 WorkBuddy 绑定。

注意：二维码有时效限制。如果二维码过期或扫码失败，请重新点击「配置」生成新的二维码后再试。

确认绑定成功

扫码完成后，WorkBuddy 会展示当前已绑定的微信头像和昵称，右侧状态会变为「已绑定」。如果后续需要更换账号，也可以在这里点击「解绑」后重新绑定。

开始使用

绑定完成后，您就可以直接在微信里和 WorkBuddy 对话，例如：

帮我总结今天桌面上最新的会议记录。

帮我检查这个项目最近改过的接口有没有明显问题。

帮我生成一个登录页原型。

WorkBuddy 会在电脑上自动执行任务，并把执行过程和最终结果同步回微信聊天窗口。

恭喜：如果您已经能在微信里收到 WorkBuddy 的执行结果，说明微信接入已经完成。

2.2.2.5 接入微信小程序

WorkBuddy 微信小程序实现把完整的 AI 生产力从桌面解绑，装进移动端：微信。用户在手机上就能用文字，语音、图片以及文件下达任务，既支持云端沙箱即开即用，也能远程操控电脑桌面端的 WorkBuddy。

灵感到，一"虾"就办。

进入小程序并登录

可通过扫码或搜索进入小程序

扫描WorkBuddy首页展示的或下图中的小程序码进入小程序。

接入微信小程序

打开微信，下拉进入「小程序」搜索栏，搜索 腾讯 WorkBuddy，点击进入小程序。

浏览并勾选《用户协议》和《隐私政策》，然后点击「授权手机号登陆」按钮。

❗️注意：登录微信小程序需要与电脑端登录的微信账号保持一致，否则无法连接到本机。

登录成功后进入主页面，即可实现WorkBuddy与微信小程序的集成。您可以在微信小程序上给WorkBuddy布置任务啦。

主页面介绍

顶部导航：点击左侧菜单（≡）打开侧边栏。

环境切换：在「☁ 云上」和「🖥 电脑」之间切换任务执行环境

模式 | 解决什么问题 | 典型场景

☁️ 云上模式 | 彻底摆脱电脑依赖，云端沙箱即开即用 | 通勤、差旅、周末——没带电脑的任何时刻

🖥 电脑模式 | 远程操控桌面端 WorkBuddy，人走了电脑还能干活 | 已经离开工位，但需要电脑上的 WorkBuddy 执行任务

快捷入口：常用场景的快捷标签，可点击更多查看全部（仅支持云上模式）

快捷标签 | 用来干嘛

幻灯片 | 一句话生成一份 PPT/演示文稿

视频生成 | 文本即视频，宣传片、解说短片快速产出

深度研究 | 行业调研、竞品分析、深度报告，自动拆解 N 步执行

文档处理 | 文档整理、生成、格式转换、批量改写

... | 横向滑动查看更多场景

输入栏：消息输入框 + 附件按钮 + 语音按钮 + 切换模型按钮（仅云上模式支持）+发送按钮

侧边栏介绍

点击左上角菜单（≡）即可展开侧边栏，包含以下内容：

用户信息：显示当前登录的微信用户头像与昵称，右侧齿轮图标进入设置 。

执行环境（电脑/云上）：当前执行环境选中项为白色。

新建任务：点击新建任务，可以建立一个独立任务。

自动化和专家功能

云上模式支持自动化和专家功能，电脑模式仅支持自动化功能。

🤖自动化功能：就像AI助手设置了一个「自动闹钟」

你可以让AI助手定时自动执行任务，不需要你每次都手动发起对话

比如：每天早上9点自动检查邮件、每周五下午6点自动生成工作报告

🧠专家功能：WorkBuddy里的「行业老司机」，就像手机里有一堆“行业大咖”随时待命

默认AI助手是「通才」，什么都知道一点

专家功能让AI在特定领域变成「专家顾问」

比如：代码专家、写作专家、数据分析专家等

❗️注：这两个功能会在3.6和3.7中详细介绍

任务列表：展示所有历史任务

每条任务显示 状态图标（已完成/ 进行中）、任务名称和时间

点击右上角「编辑」可对任务进行管理（任务名称编辑和任务删除）

添加附件、功能与技能

可添加照片、视频、微信文件/手机本地文件、腾讯文档等附件

入口 | 功能 | 适用场景

摄像头 | 调用手机摄像头实时拍照 | 拍摄纸质文档、白板笔记、发票、名片等

照片/视频 | 从手机相册选择已有图片、视频 | 处理已保存的截图、照片、视频

微信文件 | 从微信聊天记录选择文件 | 上传 Excel、Word、PDF 等文件

手机文件 | 从手机本地选择文件 | 支持Word、Excel、PDF、TXT等格式

腾讯文档 | 选择所绑定的腾讯文档账号下的相应文档 | 上传Word、Excel、收集表等文件

摄像头：点击 摄像头 后，调用手机摄像头进行拍照。

每次拍摄 1 张照片，拍摄完成后自动返回对话界面

照片会显示在输入框上方，点击 × 可移除

如需拍摄多张，需再次点击 + → 摄像头 重复操作

照片/视频：点击 照片/视频 后，进入手机相册选择界面。

支持一次选择多张图片（最多5 张）

选中的图片显示在输入框上方，可逐张预览和删除

支持常见图片格式：JPG、PNG 等

✅推荐做法：需要多张图片时，先用手机自带相机拍完，再通过「照片」一次性选择上传。

微信文件：点击 微信文件 后，选择对应聊天框，进入文件选择界面。

支持一次选择多张文件（最多5个）

选中的文件显示在输入框上方，可逐个预览和删除

支持常见文件格式：Excel、Word、PDF 等

手机本地文件：点击 手机文件 后，进入文件选择界面。

特点同上述微信文件

腾讯文档：点击 腾讯文档 后，进入文件选择界面（首次使用需授权绑定腾讯文档账号）。

每次只支持上传一个文档

选中的文件显示在输入框上方，可预览和删除

支持常见文件格式：Excel、Word、收集表 等

可添加技能（Skills）

技能（Skills）就是给 WorkBuddy 配装备，让它能干更多种类的活。选中的技能会在当前对话中生效。

点击 添加技能 后，打开技能选择面板➡️根据自身的需求，选择对应的技能添加到对话框。

**常用技能示例： **

xlsx skill：处理 Excel 数据、生成图表

pptx skill：创建、编辑和分析演示文稿

docx skill：创建、编辑和分析Word文档

find-skills skill：帮助用户发现和安装skills

什么时候需要手动添加技能？

如果你希望明确指定使用某个技能，或者 AI 没有自动启用你需要的技能，可以通过此入口手动添加。

如何安装更多技能？

如果技能列表中没有你需要的技能，可以通过 SkillHub 获取更多：SkillHub-专为中国用户优化的Skills社区，搜索所需 Skill 后复制其安装指令，将安装指令粘贴至 WorkBuddy 对话框中发送即可，安装成功后即可在技能列表中使用。具体步骤如下：

搜索所需的skill

点击「安装方式」

选择「通过对话安装」，复制安装指令后，发送给WorkBuddy让其帮助安装skill，安装成功后即可在技能列表中使用。

可添加定时任务

点击 定时任务 将其添加到输入框上方，可参照上方的示例在输入框中输入您的定时任务需求。

可添加专家

点击 专家中心，在专家或专家中心搜索您需要的专家，点击对应的专家或专家团即可将其添加到输入框上方。

选择模型（仅云上模式支持）

点击输入框中的模型名称（如「Hy3 preview▾」），弹出模型选择面板。

可用模型一览

模型 | 能力标签 | Credits 消耗 | 推荐场景

Hy3 preview | 推理 + 视觉 | x0.04（限时折扣） | 超低成本的图片相关简单任务

GLM-5.1 | 推理 | x1.06 | 复杂代码架构设计、高难度数学/逻辑题、需要最强智能的任务

GLM-5.0 | 推理 | x0.80 | 多步骤复杂任务、长文分析、深度推理链场景

GLM-4.7 | 推理 | x0.23 | 日常首选——写文案、改代码、问答、通用对话

Kimi-K2.5 | 推理 + 视觉 | x0.45 | 截图分析、图片转文档、OCR 识别、看图说话

Deepseek-V3.2 | 推理 | x0.29 | 代码编写与调试、数据分析、中英翻译等通用场景

Deepseek-V4-Flash | 推理 + 视觉 | x0.13 | 最便宜的有视觉能力的模型，快速图片理解、简单 OCR

Deepseek-V4-Pro | 推理 + 视觉 | x0.25（限时折扣） | 需要理解图片内容的分析任务，兼顾性价比

Hunyuan-2.0-Thinking | 推理 | x0.04 | 最便宜的纯文本模型，适合大批量简单文本处理

能力标签

标签 | 含义

推理 | 支持逻辑推理、任务规划与多步骤执行

视觉 | 支持图片理解（拍照、截图场景请选择此类模型）

Credits 消耗

数字越低消耗越少。例如 x0.18 的模型比 x0.95 的模型便宜约 5 倍。

任务执行与对话

云上模式

适用于周末、旅游等没带电脑的时刻，且无需电脑上的文件即可处理工作的场景。

以快捷标签「深度研究」为例，任务发送后，WorkBuddy 自动拆解并逐步执行。

步骤拆解

「拆解为 N 个步骤」：显示该阶段包含的子步骤数量

「已完成」标签：该步骤已执行完毕

点击卡片右侧 > 可展开查看详细过程

继续追问

任务完成后可在同一对话中继续追问。

WorkBuddy 会保持上下文，无需重复描述背景。

中断执行

任务进行中时，输入栏会显示停止按钮（■），点击可随时中断当前执行。

中断后仍可继续补充说明或调整需求。

电脑模式

适用于已经离开电脑，但需要WorkBuddy利用电脑上存储的文件来处理工作的场景。

可处理电脑上的文件，并将AI助手返回的结果同步在微信小程序和电脑端Claw页面中

AI助手的工具调用和思考过程信息仅在电脑端的Claw页面中展示

对于下图中的任务（无需操作电脑上的文件）可在云上和电脑模式执行

案例实践

一拍即得，两个大脑同时在学习（云上模式）

老师刚讲完一个章节，板书写满了整块黑板。你掏出手机，打开 WorkBuddy 小程序，拍一张照，语音说一句「整理成笔记，保存起来」。就这样，任务交给了云端的 WorkBuddy。手机放回口袋，继续听下一节。

下课后你还可以继续追问：让它针对这节课的内容出几道练习题，考察你对知识点的掌握程度。

紧急任务即收即处理（电脑模式）

产品经理小林正在出差路上，老板发来一条消息，要求今天内在「2025年前AI发展历程研究报告」的基础上加上2026年AI领域最新涌现的关键概念。

「2025年前AI发展历程研究报告」在公司电脑上。以前只能说"等我回去看看"——手机上没法处理电脑里的文件。

现在小林的电脑上运行着 WorkBuddy，手机上装了 WorkBuddy 小程序，两端直连。

小林打开微信 WorkBuddy 小程序，然后语音说了一句：「帮我列出2026年AI领域最新涌现的关键概念，并和桌面上的2025年前AI发展历程研究报告合并，整理一份综合研究报告给我。」

接下来不用管了。电脑端的 WorkBuddy 会调用工具完成2026年AI领域关键概念的深度搜索，并自动读取本地桌面的2025年前AI发展历程研究报告，在后台完成内容的合并处理——小林不需要坐在电脑前，电脑端就像一个远程待命的助手。

2.3 项目页面：多人协同，打造超级团队

点击项目

点击“新建项目”，然后根据提示，填入项目名称、指令，可以选择需要的连接器/专家/技能等。全部编辑完之后点击确定，即可创建新的项目

点击进入刚才新建的测试项目

点击右上角的邀请、复制链接，可以分享给项目成员，进入项目

选中动态，分别可以查看“与我相关”和“成员动态”

在下方聊天框中可以选择执行模式、模型、技能、连接器，也可以选择附件进行输入

开启这个任务之后，点击右上方的🔍，可以搜索对话内容

点击任务流转图标，可以进入任务流转，在任务流转里可以输入相应信息

选择处理人，状态（包含四种，分别是待开始、进行中、已暂停、已完成）以及截止日期

在最下方附件标识中可以上传本地文件/项目资产

可以点击增加成员，并复制链接给新增成员

点击右侧边栏，可以查看项目所产生的产物，与常规模式一致

与模型的对话会存储中“任务”中，点击任务可以查看

点击计划，可以查看代开始、进行中、暂停和完成的任务

点击新建待办

输入待办事项，点击创建

可以在对应的状态栏中看到新建的待办任务

点击添加数据源，可以选择添加所需要的外部数据源

对于已经添加的数据源，可以选择编辑、禁用或删除

点击资产，项目文件统一存放在这里。

这里是 WorkBuddy 为每个项目内置的文件管理中心，用来集中存放文档、设计稿、数据表格、图片等各类项目资产。

可以新建/上传文件，可以依据文件类型或关键词搜索定位具体文件。

2.3 右侧边栏：随时查看 AI 工作成果

WorkBuddy 的右侧有一个结果面板，任何任务只要有对话就可以在右上角打开这个面板。

展开后如图所示：

这个面板分为四个标签页，你可以理解为四个不同角度的"查看方式"。

2.3.1 产物

这里展示 AI 在当前对话中为你全新生成的文件，包括 PPT、PDF 报告、文档等各类创作成果。所有产出内容将自动在此处展示，并默认开启预览模式。如同助手完成工作后，将成品整齐呈现在桌面，打开「产物」即可查看本次对话的全部工作成果。

点击产物即可预览。

点击文件夹图标还可以在 Finder 中打开文件，直观显示文件位置。

2.3.2 全部文件

这里展示的是当前工作目录下的所有文件，以树状结构排列，点击右上角“展开箭头”展开。

如果你用过电脑上的文件管理器，这个就很好理解——文件夹套文件夹，一层一层展开，一目了然。

你不需要切到别的软件去翻找，在 WorkBuddy 里就能直接浏览整个工作目录的文件结构。

2.3.3 变更

这里记录的是 AI 修改了哪些内容，点击右上角展开即可查看哪些文件发送了变更。

它会把改动前和改动后的内容放在一起对比展示：被删掉的部分标红，新增加的部分标绿。这样你一眼就能看出 AI 到底动了什么、改了什么、加了什么。

就像老师批改作文一样，红笔划掉的是删的，绿笔写上的是加的，改了哪里一清二楚。如果你觉得改得不对，也能及时发现并纠正。

2.3.4 预览

在这里可以预览开发的网页，无需跳转到浏览器即可直接打开。

2.4 技能市场：给你的 AI 助手装上更多本领

前面我们提到，技能（Skills）就是给 WorkBuddy 配装备，让它能干更多种类的活。而技能专栏就是管理这些装备的地方——装了哪些、还能装哪些、想开想关，全在这里搞定。

2.4.1 页面介绍

打开技能专栏，页面分为上下两个部分：

上半部分：展示你已经安装在本地的技能。这些是你的 AI 助手目前"身上带着的装备"，随时可以在对话中调用

下半部分：展示推荐安装的技能。这些是 WorkBuddy 为你推荐的热门或实用技能，觉得有用就点击安装，像手机应用商店里的"推荐 App"一样，看中了就装上

2.4.2 如何安装新技能

有三种安装方式：技能页面直接安装、导入本地技能包、向WorkBuddy描述任务需求查找和创建技能。

技能页面直接安装

在技能页面展示的技能卡片中找到您任务需要的技能，然后鼠标悬停在文件上，点击出现的添加图标即可安装技能

除了从技能页面直接安装外，你还可以导入自己下载的技能。比如你在网上看到一个好用的技能包，下载下来是一个 zip 压缩文件，操作流程是这样的：

把 zip 文件解压（右键点击，选择"解压到当前文件夹"就行）。

在 WorkBuddy 的技能专栏里点击"添加技能"下的上传技能。

1. 选中解压好的技能文件夹。

就这么简单，三步搞定。

WorkBuddy 会自动把技能配置到正确的位置，你完全不需要知道文件应该放到电脑的哪个角落、也不需要手动去找什么复杂的路径。

向WorkBuddy描述任务需求查找和创建技能

点击"添加技能"下的查找技能，输入任务描述，WorkBuddy将自动查找相关技能。

点击"添加技能"下的创建技能，输入任务描述，WorkBuddy将自动调用skill-creator技能，创建相关技能。

2.4.3 启动/关闭技能

装了一个技能之后，如果暂时用不上，不需要卸载，直接一键关闭就行。就像手机上的 App 通知开关一样——关掉之后这个技能不会在对话中被调用，但它还在那里，哪天想用了再一键打开，不需要重新下载安装。

你可以根据手头的工作灵活开关技能。

比如这周在做数据分析，就把报表相关的技能打开；下周要做设计，再切换成海报生成的技能。用不到的关掉，更节省上下文的同时还可以避免 AI 错误调用。

2.4.4 技能搜索

随着你安装的技能越来越多，列表可能会变得很长。不用担心，技能专栏支持搜索功能——在搜索框里输入关键词，比如"PPT"、"海报"、"表格"，就能快速定位到你想找的技能，不用一个一个翻。

2.4.5 卸载技能

需要在本机完全卸载技能时，可选择卸载技能：

支持批量操作卸载：

2.5 连接器 ：借助连接器，打通现有业务系统

2.5.1 连接器是什么

连接器就是给 AI 装上"数据线"，让它能直接连上你的各种外部账号和工具。 你不用自己打开邮箱、不用登录文档平台、不用切换应用，只要跟 AI 说一句话，它就帮你去各个平台上操作。

打个比方：你是一个老板，AI 是你的助理。连接器就是你给助理配的一串钥匙 — 邮箱的钥匙、文档的钥匙、项目管理工具的钥匙。助理有了钥匙，就能自己跑去各个平台帮你办事，你只需要坐在椅子上下指令就行。

能连哪些平台？

连接器 | AI连上后能帮你干嘛

QQ邮箱 | 查收邮件、发邮件、搜索邮件、汇总邮件内容

腾讯文档 | 创建、读写、编辑在线文档（Word/Excel/PDF等）

腾讯乐享 | 搜索知识库、管理文档、创建内容

TAPD | 查项目进度、管任务

微云 | 访问和管理云端文件

…… | ……

自定义连接器 | 自己接其他第三方服务

连上之后怎么用？

不用学任何新操作，继续用自然语言说话就行：

"帮我查一下今天收到了什么重要邮件" → AI 连邮箱帮你查

"把这个报告存到腾讯文档" → AI 连文档帮你存

"帮我总结乐享上最近更新的文档" → AI 连乐享帮你搜

关于安全

每个连接器都需要你主动授权，不会偷偷访问

不想用了随时通过开关关闭，或者直接断开

也可以在对应平台的 App 里管理授权（比如 QQ 邮箱 App → 设置 → 账号 → 安全管理 → 应用授权）

2.5.2 两种配置方式，灵活适配你的需求

配置级别 | 适用场景 | 说明 | 配置文件路径

🌐 用户级 | 一劳永逸型 | 配置一次，所有项目（文件夹）通用 | /Users/你的电脑用户名称/.workbuddy/mcp.json

📁 项目级 | 精准定制型 | 仅对当前项目（文件夹）生效 | /项目文件夹名称/.workbuddy/mcp.json

举个例子：比如你在工作中进行需要做完事情需要通知你的企业微信同事,那么配置一个用户级的企业微信机器人就行，所有项目(文件夹)都能直接用；如果某个项目(文件夹)需要对接特定的接入，配一个项目级的就行，互不干扰。

2.5.3 如何配置

连接器整个操作流程围绕三个核心动作：连上 → 管理 → 断开。

进入连接器管理页面

入口一：左侧边栏：点击左侧边栏的 "连接器" 图标，进入连接器管理页面

入口二：消息框快捷入口：在对话输入框区域，也支持快捷管理连接器，不用专门切到管理页面

进入后你会看到一个卡片列表，每个卡片代表一个可以连接的平台（QQ邮箱、腾讯文档、乐享、TAPD、微云等），显示当前的连接状态：

绿色圆点 = 已连接已开启

灰色圆点 = 已连接未开启

无圆点 = 未连接

连接平台（以QQ邮箱和腾讯乐享为例）

示例：连接QQ邮箱

QQ 邮箱连接器支持收发、搜索和整理 QQ 邮件，用自然语言读取邮件内容、汇总邮件线程、管理文件夹。

点击添加

在连接器管理页面找到 QQ邮箱 卡片，点击右侧的 + 按钮发起连接。

扫码授权

系统会跳转到 QQ 邮箱授权页面，显示二维码。使用 QQ 邮箱 App（7.1.5 / 鸿蒙 0.2.9 及更新版本）扫码进行授权。

确认权限

在手机端确认 WorkBuddy 申请的访问权限，包括：账号信息、读取邮件、发送邮件、删除邮件（可选），确认无误后点击 同意授权。

授权成功

手机端显示 授权成功，可在「设置 - 账号 - 安全管理 - 登录设备和授权码 - 应用授权」中管理授权应用。

连接完成

回到 WorkBuddy，QQ 邮箱卡片名称旁会出现绿色圆点，并提示 连接器 QQ邮箱 已连接，右侧显示启用/禁用开关。

示例：连接腾讯乐享

腾讯乐享连接器支持搜索、创建和管理乐享知识库中的文档，支持导入 Markdown、按标签整理内容、追踪团队文档的更新动态。

点击添加

在连接器管理页面找到 腾讯乐享 卡片，点击右侧的 + 按钮发起连接。

登录乐享知识库

系统会跳转到腾讯乐享登录页面，支持 微信登录、手机号登录 和 企业微信登录 三种方式。

确认授权

登录后进入授权确认页面，显示当前账号信息。通过乐享知识库 MCP，WorkBuddy 将能够：

按你拥有的权限访问知识库

搜索、查询知识库中的内容

协助创建与管理知识库中的内容

确认无误后点击 继续。

授权成功

页面显示 Authentication Successful，表示已成功完成认证，可关闭当前窗口返回 WorkBuddy。

连接完成

回到 WorkBuddy，腾讯乐享卡片名称旁会出现绿色圆点，右侧显示启用/禁用开关，表示连接已就绪。

自定义连接器

除了官方预置的平台，你还可以自己配置第三方服务：

打开配置页面

在连接器管理页面右上角，点击 "自定义连接器" 按钮

按引导配置

系统会引导你填写第三方服务的配置信息（基于 MCP 协议），包括服务的连接地址、认证信息等，配置方式与标准的 MCP 配置类似。

在司外我们和腾讯云开发者社区提供了更多丰富的 MCP 市场： https://cloud.tencent.com/developer/mcp（仅对司外）

您可在MCP市场上选择任务需要的MCP服务，然后使用说明逐步配置。

配置完成

保存后，自定义的连接器会出现在你的连接器列表中，和官方连接器一样，支持启用/禁用开关。

以企业微信机器人MCP为例

建议从最简单的企业微信机器人 [WeCom Bot ] (点击打开)这个 MCP 服务器开始，它实现了从项目需求和研发任务的事项管理，最容易上手，配置方式：

准备配置 ： 获取企业微信群机器人WebHook URL 地址。

配置路径： 新建企业微信用户群--添加群机器人--> 获取 WebHook URL 地址。

打开WorkBuddy，选择侧边栏的“连接器”，点击右上角“自定义连接器”。

点击配置MCP

在 WorkBuddy 中配置mcp.json， 添加企业微信机器人 MCP Server，保存即可，可复制配置文件。

{
"mcpServers": {
"wecom": {
"command": "uvx",
"args": [
"wecom-bot-mcp-server"
],
"env": {
"WECOM_WEBHOOK_URL": "your-webhook-url"
}
}
}

}

请将上面JSON中的 your-webhook-url 替换为你自己的企微机器人的url，如下所示：

https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=8ef877d5-7f76-45fa-b1f9-c8f27acb8f93

配置路径及效果图。

如果安装成功后 MCP Server 将显示绿色状态，否则显示红色状态，例如：

在WorkBuddy 中描述你的需求，WorkBuddy 将根据您的任务需求进行分析，然后调用 MCP Server 工具来完成您的任务，例如：利用企业微信机器人 MCP 通知 企业微信机器人 MCP Server 正式产品发布， @xxxx 进行验收 → Wecom Bot 自动@对应人员通知处理

应用效果: 群里直接@对应人员处理

从此，让 AI "连接万物"这件事，变得像安装手机 App 一样简单。

❗️注意：这个功能适合有技术背景、需要对接特定内部系统的用户。如果你暂时用不到，完全可以跳过。

2.6 专家中心：挑一个/一群"专业人设"帮你干活

WorkBuddy 是一个"什么都能聊、什么都能做"的通用助手，但有时候，你希望它在某个领域更加专业——比如你想让它专门帮你做数据分析，或者专门帮你写小红书文案，又或者专门帮你做电商运营。

专家功能就是干这个的。

你可以把它理解为给 AI 换一套"职业装"。同样一个 AI 助手，穿上数据分析师的衣服，它就会用数据分析的思路和框架来帮你工作；换上品牌策略师的衣服，它就会从品牌一致性的角度来给你出方案。不是换了一个 AI，而是同一个大脑，切换了不同的专业视角。

但有些任务，一个人搞不定。

比如你想开发一个软件——得有人定需求、有人设计和拆解任务、有人批量实现代码、有人做QA验证质量。一个人从头干到尾，既慢又容易顾此失彼。这时候你需要的是一个团队，而不只是一个专家。

怎么用？

打开专家中心➡️找到专家团➡️召唤一个专家团帮你干活

打开专家中心➡️往下滑找到专家➡️召唤一个专家帮你干活

支持在搜索框中输入您想要召唤的专家/专家团功能定位，查询相应的专家/专家团。

打开专家中心，你会看到一排排"专家卡片"。

专家团每张卡片上有团队名称和擅长的领域。点击专家团卡片可详细查看团队专家成员的名称、头衔、具体的分工及任务示例。

以软件开发团队为例，下述截图中可以看到：

齐活林 — 交付总监：管理团队的进度，验收并负责最后交付的软件产品质量。

许清楚 — 产品经理：定义软件产品的需求，撰写prd文档，画原型。

高见远 — 架构师：对软件产品的需求设计和拆解任务。

寇豆码 — 工程师：完成开发软件产品的相关代码工作。

严过关 — QA工程师：构造测试用例，测试并验证开发的软件产品。

专家每张卡片上有专家名称、头衔、擅长的领域和任务示例。

比如截图中可以看到：

吴八哥 — 高级开发工程师：10年以上全栈经验，精通多种语言和框架。

文爆爆 — 内容创作专家：擅长创作引人入胜的多平台内容，让品牌故事触达目标受众。

数妙妙 — 数据分析报告师：将复杂数据转化为清晰可执行的业务报告，让数据驱动决策。

像素君 — UI设计师：精通设计系统和组件库，追求像素级完美，打造无障碍用户界面。

看中哪个专家/专家团，点击"召唤"，就会以这个专家/专家团的身份开启一个新的对话。

之后你跟它交流时，它就会自动带入这个专业角色的知识和思维方式来帮你工作。

截至目前，WorkBuddy 已包含31个专家团、213位专家，覆盖产品设计、技术工程、金融投资、游戏空间、数据智能、营销增长等14大品类，足以辅助绝大多数人的日常工作。

技能 VS 专家 VS 专家团

维度 | 技能 | 专家（Agent型） | 专家团（Team型）

组成关系 | 工具能力：让AI能做某件事 | AI顾问：懂某个领域的AI角色 | AI协作团队：自动拆解、并行执行、完整交付

怎么选 | 需要AI具备某种工具能力 | 有一个明确的单点问题 | 任务复杂，需要多角色配合

什么时候用专家/专家团，什么时候用普通对话？

如果你的任务比较综合、没有特定领域倾向（比如"帮我整理一下桌面的文件"），直接用普通对话就够了。

如果你的任务属于某个专业领域（比如"帮我分析这份销售数据并给出运营建议"），召唤一个对口的专家/专家团会得到更专业、更有针对性的结果。

** 一句话总结：**专家中心就是一个"AI 人才市场"。按行业分类浏览，看中谁就召唤谁。同一个 AI，换上不同的专业身份，给你更专业的帮助。

2.7 自动化：让 AI 每天按时帮你干活

前面介绍的功能，都是你主动给 AI 下指令，它才开始干活。但有些事情是每天都要做、而且每次做的内容差不多的——比如每天早上整理行业新闻、每周五生成周报、每天下班前汇总当日数据。这些重复性的工作，何必每次都手动交代一遍呢？

WorkBuddy 的自动化功能就是帮你解决这个问题的。

你只需要设置一次，告诉它"做什么"和"什么时候做"，之后它就会像一个准时打卡的员工，到点自动开工，做完把成果放到指定的文件夹里，等你查看。

2.7.1 如何设置一个自动化任务？

打开自动化页面，点击“定时任务”可以看到已经安排的自动化任务，点击“运行记录”可以看到已完成的历史任务。

点击右上角“添加”，你会看到一个配置表单，需要填的内容很直观：

任务名称：给这个任务起个名字，方便你区分。比如"每日行业新闻"、"周五周报汇总"。

提示词示例：告诉 AI 具体要做什么。就是你平时在对话框里输入的那种指令，比如"帮我调研今天的 AI 行业新闻，整理成一份简报"。

工作空间：指定 AI 在哪个文件夹里干活，生成的文件也会保存在这里。比如你指定了"每日新闻"这个文件夹，那每天生成的简报都会自动存到这个文件夹下。

定时规则：设定什么时间执行。可以按照每天或者间隔一定时间再执行来设定。

选择模型和技能：指定模型和技能来执行这个任务，与前面介绍的模型选择和技能选择一样。

推送到小程序：开启后，推送会把文件同步到云端，这样在微信小程序能接收到数据。

举个例子

假设你想让 AI 每天早上 8 点帮你整理行业新闻：

任务名称填"每日行业新闻简报"。

提示词写"调研今天的 AI 行业最新动态，整理成一份简报，包含标题、摘要和来源链接"。

工作目录选择你电脑上的"行业新闻"文件夹。

定时规则设为每天早上 8 点。

选一个你常用的模型，打开推送到微信小程序的开关。

设好之后，每天早上你打开电脑，"行业新闻"文件夹里就已经躺着一份新鲜出炉的简报了，就像有人每天给你送早报一样。

2.7.2 预设模板：一键导入，开箱即用

如果你不知道该怎么给 AI 下指令，或者懒得每次都从头写提示词，WorkBuddy 提供了预设模板功能。

你可以把模板理解为别人帮你写好的"任务说明书"。比如"竞品分析报告"、"周报生成"、"会议纪要整理"这些常见的办公场景，都有对应的模板。你只需要选一个模板，点击一键导入，相关的提示词、工作流程就自动配置好了，你稍微改改里面的具体内容（比如把公司名换成你自己的），就可以直接用。

譬如选择“每日 AI 新闻推送”模版，选择工作空间，切换模型即可直接上手使用。

2.7.3 进阶玩法：干完活直接把结果发到你邮箱

前面我们介绍了自动化功能——AI 按时干活，把成果存在指定文件夹里。但有时候你不方便打开电脑去翻文件夹，或者你就想第一时间看到结果。这时候可以用一个进阶玩法：打通邮件，让 AI 干完活直接把结果发到你邮箱。（详细配置见实践篇）

配置好邮件之后，WorkBuddy 完成任务会自动把生成的文件通过邮件发送给你。无论你在哪里，打开手机邮箱就能收到。

把它和自动化功能结合起来，效果就更强了。比如：

你设了一个自动化任务：每天早上 8 点调研行业新闻。

同时配好了邮件通知。

那么每天早上你还没到公司，手机邮箱里就已经收到了一份整理好的行业简报。到了办公室打开电脑，文件夹里也有一份备份。你什么都不用做，AI 已经帮你把活干了，并且把结果送到了手边。

一句话总结：预设模板让你不用从零开始写指令，一键导入就能用。邮件打通之后，AI 不光帮你干活，还会主动把成果"送上门"。

2.7.4 进阶玩法：干完活直接把结果推送到WorkBuddy小程序

还有另外一个进阶玩法：打通WorkBuddy小程序，让 AI 干完活直接把结果发到小程序上。（详细配置见3.2.2.6）

打开配置后，WorkBuddy 可在任务执行完成后自动将结果发送至WorkBuddy小程序，便于第一时间查看。

在小程序中查看推送结果

2.7 我的文件

点击更多、我的文件

可以查看对话生成的文件

点击后方的...可以根据自己的需求保存、分享、收藏对应文件

不同类型的对话文件存在于不同分组

点击全部类型，可以根据文件类型检索相应文件

点击“云端网盘”，选择“上传文件”，可上传电脑文件至云端。

在云端网盘的文件可以实现跨端同步

2.8 资料库：借助 资料库，打造无缝衔接工作台

2.8.1 资料库是什么

资料库，简单说就是：把你的云端文档直接接到 AI 工作台里，让 AI 能直接看到、处理、甚至帮你写回文档，全程不用下载文件、不用上传文件、不用来回切换应用。

用一个比喻来理解：你现在有一堆资料锁在腾讯文档里，以前要让 AI 帮忙，你得先下载 → 发给 AI → AI 处理完 → 你再手动把结果存回去。资料库就是给 AI 一把钥匙，让它直接走进你的资料库，自己拿、自己看、自己用、自己存回去。

它能做什么？

搜索即找到 — 不用翻文件夹，用自然语言描述你想要什么文档（比如"找到上个月的财务报表"），AI 就能帮你定位。

点击即预览 — 找到文档后直接在 WorkBuddy 里预览，不用跳转到腾讯文档。

一键开工 — 选中文件后添加到任务，告诉 AI 你想干嘛（总结、改写、分析……），它直接基于文件内容干活。

产物存回云端 — AI 处理完的结果，可以一键存回你的腾讯文档，形成"取资料 → AI 加工 → 存回去"的完整闭环。

2.8.2 如何连接腾讯文档

在左侧边栏点击资料库，选择腾讯文档。

点击立即前往授权后 WorkBuddy 将能读取您的文档内容，为您提供总结提炼、智能问答，以及自动化文档创作与管理。

支持微信/QQ扫码登录对应文档账户。

其他授权信息如下图，同意后即可使用。

如果需要换绑资料库账号或关闭连接，可以点击对应文档，在右上角点击解除绑定。

资料库完整操作流程其实就是三步：找到文件 → 交给 AI 干活 → 结果存回去。

第一步：搜索文件

资料库提供 两种搜索方式，看你的需求选：

方式一：语义搜索（让 AI 帮你找）

新建一个任务，直接用大白话描述你要什么。AI 会理解你的意图，自动从资料库里匹配对应的文档。比如：

"帮我找到腾讯文档上周写的那份季度汇报 PPT"

"帮我找一下腾讯文档终端旅游助手文件"

方式二：关键词搜索（自己精准搜）

打开资料库页面，在右上方搜索框输入关键词后回车。

系统会按文档标题和文档所有者两个维度帮你筛选。

如果你知道文件名大概叫什么，用关键词搜索更快；如果只知道"大概是什么内容"，用语义搜索更省心。

第二步：在任务中引用指定文件

找到文件后，怎么让 AI 基于它干活？

在资料库列表里 选中你要用的文件（可以多选），点击 "添加到任务" 按钮（或者鼠标悬停在文件上，点击出现的添加图标），文件就出现在当前任务里了。

不仅支持选择在线文档，腾讯文档可以上传Word、Excel、PPT、PDF等本地文件，也可以在资料库中勾选，并添加到任务中。

添加文件后，AI 就能直接读取文件内容来帮你处理了。在输入框里告诉 AI 你想干什么，比如：

"把这份 Word 文档总结成一页 PPT"

"分析这个 Excel 里的数据，帮我画个趋势图"

"根据这份 PDF 的内容，写一段 200 字的摘要"

第三步：产物存回资料库

AI 干完活后，结果怎么保存？

在右侧 产物区域 找到 AI 生成的文件，点击文件上的 "上传到云端" 按钮，选择要存到的位置（对应的资料库）。

存储成功后，直接在腾讯文档的 "我的文档" 里就能找到。

一句话总结： 资料库 = 你的云端文档 + AI 的直接通道，省去了下载/上传/切换应用的繁琐步骤。

2.8.3 如何连接ima知识库

在左侧边栏点击资料库，选择ima文档。

点击立即前往授权后 WorkBuddy 将能读取您的文档内容，为您提供总结提炼、智能问答，以及自动化文档创作与管理。

使用微信扫码授权访问。

其他授权信息如下图，同意后即可使用。

如果需要换绑资料库账号或关闭连接，可以点击对应文档，在右上角点击解除绑定。

资料库完整操作流程其实就是三步：找到文件 → 交给 AI 干活 → 结果存回去。

第一步：搜索文件

资料库提供 两种搜索方式，看你的需求选：

方式一：语义搜索（让 AI 帮你找）

新建一个任务，直接用大白话描述你要什么。AI 会理解你的意图，自动从资料库里匹配对应的文档。比如：

"帮我找到ima知识库上周写的那份季度汇报 PPT"

"帮我找一下ima知识库终端旅游助手文件"

方式二：关键词搜索（自己精准搜）

打开资料库页面，在右上方搜索框输入关键词后回车。

第二步：在任务中引用指定文件

找到文件后，怎么让 AI 基于它干活？

在资料库列表里 选中你要用的文件（可以多选），点击 "添加到任务" 按钮（或者鼠标悬停在文件上，点击出现的添加图标），文件就出现在当前任务里了。

不仅支持选择在线文档，腾讯文档可以上传Word、Excel、PPT、PDF等本地文件，也可以在资料库中勾选，并添加到任务中。

添加文件后，AI 就能直接读取文件内容来帮你处理了。在输入框里告诉 AI 你想干什么，比如：

"把这份 Word 文档总结成一页 PPT"

"分析这个 Excel 里的数据，帮我画个趋势图"

"根据这份 PDF 的内容，写一段 200 字的摘要"

第三步：产物存回资料库

AI 干完活后，结果怎么保存？

在右侧 产物区域 找到 AI 生成的文件，点击文件上的 "上传到云端" 按钮，选择要存到的位置（对应的资料库）。

一句话总结： 资料库 = 你的云端文档 + AI 的直接通道，省去了下载/上传/切换应用的繁琐步骤。

2.8.4 如何连接乐享知识库

在左侧边栏点击资料库，选择乐享知识库。

点击立即前往授权后 WorkBuddy 将能读取您的文档内容，为您提供总结提炼、智能问答，以及自动化文档创作与管理。

点击继续

授权成功

如果需要换绑资料库账号或关闭连接，可以点击对应文档，在右上角点击解除绑定。

资料库完整操作流程其实就是三步：找到文件 → 交给 AI 干活 → 结果存回去。

第一步：搜索文件

资料库提供 两种搜索方式，看你的需求选：

方式一：语义搜索（让 AI 帮你找）

新建一个任务，直接用大白话描述你要什么。AI 会理解你的意图，自动从资料库里匹配对应的文档。比如：

"帮我找到ima知识库上周写的那份季度汇报 PPT"

"帮我找一下ima知识库终端旅游助手文件"

方式二：前往乐享知识库

打开资料库页面，在右上方点击“前往乐享知识库”。

第二步：在任务中引用指定文件

找到文件后，怎么让 AI 基于它干活？

在资料库列表里 选中你要用的文件（可以多选），点击 "添加到任务" 按钮（或者鼠标悬停在文件上，点击出现的添加图标），文件就出现在当前任务里了。

不仅支持选择在线文档，腾讯文档可以上传Word、Excel、PPT、PDF等本地文件，也可以在资料库中勾选，并添加到任务中。

添加文件后，AI 就能直接读取文件内容来帮你处理了。在输入框里告诉 AI 你想干什么，比如：

"把这份 Word 文档总结成一页 PPT"

"分析这个 Excel 里的数据，帮我画个趋势图"

"根据这份 PDF 的内容，写一段 200 字的摘要"

第三步：产物存回资料库

AI 干完活后，结果怎么保存？

在右侧 产物区域 找到 AI 生成的文件，点击文件上的 "上传到云端" 按钮，选择要存到的位置（对应的资料库）。

一句话总结： 资料库 = 你的云端文档 + AI 的直接通道，省去了下载/上传/切换应用的繁琐步骤。

2.9 灵感：零配置直接生成属于你的成品

2.9.1 灵感是什么

灵感功能，一句话说清楚：它就是一个预装好的"场景模板库"，里面已经帮你配好了各种常用场景，你不用懂技术，点一下就能直接用。

用一个比喻来理解：

还记得美图秀秀的滤镜吗？你不需要懂色彩原理、不用学调参，看到哪个好看，点一下，照片就变美了。

探索就是 WorkBuddy 版的"滤镜库"，只不过美化的是你的工作任务：

你不需要知道什么是 Prompt 工程（怎么跟 AI 说话）；

你不需要了解有哪些 Skill（技能）；

你不需要研究该选什么专家。

看到哪个场景符合需求，点一下就开干。

不知道从哪开始？打开 探索，浏览大家做出的 WorkBuddy 精选成品。

看中哪个，点击制作我的版本，即可实现Prompt、Skill、专家全部自动就位，零配置直接生成属于你的版本。

它里面有什么？

目前内置了 11 个预置场景模板，每个模板都帮你配好了：

适合这个场景的提示词（告诉 AI 该怎么做）

对应的 Skill 配置（调用什么技能来完成）

适配的专家

你只需要选一个模板，然后把你的具体需求填进去就行。

适合谁？

特别适合 刚接触 AI 工具的新手。如果你不知道 WorkBuddy 能干嘛、不知道怎么写提示词、不知道该用什么技能，打开"探索"逛一圈就能找到灵感，而且点一下就能上手，零门槛。

当然，老用户也可以用它来快速启动常见任务，省去重复配置的时间。

2.9.2 如何使用

探索功能整个操作流程就是四步：逛案例 → 看详情 → 一键开做 → 查成果。

第一步：打开探索

在 WorkBuddy 左侧边栏，找到并点击 "探索"，就进入了案例库页面。进入后你会看到：

精选板块 — 系统推荐的热门案例，随机展示，像刷朋友圈一样浏览。

场景分类 — 按不同的使用场景分类，可以按需筛选。

搜索功能 — 如果你有明确需求，可以直接搜索关键词找到对应案例。

就像逛淘宝首页：有推荐爆款，有分类导航，还有搜索框，三种方式都能找到你想要的。

第二步：选择案例

浏览时看到感兴趣的案例，点击它进入详情页，你会看到：

预览效果 — 这个案例做出来长什么样

使用的工具集 — 它调用了哪些 Skill 和专家配置

详情介绍 — 这个案例是干嘛的、适合什么场景

觉得不错？还可以点 红心收藏，把它存起来，方便下次找。

就像在短视频平台刷到一个好的教程视频：看看封面预览、了解视频内容，喜欢就收藏。

第三步：开始制作

这是最关键也最省心的一步：

在案例详情页点击 "做同款"，系统会自动帮你搞定所有配置：

✅ 自动预填好 Prompt（提示词）

✅ 自动加载关联的 Skill（技能）

✅ 自动配置对应的 专家

你可以选择两种方式：

直接生成 — 不想改什么？点一下就直接产出结果

修改细节再生成 — 想个性化？改改提示词里的内容，让它更符合你的需求

就像用美图秀秀的滤镜：系统已经帮你调好了所有参数，你直接用就行；想微调也可以，但完全不是必须的。

第四步：成果查看

生成完成后，在右侧产物区域查看结果：

文件类产物（Word、PPT、Excel 等）— 直接在产物区下载或预览。

网页类产物（HTML 页面）— 系统会自动打开内置浏览器，直接预览最终效果，所见即所得。

探索 VS 技能 VS 专家

模块 | 一句话理解 | 回答的问题

技能 | 工具箱里的工具 | WorkBuddy能做什么？

专家 | 工具箱里的专家顾问 | WorkBuddy里谁能帮我做？

探索 | 用这些工具做出来的真实作品集 | 用这些能力实际做出了什么？

打个比方：

Skill 是锅碗瓢盆（厨具）

专家 是不同菜系的厨师

探索 是厨师用厨具做出来的成品菜肴展示柜

养虾实践案例

基于腾讯 12000内测员工的真实使用实践，我们从大量一线案例中总结提炼出 10 个最具价值的应用场景。接下来，本文将通过 手把手的实战步骤，带你逐一落地这些场景，快速掌握其具体用法与实践方式。

3.1 文档内容识别与处理

3.1.1 一句话批量命名文件

提示词示例：

桌面上有个叫做“团建报销发票”文件夹，请检查其中发票的内容，生成一个报销简述，包含以下信息：- 日期- 商家名称- 消费金额- 消费类别（餐饮/交通/住宿/其他）- 备注并按照如下示例排序：2025.12.01  XX地址聚餐 消费金额：299 元最后分别按照支付的明细和发票的明细金额汇总，如有异常，帮我特殊标注除了最终直接输出结果外，还要以一个excel交付

3.1.2 整理会议纪要

提示词示例：

说明素材类型 + 要整理成什么文档 + 格式要求 + 粘贴原始内容以下是【素材类型，如：本周工作备忘 / 会议语音转文字 / 调研笔记】，请帮我整理成【目标文档，如：工作周报 / 会议纪要 / 分析报告】，格式要求：【列出关键格式，如：分条列举 / 含表格 / 含摘要】，读者是【目标读者】。【粘贴原始素材】

3.1.3 外文视频翻译

提示词示例：

我想将文件夹中的英文音频和视频文件转录成中文笔记，可以帮我实现吗？

3.2 文档生成与编辑

3.2.1 一句话制作Word文档

提示词示例：

帮我生成一份公司年会活动策划的 Word 文档框架，公司约 100 人，包含：活动目标、流程安排（含时间节点）、节目类型建议、预算构成清单、注意事项。语言简洁实用，适合拿去和领导确认方向用。

效果：

结果生成后，如果你觉得某些地方不对，不需要自己动手改文档——直接用自然语言告诉 WorkBuddy 即可，就像给同事提修改意见一样。比如：

“预算清单那部分不够详细”

“流程安排写得太笼统，每个环节补充一句注意事项”

“整体语气再正式一点，这个是要发给老板审批的”

WorkBuddy 会在原有基础上按你的要求更新，不需要重新写提示词，也不需要自己打开Word 去改。

3.2.2 根据素材和模板制作PPT

提示词示例：

还可以召唤”文档生成专家“辅助制作

效果：

3.3 数据分析并可视化

3.3.1 Excel表格转为可视化图表

当已有 Excel（.xlsx / .csv）格式的数据文件时，WorkBuddy 可以直接读取文件内容，根据需求生成对应的可视化图表。

3.3.1.1 导入数据文件

3.3.1.2 描述需求

示例提示词：

请读取工作区中的所有 xlsx 数据表，生成一份可视化分析报告PDF。重点分析 2 月各渠道的投放数据、转化率和 ROI 表现，并与 1 月历史数据做对比。报告需要包含多维度的图表和文字总结。

3.3.1.3 预览结果

3.3.2 数据搜集并生成可视化报告

当数据尚未整理成文件，或需要从网络、多个来源搜集信息时，WorkBuddy 可以完成从数据采集到报告生成的端到端流程。

3.3.2.1 描述数据需求

说明需要搜集的数据主题、范围和来源偏好，例如：

搜集近三年国内新能源汽车销量数据查找主流编程语言的 GitHub 活跃度排名汇总本项目各模块的代码行数和提交频率

3.3.2.2 描述报告要求

指定报告的格式与内容结构，例如：

生成一份包含趋势图和数据表格的 HTML 报告输出 Markdown 格式的分析报告，内嵌图表制作一个可交互的数据看板页面

AI 将根据需求，从公开数据源搜集相关信息，完成数据分析、图表绘制和报告排版，输出完整的可视化报告文件。

3.4 每日自动推送资讯简报

3.4.1 第一步：连接消息平台（以QQ邮箱为例）

3.4.1.1 开启 QQ 邮箱的 SMTP 授权码

登录 QQ 邮箱网页版 → 设置 → 账户与安全 →安全设置→找到「POP3/IMAP/SMTP 服务」→ 开启服务后「生成授权码」，按提示用手机发短信验证后会得到一串授权码，复制保存好（授权码不是你的 QQ 密码）。

3.4.1.2 在 WorkBuddy 中填写邮件配置

打开 WorkBuddy → 在对话框发送以下内容：

我需要配置 QQ 邮箱的 SMTP 服务，我的邮箱号码是：xxx，授权码是：xxx

配置完成后效果如下：

3.4.2 发出你的第一条简报报指令

先手动触发一次，验证效果。把以下指令粘贴到 WorkBuddy 的对话框，按回车发送：

基础版早报指令（可直接复制使用）现在请帮我生成一份今日简报，然后通过邮件发送到我的邮箱：你的邮箱@example.com简报报需要包含以下内容：今日天气：（你的城市）的今日天气预报（温度、降雨情况、穿衣建议）科技资讯：今天的 AI 和科技圈最新动态，精选 3 条，附简短摘要内容草稿：根据以上资讯，为我的公众号生成一个今天可以发的选题和开头段落AI 建议任务：主动思考你今天可以替我完成的 2-3 件事，并列出来邮件主题格式：【AI 简报】2026年3月2日 周一

WorkBuddy 会自动拆解这个任务，你能在界面上看到它一步步执行：搜索天气 → 抓取资讯 → 读取你的任务文件 → 生成文案 → 发送到QQ邮箱。整个过程约 2-3 分钟。

3.4.3 设置每日定时发送

手动跑通之后，接下来告诉 WorkBuddy 每天自动重复这件事：

请把上面的简报任务设置为定时自动执行：每天早上 8:30 自动运行，不需要我手动触发。执行完成后发送邮件到：你的QQ邮箱@qq.com。

可以看到AI自动创建了一个自动化任务，在左侧边栏“自动化”目录下可以管理所有自动任务。

3.4.4 个性化调整

WorkBuddy 的强大之处在于，改一条自然语言就能改变早报内容。以下是一些常见调整方向：

接入其他数据源："增加微博和知乎的每日热榜精选"

换资讯方向："只要 A 股和财经资讯，不需要 AI 新闻"

换风格："用轻松愉快的语气，每条新闻加一个 表情"

工作日专属："法定节假日不要发，只在工作日执行"

3.5 零代码制作本地应用

3.5.1 让AI帮你设计应用

为了更好的执行应用开发工作，让AI完成所有的代码和界面开发，我们选择代码开发模式开始新的对话。

在对话框中输入以下提示词：

我想构建一个个人笔记系统，在这个系统中我可以回顾我的所有的笔记，谈话，想法或提醒。请使用Next.js构建它。要求如下：1.所有内容的浏览列表，支持点击条目查看完整内容2.供全文搜索功能，支持按标题和内容搜索3.支持内容的新增，编辑，删除4.支持按日期和类型的快速过滤5.简洁、清爽的中文界面

WorkBuddy 会理解你的需求，自动生成完整的应用代码并运行，最终效果如图：

3.5.2 让AI帮你解决报错

当项目运行中出现异常时，只需在对话中描述观察到的现象，例如：

页面访问返回 404界面组件未正确渲染模块加载失败

AI 将自动执行以下步骤：

1. 分析上下文：结合项目代码与错误现象，定位根因2. 修改代码：直接对问题代码进行修复3. 重新运行：执行修复后的程序并验证结果

整个过程无需手动介入，也不要求使用者具备任何代码的调试经验。

提升修复效率的建议：

提供具体的现象描述。 例如，「点击保存按钮后页面白屏，控制台显示 TypeError」比「页面坏了」能帮助 AI 更快定位问题。

支持多轮排查。如果首次修复未完全解决问题，可以继续描述新的异常现象，AI 会基于上下文进行持续排查。

善用截图。 直接提供报错界面的截图，可以为 AI 提供更丰富的诊断信息。

3.5.3 让AI帮你升级系统

新的功能需求会随着系统使用自然产生。WorkBuddy 支持通过对话持续迭代系统能力，系统可以在持续使用中不断进化，而非一次性交付后固定不变。

以下是一些典型的升级场景示例：

需求描述 | AI 执行的操作

希望支持模糊搜索，不依赖精确关键词 | 接入本地 embedding 模型，实现语义搜索能力

每天早上自动推送待处理任务 | 配置定时任务，自动汇总并推送待办事项

通过 QQ 或微信随时录入内容 | 对接消息平台 API，实现移动端输入通道

新增内容时自动关联已有记录 | 构建知识图谱，自动检测内容间的关联关系

3.6 自我进化——创建自己的Skills（技能）

除了安装和导入技能库中的Skills，WorkBuddy还可以制作自定义的Skill，实现自我升级。

基于4.6制作的笔记应用，我们使用自制Skills的能力为它赋予真正有别于一般笔记软件的AI能力，让 AI 在任意对话中都能自动识别你的记录意图，并自主整理并保存。

在对话框中输入：

请帮我制作一个Skill，并安装到WorkBuddy，这个 Skill 的功能是：当用户在对话中表达了想要保存、记忆、提醒某件事的意图时（例如"帮我记住"、"保存这个"、"提醒我"、"这个值得记录"等），自动将内容写入笔记系统中。Skill 需要包含以下行为规范：1. 自动判断内容类型2. 每条内容包含：标题、类型标签、创建时间、来源对话摘要、正文内容3. 如果内容是链接或资源，额外提取并保存摘要4. 保存成功后，简短告知用户已记录制作完成后，将其安装至WorkBuddy

AI执行完成后，打开技能栏，在已安装目录下可以看到新增的Skill，即为安装成功。

效果：

在 WorkBuddy 的任意对话中，输入：

WorkBuddy 会自动识别到这是一条"灵感"类型的内容，然后将内容梳理后存入系统，最后回复告知你已记录成功。

高效养虾小技巧

4.1 从桌面端、痛点开始，别一来就远程

别把虾神话，也有边界，先从电脑PC端开始

非常推荐从 日常办公 PC 端和当前的痛点开始，远程 Claw 模式更适合具有技术背景的同学深入，很多新手一开始就远程接入，费了很大精力连上了远程，但不知道做什么，但是远程依赖的是电脑 PC 端需要保持在线，同时远程场景针对于复杂耗时的长任务、效果的返回体验没有 PC 端那么直接直观，新手非常建议从当前的痛点

4.2 清晰表达，给虾下达明确任务

做什么 + 有什么 + 怎么样，别让 AI 猜你的意图

很多新手第一次用 WorkBuddy，往往随手甩一句模糊的需求过去，然后对结果大失所望。原因很简单：虾不会读心术。你给的信息越少，它能发挥的空间越混沌。

想让虾精准执行，记住这个三要素公式：

💡 新手小贴士：如果不确定从哪里开始，可以先问虾：「我想做 XX，你需要我提供哪些信息？」让虾帮你梳理需要补充的要素，再开始正式提问。

4.3 小步快跑，一次搞定一件事

把大任务拆成小步骤，稳稳地推进

新手最常犯的错误之一，就是把庞大的需求一口气丢给虾——「帮我把整个项目重构一遍」、「把这份 50 页的报告全部翻译并总结」。结果往往是：虾出了一大堆内容，却没有一处完全令你满意。

更好的做法是：把大任务拆解成独立的小目标，一次只推进一步。

这样每一步都有明确的验收标准，出了问题也方便定位和回滚，不用推倒重来。

4.4 不满意就追问，别一轮定生死

对话是多轮的，和虾不断磨合，找到相处之道

很多用户第一次得到不满意的回答，就放弃了——这是最可惜的。AI 对话的精髓在于多轮迭代，第一次回答只是起点，而不是终点。

追问公式参考：

「太长了，缩短一半」· 「语气太正式，换成口语」· 「重点放在 XX 部分」· 「这个例子不好，换一个」· 「整体方向对，但第三段逻辑不通，重写」

把和虾的对话想象成和一个非常勤奋但需要你指导的实习生沟通。你越愿意给反馈，他进步越快，产出越好。

4.5 别怕试错，多换几种问法

同一个需求，换个说法可能效果天差地别

AI 对你用词的细微差异非常敏感。同一个需求，换一种表达方式，可能会得到完全不同质量的回答。描述越具体、越有场景感，AI 越能「代入」你的处境，给出更贴切的结果。

优化问法的几个方向：

换个角度：换一个切入视角重新描述需求

加上受众：明确说明内容面向谁

给出场景：描述一个具体的使用情境

设定限制：字数、格式、风格限定

角色代入：让虾站在某个角色的立场思考

4.6 给虾一个身份，它就更专业

「专家」功能：角色扮演是最简单的提质手段

WorkBuddy 内置了「专家」功能，提供了各行各业的预设角色——法律顾问、产品经理、数据分析师、营销文案……一键召唤，虾就会以该身份来回答你的问题。

本质上，这是在给虾设定一个「初始化角色提示」，让它的回答框架和专业用语立刻对齐对应领域的思维方式。使用专家角色的回答，在专业性和针对性上，效果会好得多。

4.7 给虾看例子，比说一堆要求管用

一个好的参考样本，胜过写十行要求

语言描述有时候难以精确传达你期望的「感觉」。这时候，最省力也最有效的方式是：直接把一个你满意的样本扔给虾，告诉它「照这个来」。

AI 更擅长"模仿"而不是"从零想象"。给它一个锚点，它就能在那个基础上发挥得更好。

4.8 善用多任务，别在烂上下文里死磕

不同的任务，开不同的会话

就像给每件事单独准备一张桌子，互不干扰，同时推进。写方案一个窗口、整理数据一个窗口、回邮件一个窗口，效率翻倍。

另一方面，当一个会话太长、虾开始"前说后忘"时，果断开新窗口，把关键背景简洁重述一遍。AI 的上下文窗口有限，对话越长能"记住"的越少。保持会话干净，才能让虾保持清醒。

4.9 易「虾」改，频繁备份和版本管理

虾可能“虾”改，改崩了就回退

WorkBuddy 再能干，也不是每次都稳。让虾帮你修改文档、方案、表格之前，先把原文件复制一份放好——哪怕只是在文件名后面加个「_备份」或者日期。

虾有时候会改过头：删掉你想留的内容、打乱原有的格式、或者越改越偏。等你发现不对劲，原来的版本可能已经覆盖掉了。

真正成熟的用法不是“希望它永远不出错”，而是： 出错也不怕，因为你留了后路。

4.10 用户自动化，让虾自动干活

善用定时任务和自动化工作流，让虾 24 小时运转

WorkBuddy 支持自动化能力，你不必每次都手动触发虾。通过定时任务和自动化工作流，你可以让虾在后台静默地帮你处理那些重复性的日常工作：

⏰ 每天 9:00 自动生成工作日报

🧪 代码提交后自动跑测试

📊 每周汇总数据并生成报告

🔍 定期检查代码规范

📬 定期抓取并整理行业资讯

这才是 AI 助手的终极形态：不需要你每次守着屏幕，它自己就把事情干完了。

⚙️ 哪些工作适合自动化？

重复性高（每天/每周都要做）、规则明确（有固定模板或判断标准）、无需实时人工干预的任务——都是最适合交给虾自动化的场景。

4.11 学会偷懒 + PUA 虾

善用参考、激励 AI，把重复劳动统统外包

这里说的"偷懒"不是摆烂，而是把重复劳动全部交给 AI。格式化代码、写模板、整理数据这些机械性工作？统统丢给虾。

而"PUA 虾"的意思是——适当给 AI 心理暗示和正向激励，往往能让输出质量更上一层楼。别笑，这真的管用。虽然虾没有情绪，但这种「激励」会影响它选择的词语框架和回答的深度。

底层逻辑：你的精力应该花在"做决策"和"创造性思考"上，机械性的执行工作让 AI 代劳。这不是偷懒，是让对的人（和AI）做对的事。

最值得装的 10 个零成本 Skill

如果你刚开始用 OpenClaw，我很建议先从不用额外配付费 API、装完就能体验到价值的 skill 开始。

对大多数小白来说，最烦的不是“不会用 AI”，而是刚装一个 skill，就先被 API Key、计费、各种平台账号劝退了。

现在装 Skill 这件事其实已经很 AI Native 了。最简单的方式，是直接把 skill 链接丢给 AI，让它帮你装。比如你可以直接说：

帮我安装这个 skill（附链接），并把它依赖的东西也一并装好，比如 uv、ffmpeg、node、npm、obsidian-cli 等；如果发现需要付费 API、API Key、模型下载或额外手动配置，请先明确告诉我，不要默认跳过。

这篇文章推荐的 10 个 skill，核心标准只有两个：小白能理解，以及 不依赖额外付费 API。

有些 Skill 还是会需要装本地依赖，比如 uv、ffmpeg、node、npm、obsidian-cli，但这类通常都可以直接让 AI 顺手帮你一起搞定。

5.1 Agent Browser

安装名：agent-browser

仓库：https://github.com/sundial-org/awesome-openclaw-skills/tree/main/skills/agent-browser

网页从来都不是天然对 AI 开放的，尤其是那些必须滚动、点击、展开之后才看得到内容的页面。装上 agent-browser，WorkBuddy 就不再只有一张更聪明的嘴，而是拥有一双能真的去点网页、翻页面、截屏、读内容的手。

这件事的意义比看起来大得多。

以前那种“文本接口拿不到、必须点进去、滚动完、甚至需要先展开内容才能看”的页面，AI 是无能为力的。装上这个 Skill 之后，一些原本不方便直接读取的小红书页面、公众号文章、后台管理页、帮助中心、活动页，终于可以通过浏览器路径被 AI 实际访问和整理。

它解决的不是“搜不到信息”，而是“信息明明在网页里，但 AI 以前碰不到它”。

5.1.1 使用场景

读网页，但页面必须滚动、点击或展开

自动截图某个页面

检查按钮、表单、页面结构

进入网站后抓取指定信息

5.1.2 应用案例

使用Agent Browser打开这个网页链接https://mp.weixin.qq.com/s/PIOh_aXVuNUT27G5UoKCkw，帮我把标题、核心观点、结构和最值得关注的 5 个信息点整理出来。

可以看到 WorkBuddy 正在模拟人类阅读这篇文章

最终给出了非常到位的总结和文档

5.2. 办公文档四件套：PDF / Word / PPT / Excel

仓库：

PDF ｜ DOCX ｜ PPTX ｜ XLSX

大部分人的工作核心，其实就是每天在改文件。

别人发来一个 PDF，你得抽表格；领导丢来一个 Word，你得排版成正式文档；同事给你一个 PPT，你得重做结构；客户甩来一份 Excel，你得清洗数据、补公式、做结果。真正吞时间的，往往就是这些文件格式本身。

对普通用户来说，更顺手的其实是文档四件套：pdf、docx、pptx、xlsx。

更关键的是，这四个 Skill 主要走本地工具链和文档处理库，不会再额外塞进一层新的付费 API。

5.2.1 使用场景

它们最有价值的地方也很直接：遇到什么文件，就用对应的 Skill 处理什么文件。

pdf：抽正文、抽表格、做 OCR、拆分合并、处理表单

docx：生成正式文档、整理结构、补目录、补页码、处理批注和修订

pptx：读取现成幻灯片、总结每页内容、压缩结构、重做 deck

xlsx：清洗表格、补公式、整理列、输出汇总版结果

5.2.2 应用案例

下面直观的来看看这四大 Skill 的能力：

使用PDF / Word / PPT / Excel skill各自创建一个对应格式的文件，我现在需要展示你的办公能力，文件内容你自己添加合适的

5.3. Local Whisper

安装名：local-whisper

仓库：https://github.com/sundial-org/awesome-openclaw-skills/tree/main/skills/local-whisper

中文用户手里其实有大量“沉睡信息”是音频。

会议录音、微信语音、访谈素材、课程回放、播客片段，这些内容不是不重要，而是太难处理。你知道里面有信息，但又不想自己反复听，更不想为了转个文字再去配一堆 API。

local-whisper 好用的地方，是它把语音转文字这件事拉回了本地。模型下载完之后就能离线跑，不需要额外付费 API。对普通用户来说，这意味着“音频终于变成能继续加工的材料”，而不是永远躺在文件夹里。

5.3.1 适合场景

会议录音转文字

访谈素材整理

课程音频提取重点

把语音备忘录变成行动清单

5.3.2 应用案例

帮我把2384e2002bc3666f30b1a252e1dfe679这段中文音频转成文字，再基于转写结果整理成一个概览

5.4. yt-dlp-downloader

安装名：yt-dlp-downloader

仓库：https://github.com/sundial-org/awesome-openclaw-skills/tree/main/skills/yt-dlp-downloader

很多有价值的内容，不在文章里，而在视频里。

问题是视频天然不适合快速处理。你想保留一段 B 站内容、抽出其中的音频、拿到字幕、再让 AI 帮你总结，过去往往得切好几个工具。对普通人来说，这种操作链太长了，最后大概率就是“算了”。

yt-dlp-downloader 把这个链路打通了。它不只是能下载 YouTube，也明确支持 Bilibili 这类中文用户更常接触的平台。于是视频第一次不再只是“看完就过去的东西”，而是能真正进入你的知识流转。

5.4.1 适合场景

下载 B 站或 YouTube 视频

提取音频做二次整理

下载字幕

保存学习素材，交给 AI 做摘要

5.4.2 应用案例

帮我把https://www.bilibili.com/video/BV11MwXzyEtG/?spm_id_from=333.1007.tianma.4-2-12.click&vd_source=0e5a5abd004459fa9fbd8221ab8dfb49这个 B 站视频下载下来，优先保留字幕；然后根据字幕内容，整理成一份 5 点式摘要。

5.5. Web Search

安装名：web-search

仓库：https://github.com/sundial-org/awesome-openclaw-skills/tree/main/skills/web-search

只要问题里带着“最近”“最新”“现在”，单靠模型记忆其实就不够用了——模型的知识库往往在现在的半年到一年前，不会实时同步最新的知识。

web-search 的价值，不只是单纯把“搜索”塞给 AI，而是让 WorkBuddy 从“会说”变成“会先查再说”。这对小白尤其重要，因为很多误判都来自一个最基础的问题：用户以为 AI 给的是最新信息，其实它只是给了一个看起来像最新的信息。

装上这个 Skill 之后，查资料、找链接、看近期动态这件事，就从“靠记忆瞎答”变成“先查证据再整理”。

5.5.1 适合场景

查某个主题的最新资料

找最近的新闻和文章

做一个快速信息收集

先搜一轮，再让 AI 帮你归纳

5.5.2 应用案例

下面是我用 WorkBuddy 实际跑的

帮我搜索最近 30 天关于“AI 浏览器代理”的文章，筛出最值得看的 5 篇，并各用一句话告诉我为什么值得看。

5.6 Obsidian

安装名：obsidian

仓库：https://github.com/sundial-org/awesome-openclaw-skills/tree/main/skills/obsidian

你大概率会有这样一个痛点：明明已经有一套自己的知识库，但 AI 根本进不去，知识库散落在各个文件夹里，没有一个统一的地方，每次都要重新解释背景、重新粘贴资料、重新告诉 AI 你在做什么。

obsidian Skill 的意义，就是让 AI 直接进入你的第二大脑。不是临时帮你写一段话，而是能在你现有的笔记体系里读、写、搜索、整理。

对中文用户来说，这比很多“云端协作型 Skill”更接地气，因为 Obsidian 本身就是一套非常成熟的本地知识管理方式。

5.6.1 适合场景

把聊天内容整理进笔记

给旧笔记补结构

搜索 vault 里的某个主题

把零散记录归并成知识卡片

以后和 WorkBuddy 聊完后也可以让他随手建一个obsidian里的md文件记录刚刚干了什么，方便写日报周报

5.6.2 应用案例

帮我把 WorkBuddy 文件夹下今天新建的文件夹的内容读取一下，然后把每一个文件夹下的内容梳理成一个独立的md放在obsidian文件夹下，在obsidian文件夹下创建一个以今天日期命名的文件夹汇总这些md文件，方便我写日报

可以看到今日工作情况已经被收录成md文件，WorkBuddy 可以直接读取，还可以和后续文件形成知识图谱，实现知识的复利。

5.7. Skill Scanner

安装名：skill-scanner

仓库：https://github.com/sundial-org/awesome-openclaw-skills/tree/main/skills/skill-scanner

Skill 生态越繁荣，越需要一个常识：第三方 Skill 本质上就是别人写的代码。

这一点如果不说透，普通用户很容易被“好像很好用”四个字骗进去。等真的安装了，才发现里面有奇怪的脚本、硬编码路径、可疑依赖，甚至可能带来隐私和安全问题。

skill-scanner 的价值，不在于让 AI 更强，而在于让你别装错东西。它相当于给整个 Skill 生态加了一道安检，尤其适合放在“新手第一批必须知道的 Skill”里。

5.7.1 适合场景

安装某个新 Skill 之前先扫一遍

检查是否存在可疑依赖

排查是否有硬编码私人配置

给自己一个最低限度的安全感

5.7.2 应用案例

你不需要刻意强调使用这个 Skill ，安装后，WorkBuddy会自行调用，并且给出一个审计报告。

比如，下面是安装 websearch 时给出的审计报告，先审计，后安装，安全感满满

5.8. self-improvement

安装名：self-improvement

仓库：https://github.com/sundial-org/awesome-openclaw-skills/tree/main/skills/self-improvement

用龙虾最消耗耐心的体验之一，就是同一个坑反复踩。

今天提醒过一次，明天又忘。刚刚改对的流程，下次又绕回老路。问题不一定出在模型能力，而可能只是因为系统里没有一个“把经验沉淀下来”的机制。

self-improvement 正是在补这一块。它让 AI 能把错误、修正、经验和更优做法记下来，后面再遇到类似任务时，先回顾再动手。

它的价值不是第一分钟最亮眼，但会在第十次任务时拉开差距。

5.8.1 适合场景

记录一次任务失败的原因

沉淀用户纠正过的偏好

总结某类工作的最佳做法

避免 AI 在同样的问题上反复翻车

这个 Skill 同样是装上后无需明文调用，WorkBuddy 会默默记住你的偏好，自己的错误，让自己越来越聪明。

5.8.2 应用案例

例如：新开一个对话，说我是湖北人，不爱吃辣，在另外一个对话中，WorkBuddy 依旧记得我的信息。

5.9. Find Skills

安装名：find-skills

仓库：https://github.com/sundial-org/awesome-openclaw-skills/tree/main/skills/find-skills

Skill 一多，真正拉高门槛的往往就不是安装动作本身，而是选择成本。

生态一大，反而更难开始。你知道自己“好像想让 AI 干某件事”，但你未必知道这件事在 Skill 世界里叫什么。结果就是搜半天、比半天、最后还是没装。

find-skills 像一个 Skill 商店里的懂行导购。你只需要讲需求，它帮你把候选找出来，再解释各自差别。对于刚入门的人来说，这比盲搜靠谱得多。

5.9.1 适合场景

不知道某个需求有没有现成 Skill

想让 AI 先做一轮筛选

快速了解几种候选的区别

避免在 Skill 海洋里瞎逛

5.9.2 应用案例

下面来测试一下这个 skill：

我是一个产品经理，帮我找一些适合我的skill

可以看到 WorkBuddy 成功调用这个 skill ，并且给我推荐了很多我没有安装的 skill

5.10. Frontend Design

安装名：frontend-design

仓库：https://github.com/sundial-org/awesome-openclaw-skills/tree/main/skills/frontend-design

很多 AI 生成的页面，AI 味太重——经典蓝紫渐变，圆角边框，千篇一律。

结构看似完整，细节却都很虚：排版平、配色普通、层次弱、审美没有明确方向。结果就是你明知道它省了时间，但又不愿意真的拿去给别人看。

frontend-design 的价值，不是让 AI 会写 HTML，而是让它在做界面时更像一个有审美判断的人。它帮 WorkBuddy 补上的，其实是“设计感”这一层能力。

如果你的读者里有做产品、做网页、做落地页、做活动页的人，这个 Skill 很容易一试就留下来。

5.10.1 适合场景

做一个落地页或活动页

重做一个老旧后台页面

让 AI 先给出视觉方向

做一个看得过去、能演示的前端页面

5.10.2 应用案例

使用 Fronted design 帮我做一个 WorkBuddy 产品介绍页，要求首屏有强记忆点，整体风格不要像普通模板站，给我一个可以直接预览的前端页面版本。

直接把这段话贴给 AI

> 帮我检查当前 WorkBuddy 工作区里已经安装了哪些 Skills。先安装并使用 skill-scanner，对下面准备安装的 Skills 做一次基础安全扫描；如果发现明显风险、硬编码私人配置、可疑脚本、恶意依赖或高危行为，就先停下来告诉我，不要继续装。
>
> 如果扫描通过，再继续安装下面这些还没有安装的 Skills 到.WorkBuddy下：
> - agent-browser
> - pdf
> - docx
> - pptx
> - xlsx
> - local-whisper
> - yt-dlp-downloader
> - web-search
> - obsidian
> - skill-scanner
> - self-improvement
> - find-skills
> - frontend-design
～>
> 要求：
> 1. 只安装当前还没有安装的 Skills，已经安装的不要重复安装。
> 2. 安装时把每个 Skill 依赖的东西也一并装好，比如 uv、ffmpeg、node、npm、obsidian-cli 等，不要漏掉。
> 3. 每个 Skill 都先读取它自己的 SKILL.md / 安装说明，再决定依赖怎么装。
> 4. 如果某个 Skill 需要付费 API、API Key、模型下载或额外手动配置，请先明确告诉我，不要默认跳过。
> 5. 安装完成后，给我一份清单：已安装、刚安装、额外装了哪些依赖、还有哪些需要我手动配置。

真正好用的 Skill，不是那种看起来最厉害的，而是你装完之后，今天下午就能真的用起来的。

对普通用户来说，第一批 Skill 最重要的不是“能力边界有多高”，而是“能不能马上解决一个真实痛点”。

网页能不能直接读，音频能不能直接转，PDF 能不能直接喂，第三方 Skill 能不能放心装，这些问题一旦被解决，WorkBuddy 才会从一个会聊天的 AI，变成一个真的能替你干活的桌面搭子。如果后面还想继续往深处玩，再去碰 skill-creator 这类进阶 Skill 会更合适。那个阶段，问题就不再是“装什么”，而是“我想把什么能力，真正变成自己的能力”。

常见问题（正在补充中）

6.1 下载安装

6.1.1安装 Mac 版提示安装包已损坏

重启电脑再尝试安装，这是苹果电脑的一个共性bug。

原理为：从 DMG 拖拽到 /Applications 时，Finder 对 .app（实际上是个目录包）的处理是逐文件复制/覆盖（或合并目录），不是一次性原子替换。若某些文件被占用或系统/第三方进程在并发访问，就可能出现新旧文件混合的短暂不一致，触发 codesign/spctl 校验失败，被系统误判为“已损坏”。重启能解决，是因为释放了所有文件句柄并清空了相关缓存/状态。自动更新或者首次下载不会有这个问题的。

6.1.2 卸载旧版本重新安装或覆盖安装会导致数据丢失吗？

不会。重新安装原数据不会影响，但需要注意卸载方式，有的卸载应用会清除部分配置。

6.1.3 安装 Mac 版提示无法写入程序用户数据

（1）前往 /Users 文件夹修改权限为读写，

（2）进行共享与权限配置，将用户名设置为读与写权限。

（3）如以上方法无效，或有技术背景的同学，也可直接打开电脑终端执行命令，执行后重启 WorkBuddy

sudo mkdir -p ~/.WorkBuddy
sudo chown -R $(whoami) ~/.WorkBuddy
sudo chmod 775 ~/.WorkBuddy

6.2 无法登录

6.2.1 点击登录按钮没有反应

首先排查电脑是否设置默认浏览器，使用谷歌浏览器无痕模式登录。

6.3 无法更新

6.3.1 无新版本提示或点击检查更新报错

卸载当前版本，前往官网下载最新版本https://www.codebuddy.cn/work/。

6.4 跨端问题

6.4.1 配置和会话记录支持跨设备同步吗？

配置和会话记录储存在本地，不跟随账号跨设备同步。

6.4.2 在移动端可以 发送/接收 文件吗？

支持在 PC 端对话框发送文件、查看产物。计划推出主动推送文件到移动端对话框的功能。

6.4.3 在移动端可以发送 图片或文件 吗？

当前移动端支持发送文字信息、文件或图片，欢迎搜索腾讯WorkBuddy 小程序获得更好的移动端体验

6.4.4 自定义 Skills 在本地维护后，可以云端调用吗？

支持，可以直接上传到 WorkBuddy 中

6.4.5 支持服务器或容器部署吗？

暂不支持，仅限本地安装.

6.4.6 多端任务处理是分开的吗？

多端任务处理不分开，企微、微信消息可以在同一会话中，多个文件夹任务并行处理是分开的。

6.4.7 支持语音输入吗？

暂不支持，可以使用系统的语音输入暂时代替，该功能在规划中。

6.4.8 企微连接WorkBuddy能指定 对话/工作空间 吗？

暂不支持，建议直接下达指令，该功能在规划中。

6.4.9 PC端在线机制是怎么判定的？如何能在人离开电脑后保持连接？

保持设备开启 WorkBuddy 的同时，联网且未休眠，开启也锁屏不影响连接。

6.4.10 在两台PC上都装了WorkBuddy，但是企微的 WorkBuddy 只能连到其中一台机器上，怎么切换？（多个机器打开了WorkBuddy，微信或者企微对话的时候要怎么指定用哪个机器）

企微连接的是最后一个登录的设备（待确认）。

6.4.11 移动端报错 Local Agent Error: AGENTINVOKABLE CUSTOM MODEL NOT FOUND

建议重试或切换模型。

6.4.12 WorkBuddy 设置自动化任务后，企业微信并未收到相应的推送通知

bot 暂不支持自动推送，后续会支持。

6.5 工作空间

6.5.1 如何指定工作空间？

点击左侧新建任务，在对话框右下角选择文件夹处点击打开下拉框指定工作空间文件夹。

6.5.2 工作空间可以修改命名吗？

暂不支持，但可以修改任务名。

6.5.3 任务与工作空间区别是什么？

任务适用于快速新建项目，默认是用户级别的 Claw 文件夹目录，自动生成独立工作空间；工作空间适用于管理指定项目文件夹。

6.6 用户设置

6.6.1 怎么切换颜色主题 ？

左下角点击头像后在 浅色主题/深色主题 处切换。

6.6.2 怎么切换语言？

左下角点击头像后在 语言 处切换。

6.7 使用问题

6.7.1 Skills无法在对话框中引用怎么办？

进入左侧技能板块打开对应skill后，无需引用，在对话过程中WorkBuddy会自动读取。

6.7.2 如何导出日志？

在上方导航栏点击 帮助 - 打开日志文件夹 可以找到对应日期的日志。

6.7.3 连接不上Figma官方的MCP

Figma官方有限制，可以先试试腾讯设计 Ardot 新品体验 https://d.qq.com。

6.8 积分credits额度 / 计费问题

6.8.1 积分（credits）用量在哪里查看？

点击头像后再点击 积分余额进入看板。

6.8.2 如何提高积分（ Credits）额度

从CodeBuddy 进行采购：点击 https://www.codebuddy.cn/profile/plan 进行下单采购

**接入自有模型 API **

点击配置自定义模型

按照自己采购的模型供应商进行补充API Key 等信息

6.8.3 WorkBuddy的个人版、企业版有独立的收费逻辑么？还是跟CodeBuddy计费逻辑一样？

WorkBuddy账户与CodeCuddy是共用的。

6.9 性能和资源

6.9.1 报错 invoke model error / Cannot connect to APl / Invalid request parameters

模型资源紧张，建议重试或切换其他模型。

6.9.2 WorkBuddy运行时主要消耗哪些资源？

资源消耗以内存和带宽为主，占CPU较低；AI计算消耗在云端。

6.9.3 多任务并行时，是否会拖慢处理速度？

多任务并行时本地文件操作会竞争资源。

6.10 安全相关

6.10.1 系统架构如何保障全链路安全？

WorkBuddy 的做法不是“先运行再补救”，而是先把边界设好。它支持不同权限模式，也有安全中心，可以按需配置黑白名单，先决定哪些操作能做、哪些不能做。运行时又有安全沙箱做隔离，在操作系统层面识别操作意图并拦截高风险动作。简单说，就是先把规则立住，再让 Agent 在规则里工作。

6.10.2 Agent 运行时的安全风险要如何避免？

最常见的风险是有人用精心设计的提示词，诱导 Agent 做违规操作。WorkBuddy 对这件事做了三层防护：入口层先做输入清理和高风险命令拦截；运行层持续做上下文分析、隔离窗口和命令注入检测，敏感操作必须用户明确授权；兜底层用熔断机制在必要时直接中断。第三方 Skill 也不是装了就能用，安装前会先做安全扫描，检测恶意脚本和风险行为，通过后才可启用。再加上文件系统、网络、命令三类隔离，即使被诱导执行危险动作，也能把影响范围尽量压小。

6.10.3 与模型的对话数据会不会泄露？

这个问题重点看三个环节：存储、传输、使用。WorkBuddy 在这三段都有管控，目标是让数据流转可追溯、权限可控制。存储侧按场景提供策略，传输侧使用全链路 TLS 加密，使用侧遵循最小权限原则。另外还有文件删除保护，比如批量删除确认和删除进入回收站，降低 AI 误删导致数据丢失的风险。

6.10.4 如何确保身份认证与凭证安全？

在企业场景中，WorkBuddy 接入腾讯统一身份 OneID，支持 SSO 单点登录和多认证源对接；敏感操作会触发二次认证；权限按角色最小化分配，人员离职后可立即回收权限。个人场景下，OneID 也将逐步接入，基于“一人一 OneID”统一账号体系，支持一次登录多端免登，并做集中授权与风控管理。API 密钥和令牌通过操作系统原生密钥链加密存储，运行时按需调用，用后即销。

完整视频合集

【第一集】

【第二集】

【第三集】

【第四集】

【第五集】

关注「腾讯技术工程」公众号

私信回复「workbuddy」即可收到自动回复详细文档哦

跳转微信打开

AI 时代下，如何做社区内容治理与分发

作者：赵秀雯

导语：AI 时代下，平台如何做内容治理与分发？SkillHub 作为国内最大的 Skill 社区之一，与小红书、知乎、App Store 这些传统内容社区做推广搜有什么不同？SkillHub 是如何帮助用户快速找到那 20% 值得被看见的 Skill 的？本文将通过深度解读 SkillHub 针对这些命题的思考与实践，来逐一为大家解答。

SkillHub 是专为中国用户优化的 AI Skills 社区，自今年 3 月上线以来，跟随 OpenClaw 生态的快速发展获得了广泛关注。作为国内最大的 Skill 社区之一，我们在社群中最常被问到的一个问题是：

平台上那么多 Skill，我怎么知道哪一个真的好用，有推荐的 Skill 吗？

早在3个月前，当时 SkillHub 的数量大概是 5万左右，用户当时已经是挑花眼，不知道哪个 Skill 值得安装。对于一个拥有庞大资产内容的平台来说，供给的数量与供给创造的价值，往往并不均匀。AI 又让这个问题变得更突出。过去，生产本身就有门槛，但在今天，AI 大大降低了用户写作、编码、创作的成本。创作者借助 AI 一句话生成一个 Skill，立马发布到 SkillHub 上，先把 Skill 的唯一标识码抢注了，就跟五百年前抢注域名热潮一样。

就正如咱们常说的二八法则，真正有价值的内容往往只有那 20%。平台快速增长的同时，也迫使我们从早期偏粗放的供给扩充，转向更系统的推荐、分发与治理。在这个过程中，如何处理好消费者、创作者和平台之间的关系，成为 SkillHub 很关键的问题。消费者希望更快找到可信、适合自己的 Skill；创作者希望真正优质的作品能够被公平看见，并获得有效反馈；平台则需要在供给增长、分发效率和社区信任之间保持平衡。

到目前为止，平台已经收录 10 万+个 AI Skills，月下载量超过 1000 万次，数据仍在持续上涨。因此，我想借这篇文章复盘 SkillHub 的经验：在内容快速增长的情况下，作为一个诞生于 AI 时代的 AI Native 社区，SkillHub 如何寻找、验证并放大这部分真正值得被看见的 Skill。

在这个命题上，我们核心做了三件事：

• 建立一套可信的质量坐标；

• 把有限的曝光分给更值得被看见的供给；

• 让这套发现能力不仅服务人，也能被 AI 直接使用，这也是在 AI 时代下，跟传统社区最大的区别。

一、社区的老方法依然有效，SkillHub 还要多回答一道题

在开始分享 SkillHub 的实践前，可以先回到最朴素的问题：对于一般的社区来说，是怎么解决内容治理和分发问题的？那些成熟的社区，在处理海量供给时，通常有以下几种成熟的办法：

第一种，组织供给。通过频道、分类、标签和搜索，把原本平铺的内容放进用户可以理解的结构里。例如豆瓣、知乎。

第二种，分配流量。通过热门榜、新品榜、个性化推荐、编辑精选，把有限的展示位置分配给更可能被消费的内容，回答“先看什么”。例如App Store。

第三种：建立治理门槛。用发布审核、信用认证、举报、降权和下架机制，过滤明显低质或有风险的供给，回答“什么不应该被看见”。例如小红书。

第四种：形成反馈闭环。点击、停留、购买、收藏、评分等行为不断回流，帮助平台判断内容是否真正满足需求，也让创作者知道下一步该优化什么。例如淘宝。

对于 SkillHub 来说，过去这些社区产品方法论，其实依然适用。就像是道路上的交通工具从自行车、燃油车换成了电动车，车变了，但红绿灯、路标、斑马线这些规则依然有效。只是，当我在规划把这套方法搬到 SkillHub 的时候，很快又想到了一个问题：一篇文章被读完、一个商品被购买，平台就能获得相对清晰的消费信号。但 Skill 的真正使用，是用户从 SkillHub 下载安装到 Agent 后才发生的，换句话说，Skill 的反馈其实是有滞后性的。一个 Skill 被点击或下载，不代表它就能成功完成任务。

所以对于 SkillHub 来说，分类、榜单和行为数据仍然重要，但还不够，在讨论“如何推荐”之前，我们必须先补上一层普通社区很少需要深入处理的能力：这个 Skill 到底好不好，依据是什么。

二、先建立质量坐标：TRACE 回答“什么是好的 Skill”

如果把 Skill 类比成代码，那么审核 Skill 就很像是在做 Code Review。

最开始面临怎么判断上架后的 Skill 是否值得被推荐这个问题时，我们想到了两个问题，一是如果没有统一的标准，判断容易因人而异，二是平台里越来越多内容供给，如何支撑数万量级的内容持续评估也是值得被考虑的因素。

TRACE 评测体系的起点，就是来自这里：把“这个 Skill 好不好，是否值得信赖”从一种模糊感受，变成可确认可解释的质量坐标。设计这套体系时，一方面我们参考了业内例如 Anthropic 发布的 Skill 规范标准，另一方面，更多是我们对用户痛点的洞察以及对 SkillHub 的定位与思考。

在一开始 SkillHub 出生的时候，当时国内还没有比较成规模的 Skill 社区。而我所在的团队 —— 腾讯轻量云，在今年1月的时候就适配了 OpenClaw 龙虾的云端部署并推出市场，而到3月我们在深圳腾大楼下举办一场公益装机活动，又让龙虾彻底火到了老奶奶人群。当时整个 Agent 和 Skill 生态，还是以国外为主，大家首选还是 ClawHub。但这里就有出现的非常明显的问题：海外的 Skill，未必在国内适用，它可能会存在内容合规性、安全风险以及海外产品/ API 在国内无法调用等问题。

因此，首要需要先检测这个 Skill，是否安全、是否适配国内环境，我们也把 Trust 放在了整个测评体系的首要位置。这也是体现了 SkillHub 的核心定位 —— 专为中国用户优化的 AI Skills 社区。

在整个 Trace 体系制定中，我和开发也反复打磨了很多个版本。Skill 要说简单也简单，它无非就是封装了一些场景使用定义规范、产品 API 的纯文本文档。但是在使用过程中，其实还有很多问题是用户关心或者在选择的时候没有考虑到的，这里就需要作为平台方的我们，帮助用户提前判断，加速筛选：是否没有把渐进式披露考虑进去，导致让用户消耗 token 过大；用户在 Agent 中使用 Skill 的时候，往往自然语言 prompt 过于发散，Skill 是否能正确识别到用户的意图，并处理好能力边界......这些都是用户的硬痛点。

基于此，我们做了 TRACE 评测体系，把一个模糊的问题拆成五个独立的观测维度，来给每个 Skill 进行评测打分：

TRACE 维度	评测子维度	主要回答的问题
Trust（可信任度）	国内适配性、安全性扫描	关注元数据真实性、声明与实现的一致性、来源可信度以及安全边界。
Reliability（可靠性）	异常处理、功能完整性、运行稳定性	检查依赖完整性、异常处理、重试机制、超时表现和实现缺陷。
Adaptability（适用性）	能力边界定义、触发方式	评估参数兼容、异常路径、版本差异、环境容忍度与边界条件处理能力。
Convention（规范性）	反模式与 FAQ、文档质量、渐进式披露、结构清晰	检查文档结构、参数 Schema、目录命名和依赖声明是否符合工程规范。
Effectiveness（有效性）	输出准确性、内容完整度、创造力与增值、开箱即用度	判断产物是否正确、是否符合用户意图，以及 Skill 能否真正完成目标任务。

有了这份评测体系后，接下来的问题是：怎样能让平台里数万个 Skill 快速、稳定地经过这套检查呢？在这里，我们重点又建设了以下的基础设施。

2.1 从单体串行，走向五路并行

传统评测流程通常由单个 Agent 依次完成五个维度。流程容易理解，但每增加一个维度，都意味着更长的等待时间。当平台需要处理大规模 Skill 集合时，串行架构会迅速成为吞吐瓶颈。创作者肯定是希望上传 Skill 后能第一时间发布出去，而平台又希望 Skill 发布前就能够通过 TRACE 评测给 Skill 打分审核，因此，评测的用时就成为了首先要解决的问题。

我们后来把 T、R、A、C、E 拆成五条并行链路：它们共享同一份 Skill 上下文，各自完成判断，再统一做结构校验、冲突处理和结果汇总。在典型场景中，评测目标耗时由约 10 分钟缩短到约 1 分钟。每个维度也可以独立扩容和优化，新增规则时无需推翻整套体系。

2.2 内存级加载，让 Agent 专注于理解 Skill

评测的另一个技术问题是：Agent 到底应该怎样读取一个 Skill。

如果五路评测各自解压、读取文件，就像五位检查员各拿一份复印件：速度慢，还可能出现版本不一致。我们将 Skill 包一次加载到内存，再通过 list_files、read_file 等受控工具按需读取。

这样既减少重复操作，也保证五个维度看到同一份内容；读取范围被限制在当前 Skill 包内，评测系统自身同样遵守安全边界。

2.3 给每次评测一张可追踪的“工单”

一次模型调用可以生成报告，却无法支撑持续运营。新版本需要自动复评，失败任务需要重试，异常结果还要进入人工处理。我们因此把链路拆成“发现—入队—调度—评测—审核—落库”：每个 Skill 都有自己的评测任务和状态，任何一步失败都能被记录、恢复和追踪。这让 TRACE 从一次性的 AI 判断，变成了可以长期运行的质量生产系统。

目前，我们基于 Trace 测评能力，对 SkillHub 上数万个 Skill 进行了逐一扫描，并为每个 Skill 生成简要评测报告，帮助用户快速筛选和甄别优质 Skill。

同时，我们还为创作者提供了更加详细的评测报告，并集成到创作者后台。创作者可以清晰了解 Skill 的整体表现，以及在各项细分维度上的具体得分和优化建议，从而有针对性地迭代和提升 Skill 质量。

这一机制不仅帮助创作者持续优化作品，也让平台能够沉淀更多高质量 Skill，最终实现消费者、创作者与平台三方共赢。

三、TRACE 看“体检报告”，但如何测试 Skill 是否真能干？

在前面的 TRACE 评测中，我们主要通过静态分析判断一个 Skill 是否可信，但它只能告诉我们 Skill“写了什么”，不能完全证明它“运行时会做什么”：

• 安装脚本无法执行，或者依赖版本不兼容；

• 说明文档声称支持某项能力，但 Agent 实际不知道如何调用；

• 可以生成结果，但结果并没有真正解决问题；

......

所以，我们又搭建了一座“封闭试车场”——云端隔离运行环境。开发者可以直接在 SkillHub 中试跑 Skill，观察 Skill 在 Agent 里运行的效果是怎么样的，并且支持把有代表性的运行沉淀为详情页上的效果案例。

开发者可以在 SkillHub 中直接试跑 Skill，并观察真实对话和执行结果

3.1 一次试运行，实际经过了什么

云端隔离运行环境会解析目标版本，把 Skill 文件装进隔离 Workspace，再让 Agent 读取 SKILL.md，按说明调用脚本、资料和工具。只有环境返回 ready 信号，任务才会开始。这样可以排除一种常见的“假运行”：模型知道 Skill 的名字，也能生成一段像样的回答，实际并没有加载和使用它。

涉及文件读写、依赖安装和终端命令的操作，会进入独立工作区执行。平台业务服务与不可信代码彼此隔离，任务结束后还要完成清理和校验，才能安全复用环境。复杂的隔离设计最终只为一个简单目标服务：用户看到的结果，确实来自这个 Skill 的真实执行。

3.2 再让用户看懂过程，断开后也能接着跑

Agent 执行任务会经历分析、读取文件、调用工具、生成答案等多个阶段。我们把底层事件整理成用户能看懂的执行轨迹：现在做到哪一步、工具是否成功、任务正常完成还是意外中断。用户因此可以判断结果怎样产生，也能快速定位问题。

真实会话还会遇到网络中断、服务切换和环境重启。平台会保存消息、文件和关键运行状态，在条件允许时恢复原来的任务现场。这里最重要的判断很朴素：聊天记录还在，不代表运行环境还活着；页面显示“可继续”时，Workspace 和执行权限必须真的已经恢复。

3.3 针对运行环境的结果，我们沉淀了“展示案例”

目前我们计划把云端隔离运行环境的能力开放给开发者。一方面开发者上传 Skill 后，可以在平台内直接验证其 Skill 在真实环境中的运行效果，另一方面，我们也提供在运行环境中生成展示案例的能力，供消费者快速了解其 Skill 如何使用。

因此，SkillHub 把会话和公开案例设计成两个不同对象。运行环境会话是实时的、可继续执行的，包含完整上下文和运行状态；效果案例则是用户从一次真实会话中挑选出的消息与文件快照。

在前端，Skill 作者可以与 Agent 进行多轮对话，观察思考过程和工具调用，然后进入选择模式，挑选最能说明效果的回答，填写案例标题和补充说明，生成案例。

作者可以从真实的运行环境中挑选代表性问答，沉淀为 Skill 详情页可展示的效果案例

TRACE、云端隔离运行环境和效果案例，分别解决了三个不同层面的问题：

层次	回答的问题	形成的证据
TRACE 测评	这个 Skill 看起来是否可信、规范、可理解	结构、依赖、说明和静态扫描结果
云端隔离运行环境	这个 Skill 在真实环境里是否能够被 Agent 正确使用	执行轨迹、工具调用、工作区变化和最终结果
效果案例	这次成功运行是否值得被其他用户看见和复用	经筛选、审核并持久化的真实会话快照

四、有了质量底座，接下来如何让更多优质 Skill 获得曝光？

大多数内容社区都会使用点击、收藏、下载等行为做排序。这些能一定程度上反馈了内容的受欢迎程度，毕竟都是用户真实用脚在投票。但也正如前文所说的，SkillHub 跟普通内容社区不同的是，用户来这里不但只是为了看内容，他们的核心诉求是把一个 Skill 里面定义的一坨能力，能装进 Agent 中，完成真实任务。因此，在做榜单的过程中，我们不但挖掘用户的行为数据，还结合了 TRACE 测评等维度，生成最终的榜单数据：

榜单	想解决的问题
推荐榜	找到近期质量和数据都相对稳定的 Skill
飙升榜	捕捉时效性更强的新趋势
下载榜	保留最直观的长期热度入口
最新榜	给新品机会，同时过滤明显噪音

具体执行时，长期霸榜的“装机必备”类 Skill 已经能在下载榜充分体现长期热度，因此我们在榜单设计时，在推荐榜和飙升榜中适度降权，为近期优质供给腾出空间。最终，人工运营也始终存在，新品需要冷启动，垂直内容需要被“捞取”，热点需要专题承接，头部固化需要认为校准。规则、算法和运营共同把海量的供给，压缩成用户可以做选择的有限集合。

专题案例：与微信团队合作的微信小程序 AI 开发专区

如果说榜单像实时路况，标签更像是地图

刚开始做标签调研时，我看到几乎所有同类产品都有分类。就正如正文开头提到的这是社区常规手段之一，“别人有，我们也做一个”，但更深一步你就会去想：在 SkillHub，标签究竟要解决谁的什么问题？

标签分类就更像是地图一样，把庞大的 Skill 世界划分成可理解的区域。我们一开始没有把标签做成一组任意扩张的词，反而是建立受控、分层的分类体系：

• 12 个一级主分类，回答“我该去哪里逛”；

• 每个 Skill 归属 1 个一级分类、1 至 3 个二级类目，回答“它具体能做什么”；

• 行业类目回答“它适合哪个行业”；

• “需要 API Key”等系统标签回答“我能不能直接用”；

这套体系也是经过了对 SkillHub 的用户洞察， 它从中文用户的任务语言出发，同时兼顾治理和运营。一级分类保持克制，避免导航无限膨胀；二级类目提供精度；运营标签不与长期分类混在一起；存量 Skill 先由系统自动打标，再逐步开放作者校正和后台治理。后续，我们也计划把社区内的搜索做成支持智能语言搜索，用 AI 解决用户使用 AI 的问题。

我们也看到了有一些 Skill 社区，没有制定统一的分类标签体系，而是让 AI 自己去做语义理解进行自动打标签。在效率优先的年代，这似乎是一个不错的解法，快速上线需求，无需思考设计。但在我看来，起码说在竞品的结果呈现上来看：平台的 Skill 就很多，标签体系又随意任意打，有一些标签我甚至不能理解为何也能成为标签，最终呈现结果上看，不但没有提高用户筛选合适 Skill 的效率，反而增加了用户的理解成本。

克制一点，由平台来统一定义标签体系，标签分类不宜过多。现在，SkillHub已经可以按推荐、飙升、下载、最近上新等方式浏览，并结合来源、场景分类、是否需要 API Key 等条件筛选；详情页也会展示一级分类和二级类目。榜单、搜索、专题合集、大赛和后续的 Agent 检索，都开始说同一种“语言”。

五、对人友好后，还要让 AI 找到 Skill

Skill 面向的对象是谁？如果帮用户找 Skill 的，不再是用户自己，而是 Agent 呢？在实际场景中，用户不但会到 SkillHub 站点里浏览、搜索 Skill，更会在 Agent 中直接让 AI 推荐发现 Skill。

目前最受海外大众认可的 Skill 开源平台—— skills.sh，它有一个帮助用户发现合适 Skill 的「find skill」。它的逻辑很清晰：先理解任务和领域，优先查看热门榜单，再通过 CLI 关键词搜索；推荐前重点检查安装量、来源声誉和 GitHub star，最后向用户给出候选与安装方式。skills.sh 的搜索接口也会对单词使用模糊匹配、对多词查询使用语义搜索，榜单则主要依赖安装数据。

这个方法适合以 GitHub 和开发者生态为中心的供给。但回到 SkillHub，我们面对的是大量中文自然语言需求、跨场景任务，以及已经建立起来的分类、评测和来源体系。因此我们没有只复制一个“搜索命令”，而是把一套中文 Skill 发现策略封装成了自己的find skill：

1. 先从用户原话中抽取任务意图、领域分类和中英文候选词；

2. 对同义词、上位词做 2 至 4 组扩展，而不是只搜索一次原句；

3. 多次调用 SkillHub 列表接口，必要时叠加一级分类和属性标签，合并后按 slug（每个 Skill 的唯一标识） 去重；

4. 根据名称、中文描述和任务契合度重新排序，同一档位再参考下载和安装热度；

5. 只保留最合适的 3 至 5 个结果，说明匹配理由；用户确认后，再进入安装。

例如，“帮我自动写周报发给老板”不会只被当成一串关键词。Agent 会先把它理解为“办公效率”场景，再扩展“周报、工作汇报、日报、weekly report”等候选词。如果分类内结果太多，就继续收窄；如果没有结果，就去掉分类限制，换同义词和上位词放宽召回。

这也是 SkillHub 与一般 Skill 目录差异化的一点。目录解决收录，市场解决交易，社区解决互动；而一个面向 Agent 的 SkillHub，最终还要成为机器可以理解和调用的能力索引。SkillHub 的 find skill 上线后，在没有任何推广的情况下，3天即登上了飙升榜第一，一周即破了 8000 安装量。

在 Agent 中使用 find skill 来推荐相关技能

结语：如何找到那 20% 值得被看见的 Skill

回头看，我们做 TRACE、Skill 试运行、榜单、标签和 find skill，表面上是五项不同的产品能力，底层其实围绕同一件事：

在供给极度丰富之后，如何让用户更高效地找到平台中那些值得被看见的 Skill

用户需要降低试错成本，作者需要获得与质量相匹配的曝光，平台需要避免劣币驱逐良币，Agent 则需要把模糊任务稳定地映射到可执行能力。因此，我把 SkillHub 的推荐工作理解成一套“信任与分发基础设施”：

• 评测和试运行建立证据；

• 榜单和标签组织供给；

• 搜索与推荐分配注意力；

• find skill 把这套能力开放给 AI；

• 最终的真实调用结果，再回到评测和排序中。

这套体系目前也还在建设当中。评测还要持续适应新的 Agent 形态，Skill 还要补齐更完整的产物验证，标签也会随着真实需求继续迭代，创作者也需要更多曝光和激励，去支持平台做得更完善。但至少有一个方向已经越来越清楚：当 Skill 从几百个增长到几万个，平台不能只是证明“这里什么都有”，帮助用户和 Agent 更快确认找到优质的合适的 Skill，反而显得更关键，也直接影响了平台对用户的价值。这或许是 SkillHub 做内容治理与分发最重要的产品观。

欢迎前往官网体验：

https://skillhub.cn/

跳转微信打开

将真实债务项目重构成 AI 可维护项目

作者：被删

AI 时代赋予 AI 的新角色：AI 铲屎官。

在 AI 很强的现在，依然很多人会认为，AI 更适用于新项目快速迭代，但很难在一个背负着沉重的历史包袱的项目中起到很大的用处。

最近大半年都在重构项目，从前期使用 AI 依然困难重重，到如今 AI 能高效定位问题、给到十分贴合项目需要的解决方案，中间特别明显的一个转折点，在于开始给项目搭建 AI 上下文工程。

当然，这一年来 AI 的能力本身也在不断加强，我们项目的质量和架构的合理性在我的努力重构下也在稳步提升，但 AI 上下文的搭建依然起到了十分关键的作用。

今天给大家分享的，主要是如何在重构过程中，将 AI 总是胡言乱语，变成了 AI 也可高效助力的一个项目。

思考：AI 提效到底是在提效什么？

在过去的一年里，AI 的能力有大幅度的提升，从最初只能做点明确的小任务，到如今能协助排查问题、提出可落地的解决方案、自执行落地和自测等等，在我们工作中参与的幅度越来越大。

如今很多新业务直接是 AI 原生项目，意味着从立项到上线，开发未亲自写过一行代码，基本上都是 AI 自行完成的。

但即使在 AI 能力很强的今天，大家还是有些共识，比如一个历史债务很重的项目中，AI 能发挥的作用很少，还是需要开发的介入更多。

这很大一部分原因是：AI 的上下文知识不够。

业务瓶颈常在上下文

其实 AI 和开发并没有太大的区别，很多时候区别只是在于，我们比 AI 拥有更多的上下文，这些上下文包括：

1. 业务的历史背景，项目的整体协作方式（与其他模块的关系等）。

2. 过去的需求文档、技术文档，可能存在其他地方或者是开发和产品的脑袋中。

3. 项目真实运行情况，哪些分支代码上的功能还在跑的、哪些只是历史兼容但不会运行到的。

4. 架构设计和技术债务情况，哪些技术改造只做了一半，未改造彻底等。

这些问题，不管是 AI 还是新加入业务的开发来说，都会遇到，而我们过往经常做的定规范、写文档、做通用化/平台化方案等很多工作内容，都是为了降低对接和沟通成本。

现在我们很多人都会让 AI 写代码，开发成本大大降低了，如今困扰我们的往往是沟通协作成本。人和人之间如此，人和 AI 之间也是如此。

重构成为 AI 可维护项目

回到话题，我们常说的 AI 提效，到底是指什么？

在过去这一年中 AI 已经逐渐参与到很多业务中，十分肯定的是它能提效我们的开发过程，但 AI 还能做更多，包括排查问题、系统现状分析、技术方案设计和落地、代码 Review 等等。如今很多人也已经在尝试让 AI 参与更多，但大多数依然仅限于 AI 原生的新业务。

旧业务和新业务，其实区别便在于 AI 的上下文是否充分。对于历史债务多、维护成本高的项目来说，其实正适合带着 AI 进行重构，重构的过程中给 AI 逐渐补充足量的上下文信息，这样重构后我们就能得到一个 AI 可维护的项目。

过去我们重构，原因无非是架构设计已无法支持业务迭代、技术债务过重需要专项治理、来新人了大家都按自己的想法重做一遍。

如今我们重构，除了治理项目中的既有问题，更是给 AI 添加足够的上下文信息，使得 AI 能参与到日常排障、功能迭代、架构优化中，让开发从日常的高成本维护和反复沟通协作中减负，达到真正的项目提效。

AI 上下文内容建设

我从去年年底就开始治理我们项目的技术债务，今年刚开始的时候，AI 能力已经很强了，但依然经常会判断出错。

判断不准确的原因除了架构过度设计、同时设计的方案落地过程变了形之外，还有很多并没有真实在运行的代码。这些代码是否真的运行，不管是开发还是 AI 都无法通过相关引用判断，因为代码有真实的引用，但在真实运行时可能某个链路却彻底不会运行到。

这些上下文除了 AI 无非获取，很多时候开发自己也无法获取。

过去很长的工程项目中，上下文信息的维护也常常是业务痛点。团队知识的建设很重要，但是无法体现价值，因此往往因为性价比等各种原因，几乎没有团队能将团队知识建设得很好，甚至很多技术强的团队反而崇拜“自己看代码解决”的协助方式。

开发都不爱写文档，也不爱看文档，每个细节和协作内容都存在各自的脑袋中。信息的不对齐、遗漏导致协作过程中的变形，架构设计、技术方案也常常很难坚定不移地完整落地。

我们过去推崇的功能组件化、平台化、通用化，目标都是为了减少开发和维护成本，因为约束了大家认可的规范和协议，这些规范和协议便是我们协作中的上下文信息。

和 AI 协作也是如此，并且在开发成本已被 AI 大大降低的今天，业务开发的效率往往卡在人与人、人与 AI 的协作中。建设团队文档和知识，是为了减少人与人之间的协作，那么建设 AI 上下文工程，便是为了：同样的事情，应该只需要跟 AI 强调一遍即可。

从 AGENTS.md 开始

AI 的上下文知识沉淀，最简单的方式便是从静态上下文开始，这便是跟着代码仓库走的AGENTS.md。

当然，AI 上下文也是有限的，因此我们需要将项目的信息拆分领域放在对应的位置，只保留最重要的内容放置在项目根目录的AGENTS.md中，比如：

# 知识索引
此处描述各个领域的知识需要去哪里找，比如
- 业务背景知识
- 架构信息&技术方案沉淀
- 通用组件&规范
- 三方的对接系统信息
- 其他业务规范等
## 要求
- AI 代提交代码时，commit message 必须以 `| pub` 结尾（这条为我们项目仓库规范）
### 知识落盘规范
- 根目录 AGENTS.md 和 CLAUDE.md 只保留索引概要（路径 + 1~2 句摘要），不在此堆细节。
- 当对话中出现可复用的规则/兼容性/排障结论/项目知识时，必须就近落盘到对应模块 `AGENTS.md`，并同步更新根目录 AGENTS.md 和 CLAUDE.md 中的知识索引（以模块内容为准）。
- 当发现知识索引出现内容过期或不准确时，主动修改

新建一个根目录的AGENTS.md，是一个简单的开始（此处感谢 yuankai 同学的积极分享）。

带着 AI 一起重构业务

即使在 AI 能力超强的现在，依然有无数的业务不会选择进行重构。“代码还能跑就不要动”，这样的历史教训还在深刻影响着不少人。

这对一个停止迭代需求的业务来说，或许问题不大。但如果项目还在快速迭代，将项目重构成一个 AI 项目，在不远的未来可以逐步放手交由 AI 去做更多的事情。

先简单介绍下我们的小程序教育平台，该平台可以理解为一个面向教育场景的“项目创作 + 课程教学 + 小程序体验/发布”平台。它是围绕教育内容生产、学习过程、项目开发、作品体验和发布管理串起来的一整套系统，核心功能包括：

• 自由创作/AI Coding：小程序编程/编译/预览/发布、AI 编程

• 课程学习/课程制作：项目式课程的学习、制作、能力配置，包括小程序预览、富文本编辑知识面板、代码编辑器、AI 对话、答题等各种内容板块

• 资源管理：学校/班级/学生账号、小程序管理、云开发/混元资源等

自由创作（代码编辑+小程序预览+AI对话+代码版本管理+素材库资源管理）

系统的复杂度拆分为两部份：

1. 前端 WEB 本身的复杂度。除了业务需求上的复杂交互设计（比如课程学习/自由创作/课程制作等复杂板块需要支持宽窄屏+拖拽调整+动画效果），还有需求迭代导致的功能高度耦合（比如多个复杂交互页面逻辑均耦合在一起用 if/else 隔离），以及部份过度设计的技术实现（比如代码编辑器设计支持 OT 协同导致复杂度提升不少）。

2. 项目中还涉及到 WEB 外的其他模块。除了常见的后端模块外，还包括模拟器预览的代码编译模块、项目管理和代码拉取等 Node 模块、AI Agent 模块、付费能力模块，以及三方的能力比如腾讯云、混元等。

对于最复杂的自由创作/课程学习/课程制作页面，近半年的重构对比（AI 分析画的图）：

我们目标是 AI 也能在这种复杂度中有效运作，那么可以带着 AI 把这里的链路和设计一起重构。

AI 怎么知道要怎么做，那当然是我们怎么做，它就怎么做。AI 自行读代码理解依然可能不准确，前期会需要不少引导的工作。

一、移除项目中不再起作用的代码

对于债务较多的业务来说，最混淆视听的无非是设计了许多并没有真正起作用的功能代码，比如我们项目：

• 纯 WEB 项目，但因为复制粘贴旧的客户端兼容代码改造，遗留了大量的环境判断 if/else 代码

• 代码编辑设计了 OT 协同，但由于各种原因最终落地时只是纯 HTTP 请求同步代码，并没有用到协同

• 项目曾经尝试调整为 WebIDE 的架构，最终没有落地，但模块间保留了 N 种不一致的消息通信方式

• AI Agent 功能曾经在 WEB 端实现，如今迁移到了单独的 Node 模块，但前端新旧链路耦合严重，难以分辨哪些代码还在生效

这些遗留的问题不仅对开发来说很吃力，对 AI 来说也很吃力，因为它无法通过单纯的代码是否有引用来判断代码是否还真实有效，有些判断条件甚至写到了环境变量中，即使是同个项目的开发也很难辨认。

但我们在梳理治理这些债务的过程中，可以同时借助 AI 来快速辨别完全无引用的代码，再结合项目真实运行情况和从同事那问来的背景情况，和 AI 一起治理重构这些代码，同时让 AI 记录沉淀下来。

屎山清理第一步：让代码跑起来和看上去一致。

二、做减法，复杂架构简单化

其实大多数的业务里，不需要多高的复杂度。但是实际在开发过程中，过度设计的业务比比皆是。而真正让人害怕的是，过度设计之后并不能改造彻底，更可怕的是，项目在经历几轮重构不彻底之后，落下了许多的历史包袱了。

随着参与的项目数量越多，我越来越能理解这件事：架构设计之所以重要，不是因为它看起来高级，而是因为它能把复杂度压下来。

举个例子，上面提到了我们业务实现了 OT 协同编辑代码，但实际上业务场景里并没有协同的诉求，在可见的未来中也不存在类似的需求。

这是一个过度设计的经典案例，为了追求复杂度而增加复杂度，这种其实在我们很多项目中都比较常见，毕竟做复杂比做简单更能体现价值。虽不赞同，但可理解。

我们总在设计的时候过度考虑未来业务的拓展性，但是实践下来结果往往是业务变化总是跟想象的不大一样。好的架构必然是立足于现在，随着业务变动而调整的。

在代码编辑协同这个案例中，分成了两次重构，分别是：

重构步骤	核心重构点	AI 角色	AI 表现
第一次重构	下线 ot 和 websocket，改用 http 提交更新 + 定时拉取	辅助方案优化 + 执行落地	常常判断不准确，需要引导
第二次重构	下线定期拉取逻辑，保留 http 提交代码 + AI 更新代码后推送拉取	主导方案  + 执行落地	大多数情况下分析准确，偶尔需要引导

由于在第一次重构过程中，给 AI 引导添加了不少的上下文信息，在第二次重构过程中 AI 主导的方案整体上比较清晰，判断也基本准确，落地效果也很不错。

屎山清理第二步：将复杂问题简单化。

三、定规范，给项目设置约束边界

真正让一个项目难以维护的，往往不是业务本身有多难，而是缺少约束的规范和边界、以及长时间的持续收敛。

我们项目页面很多，交互也复杂，尤其是高复杂度的自由创作页面和课程制作页面，宽窄屏适配+各板块拖拽+板块出现/隐藏动画效果+国际化支持。

除了业务在快速迭代，开发的架构也在迭代以外，我们设计稿其实也在不断地调整，会出现同样的内容在不同时期的设计稿上不一致等问题，使得项目各个页面看起来问题很多。当然，这里也有不少是开发过程导致样式反复改坏的问题，后面会在自动化测试中统一阐述。

但样式设计是一个比较典型的问题，解决方法也很简单：拉齐设计同学，一起定下项目整体上的规范，包括：页面布局规范（标题&内容&间距）、宽窄屏适配规范、统一组件规范（弹窗&表格&按钮等）、页面滚动规范等等。

样式规范的落地，使用了两种方案的组合：

1. 建设统一组件，将过往设计稿中不符合规范的统一收纳处理。

2. 建设规范沉淀，让 AI 自行检查是否遵循规范，并在 MR 过程中进行规则检测。

规范有了，才能在后续长期的迭代过程中，持续地治理和遵循。

屎山清理第三步：让事情的执行有所依据。

四、定标准，建设自动化测试工程

显而易见，未来越来越多的需求会使用 AI 开发，需求开发、架构改造、问题修复过程中，难以快速判断是否有其他功能受到影响。因此，自动化测试的工程建设势在必行。

在过去，前端之所以很少使用大量的测试用例覆盖，因为前端的变化十分快，用例的维护成本很高。

但如今我们有 AI 了，自动化测试的开发工作量已经大幅度下降。在 AI 的协助下，测试用例维护成本仅剩下了 AI 上下文的维护、token 的成本。

单测/E2E用例覆盖 + MR 流水线回归

用例的搭建和完善并不是一次能达成的目标，需要持续的建设，因此我也拆了好几期进行：

搭建步骤	核心改造点	AI 角色	AI 表现
第一期	搭建项目自动化测试能力（包括单测和 E2E）	主导方案 + 执行落地	需要配合告诉 AI 预期进行调整
第二期	搭建 MR 回归流水线（包括单测和 E2E） + 流水线镜像	辅导方案 + 执行落地	需要提供蓝盾流水线、司内 docker 构建等上下文，配合 AI 调整实现
第三期	梳理和补充测试用例（拆分 P0/P1/P2）	根据上下文整理用例，拆分核心用例和非核心用例	需要提供过往已有用例辅助分析，引导和调整核心/非核心边界
第四期	梳理和补充复杂链路测试用例	辅助分析 + 执行落地	需要提供复杂链路上下文，引导分析建立用例

单测核心用于简单功能的测试，都是基于 Mock 数据建设。E2E 则涉及到多页面的链路加载和交互，不少功能会使用线上真实连续运行。真实环境的执行需要配合提供测试账号，也需要在测试完成后进行数据的治理，比如测试过程产生了很多的新建空项目，需要移除，否则测试账号很快便会触碰上限。

这部分的工作，陆陆续续大概花了一两个月。改造前后有特别明显的变化，最大的改善便是：过去每次发布前，我都需要自行回归核心的功能点，尤其是场景不一样但是功能高度耦合的 自由创作/课程学习/课程制作 这几个板块的页面。

当然，在方案上线并开始运行的一段时间，也是会人工辅助验证，确认用例覆盖是否足够和有效。现在基本上不再需要人工测试，从去年的每次发版必出核心链路的问题，到近几个月的发版基本很少用户反馈了，而我们的用户量其实是在持续上涨的。

视觉用例回归建设

去年的时候，项目整体上还处在焦头烂额地排查问题/修复问题、治理历史债务、快速迭代新需求的阶段，样式问题的治理基本上只能 case by case 解决。

今年上半年把大部分债务治理完成后，单测和 E2E 用例能力覆盖稳定了，样式问题便开始出现在我们视野范围中了。

其实前面在“定规范”的部分，也阐述了样式问题的治理方案，但依然无法解决一个问题：样式在不知不觉中会被改坏。样式被改坏的原因很多，包括改动统一组件、自测走查不仔细、AI 改动不确定边界等等，这里不仅对开发来说产生不少的反复开发工作量，对设计同学来说更是需要反复走查提问题的炸裂存在。

基于项目已经搭建好了整体的自动化测试框架，新增视觉用例的流水线便不再痛苦。基于针对项目定制的 Docker 流水线环境，新增一条视觉回归的流水线，并将视觉回归的产物跟随着代码仓库走。

当然，视觉回归并不是一张大的截图就能解决所有样式问题，考虑到流水线稳定性情况，是要给每个视觉用例的像素偏差定个范围值的。因此，视觉回归的整体解决方案会是：

1. 大的截图用于检测大的布局异常问题，像素偏差允许范围会比较高，识别不了小问题（文字、圆角等问题）。

2. 各个组件拆出小的视觉用例，补充各种状态下的样式回归，像素偏差会限制比较严格，用于发现精确问题。

这样的好处是，即使开发过程未能准确判断测试用例的异常是否符合预期，让 AI 误动了其他的样式来让流水线通过，我们也能直接在 MR 过程中发现。

下图便是发现流水线异常，AI 在修复过程中把样式改动到了，在 MR 的时候就可以明显发现：

MR 自定义规则

除了流水线确保已有功能没有改坏以外，我们还需要确保新增的功能是否都能按照定下的规范来执行。为此，我们需要一个在 MR 流水线中进行 AI 评审的能力。

这部分原本以为要自己建设，正好看到工蜂有类似的能力，便试用上了。操作也很简单，在项目中添加 AI 评审的规则，然后在工蜂中选择该规则文件给到 AI，如图：

当然，这个能力刚补充上线，目前还在实践中，还没有运行足够的时间去验证可行性和效果。

至此，我们的每次 MR 合入时，都需要通过以下流水线：

屎山清理第四步：避免问题反复出现。

五、将债务治理常态化

前面也提到过，债务的产生，很多时候来自于重构和方案落地的不够彻底，一次次遗留的问题，久而久之便成了债务。

这些问题在很多历史项目中我们都能看到，因为几乎所有项目都会存在这样的问题：

• 架构设计跟不上业务迭代，变成了技术债务

• 技术重构没有执行彻底，产生了新的技术债务

• 项目反复迭代&改造，新旧债务层层叠加

在过去，我看过的所有真实在跑的项目都没能彻底完成技术改造，很多时候大家都兴致冲冲起了个头，后续因为业务方向调整、业务需求挤压、性价比下降等各种原因未能改造彻底，总是留下不少的尾巴。

这个问题，在 AI 加入之后，我们可以得到更好地解决：将周期集中的技术专项改造，变成日常开发的常规化改造。

解决方案也很简单，无非是通过前面的“定规范”，补充持续的治理方向，在后续迭代的过程中，AI 会遵循新规范顺手治理历史问题。同时，通过 MR review 时定下的 AI 评审，来检测是否有新增问题。

屎山清理第五步：每天做一点，事情更长久。

结束语

本来想用 AI 回顾我们代码仓库近半年的演化总结文章，看了下，言之凿凿，食而无味。罢了，还是手写有味道。

AI 能做的事情越来越多了，我们干涉的越来越少了。什么时候能完全放手呢？我们应该真的放手吗？

作为旧时代守门人的老古董，我觉得落地执行、沟通提效、记录沉淀都可以交给 AI，唯独思考不可以。

正如 AI 无法写出我的思考，即使它读了足够的代码和文档、也是从AGENTS.md开始便跟随着我一路重构，但还是少了一些思想内核吧。

跳转微信打开

TencentOS 科维斯AI首秀

作者：TencentOS 安全团队

2026年7月23日，Linux内核主线合入了一份很短的补丁。

它只改动了6行代码，修复的是一个已在Linux内核中存在超过18年的 0day 漏洞（CVE-2026-64564）。攻击者可以利用它从普通用户权限提升到服务器 root 权限；另外，在容器内部，攻击者还可能利用其突破容器隔离，取得宿主机root权限。

在这18年间，Linux内核经历数百个版本迭代，接受全球数千名开发者审阅，被Google syzkaller等顶级fuzzer反复测试，也经无数安全研究者与 Agent 反复审计，却始终无人发现。我们将这个漏洞命名为 SCTPhantom（SCTP 协议栈中长期潜伏的幽灵般漏洞）。

发现它的，是TencentOS安全团队打造的内核漏洞研究智能体 —— 科维斯 AI（Corvus AI）。

这是科维斯 AI 的第一次公开亮相。

科维斯 AI 的诞生

2026年，AI能够编写代码、分析代码并发现漏洞，已经不再新鲜。

前沿模型能力的持续提升，显著推动了漏洞发现数量的增长，也让AI进入高度专业的漏洞研究领域成为一件可被验证的事。然而，从发现内存错误到构造出稳定可用的利用，仍然是一项复杂的长链路工程。此前实验中，安全研究员观察到 Mythos Preview 能够发现内核中的内存越界写，并将影响推进至宿主机拒绝服务，却未能直接完成一条可在真实环境中稳定生效的完整利用链。

这说明，漏洞发现、根因确认、利用开发与环境适配，必须被组织成可持续运行的完整研究流程。

为此，TencentOS安全团队构建了科维斯AI，并围绕真实内核漏洞研究流程，打造了支持长链路、多轮次实验的Agent Harness框架。该框架将模型能力与专业安全工具、实验状态管理相结合，使复杂的内核安全研究能够保持连贯性与可验证性。同时，科维斯AI并非依赖单一Agent从头至尾执行，而是将研究过程系统化组织：通过多Agent协同与安全专家研判相结合，在证据充分时推进，在方向不成立时及时调整。只有经过稳定复现与交叉验证的结论，才会进入后续的利用与修复流程。

Agent Harness框架保障长链路研究的连续性，多Agent协同扩大探索与验证能力，安全专家负责方法指导与关键判断。三者结合，将模型能力真正转化为可持续、可验证、可规模化复用的内核漏洞研究能力。

依靠这套体系，科维斯AI完成了SCTPhantom从漏洞发现、稳定root提权到跨发行版迁移的全链路研究与验证。

一个漏洞，为什么竟能隐藏18年

SCTPhantom位于Linux内核SCTP协议栈。

SCTP常见于电信、专用通信及部分基础设施场景。与普通TCP连接不同，一个SCTP连接可以同时使用多个网络地址，也允许在连接存续期间动态增加或删除地址。

问题就藏在地址删除逻辑中。

单独执行时，相关操作都符合协议规则；但当三个特定参数按照特定顺序出现在同一条消息中，前一个操作已经释放的内核对象，会被后一个操作继续使用，由此形成内存释放后使用漏洞（Use-After-Free）。

这类问题难以通过单次函数检查发现。研究者需要同时理解协议状态、参数执行顺序，以及同一个内核对象跨越多个处理阶段的生命周期。

相关代码在2008年进入Linux上游，随v2.6.25发布。此后，它经历了大量版本迭代、代码审计和自动化Fuzzing测试，相关风险却一直没有被发现。

直到科维斯 AI 进入这条此前没有被充分探索的执行路径。

从一次Crash，到稳定root

围绕这条路径，科维斯 AI 自主编写 PoC，并在真实内核中反复验证。第一版 PoC 就触发了系统崩溃，但一次 crash 只能证明问题可以发生，还不足以确认它的可利用性和实际危害。

围绕每次运行结果，科维斯 AI 继续参与根因分析和利用验证，与研究员共同研判攻击者能否控制关键内核对象、能否获得所需地址信息，以及能否在真实防护配置下建立稳定利用链。

经过多轮实验和复核，科维斯 AI 最终将一次内核crash推进为稳定本地提权：在 Linux 普通用户权限环境中，成功获得了系统 root 权限。

SCTPhantom 属于本地提权漏洞。攻击者先取得服务器上的普通用户权限，或进入满足触发条件的容器。成功利用后，这一有限立足点可以被提升为 root 权限；在已经验证的容器配置中，攻击链还能进一步越过容器边界，取得宿主机 root 权限。

可以把它理解为：坏人原本只有一张普通访客卡，利用这个漏洞后，却可能拿到整栋楼的总钥匙。

3小时，把利用链迁移到另一套内核

能够在一套环境中完成利用，不代表已经掌握漏洞的实际影响。

不同Linux发行版采用的内核版本、编译选项、内存布局和防护配置并不相同。过去，把一套内核利用迁移到另一套发行版，通常需要研究员逐项调试和适配。

为了验证SCTPhantom在不同发行版中的真实危害，团队将TencentOS上的漏洞利用代码交给了科维斯 AI，要求它迁移到Debian默认内核。

科维斯 AI会自动分析两个内核环境之间的差异，重新定位并调整29处内核偏移和符号，再根据编译与运行结果持续修正代码。从接收TencentOS EXP，到在Debian默认配置中再次取得root权限，整个过程约3小时。

这次迁移验证了科维斯 AI 的另一项关键能力：它不只能够找到漏洞，还能将已有研究成果带入新的真实环境，快速回答漏洞在不同产品和发行版中是否具有同等危害。

最终结果显示，SCTPhantom 自 Linux v2.6.25 起长期存在于上游代码中，影响面极大。除了TencentOS 与 Debian，我们还在 Ubuntu 和 RHEL 上完成了提权验证，其中 RHEL 环境需要预先加载 SCTP 模块。Docker 环境中，SCTPhantom 还可以进一步完成容器逃逸并获得宿主机 root 权限。截至目前，已完成以下验证的环境如下：

需要注意的是这些仅是我们已经完成的真实环境验证，不代表漏洞影响范围仅限于这些版本。实际影响面还和发行版采用的内核代码、补丁状态和SCTP功能配置相关。

这不是一次偶然发现

Linux内核拥有数千万行代码，覆盖网络、文件系统、虚拟化、驱动和权限管理等多个高复杂度子系统。仅靠研究员手工选择目标，很难形成持续、稳定的漏洞发现能力。

科维斯 AI 面向真实内核研究流程构建。围绕一个研究目标，它可以持续提出漏洞假设、运行验证、分析结果并调整方向，将已经确认的事实、失败路径和待验证问题逐步沉淀下来，直到形成完整的证据链。

同期，科维斯 AI 还在 Linux 内核 Open vSwitch 模块中独立发现了另一项本地提权漏洞 （CVE-2026-64531，OVSwrap），并完成稳定root验证。后续披露过程中，我们确认了该问题已有外部安全研究员早于我们几天报告（撞洞）。

两个漏洞来自不同的内核子系统，形成机制也完全不同；科维斯 AI 均从零出发，完成漏洞发现和真实利用验证。

当前，CyberGym 等 Benchmark 已证明 Agent 能够高效完成给定条件下的漏洞相关任务。不过，这类评测大多聚焦于在提供漏洞描述后生成 PoC，且主要针对用户态应用程序，较少涉及操作系统内核层面的复杂问题。

科维斯AI探索的是一条更具挑战性的路径：在没有漏洞描述、没有触发样例、也没有标准答案的情况下，如何让 Agent 在真实 Linux 内核中规模化发现未知 0-day 漏洞，验证其可被稳定利用，并推动社区与产品侧完成修复。

从等 CVE 公告，到提前修复

传统的操作系统漏洞响应，通常从外部CVE开始：收到漏洞信息、判断影响版本、回补补丁、完成测试，再向用户发布更新。

TencentOS安全团队正在把漏洞响应起点向前移动。

当科维斯 AI 完成漏洞发现与危害验证后，TencentOS安全团队会同步启动产品影响研判、补丁回合、内核构建和回归验证。即使CVE编号尚未分配，产品团队也能够依据真实利用证据提前判断风险并推进修复。

SCTPhantom的响应时间线如下：

从发现到上游合入主线，11 天。CVE 分配当天，TencentOS 的修复包已经就位。

对于研究中发现的安全漏洞，我们坚持负责任披露原则，与Linux内核社区协同推动修复，并已按规定向相关监管部门报送。在主要受影响产品完成修复前，我们不会公开完整利用代码和可复现攻击的细节。

SCTPhantom 是科维斯 AI 的第一份公开答卷，未来我们将持续分享更多新成果。

关于科维斯AI

科维斯AI（Corvus AI）是由 TencentOS 安全团队构建的 Linux 发行版漏洞研究智能体。面向真实复杂的内核安全场景，系统依托多 Agent 协同架构与 Harness 深度优化，实现了从漏洞挖掘、根因分析、稳定利用构建、跨环境验证到补丁开发的全链路自动化研究。科维斯AI 始终坚持负责任的漏洞披露原则，积极携手上游社区推动协同修复，致力于从源头提升开源 Linux 发行版生态的整体安全水位。

跳转微信打开

一文进阶AI Infra

作者：binnnliu

背景

你有没有发现跟大模型对话，同样的提示词每次结果都不一样。 这符合我们对于“大模型的本质就是个猜词器”的一贯认知。

然而，可重复性是科学进步的基石。因此让大模型输出完全确定的结果是一个非常值得研究的问题，特别是强化学习需要确定性的 Rollout，来保证实验的可复现性和训练过程的稳定性。

Reproducibility is a bedrock of scientific progress.

其实很多同学第一时间会想到： 同样的硬件，同样的提示词：

1. 是不是把 Temperature 设置为 0，关掉随机采样就好了？

2. 如果业务需要 Temperature > 0，那把随机数种子（Seed）锁死，是不是也能保证每次输出一样？

我已经测试过了，环境：vllm serve Qwen/Qwen3-8B 答案： 是也不是。

是（Run-to-run 确定性）： 同一时间，没有其他请求时，多次同样的提示词请求，回答是一样的；

不是（Batch Invariance / 批次不变性）： 同一时间，有其他请求时，多次同样的提示词请求，回答是不一样的；

什么！难道不同的请求间会相互影响？不可能，不同请求间的注意力机制是严格物理隔离，不存在上下文污染的问题。

其实这一切的根源是推理引擎底层的动态组批与算子调度策略引发了浮点加法的顺序变化，而浮点加法不满足结合律：(a + b) + c ≠ a + (b + c)。

从系统设计的角度来看，导致结果波动的根本原因，不在于信息干扰，而在于系统为了掩盖访存延迟，在底层触发了非确定性的硬件级并行优化（Non-deterministic Hardware-level Parallel Optimizations）。

相对于定点数，浮点数的本质是科学计数法，主要是为了在有限的位数内（如仅仅 16 bit 或 32 bit），实现动态的数值范围与绝对精度间的trade-off。指数越大能表示的数值范围也就越大，同时因为尾数位数长度固定，指数越大能表示的绝对精度也就越低。绝对精度（即步长）的计算公式为：ULP(x) = 2^E - M，其中 E 是该浮点数的真实指数，M 是尾数位数。

根据 IEEE 754 标准，FP16 包含 1bit符号位、5bit指数位和 10bit尾数位。当数值为 2048（即 2¹¹）时，其规格化表示为 1.0000000000₂ × 2¹¹。此时，相邻可表示数之间的步长（ULP）增至 2，这意味着 FP16 的下一个可表示数为 2050，无法精确表示 2049。当底层硬件执行 2048 + 1 时，运算器内部会借助更宽的 GRS 扩展位（保护位、舍入位、粘滞位）得出精确结果 2049。但当结果需要写回 10 位尾数时，由于 2049 恰好位于 2048 与 2050 的正中间，系统触发了向偶数舍入（Round to Nearest, ties to Even）的规则，最终结果被强行舍入回 2048。

这里需要说明是：

这个例子只是为了说明“浮点加法不满足结合律”。在实际 推理过程中， GEMM 是 FP16/BF16 输入、FP32 累加；batch variance 依然存在，根因是 reduction topology 改变，而不只是 FP16 存储精度低。

那么问题又来了，都有哪些操作会改变浮点加法顺序呢？这个我们要从矩阵运算说起。

GEMM的Batch Invariance

GEMM操作为啥会改变浮点加法顺序呢？这要从GEMM的优化策略说起。

GEMM的优化策略

要理解这个问题，必须要先理解内存墙下 GPU GEMM算子的演进路线。很多人可能会问：不就是一个基础的矩阵乘法吗，怎么搞得这么复杂？
答案是：极其复杂，甚至整个 AI Infra 领域都在围绕它疯狂卷细节。 核心原因在于：现代 GPU 的计算单元（Tensor Core）算力增长太猛，远远甩开了显存带宽的增速。这就导致 GPU 大部分时间都在等数据搬运，计算单元由于未能及时获取输入数据，大量时间处于空闲等待状态（即 Compute Bound 退化为 Memory Bound）。这就是所谓的内存墙（Memory Wall）。

for i from 0 to M:          // 外层：遍历 A 的行 (总共 M 行)
    for j from 0 to N:      // 中层：遍历 B 的列 (总共 N 列)
        for k from 0 to K:  // 内层：计算 A第i行 和 B第j列 的点积 (长度为 K)
            C[i,j] += A[i,k] * B[k,j]

Tiling - 分块矩阵乘法

如果单纯按照上述公式逐个元素去计算，每次乘加运算都需要从极其缓慢的全局显存（HBM）中读取数据。由于完全没有利用到片上高速缓存（SRAM / 共享内存）和寄存器（Registers），这会导致海量的 HBM 重复读操作，使得算力无法的充分利用。

为了打破内存带宽的瓶颈，业界演化出了 IO-Aware（I/O 感知） 的分块算法。其核心思想是：化整为零，将大矩阵切分成适合放入缓存的小块。 调度时，将每个CTA（Cooperative Thread Array/ Thread Block）与结果矩阵 C 的一个特定小块 C_ij 绑定，让该 CTA 全权负责这个小块的计算。

一个 CTA 负责计算 C_ij 的完整数据流转逻辑如下：

1. 初始化累加器
   分配寄存器，专门用于存放目标分块 C_ij 的中间累加结果。

2. 沿着K 维度规约
   沿着公共维度 K 步进扫描。在每一个步长（Step p）内执行以下流水线：

3. Load (HBM → SRAM)：将当前计算所需的子块 A_ip 和 B_pj 从缓慢的全局显存，一次性批量搬运到速度更快的共享内存（SRAM）中。

4. Compute (Warp GEMM)

   ：各个 Warp 从 SRAM 中将数据提取至寄存器，交由 Tensor Core 执行极速的矩阵乘法。

5. Accumulate

   ：将本轮算出的乘积结果，就地与寄存器中的累加器相加。不写回显存。

1. 收尾与写回（Epilogue）
   当 K 维度的循环全部跑完，寄存器中的累加器便得到了 C_ij 的最终精确值。此时，再将其统一写回全局显存（HBM）。

Split-K

基于我们刚刚梳理的逻辑：每个 CTA 负责输出矩阵 C 的一个 Tile，并在内部沿着 K 维度串行跑循环。

但现实中经常会遇到一种极端情况：假设 K 的维度极其庞大，而输出矩阵 C （即 M 和 N 维度）非常小，小到只能切出 4 个 Tile。
此时，GPU 硬件调度器只会拉起 4 个 CTA 去干活。要知道，一块 NVIDIA H100 拥有 132 个 SM，这就意味着有 128 个 SM 处于完全空闲的状态，都在等待那 4 个 CTA 在极其漫长的 K 维度上苦哈哈地跑 Loop，GPU 的算力也被极大的浪费了。

既然在空间维度（M, N）上切不出更多的任务，比如在 LLM 推理的 Decoding 阶段，Batch Size 极小，M=1，如果强行只按空间切分，会导致 GPU 上大量核心无活可干，那能不能在K维度拆分，分配给不同的CTA计算呢？——这就是所谓的 Split-K 优化策略。它的核心思想是：打破单个 CTA 独自计算整个 K 维度的逻辑，把 K 维度切分成多段（Split_K），让多个不同的 CTA 同时处理同一个 C_ij 块在不同 K 片段上的局部乘积累加。

（特别注意：其实在普通的 Tiling 计算时，也是沿着 K 维度分段计算的。但两者有本质区别：BLOCK_K 是时间上的串行，同一个 CTA 每次从全局显存搬运 BLOCK_K 大小的数据，在寄存器中按固定顺序累加；而 SPLIT_K 是空间上的并行，强行把任务分发给物理上独立的多个 CTA 同时计算。）

如图所示，假设设置 Split-K = 2，不同颜色的 Tile 分别由两个独立的 CTA 并行处理，算力利用率瞬间翻倍。最终通过atomic_add将结果累加到C的同一位置。 这里需要注意的是：SPLIT_K 太大, atomic_add 竞争增加,收益会递减。

当然除了atomic_add的方式，还有一种实现方式： Workspace Reduction，具体工作流程：

1. 分配 Workspace（显存分配）：在HBM中额外分配一块大小为 [split_k, M, N] 的临时内存缓冲区（Workspace）。

2. 执行 Partial GEMM Kernel: 启动主矩阵乘法 Kernel。每个 Thread Block 负责计算 K 维度上的一个切片。计算完成后，不使用原子加，而是将局部结果直接写入到 Workspace 中属于自己的那个切片位置（即 workspace[k_idx, m, n]）。

3. 执行 Reduction Kernel：主 Kernel 执行完毕并同步后，启动第二个独立的轻量级规约 Kernel。这个 Kernel 负责沿着 split_k维度，将 Workspace 中的局部结果相加，并将最终的求和结果写入到目标输出矩阵 C 中。

GROUP_M - Swizzle L2 Cache

通过约束 CTA在矩阵C中的调度顺序，避免了由于跨度过大的离散内存访问而导致的 L2 Cache 抖动（Cache Thrashing）和频繁的数据驱逐。它在逻辑上将多个独立的 CTA 重新组合成一个维度为 GROUP_SIZE_M × N 的宏观调度矩阵。在这个被限定的连续执行区间内，由于被调度的 CTA 集中处理空间上相邻的输出块，它们能够共享已加载至 L2 Cache 中的矩阵 A 和 B 的数据，从而最大化数据的时间局部性与 L2 Cache 的复用率。这何尝不是另外一种维度的Tiling呢 ? 只是为了复用L2。而之前我们提到的Tiling，是为了复用SRAM和寄存器。更进一步Tensor Parallel(Column/Row Parallel)其实也是更高维度的Tiling呢～

算子调优

前文探讨了 Tiling、Split-K、Swizzle 等旨在缓解访存瓶颈的核心优化策略。但在实际的 GPU 硬件执行层面，针对不同规模的输入张量（Tensor Shape），系统必须确定具体的并行化切分配置：即矩阵分块的具体维度（BLOCK_M / BLOCK_N / BLOCK_K）以及 K 维度的切分段数（SPLIT_K）。这些切分参数的选择，不仅直接决定了算子的访存效率与硬件利用率（Occupancy），更关键的是——分块参数的动态变化会重塑底层浮点数累加的归约拓扑（Reduction Tree），这是导致大模型推理在不同批次下失去Batch Invariance的根本原因。

为了解析推理引擎底层为何会根据输入特征动态变更这些调度参数，我们需要先回顾 GPU 算子的编程范式演进，并深入探讨现代编译器引入的自动调优（AutoTune）机制。

CUDA VS Triton

在之前的《AI Infra入门：GPU是如何工作的》中，我们探讨了 CUDA 编程模型与 GPU 硬件执行模型： Grid定义了内部Thread Block的组织形式(gridDim)；Thread Block定义了内部thread的组织形式(blockDim)。

然而，原生 CUDA 编程的门槛依然极高，开发者需要手动实现各种底层且繁琐的优化逻辑。OpenAI Triton 的出现，彻底改变了这一现状。大幅降低了编写高性能 GPU 算子（Kernel）的门槛，让开发者能以接近 Python 的生产力，写出接近 CUDA C++ 专家级性能的代码。借助内核融合（Kernel Fusion）、IO-Aware 等底层优化技术，Triton 不仅保证了极致性能，还兼顾了极佳的硬件无关性。

两者核心思想的差异在于编程范式：

• CUDA（以线程为中心）：开发者需要显式定义底层网格，例如 <<>>，由底层生成 128 个线程，硬件再将其划分为 4 个 Warp 调度执行。

• Triton（以Tiling/Block 为中心与自动调优）：开发者只需关注数据分块，并可通过 @triton.autotune 装饰器提供一个配置搜索空间（如不同的分块大小、测试 4 个或 8 个 Warp）。Triton 编译器不仅会在底层自动将需求（如 4 个 Warp）精准映射为 4×32=128 个线程以屏蔽硬件细节（即<<>> ），更会在运行时自动进行基准测试，智能选出当前硬件下的最优参数组合。

在 PyTorch 2.0 及更高版本中，引入了OpenAI Triton作为编译器：

1. 前端分析：当用户调用 torch.compile(model) 时，PyTorch 的前端（如 TorchDynamo）会捕获计算图。

2. 后端优化与代码生成：默认后端 TorchInductor 会分析图中可以被 Kernel Fusion 的操作，生成 OpenAI Triton 代码。

3. JIT编译与执行：最后，由 Triton 的 JIT (Just-In-Time) 编译器接管这些代码，将其编译成一个为特定 GPU 硬件高度优化的、单一的融合内核（Fused Kernel），最终高效执行。

在这一生态体系下，PyTorch（借助 Inductor + Triton）自动接管了过去需要 CUDA 专家耗费大量精力才能完成的性能调优工作。尽管自动调优的 Inductor+Triton 在绝大多数场景下都能带来巨大的性能飞跃，但它本质上仍是一个通用型的自动化方案。当面对极其关键、对性能压榨到极致的特殊算子时，纯手工的底层优化依然不可或缺。

当然，无论是让编译器自动调优，还是我们手动调优，都必须穿透抽象，理解 GPU 底层最核心的物理边界与调优逻辑。

在硬件执行层，多个 Thread Block 可以共享同一个流多处理器（SM）。只要 SM 的物理资源（寄存器、共享内存等）还没被占满，硬件调度器就会把更多的 Block 塞进同一个 SM 里并发执行。然而，每个 SM 都有硬性的并发规格上限（例如最大线程数 2048，最大 Block 数 32）。

同一个Thread Block 内的 Thread 可以通过共享内存（Shared Memory）进行数据交换，并且可以进行同步（__syncthreads()）。

寄存器限制

A100/H100 每个 SM 的物理寄存器文件大小固定为 65536 个 32-bit 寄存器（256 KB）。每个硬件线程最多只能分配 255 个寄存器。 而单个线程需要的寄存器数由两部分组成：

基础开销（Base Overhead）：每个线程私有的，用来存内存指针、循环计数器、TMA 状态等；

累加器分摊（Accumulator Share）：假设输出块大小，即Accumulator 为 BLOCK_M × BLOCK_N，这寄存器是被所有线程平摊的。每个进程的寄存器用量为：BLOCK_M × BLOCK_N / NUM_WARPS / 32。如果Tiling变大，必须同步增加num_warps,否则会导致Register Spilling；

关联公式：(BLOCK_M * BLOCK_N) / (num_warps * 32) <= 255 通常需控制在 128 左右, 如果超过255，num_warps 必须调大，或者 BLOCK 必须调小。

执行范式与共享内存限制

在传统的 CUDA 优化实践中，提升 Occupancy（占用率）以隐藏访存延迟是一项核心原则。即线程级并行（TLP）隐藏延迟：SM 上驻留的活跃 Warp 数量越多（即 Occupancy 越高），硬件调度器（Warp Scheduler）在当前 Warp 因访存而阻塞（Stall）时，就越容易找到其他处于就绪状态的 Warp 进行切换。通过这种零开销的上下文切换，系统使得计算指令与内存访问在时间上相互重叠，从而有效隐藏了全局内存的物理延迟。

然而，在 Ampere / Hopper 架构中，Tensor Core 提供了极高的浮点吞吐量，但 HBM 的物理访存延迟并未同比例缩减。在这种计算能力远超访存带宽的背景下，高 Occupancy 策略的边际效益急剧衰减：即使 SM 上驻留了大量 Warp，它们也会迅速耗尽当前计算任务，并集体触发访存请求，导致所有 Warp 同时陷入阻塞。此时，单纯依靠线程级的上下文切换已无法掩盖内存级别的物理延迟。

为维持 Tensor Core 的高吞吐率，现代 GPU 引入了硬件级异步内存拷贝机制（如 Ampere 架构的 cp.async 和 Hopper 架构的 TMA 引擎）。num_stages 的核心思想是利用多级缓冲（Multi-Buffering）实现计算指令与数据搬运指令的异步并发。即GEMM的优化方向从高并发掩盖访存延迟转向通过 Asynchronous Pipelining (异步流水线) 来掩盖延迟。

若 num_stages 配置过小（如默认值 2），计算过程易因等待数据就绪而产生气泡（Pipeline Bubble），导致总体吞吐量受限。若配置过大，除导致 SRAM 溢出触发编译失败（Out of Shared Memory）外，管理多级流水线状态的指针还会消耗额外的寄存器资源，造成性能倒退。在不同硬件架构（如 SRAM 容量更大的 H100）上进行高阶调优时，核心痛点在于寻找能够最大化重叠率、且不触发资源溢出的最佳边界配置参数。

(BLOCK_M * BLOCK_K + BLOCK_N * BLOCK_K) * 字节数 * num_stages <= SMEM物理上限 (如 H100 是 228KB)

调优Trade-Off

以 Llama-3-8B Q/K/V Linear Proj - Fused QKV为例，hidden_size为4096， qkv_proj_size为6144，如下：

即：M=num_sched_tokens,N=6144,K=4096，其中BLOCK_K一般设置为 16、32 或 64。

BLOCK_M / BLOCK_N的设置：

• M很大时（M>4096)，原则上我们希望提升计算强度，BLOCK_M × BLOCK_N 尽可能的大，极大地复用SMEM，此时需要寻找 num_warps 的平衡点，num_warps太小会导致干活的线程少，单个线程分摊到的累加器寄存器过多，进而击穿单线程最多 255 个寄存器的物理上限，触发Register Spilling；而num_warps太大会导致基础开销占比大，一个CTA占用大量SM资源，从而导致GPU Occupancy 降低。需要一个合适的num_warps来确保 BLOCK_M × BLOCK_N 足够大。

• M很小时 （M<64），缩小 BLOCK_M 贴合 M，为了充分利用 SM 的算力，可以 1. 适度缩小 BLOCK_N从而产生更多的Tile分发给不同的 SM； 2. 开启 Split-K，在 K维度拉起更多 CTA 并行计算。

Batch Invariance的来源

前文探讨了诸多优化策略，那么具体是哪些参数的变动导致了浮点加法顺序的改变？

从数学本质来看，矩阵乘法 C = A × B（其中 A 为 [M, K]，B 为 [K, N]，C为 [M, N]）中任意元素 C_i,j 的计算逻辑是恒定的——即取 A 的第 i 行与 B 的第 j 列进行点积：

C_i,j = Σ_k=0^K-1A_i,k × B_k,j

在 Triton / CUDA 的底层优化中，针对各项调度参数的动态调整，其对确定性的影响有着本质区别：

• BLOCK_M

   与 BLOCK_N（无影响）：分块逻辑为加载 Tile_A [BLOCK_M, BLOCK_K] 与 Tile_B [BLOCK_K, BLOCK_N]，并计算输出 Tile_C [BLOCK_M, BLOCK_N]。这仅仅是在做空间维度的任务映射，决定了哪些元素被打包在一起独立计算，以及由哪个具体的 CTA (Thread Block) 负责计算哪一块区域。对于输出矩阵 C 中的特定元素 C_i,j 而言，无论它被分配给哪个 CTA、与哪些相邻元素一起被计算，其底层的 K 维度点积逻辑并未改变。因此，改变这两个参数不会影响浮点加法的顺序。

• GROUP_M / Swizzle

  （无影响）：Swizzle 本质上是改变了多个 CTA 在网格（Grid）级别的调度顺序，以此来提高 L2 Cache 的命中率。它决定的是先算哪一个空间块，后算哪一个，完全没有干涉某一个特定分块内部的乘积累加过程。因此，Swizzle 同样不会破坏Batch Invariance。

• BLOCK_K

  （引入确定性误差）：定义了在规约维度（Reduction Dimension）上的步长。改变 BLOCK_K 会直接改变单次循环中加载到寄存器中的数据量，进而改变 Tensor Core 内部 MMA指令的累加树拓扑。这种改变会导致浮点加法顺序的变化（即不同 BLOCK_K 产生不同结果，但同一 BLOCK_K 结果恒定）。

• SPLIT_K

  （引入非确定性误差）：将 K 维度强行切分给多个 CTA 并发执行。如果采用Atomic Add进行结果合并，由于 GPU 硬件调度线程块的先后顺序是完全随机的，加法顺序是完全随机不可控的。即便采用Workspace Reduction，SPLIT_K 段数的动态变化同样会改变累加树拓扑。

• num_warps

   和 num_stages 的本质是硬件资源分配与流水线调度（决定分配多少个cta去算、开辟几份缓存池做异步搬运）。并不改变宏观的矩阵点积计算逻辑和Reduction Tree拓扑。

综上所述，推理引擎在性能与确定性之间存在着固有的架构冲突，为了追求极致的访存复用（动态调整 BLOCK_K）与并提升流多处理器（SM）的并发利用率（动态开启 SPLIT_K），底层的启发式调度策略不可避免地改变了浮点运算的Reduction Tree拓扑，这正是大模型在动态 Batch 下丢失Batch Invariance的根本原因。那么在真实的推理场景中，该如何修补这个机制？接下来我们深入 vLLM 的实现，看看它是如何在底层硬件特性和上层调度逻辑之间做 Trade-off 的。

vLLM中GEMM的Batch Invariance支持

怎么解决呢？直觉上，只需要在推理引擎中全局禁用 Split-K 并锁死 BLOCK_K 即可。但现实的工程实现远比这复杂。现代推理引擎（如 vLLM）底层的 GEMM 操作的下发路径涉及多层抽象与多种后端。实现严格的 Batch Invariance 并非单一配置的修改，而是需要针对特定的软硬件运行环境，进行多维度的执行路径路由与参数约束。具体的GEMM执行路径决于以下三个维度的组合：

• 硬件架构（Architecture）：SM80 (Ampere) 与 SM90/SM100 (Hopper/Blackwell) 的底层 GEMM 执行范式截然不同——前者靠 warp 级并发掩盖访存延迟，后者靠 TMA + WGMMA 的异步流水线。执行范式不同，实现Batch Invariance的逻辑也会不同。

• 数据精度（Data Type）：bf16/fp16 由生态最成熟的 cuBLASLt 承接；而 fp8/fp4 等低精度会转向 CUTLASS（乃至 DeepGEMM 等）专用 kernel。不同后端控制逻辑也不一致。

• 算子入口（API Backend）：nn.Linear 走的是 vLLM 自己的 dispatch，可直接路由到定制高性能内核；而裸 torch.mm / bmm 走 PyTorch dispatcher → cuBLAS/cuBLASLt，调度权在框架和闭源库手里。

SM8x vs SM90/SM100

SM80: warp维度的tensor core(mma.sync)调度 : 优化逻辑是提高占用率，warp同时负责搬运和计算。

4096 * 4096 ->CTA Tile（如128*128）  -> Warp Tile（32 * 64） -> mma 指令级(16 * 8 * 16)

SM90/100 TMA 硬件单元的引入和 WGMMA 指令（Warp Group 128 线程）促成了范式转移通过Asynchronous Pipelining (异步流水线)来掩盖延迟。

4096 * 4096 -> CTA Tile (如 256 *128) -> Warp Group Tile (64 *128) -> wgmma 指令级 (64 *N * 16)

对于大矩阵，由于 CTA 分配到的总体空间足够大，每个 Warp 都能分到一块足够大的专属空间（例如 32x64）。然后直接把大 Tile 切成小 Tile 分给 Warp，这样多个 Warp 之间交替访存和计算从而掩盖内存延迟。大家都各自在 K维度独立、串行执行到底，互不干涉，run-to-run是没问题的。

但是batch-to-batch情况下BLOCK_K的发生变化，因此会引发浮点加法顺序的波动？

实际上呢，也不一定，这取决于warp level的K是不是恒定的。比如启发式的auto tune可能导致BLOCK_K从32变成64，但是实际的底层执行以K=16为步长，依次处理K维度的tile，因此就从底层消除了Batch Variance。那是不是就是说可以忽略BLOCK_K的影响，只关注Split-K就行了。讲道理，这个在大矩阵上大概率是成立的。

对于小矩阵，比如32*32分配到一个CTA（K=4096），那每个warp可能只能分配很小的Tile，从而没有足够多的Tile，即M/N并行度不足->活的warp少,占用率低-> 这种情况下在K维度串行执行就无法充分利用隐藏延迟的特性。因此，系统被迫让所有 Warp 重叠在这同一块 32 * 32 的矩阵上，强行在时间（K）维度上进行切分（Warp-level K-Slicing）。 多个 Warp 各算一段 K，最后在共享内存里通过Reduction Tree合并。一旦 Batch 参数变动导致 K 切分段数改变，规约树形状就会改变，从而引发了浮点加法顺序的波动。

当然对于小矩阵，GEMM 库此时可能选择更小的 tile、GEMV/SIMT、persistent kernel、warp-level K-slicing、CTA-level Split-K 或 Stream-K 等不同算法。

Warp-level K-slicing 会让多个 warp 分别计算同一输出 tile 的不同 K 分片，再在 CTA 内合并 partial results；它可以增加单 CTA 内的有效 warp 数，但不能增加 grid 中的 CTA 数量。为了提升SM的利用率，通常需要 CTA-level Split-K。

不过到了SM90+,降低了对传统高 occupancy 隐藏访存延迟的依赖，标准 WGMMA mainloop 中，一个warpgroup 共同维护分布式 accumulator，并依次处理 K tile，不需要生成多个独立 warp partial result 后再做 CTA 内 reduction。

所以我们可以看到代码注释："Hopper (SM90) and Blackwell (SM100): the only source of batch variance is split-k"， 即在SM90 Hopper / SM100 Blackwell上，当前受支持和测试的 FP16/BF16 PyTorch/cuBLASLt 路径，在禁止 Split-K batch invariant。

这里需要特别说明的是，SM90/SM100锁定Split-K可以获取batch invariance，SM8x需要同时锁定BLOCK-K和Split-K才能获取batch invariance都是基于测试的，因为 cuBLAS / cuBLASLt 是闭源的。

当然也有很多人误认为Split-k多workspace时，规约树是按顺序规约的，可以保证结果不变，但是这个只是run-to-run维度的，一旦K变化，结果还是会变化。

说了这么多，其实呢，最终浮点数加法的顺序，不仅受mainloop 的 BLOCK_K staging 决定的（CTA Tiling ），也受更低维度的Warp Tiling/Warp Group Tiling（以及硬件原子指令粒度）决定。但是呢，要解决这个问题却要从CTA Tiling角度来。

SM80上GEMM的Batch Invariance支持

对于SM80要同时关注SPLIT_K和BLOCK_K。其实对于Linear层的GEMM无论SM是哪个版本/无论是eager还是compile mode，都会走到linear_batch_invariant -> matmul_persistent。

# class UnquantizedLinearMethod(LinearMethodBase):
def apply(
    self,
    layer: torch.nn.Module,
    x: torch.Tensor,
    bias: torch.Tensor | None = None,
) -> torch.Tensor:
    if envs.VLLM_BATCH_INVARIANT and current_platform.is_cuda_alike():
        return linear_batch_invariant(x, layer.weight, bias)
    return dispatch_unquantized_gemm()(layer, x, layer.weight, bias)

而对于非线性层的计算，比如代码中直接调用torch.mm,则还需要额外考虑。由于SM80在cuBLASLt上不支持禁用BLOCK_K,只能更换Triton实现，最终也会走到matmul_persistent。其中matmul_persistent是一个persistent kernel 即griddim=num_sm，固定 K 顺序、固定 tile、不切 SPLIT_K。

if current_platform.is_device_capability_family(80):
    # SM80 (Ampere) cannot rely on cuBLASLt-only determinism; install the
    # triton persistent matmul overrides for mm/addmm/matmul/linear.
    _batch_invariant_LIB.impl("aten::mm", mm_batch_invariant, "CUDA")
    _batch_invariant_LIB.impl("aten::addmm", addmm_batch_invariant, "CUDA")
    _batch_invariant_LIB.impl("aten::matmul", matmul_batch_invariant, "CUDA")
    _batch_invariant_LIB.impl("aten::linear", linear_batch_invariant, "CUDA")

特别注意：compile mode下aten override不生效，所以会走到原始的aten::mm。

matmul_persistent 是怎么做到确定性的

对于bf16和fp16，所有SM版本的SM的 Linear，无论是eager还是compile mode，最终都落到 matmul_persistent 这个 Triton kernel。当然eager mode下， SM80的裸 mm的也会走到matmul_persistent。（compile mode下aten override不生效，所以会走到原始的aten::mm）

matmul_persistent 的实现逻辑很简单，相对于普通 GEMM 靠 @triton.autotune / cuBLASLt 启发式按 shape 挑 config，matmul_persistent 直接固定 config，彻底关掉 autotune。 每种 dtype 用一套硬编码的分块参数，特别是BLOCK_K，与输入的 M/N/K 无关：

configs = {
    torch.bfloat16: {"BLOCK_SIZE_M": 128, "BLOCK_SIZE_N": 128, "BLOCK_SIZE_K": 64,
                     "GROUP_SIZE_M": 8, "num_stages": 3, "num_warps": 8},
    # fp16 / fp32 各自一套，同样是常量
}

这里要澄清一点：BLOCK_M/N/K、SPLIT_K 对 Triton autotune 来说都只是普通 constexpr，而 split-k 本身是一种需要作者手写进 kernel 的实现模式（多一维 grid + atomic/reduction），并非 autotune 的自动优化策略。matmul_persistent 没有实现 split-k，所以它既不受 autotune 影响，也天然不存在 Split-K 乱序——真正被写死的就只有 BLOCK_K 这一个变量。

另外函数名里的persistent其实跟batch invariance无关，是说grid 只开 min(NUM_SMS, tile 数)、每个 program 常驻 SM 循环吃多个 tile），是为了避免频繁 launch 开销，tile→CTA 的映射本就由固定 config 决定，与确定性无关。

SM90/SM100上GEMM的Batch Invariance支持

对于，SM90/SM100只需要关注Split-K，即禁止SPLIT_K拆分；

bf16/fp16

上面已经提到了对于Linear层的GEMM无论SM是哪个版本，都会走到linear_batch_invariant，最终走到matmul_persistent。

对于直接调用torch.mm的部分，当前的逻辑是仍然走cuBLASLt，只是依赖设置确保Split-K=1。

设置了preferred_blas_library(backend="cublaslt")之后，GEMM会优先走cuBLASLt，通过设置reduction mask，确保了bf16/fp16 Split-K=1。CUBLASLT_MATMUL_PREF_REDUCTION_SCHEME_MASK = CUBLASLT_REDUCTION_SCHEME_NONE

reduced_precision_val = (
    (False, False) if is_torch_equal_or_newer("2.10.0") else False
)
torch.backends.cuda.matmul.allow_fp16_reduced_precision_reduction = (
    reduced_precision_val
)
torch.backends.cuda.matmul.allow_bf16_reduced_precision_reduction = (
    reduced_precision_val
)
torch.backends.cuda.preferred_blas_library(backend="cublaslt")

传统 cuBLAS 后端没有 reduction-scheme mask 这个能力,PyTorch 里一旦设了 allow_splitk=False 又没切到 cuBLASLt,会直接 TORCH_CHECK 报错:
TORCH_CHECK(reduction != DisallowReducedPrecisionDisallowSplitK, "...allow_splitk=False) requires the cuBLASLt backend");

fp8

fp8 的入口是量化线性层里的 cutlass_scaled_mm，底层有 CUTLASS 与 cuBLASLt scaled_gemm 两条路。

选中 CUTLASS → 调它（csrc if(batch_invariant) 锁 config 不随 M

cuBLASLt scaled_gemm → 由于API设置mask仅支持bf16/fp16，对于fp8只能另外想办法。怎么办呢？把workspace的限制到尽量小，而split-k(COMPUTE/OUTPUT) 与 atomic(INPLACE) reduction 都需 workspace，最终可选策略只剩不需 workspace 的 NONE，即 split-k=1；但 scaled_gemm 没设置 reduction-mask，无 API 级保证。

os.environ["CUBLASLT_WORKSPACE_SIZE"] = "1"

FlashInfer → DeepGEMM

fp4

如果开启了batch invariant，无论 M 多大，都固定使用同一个配置 sm100_fp4_config_default。另外就是选择PersistentScheduler，确保K维度不拆分。

CUTLASS 3.x TileScheduler的定义：

// Dispatch function to select appropriate config based on M
template <typename OutType>
void cutlass_fp4_gemm_dispatch(torch::stable::Tensor& D,
                               torch::stable::Tensor const& A,
                               torch::stable::Tensor const& B,
                               torch::stable::Tensor const& A_sf,
                               torch::stable::Tensor const& B_sf,
                               torch::stable::Tensor const& alpha, int64_t m,
                               int64_t n, int64_t k, cudaStream_t stream) {
  if (vllm::vllm_is_batch_invariant()) {
    using BiGemm = Fp4GemmSm100<sm100_fp4_config_default, OutType>;
    static_assert(
        cute::is_same_v<typename BiGemm::TileScheduler,
                        cutlass::gemm::PersistentScheduler>,
        "batch_invariant requires a persistent tile scheduler; stream-K or "
        "split-K would break numerical invariance");
    runGemm<BiGemm>(D, A, B, A_sf, B_sf, alpha, m, n, k, stream);
    return;
  }
  uint32_t const mp2 = std::max(static_cast<uint32_t>(16), next_pow_2(m));
  if (mp2 <= 16) {
    // m in [1, 16]
    runGemm<Fp4GemmSm100<sm100_fp4_config_M16, OutType>>(
        D, A, B, A_sf, B_sf, alpha, m, n, k, stream);
  } else if (mp2 <= 256) {
    // m in (16, 256]
    runGemm<Fp4GemmSm100<sm100_fp4_config_M256, OutType>>(
        D, A, B, A_sf, B_sf, alpha, m, n, k, stream);
  } else {
    // m in (256, inf)
    runGemm<Fp4GemmSm100<sm100_fp4_config_default, OutType>>(
        D, A, B, A_sf, B_sf, alpha, m, n, k, stream);
  }
}

RMSNorm的Batch Invariance

RMSNorm - 均方根归一化

这个算子的输入是[num_tokens, hidden_size]，然后需要对于每个token的hidden做均方根归一化，均方根归一化的公式如下：

y = (x)/(RMS(x)) ⊙ γ ，其中均方根（RMS）的计算：RMS(x) = √((1)/(d) Σ_i=1^dx_i² + ε)