Skip to content

配置指南 ​

文档导航

Wenext-Pi 可以零项目配置启动。模型和凭据属于用户环境;仓库声明只补充本项目的规范、流程与检查。配置缺失使用默认行为,已存在但格式无效的配置需要修正,不能当作缺失忽略。

配置归属 ​

配置位置生效方式
模型服务提供方与认证$PI_CODING_AGENT_DIR,默认 ~/.pi/agent模型选择器刷新模型服务提供方声明;认证由 SDK 管理
节点与审查器模型$WENEXT_PI_HOME/nodes.json启动时读取
上报$WENEXT_PI_HOME/reporting.json启动时读取,见指标指南
路由、插件、检查、准备<root>/.agents/rules/workflow.json插件组合启动时固定;路由在新任务创建时快照
完整方案与模板<root>/.agents/rules/planning.json新任务保存快照,按路由生成产物
领域阶段<root>/.agents/rules/stages.json完成时核验阶段声明与产物

WENEXT_PI_HOME 默认是 ~/.wenext-pi。各 JSON 示例按所属字段合并到已有文件,不要用示例覆盖已有检查与插件。

模型与认证 ​

OpenAI 登录 ​

内置保留 openai 模型服务提供方。执行 /login openai,选择 Sign in with ChatGPT 并完成浏览器授权,然后通过 /model 选模型;这条路径无需自行填写 API Key。也可使用 OpenAI API Key 认证。

可用模型与额度由账号和服务端权限决定。当前集成走 Pi 1.1.0 的 OpenAI Responses 实现;登录、请求和续期行为见 OAuth 契约。连接失败与授权失效会分别提示,只有明确的凭据问题才要求重新登录。

Pi 默认把认证保存在 ~/.pi/agent/auth.json。/logout 移除本地凭据,不代表远端凭据已撤销。最近一次通过模型选择器或快捷键选中的模型会保存,通常无需另外按 Ctrl+S。

自定义模型服务提供方 ​

除内置 OpenAI 外,其他模型服务提供方需在 ~/.pi/agent/models.json 声明。设置 PI_CODING_AGENT_DIR 可改变 Pi 配置目录,它与 Wenext-Pi 的任务状态目录不同。

下面是结构示例;将地址、协议和模型 ID 替换为实际网关支持的值,并在启动 CLI 的环境中设置 WENEXT_MODEL_API_KEY:

json
{
  "providers": {
    "team-gateway": {
      "baseUrl": "https://models.example.com/v1",
      "api": "openai-responses",
      "apiKey": "$WENEXT_MODEL_API_KEY",
      "models": [
        { "id": "your-model-id", "reasoning": true }
      ]
    }
  }
}

打开模型选择器时会刷新该配置。JSON 损坏或 providers 类型错误会明确报错,不会静默改用其他模型服务提供方。不要把认证文件或明文密钥提交到项目。

推理强度 ​

先用 /model 选主会话模型,再执行 /thinking 选择强度;也可输入 /thinking high 直接设置。默认快捷键 Shift+Tab 循环切换支持的档位。候选档位为 off、minimal、low、medium、high、xhigh、max,选择器只显示当前模型支持的项。

在选择器中按 Enter 或直接执行 /thinking high 只改变当前会话;按 Ctrl+S 应用选中强度并保存启动默认值。会话记录会保存强度变化,恢复旧会话时沿用其设置。Ctrl+T 仅展开或折叠思考内容,不改变请求的推理强度。

也可在 Pi 用户配置 ~/.pi/agent/settings.json 中合并以下字段,作为新会话的启动默认值(PI_CODING_AGENT_DIR 可改变配置目录):

json
{
  "defaultThinkingLevel": "high"
}

项目设置或 modelThinkingLevels 的模型专属配置可能覆盖通用默认值,实际强度还会按模型支持范围调整。若自定义模型只能选 off,检查 models.json 中对应模型的 "reasoning": true 声明;该声明只描述能力,不能让不支持推理参数的模型或网关获得此能力。修改后重新打开 /model 刷新并选中模型,再查看 /thinking。

节点模型配置的含义 ​

~/.wenext-pi/nodes.json(或 $WENEXT_PI_HOME/nodes.json)维护用户级节点绑定,例如:

json
{
  "nodes": {
    "plan": { "model": "team-gateway/your-model-id" },
    "implement": { "model": "team-gateway/your-model-id" }
  },
  "hooks": {
    "plan.review": {
      "enabled": false,
      "model": "team-gateway/your-model-id",
      "onResult": "ask_human"
    }
  }
}

默认节点声明使用 default/fast、default/reasoning、default/coding 等符号值,它们不是可直接请求的模型 ID。当前主会话的节点绑定用于工作流上下文,不会自动替换 Pi 已选择的模型;实际主模型以 /model 和真实响应为准。独立审查器会解析显式配置的 hooks.plan.review.model,默认 default/critic 则沿用当前模型。普通只读子智能体固定继承创建时的模型。

CLI 的 --node、--model 用于 Wenext 节点配置覆盖;不要把它们理解成自动多模型调度。--hook plan.review=on 强制独立方案审查,off 仍保留风险驱动的审查要求。

Pi 原生扩展 ​

Figma、浏览器等扩展通过 wenext-pi install npm:<包名> 安装,用户级声明保存在 ~/.pi/agent/settings.json 的 packages 字段;--local 使用项目 .pi/settings.json。这些包为智能体提供工具或技能,不加入 Wenext 生命周期插件的 workflow.json.plugins.enable。安装、认证、浏览器依赖与更新步骤见扩展安装指南。

接入项目 ​

仓库文件 ​

text
AGENTS.md                         # 仓库级约束与导航
.agents/
├── rules/
│   ├── workflow.json             # 路由、插件、质量、准备命令
│   ├── planning.json             # 可选:完整方案产物与模板
│   ├── stages.json               # 可选:业务阶段
│   └── **/*.md                   # 编码与领域规范
└── skills/**/SKILL.md             # 按需加载的过程知识

CLI 不生成或覆盖业务 AGENTS.md。.agents/rules 有有效 Markdown 或根级 stages.json 时作为规范来源;只有 workflow.json 时仍允许读取旧 .wenext-spec/spec。根级 CLAUDE.md 可作兼容上下文,.claude/、.codex/ 的平台 Hook 不会由 Wenext-Pi 执行。用户级 ~/.agents/skills 也可按描述发现和按需读取。没有项目配置不等于隔离模式;SDK 仍可能加载用户级、祖先目录或扩展提供的上下文。

可选路由配置 ​

在 .agents/rules/workflow.json 中合并下面的声明,保留已有插件和检查:

json
{
  "schemaVersion": 1,
  "routing": {
    "schemaVersion": 1,
    "routes": {}
  }
}

不提供 routing 和空 routes 都使用内置默认定义。项目可为已有路由补充 description、requiredArtifacts、validation;描述应写清本仓的适用条件。可选验证目标为 affected、regression、impact、acceptance,不能配置 none 或审批豁免。新增路由提供者需要插件,不能仅靠写一个新键实现。

这份最小配置显式采用默认路由,没有为项目定义自动化验证。实际接入还需补充以下质量配置。

按影响选择检查 ​

下面示例适用于使用 Git 且已有 npm test 的仓库。必须按实际目录和测试入口调整;路径均为字面相对路径,目录项匹配其子路径,不支持 glob:

json
{
  "schemaVersion": 1,
  "routing": { "schemaVersion": 1, "routes": {} },
  "quality": {
    "schemaVersion": 2,
    "requireVerified": true,
    "checks": [
      {
        "id": "diff-format",
        "command": ["git", "diff", "--check"],
        "required": true
      },
      {
        "id": "tests",
        "command": ["npm", "test"],
        "required": true,
        "when": {
          "impactPaths": {
            "runtimePaths": ["src", "test", "package.json", "package-lock.json"],
            "nonRuntimePaths": ["docs"],
            "nonRuntimeFiles": ["README.md", "AGENTS.md", ".agents/rules/workflow.json"]
          }
        }
      }
    ]
  }
}

git diff --check 只验证相关 Git diff 的空白问题,不检查文档事实、链接或未跟踪文件,也不是业务验收。应结合实际需求增加文档或其他检查。

运行影响路径优先于非运行路径。全部变化明确属于非运行内容时,业务测试返回 not_applicable;有未映射路径、混合变更中的未知部分或不完整范围时,需要先查清影响,不会先安装测试工具再盲目全仓执行。不能凭 .md 后缀一律免测,例如生成配置或运行输入也可能使用 Markdown。

配置中的非运行路径只表示“不要求该业务测试”。如果修改工作流本身影响执行行为,仍应声明相应工程检查。requireVerified: true 下,所有检查均不适用或没有检查会保留未验证状态,不能制造成功证据。

命令为 argv 数组,不做 Shell 展开;默认工作目录为项目根。扩展字段要求嵌套的 quality.schemaVersion: 2,外层仍为 1。复杂工具可提供 resultFile、artifacts 和 verifyCommand,详见质量命令契约。

原始方案模板与业务阶段 ​

不配置时,新任务只要求一份包含设计与验收的 PRD。仓库可以增强契约,旧任务保留已冻结要求。可选 .agents/rules/planning.json 示例:

json
{
  "schemaVersion": 1,
  "required": ["prd.md", "research/findings.md", "implementation-spec.md"],
  "templates": {
    "research/findings.md": ".agents/templates/research.md",
    "implementation-spec.md": ".agents/templates/implementation-spec.md"
  }
}

示例模板文件须由仓库实际提供。新路由任务保存模板快照,并按选中流程生成所需文档;业务字段不会被基座缩减成通用占位内容。原样未填写的模板不满足方案就绪要求。

stages.json 可声明业务产物及消费节点,例如设计还原。阶段记录由 wenext_complete_stage 保存,要求真实产物;它不授予实施权限。模型属于用户配置,不应写入业务阶段定义。

环境准备 ​

workflow.json.preparation 可声明 startup、beforeImplement、beforeCheck 命令。后两者可用 whenChecks 绑定实际选中的检查;例如只有 business-tests 适用时才准备业务测试环境。

startup 仍是启动级动作,不受任务路由减免。不要把所有测试依赖安装塞进启动准备,否则 README 小任务也会承担它的成本。准备成功不等于测试通过。参数、超时和多会话约束见项目准备契约。

插件与扩展 ​

内置插件 ​

插件默认状态用途
planning必需规划、审查与授权契约
git-evidence必需Git 变更证据
change-scope必需变更范围与归属
quality-command必需通用检查执行与证据
quality-web可选Web 业务测试工具准备、执行与报告验证
debug可选,显式启用Web 诊断、Nous 评测、禅道与飞书流程

必需插件不可由仓库禁用。调试需要显式启用,单独声明质量检查不会自动启用调试。已有任务引用的插件缺失时会明确提示恢复依赖,不能以禁用插件消除任务义务。修改插件组合后需要重启。

Web 质量检查 ​

合并到现有 workflow.json 的示例:

json
{
  "schemaVersion": 1,
  "routing": { "schemaVersion": 1, "routes": {} },
  "plugins": { "enable": ["quality-web"] },
  "quality": { "schemaVersion": 2, "requireVerified": true, "checks": [] },
  "webQuality": {
    "schemaVersion": 1,
    "runtimePaths": ["src", "packages", "package.json"],
    "nonRuntimePaths": ["docs"],
    "nonRuntimeFiles": ["AGENTS.md"]
  }
}

插件贡献 business-tests,仓库不要重复声明同名检查。上例仍需补充锁文件、配置文件等实际影响映射,以及文档验证命令;只保留空 checks 无法让纯文档任务获得验证证据。

quality-web 在第一次选中业务测试时才查询 registry 并准备 @wenext/test-tool。普通启动和纯文档任务不会触发它的更新。工具安装到 Wenext-Pi 独立缓存,不修改业务 package.json、锁文件或 node_modules;本进程固定使用已选版本。网络或安装失败可使用健康缓存并明确提示,没有可用工具时不能伪装测试通过。

测试工具必须遵循公开 request/output 和报告验证契约。对于应测的业务变化,“没找到业务包/测试入口”不等于“不适用”。详见 Web 质量插件。

调试插件 ​

调试的 Nous、禅道和飞书逻辑位于 src/plugins/debug/,业务修改这些领域流程无需把语义塞进通用基座。启用示例:

json
{
  "schemaVersion": 1,
  "routing": { "schemaVersion": 1, "routes": {} },
  "plugins": { "enable": ["debug"] },
  "debug": { "schemaVersion": 1, "nous": true, "zendao": true, "lark": true }
}

这是领域配置片段,需与实际质量配置合并。启用的集成依赖项目中 .agents/skills/domains/nous-debug-eval/scripts/、zendao-debug/scripts/ 及对应 Python/外部 CLI 环境;只启用插件不会安装这些业务依赖。可按需要关闭外部集成,保留本地诊断。

典型流程为:初始化来源 → 记录现场与本地归因 → 绑定 Nous 查询 → 独立诊断和修复 → 真实质量检查 → 冻结 Findings → 阅读 Nous 结果并评测 → 反馈 → 用户要求归档。外部操作首次使用需真实 UI 授权。未冻结独立结论前不能先读取答案冒充独立诊断。

通过 wenext_plugin 调用 initialize、status、resolve_local、query、wait、freeze、feedback、recover 等动作。插件状态保存在任务的 plugins/debug/state.json,中断恢复不会静默重发外部请求。完整输入和顺序见路由与调试契约。

开发插件与使用 Pi 扩展 ​

Wenext 内置插件随 @wenext/pi 一起发布。新增 src/plugins/<id>/plugin.json 和入口后,构建自动生成注册表;运行时按依赖装配,通过生命周期、检查、节点、路由和动作扩展能力。仓库只能启用已经打包的插件,不能配置任意本地代码为可信插件。

这套内部插件接口尚不是稳定第三方 SDK。Pi 原生扩展仍可通过 wenext-pi install/list/remove/update/config 管理,两种扩展机制应分别理解。当前已停用“未登记可信只读能力就要求任务实施批准”的默认限制;未声明的扩展调用直接交执行器处理,不需要额外配置开关。显式项目输出、Pi 状态路径保护和已声明的写入能力仍按现有边界处理。详见内置插件契约。