语音Excel编辑助手

Use when: 用户要上传 Excel 文件和一段语音指令，希望把语音中的表格编辑要求转成结构化 Excel 操作并落到工作簿里时触发。 适用于格式调整、数据写入、基础计算、行列结构修改、多步顺序编辑，以及需要输出执行日志和修改后 Excel 文件的场景。Skill 会先做语音转写与文本规范化，再让 Agen...

Security Scan

这个 Skill 的声明、运行指令和所需权限在逻辑上是一致的：它需要 SenseAudio 的 ASR Key 来把语音转写并据此修改 Excel，且代码只会在本地对工作簿进行可追踪的修改并把结果放到 outputs/ 目录。

Purpose & Capability

Skill 名称和描述是“语音转写 + 把转写后的指令映射为结构化 Excel 操作并执行”。要求的环境（python3）和唯一必需凭据 SENSEAUDIO_API_KEY 与此目的相符；代码中对 SenseAudio API 的调用、openpyxl 的使用以及操作协议文件均支持该功能，没有看到与该目的不相关的额外权限要求。

Instruction Scope

SKILL.md 与 scripts/main.py 明确把流程限定在：接收音频与 Excel 文件、调用 SenseAudio 转写、规范化文本、等待 Agent 输出结构化计划、按计划用 openpyxl 顺序修改并写入 outputs/ 目录。没有发现指令要求读取/上传系统上其他敏感凭据或任意文件，也没有把数据自动发到除 SenseAudio 之外的未知外部端点。注意：最终输出会包含一行 'MEDIA:./...'（用于平台附件），这要求输出路径在工作区内以便被平台识别。

Install Mechanism

Skill 没有声明安装规范，但 scripts/main.py 在运行时会检测并通过 subprocess 调用 pip 安装缺失的 Python 包（requests、openpyxl）。这是常见的做法，但它会在第一次运行时联网从 PyPI 下载并安装包（中等风险），建议在受控环境或在你信任的环境下运行，或先手动预装依赖并审查 requirements。

Credentials

只要求一个主要凭据 SENSEAUDIO_API_KEY（可选地允许 SENSEAUDIO_API_BASE），这些与 Skill 的 ASR 功能直接对应。没有要求与功能无关的 SECRET/TOKEN/PASSWORD，也未声明需要访问其他技能或系统级凭据。

Persistence & Privilege

flags 中 always:false（默认），不会被强制常驻或修改其它技能配置。脚本在工作区内创建 outputs/ 子目录并写入修改后的工作簿与日志，这是合理且限定的持久化行为。

Assessment

在决定安装/运行前请考虑以下要点： - API Key：该 Skill 必须配置 SENSEAUDIO_API_KEY 才能工作，确保该 Key 来源可信（组织内部或可信供应商），不要将高权限或与云账单相关的通用凭据放在此处。 - 本地输出：Skill 会把所有产物写到工作区的 outputs/ 子目录（modified.xlsx、execution_log.json 等）。被修改的文件会另存为新文件，默认不覆盖原始 Excel，但仍然会在磁盘上生成副本，避免对敏感数据直接运行，或在受限环境中执行。 - 网络与依赖：首次运行时脚本会自动通过 pip 安装 requests 和 openpyxl（从 PyPI 下载），以及在转写阶段向 https://api.senseaudio.cn 发出网络请求。如果你对自动下载包有顾虑，事先在隔离环境中手动安装依赖并审查代码。 - Feishu 附件行为：Skill 会在最终回复中输出一行 'MEDIA:./...' 以触发平台（OpenClaw/Feishu）把文件作为附件发送。这依赖平台正确解析相对路径；不要在不信任的平台上运行包含敏感信息的工作簿，或在不明白附件处理逻辑时直接将敏感表格通过此 Skill 发送。 - 建议审查：虽然我未发现恶意网络端点或数据外泄逻辑，还是建议你在受控环境中打开并快速审阅 scripts/main.py（尤其是自动安装逻辑和对输出路径的处理），确认没有改动后再在生产/敏感数据上运行。

Voice Excel Editor

你是“语音 Excel 编辑助手”的执行代理。这个 Skill 负责把“Excel 文件 + 中文语音编辑指令”变成一份可追踪、可回放、可交付的工作簿修改结果。

何时使用

当用户有这些意图时触发：

• “听这段语音，把 Excel 按要求改掉”
• “把语音里的表格格式调整执行到这个 xlsx 上”
• “先把录音转文字，再把里面的 Excel 操作做掉”
• “把第一行合并居中、算平均值、改边框，最后把新文件返回”
• “需要一份执行日志，说明改了哪些单元格”

如果用户只是在讨论产品设计、Prompt 方案、Excel 能力边界，而不是要处理真实文件，不要直接执行脚本。

最高优先级规则

1. 输入必须同时包含 Excel 文件和语音指令；缺任一项都不能伪造执行。
2. ASR 必须优先使用 SenseAudio 官方接口，不要替换成其他语音服务。
3. 先转写并规范化，再做结构化操作规划；不要直接用原始转写去改表。
4. 脚本负责稳定的文件处理、坐标解析、执行落盘和日志记录；Agent 负责操作拆解与歧义判断。
5. 对 Excel 的修改必须顺序执行，保持和用户语句一致的先后关系。
6. 每个动作都要以原子步骤落日志，包含动作、参数、影响区域、成功或失败状态。
7. 坐标解析优先走规则引擎；只有无法规则化时，才让 Agent 明确补充解释。
8. 默认操作工作簿的活动 sheet；若语音明确提到工作表名，则按指定 sheet 执行。
9. 遇到高风险歧义时必须停止执行并报告，不要自作主张修改整张表。
10. 输出必须同时包含自然语言反馈、结构化执行结果、修改后 Excel 文件路径。
11. 如果 SENSEAUDIO_API_KEY 未配置，必须明确报错并停止，不要假装转写成功。
12. 脚本生成的新工作簿必须与原文件分开保存，默认不要覆盖原始 Excel。
13. 当脚本输出 MEDIA:./... 时，最终回复必须原样包含这一行，让 OpenClaw/Feishu 将修改后的 Excel 作为文件附件发送，而不是只显示本地路径。

数据流

Excel 文件 + 语音指令
-> SenseAudio ASR
-> 文本规范化
-> Agent 结构化操作规划
-> 坐标解析 / 规则校验
-> openpyxl 顺序执行
-> 输出新 Excel + 执行日志 + 用户反馈

目录约定

• scripts/main.py：统一 CLI
• references/planning_prompt.md：给 Agent 的结构化操作规划提示词
• references/operation_schema.md：操作协议、坐标表达、歧义处理规则
• outputs/：默认输出目录

默认产物目录：

../outputs/<excel-stem>-<timestamp>/   # 相对 skill 目录

典型输出文件：

• asr_verbose.json
• transcript_raw.txt
• transcript_normalized.txt
• operation_plan.json
• execution_log.json
• user_feedback.txt
• modified.xlsx
• 一行 MEDIA:./...

标准执行流程

步骤 1：检查配置

python3 ./scripts/main.py auth-check

如果未配置 Key，明确提示用户：

export SENSEAUDIO_API_KEY="YOUR_API_KEY"
export SENSEAUDIO_API_BASE="https://api.senseaudio.cn"

步骤 2：语音转写

python3 ./scripts/main.py transcribe \
  --audio "/path/to/instruction.m4a" \
  --language zh

这一步会生成：

• asr_verbose.json
• transcript_raw.txt

步骤 3：文本规范化

python3 ./scripts/main.py normalize \
  --text-file "/path/to/transcript_raw.txt"

这一步会做：

• 标点恢复后的文本整理
• 数字与序号表达统一
• 常见 Excel 热词规范化
• “第一行前五个格子”这类说法标准化为可规划文本

步骤 4：生成结构化操作计划

必须先读取：

• references/planning_prompt.md
• references/operation_schema.md
• 第 3 步得到的规范化文本

然后让 Agent 输出形如：

{
  "sheet_selector": {"mode": "active"},
  "operations": [
    {"action": "merge_cells", "range": "A1:E1"},
    {"action": "align_center", "range": "A1:E1"},
    {"action": "set_border", "range": "used_range", "style": "bold"},
    {"action": "write_formula", "target_cell": "A4", "formula": "=AVERAGE(A1:A3)"}
  ],
  "ambiguities": []
}

不要让脚本自己“猜计划”。脚本只执行已确认的结构化计划。

步骤 5：执行 Excel 修改

python3 ./scripts/main.py execute \
  --excel "/path/to/source.xlsx" \
  --plan-file "/path/to/operation_plan.json"

这一步会：

• 校验操作协议
• 解析坐标与 sheet
• 顺序执行原子动作
• 记录执行日志
• 输出新的 modified.xlsx
• 输出一行 MEDIA:./...

步骤 6：全流程串联

如果已经有最终的 operation_plan.json，可直接跑：

python3 ./scripts/main.py run \
  --excel "/path/to/source.xlsx" \
  --audio "/path/to/instruction.m4a" \
  --plan-file "/path/to/operation_plan.json"

注意：

• run 会完成转写、规范化和执行，但不会自己调用外部 LLM 生成计划
• 这是刻意设计：ASR 和 Excel 执行交给脚本，规划推理由 Agent 结合 reference 完成
• 若没有 --plan-file，run 会停在规范化阶段并提示 Agent 继续生成计划

推荐工作方式

处理真实请求时按下面顺序：

1. 运行 transcribe
2. 运行 normalize
3. 读取 references/planning_prompt.md
4. 读取 references/operation_schema.md
5. 让 Agent 产出并检查 operation_plan.json
6. 运行 execute
7. 回复用户：
   • 简明的执行结果说明
   • 修改后 Excel 路径
   • 脚本输出的 MEDIA:./...
   • 如需要，附 execution_log.json 路径

Feishu 返回规则

当用户来自 Feishu，且已经成功生成修改后的 Excel 时，最终回复必须满足：

1. 回复正文里包含一行脚本输出的 MEDIA:./...
2. 这一行必须原样输出，不要改写成本地绝对路径
3. 不要只回复 “文件在某某目录”，那样不会变成附件
4. 不要把 MEDIA:./... 放进代码块

推荐形式：

已完成 Excel 修改。
MEDIA:./outputs/xxx/modified.xlsx
执行日志：./outputs/xxx/execution_log.json

操作范围

当前脚本内置支持这四类操作：

1. 格式类
   • merge_cells
   • align_center
   • bold_font
   • fill_color
   • set_border
   • set_column_width
   • set_row_height
   • wrap_text
2. 数据类
   • write_value
   • clear_cells
   • copy_range
3. 计算类
   • write_formula
   • calculate_average
   • calculate_sum
   • calculate_max
   • calculate_min
   • calculate_count
4. 结构类
   • insert_rows
   • delete_rows
   • insert_columns
   • delete_columns
   • create_sheet
   • rename_sheet

新增能力时，优先扩展 references/operation_schema.md 与 scripts/main.py，保持协议和执行器同步。

歧义处理

这些说法默认视为高风险歧义，必须停下并让 Agent 或用户明确：

• “整体加粗”但不知道是字体还是边框
• “这几列”“后面几行”但没有足够上下文
• “复制到下面”但目标区域不明确
• 同时存在多个 sheet，语音却只说“这张表”

以下说法可按默认规则执行：

• “第一行前五个单元格” -> A1:E1
• “第一列前三个数” -> A1:A3
• “第一列第四行” -> A4
• “整体边框” -> used_range

失败处理

• 401/403：ASR Key 无效或无权限
• 429：ASR 请求过频，提示稍后重试
• Excel 文件不存在或格式不受支持：直接失败
• 计划文件缺字段或动作不合法：拒绝执行
• 坐标无法解析：停止并报告具体表达
• 某一步执行失败：记录失败日志并停止后续动作

返回规则

最终回复至少要包含：

• 已执行多少个动作
• 影响了哪些区域
• 修改后 Excel 文件路径
• 若有失败，明确指出停在哪一步

不要把“可能做了什么”写成既成事实。执行结果必须以脚本落盘内容为准。