Metadata-Version: 2.4
Name: wechat-chat-attitude
Version: 1.0.1
Summary: Local WeChat direct-chat evidence preparation MCP server
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp==2.1.1
Requires-Dist: cryptography<51,>=46
Requires-Dist: zstandard<1,>=0.23

# WeChat Chat Attitude

WeChat Chat Attitude 是一个在本机运行的微信单聊证据准备 MCP 服务。程序负责发现或导入聊天数据、匹配指定联系人、按聊天总长度生成近期与历史样本，并把可核对的消息分块提供给接入的模型。态度、回复节奏、沟通风格和行为倾向等语义判断由模型完成，程序本身不内置结论。

当前文档对应发行版本 `1.0.1`；`1.0.0` 为首个正式版本。

## 功能范围

- 支持 macOS 和 Windows 的本机数据发现，以及单聊 JSON、已解密数据库的导入；
- 在读取聊天正文前完成账户、进程和联系人确认，避免重名或多账户误匹配；
- 以全部导出记录计算时间范围和抽样边界，保留最近消息并按总长度增加分层历史样本；
- 通过 MCP 工具分块读取消息，并记录每个分块和消息的审阅状态；
- 支持刷新快照、比较新增消息、统计回复间隔和生成模型分析所需的证据清单；
- 服务只在本机使用 `stdio` 通信，不开放网络监听端口。

本项目不是关键词统计器，也不是自带模型的聊天机器人。模型读取哪些分块、哪些消息已经逐条审阅，以及哪些结论缺少直接证据，都应在分析报告中明确区分。

## 安装方式

### 自动下载模式（推荐）

自动下载模式从 PyPI 获取发行包，适用于支持自定义 MCP 配置的模型或 Agent。客户端需要先安装 Astral uv，使 `uvx` 命令位于系统 PATH 中：<https://docs.astral.sh/uv/getting-started/installation/>。

在 MCP 设置中加入以下 JSON，然后重启客户端：

```json
{
  "mcpServers": {
    "wechat-chat-attitude": {
      "command": "uvx",
      "args": [
        "--python", "3.11",
        "--from", "wechat-chat-attitude", "wechat-chat-attitude-mcp"
      ],
      "description": "本地微信聊天证据准备与逐条分析 MCP 服务"
    }
  }
}
```

首次启动时，`uvx` 会创建隔离环境并取得发行包；后续启动复用本机缓存。配置不要求访问本仓库，仓库可以保持 private。若客户端不能使用 `uvx`，可改用下方的本地模式。

### 本地模式（离线或需要源码时）

本地模式使用项目目录中的 `.venv`，适用于离线环境、需要审阅源码，或客户端无法调用 `uvx` 的情况。

macOS/Linux：

```bash
python3 install_mcp.py --client generic --config-mode local
```

Windows PowerShell：

```powershell
py -3 install_mcp.py --client generic --config-mode local
```

安装器会创建环境并输出包含绝对路径的 MCP 配置。`install.command`（macOS）和 `install.bat`（Windows）提供同样的图形化入口；只生成配置、不安装依赖时增加 `--config-only`。

### Codex 安装器

在项目目录运行以下命令可登记 Codex 配置：

```bash
python3 install_mcp.py --client codex
```

Windows：

```powershell
py -3 install_mcp.py --client codex
```

安装器只更新 `wechat-chat-attitude` 这一项，其他 MCP 配置会保留。重新打开 Codex 后，服务即可被发现。

## 生成或合并 MCP 配置

安装器支持把配置输出为文件，或合并到现有 JSON。合并前会在同目录生成 `.bak` 备份，并保留其他 `mcpServers` 条目。

```bash
python3 install_mcp.py \
  --client generic \
  --config-mode package \
  --config-output "/绝对路径/wechat-chat-attitude.mcp.json"
```

```bash
python3 install_mcp.py \
  --client generic \
  --config-mode package \
  --merge-config "/绝对路径/现有客户端配置.json"
```

Windows PowerShell 采用同样的参数，并将路径替换为 Windows 绝对路径。安装器不会猜测 Claude、Cursor 或其他客户端的配置位置，因此合并操作必须显式指定目标文件。

## 首次分析流程

完成 MCP 连接后，可使用类似下面的示例调用语句。尖括号内容应替换为实际联系人信息；示例不包含任何真实联系人或聊天内容。

> 使用 wechat-chat-attitude，分析“<联系人>”的全部微信单聊，重点分析对方的态度、回复变化、沟通风格和可观察到的行为倾向，并给出自然、低压力的后续聊天建议。

模型和 MCP 服务按以下顺序协作：

1. 发现本机微信账户和运行中的进程，只返回可选择的账户标识，不读取聊天正文；
2. 说明即将进行的本机授权，获得明确确认后才捕获所选进程的数据库密钥；
3. 若操作系统要求权限，仅输出一条供系统终端执行的命令；管理员密码只能输入系统终端，不进入模型上下文；
4. 提醒完全退出微信并建立稳定快照，避免复制正在写入的数据库；
5. 精确匹配一个联系人。出现重名、多个账户或多个候选时必须由调用方选择，不能猜测；
6. 以全部导出记录计算时间范围，保留最近完整消息，并按聊天总长度增加分层历史样本；
7. 逐块、逐条读取实际证据，登记已读取的消息 ID，再生成分析结论。

“全部聊天”表示全部导出记录参与范围计算和抽样；默认逐条提供给模型的是最近 1000 条消息以及按总长度增长的历史样本。超大聊天不会未经筛选地一次性放入上下文。需要更深的历史基线时，可在调用中指定 `deep` 模式。分析报告应区分以下计数：

- `raw_rows`：导出记录总数；
- `selected_rows`：抽样后准备给模型的记录数；
- `manual_reviewed_rows`：模型已经逐条读取并登记的记录数；
- 未逐条阅读的记录数及其原因。

## 刷新最新记录

新的分析应创建新的快照和 `run_id`，不能把旧运行结果当作最新数据。示例调用语句如下：

> 重新获取“<联系人>”的最新微信记录，不复用旧 run；完成后报告数据截止时间、最新消息 ID、相对上次新增的内容，再结合近期消息和回复间隔给出自然的聊天建议。

刷新流程会重新发现微信、按提示完成授权并建立稳定快照。若微信仍在运行，先结束微信进程，再继续提取。结果可以继续追问回复间隔、主动性或近期沟通变化，但每个判断都应回到已读取的消息证据。

## 无法自动获取时的导入方式

自动发现不适用于所有微信版本。此时可导入已经隔离的单聊 JSON 或稳定的已解密数据库：

> 使用 wechat-chat-attitude。导入“<单聊 JSON 或已解密数据库的绝对路径>”，联系人为“<联系人>”，本人标签为“我”。先列出将写入的本机文件，再准备证据；按顺序逐条读取所有分块，分析态度、沟通风格和可观察到的行为倾向，并给出自然的聊天建议。

单聊 JSON 的最小示例见 [examples/example-chat.json](examples/example-chat.json)。已解密数据库、加密数据库和受保护密钥 JSON 的输入约定见 [本机获取说明](references/local-acquisition.md) 和 [输入格式](references/input-format.md)。

## 隐私与安全

- MCP 服务仅通过本机 `stdio` 运行，不监听网络端口；
- 原始聊天只在读取分块时返回，不写入服务日志；
- 数据库密钥仅保存在本机私有目录，工具结果不会返回密钥字段；
- 程序不会修改微信数据库、微信应用或账户文件；
- 使用云模型时，已经读取的消息会进入该模型的上下文，并受对应服务商的数据政策约束；
- 管理员密码、数据库密钥和密钥 JSON 内容不应发送到模型对话中；
- 发行包不包含真实聊天、数据库密钥或第三方预编译扫描器。

## 常见问题

### 配置成功但客户端找不到 MCP

保存 JSON 后完全退出并重新打开客户端。自动下载模式需要确认 `uvx` 位于 PATH；发行包不可用或网络受限时切换到本地模式。

### 系统要求输入密码

密码只输入系统 Terminal/管理员终端。模型和 MCP 服务不需要、也不应接收该密码。

### 服务要求退出微信

这是为了避免复制正在写入的数据库。结束微信进程并确认进程已经退出后，再重新建立快照；不要对持续变化的数据库进行解密。

### 找不到联系人或出现多个候选

使用精确备注、昵称或微信号，并让模型列出候选后选择。服务不会替调用方猜测联系人。

### 当前微信版本不支持自动获取

改用单聊 JSON 或稳定的已解密数据库导入。服务会明确报告不支持的步骤，不会假装成功或扫描无关路径。

## 发布与仓库关系

PyPI 发行包与源码仓库相互独立：

- 使用自动下载模式只需要 PyPI 包和 `uv`，不需要源码仓库权限；
- 仓库可以保持 private，适合维护者审阅和发布；
- 需要下载安装脚本、配置模板或查看源代码时，才需要仓库访问权限；
- 发布者完成一次 PyPI Trusted Publisher 配置后，向仓库推送与 `pyproject.toml` 对应的 `v*` 标签，GitHub Actions 会自动测试、构建并发布发行包。

发布者清单见 [docs/publishing.md](docs/publishing.md)。

## 开发与验证

不使用 MCP 也可以运行 `scripts/wechat_chat_pipeline.py` 处理 JSON 或已解密数据库。抽样、刷新、审阅账本和数据格式说明见：

- [MCP 使用设计](docs/mcp-first-mvp.md)
- [本机自动获取设计](docs/foolproof-acquisition-design.md)
- [分析合同](references/analysis-contract.md)
- [刷新流程](references/refresh-workflow.md)

运行完整测试：

```bash
PYTHONPATH=. .venv/bin/python -m unittest discover -s tests -v
```

构建发行包：

```bash
uv build --wheel --sdist
```
