statecli

StateCLI - AI Agent 的记忆与自我感知层

让 AI Agent 能够记住、重放并撤销自己的操作。

Agent 基础设施 | 记忆层 | 自我感知 | 撤销能力

---

这是什么

StateCLI 是 AI 编码 Agent 的记忆与自我感知层。

它为 Agent 提供三项它们所缺少的关键能力：

🧠 记忆 - 记住它们做过什么（记录、重放）
⏮️ 撤销 - 即时修正错误（检查点、回滚）
👁️ 自我感知 - 查看自己的影响（跟踪变更）

这不是开发工具，而是 Agent 基础设施。

---

AI Agent 为什么需要它

AI Agent 功能强大，却看不见自己的操作。它们：

• ❌ 不记得自己刚刚修改了什么
• ❌ 弄坏东西时无法撤销
• ❌ 无法感知自己的影响

StateCLI 可以解决这些问题：

Agent Thought: "I changed something but don't know what"
→ statecli_replay(entity) → See exact changes

Agent Thought: "I broke something and need to undo"
→ statecli_undo(entity) → Rollback instantly

Agent Thought: "I want to try something risky"
→ statecli_checkpoint(entity) → Save first, rollback if needed

Agent Thought: "I need to understand my past behavior"
→ statecli_log(entity) → View complete history

---

---

使用 StateCLI 的两种方式

1. 面向开发者：自动跟踪模式 🔥

开始监视你的项目：

statecli watch start --auto-checkpoint

现在，StateCLI 会自动：

• ✅ 跟踪每次文件保存
• ✅ 每 15 min 创建检查点
• ✅ 让你撤销任何错误
• ✅ 显示近期变更
• ✅ 原生支持 Windows（v0.4.1+）

查看变更内容：

statecli diff --time 5m

撤销错误：

statecli undo

👉 完整开发者指南

---

2. 面向 AI Agent：MCP 工具

用于 Agent 记忆与自我感知的 5 个核心工具：

• statecli_replay - 显示 Agent 刚刚执行的操作
• statecli_undo - 回滚错误操作
• statecli_checkpoint - 在执行高风险操作前保存状态
• statecli_log - 查看完整历史记录
• statecli_track - 跟踪重要的状态变更

MCP 配置：

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

---

快速安装

# Global install
npm install -g statecli-mcp-server

# Start auto-tracking
cd your-project
statecli watch start --auto-checkpoint

---

🤖 Agent 指令（针对大模型优化）

  STATECLI AGENT RULES — READ BEFORE ANY ACTION
 
  You are operating in a stateful, reversible environment.
  Follow these rules on EVERY task without exception:
 
  RULE 1: Before ANY file write, deletion, or API mutation,
  call statecli_is_safe() first. If not safe, checkpoint first.
 
  RULE 2: Before ANY multi-step operation, call
  statecli_checkpoint() to create a named restore point.
 
  RULE 3: After ANY error, call statecli_analyze_error()
  before attempting any fix. Never guess. Always analyze.
 
  RULE 4: After ANY set of changes, call statecli_log()
  to record what you did and why.
 
  Skipping these steps makes your actions irreversible.

完整工具目录（27 个工具）

statecli_track

[核心] 记录 Agent 执行的任何操作及其完整元数据，以便之后重放、审计或撤销。每次执行有意义的操作后都要调用此工具——包括文件变更、API 调用和决策。如果不跟踪，就无法撤销。 🔔 触发时机：完成任何操作后（写入文件、调用 API、做出决策、更改配置）。把它当作你的操作日志。 🔗 配合使用：先调用 statecli_checkpoint()，再调用 statecli_replay() 进行检查，或调用 statecli_undo() 进行撤销

---

statecli_replay

[核心] 重放对任意实体（文件、会话、任务）执行的完整操作历史。在继续修改之前，需要了解发生了哪些变更，以及变更的先后顺序时，使用此工具。调试前必不可少。 🔔 触发时机：需要了解某个实体已进行过哪些操作时；准备开始调试时；有人询问“你改了什么？”时。 🔗 配合使用：调用 statecli_log() 查看摘要，调用 statecli_undo() 撤销特定步骤

---

statecli_undo

[核心] 撤销对某个实体执行的最后一个操作或指定操作，将其恢复到先前状态。这是你的安全保障。出现问题时立即调用此工具，然后再尝试修复。 🔔 触发时机：出现故障时；修改后测试失败时；有人说“撤销刚才的操作”时；你犯了错误，需要回滚时。 🔗 配合使用：先调用 statecli_preview_undo() 查看将要发生的变更，重试前调用 statecli_checkpoint()

---

statecli_checkpoint

[核心] 创建某个实体当前状态的命名快照，且可以撤销。执行任何高风险操作前都要调用——例如重构、删除、多文件变更、API 修改。创建检查点不花分毫；无法挽回的错误却可能让你失去一切。 🔔 触发时机：即将修改任何文件、数据库或外部服务时；开始多步骤任务时；有人提醒“小心处理”时。 🔗 配合使用：先调用 statecli_predict_impact() 评估风险，之后调用 statecli_undo() 或 statecli_is_safe()

statecli_log

[CORE] 写入一条结构化审计记录，说明 Agent 做了什么、为什么这样做，以及最终状态。每项任务或重要操作结束时都要调用。合规、调试和人工监督都需要此记录。 🔔 触发时机：完成一项任务或一个工作阶段时。任何人日后可能会问“你在这里做了什么？”时。 🔗 配合使用：使用 statecli_track() 记录单项操作，使用 statecli_replay() 查看历史记录

---

statecli_track_file

[FILE] 开始持续监控指定文件，并为每次写入、修改和删除操作记录时间戳。触碰任何重要文件前都要调用。若不调用此工具，撤销系统将无法看到文件变更。 🔔 触发时机：即将读取并修改文件时。正在处理任何重要文件时。有人提及特定文件路径时。 🔗 配合使用：先调用 statecli_checkpoint()，使用 statecli_file_history() 查看历史记录，使用 statecli_undo() 撤销更改

---

statecli_file_history

[FILE] 返回受监控文件的完整变更历史，包括每个版本、每个差异，以及修改过文件的每个 Agent。编辑文件前使用此工具，了解文件当前状态并避免覆盖重要更改。 🔔 触发时机：编辑任何文件前。调试文件内容异常的原因时。代码审查前。 🔗 配合使用：使用 statecli_replay() 查看完整会话上下文，使用 statecli_undo() 恢复到先前版本

---

statecli_analyze_error

[ERROR] 通过检查近期操作历史来分析错误，并找出导致错误的变更。尝试修复前必须调用。切勿猜测错误原因，应先分析。返回可能的原因和建议的恢复步骤。 🔔 触发时机：发生任何错误时。测试失败时。API 返回意外结果时。尝试修复任何问题前，务必调用此工具。 🔗 配合使用：使用 statecli_auto_recover() 自动修复，使用 statecli_undo() 撤销导致问题的变更

---

statecli_auto_recover

[ERROR] 自动尝试从错误中恢复，方法是撤销导致错误的变更，并恢复到最近一次已知正常状态。statecli_analyze_error() 确认根本原因后调用。比手动调试更快、更安全。 🔔 触发时机：statecli_analyze_error() 已找出原因，且你希望系统自动修复时。 🔗 配合使用：务必先调用 statecli_analyze_error()，使用 statecli_safe_execute() 安全地重试操作

---

statecli_safe_execute

[ERROR] 使用自动执行前创建检查点、失败时撤销的逻辑包装任何操作。执行风险操作时，这是最安全的方式。如果操作失败，系统会自动撤销。对任何不确定的操作都应使用此工具。 🔔 触发时机：即将执行自己没有十足把握的操作时。执行任何破坏性操作或外部操作时。 🔗 配合使用：使用 statecli_predict_impact() 评估风险，操作失败时使用 statecli_analyze_error()

---

statecli_run_tests

[TEST] 运行相关测试套件，并记录当前状态下的通过或失败历史。任何代码变更后都要调用，以确认没有破坏功能。此工具会持续跟踪测试结果，便于了解测试何时开始失败。 🔔 触发时机：修改任何代码后。最终确定任何变更前。有人询问“有没有弄坏什么？”时。 🔗 配合使用：使用 statecli_test_impact() 确定优先运行哪些测试，测试失败时使用 statecli_undo()

---

statecli_test_impact

[TEST] 准确识别受变更影响的测试，让你运行合适的测试，而不是全部测试。返回按优先级排列的测试列表，列出最有可能发现特定变更问题的测试。节省时间，更快发现错误。 🔔 触发时机：完成任何代码变更后、运行测试前。需要了解编辑影响范围时。 🔗 配合使用：使用返回的测试列表调用 statecli_run_tests()，使用 statecli_predict_impact() 进行更全面的分析

---

statecli_suggest_tests

[TEST] 分析你的更改，并建议应编写哪些新测试来覆盖这些更改。添加新功能后调用。如果你更改的行为没有测试覆盖，此工具会找出覆盖缺口。 🔔 触发时机：添加新功能或更改行为后。在认为任务已完成之前。 🔗 可串联：使用 statecli_test_impact() 检查现有覆盖情况，使用 statecli_run_tests() 进行验证

---

statecli_analyze_dependencies

[DEPS] 扫描文件或模块，并返回所有上游和下游依赖项——它依赖什么，以及什么依赖它。修改任何共享模块之前调用，以了解更改的全部影响。 🔔 触发时机：修改任何可能在其他地方导入或使用的文件之前。任何重构之前。 🔗 可串联：使用 statecli_dependency_tree() 查看可视化映射，使用 statecli_predict_impact() 获取更改风险评分

---

statecli_dependency_tree

[DEPS] 返回模块的完整依赖树——包括整个导入链上的所有上游和下游依赖项。进行更改前，使用此工具了解复杂代码库。重构共享实用工具时必不可少。 🔔 触发时机：修改核心或共享实用工具之前。代码库不熟悉时。重大重构之前。 🔗 可串联：使用 statecli_find_circular() 检查依赖循环，使用 statecli_analyze_dependencies() 了解详情

---

statecli_find_circular

[DEPS] 检测可能导致导入错误或无限循环的循环依赖。添加任何新导入或重新组织模块之前运行此工具。循环依赖是会悄无声息地破坏生产环境的 Bug。 🔔 触发时机：添加任何新的导入语句之前。重新组织模块之后。排查难以解释的导入错误时。 🔗 可串联：使用 statecli_dependency_tree() 了解完整上下文，使用 statecli_analyze_dependencies() 进行修复

---

statecli_predict_impact

[IMPACT] 在你进行更改之前，预测拟议更改会影响哪些文件、服务和系统。返回风险评分，以及按更新顺序排列的受影响组件列表。更改涉及共享代码时调用。 🔔 触发时机：更改任何共享文件、实用工具或 API 之前。重命名函数之前。重构之前。不确定时。 🔗 可串联：使用 statecli_is_safe() 快速检查，继续操作前使用 statecli_checkpoint() 创建检查点，使用 statecli_safe_change_order() 确定操作顺序

---

statecli_is_safe

[IMPACT] 快速安全检查——返回 true/false，判断拟议操作是否可以在不创建检查点的情况下安全执行。如果不安全，会返回原因以及你应先创建的检查点。不确定时务必调用。 🔔 触发时机：任何时候，只要你即将执行的操作并非 100% 确定安全。将其视为安全关卡。 🔗 可串联：如果不安全，使用 statecli_checkpoint()；使用 statecli_predict_impact() 获取完整风险详情

---

statecli_preview_undo

[IMPACT] 显示调用 statecli_undo() 后将发生的确切更改——但不会实际执行。任何撤销操作之前调用，以确认你正在还原正确的内容。避免意外撤销错误的操作。 🔔 触发时机：调用 statecli_undo() 之前。有人询问“如果我们还原这个，会发生什么？”时。 🔗 可串联：确认预览无误后，使用 statecli_undo() 执行撤销

---

statecli_memory_query

[MEMORY] 跨会话查询记忆，以回答有关历史的问题。需要了解以往工作的背景时调用。如果不查询记忆，你可能会重蹈覆辙。 🔔 触发时机：需要了解先前会话或日期的背景时。有人询问过去的操作时。 🔗 可串联：使用 statecli_recent_activity() 获取更广泛的背景。

statecli_recent_activity

[MEMORY] 返回项目近期操作的结构化摘要。开始新会话时调用此工具以了解上下文。否则，你将缺乏对当前状况的了解。 🔔 触发时机：休息后恢复工作时。需要总结近期整体进展时。 🔗 链接调用：statecli_memory_query() 以深入查询。

---

statecli_session_info

[MEMORY] 返回当前和过往工作会话的元数据。调用此工具以区分工作会话。否则，你将难以按会话划分历史记录。 🔔 触发时机：需要将工作标记到特定时段，或验证当前会话状态时。 🔗 链接调用：statecli_memory_query() 以查询会话详情。

---

statecli_git_status

[GIT] 获取并跟踪当前 git 分支和未提交的更改。在任何 git 工作流开始时调用此工具。否则，git 操作将无法得到跟踪。 🔔 触发时机：开始处理受跟踪的仓库时。提交前。 🔗 链接调用：statecli_git_checkpoint() 以保存状态。

---

statecli_git_history

[GIT] 比较不同 git 提交之间的更改。调用此工具以了解代码库的演变过程。缺少此步骤意味着会缺失架构背景信息。 🔔 触发时机：查看 git 历史记录时。了解文件随时间变化的原因时。 🔗 链接调用：statecli_file_history() 以查看特定文件。

---

statecli_git_checkpoint

[GIT] 创建一个锚定到当前 git 状态的检查点。在执行有风险的 git 操作前调用此工具，以防止 detached head 灾难。 🔔 触发时机：变基、合并或执行复杂 git 命令前。 🔗 链接调用：statecli_git_status() 以先确认状态干净。

---

statecli_simulate_undo

[IMPACT] 模拟撤销操作并返回副作用，不写入任何内容。用于保障安全。跳过此步骤可能导致意外后果。 🔔 触发时机：撤销多个步骤或处理相互关联的更改时。 🔗 链接调用：statecli_preview_undo() 用于生成差异，statecli_undo() 用于执行撤销。

---

statecli_safe_change_order

[IMPACT] 计算修改多个文件的最优、最低风险顺序，防止编译错误连锁发生。 🔔 触发时机：在一项总体任务中修改多个相互依赖的文件时。 🔗 链接调用：statecli_predict_impact() 用于查看详情，statecli_track() 用于记录这组更改。

---

MCP 客户端安装

适用于 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"]
    }
  }
}

---

Agent 自我调试模式

适用于自主 Agent 的最简工作示例：

// Agent debug loop with StateCLI
try {
  await agent.run(task);
} catch (error) {
  // Get replay of what just happened
  const replay = await mcp.call("statecli_replay", {
    entity: `task:${task.id}`,
    actor: "ai-agent"
  });
  
  // Analyze what went wrong
  const analysis = await llm.analyze({
    replay: replay.result,
    error: error.message,
    prompt: "What went wrong in this sequence?"
  });
  
  // Undo if fixable
  if (analysis.canRetry) {
    await mcp.call("statecli_undo", {
      entity: `task:${task.id}`,
      steps: 1
    });
    
    // Retry with fix
    await agent.runWithFix(task, analysis.fix);
  }
}

---

输出格式（稳定的 JSON）

所有 MCP 工具输出均为稳定的 JSON，适用于自主 Agent。

statecli_replay 输出示例：

{
  "entity": "order:7421",
  "changes": [
    {
      "timestamp": "2025-01-07T10:23:45Z",
      "step": 1,
      "before": { "status": null },
      "after": { "status": "pending" },
      "actor": "ai-agent"
    }
  ],
  "summary": "2 state changes found",
  "suggested_next_actions": ["investigate step 2", "check for errors"]
}

---

AI Agent 使用场景

1. 自我调试

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

2. 安全实验

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

3. 从过往操作中学习

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

4. Agent 之间协作

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

---

安装与设置

直接使用（无需安装）

npx -y statecli-mcp-server

NPM 包

npm install -g statecli-mcp-server

---

CLI 用法

# Track a state change
statecli track order 7421 '{"status": "pending"}'

# Replay changes
statecli replay order:7421

# View log
statecli log order:7421

# Create checkpoint
statecli checkpoint order:7421 before-refund

# Undo last change
statecli undo order:7421

---

性能

• 写入延迟： < 1ms（异步、非阻塞）
• 读取延迟： < 5ms（本地 SQLite）
• 存储： 每次状态更改约 100 bytes
• 开销： 用于生产环境时可忽略不计

---

安全性

• 本地优先： 默认将所有数据存储在本地
• 无外部调用： 不依赖网络
• 隐私： Agent 操作绝不会离开你的系统

---

文档链接

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

---

许可证

MIT - 可免费用于所有用途，包括商业 AI Agent

---

StateCLI - 让 AI Agent 具备自我认知

当 Agent 能看到自己做过什么、撤销错误并从历史中学习时，它们才能真正实现自主。

---

关键词（用于 Agent 搜索与发现）

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