financial-services 仓库 xlsx-author 技能详解基于 openpyxl 的无头 Excel 工作簿产出指南【免费下载链接】financial-services可将 Claude 转变为金融服务专家适用于投资银行、股票研究等领域。提供核心及专项插件支持端到端工作流集成多数据源含技能、命令和连接器可定制适配企业需求。项目地址: https://gitcode.com/GitHub_Trending/fi/financial-services导读本文围绕 xlsx-author 技能文档 展开讲解在无头headless运行环境Managed Agent / CMA 模式下如何用 Python openpyxl 在磁盘上直接生成.xlsx文件并将其作为文件产物artifact交付给编排层。读完本文你将掌握 xlsx-author 的输出契约、工作簿构建方式、蓝/黑/绿配色与公式约定以及它与audit-xls、nav-tieout等技能在 Statement Auditor 场景中的配合方式并了解它与其他 Agent 插件model-builder、pitch-agent 等共享同一套约定的实现事实。一、技能定位文件型产物的回退方案xlsx-author是 financial-services 仓库中statement-auditor插件agents/statement-auditor.md声明的三个技能之一nav-tieout·audit-xls·xlsx-author其 frontmatter 定义如下name: xlsx-author description: Produce a .xlsx file on disk (headless) instead of driving a live Excel workbook — for managed-agent sessions with no open Office app.它的适用场景非常明确当 Agent 运行在无头模式managed-agent / CMA 模式下需要把 Excel 工作簿作为文件产物交付而不是通过mcp__office__excel_*工具去驱动用户桌面上已打开的 Excel 实例时就使用本技能。这一设计在 Managed Agent cookbook 的 agent.yaml 中得到印证系统提示中追加了You are running headless. Produce files in ./out/; do not assume an open Office document.也就是说托管 Agent 场景根本没有打开的 Office 文档可操作所有产物必须以文件形式落盘。何时不要使用本技能技能文档明确给出了反向约束When NOT to use如果mcp__office__excel_*工具可用Cowork 插件模式应改用这些工具——它们驱动用户的活动工作簿并带有审查检查点review checkpoints。本技能是 headless 运行时的文件产出回退方案。也就是说xlsx-author与 Cowork 插件模式是互补关系一个面向有界面的实时协作一个面向无人值守的批量产出。二、输出契约Output contract技能规定了严格的产物交付规范编排层正是依赖它来收集文件的写入位置写到./out/name.xlsx若./out/目录不存在需要先创建。返回路径Agent 必须在最终消息中返回该文件的相对路径以便编排层orchestration layer收集。这条契约在 Statement Auditor 的实际工作流中有一个具体落点cookbook 的 README.md 提到flagger唯一持有 Write 权限的子 Agent会产出./out/signoff-batch.xlsxflagger.yaml 中正是通过skills: - { path: ../../../plugins/agent-plugins/statement-auditor/skills/xlsx-author }挂载本技能。因此./out/约定不仅是技能文档的规定也是整个 statement-auditor cookbook 的通用文件交付约定。三、如何构建工作簿openpyxl 最小可运行示例技能文档给出的构建方式是写一段简短的 Python 脚本并用 Bash 运行使用 openpyxl 库。核心示例代码如下from openpyxl import Workbook from openpyxl.styles import Font, PatternFill wb Workbook() ws wb.active; ws.title Inputs ws[B2] Revenue; ws[C2] 1_250_000_000 ws[C2].font Font(color0000FF) # blue hardcoded input calc wb.create_sheet(DCF) calc[C5] Inputs!C2*(1Inputs!C3) # black formula wb.save(./out/model.xlsx)这个示例麻雀虽小五脏俱全涵盖了几个关键要点wb.active新工作簿默认带一个工作表直接复用并重命名为Inputs作为所有硬编码输入的集中地。跨表公式calc[C5] Inputs!C2*(1Inputs!C3)表明 DCF 计算表的公式直接引用 Inputs 表单元格计算表内不出现任何硬编码数字——这正是计算单元格全部是公式约定的直接体现。字体样式Font(color0000FF)用于给输入单元格上色用颜色标记单元格性质详见下一节配色约定。保存wb.save(./out/model.xlsx)直接落盘到技能约定的./out/目录。openpyxl 依赖与版本前提仓库中对 openpyxl 的依赖要求可以在 pitch-agent/skills/dcf-model/requirements.txt 中看到该技能同样使用 openpyxl 产出 Excel 模型文件openpyxl3.0.0即需要 openpyxl 3.0 及以上版本3.0 起成为xlrd/xlsxwriter之外的主流读写 .xlsx 方案。此外dcf-model 的 validate_dcf.py 脚本 展示了 openpyxl 在实际工程中的另外两种典型用法可作为深化参考openpyxl.load_workbook(excel_path, data_onlyFalse)加载公式本身用于审计公式文本openpyxl.load_workbook(excel_path, data_onlyTrue)加载公式的计算结果值用于检查#VALUE!、#DIV/0!、#REF!、#NAME?等错误值。这提示我们用xlsx-author产出的文件后续完全可以被仓库中的audit-xls技能或类似校验脚本再次加载审计形成产出 → 校验闭环。四、工作簿约定与 audit-xls 镜像的配色与结构规范技能文档特别强调约定与audit-xls技能镜像一致audit-xls/SKILL.md。这些约定是金融模型工作簿的行业级最佳实践逐条展开如下4.1 蓝 / 黑 / 绿三色约定颜色含义蓝Blue硬编码输入hardcoded input黑Black公式formula绿Green指向其他工作表/文件的链接link to another sheet/file在audit-xls的模型结构审查Structural review中同样要求检查颜色约定是否一致应用Blueinput, blackformula, greenlink两处规定完全对应。颜色不是装饰而是让审计者人或 Agent一眼区分哪些是假设、哪些是计算的可视化契约。4.2 计算单元格禁止硬编码No hardcodes in calc cells.Every calculation cell is a formula; every input lives on an Inputs tab.所有计算单元格必须是公式所有输入必须放在 Inputs 工作表上。这一点在audit-xls的公式级检查中也占据核心位置——它将公式内的硬编码如A1*1.05中的1.05列为重点排查项并指出Hardcoded overrides are the #1 source of silent bugs硬编码覆盖是静默错误的第一大来源。换言之遵守 xlsx-author 的约定等于从源头规避审计技能最警惕的一类问题。4.3 命名区域Named ranges凡是在 Deck 或 Memo 中会被引用的值都要定义为命名区域Named ranges。命名区域让外部文档PPT 汇报材料、投资备忘录对模型的引用不再依赖脆弱的单元格坐标模型结构调整时引用依然稳定。4.4 平衡检查Balance checks工作簿必须包含一个Checks 工作表用来做勾稽验证并以 TRUE/FALSE 呈现结果典型检查包括资产负债表平衡BS balances总资产 总负债 权益现金流与现金科目勾稽CF ties to cash这与audit-xls的 model 级完整性检查高度呼应BS 平衡、Cash tie-out、DA 匹配、CapEx 匹配、营运资本变动符号等在 audit-xls 技能 中均有逐项检查清单。在 Statement Auditor 场景中它还对应 nav-tieout 技能 的 LP 资本账户复算逻辑期初资本 出资 − 分配 分配净损益 − 业绩报酬提成 期末资本Checks 表就是把这类勾稽关系固化下来的载体。4.5 一文件一模型One model per file.Do not append to an existing workbook unless explicitly asked.除非用户明确要求否则不要向已有工作簿追加内容。每个文件对应一个独立模型避免不同模型的输入/计算混在一个文件里造成交叉污染也便于审计与版本管理。五、xlsx-author 在 Statement Auditor 工作流中的位置理解一个技能最好的方式是看它在一个真实 Agent 工作流里扮演什么角色。Statement Auditorstatement-auditor.md是LP 报表分发前的最后一道眼睛其工作流如下读取报表statement-reader 子 Agent 提取每份 LP 报表的期末余额。报表被视为不可信可能由上游不受控系统生成reader 只有 Read/Grep 权限、无 MCP 访问权对账通过 NAV MCP 把每个字段与 NAV 数据包逐项比对标记把差异交给 flagger格式化异常清单与签核表sign-off sheet。而xlsx-author正是在第 3 步及类似产出环节被调用cookbook 的 README.md 说明flagger是唯一持有 Write 权限的子 Agent它把对账表整理为./out/signoff-batch.xlsx逐份报表给出 pass/hold 建议且不直接打开报表文件。这与 xlsx-author 的headless 落盘 返回相对路径契约完全一致。同时要注意安全边界statement-auditor 采用三层隔离statement-reader 触碰不可信文档但无写权限reconciler/编排层读 NAV 数据flagger 独占 Write且本 Agent 只给出 pass/hold 建议最终分发由 IR 团队在人工签核后执行——xlsx-author产出的签核表是建议层的产物不是最终对外分发文件。六、仓库中的同构技能一份约定多处复用xlsx-author并非 statement-auditor 独有。通过检索 openpyxl 的使用面可以发现该技能在仓库中被多个 Agent 插件共享且内容完全同构model-builder/skills/xlsx-author/SKILL.mdpitch-agent/skills/xlsx-author/SKILL.mdearnings-reviewer/skills/xlsx-author/SKILL.mdgl-reconciler/skills/xlsx-author/SKILL.mdkyc-screener/skills/xlsx-author/SKILL.mdmarket-researcher/skills/xlsx-author/SKILL.mdmonth-end-closer/skills/xlsx-author/SKILL.mdvaluation-reviewer/skills/xlsx-author/SKILL.mdfinancial-analysis/skills/xlsx-author/SKILL.md从源码结构看这体现了仓库的设计理念将无头产出 Excel 工作簿这一横切能力抽成统一技能供各垂直业务 Agent 复用从而保证所有 Agent 产出的工作簿遵循同一套输出契约与配色/结构规范下游审计audit-xls、校验validate_dcf.py 等与编排层收集路径./out/可以无缝衔接。七、实战要点速查维度规范产出目录./out/name.xlsx目录不存在则创建交付方式最终消息中返回相对路径供编排层收集技术栈Python openpyxl仓库要求openpyxl3.0.0输入集中所有硬编码输入放 Inputs 工作表计算规范计算单元格一律为公式禁止硬编码配色蓝输入、黑公式、绿跨表/跨文件链接命名区域被 Deck/Memo 引用的值必须命名平衡检查包含 Checks 工作表以 TRUE/FALSE 呈现勾稽结果文件粒度一文件一模型除非明确要求否则不追加适用模式headless / managed-agent / CMACowork 模式改用mcp__office__excel_*八、总结xlsx-author是 financial-services 仓库为无头 Agent 场景设计的标准 Excel 文件产出技能它通过./out/落盘 相对路径回报的输出契约打通了与编排层的文件交接通过蓝/黑/绿配色、输入与计算分离、命名区域、Checks 平衡表、一文件一模型的约定保证了产出工作簿的规范性与可审计性并在 Statement Auditor 的签核表产出./out/signoff-batch.xlsx等场景中实际落地。掌握它就等于掌握了在 Managed Agent 模式下用 Python 批量产出高质量金融 Excel 工作簿的标准姿势也让产出的文件天然兼容仓库内 audit-xls 与校验脚本的后续审计链路。【免费下载链接】financial-services可将 Claude 转变为金融服务专家适用于投资银行、股票研究等领域。提供核心及专项插件支持端到端工作流集成多数据源含技能、命令和连接器可定制适配企业需求。项目地址: https://gitcode.com/GitHub_Trending/fi/financial-services创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考