feat(cli): add info command and modularize cli (#563)

stdrc · web-flow · commit dd28e5f6018a · 2026-01-01T20:56:04.000+08:00
Signed-off-by: Richard Chien &lt;stdrc@outlook.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,7 @@ Only write entries that are worth mentioning to users.
 - ACP: Route file reads/writes and shell commands through ACP clients for synced edits/output
 - Shell: Add `/model` slash command to switch default models and reload when using the default config
 - Skills: Add `/skill:<name>` slash commands to load `SKILL.md` instructions on demand
+- CLI: Add `kimi info` subcommand for version/protocol details (supports `--json`)
 - CLI: Add `kimi term` to launch the Toad terminal UI
 - Python: Bump the default tooling/CI version to 3.14
 
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -71,9 +71,10 @@ export default defineConfig({
               text: '参考手册',
               items: [
                 { text: 'kimi 命令', link: '/zh/reference/kimi-command' },
-                { text: 'kimi acp 命令', link: '/zh/reference/kimi-acp' },
+                { text: 'kimi info 子命令', link: '/zh/reference/kimi-info' },
+                { text: 'kimi acp 子命令', link: '/zh/reference/kimi-acp' },
                 { text: 'kimi mcp 子命令', link: '/zh/reference/kimi-mcp' },
-                { text: 'kimi term 命令', link: '/zh/reference/kimi-term' },
+                { text: 'kimi term 子命令', link: '/zh/reference/kimi-term' },
                 { text: '斜杠命令', link: '/zh/reference/slash-commands' },
                 { text: '键盘快捷键', link: '/zh/reference/keyboard' },
               ],
@@ -149,9 +150,10 @@ export default defineConfig({
               text: 'Reference',
               items: [
                 { text: 'kimi Command', link: '/en/reference/kimi-command' },
-                { text: 'kimi acp Command', link: '/en/reference/kimi-acp' },
-                { text: 'kimi mcp Subcommands', link: '/en/reference/kimi-mcp' },
-                { text: 'kimi term Command', link: '/en/reference/kimi-term' },
+                { text: 'kimi info Subcommand', link: '/en/reference/kimi-info' },
+                { text: 'kimi acp Subcommand', link: '/en/reference/kimi-acp' },
+                { text: 'kimi mcp Subcommand', link: '/en/reference/kimi-mcp' },
+                { text: 'kimi term Subcommand', link: '/en/reference/kimi-term' },
                 { text: 'Slash Commands', link: '/en/reference/slash-commands' },
                 { text: 'Keyboard Shortcuts', link: '/en/reference/keyboard' },
               ],
diff --git a/docs/en/reference/kimi-acp.md b/docs/en/reference/kimi-acp.md
@@ -1,4 +1,4 @@
-# `kimi acp` Command
+# `kimi acp` Subcommand
 
 The `kimi acp` command starts a multi-session ACP (Agent Client Protocol) server.
 
diff --git a/docs/en/reference/kimi-command.md b/docs/en/reference/kimi-command.md
@@ -125,3 +125,11 @@ Thinking mode requires model support. If not specified, uses the last session's
 | `--skills-dir PATH` | Specify skills directory (default `~/.kimi/skills`) |
 
 See [Agent Skills](../customization/skills.md) for details.
+
+## Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| [`kimi info`](./kimi-info.md) | Display version and protocol information |
+| [`kimi acp`](./kimi-acp.md) | Start multi-session ACP server |
+| [`kimi mcp`](./kimi-mcp.md) | Manage MCP server configuration |
diff --git a/docs/en/reference/kimi-info.md b/docs/en/reference/kimi-info.md
@@ -0,0 +1,41 @@
+# `kimi info` Subcommand
+
+`kimi info` displays version and protocol information for Kimi CLI.
+
+```sh
+kimi info [--json]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output in JSON format |
+
+## Output
+
+| Field | Description |
+|-------|-------------|
+| `kimi_cli_version` | Kimi CLI version number |
+| `agent_spec_versions` | List of supported agent spec versions |
+| `wire_protocol_version` | Wire protocol version |
+| `python_version` | Python runtime version |
+
+## Examples
+
+**Text output**
+
+```sh
+$ kimi info
+kimi-cli version: 0.70
+agent spec versions: 1
+wire protocol: 1
+python version: 3.13.1
+```
+
+**JSON output**
+
+```sh
+$ kimi info --json
+{"kimi_cli_version": "0.70", "agent_spec_versions": ["1"], "wire_protocol_version": "1", "python_version": "3.13.1"}
+```
diff --git a/docs/en/reference/kimi-mcp.md b/docs/en/reference/kimi-mcp.md
@@ -1,4 +1,4 @@
-# `kimi mcp` Subcommands
+# `kimi mcp` Subcommand
 
 `kimi mcp` is used to manage MCP (Model Context Protocol) server configurations. For concepts and usage of MCP, see [Model Context Protocol](../customization/mcp.md).
 
diff --git a/docs/en/reference/kimi-term.md b/docs/en/reference/kimi-term.md
@@ -1,4 +1,4 @@
-# `kimi term` command
+# `kimi term` Subcommand
 
 The `kimi term` command launches the [Toad](https://github.com/batrachianai/toad) terminal UI, a modern terminal interface built with [Textual](https://textual.textualize.io/).
 
diff --git a/docs/en/release-notes/changelog.md b/docs/en/release-notes/changelog.md
@@ -7,6 +7,7 @@ This page documents the changes in each Kimi CLI release.
 - ACP: Route file reads/writes and shell commands through ACP clients for synced edits/output
 - Shell: Add `/model` slash command to switch default models and reload when using the default config
 - Skills: Add `/skill:<name>` slash commands to load `SKILL.md` instructions on demand
+- CLI: Add `kimi info` subcommand for version/protocol details (supports `--json`)
 - CLI: Add `kimi term` to launch the Toad terminal UI
 - Python: Bump the default tooling/CI version to 3.14
 
diff --git a/docs/zh/reference/kimi-acp.md b/docs/zh/reference/kimi-acp.md
@@ -1,4 +1,4 @@
-# `kimi acp` 命令
+# `kimi acp` 子命令
 
 `kimi acp` 命令启动一个支持多会话的 ACP (Agent Client Protocol) 服务器。
 
diff --git a/docs/zh/reference/kimi-command.md b/docs/zh/reference/kimi-command.md
@@ -125,3 +125,11 @@ Thinking 模式需要模型支持。如果不指定，使用上次会话的设
 | `--skills-dir PATH` | 指定 skills 目录（默认 `~/.kimi/skills`） |
 
 详见 [Agent Skills](../customization/skills.md)。
+
+## 子命令
+
+| 子命令 | 说明 |
+|--------|------|
+| [`kimi info`](./kimi-info.md) | 显示版本和协议信息 |
+| [`kimi acp`](./kimi-acp.md) | 启动多会话 ACP 服务器 |
+| [`kimi mcp`](./kimi-mcp.md) | 管理 MCP 服务器配置 |
diff --git a/docs/zh/reference/kimi-info.md b/docs/zh/reference/kimi-info.md
@@ -0,0 +1,41 @@
+# `kimi info` 子命令
+
+`kimi info` 显示 Kimi CLI 的版本和协议信息。
+
+```sh
+kimi info [--json]
+```
+
+## 选项
+
+| 选项 | 说明 |
+|------|------|
+| `--json` | 以 JSON 格式输出 |
+
+## 输出内容
+
+| 字段 | 说明 |
+|------|------|
+| `kimi_cli_version` | Kimi CLI 版本号 |
+| `agent_spec_versions` | 支持的 Agent 规格版本列表 |
+| `wire_protocol_version` | Wire 协议版本 |
+| `python_version` | Python 运行时版本 |
+
+## 示例
+
+**文本输出**
+
+```sh
+$ kimi info
+kimi-cli version: 0.70
+agent spec versions: 1
+wire protocol: 1
+python version: 3.13.1
+```
+
+**JSON 输出**
+
+```sh
+$ kimi info --json
+{"kimi_cli_version": "0.70", "agent_spec_versions": ["1"], "wire_protocol_version": "1", "python_version": "3.13.1"}
+```
diff --git a/docs/zh/reference/kimi-term.md b/docs/zh/reference/kimi-term.md
@@ -1,4 +1,4 @@
-# `kimi term` 命令
+# `kimi term` 子命令
 
 `kimi term` 命令启动 [Toad](https://github.com/batrachianai/toad) 终端 UI，这是一个基于 [Textual](https://textual.textualize.io/) 的现代终端界面。
 
diff --git a/docs/zh/release-notes/changelog.md b/docs/zh/release-notes/changelog.md
@@ -7,6 +7,7 @@
 - ACP：通过 ACP 客户端路由文件读写和 Shell 命令，实现同步编辑/输出
 - Shell：添加 `/model` 斜杠命令，在使用默认配置时切换默认模型并重新加载
 - Skills：添加 `/skill:<name>` 斜杠命令，按需加载 `SKILL.md` 指引
+- CLI：添加 `kimi info` 子命令，显示版本和协议信息（支持 `--json`）
 - CLI：添加 `kimi term` 命令，启动 Toad 终端 UI
 - Python：将默认工具/CI 版本升级到 3.14
 
diff --git a/kimi.spec b/kimi.spec
@@ -3,7 +3,7 @@
 from kimi_cli.utils.pyinstaller import datas, hiddenimports
 
 a = Analysis(
-    ["src/kimi_cli/cli.py"],
+    ["src/kimi_cli/cli/__main__.py"],
     pathex=[],
     binaries=[],
     datas=datas,
diff --git a/src/kimi_cli/__init__.py b/src/kimi_cli/__init__.py
@@ -1,5 +1,6 @@
 from loguru import logger
 
 # Disable logging by default for library usage.
-# Application entry points (e.g., cli.py) should call logger.enable("kimi_cli") to enable logging.
+# Application entry points (e.g., kimi_cli.cli) should call logger.enable("kimi_cli")
+# to enable logging.
 logger.disable("kimi_cli")
diff --git a/src/kimi_cli/acp/AGENTS.md b/src/kimi_cli/acp/AGENTS.md
@@ -14,7 +14,7 @@
   - Used when running CLI with `--acp` UI mode.
 - **Multi-session server**: `acp_main()` runs `ACPServer` with `use_unstable_protocol=True`.
   - Code: `src/kimi_cli/acp/__init__.py`, `src/kimi_cli/acp/server.py`.
-  - Exposed via the `kimi acp` command in `src/kimi_cli/cli.py`.
+  - Exposed via the `kimi acp` command in `src/kimi_cli/cli/__init__.py`.
 
 ## Capabilities advertised
 - `prompt_capabilities`: `embedded_context=False`, `image=True`, `audio=False`.
diff --git a/src/kimi_cli/agentspec.py b/src/kimi_cli/agentspec.py
@@ -9,6 +9,9 @@
 
 from kimi_cli.exception import AgentSpecError
 
+DEFAULT_AGENT_SPEC_VERSION = "1"
+SUPPORTED_AGENT_SPEC_VERSIONS = (DEFAULT_AGENT_SPEC_VERSION,)
+
 
 def get_agents_dir() -> Path:
     return Path(__file__).parent / "agents"
@@ -105,8 +108,8 @@ def _load_agent_spec(agent_file: Path) -> AgentSpec:
     except yaml.YAMLError as e:
         raise AgentSpecError(f"Invalid YAML in agent spec file: {e}") from e
 
-    version = data.get("version", 1)
-    if version != 1:
+    version = str(data.get("version", DEFAULT_AGENT_SPEC_VERSION))
+    if version not in SUPPORTED_AGENT_SPEC_VERSIONS:
         raise AgentSpecError(f"Unsupported agent spec version: {version}")
 
     agent_spec = AgentSpec(**data.get("agent", {}))
diff --git a/src/kimi_cli/cli/__init__.py b/src/kimi_cli/cli/__init__.py
@@ -9,7 +9,9 @@
 import typer
 
 from kimi_cli.constant import VERSION
-from kimi_cli.mcp import cli as mcp_cli
+
+from .info import cli as info_cli
+from .mcp import cli as mcp_cli
 
 
 class Reload(Exception):
@@ -267,11 +269,12 @@ def kimi(
     from kimi_cli.app import KimiCLI, enable_logging
     from kimi_cli.config import Config, load_config_from_string
     from kimi_cli.exception import ConfigError
-    from kimi_cli.mcp import get_global_mcp_config_file
     from kimi_cli.metadata import load_metadata, save_metadata
     from kimi_cli.session import Session
     from kimi_cli.utils.logging import logger
 
+    from .mcp import get_global_mcp_config_file
+
     enable_logging(debug)
 
     if session_id is not None:
@@ -491,14 +494,17 @@ async def _run(session_id: str | None) -> bool:
             continue
 
 
+cli.add_typer(info_cli, name="info")
+
+
 @cli.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
 def term(
     ctx: typer.Context,
 ) -> None:
-    """Run Toad terminal UI backed by Kimi ACP server (extra args go to `kimi --acp`)."""
-    from kimi_cli import toad as toad_cli
+    """Run Toad TUI backed by Kimi CLI ACP server (extra args go to `kimi --acp`)."""
+    from kimi_cli.toad import run_term
 
-    toad_cli.run_term(ctx)
+    run_term(ctx)
 
 
 @cli.command()
diff --git a/src/kimi_cli/cli/__main__.py b/src/kimi_cli/cli/__main__.py
@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+
+from kimi_cli.cli import cli
+
+if __name__ == "__main__":
+    sys.exit(cli())
diff --git a/src/kimi_cli/cli/info.py b/src/kimi_cli/cli/info.py
@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+import platform
+from typing import Annotated, TypedDict
+
+import typer
+
+from kimi_cli.constant import VERSION
+
+
+class InfoData(TypedDict):
+    kimi_cli_version: str
+    agent_spec_versions: list[str]
+    wire_protocol_version: str
+    python_version: str
+
+
+def _collect_info() -> InfoData:
+    from kimi_cli.agentspec import SUPPORTED_AGENT_SPEC_VERSIONS
+    from kimi_cli.ui.wire.protocol import WIRE_PROTOCOL_VERSION
+
+    return {
+        "kimi_cli_version": VERSION,
+        "agent_spec_versions": [str(version) for version in SUPPORTED_AGENT_SPEC_VERSIONS],
+        "wire_protocol_version": WIRE_PROTOCOL_VERSION,
+        "python_version": platform.python_version(),
+    }
+
+
+def _emit_info(json_output: bool) -> None:
+    info = _collect_info()
+    if json_output:
+        typer.echo(json.dumps(info, ensure_ascii=False))
+        return
+
+    agent_versions_text = ", ".join(str(version) for version in info["agent_spec_versions"])
+
+    lines = [
+        f"kimi-cli version: {info['kimi_cli_version']}",
+        f"agent spec versions: {agent_versions_text}",
+        f"wire protocol: {info['wire_protocol_version']}",
+        f"python version: {info['python_version']}",
+    ]
+    for line in lines:
+        typer.echo(line)
+
+
+cli = typer.Typer(help="Show version and protocol information.")
+
+
+@cli.callback(invoke_without_command=True)
+def info(
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help="Output information as JSON.",
+        ),
+    ] = False,
+):
+    """Show version and protocol information."""
+    _emit_info(json_output)
diff --git a/src/kimi_cli/cli/mcp.py b/src/kimi_cli/cli/mcp.py
diff --git a/src/kimi_cli/ui/wire/protocol.py b/src/kimi_cli/ui/wire/protocol.py
@@ -0,0 +1 @@
+WIRE_PROTOCOL_VERSION: str = "1"

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# `kimi acp` Command
	`1`	+# `kimi acp` Subcommand
`2`	`2`
`3`	`3`	The `kimi acp` command starts a multi-session ACP (Agent Client Protocol) server.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# `kimi mcp` Subcommands
	`1`	+# `kimi mcp` Subcommand
`2`	`2`
`3`	`3`	`kimi mcp` is used to manage MCP (Model Context Protocol) server configurations. For concepts and usage of MCP, see [Model Context Protocol](../customization/mcp.md).
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# `kimi term` command
	`1`	+# `kimi term` Subcommand
`2`	`2`
`3`	`3`	The `kimi term` command launches the [Toad](https://github.com/batrachianai/toad) terminal UI, a modern terminal interface built with [Textual](https://textual.textualize.io/).
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		-# `kimi acp` 命令
	`1`	+# `kimi acp` 子命令
`2`	`2`
`3`	`3`	`kimi acp` 命令启动一个支持多会话的 ACP (Agent Client Protocol) 服务器。
`4`	`4`