@lark-people/cli 0.0.0-beta.1

package/skills/people-corehr-offboarding/references/people-corehr-offboarding-search-option.md

@@ -0,0 +1,187 @@
+# search-option (offboarding.search-option)
+
+`people-cli corehr offboarding search-option --as user` 只用于运行时定位离职搜索字段、候选值和枚举/引用展示名。它不是业务查询结果，不能进入 final。
+
+## 0. 必须遵守的规则
+- 不允许手写、改写或编造 `jq` 命令。
+- 每个普通离职查询最多调用一次 `search-option`，且必须使用 people-cli 内置 `--jq` 返回一个有界 JSON 对象。
+- 只提取本题需要的筛选字段、枚举候选和返回列；禁止无 `--jq` 调用、完整 dump、shell 管道、输出重定向、临时文件或脚本解析。
+- `search-option` 只做运行时校准，不是业务结果，不能作为 total、空结果或最终答案。
+
+
+## 1. 何时调用
+
+- 每次查询前必须先调用一次：标准字段也要先取元数据确认 canonical key、筛选项是否在 system\_filters、候选展示名，再进业务查询。
+- 自定义原因/标注、自定义数字字段、发起人、签署方式、工作地点、合同主体、任职公司、合同/雇佣状态、职务、序列、职级、职等、人员类型、人员子类型、薪资类型、排班、竞业启动等候选不确定时，尤其依赖本次 search-option 结果归一候选。
+- 不为拒答调用：越权、高敏、流程节点类请求直接按拒答/澄清模板收口。
+- 禁止把 search-option 中看到的租户字段展示名、候选值、组织/人员/公司/地点名、原因 ID、枚举 ID 写进 skill 文档或最终答案；只能在当次运行中用于过滤。
+- search-option 每次查询最多调用一次；它只能决定字段 API/候选归一，不能作为业务 total，也不能作为 final。
+
+## 2. 调用（单次 bounded jq）
+
+`search-option` 原始返回极大，直接读入会超出上下文窗口。统一在一次命令中用内置 `--jq` 先把用户 query 映射为 canonical `alias_fields`，再同时裁剪本题需要的 filters、columns 和枚举候选：
+
+```bash
+people-cli corehr offboarding search-option --as user --jq '
+("QUERY_JSON_STRING" | ascii_downcase) as $q |
+def alias_rules:
+  [
+    {field:"employment.department", include:"部门|组织|团队"},
+    {field:"employment", include:"工号|姓名|同事|人员|员工"},
+    {field:"expected_offboarding_date", include:"期望离职|预计离职|预期离职|计划离职"},
+    {field:"offboarding_date", include:"实际离职|离职日期|离职日"},
+    {field:"offboarding_date", include:"离职时间", exclude:"申请"},
+    {field:"offboarding_date", include:"离职.*月|月.*离职", exclude:"申请|流程|流转|交接|手续"},
+    {field:"apply_date", include:"申请日期|申请日|申请时间"},
+    {field:"initiating_time", include:"发起|提交|创建"},
+    {field:"apply_finish_time", include:"离职申请结束|申请结束|申请完成|审批完成|审批结束"},
+    {field:"checklist_start_time", include:"流转开始|交接开始|手续开始"},
+    {field:"checklist_finish_time", include:"流转结束|流转完成|交接完成|手续完成|流程完成|审批通过"},
+    {field:"checklist_status", include:"流转状态|交接状态|手续状态"},
+    {field:"status", include:"申请状态|审批状态|离职状态|已离职|离职中|待离职"},
+    {field:"reason", include:"主离职原因|hrbp原因|离职原因"},
+    {field:"custom_field_1", include:"原因标注|自定义原因|员工原因"},
+    {field:"minor_reason", include:"次要原因"},
+    {field:"initiator_id", include:"发起人|提交人"},
+    {field:"employment.work_location", include:"工作地点|地点|城市"},
+    {field:"employment.company", include:"合同主体|合同公司"},
+    {field:"employment.service_company", include:"任职公司|service company"},
+    {field:"employment.employment_status", include:"雇佣状态"},
+    {field:"sign_type", include:"签署方式|签名方式|电子签|电签"},
+    {field:"employment.job", include:"职务|岗位|职位"},
+    {field:"employment.job_family", include:"序列|job family"},
+    {field:"employment.job_direction", include:"员工方向|job direction|employee direction"},
+    {field:"employment.job_level", include:"职级|级别|level"},
+    {field:"employment.job_grade", include:"职等|grade|pn"},
+    {field:"employment.workforce_type", include:"人员类型|正式|全职"},
+    {field:"employment.employee_subtype", include:"人员子类型|子类型"},
+    {field:"employment.compensation_type", include:"薪资类型|工资制"},
+    {field:"employment.work_shift", include:"排班|工作制"},
+    {field:"employment.direct_manager", include:"直属上级|直接上级"},
+    {field:"non_compete", include:"竞业"}
+  ];
+def aliases:
+  alias_rules
+  | map(. as $rule
+    | select(
+        ($q | test($rule.include; "i")) and
+        ((($rule.exclude // "") == "") or (($q | test($rule.exclude; "i")) | not))
+      )
+    | $rule.field)
+  | unique;
+aliases as $aliases |
+($aliases + ["<EXTRA_FILTER_FIELD>"] | unique) as $filter_fields |
+($aliases + ["status","offboarding_date","expected_offboarding_date","employment","employment.employee_number","<EXTRA_COLUMN_FIELD>"] | unique) as $column_fields |
+{
+  alias_fields: $aliases,
+  filters: [.data.system_filters[]?
+    | select((.field // .field_api_name // .filter_api_name) as $f
+      | $filter_fields | index($f))
+    | {
+        field:(.filter_api_name // .field // .field_api_name),
+        api_name,
+        type,
+        names,
+        enums:([.enums[]?
+          | select((((.label // "")+" "+(.value // "")+" "+(.description // ""))
+            | test("KEYWORD_REGEX"; "i")))])
+      }],
+  columns: [.data.system_columns[]?
+    | select((.field_api_name // .field) as $f
+      | $column_fields | index($f))
+    | {field:(.field_api_name // .field), type, names, is_custom_field}]
+}
+'
+```
+
+使用模板时必须：
+
+1. 把 `QUERY_JSON_STRING` 替换为用户完整 query 经 JSON string escaping 后的内容；它必须仍处在 jq 双引号字符串内，不能直接插入 jq 语法。
+2. `alias_rules` 是标准字段别名的唯一维护点；每行是一条“用户词 → canonical field”配置，`include` 命中且 `exclude` 未命中时输出该 `field`。新增普通别名只加一行规则，不要回退成长 `if/then` 链。
+3. 把额外已知筛选字段和用户显式返回字段分别替换进 `EXTRA_FILTER_FIELD` / `EXTRA_COLUMN_FIELD`；没有额外字段时删除对应占位元素，不保留占位符。
+4. 把 `KEYWORD_REGEX` 替换为本题枚举值语义的安全正则；若所选字段无需枚举则允许其 enums 为空，“有值/不为空”需要全部枚举时才使用 `.*`。
+
+alias 规则按每行独立求值并 `unique`，因此一个复合 query 可以同时得到多个 canonical fields；这保留旧映射关系，同时避免旧 Shell `case` 的首分支截断导致复合条件丢字段。自定义字段、展示名未知字段仍使用下方语义窄化模板，不写入 `alias_rules`。
+
+当用户点名自定义字段、字段 API 未知或展示名需要运行时定位时，只在同一个 jq 对象中增加窄化的语义匹配，不能再调用第二次 `search-option`：
+
+```bash
+people-cli corehr offboarding search-option --as user --jq '{
+  filters: [.data.system_filters[]?
+    | select((((.field // .field_api_name // .filter_api_name // "")+" "+([.names[]?.value // ""] | join(" ")))
+      | test("ESCAPED_SEMANTIC_REGEX"; "i")))
+    | {
+        field:(.filter_api_name // .field // .field_api_name),
+        api_name,
+        type,
+        names,
+        enums:([.enums[]?
+          | select((((.label // "")+" "+(.value // "")+" "+(.description // ""))
+            | test("ESCAPED_VALUE_REGEX"; "i")))])
+      }],
+  columns: [.data.system_columns[]?
+    | select((((.field_api_name // .field // "")+" "+([.names[]?.value // ""] | join(" ")))
+      | test("ESCAPED_SEMANTIC_REGEX"; "i")))
+    | {field:(.field_api_name // .field), type, names, is_custom_field}]
+}'
+```
+
+- `QUERY_JSON_STRING` 必须做 JSON string escaping；`KEYWORD_REGEX` / `ESCAPED_*_REGEX` 必须来自已经归一的业务语义和必要同义词，并转义 `\ . + * ? ( ) [ ] { } ^ $ |` 等正则元字符。禁止把未经处理的用户原文直接拼入 jq 字符串或正则。
+- 标准字段优先用 canonical field 白名单精确筛选；只有自定义/展示名未知字段才按 names 与语义关键词窄化，禁止用“部门/员工”等宽泛词扫描全部档案字段。
+- 普通枚举只返回与本题语义匹配的候选；“有值/不为空”且目标字段为 enum/tree/select 时，可以返回该已选字段的全部合法候选，但不能展开其它字段枚举。
+- 单次校准产物必须复用。若字段为空、候选多且无法唯一确定、或一次 jq 没覆盖必需字段，下一个动作只能是按已确认条件执行最终 search，或按字段未生效/工具错误收口；不得补调 `search-option`、help 或 schema。
+- 只用 `--as user`；禁止 `--as bot`、禁止主动 auth login。
+
+## 3. canonical 字段定位
+
+- 完整的「用户语义 → canonical key」映射表统一以 SKILL.md 第 4 节「字段优先级矩阵」为准，本节不重复。
+- search-option 专属原则：必须先定 canonical key，再看运行时字段；禁止因为候选为空就改查近义但业务对象不同的字段（合同主体与任职公司互换、人员类型与人员子类型互换、职务与序列互换）。
+- `system_filters` 优先级高于 `system_columns`：用户对某字段提出筛选条件时，若该 canonical field 存在于 `system_filters`，必须用该 field 构造 `--search-filter-by-name`；不得因为该字段也可展示、值需要比较/范围、或担心解析失败，就跳过服务端筛选改成本地过滤/排序。
+- 构造 `--search-filter-by-name` 时：除时间类字段外，key 必须取自本次 `system_filters` 的 `field`（不得用 `system_columns` 字段或臆造）；value 传筛选条件名称/中文展示名，不传 ID（由 shortcut 运行时解析为 ID/枚举 value），已知 ID 才改用 `--search-filter-by-id`。层级展示名含制表符/换行时，JSON 参数里写 `\t`/`\n` escape，不放 literal tab、不用空格替代、不只取叶子。
+- 人员姓名/姓名/工号/某同事/叫某人固定为 `employment`，不使用 `employment.name/name/person/initiator_id`；“离职人员/离职员工/离职同学/哪些人”只是人员展示/名单口径，不自动加 status；“待离职”固定归到 `status`，在未指定其它离职申请状态时使用 `status:["无需审批","审批通过","审批中"]`；其它“离职记录/离职单据/离职申请”默认单据口径，也不自动加 status；只有“已离职/已完成/完成离职/离职完成”才指离职单终态，流转/交接完成才用 checklist 字段。
+
+## 4. 候选归一算法
+
+1. 先确定 canonical key，不要从用户词面直译字段名。
+2. 在 search-option 中只看该 key 或同语义字段的 names/alias/options；不要跨到近义但业务对象不同的字段。
+3. 规范化候选值：去首尾空白、统一全半角、大小写、连接符/括号等格式；但业务展示值本体必须保留，不能删除“职务/岗位/子类型”等后缀或括号符号。
+4. 匹配顺序：同字段精确完整展示名 → 别名/同义词 → 明确唯一候选 → 同字段语义候选集合。多候选不唯一时澄清或字段未生效，不默认第一项；禁止模糊包含、错字纠正、相似公司/地点/序列扩展。
+5. 对“级别/职级是 X”使用数组值；对“某级及以上”只按同字段运行时候选生成完整连续展示值集合，保留空格、连接符、大小写原样；范围查询只能一次性数组业务查询，禁止写死枚举、逐级试探或用部分候选收口，候选解析失败不能回退主范围样例。
+6. 对“签署方式/人员类型/人员子类型/排班/薪资类型”等口语值，必须以运行时候选完整展示值或可接受 code 为准；用户简写只用于匹配，不能截短或只取叶子。
+7. 对“有/无/是/否/正式/全职”等语义值，收集同一字段全部等价完整候选并以数组 OR 查询；候选集合不确定则字段未生效，不采信部分命中。
+8. 对自定义字段，书名号/引号里的字段展示名只在运行时解析；解析到字段 API 和类型后立即用该 API 执行主条件+字段值业务查询。数字阈值/范围若 CLI 没有明确 operator/range，只按阈值原文的等值/文本参数执行并说明口径；不得本地枚举大于/小于范围、不得再跑 `--help`、主范围采样或输出空 final。
+9. 对引用/字符串值，完整原文值优先；保留括号、空格、连接符和后缀。精确值无匹配时最多一次完整原文重试，禁止拆词、近义改写、相似候选并集，之后收口。
+10. 修正字段候选时必须继承上一条业务命令的全部主条件，只替换出错字段；不得丢部门、日期、人员或 status。候选门禁未通过时，禁止返回主范围全量作为目标字段答案。
+11. 候选确认后必须进入 `+offboarding-search`：签署方式、员工方向、工作地点、合同主体、任职公司、合同状态、人员类型、职级、直属上级等都不能停在 search-option；输出过大或被截断时不得管道/脚本二次解析，改用 canonical key+原文/完整候选执行业务查询或字段未生效收口。
+
+## 4.1 高风险字段硬约束
+
+- 离职原因：若用户说“离职原因是/主离职原因/HRBP原因”，固定走 `reason=<叶子值>`；只有明确“原因标注/自定义原因/员工原因”才走标注字段或 `custom_field_1`。
+- 人员类型：口语值必须保持 `employment.workforce_type` 并归一为同字段完整展示值/候选集合；人员/记录状态口径按 SKILL.md P0 执行；多值用同 key 数组 OR；解析失败只能同字段原文/完整展示值重试一次或字段未生效，禁止改用 `employment.employee_subtype`、禁止先查部门主范围采样、禁止按员工去重。
+- 序列/job family：保持 `employment.job_family` 与用户完整原文值，保留书名号、方括号、连接符、空格；业务命令 0 条/no matching 即字段无匹配收口，不回退部门 total。
+- 工作地点/合同主体/任职公司/直属上级：分别保持 `employment.work_location`、`employment.company`、`employment.service_company`、`employment.direct_manager`；read model/config/resolve 错误时最多同字段原文重试一次，禁止改查国家/城市、互换公司字段、相似名称、主范围冒充；未通过可读 display 或 applied/resolved filter 证明字段过滤生效时不能写可信 `total=0` 命中，只能字段未生效/工具错误。若已由 applied/resolved filter 或服务端 total 证明命中，部分记录缺少该字段 display 时仍展示该记录，并把字段列写“字段未返回”。
+- 合同/雇佣状态：雇佣状态固定 `employment.employment_status`；合同状态/合同已终止优先真实合同状态 filter，若运行时没有合同状态 filter 但有合同结束/终止日期可展示字段，仅允许按其它主条件完整分页后用该日期字段做 columns-only 后处理。unknown filter/read model/config/resolve 错误时最多同字段原文重试一次，仍失败字段未生效；禁止改用离职申请 `status`、雇佣状态或 unsupported 结果写成无匹配。
+- 员工方向：固定 `employment.job_direction`，不得当作序列 `employment.job_family`；口语叶子值必须归一到同字段运行时完整层级展示名后再用 `--search-filter-by-name`，不能直接传叶子值。若从错误候选或枚举列表中拿到 enum id，只能改用 `--search-filter-by-id`；禁止把 id 塞进 `--search-filter-by-name`，禁止因候选失败改查全量后本地过滤。命中后必须 select `employment.job_direction` 并按默认上限展示最多 10 条明细。
+- 竞业启动：只取 `non_compete` 同字段运行时“是/启动/已启动”语义候选集合；已有成功 `+offboarding-search` 结果后立即收口，不继续脚本或候选探索。
+
+## 5. 匹配失败处理
+
+- 字段找不到：有部门/人员/状态/日期主条件时可主查询，但 final 必须说明目标字段未完成过滤；没有主条件时澄清。若业务字段本身是用户主条件，不得以主查询 total 冒充过滤结论。
+- 枚举/引用值不匹配：若唯一候选可确定，修正后重试一次；仍失败输出字段未生效或工具错误。
+- 合同主体/任职公司等引用字段出现 read model/config/resolve 错误：允许同一 canonical key 用用户原文值重试一次；仍失败立即收口为字段未生效或工具错误；禁止改查其他字段、组织全量或本地全量循环。
+- `sign_type/employment.job/job_family/job_level/company/work_location/workforce_type/employee_subtype/service_company/job_grade/direct_manager` 候选仍失败：业务命令明确 0 条或 no matching data/candidate 且无字段错误才输出 0 条；read model/config/resolve 错误、全部只返回 wk\_id、无法证明 applied/resolved filter 生效则字段未生效/工具错误。若只有部分记录只返回 wk\_id/display 缺失，但服务端筛选已生效，不能过滤这些记录，明细中标记“仅返回内部 id/字段未返回”。不得反复 search-option、查部门全量冒充字段过滤结果，也不得只让用户确认候选。
+- 人员类型失败时不得改用人员子类型；任职公司失败时不得改用合同主体；合同主体失败时不得改用任职公司；工作地点失败时只能使用 search-option 中同语义字段重试一次，不得改用国家/城市近义字段或本地全量过滤。
+- 高风险字段（`employment.workforce_type/company/service_company/work_location`）若目标命令返回 0 但伴随字段解析/候选/配置错误、字段全量缺失或未确认 applied filter，该 0 不可信；final 写“未完成 <主条件+目标字段> 联合过滤”，不得写“未找到/0条”。若目标命令 total>0 且筛选生效，部分记录字段缺失不影响命中记录展示。
+- 职级、序列、员工方向、人员类型、排班过滤未生效时，不输出主范围样例作为命中答案；主范围 total 只能作为字段未生效模板中的背景事实；职级若全部只返回 wk\_id 时最多用一次同字段候选字典映射，失败即字段未生效；若只有部分记录缺展示值，仍保留记录并标记“字段未返回/仅返回内部 id”。
+- 自定义多选/数字字段已定位 field API 后必须立即执行业务查询；若 final 同时需要主范围 total 与子条件 total，二者必须分别来自规范业务查询，不能把 search-option、探索性主范围 total 或 page items 数混入。
+- 自定义数字字段范围语义在 CLI 未明确支持 operator 时，只用阈值原文执行一次；若该业务结果成功，final 必须从最后一次成功结果重写，禁止输出“需要先查询/继续处理”等过程句。
+- 若字段在 `system_columns` 可展示但不在 `system_filters`，仅当返回 display/code 可读、用户值可精确映射、分页完整时允许本地过滤或排序；若同一 canonical field 已存在于 `system_filters`，禁止走本地过滤/排序替代服务端筛选。columns-only 本地过滤时，字段缺失/仅有 wk\_id 的记录不能被判定为命中；但若记录已经由其它服务端条件命中并只是展示字段缺失，final 仍展示该记录并标记缺失。工号只能使用 `employment.employee_number`，不得用 employment_id/wk_id/internal id 填充。
+- 竞业启动若没有枚举候选，可用主查询样本中非空值归纳启动类候选集合；集合确定后必须执行业务查询或用已有业务结果收口，不得输出“继续查看字段值”。
+- 无匹配不等于可返回主条件全量；若目标字段条件未生效，final 必须明确“以上不是该字段过滤后的数量”。
+- search-option 结果不得作为“0 条”依据；只有 `+offboarding-search` 的结构化 `total/has_more` 才能作为查询结论。
+- 入职不到一年/司龄不靠 search-option 反复确认字段；最后一轮只做部门主范围业务查询，缺专用聚合或批量档案能力时直接派生待确认（最终输出契约见 SKILL.md 第 5 节）。
+
+## 6. 最终答案要求
+
+- 最终输出契约、收尾模板统一以 SKILL.md 第 5/9 节为准，本节不重复。
+- search-option 专属：其输出只用于运行时字段/候选定位，绝不能进入 final，也不能作为 “0 条” 依据；明确查询必须继续 `+offboarding-search`，以结构化 `total` 和后台分页状态判断取数是否完成，再按 SKILL.md 的展示数量文案收口，禁止向用户回显 raw `has_more`；无法完成也要按拒答/派生待确认/工具错误收口，不得空 final。

package/skills/people-corehr-offboarding/references/people-corehr-offboarding-search.md

@@ -0,0 +1,54 @@
+# offboarding search
+
+`people-cli corehr +offboarding-search` 是离职查询唯一主执行入口。主条件明确时直接查；不要长篇解释、不要调试循环、不要把候选探查当答案。
+
+## 1. CLI 与参数硬约束
+
+- 通用硬约束（`--as user`、禁止 `--as bot`/auth login、执行前自检禁止 `|`/`2>&1`/`head/tail/grep/python`/`/tmp`/`--help`/管道截断、固定 params ID 类型、page_size=10、`--search-filter-by-name` 必须是 JSON 对象、`--select-fields` 必须是 JSON 数组）统一以 SKILL.md 第 0 节为准，本节只列 `+offboarding-search` 专属细节。
+- 命令：`people-cli corehr +offboarding-search --as user`。
+- `--search-filter-by-name` 的 key 约束：除时间类字段（如 `offboarding_date/expected_offboarding_date/initiating_time/apply_date/checklist_start_time/checklist_finish_time/apply_finish_time`）外，key 必须是 `search-option` 返回的 `system_filters` 对应的 `field`，不得臆造或用 `system_columns` 字段。
+- `--search-filter-by-name` 的 value 约束：value 必须是筛选条件的名称/中文展示名（由 shortcut 在运行时解析为 ID/枚举 value），不得直接传 ID；若已知 ID 才用 `--search-filter-by-id`。层级展示名若包含制表符/换行等字符，JSON 参数中必须写成 `\t`/`\n` escape，禁止放 literal tab、用空格替代或只取叶子值。
+- 日期区间必须写成数组 `["YYYY-MM-DD","YYYY-MM-DD"]`；同字段多候选用数组表达 OR；不同 key 在同一个对象内表达 AND，不要拆多次查询后手工并集。
+- 默认 select 基线固定为 `status,offboarding_date,expected_offboarding_date,employment,employment.employee_number`；再与所有查询条件的 canonical field、用户要求的展示字段做去重并集。每个 `--search-filter-by-name` key 都必须出现在 `--select-fields`；`--search-filter-by-id` 的 native ID key 要映射为对应 canonical 展示字段，例如 `department_ids -> employment.department`、`employment_ids -> employment`。另按目标补 `initiating_time`、`apply_finish_time`、`checklist_*`、`non_compete`、`custom_field_1/minor_reason/initiator_id` 或 `employment.<field>`。
+- 标准模板：
+
+```bash
+people-cli corehr +offboarding-search --as user --params '{"page_size":"10","user_id_type":"people_corehr_id","department_id_type":"people_corehr_department_id"}' \
+  --search-filter-by-name '{"employment.department":"<组织核心词>","<key>":"<展示名或日期区间>"}' \
+  --select-fields '["status","offboarding_date","expected_offboarding_date","employment","employment.employee_number","employment.department","<key>"]'
+```
+
+- 用户语义到 canonical key 的完整映射、字段组合规则、计数口径、字段语义锁定、字段展示值门禁、枚举/引用计数口径，统一以 SKILL.md 第 4 节「字段优先级矩阵」为准。
+- 前置拒答/澄清（越权/高敏/流程节点先拒答，命中后禁止 search-option 与业务查询）统一以 SKILL.md 第 6 节为准。
+- 授权组织短语先抽核心词：先去权限前缀，再剥离“大部门/部门/团队/组织”等泛称后缀；只有剩余具体业务组织名时才作为 `employment.department`。若只剩“我管理的部门/我负责的团队/我所在组织”等授权泛称，不构造部门 filter，不把整句或猜测组织写入 `employment.department`，也不把短词扩散为相似子组织/实验室/项目组候选；只能让 `--as user` 可见范围生效，或澄清/字段未生效。
+- `--search-filter-by-id`：仅当用户**明确给出 ID**（如部门 ID、employment_id、枚举 value 等已知 ID/值）时才使用。它是 JSON 对象，key 为 settings filter field，值是已解析的 ID/值（不做 name→ID 解析，不做枚举展示名匹配），直接合并到 `filter_str` 或对应原生字段。示例：`--search-filter-by-id '{"employment_ids":["7123456789"],"department_ids":["6987654321"]}'`。严格限制：用户只给出名称/展示名/自然语言时**禁止**使用该参数，必须走 `--search-filter-by-name`；不得自行编造、猜测或反查 ID 后塞进该参数；两个参数可同时出现，但同一字段不要重复传。
+
+## 2. 日期、状态与进度
+
+- 日期统一 `YYYY-MM-DD`；日期区间用 `[start,end]`，显式范围优先。
+- 某年/某月按完整自然年/月；“最近一个月（某月）”按括号月份自然月，不截到运行日。
+- 无显式范围的“本周/这周”按运行日所在自然周周一至周日闭区间；该规则适用于 `initiating_time/checklist_start_time/offboarding_date/expected_offboarding_date` 等所有时间字段。
+- “近/最近”按滚动窗口、“上一个/上”按自然周期，二者不可混用：
+  - “近一周/最近一周/近7天”= 运行日往前 7 天的滚动窗口；“上一周/上周”= 上一个自然周（周一到周日闭区间）。
+  - “近一个月/最近一个月/近30天”= 运行日往前 30 天的滚动窗口；“上一个月/上月”= 上一个自然月（1 日到该月最后一日）。
+  - “近一年/最近一年/近365天”= 运行日往前 365 天的滚动窗口；“上一年/去年”= 上一个自然年（1 月 1 日到 12 月 31 日）。
+- 无年份的“某月/几月”默认运行年，即使该月晚于运行月也不回退上一年；“最近一个月（某月）/最近（某年某月）”以括号或显式年月优先；修正枚举时必须保留该月份窗口。
+- “上个月/本月/下周/下个月”可唯一换算时直接查；原因、发起人、人员类型等主条件不因“最近”自动加 30 天。
+- “申请日期/申请日”固定 `apply_date`；“发起/提交/创建”固定 `initiating_time`，final 口径不得混写；若用户说申请日期但命令无法使用 `apply_date`，必须重试或字段未生效，最终不得把 `initiating_time` 表述为申请日期。
+- “离职申请结束时间/申请结束时间/申请完成时间/审批完成时间/审批结束时间”固定查该自然月 `apply_finish_time=[YYYY-MM-01,YYYY-MM-last]`；它是离职申请/审批单结束口径，不是流转/交接结束口径。
+- “某月流转结束/流程完成/流程审批通过/交接完成/手续完成”默认查该自然月 `checklist_finish_time=[YYYY-MM-01,YYYY-MM-last]`；只有用户明确“从某月起/截至当前/阶段累计”才扩到运行月月底。final 口径必须写清实际执行窗口。
+- 完成时间首查 `select-fields` 必含基线字段 `status,offboarding_date,expected_offboarding_date,employment,employment.employee_number`；申请/审批结束口径追加 `apply_finish_time`，流转/交接口径追加 `initiating_time,checklist_status,checklist_finish_time`。不得用 `checklist_finish_time` 覆盖离职申请结束口径，也不得用 `apply_finish_time` 覆盖流转/交接完成口径。
+- 完成时间可信度门禁：`checklist_finish_time/apply_finish_time` 查询返回 0 或样例缺少完成时间字段时，需用同一 checklist filter + 最小字段重试一次确认字段生效；无法确认时输出字段未生效，不把 0 条作为确定结论，不得把 `apply_finish_time` 失败或主范围 total 泛化成 checklist 结果。
+- status 判定：用户问“离职申请状态/离职单状态/已离职/已完成/完成离职”时优先 `status`；用户语句包含“待离职”且未明确指定其它离职申请状态时，固定用 `status:["无需审批","审批通过","审批中"]` 作同字段 OR 筛选，并保留 `status` 在 `select-fields` 中回显。只有“流转/交接/手续/任务/流程节点完成”才用 `checklist_status` 或 `checklist_finish_time`，二者不能混用；不得把“待离职”翻译为 `checklist_status`、`离职中` 或任一单一状态。
+- 状态展示应逐条中文归一：优先本记录中文 display/审批态 display/明确 status_display；无 display 且 raw enum 与字段语义唯一对应时才通用中文化，`Offboarded=已离职`、`Withdrawn=已撤销`、`Rejected=已拒绝`，其它未知 raw enum 不直接泄露。raw 与 display 冲突时以 display 为准；不得用 `checklist_status`、同人其他单据或 raw enum 覆盖离职申请 `status`，缺 display 且无法区分审批通过/审批中/撤销时写“状态来源不稳定”或字段未生效。
+- 人员/记录口径：用户说“离职人员/离职员工/离职同学/哪些人/哪些同事”只是人员展示/名单口径，不自动补 `status`；用户明确说“已离职/完成离职/离职完成/已完成”才按离职单终态补 `status=已离职`。用户说“待离职”时按本节 `status:["无需审批","审批通过","审批中"]` 筛选。其它“离职记录/离职单据/离职申请/全部状态/状态分布”默认保留单据口径，不自动补终态。final 不得把撤销/拒绝/进行中记录汇总成“已离职人员”。
+- 日期筛选后必须抽查返回项的目标日期字段：如按 `offboarding_date/checklist_finish_time/apply_finish_time/initiating_time` 查询，明细中的对应字段应落在用户窗口内；样例反证目标日期外、口径混用，或目标日期字段全量缺失且无法证明服务端筛选生效时，按正确字段重试一次，仍失败即字段未生效/工具错误。若只有部分记录未返回目标日期字段，仍展示这些记录并写“日期字段未返回”，不得过滤掉。
+- 工号展示只能来自 `employment.employee_number`；若该字段未返回，写“工号缺失”，禁止用 employment_id、wk_id、人员 ID 或其它内部 ID 冒充工号。
+- 单人“离职进度/状态/当前进展”：默认以离职申请 `status` 作为进度；只有用户说“流程/流转/交接进度”才追加 checklist 字段。查询后先输出一句中文状态结论；多条同状态先汇总“离职进度为<中文状态>，共 N 条记录”，状态不一致写状态分布。若 `total>0`，必须逐条列出姓名、工号、中文状态、离职日期、期望离职日期；禁止只输出表头或空表，禁止加入未 select/未返回的列。若结构化结果无法抽取明细，先用基线字段重查一次，仍失败则工具错误。
+
+## 3. 其它规则（均见各自 owner 文档）
+
+- 字段稳定性（原因字段决策、引用/字符串字段透传、职级范围展开、自定义字段/数字阈值、竞业启动、人员类型/合同主体/任职公司/工作地点/员工方向/直属上级等档案字段取值与失败收口）、高风险字段失败重试、字段未生效/字段无匹配判定，统一以 [search-option](people-corehr-offboarding-search-option.md) 第 4/4.1/5 节为准。
+- 复合统计（“其中/主范围中的子条件”分别查主范围 total 与子条件 total）、名单门禁、分页翻完口径，统一以 SKILL.md 第 2 节为准。
+- 最终输出契约（必含 `total=`、默认最多展示 10 条、超过实际展示数必须提示仍有更多、成功响应 `data.total=0` 明确写“无数据”、无权限 `msg` 必须业务化且不泄露原始错误、禁止用原始 `has_more=false` 暗示展示完整、禁止泄露内部执行物、收尾模板），统一以 SKILL.md 第 5/9 节为准。
+- 通用底线：返回样例反证目标过滤未生效（目标日期外、主条件全量特征、完全没有 applied/resolved filter 证明且字段全量缺失/仅 wk_id）时，按正确字段重试一次仍失败即字段未生效；不能把主条件 total 当目标字段过滤结果；不得空 final。若服务端筛选已生效但部分记录未返回展示字段，仍保留记录，在该字段列写“字段未返回/仅返回内部 id”，不得从明细中过滤掉。

package/skills/people-corehr-organization/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: people-corehr-organization
+version: 7.1.0
+description: "当用户需要通过 people-cli 查询 CoreHR 部门、成本中心或自定义组织的字段、节点、上下级关系、组织树或聚合时使用。"
+metadata:
+  requires:
+    bins: ["people-cli"]
+  cliHelp: "people-cli corehr --help"
+---
+
+# CoreHR 组织查询
+
+## 概述
+
+使用 `people-cli` 查询当前用户可见的 CoreHR 组织数据。先按对象家族路由；只为需要可读字段的家族读取字段元数据。关系查询先取 ID，再按需批量补全详情。
+
+## 对象家族与命令路由
+
+| 家族 | 元数据 | 搜索 / 详情 | 关系 |
+|---|---|---|---|
+| 部门 | `+department-field-list` | `+department-search` / `+department-detail` | `+department-parents` / `+department-tree` |
+| 成本中心 | `+cost-center-field-list` | `+cost-center-search` / `+cost-center-detail` | `+cost-center-parents` / `+cost-center-tree` |
+| 自定义组织 | `+custom-org-object-list`，再按需 `+custom-org-field-list` | `+custom-org-search` / `+custom-org-detail` | `+custom-org-parents` / `+custom-org-tree` |
+
+部门和成本中心命令绝不传 `--object-api-name`。除 `+custom-org-object-list` 外，每个自定义组织命令都必须传已确认的 `--object-api-name "<custom_org_xxx>"`。
+
+## 执行规则
+
+1. 确认是当前组织数据的只读问题，并按用户明确的“部门”“成本中心”或自定义组织标签选择家族；家族不明确时先澄清，不做跨家族权限探测。
+2. 仅在需要字段 API 名时读取对应的 [metadata.md](references/metadata.md)。自定义组织先用对象列表唯一匹配标签，再读取该对象字段。
+3. 按意图读取对应 reference：搜索见 [lookup.md](references/lookup.md)，已知 ID 详情见 [detail.md](references/detail.md)，父链见 [hierarchy.md](references/hierarchy.md)，下级/后代见 [tree.md](references/tree.md)，汇总见 [aggregate.md](references/aggregate.md)。search/detail 返回枚举或人员字段时，必须按 [field-values.md](references/field-values.md) 读取结构化值。
+4. 所有调用从 `PATH` 使用 `people-cli corehr`，并始终传 `--as user`；只根据真实返回作答。
+
+## 权限、范围与输出
+
+- 单一对象家族的权限错误只终止该家族路径；不得换身份、改对象家族或改条件绕过。
+- “全部可见组织类型”是例外：三个独立元数据调用可保留成功家族，并明确列出无权限或不可访问的家族；不得把未返回的家族说成不存在。
+- 名称、编码和人员姓名是搜索条件，不是组织 ID。组织 ID 是不透明的非空字符串，只能来自用户明确提供或前序真实返回。校验时仅用 trim 判断是否空白：trim 后为空的 ID 无效，ID 列表中任何空白元素（如 `id1, ,id2`）都使整次输入无效。trim 不得用于转发；任何非空白 ID 必须逐字节原样传给命令，不得解析、重新格式化、改写、补全或重排。无效 ID 不得传给 `--id-list` 或 `--organization-id`。
+- 字段 API 名只能来自匹配家族的本轮字段结果；字段缺失或歧义时澄清，不能跨家族复用。
+- `parents` 和 `tree` 不接受字段参数。需要名称、编码、头像或其他可读字段时，按 reference 的两阶段流程批量详情补全；详情失败时只可说明关系 ID 已获得、可读详情不可得，绝不推断名称或值。
+- 分页、`has_more`、`truncated=true`、上限、字段缺失或权限边界影响结论时，明确说明已返回范围；不把可见路径、树或聚合说成全量。
+- 答复结论前置，使用接口返回的业务显示名和原样组织名称；不输出 API 名，除非用户明确询问。

package/skills/people-corehr-organization/references/aggregate.md

@@ -0,0 +1,11 @@
+# 组织聚合
+
+用于数量、层级、后代关系或跨家族确定性比较。先按家族调用 [tree.md](tree.md) 或 [hierarchy.md](hierarchy.md)，只使用其标识、`parent_id`、`level`、直接下级计数和每层计数计算关系指标。
+
+## 规则
+
+- 关系数量、层级阈值、最深已返回层级和父子关系不需要字段详情；不得把树中的 ID 当成名称或编码。
+- 按名称、编码、人员或其他字段筛选，或比较这些可读值时，先按 [metadata.md](metadata.md) 确认字段，再对相关 ID 用同一家族 [detail.md](detail.md) 批量查询。不同家族绝不复用 ID 或字段 API 名。
+- 使用 `all_children` 和每层计数进行节点级统计；`level_info` 的示例 ID 不能代表完整集合。
+- 任何输入出现权限边界、分页、`has_more`、`truncated=true`、数量上限或详情补全失败时，只计算真实可用范围，不能声称全量最大值、完整集合或完整交集。
+- 单一家族失败只停止该家族指标；多家族问题可呈现已成功家族的独立结果，并明确哪些家族不可访问。失败详情不允许推断筛选值或比较结论。

package/skills/people-corehr-organization/references/detail.md

@@ -0,0 +1,39 @@
+# 组织详情
+
+仅当用户明确提供组织 ID，或前序真实结果已返回 ID 时使用。每个 ID 都是不透明的非空字符串。校验时仅用 trim 判断空白：任一 ID 的 trim 结果为空，或 `--id-list` 含空白元素（如 `id1, ,id2`），整次输入无效且不得执行。trim 只用于此校验；每个非空白 ID 必须逐字节原样转发，不得解析、重新格式化、改写、补全或重排。指定字段前，按 [metadata.md](metadata.md) 确认相同家族的字段 API 名。
+
+## 命令
+
+部门：
+
+```bash
+people-cli corehr +department-detail \
+  --as user --format ndjson \
+  --id-list "<id1,id2>"
+```
+
+成本中心：
+
+```bash
+people-cli corehr +cost-center-detail \
+  --as user --format ndjson \
+  --id-list "<id1,id2>"
+```
+
+自定义组织：
+
+```bash
+people-cli corehr +custom-org-detail \
+  --as user --format ndjson \
+  --object-api-name "<custom_org_xxx>" \
+  --id-list "<id1,id2>"
+```
+
+用户要求已确认字段时，在所选家族命令末尾追加 `--field-api-name-list "<field1,field2>"`；否则直接执行基础命令。
+
+## 结果处理
+
+- 枚举和人员字段按 [field-values.md](field-values.md) 读取对象或数组；自定义字段从匹配 `custom_api_name` 的 `custom_fields[].value` 读取。
+- 多个 ID 与字段均用逗号分隔；详情行必须与输入 ID 对应，只展示用户要求的字段。
+- 已确认字段未返回时，说“本次未返回字段值”，而不是补写或推断值。人员和枚举字段只使用接口返回的可读值。
+- 此家族权限错误终止该详情路径。详情不能替代父链或树关系查询。

package/skills/people-corehr-organization/references/field-values.md

@@ -0,0 +1,44 @@
+# 枚举与人员字段
+
+search/detail 已将枚举和指向 `employment` 的 lookup 转成结构化值。单选是一个对象，多选是对象数组；按实际返回形态读取，不把整个对象当作 ID。
+
+| 字段 | 展示值 | 可继续传递的 ID |
+|---|---|---|
+| 枚举 | `name.zh_cn` / `name.en_us` | `id` |
+| employment lookup | `name`，头像为 `avatar_url` | `employment_id` |
+
+标准字段直接从字段值读取上述属性。自定义字段先在 `custom_fields` 中按 `custom_api_name` 找到对应项，再从其 `value` 读取同一结构：
+
+```json
+{
+  "custom_fields": [
+    {
+      "custom_api_name": "status",
+      "value": {
+        "id": "enabled",
+        "name": {
+          "zh_cn": "启用",
+          "en_us": "Enabled"
+        }
+      }
+    },
+    {
+      "custom_api_name": "owner",
+      "value": {
+        "employment_id": "emp_1",
+        "name": "张三",
+        "avatar_url": "https://example/avatar"
+      }
+    }
+  ]
+}
+```
+
+## 处理规则
+
+- 多选值逐项读取；保留接口返回顺序，不去重或重排。
+- 枚举显示优先使用用户当前语言；该语言缺失时可使用另一个已返回语言。`name` 缺失时只展示 `id`，不得编造名称。
+- employment 的后续调用只使用 `employment_id`；不得把 `name`、`avatar_url` 或整个对象当作 ID。`name` 或 `avatar_url` 缺失时不得推断。
+- `custom_fields[].value` 已是对象或数组，不要再次当作 JSON 字符串解析。非枚举、非 employment lookup 的自定义字段保持其实际返回形态。
+- 指向其他对象的 lookup 不适用本页结构，不得按 employment 字段解释。
+- parents/tree 的关系 ID 返回不受此结构变化影响；仅在后续 search/detail 补全可读字段时应用本页规则。

package/skills/people-corehr-organization/references/hierarchy.md

@@ -0,0 +1,61 @@
+# 组织层级
+
+用于查询直接上级、当前可见父链或路径。先取得父链 ID；只有用户需要可读字段时才批量详情补全。
+
+每个输入和返回的组织 ID 都是不透明的非空字符串。校验时仅用 trim 判断空白：任一 ID 的 trim 结果为空，或 `--id-list` 含空白元素（如 `id1, ,id2`），整次输入无效且不得执行。trim 只用于此校验；每个非空白 ID 必须逐字节原样转发，不得解析、重新格式化、改写、补全或重排。
+
+## 第一阶段：父链 ID
+
+部门：
+
+```bash
+people-cli corehr +department-parents \
+  --as user --format ndjson \
+  --id-list "<id1,id2>"
+```
+
+成本中心：
+
+```bash
+people-cli corehr +cost-center-parents \
+  --as user --format ndjson \
+  --id-list "<id1,id2>"
+```
+
+自定义组织：
+
+```bash
+people-cli corehr +custom-org-parents \
+  --as user --format ndjson \
+  --object-api-name "<custom_org_xxx>" \
+  --id-list "<id1,id2>"
+```
+
+这些命令只接受关系参数，绝不传 `--field-api-name-list`。
+
+## 第二阶段：按需详情补全
+
+当用户要求名称、编码、头像或任何可读字段时，收集父链中需要展示的 ID，按 [detail.md](detail.md) 选择同一家族详情命令并一次批量传入这些 ID 和已确认字段。以详情结果按 ID 回填，必须保留每个父级与目标节点的关联；不得按详情返回顺序重排父链。父链 ID 的接口顺序用于识别关系，最终展示顺序按下一节处理。
+
+## 结果处理
+
+- parents 接口中的父级顺序是从目标节点的直接上级到当前可见最高层（近 → 远）。用户询问单个“上级”时，只返回第一个直接可见上级。
+- 用户询问“完整上级链路”或“路径”时，将接口返回的可见父级逆序为最高层到直接上级，再把目标节点追加到末尾且只出现一次，最终按“当前可见最高层 → … → 直接上级 → 目标节点”展示。
+- 没有数量限制或不完整标记时，使用以下输出结构：
+
+  ```text
+  当前权限范围内可见的完整上级<组织家族>链路（最高层 → 目标<组织家族>）是：
+  <当前可见最高层> → … → <直接上级> → <目标节点>
+  其中，前 <父级数量> 个是 <目标节点> 的全部可见上级<组织家族>。
+  ```
+
+  例如部门父级依次返回“OPENAPI自动化专用部门数据01「勿删勿动」”“组织自动化根部门”，目标是“部门数据01”时，输出：
+
+  ```text
+  当前权限范围内可见的完整上级部门链路（最高层 → 目标部门）是：
+  组织自动化根部门 → OPENAPI自动化专用部门数据01「勿删勿动」 → 部门数据01
+  其中，前两个是 部门数据01 的全部可见上级部门。
+  ```
+- 父链为空不能证明租户全局根节点；限制或不完整结果不能称完整路径。
+- 第一阶段成功而第二阶段失败时，可说明已取得关系 ID、可读详情不可得；不能猜名称、头像或其他字段值。
+- 家族权限错误终止该路径，不得改查其他家族、身份或条件。

package/skills/people-corehr-organization/references/lookup.md

@@ -0,0 +1,41 @@
+# 组织搜索
+
+用于按名称、编码、人员或其他字段值定位已选家族的组织节点。需要返回指定字段时，先按 [metadata.md](metadata.md) 确认字段 API 名。
+
+## 命令
+
+部门：
+
+```bash
+people-cli corehr +department-search \
+  --as user --format ndjson \
+  --keyword "<search_term>"
+```
+
+成本中心：
+
+```bash
+people-cli corehr +cost-center-search \
+  --as user --format ndjson \
+  --keyword "<search_term>"
+```
+
+自定义组织：
+
+```bash
+people-cli corehr +custom-org-search \
+  --as user --format ndjson \
+  --object-api-name "<custom_org_xxx>" \
+  --keyword "<search_term>"
+```
+
+用户要求返回已确认字段时，在所选家族命令末尾追加 `--field-api-name-list "<field1,field2>"`；不需要指定字段时保持上面的基础命令。
+
+## 结果处理
+
+- 枚举和人员字段按 [field-values.md](field-values.md) 读取对象或数组；自定义字段从匹配 `custom_api_name` 的 `custom_fields[].value` 读取。
+- 搜索词不能为空，首次查询保留用户原始词（含标点、空格及中英混合）。
+- 未命中时，仅说明已选家族未找到；唯一命中可继续详情、父链或树查询；多个命中展示少量可读候选并请用户选择。
+- 不把相似候选、名称、编码或人员姓名当作 ID。`has_more` 或返回上限表示可能还有更多结果。
+- 搜索结果中的组织 ID 是不透明的非空字符串；后续使用时必须原样传递，不得解析、改写或补全。
+- 此家族权限错误终止该搜索路径。人员字段未返回可读值时，不得据此推断负责人或归属。

package/skills/people-corehr-organization/references/metadata.md

@@ -0,0 +1,40 @@
+# 组织元数据
+
+仅在需要选择字段、列出可见类型或解析自定义组织标签时使用。按家族独立调用，不先做全局探测。
+
+## 命令
+
+部门字段：
+
+```bash
+people-cli corehr +department-field-list --as user --format json
+```
+
+成本中心字段：
+
+```bash
+people-cli corehr +cost-center-field-list --as user --format json
+```
+
+自定义组织标签发现：
+
+```bash
+people-cli corehr +custom-org-object-list --as user --format json
+```
+
+选定自定义组织的字段：
+
+```bash
+people-cli corehr +custom-org-field-list \
+  --as user \
+  --format json \
+  --object-api-name "<custom_org_xxx>"
+```
+
+## 选择规则
+
+- 明确“部门”只读取部门字段；明确“成本中心”只读取成本中心字段。
+- 自定义组织先从 `objects` 的 `object_label` 唯一匹配用户标签，取得 `object_api_name`；标签无匹配或多匹配时澄清。只有需要字段时才调用该对象的字段列表。
+- 字段只从相同家族返回的 `fields` 里以唯一显示名选择 `field_api_name`。自定义对象列表不含字段，不能据此猜测字段。
+- 需要“全部当前可见组织类型”时，分别执行部门字段、成本中心字段和自定义对象列表三条命令。合并每个成功调用的业务显示名；对权限失败的家族标为不可访问，仍保留其他成功结果。
+- 单一指定家族的元数据权限错误终止该路径；不得改查其他家族或身份。未知、缺失或歧义字段必须澄清。

package/skills/people-corehr-organization/references/tree.md

@@ -0,0 +1,45 @@
+# 组织树
+
+用于查询直接下级、全部后代、子树或层级。树命令只返回关系标识和层级摘要；可读字段必须随后批量详情补全。
+
+组织 ID 是不透明的非空字符串。校验时仅用 trim 判断空白：trim 结果为空的 ID 无效，任何 ID 列表中的空白元素（如 `id1, ,id2`）也无效。trim 只用于此校验；每个非空白 ID 必须逐字节原样转发，不得解析、重新格式化、改写、补全或重排。仅在根节点 ID 校验为非空白时传 `--organization-id`；不得传空值，因为省略或空的 `--organization-id` 表示查询根范围，会改变子树语义。
+
+## 第一阶段：树关系 ID
+
+部门：
+
+```bash
+people-cli corehr +department-tree \
+  --as user --format ndjson
+```
+
+成本中心：
+
+```bash
+people-cli corehr +cost-center-tree \
+  --as user --format ndjson
+```
+
+自定义组织：
+
+```bash
+people-cli corehr +custom-org-tree \
+  --as user --format ndjson \
+  --object-api-name "<custom_org_xxx>"
+```
+
+以上是可直接执行的当前可见根范围基础命令。查询指定节点子树时，在所选家族命令末尾追加 `--organization-id "<non_empty_organization_id>"`；全部后代再追加 `--need-all`；明确包含停用组织时再追加 `--need-inactive-org=true`。这些命令绝不传 `--field-api-name-list`。
+
+指定节点时 ID 必须来自用户明确提供或前序真实结果；仅给出自定义对象类型、未给根节点而问题限定某个子树时，先澄清根节点。
+
+## 第二阶段：按需详情补全
+
+用户要求名称、编码、负责人或其他可读字段时，从树结果中收集需要展示/筛选的节点 ID，按 [detail.md](detail.md) 对同一家族执行一次或分批详情查询，并用 ID 回填。保留原有 `parent_id`、`level`、直接下级计数和树关系，不得因详情返回顺序改变节点顺序或重建关系。
+
+## 查询范围与结果
+
+- 明确要求全部后代、完整子树、递归结果或后代总数时传 `--need-all`；只问直接下级时不传。
+- 默认查询只包含启用组织。仅在用户明确要求停用组织或所有状态时传 `--need-inactive-org=true`；默认查询为空只能说明未返回启用组织，不能证明不存在停用的下级或后代。
+- 使用返回的 `level`，不自行偏移或重算。`level_info.example_ids` 始终只是每层最多 10 个 ID 的样本；即使整体 `truncated=false`，也绝不是该层完整节点列表。
+- 用户要求列出某一层全部节点时，必须从 `all_children` 按 `level` 筛选，不能使用 `level_info.example_ids` 代替；同时仍须检查树结果的 `truncated` 以及 `all_children` 的返回上限和数量边界，受限时只能列出已返回范围。
+- 关系成功但详情失败时只可报告 ID、关系和层级，不得凭关系推断名称或字段值。家族权限错误终止该路径。