用友 SQL 助手（Yonyou SQL Assistant）
能力概述
面向用友产品实施顾问的"常用场景 SQL 查询"辅助能力，覆盖两件事：
- 生成：根据用户描述的查询意图，按指定方言（MySQL / PostgreSQL / Oracle / SQL Server）
产出准确的 SQL 语句，并附参数说明与注意事项。 - 执行：在用户确认后，通过
scripts/run_sql.py连接数据库，执行只读查询并返回
Markdown 表格 / CSV 结果。脚本内置只读护栏，仅允许SELECT/WITH语句，杜绝误改数据。
默认方言为 MySQL 8.0（用户主力环境）；用户未指定时按 MySQL 生成并在输出中提示可切换方言。
适用场景
- 用户请求"写一条 SQL""怎么查…""某方言怎么写…"等生成类诉求。
- 用户希望连接数据库实际跑一条查询并看结果（只读分析、对账、取数）。
- 用户给出表名/字段名但不知如何组织查询时，可结合通用场景模板产出。
生成工作流
> 两条硬性规范（来自实施经验沉淀，必须遵守）：
> 规范 A — 优先复用案例表/字段：references/kb/ 中的业务 SQL 是实际项目经验的总结，其表名、字段名、口径已对齐真实数据模型。命中某"分析场景"条目时，生成 SQL 必须直接采用案例中的真实表名与字段名，而非用通用模板的占位符或自行推断；仅在案例确实未覆盖、需新增字段时，才按规范 B 取字段。
> 规范 B — 结合数据字典取准字段：当场景无现成 kb 条目、或需补充/确认字段时，查 references/data_dict/<版本>/<领域>.md（大字典按版本拆分：旗舰版按 业务域/schema，高级版按 表名首字母），以字典中的权威字段名、类型、关联关系为准，杜绝臆造字段。
> 规范 C — 输出内容三限定（生成 SQL 时必须遵守，详见 references/kb/_case_standard.md §2.2–§2.4）：
> ① 字段别名一律英文（snake_case 或原字段大写形式），禁止中文别名——中文语义一律写在 -- 注释里；
> ② 档案主键必须翻译——凡输出基础档案的主键字段（pk_xxx / id / *_id），须同时带出该档案的编码(code) + 名称(name)，构成 pk + code + name 三件套；只给主键或只给名称均不合格；字典中确无编码字段时注明"待字典确认"，不得臆造；
> ③ 所有输出字段必须有 -- 注释说明业务含义，计算列须注明口径来源（公式 / 枚举翻译 / 日期算法）。
> 环境初始化（首次使用必做，幂等）：数据字典（旗舰版 + 高级版，体积较大）不随 skill 包分发（技能包本身仅约 40KB，远低于平台单包 10MB 体积上限），改为首次使用时从用友云盘分享链接按需下载到本地。每次生成 SQL 前，先用 Python 3（仅标准库，无需第三方包）运行：
> bash
> python3 <skill>/scripts/fetch_data_dict.py
>
> 脚本幂等：若 references/data_dict/ 已就位（含 .fetched_ok 标记）则秒过；否则自动从 https://pan.yonyou.com/s/duXJB5jTKY（公开分享、无访问密码、有效期至 2060-10-31）下载并解压到 references/data_dict/。落位后结构：references/data_dict/旗舰版/<业务域>/<schema>.md 与 references/data_dict/高级版/<首字母>.md。
- 业务匹配（优先，且强制复用案例对象名）：若用户查询涉及具体业务领域（财务 / 司库 / 供应链 / 人力 / 公共等）或能判定产品版本（高级版 / 旗舰版），优先在
references/kb/<版本>/<领域>.md中查找匹配的"分析场景"条目。命中后，直接复用条目里的表名、字段名、口径与 SQL 骨架，仅做必要的方言或参数适配（业务 SQL 多为 Oracle / 达梦，注意方言迁移）。无法判定版本时默认查"高级版"；领域不明时再回退到references/scenarios.md通用模板。 - 数据字典校核（取准字段）：当无命中 kb 条目、或需在案例中补充/确认字段时，按产品版本查对应字典：
- 旗舰版：references/data_dict/旗舰版/<业务域>/<schema>.md（如references/data_dict/旗舰版/智能会计/figlbase.md）。
- 高级版：references/data_dict/高级版/<表名首字母>.md（如references/data_dict/高级版/G.md；来源为另一 skill 沉淀的tables_uniq.jsonl，7543 张表）。
不确定表归属时，直接grep表名于references/data_dict/<版本>/，命中后读取对应文件中的## 表名段落。以字典中的权威字段名、数据类型、主外键/关联关系替换占位符；对不确定字段名，以字典为准，不得凭经验猜测。 - 识别场景：将用户意图映射到
references/scenarios.md中的 13 类场景之一（或多类组合）。 - 确定方言：从用户表述或上下文判断目标方言；未指定时默认 MySQL 8.0，并在回复中声明。
- 套用模板：从
references/scenarios.md选取对应场景的方言写法，替换占位符
（{table}{col}{pk}{fk}{num_col}{date_col}{n}{threshold}等）为真实对象名（优先取自 kb 案例与数据字典）。 - 差异校验：涉及分页、日期、空值、字符串拼接、限制行数、标识符引号等差异点时，
交叉核对references/dialects.md速查表，避免混用方言特有函数。 - 产出与说明：输出完整 SQL（带语法高亮），并附：
- 参数占位说明；
- 关键注意事项（如"分页必须 ORDER BY""时间用半开区间""MySQL 5.x 不支持窗口函数"等）；
- 字段来源标注（说明关键表/字段取自 kb 案例 / 数据字典，便于复核）；
- 如需其他方言，明确告知已按 X 方言生成，并可一键改写。
> 不得臆造不存在的表/字段名。若用户未提供对象名，使用占位符并标注"请替换为实际对象"；涉及业务字段时，优先从 kb 案例与数据字典取真实名称。
执行工作流（只读）
仅当用户明确要求"执行/跑一下/连库查询"时启动，且只针对 SELECT / WITH 语句。
- 确认连接：执行前确认目标 profile（见下方连接配置）。若用户未指定库，询问使用哪个 profile。
- 调用执行器：用 managed Python 运行
scripts/run_sql.py：
bash PYTHON=/Users/xxx/.workbuddy/binaries/python/versions/3.13.12/bin/python3 $PYTHON <skill>/scripts/run_sql.py \ --profile <profile名> \ --sql "SELECT ..." \ --format markdown --limit 200
也可将 SQL 写文件后用--sql-file query.sql。 - 结果呈现：将脚本输出的 Markdown 表格直接回显给用户；如为 CSV 可提示保存路径。
- 错误处理：若脚本报"只读护栏"拒绝，说明原因并确认用户是否确实需要写操作（本 skill 不支持）。
若报连接/驱动缺失，提示安装对应驱动（pip install SQLAlchemy pymysql等）。
连接配置（本地，不含在 skill 内）
- 示例：
scripts/config_example.json，含四个库 profile 模板。 - 用户需复制为
~/.workbuddy/sql-query-assistant-config.json并填入真实连接信息
（路径可由--config覆盖）。密码仅存本地，勿随 skill 分发或提交仓库。 - 驱动安装：MySQL→
pymysql；PG→psycopg2-binary；SQL Server→pyodbc（需 unixODBC + MS ODBC Driver）；
Oracle→oracledb（thin 模式纯 Python）。统一依赖SQLAlchemy。
数据字典（业务表结构）落位说明
用友产品的真实表/字段权威来源放在 references/data_dict/<版本>/，但以"首次使用按需下载"方式获取，不随 skill 包内置（避免包体过大影响 skillhub 发布，也便于字典独立更新）：
- 获取方式：运行
scripts/fetch_data_dict.py（仅标准库）。脚本从用友云盘公开分享https://pan.yonyou.com/s/duXJB5jTKY拉取data_dict文件夹（旗舰版 + 高级版，体积较大；注意这是运行时按需下载的字典、不计入技能包，技能包本身仅约 40KB，远低于平台单包 10MB 体积上限）并解压到references/data_dict/；幂等、可重复调用，已下载则跳过。分享有效期至 2060-10-31，过期后需更新脚本中的SHARE_ID。 - 旗舰版：由 V5 数据库数据字典 HTML 提炼，覆盖智能会计 / 司库 / 供应链 / 共享 / 费控 / 税务云 / 企业绩效 / 收入云 / 协同云 9 个业务域，60+ schema、2.5 万+ 张表；结构
references/data_dict/旗舰版/<业务域>/<schema>.md，README.md为索引（域 → schema 列表）。 - 高级版：由另一 skill 沉淀的
tables_uniq.jsonl提炼（7543 张表、30 万+ 字段），按表名首字母分文件references/data_dict/高级版/<首字母>.md，README.md为索引。
生成 SQL 时按"规范 B"优先从此处取准字段名、类型与关联关系；定位某表时，grep 表名于 references/data_dict/<版本>/。
资源索引
references/
scenarios.md— 13 类通用场景的 MySQL/PostgreSQL/Oracle/SQL Server 四方言模板，生成 SQL 的主知识库（业务无关时回退使用）。dialects.md— 方言差异速查表与关键注意点，用于生成时的差异校验。kb/— 业务 SQL 技能库：按 产品版本（高级版 / 旗舰版）× 业务领域（财务 / 司库 / 供应链 / 人力 / 公共等）× 分析场景 沉淀的可复用 SQL，用于提升业务查询准确性。公共域收跨业务领域的通用 SQL（当前为单据审批流类）。索引与提炼规范见kb/index.md，单条格式见kb/_template.md。data_dict/— 用友产品数据字典（表/字段/类型/主外键/关联关系），生成 SQL 时按"规范 B"取准字段名。不随包内置：首次使用时由scripts/fetch_data_dict.py从用友云盘分享https://pan.yonyou.com/s/duXJB5jTKY下载到本地（references/data_dict/）。已沉淀 旗舰版（9 域、2.5 万+ 表，V5 字典提炼）与 高级版（7543 表、30 万+ 字段，tables_uniq.jsonl 提炼）；定位字段时grep表名于data_dict/<版本>/。
scripts/
run_sql.py— 多方言只读执行器（SQLAlchemy 驱动，含只读护栏，输出 Markdown/CSV）。config_example.json— 连接 profile 配置样例，用户复制后填写真实信息。fetch_data_dict.py— 首次使用时的数据字典获取脚本（标准库实现，幂等，从用友云盘分享链接下载并解压到references/data_dict/）。
文件清单
yonyou-sql-assistant/
├── SKILL.md 技能说明：职责定位、触发条件、生成/执行工作流、数据字典落位与治理说明
├── references/
│ ├── scenarios.md 13 类通用查询场景的四方言（MySQL/PostgreSQL/Oracle/SQL Server）模板
│ ├── dialects.md 方言差异速查表与关键注意点
│ └── kb/
│ ├── _case_standard.md 案例沉淀规范（总规范：命名/SQL编写/拆分抽象/脱敏/门禁）
│ ├── _template.md 单条 SQL 案例模板
│ ├── _contribute_checklist.md 案例贡献清单与沉淀流程（维护者专用 SOP）
│ ├── index.md 业务 SQL 索引与提炼规范
│ ├── 旗舰版/
│ │ ├── 供应链.md 旗舰版·供应链域案例
│ │ ├── 公共.md 旗舰版·公共域案例（单据审批流）
│ │ ├── 司库.md 旗舰版·司库域案例
│ │ └── 财务.md 旗舰版·财务域案例
│ └── 高级版/
│ ├── 财务.md 高级版·财务域案例
│ └── 司库.md 高级版·司库域案例（融资余额归集：7 类融资）
└── scripts/
├── config_example.json 数据库连接 profile 配置样例
├── fetch_data_dict.py 首次使用按需从用友云盘下载数据字典（标准库、幂等）
├── run_sql.py 多方言只读执行器（SQLAlchemy，含只读护栏，输出 Markdown/CSV）
└── kb_quality_check.py 案例库质量门禁 + 覆盖盘点（扫描缺字段 / 检索关键词合规 / 登记漂移，标准库）
> 注：references/data_dict/（旗舰版 + 高级版，体积较大）不随包内置，首次使用时由 scripts/fetch_data_dict.py 从用友云盘分享链接下载到本地，故不列入上方清单；技能包本身仅约 40KB。
