dsh-plugin-maoxuan-pet 0.0.0-stage → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# CHANGELOG
+
+## 0.2.1 — 2026-11-01
+
+上架插件市场后的首个维护版：图标重做 + 整包瘦身 + 打包门禁补强。
+
+### 图标
+- 包内 `assets/icon.svg` 换成「红皮书」造型：米白底、深红书壳、烫金五角星与书名条；按插件面板卡片实际 36px 校过，缩到 36px 仍能读成一本红皮书。
+- 新增 `assets/icon-256.png`（256×256 RGBA，17 KB），给 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 条目的 `icon:` 用——市场只收 GitHub 托管位图，不收 SVG。
+
+### 体积
+- 四帧立绘 640×1348 → 256×539（UI 展示高 132px，2x 屏幕足够）：4 张合计 **2.96 MB → 603 KB**。
+- `npm pack` 整包 **4.2 MB → 约 1.2 MB**（59 files），安装与首屏都更快；README / 市场条目用的大图 `docs/screenshot-hero.png` 保留。
+
+### 打包与发布门禁
+- `scripts/audit-corpus-coverage.mjs` 迁到 `tools/`：`scripts/` 是开发脚本，不该进 npm 包；全局开源契约检查此前因此 1 项 FAIL，现在是 0 FAIL / 1 WARN（WARN 已由下一条解决）。
+- 新增 `prepublishOnly`：发布前自动跑 `verify/smoke.mjs` + `verify/contract.mjs`，防手滑发坏版本。
+- `scripts/post-publish-check.mjs`：市场索引有 3.3 MB，超时从 60s 提到 180s（可用 `MARKET_TIMEOUT_MS` 覆盖），慢网下 `--strict` 不再误红。
+- 仓库根新增 `screenshots.json`（`["docs/screenshot-hero.png"]`），喂给 dsh-market 详情页的 AppStore 式截图；以后换图只需往本仓 push，不用再来提 PR。
+
+### 文档
+- 新增英文 README（`README.en.md`），中文 README 顶部加英文入口。
+- README 的资产尺寸、审计脚本路径同步更新；`assets/PROVENANCE.md` 记录交付尺寸与图标改版。
+
+## 0.2.0 — 2026-11-01
+
+首个公开版本。
+
+### 宠物与气泡
+- 悬浮宠物「鲸鱼娘·小毛」：4 帧立绘（idle / talk / blink / read），Web `shell.overlay` 渲染，可拖拽、位置本地记忆。
+- 红皮书气泡：深红封面 + 烫金书脊 + 米白内文；卡片绝对定位在宠物左侧，开合不移动宠物（宠物贴左边缘时自动翻到右侧）。
+- 打开即已读：卡片显示的那一刻才标已读，右上角未读数随之消失；正在读的那条会被钉住，不会被新数据替换。
+- 全部已读后仍停在上一次产出，`‹ ›` 可往回翻历史。
+- 定时生成的新气泡自动弹出；手动关闭后不会自己重开。
+- `收起` / `再督促` 为纯文字按钮；滚动条为烫金滑块 + 深红轨道。
+
+### 内容
+- 单条气泡 = 引文 + 一句督促 + 启示，**合计 ≤200 字**（`fitLesson` 保证）。
+- 三种取材模板轮转：`quote` 金句 / `excerpt` 文章节选（逐字整句）/ `summary` 小毛概括；游标 `templateCursor` 落盘，不因历史条数封顶而卡住。
+- 启示落点六选一：客户 / 项目 / 组织 / 现金流 / 决策 / 自律；「人事」已按用户裁决改名为「组织」，旧状态文件读取时自动迁移。
+- 反编造：`quote`/`excerpt` 必须逐字命中语料全文（`isVerbatim`，去空白兜底），否则降级为 `summary`；`summary` 永不回退成篇名。
+- 模型复述原文的 `pua` 会被识别（≥8 字公共串）并整条丢弃。
+- 无凭据 / 超时 / 非 JSON 时降级为本地摘录，UI 在页脚标注「离线摘录」，不冒充模型生成。
+
+### Host
+- 5 条同源路由：`state` / `generate` / `dismiss` / `asset` / `corpus`；状态文件原子写（`.tmp` + `rename`）。
+- 每小时生成一次，支持 `quietHours`、`everySeconds`、`maxBubbles`、`headless` 开关与子进程超时；并发手动触发时同步抢占 in-flight 位。
+- 运行时把 `corpus/` 注册为 `maoxuan-vademecum` skill，preset `maoxuan-pet`（毛选创业参谋）= persona + skill + 工具。
+
+### 语料与素材
+- 33 篇毛选全文（中文马克思主义文库公开电子文本），`corpus/index.json` 记录 `sourceUrl` 与版本；`verified: true` 的条目才参与轮转。
+- 语料覆盖审计：`node scripts/audit-corpus-coverage.mjs`（金句逐字命中 33/33，节选可用 32/33）。
+
+### 验证
+- `verify/smoke.mjs`（24 项）、`verify/contract.mjs`（38 项）、`verify/host.test.mjs`（18 项）：不联网、不起子进程、不花模型调用。
+- 真实环境做过 headless 生成 + headless Chrome/CDP 页面断言（宠物坐标不变、卡片在左、chip 暖色、按钮无盒、已读徽标消失、无未读仍有内容）。
+
+### 已知限制
+- 只支持 Web 界面（`dsh.client.platform: web`）。
+- 定时器只在 `dsh web` 进程存活时运行，进程停掉不补跑。
+- 每次生成是独立的 headless 会话，不共享上下文；用最近 6 条督促避免重复。

package/LICENSE

@@ -0,0 +1,37 @@
+MIT License
+
+Copyright (c) 2026 dsh-maoxuan-pet contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Third-party content notice:
+
+`corpus/` bundles public electronic texts of Mao Zedong's writings collected
+from the public archive 中文马克思主义文库 (https://www.marxists.org/chinese/).
+Copyright in those texts belongs to their respective rights holders; they are
+included here only for personal study and research, with source URLs recorded
+in `corpus/index.json` and `corpus/README.md`. This project claims no rights in
+them and does not sell them.
+
+The pet artwork in `assets/` is AI-generated fan art of DeepSeek's unofficial
+"whale girl" community mascot, dressed in a period Red Army uniform. It is not
+official DeepSeek material and is not endorsed by DeepSeek. See
+`assets/PROVENANCE.md`.

package/NOTICE

@@ -0,0 +1,29 @@
+# NOTICE
+
+dsh-plugin-maoxuan-pet
+Copyright (c) 2026 Yuna and contributors
+
+本文件说明本仓库里**不属于 MIT 许可**的内容。代码本体见 [LICENSE](LICENSE)。
+
+## 1. 内置毛选语料（`corpus/`）
+
+- 来源：[中文马克思主义文库 · 毛泽东](https://www.marxists.org/chinese/maozedong/index.htm)，抓取日期 2026-10-31，共 33 篇（`corpus/index.json` 记录每篇的 `sourceUrl`）。
+- 著作权归原作者及原出版方所有。本项目对正文的收录**仅用于个人学习、研究**，不构成再出版、发行或商业授权。
+- 若需在商业场景公开引用原文，请自行核对正式出版物并取得授权。
+- **权利人若不希望文本随本包分发**：删除 `corpus/articles/` 即可；此时 `quote`/`excerpt` 模板会安全降级为 `summary`（插件不会编造原文），也可运行 `node scripts/fetch-corpus.mjs` 自行重新获取。
+- 语料不参与 `npm` 之外的再分发声明，也不代表本项目对原文主张任何权利。
+
+## 2. 立绘与图标（`assets/`）
+
+- `pet-idle.png` / `pet-talk.png` / `pet-blink.png` / `pet-read.png`：AI 生成（gpt-image-2，2026-10-31），形象为民间同人设定「鲸鱼娘·小毛」（红军制服、抱《毛泽东选集》）。
+  生成过程与 prompt 记录见 [assets/PROVENANCE.md](assets/PROVENANCE.md)。
+- `icon.svg`：手写 SVG（纯几何图形）。
+- 与 DeepSeek 官方无任何隶属或背书关系。
+
+## 3. 名称与立场
+
+本插件是一个桌宠 / 阅读督促工具，把毛选当作**产品与创业方法论**的文本来源。它不代表 DeepSeek、毛泽东著作出版方或任何政治组织的立场，也不作政治宣传。
+
+## 4. 第三方依赖
+
+运行时只依赖宿主 `@deepseek-ai/dsh`（peer dependency）与 Node 内置模块；`verify/` 与 `scripts/` 不引入任何第三方包。

package/README.en.md

@@ -0,0 +1,94 @@
+# dsh-maoxuan-pet · Xiao Mao, the whale-girl desktop pet
+
+[![verify](https://github.com/yuna78/dsh-maoxuan-pet/actions/workflows/verify.yml/badge.svg)](https://github.com/yuna78/dsh-maoxuan-pet/actions/workflows/verify.yml) [![npm](https://img.shields.io/npm/v/dsh-plugin-maoxuan-pet.svg)](https://www.npmjs.com/package/dsh-plugin-maoxuan-pet)
+
+A floating pet living in the DeepSeek Harness (dsh) web shell. Every hour she reads one
+essay from *Selected Works of Mao Zedong*, turns it into **one ≤200-character nudge** for a
+founder — a verbatim quote or excerpt, one line of pressure in her own voice, and one rule
+with a way to verify it — and shows it in a red-book speech bubble.
+
+![bubble](docs/screenshot-hero.png)
+
+> 中文说明见 [README.md](README.md)。
+
+## What it does
+
+| Piece | Behaviour |
+|---|---|
+| Pet | 4 sprite frames (idle / talk / blink / read), draggable, position remembered |
+| Bubble | dark-red "book cover" with a gold spine; anchored to the **left** of the pet, so the pet never moves; `收起` / `再督促` are text-only buttons |
+| Reading | opening the card marks that bubble read — the unread badge disappears; the bubble you are reading never gets swapped out |
+| History | `‹ ›` walks back through previous bubbles; with nothing unread you still see the last one produced |
+| Timing | one generation per hour (`everySeconds`), quiet hours, `maxBubbles` history cap |
+| Preset | `maoxuan-pet` — a "Selected Works startup advisor" preset with the bundled corpus registered as the `maoxuan-vademecum` skill |
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-plugin-maoxuan-pet
+# restart dsh web (Ctrl+C, then `dsh web` again), reload the page
+```
+
+Requirements: dsh `>=0.2.1-rc.2 <0.3.0`, Node `^22.19.0 || >=24.0.0`. Web shell only.
+
+## How a bubble is produced
+
+```
+everySeconds → pick next verified essay → template rotates quote/excerpt/summary
+             → spawn `dsh --profile headless --json "<prompt>"` (60s-ish, one model call)
+             → parse JSON {pua, lesson, axis, gist}
+             → quote/excerpt must match the corpus verbatim, otherwise fall back to summary
+             → fitLesson(): cite + pua + lesson ≤ 200 chars
+             → persist to $DSH_HOME/storages/dsh-maoxuan-pet.json (atomic write)
+             → client polls /api/dsh-maoxuan-pet.state every 20s
+```
+
+If the model call fails (no credentials, timeout, non-JSON), the plugin degrades to a **local
+excerpt** and labels it `离线摘录` in the footer — it never invents a quote.
+
+- Templates: `quote` (golden line) / `excerpt` (verbatim whole sentences) / `summary` (her own gist).
+- Lesson axes: 客户 customers / 项目 projects / 组织 organisation / 现金流 cash flow / 决策 decisions / 自律 self-discipline.
+- The 200-character cap is a hard invariant, not a suggestion: `fitLesson()` shrinks the lesson,
+  never the quote.
+
+## Config
+
+```yaml
+- id: dsh-maoxuan-pet
+  config:
+    enabled: true
+    everySeconds: 3600      # hourly
+    firstDelaySeconds: 90
+    quietHours: [2, 8]      # no pings between 02:00 and 08:00 local time
+    maxBubbles: 40
+    headless: true          # false = only local excerpts, zero model calls
+    profile: headless
+    timeoutMs: 180000
+    businessContext: "40, indie developer, small-tool SaaS"
+```
+
+## Verification
+
+```bash
+node verify/smoke.mjs        # 24 structural checks
+node verify/contract.mjs     # 38 pure-function tests
+node verify/host.test.mjs    # 18 fake-ctx end-to-end tests (no network, no subprocess)
+node tools/audit-corpus-coverage.mjs   # quote must be verbatim in all 33 essays
+npm pack --dry-run           # 59 files / 1.3 MB, no .dsh-dev / assets/raw / verify
+```
+
+CI runs the same set on Node 22 and 24. See [verify/README.md](verify/README.md).
+
+## License and third-party content
+
+- **Code**: MIT — see [LICENSE](LICENSE).
+- **Bundled corpus** (`corpus/`, 33 essays): **not MIT.** Texts come from the
+  [Chinese Marxist Internet Archive](https://www.marxists.org/chinese/maozedong/index.htm) and
+  are bundled for personal study only. See [NOTICE](NOTICE). Delete `corpus/articles/` to drop it;
+  quote/excerpt templates then degrade safely to summary.
+- **Sprites**: AI-generated (gpt-image-2), a fan-made "whale girl" character — not affiliated with
+  DeepSeek. See [assets/PROVENANCE.md](assets/PROVENANCE.md).
+
+This plugin is a reading/nudging tool that treats the essays as a source of product and
+entrepreneurship method. It is not affiliated with DeepSeek or any publisher, and it is not
+political advocacy.

package/README.md

@@ -1,3 +1,196 @@
-# Temporary Holding Version
+# dsh-maoxuan-pet · 鲸鱼娘·小毛
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.en.md) · 中文
+
+[![verify](https://github.com/yuna78/dsh-maoxuan-pet/actions/workflows/verify.yml/badge.svg)](https://github.com/yuna78/dsh-maoxuan-pet/actions/workflows/verify.yml) [![npm](https://img.shields.io/npm/v/dsh-plugin-maoxuan-pet.svg)](https://www.npmjs.com/package/dsh-plugin-maoxuan-pet)
+
+> 一只穿红军制服、抱着《毛泽东选集》的鲸鱼娘，住在 DSH 的 Web 界面右下角。
+> 每小时读一篇毛选，把它变成一句针对**你的**创业处境的思想 + 一句督促，
+> 并且随时可以开一个新会话问她：根据毛选，我这一步该怎么走。
+
+| 需求 | 实现 |
+|---|---|
+| 宠物形态、鲸鱼娘、红军制服、手捧毛选 | `assets/` 里 4 帧 AI 立绘（idle / talk / blink / read，256×539 RGBA，红封面竖排「毛泽东选集」可辨），`client.js` 在 `shell.overlay` 槽位渲染悬浮宠物 |
+| 每小时帮我读毛选 | Host 定时器按小时读 `corpus/` 里的下一篇（轮转、避开刚读过的） |
+| 每小时生成思想 / PUA 我的话，出现在气泡里 | 每次生成 `spawn` 一个 `dsh --profile headless` 对话，拿到结构化 JSON 后推给气泡 |
+| 有个 preset，能直接问「根据毛选我该怎么做」 | `maoxuan-pet`「毛选创业参谋」preset + 运行时注册的 `maoxuan-vademecum` skill 指向内置语料 |
+
+## 它到底怎么工作
+
+```
+┌─ DSH Web (dsh web) ───────────────────────────────────────────┐
+│                                                               │
+│  index.js  (Host)                                             │
+│   ├─ 状态：$DSH_HOME/storages/dsh-maoxuan-pet.json  (原子写)   │
+│   ├─ 定时器：ctx.timeout 链 → quietHours / dailyLimit 约束      │
+│   ├─ 语料：corpus/index.json → 轮转挑一篇 verified 的           │
+│   ├─ 生成：spawn `dsh --profile headless --json "<prompt>"`    │
+│   │        └ 失败/超时/非 JSON → 本地摘录降级（标注“离线摘录”） │
+│   ├─ 路由：/api/dsh-maoxuan-pet.{state,generate,dismiss,       │
+│   │        asset,corpus}                                       │
+│   └─ skill：把 corpus/ 注册成 maoxuan-vademecum                │
+│                                                               │
+│  client.js  (Web)                                             │
+│   └─ shell.overlay → 宠物 + 气泡，20s 轮询 / 生成中 3s 轮询     │
+│                                                               │
+│  cordis.patch.yml                                             │
+│   ├─ 插件行 dsh-maoxuan-pet                                    │
+│   └─ preset-maoxuan-pet「毛选创业参谋」(persona + skill + 工具)  │
+└───────────────────────────────────────────────────────────────┘
+```
+
+气泡里的每条内容都是**结构化**的，而且**整条不超过 200 字**：
+
+| 字段 | 含义 |
+|---|---|
+| `template` | 三种模板轮转：`quote` 金句 / `excerpt` 文章节选 / `summary` 小毛概括 |
+| `cite` | 上面那一句（逐字核对过；`summary` 是小毛的概括，不加引号），带来源链接 |
+| `axis` | 启示落点，六选一：客户 / 项目 / 组织 / 现金流 / 决策 / 自律 |
+| `pua` | 小毛对你说的一句话（≤40 字，第一人称；**模型复述原文时会整条丢弃**，气泡只留引文 + 启示） |
+| `lesson` | 启示：一条硬规则 + 怎么验证（≤100 字，围绕 `axis`） |
+| `chars` | 引文 + pua + 启示的实际字数，Host 保证 ≤200 |
+| `mode` | `headless` = 模型生成；`offline` = 本地摘录降级（UI 会标「离线摘录」） |
+
+框架是这样设计的（`template × axis` 矩阵，而不是每次同一套）：
+
+```
+取材  3 种：原文金句 / 文章节选（逐字取整句）/ 小毛概括（模型自己概括）
+落点  6 种：客户 · 项目 · 组织 · 现金流 · 决策 · 自律
+语气  3 种：sharp 硬话 · calm 冷静 · urgent 催
+```
+
+- 模板游标 `templateCursor` 持久化在状态里，按 3 种循环；不会因为历史条数封顶而卡住；
+- `axis` 在 prompt 里指定，并尽量避开上一条的落点；
+- 引文句式/节选都在 `corpus/articles/<id>.md` 里做 `isVerbatim` 逐字校验，校验不过就退到 `summary`，绝不编造；
+- 所有字段最后过一遍 `fitLesson`，把「引文 + pua + 启示」压进 200 字。
+
+为什么落点是 6 类名词、而「动作」不单列一类、字数预算怎么分、真实生成样例长什么样，
+见 [docs/CONTENT-FRAMEWORK.md](docs/CONTENT-FRAMEWORK.md)。语料能不能支撑 Quote 模板，跑一条审计就知道：
+
+```bash
+node tools/audit-corpus-coverage.mjs   # 33 篇：金句逐字命中 33/33，节选可用 32/33
+```
+
+### 界面行为（这一版按用户逐条反馈定的）
+
+（效果图见下方[「长什么样」](#长什么样)）
+
+- **红皮书卡片**：深红封面 + 烫金书脊，正文米白；卡片里不出现蓝/紫/绿，落点 chip 用同一族暖金。滚动条也换成烫金滑块 + 深红轨道。
+- **宠物不动**：卡片绝对定位在宠物左侧（宠物被拖到靠左边缘时自动翻到右侧），点开/收起只让气泡出现或消失，宠物坐标不变。
+- **打开即已读**：卡片真正显示的那一刻才把这条标已读，宠物右上角的未读数随之消失；正在读的那条会被"钉住"，Host 把 `current` 推进到下一条时，眼前的文字不会跳。
+- **没有未读也有内容**：全部读过后再点开，仍然停在上一次产出的那张卡，`‹ ›` 可以往前翻历史。
+- **定时弹出**：整点生成的新气泡会自己弹出来；手动关掉的那条不会自己再弹，等下一条。
+- **按钮无盒子**：`收起` / `再督促` 是纯文字 + 下划线，没有背景和边框。
+
+## 安装
+
+从 npm（推荐）：
+
+```bash
+dsh plugin --profile web add dsh-plugin-maoxuan-pet
+# 然后 Ctrl+C 停掉 dsh web，再重新 `dsh web`，刷新页面
+```
+
+从源码（本目录）：
+
+```bash
+node install.mjs --dry-run   # 先看要改什么
+node install.mjs             # 写入 profile 清单 + pnpm link
+```
+
+两种方式装完都要**手动重启** `dsh web`（Ctrl+C 后重新 `dsh web`），刷新页面。
+
+完整步骤、回滚、排错见 [docs/INSTALL.md](docs/INSTALL.md)；内部接口见 [docs/API-CONTRACT.md](docs/API-CONTRACT.md)。
+
+### 长什么样
+
+![红皮书气泡](docs/screenshot-hero.png)
+
+深红封面 + 烫金书脊的气泡挂在宠物左侧，宠物自己不动；打开即已读（右上角未读数消失），
+`‹ ›` 可以往回翻历史；定时生成的新气泡会自己弹出来，`收起` / `再督促` 是纯文字按钮。
+
+截图由 `scripts/hero-shot.mjs` 生成（需要本地 headless Chrome + 一个 dsh web 实例），
+换版式时重拍即可。
+
+
+## 配置
+
+```yaml
+- id: dsh-maoxuan-pet
+  config:
+    enabled: true
+    everySeconds: 3600      # 每小时
+    firstDelaySeconds: 90   # 启动后 90s 先来一次
+    quietHours: [2, 8]      # 本地时间 02:00–08:00 不打扰
+    dailyLimit: 24          # 每天最多生成次数（防失控）
+    maxBubbles: 40
+    headless: true          # false = 只用本地摘录，不花模型调用
+    dshBin: dsh
+    profile: headless
+    timeoutMs: 180000
+    businessContext: |-
+      用户是一位正在创业的独立开发者……
+```
+
+## 用 preset 问「根据毛选我应该怎么做」
+
+新建会话 → preset 选 **「毛选创业参谋」**（id `maoxuan-pet`）→ 直接问。它会：
+
+1. 加载 `maoxuan-vademecum` skill（知道语料在哪、怎么检索）；
+2. 用 `read` 打开对应篇目**全文**，取逐字原文；
+3. 按固定结构回答：原文金句（篇名 + 时间）→ 当时的问题与论证 → 方法 → 你的处境 → 今天能做的一步；
+4. 核不到原文就明说，不编造。
+
+`maoxuan-vademecum` skill 是运行时由 Host 注册的（内容来自 `skill/maoxuan-vademecum/SKILL.md` + 语料索引），所以它永远指向当前安装目录，不写死路径。
+
+## 毛选语料
+
+- **33 篇，全部 `verified: true`**，覆盖第一至第五卷（目录页实际解析出 329 篇，按“与创业最相关”白名单取 33 篇全文）；
+- 来源：中文马克思主义文库公开电子文本（https://www.marxists.org/chinese/maozedong/index.htm），GB2312 页面按 gb18030 解码，逐篇记录 URL 与抓取时间；
+- 结构：`corpus/index.json` 索引 + `corpus/articles/<id>.md` 全文；每条带 `quote`（逐字核对）、`summary`、`businessAngle`、`verified`；
+- 重新抓取 / 扩充：`npm run corpus`（见 `scripts/fetch-corpus.mjs`）；
+- 版权：文本版权归原权利人，此处仅用于个人学习研究，不用于售卖，详见 `corpus/README.md` 与 `LICENSE`。
+
+## 开发与验证
+
+```bash
+npm test            # node verify/smoke.mjs
+npm run test:contract
+node verify/host.test.mjs   # 假 ctx 端到端：路由、状态、降级、原子写
+node --check index.js
+node --check client.js
+```
+
+验证边界见 [verify/README.md](verify/README.md)：单元与端到端测试不联网、不启动子进程、不花模型调用。
+
+真实链路另做过一次隔离启动验证（`DSH_HOME=/tmp/... dsh web --port 3099`，不碰当前 GUI 的 profile）：
+
+| 验证 | 结果 |
+|---|---|
+| `--dump-config` 组装 | 插件行与 `preset-maoxuan-pet` 都在组合后的配置里 |
+| `GET /api/dsh-maoxuan-pet.state` | 200，`corpus.count=33`，`nextRunAt` 已排定 |
+| `GET /api/dsh-maoxuan-pet.asset?name=idle` | 200，`image/png`，256×539 RGBA |
+| 页面 boot payload | 含 `dsh-plugin-maoxuan-pet/client.js`，实际拉到的 bundle 里含本插件代码且可解析 |
+| `POST /api/dsh-maoxuan-pet.generate`（真实 headless） | 61s，`mode: "headless"`，返回结构化气泡（篇名/金句/思想/启示/督促/动作） |
+| 失败降级 | 无凭据时 5.5s 内降级为 `mode: "offline"` 并写入 `lastError` |
+
+### 两个真实踩到的坑（已在 docs/API-CONTRACT.md §6 详述）
+
+1. 自定义路由必须显式 `requestBody: 'buffered'`，否则 GET 会被 Host 直接 400、handler 不被调用；
+2. `ctx.timeout()` 必须在 `inject` 里声明 `'timer'`，否则真实 `dsh web` 启动 fatal。
+
+## 已知限制
+
+- 只支持 Web 界面（`dsh.client.platform: web`），终端/TUI 里没有宠物；
+- 定时器只在这个 `dsh web` 进程活着时走；进程停了不会补跑，重启后按 `nextRunAt` 决定是否补一次；
+- headless 生成每次是一个独立会话（不复用上下文），好处是稳定、坏处是“它不记得昨天说过什么”——所以 prompt 里带了最近 6 条督促用来避免重复；
+- 生图是 AI 生成，中文“毛泽东选集”可能不是逐字可辨，详见 `assets/PROVENANCE.md`；
+- DeepSeek「鲸鱼娘」是民间同人设定，本项目不是官方素材，也不代表 DeepSeek 立场。
+
+## License
+
+- **代码**：MIT，见 [LICENSE](LICENSE)。
+- **内置毛选语料**（`corpus/`）：**不是 MIT**。文本来自[中文马克思主义文库·毛泽东](https://www.marxists.org/chinese/maozedong/index.htm)，著作权归原作者与出版方，
+  本项目仅作个人学习、研究之用的整理，不构成再出版或商业授权。详见 [NOTICE](NOTICE) 与 [corpus/README.md](corpus/README.md)。
+- **立绘**（`assets/`）：AI 生成（gpt-image-2，2026-10-31），民间同人形象「鲸鱼娘·小毛」，与 DeepSeek 官方无关。生成记录见 [assets/PROVENANCE.md](assets/PROVENANCE.md)。
+- 本项目与 DeepSeek、毛泽东著作出版方均无隶属关系；内容用于产品与创业方法论的阅读辅助，不作政治宣传。

package/assets/PROVENANCE.md

@@ -0,0 +1,93 @@
+# 素材来源与生成记录（PROVENANCE）
+
+**素材性质：DeepSeek 民间同人形象「鲸鱼娘·小毛」——非官方素材，AI 生成。**
+与 DeepSeek 官方无任何关联，仅作本插件（dsh-plugin-maoxuan-pet）的宠物形象使用。
+
+- 角色设定（用户原话）：「画一个鲸鱼娘（deepseek 的民间 ip）…… 传中国的红军的制服…… 因为要读毛选，手里有毛选的书」。
+- 生成日期：**2026-10-31**（America/New_York）。
+- 生成模型：**gpt-image-2**，通过用户自建的中转线路调用（`POST /v1/images/generations` 文生图、`POST /v1/images/edits` 图生图 / 表情差分，图生图请求带 `background=transparent`）。
+- 生成工具：
+  - 文生图：作者本机的一个 `gen_image.py` 脚本（个人 skill 目录，非本仓库代码，未随包分发）。
+  - 图生图 / 表情差分：临时 multipart 脚本（仅标准库，未入库），调用同一中转的 `/v1/images/edits`。
+- 凭据处理：base URL / 模型名 / API key 全部经**环境变量**传入，未写入本仓库任何文件、日志或提交。本文件不含任何 key。
+- 后处理：系统自带 `python3` + Pillow（12.1.0）+ numpy，脚本为临时脚本（未入库）。未安装任何新的系统依赖。
+
+## 生成流程
+
+1. **定角色**：文生图一张 1024×1536 的站姿「抱书微笑」立绘（`assets/raw/idle-v1.png`）。
+2. **定封面文字**：以该立绘为参考做图生图，只改「红封面上的竖排中文」，并直接要求 `background=transparent`，得到带 alpha 的 idle 底帧（`assets/raw/idle-text-v2.png`）。
+3. **做表情/姿势差分**：全部以 idle 底帧为参考做图生图，保持角色、服装、比例、配色、封面题字不变，只改表情或持书方式，输出仍为透明底：
+   - talk → `assets/raw/talk-final.png`
+   - blink → `assets/raw/blink-final.png`
+   - read → `assets/raw/read-v3.png`
+4. **统一画面**：四帧用**同一个裁剪框**（原图 1024×1536 的 `(160, 0, 880, 1516)`）裁切，先把透明区域外扩成相邻像素颜色（避免缩放时白边渗入轮廓），再 Lanczos 等比缩放到 **640×1348** 作为母版；交付版再降到 **256×539**（UI 展示高 132px，2x 屏幕够用，四帧共用同一画布与脚底线，切换帧时身体不跳）。
+5. `assets/icon.svg`：**手写 SVG**（纯几何形状，非 AI 生成），米白底 + 红皮书 + 烫金五角星与书名条，2326 字节；另导出 `assets/icon-256.png`（256×256 RGBA）供市场条目 `icon:` 使用（市场只收 GitHub 托管位图，不收 SVG）。
+
+原始中间产物保留在 `assets/raw/`（本仓库 `.gitignore` 已忽略该目录，不随 git 提交；如需瘦身可直接删除）。
+
+## 每个文件的 prompt 全文
+
+### 1. `assets/pet-idle.png`（站姿抱书微笑）
+
+第一步（文生图，1024×1536）：
+
+> a cute chibi anime girl mascot based on a whale: deep navy-blue short bob hair with two small whale-fin shaped hair ornaments, a small blue whale tail fin peeking behind her back, big round dark-blue eyes, fair skin, cheerful, wearing an authentic 1920s-1930s Chinese Workers and Peasants Red Army uniform: grey-blue coarse cotton tunic with red collar tabs, a red cloth armband on the left upper arm, a grey-blue octagonal cloth cap with a small red five-pointed star on the front, grey-blue cloth trousers with puttees, black cloth shoes, holding a thick hardcover book hugged against her chest with both hands; the book cover is plain solid red with one subtle embossed small five-pointed star, the cover has NO text and NO letters, standing upright facing the viewer, gentle warm smile, mouth closed, clean 2D anime key-visual illustration, flat color with thin crisp lineart and soft cel shading, warm cozy palette, full body, centered, pure solid flat white background #FFFFFF, absolutely no shadow under the feet, no gradient, no frame, no text, no letters, no watermark, no 3D, not photorealistic
+
+第二步（图生图表情/题字，`background=transparent`）：
+
+> Same image, same character, fully transparent background. Only change: on the plain red front cover of the book, write the five Chinese characters 毛泽东选集 in warm off-white printed Chinese type, stacked vertically top to bottom, small, narrow, placed in the UPPER LEFT part of the red cover well above her hand so no character is covered by her hand or arm. Keep EXACTLY the same character, face design, hair, hat with red star, uniform, red armband, palette, lineart style, scale and framing. No shadows. Do not draw any text on the armband or clothing.
+
+### 2. `assets/pet-talk.png`（张嘴说话，供气泡同步）
+
+> Same character, same pose. Only her expression changes: mouth open mid-sentence speaking warmly, bright friendly eyes, slightly raised chin. Keep EXACTLY the same character, hair, hat with red star, uniform, red armband, the red book with the vertical Chinese title on its cover, palette, lineart style, scale and framing. Fully transparent background, no shadows, no text on clothing.
+
+### 3. `assets/pet-blink.png`（闭眼/眨眼，与 idle 交替播放）
+
+> Same character, same pose. Only her expression changes: eyes gently closed in a happy relaxed blink (curved eyelashes), mouth closed in a soft smile. Keep EXACTLY the same character, hair, hat with red star, uniform, red armband, the red book with the vertical Chinese title on its cover, palette, lineart style, scale and framing. Fully transparent background, no shadows, no text on clothing.
+
+### 4. `assets/pet-read.png`（低头看书）
+
+> Same character, same hat, same uniform, same red armband, same art style and scale, fully transparent background. Pose change: she lowers her head and looks DOWN at the red book, which she now holds OPEN in both hands so we can see the warm white printed pages with neat vertical lines of tiny abstract Chinese text; the red cover with the five-pointed star stays visible under the pages; calm focused smile. Keep exactly the same character design, hair, face, hat with red star, palette, lineart. No shadows, no extra text on her clothing.
+
+## 实际交付与检查结果（真实执行）
+
+| 文件 | 像素 | 色彩/通道 | `file` 输出 | 说明 |
+| --- | --- | --- | --- | --- |
+| `assets/pet-idle.png` | 256×539 | RGBA，带 alpha | PNG image data, 256 x 539, 8-bit/color RGBA, non-interlaced | 站姿抱书微笑，封面竖排「毛泽东选集」可辨 |
+| `assets/pet-talk.png` | 256×539 | RGBA，带 alpha | 同上 | 同姿势张嘴说话，封面题字保留（字号比 idle 略小、略挤） |
+| `assets/pet-blink.png` | 256×539 | RGBA，带 alpha | 同上 | 闭眼微笑，与 idle 仅表情不同 |
+| `assets/pet-read.png` | 256×539 | RGBA，带 alpha | 同上 | 低头看书，书摊开（见下方缺陷第 2 条） |
+| `assets/icon.svg` | viewBox 512×512，2326 字节 | 纯几何矢量 | — | 米白底 + 红皮书 + 烫金五角星 + 书名条，手写；同款导出为 `assets/icon-256.png` |
+
+每张 PNG 都用 `read_image` 逐张看过后才采用；另外把四帧合成到棋盘格背景上放大检查轮廓边缘，确认透明通道有效、无白色描边、脚底与发梢没有被裁断。
+
+## 缺陷与局限（如实记录）
+
+1. **封面中文是模型直接画出来的**，不是后期叠加：
+   - idle / blink / talk 三帧的红封面上，竖排「毛泽东选集」五字可辨；其中 talk 帧字号偏小、字距略挤，远看仍可读但不如 idle 干净（单张重试 3 次上限内未再重生成）。
+   - **read 帧的书是摊开的**，封面题字被书页遮住，因此该帧封面只保留五角星与米白书页上的抽象竖排小字，**没有可读的「毛泽东选集」字样**。若需要四帧都出现完整书名，需要前端在 read 帧叠加 SVG 文字。
+2. **制服**：帽子形制接近 1930 年代红军软帽/八角帽（正面红五星清晰、灰蓝土布质感），但帽檐比历史实物更挺括、略偏「军帽」感；红领章在 idle/talk/blink 是三角形小领章、在 read 帧是菱形块，帧间不完全一致。没有出现国民政府军、现代迷彩、纳粹/苏联符号。
+3. **手部**：四帧都是双手抱书或持书，手指被简化为四指团块（Q 版常见处理），没有出现多余手指或明显畸形，但也没有逐指分开。
+4. **鞋**：黑色布鞋鞋面上有一块肉色椭圆（脚背），放大看略像「鞋面开孔」，属轻微造型瑕疵。
+5. **帧间一致性**：四帧由同一底图 img2img 派生，构图、比例、配色、服装基本一致，但发梢分叉、鲸尾弯曲、腰带扣、领章形状等有细小差别。**不适合做逐像素动画**，只适合静态帧切换（插件里 idle↔blink 交替、talk 气泡同步、read 展示的用法）。
+6. 生成过程记录：blink 第一次透明底请求（`raw/blink-v2.png`）返回的是不带 alpha 的 RGB，已重新生成（`raw/blink-final.png`）；read 第一版（`raw/read-v2.png`）帽形/领章与 idle 差异偏大，改用第二版（`raw/read-v3.png`）。
+7. 全部素材无第三方素材、无水印、无多余文字；`icon.svg` 为手写纯几何图形。
+
+## 复现方式（不含任何密钥）
+
+```bash
+export GPT_IMAGE_BASE_URL="<用户自己的 OpenAI 兼容中转地址>"
+export GPT_IMAGE_MODEL="gpt-image-2"
+export GPT_IMAGE_API_KEY="<从用户私有的 key 文件按环境变量注入>"
+
+# 1) 文生图底图
+python3 ~/.codex/skills/gpt-image/scripts/gen_image.py --size 1024x1536 \
+  --prompt "<见上文 idle 第一步 prompt>" --output assets/raw/idle-v1.png
+
+# 2) 表情/姿势差分：POST {GPT_IMAGE_BASE_URL}/images/edits（multipart）
+#    image=assets/raw/idle-text-v2.png, background=transparent, size=1024x1536
+#    prompt=<见上文各帧 prompt>
+
+# 3) 统一裁剪 640×1348 母版、透明区域颜色外扩、Lanczos 缩放（Pillow）
+# 4) 交付版再等比降到 256×539，PNG optimize=True（四帧共 603 KB，0.2.1 起）
+```

package/assets/icon.svg

@@ -0,0 +1,45 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512" role="img" aria-label="鲸鱼娘·小毛 图标：米白底上的一本红皮书《毛泽东选集》，封面烫金五角星与书名条">
+  <title>鲸鱼娘·小毛</title>
+  <!-- 底板：米白圆角方块（深色市场卡片上有边界，浅色界面下不刺眼） -->
+  <rect x="0" y="0" width="512" height="512" rx="116" fill="#FFF6E9"/>
+  <rect x="14" y="14" width="484" height="484" rx="104" fill="none" stroke="#C1342B" stroke-width="6" stroke-opacity="0.16"/>
+
+  <!-- 投影：把书从米白底上「抬」起来 -->
+  <g filter="url(#softShadow)" opacity="0.22">
+    <rect x="132" y="112" width="286" height="308" rx="28" fill="#7A1410"/>
+  </g>
+
+  <g transform="translate(252,256) scale(1.08) translate(-258,-256)">
+    <!-- 书页块：右侧露出的米黄页缘 + 两道浅红页线 -->
+    <g>
+      <path d="M330 118 h78 a14 14 0 0 1 14 14 v248 a14 14 0 0 1 -14 14 h-78 z" fill="#EFDFC4"/>
+      <path d="M356 138 v236 M382 138 v236" stroke="#D9C4A2" stroke-width="5" stroke-linecap="round"/>
+    </g>
+
+    <!-- 书壳：深红封面 + 更深一档的书脊 -->
+    <g>
+      <rect x="120" y="104" width="232" height="304" rx="26" fill="#B3271E"/>
+      <rect x="120" y="104" width="46" height="304" rx="22" fill="#8F1E17"/>
+      <!-- 书脊烫金线 -->
+      <path d="M143 148 v216" stroke="#E8C36A" stroke-width="7" stroke-linecap="round" opacity="0.9"/>
+    </g>
+
+    <!-- 封面烫金细框 -->
+    <rect x="192" y="126" width="142" height="260" rx="14" fill="none" stroke="#E8C36A" stroke-width="5" stroke-opacity="0.55"/>
+
+    <!-- 五角星（10 点纯几何）：中心 (263,196)，外径 46，内径 17.6 -->
+    <polygon fill="#E8C36A" points="263,150 273.32,181.76 306.72,181.76 279.7,201.74 289.02,234.5 263,214.25 236.98,234.5 246.3,201.74 219.28,181.76 252.68,181.76"/>
+
+    <!-- 书名条：两道烫金横杠，替代小字（36px 下也能读成「书名」） -->
+    <g fill="#E8C36A">
+      <rect x="215" y="272" width="96" height="16" rx="8"/>
+      <rect x="232" y="304" width="62" height="13" rx="6.5" opacity="0.78"/>
+    </g>
+  </g>
+
+  <defs>
+    <filter id="softShadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="14"/>
+    </filter>
+  </defs>
+</svg>