层级

职责

关键模块

表现层

CLI 参数解析 + 终端 UI 渲染

Commander.js + React/Ink

应用层

会话管理、消息路由、工具编排

QueryEngine.ts

工具层

40+ 可扩展工具实现

tools/ 目录

服务层

外部服务集成（API、OAuth、MCP）

services/ 目录

基础层

工具函数、状态管理、类型定义

utils/ state/ types/

��架构选型的取舍

React/Ink 用于终端 UI 是个有趣的选择——用声明式 UI 框架管理 TUI 状态，避免了手写 ANSI 转义码的噩梦，代价是引入了 React 的全套心智模型。

Bun 替代 Node.js 主要收益在启动速度（快 2-4x）和内置 Bundle 支持，这对于 CLI 工具体验至关重要。

// Tool 接口定义（src/Tool.ts）

export type Tool = {

name: string

description: string // 供 LLM 理解工具用途的自然语言描述

inputSchema: ToolInputJSONSchema // JSON Schema，LLM 据此生成结构化调用

isEnabled: () => boolean // 动态开关，支持按环境/权限启用

isDangerous: () => boolean // 标记危险操作，触发用户确认流程

needsPermissions: () => boolean // 权限声明

validateInput: (input) => ValidationResult // 运行时输入校验（Zod）

execute: (input, context) => Promise<ToolResult>

}

��值得讨论

插件化工具注册是 AI Agent 框架的通行设计（LangChain Tools、OpenAI Function Calling 都是这个思路）。但一个容易忽视的细节是：description 的质量直接影响 Agent 表现。你在实际项目中，有没有遇到过因为 Tool description 写得不好导致 LLM 总是调错工具的问题？

��核心循环逻辑（伪代码）

async function* agenticLoop(userMessage) {

messages.push(userMessage)

while (true) {

const response = await callAPI(messages, tools) // 流式调用

yield* streamResponse(response) // 实时推送给 UI

if (response.stopReason === ‘end_turn’) break // AI 主动结束

if (response.stopReason === ‘tool_use’) {

const results = await executeTool(response.toolCalls) // 执行工具

messages.push(toolResults) // 结果作为新消息

// 继续下一轮，让 AI 基于工具结果继续推理

}

if (turnCount > maxTurns) break // 防止无限循环

}

}

// 工具执行前的权限决策

async function canUseTool(tool, input): Promise<PermissionResult> {

if (tool.isDangerous()) {

return await promptUserForConfirmation(tool, input) // 阻塞等待用户确认

}

if (hasStoredPermission(tool, input)) {

return { allowed: true } // 用户之前已授权，直接放行

}

return { allowed: false, reason: ‘permission_denied’ }

}

��可借鉴的设计：上下文对象统一传递

ToolUseContext 将所有工具执行所需的「环境」封装成一个对象传递：

• abortController — 取消信号

• readFileState — 文件读取缓存（避免重复 IO）

• getAppState / setAppState — 应用状态读写

• mcpClients — MCP 连接池

这种「上下文对象」模式（Context Object Pattern）在大型项目中比全局变量和参数透传都更清晰，值得在自己的项目里采用。

// context.ts — 并行收集上下文，使用 memoize 避免重复采集

export async function buildSystemPrompt(): Promise<string[]> {

const [gitStatus, userCtx, memoryPrompt] = await Promise.all([

getGitStatus(), // git branch/status/log

getUserContext(), // OS、cwd、环境变量

getMemoryPrompt(), // 跨会话持久化记忆

])

return [systemContext, gitStatus, userCtx, memoryPrompt]

}

// memoize 确保同一会话内多次调用只采集一次

export const getGitStatus = memoize(async () => {

const [branch, status, log] = await Promise.all([

execFile(‘git’, [‘branch’, ‘–show-current’]),

execFile(‘git’, [‘status’, ‘–short’]),

execFile(‘git’, [‘log’, ‘–oneline’, ‘-n’, ‘5’]),

])

return formatGitContext(branch, status, log)

})

风险等级

工具举例

典型用途

权限策略

只读

FileReadTool、GrepTool、GlobTool

读文件、搜索代码

默认允许

写操作

FileWriteTool、FileEditTool、NotebookEditTool

创建/修改文件

首次需确认

执行操作

BashTool、AgentTool、TeamCreateTool

运行命令、创建子 Agent

每次确认或白名单

网络操作

WebFetchTool、WebSearchTool、MCPTool

访问外部资源

按工具策略

// 输入 Schema 设计

{

file_path: string,

old_str: string, // 必须在文件中唯一出现——防止错误替换

new_str: string, // 替换为新内容（空字符串 = 删除）

}

// AgentTool：创建单个子 Agent（串行子任务）

AgentTool.execute({

task: ‘扫描 src/ 目录下所有 TODO 注释并汇总’,

tools: [‘FileReadTool’, ‘GrepTool’] // 子 Agent 可用的工具子集

})

// TeamCreateTool：创建多个并行 Agent（并行子任务）

TeamCreateTool.execute({

agents: [

{ role: ‘security-reviewer’, task: ‘检查 SQL 注入风险’ },

{ role: ‘perf-analyzer’, task: ‘找出 N+1 查询问题’ },

{ role: ‘style-checker’, task: ‘检查命名规范违反’ },

]

})

��值得讨论

多 Agent 并行看起来很强，但实际工程中有个棘手问题：子 Agent 的 Token 消耗是叠加的，一个稍微复杂的多 Agent 任务很容易烧掉十倍于单 Agent 的 API 费用。Claude Code 的 maxBudgetUsd 参数就是为此设计的。你们团队如何控制 AI 工具的 API 成本？有没有好的实践？

// MCP 服务器支持三种传输层

type MCPTransport =

| { type: ‘stdio’ } // 本地进程，最低延迟

| { type: ‘sse’, url } // HTTP SSE，适合远程服务

| { type: ‘http’, url } // HTTP，适合无状态服务

// 连接建立后的能力协商

const connection = await mcpClient.connect(transport)

const { tools, resources, prompts } = await connection.initialize()

// MCP 工具动态注册为 Claude Code 的原生工具

const mcpTools = tools.map(t => new MCPTool(t, connection))

registry.registerAll(mcpTools)

// main.tsx — 这两行在模块加载时立即执行，不等 main() 函数调用

startMdmRawRead() // 异步读取 MDM 企业配置（macOS）

startKeychainPrefetch() // 异步读取钥匙串中的 API Key

// 等到真正需要这些数据时，大概率已经 ready 了

async function main() {

const apiKey = await getKeychainValue() // 通常已经 resolved

// …

}

缓存类型

实现

适用场景

函数记忆化

lodash-es/memoize 包装纯函数

getGitStatus、getUserContext 等一次性采集

文件状态缓存

FileStateCache (Map<path, {content, hash}>)

避免同一文件在一次会话中重复读盘

上下文缓存

Anthropic API 的 cache_control 参数

system prompt 内容不变时节省 Token 费用

import { feature } from ‘bun:bundle’

// 构建时 feature(‘VOICE_MODE’) 被求值为 true/false

// false 分支的代码整个被 tree-shaking 掉

const voiceCommand = feature(‘VOICE_MODE’)

? require(‘./commands/voice/index.js’).default

: null

// 当前已知的功能开关

// PROACTIVE | KAIROS | BRIDGE_MODE | DAEMON | VOICE_MODE | AGENT_TRIGGERS

设计模式

应用位置

AI Agent 场景下的特殊考量

策略模式

Tool 接口

每个工具是一个独立策略，LLM 动态选择调用哪个——选择者是 AI 而非代码逻辑

代理模式

MCPTool

远程 MCP 服务的本地代理，对 QueryEngine 透明——跨进程/网络的工具调用

组合模式

系统提示构建

多个上下文片段组合成完整 prompt——组合的粒度和顺序影响 LLM 理解效果

观察者模式

流式响应渲染

QueryEngine 产生事件，UI 订阅渲染——生成器替代传统事件总线

命令模式

斜杠命令系统

命令封装为对象，支持 prompt/action/jsx 三种执行类型

��一个 AI 特有的模式：Prompt as Interface

在 AI Agent 开发中有个传统软件不存在的「模式」：工具的 description 字段是 AI 与工具之间的接口契约。

传统开发中接口通过类型系统约束（编译器检查）；Agent 开发中接口通过自然语言约束（LLM 理解）。

这意味着：description 不是可选的文档，而是决定工具能否被正确调用的核心代码。

实践建议：description 里要说清楚「什么时候用」「什么时候不用」「输入输出是什么格式」，就像写精确的函数文档一样。

��值得讨论

Claude Code 的架构反映了当前 AI Agent 工程实践的一个基本判断：Agent 的能力边界由工具系统决定，工具系统的质量由接口设计决定，接口设计的质量由 description 和 schema 决定。你在做 AI 相关项目时，遇到过哪些「设计上的坑」？欢迎评论区交流。