beisen-shared

beisen-cli 共享规则

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

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

⚠️ 前置检查 — 仅会话首次对话时执行

全局 CLI 版本基线：所有 beisen-* Skill 统一要求 beisen-cli >= 1.0.5（在本 Skill requires-cli 字段中声明）。各业务域 Skill 的版本要求应与 shared 保持一致，不低于 1.0.5，便于独立加载时自校验。

Step 1：检查 CLI 是否安装（仅会话首次对话）

在整个 Agent 会话中，只在第一次对话时执行版本检查。 后续对话轮次直接执行业务命令，无需重复检查版本。

beisen-cli version

预期输出（退出码 0，版本号以实际为准）：

beisen-cli version 1.0.5

如果命令不存在或报错，先检查 Node.js 版本（要求 ≥ 22.20.0）：

node -v

若版本不满足，停止并提示用户先升级 Node.js。Node.js 就绪后执行安装：

npm install -g beisen-cli

CLI 安装完成后，安装 Skill 技能包（必需，使 AI Agent 能识别 beisen-* 业务能力）：

安装后再次验证版本：

beisen-cli version

Step 2：直接执行业务命令（无需主动检查登录状态）

不再主动调用 beisen-cli auth status 检查登录状态。 CLI 内部会在每次业务命令执行时自动校验认证状态，若凭据有效则正常返回数据，若凭据失效则返回结构化认证错误。

直接执行用户的业务命令即可。

Step 3：响应式登录（仅在 CLI 返回认证错误时触发）

当业务命令返回以下错误时，触发登录流程：

识别规则：CLI 返回信息中同时包含 HTTP 401 和 CLI_AUTH_005 → 表示凭据失效，需要重新登录。

3a. 判断凭据状态，选择登录路径

收到 CLI_AUTH_005 后，先执行一次 beisen-cli auth status 判断本地凭据状态，据此选择路径：

为什么 status=valid 时不要再做 SSO：本地 token 未过期但服务端已不认可，SSO 登录会复用同一设备 ID 生成新的 device request，但服务端可能仍拒绝该设备的旧关联。API Key 绑定是独立的认证路径，可绕过此问题。

3b. 路径 A — SSO 浏览器授权登录

该命令会输出一个授权链接，等待用户在浏览器中完成北森 SSO 授权。

Agent 处理授权链接：

1. 提取 CLI 输出中的授权 URL（用正则 https?://[^\s]+ 匹配输出中以 https:// 开头的完整 URL）
2. 立即将授权链接输出给用户，提示点击链接在浏览器中完成授权。必须提醒用户：授权链接有效期为 10 分钟，请尽快完成
3. 等待用户确认已完成授权（登录命令会阻塞直到授权完成或超时）
4. 登录成功后：重新执行此前因认证失败的业务命令

若 SSO 授权超时失败（输出含"授权超时"或"CLI_AUTH_001"）→ 立即切换到路径 B（API Key 绑定），不要再重试 SSO。

3c. 路径 B — API Key 绑定登录

当 SSO 不可用或凭据陈旧时，使用 API Key 绑定：

1. 告知用户：「当前 SSO 登录无法完成，请改用 API Key 方式。请在北森 web 端获取 API Key：右上角人员头像 → 个人设置 → API Key管理 → 创建API Key，然后将 API Key 发给我。API Key 格式示例：q/oP*xxx4w== 」
2. 用户提供 API Key 后，执行绑定命令：

   beisen-cli auth bind --api-key <用户提供的APIKey>
3. 绑定成功后：重新执行此前因认证失败的业务命令

3d. 认证流程禁止事项

• ❌ 禁止 auth logout 后再 auth login：logout 会清除本地凭据，若新 login 又失败则用户陷入无凭据状态
• ❌ 禁止连续多次 auth login：SSO 超时后直接切换路径 B，不要反复生成授权链接
• ❌ 禁止在 status=valid 时重复 SSO 登录：见 3a 表格，直接走路径 B
• ❌ 禁止对同一 401 错误重试业务命令：先完成登录/绑定，再重试业务命令

认证与身份

身份模型

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

认证状态检查（按需）

认证状态由 CLI 内部自动校验，Agent 无需主动调用 beisen-cli auth status。仅当 CLI 返回 HTTP 401 + CLI_AUTH_005 时才触发登录流程（见「前置检查 Step 3」）。

如需手动排查认证问题，可使用：

beisen-cli auth status

预期输出（凭据有效）：

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

注意：status: "valid" 仅表示本地凭据未过期，不代表服务端仍认可该凭据。 若 auth status 返回 valid 但业务命令仍报 CLI_AUTH_005，说明服务端已撤销该凭据（可能因密码变更、管理员操作、设备策略变更等），此时应直接走 API Key 绑定（Step 3 路径 B），不要再尝试 SSO 登录。

退出登录

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 结构化格式，可直接解析
• ✅ 所有 CLI 返回的 ID（employee_id、org_id 等）必须替换为可读名称后再展示给用户
• ✅ 涉及 L2/L3 敏感数据的查询结果，提取关键信息后摘要展示，不回显原始 JSON
• ✅ 查询他人数据时，先确认当前账号是否具备对应访问权限

写操作门禁协议（预留）：当前版本所有 CLI 方法均为读操作，不触发写操作门禁。写方法上线后的 exit 10 强制确认协议与批量写规则详见 references/write-protocol.md [blocked]。

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）

注意：beisen-cli knowledge 命令使用与其他命令不同的成功标准——code == "0"表示成功，非 "0" 表示异常。其他所有命令仍以 code == "200"（字符串）为成功标准。

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

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

数据查询域信封（staffservice）

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

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

调用级错误

当 CLI 自身调用失败（认证失效返回 HTTP 401 + CLI_AUTH_005、参数缺失、网络异常等），退出码非 0，stderr 输出错误信息。此时外层 ok 可能为 false 或根本不返回 JSON，不属于业务信封。认证失效按「错误处理通用策略」第 1 条处理（触发响应式登录），其他错误按对应条目处理，不要尝试解析 code。

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

输出格式约束（仅适用于 recruitment / interview）

以下输出约束仅针对 beisen-cli recruitment 和 beisen-cli interview 域命令，其他 Skill 按各自输出规则处理：

• 禁止生成 JSON 文件：不得将查询结果以 JSON 文件形式输出给用户。
• CSV 表头必须使用中文：生成 CSV 文件时，表头禁止使用英文字段名（如 name、educationLevel、phaseStatus），必须使用中文（如"姓名""学历""阶段状态"）。

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 要求）。

注意：同一 API 组下的不同子命令可能使用不同的参数标志。例如 beisen-cli staffservice employeeData 组中，searchFormTool 和 sceneToolMessageForCLI 使用 --params，而 businessDataTool 使用 --data。调用前请查阅对应 Skill 文档确认具体用法。

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

日期参数格式

不同 CLI 子命令的日期参数格式由各自 inputSchema 决定，Agent 应以各 Skill 命令文档为准。常见格式速查：

注意：禁止将一种命令的日期格式直接套用到另一种命令。拼入 --data / --params 前，必须按目标命令 inputSchema 要求的格式转换。

错误处理通用策略

1. 认证失效（CLI 返回 HTTP 401 + error_code: "CLI_AUTH_005"）→ 按「前置检查 Step 3」处理：先 auth status 判断凭据状态，status=valid 走路径 B（API Key 绑定），status 非 valid 走路径 A（SSO 登录）。SSO 超时或失败后立即切路径 B，不再重试。整个认证流程最多 1 轮 SSO + 1 轮 API Key 绑定，若均失败则告知用户联系管理员
2. 权限不足（code != "200" 且 message 提示无权限）→ 从 message 提取原因，向用户说明并引导联系租户管理员授权及购买安装相关的产品；不重试
3. 参数错误（--data JSON 缺必填字段或格式不符 inputSchema）→ 先查 beisen-cli schema 或对应业务域 references，最多修正 1 次
4. 业务逻辑错误（如"该审批已被处理"、"该员工不在可见范围内"）→ 解释 message 原因，给出下一步建议
5. 网络错误 / 超时 → 最多重试 2 次，间隔递增
6. exit 10 → 按 references/write-protocol.md [blocked] 的高风险写操作门禁协议处理，向用户确认（当前版本不会触发，预留）

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

更新检查

检查是否有新版本：

beisen-cli update --check

该命令输出当前版本与最新版本的对比信息。

升级流程

升级前必须先确认版本，告知用户后再执行：

# 1. 检查当前版本
beisen-cli version
# 2. 检查最新版本
beisen-cli update --check

用户确认后，升级 CLI：

npm update -g beisen-cli

同步升级 Skill 技能包（skills add 是幂等的，重复执行会覆盖为最新版本）：

升级后验证：beisen-cli version

升级提醒策略

• 不是每次任务都要查更新
• 先完成用户当前请求
• 任务结束后，如仍相关，再简短告知可运行：beisen-cli update --check
• 不要在任务执行中途打断用户去做升级

详细参考

• references/auth.md [blocked]：认证授权流程详解
• references/security.md [blocked]：安全规则
• references/write-protocol.md [blocked]：高风险写操作门禁协议（预留）
• references/error-codes.md [blocked]：错误码参考与排查流程