专利申请文件撰写助手-芝麻纪元

概述

芝麻纪元专利申请文件撰写辅助工具

概述

本 skill 把「收集输入 → 建异步任务 → 轮询 → 下载申请文件」串成完整流程，不自撰专利内容，由芝麻纪元平台在服务端生成。本地仅用 Python 标准库完成文件 multipart 上传、HTTP 请求与轮询。

接口规范详见 references/api.md。核心执行入口为 scripts/run_patent_task.py。

触发条件

用户提供了 技术交底书 等材料并希望产出专利申请文件，或请求如：“帮我根据这份技术交底书写专利申请文件”“生成专利初稿”“撰写权利要求书”等。

输入收集（与用户交互，缺一不可）

1. 收集上传文档

约束：

• 技术交底书必须恰好一个；若用户未提供，先向用户索要，不要臆造。
• 格式不在允许范围内的文件应提示用户改传 pdf/doc/docx/txt。

2. 选择技术类型（四选一，必选）

• 1 = 软硬结合
• 2 = 软件通信
• 3 = 机械结构
• 4 = 材料化学

若用户未明确说明，用 AskUserQuestion 让其选择其一，不要默认猜测。

执行步骤

按顺序执行以下步骤。

第 1 步：确认识证信息

「创建异步任务」为 multipart/form-data 上传，请求头固定携带（content-type 由 multipart 边界指定，无需手动设成 application/json）：

x-pws-token:      <token>      # 接口密钥，脚本内部读取，不对外明文展示
x-pws-client-id:  <自动生成>     # 无需用户指定

x-pws-client-id 自动生成，不需要用户提供：优先取环境变量 X_PWS_CLIENT_ID，否则自动读取~/.workbuddy/device-id（WorkBuddy 安装级稳定设备标识，同一安装下跨会话、跨任务一致）。此逻辑由脚本内置，调用方无需传参。

x-pws-token 为接口密钥：脚本内部按「环境变量 X_PWS_TOKEN → 内置默认值」解析，该值属凭据，任何情况下不得在回复、日志或提示文案中明文展示。若会话环境提供真实 token，应通过环境变量 X_PWS_TOKEN 或脚本 --token 传入以覆盖默认值。

第 2 步：把文件转成参数并执行脚本

把收集到的每个文件路径映射为命令行参数，交给 scripts/run_patent_task.py 统一执行（该脚本负责文件 multipart 上传、建任务、轮询与保存，避免反复手工重写 HTTP 逻辑）：

# 工作目录：本 skill 目录
PY="$(pwd)/scripts/run_patent_task.py"
/usr/local/bin/python3 "$PY" 
  [--tech-type 1] 
  [--disclosure "/绝对路径/技术交底书.pdf"] 
  [--task-id 123] 
  [--aux "/绝对路径/辅助技术材料.docx"] 
  [--comparison "/绝对路径/对比文件1.pdf" --comparison "/绝对路径/对比文件2.doc"] 
  [--token "<真实token，可选>"] 
  [--output-dir "/绝对路径/输出目录"]

说明：

• 可用 /usr/local/bin/python3 或环境已配置的受管 python（需含标准库即可，无第三方依赖）。
• SSL 已内置修复：脚本会为 https 请求加载系统 CA 证书链（/private/etc/ssl/cert.pem），

规避部分 Python 发行版（如 python.org macOS 框架版）默认 CA 文件缺失导致的[SSL: CERTIFICATE_VERIFY_FAILED]。因此用 system python 或受管 python 均可正常请求，无需手工装证书；若仍偶发 SSL 报错，优先切换受管 python 复跑一次。

• --comparison 可重复传，最多 5 个。
• --output-dir 不传则申请文件落在脚本运行目录。
• 无需传 --client-id：脚本会从 ~/.workbuddy/device-id 自动生成（详见第 1 步）。

脚本返回 success 输出：

[成功] 申请文件已下载：/绝对路径/申请文件-技术交底书主文件名20260903155120.docx

第 3 步：脚本内部流程（供理解与排障，脚本已自动完成）

1. 建任务：以 multipart/form-data POST .../patent-app，其中 files part 逐个上传文件原始字节

（每个文件一个 part），data part 为 JSON {"techType": N, "files": [{name,type}...]}，只含文件 name 与 type，不传文件内容 content。正常响应得到 taskId（数字）。

• 若响应 HTTP status 非 200（body 形如 {code: xxx, message: "错误信息"}）或 success == false，

把 body 的 message 原样提示给用户并终止（执行失败），不再向下执行。

1. 轮询：GET .../patent-app/{taskId}?offset={offset}，两段式节奏：
   • 第一次轮询在创建任务后 1~3 秒发起；
   • 之后每次轮询间隔 10~30 秒（区间内随机，避免过密/同步请求）。
   • offset 为增量游标：首次轮询默认 0，服务端响应会带回新的 offset，下次轮询把上次服务端返回的

offset 原样回传，直到任务结束。

• 每次把进度 message（content）展示给用户。**当返回的 message 为空时，继续展示「上一次返回的非空

message」，让页面始终有进度呈现、看起来仍活跃（绝不因空文案让页面卡住/像挂了）；仅当从头到尾都没有过非空 message 时才展示 **「正在处理，请稍候…」。空 message 的每次轮询都要刷新一行（时间戳更新）以表明轮询仍在进行，不展示空行。非空 message 连续相同文案只展示一次以免刷屏。

• status 为数字状态码：1=未开始、2=执行中、3=已完成、4=异常。满足以下任一条即停止：
  • 响应 HTTP status 非 200 → 提示 body message，执行失败；
  • success == false → 提示 message，执行失败；
  • status == 4（异常）→ 提示 message，执行失败；
  • status == 3（已完成）→ 取其 url（申请文件下载链接）进入下一步。
• 【铁律·严禁自动重提任务】：上述轮询阶段无论发生何种失败（HTTP 非 200 / 网络或 SSL 错误 /

status == 4 / 超时），一律视为失败终止，绝不自动重新提交 create_task——创建任务非常消耗资源。脚本退出（退出码 3）后，如需重试必须征得用户明确同意，才可整脚本（含重新上传并 create_task）重新调用一次。

1. 下载文件：GET 请求 url，把返回的申请文件落盘。文件名 = 申请文件-{技术交底书主文件名去掉后缀}{yyyyMMddHHmmss}{url 推断扩展名，默认 .docx}。

第 4 步：交付

脚本输出的成功路径即最终申请文件路径。用文件预览能力打开该文件并提示用户查看。

错误处理

红线：轮询阶段严禁自动重提 create_task。 任何轮询/任务异常（HTTP 非 200、网络或 SSL 错误、

success:false、status==4、超时）都只应提示用户并终止；不要在未获用户明确同意时重新提交任务。

create_task 会重新上传全部文件、极其消耗资源。只有用户明确要求"重试"时才重新执行脚本。

• 上传文件缺失、数量超限、格式不符 → 在收集中拦截并提示用户修正。
• 建任务/轮询请求返回 HTTP status 非 200（body 形如 {code, message}）→ 把 body 的 message 提示给用户，流程终止。
• 建任务/轮询返回 success:false 或 status:4（异常）→ 把服务端 message 提示给用户，流程终止。
• 轮询返回的 message 为空 → 继续展示最近一次非空 message（见第 3 步），避免页面卡死。
• 脚本退出码：0 成功；1 一般错误；2 建任务失败；3 任务失败或轮询异常/超时。**退出码为 3 时，

无论后台报什么错，都不自动重试；重试前必须请用户确认。**

注意事项

• 不自撰专利内容：只做文件/参数收集与接口编排，最终文件完全来自平台响应 url。
• 文件以 multipart/form-data 原始字节上传（@RequestPart("files")），不转 Base64；

taskParam（data part）中只传每个文件的 name 与 type，不再传文件内容 content。

• 输出文件名统一以 申请文件- 为前缀 + 交底书原始文件名（去后缀）+ 时间戳，勿用其它文件命名。
• x-pws-client-id 由脚本自动生成（~/.workbuddy/device-id），无需也不建议用户手动指定。
• 轮询节奏为两段式：第一次在创建任务后 1~3 秒，之后每次间隔 10~30 秒（区间内随机），避免过密请求。