README.md

@nicekit/cli

CLI 工具包 — 命令解析器、会话管理器、MCP 客户端、AI 对话集成。

从 Nice Today 项目提取封装，AI 服务通过 @nicekit/core 提供。

安装

npm install @nicekit/cli @nicekit/core

快速开始

import {
  AIClient,
  AIClientAdapter,
  MemoryStoreAdapter,
  sendAiMessage,
  parseNicecliCommand,
  startSession,
  exitSession,
  routeSessionInput,
  McpClient,
  performTabComplete,
} from '@nicekit/cli';

// 1. 创建 AI 客户端
const client = new AIClient({
  models: [{ id: 'deepseek-chat', provider: 'deepseek', apiKey: '...' }],
  defaultModelId: 'deepseek-chat',
});
const aiAdapter = new AIClientAdapter(client);

// 2. 解析命令
const result = parseNicecliCommand('nicecli help');
if (result.valid) {
  console.log('Parsed:', result);
}

// 3. AI 对话
const history: ConversationHistory = [];
const response = await sendAiMessage(
  aiAdapter,
  '你好',
  history,
  (chunk) => process.stdout.write(chunk),
);

// 4. 会话管理
const session = await startSession();
const route = routeSessionInput('你好');
// route.type === 'ai_chat'

const { exitMessage } = exitSession(session.sessionStats);
console.log(exitMessage);

架构

@nicekit/cli
├── core/           ← 零外部依赖的纯逻辑层
│   ├── parser.ts       命令解析器
│   ├── session.ts      会话状态机
│   ├── permission.ts   权限管理
│   ├── protocol.ts     ACP 消息协议
│   ├── policy.ts       工具策略
│   └── types.ts        共享类型
│
├── adapters/       ← 依赖反转适配层
│   ├── types.ts        适配器接口定义
│   ├── aiAdapter.ts    AIClient → AIAdapter
│   ├── storeAdapter.ts 内存 Store 实现
│   └── storageAdapter.ts 跨环境存储
│
├── ai/             ← AI 集成（通过 AIAdapter 调用）
│   ├── chat.ts         AI 对话（流式+协议消息）
│   ├── agent.ts        Agent 对话
│   └── integrations.ts 指令与技能
│
├── mcp/            ← MCP 协议客户端
│   ├── client.ts       HTTP JSON-RPC 客户端
│   ├── types.ts        MCP 协议类型
│   ├── pythonServer.ts Python 子进程（Node only）
│   └── enhanced.ts     MCP + AI 增强管道
│
├── commands/       ← 命令处理
│   ├── dispatcher.ts   命令分发
│   ├── mcpCommands.ts  MCP 命令
│   └── autocomplete.ts Tab 补全
│
└── react/          ← React 绑定（可选）
    ├── NiceCliProvider.tsx
    └── useNiceCli.ts

核心设计

适配器模式

所有外部服务依赖通过适配器接口注入：

// AI 服务：AIClient → AIAdapter
const aiAdapter = createAIAdapter(aIClient);

// 数据源：内存实现或应用 Store 包装
const storeAdapter = new MemoryStoreAdapter();

// 存储：浏览器 localStorage 或内存
const storageAdapter = getStorageAdapter();

与 @nicekit/core 集成

import { AIClient } from '@nicekit/core';
import { AIClientAdapter } from '@nicekit/cli';

const client = new AIClient({ /* ... */ });
const adapter = new AIClientAdapter(client);

// 使用 CLI 的 AI 对话功能
await sendAiMessage(adapter, '你好', history, onChunk);

React 集成

import { NiceCliProvider, useNiceCli } from '@nicekit/cli/react';

function App() {
  return (
    <NiceCliProvider client={aIClient} storeAdapter={store}>
      <Terminal />
    </NiceCliProvider>
  );
}

function Terminal() {
  const { aiAdapter, storeAdapter } = useNiceCli();
  // ...
}

模块清单

模块	文件数	说明
core	6	纯逻辑，零外部依赖
adapters	4	依赖反转适配层
ai	3	AI 对话集成
mcp	5	MCP 协议客户端
commands	3	命令处理
react	2	React 绑定
合计	23

从原有代码迁移

原有 utils/nicecli*.ts 文件可逐步替换为 @nicekit/cli 导出：

// 旧方式
import { sendAiMessage } from '../utils/nicecliAI';
sendAiMessage(userInput, history, onChunk);

// 新方式
import { sendAiMessage } from '@nicekit/cli';
sendAiMessage(aiAdapter, userInput, history, onChunk);

主要差异：所有函数的第一个参数改为对应的适配器实例。

构建

npm run build      # Vite 构建 + TypeScript 声明
npm run typecheck  # 仅类型检查

License

MIT