@chengzhao-dev/dsh-quarto-book 0.6.3 → 0.6.5

package/README.en.md

@@ -5,7 +5,7 @@
 
 **English** | [简体中文](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/README.md)
 
-Write Chinese technical chapters in a Quarto Book repository: `writing-quarto` owns the chapter skeleton and prose, `designing-theme` owns the theme. Both skills appear only inside `type: book` repositories. After a render, `quarto_render_check` decides whether the HTML is publishable and `quarto_pass_report` prints the closing receipt.
+Take a Quarto Book from chapters to publishable output: `writing-quarto` owns the chapter skeleton, whole-book order and Chinese prose; `designing-theme` owns the theme; after a render, `quarto_render_check` decides whether the HTML is publishable and `quarto_pass_report` prints the closing receipt. Both skills appear only inside `type: book` repositories, and the workflow needs Quarto CLI and Python 3.
 
 ## What it provides
 
@@ -16,7 +16,7 @@ Write Chinese technical chapters in a Quarto Book repository: `writing-quarto` o
 | `quarto_render_check` | Check that `output-dir` is safe, render once when asked, and inspect HTML in `_book/` for publishing | Editing `.qmd`, fixing config automatically, or re-running a failed render |
 | `quarto_pass_report` | Compress the run into a fixed-line receipt card: skill, mode, files and steps changed, items held, check verdicts | Saving to disk, quoting chapter prose, or changing the text based on the receipt |
 
-Both skills are discovered from the package's `skills/` directory and loaded on demand. Relative paths inside a skill resolve against that skill's directory: `writing-quarto` uses `steps/`, `examples/`, `quarto/`, `scripts/`; `designing-theme` uses `references/`, `knowledge/`, `assets/`, `scripts/`.
+Both skills are discovered from the package's `skills/` directory and loaded on demand. Relative paths inside a skill resolve against that skill's directory: `writing-quarto` uses `steps/`, `examples/`, `quarto/`, `references/`, `scripts/`; `designing-theme` uses `references/`, `knowledge/`, `assets/`, `scripts/`.
 
 ## Quick start
 
@@ -29,7 +29,7 @@ Both skills are discovered from the package's `skills/` directory and loaded on
 2. Open a session in the book repository. `_quarto.yml` needs a standalone `type: book` line, and the book needs at least one `.qmd` or `.md` chapter source; only then do both skill names appear.
 3. Call a skill: `writing-quarto` for prose, `designing-theme` for the theme.
 
-Replace `--profile` with the profile you actually run. The desktop app always runs the `desktop` profile, and that profile is owned by the app, so `dsh --profile desktop` is rejected; install or upgrade with `dsh plugin --profile desktop add <package>`, and use the app's Settings → Plugins → Add plugin only if the app refuses that write. To pin a version, write `npm:@chengzhao-dev/dsh-quarto-book@0.6.3`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.3`.
+Replace `--profile` with the profile you actually run. The desktop app always runs the `desktop` profile, and that profile is owned by the app, so `dsh --profile desktop` is rejected; install or upgrade with `dsh plugin --profile desktop add <package>`, and use the app's Settings → Plugins → Add plugin only if the app refuses that write. To pin a version, write `npm:@chengzhao-dev/dsh-quarto-book@0.6.5`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.5`.
 
 Upgrading from the old unscoped package `dsh-quarto-book` (removed from npm with 0.3.4, so this only affects profiles that installed it earlier): remove it from the same profile first with `dsh plugin --profile <profile> remove dsh-quarto-book`, then add the scoped package. Keeping both installed registers `writing-quarto` and `designing-theme` twice at the same rank 550.
 

package/README.md

@@ -5,7 +5,7 @@
 
 [English](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/README.en.md) | **简体中文**
 
-在 Quarto Book 仓库里写中文技术章节：`writing-quarto` 管章节骨架与行文，`designing-theme` 管主题样式。两个技能只在 `type: book` 的仓库里出现。渲染后可以用 `quarto_render_check` 判断 HTML 是否可发布，用 `quarto_pass_report` 出一张收尾回执。
+把一份 Quarto Book 从章节写到可发布：`writing-quarto` 负责章节骨架、整书次序与中文行文，`designing-theme` 负责主题；渲染后由 `quarto_render_check` 判断 HTML 是否可发布，`quarto_pass_report` 给出收尾回执。两个技能只在 `type: book` 的仓库里出现，运行需要 Quarto CLI 与 Python 3。
 
 ## 提供什么
 
@@ -16,7 +16,7 @@
 | `quarto_render_check` | 先判断 `output-dir` 是否安全，再按需渲染一次，检查 `_book/` 里的 HTML 是否可发布 | 不改 `.qmd`，不自动修配置，不重复渲染 |
 | `quarto_pass_report` | 收尾时把执行结论压成固定行数的回执卡片：技能、模式、改过的文件与步骤、未改项、检查结论 | 不保存到磁盘，不贴章节原文，不据回执改文章 |
 
-两个技能从包内 `skills/` 目录发现，按需加载；技能里的相对路径以技能目录为基准：`writing-quarto` 用 `steps/`、`examples/`、`quarto/`、`scripts/`，`designing-theme` 用 `references/`、`knowledge/`、`assets/`、`scripts/`。
+两个技能从包内 `skills/` 目录发现，按需加载；技能里的相对路径以技能目录为基准：`writing-quarto` 用 `steps/`、`examples/`、`quarto/`、`references/`、`scripts/`，`designing-theme` 用 `references/`、`knowledge/`、`assets/`、`scripts/`。
 
 ## 快速开始
 
@@ -29,7 +29,7 @@
 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.3`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.3`。
+`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级用 `dsh plugin --profile desktop add <包>`，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 `npm:@chengzhao-dev/dsh-quarto-book@0.6.5`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.5`。
 
 从旧的无作用域包 `dsh-quarto-book` 升级（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile）：先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book`，再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 
@@ -87,10 +87,12 @@ python scripts/checking-names.py --root <book>
 
 | 文档 | 内容 |
 | --- | --- |
+| [docs/architecture.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/architecture.md) | 两个技能与两个工具的分层、四个写作域与文件职责 |
 | [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-flow.md) | 从安装到回执的五层结构、文件分流与渲染顺序 |
 | [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-boundaries.md) | 工作区检查的六类情形与判定顺序 |
 | [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-layout.md) | 仓库目录、发布包内容与 Python/Quarto 分工 |
 | [docs/writing-quarto-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/writing-quarto-layout.md) | 写作技能的目录分层 |
+| [docs/triggering.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/triggering.md) | 两个技能的触发判据、四个写作域与正反例 |
 | [docs/versioning.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/versioning.md) | 版本号与发布顺序 |
 
 ## 开发

package/lib/index.js

@@ -24,15 +24,17 @@ const RANK = 550;
 const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const SKILLS_ROOT = path.join(PACKAGE_ROOT, 'skills');
-/** 读取 SKILL.md 实际用到的几个键，只做最简单的 YAML frontmatter 解析。 */
+/** 读取 SKILL.md 实际用到的几个键，只做最小的 YAML frontmatter 解析。 */
 function parseFrontmatter(source) {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(source);
+    const normalized = source.replace(/^\uFEFF/, '');
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(normalized);
     if (!match)
-        return { data: {}, body: source };
+        return { data: {}, body: normalized };
     const data = {};
     const stack = [{ indent: -1, target: data }];
-    for (const rawLine of match[1].split(/\r?\n/)) {
-        const line = rawLine.replace(/\t/g, '  ');
+    const lines = match[1].split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index].replace(/\t/g, '  ');
         if (!line.trim() || line.trimStart().startsWith('#'))
             continue;
         const indent = line.length - line.trimStart().length;
@@ -43,16 +45,56 @@ function parseFrontmatter(source) {
             stack.pop();
         const parent = stack[stack.length - 1].target;
         const key = pair[1];
-        const value = (pair[2] ?? '').trim();
+        const value = stripInlineComment(pair[2] ?? '').trim();
         if (value === '') {
             const child = {};
             parent[key] = child;
             stack.push({ indent, target: child });
             continue;
         }
+        if (/^[>|][+-]?\d?$/.test(value)) {
+            const block = [];
+            let cursor = index + 1;
+            for (; cursor < lines.length; cursor += 1) {
+                const next = lines[cursor].replace(/\t/g, '  ');
+                if (!next.trim()) {
+                    block.push('');
+                    continue;
+                }
+                const nextIndent = next.length - next.trimStart().length;
+                if (nextIndent <= indent)
+                    break;
+                block.push(next);
+            }
+            const nonBlank = block.filter((item) => item.trim());
+            const cut = nonBlank.length > 0 ? Math.min(...nonBlank.map((item) => item.length - item.trimStart().length)) : 0;
+            const text = block.map((item) => item.slice(cut)).join('\n');
+            parent[key] = value[0] === '|' ? text : text.replace(/([^\n])\n(?=[^\n])/g, '$1 ').replace(/\n{2,}/g, '\n');
+            index = cursor - 1;
+            continue;
+        }
         parent[key] = parseScalar(value);
     }
-    return { data, body: source.slice(match[0].length) };
+    return { data, body: normalized.slice(match[0].length) };
+}
+/** 去掉 plain scalar 末尾的 ` # 注释`；引号内的 # 保留。 */
+function stripInlineComment(value) {
+    let quote;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (quote) {
+            if (char === quote && value[index - 1] !== '\\')
+                quote = undefined;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === '#' && (index === 0 || /\s/.test(value[index - 1])))
+            return value.slice(0, index);
+    }
+    return value;
 }
 function parseScalar(value) {
     if ((value.startsWith('"') && value.endsWith('"')) ||

package/lib/tools/pass-report.js

@@ -74,6 +74,7 @@ function normalizeFiles(value) {
         fail('files 必须是数组');
     if (value.length > MAX_FILES)
         fail(`files 最多 ${MAX_FILES} 个路径`);
+    const seen = new Set();
     return value.map((item) => {
         if (!isRecord(item))
             fail('files 的每一项必须是 { path, edits }');
@@ -85,7 +86,11 @@ function normalizeFiles(value) {
             fail('files 的 path 必须是非空字符串');
         if (!isPlainCount(item.edits))
             fail('files 的 edits 必须是非负整数');
-        return { path: filePath.trim(), edits: item.edits };
+        const normalizedPath = filePath.trim();
+        if (seen.has(normalizedPath))
+            fail(`files 的 path 重复：${normalizedPath}`);
+        seen.add(normalizedPath);
+        return { path: normalizedPath, edits: item.edits };
     });
 }
 function normalizeSteps(value, skill) {
@@ -194,17 +199,12 @@ export function buildPassReport(input) {
             fail('未执行时必须给出 skip_reason');
         if ([...reason.trim()].length > MAX_SKIP_REASON)
             fail(`skip_reason 最多 ${MAX_SKIP_REASON} 个字`);
-        if (input.files !== undefined && Array.isArray(input.files) && input.files.length > 0) {
-            fail('未执行时 files 必须为空');
-        }
-        if (input.steps !== undefined && Array.isArray(input.steps) && input.steps.length > 0) {
-            fail('未执行时 steps 必须为空');
-        }
-        if (input.held !== undefined && Array.isArray(input.held) && input.held.length > 0) {
-            fail('未执行时 held 必须为空');
-        }
-        if (input.checks !== undefined && Array.isArray(input.checks) && input.checks.length > 0) {
-            fail('未执行时 checks 必须为空');
+        for (const key of ['files', 'steps', 'held', 'checks']) {
+            const value = input[key];
+            if (value === undefined)
+                continue;
+            if (!Array.isArray(value) || value.length > 0)
+                fail(`未执行时 ${key} 必须为空数组`);
         }
         return { receipt: `未执行 ${typedSkill}：${reason.trim()}` };
     }