For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/zh/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/zh/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/zh/guide/development/index.md.
  • 简体中文
  • 开发循环

    开发只有一个入口,以及三个证据表面。入口是 agent-bundle dev —— 一个前台、仅绑定 loopback 的 服务器,它随输入变化重建产物。三个表面分别是开发者 Workbench、测试 harness 与 eval 运行器。

    npx agent-bundle dev --root .

    重建循环

    dev 会准备项目源码、构建产物,并把它发布为一个 epoch:由 epochId 标识的不可变世代。任何读取 已构建产物的表面——Workbench 产物树、一个 MCP 会话、一次钩子模拟、一个开发期宿主安装——都会指明自己 读取的是哪个 epoch,因此会话进行中的一次重建绝不会悄悄改变某个结果所证明的对象。

    重建是防抖且串行的。构建成功会发布一个 artifact.available 事件;构建失败则什么都不发布,因此 先前发布的 epoch 保持原样。不存在只发布了一半的世代。

    当项目声明了 bin/lib 条目时,同一个串行流程也会重建 dist/ 包构建。该构建有自己基于 provenance 的增量边界:一次成功之后,每个输出文件的排序后源输入会被保留下来,除非以下情况之一发生,下一次重建 就会被跳过:某个被记录的输入失效、配置文件或 package.jsontsconfig.json 发生变化、规范化后的 bin/lib 声明或 tools 逃生舱发生变化、这次失效是手动或初始触发的,或者上一次包构建失败了。 一个新增文件如果改变了模块解析却没有触及任何被记录的输入,会在下一次被记录的变化时才被捡起,而不是 立即生效。

    包构建失败绝不会让已经提交的产物 epoch 失效。它会作为一条 AB7103 警告出现在那次成功的构建 尝试上,并在下一次失效时重试。

    开发期还会从同一份编译后的路由图,把生成的路由声明发布到 .agent-bundle/routes.d.ts。每次写入都先 写入一个同级临时文件,再原子地重命名覆盖先前那份完整声明,因此无效源码会保留上一份可用文件,而一次 成功的、不含路由的准备过程会移除它。

    三个表面

    表面它是什么它证明什么
    开发者 Workbenchdev 提供的 loopback 界面:诊断、Skill、产物 provenance、MCP 与钩子 playground、Playground 轨迹、eval 运行。它自身不证明任何东西——它是你查看演练真实生成输出的地方。
    测试agent-bundle/rstestagent-bundle/test,以及框架自有的契约矩阵。可复核的证明级别,从路由模块渲染,一直到从已安装宿主布局中启动的捆绑包。
    评测通过确定性、Claude 或 Codex harness 运行的带类型 eval 套件。智能体是否真的抵达了你的插件,并以 pass / fail / inconclusive 与声明的最低证据门槛报告。

    能构建的插件不等于能工作的插件,而以上三者回答的是不同的问题。它们互不替代。

    本章的边界

    编写表面——Skill、钩子、MCP 路由、脚本或包入口是什么——在编写中。把一份 已校验的产物变成宿主能安装的东西,在分发中。精确的命令行标志、配置字段 语义与运行时契约在参考中。