Files
CyberGril/README.md
T
mobai 1012d8bb79 chore: project foundation
Contracts (the shared language):
- percept / state / context / utterance / render / audio / capabilities
- Capability model instead of vendor schemas (see below)

Providers (capability-based abstraction):
- LLM + Embedding: OpenAI-compatible shape IS the standard, adopted directly
- ASR: internal contract is an event stream (partial -> final), because
  /v1/audio/transcriptions has no partial and dialogue needs it for
  endpointing. OpenAI adapter degrades to supports_partial=False.
- TTS: internal contract carries tags/emotion/style, because
  /v1/audio/speech has no paralinguistics and [laughter]/[breath] are
  the core of feeling alive. Unsupported providers are stripped AND
  reported via Degradation -- silent degradation is forbidden.
- Avatar: no de-facto standard, custom RenderCmd protocol driven by State.

Core:
- mood: dynamical system, slow variables, negativity bias (grudge),
  numbing after prolonged negativity
- bazi: four pillars -> numeric vector; 'ming' is data, not prose
- projection: phi, system event -> in-world statement; uncovered events
  are counted as projection gaps

Storage:
- SQLite schema, three memory layers, dyad ledger
- accessibility floor 0.03 (not 0): forgettable but still there

Config split:
- models.yaml is the ONLY place model versions live
- character.yaml holds world rules / emotion params, no version numbers

58 tests pass; ruff clean.
2026-10-19 20:08:52 +08:00

7.1 KiB
Raw Blame History

CyberGril

一个有自己世界的赛博伴侣。

不是聊天机器人。区别在于:它在你不说话的时候也在运行。


它是什么

一个单用户、本地优先、常驻的存在,通过一层"膜"与你通信:

  • 有自己的时钟 —— 无输入时仍在演化、仍有生活
  • 情绪是动力学系统 —— 慢变量、有惯性、有代价(会心情不好)
  • 记忆有形状 —— 三层结构,会遗忘,且遗忘有下限
  • 关系是一等实体 —— 信任、债务、未修复的事
  • 本体不可谈判 —— 立场不因任何对话、情绪、施压而改变

三层不可混淆的东西

层 载体 变化速度 谁能改
命 bazi_core.derived 几乎不变 只有整合器,每次 ±0.02,且留痕
运 fortune_period 按周/月 排盘
状态 State (v/a/d/e) 按秒/分 tick 循环

混掉任何两层,角色就会失真:

  • 命被对话改 → 人设漂移,变成一个讨好你的东西
  • 状态被写成描述 → 模型自己编情绪,动力学失效

架构

contracts/   数据契约 —— 全项目唯一的共同语言
providers/   模型接入 —— 按能力建模
core/        状态核心 —— 独立时钟,不依赖用户输入
memory/      三层记忆 + 遗忘
dyad/        关系账本
config/      models.yaml(版本号) + character.yaml(世界法则)

设计判断(这一节比代码重要)

1. OpenAI 兼容是 adapter,不是标准

对 LLM 和 Embedding,OpenAI 的形状(/v1/chat/completions、/v1/embeddings) 已经是事实标准,内部契约就直接用它。

但对 ASR / TTS / 形象,OpenAI 的形状会砍掉这个项目最需要的能力:

能力 OpenAI 形状的问题 我们的做法
ASR /v1/audio/transcriptions 是「文件进→文本出」,没有 partial;而对话必须要 partial 才能做端点检测 内部契约是事件流(partial → final);OpenAI 适配器作为降级档,supports_partial=False
TTS /v1/audio/speech 只有 text/voice/speed,没有副语言标签;而 [laughter] [breath] 是"像活的"的核心 内部契约带 tags / emotion;不支持的 provider 在 plan() 里显式降级并上报
形象 没有事实标准 自定义 RenderCmd 协议,驱动源必须是 State,不是 LLM 文本

关键机制:静默降级是不允许的。

planned = tts.plan(request)
if planned.lost_paralinguistics:
    # 日志里会出现 [degraded] speech_tags: ...
    ...

静默降级会让你在调优时永远找不到"它为什么不像人了"。

2. 状态必须以数值注入,不能用散文描述

✗ "你现在有点难过"          → 模型会自己发挥,甚至编出更多情绪
✓ v=-0.62 a=0.41 d=0.30    → 模型知道边界
  + visible="低落"
  + constraint="不得声称与此不符的内在状态"

StateBlock 里那个 constraint 字段不是装饰,它是唯一能阻止 模型绕过状态机的机制(外加输出校验与重写)。

3. 遗忘有下限

mem_episodic.accessibility 的下限是 0.03,不是 0。

  • 正常检索拿不到 → 想不起来
  • 情绪线索命中时能捞出来 → 但还在

所有现成框架都是"要么记住要么删除",没有这个中间态。

4. 未修复的事变成行为,不变成台词

✗ "你上次伤害了我"          → 指责,而且廉价
✓ 主动性 -0.1,回复变短      → 它不说,但它不一样了

5. 缺席可以被提及,不能被使用

✗ "我一直在等你,等了好久"   → 制造负罪感,这是操控
✓ "这几天我这边发生了点事"   → 它有自己的世界,不是空转等你

这条写在 core/projection.py 的注释里,也有对应的测试。


快速开始

# 1. 安装
pip install -e ".[dev]"

# 2. 配置
cp .env.example .env
# 编辑 .env 填入 API key(不填也能跑,会回退到 echo provider)

# 3. 跑测试
pytest -q

# 4. 检查配置能被正确加载与校验
python -c "from cybergril import load_settings; print(load_settings('config').character.name)"

默认配置不需要任何 API key 就能跑通测试 —— 因为内置了 echo(LLM)/ scripted(ASR)/ silence(TTS)三个离线 provider。 它们的价值是把接口形状固定下来,让上层可以先跑通再换真后端。


换成真模型

只改 config/models.yaml,不动任何代码。

llm:
  provider: openai_compat
  model: deepseek-v4.1-flash
  base_url: https://api.deepseek.com/v1
  api_key_env: DEEPSEEK_API_KEY

tts:
  provider: cosyvoice        # 需要自己实现这个 adapter,见下
  model: fun-cosyvoice3-0.5b

新增一个 provider 只需要三步:

# 1. 继承对应的基类
class MyTTS(TTSProvider):
    name = "mytts"

    # 2. 诚实地声明能力
    @property
    def capabilities(self) -> Capabilities:
        return Capabilities(
            modality=Modality.AUDIO,
            streaming=Streaming.CHUNKED,
            speech_tags=frozenset({"laughter", "breath"}),
        )

    # 3. 实现 stream()
    async def stream(self, request): ...

# 注册
registry.register("tts", "mytts", MyTTS)

能力必须诚实。 夸大能力会让上层做出错误的规划, 而 plan() 会据此剥掉你其实需要的东西。


配置分层

文件 放什么 什么时候改
config/models.yaml 唯一允许写模型版本号的地方 换模型(每季度复核)
config/character.yaml 世界法则、情绪参数、关系参数 换人格(几乎不动)

两个文件互不污染。这是"防止文档和代码一起过时"的机制。

关于版本号的一个约定:只有 models.yaml 允许写版本号。 代码里所有模型引用走配置,不硬编码。


测试

pytest -q                    # 全部
pytest tests/test_mood.py -v # 情绪动力学
pytest -k degradation -v     # 降级机制

测试守的是设计判断,不是实现细节:

文件 守什么
test_contracts.py 接口形状
test_providers.py 降级必须显式上报
test_mood.py 情绪有惯性;负向恢复更慢
test_bazi.py 命是数值;强弱影响敏感度
test_projection.py 未覆盖事件必须计数;投影不泄漏技术词
test_store.py 遗忘有下限;间隔效应

下一步

地基只包含:契约、provider 抽象、配置、情绪动力学、八字编译、投影、存储 schema、关系账本。

还没有的(按依赖顺序):

  1. core/tick.py —— 四个循环(tick / consolidate / life / reach_out)
  2. memory/retrieval.py —— mood-congruent 检索
  3. memory/consolidation.py —— 整合与身份提升
  4. think/ —— 上下文组装、生成、三道校验
  5. express/ —— TTS 管道、形象、barge-in
  6. api/ —— WebSocket 会话

规格

完整设计见 docs/SPEC.md。

许可

私有项目,未授权。