Skip to content

内置插件开发参考 ​

文档导航 · 扩展方式选择

本页面向维护随包插件的开发者。插件统一随 @wenext/pi 构建、发布;原生 Pi extensions 的安装与注册机制保持不变。

职责与现有边界 ​

  • workflows/default/:默认节点/模型绑定、角色、上下文提示、计划产物与默认路由要求、完成要求及默认插件组合。
  • runtime/task/lifecycle.ts:校验完成转换的任务状态,并调用传入的工作流策略。现有 domain/workflow.ts 是选择默认工作流的兼容入口。
  • runtime/plugins/:manifest 解码、依赖校验与确定性装配。
  • plugins/:具体能力,生命周期、节点、路由与领域动作扩展。
  • adapters/pi/host.ts:通过统一组合入口加载插件和可信工具能力;不逐个导入插件工厂。

质量插件已消费 Execution/Scope/Evidence/Task 服务,其余旧工厂仍保留 context.legacy.layout 适配桥。新的插件优先消费 context.services。这些是内部契约,当前还不是对第三方承诺稳定的插件 SDK。同进程插件不是安全沙箱。

添加一个内置插件 ​

新增 src/plugins/<id>/plugin.json 与入口文件即可;无需修改宿主或手工编辑生成表。允许现有的嵌套目录,例如 quality/command/。

json
{
  "id": "client-check",
  "apiVersion": 1,
  "entry": "index.ts",
  "order": 60,
  "requires": ["runtime.project", "runtime.events"],
  "provides": ["client.checks"],
  "tools": { "client_inspect": "read_only" }
}
ts
import type { BuiltinPluginContext } from "../../runtime/plugins/api.js";

export function createPlugin({ services }: BuiltinPluginContext) {
  return {
    id: "client-check",
    projectOpen(context: { sessionId: string }) {
      services.events.record({
        sessionId: context.sessionId,
        kind: "client_plugin_ready",
        payload: { root: services.project.root },
      });
    },
  };
}

npm run typecheck 与 npm run build 都扫描可信源码目录,验证声明并生成 src/plugins/builtins.generated.ts。该生成文件保留在源码中,随 manifest 同步;编译产物中的静态表包含加载所需信息,安装后不扫描仓库 TS。构建拒绝符号链接、缺失入口、非法 ID/API 版本、重复能力提供者、缺失依赖与循环依赖。

requires/provides 当前描述能力依赖和执行顺序;不自动注入任意名字的服务实现。默认宿主注入 project.root、workflow.planReviewEnabled、events.record、execution(request)、scope.capture(...)、evidence.begin/finish/verify、tasks.directory(name)。对应运行能力为 runtime.execution/runtime.scope/runtime.evidence/runtime.tasks。现有 legacy.task-layout 是内置适配桥,后续由专用服务替代。

发现与启用 ​

上例中的 client-check 是需要自行实现的插件示例,不是现成可用插件。新插件被构建发现后不会自动启用。在 .agents/rules/workflow.json 显式选择:

json
{
  "schemaVersion": 1,
  "plugins": { "enable": ["client-check"], "disable": [] },
  "quality": { "schemaVersion": 2, "checks": [] }
}

enable 为默认组合之外的插件 ID,disable 移除可选插件。同一个 ID 不能同时启用和禁用。默认工作流所需的 planning/git-evidence/change-scope/quality-command 不允许被仓库配置关闭;缺依赖会明确报错,不静默跳过检查。

先按依赖拓扑排序,再以 order 和 ID 确定同层顺序。核心插件按 10/20/30/100 运行;可选调试在 40。调试需要显式启用;若旧任务仍引用未启用的插件会阻断恢复并提示恢复依赖,不能删除旧义务。组合和工具能力在宿主创建时固定;修改选择后需要重启宿主,不热加载代码。插件的 projectOpen 可保留轻量初始化;昂贵的测试工具准备使用 prepareChecks(context)。宿主先依据实际范围选择检查,只调用拥有适用检查的插件,再冻结贡献的 checks。prepareChecks 可解析命令路径,但不能改变检查 ID、条件或适用性。完成初始化后保持命令稳定;未映射影响在初始化前阻断。质量运行在执行前固定检查计划,并绑定插件 ID、版本、顺序与声明摘要。内置插件版本还包括 Pi 包版本;程序化插件应显式提供 version。

生命周期与贡献点 ​

入口用途
projectOpen、taskCreated轻量项目初始化与任务初始化
beforePlanApproval、beforeWrite返回 {ok:true} 或 {ok:false,reason} 的门禁;Shell 不走 beforeWrite
checks、prepareChecks声明检查;仅在贡献的检查适用时解析工具,不能在准备阶段执行测试
checkRun自定义质量执行;普通工具优先用声明式 checks,以保留统一重试和失败关闭语义
afterCheck消费真实检查后的领域状态
checkObserved启用指标时的检查观测,失败不阻断任务
beforeFinish、afterFinish完成前门禁与完成后观察;afterFinish 不能撤销已经完成的任务
nodes、routes、actions贡献节点、路由与 wenext_plugin 动作
beforeRoute、enterNode、context校验领域前置条件、初始化节点、提供指导
shutdown释放插件托管资源

LifecycleContext 提供当前 root、sessionId、可选 task/directoryName、取消信号、通知与进度接口。confirmExternal 请求真实 UI 决策,参数本身不代表批准。插件需保留请求开始时的归属,避免异步结果绑定到后来切换的任务。

扩展工具执行与输出路径 ​

工具实际实现继续通过 Pi 原生 extension 注册。当前停用“没有可信只读声明就拦截”的默认策略,不新增开关。Figma、浏览器、MCP 等未声明的扩展调用可直接交给执行器,认证与操作权限由工具及其执行环境处理;这不代表工具被认定为只读。生命周期插件 manifest 的 tools 和嵌入宿主的 toolCapabilities 仍兼容现有显式声明。

声明审批前行为
read_only可检查;显式输出到项目/状态目录仍按写入处理
research_output无输出参数时可检查;当前任务 research 输出需要启动任务;项目输出需要实施授权;项目与 Pi 状态目录以外的输出交执行器
mutating任务启动且获得绑定范围的 policy 或 human 授权后执行
未声明默认归为 extension,不因缺声明要求任务批准;显式输出到项目或 Pi 状态目录仍检查目标路径,当前任务 research 输出只需启动任务

受控输出字段为 outputDir/output_dir/outDir/out_dir/destination/dest。未声明扩展与只读/研究扩展均可在任务启动后输出到当前任务 research;混合输出到项目源码仍需实施授权。输入里的 readOnlyHint 不改变分类,也不能覆盖显式 mutating 声明。这里的路径检查仅覆盖上述显式参数,并不是扩展的文件系统沙箱。

原生 write/edit 的研究输出例外只限当前任务。即使已批准,也不能通过直接文件工具写其它任务的 research、task.json、运行状态或规范配置;路径穿越与指向其它任务的符号链接不能获得研究输出权限。

父会话 bash/powershell 统一归为 shell,直接交原生执行器,不分析命令名称、Git 参数、管道、重定向或替换语法。 不将其标为 read_only,也不调用 beforeWrite、计划审批或 scope.begin 来预检命令;无需单独的 mkdir 例外。 该路径不提供写入租约、控制面路径围栏或 OS 隔离;scope 查询、原生写入前与完成时仍复核观察范围内的变更。 独立只读子会话仍使用受限工具集;父会话的扩展默认放行不向子会话注入工具。

规则与旧入口兼容 ​

原 domain/roles.ts 和 resources/built-in-context.ts 继续导出相同名称。full/lightweight 用于旧任务兼容;新任务使用路由快照。

.agents/rules 存在非空 Markdown 或根级 stages.json 时优先;空目录、空 Markdown、只有 workflow.json、被忽略的 node_modules/cache 等不会遮蔽 .wenext-spec/spec。规则发现与上下文遍历共用忽略目录定义,均不跟随嵌套符号链接。

领域 stage 的 when/required/output 声明进入默认上下文。记录阶段时要求实际产物;完成时核验必需阶段的任务、声明、运行和产物摘要。自由文本 when 不作为跳过 required 的依据。旧标记需要重新记录,不能视为已执行领域验收。

发布与接口边界 ​

内置插件随 Pi 发布,新增目录仍需构建并发布新版本。通用执行与证据服务见质量协议,会话与只读子智能体分别见会话和并行运行。这些都是包内接口;独立 npm/用户目录动态加载和完整客户端 Host API 尚未提供。

声明通用质量检查 ​

插件返回对象可包含 version 与 checks: CheckDefinition[]。仓库声明和插件声明统一经过冻结、执行、证据及完成核验;同名 check 拒绝,最多 16 个。插件无需复制通用执行循环,也不得自行把失败结果改成不适用。

ts
return {
  id: "client-check",
  version: "1",
  checks: [{ id: "client-tests", command: ["cargo", "test"], required: true }],
};

正确:领域插件提供命令、适用条件、报告契约,基座管理执行和完成。 错误:插件创建另一插件工厂来刷新质量文件,或直接写任务完成状态。

普通领域工具通过 rules 声明命令即可,无需业务仓库实现插件。插件贡献 checks 可沿用重试和失败关闭;自定义 checkRun 尚无跳过/重放契约,因此其存在会阻止 failed/blocked 关闭。新增独立工具不要求 Pi 适配包名。具体职责和零案例限制见独立工具接入。

默认计划审查 ​

planning 插件消费 runtime/review 的真实审查证据,默认风险规则位于 workflows/default/plan-review.ts。旧自填 verdict 不再满足新宿主批准;插件不能自行授予人工批准。workflow.planReviewEnabled 表示强制独立审查,false 仍执行风险选择,完整接口见 方案审查契约。

可选 Web 质量插件 ​

quality-web 在仓库显式启用且首次选中 business-tests 时查询和更新 test-tool,贡献 business-tests 的 run/verify;默认服务端工作流不安装前端工具。更新策略、独立缓存、会话版本固定和失败恢复见 Web 质量插件契约。基座只提供生命周期、通知和通用质量执行服务。

节点、路由与领域流程 ​

LifecyclePlugin.nodes/routes/actions 贡献可信入口、默认路由和 wenext_plugin 动作;宿主验证启用情况并绑定当前任务。enterNode 处理入口初始化,beforeRoute 校验已有领域前置条件,context 输出下一步,afterCheck 消费真实检查证据,shutdown 清理托管进程。节点模型可由用户 nodes.json / CLI 覆盖,业务仓不提供模型 ID。

finishGate: "archive" 只在归档审计领域完成条件,避免评测必须先 check、check 又要求评测完成的死锁。未声明时保留旧检查/归档行为。归档只调用一次 beforeFinish;复用检查时不得伪造新的 afterCheck。

legacyTaskFields 用于识别旧任务依赖;legacyDefault 保留为兼容 manifest 字段,不再因缺少 routing 自动启用领域插件。任务保存的插件状态或路由提供者不可因禁用插件而忽略。领域数据不能覆盖任务生命周期、授权或质量真值。具体调试流程见 任务路由与调试契约。