Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
90 lines (65 loc) · 4.43 KB

CONTRIBUTING.md

File metadata and controls

90 lines (65 loc) · 4.43 KB
Raw

Contributing to bailian-cli

Developer guide for bailian-cli — the official CLI for Aliyun Model Studio (DashScope). For end-user usage, see README.md.

中文版 · README · Changelog

Prerequisites

  • Node.js ^22.18 or >=24.11 (required for developing this repo)
  • End users installing the published CLI only need Node.js >= 18.17
  • pnpm 10.33.2 (npm i -g pnpm@10.33.2)
  • A DashScope API key for running e2e tests

Repository layout

bailian-cli/
├── packages/
│   ├── core/           # `bailian-cli-core` — auth, config, HTTP client, errors, types
│   ├── runtime/        # `bailian-cli-runtime` — CLI framework: parsing, help, middleware, output
│   ├── commands/       # `bailian-cli-commands` — reusable command implementations
│   ├── cli/            # `bailian-cli` — the full `bl` product entry
│   ├── kscli/          # `knowledge-studio-cli` — `kscli` entry, reuses commands/
│   ├── e2e/            # Shared e2e harness utilities (private)
│   └── bailian-kb-dsh/ # `bailian-kb-dsh` — DeepSeek Harness plugin (independent version & release)
├── skills/             # Agent skills installed by `bl skill init`
├── docs/agents/        # Scenario-based maintenance guides
├── tools/              # Release automation & reference generation
├── AGENTS.md           # Contract for AI agents
└── README.md

Local setup

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

Running the CLI from source

pnpm bl auth login --api-key sk-xxxxx
pnpm bl text chat --message "hello"
pnpm bl video generate --prompt "a cat walking"

Common scripts

Command What it does
pnpm bl <args> Run the CLI from source
pnpm dev Watch-build bailian-cli-core
pnpm check Format + lint + type check
pnpm test Unit + e2e (e2e needs DASHSCOPE_API_KEY)
pnpm ready Full pre-PR verification

AI Native engineering

This project treats AI agents as first-class maintainers. Three pieces of infrastructure make that work, and they're worth knowing about whether you're a human contributor or an agent:

  • AGENTS.md + docs/agents/ — A contract for working in this repo. AGENTS.md gives the project map and a scenario index; each docs/agents/<scenario>.md breaks a recurring task (add a command, change a flag, add a model, change an error hint, …) into a checklist that can be followed end-to-end without prior exploration. New scenarios get sedimented back as they emerge — the docs grow with the project, not from a one-off design phase.

  • E2E test suite — Cases under packages/cli/tests/e2e/ cover the main flows across text / image / video / speech / understanding / knowledge / memory. They exercise the CLI as a black box against the live DashScope service, so behavior changes (yours or an agent's) are caught the way real users would experience them.

  • Main-flow stress tests (pnpm test:stress) — Concurrent runs against all model capabilities to verify they stay stable under heavy request volume. Catches rate-limit edge cases, race conditions, and silent regressions that single-shot e2e can miss. Run before each release.

If you are an AI agent working on this repo, read AGENTS.md first — it's the entry point that routes you to the right scenario doc.

Branching & PRs

  • Branch from main. Name: feat/<short-name>, fix/<short-name>, docs/<short-name>.
  • Run pnpm check before opening the PR.
  • Keep PRs focused — one logical change per PR.
  • Commit messages: imperative and scoped. Examples: feat(image): add --negative-prompt, fix(auth): handle expired console token.
  • Do not bump packages/*/package.json versions in feature PRs.

Reporting issues

Bug reports and feature requests both go to https://github.com/modelstudioai/cli/issues. For bugs, please include:

  • CLI version (bl --version)
  • Node version (node --version)
  • Exact command that failed
  • Full output (redact API keys)

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.