geometry-board

name	geometry-board
description	将自然语言、飞书文档选中文本或已有结构转译为直白易懂、简洁克制、具有几何编辑感、按关系选择卡片或点线、可插入飞书文档的高级几何视觉图示。用户要求“画一张图”“把这段内容视觉化”“生成架构图/流程图/对比图”、重绘已有图示、切换构图、自然语言修改图示、导出 SVG/PNG 或插入飞书文档时使用。

蓝色波点几何画板｜Blue Dot

首步：检查运行与交付能力

运行 scripts/doctor.sh --json，确认 Scene JSON 校验可用。需要飞书写入时， 再读取 运行与交付契约 和 Feishu delivery contract，执行身份检查并确认目标。

本仓库提供 Scene JSON 协议、校验器和示例；渲染器由当前 Agent 环境提供。 无法渲染时保留结构化 Scene JSON，并明确报告阻塞点。

目标

把知识表达转成一张“一图一意”的几何图示。核心视觉语言是点、线、面、体及其关系：先提炼唯一核心判断，再判断对象与关系、选择卡片/点线/混合表达，随后选择构图、生成 Scene JSON，用 scripts/validate_scene.py 做确定性结构校验后，按视觉系统规则生成 SVG；不要让模型不经 Scene JSON 与校验就直接自由堆砌像素或 SVG 路径。

默认输出白底、黑白灰加一个强调色、留白充足、几何语义稳定、文字直白易懂且简洁克制的图。视觉上要有“正在编辑一张结构图”的几何编辑感，而不是信息卡片墙；优先保证内容准确、重点清楚、读者一眼能看懂和结果可复用，再追求装饰性；画板负责核心判断、关系和必要副标题，正文负责背景、证据和细节，写入后删除与画板重复的解释。

触发后的标准流程

1. 获取输入。优先读取用户提供的文字或当前选中文本；若用户给出已有图示，先提取其信息关系，再决定是否进入“重绘”流程。
2. 写出内部摘要：这张图要让读者一眼理解什么？读者会带走什么？。只保留一个核心判断，并先用日常业务语言说清楚；混合技术背景时，先写共同收益、判断标准或下一步动作，再放入必要术语；标题要能被陌生读者直接复述，若读者还要先解释隐喻再说结论，就继续改写；若确实存在两个互不相容的判断，拆成两张图或向用户说明取舍。
3. 抽取信息：主体、对象、动作、关系、层级、顺序、状态、对比、重点和辅助信息。
4. 先按“表达方式选择”判断使用卡片、点线或混合，再用 点线面体与视觉关系语言 确定几何语义和主要视觉变量，最后按下方决策规则选择一个主构图。多张画板先建立“主题 → 核心判断 → 构图家族”清单，避免连续套用同一阅读方向和骨架；默认只生成一个最佳结果，用户要求备选时再给最多两个候选。
5. 生成符合 Scene JSON 协议 的结构化场景数据。节点、边和文字都要有表达目的。
6. 运行 scripts/validate_scene.py 做结构约束检查；有错误时先修正 Scene JSON，不要用渲染后的视觉问题掩盖结构问题。
7. 先执行“直白易懂 + 文字克制模式”，删除重复解释、例子、长句、抽象名词堆叠和非关键限定；必要时把一行解释压缩为副标题，再按 Scene JSON 生成 SVG（结构由 validate_scene.py 约束，视觉呈现由模型按下述规则生成）。若画板会插入正文，正文保留背景、证据和链接，删除与标题/副标题重复的说明。使用 视觉系统 中的尺寸、颜色、字号、线宽、留白和禁用规则；涉及点线面体、节奏、格式塔、图层、透明度、网格或动态关系时，读取 点线面体与视觉关系语言。
8. 做视觉审查：检查重叠、溢出、对齐、连线交叉、文字密度、视觉焦点、颜色数量和缩小后的可读性。多张画板还要检查构图家族、阅读方向和视觉重心是否有足够差异。未达标时优先删减信息、重排布局或切换构图。
9. 向用户展示预览，并用一句话说明核心判断和采用的构图。若用户要求文件，输出 SVG；需要兼容性时额外导出高分辨率 PNG。
10. 用户确认后再写入飞书文档。写入前确认目标文档、目标账号/租户和写入方式；不得混用个人与公司身份。先按文档结构建立“画板主题 → 段落锚点”映射，再把画板插入对应段落附近；默认禁止把多张画板一股脑追加到文档末尾或集中到同一处。使用当前可用的飞书文档/云盘能力完成写入并读回验证。
11. 自然语言修改时只改变用户明确提及的部分，保留其他节点、关系和风格；用户要求保留或恢复某个构图时，冻结几何骨架，只修改文字与必要间距；修改后重新校验、渲染和审查。

点线面体核心语言

• 点表达位置和对象；线表达移动、连接、方向和依赖；面表达范围、群组、阶段和共同属性；体表达层级、空间剖面和系统整体。
• 通过位置、距离、尺度、方向、线宽、对齐、重复、包含、重叠、透明度和空白表达关系；每个视觉变量优先只承担一个含义。
• 从点到体优先使用生成关系、轴测、切面、叠层和透明度，不使用写实光影制造装饰性立体感。
• 节奏来自重复与变化，平衡来自对称与有意的不对称，层级来自尺度、位置、线宽和对比度。
• 线条不默认全部使用直线：轴线、边界、对齐线和明确的步骤关系可用直线；流动、反馈、协作、回路和跨空间关系优先使用自然弧线。
• 多条弧线必须有共同的几何依据，例如共享圆心、共同控制点、统一曲率或镜面对称；弧线数量增加时优先用平行偏移或对称展开，不允许随机弯折、方向不一或为了“有设计感”而漂浮。
• Geometry Blue #2F6BFF 是唯一默认强调色，面积小而位置准，只标出核心对象、主路径、当前状态、风险或变化。
• 蓝色圆点是可选的“状态定位点”，不是必备装饰。只有当它明确标记变化、反馈、决策、信号或当前焦点，并且与主路径相连时才使用；没有可说清的语义就删除。
• 蓝色圆点可以出现一个或多个，但数量由语义决定，不由版式填充决定。多个圆点必须表达同一类状态或一组可比较的事件，并保持位置、大小和连接规则一致。
• 使用蓝色圆点时，先回答“这个点发生了什么？”以及“它改变了哪条关系？”。圆点应落在几何中心、主轴、转折点或连接端点上；不要让它漂浮在文字旁边，也不要用它替代普通节点。
• 详细语义、视觉变量和设计原则见 点线面体与视觉关系语言。

构图选择

• 明确时间、流程、因果或演进：axis-flow
• 存在上下依赖、平台/产品/组织分层：layered-architecture
• 一个中心连接多个对象：radial-center
• 两个评价维度、分类、优先级或风险影响：matrix-2d
• 输入经过中间机制产生输出：input-process-output
• 群体分类、筛选、转化或规模收敛：dot-filter
• 系统内部层次、平台能力或空间剖面：section-space
• 旧新模式、冲突、权衡、竞争或目标现实张力：tension-contrast

无法判断时，优先选择最能表达关系的构图，而不是最熟悉的传统流程图。输入缺少明确关系、信息过于零散或更适合表格/数据图表时，明确告知用户并建议缩小范围或换表达方式。

多张画板的构图策略

• 统一视觉系统，主动变化主体构图。标题位置、字体、颜色和线宽保持稳定；关系区可在汇聚、纵向筛选、双栏、上下边界、双路径和二维矩阵之间切换。
• 4 张画板至少使用 3 种构图家族；6 张画板至少使用 4 种。连续两张不要共享完全相同的阅读方向、视觉中心和节点骨架。
• 保留一张经典锚点图。系列开头若表达“若干输入组成系统并产生结果”，优先使用经典汇聚结构：左侧输入 → 中间系统/Harness → 右侧结果。经典构图承担识别与定调，不因追求变化而删除。
• 构图差异必须来自信息关系。流程用路径，筛选用漏斗，双类型用双栏，跨边界行动用上下穿透，有无增量用双路径，双条件判断用二维矩阵。
• 详细的系列编排和内容—构图映射见 视觉系统。

表达方式选择：卡片、点线还是混合

先判断读者要看的是“对象本身”还是“对象之间的关系”，再决定容器和连线：

• 卡片：当对象是相对独立、需要并列比较或需要明确边界的模块时使用，例如方案选项、角色职责、能力单元、指标组。卡片只承载标题和一条短说明，尺寸或位置可以表达层级，不默认全部等大。
• 点与线：当重点是顺序、路径、依赖、网络、流动、信号、变化或共同中心时使用。点表达对象/事件，线表达关系/方向，优先让关系直接可见。
• 混合：当对象本身需要被看作模块，但模块之间也有明显关系时使用。卡片表达真实边界，点线表达模块之间的路径；卡片不能遮住主关系。
• 判断方法：去掉边框后，如果关系仍然清楚，边框多半只是装饰，应改用点线；如果去掉边界会让独立模块难以识别，才保留卡片。卡片不是禁用项，卡片墙才是问题。
• 视觉复核：说明为什么选择这种表达方式；如果所有内容都能被机械地塞进相同卡片，说明还没有完成关系判断。

版式与布局原则

• 居中：主视觉中心落在画布主轴或有意设置的视觉中心，文字使用明确的中心锚点和统一基线；几何中心、文字中心和视觉重心不应互相打架。
• 对齐：使用 8 px 网格、共同基线、共同轴线和统一内边距；对齐是让关系可读，不是把所有元素机械地排成同一列；宁可重新排版，也不要留下“差一点对齐”的边缘错位。
• 排列：按读者阅读顺序组织，默认从左到右、从上到下；一张图只保留一条主路径，相关元素成组，不相关元素拉开，连线尽量不交叉。自然弧线要有明确起点和终点，不能穿过文字；多条弧线采用对称、镜像或等距偏移。
• 紧密度：距离表达关系强弱。同组元素使用 8 / 16 / 24 px，相关组之间使用 40 / 64 px，独立组之间保留更大空白；不要把所有元素平均铺满画布。
• 密度：关系密集处可以紧凑，但必须保留清晰层级；关系稀疏处保留空白，不用额外组件填空。留白是结构的一部分，不是未完成的区域。
• 视觉重点：主对象、主路径和次要信息使用不同的尺寸、线宽、对比度或颜色；禁止多个同等强度的视觉中心。
• 关系优先：先检查容器是否帮助读者识别关系；若边框只是装饰或遮住主路径，就删除卡片，改用点、线、面、层或空间距离。

详细的点线面体生成关系、节奏与平衡、尺度、格式塔、图层、透明度、模块、网格、模式、时间和规则原则见 点线面体与视觉关系语言。

硬约束

• 默认画布 1200 × 675、比例 16:9、8 px 网格；可按用户要求切换 4:3 或 A4 纵向。
• 外边距约为画布宽度的 8%，安全区 64–96 px；留白原则上不低于 40%。
• 颜色只用 #111111 / #666666 / #999999 / #222222 / #B8B8B8 / #E8E8E8 / #F5F5F5 / #FFFFFF 加最多一个强调色；默认强调色为 #2F6BFF（Geometry Blue），强调色面积原则上低于 8%。
• 线宽默认 0.5 / 1 / 1.5 px；轴线和边界优先用直线，流动与反馈优先用自然弧线；避免粗大箭头、随机曲线和无语义线条。
• 中文优先苹方、思源黑体、HarmonyOS Sans 或系统无衬线；英文/数字优先 Inter、SF Pro、Helvetica Neue 或 IBM Plex Sans。
• 文字层级不超过三种；单个节点标签不超过 12 个汉字，中文可见文字默认不超过 80 个汉字，硬上限 120 个汉字。
• 节点默认不超过 15 个，边默认不超过 20 条；不得出现无连接、无语义的装饰节点。
• 禁止蓝紫渐变、玻璃拟态、大面积阴影、高饱和配色、彩色圆角卡片阵列、卡通图标、写实 3D、复杂插画和模板化 SmartArt 审美。
• 禁止把内容拆成三个以上等尺寸信息卡片、圆角卡片墙、标签胶囊或 dashboard 式模块阵列；关系优先用轴线、点、面、层、交叠、辅助线和空间距离表达。
• 不添加原文没有的重要事实；无法确认的关系标为假设或请求用户确认。

视觉定位：几何编辑感，不是信息卡片

• 把画板当作一张正在被编辑的结构图：优先使用几何体、主轴、辅助线、对齐线、定位点、截面、边界和空间关系；这些元素必须有结构作用，不做装饰。
• 默认只设一个主视觉中心或一条主路径。主对象使用最清晰的轮廓和唯一强调色，其他元素降低对比度、尺寸或线宽，不让多个模块争夺注意力。
• 高级审美来自比例、对齐、留白、线条层级和克制的对比，不来自复杂纹理、阴影、渐变、图标或堆叠更多组件。
• 如果一个构图可以被轻易改写成“三张并列卡片”，优先重构为轴线、层级、中心几何体、交叠关系或空间布局。
• 视觉审查时先暂时忽略文字：即使不读文字，也应能看出重点、方向和关系；若去掉文字后只剩一组盒子，视为卡片感过强，必须重排。

文字克制模式（默认）

• 只保留一个核心判断；标题表达判断，几何关系表达逻辑，副标题在必要时补充一行“为什么/怎么用”，正文承载背景、证据和细节。
• 默认采用三层文字：标题、关键词节点、必要注释；副标题承担局部解释时，正文删除相同意思的导语，底部说明默认删除。
• 中文可见文字默认控制在 80 字以内；结构复杂时硬上限 120 字。标题之外的句子尽量不超过 18 个汉字。
• 节点优先使用 2–8 字关键词；把完整解释移到文档正文。
• 一张图最多保留 6–8 个关键节点；信息过多时，先删例子和背景，再删次要节点，不靠缩小字号解决。
• 若出现“标题 + 副标题 + 阶段说明 + 节点说明 + footer”五层文案，至少删掉其中两层。
• 修改已有图示时按顺序执行：删长句 → 压缩节点 → 删除重复副标题 → 删除 footer → 再检查关系是否仍然清楚。

受众与收获模式

• 技术和非技术共读时，先回答“这对我有什么用”：共同语言、判断标准、应用边界或下一步动作；术语放在收益之后。
• 画板标题负责结论，副标题负责消除歧义，节点负责动作和结果；三者形成一条短阅读路径，不重复同一句话。
• 茶水间、群聊、内部推荐等轻阅读场景，正文先给阅读理由和可带走的收获，再给入口链接；画板作为快速入口，承载最小必要解释。
• 正文与画板同时出现时，保留背景、证据、数据、链接和需要展开的细节；删去读者已经能从标题、副标题和关系图中读出的句子。

直白易懂模式（与少字模式同等优先级）

• 优先使用同事日常会说的话，让不熟悉原文的人也能看懂；标题先说结论，节点尽量写成“谁做什么 / 先做什么 / 结果是什么”。
• 能用动词就不用抽象名词，能用短句就不用概念堆叠。例如“先说清楚”优于“提炼判断”，“放回原文”优于“确定输出”。
• 默认少用“赋能、抓手、沉淀、洞察、画像、机制、链路、闭环”等泛化术语；确需保留时，补一个更直白的解释，或改成具体动作和结果。
• 英文缩写只在确有必要时保留；首次出现优先给出中文含义，不能让读者依赖术语表才能理解图。
• 每个标题和节点都做一次“陌生同事测试”：只看画板，能否说出谁、做什么、为什么或下一步是什么；不能时先改文字，再考虑改布局。
• 做一次“3 秒复述测试”：只看标题和主关系，读者应能说出核心判断。公式可直接写成公式，分类可直接写“分两类”，条件可直接写“满足两个条件才做”；不要让读者从抽象隐喻里猜结论。
• 节点可用问题句降低理解成本，例如“这个人是谁”“这个世界是什么”；结果节点优先写“拿到信息”“验证结果”“完成动作”“修改下一步”。
• 直白不等于口语化过度：保持专业、准确和克制，不添加原文没有的判断或情绪。

修改指令的处理

把用户修改分为三类：

• 内容：删除、增加、改名、合并节点；同步更新节点和相关边。
• 结构：改成三层、左右对比、时间轴、闭环或纵向版；只重排受影响结构。
• 视觉：更简洁、增加留白、减少颜色、突出路径、缩小辅助信息；优先调整 Token 和布局，不改变语义。

每次修改都要保留未被提及的内容，重新运行校验和视觉审查，并说明实际改变了什么。

若反馈只指向一张画板，只更新该画板及其源文件，不顺手重画整组。若用户说“保留上一版构图，只改内容”，把构图当作已确认资产，保持节点位置、主路径和视觉重心，仅改文案及其必要适配。

飞书写入与交付

默认先交付可审阅的 SVG/PNG 和一句结果说明，再执行插入。若用户明确要求直接插入，仍需先生成并检查结果。

分段定位与插入规则

• 先读取文档标题层级、段落顺序和已有画板；长文优先读取大纲及候选章节上下文，不凭标题猜位置。
• 为每张画板写出一句内部定位说明：主题 → 对应章节/段落 → 插入锚点。画板表达该段落刚刚引出的关系、流程或判断。
• 默认将画板插在对应段落之后、下一主题标题之前；若该段落有小标题，优先插在小标题下的解释段之后，而不是插在章节开头或文档末尾。
• 多张画板对应不同主题时，按正文主题出现顺序分散插入；同一主题需要多张图时，保持连续但只放在该主题的小节内。
• 保留原文已有画板及其相对位置；除非用户明确要求重排，不移动、替换或合并已有画板。
• 找不到精确锚点时，选择最近的语义完整段落，并在写入前向用户说明位置假设；不要为了完成插入而集中放置。
• 写入后不仅确认画板数量，还要读回大纲和每个插入点前后的文本，核对“画板主题—段落主题”是否匹配。
• 若画板标题与副标题已经承担该段的局部解释，可采用“章节标题 → 画板”的紧凑结构；不要强行保留一段重复导语。

写入飞书前：

• 确认目标文档和插入位置；
• 验证当前使用的账号/租户与用户目标一致；
• 按当前可用连接器或飞书 Skill 的规范上传/插入；
• 写入后读回文档或资源元数据，确认插入成功；
• 在结果中区分“已生成”“已插入”“仅保留源文件”三种状态。

若飞书图片预览暂时返回占位图或空白图，先查询原生节点数量并导出远端 SVG；远端 SVG 可正确回读和渲染时，说明画板内容已写入，再重试图片预览。不要把预览缓存延迟误判为画板丢失。

若飞书侧无法保留 SVG 的可编辑性，插入高分辨率 PNG，同时保留 SVG 源文件；不要把 PNG 插入成功误报为可编辑画板。

交付检查清单

在声明完成前确认：

• 核心判断能用一句话说清，且与原文一致；
• 画板文字直白易懂，陌生读者不需要额外术语解释；
• 卡片、点线或混合表达方式与信息关系匹配，并能说明选择理由；
• 居中、对齐、排列和紧密度经过检查，关系强弱与空间距离一致；
• 构图与关系匹配；
• 多张画板达到构图多样性要求，并保留适合内容的经典锚点图；
• 标题与主关系通过“3 秒复述测试”，读者无需先解释隐喻；
• 无重叠、文字溢出、无意义节点和明显连线交叉；
• 弧线有明确关系语义，多条弧线经过对称、镜像或等距检查，没有随机弯折；
• 黑白灰加一个强调色，字号/线宽/圆角统一；
• 留白充分，缩小至 25% 仍能看懂整体关系；
• Scene JSON 已通过校验；
• 多张画板已按主题分散到对应段落，未无理由集中追加；
• 文件路径或飞书文档写入状态可被用户复核。

详细构图模板、视觉 Token、禁用样式和审查权重见 references/visual-system.md；Scene JSON 字段和示例见 references/scene-json-schema.md。