增值税政策第二大脑（vat-policy）
把本地「增值税政策文档」目录下成批的增值税政策 docx（国家税务总局 / 财政部 / 地方法规三类）封装成可全文检索的「第二大脑」。每篇文档正文前都内嵌结构化元数据（来源 / 效力级别 / 发布日期 / 栏目 / 原文链接），已被抽取进索引，可精准过滤与引用。
> 语料规模取决于你自备的文档：本技能不随包分发任何政策原文（2200+ 篇 docx 体积与版权原因）。安装后，请按下方「语料准备」放置你自己的政策 docx 集合，再首次运行 build_index.py 自动建索引。索引规模、日期跨度会随你的语料自动变化。
何时使用
- 用户问「某增值税政策怎么规定」「XX 优惠怎么享受」「留抵退税 / 起征点 / 加计抵减 / 差额征税 等如何适用」。
- 需要定位并引用政策原文、出具处（发文机关 + 发布日期 + 原文链接）。
- 对比「增值税法」与「增值税暂行条例」、新旧政策衔接等。
- 用户要「查某个政策的全文 / 解读」。
语料准备（重要：首次使用前必做）
本技能只提供检索程序，政策 docx 原文需你自己准备：
1. 在你的电脑上建一个根目录（例如命名为 增值税政策文档，可放在 ~/Desktop 或 ~/Documents 下），其下按三个子文件夹放置 docx：
- 国家税务总局/（若干 .docx）
- 财政部/（若干 .docx）
- 地方法规/（若干 .docx）
2. 每篇 docx 正文首行建议为标题，其下含一行 来源 … 发布日期 … 元数据（脚本按此抽取；缺失则仅索引标题与正文）。
3. 可选：若你有一份记录「抓取失败政策」的 待补清单.xlsx（列：序号/标题/来源/原文链接/原因），放在根目录，脚本会把它解析进 gaps 命令。
文档根目录（可配置）
默认根目录（按此优先级解析）：
1. 环境变量 VAT_POLICY_ROOT
2. 用户主目录下名为 增值税政策文档 的目录（~ 为用户主目录，Windows 即 C:\Users\<你的用户名>）；也可放在任意位置
脚本均接受 --root DIR 覆盖。
核心脚本
位于 scripts/，用隔离 Python 运行（见下）。两个脚本：
- build_index.py：扫描 docx + 解析「待补清单.xlsx」，生成 SQLite FTS5 索引（trigram 中文子串检索）。仅在索引库不存在时自动构建一次，之后 query.py 直接复用。
- query.py：检索接口，子命令 search / list / read / lookup / gaps / stats。
运行环境（重要）
使用任意装了 python-docx 与 openpyxl 的 Python 3：
pip install python-docx openpyxl
PY=python3 # 或你的 Python 解释器路径
SKILL="<本技能安装目录，即含 SKILL.md 的 vat-policy 文件夹>"
所有命令在 scripts/ 目录内执行（cd "$SKILL/scripts"），因为 query.py 内部 import build_index。
工作流（请严格按此做检索）
- 先理解用户意图，把口语转成 2~6 字的政策关键词（如「留抵退税」「逾期申报罚款」「差额征税」「即征即退」）。中文检索按子串匹配，关键词越精炼命中越准。
- 检索：
"$PY" query.py search "关键词" --limit 10
可叠加过滤：--source 国家税务总局/--column 政策解读/--level 财政法律法规/--after 2024-01-01/--before 2025-12-31。 - 阅读全文（拿到 doc_id 后）：
"$PY" query.py read SAT-0010
返回元数据 + 正文；引用时务必带上「来源 + 发布日期 + 原文链接」。 - 定位标题：若记得大概标题，用
lookup：
"$PY" query.py lookup "增值税法" - 缺口核查：若检索无果，先查
gaps确认该政策是否本就在「待补清单」（抓取失败未入库）：
"$PY" query.py gaps
若命中缺口，明确告知用户「该政策在本地缺漏清单中（原因为抓取失败），建议按原文链接补全」。
输出纪律
- 先给结论，再给依据：回答增值税问题时，第一句直接说结论；随后列出命中政策的「标题 + 来源 + 发布日期 + 适用要点」，并附原文链接。
- 区分政策文件与政策解读：
栏目=政策解读是官方释义，引用法条以政策文件原文为准，解读仅作理解辅助。 - 效力提示：注意发布日期与「增值税法 2024-12-25 公布、2026-01-01 施行」的新旧衔接；旧条例/公告在其废止前仍可能有效，回答时标注时效性。
- 不杜撰：检索无结果且不在 gaps 中时，说明「本地语料未覆盖，建议补充」，不要凭记忆编条文。
- 已知缺口：语料中 242 条政策因抓取失败缺漏（见
待补清单.xlsx），属已知局限，已内置于gaps命令。
统计与维护
- 查看语料概览：
"$PY" query.py stats - 新增/替换 docx 后重建索引：
"$PY" build_index.py --force - 索引库位置：
<skill>/data/vat_policy.db（由脚本自动生成，不随技能包分发；发布技能时此文件应排除，由使用者首次运行自动构建）。
