---
name: "skill_log_feishu_analysis_report"
description: "将日志分析结果整理为飞书分析报告，并输出可直接访问的稳定文档链接。"
version: "1.0.0"
author: "bytedance"
tags:
  - feishu
  - lark
  - report
  - log-analysis
categories:
  - documentation
  - analysis
---

# skill_log_feishu_analysis_report

用于把日志分析结论整理成飞书文档，并向用户返回可直接打开的文档地址。

## 前置要求

- 如果当前任务需要**先读取用户提供的飞书文档/设计图/白板**再生成报告，不要直接假设已有权限。
- 先执行 [skill_doc_lark_access_workflow](../skill_doc_lark_access_workflow/SKILL.md)，完成 `lark-cli` 用户态认证闭环与文档读取验证，再继续本技能。

## 核心要求

- 生成的飞书文档应放在用户自己的飞书云盘中，避免用户无权限打开。
- 返回给用户的文档链接必须是**标准永久链接**，只保留文档主地址。
- 输出链接前，必须检查是否混入了代码格式符号、临时登录参数或其它无关后缀。
- 如果用户明确给出`报告语言`、`模板文档`、`图片组织方式`，必须严格遵守，不得自行退化成默认模板或默认语言。
- 如果报告基于 AP+MD 联合分析，正文必须显式写出时间基准：`AP log = Beijing time`，`MD csv = UTC`，分析按 `AP = MD + 8h` 对齐。

## Plot 呈现要求

### 默认规则

如果分析流程里**已经生成了 Plot**（例如 HTML 图、PNG 子图、参数对比图），写飞书分析报告时，默认必须同时提供：

1. **摘要表**：给出关键指标的均值/频次/差异结论
2. **对应子图**：给出与摘要表同一参数的时间序列图或对比图

禁止只给表格不放图，也禁止只贴图不总结表格结论。
禁止把一张超长 `combined` 大图作为正文唯一主图。

### 推荐对应关系

- `RSRP` / `SNR` / `CQI` / `BLER` / `Tx Power` / `PathLoss` / `吞吐` 等关键参数，优先采用“**一张摘要表 + 若干对应子图**”的联合呈现方式。
- 表格负责沉淀结论：如均值、稳态窗口、频次、差异量、初步解读。
- 子图负责补充趋势：如时间走势、抖动、平台切换、瞬时尖峰、两机相对高低关系。
- 报告文字中应明确说明：图与表需要联合解读，避免只凭单一均值或单一截图下结论。

### 多波束/多分量参数的特殊要求

- 对 `RSRP_x`、`SNR_x` 这类多波束/多分量指标，**不能只保留单条平均线**。
- 应尽量保留全部有效分量（如 `RSRP_0`、`RSRP_1`、`SNR_0`、`SNR_1`...），必要时补充与主分量的差值图。
- 因为“有几个有效 beam”以及“主 beam 与其它 beam 的差异”本身就是分析结论的一部分，不能在出图时被平均掉。

### 无 Plot 时的处理

- 如果当前流程没有生成 Plot，报告里应优先给出摘要表，并明确说明“本次未生成对应 Plot”。
- 只要已有正式 Plot 产物可用，就应优先把对应子图同步写入报告，而不是只保留表格结论。

### HTML 报告入口要求

- 如果流程里已经生成 `nr_lte_multi_figure_subid_<id>_grid.html` 或其它正式交互式 HTML 报告，飞书文档中必须同时提供：
  1. 正文中的**直接跳转链接**
  2. 原始 HTML 文件附件
- 两者缺一不可。附件用于归档和复核，正文链接用于快速访问。

### 图片插入路径要求

- 使用 `lark-cli docs +media-insert` 时，必须先切换到图片所在目录，再使用相对路径如 `./figure.png`。
- 不要直接传绝对路径，否则会触发 `unsafe file path` 错误。

## 最小执行脚本

- 可选辅助脚本：

```bash
python3 /home/bytedance/disk4T/jieli/modem_proc_ext/skills/skill_log_workflow/sub_skills/skill_log_feishu_analysis_report/scripts/prepare_feishu_report_assets.py \
  --session-root <session_root> \
  [--template-url <docx_url>] \
  [--language zh|en]
```

- 该脚本不会直接写飞书，但会生成一份本地 `feishu_report_assets.md/json` 清单，约束：
  - 推荐单图目录
  - HTML 报告链接占位
  - 飞书正文插图顺序
  - 干净永久链接要求
- `skill_log_workflow` 主流程默认会在分析阶段后自动调用该脚本，产物固定在：
  - `<session_root>/analysis/feishu_report_assets.md`
  - `<session_root>/analysis/feishu_report_assets.json`
- 写飞书文档时，必须同时读取 `<session_root>/analysis/analysis_report.md` 和上述 asset manifest。`analysis_report.md` 是逐 filter 产物检查后的事实输入，asset manifest 是图片、HTML、附件和链接规则输入。

## 飞书文档链接输出规则

### 正确做法

只输出这种标准形式：

```text
https://bytedance.larkoffice.com/docx/<doc_token>
```

### 严禁携带的污染内容

- 反引号编码后的 `%60`（通常来自误把 `` `https://...` `` 中的结尾反引号写进真实链接）
- `?disposable_login_token=...` 这类一次性登录参数
- 其它浏览器临时跳转参数、鉴权参数、复制时混入的 Markdown/代码格式残留

### 原因说明

- `%60` 是反引号 `` ` `` 的 URL 编码；如果它出现在 `href` 里，说明真实链接被额外拼进了一个反引号。
- `disposable_login_token` 是临时访问参数，不是文档永久地址的一部分。
- 一旦把这些内容附加到文档链接后面，飞书会把它当成错误 URL，导致文档无法打开。

### 实战经验

如果用户反馈“手动删掉链接尾部某段内容后可以打开”，优先检查：

1. 链接末尾是否多了 `%60`
2. 是否附带了 `disposable_login_token`
3. 展示文本或超链接地址是否被写成空字符串、错误字符串或带格式污染的内容

### 自检清单

在把飞书文档链接发给用户前，必须确认：

- 链接是裸的标准文档 URL，而不是浏览器当前地址栏里的临时跳转链接
- 链接不包含 `%60`
- 链接不包含 `disposable_login_token`
- 链接文本与实际跳转地址一致

### 示例

正确：

```text
https://bytedance.larkoffice.com/docx/StLgd6q9poOeqsxM7ZTc0JPfnId
```

错误：

```text
https://bytedance.larkoffice.com/docx/StLgd6q9poOeqsxM7ZTc0JPfnId%60?disposable_login_token=...
```