ARTICLE · 1288047

空谷 Ondra 项目文档

发布时间：2026-10-31 22:59:22 最近访问：2026-10-31 22:59:23

空谷 Ondra 项目文档

空谷 Ondra

中文｜English

于无声处，听见共鸣。

空谷 Ondra 是星玖工作室（Ntarstudio）出品的开源 AI 陪伴体应用，可一键部署、高度自定义。产品运行在 DeepSeek-Harness（下称 dsh）的 Cordis 插件体系之上，dsh 仅提供插件容器与运行时底座，产品的全部能力由 144 个 ondra-* 插件实现。

项目	内容
中文名	空谷 Ondra，取自成语「空谷足音」
仓库	ntars/Ondra
官网	https://ai.ntars.cn/
版本	1.0.1
许可	AGPL-3.0
插件数量	144 个，按 B0–B13 十四个批次交付
插件目录	`cordis/`
出厂人设	鲸鲸（人格包 `哦鲸鲸`），夏柠柒为示例包
运行时	内置 Node.js 24，无需用户安装
开发手册	material/Ondra-dev-handbook.md（唯一正典，全部插件规范的来源）

开始阅读前建议先打开开发手册：material/Ondra-dev-handbook.md。本文档的插件分层、参数取值与取舍均以该手册为唯一依据；两者不一致时以手册为准。

一、插件体系

1.1 分层与崩溃半径

插件按「崩溃后影响什么」分为十层，而非按功能数量分组。上层可调用下层，下层不得反向依赖；同层之间只经服务键通信，不互相导入源码。

层	名称	插件数	崩溃后果
L0	基座	5	无法定位问题
L1	存储	4	记忆不可恢复
L2	内核（记忆、人格、情绪）	29	对话质量下降，仍可说话
L3	对话链	5	无法对话
L4	表达与生活	20	无语音、无表情、无生活感
L5	通道	13	单个渠道收发中断
L6	端侧	8	单项扩展不可用
L7	系统与交付	9	装不上或起不来
L8	界面	14	白屏
L9	运行时治理与扩展	37	治理能力或扩展能力缺失

1.2 插件契约

每个插件是一个独立 npm 包，入口固定导出四项：

export const name = 'ondra-memory-core'        // 插件标识，同时是服务键export const inject = ['ondra-store-sqlite']   // 依赖的服务键，可选export function apply(ctx: Context) { }        // 生命周期入口export const Config = { /* 配置结构与默认值 */ }

六条硬约束：

包间不互相 import，一律 ctx.get('ondra-xxx')，取不到则静默降级。
默认给好，全部可调；简单模式四档，高级模式暴露具体数值。
失败静默降级，增强能力失效不影响主对话。
可逆注册，定时器、监听器、路由、面板均经 ctx.effect() 或 ctx.on() 注册并返回 disposer。
单一真源，数据结构与默认值由提供方拥有，消费方只读。
命名硬约束：服务键、工具名、配置键必须匹配 ^[a-z][a-z0-9_-]{1,63}$，统一使用连字符，不使用冒号。

1.3 组合包声明（漏写即静默不加载）

package.json 必须声明补丁文件：

{ ”dsh”: { ”bundle”: { ”patch”: ”./cordis.patch.yml” } } }

未声明时宿主只在 stderr 输出一行 declares no dsh.bundle 便跳过该包，包虽存在于依赖目录、组合包清单中也写入了名字，但插件永远不会被加载。补丁语义为：insert 不带 id 时追加到根入口列表；insert 带 id 时目标必须是分组入口；不带 insert 的补丁行必须提供 id；目标不存在、非分组或名称不一致时只告警并跳过。入口字段只有六个：id、name、config、group、disabled、inject。

1.4 三档复用

档位	含义	数量级
〔复〕复用	生态成熟，插件只做接线、配置与降级	通道、语音、视觉、桌宠、市场、图标、农历、记忆底层
〔薄〕薄封装	有实现，需包一层适配与护栏	语言锁、思维链锚、输出评审、心跳、生活日志、证据门控
〔研〕自研	生态无成熟实现，允许写厚，总量控制在 15 项以内	七阶关系弧、阈值漂移、语感统计、九步过滤、节制设计、器官 ABI、上下文治理七件

1.5 器官 ABI（插件体系宪法）

涉及器官的插件必须遵守三条不可让渡约束：

C1 不直接写状态：器官只提交变更提议，由宿主累加后一次性应用并裁剪。
C2 为感知付费：每次感知返回能量回执，状态为 full、partial、starved 或 shadow；denied 为真时必须立即放弃本次感知。
C3 错误不传播：外层捕获异常，转为 degraded 并返回空值。

上下文以门面形式暴露，仅开放 state、consume、emit、proposeGap、onToolResult、onTick、registerTool、onPrompt、kv、log。能力白名单默认拒绝，越权调用抛出 CapabilityDeniedError。提示词片段携带 order、ttl、confidence，疤痕权重恒为 -1e4，器官不得低于 -1000。

1.6 执行批次

批次	范围	插件数
B0	基座	5
B1	存储与模型网关	5
B2	记忆纵深	14
B3	人格与情绪	16
B4	对话链与表达	14
B5	主动与节制	10
B6	运行时治理	7
B7	通道	13
B8	界面	14
B9	多模态	3
B10	端侧	8
B11	系统与交付	9
B12	多方案分支	2
B13	扩展池	24

二、B0 基座（5 个）

编号	插件	档位	功能	实现技术
O-001	`ondra-identity`	〔研〕	产品名、进程名、pidfile 名与环境变量前缀的唯一真源	纯常量模块，零副作用；导出只读对象，`apply` 仅注册服务；命名在 `app ready` 之前完成，保证内置目录落在产品名下
O-002	`ondra-path-layout`	〔研〕	解析数据根、运行时根、技能根、用户数据根与临时目录，创建目录并设置权限	`path.join` 组合路径，`fs.mkdir` 递归创建；目录 0700、文件 0600；`chmod` 失败不阻断（网络盘不支持权限），仅记录降级
O-003	`ondra-clock`	〔研〕	统一时间源与自然日判定，供关系天数去重与定时任务使用	时间函数可注入以便测试；自然日按本地时区切分；跨日判定只比较日期部分，不做时间差近似
O-004	`ondra-log-zh`	〔研〕	双层日志：面向用户的概览层与面向开发者的代码层，含轮转与写放大保护	环形缓冲 + 同键去重（同一错误每秒只保留一条）+ 4 MB×3 轮转；代码层仅在开发者模式输出
O-005	`ondra-config-schema`	〔研〕	四层配置结构与全部默认值的单一真源	声明式 schema，合并顺序为出厂默认、组合包默认、用户配置、运行时覆盖；校验失败回退该字段默认值而非整体失败

三、B1 存储与模型网关（5 个）

编号	插件	档位	功能	实现技术
O-006	`ondra-store-sqlite`	〔薄〕	SQLite 存储端口：建表、补列、事务、权限	`node:sqlite` 的同步接口；启动执行 `PRAGMA journal_mode=WAL` 与 `PRAGMA foreign_keys=ON`；用 `PRAGMA table_info` 比对后对缺失列执行 `ALTER TABLE`；文件权限 0600
O-007	`ondra-store-memory`	〔研〕	SQLite 不可用时的内存实现，接口与 SQLite 端口一致	`Map` 承载表与索引，进程退出即失效；仅用于降级，不做持久化承诺
O-008	`ondra-data-migrate`	〔研〕	幂等初始化与版本迁移	版本表记录当前版本，迁移脚本按序执行并包裹在事务中；重复执行不产生副作用
O-009	`ondra-snapshot`	〔研〕	记忆库快照、保留 3 份、显式恢复	三级降级：系统 `sqlite3 VACUUM INTO`、`node:sqlite` 在线导出、文件复制；恢复前先复制一份 `before-restore` 留档；文件名白名单校验，绝不自动恢复
O-035	`ondra-llm-gateway`	〔薄〕	模型供给：在线 API、本地模型、免费模型三来源切换，密钥注入与超时重试	OpenAI 兼容客户端；密钥由宿主环境注入，不写入配置；思考型模型走 nothink 代理兜底，避免正文为空；超时与指数退避重试，失败不阻塞主链路

四、B2 记忆纵深（13 个）

编号	插件	档位	功能	实现技术
O-010	`ondra-memory-core`	〔研〕	双层记忆存储与寿命计算	原文表与事实表，同一事务写入；寿命 `S(h) = baseHours × (0.45 + salience/100 × 1.25) × (1 + arousal × 0.65)`；11 类基线：约定 8000、自我 20000、人物 240、学习 80、情绪 50、事件 40、杂项 20、地方 12、饮食 10、日常 3、看片 2 小时；三通道 4/12/180 天作为第二层调制，先类别后通道相乘
O-011	`ondra-memory-extract`	〔研〕	从对话中提炼事实，附来源类别与逐字引文	5 秒定时、按会话分组、单批 20 条且不超过 3000 字；提示词附该会话既有事实要求沿用措辞；严格 JSON 输出，五级解析兜底（直解、去围栏、切片、对象抢救、按句回退）；按角色过滤掉助手自身输出
O-012	`ondra-memory-dedupe`	〔研〕	事实去重与取代链	归一化键为主语、谓语、宾语，处理空白折叠与小写；裁决优先级为手改优先、重要度高优先、创建早优先；败者保留并指向胜者，不物理删除
O-013	`ondra-memory-decay`	〔研〕	衰减结算、容量淘汰与间隔复习	指数半衰期为主；命中拉长 `1 + 0.6·log2(1+次数)`，封顶 4 倍；重复提及拉长 `min(15, 3×(1+ln(1+times_said)))` 天；SM-2 间隔复习按记忆难度排期；归档只降强度不删除，30 天未带出强制补出 1 条
O-014	`ondra-memory-recall`	〔研〕	三路径检索与打分	五因子加权：语义 0.18、关键词 0.46、图谱 0.11、重要度 0.14、新鲜度 0.11；BM25 参数 `k1=1.2`、`b=0.75`；新鲜度 `0.5^(距上次想起÷半衰期)`，锚点为最近命中或创建时间；归一化只除以参与权重的因子；RRF 融合只看名次不看分数；召回不按条数截断
O-015	`ondra-memory-graph`	〔研〕	图谱四边建边与联想扩散	四类边：共享实体、时间邻近、日历锚点、同主题；召回后沿边扩散 1 跳，边权 0.6；扩散门槛 0.4，枢纽度上限 40；同主题初值 0.72–0.85 每次 +0.05，共现初值 0.15 每次 +0.10
O-016	`ondra-memory-prospective`	〔研〕	承诺与待办的前瞻记忆	承诺锁原文永不压缩；权重反向 `0.4 + 0.6·e^(-
O-017	`ondra-memory-audit`	〔研〕	遗忘可解释与四态删除	每条展示通道、当前强度、剩余半衰期与「为什么还记得」；提供钉住（地板置 1）与忘掉；四态删除为 `forget` 写墓碑且合并不复活、`seal` 封存、自然沉底、`revise` 保留旧文本且新版本合并必胜
O-018	`ondra-memory-humanlike`	〔研〕	三通道视图与随机回顾	事实 4 天、感觉 12 天、情绪 180 天，地板 0.02、0.30、0.55；会话开始掷骰 `p=0.15`，命中则从弱记忆抽一条自然带出；弱记忆被提起 2 次升为强记忆，重要度 +0.1
O-019	`ondra-memory-dream`	〔研〕	夜间记忆巩固（闸式）与轻量分支	六步夜跑：共现加固、衰减（必须携带 `decayed_at` 游标，否则重复乘算）、软剪枝、荒诞联想、梦话、重写摘要；开工前在线备份，每步限额，删除一律软删；轻量分支在空闲 2 分钟与 5 分钟分两档，纯规则挖五类卡片，未用卡片 168 小时半衰期
O-131	`ondra-memory-pool`	〔研〕	八池分层与归档	核心池永不衰减、上限 32；铁律池半衰期 730 天且常驻全量；经验池 60 天；日常核心 60 天；日常片段 20 天；情绪池 1 天且非日志；海马体 1 天且永不注入；标签未命中任何池时不猜测，落海马体并标记未归类，同句重复 3 次升级为需人工定池
O-140	`ondra-evidence-gate`	〔研〕	记忆写入门控	写入前做确定性校验：四类引文必须可定位并逐字比对；数字断言必须携带工具来源标记；缺少用户引文的归功断言直接拒绝；校验不依赖模型自觉
O-142	`ondra-inject-dedupe`	〔研〕	注入去重	首轮一次性大块注入，此后只推增量；已见标识记账；压缩信号触发释放已见集合；实测每次唤醒重复注入会使单次上下文多背 13000 字以上
O-136	`ondra-recall-eval`	〔研〕	检索评估	20–40 条真实问法并含换说法集；输出 recall@1、recall@3、MRR 与端到端成功率；报告落盘；改一次参数跑一次评估，评估先于任何调参

五、B3 人格与情绪（15 个）

编号	插件	档位	功能	实现技术
O-020	`ondra-persona-loader`	〔研〕	读取人格包并注册为可用人设	扫描 `cordis/ondra-persona-skills/` 下的 `*.skill.zip`，解析包内 `meta.json` 与 `SKILL.md`；人设包只读，不写入、不改名；出厂人设为鲸鲸，示例包可替换
O-021	`ondra-persona-core`	〔研〕	人格内核、五关系变体与六槽位	内核放共享身份、性格、诚实与边界；五个变体只写关系差异（称呼、相处节奏、典型反应）；同 id 合并时后者覆盖前者
O-022	`ondra-persona-vars`	〔研〕	变量替换与说话浓度	支持 `{{name}}`、`{{callUser}}`、`{{relation}}`、`{{toneLevel}}` 等占位；未识别占位原样保留而不清空；浓度三档生成不同强度的语气提示
O-023	`ondra-persona-assemble`	〔研〕	四段拼装与预算裁剪	顺序恒为内核、关系微调、浓度、边界；`priority` 只用于超预算时决定先砍谁；边界层整层豁免裁剪，超预算返回 `overBudget` 而不悄悄少一条禁令；总预算 1600 字符
O-024	`ondra-worldbook`	〔研〕	六层世界书选择器	总预算 1600 token，分层 350、180、100、500、200、150；L1 与 L6 常驻不看关键词，其余按关键词命中；层内按优先级装填，超限整条丢弃并记入 dropped；层内余量顺延下一层
O-025	`ondra-worldbook-scenes`	〔研〕	场景卡数据与触发规则	关键词小写 `includes` 匹配；同层多张卡只留优先级最高一张，其余记入 suppressed；仅 L4 可递归拉起，深度不超过 3
O-129	`ondra-drive-gap`	〔研〕	缺口池与张力，构成内驱源	`tension = clamp(base + h×rate − relief)` ；相似度 ≥0.6 只加 10 避免重复加压；唤醒门槛 80；三源生成；缺口闭合时触发关联结算；承诺闸门可并入本插件
O-130	`ondra-persona-evolve`	〔研〕	由经历改写人格与阈值漂移	`threshold = base × (1 + 0.6 × min(1, interactions/5000))` ，上限 +60%；随熟悉度、关系阶段与累计互动量单调上移；漂移落盘并提供 `explainThreshold()`
O-026	`ondra-emotion-core`	〔研〕	情绪状态容器、PAD 三维、十标签与化学池	指数回归 `v(t)=baseline+(v₀−baseline)·e^(−λt)`，`λ=ln2/半衰期`，读取时惰性补算；单条消息变化上限 0.12，标签上限 0.6，标签半衰期 45 分钟，心情 6 小时；多巴胺 50/45min、皮质醇 20/30min、血清素 50/120min；存档缺字段补基线 50 不补 0
O-027	`ondra-emotion-diffuse`	〔研〕	跨会话情绪弥散	`(mood − baseline) × 0.4 × (1 − familiarity × 0.5)` ，越不熟悉越容易被迁怒；纯函数，可单测
O-028	`ondra-emotion-stage`	〔研〕	七阶关系弧与防跃迁	敌意、试探、心动、占有、病态、献祭、落定；三轴（互动天数、亲密、信任）同时达标才升阶；四道防跃迁为时间闸、步长闸 0.06、只升不降、冲突锁覆盖；五阶段与六段刻度仅作只读映射
O-029	`ondra-emotion-stress`	〔研〕	应激注意力倍率	皮质醇 ≥80 时危机类 ×3、日常类 ×0.1；60 时 ×2 与 ×0.55 线性插值；≤40 均为 ×1；≥80 时在系统提示词最前注入行为指令
O-030	`ondra-emotion-conflict`	〔研〕	冲突锁定与解除	冲突事件使张力 +0.15 并压低心情；锁定期不撒娇、不主动、回复变短；解除条件为致歉或连续两次正向信号且心情回升过阈
O-031	`ondra-emotion-express`	〔研〕	状态到六态表达的映射	六态为雀跃、软和、平静、蔫、炸毛、困；择档顺序为锁定或高张力、高应激低心情、高应激、低能量、高心情高能量、中等心情、默认；每档给出句数上限、单句字数、语气词、标点与是否起话头
O-032	`ondra-emotion-project`	〔研〕	情感投影与内感受铁律	将六维状态序列化为 60–100 字自然语言，注入用户消息尾部以占据注意力高位；禁止报出数值，只允许主观表述

六、B4 对话链与表达（14 个）

编号	插件	档位	功能	实现技术
O-033	`ondra-dialogue`	〔研〕	对话编排：取上下文、组装提示词、流式调用、收尾	上下文装配顺序为日期事实、人格、世界书、情感投影、长度纪律；会话内冻结稳定前缀，易变段追加尾部，禁止每轮重拼；绝不创建会话记录、绝不写会话日志；任一提示词段取不到时以空串继续并只告警一次
O-034	`ondra-dialogue-protocol`	〔研〕	对话事件协议	五类帧：文本增量、文本替换、危机信号、用量统计、结束；结束帧携带停止原因（正常、中断、错误、长度）；未知分片忽略而不抛错
O-038	`ondra-rhythm`	〔研〕	分条与停顿的纯计算	按强标点切句，仅当单句超过 40 字才在软停顿处二次切分；条数上限 4 条，超出时从尾部合并；字速 6 字每秒，标点附加 150 至 500 毫秒；停顿时长先卡上下限、再乘深夜系数 1.6、再卡一次；首条延迟 0.8 至 2.0 秒；长停顿概率 0.20 且整轮最多一次；自我修正概率 0.05
O-039	`ondra-rhythm-typing`	〔研〕	拟人打字节奏	打字时长由字数与字速推导，叠加标点附加；长停顿与自我修正在此层落地；深夜与低落时整体放慢，雀跃时加快
O-040	`ondra-oral`	〔研〕	口语化	口头禅池按情绪分档，单场最多使用 2 次防复读；语气词按六态映射启用；不完整句概率 8%；句末不用句号以保留聊天感；单条中位长度 8 至 12 字；不引入错别字
O-041	`ondra-breath`	〔研〕	非语言层	首条延迟期间显示正在输入；长时间在线时偶发无信息量的呼吸动作，单日不超过 2 次；与贴纸、语音共用最小间隔约束
O-036	`ondra-prompt-inject`	〔研〕	上下文注入与预算分配	装箱制：按权重全局排序逐条装入字符预算，装不下跳过继续试下一条，段标题写明「另有 N 条未展开」；预算三档 2600、24000、1200 字符，默认 2600；核心段不参与装箱；首轮一次大块，正文留盘按需展开
O-037	`ondra-filter-chain`	〔研〕	九步输出过滤与事后评审	管道式 pass：剥思考过程、硬性违规替换、关系红线、阶段红线打回重生成、设定暴露替换、旁白化删动作、复读按 4-gram 重叠判定、客服腔替换、长度回退到完整句；事后评审由独立模型打 1–100 分，低于阈值携带反馈重生成，每轮最多两轮
O-137	`ondra-lexicon`	〔研〕	语感统计	取最近 300 条真人消息，统计中位句长、无标点率与语气词分布，压缩为约 130 字注入；只统计不覆盖人格；注入块带标记便于替换
O-050	`ondra-tts`	〔复〕	语音合成双通道	本地 GPT-SoVITS 走 HTTP 接口，云端 Edge TTS 提供 19 种音色与 8 套预设（温柔、活泼、播音、东北、陕西、粤语、台湾、English）；合成或上传失败一律静默回退文本
O-051	`ondra-tts-gate`	〔研〕	语音放行四闸门	开关需显式开启；句长 6–30 字；情绪强度 `max(
O-052	`ondra-expression-decide`	〔研〕	正文到表情的规则决策	三条正则按序匹配（困、羞、喜），命中即返回；最小间隔 3 条；无关键词时按心情与随机数兜底；不让模型直接输出表情标记，避免每条都带且位置随机
O-053	`ondra-sticker`	〔研〕	贴纸包读取与分发	读取人格目录下 `stickers/`，扩展名白名单为 png、webp、gif、jpg、jpeg；文件名下划线前为标签；目录缺失或为空时回退内置三张
O-054	`ondra-avatar`	〔复〕	立绘渲染	复用生态实现（airi、dsh-whale-girl-live2d）并以适配层包裹；渲染器不可用时降级为静态立绘；未实现时显式提示而不显示可点击控件

七、B5 主动与节制（8 个）

编号	插件	档位	功能	实现技术
O-042	`ondra-proactive-gate`	〔薄〕	主动消息三闸门与心跳引擎	时机闸：静默时段 23:00–08:00 不打扰、空闲 ≥25 分钟、每日 ≤3 条、距上次 ≥2 小时；话由闸：到点承诺、待办、近期事件、时间线、环境；分寸闸：单句 ≤20 字、必须含具体锚点、禁止「在吗」、35% 概率放弃；心跳由模型自排闹钟（一次、间隔、cron 加抖动），支持唤醒冷会话，静默唤醒回合以固定标记结束并从上下文折叠；叠加防封六道闸
O-043	`ondra-proactive-reason`	〔研〕	话由排序与冷却	优先级为承诺到期、待办、近期事件、时间线、环境场景；叠加缺口池的「她自己在惦记」；话题 72 小时冷却；被排除的理由本轮不再使用
O-044	`ondra-proactive-quota`	〔研〕	额度与衰减	每日 3 条；连续 3 天无回应额度减半，7 天暂停；退场规则为连续静默 2 天或用户开口后已主动 2 次，只说一句退场句；群聊不主动、支持一键静音
O-134	`ondra-climb`	〔研〕	群消息积压补读	读取未读积压并逐条摘要，输出携带时间、发言人与群号；设有条数上限；唤醒仅在私聊生效
O-135	`ondra-narrative-log`	〔研〕	回复决策解释	记录本轮使用的记忆、情绪值、关系阶段与话由，追加写入只读日志；供界面与审计查询「她为什么这么回」
O-045	`ondra-diary`	〔研〕	每日第一人称日记	02:00–04:00 窗口内生成 100–200 字；按日期幂等查重，同日不重写；素材只取库中真实记录，禁止编造天气与饮食；模型不可用时走规则兜底；不通知、不改未读、不弹窗
O-046	`ondra-live`	〔复〕	日期事实	星期、农历、节气与节日；农历用 lunar-javascript 与 tyme4ts 双实现并对拍；全部本地计算，不联网；只给事实不加指令
O-047	`ondra-weather`	〔复〕	天气	需显式配置坐标才启用；缓存 20 分钟，失败后 10 分钟内不重试；取不到时不写入任何提示词内容
O-048	`ondra-life-rhythm`	〔薄〕	生活层与能量作息	生活层在独立脚本进程中运行，随机六类活动（学习、看书、刷视频、写日记、发呆、群里冒泡），兴趣带权重与标签，10% 概率探索新兴趣，心情差时优先放松型；能量清醒 +0.2/分钟、深睡或深夜 +1/分钟，自然上限 60，急停期间冻结，分段积分按 5 分钟切片，睡醒指令取走即清零
O-049	`ondra-onthisday`	〔研〕	那年今日	以日历锚点边查询同一日期区间的历史记忆，按强度排序，最多返回若干条，用于制造回忆感

八、B6 运行时治理（7 个）

编号	插件	档位	功能	实现技术
O-132	`ondra-organ-host`	〔研〕	器官 ABI 与宿主	门面上下文只暴露十项能力；能力白名单默认拒绝，越权抛 `CapabilityDeniedError`；能量回执状态机 `full`、`partial`、`starved`、`shadow`，迁移期默认 `shadow` 只记账不真扣；反馈仲裁累加后一次性应用再裁剪；提示词片段按 `order` 排序并过滤过期与低置信度；疤痕恒 -1e4
O-138	`ondra-organ-gate`	〔研〕	工具 schema 门控与意图路由	确定性规则判定意图，按需暴露工具定义；实测工具定义由 55154 token 降至 8433 token，压缩 84.7%；门控规则不调用模型，避免额外延迟
O-139	`ondra-failure-attrib`	〔研〕	八类失败归因与处方	归因为工具缺失、参数错误、权限、超时、网络、未找到、冲突与未知；参数错误永不自动重试；伤口在下一次同工具成功时闭合，5 分钟未闭合标记慢性；归因结果进入诊断视图
O-141	`ondra-memory-recognition`	〔研〕	再认检索分支	将全量索引放入提示词（500 条约 6k token，走前缀缓存），由小模型挑选 slug，再沿 `[[links]]` 做邻域游走；与向量分支并列，默认仍以倒排为主
O-143	`ondra-zero-residence`	〔研〕	零常驻上下文	以确定性指针替换常驻内容，被遮蔽的字节可从会话日志逐字恢复，保证可逆可审计；压缩前先把状态写入 SQLite；提供压缩、召回、账本与快速四类操作
O-144	`ondra-reflex`	〔研〕	反射弧与链路结晶	同一工具同一原因失败 3 次后自动写入规则 `R-auto-<cause>-<tool>`；跨器官 3 步以上成功链固化为技能；全过程零模型调用；写坏 3 次触发熔断，防止死循环烧钱
O-133	`ondra-install-doctor`	〔研〕	安装自检	移植补丁解析、补丁应用与入口树合成三步，算出宿主实际会看到的入口树；报告被跳过的组合包与告警条数；第十项检查为「宿主会不会真的加载我」

九、B7 通道（13 个）

通道层遵循一条隔离铁律：一个通道一个插件，独立配置、独立凭据文件（0600）、独立日志命名空间、独立探针实例、独立启停。任一通道崩溃、超时或被风控，其余通道与主对话不受影响。

9.1 公共层（3 个）

编号	插件	档位	功能	实现技术
O-055	`ondra-router`	〔研〕	唤醒判断、多会话排队与通道能力查询	私聊必回、被提及必回、关键词命中、概率唤醒（默认 0.1）、其余不回；跨会话不并行；唤醒身份纪律为仅在私聊唤醒
O-056	`ondra-channel-kit`	〔研〕	通道公共段：收消息、问人格、发回复	纯函数与工厂：`callPersona` 返回字符串或空值，人格服务缺席时告警并丢弃消息；`chunkText` 按上限切分；`PeerHistory` 每通道独立实例、仅内存、上限 12 条；刻意不做消息落盘与限流重试
O-057	`ondra-channel-health`	〔研〕	通道探针	包装日志的告警与错误级别，先调用原函数再观察，观察内部全捕获；按 `[channel]` 前缀识别通道；以关键词判定正常与异常，无法判定则忽略；不依赖被观测进程存活，适配器崩溃时界面仍显示异常而非正常

9.2 合规通道（7 个）

编号	插件	档位	传输与实现
O-058	`ondra-adapter-qq-official`	〔复〕	开放平台 OpenAPI v2，WebSocket 长连；先取网关地址再连接，心跳携带序号；被动回复必须携带原消息 id；分条上限 1200 字
O-060	`ondra-adapter-wechat-official`	〔复〕	Webhook 接收，签名校验；被动回复有 5 秒硬超时，因此先回降级话术，再用客服消息接口在 48 小时窗口内补发真实回复；分条上限 800 字
O-061	`ondra-adapter-wechat-kf`	〔复〕	拉取式：每 5 秒调用 `sync_msg` 并携带游标，回调仅作为有新消息的信号；只处理用户发来的文本；分条上限 800 字
O-063	`ondra-adapter-wecom`	〔复〕	Webhook 接收，自实现消息加解密：SHA1 验签、AES-256-CBC 解密、去除补位与随机前缀、校验企业标识；先返回成功再异步处理；分条上限 2000 字
O-064	`ondra-adapter-feishu`	〔复〕	Webhook 接收，校验验证令牌并回显挑战；仅处理消息接收事件；租户令牌缓存并在到期前 300 秒刷新；不支持加密事件体，检测到加密配置时提示关闭
O-065	`ondra-adapter-dingtalk`	〔复〕	Webhook 接收，HMAC-SHA256 验签；先返回空消息再异步处理；回复走会话 Webhook；需要公网可达地址
O-066	`ondra-adapter-telegram`	〔复〕	`getUpdates` 长轮询，超时 50 秒；令牌置于 URL；按偏移量天然去重；失败 3 秒退避后继续；分条上限 4000 字
O-067	`ondra-adapter-discord`	〔复〕	Gateway WebSocket v10，自实现连接与心跳；仅处理消息创建事件；群聊必须提及、私信必回；令牌无效错误码时停止重连，其余 5 秒重连；分条上限 1900 字

9.3 高危通道（3 个）

编号	插件	档位	传输与实现
O-059	`ondra-adapter-qq-napcat`	〔复〕	NapCat 反向 WebSocket（OneBot 11），由协议端主动连入本机；默认关闭，独立区块展示风控说明；不与合规通道混列
O-062	`ondra-adapter-wechat-personal`	〔复〕	用户自备协议端，本机 HTTP 收发；双闸门 `enabled` 与 `confirmed` 同时为真才生效；只处理私聊文本，不读历史；全程本地不上报

十、B8 界面（14 个）

编号	插件	档位	功能	实现技术
O-085	`ondra-ui-shell`	〔研〕	三栏骨架与滚动规则	栏宽 272、自适应最小 520、300；仅会话列表、消息流与卡片区各自滚动，页面整体不滚动；断点为 1440、1240、1080、900、860，900 以下右栏折叠为抽屉
O-086	`ondra-ui-tokens`	〔研〕	设计令牌单一真源	品牌色 `#6E56E0`（白字对比度 5.16:1），深色模式文字色与填充色分开使用；字号 7 档（15、13、12、11、14、13、10）；圆角 6 档（4、6、8、10、12、999）；间距 7 档（4 至 32）；密度三档
O-087	`ondra-ui-icons`	〔复〕	图标与形变	直接引入 morphicons（MIT，零依赖），44 个注册表图标与 12 组形变配对；描边按尺寸分档 16 像素用 2、20 像素用 1.8、24 像素用 1.6；同屏形变不超过 2 个
O-088	`ondra-ui-api`	〔研〕	本地接口层	挂载固定前缀，核心 19 条路由并扩展至 40 余条；令牌 32 字节随机、文件 0600、请求头校验、定长比较；响应统一为 `{ok, data}` 或 `{ok, error}`；未就绪返回 503
O-089	`ondra-ui-chat`	〔研〕	对话渲染	流式五帧渲染；时间分隔规则为跨天显示日期、同日间隔超过 5 分钟显示时间；富消息含图片、文件、引用与日记卡；气泡圆角 12，靠近头像上角收窄为 4
O-090	`ondra-ui-sessions`	〔研〕	会话列表与搜索	会话行高 60，支持紧凑与宽松；搜索框 30 像素，快捷键聚焦，输入即筛会话与记忆两个结果区；行右键提供重命名、置顶与删除
O-091	`ondra-ui-panel`	〔研〕	右栏状态卡	情绪、记忆、关系与连接四类卡片；关系阶段条分母为 7，已过阶段浅实心、当前实心、未到描边；六态光球随实时状态呼吸变色
O-092	`ondra-ui-settings`	〔研〕	设置面板	九个分类；必须补齐九个入口（通道凭据表单、模型参数、贴纸管理、头像上传、记忆抽屉、会话管理、主动数值、主题密度、数据导出）；字段由插件配置结构声明，界面只按结构渲染，不写死字段名
O-093	`ondra-ui-a11y`	〔研〕	无障碍	焦点环 3 像素，移除全局 outline 抑制；aria 标注覆盖全部图标按钮；快捷键覆盖设置、搜索、新建会话、导出与发送
O-094	`ondra-ui-theme`	〔研〕	主题	跟随系统深浅色；系统未提供时按日出日落切换；主题色可自定义并提供对比度预校验
O-095	`ondra-ui-toast`	〔研〕	提示与空态	Toast 三级（成功、失败可重试、提示），图标与颜色区分；空态显示线性插画与主副文案；加载显示 3 行骨架；出错显示原因与重试按钮
O-096	`ondra-ui-logs`	〔研〕	日志视图	中文简易日志与开发者代码日志切换；日志走环形缓冲，视图只读
O-124	`ondra-ui-growth`	〔研〕	人物成长面板	九个视图（情绪、情绪曲线、性格、记忆、记忆星图、好感、学习、花费、体检）；一份大快照，60 秒自动刷新；预加载只暴露 5 至 7 个方法，零框架
O-125	`ondra-ui-prompt-preview`	〔研〕	提示词预览	`GET /api/prompt-preview` 返回本轮模型实际收到的文本与工具清单；只读并脱敏，不返回密钥

十一、B9 多模态（3 个）

编号	插件	档位	功能	实现技术
O-126	`ondra-vision`	〔复〕	图片理解、OCR、物体定位与视频抽帧	提供方可插拔：云端 OpenAI 兼容接口、本地 Ollama、通义千问；默认关闭；与隐私插件联动，启用时展示出站提示；模型不可用时停止行动而不猜测
O-127	`ondra-asr`	〔复〕	语音转写	本地 Whisper 优先，云端兜底；输出带时间戳与说话人分离；失败静默；转写文本按普通记忆入库
O-128	`ondra-multimodal-memory`	〔研〕	多模态记忆入库	图片存描述、语音存转写、视频存 4 帧与音轨；记录 `modality` 与 `source_path` 便于溯源；与证据门控共用写入路径

十二、B10 端侧（8 个）

编号	插件	档位	功能	实现技术
O-068	`ondra-adb`	〔复〕	安卓设备能力	以 scrcpy 封装为主（投屏与控制能力强于纯 adb）；默认只读；轮询式取新增数据；失败时静默不刷屏
O-069	`ondra-device-mcp`	〔研〕	手机只读 MCP	五个工具：通知、短信、联系人、电量、前台应用；全部只读；单次调用超时 8 秒；指定序列号时前置设备参数
O-070	`ondra-desktop-mcp`	〔研〕	电脑只读 MCP	五个工具：进程、前台窗口、剪贴板元信息、文件检索、系统状态；进程不返回命令行（可能含令牌），剪贴板只返回类型与长度，文件检索限定主目录、深度 2、最多 30 条；超时 5 秒
O-071	`ondra-browser`	〔复〕	浏览器自动化	复用生态实现并以适配层包裹；工具输出经沙箱压缩后进入上下文；默认关闭
O-072	`ondra-gui-agent`	〔研〕	桌面自动化	单步决策环：感知、决策、执行一个动作、复核、汇报；四级风险分级（只读、点击、输入、系统）；三层安全网为危险区域黑名单、应用白名单默认零授权、动作确认阈值；表单红线为检测到已输入字段立即收手；每步写审计日志
O-073	`ondra-minecraft`	〔复〕	游戏接入	基于 Mineflayer；占位形态，默认关闭，启用时给出明确提示
O-074	`ondra-pet`	〔复〕	桌面宠物	复用生态实现（dsh-pet、agentpet，MIT）；保留为能力入口，不自行实现渲染
O-075	`ondra-pet-mobile`	〔复〕	移动端桌宠	占位插件，钉住三端技术前提并说明形态差异，未实现时显式提示

十三、B11 系统与交付（9 个）

编号	插件	档位	功能	实现技术
O-076	`ondra-privacy`	〔研〕	合规告知与风控提醒	展示出站清单、数据处理说明与卸载导出方式；对高危通道做三层提醒（首次绑定全屏确认、列表色标、失败率超 20% 横幅）；真正的隐私硬关在配置层，本插件只负责告知与提醒
O-077	`ondra-startup-check`	〔研〕	启动自检	十项检查，含入口激活数、隐私两开关、关键包存在性；只判定与报告，不负责拒绝启动；拒绝启动由渲染层决定
O-078	`ondra-market`	〔复〕	组合包市场	复用 dsh-market 生态实现；清单驱动、只读浏览；安装入口依赖还原点机制，无还原点时不提供安装按钮
O-079	`ondra-installer`	〔研〕	安装流水线	九步：环境探测、组件下载、完整性校验、装配配置、安装组合包、隐私加固、视图设定、首启引导、启动主进程；清单制 Bootstrap，每组件独立 SHA-256 与记账文件，收尾执行 `bootstrap-ok` 自检；多源回退与断点续传
O-080	`ondra-process-host`	〔研〕	子进程托管	以独立进程组启动并重写进程名；pidfile 记录组长；按 pidfile 杀进程组，绝不按命令行模糊匹配杀进程；30 秒就绪窗，异常重启 1 次；端口就绪后再宽限 3 秒等待带令牌地址
O-081	`ondra-window`	〔研〕	窗口	隐藏系统标题栏、红绿灯内嵌并定位；页面顶部保留 44 像素拖动区；预加载脚本只暴露重启一个能力，不开启 Node 集成
O-082	`ondra-onboarding`	〔研〕	首启引导	四段递进（模型来源、人格、称呼与关系、界面偏好）；不使用进程间通信，改为拦截页面导航并从地址回传结果；用户直接关窗视为未完成
O-083	`ondra-port-picker`	〔研〕	端口挑选	在 9060 至 9079 的回环范围内探测可用端口；占用则递增；不监听公网地址
O-084	`ondra-dev-rebrand`	〔研}	开发态改名	复制运行时应用并修改显示名与图标；修改后逐层重新签名，否则系统拒绝启动；避免开发态与正式态在进程列表中混淆

十四、B12 多方案分支（3 个）

编号	插件	档位	功能	实现技术
O-121	`ondra-store-json`	〔研〕	JSONL 持久化后端	与 SQLite 端口同接口；原子写采用临时文件加改名；用于无 SQLite 环境或库损坏时兜底；默认不启用
O-122	`ondra-memory-vector`	〔研〕	向量检索分支与混合检索	向量模型可选；混合检索为 BM25 加向量再加重排；启用条件按记忆条数分级：少于 300 条用纯字面，300 至 1000 条用混合，超过 1000 条用向量加近似最近邻；默认仍以倒排为主
O-123	`ondra-emotion-hormone`	〔研〕	激素扩展	见第五章；与核心三维并存，只读叠加，默认关闭

十五、B13 扩展池（24 个）

扩展池为独立可启停的增强能力，默认全部关闭，核心批次完成后按需启用。

编号	插件	功能
O-097	`ondra-grow`	养成系统：可量化成长与阶段奖励，只读元数据
O-098	`ondra-persona-workshop`	人格包工坊：创建、校验与导出
O-099	`ondra-memory-git`	记忆版本化：可回滚、可审计
O-100	`ondra-memory-heal`	记忆自愈：矛盾检测与修复建议
O-101	`ondra-time-capsule`	时间胶囊：定时投递给未来的话
O-102	`ondra-trust-dashboard`	信任仪表盘：把隐私状态做成可读界面
O-103	`ondra-forget-right`	被遗忘权：软删除与墓碑机制
O-104	`ondra-redteam`	红队评测：越阶率、复读率、空返回率
O-105	`ondra-digital-health`	数字健康护栏：反依赖设计
O-106	`ondra-crisis`	危机干预分级协议
O-107	`ondra-first-meet`	冷启动初见剧本
O-108	`ondra-absence`	空窗期礼仪：以诚实作为人设资产
O-109	`ondra-screen-sense`	屏幕感知陪伴，需显式授权
O-110	`ondra-dev-companion`	开发者陪伴：任务状态可见
O-111	`ondra-ambient`	键鼠反应与桌面物理
O-112	`ondra-theater`	多角色同屏剧场
O-113	`ondra-weekly`	日记周报汇总
O-114	`ondra-webhook-inbox`	外部事件播报收件箱
O-115	`ondra-ritual`	二十四节气与节日仪式
O-116	`ondra-study`	学伴模式：间隔重复
O-117	`ondra-cocreate`	共创模式：写作与头脑风暴
O-118	`ondra-consistency-bench`	人格确定性评测流水线
O-119	`ondra-sandbox`	插件能力分级沙箱
O-120	`ondra-daily-brief`	晨间简报

十六、目录结构

Ondra/├── README.md                     中文主文档├── README_EN.md                  英文完整版├── NOTICE                        第三方依赖与许可声明├── LICENSE                       AGPL-3.0 全文├── package.json                  仓库元信息与根依赖├── .gitignore                    入库排除规则├── cordis/                       插件目录│   ├── ondra-master-plan.md      插件总纲：分层、依赖矩阵、参数速查、纪律│   ├── ondra-plugin-index.md     插件台账：144 项编号、档位、批次、状态│   ├── ondra-persona-skills/     出厂与示例人设（2 个 .skill.zip：哦鲸鲸、夏柠柒）│   ├── ondra-beichen-api/        预留插件位│   └── ondra-our-free-model/     预留插件位├── material/                     文档与素材（随仓库分发）│   ├── Ondra-dev-handbook.md     开发手册（唯一正典）│   ├── image/                    品牌标识与界面预览图（Logo SVG/PNG、背景、三张视图）│   ├── morphicons/               图标库：提取产物、图标集与上游仓库快照│   └── persona/                  角色人设包（10 个 .skill.zip）├── desktop/                      桌面壳与运行时源码│   ├── apps/                     应用入口与构建配置│   ├── packages/                 宿主与客户端包（workspace 包集合）│   ├── docs/                     架构、插件教程、接口参考│   ├── scripts/                  构建与维护脚本│   ├── website/                  官网静态站点│   ├── snapshots/                快照测试基线│   └── vendor/                   源码内置的 Cordis 及基础库（9 项）├── tools/                        开发辅助脚本├── toolchain/                    工具链缓存（不入库，可由安装器重建）├── build/                        安装包输出（不入库）└── .backup/                      本地备份（不入库）

不入库目录说明：toolchain/ 存放便携运行时缓存，build/ 存放打包产物（macOS 的 dmg、Windows 的 nsis 以及解包后的应用目录），.backup/ 存放本地备份。三者均可由构建或安装流程重建，不进入版本库，避免仓库体积失控。

人设包分布：出厂人设与示例人设位于 cordis/ondra-persona-skills/，其余角色人设位于 material/persona/，两处合计 12 个。插件 ondra-persona-loader 同时扫描这两个目录。

十七、安装与运行

git clone https://github.com/ntars/Ondra.gitcd Ondra/desktoppnpm installpnpm run typecheckpnpm start

首次启动执行安装流水线：环境探测、组件下载、完整性校验、装配配置、安装组合包、隐私加固、视图设定、首启引导、启动主进程。数据目录在 macOS 为 ~/Library/Application Support/空谷 Ondra/，在 Windows 为 %APPDATA%\空谷 Ondra\；开发态使用带 -dev 后缀的独立目录，与正式版互不干扰。应用不写入用户主目录下的 dsh 与 agents 配置，不占用 3080 端口。

十八、配置说明

配置分四层，优先级由低到高为出厂默认、组合包默认、用户配置、运行时覆盖；升级只改动前两层。

分类	配置项	默认值
人格	人格包	哦鲸鲸
人格	关系	未设定（五选一）
情绪	心情半衰期	4 小时
情绪	弥散系数	0.4
记忆	衰减档位	standard
记忆	注入预算	2600 字符
记忆	快照保留	3 份
主动	静默时段	23:00–08:00
主动	每日额度	3 条
主动	放弃率	35%
语音	是否朗读	关闭
语音	句长范围	6–30 字
节奏	分条上限	4 条
界面	主题	跟随系统
隐私	会话日志上传	强制关闭

每项改动立即写入后端，不存在仅存于浏览器本地的设置；需要重启生效的项在界面标注；恢复默认按分类执行。

十九、接口与性能

18.1 接口

本地接口挂载固定前缀，需令牌鉴权，请求头为 X-Ondra-Token。核心路由包括状态、对话（流式）、历史、会话、搜索、记忆读写、遗忘、情绪读写、关系阶段、人格读写、日期事实、日记、贴纸、市场、通道开关、通道健康、快照、提示词预览与健康检查。

18.2 实测数据

指标	数值	条件
前缀缓存命中率	99.3%–99.6%	5 个会话、2001 次请求
成本变化	¥879.97 → ¥19.96	启用冻结前缀
工具定义压缩	55154 → 8433 token（84.7%）	启用意图路由门控
浏览器快照压缩	315 KB → 5.4 KB（98%）	启用输出沙箱
记忆注入量	预算内恒定	1000 条封顶 24000 字符
召回截断	0 条	未展开条数可查
衰减示例	98 天前记忆，0 次想起衰减 25.7%	3 次 12.6%，10 次 9.2%
应用包体积	约 1.3 GB	含内置运行时
workspace 包数	399	不含依赖目录的 package.json 计数

未提供冷启动、首屏、首字延迟与内存增长等指标：这些数值受硬件与模型端点影响显著，引用他处数据不具可比性。

二十、安全与隐私

数据本地化：会话、配置、凭据、记忆与工作区文件均位于应用数据目录，默认不上传。
隐私三道防线：配置层关闭会话日志上传（唯一真防线，实测 0/3 次携带）、环境层遥测开关、启动自检每次核对；配置被改动时拒绝启动。
出站清单：仅依赖镜像、运行时下载、模型端点、已启用通道与显式配置的天气接口；不含遥测、崩溃上报、账号校验与更新检查。
文件权限：目录 0700，记忆库与凭据 0600。
本地接口：令牌鉴权、定长比较、同源校验。
记忆不加密是主动取舍：本地加密对同机同用户攻击几乎无防护，却牺牲用户查看、导出与修复数据的能力；真正的防线在网络侧。
高危能力默认关闭：个人号通道、桌面自动化与开发者模式均需显式开启，个人号通道需双闸门确认。

二十一、兼容性与已知限制

20.1 平台

macOS（Apple Silicon 优先，Intel 可用）与 Windows x64 为首发平台；Linux 构建配置在位但未做发布验证；移动端形态待定，宣传口径为即将适配，不作内测承诺。

20.2 运行时

内置 Node.js 24；上游基线为 0.2.2-alpha.2，区间外不保证兼容；本地推理需自备 OpenAI 兼容服务。

20.3 已知限制

144 个插件处于分批交付阶段，未落地能力在界面显式标注「本版未实现」。
需要公网回调的通道必须由用户自备 HTTPS 地址。
群聊不做主动介入，仅响应明确提及。
桌面自动化仅支持单步，写操作逐条确认。
向量检索为可选分支，默认使用关键词与图谱。
部分依赖的许可证归属仍需逐项核对，已在 NOTICE 中标注待确认。

二十二、更新日志

1.0.1

按开发手册重排插件清单为三档复用结构，自研项压缩至 15 项以内。
新增 21 个插件：视觉、语音识别、多模态记忆、缺口池、阈值漂移、八池、器官 ABI、安装自检、爬楼、叙事日志、检索评估、语感统计与上下文治理七件。
服务键统一为连字符命名，强制组合包声明补丁文件。
关系阶段统一为七阶，进度条分母修正为 7。
出厂人设确定为鲸鲸，夏柠柒作为示例包。
双语文档按插件粒度重写，中英文章节一一对应。

1.0.0

首个对外版本，完成对话链路、记忆、情绪、人格、通道、语音与界面主体能力。
完成 macOS 与 Windows 安装包与一键部署流水线。
建立隐私三道防线与启动自检。

二十三、路线图

阶段	内容
近期（内测前）	交付 B0 至 B6：基座、存储与模型网关、记忆纵深、人格与情绪、表达、主动与节制、运行时治理；建成评估集；完成两端安装包冒烟
中期	交付 B7 至 B11：通道、界面、多模态、端侧、系统与交付；上线成长面板与提示词预览；迁入台词库与九步过滤链
远期	交付 B12 与 B13：多方案分支与扩展能力；评估移动端形态；建立人格包开放格式与评测流水线

二十四、参与贡献

缺陷报告：提供复现步骤、预期与实际行为、环境信息与日志片段。
插件开发：遵循 cordis/ondra-master-plan.md 的分层、依赖矩阵与命名规则；每个插件须写明职责、明确不负责的事项、技术来源与隔离自检结论。
文档：中英文同步修改，章节一一对应。
素材：须确认授权范围，不得提交来源不明的文本、图像或音视频。
许可义务：本项目以 AGPL-3.0 发布，分发修改版本须保留 LICENSE 与 NOTICE，并在被索取时提供完整源码。