角色卡管理器

⚠️ 免责声明：本文档由 GLM4.7 自动生成，内容可能存在错误或不完整之处。请以人工书写的官方文档为准。

角色卡管理器是一个可视化的角色卡片编辑器，用于创建和管理角色信息。

功能说明

角色卡管理器提供：

可视化角色卡片界面
拖拽排序
分组管理
自定义字段

打开方式

方法一：从包管理器打开（推荐）

在 VS Code 左侧活动栏中点击 包图标（📦）
在包管理器中找到角色文件：
- .json5 文件（如 character-gallery.json5）
- .ojson5 文件（如 main-characters.ojson5）
双击文件即可用角色卡管理器打开

双击角色文件时会根据设置决定打开方式：
默认使用角色卡管理器打开
可在设置中配置 andrea.roleJson5.openWithRoleManager
右键点击文件可选择"打开方式"

方法二：右键菜单

在包管理器中右键点击角色文件
选择 打开方式 → 角色卡管理器

方法三：命令面板

按 Ctrl+Shift+P 打开命令面板
输入 Andrea Novel Helper: 打开角色卡管理器
管理器会在新列中打开

支持的文件格式

扩展名	类型	说明
`.json5`	角色库	通用角色集合
`.ojson5`	角色文件	专用角色格式
`.txt`	纯文本	一行一个条目
`.md`	Markdown	Markdown 格式

角色卡结构

角色卡模型 (RoleCardModel) 由三部分组成，支持完整的自定义键值对：

基本信息 (base)

基础字段是角色的核心属性，用于系统识别和处理。

必填字段：

name - 角色名称
type - 角色类型

可选字段：

uuid - 角色唯一标识符 (UUID v7)
affiliation - 从属标签（如阵营、组织）
aliases - 别名列表
color - 颜色 (#RRGGBB) - 旧字段
style - 文本样式（新字段）
- color - 前景色
- backgroundColor - 背景色
- bold - 是否粗体
- italic - 是否斜体
- strikethrough - 是否删除线
- underline - 是否下划线
priority - 优先级
description - 简介
regex - 正则模式（仅正则类型）
regexFlags - 正则标志（仅正则类型）
fixes - 修复候选（仅敏感词）

扩展信息 (extended)

扩展字段是预定义的自定义字段，用于存储常见的角色属性。支持任意键值对，值类型为 string | number | boolean | null | string[]。

常用扩展字段示例：

外貌 / appearance - 外貌描述
性格 / personality - 性格特点
背景 / background - 背景故事
技能 / skills - 技能能力
爱好 / hobbies - 爱好习惯
年龄 / age - 年龄（number 类型）
身高 / height - 身高
职业 / occupation - 职业

自定义字段 (custom)

自定义字段提供完全自由的键值对存储，支持任意属性名和值类型。

值类型支持：

string - 字符串
number - 数字
boolean - 布尔值
null - 空值
string[] - 字符串数组

使用场景：

标签系统：tags: ["主角", "女性", "法师"]
备注：note: "重要角色，需重点描写"
元数据：created: "2024-01-01"、updated: 1734567890
自定义评分：powerLevel: 85、popularity: 9.5
任意业务字段

完整数据结构示例

json5

{
  base: {
    name: "博丽灵梦",
    type: "主角",
    uuid: "01234567-89ab-cdef-0123-456789abcdef",
    affiliation: "博丽神社",
    color: "#e94152",
    priority: 10,
    description: "乐园的巫女",
    aliases: ["灵梦", "Reimu"],
    style: {
      color: "#e94152",
      bold: true
    }
  },
  extended: {
    外貌: "红白巫女服，大红蝴蝶结",
    性格: "大而化之，懒散随性",
    年龄: 17,
    身高: 160,
    职业: "巫女",
    技能: ["符卡射击", "灵力感知", "结界展开"]
  },
  custom: {
    称号: "乐园的巫女",
    登场章节: "第一章",
    重要程度: 5,
    tag: ["主角", "女性", "东方Project"],
    created: "2024-01-01",
    note: "需要重点描写的核心角色"
  }
}

自定义键值对使用指南

添加自定义字段

打开角色卡管理器
选择或创建角色卡
在 扩展信息 或 自定义字段 部分添加新字段
输入字段名和值
保存（自动保存）

扩展信息 vs 自定义字段

特性	扩展信息 (extended)	自定义字段 (custom)
用途	预定义的常见属性	完全自由的自定义属性
字段名	建议使用有意义的中文名	任意字符串
值类型	`string \| number \| boolean \| null \| string[]`	`string \| number \| boolean \| null \| string[]`
数量	建议控制在合理范围内	无限制
显示	在角色卡中显示	在角色卡中显示

值类型说明

类型	示例	说明
`string`	`"红白巫女服"`	文本字符串
`number`	`17`	数字（年龄、评分等）
`boolean`	`true`	布尔值
`null`	`null`	空值
`string[]`	`["主角", "女性"]`	字符串数组（标签列表等）

角色类型

预设类型

主角 - 主要角色
配角 - 次要角色
联动角色 - 跨作品角色
敏感词 - 需要替换的词汇
词汇 - 世界观相关词汇
正则表达式 - 模式匹配

自定义类型

可以创建任意自定义类型。

使用方法

创建新角色卡

点击"新建"按钮
填写基本信息
添加扩展信息
添加自定义字段
保存

编辑角色卡

点击要编辑的角色卡
修改内容
自动保存

删除角色卡

选择要删除的角色卡
点击删除按钮
确认删除

搜索和过滤

使用搜索框：

按名称搜索
按类型过滤
按标签过滤

示例角色卡

主角示例

yaml

base:
  name: 博丽灵梦
  type: 主角
  affiliation: 博丽神社
  color: '#e94152ff'
  priority: 10
  description: 乐园的巫女
  aliases:
    - 灵梦
    - Reimu

extended:
  外貌: |
    - 红白巫女服
    - 大红蝴蝶结
    - 阴阳玉随身
  性格: |
    - 大而化之
    - 懒散随性
    - 直觉敏锐

custom:
  称号: |
    - **乐园的巫女**
  备注: 香火清淡与钱包清冷

敏感词示例

yaml

base:
  name: 禁忌术
  type: 敏感词
  description: 需要替换的高危词汇
  fixes:
    - 禁止术
    - 秘法
    - 封印术
  color: '#ff0000'

extended:
  风险等级: |
    **高危**
    需重点替换

数据同步

自动同步

角色卡数据会：

自动保存到本地
同步到文件系统
与角色管理侧栏同步

导出格式

角色卡可以导出为：

JSON 格式
YAML 格式
Markdown 格式

快捷操作

快速创建

从选择文本创建角色
从模板创建角色

批量操作

批量编辑
批量删除
批量导出

常见问题

角色卡没有保存？

检查是否点击了保存
查看错误信息
确认文件权限

数据丢失？

检查自动保存设置
查看备份文件
尝试从文件系统恢复

如何导入现有角色？

使用导入功能
选择文件格式
映射字段
完成导入

角色卡管理器 ​

功能说明 ​

打开方式 ​

方法一：从包管理器打开（推荐） ​

方法二：右键菜单 ​

方法三：命令面板 ​

支持的文件格式 ​

角色卡结构 ​

基本信息 (base) ​

扩展信息 (extended) ​

自定义字段 (custom) ​

完整数据结构示例 ​

自定义键值对使用指南 ​

添加自定义字段 ​

扩展信息 vs 自定义字段 ​

值类型说明 ​

角色类型 ​

预设类型 ​

自定义类型 ​

使用方法 ​

创建新角色卡 ​

编辑角色卡 ​

删除角色卡 ​

搜索和过滤 ​

示例角色卡 ​

主角示例 ​

敏感词示例 ​

数据同步 ​

自动同步 ​

导出格式 ​

快捷操作 ​

快速创建 ​

批量操作 ​

常见问题 ​

角色卡没有保存？ ​

数据丢失？ ​

如何导入现有角色？ ​

相关功能 ​