Kimi Session Orchestrator

License Version Node MCP Tools Skills Loop Engineering

Kimi Code CLI 的 Loop Engineering PM 视角多 session 编排系统——不手动 prompt Agent，而是设计自动 prompt Agent 的循环系统。29 个 MCP 工具，支持 L2 验证闭环（grade_step LLM 自动评分 + loop 指纹检测）+ 自适应工作流引擎 + 三层共享内存 + 权限策略管理。

目录

• Loop Engineering
• 架构
• ⛔ Agent自动部署必读
• 快速开始
  • 前置条件
  • 安装
  • 启动
  • 环境变量
  • 注册到 Kimi Code CLI
  • Skill
  • 更新工具
• MCP 工具
  • Session 管理
  • 任务下发
  • 状态监控
  • 共享记忆
  • 工作流模板
  • 权限策略
  • 推送
• REST API
• 项目结构
• 共享记忆系统
• 权限策略系统
• 参考文档
• Linux 部署
• 常见问题 (FAQ)
• 参与贡献
• 版本历史
• License

架构

外部用户 (浏览器 / curl)
    ↕ HTTP + WebSocket (默认 3456，通过 TUNNEL_PORT 配置)
┌──────────────────────────────┐
│   kimi-session-orchestrator MCP 服务器 │
│   ├─ Express HTTP Server      │
│   ├─ WebSocket Server         │
│   ├─ WireClient (ISessionClient + IStatusClient + IPushClient) │
│   ├─ WorkflowEngine (自适应工作流)      │
│   ├─ PolicyEngine (权限策略引擎)       │
│   ├─ MemoryStore (SQLite 共享记忆)     │
│   └─ MCP stdio transport      │
└─────────────┬────────────────┘
              ↕ Bearer Token REST API
┌─────────────────────────────┐
│   Kimi Server (kimi web)    │  端口自动检测
│   POST /api/v1/sessions/... │
└─────────────────────────────┘

Loop Engineering（v2.11+）

已独立为 loop-orchestrator skill。用户 /loop-orchestrator 直接激活，不再从 kimi-session-orchestrator Q1 分叉。

详细设计见 docs/superpowers/specs/2026-07-15-loop-orchestrator-v2-design.md。

⛔ Agent自动部署必读

快速开始

前置条件

• Node.js ≥ 22（node:sqlite 内置模块要求）
• Kimi Code CLI ≥ 0.22.3
• Git Bash（Windows）或 bash（Linux/macOS）

安装

git clone https://github.com/FirenzeClaw/kimi-session-orchestrator.git
cd kimi-session-orchestrator
npm install
npm run build

启动

# 1. 启动 Kimi Server（Tunnel 自动从 ~/.kimi-code/server/lock 检测端口，无需显式指定 --port）
kimi web --no-open

# 2. 设置 token（Kimi Server 启动时打印）
export KIMI_SERVER_TOKEN="your-token-here"

# 3. 启动 Tunnel
npm start

Tunnel 启动后自动连接 Kimi Server，选择最近 session，初始化记忆库（如 .kimi-tunnel/ 存在）。

端口自动检测：Tunnel 启动时自动读取 ~/.kimi-code/server/lock 获取 Kimi Server 实际端口。不要在 mcp.json 或环境变量中硬编码 KIMI_SERVER_URL——端口每次启动可能不同，硬编码会导致连接失败。仅在自动检测异常时才显式设置。

注册到 Kimi Code CLI

在 ~/.kimi-code/mcp.json 中添加（路径按实际安装位置调整）：

{
  "mcpServers": {
    "kimi-session-orchestrator": {
      "command": "node",
      "args": ["<项目绝对路径>/dist/index.js"],
      "env": {
        "KIMI_SERVER_TOKEN": "your-token-here"
      }
    }
  }
}

注意：KIMI_SERVER_URL 无需设置——Tunnel 自动从 lock 文件检测端口。仅在需要覆盖自动检测时才显式设置。

然后 /reload 即可使用。

环境变量

Skill

本项目配套 7 个 skill，分为 Agent 级（新 session 自动加载）和 PM 级（统筹 session 按需调用）。

Skill 列表

使用场景

安装

# Agent 级 skill（新 session 自动加载）——安装到 ~/.agents/skills/
rm -rf ~/.agents/skills/kimi-session-orchestrator
cp -r skills/kimi-session-orchestrator ~/.agents/skills/kimi-session-orchestrator
rm -rf ~/.agents/skills/xmind-orchestrated
cp -r skills/xmind-orchestrated ~/.agents/skills/xmind-orchestrated
rm -rf ~/.agents/skills/xmind
cp -r skills/xmind ~/.agents/skills/xmind
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 级 skill（统筹 session 按需调用）——安装到 ~/.kimi-code/skills/
rm -rf ~/.kimi-code/skills/session-retire
cp -r skills/session-retire ~/.kimi-code/skills/session-retire

# PM 级 skill — Loop Orchestrator
rm -rf ~/.kimi-code/skills/loop-orchestrator
cp -r skills/loop-orchestrator ~/.kimi-code/skills/loop-orchestrator

新 session 加载 kimi-session-orchestrator skill 后自动触发最小启动协议——auto 检测 → Q1 角色维度 → 按需 Read 对应 guide。/reload 后生效。

更新工具

⛔ 更新前检查

更新前确认以下前置条件，避免 /reload 后 MCP 连接失败：

kimi web 未运行是最常见的更新后连接失败原因——Tunnel 启动时从 lock 文件读取端口，若 Kimi Server 不在线则报 ECONNREFUSED。详见 FAQ。

更新步骤

git pull
npm run build                              # 重新编译 TypeScript

# 更新 Agent 级 skill
rm -rf ~/.agents/skills/kimi-session-orchestrator
cp -r skills/kimi-session-orchestrator ~/.agents/skills/kimi-session-orchestrator
rm -rf ~/.agents/skills/xmind-orchestrated
cp -r skills/xmind-orchestrated ~/.agents/skills/xmind-orchestrated
rm -rf ~/.agents/skills/xmind
cp -r skills/xmind ~/.agents/skills/xmind

# 更新 PM 级 skill
rm -rf ~/.kimi-code/skills/session-retire
cp -r skills/session-retire ~/.kimi-code/skills/session-retire
rm -rf ~/.kimi-code/skills/loop-orchestrator
cp -r skills/loop-orchestrator ~/.kimi-code/skills/loop-orchestrator

使更新生效

在 Kimi Code CLI 中执行 /reload 使 MCP 工具和 skill 变更生效。

原理：/reload 会杀死旧 MCP 进程并重新启动，新进程加载更新后的 dist/index.js。仅 git pull + npm run build 不更新 skill 文件时，/reload 即可——编译输出已变更。若端口 3456 被旧孤儿进程占用，/reload 通常能清理；残留时手动 taskkill /PID <pid> 即可。

MCP 工具

Session 管理

任务下发

状态监控

共享记忆（v2.5+）

v2.6 注入策略：create_session(memory_level) 自动注入记忆索引（命名空间 + 键名 + 读取建议），task session 首 turn 自主调用 memory_get 按需拉取。注入文本从 ~600B 降至 ~200B。

工作流模板

权限策略

验证评分

推送

REST API

示例

# 端口默认 3456，也可通过 TUNNEL_PORT 设置
curl -X POST http://localhost:${TUNNEL_PORT:-3456}/api/execute \
  -H "Content-Type: application/json" \
  -d '{"prompt":"你的 prompt","timeout_ms":60000}'

智能思考过滤

• 默认：排除思考链内容，仅返回文本回复
• 自动触发：当回复含"不确定/可能/需要更多"等模糊词时，自动读取思考内容确认意图
• 手动：设置 include_thinking: true 强制包含

项目结构

src/
├── index.ts                     # 入口：DI 装配，启动 HTTP+MCP，初始化记忆库和编排追踪
├── types.ts                     # ISessionClient / IStatusClient / IPushClient / IMemoryStore / IWorkflowEngine + TunnelServices
├── mcp-server.ts                # MCP stdio 服务器（注册 29 个工具）
├── http-server.ts               # Express + WebSocket + /api/orchestrations + /api/token
├── wire-client.ts               # Kimi Server REST + WS 推送（实现 ISessionClient/IStatusClient/IPushClient）
├── message-queue.ts             # WebSocket pub/sub 广播
├── orchestration-store.ts       # PM→子 session 编排关系内存追踪
├── session-store.ts             # 文件系统扫描 + 路径解析
├── session-log-reader.ts        # wire.jsonl 日志解析 + IO 提取 + sanitizeText
├── workflow-template.ts         # 模板类型定义 + YAML 解析 + Zod 校验
├── workflow-store.ts            # 模板持久化（templates/ CRUD）
├── workflow-engine.ts           # 自适应工作流引擎
├── policy-types.ts              # 策略类型 + Zod schema + 已知工具清单
├── policy-builtins.ts           # read-only / safe-edit / full-access
├── policy-store.ts              # YAML 策略文件 CRUD
├── policy-engine.ts             # 策略解析/检查/绑定
├── memory-store.ts              # SQLite 持久化 + buildInjection() + 记忆profiles
├── server-lock.ts               # Kimi Server 端口自动检测（lock 文件解析）
├── tools/                       # 29 个 MCP 工具
│   ├── helpers.ts               # injectMemoryIntoPrompt + preparePrompt + ensureConnected + setMemoryProfileWithExpiry
│   ├── manifest.ts              # 工具注册桶文件（统一导入点）
│   ├── create-session.ts        # + 编排追踪
│   ├── run-flow.ts              # + 编排追踪
│   ├── execute-workflow.ts      # + 编排追踪
│   └── ...

shared/                          # 浏览器端共享 JS（ES2020+）
├── api.js                       # Tunnel + Kimi Server API 客户端
├── state.js                     # Session 树状态管理
├── renderer.js                  # DOM 渲染（复用页面原生样式）
├── injector.js                  # DOM 注入 + token 自动填入
└── styles.css                   # 最小注入样式

ext/                             # Chrome MV3 扩展
├── manifest.json                # content_scripts → Kimi Web UI 页面
├── content.js                   # 扩展入口
├── service-worker.js
├── options.html                 # 端口配置页
├── options.js
└── icons/

userscript/                      # Tampermonkey 用户脚本源
└── （构建输出到 dist/userscript/）

scripts/
└── build-userscript.mjs         # 共享代码内联 → .user.js

skills/                          # 配套 Skill（7 个）
├── kimi-session-orchestrator/   # Agent 级——MCP 工具使用规范
├── xmind-orchestrated/          # Agent 级——task session 隔离困境分析
├── xmind/                       # Agent 级——本地子 Agent 困境分析（保留原版）
├── session-retire/              # PM 级——退役与接班自动化 pipeline（v2.7 新增）
├── loop-orchestrator/           # PM 级——Loop Engineering 自主编排（v2.11+ 独立）
├── agent-session-monitor.md     # wire.jsonl 状态推断
└── mcp-async-tool.md            # 异步工具设计模式

v2.7 变更：src/public/console.html 和 workflow-console.html 已移除。监控 UI 迁移至浏览器扩展 + JS 脚本插件，直接注入 Kimi Web UI 侧边栏。新增 session-retire skill——退役→接班自动化 pipeline（memory_archive + 7-block 模板 + 新 session 启动自举协议）。

v2.11 变更：架构深化第2轮——IWireClient（20方法）拆分为 ISessionClient/IStatusClient/IPushClient 三个聚焦接口；消除 ambient sessionId（submitPrompt/sendPrompt/getSessionStatus 参数化，8个save/restore块删除）；apiGet/apiPost → getSessionMessages/resolveApproval 语义方法；记忆注入统一到 helpers.ts（injectMemoryIntoPrompt + setMemoryProfileWithExpiry）；移除 WorkflowEngine || 回退（workflowEngine 非可选）；tools/manifest.ts 桶文件；session-log-reader 共享 parseWireJsonl 解析流。

v2.10 变更：架构深化——WireClient 上帝类拆分，新增 IWireClient 接口 + server-lock.ts；删除 memory-injector.ts（死代码）；新增 tools/helpers.ts（preparePrompt + ensureConnected，消除 4 处重复样板）；记忆 profile 从 WireClient 移至 MemoryStore；WorkflowEngine/SessionWatcher 改用 IWireClient；workflow-store.ts 手写 toYaml → js-yaml dump；移除 /api/send 死端点。

v2.8.5 修复：buildInjection() 空守卫在 project 知识库为空时过早返回，截断 fromSession handoff 注入——session-retire 交接数据被静默丢弃。修复：handoff 提前收集 + 联合判空 + handoff-only 分支 + 去重。

v2.8 变更：buildInjection() 注入文本 memory_get("ns") → memory_get(namespace="ns")——消除工具名歧义；REST API 端点删过时补漏（移除已删除的 / 和 /workflow-console.html，补充 /api/orchestrations、/api/token）；新增"更新工具"章节；全文档过时内容清理。

共享记忆系统（v2.5+）

┌─────────────────────────────────────────────────┐
│ L1: 项目知识库 (.kimi-tunnel/memory.db)          │
│ PM 一次性录入 → task session 启动时自动注入索引    │
│ project/meta / decisions / risks / learnings    │
├─────────────────────────────────────────────────┤
│ L2: Session 上下文 (session:<id>/*)             │
│ 创建时写入，运行时更新，退役后归档                  │
├─────────────────────────────────────────────────┤
│ L3: 学习沉淀 (learn skill → 向量库)              │
│ 从 L1+L2 提取可复用模式                          │
└─────────────────────────────────────────────────┘

PM 操作:                            Task session 首 turn:
  memory_set(ns, key, value)         → 收到索引 → memory_get(namespace=ns)
  create_session(memory_level=full)  → 评估关联 → 拉取条目 → 执行任务
  execute_prompt(task)               → 同一 turn 完成上下文建立 + 工作

权限策略系统（v2.4+）

• 三层架构：Session 级策略（create_session permission_mode）+ 任务级策略（policy 参数）+ 工具级回调（Bash 检测 awaiting_approval → PM 手动 approve_tool / deny_tool）。已移除 approveAll 自动裁决，改为 PM 决策闭环。
• 3 内置策略：read-only（只读）/ safe-edit（安全编辑，禁 shell 命令）/ full-access（全部允许）
• 自定义 YAML：.kimi-tunnel/policies/<name>.yaml
• PM Dashboard：实时阻断事件面板，支持 approve/deny（once/session scope）

参考文档

Linux 部署

前置条件、安装、启动、MCP 注册、Skill 安装与上方 快速开始 完全一致。以下仅补充 Linux 特有的注意事项。

注册 MCP（Linux 路径示例）

mkdir -p ~/.kimi-code

cat > ~/.kimi-code/mcp.json << 'EOF'
{
  "mcpServers": {
    "kimi-session-orchestrator": {
      "command": "node",
      "args": ["/home/user/kimi-session-orchestrator/dist/index.js"],
      "env": {
        "KIMI_SERVER_TOKEN": "<token>"
      }
    }
  }
}
EOF

args 中的路径需为绝对路径，按实际 clone 位置调整。/reload 后生效。

构建兼容性

项目 package.json 的 build 脚本使用 cp -r，兼容 Linux。

平台兼容性

常见问题 (FAQ)

rm -rf ~/.agents/skills/kimi-session-orchestrator
cp -r skills/kimi-session-orchestrator ~/.agents/skills/kimi-session-orchestrator
rm -rf ~/.agents/skills/xmind-orchestrated
cp -r skills/xmind-orchestrated ~/.agents/skills/xmind-orchestrated

export TUNNEL_PORT=3457
npm start

参与贡献

• Bug 报告 / 功能请求：GitHub Issues
• 代码贡献：Fork → Feature Branch → Pull Request。提交前确保 npm run build 零错误。
• 文档规范：参考 docs/coordinator-guide.md 了解项目约定。

版本历史

License

MIT