mcpField
S
spreadsheets

spreadsheets

github.com/paulrberg文档处理102259 次安装今天更新
代码仓库

关于 spreadsheets

供 Agent 处理表格数据的技能，强调数值精度、最小化修改、原子写入、按数据来源处理及结构验证。

主要功能

  1. 01精度安全的数值处理
  2. 02最小化定向修改
  3. 03原子替换文件
  4. 04公式注入防护
  5. 05结构与领域验证
  6. 06表格任务工具选择

适用场景

  1. 01转换金融表格并保留精度
  2. 02仅编辑指定的表格单元格
  3. 03验证更新后的工作簿或表格
  4. 04处理公式兼容文件中的不可信数据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/paulrberg/agent-skills --skill spreadsheets

安装后在 Claude Code 中输入/spreadsheets确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
recipes.md
text-table-design.md
xlsx.md
scripts/
peek.py
profile.py
recalc.py

详细介绍

电子表格

处理表格数据时，确保数值准确、差异最小、按接收方范围处理数据、原子写入，并验证结构。

不变量

  1. 将精度敏感的金额保留为字符串，并使用 decimal.Decimal 或 DuckDB DECIMAL(38, 18) 进行计算，切勿使用二进制浮点数。
  2. 仅修改请求涉及的行、列、公式和格式。现有文件约定优先于本地默认设置。
  3. 对于新建的文本表格，优先使用 TSV、无 BOM 的 UTF-8、LF、末尾一个换行符、小写 snake_case 表头、ISO 日期、. 小数点和 - 表示空值。
  4. 读取未知文本表格时，使用可处理 BOM 的 UTF-8。绝不写入 BOM。
  5. 通过同级临时文件原子地原位写入，验证后再替换目标文件。
  6. 对以 =、+ 或 @ 开头的外部单元格进行转义。单独的 - 空值除外。可信作者数据中的公式前缀单元格只是观察结果，并不能证明存在注入。
  7. 将交易、银行、交易所和税务数据视为用户所有。若在内部 Agent 报告中具有实质帮助，可使用未脱敏样本。若要向公众或第三方披露，或用户提出要求，则使用 --redact-samples。

事实分析

从此 SKILL.md 解析辅助工具路径。选择转换工具之前，先分析未知数据：

uv run "<skill-dir>/scripts/profile.py" <file>

JSON 输出中的 schema_version 为 2。它会报告结构事实、表头质量、基数/统计信息（若 qsv 可用）、频率事实、公式前缀单元格、工作簿元数据和本地工具可用性。它不包含工具推荐，也不会根据唯一性推断标识符。请根据所请求的转换、数据来源、输出格式和保留要求选择工具。

仅当单元格来自外部或其他不可信来源，且将写入支持公式的使用方时，才使用 --external-data。使用此标记时，公式前缀单元格会影响 status。不使用该标记时，像 =SUM(...) 这样的合法公式仍只是事实观察，不会导致分析失败。

工具选择

需求工具
快速结构预览/验证uv run "<skill-dir>/scripts/peek.py" <file>
本地事实质量分析uv run "<skill-dir>/scripts/profile.py" <file>
计数、统计、频率、选择、去重qsv
联接、透视、聚合、转换设置 all_varchar = true 的 DuckDB
精确的自定义转换uv run Python，标准库 csv、decimal.Decimal
新建文本表格或有意更改架构首先阅读 references/text-table-design.md
任何 .xlsx/.xlsm 输入或输出首先阅读 references/xlsx.md
精确转换/验证方案仅在需要时阅读 references/recipes.md

在支持的情况下，优先使用 qsv --cache-threshold 0。若 qsv 标准输出必须保持为 TSV，请使用 -o out.tsv。否则，标准输出默认为 CSV。

工作流

  1. 对于新的文本表格或有意进行的架构变更，请阅读 references/text-table-design.md，并记录预期的表格接口及迁移范围。
  2. 使用 peek.py 检查。当基数、公式前缀、元数据或可用工具很重要时，添加 profile.py。对于不改变形状的编辑，保存 peek JSON。对于有意进行的行数或架构变更，记录预期宽度和不变量。
  3. 根据来源和输出上下文，判断带公式前缀的单元格是否存在风险。确定能够保留值和格式的最小工具。除非必要，否则避免使用 pandas。如果使用，请将每一列都加载为字符串。
  4. 以原子方式应用转换。对于允许存在合法重复行的幂等追加，使用多重集差异，而不是集合去重。
  5. 验证：
    • 形状不变：peek.py --strict --expect-like <before-report>。
    • 形状变更：peek.py --strict --expect-columns <n>，并验证任务特定的计数/键。
    • 自行编写的 house TSV：添加 --house。
    • 公式：运行 uv run "<skill-dir>/scripts/recalc.py" <file.xlsx>，并要求执行成功。
  6. 报告路径、行/列影响、验证结果，以及无法保留的任何工作簿功能。

对于面向用户的输出，只有在写入和所需验证均通过后，才以 ### 📊 Spreadsheet — ✅ updated 开头；对于只读操作，则以 ### 📊 Spreadsheet — 🔎 inspected, no files written 开头。所需验证失败时，使用 ### 📊 Spreadsheet — ⛔ not deliverable。仅在有助于实质性支持报告时才包含 profile JSON，并确保 JSON、单元格、表头、公式、路径、命令和诊断信息不添加装饰。

生成的财务产物

将生成的财务表格和报告视为输出。编辑前，确定其源输入，以及项目提供的验证和重新生成命令。只编辑源文件，验证后再重新生成受影响的输出。切勿手动编辑生成的表格或报告。除非原始行对任务有实质性帮助或用户要求提供，否则财务输出仅限于数量和文件引用。在将财务数据发送到 Agent 工作区之外之前，进行外部披露审查。

完成任务需要提供所请求的产物、明确的差异，并在适用时进行原子替换，同时提供结构和领域验证证据。对于新增或变更的文本表格架构，还必须定义表格接口，并完整迁移受影响的生产方、使用方、现有行、生成的产物和验证器。

评论

支持 Markdown