Beisen Shared

beisen-cli 共享规则

本 Skill 是 beisen-cli 所有业务域 Skill 的公共基础设施。每个业务域 Skill 必须在其 SKILL.md 第一行声明：

**CRITICAL — 开始前 MUST 读取 [../beisen-shared/SKILL.md](../beisen-shared/SKILL.md)**

⚠️ 前置检查 — 使用任何业务命令前必须执行

Step 1：检查 CLI 是否安装

beisen-cli version

如果命令不存在或报错，执行安装：

npm install -g beisen-cli

安装后再次验证版本：

beisen-cli version

要求版本满足 >=1.0.1。

Step 2：检查登录状态

beisen-cli auth status

• 输出 authorized → 已认证，可以继续使用
• 输出 unauthorized → 需要完成 Step 3

Step 3：完成登录（仅未认证时执行）

优先使用 SSO 浏览器授权登录：

beisen-cli auth login

该命令会输出一个授权链接，引导用户在浏览器中完成北森 SSO 授权，授权完成后 CLI 自动获取 token。

Agent 处理授权链接：

1. 提取 CLI 输出中的授权 URL
2. 将授权链接直接输出给用户，提示用户点击链接在浏览器中完成北森 SSO 授权
3. 等待用户确认已完成授权
4. 验证登录状态（beisen-cli auth status）
5. 登录成功后：若用户此前有未完成的任务，继续执行后续任务；若无任务，结束当前流程，等待用户的下一条指令

回退方案：若 auth login 等待授权超时失败（如进程被 kill、exit 137，或浏览器未在窗口期内完成授权），改用 API Key 绑定登录：

beisen-cli auth bind --api-key <你的APIKey>

该命令将已有 API Key 绑定到当前设备并保存设备凭据，作为浏览器 SSO 不可用时的替代登录方式（需先从北森管理后台获取 API Key）。

认证与身份

身份模型

beisen-cli 不提供 --as 身份切换标志。执行身份由当前登录账号决定：用谁的账号登录，就以谁的身份执行操作。可查询的数据范围、是否具备管理权限，由北森后台对该账号的授权决定，而非 CLI 参数控制。

检查设备凭据

beisen-cli auth status

预期输出（凭据有效）：

{
  "deviceId": "22cf...0f7a",
  "expiryTime": "2026-11-05T12:31:51Z",
  "status": "valid"
}

• status: "valid" → 设备凭据有效，可继续
• status 为其他值或 token 已过期 → 重新登录

退出登录

beisen-cli auth logout

权限三层模型

第 1 层：身份认证 → beisen-cli auth login（SSO）/ auth bind（API Key 回退）
第 2 层：组织授权 → 企业管理员在后台开启账号的数据访问权限
第 3 层：业务 scope → 具体操作所需的权限范围

说明： beisen-cli 的方法 inputSchema/outputSchema 中未暴露 scope 校验字段，以下 scope 清单为概念模型，供 Agent 理解权限边界；实际能否访问由后台对该登录账号的授权决定。

业务 scope 清单

权限不足处理

当业务命令返回权限相关错误（如 code 非 "200"、isSuccess: false 或 message 提示无权限）时：

1. 从返回信封的 message 字段提取错误原因
2. 向用户说明当前账号缺少哪类数据访问权限及其用途
3. 引导用户联系企业管理员在后台开通对应权限
4. 不要对权限错误反复重试业务命令

安全规则

绝对禁止

• ❌ 不要把 AppKey、AppSecret、access_token 写入 SKILL.md、references 或日志
• ❌ 不要编造 employee_id、org_id、approval_code 等标识符；必须从 CLI 返回中提取
• ❌ 不要在未获用户确认时执行薪酬查询、批量操作、数据导出
• ❌ 不要将人力资源数据（薪酬、绩效、个人信息）发送到任何外部系统
• ❌ 不要在同一轮对话中展示敏感数据后紧跟着询问"是否要分享"
• ❌ 不要在 L3 机密数据场景中跳过二次身份验证

严格要求

• ✅ 所有业务命令默认输出 JSON 结构化格式，可直接解析
• ✅ 危险操作必须先展示操作摘要（操作类型、目标对象、影响范围），用户确认后才执行
• ✅ 单次批量写入/删除不超过 50 条；超过时拆批并逐批确认
• ✅ 所有 CLI 返回的 ID（employee_id、org_id 等）必须替换为可读名称后再展示给用户
• ✅ 涉及 L2/L3 敏感数据的查询结果，提取关键信息后摘要展示，不回显原始 JSON
• ✅ 查询他人数据时，先确认当前账号是否具备对应访问权限

高风险操作门禁协议（exit 10）

说明： beisen-cli的方法均为读操作，不触发写操作门禁。以下 exit 10 / --yes / --dry-run 协议为写方法上线后的预留设计，当前版本不会出现 exit 10。Agent 仍应了解该协议，以便写方法可用时正确处理。

beisen-cli 对高风险写操作有强制确认门禁。当 Agent 不带 --yes 调用高风险命令时，CLI 返回 exit code 10 + 结构化 JSON（exit code 10 即为确认信号，不需要判断 ok）：

{
  "type": "confirmation",
  "subtype": "confirmation_required",
  "risk": "high-risk-write",
  "action": "<command>",
  "hint": "add --yes to confirm"
}

Agent 遇到 exit 10 时必须：

1. 识别 type == "confirmation" 和 subtype == "confirmation_required"
2. 向用户展示操作摘要（操作类型、目标对象、影响范围、风险等级）
3. 等待用户显式回复"确认 / 同意 / 执行"
4. 用户确认后，在原始命令末尾追加 --yes 重试
5. 用户拒绝 → 终止流程，不要擅自改写参数或跳过门禁

绝对不允许：

• 看到 exit 10 就默认加 --yes 静默重试（等于禁用安全门禁）
• 把 confirmation_required 当作网络错误或权限错误处理
• 在用户未明确同意前追加 --yes 重试

HR 数据分级展示策略

数据展示强制规则：

• 查询 L2/L3 级别的他人数据时 → 必须先确认当前账号是否具备管理员访问权限
• L3 数据查询 → 二次身份验证（密码或短信验证码），验证失败直接终止
• 展示 L3 数据后 → 以"薪酬/个人信息已展示，请注意信息安全"作为收尾

JSON 输出契约

业务命令默认输出 JSON，退出码 0 表示 CLI 调用本身成功。CLI 实际输出为两层嵌套结构：

┌─ CLI 调用包装层（外层）──────────────────┐
│  ok: boolean    — CLI 调用是否成功       │
│  identity: string — 执行身份（如 "user"）│
│  data: object   ┌─ 业务信封层（内层）─────┐│
│                 │  code: string          ││
│                 │  data / payload: ...   ││
│                 │  message: string       ││
│                 └────────────────────────┘│
└──────────────────────────────────────────┘

两层各自的职责：

判断业务成功一律看业务信封层的 code == "200"（注意 code 是字符串 "200"，不是数字 200，也不是退出码）。外层 ok: true 仅表示 CLI 调用成功，不代表业务成功。

审批域信封（approval）

{
  "ok": true,
  "identity": "user",
  "data": {
    "code": "200",
    "isSuccess": true,
    "data": [ { "instanceCode": "...", "title": "..." } ],
    "message": ""
  }
}

• 内层 code == "200" 且 isSuccess == true → 业务成功，结果在内层 data 数组
• 内层 code != "200" 或 isSuccess == false → 业务失败，原因在内层 message

知识域信封（knowledge）

{
  "ok": true,
  "identity": "user",
  "data": {
    "code": "200",
    "message": "",
    "payload": {
      "hitKnowledgeList": [ { "title": "...", "summary": "..." } ]
    }
  }
}

• 内层 code == "200" → 业务成功，结果在 payload.hitKnowledgeList
• 内层 code != "200" → 业务失败，原因在内层 message

数据查询域信封（staffservice）

{
  "ok": true,
  "identity": "user",
  "data": {
    "code": "200",
    "data": { "..." : "..." }
  }
}

• 内层 code == "200" → 业务成功，结果在内层 data
• 内层 code != "200" → 业务失败

调用级错误

当 CLI 自身调用失败（未登录、参数缺失、网络异常等），退出码非 0，stderr 输出错误信息。此时外层 ok 可能为 false 或根本不返回 JSON，不属于业务信封，Agent 应按「错误处理通用策略」处理，不要尝试解析 code。

成功判断只看业务信封层：外层 ok: true 仅表示 CLI 调用成功（进程正常退出），不代表业务成功。业务是否成功一律看内层 code == "200"。部分命令的响应可能不含外层 ok/identity 包装（直接返回业务信封），Agent 应以 code 字段为准统一判断。

ID 引用规则

适用于所有 beisen-cli 工具调用，包括 beisen-data-query 中的 SceneTool / SceneToolMessage / SearchFormTool / BusinessDataTool 及所有其他 CLI 工具。

1. 只复制真实值：当工具返回结果包含 id、task_id、record_id、intentionId、menuId 等标识符，你只允许直接复制工具返回 content 中真实存在的值。
2. 严禁编造 ID：严禁自己编造、猜想、拼接任何 id。如果需要传给下一个工具的参数 id 不在刚刚 tool 返回的内容中，禁止调用工具，向用户报错说明缺少 ID。
3. 精确匹配：调用后续工具时，引用的 ID 必须完全和 tool 返回 JSON 字符串中的字符完全一致，大小写、符号不能修改。
4. 就近取用：不要靠记忆记录 id，所有参数值必须来源于最近 tool 角色返回的 JSON 内容。
5. 空值阻断：如果工具返回为空 / 没有需要的 id，停止工具调用，告知用户无法继续。

全局标志

beisen-cli 业务方法不使用 --query/--page/--size/--as 等分散标志，所有方法入参统一通过 --data 以 JSON 字符串承载。分页、筛选条件都写在 --data 的 JSON 内（按各方法 inputSchema 要求）。

不要使用 --as： beisen-cli无身份切换标志，执行身份由登录账号决定。不要使用 --page/--size：分页字段写在 --data JSON 内。

错误处理通用策略

1. 认证失败（未登录 / token 过期，退出码非 0）→ 引导用户重新登录，不重试业务 API
2. 权限不足（code != "200" 且 message 提示无权限）→ 从 message 提取原因，向用户说明并引导联系管理员授权；不重试
3. 参数错误（--data JSON 缺必填字段或格式不符 inputSchema）→ 先查 beisen-cli schema 或对应业务域 references，最多修正 1 次
4. 业务逻辑错误（如"该审批已被处理"、"该员工不在可见范围内"）→ 解释 message 原因，给出下一步建议
5. 网络错误 / 超时 → 最多重试 2 次，间隔递增
6. exit 10 → 按高风险操作门禁协议处理，向用户确认（beisen-cli不会触发，预留）

重试限制： 同一个失败原因最多重试 1 次（网络重试除外），防止 token 消耗和耗时失控。

更新检查

beisen-cli 提供 beisen-cli update 命令用于升级。业务命令输出中不附带版本通知字段。

• 不是每次任务都要查更新
• 先完成用户当前请求
• 如仍相关，再简短告知可运行：beisen-cli update

详细参考

• references/auth.md：认证授权流程详解
• references/security.md：安全规则与门禁协议
• references/error-codes.md：错误码参考与排查流程