输入一句品牌 brief，自动完成 选博主 → 学博主 → 写出该博主本人愿意拍的脚本 → 合规质检 → 写入飞书文档，并把"对每个博主的理解"沉淀成可复用、会过期刷新的档案。
方案报告（怎么找博主/参考内容/设计脚本分镜）：report.md 飞书最终文档：https://fcnzx8bplws5.feishu.cn/docx/C97tdzN7doCMCbxYIKNcaBKcn2b 飞书写入证据（截图）：feishu/feishu-doc.png — 脚本由 Agent 自动写入飞书后的文档内容 运行时架构图（动态）：用浏览器打开
architecture.html
MCN 商单脚本的难点不是"写得好看"，而是同时满足三件事：贴合这个博主的表达（不像本人会说的话，博主会拒拍、发出去数据也差）、规模化产出、踩不得广告法红线。通用文案工具解决不了第一件，模板解决不了，人工又慢。
这个 Agent 的产物验收标准为：博主本人看完会不会说"这就是我会拍的"。脚本、分镜、飞书文档都是它的载体。
# 1. 依赖（uv 管理）
uv sync # 或 pip install -r requirements.txt
# 2. 配置 .env（见下）
cp .env.example .env # 然后填入 key
# 3. 运行（默认用内置的轻醒 brief）
uv run python main.py
# 也可传入自定义 brief 文件：
uv run python main.py path/to/brief.txt.env 需要的变量：
DEEPSEEK_API_KEY=sk-... # 运行时 LLM（OpenAI 兼容协议）
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_MODEL=deepseek-chat
# 飞书（配了才会真实写入，否则返回 blocks 预览）
FEISHU_APP_ID=cli_...
FEISHU_APP_SECRET=...
FEISHU_DOCUMENT_ID=... # 见「飞书接入」
运行后产物落在 output/（脚本/分镜/合规结果）、creators/（博主档案），并写入飞书。
以 Context Window 为中心：每一步把前面所有产出一起注入，模糊判断交给 LLM，确定性操作交给工具。
判断 = 多个可被自主发现的 Skill。 skills/ 下有 4 个独立小 Skill（brief-decoder / creator-study / script-writer / compliance-checker），每个带 description。运行时 agent/skill.py 把所有 skill 的 description 交给模型，模型按当前环节自主选出匹配的那一个（代码校验、有默认兜底），再把它的正文载入上下文。system prompt 只放 Agent 的运作协议（怎么干、如何选用 skill），不含领域判断；agent/prompts.py 只剩"做什么 + 输出什么 JSON"的薄任务模板。改判断 = 改对应 skill 的 markdown，跑动的 Agent 立刻随之变——判断是可被发现、可加载的资产，不是硬编码，也不是塞死在 system prompt 里。
| 步 | 做什么 | 由谁 | 产物 |
|---|---|---|---|
| 1 | 解析 brief 为结构化数据 | LLM | Brief |
| 2 | 推导达人筛选标准 | LLM | ScreeningCriteria |
| 3 | 召回候选 + 选定 1 位 | 工具召回 + LLM 判断 | Creator |
| 4 | 抽取博主档案 | LLM（命中缓存则跳过） | CreatorContract |
| 5 | 生成脚本 + 分镜 | LLM | Script |
| 6 | 合规质检 | 规则引擎 + LLM 改写（≤3 轮） | 合规 Script |
| 7 | 写入飞书文档 | 飞书 API | 文档链接 |
第 4 步抽的是博主的判断（她替受众解决什么、什么会让她掉粉、会接/拒什么植入），不是"开场/语气/节奏"这类表面特征——后者换一个她没拍过的产品就套不上去。档案里内置一个自检：给一个陌生产品，能否凭档案推出她会怎么开场/收尾。推不出就判定抽得太浅、打回重抽。 档案带内容指纹与时间戳，存为
creators/<id>.contract.md；下次运行若博主内容没变就复用缓存、变了才重抽（缓存失效）。
动态架构图见 architecture.html（可自动播放，逐步展示每一步什么进入 Context、什么沉淀进 Memory、Loop 如何回流）。
走企业自建应用 + tenant_access_token，调 docx/v1 接口写文档块。
配置步骤：
- 飞书开放平台 → 创建企业自建应用 → 拿
App ID/App Secret - 权限管理开通
docx:document（读写）+drive:drive，创建版本并发布（改权限必须重新发版才生效） - 新建一篇飞书文档，地址
…/docx/XXXX中的XXXX即document_id；在文档「分享」里把本应用加为可编辑 - 填入
.env的FEISHU_APP_ID/FEISHU_APP_SECRET/FEISHU_DOCUMENT_ID
写入是幂等的：write_script_to_doc(replace=True) 会先清空文档根块的已有子块再写，同一文档跑 N 次结果恒等于一份（实测连写 3 次块数稳定不翻倍），不会重复追加。
连通性自检（不跑整条 Agent，逐层定位问题）：
uv run python -m feishu.test_connection
# [1/3] 拿 token [2/3] 读文档 [3/3] 写测试块排查记录（题目要求：遇到权限/API 限制如何排查）——真实踩坑顺序：
| 现象 | 原因 | 解决 |
|---|---|---|
| 拿 token 失败 | App 未发布 / 凭证错 | 发版、核对 App ID/Secret |
读 OK、写 1770032 forbidden |
文档只分享了「可阅读」 | 改为「可编辑」 |
写 1770001 invalid param |
文档块 block_type 与字段名不匹配（heading2 应为 4、bullet 应为 12，原代码写成 3/15） |
修正 feishu/client.py 的块类型 |
code:0 |
— | 成功写入 18 块 |
- Claude Code — 搭建/重构 Agent 主体（管线、契约抽取、缓存、合规、飞书修复）
- Codex — 初版脚手架
- DeepSeek（deepseek-chat） — 运行时 LLM，OpenAI 兼容协议接入
repo/
├── README.md # 本文件：说明/运行/飞书接入/边界
├── report.md # 方案报告：怎么找博主/参考内容/设计脚本分镜
├── main.py # 入口
├── agent/
│ ├── core.py # 7 步编排 + 校验/重试/合规循环
│ ├── skill.py # Skill 注册表：扫描 skills/、按 description 供模型选用、载入正文
│ ├── prompts.py # 薄任务模板（只剩"做什么+输出什么 JSON"，判断不在这里）
│ ├── schemas.py # 结构化数据定义（含 CreatorContract）
│ ├── validation.py # 结构化校验 + 失败回灌
│ ├── contract_store.py # 博主档案落盘 + 缓存失效（新鲜度检查）
│ ├── tools.py # 确定性工具：召回/取内容/合规/写飞书
│ └── memory.py # AgentState 累积 + Context 注入
├── feishu/
│ ├── client.py # 飞书 docx/v1 客户端
│ └── test_connection.py # 飞书连通性自检
├── config/compliance_rules.json # 合规词表（外置，业务可改，无需动代码）
├── skills/ # 4 个独立小 Skill = 判断源，按 description 自主发现、按需载入
│ ├── brief-decoder/SKILL.md # 拆 brief、推筛选标准、选博主
│ ├── creator-study/SKILL.md # 学博主、提炼内容逻辑（判断非特征）
│ ├── script-writer/SKILL.md # 写"博主会拍的"脚本+分镜
│ └── compliance-checker/SKILL.md # 合规判断与按口吻改写
├── creators/ # 博主档案（运行时生成，含 .md 可读版）
├── output/ # 脚本 / 分镜 / 合规结果
├── architecture.html # 动态运行时架构图
└── prompts/ · references/ # Prompt 迭代记录 · 调研材料（接入位见下）
- 博主数据是 stub。 候选库与内容样本目前是内置示例，收在
search_creators()/get_creator_content()两个工具背后。真实小红书接入就是替换这两个工具的实现（爬虫 / MCP / 人工录入），管线、Prompt、Skill 均不变——这是刻意留出的数据接缝。 - 合规修复：LLM 按博主口吻重写，不做机械替换。 命中红线后让 LLM 在博主口吻内重写（≤3 轮）；多轮仍触线则阻止交付、待人工介入——不靠无上下文的字符串替换产出生硬/误替换的稿（如
第一步→很适合步）。 - 合规词表外置在
config/compliance_rules.json，业务方新增违禁词/调阈值只改配置、无需动代码或重新部署；文件缺失会回退到代码内默认值。规则的「campaign 级动态化」（直接由Brief.red_lines驱动）是下一层——红线是自然语言、需先做术语抽取，当前仍以全局词表 + 生成时 prose 约束的方式落地。 - 管线是确定性编排，非模型自主调度。 步骤顺序由代码固定（更可控、可复现），而非交由模型自由决定工具调用——这是面向可靠交付的取舍。