Month-End Closer 波动性注释（Variance Commentary）技能深度解析：从阈值筛选到驱动归因的完整实战指南-平芜编程栈

Month-End Closer 波动性注释（Variance Commentary）技能深度解析：从阈值筛选到驱动归因的完整实战指南

【免费下载链接】financial-services项目地址: https://gitcode.com/GitHub_Trending/fi/financial-services

导读

波动性注释（Variance Commentary）是财务月末结账（month-end close）中不可或缺的一环：管理层需要一份"为什么本期利润表与资产负债表与上期或预算不同"的可读解释，而不是一堆原始数字。本指南以 financial-services 仓库中 month-end-closer 插件的 variance-commentary 技能为核心，完整解析其阈值判定规则、逐行注释表结构、"驱动归因（driver）"的写作规范、数据溯源方式与最终交付形态，并结合仓库内的 Agent 定义、Managed Agent 编排配置与配套技能，展示该技能在月末结账闭环中的真实调用位置与落地方式。读完本文，你将掌握如何让 AI 会计助手输出一份"可审计、可签字、不编造"的波动性注释。

技能定位：month-end-closer 结账包中的第四环

variance-commentary 技能归属于 plugins/agent-plugins/month-end-closer 插件，其前置元数据定义如下：

--- name: variance-commentary description: Write flux commentary for every P&L and balance-sheet line over threshold — current vs prior period and vs budget, with the driver explained from underlying activity. Use for the month-end close package and management reporting. ---

从 month-end-closer 的 Agent 定义可以看出，一次完整结账要交付四类产物，而波动性注释是其中第三环：

应计项目表（Accrual schedule）—— 每笔应计的计算、支持凭证引用与 JE 草稿；
滚动对账表（Roll-forward schedules）—— 期初 + 本期活动 − 冲销 = 期末，并与总账勾稽；
波动性注释（Variance commentary）—— 对超过阈值的 P&L 与资产负债表科目做本期 vs 上期、本期 vs 预算的波动解释；
结账包（Close package）—— 将上述内容整理成可供财务总监（controller）复核与签字的正式文件。

Agent 的系统提示中明确了该技能的工作语境："Draft variance commentary. Flux every line over threshold; explain from the underlying activity."（起草波动性注释：对每个超过阈值的科目做通量分析，并从底层业务活动出发解释原因。）这意味着，variance-commentary 不是孤立工具，而是 month-end-closer Agent 声明的五大技能之一（accrual-schedule·roll-forward·variance-commentary·audit-xls·xlsx-author）——它在拿到应计表与滚动对账表之后执行，再交由 xlsx-author 组装成结账包。

值得注意的是，同一份技能内容也以 fund-admin 垂直插件的 variance-commentary 形式存在（内容一致），说明该技能在基金行政管理等后台财务场景同样适用。

输入三要素与阈值（Threshold）判定规则

输入：三个口径的数值

技能开篇即定义了输入契约——在相同范围（same scope）下同时提供三组数值：

本期实际值（current-period actuals）
上期实际值（prior-period actuals）
预算值（budget）

"相同范围"是严谨性的关键：只有实体、科目、币种、期间口径完全一致的三个数才具备可比性，否则波动百分比本身会失真。

阈值：什么行必须写注释

技能的筛选逻辑是"二者满足其一即标记（Flag a line for commentary ifeitheris true）"：

绝对值波动 ≥ 公司重要性阈值（materiality threshold）：使用调用方提供的数值；默认取"该科目金额的 5%"与"一个固定底线金额（fixed floor）"中的较大者。这个"取较大者"设计非常实用——它同时防止了两个方向的问题：对巨额头寸，5% 可能绝对金额巨大，避免注释轰炸；对小额科目，5% 可能低到没有意义，固定底线确保任何金额超过 floor 的科目都不会被漏掉。
科目位于"必须注释清单"（always comment list）上：技能明确点名的三类科目是收入（revenue）、人头成本（headcount cost）、现金（cash）。这三类对管理层决策最敏感——收入波动直接反映业务基本面，人头成本是可控性最强的费用，现金则是流动性安全的直接信号——因此无论波动是否达到阈值都必须解释。

从 month-end-closer Agent 的工作流看，阈值参数由结账任务上下文携带（例如管理报告制度中定义的 5% 与固定金额底线），技能本身只负责按规则执行，不自行决定阈值——这保证了注释口径在全公司范围内的一致性。

逐行注释表：列结构与"驱动归因"写作规范

注释表的五列结构

对每个被标记的科目，技能要求输出如下表格：

Column	Content
Line	Account or caption
Current / Prior / Budget	The three values
Δ vs priorandΔ vs budget	Amount and %
Driver	One sentence explaining the movement from underlying activity — not a restatement of the number

即每个被标记科目需要：科目名称、三个口径数值、相对上期与相对预算的金额差与百分比差、以及一句话驱动归因。

Driver 写作规范：解释 why，而不是复述 what

技能用一段话专门强调了 Driver 列的核心纪律——这是本技能与普通"数字变动罗列"的本质区别：

A driver explainswhy, notwhat: "Cloud spend up $1.2M on incremental GPU reservations for the May launch" — not "Cloud spend increased $1.2M (18%)."

技能给出了正反两个例子：

合格写法（driver）："云支出增加 120 万美元，源于 5 月发布活动新增的 GPU 预留"——直接点出底层业务活动（incremental GPU reservations / May launch）；
不合格写法（复述数字）："云支出增加了 120 万美元（+18%）"——只是把 Δ 列的数字翻译成一句话，没有解释任何原因。

这条规范的价值在于：管理层读注释包时真正想要的是"发生了什么业务变化"（新增 GPU 预留、新项目立项、供应商切换），而不是"数字变成了多少"（表格里已经写明了）。Driver 必须做到可追溯到真实业务活动，而不是数字的二次陈述。

数据溯源：通过 internal-gl MCP 挖掘驱动因素

技能的"Sourcing the driver"一节规定了驱动归因的证据来源与边界：

Look at the activity behind the line (journal-source breakdown, vendor mix, headcount delta, volume × rate) via the internal-gl MCP. If the driver isn't clear from the data, write "driver unclear — flag for controller" rather than inventing one.

具体而言，Agent 应通过internal-gl MCP 服务器（内部总账查询接口）查看科目背后的活动分解：

凭证来源分解（journal-source breakdown）：例如本期新增的预提凭证、付款凭证、调账凭证各贡献了多少；
供应商组合（vendor mix）：费用集中在哪些供应商，是否有新供应商进入；
人头变动（headcount delta）：解释薪资、福利类科目波动的直接依据；
量 × 价（volume × rate）：收入或成本科目的标准分解框架，拆出量效应与价效应。

这正是 roll-forward 技能所强调的"每条活动行都要有 GL 查询（account + date range + journal-source filter）支撑"的方法在注释场景的延伸——注释中的每个 driver 背后都应该能对应到一条可重跑的总账查询。

技能在此设置了最重要的一条安全边界：如果数据里找不到清晰的驱动因素，就写 "driver unclear — flag for controller"（驱动不明确——标记给财务总监），而不是编造一个。这条规定把"诚实的不知道"制度化：财务总监宁可看到一个明确标注"待查"的行，也不愿意在签字文件里出现一个无法验证的解释——后者在审计场景中可能升级为披露风险。

输出形态：注释表 + 摘要叙述

技能定义的最终产出是两部分：

注释表（the commentary table）：即上文"逐行注释表"中的完整表格，覆盖所有被标记科目；
短摘要叙述（a short narrative，3–5 句）：总结本期最大的几个变动项（biggest movers），让读者无需逐行读表就能先抓住本期财务状况的核心变化。

这段 3–5 句的叙述是管理报告的标准做法：先给结论性的"最大变动"，再让读者按需查看表格细节。

在结账闭环中的落地：从技能到结账包

Managed Agent 编排中的实际调用链

managed-agent-cookbooks/month-end-closer 目录提供了该技能的 Managed Agent 部署形态（面向POST /v1/agents接口）。从 agent.yaml 可以看到完整编排：

name: month-end-closer model: claude-opus-4-7 system: file: ../../plugins/agent-plugins/month-end-closer/agents/month-end-closer.md append: "You are running headless. Produce files in ./out/; do not assume an open Office document." tools: - type: agent_toolset_20260401 default_config: { enabled: false } configs: - { name: read, enabled: true } - { name: grep, enabled: true } - { name: glob, enabled: true } - { type: mcp_toolset, mcp_server_name: internal-gl, default_config: { enabled: true } } mcp_servers: - { type: url, name: internal-gl, url: "${GL_MCP_URL}" } skills: - { from_plugin: ../../plugins/agent-plugins/month-end-closer } callable_agents: - { manifest: ./subagents/ledger-reader.yaml } - { manifest: ./subagents/rollforward.yaml } - { manifest: ./subagents/poster.yaml } # only leaf with Write

关键点在于：variance-commentary 技能被整体打包进 month-end-closer 插件的 skills 集合中（from_plugin），而驱动归因所需的总账数据来自internal-gl这个 URL 型 MCP 服务器（地址由环境变量GL_MCP_URL注入）。部署命令为：

export ANTHROPIC_API_KEY=sk-ant-... export GL_MCP_URL=... ../../scripts/deploy-managed-agent.sh month-end-closer

三层隔离与权限边界

month-end-closer cookbook 的 README 明确了结账流程的三层安全架构，这也界定了注释撰写环节的数据边界：

Tier	Touches untrusted docs?	Tools	Connectors
`ledger-reader`	Yes	`Read`,`Grep`only	None
`rollforward`/ Orchestrator	No	`Read`,`Grep`,`Glob`,`Agent`	internal-gl (read-only)
`poster`(Write-holder)	No	`Read`,`Write`,`Edit`	None

ledger-reader专门读取不可信的支持性文档（供应商发票、对账单），其 worker 定义只授予Read/Grep，无 MCP、无写工具，且必须返回 schema 校验过的 JSON（entity、period、support[]）；
rollforward / Orchestrator通过只读的 internal-gl MCP 查询总账，是注释与滚动对账表的数据来源，见 rollforward worker 定义；
poster是唯一持有Write权限的叶节点，负责把 JE 草稿、滚动对账表与注释组装成./out/close-package-<entity>-<period>.xlsx，见 poster worker 定义。

这条链路对 variance-commentary 的含义是：注释的 driver 只能基于只读总账数据与已校验的支持性数据生成——Agent 本身没有写总账的工具，JE 一律以"草稿"形态进入结账包，实际过账必须由财务总监在 Agent 外部审批（"No GL posting. This agent drafts JEs; posting requires controller approval outside the agent."）。注释中"driver unclear — flag for controller"的行，恰好会被 controller 在签字环节重点关注。

结账包的组装规范

注释表与摘要叙述最终由 xlsx-author 技能写入结账包。从 xlsx-author 技能可以看到 headless 模式下的输出契约：

写入./out/<name>.xlsx（目录不存在则创建），并在最终消息中返回相对路径供编排层收集；
遵循与 audit-xls 技能一致的着色约定：蓝色 = 硬编码输入、黑色 = 公式、绿色 = 跨表/跨文件引用，计算单元格一律为公式、输入统一放在 Inputs 页；
使用 openpyxl 编写短 Python 脚本生成工作簿，并建议包含 Checks 页做勾稽校验（TRUE/FALSE）。

这意味着注释表在交付时应保持"输入数据（三口径数值、阈值参数）与计算列（Δ 金额、Δ %）分离"的结构，方便财务总监与审计复核时追溯每个百分比的计算口径。

二次结账与后续调整：注释的可重复性

cookbook 的 steering-examples.json 展示了三种典型触发场景：

[ { "event": "Close entity US-OPCO for period 2026-04", "description": "Standard month-end close" }, { "event": "Close entity UK-HOLDCO for period 2026-03, scope: accruals only", "description": "Partial close, accruals only" }, { "event": "Re-draft variance commentary for entity US-OPCO 2026-04 after late JEs", "description": "Follow-up after adjustments post" } ]

第三种场景尤其值得注意："滞后过账后的注释重写"——当某些 JE 在首次结账后才过账，期末数发生变化，注释必须随之重跑。这要求注释生成过程完全可重复、可重跑：输入（三口径数值）变了，阈值筛选、Δ 计算与 driver 溯源逻辑保持不变，重新执行即可得到更新后的注释包。这一设计印证了技能定义中"输入契约驱动输出"的工程化思路——注释不是一次性的人工叙述，而是可参数化重跑的确定性流程。

此外，month-end-closer README 还提到该 Agent 会接收来自gl-reconciler（总账对账 Agent）的handoff_request事件——把已验证的对账差异（verified breaks）纳入结账注释，实现"对账发现问题 → 结账解释问题"的跨 Agent 协作。

实战要点速查

阈值取较大者：默认规则是max(科目金额 × 5%, 固定底线金额)，防止巨额头寸注释轰炸与小额科目漏判；
三类必注释科目：收入、人头成本、现金，即使未达阈值也必须写；
Driver 三问：是否回答了 why？是否指向底层业务活动（凭证来源、供应商、人头、量×价）？是否可被总账查询重跑验证？
宁缺毋滥：数据不支持解释时写driver unclear — flag for controller，绝不编造；这是审计友好设计，不是能力缺陷；
交付物两件套：逐行注释表 + 3–5 句摘要叙述，前者供细节核查，后者供快速浏览；
写权限边界：注释生成全程只读总账（internal-gl MCP），JE 只以草稿进入./out/close-package-<entity>-<period>.xlsx，过账必须由 controller 在 Agent 外部批准。