@chengzhao-dev/dsh-quarto-book

dsh plugin --profile web add @chengzhao-dev/dsh-quarto-book

dsh-quarto-book



English | 简体中文

把一份 Quarto Book 从章节写到可发布：writing-quarto 负责章节骨架、整书次序与中文行文，designing-theme 负责主题；渲染后由 quarto_render_check 判断 HTML 是否可发布，quarto_pass_report 给出收尾回执。两个技能只在 type: book 的仓库里出现，运行需要 Quarto CLI 与 Python 3。

提供什么

名称 · 用途 · 不做什么

writing-quarto · 新建或修改 content/**/*.qmd、index.qmd、_quarto.yml；章节骨架、中文行文、代码与图表、内容检查 · 不改 CSS、字体和颜色

designing-theme · 调整主题的 CSS、SCSS、字体、palette、导航与 Callout 样式 · 不改章节正文

quarto_render_check · 先判断 output-dir 是否安全，再按需渲染一次，检查 _book/ 里的 HTML 是否可发布 · 不改 .qmd，不自动修配置，不重复渲染

quarto_pass_report · 收尾时把执行结论压成固定行数的回执卡片：技能、模式、改过的文件与步骤、未改项、检查结论 · 不保存到磁盘，不贴章节原文，不据回执改文章

两个技能从包内 skills/ 目录发现，按需加载；技能里的相对路径以技能目录为基准：writing-quarto 用 steps/、writing/、writing/examples/、quarto/、scripts/，designing-theme 用 theme/、assets/、scripts/。

快速开始

1. 安装插件：

   dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@latest

2. 在书仓库里打开会话。_quarto.yml 要有独立一行的 type: book，书根至少有一个 .qmd 或 .md 章节源文件；两个技能名这时才会出现。

3. 调用技能：写正文用 writing-quarto，改主题用 designing-theme。

--profile 换成你实际运行的那个 profile。桌面应用固定跑 desktop profile，且该 profile 由应用独占管理，dsh --profile desktop 直接启动会被拒绝；安装或升级用 dsh plugin --profile desktop add <包>，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 npm:@chengzhao-dev/dsh-quarto-book@0.6.23，跟 GitHub 标签时写 github:chengzhao-dev/dsh-quarto-book#v0.6.23。

从旧的无作用域包 dsh-quarto-book 升级（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile）：先在同一个 profile 里 dsh plugin --profile <profile> remove dsh-quarto-book，再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 writing-quarto 和 designing-theme。

安装单位是 profile，不是仓库：只影响执行 add 的那个 profile。装好之后还要过工作区检查：按会话 cwd 判断当前目录是不是一本书，通过后技能名才会出现。检查的六类情形见 docs/plugin-boundaries.md。

环境要求

依赖 · 用途

DSH 0.2.x · 宿主；插件按 dsh.bundle.patch 注册技能与两个工具

Node.js 22 及以上 · 运行插件与检查脚本

Python 3 · 内容、链接、命名检查，以及渲染后的 HTML 检查

Quarto CLI · 仅 quarto_render_check 真正渲染时需要

发布包已经带编译好的 lib/，安装后不需要构建。环境分工见 docs/plugin-layout.md。

使用

写章节

在 type: book 的仓库里加载 writing-quarto，按 SKILL.md 判操作并走九步。每一步只打开同号的一个 steps/ 文件；判不准才读 examples/ 里同号的案例；要排图、查渲染或全仓改写才打开 quarto/。

书仓库根目录的 README.md 是说明页，不是章节：只走第 5–8 步，不套第 1–4 步的任务与结构骨架，不写「常见错误」「自测问题」，不调 quarto_render_check。README.en.md 同样处理。

插件没有常驻进程，也不会在会话开始时自动执行技能。技能目录里出现名字只说明当前会话过了检查；只有调用 skill、quarto_render_check 或 quarto_pass_report 才算一次使用。同一会话再次调用会重读技能正文，工具失败后不会自动重试。

改主题

主题资产在 skills/designing-theme/assets/theme/，包内是权威来源，书内 theme/ 是渲染副本。已有副本时 designing-theme 只改副本；只有用户明确要求「把插件主题装进这本书」且目标目录不存在，才从包复制，并把 skills/writing-quarto/scripts/answering-disclosure.lua 放到书内 filters/answering-disclosure.lua。_quarto.yml 只引用书内副本，不指向 npm 包或插件检出目录。

检查与渲染

内容与链接检查在 writing-quarto 技能目录下运行：

python scripts/verifying-content.py --root <book>
python scripts/checking-links.py --root <book>
python scripts/checking-prose.py --root <book>
python scripts/checking-names.py --root <book>

checking-prose.py 只报中文混排里能直接判断的问题；checking-names.py 只在全仓改写时加跑。日常章节检查跑前三条即可。

渲染后的 Callout、HTML 产物与 DOM 结构约定由 quarto_render_check 调包内脚本完成，不用手跑 checking-callouts.py、checking-output.py 或 checking-dom.py；designing-theme 的 scripts/checking-layout.py 在渲染后的 HTML 上检查溢出、对比度和页面结构。apply() 不在加载时跑这些脚本，也不跑 quarto render。

一轮结束时调用一次 quarto_pass_report，把这次执行的结论压成卡片；卡片就是回执，回复里不再复述。

项目技能

项目只放一份自己的约定技能：<book>/.agents/skills/quarto-book-project/，模板见 templates/quarto-book-project/。存在时两个通用技能先读它的 SKILL.md，再按它指向的 writing/ 文件读章节表；不存在就跳过，不猜项目约定。

不要把同名技能嵌进书仓库：DSH 在同一技能层按 rank 取一个，.agents/skills（rank 200）优先于插件（rank 550），书里再放 writing-quarto 或 designing-theme 会让插件正文失效。

文档

文档 · 内容

docs/architecture.md · 两个技能与两个工具的分层、四个域（内容、结构、版式、措辞）与文件职责

docs/plugin-flow.md · 从安装到回执的五层结构、文件分流与渲染顺序

docs/plugin-boundaries.md · 工作区检查的六类情形与判定顺序

docs/plugin-layout.md · 仓库目录、发布包内容与 Python/Quarto 分工

docs/writing-quarto-layout.md · 写作技能的目录分层

docs/triggering.md · 两个技能的触发判据、四个域与正反例

docs/versioning.md · 版本号与发布顺序

开发

源码用 TypeScript，构建产物 lib/ 提交进仓库；发布包直接加载 lib/，安装后不需要构建。开发时把本仓库链接进写书用的 profile，而不是把技能复制进书：

npm ci
npm test
npm run check
npm run pack

npm test 会先编译再跑工具测试；npm run check 做类型检查与技能路径自检；npm run pack 把 tarball 只写进 temp/，那个目录已在 .gitignore 里。

推送前用一条命令复现 CI 的检查序列：

npm run ci

npm run ci 依次执行 npm ci、npm test、npm run check:lib、npm run check 与 npm run pack:check，覆盖 .github/workflows/ci.yml 的全部步骤，并在打包前挡住发布内容的问题。

开发安装：

dsh plugin --profile web add D:\\Github\\dsh-quarto-book

SKILL.md、steps/、examples/、quarto/ 在下一次 skill 工具调用时重读，改完不用发 npm。包内主题改动不会自动进书的 HTML；要看页面效果，把改过的文件同步到书的 theme/，再在书根运行 quarto render。不要把 _quarto.yml 指到插件检出目录，那条路径换机器就不存在。

插件以 bundle 形式发布：package.json 的 dsh.bundle.patch 指向 cordis.patch.yml，补丁只插入 `id

…(truncated)