Flyflor 是一个 Bun + TypeScript 智能体运行时，目标是单文件二进制交付。

核心设计：LLM 负责流体智力，反思沉淀晶体智力（Gem），海马体负责工作记忆与长期记忆图，黑板协作处理复杂任务。

curl -fsSL https://flyflor.dev/install.sh | sh
# 固定版本：
curl -fsSL https://flyflor.dev/install.sh | sh -s -- --version v0.4.0
# 自定义前缀：
curl -fsSL https://flyflor.dev/install.sh | sh -s -- --prefix /usr/local/flyflor
# 更新 / 卸载：
flyflor update -y
curl -fsSL https://flyflor.dev/install.sh | sh -s -- --uninstall

脚本从 GitHub Releases 下载匹配平台的 flyflor-{os}-{arch} 二进制与 flyflor-templates.tar.gz，默认安装到 ~/.flyflor。--uninstall 保留配置和数据。

bun install
bun run install:templates
bun run chat

常用命令：

bun run setup        # 初始化向导
bun run status       # 运行状态
bun run doctor       # 诊断配置与依赖
bun run doctor --fix # 自动创建缺失目录
bun run tui          # 仪表板 TUI
bun run app.ts gateway

质量验证：

bun run check        # TypeScript 类型检查
bun test             # 运行所有测试
bun run build:binary # 编译本机二进制

Docker dev 运行已编译的 Linux 二进制，Compose 内不安装依赖也不构建。

bun run docker:dev                        # 重编 Linux binary + 启动 compose + 跟日志
bun run docker:chat                       # 直接进入 chat TUI
curl http://127.0.0.1:18790/health        # 健康检查
docker exec -it flyflor-dev flyflor       # 进入容器交互

挂载路径：

Redis 和 SurrealDB 为内部 compose 服务，不向宿主机暴露端口。架构变更后重新编译 + 重启：

bun run docker:up   # = 重编 binary + force-recreate compose

• LLM = 流体智力：当前任务的理解、推理、生成、工具编排、黑板讨论和即时决策。
• Crystal = 晶体智力：把验证过的经验压缩成可复用 Gem（晶粒），由证据门和质量门控制升格。
• Neural = 海马体：工作记忆（Redis）+ 长期记忆图（SurrealDB），支持 TTL 遗忘曲线、概念激活、记忆重建。

核心原则：不在堆叠记忆上发力，而在思考能力的自我迭代上发力。

1. 渠道、消息、用户身份归一为 GatewayMessage
2. 路由判断：fastRoute 启发式（~70% 命中）或 LLM route，决定 direct / direct-with-watch / blackboard
3. 上下文装配（热路径）：宪法层 Markdown + brain prompt atoms + Redis 海马体激活 + project/codename 局部记忆 + SurrealDB Gem 召回
4. LLM 主循环：流式生成，解析结构化 memory action / Ask / Ghost decision / identity append；TTFB 目标 < 350ms
5. 同步收尾：写 episode、brain 双写、Ask/Ghost/Codename/EQ 状态、skill usage 和 fastRoute snapshot
6. 后台 worker：consolidation、summary、decay、dormant、dream、feedback classify、reflection

SurrealDB 主表： episode、memory_node、gem（晶粒，crystallized intelligence）、gem_snapshot（防漂移版本快照）、summary_embedding

图边： next_context、similar_ep、consolidated_into、similar_concept、proven_as、proven_by

候选来源：runtime LLM 反思（整合 worker 异步触发）、用户显式提升、黑板收敛 / MCP 增强证据、skill promotion 与 brain 事件状态。

双质量门：

• 门 1：episode cluster sourceKind weight gate
• 门 2：memory_node confidence > 0.5 AND evidenceCount ≥ 3 → 升格 Gem

Evidence Weight 裁判表：

• 双轨衰减：episode 5%/天、memory_node 2%/天、Gem 0.5%/天；lastVerifiedAt 超 30 天额外打折。
• 矛盾检测：contradictionCount ≥ 2 → drift-repair；confidence < 0.1 → deprecated 归档。
• 容量阀门：Redis maxEpisodesPerUser=200；SurrealDB episode 500 / memory_node 100 / Gem 50。
• Gem 去重：symbols IoU ≥ 0.7 且 cosine ≥ 0.85 → merge（dedupeGems，纯函数，无字符匹配）。

Dream 是长期晶体层的主动维护 worker，仅读写 SurrealDB（gem / memory_node / episode / gem_snapshot），不触碰 Redis 工作记忆。

三类动作：

• drift-repair：先写 gem_snapshot 存档，再收窄 scope/precondition 或转 deprecated
• recall-reinforce：importance × 1.1，追加 proven_by 边
• contradiction-audit：弱侧 contradictionCount += 1，confidence × 0.7；< 0.1 → deprecated 归档

触发：定时 30 min 节拍 + 用户 10 min 静默自动触发（类海马 SWR 回放）。

单 pass：≤ 1 次 LLM 调用、≤ 8K token；候选选择仅用资源指标（counter / age / cosine），不用关键词。

Runtime 通过 blackboard.route.md 获取结构化路由：

• direct：单智能体直接回答
• direct-with-watch：直接回答同时监听升级信号
• blackboard：动态 worker 多轮讨论

黑板特性：

• 同 project constraint 同时只能一个 turn（lease 机制）
• 目标 3 轮收敛，5 轮硬上限
• livelock 检测（两轮无新事实、重复争议、重复失败工具）
• 流式输出 worker 讨论步骤
• 无法收敛时由 runtime 合成 Ask（reason=blackboard-stalemate），交还用户选择；旧 flyflor-decision-form 已退役

flyflor                      # 启动 chat TUI（TTY 环境）
flyflor chat                 # 对话模式
flyflor tui                  # 仪表板 TUI
flyflor setup                # 初始化向导
flyflor status               # 运行状态
flyflor doctor [--fix]       # 诊断（--fix 自动创建缺失目录）
flyflor update [--check] [-y]# 检查 / 应用更新
flyflor version              # 版本信息
flyflor config show          # 查看配置
flyflor config path          # 配置文件路径
flyflor memory status        # 记忆状态
flyflor blackboard list      # 黑板 turn 列表
flyflor codename list        # 代号锚点列表
flyflor inbox list           # inbox/codename 桶中的 atom
flyflor ghost list --user me # 未完事项 / 可恢复上下文
flyflor identity list --user me # identity 自写条目
flyflor gem list             # 晶体列表（`skills` 子命令已更名为 `gem`）
flyflor mcp list             # MCP 服务列表
flyflor plugins list         # 插件列表
flyflor plugins run <name>   # 沙箱审批后运行插件
flyflor dream status         # Dream 队列状态
flyflor dream run            # 手动触发 dream pass
flyflor model                # 模型配置向导
flyflor gateway status       # 网关状态

• 只保留必要 decorator：@Module、@Provide、@Inject、@Service、@Component、@Worker、@Channel、@Plugin
• 边界模块用继承表达：class RuntimeModule extends Runtime，不新增专用 decorator
• 实现文件使用点分后缀：*.module.ts、*.service.ts、*.worker.ts、*.manager.ts、*.adapter.ts、*.store.ts
• 目录入口统一为 index.ts，不新增连字符或下划线命名的仓库文件

业务语义判断（意图、路由、记忆动作、反馈分类、矛盾检测、复杂度评估等）只能由模型同轮返回的结构化字段或专用提示词模板的 JSON 输出驱动。

禁止：text.includes()、正则识别意图、关键词列表、句式启发式、情感词典、句末标点判断。

性能优化只能用资源指标（token 数、向量相似度、TTL、cluster size）短路。

• 只使用 Bun 命令管理依赖，不要求安装 Node.js
• 配置走 ~/.flyflor/config.jsonc（Docker dev：./docker/config/config.jsonc），兼容 JSONC
• 业务配置不走环境变量；凭据、沙箱策略走 config/secrets provider
• 新增运行时依赖前确认兼容 bun build --compile（无 native addon、无 postinstall、无动态 require）
• 不把密钥、日志、会话数据库、用户数据编译进二进制
• 跨模块通信使用显式类型；公共事件和协议必须可 JSON 序列化
• 修改边界、高风险工具或依赖策略时同步更新 docs/boundaries.md

完整文档索引见 docs/README.md。核心文档：