把深度调研写作做成可验收流水线：多 Agent + 质量闸门 + OpenCode skill zhihu-deep-research-writer

先说结论

• 别堆提示词，先把“写文章”拆成可验收工件：证据表 -> 章节草稿 -> 终稿 Markdown。
• 研究、写作、编辑必须拆人拆责：Researcher 只交证据，Writer 只按证据写，Editor 只做一致性与引用核对。
• 编排模式选 3 种就够：顺序流水线、图式回路、经理-工人并行；你更怕质量失控还是更怕交付太慢，决定选哪个。
• Skill 化关键不是“更聪明”，而是“入口固定、参数明确、验收可重复”。
• 知乎发布别在平台里手改到失控：源 Markdown + 发布版 Markdown 双轨维护（必要时用 mdzh / md2zhihu 之类做预处理）。

你将得到什么

• 一套可复用的“深度研究 -> 分章写作 -> 统一润色”流水线拆解与验收闸门。
• OpenCode skill 的封装要点（发现机制、frontmatter 规则、权限/可见性），以及落地检查清单。
• 知乎友好 Markdown 的实操规则（表格/公式/图片/导入流程）和最小返工策略。
• 本项目已实现的 skill：.opencode/skills/zhihu-deep-research-writer/SKILL.md。

1. 把“深度研究 -> 多智能体成章 -> 润色”做成一条可复用的写作流水线

写一篇技术向长文，真正消耗的往往不是打字，而是可验证的材料和结构。模型可以把段落写得很顺，但读者一旦点开引用，或者追问“这个结论对应哪段原文”，最常见的翻车点就是：来源不可靠，论证链断掉，甚至把不同版本的说法揉成一个看似完整的答案。

这篇长文想解决的很具体：把“深度网络研究，分章起草，统一润色”变成一条可执行的 pipeline，然后封装成 OpenCode 的 skill，像命令一样重复用。OpenCode 对 skill 的定位是把可复用的任务流程打包成技能，方便加载和执行，细节可以直接看官方文档 OpenCode Skills。

1.1 我说的 deep research，到底深在哪里

这里的“deep web research”不等同于“深网”，也不等于“搜几篇文章然后总结”。更贴近的定义是：围绕写作目标做多轮检索与阅读，产出能追溯到链接的证据笔记，再用笔记驱动写作。深不深，最后不是看语气多笃定，而是看你能不能回答“这句话凭什么”。

为了让它在工程上可落地，我会把深度研究的交付物写成硬要求：

• 问题拆解清单：每章要回答什么，哪些是事实，哪些是观点。
• 来源优先级：先官方文档、标准、仓库 README，再到二手解读。
• 可引用摘录：关键主张旁边必须有链接，必要时保留原文短句。
• 冲突与不确定：说法不一致就记录差异点，不强行合并成“统一结论”。
• 版本边界：框架版本、API 变更点、是否稳定，这些要在研究阶段钉死。

做到这些，写作阶段才有“硬地面”。否则你引入再多 agent，本质也是更快地产出同一份不确定。

1.2 多智能体成章的动机，以及不可回避的代价

把长文拆成多智能体，不是为了让它“更像人”，而是为了把任务边界做清楚。研究、规划、写章、校对，这四件事对输入输出的要求完全不同，硬塞进一个超长提示里，结果往往是上下文挤爆、段落重复、术语前后不一。

更可控的做法是分工并约束接口，例如：

• Researcher 只产出带链接的笔记，不写成文。
• Planner 只根据笔记生成大纲和缺口清单，缺什么证据就回到研究阶段补。
• Chapter Writer 只写某一章，所有关键结论必须能回链到笔记来源。
• Editor 只做风格统一、去重、引用核对，把无法支撑的句子改成观点表述或直接删掉。

代价同样清楚：

• 深度研究慢，多轮检索和阅读会拉长整体耗时。
• 多 agent 更贵，回合数和上下文长度通常都更大。
• 工程复杂度上升，需要状态管理、失败重试、去重和缓存，否则容易陷入无意义循环。
• 验收标准更严格，必须能回答“每段关键结论来自哪条来源”。

实现编排时，主流框架的取舍也会影响这些代价。如果你希望把流程写成显式的图，让节点间传递状态，LangGraph 的整体思路就是为这类有状态、多 actor 的应用服务，官方概览见 LangGraph Overview。偏对话协作的路线可以看 AutoGen，它把多 agent 对话和协作组件化。想用“角色、任务、工具”来组织团队，CrewAI 的范式和文档体系在 CrewAI Docs 里更直观。

1.3 开源示例里最值得学的，不是模型，而是产物格式

你很难只靠想象写出能跑的“研究->报告”流程，因为关键在中间态。一个基于 LangGraph 的多 agent 报告示例仓库是 botextractai/ai-langgraph-multi-agent，CrewAI 路线也有把研究与报告串联起来的实现 vipunsanjana/Multi-agent-AIPipeline...。读这类项目时，建议盯住两个问题：研究笔记如何结构化保存，后续写作节点如何消费它并保留引用。

这一章只把概念讲清楚：深度研究是一套证据流程，多智能体是分工与接口，OpenCode skill 是把流程固化成可重复执行的入口。下一章我会从最小可运行版本开始，给出研究笔记和章节草稿的约束格式，以及怎么把它们串成一条真正可用的技能命令。

2. 多智能体研究写作的编排模式

多智能体研究写作的难点往往不在“会写”，而在团队如何协作：先计划，再检索与取证，然后成文，接着反思与批评，最后把结论回写到结构和论据里。所谓编排，就是把三件事说清楚：谁在什么时候做什么，产出以什么格式进入共享状态，以及什么时候停止、回退或重试。把每轮产物当作“工件”来管理很关键，比如提纲、术语表、主张-证据表、草稿段落、问题清单、修改记录，这些都是跨角色的契约。

模式一：带检查点的顺序流水线（计划 -> 研究 -> 写作 -> 批评 -> 修订）

这是最接近传统编辑流程的做法。每一步只接收上一步工件，并在进入下一步前做一次闸门检查。

适用场景：主题边界清晰，交付时间紧，篇幅中等，优先追求可控与稳定。

关键做法：计划阶段冻结提纲与口径；研究阶段产出主张-证据表，每条主张绑定来源链接；写作阶段只允许引用表内证据；批评阶段输出可执行问题清单（缺证据、逻辑跳跃、表述风险）；修订阶段逐条闭环并记录变更。

常见失败：闸门标准模糊导致“带病前进”，或批评过于笼统导致反复返工。

模式二：图式状态机与条件回路（含反思、批评的迭代）

当议题本身不确定，或者论证需要多轮推敲时，用“图”比“线”更合适。节点是能力或角色（规划者、研究员、写作者、反思者、批评者），边是条件路由（证据不足就回检索，结构不稳就回计划，措辞不当就回重写）。

适用场景：信息噪声大，观点分歧多，需要在论证结构与证据之间来回调整。

关键做法：状态里保存未解决问题列表与证据置信度；反思节点专门找空白与矛盾，批评节点只输出结构化改动项，便于后续节点自动处理；同时设置停止条件，例如最多迭代 N 轮、问题列表清零、或质量评分达标。

常见失败：回路缺预算上限，打磨无限延长，成本和时延失控。

模式三：经理-工人分治与并行取证（并行研究，集中写作，独立评审）

用一个“经理”拆分研究子问题，派多个研究员并行搜证，写作者统一叙事，再交给独立批评者做交叉审阅。

适用场景：需要覆盖面，资料分散在不同领域，或你想在有限时间内拿到较全面的初稿。

关键做法：经理先定义统一模板（结论、出处、适用边界、反例），并要求研究员互相指出缺口；写作者只做综合与取舍，不再临时新增事实；批评者重点查引用是否支撑主张，是否存在“看似合理但无来源”的段落。

常见失败：并行带来口径不一，所以共享词表与论点层级必须先定好。

框架如何结构这些编排

LangGraph 把工作流表达成有状态的图，节点、边、条件分支与循环都是一等公民，适合把反思和批评做成显式回路，并把提纲、证据表、草稿、问题清单放进统一状态里 [1]。如果你偏向模式二或需要细粒度的路由控制，LangGraph 通常更顺手，示例实现也更容易对照调试 [5]。代价是工程投入更高，状态结构和路由逻辑需要你自己设计。

CrewAI 更像“角色 + 任务 + 流程”的装配线，你定义每个 Agent 的职责和每个 Task 的输入输出，再选择顺序或层级执行 [2]，[4]。它对模式一、模式三很友好，上手快，流程读起来像项目计划书；遇到复杂条件分支时，往往要靠自定义任务或外部控制补齐。

AutoGen 主打多智能体对话与协作，把编排落在“谁发言、如何选择下一位说话者、何时终止”这类对话控制上 [3]。它适合探索式讨论和评审会式的批评环，也能把写作做成多轮对话逐步收敛；不过如果你要强约束的工件流（固定模板、严格闸门、可审计状态），通常需要额外的记忆结构与验证器。

没有一种编排或框架能通吃。图式编排给你更强控制，但开发与维护成本更高；任务流水线更直观，却可能在复杂回路里变笨；对话式协作自由度大，可重复性与可审计性要靠你补上。选型时可以先问三个问题：你更怕质量失控还是更怕交付太慢，你需要的是可解释流程还是快速产出，还有预算是否允许多轮反思与批评。

2.4 额外可复用的开源零件（按模块挑）

下面这些更像“零件库”，建议先看各自 README 确认输入输出，再决定接到流水线哪个环节（尤其是：能否输出结构化证据，而不是只给摘要）。

• 深度研究类候选：agent-deep-research https://github.com/24601/agent-deep-research
• 素材聚合/选题类候选：ai-wechat-news-agent https://github.com/zengzhengtx/ai-wechat-news-agent
• 文风/改写类候选：WenShape https://github.com/unitagain/WenShape
• 发布适配类候选：md2zhihu https://github.com/drmingdrmer/md2zhihu
• 发布适配类候选：Markdown4Zhihu https://github.com/miracleyoo/Markdown4Zhihu
• 发布适配类候选：markdown-it-zhihu-common https://github.com/jks-liu/markdown-it-zhihu-common
• 文风/表达类候选：wenyan-cli https://github.com/caol64/wenyan-cli

如果你只想“减少发布走样”，优先从发布适配类工具入手；如果你更在意“证据链闭环”，优先从深度研究类候选入手。

3. 将工作流封装成 OpenCode Skill（SKILL.md）

当你发现同一套提示词和步骤总要重复写，把它封装成 skill 往往更省事。OpenCode 的 skill 用一个带 YAML frontmatter 的 SKILL.md 来承载，OpenCode 会从项目或个人目录发现这些文件，并通过内置 skill 工具按需加载内容（机制与示例见 Agent Skills）。

把 skill 当成“流程说明书”更合适，它不是脚本，也不是一次性对话记录。写作目标很朴素，让 agent 在最少猜测的情况下，按你的顺序完成动作，并且能用同一套验收标准检查产物。

3.1 放置位置与发现机制（Discovery）

OpenCode 约定“一个 skill 一个目录”，目录名就是 skill 的 name，目录里放全大写的 SKILL.md。官方列出的搜索位置包括（完整清单见 Agent Skills: Place files）：

• 项目级：.opencode/skills/<name>/SKILL.md
• 全局级：~/.config/opencode/skills/<name>/SKILL.md
• 兼容目录：.claude/skills/<name>/SKILL.md、.agents/skills/<name>/SKILL.md 以及各自的全局路径

对项目路径，OpenCode 会从当前工作目录向上遍历，直到 git worktree 为止，沿途加载匹配的 skills/*/SKILL.md（规则见 Agent Skills: Understand discovery）。团队共享的流程通常放在仓库的 .opencode/skills/，个人偏好更适合放到 ~/.config/opencode/skills/。

还有一个很实用的点：OpenCode 会把可用 skills 列在 skill 工具的描述里，每条只有 name 和 description，agent 先靠这两项做选择，再决定是否加载全文（见 Agent Skills: Recognize tool description）。

3.2 Frontmatter 规则与命名约束

每个 SKILL.md 顶部必须是 YAML frontmatter。OpenCode 只识别这几个字段，其他字段会被忽略：name、description（必填），license、compatibility、metadata（可选，且 metadata 是 string 到 string 的映射），字段列表来自 Agent Skills: Write frontmatter。

name 的限制更严格：长度 1 到 64；只能是小写字母和数字，中间用单个连字符分隔；不能以连字符开头或结尾；不能出现连续的 --；并且必须和目录名一致，对应正则是 ^[a-z0-9]+(-[a-z0-9]+)*$（见 Agent Skills: Validate names）。

3.3 SKILL.md 内容怎么写才“像流程”

内容部分没有强制模板，但最好把“触发条件、输入、步骤、输出、边界”固定下来。每一步建议包含三类信息：输入检查（缺什么就问什么），动作清单（用哪些工具做什么），验收点（结果长什么样算合格）。

写作类 skill 可以参考 wechat-article-writer/SKILL.md 的 Step 粒度和节奏。若你的工作流更像多角色协作，把“研究、规划、写作、校对”拆成阶段通常更稳。多智能体流水线仓库常见这种分工方式，例如 ai-langgraph-multi-agent 和 Multi-agent-AIPipeline...。

3.4 权限与可见性（Permissions）

skill 能否被 agent 看到和加载，取决于权限配置。OpenCode 文档给出的做法是在 opencode.json 里配置 permission.skill，用模式匹配把技能分成 allow、deny、ask 三类，示例见 Agent Skills: Configure permissions：

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

关于权限语义与匹配规则，可以交叉看 Agent Skills 与 Permissions。

3.5 实用检查清单

• [ ] 选好 name，满足 ^[a-z0-9]+(-[a-z0-9]+)*$ 且与目录名一致
• [ ] 创建 .opencode/skills/<name>/SKILL.md（文件名全大写）
• [ ] frontmatter 至少包含 name 与 description
• [ ] description 写清触发场景与产出，便于在 skill 列表里被选中
• [ ] 正文固定栏目：输入、步骤、验收点、边界；每步都能检查
• [ ] 在 opencode.json 配置 permission.skill 管控 allow/ask/deny

4. 知乎友好 Markdown 输出的实操要点

知乎的文章编辑器和“文档导入”效果会随版本变化。下面是写作和导入时经常遇到的约束，以及一套更省返工的输出法。这不是官方规范，导入前最好用一篇草稿试一遍。

4.1 结构先稳住

• 源 Markdown 里保留 # 作为标题没问题；如果你用“文档导入”且平台已经有文章标题，可以在发布版里把 H1 删除或降级成 ##，避免标题重复。
• 标题别跳级，建议最多用到 ####。每个标题下至少放一段文字，别只挂一张图或一行公式。
• 段落之间留空行。列表、引用、代码块前后也留空行，粘贴后不容易黏连。
• 段落尽量短，每段 2-4 句更利于手机阅读。
• 代码块统一用三反引号包住，并写语言标识，比如 python。
• 少用花式 Markdown（脚注、任务列表、复杂内嵌 HTML）。

4.2 表格和 LaTeX：常见翻车点

• 管道表格（|a|b|）导入后偶尔会被打散，或者列对不齐。能不用表格就用“小标题 + 列表”表达。
• 必须用表格时，把单元格内容压成单行，避免换行、嵌套列表、代码块，也别指望合并单元格。
• 表格里尽量别塞公式。公式里出现 |、大量反斜杠时，最容易把整张表弄坏，可以把公式挪到表格下方，用编号对应。
• 公式分隔符尽量用 $...$（行内）和 $$...$$（块级）。复杂环境先在草稿里试渲染，再决定要不要改写成更朴素的形式。

4.3 图片处理：先解决“可访问”

• 相对路径 ![](./img/a.png) 通常不会在导入时自动变成已上传图片。发布版 Markdown 里优先放可访问的 HTTPS 绝对链接（或图床/CDN 地址），或者先在知乎编辑器上传图片，再把生成的链接回填到源文件。
• 文件名别带空格，尽量用 plot-1.png。
• 多图排版时，一张图就是一个独立段落，每张图上下各留一行空行。
• 关键图配一句短图注，放在图片下一行。

4.4 导入工作流：一份源文件，两份产物

1. 本地维护“源 Markdown”，只管内容，不为平台妥协。
2. 复制一份“发布版”，做清洗：表格简化、公式分隔符统一、图片链接改成可访问地址。
3. 去知乎写文章，用“文档导入”导入发布版。
4. 第一轮只检查 5 件事：标题层级、列表缩进、代码高亮、公式渲染、图片加载。
5. 如果在知乎里手改了格式，把改动同步回源文件，否则下次重新导入又得重来。

4.5 用 mdzh 这类预处理器把坑提前填上

像 mdzh 这种工具，就是把 Markdown 先预处理成更适合知乎导入的版本。它在 README 里明确写了会替换表格和 $\TeX$ 公式，并输出 xxx.zhihu.md 供“文档导入”使用。用法示例：

python3 path/to/mdzh.py path/to/xxx.md

你也可以把预处理当成一个“可重复的发布步骤”：每次发布都跑同一套规则，减少靠手修。

4.6 Before/After：导入前先做一次“发布版”整理

Before（常见导入后走样）

| 指标 | 公式 |
| --- | --- |
| 准确率 | $acc=\frac{TP+TN}{TP+FP+TN+FN}$ |
![](./img/plot 1.png)

After（更稳；IMAGE_URL 用可访问地址替换）

准确率
- 公式：$$acc=\frac{TP+TN}{TP+FP+TN+FN}$$

![plot-1](IMAGE_URL)

4.7 导入后的 5 分钟回归检查

• 先在电脑预览，再用手机看一遍，重点盯长代码行、长公式、超宽图片。
• 表格一旦错位，优先降级成列表或截图，别在知乎里硬调对齐。
• 随手点开每个链接，确认没有被截断或变成不可点击的纯文本。
• 发现问题先回源文件修，再重新生成发布版。

常见误区与坑

• Researcher 只交“链接堆”而不交“主张-证据”索引，Writer 必然回到凭印象写。
• 引用闸门写在文档里但从不执行，最后只能在编辑阶段爆炸式返工。
• 并行研究不做口径统一（词表、论点层级、边界条件），最后合并时只能靠感觉“揉”。
• 把知乎适配当成写作的一部分（在平台里大量手改），导致源文件和发布版永久漂移。

结语

一套能长期复用的“深度调研写作”工作流，本质上不是更长的提示词，而是更清晰的工件接口与更硬的质量闸门。你可以先从最小闭环开始：固定来源账本格式 + 分章写作合同 + 引用体检清单；跑通后再把它封装进 .opencode/skills/zhihu-deep-research-writer/SKILL.md，把“偶尔写得像”变成“每次都能复现”。

参考与延伸阅读

• OpenCode Agent Skills: https://opencode.ai/docs/skills/
• OpenCode Permissions: https://opencode.ai/docs/permissions/
• LangGraph overview: https://docs.langchain.com/oss/python/langgraph/overview
• AutoGen (stable docs): https://microsoft.github.io/autogen/stable/
• CrewAI docs: https://docs.crewai.com/
• CrewAI (GitHub): https://github.com/crewAIInc/crewAI
• LangGraph multi-agent report example: https://github.com/botextractai/ai-langgraph-multi-agent
• CrewAI research pipeline example: https://github.com/vipunsanjana/Multi-agent-AIPipeline-AutomatedResearch-reportGeneration-CrewAI-LangChain-Groq
• Workflow-only skill example (wechat-article-writer): https://raw.githubusercontent.com/iamzhihuix/happy-claude-skills/632f2c34/skills/wechat-article-writer/SKILL.md
• mdzh (Zhihu Markdown preprocessor): https://github.com/cdfmlr/mdzh
• agent-deep-research: https://github.com/24601/agent-deep-research
• WenShape: https://github.com/unitagain/WenShape
• ai-wechat-news-agent: https://github.com/zengzhengtx/ai-wechat-news-agent
• md2zhihu: https://github.com/drmingdrmer/md2zhihu
• Markdown4Zhihu: https://github.com/miracleyoo/Markdown4Zhihu
• wenyan-cli: https://github.com/caol64/wenyan-cli
• markdown-it-zhihu-common: https://github.com/jks-liu/markdown-it-zhihu-common