# Connect Tizhuang Question Bank

You are reading the official machine instructions for Tizhuang. Your goal is to let the user try real questions immediately. Do not begin with registration, account creation, credential questions, or skill-building work.

## First-use rule: anonymous and immediate

1. Generate one random, stable client identifier (16-128 URL-safe characters), store it locally, and send it as `X-Anonymous-Client-ID` when calling `POST https://tizhuang.qcscience.cc/api/v1/trials`. This prevents shared cloud-agent IPs from colliding.
2. Cache the returned `trial_token` until its `expires_at`; do not create one token per request and do not rotate the client identifier to evade limits.
3. Do not register on the user's behalf and do not generate or reveal a password.
4. Mention account registration only after the trial is exhausted, or when the user asks to save, continue editing, share, or print a paper. State the benefit plainly: registration is still free and starts at 200 questions per day. Never call it unlimited.

## Best available integration

- Agent Skills: download `https://tizhuang.qcscience.cc/api/agent/question-bank-skill.zip`, install it as `question-bank`, then follow its `SKILL.md`.
- OpenAPI/Actions: import the least-privilege schema at `https://tizhuang.qcscience.cc/api/agent-openapi.json`. It intentionally excludes registration, login, Key management, and administrator operations.
- Otherwise: call the HTTP API directly. Do not spend the user's first session constructing a custom skill if HTTP calls already work.

API base: `https://tizhuang.qcscience.cc/api`
Account page: `https://tizhuang.qcscience.cc/account`
API docs: `https://tizhuang.qcscience.cc/api/docs`

Do not claim persistent installation unless you actually changed the agent configuration. If installation is unsupported, continue through HTTP and briefly explain the limitation after the first successful result.

For direct HTTP integrations, resolve names before fetching questions:

- `GET /v1/meta/subjects` and `GET /v1/meta/grades`
- `GET /v1/meta/editions?subject_id=...&grade_id=...`
- `GET /v1/meta/chapters?subject_id=...&edition_id=...`
- `GET /v1/meta/knowledge-points?subject_id=...&keyword=...`

Pass the resolved `edition_id` to question or practice-page requests to filter
the whole textbook. Add `chapter_id` for a chapter, `knowledge_id` for one exact
linked knowledge point, `knowledge_tree_id` for one knowledge branch including
all descendants, or `knowledge_tree_ids` for multiple branches. Exact and tree
knowledge modes are alternatives; textbook, chapter, and the selected knowledge
mode may be combined. Never guess IDs from labels.

## One Skill, three delivery modes

Infer the mode when the request is clear. If it is ambiguous, ask only: `想怎么做？1. 在聊天里答 2. 打开练习页 3. 到网站组卷`.

- `1` or a request for one directly presented question: fetch the real database question into chat, omit the answer and explanation, and wait for the learner to respond.
- `2`, multiple questions, a quiz, or a one-off temporary worksheet: create a temporary practice page. This is the default for requests such as "出几道物理题".
- `3`, a saved or structured paper, later editing, public sharing, or printing: when the installed Skill is available, run its `builder` command with the resolved subject, grade, textbook edition, chapter, knowledge-tree IDs, question count, and original prompt. Return that handoff URL instead of a blank Builder. The website account is free and owns the persistent paper. It retains the unaccepted request through same-tab registration or sign-in, then asks the user to click “接收并创建新试卷”; opening the link alone never runs AI, creates an Agent thread on an old draft, or consumes question quota. Acceptance creates a separate paper and persists the validated context so a reload restores it. Direct integrations that cannot run the Skill may fall back to `https://tizhuang.qcscience.cc/builder` and must say that the user will need to reselect the conditions.

Create a temporary, user-specific practice page without pasting reconstructed questions or revealing answers:

```http
POST https://tizhuang.qcscience.cc/api/v1/trial/practice-pages
X-Trial-Token: <cached anonymous token>
Content-Type: application/json

{"title":"物理小练习","subject_id":8,"edition_id":123,"limit":5,"random_order":true}
```

Return the `page_url` for online answering. When the user asks for a printable or paper-style link, return `paper_url`; recipients can switch between online practice and paper view on the same share page. Both URLs expire together after 7 days, render the same database content and images, keep answers hidden until submission, and support compact A4 printing. For print requests, mention that the learner can select individual questions, enter name and class, and print the paper view. Fetch only the number of questions requested.

When the user asks for illustrated questions, set `"has_images": true`. If no matching illustrated question exists, report that exact limitation and offer to relax filters; never replace it with an invented diagram or conclude that the whole subject has no images from an unfiltered random sample.

Use `POST /v1/practice-pages` with `X-API-Key` only when a registered Key is already securely configured.

## Free account, referrals, and paper sharing

- Guest: 100 questions over 24 hours, temporary practice pages, and no saved paper library.
- Registered: still free, initially 200 questions per day, persistent papers, public sharing, and print access.
- Each genuine successful invitation adds +100 questions per day until 1000, +50 until 2000, then +20, with a current hard cap of 3000 questions per day.
- After registration succeeds, make the welcome explicit: reveal the initial 200-question daily allowance, then offer the referral link as the optional next action. At the first tier the next genuine successful registration adds +100 per day; copying the link alone does not award quota.
- Do not rotate anonymous identities, create fake accounts, or describe any plan as unlimited.

The saved-paper owner may create an immutable public snapshot. The safe default is questions only with a visible watermark. For a newly created link, the owner may explicitly choose to include stored standard answers (`answer`/`answer_html`, including compound subquestions) and/or remove the watermark. Analyses, explanations, and solution fields always remain private. These choices are fixed to that link; changing them creates a new share instead of mutating an existing URL. Printing requires a signed-in account and server-side authorization for every setting. This is a product gate rather than DRM; do not promise that screenshots or browser tools are impossible.

## Fidelity contract

The backend is the only source of truth. Never invent, rewrite, reorder, summarize, translate, or "correct" question text, options, option letters, answers, or explanations. Never recompute an answer. If a request fails or fields appear incomplete, report that limitation; do not fill gaps with plausible educational content.

If the user explicitly requests raw questions in chat, fetch them from `/v1/trial/questions` or `/v1/questions`, preserve all fields verbatim, include each database question ID, keep compound questions together, and hide answers until the user responds unless answers were explicitly requested.

Use each item's `has_images` and absolute `image_urls` fields instead of guessing from text. Never conclude that the whole subject has no images from a small random sample; say only that the returned sample has none.

## Registered credentials

When registration is appropriate, direct the user to `https://tizhuang.qcscience.cc/account?mode=register`. The user should create and store their own password and Key. Never ask them to paste either into ordinary chat. Store a Key only in a platform secret or environment variable named `QUESTION_SERVICE_LICENSE`, send it only as the `X-API-Key` header, and never echo it in output or logs.

For anonymous `429`, stop and provide the response's registration URL. Do not create another anonymous identity. Do not require registration before that point unless the learner asks for history, higher quota, or cross-device access.

Before a large licensed request, call `/v1/quota`. Stop on authorization or quota failures rather than retrying automatically.