dsh-maoying 0.1.12 → 0.1.13

package/README.en.md

@@ -0,0 +1,169 @@
+# dsh-maoying (Maoying)
+
+[中文](README.md) | English
+
+**Maoying** literally means "the brush" — in *Maoying Zhuan* (毛颖传, "The Biography of the Brush"), Han Yu wrote a writing brush as a courtier with a fief and a title. dsh-maoying fits that brush into DSH (DeepSeek Harness): **a brush that manages a crew of helpers and guards a stack of manuscripts** — a web-novel writing assistant plugin, fully original, released under MIT.
+
+Once installed, the main agent becomes the **editor-in-chief of your novel**: it runs a seven-phase workflow with a six-step writing method, delegating outlining, drafting, review, lore-keeping and research to five helpers who each carry only their own tools. The whole novel is a structured markdown/YAML `novel/` directory in the workspace (character cards, foreshadowing state machine, timeline, clue board, narrative memory) — agents read and write files directly, **no database, no API layer**. "Show all unresolved foreshadowing" is one line of grep.
+
+## Features
+
+- **Editor-in-chief + five helpers**: the main agent plans, connects, reviews and advances states; the outliner (outline), writer (write), reviewer (review), lore keeper (lore) and researcher (research) each carry their own tools. Trivial errands like finding a file or checking a foreshadow status, the chief handles itself with glob/grep.
+- **novel/ as a file database**: character cards, worldbuilding & science settings with three-color tags, relations graph, foreshadow ledger, timeline, narrative memory, clue board — all grep-friendly flat-key/top-level-array YAML, human-editable, git-versioned, no migrations, no ops.
+- **Seven-phase workflow**: idea → setting → outline → writing → review → consistency → export. The phase lives in the `phase` key of project.yml; the chief advances it at each milestone and reports to you.
+- **Writing six-step method**: continuity check → outline → draft → review → revision → finalization, looping per chapter; paired with the Collab four-step co-writing flow (setting co-creation → volume planning → golden three chapters → handoff loop) it takes a new book from zero to rolling updates.
+- **Foreshadowing state machine**: planted → progressing → resolved / abandoned, with planting and payoff chapter numbers, expected-payoff scheduling and priority tiers — a long serial never drops a thread; past 15 active foreshadowing entries the chief proactively suggests cleanup.
+- **Context on demand**: the chief reads index.yml for the big picture, then pulls only what the chapter at hand needs (previous chapter's ending ≈1500 chars + its outline + on-stage character cards + active foreshadow excerpts) — never the whole book.
+- **Narrow tool surface**: the chief sees only "role delegation + internal retrieval + coordination"; helpers carry their line's tools (reviewer read-only, researcher web+notes only) — less per-request tool overhead and context weight.
+- **Research**: the research helper searches the web for historical/geographic/domain material, files notes under `novel/research/`, separating fact from common lore from legend, with sources — a dividend of the DSH architecture.
+- **Creator panel**: a full-page web panel from the DSH sidebar — Overview / Chapters / Characters / Foreshadowing / Relations / Timeline / Worldbuilding / Index Board / Novel Settings; full-page chapter reading (outline side-by-side + five-dimension fields + status flow), form-based project.yml editing, UI language (中文/English), six font-size steps, and automatic new-version detection.
+- **CLI fallback**: `maoying init / stats / index / export / brief / check` — six zero-dependency commands for scaffolding, stats, index rebuild, export, per-chapter writing cards and static checks.
+
+## Quick Start
+
+Prerequisites: **Node.js ≥ 18** and an installed DSH host (**0.1.7+**, see "Compatibility").
+
+The official plugin channel — one command, then restart:
+
+```bash
+dsh plugin --profile web add dsh-maoying
+```
+
+**Restart DSH (`dsh web`)**: at startup the plugin installs the preset into `~/.dsh/.agent-presets/maoying/` and writes the managed declaration block into `~/.dsh/cordis.patch.yml` — no buttons to press. Pick "**毛颖创作 (Maoying)**" in the preset selector of a new session; to make it default, select it in Settings → Agent Presets.
+
+For a development checkout (you want to modify the plugin or preset sources), link the repo directly; changes take effect after a restart:
+
+```bash
+git clone https://github.com/lifangjin/dsh-maoying.git
+dsh plugin --profile web add link:"$PWD/dsh-maoying"
+```
+
+Only want the command-line tool, without the plugin? The zero-dependency CLI works standalone via `npx`, or as a global command (both npm channels, independent of the plugin):
+
+```bash
+npx maoying init                 # run without installing
+npm install -g dsh-maoying       # or install a global maoying command
+```
+
+## How to Use
+
+With the preset selected, just talk to the chief; it routes by the workflow itself:
+
+**Start a new book (Collab four-step co-writing)**:
+
+> I want to write an Eastern fantasy where the protagonist's golden finger is hearing objects speak and appraising treasures to level up.
+
+The chief aligns genre and tone with you, delegates core character cards and worldbuilding to the lore keeper, volume planning to the outliner, then has the golden three chapters (world hook, protagonist motivation, core conflict) written and delivered.
+
+**Per-chapter writing (Writing six-step method)**:
+
+> Can we start chapter 3?
+
+The chief runs the continuity check, has the outliner produce the chapter outline (with the five narrative dimensions), and after your sign-off sends it to the writer, then the reviewer (checklist + four-dimension consistency scan); issues go back to the writer; once accepted, the lore keeper does finalization upkeep — you only call the shots at decision points.
+
+**Consistency pass**:
+
+> Run a consistency check over the first 20 chapters.
+
+The chief advances the phase to consistency; the reviewer scans four dimensions — conflicts / timeline / foreshadowing / settings — and returns issues ranked by severity.
+
+A reply of "ok / sure / go on" counts as confirmation; the chief advances directly without echoing it back.
+
+## Creator Panel
+
+Open "**毛颖创作台**" at the bottom of the DSH sidebar — a full-page cockpit for the human eye, beyond what agents do:
+
+- **Chapters**: status filters + the writing queue; click a chapter for full-page reading — back button, outline side-by-side (Markdown rendered), read-only manuscript, five narrative-dimension fields, one-click status flow.
+- **Novel Settings**: form-based editing of project.yml — title / author / genre / planned length / language / workflow phase / co-writing mode / synopsis; saving preserves the file's existing comments.
+- **Top bar**: current version always visible; a "new version ↗" badge links to the release page when npm has a newer one; the gear opens Settings — UI language (中文/English), six font-size steps (100%–150%), all applied immediately and remembered.
+
+The panel only writes state (chapter status, project.yml, index.yml rebuilds), never prose — prose belongs to the author and the chief.
+
+## Co-writing Mode (Author Writes)
+
+Not everyone wants AI ghostwriting. The `mode` key in project.yml decides who writes the prose — three modes in one line each: `ai-draft` (default) AI drafts via the Writing six-step method; `co-write` assigns a writer per chapter, and the chief asks who writes before touching the pen; `author-draft` the author writes the whole book, and Maoying only preps, reviews and keeps the books — never ghostwrites.
+
+The author-draft loop — you just write, hand it over, and the chores are taken care of:
+
+> Chapter 5 is done, here it is. (paste the text, or just say chapter X is done and point at a file)
+
+After receiving a manuscript you get three things: a **review checklist** (issues only, no rewriting — applying them is up to you), a **ledger backfill** (foreshadowing / timeline / relations / memory / clue board recorded from what your text actually does, even off-plan changes, tagged `backfill`), and the **next chapter outline** (`novel/outlines/vXX-cXXX.md`, ready to write from).
+
+Companion commands: `maoying brief <dir> <chapter>` packs a per-chapter writing card (outline + previous ending + character cards + active foreshadowing — carry it to any editor or AI), and `maoying check <dir>` runs a zero-model static check (frontmatter completeness, foreshadow chapter references, timeline ordering — no model calls; LLM review goes through the chief).
+
+## Methodology Skills
+
+The plugin ships 4 web-novel methodology skills. At startup the installer drops four `maoying-*` directories under `~/.dsh/skills/` (i.e. `<home>/skills/`) where the host's skill panel lists them; the outliner, writer, reviewer and lore keeper load them by scenario — no manual steps:
+
+| Skill | One-liner |
+|---|---|
+| maoying-golden-opening | Golden three chapters: role split of the first three chapters (world hook → motivation → conflict detonation), the "something happens in the first 300 words" rule, information-release discipline and a self-check list |
+| maoying-beat-pacing | Payoff pacing: a payoff-type library, suppression-release ratios, chapter/arc/book pacing curves and chapter-end hook selection |
+| maoying-review-checklist | Review checklist: six layers (language / pacing / characterization / logic / foreshadowing / spoilers) with P0/P1/P2 severity |
+| maoying-foreshadow-discipline | Foreshadow management: register on planting, pacing & scheduling, the "surprising yet reasonable" payoff bar, and ledger cleanup thresholds |
+
+The installer only touches `maoying-*` prefixed directories; your own skills under `~/.dsh/skills/` are untouched, byte for byte. After uninstalling the plugin, remove the skill directories manually (all four together):
+
+```bash
+dsh plugin --profile web remove dsh-maoying
+rm -rf "${DSH_HOME:-$HOME/.dsh}/skills/"maoying-*
+```
+
+## The novel/ Data Spec
+
+The `novel/` directory is the plugin's entire database: project.yml (metadata + seven-phase state), volumes.yml, chapters/ (frontmatter five narrative dimensions + prose), characters/ (character cards), world/, science/ (three-color settings), relations.yml, foreshadows.yml (the state machine), timeline.yml, memories.yml (with appearance records and the promise ledger), clue-board.yml, research/, exports/. Full formats, examples and design rationale:
+
+- Quick reference: `novel/README.md` after project init (template source: [templates/novel/README.md](templates/novel/README.md))
+- Full spec: [docs/spec.md](docs/spec.md) (why not SQLite, five-dimension field definitions, foreshadow state-machine semantics, appearance-record conventions)
+
+## CLI
+
+```bash
+maoying init [dir]     # scaffold novel/ (default ./novel; existing files are always skipped, never overwritten)
+maoying stats [dir]    # per-chapter CJK counts, status breakdown, current phase
+maoying index [dir]    # rebuild index.yml from volumes.yml + chapters/ (derived file)
+maoying export [dir]   # export the book: --format md|txt|epub (default md), --out <dir> to change destination
+maoying brief [dir] <chapter>  # pack a per-chapter writing card (outline + previous ending + character cards + active foreshadowing); --out to write to disk, stdout by default
+maoying check [dir]    # static check (no model calls): frontmatter / enums / chapter numbers / foreshadow refs / timeline years / relation-card refs
+```
+
+Export examples:
+
+```bash
+maoying export novel                      # Markdown, into novel/exports/
+maoying export novel --format txt         # plain text
+maoying export novel --format epub        # EPUB 3 (zero-dependency packaging, importable into readers)
+maoying export novel --format epub --out ~/Downloads   # different destination
+```
+
+The output directory defaults to `<dir>/exports/`, file name `<title>-<YYYYMMDD>.<ext>` (title from project.yml); chapter parsing shares the same logic as stats/index, so frontmatter never leaks into prose.
+
+Zero dependencies (node:fs/path/url/crypto), runs from any cwd. Install one of three ways: `npm install -g dsh-maoying`, on-demand `npx maoying <command>`, or `npm link` on a dev machine (repo checkout, edits take effect immediately). With none of these, `node <plugin dir>/bin/maoying.mjs` is equivalent (a dsh plugin install also drops the package into the profile, so you can point there directly). In day-to-day writing the lore keeper rebuilds index.yml directly; the CLI is mainly for humans.
+
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-maoying
+rm -rf "${DSH_HOME:-$HOME/.dsh}/.agent-presets/maoying"
+rm -rf "${DSH_HOME:-$HOME/.dsh}/skills/"maoying-*
+```
+
+On DSH 0.1.7+ also delete the dsh-maoying managed block in `~/.dsh/cordis.patch.yml` (the whole section between `# --- dsh-maoying preset managed (auto-generated; do not edit) ---` and `# --- end dsh-maoying preset managed ---`, markers included), so no declaration lines point at a deleted directory. The `novel/` directory is your manuscript — uninstalling never touches it.
+
+## Compatibility
+
+At startup the plugin reads the host version (`<home>/node_modules/@deepseek-ai/dsh/package.json`) and picks the delegation-line shape automatically — **after a host upgrade, a restart is all it takes; no reinstall**:
+
+- **DSH 0.1.7 – 0.2.1-rc.1 → v1 inline shape**: the 5 role delegation lines inline persona and toolFilter; the managed block is 1 declaration line.
+- **DSH 0.2.1-rc.2+ → v2 AgentPreset shape**: from that version dsh-tool-subagent rejects inline persona/toolFilter, so the plugin switches to [presets/maoying/agent.cordis.v2.yml](presets/maoying/agent.cordis.v2.yml) — the managed block writes 6 declaration lines (chief-in-chief preset + 5 role presets: outliner / writer / reviewer / lore keeper / researcher); the chief's delegation line points at the role presets via `agentPreset`, and each role's tool surface is carried by the preset's entity tool lines (reviewer read-only, researcher with web search).
+- **Role presets appear in the preset selector** (the host has no hiding mechanism for presets); their names carry "（内部）" to mark them: in daily writing they are picked automatically via chief delegation, but you can also select a writer/researcher directly for a session without the chief.
+- Both shapes share persona text byte-for-byte from one source ([test/composition.test.mjs](test/composition.test.mjs) guards it); if the host version can't be read, the plugin falls back to v1 conservatively.
+- The ≤0.1.6 directory-scan track: not supported (the host dropped it).
+
+## License
+
+[MIT](LICENSE) © 2026 lifangjin
+
+## Acknowledgments
+
+- "Maoying" comes from Han Yu's *Maoying Zhuan* (毛颖传): a writing brush personified, with a fief and a title.

package/README.md

@@ -1,5 +1,7 @@
 # dsh-maoying（毛颖）
 
+中文 | [English](README.en.md)
+
 毛颖者，笔也——韩愈作《毛颖传》，把一支毛笔写成有封地有爵位的臣子。dsh-maoying 把这支笔装进 DSH（DeepSeek Harness）：**一支管着一班帮手、守着一摞书稿的毛笔**——网文创作辅助插件，全部实现原创，MIT 发布。
 
 装上之后，主 agent 变身**网文主编（创作总监）**：带七阶段工作流与六步写作法，把大纲、正文、审校、设定维护、素材考据分别委派给五个只带本行工具的帮手；整部小说就是工作区里的 `novel/` 结构化 markdown/YAML 目录（角色卡、伏笔状态机、时间线、线索板、叙事记忆）——agent 直接读写文件，**没有数据库，没有 API 层**。查「所有未回收伏笔」就是 grep 一行。
@@ -73,7 +75,7 @@ DSH 左侧栏底部点「**毛颖创作台**」打开全页面板（改文件、
 
 - **章节**：状态筛选 + 按单写作清单；点章节进整页阅读——返回按钮、章纲对照（Markdown 渲染）、只读正文、五维叙事字段、一键状态流转。
 - **小说设置**：project.yml 的书名/作者/题材/篇幅/语言/工作流阶段/共创模式/简介表单化编辑，保存保留文件里原有注释。
-- **顶栏**：当前版本号常驻；npm 上有新版时亮「有新版 ↗」徽章直连发布页；齿轮打开系统设置，字号五档（100%–200%）整体缩放并记忆。
+- **顶栏**：当前版本号常驻；npm 上有新版时亮「有新版 ↗」徽章直连发布页；齿轮打开系统设置，界面语言中文/English 可切、字号六档（100%–150%）整体缩放，均立即生效并记忆。
 
 面板只写状态（章节状态、project.yml、index.yml 重建），不改正文——正文永远归作者与主编。
 

package/docs/creator-panel.md

@@ -116,14 +116,16 @@ webServer.register({ kind: 'prefix', path: '/api/maoying', handler: async (req,
 
 状态徽章色（全局统一）：pending 灰 / writing 蓝 / review 橙 / accepted 绿；phase 七态沿用七色 pill。文案全中文、禁 emoji 图标（用 ui-primitives 图标或纯 CSS）。
 
-## 4.1 后续迭代记录（0.1.10 – 0.1.12）
+## 4.1 后续迭代记录（0.1.10 – 0.1.13）
 
 - **MaskPortal**：抽屉/弹层统一 portal 到 `document.body`——面板容器挂在宿主会话中栏，中栏 transform/overflow 会把 `position: fixed` 劫持成相对自身并连同裁剪（桌面端「点了没反应」实测病灶）；无 createPortal 的老宿主退回原地渲染。
 - **顶栏版本区**：当前版本号常驻；`update-check` 路由（模仿 dsh-paoding：npm registry → npmmirror → GitHub 三级源，1h 缓存 + 7 天 stale-if-error，全败静默）发现新版时亮「有新版 ↗」徽章。
-- **系统设置**：齿轮弹窗，字号五档（100/120/150/180/200%）——面板根与 portal 节点读同一 `--myt-zoom` 变量整体 zoom，localStorage 记忆。
+- **系统设置**：齿轮弹窗，字号六档（100/110/120/130/140/150%）——面板根与 portal 节点读同一 `--myt-zoom` 变量整体 zoom，localStorage 记忆。
+- **界面语言**：系统设置可选中文/English——全部 UI 文案走 `I18N` 词典（zh/en 各 209 条，`tt`/`tf` 取词 + `{x}` 插值，zh 值与历史硬编码逐字一致保证中文界面零回归），切换立即生效整树重渲并 localStorage 记忆；语言自称（中文/日本語）与侧栏入口品牌名不翻译。
 - **Markdown 渲染**：零依赖渲染器（先整体转义再变换），章纲对照与世界观/科学设定描述不再裸显 md 源码；正文手稿仍走 pre。
 - **章节整页阅读**：替代右侧抽屉（侧边栏遮挡问题），返回按钮 + 章纲对照 + 五维 + 状态流转原位保留；阅读态隐藏 tab 条。
 - **小说设置 tab**（第 9 个）：project.yml 平键表单化编辑，`POST project-save` → `mutateProject` 逐键改写保行尾注释、缺键按模板补齐、phase/mode 越枚举与空书名 422。
+- **字号六档改百分比**（0.1.13）：档位从中文名（小/标准/大…）改为 100/110/120/130/140/150% 直读，旧 localStorage 档位值回落 100%。
 
 ## 5. 验收基线