# pi-alibaba-bailian

通过阿里云百炼（Model Studio / DashScope）的 **API Key** 在 [Pi](https://github.com/earendil-works/pi) 中直接使用千问及百炼托管的文本模型。Provider ID 为 `bailian`，使用 OpenAI Chat Completions 兼容接口。

## 快速开始

要求 Node.js 22.19+ 与 Pi 0.84.2+。

```bash
export DASHSCOPE_API_KEY="sk-..."

# 在本仓库直接试用
pi -e .

# 或安装本地包
pi install /absolute/path/to/pi-alibaba-bailian
```

启动 Pi 后运行 `/model`，选择 `bailian/qwen3.8-max`、`bailian/qwen3.7-plus`、`bailian/qwen3-coder-plus` 等模型。也可以查看模型：

```bash
pi -e . --list-models bailian
```

插件只读取 `DASHSCOPE_API_KEY` 环境变量，不会保存或输出 API Key。

## 地域与 Endpoint

API Key **与地域绑定**。默认使用中国内地通用地址：

```text
https://dashscope.aliyuncs.com/compatible-mode/v1
```

可通过地域别名选择 Endpoint：

```bash
export DASHSCOPE_REGION=china         # cn / beijing / cn-beijing
export DASHSCOPE_REGION=singapore     # sg / intl / international / ap-southeast-1
export DASHSCOPE_REGION=us            # usa / virginia / us-east-1
```

阿里云建议北京、新加坡业务空间使用专属域名。请通过 `DASHSCOPE_BASE_URL` 配置控制台中显示的地址（优先级高于 `DASHSCOPE_REGION`）：

```bash
export DASHSCOPE_BASE_URL="https://WORKSPACE_ID.cn-beijing.maas.aliyuncs.com"
```

仅提供 host 时，插件自动补充 `/compatible-mode/v1`；已经包含 `/v1` 的地址保持不变。出于 API Key 安全考虑，自定义地址必须使用 HTTPS。修改环境变量后请重启 Pi 或执行 `/reload`。

## 模型发现

插件会用当前 API Key 请求 `{baseUrl}/models`，并将返回结果与实际可见 ID 相交。为了避免在 Pi 中显示无法用于 Agent 的媒体或任务专用模型，自动排除图像生成、Embedding、ASR/TTS、Audio、Realtime、翻译、搜索/研究、角色扮演、GUI、OCR、无工具长文本等模型，只保留适合 OpenAI Chat Completions 与 Function Calling 的：

- Qwen 通用、Coder、VL 系列（含快照别名）；
- 百炼托管的 DeepSeek、Kimi、GLM、MiniMax、MiMo 文本模型。

网络刷新前提供一组推荐模型作为静态 fallback；刷新成功后列表严格使用 API 返回的可用 ID。模型列表打开时也会刷新，因此新模型通常无需更新插件。

模型上下文、输出上限与思考能力对已知型号使用明确元数据，新型号采用保守的系列推断。**费用字段固定为 0，仅表示本插件不估算账单，不代表 API 免费**；请以阿里云控制台计费为准。

## 覆盖模型元数据

如模型规格变化，可通过 `~/.pi/agent/models.json` 覆盖插件注册的模型，例如：

```json
{
  "providers": {
    "bailian": {
      "modelOverrides": {
        "qwen3.8-max": {
          "contextWindow": 1000000,
          "maxTokens": 131072
        }
      }
    }
  }
}
```

## 开发与验证

```bash
npm install
npm run check
```

## English

Pi provider extension for Alibaba Cloud Model Studio (Bailian/DashScope) API-key access. Set `DASHSCOPE_API_KEY`, run `pi -e .`, and select a `bailian/...` model. Model discovery is dynamic and filtered to agent-capable Chat Completions models. API keys are region-specific.

## License

MIT