铃阅
❌

普通视图

开坑!从 AI Coding 到 AI4S:新开源项目 Pero 的一次探索

2026年10月29日 16:24

原创 Phodal 2026-10-29 16:24 浙江

一次不靠谱的新探索/

PS:最近从 Qoder 离职了。原本还想继续折腾 AI Coding 和 Coding Agent 相关的开源项目,但考虑到过去的工作经历, 还是希望换个应用方向,尽量避开与此前工作内容、产品方向的交集,做点不一样的东西。

于是,就有了这个新坑:Pero。坑是新挖的,还比较粗糙,欢迎大家来贡献 tokens。

GitHub:https://github.com/phodal/pero


好久没有认真开一个不一样的新坑了。过去几年,我的大部分精力都放在 AI Coding、Coding Agent,以及 AI 如何改变软件工程上。 从 AI 辅助编程,到 Agent 自主执行、多 Agent 协作,再到各种工程化实践,基本上一直围绕着「如何让 AI 更好地帮助开发者」 这个问题打转。

虽然想换个方向,但过去积累的技术和经验总还是有些舍不得放下。毕竟,Agent 的任务规划、工具调用、长期记忆、多 Agent 协作、 执行环境管理等能力,并不只是为软件开发准备的。

这一次,我想把这些积累带到科研工作流中。

为什么是 AI for Science(AI4S)?

最近一直在想一个问题:

如果 AI Agent 不只是帮助开发者写代码,而是能够参与科研任务、组织研究过程、调用专业工具,甚至协调分布式计算环境, 那么我们能把它带到哪里?

科研工作流往往从一个 Python 脚本、Notebook 或模型 Demo 开始。随着研究深入,又会涉及文献、数据、实验、计算资源和结果验证。 这些环节和软件工程有不少相似之处,但也提出了不同的要求。代码能运行,并不意味着科研结论成立。输入数据来自哪里、 使用了什么方法和环境、结果能否复现,以及应该由谁来判断它是否可信,都是需要认真对待的问题。

Pero 是一个面向科研工作流的开源工作区,尝试把领域 App、Agent 和计算资源连接起来。 当前先从 Virtual Cell 入手, 探索如何把散落在脚本、Notebook 和专业工具中的研究过程,组织成可以持续执行、追踪和复核的项目。

这还是一个很早期的项目。很多想法需要通过真实场景来验证,也有不少技术问题尚未解决。比起一开始就覆盖所有科研领域, 我更希望先找到具体问题,把一条有用的工作流做出来。

Pero 想做什么?

最终形态还在探索,但目前有三个明确的切入点。

1. 以项目为中心的工作区

我更想探索的,是如何让 Agent 参与一个持续推进的研究项目,而不只是完成一次问答。

为此,我希望围绕 Project 组织研究问题、文献、数据、任务、实验结果与知识。 让 Agent 能够理解项目上下文,持续跟踪研究进展,并在数据或研究条件发生变化时,提出可供研究者审阅的新任务。

从一次性对话,走向持续的研究协作。这是 Pero 想探索的方向,完整的项目记录、长期记忆和主动工作流还需要逐步实现。

2. 开放式分布式 Agent 协作

科研往往需要不同专业的人和工具共同参与。我希望 Pero 能够支持不同的 Agent 在同一个项目中分工, 并把任务交给获准使用的本机、实验室服务器或云端计算资源。

过去参与开源主要是贡献代码,未来或许还可以贡献 Agent、Tokens、算力和实验结果。目前,Pero 已经有了 Task、Run、Worker 的基础实现,并开始支持 GitHub 任务导入、认领与分发。可以先从一个具体任务开始,探索如何把协作和执行连接起来。

任务广场:https://app.openpero.com/tasks (服务器有点拉了)

这距离完整的多 Agent 研究协作还有很长的路。自动化贡献、研究产物登记与独立验收等环节,仍需要继续完善。

3. 领域驱动的垂直场景

我希望不同的科研领域能够拥有自己的 App,把领域数据、专业工具、计算方法和 Agent 组合起来。比如:

  • • 生命科学中的细胞图谱、基因表达和蛋白质结构分析。

  • • 材料科学中的分子建模、晶体结构和物理仿真。

不同领域有不同的数据格式、计算模型和验证方法。一个通用聊天界面,很难直接承载这些差异。

所以,Pero 希望支持一种可组合的科研 App 模式:领域能力可以通过专门的界面独立使用,后续也能作为工具被 Agent 调用, 参与更复杂的研究工作流。

一个示例:从 Virtual Cell 开始

为了验证这个方向,我先做了一个具体的实验:Virtual Cell(虚拟细胞)。它最初来自一位前前同事提出的问题。我借助 ChatGPT 做了一些资料调研,并尝试把相关分析与可视化流程做成可交互的 App。我不是这个领域的专家,因此目前更适合把它看作工作流与交互方式的原型; 其中的科学假设、方法选择和结果解释,还需要领域研究者参与审查。

目前,它包含参考细胞图谱浏览、扰动分析流程、一阶反应模拟,以及三维体数据可视化。使用者可以通过界面查看细胞数据、 调整参数和观察输出,减少在不同脚本与工具之间切换的操作。 其中,反应模拟和体数据示例用于演示交互,不能代表经过科学验证的细胞预测模型。扰动分析也有其数据与评估范围,不能直接推广为对未知条件的可靠预测。

Virtual Cell 延续了此前在 Point 中公开的虚拟细胞实验,目前已经作为 Pero 的第一个领域 App 接入。本地界面与 Python 后端已经可以运行;Agent 工具调用、Task/Run 执行和 Project 产物登记,还没有与它连通。

不过,我觉得这里有一个很有意思的方向:如果 Virtual Cell 能成为一个 Agent 可以理解和操作的科研环境,会怎样?比如, 研究者提出一个基因扰动相关的问题,Agent 协助查阅文献、整理可选方法、提出实验计划。研究者确认后,再调用领域 App 或远程计算资源执行分析,将输入、方法版本、执行环境和结果保存到 Project 中,供后续复核与迭代。

这是一条希望逐步打通的工作流。相比一开始就设计一个宏大的 AI4S 平台,我更愿意从具体的领域 App 入手,边做边验证, 再沿着这个思路探索更多场景。

技术栈

围绕工作台、任务协调和领域计算,Pero 目前采用了几种不同的技术:

  • • Python:承载科学计算、数据处理与领域 App 后端,按具体场景接入方法和模型。

  • • Rust:承载 GPUI 工作台、本地 Host、ACP 接入与独立 Worker;当前桌面主路径采用 GPUI/Wasm,也在探索原生桌面形态。

  • • Go:承载云端任务协调与分发;自研 Agent Harness 是后续探索方向。

  • • Electron 与 JavaScript/TypeScript:承载桌面壳、领域 App、可视化及 Web 集成。

设计上,也参考了几个不同方向的探索:Zed 与 GPUI 的工作台和界面实现、Kiro Crew 的持久工作区与 App 组合、Claude Science 的科研工作台, 以及 DeepSeek Harness 的插件架构。

DSH 的 harness PR 在:https://github.com/phodal/pero/pull/4 如果你也有兴趣欢迎来设计。

目前,macOS 桌面开发版、ACP 会话、分布式任务基础以及 Virtual Cell 已经有初步实现。领域 App、Agent 和研究结果复核之间的完整流程,仍需要逐步打通。

小结

从 AI Coding 到 AI4S,对我来说,既是一次方向上的切换,也是一次重新学习。我希望通过开源的方式,和科研工作者、AI 研究者以及开发者一起,把这些想法放到真实问题中检验。

如果你有一个正在反复手工操作的科研流程,欢迎带着具体问题来聊:输入是什么、目前怎么做、最后怎样判断结果是否有用。也欢迎贡献领域 App、分析方法,或者帮助审查 Virtual Cell 中的方法与示例。

Pero 最终会变成什么样子,现在还很难说。这一次,不急着给出答案。先把坑挖起来,边做边探索,也欢迎更多人一起参与。

GitHub:https://github.com/phodal/pero 

阅读原文

跳转微信打开

/mobile-use 在 AI IDE 中构建通鸿蒙、安卓与 iOS 的 Agent 闭环验证

2026年9月11日 16:00

Phodal 2026-09-11 16:00 浙江

Computer Use 已经可以操作电脑,Browser Use 可以进入正在使用的浏览器。Qoder 推出 Mobile Use 插件(Beta),在安卓、鸿蒙与 iOS 上将代码修改接入真机或模拟器,完成运行、交互与结果确认。

Computer Use 已经可以操作电脑,Browser Use 可以进入你正在使用的浏览器。移动端还没有对等的能力。

今天的 Coding Agent 已经可以修改安卓、鸿蒙与 iOS 代码,但往往止步于提交之前。移动端 app 是否成功构建,修改后的页面如何呈现,用户所指的是哪一个控件,点击之后是否进入正确页面,这些问题还需要解决。

因此,我们推出 Mobile Use 插件(Beta)。安卓、鸿蒙与 iOS 均可将代码修改接入应用运行,在设备上完成交互,并确认修改是否生效。

image.png
image.png

Mobile Use 面向正在开发中的手机应用

常见的 Mobile Agent 多用于“操作手机”,比如打开应用、填写表单、走完一段操作流程。Qoder 新上线的 Mobile Use 插件面向另一类场景:应用本身仍在开发与修改之中。

Agent 既要执行点击,也需要理解当前工程、构建目标、运行设备与界面状态。完成代码修改后,它重新运行应用,定位受影响的页面,执行必要交互,并以截图、日志、断言或测试结果证明本次修改有效。

点击与输入只是其中一步。需要完成的,是从代码变更到结果确认。

image.png
image.png

一次完整验证:从代码修改到结果确认

以一次界面修改为例。无论是布局、文案、点击反馈还是页面跳转,以往都需要自行完成构建、安装、在设备上操作,再对照代码。证据在设备上,代码在 IDE 中,中间依赖开发者在两端传递信息。若 Agent 只能依据文字描述和数秒前的截图,便容易改错位置。

现在可以将这项工作交给同一条会话中的 Agent。在 Canvas 上圈选出问题的区域,并在对话中发送:

我刚修改了界面上圈出来的这一处。请构建并运行应用,按圈选位置执行操作,截图确认结果是否符合预期。若不符,请对照代码修改,完成后再验证一次。

圈选给出的是具体控件和当前画面,Agent 可以同时使用截图、可访问性结构、控件文本和界面状态,而无须仅凭「这里不对」进行推断。它在同一台设备上执行操作、截取画面并对照结果:验证通过则返回结论;未通过则回到代码修改,并再次验证。

image.png
image.png

若结果不符合预期,可以在 Canvas 中直接看到它操作了哪一处、界面变成了什么样。下一轮仍使用同一台设备、同一条会话,无须重新描述现场。

image.png
image.png

三端接入方式不同,验证过程保持一致

安卓、鸿蒙与 iOS 的工程结构、构建工具、模拟器、测试框架和设备接口本就不同。Mobile Use 不会以一套最低能力将三端强行对齐。现有开发环境可以继续使用,不必另行准备仅供 Agent 使用的测试设备。

image.png
image.png

安卓仍然通过 Emulator、ADB 与 Instrumentation 工作。鸿蒙可以连接 DevEco Previewer、HDC 与 ArkXTest。iOS 则使用 Xcode Simulator、Accessibility 与 XCTest。平台差异由各自的适配器处理。

上层通过统一的 Skill 与 CLI,将这些能力提供给 Agent。需要对齐的是更上一层的开发过程:观察、操作与验证。

若某一平台或运行环境不具备某项能力,Mobile Use 会明确说明,而不会以一条不等价的命令冒充成功。

ADB、HDC 与 simctl 仍然是三条不同的命令。Agent 在三端进入的,是同一套观察、操作与验证流程。

image.png
image.png

开发者使用 Canvas,Agent 使用 CLI,共用同一台设备

开发者通过 Canvas 查看应用运行状态,在界面上观察、标注并检查结果。Agent 通过确定性的 CLI 查询设备、观察界面、执行操作并运行验证。

image.png
image.png

两侧接入 Host 管理的同一条设备会话。 Host 负责设备生命周期:当前连接、运行状态、权限范围,以及证据的归属。

因此,Agent 不会在后台另行启动一台模拟器,也不会因注册大量 MCP 工具(即为 Agent 注册工具接口)而形成一套与开发者割裂的设备环境。 CLI 只是智能体进入现有能力的入口。设备本身、权限、状态与证据,仍由统一运行时管理。

随后执行的操作作用于同一条设备会话。截图、日志、录像与断言结果也关联到该会话。「这里有问题」可以连同圈选与当前画面,成为 Agent 继续定位、修改与验证的任务入口。

立即体验

Mobile Use 插件已在 Qoder 桌面端与 Qoder IDE 中上新。

  1. 1. 打开左下角的拓展或插件市场,搜索 Mobile Use,安装后重启。

  2. 2. 在对应工程中双击以打开 Canvas:安卓双击 **AndroidManifest.xml**,iOS 双击 **Package.swift**,鸿蒙双击 **build-profile.json5**。

  3. 3. 先连接模拟器或真机,将上文提示词发送给 Agent,并在 Canvas 上圈选需要验证的区域。

image.png
image.png

跳转微信打开

Harness 工程治理:从一次做成,到可复制、可运营的交付能力

2026年9月8日 18:00

phodal 2026-09-08 18:00 浙江

让 Agent 不只是“会完成一次编码任务”,而是逐渐成为一种可验证、可复制、可治理、可运营的交付能力。

在 Better Harness 中,我们构建了一套分析体系,用于理解 Agent 的执行过程及其所处的工程环境。对应的开源版本,也已经支持从十余种 Coding Agent 中读取并分析不同层级的本地数据。但随着开发者开始并行使用多个 Agent、维护多个项目,并在不同设备间切换,核心问题不仅仅是:如何将分散的数据汇总?

真正的问题是:如何将分布在不同 Agent、项目和机器上的执行数据串联起来,形成一条从需求到验证的完整任务链路?又如何让这套能力不仅帮助个人更好地完成任务,也帮助团队把方法复用,并最终支撑组织规模化地交付?

这也是我们正在尝试探索的方向:让 Agent 不只是“会完成一次编码任务”,而是逐渐成为一种可验证、可复制、可治理、可运营的交付能力。

为什么:Agent 的挑战正在从“单点做成”走向“规模运营”

在使用一个新的 Agent 的时,通常我们只关心一个问题:它能不能把眼前的任务完成?然而一次成功,并不等于形成了稳定能力,所以在构建 Agent Harness,我们需要构建持续丰富的测试集来评测。

同样的任务交给另一位开发者、另一个 Agent、另一个项目,或者换到另一台机器上,结果可能完全不同。与此同时,上下文、工具、权限、项目规范、Skill、MCP、模型和验收方式中的任何差异,都可能改变最终结果。

因此,Agent 能力要真正进入团队和组织,需要经历三个阶段:

image.png
  • • 单点做成关注的是:这一次任务需要怎样的上下文、知识和工具能力等,才能产生可靠的结果产物。

  • • 团队复制关注的是:一次成功中的哪些做法,可以沉淀为 Skill、模板、MCP 服务和质量规则。

  • • 规模运营关注的是:这些能力如何通过 Skill 市场、 MCP 网关、评测体系和模型网关,被安全地提供给更多团队。

这条路径对应三个逐步升级的问题,一次任务能力能不能做好,同类任务能不能稳定复用,成熟能力能不能安全、经济地规模化运行。

要回答这些问题,仅仅统计 Session 数量、Token 消耗或者工具调用次数是不够的,还需要建立围绕任务结果的采集与反馈机制,把 Skill 与 MCP 的执行过程、验收结果和资源消耗连接起来,再据此优化 Harness 资产、改进团队实践、补齐个人能力,最终降低完成一次合格任务所需要的整体成本。

关注点驱动:不同层级,需要不同的 Harness

随着 Builder 从个人走向团队和企业,Harness 解决的问题也随之变化:个人首先需要把一次 Agent 协作做好;团队需要让有效的方法稳定复用;企业则需要让成熟能力在安全与成本可控的前提下规模化运行。因此,Harness 的能力重点也应当分层设计。

image.png

个人:把一次 Agent 协作做好

今天,人人都可以成为 Builder,每天指挥多个 Agent 工作。对于个人而言,最直接的问题是:怎样让 Agent 一次把活干好?所以,我们需要:

  • • 先把任务说清楚,再让 Agent 动手:明确问题、改动范围、不做什么、交付物、验收方式和风险点,即我们的 spec 文档上的内容;如果 Agent 还无法准确理解完成条件,就不进入执行/实现阶段。

  • • 按任务准备上下文和工具:提供当前任务真正需要的项目说明、架构知识、领域知识和技能,只开放必要的目录、命令、工具与网络权限。

  • • 围绕真实产物与 Agent 协作:直接在代码 diff、网页或文档上标注、修改和验收,同时要求 Agent 给出验证结果(截图、测试等 )。

因此,个人视角关注的是能否还原一次任务从定义、执行到最终验收的完整过程。

团队:把个人经验变成稳定的工程实践

而对于来说团队,关注的层面就有所不同,更关注的是如何把个人经验变成稳定的工程实践?

  • • 让环境可以被 Agent 操作:搭建统一安装、启动、测试和调试方式,使 Agent 能快速进入验证阶段、复现问题,并在失败后恢复。诸如于通过 Npm、Gradle 之类的标准构建工具,定义好构建任务。

  • • 让规则可以被自动检查:为架构、安全、测试和视觉要求配置对应的检查机制与验收方式,让规则真正进入执行流程。诸如于,能通过 Playwright CLI、Agent Browser 访问环境,来进行视觉检查。

  • • 让任务经验可以被持续沉淀:关联需求、会话、文件变化、测试、提交和评审证据,将反复验证有效的做法沉淀为项目规范、Skill、脚本、Hook、任务模板或质量门禁。

团队视角关注的不是某一次任务偶然成功,而是能否通过统一环境、自动检查和 Harness 资产,把一类任务持续做稳。

组织:让 Agent 能力以可接受的成本规模化运行

当 Harness 进入多团队、多项目和多设备协作后,组织需要解决的,不再只是某个 Agent 是否完成任务,而是如何基于跨任务、跨团队的真实证据,持续治理和优化交付能力:

  • • 建立跨 Agent 的任务证据链:关联需求、任务定义、Agent 会话、上下文与工具使用、代码变更、验证结果、人工验收和后续缺陷,使一次交付能够被还原、追溯和复盘。

  • • 治理可复用的 Harness 能力:结合轨迹分析,将经验证有效的 Skill、MCP、Hook、规则和评测集版本化,并明确其适用任务、质量要求与维护责任,避免“能用一次”的经验被无边界扩散。

  • • 基于结果决定投入与推广:按任务类型持续比较不同 Harness 方案的验收通过率、人工介入、失败重试、返工、资源消耗和后续缺陷,判断哪些能力应推广、优化、收窄或停用。

组织视角关注的不是“Agent 看起来是否聪明”,也不只是单次调用成本,而是能否把分散的执行活动转化为可验证的交付证据,并据此以可控的质量、风险和成本持续扩大有效能力的覆盖范围。

Better Harness 的初步尝试:从执行数据走向任务反馈

前面讨论的个人协作、团队复用和企业运营,最终都依赖同一个前提:我们能否知道一次任务是如何完成的、最终产生了什么结果,以及其中哪些能力真正发挥了作用。一次完整任务并不只发生在 Agent 的对话窗口中,而是穿过四层相互连接的 Harness:

image.png

向下,组织和团队目标被转化为任务边界、验收条件、上下文、工具与规则,由 Agent 完成计划、执行、验证和恢复;向上,真实产物经过自动验证或人工验收后形成任务证据,并将反复验证有效的方法沉淀为 Skill、MCP、Hook、规则或任务模板,为团队复用和组织决策提供依据。

这也是 Better Harness Dashboard 想做的事情,尝试把分散的 Agent 执行记录转化为可观察的任务反馈,以降低人与 Agent 的摩擦,从而让组织减少 token/credits 的浪费,以放在更有价值的任务上。

目前,Dashboard 已能跨项目查看 Skill、MCP、模型、Token 和工具调用等活动,帮助个人和团队识别能力是否被使用、使用发生在哪些阶段,以及是否存在异常消耗或执行摩擦。

image.png

但“被调用”并不等于“有效”。下一步需要把这些活动与任务意图、验收条件、真实产物和人工验收连接起来,逐步回答:

  • • 任务是否真正通过验收?对应的 Edit 文件工具的调用,引发的提交是不是在对应的 release 版本中。

  • • Skill 和 MCP 是否用在了正确阶段?在  Skill、MCP 执行过程中有多少的调用失败、错误场景,应该要合理的统计进来,以便反馈给发布者进行改进,减少额外的 token 消耗。

  • • 哪些消耗没有转化为有效进展?是否存在消耗巨大的无效长程任务等。

  • • 哪些经验值得沉淀为团队 Harness 资产?诸如于在当前阶段 400k 的上下文能达到最好的成本和效果平衡等。

因此,Dashboard 不是最终目标,而是任务反馈的观察入口。现阶段最重要的,是先把执行活动与真实结果连接起来,为持续改进 Harness、降低合格任务的整体成本建立基础。后续,则可以结合这些经验和教训,将更多的最佳实践分享给更多的团队。

欢迎体验 Better Harness

Better Harness 当前仍在快速演进。你可以先在本地运行 Harness UI,看看它如何读取项目中的 Agent、Skill、MCP 和任务数据:

  1. git clone https://github.com/QoderAI/better-harness.git
  2. cd better-harness
  3. npm install
  4. npm run harness-ui:dev

访问 http://127.0.0.1:3410 查看 Dashboard。然后,一起探索一些有意思的话题:

  • • 连接 Session、任务历程、代码变更与交付结果,建立跨 Agent 的任务证据链。

  • • 从多个任务中识别可复用的工作模式,并沉淀为可追踪的 Harness Issue。

  • • 通过版本化组件、评测集和受控实验,验证 Skill、MCP 与规则等改动是否有效。

  • • 完善成本与路由评估、长期任务基准,以及不同 Agent 和操作系统的真实验证。

欢迎提交 Issue、贡献 Adapter,或参与 Better Harness 的设计与验证。

阅读原文

跳转微信打开

我做了一个 Lottie 插件:让动画可以被 Agent 持续编辑

2026年8月30日 18:05

原创 Phodal 2026-08-30 18:05 浙江

当动画已经生成以后,智能体怎样重新进入它,找到需要修改的对象,并在不破坏其他部分的前提下继续工作?

最近,我把 Lottie 插件的第一个版本 0.1.0 发布到了 Qoder Marketplace (从 https://qoder.com/marketplace?type=plugin 下载),它可以让智能体在 Qoder 中创建、编辑、打包、校验和预览 Lottie 动画。

从功能上看,这很容易被理解成另一个“AI 生成动画”的插件:用户描述一个加载效果,智能体生成一份 Lottie JSON,再通过播放器展示结果。

但真正把插件做完以后,我反而觉得,生成可能是其中最不重要的一步,因为一份动画只要进入真实的创作过程, 用户很快就会提出下一轮要求:让这个对象慢一点、让那段轨道提前出现,或者把循环接缝再处理得自然一些。

回头看,这个插件真正想解决的并不是“让智能体多生成一种文件”,而是另一个更接近创作过程的问题:

当动画已经生成以后,智能体怎样重新进入它,找到需要修改的对象,并在不破坏其他部分的前提下继续工作?

换句话说,我们需要的不是一个 Lottie 生成器,而是一套能够让动画被持续观察、定位、修改和验证的创作运行时,也就是:让 Lottie 成为 Agentic Loop 中的工作对象。

引子:生成产物之后,智能体如何重新进入一份动画?

在早期设计这个插件,主要还是延续复用之前的 Canvas 能力,以及 Codex 的启发

  • 在使用 Codex 的产物工具时,注意到它处理文档、演示文稿和表格的方式,并不是直接在对话里拼出最终文件,而是先编写一段程序,再由程序生成、检查和修改产物。

  • Codex 会把生成后的文件继续留在预览界面中,让人可以直接审阅、标注,再要求智能体完成下一轮修改。

文件不再只是对话结束时的附件,而开始成为协作过程的一部分。

但是,当工作对象从静态文档变成带有对象、轨道和时间轴的动画以后,仅仅把文件留在界面里还不够。

Lottie JSON 和 .lottie 很适合播放与分发,dotLottie 还可以在一个压缩容器中封装多份动画、图片、主题与状态机;Lottie Creator MCP 也已经证明,智能体可以读取动画文件、编辑图层并生成变体。真正没有被自然解决的,是智能体如何在连续多轮修改中继续引用同一个对象、同一条轨道和同一段时间。

当用户说“让左眼在 idle 阶段眨得慢一点”时,智能体需要的不是“画面左边那个眼睛”的屏幕坐标,而是一条能够在工程状态中重新解析的语义地址,以及这次修改所依赖的版本前提。地址负责回答“修改什么”,版本前提负责回答“现在面对的,是否仍然是刚才检查过的那一版”。

所以,可编程动画并不是“由代码生成的动画”。它更接近这样一种产物:

对象、轨道和时间状态拥有稳定身份,智能体可以基于明确版本持续修改,并通过验证确认修改范围的动画工程。

可持续编辑:在产物之外保留工程状态

如果动画只生成一次, .lottie 可以是终点;但只要它还会被人、另一个智能体或外部工具继续修改,问题就不再是文件能否打开, 而是系统能否重新识别同一对象、确认修改所基于的版本,并证明未触及的部分保持不变。

我们要做的不是保存所有对话,而是在产物之外保留可恢复的工程状态。 MotionProgram 表达期望变化, MotionProject 保存稳定身份与修订, MotionRuntime 负责计算差异、试运行、校验和提交, .lottie 只是某次提交后的交付结果;即使文件被外部修改,系统也应该先完成对象对账,而不是根据相似性自行猜测。

围绕这个目标,我们采用了三个相互衔接的实践:用 Agentic DSL 保留可重放的创作意图,用 CLI over MCP 稳定跨宿主的执行语义,再通过 Canvas 将人的视觉反馈重新转换为可寻址、可验证的工程状态。

Agentic DSL:用 JS API 表达完整的创作程序

设计 MotionProgram 时,我们没有重新发明一门动画脚本语言,而是选择把一套受到约束的 JS API 当作 Agentic DSL。

这里其实包含了一个很重要的判断:DSL 不一定需要重新设计语法。对于已经能够熟练编写 JavaScript 的智能体来说,变量、函数、循环、模块和组合能力都是现成的;我们真正需要重新设计的,是它能够表达什么、哪些对象必须拥有稳定身份,以及程序最终怎样被执行和验证。

因此,JavaScript 只是表达层, MotionProgram 的数据结构负责限定领域语义,真正的执行权限与状态变更则由 MotionRuntime 控制:

这里的关键并不是 JavaScript 本身,而是智能体提交的是一份完整程序,而不是一串散落在对话中的 createLayer、 updateTrack 和 exportFile 工具调用。

完整程序可以被检查、比较、试运行和重放;稳定键、随机种子和目标配置也可以成为程序的一部分。下一轮修改时,智能体重新生成完整的 MotionProgram,运行时计算前后差异,并证明除了指定对象、轨道和时间范围之外,其他内容没有被意外修改。

自然语言意图经过 Agentic DSL 与创作运行时生成动画

Vercel 在内部文本生成 SQL 智能体 d0 上删去了约 80% 的专用工具,转而让智能体通过文件系统和命令行探索已有语义层;后续实验又说明,Bash 并不适合所有任务。两次实践放在一起,真正值得关注的不是“工具越少越好”,也不是“Bash 可以替代一切”,而是智能体需要一个符合领域语义、可以组合、检查和验证的可编程环境。([Vercel][4])

对于 Lottie 来说,这个环境不是裸 Bash,也不是几十个原子工具,而是一份可以整体推演的动画程序。

CLI over MCP:先稳定运行时,再扩展协议入口

插件 0.1.0 没有一开始就把每一种动画操作包装成 MCP 工具,而是让 JS API 与 qoder-lottie CLI 共享同一套 MotionRuntime。对象身份、版本冲突、变更计划、验证和错误语义都在运行时中定义,CLI 只是把这些能力稳定地提供给智能体、自动化脚本和持续集成环境。

它并不是说 MCP 不重要,而是一种架构上的先后顺序:先让领域能力成为可以独立运行、调试、组合和复现的命令,再根据跨宿主发现、远程连接、权限控制和结构化工具描述的需要,为它增加 MCP 入口。

JS API、CLI 与 MCP 适配层共享同一套动画运行时

在这套分层里,MCP 负责连接,CLI 负责执行,真正的领域语义始终留在运行时。这样,无论能力最终被 Qoder、Codex、Claude Code、持续集成系统还是其他宿主调用,它们面对的都是同一套对象身份、事务边界与错误语义。

一项覆盖七种智能体脚手架、五个模型和一个固定软件任务的对照研究,也给出了一个很有意思的结果:13 组严格配对实验中的 MCP/CLI 成本比从 0.43 倍跨到 29 倍,主导差异的并不是接口形式,而是脚手架如何组织上下文、工具和执行过程。这个实验无法证明 CLI 普遍优于 MCP,却足以提醒我们,不应该在运行时语义还没有稳定之前,就把架构问题简化成协议选择。

Canvas 交互:让人的视觉选择回到语义地址

如果说运行时解决的是智能体怎样修改动画,那么 Canvas 解决的就是人怎样重新进入这份动画。

当前版本已经打通了从 MotionProgram 生成 .lottie、完成静态校验,再在 Qoder Canvas 中加载和播放的单向流程。验证器还可以进一步检查指定帧、场景状态和循环接缝,因为静态结构正确,并不意味着运动一定自然;一张截图看起来正常,也不意味着整段时序没有问题。

人与智能体围绕共享 Canvas 形成动画创作闭环

但是,Canvas 真正有价值的下一步,并不是增加更多播放按钮,而是把人的视觉选择重新转换成智能体可以理解的语义地址。

用户在画面中选择左眼,在时间轴上框出 idle 阶段,Canvas 将这次选择转换成对象、轨道、时间范围与当前工程修订,智能体再据此生成新的 MotionProgram,完成试运行、差异检查和重新预览。

到这一步,Canvas 就不再只是最终结果的预览器,而开始成为人与智能体共同操作产物的界面。人的视觉判断可以落回稳定对象,智能体的结构化修改也可以重新呈现为人能够观察的动画,两者围绕同一份工程状态不断循环。

小结:当动画不再只是文件,而成为可持续演化的产物

当一份动画拥有稳定身份、工程状态、版本约束和验证证据,并且人和智能体都可以重新进入同一份工作现场时,它才不再只是 Agent 的一次性输出,而真正成为 Agentic Loop 中可以持续演化的工作对象。

阅读原文

跳转微信打开

面向人机交互设计 Harness:构建以产物为中心的 Agent Loop

2026年8月23日 10:51

原创 Phodal 2026-08-23 10:51 浙江

当人与智能体共同面对的是一份会被持续修改、审阅和交付的工作产物时,我们还应该把对话当作人机交互的中心吗?

最近,我一直在 Better Harness 里思考编码智能体的工作闭环:用户究竟想完成什么,智能体读取了哪些上下文、执行了哪些操作, 结果有没有得到验证,以及这些过程中暴露出来的经验,能否继续沉淀为下一次任务可以复用的能力。

而随着现在的 Coding Agent 工作对象从代码不断扩展,从 API、网页到 PPT、Word、Notebook、3D 模型、动画等不同类型的产物。我们会发现: 它们面对的其实是同一个问题:智能体如何理解产物、修改产物、展示结果,并根据人的反馈继续下一轮工作。

这也让我开始重新思考一个问题:

当人与智能体共同面对的是一份会被持续修改、审阅和交付的工作产物时,我们还应该把对话当作人机交互的中心吗?

引子:从以对话为中心,到以产物为中心

今天的大多数智能体产品,仍然围绕对话来组织任务:用户输入一段需求,智能体读取上下文、调用工具、修改文件,再把执行过程和最终结果返回到对话中; 即使产品旁边已经放置了代码编辑器、终端、文件浏览器和预览窗口,对话记录仍然承担着保存目标、解释过程和串联上下文的主要职责。

Qoder 中的 Quest 对话示例

这种交互方式可以称为以对话为中心的智能体闭环。在这套模式里,对话既是任务入口,也是过程记录,还是智能体解释结果的主要载体。

在代码场景中,这种方式之所以还能成立,是因为任务的真实状态并不只存在于对话里,它同时存在于代码仓库、文件内容、符号关系、Git 差异、编译结果和测试报告中;即使智能体遗失了一部分对话上下文,它仍然可以重新读取项目,找到相关代码,运行测试,再次进入之前的环境。

但是,当工作对象变成 PPT、表格、架构图、移动设备或者三维场景之后,情况就开始不一样了。用户可能在两轮对话之间手工调整了一页幻灯片, 移动了一个节点,修改了几个单元格,或者在模拟器中切换到了另一个页面;

下一次交互开始时,智能体不能只回顾聊天记录, 还必须重新理解眼前这份已经发生变化的工作产物,以及用户刚刚通过直接操作表达出来、却未必被完整记录进对话中的意图。

换句话说,一旦人开始直接操作产物,对话就不再拥有完整的工作现场。

以产物为中心的 Agent Loop

因此,我更愿意把这种新的协作方式称为:

以产物为中心的智能体协作闭环,是人与智能体围绕同一份可持续演化的工作产物展开协作的过程;对话仍然负责表达目标和解释判断, 但真正承载工作现场的,不再只是对话,而是双方正在共同维护的产物及其状态。

这里所说的产物,可以是一段代码,也可以是一份演示文稿、一张架构图、一个工作簿、一个正在运行的设备界面,或者一个包含空间和物理状态的模拟世界。 它们的内部结构和运行方式并不相同,但都有一个共同点:

它们都不是一次生成之后便结束的文件,而是会被持续进入、修改、验证和审阅的工作对象。

从早的 PPT Agent 到 ChatGPT 中采用的 Agent 看到轨迹。上一个阶段的主流 Office Agent 更喜欢基于 HTML 来展示结果, PPTX 只是最后的导出物 —— 在过去的模型能力及交互形态有限的情况下,这种方式已经是最接近“产物中心”的实现了。

ChatGPT/Codex  的 PPT 示例

不过,在各类 GUI Agent 更完善之后,形态发生了一些变化。比如 Codex 基于自己的 Office 相关的 API/DSL 封装,以及可以直接生成、编辑 PPT,并 与 PPT 进行交互。

示例:以网页为核心的 Browser Agent 的闭环

浏览器智能体可能是最容易理解的例子。它之所以比“把网页截图发给模型”更进一步,是因为网页本身拥有浏览器运行时: 智能体既可以看到页面,也可以点击、输入、滚动和截图,还能够结合页面元素、控制台日志和网络请求理解操作前后的变化; 换句话说,网页不是智能体最后交付的一张图片,而是一个能够被不断观察、操作,再重新观察的工作环境。

Qoder 浏览器  Agent 示例

到了新一代 Coding Agent,这个闭环又向前走了一步:智能体不只是自己操作网页,人也开始直接通过网页向智能体表达意图。

以 Cursor、Qoder 的浏览器设计模式为例,用户可以直接选择运行中页面里的元素,通过绘制、语音或者文字补充修改要求, 而系统则把被选中的元素、背后的代码、周围布局和视觉关系一起交给智能体。

这里发生的变化其实很重要:产物本身开始承担上下文和指令入口的一部分职责。用户不再需要先把自己看到的问题翻译成一段完整的自然语言,再告诉智能体“我说的是哪个地方”。

示例:网页到可交互的 Canvas 形态

在诸如 Cursor/Qoder 的 Canvas 能力吧把这种方式进一步扩展到了智能体自己生成的工作产物。用户可以直接选择和批注画布里的界面元素, 让智能体根据这些局部反馈继续修改,也可以通过画布中嵌入的按钮直接触发后续动作。

IQoder IDE 对于 .dot 格式标注(Architecture Visulization 插件)

如上图的 Qoder IDE 对于 .dot 格式的标注示例。这里真正重要的,不是多了一个更漂亮的预览窗口, 而是用户不再需要把“我指的是哪里”重新翻译成文字,产物本身已经成为下一轮交互的入口。

当智能体把代码审查、测试报告、架构说明或者调研结果组织成可阅读、可筛选、可操作的界面时,Canvas 就不应该只是一次性的 HTML 输出,而应该进一步把团队对信息组织、证据呈现和下一步操作的经验带进产物;更重要的是, 画布中的结构化节点也可以成为后续行动的入口,使用户能够从某个风险、某段差异或者某项建议直接发起修复、解释或追问, 而不必重新回到聊天框里描述一遍上下文。

Browser Agent 和 Qoder Canvas 的实现方式并不相同,但它们共同体现了一种变化:智能体的交互界面正在从“对话中附带一个结果”,转向“人与智能体共同操作一份产物”。

如我们可以基于 Qoder Canvas / Cursor Canvas 来实现 3D 模型的可视化,并使用相同的标注分享等能力。

基于 3D 模型的 Canvas 示例

在这种模式里,语言仍然重要,但语言不再承担全部上下文;用户看到的对象、选中的区域、留下的批注、直接进行的修改以及最终作出的批准, 同样属于任务的一部分。

而问题也就自然地从“Canvas 应该长什么样”,进一步走向了另一个层次:如果产物本身开始成为人机协作的工作现场,那么 Harness 应该如何理解和维护这个现场?

Harness 如何成为人与智能体的协作环境

如果只是增加一个画布或者预览窗口,这种协作仍然很容易退回到“看图说话”。画布解决的是人如何直接进入产物,领域运行时解决的是 智能体如何理解和操作产物;而 Harness 要做的,则是把人的意图、智能体的操作和产物的变化连接成一个持续运行的闭环。

具体来说,它至少需要处理四件事情:

  • • 维护持续变化的任务意图。 不只记录最初的提示词,也要记录用户选中了什么、批注了什么、拒绝了什么,以及最终为什么接受结果。

  • • 让操作落在确定的产物版本上。 无论是网页元素、幻灯片中的图表,还是画布中的节点,每次选择、修改和验证都应该指向同一个版本和语义对象,避免智能体操作已经过期的截图、坐标或者内容。

  • • 让不同产物使用各自的运行时。 网页交给浏览器,代码交给代码仓库和构建系统,文档、表格、图表和模拟器也保留自己的结构、操作和验证方式。

  • • 保留可以被检查的验证证据。 智能体不能只说一句“已经完成”,Harness 还需要记录产物发生了什么变化、哪些结果已经验证、哪些仍然无法确认,并把这些信息交给人判断。

在 Better Harness 当前的产物模型里,一份产物因此也不再只是一个文件路径,而是一个带有明确版本、结构和展示方式的工作对象。 人的选择、智能体的修改以及后续验证,都应该落在同一个产物版本上,双方才真正是在面对同一份工作现场。

这也不意味着所有产物都要被塞进同一种画布。文档可以转换成带有结构和语义地址的数据快照,需要运行才能呈现的内容则可以经过受约束的构建和隔离预览。Harness 统一的是意图、版本、操作、回执和证据,而不是不同领域内部的模型。

其中最关键的是“人 ↔ 产物”:在传统的 Agent Loop 中,人主要通过提示词间接改变工作对象;而在以产物为中心的协作里,人和智能体都可以直接修改同一份产物。Harness 要维护的,正是这些操作背后的意图、版本和验证关系。

因此,面向产物的 Harness 不需要统一所有领域模型,而是统一协作方式,不统一领域实现 。目前的产物视图先解决版本绑定、结构理解和安全呈现;接下来再逐步连接选择、批注、写回、版本比较和验证证据,形成完整的以产物为中心的 Agent Loop。

总结:从单一闭环走向多元化闭环

从代码、网页到演示文稿、表格和模拟世界,不同产物都会形成各自的观察、操作和验证闭环。所谓多元化的 Agent Loop, 就是让不同产物拥有适合自己的协作方式,而 Harness 负责连接人的意图、智能体的操作与验证结果。

当对话不再是唯一中心,产物才真正成为人与智能体共同工作的地方。

阅读原文

跳转微信打开

AI 会生成 PPT 之后,Runtime 决定了它能做多好

2026年8月17日 07:58

原创 Phodal 2026-08-17 07:58 浙江

当 Agent 已经能够通过代码生成 PPT,我们真正缺少的还是更多 API 吗?

最近,我重新看了 remio 在 PPT DSL 上的尝试,也注意到 OpenAI 的 Artifact Tool(产物工具)正逐渐演进成一套完整的专业文档运行时。 这让我重新想到一个问题:

当 Agent 已经能够通过代码生成 PPT,我们真正缺少的还是更多 API 吗?

引子:PPT 已经可以被编程,为什么仍然不好用?

回头看最早的 PPT Agent,我觉得这里其实存在两个不同的问题:

  • • Agent 如何理解并持续操作一份专业文档

  • • 当底层能力已经足够丰富时,为什么 AI 生成的 PPT 仍然如此千篇一律

前者关乎产物(Artifact),后者则关乎表现力。

生成之后:Agent 如何重新进入一份 PPT?

年初还在 Thoughtworks 的时候,我做了一个 PPT Agent 原型,希望加速咨询师日常的复制、修改和排版。第一个版本借鉴了 ChatGPT.com 的 slide Skill,基于 PptxGenJS 和 python-pptx 实现,后来放在了 phodal/claude-code-codex-slide项目下。

真正做起来以后,我发现咨询师面对的通常不是一份空白 PPT,而是大量历史材料:找到合适的页面和对象,完成局部修改,同时保留原来的模板和布局。用户还会继续在 PowerPoint 中修改,之后又希望 Agent 能接着工作。

因此,PPT 不能只是 Agent 一次性生成的文件,它还需要成为一个能够被重新理解、定位和持续操作的 Artifact。

能力足够:为什么表达仍然千篇一律?

另一个问题则发生在生成这一侧。今天的大模型已经很会写 JavaScript,PptxGenJS 也几乎能够表达所有常见的 PPT 对象。 AI 做 PPT 早已不是“能不能画出来”的问题。

但生成得越多,就越容易发现结果不断收敛到三栏卡片、四宫格、左右分栏和时间线。底层 API 明明拥有巨大的能力空间,Agent 实际使用的却只是其中很小的一部分。

因为 Agent 真正需要表达的并不是 Shape 和坐标本身,而是观点的主次、数据中的异常、架构中的边界,以及背后的专业判断。

可编程解决的是“能不能做出来”,表现力解决的是“这个意图可以怎样被更好地表达”。

这实际上是 Runtime 演进的两个方向:先让产物变得可操作,再让操作本身变得更有表现力。前者解决 Agent 如何持续进入一份 PPT,后者解决 Agent 如何从巨大的能力空间中选择更合适的表达方式。我们先从第一步说起:从可编程文件到可操作的 Artifact。

API 让 PPT 可编程,Runtime 让 PPT 可持续操作

如果目标只是从零生成 PPT,PptxGenJS 已经足够好。Card、Grid、设计 Token、文本测量、图片裁切乃至碰撞检测,都可以继续封装成 JavaScript Helper。

但这些抽象主要服务于生成过程。一旦 PPT 被用户修改、数据发生变化,或者 Agent 需要在几天之后重新接管,真正困难的问题 就不再是“有没有一个 Helper 可以调用”,而是:

Agent 如何重新理解当前产物,并找到自己需要继续操作的对象?

产物运行时:让 Agent 持续理解和操作 PPT

Browser Use 是一个很好的参照。Playwright 早就可以 click() 和 fill(),但 Browser Agent 真正需要的是另一层能力: 它必须先看到当前页面,找到具体对象,对对象执行操作,再观察操作后的结果。

换句话说,Agent 面对的不再是一组孤立 API,而是一个可以反复进入的工作环境。我把这样的一层抽象称为 Artifact Runtime。

产物运行时(Artifact Runtime),是位于 Agent 与专业产物之间的一层运行时:它把原本只是输入或输出的产物,转换成 Agent 可以持续观察、定位、操作和验证的工作对象。

工作循环:观察、寻址、操作与验证

也就是说,这个实际工作的过程更接近一个循环:

Observe(观察),是让 Agent 理解产物当前是什么状态;Address(寻址),是让 Agent 能够定位并引用其中具体的对象;Operate(操作),是对这些对象执行局部操作,而不是重新生成整个产物; Verify(验证),则是在操作以后重新检查结果,再决定下一步做什么。

关键在 Address。它不只是"找到一个对象",而是让对象拥有可以被 Agent 稳定引用的身份。"第三页左边蓝色的框"不是好的寻址方式。Artifact Tool 里更接近真实工作方式的是:先 inspect 出一份带锚点的快照,再 resolve("sh/c3d4e5f6") 去改那个对象。

一次很普通的修改大概是这样:

  1. inspect({ search:"Revenue"})
  2. →{"kind":"textbox","id":"sh/c3d4e5f6","name":"headline","text":"Revenue outlook"}
  3. resolve("sh/c3d4e5f6").text.replace("Revenue","Revenue outlook")
  4. inspect({ target:{ id:"sh/c3d4e5f6"}})

Agent 先看到当前页,拿到 sh/c3d4e5f6 这个身份,改完标题后再检视一次。用户在 PowerPoint 里改过字、挪过框, 这份文件仍然可以被重新进入。文件不再只是 Agent 的输出,而开始成为工作循环的一部分。

这也是 Artifact Tool 真正往前走的一步:它不只是另一套 PPT API,而是让 Presentation 开始成为可以被反复观察和操作的产物。

而当对象已经可以被持续操作,新的问题也随之出现:对象之间的布局、关系和规则,是否还需要 Agent 每次重新计算?这也推动 Runtime 继续向上生长。

从可操作到可表达:Runtime 接管重复决策

到这里,Agent 已经可以重新进入一份 PPT,定位对象并完成局部修改。但如果新增一张指标卡之后,它仍要重新计算卡片宽度、间距、换行和标题高度, 那它只是从"一次性生成" 变成了 "反复编程"。

Runtime 的下一步不是增加更多原子 API,而是开始维护对象之间的关系。表现力不会因为多了几个 Helper 自动出现;它出现在 Agent 不用再把注意力耗在坐标上的时候。

布局语义:保存关系,而不是保存一次排版结果

在坐标模型中,“四张指标卡等宽排列”最终只会留下四组位置和尺寸。一旦卡片数量或文字长度变化,Agent 就需要重新排版。 布局语义保存的则是对象之间的关系:等宽、等距、对齐,以及空间不足时如何换行。Agent 选择表达方式,Runtime 负责重新求解布局。

Artifact Tool 的 Compose 已经把这件事做成了页面描述方式。 row、 column、 grid 描述结构, fill 和 hug 描述空间怎么分配:

  1. slide.compose(
  2. <row width="fill" gap={24}>
  3. <box width="fill" height="hug">ARR</box>
  4. <box width="fill" height="hug">NRR</box>
  5. <box width="fill" height="hug">Churn</box>
  6. <box width="fill" height="hug">Payback</box>
  7. </row>,
  8. { frame:{ left:72, top:160, width:1136, height:200}}
  9. )

这还不是表现力本身。四张等宽卡排得再稳,仍然可能是同一套模板。但 Agent 只有先从坐标里脱身,才有机会去想:这一页该强调异常,还是该画出边界。

领域语义:从通用形状到可复用的专业对象

grid 只知道对象如何排列,并不知道它们是一组指标卡; connector 只知道节点需要连接,并不知道这条线表达的是服务依赖还是演进路径。布局语义解决的是空间关系,还解决不了专业意图。

当这些结构反复出现以后,就可以进一步沉淀为领域对象。remio 走的是这一层:Agent 不再先写 Shape,而是先写"这是一组指标 / 一条演进 / 一个架构边界",再由 Runtime 展开成可编辑的 PPT 对象。Agent 决定新增什么指标、服务或阶段;Runtime 负责继承样式、调整布局、重排连接,并检查结果是否仍然可读。

  1. 专业意图
  2. ↓
  3. 领域对象与关系
  4. ↓
  5. 布局约束
  6. ↓
  7. 可编辑的 PPT 对象

这条演进可以概括成:坐标与形状 → 布局关系 → 领域对象 → 专业意图。每向上一层,Agent 需要维护的实现细节就少一些,Runtime 能够确定性完成的工作就多一些。

表现力也是在这一层才真正开始分叉。面对同一组数字,坐标层的 Agent 很容易继续生成四张卡;领域层的 Agent 才有机会说:这里该强调异常,而不是再铺一张对称网格。Runtime 不会替 Agent 做这个判断,但它决定了 Agent 是在 Shape 上做选择,还是在专业对象上做选择。

Runtime 的边界:接管工程复杂度,而不是替代专业判断

Runtime 并不是抽象得越高越好。对象寻址、布局求解和格式转换,可以交给系统;页面要表达什么、采用怎样的叙事结构,仍然需要 Agent 判断。 用户最终感受到的,只是修改以后布局是否稳定、模板能否保留,以及 Agent 能否继续接管。

Agent 负责专业判断,Runtime 负责把判断稳定地展开、修改和验证。

从可编程走向表现力,不是给 Agent 更多 API,而是让 Runtime 接管已经可以被工程化的复杂度。

阅读原文

跳转微信打开

Harness Inspector:让 Agent 交付过程可观察、可检查、可追溯

2026年8月14日 16:53

原创 Phodal 2026-08-14 16:53 浙江

Harness Inspector 是一个面向 Agent 交付过程的本地、只读工作台。它将需求、Agent Session、文件活动和 Git Commit 放在同一个交互界面中,用来检查一次软件变化为什么发生、怎样发生,以及最终留下了什么。

最近,我们一直在尝试优化 Better Harness 的 SKILL 自动沉淀能力:从 Agent 的真实会话中识别重复出现的工作路径,再判断其中哪些经验值得进一步沉淀成可复用的 SKILL。真正做起来以后,我们发现这件事远比“把一段 Session 分析一遍”复杂得多。

对于一次软件开发任务来说,Agent 的行为并不是孤立发生的。它从一个需求或者用户故事开始,经过对需求的理解、上下文探索、代码修改和验证,最终才形成一次可以被评审的代码贡献。只看中间的 Session,我们能看到 Agent 做了什么,却很难判断这些行为为什么发生,又有哪些行为真正进入了最后的交付。

因此,我们开始把一次 Agent 的交付理解成一条连续的链路。现在,只需要在项目目录执行:

  1. npx @qoder-ai/better-harness inspector

就可以生成一个本地、只读的 Harness Inspector 页面,把当前项目中的 Agent Session、文件活动和 Git Commit 放到同一个交互界面里。

GitHub:https://github.com/QoderAI/better-harness

从 Session 到一次完整的交付过程

Harness Inspector 最初只是一个会话调试工具:帮助我们查看 Agent 说了什么、调用了哪些工具,以及修改了哪些文件。但随着 Session、文件活动和 Git 历史逐渐被连接起来,我们发现,真正需要观察的并不是会话本身,而是:

一次软件变更如何从一个意图出发,经过 Agent 的执行,最终形成可以进入工程系统的产出。

Session 只是这条链路的中间部分。

从意图到产出的交付链

我们将一次 Coding Agent 的交付拆成三个连续、但边界不同的部分:

意图、过程与产出构成一条从需求到提交的交付链
  • • 意图(Intent) 是一次变化的语义化起点,例如用户的需求、Issue、Spec 或者架构约束。

  • • 过程(Process) 体现的是这次变化真正发生的过程,对于 Agent 来说,主要体现为 Session 记录以及其中的搜索、读取、修改和验证。

  • • 产出(Output) 则是 Agent 交付到工程系统的最终结果,现阶段最清晰的锚点就是代码 Commit。

所以,Story、Session 和 Commit 并不是三个并列的抽象概念,它们分别是 Intent、Process 和 Output 在当前软件开发工具链中的可观察对象(意图在不同场景下也可能表现为 Issue 或 Spec)。Harness Inspector 要做的,也不是把一段对话展示得更完整,而是重新建立这条从需求到提交、可以追溯的交付链路。

从叙述上看,它是一条连续的交付链;但在真实项目中,它更接近一张证据图。一个 Story 可能经历多个 Session,一段 Session 也可能涉及多个 Commit。

一个简单的示例:从 Story 到 Commit

我们在 Better Harness 文档页创建了一个只读的公开样本(英文示例数据,不读取本地内容):https://qoderai.github.io/better-harness/inspector。

只看 Session,我们只能看到它是一串搜索、读取、修改和测试活动,很难确定它是否一直围绕最初的需求展开,也不知道其中哪些修改真正进入了代码库。单独看 Commit,我们虽然可以看到最终修改了哪些文件,却无法知道 Agent 在提交之前如何理解问题、建立上下文和完成验证。

当 Story、Session 和 Commit 被放到同一个界面后,这次变化才成为一段相对完整的交付过程:Story 说明为什么要修改,Session 展示修改是怎样发生的,Commit 则记录最后留下了什么。

把需求、Agent 行为和代码提交连接起来,让我们第一次能够从整体上检查一次交付。但真正打开一些包含数百次 Tool Call 的真实 Session 后,另一个问题很快出现了:能够把一次交付连接起来,并不意味着我们已经能够读懂它。

Harness Inspector 如何读懂一次 Agent 交付?

围绕 Better Harness 的 Harness 模型,我们将 Harness Inspector 定义为:

Harness Inspector 是一个面向 Agent 交付过程的本地、只读工作台。它将需求、Agent Session、文件活动和 Git Commit 放在同一个交互界面中,用来检查一次软件变化为什么发生、怎样发生,以及最终留下了什么。

Harness Inspector 以一次完整交付为中心,围绕从需求到提交的链路,提供了三种观察方式:

  • • Workbench:查看需求、Session 与 Commit 之间的关系;

  • • Trace:查看 Session 内部的工作结构;

  • • Replay:按照事件顺序重新观察任务如何展开。

简单来说,Workbench 看关系,Trace 看结构,Replay 看顺序。三者共同帮助我们还原一个需求如何经过 Agent 的理解、探索、修改和验证,最终形成一次可以被评审的代码提交。

Workbench:连接需求、过程与产出

Workbench 是一次交付的整体视图。在左侧,我们可以看到触发这段 Session 的用户需求,以及执行过程中对目标的补充和调整;中间展示 Agent 在 Session 中发生的搜索、读取、工具调用和 Git 操作;右侧则是当前范围内观察到的 Commit,以及它最终修改的文件。

它关注的不是简单地把数据放在一起,而是展示需求、过程和产出之间已经观察到的关系。关系证据不足时,Inspector 会继续把它保留为候选或未映射,而不是自动拼出一条看起来完整的交付路径。

Trace:把 Session 读成一条工作轨迹

Workbench 帮助我们找到一次交付,Trace 则进一步展开其中的 Session。

进入 Session 后,Trace 会按照 Turn 组织用户输入、中间回复、Tool Call 和文件活动,并通过顶部的时间轴连接事件在时间上的位置。点击某个区段可以跳转到对应调用,连续重复的活动也会被折叠,避免大量相似操作淹没真正重要的变化。

Trace 按 Turn 组织用户输入、中间回复、Tool Call 和文件活动

Trace 并不试图还原模型没有暴露的思考过程,而是将已经记录下来的行为重新组织成一条可以阅读的工作轨迹,帮助我们检查 Agent 如何搜索上下文、修改代码和执行验证。

Replay:沿事件顺序回看一次交付

Replay 则沿着已经保留的事件逐步回看任务如何展开。Reviewer 可以依次查看用户输入、Agent 回复、Tool Call、文件和 Commit,观察 Agent 在什么上下文中形成方向,又在什么时候进行了修改和验证。

它只是一次只读的证据回放,不会重新运行工具、恢复工作区或者继续原来的 Session;没有精确时间的内容,也只保留顺序,不会补充没有被记录的过程。

Workbench 建立交付上下文,Trace 展开 Session 的工作轨迹,Replay 补充事件发生的顺序。三者共同把一次从需求到提交的 Agent 交付,变成可以逐层进入和检查的过程。当我们真正把一次交付读清楚之后,就可以回到最初的问题:这条轨迹里,哪些经验真正值得留下来。

从交付证据到 SKILL 沉淀

当一次交付能够被看清之后,我们才能重新回到最初的问题:Session 中的哪些经验,真正值得沉淀成 SKILL?

答案显然不是出现次数最多的 Tool Call。Agent 可能因为上下文不足而反复读取同一个文件,也可能因为命令失败不断重试;这些行为虽然频繁出现,却更可能是一次交付中的噪声,而不是值得复用的工程经验。

真正值得沉淀的,通常是一条能够在相似任务中重复出现,并且得到最终产出与验证结果支持的工作路径。例如,Agent 如何从需求中确定修改边界,如何建立必要的上下文,又如何完成修改、执行验证并检查最终结果。只有把这些行为放回对应的 Story、Session 和 Commit 中,我们才能判断它们是当前任务中的偶然选择,还是一套相对稳定、可以迁移到其他任务中的工作方式。

因此,SKILL 自动沉淀并不是将一段 Session 总结成新的 SKILL.md,而是从多次真实交付中识别稳定模式,再为它补充适用场景、上下文边界、执行步骤和验证方式。Inspector 当前解决的,正是这一过程最基础的一环:先让真实交付留下边界清晰、可以检查的证据。只有在此基础上,我们才可能进一步比较相似任务,形成 SKILL 候选,并在后续交付中验证它是否真的改善了 Agent 的工作方式。

结语:先看清交付,再沉淀经验

我们最初想解决的是,如何从 Agent Session 中识别可复用的工作路径。但真正分析之后会发现,Session 只能记录 Agent 做了什么,却无法单独解释任务为什么开始,也不能证明哪些行为最终形成了工程产出。

Harness Inspector 将需求、Session、文件活动和 Git Commit 重新连接起来,让一次 Agent 交付变得可以观察、检查和追溯。只有先看清一次交付,我们才可能判断哪些行为只是偶然选择,哪些路径值得进一步沉淀成 SKILL。

从 Session 到交付,再从交付中沉淀经验,这正是 SKILL 自动演进的起点。

阅读原文

跳转微信打开

Agent 插件工程化:如何让 Skill 可验证、可维护、可演进

2026年8月9日 14:11

原创 Phodal 2026-08-09 14:11 浙江

将把一项能力写进 SKILL.md,再封装成 Agent 插件,并不难。真正困难的是,当它被不同用户、不同项目和不同 Agent宿主反复调用之后,如何保证它仍能被正确触发、执行和验证,并证明一次修改带来的是改善,而不是退化。

将把一项能力写进 SKILL.md,再封装成 Agent 插件,并不难。真正困难的是,当它被不同用户、不同项目和不同 Agent 宿主反复调用之后,如何保证它仍能被正确触发、执行和验证,并证明一次修改带来的是改善,而不是退化。

本文结合 Better Harness 的开发实践,从规格驱动、上下文编排、确定性验证、行为评测和证据闭环五个方面,讨论如何把 Agent 插件中的能力从“写出来能用”,逐渐变成可验证、可维护、可持续演进的软件资产。

引子:从 Agent 插件说起

在加入 Qoder 的这三个月里,除了设计基于 Canvas 的 Agentic UI 体系,我另外一项持续投入的工作,是构建 Agent 插件生态。从筛选社区里已有的软件工程流程插件,到创建 Architecture Visualization、Design Review 等插件,我们尝试把原本分散在不同角色、不同工具里的能力,封装成 Agent 可以发现和调用的能力。

例如在 Architecture Visualization 插件中,Agent 可以直接通过 Canvas 可视化架构模块之间的依赖关系,并分享给团队成员,帮助他们理解系统结构:

一开始,插件更像是对 Agent 能力边界的扩展:缺什么能力,就补一个 Skill、一个工具或者一段工作流。但随着插件越来越多、越来越复杂,我们开始遇到另一个问题:

这些能力应该如何被长期维护?

特别是在构建 Better Harness 的过程中,这个问题变得越来越明显。Better Harness 面向 Coding Agent 的工作流分析与持续改进,其中包含一个核心 Skill、大量 JavaScript 脚本、参考资料、评测逻辑,以及不同 Agent 宿主的适配。

当这些能力真正作为插件的一部分被长期维护之后,我们发现,问题已经不再只是“怎么写好一个 SKILL.md”。

Agent Plugin 到底是什么?

如果你已经熟悉 Agent Plugin 和 Agent Skills,可以直接跳到下一节。

简单来说,Agent Plugin 是能力的交付与分发边界,Skill 是其中可以被 Agent 独立发现和执行的能力单元。一个典型的 Plugin 可以同时包含 Skill、MCP Server、Hook,以及针对不同 Agent 宿主的扩展:

  1. my-plugin/
  2. ├── plugin.json
  3. ├── skills/
  4. │└── summarize/
  5. │├── SKILL.md
  6. │├── scripts/
  7. │└── references/
  8. ├── mcp.json
  9. └── com.example.client/
  10. └── hooks/

其中, SKILL.md 并不是插件本身,而更像插件中的一个能力入口。它描述这个能力什么时候应该被发现、如何执行,以及需要继续读取哪些资料和工具。如果 Skill 只是自己偶尔使用的 Prompt,这种区别并不重要;但一旦它进入 Plugin,被不同用户、不同项目和不同 Agent 宿主反复调用,事情就不一样了。

为什么插件需要工程化?

在个人使用阶段,写清任务和步骤通常就够了;但当一个插件被不同用户、不同项目、不同 Agent 宿主反复调用之后,一系列更接近软件工程的问题就会自然出现:

  • • 行为契约:它应该怎么工作? 什么场景应该触发,什么场景不应该触发;需要哪些上下文,可以调用哪些工具,又有哪些行为必须禁止?

  • • 变更验证:修改之后还是对的吗? Skill、脚本或参考资料发生变化之后,如何确认原有能力没有被破坏,已经修复的问题不会再次出现?

  • • 环境兼容:换个环境还能工作吗? 当模型、Agent、宿主乃至运行环境发生变化时,这套能力是否仍然能够被发现、加载和正确执行?

  • • 效果评估:它真的让 Agent 变好了吗? 即使 Skill 被正确触发并完整执行,我们又如何证明,相比不使用 Skill,它确实改善了真实任务的结果?

这些问题已经很难通过“把 Prompt 写得更详细”来解决。它们对应的其实都是软件工程中非常熟悉的问题:*定义契约、验证变更、管理兼容性,以及评估真实效果 *。继续往下拆,才会进一步涉及规格、知识与依赖组织、接口和权限边界、自动化测试、回归验证,以及跨模型、跨宿主的行为评测。

也正是在 Better Harness 的开发过程中,我们逐渐开始用另一种方式理解 Skill:

Skill 一旦从个人 Prompt 进入插件生态,它面对的问题就越来越像软件,而不是提示词。

下面结合 Better Harness 的实践,依次展开这五个工程环节。

一、规格驱动:把 Agent 行为写成可验证契约

规格驱动(Spec-driven)是我们在 Better Harness 中最早开始实践的部分。它的核心思想是:在实现之前,先把“什么时候做、做什么、做到什么程度”写成可验证的契约。 

我们在 AGENTS.md 中约定:

只要 Skill、脚本、模板、宿主适配或评审工作流发生会影响实际行为的变化,就要先建立规格和可追踪的验收条件。

一份规格至少要回答几个问题:什么请求应该触发,哪些相似请求不应该触发;需要读取什么信息,允许调用哪些工具;哪些行为明确禁止;证据不足时应该停止、降级,还是交回给人;最终又用什么证据证明这次实现符合预期。

每条验收条件还应该有稳定编号,例如 AC-01、 AC-02 ,并分别对应实现、测试和评审证据。一份边界加固规格 就把已经复现的问题拆成 AC-01 到 AC-09。

例如,Agent 扫描写入内容时不能回显密钥;分析某个 workspace 时,不能顺手把其他目录的会话也算进来;无法确认 Git 基线时,应明确停止,而不是把失败伪装成“没有变更”。最后再由 AC-09 收口到完整测试与打包验证。

规格本身也需要评审。在 Better Harness 的 triangulate-spec-review Skill 中,我们会让至少两个、通常三个评审 Agent 在相同上下文下,分别检查实现复杂度、使用便利性和长期演进。主评审 Agent(Lead Agent)负责合并同类问题、核对证据和修改文档,其他评审 Agent 只提供独立判断,不直接改文件。规格驱动的价值,就是先把这些模糊从运行时搬到设计时。

不过,规格驱动也有边界。验收条件写得过细时,AI 很容易把测试变成对 Skill 文本的逐字匹配,而不是验证真实行为,反而降低测试稳定性。因此,规格应该约束可观察行为,而不是锁死具体措辞。

规格定义了能力应该怎样工作,下一步则是让 Agent 在执行时准确找到支撑这些行为的知识。

二、上下文编排:让 Skill 知识在需要时准确抵达

Agent Skill 通常采用渐进式披露:知识不应该一次性全部进入上下文,而应按任务需要逐步展开。

宿主先读取 name 和 description 完成发现,决定使用后才加载完整的 SKILL.md,更细的资料则按任务需要进入上下文。它本质上是一种面向 Agent 的上下文工程:不是把所有知识一次性塞给模型,而是设计知识何时出现、从哪里进入,以及如何被继续追踪。

对应到目录结构上,入口应该保持短:

  1. my-skill/
  2. ├── SKILL.md          # 触发条件、主流程、停止条件
  3. ├── references/# 按需读取的判断规则
  4. ├── scripts/# 可重复执行的确定性逻辑
  5. └── assets/# 模板与交付骨架

SKILL.md 负责触发、路由和停止条件;详细判断放进 references/;稳定执行的逻辑放进 scripts/;模板与交付骨架放进 assets/。

但在 Better Harness 的实践中,我们发现,仅仅把知识拆开放置还不够:文件存在,不代表 Agent 找得到;入口曾经引用过,也不代表重构之后路径仍然有效。

所以,我们主要从三个方面保证知识路由:

  • • 可发现:通过 SKILL.md 的入口和明确引用,把相关资料纳入 Agent 的知识路径,而不是依赖它临时搜索。

  • • 可到达:通过自动测试 检查相对链接是否有效,以及 Skill 所需资料是否真正被入口路由。

  • • 可追踪:通过文档图生成器从真实 Markdown 引用生成 Mermaid 图,并验证生成结果是否与当前引用关系一致。

这样,Markdown 引用本身成为事实来源,图只是知识路由的一种可验证投影。文档移动、链接断裂或路由关系发生变化时,可以由机器及时发现,而不是依赖维护者人工同步。

上下文编排的目标,不是让 Agent 读得更多,而是让正确的知识在正确的时机,通过仍然有效的路径进入上下文。知识准确抵达之后,下一个问题是:哪些边界应该交给程序直接判断,而不是继续让模型猜。

三、确定性验证:把能判断的交给程序

在 Skill 和插件里,并不是所有问题都应该交给模型判断。关键词、正则和程序检查适合处理边界明确、结果可判定的问题,例如元数据、目录结构、断链、数据格式、废弃名称和权限声明;但它们不能证明 Agent 是否理解了任务,也不能替代语义质量评审。

在 Better Harness 中,我们主要用三层确定性机制守住这些边界:

  • • 静态检查(Lint):检查文件头、目录结构、断链、数据格式和权限声明,尽早发现低成本、可确定的问题。

  • • 单元测试(Unit Test):验证脚本、解析器和模板转换等确定性逻辑,保证基础能力在修改之后仍然成立。

  • • 契约测试(Contract Test):验证命令和入口真正允许发生什么,包括输入输出、错误状态、产物位置,以及副作用边界。

一个比较典型的例子,是 Better Harness 对 --help 路径的测试。 better-harness-cli.test.mjs 不只是检查帮助信息是否正确,而是进一步验证:执行帮助命令时,不应该读取工作区、写入文件、等待标准输入、启动子进程或访问网络。只要其中任何一种副作用发生,测试就会失败。

这里真正被验证的,不是“帮助文案长什么样”,而是这个入口被允许做什么、不允许做什么 。这也是确定性验证的价值:把原本容易被模型行为掩盖的边界,变成可以自动检查、持续回归的工程约束。在 Agent 系统里,模型更适合理解、规划和权衡,确定性程序则更适合验证、约束和拒绝。

能被程序明确判定的,就不要交给模型猜;需要语义判断的,也不要硬塞进字符串断言。

不过,确定性验证只能守住可判定边界,无法证明 Agent 在真实任务中真的照做。这就需要进入行为评测。

四、行为评测:验证 Agent 是否真正照做

Skill 存在、被发现、被加载、被执行、最终带来改善,是几件不同的事。静态检查通过,只能说明文件和脚本没有明显问题;Agent 会不会在正确的时候选择 Skill、执行关键步骤,并在证据不足时停下来,仍然需要行为评测。

在 Better Harness 中,我们通常准备三类场景:应该触发的正例、不应该触发的负例,以及措辞相似但意图不同的边界用例 。执行过程中重点观察四件事:

  • • 选择:该用时有没有用,不该用时有没有误触发;

  • • 上下文:有没有读取真正需要的资料;

  • • 执行:关键步骤、工具和权限是否符合约束;

  • • 结果:最终产物能否通过独立验证。

同一个场景还需要重复运行,因为一次成功只能证明“这次跑通了”,不能证明行为足够稳定。

到了宿主边界,Better Harness 还会通过真实 Qoder CLI 和插件加载链路做端到端验证,并从中立目录发起测试:

  1. python3 <skill-creator-root>/scripts/quick_validate.py <skill-dir>
  2. qodercli --cwd <neutral-dir>--plugin-dir <plugin-root>-p "<forward-test-prompt>"
  3. qodercli plugin validate <plugin-root>

从 neutral-dir 发起测试,是为了避免 Agent 意外借用当前仓库中的配置、上下文或未声明依赖,让“能跑通”显得比真实情况更乐观。与此同时, qodercli 的回答只属于模型行为证据,最终是否通过,仍然由本地校验器、产物检查和 Git 状态等确定性证据决定。

模拟用例负责覆盖异常和边界场景,真实宿主测试则验证 Plugin 加载、Skill 发现、资料读取、工具调用到最终交付这条链路是否真的连通。 行为评测真正要证明的,不是 Agent “看过” Skill,而是 Skill 要求的关键行为确实发生了。

但证明 Agent 确实执行了 Skill,仍不等于证明这个 Skill 带来了更好的结果。后者需要进入证据闭环。

五、证据闭环:先证明 Skill 有效,再谈自我演进

行为评测回答的是“Agent 有没有照做”,证据闭环进一步回答:面对同样的任务,使用这个 Skill 之后,Agent 是否真的做得更好?

在 Better Harness 中,我们把它设计成一套评测执行协议 。在任务、模型、工具、权限和测试环境保持一致时,进行三组对照:无 Skill / 当前版本 Skill / 候选版本 Skill。

评测不只看最终成功率,还要观察关键步骤是否执行、验证是否完整、时间与 Token 成本,以及有没有额外副作用。否则,一个看起来“更好”的 Skill,可能只是用了更多权限或资源。

这里尤其要防止一种“假使用”:Agent 找到了 Skill,也读取了 SKILL.md,但并没有真正执行其中要求的步骤。Better Harness 将这种情况称为“ 已经路由,但没有真正执行”( routed-but-not-applied)。

因此,我们会沿着一条证据链继续判断:

  • • 存在吗? Skill 和相关机制是否存在;

  • • 找得到吗? 真实任务能否发现并选择它;

  • • 执行了吗? 要求的关键步骤是否真正发生;

  • • 有效吗? 相比不使用 Skill,结果是否确实改善。

在 Agent Work Loop 中,这对应“已存在 → 已接入 → 已执行 → 有效果证据”( Present→Wired→Exercised→Outcome-supported)。核心原则只有一个:证据走到哪一步,结论就只能说到哪一步。

这也和近期 Skill 评测研究的方向一致:SkillsBench 关注同一任务下使用与不使用 Skill 的结果差异,Skill Coverage 则进一步检查 Skill 中要求的行为是否真的出现在执行轨迹里。前者回答“结果有没有变好”,后者回答“过程有没有真正发生”。

结果改善和过程覆盖,两种证据缺一不可。 只有这条证据链建立起来之后,自我演进才有意义。否则,Trace2Skill、EvoSkill、CoEvoSkills 或 SkillOpt,都可能只是帮助 Agent 更快地产生更多未经验证的 Skill。

Skill 的演进,不应该从“生成更多经验”开始,而应该从“证明这次修改确实让下一次做得更好”开始。

结语

Agent 插件工程的核心,不是把 Skill 写得更复杂,而是把插件中的能力当作软件资产来维护:用规格约束行为,用上下文编排知识,用确定性验证守住边界, 用行为评测确认执行,再用对照证据判断效果。

当这些机制能够共同工作时,一个插件才真正从“写出来能用”,走向“可验证、可维护、可持续演进”。

阅读原文

跳转微信打开

别再反复教 Coding Agent:让项目记住自己如何工作的五个步骤

2026年8月2日 12:47

原创 Phodal 2026-08-02 12:47 浙江

所谓持续改进,不是不断增加配置,而是让这一次任务留下的东西,真正帮助下一次。

最近我重新整理 Better Harness ( https://github.com/QoderAI/better-harness )的 references 目录时。其核心我们是整理了一系列 AI Coding 的最佳实践,以让 AI 在调用这个 plugin 的时候写出有价值的修复建议。

过程中,发现一个有意思的问题:里面积累的实践越来越完整,但第一次接触 Coding Agent 工程化的人,反而更难判断应该先做什么。

如果你已经让 Coding Agent 修改过真实项目,大概见过这样的场景:它能很快找到代码、完成修改,甚至运行测试;但换一次对话,又要重新猜测项目使用什么命令、 哪些文档可信、哪些文件不能修改。你不断补充 Prompt,项目里的经验却没有真正留下来。放回 AI Coding 项目的成长过程,顺序其实很清楚,要添加的内容很也简单

阶段

要解决的问题

主要产物

进入项目

Agent 不知道怎样开工

AGENTS.md

理解项目

文档存在,但任务中找不到

知识路由

复用经验

同类流程需要反复解释

Skill

执行流程

方法有了,却缺少可靠工具

CLI、MCP、Hook

持续改进

这次经验没有进入下一次任务

Agent Work Loop

一个 Agent 友好的项目,不是安装了多少工具,而是项目知识能否被发现,流程能否被执行,结果能否被验证,经验能否进入下一次任务。

第一步:先用 AGENTS.md 给 Agent 一张项目地图

假设一个新人第一天加入项目,我们通常不会直接递给他全部架构文档,而会先告诉他:项目做什么、代码在哪里、怎样启动、修改后运行什么测试,以及哪些地方不要碰。

Coding Agent 进入仓库时,也需要这样一张地图。这是 AGENTS.md 最容易理解的用途。

不同 Coding Agent 对文件名和加载范围的支持有所不同,但 AGENTS.md 承担的内容应该尽量稳定:项目使用的包管理器和运行时、安装与测试命令、无法从目录结构推断的约定、生成文件的位置,以及涉及凭据、数据库迁移和发布时的安全边界。

Agent 能从代码中看出来的内容,没有必要再写一遍。真正值得写进去的,是它看不出来、却很容易猜错的事实。例如:

  • • 仓库里同时存在 npm 和 pnpm 的痕迹,当前究竟使用哪一个;

  • • 某个目录看起来像源码,实际上由工具生成;

  • • 完整测试需要半小时,修改一个模块时应该先运行哪条聚焦命令。

如果还不知道怎样起步,可以先在仓库根目录创建一份很短的 AGENTS.md:

  1. # AGENTS.md
  2. -安装依赖:`pnpm install`
  3. -修改后先运行:`pnpm test -- <相关测试>`
  4. -不要直接修改:`dist/`、`generated/`
  5. -修改模块边界前:阅读`docs/ARCHITECTURE.md`
  6. -涉及数据库迁移或发布:先请求人工确认

这只是最小示意,命令和路径必须替换为项目中真实可用的内容,并且亲自运行一遍。

一份实用的 AGENTS.md 应该简短、准确、可执行,并且与当前项目直接相关。AGENTS.md Review 还强调了一个重要原则:渐进式披露。根目录只保留多数任务都需要的说明,更详细的架构、设计和工作流程,通过链接按需读取。

第一步不必追求一份完美的 Agent 手册。先写清入口、命令、风险和文档导航,让 Agent 能够正确进入项目。

第二步:把核心文档接到任务路径上

有了项目地图,Agent 只是知道怎样开工,还不知道代码为什么这样组织。真正影响修改质量的知识,仍然散落在架构决策、设计规范、测试策略和运行手册中。

第二步要做的,是让这些文档从“仓库里存在”,变成“任务进行到这里时能够被找到”。

常见的核心文档包括 ARCHITECTURE.md、 DESIGN.md、编码规范、测试指南、发布说明和 Runbook。名字不必统一,但职责应该清楚:架构文档解释模块边界和依赖方向,设计文档保存界面与交互约束,编码规范记录团队特有的技术选择,测试与运行手册说明如何验证和诊断系统。

只在 AGENTS.md 末尾放一串链接还不够。更有效的写法,是同时给出读取条件:

  • • 修改模块边界前,阅读 ARCHITECTURE.md;

  • • 调整公共界面前,检查 DESIGN.md;

  • • 改变发布流程前,阅读 Runbook。

这一小句把文档接到了具体任务上,也形成了一条最小的知识路由。架构约束属于架构文档, AGENTS.md 只负责把 Agent 带过去;测试命令如果已经由脚本提供,文档负责解释如何选择,而不是再复制一份可能过期的命令。

到了这一步, AGENTS.md 负责导航,核心文档负责解释,源码和测试提供最终事实。项目开始拥有一套 Agent 可以使用的知识路由,而不再依赖一个巨大的万能 Prompt。

第三步:从重复工作中提炼第一个 Skill

文档适合解释稳定知识,但有些任务不只是“知道什么”,还包含一套反复出现的判断和步骤。

每次发布都要检查版本、变更记录和产物;每次排查线上问题都要收集日志、缩小范围并验证修复;每次代码审查都要核对最终变更、测试证据和风险边界。如果团队每次都要重新提醒 Agent,这段过程就值得被观察。

Skill 可以理解为一份由 Agent 按需加载的工作手册。它回答的是一种任务应该怎样完成:何时触发、需要哪些输入、按什么顺序执行、产出什么结果、如何验证,以及遇到什么情况应该停止并交给人。

但重复出现,不等于立即创建 Skill。一个实用的 Skill 探索门槛是:相似需求至少出现过两次;或者虽然只发生过一次,但成本高、风险大,并且很可能再次发生。在此基础上,还要确认输入相对稳定、步骤能够复用、结果可以检查,而且没有被现有文档、脚本或 Skill 覆盖。

如果不知道第一个 Skill 应该从哪里来,可以翻看最近几次与 Agent 的对话:

  • • 哪些要求已经解释过两次?

  • • 哪些检查每次都要手工提醒?

  • • 哪些失败修复以后很可能再次出现?

它们通常比一张通用的 Skill 推荐清单更值得优先处理。

例如,团队连续几次在代码审查中遇到同一类问题:Agent 只检查了未暂存的修改;测试运行在较早的代码上,最终提交又发生了变化;总结写着“测试通过”,却没有记录具体命令。与其继续往 AGENTS.md 增加提醒,不如把“审查最终变更”整理成一个 Skill,固定收集变更范围、运行对应检查、记录验证证据,并列出尚未覆盖的风险。

第四步:把重复流程变成可执行的工程接口

写出 Skill,只是定义了方法。要让流程真正运行起来,Agent 还需要读取数据、执行检查或操作外部系统。

这时不必立刻增加一个 MCP Server。对于已经拥有脚本或命令行工具的项目,CLI 通常是成本最低、也最容易复现的起点。一个友好的 Agent CLI 应该:

  • • 能从 --help 中发现用法;

  • • 支持非交互执行;

  • • 输出稳定,必要时提供 JSON 等结构化格式;

  • • 失败时返回明确的错误和退出状态;

  • • 为耗时操作提供超时;

  • • 修改外部状态前支持 plan 或 dry-run。

这样的 CLI 可以同时服务开发者、Agent、脚本和 CI,也容易在本地复现 Agent 的操作。团队已经使用 gh、 kubectl 或内部运维 CLI 时,优先把这些能力整理成稳定接口,通常比为每个 Agent 宿主重新包装一套工具更轻。

CLI 优先并不意味着拒绝 MCP。当外部系统缺少合适的命令行入口,或者需要结构化资源发现、宿主集成、持续交互时,MCP 仍然合适。关键是让 CLI 与 MCP 建立在同一套底层能力和权限规则上,而不是分别定义输入、输出和错误语义。

此外,并不是所有问题都应该由 Skill 提醒。能够被程序明确判断的规则,例如禁止修改生成文件,应该交给脚本、Hook 或 CI 自动检查;涉及生产环境、凭据和不可逆操作,则继续保留权限控制、沙箱或人工确认。

第五步:回到真实任务,让项目记住经验

Agent 完成修改、测试显示通过时,我们很容易马上开始下一个需求。先别急着结束:打开最终代码变更,确认测试覆盖的是这次修改后的版本,再检查它是否走完了必要的 Review 和 CI。代码写完只是过程的一部分,结果能够被验证和交付,这次任务才算完成。

Better Harness 把从理解需求、找到知识、执行修改到验证交付的过程,称为 Agent Work Loop 。在这个循环中, AGENTS.md 帮助 Agent 进入项目,核心文档提供上下文,Skill 与工具推动任务执行,测试、Hook 和权限守住结果与边界。

交付以后,再回头看一眼这次任务:Agent 是否又重新寻找了一遍启动命令?是否在同一个目录上再次犯错?是否仍然需要人提醒某项检查?也要留意那些已经奏效的路径,例如某个排查步骤是否连续帮助了几次任务。

这些反复出现的摩擦和有效经验,才是下一轮改进的起点。可以借助 Loop Discovery ,判断它们应该沉淀在哪里:

  • • 稳定事实,写回 AGENTS.md 或核心文档;

  • • 重复方法,整理成 Skill;

  • • 确定性的操作和检查,交给 CLI、脚本、Hook 或 CI;

  • • 确实需要外部资源发现或持续交互时,再使用 MCP;

  • • 高风险、不可逆的操作,保留权限边界和人工确认。

不过,写进仓库并不代表实践已经生效。等下一次类似任务到来,Agent 能否找到它、用上它,并因此少一次返工或提醒,才决定这项实践是否值得保留。

总结

所谓持续改进,不是不断增加配置,而是让这一次任务留下的东西,真正帮助下一次。

如果刚刚开始,就选择一个最近发生的真实任务:让 Agent 从理解需求走到验证与交付,结束时只沉淀一件最值得复用的经验。

项目不需要在第一天就拥有完整的 Agent 平台。它只需要开始记得自己如何工作。

当这个循环转起来,AI Coding 才不再只是个人临时使用的聪明工具,而会逐渐成为项目自身拥有的工程能力。

详细实践文档可以参考:https://github.com/QoderAI/better-harness/tree/main/references/agent-customize

阅读原文

跳转微信打开

Better Harness 开源了:立即把 Harness 专家带进你的 AI Coding 工具

2026年7月28日 21:28

Phodal 2026-07-28 21:28 浙江

Better Harness 是一套面向 Coding Agent 工作流的开源分析与持续改进工具,将 Harness Engineering 与 Loop Engineering 的工程实践、评估模型和运行能力连接起来,并适配 Claude Code、Codex、Qoder 和 Cursor。

上周,我们在 Qoder Desktop 中内置了 Better Harness。上线后,很多用户都在问:这个功能会开源吗?

答案是:会!

今天,我们正式开源 Better Harness。

项目地址:

https://github.com/QoderAI/better-harness

Better Harness 是一套面向 Coding Agent 工作流的开源分析与持续改进工具,将 Harness Engineering 与 Loop Engineering 的工程实践、评估模型和运行能力连接起来,并适配 Claude Code、Codex、Qoder 和 Cursor。

四个平台共享同一套判断模型,但会话分析、证据覆盖和输出能力尚未完全对齐。其中,Qoder 已在真实开发工作流中反复验证,是当前能力最完整的参考实现。

图片
图片

完成对应平台的安装或加载后,都可以在要分析的项目中执行:

/better-harness

你可以先让它跑起来,边看报告,边继续读这篇文章。如果某类证据不可用,Better Harness 会在结果中保留这个边界,而不会用配置数量或其他平台的数据替代它。

Better Harness 关心的是 Agent 在任务中做了什么

假设 Agent 修改了一个模块,运行一条测试命令后便宣布任务完成。真正需要判断的,不是仓库“有没有测试”,而是这条测试是否与改动相关、是否覆盖主要风险,以及结果能否支持交付。

Better Harness 因此不会把 AGENTS.md、Rules、Skills、MCP、Hooks、Memory、测试或 CI 的存在,当成它们已经在任务中发挥作用。每条待优化项(Finding)都需要给出可追溯的证据、具体的用户影响、最小修复边界,以及修复后的验证方式。

下面是 Better Harness 在 Codex 中对自身项目进行的一次分析快照:

图片

图中没有把“缺少 Codex 宿主测试”直接写成“Codex 已经失败”,而是保留未执行宿主测试的证据边界。分数只帮助定位问题,真正重要的是结论、影响、最小修复范围和验证方式。

这也是 Better Harness 与配置清单的区别:配置清单告诉你项目拥有什么;Better Harness 关注这些能力是否真正支持 Agent 完成了一次可信的任务。

而要让报告中的判断能够被检查、修改和重新验证,开源就不能只停留在一个可执行入口。

Better Harness 的三层开源体系

如果只是把 /better-harness 的 Prompt 放到 GitHub 上,它当然也可以被称为开源。

但对 Coding Agent 来说,真正决定结果的从来不是某一句提示词,而是提示词背后的整套工作方式:什么值得检查,什么证据才算数,怎样形成判断,以及这些判断如何在真实项目中持续运行和修正。

图片

因此,这次 Better Harness 开放的是三层彼此连接的内容。

第一层是 Harness Engineering 最佳实践

它回答的是:面对 Session、CLI、可观测性、Rules、Skills、MCP、Memory、Hooks 和自动化,我们应该检查什么,又有哪些结论不能仅凭配置存在就得出。

这些知识按照问题领域被组织在 references 中:

图片

Better Harness 不会在每次运行时加载一个无限膨胀的总 Prompt,而是根据当前发现的问题,读取对应领域的判断依据。遇到诊断问题时进入可观测性实践,遇到 Skill 问题时进入 Skill Review,发现重复流程时再判断它是否应该由 Skill、Hook、Script 或 Automation 长期承载。

第二层:Agent Work Loop 评估模型

它负责把工程实践转化为可以逐项检查的问题,并约束证据、评分与结论之间的关系。当前模型和证据状态定义公开在 Agent Work Loop 中。

鉴于标准尚未成熟,我们避免让单个模型主观定义 “好的Harness”。首轮内部评测选取 30 个 GitHub 真实项目,由四类模型基于 OpenAI 的 Harness Engineering 文章独立评估,生成 120 份标准化报告;随后通过跨模型对比和人工校准,明确证据要求、判断边界及项目类型差异,并应用更新准则对全部项目重新评估。

图片

这条“自动评测—自动汇总—人工校准—自动复跑”的闭环,帮助我们得到第一个可复现、可持续调整的 Harness Engineering 评估模型。

第一版模型仍然更接近传统的软件工程成熟度扫描,关注项目是否拥有文档、测试、CI 和安全机制。但我们很快发现,静态资产不能证明 Agent 真正完成过一次任务。

为了持续追踪模型与项目能力的变化,我们采用 Spec 驱动的方式建设 Better Harness。随着 200 多份 Spec 的积累,模型逐渐从关注“仓库里有什么”,转向判断“任务中实际发生了什么”。

评估对象由仓库或会话,收敛为一个具体的任务;会话不再是评估对象,而只是承载证据的容器。模型也逐步稳定为五个维度:任务理解、可控执行、改动验证、可靠交付和经验沉淀。文件存在、配置数量、时间相邻,甚至一次命令成功,都不能再被直接推导为某项能力已经真正生效。

最终,Agent Work Loop 不再是一张静态评分表,而是一套围绕真实任务、能够复现并持续校准的判断系统。

第三层:可运行的工程实现

它负责让前两层不只停留在文档和模型中,而是能够在真实项目里重复运行。Better Harness 通过插件或 CLI(项目中的 scripts 目录下的 JavaScript 代码) 启动一次分析,先冻结任务范围,再分别采集三类证据:

  • • Session Evidence 还原 Agent 在真实任务中的行为;

  • • Project Harness 检查项目是否可启动、可诊断、可验证和可恢复;

  • • Agent Customize 检查 Rules、Skills、MCP、Memory 和 Hooks 的配置、路由与使用证据。

三类证据在采集和分析阶段保持独立,最终才由 Lead 结合 References 中的判断依据和 Agent Work Loop 评估模型进行综合判断。因为“项目拥有一项能力”和“Agent 在任务中真正使用了它”,始终是两个不同的事实。

图片

最终输出的不只是一个分数,而是一组带有证据边界、用户影响、修复范围和验证方式的 Findings。报告经过渲染和校验后,可以继续进入修复流程;如果发现稳定的重复工作,则通过 Loop Engineering 判断它应该由 Skill、Hook、Script、Automation 或其他机制长期承载。

修复完成也不等于流程已经改善。只有在后续同类任务中再次观察到更好的结果,改进闭环才真正成立。

现在,从第一条可验证的问题开始

Qoder 用户

Qoder Desktop 已内置 Better Harness,更新到最新版即可,打开 Quest 视窗选择 Better Harness(Beta),或者直接运行 /better-harness。Qoder CLI 和 JetBrains 插件在装过 Qoder Desktop 的机器上同样直接可用。

开源仓库

访问 Better Harness 的 GitHub 仓库 (https://github.com/QoderAI/better-harness)

按照 README 安装并运行第一次 /better-harness。诸如 Claude Code 用户可以依次执行:

  1. /plugin marketplace add QoderAI/better-harness
  2. /plugin install better-harness@better-harness

然后运行:

/better-harness 分析我项目的Harness情况,生成 HTML 报告

第一次运行 Better Harness,不必立即构建一套完整的 Agent 工程体系,也不必追求满分。更实际的方式,是先找到一个证据明确、影响具体,并且能够快速验证的问题。

它可能是一条 Agent 找不到的检查命令,一段无法提供下一步诊断路径的错误日志,也可能是一个已经存在、却从未进入任务路由的 Skill。

修复一个问题,重新运行检查,再观察后续相似任务是否发生变化。Harness Engineering 不是一次性的配置工作,而是持续让项目更容易被 Agent 理解、执行和验证。

图片

欢迎来给 Better Harness 贡献

Better Harness 已经在 Qoder 的真实研发流程里反复运行和校准过,但当前模型主要来自我们熟悉的项目类型和任务场景。

面对不同的技术栈、工程规模、团队约束和 Coding Agent,它仍然可能存在判断盲区,也需要更多真实证据来持续修正。

如果你愿意参与,可以从以下几个方面贡献:

  • • 补工程实践:往 references/ 里加一份某个语言、框架或者常见工作流的判断依据。不用写代码。

  • • 补评估视角:往 models/ 或 scripts/ 里加一个有证据支撑的检查维度或检测器,带上 fixture 和测试。

  • • 补宿主支持:为另一个 Coding Agent 补齐证据采集与验证,仓库的 Roadmap 里有现成的 to-do 清单。

  • • 补真实案例:往 case-studies/ 里贡献一个脱敏的团队实践例子。

如果你不认同报告里的某一条 Finding,也热烈欢迎直接开 issue。对我们来说,一条来自真实项目的反驳,比一个 star 有用得多(当然也欢迎顺手点个 Star 😁)。

项目地址:

https://github.com/QoderAI/better-harness

阅读原文

跳转微信打开

❌