dsh-maoying 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lifangjin
+
+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.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# dsh-maoying（毛颖）
 
-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.
+毛颖者，笔也——韩愈作《毛颖传》，把一支毛笔写成有封地有爵位的臣子。dsh-maoying 把这支笔装进 DSH（DeepSeek Harness）：**一支管着一班帮手、守着一摞书稿的毛笔**——网文创作辅助插件，全部实现原创，MIT 发布。
+
+装上之后，主 agent 变身**网文主编（创作总监）**：带七阶段工作流与六步写作法，把大纲、正文、审校、设定维护、素材考据分别委派给五个只带本行工具的帮手；整部小说就是工作区里的 `novel/` 结构化 markdown/YAML 目录（角色卡、伏笔状态机、时间线、线索板、叙事记忆）——agent 直接读写文件，**没有数据库，没有 API 层**。查「所有未回收伏笔」就是 grep 一行。
+
+## 功能特性
+
+- **主编 + 五帮手**：主 agent 当主编，只做规划、衔接、验收、状态推进；大纲师（outline）、写手（write）、审校（review）、设定管理员（lore）、素材调研员（research）各带本行工具随叫随到。找文件、查伏笔状态这类顺手小事主编自己 glob/grep 就办，不绕委派。
+- **novel/ 文件数据库**：角色卡、世界观、科学设定三色标注、关系图、伏笔账本、时间线、叙事记忆、线索板，全部是 grep 友好的平键/顶层数组 YAML——人可直接改，git 可版本化，无迁移无运维。
+- **七阶段工作流**：idea 选题 → setting 设定 → outline 大纲 → writing 写作 → review 审阅 → consistency 一致性 → export 导出。阶段记在 project.yml 的 phase 键，每完成一个里程碑主编推进并简报。
+- **Writing 六步法**：衔接检查 → 出大纲 → 写正文 → 审稿 → 修改 → 定稿维护，逐章循环；配合 Collab 四步共创（设定共创 → 分卷规划 → 黄金三章 → 交接循环）把新书从零带到滚动更新。
+- **伏笔状态机**：planted（埋设）→ progressing（推进）→ resolved（回收）/ abandoned（弃用），埋设与回收记章节号、预期回收章节排期、优先级分档——长篇不断线，活跃伏笔超 15 条主编主动提醒清理。
+- **上下文按需取**：主编先读 index.yml 概览，写到哪章读哪章（前章结尾约 1500 字 + 该章大纲 + 出场角色卡 + 活跃伏笔节选），不把整本书塞进上下文。
+- **工具面收窄**：主编只见「角色委派 + 内部检索 + 协调」白名单，帮手各带本行工具（审校只读、考据只带联网+落笔记）；每次请求的工具开销与上下文占用随之下降。
+- **素材考据**：research 帮手联网检索历史/地理/专业领域素材，笔记落 `novel/research/`，区分史实/通说/演义并附来源——DSH 架构的红利。
+- **CLI 兜底**：`maoying init / stats / index` 三条零依赖命令管脚手架、字数统计与章节概览重建。
+
+## 快速开始
+
+前置：**Node.js ≥ 18**、已装好的 DSH host（**0.1.7+**，见「兼容面」）。
+
+官方插件通道——一条命令，装完重启即用：
+
+```bash
+dsh plugin --profile web add dsh-maoying
+```
+
+**重启 DSH（`dsh web`）**：插件启动时自动把预设装进 `~/.dsh/.agent-presets/maoying/`，并在 `~/.dsh/cordis.patch.yml` 写好声明行托管块，无需再点任何按钮。新会话的预设选择器里选「**毛颖创作 (Maoying)**」即可开写；要设为默认，在 Settings → Agent Presets 里选。
+
+开发检出（想改插件或预设源码）用 link 形态直连仓库，改动经重启生效：
+
+```bash
+git clone https://github.com/lifangjin/dsh-maoying.git
+dsh plugin --profile web add link:"$PWD/dsh-maoying"
+```
+
+## 怎么用
+
+选好预设后，对主编说话即可，它按工作流自己路由：
+
+**开新书（Collab 四步共创）**：
+
+> 我想写一本东方玄幻，主角靠「听懂器物说话」的金手指鉴宝升级。
+
+主编与你对齐题材与基调，委派设定管理员建核心角色卡与世界观条目，委派大纲师做分卷规划，然后把黄金三章（立世界钩子、立主角动机、立核心冲突）写出来交付。
+
+**逐章写作（Writing 六步法）**：
+
+> 第三章可以开写了吗？
+
+主编做衔接检查，委派大纲师出本章大纲（含五维叙事字段），过目后派写手写正文、审校审稿（清单 + 四维一致性扫描），有问题回写手修，通过后置 accepted 并委派设定管理员做定稿维护——你只需要在决策点拍板。
+
+**集中审查**：
+
+> 前 20 章做一次一致性检查。
+
+主编推进 phase 到 consistency，审校扫描冲突/时间线/伏笔/设定四维，问题按严重度排好交回写手。
+
+用户回「ok / 可以 / 继续」即视为确认，主编直接推进，不复述确认。
+
+## 共创模式（作者亲笔）
+
+不是谁都想让 AI 代笔。project.yml 的 `mode` 键决定正文归谁写，三种模式一句话：`ai-draft`（默认）AI 代笔，走 Writing 六步法；`co-write` 逐章指派谁写，主编动笔前先问清本章归谁；`author-draft` 全书作者亲笔，毛颖只备料、审稿、记账，永不代写。
+
+author-draft 下的协作循环——你只管写，交稿即接管杂务：
+
+> 第 5 章写完了，贴给你。（正文直接粘进对话，或者说一声第 X 章写完、指个文件）
+
+主编收稿后你会拿到三样东西：**审校意见清单**（只挑问题、不代改，改不改随你）、**账本回填**（伏笔/时间线/关系/记忆/线索五本账按你正文实际发生的记，计划外的改动也能认领，来源标 `backfill`）、**下一章章纲**（`novel/outlines/vXX-cXXX.md`，拿着就能写）。圣域纪律：`chapters/` 正文唯作者可改，agent 至多更新 frontmatter 的 summary 与五维字段，且先建议后动手。
+
+配套命令：`maoying brief <dir> <章号>` 打包写作卡（章纲 + 前章结尾 + 角色卡 + 活跃伏笔，带去任意编辑器或其他 AI），`maoying check <dir>` 做零模型静态体检（frontmatter 完整性、伏笔章号引用、时间线乱序等，不调模型——LLM 审校走主编）。
+
+## 方法论技能
+
+随插件带 4 个网文方法论技能，插件启动时安装器把它们落盘到 `~/.dsh/skills/`（即 `<home>/skills/`）下的 `maoying-*` 四个目录，宿主技能面板可直接看到；大纲师、写手、审校、设定管理员按场景自动加载，你不用手动操作：
+
+| 技能 | 一句话说明 |
+|---|---|
+| maoying-golden-opening | 黄金三章：前三章职能分工（世界钩子 → 动机确立 → 冲突引爆）、前 300 字出事原则、信息释放纪律与自检清单 |
+| maoying-beat-pacing | 爽点节奏：爽点类型库、压抑-释放配比、单章/中/大三级节奏曲线与章尾钩子选型 |
+| maoying-review-checklist | 审校清单：语言/节奏/人设/逻辑/伏笔/剧透六层逐项检查，按 P0/P1/P2 三档严重度输出 |
+| maoying-foreshadow-discipline | 伏笔管理：埋设即登记、推进节奏排期、回收「意外 + 合理」标准与台账清理阈值 |
+
+安装器只认 `maoying-*` 前缀目录，`~/.dsh/skills/` 下你自己的技能一个字节不动。卸载插件后技能目录需手动清理（四目录一起删）：
+
+```bash
+dsh plugin --profile web remove dsh-maoying
+rm -rf "${DSH_HOME:-$HOME/.dsh}/skills/"maoying-*
+```
+
+## novel/ 数据规范
+
+`novel/` 目录是整个插件的数据库：project.yml（元信息与七阶段 phase）、volumes.yml、chapters/（frontmatter 五维叙事字段 + 正文）、characters/（角色卡）、world/、science/（三色设定）、relations.yml、foreshadows.yml（伏笔状态机）、timeline.yml、memories.yml（含出场记录与承诺账）、clue-board.yml、research/、exports/。全部格式、示例与设计理由见：
+
+- 速查版：项目初始化后的 `novel/README.md`（模板源 [templates/novel/README.md](templates/novel/README.md)）
+- 完整版：[docs/spec.md](docs/spec.md)（为什么不用 SQLite、五维字段定义、伏笔状态机语义、出场记录约定）
+
+## CLI
+
+```bash
+maoying init [dir]     # 生成 novel/ 脚手架（默认 ./novel；已存在文件一律跳过，绝不覆盖）
+maoying stats [dir]    # 逐章 CJK 字数、状态分布、当前 phase
+maoying index [dir]    # 从 volumes.yml + chapters/ 重建 index.yml（派生文件）
+maoying export [dir]   # 导出全书：--format md|txt|epub（默认 md），--out <目录> 改输出位置
+```
+
+export 示例：
+
+```bash
+maoying export novel                      # Markdown，落到 novel/exports/
+maoying export novel --format txt         # 纯文本
+maoying export novel --format epub        # EPUB 3（零依赖打包，可直接导入阅读器）
+maoying export novel --format epub --out ~/Downloads   # 换输出目录
+```
+
+输出目录默认 `<dir>/exports/`，文件名 `<书名>-<YYYYMMDD>.<扩展名>`（书名取 project.yml 的 title）；章节解析与 stats/index 同一套逻辑，frontmatter 不会混进正文。
+
+零依赖（node:fs/path/url/crypto），任意 cwd 可用；npm 全局安装或 `pnpm link` 后可直接 `maoying` 调用，否则 `node <插件目录>/bin/maoying.mjs` 等价。日常写作中 index.yml 由设定管理员直接重建，CLI 主要给人用。
+
+## 卸载
+
+```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-*
+```
+
+宿主是 DSH 0.1.7+ 时再补一步：删去 `~/.dsh/cordis.patch.yml` 里的 dsh-maoying 托管块（`# --- dsh-maoying preset managed (auto-generated; do not edit) ---` 到 `# --- end dsh-maoying preset managed ---` 之间的整段，含两行标记），免得留下指向已删目录的声明行。`novel/` 目录是你的书稿，卸载插件不会动它。
+
+## 兼容面
+
+插件启动时读宿主版本（`<home>/node_modules/@deepseek-ai/dsh/package.json`），按版本自动选择委派行形状——**宿主升级后重启即切换，无需重装插件**：
+
+- **DSH 0.1.7 – 0.2.1-rc.1 → v1 内联形状**：5 个角色委派行直接内联 persona 与 toolFilter，托管块 1 条声明行。
+- **DSH 0.2.1-rc.2+ → v2 AgentPreset 形状**：该版本起 dsh-tool-subagent 拒绝内联 persona/toolFilter，插件改用 [presets/maoying/agent.cordis.v2.yml](presets/maoying/agent.cordis.v2.yml)——托管块写 6 条声明行（主编 preset + 大纲师/写手/审校/设定管理员/素材调研员 5 张角色 preset），主编委派行以 `agentPreset` 指向角色 preset，角色的工具面由 preset 里的实体工具行承载（审校只读、考据带联网检索）。
+- **角色预设会出现在预设选择器**（宿主对预设没有隐藏机制），name 带「（内部）」标明：日常写作由主编委派自动选用，不经主编、想单独开一个写手/考据会话时直接选中即可。
+- 两种形状的 persona 文本同源逐字一致（[test/composition.test.mjs](test/composition.test.mjs) 逐字节把关）；宿主版本读不到时保守按 v1 处理。
+- ≤0.1.6 的目录扫描轨道：不做（宿主已淘汰）。
+
+## 许可
+
+[MIT](LICENSE) © 2026 lifangjin
+
+## 致谢
+
+- 「毛颖」得名于韩愈《毛颖传》：毛笔拟人，有封地有爵位。

package/bin/maoying.mjs

@@ -0,0 +1,456 @@
+#!/usr/bin/env node
+/**
+ * maoying — 毛颖网文创作项目 CLI（init / stats / index / export / brief / check）
+ *
+ * 零依赖：只用 node:fs / node:path / node:url / node:crypto，模板目录经
+ * import.meta.url 定位，任意 cwd 可用。novel/ 目录的数据规范见
+ * templates/novel/README.md（或已初始化项目里的 novel/README.md）。
+ *
+ *   maoying init [dir]    生成 novel/ 脚手架（默认 ./novel；已存在文件跳过，绝不覆盖）
+ *   maoying stats [dir]   逐章字数（CJK 计数）、状态分布、当前 phase
+ *   maoying index [dir]   从 volumes.yml + chapters/ 重建 index.yml（派生文件）
+ *   maoying export [dir]  导出全书：--format md|txt|epub（默认 md）、--out <目录>
+ *   maoying brief [dir] <chapter> [--out <文件>]
+ *                         组装某章写作卡（章纲+前章结尾+出场角色卡+活跃伏笔）
+ *   maoying check [dir]   静态体检（不调模型）：frontmatter/枚举/章号/伏笔引用等
+ *
+ * 子命令出错 exit 1，中文报错。
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { buildEpub } from '../lib/epub.mjs'
+// 解析层与面板共用（lib/novel-parse.mjs）；parseFlatYamlArray 沿用旧名
+// parseSimpleYaml，保持本文件其余代码原样不动。
+import { buildBrief, buildIndexYaml, checkProject, collectChapters, parseFlatYamlArray as parseSimpleYaml } from '../lib/novel-parse.mjs'
+
+const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const TEMPLATE_DIR = path.join(PLUGIN_ROOT, 'templates', 'novel')
+
+/** 七阶段工作流（与 project.yml 的 phase 枚举一致）。 */
+const PHASES = {
+  idea: '选题',
+  setting: '设定',
+  outline: '大纲',
+  writing: '写作',
+  review: '审阅',
+  consistency: '一致性',
+  export: '导出',
+}
+
+/** 章节状态机（frontmatter status 枚举；带中文标签，展示用）。 */
+const STATUSES = [
+  ['pending', '待写'],
+  ['writing', '写作中'],
+  ['review', '审阅中'],
+  ['accepted', '已定稿'],
+]
+
+// ── 基础工具 ────────────────────────────────────────────────────────────────
+
+/** 中文报错 + exit 1。 */
+function fail(message) {
+  console.error(`maoying: ${message}`)
+  process.exit(1)
+}
+
+/** 读文本文件；读不到返回 null。 */
+function readTextOrNull(file) {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+// ── init ────────────────────────────────────────────────────────────────────
+
+/** 递归复制模板树；已存在文件跳过（绝不覆盖），返回 {created, skipped} 相对路径清单。 */
+function copyTemplateTree(srcDir, destDir, relBase = '') {
+  const created = []
+  const skipped = []
+  mkdirSync(destDir, { recursive: true })
+  for (const entry of readdirSync(srcDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const rel = relBase === '' ? entry.name : `${relBase}/${entry.name}`
+    const src = path.join(srcDir, entry.name)
+    const dst = path.join(destDir, entry.name)
+    if (entry.isDirectory()) {
+      const sub = copyTemplateTree(src, dst, rel)
+      created.push(...sub.created)
+      skipped.push(...sub.skipped)
+    } else if (existsSync(dst)) {
+      skipped.push(rel)
+    } else {
+      copyFileSync(src, dst)
+      created.push(rel)
+    }
+  }
+  return { created, skipped }
+}
+
+function cmdInit(targetArg) {
+  if (!existsSync(TEMPLATE_DIR)) fail(`模板目录缺失：${TEMPLATE_DIR}（插件包不完整？）`)
+  const dest = path.resolve(targetArg ?? 'novel')
+  const { created, skipped } = copyTemplateTree(TEMPLATE_DIR, dest)
+  console.log(`毛颖脚手架 → ${dest}`)
+  for (const rel of created) console.log(`  创建 ${rel}`)
+  for (const rel of skipped) console.log(`  跳过 ${rel}（已存在，未覆盖）`)
+  console.log(`完成：新建 ${created.length} 个文件，跳过 ${skipped.length} 个。`)
+  console.log('数据规范见 novel/README.md；动手前先填 novel/project.yml。')
+}
+
+// ── stats ───────────────────────────────────────────────────────────────────
+
+function cmdStats(targetArg) {
+  const root = path.resolve(targetArg ?? 'novel')
+  const chapters = collectChapters(root)
+  if (chapters === null) fail(`找不到 ${path.join(root, 'chapters')}——先跑 maoying init ${root}`)
+
+  const project = parseSimpleYaml(readTextOrNull(path.join(root, 'project.yml')))
+  const phase = project !== null && typeof project.phase === 'string' && project.phase !== '' ? project.phase : null
+  const phaseText = phase === null ? '未设置（缺 project.yml 或 phase 键）' : `${phase}（${PHASES[phase] ?? '未知阶段'}）`
+
+  console.log(`小说统计：${root}`)
+  console.log(`阶段：${phaseText}`)
+  console.log('')
+
+  if (chapters.length === 0) {
+    console.log('章节（0）：chapters/ 下还没有章节文件')
+  } else {
+    console.log(`章节（${chapters.length}）：`)
+    for (const ch of chapters) {
+      const statusLabel = STATUSES.find(([s]) => s === ch.status)?.[1] ?? ch.status
+      // 文件名合规范时 stem（v01-c001）即唯一标识；不合规范再补 meta 卷号/章号
+      const id = ch.sortKey !== null ? ch.stem : `${ch.volume || 'v??'} c${String(ch.num ?? 0).padStart(3, '0')}`
+      console.log(`  ${ch.stem.padEnd(10)} ${id !== ch.stem ? `(${id}) ` : ''}${ch.title}  [${statusLabel}]  ${ch.words} 字`)
+    }
+  }
+
+  const counts = Object.fromEntries(STATUSES.map(([s]) => [s, 0]))
+  let total = 0
+  for (const ch of chapters) {
+    counts[ch.status] += 1
+    total += ch.words
+  }
+  console.log('')
+  console.log(`状态分布：${STATUSES.map(([s, label]) => `${s}（${label}）${counts[s]}`).join(' · ')}`)
+  console.log(`总字数：${total}（CJK 计数）`)
+}
+
+// ── index ───────────────────────────────────────────────────────────────────
+
+// index.yml 的拼装逻辑在 lib/novel-parse.mjs 的 buildIndexYaml（与创作台
+// rebuild-index 路由共用），这里只负责读卷表、落盘与汇报。
+
+function cmdIndex(targetArg) {
+  const root = path.resolve(targetArg ?? 'novel')
+  const chapters = collectChapters(root)
+  if (chapters === null) fail(`找不到 ${path.join(root, 'chapters')}——先跑 maoying init ${root}`)
+  const volumesRaw = parseSimpleYaml(readTextOrNull(path.join(root, 'volumes.yml')))
+  const { text, volumesCount, chaptersCount, orphansCount, totalWords } = buildIndexYaml(chapters, volumesRaw)
+  const indexPath = path.join(root, 'index.yml')
+  writeFileSync(indexPath, text, 'utf8')
+  console.log(`已重建 ${indexPath}：${volumesCount} 卷、${chaptersCount} 章（总字数 ${totalWords}）、未归卷 ${orphansCount} 章。`)
+}
+
+// ── export ──────────────────────────────────────────────────────────────────
+
+/** 支持的导出格式（--format 取值）。 */
+const EXPORT_FORMATS = ['md', 'txt', 'epub']
+
+/**
+ * 导出文件名里的书名清洗：路径非法字符 /\\:*?"<>| 一律替换掉，再去首尾
+ * 空白与点（Windows 上尾点会吞扩展名）。清完为空兜回「未命名书稿」。
+ */
+function sanitizeTitleForFile(title) {
+  const cleaned = String(title ?? '')
+    .replace(/[/\\:*?"<>|]/g, '')
+    .replace(/^[.\s]+|[.\s]+$/g, '')
+  return cleaned !== '' ? cleaned : '未命名书稿'
+}
+
+/** 卷标题映射：volumes.yml 的 id → title；文件缺失/不合规返回空映射。 */
+function volumeTitleMap(root) {
+  const raw = parseSimpleYaml(readTextOrNull(path.join(root, 'volumes.yml')))
+  const list = Array.isArray(raw) ? raw.filter((v) => v !== null && typeof v === 'object' && !Array.isArray(v)) : []
+  const map = new Map()
+  for (const v of list) {
+    const id = String(v.id ?? '')
+    if (id !== '' && typeof v.title === 'string' && v.title !== '') map.set(id, v.title)
+  }
+  return map
+}
+
+/** 卷号还原：'v01' → 1；不合规范的卷 id 返回 null（该卷跳过卷层）。 */
+function volumeNumber(volume) {
+  const m = /^v(\d+)$/.exec(String(volume ?? ''))
+  return m === null ? null : Number(m[1])
+}
+
+/**
+ * 正文分段：空行为段界；段内多行去首尾空白后直接拼接（中文行间不加空格）。
+ * md/txt 的正文与 epub 的 <p> 共用这一套。
+ */
+function bodyParagraphs(body) {
+  const paragraphs = []
+  let current = []
+  for (const rawLine of String(body ?? '').split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (line === '') {
+      if (current.length > 0) paragraphs.push(current.join(''))
+      current = []
+    } else {
+      current.push(line)
+    }
+  }
+  if (current.length > 0) paragraphs.push(current.join(''))
+  return paragraphs
+}
+
+/**
+ * 章节展示信息（md/txt/epub 三格式共用）：卷层、章标题、分段正文。
+ * 章标题形如「卷X-章Y 章节标题」；卷 id 不合规范或章节无卷信息时退为
+ * 「章Y 章节标题」，卷层记 null（导出时跳过卷层）。章号缺省用全书序号。
+ */
+function chapterDisplay(ch, ordinal, volTitles) {
+  const volNum = volumeNumber(ch.volume)
+  const chNum = Number.isInteger(ch.num) ? ch.num : ordinal
+  const volPart = volNum !== null ? `卷${volNum}-章${chNum}` : `章${chNum}`
+  return {
+    volume: volNum !== null ? { num: volNum, title: volTitles.get(ch.volume) ?? '' } : null,
+    heading: `${volPart} ${ch.title}`.trim(),
+    body: ch.body,
+    paragraphs: bodyParagraphs(ch.body),
+  }
+}
+
+/** 按相邻同卷分组（保持章序）：[{ volume, chapters: [display] }]，无卷组 volume 为 null。 */
+function groupByVolume(chapters, volTitles) {
+  const groups = []
+  let current = null
+  chapters.forEach((ch, i) => {
+    const display = chapterDisplay(ch, i + 1, volTitles)
+    const rawVolume = ch.volume ?? ''
+    if (current === null || current.rawVolume !== rawVolume) {
+      current = { rawVolume, volume: display.volume, chapters: [] }
+      groups.push(current)
+    }
+    current.chapters.push(display)
+  })
+  return groups
+}
+
+/** 卷层标题：`卷1 卷名`；无卷名只留 `卷1`。 */
+function volumeHeading(volume) {
+  return volume.title !== '' ? `卷${volume.num} ${volume.title}` : `卷${volume.num}`
+}
+
+/** md：`# 书名` + 卷层 `## 卷N 卷名` + 每章 `### 卷X-章Y 标题` + 正文原文。 */
+function renderMarkdown(title, groups) {
+  const lines = [`# ${title}`, '']
+  for (const group of groups) {
+    if (group.volume !== null) lines.push(`## ${volumeHeading(group.volume)}`, '')
+    for (const display of group.chapters) {
+      lines.push(`### ${display.heading}`, '', display.body.trim(), '')
+    }
+  }
+  return `${lines.join('\n').replace(/\n+$/, '')}\n`
+}
+
+/** txt：纯文本；书名/卷名/章标题独立成行（章标题前空一行），段间空行。 */
+function renderText(title, groups) {
+  const lines = [title]
+  for (const group of groups) {
+    if (group.volume !== null) lines.push('', volumeHeading(group.volume))
+    for (const display of group.chapters) {
+      lines.push('', display.heading, '', display.paragraphs.join('\n\n'))
+    }
+  }
+  return `${lines.join('\n').replace(/\n+$/, '')}\n`
+}
+
+function cmdExport(args) {
+  let dirArg = null
+  let format = 'md'
+  let outArg = null
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--format' || arg === '--out') {
+      const value = args[++i]
+      if (value === undefined) fail(`选项 ${arg} 缺参数——--format 取 md|txt|epub，--out 取输出目录`)
+      if (arg === '--format') format = value
+      else outArg = value
+    } else if (arg.startsWith('--format=')) {
+      format = arg.slice('--format='.length)
+    } else if (arg.startsWith('--out=')) {
+      outArg = arg.slice('--out='.length)
+    } else if (arg.startsWith('-')) {
+      fail(`未知选项「${arg}」——export 只认 --format md|txt|epub 与 --out <目录>`)
+    } else if (dirArg === null) {
+      dirArg = arg
+    } else {
+      fail(`多余的位置参数「${arg}」——export 只接受一个项目目录`)
+    }
+  }
+  if (!EXPORT_FORMATS.includes(format)) fail(`未知导出格式「${format}」——支持 ${EXPORT_FORMATS.join(' / ')}`)
+
+  const root = path.resolve(dirArg ?? 'novel')
+  const chapters = collectChapters(root)
+  if (chapters === null) fail(`找不到 ${path.join(root, 'chapters')}——先跑 maoying init ${root}`)
+  if (chapters.length === 0) fail('没有可导出的章节')
+
+  const project = parseSimpleYaml(readTextOrNull(path.join(root, 'project.yml')))
+  const rawTitle =
+    project !== null && typeof project.title === 'string' && project.title.trim() !== '' ? project.title.trim() : ''
+  const title = rawTitle !== '' ? rawTitle : '未命名书稿'
+  const author =
+    project !== null && typeof project.author === 'string' && project.author.trim() !== ''
+      ? project.author.trim()
+      : '佚名'
+
+  const groups = groupByVolume(chapters, volumeTitleMap(root))
+  const now = new Date()
+  const stamp = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}`
+  const outDir = path.resolve(outArg ?? path.join(root, 'exports'))
+  const outPath = path.join(outDir, `${sanitizeTitleForFile(rawTitle)}-${stamp}.${format}`)
+
+  let content
+  if (format === 'md') {
+    content = renderMarkdown(title, groups)
+  } else if (format === 'txt') {
+    content = renderText(title, groups)
+  } else {
+    content = buildEpub({
+      title,
+      author,
+      uuid: randomUUID(),
+      chapters: groups.flatMap((group) => group.chapters),
+    })
+  }
+
+  mkdirSync(outDir, { recursive: true })
+  writeFileSync(outPath, content)
+  const totalWords = chapters.reduce((sum, ch) => sum + ch.words, 0)
+  console.log(`导出完成：${path.resolve(outPath)}`)
+  console.log(`格式 ${format}；${chapters.length} 章，总字数 ${totalWords}（CJK 计数）。`)
+}
+
+// ── brief ───────────────────────────────────────────────────────────────────
+
+/**
+ * maoying brief [dir] <chapter> [--out <文件>]
+ *
+ * 组装某章写作卡（章纲 + 前章结尾 + 出场角色卡 + 活跃伏笔 + 本章状态），
+ * 给作者带去任意编辑器/其他 AI。不带 --out 时写卡打到 stdout，提示与提醒
+ * 走 stderr，重定向出去的就是干净的卡；带 --out 落盘。组装逻辑在
+ * lib/novel-parse.mjs 的 buildBrief（与面板共用解析层）。
+ */
+function cmdBrief(args) {
+  let dirArg = null
+  let chapterArg = null
+  let outArg = null
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--out') {
+      const value = args[++i]
+      if (value === undefined) fail('选项 --out 缺参数——--out 取输出文件路径')
+      outArg = value
+    } else if (arg.startsWith('--out=')) {
+      outArg = arg.slice('--out='.length)
+    } else if (arg.startsWith('-')) {
+      fail(`未知选项「${arg}」——brief 只认 --out <文件>`)
+    } else if (chapterArg !== null) {
+      fail(`多余的位置参数「${arg}」——brief 只接受 [dir] <chapter> 两个位置参数`)
+    } else if (dirArg === null) {
+      dirArg = arg
+    } else {
+      chapterArg = arg
+    }
+  }
+  if (dirArg === null && chapterArg === null) {
+    fail('用法：maoying brief [dir] <chapter> [--out <文件>]——chapter 可写文件名（v01-c002.md）、stem（v01-c002）、「卷-章」（1-2）或裸章号（2）')
+  }
+  // 只给一个位置参数时把它当章号用（dir 走默认 ./novel），这是常用路径
+  const root = path.resolve(chapterArg === null ? 'novel' : dirArg)
+  const brief = buildBrief(root, chapterArg ?? dirArg)
+  if (!brief.ok) fail(brief.reason)
+  for (const warning of brief.warnings) console.error(`提醒：${warning}`)
+  if (outArg !== null) {
+    const outPath = path.resolve(outArg)
+    mkdirSync(path.dirname(outPath), { recursive: true })
+    writeFileSync(outPath, brief.text, 'utf8')
+    console.log(`写作卡已写入：${outPath}`)
+    console.log('拿去写，写完丢回给主编收稿。')
+  } else {
+    process.stdout.write(brief.text)
+    console.error('—— 写作卡到这儿为止。拿去写，写完丢回给主编收稿。')
+  }
+}
+
+// ── check ───────────────────────────────────────────────────────────────────
+
+/**
+ * maoying check [dir]
+ *
+ * 静态体检：只查文件规范，不调模型（LLM 审校走主编）。检查逻辑在
+ * lib/novel-parse.mjs 的 checkProject。有 error 退出码 1，只有 warn 退出码 0。
+ */
+function cmdCheck(targetArg) {
+  const root = path.resolve(targetArg ?? 'novel')
+  const result = checkProject(root)
+  console.log(`静态体检：${root}（只查文件规范，不调模型）`)
+  if (result.problems.length === 0) {
+    console.log('未发现问题。')
+  } else {
+    for (const p of result.problems) {
+      console.log(`${p.level === 'error' ? '[错误]' : '[提醒]'} ${p.file}：${p.message}`)
+    }
+  }
+  const { chapters, outlines, foreshadows, problems } = result.summary
+  console.log(`汇总：${chapters} 章、${outlines} 章纲、${foreshadows} 条伏笔；错误 ${problems.error} 个，提醒 ${problems.warn} 个。`)
+  if (!result.ok) process.exit(1)
+}
+
+// ── 入口 ────────────────────────────────────────────────────────────────────
+
+const HELP_TEXT = `毛颖（maoying）—— 网文创作项目 CLI
+
+用法：
+  maoying init [dir]     生成 novel/ 脚手架（默认 ./novel；已存在的文件一律跳过，绝不覆盖）
+  maoying stats [dir]    逐章字数（CJK 计数）、状态分布、当前阶段
+  maoying index [dir]    从 volumes.yml + chapters/ 重建 index.yml（派生文件）
+  maoying export [dir]   导出全书：--format md|txt|epub（默认 md），--out <目录> 改输出位置
+  maoying brief [dir] <chapter>
+                         组装某章写作卡（章纲+前章结尾+出场角色卡+活跃伏笔）；--out <文件> 落盘，缺省打到 stdout
+  maoying check [dir]    静态体检（不调模型）：frontmatter 完整性、枚举值、章号卷号一致、伏笔章号引用、时间线年份、关系卡引用
+
+说明：
+  novel/ 目录的数据规范见 templates/novel/README.md（或项目内 novel/README.md）。
+  export 输出目录默认 <dir>/exports/，文件名 <书名>-<YYYYMMDD>.<扩展名>。
+  brief 的 chapter 可写文件名（v01-c002.md）、stem（v01-c002）、「卷-章」（1-2）或裸章号（2）。
+  check 有 error 退出码 1，只有 warn 退出码 0。
+  所有命令零依赖，任意 cwd 可用；出错时退出码 1。`
+
+function main(argv) {
+  const [command, ...rest] = argv
+  if (command === '--help' || command === '-h' || command === 'help') {
+    console.log(HELP_TEXT)
+    return
+  }
+  if (command === 'init') return cmdInit(rest[0])
+  if (command === 'stats') return cmdStats(rest[0])
+  if (command === 'index') return cmdIndex(rest[0])
+  if (command === 'export') return cmdExport(rest)
+  if (command === 'brief') return cmdBrief(rest)
+  if (command === 'check') return cmdCheck(rest[0])
+  if (command === undefined) {
+    console.error('maoying: 缺少子命令（init / stats / index / export / brief / check，--help 看用法）')
+    process.exit(1)
+  }
+  fail(`未知子命令「${command}」——可用：init / stats / index / export / brief / check（--help 看用法）`)
+}
+
+main(process.argv.slice(2))

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-maoying bundle patch — `dsh plugin --profile <name> add dsh-maoying` 时由
+# reconcilePlugins 并入该 profile 的 dsh.profile.bundles，boot 时并入补丁树。
+# name: dsh-maoying 指向 pnpm 装进 profile 的本包（main: index.mjs）。
+- insert:
+    - id: maoying-installer
+      name: dsh-maoying