Skip to content

[native] kimi: three-mode alignment (proxy / launcher / native plugin) + runtime-info #963

Closed

Description

@ranxianglei

Goal

Bring kimi to full three-mode alignment like pi / opencode / dsh already have:

  1. Mode 1 — proxy (URL prefix, exists today via launcher)
  2. Mode 2 — launcher (bili kimi — exists)
  3. Mode 3 — native plugin (bili plugin install kimi — the gap): plugin loaded by the CLIENT itself, spawns/attaches its own proxy, rewrites model traffic, registers ACP tools natively, stamps plugin-mode headers, implements the runtime-info protocol.

Feasibility pre-assessment

UNKNOWN — research first: plugin/extension surface (config rewrite, request headers, native tool registration)? Follow the dsh playbook if yes.

Reference implementations (read these first)

Requirements if feasible

  • No launcher, no env vars, no fixed port for the end user; opt-out env BILI_NATIVE_KIMI=0
  • Plugin-mode gating: stamp x-bili-plugin ONLY after native tools are registered (round 1 rides wire mode)
  • Parent-pid watchdog proxy teardown; attach to a healthy proxy when present
  • Runtime-info stamps (model + contextWindow + maxOutput whenever the client exposes them)
  • npm run typecheck + npm test + npm run build green; new tests for the plugin module (see tests/dsh-native.test.ts for the harness style)
  • README (en + zh) client table + install section updated

If NOT feasible

Post the evidence (what extension points exist, why wire interception / native tools are impossible) and close as wontfix — a documented no is a deliverable too.

For ework

This issue is directly implementable. Follow the dsh playbook; ask in this thread before inventing new protocol surface. PR must reference this issue (Fixes #N).

Activity

  1. ranxianglei commented on Sep 18, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 Picking up #963. Plan: research Kimi Code's extension surface first (feasibility gate), then follow the dsh-native playbook if there's a viable seam.

    Initial facts gathered:

    • @moonshot-ai/kimi-code latest = 2.0.1 (published today), bin kimi → dist/main.mjs — a Node ≥22 ESM bundle with only ws + qrcode as deps, so it's a JS process we can inspect/patch, not a closed binary like trae.
    • Current kimi launcher (支持kimi code #757) rides cert-MITM via proxy envs; loopback endpoints have no rewrite channel. No native plugin lane today (src/plugin-install.ts only knows pi/opencode/dsh).

    Installing the package locally now to probe for plugin/extension hooks (config rewrite, request headers, native tool registration, session id surface). Will report feasibility with evidence either way.

  2. ranxianglei commented on Sep 18, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 Feasibility research done — Mode 3 is feasible, with adaptations forced by Kimi's extension surface. Evidence from official docs + public source (MoonshotAI/kimi-code, v2 engine packages/agent-core-v2), verified against npm latest 2.0.1.

    What Kimi Code 2.x exposes (and what it doesn't)

    • ❌ No in-process JS extension point. Plugin manifests explicitly reject tools / apps / inject / configFile fields ("not part of the plugin runtime"). There is no fetch-patch seam like dsh/opencode/pi natives have — so the dsh playbook cannot be followed literally, and no globalThis.fetch interception is possible.
    • ✅ MCP stdio servers declared by plugins — spawned per session as children of the kimi main process (lease-tracked, killed when the session ends); env is parent env + per-server env + injected KIMI_CODE_HOME + KIMI_PLUGIN_ROOT; command: "node" even works on single-binary installs (built-in Node fallback via __plugin_run_node). Tools appear as mcp__<server>__<tool>.
    • ✅ Hooks (SessionStart, SessionHeartbeat, …) — external commands run with cwd = plugin root, same env injection; SessionStart payload carries session_id + model; fail-open design.
    • ✅ config.toml [providers.<name>] supports base_url plus custom_headers (a static string table "attached to each request"), and the whole file hot-reloads: chokidar watch → debounced re-parse → provider diff event → catalog invalidation → the next request re-resolves base_url/headers mid-session. I traced this end-to-end in source (configService.reload() → kosongConfigService.onConfigSectionChanged → providerService.loadAll → catalog-runtime.markDirty + cache invalidation → buildModel), so ephemeral ports work without any fixed port.
    • Native auto-compaction exists but cannot be disabled, only threshold-tuned via [loop_control] compaction_trigger_ratio (0.5–0.99) / reserved_context_size.

    Proposed design (dsh playbook, adapted)

    1. bili plugin install kimi writes a managed plugin into ~/.kimi-code/plugins/managed/billion-context/ + appends the installed.json record (same store format kimi itself uses). It bundles two small scripts + declares them: an MCP stdio server and a SessionStart hook. No launcher, no env vars, no fixed port for the end user; opt-out BILI_NATIVE_KIMI=0.
    2. Bootstrap (blocking SessionStart hook): attach to a healthy proxy or spawn one (ensureProxyRunning({ port: 0 })), then a parse-guarded read-modify-write of config.toml rewrites the active provider's base_url to http://127.0.0.1:<actual-port>/bili/<upstream> (original file snapshotted to .bili-bak first). Hot-reload applies routing to the live session; round 1 rides wire mode because the plugin header isn't stamped yet.
    3. Native ACP tools: the MCP server registers compress / decompress / search_context / acp_status (surfaced as mcp__bili__*, pre-allowed via a [[permission.rules]] entry). Only after registration does bootstrap write custom_headers { x-bili-plugin = "kimi" } into the same provider — satisfying the "stamp only after tools are ready" gate.
    4. Runtime-info: bootstrap POSTs /__bili/plugin/runtime-info with the model name (from the SessionStart payload) + contextWindow/maxOutput from [models.<alias>] max_context_size / max_output_size.
    5. Watchdog: the MCP child dies when kimi exits → spawned-proxy teardown (parent-pid watchdog, same as dsh); SessionHeartbeat health-checks the proxy and, on death, restores the original base_url from .bili-bak so traffic degrades to direct instead of failing, then retries respawn+rewrite. Self-healing.
    6. Version floor: requires Kimi Code ≥ 2.0.0 (detected via kimi --version); older installs stay on launcher mode with a notice. Tests follow the tests/dsh-native.test.ts harness style; README en+zh updated.

    Deviations from the dsh playbook — asking before implementing

    None of these invent new proxy-side protocol surface (the #955 runtime-info contract is used exactly as documented); they're client-side adaptations dictated by what Kimi allows:

    1. Routing via a config.toml managed edit instead of dynamic service injection — Kimi has no overlay-file mechanism (one user-level config file). The client-side helper does a parse-guarded RMW: rejects malformed TOML loudly, never drops unknown keys, keeps a .bili-bak snapshot. OK?
    2. Plugin-mode stamping via a dynamic custom_headers write (not per-request header code, since headers are a static table) — same guarded RMW, written only after tool registration.
    3. Compaction push-out, not hard-disable — we set compaction_trigger_ratio = 0.99 + reserved_context_size = 0 so ACP compression wins in practice and native compaction becomes a ~99%-window backstop. Acceptable?
    4. No per-request conversation-id header — static headers can't carry x-bili-plugin-conversation, so session binding falls back to the derived id (first-message hash), same as pi today; sub-agent conversations get their own proxy sessions (known limitation).

    My recommendation: proceed with all four as stated — they're the minimal viable shape given Kimi's surface, and each degrades safely. Object to any point (or say go) and I'll implement, test, and open the PR referencing #963.


    中文摘要:可行性确认——Kimi Code 2.x 没有进程内插件运行时(无法像 dsh 那样 patch fetch),但有插件声明的 MCP stdio server、hooks、以及支持热重载的 config.toml(base_url / custom_headers);方案为 config.toml 托管改写路由 + MCP 原生工具 + 工具注册后再打 plugin 头,共四处对 dsh playbook 的适配(见上),等你拍板后开工。

  3. ranxianglei commented on Sep 19, 2026

    @ranxianglei
    OwnerAuthor

    调研已完成且结论可行——按你调研里适配后的方案开工实现,出 PR 引用 Fixes #963。

  4. ranxianglei commented on Sep 19, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 收到——按适配后方案开工(四处适配全部照做)。计划:bili plugin install kimi 写入托管插件(MCP stdio server 注册原生 ACP 工具 + SessionStart bootstrap hook),bootstrap 负责 spawn/attach 代理并改写 config.toml 路由,MCP 侧在工具就绪后打 x-bili-plugin 头,runtime-info 按 #955 契约上报。实现中,完成后出 PR(Fixes #963)并在本线程汇报。

  5. ranxianglei commented on Sep 19, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 完成 — PR: #982 (Fixes #963)

    kimi 三模式对齐已实现,按你在楼里拍板的适配方案(dsh playbook 的声明式变体):

    • Mode 3 native plugin:bili plugin install kimi 写 $KIMI_CODE_HOME/plugins/managed/billion-context/kimi.plugin.json(stdio MCP server + SessionStart hook,绝对路径指向 live package dist)+ installed.json 记录;版本门槛 kimi --version ≥ 2.0.0,低于则拒绝安装(启动器模式不受影响)。
    • 每会话自举:MCP 子进程(kimi 直接 spawn)attach BILLION_CONTEXT_PROXY 或临时端口自拉起 → 幂等逐行受管块改写 ~/.kimi-code/config.toml(自有 [providers.bili] 原样克隆当前 provider 的 oauth/api_key 引用、[models.bili-kimi] 别名、default_model 重定向且原值记录在块内;首改前快照 .bili-bak;mkdir 锁文件;kimi 热重载对存活会话生效)。
    • 盖章纪律:custom_headers x-bili-plugin=kimi 仅在 ACP 工具清单经存活代理 manifest 验证后写入(第一轮走 wire 模式);静态头无法承载逐请求窗口/模型值(模型切换会过期),故 runtime-info 仅自举时上报([native] runtime-info protocol: plugins report real model config (model / contextWindow / maxOutput) to the proxy #955 协议,README 已注明此偏差)。
    • 看门狗:30s 探测;attach 模式永等不动用户代理;spawn 模式死亡则重新拉起并改写路由到新 origin;恢复失败移除受管块退回直连(绝不指向死端口)。会话结束 kimi 杀 MCP 子进程 → parent-pid 看门狗收掉代理。多 TUI 共享首个代理,死亡后自动自愈。
    • 退出开关 BILI_NATIVE_KIMI=0;子代理会话各自派生独立会话(per-call conversation_id 绑定,feat: per-call conversation_id for MCP tools — let the model supply its session id #760 通道)——kimi 不暴露稳定会话 id,已作为已知局限写入 README。

    测试:tests/kimi-native.test.ts 20 个用例(plan 优先级、TOML 往返含幂等+用户改动保留、假 home 安装器、真代理集成含 runtime-info 捕获)。测试揪出两个真实 bug 并已修:①重复自举会把记录的 default_model 降级成别名(卸载后用户卡在别名上);②健康探测把新代理首请求前的 404 当成不健康。

    Pre-flight:npm run typecheck ✓ / npm test ✓(1919 pass, 0 fail, 2 skipped gated e2e)/ npm run build ✓(dist/kimi/native-mcp.js + dist/kimi/bootstrap-hook.js 就位)。README en+zh 已同步更新(客户端表、Option 1、runtime-info 实现列表、新增 "Kimi Code" 小节)。

    中文一句话:kimi 原生插件模式(config.toml 受管块路由 + stdio MCP 壳 + SessionStart hook,替代不可行的 fetch 补丁)已按批准方案落地并通过全量门禁,可以合并。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions