modelstudioai__cli/CONTRIBUTING.zh.md

# 参与贡献 bailian-cli

`bailian-cli` 是阿里云百炼(DashScope)的官方 CLI。本文是面向**开发者**的指南;终端用户请看 [README.zh.md](README.zh.md)。

[English](CONTRIBUTING.md) · [README](README.zh.md) · [更新日志](CHANGELOG.zh.md)

## 环境要求

- 参与本仓库开发：Node.js ≥ 22.12
- 仅安装/使用已发布的 CLI：Node.js >= 18.17
- pnpm 10.33.2（`npm i -g pnpm@10.33.2`）
- 跑 e2e 需要一个百炼 API Key

## 仓库结构

```
bailian-cli/
├── packages/
│   ├── core/           # `bailian-cli-core` —— 鉴权、配置、HTTP client、错误、类型
│   ├── runtime/        # `bailian-cli-runtime` —— CLI 运行时:参数解析、help、middleware、输出
│   ├── commands/       # `bailian-cli-commands` —— 可复用命令实现库
│   ├── cli/            # `bailian-cli` —— 完整 `bl` 产品入口
│   ├── kscli/          # `knowledge-studio-cli` —— `kscli` 入口,复用 commands/
│   ├── e2e/            # e2e 共享工具(不发布)
│   └── bailian-kb-dsh/ # `bailian-kb-dsh` —— DeepSeek Harness 插件(版本与发布独立)
├── skills/             # `bl skill init` 安装的 Agent skill
├── docs/agents/        # 场景化维护文档
├── tools/              # 发版自动化与命令手册生成
├── AGENTS.md           # AI agent 维护契约
└── README.md
```

## 本地搭建

```bash
git clone https://github.com/modelstudioai/cli.git bailian-cli
cd bailian-cli
pnpm install
```

### 从源码运行 CLI

```bash
pnpm bl auth login --api-key sk-xxxxx
pnpm bl text chat --message "你好"
pnpm bl video generate --prompt "一只走路的猫"
```

## 常用脚本

| 命令             | 作用                                     |
| ---------------- | ---------------------------------------- |
| `pnpm bl <args>` | 从源码运行 CLI                           |
| `pnpm dev`       | watch-build `bailian-cli-core`           |
| `pnpm check`     | format + lint + 类型检查                 |
| `pnpm test`      | 单测 + e2e(e2e 需要 `DASHSCOPE_API_KEY`) |
| `pnpm ready`     | 提 PR 前的完整自检                       |

## AI Native 工程化

我们把 AI agent 当作一等公民的维护者。下面三套基建让这件事能跑起来,无论你是人类贡献者还是 AI agent,都值得了解一下:

- **[AGENTS.md](AGENTS.md) + [docs/agents/](docs/agents/)** —— 本仓库的维护契约。`AGENTS.md` 给出项目地图和场景索引;每份 `docs/agents/<场景>.md` 把高频任务(加命令、改 flag、加模型、改错误提示……)拆成一份可端到端执行的清单,不需要事先摸索全仓库。新场景随真实工作沉淀回来——这份文档随项目生长,不是一次性的设计产物。

- **E2E 测试体系** —— [packages/cli/tests/e2e/](packages/cli/tests/e2e/) 下的用例覆盖文本 / 图像 / 视频 / 语音 / 理解 / 知识库 / 记忆库的主链路,黑盒方式打真实的 DashScope 服务。任何人或 agent 改了行为,会以真实用户感知到的方式被兜住。

- **主链路压测**(`pnpm test:stress`)—— 对所有模型能力做并发压测,验证它们在大量请求下仍然稳定;同时捕捉单次 e2e 抓不到的限流边界、竞态、静默回归。每次发版前跑。

**如果你是在本仓库上工作的 AI agent,先读 [AGENTS.md](AGENTS.md)** —— 它是会把你引到正确场景文档的入口。

## 分支与 PR

- 从 `main` 拉分支。命名:`feat/<short-name>`、`fix/<short-name>`、`docs/<short-name>`。
- 提 PR 前先跑 `pnpm check`。
- 一个 PR 只解决一类问题。
- 提交信息祈使句、带 scope。例:`feat(image): add --negative-prompt`、`fix(auth): handle expired console token`。
- 功能 PR 不要去动 `packages/*/package.json` 的版本号。

## 反馈问题

Bug 和需求都走 https://github.com/modelstudioai/cli/issues。如果是 bug,请包含:

- CLI 版本(`bl --version`)
- Node 版本(`node --version`)
- 触发问题的完整命令
- 完整输出(请脱敏 API Key)

## License

提交贡献即表示你同意以 [Apache License 2.0](LICENSE) 协议授权。