yzy-knowledge-search

name	yzy-knowledge-search
description	结合有赞云 llms.txt 文档导航、云文档中心搜索接口和 wiki 关键词搜索接口查询有赞云开放知识。用于回答开放平台、开发者接入、开放 API、开放消息、扩展点、定制需求、集成方案、工单答疑和能力咨询；其他有赞云开发 Skill 需要官方依据时也应使用本 Skill。

YZY 有赞知识库查询

概述

结合文档目录导航、有赞云文档中心搜索接口和 wiki 关键词搜索接口，查询与用户问题相关的开放文档范围、内部知识库内容和 wiki 原文内容。当答案依赖有赞特定文档、内部实现、业务规则或定制需求背景时，优先查询知识库，不要凭通用经验猜测。

工作流程

1. 先判断问题属于哪一类：语义问题、精确对象问题、混合问题，还是模块定位问题。
2. 语义问题优先走 rag，检索词保留完整自然语言表达；不要压成单个关键词。
3. 精确对象问题优先走 wiki，只提炼 1 到 3 个高识别度客体，并通过 --wiki-keywords 'kw1|kw2|kw3' 显式传给脚本。
4. 混合问题走 hybrid，同时提供自然语言查询和 wiki 关键词；先让 wiki 定位对象，再让 rag 补证据。
5. 目录探索问题才启用 nav 或同时读取 llms.txt。
6. 单点问答默认使用 --top-k 3 --no-navigation 完成一次查询；模块探索类问题才同时使用 llms.txt 导航。
7. wiki 搜索返回完整 content 时，脚本会按 Markdown 标题切片、按关键词打分、提取 matchedSections 和 sourceExcerpt，不要把完整 content 原样作为最终回答。
8. 优先使用脚本返回的 sourceExcerpt 回答具体字段、参数和规则问题。它来自首条结果的 Markdown 原文或 wiki 相关章节，避免因为搜索摘要截断而重复检索。
9. 先观察接口响应结构，再做总结。未知字段只能当作来源元信息，不要假设其业务含义。
10. 先基于检索结果给出结论，不要只贴接口 JSON。
11. 归纳关键依据；llms.txt 模块和文档链接可用于说明来源范围，知识库和 wiki 结果用于支撑结论。
12. 回答接口、扩展点、消息、方案类问题时必须有据可循，优先引用原始链接；缺少链接的 wiki 或知识库结果只能作为弱依据。
13. 只基于返回的知识库内容、wiki 内容和目录导航回答，不编造三者没有返回的事实。
14. 首轮结果为空、报错或明显不相关时，可再执行一次更精确的查询；一次用户问题最多执行两次知识检索。
15. 结果仍然含糊或接口不可用时，明确说明，并建议用户补充信息，不要继续循环调用工具。
16. 如果响应中包含标题、URL、文档 ID、slug 或其他来源标识，回答时一并标注。

模式怎么选

• rag：问的是“是什么、怎么做、为什么、流程是什么、适用场景是什么”这类语义问题，或者需要跨文档综合判断时用。
• wiki：问的是“某个明确对象在哪里、叫什么、参数是什么、字段是什么、错误码是什么、扩展点文档是哪一篇”这类精确定位问题时用。
• hybrid：问题同时包含“明确对象”与“语义解释/接入背景/限制条件/替代方案”时用；先靠 wiki 锁定对象，再用 rag 补上下文。

简单判断规则：

1. 只要问题里有稳定名词，但用户主要是在问定义、用途、流程、场景，优先 rag。
2. 只要问题里有明确 API 名、字段名、错误码、扩展点名、文档名或 slug，优先 wiki。
3. 如果你既要精确对象，又要证据更完整、上下文更稳，选 hybrid。
4. 首轮不要同时乱试多个模式；一次问题只选一个主模式，结果不够再做第二次更精确检索。
5. nav 只用于模块定位，先看看这个领域有哪些目录和候选文档，不用于直接回答具体问题。

示例：

用户问题	推荐模式	入参要点
app开店是什么	rag	query="app开店是什么"，保留完整问题
有赞云 API 服务费规则是什么	rag	query="有赞云API服务费规则"；属于 FAQ/运营类时按标题式表达改写
youzan.item.add 的 sku_list 报错	hybrid	query="youzan.item.add 的 sku_list 报错"，--wiki-keywords 'youzan.item.add'；先用 API 名定位，再用 query 补字段和报错语义
支付扩展点文档是哪一篇	wiki	query="支付扩展点"，--wiki-keywords '支付扩展点'
第三方支付通道扩展点怎么接入，有哪些限制	hybrid	query 保留完整问题，--wiki-keywords '第三方支付通道扩展点'
开放消息相关文档有哪些	nav	query="开放消息"，用于先定位模块和候选文档

入参关键词解析

这一节只适用于 wiki / hybrid，或者用户明确要求精确按对象检索的场景；rag 直接保留完整自然语言问题，不做这类规整。

关键词规整应由调用 skill 的 Agent 负责，脚本只执行最终检索词。

解析规则：

• --wiki-keywords 只放高识别度客体，例如开放 API 名、扩展点名、消息名、文档名、产品能力名、稳定 slug。
• 字段名、泛化动作词、问题状态词通常不进 --wiki-keywords，例如 sku_list、报错、限制、怎么接入；这些信息应保留在 query。
• 优先提取引号、反引号、书名号中的显式检索词。
• 保留接口路径、开放 API 名、类名、方法名、字段名、错误码、英文标识符等稳定 token；其中只有具备独立定位能力的 token 才放入 --wiki-keywords。
• 移除“帮我查一下”“知识库里有没有”“怎么处理”等检索话术。
• 保留有赞业务核心词，例如订单、商品、营销、优惠券、支付、退款、会员、店铺、库存、物流、开放 API、开放消息、扩展点、开发者、定制需求、集成方案等。
• 解析后的检索词过短或为空时，回退使用原始问题。
• 用户要求精确按输入查询时，直接把原始问题作为最终检索词。
• 如需留存原始问题，调用脚本时额外传入 --original-query 记录上下文。

工作流程

1. 将用户意图提炼成简洁的中文查询词。产品名、API 名、标识符、错误信息要保持原样；不要把整段闲聊式用户问题直接作为检索词。
2. 单点问答默认使用 --top-k 3 --no-navigation 完成一次查询；模块探索类问题才同时使用 llms.txt 导航。
3. 优先使用脚本返回的 sourceExcerpt 回答具体字段、参数和规则问题。它来自首条结果的 Markdown 原文，避免因为搜索摘要截断而重复检索。
4. 先观察接口响应结构，再做总结。未知字段只能当作来源元信息，不要假设其业务含义。
5. 先基于检索结果给出结论，不要只贴接口 JSON。
6. 归纳关键依据；llms.txt 模块和文档链接可用于说明来源范围，知识库结果用于支撑结论。
7. 回答接口、扩展点、消息、方案类问题时必须有据可循，优先引用原始链接；缺少链接的知识库结果只能作为弱依据。
8. 只基于返回的知识库内容和目录导航回答，不编造二者没有返回的事实。
9. 首轮结果为空、报错或明显不相关时，可再执行一次更精确的查询；一次用户问题最多执行两次知识检索。
10. 结果仍然含糊或接口不可用时，明确说明，并建议用户补充信息，不要继续循环调用工具。
11. 如果响应中包含标题、URL、文档 ID 或其他来源标识，回答时一并标注。

内容有效性与时效判断

检索结果不是都能直接作为最终推荐方案，必须先做内容有效性筛选，并在同一章内处理输出内容和格式要求。

内容有效性规则

1. 如果结果中出现以下标记，不可作为最终推荐方案：
   • 已弃用
   • 已废弃
   • 已下线
   • 即将下线
   • 不推荐使用
   • 不推荐新接入使用
   • 仅历史兼容
   • 只维护不迭代
   • 不再维护
   • 请改用 xxx
   • 推荐使用 xxx
   • 已迁移至 xxx
   • 新接入开发者请使用 xxx
2. 如果结果明确给出了替代方案，应继续检索替代方案，并优先用替代方案文档回答。
3. 回答中的能力名称、接口名称、参数、示例、限制条件、操作步骤和参考文档，都必须以替代方案文档为准。
4. 历史兼容或背景说明可以简述，但不能作为新接入推荐。

公告时效规则

公告、通知、上线说明、变更通知、临时说明、活动说明、维护通知等内容，必须额外判断时效：

1. 默认只在发布时间起 2 个月内视为可作为当前结论依据。
2. 超过 2 个月且没有明确长期有效说明的公告，只能作为历史背景。
3. 当前问题必须依赖公告判断，但只检索到过期公告时，应继续查正式文档或更新说明。

输出内容要求

1. 回答中返回 sourceUrl 前必须先访问验证；只有 HTTP 状态为 2xx 时，才返回该 sourceUrl。
2. 默认面向人类输出归纳后的结论、操作步骤、关键依据和来源链接，不只返回接口原始 JSON。
3. 内部整理证据时，每条知识库结果必须尽量保留 sourceType、sourceUrl、url、docId 等来源字段；最终回答可按自然语言或列表呈现。
4. 内部追踪时，应汇总知识库原始链接、llms.txt 目录链接、模块链接和 Markdown 文档链接；最终回答优先引用已验证可访问的来源链接。
5. 缺少原始链接的条目只能作为弱依据，不能单独支撑关键结论；如引用此类条目，应明确说明缺少可验证链接。
6. 不要根据字段名猜测知识库未返回的事实；脚本只能抽取标题、摘要、类目路径、URL、文档 ID 等可见信息。

输出格式要求

1. 面向人类展示时，调用脚本使用 --format pretty，最终回答也默认使用自然语言、列表或表格等人类可读格式。
2. 只有用户明确要求 JSON、结构化输出、机器可读结果或需要沉淀为程序输入时，才输出归纳后的 JSON；JSON 中可包含 originalQuery、usedQuery、conclusion、evidence、sources、navigation、traceability 等字段。
3. 用户明确要求原始结果时使用 --full-response，在输出中附带完整接口响应。

脚本

统一使用 scripts/search_knowledge.py。它只做一件事：按工作流程选定的模式，把检索词、wiki 关键词和必要参数转成一次查询，并把结果整理成可直接回答的证据。脚本只接收最终检索词，不在代码里做关键词规整；关键词规整由 Agent 按上述规则完成。脚本默认返回 3 条结果，并自动读取首条结果的 Markdown 原文相关片段。默认输出 JSON，便于 Agent 组合调用；遇到 HTTP 或 JSON 错误时以非 0 状态退出。内部服务响应慢时，使用 --timeout <秒数> 调整超时时间。

原文参数：

• --source-depth <数量>：读取前 N 条结果的 Markdown 原文，默认 1。
• --source-timeout <秒数>：单次原文请求超时，默认 5 秒。
• --source-excerpt-limit <字符数>：每条原文相关片段的最大字符数，默认 2500。
• --no-source-hydration：不读取 Markdown 原文，仅保留搜索摘要。

rag

• 用于语义问题。
• query 保留完整自然语言表达，不压成单关键词。
• 常用参数：--top-k、--timeout、--no-navigation、--original-query、--no-source-hydration、--source-depth、--source-timeout、--source-excerpt-limit。

wiki

• 用于精确对象问题。
• query 保留对象名，额外传 --wiki-keywords 'kw1|kw2|kw3'。
• 常用参数：--top-k、--wiki-limit、--wiki-section-limit、--timeout、--no-navigation、--original-query、--no-source-hydration、--source-depth、--source-timeout、--source-excerpt-limit。

hybrid

• 用于混合问题。
• 同时提供自然语言 query 和 --wiki-keywords。
• 常用参数：--top-k、--wiki-limit、--wiki-section-limit、--timeout、--no-navigation、--navigation-top-n、--navigation-module-depth、--original-query、--no-source-hydration、--source-depth、--source-timeout、--source-excerpt-limit。

nav

• 用于目录探索，只看模块和候选文档。
• 常用参数：--navigation-top-n、--navigation-module-depth、--navigation-url、--navigation-timeout、--no-navigation。

常用参数

• --top-k <数量>：RAG 结果数量，默认 3。
• --wiki-limit <数量>：wiki 结果数量，默认 5。
• --wiki-section-limit <数量>：每条 wiki 结果保留的相关章节数量，默认 4。
• --timeout <秒数>：请求超时时间。
• --no-navigation：不读取 llms.txt 导航。
• --navigation-top-n <数量>：导航候选数量，默认 5。
• --navigation-module-depth <数量>：读取前几个模块的二级目录，默认 3。
• --original-query：保留用户原始问题。
• --no-source-hydration：不读取 Markdown 原文。
• --source-depth <数量>：读取前 N 条结果原文，默认 1。
• --source-timeout <秒数>：原文请求超时时间，默认 5 秒。
• --source-excerpt-limit <字符数>：原文片段最大长度，默认 2500。

输出与筛选

• 脚本默认输出 JSON，也支持 --format pretty。
• wiki 和 hybrid 模式会整理 matchedKeywords、matchedSections、sourceExcerpt 和 riskFlags。