MetaPact 功能 / 技术分析报告

日期：2026-06-22 ｜分析人：张一章（PM）数据来源：github.com/Lovappen/MetaPact 仓库源码实读（今日 clone，非训练数据）+ README + 抖音作者口播。时效边界：基于今日仓库快照（MIT，约 27★，最近更新约 26 天前）；运行时行为未实测（未真实部署跑通），代码层结论可靠，效果/稳定性为推断。

0. 一句话定性

成人向（NSFW）的 「文件化人格 + 双层记忆 + 定时思念 + 多模态 skill + 多平台投递」AI 陪伴 agent 套件，跑在通用 agent 运行时（OpenClaw / QClaw / HermesAgent）之上。主力角色野木奈子。卖点是"灵魂/记忆全在本地、可版本化"。

1. 架构总览（三层）

层	内容	说明
运行时层	OpenClaw / QClaw / HermesAgent	消息 agent 框架，MetaPact 不自造，是其上的"人格+技能包"
人格 & 记忆层	`nako/agent/` 一组 markdown「灵魂文件」+ `memory/` 目录	核心创新点：persona/记忆/情绪全用文件承载
技能层	`nako/skills/*` 一组 bash 脚本	每个能力=脚本调第三方 API（语音/唱歌/自拍/看图/听音/BLE）
接入/分发	`scripts/cc-connect-*`、`nako-agent-factory/nako-server.py`	多平台 host + LAN 扫码工厂

factory 服务：nako-server.py 在 Linux 起 LAN HTTP（端口 8088），按客户端 IP 建 agent-nako-N、选运行时、生成飞书/微信二维码、流式回显安装日志——即"一台机器给多人扫码开通分身"。

2. 人格系统

灵魂文件（nako/agent/）：SOUL.md(核心人格) / IDENTITY.md(身份卡) / USER.md(用户档案) / AGENTS.md(工作区+启动规约) / HEARTBEAT.md(主动规则) / TOOLS.md(技能速查) / custom.md(用户扩展层)。
启动规约：每次会话强制按序读 SOUL → USER → memory/今日+昨日 →（主会话才读）MEMORY.md，"不问直接做"。
5 阶段好感系统：阶段1初识 → 阶段5永恒，每阶段在 prompt 里完整内嵌语气、亲密度、行为边界、示例台词；NSFW 内容随阶段升级且概率门控（阶段4 5%、阶段5 8%）。
升级不覆盖定制：custom.md 安装器只首建、之后永不碰，AGENTS.md 末尾 @custom.md 引入——干净的"稳定层 vs 用户层"分离。
本质：一套超长结构化 system prompt 的文件化 + 分层，与 Claude Code 自身的 AGENTS.md/memory 范式同构。

3. 长期记忆（重点，对标你的持久记忆项目）

双层记忆：memory/YYYY-MM-DD.md（每日原始日志）+ MEMORY.md（curated 长期记忆，蒸馏精华）。
写入机制：scripts/memory-write.sh --summary "<改了什么>" [--long "<持久事实>"]，滚动更新 MEMORY.md；禁止"心理笔记"，一切要记的写进文件。
上下文隔离（隐私）：MEMORY.md 仅主会话加载，群聊/Discord/有他人的共享会话不加载——防个人信息泄露给陌生人。
状态：好感值 0–100、当前阶段、最后互动时间、memory/heartbeat-state.json。
技术评：是"原始日志 + 人工/自动蒸馏 + 按上下文隔离加载"的纯文件方案。无向量检索——简单可控，但只够"单角色 × 单用户"。

4. 情绪 / 状态 + 主动思念

思念机制（dokidoki/heartbeat）：heartbeat-check.sh 每 30 分钟 cron 跑；思念值 ≥80 → 退出码 1 → 主动给用户发一条。
情绪回血：mood-recovery.sh 收到用户消息时重置思念值 + 回血情绪。
阶段门控频率：阶段1=48h 才心跳一次 → 阶段5=6h；消息 ≤100 字、必含当地时间/天气、避免深夜打扰。
技术评：用"cron + 状态文件 + 阈值"实现"主动联系/情绪"，工程极轻；但"情绪"是规则脚本，不是情感模型。

5. 多模态能力（每个=独立 bash skill，调第三方 API）

能力	实现	依赖
语音 voice	MiniMax TTS（默认 female-tianmei，按情绪调语速）	`MINIMAX_API_KEY` / `VOLCENGINE_API_KEY`
唱歌 sing	MiniMax music-2.6（10–60s）	MiniMax
自拍 selfie	文生图 + 图生视频，参考图保外观一致	`FAL_KEY` / `KIE_API_KEY`
看图 vision	resolve 拿路径 → Read 看图	主模型需视觉
听语音 hearing	STT 转写	STT provider
BLE 互动 dokidoki	蓝牙控制互动设备（成人玩具）	本地 BLE

投递双模式：feishu（OpenClaw 原生直连飞书）vs acp（cc-connect 多平台 host 接管）。TOOLS.md 有大量硬规则：飞书/微信场景必须走自家 nako 脚本，禁用运行时原生 image_generate/tts/video_generate（否则只生成 webchat 媒体，IM 收不到）。

6. 多平台接入

cc-connect（CodeEagle fork）做多平台 host：飞书、微信、Telegram、Slack、Discord、QQ、微博、钉钉、企微、LINE。
安装开关：--with-feishu / --with-weixin / --with-cc-connect / --cc-connect-source auto|npm|lazycat|skip。
绑定方式：agent-factory 扫码（飞书/微信二维码）。

7. 模型路由（技术）

按能力选模型：roleplay 首选（sensenova/SenseChat-Character-Agt 标注最佳；其次 kimi-k2 系列 / glm-4-plus / glm-5 / claude-sonnet-4 / gpt-4o），不命中降级 general，再不行才报错。
config/model-map.yaml 是偏好排序（非硬支持表）；detect-models.sh/map-model.sh 读用户 openclaw.json 的 capabilities 字段优先。
providers-preset.json 预置 zai/glm 等（注意其 cost 字段全 0，是占位非真实计费）。
角色一致性强依赖模型——作者明确推荐商汤 SenseChat-Character-Agt。

8. 部署 / 工程质量

一行安装：curl -fsSL https://cdn.jsdelivr.net/gh/Lovappen/MetaPact@main/install.sh | bash；参数 --runtime openclaw|hermes|qclaw、--with-feishu/--with-weixin、--skip-skills/--skip-models、--non-interactive。
脚本 set -euo pipefail；curl 管道时自 clone 到 temp；装 cron heartbeat。
跨平台：mac / Linux / Windows(PowerShell 7+)。
测试覆盖：tests/ 含 memory-write、heartbeat-state、voice fallback、media-path、windows 兼容、cc-connect 等——工程严谨度高于 27★ 的体感。
文档齐：docs/nako/ install/models/skills/customization/feishu-setup/troubleshooting。

9. 安全 / 隐私 / 合规

正面：灵魂&记忆全本地、可版本化；红线规则（不外泄隐私、trash>rm、破坏性操作先问）；MEMORY.md 上下文隔离防泄露。

风险：

curl | bash 远程执行——装前应审 install.sh，或隔离环境试。
大量第三方 API key 落本地 env（MiniMax/FAL/KIE + 模型 provider）。
微信/飞书为非官方接入（cc-connect）——账号封禁风险，商用尤甚。
NSFW 成人内容 + BLE 成人设备——合规/平台风险高。
27★ 新项目——供应链信任度有限。

10. 对你（PM / AI女友 & 代聊项目）的可借鉴点

记忆架构：daily 原始日志 + curated 长期 + 上下文隔离加载，直接映射你的「持久记忆框架」。但你的目标是百万×万级多对多，需向量召回；MetaPact 纯文件撑不住规模——借"分层+隔离"思想，不借实现。
人格分层：SOUL(稳定) + custom(用户层，升级不覆盖) + 阶段化推进——可用于代聊/AI女友的人格配置与确权。
主动触达：heartbeat 阈值 + cron 的"思念"机制——对应你代聊的"蜂群破冰 / 主动召回"，是个极轻的可抄实现。
多平台投递抽象：feishu / acp 双模式 + "强制走自家脚本"——接入层设计参考。
商业化对照：开源引流 + "心跳元力" App + 硬件（元力2 / 黑洞SE）变现的组合打法。

结论

MetaPact 工程完成度不错，是定位成人向的「文件化人格 + 双层记忆 + 定时思念 + 多模态 + 多平台」陪伴 agent 套件。架构思想（尤其记忆分层与上下文隔离）值得你的持久记忆/AI女友项目借鉴；但成人内容、非官方 IM 接入、curl|bash 与第三方 key 是落地前必须评估的风险，且纯文件记忆无法支撑你规划的百万级多对多规模。建议定位为"架构参考样本"，而非可直接商用的底座。