pm-weekly-report-update

by romicboy

Install this Skill

curl -fsSL -o pm-weekly-report-update.zip https://skill.seembox.com/api/v1/skills/pm-weekly-report-update/download && unzip pm-weekly-report-update.zip

Download pm-weekly-report-update.zip

SKILL.md About

---
name: pm-weekly-report-update
description: 将项目经理提交的原始 Excel 周报数据同步到乐荐飞书表格。当项目经理发送周报 Excel 文件、要求更新周收入数据、核对周报数据时激活。
---

# PM Weekly Report Update

项目经理周报数据同步技能。

## 配置文件

目标飞书表格配置存储在 `env.vars` 下，**使用扁平 key**：

| 字段 | 说明 |
|------|------|
| `env.vars.pm_feishu_sheet_token` | 飞书表格 token |
| `env.vars.pm_feishu_sheet_sheet_id` | Sheet ID |
| `env.vars.pm_feishu_sheet_url` | 完整 URL |

> ⚠️ 注意：配置系统**不支持嵌套格式**（如 `pm_feishu_sheet.token`），写入时会自动拍扁为 `pm_feishu_sheet_token`。读取时必须使用上述扁平 key。

**读取配置**（无默认值，配置不存在时为空）：
```bash
openclaw config get env.vars.pm_feishu_sheet_token
openclaw config get env.vars.pm_feishu_sheet_sheet_id
openclaw config get env.vars.pm_feishu_sheet_url
```

**写入配置（每次只写一个字段）**：
```bash
openclaw config set env.vars.pm_feishu_sheet_token "你的token"
openclaw config set env.vars.pm_feishu_sheet_sheet_id "你的sheet_id"
openclaw config set env.vars.pm_feishu_sheet_url "完整URL"
```

**严禁使用覆盖整个 JSON 的方式写入配置。**

---

## 配置管理流程

### 流程 1：首次配置（无配置时）

1. 用户发送飞书表格 URL（如 `https://lejian.feishu.cn/wiki/RgS0wyoEdisDOCkXE0icPWBPnoe?sheet=NdGNM7`）
2. 从 URL 解析出 `token`、`sheet_id`、完整 `url`
3. 逐字段写入配置（每次一个字段）：
   ```bash
   openclaw config set env.vars.pm_feishu_sheet.token "RgS0wyoEdisDOCkXE0icPWBPnoe"
   openclaw config set env.vars.pm_feishu_sheet.sheet_id "NdGNM7"
   openclaw config set env.vars.pm_feishu_sheet.url "https://lejian.feishu.cn/wiki/RgS0wyoEdisDOCkXE0icPWBPnoe?sheet=NdGNM7"
   ```
4. 告知用户配置完成，可以继续发送 Excel

### 流程 2：已有配置时

1. 调用 `openclaw config get env.vars.pm_feishu_sheet.token` 读取 token
2. 配合 `sheet_id` 和 `url` 用于后续操作

### 流程 3：配置更新（用户发送新链接）

如果用户发送了新的飞书表格 URL，视为重新配置提示，重复流程1逐字段更新。

---

## URL 解析规则

飞书表格 URL 格式：
- Wiki 乐荐格式（带 `/wiki/`）：`https://*.feishu.cn/wiki/TOKEN?sheet=SHEET_ID`
  - `token` = `?sheet=` 前面的路径部分（如 `RgS0wyoEdisDOCkXE0icPWBPnoe`）
  - `sheet_id` = `?sheet=` 后面的部分（如 `NdGNM7`）
  - `url` = 原始 URL 整体
- 标准格式（带 `/sheets/`）：`https://feishu.cn/sheets/shtcnABC123`
  - `token` = 路径最后一段（如 `shtcnABC123`）
  - `sheet_id` = 从 URL 中找 `sheet=` 参数；无则调用 meta 获取第一个 sheet

**判断逻辑**：
- 链接含 `/wiki/` → Wiki 格式，直接解析 token + sheet_id
- 链接含 `/sheets/` → 标准格式，token 取路径最后一段，sheet_id 从参数读或调用 meta
- 既无 `/wiki/` 也无 `/sheets/` → 视为 token，sheet_id 待指定

---

## 安装后引导 ⚠️

**本技能依赖 `lejian-feishu-sheet`（飞书电子表格操作技能），必须先安装并配置才能正常工作。**

### 前置条件

1. **安装依赖技能**（如果尚未安装）：
   ```bash
   openclaw skills install lejian-feishu-sheet
   ```

2. **飞书应用权限**：你需要有一个乐荐的飞书应用，该应用需要开通「电子表格」编辑权限（`sheets:spreadsheet`），并将此飞书表格分享给该应用（编辑权限）。

3. **配置飞书凭证**：
   ```bash
   openclaw config set channels.feishu.appId "你的appId"
   openclaw config set channels.feishu.appSecret "你的appSecret"
   ```

4. **如需重置本技能配置**（只清除乐荐飞书表格配置，保留其他 env.vars）：
   ```bash
   openclaw config unset env.vars.pm_feishu_sheet_token
   openclaw config unset env.vars.pm_feishu_sheet_sheet_id
   openclaw config unset env.vars.pm_feishu_sheet_url
   ```

⚠️ **不要**使用 `openclaw config unset env.vars`（会清除所有 env.vars，影响其他技能）。

### 首次配置

配置完成后，发一次飞书表格链接（如 `https://lejian.feishu.cn/wiki/RgS0wyoEdisDOCkXE0icPWBPnoe?sheet=NdGNM7`），技能会自动解析并保存。

---

## 字段枚举与映射关系

### Excel 列定义

| Excel列索引 | Python变量名 | 飞书列对应 | 说明 |
|------------|------------|----------|------|
| B（第1索引） | `channel_name` | 对应飞书G列 | 客户名称（规则2使用） |
| C（第2索引） | `ops_channel_name` | 对应飞书**X列**（**重要！**） | **OPS渠道单位名称**（规则1使用） |
| F（第5索引） | `pe` | 对应飞书E列 | 项目经理 |
| H（第7索引） | `supply_price` | — | 渠道供货价（要同步的周收入） |

### 飞书表格列定义

| 飞书列 | 列名 | 说明 |
|--------|------|------|
| B | 区域 | |
| C | 总监 | |
| D | 销售 | |
| E | PM（项目经理） | 匹配 Excel `pe` |
| F | 项目唯一标识 | |
| G | 项目名称 | 匹配 Excel `channel_name` |
| **X** | **OPS渠道单位名称** | **匹配 Excel `ops_channel_name`（规则1）** |
| CS~CW | 周收入列 | 第1-5周数据 |

> ⚠️ **关键映射**：
> - Excel `ops_channel_name`（C列）→ 飞书 **X列**（不是G列）
> - Excel `channel_name`（B列）→ 飞书 **G列**（规则2使用）

### 匹配字段速查

| 规则 | Excel字段 | 飞书字段 | 优先级 |
|------|----------|---------|--------|
| 规则1 | `ops_channel_name`（C列） | X列 | 最高 |
| 规则2 | `channel_name`（B列）+ `pe`（F列） | G列 + E列 | 降级 |

---

## 飞书表格结构

| 飞书列 | 内容 | 说明 |
|--------|------|------|
| B | 区域 | |
| C | 总监 | |
| D | 销售 | |
| E | **PM（项目经理）** | ← 匹配 Excel F列 |
| F | 项目唯一标识 | |
| G | **项目名称** | ← 匹配 Excel B列 |
| X | **OPS渠道单位名称** | ← **匹配 Excel C列（重要！）** |
| CS | 第1周（4/1-4/5） | |
| CT | 第2周（4/6-4/12） | |
| CU | 第3周（4/13-4/19） | |
| CV | 第4周（4/20-4/26） | |
| CW | 第5周（4/27-4/30） | |

数据从第3行开始。第2行是表头。

## 匹配规则

详见 `references/match-rules.md`。

**优先级：**
1. **规则1（最高）**：Excel `ops_channel_name`（C列）== 飞书 **X列**（OPS渠道单位名称）→ 直接命中
2. **规则2（降级）**：`channel_name` + `pe` 联合定位飞书 G列+E列，按 2.1精确 → 2.2前缀剥离 → 2.3双向包含 依次尝试

**别名支持：** 系统支持项目别名映射，例如 `享道出行`/`赛可出行` → `享道汽车`。别名在所有规则中均生效。

**匹配失败处理：** 规则1失败 → 降级规则2；规则2某一子级失败 → 降级下一级；全部失败 → 报错

**报错信息：** `未找到项目 [channel_name] + PM [pe] 的行，请确认该项目的周报已添加到此表格`

---

## 原始 Excel 格式

Sheet 名：UUID 风格（如 `d2721d4c-95a5-4d8c-bc12-668050f`）

| 列索引 | Python变量名 | 列名 | 说明 |
|--------|------------|------|------|
| B（第1索引） | `channel_name` | 客户名称 | 规则2使用 |
| C（第2索引） | `ops_channel_name` | OPS渠道单位名称 | **规则1匹配字段（最高优先级）** |
| F（第5索引） | `pe` | 项目经理 | 匹配飞书E列 |
| H（第7索引） | `supply_price` | 渠道供货价 | **= 要同步的周收入** |

> ⚠️ openpyxl 的 row 数组是 0-based 索引（Python list）：A=index0, B=index1, ..., H=index7

## 同步流程

### 第一步：检查配置

调用 `openclaw config get env.vars.pm_feishu_sheet.token` 读取配置。

- **有配置** → 继续
- **无配置** → 请用户发送飞书表格 URL，完成配置后继续

### 第二步：解析文件名判断周次

文件名格式：`xxx_2026_0420-0426---uuid.xlsx`

| 日期区间（MMDD） | 对应列 |
|----------|--------|
| 0401-0405 | CS |
| 0406-0412 | CT |
| 0413-0419 | CU |
| 0420-0426 | CV |
| 0427-0430 | CW |

从文件名提取 `MMDD-MMDD` 区间，匹配上表确定目标列。

### 第三步：读取 Excel 数据

读取 Sheet 1，从第2行起，提取：
- `channel_name`（B列）
- `ops_channel_name`（C列）
- `pe`（F列）
- `supply_price`（H列）

### 第四步：匹配项目行

按 `references/match-rules.md` 中的规则依次尝试匹配：
1. **规则1**：Excel `ops_channel_name`（C列） == 飞书 **X列**（最高优先级）
2. **规则2**：`channel_name` + `pe` 联合定位飞书 G列+E列（2.1精确 → 2.2前缀剥离 → 2.3双向包含）

全部失败 → 报错。

### 第五步：写入飞书表格

使用 `lejian-feishu-sheet` 的 write 命令，token/sheet_id 从配置读取：
```bash
TOKEN=$(openclaw config get env.vars.pm_feishu_sheet.token)
SHEET_ID=$(openclaw config get env.vars.pm_feishu_sheet.sheet_id)
OPENCLAW_CONFIG=~/workspace/agent/openclaw.json \
~/workspace/agent/skills/lejian-feishu-sheet/scripts/feishu-sheet.sh \
write "$TOKEN" "${SHEET_ID}!CV5:CV5" '[[159468.66]]'
```

## 输出格式要求

### 执行结果输出（JSON）

脚本执行后输出结构化 JSON，包含以下字段：

```json
{
  "week_col": "CV",        // 本次更新的周次列
  "updates": [             // 成功匹配的记录列表（包含写入和跳过）
    {
      "channel": "某科技公司",           // Excel channel_name（B列）
      "ops_channel_name": "2026某科技公司", // Excel OPS渠道单位名称（C列）
      "pe": "张三",               // PM（项目经理）
      "row": 17,                    // 飞书表格目标行号
      "col": "CV",                  // 周次列
      "value": 35792,               // 本次写入的供货价
      "rule": "规则1",              // 命中的匹配规则
      "status": "ok"                // 状态：ok=成功写入, skipped=跳过
    }
  ],
  "errors": [              // 匹配失败的记录列表
    "未找到项目 [某渠道]（2025某渠道名）+ PM [李四] 的行"
  ]
}
```

**输出要求：**
1. `week_col` 必须标注本次更新的周次列（如 CV=第4周）
2. `updates` 中的每条记录必须包含：channel、ops_channel_name、pe、row、col、value、rule
3. `errors` 中每条错误信息必须包含：项目名（channel_name）、OPS渠道单位名称（ops_channel_name）和 PM
4. 匹配规则名称需标准化：规则1、规则2.1、规则2.2、规则2.3

---

## 错误处理

| 情况 | 处理 |
|------|------|
| 无飞书表格配置 | 请用户发送飞书表格 URL，分析后写入配置 |
| 文件名无法解析周次 | 报错：「无法识别文件名中的日期，请确认格式如 xxx_2026_0420-0426---uuid.xlsx」 |
| 项目行未找到 | 报错：「未找到项目 [某公司] + PM [某PM] 的行，请确认该项目的周报已添加到此表格」 |
| 渠道供货价为0或空 | 跳过该行（不写入），并在结果中说明「[某公司] 无渠道供货价数据（0），已跳过」 |
| 找到多个匹配行 | 报错：「匹配到多行，请检查数据：[行号1] [行号2]」 |

## 注意事项

- 每次只更新已有行，不新建行
- 有任何一行匹配失败，整体报错，不部分更新
- 使用乐荐飞书凭证（`channels.feishu.appId` / `channels.feishu.appSecret`）
- 写入前**展示将要更新的内容**，确认后执行

_meta.json Metadata

{
  "ownerId": "kn72y8ps3443dha8d3y6zqf6sx85k1t2",
  "publishedAt": 1777885039087,
  "slug": "pm-weekly-report-update",
  "version": "1.1.9"
}