AI Research 技术调研

月之暗面 Kimi Code CLI：无沙箱、策略链权限、handoff-note 压缩的多 provider TS harness

29分钟阅读

月之暗面 Kimi Code CLI

一句话定位

Moonshot AI 官方开源的 CLI/TUI 编码 agent harness（MIT 协议，TypeScript pnpm monorepo），核心是一个刻意做成 stateless、host-agnostic 的循环引擎 agent-core；对 Kimi 模型系不独占，同时支持 Anthropic/OpenAI/Gemini/Vertex 等多 provider 协议；无 OS 级沙箱，隔离完全依赖 19 策略链式权限系统；Claude Code 兼容的 hooks/skills 模型，并自带 import-from-cc-codex 迁移 skill，明确面向从 Claude Code / Codex CLI 迁移的用户。

核心架构总览

仓库为 pnpm workspaces + Nix flake 的 TypeScript monorepo，分析基于 commit 4aeb33637f8c707ff21198fb59185929a4334f47（2026-07-07 浅克隆）：

apps/
  kimi-code/      # CLI/TUI 入口 (src/main.ts)，只依赖 node-sdk，不直接依赖 agent-core
  kimi-web/       # 浏览器 UI (Vue3+Vite)，走 REST+WS /api/v1
  kimi-desktop/   # 桌面壳
  vis/            # session wire.jsonl 轨迹可视化调试工具 (server+web)
packages/
  agent-core/     # 核心引擎：Agent/Session/profile/skill/tool/plan/permission/
                  # background-task/records(事件日志)/DI service 层 (src/services/)
  kosong/         # LLM/provider 抽象层（多 provider wire 协议）
  kaos/           # "Kimi Agent Operating System" — 执行环境抽象（local/ssh）
  node-sdk/       # 公开 TS SDK，apps/kimi-code 通过它间接使用 agent-core
  server/         # 托管 agent-core session 的服务端 (REST+WS)
  protocol/       # wire 协议类型
  oauth/          # Kimi OAuth / 托管认证
  telemetry/      # 客户端遥测
  pi-tui/         # 终端 UI 工具包
  acp-adapter/    # Agent Client Protocol 适配器（Zed/JetBrains 等 IDE 集成）
plugins/official/kimi-datasource/
.agents/skills/   # kimi-code 自身开发用的 meta-skill

架构约束直接来自根 AGENTS.md（该文件本身即项目对 AI 贡献者的架构地图，精确度高于常见 README）：apps/kimi-code 被显式禁止直接依赖 @moonshot-ai/agent-core，必须经 @moonshot-ai/kimi-code-sdk（node-sdk）间接调用；packages/agent-core/src/services/AGENTS.md 记录了一套 VSCode 平台风格的 DI service 层（IXxxService/XxxService 约定，registerSingleton，InstantiationType.Delayed/Eager），覆盖 coreProcess/event/approval/question/environment/logger/fileStore/fs 系列/workspace/config/session/message/prompt/tool/mcp/task/oauth/authSummary 等服务。

Agent Loop（主循环 / 何时继续何时停）

循环被显式拆成独立的、无状态的库模块 packages/agent-core/src/loop/，自带 README.md：

  • run-turn.ts::runTurn()（全文 184 行）是 turn 级收敛逻辑：while(true) { steps+=1; stepResult=executeLoopStep(...); if (stepResult.stopReason==='tool_use') continue; else { 评估 hooks.shouldContinueAfterStop(); 不继续则 break } }（run-turn.ts:100-149）。有 maxSteps 硬上限（抛 MaxStepsExceededError），跨 step 累加 TokenUsage（addUsage），abort 时区分 user_cancelled 与普通 aborted（isUserCancellation(signal.reason)，run-turn.ts:150-159）。hooks.shouldContinueAfterStop 是”非工具停止后是否继续”的扩展点（Goal Mode 借此在 end_turn 后继续跑）。
  • turn-step.ts::executeLoopStep()（全文 363 行）是单次 provider round-trip：beforeStep 钩子（可阻断该 step，如权限/压缩 gating）→ 重新解析工具表（buildTools()，每 step 都重新求值以尊重压缩后被裁剪的 schema）→ buildMessages() → 派发 step.begin → 流式调用 LLM → 遇到结构性 400（tool_use/tool_result 不相邻、角色不交替等 wire 格式错误）时用严格重建的消息 buildMessagesStrict 重试恰好一次（turn-step.ts:142-182，针对 provider wire 边界情况的防御性设计）→ 根据 providerFinishReason 映射停止原因（tool_calls→tool_use，truncated→max_tokens，filtered→filtered，paused→paused）→ 若为 tool_use 则跑 runToolCallBatch → 派发 step.end → afterStep 钩子。
  • 工具执行并发：tool-scheduler.ts::ToolScheduler（全文 101 行）是资源冲突调度器——ToolAccesses 不冲突的任务并发跑，冲突任务排队等冲突中的任务结束后才启动（tool-scheduler.ts:1-100）。这是同一 step 内多个并行工具调用（如并行 Read/Grep）安全并发、同时对写同一资源的调用做串行化的机制。
  • 停止原因是封闭枚举：end_turn | tool_use | max_tokens | filtered | paused | unknown | aborted。

记忆与上下文管理（压缩、长期记忆、会话持久化）

代码中存在两条压缩路径，只有一条是活的：

  • micro.ts（MicroCompaction，全文 169 行）——按工具结果逐条截断，受实验性 flag micro_compaction 控制，该 flag 已从 flag 注册表中移除，导致 detect()/compact() 是硬编码 no-op（原实现整段被注释保留为死代码，micro.ts:1,50-53,110-113）——确认是”彻底禁用”而非”默认关闭”。
  • full.ts（FullCompaction）是实际生效路径：在模型 max_context_tokens 的 triggerRatio=0.85 处触发，blockRatio=0.85 同值（即默认 checkAfterStep=false，压缩是同步阻塞的，不是后台异步）（strategy.ts:25-31）；保留 reservedContextSize=50,000 token 余量；maxOverflowCompactionAttempts=3 防止”溢出→压缩→再溢出”死循环（strategy.ts:12-17）。
    • 压缩后的历史重写为：保留的用户消息原文（预算 COMPACT_USER_MESSAGE_MAX_TOKENS=20,000，超预算时按 HEAD COMPACT_USER_MESSAGE_HEAD_TOKENS=2,000(最早) + TAIL(最近) 切分、中间加省略标记）+ 紧随其后的一条 COMPACTION_SUMMARY_PREFIX 前缀的用户角色 handoff 摘要（handoff.ts:1-36）。assistant 消息、工具调用与工具结果被整体丢弃。
    • 摘要由模型自己按 compaction-instruction.md（全文 79 行）生成——这是一段刻意设计成”写一份第一人称交接笔记给未来的自己”的 prompt，而非第三方报告，明确要求保留：当前请求意图、生效中的约束/决策、已执行的确切命令/路径/结果、已知未知项、具体的前进计划；并要求用对话原本的语言写作而非强制英文。TODO 列表不重复进摘要——与其活的数据源分开重新附加，避免矛盾。
    • compactionUserMessageDisposition()（handoff.ts:61-80）是唯一权威判定：只有 kind:'user' 与 slash 触发的 skill/plugin 激活算作”压缩后原文保留的真实用户输入”；注入内容、shell 命令、压缩摘要本身、系统触发、后台任务/cron 通知、hook 结果、重试等一律被丢弃。
    • 系统提示本身（system.md:65-74，”# Context Management” 一节）向模型显式讲解压缩的工作方式，并指示模型将摘要视为权威、不要重做已完成的工作——即压缩契约是”教给模型”的，不只是代码层实现。
  • 会话持久化：session-store.ts — session 存放于 ~/.kimi-code/sessions/<workDirKey>/<sessionId>/（workDirKey 是工作目录的哈希桶）。每个 session 目录含 agents/main/wire.jsonl（主 agent 完整回放/恢复日志）+ 每个子 agent 一份 agents/agent-<N>/wire.jsonl、state.json（标题/lastPrompt/时间戳/forkedFrom）、plans/、tasks/（后台任务持久化）、cron/（kimi resume 时重新加载的定时任务持久化）——验证自 docs/en/configuration/data-locations.md:71-84。
  • 事件日志：records/types.ts（全文 122 行）定义 AgentRecordEvents——一个详尽的判别式联合类型（turn.prompt/steer/cancel、config.update、permission.set_mode/record_approval_result、full_compaction.begin/cancel/complete、micro_compaction.apply、plan_mode.、swarm_mode.、tools.、usage.record、context.append_message/append_loop_event/clear/apply_compaction/undo、goal. 等）。文件顶部注释：“当正确性依赖状态转换发生的先后顺序时，用 records，不要用 state.json”——这是 resume/replay/undo 的事件溯源骨架。
  • 没有发现跨会话的长期记忆库（不存在类似”memory MCP”的持久知识存储）；记忆是逐 session 的（wire.jsonl + records）加上用户可编辑的静态 AGENTS.md（非学习型）。

工具体系（定义/调用协议/注册/权限）

packages/agent-core/src/agent/tool/index.ts::ToolManager（全文 765 行）是中心注册/派发器：

  • 三种工具来源：builtin（tools/builtin/*：文件 Read/Write/Edit/Grep/Glob，shell Bash，规划 Enter/ExitPlanMode，目标 Create/Get/SetBudget/UpdateGoal，协作 Agent/AgentSwarm/AskUserQuestion/Skill，状态 TodoList，定时 Cron Create/List/Delete，网络 WebSearch/FetchURL，ReadMediaFile）；用户工具（registerUserTool/unregisterUserTool 动态 RPC 注册）；MCP 工具（registerMcpServer，命名规则 mcp__<server>__<tool>，含同 server 内与跨 server 的命名冲突检测，tool-manager.ts:247-307）。
  • 渐进式披露（progressive disclosure）：当 agent.toolSelectEnabled 时，MCP 工具不放进发给模型的顶层 tools[]；只有名字经 loadableDynamicToolNames() 传递，模型必须调用内置 select_tools 工具才能把 schema 加载进上下文变为可调用（tool-manager.ts:437-498, 721-763）。已加载工具的状态是从对话历史本身派生的账本（collectLoadedDynamicToolNames）与一个”待定”集合（schema 消息落地前的延迟窗口）的并集——刻意设计为对 resume/undo/压缩安全，因为历史记录是唯一权威来源。
  • 工具执行协议：每个 ExecutableTool.resolveExecution(args) 返回一个 execute() 闭包或静态失败输出；执行时接收 {turnId, toolCallId, signal, onUpdate, onForegroundTaskStart}——支持流式局部输出（stdout/stderr 增量）与执行中途的后台任务分离（Ctrl+B）（tool-manager.ts:110-195，runShellCommand 处理用户手输的 ! shell 命令，复用与 agent 调用相同的 BashTool/kaos/BackgroundManager）。
  • 权限门控：每个工具携带一个供权限层消费的 approvalRule 字符串（见”安全与权限”节）。
  • 工具调用参数在到达 resolveExecution 之前，先在循环的 preflight 阶段做一次 JSON 解析与 schema 校验（loop/tool-args-parse.ts，未全文精读）。
  • 子 agent 工具：AgentTool（单次子 agent 生成，profile 可选）与 AgentSwarmTool（扇出，见 Router 节）本身也作为普通工具注册，依赖 agent.subagentHost 存在。

Prompt 设计（系统提示结构、动态组装）

  • 模板引擎：nunjucks（{{ var }}/{% if %}），经统一函数 renderPrompt() 渲染，autoescape:false（prompt 文本非 HTML）、throwOnUndefined:true（缺失模板变量是构建期式的显式报错，绝不会把 {{ placeholder }} 字面量泄漏给模型）——packages/agent-core/src/utils/render-prompt.ts（全文 20 行）。
  • 系统提示（packages/agent-core/src/profile/default/system.md，全文 159 行）用变量模板化：{{ROLE_ADDITIONAL}}（子 agent 角色覆盖点）、{{KIMI_OS}}、{{KIMI_SHELL}}、{% if KIMI_OS=="Windows" %} 分支、{{KIMI_NOW}}（session 开始时捕获一次，明确告知模型可能已过期）、{{KIMI_WORK_DIR}}、{{KIMI_WORK_DIR_LS}}（两级目录树）、{{KIMI_ADDITIONAL_DIRS_INFO}}、{{KIMI_AGENTS_MD}}（合并的项目 AGENTS.md 内容，被明确降级为”非特权指令通道”，有文档化的优先级顺序：用户 > 更高优先级的系统规则 > 更具体的 AGENTS.md 文件优先于不那么具体的）、{{KIMI_SKILLS}}（按 scope 分组 Project>User>Extra>Built-in 的条件性 skill 清单）。
  • 值得注意的明文表述：“The operating environment is not in a sandbox”（system.md:85）——直接、承重的沙箱声明（见”沙箱”节）。还有显式的语言镜像规则、显式的工具并行建议（“HIGHLY RECOMMENDED” 批量发起独立工具调用）、显式的 <system> vs <system-reminder> 标签语义（后者是”权威指令”，可覆盖常规行为，如计划模式的只读限制），以及一整段内嵌的压缩机制说明，让模型能自我叙述连续性。
  • 动态注入层（packages/agent-core/src/agent/injection/manager.ts）：InjectionManager 每 step 跑一组固定的 DynamicInjector（PluginSessionStartInjector、TodoListReminderInjector、PlanModeInjector、PermissionModeInjector），另有两个刻意排除在每 step 循环外、只在”边界节奏”触发的注入器（为保护 prompt cache）：GoalInjector（仅在 turn 开始/续接/压缩后边界追加目标提醒，仅主 agent）与 ToolsDiffInjector（宣布新可加载的 MCP 工具名，主/子 agent 都有）。注释明确说明设计原因：逐 step 注入此前在上下文增长下是 O(n²) 且破坏 prompt caching，边界节奏 + 仅追加同时解决了两个问题。
  • Profile 系统：YAML profile（agent.yaml、explore.yaml、coder.yaml、plan.yaml）可 extends: agent 并覆写 promptVars.roleAdditional + 限定 tools: 列表——这就是子 agent 人格的构造方式（explore.yaml 全文：只读代码探索人格，显式工具白名单 Bash, Read, ReadMediaFile, Glob, Grep, WebSearch, FetchURL，无 Write/Edit）。

Router / 编排（任务分解、多 agent、子 agent）

  • 子 agent 生成：packages/agent-core/src/session/subagent-host.ts::SessionSubagentHost。默认子 agent 超时 DEFAULT_SUBAGENT_TIMEOUT_MS = 30*60*1000（30 分钟）；子 agent 被叠加 DenyAllPermissionPolicy（不能静默越权于父级授予的范围之外）；子 agent 完成摘要短于 SUMMARY_MIN_LENGTH=200 字符会触发一次自动追问要求扩写（SUMMARY_CONTINUATION_ATTEMPTS=1）——针对”技术上完成但交接不可用”的具体设计防护。
  • 还支持一种轻量”侧问”子 agent 模式（SIDE_QUESTION_SYSTEM_REMINDER，禁用工具调用、纯文本），用于主 agent 继续工作时的旁路用户问答，明确告知它”不要提及自己被打断”。
  • Profile 决定子 agent 角色：agent.yaml 的 subagents: map 声明 coder（唯一有文件编辑工具的子 agent）、explore（只读、快速）、plan（只读，架构/规划）——默认 profile 下固定的三角色 router 分类。
  • AgentSwarm（packages/agent-core/src/agent/swarm/index.ts，全文 61 行 + agent-swarm.md 工具描述）：从一个带 {{item}} 占位符的 prompt 模板一次扇出最多 128 个子 agent，或恢复一组既有子 agent ID，或两者同时。启动前强制校验（任一失败则整批不启动）：无 resume 时 items ≥2；prompt_template 必须包含 {{item}}；展开后的 prompt 必须两两不同。SwarmMode 追踪激活触发方式（manual 经 /swarm on、task 一次性、tool 经 AgentSwarm 工具调用本身），并注入进入/退出提醒（除非是静默的工具触发）。权限策略 AgentSwarmExclusiveDenyPermissionPolicy 使 AgentSwarm 调用在该 step 内批次排他（必须是该 step 唯一的工具调用），无论权限模式如何（policies/index.ts:33 确认）。
  • swarm 子 agent 的并发上限经 session/subagent-batch.ts::resolveSwarmMaxConcurrency 解析（未全文精读）。
  • 没有发现”planner LLM vs executor LLM”式的独立拆分；任务分解完全由 prompt/工具驱动（模型自己调用 Agent/AgentSwarm 来分解），不是硬编码的独立规划模块。唯一例外是 plan.yaml/Plan Mode——一个一等公民模式（EnterPlanMode/ExitPlanMode 工具、plan_mode.* 事件记录、专属权限策略 PlanModeGuardDenyPermissionPolicy 与 PlanModeToolApprovePermissionPolicy），在用户批准退出计划模式前将 Write/Edit 限制在单一计划文件内。

Skill / 插件体系

  • Skills（docs/en/customization/skills.md，全文 131 行）：带 YAML frontmatter（name、description、type: prompt|inline|flow、whenToUse、disableModelInvocation、arguments）的 Markdown 文件，目录形式（<name>/SKILL.md，推荐，可配套参考文件/脚本）或扁平形式（<name>.md）。正文占位符展开：$ARGUMENTS、$ARGUMENTS[0]/$0 位置参数（引号感知分词）、$<name> 具名参数、${KIMI_SKILL_DIR}。四层 scope 解析，最具体优先：Project（.kimi-code/skills/、.agents/skills/）> User（$KIMI_CODE_HOME/skills/、~/.agents/skills/）> Extra（config.toml 里的 extra_skill_dirs）> Built-in（CLI 自带：mcp-config、custom-theme、update-config、write-goal、sub-skill review/consolidate、import-from-cc-codex）。模型经 description/whenToUse 匹配自动触发，除非 disableModelInvocation:true 或 type:flow；嵌套上限 3 层。手动触发用 /skill:<name> <args>。
  • 实现：packages/agent-core/src/skill/{scanner,parser,registry,types}.ts + builtin/*（目录结构确认了 scanner/parser/registry 分离，以及一个 sub-skill.ts + 嵌套的 sub-skill/{SKILL.md, consolidate/SKILL.md, review/SKILL.md} meta-skill；未逐行精读）。
  • 插件（packages/agent-core/src/plugin/{manager,manifest,archive,source,store,commands,github-resolver,types}.ts）：将 skill/MCP server/命令打包成可安装单元；github-resolver.ts 暗示支持 GitHub 托管插件安装；状态持久化于 ~/.kimi-code/plugins/installed.json，zip/本地路径安装有 managed/<id>/ 副本（data-locations.md:35-37,68）。
  • Kimi Code 显式自带一个 import-from-cc-codex 内置 skill——即从 Claude Code 与 Codex CLI 导入配置/skill 的一等迁移路径，是团队面向跨 harness 可移植性设计的直接证据。

自进化能力（自我改进 / 学习型记忆 / eval 驱动纠错）

  • 未发现模型微调或权重更新回路——这只是一个推理时（inference-time）harness，仓库里没有任何东西训练或适配底层 LLM。
  • 最接近的类比是 Goal Mode（packages/agent-core/src/agent/goal/index.ts + docs/en/guides/goals.md）：一个持久化的、有预算约束的自主续接循环。每 agent 一个 goal，状态为 active|paused|blocked|complete（complete 是瞬态的，宣布后即清除，不持久化）。goal 驱动器在 active 时持续跑续接 turn，每 turn 后检查模型是否自报目标已达成（UpdateGoal('complete')）或受阻（UpdateGoal('blocked')），并独立强制硬预算（token/turn/墙钟时间）超限时强制置为 blocked。这只在”模型每 turn 自评进度并决定继续/停止/升级”的弱意义上算 eval 驱动纠错——没有外部评测 harness 或打分反馈信号驱动它，也没有跨会话的持久化学习记忆。
  • Cron（packages/agent-core/src/agent/cron/、packages/agent-core/src/tools/cron/）提供定时/周期性任务重新调用（持久化，kimi resume 时重新加载），是”跨时间自主性”基础设施，但同样不是模型自我改进。
  • 结论：本维度未实现（提示词要求的”自我改进/学习驱动纠错”意义上）——记为”不适用：存在推理时自主性（Goal Mode），但无学习回路”。

可观测性（日志 / trace 格式）

  • 结构化事件日志（“records”）：records/types.ts 定义的 AgentRecordEvents 是权威的、带版本号（metadata 记录里的 protocol_version，records/migration/*.ts 有 v1.1–v1.4 迁移模块）事件溯源日志，覆盖每一次状态转换。注释：“当正确性依赖状态转换的先后顺序时，用 records，不要用 state.json。”
  • wire 级会话轨迹：每个 session 的 agents/main/wire.jsonl（及每子 agent 一份 agents/agent-N/wire.jsonl）是完整回放/恢复日志——JSONL 格式，一行一条（data-locations.md:79-81）。
  • 可视化轨迹调试器：apps/vis（@moonshot-ai/vis，package.json 描述”Debug visualization tool for kimi-code sessions”）——专门用于查看这些 session 轨迹的 server+web 应用（仅确认其存在与用途，未深读）。
  • 诊断日志：packages/agent-core/src/logging/{logger,formatter,sinks,resolve-config,types}.ts——全局日志 ~/.kimi-code/logs/kimi-code.log，session 级日志 <sessionDir>/logs/kimi-code.log（仅在诊断事件发生时创建）。kimi export 打包 session + 可选全局日志用于提交 bug 报告（--no-include-global-log 可排除）。
  • 遥测：packages/telemetry/src/types.ts（全文 33 行）定义 TelemetryEvent{event_id, device_id, session_id, event, timestamp, properties}，传输前补充 context 对象；TelemetryTransport 接口支持 send/saveToDisk/retryDiskEvents（离线/重试的磁盘缓冲）。遥测调用贯穿权限系统（permission_policy_decision、permission_approval_result 事件，含策略名/工具名/决策/耗时/是否给出反馈，permission/index.ts:102-108,221-233 直接可见）与工具使用（视频上传遥测，tool/index.ts:672-700）。
  • 单 step LLM 耗时按细粒度记录：TTFT 拆分为客户端请求构建时间 vs 网络/服务端时间，解码窗口拆分为服务端等待 vs 客户端处理时间（turn-step.ts:246-274，logStepTiming）。

安全与权限（审批门、密钥管理）

  • 策略链式权限引擎：agent/permission/index.ts::PermissionManager + policies/index.ts（全文确认了精确评估顺序——第一个非 undefined 结果生效）：
    1. PreToolUse hook 阻断 → 拒绝
    2. AgentSwarm 批次排他性（非唯一调用时）→ 拒绝
    3. auto 模式 + AskUserQuestion（auto 模式不能问用户）→ 拒绝
    4. 计划模式守卫（计划文件之外的 Write/Edit，或 TaskStop）→ 拒绝
    5. 用户配置的 deny 规则 → 拒绝
    6. auto 模式 → 批准
    7. 会话记忆的”本次会话已批准”规则 → 批准
    8. 用户配置的 ask 规则 → 询问
    9. 用户配置的 allow 规则 → 批准
    10. ExitPlanMode 且存在活跃、非空、非 auto 的计划评审 → 询问
    11. CreateGoal（非 auto）→ 询问（选择该 goal 运行的权限模式）
    12. 计划模式工具批准（EnterPlanMode、计划文件写入、无害的 ExitPlanMode）→ 批准
    13. 敏感文件（.env、SSH 密钥、凭据）访问 → 询问
    14. .git/git 控制目录路径访问 → 询问
    15. yolo 模式 → 批准
    16. swarm-mode-only 的 AgentSwarm 批准
    17. 默认批准列表（只读/UI 辅助工具）→ 批准
    18. git worktree 内、cwd 内、POSIX 路径的 Write/Edit → 批准
    19. 兜底 → 询问
    • 权限模式：manual（默认）、auto、yolo，加上计划模式作为正交的守卫层。模式可父子继承（子 agent 的 PermissionManager.mode 回退到 parent?.mode）。
    • 批准请求携带 display（kind/summary/detail），经 agent.rpc.requestApproval（宿主提供的 UI 回调）处理，周围触发 PermissionRequest/PermissionResult hook 事件；拒绝提示对子 agent（“换个方法……别试图绕过限制”）与主 agent（更委婉，“调整方法或询问用户”）措辞不同。
    • “本会话已批准”结果缓存为规则模式（sessionApprovalRulePatterns），从父会话继承到子会话。
  • Hooks（docs/en/customization/hooks.md，全文 158 行）——config.toml 里的 [[hooks]]，event+matcher(正则)+command+timeout(1-600秒，默认30)。退出码语义：0=允许，2=阻断（stderr 为原因），其他非零或超时/崩溃 = fail-open（默认放行）——文档明确说明这是刻意的设计选择，并警告 hooks 不应作为唯一的安全屏障。可阻断事件：UserPromptSubmit、PreToolUse、Stop；其余（PostToolUse、PostToolUseFailure、PermissionRequest/Result、SessionStart/End、SubagentStart/Stop、StopFailure、Interrupt、PreCompact/PostCompact、Notification）仅可观察。这基本是 Claude Code hook 事件模型的直接移植（同名事件、同退出码语义）。
  • 密钥/凭据处理：Read/Write/Edit 默认拒绝一组已知敏感文件（.env、SSH 私钥、部分凭据文件），但系统提示明确警告这份清单不完整，且 Bash 不执行这些防护中的任何一条（system.md:97）——一个文档化、诚实披露的缺口。OAuth 凭据存放于 ~/.kimi-code/credentials/，权限 0700/0600，原子写入（tmp→fsync→rename）（data-locations.md:69）。
  • packages/agent-core/src/tools/policies/{path-access.ts, sensitive.ts} 实现上述策略用到的工作区边界与敏感文件匹配（目录确认，未逐行精读）。

沙箱与执行隔离

  • KAOS（packages/kaos/src/kaos.ts，全文 98 行）是执行环境抽象接口：“allows the agent to interact with different execution environments (local, SSH, containers, etc.) through a unified API”（docstring, kaos.ts:6-10）。但经 grep 验证，本仓库只有两个具体实现：LocalKaos（local.ts）与 SSHKaos（ssh.ts）。没有容器/Docker/gVisor 后端——接口文档里提到的”containers”仅是愿景性措辞，截至本 commit 并未实际落地。
  • 系统提示对此明确无歧义地声明：“The operating environment is not in a sandbox. Any actions you do will immediately affect the user’s system. So you MUST be extremely cautious.”（system.md:85）——这是一个直接承重的设计事实：隔离完全依赖权限/审批策略链（见”安全与权限”节）与提示层面的谨慎指令，而非 OS 级沙箱。
  • Bash 工具执行直接经 kaos.exec()/execWithEnv() 落到真实子进程（LocalKaos）或真实 SSH 会话（SSHKaos）——本代码库中未见 seccomp/namespace/容器包装。
  • 后台任务执行（BashTool 的 allowBackground）支持将长时间运行的前台命令分离（Ctrl+B）为可追踪的后台任务（tasks/<task_id>.json + output.log），但这是进程生命周期管理，不是沙箱化。

与模型的协同设计

  • 多 provider 抽象（kosong）：packages/kosong/src/catalog.ts 定义了类 models.dev 风格目录，KNOWN_WIRE_TYPES 列表为 anthropic | openai | kimi | google-genai | openai_responses | vertexai（catalog.ts:51-58）。kimi 是一等公民 wire 类型（OpenAI 兼容协议，docs/en/configuration/providers.md:9-12），与 Anthropic/OpenAI/Gemini/Vertex 的完整支持并列——即 Kimi Code CLI 明确不是 Kimi 模型专属的，而是一个由 Moonshot 打造、默认通过托管 OAuth 登录使用 Kimi 模型的通用 harness。
  • ModelCapability（packages/kosong/src/capability.ts，全文 65 行）：按模型声明的能力标志 image_in, video_in, audio_in, thinking, tool_use, max_context_tokens, select_tools?。select_tools 能力标志正是渐进式工具披露（见”工具体系”节）的具体挂钩点——“模型接受消息级工具声明（messages[].tools）……不存在即视为不支持：只有被明确编目或声明该能力的模型才会收到携带 tools 的消息”（capability.ts:18-24）。这暗示 Kimi 模型（K2/K2.5 级）被专门编目为 select_tools:true 以支持渐进披露体验——但本轮未读到 kosong 具体的 catalog 数据文件/Kimi 条目本身，只读了机制层代码，Kimi 具体 model ID 与该标志的对应关系未被证实，需要进一步读 packages/kosong 的 catalog 数据文件或 providers.md 的 “kimi” 完整小节才能坐实。
  • 所有 provider 默认走流式；能力（thinking/vision/tool-use）“按模型名前缀自动匹配”（providers.md:17）——暗示 kosong 内部存在一张按名字前缀推断能力的表，本轮未定位到具体位置。
  • 视频上传被列为 Kimi provider 特有的附加能力（providers.md ”## kimi” 小节：“Additional capability: supports video upload”；tool-manager.ts:659-701 的 createVideoUploader 经 provider.uploadVideo 接入）。

轨迹利用（session/trajectory 是否反哺训练/评测）

  • 本 OSS 仓库中未发现session 轨迹（wire.jsonl、records）被反馈进模型训练或自动化评测管线的证据。对 docs/en/、packages/telemetry/src/、SECURITY.md、README.md 做过 train/finetune/RLHF 的 grep——只有误报命中（docs/en/customization/plugins.md 里一个与 Kimi Code 自身数据无关的 RLHF 文献综述示例）。
  • 确实存在的是 kimi export（把某 session 的 wire.jsonl + 可选全局日志打包成可分享归档，用于bug 报告，data-locations.md:95 + packages/agent-core/src/session/export/*.ts）——这是用户主动发起、opt-in 的支持/调试导出，不是自动回流给 Moonshot 用于训练的遥测管线。
  • 遥测（packages/telemetry/）捕获结构化的使用/行为事件（权限决策、工具使用、视频上传等），但仓库中没有文档或代码迹象表明这些事件被用于 RL/微调；读起来是标准的产品分析（crash.ts 崩溃上报、systemMetrics.ts 系统指标）。
  • 结论：记为”未发现/基于现有公开源码不适用——本仓库中看不到训练反馈管线，遥测看起来只是产品分析”。

与同类 harness 的关键差异（1-3 条，跨 harness 对比留待 synthesis 阶段）

  1. 无沙箱且在系统提示中反复明文声明（system.md:85），隔离完全依赖 19 策略链式权限系统而非 OS 级隔离——这一点比多数同类 CLI harness 更”诚实透明”，也更依赖策略链本身的正确性。
  2. Handoff-note 式压缩：不是泛化的”总结对话”，而是让模型以第一人称给”未来的自己”写交接笔记，且刻意区分”已定决策”与”未决问题”；micro-compaction 曾实现后被显式禁用但保留为死代码，是一条可追溯的”废弃方案审计轨迹”。
  3. Hooks 系统基本是 Claude Code hook 模型的移植（同名事件、同退出码语义、同 fail-open 哲学），并自带 import-from-cc-codex 迁移 skill，证明团队刻意面向 Claude Code / Codex CLI 用户做兼容/迁移设计——这与其”多 provider、不锁定 Kimi 模型”的整体定位一致。

原始源码定位

  • repo: https://github.com/MoonshotAI/kimi-code
  • commit/version analyzed: 4aeb33637f8c707ff21198fb59185929a4334f47（浅克隆，2026-07-07 拉取）
  • 关键文件列表（相对路径）：
    • AGENTS.md（根，架构地图）
    • packages/agent-core/src/services/AGENTS.md（DI service 层约定）
    • packages/agent-core/src/loop/README.md
    • packages/agent-core/src/loop/run-turn.ts
    • packages/agent-core/src/loop/turn-step.ts
    • packages/agent-core/src/loop/tool-scheduler.ts
    • packages/agent-core/src/agent/compaction/strategy.ts
    • packages/agent-core/src/agent/compaction/micro.ts
    • packages/agent-core/src/agent/compaction/full.ts
    • packages/agent-core/src/agent/compaction/handoff.ts
    • packages/agent-core/src/agent/compaction/compaction-instruction.md
    • packages/agent-core/src/session/store/session-store.ts
    • packages/agent-core/src/agent/tool/index.ts
    • packages/agent-core/src/agent/permission/index.ts
    • packages/agent-core/src/agent/permission/policies/index.ts
    • packages/kaos/src/kaos.ts
    • packages/agent-core/src/profile/default/system.md
    • packages/agent-core/src/profile/default/agent.yaml
    • packages/agent-core/src/profile/default/explore.yaml
    • packages/agent-core/src/utils/render-prompt.ts
    • packages/agent-core/src/agent/injection/manager.ts
    • packages/agent-core/src/session/subagent-host.ts
    • packages/agent-core/src/agent/swarm/index.ts
    • packages/agent-core/src/tools/builtin/collaboration/agent-swarm.md
    • packages/agent-core/src/agent/goal/index.ts
    • packages/telemetry/src/types.ts
    • packages/agent-core/src/agent/records/types.ts
    • packages/kosong/src/capability.ts
    • packages/kosong/src/catalog.ts
    • apps/kimi-code/src/main.ts
    • docs/en/configuration/data-locations.md
    • docs/en/customization/hooks.md
    • docs/en/customization/skills.md
    • docs/en/guides/goals.md
    • docs/en/configuration/providers.md
    • docs/en/reference/kimi-acp.md

一手源存档（sources/）

/Users/zhao/projects/self-wiki/ai-research/sources/harness/moonshot-kimi-code/ 下保存：

  • NOTES.md（39.8KB，完整调研笔记，含逐维度发现与精确行号引用）
  • key-files/AGENTS.md（根架构地图）
  • key-files/services-AGENTS.md（DI service 层约定）
  • key-files/capability.ts（kosong ModelCapability）
  • key-files/records-types.ts（AgentRecordEvents 事件日志 schema）
  • key-files/kaos.ts（Kaos 执行环境接口）
  • key-files/compaction/：strategy.ts、handoff.ts、compaction-instruction.md
  • key-files/docs/：data-locations.md、goals.md、hooks.md、skills.md
  • key-files/loop/：README.md、run-turn.ts、turn-step.ts、tool-scheduler.ts
  • key-files/permission/：index.ts、policies-index.ts
  • key-files/profile/：agent.yaml、explore.yaml、system.md
  • key-files/tool/tool-manager.ts
  • key-files/agent-tools-md/agent-swarm.md

关系图谱

反向链接