# Snow Role Assistant

Snow Role Assistant 是从 [Project Snow](https://github.com/X1aoB/Project_Snow) 中拆分出的独立本机运行包。它为 Codex 提供只读角色表达层和公开知识检索，但不依赖 Project Snow 的进程、HTTP 服务、私聊数据库或用户事实库。

> 当前版本：`0.6.0`。仓库拆分后默认保持**未安装、未启用**；只有在用户主动完成数据导入、启动本机服务并安装插件后，Codex 才会加载它。

## 当前进展

- 插件、MCP、配对服务、管理 UI 和 SQLite FTS5 检索已经成为独立组件。
- MCP 保留原有四个只读工具名，并在服务缺失时返回可恢复错误，不退出 MCP 进程。
- `.mcp.json` 显式使用插件根目录作为 `cwd`，避免从错误工作目录解析服务脚本。
- 真实人格包、令牌、配对数据库和迁移备份均为本地忽略文件；公开仓库只包含 schema 与合成样例。
- 原插件子树 Git 历史已保留。拆分来源为 `X1aoB/Project_Snow` 的 `38a880810d1660f8e457cdf1373413d48d806555`。
- 2026-09-01 本地验收为 `8 passed`；另已用 Project Snow 导出的真实契约 ZIP 完成校验、原子导入和状态读取。

## 架构

```text
Project Snow
  └─ 脱敏 bundle 导出器
        └─ manifest + 人格快照 + 关系投影 + 公开知识
              ↓ 手动导入
Snow Role Assistant
  ├─ 本机 SQLite / FTS5 数据库
  ├─ 127.0.0.1:8765 配对与只读 API
  ├─ /assistant/ 管理 UI
  └─ Codex plugin / stdio MCP
```

导入完成后，Snow Role Assistant 不再调用或导入 Project Snow。两个项目可以独立升级、测试和运行。

## 安装独立运行环境

需要 Python 3.11 或更高版本。

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
```

先用公开的合成数据验证链路：

```powershell
.\.venv\Scripts\snow-role-assistant.exe validate-bundle .\examples\synthetic-bundle
.\.venv\Scripts\snow-role-assistant.exe import-bundle .\examples\synthetic-bundle
.\.venv\Scripts\snow-role-assistant.exe serve
```

管理界面位于 `http://127.0.0.1:8765/assistant/`。默认运行数据目录为 `%LOCALAPPDATA%\SnowRoleAssistant`；可通过 `SNOW_ROLE_ASSISTANT_DATA_DIR` 或 `--data-dir` 覆盖。

## 人格数据包

数据包可以是目录或 ZIP，必须包含：

- `manifest.json`：`snow-persona-bundle.v1`、生成时间、来源仓库/提交、知识版本、角色清单和文件校验和。
- `personas.json`：版本化角色快照。
- `relationships.json`：称呼和关系投影。
- `knowledge.jsonl`：带稳定 `source_id` 的公开知识文档。

导入器会验证 SHA-256、角色引用、重复 ID、危险归档路径和隐私禁用字段，并通过临时数据库原子替换当前索引。完整 manifest 契约见 [`schemas/persona-bundle.schema.json`](schemas/persona-bundle.schema.json)。

下列内容不得进入数据包或 Git：私聊、对话摘要、用户事实、令牌/散列、API 密钥、本机路径、Agent 日志、附件和原始运行数据库。

## 本机 API 与配对

服务只允许绑定 `127.0.0.1`、`::1` 或 `localhost`，管理写操作同时拒绝非回环 Origin。

| 接口 | 认证 | 用途 |
| --- | --- | --- |
| `GET /health` | 无 | 进程健康检查 |
| `GET /api/v1/persona/status` | 回环管理 | 数据包和配对状态 |
| `POST /api/v1/persona/pairings` | 回环管理 | 创建一次性配对令牌 |
| `DELETE /api/v1/persona/pairings/current` | 回环管理 | 撤销当前配对 |
| `GET /api/v1/persona/pairing` | Bearer | 读取当前配置 |
| `GET /api/v1/persona/snapshot/{id}` | Bearer | 读取人格快照 |
| `GET /api/v1/relationships/{id}` | Bearer | 读取关系投影 |
| `GET /api/v1/knowledge/search` | Bearer | FTS5 公开知识搜索 |

原始令牌不会写入 SQLite，只保存 SHA-256。可用时，当前令牌和配对 ID 写入 `SnowRoleAssistant` 系统凭据命名空间；也可显式设置 `SNOW_ROLE_ASSISTANT_TOKEN`。

## Codex 插件

插件位于 `plugins/snow-role-assistant`，公开 marketplace 位于 `.agents/plugins/marketplace.json`。MCP 默认连接 `http://127.0.0.1:8765`，可使用 `SNOW_ROLE_ASSISTANT_BASE_URL` 覆盖。

保留的工具：

- `snow_get_configuration`
- `snow_get_persona_snapshot`
- `snow_search_knowledge`
- `snow_get_relationship`

仓库拆分完成后的安全默认值是“不安装”。需要主动启用时，再运行：

```powershell
codex plugin marketplace add .
codex plugin add snow-role-assistant@snow-role-assistant
```

安装或升级后应新建 Codex 任务加载新的插件快照。若服务或 bundle 未就绪，initialize 和工具枚举仍会成功；具体工具调用会返回 `isError: true` 的结构化可恢复错误。

## 测试与故障排查

```powershell
.\.venv\Scripts\python.exe -m pytest
```

测试覆盖 bundle 校验与篡改拒绝、隐私边界、原子导入、FTS5、配对鉴权、令牌不落库、管理 Origin、防止任意工作目录启动失败、MCP 降级以及 marketplace 契约。

- MCP 报告服务不可用：确认 `snow-role-assistant serve` 正在运行，并检查 `SNOW_ROLE_ASSISTANT_BASE_URL`。
- MCP 报告未配对：打开 `/assistant/` 创建配对，或设置一次性环境令牌。
- bundle 校验失败：不要跳过校验；重新从 Project Snow 导出并核对 manifest 中的 SHA-256。
- Codex 启动异常：先卸载本插件并移除 marketplace 验证隔离状态；不要用自动重启掩盖新的 app-server 崩溃。

## 来源、许可与路线图

本仓库由 Project Snow 的 `plugins/snow-role-assistant` 子树历史拆分而来，后续独立维护。新增提交会记录来源仓库和来源提交，不重写 Project Snow 历史。

代码采用 GPL-3.0-only。下一阶段包括签名 bundle、可视化导入审计和更细粒度的角色包版本迁移；在稳定性验证完成前，不会默认安装插件或自动启动任何 TTS/Live2D 工作流。