Skip to content

扩展设计 ​

文档导航 · 架构设计

本页说明如何让不同项目复用 Wenext-Pi,以及新增能力应放在哪一层。文件路径为兼容已有链接保留,内容描述当前扩展边界,不是实施排期。

选择接入方式 ​

需求首选方式是否修改并发布 Pi
补充编码规范、领域知识或操作说明项目 AGENTS、Rules、技能否
修改本项目路由的适用描述、产物或验证目标workflow.json.routing 与 planning.json否,不能降低核心授权要求
运行已有测试、构建、审计或校验工具workflow.json.quality.checks否
为单次任务添加验证wenext_check.checks否
准备项目依赖或检查环境workflow.json.preparation否
增加智能体工具、交互命令或 UIPi 原生 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 扩展的现有使用方式;提案不能作为已经可调用的接口。