Archify 架构图谱工程化交付标准与 SOP 指南

责任人：Obsidian Knowledge Vault PM（原 Architecture Tooling PM）
归属组织：HS Design 架构委员会
版本：v1.0 (2026-08-26)
适用范围：HS Design 全域多 Agent 拓扑、微服务架构、数据流管线与知识中枢可视化

1. 专案背景与技术选型

CEO Jake 批准引入 Archify (tt-a1i/archify) 作为 HS Design 体系的架构可视化标准工具链。 Archify 基于纯原生 Web 技术栈与严格的几何排版引擎，能够将 JSON IR（中间表示）编译为零外部依赖、自包含单文件（Single-file Self-contained）的交互式矢量 HTML / SVG，完美契合我们对高保真架构表达、动态流光路径（Motion Trace）、多视角导览（Guided Views）与无缝内嵌 Quartz 知识库的严苛要求。

2. 环境装配与 CLI 规范

2.1 依赖环境（Debian 13 WSL 2）

Node.js: v22.23.2+
Archify CLI: /usr/local/bin/archify（软链至 /root/tools/archify）
Google Chrome / Chromium: 用于无头渲染与视觉质检

2.2 核心命令集

# 1. 验证 JSON IR 语法与走线合规性（Showcase 等级）
archify validate architecture <input.json> --json
 
# 2. 编译渲染高质量自包含 HTML 大图
archify render architecture <input.json> <output.html> --quality showcase
 
# 3. 生产级封装着色与交付
archify deliver architecture <input.json> <output.html> --quality showcase --json
 
# 4. 内置品牌矢量图标库查询
archify brands [category/name]

3. JSON IR 语法与排版黄金法则

3.1 核心字段结构

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "系统架构名称",
    "locale": "zh-CN",
    "quality_profile": "showcase",
    "animation": "trace",
    "viewBox": [1360, 920],
    "views": [
      {
        "id": "view-id",
        "label": "导览章节标签",
        "focus": ["node1", "node2"],
        "note": "聚焦说明文案"
      }
    ]
  },
  "components": [...],
  "boundaries": [...],
  "connections": [...],
  "cards": [...]
}

3.2 几何走线与排版黄金法则（Zero-Warning Standard）

Desktop Readability 约束：
- 保证在 1440px 桌面视口下，字号投影 $\geq 6.0 px$ ；
- 建议 viewBox 宽度控制在 1360px 内，确保 $9.0 px$ 的子标签投影为 $9.0 \times \frac{930}{1360} \approx 6.15 px > 6.0 px$ 。
连接点法线与垂直出入（Perpendicular Endpoint Side Direction）：
- fromSide: "bottom" 必须垂直向下离开；
- toSide: "top" 必须从上方垂直向下进入目标中点；
- 必须精确对齐组件的几何中心点（例如 X = pos[0] + width / 2）。
安全通道隔离（Corridor Clearance）：
- 走线间距保持 $\geq 12 px$ ，避免非关联连线穿透组件（clean-flow/edge-through-node）；
- 标签与并行走线预留 $\geq 4 px$ 间隙。

4. 首期核心架构（Pilot Test）交付清单

4.1 核心产物索引

产物名称	物理路径	说明
JSON IR 规格源	`d:\ida ceo\reports\archify_multiagent_graph.architecture.json`	20 个核心组件、4 大安全边界、4 组导览视图
交互式 HTML 大图	`d:\ida ceo\reports\archify_multiagent_graph.html`	765 KB 自包含 HTML，集成流光动效与中文检索
暗色真机渲染图	`d:\ida ceo\reports\screenshots\archify_multiagent_graph_overview_dark.png`	1920x1080 暗色高保真渲染
亮色真机渲染图	`d:\ida ceo\reports\screenshots\archify_multiagent_graph_overview_light.png`	1920x1080 亮色模式渲染
导览聚焦真机图	`d:\ida ceo\reports\screenshots\archify_multiagent_graph_guided_view.png`	IDA PC 执行中枢高亮聚焦

4.2 拓扑四大核心域

Cloudflare Edge 云端基础设施：Anycast CDN、WAF 防护、Workers 边缘接口（hsd-cashflow）、D1 数据库群与 Named Tunnels 安全隧道；
IDA PC 24/7 执行中枢：AGY CEO 大管家协同 DSH 总管家，统管 master-app / ops / hsdesign / watch 四域 PM 矩阵，直控 Debian 13 WSL 2、Live Collab 与 Local Tuya Hub（8788）；
Sozo PC 主力与移动救援节点：Hermes 主控派单 PI Agent（DeepSeek V4 Flash max），S23 Ultra Termux 与 OpenCode CLI 构成双向免密 SSH 8022 应急救治链路；
全局事实源与知识同步层：Google Drive 虚拟盘与 Obsidian Vault 构建跨端唯一真实源（SSOT）。

5. Quartz 4 知识库与 App Portal 嵌入标准

5.1 嵌入代码规范（Iframe 隔离方案）

在 Quartz 4 Markdown 页面中内嵌交互图谱：

<div class="archify-container" style="margin: 2rem 0; border-radius: 12px; overflow: hidden; border: 1px solid var(--lightgray); box-shadow: 0 8px 30px rgba(0,0,0,0.12);">
  <iframe src="/static/archify/multiagent_graph.html" width="100%" height="680" frameborder="0" style="display: block; width: 100%;"></iframe>
</div>

5.2 离线资产与构建同步 SOP

将 d:\ida ceo\reports\archify_multiagent_graph.html 复制至 Quartz 项目的 content/static/archify/multiagent_graph.html；
在 Quartz 页面中引用；
执行 npx quartz build 编译静态资源；
通过 wrangler pages deploy 部署至 Cloudflare Pages。

HS Knowledge Vault

探索

archify-code-graph-pilot