# 夜猫子论文工作台（OwlWrite）

> 夜猫子论文工作台为 AI Agent 提供可溯源、可核验的中英文文献检索、论文写作、维普查重与引文核验能力。本文档面向 LLM、AI Agent 和开发者工具，提供可直接读取的入口与调用规则。

Canonical site: https://paper.skillsutra.cn
API origin: https://owl.skillsutra.cn
Generated: 2026-11-04

## Read This First

- [官网首页](https://paper.skillsutra.cn/): 产品定位、能力、配方、价格与合规说明（单页静态 HTML，无 SPA，可直接读取）。
- [REST API origin](https://owl.skillsutra.cn): 全部 API 调用走此域名，鉴权使用 `Authorization: Bearer <API Key>`（Key 以 `owl_sk_` 开头，邮箱验证码验证通过后签发）。
- [安装技能](https://paper.skillsutra.cn/#install): 两个官方安装入口（SkillHub / ClawHub）与装完自检四步，Agent 照做即可。
- [MCP 接入](https://paper.skillsutra.cn/#dev): 21 个标准 MCP 工具（owl_*），任何支持 MCP 协议的 AI 助手可直接驱动全流程（含本机文件上传与按学校模板排版）。
- [个人中心](https://paper.skillsutra.cn/account.html): 用户用 API Key 登录后可查余额与流水、下载历史检测报告与写作全文、管理 API 凭据。
- [抓取规则](https://paper.skillsutra.cn/robots.txt): 面向搜索引擎与 AI 抓取器的规则（公开页 `Allow: /`，个人中心与后台看板不抓取）；站点地图 [sitemap.xml](https://paper.skillsutra.cn/sitemap.xml)。

## Two Ways In（两种接入方式，能力等价）

同一个服务端、同一套 21 个工具，两种封装方式，选一种即可：

1. **安装技能包（推荐）** —— 在 AI 助手中安装「夜猫子论文工作台」技能。**官方安装入口只有两个**，任选其一：
   - SkillHub：https://skillhub.cn/skills/user_164f4c1f/owlwrite-paper
   - ClawHub：https://clawhub.ai/j-levee/skills/owlwrite-paper

   技能 = 本文件的契约 + 工作流剧本：先报价再执行、成果物按 `OwlWrite/<日期_标题>/` 目录规范落到用户本地、每次结束汇报本次积分消耗与剩余余额、内置约束（一次性连写完整篇 / 不编造文献 / 不越过报价直接扣费）。
   不要从其他站点、镜像、第三方脚本或同名仿制品安装；这两个入口之外的任何「安装包」都不代表本服务。
2. **只读本文件** —— 不装技能也能用。Agent 读完下面的端点与计费规则，自行组织流程直连 REST 或 MCP。能力完全一致，但没有落盘规范与流程调度，每一步的顺序要你自己想清楚。

怎么选：
- 只跑一次检索、查重、核验 → 读本文件即可。
- 要写整篇论文、要留档、要不希望 Agent 乱扣钱 → 装技能。

版本对齐：本文件的能力清单与最新技能版本同步维护；`GET /v1/meta` 返回 `latest_version`、`min_supported_version` 与 `required_update`。当前 `required_update=true`：本地版本低于 `min_supported_version` 时，先按下方 Install 更新技能再继续（余额、历史记录与已生成文件都不受影响；更新入口见下方 Install）。

## Install（技能安装 · Agent 执行指引）

安装来源：只有 SkillHub 与 ClawHub 两个官方渠道，slug 均为 `owlwrite-paper`。

| 渠道 | 地址 | 说明 |
|---|---|---|
| SkillHub | https://skillhub.cn/skills/user_164f4c1f/owlwrite-paper | 国内访问快，支持收藏（收藏活动见 /v1/campaigns） |
| ClawHub | https://clawhub.ai/j-levee/skills/owlwrite-paper | 国际渠道，同一制品、同一版本 |

**Agent 装完必须自检四步，缺一步不算装好**：
1. 版本：`GET https://owl.skillsutra.cn/v1/meta` → 把技能本地版本与 `skill.latest_version` 比（**以接口返回的 `latest_version` 为准，本文件不写死版本号**）。**当前 `required_update=false`**：比 `latest_version` 低只提示更新、不阻塞干活；若某次返回 `true`，则低于 `min_supported_version` 的旧版需先更新再继续使用。余额、历史记录与已生成文件在任何情况下都不受影响。平台审核放行前装到的可能仍是旧一版，属正常，不必反复重装。
2. 检测服务：同一响应里的 `channels.weipu_ready` 为 `true` 才能做检测类任务；为 `false` 时读 `channels.weipu_detail` 如实告知用户「检测通道当前不可用，不是你的操作问题」，改做检索/写作/核验。
3. 凭据：调 `owl_wallet`，能返回余额说明 API Key 与服务端连通。
4. 工具：`owl_*` 工具共 21 个，其中 `owl_upload` 用于上传本机论文文件换 `file_id`（云端读不到用户本机路径，检测必须先上传）；`owl_typeset` 用于按学校模板排版出 PDF（Word 稿另出同版式 Word），需先 `owl_quote` 拿报价。

**给 Agent 的安装提示词（可直接照做）**：

> 帮我安装「夜猫子论文工作台」技能（slug: `owlwrite-paper`），只从下面两个官方入口安装，任选其一：
> · SkillHub https://skillhub.cn/skills/user_164f4c1f/owlwrite-paper
> · ClawHub https://clawhub.ai/j-levee/skills/owlwrite-paper
> 装完请依次确认：① 技能版本与 `/v1/meta` 的 `latest_version` 对照（≥ `min_supported_version` 且工具能正常调用即可；低一版只提示更新，不阻塞干活）；② MCP 服关指向 https://owl.skillsutra.cn 并填入我的 API Key；③ 调 `owl_meta` 看 `latest_version` 与 `channels.weipu_ready`；④ 调 `owl_wallet` 念一次余额。不要从其他站点或第三方脚本安装同名技能。

## Current Campaign（当前活动 · 状态以接口为准）

- 活动：在 SkillHub 技能页给本技能点「收藏」，把截图发给你的 AI 助手对话，即可领取 **5000 活动积分**（赠送积分 90 天有效，先到期先扣）。
- 实时状态：开放期、剩余名额、是否已到账，一律以 `GET /v1/campaigns`（需 API Key）或个人中心「活动与邀请」的返回为准；**不要把本文件的静态描述当成承诺**。
- 公告推送：调用 API 时响应可能带顶层 `owl_notice` 字段（当前活动与重要公告），`GET /v1/meta` 的 `notices` 是完整公告列表。Agent 看到与用户相关的公告应如实转告，不要静默丢弃。

## Agent Fetch Rules

- 本站为静态单页，无客户端渲染；Agent 可直接抓取 `https://paper.skillsutra.cn/` 原始 HTML 与本文件。
- API 调用一律使用 `https://owl.skillsutra.cn`；`https://paper.skillsutra.cn` 仅为官网静态页，不代理 API。
- 所有付费动作必须先报价（owl_quote / POST /v1/quote）并向用户确认后执行；报价 24 小时内有效。
- 计价规则：1 积分 = ¥0.01。购买积分有效期 1 年、活动赠送积分 90 天，均先到期先扣。全平台缓存命中统一 1 积分，**缓存窗口统一 72 小时**（检索同 query / 详情同篇 / 全文同篇 / 核验同条 / 引文同方向）；无结果 0 积分；任务执行失败自动退款；外文 OA 免费探测 0 积分。写作与检测类均为**后付费**：开工前只做余额软预检（余额不足按差额拦截），**不冻结任何积分**；结束后按实际量结算——写作按实际成文字数、检测按解析出的真实字符数，**无封顶、无下限、无「不足千字按千字计」**。完整实时价目：/price 页与 GET /v1/prices。

## Capabilities（能力全景，14 类）

- 文献检索：中英文双库自动路由，返回题名/作者/刊名/年份/DOI/链接，支持文献清单、BibTeX 与 GB/T 7714 引用格式。
- 文献详情：单篇完整元数据（DOI/年卷期/摘要），中文库与全球库同一接口切换 lang。
- 中文全文下载：授权中文期刊 PDF 直链（发链前服务端已自动验证链接可下载，验证不过不扣费）。
- 外文 OA 全文：arXiv / OpenAlex / Unpaywall / Europe PMC 四级免费探测，0 积分。
- 引文追溯：从一篇文献出发查它引用了谁（refs）、又被谁引用（cited）。
- 论文写作：标准（¥6/千字）与深度（¥9/千字）双模式，一次性连续成文，按实际成文字数结算，全文可取回落盘。
- 论文查重（商品名：维普查重）：维普官方检测服务，大学生版/研究生版/职称版等商品，报告可双平台验真。
- AIGC 检测 / 格式检测 / 斟知智评 / 图像可信度 / 参考文献质量 / 斟校对：同一检测流程不同商品，实时价目见 /v1/products。
- 引文核验：逐条四档判定（已证实 / 元数据不符 / 疑似 / 未找到），元数据不符直接给出正确字段与修改建议，并做撤稿把关。
- 引文检查选型：写作过程中逐条自查用「引文核验」（按条计费，含撤稿把关）；投稿前整篇终检用「参考文献质量检测」（按篇计费，官方检测报告）。两者数据源与判定口径不同，结论可能不完全一致，以数据库原始记录为准。
- 按模板排版：LaTeX 工程或 Word 稿按学校模板排出可提交 PDF + 同版式 Word + 格式体检单，支持盲审版与 GB/T 7714 双标准。
- 科研配图：TikZ 矢量示意图 / 数据图表 / AI 配图，按实际交付张数扣费。
- 账户与充值：余额、流水、充值（扫码）、凭据管理、活动与邀请。
- 报告验真：维普官方与斟知双平台核验报告真伪。
- 产物落盘：技能包模式下按 `OwlWrite/<日期_标题>/` 目录规范落到用户本机。

## Resource Foundation（资源基础）

- 中文期刊库：8000 万篇授权中文期刊全文，支持检索、详情与 PDF 全文下载；中文引文核验逐条比对真实记录。
- 全球文献库：12.28 亿条元数据（期刊 7.19 亿 / 专利 2.15 亿 / 会议 7155 万 / 学位论文 2473 万 / 标准 268 万）。
- 撤稿与诚信库：8 万+ 条撤稿 / 关切（Expression of Concern）/ 更正记录（Retraction Watch + PubPeer 聚合），支持引用前把关。
- DOI 注册库：Crossref 备用验证来源；检索多来源自动补充，无结果不扣费。

## MCP Clients（国内助手优先适配）

国内优先，WorkBuddy 首推。

- 国内：WorkBuddy（首推）、千问办公、豆包、百度搭子、DSH（DeepSeek Harness）、AutoClaw（智谱）、Trae Work、Zcode、MiniMax Code、Dify、Cherry Studio。
- 国际：Codex、Claude Code、Cursor、ChatGPT、Hermes。
- 以上均通过 MCP 协议接入：先按上一节「Install」从 SkillHub / ClawHub 装技能包，再填入 API Key；开发者亦可直连 REST API。

## MCP Tools（21 个）

- owl_search：文献检索（相关性重排 + 核心刊标记 core_tags + 关键词扩展；命中 2 积分 / 缓存 1 积分 / 无结果 0 积分）
- owl_article：文献详情查询（4 积分/次，72 小时缓存 1 积分；返回 DOI/年卷期等完整元数据）
- owl_fulltext：中文期刊全文 PDF 直链（200 积分/篇，72 小时内同篇重取 1 积分，单账号每日 100 篇；服务端发链前已自动验证链接可下载，验证不过不扣费并返回 502 fulltext_delivery_failed；链接约 1 小时有效，拿到后**原样完整**（URL 含 & 与编码文件名，进 shell 要整体加引号）立即 HTTP GET 下载并校验文件头为 %PDF；仅中文库文献有全文，404 表示无授权全文）
- owl_oa：外文 OA 免费全文（0 积分；arXiv / OpenAlex / Unpaywall / Europe PMC 四级探测，返回 pdf_url 或 landing_page；closed 表示付费墙内）
- owl_figure：科研配图（mode=tikz 矢量示意图 / chart 数据图表 / image AI 配图；25 积分/张，按实际交付张数扣，未交付不收费；tikz 额外返回可直接粘贴的 tikz_code；图片落盘后给下载地址）
- owl_citations：引文追溯（doi + direction=refs|cited，2 积分/次，72 小时缓存 1 积分）
- owl_campaign：活动券码兑换 / 我的邀请码与战绩（免费；赠送积分有效期 90 天）
- owl_claim_favorite：提交 SkillHub 收藏截图领活动积分（免费，每人限 1 次，截图需含技能 id 且为已收藏状态）
- owl_upload：上传本机文件换 file_id（docx/doc/pdf/txt 或 png/jpg/tif 等，单文件 ≤30MB，免费）；托管环境检测必用——服务在云端读不到用户本机路径
- owl_quote：写作/查重/核验报价（免费；检测需给 file_id 或 content，并给 hanzi 汉字数才出价）
- owl_run：执行已报价任务（写作/检测按实际量结算，无冻结、无封顶）
- owl_typeset：按学校模板排版出 PDF（Word 稿另出同版式 Word + 格式体检单；可选 blind=true 出盲审版：封面脱敏+隐藏致谢；可选 refs_std=2015/2025 切 GB/T 7714 著录标准；按篇一口价 500–2000 积分，按整本 PDF 页数分档；先 owl_quote 拿报价，报价即最终价，实排超档会拒单不扣费；72 小时内同一篇稿改格式重排只收 1 积分；排版失败不收费）
- owl_run_status：轮询任务状态（免费）
- owl_run_content：取回写作完整正文与参考文献（免费）
- owl_run_report：核验逐条判定摘要；检测报告四份可选 part=main 综合 / compare 逐句比对 / simple 简洁版 PDF / fulltext 原文对照 PDF（免费）
- owl_products：全平台实时价目（积分体系；价格唯一可信来源，勿引用静态数字）（免费）
- owl_disciplines：斟知智评学科编码表（class_id 用，逐级筛给用户选；免费）
- owl_meta：技能最新版本 + 平台公告（开工校准用；免费）
- owl_wallet：查余额（免费）
- owl_recharge：发起充值（10/30/50/100/500 元，返回扫码链接，15 分钟有效）（免费）
- owl_recharge_status：核实充值到账（免费）

## REST Endpoints（核心）

- POST /v1/auth/send-code：发 6 位邮箱验证码（15 分钟有效，同邮箱 60 秒冷却，同 IP 限频）。
- POST /v1/auth/register：带上验证码注册，返回 api_key（只显示一次）。参数 {"email","code"}。
- POST /v1/auth/login-code：给**已注册**邮箱发登录验证码（API Key 丢失时的找回入口，不用重新注册）。
- POST /v1/auth/login-code/verify：参数 {"email","code"} → 签发一把新 api_key；旧 key 继续有效，余额与记录不变。
- GET /v1/auth/policy：当前注册/登录策略（是否强制验证码、邮件发送是否就绪），公开只读。
- POST /v1/search：文献检索，Body: {"query": "...", "limit": 5}。
- POST /v1/fulltext：中文期刊全文下载，Body: {"identifier": "<检索返回的 Identifier>"} → {"url": "<下载直链>", "expires_in": 3600, "points_charged": 200}；仅中文库，无授权全文返回 404 fulltext_unavailable；链接校验未通过返回 502 fulltext_delivery_failed（**未扣费**）。
- POST /v1/files：上传待检测文件，Body 为原始字节 + 请求头 X-Filename（UTF-8 百分号编码）→ {"file_id","filename","ext","bytes"}；限 docx/doc/pdf/txt 与 png/jpg/tif/bmp/gif/webp，≤30MB。
- POST /v1/quote：任务报价（action: write / check / verify / typeset）；check 支持 file_id + hanzi（汉字数）或 content 直传。
- POST /v1/runs：执行已报价任务；GET /v1/runs/{id} 轮询状态；POST /v1/runs/{id}/cancel 取消在跑任务（写作/检测取消不扣费）。
- GET /v1/runs/{id}/content：取回写作完整正文。
- POST /v1/typeset：按模板排版（Body 用 /v1/quote 的 typeset 报价：模板 file_id + 稿件 file_id，可选 blind=true 盲审版、refs_std=2015|2025）。响应含 pdf/docx 下载链接、格式体检单、字体差异说明（font_notice）。
- GET /v1/runs/{id}/typeset/pdf 与 /v1/runs/{id}/typeset/docx：排版产物下载（响应里给的签名链接 7 天内有效，直接 GET）。
- GET /v1/runs/{id}/figures/{idx}：配图产物下载（响应里给签名链接）。
- GET /v1/me：账号信息 + 钱包 + 计费表。
- GET /v1/me/wallet：余额（积分、30 天内到期量、最早到期日）。
- GET /v1/me/ledger：点数流水。
- GET /v1/prices：公开实时价目（含 version，价格如有调整以此为准）。
- GET /v1/products：检测/流程商品目录（编码、名称、计费单位 `unit` 与 `count_unit`、单价；Agent 取商品码就用它，不要再背编码）。
- GET /v1/disciplines：斟知智评学科编码表（`class_id` 用，逐级筛给用户选；约 5000 条/5 维度）。
- GET /v1/health：全站能力实时状态（7 类服务的 state 与 detail + 自洽的 counts；官网状态列就取它）。
- GET /v1/meta：技能最新版本与公告（公开）。
- GET /v1/article?identifier=&lang=zh|en：文献详情（4 积分/次，缓存 1 积分）。
- POST /v1/oa：外文 OA 免费全文探测，Body: {"doi","title"} → {"oa_status","pdf_url","landing_page","via"}；0 积分，未命中不收费。
- GET /v1/citations?doi=&direction=refs|cited&limit=20：引文追溯（2 积分/次，72 小时缓存 1 积分）。
- POST /v1/campaign/redeem：兑换活动券码，Body: {"code"}（免费）；GET /v1/campaigns、GET /v1/invite：可领活动与邀请码战绩（免费）。
- GET /v1/me/runs：我的任务记录（含报告 / 全文可取回标记）。
- GET /v1/me/keys：凭据列表（只回前缀，不含明文）；POST /v1/me/keys 新建；POST /v1/me/keys/{id}/revoke 吊销。
- GET /v1/runs/{id}/report?part=main|compare|simple|fulltext：引文核验报告，或检测报告四份（综合 HTML / 逐句比对 HTML / 简洁版 PDF / 原文对照 PDF）。核验报告逐条带撤稿风险徽标（已撤稿 / 编辑关切 / 未撤稿，撤稿库 8.6 万+ 篇每日更新）。
- GET /v1/me/runs/{id}/link：生成个人中心产物分享链接（用户要在浏览器里下载历史报告/全文时用）。

## Errors & Limits（错误码与限额，Agent 必读）

**通用计费规则**：任务执行失败自动退回点数（status=failed 时钱包不受影响）；报价 24 小时有效，过期重报（quote_expired / quote_consumed）。

| HTTP | code | 含义与 Agent 该怎么做 |
|---|---|---|
| 401 | invalid_key | API Key 无效或已吊销：引导用户去个人中心重新签发 |
| 402 | insufficient_balance | 余额不足（这里给的是估算值，结算按实际用量）：报出差额与今天可用额度，引导 /v1/pay/recharge 扫码充值 |
| 402 | shortfall_blocked | 有历史任务欠款未结清：引导充值，充值额度优先抵扣欠款 |
| 404 | fulltext_unavailable | 该篇没有授权全文：如实转告，别换参数硬试 |
| 404 | quote_not_found / bad_file | 报价不存在 / 文件不是本人的或已过期：重新报价或重新上传 |
| 422 | bad_params | 参数不合法（identifier 格式、缺 hanzi 等）：按 message 修正后重试 |
| 429 | too_many_requests | 限频（全文 10 次/分钟、查询 20 次/分钟）或排版同账号单任务：按 message 里的提示稍后重试 |
| 429 | fulltext_daily_limit | 全文下载达每日 100 篇上限：告知明天再试 |
| 502 | upstream_error | 检测服务暂时不可用：原样重试一次；仍失败如实转告，不扣费 |
| 502 | fulltext_delivery_failed | 全文链接交付校验未通过（已自动重试 1 次）：**未扣费**，请稍后重试或换一篇 |
| 503 | typeset_disabled | 排版功能暂未对外开放（服务级开关）：如实转告，不报价不让用户等 |

**频控/限额汇总**：全文下载 10 次/分钟 + 每日 100 篇；检索/详情/核验等查询类 20 次/分钟；检测类按商品各有日限额（以 429 的 message 为准）；排版同一账号同时只能跑一个任务；充值订单 15 分钟有效（/v1/pay/recharge/{order_no}/cancel 可取消）。

## Report Verification（报告验真）

- 查重等产品为维普官方检测，报告可通过以下两个平台验真，保障用户权益与信息安全：
  - 维普报告验真平台：https://vpcs.fanyu.com/systemVerify
  - 斟知验真平台：https://www.zhenzhi.com/verify

## Compliance

- 产出文本由 AI 辅助生成，所有报告按《人工智能生成合成内容标识办法》携带 AI 标识与 AIGC 元数据；署名作者对最终提交内容负责。
- 拒绝代写代考等违反学术诚信的请求；检测与核验工具用于帮助作者自查与修正。
- 本服务通过 API 调用第三方大模型服务，该提供方已按国家规定履行生成式人工智能服务备案义务；产出内容与报告均带显式 AI 标识与 AIGC 元数据，可追溯。