ultradoc

ultradoc

根据检索到的源代码证据作答，并提供带引用的答案或参考手册。随附的 scripts/ultradoc.mjs 是一个零依赖的 Node 引擎。脚本路径应相对于此技能目录解析，而不是相对于目标检出目录。

选择足以解决问题的最小路径

请求	路径
单个本地事实或命名声明	下方的快速回答
行为、歧义、解释、Issue/PR 证据	下方的标准回答
整个项目/软件包的参考文档	workflow.md 中的 doc 工作流
声明主体/调用者	symbol --repo <path> --name <symbol>；仅靠词法搜索无法确认调用关系
跨文件实现 → 调用者 → 测试	trace；先阅读 trace.md
版本/变更历史	检索 releases,history，如有指定则固定 --ref

使用 node <skill-dir>/scripts/ultradoc.mjs --help 查看标志。本地请求仅使用 --sources code,docs；不要为此探测远程提供方。对于小问题，不要加载完整工作流、概览、可选的语义设置或编排，除非证据暴露出缺口。

快速回答

对于最多由三条字面代码/文档声明即可确定的单个事实：

1. 运行 ask --repo <path> --q "<identifier and question>" --sources code,docs --out <run-dir>。阅读其检索说明，然后阅读 EVIDENCE.md 中相关摘录。对于单个命名声明，也可以先运行 symbol，再保存回答/检查工作流所需的证据。
2. 阅读 citation-format.md，在运行目录中编写 ANSWER.md：先给出答案，每句话只陈述一项主张，并各自引用 [E#]。将 meta.json 中固定的提交哈希放入 HTML 注释。将未解决的问题放在 ## Unknowns 下；切勿凭记忆补全。描述效果前，检查回调默认值和注入的依赖项：区分计算/请求的值与实际执行的效果。空操作实现是无效果的证据，不是未知情况，也不代表真实的计时器/写入/网络调用。
3. 运行 check --run <run-dir> --strict。修复引用/覆盖率问题并重新运行。如果覆盖率摘要统计出的主张超过三条，请使用下方的标准语义验证；严格检查通过也不能免除该要求。呈现答案、可点击的源代码引用、提交哈希和未知项。

当摘录已确定问题答案且通过检查关卡时，即可停止。对于只读说明，不要运行无关的项目测试。只有发现明确的证据缺口时才进行额外检索，而不是为了满足命令数量要求。

任何解释、有争议的行为或 Issue/PR 主张都需要进行下方的语义验证。引用可解析本身并不能证明主张成立。

标准回答与语义验证

1. 确认项目、具体问题和所需版本。只有当目标不明确导致无法检索时才提问。将多部分问题拆分为明确的子问题。选择来源／查询变体时，请阅读 retrieval-playbook.md；使用 ask 保存固定的资料档案。
2. 阅读检索说明后再查看代码片段：截断、速率限制、正则表达式层级分析和缺失的提供方都会限制答案。使用 reading-evidence.md 和 engine-evidence.md 解读含义不清的说明。
3. 仅深入检索尚未解决的子问题。标准情况：进行一轮深入检索，每个子问题针对两个相关条目。深入／有争议的情况：最多进行三轮；若某一轮没有带来新的相关证据，则停止。明确说明仍存在的缺口。
4. 按照快速路径使用相同的答案规范撰写回答。始终运行 check --strict。
5. 运行 verify --run <run-dir>，以审慎的态度将每组论断↔证据判定为 supported、partial、refuted 或 unsupported，并附上具体说明。将有关 issue／PR 的断言与当前代码交叉核对。将所有判定汇总到一个文件中，然后运行 verify --apply <verdicts.json> --run <run-dir> 和 check --semantic --run <run-dir>。缺少验证时一律判定为不通过。修正、弱化、删除或重新检索不受支持的论断，然后重新验证；绝不绕过关卡以获得通过。
6. 阅读 answer-rubric.md，然后使用用户的语言提供答案，并附上来源链接、提交版本和覆盖范围缺口。

证据规则

• 仅依据检索到的证据作答。熟悉某个 API 或关键词匹配都不足为证；代码片段必须能支持实际论述。
• 绝不能将空结果、结果数达到上限或检索失败视为不存在的证明。将结论限定在已搜索的范围内，并披露缺失的来源。
• check --strict 适用于所有答案和所有生成的 DOC.md。除上述严格限定的快速路径外，都必须进行语义验证。
• 遇到可恢复的错误时继续处理。改写偏离主题的查询；使用 --package 限定被截断的单体仓库检索范围；离线时使用可用的本地来源并说明缺口。不要声称失败的提供方提供了证据。
• 检索和验证可以按顺序运行。可选的并行分发不会改变证据或退出关卡。

仅在需要时查看详细信息

• workflow.md：完整工作流、文档、恢复表、来源路由和可选语义模式。
• tuning.md：上限、缓存、成本和嘈杂的检索结果。
• orchestration.md：独立任务清单、子 Agent 规范和顺序节能模式；由一名撰写者汇总结果。
• provider-apis.md：issue／PR 提供方问题。
• web-discovery.md：网页提取与发现。
• semantic-setup.md：可选的本地向量层级。
• worked-example.md：完整的示例答案。