---
slug: "sheet-process"
source_type: "clawhub"
source_url: "https://clawhub.ai/skills/sheet-process"
repo: ""
source_file: "description"
---
---
name: sheet-process
description: 腾讯文档智能表格通用筛选处理工具。支持两种模式：工作流模式（一键输出JSON，适合作为下游AI节点输入）和原子模式（引导式问答，可自定义输出格式）。触发词：sheet-process（工作流）、表格筛选/表格处理/表格过滤（原子模式）。当用户在腾讯文档智能表格中需要按列进行多条件筛选时使用。
---

# sheet-process — 智能表格通用筛选处理 Skill

## 概述

将腾讯文档智能表格筛选功能抽象为可编排的工作流节点。支持两种模式：

| 模式 | 触发词 | 优先级 | 输出 |
|------|--------|--------|------|
| **工作流模式** | `sheet-process` | 最高 | 自动输出 JSON（供下游 AI 节点消费） |
| **原子模式** | `表格筛选`、`表格处理`、`表格过滤` | 次高 | 引导式问答，输出格式由用户决定 |

若两种模式的触发词同时出现，工作流模式优先。

---

## 模式判定规则（执行任何操作前必须先判定）

**当 Skill 被触发时，首先读取用户消息中的触发词：**

```
IF 用户消息包含 "sheet-process" →
    模式 = "workflow"
ELSE IF 用户消息包含 "表格筛选" / "表格处理" / "表格过滤" →
    模式 = "atomic"
ELSE →
    模式 = "atomic"（默认）
```

**注意：** 即使模式已确定，也可以从对话上下文中获取已有的 file_id。如果用户消息中包含 `@tdoc#xxx` 引用，提取 file_id 备用。

---

## 交互流程（严格按此顺序执行，每步必须等待用户应答后继续）

### 第 0 步：模式确认

**仅在工作流模式下执行。** 向用户展示：

```
🔄 工作流模式已激活

我将通过以下步骤完成智能表格筛选：

  ① 确认腾讯文档连接状态
  ② 选择要筛选的工作表
  ③ 填写筛选参数
  ④ 输出 JSON 结果

现在开始 →
```

**在原子模式下：** 直接进入第 1 步，不展示模式说明。

---

### 第 1 步：确认连接状态

向用户提问：

```
📋 第 1 步：确认环境

是否已在 WorkBuddy 中连接好腾讯文档，并导入需要处理的表格？

  · 若已完成 → 回复「是」
  · 若未完成 → 请先在连接器管理中连接「腾讯文档」，在对话中 @ 引用需要处理的表格
```

**等待用户回复。** 规则：
- 用户回复「是」或含义相同的肯定 → 将 input1 记为 "是"，进入第 2 步
- 用户无输入 → 继续等待
- 其他情况 → 重复第 1 步（提示用户先连接并导入）

---

### 第 2 步：选择工作表

**前提：** 从对话上下文中提取 file_id（来自 `@tdoc#xxx` 引用，或用户直接提供的表格链接/ID）。

若无法提取 file_id，询问用户：

```
请提供要处理的腾讯文档链接，或使用 @ 引用该文档。
```

拿到 file_id 后，调用 `smartsheet.list_tables` 获取所有工作表列表。

**只有一个工作表：**
自动选中该工作表，将 input2 记为该 sheet 标题，直接进入第 3 步。向用户提示：

```
📋 该文档只有一个工作表：「{sheet_title}」，已自动选中。
```

**有多个工作表：**
列出所有工作表并询问：

```
📋 该文档包含以下工作表：

  1. {sheet_1_title}
  2. {sheet_2_title}
  3. {sheet_3_title}
  ...

你想对哪一个 sheet 进行筛选？请回复这个 sheet 的名称（完整标题或序号均可）。
```

**等待用户回复。** 规则：
- 用户回复的工作表名称存在于列表中 → 将 input2 记为该标题，进入第 3 步
- 用户无输入 → 继续等待
- 回复名称不存在 → 重复第 2 步（提示用户重新选择）

---

### 第 3 步：填写筛选参数

**进入本步后，先调用 `smartsheet.list_fields` 加载该工作表的列信息（含列名和列序号 1-based），然后输出以下内容：**

```
📝 第 3 步：填写筛选参数

请参考示例及说明，在「用户输入」行填写表格，然后发送给我。

┌──────────┬──────────────────────────────────┬──────────────────────────────────────────────────┬──────────────────────────────────────────────────┬──────────────────────────────┐
│          │ 筛选列                           │ 关键词（#分隔）                                   │ 取并集（Y/N）                                    │ 结果输出哪些列               │
├──────────┼──────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────┤
│ 示例     │ [1, 2]                           │ ["关键词1#关键词2", "关键词3#关键词4#关键词5"]     │ [true, false]                                    │ [2, 3, 5]                    │
├──────────┼──────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────┤
│ 说明     │ 要筛选的第一列、第二列           │ 第一列筛选关键词1、关键词2；                      │ 第一列取交集（同时含关键词1和关键词2）；         │ 输出原有表格第2、3、5列      │
│          │ （填列序号或列标题）              │ 第二列筛选关键词3、4、5                           │ 第二列取并集（含任一关键词即命中）               │ （填列序号或列标题）         │
├──────────┼──────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────────────────────────┼──────────────────────────────┤
│ 用户输入 │                                  │                                                  │                                                  │                              │
└──────────┴──────────────────────────────────┴──────────────────────────────────────────────────┴──────────────────────────────────────────────────┴──────────────────────────────┘

💡 当前工作表「{sheet_title}」的列信息：

{列出所有列，格式：序号. 列标题 [类型]}

💡 提示：
  · 筛选列支持列序号（如 7）或列标题（如 "招聘岗位"）
  · 多个筛选列用逗号分隔，写在 [] 内（如 [7, 3] 或 ["招聘岗位", "城市"]）
  · 关键词用 # 分隔同列多个关键词（如 "前端#全栈#开发"）
  · 取并集 Y = 命中任一即保留，N = 全部命中才保留
  · 输出列同样支持序号或标题
```

**等待用户回复。** 解析规则：

用户需填写「用户输入」行的四列内容。解析方式：

1. **筛选列**：去掉外层 `[]`，按逗号拆分为列表，每项尝试转 int，失败则保留字符串
2. **关键词**：去掉外层 `[]`，按 `", "` 拆分为各组，每组去掉引号后按 `#` 拆分关键词
3. **取并集**：去掉外层 `[]`，按逗号拆分，`true`/`Y`/`y` → True，`false`/`N`/`n` → False
4. **输出列**：去掉外层 `[]`，按逗号拆分为列表，每项尝试转 int，失败则保留字符串

**格式校验：**
- 四项都必须填写，不能为空
- 筛选列数量 = 关键词组数 = 取并集数量（长度必须一致）
- 若格式不符 → 展示错误提示，重复第 3 步

**格式正确后：** 回显解析结果确认：

```
🔍 解析结果确认：

  筛选列：{filter_columns}
  关键词：{keywords}
  列内取并集：{union_mode}
  输出列：{return_columns}

  确认无误？回复「确认」执行筛选。
```

用户确认后进入第 4 步。

---

### 第 4 步：执行筛选并输出

调用 `scripts/smartsheet_filter.py` 执行筛选：

```python
import sys
sys.path.insert(0, '/Users/liuliu/.workbuddy/skills/sheet-process/scripts')
from smartsheet_filter import SmartsheetFilter

sf = SmartsheetFilter(file_id=file_id, sheet_title=sheet_title)
```

#### 工作流模式输出（直接输出 JSON）

```python
result = sf.filter_to_json(
    filter_columns=filter_cols,
    keywords=keywords,
    union_mode=union_mode,
    return_columns=return_cols,
    column_combine="intersection",
    output_path=output_json_path,
)
```

输出 JSON 文件到当前工作区，并展示摘要：

```
✅ 筛选完成

  工作表：{sheet_title}
  总记录数：{total}
  匹配记录数：{matched}
  筛选条件：{filter_summary}
  输出文件：{json_path}

JSON 结构化输出已就绪，可作为下游节点输入。
```

#### 原子模式输出（询问用户输出格式）

```
📋 第 4 步：选择输出格式

是否以 JSON 格式输出最终结果？

  · JSON 格式文件有利于 AI 读取，便于作为下一个工作流节点的输入
  · 也可以选择 HTML 可视表格、Excel 等格式

  若以 JSON 格式输出 → 回复「是」
  若以其他格式输出 → 回复您期望的输出格式（如 HTML、Excel）
```

**等待用户回复。** 规则：
- 用户回复「是」→ 同工作流模式，输出 JSON
- 用户无输入 → 继续等待
- 用户回复其他格式（如「HTML」）→ 调用对应的输出方法，使用 `sf.filter_to_html()` 等方法
- 无论如���，最终都将输出文件通过 `present_files` 展示给用户

---

## 参数映射速查

用户模板填入的内容与 smartsheet_filter.py 参数的映射关系：

| 模板字段 | 用户输入示例 | smartsheet_filter.py 参数 |
|----------|-------------|--------------------------|
| 筛选列 | `[7]` 或 `["招聘岗位"]` | `filter_columns` |
| 关键词 | `["前端#全栈#开发#研发#软件"]` | `keywords` → `[["前端","全栈","开发","研发","软件"]]` |
| 取并集 | `[true]` 或 `[Y]` | `union_mode` |
| 输出列 | `[1, 2]` 或 `["招聘企业","投递链接"]` | `return_columns` |

**说明：** 本 Skill 暂不支持跨列组合方式配置，固定使用 `column_combine="intersection"`（所有筛选列都满足才保留）。如需更灵活的组合，请使用 `smartsheet-filter` Skill。

---

## 自然语言快速模式

如果用户在第 3 步直接用自然语言描述筛选需求（而非填写模板表格），按以下映射自动转换：

| 用户表述 | 映射 |
|----------|------|
| 「筛选 A 列含 X 或 Y 或 Z」 | filter_columns=[A]，keywords=[[X,Y,Z]]，union_mode=[True] |
| 「筛选 A 列同时含 X 和 Y」 | filter_columns=[A]，keywords=[[X,Y]]，union_mode=[False] |
| 「返回 B 列和 C 列」 | return_columns=[B, C] |
| 列用标题描述（如「招聘岗位」） | 直接使用列标题字符串 |
| 列用序号描述（如「第7列」） | 使用整数索引 |

快速模式下仍需在第 3 步回显解析结果，确认后再执行。

---

## 依赖

- `scripts/smartsheet_filter.py` — 核心筛选引擎（从 smartsheet-filter skill 移植）
- 需要 WorkBuddy 已连接「腾讯文档」连接器
- 依赖 `/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/resources/builtin-plugins/tencent-docs-plugin/skills/tencent-docs/tencentdocs.py`