diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 844f8b02b..fcb0c6c6b 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -10,6 +10,7 @@ on: options: - bailian-cli - knowledge-studio-cli + - bailian-kb-dsh mode: description: "Publish mode" required: true @@ -18,7 +19,7 @@ on: - channel - stable channel: - description: "Required when mode=channel. npm dist-tag only (lowercase, digits, dashes), e.g. mcp / plugin / sync-release. bailian-cli binary CDN always overwrites sync-release.json; knowledge-studio-cli is npm-only." + description: "Required when mode=channel. npm dist-tag only (lowercase, digits, dashes), e.g. mcp / plugin / sync-release. bailian-cli binary CDN always overwrites sync-release.json; knowledge-studio-cli and bailian-kb-dsh are npm-only." required: false type: string @@ -28,7 +29,7 @@ concurrency: jobs: publish-stable: - if: inputs.mode == 'stable' + if: inputs.mode == 'stable' && inputs.package != 'bailian-kb-dsh' name: publish stable (${{ inputs.package }}) to npm + binary + tag runs-on: ubuntu-latest environment: production # Required Reviewers gate @@ -83,7 +84,7 @@ jobs: run: node tools/release/publish-stable.mjs ${{ inputs.package == 'knowledge-studio-cli' && '--knowledge' || '' }} publish-channel: - if: inputs.mode == 'channel' + if: inputs.mode == 'channel' && inputs.package != 'bailian-kb-dsh' name: publish channel (${{ inputs.package }}) to npm + binary runs-on: ubuntu-latest permissions: @@ -138,3 +139,49 @@ jobs: BAILIAN_RELEASE_PREFIX: ${{ secrets.BAILIAN_RELEASE_PREFIX }} BAILIAN_STATIC_PREFIX: ${{ secrets.BAILIAN_STATIC_PREFIX }} run: node tools/release/publish-channel.mjs ${{ inputs.package == 'knowledge-studio-cli' && '--knowledge' || '' }} --channel "${{ inputs.channel }}" + + # bailian-kb-dsh is the dsh plugin (downstream host adapter): independent version, + # tsc + tsdown build, npm-only. It shares this workflow's entry UI and setup steps + # but NOT publish-stable.mjs / publish-channel.mjs — those broadcast one version + # across the locked bl package set and produce binary artifacts, neither of which + # applies here. See docs/agents/dsh-plugin.md. + publish-kb-dsh: + if: inputs.package == 'bailian-kb-dsh' + name: publish ${{ inputs.mode }} (bailian-kb-dsh) to npm + runs-on: ubuntu-latest + # stable goes through the Required Reviewers gate, same as the bl stable job; + # channel stays ungated so dist-tag drops need no approval. + environment: ${{ inputs.mode == 'stable' && 'production' || '' }} + permissions: + contents: write # push the bailian-kb-dsh-v tag (stable only) + id-token: write # OIDC for npm Trusted Publishing + provenance + steps: + - name: Require channel input + if: ${{ inputs.mode == 'channel' && inputs.channel == '' }} + run: | + echo "::error::mode=channel requires the workflow input \"channel\" (npm dist-tag, e.g. mcp / plugin). Leave mode=stable if you do not need a dist-tag." + exit 1 + + - uses: actions/checkout@v6 + + - uses: pnpm/action-setup@v6 + + - uses: actions/setup-node@v6 + with: + node-version: "24" + cache: pnpm + registry-url: "https://registry.npmjs.org/" + + - name: Install gitleaks + run: | + set -euo pipefail + GITLEAKS_VERSION=8.21.2 + curl -sSfL \ + "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \ + | sudo tar -xz -C /usr/local/bin gitleaks + gitleaks version + + - run: pnpm install --frozen-lockfile + + - name: publish-kb-dsh + run: node tools/release/publish-kb-dsh.mjs ${{ inputs.mode == 'channel' && format('--channel "{0}"', inputs.channel) || '' }} diff --git a/.gitignore b/.gitignore index 97b436694..00e5056e3 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,7 @@ dist-bin dist-ssr tools/generated .node-version +*.tsbuildinfo *.local diff --git a/AGENTS.md b/AGENTS.md index ac772ed0e..f24cb0240 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,7 @@ monorepo 现在按"纯逻辑 → 运行时框架 → 命令库 → 产品入口" - `packages/commands` — `bailian-cli-commands`,可复用命令实现库,只导出 command,不决定产品路径 - `packages/cli` — `bailian-cli`,完整 `bl` 产品入口;`src/commands.ts` 组装 `bl` 暴露的命令路径 - `packages/kscli` — `knowledge-studio-cli`,Knowledge Studio 专用入口;`src/main.ts` 复用 commands 并重映射为 `kscli` 路径 +- `packages/bailian-kb-dsh` — `bailian-kb-dsh`,**下游宿主适配层**(依赖方向朝外):百炼知识库的 DeepSeek Harness (dsh) 插件,消费 `bl` CLI 与知识库 API,不在上面这条分层链上;版本、构建、发布都独立,见 [docs/agents/dsh-plugin.md](docs/agents/dsh-plugin.md) ### 关键文件 @@ -56,25 +57,26 @@ Skill / 命令手册随 `skills/bailian-*/` 经 `bl skill init` 安装（装齐 按当前任务从下表挑一条进入对应文档: -| 场景 | 何时进入 | 详见 | -| ----------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- | -| 命令增删改 | 增加 / 删除 / 重命名 `bl xxx` 或入口命令路径 | [docs/agents/command-add-remove.md](docs/agents/command-add-remove.md) | -| E2E 测试维护 | 新增/改命令或 e2e 用例、补 help/缺参/dry-run | [docs/agents/cli-e2e-tests.md](docs/agents/cli-e2e-tests.md) | -| 批量压测 | 改/跑多能力并发压测、`test:stress`、fixtures | [docs/agents/stress-batch-tests.md](docs/agents/stress-batch-tests.md) | -| 选项变更 | 给已有命令加 `--flag` 或改默认值 | [docs/agents/command-flag-change.md](docs/agents/command-flag-change.md) | -| 模型上下架 | 增加新模型 / 改默认模型 / 废弃旧模型 | [docs/agents/model-add-remove.md](docs/agents/model-add-remove.md) | -| Skill 文案 / 路由 | 改 SKILL 路由、安装约定、hand-off、hub/领域边界 | [docs/agents/skill-change.md](docs/agents/skill-change.md) | -| 错误文案变更 | 改 `BailianError` 的 message 或 hint | [docs/agents/error-hint-change.md](docs/agents/error-hint-change.md) | -| URL / 渠道变更 | 控制台域名 / 文档站 / 追踪参数 | [docs/agents/url-change.md](docs/agents/url-change.md) | -| 埋点变更 | 改 AEM 命令事件、后端渠道 header、User-Agent | [docs/agents/telemetry-change.md](docs/agents/telemetry-change.md) | -| 鉴权扩展 | 加 OAuth / SSO / 换 token 来源 | [docs/agents/auth-change.md](docs/agents/auth-change.md) | -| 配置项扩展 | 新 env var 或 `~/.bailian/config.json` 字段 | [docs/agents/config-add.md](docs/agents/config-add.md) | -| Profile / 激活 | 改命名 Profile、预设或 `active_config` | [docs/agents/config-profile-change.md](docs/agents/config-profile-change.md) | -| 安装文档 | 改安装、鉴权、验证流程或线上 install 页面 | [docs/agents/install-doc-change.md](docs/agents/install-doc-change.md) | -| 发布 | channel / stable 发布到 npm（CI 驱动） | [docs/agents/publish.md](docs/agents/publish.md) | -| Change Log | 发版说明 / 历史版本说明 | [docs/agents/changelog-write.md](docs/agents/changelog-write.md) | -| 工具链调整 | lint 规则 / 构建配置 / 依赖升级 | [docs/agents/lint-toolchain.md](docs/agents/lint-toolchain.md) | -| Command Pack | 扩展包 / 白名单 / plugin 管理命令 | [docs/agents/command-pack.md](docs/agents/command-pack.md) | +| 场景 | 何时进入 | 详见 | +| ----------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- | +| 命令增删改 | 增加 / 删除 / 重命名 `bl xxx` 或入口命令路径 | [docs/agents/command-add-remove.md](docs/agents/command-add-remove.md) | +| E2E 测试维护 | 新增/改命令或 e2e 用例、补 help/缺参/dry-run | [docs/agents/cli-e2e-tests.md](docs/agents/cli-e2e-tests.md) | +| 批量压测 | 改/跑多能力并发压测、`test:stress`、fixtures | [docs/agents/stress-batch-tests.md](docs/agents/stress-batch-tests.md) | +| 选项变更 | 给已有命令加 `--flag` 或改默认值 | [docs/agents/command-flag-change.md](docs/agents/command-flag-change.md) | +| 模型上下架 | 增加新模型 / 改默认模型 / 废弃旧模型 | [docs/agents/model-add-remove.md](docs/agents/model-add-remove.md) | +| Skill 文案 / 路由 | 改 SKILL 路由、安装约定、hand-off、hub/领域边界 | [docs/agents/skill-change.md](docs/agents/skill-change.md) | +| 错误文案变更 | 改 `BailianError` 的 message 或 hint | [docs/agents/error-hint-change.md](docs/agents/error-hint-change.md) | +| URL / 渠道变更 | 控制台域名 / 文档站 / 追踪参数 | [docs/agents/url-change.md](docs/agents/url-change.md) | +| 埋点变更 | 改 AEM 命令事件、后端渠道 header、User-Agent | [docs/agents/telemetry-change.md](docs/agents/telemetry-change.md) | +| 鉴权扩展 | 加 OAuth / SSO / 换 token 来源 | [docs/agents/auth-change.md](docs/agents/auth-change.md) | +| 配置项扩展 | 新 env var 或 `~/.bailian/config.json` 字段 | [docs/agents/config-add.md](docs/agents/config-add.md) | +| Profile / 激活 | 改命名 Profile、预设或 `active_config` | [docs/agents/config-profile-change.md](docs/agents/config-profile-change.md) | +| 安装文档 | 改安装、鉴权、验证流程或线上 install 页面 | [docs/agents/install-doc-change.md](docs/agents/install-doc-change.md) | +| 发布 | channel / stable 发布到 npm（CI 驱动） | [docs/agents/publish.md](docs/agents/publish.md) | +| Change Log | 发版说明 / 历史版本说明 | [docs/agents/changelog-write.md](docs/agents/changelog-write.md) | +| 工具链调整 | lint 规则 / 构建配置 / 依赖升级 | [docs/agents/lint-toolchain.md](docs/agents/lint-toolchain.md) | +| Command Pack | 扩展包 / 白名单 / plugin 管理命令 | [docs/agents/command-pack.md](docs/agents/command-pack.md) | +| dsh 插件 | 改 `packages/bailian-kb-dsh`、dsh 依赖、插件发布 | [docs/agents/dsh-plugin.md](docs/agents/dsh-plugin.md) | 如果当前任务无法对应任何场景,先按经验完成,然后**回来评估这是不是一类新场景** —— 是就新增 `docs/agents/.md`,把清单沉淀下来。 @@ -84,12 +86,15 @@ Skill / 命令手册随 `skills/bailian-*/` 经 `bl skill init` 安装（装齐 源码包的 `version` 当前保持一致: `packages/core`、`packages/runtime`、`packages/commands`、`packages/cli`、`packages/kscli`。做版本 bump 时一动多动。release 工具当前强校验 / 发布范围以 `tools/release/lib/packages.mjs` 为准;把新包纳入发布前必须同步该清单和 [publish.md](docs/agents/publish.md)。 +**例外**: `packages/bailian-kb-dsh` 不参与这个锁步(独立 `0.1.x`,跟随 dsh rc 节奏),也不在 release 白名单里;它走 `publish.yml` 里 `package=bailian-kb-dsh` 的独立 job(`tools/release/publish-kb-dsh.mjs`)。 + ### 2. 分层边界 - `core` 是纯库:不依赖 `runtime` / `commands` / 产品入口;不调 `process.exit`;新增/改动时不硬编码 `bl` / `kscli` 命令名、控制台 URL 或渠道追踪参数。当前遗留项见 [error-hint-change.md](docs/agents/error-hint-change.md) 与 [url-change.md](docs/agents/url-change.md),触碰相关代码时顺手收敛 - `runtime` 是通用 CLI 框架:可以处理 TTY、help、错误输出、middleware,但不写具体业务命令逻辑 - `commands` 是命令实现库:不决定产品路径;不在 `usageArgs` / `exampleArgs` / hint 里硬编码产品 bin 前缀 - `cli` / `kscli` 是产品层:负责命令路径 map、产品 identity、README、技能 reference、发版入口 +- `bailian-kb-dsh` 在这条链之外:它是别的宿主(dsh)里的插件,只允许依赖 `core`(且当前刻意零依赖),反过来 `core` / `runtime` / `commands` / 产品层**永远不许**依赖它 - URL 集中在 `packages/runtime/src/urls.ts`(用户面控制台)和 `packages/core/src/config/schema.ts` / client 层(API) ### 3. 错误处理边界:CLI 不翻译服务端错误 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e39070800..0d25145a8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,11 +16,17 @@ Developer guide for `bailian-cli` — the official CLI for Aliyun Model Studio ( ``` bailian-cli/ ├── packages/ -│ ├── cli/ # `bailian-cli` — CLI entry, commands, UI -│ └── core/ # `bailian-cli-core` — auth, HTTP, types -├── docs/agents/ # Scenario-based maintenance guides -├── tools/ # Release automation & reference generation -├── AGENTS.md # Contract for AI agents +│ ├── 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 ``` diff --git a/CONTRIBUTING.zh.md b/CONTRIBUTING.zh.md index df9d3ad16..7dad8b592 100644 --- a/CONTRIBUTING.zh.md +++ b/CONTRIBUTING.zh.md @@ -16,11 +16,17 @@ ``` bailian-cli/ ├── packages/ -│ ├── cli/ # `bailian-cli` —— CLI 入口、命令、UI -│ └── core/ # `bailian-cli-core` —— 鉴权、HTTP、类型 -├── docs/agents/ # 场景化维护文档 -├── tools/ # 发版自动化与命令手册生成 -├── AGENTS.md # AI agent 维护契约 +│ ├── 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 ``` diff --git a/docs/agents/dsh-plugin.md b/docs/agents/dsh-plugin.md new file mode 100644 index 000000000..b5f953560 --- /dev/null +++ b/docs/agents/dsh-plugin.md @@ -0,0 +1,125 @@ +# dsh 插件维护（packages/bailian-kb-dsh） + +## 触发条件 + +- 改 `packages/bailian-kb-dsh` 的工具（`kb_search` / `kb_chat`）、服务缓存、settings / 凭据解析 +- 改 web 半（Settings 配置页 React 组件、CSS Modules） +- 升级 `@deepseek-ai/dsh-*` peer 依赖 +- 改插件包名、bundle 声明或产物布局 +- 发布插件到 npm + +## 这个包和其他 packages 不一样的地方 + +它是**下游宿主适配层**：依赖方向朝外（消费 `bl` CLI 与百炼 API，装进 DeepSeek Harness 运行），不是 `core → runtime → commands → 产品入口` 这条链上的一环。由此带来四条与 `packages/*` 通行约定的**故意偏离**： + +| 项 | 本包 | 其他包 | 原因 | +| -------- | ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| 版本 | 独立 `0.1.x` | core/runtime/commands/cli/kscli 锁步 | 跟随 dsh 的 rc 节奏，与 `bl` 发版无关；不在 `tools/release/lib/packages.mjs` 白名单里 | +| 构建 | `tsc` + `tsdown` | `vp pack` | 浏览器半需要 `__ModuleLoader__` banner/footer 与 lightningcss CSS Modules 内联，`vp pack` 产不出 | +| 发布 | `publish.yml` 里 `package=bailian-kb-dsh` job，走 `publish-kb-dsh.mjs` | `publish.yml` 里 `publish-stable/channel.mjs` | 不在 `bailian-cli` 依赖闭包内，版本与构建都不同，不能与 `bl` 共用同一条 script | +| tsconfig | 三个 | 一个 | 见下 | + +## tsconfig 三件套（改动前先读） + +| 文件 | 谁在用 | 作用 | +| --------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------- | +| `tsconfig.json` | oxlint / `vp check` 自动发现 | **纯类型检查**，覆盖 `src` + `tests` 两半：`noEmit` + `jsx: react-jsx` + DOM lib + `allowImportingTsExtensions` | +| `tsconfig.build.json` | `build` script（`tsc -b`） | **产出** node 半到 `dist/`，`exclude: src/web` | +| `tsconfig.web.json` | `build` / `typecheck` script | web 半的**隔离检查**：`types: []`，确保浏览器代码不误用 node 全局 | + +- 不要把 `tsconfig.json` 改成产出配置：`allowImportingTsExtensions` 与 emit 互斥，一改 oxlint 就再也检查不了 `.tsx`（报 TS17004 `--jsx` not set）。 +- web 半的隔离检查挂在 `build` script 里，因为 CI 只跑 `build` / 根 `check` / 根 `test`，`typecheck` script 没有调用点。 + +## 必查清单 + +### A. 包身份（改包名时三处必须一起改） + +- [ ] `package.json` 的 `name` +- [ ] `cordis.patch.yml` 的 `insert[].name`（profile 层栈按这个名字解析插件） +- [ ] `tsdown.config.ts` 的 `PLUGIN_ID`（进 `window.__ModuleLoader__.load({ id })` 与 `