芝麻纪元专利申请文件撰写辅助工具
概述
本 skill 把「收集输入 → 建异步任务 → 轮询 → 下载申请文件」串成完整流程，不自撰专利内容，
由芝麻纪元平台在服务端生成。本地仅用 Python 标准库完成文件 multipart 上传、HTTP 请求与轮询。
接口规范详见 references/api.md。核心执行入口为 scripts/run_patent_task.py。
触发条件
用户提供了 技术交底书 等材料并希望产出专利申请文件，或请求如：
“帮我根据这份技术交底书写专利申请文件”“生成专利初稿”“撰写权利要求书”等。
输入收集（与用户交互，缺一不可）
1. 收集上传文档
| 文档 | 是否必选 | 数量上限 | 允许格式 |
|---|---|---|---|
| 技术交底书 | 必选 | 1 | pdf / doc / docx / txt |
| 辅助技术材料 | 非必选 | 1 | pdf / doc / docx / txt |
| 对比文件 | 非必选 | 5 | pdf / doc / docx / txt |
约束：
- 技术交底书必须恰好一个；若用户未提供，先向用户索要，不要臆造。
- 格式不在允许范围内的文件应提示用户改传 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 步：脚本内部流程（供理解与排障，脚本已自动完成）
- 建任务：以
multipart/form-dataPOST.../patent-app，其中filespart 逐个上传文件原始字节
（每个文件一个 part），datapart 为 JSON{"techType": N, "files": [{name,type}...]}，
只含文件 name 与 type，不传文件内容 content。正常响应得到taskId（数字）。
- 若响应 HTTP status 非 200（body 形如{code: xxx, message: "错误信息"}）或success == false，
把 body 的message原样提示给用户并终止（执行失败），不再向下执行。 - 轮询：
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）重新调用一次。
- 响应 HTTP status 非 200 → 提示 body
- 下载文件：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（datapart）中只传每个文件的name与type，不再传文件内容content。 - 输出文件名统一以
申请文件-为前缀 + 交底书原始文件名（去后缀）+ 时间戳，勿用其它文件命名。 x-pws-client-id由脚本自动生成（~/.workbuddy/device-id），无需也不建议用户手动指定。- 轮询节奏为两段式：第一次在创建任务后 1~3 秒，之后每次间隔 10~30 秒（区间内随机），避免过密请求。
