配置指南
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:
{
"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 可改变配置目录):
{
"defaultThinkingLevel": "high"
}项目设置或 modelThinkingLevels 的模型专属配置可能覆盖通用默认值,实际强度还会按模型支持范围调整。若自定义模型只能选 off,检查 models.json 中对应模型的 "reasoning": true 声明;该声明只描述能力,不能让不支持推理参数的模型或网关获得此能力。修改后重新打开 /model 刷新并选中模型,再查看 /thinking。
节点模型配置的含义
~/.wenext-pi/nodes.json(或 $WENEXT_PI_HOME/nodes.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。安装、认证、浏览器依赖与更新步骤见扩展安装指南。
接入项目
仓库文件
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 中合并下面的声明,保留已有插件和检查:
{
"schemaVersion": 1,
"routing": {
"schemaVersion": 1,
"routes": {}
}
}不提供 routing 和空 routes 都使用内置默认定义。项目可为已有路由补充 description、requiredArtifacts、validation;描述应写清本仓的适用条件。可选验证目标为 affected、regression、impact、acceptance,不能配置 none 或审批豁免。新增路由提供者需要插件,不能仅靠写一个新键实现。
这份最小配置显式采用默认路由,没有为项目定义自动化验证。实际接入还需补充以下质量配置。
按影响选择检查
下面示例适用于使用 Git 且已有 npm test 的仓库。必须按实际目录和测试入口调整;路径均为字面相对路径,目录项匹配其子路径,不支持 glob:
{
"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 示例:
{
"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 的示例:
{
"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/,业务修改这些领域流程无需把语义塞进通用基座。启用示例:
{
"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 状态路径保护和已声明的写入能力仍按现有边界处理。详见内置插件契约。