Kimi Debug Tunnel is a multi-session orchestration server for Kimi Code CLI, providing 28 MCP tools and a REST/WebSocket API to manage AI sessions from a Project Manager perspective.
Session Management
Create sessions with configurable working directory, model, permission policy, thinking level, and memory injection
List, inspect, and check tunnel/connection status of all sessions
Task Execution & Communication
Send prompts with fire-and-return semantics, auto-mode, and thinking control
Run multi-step flows (auto-create session + sequential steps) and execute adaptive workflow templates
Handle paused workflows with retry, skip, abort, or manual override decisions
Real-time Monitoring & Logging
Poll session state (active/awaiting/done/error/idle) via WebSocket cache
List I/O records (user prompts + assistant replies, filtering tool noise)
Read full conversation logs with pagination, incremental updates, and thinking content toggle
Background-watch sessions for passive completion tracking; chain watch cycles to auto-submit next instructions; write results to file
Shared Memory System (3-layer)
Write/read/list/delete key-value memory entries across namespaces with auto-versioning
L1 project knowledge → L2 session context → L3 learned patterns
Archive session findings to promote L2 learnings to L1 project knowledge
View memory status (entry count, namespace distribution, last update)
Workflow Templates
Learn reusable YAML workflow templates from natural language descriptions or historical session I/O
List available templates with name, version, and step count
Permission Policy Management
Enforce built-in (read-only, safe-edit, full-access) or custom YAML policies
Approve or deny blocked tool calls at runtime (once or session scope)
Real-time Push & Debug
Stream responses to connected WebSocket debug clients
Web dashboard and REST endpoints for session health monitoring and attention alerts
Robust WireClient with heartbeat detection and automatic reconnection
Provides a Tampermonkey userscript for interacting with the orchestrator server from the browser.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kimi-debug-tunnel execute prompt: write a Python hello world"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Kimi Code CLI 的 Loop Engineering PM 编排系统。 16 核心 + 14 可选 MCP 工具（可选组按部署开关，见 可选工具部署）——不手动 prompt Agent，而是设计自动 prompt Agent 的循环系统。
问题 | 方案 |
上下文腐化 — session 越跑越笨，偏离规范 |
|
无法确认完工 — Agent 说"好了"但实际没好 |
|
冷启动灾难 — 每次新 session 从零开始 |
|
重复告知规范 — Agent 不记得项目约定 |
|
超时截断 — 耗时任务被 MCP 30s 超时杀死 | 即发即返 + Bash 后台 Python 轮询（v2.16 首次调用自动写入 poll.py → 后续短命令引用 + poll-result-{sid}.txt），OS 进程退出自动通知 |
痛点 | 行业现状 | 本项目 |
上下文不可见 | 浏览器端无任何指示 |
|
会话交接繁琐 | 手写总结，容易遗漏 |
|
多 Agent 编排 | 缺编排层，状态不可见 |
|
跨项目知识不共享 | 项目级记忆绑定单仓库 |
|
服务端崩溃 | 任务丢失，需手动重做 | 五层离线防御 + |
Related MCP server: Kimi MCP Server
git clone https://github.com/FirenzeClaw/kimi-session-orchestrator.git
cd kimi-session-orchestrator
# 0. 确认 Python ≥ 3.7（后台轮询依赖）
python3 --version || python --version
npm install && npm run build
# 1. 启动 Kimi Server（v2.24 起隧道启动时会自动激活，此步可跳过）
kimi web --no-open
# 2. 设置 token 并启动 Tunnel
export KIMI_SERVER_TOKEN="<printed-at-startup>"
npm start注册到 ~/.kimi-code/mcp.json：
{
"mcpServers": {
"kimi-session-orchestrator": {
"command": "node",
"args": ["<绝对路径>/dist/index.js"],
"env": { "KIMI_SERVER_TOKEN": "<token>" }
}
}
}/reload 即可使用。详见 完整安装指南。
用户 ──HTTP/WS──▶ Express Server ──REST──▶ Kimi Server
│ │
┌─────────────┼──────────────┐ │
▼ ▼ ▼ │
WorkflowEngine SessionWatcher PolicyEngine │
MemoryStore(SQLite) MessageQueue OrchestrationStore
│
MCP stdio ──▶ Kimi Code CLI类别 | 工具 |
Session |
|
任务 |
|
监控 |
|
模型 |
|
记忆 |
|
验证 |
|
权限 |
|
工作流 |
|
推送 |
|
* = 可选工具（默认注册，KIMI_TUNNEL_OPTIONAL_TOOLS=core 时关闭，见下方章节）
完整工具参数见 API.md。
10 个配套 skill，分为 Agent 级（新 session 自动加载）和 PM 级（按需调用）：
Skill | 级别 | 一句话 |
| Agent | 启动协议：auto 检测 → Q1 角色维度 → 按需加载 guide |
| PM |
|
| PM | 从 SPEC/PRD/PLAN/TASK 提取 AC、复杂度和 Loop Contract |
| PM | 一句话需求 → 5 轮追问 → 基线锁定 → Loop Contract |
| PM | 定时自动化编排：cron.yaml 双写、自举续期链、run_lock 防重叠 |
| PM | 退役→接班全自动 pipeline，近乎无损接力 |
| Agent | 困境分析——task session 独立上下文 + 零污染 |
| Agent | 本地子 Agent 困境分析（原版） |
| Agent | 无需 API 认证，wire.jsonl 尾部状态推断 |
| Agent | MCP 异步工具设计模式——解决 >30s 超时 |
安装：
# Agent 级
cp -r skills/kimi-session-orchestrator ~/.agents/skills/
cp -r skills/xmind-orchestrated ~/.agents/skills/
cp -r skills/xmind ~/.agents/skills/
cp skills/agent-session-monitor.md ~/.agents/skills/agent-session-monitor/SKILL.md
cp skills/mcp-async-tool.md ~/.agents/skills/mcp-async-tool/SKILL.md
# PM 级
cp -r skills/session-retire ~/.kimi-code/skills/
cp -r skills/loop-orchestrator ~/.kimi-code/skills/
cp -r skills/loop-contract-from-docs ~/.kimi-code/skills/
cp -r skills/loop-contract-from-idea ~/.kimi-code/skills/
cp -r skills/cron-scheduler ~/.kimi-code/skills/三层架构——PM 一次性录入，session 自动继承。
L1: 项目知识库 (.kimi-tunnel/memory.db)
PM: memory_set(ns, key, value)
Session: create_session(memory_level) → 自动注入索引 → 自主 memory_get
L2: Session 上下文 (session:<id>/*)
运行时更新，退役后 memory_archive 归档到 L1
L3: 学习沉淀 (learn skill → 向量库)
从 L1+L2 提取可复用模式v2.13+：支持跨项目双层注入——buildInjection() 按 profile.cwd 自动生成全局正文 + 子项目索引导航表。
文档 | 说明 |
Kimi Server API 0.27.0 实测版（v1 REST + v1/v2 WS，含 11 项破坏性变更清单；0.31.1 busy 漂移增量实测见 §五） | |
PM 统筹准入规范 | |
Loop Engineering 概念与项目对照 | |
Loop Engineering 全面参考（16 章，7 篇来源聚合） | |
7 个功能规格（001-007，含 cross-model grader 与 cron-scheduler） | |
架构设计文档（含 Loop Contract 双 Skill 设计） | |
已修复问题记录（7 个，含 0.27 Web 引擎适配与 0.31.1 busy 漂移全记录） |
方向 | 现状 | 价值 |
v2 channel RPC 迁移 | 0.24+ 引擎的 37 个 channel 已可自省（ |
|
|
| 目标模式编排的原生化 |
单 prompt 多 | 观察项，当前无症状 | watch 输出在该场景可能截断 |
Node.js ≥ 22（node:sqlite 内置 + tsc 编译）
Python ≥ 3.7（后台轮询脚本 poll_command 运行时依赖）
Kimi Code CLI ≥ 0.22.3（0.24+/0.27 新 Web 引擎自 v2.17 起适配；0.31.1 busy 语义漂移自 v2.21 起适配，见 API.md §五）
Git Bash（Windows）或 bash
变量 | 必需 | 默认 | 说明 |
| ✅ | — | Kimi Server 启动时打印的 Bearer Token |
| 否 | 自动检测 | 覆盖 Kimi Server 地址（端口自动从 lock 检测） |
| 否 |
| Tunnel HTTP/WS 监听端口 |
| 否 |
| Kimi Code 数据目录 |
| 否 |
| 可选工具开关： |
v2.23 起，14 个低使用率工具（使用率统计 0 次）拆为可选组，默认随 MCP server 注册；设 KIMI_TUNNEL_OPTIONAL_TOOLS=core 可整体关闭，仅保留 16 个核心工具（session 生命周期 + 监控 + 记忆 + 验证 + 模型）。
类别 | 可选工具 | 说明 |
审批流 |
| manual session + 策略审批路径（需配合 policy 使用） |
工作流引擎 |
| 模板驱动多步编排（实际使用走 execute_prompt + 后台轮询路线） |
watch 族 |
| MCP 内部轻量监听（备选方案） |
推送 |
| WS 外部调试客户端推送 |
启用/禁用（~/.kimi-code/mcp.json 的 env）：
{
"mcpServers": {
"kimi-session-orchestrator": {
"command": "node",
"args": ["<绝对路径>/dist/index.js"],
"env": {
"KIMI_SERVER_TOKEN": "<token>",
"KIMI_TUNNEL_OPTIONAL_TOOLS": "core"
}
}
}
}修改后 /reload 生效。源码保留在 src/tools/（可选 ≠ 删除），需要时改回 all 即可。协议级验证：core 模式注册 16 个、默认 30 个。
# | 规则 |
1 | ⛔ 不要硬编码 |
2 |
|
3 | 安装后执行 |
4 | 更新代码后需重装 skill： |
与上方完全一致，仅路径用绝对路径。自动端口检测、MCP stdio、跨平台 API 均兼容。
src/ — TypeScript 核心（index, mcp-server, wire-client, workflow-engine, memory-store 等）
tools/ — 16 核心 + 14 可选 MCP 工具（可选组开关见「可选工具部署」）
shared/ — 浏览器端 JS（API 客户端、状态管理、渲染、注入）
ext/ — Chrome MV3 扩展
userscript/ — Tampermonkey 用户脚本
skills/ — 10 个配套 Skill（含 Loop Contract 双 Skill + cron-scheduler）
templates/ — 工作流 YAML 模板
docs/ — 规格、设计文档、问题记录
specs/ — 功能规格（001-005）最常见根因：mcp.json 中硬编码了 KIMI_SERVER_URL。删除该行——Tunnel 自动从 lock 文件检测端口。确认 kimi web 运行中 + token 正确。
确保 ~/.kimi-code/mcp.json 中注册了 kimi-session-orchestrator，然后 /reload。全局 mcp.json 对所有 session 生效——配置一次即可。
Tunnel 内置五层防御：过期 lock 清理 + 10s 心跳 + 断连判定 + 指数退避重连 + WS 独立重连。短时中断自动恢复，运行中的 task session 不受影响。
kimi web 未运行或已崩溃。v2.9.1 起 MCP stdio 优先启动，wire 离线时工具返回友好报错而非进程崩溃。
端口 3456 被 WSL2 绑定的 winnat 驱动划入动态排除范围。验证：
netsh int ipv4 show excludedportrange protocol=tcp | findstr 3456如果有 3430-3529 输出说明命中。修复（管理员终端）：
net stop winnat
netsh int ipv4 add excludedportrange protocol=tcp startport=54000 numberofports=100
net start winnat原理：为 winnat 固定预留 54000-54099，释放随机占用的 3430-3529。WSL2 网络短暂中断（3-5 秒），数据和进程不受影响。
Bug / 功能请求 · Fork → PR · 提交前 npm run build 零错误。
MIT
放行被策略阻断的工具调用（仅 PM 使用）。scope=once 仅放行本次调用，scope=session 将工具加入 session 临时白名单。
Inputs: scope, block_id, session_id, approval_id.
向指定 session 发送任务（即发即返）。用 poll_session 跟踪进度。
Inputs: task (required), session_id (required), policy, auto_mode, +1 more.
检查后台监听结果。若任务 session 已完成，自动提交下一步指令并启动新一轮后台监听，形成完整自动化循环。
Inputs: watch_id (required), next_instruction.
对暂停的工作流执行决策：重试当前步骤、跳过、终止、或用自定义指令覆盖。用于处理工作流执行中遇到的阻塞。
Inputs: decision (required), execution_id (required), instruction.
创建新的 Kimi Code session。可指定工作目录和权限模式（auto/manual/yolo）。
Inputs: cwd (required), model, title, policy, +4 more.
拒绝被策略阻断或待审批的工具调用（仅 PM 使用）
Inputs: block_id, session_id, approval_id.
向目标 session 发送 prompt 并等待完整回复。通过 Kimi Server REST API 直接通信。默认排除思考链内容以节省 token。若回复模糊，可设置 include_thinking 获取思考内容确认意图。
Inputs: prompt (required), session_id (required), wait, policy, +4 more.
执行工作流模板：加载模板，创建任务 session，逐步下发指令，自适应调整，阻塞时暂停等待决策。
Inputs: template_name (required), cwd, model, policy, +4 more.
获取指定 session 的详细信息，包括标题、工作目录、创建/更新时间、agent 列表和最后一条 prompt。
Inputs: session_id (required).
获取调试隧道当前状态：已连接客户端数、Wire 协议连接状态、消息队列长度、运行时间。
Inputs: no named parameters.
获取 watch_session 的后台监听结果。返回 null 表示仍在等待中。
Inputs: watch_id (required).
对 task session 的产出进行 LLM 自动评分验证。返回 pass/fail 及详细反馈。grader 是筛子非裁判——pass 不代表完美，fail 也不一定是真问题。
Inputs: criteria (required), session_id (required), focus.
从口头描述或历史 session 中学习工作流，生成可复用的 YAML 模板。
Inputs: cwd (required), name (required), steps, spec_docs, +2 more.
快速列出 session 的输入输出记录。仅提取用户 prompt 和助手文本回复，过滤所有 tool_call/thinking/step_end 噪音。用于快速了解对话流程。
Inputs: session_id (required), limit, max_content_length.
列出所有可用的权限策略。包括内置策略（read-only/safe-edit/full-access）和项目 .kimi-tunnel/policies/ 下的自定义策略文件。每个策略附带验证状态。
Inputs: no named parameters.
列出所有 Kimi Code CLI session。返回 session ID、标题、创建/更新时间、工作目录和 agent 数量。按更新时间倒序排列。
Inputs: limit.
列出所有可用的工作流模板。返回模板名称、版本、步骤数、描述。
Inputs: no named parameters.
将指定 session 的 L2 findings 归档为 L1 learnings。PM 审查后调用。
Inputs: session_id (required), keys, project, target_namespace.
删除指定键。仅 PM 或写入者有权删除。
Inputs: key (required), namespace (required), project.
读取指定命名空间下的条目。不指定 key 则返回全部条目。支持过滤已过期条目。
Inputs: namespace (required), key, project, include_expired.
列出指定命名空间下所有键名，不含值体。支持前缀匹配快速浏览。省略参数列出所有命名空间。
Inputs: project, namespace.
写入一条键值对到指定命名空间，自动记录写入时间和来源 session。若 key 已存在则覆盖（upsert），version 递增。
Inputs: key (required), value (required), namespace (required), expire, +2 more.
查看当前项目知识库整体状态：条目数、最后更新时间、过期条目列表、各命名空间分布。
Inputs: project.
轮询 session 运行状态。返回结构化状态报告，优先使用 WebSocket 推送缓存（零 I/O）。
Inputs: session_id (required).
读取指定 session 的对话日志。返回最近的消息条目、最后一条用户 prompt、最后一条助手回复、最近调用的工具、以及当前 turn 是否已完成。用于多轮编排时检测目标 session 的处理状态。
Inputs: session_id (required), limit, after_line, include_thinking, +1 more.
分步流程执行引擎。创建 session 后逐步提交任务，每步完成后自动提交下一步。即发即返，通过 poll_session 跟踪流程进度。
Inputs: cwd (required), steps (required), model, policy, +4 more.
设置监听结果文件路径。设置后每次 prompt.completed 时自动写入结果到该文件，统筹 session 读取即可获取任务回复。
Inputs: path (required).
将处理结果实时推送给所有连接的外部调试客户端。客户端通过 WebSocket 实时接收响应，无需轮询。
Inputs: content (required), in_reply_to.
启动后台监听任务 session 的完成状态。提交任务后调用此工具，tunnel 通过 WS 主动等待完成。完成后用 get_watch_result 获取回复。
Inputs: session_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 29 tools
Several tools have heavily overlapping purposes: execute_prompt vs chat_with_session both send prompts, and watch_session/continue_watch overlap with run_flow/execute_workflow/continue_workflow. poll_session and get_watch_result also both serve as status/result checks, making misselection likely despite the detailed descriptions.
Naming is mostly consistent snake_case verb_noun: list_*, get_*, execute_*, continue_* are clear patterns. Minor deviations like memory_set (noun-first) vs set_watch_output, and the semantically close run_flow vs execute_workflow, prevent a perfect score.
With 29 tools this exceeds the 25+ threshold that reads as too many for a focused server. While the domain spans sessions, workflows, policies, memory, and grading, the count feels bloated, especially with redundant execution/watch mechanisms.
The tool surface covers session creation and observation, workflow execution, policy decisions, memory CRUD, and result grading. Minor gaps exist—there is no explicit session deletion or template update/delete—but agents can complete core workflows without hitting dead ends.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
