扩展设计
本页说明如何让不同项目复用 Wenext-Pi,以及新增能力应放在哪一层。文件路径为兼容已有链接保留,内容描述当前扩展边界,不是实施排期。
选择接入方式
| 需求 | 首选方式 | 是否修改并发布 Pi |
|---|---|---|
| 补充编码规范、领域知识或操作说明 | 项目 AGENTS、Rules、技能 | 否 |
| 修改本项目路由的适用描述、产物或验证目标 | workflow.json.routing 与 planning.json | 否,不能降低核心授权要求 |
| 运行已有测试、构建、审计或校验工具 | workflow.json.quality.checks | 否 |
| 为单次任务添加验证 | wenext_check.checks | 否 |
| 准备项目依赖或检查环境 | workflow.json.preparation | 否 |
| 增加智能体工具、交互命令或 UI | Pi 原生 extension | 遵循 Pi 扩展机制 |
| 增加可复用的路由、生命周期、检查提供者或领域完成条件 | 随包构建的内置插件 | 是 |
| 嵌入新的 IDE、Web 或桌面宿主 | 需要宿主 API 与交互协议设计 | 当前没有稳定客户端 SDK |
先使用声明式检查。只有需要持久领域流程、托管资源、专属动作或共享检查提供者时,才增加生命周期插件。项目不必为了运行一个测试命令实现插件。
普通工具协议
工具接收基座生成的公开 request 文件和输出目录,负责领域判断;基座负责进程、取消、证据、重试和完成。工具无需导入 Pi、读取私有任务文件或自行上报一套重复任务状态。
- argv 以独立参数传入,不使用隐式 Shell 展开。
- 输出
resultFile时,schema 1 的verdict为passed或failed;退出码与领域结果都参与判断。 - 找不到应有测试、缺失场景或框架不支持,应由工具报告失败或阻塞,不能让空执行伪装成通过。
- 工具可独立使用;Pi 的
requireVerified证明有适用检查通过,不能理解任意工具内部的用例完整性。
生命周期插件
可信插件位于 src/plugins/,由 manifest 和入口组成,构建生成静态注册表。运行时校验依赖和启用状态,固定本次组合。项目只能选择已随包发布的插件,不能把任意项目 TypeScript 标为可信代码。
插件可贡献:
- 生命周期处理与轻量项目初始化。
- 检查声明及选中检查后的工具准备。
- 节点、路由、领域动作与上下文指导。
- 领域状态和归档条件。
插件通过 context.services 访问通用执行、范围、证据和事件服务。它不能伪造人工批准、删除失败记录、直接完成任务或依赖另一插件的私有文件格式。组合、工具能力与质量计划共同绑定证据。详见插件开发参考。
领域流程示例
quality-web 管理 Web 测试工具的发现、安装和报告解释;quality-command 保持语言无关。只在 business-tests 适用时准备工具,使文档任务避免承担业务测试环境的成本。
debug 管理复现、归因、独立结论、Nous 评测、禅道来源和飞书反馈。业务脚本仍由项目提供,启用集成不等于安装这些依赖。基座只理解插件动作、执行结果和完成条件。领域流程改变时主要修改调试插件;超出现有运行能力的需求仍可能需要演进基座接口。
服务端、客户端和游戏项目可先声明自身命令;通用 CLI 可启动不代表所有领域工具链已经适配。需要新的领域语义时,按同样边界设计插件,并用真实目标工具验证。
配置与兼容
新任务冻结路由与规划契约,已有任务使用原快照。插件组合在宿主启动时固定,调整后需重启;任务引用的插件缺失时明确阻断,不能通过禁用插件免除历史义务。命令、版本或检查声明变化使旧质量证据失效。
接口增加字段时保留版本与兼容策略。协议、领域报告、插件版本与任务状态分别演进;不要用一个发布版本隐含改变所有历史数据的含义。迁移与恢复须保留原始状态和失败事实。
尚未提供的扩展能力
- 第三方 npm/用户目录生命周期插件动态加载与稳定插件 SDK。
- 完整客户端 Host API、独立 Web/IDE 宿主交互协议。
- 写入型子智能体、隔离 worktree、冲突合并与自动合并。
- 长期记忆云同步与独立记忆 UI。
- 任意插件声明指标后自动获得统计页面的能力,见插件观测提案。
这些边界不影响声明式工具、内置插件和原生 Pi 扩展的现有使用方式;提案不能作为已经可调用的接口。