@lark-people/cli 0.0.0-beta.1

package/skills/people-corehr-prehire/references/templates.md

@@ -0,0 +1,202 @@
+# 命令、模板、消歧规则
+
+## 核心命令
+
+### 1. 获取 Option Fields（可返回字段）
+
+```bash
+people-cli corehr +prehire-fields-query \
+  --accept-language zh-CN \
+  --format json
+```
+
+- 接口：`GET /open-apis/corehr/v2/pre_hires/optional_field`
+- 用途：确定 `+prehire-search --fields` 可以请求哪些返回字段。
+- 搜索前必须先执行；用户未指定返回字段时，可不传 `--fields`，使用命令默认字段。
+
+### 2. 获取 Filter Fields（可筛选字段与可选值）
+
+```bash
+people-cli corehr +prehire-filter-options-query \
+  --accept-language zh-CN \
+  --format json
+```
+
+- 接口：`GET /open-apis/corehr/v2/pre_hires/filter_field`
+- 用途：确定 `+prehire-search --common-filters` 的筛选左值、右值来源和本地枚举 options。
+- 搜索前必须在 Option Fields 之后执行；不要根据经验猜测筛选字段或枚举值。
+
+### 3. 查询待入职数据
+
+```bash
+people-cli corehr +prehire-search \
+  --fields "<aliases_csv>" \
+  --common-filters '<json_array>' \
+  --accept-language zh-CN \
+  --format json
+```
+
+- 接口：`POST /open-apis/corehr/v2/pre_hires/retrieve`
+- `--fields` 只传别名（中文/英文/短 api_name）。
+- 命令端默认始终携带 `preferred_name` / `worker_id` / `hire_date`，**禁止**重复追加。
+- `common_filters` 为空时自动追加 `{"api_name":"stage_id","values":["preboarding","day_one"]}`。
+- 执行后检查输出末尾的 `Has more` 与 `Next page: --page-token <token>`。
+
+### 4. 远程数据源 name→ID（由 `+prehire-search` 内部完成）
+
+当 `--common-filters` 使用 `<api_name>:name` 时，`+prehire-search` 会在命令内部直接调用
+`POST /open-apis/corehr/v2/common/query_id_by_name` 做 name→ID 解析。AI **不要**单独调用其它命令预解析 ID。
+
+`field_api_name` / `target_object_api_name` 由代码根据 `filter_field.option_src` 与 `api_name` 推导：
+
+- `department_id` → `field_api_name=department`，`target_object_api_name=department`
+- `position_id` → `field_api_name=position`，`target_object_api_name=position`
+- `direct_manager_id` / `dotted_line_manager_id` / `offer_hr_id` → 去掉 `_id` 作为 `field_api_name`，`target_object_api_name=employment`
+
+## stage_id 语义
+
+`stage_id` 是入职流程阶段，`option_src=passthrough`（透传）。默认值 `["preboarding","day_one"]`。
+
+| 值 | 中文含义 |
+| --- | --- |
+| `preboarding` | 入职进行中 |
+| `day_one` | 入职准备就绪（默认待入职口径之一，不等同于流程已完成） |
+| `completed` | 入职流程已完成（已入职） |
+| `withdrawn` | 撤销/撤回 |
+
+口径：
+
+- 「今年入职的员工」→ `completed`，按需扩展。
+- 「今年已入职的员工」→ `completed`，按需扩展。
+- 「入职流程全部走完」→ `completed`。
+- 「放弃入职/撤回」→ `withdrawn`。
+- 用户**未显式**指定 → 用命令默认（不要自行覆盖）。
+- 用户**显式**指定 → 直接传，不再附加默认。
+
+## 强约束消歧规则
+
+### 社保城市 ≠ 工作地点
+
+- `social_security_city` **只是可返回字段**，`filter-fields.md` 中**没有**对应可筛选 `api_name`。
+- 用户要按社保城市筛 → 直接回复「社保城市不支持作为筛选条件」，**禁止**改用 `work_location_id` 兜底。
+- 「工作城市」与「工作地点」**同义** → 统一映射 `work_location` / `work_location_id`，无需澄清。
+
+### 任职公司 vs 合同主体（两组同义、组间互斥）
+
+- 「任职公司」=「所属公司」→ `service_company` / `service_company_id`
+- 「公司主体」=「合同主体」→ `company` / `company_id`
+- 两组是**完全不同的字段**，**禁止**互相替代或兜底。
+
+## 单次查询原则（强约束）
+
+每条用户消息**只发起一次** `+prehire-search`。
+
+| 用户意图 | 是否续拉 / 翻页 |
+| --- | --- |
+| 普通查询（"查一下…"、"看下…"、"哪些…"） | **否**：跑一次拿默认 20 条，原样汇报 `total_number` 与 `Has more` |
+| 显式要全量（"全部 / 拉完 / 都列出来 / all"） | **是**：先 `--page-size 100` 再循环 `--page-token`，受 `total_number ≤ 1000` 守卫约束 |
+| 显式分页（"翻页 / 继续 / 下一页 / 第 N 页 / 更多"） | **是**：复用上次返回的 `--page-token` 续拉一次 |
+| 仅扩大返回字段（"再加上 X 字段"） | **是**：保留筛选条件重跑一次，不要单独再翻页 |
+
+禁止动作：
+
+- 用户没要全量时**禁止**主动调高 `--page-size`（命令默认 `20`，保持默认）。
+- 用户没要翻页时**禁止**主动用 `--page-token` 续拉，即使 `Has more: true`。
+- 用户没要重跑时**禁止**因为"返回字段不全 / 想看更多"自行复跑。
+- `Has more: true` 时仅原样转述给用户：「还有更多结果，需要时回复『继续』即可」。
+
+## 输出与过程信息
+
+默认回复用户时，只输出最终结论。默认禁止展示：
+
+- 内部思考、字段匹配草稿、消歧推理过程；
+- 命令构造草稿（`people-cli ...`、`--common-filters '...'`）；
+- shortcut 名、内部 `api_name`、`option_src`、`sub_field` 路径；
+- 元数据加载日志、本地选项缓存命中信息、debug 输出。
+
+允许展示：
+
+- 结果摘要（自然语言一句话，含 `total_number`）；
+- 关键字段表（姓名 + 工号 + 用户要求的字段）；
+- 个人信息对象按 [必须显式回传给用户的元信息](#必须显式回传给用户的元信息) 收敛；
+- `Has more: true` 时一句提示「需要更多请回复『继续』」；
+- 命令报错时只转述错误**业务含义**与下一步建议，不贴原始 stderr / 调用栈。
+
+> 用户主动要「看下你刚才执行的命令 / 用了哪些字段 / 调试」时才可暴露技术细节，且仅提供该次问答必需的最小子集。
+> 用户主动要「原始数据 / 原始输出」时，必须直接提供 CLI 原始输出；不要再做字段映射、摘要、脱敏或二次整理。
+
+## 「可看不可筛」字段执行守卫
+
+用户要筛的字段不在 `filter-fields.md`、但在 `return-fields.md` 中（典型：社保城市）时，**禁止**直接拉全量本地筛选，必须按 `troubleshooting.md` 分支 A 执行：
+
+
+1.第一次调用务必带 `--page-size 1` + 业务过滤条件，**最小代价探查 `total_number`**。
+2`total_number ≤ 1000` → 才可分页拉全量（`--page-size 100` + 复用 `--page-token`），客户端按目标字段值筛选展示。
+3`total_number > 1000` → **立即停止**，提示用户追加更精确条件。**禁止**继续翻页。
+
+## 输出规范
+
+`+prehire-search` 输出已被 Shortcut 标准化：
+
+- `names` → `name`，`preferred_names` → `preferred_name`
+- `custom_fields[].value` 中的 JSON 字符串已被反序列化
+- 递归过滤空对象 `{}` 与 `nil`；保留空字符串 `""`、空数组 `[]`、`false`、`0`
+- 末尾包含 `Next page: --page-token <token>` / `Has more: true|false`
+
+回复用户时：不忽略分页提示；不把未返回字段说成"为空"；保留默认字段（姓名/工号/入职日期）。
+
+### 必须显式回传给用户的元信息
+
+- **`total_number`**：响应中只要存在 `total_number` 字段，**必须**在回复正文中显式告知用户，例如「本次共匹配 357 人」。不允许仅在表格里暗示，也不允许略过。
+- **个人信息对象**（典型形态：`{avatar, display_name, employee_number, id, name}`，常见于 `direct_manager` / `offer_hr` / `recruiter` 等字段）：回复时**只需要**呈现 `display_name`（缺失时退回 `name`）+ `employee_number`，例如「直属上级：刘明臻（工号 940610）」。**禁止**输出 `avatar` URL、`id` 长串。
+
+## 快速模板
+
+### 模板 1：按部门 ID 筛选
+
+```bash
+people-cli corehr +prehire-search \
+  --common-filters '[{"api_name":"department_id","values":["7552796827847525896"]}]' \
+  --format json
+```
+
+### 模板 1b：按部门名称筛选（命令端自动 name→ID）
+
+```bash
+people-cli corehr +prehire-search \
+  --common-filters '[{"api_name":"department_id:name","values":["corehr"]}]' \
+  --format json
+```
+
+### 模板 2：部门 ID + 直属上级姓名 + 自定义返回字段
+
+```bash
+people-cli corehr +prehire-search \
+  --fields "部门,直属上级,入职方式,工作国家/地区" \
+  --common-filters '[{"api_name":"department_id","values":["7552796827847525896"]},{"api_name":"direct_manager_id:name","values":["张三"]}]' \
+  --accept-language zh-CN \
+  --format json
+```
+
+### 模板 3：按入职日期区间筛选
+
+```bash
+people-cli corehr +prehire-search \
+  --common-filters '[{"api_name":"onboard_date_range","values":["2026-05-01","2026-06-04"]}]' \
+  --format json
+```
+
+## 搜索构造细则
+
+### `--common-filters`
+
+- 所有条件统一放进数组。
+- 每项严格 `{"api_name": "...", "values": [...]}` 结构；**禁止** `{"<field>": [...]}` 简写。
+- 用户显式跨阶段时，必须明确告知"默认会限制到 preboarding/day_one，已按你的要求覆盖"。
+
+### `--fields`
+
+- 只追加用户额外要求的字段，**只能传别名**。
+- 多个别名用逗号拼接，命令端自动展开/去重/合并默认字段。
+- 不允许带点号嵌套路径。
+- 接口报 `1000` 错误：先怀疑别名命中过多/字段过多，按二分法缩小定位，**不要**继续扩大字段范围。

package/skills/people-corehr-prehire/references/troubleshooting.md

@@ -0,0 +1,93 @@
+# pre_hire 排错与歧义消解
+
+> 本文档由 `SKILL.md` 引用，集中沉淀 `+prehire-search` 各类错误的强约束处理流程。
+> 任何与本文档冲突的猜测、自动重试、字段降级行为都视为违规。
+
+## 错误模式速查表
+
+| 错误模式 | 修复 |
+| --- | --- |
+| 跳过 `+prehire-fields-query` / `+prehire-filter-options-query` 直接搜索 | 立即停止，按标准流程先获取 Option Fields 和 Filter Fields |
+| `--fields` 里写了带点号的嵌套路径（含 `.`） | 改成 `references/return-fields.md` 中的别名（`name_zh` / `name_en` / `alias`） |
+| 用户字段不在 `references/return-fields.md` 仍硬拼别名 | 直接告知不支持，禁止猜测 |
+| 把"技术部"/"张三"/"岗位 A"直接放进 `values` 但忘了加 `:name` | `api_name` 后追加 `:name`（如 `department_id:name`）；命令端会在 `+prehire-search` 内部调用 `query_id_by_name` 解析 |
+| 用户给的是纯数字 ID 还硬加 `:name` | 去掉 `:name`，让命令端原样透传 |
+| 把展示字段当筛选字段 | 返回字段看 `return-fields.md`；筛选字段看 `filter-fields.md`，二者独立匹配 |
+| 把 `common_filters` 写成 `{"stage_id":[...]}` | 必须为 `{"api_name":"stage_id","values":[...]}` |
+| 接口返回 `1000` 仍继续追加字段 | 二分法缩小 `--fields` 定位非法字段 |
+| 用户明确要所有字段 | 按 `return-fields.md` 全字段导出口径拼接本次支持的别名；用户未明确要全量时不要擅自扩大字段 |
+| 枚举值（如入职地点、工作地点）匹配失败 | 走「枚举值匹配失败」流程：展示候选 → 让用户选 → 禁止自动重试 |
+| 用户指定的筛选字段不在 `filter-fields.md` 支持列表 | 走「不支持筛选字段的分流处理」流程（A/B 分支） |
+| `matches multiple options` / `matches multiple records` 多候选命中 | 走「多候选命中」流程：AI 先消歧，置信度不足让用户选 |
+
+## 枚举值匹配失败的处理流程
+
+触发条件：命令返回类似 `"failed to resolve onboard_location_id value \"北京大兴\": no matching option (supported names: ...)"`。
+
+1. **提取支持的选项列表**：从错误信息中解析出所有支持的枚举值名称。
+2. **向用户展示选项**：将支持的选项分组展示（如按地区、类型等），便于用户选择。
+3. **请求用户确认**：询问用户是否需要从支持的选项中选择，或确认输入的值是否正确。
+4. **禁止自动重试**：**不允许**自动尝试其他可能的值（如用户输入"北京大兴"失败后，不要自动尝试"北京"），必须由用户明确确认。
+
+**示例响应**：
+> "未找到匹配的「北京大兴」入职地点。系统支持的北京相关地点包括：北京、北京东城区、北京密云区、北京朝阳、北京（东区）等。请确认您需要查询的入职地点。"
+
+## 不支持筛选字段的分流处理
+
+当用户给出的筛选字段**不在** `references/filter-fields.md` 中时，禁止简单丢弃，按下列分支处理：
+
+### 分支 A：该字段在 `return-fields.md` 中可作为返回字段展示（"可看不可筛"）
+
+1. 不要把它写进 `--common-filters`。
+2. 用用户给出的**其他可筛选字段**作为前置过滤条件，并把目标字段加入 `--fields`。
+3. **第一次调用务必带 `--page-size 1` + 业务过滤条件**（最小代价探查 `total_number`）：
+   - `total_number ≤ 1000`：分页拉取全量数据（`--page-size 100` + 复用 `--page-token`），客户端按目标字段值做最终筛选与展示。
+   - `total_number > 1000`：**立即停止**，向用户提示：「`<字段中文名>` 不支持作为筛选条件，当前业务条件下命中 `<total_number>` 条数据量过大，请追加更精确的可筛选字段（如部门、入职日期、阶段等）后重试。」并列出 `references/filter-fields.md` 中可加的字段。
+4. **必须存在至少一个其他可筛选字段**才走分支 A；用户**没有**任何其他可筛选条件时，直接拒绝并提示「请补充至少一个可筛选条件（部门 / 阶段 / 入职日期 / 关键字 等）」，禁止裸拉全量。
+
+### 分支 B：该字段在 `return-fields.md` / `filter-fields.md` 中都不存在
+
+直接告诉用户「`<字段名>` 在待入职数据中暂不支持查询或展示」，停止。**禁止**用 keyword 或其他字段做近似替代。
+
+### 强约束
+
+- 禁止丢掉该字段后直接走 `+prehire-search` 不带任何业务条件。
+- 禁止在 `total_number` 未确认时批量翻页。
+- 禁止把"暂不支持的字段"伪装成 keyword 模糊查询。
+
+## 多候选命中的 AI 消歧流程
+
+触发条件：`+prehire-search` 在 `:name` 解析路径上返回本地枚举多候选或远程数据源多候选错误，例如：
+
+```
+direct_manager_id name "张三" matches multiple options, please disambiguate by id:
+  - 张三 (ID: 7000000001, path: 字节跳动/技术线/CoreHR)
+  - 张三疯不疯001 (ID: 7000000002, path: 字节跳动/产品线)
+  - 张三在职 (ID: 7000000003)
+```
+
+或：
+
+```text
+direct_manager_id="张三": multiple records match this name, please re-run with the exact id via "direct_manager_id" (omit the :name suffix):
+    - 张三 (ID: 7000000001, path: 字节跳动/技术线/CoreHR)
+```
+
+**处理顺序（必须按 1→2→3 依次尝试，不能跳步）：**
+
+1. **AI 优先做语义消歧**：
+   - 解析候选列表里的 `name` / `path`（部门/汇报路径）等结构化字段。
+   - 结合对话上下文：当前对话中已经出现的部门、汇报关系、岗位、用户最近一次明确指出的目标部门 / 团队等。
+   - 优先选择**精确等于用户输入**的候选；其次选择**path 命中用户上下文部门**的候选；最后选择**name 不带噪声后缀**（不带「001」「测试」「在职」等无关 token）的候选。
+2. **只有在高置信度（唯一精确等值 + path 与上下文吻合）时**，才直接用对应的 ID 重写为 `:id` 路径再调用一次：
+   - 把出错那一项 `{"api_name":"<field>:name","values":["<name>"]}` 改成 `{"api_name":"<field>","values":["<id>"]}`，重跑命令。
+   - 在最终回复中**显式向用户说明**："候选中存在多个同名记录，已根据 `<部门 / path / 上下文>` 自动选定 `<name>(<id>)`，如果不正确请直接给出 ID。"
+3. **判断不出来（多个候选都同名 / path 都不命中上下文 / 候选信息不足）**：
+   - **立即停止**，把候选列表（含 `name` / `id` / `path`）原样列给用户，要求用户用 ID 明确指定。
+   - 禁止随机选第一项；禁止用模糊匹配；禁止把 `:name` 退化成 keyword。
+
+### 强约束
+
+- 禁止在没有任何上下文证据的前提下声称"自动选了最合适的"；置信度不高时必须问用户。
+- 禁止反复用 `:name` 重跑期望"碰运气得到唯一命中"——后端不会因为重试就唯一化。
+- 禁止把多候选错误吞掉、隐瞒，必须把决策过程显式告知用户。

package/skills/people-corehr-query-id-by-name/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: people-corehr-query-id-by-name
+description: "Use when resolving CoreHR object names to IDs via people-cli for downstream business workflows, especially when a skill already has explicit business_scene and needs department, location, job level, or similar object IDs before calling other shortcuts."
+---
+
+# 名称换 ID 查询 (+query-id-by-name)
+
+**⚠️ CRITICAL - 在调用此 Shortcut 之前，请遵循以下步骤：**
+1. **前置要求 - 必须满足！！！**
+   - **必须明确 business\_scene**：不允许无场景调用名称换 ID
+   - **必须提前获取好参数**：使用 JSON 数组格式构造查询请求
+   - **必须判断语言环境**：**根据当前对话使用的语言自动设置** **`--language`** **参数**，中文用 `zh-CN`，英文用 `en-US`
+   - **不允许自动推断或无场景调用**：缺少这些参数必须直接报错提示用户
+
+通过名称查询 CoreHR 对象 ID：部门、地点、职级、序列等对象的名称转 ID。支持单个查询或批量并发查询（最大并发度 5）。
+
+## 使用场景
+
+此 shortcut 是**底层通用 shortcut**，由各个业务场景的 skill 调用。主要功能：
+
+- 业务场景 skill 自己处理入参解析
+- 业务场景 skill 负责获取好入参后调用此 shortcut
+- **业务场景 skill 必须明确 business\_scene**，不允许无场景调用
+
+## 命令格式
+
+```bash
+# 中文环境示例
+people-cli corehr +query-id-by-name --business-scene workforce_plan \
+  --language zh-CN \
+  --queries '[{"field_api_name":"department","target_object_api_name":"department","query_name":"技术部"}]'
+
+# 英文环境示例（批量查询）
+people-cli corehr +query-id-by-name --business-scene workforce_plan \
+  --language en-US \
+  --queries '[{"field_api_name":"department","target_object_api_name":"department","query_name":"Engineering Department"},{"field_api_name":"job_level","target_object_api_name":"job_level","query_name":"P7"}]'
+```
+
+## 参数说明
+
+| 参数                 | 类型   | 必填 | 默认值    | 说明                                                                                                                                   |
+| ------------------ | ---- | -- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `--business-scene` | string | 是  | —      | 业务场景，可选值：`workforce_plan`（编制规划）、`team`（我的团队）、`onboarding`（入职管理）、`job_change`（异动管理）、`offboarding`（离职管理）、`probation_management`（试用期管理）、`renewal`（续约管理） |
+| `--queries`        | string | 是  | —      | 查询列表，JSON 数组格式：`[{"field_api_name":"...","target_object_api_name":"...","query_name":"..."}]`，支持批量查询                              |
+| `--language`       | string | 否  | 自动检测   | 语言设置：`zh-CN`（中文）或 `en-US`（英文）。**必须根据当前对话语言设置此参数！** 若当前对话是中文，用 `zh-CN`；是英文，用 `en-US`。                                                 |
+| `--format`         | string | 否  | pretty | 输出格式：`pretty`（易读）或 `json`                                                                                                            |
+| `--dry-run`        | —      | 否  | —      | 仅打印将要调用的 API，不实际执行                                                                                                                   |
+
+### QueryRequest JSON 结构
+
+`--queries` 参数是一个 JSON 数组，每个元素的结构如下：
+
+| 字段名                 | 类型   | 必填 | 说明                                  |
+| ------------------- | ---- | -- | ----------------------------------- |
+| `field_api_name`    | string | 是  | 业务字段的 API 名称                        |
+| `target_object_api_name` | string | 是  | 目标对象的 API 名称                        |
+| `query_name`        | string | 是  | 要查询的名称                              |
+| `language`          | string | 否  | 单个查询的语言设置（可选，优先级高于全局 `--language`）   |
+
+## 输出说明
+
+### Pretty 格式示例
+
+```
+Query Results:
+--------------------------------------------------------------------------------
+[1] Query: 技术部
+  Matched: 技术部
+  Path: 公司/技术部
+  ID: people_corehr_department_id_123
+
+[2] Query: 北京
+  Matched: 北京
+  ID: people_corehr_location_id_456
+
+Errors:
+--------------------------------------------------------------------------------
+- query 3 (P7): no matching data found for "P7"; please check whether the name is correct, or you may not have permission to access it
+```
+
+### JSON 格式示例
+
+```json
+{
+  "results": [
+    {
+      "matched_id": "people_corehr_department_id_123",
+      "matched_name": "技术部",
+      "matched_name_path": "公司/技术部"
+    },
+    {
+      "matched_id": "people_corehr_location_id_456",
+      "matched_name": "北京",
+      "matched_name_path": ""
+    }
+  ],
+  "errors": [
+    "query 3 (P7): no matching data found for \"P7\"; please check whether the name is correct, or you may not have permission to access it"
+  ]
+}
+```
+
+#### JSON 字段说明
+
+| 字段                  | 说明                                              |
+| ------------------- | ----------------------------------------------- |
+| `matched_id`        | 匹配到的对象 ID，此值为后续筛选/调用时需要使用的 ID                   |
+| `matched_name`      | 匹配到的对象名称                                        |
+| `matched_name_path` | 匹配对象的路径（如部门层级路径），为空表示无路径信息                      |
+| `errors`            | 查询失败的错误信息数组；顺序与请求顺序无关，可通过 `query N (name)` 前缀定位 |
+
+## 异常处理 - 调用方（重点关注！）
+
+### 0. 前置检查失败（必须优先处理！）
+
+- **场景缺失**：没有明确 business\_scene
+  - **处理策略**：直接报错，由各个业务场景的 SKILL 自行处理
+- **参数缺失或不正确**：无法获取正确的 JSON 格式查询参数
+  - **处理策略**：直接报错，由各个业务场景的 SKILL 自行处理
+- **字段与场景不匹配**：使用了不适合当前业务场景的字段
+  - **处理策略**：提示用户参考「业务场景与字段匹配规则」，使用正确的字段
+
+### 1. 部分查询失败 / 所有查询都失败
+
+- 错误信息：`all queries failed: ...` 或者 `errors` 数组有内容
+- **处理策略**：直接报错，提示用户"系统异常，稍后重试"
+
+### 2. 无匹配结果
+
+- 错误信息：`query X (name): no matching data found for "name"; please check whether the name is correct, or you may not have permission to access it`
+- **处理策略**：告诉用户"没匹配到相关数据或者您没相关权限，请确认名称是否正确"
+
+### 3. 多个匹配结果
+
+- 错误信息开头：`query X (name): found N entries matching "name", please refine the query to a more specific name:`
+- 后面以 `1. (id: ..., name: ..., name_path: ...)` 的格式逐行列出所有候选项
+- **处理策略（必须按以下顺序执行，禁止跳步或默认选第一条）**：
+  1. **优先精确匹配**：遍历所有候选项，将每个候选项的 `name` 与用户原始输入的 `query_name` 进行**完全一致**的字符串比较（大小写敏感、去除首尾空白后仍需完全相等）。
+     - 若**有且仅有一条**候选项的 `name` 与 `query_name` 完全精确匹配，则**自动选用**该条结果继续后续流程，并在回复中明确告知用户："检测到多条候选，已按精确匹配自动选用 `<matched_name>`（id: `<matched_id>`）"。
+     - 若**有多条**候选项 `name` 均与 `query_name` 完全精确匹配（如不同层级路径下同名对象），**不得自动选择**，进入下一步。
+     - 若**没有任何**候选项 `name` 与 `query_name` 完全精确匹配，进入下一步。
+  2. **无精确匹配或多条精确匹配时必须追问用户**：使用 `AskUserQuestion` 或等效的用户确认机制，列出所有候选 `(id, name, name_path)` 供用户选择；**禁止默认选择第一条或任意兜底**。
+     - 建议用户使用 `name_path` 中更靠近目标的层级名称进行更精确查询；若用户能直接辨认目标，也可使用对应的 `id`。
+     - 用户明确指定后再继续下游命令。
+
+### 4. 查询格式错误
+
+- 错误信息：`invalid queries JSON format: ...`
+- **处理策略**：直接报错，由各个业务场景的 SKILL 自行处理
+
+### 5. 参数为空
+
+- 错误信息：`at least one query must be provided` 或 `query X: ... cannot be empty`
+- **处理策略**：直接报错，由各个业务场景的 SKILL 自行处理