从 0 到 1 构建一个多 Agent 平台：架构、产品、应用与 AI 编程落地的完整复盘

项目：Content Pipeline Platform（多 Agent 内容生产平台）复盘范围：2026-08-16 起，从"想做 Agent"到 M0/M1/M2 落地、M3 演进，及生鲜行业应用推演写作目的：把"从 0 到 1 的思考链"完整存档——决策怎么做的、坑怎么踩的、方法论是什么，供学习与复用

0. 序：这一切是怎么开始的

一切始于一句话：「我要实现一个 agent，先不急着写代码，帮我调研一下架构，单一 agent vs 多 agent，也可以参考一下这几天开源的 dsh」。

这句话里藏着三个信号，后来回头看，都是关键的：

"先不急着写代码" —— 用户天然认可"想清楚再动手"，这为后续"文档驱动、决策先行"定了调；
"调研一下架构" —— 起点是决策问题，不是技术方案；
"参考一下 dsh" —— 用户引用了具体的开源参考物，这往往隐含偏好（想要能落地的、开源的、可自控的方案）。

接下来的旅程，是一条完整的主线：调研 → 决策 → 架构 → 基础设施 → 编码落地 → 行业应用。每一步都留下了可复用的方法论。本文按"架构层 → 产品层 → 应用层 → AI 编程落地"四层复盘，最后给出可迁移的学习清单。

一、架构层：从"单一 vs 多 Agent"到 LangGraph 内核

1.1 调研的第一课：先确认"是什么"，再看"业界怎么看"

拿到"参考 dsh"这个线索，第一轮搜索的目标是实体确认：dsh 是什么？——答案是 DeepSeek Harness，2026-08-13 开源，MIT，命令名 dsh，基于 Cordis 插件框架。这一步锁定了事实（版本、日期、协议、定位），而不是观点。

第二轮才进入共识确认：业界对"单一 vs 多 Agent"怎么看？交叉了 Azure 架构中心、Jishu Labs、Catalect、腾讯云开发者社区等多来源，得到交集结论。

方法论：调研永远两段式——先"是什么"（事实，标来源），再"怎么看"（共识，多源交叉 ≥3）。一次搜索就下结论，是埋雷的开始。

1.2 dsh 给了我们什么（不是抄，是吸收）

dsh 最有价值的三个设计，全部被吸收进了我们的架构：

dsh 设计	我们吸收为什么	落点
Turn/Step 生命周期 + append-only 会话日志，"模型可见必可重建"	ADR-003 日志即真相：事件日志是系统核心表，只追加不修改，任何进模型的内容必须先落日志	`observability/event_log.py` + 事件类型枚举（6 域 13 事件）
ctx.subagents 单接口，多实现（Spawn/Fork/ACP/Workflow）	编排演进有触发条件：M0 用固定流水线，supervisor 只留入口节点，M3 才动态分流	`graph/pipeline.py` 的 supervisor 节点
Capability Seam（接口/实现/消费者三层）	ADR-004 工具 Seam 三层：换数据源/工具实现不碰编排代码	`tools/spec.py` + `impl/` + MCP 适配

dsh 的教训同样重要：v0.1 开发者预览版、破坏性变更频繁，不适合做生产底座——它被定位为"架构范本"，而不是依赖。这是"参考开源项目"的正确姿势：抄思想，不抄依赖。

1.3 单一 vs 多 Agent：一个反直觉的结论

业界 2026 年的共识（多家印证）是：多 Agent 被过度推荐。它的代价很具体：归因困难（5 个 Agent 出错看不出是哪步）、上下文丢失（每次 handoff 都是一次摘要）、延迟叠加、非确定性相乘。而拆分的合法理由只有四类：

权限边界不同（安全隔离）
模型类别不同（成本分层，plan-and-execute 可降本 90%）
独立审查（Reviewer 上下文必须与 Generator 隔离）
真并行（N 个互不依赖的子任务）

一句话判据："能说清第二个 Agent 做了一件第一个做不了的事"才拆。"关注点分离"不是理由——那是代码架构的审美，不是 Agent 的。

这个结论直接塑造了我们的起步形态：单一主流水线 + 强可观测，而不是一开始就上 Supervisor 编排群。

1.4 选型：LangGraph 为什么赢

对比了 LangGraph / CrewAI / OpenAI Agents SDK / 复用 dsh / 自研，LangGraph 胜出在四个点，恰好都是平台型产品要命的点：

checkpoint / HITL / time-travel 是一等公民——60% 生产 Agent 事故源于状态管理，这是官方实现的护城河；
模型无关——DeepSeek V4-Pro 同周涨价 1100%，模型切换自由是平台的生命线；
Supervisor/Swarm/Hierarchical 官方内置——演进路径现成；
Python + TS 双语言，社区最大。

中间有一个值得记录的决策插曲：用户问"Go + LangGraph 会不会更好"。没有硬答"行/不行"，而是查证：官方无 Go 版，Go 生态只有社区移植（LangGraphGo v0.8.2，非官方、API 不同步）。把事实摆出来后，用户自己拍板了 Python。

方法论：重大技术方向被质疑时，不替用户拍板——查证、给依据、让用户基于事实决策。这也是后来沉淀进 research 技能的一条原则。

1.5 架构设计的锚：ADR 先行，图定控制流

架构文档的写法比内容更值得学：先把不可变约束固化成 ADR，再展开细节。6 条 ADR 分别是：官方 LangGraph 内核、固定流水线起步、日志即真相、工具 Seam 三层、发布前人工确认（HITL）、模型无关。

然后是一张编排图定控制流：supervisor → research → write → review → publish，review 不合格条件边回写（≤3 轮），超限转人工；publish 前 interrupt()。这张图成为所有后续讨论的主入口——循环、条件、HITL 点全部可见，评审 30 秒看懂。

状态 schema（TypedDict）是组件间契约，先于节点实现；目录结构从职责边界推出（graph/agents/tools/observability/persistence/api）；事件日志表先于业务代码设计。

二、产品层：从"技术平台"到"内容生产流水线"

2.1 定位的过程：问出来的，不是想出来的

产品定位经历了两轮结构化提问：

做什么？→ 多 Agent 协作平台（单 Agent 只是组件，编排是核心）
第一个场景？→ 内容生产流水线（research → write → review → publish）

为什么是"内容生产"？因为它同时满足三个条件：流程可编排（角色边界清晰）、产出高频（每天都要内容）、错误代价高（写错价格/违规词/食安信息都是事故）——正好是"审核循环 + HITL + 事件流"这套机制最能体现价值的场景。

2.2 HITL 是产品哲学，不是技术细节

平台最核心的产品主张：发布前人工确认（ADR-005）。体现在三个层面：

审核循环：AI 审 AI（Reviewer 角色），不合格回写重写 ≤3 轮——把质量收敛交给编排；
超限转人工：3 轮仍不过，强制 interrupt() 交给人类——防死循环，也守住质量底线；
发布前确认：任何对外发布动作必须人工点头——不可逆动作永远留一道人类闸门。

这套设计让平台敢于"自动干活"而不失控，也让"高价值场景"（营销物料、食安声明）敢于交给它。

2.3 可观测性即产品：让用户看见 Agent 在干什么

"事件流"不只是调试工具，而是用户体验层：C 端任务详情页实时展示 stage/start、agent/request、tool/call、human/approval_requested，用户能看到内容是怎么一步步产出的。信任来自透明——这是"日志即真相"从技术约束升华为产品卖点的过程。

2.4 产品化的三个诚实边界

平台是内容生产引擎，不是对话引擎——客服类场景的形态是"话术草稿生成"，不是实时聊天机器人；
数据接入（订单/库存/价格）需要走工具 Seam 扩展，编排零改动，但要付出工具开发成本；
定时发布（晚市清货推送）需要 publish 节点加 scheduled_at——小改动，但要规划。

场景架构示意图

对应：server/app/pipeline/types.py · server/app/persistence/scenario_seed.py · server/app/pipeline/scenarios.py 本节说明 29 个场景如何挂载到固定图结构上，是 §三应用层的先决知识。

1. 系统调用链

┌─────────────────────────────────────────────────────────────────────────┐
│                          用户提交任务（C 端）                              │
│                         POST /tasks { target }                           │
└───────────────────────────────┬─────────────────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────────────┐
│                        ScenarioRegistry（运行时注册表）                     │
│                                                                         │
│   ┌──────────────────────────────────────────────────────────────┐      │
│   │  代码默认 (TASK_TYPES, 3 条)          DB 覆盖 + 自定义 (26 条)  │      │
│   │  ┌──────────────────────────────────────────────────────┐     │      │
│   │  │ content       → targets: {wechat_article, video_...}  │     │      │
│   │  │ direct_answer → targets: {direct_answer}              │     │      │
│   │  │ video_short   → targets: {video_short}                │     │      │
│   │  └──────────────────────────────────────────────────────┘     │      │
│   │                          ▼                                      │      │
│   │  ┌──────────────────────────────────────────────────────┐     │      │
│   │  │ 生鲜行业场景 (26 条，seed 写入 scenarios 表)           │     │      │
│   │  │ live_script │ batch_video │ new_store_launch │ ...   │     │      │
│   │  └──────────────────────────────────────────────────────┘     │      │
│   └──────────────────────────────────┬────────────────────────────┘      │
│                                      │ resolve_target(target)             │
└──────────────────────────────────────┼───────────────────────────────────┘
                                       │
                    ┌──────────────────▼──────────────────┐
                    │         supervisor 节点              │
                    │   target → TaskType → pipeline       │
                    └──────────────────┬──────────────────┘
                                       │
                    ┌──────────────────▼──────────────────┐
                    │      LangGraph 图（固定 8 节点）       │
                    │                                      │
                    │  research → write → video_gen → ...  │
                    │                          ▲            │
                    │                          └ 条件边      │
                    └──────────────────────────────────────┘

关键设计：图结构（8 个节点 + 条件边）零改动，新场景只需在注册表加一条 TaskType。

2. Target → Scenario → Agent 分层模型

  ┌─────────────────────────────────────────────────────────────────────┐
  │  Target（入口）          用户选择 "公众号文章" / "晚市清货" 等       │
  │  targets 表              23 个 target，每个有 name + label          │
  └────────────────────┬────────────────────────────────────────────────┘
                       │ 属于（多对多）
  ┌────────────────────▼────────────────────────────────────────────────┐
  │  Scenario / TaskType（类型）          29 个场景                     │
  │  scenarios 表（DB 真相源）             每个场景声明：                  │
  │                                        • targets（哪些入口可用）      │
  │                                        • roles（角色序列）            │
  │                                        • pipeline（节点序列）         │
  └────────────────────┬────────────────────────────────────────────────┘
                        │ 解析出
  ┌────────────────────▼────────────────────────────────────────────────┐
  │  Agent（角色）                         research / write / review /   │
  │  agent_configs 表                     publish / cs_writer / ...     │
  │  （prompt / model_tier / tools / skills）                            │
  └─────────────────────────────────────────────────────────────────────┘

3. 图节点 × 场景复用矩阵

所有场景共享同一张图（8 个节点），通过 pipeline 字段决定走哪些节点：

图节点（固定，不可新增）
┌──────────────────────────────────────────────────────────────────────┐
│   research    write    review    publish_confirm    review_escalate  │
│      │         │         │              │                  │         │
│   video_gen  publish                                          (interrupt)│
│                                                                      │
│   ● 机制节点（不走 agent，纯 interrupt 操作）：                       │
│     publish_confirm   — 发布前人工确认                               │
│     review_escalate   — 审核超限转人工                               │
│   ● Agent 节点（需配置 agent 角色）：                                │
│     research / write / review / publish / video_gen                  │
└──────────────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         ▼                    ▼                    ▼
  需研究素材的场景       需视频生成的场景      需升级审核的场景
  content/new_store      batch_video          food_safety_response
  competitor/knowledge                   trust_content / trust_matrix

  ─────────────────────────────────────────────────────────────
  其余 ~18 个场景走标准流水线：write → review → publish → publish_confirm
  ─────────────────────────────────────────────────────────────

节点	出现场景数	说明
`write`	29	全部场景必过
`review`	~20	需人工审核的场景
`publish`	~20	review 通过后进入
`publish_confirm`	~20	发布前 HITL 确认
`research`	~6	需外部素材支撑
`video_gen`	1	仅 batch_video
`review_escalate`	3	food_safety/trust_content/trust_matrix

4. 29 场景分类树

  29 场景
    ├── Builtin（3）
    │     ├── content        内容生产（公众号/视频脚本/社媒）
    │     ├── direct_answer  直接问答
    │     └── video_short    AI 短视频（write→video_gen→review→publish）
    └── Custom（26，seed 写入 scenarios 表）
          ├── A. 营销内容域（6）：live_script / batch_video / new_store_launch
          │     / community_daily / multi_channel_listing / competitor_monitor
          ├── B. 客服售后与信任域（5）：customer_service / food_safety_response ←review_esc
          │     / knowledge_faq / trust_content ←review_esc / member_touch
          ├── C. 私域与渠道域（4）：leader_pack / ugc_remake / member_daily / staff_training
          ├── D. 日清模式专属域（7）：evening_clearance / fresh_daily / last_stock_push
          │     / trust_matrix ←review_esc / supply_plan / weather_alert / bundle_meal
          └── E. 内部治理域（5）：daily_report / loss_report / overnight_loss
                / sell_by_prompt / store_clearance_script

5. Pipeline 形态分布

  形态 1（~18 个）：write → review → publish → publish_confirm
  形态 2（~5 个）：research → write → review → publish → publish_confirm
  形态 3（1 个）：write → video_gen → review → publish → publish_confirm  [batch_video]
  形态 4（3 个）：write/research → review_escalate → review/publish → ...

三、应用层：从通用平台到生鲜行业

3.1 应用的本质是"能力 × 业务"的映射

把平台能力盘出来：多角色编排、审核循环、HITL、事件流、B 端配置、工具扩展、模型无关。然后问：生鲜公司哪里"内容高频、错不得、要留痕"？

三轮 brainstorm 共沉淀 29 个场景，完整清单见 §3.3（按业务域归类）。初期按贴合度分三档：

A 类（平台原生直出）：营销活动物料、社群日更、详情页多端、直播/短视频、天气联动、培训等；
B 类（扩展工具后）：客服工单、食安投诉、会员触达、团长赋能、备货预测等；
C 类（内部治理）：经营日报、损耗治理/归因周报。

3.2 日清模式的启示：业务约束重塑场景

当用户说"我们是日清模式"（当日到货当日清，不卖隔夜菜），场景设计逻辑被整个改写：

库存从"静态"变"当日动态"→ 内容必须当日生成当日用；
晚市清货时段成为全天最有价值的营销窗口（18:00 预告 → 20:00 实时清货推送）；
"不卖隔夜菜"本身是最强品牌资产 → 信任内容矩阵；
备货预测直接决定损耗 → 预警内容从源头降损耗；
天气是当日销量的最大变量 → 雨天应变双轨内容（对客促销 + 内部备货调整）。

方法论：行业应用不是"把通用方案套上去"，而是先找到业务的核心约束（日清、损耗、时效），让约束反向设计场景。通用平台提供能力，业务约束决定怎么组合。

3.3 场景全景（三轮推演共 29 个）

三轮 brainstorm（通用场景 → 内容矩阵 → 日清模式专属）沉淀出 29 个场景，按业务域归类如下。

A. 营销内容域（8 个 · 平台原生直出为主）

场景	一句话	优先级
每周营销活动物料流水线	促销活动从选品到多端文案一条线	P0
社群每日运营内容	每天 3-5 个群按画像差异化推送	P0
商品详情页/多平台上架素材	新品/应季 SKU 一次生产、多平台差异	P0
节气/天气联动营销	暴雨囤菜提醒、24 节气日历	P1
直播脚本流水线	选品顺序/口播话术/福利节点/互动引导	P0
短视频批量生产	选题→脚本→抖音/小红书/视频号差异化标题	P0
新店开业/加盟营销包	预热→开业→店庆全链路模板化	P2
竞品监测与应对内容	竞品价格/活动监测→合规应对内容（需爬虫工具）	P2

B. 客服售后与信任域（5 个 · 扩展工具为主）

场景	一句话	优先级
客服工单话术助手	高频投诉生成个性化回复稿（需订单/CRM 工具）	P1
食安投诉/声明响应	批次调查→回复稿/公告，法务+品控强 HITL	P2
生鲜知识库 & FAQ 生产	质检/产地/保存方法白话化，喂客服与社群	P1
食安信任内容（检测解读）	检测报告→白话解读+冷链透明化，证据链 HITL	P2
会员个性化触达	生日关怀、复购唤醒（需会员数据工具）	P1

C. 私域与渠道域（4 个）

场景	一句话	优先级
团长/分销商赋能内容包	每团长一键生成推广文案+海报（需团长画像工具）	P1
用户晒单 UGC 再创作	好评转官方种草内容，授权合规审核	P2
会员"日清专享"复购内容	每天固定时段推"今日到货+会员专属价"	P1
门店店员培训内容	生鲜知识/损耗控制周报	P2

D. 日清模式专属域（7 个 · 平台核心价值区）

场景	一句话	优先级
晚市清货倒计时营销 ⭐	18:00 预告→20:00 实时清货推送（剩余库存→折扣梯度）	P0
"今日鲜"每日内容流	早 7 点到货后 1 小时内产出当天内容	P0
"最后 X 份"紧迫感推送	将售罄→即时限量内容（真实性核对，禁假缺货）	P1
"不卖隔夜菜"信任内容矩阵 ⭐	把日清卖点做成品牌资产（检测/冷链证据链）	P2
备货预测与损耗预警	明日备货建议+天气预警（源头降损耗）	P1
雨天/极端天气当日应变	对客"雨天新鲜直送"+内部备货调整双轨	P1
今日"菜篮子"套餐内容	按库存组 3 菜 1 汤套餐+做法，一键下单	P2

E. 内部治理域（5 个）

场景	一句话	优先级
经营日报/周报	销售数据→管理层报告	P2
损耗治理周报	损耗数据→改进建议+门店提醒	P1
隔夜损耗归因周报	日清率 KPI 归因（备货多/价格高/天气）	P2
门店清货话术与激励	店员清货推荐话术+激励海报（日清靠一线执行）	P2
临期品清库存菜谱引擎	按库存生成"今日特价+做法"内容	P1

3.4 场景 × 平台能力映射（落地前必看）

平台能力	场景	说明
原生直出（零新增）	A 类全部、知识库/食安信任/信任矩阵/清货倒计时/今日鲜/菜篮子/清货话术/店员培训	改 prompt + 角色配置即用，B 端可运营
扩展工具（Seam 三层接数据源）	客服工单、食安投诉、会员触达、团长赋能、竞品应对、备货预测、损耗周报/归因、"最后 X 份"	只加 read_only 查询工具，编排零改动
新增平台能力	清货倒计时/会员日清专享/雨天应变（定时推送）	publish 节点加 `scheduled_at` 字段，发布管理支持计划任务

3.5 应用层推荐的落地顺序

P0（日清最痛）: 晚市清货倒计时 + 今日鲜内容流
P1:            会员日清专享 + 备货预测预警
P2:            信任内容矩阵 + 损耗归因周报

选 P0 的理由：直接对日清率这个核心 KPI，说服力最强，且平台原生能力直出（零新工具）。

四、AI 编程真实落地：流程、踩坑与思考

4.1 我们实际跑的工作流

真实落地不是"AI 替人写代码"，而是一套人机协同的工程流水线：

调研(research 技能) → 架构(architecture-design 技能) → 开发(python-backend/nextjs-frontend)
→ 审查(code-review 技能) → 收尾(project-workflow 三件套) → 沉淀(self-improving-agent)

配套的硬纪律（写进 AGENTS.md）：TDD 强制（test 提交在前，feat 在后）、小步频繁提交、日志即真相、HITL 不绕过、文档三件套（迭代记录 + 版本计划 + issues-log）、契约先行（改接口先改 api-contract）。

4.2 真实踩坑实录（都是学费）

坑	教训
LangGraph 1.x checkpoint 要求 config 里必须有 `thread_id`（只传业务 id 会 `KeyError: 'thread_id'`）	新框架 API 差异大，先跑最小骨架验证，别按旧知识写
pip 在沙箱里被 safe-delete 拦截（清缓存触发批量删除确认）	受限环境用 `--no-cache-dir` 规避
`pytest	tail` 前台看似卡死，实为管道缓冲
MySQL 版本红线：checkpoint 要求 `≥8.0.19 且 <9.6`；`mysql:latest` 已滚到 26.x、5.7 建表 1064	社区包有隐式版本边界，选型必查；显式锁 `mysql:8.4` LTS
pymysql 非线程安全：checkpoint（LangGraph 线程池）与事件日志/业务表（主线程）必须各持独立连接，复用会 `read of closed file`	多线程架构下连接隔离是硬规则
LangGraph 挂起返回值含 Interrupt 对象（不可 JSON 序列化），保存快照前必须剔除 `__interrupt__`	序列化边界要显式处理
新建 `app/api/*.py` 忘记 `app.include_router(router)` → 路由静默缺失（404 无报错）	自检 `[r.path for r in app.routes]`
React 19 lint：effect 体内禁止同步 setState（`react-hooks/set-state-in-effect` error）	初始化副作用放 .then 回调 + useRef 守卫
MCP 远端工具 read_only 判定依赖厂商是否声明 `readOnlyHint`，未声明默认"需审批"	查询类工具会集体误判，B 端需人工修正

这些坑没有一个是"算法难题"，全是工程现实——而它们恰恰是 AI 编程最容易翻车的地方（AI 会自信地写出"看起来对"的代码）。这也是 TDD + 真实运行验证如此重要的原因。

4.3 并行开发的新现实

真实落地中一个高价值的发现：多个 AI 会话并行开发。git log 显示 v0.1~v0.4 分支和大量提交来自并行推进，甚至出现过两个会话同时创建同主题技能（research vs research-method）的冲突。处理原则：

不擅自删除并行产物（先告知用户，由用户决策合并或保留）；
技能表标注职责边界，避免重复；
AGENTS.md 作为总纲，是并行会话共享的"宪法"，谁改都要遵守纪律。

多会话并行的管理，本质是把"团队协作的 Git 纪律"延伸到 AI：分支隔离、契约先行、文档同步、冲突显式化。

4.4 AI 编程的纪律：为什么 AGENTS.md 是核心

这个项目里 AGENTS.md 不止是给 AI 看的说明书，它是一份可执行的工程宪法：技术栈锚定（防止 AI 用过时知识写代码）、硬性纪律（TDD/HITL/日志）、环境注意事项（每次踩坑都回填）、版本路线图（进度对齐）。配合 .agent/skills/ 的技能闭环（research → architecture-design → python-backend/nextjs-frontend → code-review → project-workflow → self-improving-agent），AI 的每次产出都有流程约束和验收标准。

4.5 本项目用到的 Skill 全景与串联

技能不是"一堆模板"，而是一条接力流水线：每个 skill 有明确的触发时机、输入契约和输出产物，上一个 skill 的产物就是下一个 skill 的输入。分两层：项目级技能（.agent/skills/，随仓库版本化、按本项目定制）与运行时内置技能（Reasonix 平台自带、不落仓库、任何项目通用）。

4.5.1 项目级技能清单（12 个）

Skill	定位	触发时机	输出产物
`grill-me`	需求追问（GRILL 五问：Goal/Range/Inputs/Logic/Legacy）	任何新需求/变更之前，强制	「需求共识」段落，用户确认后才可继续
`research`	引导式调研（澄清→拆解→两段式搜索→交叉验证→结论先行报告）	技术调研/选型/生态查证/新领域扫盲	调研报告（标来源、≥3 来源交叉）
`architecture-design`	架构设计流程（澄清→调研→决策→ADR→编排图/状态 schema/数据表→风险与路线图）	新系统/新项目/大功能从 0 到 1	ADR + 编排图 + 状态 schema + 目录结构 + 路线图
`python-backend`	后端 TDD（FastAPI + LangGraph + 工具 Seam 三层 + 事件日志）	写/改后端时	pytest 全绿的代码 + 契约同步（api-contract）
`ui-new`	UI 设计先行（页面结构/组件划分/设计 Token/交互稿）	需求明确后、前端代码前，先出方案让用户确认	页面级 UI 设计方案
`nextjs-frontend`	前端实现（App Router + TS + Tailwind/Design Token + lib/api.ts）	按已确认的 UI 方案写代码时	通过 `pnpm lint && type-check && build` 的界面
`code-review`	风险优先审查（`文件:行号` + 影响 + 置信度，Critical/Major 阻断）	代码完成、合并前	分级 findings，阻断项修复后重审
`project-workflow`	流程编排器：把 Phase 0~6 串成流水线，按阶段加载子 skill	开始新版本/新需求/里程碑收尾	各阶段验收标准与验证命令
`project-docs`	文档三件套（迭代记录/版本计划/issues-log）	任何文档变更或版本收尾	三件套文件齐全
`impeccable`	高品质前端视觉（排版/色彩/动效/响应式/设计系统）	需要非泛化审美的高质量界面时	设计指导与代码模式
`rn-project`	React Native 移动端（脚手架/打包/模拟器预览/RN 0.87 硬坑）	移动端任务时	可运行打包的 RN 工程
`self-improving-agent`	经验沉淀（LRN/ERR → 可复用资产）	里程碑收尾、踩坑后	`.learnings/` 条目 + AGENTS.md 环境坑回填

4.5.2 运行时内置技能（Reasonix 自带，迭代中高频使用）

Skill	定位	用在哪儿
`explore` / `read_only_task`	只读子代理探查代码库，只回传蒸馏结论	进入不熟悉的代码区前先探查，避免主上下文被大段读取污染
`review` / `security_review`	对当前分支 diff 做风险/安全审查（文件:行号）	PR/合并前，与项目级 `code-review` 互补：一个 diff 级通用审查，一个项目定制纪律审查
`init`	初始化/刷新项目 AGENTS.md	项目起步、目录结构变化后
`install-capability`	安装 MCP server / 技能（URL/本地路径/.mcp.json）	需要新工具链/新技能时
`docs` / `reasonix-guide`	查 Reasonix 平台自身文档与配置排查	平台级问题（技能优先级、配置、MCP 故障）

4.5.3 它们如何串联：一条里程碑的接力

新需求进来
   │
   ▼
grill-me ──→ 「需求共识」（等用户确认）
   │
   ▼
project-workflow（总编排，Phase 0→6，每阶段加载对应子 skill）
   │
   ├─ Phase 0 规划：版本计划条目（验收标准含：范围纪律 + 规则显性化）
   ├─ Phase 1 分支：feature_vX.Y_name + 按改动面加载子 skill
   ├─ Phase 2 后端：python-backend（RED→GREEN，test 提交在前）
   │        └─ 产物：pytest 全绿 + api-contract 同步
   ├─ Phase 3a UI：ui-new 出方案 → 用户确认
   ├─ Phase 3 前端：nextjs-frontend 按方案实现
   │        └─ 产物：lint + type-check + build 通过，规则可见性检查
   ├─ Phase 4 审查：code-review（+ 运行时 review/security_review）
   │        └─ 阻断项修复 → 重审通过
   ├─ Phase 5 文档：project-docs 三件套
   └─ Phase 6 沉淀：self-improving-agent（LRN/ERR）→ AGENTS.md 回填

接力点（上一个的输出 = 下一个的输入）：

交接	输入 → 输出
grill-me → project-workflow	需求共识 → 版本计划条目（验收标准）
python-backend → ui-new / nextjs-frontend	api-contract 契约 → 前端类型与请求对齐
ui-new → nextjs-frontend	UI 设计方案（用户确认）→ 界面实现
全部代码 → code-review	完整 diff → 分级 findings → 修复 → 重审通过
code-review → project-docs	审查结论 → 三件套记录关键决策与问题
project-docs → self-improving-agent	问题清单/踩坑 → LRN/ERR 沉淀 → AGENTS.md 环境坑

两条铁律如何横切所有阶段：范围纪律（只做用户明确要求的）在 grill-me 追问时锁定边界、Phase 0 写进验收标准；规则显性化（业务规则必须在 UI 可见）在 Phase 0 验收标准强制写一条"该规则在界面哪里可见"，Phase 3 前端逐条检查，Phase 4 code-review 复核——它们不是某个 skill 的附注，而是贯穿整条流水线的验收条件。

五、总结：从 0 到 1 的可复用方法论

5.1 三条主线

决策先行，证据驱动：每个重大选择（单/多、框架、语言、数据库）都是"查证 → 权衡 → 决策 → ADR 固化"，不拍脑袋；
渐进落地，演进有触发条件：M0 骨架 → M1 单角色 → M2 HITL → M3 动态分流，每步有验收标准，不一步到位；
沉淀闭环，学习制度化：调研/架构/开发经验沉淀为技能（research/architecture-design/python-backend），踩坑沉淀为 LRN/ERR，通用坑回填 AGENTS.md。

5.2 一张时间线（从 0 到 1）

08-16 调研（dsh + 单vs多共识） → 选型（LangGraph）→ 架构设计（6 ADR + 编排图）
     → 基础设施（AGENTS.md/docs/技能重建）→ git 初始化 → 自查修复（事件枚举/health/README/env）
     → M0 骨架（图+checkpoint+事件日志，假数据跑通）
08-16~08-19 M1（真实模型+工具）→ M2（HITL+审批+SSE+MySQL 固化）→ M3 进行中（supervisor 动态分流）
08-19 生鲜应用推演（通用场景 → 日清模式专属场景）

5.3 学习清单（个人/团队可复用）

调研：先"是什么"后"怎么看"，≥3 来源交叉，结论先行；
决策：ADR 先行锁不可变约束；被质疑就查证给依据，不替用户拍板；
架构：一张控制流图 + 状态 schema 契约 + 核心表先设计 + 风险表 + 渐进路线图；
工程：TDD 强制、小步提交、契约先行、日志即真相、HITL 兜底；
AI 编程：AGENTS.md 宪法化、技能闭环、并行会话用 Git 纪律管理、踩坑即时回填；
应用：找业务核心约束（日清/损耗/时效），让约束设计场景，而不是硬套通用方案；
沉淀：可复用流程技能化、踩坑进 ERR、通用坑提升到 AGENTS.md——自我改进是闭环，不是口号。

六、附：关键资产索引

资产	位置	用途
调研报告	`docs/agent-architecture-research.md`	单 vs 多 Agent 决策依据
选型报告	`docs/agent-framework-comparison.md`	LangGraph 胜出对比
架构设计	`docs/agent-platform-architecture.md`	ADR/编排图/事件枚举/路线图（唯一核心）
架构复盘	`docs/architecture-writing-guide.md`	从调研到架构的方法论
自查报告	`docs/project-self-check.md`	前期工作完整性审计
项目总纲	`AGENTS.md`	技术栈/纪律/环境坑/路线图
技能闭环	`.agent/skills/`	grill-me / research / architecture-design / python-backend / ui-new / nextjs-frontend / code-review / project-workflow / project-docs / impeccable / rn-project / self-improving-agent（共 12 个，详见 §4.5）
经验库	`.learnings/`（LRN/ERR）	学习与错误沉淀

最后一句：这个项目最值得记住的，不是用了 LangGraph，也不是做成了内容平台——而是一套让"从 0 到 1 的思考"不丢失、可复用、能闭环的工程方法。技术会过时，方法论不会。