OpenClaw-SMR

Social Mind Reasoning — 为 OpenClaw 构建的运行时社会心智推理增强系统。

追踪信念、偏好、承诺、关系，防止视角泄漏，支持可插拔的 Theory of Mind 推理框架。

架构

┌─────────────────────────────────────────────────────────┐
│  packages/core (@openclaw/smr-core)                      │
│  框架无关 · 零外部依赖 · 57 tests                          │
│                                                          │
│  types.ts          30+ 核心类型                           │
│  engine.ts         SmrCoreEngine（主入口）                 │
│  state/            SocialStateStore + MemoryStore         │
│  extraction/       规则引擎（7 类事件，EN+CN，<10ms）        │
│  reasoning-engine/ 三层可插拔架构                           │
│    ├── backends/     RelationalStateBackend (V1)          │
│    ├── strategies/   RuleBasedUpdateStrategy (V1)         │
│    └── engines/      TemplateInferenceEngine (V1)         │
│  verification/     Leakage + delegate boundary 检测        │
│  mcp/             MCP Extension Seam                      │
│  eval/            Benchmark 框架 + 9 场景内置 benchmark     │
├─────────────────────────────────────────────────────────┤
│  packages/openclaw-plugin (@openclaw/social-mind-reasoner)│
│  OpenClaw 适配层 · 46 tests                               │
│                                                          │
│  index.ts          definePluginEntry 入口                  │
│  hooks/            Lazy Extraction 架构                    │
│  integration/      SQLiteStore + Memory Supplement + MCP  │
│  tools/            social_state_get / export / reset      │
│  commands/         /smr status|export|reset               │
└─────────────────────────────────────────────────────────┘

关键设计决策

Lazy Extraction：message_received（fire-and-forget）仅缓存消息；before_prompt_build（awaited）中完成事件提取 → 状态更新 → prompt 注入，保证因果顺序
三层可替换推理引擎：StateRepresentationBackend / StateUpdateStrategy / InferenceEngine 独立替换，通过 SmrReasoningRegistry 按 preset 组合
核心引擎与框架解耦：packages/core 零 OpenClaw 依赖，可被 Hermes 等其他 Agent 框架复用

快速开始

前置条件

Node.js >= 22.14.0
pnpm >= 10.32.1
Docker（推荐，用于隔离开发环境）

Docker 方式（推荐）

# 运行全部测试
docker compose run --rm test

# TypeScript 类型检查
docker compose run --rm typecheck

# 进入交互式开发 shell
docker compose run --rm dev

本地方式

# 安装依赖
pnpm install

# 运行全部测试
pnpm -r run test

# 类型检查
pnpm -r run typecheck

项目结构

openclaw-smr/
├── packages/
│   ├── core/                   # @openclaw/smr-core（框架无关核心引擎）
│   │   ├── src/
│   │   │   ├── types.ts        # 所有核心类型定义
│   │   │   ├── adapter.ts      # SmrAdapterInterface + SmrConfig
│   │   │   ├── engine.ts       # DefaultSmrCoreEngine
│   │   │   ├── state/          # SocialStateStore 接口 + MemoryStore
│   │   │   ├── extraction/     # EventExtractor（规则引擎）
│   │   │   ├── reasoning-engine/
│   │   │   │   ├── registry.ts      # SmrReasoningRegistry
│   │   │   │   ├── orchestrator.ts  # DefaultReasoningOrchestrator
│   │   │   │   ├── backends/        # RelationalStateBackend
│   │   │   │   ├── strategies/      # RuleBasedUpdateStrategy
│   │   │   │   └── engines/         # TemplateInferenceEngine
│   │   │   ├── verification/   # (由 TemplateInferenceEngine 内置)
│   │   │   ├── mcp/            # MCP Extension Seam
│   │   │   └── eval/           # Benchmark 框架
│   │   └── tests/              # 57 tests
│   │
│   └── openclaw-plugin/        # @openclaw/social-mind-reasoner（OpenClaw 插件）
│       ├── index.ts            # definePluginEntry 入口
│       ├── openclaw.plugin.json
│       ├── src/
│       │   ├── config.ts       # preset 配置解析
│       │   ├── hooks/          # Lazy Extraction hook 注册
│       │   ├── tools/          # 3 个工具
│       │   ├── commands/       # /smr 命令
│       │   ├── integration/    # SQLiteStore + Memory Supplement + MCP Bridge
│       │   └── openclaw-stubs/ # 独立开发用 SDK stub
│       └── tests/              # 46 tests
│
├── skills/smr/                 # 5 个 Skills 定义
│   ├── runtime/                # perspective-split, relationship-aware-reply, commitment-reminder
│   ├── verifier/               # leakage-check
│   └── delegate/               # delegate-boundary-check
│
├── docs/                       # 7 份设计文档
│   ├── requirements.zh-CN.md
│   ├── system-design.zh-CN.md
│   ├── interface-design.zh-CN.md
│   ├── implementation-plan.zh-CN.md
│   ├── reasoning-engine-design.zh-CN.md
│   ├── test-design.zh-CN.md
│   ├── tech-spec.zh-CN.md
│   └── versions/               # v1-v4 历史快照
│
├── Dockerfile                  # 开发环境镜像
├── docker-compose.yml          # test / typecheck / dev 服务
└── pnpm-workspace.yaml

核心概念

社会状态模型

系统追踪 5 类社会状态：

| 类型 | 说明 | 示例 | |------|------|------| | Belief | 某个实体持有的信念（含 scope：shared/private/system-only） | "Alice 认为项目预算是 50k"（private） | | Relation | 实体间的关系（含 trust/closeness 分级） | "Alice → Bob: colleague, trust: high" | | Preference | 实体的偏好（含 strength 分级） | "Alice: 沟通风格 → 简洁 (strong)" | | Commitment | 实体间的承诺（含 deadline/status 生命周期） | "Alice → Bob: 周五前发报告 (active)" | | Event | 社会事件流（7 类 + system） | preference_declared, commitment_made, ... |

事件提取

规则引擎从消息中提取 7 类社会事件：

preference_declared — 偏好声明
commitment_made — 承诺创建
commitment_completed — 承诺完成
fact_shared — 事实分享
private_fact_detected — 私有信息检测
relationship_signal — 关系信号
misunderstanding_repair — 误解修复

支持中英文模式匹配，单条消息 < 10ms。

推理引擎扩展层

三层独立可替换，通过 preset 快速切换：

| Preset | Backend | Strategy | Engine | 适用场景 | |--------|---------|----------|--------|---------| | default | relational | rules | template | 通用对话 | | perspective-aware | relational | rules | simtom | 视角敏感场景 | | belief-tracking | belief-graph | recursive | klevel | 策略博弈 | | privacy-strict | kripke | del | epistemic | 隐私合规 | | probabilistic | probabilistic | bayesian | bayesian | 不确定性推断 |

V1 实现了 default preset（relational + rules + template），其他 preset 的三层实现为接口预留。

输出校验

TemplateInferenceEngine 内置 verifier，检测：

Private leak：草稿中包含他人私有信息的关键词
System-only exposure：暴露系统内部推断（如情感分析结果）
Delegate overreach：代理越权表达委托人的私有观点
Scope mismatch：信息 scope 与接收者权限不匹配

决策模式：allow / warn（记录日志）/ block（拦截回复）

OpenClaw 集成

Hook 生命周期（Lazy Extraction）

入站消息
  ├─ message_received (fire-and-forget)
  │    └─ 缓存消息到内存队列
  │
  ├─ before_prompt_build (awaited)
  │    └─ flush 队列 → 事件提取 → 状态更新 → prompt 注入
  │
  ├─ LLM 推理
  │
  └─ before_agent_reply (awaited, claiming)
       └─ 校验输出 → block / warn / allow

安装到 OpenClaw

将 packages/openclaw-plugin/ 复制到 OpenClaw 的 extensions/social-mind-reasoner/，更新 import 路径（将 openclaw-stubs/plugin-entry 替换为 openclaw/plugin-sdk/plugin-entry），然后在 OpenClaw 配置中启用插件。

配置 Preset

| Preset | 验证模式 | Prompt Token | 推理引擎 | |--------|---------|-------------|---------| | minimal | warn | 500 | default | | balanced | warn | 2000 | default | | safety-first | block | 2000 | default | | full | block | 4000 | perspective-aware |

测试

# 全部测试（103 个）
pnpm -r run test

# 仅 core 测试
cd packages/core && pnpm test

# 仅插件测试
cd packages/openclaw-plugin && pnpm test

# Docker 中运行
docker compose run --rm test

测试分层：

核心引擎（57 tests）：state CRUD、event extraction、prompt builder、verifier、reasoning registry、engine e2e、eval framework
OpenClaw 插件（46 tests）：hook pipeline、SQLite persistence、memory supplement、MCP bridge、config resolution

设计文档

完整设计文档在 docs/ 目录：

| 文档 | 内容 | |------|------| | requirements.zh-CN.md | 需求定义（FR/NFR/验收标准） | | system-design.zh-CN.md | 系统架构与数据流 | | interface-design.zh-CN.md | 接口级设计（TypeScript 接口冻结） | | implementation-plan.zh-CN.md | 实施计划（Stage 0-7） | | reasoning-engine-design.zh-CN.md | 推理引擎扩展层三层架构 | | test-design.zh-CN.md | 测试设计（57 TC + 9 QA 场景） | | tech-spec.zh-CN.md | 技术规范 + OpenClaw API 对照 |

技术栈

语言: TypeScript 5.7+, ES2023, ESM
运行时: Node.js >= 22.14.0
包管理: pnpm workspaces
测试: Vitest
持久化: sql.js (SQLite, 纯 JS)
容器化: Docker + docker-compose

License

MIT

social-mind-reasoner

Summary

Install to Claude Code