CLIAI 应用MCP 服务【免费下载链接】OfficeCLIOfficeCLI is the first and best Office suite purpose-built for AI agents to read, edit, and automate Word, Excel, and PowerPoint files. Free, open-source, single binary, no Office installation required.项目地址https://gitcode.com/GitHub_Trending/of/OfficeCLI点击查看免费下载OfficeCLI 是一个专门为 AI Agent 设计、用于读写和自动化 Word/Excel/PowerPoint 文件的命令行套件。为了让 Agent 在不安装 Office、不依赖网络的前提下精确掌握「CLI 到底能对哪个元素做什么」项目在 schemas 目录下维护了一套名为capability schemas能力声明 Schema的 JSON 文件作为整个 CLI 能力面的单一事实源single source of truth。本文以 schemas/README.md 为核心骨架结合_schema.json元 Schema、具体元素 Schema 以及src/officecli/Help/下的加载器与渲染器源码系统讲解这套 Schema 的目录组织、字段语义、合并机制、运行时消费路径与契约测试守门方式。读完本文你将能够读懂任意一个schemas/help/format/element.json文件理解officecli format op element --help --json输出的来龙去脉并掌握「改实现必须同步改 Schema、否则 CI 失败」的工程约束。一、Schemas 是什么Agent 可消费的能力声明清单schemas/目录的核心定位从 schemas/README.md 第一段即可确认Agent-facing capability schemas for officecli. Single source of truth for what the CLI supports。换句话说这套 Schema不是给人类看的帮助文档而是给 AI Agent 看的机器可读能力面。它精确回答了三类问题某个格式docx / xlsx / pptx下存在哪些元素element每个元素支持哪些操作add / set / get / query / remove每个操作上支持哪些属性property、属性的类型、取值、别名与读回格式是什么同一份声明被三处消费形成「一处声明、三端一致」的闭环运行时帮助输出officecli format op element --help --json。Schema 在构建期被嵌入二进制因此运行时既不依赖文件系统路径也不依赖网络访问契约测试contract tests每一个 Schema 声明add、set、get、readback都要与真实的 handler 实现逐一验证。属性上的enforcement: strict一旦出现漂移会导致 CI 失败而enforcement: report只记录日志发布期 Wiki 生成未来功能发布前从 Schema 生成/比对 Wiki 的 Markdown。开发期间 Wiki 不被改动Agent 直接读 Schema。这一「Schema 驱动」的设计与项目描述中「Free, open-source, single binary, no Office installation required」的定位一脉相承所有能力描述随二进制分发Agent 拿到一个文件即可自省。二、目录布局与文件组织schemas/README.md 给出了标准布局schemas/ help/ _schema.json ← JSON Schema (draft 2020-12) describing the format below docx/element.json ← Word per-element capability pptx/element.json ← PowerPoint per-element capability xlsx/element.json ← Excel per-element capability从仓库实际文件看schemas/help/下分为四类内容目录内容说明_schema.json元 Schema用 JSON Schemadraft 2020-12描述所有元素 Schema 的合法结构供 IDE 工具链校验docx/46 个元素 SchemaWord 的逐元素能力声明如paragraph、table、style、numbering、field、textbox等pptx/34 个元素 SchemaPowerPoint 的逐元素能力声明如slide、shape、transition、animation、model3d、theme等xlsx/41 个元素 SchemaExcel 的逐元素能力声明如cell、sheet、workbook、pivottable、conditionalformatting、validation等_shared/30 个共享基类跨格式复用的属性集合例如_shared/run.json、_shared/paragraph.json、_shared/chart*.json、_shared/picture*.json、_shared/table*.json等元素文件的命名即 CLI 中可寻址的元素名例如paragraph.json声明元素paragraph同时通过elementAliases: [p]声明路径缩写别名让help docx p与help docx paragraph等价详见第六节。三、元 Schema 详解schemas/help/_schema.json 的顶层字段schemas/help/_schema.json 是整个 Schema 体系的「宪法」。它声明了每个元素 Schema 必须具备的结构顶层字段如下字段类型语义$schemastring指向元 Schema 的指针仅供 IDE 工具使用运行时忽略formatenum:docx/xlsx/pptx所属格式顶层必填elementstring元素在 CLI 中的名字如shape、paragraph、cell、chart-seriesparentstring 或 array若该元素只是其他元素的子节点声明其父元素顶层元素可省略notestring结构化字段装不下的自由说明如不变量、注意事项containerboolean只读根/容器实体presentation、workbook、document、theme、slidemaster 等可被导航但不可创建或变更契约测试对容器跳过 Add/Set 断言operationsobject元素支持的顶层操作含add/set/get/query/remove五个布尔开关addParentstring 或 arrayAdd 接受的具体 CLI 父路径当元素的 stable/positional 路径描述的是自身地址而非 Add 时的父路径时必填例如/comments/comment[N]帮助渲染器据此打印准确的officecli add file parent --type element用法省略时渲染器取paths.positional[0]去掉末段推导pathsobject元素被索引或id寻址时接受的路径形式含stable如/body/p[paraIdID]与positional如/body/p[N]两个数组addressingobject当子元素按 key 属性如axis[rolevalue]而非[N]寻址时使用必填key与pathForm可选keyValuespropertiesobject元素支持的属性表键为规范属性名值为 property 定义见第四节childrenarray声明可在 CLI 路径中寻址的子元素类型childRef见下文partsarray仅合成元素raw使用枚举可通过raw/raw-set命令寻址的原始 OOXML part如/workbook、/Sheet1、/stylesexamplesarray元素级命令示例主要用于合成元素rawdescriptionstring元素级说明elementAliasesarray可解析到本 Schema 的替代元素名如paragraph.json声明[p]使/body/p[N]中的路径缩写与帮助索引对齐operations是 Agent 判断「能不能做」的第一入口。例如 schemas/help/docx/paragraph.json 中五个操作全部为true而container: true的实体如 schemas/help/pptx/presentation.json在渲染时会输出 Read-only container (never created or removed via CLI) 提示且只允许 Get/Set 元数据属性。children数组中的每一项childRef需要四个要素字段语义element子元素 Schema 文件名不带.jsonpathSegment该子元素在 CLI 路径中的段名如series、title、axiscardinalityenum0..1可选单例无[N]、1必选单例、0..n/1..n可索引或按 key 寻址key/keyValues若子元素按属性而非[N]寻址给出属性名及允许值appliesWhen条件适用声明见第四节例如 paragraph 声明子元素runpathSegmentrcardinality0..n对应路径/body/p[N]/r[N]。四、属性声明的五种类型与关键字段每个 property 定义同样由 schemas/help/_schema.json 的$defs.property约束核心字段如下类型type必填string、bool、number、color、length、font-size、enum。其中color统一接受#RRGGBB、RRGGBB、命名色如red、rgb(r,g,b)length要求单位限定的值如12pt、2cmenum配合values数组给出全部合法规范值。取值与别名字段语义valuestypeenum时的合法规范值数组aliases输入时接受的宽松/旧式名字输出时归一化为规范键。数组形式为纯别名列表对象形式为 别名→规范值 映射当多个别名指向不同规范值时有用如chartTypemodifiers枚举类属性的正交修饰符组合规则用prefix/suffix声明如何复合为最终值如stackedBar、column3d并可用appliesWhen限定适用的基值appliesWhen条件适用性键是兄弟/祖先状态的点路径如chartType、role、parent.chartType值是允许值数组所有键必须同时匹配AND 语义requires必须与当前属性同时设置的同一元素上的其他属性例如opacity需要fill才能附着 alpha契约测试会自动捆绑requires条目一起验证操作与读回字段语义add/set/get该属性在对应动词下是否可用。例如 paragraph 的start是add:true, set:true, get:false只写不回读examples属性级命令示例如--prop aligncenterreadbackGet 读回值的预期格式例如12pt、#RRGGBB uppercaseenforcementstrict或report。strict 契约测试失败即阻断 CIreport 漂移仅记录日志。新属性默认strict历史债可以report起步再逐步迁移这套字段设计让 Schema 不仅能「描述」还能被契约测试直接执行——每个属性的add/set/get开关、readback格式、requires依赖都变成了可自动断言的内容。五、案例解剖docx paragraph 的完整能力面schemas/help/docx/paragraph.json共 1630 行是体系中最有代表性的元素 Schema 之一值得完整拆解。头部声明{ $schema: ../_schema.json, format: docx, element: paragraph, elementAliases: [p], operations: { add: true, set: true, get: true, query: true, remove: true }, paths: { stable: [/body/p[paraIdID]], positional: [/body/p[N]] }, children: [ { element: run, pathSegment: r, cardinality: 0..n } ], extends: _shared/paragraph }其note字段直接点明了 readback 的规范键语义Get 返回规范键spaceBefore/spaceAfter/lineSpacing/align旧式别名spacebefore/linespacing/halign仍可在 Add/Set 时接受effective.*键是通过「首个 run 的样式链 → 段落样式 → docDefaults」解析出的只读有效值每个effective.X都携带effective.X.src指针指向写入层如/styles/Heading1当段落或首个 run直接设置了该值时这些有效值会被抑制。属性可以按职责分成五组段落级版式align枚举left/center/right/justify/both/distribute、style/styleId/styleName样式寻址三态styleId直击 OOXML styleIdstyleName经 styles part 解析显示名、lineRuleauto/exact/atLeast与lineSpacing配对、lineSpacing倍距1.5x或固定18pt、spaceBefore/spaceAfter12pt这类单位限定长度、firstLineIndent/rightIndent/hangingIndent经 SpacingConverter 路由列表与编号listStylebullet/ordered/none会自动延续紧邻的前一个同类型列表、numId底层编号实例 id需先add /numbering --type num、numLevel缩进级别 0..8requires: [numId]、start起始编号作用于整个共享 numId 的编号实例只写不回读——w:start位于独立的 numbering part跨 part 遍历脆弱需要时直接 query numberingrun 级字符格式Add 时作用于text隐式创建的 runSet 时作用于段落全部 runbold/italic/font/size/color/underline含underline.color/strike/highlight/caps/smallcaps/dstrike/vanish/outline/shadow/emboss/imprint/noproof/superscript/subscript/vertAlign/charSpacing/rtl其中大量效果型属性caps、smallcaps、shadow、emboss等明确标注set:false, get:false仅限 Add复合脚本与多语言directionltr/rtlrtl 会同时写w:bidi/、段落标记上的w:rtl/与每个 run 的w:rtl/、font.cs/font.ea/font.latin、font.*Theme系列minorHAnsi、majorEastAsia等主题字体绑定、bold.cs/italic.cs/size.cs阿拉伯/希伯来语粗斜体与字号、markRPr.*段落标记 ¶ 的 run 属性含markRPr.size.cs等 CJK/RTL 对应项保证 dump→batch 往返不丢复数字体度量只读有效值effective.*effective.size、effective.font.ascii/eastAsia/hAnsi/cs、effective.bold/italic/color/underline/rtl每个都带.src源指针add:false, set:false, get:true供 Agent 判断「最终渲染效果从哪一层来」。这种「写入口含别名 读回格式 有效值解析 只写属性标注」的组合是 Agent 正确调用的关键——例如设置--prop styleNameHeading 1会通过 styles part 解析显示名而 Get 只会回读styleId。六、共享基类_shared/*与 extends 合并机制跨格式元素存在大量重复属性Schema 体系用「共享基类 extends 合并」来消除重复。schemas/help/_shared/run.json 是典型基类只声明bold、color、font、italic、size、text六个通用属性并以shared_base: true标记。从源码 src/officecli/Help/SchemaHelpLoader.cs 看合并发生在加载时而非构建时ReadExtendsList读取extends字段单个字符串或数组按声明顺序先加载第一个基类再逐层用MergeSchemaJson深合并后续基类最后应用覆盖文件MergeSchemaJson的覆盖语义顶层标量/数组字段直接替换properties对象按 key 合并同名属性整体原子替换不做逐属性深合并合成标记extends与shared_base被剥离。因此docx/paragraph.json的extends: _shared/paragraph意味着_shared/paragraph中跨格式共用的段落属性会先合入格式专属属性如lineRule、markRPr.*、effective.*在覆盖文件中补齐。加载器对_shared的解析路径统一为schemas/help/{baseRef}.json即_shared/paragraph对应 schemas/help/_shared/paragraph.json。七、运行时消费help 命令的加载与渲染链路7.1 嵌入式资源与格式别名Schema 在构建期通过 src/officecli/officecli.csproj 的EmbeddedResource Include..\..\schemas\help\**\*.jsonLogicalName 归一为schemas/help/...嵌入二进制。SchemaHelpLoader在首次使用时扫描Assembly.GetManifestResourceNames()构建 manifest 索引之后所有查找都在内存中进行——这正是「运行时不依赖文件系统路径或网络」的实现基础。加载器还提供了一层人性化容错格式别名word→docx、excel→xlsx、ppt/powerpoint→pptx未知格式会给出最近匹配建议ClosestMatch用子串 Damerau-Levenshtein 距离容差max(2, len/3)根别名/按格式映射到xlsx→workbook、docx→document、pptx→presentation与 set/get/query 中/表示文档根保持一致元素别名文件名精确匹配失败后扫描各 Schema 顶层的elementAliases如p→paragraph、col→column使路径缩写与帮助索引对齐见 src/officecli/Help/SchemaHelpLoader.cs。7.2 渲染人类可读文本与机器可读 JSONsrc/officecli/Help/SchemaHelpRenderer.cs 提供两个入口RenderJson直接以缩进 JSON 输出整份 Schema--help --json的机器可读路径RenderHuman按固定版式渲染。支持verbFilter--help set paragraph这类动词视图只展示声明verb: true的属性并带(verb-view)标记若元素根本不支持该动词则输出verb is not supported on format element.。人类可读视图的排版元素包括格式/元素标题、容器只读提示、Parent、Pathsstable positional 合并、Addressing含 key 的允许值如role values: cat, val, ser、Operations、Usage 块、Properties、Parts、Children、Note、Examples。其中Usage 块是自动化生成 CLI 用法的关键优先取paths.positional[0]回退stable[0]按add/set/get/query/remove各生成一行命令模板例如officecli add file /body --type paragraph [--prop keyval ...] officecli set file /body/p[N] --prop keyval ... officecli get file /body/p[N] officecli query file paragraph officecli remove file /body/p[N]父路径默认由DeriveParentPath去掉末段推导/body/p[N]→/body当元素的路径描述自身地址如/comments/comment[N]而非 Add 父路径时Schema 必须显式声明addParent渲染器优先采用它。7.3 平面转储help all 与 --jsonl对 Agent 而言逐元素查看效率偏低src/officecli/Help/SchemaHelpFlatRenderer.cs 提供了全量平面视图RenderAll每行一条自包含记录两种行标签——ELEM元素摘要含ops:[asgqr]与 paths与PROP属性明细含 name/type/ops/enum 值/aliases/描述/首个示例。ops用 5 字符表达aadd sset gget qquery rremove-表示不支持一行即可 grep 到「哪个元素能 add、哪个属性有某别名」RenderAllJsonl每行一个独立可解析的 JSON 记录首行是带ops_legend的 meta 记录适合while read line; jq ...流式消费RenderAllJsonArray同一记录集的单个 JSON 数组配合标准{success, data, warnings}信封一次JSON.parse即可。因此 Agent 可以执行officecli help all或officecli help docx all | grep ...快速定位能力面。7.4 校验与指纹--prop 合法性 officecli crcSchemaHelpLoader.ValidateProperties见 src/officecli/Help/SchemaHelpLoader.cs会在 Add/Set 前校验--prop字典允许键 规范属性名 该属性的 aliases 通用键from/copyFrom/path/positional/text 点分属性命名空间前缀font.、alignment.、border.、fill.、shadow.、glow.、series.、trendline.、表格/段落的ind./shd./pbdr.等带索引的点分键series1.color、dataLabel3.text、point2.fill、legendEntry1.delete、criteria0.equals按前缀数字点匹配未知键返回给调用方并报 bogus props 错误。该校验器被CommandBuilder.Add内联与ResidentServer.ExecuteAdd驻留模式共用保证两条执行路径报错语义一致。另外 src/officecli/Help/SchemaCrc.cs 对全部嵌入式schemas/help/**资源按规范名排序计算 CRC32 指纹通过officecli crc暴露。下游自动化可以在升级二进制后比对指纹未变化 → 文档化的属性面一致变化 → 重新验证机器可读输出的假设。指纹只覆盖 Schema 文件序列化行为如 JSON 字段顺序不在其内。八、契约测试strict 与 report 两级守门Schema 声明的每一项能力都必须经过真实 handler 的验证这是「单一事实源不漂移」的机制保障。两层执行语义README 原文enforcement: strict属性级契约测试失败会阻断 CI。凡是新加入的属性默认就是strictenforcement: report漂移只记日志。历史遗留债务可以report起步再逐步迁移到strict。具体到执行粒度契约测试覆盖「元素级操作声明」与「属性级动词/readback 声明」两层元素上的operations声明的add/set/get/query/remove会与 handler 的实际支持情况比对属性上的add/set/get开关与readback格式会逐一断言requires字段声明的成对属性会被测试自动捆绑携带container: true的实体跳过 Add/Set 断言只读容器不可创建或变更。SchemaHelpLoader中的FindUnknownKeys对比 handler Get 返回的键与 Schema 声明被描述为「Phase-1 schema/handler parity helper」正是契约测试的反向核对通道不仅 Schema 说的 handler 要做到handler 实际输出的也不能超出 Schema 声明未落地 Schema 的新元素保持宽容不产生硬失败。九、编辑规则与维护边界schemas/README.md 明确了协作纪律任何改变某元素Add、Set或Get行为的 PR必须在同一 PR 内同步更新对应的 Schema 文件否则 CI 契约测试直接失败。这是双向往的一致性保证——实现与声明必须同批落地。同时 README 划定了「不属于这里」的内容边界避免目录职责污染叙事/教程/最佳实践→ 发布期由 Schema 生成或手写的 Wiki内部实现笔记→ 项目约定与代码注释临时发布说明→ CHANGELOG。也就是说schemas/help/*.json只承载「结构化的能力事实」不带故事性内容保证它始终是可以机械校验的最小声明面。十、给 Agent 的实战建议基于以上机制Agent 在集成 OfficeCLI 时可以遵循以下实践用--help --json而非猜测属性写任何add/set命令前先执行officecli format op element --help --json拿机器可读能力面确认属性名、类型、枚举值与动词支持善用动词视图与平面转储--help set element只显示可 set 的属性officecli help all或help docx all可一次拉全量配合grep/awk/fzf语义检索流式场景用--jsonl尊重只写与只读标记注意get:false的属性如 paragraph 的start、caps、shadow只能写入不能回读读回请走对应 part如 query/numberingeffective.*是只读推导值不要尝试写入利用requires与别名numLevel要求numId同时设置fill/shd/shading是三合一别名契约测试会自动验证这些组合Agent 依样组合即可避免 OOXML 畸形升级后校验officecli crc比对 CRC 指纹确认 Schema 能力面是否变化再决定是否重跑校验管线。小结schemas/help不是一份给人翻阅的文档而是 OfficeCLI 能力面的机器可读单一事实源它驱动运行时--help --json输出、被契约测试逐项校验、并被规划为发布期 Wiki 的生成基础。通过_schema.json的严格约束、_shared/*的 extends 合并、elementAliases与格式别名的容错解析、以及enforcement: strict/report的两级守门OfficeCLI 做到了「Agent 看到的帮助、测试验证的行为、二进制实际提供的能力」三者始终一致——这正是它作为 AI Agent 优先的 Office 自动化套件最核心的工程基石。想要深入验证文中任一机制可直接查看 schemas/help/docx/paragraph.json、schemas/help/_schema.json 与 src/officecli/Help/SchemaHelpLoader.cs 等源码文件。赞分享CLIAI 应用MCP 服务【免费下载链接】OfficeCLIOfficeCLI is the first and best Office suite purpose-built for AI agents to read, edit, and automate Word, Excel, and PowerPoint files. Free, open-source, single binary, no Office installation required.项目地址https://gitcode.com/GitHub_Trending/of/OfficeCLI点击查看免费下载相关推荐OfficeCLI 能力模式Agent-Facing Capability Schemas深入解析schemas/ 目录结构与 --help --json 的单一事实来源OfficeCLI 能力模式Agent Facing Capability Schemas深入解析 schemas/ 目录结构与 help json 的单人工智能AI 应用AI 技能CLIMCP 服务Agent Governance Toolkit 一致性测试体系运行时策略契约、适配器中介与证据测试Agent Governance Toolkit 一致性测试体系运行时策略契约、适配器中介与证据测试 本文讲解 Agent Governance Toolki人工智能AI AgentAI 安全治理策略引擎认证鉴权Agent 沙箱可观测性ZeroClaw AGENTS.md 全解面向 AI 编码助手的仓库协作契约与单一事实来源指南ZeroClaw AGENTS.md 全解面向 AI 编码助手的仓库协作契约与单一事实来源指南 ZeroClaw 项目根目录 https://link.gi人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考