概览、安装与系统架构

一、项目定位与核心能力

ToM-SWE（Theory of Mind for Software Engineering）是一个面向软件工程智能体的「心智理论」增强包，旨在通过理解用户心智状态、偏好与工作风格，为 AI 代理提供个性化指导。根据 README.md 的介绍，该项目能够与 OpenHands 等 SWE 代理框架无缝集成，使代理在执行任务前先进行"心智推理"，从而更准确地把握用户意图。

项目核心项目含三大模块：

1. 心智理论建模：基于历史交互数据预测用户意图与下一步动作，参见 AGENTS.md 中的功能描述。
2. 指令改写：将模糊的用户请求转化为可执行的个性化指导，参考 tom_swe/rag_module.py 中 _format_chunk 方法的上下文组装逻辑。
3. 会话清洗与基准构建：stateful_swe/session_washer.py 提供向历史会话注入偏好信号的能力，用于训练数据生成与基准测试。

社区关注点：issue #11 讨论了如何将 ToM 代理作为 MCP/API 服务供 OpenHands 调用，这是该项目在生产环境落地的重要方向。

资料来源：README.md:1-40，AGENTS.md:1-15

二、系统架构

整个项目采用三层记忆 + 双模块的设计，记忆层从底向上分别为已清洗会话、会话分析与用户画像。双模块则分别是核心 tom_swe（推理与分析）与基准工具 stateful_swe（数据生成与评估）。整体数据流如下：

flowchart TB
    A[原始用户会话<br/>data/sessions/] --> B[CleanSessionStore<br/>会话清洗]
    B --> C[SessionAnalysis<br/>会话分析]
    C --> D[UserProfile<br/>用户画像]
    D --> E[ToMAgent<br/>推理代理]
    E -->|propose_instructions| F[个性化指令]
    E -->|suggest_next_actions| G[下一步动作建议]
    H[RAGAgent<br/>向量检索] --> E
    I[PromptManager<br/>Jinja2 模板] --> E
    J[stateful_swe<br/>基准与评估] -.训练数据.-> A
    J -.评估.-> E

关键设计模式在 CLAUDE.md 中有详细说明：

• 异步处理：大量使用 asyncio 实现并发 LLM 调用。
• 多级缓存：Web 查看器对元数据与单次对话进行缓存以提升性能。
• 优雅降级：当 LLM 不可用时回退到基于规则的分析。
• Pydantic 模型：在管道中贯穿结构化数据校验，参见 tom_swe/__init__.py 导出的 UserProfile、SessionAnalysis 等模型。

提示词管理由 tom_swe/prompts/manager.py 中的 PromptManager 类统一负责，底层使用 Jinja2 的 FileSystemLoader，并启用 trim_blocks 与 lstrip_blocks 以获得整洁的输出。tom_swe/prompts/__init__.py 进一步通过 get_prompt_manager() 单例提供全局访问入口。

资料来源：CLAUDE.md:30-55，tom_swe/prompts/manager.py:1-50，tom_swe/__init__.py:15-50

三、安装方式

项目支持两种安装路径，详见 README.md 的 "Get Started" 章节：

3.1 从 PyPI 安装（推荐）

pip install tom-swe

该方式适用于仅需调用 ToM-SWE 公共 API 的下游用户。

3.2 从源码本地安装

推荐使用 uv 进行依赖管理：

pip install uv
uv sync

若希望参与 Beta 测试 OpenHands 集成的 ToM 增强代理，可使用以下命令拉取预构建分支：

pip install uv
uvx --python 3.12 --from git+https://github.com/XuhuiZhou/OpenHands@feature/tom-codeact-agent openhands

3.3 运行时依赖

资料来源：README.md:20-50，CLAUDE.md:55-62

四、关键模块清单

下表汇总了主要模块及其职责，便于快速定位代码：

公共 API 在 tom_swe/__init__.py 中通过 __all__ 统一暴露，并在包导入时自动调用 auto_configure_logging() 以便与上层应用（如 OpenHands）共享日志格式。

社区关注点：issue #30 报告了 tom_swe/prompts/registry.py 链接已失效（404），当前实际模块为 tom_swe/prompts/manager.py，引用文档时需注意纠正路径。

资料来源：tom_swe/__init__.py:30-65，AGENTS.md:18-35

参见

• ToM Agent 与 RAG 模块详解
• Stateful SWE 基准与评估
• OpenHands 集成指南

核心代理组件（ToM Agent、ToM 模块、RAG 与生成子系统）

概述

ToM-SWE 项目的核心由四个相互协作的 Python 模块组成：tom_swe.tom_agent、tom_swe.tom_module、tom_swe.rag_module 与 tom_swe.generation。它们共同提供软件工程（Software Engineering, SWE）场景下的"心智理论"（Theory of Mind, ToM）能力——理解用户意图、记忆会话历史，并为代理提出个性化建议。AGENTS.md 中描述的"三层记忆系统"（清洗后的会话 → 会话分析 → 用户画像）正是由这些组件协同构建。资料来源：tom_swe/__init__.py:1-80、AGENTS.md:1-30。

整个子系统以 ToMAgent 为对外入口，通过 create_tom_agent 工厂方法创建实例。ToMAgent 同时承担"用户消息分析"与"代理查询"两类双向咨询职责，并将请求路由到底层的 ToMAnalyzer 与 RAGAgent。资料来源：tom_swe/tom_agent.py:1-50。

flowchart LR
    User[用户/上游 SWE 代理] --> ToMAgent[ToMAgent<br/>tom_agent.py]
    ToMAgent -->|sleeptime_compute| CS[CleanSessionStore<br/>清洗会话]
    ToMAgent -->|propose/suggest| ToM[ToMAnalyzer<br/>tom_module.py]
    ToMAgent -->|检索| RAG[RAGAgent + VectorDB<br/>rag_module.py]
    ToMAgent -->|生成/执行| Gen[LLMClient + ActionExecutor<br/>generation/]
    CS --> ToM
    RAG --> ToM
    Gen --> CS
    Gen --> RAG

ToM Agent（编排层）

ToMAgent 是整套核心组件的编排入口，定义在 tom_swe/tom_agent.py:1-50 中。其关键方法包括：

• sleeptime_compute(sessions_data)：批量处理原始会话数据，写入清洗后的会话目录，并触发下游分析流程。资料来源：tom_swe/tom_agent.py:30-50。
• propose_instructions(...) 与 suggest_next_actions(...)：对应社区讨论 #14 "Create ToM Agent" 与 #17 "write a restful API for tom agent" 中提出的两项核心 API（"建议下一步动作"与"建议改进指令"）。SWEAgentSuggestion 数据类承载返回结构。资料来源：tom_swe/generation/dataclass.py:1-30。
• 通过 ToMAgentConfig 配置 file_store、mode（如 Pure RAG 基线）等参数，参见 example.py:30-60。

社区需求 #11 "Connect with Openhands" 期望 ToMAgent 通过 MCP/RESTful API 暴露给 OpenHands 使用，目前实现已具备 ToMAgent 与 TomCodeActAgent 集成的基础结构，但 API 服务层（#17）尚在规划中。资料来源：README.md:1-50。

ToM 模块（分析层）

ToMAnalyzer 在 tom_swe.tom_module 中实现，负责从清洗后的会话生成 UserMessageAnalysis、SessionAnalysis 与 UserProfile 三类结构化输出，对应 tom_swe/__init__.py:40-60() 中导出的公共 API。

tom_swe.memory.conversation_processor.clean_sessions 与 _clean_user_message 负责把原始事件流拆解为单轮用户消息，供 ToMAnalyzer 进一步分析。资料来源：tom_swe/tom_agent.py:30-50。

在 stateful_swe/profile_generator.py:1-30 中描述的 15 个 ConcreteUserProfile 覆盖了简洁/冗长、上游/过程式、短答复/长答复等组合，为 ToMAnalyzer 的画像生成提供合成数据基线，与 README 中提到的"real power user data"对一致。资料来源：stateful_swe/profile_generator.py:1-30。

RAG 模块（检索层）

RAGAgent、VectorDB、Document、RetrievalResult、ChunkingConfig 在 tom_swe.rag_module 中定义，是 ToMAgent 进行上下文检索的核心。RAGAgent 将会话切分为 Document 块，构建 markdown 化的"用户消息 + 上下文 + 元数据"字符串（包含 title、selected_repository、selected_branch、trigger 等字段）。资料来源：tom_swe/rag_module.py:1-50。

检索支持两种模式：

1. 向量检索：基于 VectorDB 的语义匹配；
2. BM25 检索：默认通过 bm25s + Stemmer 实现；若环境缺少依赖，则回退到 tom_swe.generation.bm25_fallback，仅保留最近 10 段对话，使用简化的 Porter 词干近似（约 80% 准确率）。可通过 pip install tom-swe[search] 安装完整 bm25s。资料来源：tom_swe/generation/action.py:1-40。

生成子系统（执行层）

tom_swe.generation 子包承担 LLM 调用与动作执行：

• LLMClient + LLMConfig：通过 litellm 统一封装，支持 litellm_proxy/claude-sonnet-4-20250514 等模型，并具备 Claude 3.5 Sonnet / Haiku 等回退。资料来源：CLAUDE.md:1-40。
• ActionType、ActionResponse、ActionExecutor：定义可执行动作的枚举与执行引擎，支撑 sleeptime_compute 等异步工作流。资料来源：tom_swe/generation/action.py:1-30。
• 参数模型（AnalyzeSessionParams、InitializeUserProfileParams、GenerateSuggestionsParams、SearchFileParams、ReadFileParams 等）由 tom_swe/generation/dataclass.py 统一导出。资料来源：tom_swe/generation/dataclass.py:1-30。
• 提示词管理：tom_swe.prompts.manager.PromptManager 基于 Jinja2 模板集中渲染。社区 #30 提示 README 中指向 tom_swe/prompts/registry.py 的链接为失效（404），实际入口应为 tom_swe/prompts/__init__.py。资料来源：tom_swe/prompts/__init__.py:1-20。

常见故障模式

• BM25 不可用：未安装 tom-swe[search] 时检索精度下降，应仅作为本地调试。资料来源：tom_swe/generation/action.py:1-40。
• LLM API Key 缺失：LITELLM_API_KEY 与 LITELLM_BASE_URL 未配置时 LLMClient 会抛错，需运行 uv run tom-config 初始化。资料来源：README.md:30-60。
• 会话目录写权限：sleeptime_compute 依赖 LocalFileStore 写入 data/，权限不足会中断整个流水线。资料来源：example.py:10-40。
• RESTful API 缺失：当前未提供官方 FastAPI 服务（#17 待实现），调用方需直接导入 ToMAgent。

See Also

• README.md
• AGENTS.md
• CLAUDE.md
• example.py
• Stateful SWE Benchmark 评估与数据集生成

记忆系统、对话处理与数据流水线

1. 概述与设计目标

ToM-SWE 的核心能力是为软件工程智能体（Software Engineering Agent）构建"心智理论"（Theory of Mind, ToM）建模。该能力依赖于一套三层记忆系统（three-tier memory system），把原始的用户交互数据逐步提炼成可推理的心理画像。

• 第一层：已清洗会话（Cleaned Sessions），由 tom_swe/memory/conversation_processor.py 提供的 CleanSessionStore 负责存储。
• 第二层：会话级分析（Session Analyses），由 LLM 提取的 SessionAnalysis 与 UserMessageAnalysis 组成。
• 第三层：用户级档案（User Profiles），由 UserProfile 等 Pydantic 模型刻画长期偏好与意图。

资料来源：AGENTS.md:5-10, tom_swe/__init__.py:35-58

整套流水线强调：异步并发处理、模型化数据校验（Pydantic）、多级缓存，以及在 LLM 不可用时的优雅降级（fallback 到规则化分析）。资料来源：CLAUDE.md:55-66

2. 整体架构与数据流

下图为数据从原始事件经过清洗、分析、检索到画像消费的整体流向：

flowchart LR
    A[Raw Sessions<br/>data/sessions/] --> B[conversation_processor<br/>CleanSessionStore]
    B --> C[SessionAnalysis<br/>UserMessageAnalysis]
    C --> D[UserProfile<br/>tom_module.ToMAnalyzer]
    D --> E[tom_agent.ToMAgent]
    E --> F[propose_instructions /<br/>suggest_next_actions]
    D --> G[RAGAgent / VectorDB]
    G --> F
    F --> H[OpenHands / SWE Agent]

关键设计点：

• CleanSessionStore 作为可持久化、可检索的会话仓库，是流水线的入口。资料来源：tom_swe/__init__.py:54-58
• RAGAgent 内部把每条用户消息组织为带有 Chunk ID、Session、Repository、Branch、Trigger 等元数据的 Markdown 片段，供向量检索召回。资料来源：tom_swe/rag_module.py:108-145
• tom_agent 在发起"咨询评估"（consultation assessment）时，把长 system prompt 标记为 cache_control: ephemeral，借助 prompt cache 降低重复推理成本。资料来源：tom_swe/tom_agent.py:15-32

3. 对话处理与"会话洗涤"流水线

为了生成训练数据与基准测试，仓库在 stateful_swe/ 下提供了会话洗涤（session washing）工具：

• session_washer.py：按用户的 concise/verbose（表达风格）、upfront/ongoing（提问时机）、short_response/long_response（消息长度）等偏好维度，向原始会话注入自然语言信号。资料来源：stateful_swe/session_washer.py:1-18
• profile_generator.py：基于真实"重度用户"数据，组合生成 15 个多样化的 ConcreteUserProfile，覆盖完整的偏好组合。资料来源：stateful_swe/profile_generator.py:1-25
• dataset_builder.py：将洗涤后的会话与画像组合，构建用于评估 ToM Agent 的基准数据集。

该数据集在社区中被广泛使用，外部访问入口位于 cmu-lti/stateful Hugging Face 数据集。资料来源：Issue #29（Stateful SWE benchmark data access request）

4. 核心数据结构与消费方式

tom_swe/generation/dataclass.py 定义了流水线中的关键模型，并通过 tom_swe/__init__.py 统一对外导出：

资料来源：tom_swe/__init__.py:15-58, tom_swe/generation/dataclass.py

最终消费侧由 tom_agent.ToMAgent 完成：它综合 UserProfile、清洗后的对话上下文与 RAG 检索结果，分别暴露 propose_instructions（给出建议性指令）和 suggest_next_actions（推荐下一步动作）两类能力，供 OpenHands 等 SWE Agent 远程调用。资料来源：tom_swe/tom_agent.py:8-40, Issue #17（write a restful API for tom agent）

5. 常见使用模式与失败模式

• 快速上手：通过 create_tom_agent() 工厂方法获得默认实例，配合 load_processed_data() 加载已有分析结果。资料来源：tom_swe/__init__.py:42-58
• 批处理分析：utils/aggregate_user_behavior.py 提供"综合分析"入口，输出系统提示词建议、沟通最佳实践、避免挫折策略等 Markdown 报告。资料来源：utils/aggregate_user_behavior.py:1-30
• 失败模式：
• 当 LLM 不可达时，模块会回退到规则化分析，但准确度显著下降。资料来源：CLAUDE.md:62-66
• 若 tom_swe/prompts/registry.py 路径失效，prompt 加载会报错（社区已记录为 Issue #30，README 中的链接 404）。资料来源：Issue #30（Dead link）
• tom_agent 在 consultation assessment 阶段返回非 GenerateSuggestionsParams 时，会进入"工作流未完成"分支并回退到文本降级结果。资料来源：tom_swe/tom_agent.py:28-40

See Also

• ToM Agent 与 RAG 模块架构
• Stateful SWE 基准与数据集构建
• OpenHands 集成与 REST/MCP 接口

概述

ToM-SWE 是一个面向软件工程（Software Engineering）代理的理论心智（Theory of Mind，简称 ToM）包，旨在为 OpenHands 等 SWE 代理提供用户偏好理解与个性化指令增强能力。包名已经从早期的 tom_module 重构为 tom_swe，并且在 PyPI 上以 tom-swe 名称发布 资料来源：AGENTS.md:1-20。本页面聚焦于该项目的四个关键运营维度：与 OpenHands 的集成方式、PyPI 发布部署流程、多模型分析能力，以及社区反馈所揭示的运维痛点。

OpenHands 集成

ToM-SWE 通过 TomCodeActAgent 与 OpenHands 框架深度集成，提供"咨询式"心智建模能力，使 SWE 代理在执行任务时能够调用 ToM 模块来推断用户意图 资料来源：AGENTS.md:8-12。在 Beta 测试阶段，用户可以通过如下命令从 OpenHands 的 feature/tom-codeact-agent 分支直接拉取并运行：

pip install uv
uvx --python 3.12 --from git+https://github.com/XuhuiZhou/OpenHands@feature/tom-codeact-agent openhands

该方式使用 uvx 工具创建隔离的 Python 3.12 运行环境，避免与本地依赖产生冲突 资料来源：README.md:25-35。社区在 Issue #11 中讨论了更进一步的连接方式——通过 MCP 或 RESTful API 服务器暴露 ToM 与 RAG 能力供 OpenHands 远程调用，Issue #17 进一步要求使用 FastAPI 包装 suggest_next_actions、propose_instructions 以及消息推送接口 资料来源：AGENTS.md:30-50。

部署与发布流程

ToM-SWE 采用 PyPI Trusted Publishing 机制进行零令牌的安全发布。发布前需要在 PyPI 后台配置 Pending Publisher，将 GitHub 仓库 All-Hands-AI/ToM-SWE 与 publish-to-pypi.yml 工作流进行 OIDC 绑定 资料来源：RELEASE.md:6-30。开发者也可以先发布到 TestPyPI 进行冒烟测试，配置流程与正式环境一致。项目同时支持本地开发模式：

pip install uv
uv sync

需要 Python 3.8+ 与可用的 LLM API Key 资料来源：README.md:55-75。从版本演进来看，仓库已发布 1.0.0（首个稳定版）、1.0.1（类型注解更新）、1.0.2（清理包依赖）和 1.0.3（体积优化）四个版本，每个版本对应一次明确的功能或质量改进 资料来源：README.md:14-20。

分析与评估能力

项目的 stateful_swe 子包提供了完整的数据生成与多模型评估流水线。MultiModelClarityEvaluator 类可在同一数据集上对多个 LLM 进行清晰度分类评估，记录每个样本的输入/输出 token 数、成本、置信度与耗时，最终汇总为 ModelResults 聚合对象 资料来源：stateful_swe/multi_model_clarity_eval.py:15-95。评估结果通过 visualize_model_results.py 渲染为 HTML 报告，包含准确率、误报率、漏报率以及"每美元准确率"成本效益排名 资料来源：stateful_swe/visualize_model_results.py:1-50。配套的 session_washer.py 用于向原始会话注入用户偏好信号以构造训练数据，而 profile_generator.py 则基于真实高频用户数据生成 15 份覆盖全交互组合的 ConcreteUserProfile 资料来源：stateful_swe/profile_generator.py:25-55、资料来源：stateful_swe/session_washer.py:1-30。

下表总结了仓库各子包承担的运营职责：

资料来源：AGENTS.md:14-30、资料来源：tom_swe/__init__.py:1-55。

运维痛点与社区反馈

从社区 Issue 与发布记录可以归纳出当前的几项主要运维挑战。其一，Issue #30 指出 README 中 tom_swe/prompts/registry.py 链接已失效（404），需要在文档中修正路径 资料来源：AGENTS.md:30-50。其二，Issue #8 与 Issue #10 反映项目目前缺少 pre-commit、mypy 与 pytest 的 GitHub Actions 工作流，开发者希望参考 sotopia-lab/sotopia 的 CI 配置补齐这一缺口。其三，Stateful SWE 基准数据最初不可公开访问，后由维护者在 Issue #29 中提供 Hugging Face 数据集地址 https://huggingface.co/datasets/cmu-lti/stateful 解决了访问问题 资料来源：AGENTS.md:30-50。最后，utils/aggregate_user_behavior.py 提供了综合分析流水线，可将负面消息、用户偏好与系统提示词建议整合输出 Markdown 报告，是运营可观测性的重要组件 资料来源：utils/aggregate_user_behavior.py:1-30。

架构总览

flowchart LR
  A[OpenHands Agent] -->|consult| B(TomCodeActAgent)
  B --> C[tom_swe.tom_agent]
  C --> D[tom_swe.tom_module]
  C --> E[tom_swe.rag_module]
  D --> F[(Three-Tier Memory)]
  E --> F
  G[stateful_swe] -->|eval| H[MultiModelClarityEvaluator]
  H --> I[HTML Reports]
  J[PyPI Trusted Publishing] -->|uv sync| K[End Users]

资料来源：AGENTS.md:8-30、资料来源：stateful_swe/multi_model_clarity_eval.py:15-95。

参见

• tom_swe 包初始化与公开 API 列表
• stateful_swe 数据集生成与模型评估
• PyPI Trusted Publishing 发布流程（RELEASE.md）
• Beta 测试接入指南（README.md）

Pitfall Log / 踩坑日志

项目：OpenHands/ToM-SWE

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | github_repo:1010896499 | https://github.com/OpenHands/ToM-SWE | host_targets=claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:1010896499 | https://github.com/OpenHands/ToM-SWE | README/documentation is current enough for a first validation pass.

3. 运行坑 · 来源证据：Dead link

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Dead link
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/OpenHands/ToM-SWE/issues/30 | 来源类型 github_issue 暴露的待验证使用条件。

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:1010896499 | https://github.com/OpenHands/ToM-SWE | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:1010896499 | https://github.com/OpenHands/ToM-SWE | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:1010896499 | https://github.com/OpenHands/ToM-SWE | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:1010896499 | https://github.com/OpenHands/ToM-SWE | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:1010896499 | https://github.com/OpenHands/ToM-SWE | release_recency=unknown