WISC 框架下的 Orchestrator 路由 Agent 约定从消息流、会话转换到反模式清单【免费下载链接】context-engineering-introContext engineering is the new vibe coding - its the way to actually make AI coding assistants work. Claude Code is the best for this so thats what this repo is centered around, but you can apply this strategy with any AI coding assistant!项目地址: https://gitcode.com/gh_mirrors/co/context-engineering-intro导读本文围绕 orchestrator.md 这一 WISC 框架 Tier 2 规则文件展开系统拆解一个多平台 AI 编码平台中编排器Orchestrator路由 Agent 的核心设计确定性命令与 AI 路由的分流边界、消息锁管理、提示构建、/invoke-workflow协议、不可变会话转换、隔离解析与后台工作流分发。读完本文你将掌握如何把这类高价值架构约定写成可被 AI 自动加载与遵守的规则文件并理解其背后的并发安全、审计与可观测性设计。本文的关联文档是 WISCWrite–Isolate–Select–Compress上下文工程框架在 use-cases/ai-coding-wisc-framework/ 中的实战示例之一。该目录以 Claude Code 为载体演示了三层上下文体系全局规则、按路径自动加载的规则.claude/rules-example/与按需拉取的深度参考文档。orchestrator.md 正是 Tier 2 中触发面最广、约束最硬的一份规则——它约束的是整个平台消息处理的心脏。一、规则文件定位Tier 2 按需加载规则在 WISC 三层上下文体系中README.md 明确Tier 1CLAUDE.md始终加载要求精简建议 500 行以内Tier 2.claude/rules/根据paths:frontmatter 在 Agent 触碰对应文件时自动加载Tier 3.claude/docs/深度参考文档仅在子代理判断相关后按需加载。orchestrator.md 属于 Tier 2其 frontmatter 声明了自动加载触发范围--- paths: - packages/core/src/orchestrator/**/*.ts - packages/core/src/handlers/**/*.ts - packages/core/src/state/**/*.ts ---也就是说只要 Agent 开始阅读或修改编排器、命令处理器、会话状态相关代码这份约定就会自动进入上下文无需人工提醒。这正是 WISC 中Select选择策略的落地只有当下需要的规则才被加载避免主上下文被无关约定挤占。说明规则中引用的packages/core/src/orchestrator/...等路径是规则所约束的目标项目一个名为 Archon 的远程 Agent 编码平台的源码布局。在当前仓库中这些路径的规范文本即位于 orchestrator.md 及同目录的兄弟规则文件workflows.md、isolation.md、server-api.md、testing.md 等中。二、消息流路由 Agent 架构总览orchestrator.md 用一张消息流图完整勾勒了平台消息从进入到响应的主链路Platform message → ConversationLockManager.acquireLock() → handleMessage() (orchestrator-agent.ts:383) → inheritThreadContext() — copy parents codebase/cwd if child thread → Deterministic gate: 5 commands only (help, status, reset, workflow, register-project) → Everything else → AI routing call: → listCodebases() discoverAllWorkflows() → buildFullPrompt() → buildOrchestratorPrompt() or buildProjectScopedPrompt() → AI responds with natural language ± /invoke-workflow or /register-project → parseOrchestratorCommands() extracts structured commands from AI response → If /invoke-workflow found → dispatchOrchestratorWorkflow() → If /register-project found → handleRegisterProject() → Otherwise → send AI text to user这条链路的几个关键设计意图值得展开单一入口所有平台的消息都汇聚到handleMessage()规则文档标注位于orchestrator-agent.ts:383平台适配层不直接处理业务逻辑。这与同目录 server-api.md 中的反模式条款相互印证——Never call platform adapters directly from route handlers — usehandleMessage() lock manager。先加锁、后处理ConversationLockManager.acquireLock()位于处理最前端防止同一会话的并发消息互相踩踏。确定性门控在前AI 路由在后只有 5 个命令走确定性处理其余全部交给 AI 路由保证高频系统命令稳定可预期同时把长尾需求交给模型灵活理解。AI 输出结构化化AI 的响应不是直接透传而是经过parseOrchestratorCommands()提取结构化命令/invoke-workflow、/register-project再决定派发工作流、注册项目或原样回复用户。锁管理器返回值的正确用法规则特别强调一个并发陷阱Lock manager returns{ status: started | queued-conversation | queued-capacity }. Always use the return value to decide whether to emit a queued notice — never callisActive()separately (TOCTOU race).锁管理器返回三种状态状态含义started锁获取成功会话开始处理queued-conversation同一会话已有消息在处理当前消息排队queued-capacity系统容量受限消息排队等待反模式先调用isActive()再调用acquireLock()。这两步之间存在时间窗口TOCTOU即检查后使用竞态状态可能在这两步之间发生变化导致错误地判断会话是否空闲。正确的做法是只用acquireLock()的返回值决定是否向用户发出排队中通知。三、确定性命令只有 5 个命令绕过 AI规则文档标注位于orchestrator-agent.ts:420明确只有5 个命令走确定性处理全部定义在 command-handler.ts命令行为/help显示可用命令/status显示会话/对话状态/reset停用当前会话/workflow子命令list、run、status、cancel、reload/register-project内联处理——创建 codebase 数据库记录其余所有斜杠命令一律落入 AI 路由。这一点非常重要旧版遗留命令/clone、/setcwd、/getcwd、/repos、/repo、/worktree、/init、/command-set、/command-invoke、/load-commands、/reset-context在 command-handler.ts 中仍有实现但只能通过旧的直接路径触达default分支对其中一部分codebase-switch、command-invoke、template-*返回弃用提示deprecation notice。这份命令白名单设计的价值在于系统命令的可用性与语义不应依赖模型发挥。/help、/status、/reset这类高频且结果必须精确的操作任何一次模型误判都会直接损害用户体验而工作流派发、项目注册这类语义开放的操作交给 AI 理解用户意图反而更自然。从源码结构可以推断这一设计在 prime.md 描述的消息流中同样得到体现Message flow: platform adapter → orchestrator-agent → command handler OR AI client——命令处理器与 AI 客户端是二选一的分支关系。四、路由 AI 的提示构建prompt-builder.tsAI 路由的质量取决于提示词。规则规定提示选择取决于会话是否已绑定项目无项目→buildOrchestratorPrompt()规则标注位于prompt-builder.ts:116——平等列出所有项目若用户意图含糊则请求澄清有项目→buildProjectScopedPrompt()规则标注位于prompt-builder.ts:153——活跃项目排在最前含糊请求默认落到该项目。两种提示都包含三类信息已注册项目registered projects、已发现的工作流discovered workflows、/invoke-workflow与/register-project的格式规范。这一项目作用域设计直接呼应了消息流图中的inheritThreadContext()——子线程child thread会继承父线程的 codebase/cwd 上下文从而影响提示选择分支。/invoke-workflow协议AI 被要求按如下格式输出工作流派发指令/invoke-workflow name --project project --prompt users intentparseOrchestratorCommands()规则标注位于orchestrator-agent.ts:90解析时执行三条校验工作流名校验通过findWorkflow()与已发现工作流比对项目名校验通过findCodebaseByName()比对——大小写不敏感且支持部分路径段匹配例如repo可匹配owner/repo参数顺序约束--project必须出现在--prompt之前。最后一条约束值得注意它把 AI 生成格式的容错成本前置到解析器——与其让解析器智能容忍各种乱序不如在提示词中规定严格顺序让格式错误快速暴露、便于修复。filterToolIndicators()orchestrator-agent.ts:163该函数仅作用于批处理模式batch mode在把累积的 AI 响应发给用户之前剥离以 emoji 工具指示符✏️️开头的段落。这样用户在批处理模式下收到的只是干净的文本而不是夹杂着内部工具调用痕迹的噪音。五、会话转换不可变会话与审计链这是 orchestrator.md 中最具架构深度的一节Sessions areimmutable— never mutated, only deactivated and replaced. The audit trail is viaparent_session_idtransition_reason.会话是不可变对象——绝不就地修改只能停用deactivate并替换。审计线索通过parent_session_id父会话 IDtransition_reason转换原因保留形成可追溯的会话族谱。最关键的一条规则Onlyplan-to-executeimmediately creates a new session.All other triggers only deactivate; the new session is created on the next AI message.只有plan-to-execute会立即创建新会话其他所有触发条件只做停用新会话等下一次 AI 消息到来时才创建。这种延迟创建避免了空转会话的产生。规则给出用法示例import { getTriggerForCommand, shouldCreateNewSession } from ../state/session-transitions; const trigger getTriggerForCommand(clone); // codebase-cloned if (shouldCreateNewSession(trigger)) { // plan-to-execute only }TransitionTrigger的完整取值集合规则文档原文first-message | plan-to-execute | isolation-changed | codebase-changed | codebase-cloned | cwd-changed | reset-requested | context-reset | repo-removed | worktree-removed | conversation-closed这些触发条件覆盖了会话生命周期中的主要事件首条消息、计划转执行、隔离环境变化、代码库克隆/变更、工作目录变化、显式重置、上下文重置、仓库/工作树移除、会话关闭。每个事件都携带明确的原因让审计日志能够回答这个会话为什么存在、从哪个会话而来。六、隔离解析IsolationResolver 与错误处理validateAndResolveIsolation()规则标注位于orchestrator.ts:108委托给IsolationResolver并负责向平台发送上下文消息例如正在复用 issue #42 的工作树更新数据库conversation.isolation_env_id、conversation.cwd当发现过期引用时重试一次stale_cleaned当隔离被阻塞时在平台通知后抛出IsolationBlockedError。铁律当隔离被阻塞立即停止一切后续处理——IsolationBlockedError意味着用户已经被通知继续处理只会产生混乱的二次输出。兄弟规则中的 7 步解析顺序隔离的底层算法在同目录 isolation.md 中有完整定义IsolationResolver的 7 步解析顺序现有环境——工作树仍在磁盘上则直接使用existingEnvId无代码库——完全跳过隔离返回status: none工作流复用——查找同(codebaseId, workflowType, workflowId)的活动环境关联 issue 共享——PR 可复用关联 issue 的工作树PR 分支采纳——通过findWorktreeByBranch按分支名查找已有工作树上限检查 自动清理——达到maxWorktrees默认 25时先尝试makeRoom()创建新环境——调用provider.create(isolationRequest)再store.create()。错误处理上isolation.md 给出了完整的捕获模式先用isKnownIsolationError()判断未知错误必须作为崩溃向上传播可能是编程 bug已知错误permission denied、eacces、timeout、no space left、enospc、not a git repository、branch not found则经classifyIsolationError()映射为友好提示发给用户。这与 orchestrator.md 的IsolationBlockedError规则一脉相承——阻塞即停止。七、后台工作流分发Web 专属dispatchBackgroundWorkflow()规则标注位于orchestrator.ts:256处理 Web 平台的异步工作流创建隐藏 worker 会话命名格式web-worker-{timestamp}-{random}事件桥接把 worker 的 SSE 事件桥接到父会话的 SSE 流预创建运行记录提前创建 workflow run 行防止用户立即跳转 UI 时出现 404fire-and-forget 执行调用executeWorkflow()后不等待完成后回传摘要把result.summary呈现到父会话。其中预创建运行记录是典型的 UX 防御性设计后台任务刚派发、尚未真正开始执行的瞬间如果 UI 已经跳转到运行详情页查询不到记录就会 404。提前落库一行把这个窗口期抹平。关于工作流执行本身同目录 workflows.md 定义了三种互斥执行模式顺序 steps、循环 loop、DAG 节点以及完整的变量替换表$1/$2/$3、$ARGUMENTS、$PLAN、$IMPLEMENTATION_SUMMARY、$ARTIFACTS_DIR、$WORKFLOW_ID、$BASE_BRANCH、$nodeId.output并给出了路由回退策略若没有产生/invoke-workflow则回退到archon-assist只有archon-assist也不可用时才返回原始 AI 响应——这正好补全了本文消息流图中Everything else → AI routing call之后的分支细节。八、惰性日志模式Lazy Loggerorchestrator.md 规定该区域所有文件一律使用延迟初始化日志器模式——绝不在模块作用域初始化let cachedLog: ReturnTypetypeof createLogger | undefined; function getLog(): ReturnTypetypeof createLogger { if (!cachedLog) cachedLog createLogger(orchestrator); return cachedLog; }设计动机可以从 testing.md 反推模块顶层初始化意味着在测试中必须先 mock 再 import顺序一旦颠倒测试就会用到真实日志器污染测试输出甚至触发真实副作用。惰性初始化让日志器在真正调用时才创建配合测试规则中Mock before import的要求两者共同保证了可测试性。同时惰性初始化也避免了未被使用路径上的无谓开销。九、反模式清单六条不可违背的约束orchestrator.md 以反模式清单收尾这是规则文件中约束力最强、Agent 必须无条件遵守的部分#反模式正确做法1先isActive()再acquireLock()只用锁返回值判断避免 TOCTOU 竞态2绕过 resolver 直接访问conversation.isolation_env_id一律经过隔离解析器3吞掉或忽略IsolationBlockedError必须传播以停止所有后续消息处理4在编排器中加入平台特定逻辑只使用IPlatformAdapter接口5通过原地修改来转换会话总是停用并创建新的关联会话6假定斜杠命令是确定性的只有上述 5 个命令绕过 AI 路由这六条分别对应六个易错点并发安全1、封装边界2、4、错误传播3、不变性5、路由边界6。把这六条写进规则文件的意义在于它们都是看起来无害、实则破坏架构的陷阱——比如第 4 条为某个平台加一个 if 分支很容易但会让编排器逐渐腐化为平台耦合的泥潭。十、把规则写进上下文的工程启示从 orchestrator.md 这份示例可以提炼出一份高质量规则文件的通用模板paths:frontmatter 限定触发面——规则只在相关代码被触碰时加载与 WISC 的 Select 策略对齐先给架构总览图——消息流图让 Agent 在动手前建立全局心智模型白名单表格化——命令、状态、取值全部表格化信息密度高、检索友好关键代码原位给出——如锁返回值、会话转换示例Agent 可以直接模仿反模式清单收尾——把绝对不能做的事单列比应该怎么做约束更强与兄弟规则互相引用——orchestrator 的隔离、工作流、SSE 细节分别由 isolation.md、workflows.md、server-api.md 承接避免单文件臃肿——这本身就是 WISC 三层上下文体系的分工逻辑。如果你想在自己的项目里复用这套模式可以参照 README.md 中Applying This to Your Project的步骤先写Write落地规则文件并配合/plan-feature、/execute、/handoff、/commit等命令再逐步用路径作用域规则替换全局规则最后用子代理隔离研究噪音。而 orchestrator.md 正是路径作用域规则的典范——它把一个复杂子系统最重要的架构约束压缩成了一份 Agent 在正确时机自动读取、立刻可执行的约定。【免费下载链接】context-engineering-introContext engineering is the new vibe coding - its the way to actually make AI coding assistants work. Claude Code is the best for this so thats what this repo is centered around, but you can apply this strategy with any AI coding assistant!项目地址: https://gitcode.com/gh_mirrors/co/context-engineering-intro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考