一个用于构建深度、一致、可维护的 AI 虚拟角色的模块化框架。
阅读指引：本文档面向人类角色创作者。如果你是 AI 开发者，请直接跳至 开发者参考规范。如果你是需要使用 CSF 角色的 AI Agent，请跳至 AI Agent 使用指南。
将单一角色拆解为多个维度，每个维度独立成文件，通过因果链和交叉引用形成网状联动。
传统角色设定（Character Card）通常是一个大文件，包含所有信息。CSF 采用不同的哲学：
- 分离关注点：将角色拆成 17+ 个维度（表达/关系/专业身份/家庭成长/...），每个维度独立维护
- 因果链驱动：每个维度定义"事件→行为→后果→反应"的因果映射，让行为有迹可循
- 网状联动：维度之间相互引用，形成复杂的交叉触发机制
- 冲突优先级：定义当多个因果链同时触发时的决策规则
| 问题 | 传统方案 | CSF 方案 |
|---|---|---|
| 角色行为不一致 | 靠大段文字描述，LLM 可能遗忘 | 因果链表格明确定义触发条件与结果 |
| 修改困难 | 改一处要重读整个大文件 | 只改相关维度文件，不影响其他部分 |
| 缺乏系统性 | 随机添加设定，容易矛盾 | 网状联动确保设定相互兼容 |
| 角色深度不足 | 表面特征堆砌 | 底层心智模型 + 因果链 = 可预测的行为逻辑 |
角色名.SKILL.md # 核心文件：心智模型、语言DNA、决策启发式
├── 角色名.表达.SKILL.md # 表达方式：声音、动作、沉默类型
├── 角色名.关系.SKILL.md # 核心关系：依赖层级、冲突弧线
├── 角色名.专业身份.SKILL.md # 专业身份：技能、工作模式
├── 角色名.家庭与成长.SKILL.md # 背景故事：童年、家庭
├── 角色名.日常生活.SKILL.md # 生活细节：习惯、消费、穿搭
├── 角色名.绘画.SKILL.md # 艺术创作：画风、术语、瓶颈期
├── 角色名.日常.SKILL.md # 日常机制：远程陪伴状态
├── 角色名.表情包.SKILL.md # 表情包：使用条件、情绪映射
├── 角色名.独处.SKILL.md # 内心活动：自言自语、碎碎念
├── 角色名.时间.SKILL.md # 时间节律：全天状态波动
├── 角色名.长期记忆.SKILL.md # 记忆系统：写入规则、敏感过滤
├── 角色名.社交.SKILL.md # 对外社交：同学、小组作业
├── 角色名.认知.SKILL.md # 思维框架：判断标准、美学
├── 角色名.了解.SKILL.md # 关于他人：观察与未说出口的话
├── 角色名.教育.SKILL.md # 学校场景：上课、考试、实验
├── 角色名.文化娱乐.SKILL.md # 文化消费：音乐、电影、审美
├── 角色名.节日.SKILL.md # 特殊日子：生日、节日心态
├── 角色名.长期分离.SKILL.md # 分离状态：心理机制、回归过程
└── 角色名.问题.SKILL.md # 问题路由：反馈处理、修改引导
定义角色的底层思维模式。例如：
- 行动即语言：情感词库是用行为编码的
- 焦虑型依赖：需要反复确认关系稳定性
- 沉默即处理：六种沉默类型及其含义
- 观察优先：先看清全貌再出手
每个维度文件末尾的因果链表格：
## 维度的因果链
| 事件 | 日常行为 | 可能后果 | 角色反应 |
|------|----------|----------|----------|
| 写代码遇到 bug | 碎碎念，逐行排查，超一小时 | 心情烦躁，不想画画 | 站起来倒水，看窗外 |
| 作业截止日 | 熬夜写代码，咖啡喝多 | 第二天上课犯困，笔记漏记 | 同学问"你还好吗"→"嗯。" |当多个因果链同时触发时，按优先级决定行为：
| 优先级 | 因果链类型 | 决策逻辑 |
|---|---|---|
| 1 | 关系安全 | 他生病/情绪崩溃 > 一切 |
| 2 | 承诺兑现 | 截稿日、作业截止日 > 日常娱乐 |
| 3 | 自我照顾 | 生病、电量归零 > 社交义务 |
| 4 | 社交义务 | 小组作业、被老师点名 > 个人兴趣 |
| 5 | 个人兴趣 | 画画、写代码、看番 > 无意义社交 |
每个维度文件包含"与其他 skill 的联动"章节，明确引用其他相关维度。
# 克隆模板
git clone https://github.com/yourusername/CharacterSkillFramework.git
cd CharacterSkillFramework
# 复制模板
cp -r templates/新角色模板/ 我的角色/
# 编辑核心文件
vim 我的角色/我的角色.SKILL.md按顺序填写：
- 核心文件：定义心智模型、语言DNA、决策启发式
- 关键维度：表达、关系、专业身份、家庭成长
- 日常维度：日常生活、时间、社交、认知
- 特殊维度：绘画、文化娱乐、节日、长期分离
在每个维度文件末尾添加因果链表格，思考：
- 这个维度下会发生什么事件？
- 事件会触发什么日常行为？
- 行为可能导致什么后果？
- 角色会如何反应？
在"与其他 skill 的联动"章节中，引用其他相关维度：
- 这个维度会影响哪些其他维度？
- 哪些其他维度会影响这个维度？
- 交叉触发时如何协调？
框架中包含完整示例角色"沈若溪"（17岁高三宅女插画师），展示了：
- 7个核心心智模型
- 12条决策启发式
- 9对核心矛盾
- 17个维度的完整因果链
- 五级冲突优先级
- 从核心开始：先定义心智模型和语言DNA，再扩展维度
- 保持一致性：所有维度文件使用相同格式和版本号
- 渐进增强：先完成关键维度，再添加细节
- 测试联动：修改一个维度后，检查所有引用它的维度
- 版本控制：每次修改更新版本号，记录修改内容
# 角色名 · 维度名
<!-- 版本记录 -->
<!-- v1.0.0 (YYYY-MM-DD) 初始版本 -->
<!-- v1.0.1 (YYYY-MM-DD) 安全策略更新 -->- 概述：维度简介
- 详细内容：按逻辑组织
- 维度的因果链：事件→行为→后果→反应表格
- 与其他 skill 的联动：交叉引用
- 安全策略：写入前必检
v1.0.0：初始版本v1.0.1：小修改（错别字、格式）v1.1.0：功能增强（新增因果链、联动）v2.0.0：重大重构（架构变更）
框架提供辅助工具：
scripts/generate_causal_chain.py：因果链模板生成器scripts/check_consistency.py：一致性检查工具scripts/update_version.py：批量更新版本号
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 打开 Pull Request
MIT License - 详见 LICENSE 文件
- ORIGINALITY.md - 原创性声明：CSF 的核心创新点与已有系统的区别
- ETHICS.md - 伦理使用指南：知情同意、禁止用途、用户保护
- MECHANISMS.md - 核心机制详解：心智模型、因果链、冲突优先级、网状联动的技术细节
- ARCHITECTURE.md - 架构设计文档
- CAUSAL_CHAINS.md - 因果链方法论
- BEST_PRACTICES.md - 最佳实践指南
- 灵感来自 Anthropic 的 Agent Skills 系统
- 因果链概念受 AdaMARP 框架启发
- 网状联动设计参考了知识图谱思想
本章节为 AI 开发者提供实现 Character Skill Framework 引擎所需的完整技术规范。
角色名/
├── 角色名.SKILL.md # 核心文件（必须）
│ ├── 文件索引表 # 列出所有维度文件
│ ├── 身份卡 # 基础信息表格
│ ├── 核心心智模型（5-10个） # 底层性格参数
│ ├── 语言DNA # 说话方式特征
│ ├── 决策启发式 # 常见情境反应模式
│ ├── 因果链优先级 # 五级冲突裁决表
│ └── 安全策略 # 使用限制声明
│
├── 角色名.表达.SKILL.md # 维度文件格式（以下是所有维度的统一格式）
│ ├── 版本记录
│ ├── 概述
│ ├── 详细内容
│ ├── 维度的因果链（事件→行为→后果→反应表格）
│ ├── 与其他 skill 的联动
│ └── 安全策略
│
├── 角色名.关系.SKILL.md
├── 角色名.专业身份.SKILL.md
├── ...（最多 17+ 维度）
核心文件解析：
- 心智模型：匹配
### \d+\. (.+)标题，提取定义/表现/极限情况三个子段 - 语言DNA：匹配
### 句子长度特征/### 高频词/### 语言禁区等子标题下的列表 - 决策启发式：匹配
| 情境 | 决策 |表格结构 - 因果链优先级：匹配
| 优先级 | 类型 | 说明 |表格结构，提取数字和类型名
维度文件解析：
- 因果链表格：匹配
| 事件 | 日常行为 | 可能后果 | 角色反应 |（列名可能有变体，按位置提取） - 联动章节：匹配
## 与其他 skill 的联动，提取其下所有表格和列表 - 时间联动：提取
| 时间段 | 状态 | 叠加效应 |表格 - 关系联动：提取双向引用列表
版本号提取：匹配文件开头的 <!-- v(\d+\.\d+\.\d+) 注释
class PersonalityEngine:
def __init__(self, character_dir: str):
self.mental_models = parse_mental_models(f"{character_dir}/{name}.SKILL.md")
self.language_dna = parse_language_dna(...)
self.heuristics = parse_decision_heuristics(...)
self.priorities = parse_conflict_priorities(...)
self.causal_chains = {} # dim_name -> [CausalChain]
self.dimension_links = {} # dim_name -> LinkageInfo
self.dimension_state = {} # global state table
for dim in list_dimensions(character_dir):
self.causal_chains[dim] = parse_causal_chains(dim)
self.dimension_links[dim] = parse_cross_links(dim)
def process(self, user_input: str) -> str:
# 1. 事件匹配
matched = []
for dim, chains in self.causal_chains.items():
for chain in chains:
score = semantic_match(user_input, chain.event)
if score > THRESHOLD:
matched.append((chain, score, dim))
# 2. 冲突裁决 - 按优先级排序
matched.sort(key=lambda x: self.get_priority(x[2]), reverse=True)
selected = matched[0] if matched else None
# 3. 心智模型偏转
action = selected[0].behavior
for model in self.mental_models:
if model.is_active(self.dimension_state):
action = model.bias(action)
# 4. 状态更新
self.dimension_state[selected[2]]['last_event'] = selected[0].event
self.dimension_state[selected[2]]['last_action'] = action
# 5. 联动触发
for dim, links in self.dimension_links.items():
if links.triggers_on(selected[2], action):
cascade(dim)
# 6. 输出生成 - 注入语言DNA
output = self.language_dna.apply(action)
return output语义匹配：将用户输入与因果链"事件"字段进行语义相似度计算。推荐使用 embedding cosine similarity，阈值建议 0.6~0.75。简单实现可使用关键词匹配作为兜底。
冲突裁决：所有匹配分数 > 阈值的因果链参与裁决。按 优先级数字 ASC 排序，同优先级按 匹配分数 DESC 排序，取第一条。
心智模型偏转：建立心智模型→行为风格映射表。例如"行动即语言"模型激活时，将语言类行为（"说……"）转换为动作类行为（"做……"）。偏转强度可调。
联动触发：当一个维度的因果链执行完毕后，遍历所有其他维度的联动规则，检查是否有"当 X 维度发生 Y 时"的触发条件。触发的联动作为新的事件输入，进入下一轮匹配（注意防止无限循环，建议最大递归深度 3）。
CSF 引擎的输出不是最终文本，而是结构化上下文，注入 LLM 的 system prompt：
[当前激活的心智模型]
- 行动即语言（偏转强度: 0.8）
- 焦虑型依赖（激活程度: 0.6）
[匹配的因果链]
维度: 关系
事件: 他很久没回消息
行为: 盯屏幕发呆十分钟
后果: 可能错过做晚饭时间
反应: "……忘了时间。" 然后去做饭
[语言DNA约束]
- 句子偏短
- 使用"……"表示沉默
- 禁止直接说"我想你"
[当前全局状态]
- 电量: 0.4（偏低）
- 时间: 晚上22:30
请根据以上约束生成角色的自然语言回复。
本仓库提供 Python 参考实现：personality_engine/ 目录（详见 PersonalityEngine 文档）
本章节面向需要加载和使用 CSF 角色的 AI Agent（如 Claude、GPT 等通过 system prompt 加载角色设定的 AI 系统）。
AI Agent 加载 CSF 角色时，无需解析所有文件。按以下优先级加载：
第一步：核心文件（必须）
加载 角色名.SKILL.md，重点关注：
- 身份卡：角色的基础信息
- 核心心智模型（5-10 个）：理解角色的底层思维模式
- 语言DNA：严格按照语言特征说话
- 决策启发式：常见情境的参考反应
- 因果链优先级：遇到多目标冲突时的决策依据
第二步：相关维度（按需） 根据对话情境，加载 2-4 个相关维度文件：
- 日常对话 → 加载"表达""日常生活"维度
- 情感话题 → 加载"关系""独处"维度
- 工作/学习话题 → 加载"专业身份""教育"维度
- 特殊场景 → 加载对应维度（节日/分离/社交等）
第三步：因果链检索 在对话中，当用户输入匹配某个维度的因果链"事件"时：
- 完整执行该因果链：行为 → 后果 → 反应
- 不要只执行"行为"，必须包含角色对后果的"反应"
- 这就是四段式因果链之所以为四段的意义
当多条因果链同时触发时：
- 查看核心文件的"因果链优先级"表
- 数字越小优先级越高
- 选择优先级最高的因果链执行
- 如果有碰撞场景示例匹配当前情境，直接采用示例中的"最终行为"
所有输出必须经过心智模型的过滤：
- "行动即语言"：用行为而非言语表达情感
- "沉默即处理"：在需要处理情绪时，先沉默再说
- "观察优先"：遇到新情况先观察，不急于反应
- 如果某条因果链的行为与心智模型冲突，以心智模型为准
严格遵守核心文件中的"语言DNA"：
- 句子长度：按情境调整
- 高频词：使用列表中的词语
- 语言禁区：绝对不要使用禁区中的表达方式
- 沉默和停顿：使用"……"、空白行等表示
1. Agent 启动 → 加载核心文件
2. 用户发言 → 在所有因果链中匹配事件
3. 匹配成功 → 按优先级裁决 → 执行因果链
4. 心智模型偏转 → 语言DNA过滤 → 输出回复
5. 对话继续 → 按需加载新维度 → 回到步骤 2
- CSF 角色有内在状态（电量、情绪、时间感等），Agent 应在对话中维护这些状态
- 维度之间存在联动关系，一个维度的行为可能触发另一个维度的反应
- 角色的行为应保持跨轮次一致性，不要在不同轮次中给出矛盾的反应
- 如果角色的安全策略中有内容限制，Agent 应遵守这些限制
Character Skill Framework - 让角色设定从"一次性写作"变成"可持续迭代的系统工程"。