Skip to content

RULES.md

Latest commit

 

History

History
307 lines (233 loc) · 23.8 KB

RULES.md

File metadata and controls

307 lines (233 loc) · 23.8 KB
Raw

药学领域特化参数（RULES）

本文件是 frontmatter.md 在药学领域的特化参数文档，定义：

  • 药学顶层类（fill 取值）
  • fill 默认外观配置（形状/背景色/默认边框）
  • stroke 渲染参数（边框样式组合值）
  • 药学概念 → fill/stroke 映射表

不包含：转录工作流、字段制作规范、照片提取原则、YAML 格式、质量检查清单——这些在 SKILL.md 中。

旧 essence → 新规范迁移映射见 §七（本文件维护权威源）。 字段填写细则索引（tags / reason / summary / location / edges_out.type 等）见 §八。各权威源的指针集中在此，本文件不复制细则正文。 通用字段规范见 frontmatter.md（基于 OWL2，不绑定学科）。 视觉配置的单一来源是 src/core/config.ts（FILL_CONFIG / STROKE_CONFIG / SHAPE_BY_OWL2 / FILL_BORDER_HINTS）。本文件中的外观表格是说明性副本，若与 config.ts 不一致，视为文档过期，先核对 config.ts 再修订本文件。 转录铁律（逐字转录、唯一来源、加粗即 tags 等）见 SKILL.md §零。

一、设计理念

构图原则（初学搭建框架阶段）：上层维持严格树状层级以建立清晰知识骨架，仅允许在底层叶子节点局部引入网状横向关联，不追求一次性还原现实全部复杂联系。 原理依据：现实知识本体是完整网状系统，但人的工作记忆有限；树状结构保障框架可理解、可维护，网状用于捕捉跨节点的隐性联系。采用“上树下网”的混合认知模型，本体可留存全部关系，可视化视图做适度裁剪，避免因过度还原真实而陷入信息过载、视图混乱。

本项目采用 OWL2 风格的 5 种边关系类型（subclass_of / instance_of / part_of / disjoint_with / equivalent_to，见 frontmatter.md §3.8；config.ts 的 EDGE_TYPE_STYLE 中另有 default 兜底样式，不计入） + 三维度视觉编码：

  • shape（OWL2 实体类型）：显式填写时覆盖 fill 的默认形状（一对一固定映射）
  • fill（领域顶层类）：决定背景色 + 默认形状 + 默认边框色（配置中心）
  • stroke（边框样式组合值）：显式填写时覆盖 fill 的默认边框（双线/光晕/流光）

fill 是配置中心：每个药学顶层类定义完整默认外观；shape/stroke 显式填写时覆盖 fill 默认值。 double 是重点节点专用：所有 fill 的 defaultStroke 统一为 glow（默认呼吸光晕）；重点节点需在节点 frontmatter 中显式写 stroke: double。

二、药学顶层类（fill 取值范围）

药学图谱所有节点 fill 必填（通用图谱可选，见 frontmatter.md §3.3）。

以下 10 个顶层类本身也是 shape: class 的节点，作为 fill 的引用目标。

fill 值 名称 包含的节点
cls-structure 组织结构 书/篇/章/节入口
cls-classification 药物分类 粗分类/细分类/亚类
cls-drug 药物 具体药物（重点+普通）
cls-disease 疾病 疾病/症状/综合征
cls-biomolecule 生物实体 靶点/受体/酶/转运体/基因
cls-feature 作用特点/临床评价 作用特点/临床用药评价/选药原则
cls-adverse 不良反应/禁忌 典型不良反应/禁忌/毒性
cls-concept 抽象概念/总论 定义性概念/总论/术语
cls-summary 总结 节内总结/跨节大总结/表格
cls-mnemonic 口诀 记忆口诀/顺口溜

三、OWL2 实体类型 → 几何形状映射（shape 显式填写时生效）

shape 取值 OWL2 原名 几何形状 设计意图
class owl:Class round-rectangle 类用圆角矩形——比纯矩形柔和，比椭圆正式
named_individual owl:NamedIndividual ellipse 实例用椭圆——最通用的具体物形状
object_property owl:ObjectProperty hexagon 实体化的关系用六边形——视觉区分于实例
data_property owl:DatatypeProperty rectangle 数据属性用纯矩形——紧凑、突出数值感
annotation_property owl:AnnotationProperty tag 注释用标签形——视觉上像"附加的注释标签"
auto — 由 fill 决定 留空走 fill 默认（可为 vee / tag / barrel / star 等扩展形状）

覆盖规则：显式填写 shape: <owl2类型> → 用映射表的固定形状，覆盖 fill 的默认形状。 留空时 → 用 fill 默认形状（FILL_CONFIG 可提供 vee / tag / barrel / star 等扩展形状）。 一对一映射：见 src/core/config.ts 的 SHAPE_BY_OWL2 常量。

四、fill 默认外观配置表

原则：fill 只管背景色 + 默认形状 + 默认 stroke。边框色由 stroke 方案决定：

  1. 节点显式 stroke（double/glow/flow/fallback）→ STROKE_CONFIG[stroke].color + 对应特效
  2. 节点没填 stroke → 用 FILL_CONFIG[fill].defaultStroke（所有 fill 均默认为 glow）
  3. 节点填了 stroke="auto" 或没 fill → 走 subtreeRoot 色 / fill 兜底边框色 fallback

4.1 fill 字段定义

"默认 stroke" = 节点不填 stroke 时使用的值（统一为 glow，详见 4.4）。 "fill 兜底边框色" = 节点显式 stroke: auto 且无 subtreeRoot 时，按 fill 取的边框色（FILL_BORDER_HINTS[fill]）。

fill 中文含义 形状 背景色 默认 stroke fill 兜底边框色
cls-structure 组织结构 round-pentagon（五边形） #fae8e3 柔奶杏粉 glow #c89b8a 浅棕
cls-classification 药物分类 octagon（八边形） #ffe4b5 柔莫兰迪黄 glow #c9a06a 莫兰迪棕黄
cls-drug 药物 ellipse（椭圆） #dbeafe 柔天空蓝 glow #7aa8d9 浅蓝
cls-disease 疾病 diamond（菱形） #fce7f3 柔樱花粉 glow #e89bb8 浅粉
cls-biomolecule 生物实体 round-triangle（圆角三角） #d1fae5 柔薄荷绿 glow #6dbfa0 浅绿
cls-feature 作用特点/临床评价 star（星形） #cffafe 柔湖青 glow #7db8c4 浅青
cls-adverse 不良反应/禁忌 round-hexagon（圆角六边形） #ffe4e6 柔玫瑰粉 glow #d4868f 浅玫
cls-concept 抽象概念/总论 round-rectangle（圆角矩形） #e0e7ff 柔雾紫蓝 glow #818cf8 浅紫
cls-summary 总结 bottom-round-rectangle（下圆矩形） #fef9c3 柔麦穗黄 glow #c9b96a 浅黄
cls-mnemonic 口诀 tag（标签形） #fed7aa 柔蜜桃橙 glow #d4884e 浅橙
owl:Thing（兜底） 默认 ellipse #f9fafb 极浅灰 glow #9ca3af（FILL_BORDER_DEFAULT）

边框色名称统一："fill 兜底边框色" = stroke=auto 链路无 subtreeRoot 时的边框色 = FILL_BORDER_HINTS[fill] 值。 该色同时被 stroke: fallback 链路使用（详见 5.1 完整链路）。

4.2 字段兜底关系：fill / shape / stroke 三件套

核心原则：三个字段都是"我要这个节点长什么样"——用户显式填写的值就是最终决定；不填时由 fill 兜底。

字段 用户显式值 用户不填（undefined/字段缺失）
fill 用用户填的 fill 节点归入通用类（不参与 fill 配置；边框色降级到 FILL_BORDER_DEFAULT）
shape 用用户填的 shape FILL_CONFIG[fill].shape（fill 缺失时用 ellipse）
stroke 用用户填的 stroke（含 'auto' / 'glow' / 'flow' / 'fallback' / 'double'） FILL_CONFIG[fill].defaultStroke（统一为 'glow'）

关键点：

  • fill 在药学图谱中必填（通用图谱可选）——技术上不填也能渲染（通用外观），但会失去 fill 提供的语义色，药学节点不应出现这种情况
  • shape 不填 → 用 FILL_CONFIG[fill].shape
  • stroke 不填 → 用 FILL_CONFIG[fill].defaultStroke（统一为 glow，呼吸光晕）
  • defaultStroke（当前 glow）始终生效：无论 md 填不填 stroke，它都是底子
  • md 填了 stroke 时，在 defaultStroke 之上叠加 md 自己的效果：边框本体由 md 决定，覆盖层特效两者并存
  • 合并方式由 STROKE_MERGE_MODE 控制：默认 coexist（并存）；改为 override 后，md 填 stroke 时 defaultStroke 才让位

示例（假设 fill=cls-drug）：

  • fill: cls-drug（无 shape/stroke）→ 椭圆药物 + 默认边框（glow，呼吸光晕）
  • fill: cls-drug, shape: object_property → 六边形药物 + 默认边框（shape 显式覆盖为六边形，stroke 仍走 glow）
  • fill: cls-drug, stroke: auto → 椭圆药物 + fill 兜底边框色（subtreeRoot 色优先，无则 #7aa8d9）
  • fill: cls-drug, stroke: double → 椭圆药物 + 双线边框（重点药/重点分类）

4.3 形状分配设计意图

  • 结构/概念：方形系（round-pentagon / round-rectangle）—— 稳定的"骨架/定义"
  • 分类/总结：多边形系（octagon / bottom-round-rectangle）—— 明显的"层级感"
  • 药物/疾病：实物形（ellipse / diamond）—— 直觉化的"物质感"
  • 生物实体：圆角三角形（round-triangle）—— 三角形的"指向/锚定"意象，靶点/受体是药理作用的锚点
  • 特点/口诀：特征形（star / tag）—— 醒目的"标签/亮点"
  • 不良反应：警示形（round-hexagon）—— 类似交通警示标志，唤起警惕

4.4 默认 stroke 设计意图

fill defaultStroke 理由
所有 fill glow 所有 fill 统一默认 glow（呼吸光晕）；重点节点需在 frontmatter 中显式写 stroke: double

为什么统一为 glow？ 呼吸光晕作为所有节点的默认底色，让普通节点也保留轻微动感；重点节点（临床用药评价分支下的重点药/重点分类）则显式写 stroke: double，用双线边框进一步强调。

如需某 fill 始终按 fill 颜色着色（不跟子树走），可把 defaultStroke 改为 fallback 或让节点显式写 stroke: fallback（需同步改 src/core/config.ts）。

4.5 边框色配置

  • FILL_BORDER_HINTS（在 src/core/config.ts 末尾）：fill 兜底边框色，stroke=auto 链路无 subtreeRoot 时（5.1 第 4 步）和 stroke=fallback 时（5.1 第 2 步）都用它
  • FILL_BORDER_DEFAULT（也在 src/core/config.ts 末尾）：节点连 fill 都没填时的中性灰边框色

设计原则：每个 fill 的边框色与背景色系协调、取同一色相的中等明度版本，保持"色块是这类内容"的视觉记忆。

调色流程：先在 FILL_BORDER_HINTS 调色，覆盖的是 stroke=auto 默认外观和 stroke=fallback 默认外观（共用一张表）；如需特殊边框（比如某节点想用 subtreeRoot 色），节点填 stroke: auto 后由 subtreeRoot 接管，无需改 hints。

覆盖规则：

  • 显式填写 shape: hexagon → 覆盖 fill 的默认几何形状
  • 显式填写 stroke: double → 覆盖 fill 的默认边框（双线边框）
  • 不填 → 使用 fill 的默认配置（defaultStroke: glow，呼吸光晕）

五、渲染参数

5.1 stroke 组合值

权威说明：本节是 stroke 取值与渲染链路的唯一权威源。SKILL.md §1.4 给出了简化判定清单，但其文字以本节为准；若两处文字出现分歧，以本节为准。

stroke 值 边框色 线型 特效 适用场景
auto subtreeRoot 色 或 FILL_BORDER_HINTS[fill] solid 实线 无 跟子树走
fallback FILL_BORDER_HINTS[fill]（不查 subtreeRoot） solid 实线 无 按 fill 自身颜色着色的节点
glow 固定紫 #818cf8（有子树时被子树色覆盖） solid 实线 呼吸脉冲光晕 默认 stroke（所有 fill 的 defaultStroke）
flow 同 auto（subtreeRoot 色 / fill 兜底） solid 实线 绕节点旋转的流动光点 需要"流动"强调的节点
double 同 auto（subtreeRoot 色 / fill 兜底） double 双线 无 重点节点：临床用药评价分支下的重点药（med-）/重点分类

什么是重点节点（stroke: double）？

临床用药评价分支下独立成框的节点：

节点类型 示例 判定标准
重点药 地西泮、唑吡坦、巴氯芬 纸质版"临床用药评价"分支下有该药的独立框（含作用特点/临床应用/不良反应正文）
重点分类 巴比妥类、苯二氮䓬类 纸质版"临床用药评价"分支下直接出现该分类名，且其下有作用特点/不良反应

例外：cls-summary 中的"跨节大总结/表格"不在临床用药评价分支下，但同样写 double（见 §六）。

电子版说明：判定依据是纸质版位置；电子版不保留"临床用药评价"分支节点（内容并入重点药 full），因此不能靠图上的层级反推。

关键区分：double 的判定依据是"该节点是否出现在纸质版'临床用药评价'分支下"，不是"该分类下有没有药"或"该分类有没有代表药"。分类与作用机制分支里的分类，即使列出了代表药，也不加 double。

示例：中枢肌松药的"非苯二氮䓬类"只出现在分类分支，临床用药评价分支下直接是乙哌立松/巴氯芬/氯唑沙宗三个药 → 非苯二氮䓬类不加 double，三个药加 double。

边框本体（线型/颜色）取色优先级（覆盖层特效独立叠加，见下文）：

  1. 用户填 stroke: double → 双线边框，取色同 auto（subtreeRoot 色 / fill 兜底）
  2. 用户填 stroke: fallback → 直接用 FILL_BORDER_HINTS[fill]，跳过 subtreeRoot
  3. 用户填 stroke: glow → 呼吸光晕（有子树时被子树色覆盖，无子树用固定紫）
  4. 用户填 stroke: flow → 取色同 auto，外加旋转光点
  5. 用户填 stroke: auto + 有 subtreeRoot → subtreeRoot 色
  6. 用户填 stroke: auto + 无 subtreeRoot → FILL_BORDER_HINTS[fill]
  7. 用户不填 stroke → FILL_CONFIG[fill].defaultStroke（统一为 glow）
  8. 节点连 fill 都没填 → FILL_BORDER_DEFAULT（中性灰）

特效叠加（与上面独立）：defaultStroke 的 glow/flow 特效始终生效；md 填的 stroke 特效在此基础上再叠加。 合并方式由 STROKE_MERGE_MODE 决定：coexist（默认）两者并存；override 时 md 填了 stroke 就完全接管，defaultStroke 不再生效。

auto vs fallback 的区别：

  • auto：先查 subtreeRoot，有就用子树色（保持同子树视觉统一）；无才用 fill 兜底边框色

  • fallback：永远按 fill 兜底边框色着色，subtreeRoot 完全不参与

  • 边框宽度默认 2px（double 为 4px），不参与区分

六、药学概念 → fill/stroke 映射表

药学概念 fill 普通节点 stroke 重点节点 stroke
书/篇/章/节入口 cls-structure 不填 —
药物分类（无临床评价） cls-classification 不填 —
药物分类（有临床评价） cls-classification — double
普通药（仅提名） cls-drug 不填 —
重点药（有药理卡片） cls-drug — double
疾病/症状 cls-disease 不填 —
靶点/受体/酶 cls-biomolecule 不填 —
作用特点/临床评价 cls-feature 不填 —
选药原则/用药注意 cls-feature 不填 —
典型不良反应 cls-adverse 不填 —
禁忌 cls-adverse 不填 —
抽象概念/总论 cls-concept 不填 —
节内总结 cls-summary 不填 —
跨节大总结/表格 cls-summary — double
口诀 cls-mnemonic 不填 —

"重点"判定标准：教材中有详细药理卡片/临床用药评价单独讲解的药物或分类。

七、旧 essence → 新规范迁移映射

本节是旧 essence 字段迁移到新 fill+stroke 字段的权威映射表。迁移工作流（含 data: 包装的去除、essence/depth 字段的移除）见 SKILL.md §8。

旧 essence 新 fill 新 stroke
module cls-structure 不填
umbrella-class / strict-class cls-classification 有临床评价 → double，否则不填
medication cls-drug double
drug cls-drug 不填
notion（作用特点/临床评价/选药原则） cls-feature 不填
notion（不良反应/禁忌） cls-adverse 不填
concept cls-concept 不填
summary cls-summary 跨节 → double，节内不填
mnemonic cls-mnemonic 不填

迁移时同时移除 data: 包装、essence 字段、depth 字段，改为平铺结构。

八、字段填写细则索引

本节不是字段填写规范的副本，而是把分散在三份文档里的填写细则集中到一个跳转索引。规范正文只在权威源维护，本节只负责"在哪里查"。

8.1 tags — 结构标签 + 重点提示词标签

项 内容
权威源 SKILL.md §5.4
字段定义 frontmatter.md §3.6
构成 结构标签（名称 / 归属分类 / 节名 / 下级与代表药）+ 重点提示词标签（summary.full 中的加粗词，按所在【框名】加前缀）
前缀（v1 草案） 药理作用： / 特点： / 适应症： / ADR： / 禁忌： / 相互作用： / 用药注意：
口诀节点 见 SKILL.md §6.3

8.2 reason — edges_out 措辞规范

项 内容
权威源 SKILL.md §5.5
字段定义 frontmatter.md §二"边（OWL2 公理）"
三条铁律 必填 / 必须包含具体对象（药名或分类名）/ 必须能独立成句
边方向铁律 见 §5.5 表格（子类→父类用 subclass_of；药物→分类用 instance_of；口诀/总结用 part_of）
禁止的层位词占位 详细改写表见 SKILL.md §5.5（"该书籍"/"该章"/"第N章的一部分"/"第N节的总结"等）

8.3 其它字段填写

字段 权威源
summary.short / summary.full SKILL.md §5.2–§6.4（字段格式、full 多标签、加粗规则）
location SKILL.md §5.6
shape / stroke 组合值 RULES.md §三 / §四（OWL2 实体类型映射 / fill 默认外观）
edges_out.type（5 种 OWL2 公理） frontmatter.md §3.8
id 命名 / 前缀表 SKILL.md §1.2（frontmatter §六 不再重复维护）

8.4 转录总则与字符规则

项 权威源
逐字转录、唯一来源、疑似印刷错误与待核对清单 SKILL.md §零
重点提示（红色细黑字 / 蓝色加粗字）与加粗规则 SKILL.md §5.3
字符统一（上下标、标点宽度、范围号等） SKILL.md §5.7
纸质版版式符号约定（虚线框、竖线括号、"见侧图"） SKILL.md §2.8

冲突处理：若本索引指向的权威源之间出现分歧，按 AGENTS.md §0 的优先级链处理（AGENTS < ARCHITECTURE < DEVELOP < RULES，RULES 最高）。