尧图网站建设 
CocoIndex 文档站内联 SVG 图解开发指南基于 Astro 组件的形状语义化图表体系【免费下载链接】cocoindexIncremental engine for long horizon agents Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/co/cocoindex本指南以dev/agent-skills/cocoindex-diagrams/SKILL.md及其配套参考文档为骨架系统讲解 CocoIndex 文档站docs/内联 SVG 图解体系的完整开发方法论从形状语义化的组件原语、调色板与共享样式到先布局、后组合、再预览验证的标准工作流以及多年迭代沉淀下来的常见陷阱。读完你将掌握在.mdx文档页中创建、编辑与评审高一致性技术图解的完整实战技能并能直接复用到仓库中任意docs/src/content/docs/**文档页。一、为什么文档图解要组件化而不是静态 SVGCocoIndex 文档站的全部图解任何位于docs/src/content/docs/**下的页面内嵌图都以 Astro 组件形式编写统一放在docs/src/components/diagrams/目录下。这个目录是文档图解的唯一事实来源single source of truth——早期由设计工具Excalidraw、Figma、Sketch 等导出的静态.svg文件位于/public/img/**/*.svg已被视为遗留资产会随着组件化替换逐渐删除不再继续编辑。静态 SVG 的三个致命问题正是组件化方案的动机依据docs/src/components/diagrams/README.md编辑需要往返设计工具SVG 是不透明的产物改一处布局就要重新走一遍工具链无共享样式每个图各自为政颜色、线宽、字体漂移难以评审二进制式的大段坐标数据让 git diff 失去可读性。组件化图解则免费获得四重收益收益说明单一调色板CSS 变量改一处变量全局生效CSS:hover驱动的动画零 JS、SSR 友好静态页面保持安静组件边界处类型化 props标签、状态、高亮等以强类型接口暴露可读的 diffgit 评审流畅符合 README.md 中模型来自cocoindex.github.io首页内联 SVG的实践docs/astro.config.mjs中通过astrojs/mdx集成让 Astro 组件可以在.mdx中原生导入使用这是整个体系能够落地的工程基础。二、形状语义以含义而非外观选择原语图解体系的核心原则是shape carries meaning——形状本身传达语义选原语要依据元素是什么而不是看起来顺眼。全部内联 SVG 由一组形状语义原语primitives组合而成它们共享同一套调色板与样式docs/src/components/diagrams/diagrams.css。2.1 基础形状原语形状语义含义原语组件尖角矩形数据文件、chunk、行DataBox圆角矩形子系统 / 逻辑Split、Embed、Drive Folder、Vector Database 等LogicBox支持memoizedstatusprops 与插槽奶油色带表头容器一个 Processing Component承载其他元素ProcessingComponent插槽使用局部坐标系支持memoizedstatus桃色带表头容器一个 CocoIndex App承载其他元素AppContainer插槽使用局部坐标系子弹形左侧平直、右侧圆角目标状态vector、输出文件、数据库行TargetBullet动画虚线带箭头流转 / 因果A 产生 B、A 变换为 BFlowArrow静态虚线无箭头绑定 / 身份X 绑定于 YConnector这里有一个反直觉但重要的设计决策所有非容器逻辑框源、目标、数据、子弹形共用同一种中性奶油色 酒红色填充与描边语义区分完全由形状承担而不是颜色。只有 App 容器保留桃色调用于视觉分组dg-box--app见 diagrams.css 中.dg-box与.dg-box--component的注释。2.2 正交标注状态、缓存徽标与高亮在原语之上有一套与形状正交orthogonal可叠加在任意形状上的标注体系用于表达这次运行中发生了什么Prop取值视觉表现statenew、updated、removed、changed、idle默认掌绿色 / 金色 / 粉色 / 细粉色填充removed的标签带删除线并弱化hover 时显示原生deleted工具提示状态级联通过直接子代 CSS 组合器阻止详见陷阱节statuscache-ready、refreshing左上角徽标缓存命中显示对勾书写动画hover 触发缓存未命中显示旋转箭头hover 触发两者在stateremoved时自动抑制highlighttrue粗掌绿色描边表示当前文字正在讨论的元素memoizedtrue作用于LogicBox/ProcessingComponent右上角酒红色备忘缎带表示该函数/组件被 memo 化memoized缎带、cache-ready徽标、refreshing徽标三个角标的精确位置与尺寸由原语自身内部计算——调用方只需传递容器参考角MemoMark传右上角、StatusBadge传左上角彻底消灭了散落各处的魔法数字偏移magic-number insets详见陷阱节。2.3ShapeGroup基座所有形状原语的公共底座DataBox、LogicBox、TargetBullet、ProcessingComponent四个形状原语全部组合在一个共享基座ShapeGroup之上ShapeGroup.astro它集中处理了每个原语都会重复的公共关注点外层g transformtranslate(x y)与基础 class状态修饰类 高亮修饰类的组合dg-state-*、dg-highlightstateremoved时的原生titledeleted/title工具提示可选的StatusBadge左上与MemoMark右上徽标且当stateremoved时自动同时抑制——已删除的东西既没有缓存状态也没有可备忘的内容。从 ShapeGroup.astro 源码可见其 props 接口与实现逻辑type State idle | new | updated | changed | removed; type Status cache-ready | refreshing;当你需要新增一个形状原语时必须组合在ShapeGroup之上而不是从零重写外层g、状态类、title与徽标逻辑。参考 README.md 给出的标准写法--- import ShapeGroup from ./ShapeGroup.astro; // ... --- ShapeGroup x{x} y{y} w{w} baseClassdg-myshape state{state} highlight{highlight} memoized{memoized} status{status} rect classdg-box x0 y0 width{w} height{h} rx8 / foreignObject ...div classdg-fo-label{label}/div/foreignObject /ShapeGroup2.4 目录结构docs/src/components/diagrams/ ├── README.md # 本体系权威参考 ├── diagrams.css # 调色板变量、共享类、keyframes 动画 ├── primitives/ │ ├── DiagramFrame.astro # 外层 svg 包装viewBox、aria 标签 │ ├── ShapeGroup.astro # 形状原语共享基座 │ ├── DataBox.astro # 尖角矩形 —— 数据 │ ├── LogicBox.astro # 圆角矩形 —— 子系统 / 逻辑 │ ├── TargetBullet.astro # 子弹形 —— 目标状态 │ ├── ProcessingComponent.astro # 圆角容器插槽使用局部坐标 │ ├── AppContainer.astro # 桃色容器CocoIndex App │ ├── MemoMark.astro # memo 角标经 memoized prop │ ├── StatusBadge.astro # cache-ready / refreshing 角标经 status prop │ ├── FlowArrow.astro # 动画虚线箭头 │ └── Connector.astro # 静态绑定线无箭头 └── concepts/ ├── AppOverview.astro # Source → App → Target statecore_concepts 页 ├── AppExample.astro # PDF → markdown 总览共享 ├── AppDef.astro # App 绑定主函数与参数quickstart 页 ├── ComponentPerFile.astro # Drive → 逐文件 PCConvert → a.md→ Drive ├── FileProcess.astro # ComponentPerFile 的薄包装 highlight ├── ComponentsFanout.astro # ComponentPerFile 的薄包装 highlight ├── MountVsUseMount.astro └── ComponentWithChunks.astro # Drive → App(PC→Split→chunks→Embed→vectors) → VDB # 接受 memoized 与 scenario props三、标准创作流程六步走第 1 步先读参考材料动手前首先通读权威参考 README.md形状词汇、调色板变量、共享 CSS 类、动画约定、目录布局、MDX 嵌入模式再结合本 Skill 自带的三个会话级参考workflow.md —— 预览循环headless Chrome base-path 陷阱、如何裁剪与查看输出、重建纪律pitfalls.md —— 反复消耗迭代轮次的陷阱记录layout-patterns.md —— 布局惯用法水平箭头、对称内边距、紧凑性、绑定 vs 箭头。浏览即可不必背诵——设计时随时回查。第 2 步先设计布局再写代码任何非平凡图解都以.astro文件顶部的一段命名常量配置块开始用具体数字勾勒位置。偏好绝对坐标 按内容定尺寸的viewBox盒子尺寸与列偏移使用命名常量。核心纪律是容器尺寸由内容推导而不是反过来。从内部宽度、间距、内边距出发计算APP_W sum(cols) (n-1) * GAP 2 * APP_PAD_X下游兄弟元素Target System、右侧 Drive Folder 等引用APP.x APP_W绝不硬编码 x 坐标垂直方向同理——选取行中心点使得 top-pad bottom-pad。这样迭代时四个方向的留白始终保持平衡。完整惯用法见 layout-patterns.md 的 Balanced padding on all sides。标准配置块示例出自 layout-patterns.md--- const VB_W 980, VB_H 380; const TOP_Y 30, TOP_H 330; const DRIVE { x: 20, y: TOP_Y, w: 110, h: TOP_H }; const APP { x: 160, y: TOP_Y, w: 664, h: TOP_H }; const VDB { x: 844, y: TOP_Y, w: 110, h: TOP_H }; const PC_W 510, PC_H 128; const ROW1_CY 130, ROW2_CY 268; // ... ---改一个常量即可让整图重新流动无需在 JSX 里大海捞针。正确与错误的容器宽度推导对比layout-patterns.md错误做法——猜测容器宽度再往里塞内容const APP { x: 140, y: TOP_Y, w: 700, h: TOP_H }; // 猜的 const FILE_DX 24; const PC_DX FILE_DX FILE_W 34; const PC_W 360; // 右内边距700 - (PC_DX PC_W) 256远大于左侧 24正确做法——由内容反推容器宽度const APP_PAD_X 24; const FILE_W 62; const PC_W 360; const FILE_TO_PC_GAP 34; const APP_W FILE_W FILE_TO_PC_GAP PC_W APP_PAD_X * 2; // APP_W 484。左内边距 24 右内边距 24由构造保证。 const APP { x: 140, y: TOP_Y, w: APP_W, h: TOP_H }; const DRIVE_R { x: APP.x APP_W 20, y: TOP_Y, w: 100, h: TOP_H };对于水平内容行通用公式为[pad_x] col1 [gap] col2 [gap] … coln [pad_x] container_w sum(cols) (n-1) * gap 2 * pad_x由构造保证左右相等增删列也无需重新调参。垂直方向同理单行内容垂直居中content_y_top (container_h - content_h) / 2多行时选择ROW1_CY/ROW2_CY使首行顶部留白等于末行底部留白。注意容器自带约 28px 高的表头标签会占用顶部可用空间要么计入顶部内边距要么让内容行保持在它下方。第 3 步用形状语义原语组合严格按 2.1 节的语义表挑选原语。两个易混场景要分清绑定 vs 流转Drive Folder → 文件是绑定文件本就来自该目录用Connector文件 → Processing Component 是流转PC 处理该文件用FlowArrowSplit → chunk、chunk → Embed、Embed → vector 均为流转用FlowArrowvector → Vector Database 是绑定向量本就写入该库用Connector。两套坐标系外层布局Drive、App、Vector Database 之间的连线用绝对坐标ProcessingComponent/AppContainer的插槽内子元素以容器左上角为 (0,0) 使用局部坐标。任何视觉上要穿出容器的元素如 vector → Vector Database 的绑定线必须在容器标签之外用绝对坐标绘制。典型行循环出自 layout-patterns.md{rows.map((row) ( g {/* 绝对坐标外层布局 */} Connector d{M ${DRIVE.x DRIVE.w} ${row.rowCY} L ${FILE_X} ${row.rowCY}} / DataBox x{FILE_X} y{row.rowCY - FILE_H/2} ... / FlowArrow d{M ${FILE_X FILE_W} ${row.rowCY} L ${PC_X} ${row.rowCY}} / ProcessingComponent x{PC_X} y{row.pcY} w{PC_W} h{PC_H} memoized{true} {/* 局部坐标PC 内部(0,0) 容器左上角 */} LogicBox x{PC_PAD} y{(PC_H - SPLIT_H)/2} ... / {/* ... */} /ProcessingComponent {/* 绝对坐标从 PC 穿出到外部目标 */} {chunkCYs.map((cy) ( Connector d{M ${PC_X VECT_DX VECT_W} ${cy} L ${VDB.x} ${cy}} dashed{true} / ))} /g ))}为可读性源码中把外部空间与内部空间的代码块在视觉上分区。行中心ROW_CY先行定义再由此推导文件 y、chunk y、embed y 等子元素位置——上下平移整行只需改一个常量。第 4 步用 foreignObject 渲染标签所有带标签的原语DataBox、LogicBox、ProcessingComponent、TargetBullet都使用foreignObject内嵌 flex 居中的div classdg-fo-label让浏览器自动按盒子宽度换行。调用方只需传label...绝不要手动预拆分换行。CSS 侧diagrams.css 的.dg-fo-label通过display: flexalign-items: centerjustify-content: center实现垂直水平双向居中overflow-wrap: break-wordwhite-space: pre-line支持自动换行与\n显式换行。标签溢出时正确做法是加宽盒子或缩短文案而不是手工切行。第 5 步预览验证看到再交付构建通过了绝不是图解完成的证据。图解是视觉产物代码层面永远看不到标签重叠、整行变暗、箭头样式错误这类小问题。必须运行预览脚本渲染成 PNG 亲眼确认可用Read工具读回截图自查。scripts/preview.sh docs-slug # 示例scripts/preview.sh programming_guide/core_concepts该脚本preview.sh依次完成在docs/内执行npm run build构建 Astro 站点将docs/dist/rsync 镜像到临时目录下的docs/子目录base path 关键步骤见下文陷阱杀掉 8765 端口上的残留服务在下一个空闲端口重新启动python3 -m http.server用无头 Chrome--headlessnew以1400x5200、scale 1 截取整页保存整页 PNG 可选的裁剪图打印输出路径。脚本还支持可选的裁剪参数定位图中目标区域scripts/preview.sh programming_guide/core_concepts 3300 600整页截图通常很高需要裁剪定位具体图解workflow.mdmagick /tmp/dg-preview/full.png -crop 1400x50003300 /tmp/dg-preview/crop.png目标不在裁剪区内就调整 y 偏移如2500、3500、4000需要细查布局时紧贴裁剪并裁掉周边正文。预览产物统一写入/tmp/dg-preview/下次运行自动清理端口卡死时可用lsof -ti:8765 | xargs kill -9释放。第 6 步依据视觉反馈迭代任何非平凡图解都预期需要 2–4 轮预览循环——首轮渲染几乎必然暴露代码检查看不到的问题标签与图标重叠、透明度异常、颜色漂移、箭头指向错误。预算好迭代轮次不要试图一次成型。只有不影响布局的纯文本/标签修正如改错别字可以跳过预览凡是涉及坐标、形状选择或新原语的改动都必须预览。四、动画纪律与无障碍所有图解默认静止idle by default动效一律藏在.dg-root:hover之后与首页模式一致让静态页面保持安静diagrams.css动画触发机制dg-flow虚线箭头漂移root hoverstroke-dashoffset从 18 → 0 循环dg-pulse脉冲圆点root hover缩放 1 → 1.6、透明度 1 → 0.55dg-state-{new,updated,removed}边框脉冲root hover共享dg-delta-pulse线宽 2.2 ↔ 4.2dg-status-badge--ok对勾书写root hoverdg-check-draw~0.6s 从左到右书写、保持 ~1.2s、复位循环dg-status-badge--refresh箭头旋转root hoverdg-spin1.6s 线性无限旋转新增keyframes规则时必须同时在diagrams.css底部的media (prefers-reduced-motion: reduce)块中登记为animation: none !important且.dg-step在此媒体查询下强制opacity: 1。所有动画不应引入运行时 JS——图解默认零 JS只有确实需要 hover 之外交互scrubber、点击分步的极少数情况才允许将该图单独做成 React island并复用相同的 SVG 原语绝不为一帧 hover 动画加载整棵 React 树。无障碍方面DiagramFrame接受title与descprops渲染为svg的子title/desc并通过aria-labelledby/aria-describedby关联roleimg已内置。stateremoved时原生titledeleted/title提供 hover 工具提示。五、调色板与共享 CSS 类调色板取自docs/src/styles/globals.css与品牌规范一致图解内禁止硬编码 hex 值一律使用 CSS 变量CSS 变量Hex用途--coral#BE5133流转箭头、桃色容器、refreshing徽标--peach#E59A63App / Processing Component 填充着色--palm#27E62Bnew状态、cache-ready徽标、highlight--pink#FB6A76removed/changed状态、指纹失效--maroon#532638主描边、MemoMark填充--maroon-ink#2A121B正文墨色--cream#FCF3D8默认填充、徽标内标记--dg-gold#D4A835updated状态图解局部变量定义在.dg-root上避免泄漏--paper#FBF6E8图解背景常用共享 CSS 类速查完整定义见 diagrams.cssdg-root—— 最外层svg包装:hover规则的容器dg-box—— 基础描边矩形/路径奶油 酒红线宽 1.4dg-box--component/dg-box--app—— 桃色着色的组件 / App 容器coral 描边dg-box--muted—— 淡虚线外框示意容器dg-label/dg-fo-label—— SVG 文本 / foreignObject HTML 标签dg-state-{new,updated,removed,changed}—— 增量状态直接子代作用域dg-status-badge--ok/--refresh—— 状态徽标变体dg-highlight—— 粗掌绿描边当前讨论元素dg-flow/dg-connector—— 流转箭头 / 静态绑定线dg-pulse—— 脉冲圆点dg-step-NN1–6—— 渐进揭示的错峰延迟0s 起每级 0.15s。六、Delta 状态与缓存徽标的深层语义6.1 Delta 状态state propstate表达本次运行中该元素发生了什么由ShapeGroup以 wrapperg上的类应用。所有增量状态共享同一套运动词汇——.dg-root:hover上的边框脉冲state填充 / 描边标签处理hover 工具提示用途idle默认奶油 酒红正常—未变化new掌绿色正常—本次运行新增updated金色正常—本次运行原地变更removed粉色删除线 弱化deleted本次运行删除changed细粉描边无填充脉冲正常—指纹传播信号仅用于指纹传播类图解关键工程约束状态规则必须使用直接子代组合器 .dg-box绝不能写成后代选择器。如果容器如pcStateupdated的 ProcessingComponent上的状态类向下级联内部的每一个嵌套.dg-boxchunks、embeds、vectors都会被染成金色。每个形状原语在自己的 wrapperg上各自持有状态互不污染。同时为了在着色的父容器背景下依然可读所有 delta 状态的stroke-width提升到 2.2hover 时dg-delta-pulse进一步推到 4.2。6.2 缓存状态徽标status propstatus作用于LogicBox/ProcessingComponent标注某元素在本次运行中的 memo 化行为cache-ready—— 掌绿圆盘 奶油色对勾hover 时对勾从左到右手写绘制stroke-dasharray 书写动画约 0.6s保持约 1.2s 后复位进入下一循环语义是已验证新鲜refreshing—— 珊瑚色圆盘 奶油色环形箭头hover 时箭头持续旋转1.6s 线性无限语义是缓存未命中正在重新执行。两者在stateremoved时同时抑制已删除的东西没有活动缓存状态。徽标位于左上角同时被顶边与左边平分与右上角的MemoMark互为镜像。state与status可正交组合memo 化函数正在重跑 →statusrefreshing命中缓存 →statuscache-ready。6.3 scenario 模式多状态图解的内容是数据ComponentWithChunksComponentWithChunks.astro接受scenario?: Scenarioprop 描述逐行 / 逐 chunk 的覆盖。不要为每个如果…会怎样的场景创建一个.astro包装器——场景是内容哪个文件变了哪个 embed 命中了缓存不是可复用组件。场景直接内联在.mdx中、紧跟描述它的正文旁让我在展示什么与我在说什么保持在一起避免未来编辑漂移ComponentWithChunks memoized{true} scenario{{ rows: [ { file: a.md, pcStatus: cache-ready, chunks: [ { label: chunk1, vectorLabel: vector1, embedStatus: cache-ready }, { label: chunk2, vectorLabel: vector2, embedStatus: cache-ready }, ] }, { file: b.md, fileState: updated, pcStatus: refreshing, pcState: updated, chunks: [ { label: chunk3, vectorLabel: vector3, embedStatus: cache-ready }, { label: chunk4, vectorLabel: vector4, state: removed }, { label: chunk5, vectorLabel: vector5, state: new }, ] }, ]}} /ComponentWithChunks的类型化场景 schema 定义了RowEntryfile、fileState、pcStatus、pcState、splitState、chunks与ChunkEntrylabel、vectorLabel、state、embedStatus且实现了pcStateremoved时 chunk 状态级联为removed的继承逻辑见其effectiveChunks计算保证删除语义一致。无scenario时默认渲染两文件基线a.md → chunk1/chunk2 → vector1/vector2、b.md → chunk3/chunk4 → vector3/vector4全部idle。七、在 .mdx 页面中嵌入图解.mdx页面中从站点根目录使用绝对导入路径保证任意文档深度下均可解析--- title: Core Concepts --- import ComponentWithChunks from /src/components/diagrams/concepts/ComponentWithChunks.astro; ## Processing Component ComponentWithChunks /Astro 原生支持.mdx中的组件导入经astrojs/mdx见 astro.config.mjs。绝对路径以/src/...为根跨深度稳定。八、高频陷阱实录来自真实迭代教训dev/agent-skills/cocoindex-diagrams/references/pitfalls.md记录了构建当前图解集时反复消耗迭代轮次的陷阱。以下是完整清单与修复要点1. 所有盒子渲染为纯黑症状截图里图解全是黑色矩形文字隐约可见但所有填充都是黑色。 原因文档站配置了base: /docsastro.config.mjs构建后的 HTML 引用/docs/_astro/*.css下的 CSS若在dist/直接起python3 -m http.serverCSS 会以/_astro/...路径返回 404。样式表缺失时var(--cream)、var(--coral)等全部未定义SVGfill回退为黑色。 修复从包含docs/子目录符号链接或dist/副本的父目录提供服务使/docs/_astro/...可解析。scripts/preview.sh已自动处理rsync 到docs/子目录。这是服务端问题不是图解代码问题。2. 行 / 内容以 35% 透明度变暗原因dg-stepdg-step-N类专为渐进揭示叙事设计如三面板步骤 1 → 2 → 3默认透明度 0.35、仅 hover 时点亮。误用在本应静态全显的并行行上就会整体变暗。 修复从包裹行的g上移除dg-step仅当有意做 hover 驱动揭示时才使用。3. 标签溢出 / 窄盒内被裁剪原因早期版本用 SVGtext不换行手工切行lines{[Split into, chunks]}笨拙。 修复所有带标签原语改用foreignObject flex 居中div classdg-fo-label浏览器按盒宽自动换行只需传label...。4. 魔法数字偏移散落各处原因MemoMark x{PC_X 14} y{row.pcY 4} size{12} /这类调用点内联不同偏移与尺寸与容器尺寸隐形耦合。 修复原语自持内嵌偏移与尺寸调用方只传容器参考角MemoMark传右上角原语内部做translate(x - INSET_X - w, y)。ProcessingComponent的表头与 memo 标记同理由容器原语自行定位。5. 源 / 目标颜色意外分化原因早期LogicBox有variantsource/varianttarget不同填充源自不适用于文档图解的首页旧约定。 修复所有非容器逻辑框统一中性奶油 酒红语义区分由形状承担TargetBullet的子弹形本身就与LogicBox不同只有 App 容器保留桃色调。6. 不同高度的箭头打错目标原因所有箭头都指向目标盒的唯一 y 中心导致多条箭头交叉。 修复保持箭头水平——每条箭头在源元素的 y 坐标处射向目标左边缘。前提是目标足够高能容纳多条水平入口。7. 绑定线上出现箭头原因到处用FlowArrow使绑定显得像因果流转。 修复绑定用Connector静态虚线无箭头FlowArrow只用于因果流转。8. MemoMark 实心黑、视觉过重修复用珊瑚色描边 半透明珊瑚填充fill: color-mix(in oklab, var(--coral) 22%, transparent)在任意背景下可读且贴合品牌配色。9. 容器内不对称内边距原因把APP.w/APP.h硬编码成整数再往里塞内容剩余空间全落在右 / 下侧。 修复按第 2 步公式由内容推导容器尺寸下游兄弟引用APP.x APP_W。10. 容器状态类级联污染子元素原因状态 CSS 写成后代选择器.dg-state-updated .dg-box。 修复改用直接子代组合器.dg-state-updated .dg-box。每个基于ShapeGroup的原语有自己的 wrapperg、自己的状态类、自己的直接子代.dg-box。11. 有状态容器内的新状态视觉不突出原因默认线宽 1.4 的彩色状态描边在着色父背景下太细。 修复dg-state-*规则统一把stroke-width提到 2.2hover 的dg-delta-pulse推到 4.2。12. 常驻动画干扰静态页面原因旋转图标refresh 徽标在无人观看时也一直转。 修复diagrams.css中每个动画默认静止、仅.dg-root:hover激活dg-flow、dg-pulse、dg-delta-pulse、dg-spin、dg-check-draw全部如此新动画一律同规则门控并在prefers-reduced-motion覆盖块登记。13. 不看就报告完成症状构建成功了图解完成随后用户截图暴露重叠 / 黑盒 / 变暗内容。 修复报告前必跑scripts/preview.sh并ReadPNG。干净的npm run build只证明 Astro 组件能编译不证明渲染正确。九、创作纪律清单形状承载含义按语义选原语而非看起来合适禁止手动切行标签溢出就加宽盒子或缩短文案外层绝对坐标、插槽局部坐标ProcessingComponent的插槽以 (0,0) 容器左上角渲染子元素流转箭头统一用色默认珊瑚色variantpalm/muted仅在语义需要时使用绑定保持安静Connector静态、虚线、无箭头表示X 绑定于 Y四边内边距全平衡容器内左 右、上 下宽度高度由内容推导下游兄弟引用推导出的宽度优先紧凑图解应在文档列宽约 720px下可读仅在视觉叙事需要时才拉伸maxWidth多在 720–960 之间行距小到同族感而非割裂感dg-step只用于静态内容之外默认 35% 透明度仅 hover 点亮专用于渐进揭示叙事所有动画默认静止flow-drift、delta-pulse、check-draw、refresh-spin 一律.dg-root:hover门控新增keyframes必须在diagrams.css底部prefers-reduced-motion块登记状态规则用直接子代组合器.dg-state-X .dg-box禁止级联新形状原语组合在ShapeGroup上wrapperg、状态/高亮类、titledeleted/title工具提示、MemoMark/StatusBadge徽标含 removed 抑制全部由它接管绝不重实现多状态图解用scenarioprop场景内联在 MDX 正文旁不创建每场景一个.astro包装器单图内联标记尽量精简每个图解的内联 SVG 标记控制在约 30 行以内超长就把重复分组提炼成原语依据 README.md。十、启动模板dev/agent-skills/cocoindex-diagrams/assets/starter.astro提供了一个最小的形状语义图解骨架config-first 布局、带局部坐标插槽的ProcessingComponent、水平箭头、绑定连接线各一复制到docs/src/components/diagrams/concepts/MyDiagram.astro后按需调整即可无需从零起笔。模板中DiagramFrame的title/descprops 应填写面向辅助技术的有意义描述viewBox与maxWidth依据内容推导。至此从形状语义原语、状态/缓存标注体系、布局惯用法、动画纪律到预览验证闭环与陷阱防御CocoIndex 文档图解的完整开发方法论已经贯通。遵循本指南新图解通常可在 2–4 轮预览内达到与既有图解一致的视觉质量与语义精度。【免费下载链接】cocoindexIncremental engine for long horizon agents Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/co/cocoindex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CocoIndex 文档站内联 SVG 图解开发指南：基于 Astro 组件的形状语义化图表体系
CocoIndex 文档站内联 SVG 图解开发指南基于 Astro 组件的形状语义化图表体系【免费下载链接】cocoindexIncremental engine for long horizon agents Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/co/cocoindex本指南以dev/agent-skills/cocoindex-diagrams/SKILL.md及其配套参考文档为骨架系统讲解 CocoIndex 文档站docs/内联 SVG 图解体系的完整开发方法论从形状语义化的组件原语、调色板与共享样式到先布局、后组合、再预览验证的标准工作流以及多年迭代沉淀下来的常见陷阱。读完你将掌握在.mdx文档页中创建、编辑与评审高一致性技术图解的完整实战技能并能直接复用到仓库中任意docs/src/content/docs/**文档页。一、为什么文档图解要组件化而不是静态 SVGCocoIndex 文档站的全部图解任何位于docs/src/content/docs/**下的页面内嵌图都以 Astro 组件形式编写统一放在docs/src/components/diagrams/目录下。这个目录是文档图解的唯一事实来源single source of truth——早期由设计工具Excalidraw、Figma、Sketch 等导出的静态.svg文件位于/public/img/**/*.svg已被视为遗留资产会随着组件化替换逐渐删除不再继续编辑。静态 SVG 的三个致命问题正是组件化方案的动机依据docs/src/components/diagrams/README.md编辑需要往返设计工具SVG 是不透明的产物改一处布局就要重新走一遍工具链无共享样式每个图各自为政颜色、线宽、字体漂移难以评审二进制式的大段坐标数据让 git diff 失去可读性。组件化图解则免费获得四重收益收益说明单一调色板CSS 变量改一处变量全局生效CSS:hover驱动的动画零 JS、SSR 友好静态页面保持安静组件边界处类型化 props标签、状态、高亮等以强类型接口暴露可读的 diffgit 评审流畅符合 README.md 中模型来自cocoindex.github.io首页内联 SVG的实践docs/astro.config.mjs中通过astrojs/mdx集成让 Astro 组件可以在.mdx中原生导入使用这是整个体系能够落地的工程基础。二、形状语义以含义而非外观选择原语图解体系的核心原则是shape carries meaning——形状本身传达语义选原语要依据元素是什么而不是看起来顺眼。全部内联 SVG 由一组形状语义原语primitives组合而成它们共享同一套调色板与样式docs/src/components/diagrams/diagrams.css。2.1 基础形状原语形状语义含义原语组件尖角矩形数据文件、chunk、行DataBox圆角矩形子系统 / 逻辑Split、Embed、Drive Folder、Vector Database 等LogicBox支持memoizedstatusprops 与插槽奶油色带表头容器一个 Processing Component承载其他元素ProcessingComponent插槽使用局部坐标系支持memoizedstatus桃色带表头容器一个 CocoIndex App承载其他元素AppContainer插槽使用局部坐标系子弹形左侧平直、右侧圆角目标状态vector、输出文件、数据库行TargetBullet动画虚线带箭头流转 / 因果A 产生 B、A 变换为 BFlowArrow静态虚线无箭头绑定 / 身份X 绑定于 YConnector这里有一个反直觉但重要的设计决策所有非容器逻辑框源、目标、数据、子弹形共用同一种中性奶油色 酒红色填充与描边语义区分完全由形状承担而不是颜色。只有 App 容器保留桃色调用于视觉分组dg-box--app见 diagrams.css 中.dg-box与.dg-box--component的注释。2.2 正交标注状态、缓存徽标与高亮在原语之上有一套与形状正交orthogonal可叠加在任意形状上的标注体系用于表达这次运行中发生了什么Prop取值视觉表现statenew、updated、removed、changed、idle默认掌绿色 / 金色 / 粉色 / 细粉色填充removed的标签带删除线并弱化hover 时显示原生deleted工具提示状态级联通过直接子代 CSS 组合器阻止详见陷阱节statuscache-ready、refreshing左上角徽标缓存命中显示对勾书写动画hover 触发缓存未命中显示旋转箭头hover 触发两者在stateremoved时自动抑制highlighttrue粗掌绿色描边表示当前文字正在讨论的元素memoizedtrue作用于LogicBox/ProcessingComponent右上角酒红色备忘缎带表示该函数/组件被 memo 化memoized缎带、cache-ready徽标、refreshing徽标三个角标的精确位置与尺寸由原语自身内部计算——调用方只需传递容器参考角MemoMark传右上角、StatusBadge传左上角彻底消灭了散落各处的魔法数字偏移magic-number insets详见陷阱节。2.3ShapeGroup基座所有形状原语的公共底座DataBox、LogicBox、TargetBullet、ProcessingComponent四个形状原语全部组合在一个共享基座ShapeGroup之上ShapeGroup.astro它集中处理了每个原语都会重复的公共关注点外层g transformtranslate(x y)与基础 class状态修饰类 高亮修饰类的组合dg-state-*、dg-highlightstateremoved时的原生titledeleted/title工具提示可选的StatusBadge左上与MemoMark右上徽标且当stateremoved时自动同时抑制——已删除的东西既没有缓存状态也没有可备忘的内容。从 ShapeGroup.astro 源码可见其 props 接口与实现逻辑type State idle | new | updated | changed | removed; type Status cache-ready | refreshing;当你需要新增一个形状原语时必须组合在ShapeGroup之上而不是从零重写外层g、状态类、title与徽标逻辑。参考 README.md 给出的标准写法--- import ShapeGroup from ./ShapeGroup.astro; // ... --- ShapeGroup x{x} y{y} w{w} baseClassdg-myshape state{state} highlight{highlight} memoized{memoized} status{status} rect classdg-box x0 y0 width{w} height{h} rx8 / foreignObject ...div classdg-fo-label{label}/div/foreignObject /ShapeGroup2.4 目录结构docs/src/components/diagrams/ ├── README.md # 本体系权威参考 ├── diagrams.css # 调色板变量、共享类、keyframes 动画 ├── primitives/ │ ├── DiagramFrame.astro # 外层 svg 包装viewBox、aria 标签 │ ├── ShapeGroup.astro # 形状原语共享基座 │ ├── DataBox.astro # 尖角矩形 —— 数据 │ ├── LogicBox.astro # 圆角矩形 —— 子系统 / 逻辑 │ ├── TargetBullet.astro # 子弹形 —— 目标状态 │ ├── ProcessingComponent.astro # 圆角容器插槽使用局部坐标 │ ├── AppContainer.astro # 桃色容器CocoIndex App │ ├── MemoMark.astro # memo 角标经 memoized prop │ ├── StatusBadge.astro # cache-ready / refreshing 角标经 status prop │ ├── FlowArrow.astro # 动画虚线箭头 │ └── Connector.astro # 静态绑定线无箭头 └── concepts/ ├── AppOverview.astro # Source → App → Target statecore_concepts 页 ├── AppExample.astro # PDF → markdown 总览共享 ├── AppDef.astro # App 绑定主函数与参数quickstart 页 ├── ComponentPerFile.astro # Drive → 逐文件 PCConvert → a.md→ Drive ├── FileProcess.astro # ComponentPerFile 的薄包装 highlight ├── ComponentsFanout.astro # ComponentPerFile 的薄包装 highlight ├── MountVsUseMount.astro └── ComponentWithChunks.astro # Drive → App(PC→Split→chunks→Embed→vectors) → VDB # 接受 memoized 与 scenario props三、标准创作流程六步走第 1 步先读参考材料动手前首先通读权威参考 README.md形状词汇、调色板变量、共享 CSS 类、动画约定、目录布局、MDX 嵌入模式再结合本 Skill 自带的三个会话级参考workflow.md —— 预览循环headless Chrome base-path 陷阱、如何裁剪与查看输出、重建纪律pitfalls.md —— 反复消耗迭代轮次的陷阱记录layout-patterns.md —— 布局惯用法水平箭头、对称内边距、紧凑性、绑定 vs 箭头。浏览即可不必背诵——设计时随时回查。第 2 步先设计布局再写代码任何非平凡图解都以.astro文件顶部的一段命名常量配置块开始用具体数字勾勒位置。偏好绝对坐标 按内容定尺寸的viewBox盒子尺寸与列偏移使用命名常量。核心纪律是容器尺寸由内容推导而不是反过来。从内部宽度、间距、内边距出发计算APP_W sum(cols) (n-1) * GAP 2 * APP_PAD_X下游兄弟元素Target System、右侧 Drive Folder 等引用APP.x APP_W绝不硬编码 x 坐标垂直方向同理——选取行中心点使得 top-pad bottom-pad。这样迭代时四个方向的留白始终保持平衡。完整惯用法见 layout-patterns.md 的 Balanced padding on all sides。标准配置块示例出自 layout-patterns.md--- const VB_W 980, VB_H 380; const TOP_Y 30, TOP_H 330; const DRIVE { x: 20, y: TOP_Y, w: 110, h: TOP_H }; const APP { x: 160, y: TOP_Y, w: 664, h: TOP_H }; const VDB { x: 844, y: TOP_Y, w: 110, h: TOP_H }; const PC_W 510, PC_H 128; const ROW1_CY 130, ROW2_CY 268; // ... ---改一个常量即可让整图重新流动无需在 JSX 里大海捞针。正确与错误的容器宽度推导对比layout-patterns.md错误做法——猜测容器宽度再往里塞内容const APP { x: 140, y: TOP_Y, w: 700, h: TOP_H }; // 猜的 const FILE_DX 24; const PC_DX FILE_DX FILE_W 34; const PC_W 360; // 右内边距700 - (PC_DX PC_W) 256远大于左侧 24正确做法——由内容反推容器宽度const APP_PAD_X 24; const FILE_W 62; const PC_W 360; const FILE_TO_PC_GAP 34; const APP_W FILE_W FILE_TO_PC_GAP PC_W APP_PAD_X * 2; // APP_W 484。左内边距 24 右内边距 24由构造保证。 const APP { x: 140, y: TOP_Y, w: APP_W, h: TOP_H }; const DRIVE_R { x: APP.x APP_W 20, y: TOP_Y, w: 100, h: TOP_H };对于水平内容行通用公式为[pad_x] col1 [gap] col2 [gap] … coln [pad_x] container_w sum(cols) (n-1) * gap 2 * pad_x由构造保证左右相等增删列也无需重新调参。垂直方向同理单行内容垂直居中content_y_top (container_h - content_h) / 2多行时选择ROW1_CY/ROW2_CY使首行顶部留白等于末行底部留白。注意容器自带约 28px 高的表头标签会占用顶部可用空间要么计入顶部内边距要么让内容行保持在它下方。第 3 步用形状语义原语组合严格按 2.1 节的语义表挑选原语。两个易混场景要分清绑定 vs 流转Drive Folder → 文件是绑定文件本就来自该目录用Connector文件 → Processing Component 是流转PC 处理该文件用FlowArrowSplit → chunk、chunk → Embed、Embed → vector 均为流转用FlowArrowvector → Vector Database 是绑定向量本就写入该库用Connector。两套坐标系外层布局Drive、App、Vector Database 之间的连线用绝对坐标ProcessingComponent/AppContainer的插槽内子元素以容器左上角为 (0,0) 使用局部坐标。任何视觉上要穿出容器的元素如 vector → Vector Database 的绑定线必须在容器标签之外用绝对坐标绘制。典型行循环出自 layout-patterns.md{rows.map((row) ( g {/* 绝对坐标外层布局 */} Connector d{M ${DRIVE.x DRIVE.w} ${row.rowCY} L ${FILE_X} ${row.rowCY}} / DataBox x{FILE_X} y{row.rowCY - FILE_H/2} ... / FlowArrow d{M ${FILE_X FILE_W} ${row.rowCY} L ${PC_X} ${row.rowCY}} / ProcessingComponent x{PC_X} y{row.pcY} w{PC_W} h{PC_H} memoized{true} {/* 局部坐标PC 内部(0,0) 容器左上角 */} LogicBox x{PC_PAD} y{(PC_H - SPLIT_H)/2} ... / {/* ... */} /ProcessingComponent {/* 绝对坐标从 PC 穿出到外部目标 */} {chunkCYs.map((cy) ( Connector d{M ${PC_X VECT_DX VECT_W} ${cy} L ${VDB.x} ${cy}} dashed{true} / ))} /g ))}为可读性源码中把外部空间与内部空间的代码块在视觉上分区。行中心ROW_CY先行定义再由此推导文件 y、chunk y、embed y 等子元素位置——上下平移整行只需改一个常量。第 4 步用 foreignObject 渲染标签所有带标签的原语DataBox、LogicBox、ProcessingComponent、TargetBullet都使用foreignObject内嵌 flex 居中的div classdg-fo-label让浏览器自动按盒子宽度换行。调用方只需传label...绝不要手动预拆分换行。CSS 侧diagrams.css 的.dg-fo-label通过display: flexalign-items: centerjustify-content: center实现垂直水平双向居中overflow-wrap: break-wordwhite-space: pre-line支持自动换行与\n显式换行。标签溢出时正确做法是加宽盒子或缩短文案而不是手工切行。第 5 步预览验证看到再交付构建通过了绝不是图解完成的证据。图解是视觉产物代码层面永远看不到标签重叠、整行变暗、箭头样式错误这类小问题。必须运行预览脚本渲染成 PNG 亲眼确认可用Read工具读回截图自查。scripts/preview.sh docs-slug # 示例scripts/preview.sh programming_guide/core_concepts该脚本preview.sh依次完成在docs/内执行npm run build构建 Astro 站点将docs/dist/rsync 镜像到临时目录下的docs/子目录base path 关键步骤见下文陷阱杀掉 8765 端口上的残留服务在下一个空闲端口重新启动python3 -m http.server用无头 Chrome--headlessnew以1400x5200、scale 1 截取整页保存整页 PNG 可选的裁剪图打印输出路径。脚本还支持可选的裁剪参数定位图中目标区域scripts/preview.sh programming_guide/core_concepts 3300 600整页截图通常很高需要裁剪定位具体图解workflow.mdmagick /tmp/dg-preview/full.png -crop 1400x50003300 /tmp/dg-preview/crop.png目标不在裁剪区内就调整 y 偏移如2500、3500、4000需要细查布局时紧贴裁剪并裁掉周边正文。预览产物统一写入/tmp/dg-preview/下次运行自动清理端口卡死时可用lsof -ti:8765 | xargs kill -9释放。第 6 步依据视觉反馈迭代任何非平凡图解都预期需要 2–4 轮预览循环——首轮渲染几乎必然暴露代码检查看不到的问题标签与图标重叠、透明度异常、颜色漂移、箭头指向错误。预算好迭代轮次不要试图一次成型。只有不影响布局的纯文本/标签修正如改错别字可以跳过预览凡是涉及坐标、形状选择或新原语的改动都必须预览。四、动画纪律与无障碍所有图解默认静止idle by default动效一律藏在.dg-root:hover之后与首页模式一致让静态页面保持安静diagrams.css动画触发机制dg-flow虚线箭头漂移root hoverstroke-dashoffset从 18 → 0 循环dg-pulse脉冲圆点root hover缩放 1 → 1.6、透明度 1 → 0.55dg-state-{new,updated,removed}边框脉冲root hover共享dg-delta-pulse线宽 2.2 ↔ 4.2dg-status-badge--ok对勾书写root hoverdg-check-draw~0.6s 从左到右书写、保持 ~1.2s、复位循环dg-status-badge--refresh箭头旋转root hoverdg-spin1.6s 线性无限旋转新增keyframes规则时必须同时在diagrams.css底部的media (prefers-reduced-motion: reduce)块中登记为animation: none !important且.dg-step在此媒体查询下强制opacity: 1。所有动画不应引入运行时 JS——图解默认零 JS只有确实需要 hover 之外交互scrubber、点击分步的极少数情况才允许将该图单独做成 React island并复用相同的 SVG 原语绝不为一帧 hover 动画加载整棵 React 树。无障碍方面DiagramFrame接受title与descprops渲染为svg的子title/desc并通过aria-labelledby/aria-describedby关联roleimg已内置。stateremoved时原生titledeleted/title提供 hover 工具提示。五、调色板与共享 CSS 类调色板取自docs/src/styles/globals.css与品牌规范一致图解内禁止硬编码 hex 值一律使用 CSS 变量CSS 变量Hex用途--coral#BE5133流转箭头、桃色容器、refreshing徽标--peach#E59A63App / Processing Component 填充着色--palm#27E62Bnew状态、cache-ready徽标、highlight--pink#FB6A76removed/changed状态、指纹失效--maroon#532638主描边、MemoMark填充--maroon-ink#2A121B正文墨色--cream#FCF3D8默认填充、徽标内标记--dg-gold#D4A835updated状态图解局部变量定义在.dg-root上避免泄漏--paper#FBF6E8图解背景常用共享 CSS 类速查完整定义见 diagrams.cssdg-root—— 最外层svg包装:hover规则的容器dg-box—— 基础描边矩形/路径奶油 酒红线宽 1.4dg-box--component/dg-box--app—— 桃色着色的组件 / App 容器coral 描边dg-box--muted—— 淡虚线外框示意容器dg-label/dg-fo-label—— SVG 文本 / foreignObject HTML 标签dg-state-{new,updated,removed,changed}—— 增量状态直接子代作用域dg-status-badge--ok/--refresh—— 状态徽标变体dg-highlight—— 粗掌绿描边当前讨论元素dg-flow/dg-connector—— 流转箭头 / 静态绑定线dg-pulse—— 脉冲圆点dg-step-NN1–6—— 渐进揭示的错峰延迟0s 起每级 0.15s。六、Delta 状态与缓存徽标的深层语义6.1 Delta 状态state propstate表达本次运行中该元素发生了什么由ShapeGroup以 wrapperg上的类应用。所有增量状态共享同一套运动词汇——.dg-root:hover上的边框脉冲state填充 / 描边标签处理hover 工具提示用途idle默认奶油 酒红正常—未变化new掌绿色正常—本次运行新增updated金色正常—本次运行原地变更removed粉色删除线 弱化deleted本次运行删除changed细粉描边无填充脉冲正常—指纹传播信号仅用于指纹传播类图解关键工程约束状态规则必须使用直接子代组合器 .dg-box绝不能写成后代选择器。如果容器如pcStateupdated的 ProcessingComponent上的状态类向下级联内部的每一个嵌套.dg-boxchunks、embeds、vectors都会被染成金色。每个形状原语在自己的 wrapperg上各自持有状态互不污染。同时为了在着色的父容器背景下依然可读所有 delta 状态的stroke-width提升到 2.2hover 时dg-delta-pulse进一步推到 4.2。6.2 缓存状态徽标status propstatus作用于LogicBox/ProcessingComponent标注某元素在本次运行中的 memo 化行为cache-ready—— 掌绿圆盘 奶油色对勾hover 时对勾从左到右手写绘制stroke-dasharray 书写动画约 0.6s保持约 1.2s 后复位进入下一循环语义是已验证新鲜refreshing—— 珊瑚色圆盘 奶油色环形箭头hover 时箭头持续旋转1.6s 线性无限语义是缓存未命中正在重新执行。两者在stateremoved时同时抑制已删除的东西没有活动缓存状态。徽标位于左上角同时被顶边与左边平分与右上角的MemoMark互为镜像。state与status可正交组合memo 化函数正在重跑 →statusrefreshing命中缓存 →statuscache-ready。6.3 scenario 模式多状态图解的内容是数据ComponentWithChunksComponentWithChunks.astro接受scenario?: Scenarioprop 描述逐行 / 逐 chunk 的覆盖。不要为每个如果…会怎样的场景创建一个.astro包装器——场景是内容哪个文件变了哪个 embed 命中了缓存不是可复用组件。场景直接内联在.mdx中、紧跟描述它的正文旁让我在展示什么与我在说什么保持在一起避免未来编辑漂移ComponentWithChunks memoized{true} scenario{{ rows: [ { file: a.md, pcStatus: cache-ready, chunks: [ { label: chunk1, vectorLabel: vector1, embedStatus: cache-ready }, { label: chunk2, vectorLabel: vector2, embedStatus: cache-ready }, ] }, { file: b.md, fileState: updated, pcStatus: refreshing, pcState: updated, chunks: [ { label: chunk3, vectorLabel: vector3, embedStatus: cache-ready }, { label: chunk4, vectorLabel: vector4, state: removed }, { label: chunk5, vectorLabel: vector5, state: new }, ] }, ]}} /ComponentWithChunks的类型化场景 schema 定义了RowEntryfile、fileState、pcStatus、pcState、splitState、chunks与ChunkEntrylabel、vectorLabel、state、embedStatus且实现了pcStateremoved时 chunk 状态级联为removed的继承逻辑见其effectiveChunks计算保证删除语义一致。无scenario时默认渲染两文件基线a.md → chunk1/chunk2 → vector1/vector2、b.md → chunk3/chunk4 → vector3/vector4全部idle。七、在 .mdx 页面中嵌入图解.mdx页面中从站点根目录使用绝对导入路径保证任意文档深度下均可解析--- title: Core Concepts --- import ComponentWithChunks from /src/components/diagrams/concepts/ComponentWithChunks.astro; ## Processing Component ComponentWithChunks /Astro 原生支持.mdx中的组件导入经astrojs/mdx见 astro.config.mjs。绝对路径以/src/...为根跨深度稳定。八、高频陷阱实录来自真实迭代教训dev/agent-skills/cocoindex-diagrams/references/pitfalls.md记录了构建当前图解集时反复消耗迭代轮次的陷阱。以下是完整清单与修复要点1. 所有盒子渲染为纯黑症状截图里图解全是黑色矩形文字隐约可见但所有填充都是黑色。 原因文档站配置了base: /docsastro.config.mjs构建后的 HTML 引用/docs/_astro/*.css下的 CSS若在dist/直接起python3 -m http.serverCSS 会以/_astro/...路径返回 404。样式表缺失时var(--cream)、var(--coral)等全部未定义SVGfill回退为黑色。 修复从包含docs/子目录符号链接或dist/副本的父目录提供服务使/docs/_astro/...可解析。scripts/preview.sh已自动处理rsync 到docs/子目录。这是服务端问题不是图解代码问题。2. 行 / 内容以 35% 透明度变暗原因dg-stepdg-step-N类专为渐进揭示叙事设计如三面板步骤 1 → 2 → 3默认透明度 0.35、仅 hover 时点亮。误用在本应静态全显的并行行上就会整体变暗。 修复从包裹行的g上移除dg-step仅当有意做 hover 驱动揭示时才使用。3. 标签溢出 / 窄盒内被裁剪原因早期版本用 SVGtext不换行手工切行lines{[Split into, chunks]}笨拙。 修复所有带标签原语改用foreignObject flex 居中div classdg-fo-label浏览器按盒宽自动换行只需传label...。4. 魔法数字偏移散落各处原因MemoMark x{PC_X 14} y{row.pcY 4} size{12} /这类调用点内联不同偏移与尺寸与容器尺寸隐形耦合。 修复原语自持内嵌偏移与尺寸调用方只传容器参考角MemoMark传右上角原语内部做translate(x - INSET_X - w, y)。ProcessingComponent的表头与 memo 标记同理由容器原语自行定位。5. 源 / 目标颜色意外分化原因早期LogicBox有variantsource/varianttarget不同填充源自不适用于文档图解的首页旧约定。 修复所有非容器逻辑框统一中性奶油 酒红语义区分由形状承担TargetBullet的子弹形本身就与LogicBox不同只有 App 容器保留桃色调。6. 不同高度的箭头打错目标原因所有箭头都指向目标盒的唯一 y 中心导致多条箭头交叉。 修复保持箭头水平——每条箭头在源元素的 y 坐标处射向目标左边缘。前提是目标足够高能容纳多条水平入口。7. 绑定线上出现箭头原因到处用FlowArrow使绑定显得像因果流转。 修复绑定用Connector静态虚线无箭头FlowArrow只用于因果流转。8. MemoMark 实心黑、视觉过重修复用珊瑚色描边 半透明珊瑚填充fill: color-mix(in oklab, var(--coral) 22%, transparent)在任意背景下可读且贴合品牌配色。9. 容器内不对称内边距原因把APP.w/APP.h硬编码成整数再往里塞内容剩余空间全落在右 / 下侧。 修复按第 2 步公式由内容推导容器尺寸下游兄弟引用APP.x APP_W。10. 容器状态类级联污染子元素原因状态 CSS 写成后代选择器.dg-state-updated .dg-box。 修复改用直接子代组合器.dg-state-updated .dg-box。每个基于ShapeGroup的原语有自己的 wrapperg、自己的状态类、自己的直接子代.dg-box。11. 有状态容器内的新状态视觉不突出原因默认线宽 1.4 的彩色状态描边在着色父背景下太细。 修复dg-state-*规则统一把stroke-width提到 2.2hover 的dg-delta-pulse推到 4.2。12. 常驻动画干扰静态页面原因旋转图标refresh 徽标在无人观看时也一直转。 修复diagrams.css中每个动画默认静止、仅.dg-root:hover激活dg-flow、dg-pulse、dg-delta-pulse、dg-spin、dg-check-draw全部如此新动画一律同规则门控并在prefers-reduced-motion覆盖块登记。13. 不看就报告完成症状构建成功了图解完成随后用户截图暴露重叠 / 黑盒 / 变暗内容。 修复报告前必跑scripts/preview.sh并ReadPNG。干净的npm run build只证明 Astro 组件能编译不证明渲染正确。九、创作纪律清单形状承载含义按语义选原语而非看起来合适禁止手动切行标签溢出就加宽盒子或缩短文案外层绝对坐标、插槽局部坐标ProcessingComponent的插槽以 (0,0) 容器左上角渲染子元素流转箭头统一用色默认珊瑚色variantpalm/muted仅在语义需要时使用绑定保持安静Connector静态、虚线、无箭头表示X 绑定于 Y四边内边距全平衡容器内左 右、上 下宽度高度由内容推导下游兄弟引用推导出的宽度优先紧凑图解应在文档列宽约 720px下可读仅在视觉叙事需要时才拉伸maxWidth多在 720–960 之间行距小到同族感而非割裂感dg-step只用于静态内容之外默认 35% 透明度仅 hover 点亮专用于渐进揭示叙事所有动画默认静止flow-drift、delta-pulse、check-draw、refresh-spin 一律.dg-root:hover门控新增keyframes必须在diagrams.css底部prefers-reduced-motion块登记状态规则用直接子代组合器.dg-state-X .dg-box禁止级联新形状原语组合在ShapeGroup上wrapperg、状态/高亮类、titledeleted/title工具提示、MemoMark/StatusBadge徽标含 removed 抑制全部由它接管绝不重实现多状态图解用scenarioprop场景内联在 MDX 正文旁不创建每场景一个.astro包装器单图内联标记尽量精简每个图解的内联 SVG 标记控制在约 30 行以内超长就把重复分组提炼成原语依据 README.md。十、启动模板dev/agent-skills/cocoindex-diagrams/assets/starter.astro提供了一个最小的形状语义图解骨架config-first 布局、带局部坐标插槽的ProcessingComponent、水平箭头、绑定连接线各一复制到docs/src/components/diagrams/concepts/MyDiagram.astro后按需调整即可无需从零起笔。模板中DiagramFrame的title/descprops 应填写面向辅助技术的有意义描述viewBox与maxWidth依据内容推导。至此从形状语义原语、状态/缓存标注体系、布局惯用法、动画纪律到预览验证闭环与陷阱防御CocoIndex 文档图解的完整开发方法论已经贯通。遵循本指南新图解通常可在 2–4 轮预览内达到与既有图解一致的视觉质量与语义精度。【免费下载链接】cocoindexIncremental engine for long horizon agents Star if you like it!项目地址: https://gitcode.com/GitHub_Trending/co/cocoindex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考