Snow Role Assistant

Snow Role Assistant 是从 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 完成校验、原子导入和状态读取。

Related MCP server: edge_browser

架构

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 或更高版本。

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

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

.\.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。

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

本机 API 与配对

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

原始令牌不会写入 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

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

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

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

测试与故障排查

.\.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 工作流。