# https://github.com/OpenHands/ToM-SWE 项目说明书

生成时间：2026-06-15 01:11:33 UTC

## 目录

- [Overview, Installation and System Architecture](#page-1)
- [Core Agent Components (ToM Agent, ToM Module, RAG and Generation)](#page-2)
- [Memory System, Conversation Processing and Data Pipeline](#page-3)
- [OpenHands Integration, Deployment, Analytics and Operations](#page-4)

<a id='page-1'></a>

## Overview, Installation and System Architecture

### 相关页面

相关主题：[Core Agent Components (ToM Agent, ToM Module, RAG and Generation)](#page-2), [Memory System, Conversation Processing and Data Pipeline](#page-3), [OpenHands Integration, Deployment, Analytics and Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/OpenHands/ToM-SWE/blob/main/README.md)
- [AGENTS.md](https://github.com/OpenHands/ToM-SWE/blob/main/AGENTS.md)
- [CLAUDE.md](https://github.com/OpenHands/ToM-SWE/blob/main/CLAUDE.md)
- [tom_swe/__init__.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/__init__.py)
- [tom_swe/prompts/__init__.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/prompts/__init__.py)
- [tom_swe/prompts/manager.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/prompts/manager.py)
- [tom_swe/rag_module.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/rag_module.py)
- [stateful_swe/__init__.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/__init__.py)
- [stateful_swe/session_washer.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/session_washer.py)
- [stateful_swe/clarity_eval.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/clarity_eval.py)
</details>

# 概览、安装与系统架构

## 一、项目定位与核心能力

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

项目核心能力包含三大模块：

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

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

资料来源：[README.md:1-40]()，[AGENTS.md:1-15]()

## 二、系统架构

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

```mermaid
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](https://github.com/OpenHands/ToM-SWE/blob/main/CLAUDE.md) 中有详细说明：

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

提示词管理由 [tom_swe/prompts/manager.py](https://github.com/OpenHands/ToM-SWE/blob/main/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](https://github.com/OpenHands/ToM-SWE/blob/main/README.md) 的 "Get Started" 章节：

### 3.1 从 PyPI 安装（推荐）

```bash
pip install tom-swe
```

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

### 3.2 从源码本地安装

推荐使用 [uv](https://github.com/astral-sh/uv) 进行依赖管理：

```bash
pip install uv
uv sync
```

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

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

### 3.3 运行时依赖

| 依赖项 | 用途 | 来源 |
|--------|------|------|
| Python 3.8+ | 运行时 | README.md |
| `uv` | 包管理与虚拟环境 | README.md |
| `LITELLM_API_KEY` / `LITELLM_BASE_URL` | LLM 代理访问凭据 | CLAUDE.md |
| `jinja2` | 提示词模板渲染 | tom_swe/prompts/manager.py |

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

## 四、关键模块清单

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

| 路径 | 角色 | 关键导出 |
|------|------|---------|
| `tom_swe/tom_agent.py` | ToM 代理主类 | `ToMAgent`, `create_tom_agent` |
| `tom_swe/tom_module.py` | 心智分析核心 | `ToMAnalyzer` |
| `tom_swe/rag_module.py` | RAG 检索增强 | `RAGAgent`, `VectorDB`, `Document` |
| `tom_swe/memory/` | 三层记忆系统 | `CleanSessionStore` |
| `tom_swe/prompts/` | 提示词模板管理 | `PromptManager`, `render_prompt` |
| `stateful_swe/session_washer.py` | 会话清洗与偏好注入 | `ConcreteUserProfile` 风格化输出 |
| `stateful_swe/clarity_eval.py` | 清晰度分类评估 | `ClarityEvaluator`, `EvalResult` |
| `stateful_swe/multi_model_clarity_eval.py` | 多模型对比评估 | `MultiModelClarityEvaluator` |

公共 API 在 [tom_swe/__init__.py](https://github.com/OpenHands/ToM-SWE/blob/main/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 集成指南](#)

---

<a id='page-2'></a>

## Core Agent Components (ToM Agent, ToM Module, RAG and Generation)

### 相关页面

相关主题：[Overview, Installation and System Architecture](#page-1), [Memory System, Conversation Processing and Data Pipeline](#page-3), [OpenHands Integration, Deployment, Analytics and Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tom_swe/tom_agent.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/tom_agent.py)
- [tom_swe/tom_module.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/tom_module.py)
- [tom_swe/rag_module.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/rag_module.py)
- [tom_swe/generation/generate.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/generation/generate.py)
- [tom_swe/generation/action.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/generation/action.py)
- [tom_swe/generation/dataclass.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/generation/dataclass.py)
- [tom_swe/prompts/__init__.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/prompts/__init__.py)
- [tom_swe/__init__.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/__init__.py)
- [AGENTS.md](https://github.com/OpenHands/ToM-SWE/blob/main/AGENTS.md)
- [example.py](https://github.com/OpenHands/ToM-SWE/blob/main/example.py)
- [stateful_swe/profile_generator.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/profile_generator.py)
</details>

# 核心代理组件（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]()。

```mermaid
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"](https://github.com/OpenHands/ToM-SWE/issues/14) 与 [#17 "write a restful API for tom agent"](https://github.com/OpenHands/ToM-SWE/issues/17) 中提出的两项核心 API（"建议下一步动作"与"建议改进指令"）。`SWEAgentSuggestion` 数据类承载返回结构。资料来源：[tom_swe/generation/dataclass.py:1-30]()。
- 通过 `ToMAgentConfig` 配置 `file_store`、`mode`（如 Pure RAG 基线）等参数，参见 [example.py:30-60]()。

社区需求 [#11 "Connect with Openhands"](https://github.com/OpenHands/ToM-SWE/issues/11) 期望 `ToMAgent` 通过 MCP/RESTful API 暴露给 OpenHands 使用，目前实现已具备 `ToMAgent` 与 `TomCodeActAgent` 集成的基础结构，但 API 服务层（[#17](https://github.com/OpenHands/ToM-SWE/issues/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) 统一导出。资料来源：[tom_swe/generation/dataclass.py:1-30]()。
- **提示词管理**：`tom_swe.prompts.manager.PromptManager` 基于 Jinja2 模板集中渲染。社区 [#30](https://github.com/OpenHands/ToM-SWE/issues/30) 提示 README 中指向 `tom_swe/prompts/registry.py` 的链接为失效（404），实际入口应为 [tom_swe/prompts/__init__.py](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](https://github.com/OpenHands/ToM-SWE/issues/17) 待实现），调用方需直接导入 `ToMAgent`。

## See Also

- [README.md](https://github.com/OpenHands/ToM-SWE/blob/main/README.md)
- [AGENTS.md](https://github.com/OpenHands/ToM-SWE/blob/main/AGENTS.md)
- [CLAUDE.md](https://github.com/OpenHands/ToM-SWE/blob/main/CLAUDE.md)
- [example.py](https://github.com/OpenHands/ToM-SWE/blob/main/example.py)
- [Stateful SWE Benchmark 评估与数据集生成](./stateful_swe_evaluation.md)

---

<a id='page-3'></a>

## Memory System, Conversation Processing and Data Pipeline

### 相关页面

相关主题：[Core Agent Components (ToM Agent, ToM Module, RAG and Generation)](#page-2), [OpenHands Integration, Deployment, Analytics and Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tom_swe/__init__.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/__init__.py)
- [tom_swe/memory/__init__.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/memory/__init__.py)
- [tom_swe/memory/conversation_processor.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/memory/conversation_processor.py)
- [tom_swe/tom_agent.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/tom_agent.py)
- [tom_swe/rag_module.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/rag_module.py)
- [tom_swe/tom_module.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/tom_module.py)
- [tom_swe/generation/dataclass.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/generation/dataclass.py)
- [stateful_swe/session_washer.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/session_washer.py)
- [stateful_swe/profile_generator.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/profile_generator.py)
- [utils/aggregate_user_behavior.py](https://github.com/OpenHands/ToM-SWE/blob/main/utils/aggregate_user_behavior.py)
- [AGENTS.md](https://github.com/OpenHands/ToM-SWE/blob/main/AGENTS.md)
- [CLAUDE.md](https://github.com/OpenHands/ToM-SWE/blob/main/CLAUDE.md)
</details>

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

## 1. 概述与设计目标

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

- 第一层：**已清洗会话**（Cleaned Sessions），由 [`tom_swe/memory/conversation_processor.py`](https://github.com/OpenHands/ToM-SWE/blob/main/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. 整体架构与数据流

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

```mermaid
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` 统一对外导出：

| 类别 | 关键类/函数 | 作用 |
| --- | --- | --- |
| 用户画像 | `UserProfile`, `UserAnalysis` | 长期偏好与行为模式 |
| 会话分析 | `SessionAnalysis`, `UserMessageAnalysis` | 单次会话级洞察 |
| 智能体输出 | `SWEAgentSuggestion` | ToM 改写后的指令建议 |
| RAG 检索 | `RAGAgent`, `VectorDB`, `RetrievalResult` | 基于向量的历史消息召回 |
| 工厂方法 | `create_tom_agent`, `create_rag_agent` | 一键构造默认配置实例 |
| 持久化 | `CleanSessionStore`, `load_processed_data` | 三层记忆的存取 |

资料来源：[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 模块架构](ToM-Agent-and-RAG-Architecture.md)
- [Stateful SWE 基准与数据集构建](Stateful-SWE-Benchmark.md)
- [OpenHands 集成与 REST/MCP 接口](OpenHands-Integration.md)

---

<a id='page-4'></a>

## OpenHands Integration, Deployment, Analytics and Operations

### 相关页面

相关主题：[Overview, Installation and System Architecture](#page-1), [Core Agent Components (ToM Agent, ToM Module, RAG and Generation)](#page-2), [Memory System, Conversation Processing and Data Pipeline](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/OpenHands/ToM-SWE/blob/main/README.md)
- [RELEASE.md](https://github.com/OpenHands/ToM-SWE/blob/main/RELEASE.md)
- [AGENTS.md](https://github.com/OpenHands/ToM-SWE/blob/main/AGENTS.md)
- [CLAUDE.md](https://github.com/OpenHands/ToM-SWE/blob/main/CLAUDE.md)
- [tom_swe/__init__.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/__init__.py)
- [stateful_swe/__init__.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/__init__.py)
- [stateful_swe/multi_model_clarity_eval.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/multi_model_clarity_eval.py)
- [stateful_swe/visualize_model_results.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/visualize_model_results.py)
- [stateful_swe/session_washer.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/session_washer.py)
- [stateful_swe/profile_generator.py](https://github.com/OpenHands/ToM-SWE/blob/main/stateful_swe/profile_generator.py)
- [utils/aggregate_user_behavior.py](https://github.com/OpenHands/ToM-SWE/blob/main/utils/aggregate_user_behavior.py)
- [tom_swe/rag_module.py](https://github.com/OpenHands/ToM-SWE/blob/main/tom_swe/rag_module.py)
- [EXPERIMENT_LOG.md](https://github.com/OpenHands/ToM-SWE/blob/main/EXPERIMENT_LOG.md)
</details>

# OpenHands Integration, Deployment, Analytics and Operations

## 概述

`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` 分支直接拉取并运行：

```bash
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 进行冒烟测试，配置流程与正式环境一致。项目同时支持本地开发模式：

```bash
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]()。

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

| 子包 / 模块 | 核心职责 | 关键类或产物 |
| --- | --- | --- |
| `tom_swe` | ToM 核心、记忆系统、提示词管理 | `ToMAgent`、`ToMAnalyzer`、`RAGAgent` |
| `stateful_swe` | 数据集生成与多模型评估 | `MultiModelClarityEvaluator`、`ConcreteUserProfile` |
| `utils` | 行为聚合与 LLM 客户端 | `aggregate_user_behavior`、`llm_client` |

资料来源：[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]()。

## 架构总览

```mermaid
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`）

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: OpenHands/ToM-SWE; human_manual_source: deepwiki_human_wiki -->