Skip to content

架构设计 ​

文档导航 · 扩展设计

Wenext-Pi 在 Pi 的模型、会话与工具能力之上管理可恢复的开发任务。设计目标是让流程成本与任务风险相称,同时保留可靠的授权、检查证据和运行观测。项目可以没有工作流资产;已有项目则通过声明和领域知识增强默认行为。

系统职责 ​

层职责不负责的内容
Pi 引擎与适配模型、认证、消息循环、原始会话、TUI/RPC、原生工具与 extensions项目的业务验收规则
运行基座任务状态、执行、取消、范围、证据、审查运行、会话和智能体协调用包名或框架推断业务是否通过
默认工作流通用路由、节点、风险升级、产物要求、批准和完成策略项目专属模块和外部系统语义
内置插件贡献检查、节点、路由、动作和领域完成条件自行签发人工批准或改写任务完成状态
项目配置与知识AGENTS、技能、Rules、路由判定说明、模板和验收命令复制一套通用任务状态机
指标接收与展示接收事实、去重、投影、查询和仪表盘决定本地任务能否实施或完成

运行基座验证可信状态和证据;默认工作流决定何时要求哪些材料。领域插件通过通用服务消费这些能力,避免把 Web、Nous、禅道等语义带进核心。

源码模块 ​

text
src/
  cli/                    命令入口与启动
  application/            用例编排、路由决策与插件组合
  domain/                 任务、规划产物和配置类型
  adapters/
    pi/                   SDK、UI、模型与会话生命周期
    filesystem/           项目布局、任务和配置持久化
  runtime/                执行、范围、证据、质量、审查、会话和协调服务
  workflows/default/      默认流程策略与提示
  plugins/                随包发布的可信内置能力
  telemetry/              指标协议与观测事实

内部 TypeScript 接口供本包协作使用,尚不构成稳定的第三方 SDK。部分内置插件保留 context.legacy.layout 兼容桥;新能力优先消费 context.services,不解析其他插件的私有状态。

任务路由与授权 ​

mermaid
flowchart TD
    A[用户目标与必要调查] --> B[创建并启动任务]
    B --> C[选择路由与明确范围]
    C --> D{风险与策略}
    D -->|简单低风险| E[必要产物与策略授权]
    D -->|复杂或高风险| F[完整方案与审查]
    F --> G[真实人工批准]
    E --> H[实施]
    G --> H
    H --> I[适用检查与需求验收]
    I --> J[汇报结果,任务保持开放]
    J -->|用户要求归档| K[最终核验与归档]

quick/small/infra/standard/foundation 是通用路由,debug 由插件提供。路由描述工作策略,plan/implement/check 等节点描述当前阶段。智能体结合需求语义、仓库说明与代码事实选择路由;不确定时先研究。配置解析和门禁不能证明自然语言分类总是正确。

新任务在创建时冻结路由与完整方案模板,最初只生成 PRD;选定路由后生成必要产物。未配置项目使用内置默认值,格式无效的配置明确失败。旧任务保留创建时的契约,不能因为升级默认值而丢失义务。

简单低风险任务获得绑定方案、范围和策略的 policy 授权;完整方案需要审查和真实用户批准。已展示且未变化的方案可复用明确的原生对话授权,其余情况使用具体 UI。独立评审每个任务最多三轮。研究更新不撤销实施资格,正式目标、公共契约或风险改变时重新评估。详见路由、方案审查和范围。

检查与完成 ​

质量检查合并仓库、插件与本次调用的专项命令,专项命令不累积为任务永久门禁,先根据实际范围决定适用性,再准备需要的工具并冻结执行计划。普通命令只需 argv 和退出码;领域工具可以消费公开 request JSON,输出结构化结果与报告。

一次执行绑定任务、输入摘要、检查配置、插件版本和实际输出。完成前再次核验,防止后续修改继续使用旧成功结果。准备依赖、模型文字结论、退出后的摘要均不能代替真实证据。

检查结果、验收与归档分开:检查通过不自动归档,零检查为未验证,失败关闭也保留失败事实。wenext_finish 复用有效检查;缺失或过期时提示显式调用 wenext_check,归档不执行检查命令。外部完成、放弃或移交经确认后按未验证收纳。详见质量协议和任务执行。

状态权威与恢复 ​

对象权威来源派生信息的用途
任务与授权任务记录、冻结方案、审查及范围证据wenext_current 给出下一步指导
会话Pi 原始 JSONL、分支与任务主会话指针压缩、交接和近期片段帮助恢复上下文
检查冻结计划、运行记录、输入和报告摘要收据、日志摘要、仪表盘展示
智能体 / Run独立身份、运行状态与所属会话父智能体读取结果后判断用途
记忆带作用域、版本和来源的本地记录检索知识,不授予任务权限
上报持久事件与 ACK 检查点服务端统计,不回写本地任务真值

项目根的规范化路径区分不同 checkout;状态默认位于用户目录。任务主会话保持一个写者,分支与 generation 防止迟到指针覆盖新状态。创建或继续任务切换原始会话,内部替换不等于用户暂停。归档等待最终回复落盘;崩溃留下的 pending 状态在后续启动恢复。

同机进程通过租约和版本比较协调。活进程锁不会仅因时间经过而被抢占;死进程恢复不自动重放命令或模型请求。这不是跨主机共享存储事务。详见状态迁移、会话和并行协调。

观测链路 ​

宿主观察真实生命周期、模型响应、技能正文交付和质量结果,将版本化事实写入持久队列。队列按目的地隔离,服务端持久接收并逐条 ACK 后才确认;网络失败不改变任务状态。查询端区分生命周期、阶段停留和实际观测执行时间,缺失数据保持未知。

CLI、接收端和仪表盘是不同部署单元;协议变更需要接收端先兼容。当前通用工作流与 Web 质量观测已经实现,异构插件的 descriptor 和通用仪表盘属于待实现提案。

运行边界 ​

父会话 Shell 使用原生执行器,不提供命令文本过滤、逐次写入预检或 OS 沙箱。原生文件工具及可信扩展执行工作流门禁,范围观察和完成核验覆盖可见文件。Git 可增强归属信息,非 Git 目录仍能执行真实检查,但不能声称拥有完整历史变化证据。

内置插件是可信同进程代码;能力声明用于调度和校验,不隔离恶意 JavaScript。只读子智能体通过有限工具集限制操作,不提供写入 worker、worktree 或自动合并。完整客户端 API、第三方生命周期插件动态加载和记忆云同步尚未提供。