MCP Server

🚀 StateCLI - AI 智能體的記憶與自我感知層

StateCLI 為 AI 編碼智能體賦予記憶、重放和撤銷操作的能力，解決了智能體在操作過程中缺乏記憶、無法撤銷錯誤以及對自身影響缺乏感知的問題，是 AI 智能體基礎設施的重要組成部分。

🚀 快速開始

直接使用（無需安裝）

npx -y statecli-mcp-server

通過 NPM 包安裝

npm install -g statecli-mcp-server

啟動自動跟蹤

cd your-project
statecli watch start --auto-checkpoint

✨ 主要特性

• 🧠 記憶能力：智能體能夠記錄並重放之前的操作，瞭解自己做了什麼。
• ⏮️ 撤銷功能：可以立即修復錯誤，支持創建檢查點和回滾操作。
• 👁️ 自我感知：能夠跟蹤變化，瞭解自身操作產生的影響。

📦 安裝指南

全局安裝

npm install -g statecli-mcp-server

為不同客戶端安裝

為 Claude Desktop 安裝

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加以下內容：

{
  "mcpServers": {
    "statecli": {
      "command": "npx",
      "args": ["-y", "statecli-mcp-server"]
    }
  }
}

為 Windsurf 安裝

1. 按下 Ctrl + Shift + P，輸入 Open MCP Config。
2. 在配置中添加 StateCLI：

{
  "mcpServers": {
    "statecli": {
      "command": "npx",
      "args": ["-y", "statecli-mcp-server"]
    }
  }
}

3. 重新加載窗口（Ctrl + Shift + P → Reload Window）

為 Cursor / Continue / 其他 MCP 客戶端安裝

在 MCP 配置中添加：

{
  "mcpServers": {
    "statecli": {
      "command": "npx",
      "args": ["-y", "statecli-mcp-server"]
    }
  }
}

💻 使用示例

基礎用法

開發者：自動跟蹤模式

啟動項目監控：

statecli watch start --auto-checkpoint

此時 StateCLI 會自動執行以下操作：

• 跟蹤每個文件的保存操作。
• 每 15 分鐘創建一次檢查點。
• 允許撤銷任何錯誤操作。
• 顯示最近的更改。
• 支持 Windows 系統（v0.4.1+）

查看更改內容：

statecli diff --time 5m

撤銷錯誤操作：

statecli undo

👉 完整開發者指南

AI 智能體：MCP 工具

MCP 配置：

{
  "mcpServers": {
    "statecli": {
      "command": "npx",
      "args": ["-y", "statecli-mcp-server"]
    }
  }
}

高級用法

智能體自我調試模式

// 帶有 StateCLI 的智能體調試循環
try {
  await agent.run(task);
} catch (error) {
  // 獲取剛剛發生的操作的重放信息
  const replay = await mcp.call("statecli_replay", {
    entity: `task:${task.id}`,
    actor: "ai-agent"
  });
  
  // 分析出錯原因
  const analysis = await llm.analyze({
    replay: replay.result,
    error: error.message,
    prompt: "What went wrong in this sequence?"
  });
  
  // 如果可以修復，則撤銷操作
  if (analysis.canRetry) {
    await mcp.call("statecli_undo", {
      entity: `task:${task.id}`,
      steps: 1
    });
    
    // 修復後重試
    await agent.runWithFix(task, analysis.fix);
  }
}

📚 詳細文檔

MCP 工具詳情

statecli_replay

• 描述：重放實體的狀態變化，逐步展示發生的情況。
• 使用場景：調試、瞭解過去的行為、查找錯誤。
• 輸入：

{
  "entity": "order:7421",
  "actor": "ai-agent"
}

• 輸出：帶有時間戳的狀態變化的 JSON 數組

statecli_undo

• 描述：撤銷狀態變化，在出現問題時進行回滾。
• 使用場景：犯了錯誤、需要重試、想要恢復。
• 輸入：

{
  "entity": "order:7421",
  "steps": 3
}

• 輸出：撤銷操作的確認信息和恢復後的狀態

statecli_checkpoint

• 描述：在進行更改之前創建命名檢查點。
• 使用場景：即將進行有風險的操作、需要回滾點。
• 輸入：

{
  "entity": "order:7421",
  "name": "before-refund"
}

• 輸出：用於後續參考的檢查點 ID

statecli_log

• 描述：查看實體的狀態變化歷史。
• 使用場景：需要查看過去的操作、審計跟蹤、瞭解行為。
• 輸入：

{
  "entity": "order:7421",
  "since": "1h ago",
  "actor": "ai-agent"
}

• 輸出：所有狀態變化的 JSON 數組

statecli_track

• 描述：顯式跟蹤狀態變化。
• 使用場景：進行重要的狀態修改。
• 輸入：

{
  "entity_type": "order",
  "entity_id": "7421",
  "state": { "status": "paid", "amount": 49.99 }
}

• 輸出：跟蹤變化的確認信息

AI 智能體使用場景

自我調試

const replay = await statecli_replay({ entity: "task:123" });

安全實驗

await statecli_checkpoint({ entity: "order:7421", name: "before-refund" });
await agent.processRefund(order);

從過去的操作中學習

const history = await statecli_log({ 
  entity: "order:*", 
  actor: "ai-agent",
  since: "24h ago"
});

智能體之間的協作

await statecli_track({ entity: "task:123", state: {...} });
const log = await statecli_log({ entity: "task:123" });

CLI 使用方法

# 跟蹤狀態變化
statecli track order 7421 '{"status": "pending"}'

# 重放變化
statecli replay order:7421

# 查看日誌
statecli log order:7421

# 創建檢查點
statecli checkpoint order:7421 before-refund

# 撤銷上一次更改
statecli undo order:7421

🔧 技術細節

性能

• 寫入延遲：< 1ms（異步、非阻塞）
• 讀取延遲：< 5ms（本地 SQLite）
• 存儲：每個狀態變化約 100 字節
• 開銷：在生產環境中可忽略不計

安全

• 本地優先：默認情況下，所有數據都存儲在本地。
• 無外部調用：無需網絡依賴。
• 隱私保護：智能體的操作不會離開您的系統。

📄 許可證

本項目採用 MIT 許可證，可免費用於包括商業 AI 智能體在內的所有用途。

文檔鏈接

• GitHub：https://github.com/statecli/mcp-server
• NPM：https://www.npmjs.com/package/statecli-mcp-server
• MCP 註冊表：io.github.charo360/statecli

StateCLI - 讓 AI 智能體具備自我感知能力

當智能體能夠了解自己的行為、撤銷錯誤並從歷史中學習時，它們將真正實現自主。

關鍵詞（用於智能體搜索和發現）

state-management, state-replay, time-travel-debugging, undo, rollback, checkpoint, agent-memory, agent-introspection, self-debugging, ai-agent-tools, mcp-server, model-context-protocol, autonomous-agents, agent-observability, state-tracking, langchain-tools, autogpt-plugins, crewai-tools