编写 GenOffice 标准编辑操作文档：ops/_format.md 规范、OP_DOCS 解析与示例测试保障

人工智能AI 应用桌面应用AI AgentMCP 服务AI 技能【免费下载链接】genofficeFree, open-source AI Office suite: Docs, Sheets, Slides, PDF, Markdown and HTML editors with a built-in AI agent, plus a genoffice CLI and agent skill so Claude Code, Codex and Cursor can create and edit real .docx/.xlsx/.pptx files locally. Bring your own key. macOS, Windows Linux.项目地址https://gitcode.com/gh_mirrors/ge/genoffice点击查看免费下载导读本文围绕 GenOffice 开源 AI Office 套件中演示文稿slidesAI 编辑能力的核心文档packages/pptx-ops/src/prompts/ops/_format.md完整讲解标准编辑操作canonical edit opsMarkdown 文档的编写格式规范。你将掌握操作文档的文件布局、block 语法、签名与 flags 约定、示例占位符 id、写作规则以及这套文档如何被解析成OP_DOCS、如何经测试套件与操作注册表双向校验、如何最终通过apply_ops/load_guide工具进入模型上下文从而具备为 GenOffice 幻灯片 AI 面编写或维护操作文档的完整实战能力。在 GenOffice 的幻灯片模块apps/slides中模型Agent编辑真实.pptx文件的动作被收敛为一组标准编辑操作。这些操作的名字、签名、字段表、示例与常见错误全部以 Markdown 形式存放在packages/pptx-ops/src/prompts/ops/目录下而_format.md正是约束这些文件形态的编写规范authoring guide——它本身不会被加载进任何 prompt却决定了模型对全部编辑操作的认知质量。一、文档的定位模型所知的唯一事实来源single source of truth_format.md开篇即明确了这套文档在整个 AI 编辑链路中的地位Theops/*.mdfiles are the single source of truth for what the model knows about canonical edit ops.也就是说模型对于能执行哪些操作、每个操作长什么样的认知完全由packages/pptx-ops/src/prompts/ops/下的六个分组文件text.md、element.md、insert.md、table.md、slide.md、deck.md决定。这条链路在源码中可完整印证解析packages/pptx-ops/src/op-docs.ts在模块导入时通过import textMd from ./prompts/ops/text.md?raw等方式将各 Markdown 文件以原始字符串内联构建期?raw内联运行期不读磁盘随后用正则逐 block 解析为OP_DOCS。派生opVocabulary()按组列出可调用操作名供工具描述使用、opUsage()失败操作的引导错误中附带一行签名、opSignatureIndex()全部可调用操作的一行签名索引约 4 KB常驻 prompt、opGuide()按需返回某个组的完整 Markdown 正文均由解析结果派生。校验apps/slides/tests/op-docs*.test.ts断言文档与操作注册表完全对应、每个示例都能针对 fixture deck 通过runTxn(dryRun)验证、且文件不包含任何 CJK 文本。由此可以概括出该设计的目的把文档与代码放在同一仓库并接受自动校验防止两者漂移——操作注册表里新增了一个操作而文档缺失测试会立即失败而不是在生产环境中让模型盲调。二、文件布局一个分组一个文件规范给出了每个分组文件的顶层骨架# Group title one-line summary shown in the load_guide catalog optional group-level prose: addressing, units, conventions ### opName signature prose, field table, examples, common mistakes, related ops ### nextOpName (not-ai-callable) signature ...对应的硬性约定一文件一分组文件名即分组 id允许的分组为text、element、insert、table、slide、deck与packages/pptx-ops/src/op-docs.ts中的OpGroup联合类型及GROUP_ORDER常量一一对应。分组标题行文件首行必须是# Group title例如# Text ops紧接着是 one-line summary摘要行。解析器要求两者都必须存在否则抛出missing # Title / summary header错误该摘要正是load_guide工具目录catalog里展示的一行简介。分组级说明标题与摘要之后可以有一段可选的分组级 prose通常交代本组通用的寻址方式、单位与惯例。例如text.md的 All three taketarget:{slide, el}、element.md的 Geometry is document-space EMU: 1 pt 12700 EMU、slide.md的 slideis a 0-based index or a durables_nid。以packages/pptx-ops/src/prompts/ops/text.md为例其头部结构为# Text ops Replace or restyle the text of a text box, shape or table: whole-body rewrite (setText), run-level font patch (setFont), paragraph format patch (setParagraphFormat), typeset math (insertEquation). All three take target:{slide, el}. ...解析器对这段头部的处理逻辑op-docs.ts中parseGroup的头部扫描循环与上述格式完全一致。三、block 语法标题、签名与 flags每个操作op对应一个以###开头的 block规范定义了其内部结构的全部细节1. 标题行与操作名block 以### opName开始opName必须与注册表中已注册的操作名精确匹配由packages/pptx-ops/src/ops/registry.ts的register()维护opNames()可枚举全部名称。标题后的括号内可追加 flags用逗号分隔Flag含义(not-ai-callable)将该操作从词汇表opVocabulary()与签名索引opSignatureIndex()中隐藏——适用于字节bytes/剪贴板clipboard/部件路径part-path载荷模型无法自行产生这些数据(pending)完全隐藏该操作直到注册该操作的分支真正落地避免模型调用尚不存在或签名尚未固定的操作组合例如(not-ai-callable, pending)解析器对 flags 有严格校验op-docs.ts中for (const flag of flags)循环任何未知 flag 都会直接抛出unknown flag错误重复定义同一操作名duplicate block同样报错。pending语义在op-docs.ts的注释中说得更透一个未落地分支提前写好文档可以保持 PR 相互独立但必须隐藏该操作否则模型调用未知操作、或 unknown-op 错误上出现一行看似字段问题的 usage 行都会误导模型。2. 签名行signature标题行之后第一个非空行即为签名必须用单个反引号包裹解析器用SIG_RE /^([^])\s*$/ 匹配缺签名会直接抛错。签名会被原样拼进引导错误格式为Usage: opName signature因此规范要求保持紧凑、且签名内部不得再出现反引号。签名索引中?标记可选字段。实测签名示例opUsage()与opSignatureIndex()的输出包括setText {paragraphs:[{runs:[{text,bold?,italic?,fontSize?,color?}],align?}]} (group children: add group:group id) setTransform {box:{x,y,cx,cy},rotDeg?} (group children: absBox instead of box, plus group:group id) addChart {kind:bar|barStacked|line|area|pie|doughnut|scatter|radar|comboBarLine,categories:[…],series:[{name,values:[…]}],offset,title?,colorScheme?:[#RRGGBB],holeSizePct?} setTableStyle {styleName} | {styleId?,firstRow?,lastRow?,firstCol?,lastCol?,bandRow?,bandCol?,keepFormatting?,shadingColor?,borderColor?,borderWidthPt?,borderPreset?}3. 正文与示例标题与签名之下是自由正文说明 prose、字段表、JSON 示例、Common mistakes、Related ops 等。AI-callable 操作 block 内每一个 json fenced block 都是一个可运行示例——测试套件会将其中的占位符 id 替换为 fixture deck 的真实 id然后通过runTxn(dryRun)以干跑模式执行验证见第五节。因此示例必须使用规范给定的占位符且 JSON 必须严格合法。四、示例占位符 id 与 fixture deck为了让示例既可读又可自动化验证规范维护了一张占位符表每个占位符映射到 fixture deck 中的一个确定元素PlaceholderFixture elemente_TEXTa text box on slide 0e_SHAPEa rounded rectangle on slide 0e_PICTUREa picture on slide 0e_TABLEa 2x2 table on slide 0e_CHARTa bar chart on slide 0e_LINEa straight connector on slide 0e_GROUPa group on slide 0e_CHILDa direct child of that groupSECTION_IDan existing section GUID配套约束fixture deck 恰好只有两张幻灯片索引 0 和 1durable id 分别为s_1与s_2。这意味着面向当前幻灯片的示例可以放心引用 slide 0 上的e_*元素涉及另一张幻灯片的操作如addElement的插入目标示例中会用到slide: 1target.slide既可以写 0-based 索引也可以写 durable id如addBlankSlide的示例中slide: s_1文档编写者可自由选择更能说明问题的写法。在apps/slides/tests/op-docs-examples.test.ts中这些占位符被替换为 fixture 的真实元素 id随后逐一执行runTxn(dryRun)——dry-run 语义意味着只做计划期校验、不真正改动 deck任何字段缺失、类型错误、越界引用都会让测试失败。这正是文档即契约的落地方式。五、写作规则语言、单位、字段表与篇幅_format.md的 Writing rules 部分给出了文档作者必须遵守的硬性要求逐条对应到实现与测试仅英文。正文以及示例中的文本内容标题、标签、类别等也必须使用英文。这条规则的强制执行由apps/slides/tests/op-docs-english.test.ts负责——它扫描六个分组文件断言其中不包含任何 CJK 字符。单位约定除非字段名本身带单位后缀...Pt、...Pct、...Deg否则数值单位一律是文档空间 EMU且必须在字段表中显式说明。例如element.md明确指出1 pt 12700 EMU、1 px 9525 EMU仅对标准 1280 px 宽的 16:9 deck并提示read_slide会报告当前 deck 的精确换算因子。字段表完整性字段表必须列出该操作validate/apply读取的每一个字段而不仅是签名中出现的那几个。例如setText的字段表覆盖了paragraphs、paragraphs[].runs含link的三种 kind、align、level、bullet、lineSpacingPct/spaceBeforePt/spaceAfterPt、rtl、group等签名之外的细节。Common mistakes 的写法每条错误描述都应当指出模型通常错在哪里以及正确的做法是什么语气与运行期的引导错误GuidedError保持一致——即既说明哪里错了也说明该怎么做因为模型正是靠这类反馈实现自纠错的。packages/pptx-ops/src/ops/registry.ts的注释对此有明确论证validation failures must state what is wrong AND what to do。篇幅上限每个分组文件应控制在约 8 KB 以内若超限应将分组拆分为子文件并相应添加 catalog 条目而不是放任文件膨胀。这保证了load_guide按需加载单组文档时上下文开销可控。六、解析器实现从 Markdown 到 OP_DOCSpackages/pptx-ops/src/op-docs.ts是规范落地为代码的核心值得深入理解其解析流程约 160 行全部逻辑清晰可读正则约定HEADING_RE匹配### opName (flags)标题行SIG_RE匹配单反引号签名FENCE_JSON_RE/FENCE_END_RE界定 json 代码块。解析器从每个文件头部提取# 标题与 摘要然后逐 block 提取 name、flags、sig、body 与 examples 数组。OpDoc结构每个操作解析为一个对象{ sig, group, aiCallable?, pending?, examples, body }其中body是签名行之下的整段正文prose、字段表、示例、mistakes 均在内。四个派生函数opVocabulary()按组输出可调用操作名一行一组作为apply_ops工具描述中的词汇表opSignatureIndex()输出全部可调用操作的一行签名name sig按组以## group分节约 4 KB常驻 prompt让模型知道有什么、长什么样opUsage(name)某操作校验失败时向引导错误追加Usage: name sig一行让模型在首次接触失败时立刻学到精确字段opGuide(group)/opGuideCatalog()按需返回某个分组的完整 Markdown 正文 / 分组目录行。在apps/slides/src/renderer/ai/slides-skill.ts中可以看到这些函数的真实消费场景apply_ops工具描述内联了opSignatureIndex()并明确告知模型字段表、可运行 JSON 示例与常见错误可通过load_guide按组加载load_guide工具的inputSchema则用[...OP_GROUPS]限定可选的组名枚举其描述文本由opGuideCatalog()生成。七、测试保障文档与注册表的双向约束apps/slides/tests/op-docs.test.ts将上述规范固化为可执行断言其核心包括每个已注册操作都有文档行opNames().filter((n) !OP_DOCS[n])必须为空——新增操作忘记写文档测试失败每条文档行都对应已注册操作反向检查OP_DOCS中是否存在注册表里已移除的僵尸文档pending项in-flight 分支除外词汇表只列可调用操作opVocabulary()必须包含tableMerge、applyHeaderFooter、groupElements等且不得包含addPicture、pasteSlide这类字节/剪贴板载荷操作对应(not-ai-callable)flag每个 block 都有紧凑签名与正文sig必须以{开头、不含反引号body长度大于 20签名索引与词汇表一致aiCallable false或pending的操作不得出现在opSignatureIndex()中每个分组都有完整 guide标题、摘要、全文 markdown 均存在且opGuideCatalog()中每行格式为group — summary。配合op-docs-examples.test.ts示例逐一 dry-run与op-docs-english.test.ts无 CJK三个测试文件共同构成了对文档-注册表-示例-语言四重维度的自动校验网。这正是_format.md所说 Tests ... assert that the docs track the op registry exactly 的工程实现。八、实战如何编写或修改一个操作文档综合以上规范为一个新操作例如注册表新增的setConnectorEndpoints编写文档时应遵循以下步骤选定分组文件按操作语义归入text/element/insert/table/slide/deck之一若操作属于演示文稿级无 target归入deck。书写 block以### opName开头若载荷为字节/剪贴板/部件路径则加(not-ai-callable)若分支未落地加(pending)紧随其后一行单反引号包裹的紧凑签名。补全字段表列出validate/apply读取的全部字段注明类型、单位EMU/Pt/Pct/Deg、默认值与取值范围颜色一律#RRGGBB主题槽位仅 6 位十六进制。编写可运行示例使用e_*/SECTION_ID占位符保证 JSON 结构完整、字段与签名一致示例将接受 dry-run 验证。编写 Common mistakes以模型易错点 纠正动作的句式给出 13 条语气对齐GuidedError。保持仅英文与 8 KB 篇幅限制必要时拆分分组并更新 catalog。完成之后运行apps/slides/tests/op-docs*.test.ts即可验证文档与注册表、fixture deck 的契约关系——通过即代表该操作已经可以被 GenOffice 的 AI 编辑链路apply_ops/load_guide正式认知与调用。参考与延伸阅读编写规范原文packages/pptx-ops/src/prompts/ops/_format.md六个分组文档text / element / insert / table / slide / deck解析器实现packages/pptx-ops/src/op-docs.ts操作注册表与引导错误packages/pptx-ops/src/ops/registry.ts消费端工具定义apply_ops / load_guideapps/slides/src/renderer/ai/slides-skill.ts契约测试apps/slides/tests/op-docs.test.ts、apps/slides/tests/op-docs-examples.test.ts、apps/slides/tests/op-docs-english.test.ts赞分享人工智能AI 应用桌面应用AI AgentMCP 服务AI 技能【免费下载链接】genofficeFree, open-source AI Office suite: Docs, Sheets, Slides, PDF, Markdown and HTML editors with a built-in AI agent, plus a genoffice CLI and agent skill so Claude Code, Codex and Cursor can create and edit real .docx/.xlsx/.pptx files locally. Bring your own key. macOS, Windows Linux.项目地址https://gitcode.com/gh_mirrors/ge/genoffice点击查看免费下载相关推荐CesiumJS文档编写规范API文档与示例代码标准终极指南CesiumJS文档编写规范API文档与示例代码标准终极指南 CesiumJS作为领先的开源3D地球和地图可视化库其 API文档编写规范 和 示例代码标准前端3D渲染图形学数据可视化文档标题文档标题 概述 简要说明文档目的和范围 功能特性 功能点1详细描述 功能点2详细描述 安装指南 系统要求 Windows版本要求 硬件要求 安装步骤 1.桌面应用系统编程Anime.js文档编写API文档与示例代码规范Anime.js文档编写API文档与示例代码规范 引言 还在为JavaScript动画库的文档质量参差不齐而烦恼吗Anime.js作为一款轻量级、高性能的J前端上一篇Linux平台B站客户端深度评测从核心功能到高级玩法下一篇重构实时语音转文字体验TMSpeech的插件化架构革新创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考