linxiao-writing-v2

name	linxiao-writing-v2
description	小红书视频口播稿生成系统。基于真实爆款反向提取的叙事路线 + 钩子库 + 75 标题公式 + 23 条护栏 + 数千条观点案例种子的一体化创作管道。当用户说"生成笔记"、"写小红书"、"写口播稿"、"/生成 选题..."、"帮我写一篇关于 X 的小红书"等时使用。

小红书视频口播稿生成系统 · v3.7

把"选题"变成"N 篇成稿 + 每篇 4-5 候选标题 + 护栏报告"。

体裁：小红书视频口播稿（4-6 分钟视频脚本，800-1200 字）—— 不是图文笔记。

何时调用

用户输入符合以下任一：

• /生成 "选题文本" --主权重=客资（slash 命令，最准）
• /生成 选题：...
• "用我们的风格写一篇 X 的小红书"
• "生成一篇 X 的口播稿"
• "帮我写小红书，主题是 X"

调用接口

/生成 "选题文本" --主权重=客资 [--N=1] [--partitions=...] [--run_id=...]

参数	必需	默认	说明
topic	✅	—	选题文本（自由文本，可口语化）
--主权重	✅	—	客资 | 涨粉，决定 partition 路由
--N	❌	1	输出篇数（1-3）；N>1 = 同 1 论点的不同叙事路线
--partitions	❌	按主权重派生	显式覆盖召回分区，逗号分隔
--run_id	❌	yymmdd-HHMM	自定义 run id

核心管道（v3.7 一体化范式）

选题
  ↓
Step 1: wide-recall          (脚本驱动 · partition+stable 过滤 · Top 50 素材)
  ↓
Step 2: stage1-claim-route   (1 次 LLM · 候选论点+5项自审+proof_tasks+N 路选择)
  ↓
Step 3: stage2-compose × N   (N 次独立 LLM · 标题+开头+骨架+成稿+钩子+自审)
  ↓
Step 4: guardrail-check      (只读 · 23 条护栏 · PASS/WARN/FAIL)
  ↓
可选 Step 5: guardrail-fix → guardrail-recheck
  ↓
N 篇成稿 + 每篇 4-5 候选标题 + gate 报告

设计哲学：v2.0 的 10 步原子化方案被证明丢全局协调能力。v3.6 写作链压成 1 + N 次 LLM——一次决策 + 每路一次完整成稿——保留全局视角；v3.7 把 Step 1 默认召回切到 sparse 索引，降低延时和安装成本。

运行前硬要求

Step 1 默认使用轻量 sparse 召回，只需要本地 Python 能运行 pyyaml 和 jieba：

pip install pyyaml jieba

安装后先确认当前 shell 的 Python 环境：

python3 -c "import yaml; import jieba; print('OK')"

fastembed 和 scikit-learn 已降为可选依赖：只有显式使用 --backend auto、--backend embedding、--backend tfidf，或构建 .cache/embeddings.jsonl 时才需要。深度召回依赖安装：

pip install fastembed scikit-learn

执行步骤

主 orchestrator 收到 /生成 命令后按以下步骤执行。

Step 0 · 准备

1. 解析参数（topic / 主权重 / N / partitions / run_id）
2. 用户当前工作目录下创建 runs/{run_id}/
3. 初始化 runs/{run_id}/decisions.md

Step 1 · 宽召回（wide-recall）

读 atoms/wide-recall.md 执行。

主 orchestrator 用 Bash 调脚本：

python3 scripts/wide_recall.py "{topic}" \
  --partition {partitions_csv} \
  --top_k 50 \
  --backend sparse \
  --output runs/{run_id}/material-pool.md

• 候选池：viewpoints/v*.md ∪ cases/c*.md ∪ atoms/viewpoint-bank/v-*.md
• 默认只读 stable: true 素材（显式 --include_unstable 覆盖）
• 后端默认 sparse：字段化宽召回，无需 fastembed/scikit-learn；fast 是 sparse 别名；auto 会在 sparse 低置信且 embedding 可用时升级
• stdout 只输出 JSON；runs/{run_id}/material-pool.md frontmatter 会写 backend/degraded/text_format_version/score_formula/sparse_low_confidence
• trust 只展示来源，不参与排序；素材排序由字段关键词命中和可选语义分数决定
• 表格含 semantic_score/keyword_score/field_score/match_reason，用于解释为什么命中
• partition 默认按主权重派生（详见 atoms/wide-recall.md）

出：runs/{run_id}/material-pool.md（Top 50 markdown 表）

如果 material-pool.md frontmatter 里 degraded: true，必须在 Stage 1 prompt 顶部提示：⚠️ 当前召回降级到 {backend}，相关性较弱，请更谨慎使用 material-pool。

如果 sparse_low_confidence: true，不阻塞创作，但应更谨慎使用 material-pool；人工发现 TopK 不切题时，可单独重跑 --backend auto 或 --backend embedding。

Step 2 · 一体化论点+路线决策（stage1）

读 atoms/_unified/stage1-claim-route.md 执行。

orchestrator Read 并拼到 prompt context：

• runs/{run_id}/material-pool.md 全文
• atoms/cognitive-gap-anchor.md（"## 认知冲突类型汇总"段）
• atoms/narrative-route/_index.md

一次 LLM 调用完成 brief + 4-7 候选论点 + 5 项自审选 picked_claim + 4-7 个 proof_tasks + N 条 picked_routes。

5 项自审（picked_claim 全过）：

1. 聚焦性：删 1 句论点是否还成立
2. 无跨主题污染：不借其他主题爆款论点
3. 行动直达：读者明天能做什么
4. 证据可达：material-pool 50 条能支撑
5. 转化承接：与主权重对齐

候选都通不过自审 → 标 manual_intervention_required: true 等待人选。

出：runs/{run_id}/stage1.md

Step 3 · N 路独立成稿（stage2-compose × N）

对每条 picked_route 中的 nr_j（共 N 路），独立调用 atoms/_unified/stage2-compose.md。

每路独立 Read 并拼到 prompt context：

• runs/{run_id}/stage1.md 全文
• runs/{run_id}/material-pool.md 全文
• atoms/style-fingerprint/linxiao_v1.md
• atoms/_unified/expression-rules.md（5 核心原则）
• atoms/xhs-title-formulas.md（75 标题公式 + 5 铁律）
• atoms/narrative-route/{nr_j}.md（当前路线全文）
• atoms/hook-bank/README.md + 该主题 Top 5 钩子全文

一次 LLM 调用完成：

1. 选素材
2. 生成 4-5 候选标题（每个必须追溯 75 公式之一）
3. 写开头三件套（第 1 句必含选题主题词 + Hook + 可信度）
4. 写骨架（字数动态分配）
5. 直接成稿（expression-rules 5 原则同步内嵌，不后置润色）
6. 钩子承接（从 hook-bank 召回核心 CTA，承接案例段末尾，禁独立 CTA 段）
7. 全文 5 项自审

字数硬约束 r-022：800-1200 字（<800 或 >1200 禁输出）

出：runs/{run_id}/article-{nr_id}.md × N + runs/{run_id}/articles.md 汇总

Step 4 · 护栏 gate（guardrail-check）

读 atoms/guardrail-check.md 执行。

跑 23 条 atoms/guardrail/r-*.md，每路独立判：

判定	标准
PASS	hard 全过 + soft ≥ 80%
WARN	60-80%
FAIL	hard 失败 OR soft < 60%

通过门槛：N 路中 ≥ ⌈N/2⌉ PASS（N=1 时 1 篇必 PASS）。

guardrail-check 只读，不修改 article。

出：runs/{run_id}/gate-report.md

可选 Step 5 · 修复（guardrail-fix → guardrail-recheck）

仅 gate FAIL 或用户要求时执行：

• atoms/guardrail-fix.md：读 gate-report + 原文 → article-fixed-{nr_id}.md
• atoms/guardrail-recheck.md：对 fixed 版本重判
• 不允许覆盖原始 article-{nr_id}.md

Step 6 · 输出给用户

• 主消息直接展示 N 篇的【4-5 候选标题 + Top 1 推荐】+【口播稿正文】
• 末尾附护栏简报（每路 PASS/WARN/FAIL + 关键警告）
• 提示介入点（manual_intervention_required / 字数边缘 / 标题语气）

硬规则总览

1. 不创作钩子 — 仅从 atoms/hook-bank/ 召回原文，可替换 {资料名} 等占位
2. 钩子顺序 r-019 — 用户痛点 → CTA → 自我背书
3. 钩子段数 r-012 — 仅 1 段私信通道；评论区/主页钩子由人手动加
4. 不编造具体姓名 — 不出现"我学员小李"等虚构人名
5. 每篇 ≥ 1 案例 — 用具体场景/数据/对比/流程把抽象观点落地（不是学员故事）
6. 字数 800-1200 hard（r-022）
7. 专家角色锁定（r-023） — L3 补齐观点 + AI 生成案例必须载入 atoms/_persona/
8. 风格遵守 v1.1.1 — 女性视角；无爹味 / AI 味；逻辑连贯
9. 标题必须追溯 75 公式之一 — 不允许自由发挥
10. 开头第一句必含选题主题词 — 禁"我观察到 / 很多同学"共鸣前置

输出文件清单（in runs/{run_id}/）

文件	来源步骤	说明
decisions.md	每步追加	决策日志（yaml frontmatter + 自然语言）
material-pool.md	Step 1	Top 50 素材表
stage1.md	Step 2	brief + claim + tasks + routes
article-{nr_id}.md × N	Step 3	单路成稿 + 4-5 标题
articles.md	Step 3	N 路并列汇总
gate-report.md	Step 4	23 条护栏判定
article-fixed-{nr_id}.md	可选	修复版
gate-report-fixed-{nr_id}.md	可选	修复版复查

介入点

#	何时	动作	时长
①	Stage 1 后（条件）	manual_intervention_required: true 时，4-7 候选选 1	1-2 min
②	Stage 2 后	看 N 篇 + gate-report，挑 1 + 终校 + 发布	3-5 min

目标：N=1 ≤ 3 min，N=3 ≤ 5 min。

Token 预估

N	Step 1	Step 2	Step 3	Step 4	总计
1	~2K	~3K	~6K	~1K	~10K
2	~2K	~3K	~12K	~2K	~17K
3	~2K	~3K	~18K	~3K	~24K

知识资产清单

资产	路径	数量
叙事路线	atoms/narrative-route/nr-*.md	9 + _index
钩子库	atoms/hook-bank/h-*.md	40
护栏规则	atoms/guardrail/r-*.md	23
风格指纹	atoms/style-fingerprint/	1
专家角色	atoms/_persona/	1
标题公式	atoms/xhs-title-formulas.md	75 + 5 铁律
认知冲突锚点	atoms/cognitive-gap-anchor.md	12 类
表达规则	atoms/_unified/expression-rules.md	5 核心原则
观点种子库	atoms/viewpoint-bank/v-*.md	30
观点真源	viewpoints/v*.md	3481
案例真源	cases/c*.md	1073

详细文档

• README.md — 概览 + 架构图
• USAGE.md — 详细调用示例 + 完整命令清单
• INSTALL-mac.md — Mac 安装
• INSTALL-windows.md — Windows 安装