wengaosheng

Ping

连通性自检 tool（健康检查 + 鉴权自检）。 **调用需鉴权**（FR-M3）：从当前请求的 Bearer key 解析出 User；缺 / 非法 / 吊销 / 禁用 → 返结构化 `auth_required`。成功时回当前鉴权身份（username / id）， 供调用方确认 key 绑定的是哪个账号。anonymous discovery 仍可列出本 tool 的 schema（列举不执行 body，故天然不鉴权）。

Generate Doc

Generate a bilingual close-reading document from English text or an SRT subtitle. Submits an async job and returns immediately with a task_id; poll get_doc until status is "SUCCESS" (statuses are uppercase: PENDING / PROCESSING / SUCCESS / FAILED). Personalization (vocabulary level / Zipf threshold) always follows the key owner's profile and cannot be overridden here. Args: source_type: "text" (pasted English text) or "srt" (SRT subtitle file content). text:

Upload Audio

Attach a full-length audio track (by public URL) to make a spoken document. The server fetches the audio from the URL, validates size/duration, stores it, and marks the document as a spoken (uploaded-audio) version. SRT-sourced documents only. Idempotent: if audio already exists, returns current status. Args: task_id: The document task_id (must belong to the key owner). audio_url: A public http(s) direct link to the audio file (mp3/m4a/aac/wav). Returns:

Set Title Summary

Edit a document's title and/or English/Chinese summary (author only). Each field is optional: omit (null) to leave unchanged; empty string clears the summary fields (title cannot be cleared). Args: task_id: The document task_id (must belong to the key owner). title: New title (optional). summary_en: New English summary, or "" to clear (optional). summary_zh: New Chinese summary, or "" to clear (optional). Returns: {ok: true} on success,

List My Docs

List documents created by the authenticated account (newest first). Only the key owner's own documents (not forks). Use this to find task_ids and doc URLs to share. Page through all docs with `offset`: keep increasing it by `limit` until you get fewer than `limit` items (that's the last page). Args: limit: Max items per page (default 50, 1–200). offset: Skip the first N items (pagination; 0 = first page). since: ISO-8601 timestamp; only return documents

Get Doc

Get status and metadata for one of your documents. Poll this after generate_doc until `status` is "SUCCESS" (uppercase: PENDING / PROCESSING / SUCCESS / FAILED). For spoken documents it also returns the audio_url once available. Args: task_id: The document task_id (must belong to the key owner). Returns: {status, title, doc_url, visibility, error?, audio_url?}, or a structured error dict on auth failure.

Get Doc Content

Get the full annotated content (result_json) of one of your documents. Returns the bilingual sentences, vocabulary annotations, levels, title and summaries — everything needed to render or post-process the doc downstream. Author only. Args: task_id: The document task_id (must belong to the key owner). Returns: {task_id, title, summary_en, summary_zh, visibility, source_lang, gloss_lang, result} where `result` is the full result_json, or a structured

Get Quota Status

Get the account's token quota / rolling-window status, tier and word limit. Use before generating to know remaining budget, and to explain limits to the user. Returns: {tier, word_limit (null = unlimited), windows: {session?/weekly?/monthly: {used, limit, pct, reset_in_seconds, status}}}, or a structured error dict.

Get Vocab Profile

Get the account's personalization profile used for annotation. Generation always annotates against this profile (vocab size / Zipf threshold / levels / pronunciation accent) — read it to understand how docs will be marked. Returns: {vocab_size, zipf_threshold, vocab_levels, pron_accent}, or a structured error dict.

List My Groups

List the learning groups (学习圈, R28) you own or have joined. Returns: {owned: [{group_id, name}], joined: [{group_id, name}]}, or a structured error dict.

Reannotate Doc

Re-annotate one of your documents against new exam levels / your vocab threshold. Reuses existing translations (no re-translation, no LLM cost beyond annotation), overwrites the current doc. Async — poll get_doc until status SUCCESS. Author only. Args: task_id: The document task_id (must belong to the key owner). levels: Exam vocab levels to annotate against (e.g. ["cet4","cet6"]). Omit to fall back to the key owner's global `vocab_levels` profile (then

Edit Doc Sentence

Edit one sentence's English original and/or Chinese translation (R13, owner only). Editing `en` re-annotates that sentence (no LLM) and re-renders the PDF; editing `zh` just updates the text. Audio (if any) may become inconsistent with the new text. Args: task_id: The document task_id (must belong to the key owner). index: 0-based sentence index. en: New English text (optional). zh: New Chinese translation (optional). Provide at least one of en/zh.

Set Vocab Prefs

Update your annotation preferences (affects how FUTURE docs are annotated). Args: levels: Exam levels / wordlists to prefer (empty list = unset). Replaces the current set. pron_accent: "us" or "uk" (omit to leave unchanged). Returns: {vocab_levels, pron_accent} on success, or a structured error dict.

Download Pdf

Get the PDF download URL and generation status for your document. The URL needs your API key (Bearer) to fetch. If status isn't "done" yet, the PDF is still rendering. Author only. Args: task_id: The document task_id (must belong to the key owner). Returns: {pdf_status, download_url}, or a structured error dict.

Set Visibility

Change a document's visibility. Owner only. ⚠️ DANGER: setting a private doc to "public"/"unlisted" exposes it publicly. **You MUST pass confirm=true** to proceed — read the change aloud to the user first. Args: task_id: The document task_id (must belong to the key owner). visibility: One of "private" / "unlisted" / "restricted" / "public" / "group_visible". confirm: Must be true to apply (safety gate against accidental exposure). emails: For "restri

Set Enable Fork

Toggle whether others can derive a personalized child ("跟学") from your doc. Args: task_id: The document task_id (must belong to the key owner). enable: True to allow forking, False to disallow. Returns: {ok: true, enable_fork} on success, or a structured error dict.

Create Child

Derive your own personalized child copy ("跟学") of a forkable document. Idempotent: if you already have a child of this parent, returns it (no extra cost). First create costs tokens. The parent must allow forking and be visible to you. Args: parent_task_id: The parent document's task_id. Returns: {ok: true, child_task_id, ...} on success, or a structured error dict.

Like Doc

Like a document you can view (R12). Args: task_id: The document task_id. Returns: The like result, or a structured error dict.

Follow User

Follow a user by their @username (R12). Args: username: The target user's unique @username (without the @). Returns: The follow result, or a structured error dict.

Share Poster

Get the share-poster image URL for your document (server-rendered PNG). The poster is gated by the doc's visibility (private docs can't be shared). The URL renders/returns the poster on fetch. Author only here. Args: task_id: The document task_id (must belong to the key owner). include_qr: Optional QR toggle. None = visibility default (public/paid carry a QR that links back to the doc, unlisted/guest-public don't). Set False to drop the QR (e

Delete Doc

Permanently delete ONE of your documents. **IRREVERSIBLE.** Cascades to the document's audio, poster and PDF, and leaves a tombstone for anyone who forked it ("原作者已删除"). Author only. Safety protocol: call once WITHOUT confirm to get the title, **read it to the user for explicit confirmation**, then call again with confirm=true. One document per call — never batch deletes. Args: task_id: The document task_id (must belong to the key owner). confirm: Must