@ipfans/pi-provider-deveco

将 Huawei DevEco Code 的登录和模型接入 pi。原生 Provider，无本地代理或常驻进程。

非华为官方集成。当前针对 pi 1.2.0 开发。 参考 opencode-deveco v1.3.0，来源及 MIT 声明见 THIRD_PARTY_NOTICES.md。

安装与使用

要求 Node.js ≥ 22.19、pi 1.2.0，以及已开通 DevEco Code、完成实名认证的中国区华为账号。请遵守服务条款与地区限制；账号额度和可用模型由华为控制。

npm 包公开发布，安装无需 GitHub 仓库权限：

pi install npm:@ipfans/pi-provider-deveco
pi

在 pi 中：

/login deveco
/model deveco/GLM-5.1

按提示打开登录链接并授权。登录后可通过 /model 选择动态发现的模型；云端目录与黑名单优先，GLM-5.1 只是无有效目录时的后备。移除登录使用 /logout deveco。

更新与移除

使用未固定版本的安装源时，在终端更新扩展后重启 pi：

pi update npm:@ipfans/pi-provider-deveco

若此前固定安装了 @0.1.0，先运行 pi install npm:@ipfans/pi-provider-deveco 改为跟随 npm 最新版本；固定版本不会随普通更新升级。0.1.1 修复了流式请求的 HTTP 406 问题。

卸载扩展使用 pi remove npm:@ipfans/pi-provider-deveco。若也要删除登录凭证，先在 pi 中执行 /logout deveco，再卸载。

远程终端登录

回调仅监听 127.0.0.1，优先端口 10101，占用时依次尝试 34567–34570。SSH 场景须将提示中的端口转发到运行 pi 的机器，例如：

ssh -L 10101:127.0.0.1:10101 your-host

浏览器必须能访问该转发端口。登录最多等待 10 分钟；取消或超时会关闭监听器。回调含一次性随机校验码，支持 GET 和表单 POST。

行为与安全

凭证

• 凭证交由 pi 管理：默认位于 ~/.pi/agent/auth.json（或 PI_CODING_AGENT_DIR）。不另建 token 文件，不读取 DevEco IDE 或 OpenCode 的凭证。
• DevEco 长期 jwtToken 存入 OAuth refresh 字段；不是接口返回的 refreshToken。access token 按 30 分钟有效期交给 pi 自动刷新。不要公开 auth.json、登录回调 URL 或诊断中的请求头。

模型能力

• 模型目录由 pi 的 models-store.json 持久化，缓存约 1 小时。离线或刷新失败保留上次目录；pi update --models 可主动刷新。模型删除、黑名单、上下文限制、图片与工具能力以云端元数据为准。
• 复用 pi 的 OpenAI Chat Completions 流解析，支持文本、reasoning_content、工具调用和用量；模型定价未知，显示的零成本不代表服务免费。
• 适配 system、max_tokens 和指定工具调用；没有声明图片能力的模型会明确拒绝带图片的上下文，不暗中换模型。
• 有 reasoning effort 元数据时映射 pi 思考档位；不支持的档位按宿主规则收敛。GLM-5.1 后备只声明默认思考能力，不发送未知的 effort 参数；其默认 enable_thinking=true 用于分离思考内容，不保证所有思考档位都能改变服务端行为。

会话与队列

• Session-Id / Chat-Id 从 pi 会话 ID 稳定派生。无会话 ID 的 SDK 调用退回首条用户消息摘要，建议 SDK 调用者始终传 sessionId。
• 每个 Provider 实例串行生成，最多 3 个等待请求；支持排队取消。连续生成交接冷却 1 秒。流使用 120 秒空闲超时，不是整个回答只能持续 120 秒。
• 成功、错误或取消后都尝试退出服务端队列，最多等待 3 秒，再释放本地槽位。没有跨进程/应用锁；不要同时让多个 pi、DevEco IDE 或代理争用同一账号。

服务边界

• 认证和聊天固定访问华为 HTTPS 地址并禁止重定向。默认 X-DevEco-Improvement-Enabled=false。如确需参与相应改进计划，可自行设置 DEVECO_TOOL_IMPROVEMENT=1；此请求头不替代华为的数据处理条款。
• 保留参考项目的欧洲相关时区拒绝策略；它不是可靠地理定位，也不代表其他地区自动符合服务资格。不提供绕过限制的开关。

不包含 Anthropic 转换、隐藏模型、自动视觉路由、守护进程，也不从历史文本中删除字面量 </think>。

故障排查

| 现象 | 处理 | | --- | --- | | /login 没有 DevEco | 确认扩展已加载，使用 pi 1.2.0；重启 pi 或 /reload | | 登录后 /model 搜不到 DevEco | 若选择器处于 scoped 范围，按 Tab 切到 all 再搜索 deveco。长期启用可在 /scoped-models 勾选模型并按 Ctrl+S 保存，或在设置的 enabledModels 中追加 deveco/* 后重启。已有模型缓存不代表模型已加入启用范围，无需因此重新登录 | | 回调端口全部被占用 | 关闭其他登录尝试，再登录；远程环境检查端口转发 | | China-region / real-name 错误 | 使用符合条件的中国区账号并完成实名认证 | | HTTP 401 | /login deveco 重新授权；扩展不会自动重放生成请求 | | HTTP 403 | 检查模型授权、账号资格和请求长度；不将所有 403 误判为上下文溢出 | | HTTP 406 | 流式接口要求 Accept: text/event-stream；0.1.0 未覆盖 OpenAI SDK 的 JSON 默认值。按更新说明升级到 0.1.1 或更高版本并重启 pi；重新登录不能修复此问题 | | HTTP 429 / 本地队列已满 | 稍后重试，并停止同账号的其他客户端请求 | | 空闲超时 / 中断 | 检查网络或代理；取消后可再发起下一轮 | | 模型目录刷新失败 | 使用已有缓存或后备模型，网络恢复后运行 pi update --models |

开发与验收

GitHub 源码仓库为私有，有权限的开发者可获取源码后运行检查：

gh repo clone ipfans/pi-provider-deveco
cd pi-provider-deveco
npm ci --ignore-scripts
npm run lint       # Biome + TypeScript strict
npm test           # 模拟服务 + 真正的 pi CLI 隔离加载测试

在源码目录运行 pi -e ./src/index.ts 可单次试用，不写入安装配置；运行 pi install . 则保存本地安装。代码代理的维护约束见源码根目录 AGENTS.md（不随 npm 包发布）。

宿主兼容性

扩展由 pi 直接加载 TypeScript，无需构建。宿主提供 pi 依赖，本仓库的开发依赖仅用于检查和测试；peerDependencies 的 * 不代表已验证所有 pi 版本。

当前使用 pi 1.2.0 的公共 @earendil-works/pi-ai/compat 入口获取原生 OpenAI 适配器，因为该版本的扩展加载器不映射任意 pi-ai/api/* 子路径。升级宿主或修改导入路径时，以发布包的隔离加载测试为准，而非仅验证带有本地 node_modules 的源码。

自动检查与真实账号验收

测试覆盖 loopback 回调、取消/超时、JWT 刷新与登出竞争、模型缓存和删除、思考与工具参数、中文 UTF-8 分片、多轮工具消息、SSE 请求头与 HTTP 错误、空闲超时及槽位清理。

集成测试实际执行 npm pack 和 npm publish --dry-run，检查发布白名单，再把解包后不含 node_modules 的包安装进临时 pi 目录，使用虚构凭证和 --offline 验证加载、重启及登出后的模型可见性；不会访问你的现有凭证、请求真实模型或上传 npm 包。本地 dry-run 不验证 npm 发布权限。

验收状态： 已进行真实华为账号联调与远端发布验证。

后续版本回归清单： 浏览器授权 → 云端目录 → 多轮文本/工具调用 → 取消后继续 → 重启恢复 → access token 到期刷新。模拟测试与真实服务回归分别验收；账号资格和模型行为以实际服务为准。

发布维护

.npmrc 固定使用 https://registry.npmjs.org/，包括 @ipfans 作用域。package.json 的发布白名单只包含运行时 TypeScript 源码、README 与许可证；测试、参考仓库、开发依赖和本地配置不会进入包。pi 直接加载 TypeScript，因此打包无需编译或捆绑宿主依赖。

发布一个正式 GitHub Release（非草稿、非预发布）会触发 .github/workflows/publish.yml：校验 tag 与版本一致 → 安装锁定依赖 → lint 和测试 → npm pack → OIDC 发布 npm → 将同一个 .tgz 附到 Release。

Trusted Publisher 配置

npm Trusted Publisher 必须绑定：

• Package：@ipfans/pi-provider-deveco
• Organization or user：ipfans
• Repository：pi-provider-deveco
• Workflow filename：publish.yml
• Environment name：npm
• Allowed action：允许直接 npm publish，不能只允许 npm stage publish

无需 NPM_TOKEN。GitHub Environment npm 若配置了审批，发布会等待审批。仓库保持私有，因此明确关闭 npm provenance；这不影响 OIDC 身份验证。

首次配置和绑定有效期以 npm 官方说明为准。认证是否成功以 Actions 的 OIDC 交换日志为准，不能用本地发布或无认证的 dry-run 代替。

验证 OIDC

选择已有的正式 Release tag，可在不新增 npm 版本、不修改 Release 附件的情况下验证真实 Actions OIDC 认证和打包：

TAG=v0.1.1  # 替换为要验证的已有正式 Release tag
gh workflow run publish.yml --ref main -f tag="$TAG" -f verify_only=true

此模式只执行发布 dry-run，且检查 npm 确实成功交换了 OIDC token；它不等同于新版本的实际上传。

发布新版本

确认工作区干净并完成验收后：

npm version patch --no-git-tag-version
# 提交 package.json / package-lock.json，并推送 main
VERSION=$(node -p 'require("./package.json").version')
git tag "v$VERSION"
git push origin "v$VERSION"
gh release create "v$VERSION" --verify-tag --title "v$VERSION" --generate-notes

仅推送 tag 不会发布；创建正式 Release 才会。发布失败且 npm 尚无该版本时，将 TAG 设为该 Release 的 tag，运行 gh workflow run publish.yml --ref main -f tag="$TAG"，用 main 上的工作流重新打包并发布原 tag 的源码，不移动 tag。npm 的同名同版本不能覆盖，应发布新版本。工作流日志可通过 gh run list --workflow publish.yml 查看。