用途：这是 reasonhub-skills 中多个技能共用的参考文档，说明 ValueSet 展开（expansion）机制，供 snomed-semantic、clinical-search、terminology-crossmap 使用，不直接由用户查询触发。
主要能力与要点： 展开前每个 compose.include 块必须指定 version，否则展开会静默失败或使用意外默认值；可先调用 list_available_codesystem_versions() 获取版本字符串。
valueset_expand 失败：部分 agent harness 会把类型为 $ref schema 对象的 valueset 参数序列化成普通字符串，MCP 服务器收到字符串后返回 “valueset: must be object / must be null / must match a schema in anyOf”。这是 pi（XML <parameter> 标签序列化）中的已知问题，其他不处理嵌套 JSON 对象的 harness 也可能出现。重新格式化 JSON、删除 count/offset 等可选参数、改变引号或转义、重试同一调用都无法修复。不要重试，也不要提供替代方案，应立即改用 reasonhub-skills expand。
CLI 回退：valueset_expand 失败或超时时，无论使用哪种 harness，推荐回退命令为 echo '{ ... paste ValueSet JSON here ... }' | reasonhub-skills expand。若报 stdin is closed 或打印帮助文本，说明 CLI 过旧，需升级：curl -fsSL https://raw.githubusercontent.com/reason-healthcare/reasonhub-skills/main/bin/reasonhub-skills
-o ~/.local/bin/reasonhub-skills && chmod +x ~/.local/bin/reasonhub-skills。无法立即升级时可加 --count 100 作为临时方案。不要并行运行 echo | 形式与 mktemp 形式，二者是替代关系，选一个执行并使用其输出。CLI 未安装时同样用上述 curl 命令安装。不要自行读取凭据，不要读取 ~/.reasonhub/config.toml、.reasonhub/config.toml、~/.pi/agent/mcp.json 或任何环境变量来提取 token 并手写 curl 命令；CLI 内部处理凭据。
截断：MCP 传输层会截断返回行，与 count 参数无关。展开成功后检查响应中的 total；若返回行数少于 total，应标注并停止：⚠️ Partial result — {n} of {total} codes shown. The full set is defined by the ValueSet JSON above; run it against any FHIR terminology server for the complete expansion. 不要用不同 count 或 offset 重试。
Python 批量脚本：循环展开多个 ValueSet 时使用 subprocess.run 的 input=，不要在 subprocess 调用内使用 heredoc（<< 'EOF'），否则会关闭 stdin 并导致 write_stdin failed: stdin is closed。小集合可顺序调用，20 个以上分析物建议用 ThreadPoolExecutor。LOINC 展开可能对同一 code 返回不同 display（规范名与短名），处理前按 code 去重。
调试清单：检查 version 是否与 list_available_codesystem_versions() 完全一致；用 codesystem_filter_properties(system=...) 核对属性名拼写；用 codesystem_lookup 确认过滤值存在且有效；先只保留一个过滤条件以定位空结果来源；SNOMED 属性过滤时，先查一个预期匹配的代表性概念，确认其确实带有该属性，原始概念（sufficientlyDefined = false）可能没有任何属性。