5000 行够不够写一个 Claude Code——读 Helixent 源码的七个意外发现

你大概觉得 Claude Code 是个很复杂的东西——有 MCP、有 Hooks、有 subagent、有 plan mode、有一堆工具、有完整的 Settings 层、有 Skills 加载、有审批系统……每一样都够一个工程师写一周。

一个叫 MagicCube 的开源项目 Helixent 最近让笔者改了想法——它用 5000 行不到的 TypeScript，复刻了 Claude Code 大约 80% 的体验骨架。读完整个仓库的当下，笔者的第一反应是："原来核心可以这么小"。

这篇文章是笔者这几天把 Helixent 整个 src 目录读了一遍之后写的。不讲"怎么用"，讲这个项目在架构上做对了什么，以及里面有哪些巧思值得抄到你自己的 Agent 里。

文章的顺序大致是：从最上层的定位讲起，到 Agent Loop 的形态，再到中间件、工具、UI、最后落到一个能随手抄的 checklist。

一、先把定位说清楚：Helixent 到底是什么

一句话：Bun 生态下的一个 ReAct Coding Agent 开源库 + CLI，作者是孙志岗，MIT license，npm 直接装。

npm install -g helixent@latest
cd your-project
helixent

跑起来你会看到一个非常熟悉的终端 TUI——输入框、流式输出、工具调用前的审批弹窗、slash 命令补全、todo 面板。如果你习惯了 Claude Code，你会产生一种"这界面怎么似曾相识"的感觉。

然后你去看它的依赖：

"dependencies": {
  "@anthropic-ai/sdk": "^0.87.0",
  "openai": "^6.33.0",
  "ink": "^6.8.0",
  "react": "^19.2.4",
  "commander": "^14.0.3",
  "zod": "^4.3.6",
  "gray-matter": "^4.0.3",
  // ...10 个左右
}

没有 MCP SDK、没有 PTY、没有私有协议。一切都是透明可读的 TypeScript——这是它最让笔者兴奋的点。想知道 Claude Code 里 apply_patch 工具内部到底怎么处理 hunk 匹配？看 src/coding/tools/apply-patch.ts 的 232 行就够了。想知道审批队列怎么做？看 src/coding/permissions/approval-manager.ts 的 60 行。

这种"把产品里所有黑盒打开让你看"的体验，是任何闭源工具给不了的。

二、四层架构：依赖方向单向，每层职责清爽

Helixent 自己的 AGENTS.md（作者写给 AI 协作者看的架构文档）里明确写了四层：

┌──────────────────────────────────────────────────────┐
│  cli        CLI 入口 + commander + Ink TUI           │
│             依赖: coding, community, foundation      │
├──────────────────────────────────────────────────────┤
│  coding     Coding Agent 工厂 + 13 个工具 + 审批     │
│             依赖: agent, foundation                  │
├──────────────────────────────────────────────────────┤
│  agent      ReAct loop + Middleware + Skills + Todos │
│             依赖: foundation                         │
├──────────────────────────────────────────────────────┤
│  foundation Model / Message / Tool 核心类型          │
│             依赖: 无（只有 zod）                     │
└──────────────────────────────────────────────────────┘

   ┌──────────────────┐
   │  community/      │  侧路：第三方 Provider 适配器
   │  ├─ anthropic/   │  依赖 foundation，不依赖 agent/cli
   │  └─ openai/      │
   └──────────────────┘

注意两个细节：

第一，依赖方向严格单向。agent 不允许依赖 coding，foundation 不允许依赖任何东西。作者在文档里写死了这个约束，而且真的执行了——grep 一下 import from "@/coding" 在 src/agent/ 下的出现次数，是 0。

第二，community 是"侧路"不是 Layer。Anthropic、OpenAI 这两个 provider 适配器被特意放在 community/ 而不是 foundation/providers/。这个命名选择在传达一句话——"这些是可选的，不是核心的一部分"。未来要加 Gemini、Mistral，再加一个 community/google/ 就行，foundation 永远不动。

这种"用目录名传达架构意图"的做法，比写一大堆 ADR 文档有效得多。

三、Agent Loop 用 AsyncGenerator 作为主 API

这是笔者读完 src/agent/agent.ts 的第一个惊叹点。

传统的 Agent loop 长这样（伪代码）：

// 老派：EventEmitter + callback
const agent = new Agent({...})
agent.on("message", (msg) => render(msg))
agent.on("progress", (p) => showSpinner(p))
agent.on("done", () => hideSpinner())
await agent.run(userInput)

Helixent 的写法：

// Helixent：AsyncGenerator
for await (const event of agent.stream(userMessage)) {
  if (event.type === "message") {
    enqueueMessage(event.message)
  }
  // progress 事件 UI 里忽略（用 streaming boolean 驱动 shimmer）
}

差别看起来小，实际带来的体验完全不同：

• 类型安全：AgentEvent 是一个 union，switch 穷尽所有情况会被 TS 检查
• 背压自然：消费者的 for await 多慢，agent 就产出多慢，没有 buffer 溢出
• 取消信号干净：AbortSignal 配合，throws 从 await 那里传出来
• yield* 嵌套：内部 generator 可以把自己的 yield 直通给外层

这最后一条是 agent.ts 里最漂亮的一处：

async *stream(message: UserMessage): AsyncGenerator<AgentEvent> {
  // ...
  for (let step = 1; step <= maxSteps; step++) {
    // yield* 会把 _think() 里的所有 yield 直通到外面
    // 同时拿到它的 return 值
    const assistantMessage = yield* this._think()
    //                       ^^^^^ 关键
    // ...
  }
}

async *_think(): AsyncGenerator<AgentEvent, AssistantMessage> {
  //                            ^^^ yield 类型     ^^^ return 类型
  for await (const snapshot of this.model.stream(modelContext)) {
    if (snapshot.streaming) {
      yield this._deriveProgress(snapshot)  // 途中 yield 给外层
    }
  }
  return finalMessage  // 最后 return 给 yield* 表达式
}

TypeScript 3.6 以后 AsyncGenerator 的类型签名是 <Yield, Return, Next> 三个参数，Helixent 用得非常精准——_think 的 yield 类型是 AgentEvent、return 类型是 AssistantMessage。这让外层一行 const msg = yield* this._think() 既能把内部的 progress 事件直通给调用者，又能拿到最终的 assistant message 作为返回值。

这是一个把 generator 用到它应该被用的样子的例子。

四、流式用"累积快照"，不用 delta——这个决策贯穿全项目

Helixent 的 ModelProvider.stream 的契约是这样的：

/**
 * Streams the model response, yielding accumulated snapshots.
 * Each yielded value is a progressively more complete AssistantMessage.
 * The final yielded value is equivalent to what invoke() would return.
 */
stream(params): AsyncGenerator<AssistantMessage>

关键词是 accumulated snapshots——每次 yield 的不是 delta（增量片段），而是"到目前为止的完整消息"。

传统 delta 协议：              Helixent 快照协议：
yield { delta: "你" }           yield "你"
yield { delta: "好" }           yield "你好"
yield { delta: "，" }           yield "你好，"
yield { delta: "世" }           yield "你好，世"
yield { delta: "界" }           yield "你好，世界"

消费者的复杂度差别很大：

• delta 协议：消费者要维护状态，把 delta 合并起来才能渲染
• 快照协议：消费者每次直接替换当前显示即可

这个设计贯穿了 Helixent 的整个流式体系——StreamAccumulator 在 community/anthropic/ 和 community/openai/ 各实现了一份，内部把 Anthropic 的 event-based 协议和 OpenAI 的 chunk-based 协议都统一吐成累积快照。上层只看到 snapshot，底层差异完全被吃掉。

代价：内存占用 O(n)，但对话规模通常几 KB，可以忽略。 收益：UI 层代码简化一大截、跨 provider 统一、throttle 容易（只需要 debounce，不需要 merge 队列）。

这是笔者第一次看到有项目把这个决策推得这么彻底。以前笔者自己写 LLM 流式也是用 delta，看完 Helixent 下次绝对不干这事儿了。

五、Middleware：八个 hook 把所有扩展都收进一个接口

Helixent 里没有"插件系统"、没有"事件总线"、没有"依赖注入容器"。它的扩展点只有一个——Middleware。

interface AgentMiddleware {
  beforeAgentRun?: (params) => Promise<Partial<AgentContext> | void>
  afterAgentRun?:  (params) => Promise<Partial<AgentContext> | void>
  beforeAgentStep?:(params) => Promise<Partial<AgentContext> | void>
  afterAgentStep?: (params) => Promise<Partial<AgentContext> | void>
  beforeModel?:    (params) => Promise<Partial<ModelContext> | void>
  afterModel?:     (params) => Promise<Partial<AssistantMessage> | void>
  beforeToolUse?:  (params) => Promise<BeforeToolUseResult>
  afterToolUse?:   (params) => Promise<Partial<AgentContext> | void>
}

八个 hook，对应 ReAct 循环的不同粒度：

 beforeAgentRun ────────── 整个 run 一次
   ├─ beforeAgentStep ──── 每一步
   │    ├─ beforeModel ─── model 调用前
   │    ├─ afterModel ──── model 调用后
   │    ├─ beforeToolUse ─ 每个 tool 执行前
   │    └─ afterToolUse ── 每个 tool 执行后
   └─ afterAgentStep ───── 每一步
 afterAgentRun ─────────── 整个 run 结束一次

然后所有扩展都是中间件：

• Skills 系统？beforeAgentRun 扫描目录 + beforeModel 注入 XML。
• Todo 系统？beforeModel 判断"几步没写 todo 了"决定是否提醒 + afterToolUse 重置计数器。
• 审批系统？beforeToolUse 问用户 + 返回 {__skip: true, result} 短路执行。
• 日志？任意 hook，不返回值。
• 修改消息？afterModel 返回 {content: ...} 被 merge 进去。

// 最终组装
new Agent({
  model,
  prompt,
  middlewares: [
    createSkillsMiddleware(skillsDirs),
    todoMiddleware,
    createCodingApprovalMiddleware({ cwd, askUser, approvalPersistence }),
    // 任何你想加的……
  ],
})

对比 Claude Code 的 hook 系统（shell 命令级别），Helixent 的 middleware 是函数级别的。两者各有利弊：

如果你在做一个闭源工具需要让非 JS 开发者扩展，选 CC 那套。如果你在做开源库、用户就是 TS 开发者，选 Helixent 这套。

最值钱的设计：{__skip, result} 返回形态

beforeToolUse 有一个特殊的返回值：

type BeforeToolUseResult =
  | Partial<AgentContext>                              // 普通 merge
  | { readonly __skip: true; readonly result: unknown }// 跳过执行，用 result 代替
  | null | undefined | void

审批中间件靠这个实现：

// src/coding/permissions/coding-approval-middleware.ts
beforeToolUse: async ({ toolUse }) => {
  if (!requiresApproval.includes(toolUse.name)) return
  const allowed = await loadAllowList(cwd)
  if (allowed.has(toolUse.name)) return

  const decision = await askUser(toolUse)
  if (decision === "deny") {
    return {
      __skip: true,
      result: `User denied execution of tool: ${toolUse.name}. ` +
              `You must either find an alternative approach or ask the user for clarification.`,
    }
  }
}

这比 express 那种 next() 机制更声明式——你不是"决定要不要往下走"，而是"告诉框架结果是什么"。模型下一轮看到的就是一个被替换掉的 tool_result，完全透明。

特别留意那段 deny 文本：

You must either find an alternative approach or ask the user for clarification.

这不是冷冰冰的 "Access denied"，而是给模型的下一步指导。这种用 tool_result 文本引导模型行为的微操，是 prompt engineering 里很容易被忽视的一层——错误文本本身就是给下一轮模型的 prompt。

六、_act() 的 Promise.race 循环——并行工具执行最漂亮的写法

这段是整个项目笔者最喜欢的代码。

场景：模型一次产出 3 个 tool_use（比如 read 3 个文件），你想让它们并行执行。

新手写法：

const results = await Promise.all(toolUses.map(t => tool.invoke(t.input)))
for (const result of results) {
  messages.push({ role: "tool", content: [result] })
}

问题：必须所有 tool 都完成才能处理，最慢的那个拖死全场。UI 看起来就是"卡一下，然后所有结果一起刷出来"。

Helixent 的写法：

private async *_act(toolUses: ToolUseContent[]): AsyncGenerator<AgentEvent> {
  const pending = toolUses.map(async (toolUse, index) => {
    const result = await tool.invoke(toolUse.input, signal)
    return { index, toolUseId, toolName, result }
  })

  const remaining = new Set(pending.map((_, i) => i))
  while (remaining.size > 0) {
    // race：谁先完成就拿谁
    const candidates = [...remaining].map((i) => pending[i])
    const resolved = await Promise.race([...candidates, abortPromise])
    remaining.delete(resolved.index)

    // 立即产出
    const toolMessage: ToolMessage = {
      role: "tool",
      content: [{ type: "tool_result", tool_use_id, content: format(resolved.result) }],
    }
    this._appendMessage(toolMessage)
    yield { type: "message", message: toolMessage }
  }
}

关键是 while remaining.size > 0 这个 race 循环：

1. 把所有 tool 的 promise 塞进 pending
2. 每轮 race 谁先 resolve 就处理谁，立即 yield 出去
3. 从 remaining 里删掉，继续 race 剩下的
4. abortPromise 参与 race，让整体可取消

效果：3 个 tool 调用，谁先 ready UI 就立刻显示谁的结果，不等慢的。abort 信号能整体中断所有正在跑的 tool。错误隔离——单个 tool 失败不影响其他。

这是 "边执行边产出" 在 JS 里最优雅的写法，笔者看完当场决定把自己另一个项目里的 Promise.all 全改成这个模式。适用于任何"n 个并行任务、每完成一个立即响应"的场景。

七、tool-result-policy：给每个工具单独配"上下文经济学"策略

这是 Helixent 里一个特别不起眼、但实际极其关键的设计。

文件：src/agent/tool-result-policy.ts

export function getToolResultPolicy(toolName: string): ToolResultPolicy {
  switch (toolName) {
    case "list_files":
    case "glob_search":
    case "grep_search":
    case "file_info":
    case "mkdir":
    case "move_path":
      return { preferSummaryOnly: true, includeData: false, maxStringLength: 1000 }

    case "read_file":
      return { preferSummaryOnly: false, includeData: true, maxStringLength: 12000 }

    case "apply_patch":
    case "write_file":
    case "str_replace":
      return { preferSummaryOnly: false, includeData: true, maxStringLength: 4000 }

    default:
      return DEFAULT_POLICY
  }
}

一张表，把工具分成三类、对应三种"给模型看的详细程度"：

笔者自己以前写工具的时候，所有工具结果一股脑 JSON.stringify 全塞给模型。读完这张表的当下感觉自己之前的实现在浪费对话 token 的一半——list_files 返回 100 个文件的完整 stat 信息，而模型其实只关心"找到了哪些相关的"。

这个策略可以直接抄到任何 Agent 项目里，立竿见影。

还有一个更细的小点：formatToolResultForMessage 里 read_file 有一个特判——直接返回 raw string，不包装 JSON：

export function formatToolResultForMessage({ toolName, result }) {
  if (toolName === "read_file" && typeof result === "string") {
    return result  // 直接返回，不包装
  }
  // 其他工具走 normalize + policy
  // ...
}

为什么？因为模型看到 <tool_result>\n123: import ...\n124: ...\n</tool_result> 比 <tool_result>{"ok":true,"summary":"Read 500 lines","data":"123: import...\\n"}</tool_result> 认知负担低得多。省下的那点 JSON 包装在 read_file 这种超高频的工具上，积少成多。

八、几个值得一起学的小点

上面那些是"大"的，下面几个是"小但值钱"的。

8.1 每个工具强制要求 description 作为第一个参数

parameters: z.object({
  description: z.string().describe(
    "Explain why you want to execute the command. " +
    "Always place `description` as the first parameter."
  ),
  command: z.string(),
})

这是一个让模型先说"为什么"再执行的 prompt engineering 技巧。配合 UI 显示 description 作为 tool 标题，用户看到的是：

⏺ 查找 eslint 配置位置
  └─ /Users/felix/ai/0421-helixent :: eslint.config

而不是冷冰冰的 grep_search(path=..., pattern=...)。能读的意图 > 精确的参数。

8.2 apply_patch 的"硬失败"策略

Helixent 的 apply_patch 严格到苛刻——context line 不匹配就直接 throw，绝不做模糊匹配：

if (actual !== line.text) {
  throw new Error(
    `Context mismatch in ${file.newPath} at line ${sourceIndex + 1}: ` +
    `expected ${JSON.stringify(line.text)}, got ${JSON.stringify(actual)}`
  )
}

笔者第一次看觉得"这也太严了吧"，读完一会儿才反应过来——这是故意的。Coding Agent 经常生成"看起来对"但 context 偏移的 patch，如果允许模糊匹配就会引入静默 bug（打在了错的地方但没报错）。

硬失败的机制是：patch 失败 → 模型收到错误 → 重新 read_file → 生成新 patch。这条路径稍微慢一点，但永远不会静默损坏文件。

这个 trade-off 值得每个做 Coding Agent 的人想清楚："宁可多跑一轮，不能错改一个字节"——这是 Agent 应该有的姿态。

8.3 Skills 的 progressive loading

Helixent 支持 agentskills.io 的标准 Skills 格式。加载时的做法很聪明——只把 frontmatter 塞进 system prompt，不塞正文：

<skill_system>
<instructions>
...
**Progressive Loading Pattern:**
1. When a user query matches a skill's use case, immediately call `read_file`
   on the skill's main file using the path attribute
...
</instructions>
<skills>
  <skill name="skill-creator" path="/Users/.../skills/skill-creator/SKILL.md">
  Create and manage skills
  </skill>
  <skill name="frontend-design" path="...">
  Frontend design and UI development
  </skill>
</skills>
</skill_system>

关键是 path="..." 这个 attribute——告诉模型"要用就先 read_file 这个路径"。这样初始 context 只有 skills 列表（几百字节），真正需要的时候才 read_file 加载正文（几千字节）。

一台装了几十个 skill 的机器，启动时 context 增加约等于 0；用到的时候才按需展开。

8.4 Settings 三层合并 + permissions.allow 用 Set merge

async load(cwd: string): Promise<Settings> {
  const paths = [
    this.userSettingsPath(),              // ~/.helixent/settings.json
    this.projectSettingsPath(cwd),        // ./.helixent/settings.json
    this.projectLocalSettingsPath(cwd),   // ./.helixent/settings.local.json
  ]
  // ...
}

大多数字段 last-write-wins，permissions.allow 特判用 Set merge（三层并集）。这让：

• 用户级 allowlist（bash、git 之类跨项目都信任的）在 ~/.helixent/settings.json
• 项目级 allowlist 在 ./.helixent/settings.json（提交 git 团队共享）
• 个人临时 allowlist 在 ./.helixent/settings.local.json（gitignored）

allow 用 Set 并集而不是覆盖是一个对的细节——不会出现"项目里加了一条就把全局的全覆盖了"的惊喜。这个细节跟 Claude Code 完全同构，作者显然做过对标。

九、和 Claude Code 对比：Helixent 像什么

把 Helixent 和 CC 逐项对照一下：

几乎一一对应。

Helixent 没有的 CC 特性：MCP、Hooks、subagent（Task tool）、WebFetch、plan mode、多轮 context 压缩。

这些是 CC 的"产品宽度"，不是"核心深度"。Helixent 把核心 80% 用 5000 行写完了，剩下 20% 的宽度给生态去长。

笔者读完的整体判断：

这不是一个 CC 的 clone，是一个 CC 的 reference implementation。

如果你想理解 Claude Code 为什么是现在这个形态、里面每个决策背后的 trade-off 是什么，读 Helixent 比读任何 CC 的博客都有效——因为你能看见具体的代码。

十、Checklist：哪些直接能抄

如果你明天就要动手写一个 Coding Agent（或改一个旧的），下面这些东西可以直接从 Helixent 抄：

架构层

• Message 用一个 union 类型贯穿所有层，provider 适配器做双向转换
• Model = name + provider + options，provider 接口只有 invoke 和 stream
• Agent loop 的主 API 是 stream(): AsyncGenerator<AgentEvent>
• 流式协议返回"累积快照"而不是 delta
• 中间件接口 = 8 个生命周期 hook + 返回 Partial 被 merge

工具层

• 每个工具强制 description 作为第一个参数
• StructuredToolResult 用 tagged union {ok, summary, data/error, code}
• 按工具名配 tool-result-policy（summaryOnly/maxStringLength）
• apply_patch 严格 context 匹配，不模糊匹配
• read_file 的 tool_result 直接返回 raw string，不包 JSON

Agent 执行

• _act() 用 Promise.race 循环，不用 Promise.all
• beforeToolUse 支持返回 {__skip: true, result} 跳过执行
• 错误文本要带引导语（告诉模型下一步该干嘛）
• AbortController 穿透到 tool，用 signal 参与 race

Skills / Settings

• Skills = SKILL.md + frontmatter + progressive loading（路径塞 prompt，正文按需 read_file）
• 审批清单 = "改变 fs 或执行命令的工具"
• Settings 三层合并，permissions.allow 用 Set 做并集
• AGENTS.md / CLAUDE.md 自动注入为 user message

UI 层（如果是 Ink TUI）

• 最新消息用 Ink 渲染，历史消息 flush 到 scrollback 写 stdout
• 50ms 批处理 setState 防止高频重绘
• ask_user_question / approval 用单例 Manager + subscribe pattern

这张表大概覆盖了笔者从 Helixent 学到的 80%。

十一、最后一句话

笔者读开源项目一般不会把感想写成一篇文章，但 Helixent 这个让笔者例外了。原因不是它"做了什么新的事"——它做的每件事都不新，都在 Claude Code 里见过、在若干教程里讲过——而是它把每件事都做到了非常干净的样子，干净到你读完代码会产生"原来就这么简单"的错觉。

这种让复杂的事看起来简单的能力，是少数顶级工程师才有的品味。

推荐指数：★★★★★

阅读时间建议：一个完整周末，从 src/foundation/ 开始往上读，跟着依赖方向走。

如果你在做 Agent 相关的任何工作、或者单纯想提升自己的 TypeScript 架构品味——Go read it.

仓库地址：https://github.com/MagicCube/helixent

本文基于 Helixent main 分支 v1.1.0 源码，阅读时间 2026-04-21。后续版本可能有变化，以仓库实际代码为准。