Ihr Shared

---
name: ihr-shared
description: "iHR360 CLI 共享规则：ihr-cli 运行时、auth/config 规则、JSON 输出协议、时间处理与错误排查。"
---

# ihr-shared (v1)

## 作用

本 skill 不直接承载业务动作，只负责说明 `ihr-cli` 相关命令的共享规则：

1. CLI 运行时要求
2. auth/config 配置规则
3. 默认身份上下文约定
4. JSON 输入输出协议
5. 相对时间处理规则
6. 常见错误类型

## 运行时规则

### 1. CLI 运行时

1. 当前业务动作通过 `ihr-cli` 执行。
2. 结构化业务命令通常挂在 `ihr-cli <domain>` 下，例如 `ihr-cli base`、`ihr-cli conference`。
3. 原生网关调用器挂在 `ihr-cli interface` / `ihr-cli ihr-interface` 下。
4. 本目录是 `ihr-cli` 随包分发的共享 skill 位置。

#### 1.1 安装 ihr-cli

如果 `ihr-cli` 尚未安装，先从官方 CDN 获取最新稳定版并安装。完整安装指南参见 <https://cdn-txtoqiniu.ihr360.com/ihr-cli/agent-install.md>，以下为快速摘要：

**Linux / macOS**：
```bash
# 1. 获取最新版本号
VERSION=$(curl --http1.1 -fsSL "https://cdn-txtoqiniu.ihr360.com/ihr-cli/latest.json?ts=$(date +%s)" | python3 -c 'import json,sys; print(json.load(sys.stdin)["version"])')

# 2. 下载并运行安装脚本（SKILLS_DIR 默认 $HOME/.ihr-cli/skills）
curl --http1.1 -fsSL "https://cdn-txtoqiniu.ihr360.com/ihr-cli/v${VERSION}/install.sh" -o "/tmp/ihr-cli-install.sh"
bash "/tmp/ihr-cli-install.sh" --version "${VERSION}" --channel stable --skills-dir "$HOME/.ihr-cli/skills" --yes
```

**Windows PowerShell**：
```powershell
$ProgressPreference = "SilentlyContinue"
$version = (Invoke-RestMethod -UseBasicParsing "https://cdn-txtoqiniu.ihr360.com/ihr-cli/latest.json").version
$script = Join-Path $env:TEMP "ihr-cli-install.ps1"
Invoke-WebRequest -UseBasicParsing "https://cdn-txtoqiniu.ihr360.com/ihr-cli/v$version/install.ps1" -OutFile $script
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $script -Version $version -Channel stable -SkillsDir "$HOME\.ihr-cli\skills" -Yes
```

**验证安装**：
```bash
ihr-cli --version          # 确认版本号输出
ihr-cli config init --env work100-prod   # 初始化本专家预设环境
ihr-cli auth verify        # 检查登录状态
```

> 安装脚本会从 `https://cdn-txtoqiniu.ihr360.com/ihr-cli/` 下载二进制并写入 `$HOME/.ihr-cli/`。如已安装旧版本，在安装命令末尾追加 `--update`（Linux/macOS）或 `-Update`（Windows）进行更新。

### 2. 配置加载

1. 推荐先执行 `ihr-cli auth login`，按终端打印的授权链接在浏览器完成登录授权。
2. CLI 会打印 `verification_uri_complete` 和 `user_code`，并在交互环境下尽力自动打开浏览器；无论是否自动打开，默认都会持续轮询授权结果。
3. 授权成功后 CLI 会保存 `apiKey/baseUrl/user context`，`base`、`conference`、`ihr-interface` 等动作默认复用当前 profile 的配置与登录态。
4. `config init --env <env>` / `config init --base-url <url>` 与 `auth login --api-token-stdin` 继续作为手工 token 兼容入口。
5. 当前不再以 `.env` 作为主路径。
6. `auth login` 必须能写入本机登录态目录：优先使用 `IHR_CLI_CONFIG_DIR`，未设置时为 `~/.ihr-cli`，凭证文件在其 `credentials/ihr-cli/` 子目录下。
7. 如果当前 Agent/WorkBuddy 命令运行在只读沙盒中，出现 `credential_store_error`、`permission denied`、无法创建/写入 `credentials` 等错误时，必须停止；不要在同一沙盒内反复 `mkdir` 或重新执行 `auth login`。
8. 沙盒无法写入时，可以先在沙盒中执行 `ihr-cli auth login --no-wait --json` 获取 `verification_uri_complete`、`user_code`、`device_code`，立即把授权链接展示/打开给用户；随后必须在宿主机终端执行 `ihr-cli auth login --device-code <device_code>` 保存凭证。
9. 宿主机终端登录成功并确认 `ihr-cli auth verify` 通过后，Agent 再继续业务命令。

推荐初始化方式：

```bash
ihr-cli auth login
```

发布包内置当前打包环境的默认 `baseUrl` 和 `authCenterUrl`。如果需要切换业务 `baseUrl` 默认值，使用 `ihr-cli config init --env prod|uat|qa2|dev|work100-prod|work100-uat|work100-qa2`；如果需要临时切换登录入口环境，使用 `ihr-cli auth login --env prod|uat|qa2|dev|work100-prod|work100-uat|work100-qa2`；如果只想覆盖认证中心地址，使用 `--auth-center-url`。当前回归测试只使用 `qa2` 和 `work100-qa2`。

非交互或 Agent 分回合场景：

```bash
ihr-cli auth login --no-wait --json
ihr-cli auth login --device-code <device_code> --no-browser
```

如果第一次 `--no-wait --json` 使用了 `--auth-center-url` 或 `--env`，继续轮询时也要携带同一登录入口参数，避免轮询到不同 auth-center。

手工 token 兼容方式；回归测试默认不走此路径：

```bash
ihr-cli config init --env qa2
ihr-cli config init --base-url https://qa2.ihr360.com
printf '%s' "$IHR360_API_TOKEN" | ihr-cli auth login --api-token-stdin
```

### 3. 身份上下文

1. 业务语义上默认依赖服务端注入的身份上下文。
2. CLI 会自动从本地 credential store 读取 token，并注入请求头。
3. 领域 skill 不应把鉴权细节作为主流程重点说明。

## JSON 协议

### 1. 输入方式

当前 `ihr-cli` 同时存在两类输入模型：

1. 模板化 shortcut 的分项参数输入，例如 `base`、`conference`
2. 原生 interface 的 curl 风格输入，例如 `-H / -q / --json / --form`

业务动作文档应按自己所属模型说明输入方式。

模板化 shortcut 通用支持以下调试与输出参数：

| 参数 | 说明 |
|------|------|
| `--json <json>` | 直接传入 JSON 请求体，不能和分项参数混用 |
| `--stdin` | 从标准输入读取 JSON 请求体，不能和分项参数混用 |
| `--output-file <file>` | 将最终 JSON 结果额外写入指定文件 |

### 2. 输出结构

模板化 shortcut 通常输出单行 JSON：

```json
{"success":true,"command":"queryConference","request":{},"response":{}}
```

原生 `ihr-interface` 也输出单行 JSON，但 envelope 为：

```json
{"success":true,"command":"interface +post","request":{},"response":{}}
```

共享规则：

1. `success` 表示 CLI 动作是否执行成功
2. `command` 表示本次动作语义，例如 `queryConference` 或 `interface +post`
3. `request` 表示 CLI 最终构造出的请求信息
4. `response` 表示服务端响应信息
5. 对标准业务接口，业务数据通常仍从 `response.data` 读取

### 3. 错误结构

统一错误结构：

```json
{"success":false,"command":"queryConference","error":{"code":"CONFIG_ERROR","message":"配置缺失","details":{}}}
```

## 时间处理规则

1. 遇到“今天、昨天、上周、最近30天、去年年底到今年年初”这类相对时间，不要心算。
2. 先基于系统时间换算出绝对日期，再传给业务动作。
3. 时间字符串优先使用：
   1. `yyyy-MM-dd`
   2. `yyyy-MM-dd HH:mm:ss`

## 常见错误类型

| 错误码 | 含义 |
|---|---|
| `CONFIG_ERROR` | 配置缺失或配置格式非法 |
| `AUTH_REQUIRED` | 当前 profile 尚未 login |
| `ARGUMENT_ERROR` | 参数冲突、缺失或范围非法 |
| `VALIDATION_ERROR` | 原生 interface 参数非法 |
| `INVALID_JSON` | `--json` / `--stdin` 输入不是合法 JSON |
| `IO_ERROR` | 读取标准输入、上传文件或写输出文件失败 |
| `OUTPUT_ERROR` | 输出序列化失败 |
| `NETWORK_ERROR` | 网络请求失败 |
| `HTTP_ERROR` | 服务端返回非 2xx |
| `HTTP_INVALID_JSON` | 服务端响应不是合法 JSON |
| `UNEXPECTED_ERROR` | 未归类异常 |

## 使用方式

`ihr-cli` 的相关 skill 执行前，都应先理解本共享规则，再读取对应的 reference 文档。