Claude Code Projects开放：用TypeScript手搓一个微型项目协调器

Anthropic的Claude Code Projects正式向Pro和Max用户开放，核心思路很清晰——项目不再是聊天记录的文件夹，而是一个协调者会话，负责划定目标、把工作分派给并行线程、审查结果、再拼装成最终交付物。官方原话说得很直白：「项目有干活的线程，也有指挥它们的协调者。」

这篇文章不复述新闻，而是动手用TypeScript实现一个微型版本，理解协调器究竟要解决什么问题。

并行容易，协调才是产品

多数多智能体演示的开场都差不多：启动三个agent，给它们同一个目标，然后祈祷它们别互相踩脚。偶尔能跑通，但更常见的结果是三个PR改了同一个文件，外加第四场对话解释为什么会这样。

Anthropic的设计里有个关键细节值得记住：每个线程其实是一个Claude Code云会话，跑在自己的分支和仓库副本上。协调者负责组织工作，如果线程改到同一份代码，重叠部分就像普通PR一样以合并冲突解决。

这个区分很重要。如果你能启动五个agent却说不清谁拥有哪些文件，你手里不是项目，而是一场带着日志的交通堵塞。

协调器必须回答四个问题：哪些工作应该独立成线程？今天能开多少线程？谁已经认领了哪些文件？完成的部分能交付什么？大多数agent循环只回答了第一个——把整个目标塞进一个prompt，然后让合并冲突替你回答第三个问题。

正确的顺序是：先划定范围，再设上限，然后认领文件，最后拼装。顺序本身就是设计。

多智能体系统（Multi-Agent System）指由多个自主 agent 协作完成任务的架构，常见拓扑包括流水线式、黑板式和协调者-工作者式。Anthropic 采用的是第三种：一个协调者负责规划、分配和审查，多个工作线程并行执行。这种模式在学术上可追溯到「主从 agent」（master-worker）范式，其优势在于将全局决策集中化，避免 agent 之间互相争夺范围；代价是协调者成为瓶颈和单点故障。理解这一拓扑有助于判断文中四问的合理性——它们本质上都是协调者必须维护的全局状态：谁在做什么、能开多少、资源归谁、产出如何合并。

三步搭起最小协调器

共享记忆：带键的白板

Anthropic说每个线程都从共享项目记忆里取信息——发布日期、决策、动计费前该先ping谁。微型版本里，记忆就是一个事实列表，remember 写入或覆盖某个键，recall 读取它。

人类写下 release=Friday，线程完成时读取它，这样拼装出来的看板保持一致，不需要重新提示。这不是RAG，它就是一块带键的白板。

RAG（检索增强生成）是另一个常被拿来与共享记忆对比的概念：它从大规模文档集合中通过向量相似度动态检索相关片段注入模型上下文，侧重「无结构的召回」；而共享记忆是显式键值对，侧重「有结构的写入与覆盖」，任何线程都能以确定性的方式读取 release=Friday 这样的确定事实。二者解决不同问题——RAG 回答「相关知识在哪里」，共享记忆回答「当前项目已确认了什么」。当一个系统的多个并行线程需要保持一致的世界观时，键值式记忆比检索式记忆更合适，因为前者能保证所有线程看到同一份真相，而不会因为检索结果不同而产生分歧。

划定目标：协调者拥有拆分权

真实系统在这一步会调用模型。示例里planner是模拟的，两个演示目标返回固定的线程计划，每个计划有id、标题和将要触碰的文件列表。

Anthropic文章用的也是同样的形状：退役一个废弃的v1端点，每个仓库一个线程；或者并行做性能分析并开PR。最关键的一点是——协调者拥有拆分权，线程不能自己发明范围。坏的拆分比不拆分更糟。

线程上限与文件认领

每个线程都是完整会话，所以Claude Code Projects会比普通用法更快触达使用限制。Anthropic文档里有项目级别的用量控制，等待名单开放时的媒体报道也提到每日新线程额度——但这个数字应被视为媒体消息，而非官方文章的原文引用。

示例里每日上限是输入：第一个项目每天三个线程。适合上限的线程以 running 启动，其余的保持 queued 并附带原因。排队不是失败，它只是在等明天，或者等人手动抬高上限。

文件认领比Anthropic更严格也更早：线程必须认领文件才能完成，先到先得。如果另一个线程已经认领 api/routes/checkout.ts，新线程就变成 blocked，并打印出原因。你希望冲突出现在协调器日志里，而不是周五突然爆发的PR争夺战。

看板是交给人类的交付物

一个从不总结的协调器只是个进程孵化器。assemble 函数把项目状态整理成一张看板：列出记忆、已完成线程、被阻塞线程、排队线程。

运行 npx tsx coordinator.ts 会看到两个演示：第一个退役v1 checkout，三个线程启动，docs因为每日上限排队，记忆把 release=Friday 带进每个完成结果；第二个降低p75延迟，profile 和 cache 完成，query 因为 profile 已认领 api/routes/checkout.ts 而被阻塞。

人类读看板，agent应该留下一张。

这套模型哪里会崩

诚实地说，示例有明确的局限：划定目标是模拟的，真实协调器需要模型或人来拆分工作；文件认领太粗，真实仓库需要更细的锁或有意的共享所有权加合并规则；记忆是扁平map，没有溯源、没有过期、没有访问控制——没有规则的共享记忆会变成共享污染；每日线程数不等于token预算、美元预算或风险预算，三者可能都需要；示例没有审查步骤，Anthropic的协调器在拼装前会审查输出，这里只统计状态；排队的工作不会自动恢复，抬高上限并排空队列留给读者作为练习。

合并冲突（merge conflict）是版本控制系统中的常见问题：当两个分支修改了同一文件的同一区域，Git 无法自动决定保留哪一份，便要求人工选择。在 Claude Code Projects 中，每个线程运行在独立分支和仓库副本上，因此冲突不会在线程执行时爆发，而是在合并时暴露——这既是优点也是限制。优点是线程之间互不阻塞，可并行推进；限制是冲突被推迟到集成阶段，可能积压成一次性的大量人工裁决。文件认领机制正是为了在源头减少冲突面：先到先得地占住文件，让其他线程提前 blocked，而不是在合并时才发现重叠。

协调正在成为多智能体的主战场

Anthropic把协调者会话放在并行云线程之上，方向是对的。Google的Gemini agent、Meta的Muse Wonder focus loop、OpenAI的工具密集型栈，都在从不同侧面逼近同一个形状。

不同产品，同一方向。并行是功能，协调才是产品。

真正值得追问的问题不再是「我们能跑多少agent」，而是「谁来协调它们」。

背景补充

文中提到的每日线程额度与 token 预算，触及了 agent 系统成本控制的一个基本区别：并发预算与经济预算并不等价。线程数限制控制的是同一时间有多少会话在消耗资源，属于速率控制；而 token 预算、美元预算控制的是总共能花多少，属于总量控制；风险预算则约束哪些操作需要审批或可回滚。三者需要分别设计，因为一个系统可能 token 充足但并发爆表，也可能并发空闲但经济成本失控。真实的多智能体系统往往需要同时维护这三种预算维度，才能在可用性和可控性之间取得平衡。