render-html

/render-html：Markdown → 单文件 HTML，便于阅读

每次审稿人轮次开始前，请遵循 Selectable Reviewers： 通过 reviewer_route.py 和规范的辅助解析器，依次解析调用参数 → .aris/reviewer.json → Claude Code 默认设置（Codex MCP），并保留此轮次的层级、全新上下文、源文件/图像输入和确定性门槛。 下方的 Codex 示例/固定设置仅适用于 backend=codex；其他路由使用各自的首次调用/回复约定。保存路由和实际返回的身份；无法使用的选择标记为 REVIEW_UNAVAILABLE。根据实际的类别/完成情况/范围对验收进行分类。将调用参数中的审稿人/模型/工作量覆盖设置传递给包含审稿人的子流程。生成工作线程保持不变。

Markdown 面向写作者。HTML 面向读者。 ARIS 工作流节点会写入 Markdown（规范、便于审计追踪且可由机器解析）。/render-html 会将选定的产物转换为精致的单文件 HTML 视图，供实际需要阅读的人使用。Markdown 仍是事实来源。

何时使用此技能

以下 ARIS 产物适合使用 /render-html，因为它们有实际的人类读者：

产物	HTML 的优势	模板
idea-stage/IDEA_REPORT.md	排序后的创意、试点信号和评分更像决策仪表板，而非简单列表	academic
review-stage/AUTO_REVIEW.md（+ REVIEW_STATE.json）	展示逐轮评分变化和弱点状态；传入 --state 可嵌入 JSON	academic
paper/KILL_ARGUMENT.md（+ KILL_ARGUMENT.json）	分点攻防，配有 <details> 问答卡片和红/黄/绿提示	academic
research-wiki/SUMMARY.md（或 research-wiki/index.md）	跨实体总览：一目了然地查看论文/创意/实验/主张	dashboard
PAPER_PLAN.md（可选）	主张-证据矩阵以精致表格呈现，比原始 MD 更易阅读	academic
RESUBMIT_REPORT.{md,json}（可选）	7 种状态的失败模式清单	academic 或 dashboard

请勿用于：

• LaTeX 论文输出——面向最终读者的产物是 PDF，而非 HTML。
• SKILL.md 文件——这些文件是面向大模型的内部协议。
• .aris/traces/* 审稿追踪记录——用于取证调试，而非供人阅读。
• 项目中的每个 Markdown 文件——仅转换能从固定目录、提示框、数学公式或评分变化中受益的产物。

核心不变量

• MD / JSON 是规范来源，HTML 是生成的视图。 编辑源文件，然后重新渲染。不要手动编辑 HTML。
• 在产物边界进行跨模型审查（ARIS 不变量）。学术模板 HTML——用于人们实际阅读的产物（IDEA_REPORT、AUTO_REVIEW、KILL_ARGUMENT、PAPER_PLAN）——由选定的审查者在全新上下文中审查；在将其认定为完成的视图之前，根据实际身份对其家族进行分类。仪表板模板 HTML（驾驶舱 / 调试视图）默认跳过审查，但可通过 --review 强制审查。详见下文 § HTML Review Gate。
• 漂移检测。 每份渲染后的 HTML 都会在 <meta> 标签和可见的页面页眉中嵌入源文件路径、SHA256 和生成时间戳。如果 HTML 与源文件不一致，元数据会告诉你生成该版本 HTML 时使用的是哪个版本的源文件。
• 单文件输出。 无需构建系统、独立 CSS 或 node_modules。只有一个 .html 文件。
• 默认使用适合 CDN 的模式，--offline 用于回退。 MathJax 3 和 highlight.js 默认从 cdn.jsdelivr.net 加载。传入 --offline 可跳过两者——数学公式会显示为原始的 $x$，代码块不会进行语法高亮，但所有内容仍清晰可读。
• 纯标准库辅助工具。 render_html.py 只使用 re、html、hashlib、json、datetime、pathlib、argparse、sys。无需安装 pip 包。
• 纵深防御式 XSS 清理。 此辅助工具会移除 <script>/<style>/<iframe>/<object>/<embed>/<form>/<input>/<button>/<link>/<meta>/<base> 标签、所有 on* 事件处理程序属性（onclick、onload 等），并将 javascript:/vbscript:/data: href/src/action 方案重写为 #blocked-unsafe-url:。ARIS 工作流产物本就不应包含这些内容；清理器是在大模型产生幻觉时提供的安全防线。Markdown 文本内容会单独进行 HTML 转义，不会传入清理器。

工具位置

Arch C 自包含：规范实现位于 skills/render-html/scripts/render_html.py（此 SKILL 自带的 scripts/ 子目录），模板则位于 skills/render-html/scripts/templates/{academic,dashboard}.html。这是一个新辅助工具，不存在旧版 tools/ 兼容层。

使用混合链解析 $RENDER_HTML（第 0 层优先使用所属 SKILL 的自包含位置；第 1–3 层是 shared-references/integration-contract.md §2 中记录的共享运行时链，策略 A — skill-local gate）：

# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).
RENDER_HTML=""
if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/render_html.py" ]; then
  RENDER_HTML="$CLAUDE_SKILL_DIR/scripts/render_html.py"
fi
# Layers 1-3: shared-runtime chain (non-CC hosts + manual installs).
if [ -z "$RENDER_HTML" ]; then
  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
  if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
      ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
  fi
  RENDER_HTML=".aris/skills/render-html/scripts/render_html.py"
  [ -f "$RENDER_HTML" ] || RENDER_HTML="skills/render-html/scripts/render_html.py"
  [ -f "$RENDER_HTML" ] || { [ -n "${ARIS_REPO:-}" ] && RENDER_HTML="$ARIS_REPO/skills/render-html/scripts/render_html.py"; }
  [ -f "$RENDER_HTML" ] || RENDER_HTML=""
fi
[ -z "$RENDER_HTML" ] && {
  echo "ERROR: render_html.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-3: .aris/skills/render-html/scripts/, skills/render-html/scripts/, \$ARIS_REPO/skills/render-html/scripts/)." >&2
  echo "       /render-html cannot produce HTML output. Fix: rerun bash tools/install_aris.sh, or copy from \$ARIS_REPO/skills/render-html/scripts/." >&2
  exit 1
}

调用

# Default: academic template, output to <input>.html alongside source
python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md

# Dashboard template for cockpit-style views
python3 "$RENDER_HTML" research-wiki/SUMMARY.md --template dashboard

# Custom output path + title + eyebrow
python3 "$RENDER_HTML" review-stage/AUTO_REVIEW.md \
  --out review-stage/AUTO_REVIEW.html \
  --title "Auto Review — overnight run" \
  --eyebrow "Workflow 2"

# Embed sidecar state JSON (rendered as a folded <details> JSON block at end)
python3 "$RENDER_HTML" review-stage/AUTO_REVIEW.md \
  --state review-stage/REVIEW_STATE.json

# Embed sidecar JSON (e.g., for KILL_ARGUMENT.md + KILL_ARGUMENT.json)
python3 "$RENDER_HTML" paper/KILL_ARGUMENT.md \
  --json paper/KILL_ARGUMENT.json \
  --title "Kill Argument — adversarial review"

# Offline (no CDN; math + code render as plain text)
python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md --offline

# JSON-only input (wrapped in a <pre><code class="language-json"> block)
python3 "$RENDER_HTML" review-stage/REVIEW_STATE.json --template dashboard

# Language attr (default zh-CN; set for English-primary artifacts)
python3 "$RENDER_HTML" docs/SKILLS_CATALOG.md --lang en

# Skip review (academic template otherwise reviews by default)
python3 "$RENDER_HTML" idea-stage/IDEA_REPORT.md
# … then the skill skips the mcp__codex__codex review step if --no-review
# was on the command line. Pass --review to a dashboard render to force it.

--review / --no-review 标志由 SKILL 编排器（Claude Code）解析，而不是由 render_html.py 解析。辅助工具本身保持纯标准库，不会调用 MCP。确切的解析逻辑和提示词见下文 § HTML Review Gate。

工作流

步骤 1：识别产物

根据 $ARGUMENTS 确定要渲染的内容。常见模式：

• “渲染 IDEA_REPORT” → idea-stage/IDEA_REPORT.md，学术模板
• “让 AUTO_REVIEW 更易读” → review-stage/AUTO_REVIEW.md + --state review-stage/REVIEW_STATE.json
• “将否决论证显示为 HTML” → paper/KILL_ARGUMENT.md + --json paper/KILL_ARGUMENT.json
• “research-wiki 仪表板” → 查找 research-wiki/SUMMARY.md，或根据原始实体计数生成（第 2 阶段工作；第 1 阶段只需在存在 SUMMARY.md 时渲染它，否则退回到列出 wiki 的顶层结构）

步骤 2：选择模板

• academic（默认）：线性长文布局。粘性目录侧边栏 + 衬线字体正文 + 提示框 + 表格 + 数学公式 + 问答 <details>。用于 IDEA_REPORT、AUTO_REVIEW、KILL_ARGUMENT、PAPER_PLAN。
• dashboard：网格布局、较小字号、更密集的指标卡片、无目录侧边栏。用于 research-wiki 驾驶舱、RESUBMIT_REPORT、多项目概览。

步骤 3：运行辅助脚本

使用上面的解析器获取 $RENDER_HTML，然后调用它。脚本默认会在源文件旁写入 HTML（或写入 --out 指定的位置），并打印一行确认信息，其中包含源文件 SHA256 前缀。

步骤 4：HTML 审查关卡（跨模型）

决定是否运行审查。 根据 ARIS 不变量“执行者不得评判自己的输出”，学术模板 HTML 由在全新上下文中选定的审查者进行审查；在将其作为交付视图前，需根据实际身份判定其类别。解析方式：

should_review = explicit --review present
             or (template == "academic" and --no-review NOT present)

因此：

• --template academic（默认值）→ 默认审查。使用 --no-review 跳过。
• --template dashboard → 默认不审查。使用 --review 强制审查。
• 第 2 阶段工作流自动生成（于 2026-05 启用）会根据下文记录的 RENDER_HTML hooks 按技能进行选择 — 中间视图默认使用 --no-review，最终交付物／审计类交付物默认通过完整关卡。

如果 should_review 为 true，启动一个全新的 mcp__codex__codex 线程（绝不可使用 codex-reply；根据 ../shared-references/reviewer-routing.md 固定使用 model: gpt-6-astra + config: {"model_reasoning_effort": "xhigh"}），并使用下方提示词。审查者会直接读取源 MD 和生成的 HTML；它看不到此技能的中间状态。

审查范围（有意限定）。 HTML 审查者仅审查渲染保真度／安全性／结构 — 不审查论断的真实性。论断审计应在上游进行（/paper-claim-audit、/research-review、/result-to-claim）。具体而言，审查者会检查：

1. 信息保真度 — HTML 中包含每个章节、论断、表格、代码块、列表、数学片段和 sidecar 负载（无静默丢失）
2. 结构完整性 — 标题层级／嵌套列表／表格单元格／代码围栏／<details> 块／数学分隔符在解析后均得以保留
3. 提示框路由 — > 🚨 … 转换为 .callout-bad，> 💡 … 转换为 .callout-info，等等
4. 安全性／转义 — 不存在原始 <script>／onclick=／javascript:／未替换的占位符／模板泄漏
5. 预期差异的允许范围 — 移除 frontmatter、生成的页眉／页脚／元数据、插入目录、清理不安全的 HTML 均属预期，不应标记

Codex 提示词（必须采用此格式）。 使用全新线程发送此提示词（mcp__codex__codex，而非 codex-reply）：

You are an independent ARIS HTML render auditor. This is a fresh review thread.

Read these files directly:
- Source artifact: <ABS path to source.md or source.json>
- Generated HTML:  <ABS path to out.html>
- Optional sidecars: <state.json>, <kill_argument.json> (if any)

Task: Audit whether the generated HTML is a faithful, safe, structurally
usable view of the source artifact. Do NOT judge whether the research
claims are true. Judge only rendering fidelity.

Checks:
1. Information fidelity — sections / claims / tables / code blocks /
   lists / math / sidecars not silently dropped or materially altered.
2. Structural integrity — heading hierarchy, tables, nested lists,
   code fences, details/summary, math delimiters preserved.
3. Callout routing — warning/critical/good/info blockquotes map to
   appropriate CSS classes when present.
4. Safety/escaping — no unexpected raw script/style/iframe/form/
   event-handler/javascript/data URL survives from source.
5. Placeholder/template leakage — no unreplaced {{PLACEHOLDER}} or
   parser private placeholder character appears.
6. Expected differences — frontmatter strip, generated header/footer/
   meta, TOC insertion, sanitized unsafe HTML are EXPECTED and not a
   defect.

Return STRICT JSON first, then a short prose note:

{
  "verdict": "PASS|WARN|FAIL|ERROR",
  "checks": {
    "source_hash_match": "pass|warn|fail|unknown",
    "information_fidelity": "pass|warn|fail",
    "structure": "pass|warn|fail",
    "math_code_tables": "pass|warn|fail",
    "callouts": "pass|warn|fail|not_applicable",
    "safety_escaping": "pass|warn|fail",
    "placeholder_leak": "pass|warn|fail"
  },
  "blocking_issues": [
    {"severity": "fail",
     "source_location": "L<n>...",
     "html_location": "<selector or near-text>",
     "issue": "...",
     "suggested_fix": "..."}
  ],
  "warnings": [
    {"severity": "warn", "issue": "...", "suggested_fix": "..."}
  ],
  "summary": "one paragraph"
}

Verdict rules:
- PASS: no material fidelity/safety issue.
- WARN: readable output with minor unsupported-Markdown or cosmetic
  degradation only.
- FAIL: missing/altered meaningful content, broken tables/math/code/
  callouts that change interpretation, unsafe executable HTML, source
  hash mismatch, or placeholder leakage.
- ERROR: files could not be read or audit could not complete.

保存输出：

1. 将 JSON 判定结果写入 <out_path>.review.json（与 HTML 同目录）。
2. 根据 shared-references/review-tracing.md，将原始 codex 跟踪记录保存到 .aris/traces/render-html/<YYYY-MM-DD>_run<NN>/review.{txt,json}。
3. 向用户打印一行摘要：verdict, N blocking, N warnings, trace: <path>。

如果 verdict == FAIL：该 HTML 不是已通过审查的交付视图。告知用户阻塞问题，并引导其查看源文件（修复 MD 或模板，而非 HTML），然后重新渲染。不要静默覆盖或标记为已完成。

如果 verdict == WARN：交付 HTML，但列出警告。由用户决定是修复还是接受。

如果选定的审查者路由不可用：向 sidecar 输出 verdict: REVIEW_UNAVAILABLE，不要伪造 PASS，并告知用户 HTML 已生成，但未经独立审查。用户可以在源 MD 上手动调用 /research-review，或等选定的审查者可用后重新运行。

步骤 5：（可选）在浏览器中验证

macOS 上使用 open <out.html>，Linux 上使用 xdg-open，Windows 上使用 start。数学公式和代码高亮需要联网（CDN）；离线模式会优雅降级为可读文本。

此辅助工具支持的内容

Markdown 子集（根据 ARIS 工作流实际生成的内容选定）：

• 标题 #/##/###/####，并自动生成用于目录的 ID
• 段落、粗体 **x**、斜体 *x* / _x_、行内代码 `x`、删除线 ~~x~~、链接 [t](url)、图片 ![a](url)
• 使用 2 个空格缩进的无序列表和有序列表
• 可选语言的代码块（```python）——会生成 <pre><code class="language-python">，供 highlight.js 使用
• ASCII 艺术代码块（启发式判断：包含许多制图字符）→ <pre class="diagram">，背景为独特的奶油黄色
• 使用 :--- / :---: / ---: 对齐的表格
• 引用块 > ...——根据表情符号前缀检测结果，分流到不同的提示框样式：
  • ⚠️ → .callout-warn（警告）
  • 💡 / 📝 → .callout-info（提示 / 注释）
  • ✅ / 🔒 → .callout-good（正常 / 保证）
  • ❌ / 🚨 → .callout-bad（受阻 / 严重）
• 支持原样传递 HTML，包括 <details>、<summary>、<div>、<figure>、<table>、<section> 等（块级）——用于 KILL_ARGUMENT.md 中现有的 Round-1/2/3 修复详情
• LaTeX 数学公式：行内 $x$ 和展示公式 $$x$$ 会原样传递给 MathJax

此辅助工具不支持的内容（有意简化）：

• 脚注（[^1]）
• 定义列表
• 引用式链接 [label][ref]
• Setext 风格标题（=== / --- 下划线形式——ARIS 不会生成这些内容）

文件最顶部的前置元数据（--- ... ---）会在渲染前被剥离（SKILL.md 前置元数据风格）；后续正文将被转换。

两阶段集成计划（阶段 1 即本技能；阶段 2 为工作流钩子，于 2026-05 启用）

**阶段 1（最初发布）：**仅限主动调用。工作流完成后，用户需明确调用 /render-html <artifact.md>。

**阶段 2（于 2026-05 启用）：**现在有八项关键技能会在工作流结束时自动生成 HTML；每项技能都由 RENDER_HTML = true 常量控制，用户可在每项技能中将其关闭（或在调用时传入 — render html: false）。

按成本分级的审核门槛（按产物类型）：

技能	产物	审核等级	原因
/idea-discovery	idea-stage/IDEA_REPORT.md	--no-review	中间产物；来源已通过新颖性和跨模型审核
/auto-review-loop	review-stage/AUTO_REVIEW.md	--no-review	每轮日志；循环本身就是跨模型审核
/research-pipeline	NARRATIVE_REPORT.md	--no-review	移交给 /paper-writing 的内部阶段 5 产物；不面向审稿人——上游阶段 4 的 auto-review-loop 已对论断进行把关
/kill-argument	<paper-dir>/KILL_ARGUMENT.md	完整审核	审计级产物；符合该技能自身的跨模型不变式
/paper-claim-audit	paper/PAPER_CLAIM_AUDIT.md	完整审核	审计级产物
/citation-audit	paper/CITATION_AUDIT.md	完整审核	审计级产物
/proof-checker	PROOF_AUDIT.md	完整审核	审计级产物
/rebuttal	REBUTTAL_DRAFT_rich.md	完整审核	提交前的交付物
/paper-writing	（不自动生成 HTML）	不适用	面向最终读者的产物是 PDF
/research-wiki	research-wiki/index.html 仪表板	未来计划	阶段 2.1——仪表板模板工作，不在本轮范围内

中间报告使用 --no-review 是有意为之：源 MD 已通过生成该报告的技能自身的跨模型审核门槛，而 HTML 渲染只会转换结构——不会添加新的论断。在每个检查点都进行完整审核，会使每条流水线的 Codex 调用次数增加 4-6 倍。

要为特定技能禁用 HTML 输出：在该技能的常量块中设置 RENDER_HTML = false，或传入 — render html: false。要全局禁用：使用环境变量 ARIS_RENDER_HTML=0 跳过（计划中，尚未实现；目前请按技能设置标志）。

自定义模板

两个模板位于 skills/render-html/scripts/templates/{academic,dashboard}.html。每个模板都是一个独立的 HTML 文件，包含使用 {{PLACEHOLDER}} 替换内容的内联 CSS。自定义方法：

1. 将其中一个模板复制并改为新名称，例如 my_brand.html。
2. 编辑 :root { ... } 中的 CSS 变量，以更改颜色、字体栈或布局尺寸。
3. 将模板名称添加到 render_html.py argparse 中的 --template 选项。
4. 重新运行 /render-html <input> --template my_brand。

默认模板源自用户自己的学术报纸风格教程（Source Serif Pro + Songti SC、3 色调色板、粘性目录、低闪烁）。除非有明确理由要打破视觉语言，否则 ARIS 产物应保持这种风格。

外部替代方案（适用于更丰富的呈现形式）

对于幻灯片 / 海报 / 小红书卡片 / 推文卡片 / 数据报告风格的输出，请向用户推荐 html-anything（Apache-2.0，撰写本文时为 3000⭐）。它提供覆盖 9 种呈现形式的 75 个 SKILL.md 模板，并能检测 8 种编码 Agent CLI（包括 Claude Code、Codex、Copilot）。ARIS 不依赖它——/render-html 用于 ARIS 原生产物；对于更丰富的发布形式，推荐使用 html-anything。

关键规则

• 不要自动渲染每个 Markdown 文件。 仅渲染上述白名单中的产物。文件泛滥是最主要的反模式。
• 不要手动编辑生成的 HTML。 编辑源文件，然后重新渲染。HTML 元数据中的 SHA256 可以告知你源文件自渲染后是否有过更改。
• academic-template HTML 默认是经过审阅的产物，而非原始输出。跨模型 Codex 审阅（新对话）是学术交付物的准入关卡——与 /proof-checker、/paper-claim-audit、/citation-audit、/kill-argument 分别把关其对应产物的方式相同。对于 中间阶段的自动生成内容（例如 idea-stage/IDEA_REPORT.html、每轮生成的 review-stage/AUTO_REVIEW.html），如果源 MD 已通过上游跨模型关卡，则适合使用 --no-review——此时 HTML 渲染只是结构转换，而非新的论断审计。对于已交付 / 面向审阅者 / 审计级输出，请保留完整关卡。
• 审阅者审计的是渲染，而非研究。 论断真实性由上游的 /paper-claim-audit、/result-to-claim、/research-review 负责。HTML 审阅者要问的是：“渲染器是否忠实且安全地转换了此源文件？”——仅此而已。
• CDN 依赖默认启用，可选择关闭。 大多数用户都有互联网；--offline 用于隔离网络的运行环境 / 归档。
• 默认风格是学术报纸风格，而非浮夸的营销风格。 与现有 ARIS 语调保持一致。如果需要幻灯片 / 海报 / 社交卡片，请向用户推荐 html-anything。
• 仅使用纯标准库。 若要在 render_html.py 中添加 pip install 依赖，必须经过明确决策——该辅助脚本目前没有任何依赖。MCP 调用由技能编排器负责，绝不能放在辅助脚本中。