Files
ssw-mpc/tools/render-share-html.py
T
admin c51190b20c docs: 拆解决策文档形成系统架构文档,附可分享 HTML
- 新增 docs/ARCHITECTURE_SYSTEM.md(活真相源):组件清单、双层控制面、
  会话主键、端到端数据流、部署拓扑、平台矩阵、判定治理、诚实边界。
  用 [实证]/[桩验]/[设计]/[禁用] 区分实证与蓝图 —— `mpc site` 等
  决策角色不再被写成已部署服务,避免照着文档敲不存在的命令。
- 新增 tools/render-share-html.py 与 docs/ARCHITECTURE_SYSTEM.html:
  自包含单文件分享页,md 是唯一真相源、HTML 是派生产物勿手改;
  --check 校验两者同步,生成幂等无 diff 噪音。
- INTEGRATION_ANALYSIS.md 文首加「架构结论已抽出」指针,正文决策取证链
  保持不变;INDEX.md(§0/§2/§3/§6)、CLAUDE.md、README.md 登记新文档
  与第 9 条更新纪律。与原 ARCHITECTURE.md(计算分层)明确分工。
- 校验:HTML 与 md 同步、ci.sh 语法、判据自测 22/22、diff 空白、
  23 个引用路径与密钥扫描全过;纯文档改动未跑全量门禁。
2026-11-08 19:29:18 +08:00

219 lines
9.1 KiB
Python
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env python3
"""把 docs/ARCHITECTURE_SYSTEM.md 渲染成自包含、可分享的单文件 HTML。
设计约束(与项目「判定口径只有一份实现」一致):
* md 是唯一真相源,HTML 是**派生产物,勿手改**;
* 输出不含外部资源(CDN / 字体 / JS),离线双击即可看,也可直接分享;
* 生成结果幂等:不写时间戳,重复生成不产生 diff 噪音;
* `--check` 用于校验 HTML 是否与 md 同步(改了 md 忘记重新生成会被抓到)。
用法:
python3 tools/render-share-html.py # 生成
python3 tools/render-share-html.py --check # 只校验,不写文件
python3 tools/render-share-html.py --input X --output Y
依赖:markdown-it-py(本机已装)。缺失时明确报错,绝不静默跳过。
"""
from __future__ import annotations
import argparse
import html
import re
import sys
from pathlib import Path
REPO = Path(__file__).resolve().parent.parent
DEFAULT_INPUT = REPO / "docs" / "ARCHITECTURE_SYSTEM.md"
DEFAULT_OUTPUT = REPO / "docs" / "ARCHITECTURE_SYSTEM.html"
try:
from markdown_it import MarkdownIt
except ImportError:
sys.exit(
"缺少 markdown-it-py:请先 `python3 -m pip install markdown-it-py`。\n"
"本脚本不静默降级 —— 半渲染的 HTML 比没有 HTML 更危险。"
)
CSS = r"""
:root{
--bg:#f7f8fa; --surface:#ffffff; --ink:#1b1f24; --muted:#5b6572;
--line:#e3e7ec; --accent:#2563a8; --accent-soft:#eaf2fb;
--code-bg:#f2f4f7; --quote-bg:#f4f8fd; --warn-bg:#fff7e8; --warn-line:#e0a336;
--mono:ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace;
--sans:-apple-system,BlinkMacSystemFont,"PingFang SC","Hiragino Sans GB",
"Microsoft YaHei","Segoe UI",Roboto,sans-serif;
}
@media (prefers-color-scheme:dark){
:root{
--bg:#14171c; --surface:#1b2027; --ink:#e6e9ee; --muted:#9aa5b3;
--line:#2c333d; --accent:#79b8ff; --accent-soft:#1c2c3e;
--code-bg:#20262f; --quote-bg:#1a2532; --warn-bg:#33291a; --warn-line:#b8842f;
}
}
*{box-sizing:border-box}
html{scroll-behavior:smooth}
body{margin:0;background:var(--bg);color:var(--ink);font-family:var(--sans);
font-size:15.5px;line-height:1.75;-webkit-font-smoothing:antialiased}
.layout{display:flex;gap:0;max-width:1320px;margin:0 auto;align-items:flex-start}
nav.toc{position:sticky;top:0;flex:0 0 268px;width:268px;height:100vh;overflow-y:auto;
padding:28px 18px 40px 24px;border-right:1px solid var(--line);background:var(--surface)}
nav.toc .brand{font-weight:700;font-size:15px;letter-spacing:.02em;margin-bottom:4px}
nav.toc .sub{font-size:12px;color:var(--muted);margin-bottom:20px}
nav.toc a{display:block;color:var(--muted);text-decoration:none;font-size:13px;
padding:5px 8px;border-radius:5px;border-left:2px solid transparent}
nav.toc a:hover{color:var(--accent);background:var(--accent-soft)}
nav.toc a.lv3{padding-left:22px;font-size:12.5px;opacity:.9}
main{flex:1 1 auto;min-width:0;padding:30px 40px 90px;background:var(--bg)}
.banner{background:var(--warn-bg);border-left:3px solid var(--warn-line);
padding:10px 14px;border-radius:0 6px 6px 0;font-size:13px;color:var(--ink);
margin-bottom:26px}
.banner code{font-family:var(--mono);font-size:12px}
article{background:var(--surface);border:1px solid var(--line);border-radius:10px;
padding:34px 40px 48px;box-shadow:0 1px 3px rgba(0,0,0,.04)}
article h1{font-size:27px;line-height:1.35;margin:0 0 22px;padding-bottom:14px;
border-bottom:2px solid var(--accent)}
article h2{font-size:20px;margin:38px 0 14px;padding-top:10px;
border-top:1px solid var(--line)}
article h3{font-size:16.5px;margin:26px 0 10px;color:var(--accent)}
article h1:first-of-type{border-top:0}
article p{margin:10px 0}
article a{color:var(--accent);text-decoration:none;border-bottom:1px solid var(--accent-soft)}
article a:hover{border-bottom-color:var(--accent)}
article strong{font-weight:650}
article hr{border:0;border-top:1px solid var(--line);margin:30px 0}
article blockquote{margin:16px 0;padding:10px 18px;background:var(--quote-bg);
border-left:3px solid var(--accent);border-radius:0 6px 6px 0;
color:var(--ink)}
article blockquote p{margin:6px 0}
article ul,article ol{padding-left:24px;margin:10px 0}
article li{margin:4px 0}
article code{font-family:var(--mono);font-size:.88em;background:var(--code-bg);
padding:1px 5px;border-radius:4px;word-break:break-word}
article pre{background:var(--code-bg);border:1px solid var(--line);border-radius:7px;
padding:16px 18px;overflow-x:auto;line-height:1.55;margin:16px 0}
article pre code{background:none;padding:0;font-size:12.6px;white-space:pre}
article table{display:block;width:100%;overflow-x:auto;border-collapse:collapse;
margin:16px 0;font-size:13.8px}
article th,article td{border:1px solid var(--line);padding:8px 11px;text-align:left;
vertical-align:top;min-width:80px}
article th{background:var(--accent-soft);font-weight:650;white-space:nowrap}
article tr:nth-child(even) td{background:rgba(127,140,160,.045)}
article blockquote table{font-size:13px}
footer{max-width:760px;margin:26px auto 0;color:var(--muted);font-size:12.5px;text-align:center}
@media (max-width:900px){
.layout{display:block}
nav.toc{position:static;width:auto;height:auto;border-right:0;
border-bottom:1px solid var(--line);padding:18px 20px}
nav.toc a{display:inline-block;margin:2px 4px 2px 0}
nav.toc a.lv3{display:none}
main{padding:20px 16px 60px}
article{padding:22px 18px 32px}
}
@media print{
body{background:#fff;color:#000;font-size:11pt}
nav.toc,.banner{display:none}
main{padding:0}
article{border:0;box-shadow:none;padding:0}
article h2{page-break-after:avoid}
article pre,article table,article blockquote{page-break-inside:avoid}
a{color:#000;text-decoration:underline}
}
"""
HTML_TEMPLATE = """<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{title} · ssw-mpc</title>
<style>{css}</style>
</head>
<body>
<div class="layout">
<nav class="toc" aria-label="目录">
<div class="brand">ssw-mpc · 系统架构</div>
<div class="sub">当前形态 · 2026-11-08</div>
{toc}
</nav>
<main>
<div class="banner">
<strong>派生产物,勿手改。</strong>
真相源是 <code>docs/ARCHITECTURE_SYSTEM.md</code>;
由 <code>tools/render-share-html.py</code> 生成,改架构请改 md 后重新生成。
文内链接指向仓库内其他 <code>.md</code>:单独分享本页时这些链接不可用,
但正文、表格与拓扑图完全自包含,可离线阅读。
</div>
<article>
{body}
</article>
<footer>ssw-mpc · 文档总入口 <code>docs/INDEX.md</code> · 本页自包含,可离线查看与分享</footer>
</main>
</div>
</body>
</html>
"""
def render(md_text: str) -> tuple[str, str]:
"""返回 (标题, 完整 HTML)。"""
md = MarkdownIt("commonmark").enable(["table", "strikethrough"])
rendered = md.render(md_text)
title_m = re.search(r"<h1>(.*?)</h1>", rendered, re.S)
title = html.unescape(re.sub(r"<[^>]+>", "", title_m.group(1))).strip() if title_m else "系统架构"
headings: list[tuple[str, str, str]] = []
counter = [0]
def add_ids(m: re.Match[str]) -> str:
counter[0] += 1
level, inner = m.group(1), m.group(2)
sec_id = f"sec-{counter[0]}"
text = html.unescape(re.sub(r"<[^>]+>", "", inner)).strip()
if level in ("2", "3"):
headings.append((sec_id, level, text))
return f'<h{level} id="{sec_id}">{inner}</h{level}>'
rendered = re.sub(r"<h([123])>(.*?)</h\1>", add_ids, rendered, flags=re.S)
toc = "\n ".join(
f'<a class="lv{level}" href="#{sec_id}">{html.escape(text)}</a>'
for sec_id, level, text in headings
if level in ("2", "3")
)
return title, HTML_TEMPLATE.format(title=html.escape(title), css=CSS, toc=toc, body=rendered)
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__)
ap.add_argument("--input", type=Path, default=DEFAULT_INPUT)
ap.add_argument("--output", type=Path, default=DEFAULT_OUTPUT)
ap.add_argument("--check", action="store_true", help="只校验产物是否与 md 同步,不写文件")
args = ap.parse_args()
if not args.input.is_file():
sys.exit(f"输入不存在:{args.input}")
md_text = args.input.read_text(encoding="utf-8")
_, output = render(md_text)
if args.check:
if not args.output.is_file():
print(f"FAIL: 产物不存在 {args.output}")
return 1
if args.output.read_text(encoding="utf-8") != output:
print("FAIL: HTML 与 md 不同步,请运行 python3 tools/render-share-html.py")
return 1
print(f"OK: HTML 与 md 同步({args.output.relative_to(REPO)})")
return 0
args.output.parent.mkdir(parents=True, exist_ok=True)
args.output.write_text(output, encoding="utf-8")
print(f"OK: 已生成 {args.output.relative_to(REPO)}({len(output)} 字节,自包含)")
return 0
if __name__ == "__main__":
sys.exit(main())