@apprun/shiqu 0.7.0 → 0.8.0

package/NOTICE

@@ -11,8 +11,8 @@ rights that their respective rights holders have not granted.
 
 For the bundled book collection, see data/library/source-notices.md and
 data/library/catalog.json, together with notices in the original downloads.
-The Wikisource and Kanripo transcription contributions retain CC BY-SA 4.0,
-including the historical Zhongli excerpt in lib/content.ts. See data/library/licenses/CC-BY-SA-4.0.txt. Original authors and
+The Wikisource and Kanripo transcription contributions retain CC BY-SA 4.0.
+See data/library/licenses/CC-BY-SA-4.0.txt. Original authors and
 upstream contributors are credited in the catalog and original downloads.
 Project Gutenberg downloads retain their own accompanying notices and terms.
 

package/README.md

@@ -1,201 +1,109 @@
 # 拾趣 · Shiqu
 
-Turn Chinese classics into your own illustrated storybooks. Read in your browser, generate with a logged-in Codex CLI, OpenAI API, or Gemini, and keep stories, images, and reading progress on your computer.
+用拾趣，把中国古典故事变成你自己的连环画。支持电脑与手机阅读，以及 PDF、PNG 长图和 ZIP 导出。故事、图片和阅读进度保存在你的电脑上。
 
-## Choose how to use Shiqu
+[在线阅读拾趣好故事 →](https://yysun.github.io/awesome-shiqu/)
 
-**Choose the desktop app for graphical use, the Codex skill to delegate tasks in natural language, or the CLI for direct commands and scripted startup.**
+## 快速开始制作
 
-| Your situation | Recommended entry point |
-| --- | --- |
-| You want graphical settings, library and queue management, and no separate Node installation | Desktop app: includes Node 24 and service controls |
-| You want Codex to create, edit, export, or maintain stories without a server | Install the Shiqu skill and invoke `$shiqu`; requires Node 24 |
-| You already have Node 24 and want one-command startup without installing a desktop app | CLI: `npx @apprun/shiqu`; keep the terminal running and press Ctrl+C to stop |
-| You want generation and reading access to continue after closing the control window | Desktop app: stays in the system tray until you stop the service or quit the app |
-| You need startup parameters, environment overrides, or non-interactive operation | CLI: prepare provider configuration and a library path in advance |
-| You use Linux, an Intel Mac, or Windows ARM64 | CLI: install Node 24 yourself; no desktop installer is provided for these platforms. Windows supports API providers or read-only mode |
-| You want phone access on the same Wi-Fi | Both entries: CLI prints phone QR codes on startup; desktop shows them in its control window |
-| You need built-in internet tunnel controls | Desktop app: requires a separate cloudflared installation. CLI has no built-in internet tunnel |
-
-**Shared features:** Both entry points provide the same browser interface for story creation, production and acceptance requirements, generation queues, pause/resume, reading, library organization, and PDF / PNG / ZIP export. The desktop window adds library, queue, settings, and service controls; interactive reading and story creation happen in the browser. The Codex skill uses CLI subcommands for production, editing, library maintenance, and offline exports without a running service. Both support OpenAI API, Gemini, and read-only mode. Codex generation is supported on macOS / Linux and requires a separately installed, logged-in Codex CLI; the Shiqu CLI and Codex CLI are different tools.
-
-**Shared settings and data:** Under the same local user account, both entry points reuse saved provider settings and API keys. With the same library directory, they share stories, images, and reading progress. Neither requires the other to be running.
-
-### Switching between CLI and desktop
-
-1. **Stop the current service.** Press Ctrl+C in the CLI, or stop the service / quit the desktop app. Closing the desktop window alone does not stop the service.
-2. **Use matching versions and the same library directory.** Check the CLI version with `npx @apprun/shiqu --version`; use `npx @apprun/shiqu@<version>` to select a published version matching the desktop app. Explicit `--data-dir` / `SHIQU_DATA_DIR` overrides apply only to that invocation and do not change the saved directory.
-3. **Start the other entry point.** Saved provider settings and keys are reused. Changes to shared settings take effect in an already-running service only after it restarts.
-
-**Only one service can run against a library at a time, even on different ports.** Switching entry points needs no data copy. Choosing another directory opens another library; it does not move or merge data. Back up before upgrading or downgrading, as older versions may not read newer settings or data. See the [full user guide](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md).
-
-## Use Shiqu through Codex
-
-Install the bundled skill once, then ask Codex to perform Shiqu tasks in natural language. The skill defines data contracts, business rules, and acceptance criteria. Codex can write task-specific programs for filtering, comparison, reports, and batch orchestration; saved-state changes, generation, review, and exports use Shiqu's existing production implementation.
-
-See the [prompt-only Use as SKILL guide](https://github.com/yysun/shiqu/blob/main/.docs/use-as-skill.md) for copyable requests covering setup, provider/model configuration, creation and editing, exports, batch tasks, recovery, and diagnostics.
-
-```bash
-npx @apprun/shiqu skill install --scope global
-```
-
-Global installation copies the skill to `~/.agents/skills/shiqu/SKILL.md` for use across projects. For one project, run `skill install --scope project` in that directory; it writes `.agents/skills/shiqu/SKILL.md` there. Both scopes copy independent files, reject symlinks and different existing instructions, and require an explicit scope. Installing a skill does not start a server, initialize or move a library, or globally install the CLI executable.
-
-In Codex, invoke the skill with a request such as:
+三种方式，任选一种：
 
-```text
-$shiqu Find a story about kindness and misunderstanding in Zhuangzi.
-Use Chinese ink painting and balanced narrative detail. Show candidates and a production plan first;
-wait for my confirmation before generating illustrations, then export an offline preview and public ZIP.
-```
-
-Specify the library, output directory, and author credit in your request. Codex queries the selected CLI version's help and chooses operations from saved state. Simple tasks can call the CLI directly; generated programs use argument arrays and JSON input without modifying SQLite or reimplementing generation or exports. Shiqu uses its saved generation provider and credentials. Library commands automatically create the directory and initialize the database on first access using the same startup/migration path as desktop and server; no separate init step is required. Configure a provider first if needed. Stop any service using the same library before running headless commands. Only explicit run performs inference; edits, inspection, preview and export do not start background generation.
-
-`skill show` prints the instructions without installing them. If a new skill does not appear in Codex, restart Codex. The copied skill does not pin the CLI runtime: use `npx @apprun/shiqu@VERSION` when a fixed version is required. Use `skill check` to report npm release updates (cached for 24 hours), `skill check --auto-update on|off` to save your preference, and a fixed-version `skill update --scope global|project` to copy that CLI package’s bundled skill. Automatic updates are off by default: Codex applies the returned pinned command only after opt-in, without overriding explicit or project-pinned versions. Installation state records version and content hash; local edits, unknown copies, unsupported state and downgrades are refused. Legacy copies can be registered by reinstalling their matching package only when their contents match. Offline checks retain the existing version. No background updater is installed.
+### 1. npx：一条命令启动
 
-### Direct headless commands
-
-With no subcommand, Shiqu starts the existing browser service. Subcommands operate directly on the production workflow without HTTP, desktop, or frontend:
-
-```bash
-npx @apprun/shiqu help --json
-npx @apprun/shiqu stories list --data-dir /private/shiqu-library
-npx @apprun/shiqu run STORY_ID --until reviewed --data-dir /private/shiqu-library
-npx @apprun/shiqu preview STORY_ID --data-dir /private/shiqu-library --output /private/preview.html
-npx @apprun/shiqu export STORY_ID --data-dir /private/shiqu-library --format zip --output /private/story.zip
-npx @apprun/shiqu skill show
-```
-
-Use `help --json` for command inputs and effects. Subcommands return one JSON receipt on stdout, logs on stderr, and nonzero exit codes on errors. The exception is skill show, which prints Markdown unless --json is supplied. Only explicit run invokes inference, only for the specified story. Saving, editing, confirmation, inspection and export do not start background generation. Read reason/session before continuing; pauses/faults require explicit control/recovery. Intake mutations require explicit `--generation N` or input.generation from stories get. Retry/override require explicit faultId. Reuse the same request UUID and original generation/token/faultId and input for mutation replay; edits require the token from `stories revisions ID`.
-
-Creation follows create → search → run until candidates → choose → run until prepared → confirm → run until reviewed or completed. Follow returned IDs and states. Complete ZIP/PDF/PNG exports require the current version and all images. Public ZIP is the default; internal prompts require `--include-prompts`. Unsigned export requires `--allow-unsigned`. Preview is escaped, self-contained HTML. Outputs must be new paths. Config reuses saved settings; keys go through input files/stdin, never argv.
-
-`init` remains optional for explicit early initialization. Database creation follows --data-dir, SHIQU_DATA_DIR, saved location, then the default library; it does not configure a provider or start generation. Corrupt databases fail instead of being rebuilt. Backup requires an existing database. Help, catalogs, skill installation and diagnostic export do not create a library; restore still requires a new target directory.
-
-To choose a database folder explicitly:
-
-```bash
-npx @apprun/shiqu init --data-dir /absolute/path/my-library
-npx @apprun/shiqu stories list --data-dir /absolute/path/my-library
-```
-
-The argument is a directory: Shiqu creates it if needed and stores `shiqu.sqlite` and `media/` there. Existing data is retained. The command returns the resolved absolute path. This does not change the saved desktop/CLI default; reuse --data-dir or set SHIQU_DATA_DIR for later commands.
-
-### Library maintenance
-
-Maintenance is shared with desktop libraries: `shiqu --backup <new-directory>`, `shiqu --verify-backup <backup>`, `shiqu --restore <backup> --data-dir <new-library>`, and `shiqu --diagnostics <new-json-file>`. Stop all services before backup; diagnostics can be exported while running. Restore never overwrites an existing directory or starts generation. Backups include private story/media data, not the separate provider credentials. Existing libraries receive a verified sibling `library-backups/pre-upgrade-*` snapshot before new migrations; keep these private and restore with a matching application version. Diagnostic exports contain bounded allowlisted metadata, not prompts, keys, story text or raw provider responses.
-
-## Run
-
-Requires **Node 24** (recommended: 24.22.1) and its bundled npm / npx. No separate pnpm installation is needed:
+需要 **Node 24**：
 
 ```bash
 npx @apprun/shiqu
 ```
 
-On first use, npx may ask to download the package; confirm to continue. Open the printed URL, normally `http://127.0.0.1:3000`, or scan a terminal QR code from a phone on the same trusted Wi-Fi. LAN access is enabled by default. Keep the terminal running; stop with Ctrl+C. No checkout, build, Docker, or desktop app is needed.
+按提示选择书库和生成服务，打开终端打印的网址即可使用。同一可信 Wi-Fi 下，手机可扫描终端二维码接着读。保持终端运行，按 Ctrl+C 停止。[CLI 使用说明](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#cli-启动)
 
-If you already use pnpm, `pnpm dlx @apprun/shiqu` starts the same app. You can also install it globally with pnpm for a permanent `shiqu` command:
+### 2. Desktop：下载安装
 
-```bash
-pnpm add -g @apprun/shiqu
-shiqu --help
-```
+内置 Node，无需另装运行环境。支持 Apple Silicon Mac（macOS 13.5+）和 Windows 10/11 x64。
 
-## First-run provider setup
+[下载 macOS DMG](https://github.com/yysun/shiqu/releases/latest/download/shiqu-standard-macos-arm64.dmg) · [下载 Windows 安装程序](https://github.com/yysun/shiqu/releases/latest/download/shiqu-standard-windows-x64-setup.exe) · [版本与校验文件](https://github.com/yysun/shiqu/releases/latest)
 
-No environment variables are required for interactive setup. After finding or choosing a library, the CLI reuses saved settings. If none are configured, choose **Codex / OpenAI API / Gemini / Read only**. Enter API keys at the hidden terminal prompt; model prompts accept the saved/default value on Enter. Codex needs an installed, logged-in CLI instead of an API key. Windows supports the API providers and read-only mode.
+打开拾趣，在「设置」中选择生成服务，保存并启动，再点击「在浏览器打开」。安装包未签名，首次打开的系统提示见[桌面版入门](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#桌面版入门)。
 
-Settings and provider-specific keys are shared with the desktop app in the separate private `desktop.sqlite`, outside story libraries. Saved configurations do not prompt again. Keys are plaintext protected by local filesystem permissions (0700 directory / 0600 database on Unix); do not share settings backups. Keys never appear in HTTP responses or settings views.
+### 3. Skill：让 Codex 帮你制作
 
-```bash
-npx @apprun/shiqu --configure
-npx @apprun/shiqu --reset-providers
-```
-
-`--configure` selects/edits a profile, retains that profile's saved key on blank input, saves only a completed setup, and exits. Switching profiles preserves other providers' models/keys. `--reset-providers` removes saved provider settings and keys, preserving libraries/network settings and all stories. It reopens setup in a terminal, or exits with guidance when non-interactive. Already-running servers keep their startup snapshot until restarted.
-
-OpenAI uses the official Responses API for text and Images API for illustrations, including saved reference images. Defaults: `gpt-6.1-sol` / `gpt-image-2.5-sunburst`; access/quota depend on your API project. OpenAI API billing is separate from Codex subscription quota. Public webpage URL discovery remains Gemini-only. Read-only never dispatches generation.
-
-### Invocation-only overrides
+需要 **Node 24**。运行一次，安装供当前用户各项目使用的技能：
 
-Environment variables or an explicitly selected env file override saved configuration without being imported or persisted:
-
-```dotenv
-SHIQU_AI_PROVIDER=openai
-OPENAI_API_KEY=your-key
-# Optional model overrides:
-OPENAI_TEXT_MODEL=gpt-6.1-sol
-OPENAI_IMAGE_MODEL=gpt-image-2.5-sunburst
+```bash
+npx @apprun/shiqu skill install --scope global
 ```
 
-Other choices: `SHIQU_AI_PROVIDER=codex` after `codex login`, `SHIQU_AI_PROVIDER=gemini` with `GEMINI_API_KEY`, or `SHIQU_AI_PROVIDER=readonly` with no key.
+然后在 Codex 中说：
 
-```bash
-npx @apprun/shiqu --config /path/to/shiqu.env
+```text
+$shiqu 从《庄子》中找一个关于善意与误解的故事，用水墨写意。
+先给我候选和制作方案，确认后再生成插图，完成后导出离线预览和公开 ZIP。
 ```
 
-No `.env` is loaded automatically. Existing shell variables beat the selected file; CLI flags beat both. Non-interactive startup requires saved settings or a complete provider override, and a discoverable/explicit library path. No prompt waits indefinitely. The package includes `.env.example` with optional settings.
+无需启动桌面或浏览器服务。[提示词示例](https://github.com/yysun/shiqu/blob/main/.docs/use-as-skill.md) · [技能安装与配置](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#无服务-cli-与-codex-技能)
 
-## Create, review, and read stories
+生成服务可选 Codex、OpenAI API 或 Gemini，也可选择只读。Codex 需 macOS / Linux，并另行安装和登录 Codex CLI；OpenAI API 与 Gemini 使用各自 API 密钥并单独计费。[如何选择后端](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#如何选择后端)
 
-1. Choose one of the 24 books. Select a standalone story directly, extract candidates from up to 24 selected chapters, or search by theme. Theme search shows candidates one at a time while the picker stays open; selecting a story or leaving stops further discovery. Saved candidates and reading progress can be resumed. An incomplete-results notice means some stories could not be judged, not that they failed the theme.
-2. After the original and a verified summary are ready, choose an art style and **brief / balanced / detailed** narrative detail. The frame estimate is not a fixed count: the model plans from the original, and review can add, remove, or replace frames before drawing.
-3. Set production requirements for the adaptation and, optionally, acceptance requirements (one per line, up to 20). Start production explicitly. Review gives a verdict and evidence for each criterion; actionable failures enter repair, while conflicts or criteria that cannot be judged from the written storyboard stop drawing. Inspect the reason and revise the requirements rather than repeatedly resuming.
-4. Production continues in the background after confirmation. Pause/resume controls are shared across windows. Automatic repair stops after 20 rounds or no effective change; inspect the saved issues, continue repair, or edit and save for a fresh review. Explicitly skipping issues is recorded and does not mean acceptance passed.
-5. Read on your computer or phone. Rename a story independently without regenerating it. Once every illustration is ready, export PDF, a PNG overview, or a ZIP containing story JSON, storyboard Markdown, source text, full-resolution WebP images, and saved prompt records. Exports do not make generation requests.
+## CLI 命令
 
-The production and acceptance editors let you inspect current system-rule previews, copy recorded actual prompts, and view saved acceptance results. Previews include unsaved edits and are not execution history; inherited records identify their source version, and missing historical records are not fabricated. Changing only acceptance requirements preserves the storyboard and reusable images for a new review; subsequent repair may still invalidate affected images. Written-storyboard acceptance is not a visual inspection of generated artwork. Prompt records may contain source text and custom requirements; check them before sharing.
+以下命令均加上前缀 `npx @apprun/shiqu`。不带子命令时启动浏览器服务；带子命令时直接操作本地书库。执行书库命令前，先停止占用同一书库的服务。
 
-Set default production credits, a public work link/contact, source licensing, and reuse conditions under **我的 → 署名与转载**, or edit one story under **故事设置**. New stories copy the defaults; each export also resolves blank fields against the latest defaults without rewriting the saved story. Explicit story fields win. Unsigned downloads require confirmation, including repeated downloads; a failed defaults read stops export rather than using stale information. WebP signature size is adjustable from 12–48 original-image pixels, defaulting to 24px; PDF/PNG layout and clean source images remain unchanged.
+| 命令 | 用途 |
+| --- | --- |
+| `help --json` | 查看命令目录、参数、JSON 输入与示例 |
+| `init`, `status` | 显式初始化书库，或检查书库完整性与数量统计 |
+| `catalog`, `books`, `themes`, `styles` | 列出书籍、主题和画风 |
+| `books contents BOOK_ID --query TEXT` | 浏览或搜索书籍的本地目录，查询条件可省略 |
+| `stories list`, `stories get ID`, `stories current ID` | 查看故事列表、故事详情与当前版本 |
+| `stories create --input FILE` | 保存新故事的选题条件 |
+| `stories setup`, `stories search`, `stories choose`, `stories confirm` | 设置要求、查找候选、选择故事与确认制作 |
+| `run ID`, `stories run ID` | 制作指定故事；`--until` 可选 candidates、prepared、reviewed 或 completed |
+| `stories edit ID --input FILE` | 使用 `stories revisions ID` 返回的 token 保存修改版本 |
+| `stories pause`, `stories resume`, `stories stop` | 暂停、恢复或停止故事制作 |
+| `stories retry`, `stories override` | 重试当前故障，或明确跳过审核问题 |
+| `stories rename`, `stories delete`, `stories restore`, `stories favorite`, `stories reference` | 改名、删除、恢复、收藏故事，或设置本书参考图 |
+| `stories revisions`, `stories prompts`, `stories review-history`, `stories source` | 查看版本、提示词、审核记录与原文 |
+| `stories reselect`, `stories replace`, `stories cancel-reselection` | 发起、应用或取消重新选题 |
+| `preview ID --output FILE` | 导出可独立打开的离线 HTML 预览 |
+| `export ID --format FORMAT --output FILE` | 导出 json、md、zip、pdf 或 png |
+| `skill show`, `skill install`, `skill check`, `skill update` | 查看、安装、检查或更新 Codex 技能 |
+| `config get`, `config set`, `config reset` | 查看、保存或重置共享生成服务配置 |
+| `backup DIR`, `verify-backup DIR`, `restore DIR`, `diagnostics FILE` | 备份、校验、恢复书库，或导出脱敏诊断 |
+| `api METHOD reader/ROUTE` | 在当前进程调用允许的 reader 接口 |
+
+只有显式 `run` 执行 AI 生成，其他命令只查看或保存状态。故事操作需传入故事 ID；选题操作还需 `--generation N`。JSON 输入使用 `--input FILE`，或用 `--input -` 从标准输入读取。各命令的必填字段与恢复规则见 `help --json`。
+
+用 `--data-dir DIR` 指定书库。ZIP、PDF、PNG 要求当前版本全部图片完成，导出路径必须尚不存在。恢复书库需显式指定尚不存在的 `--data-dir DIR`。[完整命令流程](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#直接使用命令) · [备份、恢复与诊断](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#书库维护命令)
+
+### 浏览器服务启动参数
+
+| 参数 | 用途 |
+| --- | --- |
+| `--port PORT`, `--host ADDRESS` | HTTP 端口（默认 3000）与监听地址（默认 0.0.0.0）；仅限本机访问时使用 `--host 127.0.0.1` |
+| `--data-dir DIR`, `--config FILE` | 指定书库目录，或加载指定的环境配置文件 |
+| `--configure`, `--reset-providers` | 配置或清除已保存的生成服务设置与密钥 |
+| `--backup DIR`, `--verify-backup DIR`, `--restore DIR`, `--diagnostics FILE` | 维护命令的参数形式，每次单独执行一项 |
+| `--help`, `--version` | 查看启动帮助或当前版本 |
 
-ZIPs include `提示词.md`, `提示词.json`, and `系统提示词.md`. Identical recorded system rules are stored once and referenced from individual calls; distinct historical rules and actual inputs are retained. The archive also preserves credits, AI disclosure, public WebP XMP, and image hashes for integrity checks, not proof of ownership. **Review the entire ZIP before sharing or submitting it:** prompt inputs and custom requirements are included by default. Reference images are represented by saved paths, not bundled files. Deduplication does not guarantee every text file fits a reading site's 1 MiB limit.
+## 更多说明
 
-Use the star button on an illustrated page to select **one reference image per book**, separate from the bookmark for story favorites. Later image requests for that book, including a new story's first frame, prefer the star; without it, later frames use their own story's first image. Replacing or removing the star does not redraw saved images or change requests already in flight.
+[使用指南](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md) · [手机阅读](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#在手机上阅读) · [制作与导出](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#制作与阅读故事) · [常见问题](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#常见问题)
 
-See the [full creation and reading guide](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#制作与阅读故事). Generation uses your configured provider's quota or API billing; quality and completeness still need human review.
+## 开发者
 
-## Options and data
+源码开发使用 **Node 24.22.1** 与 **pnpm 11.25.0**：
 
 ```bash
-npx @apprun/shiqu --port 3100 --data-dir ./my-library
-pnpm dlx @apprun/shiqu --host 127.0.0.1
-npx @apprun/shiqu --version
+nvm install
+nvm use
+corepack enable pnpm
+pnpm run setup
+pnpm dev
 ```
 
-| Option | Environment | Default |
-| --- | --- | --- |
-| `--port` | `PORT` | `3000` |
-| `--host` | `SHIQU_BIND_IP` | `0.0.0.0` (LAN access) |
-| `--data-dir` | `SHIQU_DATA_DIR` | Saved desktop library; otherwise find or ask below |
-| `--config` | — | No env file |
-
-Library selection:
-
-1. An explicit `--data-dir` wins over `SHIQU_DATA_DIR` from the shell or selected env file.
-2. Otherwise reuse the library directory saved in the shared CLI / desktop settings, creating it if necessary. Provider settings and keys are reused separately during provider setup; they are not stored in the story library.
-3. Without shared saved settings, import a prior CLI `cli-library.json` directory if present, otherwise look for an existing database in the desktop default library directory.
-4. If none is found, ask which directory to use or create. Enter accepts the suggested desktop default. Cancel/EOF creates no library; non-interactive first use must supply `--data-dir`.
-
-Suggested desktop-compatible defaults:
-
-- macOS: `~/Library/Application Support/com.shiqu.desktop/library`
-- Linux: `${XDG_DATA_HOME:-~/.local/share}/com.shiqu.desktop/library`
-- Windows: `%APPDATA%\com.shiqu.desktop\library`
-
-Confirmed library choices now live in the shared settings database; legacy `cli-library.json` choices are imported when needed and the old file is retained. Desktop and CLI use the same directory when either configures it first. Explicit `--data-dir` / `SHIQU_DATA_DIR` overrides are invocation-only. New settings databases created by `--configure` do not treat the unconfirmed default library path as a saved choice.
-Relative paths resolve from the launch directory. Both entries use the same SQLite/media format; use matching versions and stop one before starting the other. A busy library is rejected even on a different port. Database and media survive package updates and npm-cache cleanup. Back up the entire library while stopped.
-
-Older CLI releases used `shiqu/library` rather than `com.shiqu.desktop/library` (Windows used LOCALAPPDATA, falling back to APPDATA). Existing data is never moved or merged automatically; pass the old directory with `--data-dir` to continue using it. CLI and desktop now share saved credentials; explicit invocation overrides remain separate and are not saved.
-
-Version 0.6.0 migrates legacy summary fields and adds book-reference storage without regenerating existing stories. Back up the entire stopped library before upgrading, refresh old browser tabs, and keep CLI and desktop versions matched. Older binaries may not read the upgraded schema; restore a pre-upgrade backup when rolling back.
-
-Version 0.6.5 adds default publication settings without rewriting existing stories or images. Stop all services using the library and back it up before upgrading; refresh browser tabs afterward. ZIP exports now include saved prompts and custom requirements by default, so check the contents again before sharing. Missing historical prompt records are not reconstructed.
-
-The CLI listens on `0.0.0.0` by default and prints LAN URLs and phone QR codes when a network interface is available. Every connected device shares the library and generation permissions; use a trusted LAN. Use `--host 127.0.0.1` (or `SHIQU_BIND_IP=127.0.0.1`) for local-only access without phone QR codes. Keep the computer awake while reading from a phone. This CLI does not provide the desktop app's internet tunnel or native control window.
-
-## Sources and license
+桌面 UI 预览用 `pnpm desktop:preview`，源码目录的 CLI 帮助用 `pnpm cli help --json`。[开发指南](https://github.com/yysun/shiqu/blob/main/.docs/development.md) · [桌面开发与打包](https://github.com/yysun/shiqu/blob/main/desktop/README.md)
 
-The package includes all 24 classical texts, their catalog, and source notices, so first use needs no separate book download. Original project code is Apache-2.0; book sources retain their applicable terms. See `LICENSE`, `NOTICE`, `data/library/source-notices.md`, and `data/library/catalog.json`. Generated stories and illustrations do not inherit the code license automatically.
+## 来源与许可
 
-[Project and full documentation](https://github.com/yysun/shiqu)
+项目原创代码与文档采用 [Apache-2.0](https://github.com/yysun/shiqu/blob/main/LICENSE)，另见 [NOTICE](https://github.com/yysun/shiqu/blob/main/NOTICE)。古典原文遵循各自的[来源许可](https://github.com/yysun/shiqu/blob/main/data/library/source-notices.md)。生成的故事与插图不会自动适用代码许可，分享前请检查[署名与转载说明](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#署名与转载)及 [ZIP 内容](https://github.com/yysun/shiqu/blob/main/.docs/user-guide.md#zip-内容与提示词分享)。