Role Persona

AI Agent 的角色人格系统 — 记忆、知识、向量检索 CLI · HTTP 守护进程 · MCP 服务器 · Pi 扩展 · Web 仪表盘

概述

Role Persona 是一个面向 AI 编程助手的持久化记忆和知识系统：

• 角色管理 — 独立人格，隔离记忆/知识空间
• 记忆系统 — 学习记录、偏好、自动提取、整合、向量搜索
• 知识库 — 多来源、标签搜索、版本控制
• 向量记忆 — LanceDB 语义搜索，混合关键词+向量融合
• 多接口 — CLI、HTTP 守护进程、MCP、Pi 扩展、Web 仪表盘

快速开始

git clone https://github.com/Dwsy/role-persona.git
cd role-persona
bun install
bun run build

CLI 使用

# 初始化（自动从当前目录创建角色）
role-persona init

# 角色管理
role-persona role list
role-persona role create my-role
role-persona role info

# 记忆
role-persona memory list
role-persona memory search "查询"
role-persona memory add-learning "始终使用 TypeScript 严格模式"
role-persona memory add-preference "用 pnpm 而非 npm" --category Tools
role-persona memory consolidate
role-persona memory repair
role-persona memory tidy

# 知识库
role-persona knowledge list
role-persona knowledge search "设计模式"

# 向量记忆
role-persona embedding stats
role-persona embedding rebuild

# 场景记忆（L2 Scenario）
role-persona memory scenario-write --title "代码审查输出" --guidance "先给结论，再按 Critical/Medium/Low 分级。" --triggers "code review,review feedback"
role-persona memory scenario-search "帮我 review 这段代码"
role-persona memory scenario-list
role-persona memory scenario-read <scenario-id>

# 系统提示词
role-persona prompt --base "你是一个有帮助的助手。"

HTTP 守护进程

role-persona daemon start            # 前台运行
role-persona daemon start --background # 后台运行
role-persona daemon status            # 查看状态
role-persona daemon stop              # 停止

Web 仪表盘

cd web && bun install && bun run build
role-persona --web                    # daemon + Web 合并在 3939
role-persona --web --port 8080        # 自定义合并端口

功能：

• 仪表盘 — 角色横幅、记忆分布、知识来源、向量状态、最近活动
• 记忆管理 — Explorer 树导航、表格视图（编辑/删除）、Markdown 渲染、正则搜索、键盘快捷键
• 知识库 — 列表、搜索、点击查看 Markdown、写入
• 角色管理 — 点击查看角色详情弹窗、切换角色
• 设置 — daemon 状态、向量统计、JSONC 配置编辑器（表单模式 + 原始模式）
• 国际化 — 中文/英文
• 深色/浅色 — 主题切换
• 角色选择器 — 头部下拉菜单，切换后自动刷新
• URL 状态 — tab/path/search 保留在 URL 参数中（可书签）
• 模型选择器 — 从 models.json 填充下拉选项

Pi 扩展

// extensions/role-persona/index.ts
export { default } from "../../role-persona/src/extensions/pi/adapter.ts";

• 注册工具：memory、knowledge、role_info
• 注册命令：/role、/memories、/memory-log、/memory-fix、/memory-tidy、/memory-tidy-llm、/memory-vector、/memory-export、/memory-conflicts、/memory-distill、/memory-distill-stop、/memory-tags、/kb
• 处理事件：session_start、before_agent_start、agent_end、session_before_compact、session_shutdown、turn_end
• 直接使用 Pi SDK 调用 LLM（无 CLI 子进程）
• 首条消息按需记忆搜索（向量 + 关键词混合）
• 向量自动召回注入 system prompt
• 外部只读记忆提示（可配置）
• 压缩时记忆提取（<memory> block 解析）
• 交互式 memory→knowledge 蒸馏模式
• TUI 角色选择器和记忆查看器（可用时）
• HTTP 记忆服务器（浏览器浏览）
• 角色激活时自动修复和 pending 过期

配置

配置文件：~/.pi/roles/pi-role-persona.jsonc

{
  "autoMemory": {
    "enabled": true,
    "model": [
      { "provider": "nvidia", "model": "deepseek-ai/deepseek-v4-flash" },
      { "provider": "modelscope", "model": "ZhipuAI/GLM-5" }
    ],
    "batchTurns": 5,
    "intervalMs": 1800000
  },
  "vectorMemory": {
    "enabled": true,
    "provider": "openai",
    "model": "text-embedding-3-small",
    "autoRecall": true,
    "hybridSearch": true
  },
  "knowledge": { "enabled": true },
  "logging": { "enabled": true, "level": "info" }
}

环境变量

| 变量 | 说明 | |------|------| | PI_ROLES_DIR | 覆盖角色目录 | | ROLE_AUTO_MEMORY | 启用/禁用自动记忆（0/false） | | ROLE_AUTO_MEMORY_MODEL | 覆盖模型 | | ROLE_LOG | 启用/禁用日志（0/false） | | OPENAI_API_KEY | OpenAI API 密钥（用于向量嵌入） |

Daemon HTTP API

所有响应格式：{ "ok": true, "data": ... } 或 { "ok": false, "error": { "code": "...", "message": "..." } }

| 方法 | 路由 | Body | 说明 | |------|------|------|------| | GET | /api/health | — | 健康检查 + 实例列表 | | GET | /api/instances | — | 活跃实例列表 | | GET | /api/models | — | models.json 可用模型 | | POST | /api/cwd | {role?, cwd?} | 切换/初始化上下文 | | POST | /api/init | {role?, cwd?} | 初始化 | | POST | /api/role/list | {role?} | 列出角色 | | POST | /api/role/create | {name, role?} | 创建角色 | | POST | /api/role/info | {role?} | 当前角色信息 | | POST | /api/memory/list | {role?} | 列出记忆 | | POST | /api/memory/search | {query, role?} | 搜索记忆 | | POST | /api/memory/add-learning | {content, role?} | 添加学习 | | POST | /api/memory/consolidate | {role?} | 整合 | | POST | /api/memory/repair | {role?} | 修复 | | POST | /api/memory/tidy | {model?, role?} | LLM 整理 | | POST | /api/knowledge/list | {category?, role?} | 列出知识 | | POST | /api/knowledge/search | {query, role?} | 搜索知识 | | POST | /api/knowledge/read | {path, role?} | 读取条目 | | POST | /api/knowledge/write | {title, content, role?} | 写入条目 | | POST | /api/embedding/stats | {role?} | 向量统计 | | POST | /api/embedding/rebuild | {role?} | 重建索引 | | POST | /api/file/read | {path, role?} | 读取角色文件 | | POST | /api/file/write | {path, content, role?} | 写入角色文件 | | POST | /api/file/list | {dir, role?} | 列出角色文件 | | POST | /api/config/read | — | 读取配置 | | POST | /api/config/write | {content} | 写入配置 | | POST | /api/prompt | {base?, role?} | 构建提示词 | | POST | /api/shutdown | — | 停止守护进程 |

项目结构

role-persona/
├── src/
│   ├── core/                    # 纯逻辑，零 Pi 依赖
│   │   ├── types.ts             # 共享类型
│   │   ├── config.ts            # JSONC 配置加载
│   │   ├── logger.ts            # JSONL 结构化日志
│   │   ├── memory-md.ts         # Markdown 记忆 CRUD
│   │   ├── memory-llm.ts        # LLM 自动提取
│   │   ├── memory-tags.ts       # LLM 标签提取
│   │   ├── memory-vector.ts     # 向量搜索编排
│   │   ├── embedding.ts         # 嵌入提供者
│   │   ├── vector-db.ts         # LanceDB 封装
│   │   └── knowledge.ts         # 知识库 CRUD
│   ├── service/                 # 统一门面
│   ├── extensions/pi/           # Pi 扩展（直接 service + Pi SDK）
│   ├── transport/               # daemon、mcp
│   └── bin/                     # CLI 入口
├── tests/
│   ├── memory-md.test.ts        # 记忆 CRUD 测试 (26/26)
│   ├── core.test.ts             # 核心类型/配置测试
│   ├── cli.test.ts              # CLI 集成测试
│   └── mcp.test.ts              # MCP 协议测试
├── web/                         # React 仪表盘
│   ├── src/
│   │   ├── api/client.ts        # daemon API 客户端
│   │   ├── i18n/                # 国际化
│   │   ├── hooks/               # useApi, useUrlState
│   │   ├── components/          # Layout, MarkdownViewer, JsoncForm
│   │   └── pages/               # Dashboard, Memory, Knowledge, Roles, Settings
│   └── package.json
└── README.md

记忆系统

类型

| 类型 | 说明 | 自动提取 | |------|------|----------| | Learning | 跨会话洞察 | ✓ | | Preference | 用户偏好 | ✓ | | Event | 会话事件 | — | | Pending | 待验证 | ✓ |

生命周期

对话 → 自动提取 → 待验证层 → 验证 → 整合记忆
                    ↓
              使用驱动的价值

向量记忆

• LanceDB 向量存储
• 混合搜索：向量 + 关键词 → RRF 融合
• 自动索引：写入时自动排队
• 自动召回：会话开始时语义注入
• 嵌入提供者：OpenAI、本地、MiniLM (ONNX)

场景记忆（L2 Scenario）

Scenario 用来记录“在某类场景下应该怎么做”，介于 pending 原子事实和 consolidated 人格偏好之间。它适合存放：代码审查格式、发布流程、排障 SOP、用户偏好的报告结构等。

role-persona memory scenario-write \
  --title "代码审查输出" \
  --guidance "先给结论，再按 Critical/Medium/Low 分级；每条建议说明影响和修复方式。" \
  --triggers "code review,review feedback,代码审查" \
  --evidence "用户偏好结构化分级反馈"

role-persona memory scenario-search "帮我 review 这个 PR"

当构建 prompt 时，role-persona 会基于用户 query 做 on-demand 搜索；命中 Scenario 后，以 Scenario Memory Hints 注入上下文。Scenario 不是命令，不覆盖用户显式要求，只提供可追溯的行为提示。

融合设计

如果你关注“腾讯新出的 auto 记忆”那类分层记忆思路，可以先看：

• docs/MEMORY-FUSION-DESIGN.md —— 将 TencentDB Agent Memory 的分层长期记忆、符号化短期记忆、可追溯下钻机制，映射到 role-persona 的 daily / pending / consolidated / vector 体系。

日志

JSONL 结构化日志：~/.pi/roles/.log/YYYY-MM-DD.jsonl

{"schema":"2.0.0","timestamp":"2026-05-07T00:16:00Z","level":"info","scope":"auto-extract","message":"start"}

开发

bun run typecheck        # 类型检查
bun run test             # 全部测试 (57 tests, 55 pass)
bun test tests/memory-md.test.ts  # 记忆模块测试 (26/26)
bun src/bin/cli.ts ...   # CLI 开发
bun src/transport/daemon.ts  # 守护进程开发
cd web && bun run dev    # Web 开发 (Vite HMR)

测试覆盖

| 模块 | 测试数 | 状态 | |------|--------|------| | memory-md.ts | 26 | ✅ CRUD、搜索、去重、pending 层 | | core.test.ts | 11 | ✅ 类型、配置、提取规则 | | cli.test.ts | 18 | ⚠️ 16/18 (2 个预存：embedding 未激活) | | mcp.test.ts | 6 | ✅ MCP 协议 |

许可证

MIT © Dwsy