Centrol 代码深度分析：Agent 怎么搭的、哪里是毛线团、业务流程与代码流程对照

调研日期：2026-11-05。对象：repos/CentrolAI main 分支（579 次提交，最后提交 2026-11-05，主要作者 Gloridust）。
起因：合伙人在 Lark 上的八轮反馈（Feedback 1.0 → 8.0，2026-08 至 2026-11-04）里，大量问题反复出现、改了又回来；开发方自己的评价是「不够智能、不够灵活、很难跑通」。
方法：先读仓库自己的架构文档与 37 份 ADR、46 份踩坑笔记，再分五路只读通读源码（Agent 内核、旧 lib/ai 层、数据层与状态机、九步业务流程逐步追代码、Funyard 工程做法对照），每条结论都对到文件和行号。文档与代码不一致时以代码为准。
读者：我们自己（决定要不要在这套代码上继续做）和合伙人（理解为什么反馈改不动）。

0. 一页结论

这个 Agent 的「形状」是对的，但「骨架」没有。 2026-10-16 的重构（ADR 0026）把对话 Agent 做成了常驻、一步一落库、能被事件叫醒的会话，这一步解决了「Agent 只活 95 秒」的根本问题，方向和业界（Anthropic Managed Agents、pi）一致。但它没有替换旧层，而是在旧层上加了一层「名字翻译 + 权限判定」：真正的业务逻辑（匹配 977 行一个函数、梯子 985 行一个函数、工具执行 31 个 case 的 switch、SMTP 投递 607 行）仍留在 2026-08 起堆出来的三个巨型文件里。

「毛线团」不是风格问题，是七件结构性的事叠在一起：

对我们的含义： 它不是一个能在上面「继续加功能」的代码库，而是一份非常详细的、用血换来的需求与坑位清单（37 份 ADR + 46 份踩坑笔记 + 37 份评测场景）。真正值钱的是这些知识和几块做对了的部件（见 §6），不是这 8.8 万行 TypeScript 本身。

1. 这个 Agent 是怎么搭的

1.1 四个「大脑」与它们的分工

文档里说「一个常驻的活动 Agent」，代码里实际并存四个决策者，互相靠事件和数据库列沟通：

ADR 0026 承诺的「谈判 → 主 Agent 的结构化报告 negotiation_report」在代码里不存在，替代物是事件旁路：只有升级、匹配完成、审片完成会叫醒主 Agent，成交和回绝不叫醒，主 Agent 要等下一次用户说话时才从事件日志里读到。

1.2 一轮对话（turn）端到端

浏览器 POST /api/copilot                         app/api/copilot/route.ts
 ├ requireOrg（余额 ≤ 0 直接 402）→ 用户消息先落库 append_thread_message
 ├ beginUserTurn：insert agent_runs{kind:turn, status:running}      lib/agent/store.ts:234
 │   锁 = 迁移 0061 的部分唯一索引 agent_runs_one_live_turn（一个对话同时只有一轮）
 │   插不进去 → 接手排着的那行 / 回 {queued:true}
 ├ ReadableStream(ndjson) + runTurn({inline:true, deadline:+95s})   lib/agent/loop.ts:112
 └ after()：compactCopilotThread 折叠长对话进 context_digest

runTurn 主循环，每圈：
 ① 查 threads.agent_cancel_at（真的能停）
 ② 上一步没执行完的工具 → executeCall
 ③ 拼上下文：loadLiveState（实时状态块）+ loadLog（thread_messages）+ 最近 6 轮 agent_steps
    → projectLog（按模型「当时看到的顺序」重排；补 user 结尾）
    system = agentSystemPrompt（≤4k）+ context_digest，<now> 贴在最后一条消息末尾
 ④ streamWithTools（lib/ai/client.ts:888）边流边推给浏览器
 ⑤ appendStep(role:assistant, tool_calls) → 回 ①

executeCall（loop.ts:400）：
  effectOf(tool)（read / external / config / money / delete …）
  → userSaidIt 正则 → gateRule（效果 × 来源 × 是否读过外部文字）→ run / ask / classify
  → classify 时调一个只看用户原话的分类器
  → ask 时 postCard（approval_requested 事件）
  → run 时 executeAgentTool（lib/agent/toolbox.ts）→ 多数转 runTool（lib/ai/tool-exec.ts）
    部分直调 lib/data/actions，部分直接 .from() 写表
  → appendStep(role:tool)

收尾：appendMessage(assistant) + chargeFeature（幂等键 turn:<run>）+ finishRun
超时：handoffRun（status→queued，attempts 清零）→ cron 认领 → runner HANDLERS.turn
     → withSystemActor（无用户会话时用「系统执行身份」）→ runTurn(inline:false, 240s)
     已有结果的 tool_call_id 不重做

做对的部分：一步一落库、唯一索引当锁、tool_call_id 去重、requeueRun 合并排队行，这四件事真正解决了「95 秒」问题。gate-rules / consent-rules / projection / wake-rules 是纯函数，能裸 node 测。withSystemActor 让被叫醒的 Agent 和人点按钮走同一组函数，没有另写一套 worker 版。

但 loop.ts 也承担了本该在协议层或网关层解决的「模型行为矫正」：按书写系统压流（中文里闪英文）、整段回复再调一次模型翻译（fixReplyScript）、模型说了要做没做就替它排任务（keepBriefPromise）、叫醒时和上一条没答的问题两字一组重合 ≥55% 就删掉（dropRepeatedQuestion）。主循环 56 个 if、12 个出口；lib/agent/ 里带 2026-10 日期的事故注释 109 处，这个目录 3 天内 31 次提交。

1.3 被叫醒（wake）与驱动器梯子

• wake 怎么来：appendThreadEvent(..., {wake}) → requestWake：插一行 agent_runs{kind:wake, queued, next_attempt_at +60s} 去抖；撞唯一索引就把原因并进排着的那行。闹钟走 agent_timers → fireDueTimers。
• 限额与计费：decideWake 依次查总开关 → 对话在不在 → 暂停 → 每日上限（默认 24）→ 余额；入队判一次、认领再判一次。wake 扣 agent_wake，turn 扣 copilot_reply。
• 梯子：advanceCampaign 一个函数 985 行、61 个 if、16 个提前 return，档位 ⓪ 起草 brief → ① 放行待批 → ② 草稿入队 → ③ 挑人 → ④ 来信没回 → ⑤ 追信/放手 → ⑥ 补人 → ⑦ 没事干。每拍从 loadLadderRows 重读，「在哪一步」由 status + outreach_queued_at + defection_reason + nudge_count + hold_until + keep + autopilot_blocked_at + pending_actions + thread_messages 里的卡 推导。decide() 在主梯子里调 9 次，其中一处「deny 之后再判一次 auto」。返回值是 23 种自由字符串。同一文件尾部的分段注释和头部编号对不上（两套编号）。
• 判断：这是一个「每两分钟跑一遍的巡检脚本」，不是状态机。没有状态枚举、没有转移表；每档内部按 auto / ask 两条路各写一遍。

1.4 谈判子 Agent

文档说「四道闸：detectEscalation → complete → screenMessages → decide」。代码实际是：入口升级检测（仅非跟进、非人工改稿）→ 最多 2 轮工具查资料 → 生成 → WAIT 判定 → 截断判定 → 风格闸 → 繁简转换 → 单号/人填价核对 → agreedFee 分支（内含 decide）→ maxOffer 分支 → 跟进分支（内含 decide）→ 主 decide。blocked() 17 处、decide() 3 处分散在三条分支里。negotiation-context.ts 拼输入时顺手写库（更新 quote、first_ask）。

护栏做对了：价格上限、让步次数卡在 policy.ts 判定表和出参校验里，不指望模型遵守；「只有 SMTP 成功才算寄出」；回信按人设工作时段排 deliver_at。

1.5 队列、邮件、计费

• 队列 agent_runs：14 种 kind、5 种 status；claim_next_run 最终版约 70 行，WHERE 里 11 个条件（queued、退避、对话已删、活动已删、campaign 沙盒、thread 沙盒、org 挂起、org_balance()>0 每行调一次聚合、活动暂停的 5 种 kind、同 chat_session 已有 negotiate、同 thread 已有 turn/wake），再 for update skip locked + 捕获 unique_violation 兜底。这个函数被整体重写 8 次（0011/0023/0027/0035/0051/0060/0061/0062）。插入 agent_runs 的代码散在 10 个文件 27 处。
• 邮件：出站只有 runner.deliverDueMessages（607 行，放在 Agent 队列消费者文件里）真正调 SMTP；但「往 messages 表插一行」的入口 ≥8 处，各自拼节奏和 outreach_queued_at。入站 mail/route.ts 871 行：剥引用 → 判类型 → 按线程头 / 发件人认领行 → 立刻把行改成 replied → 排 negotiate。
• 计费：feature_prices 一功能一价，record_usage 幂等（只在调用方传幂等键时生效），metering/context.ts 带三层「迁移没跑」降级。扣费点 65 处 / 15 个文件。「没额度」的判定点有 6 处、口径不一。

2. 业务流程 ↔ 代码流程

下表每步给出：触发 → 入口与链路 → 写哪些表/状态 → 写哪些事件 → 界面怎么知道 → 已知问题。路径相对 src/lib/。

一拍能串起多少层：cron → runNextJob → claim_next_run（11 条件）→ HANDLERS[kind] → 跑完 chainAdvance 排 advance → 下一拍 advanceCampaign → propose 出卡 / 排 outreach、negotiate、match → 跑完写事件 → requestWake（60s 去抖）→ 下一拍 runTurn。用户看到的「on it」卡住，是这条链里任何一环（积分闸、暂停闸、cron 延迟、kickQueue 无 origin、建活动前没有 campaignId 导致 useRunningJobs(null) 返回空）的统一表现，前端没有「做到哪一步」的机制，只有同一请求内的 liveSteps。

前端怎么知道后台在干嘛：useRunningJobs(campaign.id) 每 3s 轮询只查有 campaign_id 的 queued/running 任务；对话气泡和右屏共用这一份。请求超时 handoff 后，气泡「还在处理」只在 5s 轮询拉到 assistant 消息或 run_failed 事件才消失。卡片由 approval_requested / approval_resolved 事件按 key 重建。

3. 毛线团在哪：七条根因

3.1 没有领域层，没有状态机

• lib/data/actions.ts 4,106 行、55 个 server action，直接拼 PostgREST 查询；典型形状是 supabaseServer() → .from("campaigns").insert → .from("guardrails").insert → revalidatePath。横切全靠手写：supabaseServer() 51 次、requireOrg( 28 次（即约一半 action 不走它、靠 RLS）、appendThreadEvent( 23 次、revalidatePath( 49 次、userError( 156 次。
• declineAsk 550 行（3299–3849），内部按 action 字符串分 11 支，实为「确认卡执行器」；closeDeal 238、sendOutreach 205、counterOffer 191 行。
• 创作者 13 态（status.ts:28-41）没有转移表，grep 不到任何 transition / canTransition。campaign_influencers.status 在 10 个文件 33 处裸写；setRowStatus（actions.ts:618）让 UI 传什么写什么；awaiting_reply 曾是「画得出来、全项目没有一处写入」的状态（advance.ts:2423 注释自述）。活动状态 campaigns.status 只在 runner.ts:1226 写过一次 strategy，界面改为从管道行推导，status.ts:228-237 注释承认库列已漂移。
• 两张核心表：campaigns 初始 26 列、14 个迁移 ALTER、最终 45 列；campaign_influencers 初始 20 列、15 个迁移、最终 44 列。一行里同时存状态、子状态标记（outreach_queued_at / excluded_at / hold_until / no_followup / keep / defection_reason 当「升级中」）和缓存（thread_digest ×4）。每个新需求 = 加一列 + 加一个写入点 + 加一段 if。

3.2 新内核叠在旧层上，三层工具体系，双向依赖

• 模型看到的是 agent/toolbox-spec.ts 的 29 个工具（文件头注释写「没有活动时 4 个，有了 22 个」已过时）；agent/toolbox.ts 916 行里约 770 行是新逻辑：14 个纯转发 runTool，13 个自写（creators_query、campaign_get 5 个 section、negotiation_instruct、creators_update 14 个 op 里 9 个自写…）；旧 ai/tool-exec.ts 2,058 行 runTool 31 个 case 仍是唯一执行层，47 处直接 .from() 写表，remove_creators case 87 行已不可达。
• toolbox 的 remove（377–409）与 tool-exec 的 remove_creators（1200–1278）同一套 removable / keptDeals / contacted 口径各写一遍，注释自承「同一套口径」；候选过滤口径在 agent/creator-filter.ts 第四次实现。
• ai/tools.ts 949 行（31 个旧工具定义）在 src 内唯一引用是 toolbox-spec.ts:25 借 15 个 schema；tier、description 只有 scripts/test-*.mjs 在读。运行时约九成是尸体，但平价测试还按它查，谁也不敢删（backlog 里记着「实现层工具说明的去留 P3」）。
• 依赖方向：agent → ai 静态 import 16 处；ai → agent、data → agent 全是 await import 或类型引用（runner.ts:32 唯一静态）。tool-exec ↔ toolbox、runner ↔ job/store、actions ↔ toolbox/triggers 三对双向依赖靠动态 import 规避循环。「内核在 lib/agent」并不成立：内核仍依赖 ai/ 与 data/ 的大量旧实现。

3.3 横切关注点没有落点

• 权限 decide() 分布 12 个文件；tool-exec.ts 只有 3 处、advance.ts 13 处、negotiate.ts 3 处；agent/gate-rules.ts:13 注释：「钱的上限在工具里面的 decide()」。同一动作在 toolbox 权限层、tool-exec、runConfirmedAction 三层各判一段。
• 事件 appendThreadEvent 90 处 / 17 文件，runClaimedJob（runner.ts:3955）注释自承「七个地方要记得写、漏一个不报错」。写事件失败吞掉只打日志（thread-events.ts:66-69）——而事件是状态源（§3.5）。
• 计费 65 处 / 15 文件（actions.ts 25、runner.ts 16）。
• 重试策略靠中文错误串子串匹配（runner.ts:3321-3340 NO_RETRY），加一份文案编号 NO_RETRY_KEYS，两套并存，注释自承前者认不出英文版。

3.4 同一件事多份实现

ARCHITECTURE.md §13 自己写「已应验五次」，实测更多：

3.5 队列表和事件表身兼数职

• agent_runs 既是队列（14 种 kind）、又是锁（4 个部分唯一索引当锁：advance、negotiate 按 input->>'chat_session_id'、turn running、turn queued）、又是进度表（progress / total / output）、还是续跑状态容器（input 自由 JSON 里存 stalls / handoff_steps / time_waits / began_at，靠 run-merge.ts 手工合并）。claim_next_run 把暂停、沙盒、余额、删除四种业务闸都塞进认领 SQL；自述「八道闸」，改动前要读 5 个迁移头。
• thread_messages 既是给人看的对话，又是事件日志，又是状态源：确认卡开/关（propose.askStatus limit 1、propose 列开着的卡 limit 500、threads.openAsksByThread limit 600 自带去重 reducer、actions.settleOutreachCards limit 300 自己写 Map 回放、runner.ts:2589 limit 5）、冷却期、积分提醒，9 处各扫一遍、limit 各异，同一张卡在不同入口可能得到不同「开/关」结论。
• campaigns.sandbox 是 threads.sandbox 的冗余副本，靠两个触发器同步。

3.6 测试钉的是源码文本，不是行为

• scripts/test-*.mjs 94 个文件、1,069 个 test()；88 个文件 readFileSync 读 src/ 源码，assert.match / doesNotMatch 3,009 条——比 test 用例多两倍。典型断言：assert.match(src, /const \[confirmingId, setConfirmingId\] = useState<string \| null>\(null\);/)，即测试钉死某个变量名、某行写法。32 个文件完全不 import 任何 src 模块。
• 测试按客户反馈轮次和审查日期命名：test-feedback3-chains / feedback4 / feedback5 / feedback6 / feedback7-8 / feedback8b / audit-1017 / agent-review-fixes / agent-live-fixes…，而不是按模块。
• 没有 .github/，没有 CI；npm test 跑 node --test。本地与线上是同一个 Supabase 项目（ARCHITECTURE §2「本地跑过就等于线上跑过」）。
• 后果：任何重命名、抽函数、合并两份实现，都会让几十个测试变红——而这些红和行为是否正确无关。这是「无法继续迭代」最直接的机械原因。好的一面：scripts/eval/scenarios.mjs 37+ 个评测场景「按结果判、不按措辞判」（踩坑 §3），scripts/e2e/run.mjs 真实模型 + 沙盒对话跑全流程，这两套是可保留的资产。

3.7 开发模式：按反馈逐条打补丁

• 579 次提交里 58 条标题含「反馈 / feedback」，151 次碰 ≥10 个文件；最大的一次 76 个文件（ADR 0026 重构）。重构方案 §1 自己统计：9-15 以来 258 个提交，45 个改对话 Agent 那四个文件、78 个改 advance.ts / runner.ts；反馈 6.0 的每一条都同时动工具、梯子、提示词三处。
• 每轮审查都是几十条：2026-08-17「假成功」9 处、09-22 体检 40 条（38 条站住）、09-23 全面审查约 90 条、10-06 审查二约 48 条、10-16 重构后四路审查又 16 条踩坑。修法都是在原函数里加分支，没有抽象层吸收：runMatch 977 行、最大嵌套 8 层、38 个 if，内部串了 EasyKOL 拉取、HypeAuditor 补人、品牌号判定、地域核验、硬条件清扫、写理由、叫醒规则。
• 文档与代码脱节：ARCHITECTURE.md（最后校对 09-22）和 AGENT-SYSTEM.md（09-23）描述的 X-Copilot-Effects 响应头、tools.ts 三轮工具循环都已不存在；doc/演示测试流程.md 写的还是「6 步表单」路径；AGENTS.md §1.5 标题仍是「当前进度（2026-08-20）」。ADR 用词很诚实（「架构不换，补的是边界」「是一堆 if」），但 ADR 0024 说「架构形状是对的」十天后 ADR 0026 就推翻了它。
• 根本原因在约束本身：AGENTS.md §1 写明「工期只有 1–2 周」「不做抽象层、不做插件化、不预留扩展点」「演示链路可跑通 > 视觉完成度 > 功能覆盖面 > 工程健壮性」。这套约束下做出的代码跑了三个月、接了八轮真实客户反馈，但约束从来没有被重新审视。

3.8 两条次要的

• 供应商补丁留在客户端里：client.ts 1,076 行里真正的 HTTP 调用约 100 行；Poe 时代的引用剥离（两份，注释自承「换供应商后是无害空操作」）、jsonInstruction 代替 response_format、400 "upstream gateway failure" 当 5xx 重试、402 "used up your points"、"对话必须以 user 结尾" 约束（negotiate.ts:275、projection.ts:151）在 2026-10-19 换到 OpenRouter 后都可删但还在。
• service role 面：supabase/server.ts:50 注释说「只在两处该用」，实际 13 个目录 30+ 文件调 supabaseAdmin()；系统身份下 supabaseServer() 静默返回 admin 客户端并伪装成会话客户端类型；RLS 对 worker 路径不构成约束，安全靠一个静态扫描脚本 test-service-role-guard.mjs。

4. 合伙人反馈 ↔ 代码根因对照

把 Lark 文档里反复出现的条目映射到上面的根因。「已修」指代码里有对应改动，不代表线上验证过。

5. 对照 Funyard 的工程原则

Funyard 是我们自己的 Cloudflare Workers + Durable Object 项目，和 Centrol 规模相近（server 约 1.9 万行 TS，不含生成的目录文件）。拿它的 11 条做法逐条对照，不是说 Funyard 完美（它的浏览器端也没复用 protocol 包），而是这些做法恰好各自防住了 Centrol 的某一类混乱。

一句话：Funyard 把「状态」「契约」「门禁」三件事各自收口在一个地方；Centrol 把这三件事分散在每一个函数里，靠作者的记忆和 ⚠️ 注释维持。

6. 还能不能迭代：三条路与建议

6.1 值得保留的资产

6.2 三条路

6.3 建议

1. 不要选 A 让它「再修一轮」。 七条根因里六条是结构性的，每轮审查几十条、修完下一轮又几十条，这个曲线已经持续三个月。再来一轮反馈 9.0，大概率还是同一批问题换个地方出现。
2. 无论 B 还是 C，先做三件收口的事再写任何功能： 一份工具 / 事件 / 确认卡的契约（像 Funyard 的 packages/protocol）；一张创作者状态转移表和唯一的写入函数；一条 CI 门禁（行为测试 + 迁移校验 + 密钥扫描）。这三件事做完，剩下的功能才能「加一个不碰另一个」。
3. 把 doc/dev/ 当需求源，不要当代码注释读。 建议 PM（product-research-agent）把 46 份踩坑笔记和 8 轮反馈收成一份「网红营销 Agent 的硬规矩清单」（例如：只有 SMTP 成功才算寄出；钱不替用户编；不符合硬条件不进名单；秒回等于穿帮），这份清单是我们产品的验收标准，和代码无关。
4. 和合伙人沟通时的说法：不是「代码写得差」——注释、ADR、踩坑笔记的质量在同类项目里是高的；是「两周 demo 的约束下做出的代码被当成产品跑了三个月」，约束从没被重新审视。决定下一步前先定：这是继续做 demo，还是开始做产品。

附录 A：关键文件地图

附录 B：数字汇总

附录 C：调研方法与局限

• 只读调研，未运行代码、未连库、未在线上复现任何反馈。所有「已知问题」是从代码路径推断的可能原因，不是线上定位结论。
• 行数、处数由 wc / grep 在 2026-11-05 的 main 分支上统计；「某处是死代码」的判断基于 src/ 内的静态引用，不排除脚本或迁移引用。
• 五路调研由五个独立会话完成，每条结论附文件:行号，主文档作者抽查过测试、提交历史、目录规模等数字；逐条行号未全部二次核对。
• Lark 反馈文档里含第三方 API 账号信息，本文档未收录；原始反馈以 Lark 文档为准。
• 未读 doc/customer_document/ 下的 docx（功能边界确认书、合同）。

提示：点击任意图片可放大查看，再点一次缩回。