技术白皮书 · 正式发布

.guzhi 开放标准

开放解剖数据包标准 · 让解剖教学资源像网页一样开放、可分享、可离线

版本1.0.0
状态正式发布
许可CC BY-SA 4.0
发布日期2026-09
在线阅读 查看数据包结构
01

引言

1.1 什么是 .guzhi 标准 ▾

.guzhi 是一套开放解剖数据包标准，定义了如何将 3D 解剖模型、结构化标签和教学知识库封装为一个自包含的 ZIP 容器。一个 .guzhi 文件即代表一套完整的、可交互的解剖教学资源——无需后端、无需安装、无需联网。

该标准源自「古志（Guzhi）」项目——一个纯前端、零服务器的离线 3D 解剖 AI Web 应用。经过多版本迭代验证（v1.0 → v3.3.0），其架构已被证明可以在 Cloudflare Pages 等静态托管平台上稳定运行，覆盖骨骼、肌肉、神经等 329+ 个解剖结构。

1.2 为什么需要它 ▾

当前 3D 解剖教学资源面临三大困境：

🔗

平台锁定

解剖模型被绑定在特定商业平台，无法离线使用，数据主权不属于教育者。

📦

资源碎片化

3D 模型、标签数据、教学文本分散在不同格式和系统中，缺乏统一的封装标准。

🌐

网络依赖

现有方案几乎都需要联网访问，在手术示教、野外学习、教学机房等场景下不可用。

.guzhi 标准通过定义统一的 ZIP 数据包格式，使任何人都能创建、分享和部署离线可用的解剖教学资源。

1.3 核心理念 ▾

一

一个文件即一套资源

.guzhi 文件 = ZIP 容器，内含 3D 模型 + 标签 + 知识库 + 元数据，双击即用。

二

纯前端零服务器

HTML/CSS/JS 直接渲染，静态托管即可上线，无需 Node.js、无需数据库、无需 API。

三

全中文本地化

解剖术语、知识库文本、用户界面全部中文化，适配中国医学教育场景。

四

开放可分享

标准完全开放，数据包可经邮件、U盘、网盘等任意渠道分发，CC BY-SA 4.0 许可。

02

设计原则

2.1 纯前端零构建 ▾

.guzhi 标准要求所有运行时代码为纯 HTML/CSS/JavaScript，不依赖任何编译步骤或构建工具。这意味着：

  • 无 Node.js 依赖：不需要 npm install、webpack、vite 等构建流程
  • ES Module + Importmap：使用浏览器原生模块系统，Three.js 等依赖通过 importmap 声明
  • 单一入口：index.html 是唯一入口文件，位于 ZIP 根目录
  • 即开即用：解压后双击 index.html 即可在浏览器中运行
importmap 声明示例
<script type="importmap">
{
  "imports": {
    "three": "https://unpkg.com/three@0.160.0/build/three.module.js",
    "three/addons/": "https://unpkg.com/three@0.160.0/examples/jsm/"
  }
}
</script>

2.2 离线优先 ▾

所有资源必须自包含在 .guzhi 数据包内，不依赖任何外部网络请求。包括：

📦

3D 模型本地化

GLB 模型文件内嵌于 ZIP，Draco 解码器 wasm 同步打包，零外网依赖。

📚

知识库内嵌

解剖结构知识以 JSON 格式内置，支持 fallback 默认值机制。

🎨

UI 资源自包含

图标使用 SVG 内联，字体使用系统字体栈，CSS/JS 全部本地引用。

2.3 零服务器架构 ▾

数据持久化使用浏览器 localStorage，不引入任何后端服务。数据流如下：

.guzhi ZIP 数据包
3D模型 + 标签 + 知识库
→
浏览器渲染引擎
Three.js + ES Modules
→
用户交互界面
3D查看 + AI对话 + 学习统计
localStorage
学习进度 / 错题本 / API Key / 设置

此架构可在 Cloudflare Pages、Netlify、GitHub Pages 等任意静态托管平台部署，构建命令和输出目录均留空。

2.4 全中文本地化 ▾

标准要求所有面向用户的文本均为中文，包括：

  • 解剖术语：采用中国解剖学会《人体解剖学名词》标准译名
  • 知识库文本：精讲、对比、刷题、记忆、规划、战略六类指令模板全中文
  • 界面文案：按钮、菜单、提示、错误信息全部中文化
  • 双语映射：labels.json 同时保留中英文术语，支持双向检索
03

两大资产分支

.guzhi 数据包内包含两大独立的资产分支，可分别更新、独立版本管理。两者通过 manifest.json 中的结构映射关联。

分支 A：3D 模型资产

GLB 格式容器 · 节点级结构标识 · Draco 压缩

▾

核心规范

容器格式GLB (GL Transmission Binary)
压缩方案Draco 几何压缩（减少 70-90% 体积）
节点标识每个解剖结构对应一个 GLB Node，通过 nodeId 映射
材质标准PBR 材质，sRGB 色彩空间
相机预设每个结构预设 cameraPosition / cameraTarget
高亮机制EffectComposer + OutlinePass 金色描边

文件结构

3D 模型资产目录结构
models/
├── body.glb              # 主模型文件（Draco 压缩）
├── skeleton.glb          # 骨骼系统（可选独立文件）
├── muscles.glb           # 肌肉系统（可选独立文件）
└── lib/
    ├── draco_decoder.wasm  # Draco 解码器
    └── draco_wrapper.js    # 解码器封装
设计要点：模型文件使用 GLB 而非 glTF JSON，因为二进制格式读取更快、文件更小。Draco 压缩使典型人体模型从 ~50MB 压缩至 ~5MB。

分支 B：知识数据资产

结构化标签 · 解剖知识库 · 多层教学分类

▾

核心组件

标签文件labels.json — 中英文术语映射
结构映射structures.json — nodeId → 结构信息
知识库knowledge_base/ — 按系统拆分的 JSON 文件
教学分类五级层级 L1框架→L2空间→L3结构→L4功能→L5应试验收
指令模板精讲/对比/刷题/记忆/规划/战略 六类
编码格式UTF-8，无 BOM，支持中文直接读写

知识库目录结构

知识数据资产目录结构
knowledge_base/
├── skeleton.json        # 骨骼系统知识（269条）
├── muscles.json         # 肌肉系统知识（439条）
├── nerves.json          # 神经系统知识
├── vessels.json         # 血管系统知识
├── joints.json          # 关节系统知识
├── ligaments.json       # 韧带系统知识
├── organs.json          # 内脏系统知识
└── default_fallback.json # 内嵌默认回退值
设计要点：知识库按解剖系统拆分为独立 JSON 文件，而非单个大文件。加载时按需读取，未加载的系统使用 default_fallback.json 提供基本占位信息，保证页面不报错。

五级教学层级

L5 应试验收 — 模拟考核、错题复盘
L4 功能临床 — 功能机制、临床意义
L3 结构辨识 — 起止点、毗邻关系
L2 空间定位 — 3D空间位置、层次
L1 框架认知 — 系统名称、大体概念
资产关联：两大分支通过 manifest.json 中的 structureMap 字段关联。3D 模型的 nodeId 与知识数据的结构 ID 一一对应，实现「点击 3D 模型 → 高亮结构 → 弹出知识卡片」的双向联动。
04

数据结构规范

4.1 manifest.json — 数据包元数据 ▾

manifest.json 是 .guzhi 数据包的入口文件，定义版本、模型路径、结构映射和配置信息。

manifest.json 
{
  "specVersion": "1.0.0",
  "package": {
    "name": "人体解剖基础数据包",
    "nameEn": "Human Anatomy Basic Pack",
    "version": "1.0.0",
    "author": "Guzhi Project",
    "license": "CC BY-SA 4.0",
    "description": "包含骨骼、肌肉、神经等329个解剖结构的基础数据包",
    "createdAt": "2026-09-01",
    "updatedAt": "2026-09-01"
  },
  "model": {
    "format": "glb",
    "mainModel": "models/body.glb",
    "systems": {
      "skeleton": "models/skeleton.glb",
      "muscles": "models/muscles.glb"
    },
    "dracoDecoderPath": "models/lib/draco/",
    "encoding": "sRGB",
    "outlineColor": "#FFD700"
  },
  "structureMap": {
    "bone_001": {
      "nodeId": "Bone_001",
      "nameCn": "股骨",
      "nameEn": "Femur",
      "system": "skeleton",
      "level": "L3",
      "cameraPosition": [120, 80, 200],
      "cameraTarget": [0, 80, 0],
      "knowledgeRef": "knowledge_base/skeleton.json#femur"
    },
    "muscle_001": {
      "nodeId": "Muscle_Quadriceps_001",
      "nameCn": "股四头肌",
      "nameEn": "Quadriceps Femoris",
      "system": "muscles",
      "level": "L3",
      "cameraPosition": [100, 60, 180],
      "cameraTarget": [0, 60, 0],
      "knowledgeRef": "knowledge_base/muscles.json#quadriceps"
    }
  },
  "ui": {
    "defaultLang": "zh-CN",
    "theme": "anatomy-blue-green",
    "primaryColor": "#1a3a5c",
    "accentColor": "#2d8f7a"
  }
}
字段类型必填说明
specVersionstring是标准版本号，当前为 "1.0.0"
packageobject是数据包基本信息（名称、版本、作者、许可）
modelobject是3D 模型配置（路径、格式、解码器、色彩空间）
structureMapobject是结构映射表，key 为结构 ID，关联 nodeId 与知识库
uiobject否界面配置（语言、主题、配色）

4.2 labels.json — 解剖术语标签 ▾

labels.json 存储所有解剖结构的中英文双语术语映射，是 3D 模型节点与知识库之间的桥梁。

labels.json 
{
  "version": "1.0.0",
  "totalCount": 329,
  "labels": [
    {
      "id": "bone_001",
      "nodeId": "Bone_001",
      "nameCn": "股骨",
      "nameEn": "Femur",
      "alias": ["大腿骨"],
      "system": "skeleton",
      "category": "长骨",
      "pinyin": "gǔ gǔ"
    },
    {
      "id": "bone_002",
      "nodeId": "Bone_002",
      "nameCn": "胫骨",
      "nameEn": "Tibia",
      "alias": ["小腿内侧骨"],
      "system": "skeleton",
      "category": "长骨",
      "pinyin": "jìng gǔ"
    },
    {
      "id": "muscle_001",
      "nodeId": "Muscle_Quadriceps_001",
      "nameCn": "股四头肌",
      "nameEn": "Quadriceps Femoris",
      "alias": ["股四头"],
      "system": "muscles",
      "category": "肌群",
      "pinyin": "gǔ sì tóu jī"
    }
  ]
}
字段类型必填说明
idstring是结构唯一标识，与 structureMap 的 key 对应
nodeIdstring是GLB 模型中的 Node 名称
nameCnstring是中文标准名称（解剖学会译名）
nameEnstring是英文标准名称（Terminologia Anatomica）
aliasstring[]否常用别名/俗称列表
systemstring是所属系统（skeleton/muscles/nerves等）
pinyinstring否拼音，支持模糊搜索

4.3 structures.json — 3D 结构映射 ▾

structures.json 定义 3D 模型中每个 Mesh 节点到解剖结构 ID 的映射，用于双向联动（点击模型 → 定位知识 / 搜索知识 → 高亮模型）。

structures.json 
{
  "version": "1.0.0",
  "meshCount": 329,
  "meshes": {
    "Bone_Femur_L": { "structureId": "bone_001", "meshName": "Bone_001" },
    "Bone_Femur_R": { "structureId": "bone_001", "meshName": "Bone_001" },
    "Bone_Tibia_L": { "structureId": "bone_002", "meshName": "Bone_002" },
    "Bone_Tibia_R": { "structureId": "bone_002", "meshName": "Bone_002" },
    "Muscle_Quad_L": { "structureId": "muscle_001", "meshName": "Muscle_Quadriceps_001" }
  },
  "fallback": {
    "strategy": "meshName_to_structureId",
    "defaultStructureId": null,
    "hideRawIds": true
  }
}
容错机制：当 GLB 模型中的 meshName 未在映射表中找到对应 structureId 时，系统自动使用 meshName 作为 fallback 键，在列表中隐藏原始 GLB ID，避免用户看到不可读的内部标识。
05

数据包模拟

以下可视化展示了 .guzhi 数据包的 ZIP 容器物理结构。点击文件夹展开/折叠，直观理解数据包的组织方式。

anatomy-basic.guzhi ~5.2 MB
📦

点击左侧文件查看详情

.guzhi 文件本质是一个 ZIP 压缩包，扩展名改为 .guzhi 仅为语义标识

命名约定：数据包文件名格式为 [名称]-[版本].guzhi，例如 anatomy-basic-1.0.0.guzhi。ZIP 内 index.html 必须位于根目录，不嵌套子文件夹。
06

3D 模型查看器

此区域为 3D 模型查看器的演示占位。实际部署后，此处将加载 .guzhi 数据包中的 GLB 模型，支持旋转、缩放、结构点击高亮。

正在加载 3D 场景...

场景控制
几何体—
渲染器—
帧率—
模拟结构列表
  • 股骨 (Femur)
  • 胫骨 (Tibia)
  • 腓骨 (Fibula)
  • 颅骨 (Skull)
  • 脊柱 (Spine)
占位说明：当前 3D 场景使用 Three.js 几何体作为占位演示。正式使用时，将 app.js 中的场景初始化代码替换为 GLTFLoader 加载 .guzhi 数据包中的 body.glb 即可。所有交互逻辑（点击高亮、相机定位、结构切换）已预留接口。
07

生态路线图

.guzhi 标准的演进规划，从核心规范发布到社区生态建设。

v1.0.0 2026-09

标准发布

  • 核心规范定义（manifest / labels / structures）
  • GLB + Draco 压缩方案确定
  • 基础数据包（329 结构）验证通过
  • Cloudflare Pages 部署验证
已完成
v1.1.0 2026-Q4

知识库扩展

  • 神经/血管/韧带/关节系统知识库补全
  • 708 库全量结构映射
  • AI 对话导出/导入模块
  • WebDAV 同步增强
进行中
v1.2.0 2027-Q1

社区工具链

  • .guzhi 数据包打包工具（CLI）
  • 在线数据包编辑器
  • 结构标注可视化工具
  • 多数据包合并/拆分
计划中
v2.0.0 2027-Q3

交互式教学引擎

  • AI 驱动的自适应学习路径
  • SSE 流式解剖问答
  • 跨数据包知识图谱
  • 协作标注与社区分享
远期规划
08

部署指南

8.1 本地运行 ▾

  1. 解压 .guzhi 数据包（或本白皮书 zip）到任意目录
  2. 直接双击 index.html 在浏览器中打开
  3. 或使用本地服务器：python3 -m http.server 8766
  4. 浏览器访问 http://localhost:8766
注意：ES Module 模式下，直接双击打开 file:// 协议可能被浏览器 CORS 策略拦截。建议使用本地 HTTP 服务器。

8.2 Cloudflare Pages 部署 ▾

  1. 登录 Cloudflare Dashboard → Pages → Create a project
  2. 选择 "Direct Upload" 直接上传模式
  3. 将解压后的文件夹拖入上传区域
  4. 构建命令：留空
  5. 输出目录：留空
  6. 点击 "Deploy site"，约 30 秒后获得 *.pages.dev 链接
关键要求：ZIP 包内 index.html 必须在根目录，不能套子文件夹。此前因嵌套 guzhi/ 文件夹导致 Pages 部署成功但页面空白的教训。

8.3 备选部署方案 ▾

🟧

Netlify Drop

访问 app.netlify.com/drop，直接拖入文件夹即可部署，零配置。

🐙

GitHub Pages

推送到 GitHub 仓库，开启 Pages 服务，选择 main 分支根目录。

🐱

Gitee Pages

国内访问优化方案，推送到 Gitee 仓库后开启 Pages 服务。