Harness 资产效果展示与标准验收

可复用性之外的再现性：test 沙盒、自动化断言与 templates 分工

摘要

templates/ 适合展示「业务项目如何消费 harness 资产」，但不能替代可重复跑通的验收规程。本文定义 harness 在「可复用配置」之上应具备的效果再现能力，并以 scripts/quarto-docx/test/ 为首个 scripts/ 类资产示范。

---

1. 问题：复用 ≠ 可验证

缺口	后果
只有文档与拷贝清单	升级 Quarto / 改 Lua 后不知是否仍满足出版社验收
templates/ 仅有规划项	外部读者看不到「渲出来长什么样」
仅 js/mathjax-xaringan 有 test/	scripts/ 资产缺少同等地位的沙盒

优良资产应同时提供：canonical 源、安装路径、标准样例、自动化或半自动验收。

---

2. 推荐功能特征

flowchart LR
  canon["canonical 源<br/>js/ 或 scripts/"] --> test["test/ 沙盒<br/>镜像 + 规程"]
  test --> auto["L0/L1 自动化<br/>+ 可选目视"]
  auto --> promote["晋升 canonical"]
  test --> tmpl["templates/<br/>消费示例（可选）"]
  docs["docs/*.qmd"] --> test

组件	职责	提交 Git
*/test/	镜像、用例 qmd/Rmd、运行脚本、verify_*	是（无 output/）
*-test-guide.md	用例矩阵、环境、晋升规则	是
verify_*	对产物做机器可读断言（docx XML、HTML 片段等）	是
templates/<demo>/	模拟业务仓目录布局；链到 test 效果	是
output/、TEST-LOG.md	本地渲染与记录	否

与 配置资产验证工作流 的关系：同一五阶段（Isolate → Specify → Verify → Promote → Publish），将目录约定从 js/<asset>/test/ 扩展到 scripts/<asset>/test/。

---

3. 首个示范：scripts/quarto-docx

路径	内容
test/README.md	快速开始
quarto-docx-test-guide.md	用例矩阵与 L0/L1
mod-acceptance.qmd	网站剖面六项验收样例（静态，无需 R）
test/book/	book 剖面：图N-M 与一页横向表
verify_docx.py	网站 docx XML 断言
verify_book.py	book docx XML 断言
run-check-all.ps1	Windows 一键 sweep（Linux/Cloud 用 .sh）

cd scripts\quarto-docx\test
.\scripts\run-check-all.ps1

长文验收语义见 Quarto 中文书稿 docx 滤镜。

---

4. 后续资产建议

资产	test 方向
js/mathjax-xaringan	已有；保持 L0/L1 分模块
scripts/quarto-sync	镜像后 quarto render + 比对输出目录
scripts/docker-selenium	compose up + healthcheck（Linux/CI）
ide/*	以文档 + distribution log 为主；可选 schema 校验 settings.json

---

5. 相关文档

• 配置资产本地验证与发布工作流
• Quarto 中文书稿 docx 目录索引
• 项目模板