Ihr Shared

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：

# 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：

$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

验证安装：

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 再继续业务命令。

推荐初始化方式：

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 分回合场景：

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 兼容方式；回归测试默认不走此路径：

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 通用支持以下调试与输出参数：

2. 输出结构

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

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

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

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

共享规则：

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

3. 错误结构

统一错误结构：

{"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

常见错误类型

使用方式

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