# 铁律避坑规则

> 本文件记录账号数据分析（功能四）执行过程中踩过的坑和沉淀的解决方案，防止重复犯错。

## 一、工具/工艺类

| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
|---|---------|------|---------|---------|
| 1 | Write工具写入的.py文件无法被Bash/Python执行（报"No such file or directory"） | Write虚拟文件系统与实际文件系统存在映射差异，写入的.py文件对Bash不可见 | 改用 `Python -c + heredoc(stdin)` 方式：通过stdin传入文本，Python用 `io.TextIOWrapper(sys.stdin.buffer, encoding='utf-8')` 读取，不依赖文件系统中的脚本文件 | 已沉淀为 `json_tool.py` create-content/create-analysis 模式 |
| 2 | analysis数据嵌入Python脚本后被截断，analysis缺少场次section | Write工具写入超长内容（>20000字）时被截断 | 改用heredoc方式通过stdin传入，不受Write工具长度限制；或先用Write写临时txt文件，再用Python读取 | 已沉淀为 `json_tool.py` 的 --input-file 参数 |
| 3 | Python -c 中反斜杠转义与Bash转义冲突（`\\` 在双引号中被Bash吞掉） | Bash双引号会解释反斜杠转义，与Python字符串中的 `\\` 冲突 | 用 `chr(92)` 替代反斜杠、`chr(34)` 替代双引号、`chr(8220)` 替代中文左引号，避免所有转义冲突 | 已沉淀在 `json_tool.py` fix_unescaped_quotes 函数 |

## 二、数据质量类

| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
|---|---------|------|---------|---------|
| 4 | analysis.json写入后json.loads报"Expecting ',' delimiter" | MCP返回的analysis字符串值中含未转义的英文双引号(U+0022)，如 `"前男友七年念念不忘"` 中的引号 | 自动修复算法：逐次定位JSONDecodeError位置→向前搜索未转义双引号→检查其后字符是否为JSON结构字符(: , } ] 空白)→不是则替换为中文左引号(U+201C)→循环直至解析成功 | 已沉淀为 `json_tool.py` fix_unescaped_quotes 函数 |
| 5 | 视频文件夹名带空格，导致路径处理出错 | MCP返回的标题含空格，直接用作文件夹名 | 批量去空格：`for dir in */; do newname="${dir// /}"; mv "$dir" "$newname"; done`。规则：文件夹名一律不含空格 | 已沉淀为命名规则 |
| 6 | 12条视频筛选后文件夹出现18个 | 4个不属于任何方案的文件夹（2个月度中间位+2个超时长）+ 数据跨7个月需选6个月 | 先用 `excel_tool.py query --all` 全量查看再人工确认删除列表，删除前必须用户确认 | 已沉淀为筛选流程 |

## 三、流程/规范类

| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
|---|---------|------|---------|---------|
| 7 | raw中间文件增加了复杂度但无实际价值 | content_raw.txt→Python组装content.json的工艺过度设计 | 放弃raw→组装工艺，直接拆成content.json+analysis.json两个文件存储 | 已沉淀为新格式标准 |
| 8 | Python脚本反复用 `python -c` 内联生成，每次重写 | 没有沉淀可复用脚本 | 创建 `json_tool.py`（4模式）和 `excel_tool.py`（3模式）两个统一脚本，后续优先复用/扩展 | 已沉淀为项目规则 |
| 9 | 并行处理多条视频导致文件混乱和上下文截断 | Agent自动并行化MCP调用 | 用户铁律："视频文件一条条处理 禁止并行处理" | 已沉淀为执行铁律 |
| 10 | 旧格式文件（原视频解析.json）的analysis字段有时是str有时是dict | 新旧格式混用，inspect代码只判断了str | inspect函数兼容两种类型：先检查是否为str→是则json.loads→再检查是否为dict | 已沉淀在 `json_tool.py` inspect 函数 |

## 四、分析质量类

| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
|---|---------|------|---------|---------|
| 11 | 报告"分析很浅"，编导反馈不够深 | 只看13列Excel数据，没有逐条重度调用源技能拆解视频内容 | 两段式铁律：必须先逐条重度拆解（调用源技能3_对标视频账号拆解+12_爆款拆解+11_广告植入方法论），拆解单独存档，全部完成后才能汇总 | 已沉淀为SKILL.md红线+方法论3.0 |
| 12 | 报告中"白惜/敷尔佳自然收口"是无解析推断 | 最好视频缺MCP解析，用数据层结论硬套内容层 | 铁律：无解析视频不得作为内容层论据，提及只陈述数据层事实+注明待验证；后续补解析后用实证替换 | 已沉淀为方法论分析维度总则 |
| 13 | 报告类型归类张冠李戴（飞科清冷帅哥错归健身房肌肉男） | 凭印象归类，未基于MCP解析内容核实 | 铁律：类型归类（男主类型/赛道）必须基于MCP解析内容，不凭印象 | 已沉淀为报告质量自查红线 |
| 14 | 统计口径前后不一致（13条→14条、5条解析→7条解析、3/7带品牌→2/7） | 补解析后部分统计未同步更新 | 补解析后必须全局检查统计口径一致性 | 已沉淀为报告质量自查红线 |