z-grounded-source-qa

用途

Grounded Source QA 用于把任意本地 Markdown 或文本文件变成可追溯的证据基础，服务于回答、综合、比较、写作和人格模拟等任务。技能本身承载工作流与检索引擎，用户语料保持在技能之外。

主要能力

来源契约：识别用户纳入范围的精确文件或目录，接受 Markdown、纯文本、转录稿、会议记录、导出的网页和已解析文档；PDF、Office、图片、音频或视频需先用合适的解析器转换为 Markdown/文本再检索。保持原始文件不变，不静默添加网络知识、模型记忆或无关工作区文件，并说明任何实质性影响答案的来源访问限制。
检索工作流：在从语料做出实质性声明前，先将用户问题重述为待解决的声明或决策，生成 3–8 个检索表达式，覆盖用户措辞、同义词与缩写、可能的来源措辞、以及完整回答所需的原因、机制、风险或反论点。然后运行确定性检索脚本：

python3 scripts/search_evidence.py \
  --source "/path/to/source-or-directory" \
  --query "core phrase" \
  --query "synonym" \
  --query "likely source wording" \
  --top-k 8 \
  --format json

检查证据对象的覆盖范围、位置和上下文，将每个意图声明映射到证据。若证据只覆盖问题的一部分，改变表达式并运行第二次检索。当结果碎片化、冲突或低置信度时，直接阅读最接近的来源章节。仅在证据集充分后才起草。仅增加 --top-k 不算第二次检索；需改变措辞或搜索缺失的机制、例外、时间段或对立观点。一个空查询意味着当前表达式未命中，并不证明语料缺乏相关材料。

证据纪律：在内部将每个实质性陈述分类为直接（在一个来源段落中明确陈述）、综合（由多个段落组合支持且不添加新前提）、推断（依赖假设的合理结论，需标注假设）、无支撑（第二次检索和直接阅读后仍无充分证据，应省略或说明缺口）。对于高风险、有争议、公开或面向出版的声明，阅读 references/evidence-contract.md 并保留使用的证据 ID。当来源冲突时，展示冲突陈述和位置，区分日期、范围、说话人和定义差异，避免静默选择更便利的段落。
回答模式：选择满足用户的最小模式。自然回答以答案开头，在支持的声明后添加紧凑的来源位置。证据审计用于用户要求验证、引用、审计轨迹或出版审查时，格式为：

## Conclusion

## Evidence
- Claim — source file:line, page/time when available

## Inferences and assumptions

## Gaps or conflicts

人格或声音模拟使用来源支持的推理和词汇，保留限定词和不确定性，当来源提供框架但无直接答案时标记外推，绝不将虚构的私人想法呈现为来源材料。

检索输出：scripts/search_evidence.py 仅使用 Python 标准库，递归发现 .md、.markdown 和 .txt 文件，返回完整语义段落，保留文档、行、页、时间戳、章节和说话人元数据，对多表达式覆盖进行排序，合并相邻匹配段落，去重重复内容同时保留额外位置，支持通过 --regex 显式正则表达式查询，返回 JSON 证据对象供可靠下游使用。脚本在无证据匹配时以代码 1 退出，同时仍发出有效结果和查询未命中警告。
创建专用技能：当同一人物、书籍、政策、项目或产品语料将被反复查询时，使用专用技能。专业化应结合四层：检索能力 + 有界语料 + 答案契约 + 评估问题。需要时从 pdftotext 输出准备带页码标记的 Markdown：

python3 scripts/prepare_pdftotext.py \
  extracted.txt prepared-source.md \
  --title "Source title"

生成自包含专业化：

python3 scripts/create_specialized_skill.py \
  --name z-example-advisor \
  --title "Example Advisor" \
  --mode advisor \
  --source prepared-source.md \
  --output-root /path/to/.agent/skills \
  --trigger "example book" \
  --question "What should I do first and why"

根据预期答案契约选择 persona、advisor、policy 或 source-qa。生成的技能包含自己的检索器、语料目录、来源哈希、配置和评估问题。在公开发布前或当专业化需要自定义声音、政策权威、来源可靠性或失败边界规则时，阅读 references/specialization-guide.md。

使用方式

先确定来源契约，再运行检索工作流，检查证据对象，映射声明到证据，必要时进行第二次检索或直接阅读来源章节，最后根据用户要求的格式起草回答、审计、文章或模拟。完成前确认：每个实质性声明映射到直接证据、综合或标注的推断；至少运行了一次多表达式检索；不完整的第一轮证据触发了重写的第二次检索；查询未命中与来源缺失保持分离；冲突和来源限制可见；来源位置足够精确以便他人验证；最终格式匹配用户请求；生成的专用技能在分享前用现实问题测试过。

适用场景

适用于基于用户自有本地语料的问答、摘要、比较、决策、引用、人格模拟、文章撰写、脚本编写和事实核查。特别适合需要可追溯证据、证据审计或出版审查的场景，以及同一语料被反复查询时创建专用技能。

限制

技能不静默添加网络知识、模型记忆或无关工作区文件。PDF、Office、图片、音频或视频需先转换为 Markdown/文本。仅增加 --top-k 不算第二次检索。空查询不证明语料缺乏相关材料。无支撑的声明应省略或说明缺口。来源冲突时需展示冲突而非静默选择。具体收费、价格、平台支持等信息暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制