- 新增 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 个引用路径与密钥扫描全过;纯文档改动未跑全量门禁。
219 lines
9.1 KiB
Python
Executable File
219 lines
9.1 KiB
Python
Executable File
#!/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())
|