kimi-code 深度掌握系列文章-从 kimi-code 到你的 Agent（十七）

这是系列最后一篇。前面 16 篇建立了完整的认知体系，现在我们要回答最关键的问题：怎么基于 kimi-code 做出属于你自己的 Agent？

1. 理解你的目标

在动手之前，先回答三个问题：

1. ​你的 Agent 要解决什么问题？​是编程助手、数据分析师、运维机器人，还是某个垂直领域的专家？
2. ​用户交互方式是什么？​CLI、Web UI、API、IDE 插件，还是嵌入到现有系统中？
3. ​你需要什么独特能力？​哪些是 kimi-code 已有的，哪些需要你从头构建？

这三个问题的答案决定了你走哪条路线。

2. 架构决策：保留什么，替换什么

kimi-code 的架构像一层层洋葱——你可以只剥开外面几层，也可以一路剥到核心。下面是各层的"复用友好度"评估：

层	复用度	说明
CLI/TUI（apps/kimi-code）	⭐⭐	如果你做 CLI Agent 可以基于它改，否则可以忽略
Web UI（apps/kimi-web）	⭐⭐	Vue 3 实现，适合做 Web Agent 的参考
VS Code 扩展（apps/vscode）	⭐	高度特定于 kimi-code 品牌，参考价值有限
node-sdk	⭐⭐⭐⭐	如果你想快速接入引擎，这是最好的入口
agent-core（V1）	⭐⭐⭐⭐⭐	核心资产，几乎所有 Agent 都需要
agent-core-v2（V2）	⭐⭐⭐⭐⭐	V2 引擎，架构更优但文档可能不完整
kosong	⭐⭐⭐⭐⭐	LLM 抽象层是独立包，几乎零成本复用
kaos	⭐⭐⭐⭐⭐	执行环境抽象也是独立包，可以直接用或扩展
transcript	⭐⭐⭐⭐	如果你的 Agent 需要会话记录和回放，非常有用
kap-server	⭐⭐⭐	如果要做 HTTP 服务化的 Agent，可以参考
pi-tui	⭐⭐⭐	差分渲染 TUI 库，做终端应用的好选择

核心原则：kosong 和 kaos 是两块基石，agent-core 是引擎，其他都是"壳"——根据你的交互方式选择或替换即可。

3. 路线 A：基于 SDK 的轻量定制

推荐指数：⭐⭐⭐⭐ 难度：低 灵活性：中

适合场景：你想做一个有自定义 UI 和特定工具集的 Agent，但不想深入引擎内部。

核心思路

你的应用 (自定义 UI) │ └── @moonshot-ai/kimi-code-sdk (node-sdk) │ ├── KimiHarness: 管理会话、认证、配置 ├── Session.prompt(): 发送请求 ├── Session.onEvent(): 监听事件 └── 自定义工具注册 │ └── @moonshot-ai/agent-core (引擎) ├── kosong (LLM 抽象) └── kaos (执行环境)

实现要点

// 1. 初始化 harness
import { KimiHarness } from '@moonshot-ai/kimi-code-sdk';

const harness = await KimiHarness.create({
  auth: { /* 认证配置 */ },
  config: { /* Agent 配置 */ },
});

// 2. 创建 Session
const session = await harness.createSession();

// 3. 注册自定义工具
session.registerTool({
  name: 'my_custom_tool',
  description: '我的自定义工具',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string', description: '查询参数' }
    },
    required: ['query'],
  },
  execute: async (params) => {
    // 你的业务逻辑
    return { result: `处理了: ${params.query}` };
  },
});

// 4. 发送 prompt 并处理事件
session.onEvent((event) => {
  switch (event.type) {
    case 'text_delta':  /* 流式文本 */ break;
    case 'tool_call':   /* 工具调用 */ break;
    case 'completed':   /* 完成 */ break;
  }
});

await session.prompt('帮我分析这份数据');

// 5. 清理
await session.dispose();
await harness.dispose();

这条路线你保留的

• 整个 agent-core 引擎（TurnFlow、ToolManager、权限系统等）
• kosong 和 kaos 抽象层
• SDK 的事件模型和会话管理

你需要做的

• 构建自己的 UI（Web、CLI、API 等）
• 定义你的自定义工具集
• 设计你的 Agent 的 system prompt / profile
• 处理认证和配置

​注意：​node-sdk 目前是 kimi-code 项目的一部分，没有作为独立的 npm 包发布。你需要 fork 这个仓库或者将 SDK 代码提取出来。

4. 路线 B：基于 agent-core 的深度定制

推荐指数：⭐⭐⭐⭐⭐ 难度：中 灵活性：高

适合场景：你需要深度定制 Agent 的行为——修改 TurnFlow、自定义 Compaction 策略、添加新的执行模式等。

核心思路

不依赖 node-sdk，直接使用 agent-core + kosong + kaos 构建。

你的 Agent 应用 │ ├── kosong (LLM 抽象，直接用或扩展) ├── kaos (执行环境直接用或扩展) └── agent-core (引擎，选择性使用 + 定制) │ ├── 使用: ToolManager, PermissionManager, ContextMemory ├── 扩展: 自定义 Compaction, 自定义 PlanMode └── 替换: 自己的 Agent 编排逻辑

实现要点

// 1. 直接使用 kosong
import { createChatProvider, generate } from '@moonshot-ai/kosong';

const provider = createChatProvider('openai', 'gpt-4o');
const response = await generate({
  provider,
  systemPrompt: '你是一个数据分析助手',
  tools: [myTools],
  history: conversationHistory,
});

// 2. 直接使用 kaos
import { LocalKaos } from '@moonshot-ai/kaos';

const kaos = new LocalKaos('/workspace');
const files = await kaos.glob('**/*.ts');
const content = await kaos.readText('package.json');

// 3. 选择性使用 agent-core 组件
import { ToolManager, PermissionManager, ContextMemory } from '@moonshot-ai/agent-core';

// 4. 构建自己的 Agent 编排逻辑
class MyAgent {
  constructor(config) {
    this.toolManager = new ToolManager(config.tools);
    this.permissionManager = new PermissionManager(config.permissions);
    this.context = new ContextMemory(config.systemPrompt);
  }

  async run(userPrompt: string): Promise<string> {
    this.context.addUserMessage(userPrompt);

    let turnComplete = false;
    while (!turnComplete) {
      const response = await generate({
        provider: this.provider,
        systemPrompt: this.context.getSystemPrompt(),
        tools: this.toolManager.getToolSchemas(),
        history: this.context.getMessages(),
      });

      if (response.toolCalls.length > 0) {
        for (const tc of response.toolCalls) {
          await this.permissionManager.check(tc);
          const result = await this.toolManager.execute(tc);
          this.context.addToolResult(tc.id, result);
        }
      } else {
        this.context.addAssistantMessage(response.text);
        turnComplete = true;
      }
    }

    return this.context.getLastAssistantMessage();
  }
}

这条路线你保留的

• kosong：完整的 LLM 抽象层，多供应商支持
• kaos：完整的执行环境抽象
• agent-core 的关键子系统：ToolManager、PermissionManager、ContextMemory

你需要做的

• 实现自己的 Agent 编排逻辑（替代 TurnFlow）
• 定义 Compaction 策略
• 实现自己的 Plan/Goal/Swarm 模式（如果需要）
• 构建自己的 UI 和通信层

5. 路线 C：基于 agent-core-v2 的全新构建

推荐指数：⭐⭐⭐ 难度：高 灵活性：最高

适合场景：你需要最先进的 DI x Scope 架构，或者想要构建一个多租户的 Agent 平台。

核心思路

基于 agent-core-v2 的域划分（_base、agent、app、session、kosong、os、persistence、tool、wire）来构建你的 Agent。

你的 Agent 平台 │ ├── 你的 Session 管理 ├── 你的 UI 层 └── agent-core-v2 ├── DI 容器（应用级 Scope） ├── Agent Scope（每个 Agent 独立 Scope） │ ├── 上下文注入器 │ ├── LLM 请求器 │ ├── 权限管理器 │ └── 技能管理 └── Session Scope（会话级服务） ├── 交互管理 ├── 审批管理 └── 子 Agent 管理

关键决策点

• ​是否使用 kap-server？​如果不需要 HTTP 服务化，可以跳过，直接嵌入 agent-core-v2
• ​是否使用 klient？​如果构建服务化 Agent，klient 提供类型安全的客户端门面
• ​持久化后端：​minidb（嵌入式）vs 你自己的存储方案

6. 关键扩展点详解

不管你走哪条路线，以下扩展点是你最可能接触的：

6.1 自定义工具

这是最常见的扩展。你只需要实现 Tool 接口：

interface CustomTool {
  name: string;                    // 工具名称
  description: string;             // 给 LLM 看的描述
  parameters: JsonSchema;          // 参数 JSON Schema
  execute(params): Promise<any>;   // 执行逻辑
  permission?: 'default' | 'auto' | 'yolo'; // 权限级别
}

然后把工具注册到 ToolManager，它会自动生成 LLM function calling 的 schema。

6.2 自定义 LLM Provider

如果你想接入 kimi-code 不支持的模型（如国产大模型），实现 ChatProvider 接口：

class MyProvider implements ChatProvider {
  name = 'my-provider';
  modelName = 'my-model';

  async generate(systemPrompt, tools, history, options) {
    // 调用你的模型 API
    // 返回流式响应（AsyncIterable<ContentPart>）
  }

  withThinking(effort) { /* 返回新实例 */ }
  withMaxCompletionTokens(n) { /* 返回新实例 */ }
}

6.3 自定义 Compaction 策略

如果你的场景有特殊的上下文管理需求，可以实现自定义 Compaction：

class MyCompactor implements Compactor {
  shouldCompact(context: ContextMemory): boolean {
    // 判断是否需要压缩
  }
  compact(context: ContextMemory): CompactedResult {
    // 你的压缩算法
  }
}

6.4 自定义 Profile（System Prompt）

通过修改 profile 配置，你可以完全改变 Agent 的行为模式：

// 一个数据分析 Agent 的 profile 示例
const myProfile = {
  systemPrompt: `
    你是一个专业的数据分析师。
    - 你擅长 SQL、Python 数据分析
    - 你会主动发现数据中的模式和异常
    - 你输出的分析结论要有数据支撑
    - 不确定时要主动验证而不是猜测
  `,
  tools: ['bash', 'read', 'write', 'web_search'],
  capabilities: {
    goalMode: true,    // 启用自主执行
    planMode: false,   // 不需要代码审查规划
  },
};

7. 实战路线图

这是一个为期 4-6 周的实战计划：

第 1 周：跑起来 + 选路线

fork 仓库，在本地跑通开发环境（pnpm dev:cli）。用一个简单的自定义工具验证你能修改 Agent 行为。根据验证结果确定走 A/B/C 哪条路线。

第 2 周：核心定制

定义你的 Agent 的 Profile（system prompt），设计并实现核心工具集。如果用路线 B，实现自己的 Agent 编排循环。

第 3 周：交互层

构建用户界面。CLI 用 pi-tui，Web 可以参考 kimi-web 的 Vue 3 架构，API 方式可以参考 kap-server 的 Fastify 模式。

第 4 周：打磨 + 扩展

添加错误处理、日志、监控。根据需要扩展 Compaction 策略、Plan Mode、Goal Mode。编写测试。

第 5-6 周（可选）：高级特性

MCP 工具集成、自定义 LLM Provider、多租户支持、性能优化、打包分发。

---

最后的建议

kimi-code 是一份非常高质量的 Agent 架构参考。它的价值不在于你直接用它，而在于你理解它的设计决策之后，在自己的场景中做出正确的选择。

几个关键原则：

1. ​先跑通最小闭环​：一个自定义工具 + 一个自定义 prompt = 你就拥有了自己的 Agent
2. ​不要过早优化​：先用最简单的实现验证价值，再考虑 Compaction、Swarm 等高级特性
3. ​kosong 和 kaos 是独立宝藏​：即使不用 agent-core，这两个包也值得在你的任何 AI 项目中使用
4. ​跟踪上游​：kimi-code 在快速演进，V2 引擎成熟后可能带来新的最佳实践

🎉 恭喜你完成了这 17 篇文章的学习！
现在，去构建属于你自己的 Agent 吧。