---
name: shb-shared
version: "1.1.0"
description: "当用户首次使用 shb-cli、需要登录授权、检查认证状态、切换租户、或遇到 token 过期/401 错误时触发。管理本地 profile（auth login）、OAuth2 登录、token 导入(auth token-import)、租户切换(auth switch-tenant)、权限不足处理与安全规则。"
metadata:
  requires:
    bins: ["shb-cli"]
  cliHelp: "shb-cli --help"
---

# shb-cli 共享规则

本技能指导你如何通过 `shb-cli` 完成 SHB 系统的本地配置与鉴权。所有 SHB 业务模块技能（`shb-paas`、`shb-task` 等）在执行任何调用前都依赖本技能的状态。

**CRITICAL — 执行以下命令前，必须先用 Read 工具读取对应文档：**
- `shb-cli config`（状态查看）/ `auth login` → Read `references/shb-shared-config.md`
- `auth login` / `auth authorize-url` → Read `references/shb-shared-auth-login.md`
- `auth token-import` / `auth logout` → Read `references/shb-shared-token-import.md`

## 唯一推荐路径

面向普通用户时，只推荐这一条主路径：

1. `shb-cli auth login --env <env>` ← 首次使用 & 重新登录均用此命令
2. `shb-cli config` ← 确认 `authenticated: true` 且 `valid: true`
3. 再进入业务模块命令，例如 `shb-cli paas ...` / `shb-cli task ...`

`auth token-import`、`auth authorize-url`、`auth exchange-code` 都属于兼容或排障入口，不要把它们当成普通用户默认路径。

## 二进制定位

下文一律写作 `shb-cli`。执行任何命令前，先验证可用性：

```bash
shb-cli version --json
```

**不可用时**，通过 npm 全局安装：

```bash
npm install -g @publink-ai/cli
```

安装后再次执行 `shb-cli version --json` 确认成功，并检查 `build_env` 字段是否符合预期。

## 首次使用与登录

首次使用只需一步：通过 `auth login` 同时完成环境设置与 OAuth2 授权。

```bash
# 交互终端（CLI 会提示选择环境，再输出浏览器授权链接）
shb-cli auth login

# agent / 非交互执行时，显式传 --env 避免卡在 prompt
shb-cli auth login --env dingtalk
shb-cli auth login --env lark
```

`auth login` 会将 `environment`、`device_id` 写入本地 profile，同时输出浏览器授权链接（在 stderr）。读取输出，提取链接发给用户。

> **没有独立的 `config init` 命令**，`auth login` 已包含首次配置的全部步骤。

详见 [`references/shb-shared-auth-login.md`](references/shb-shared-auth-login.md)。

## 认证

### 身份模型

`shb-cli` 当前只有 **用户身份**：本地 profile 持有一份 `user_access_token`（优先存到 OS keyring，旧明文 token 在加载时自动迁移），所有业务命令都以该用户为操作者。

- 命令的可见数据 = 当前 profile 用户在 SHB 后端的可见范围。
- **没有 bot 身份**，PaaS 写操作也以当前用户提交。
- 多租户场景使用 `auth switch-tenant`，而不是同时维持多个 profile。

### 状态查看

```bash
shb-cli config
```

输出中需确认包含：

- `authenticated: true`
- `valid: true`

> `shb-cli config` 是唯一的状态查看命令，**不存在 `auth status`**。

详见 [`references/shb-shared-config.md`](references/shb-shared-config.md)。

### Agent 代理发起 OAuth2 授权（推荐）

当你作为 AI agent 需要帮用户完成认证时：

1. **先询问用户使用的登录环境**，例如：

   > "请问您使用的是哪个环境登录？钉钉端（dingtalk）、飞书端（lark）、独立端（standalone）还是企业微信端（wecom）？"

2. 获得环境后，用 background 方式执行登录，将 stderr 中的授权链接发给用户：

   ```bash
   shb-cli auth login --env <用户选择的环境> --no-browser
   ```

3. 用户完成浏览器授权后，执行 `shb-cli config` 确认 `authenticated: true` 且 `valid: true`。

详见 [`references/shb-shared-auth-login.md`](references/shb-shared-auth-login.md)。

### 租户切换

**仅限 `standalone` 环境（独立端）使用。** 其他环境执行时 CLI 会报错。

```bash
shb-cli auth switch-tenant --list
shb-cli auth switch-tenant --tenant-name <tenant-name> --password <password>
shb-cli auth switch-tenant --tenant-index <1-based-index> --password <password>
```

把租户切换视为共享会话管理的一部分，而不是某个业务模块的命令。

## 权限不足处理

遇到 401 / `token is empty` / `valid: false` 时，按下面顺序处理：

1. `shb-cli config` 复核当前 profile 的 `environment`、`base_url` 与认证状态。
2. 如果用户给出新的 token，优先 `auth token-import`。
3. 否则用 `auth login [--env ...]` 重新走浏览器授权会话。
4. 不要要求普通用户提供 `org-code`、`domain`、`authorize-url` 这类底层参数，这些只用于调试或兼容场景。

## 安全规则

- **禁止把 token 明文写入终端输出或仓库文件**。
- **写入 / 删除 / 状态变更操作前必须先和用户确认**（具体清单见 `shb-paas` 技能）。
- 复杂 payload 一律走 `--file` / `--payload-file`，不要把长 JSON 拼到命令行。
- 优先使用 `--dry-run`（支持的命令）预览危险请求。

## 版本检查

每次执行 `shb-cli version --json` 后，如果输出中包含 `_notice.update: true` 字段，主动提示用户：

> "检测到 shb-cli 有新版本。建议运行 `npm update -g @publink-ai/cli` 更新。"

## References

- [`references/shb-shared-config.md`](references/shb-shared-config.md) —— `shb-cli config`（查看 profile/auth 状态）、`--profile` 全局 flag
- [`references/shb-shared-auth-login.md`](references/shb-shared-auth-login.md) —— OAuth2 推荐登录（CLI Auth Session）、SSO、`exchange-code`
- [`references/shb-shared-token-import.md`](references/shb-shared-token-import.md) —— `auth token-import` / `auth logout`