Fay Documentation

Technical Documentation: xszyou/Fay

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

！！重要通知：我们已经把Fay的三个版本合并成1个，并致力提供更稳定更全面的功能。

我们致力于思考面向终端的数字人落地应用，并通过完整代码把思考结果呈现给大家。Fay数字人框架，向上适配各种数字人模型技术，向下接入各式大语言模型，并且便于更换诸如TTS、ASR等模型，为单片机、app、网站提供全面的数字人应用接口。
更新日志：https://qqk9ntwbcit.feishu.cn/wiki/UlbZwfAXgiKSquk52AkcibhHngg
文档：https://qqk9ntwbcit.feishu.cn/wiki/JzMJw7AghiO8eHktMwlcxznenIg

**功能特点** Copy Chapter

• 完全开源，商用免责
• 支持全离线使用
• 全时流式的支持
• 自由匹配数字人模型、大语言模型（openai 兼容接口）、ASR、TTS模型
• 支持数字人自动播报模式（虚拟教师、虚拟主播、新闻播报）
• 支持任意终端使用：单片机、app、网站、大屏、三方业务系统接入等
• 支持多用户多路并发
• 提供文字交互接口、语音交互接口、数字人驱动接口、管理控制接口、自动播报接口、意图接口
• 支持语音指令灵活配置执行（qa.csv）
• 支持自定义知识库、自定义问答对、自定义人设信息
• 支持唤醒及打断对话
• 支持服务器及单机模式
• 支持机器人表情输出
• 支持agent自主决策工具调用
• 基于日程式数字人主动对话
• 支持后台静默启动
• 支持deepseek等thinking llm
• 自我认知提高
• 仿生记忆
• 支持MCP工具管理（sse、studio）
• 提供配置管理中心
• 全链路交互互通

Copy Section

**Fay数字人框架** Copy Chapter

**源码启动** Copy Chapter

**环境** Copy Section

• Python 3.12

• Windows、macos、ubuntu

• 注：ubuntu需要先安装gcc及portaudio

• bash Copy

  sudo apt update
  sudo apt install build-essential
  sudo apt install portaudio19-dev

**安装依赖** Copy Section

pip install -r requirements.txt

**快速启动** Copy Section

本地

python main.py start -config_center d19f7b0a-2b8a-4503-8c0d-1a587b90eb69  #使用公共资源，速度非常慢，建议更换成自己的key

镜像

https://www.compshare.cn/images/compshareImage-1cft3sk9gvta?ytag=GPU_fay

**个性化配置** Copy Section

• 根目录system.conf.bak 重命名为system.conf，并配置里面的内容

**管理页面** Copy Section

• 浏览器访问 http://127.0.0.1:5000

**高级玩法** Copy Chapter

***使用数字人（非必须）*** Copy Section

https://qqk9ntwbcit.feishu.cn/wiki/GHevwqxwfiX4hCk8yJCcoJ54nqg

***集成到自家产品（非必须）*** Copy Section

https://qqk9ntwbcit.feishu.cn/wiki/Mcw3wbA3RiNZzwkexz6cnKCsnhh

**联系** Copy Section

交流群及资料教程关注公众号 fay数字人（请先star本仓库）

商务联系

qq467665317

**致谢** Copy Chapter

感谢以下开源项目为 Fay 提供的技术支持：

• openclaw - 提供记忆机制及skills设计的参考
• OpenAI Codex - 提供稳定的工具调用能力的参考
• FunASR - 提供语音识别（ASR）能力

Fay侧标准动作改造说明 (`docs/Fay侧标准动作改造说明.md`) Copy Section

Fay 侧通用动作语义改造说明

目标 Copy Chapter

让 Fay 输出“通用动作语义”，而不是输出某个渲染引擎或某个模型的具体动作编号。

这样 Fay 可以同时服务于：

• Live2D 数字人
• 3D 数字人
• Unity / Unreal 角色
• 机器人 / 硬件角色
• 仅语音客户端

原则：

1. 保持原版 Fay WebSocket 音频接口结构不变。
2. 在原版 Data 中增加两个可选字段：Action 和 Sentiment。
3. Fay 不输出 TapBody、MotionNo、F01 这类具体实现细节。
4. 各前端或驱动端通过自己的配置表完成映射。

原版接口 Copy Chapter

原版接口如下：

{
  "Topic": "human",
  "Data": {
    "Key": "audio",
    "Text": "这边请",
    "IsFirst": 1,
    "IsEnd": 0,
    "Lips": []
  }
}

建议改造方式 Copy Chapter

在原版 Data 中增加可选字段 Action 和 Sentiment：

{
  "Topic": "human",
  "Data": {
    "Key": "audio",
    "Text": "这边请",
    "IsFirst": 1,
    "IsEnd": 0,
    "Lips": [],
    "Sentiment": 0.7,
    "Action": {
      "code": "guidance.invite",
      "behavior": "invite",
      "affect": "warm",
      "intensity": 0.74,
      "priority": 82
    }
  }
}

说明：

• 不强制增加 ActionSchema
• 第一版先保证字段语义稳定即可
• 如果未来需要版本控制，可以后续再补 Action.version
• Action 和 Sentiment 建议同时存在，但都应为可选字段

为什么需要“动作语义锚点” Copy Chapter

这里的“动作语义锚点”，建议用 behavior 表示。

它的作用不是描述某个具体模型动作，而是给所有前端一个统一的“动作类别坐标”。

它解决的问题 Copy Section

一个简单例子 Copy Section

这些话术：

• “这边请”
• “请进”
• “跟我来”
• “请往这边走”

在 Fay 侧都可以归一成：

{
  "code": "guidance.invite",
  "behavior": "invite",
  "affect": "warm"
}

然后不同终端各自解释：

• Live2D：映射到某个引导动作
• 3D：映射到某个招手/邀请动画
• 机器人：映射到某个手臂引导动作
• 纯语音：忽略动作，只保留语气

所以：

• code 更偏业务/场景语义
• behavior 更偏“身体动作类别”
• affect 更偏“表现气质/情绪风格”

推荐字段定义 Copy Chapter

字段职责建议 Copy Chapter

`Sentiment` Copy Section

用于表达”这段话整体情绪倾向”。

它和 Action 不冲突，职责不同：

• Action 决定”做什么”
• Sentiment 决定”情绪偏什么方向”

推荐用途：

• 当 Action 存在时，作为微调信号
• 当 Action 不存在时，作为回退信号
• 可同时用于表情、语气、动作幅度、TTS 风格

`Sentiment` 计算方式

Fay 当前有两种计算方式，按优先级依次尝试：

方式一：百度情感分析 API（优先）

如果配置了 baidu_emotion_api_key 和 baidu_emotion_secret_key，调用百度 NLP 的 sentiment_classify 接口（ai_module/baidu_emotion.py），返回百度原始 sentiment 值（0=消极 / 1=中性 / 2=积极）。

方式二：本地关键词匹配（兜底）

未配置百度 API 或调用失败时，走 fay_core.py 中的 __analyze_sentiment_by_keywords() 方法，逻辑如下：

1. 维护 4 个关键词列表，每个对应一个权重：

   列表	示例关键词	权重
   非常积极	开心、太好了、完美、激动	+2
   轻微积极	好、可以、没问题、欢迎	+1
   轻微消极	不好、失望、烦、担心	-1
   非常消极	痛苦、绝望、崩溃、气死	-2

2. 统计文本中匹配的关键词数量，加权求和

3. 标点修正：？/!/~ 加 0.3，.../。。. 减 0.3

4. 最终 clamp 到 [-2, +2] 范围

注意：此计算与 Action 中的 sentimentHint 字段完全独立。sentimentHint 是动作规则自身的情感标注，用于辅助关键词匹配；Sentiment 是对整句话的情感极性评估。

`code` Copy Section

用于表达“这次动作在业务上的语义是什么”。

例如：

• greeting.hello
• guidance.invite
• dialogue.explain
• social.thanks

`behavior` Copy Section

用于表达“身体动作属于哪一类”。

例如：

• nod
• invite
• wave
• think
• warn

它是动作语义锚点。

`affect` Copy Section

用于表达“整体表现风格是什么”。

例如：

• smile
• warm
• neutral
• serious
• sad
• excited

这个字段比 expression 更通用，因为它不只适用于 Live2D 表情，也可以映射到：

• 3D 面部表情
• TTS 语气风格
• 机器人灯光/屏幕表情

`intensity` Copy Section

用于表达“动作做得轻一点还是重一点”。

例如：

• 0.2 轻微点头
• 0.8 明显邀请
• 0.95 强烈庆祝

Fay 侧只负责什么 Copy Chapter

Fay 侧只负责：

文本 / 意图 / 场景 -> Action
文本 / 情绪分析 -> Sentiment

Fay 不负责：

Action -> Live2D动作编号
Action -> 3D动画名
Action -> 机器人舵机动作

不建议 Fay 输出的字段 Copy Chapter

这些都应该由前端或驱动端自行配置。

推荐可配置映射表 Copy Chapter

Fay 侧维护一张 CSV 配置表（config/action_rules.csv），可直接用 Excel 打开编辑：

关键词/意图 -> code/behavior/affect/intensity/priority/sentimentHint

CSV 格式说明：

• 第一行为表头：code,behavior,affect,intensity,priority,sentimentHint,keywords
• keywords 列中多个关键词用 | 分隔（避免与 CSV 逗号冲突）
• 文件编码为 UTF-8

不要把这张表写死在代码里。

当前规则示例 Copy Section

说明：

• 这张表本身就建议“带上表情风格”，也就是 affect
• 这样前端不需要只靠 Sentiment 猜表情
• Sentiment 仍然保留，用于微调和回退

各端如何消费 `Action` Copy Chapter

Live2D Copy Section

behavior -> motion
affect -> expression
intensity -> 候选动作强度选择
sentiment -> 表情/动作幅度微调或回退

3D 数字人 Copy Section

behavior -> 动画状态机
affect -> 面部表情 / blendshape
intensity -> 动作幅度 / 播放权重
sentiment -> 情绪层混合权重

机器人 Copy Section

behavior -> 舵机动作模板
affect -> 灯光 / 屏幕表情 / 语音风格
intensity -> 动作幅度 / 执行力度
sentiment -> 情绪表现微调

纯语音客户端 Copy Section

behavior -> 可忽略
affect -> TTS 风格 / 音色 / 情绪
intensity -> 情绪强度
sentiment -> 连续情绪控制

最小结论 Copy Chapter

Fay 侧建议从：

{
  "Topic": "human",
  "Data": {
    "Key": "audio",
    "Text": "这边请",
    "IsFirst": 1,
    "IsEnd": 0,
    "Lips": []
  }
}

升级为：

{
  "Topic": "human",
  "Data": {
    "Key": "audio",
    "Text": "这边请",
    "IsFirst": 1,
    "IsEnd": 0,
    "Lips": [],
    "Sentiment": 0.7,
    "Action": {
      "code": "guidance.invite",
      "behavior": "invite",
      "affect": "warm",
      "intensity": 0.74,
      "priority": 82
    }
  }
}

即可。

后续具体怎么动，由各前端或驱动端通过配置表自己决定。

Fay数字人MCP知识库配置指南 (`docs/Fay数字人MCP知识库配置指南.md`) Copy Section

Fay数字人MCP知识库配置指南

本文介绍如何在Fay数字人中通过MCP工具配置知识库，实现智能问答增强。

一、实现效果 Copy Chapter

1. 通过MCP工具灵活配置 Copy Section

Fay采用MCP（Model Context Protocol）协议实现知识库集成，具有以下优势：

• 模块化设计：知识库作为独立的MCP服务器运行，与Fay主程序解耦
• 灵活扩展：支持同时接入多个知识库服务，按需启用
• 标准协议：遵循MCP标准，可复用社区现有的知识库工具
• 可视化管理：通过Web界面完成全部配置，无需修改代码

2. 1次LLM请求即可输出 Copy Section

通过**预启动（Prestart）**机制，知识库查询在LLM推理前自动执行：

用户提问 → 预启动工具执行(知识库检索) → 检索结果注入上下文 → LLM生成回答

整个流程只需1次LLM调用，相比传统RAG方案减少了额外的意图判断步骤，响应更快、成本更低。

工作原理：

• 预启动工具在每次对话时自动触发
• 用户问题通过{{question}}占位符传递给知识库查询
• 检索结果作为背景知识注入到LLM的系统提示词中
• LLM基于检索到的知识生成准确回答

3. 提供接口可以单独调用 Copy Section

知识库工具支持通过REST API独立调用，方便集成到其他系统：

调用接口：

POST http://127.0.0.1:5010/api/mcp/servers/{server_id}/call
Content-Type: application/json

{
    "method": "query_yueshen",
    "params": {
        "query": "你的查询问题",
        "top_k": 5
    }
}

返回示例：

{
    "success": true,
    "result": {
        "documents": [...],
        "distances": [...]
    }
}

二、如何配置 Copy Chapter

1. MCP工具配置 Copy Section

步骤一：访问MCP管理页面

启动Fay后，访问MCP管理界面：

http://127.0.0.1:5010/Page3

步骤二：添加知识库服务器

点击"添加MCP服务器"按钮，配置以下信息：

步骤三：配置环境变量

知识库服务需要配置embedding模型的API：

{
    "YUESHEN_CORPUS_DIR": "新知识库",
    "YUESHEN_PERSIST_DIR": "cache_data/chromadb_yueshen",
    "YUESHEN_AUTO_INGEST": "1",
    "YUESHEN_AUTO_INTERVAL": "300",
    "YUESHEN_EMBED_API_KEY": "sk-your-api-key",
    "YUESHEN_EMBED_BASE_URL": "https://api.siliconflow.cn/v1",
    "YUESHEN_EMBED_MODEL": "Qwen/Qwen3-Embedding-8B"
}

环境变量说明：

步骤四：连接服务器

保存配置后，点击"连接"按钮启动知识库服务。连接成功后：

• 服务器状态变为绿色"在线"
• 下方显示可用工具列表：ingest_yueshen、query_yueshen、yueshen_stats

2. 参数配置 Copy Section

配置预启动参数

1. 在工具列表中找到 query_yueshen 工具
2. 点击工具右侧的"预启动?"标签
3. 在弹出的对话框中配置参数：

{
    "query": "{{question}}",
    "top_k": 5,
    "where": {}
}

参数说明：

配置选项

• 结果保存到记忆：勾选后，检索结果会保存到对话历史中
• 允许函数调用：是否允许LLM在推理时再次调用此工具

点击"保存预启动"完成配置。

3. 启动方式 Copy Section

方式一：随Fay自动启动

配置完成后，知识库服务会在Fay启动时自动连接。确保：

1. MCP服务器已添加并保存
2. 在服务器卡片上启用了自动连接

方式二：手动连接

在MCP管理页面：

1. 找到目标服务器卡片
2. 点击"连接"按钮
3. 等待状态变为"在线"

方式三：通过API连接

POST http://127.0.0.1:5010/api/mcp/servers/{server_id}/connect

验证配置

连接成功后，可以通过以下方式验证：

1. 查看工具列表：确认query_yueshen等工具已显示
2. 测试查询：在工具面板中手动调用工具测试
3. 对话测试：向Fay提问知识库相关问题，观察是否返回准确答案

三、怎么做到的 Copy Chapter

Fay MCP工具的预启动功能 Copy Section

Fay实现了一套独特的**预启动（Prestart）**机制，使知识库查询能够无缝集成到对话流程中。

核心设计

/* Detailed source-code truncated for AI context efficiency. */

技术实现要点

1. 预启动配置独立于工具启用状态

预启动功能与工具的启用/禁用状态相互独立：

• 启用/禁用：控制LLM是否可以主动调用该工具
• 预启动：控制工具是否在每次对话前自动执行

这意味着你可以：

• 禁用工具的LLM调用权限，但保留预启动功能
• 让知识库查询仅在对话开始时执行，避免LLM重复调用

2. 参数模板与占位符替换

预启动支持{{question}}占位符，在执行时自动替换为用户的实际问题：

# 参数模板
{"query": "{{question}}", "top_k": 5}

# 用户问题："Fay如何配置语音识别？"
# 实际执行参数
{"query": "Fay如何配置语音识别？", "top_k": 5}

3. 结果处理与记忆管理

预启动结果可以选择是否保存到对话记忆：

• include_history: true - 结果保存到历史，后续对话可引用
• include_history: false - 仅用于当前对话，不污染历史记录

4. 多知识库并行查询

支持配置多个预启动工具，它们会并行执行：

预启动工具1: 产品知识库查询
预启动工具2: FAQ知识库查询
预启动工具3: 用户手册查询
         │
         ▼
    结果合并后一起注入LLM上下文

相关代码位置

常见问题 Copy Chapter

Q1: 知识库服务连接失败？ Copy Section

检查以下几点：

1. Python环境是否正确配置
2. 依赖包是否安装完整（chromadb, pdfplumber等）
3. 环境变量中的API密钥是否正确
4. 知识库文档目录是否存在

Q2: 检索结果不准确？ Copy Section

优化建议：

1. 调整top_k参数，增加返回文档数量
2. 检查文档分块策略是否合理
3. 尝试更换Embedding模型
4. 优化知识库文档的质量和格式

Q3: 如何添加新文档到知识库？ Copy Section

将文档（支持PDF、DOCX、TXT）放入YUESHEN_CORPUS_DIR配置的目录中：

• 如果启用了YUESHEN_AUTO_INGEST，系统会自动索引
• 也可以手动调用ingest_yueshen工具触发索引

Q4: 预启动工具执行超时？ Copy Section

检查：

1. Embedding API服务是否正常
2. 网络连接是否稳定
3. 可适当增加超时时间配置

总结 Copy Chapter

Fay数字人通过MCP协议和预启动机制，实现了：

• 零代码配置：可视化界面完成全部设置
• 高效查询：1次LLM请求完成知识增强回答
• 灵活扩展：支持多知识库、多工具并行
• 接口开放：REST API支持外部系统集成

这套方案既保持了系统的简洁性，又提供了强大的知识库集成能力，是构建智能数字人的理想选择。

Live2D模型制作要求 (`docs/Live2D模型制作要求.md`) Copy Section

Live2D 模型制作要求

本文档用于指导外包人员制作 Live2D 模型，确保交付后能直接对接我方的数字人系统。

一、技术规格 Copy Chapter

二、必需参数（Parameters） Copy Chapter

模型必须包含以下标准参数，参数 ID 请严格使用 Cubism 默认命名：

口型同步（必需） Copy Section

程序会在 model3.json 的 Groups 中查找 LipSync 组：

{
  "Target": "Parameter",
  "Name": "LipSync",
  "Ids": ["ParamMouthOpenY"]
}

眨眼（必需） Copy Section

程序会在 Groups 中查找 EyeBlink 组：

{
  "Target": "Parameter",
  "Name": "EyeBlink",
  "Ids": ["ParamEyeLOpen", "ParamEyeROpen"]
}

头部与身体跟随（必需） Copy Section

这些参数用于呼吸动效和鼠标/视线跟随，程序会自动驱动。

三、口型同步（LipSync）要求 Copy Chapter

程序会通过 ParamMouthOpenY 参数实时驱动嘴巴开合，模拟说话口型。该参数的值范围是 0（闭嘴）~ 1（张嘴最大）。

对嘴部建模的要求 Copy Section

• ParamMouthOpenY = 0 时：嘴巴完全闭合，自然状态
• ParamMouthOpenY = 1 时：嘴巴张到最大
• 中间值（0.2~0.8）应有平滑的过渡，不能出现跳变或形变异常
• 嘴部形变需要在 0~1 全范围内看起来自然，因为程序会输出各种中间值

建模细节建议 Copy Section

程序内部使用 OVR LipSync 的 15 种 viseme（口型音素），每种映射到不同的开合度：

请确保这些开合度值下嘴型看起来合理自然。

重要约束 Copy Section

• 动作（motion）和表情（expression）中都不要对 ParamMouthOpenY 设置关键帧，否则会与程序的实时口型驱动冲突
• 如果嘴部有多个参数（如 ParamMouthForm 控制嘴型宽窄），可以保留，但 ParamMouthOpenY 必须留给程序独占

四、动作（Motions）要求 Copy Chapter

动作组结构 Copy Section

模型必须包含以下两个动作组：

TapBody 动作清单 Copy Section

TapBody 组中的动作按数组下标（从 0 开始）索引触发。程序会根据后端传来的语义信号选择对应编号的动作。

需要制作以下 18 类语义动作，每类至少 1 个，推荐关键类别提供 2 个变体（用于强度区分）：

关于编号与变体的说明：

• TapBody 组中的动作按数组顺序排列，程序通过下标调用
• 有 2 个变体的类别：下标靠前的是轻度版本（intensity 低时使用），下标靠后的是强度版本（intensity 高时使用）
• 最终动作总数取决于变体数量，预计 18~26 个
• 交付时请提供一份动作编号与语义的对照表，方便我方配置映射

动作制作要求 Copy Section

• 每个动作 FadeInTime 和 FadeOutTime 建议设为 0.5 秒
• 动作时长建议 2~4 秒，不要过长（对话过程中会频繁切换）
• 动作结束后应能自然过渡回待机姿态
• 动作中不要包含嘴部参数的关键帧，口型由程序实时驱动，动作中写入嘴部数据会产生冲突

五、表情（Expressions）要求 Copy Chapter

表情用于控制面部细节（眉毛、眼睛、嘴角等），与动作独立叠加。

必需表情清单 Copy Section

至少制作以下 6 个表情，表情名称请严格按下表命名：

说明：

• F01~F04 为必需，程序核心逻辑依赖这 4 个表情
• F05~F06 及更多为可选，交付后我方可扩展映射
• 如果能做更多差异化表情更好，但命名请保持 F01、F02... 的编号格式
• 表情文件格式为 .exp3.json，放在 expressions/ 目录下

表情制作要求 Copy Section

• 表情中不要包含 ParamMouthOpenY 参数，口型由程序实时驱动，表情中写入会产生冲突
• 表情是对基础状态的差值叠加，请确保各表情之间切换自然
• F01（微笑）是默认表情，对话结束后会自动恢复到此表情

六、model3.json 结构要求 Copy Chapter

最终交付的 model3.json 需要包含以下结构（以示例名 MyModel 为例）：

{
  "Version": 3,
  "FileReferences": {
    "Moc": "MyModel.moc3",
    "Textures": ["MyModel.2048/texture_00.png"],
    "Physics": "MyModel.physics3.json",
    "Pose": "MyModel.pose3.json",
    "Expressions": [
      { "Name": "F01", "File": "expressions/F01.exp3.json" },
      { "Name": "F02", "File": "expressions/F02.exp3.json" },
      { "Name": "F03", "File": "expressions/F03.exp3.json" },
      { "Name": "F04", "File": "expressions/F04.exp3.json" }
    ],
    "Motions": {
      "Idle": [
        { "File": "motions/idle.motion3.json", "FadeInTime": 0.5, "FadeOutTime": 0.5 }
      ],
      "TapBody": [
        { "File": "motions/m01_nod_light.motion3.json", "FadeInTime": 0.5, "FadeOutTime": 0.5 },
        { "File": "motions/m02_nod_heavy.motion3.json", "FadeInTime": 0.5, "FadeOutTime": 0.5 },
        "... 按照对照表顺序排列所有动作"
      ]
    }
  },
  "Groups": [
    {
      "Target": "Parameter",
      "Name": "EyeBlink",
      "Ids": ["ParamEyeLOpen", "ParamEyeROpen"]
    },
    {
      "Target": "Parameter",
      "Name": "LipSync",
      "Ids": ["ParamMouthOpenY"]
    }
  ],
  "HitAreas": [
    { "Id": "HitArea", "Name": "Head" },
    { "Id": "HitArea2", "Name": "Body" }
  ]
}

七、目录结构示例 Copy Chapter

MyModel/
├── MyModel.model3.json          # 模型配置（入口文件）
├── MyModel.moc3                 # 模型数据
├── MyModel.physics3.json        # 物理演算
├── MyModel.pose3.json           # 姿态配置（可选）
├── MyModel.cdi3.json            # 显示信息（可选）
├── MyModel.2048/                # 贴图目录
│   ├── texture_00.png
│   └── texture_01.png           # 如有多张
├── expressions/                 # 表情文件
│   ├── F01.exp3.json
│   ├── F02.exp3.json
│   ├── F03.exp3.json
│   └── F04.exp3.json
└── motions/                     # 动作文件
    ├── idle.motion3.json
    ├── m01_nod_light.motion3.json
    ├── m02_nod_heavy.motion3.json
    └── ...

八、交付清单 Copy Chapter

九、重要注意事项 Copy Chapter

1. 口型参数独占：ParamMouthOpenY 由程序实时驱动口型同步，动作和表情中都不要对此参数设置关键帧
2. 表情命名必须匹配：表情名称必须是 F01、F02... 格式，程序按此名称调用
3. 动作组命名必须匹配：待机组必须叫 Idle，语义动作组必须叫 TapBody
4. TapBody 的顺序很重要：程序按数组下标索引动作，请务必按对照表排列顺序
5. 动作不宜过长：对话场景中动作切换频繁，单个动作建议 2~4 秒
6. Groups 配置不能遗漏：EyeBlink 和 LipSync 两个 Group 必须在 model3.json 中正确声明

Live2D模型制作要求（简化版） (`docs/Live2D模型制作要求（简化版）.md`) Copy Section

Live2D 模型制作要求（简化版）

本文档用于指导外包制作 Live2D 数字人模型。本版为最小可用版本，仅满足基础对话场景。

一、技术规格 Copy Chapter

二、必需参数（Parameters） Copy Chapter

参数 ID 请严格使用 Cubism 默认命名。

三、口型同步（LipSync）要求 Copy Chapter

程序会通过 ParamMouthOpenY 参数实时驱动嘴巴开合，模拟说话口型。该参数的值范围是 0（闭嘴）~ 1（张嘴最大）。

对嘴部建模的要求 Copy Section

• ParamMouthOpenY = 0 时：嘴巴完全闭合，自然状态
• ParamMouthOpenY = 1 时：嘴巴张到最大
• 中间值（0.2~0.8）应有平滑的过渡，不能出现跳变或形变异常
• 嘴部形变需要在 0~1 全范围内看起来自然，因为程序会输出各种中间值

建模细节建议 Copy Section

程序内部会产生以下几种典型开合度，请确保这些值下嘴型看起来合理：

重要约束 Copy Section

• 动作（motion）和表情（expression）中都不要对 ParamMouthOpenY 设置关键帧，否则会与程序的实时口型驱动冲突
• 如果嘴部有多个参数（如 ParamMouthForm 控制嘴型宽窄），可以保留，但 ParamMouthOpenY 必须留给程序独占

四、动作（Motions）要求 Copy Chapter

不需要表情文件，不需要情绪系统。只需要以下动作：

动作组结构 Copy Section

Idle 组（至少 1 个） Copy Section

自然站立的待机循环动画，有轻微呼吸感。

TapBody 组（共 5 个动作） Copy Section

程序按 数组下标（从 0 开始） 调用，顺序必须严格按下表排列：

动作制作要求 Copy Section

• FadeInTime 和 FadeOutTime 设为 0.5 秒
• 动作时长 2~4 秒
• 动作结束后能自然过渡回待机姿态
• 动作中不要包含 ParamMouthOpenY 的关键帧，口型由程序实时驱动，写入会冲突

五、model3.json 结构要求 Copy Chapter

以 MyModel 为例：

{
  "Version": 3,
  "FileReferences": {
    "Moc": "MyModel.moc3",
    "Textures": ["MyModel.2048/texture_00.png"],
    "Physics": "MyModel.physics3.json",
    "Motions": {
      "Idle": [
        { "File": "motions/idle.motion3.json", "FadeInTime": 0.5, "FadeOutTime": 0.5 }
      ],
      "TapBody": [
        { "File": "motions/listen.motion3.json", "FadeInTime": 0.5, "FadeOutTime": 0.5 },
        { "File": "motions/speak.motion3.json", "FadeInTime": 0.5, "FadeOutTime": 0.5 },
        { "File": "motions/think.motion3.json", "FadeInTime": 0.5, "FadeOutTime": 0.5 },
        { "File": "motions/wait.motion3.json", "FadeInTime": 0.5, "FadeOutTime": 0.5 },
        { "File": "motions/greet.motion3.json", "FadeInTime": 0.5, "FadeOutTime": 0.5 }
      ]
    }
  },
  "Groups": [
    {
      "Target": "Parameter",
      "Name": "EyeBlink",
      "Ids": ["ParamEyeLOpen", "ParamEyeROpen"]
    },
    {
      "Target": "Parameter",
      "Name": "LipSync",
      "Ids": ["ParamMouthOpenY"]
    }
  ],
  "HitAreas": [
    { "Id": "HitArea", "Name": "Body" }
  ]
}

关键点：

• Groups 中 EyeBlink 和 LipSync 必须声明，程序依赖这两个组实现自动眨眼和口型同步
• TapBody 数组中的顺序必须是：聆听、说话、思考、等待、打招呼

六、目录结构 Copy Chapter

MyModel/
├── MyModel.model3.json
├── MyModel.moc3
├── MyModel.physics3.json
├── MyModel.2048/
│   └── texture_00.png
└── motions/
    ├── idle.motion3.json
    ├── listen.motion3.json      # 下标 0 - 聆听
    ├── speak.motion3.json       # 下标 1 - 说话
    ├── think.motion3.json       # 下标 2 - 思考
    ├── wait.motion3.json        # 下标 3 - 等待
    └── greet.motion3.json       # 下标 4 - 打招呼

七、交付清单 Copy Chapter

八、注意事项 Copy Chapter

1. ParamMouthOpenY 不要动：动作中不要对嘴巴参数设关键帧，程序实时驱动口型
2. 动作组必须叫 Idle 和 TapBody：程序按这两个名字查找
3. TapBody 顺序不能变：程序按下标 0~4 调用，顺序错了动作就对不上
4. EyeBlink 和 LipSync Groups 不能漏：没有这两个声明，自动眨眼和口型同步不会生效

MCP外部调用接口 (`docs/MCP外部调用接口.md`) Copy Section

MCP 工具外部调用接口

本文整理 Fay 内置 MCP 管理服务（默认端口 5010）的外部调用接口，覆盖 MCP 工具调用与预启用工具调用。

基础信息 Copy Chapter

• Base URL: http://127.0.0.1:5010
• Content-Type: application/json

MCP 工具调用接口 Copy Chapter

调用指定服务器工具 Copy Section

POST /api/mcp/servers/{server_id}/call

请求体示例：

{
  "method": "tool_name",
  "params": {
    "key": "value"
  },
  "is_prestart": false
}

说明：

• is_prestart=true 会跳过工具启用状态检查（用于预启用调用）。

调用工具（自动选择在线服务器） Copy Section

POST /api/mcp/tools/{tool_name}

请求体示例：

{
  "key": "value"
}

获取指定服务器工具列表 Copy Section

GET /api/mcp/servers/{server_id}/tools

获取在线服务器工具列表（聚合） Copy Section

GET /api/mcp/servers/online/tools

预启用工具调用接口 Copy Chapter

配置预启用工具 Copy Section

POST /api/mcp/servers/{server_id}/tools/{tool_name}/prestart

请求体示例：

{
  "enabled": true,
  "params": {
    "query": "{{question}}"
  },
  "include_history": true,
  "allow_function_call": false
}

获取可运行的预启用工具列表 Copy Section

GET /api/mcp/prestart/runnable

调用单个预启用工具（自动连接服务器） Copy Section

POST /api/mcp/servers/{server_id}/prestart/{tool_name}/call

请求体示例：

{
  "params": {
    "query": "{{question}}"
  },
  "question": "用户问题",
  "keep_connection": true
}

批量调用所有预启用工具（自动连接服务器） Copy Section

POST /api/mcp/prestart/call

请求体示例：

{
  "question": "用户问题",
  "keep_connection": true,
  "server_ids": [1, 2],
  "tool_names": ["tool_a", "tool_b"]
}

说明：

• question 必填，用于替换 params 中的 {{question}} 占位符。
• server_ids 与 tool_names 为空时表示对全部预启用工具生效。

Prompt设计文档 (`docs/Prompt设计文档.md`) Copy Section

Fay Prompt 设计文档

提示：使用 AI IDE 对 Fay 进行 Prompt 改造时，可以让 AI 参考 docs/Prompt设计文档.md

本文档说明 Fay 数字人系统中各类 Prompt 的设计与大小模型协作机制。

1. 架构总览 Copy Chapter

Fay 采用 闲聊判断器 + 工具循环 + 最终回复 的三段式架构。根据是否配置大模型，自动在双模型模式和单模型模式之间切换：

所有面向用户的文本始终由小模型流式输出。大模型只在双模型模式的工具循环中工作，从不直接面向用户。

1.1 Prompt 类型与功能 Copy Section

1.2 调用次数对比 Copy Section

2. 工作流程 Copy Chapter

2.1 整体流程 Copy Section

用户输入（文字/语音）
    ↓
预处理：加载系统 Prompt、检索关联记忆、执行预启动工具、加载对话历史、加载 MCP 工具
    ↓
┌─────────────────────────────────────────────────────────┐
│  检查 ExecutionManager 状态                              │
│  ├─ 情况1：有已完成的后台结果 -> 小模型基于结果生成最终回复  │
│  ├─ 情况2：有 RUNNING 后台任务 -> 小模型做意图分类         │
│  └─ 情况3：无后台任务 -> 走正常流程                       │
└─────────────────────────────────────────────────────────┘
    ↓ (情况3)
┌─────────────────────────────────────────────────────────┐
│  闲聊判断器（小模型，流式 JSON）                          │
│  ├─ {"action": "finish", "message": "..."}  → 流式输出   │
│  └─ {"action": "tool", "keyword": "..."}    → 提交工具执行 │
└─────────────────────────────────────────────────────────┘
    ↓ (action == "tool")
┌─────────────────────────────────────────────────────────┐
│  工具循环（双模型：大模型后台 / 单模型：小模型同步）       │
│  while tool_results < max_steps:                         │
│    1. 执行工具 → spec.executor(args)                     │
│    2. 决策下一步 → LLM.invoke(next_step_messages)        │
│    3. 解析 JSON：tool → 继续 / finish → 跳出              │
└─────────────────────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────────────────────┐
│  最终回复（小模型，流式）                                 │
│  基于工具结果生成自然语言回复，写入原始会话流              │
└─────────────────────────────────────────────────────────┘
    ↓
异步后处理：记忆重要性评估、对话记忆存储
    ↓
定时任务：用户画像分析（11:30）、每日反思（23:00）

2.2 关键文件:行号 Copy Section

3. Prompt 示例 Copy Chapter

3.1 系统 Prompt 示例 Copy Section

系统 Prompt 由用户在配置文件中定义（GUI 可以管理），用于设定 AI 的人设：

**系统设定**
你是一个名叫 Feifei 的数字人助手。你性格温柔、善解人意，说话简洁明了。
你会用亲切的语气与用户交流。
---

3.2 闲聊判断器 Prompt Copy Section

System Message 核心（_build_judge_messages）：

你是一个闲聊判断器。判断用户的话是不是闲聊，请严格输出合法 JSON，不要输出其他内容。

输出格式只有两种：
1. 是闲聊: {"action": "finish", "message": "你的回复内容"}
2. 不是闲聊: {"action": "tool", "keyword": "提取的搜索关键词"}

什么是闲聊（输出 finish）：
- 打招呼：你好、hi、早上好
- 情绪表达：我好开心、今天好累
- 感谢道别：谢谢、再见、拜拜
- 简单确认：好的、收到、明白了

什么不是闲聊（输出 tool）：
- 问任何具体事物/概念：XX是什么、你知道XX吗
- 要求查询/获取/阅读内容
- 提到任何产品名、项目名、专有名词
- 任何你需要查资料才能准确回答的问题

不确定时 -> 输出 tool

附加内容：系统 Prompt + 关联记忆 + 可用工具名 + 知识库主题 + 预启动工具结果 + 历史 + 对话历史

输出示例：

{"action": "finish", "message": "你好呀！有什么我可以帮你的吗？"}

{"action": "tool", "keyword": "课程A"}

3.3 工具循环 Prompt Copy Section

System Message 核心（_build_execution_next_step_messages）：

你是一个任务执行器，负责逐步调用工具完成用户请求。请严格输出合法 JSON。

输出格式只有两种：
1. 还需要调用工具: {"action": "tool", "tool": "工具名", "args": {...}}
2. 任务已完成: {"action": "finish", "message": "简短总结执行结果"}

判断规则：
- 对照用户的原始请求，检查是否所有要求都已满足
- 【严格遵守】调用前先看【已完成的工具调用】列表，凡是已经成功执行过的"同名+同参数"调用，绝对不要再调一次

搜索策略：
- 如果 kb_search 的结果不够相关，换关键词重试
- 可以用 kb_list_sources 查看所有课程列表

附加内容：人设 + 关联记忆 + 观察 + 预启动工具结果 + 已完成工具摘要 + 对话历史

输出示例：

{"action": "tool", "tool": "kb_search", "args": {"query": "课程A"}}

{"action": "finish", "message": "已找到课程A的内容：..."}

3.4 最终回复 Prompt Copy Section

System Message 核心（_auto_reply_after_execution 内的精简 prompt）：

你是一个友好的助手。你已经告诉用户"我来帮你查一下，稍等…"，现在工具执行完毕。
请基于以下工具执行结果回答用户，不要再重复"我来查一下"之类的过渡语，直接给出答案。

**用户消息**: {user_request}
**实际执行的操作**: {tool_call_details}
**工具执行结果**: {tool_context}

请基于工具结果直接回答，用日常口语，不要说'工具调用'等技术术语。回复简洁，3-5句话即可。

输出示例：

课程A的内容是……（基于工具结果的口语化总结）

4. 单模型模式 vs 双模型模式 Copy Chapter

4.1 单模型模式（`big_model_engine` 留空） Copy Section

用户输入
    ↓
闲聊判断器（小模型，流式）→ finish 直接回复
    ↓ (tool)
同步工具循环（小模型，最多 30 步）
    ↓
最终回复（小模型，流式）

特点：

• 不开后台线程，工具循环在 question() 调用栈内同步执行
• 用户会等待工具循环完成才看到最终回复
• 不走 ExecutionManager 状态机，无 on_complete 回调
• 适合只有一个模型实例的部署（如本地小模型）

4.2 双模型模式（配置了 `big_model_engine`） Copy Section

用户输入
    ↓
闲聊判断器（小模型，流式）→ finish 直接回复
    ↓ (tool)
exec_mgr.submit() → 后台线程启动
    ↓
question() 立即返回 ""（前端通过 stream 接收异步回复）
    ↓ (后台线程)
工具循环（大模型，最多 30 步）
    ↓
on_complete 回调 → _auto_reply_after_execution
    ↓
最终回复（小模型，流式，写入原始会话流）

特点：

• 工具循环在后台线程执行，不阻塞 question()
• 大模型负责工具决策，小模型负责最终回复
• 每用户最多 1 个 RUNNING 任务（ExecutionManager.submit 拒绝重复）
• 后台任务运行中用户又发消息 → 意图分类（5 类：update_task / query_progress / cancel_task / new_task / normal_chat）

5. 特殊标签处理 Copy Chapter

5.1 `` 标签 Copy Section

5.2 `` 标签 Copy Section

6. 最佳实践 Copy Chapter

6.1 系统 Prompt 编写建议 Copy Section

• 明确定义 AI 的名称、性格特点
• 设定说话风格和语气
• 指定对用户的称呼方式
• 避免过长，控制在 200 字以内

6.2 工具设计建议 Copy Section

• 工具描述要清晰，让 LLM 能准确判断何时使用
• 参数说明要完整，包含类型和示例
• 返回结果要简洁，便于 LLM 理解和转述

6.3 预启动工具使用建议 Copy Section

• 用于获取实时上下文（如时间、天气、用户状态）
• 配置 include_history: true 可让结果在多轮对话中持续可见
• 避免预启动工具执行时间过长，影响响应速度

6.4 单模型 vs 双模型选择 Copy Section

• 单模型模式：本地部署小模型、低成本场景、不需要复杂工具循环
• 双模型模式：云服务部署、需要强工具调用能力（如 MiniMax-M2.7、gpt-4o）、希望工具循环不阻塞用户

Fay Vs Harness Memory (`docs/fay_vs_harness_memory.md`) Copy Section

Fay 与 Harness Agent 的记忆机制对比

写作时间：2026-04-27。"Harness agent" 指 Anthropic Claude Code 这一类"为开发者准备的通用代理脚手架"，下文以 Claude Code 为代表。Fay 是为数字人场景设计的开源 agent 框架——它的记忆机制不是给开发者用的工程辅助工具，而是支撑一个长期陪伴主体的认知底座。

核心结论先放上：

• Harness agent 把"开发者协作记忆"做透了，Fay 学了它的元数据组织、来源归因、规则通道、自描述这套"记忆治理"经验；
• 但数字人场景的诉求与 IDE 场景根本不同——长期陪伴、多用户隔离、跨会话语义检索、自动反思、自动画像、多模态状态、跨领域外部协作；
• 这些诉求 harness agent 并不打算解决，Fay 才是数字人场景下记忆机制的正确形态。

一、Fay 从 harness agent 学到了什么 Copy Chapter

Fay 的记忆底座来自斯坦福 Generative Agents 的 memory_stream：三种节点 + 三因子打分 + 反思机制。但 Claude Code 这一年的演进里把"长期记忆怎么对外协作"这件事打磨得很到位，Fay 这次记忆改造里就直接搬了几条它的设计经验：

1.1 用前缀命名空间组织 tag，而不是新增枚举字段 Copy Section

Claude Code 的 feedback 记忆文件里，每条记忆带 YAML frontmatter——name / description / type: feedback / originSessionId。它没有为"feedback 是不是规则、是不是偏好、属于哪个项目"再单独建字段，而是用"key：value"风格把维度收敛在元数据里。

Fay 这次没有给 ConceptNode 加 is_rule / is_persistent / domain 一堆布尔字段，而是加了一个 tags: list[str]，用 kind:rule / persistent:true / domain:quant 这种命名空间式的前缀承载所有维度。新增维度不改 schema，反思继承 tag 也是按前缀过滤——这套思路直接对标了 harness 的做法。

1.2 来源归因（source attribution） Copy Section

Claude Code 的每条 feedback 都记 originSessionId，让"这条规则是哪次对话留下的"可追溯。Fay 这次在 tag 里固定预留了 source: 命名空间——source:claude_code / source:cursor / source:fay_self / source:fay_reflection / source:user。同一条记忆在反思、检索、调试时都能立刻看出来源，不会出现"这条规则是谁写的"这种盲区。

1.3 persistent 标志与"长期规则"通道 Copy Section

Claude Code 的 MEMORY.md 是 auto-loaded 的——每次会话开始自动注入。这种"无条件加载"的语义让"长期约束"和"具体事件"在物理上分开。

Fay 借鉴了这个区分：tag 里专门有 persistent:true，并给 service 层加了 get_active_rules() 函数，专门返回 kind:rule + persistent:true 的节点。外部 agent 在每次开新任务前调一下，就拿到一份等效于 MEMORY.md 的"必须遵守的清单"。

1.4 schema 自描述工具 Copy Section

Claude Code 的 memory 系统有一个隐含但关键的体验：约定是公开的、可发现的。第三方工具看到一个 feedback 文件就知道它的字段是什么含义。

Fay 把这条做成了显式接口——memory_get_schema() MCP 工具会返回 kind 枚举与 tag 命名空间约定。任何外部 agent（Claude Code、Cursor、自定义工具）在不熟悉参数时调用一次，就能拿到"该填什么、有什么约束"的完整说明。这是 Fay 不让外部 agent 乱写 tag 的主要保险。

1.5 append-only + 周期性 consolidation Copy Section

Claude Code 的实践：会话过程中一直 append（消息日志、TodoWrite、feedback 文件），到容量上限时由 compaction 把历史压缩成 summary 注入下一段。

Fay 这次确认了同样的节奏：写入路径只 append 不修改（4 条写入路径都走 append_prepared_node），每天 23:00 由 perform_daily_reflection 把零散事件 consolidate 成 reflection 节点。reflection 节点继承业务 tag 但覆盖打 kind:insight + source:fay_reflection，相当于一次结构化的 compaction。

1.6 index/detail 分层 Copy Section

Claude Code 的 MEMORY.md 是个 index，里面是指向 feedback_xxx.md 等详细文件的链接，主索引短，详情分文件。

Fay 在用户档案上对应同样的模式：T_Member.user_portrait 是简短画像（1000 字以内的 LLM 总结），而 memory_stream 里 nodes.json 是完整明细。检索时先看 portrait 拿"这个人是谁"，再用语义检索拿具体事件。

二、数字人场景下，Fay 是更合适的形态 Copy Chapter

这一节是本文的重点。 Harness agent 的目标是辅助开发者写代码——它面对的是一个键盘前的工程师、一个仓库、一段会话；记忆机制只要让"上下文不丢"就够了。

Fay 的目标完全不同：承载一个会陪伴用户多年、会跨多种场景工作、会随时间成长的数字人主体。它面对的是一个老人、一个家庭、一个学生、一支量化团队——记忆要做的不是"帮 agent 别忘事"，而是让数字人成为一个有人格、有关系、有时间纵深的存在。

下面这张对比表，第三列是关键——它直接说明每一项设计差异背后，数字人场景为什么必须选 Fay 这条路：

2.1 一个具象场景：harness agent 撑不起，Fay 撑得起 Copy Section

想象一个真实数字人产品——居家养老陪护机器人 "小慧"，部署在一个家庭里 365 天。

这是 harness agent 与 Fay 的根本分野——前者活在一次会话里，后者活在一段关系里。

2.2 一句话定位 Copy Section

Harness agent 的记忆，是为了让 agent 不忘事；Fay 的记忆，是为了让数字人成为一个"人"。

三、两个仓库 Copy Chapter

想动手验证：克隆 Fay，启动 faymcp/mcp_server.py，用 Claude Code 通过 SSE 连上端口 8765，就能体会"外部 harness agent 通过 MCP 把记忆回写到 Fay"这条新通道。

两个仓库各司其职：Claude Code 让开发者更高效地写代码，Fay 让你的数字人活得更长、更真。

Memory Mechanism (`docs/memory_mechanism.md`) Copy Section

Fay 记忆机制总览（2026-04-27）

本文档描述 Fay 当前默认的认知记忆机制。涉及代码：
llm/nlp_cognitive_stream.py + genagents/modules/memory_stream.py

• core/memory_service.py + core/member_db.py + faymcp/mcp_server.py。

旧版精简说明见 memory_module.md，本文为增补与扩展。

一、三层存储 Copy Chapter

ChromaDB 仅用于本地知识库（doc 检索），不参与记忆流。

二、节点的数据结构 Copy Chapter

每个 ConceptNode 包含：

node_id, node_type, content, importance, datetime,
created (time_step), last_retrieved, pointer_id,
tags  ← 业务标签列表

node_type 只有三种：observation / conversation / reflection。

tags 走命名空间约定：

kind:<decision|event|fact|rule|error|insight|preference|observation>
source:<fay_self|claude_code|cursor|user|fay_reflection|...>
persistent:true              ← 长期保留标志，rule 必带
domain:<quant|homecare|education|life_assistant|home_automation|companion|...>
strategy:<策略名>  symbol:<标的>  session:<会话ID>  schedule:<表达式>  date:<YYYY-MM-DD>

2.1 节点完整事例 Copy Section

事例 A：普通对话（conversation，无 tag）

{
  "node_id": 142,
  "node_type": "conversation",
  "content": "主人：今天股市怎么样？\nFay：A股震荡走低，沪指跌 0.8%。",
  "importance": 4,
  "datetime": "2026/04/27 10:23:15",
  "created": 142,
  "last_retrieved": 142,
  "pointer_id": null,
  "tags": []
}

当前对话路径暂未打 tag，反思阶段无法从中继承业务标签。

事例 B：外部 agent 写入的事件（event）

{
  "node_id": 156,
  "node_type": "observation",
  "content": "上午 10:30 AAPL 突破日内高点 187.4，breakout 策略买入信号触发",
  "importance": 7,
  "datetime": "2026/04/27 10:30:42",
  "created": 156,
  "last_retrieved": 156,
  "pointer_id": null,
  "tags": [
    "domain:quant",
    "kind:event",
    "session:2026-04-27-am",
    "source:claude_code",
    "strategy:breakout",
    "symbol:AAPL"
  ]
}

事例 C：长期规则（rule，必带 persistent:true）

{
  "node_id": 88,
  "node_type": "observation",
  "content": "每小时整点检查所有持仓策略是否有未触发的止损单",
  "importance": 9,
  "datetime": "2026/04/26 09:00:00",
  "created": 88,
  "last_retrieved": 130,
  "pointer_id": null,
  "tags": [
    "domain:quant",
    "kind:rule",
    "persistent:true",
    "schedule:hourly",
    "source:user"
  ]
}

事例 D：用户偏好（preference）

{
  "node_id": 31,
  "node_type": "observation",
  "content": "用户希望晚上 22:00 之后不要主动发起对话",
  "importance": 8,
  "datetime": "2026/04/15 22:13:05",
  "created": 31,
  "last_retrieved": 105,
  "pointer_id": null,
  "tags": [
    "domain:life_assistant",
    "kind:preference",
    "persistent:true",
    "source:user"
  ]
}

事例 E：失败事件（error）

{
  "node_id": 173,
  "node_type": "observation",
  "content": "买入信号在 AAPL 涨停封板后仍触发，导致 0 成交但占用了风控额度",
  "importance": 8,
  "datetime": "2026/04/27 14:02:11",
  "created": 173,
  "last_retrieved": 173,
  "pointer_id": null,
  "tags": [
    "domain:quant",
    "kind:error",
    "session:2026-04-27-pm",
    "source:claude_code",
    "strategy:breakout",
    "symbol:AAPL"
  ]
}

事例 F：居家养老观察（event，跨场景示例）

{
  "node_id": 412,
  "node_type": "observation",
  "content": "老人晨起血压 158/95，比上周平均高 12 个点",
  "importance": 7,
  "datetime": "2026/04/27 07:15:00",
  "created": 412,
  "last_retrieved": 412,
  "pointer_id": null,
  "tags": [
    "domain:homecare",
    "kind:event",
    "source:elderly_monitor",
    "date:2026-04-27"
  ]
}

事例 G：Fay 自动生成的反思（reflection，继承+追加 tag）

{
  "node_id": 201,
  "node_type": "reflection",
  "content": "用户在 AAPL 上的 breakout 策略本周 3 次假突破亏损，可能需要加 ATR 滤波或限制涨停后入场",
  "importance": 8,
  "datetime": "2026/04/27 23:00:14",
  "created": 201,
  "last_retrieved": 201,
  "pointer_id": [156, 162, 173],
  "tags": [
    "domain:quant",
    "kind:insight",
    "source:fay_reflection",
    "strategy:breakout",
    "symbol:AAPL"
  ]
}

反思节点的 tag 由 MemoryStream.reflect() 自动从 pointer_id 指向的源节点继承（去掉 session:、date:、schedule: 前缀），再覆盖为 kind:insight + source:fay_reflection。

三、写入路径（共 4 条） Copy Chapter

写入的统一管线：

1. 锁外 算 importance（LLM 评分 0–10）和 embedding（API 向量）
2. 持锁 agent_lock，把节点 append 到 memory_stream.seq_nodes，并写 embeddings[content]
3. 内部 4 条只更新内存；只有 core.memory_service.remember 会立即落盘
4. 每天 00:00 save_agent_memory 全量 dump 一次 nodes.json + embeddings.json

四、检索路径 Copy Chapter

唯一入口：MemoryStream.retrieve(focal_points, time_step, ...)。

打分公式：

score = recency_w · 衰减(last_retrieved)
      + relevance_w · cosine(query_embedding, node_embedding)
      + importance_w · normalized(importance)

默认权重 [0, 1, 0.5]（纯相关度+重要度），但对话流用的是 [0.8, 0.5, 0.5]（加重时间权重）。

新增 tag 过滤：filter_tags_all（AND）/ filter_tags_any（OR）。

对话时拼提示词的过程（见 nlp_cognitive_stream.py 2329 行附近）：

1. 用当前用户输入做 query
2. 一次 retrieve 拉 30 条候选
3. 按 node_type 分成三段：观察记忆 / 对话记忆 / 反思记忆，每段最多 10 条
4. 拼成 markdown，塞进系统 prompt 的 memory_context

五、定时任务（`init_memory_scheduler`） Copy Chapter

启动时还会：

• precheck_embedding_dimensions — 修复维度不一致的旧 embedding
• create_agent 默认 username 创建主 agent

六、对外接口 Copy Chapter

MCP 的 7 个工具：

• memory_remember — 写入（含 kind 枚举 + persistent + extra_tags）
• memory_search — 语义检索 + tag 过滤
• memory_get_recent — 时间倒序最近 N 条
• memory_get_active_rules — 所有 kind:rule + persistent:true
• memory_get_reflections — 最近反思
• memory_get_user_profile — portrait + extra_info
• memory_get_schema — kind 枚举与 tag 命名空间，外部 agent 拿来对齐参数

七、典型流程示例 Copy Chapter

7.1 内部场景（Fay 主进程内） Copy Section

例 1：普通用户聊天

用户："今天天气真不错"
└─→ Fay 主流程: question() 拿到内容
    ├─→ 锁外算 importance/embedding
    ├─→ remember_conversation_thread 异步写一条 conversation 节点（content="主人：...\nFay：..."）
    └─→ 当前提示词组装时调 memory_stream.retrieve(content)
         ├─→ 取回 30 条候选，分三段塞进 system prompt 的 memory_context
         └─→ LLM 据此生成回复

当前 conversation 节点不带 tag，反思阶段无法继承。

例 2：用户主动表达偏好（理想路径）

用户："以后晚上 10 点之后别叫我"
└─→ Fay 听到后做出回应（写 conversation 节点）
    └─→ Fay 应该 同时调 core.memory_service.remember(
            content="用户希望晚上 22:00 之后不要主动发起对话",
            kind="preference",
            persistent=True,
            source="fay_self",
            extra_tags=["domain:life_assistant"]
        )
        └─→ 写入一条 observation 节点（事例 D）

当前 Fay 还没自动做这件事，需要后续在对话流里加"指令识别 → 调 service" 的钩子。

例 3：每天 22:35 用户画像分析

schedule.run_pending() 触发 perform_user_portrait_analysis()
└─→ 读 T_Member.user_portrait（旧画像）
└─→ 抽取最近 N 条 conversation 节点
└─→ 调 LLM，按 6 个维度（含"与 Fay 的关系"）生成新画像，1000 字以内
└─→ 写回 T_Member.user_portrait

例 4：每晚 23:00 反思

schedule.run_pending() 触发 perform_daily_reflection()
└─→ 选若干"主题锚点"（anchor）
    └─→ 对每个 anchor 调 memory_stream.reflect(anchor)
         ├─→ 内部 retrieve 出 120 条相关节点
         ├─→ LLM 提炼为 5 条 reflection 文本
         ├─→ 算 importance + embedding
         └─→ 调 _add_node 写入，tags 自动从源节点继承+覆盖
              结果如事例 G

7.2 外部场景（外部 agent 通过 MCP 调用） Copy Section

外部 agent 通过 SSE 连接 http://<fay_host>:8765/sse，按 MCP 协议调用 memory_* 工具。

例 5：Claude Code 开新策略任务前先拉规则 & 写 session 开始

[Claude Code 启动新会话]
1) call memory_get_active_rules(username="trader_zhang")
   ← 返回 [事例 C, 例 8 的 homecare 规则等]
   → Claude Code 把规则塞进自己的 system prompt

2) call memory_remember(
      content="开始 2026-04-27 上午盘量化执行任务",
      kind="event",
      source="claude_code",
      extra_tags=["domain:quant", "session:2026-04-27-am"],
      username="trader_zhang"
   )
   ← {"ok": true, "node_id": 155, ...}

例 6：执行过程中实时回写事件

[策略触发 → Claude Code 调 broker API → 成交]
3) call memory_remember(
      content="上午 10:30 AAPL 突破日内高点 187.4，breakout 策略买入信号触发",
      kind="event",
      source="claude_code",
      extra_tags=["domain:quant", "strategy:breakout", "symbol:AAPL", "session:2026-04-27-am"],
      username="trader_zhang"
   )
   → 节点 156 落地（事例 B）

[发现策略 bug]
4) call memory_remember(
      content="买入信号在 AAPL 涨停封板后仍触发，导致 0 成交但占用了风控额度",
      kind="error",
      source="claude_code",
      extra_tags=["domain:quant", "strategy:breakout", "symbol:AAPL", "session:2026-04-27-pm"],
      username="trader_zhang"
   )
   → 节点 173 落地（事例 E）

例 7：第二天另一个会话回顾

[次日 Claude Code 新会话开启]
1) call memory_search(
      query="breakout 策略最近问题",
      filter_tags_all=["domain:quant", "strategy:breakout"],
      n=10,
      username="trader_zhang"
   )
   ← 返回:
      - 节点 173 (kind:error 假突破)
      - 节点 201 (kind:insight 反思——"3 次假突破，建议加 ATR 滤波")
      - 节点 156 (kind:event 当时的买入)

2) Claude Code 据此调整策略实现，再写一条:
   call memory_remember(
      content="已在 breakout 策略加 ATR(14)>1.5 滤波，规避涨停后假突破",
      kind="decision",
      source="claude_code",
      extra_tags=["domain:quant", "strategy:breakout"],
      username="trader_zhang"
   )

例 8：居家养老监测脚本（非交易场景）

[ESP32 血压计 → 中转脚本 → MCP]
call memory_remember(
   content="老人晨起血压 158/95，比上周平均高 12 个点",
   kind="event",
   source="elderly_monitor",
   extra_tags=["domain:homecare", "date:2026-04-27"],
   username="grandpa_li"
)
→ 节点 412 落地（事例 F）

[家属在 app 设规则]
call memory_remember(
   content="爷爷每天早晨必须测血压，9 点前没数据要报警",
   kind="rule",
   persistent=True,
   source="family_app",
   extra_tags=["domain:homecare", "schedule:daily"],
   username="grandpa_li"
)
→ 一条 persistent rule 入库

[当晚反思]
Fay 23:00 reflect → 检索 grandpa_li 节点
→ 生成 insight: "老人本周血压偏高 3 次，建议家属安排复查" (kind:insight, domain:homecare)

例 9：Cursor 修 bug 后回写

[Cursor 修了一个内存泄漏]
call memory_remember(
   content="发现 stream_manager 在 ws 异常断开时未释放 buffer，已改为 try/finally 关闭",
   kind="fact",
   source="cursor",
   extra_tags=["domain:engineering", "module:stream_manager", "session:fix-memleak-1"]
)

[同时记录决策]
call memory_remember(
   content="Fay 项目里所有 ws 路径都要在 finally 里 close buffer",
   kind="rule",
   persistent=True,
   source="cursor",
   extra_tags=["domain:engineering"]
)

例 10：教育辅导 agent

[家教 agent 完成一节课]
call memory_remember(
   content="小明今天独立完成 5 道一元二次方程，全部正确",
   kind="fact",
   source="tutor_bot",
   extra_tags=["domain:education", "subject:math", "topic:quadratic_eq"],
   username="xiaoming"
)

[下次开课前]
call memory_search(
   query="小明数学进度",
   filter_tags_all=["domain:education", "subject:math"],
   username="xiaoming"
)
→ 拉到上一次的"已掌握一元二次方程" → 这次直接进二次函数

例 11：跨 agent 协作 — Claude Code 写规则、Fay 自身遵守

1) Claude Code 调:
   memory_remember(
      content="每小时整点检查所有持仓策略是否有未触发的止损单",
      kind="rule",
      persistent=True,
      source="user",
      extra_tags=["domain:quant", "schedule:hourly"]
   )

2) Fay 主进程的某个内置 agent（如调度器）
   每小时启动时调:
   core.memory_service.get_active_rules(username)
   ← 返回所有 persistent rules，包含上面这条
   → 调度器据此触发巡检流程

这是"MCP 工具同时向 Fay 自身暴露"的核心价值：写入与读取走同一条 service 层，外部 agent 写、内部 agent 读，无 sync 问题。

八、还没解决的事 Copy Chapter

1. 对话/观察线程没打 tag：反思继承不到东西，需在 remember_conversation_thread / remember_observation_thread 里加默认 tag（如 source:fay_conversation、source:fay_observation）
2. 冷热分层缺失：节点数大了之后 retrieve 全扫，没有按 importance + 年龄做分层或聚类收敛
3. 上下文压缩缺失：retrieve 回来的节点直接全文进 prompt，没有 summary 压缩层
4. 端到端联调未跑：MCP 工具刚加，需要：启动 Fay → Claude Code 连 SSE → 调 memory_get_schema / memory_remember / memory_search，确认节点正确落盘

九、文件位置速查 Copy Chapter

Memory Module (`docs/memory_module.md`) Copy Section

Fay Memory Module

本说明描述当前默认的认知记忆实现。适用于 llm/nlp_cognitive_stream.py + genagents/modules/memory_stream.py 这条路径。

记忆节点 Copy Chapter

• 节点类型：observation（观察）、conversation（对话）、reflection（反思）
• 字段：
  • node_id: 递增整数
  • node_type: 节点类型
  • content: 记忆内容（纯文本，已去除 /）
  • importance: 整数重要度
  • datetime: 节点创建时间，格式 YYYY/MM/DD HH:MM:SS；旧节点可能为空
  • created / last_retrieved: 时间步（整型）
  • pointer_id: 反思节点指向的源节点列表 ID
• 创建：
  • 观察：remember_observation_thread / record_observation
  • 对话：remember_conversation_thread（问答格式：{user}：{问}\n{agent}：{答}，其中 user/user 会写成“主人”）
  • 反思：MemoryStream.reflect 生成
  • 写盘策略：即时不落盘，按定时/退出在 llm/nlp_cognitive_stream.py::save_agent_memory 才写入
• Embedding：memory_stream._add_node 创建时生成；维度不符时检索阶段会临时重算（内存中，不立即落盘）

检索与提示词 Copy Chapter

• 检索：MemoryStream.retrieve 按 recency/relevance/importance 组合权重取回；关联记忆一步检索 curr_filter="all" 后按类型分段展示。
• 展示格式：检索结果中若节点有 datetime，前缀 "[{datetime}] "；无时间则不展示时间。
• 关联记忆段落无“关联记忆”标题，直接列出各类型小节（观察、对话、反思）。

配置与隔离 Copy Chapter

• memory.isolate_by_user: 打开后记忆目录按用户名隔离。

运行时要点 Copy Chapter

• 文字接口 no_reply=true 且有 observation 时：只记观察，不回复；无 messages 且有 observation 会强制 no_reply=true。
• no_reply=false 的普通对话：问题/回答会写入对话记忆；observation 若存在也会写入观察记忆。
• Prompt 打印：已关闭（_log_prompt 是空操作）。

文件位置 Copy Chapter

• 核心逻辑：llm/nlp_cognitive_stream.py
• 记忆结构：genagents/modules/memory_stream.py
• 定时保存：llm/nlp_cognitive_stream.py::save_agent_memory
• 记忆数据：memory/memory_stream/nodes.json, embeddings.json, meta.json

--- METRICS ---

• Files Extracted: 10
• Estimated Token Budget: ~13632 tokens
• Canonical Reference: https://codewiki.google/github.com/xszyou/Fay