mcn-dou-analysis 内嵌副本结构整合（08-27 主版本定稿）

- references-add/ 内容迁入 references/：路径配置.md、铁律避坑规则/（账号数据分析执行避坑、账号设定执行避坑）改为标准库，references-add 仅留 README - 五功能文件（01获取账号信息/02获取视频/03提炼账号设定/04分析视频数据/05解析视频）与 SKILL.md、MCP 规范、excel_tool.py、select_top6.py 同步更新 - 记忆日志（08-26 追加/08-27 新增）+ MEMORY.md + 失误与规避记录
2026-08-27 10:25:00 +08:00
1 parent b05e74bbbc
commit f025ad3b86
@@ -7,6 +7,10 @@

 ## Step 1：获取达人账号信息

+### 数据源优先级（红线）
+
+获取达人账号信息**必须浏览器优先**：默认用 browser-harness 访问抖音网页版账号主页提取（流程见下）。**如无必要不用查 MCP 达人信息**——MCP 的 `list_hot_accounts`/`hot_account_detail` 是**内部账号库查询工具**（MCN 内部维护的达人账号库，含人设/赛道/标签，非抖音页面实时数据），**不是本功能数据源**；仅当浏览器无法访问（账号搜索不到/主页打不开）时，才可用 MCP 达人信息兜底，并须在账号表「备注」列注明数据来源。
+
 ### Step 1.0 账号表登记（前置）

 先检查 `达人账号表.xlsx`，输入信息中的账号若不在表中，先添加到表（账号ID自增、抖音号/抖音ID(sec_uid)/抖音地址存文本格式，其余字段留空），再继续获取数据。
@@ -27,4 +31,4 @@

 - 账号信息登记到 **`达人账号表.xlsx`**（权威源，字段：账号ID/达人昵称/抖音号/抖音ID/抖音地址/粉丝数/解析状态/人设卡/更新时间/获赞数/关注数/作品数/IP属地/简介/备注；抖音号/抖音ID/抖音地址存文本格式。**注：仅保留网页可获取的账号数据列 + 内部主键/更新时间/流程状态，已删除非网页字段「类别/数据来源/对标视频数」**）
 - **「更新时间」字段**：每次获取账号数据后，**更新「更新时间」字段**（格式 `YYYY-MM-DD HH:MM`）。再次获取前先检查该字段：若数据较新（如近 1 个月内）应提示用户判断是否仍需刷新，避免无谓重复抓取
- 根目录默认位于用户桌面 `{产出根目录}/`（实际产出路径以 `references-add/路径配置.md` 为准）
+- 根目录默认位于用户桌面 `{产出根目录}/`（实际产出路径以 `references/路径配置.md` 为准）
@@ -19,4 +19,4 @@
 ### 数据保存规则

 - 浏览器抓取数据保存为 **Excel 文件**（`短视频表格.xlsx`，13列标准格式：序号 | 视频ID | 视频标题 | 视频地址 | 点赞数 | 点赞(显示) | 评论数 | 分享数 | 收藏数 | 播放量 | 视频时长 | 发布时间 | 标签）
- 根目录默认位于用户桌面 `{产出根目录}/`（实际产出路径以 `references-add/路径配置.md` 为准）
+- 根目录默认位于用户桌面 `{产出根目录}/`（实际产出路径以 `references/路径配置.md` 为准）
@@ -3,7 +3,7 @@
 > 本文件是 MCNDouAnalysis 技能**功能三（提炼账号设定）**的完整执行流程。
 > 独立文件设计目的：部署到用户电脑时，如不需要此功能，**删除本文件即可禁用**（同时可删除 `references/人设卡生成方法.md`、`references/知识库/账号设定/`、`references/解析结果格式规范.md`；**如功能四仍启用，解析结果格式规范需保留**，功能四目录结构以其为准）。

-> 🔴 **执行前必读避坑**：`references-add/铁律避坑规则/账号设定执行避坑.md`（本功能执行中踩过的坑：本地接口调用超时、大文本序列化、analysis 简化格式、写库验证等，防止重复犯错）。
+> 🔴 **执行前必读避坑**：`references/铁律避坑规则/账号设定执行避坑.md`（本功能执行中踩过的坑：本地接口调用超时、大文本序列化、analysis 简化格式、写库验证等，防止重复犯错）。

 ---

@@ -62,4 +62,4 @@
 | `references/知识库/视频拆解/` | 功能四拆解知识库（23文件：开场/框架/情绪/钩子/植入/拆解，③用户环境独立运行） |
 | `references/解析结果格式规范.md` | 目录结构权威源 |
 | `references/接口调用/MCP_工具调用规范.md` | MCP 安装/登录/降级规范（Step 7 补解析 + 拆解降级） |
-| `references-add/铁律避坑规则/账号数据分析执行避坑.md` | 功能四执行避坑（14个问题按工具/数据/流程/分析四类归档） |
+| `references/铁律避坑规则/账号数据分析执行避坑.md` | 功能四执行避坑（14个问题按工具/数据/流程/分析四类归档） |
@@ -48,7 +48,7 @@ id = "{detailId}"
 > - `python json_tool.py create-content --detail-id {detailId} --title "标题" --output-dir "{产出目录}/视频文件夹" --input-file _tmp.txt`
 > - `python json_tool.py create-analysis --output-dir "{产出目录}/视频文件夹" --input-file _analysis_tmp.txt`

-保存位置：`{产出根目录}/{达人昵称}/视频对标/{视频文件夹}/`（产出根目录以 `references-add/路径配置.md` 为准；视频文件夹命名按 SKILL.md 规则：`视频标题（去特殊符号）_标签1_标签2`）。
+保存位置：`{产出根目录}/{达人昵称}/视频对标/{视频文件夹}/`（产出根目录以 `references/路径配置.md` 为准；视频文件夹命名按 SKILL.md 规则：`视频标题（去特殊符号）_标签1_标签2`）。

 ### ⑤ 写入数据库（可选，环境支持时）

@@ -130,3 +130,5 @@ MCP 工具可用后，调用任何 MCP 工具前须先检查飞书登录状态
 | `upload_other_video` | 上传本地视频文件做 AI 内容解析入库 | `title` + `file_path` | 对标视频是本地文件时 |
 | `short_video_detail` | 查询解析结果（文案+拆解），判断是否完成 | `id`（详情ID） | Step 4 轮询获取解析内容 |
 | `current_user` | 获取当前登录用户完整资料 | 无 | 确认登录身份 |
+
+> ⚠️ **工具边界（数据源红线）**：MCP 服务另暴露 `list_hot_accounts`（内部账号列表）、`hot_account_detail`（内部账号详情）等工具（工具命名 hot_accounts 有误导性，实为 **MCN 内部维护的达人账号库**，含人设/赛道/标签/代表作，非抖音页面实时数据）——**仅作内部账号库查询，禁止作为功能一「获取账号信息」的数据源**。功能一数据源 = 浏览器访问抖音账号主页（**浏览器优先，如无必要不用查 MCP 达人信息**；浏览器无法访问时才可兜底并注明来源）。
@@ -0,0 +1,60 @@
+# 路径配置（运行时优先）
+
+> 本文件是**产出路径的唯一权威配置**，运行时优先于 SKILL.md 中默认路径。
+> 只要本文件存在，AI 执行工作流前必须先读本文件；如有「用户自定义路径」记录，一律以用户指定为准，默认路径自动失效。
+
+## 一、默认路径（用户未自定义时生效）
+
+**先判断运行环境（三环境两步判定），再按运行系统解析桌面路径：**
+
+| 运行环境 | 判断依据 | 默认产出根目录 |
+|:---|:---|:---|
+| dsh 部署环境 | 技能路径含 `.dsh`，且本机存在 `D:\AgentSkill`（如 `C:\Users\{用户名}\.dsh\skills\…`） | **优先** `D:\dshworkspace\解析任务\`（主工作区「解析任务」目录） |
+| 开发机 | 技能路径不含 `.dsh`（源技能在 `D:\AgentSkill` 下） | 用户桌面 `MCNSkill项目/`（`{达人昵称}/` 直挂，无技能文件夹层） |
+| 用户环境 | 本机不存在 `D:\AgentSkill`（技能装在用户机器上，路径不限、不一定含 `.dsh`） | 用户桌面 `MCNSkill项目/`（与开发机同构） |
+
+桌面路径按运行系统自动解析：
+
+| 系统 | 桌面路径 |
+|:---|:---|
+| Windows | `C:\Users\{用户名}\Desktop\` |
+| macOS | `~/Desktop/`（即 `/Users/{用户名}/Desktop/`） |
+
+**AI 执行规则：**
+1. 先做三环境两步判定：① 本机是否存在 `D:\AgentSkill`——不存在即**用户环境** → 桌面 `MCNSkill项目/`；② 本机存在时再看技能自身路径——含 `.dsh` 即 **dsh 部署环境** → **优先操作** `D:\dshworkspace\解析任务\`（「解析任务」子目录不存在则创建）；不含 `.dsh` 即**开发机** → 桌面 `MCNSkill项目/`（开发机与用户环境同构：`MCNSkill项目/{达人昵称}/`）
+2. 再判断当前运行系统（Windows / macOS），拼接桌面路径
+3. 目录不存在则自动创建
+4. 产出结构：`{产出根目录}/{达人昵称}/…`（内部文件结构不变，仅根目录可变）
+
+## 二、用户自定义路径（最高优先级）
+
+**如果用户明确要求修改产出位置，一律以用户指定为准，不要沿用默认桌面路径，也不要自作主张改回桌面。**
+
+出现自定义需求时，在此追加记录（保留用户原话，便于追溯）：
+
+```
+> 用户指定：{用户原话}
+> 解析后路径：{绝对路径}
+> 记录时间：{日期}
+```
+
+**示例：**
+
+> 用户指定：产出放到 D 盘我的素材文件夹里
+> 解析后路径：`D:\我的素材\账号分析\`
+> 记录时间：2026-08-14
+
+记录后，AI 每次执行工作流都以「解析后路径」为产出根目录；用户再次修改时直接更新本记录即可（旧记录保留，标注新记录生效）。
+
+## 三、解析规则（优先级从高到低）
+
+1. 本文件「用户自定义路径」记录 → 用自定义路径（最新一条生效）
+2. 本文件默认路径 → 按三环境两步判定确定产出根目录（本机无 `D:\AgentSkill` → 桌面 `MCNSkill项目/`；有且技能路径含 `.dsh` → `D:\dshworkspace\解析任务\`；有且不含 `.dsh` → 桌面 `MCNSkill项目/`），再按系统拼接桌面路径
+3. 路径含 `~` 时自动展开为用户主目录
+4. 路径含 `{用户名}` 时替换为当前系统用户名
+5. 目录不存在时自动创建
+
+## 变更记录
+
+- 2026-08-26：产出路径改为三级优先级（借鉴脚本创作技能）：① dsh 环境 + 主工作区 `D:\dshworkspace` 存在 → `D:\dshworkspace\解析任务\`；② dsh 环境但无主工作区（异机部署）→ 桌面 `DSHSkill项目/账号分析/`；③ 非 dsh → 桌面 `MCNSkill项目/账号分析/`。产出结构 `{达人昵称}/…` 不变。
+- 2026-08-26（三环境重构 + 账号层直挂，对齐脚本创作技能定稿）：环境判定由「dsh vs 非 dsh」改为**三环境两步判定**（①本机无 `D:\AgentSkill`=用户环境；②有且技能路径含 `.dsh`=dsh 部署环境；③有且不含 `.dsh`=开发机）；`DSHSkill项目/` 根目录**整体废弃**（原「dsh 异机兜底」场景并入用户环境）；非 dsh 产出根目录由 `MCNSkill项目/账号分析/` 改为 `MCNSkill项目/`——去掉技能文件夹层，`{达人昵称}/` 直挂（与脚本创作 `MCNSkill项目/{账号名}/` 同根）；dsh 部署环境产出 `D:\dshworkspace\解析任务\` 不变。产出结构 `{达人昵称}/…` 不变。
@@ -0,0 +1,37 @@
+# 铁律避坑规则
+
+> 本文件记录账号数据分析（功能四）执行过程中踩过的坑和沉淀的解决方案，防止重复犯错。
+
+## 一、工具/工艺类
+
+| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
+|---|---------|------|---------|---------|
+| 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） | 补解析后部分统计未同步更新 | 补解析后必须全局检查统计口径一致性 | 已沉淀为报告质量自查红线 |
@@ -0,0 +1,32 @@
+# 铁律避坑规则（功能三：提炼账号设定）
+
+> 本文件记录账号设定提炼（功能三）执行过程中踩过的坑和沉淀的解决方案，防止重复犯错。
+> 与「账号数据分析执行避坑.md」（功能四）互为镜像，结构一致。
+
+## 一、工具/工艺类
+
+| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
+|---|---------|------|---------|---------|
+| 1 | PowerShell `ConvertTo-Json` 序列化大文本（人设卡全文约 1.5 万字符）后 `Invoke-RestMethod` POST 接口超时（120s 卡死，后台任务被终止） | PowerShell `ConvertTo-Json` 对大字符串序列化性能差，请求发送阶段卡住；最小 payload（几十字节）46ms 即成功，证明是**请求体大小**问题而非接口问题 | 接口调用改用 **Python 直连构造 JSON**（`urllib.request` + `json.dumps(ensure_ascii=False)`），绕开 PowerShell ConvertTo-Json；大文本一律走 Python，不用 PowerShell 序列化 | 已沉淀为本规则 |
+| 2 | 写库后无法确认是否写入成功（后台任务消失、无输出） | 后台 job 被终止后状态丢失，接口又无查询列表端点 | 用**幂等重试**验证：同 payload 重复提交，返回 `analyses:0` 即证明已去重入库（脚本层自动去重）；POST 接口本身是最可靠的验证手段 | 已沉淀为本规则 |
+| 3 | 人设卡写入数据库时误用测试 payload 探测接口，留下脏数据 | 先用最小 payload 测连通性，意外写入 1 条测试记录 | 探测接口连通性用 `GET`（如 `/mcn/api/account/videos?accountId=X`），**不用写接口探测**；若已写入测试数据，同账号+type 重复提交正式内容会覆盖（脚本层按 账号+类型 去重） | 已沉淀为本规则 |
+
+## 二、数据质量类
+
+| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
+|---|---------|------|---------|---------|
+| 4 | 平台返回的 analysis 为 6 字段简化格式（缺赛道/人设/框架/事件等核心维度） | 部分视频平台侧解析版本较旧，仅返回简化分析 | 以平台实际返回为准照实保存，在人设卡「设定分析说明」中标注该条深度弱于其他条；不得凭印象补造缺失维度；后续可用功能五单独重解析替换 | 已沉淀为设定分析说明规则 |
+| 5 | 既有解析产物 detailId 与 aweme_id 不一致（如 26164 vs 7667477088350044069） | detailId 是业务解析 ID，aweme_id 是抖音视频 ID，两者本就不同 | 校验产物归属时用**标题匹配**而非 ID 匹配；detailId 不用于对照视频来源 | 已沉淀为校验规则 |
+
+## 三、流程/规范类
+
+| # | 问题现象 | 根因 | 解决方案 | 沉淀状态 |
+|---|---------|------|---------|---------|
+| 6 | 本地接口（`/mcn/api/...`）调用规范未沉淀，每次现查 | 无统一接口调用规范文件 | 新建 `references/接口调用/本地接口调用规范.md`，记录接口基地址判定（`$env:DSH_WEB_URL` → 3080/3081 兜底）、接口清单、请求构造方式（Python 直连优先） | 已沉淀为本规则 |
+| 7 | 生成人设卡前未先判定账号类型就套模板 | 账号类型判定是模板选择前置 | 严格执行 5.0 判定：从筛选出的 TOP 视频 analysis「人设」字段提取主角名称 → 全部不同=群像型 / 同一主角=固定主角+轮换搭档 / 全固定=单一达人型 | 已沉淀为人设卡生成方法 5.0 |
+
+---
+
+## 快速参考：本地接口调用（功能三写库用）
+
+> 接口基地址判定、接口清单、请求构造铁律，见 `references/接口调用/本地接口调用规范.md`。