dsh-maoying 0.0.0-stage → 0.1.0

package/docs/creator-panel.md

@@ -0,0 +1,108 @@
+# 毛颖创作台（Web 面板）设计 · v1
+
+三期交付：DSH Web 左侧栏「毛颖创作台」入口 + 会话中栏全页面板 + `/api/maoying/*` 路由。机制与实现全部原创。
+
+## 0. 定位与边界
+
+面板管**可视化与状态**，不管正文创作：小说内容由主编（agent）与作者在编辑器里写，面板负责「一眼看清全局 + 状态快捷流转」。v1 读全量、写少量（状态流转 + 索引重建）；正文编辑不做（那是编辑器和 agent 的活，面板里点「让主编改」提示语即可）。
+
+## 1. 包接线（单包形态，不建子包）
+
+- `package.json`：
+  - `main` 不变（index.mjs，Node 侧 = 安装器 + 创作台路由）；
+  - 新增 `exports["./client"]`: `"./lib/client.js"`；
+  - 新增 `dsh.client`: `{ platform: "web", inject: ["@deepseek-ai/dsh-client-ui-settings", "@deepseek-ai/dsh-client-connection"] }`；
+  - `files` 补 `lib/`（已含）。
+- cordis.patch.yml 不变（bundle insert 已挂主包）。
+- 浏览器 bundle：`window.__ModuleLoader__.load({ id, factory })`，**id 从 currentScript.src 动态解析**（`/\/plugins\/([^/]+)\/client\.js/` 首段），解析不到回退 `'dsh-maoying'`——宿主合并 bundle 下 currentScript 是唯一可靠线索（踩坑教训：宿主合并 bundle 下 id 不可写死）。
+- factory 内 `require('react')` + `require('@deepseek-ai/dsh-client-ui-primitives')`；图标做跨版本兜底可简化：只用 Regular 系（0.1.7+ 命名），旧宿主（≤0.1.6）不承诺。
+- CSS：`lib/base.css` 独立文件，Node 侧 `GET /api/maoying/client.css` 现读下发（no-cache），客户端首次物化幂等注入 `<link data-plugin-css="maoying-creator/base">`——改样式无需重启，GUI 刷新即生效。设计令牌用 `--dsw-alias-*`，深色主题随 `body[data-ds-dark-theme]` 自动跟随。
+
+## 2. Node 侧：/api/maoying/* 路由
+
+注册形态：
+
+```js
+export const inject = ['webServer', 'workspaceRegistry']   // webRuntime 经 ctx.get 读，不进 inject
+webServer.register({ kind: 'prefix', path: '/api/maoying', handler: async (req, res) => {...} })
+```
+
+- **信任围栏**：isTrustedApiRequest 信任围栏（Host 回环或 webRuntime.trustedHosts + 拒 cross-site + origin 同源校验），403 走 `{ error: 'forbidden' }`。读取 trustedHosts 每请求实时 `ctx.get('webRuntime')?.trustedHosts ?? []`，自捕不抛。
+- duplicate prefix route 短重试（8 次 × 30ms）。
+- 所有响应 JSON；错误形状统一 `{ ok: false, error }`（读路由可省 ok，直接 `{ error }` + 状态码）。
+- **路径安全**：凡是带 `path` 参数的请求，必须 resolve 后与 workspaceRegistry 列出的某个 workspace root **严格相等**（不做子路径、不做 ~ 展开）；novel 目录恒为 `<root>/novel`，file 参数 basename 化 + 规范化后必须落在 novel 根内（防穿越）。不满足一律 403。
+- 全程 try/catch，路由崩溃不弄死宿主；注册失败只 warn（安装器语义不变）。
+
+### 路由清单
+
+| 路由 | 方法 | 入参 | 出参 |
+|---|---|---|---|
+| `client.css` | GET | — | text/css（lib/base.css 现读） |
+| `workspaces` | GET | — | `{ ok, workspaces: [{ path, name, hasNovel }] }`——workspaceRegistry.list() 逐根探测 `<root>/novel/project.yml` |
+| `state` | GET | `path=<root>` | 全量快照（见 §3 契约） |
+| `chapter` | GET | `path`, `file`（chapters/ 下文件名） | `{ ok, file, frontmatter, body, outline }`——正文全文 + 对应章纲（`{ file, words, body }`，outlines/ 无对应文件时 null），章节抽屉用 |
+| `chapter-status` | POST | `{ path, file, status }` | `{ ok }`——frontmatter status 行原地替换；status 必须 ∈ pending/writing/review/accepted |
+| `foreshadow-status` | POST | `{ path, id, status }` | `{ ok }`——foreshadows.yml 对应条目 status 行替换；∈ planted/progressing/resolved/abandoned |
+| `phase` | POST | `{ path, phase }` | `{ ok }`——project.yml phase 行替换；七态枚举 |
+| `rebuild-index` | POST | `{ path }` | `{ ok, chapters }`——照 CLI index 同一逻辑重建 index.yml |
+
+写操作全部「行级原地替换」：只在 frontmatter/目标 yml 的对应行上做字符串手术，写前读、写后校验（替换计数 ≠1 即 409 拒写并报错），不做整文件重排——把对 git diff 的扰动压到最小，也与 agent 的写法兼容。
+
+## 3. state 快照契约（前后端共同遵守，字段名冻结）
+
+```jsonc
+{
+  "ok": true,
+  "root": "<workspace root>",
+  "novelDir": "<root>/novel",
+  "found": true,                          // false 时其余字段缺省，面板显示「未初始化」引导
+  "project": { "title","author","genre","length","language","phase","description" },
+  "chapters": [{ "file","volume","num","title","status","words","summary",
+                 "cognitive_frame","emotional_anchor","world_texture",
+                 "suspense","interpersonal_tension" }],     // 按 volume,num 升序；words 为 CJK 计数
+  "characters": [{ "file","name","age","gender","role","appearance","personality",
+                   "background","motivation","arc","markers" }], // markers 数组，缺省 []
+  "relations": [{ "a","b","type","description","intensity","started","ended" }],
+  "foreshadows": [{ "id","title","status","priority","planted_chapter",
+                    "expected_resolve","resolved_chapter","notes","source" }], // source: plan|backfill，缺省 plan
+  "timeline": [{ "year","title","description","importance","chapter" }],
+  "memories": [{ "category","content","source_chapter" }],
+  "clues": [{ "kind","content","related_chapter","resolved" }],
+  "world": [{ "file","category","tags","name","description" }],
+  "science": [{ "file","label","name","description","references" }],
+  "research": [{ "file","topic" }],
+  "outlines": [{ "file","chapter","words","excerpt" }],  // outlines/ 章纲清单，chapter 为对应章节文件名，excerpt 为章纲节选（前 120 字，面板按单写作区块用），无章纲的章不列
+  "totals": { "chapters": 12, "words": 38412,
+              "byStatus": { "pending": 3, "writing": 2, "review": 1, "accepted": 6 } },
+  "generatedAt": "2026-10-19T…Z"
+}
+```
+
+解析层：`lib/panel-core.mjs` 新建，**与 CLI 共享**——把 bin/maoying.mjs 里的 frontmatter 解析 / CJK 计数 / collectChapters / index.yml 重建抽到 `lib/novel-parse.mjs`，CLI 与面板都 import（CLI 行为零变化，改动后跑一遍 CLI 验收）。YAML 解析走 index.mjs 现有 loadYamlLib（dsh home 的 yaml 包），不可用时回退：frontmatter 用正则平键解析，数组 yml 用「条目块 + 平键」极简解析（顶层只允许数组或平键——数据规范本来就禁深嵌套），解析不了的条目跳过并记 `warnings`。
+所有实体字段缺省为 null/[]，绝不让一个坏文件炸掉整个快照；坏文件进 `warnings: ["<file>: <原因>"]`，面板顶部黄条显示。
+
+## 4. 浏览器侧：面板结构
+
+挂载：
+- 左侧栏底部动作位入口「毛颖创作台」（sidebar.footer.action 键控槽，ctx.effect 注入 + MutationObserver 自愈）；
+- 会话中栏全页 overlay：`html[data-dsh-maoying-active]` 驱动，`dsh-panel-activate` 事件与 mnemon/taskboard/ssh 等全页面板互斥，点侧栏会话行自动关闭；
+- 顶部工作区选择器（workspaces 路由取数，hasNovel 的排前；无 novel 工作区显示引导卡：一句 `maoying init` 提示 + 复制按钮）。
+
+八个 tab（顺序即默认排布）：
+
+1. **概览**：project 卡（书名大字 + 类型/篇幅/语言 pills + 阶段徽章 + 简介）；统计卡（总字数/章节数/状态分布条）；最近更新（chapters 按 mtime 前 5）；warnings 黄条。
+2. **章节**：表格（卷-章/标题/状态徽章/字数/梗概），状态筛选 pills；表格上方「按单写作」区块——有章纲且 status=pending 的章按序列出（章纲节选 + 状态徽章，共创模式的主工作清单）；行点击开抽屉：GET chapter 显示正文（只读，等宽滚动）+ 章纲对照栏（左右分栏或折叠段）+ 复制文件路径按钮 + 五维字段卡 + 状态流转按钮（当前态 → 下一态一键，pending→writing→review→accepted）。
+3. **角色**：卡墙（姓名/role 徽章四色/年龄性别/性格一句/动机一行），点击看全卡（含 arc/markers/background）。
+4. **伏笔**：四列看板（埋设/推进/已回收/弃用），卡片含 priority 色点（high 红/normal 灰/low 淡）、`source: backfill` 的「回填」小徽章（账本回填来的条目，区别于写前规划）、埋设章→预期回收章、notes 悬浮；卡片按钮：推进到下一状态（planted→progressing→resolved；abandoned 只能从看板拖不动、按钮给「弃用」）。列头计数。
+5. **关系图**：canvas 力导向图——节点=角色（radius 随出场无关、固定 18px，名字 label 下方），边=relations（intensity 1-5 → 线宽 1-4px，type 标在边中点 hover 显示 description）；拖拽节点、空白处滚轮缩放、双击复位；intensity 缺省 3。角色多于 30 个时只画与 relations 相连的节点，其余进「未入图」列表。
+6. **时间线**：垂直轴，importance 1-5 → 点大小/颜色深浅，year 左列右卡片。
+7. **设定**：world 按 category 分组列表 + science 三色标签（known 绿/extrapolation 黄/hypothesis 紫，标签下 references 链接列表）。
+8. **索引板**：clues 按 kind 分组（线索/红鲱鱼/推理/疑问，resolved 划线置灰）+ memories 按 category 分组（promise 类高亮）。
+
+状态徽章色（全局统一）：pending 灰 / writing 蓝 / review 橙 / accepted 绿；phase 七态沿用七色 pill。文案全中文、禁 emoji 图标（用 ui-primitives 图标或纯 CSS）。
+
+## 5. 验收基线
+
+- Node 侧：临时 workspace（/tmp）+ 假 workspaceRegistry 不行——路由从 ctx.workspaceRegistry 取；单测直接 import lib/panel-core.mjs 的函数（parseStateSnapshot / mutateChapterStatus / mutateForeshadowStatus / mutatePhase / rebuildIndex）跑断言；路由层用 node 起一个最小 ctx 假件（webServer.register 收集 handler，workspaceRegistry 返回临时 root）模拟请求验证围栏 403 / 状态流转 / 防穿越。
+- 浏览器侧：`node --check` 不适用（browser bundle 用 var/require factory 语法）——语法用 `node --input-type=module -e "await import('...')"` 不可行；改用 esbuild？零依赖约束下用「提取 factory 体 + new Function 包裹」的冒烟脚本验证可解析不执行 DOM。至少：括号配平检查 + 手工浏览器验收由用户重启后做。
+- 不写死任何真实路径；测试全在 /tmp；真实 ~/.dsh 不碰。

package/docs/design.md

@@ -0,0 +1,206 @@
+# dsh-maoying（毛颖）设计文档
+
+网文创作辅助 DSH 插件。全部实现原创，以 MIT 发布。
+
+命名：毛颖，典出韩愈《毛颖传》——毛笔拟人得名「毛颖」。
+
+## 1. 核心洞察与架构
+
+常见 AI 小说工具的链路是 LLM → function calling（30+ 工具）→ Express API → SQLite；毛颖走 DSH 里天然更省的一条：
+
+```
+maoying:  agent → glob/grep/read/edit/write → 工作区 novel/ 结构化文件
+```
+
+小说项目 = 一个结构化 markdown/YAML 目录。查「所有未回收伏笔」就是 grep foreshadows.yml，无需 API 层与数据库；人可直接改文件、git 可版本化。
+
+插件形态（一期，无 UI 面板）：
+
+```
+dsh-maoying/
+  package.json            # name: dsh-maoying, engines: dsh >=0.1.7 <0.3, type: module
+  cordis.patch.yml        # bundle insert → 挂载 index.mjs（启动时安装预设）
+  index.mjs               # cordis 插件：启动时 ensurePresetInstalled（幂等）
+  icon.svg
+  presets/maoying/        # 预设源（会被复制到 ~/.dsh/.agent-presets/maoying/）
+    preset.yml            #   name/description/order
+    agent.cordis.yml      #   完整组合：主编人设 + 5 角色委派 + 工具行
+    restrict.mjs          #   主编工具面白名单（system-prompt/assemble 瀑布）
+    delegation-labels.mjs #   委派标签带角色显示名（tools/pre-execute 瀑布）
+  bin/maoying.mjs         # CLI：init / stats / index
+  templates/novel/        # init 脚手架模板
+  docs/                   # design.md（本文）、spec.md（数据规范）
+```
+
+### 安装机制
+
+1. `dsh plugin --profile web add dsh-maoying`：包经 pnpm 装进 profile，包内 cordis.patch.yml 声明 bundle insert（`- insert: [- id: maoying-installer, name: dsh-maoying]`），boot 时并入补丁树。
+2. index.mjs（cordis 插件 main）启动时执行 ensurePresetInstalled：
+   - 解析 dsh home（`DSH_HOME` 或 `~/.dsh`）；
+   - 把 `presets/maoying/` 四个文件复制到 `<home>/.agent-presets/maoying/`（内容或版本变化即覆盖，写入 `.installed-version` 标记）；
+   - 在 `<home>/cordis.patch.yml` 写托管块（`# --- dsh-maoying preset managed (auto-generated; do not edit) ---` 起止标记），内容为声明行：
+
+     ```yaml
+     - insert:
+         - id: preset-maoying
+           name: '@deepseek-ai/dsh-agent-preset'
+           config:
+             id: maoying
+             name: "毛颖创作"
+             description: <preset.yml description>
+             order: 6
+             plugins: <agent.cordis.yml 解析后的完整数组>
+     ```
+
+   - 全程幂等：标记块已存在且版本一致则跳过；不一致则整块替换。YAML 解析/序列化用 `yaml` npm 包（dependencies 声明）。
+   - 按宿主版本自动选委派行形状：≥0.2.1-rc.2 写 v2 AgentPreset 六行块（agent.cordis.v2.yml），否则写 v1 内联单行块；宿主升降级重启即整块切换，不再需要任何降级提示（形态依据见 §8，支持面见 §6）。
+3. 卸载 `dsh plugin remove dsh-maoying` 后：bundle 行消失，托管块与 .agent-presets/maoying/ 需手动删（README 写明两条 rm 命令）。
+
+## 2. 功能裁决（一期范围）
+
+| 功能 | maoying 一期 | 载体 |
+|---|---|---|
+| 项目管理（类型/篇幅/语言） | novel/project.yml | 文件规范 |
+| 7 阶段工作流状态机 | 保留，写 project.yml phase | 主编人设 |
+| Writing 6 步写作法 | 保留改写 | 主编人设（委派映射：大纲→outline、正文→write、审稿→review） |
+| Collab 4 步共创 | 保留改写 | 主编人设 |
+| 五维叙事字段 | 保留（章节 frontmatter 五键） | 文件规范 |
+| 角色卡 + 出场记录 | characters/*.md；出场记录入 memories.yml（category: appearance） | 文件规范 |
+| 世界观 / 科学设定三色 | world/*.md、science/*.md（label: known/extrapolation/hypothesis） | 文件规范 |
+| 伏笔状态机 | foreshadows.yml（planted/progressing/resolved/abandoned + 预期回收章节 + 优先级） | 文件规范 |
+| 时间线 / 叙事记忆（promise）/ 线索板 | timeline.yml / memories.yml / clue-board.yml | 文件规范 |
+| 人物关系图可视化 | relations.yml 纯数据（一期无图） | 文件规范 |
+| 上下文注入（全量角色+章节+伏笔） | 改为按需读：主编先读 index.yml 概览，写到哪章读哪章的上下文（前章结尾+该章大纲+出场角色卡+活跃伏笔） | 主编人设纪律 |
+| AI 工具集 function calling | 天然消失（agent 直接用文件工具） | DSH 架构红利 |
+| 一致性检查（冲突/时间线/伏笔/设定） | review 角色（审校）：四维扫描 + 审稿清单 | 委派角色 |
+| 导出 EPUB/HTML/MD/TXT | **二期**（一期只留 CLI stats/index） | — |
+| Token 用量统计 | 无需（DSH 自带） | — |
+| Web 管理面板 | **三期** | — |
+| 素材考据调研 | **research 角色**：web 检索历史/地理/专业素材，笔记落 novel/research/ | 委派角色（DSH 差异化优势） |
+
+## 3. novel/ 数据规范（决策定稿）
+
+```
+novel/
+  README.md            # 数据规范速查（init 时从模板生成；主编不确定格式时读它）
+  project.yml          # title/author/genre/length/language/phase/description
+  index.yml            # 派生概览（maoying index 重建；主编每次开工先读）
+  volumes.yml          # - {id: v01, title, summary, chapters: "001-020"}
+  chapters/
+    v01-c001.md        # frontmatter: volume/num/title/status/summary + 五维键；
+                       #   正文在 body。status: pending|writing|review|accepted
+  characters/
+    <slug>.md          # frontmatter: name/age/gender/role(protagonist|antagonist|supporting|minor)/
+                       #   appearance/personality/background/motivation/arc/markers[]；body 为备注
+  world/
+    <slug>.md          # frontmatter: category(地点|组织|概念|事件)/tags[]；body 为描述
+  science/
+    <slug>.md          # frontmatter: label(known|extrapolation|hypothesis)/references[]；body
+  relations.yml        # - {a, b, type, description, intensity: 1-5, started, ended}
+  foreshadows.yml      # - {id: fs-001, title, status, priority, planted_chapter,
+                       #    expected_resolve, resolved_chapter, notes}
+  timeline.yml         # - {year, title, description, importance: 1-5, chapter}
+  memories.yml         # - {category: character|location|item|event|promise|appearance|other,
+                       #    content, source_chapter}
+  clue-board.yml       # - {kind: clue|red-herring|deduction|question, content,
+                       #    related_chapter, resolved: bool}
+  research/            # research 角色考据笔记落这里（<topic>.md）
+  exports/             # 二期导出产物
+```
+
+要点：五维字段键名用英文（cognitive_frame / emotional_anchor / world_texture / suspense / interpersonal_tension，YAML 工具安全），值中文；模板文件内注释给中文说明。frontmatter 用 `---` 围栏。所有 yml 顶层是数组或平键，禁止深嵌套——grep 友好。
+
+## 4. 编排预设：主编 + 五帮手
+
+主 agent = 主编（创作总监），带方法论人设；重活委派：
+
+| toolName | 角色 | 干什么 | backgroundMode | 工具面（toolFilter.allow） |
+|---|---|---|---|---|
+| outline | 大纲师 | 卷章规划、章节大纲+五维字段 | continuable | read read_image glob grep write edit bash ask_user_question todo_write |
+| write | 写手 | 章节正文（按大纲写、衔接前章、回报设定变更） | continuable | read read_image glob grep write edit bash ask_user_question todo_write |
+| review | 审校 | 审稿清单 + 四维一致性扫描（只读、出报告不改稿） | one-shot | read read_image glob grep todo_write ask_user_question |
+| lore | 设定管理员 | 章节/角色/世界观/伏笔/时间线/记忆/线索板维护，出场记录与伏笔状态推进 | continuable | read glob grep write edit bash ask_user_question todo_write |
+| research | 素材调研员 | 联网考据（历史/地理/专业领域），笔记落 novel/research/ | one-shot | web_search web_fetch glob grep read write bash ask_user_question todo_write |
+
+主编工具面（restrict.mjs 白名单）：outline write review lore research + send_message list_agents interrupt_agent + glob grep read read_image bash + todo_write ask_user_question get_goal create_goal update_goal exit_plan_mode job_output job_list job_kill。registry deny: ['skill']（堵 ~1.3k 技能目录注入）。
+
+注意：toolFilter.allow 一律不放 mcp__* 工具（子代理创建时 tools.restrict 校验名字必须在注册面，MCP 是否挂载是 host 事实，硬编码会让未装 tavily 的宿主直接建不出子代理）。
+
+delegation-labels 静态角色名映射：{outline: 大纲师, write: 写手, review: 审校, lore: 设定管理员, research: 素材调研员}。
+
+## 5. 主编人设（核心 IP，中文）
+
+persona prefix 内容骨架（agent.cordis.yml 内联，中文书写）：
+
+1. **身份**：网文主编/创作总监，管 project 目录 novel/，重活委派五帮手，自己只做规划、衔接、验收、状态推进。
+2. **开工纪律**：先读 novel/project.yml + index.yml；不确定文件格式读 novel/README.md；不全量读章节，写到哪章读哪章上下文（前章结尾 ~1500 字 + 该章 frontmatter + 出场角色卡 + 活跃伏笔节选）。
+3. **七阶段状态机**（每阶段推进写 project.yml phase）：idea 选题 → setting 设定 → outline 大纲 → writing 写作 → review 审阅 → consistency 一致性 → export 导出。每完成一个里程碑必须推进 phase 并告知用户。
+4. **Writing 六步法**（逐章循环）：
+   ① 衔接检查：读前章结尾，确认无断裂；
+   ② 委派 outline 出/改本章大纲（含五维字段），主编过目；
+   ③ 委派 write 写正文（写手人设要求：按大纲覆盖五维、不写崩人设、章尾留钩子），status→writing；
+   ④ 委派 review 审稿（清单：语言/节奏/人设符合/不剧透/伏笔推进合理/前后矛盾），status→review；
+   ⑤ 审稿问题回 write 修（continuable 就地续修）或主编微调；
+   ⑥ 通过后 status→accepted，委派 lore 做定稿维护（出场记录、伏笔状态、记忆、线索板、时间线），`maoying index` 重建概览。
+   循环检查：还有非 accepted 章节 → 回 ①。
+5. **Collab 四步共创**（新书冷启动）：设定共创（世界观+核心角色卡）→ 分卷规划（volumes.yml + 各卷 summary）→ 前三章交付（黄金三章：第一章立世界观钩子、第二章立主角动机、第三章立核心冲突）→ 交接循环写作（切 Writing 六步法）。
+6. **简短确认即执行**：用户回「ok/可以/继续」直接推进下一步，不再复述确认。
+7. **设定变更上报**：写手回报的临场设定变更（新角色/新地点/伏笔异动）必须经 lore 落盘才算数；发现与既有设定冲突，先停笔报告主编。
+8. **失败处理**：委派失败按 DSH 委派 SOP（diagnose by stop reason，max-tokens 拆章，refusal 换路）。
+
+各帮手 persona 一段话（内联在各委派行），写明本行工具纪律与回报格式（如 review 固定输出四维表格 + 清单勾选）。
+
+## 6. 兼容面
+
+- 支持：DSH 0.1.7 – 0.2.1-rc.1（patch 声明行 + 内联委派行形状）。
+- 0.2.1-rc.2+：dsh-tool-subagent 拒内联 persona/toolFilter——**已适配**：安装器按宿主版本自动切换 v1 内联 / v2 AgentPreset 形状，见 §8 与 README「兼容面」。
+- ≤0.1.6 目录扫描轨道：不做（已淘汰）。
+- 当前开发宿主：0.2.0-rc.2（内联形状 OK）。
+
+## 7. CLI（bin/maoying.mjs，零依赖 node:fs）
+
+- `maoying init [dir]`：从 templates/novel/ 脚手架生成 novel/（已存在文件跳过，绝不覆盖），README.md + 各 yml 带中文注释示例。
+- `maoying stats [dir]`：逐章与总字数（CJK 计数）、状态分布、phase 展示。
+- `maoying index [dir]`：从 chapters/ 重建 index.yml（卷/章/标题/状态/字数/一句话梗概）。
+- 主编人设里写明：定稿维护后跑 `bash bin 不可用`——CLI 经 npx 形态不可靠，改为主编用 node 直跑插件内 CLI？**否**——一期方案：index.yml 由 lore 角色直接重写（文件规范写明格式），CLI index 仅供人工兜底。stats/init 人工用。
+
+## 8. 二期路线
+
+- ✅ **技能包（黄金三章/爽点节奏/审校清单/伏笔管理）**——已做：skills/ 四目录随包分发，安装器复制到 `<home>/skills/maoying-*`（逐字节比较幂等 + .installed-version 标记，见 index.mjs installSkills）。
+- ✅ **导出（MD/TXT/EPUB）**——已做：`maoying export [dir] --format md|txt|epub [--out <目录>]`；EPUB 由 lib/epub.mjs 零依赖打包（手写 stored zip + CRC32 表格法，EPUB 3 最小合法结构）。
+- ✅ **0.2.1-rc.2+ AgentPreset 形态适配**——已做：presets/maoying/agent.cordis.v2.yml（主编 + 5 角色 preset 的 v2 组合源）+ index.mjs composeManagedRows 按宿主版本双形态切换（v1 内联 / v2 AgentPreset，宿主升降级重启即整块换形状；防漂移由 test/composition.test.mjs 逐字节断言，见 README「兼容面」）。
+- ✅ **Web 创作台面板**——已做：/api/maoying/* 八条路由 + 左侧栏入口 + 会话中栏全页面板，八视图（概览/章节/角色/伏笔看板/关系图/时间线/设定/索引板）；设计与契约见 docs/creator-panel.md。
+
+## 9. 五期：共创模式（作者亲笔稿）
+
+定位：作者自己写正文，毛颖从「代笔」转「备料 + 审稿 + 记账」。P0 改流程与规范，P1 补工具。
+
+### 9.1 模式开关
+
+project.yml 加 `mode` 字段：`ai-draft`（默认，现状）/ `co-write`（逐章指派谁写）/ `author-draft`（全书作者写）。章节 frontmatter 可选 `writer: author | ai`（co-write 下用；缺省按 mode 推）。
+
+### 9.2 主编共创流程（author-draft / co-write 的 author 章）
+
+- **永不代写**：主编不产出章节正文，不委派 write 写 author 章；
+- 循环：大纲师出下一章章纲 → 作者自写 → 作者交稿（贴文或说「第 X 章写完了」）→ 主编收稿：review 意见清单 + lore 账本回填 + 重建 index.yml + 汇报本章伏笔/时间线变动 → 出再下一章章纲；
+- co-write 下主编动笔前必须问清本章归谁；author-draft 下 write 角色闲置是正常态。
+
+### 9.3 章纲 outlines/
+
+`novel/outlines/vXX-cXXX.md`，**纯 markdown 无 frontmatter**（作者编辑器里打开不碍眼）：本章目标、节拍、出场角色、需埋/需收伏笔、与前章接口。大纲师产物、作者创作输入、review 收稿时的对照基准。不入 index.yml，面板与 brief 现查现拼。
+
+### 9.4 账本回填（lore 收稿流程）
+
+作者正文偏离章纲是常态，账本必须跟正文走：lore 读新稿 → 提取**实际发生**的伏笔埋设/回收、时间线事件、新关系、承诺线、线索 → 更新五本账；foreshadows.yml 条目加可选 `source: plan | backfill`（缺省 plan，回填的标 backfill）。使用约定：novel/ 纳 git，账本变动看 diff。
+
+### 9.5 作者稿圣域（全部模式生效）
+
+- `chapters/` 正文唯作者可改；agent 在 author-draft / co-write 的 author 章上只许动 frontmatter 的 summary / 五维字段，且以建议为先；
+- review 输出意见清单，不改稿（工具面本就只读，人设立规矩）；
+- ai-draft 章节不受此限（write 照旧）。
+
+### 9.6 P1 工具
+
+- `maoying brief <dir> <章号>` 写作卡：章纲 + 前章结尾约 1500 字 + 出场角色卡 + 活跃伏笔节选，打成一个 md（stdout 或 --out）。给作者带去任意编辑器/其他 AI；
+- `maoying check <dir>` 静态体检（**不调模型**——LLM 审校走主编）：frontmatter 完整性、五维缺键、状态枚举、章号/卷号规范、伏笔章号引用存在性、时间线年份乱序、角色卡悬空引用；
+- 面板三件：章节抽屉加章纲对照栏 + 复制文件路径按钮；伏笔看板卡上 `source: backfill` 显示「回填」徽章；章节 tab 顶部「按单写作」区块（有章纲且 status=pending 的章，按序列章纲节选）。

package/docs/spec.md

@@ -0,0 +1,133 @@
+# novel/ 数据规范（完整版）
+
+本文是 `templates/novel/README.md`（速查版）的扩写：给每个文件补上设计理由与边界约定。日常查阅用速查版即可；改机制、起争议时以本文为准。速查版与本文冲突时，以本文为准并回报仓库 issue。
+
+## 0. 设计理由：为什么是文件而不是 SQLite
+
+常见做法是 LLM → function calling → Express API → SQLite；毛颖砍成 agent → 文件工具 → `novel/` 目录。这不是省事，是同一种创作负载下的更优解：
+
+- **查询形态匹配**。小说创作的查询是「所有未回收伏笔」「这个角色出场过几章」「v01 的时间线」——全是 grep 一行的事，不需要 JOIN，更不需要 ORM。SQLite 的强项（并发写、随机读、事务）在单人单会话的写作流里用不上。
+- **人机共读**。作者随时打开 foreshadows.yml 看账本、手改一个错字；数据库要做到同样的事得先写一层 UI 或 CLI——而文件天然免费。
+- **git 即版本控制**。整本书的历史就是目录的历史：哪一章改了什么、伏笔账本何时被谁推进，`git log -p` 一目了然；回滚一章就是回滚一个文件。SQLite 的 blob 历史在 git 里是噪音。
+- **零迁移零运维**。schema 演进 = 在 README 里补两行说明 + 旧文件照读；没有 migration 脚本，没有锁文件，没有「数据库被另一个进程占用」。
+- **上下文按需取**。主编不全量读章节：先读 index.yml 概览，写到哪章读哪章的上下文（前章结尾 + 该章 frontmatter + 出场角色卡 + 活跃伏笔节选）。文件粒度就是天然的上下文裁剪单元。
+
+什么时候该换数据库：多人同时写同一本书、单书章节数到千级、需要全文检索正文以外的高级查询。一期都不在诉求内。
+
+## 1. 总约束
+
+- **所有 yml 顶层是数组或平键，禁止深嵌套**。深嵌套的 YAML 人读着费劲、diff 噪音大、grep 不到——「查所有 high 优先级伏笔」必须能靠 `grep -A3 'priority: high' foreshadows.yml` 完成。需要表达从属关系时用键值引用（slug、章节号），不要用嵌套结构。
+- **frontmatter 用 `---` 围栏**，键值一行一个、简单标量；正文（body）在第二个 `---` 之后。frontmatter 键名用英文（工具安全），值用中文。
+- **枚举一律全称**，见速查版「总原则」一节；新增枚举值属于规范变更，须同步本文与主编人设。
+- **index.yml 是派生文件**，任何手工改动都会被 `maoying index` 或 lore 角色覆盖。
+- 章节文件名 `v<卷号2位>-c<章号3位>.md`；frontmatter 的 `volume`/`num` 与文件名一致（CLI 与 index 重建以文件名为主键，frontmatter 为辅）。
+
+## 2. 逐文件规范
+
+字段与最小示例见速查版（`templates/novel/README.md`），此处只补约定：
+
+### project.yml
+`phase` 七态 `idea|setting|outline|writing|review|consistency|export` 只能由主编推进（帮手不得越权改），且必须顺序推进不可跳越；推进时主编须向用户简报。`language` 影响写手与审校的语言纪律（如 `zh` 不允许成段外文）。`mode` 三值决定正文归谁写：`ai-draft`（缺省，AI 代笔，主编走 Writing 六步法）/ `co-write`（逐章指派谁写，主编动笔前先问清本章归谁）/ `author-draft`（全书作者亲笔，主编只备料、审稿、记账，永不代写）。文件里没有 `mode` 键的旧项目一律按 `ai-draft` 处理。
+
+### volumes.yml
+`id` 与章节文件名前缀严格一致（`v01` ↔ `chapters/v01-cXXX.md`），index.yml 的卷分组按本文件顺序输出。`chapters` 范围写法 `001-020` 是给人看的计划值，运行时以章节文件实况为准。
+
+### chapters/vXX-cXXX.md
+- `status` 流转 `pending → writing → review → accepted`，由主编控制：写手只允许把 `pending/writing` 置为 `writing`，审校不改状态，`accepted` 之前的放行是主编的裁决。
+- 五维叙事字段（写手按大纲覆盖、审校逐项对照）：
+  - `cognitive_frame` 认知框架：本章读者的认知被如何推动——抛出什么信息差、制造什么误解、在哪里顿悟。防止「读者全知视角写惊悚」的经典翻车。
+  - `emotional_anchor` 情感锚点：本章要锚定的情绪与共情对象。网文的核心交付是情绪，不是情节；情节为情绪服务。
+  - `world_texture` 世界质感：本章着墨的世界细节层面（风物/规矩/器物/习俗）。逐章小剂量投放，避免设定集中倾泻。
+  - `suspense` 具体悬念：本章悬念与章尾钩子的问题化表述（必须是「读者会问出的问题」，不是「作者知道的事实」）。
+  - `interpersonal_tension` 人际张力：本章人物关系中的压力与变化（谁与谁的矛盾升温/缓和/变质）。
+- 五维字段在大纲阶段（outline 角色）写定、写作阶段（write 角色）覆盖、审校阶段（review 角色）对照——三处都用同一组键，这就是「按大纲写」的可检查形态。
+- 可选 `writer` 键（co-write 用）：`author | ai`，记本章正文归谁写；缺省按 project.yml 的 `mode` 推——`author-draft` 下整本按 author、`ai-draft` 下整本按 ai。键只做记录与面板展示，状态机仍看 `status`。
+
+### outlines/vXX-cXXX.md
+章纲：共创模式（`co-write` / `author-draft`）下大纲师给作者的创作输入，与章节文件一一对应（`outlines/v01-c005.md` ↔ `chapters/v01-c005.md`）。**纯 markdown、无 frontmatter**——作者会在任意编辑器里打开它，`---` 围栏只会碍眼（第 1 节「frontmatter 用围栏」的总约束不适用本目录）。五件内容写全：本章目标、节拍（场景推进顺序与情绪起伏）、出场角色（谁上场、各带什么目的）、需埋/需收伏笔（对照 foreshadows.yml 报 id）、与前章接口（从哪个钩子接、结尾钩到哪）。颗粒度标准：作者拿着就能动笔，不写「参见大纲」式的空转。
+
+约定：章纲是计划不是章节事实，**不入 index.yml**（index 只索引章节实况），面板与 `maoying brief` 现查现拼。谁写谁读：大纲师写，作者读，review 收稿时对照评偏离——作者没照章纲写不算错，偏离如实报给主编裁决，账本永远跟正文走。
+
+### characters/<slug>.md
+`role` 四态 `protagonist|antagonist|supporting|minor`。`markers`（辨识标记）是审校盯人设的抓手：口癖、习惯动作、禁忌。角色卡一经 `accepted` 章节引用，改动须过主编（写手发现需要新设定时上报，不得自行改卡）。
+
+### world/<slug>.md
+`category` 用中文四类 `地点|组织|概念|事件`（值是给人和 agent 读的，中文检索更直接）；`tags` 供 grep 圈定范围。
+
+### science/<slug>.md
+三色标注：`known`（史实/公理，写了不算错）→ `extrapolation`（从 known 合理推演，读者能接受）→ `hypothesis`（自设假说，全书内部自洽即可）。审校的「设定一致性」扫描以此分级裁判：违反 known 是硬伤，hypothesis 之间打架按主编裁决。`references` 指向依赖的其他设定 id 或现实出处，形成可追溯的设定依赖链。
+
+### relations.yml
+`a`/`b` 用角色 slug；`intensity` 1-5 是给大纲师排戏剧权重的启发值。关系结束（`ended` 填章节号）不删条目——历史关系是审校查「已死角色复活」类 bug 的依据。
+
+### foreshadows.yml
+伏笔状态机语义：
+
+```
+planted ──→ progressing ──→ resolved
+   │              │
+   └──────────────┴────→ abandoned
+```
+
+- `planted` 埋设：已在正文出现、读者可感知，`planted_chapter` 必填；
+- `progressing` 推进：有中间揭示/强化，多章长线伏笔的常态；
+- `resolved` 回收：兑现完成，`resolved_chapter` 必填，且不得早于 `planted_chapter`；
+- `abandoned` 弃用：明确决定不回收（不是遗忘）——`notes` 里写弃用原因；被遗忘的伏笔不走 abandoned，由 consistency 阶段的审校捞出、主编决定补收或弃用；
+- 转移只按上图的边走；`resolved`/`abandoned` 是终态，回退（如 resolved 又翻案）须主编操作并在 `notes` 记一行；
+- `expected_resolve` 是排期承诺：写作推进到预期章节附近仍未回收时，主编须向用户报告并决定顺延或弃用；
+- 活跃伏笔（planted + progressing）超过 15 条时主编主动提醒清理——账本膨胀是长篇烂尾的第一征兆；
+- 可选 `source` 键：`plan | backfill`，缺省 `plan`。`plan` 是章纲/大纲阶段计划登记的伏笔；`backfill` 是共创收稿时 lore 从作者正文里回填认领的——作者正文偏离章纲是常态，账本必须跟正文走，实际发生了计划外的埋设/回收就补登并标 `backfill`，面板据此挂「回填」徽章区分计划内与回填。
+
+### timeline.yml
+记故事内时间（`year` 用故事内纪年），不是写作顺序；`chapter` 把事件锚回正文。审校的「时间线一致性」扫描就是对照本表与章节正文。
+
+### memories.yml
+叙事记忆 = 正文里已成立的事实账。约定：
+
+- **出场记录**：`category: appearance`，一章一条记「谁在哪章登场」；主角每章都记（审校查隐身主角），配角记首次登场与关键回场；
+- **承诺**：`category: promise`，角色说出口的承诺逐条记账——读者记得每一句「我一定会回来」，审校查兑现；
+- 只记已写进正文的事实；计划中的事记在章节 frontmatter 或 foreshadows.yml，不进记忆；
+- 不改动既有条目（写错了由主编裁决后修正，留 notes 说明）。
+
+### clue-board.yml
+`kind` 四类：`clue`（线索）`red-herring`（误导）`deduction`（推理）`question`（悬问）。`resolved: true` 表示该线索的戏剧功能已兑现——误导被揭示、悬问被解答、推理被验证。红鲱鱼（red-herring）必须有意埋设，`content` 里写明「误导什么、真答案是什么」，防止审校误报。
+
+### research/ 与 exports/
+`research/<topic>.md` 由素材调研员（research 角色）独占写入；frontmatter 记 `topic` 与 `sources`（URL 列表），body 是可直接用于写作的结论要点，区分史实/通说/演义并逐条附来源。`exports/` 一期只建目录，导出能力在二期。
+
+### 作者稿圣域（共创模式）
+`chapters/` 目录的正文唯作者可改。author-draft / co-write 的 author 章节上，agent（主编与帮手）只可更新 frontmatter 的 `summary` 与五维字段，且以建议为先、动笔前说明；review 一律只出意见清单不改稿。`ai-draft` 章节不受此限，write 照旧。
+
+收稿循环（author-draft / co-write 的 author 章）：作者交稿 → review 出意见清单 → lore 按正文回填五本账（foreshadows / timeline / relations / memories / clue-board）并重建 index.yml → 主编向作者汇报本章伏笔/时间线/关系变动 → 大纲师出下一章章纲。
+
+使用约定：`novel/` 建议纳入 git——账本变动看 diff，lore 回填动了哪条一目了然；作者对某笔回填不认可，`git checkout` 对应文件即是回滚。
+
+## 3. index.yml（派生）
+
+由 lore 角色按本节格式重建，或人工跑 `maoying index` 兜底。格式：
+
+```yaml
+# index.yml —— 派生文件，可由 lore 角色或 `maoying index` 重建；手工改动会被覆盖。
+volumes:
+  - id: v01
+    title: 第一卷 北境风雪
+    summary: 卷定位一句话
+    chapters:
+      - {num: 1, title: 雪夜来客, status: accepted, words: 3210, summary: 一句话梗概}
+orphans:
+  - {volume: v02, num: 5, title: 未归卷章, status: writing, words: 1200, summary: ...}
+total: {chapters: 21, words: 65210, accepted: 18}
+```
+
+- 卷分组照 volumes.yml 顺序；卷内章节按章号升序；章节行一行一条（num/title/status/words/summary），grep 友好；
+- 不在任何卷里的章节落 `orphans`（带 volume 键）——主编每次开工扫一眼 orphans 就知道归档欠账；
+- `total` 汇总全书：章节数、CJK 总字数、已定稿章数；
+- 重建是全量覆盖、确定性输出（不含时间戳），产物可进 git 且 diff 干净。
+
+## 4. CLI 与本规范的关系
+
+- `maoying init` 生成上述全部骨架（已存在文件绝不覆盖）；
+- `maoying stats` 读 project.yml + chapters/，报告逐章 CJK 字数、状态分布、当前 phase；
+- `maoying index` 是第 3 节重建逻辑的人工兜底（主编的日常路径是让 lore 角色直接重建）。
+
+三者都零依赖，解析器只认本规范的两类形态（平键映射、顶层数组）；深度嵌套不在支持范围——这是规范约束的执行手段之一。

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" role="img" aria-label="毛颖">
+  <!-- 毛笔笔杆 -->
+  <path d="M19.6 4.4c.9.9.9 2.4 0 3.3l-7.2 7.2-3.4 1.1a.55.55 0 0 1-.7-.7l1.1-3.4 7.2-7.2c.9-.9 2.4-.9 3 0Z"/>
+  <!-- 蘸墨的笔锋 -->
+  <path d="M9 11.6c-2 .5-3.5 2-4.3 4.5-.3 1.1-.5 2.2-.5 3 .8 0 1.9-.2 3-.5 2.5-.8 4-2.3 4.5-4.3"/>
+  <!-- 纸上墨痕 -->
+  <path d="M4.5 20.5h9.5"/>
+</svg>