Insights 中文报告生成器

生成或翻译 Claude Code 的 insights HTML 报告为中文。

核心优势

✅ 避免嵌套会话问题：使用 Task 工具而非 subprocess 调用 claude 命令
✅ 避免 JSON 转义问题：使用 TSV 格式而非 JSON 存储翻译
✅ 修复索引不一致问题：统一使用 BeautifulSoup，通过原文匹配而非索引
✅ 简化流程：单一脚本完成提取、合并流程
✅ 自动清理：翻译完成后自动删除临时 TSV 文件
✅ 自动检查：检测报告年龄，过期时提示用户

执行流程

步骤 0: 智能判断与报告检查

检查源文件：

ls -lh ~/.claude/usage-data/report.html

检查报告年龄：
- 自动检查报告是否在 3 天内生成
- 如果报告过期：提示用户运行 /insights 生成新报告，结束技能
判断用户意图：
- 如果用户说"生成"、"新建"或文件不存在 → 提示运行 /insights
- 如果用户说"翻译"、"转换"且文件存在且新鲜 → 继续翻译步骤

步骤 1: 提取文本块

运行提取脚本：

python3 ~/.claude/skills/insights-zh/scripts/translate.py

脚本会：

✅ 检查报告年龄（3 天内为新鲜）
✅ 提取 HTML 中的所有文本块
✅ 保存为 TSV 格式到 /tmp/insights_blocks.tsv
✅ 显示翻译提示

输出示例：

============================================================
Insights 报告翻译工具
============================================================

[1/4] 检查报告状态...
✅ 报告新鲜（0 天前生成）

[2/4] 提取文本块...
✅ 提取了 311 个文本块，共 15756 字符
✅ 已保存到 /tmp/insights_blocks.tsv

[3/4] 等待翻译...
请使用 Task 工具翻译 /tmp/insights_blocks.tsv

步骤 2: 使用 Task 工具翻译

重要：不要在当前会话中直接处理 TSV 文件，而是启动 Task 子代理：

请将 /tmp/insights_blocks.tsv 翻译为中文。

TSV 格式说明：
- 第一列：原文（保留不变）
- 第二列：译文（请填写翻译）

要求：
1. 只翻译第二列（当前为空）
2. 保持 TSV 格式不变
3. 保留所有专有名词（Claude Code、GitHub、Python 等）
4. 保留技术术语（TUI、API、HTML、CSS 等）
5. 翻译中不要使用任何引号（中文或英文），用其他方式表达
6. 完成后保存回原文件

为什么使用 Task 工具？

避免嵌套会话：原方案使用 subprocess.run(['claude', 'prompt', ...]) 会导致错误
```
Error: Claude Code cannot be launched inside another Claude Code session
```
Task 工具启动独立子代理，完全隔离，无此限制

步骤 3: 合并翻译结果

翻译完成后，再次运行脚本：

python3 ~/.claude/skills/insights-zh/scripts/translate.py

脚本会自动：

✅ 加载 TSV 中的翻译
✅ 使用 BeautifulSoup 合并到 HTML
✅ 保存为 report-zh.html
✅ 在浏览器中打开

输出示例：

[4/4] 合并翻译...
✅ 生成完成: ./report-zh.html
   替换了 305 个文本节点

============================================================
✅ 翻译完成！
输出文件: /path/to/report-zh.html
============================================================

翻译规则

必须保留不翻译：

HTML 标签和属性名（class、id、data-*、style、href 等）
HTML 属性值（class="container"、id="header" 等）
CSS 类名和 ID
代码块中的技术术语和代码片段
专有名词：Claude Code、GitHub、Twitter、Python、Rust 等
技术术语：TUI、API、HTML、CSS、JSON、SSH 等

需要翻译：

所有用户可见的文本内容
页面标题、标题、段落文本
按钮文本、链接文本（href 保留，链接文本翻译）
表格内容、列表项文本

翻译原则：

保持 HTML 结构完全不变
保持所有标签和属性完整
只翻译文本节点内容
确保翻译后的 HTML 语法正确
技术术语保持一致性
避免使用引号：TSV 格式下，中文引号会破坏解析，用其他表达方式

错误处理

报告不存在

如果 ~/.claude/usage-data/report.html 不存在：

提示用户运行 /insights 命令生成报告
支持指定自定义路径：--path <your-report.html>

报告过期

如果报告超过 3 天未更新：

提示用户报告已过期及过期天数
建议运行 /insights 生成最新报告
可使用 --force 参数强制翻译过期报告

嵌套会话错误

如果看到错误：

Error: Claude Code cannot be launched inside another Claude Code session

原因：使用了 subprocess.run(['claude', 'prompt', ...]) 解决：使用 Task 工具启动独立子代理

TSV 格式问题

如果 TSV 解析失败：

检查是否有未转义的制表符
检查是否有中文引号（应该避免使用）
确保每行都有两列：原文\t译文

依赖问题

脚本需要 beautifulsoup4 库：

pip3 install beautifulsoup4

可选参数

# 翻译指定报告
python3 ~/.claude/skills/insights-zh/scripts/translate.py --path <your-report.html>

# 指定输出文件
python3 ~/.claude/skills/insights-zh/scripts/translate.py --output result.html

# 强制翻译过期报告（不推荐）
python3 ~/.claude/skills/insights-zh/scripts/translate.py --force

完成提示

✅ Insights 中文报告生成完成！

生成的文件：
- report-zh.html (当前目录)

原始报告：~/.claude/usage-data/report.html (未修改)

已在浏览器中打开翻译后的报告。

架构说明

新架构（推荐）

流程：

检查报告 → 提取文本 → TSV 格式 → Task 子代理翻译 → 合并 HTML

优势：

避免嵌套会话：Task 工具启动独立子代理
避免 JSON 转义：TSV 格式天然支持中文引号
易于维护：单一脚本，逻辑清晰
进度可控：每个步骤独立执行，可中断恢复

旧架构问题（已废弃）

旧方案 translate_report.py 存在以下问题：

嵌套会话失败：

subprocess.run(['claude', 'prompt', '--model', 'haiku', ...])
# Error: Claude Code cannot be launched inside another Claude Code session

JSON 转义问题：

# 子代理生成的 JSON
{"translation": "例如，你多次用"算了，clear"这样的短语"}
# 中文引号导致解析失败

修复困难：
- 多次尝试正则替换、行级修复均失败
- 最终改用 TSV 格式才解决

详见

技术细节记录：~/memory/insights-translation-fix.md

索引问题修复

问题描述

早期版本的 translate.py 存在索引不一致问题：

提取阶段使用 HTMLParser，提取了 311 个文本块
合并阶段使用 BeautifulSoup.find_all(string=True)，找到 315 个文本节点
两者的遍历顺序和节点计数不同，导致索引错位

解决方案

统一使用 BeautifulSoup 进行文本提取和合并：

提取阶段：保存 (NavigableString 对象, 文本) 元组
存储格式：TSV 改为 原文 | 译文 两列
合并阶段：重新提取节点，按原文内容匹配翻译

优势

彻底解决索引不一致问题
不依赖索引，使用内容匹配
代码更简洁（不需要索引管理）

insights-zh

Safety Notice

Copy this and send it to your AI assistant to learn