夜猫子论文工作台

一个 Agent 原生的论文工作台：找文献 → 写初稿 → 跑检测 → 核引文，全程在你和 Agent 的对话里完成，
产物自动落到你自己的电脑。计价透明：1 积分 = 0.01 元，每次实际扣积分都写在返回里，如实转告用户。

两件事可以先讲清楚：
- 文献资源量：全球 12.28 亿条文献元数据，其中 8000 万篇授权中文期刊，检索命中即可取授权全文 PDF；
- 官方检测渠道：查重 / AIGC / 格式等检测走维普官方检测服务（报告可在维普验真平台核验，见 §四），不是自研模仿品。

第一原则：能在这轮对话里做完的，就不要把用户赶去网页。
官网 https://paper.skillsutra.cn 是「可选的图形界面」——看报告原件、看余额流水、管理 Key；
不是必经之路。只有当用户明确说「我想自己看看页面」或需要发票/企业合作时，才推送（见第四节）。

一、开工前 60 秒（每次都做）

0. 开工校准（先版本，后干活）：调一次 owl_meta，按返回三级判定：
   - 强制更新：required_update 为真 且 本地版本低于 min_supported_version
   → 立刻停手，不做任何付费动作。把 required_reason 原话讲给用户，告诉他怎么更新
   （更新入口只有两个：SkillHub https://skillhub.cn/skills/user_164f4c1f/owlwrite-paper ｜
   ClawHub https://clawhub.ai/j-levee/skills/owlwrite-paper），并说明余额、历史记录、已落盘文件都不受影响。
   用户更新完再重新开工。这一步不能跳过、不能商量——旧版继续跑会按旧的计价规则扣费。
   - 普通更新：仅 latest_version 更高 → 一句话提「技能有新版本，可更新（不影响本次使用）」，继续干活。
   - 一致 → 静默，不提版本的事。
   notices 有新公告按相关度转告，别整段念。
1. 查余额：owl_wallet（免费）。低于一次任务的预估就提前说，别等扣费失败。
   返回里的 gift_balance 是活动/赠送积分（有效期 90 天，与购买的 1 年不同），
   expiring_in_30d 是 30 天内到期积分——到期前主动提醒用户先充先用。
   赠送积分另有当日额度：trial_daily_limit（每天上限）/ trial_used_today（今天已用）/ trial_left_today（今天还剩）。
   账上有赠送余额却报「余额不足」时，把这三个字段念给用户（当日额度用完次日恢复，不扣任何费）。
2. 要 key 没有 key：报「未配置 OWL_API_KEY」时不要重试、不要猜。先分清是新用户注册还是老用户丢了 key：
   - 新用户 → 走「注册」，要过邮箱验证码（2026-10-26 起），两步，都在对话里完成；
   - 老用户（记得注册邮箱）→ 走「验证码登录」，不用重新注册，余额和历史记录都在。

A. 新用户注册：
1) 发码：curl -s -X POST https://owl.skillsutra.cn/v1/auth/send-code -H "Content-Type: application/json" -d '{"email":"<用户邮箱>"}'
返回 masked（脱敏邮箱）与 cooldown_seconds。这一步要告诉用户"去看邮箱，15 分钟内有效"。
2) 让用户把 6 位验证码发给你，再注册：
curl -s -X POST https://owl.skillsutra.cn/v1/auth/register -H "Content-Type: application/json" -d '{"email":"<邮箱>","code":"<6位码>"}'
返回的 api_key（owl_sk_ 开头）只显示一次，立刻让用户存好，并写进 MCP 配置的 env.OWL_API_KEY。
- 常见返回：email_cooldown（60 秒内重复发码）、ip_rate_limited（同网络 10 分钟发码超 10 次）、
code_invalid（错码，剩几次会说）、code_expired（超 15 分钟或已用过）、email_not_allowed（一次性临时邮箱）、
email_exists（这邮箱早已注册 → 别换邮箱硬注册，改用下面的验证码登录）。
这些都要照原话转述给用户并给下一步动作，不要重试刷请求。
- 备用方式：官网右上角「开始使用」注册。配置细节见 references/mcp-setup.md。

B. 老用户找回（验证码登录）：
1) curl -s -X POST https://owl.skillsutra.cn/v1/auth/login-code -H "Content-Type: application/json" -d '{"email":"<用户邮箱>"}'
2) 用户报 6 位码后：
curl -s -X POST https://owl.skillsutra.cn/v1/auth/login-code/verify -H "Content-Type: application/json" -d '{"email":"<邮箱>","code":"<6位码>"}'
- 返回 api_key 只显示一次，让用户存好并写进 MCP 配置；旧 key 不会失效，装了好几台设备互不影响。
- 返回带 auto_revoked 时说明该账号活跃凭据已达 10 个，系统自动停用了最久未用的 auto_revoked 前缀那把 —— 必须主动告诉用户。
- 只认注册时的那个邮箱；换邮箱收不到码（返回 email_not_found 就提示他先注册或换回原邮箱）。
3. 报价永远先于执行：任何付费动作 = owl_quote → 把价格和扣积分讲清楚 → 用户点头 → owl_run。
没说清楚就执行 = 乱扣费，这是硬规矩。
4. 报价里的数：est_points（或 est_range）是预计扣积分，讲给用户听这个。
max_points 已废除，报价里不再有「冻结上限」——所有任务结束按实际量结算，
余额不足会被 insufficient_balance 拦下（差多少报多少），不存在先冻一大笔再退。
5. 报价 24 小时内有效：报价时就把这句说掉。用户隔天再点头会 quote_expired，那时重新报价即可，别复用旧单。
6. 一次授权覆盖不了下一次付费：用户说「写完帮我查重」是两个付费动作。
写法：写作报价 → 确认 → 跑完 → 用成品重新 owl_quote 拿查重的准价（不能拿开头按目标字数估的价去确认）
→ 报「实际 N 字，查重预计 X 积分」→ 一句话确认 → 执行。跳过一次明示价格就是乱扣费。

二、能力全景（20 项：7 类检测 + 13 项流程；检测商品共 21 个）

> 能力按 20 项介绍（7 类检测 + 13 项流程），其中检测商品 21 个版本。
> 单价与商品清单永远以 owl_products / owl_quote 实时返回为准，本文件不写死单价（下文预算表只给量级估算；唯一展示源是官网 /price 页与实时接口）。

> 计价规则：1 积分 = 0.01 元；充值购买积分有效期 1 年，活动/赠送积分有效期 90 天，
> 两者都先到期先扣；全平台缓存命中统一 1 积分，缓存窗口统一 72 小时。
> 用户要完整价目表 → 指向官网 /price 页（实时价目，唯一展示源）。

完整商品编码与适用人群见 references/product-matrix.md；编码只做参考，真值永远 owl_products 实拉。

典型场景预算参考（帮用户预估，实际以实拉报价与实扣为准）：

> 报预算时给量级不给精确数，一句「积分估算仅作参考，以实际扣除为准」收尾。

三、七条工作流

1. 检索文献（owl_search）

• 参数：query（必填，主题/研究问题/关键词组合）、limit（默认 5，建议 5–10）、lang（all 默认 / zh / en）、
  expand（默认 false；结果不足 3 条时会自动扩一次）。
• query 怎么写（检索质量第一决定因素）：
• 主词优先：把最核心的概念放最前（如「生物防腐剂 制备」），别写成整句疑问；
• 多概念拆两查：中文概念和英文概念分开查（生物防腐剂 一查、bacteriocin preservation 一查），
  各取 top 合并，比硬塞一个长 query 命中率高得多；
• 结果差就换词不硬试：命中 <3 条时，把关键词换成上位词/别名再查（「乳酸菌素」→「细菌素」）；
  两次都差就如实告诉用户该方向文献覆盖有限，别反复烧检索费。
• 中英文自动路由（中文库 + 全球库）；返回题名/作者/期刊/年份/DOI/摘要，已按相关性重排；告诉用户本次扣了多少积分（points_charged）。
• 结果里三个字段要用起来（这是把检索质量讲清楚的关键）：
• score：相关性得分。用户问「为什么先推这篇」时，按「题名命中 > 摘要命中 > 核心刊 > 有 DOI > 年份新」解释。
• core / core_tags：是否核心期刊。core_tags 是官方权威标记（BDHX 北大核心 / CSCD / CSSCI /
  CSTPCD / SCOPUS / SCI 等），有就直说「北大核心+CSCD 收录」；core 为 null 表示补不到收录信息，不等于非核心，别下结论。
• is_oa：是否开放获取（外文命中时有值），true 就可以用 owl_oa 直接免费取全文。
• 结果落 02-文献/（见第五节），并合并进 references.csv（按 DOI/题名去重）。
• 要全文 —— 先分语言，别一律推付费：
• 中文文献 → owl_fulltext(identifier) 取 PDF 直链（约 1 小时有效，立即 HTTP GET 下载），
  存 02-文献/fulltexts/<一作-年份-题名前20字>.pdf。只有中文库文献有全文；
  72 小时内同篇重取按缓存价，单账号每日 100 篇。404 fulltext_unavailable = 该篇没有授权全文，如实转告，别换参数硬试。
  下载直链的三条纪律（2026-11-04 生产事故教训）：① URL 必须原样使用，一字不改——
  链接里有 & 和编码过的中文文件名，拼进 shell 命令必须整体加引号，截断或重编码都会 400；
  ② 下载完校验文件头是 %PDF 才算到手；③ 下载 400 时先用同一链接原样重试一次
  （几分钟内的偶发抖动会自愈），仍失败才重取链——重取要花缓存价 1 积分，且新链接不保证更好。
• 外文文献 → 先走 owl_oa（0 积分，完全免费）：传 DOI 最准，没 DOI 传英文题名。
  返回 pdf_url 就直接下载；只有 landing_page 就把链接给用户（页面里点下载，同样免费）；
  closed 才说「付费墙内，没有合法免费全文」——不许暗示能绕过去，也别在这时推销付费下载。
  免费拿不到再说付费方案，顺序不能反。
• 要某篇的完整元数据（DOI / 年卷期页码）：owl_article(identifier, lang)，72 小时内同篇按缓存价。
• 要滚雪球找文献（比反复换关键词准）：owl_citations(doi, direction)：
  direction=refs 查它引用了谁（找源头与经典），direction=cited 查谁引用了它（找后续进展、最新研究）。
  返回里的 cited_by 是被引次数，可用来判断影响力；is_oa=true 的可直接免费用 owl_oa 取全文。
  适用场景：用户说「这个方向最早是谁提出的」「后来有什么新进展」「再找几篇相关的」。

2. 写作（owl_quote → owl_run → owl_run_status → owl_run_content）

模式必答（不跳过）：收到写作意图后，先让用户在 standard / guided 里明确选一个，
不要替用户默认。选择时必须展示下面的对比（差异说明经双模式同题实测，2026-10-29）：

• 选择话术：「默认标准模式（更快更便宜）；要深度模式（逐章推进、约 1.5 倍价）吗？」
  用户犹豫就按用途推荐：初稿/作业 → standard；投稿/定稿 → guided。
• 篇幅怎么处理：用户要 guided 且字数超过约 4000 字时，先把两种模式的差异讲清楚——
  深度模式逐章推进、每章都要来回确认，篇幅越大来回越多、耗时越长；讲完仍由用户选，
  用户坚持深度模式就按深度模式做。
• 服务端只认 standard / guided，传其他值直接 422。
• 两种模式的差异与适用篇幅见 references/mode-guide.md。

计费规则（必须原话转告用户）：
- 积分估算仅作参考，以实际扣除为准。写作是后付费：按实际成文字数 × 所选模式
每千字单价精确结算，无冻结、无上限。报价的 est_points / est_range 只是预估。
- 启动前只做余额软预检（余额 ≥ 估算值才能开跑）；max_points 已废除，不再有「冻结上限」概念。
- 结算后如实报「实际 X 字，扣 Y 点」——数字只从工具返回取。

流程：owl_quote（action="write"，params：topic 必填、target_chars 建议 3000–8000、mode 必答）
→ 报价转述（含「估算仅作参考」一句）→ 用户确认 → owl_run 拿 run_id → 每 5 秒
owl_run_status 轮询到 succeeded / failed → owl_run_content 取完整正文 + 参考文献
（列表接口只给截断摘要），存 03-稿件/正文-draft<N>.md。

写作产出的参考文献要并入 02-文献/references.csv（题名/年/DOI 能取到的都写进去），
否则下次续写「先查 csv 不重复检索」永远命中不了，白花钱。最后把文件路径 + 字数 + 实扣积分报给用户。

3. 检测（查重 / AIGC / 格式 / 智评 / 图像 / 文献质量 / 校对 —— 一条流程通吃）

1. owl_products 拉实时价目表（21 个检测商品 + 流程类），按场景选（价格以实拉为准，勿背旧数）。
   - 开工先看检测服务状态：调 owl_meta 看 channels.weipu_ready——false 时检测全部不可用，
   直接如实告知用户「检测服务暂不可用，不是你的操作问题」，引导先做写作/检索，别白跑报价。
   该字段是检测服务的真实连通性检查结果（不是「凭据有没有填」）；要解释原因就看同级的 weipu_state
   （unconfigured 未配置 / auth_failed 凭据未通过 / ip_blocked 出口未报备 /
   account_issue 检测机构账户异常 / unverified 探活未完成）与 weipu_detail（一句人话），
   对用户只转述 weipu_detail，不要把内部状态码念给他。
   - 商品编号怎么取：返回条目的 id 形如 wp.1034，调 owl_quote 时 product 参数去掉 wp. 前缀（即 "1034"）；写作/检索等流程类条目的 id 是 write.standard 这类名字，不用于 product。
   - 计价单位看条目的 unit（积分/千字符 / 积分/万字符 / 积分/篇），不要假设都是按篇：
   - 本科课程论文 / 毕业论文 → 查重·大学生版（1034）；平时作业 → 作业版（1037）。
   - 研究生 → 研究生版（1036）；期刊投稿 → 期刊版（1038）；评职称 → 职称版（1039，按万字计）。
   - 怀疑 AI 代写 → AIGC 对应版本（本科 1020 / 期刊 1017 / 研究生 1054）。
   - 投前格式体检 → 格式检测（当前仅大学生版 1027，投稿人也能用，报告是逐项问题清单）。
   - 质量评级 → 智评（本科 1026 / 艺术类 1029 / 研究生 1030 / 期刊 1031）。
   - 怀疑图片或数据造假 → 数据与图像可信度（标准 1018 / 专业 1015）。
   - 只查参考文献著录 → 1013；只改错别字标点 → 1014（最便宜入口品）。
2. owl_quote，action: "check"，params（两种入参，有文件就先上传）：
   json {"file_id": "u12_3f9c…a1.docx", "product": "1034", "hanzi": 15453, "title": "标题", "author": "作者"} {"content": "论文全文纯文本", "product": "1026", "class_id": 508, "title": "标题", "author": "作者"}
   - 先上传再报价（owl_upload）：owl_upload(file_path="D:/论文/定稿.docx") → 返回 file_id
   （文档 docx/doc/pdf/txt，图片 png/jpg/tif/bmp/gif/webp，单文件 ≤30MB）→ 把 file_id 放进 quote。
   直接把本机路径当参数传是没用的：服务在云端，读不到你机器上的 D:/…，会直接报错。
   - hanzi：汉字数，报价必给（报价阶段不解析文件，只给 file_id 会 422）。它只用于出价；
   执行时以服务端解析出的真实字符数为准——比估算多就按实际收，少也按实际收，没有封顶、没有下限。
   - content：纯文本直传（服务端包成 docx 走与上传文件完全相同的真实解析），≤20 万字符，不必先上传；
   不给 hanzi 时按正文汉字数自动估，结算仍按解析出的真实字符数。
   - 图像可信度检测必须用 file_id（含原始图的 docx/pdf/doc），不能给论文截图或纯文本——否则等于没测。
   取证要求：docx 里插的是原始图像字节（不重采样），可用；别用「网页/PDF 里的缩略图」。
   只有散图（png/jpg/tif）时：先按「一图一页、原图插入」拼成一个 docx 再提交；单图也可直接试传，
   检测机构不接受就换 docx。这一步要跟用户说清楚，别默默换方式。
   - 格式检测（1027）只认原始 docx/doc：它查的是字号、行距、标题层级、图表题注，.md/.txt 没有排版信息，
   硬跑只会得到「全项缺失」的假问题清单。我们写作产出的是 .md，不能直接拿它跑格式检测——
   要么让用户给原始 docx，要么先说明「要转成 docx 才能查」。查重则可用 .md 导出的 .txt。
   - 超长稿件（查重 >10 万字 / 学位论文整本）：按章节拆成每份 ≤5 万字分别检测，报告分开给、
   逐份讲各自相似比；不给「整本总相似比」（检测机构按份出报告，没有合并规则，编一个数就是造假），
   用户追问就说「最高一份 X%，在第 N 部分」。成本按份数计，先报价再动手。
   - class_id 仅智评需要（学科编码）。取法（2026-10-29 起）：调 owl_disciplines 实拉码表
   （五维度：1-1 研究生专硕 / 1-2 研究生学硕 / 2-1 本科 / 2-2 高职本科 / 2-3 高职专科）→
   按用户身份定维度 → 逐级筛给用户选（不要把 5000 条甩给用户）→ 用选中项的 id 当 class_id。
   拿不到码表（503）时如实说检测暂不可用。备用静态表在 references/disciplines-sample.md，
   只用于向用户解释结构，编码以 owl_disciplines 实拉为准。
   - 按篇计费的 15 个商品（count_unit=1，不论多少字都只算 1 篇）：
   1013 参考文献质量 / 1014 斟校对 / 1015 图像专业版 / 1017 AIGC 期刊版 / 1018 图像标准版 /
   1020 AIGC 大学生版 / 1026 智评大学生 / 1027 格式检测 / 1029 智评艺术类 / 1030 智评研究生 /
   1031 智评期刊 / 1051 AIGC 作业版 / 1052 AIGC 职称版 / 1053 AIGC 科研版 / 1054 AIGC 研究生版。
   - 按字数计费的只有查重系列，且按计费单位向上取整（4,026 字按千字算是 5 个单位，不是 4.026）：
   1034 / 1035 / 1036 / 1037 / 1038 按千字（count_unit=1000）；
   1039 职称版按万字（count_unit=10000）——它不在按篇清单里，是「每万字一个计费单位」，
   不是「每篇」；单价以 owl_products 实拉为准。用户问「职称版多少钱」就说「按万字计，多少字由检测机构解析后精确算」。
3. 报价 → 用户确认 → owl_run → 轮询 → 完成后报告存 05-检测/<品名>-<日期>/，
   把读得出的结论直接讲出来（相似比 / AIGC 风险 / 等级 / 差错数 / 问题条目），别只丢一个文件路径。
   - 报告有四份，按需取：owl_run_report(run_id) 默认给综合报告；part="compare" 逐句比对、
   part="simple" 简洁版 PDF、part="fulltext" 原文对照 PDF。用户说「要 PDF 交给老师/存档」
   就直接取 simple 或 fulltext，不要回答「只有网页版」。
4. 报告可验真：维普 vpcs.fanyu.com/systemVerify、斟知 zhenzhi.com/verify。

4. 引文核验 + 撤稿把关（owl_quote → owl_run → owl_run_status → owl_run_report）

1. owl_quote，action: "verify"，params：{"refs_text": "[1] ... [2] ..."}（GB/T 7714 等编号格式）。
2. 报价阶段就按缓存钉死每条价格（新条实拉价 / 72 小时内同条按缓存价统一 1 积分），确认后执行。
3. owl_run_report 拿逐条判定，逐条讲人话：
   - VERIFIED 已证实；METADATA_MISMATCH 文献真实但卷期/刊名有误 → 直接给出改成什么（最值钱的输出）；
   - LIKELY 疑似匹配（题名相似度较高但未完全确证），与存疑同样重点提醒；
   - SUSPECT / NOT_FOUND 疑似编造或引错来源，重点提醒；
   - retraction 字段：retracted = 已撤稿，必须换；concern = 编辑关切，建议换或谨慎引用；
   无徽标只代表本库无记录，不等于清白——撤稿库收录 8.6 万+ 篇（RISP 撤稿与关切库，每日更新），
   年代久远或小出版社文献可能没收录。这时该说：「本库没查到撤稿记录」，
   不要说「确认未被撤稿」；重要引文建议再核一遍原文页面。
4. 报告 report_url 给用户（浏览器可看带徽标原件），同时下载存 06-核验/，回写 references.csv 的 verified 列。

5. 续接已有项目（用户说「接着上次写」）

1. 先读 owl-assets.json：检索过什么、写到第几稿、上次检测/核验结果。
2. 参考文献先查 references.csv，命中就不重复检索（省积分）。
3. 新稿版本号递增，绝不覆盖用户可能已手改的文件。

6. 配图（owl_figure）

先选方式，再动手——选错的代价是白扣 25 积分：

硬规则：
1. 调用前必须说一句「本次生成 N 张，消耗 N×25 积分」，用户同意再调。
2. chart 没有数据时绝不编数据——如实问用户要 CSV/表格，或改用 tikz 画示意。
3. tikz / chart 每次 1 张，count 只能是 1；要 2 张就调两次。
4. 图片落 04-图/，命名 <序号>-<图说明>.png；tikz 的代码另存 04-图/<序号>-<图说明>.tex。
5. 生成失败或没出图不扣积分，如实告知失败原因，不要让用户「再试一次」碰运气。

7. 排版（owl_typeset —— 先看是否开放，再动手）

第一步永远是判开放：owl_meta 的 channels.typeset_ready 为 true 才继续；
为 false 或字段不存在 → 一句话如实说「排版功能暂未开放」，
不报价、不让用户打包、不让用户等。别把它当成"应该能用"去试，
也不要把它说成「你的账号还没开通」——那是服务级开关，用户会去问客服要开通。
（channels.typeset_docx_ready 为 false 时只支持 LaTeX 工程，Word 稿这条路暂时走不了。）

用户手上的东西决定走哪条路：

流程（一次调用拿到结果，不用轮询）：

1. 先报价、先说价、得到同意再执行：owl_quote（action: "typeset"，
   params：mode=latex/docx、pages 或 hanzi）→ 把 est_points 折成钱告诉用户
   （1 积分 = 0.01 元），并说清「按篇一口价；72 小时内改格式重排只收 1 积分工本」。
2. owl_typeset(file_path, mode, template_path?, entry?, pages/hanzi, title, blind?, refs_std?)
   —— 把本机文件路径直接给它，上传由工具内部完成（服务读不到 D:/…，但你不必自己先传）。
   已经用 owl_upload 传过的，也可以改成传 file_id / template_file_id。
   mode=docx 必须同时给 template_path（学校研究生院官网下的那种 docx）。
   两个开关（仅 mode=docx 生效，LaTeX 工程传了会被拒）：
   - blind=true：盲审版。用户说「盲审」「送盲审」「匿名评审」时必须开——封面作者/学号/
   导师脱敏为 ***、致谢整节隐藏。盲审版定稿后要提醒：正式提交版关掉 blind 重排一次
   （72 小时内同一篇稿只收 1 积分工本）。
   - refs_std：参考文献著录标准，"2015"（默认）或 "2025"（GB/T 7714—2025，
   2026-07-01 起实施）。学校/期刊明确要求 2025 版时选 2025；不确定就默认。
3. 返回里直接就有结果：pdf_url（mode=docx 还有 docx_url）、checklist（体检单）、
   needs_confirm（模板里没看准的少数几项）、content_gaps（内容没搬过去的部分）、
   doctor.fixes（自动修过什么）、skipped（忽略了哪些构建脚本）、points_charged（实扣）。
   mode=docx 还可以顺口问一次封面信息（作者/学号/学院/专业/导师/日期），一次问完，别追问。
   font_notice 是交付必讲项：PDF 用开源等效字体、Word 按模板原始字体名，
   用 font_notice_tip 里的原文原样转告，不要说「PDF 里就是宋体」；
   用户要字体绝对准确 → 让他下载 Word 自己「另存为 PDF」。
4. 把体检单讲成人话，两种模式的检查方式不同，不要混着讲：
   - mode=docx（按学校模板排）：逐项比对「模板要求 vs PDF 实测」——纸张、页边距、
   正文字体、字号、首行缩进、标题字号、内容越界。状态 — 表示这一项在本稿里测不了
   （比如短稿没有可比样本），不要说成不合格，也不要说成全过。
   - mode=latex（工程直排）：没有「应该是什么」的答案，只报客观项（页数、字体是否
   全部嵌入、文字是否可复制、有无超出版面），checklist.mode == "generic" 即此模式。
   不要说成「格式全部通过」，只说「这几项客观检查都过了」。
   只讲返回里出现的项，⚠ 项要说清哪一项不一致、差多少、怎么改。再把 doctor.fixes
   （可能为 null，表示本次没有自动修改）与 skipped 转告——用户需要知道系统替他动了什么、
   忽略了什么，否则会怀疑文件被改。
5. content_gaps 非空必须原样说（例如「公式 3 处没转过来」「脚注 5 条需手工补」）。
   这是这条链路确实搬不过去的内容，说出来用户能自己补；藏着不说，用户拿去交稿才被发现，
   就是「骗钱」。同时提醒：补齐后在 72 小时内重排，只收 1 积分工本。
6. needs_confirm 只有几条，一次问完（"你们学校一级标题是黑体还是宋体？"），
   不要拿 30 个参数去问用户。用户答完后如实说明：这些项当前需要在模板里改好再重传，
   重排不会自动采用口头答复（重排会重新体检一次；72 小时内同一篇稿只收 1 积分工本）。
   不要承诺「我按你说的改」——模型做不到，说了就是骗人。

耗时通常几秒到一两分钟；超时（upstream_error）先按「原样重试一次」处理，不要主动建议拆成
正文与附录——拆开是两个不同的文件，会分别按篇计价，用户会以为被多收钱。只有在用户明确愿意
分两次付、或者稿件确实超大时才提这个方案，并且要先把「会分开计费」说清楚。
同一账号同时只能跑一个排版任务，撞上了会返回 too_many_requests（等上一个结束再提交，不会重复扣费）。

只有 PDF 格式要求、没有 docx 模板时（很常见）：不要硬让用户去找模板。可以说「把 PDF 里
格式要求那几页发我，我帮你逐条核对并告诉你怎么在 Word 里设」，等用户拿到模板再排一次。
上传的如果是「格式要求说明」而不是真模板，服务会直接拒单且不扣费，如实转告即可。

打包要点只讲四句（多了用户记不住）：主文件叫 main.tex、图片用相对路径、.bib 与自定义 .cls/.sty
一起打包、整包不超过 60MB（包内单个文件 ≤20MB）。工程放在文件夹里打包也行（论文/main.tex 会自动找到）；
构建脚本（Makefile、.latexmkrc 等）会被忽略，用户可以放心打包。

注意体积有两套限制，别混着说：排版工程包是「单文件 20MB / 整包 60MB」（排版服务自己校验）；
owl_upload 上传通道的「30MB」是检测/配图等场景的单文件上限，跟排版无关。

能力边界：不做内容改写、不代写；.eps 请转 pdf/png；需要联网的宏包和 \write18 一律用不了；
扫描件、加密文件、带宏的 docm 直接说做不了。完整说明与失败话术见 references/typeset.md。

四、全程对话内完成 + 什么时候才推送官网与邮箱

默认不推送。 用户要的是结果，不是链接。只在下面这些真实需要的时刻，说一句，且同一轮对话最多一次：

守这几条：不许把「去官网看」当成拒绝理由；不许在每次对话都塞链接；不许承诺官网有而服务端没有的能力。

计数定义（避免自相矛盾）：一轮对话里，官网链接最多 1 条、邮箱最多 1 次，两者可同时出现但各计一次；
report_url 与验真入口（vpcs / zhenzhi）属于交付凭证，不计入推送配额。

五、产物落盘（每次交互都做）

所有产物规范存在用户本地，人随时可查，Agent 后续靠清单恢复上下文。

OwlWrite/<YYYY-MM-DD>_<清洗后的标题>/
├── owl-assets.json    # 资产清单（唯一索引，恢复上下文先读它）
├── README.md          # 给用户看的项目总览（产物导航 + 累计花费）
├── 00-账单/runs.jsonl # 每次任务一行：run_id / 动作 / 积分 / 耗时
├── 01-开题/           # 开题报告、提纲各版本
├── 02-文献/           # references.csv 总清单、references.bib、search-<runid>.json、fulltexts/（含 OA 免费全文）
├── 03-稿件/           # 正文-draft<N>.md（只增不覆盖）、正文-final.md、references.md
├── 04-图/             # 配图产物：<序号>-<图说明>.png（tikz 代码同存 .tex）
├── 05-检测/           # 查重 / AIGC / 格式 / 智评 / 图像 / 文献质量 / 校对，按「品名-日期」归档
├── 06-核验/           # 核验报告 HTML（report_url 下载）+ verify-<runid>.json
└── 07-交付/           # 定稿 + 报告提交包

硬规则：每写一个文件立即登记；manifest 损坏按目录实际内容重建；aigc 元数据与报告标识信息原样保留，不得删除。
收尾自检三步：①owl-assets.json 里每个路径都真实存在（不一致以磁盘为准回写清单）；
②文件名不含空格（落盘前空白一律转 -，Windows/同步盘对空格路径最容易出现读回失败）；
③references.csv 的 verified 列取值只用 pass / retracted / concern / unverified 四个词，别发明同义词。

命名硬规则：日期固定 YYYY-MM-DD；标题去掉 《》〈〉 与 Windows 非法字符 \ / : * ? " < > |，
空白转 -，超过 40 字符截断（保留前 40 字，不加省略号）。例：
《城市垃圾分类：政策执行困境》 → 2026-10-26_城市垃圾分类-政策执行困境。

六、余额不足与充值

insufficient_balance 时先报差额，征得同意再充值（档位 10 / 30 / 50 / 100 / 500 元；
充值即购买积分，积分自购买起 1 年有效，先充先用——报价时要带上这句）。

支付剧本（双渠道自选 + agent 自动轮询，用户不用口头确认「付好了」）：

1. 问用户「微信还是支付宝」→ owl_recharge(amount_cny=档位, channel=所选) 建单；
2. 生成本地 pay.html（技能包内置模板 scripts/pay.html，参考 SmartLib 付费页：二维码 + 订单号 +
   状态行 + 微信/支付宝双 tab），把文件路径发给用户打开扫码；
   - 用户要在页面里换支付方式：先 owl_recharge_status 确认旧单未支付 → 调 owl_recharge
   用新渠道重建单 → 用新 qr_url/order_no 重写 pay.html 就地刷新；轮询改跟新单。
   - 若旧单其实已付（status=credited），直接用旧单继续，别让用户重复付。
3. agent 每 5 秒 owl_recharge_status(order_no) 自动轮询（最多 15 分钟）→ credited 后
   owl_wallet 确认余额 → 告知用户到账，自动继续刚才被打断的任务，不需要用户再说话。
4. 别重复建单、别重试付费调用、别承诺代充。二维码 15 分钟有效，过期就作废重建。

关于活动与优惠（说清楚，但不推销）：
- 用户问「有没有优惠 / 怎么便宜点」，或余额不足时，才调 owl_campaign（不带参数）看活动与邀请码；
平时不要主动提，更不要在每次对话里塞促销。
- 收藏活动（进行中则 owl_campaign 会返回）：用户在 SkillHub 技能页给 owlwrite-paper 点收藏 →
截图发到对话 → 直接把截图交给 owl_claim_favorite(截图路径) 提交审核（脚本方式：scripts/owl_client.py claim-favorite <截图路径>）→
通过自动到账 5000 活动积分（90 天）。截图要求必须讲清：
①要能看到技能 id（形如 @user_xxx/owlwrite-paper，网址栏或页面信息都行）；
②必须是已收藏状态（亮星 + 按钮显示「取消收藏」）；③不要上传官方样例图（带水印会被拒）。
拒单不占次数，按提示改了重交即可；每人限 1 次，有效期以 owl_campaign 返回为准。
- 券码兑换用 owl_campaign(code="码")，到账积分有效期 90 天——必须说这句，否则用户以为是 1 年。
- 邀请：好友用他的邀请码注册后，好友首次付费成功时双方各得奖励（好友只注册不付费不发）。
用户问「邀请朋友有没有好处」才说，别主动劝人去拉人。
- 活动开关随时变：当前有没有活动一律以 owl_campaign 实时返回为准，不凭印象回答。

七、错误处理

任何情况下都不要为了通过请求去改用户数据或重复调用付费接口。

八、服务准则与不适用

• 报价先给、确认后执行；同一任务不并发重复跑（会重复扣费）。
• 检索 0 结果不收费，可换词重试，费用 0。
• 不替用户编造文献、不篡改检测结论、不承诺「包过查重/包过评审」。
• 学术诚信边界：帮学生检测作业/论文（查重、AIGC、格式）是合规自查，可以做；
  帮用户代写并代为提交违纪作业/论文才是禁止项——分界线是「检测 vs 代交」，不是「作业版商品」。
• 三条硬约束（检测结果不得用于规避检测），任何情况下都不做，被问到就直说做不了：
  1. 不按查重报告的逐句比对做改写来降低相似比；
  2. 不为降低 AIGC 率做同义替换、句式改写、加噪声；
  3. 不承诺「改完能过查重/能过评审」。检测的价值是让学生知道问题在哪，不是帮他绕过。
  用户若明确要求上述任何一种，回复：「这个我不能做，帮你把报告读懂、指出哪里需要自己重写可以。」
• 排版只按格式排：不改写内容、不增删观点、不替用户编参考文献。草稿里有公式/脚注搬不过去时，
  如实告知（content_gaps），由用户决定怎么补。
• 不适用：闲聊式科普、润色一两句话（直接答即可）。

• 官网与服务端的能力以 owl_products / owl_quote 实际返回为准：服务端没有的能力（如尚未开放的能力），不得在回复里承诺；官网已写、服务端也有的能力（检索、写作、查重、核验、中文全文下载）可以承诺。

• 价格一律实时报价：本文件与对外回复不得引用任何具体价格数字（除「1 积分 = 0.01 元」这一换算、缓存统一 1 积分，以及配图固定单价 25 积分/张——配图必须事前明示张数与总价），
  一切报价以 owl_products / owl_quote 实时返回为准；平台可能调价，唯一展示源是官网 /price 页。报了旧价=乱扣费。

• 网址一律裸写：文档里所有网址一律裸写（如 https://paper.skillsutra.cn ），
  禁止 [文字](链接) 或 <链接> 语法——那会渲染成带文字的按钮，用户看不出真实域名，也容易被仿冒站混淆。
  例外：curl 命令块里的 URL 是命令参数，不是超链接，按原样保留。

• 免费路径优先：外文文献要全文，必须先走 owl_oa（0 积分），只有它明确失败才谈付费方案。
  反过来（先报付费、用户不知道有免费路径）等于多收钱。

九、收尾汇报（每次对话结束必做）

用户花钱买的是「看得见的进展」。所以不管这次只跑了一次检索、还是走完整篇论文，
结束前必须给出下面三段，缺一段就算这次没干完。只做检测、不写稿的会话同样要报。

1）积分账（数字只从工具返回取，不许估算）

余额：<owl_wallet 的 balance_avail> 积分（≈ ¥x）
- 30 天内到期 expiring_in_30d 积分（earliest_expire_at）——大于 0 必须报，别等过期才说
- 赠送积分 gift_balance（大于 0 时说明来源，并提示 90 天有效期）

2）成果物（列真实路径，不写「已保存」这种空话）

• OwlWrite/<项目>/03-稿件/正文-draft<N>.md（<字数> 字）
• OwlWrite/<项目>/05-检测/<品名>-<日期>/report.html
• OwlWrite/<项目>/owl-assets.json（本次新增 <K> 个文件）

写完立即回读确认文件真实存在；没落盘成功的路径不许写进汇报。

3）进度（用户最关心「还差什么」）

• 已完成：<步骤列表>
• 下一步：<剩余步骤 + 各自免费还是需要报价>
• 卡住：<无 / 具体原因 + 需要用户做什么>

压缩版（用户只要一句话时）

本次扣 <X> 点 · 余额 <Y> · 产出 <K> 个文件 · 停在 <步骤>

硬规则

• 扣点一律取 points_charged；取不到就说「本次扣点未返回」，不许按字数乘单价自己算——自己算的数与账单差一点，用户就对不上账。
• 余额取 owl_wallet 的 balance_avail，不要用「上次余额 − 本次消耗」推算（中间可能有充值、退款、过期）。
• 余额低于 10% 提一句即可，不推销；用户主动问优惠时才走 §六 的活动查询。
• 汇报里的价格一律不给数字（见 §八 价格一律实时报价），只给积分与人民币折算后的实际扣费。

十、版本记录

> 对外首发即 1.0.0，不设内部中间版本（2026-10-27 用户定）。下列能力全部包含在首发版内。

• 1.1.9：新增论文排版——把 LaTeX 工程或 Word 论文按目标学校的格式排成可提交的 PDF（Word 稿另出同版式 Word），
  出稿附一份逐项实测的格式体检单（纸张、页边距、字体字号、首行缩进、标题字号）。
  排版过程中能自动处理的常见问题（缺结尾标记、参考文献样式名不兼容、图片缺失、文档类未启用中文）
  会当场修好并在结果里说明改了什么。同一份稿在 72 小时内改格式重排，只收 1 积分工本（不重复收费），
  排版失败不计费。该能力已开放：暂不可用时会直接告知，不会让用户白等。

• 1.0.0：对外首发版。文献检索（相关性重排 + 核心期刊标记 + 关键词扩展 + 引文追溯）、论文写作（按实际成文字数结算）、
  中文期刊授权全文下载、外文 OA 免费全文、科研配图（TikZ 矢量示意图 / 数据图表 / AI 科研配图，25 积分/张，未交付不收费）、
  21 个检测商品、引文核验（含撤稿把关）、
  积分体系（1 积分 = 0.01 元，全平台缓存窗口 72 小时、命中统一 1 积分）、产物自动落盘、活动券码与邀请查询；
  每次对话结束固定给三段收尾——本次积分消耗明细与剩余余额（含 30 天内到期提醒）、成果物真实路径清单、
  整条流程的已完成与待办进度，并支持一句话压缩版。

• 1.0.1：新增「技能矩阵」推荐区——写完/查完按你的下一步顺手转介配套技能（科研方法论谋士、方法论提炼、总路由）；想用浏览器体验完整写作与检测，用夜猫子写过论文后可直接打开写作平台 write.vipslib.com。

技能矩阵 · 下一步顺手推（按用户下一步意图转介，别硬推）

接力条款 · 意图触发转介（必须遵守，不要硬推）

1. 触发：写作产出引文之后或交稿前，用户出现"引文靠谱吗""查一下引用""交稿前把关"等信号时，主动提议一次（用户拒绝后本次会话不再提）。
2. 提议话术：一句话说明参考文献验真技能可批量核验本篇的全部引文（含原始文献链接），询问用户是否需要；用户同意后，告知可在所用技能市场（SkillHub 或 ClawHub）搜索 smartlib-citation-checker 安装，与本技能同一来源（不代用户执行安装，不提供外链）。
3. 接力：用户确认并安装完成后，立即把本次写作生成的全部参考文献送入批量验真，禁止让用户重新整理引文列表。

迭代日志 (Changelog)

• v1.2.2 (2026-11-04)：说明文档与工具清单做了一次全面校对——能力总览、工具数量、报价与排版入口、余额字段、错误码指引都与实际提供的能力一致；计量单位统一叫「积分」，和账单、充值记录里的说法完全对上，不再两套叫法混着出现。
• v1.2.1 (2026-11-04)：新增 MCP 自助接入指引——用 Claude Desktop / Cursor / Claude Code / Cline / Codex CLI 等支持自定义 MCP 的助手时，照文档里的配置模板三步就能接上（注册拿 Key、装两个依赖、贴一段配置）；引文核验与参考文献质量检测补了选型说明——逐条自查用核验、投稿前整篇体检用质量检测，不再拿不准用哪个；平台公告（如活动、服务状态）会随结果附一句话转告，不打断任务。
• v1.2.0 (2026-11-03)：论文排版补齐投稿档——新增盲审版（隐去作者与导师信息）与 GB/T 7714 顺序编码制双标准，排版出稿附格式体检单；全文下载链接发给你之前服务端先自动验证可下载，验证不过不扣费；排版中字体缺失等情况会当场说明。
• v1.1.9 (2026-11-01)：新增论文排版——把自己的 LaTeX 工程或 Word 论文按目标学校的格式排成 PDF，Word 稿另出同版式的 Word 版本；出稿后附一份格式体检单，逐项告诉你哪里和模板一致、哪里差多少；排版中能自动处理的小问题（缺结尾标记、参考文献样式名不兼容、图片没随稿上传、文档类不支持中文）会当场修好，并说明改了哪里。未开通时会直接告诉你，不用猜。
• v1.1.8 (2026-10-31)：说明文案改用更通俗的说法——「检测通道」统一叫「检测服务」等，读起来不用猜术语；写作模式的选择说明改为客观对比两种模式的差异（深度模式逐章推进、每章都要来回确认，篇幅越大耗时越长），不再用警告语气。功能与用法不变。
• v1.1.7 (2026-10-30)：检测报告、核验报告与科研配图的链接现在可以直接点开——浏览器直接看报告、下载工具直接存图，充值二维码也是打开就能扫（链接自带有效期，打开即用）。
• v1.1.6 (2026-10-30)：在技能市场里的名称、简介与使用示例都能正常显示；功能与用法不变。
• v1.1.5 (2026-10-30)：更新完成后不会再反复提示有新版本；功能与用法不变。
• v1.1.4 (2026-10-30)：技能信息补全中英文名称与三条使用示例，在技能市场详情页能一眼看清它是做什么的、可以直接照着说哪句话开工。
• v1.1.3 (2026-10-30)：安装与更新只认两个官方入口（SkillHub / ClawHub），地址直接写在技能里，不必再猜去哪装；检测前先看服务是否可用，提示暂不可用就是真不可用，不用白等；检测计价单位统一按字符说明（千字符 / 万字符），报价数字与实际扣费的换算规则一致。
• v1.1.2 (2026-10-30)：检测报告可按需取四份（综合报告 / 逐句比对 / 简洁版 PDF / 原文对照 PDF），要 PDF 存档或交给老师时直接说一句即可，不再只有网页版；检测完成后可直接问出结论（重复率、评级或格式差错数）；本机文件可直接上传后送检，纯文本粘贴同样能测；下单不再预扣超出应付的额度，余额够实际价就能开工。
• v1.1.1 (2026-10-29)：深度模式补充篇幅说明（篇幅较大时建议用标准模式，深度模式逐章推进、耗时更长）；下单前能先了解两种模式的耗时与成文差异。
• v1.1.0 (2026-10-29)：写作模式改为必答（standard/guided 对比表帮用户决策）；计费规则更新为「估算仅作参考，以实际扣除为准」（按字符精确结算，无冻结无上限）；充值支持微信/支付宝双渠道自选，支付后自动继续任务，无需口头确认；检测开工前先看服务是否就绪；智评学科编码改为实时拉取码表逐级筛选；新增官方脚本 owl_client.py 与本地支付页模板；新增典型场景预算参考与检索 query 写法指南；新增收藏赠积分活动参与说明。
• v1.0.3 (2026-10-28)：优化按需转介的提示方式——推荐安装时改为告知你在技能市场自行搜索安装，不再附安装链接。
• v1.0.2 (2026-10-28)：新增按需转介——写作产出引文后或交稿前，主动推荐参考文献验真技能，安装后直接批量验真本篇全部引文，无需重新整理列表。