Wenext-Pi v0.1.8
@wenext/pi 是基于 Pi 的 AI 开发命令行工具,提供任务路由、方案审查、质量检查、会话恢复和运行观测。你描述目标,智能体按任务复杂度选择流程:简单修改保持轻量,复杂需求保留完整方案与必要审批。
可在业务仓库、普通 Git 仓库或非 Git 目录使用。无需预先创建 AGENTS.md、技能或工作流配置;项目可以按需补充自己的规范、模板、检查命令与领域插件。
安装
要求 Node.js ≥ 22.19.0。从已配置的 npm registry 安装;私有源权限沿用你的 npm 配置。
npm install -g @wenext/pi
wenext-pi --version
cd /path/to/project
wenext-pi也可指定目录:
wenext-pi --root /path/to/project项目根默认为启动目录,不会向上查找 Git 根。在多包仓库中请从希望管理的根目录启动。通用检查的进程管理目前支持 POSIX 环境;Windows 上的托管质量命令会返回不支持。包提供 wenext-pi 命令,并保留 wenext-spec 兼容别名;当前不提供稳定的 JavaScript 导入 SDK。
开始使用
- 在交互界面执行
/login openai完成认证,或配置自定义模型服务提供方。 - 用
/model选择主会话模型,再用/thinking选择该模型支持的推理强度。 - 输入目标,例如:“修正 README 中启动单个项目的命令,并核对实际脚本。”
- 智能体调查必要上下文、创建任务并选择路由。需要人工批准时,阅读完整方案并在 CLI 确认。
- 实施后执行适用检查、核对验收要求并汇报。Git 仓库中先确认当前任务的提交清单并提交,再告诉智能体:“归档这个任务。”提交确认先展示摘要,可选择“查看完整详情”滚动阅读 diff,Esc 取消并返回对话。选择自行提交时,任务保持开放。
交互界面的 /resume 可选择任务完整主会话;已归档任务打开只读历史,按 Esc 返回。详见会话恢复。
普通问答无需创建任务。同一需求的方案微调、原型和文档同步继续使用当前任务;用户只要求方案时会说明尚未同步的产物。自动检查通过后任务仍可继续补充;归档与检查是两个操作。启用 Web 质量插件时,归档后自动回收较早失败的测试附件,完整会话和每轮报告保留;设置 WENEXT_TEST_RETAIN_ALL=1 可保留全部附件,详见Web 质量插件。
环境缺参时会报告恢复条件并停止重复尝试。用户也可以要求保留失败结论归档:默认需要人工确认,仓库可显式禁止;归档不会把失败或未验收改写成成功。详见执行与暂停和失败关闭。
验收按实际目标区分必需项、建议项和待确认范围,不因修改 UI 自动扩大为全平台或真实登录测试。提交完成/取消、归档失败会保留具体结果,不因为任务仍开放就重复催促实施。也可以让 Pi 维护仓库 .agents 中的规则和技能;链接入口需改用已授权的真实源文件,详见写入范围。
| 路由 | 适用场景 | 默认要求 |
|---|---|---|
quick | 已定位、做法明确的微小修改 | PRD 与直接影响验证 |
small | 局部小功能、已知原因修复 | PRD、必要研究与针对性测试 |
infra | 构建、CI、开发工具和流程维护 | PRD、按需研究与工程影响验证 |
standard | 需要正式设计的功能或模块协同 | 完整规划、人工批准与验收 |
foundation | 架构、公共契约、新项目或迁移 | 完整规划、人工批准与阶段验证 |
debug | 原因未明、需要复现与诊断的问题 | 显式启用调试插件及其诊断流程 |
非低风险、复杂或未知影响的任务会提高规划和审批要求。仓库负责描述本项目的判定条件;默认工作流负责路由策略与授权规则。详见任务路由与调试。
模型与推理强度
在 Wenext-Pi 交互界面中操作,模型与推理强度分别选择:
| 命令/默认快捷键 | 用途 |
|---|---|
/model | 选择实际主会话模型 |
/thinking | 打开当前模型的推理强度选择器 |
/thinking high | 直接将当前会话设为 high,需模型支持 |
Shift+Tab | 循环切换当前模型支持的推理强度 |
选择器内 Ctrl+S | 在 /thinking 中将选中强度设为启动默认值 |
Ctrl+T | 展开/折叠思考内容,不改变推理强度 |
档位包括 off、minimal、low、medium、high、xhigh、max,实际可选项取决于模型。普通选择只改变当前会话;恢复会话时会恢复其强度,新会话使用启动配置。若自定义模型只有 off,检查 ~/.pi/agent/models.json 中的模型是否声明 "reasoning": true,并确认模型和网关实际支持推理参数。详见推理强度配置。
安装 Figma 与浏览器扩展
这些能力通过可选的 Pi 原生扩展安装,供智能体读取设计稿或操作浏览器:
wenext-pi install npm:pi-mono-figma
wenext-pi install npm:pi-agent-browser-native
wenext-pi listFigma 扩展提供设计上下文、节点渲染与资源提取。安装后重启 Wenext-Pi,在交互界面执行 /figma-auth --force,通过本地遮蔽输入配置具有目标文件读取权限的 Token,然后提供 Figma 节点链接。
扩展工具不再因为未登记“可信只读能力”而要求先批准任务实施。认证由扩展自身处理;显式写入项目文件仍遵循任务范围,当前任务的研究目录输出只需启动任务。
浏览器扩展提供 agent_browser 工具,还需单独安装浏览器引擎并下载 Chrome:
npm install -g agent-browser
agent-browser install
agent-browser --version安装后完整退出并重启 Wenext-Pi,再提出“用 agent_browser 打开页面并截图”。默认扩展声明保存到用户级 ~/.pi/agent/settings.json;项目级安装、版本固定、更新卸载和排障见扩展安装指南。这些扩展无需加入 workflow.json.plugins.enable,该字段用于 Wenext-Pi 随包提供的生命周期插件。
验证改动
已有仓库可在 .agents/rules/workflow.json 声明检查。普通目录也可让智能体通过 wenext_check 执行本次专项检查,无须生成配置文件。例如,下面是 智能体工具参数,不是终端命令:
{
"checks": [
{ "id": "syntax", "command": ["node", "--check", "src/main.js"] }
]
}请按实际文件和验收目标选择命令;语法检查不能代替行为测试。专项命令和结果保存在本轮检查记录中,有效结果可在重启和归档时复用;命令不会累积为永久门禁。再次检查时按当前验收目标提供专项命令,省略 checks 只运行仓库和插件检查。没有检查或全部检查不适用时显示“未验证”,不会视为通过。见质量检查配置与工具协议。
配置与数据位置
| 内容 | 默认位置 | 是否必需 |
|---|---|---|
| 模型与凭据 | ~/.pi/agent/models.json、auth.json | 需要可用模型和认证 |
| 用户节点偏好 | ~/.wenext-pi/nodes.json | 可选 |
| 指标目的地与开关 | ~/.wenext-pi/reporting.json | 可选,默认启用上报 |
| 项目规则与检查 | .agents/rules/workflow.json | 可选 |
| 完整方案模板与业务阶段 | .agents/rules/planning.json、stages.json | 可选 |
| 任务、会话与证据 | ~/.wenext-pi/projects/<name>--<path-hash>/ | CLI 自动维护 |
WENEXT_PI_HOME 可更换 Wenext-Pi 状态根;PI_CODING_AGENT_DIR 控制 Pi 的模型与认证配置目录。仓库外状态让普通目录也能恢复任务;移动项目根不会自动关联旧状态。
详细接入方式见配置指南。Web 检查和调试均需显式启用,不是通用目录的前置依赖。
恢复任务
在同一项目目录重新启动,输入“继续上次任务”。当前绑定优先;有多个未完成任务时指定任务 ID,或执行 /wenext-task <task-id>。
wenext-pi projects
wenext-pi doctor --root /path/to/projectprojects 只读列出已知项目;doctor 诊断环境并准备项目状态,可能触发旧状态迁移。原始会话、分支及交接保存在本地,详见会话恢复与记忆。
指标与仪表盘
默认匿名上报到 https://offlines-platform-test.wenext.chat,网络失败不阻断任务。采集任务与阶段时间、实际模型、质量检查和可观测的技能加载等事实;包括有界任务标题与项目目录名,不上传完整对话、代码、命令、绝对路径或凭据。
关闭上报,在 ~/.wenext-pi/reporting.json 写入并重启:
{ "enabled": false }本地接收端使用 9001 时可改为 { "server": "http://localhost:9001" }。用 /wenext-metrics 查看实际目的地和健康状态,/wenext-metrics flush 重试当前目的地积压。仪表盘和 API 由独立的 wenext-offline-platform 提供,本包不启动它们。见上报配置、统计口径与排障。
文档
- 任务提交与归档:提交范围、人工确认、暂存区保护和手动提交。
- 文档导航:按使用、集成和设计查找主题。
- 配置指南:模型、路由条件、模板、检查与插件。
- 扩展安装指南:Figma、浏览器扩展的安装、认证、依赖与管理。
- 命令与智能体工具:区分终端命令、交互命令和模型工具。
- 故障排查:恢复、授权、检查与上报问题。
- 架构设计:运行基座、默认工作流、仓库与插件的职责。
- 扩展设计:选择声明式命令、内置插件或 Pi 扩展。
- 开发指南:源码布局、构建、验证和发布约束。
第三方生命周期插件动态加载、稳定客户端 SDK、写入型子智能体、自动合并和记忆云同步尚未提供。通用插件观测设计为待实现提案。
默认以一份 PRD 组织目标、方案和验收,尊重仓库额外模板。独立评审按风险保留,每个任务最多三轮;归档复用有效验证,不自动重跑测试。详见轻量化设计和归档方式。
许可证
MIT,见 LICENSE。