@kukonce/dsh-loomy 0.0.0-stage → 0.3.1

package/cordis.patch.yml

@@ -0,0 +1,28 @@
+# dsh-loomy bundle patch.
+#
+# One Host line. The plugin registers one llm provider route per account itself:
+#
+#   @loomy/dsh-loomy/<id>
+#
+# Accounts come from the plugin's own table ($DSH_HOME/dsh-loomy/accounts.json), which
+# /loomy login and /loomy import write. The first start adopts an existing Loomy desktop
+# login if it finds one, so a fresh install usually needs no configuration at all.
+#
+# Optional: declare the accounts up front, which only affects the display order and the
+# labels shown in the model picker. The id is what the provider route is built from, so
+# it must match the characters a route and a file name tolerate: lowercase letters,
+# digits and dashes, starting with a letter.
+#
+# accounts:
+#   - id: loomy
+#     label: 我的 Loomy
+#   - id: work
+#     label: 工作号
+#
+# Login:  /loomy import            adopt the Loomy desktop app's existing session
+#         /loomy login <手机号>     sign in with an SMS code
+
+- insert:
+    - id: loomy
+      name: '@loomy/dsh-loomy'
+      config: {}

package/docs/PUBLISHING.md

@@ -0,0 +1,87 @@
+# 发布到社区
+
+目标列表：[awesome-dsh-plugin](https://awesome-dsh-plugin.com)（当前收录 10365 个插件）。
+
+## 官方要求核对
+
+| 要求 | 本插件 | 说明 |
+|---|---|---|
+| `package.json` 声明 `dsh.bundle.patch` | ✅ | 已声明，且 `cordis.patch.yml` 在仓库根 |
+| 有真实可用代码 | ✅ | 30 个源文件，47 项协议自检全通过 |
+| 仓库创建满 1 天 | ⬜ | 你自己建仓后计时 |
+| 加 `dsh-plugin` topic | ⬜ | GitHub 仓库设置里加 |
+| 活跃维护 | ⬜ | 持续更新即可 |
+| 描述属实、无营销词 | ✅ | 见 `docs/community-entry.yml` |
+| 分类准确 | ✅ | `model`（模型提供方） |
+
+> 官方明说：**最常见的被拒原因是只声明了 `dsh.client` 而没有 `dsh.bundle`** —— 那样无法安装。
+> 本插件两者都有，这条不会踩。
+
+## 第 1 步：建 GitHub 仓库
+
+```sh
+cd ~/.dsh/local-plugins/dsh-loomy
+git init
+git add .
+git commit -m "dsh-loomy 0.1.0"
+git branch -M main
+git remote add origin https://github.com/kukonce/dsh-loomy.git
+git push -u origin main
+```
+
+**提交前务必确认**：`.gitignore` 已排除运行时状态（`accounts.json` 里有你的登录凭证）。
+`.gitignore` 已经写好，但推完去 GitHub 网页上看一眼文件列表，确认那个文件不在。
+
+然后：
+- 仓库 **Settings → Topics** 加 `dsh-plugin`
+- 把 `package.json` 里 4 处 `kukonce` 换成你的用户名
+
+## 第 2 步：发布到 npm（可选但推荐）
+
+列表里 5123 个插件是 npm 包，5242 个是 GitHub 直装。**只发 GitHub 也能收录**，但 npm 的安装命令更短、有版本管理。
+
+```sh
+npm login
+npm publish --access public
+```
+
+包名 `@kukonce/dsh-loomy` 用 npm 用户 `kukonce` 的个人 scope 发布；
+例如 `@你的用户名/dsh-loomy`，同时同步修改 `cordis.patch.yml` 里的 `name`。
+
+## 第 3 步：提交收录 PR
+
+在 `awesome-dsh-plugin` 仓库新建**一个文件**：
+
+    路径：data/plugins/kukonce__dsh-loomy.yml
+    内容：docs/community-entry.yml（改掉 kukonce）
+
+就这一个文件，不要手工编辑 README（它们由脚本生成）。
+
+## 第 4 步：其他渠道
+
+- 给 GitHub 仓库打 `dsh-plugin` topic 后，会自动出现在
+  [github.com/topics/dsh-plugin](https://github.com/topics/dsh-plugin)
+- 装 `dsh-market` 插件的用户可以在「插件 → 发现」里直接搜到（它索引同一份
+  `dsh-plugin-catalog`）
+
+## 发布前最后检查
+
+```sh
+# 1. 协议自检（会花约 1 次免费模型调用，不扣积分）
+npm run verify
+
+# 2. 确认没有被忽略的敏感文件混进提交
+git status --ignored | grep -E 'accounts|expired|catalog|daily-grant'
+```
+
+## 已知的、要在 PR 描述里主动说明的点
+
+诚实说明这些，比被 reviewer 发现要好：
+
+1. **非官方集成** —— 接口是逆官方客户端得到的，无公开文档。
+2. **内嵌客户端凭据** —— `src/core/endpoints.js` 里有 iFlytek CAccount 的 app key
+   （随每个 Loomy 安装包以混淆形式分发，标识的是客户端应用而非用户，没有用户手机号+验证码无法使用）。
+   这是为了让插件开箱即用，且可用环境变量覆盖。
+3. **会话明文存储** —— `accounts.json` 存 bearer session，权限 0600。Loomy 的 session
+   本身不加密，没有可用的加密层。
+4. **生图模型不支持对话** —— 目录里有 3 个 `type: image` 的模型，只列在选择器外并标注。

package/docs/community-entry.yml

@@ -0,0 +1,21 @@
+# Ready-to-submit entry for awesome-dsh-plugin.
+#
+# Target path in that repo:  data/plugins/<owner>__dsh-loomy.yml
+# One file is the whole submission — the READMEs are generated from these.
+#
+# Two placeholders must be replaced with your own values before opening the PR:
+#   kukonce  -> your GitHub username / org (appears 3 times)
+#
+# The description is a claim that reviewers check against the code, so it states only
+# what the plugin demonstrably does. Category `model` is the one that matches: this is a
+# model provider, not a UI/usage/memory plugin.
+
+url: https://github.com/kukonce/dsh-loomy
+name: kukonce/dsh-loomy
+category: model
+description:
+  en: 'Loomy (iFlytek) model provider: SMS or desktop-session login, live per-account model catalog, and automatic renewal of the daily 5000 free credits.'
+  zh: 'Loomy（讯飞）模型提供方：手机验证码或桌面端登录态登录，按账号实时拉取模型目录，并自动续领每日赠送的 5000 积分。'
+# Optional: point this at a raster image committed to your repo. Omit and the list falls
+# back to your GitHub avatar.
+# icon: https://raw.githubusercontent.com/kukonce/dsh-loomy/main/icon.png

package/docs/models.md

@@ -0,0 +1,74 @@
+# Loomy model catalog
+
+Live snapshot of `GET /api/v1/models`, read from a real account on 2026-11-11
+(catalog version `sha256:7c15cde8…1a8394`, `reasoning_enabled: true`).
+
+This file is a **record**, not a source of truth. The plugin never reads it — it
+calls the endpoint and caches the answer (`src/account/models.js`). The list is
+per-account: a model an account may not use is simply absent from its response,
+so an id missing here means nothing about whether another account gets it.
+
+## Chat models
+
+| id | display name | ctx | max out | reasoning | vision | tools | input modalities |
+|---|---|---|---|---|---|---|---|
+| `spark-x2.6` | Spark-X2.6 正式版(限时免费)(x0.0) | 1 048 576 | 131 072 | yes | no | yes | text |
+| `DeepSeek-V4.1-Flash` | DeepSeek V4.1 Flash(x2.0) | 1 048 576 | 384 000 | yes | yes | yes | text, image |
+| `GLM-5.3-Flash` | GLM 5.3 Flash(x0.8) | 1 048 576 | 131 072 | yes | yes | yes | text, image, video |
+| `qwen3.8-flash` | qwen 3.8 flash（x0.8） | 1 000 000 | 131 072 | yes | yes | yes | text, image, video |
+| `mimo-v2.5` | MiMo V2.5（x3.3） | 1 048 576 | 131 072 | yes | yes | yes | text, audio, image, video |
+| `auto` | 自动 · 均衡 | — | — | — | — | — | (undeclared) |
+
+All five metered chat models plus `auto` report `reasoning_efforts` of
+`["none","low","medium","high","xhigh"]` with `default_reasoning_effort: "low"`.
+`auto` declares no capabilities block at all — the router picks a concrete model
+per request and reports the chosen one in the stream's `model` field.
+
+`is_default_model` and `is_default_small_model` are both `true` on
+`spark-x2.6` and `false` everywhere else. That is why the plugin's default is
+spark-x2.6: it is what a fresh Loomy install would use.
+
+## Image models
+
+| id | display name | ctx | max out | streaming | input | output |
+|---|---|---|---|---|---|---|
+| `Hy-Image-3.5-preview` | Hy image 3.5 preview | 100 000 | — | no | text, image | image |
+| `doubao-seedream-5-lite` | Doubao seedream 5 lite | 128 000 | 131 072 | yes | text, image | image |
+| `qwen-image-3.0-pro` | qwen image 3.0 pro | — | — | no | text, image | image |
+
+These carry `type: "image"` and `output_modalities: ["image"]`, and all report
+`function_calling: false`, `reasoning: false`. **The plugin does not expose them
+as chat routes** — a DSH provider route must answer chat-completions semantics, and
+these answer an image-generation payload shape the harness has no surface for. They
+are listed here only so the catalog table is complete.
+
+## How the `(xN.N)` suffix maps to cost
+
+The parenthetical in the display name is the **points multiplier**: a turn on
+`DeepSeek-V4.1-Flash` costs about twice the token-derived base rate, `GLM-5.3-Flash`
+about 0.8×, and `spark-x2.6` is `x0.0` — free while it is labelled 限时免费
+(limited-time free). The multiplier is presentation only; nothing in the response
+exposes it as a field, so the plugin parses it out of `name` when it wants to warn
+about cost. `usage.points_consumed` on the final SSE chunk is the authoritative
+number for a given turn.
+
+Observed: a 140-token turn on `spark-x2.6` reported `points_consumed: 0`; routing
+the same turn through `auto` (which resolved to `GLM-5.3-Flash`) consumed 1 point.
+
+## Fields the plugin actually uses
+
+```
+id                     → the model id DSH sends in a chat request
+name                   → picker label
+context_length         → DSH context window
+max_output_tokens      → DSH output cap
+capabilities.reasoning → whether to send reasoning effort
+capabilities.function_calling → whether to offer tools
+capabilities.input_modalities  → whether to allow image attachments
+reasoning_efforts / default_reasoning_effort → effort picker and its default
+is_default_model       → which id to preselect
+```
+
+`capabilities.vision` is a redundant older field alongside
+`input_modalities.includes("image")`; both were consistent in every entry above,
+and the plugin prefers `input_modalities` because that is what the harness reads.

package/docs/protocol.md

@@ -0,0 +1,403 @@
+# Loomy upstream protocol reference
+
+Everything here was read off the wire against a real account on 2026-11-11, not
+guessed from documentation (Loomy publishes none). Where a claim is unverified it
+says so and is repeated in [Unknowns](#unknowns).
+
+This is an **unofficial** integration. No API key exists: auth is a session string
+issued to the desktop client after an SMS login. See [README](../README.md) for the
+risk statement.
+
+---
+
+## 1. Hosts
+
+| host | purpose | auth style |
+|---|---|---|
+| `https://account.xfinfr.com` | iFlytek CAccount: SMS send/verify, userinfo | HMAC-SHA1 request signing |
+| `https://loomyad.xunfei.cn` | points, models, onboarding, pet-work | envelope APIs, `token` header |
+| `https://loomyad.xunfei.cn/api/v1` | chat gateway (OpenAI-compatible) | `Authorization: Bearer` |
+| `https://loomy.xunfei.cn` | web pages (share, docs) | none |
+
+`account` and `loomyad` are separate services that happen to share a vendor. A
+session minted by CAccount is accepted by `loomyad` — that is the whole link.
+
+---
+
+## 2. Auth header matrix
+
+**This is the single most error-prone part of the protocol.** The two API families
+on the *same host* accept *different* headers, and the failure is a 200 OK carrying
+an error envelope, not a 401.
+
+| endpoint | `token: <session>` | `Authorization: Bearer <session>` | needs both? |
+|---|---|---|---|
+| `GET /api/v1/models` | **required** | ignored | no |
+| `POST /api/v1/points/first-login` | **required** | ignored | no |
+| `GET /api/v1/points/records` | **required** | ignored | no |
+| `GET /api/v2/points/records` | **required** | ignored | no |
+| `GET /api/v1/user/identity` | **required** | ignored | no |
+| `GET /api/v1/onboarding/tasks` | **required** | ignored | no |
+| `GET /api/v1/pet-work` | **required** | ignored | no |
+| `GET /api/v1/points/activation` | **required** | ignored | no |
+| `POST /api/v1/chat/completions` | **rejected** | **required** | no |
+
+Measured behaviour for `GET /api/v1/models`:
+
+```
+token only            -> 200, bare model list
+Authorization only    -> 200, {"code":"100002","desc":"缺少 token", ...}
+both                  -> 200, bare model list
+neither               -> 200, {"code":"100002","desc":"缺少 token", ...}
+```
+
+Measured behaviour for `POST /api/v1/chat/completions`:
+
+```
+token only            -> 200, application/json, {"code":"100002","desc":"缺少 token"}
+Authorization Bearer  -> 200, text/event-stream, real SSE stream
+both                  -> 200, text/event-stream, real SSE stream
+lowercase "bearer"    -> 200, {"code":"100002","desc":"缺少 token"}
+```
+
+Note the last row: the scheme name is matched **case-sensitively**. `bearer` fails
+where `Bearer` works. Sending `token` to the gateway is not a substitute for
+`Authorization`, and reproduces a misleading `缺少 token` ("missing token") message
+while a token is plainly present — the message means "missing *Authorization*".
+
+Headers that are **optional** in practice (dropped one at a time, request still
+streamed normally): `Accept`, `Content-Type`, `loomy-version`,
+`X-Loomy-Request-Purpose`, `traceparent`. They are sent anyway because the real
+client sends them and they carry points-attribution and tracing meaning.
+
+`traceparent` when sent follows W3C trace-context at version `00`:
+`00-<32 hex>-<16 hex>-01`. No observed validation of its contents.
+
+---
+
+## 3. Envelope shapes
+
+Two families, distinguishable by which key is present:
+
+```jsonc
+// family A — business envelope (nearly all /api/v1/* and /api/v2/*)
+{ "code": "000000", "desc": "成功", "trace_id": "<32 hex>", "data": { } }
+
+// family B — bare OpenAI-style list (GET /api/v1/models ONLY)
+{ "object": "list", "reasoning_enabled": true,
+  "reasoning_catalog_version": "sha256:<64 hex>", "data": [ ] }
+```
+
+**`code` is a string**, not a number. `"000000"` is success. An adapter that
+checks `code === 0` fails on every response.
+
+Family B has **no `code` field at all** — a parser that requires an envelope
+rejects the model list as malformed. That is the bug this note exists to prevent.
+
+### Envelope codes seen
+
+| code | meaning | recovery |
+|---|---|---|
+| `"000000"` | success | — |
+| `"100002"` | session dead / missing token | re-login |
+| `"020002"` | session invalid (seen in client source) | re-login |
+| others | business error, `desc` is user-facing Chinese | surface `desc` |
+
+`data` is sometimes `{}` on error rather than absent.
+
+---
+
+## 4. SSE event shapes (chat gateway)
+
+Request: `POST https://loomyad.xunfei.cn/api/v1/chat/completions`.
+
+Response is `text/event-stream`; each event is one `data: <json>` line followed by
+a blank line. The stream ends with the literal sentinel `data: [DONE]`.
+
+### Event sequence observed (tool-calling turn)
+
+```
+1. data: {"id":"cht000d5341@dx1a1c...","object":"chat.completion.chunk",
+          "created":1794362374,"model":"spark-x2.6",
+          "choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
+
+2..n data: {...,"choices":[{"index":0,"delta":{"reasoning_content":"The"},"finish_reason":null}]}
+      ...  {"delta":{"reasoning_content":" user is"}} ...
+
+k. data: {...,"choices":[{"index":0,"delta":{"content":"..."},"finish_reason":null}]}
+
+m. data: {...,"choices":[{"index":0,"delta":{"tool_calls":[
+          {"index":0,"id":"call_3eb7ceb997564af380b3d52f","type":"function",
+           "function":{"name":"get_weather","arguments":""}}]},"finish_reason":null}]}
+
+m+1.. data: {...,"delta":{"tool_calls":[{"index":0,"id":"","type":"function",
+            "function":{"name":"","arguments":"{\"city\":\"Bei"}}]}}
+
+last. data: {...,"choices":[{"index":0,"delta":{},"finish_reason":"tool_calls"}]}
+
+final. data: {...,"choices":[],
+              "usage":{"prompt_tokens":92,"completion_tokens":48,
+                       "total_tokens":140,"points_consumed":0}}
+
+data: [DONE]
+```
+
+Rules an adapter must follow:
+
+- **`id` and `name` on `tool_calls` deltas are sent once, on the first fragment.**
+  Follow-up fragments carry `"id":""` and `"name":""` and must be treated as
+  continuations of the same `index`, not as new calls. This differs from some
+  OpenAI-compatible servers that repeat the id on every fragment.
+- **`arguments` arrives as a stream of string fragments** that must be
+  concatenated in order; it is not valid JSON until the stream ends.
+- The **usage chunk has `"choices": []`** — an adapter that indexes `choices[0]`
+  unguarded throws here, on the last event of every stream.
+- `usage.points_consumed` is Loomy's own meter and has no OpenAI equivalent.
+  It is the only per-turn cost signal.
+- `reasoning_content` is a separate delta key from `content`, and both appear on
+  the same model. It maps to the harness's reasoning/thinking channel.
+- No `event:` field, no `retry:` field, no SSE comments observed.
+
+---
+
+## 5. Non-streaming and empty-input behaviour
+
+| probe | result |
+|---|---|
+| `stream: false` | **works** — answers one `application/json` `chat.completion` object with `choices[0].message.{content,reasoning_content}` and a `usage` block |
+| `messages: []` | **400** `{"error":{"message":"messages 不能为空","type":"invalid_request_error","param":"messages","code":400,"metadata":{"provider_name":"loomy"}}}` |
+| no `messages` key | same 400 as above |
+| no `model` key | **200**, silently defaults to `spark-x2.6` |
+| `model: "gpt-4o"` (unknown) | **200**, silently falls back to `spark-x2.6` |
+| `model: ""` | **200**, silently falls back to `spark-x2.6` |
+| `model: "auto"` | **200**, router picks a concrete model (`GLM-5.3-Flash` here) and reports it in `model` |
+| malformed JSON body | 400 `{"error":{"message":"请求参数错误","param":null,...}}` |
+| wrong `Content-Type` (`text/plain`) | still accepted, streams normally |
+
+**There is no free probe via an empty `messages` array** — unlike WorkBuddy, which
+accepts one. Loomy rejects it with a 400 before doing any work. The equivalent
+free probe is a one-token turn on a `x0.0` model: `spark-x2.6` is currently
+限时免费 and reports `points_consumed: 0`.
+
+> **Trap:** an unknown model id does *not* error. It silently answers as
+> `spark-x2.6`. A typo'd or removed model therefore looks like a working call
+> returning a different model than requested — check the `model` field of the
+> stream's first chunk, not the status code. The plugin validates the id against
+> the live catalog rather than trusting the gateway to reject it.
+
+---
+
+## 6. The daily 5000 mechanism — what actually refreshes it
+
+### What the numbers are
+
+`POST /api/v1/points/first-login` returns the full balance picture:
+
+```json
+{ "alreadyProcessed": true,
+  "currentBalance": 10500,
+  "permanentBalance": 5500,
+  "dailyBalance": 5000,
+  "dailyQuota": 5000,
+  "dailyConsumed": 0,
+  "dailyCycleDate": "2026-11-11",
+  "registerReward": 0, "inviteeReward": 0, "inviterReward": 0,
+  "invitationCodes": [ { "inviteCode": "6W9AD9", "usedCount": 0,
+                         "maxUses": 20, "status": "active" } ] }
+```
+
+`currentBalance === permanentBalance + dailyBalance` is the arithmetic identity
+(5500 + 5000 = 10500). The metering has two pots: **每日赠送 (daily)**, capped at
+`dailyQuota` = 5000 and consumed first, and **长期/永久 (permanent)**, which is
+registration reward + onboarding points + redemption codes and does not expire daily.
+
+### What does *not* refresh it
+
+`GET /api/v1/points/records` and `GET /api/v2/points/records` are pure reads. The
+daily balance did not change across repeated calls, and no ledger entry was
+appended. **Reading the records does not renew the daily pot.**
+
+### What does
+
+`POST /api/v1/points/first-login` with body `{}`:
+
+- is **idempotent per `dailyCycleDate`** — two consecutive calls both answered
+  `alreadyProcessed: true` with an unchanged `currentBalance`, and appended
+  nothing to the ledger;
+- is **the call the official client makes exactly on login**, not on a timer.
+  In the shipped renderer bundle (`dist/assets/main-*.js`) the wrapper
+  `completeFirstLogin` has exactly four call sites: two in the SMS-login success
+  handler, one in the WeChat-login success handler, and one fallback when the
+  invitation-code list comes back empty. There is no startup timer, no midnight
+  timer, no interval;
+- is documented by the client's own UI copy, verbatim:
+  > 每日赠送积分会在你每日登录后自动刷新为 5000。
+
+  ("Daily gift points are automatically refreshed to 5000 after your daily login.")
+
+So the mechanism is: **the daily pot is reset by a server-side per-day ledger keyed
+on `dailyCycleDate`, and `POST /points/first-login` is the client's idempotent
+"begin today's cycle" signal.** Repeated calls within the same day are free and
+harmless; that is precisely what makes it safe to call on every startup.
+
+### What this plugin does
+
+- **On startup**, for each account: `POST /api/v1/points/first-login` (reason `启动`).
+- **At local midnight**, for each account: the same call (reason `午夜`), scheduled
+  by `msUntilNextMidnight()`.
+- **On panel refresh**, the same call — it doubles as the balance read because it
+  is the only endpoint returning all four numbers plus `dailyConsumed` at once.
+- A per-account ledger (`daily-grant.json`) records the last attempt's day and
+  outcome so a restart inside the same day does not re-ask; the panel's manual
+  button forces it.
+
+Whether the pot would eventually refresh *without* the call is **not something I
+could observe** — the test account was created on the observation day, so no
+rollover ever occurred. See [Unknowns](#unknowns). Calling it is correct either
+way: it is the client's own mechanism and it is free.
+
+---
+
+## 7. Endpoint inventory
+
+| method | path | envelope | notes |
+|---|---|---|---|
+| GET | `/api/v1/models` | **bare list** | per-account catalog; see models.md |
+| POST | `/api/v1/points/first-login` | yes | daily claim + full balance |
+| GET | `/api/v1/points/records` | yes | `?pageNo&pageSize&recordType=all`; returns `balance`(=permanent), `dailyBalance`, `availableBalance`(=total), `total`, `list` |
+| GET | `/api/v2/points/records` | yes | `?pageNo&pageSize&direction=credit|debit&granularity`; `list[].points` + `source` instead of `pointsActual` |
+| GET | `/api/v1/user/identity` | yes | `{isInternal, currentTeamId, teams}` |
+| GET | `/api/v1/onboarding/tasks` | yes | `{tasks:{key:bool}, earned, total:10000}` |
+| POST | `/api/v1/onboarding/tasks/complete` | yes | `{key}`; idempotent, returns `alreadyCompleted` + `balance` |
+| GET | `/api/v1/pet-work` | yes | daily pet-work snapshot |
+| GET | `/api/v1/points/activation` | yes | `{activated: bool}` — redemption-code state |
+| GET | `/api/v1/invitation-codes` | yes | referrer codes |
+| POST | `/api/v1/chat/completions` | **SSE / plain JSON** | the gateway |
+
+### `v1` vs `v2` records — a real shape difference
+
+```jsonc
+// v1 record     {ledgerId, description, direction, createdAt, pointsActual,
+//                balanceBefore, balanceAfter, dailyCycleDate, modelName, consumeSource}
+// v2 record     {ledgerId, description, direction, createdAt, points, source}
+```
+
+The **point value lives at a different key** (`pointsActual` vs `points`), and
+`balanceBefore`/`balanceAfter`/`dailyCycleDate` exist only in v1. v2 additionally
+filters by `direction`. The plugin's `queryRecords` uses v2 and reads `points`.
+
+Also note the top-level `balance` means different things: in **v1 records** it is
+the permanent pot (5500); in **first-login** the comparable field is
+`permanentBalance` (5500) while `currentBalance` is the total (10500). Mixing those
+two up double-counts the daily pot.
+
+### Onboarding keys (one-time pool, 10 000 total)
+
+`first_message` 500 · `pick_skill` 1000 · `generate_ppt` 1500 ·
+`set_schedule` 1000 · `install_skill` 1500 · `configure_remote` 1000 ·
+`create_soul` 1500 · `share_soul` 2000
+
+Claiming these is **not** automatic in this plugin: they are a one-time resource
+the user may want to spend deliberately, and auto-claiming on someone's behalf
+would burn them without consent.
+
+---
+
+## 8. Error table
+
+Every error below was produced by a live request.
+
+| trigger | HTTP | Content-Type | body |
+|---|---|---|---|
+| bad/expired token, envelope endpoint | **200** | `application/json` | `{"code":"100002","desc":"登录已失效，请重新登录","trace_id":"…","data":{}}` |
+| no `token` header, envelope endpoint | **200** | `application/json` | `{"code":"100002","desc":"缺少 token",…}` |
+| no `Authorization`, chat endpoint | **200** | `application/json` | `{"code":"100002","desc":"缺少 token",…}` — *not* an SSE error event |
+| chat with `messages: []` | **400** | `application/json` | `{"error":{"message":"messages 不能为空","type":"invalid_request_error","param":"messages","code":400,"metadata":{"provider_name":"loomy"}}}` |
+| chat with malformed JSON | **400** | `application/json` | `{"error":{"message":"请求参数错误","type":"invalid_request_error","param":null,"code":400,"metadata":{"provider_name":"loomy"}}}` |
+| unknown model id | **200** | `text/event-stream` | **no error** — silently answers as `spark-x2.6` |
+| rate limited | — | — | **never observed** |
+
+### What this means for retry logic
+
+- **HTTP status is not a reliable failure signal.** Auth failures arrive as
+  `200 OK`. Every response must be inspected: a model-list answer is valid only if
+  it has a `data` array; an envelope answer is valid only if `code === "000000"`;
+  a chat answer is valid only if `Content-Type` starts with `text/event-stream`
+  (or is a well-formed `chat.completion` when non-streaming).
+- **There is no SSE error event.** Auth and validation failures are answered as
+  plain JSON with a non-SSE `Content-Type` before the stream opens. An adapter
+  that only parses `data:` lines will see an empty stream and hang or return
+  nothing. Check the content type first.
+- No `Retry-After` was ever sent, and no error was retryable in the observed set —
+  all are terminal (bad credentials / bad request). The plugin does not retry auth
+  or validation errors; it surfaces them.
+
+---
+
+## 9. Rate limiting and cost signals
+
+**No rate-limit headers exist on this API.** Responses carried only:
+`server: xunfei`, `date`, `content-type`, `connection`, and either
+`content-length` or `transfer-encoding: chunked` (plus `cache-control: no-cache`
+on SSE). No `x-ratelimit-*`, no `retry-after`, no points headers — across every
+endpoint and both auth states.
+
+The only cost signal is therefore **in-band**:
+
+- `usage.points_consumed` on the final SSE chunk (streaming) or the `usage` block
+  (non-streaming) — the authoritative per-turn cost;
+- `dailyConsumed` / `dailyBalance` on `first-login` — the running daily total;
+- the `(xN.N)` multiplier in the model's display `name` — advisory, from the
+  catalog, not from the response.
+
+Because there is no rate-limit header to react to, the plugin meters itself:
+it tracks `points_consumed` per turn and refuses to spend when
+`dailyBalance + permanentBalance` is exhausted rather than discovering it via 4xx.
+
+---
+
+## 10. Session lifetime
+
+The desktop session is a 32-character opaque string with no expiry encoded in it
+and no refresh token in the observed flows. The desktop client is re-authenticated
+by the user logging in again. `auth-session.json` on disk carries
+`{session, userid, phone, updatedAt}` and is what the plugin's "import desktop
+login" button adopts.
+
+A dead session is detected by envelope `code` `100002`/`020002`, never by HTTP
+status. There is **no documented TTL** — see Unknowns.
+
+---
+
+## Unknowns
+
+Honest list of what this survey could not establish, with why:
+
+1. **Whether the daily pot refreshes without any call.** The test account was
+   created on the observation day (`dailyCycleDate` = 2026-11-11, first ledger
+   entry same day), so no date rollover ever occurred during testing. I cannot
+   distinguish "the `first-login` call performs the reset" from "the server resets
+   lazily at rollover and `first-login` merely reports it". The plugin calls it
+   anyway: the official client does it on login, it is idempotent, and it is free.
+2. **Session TTL / absolute expiry.** No expiry field in the session or any
+   response. Only the failure mode (`100002`) is known.
+3. **Rate limits.** None observed and no headers advertise them. Whether limits
+   exist at higher request rates is untested — I deliberately did not hammer the
+   API with the user's credentials.
+4. **Exact points formula.** How `prompt_tokens`/`completion_tokens` translate to
+   `points_consumed` under a given `(xN.N)` multiplier is not derivable from the
+   responses. Observed samples: 140 tokens on `spark-x2.6` → 0 points; one short
+   turn on `GLM-5.3-Flash` → 1 point. Too few points to model.
+5. **Behaviour of image models via the chat gateway.** `Hy-Image-3.5-preview` and
+   friends declare `type: "image"` and `output_modalities: ["image"]`. Whether
+   `/chat/completions` services them at all, or they require a separate
+   images endpoint I did not find, is untested — testing would have spent the
+   user's points on image generation.
+6. **Multi-account rate interaction.** Whether several sessions on one machine or
+   IP share a limit is untested.
+7. **`reasoning_effort` semantics.** Every effort value was accepted in the request
+   shape, but whether `none` truly disables reasoning (vs. still emitting
+   `reasoning_content`) was not verified per-value on every model.
+8. **Server-side model retirement.** Because an unknown id silently falls back
+   instead of erroring, there is no way to detect that a model was retired except
+   by comparing the live catalog — which is exactly why the plugin does.