OfficeCLI 连接器与形状组合实战用命令行构建 PPT 流程图与组合图形【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源仅包含一个二进制文件无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLIOfficeCLI 是一款面向 AI Agent 与脚本化工作流的命令行办公文档工具。本指南以examples/ppt/shapes/目录下的 shapes-connectors 演示为骨架系统讲解如何用officecli add --type connector绘制 straight / elbow / curve 三种几何预设的连接线、用from/to将连接线钉在既有形状之间、用--type group把多个形状打包成整体以及如何精细控制箭头headEnd/tailEnd、线宽、虚线、折角lineJoin与 miterLimit。读完你即可在终端里徒手搭建一张完整的流程图并理解连接线几何推导、id 路径稳定性等底层机制。演示文件与重新生成shapes-connectors 演示由三个文件协同构成全部位于 examples/ppt/shapes/shapes-connectors.sh —— Shell 脚本串起全部officecli命令并生成 4 页演示文稿shapes-connectors.pptx —— 生成的 4 页成品3 组连接线预设、1 张流程图、1 组形状组合以及 headEnd/lineJoin/miterLimit 组合示例shapes-connectors.md —— 本文的原始素材逐页映射所演示的功能点。随时可重新生成cd examples/ppt bash shapes/shapes-connectors.sh # → shapes/shapes-connectors.pptx脚本末尾会执行officecli close与officecli validate前者落盘后者对文件做结构校验确保产物可被 PowerPoint 打开。脚本刻意不启用set -e当未来版本新增属性、命令返回 exit 2 的UNSUPPORTED props兼容性警告时脚本仍会继续构建完整文档这一设计使旧脚本对新版 CLI 保持向前兼容。核心概念连接器与组合在 OfficeCLI 中连接器connector是一种特殊的帧元素对应 OOXML 的p:cxnSp本质是一条附着在形状上的线——它记录起点/终点所绑定的形状a:stCxn/a:endCxn当形状移动时连线跟随。组合group对应p:grpSp把多个帧打包成单一单元便于整体移动、缩放与统一寻址。连接器的关键属性速览完整字段定义见 schemas/help/pptx/connector.json属性取值说明shapestraight/elbow/curve几何预设另接受 OOXML 全名见下文from/to帧引用起点/终点可为索引、位置路径、id路径或name路径fromSide/toSidetop/bottom/left/right/center强制连线从目标形状的哪条边出发/进入默认自动选相向的边color/lineWidth/lineDash十六进制色 /Npt/ 预设虚线连线外观headEnd/tailEndnone/triangle/arrow/stealth/diamond/oval起点/终点箭头lineJoinround/bevel/miter折角样式支持复合形式miter:limmiterLimit整数miter 上限单位是千分之一百分比800000 800%Slide 1 — 连接器几何预设straight / elbow / curve第一页演示三对锚点形状椭圆 A、B分别用三条不同几何预设的连接线相连officecli create shapes-connectors.pptx officecli open shapes-connectors.pptx officecli add shapes-connectors.pptx / --type slide # Capture the added shapes stable id path (from Added shape at /slide[N]/shape[idM]) A1$(officecli add shapes-connectors.pptx /slide[1] --type shape --prop geometryellipse \ --prop x0.5in --prop y1.5in --prop width2in --prop height1.2in \ --prop fill4472C4 --prop colorFFFFFF --prop boldtrue --prop textA \ | awk /Added/ {print $NF}) B1$(officecli add shapes-connectors.pptx /slide[1] --type shape --prop geometryellipse \ --prop x4.5in --prop y1.5in --prop width2in --prop height1.2in \ --prop fillE63946 --prop colorFFFFFF --prop boldtrue --prop textB \ | awk /Added/ {print $NF}) # Straight connector — direct line between anchor shapes officecli add shapes-connectors.pptx /slide[1] --type connector \ --prop shapestraight --prop from$A1 --prop to$B1 \ --prop color1D3557 --prop lineWidth2pt --prop tailEndtriangle # Elbow connector — 90° right-angle bends A2$(officecli add shapes-connectors.pptx /slide[1] --type shape --prop geometryellipse \ --prop x0.5in --prop y3.6in --prop width2in --prop height1.2in \ --prop fill4472C4 --prop colorFFFFFF --prop boldtrue --prop textA \ | awk /Added/ {print $NF}) B2$(officecli add shapes-connectors.pptx /slide[1] --type shape --prop geometryellipse \ --prop x4.5in --prop y5in --prop width2in --prop height1.2in \ --prop fillE63946 --prop colorFFFFFF --prop boldtrue --prop textB \ | awk /Added/ {print $NF}) officecli add shapes-connectors.pptx /slide[1] --type connector \ --prop shapeelbow --prop from$A2 --prop to$B2 \ --prop color1D3557 --prop lineWidth2pt --prop tailEndtriangle # Curve connector — smooth Bezier arc A3$(officecli add shapes-connectors.pptx /slide[1] --type shape --prop geometryellipse \ --prop x8in --prop y1.5in --prop width2in --prop height1.2in \ --prop fill4472C4 --prop colorFFFFFF --prop boldtrue --prop textA \ | awk /Added/ {print $NF}) B3$(officecli add shapes-connectors.pptx /slide[1] --type shape --prop geometryellipse \ --prop x11.5in --prop y4.5in --prop width2in --prop height1.2in \ --prop fillE63946 --prop colorFFFFFF --prop boldtrue --prop textB \ | awk /Added/ {print $NF}) officecli add shapes-connectors.pptx /slide[1] --type connector \ --prop shapecurve --prop from$A3 --prop to$B3 \ --prop color2A9D8F --prop lineWidth3pt --prop tailEndarrow本页覆盖的功能点--type connector、shapestraight / elbow / curve、from/to捕获的id路径、color、lineWidth、tailEndtriangle / arrow。为什么必须捕获id路径add会在 stdout 打印Added shape at /slide[N]/shape[idM]awk /Added/ {print $NF}取最后一个空白分隔的 token 即得到该路径。id形式在元素重新编号后依然稳定如果之后添加 group 导致位置索引位移/slide[N]/shape[M]这类位置路径可能指向错误的形状而id路径不会失效。这也是全程用变量捕获路径并传入from/to的原因。Slide 2 — 迷你流程图附着连接线 虚线回环第二页用四个流程框Start、Valid?、End、Retry构建真实流程图拓扑happy path 用实线 straight 连接回环分支用虚线 elbow 连接officecli add shapes-connectors.pptx / --type slide # Process boxes — capture paths for connector endpoints P1$(officecli add shapes-connectors.pptx /slide[2] --type shape \ --prop geometryroundRect \ --prop x0.8in --prop y2.5in --prop width2.2in --prop height1.2in \ --prop fill2A9D8F --prop colorFFFFFF --prop boldtrue --prop size16 \ --prop textStart | awk /Added/ {print $NF}) P2$(officecli add shapes-connectors.pptx /slide[2] --type shape \ --prop geometrydiamond \ --prop x4.5in --prop y2.3in --prop width2.8in --prop height1.6in \ --prop fillF4A261 --prop color000000 --prop boldtrue --prop size14 \ --prop textValid? | awk /Added/ {print $NF}) P3$(officecli add shapes-connectors.pptx /slide[2] --type shape \ --prop geometryroundRect \ --prop x9in --prop y2.5in --prop width2.2in --prop height1.2in \ --prop fillE63946 --prop colorFFFFFF --prop boldtrue --prop size16 \ --prop textEnd | awk /Added/ {print $NF}) P4$(officecli add shapes-connectors.pptx /slide[2] --type shape \ --prop geometryroundRect \ --prop x4.7in --prop y5in --prop width2.4in --prop height1in \ --prop fillA8DADC --prop color000000 --prop boldtrue --prop size14 \ --prop textRetry | awk /Added/ {print $NF}) # Happy path: Start → Valid? → End (solid black) officecli add shapes-connectors.pptx /slide[2] --type connector \ --prop shapestraight --prop from$P1 --prop to$P2 \ --prop color1D3557 --prop lineWidth2pt --prop tailEndtriangle officecli add shapes-connectors.pptx /slide[2] --type connector \ --prop shapestraight --prop from$P2 --prop to$P3 \ --prop color1D3557 --prop lineWidth2pt --prop tailEndtriangle # Loopback: Valid? → Retry → Start (dashed red elbow) officecli add shapes-connectors.pptx /slide[2] --type connector \ --prop shapeelbow --prop from$P2 --prop to$P4 \ --prop colorE63946 --prop lineWidth2pt --prop lineDashdash --prop tailEndtriangle officecli add shapes-connectors.pptx /slide[2] --type connector \ --prop shapeelbow --prop from$P4 --prop to$P1 \ --prop colorE63946 --prop lineWidth2pt --prop lineDashdash --prop tailEndtriangle # Branch labels — bare textboxes with no fill (floating text over canvas) officecli add shapes-connectors.pptx /slide[2] --type textbox \ --prop x7.4in --prop y2.7in --prop width1.3in --prop height0.5in \ --prop textyes --prop size12 --prop boldtrue --prop color2A9D8F officecli add shapes-connectors.pptx /slide[2] --type textbox \ --prop x6in --prop y4in --prop width1.3in --prop height0.5in \ --prop textno --prop size12 --prop boldtrue --prop colorE63946本页覆盖的功能点from/to形状路径附着、shapestraight|elbow、lineDashdash回环虚线、tailEndtriangle、--type textbox无填充浮动标签。lineDash的完整取值域在 schemas/help/pptx/connector.json 中声明为 13 种solid、dot、dash、dashDot、lgDash、lgDashDot、lgDashDotDot、sysDot、sysDash、sysDashDot、sysDashDotDot 及兼容别名 longdash、longdashdot。分支标签的另一种方案连接线内联文本流程图上yes / no这类分支标注除独立 textbox 外还可以直接写在连接线上——connector 支持text属性底层是p:cxnSp的子元素p:txBody见 schemas/help/pptx/connector.json。officecli add ... --type connector --prop textYes即可生成带内联标签的连接线多段落的标签可继续用add paragraph/run定向到该 connector 路径上追加。Slide 3 — 形状组合group / shapes / opacity / name第三页把三个半透明叠加的椭圆打包成一个组合单元右侧则是三个未组合的独立矩形作对比officecli add shapes-connectors.pptx / --type slide # Three overlapping ellipses with partial opacity G1$(officecli add shapes-connectors.pptx /slide[3] --type shape \ --prop geometryellipse \ --prop x1.5in --prop y2in --prop width1.4in --prop height1.4in \ --prop fillE63946 | awk /Added/ {print $NF}) G2$(officecli add shapes-connectors.pptx /slide[3] --type shape \ --prop geometryellipse \ --prop x2.4in --prop y2in --prop width1.4in --prop height1.4in \ --prop fillF4A261 --prop opacity0.75 | awk /Added/ {print $NF}) G3$(officecli add shapes-connectors.pptx /slide[3] --type shape \ --prop geometryellipse \ --prop x3.3in --prop y2in --prop width1.4in --prop height1.4in \ --prop fill2A9D8F --prop opacity0.75 | awk /Added/ {print $NF}) # Group the three shapes — shapes is a comma-separated list of captured paths officecli add shapes-connectors.pptx /slide[3] --type group \ --prop shapes$G1,$G2,$G3 --prop nameLogo本页覆盖的功能点--type group、shapes逗号分隔的id或位置路径、name组合的稳定标识、opacity0.0–1.0在分组前作用于单个形状。分组后位置索引会重排id 路径因此不可或缺添加 group 之后处理器会对剩余形状重新编号源码AddGroup位于 PowerPointHandler.Add.Misc.cs。这正是 add 时捕获id形式路径至关重要的原因——它们能在位置索引失效后依然正确寻址。group 的更多细节shapes除id路径外也接受裸数字索引但注意数字索引按 z-order 统计全部顶层帧含已有 group、图片、图表与 Query/Get 使用的p:sp专用 shape[N] 索引空间不同。需要绝对明确的指向时请用id路径见 schemas/help/pptx/group.json。可被组合的元素不只是 shape还包括 picture、table、chart、group、connector——任何顶层帧都能进入shapes列表。组合也支持嵌套add group的父路径可写成/slide[N]/group[K]从而在组合内再建组合源码见 PowerPointHandler.Add.Misc.cs。Set 侧还支持dissolvetrue解散组合把成员提升回幻灯片并展平为幻灯片绝对坐标再移除空组合是 add-group 的逆操作。Slide 4 — headEnd / tailEnd / lineJoin / miterLimit 全组合第四页完整演示所有headEnd/tailEnd组合与全部lineJoin模式officecli add shapes-connectors.pptx / --type slide # headEnd tailEnd arrowhead combinations on straight connectors officecli add shapes-connectors.pptx /slide[4] --type connector \ --prop shapestraight \ --prop x0.5in --prop y1.8in --prop width5in --prop height0in \ --prop color1D3557 --prop lineWidth2pt \ --prop headEndtriangle --prop tailEndoval officecli add shapes-connectors.pptx /slide[4] --type connector \ --prop shapestraight \ --prop x0.5in --prop y2.6in --prop width5in --prop height0in \ --prop color1D3557 --prop lineWidth2pt \ --prop headEnddiamond --prop tailEndarrow officecli add shapes-connectors.pptx /slide[4] --type connector \ --prop shapestraight \ --prop x0.5in --prop y3.4in --prop width5in --prop height0in \ --prop color1D3557 --prop lineWidth2pt \ --prop headEndarrow --prop tailEndarrow # lineJoin on elbow connectors (affects the bend corner geometry) officecli add shapes-connectors.pptx /slide[4] --type connector \ --prop shapeelbow \ --prop x0.5in --prop y5.2in --prop width3.4in --prop height1.6in \ --prop colorE63946 --prop lineWidth5pt \ --prop lineJoinround officecli add shapes-connectors.pptx /slide[4] --type connector \ --prop shapeelbow \ --prop x4.7in --prop y5.2in --prop width3.4in --prop height1.6in \ --prop colorE63946 --prop lineWidth5pt \ --prop lineJoinbevel # Third column uses the compound lineJoinmiter:lim form (1/1000ths of %) # to set the join style AND the miter limit in one prop. officecli add shapes-connectors.pptx /slide[4] --type connector \ --prop shapeelbow \ --prop x8.9in --prop y5.2in --prop width3.4in --prop height1.6in \ --prop color2A9D8F --prop lineWidth5pt \ --prop lineJoinmiter:800000 officecli close shapes-connectors.pptx officecli validate shapes-connectors.pptx本页覆盖的功能点headEnd/tailEndnone、triangle、stealth、diamond、oval、arrow、lineJoinround、bevel、miter、复合形式lineJoinmiter:N、lineWidth。关于 headEnd 与 tailEnd 的方向约定箭头方向存在易混淆的约定head 是连接线的起点from 一侧tail 是终点to 一侧。脚本第 4 页的注释明确写出了这一点。headEndtriangle --prop tailEndoval意味着从起始形状出发的一端画三角形箭头抵达目标形状的一端画椭圆形端点。完整功能覆盖表FeatureSlideConnector presets:straight, elbow, curve1Attached endpoints:from/towith capturedidpaths1, 2Tail arrowheads:tailEndtriangle|arrow|oval1, 2, 4Head arrowheads:headEndtriangle|diamond|oval|arrow4Dash pattern:lineDashdash(dashed loopback connectors)2Line width:lineWidthNpt1–4Color:colorhex1–4Flowchart topology:mixed shapes connectors2Floating labels:--type textboxwith no fill2Group:--type groupwithshapespath1,path2,...3Group name:name(stable name addressing)3Opacity on grouped shapes:opacity0.0–1.03lineJoin on connectors:round, bevel, miter4miterLimit:lineJoinmiter:Ncompound form4验证与检查生成文件closevalidate之后可用查询命令检查任意元素的实际落盘属性# List all elements on slide 1 (shapes connectors) officecli query shapes-connectors.pptx /slide[1] shape # Get the straight connector details officecli get shapes-connectors.pptx /slide[1]/connector[1] # Inspect flowchart connectors on slide 2 officecli query shapes-connectors.pptx /slide[2] connector # Get the group on slide 3 officecli get shapes-connectors.pptx /slide[3]/group[1] # Inspect headEnd/tailEnd on slide 4 connectors officecli get shapes-connectors.pptx /slide[4]/connector[1] officecli get shapes-connectors.pptx /slide[4]/connector[4]connector 的定位路径为/slide[N]/connector[M]支持 add / set / get / query / remove 全操作见 schemas/help/pptx/connector.json。get返回的 readback 是规范化的 OOXML 值例如shape读回straightConnector1/bentConnector3/curvedConnector3这类全名color读回#前缀大写十六进制lineWidth读回 pt 限定字符串。源码级原理连接线几何从何而来from / to 附着与几何自动推导AddConnector实现在 PowerPointHandler.Add.Misc.cs。核心逻辑当提供了from/to而省略x/y/width/height时处理器通过FrameBoundsById查找两端形状的包围盒再调用ComputeConnectorEndpoints计算连线几何源码 PowerPointHandler.Add.Misc.cs。ComputeConnectorEndpoints的自动选边规则是比较两端形状中心的横向/纵向距离差取绝对值更大的那条轴——若横向差更大则 A 从right边出发、B 从left边进入反向布局则对调若纵向差更大则走bottom↔top。这样连线跨过两形状之间的空隙而不是横穿形状本体。若想强制指定边就用fromSide/toSidetop/bottom/left/right/center其中center还原旧版中心到中心的连线观感。一个重要的实现事实PowerPoint 在渲染时不会根据 stCxn/endCxn 重新计算连接线几何它信任写入的 offset/extent。因此若省略位置属性连接线会被画在幻灯片中心附近的硬编码默认位置——这就是为什么脚本必须依赖自动几何推导而不能省略from/to。方向编码则通过flipH/flipV表达当终点在起点左侧或下方时处理器自动设置水平/垂直翻转除非调用方显式传入flipH/flipV覆盖。预设名映射与 OOXML 全名shape属性在底层被映射到 DrawingML 的prstGeom源码 PowerPointHandler.Add.Misc.csstraight别名straightConnector1→StraightConnector1elbow别名bentConnector3→BentConnector3同族还有bentConnector2/4/5curve别名curvedConnector3→CurvedConnector3同族还有curvedConnector2/4/5line→ 裸几何原语Line不带标准连接线 adjust 列表。bent/curved 家族各自有 2~5 段变体映射必须精确到具体的ShapeTypeValues否则 dump→replay 会把源文件的折弯形态悄悄改写例如把 curvedConnector4 折叠成 3 段会改变渲染出的弯曲形状。友好的elbow/curve别名默认取最常见的 3 段形式。箭头类型规范化headEnd/tailEnd经ParseLineEndType解析PowerPointHandler.Fill.cs接受 6 个规范 tokentriangle、arrow、stealth、diamond、oval、none及兼容别名closed→triangle、open→arrow、circle→ovalget读回时统一输出规范 OOXML token保证输入输出对称。此外 head/tail 端还支持size尺寸 tokensmall/medium/large见 PowerPointHandler.Fill.cs。lineJoin 与 miterLimit 的复合形式lineJoin在a:ln下生成a:round//a:bevel//a:miter/子元素。为了用一个键同时表达折角样式 miter 上限支持复合写法lineJoinmiter:lim单独的miterLimit键也会隐式声明 miter 连接PowerPoint 语义中 lim 脱离 miter 无意义值域必须为非负整数千分之一百分比800000 800%非法值会被显式拒绝而非静默忽略PowerPointHandler.ShapeProperties.cs。这些属性同样适用于普通形状轮廓shape 的 headEnd/tailEnd 处理见 PowerPointHandler.ShapeProperties.cs因此连接线教程里的箭头知识可直接复用到描边形状上。合法性约束负尺寸拒绝width/height为负会直接抛错Negative width is not allowed与 shape/picture/chart/media 保持一致避免写出 PowerPoint 绘制为翻转或零尺寸的非法文件。跨度上限由两个相距很远的端点推导出的包围盒可能超过 INT32_MAX EMU即使每个形状自身坐标合法此时抛出Connector span exceeds the maximum supported coordinate。同页约束连接线是页面局部的stCxn/endCxn 的 id 作用域限于所在幻灯片from/to若写成/slide[N]/...且 N 不是当前页会被拒绝而非静默错绑到本页同索引形状PowerPointHandler.Add.Misc.cs。组合内形状不可作为端点FrameBoundsById不深入 group 内部引用组合内的形状会在几何推导路径上被显式拒绝而不是生成坍缩成一端的退化连接线。小结通过 examples/ppt/shapes/shapes-connectors.sh 这一个演示可以完整掌握 OfficeCLI 的 PPT 连线与组合能力用--type connector加shapestraight|elbow|curve快速获得三种几何预设用from/to配合 add 时捕获的id路径把连线可靠地钉在形状之间即使后续 add group 引发重编号用lineDashdash、tailEnd/headEnd、lineJoin与复合miter:lim精细控制流程图视觉再用--type group配合shapes与opacity把多个元素打包为整体。底层实现上几何自动推导、OOXML 预设精确映射、输入规范化与边界守卫共同保证了命令行为构建、PowerPoint 忠实渲染的端到端正确性——这套能力让 AI Agent 无需启动 Office 就能批量生成、改造带流程图的演示文稿。【免费下载链接】OfficeCLIOfficeCLI 是首款也是最佳的专为 AI 代理设计的命令行工具可用于读取、编辑和自动化处理 Word、Excel 和 PowerPoint 文件。它免费、开源仅包含一个二进制文件无需安装 Office 套件。项目地址: https://gitcode.com/iOfficeAI/OfficeCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考