SAC 从业人员信息公示查询
查询中国证券业协会公示的证券从业人员执业信息：按机构查名单、按姓名查执业详情、按编号（证书编号/证件号）定位人员，支持多条件组合与结果导出。
功能特性
- 机构查名单：输入机构名（模糊词先返回候选确认），一次拉取该机构全部登记人员
- 大机构分页抓取：分页通道（预览/全量两档），单次响应体小、翻页稳定
- 姓名查执业信息：业务类别、登记日期、证书编号、登记次数、违规记录计数
- 证书编号/证件号直查：S 开头证书编号或 18 位证件号无需其他条件即可定位人员并取完整详情
- 多条件组合：姓名 × 机构 × 编号（执业编号/工号本地过滤）任意组合精确筛选
- 统计概览：登记机构按类型的人员分布
触发示例
查中信建投有哪些从业人员 → 机构名模糊时先列候选请确认
查一下张某某的执业信息 → 姓名查询
S0820108040347 是谁 → 证书编号直查
爱建证券里有没有叫顾某某的 → 姓名+机构组合
一、使用方法
用户传入的参数：$ARGUMENTS
命令模板（SKILL_DIR = 本 skill 的安装目录，如 Windows 下为 %USERPROFILE%\.workbuddy\skills\sac-person-query，macOS/Linux 下为 ~/.workbuddy/skills/sac-person-query）：
python "SKILL_DIR\scripts\sac_query.py" <子命令> [参数]
第 1 步：判断查询意图
person 支持三个条件任意组合：
| 用户想做什么 | 典型问法 | 用法 |
|---|---|---|
| 查机构的人员名单 | "中信建投有哪些从业人员" | --org <机构全称> |
| 查某人的执业信息 | "张三的执业信息" | --name <姓名> |
| 编号定位 | "证书编号 S0820… 是谁" / "证件号 3203… 是谁" | 单独 --no <编号>（直查） |
| 编号 + 名单筛选 | 已知执业编号/工号 | --no + --name 或 --org |
| 机构内找人 | "爱建证券里有没有叫顾某某的" | --name + --org |
| 机构名不确定 | "建投"之类的模糊叫法 | 先跑 org 列候选 |
第 2 步：机构名模糊时先确认（查机构前必做）
接口只认机构精确全称（如"中信建投证券股份有限公司"）。用户给了模糊机构名（如"建投"、"中信建投"）时，先列候选让用户确认，绝不要替用户猜：
python "SKILL_DIR\scripts\sac_query.py" org "建投"
把返回的 candidates（机构全称、类型、人数）展示给用户，请用户确认具体机构。若用户不在线确认，停止并等待；不要自动选择候选。
第 3 步：执行查询
SQ="SKILL_DIR\scripts\sac_query.py"
# 按机构查全量名单（--org 用确认后的精确全称；--out 缺省落到当前目录 sac_output/）
python "$SQ" person --org "爱建证券有限责任公司" --limit 20 --out "./sac_output"
# 大机构名单:分页通道预览(默认只抓前 limit 条) / 全量抓取落盘(--all + --out)
python "$SQ" person --org "东方证券股份有限公司" --paged --limit 5
python "$SQ" person --org "东方证券股份有限公司" --paged --all --out "./sac_output"
# 按姓名查
python "$SQ" person --name "张三" --out "./sac_output"
# 机构 + 姓名 组合（机构仍需精确全称）
python "$SQ" person --name "张某某" --org "爱建证券有限责任公司"
# 编号定位：证书编号（S 开头）或 18 位证件号可单独直查，脚本自动识别；
# 执业编号/工号不能单独查，须搭配 --name 或 --org
python "$SQ" person --no "S1xxxxxxxxxxxxx"
python "$SQ" person --no "320323xxxxxxxxxxxxx"
python "$SQ" person --name "张某某" --no "S1xxxxxxxxxxxxx"
python "$SQ" person --org "爱建证券有限责任公司" --no "123456"
不确定编号类型时，直接用 --no <编号> 单独尝试即可：命中则返回结果，未命中会在 note 中提示改用组合查询。
第 4 步：结果解读与呈现
count为命中总数；remoteCount为远程查询（编号过滤前/分页端点 total）的原始条数，两者差异说明编号过滤生效；truncated=true表示展示被截断（完整结果看output_files落盘文件）。mode=paged= 走了分页通道（paged+all表示已抓全量）；paged 模式下pageCount为总页数、fetched为本次实际抓取条数。partial=true（仅 paged）= 该机构人数多于本次抓取量（未加--all时只抓了前--limit条预览，远端还有数据未取）；用户需要全量时提示加--all --out。mode=certif-direct= 走了编号直查链路（编号定位 → 详情），此时记录额外含机构官网（compWeb）、投诉咨询电话；query.noParam为certifNo（证书编号）或certNo（证件号）。- 向用户复述关键信息：姓名、机构、业务类别（pracCtegName）、登记日期（regDate）、证书编号（certifNo）、违规计数是否为 0。
ambiguous=true（退出码 2）= 机构名模糊，按候选列表询问用户。ok=false（退出码 1）= 出错，把error内容转述给用户；"参数错误"通常是机构全称不对。count=0且remoteCount>0= 编号在该范围内无匹配（可能编号有误）；remoteCount=0且count=0= 公示系统无此登记记录；编号直查count=0时按note提示（可能是执业编号/工号被当作直查编号，改用组合查询）。如实告知。- 落盘结果默认不弹出预览：查询完成后只向用户报告文件保存路径（
output_files）与关键统计（count/remoteCount/total 等），不要主动把 JSON/CSV 文件作为产物卡片展示；仅当用户明确要求查看/预览文件时再展示。批量查询（数百条以上）尤其不要弹预览。
补充：机构统计概览（可选）
python "SKILL_DIR\scripts\sac_query.py" stat
返回 317 家机构按类型的数量与人员总数；--refresh 可强制刷新机构索引缓存。
使用注意事项
- 大机构查询：优先
--paged（翻页稳定、单次响应体小）；不加--paged时务必带--limit，并加--out落盘完整结果。 - 限流：内置请求间隔 0.6 秒，不要调小；不要并发调用；不要绕过
sac_query.py直接高频请求公示接口。 - 敏感信息：登记历史/任职轨迹属较敏感个人信息，落盘结果仅存放在用户指定目录（默认当前目录
sac_output/），提示用户妥善保管。
二、技术实现细节
以下内容供排查问题、理解脚本行为时参考，日常使用无需阅读。
数据源
- https://gs.sac.net.cn/ （中国证券业协会从业人员信息公示系统），公开公示信息，无需登录。
- 接口细节（端点、参数规则、响应字段）见
references/api_docs.md，仅当需要排查字段含义或接口行为时再加载。
脚本架构
scripts/sac_client.py：核心库，封装公示系统接口调用、限流与重试。scripts/sac_query.py：CLI 入口，提供org/person/stat三个子命令。references/api_docs.md：接口文档。
查询链路：
- 常规查询（姓名/机构/组合）：远程查询 → 本地过滤 → 输出。
- 编号直查（证书编号/证件号单独使用）：编号定位 → 取详情（
mode=certif-direct），返回含机构官网、投诉电话的完整记录。 - 分页查询（
--paged）：按机构走分页端点，翻页真实生效；单页条数默认 1000（--page-size可调，上限 1000，超出自动收敛）；--all抓全量，否则只抓前--limit条预览。
缓存与输出
- 全量机构名单有本地缓存：当前项目
.workbuddy/cache/sac_org_index.json（TTL 7 天），stat --refresh强制刷新。 - 输出目录默认跟随当前工作目录的
sac_output/（不存在则创建），JSON + CSV 双格式落盘。
可移植性与合规
- 脚本用 Python 标准库实现（零第三方依赖），无遥测、无外部数据上传；输出目录默认跟随当前工作目录的
sac_output/（不存在则创建）。 - 内置限流（请求间隔 0.6 秒）与失败退避重试，不对公示系统造成压力。
- 数据来源为中国证券业协会从业人员信息公示系统（gs.sac.net.cn），公开公示信息，无需登录；查询结果仅落盘到用户指定目录，登记历史等较敏感字段已在文档中标注妥善保管提示。
