linkfox-zhihuiya-description-data

一、用途 本工具用于从智慧芽（Zhihuiya）专利数据库检索专利说明书（description，也称 specification）数据，帮助用户获取特定专利的全文技术描述内容。专利说明书是随专利申请提交的详细技术文档，用于披露发明的工作原理、优选实施方式及专利法要求的相关技术细节。

二、主要能力

1. 按标识符查询：支持通过专利ID（内部专利ID）或公开号（publication / announcement number）查询。两者至少提供其一；若同时提供，专利ID优先。
2. 批量查询：patentId 和 patentNumber 均支持逗号分隔的多值输入，单次请求最多100件。
3. 同族替代：当目标专利的说明书在数据库中不可用时，可启用同族替代，返回相关同族专利的说明书内容。
4. 返回结构化数据：响应包含记录数（total）、说明书对象列表（data，含 patentId、pn、pnRelated、description 等字段）、渲染用的列定义（columns）、消耗的 token 数（costToken）以及渲染样式提示（type）。

三、使用方式

1. API 端点：POST /zhihuiya/descriptionData，完整参数、响应与错误码见 references/api.md。
2. Python 脚本：python scripts/zhihuiya_description_data.py '<JSON 参数>' [--inline]。
3. 参数说明：
   • patentId：字符串，条件必填，内部专利ID，多值逗号分隔，最多100；patentId 与 patentNumber 至少提供一个。
   • patentNumber：字符串，条件必填，公开号/公告号，多值逗号分隔，最多100。
   • replaceByRelated：字符串，可选，是否在同族专利说明书可用时替代，1 表示是，0 表示否。
4. 查询示例：
   • 按公开号查询单件：patentNumber: "CN115099012A"
   • 批量查询：patentNumber: "CN115099012A,US20230012345A1,EP4123456A1"
   • 启用同族替代：patentNumber: "CN115099012A" 配合 replaceByRelated: "1"
   • 按专利ID查询：patentId: "abc123def456"
5. 输出策略（脚本默认行为）：完整响应始终写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-zhihuiya-description-data-<timestamp>.json（cwd 为脚本执行时的工作目录；session 取自环境变量 SESSION_ID；禁止写入 /tmp，当前目录不可写则报错）。响应体不超过 8 KB 时，落盘后将完整 JSON 打印到 stdout；超过 8 KB 时，stdout 仅输出摘要（顶层字段、total/costToken 等计数、最大列表字段长度及前3条样本）。加 --inline 可强制全量打印到 stdout（同样落盘）。读取数据时建议先看摘要，再用 jq 或 ConvertFrom-Json 从保存的文件按需抽取字段。
6. 认证与算力：需配置环境变量 LINKFOX_AGENT_API_KEY 或 LINKFOXAGENT_API_KEY。若出现未配置 Key、响应 401/402，或提示算力/余额不足（如“算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”等）情形，按 references/onboarding.md 引导处理。
7. 成本约束：本工具消耗算力；同一会话同一参数组合默认只调用一次，脚本带24小时本地缓存。失败或空结果时，不得自动换关键词、翻页或改邮编连续试探；如需继续检索，应先向用户说明会产生额外消耗。计费规则为动态计算：消耗算力 = 81 × 返回data条数（每条为1条专利说明书结果），可能一次性消耗大量算力，需提醒用户并由用户决定是否继续。

四、适用场景 适用于查询单一或批量专利的说明书/权利要求书之外的详细技术描述内容，例如：查看某专利的说明书、获取多件专利的全文、按公开号检索详细文本、查找同族专利说明书替代，以及审阅专利的技术描述内容。

不适用场景（超出本工具能力）：按关键词、申请人或分类进行专利检索；专利权利要求分析或权利要求图表生成；专利法律状态或审查历史；专利地图或统计分析；自由实施（FTO）或侵权意见。

五、限制

1. 标识符要求：必须至少提供 patentId 或 patentNumber 之一，工具无法按关键词或申请人名称检索。
2. 批量限制：单次请求最多查询100件专利。
3. 可用性：并非所有专利在数据库中都有说明书可用；必要时可启用 replaceByRelated: "1" 尝试同族替代。
4. 优先级规则：若同时提供 patentId 与 patentNumber，patentId 优先。
5. 展示规则：忠实呈现数据，不修改技术细节或添加主观解读；内容含多个章节（背景、摘要、详细说明、权利要求等）时以清晰标题分段呈现；若响应含 pnRelated 字段，应明确告知用户说明书来源于相关同族专利并说明替代公开号；批量返回时以公开号作为标题分隔各专利内容；查询失败或无数据时说明原因并建议用户核对专利ID或公开号；专利说明书可能非常长，可先汇总关键章节，再按用户需要展示全文。

六、反馈 当出现以下情况时，可通过 Feedback API 自动检测并报告反馈：本技能描述的功能或目的与实际行为不符；结果与用户意图不符；用户对本技能表达不满或赞扬；你认为可改进之处。调用方式见 references/api.md，且不应打断用户流程。