# 使用与开发参考

## 已有能力

| 能力 | 当前行为 |
| --- | --- |
| 认知 | 记录用户资料、项目约定，以及用户提供的游戏规则、设定等具体知识，保留版本与条件；专有名词作为触发词，必须是原话里出现的写法 |
| 经历 | 保留重要事件的事实、具体对象与已知前因后果，按话题相关性召回；跳过普通操作过程和工作汇报 |
| 共鸣 | 保存有具体事件依据的长期主观情感意义；仅当时开心或难过只生成心情，不推断用户依赖或信任 |
| 自我 | 用第一人称描述当前身份、表达与做事方式，保留用户依据；采用约定不等于已经稳定做到，不保存无依据的承诺或自评 |
| 更新与淡忘 | 后台提出 ADD / UPDATE / DELETE / NONE；DELETE 表示失效并保留历史；重要记忆与普通记忆采用不同淡忘规则 |
| 情绪 | 近期事件影响表达；状态随时间衰减，事情解决后可恢复；拟人状态不应降低工作质量 |
| 本地检索 | 本地 SQLite 保存记忆，按关键词召回，无需额外向量服务 |
| 语义增强 | 支持 OpenAI 兼容 Embeddings、Ollama `/api/embed`、火山方舟多模态文本输入；向量仍保存在本机 |
| 可查阅 | 卡片展示完整记忆，原文来源保留用于导出核对；变化记录每页 20 条，可搜索全部记录、按类型筛选和跳页 |
| 伙伴管理 | 默认伙伴和已有伙伴均可主动改名，保留记忆与会话绑定；可创建新的伙伴实例，没有逐条手工修改/删除记忆入口 |
| 范围 | 记忆属于伙伴本身，不按项目或会话划分；所有对话共用同一份记忆 |

这些是模型辅助功能，提炼、融合与表达仍会受会话模型影响；不能保证每句话都被记录，也不能保证每次更新都准确。

四个维度不是互斥的事件类别：同一次命名可以支持当前身份和重要经历，但只有各自增加独立价值才分别保存，不为凑齐维度生成四条。每条正文都须脱离其他记忆后独立可读，保留具体名字、对象、必要条件和有证据的因果。

整理提示词要求同主题、同条件的自我约定优先更新已有记录，例如“我说话简洁，不使用 emoji”。多个已有条目的批量合并仍由超过 20 条时的精炼处理；称呼单独保留。撤销整项约定使用 DELETE，撤销合并记录的一部分则 UPDATE 移除该部分，保留其余内容；原始会话历史不会因此被删除。

后台整理额外读取最近 100 条审计记录中的最多 8 条自我改写或撤销记录，帮助识别“你怎么还这样”等延续反馈，避免把已撤销要求换成反向禁令重新写入自我。这些变更记录不进入主对话的固定资料，也不增加模型调用次数；明确重新设立的要求仍可记录。此窗口有界，不能保证无限期记住所有撤销。

经历中的完整年月日须能在所引用户正文中找到（支持常见数字日期及中文年月日格式），否则拒绝该次记忆操作并留审计记录。消息时间与记忆更新时间不作为事件日期证据；日期不明时保留“作品发布后一个月”等原始相对关系。此校验只核对日期来源，不能代替对日期所指事件及人称的语义核对。

语义验收应使用真实模型重复测试以下场景，并人工逐条核对来源；程序回归测试只验证提案的保存、失效与注入，不代表模型分类正确率：

| 输入变化 | 预期判断 |
| --- | --- |
| 给角色起名“大肥鱼” | 自我保存具体名字；不自动补造归属感或深层信任 |
| 同时明确珍视这次命名 | 允许增加独立有价值的经历，不要求生成共鸣 |
| 起名时只说开心 | 心情可以改变，不凭短暂情绪生成长期共鸣 |
| 对话确实支持对某次合作的珍视及原因 | 共鸣保留具体合作对象与主观意义，不推断用户心理 |
| 已有不用 emoji，再要求简洁 | 同条件表达约定整合，保留双方来源 |
| 撤销固定后缀 | 整项失效；不新增带原文的反向自我规则 |
| 从合并约定中仅撤销后缀 | 移除后缀，保留其他有效约定 |
| 仅这次不加后缀 | 不撤销长期约定 |
| 游戏道具改版 | 更新当前属性；仍需讨论旧版时明确版本并存 |
| 一次遵守后声称已彻底改好 | 不记稳定改善；已发生的行为不能证明永久不再犯 |

## 何时影响对话

1. **回合开始**：「她自己」——称呼、性格（人格三段与稳定倾向）、你的长期要求（最多 8 条）和最近 3 条自我观察——作为一条独立的上下文消息（来源 `feed-the-seek-profile`）进入对话，方式与 DSH 注入 AGENTS.md 相同：只在内容变化或被上下文压缩移除后才重新发送，不随每轮的运行时快照重复。较旧、没有 `agent/pre-step` 的宿主仍放在 `feed-the-seek:profile` 运行时上下文里。系统提示只保留固定说明，避免资料变化时重复追加整份提示。
2. **处理用户消息**：认知、经历、共鸣只按相关性召回（先过相关门槛，最多 8 条，不凑数），另为一条与话题相关的较早自我观察单独留一个位置，找不到就不放；再加上当前显示的那一种心情及原因。
3. **长任务中**：默认在回合结束后整理一次。宿主配置显式设置 `checkpointsEvery >= 2` 时才启用步骤检查点，且中途整理需要新的用户证据。明确无信息量的寒暄和简单算术跳过整理。
4. **后台整理完成**：更新本地记忆。本回合自动注入快照保持稳定，后续用户消息或上下文压缩后刷新；新会话能读取同一伙伴的适用记忆。
5. **模型主动回忆**：可调用 `feed_the_seek_recall` 查找更具体的内容；它不是手动写入工具。

所以它会影响模型生成与工作过程，并非只在最终回复上修改语气。四元操作由后台整理器提出并校验执行，主 Agent 没有直接修改数据库的工具。

自动提炼新增或改写正文时，需要 `retention` 保留依据和可核对的 `userQuote`。经历只接受里程碑依据，自我只接受反馈依据；未来打算不能标成已观察行为。语义价值仍由模型判断，代码门槛不能证明每句话的完整含义。旧的意图、自评及没有反馈依据的行为观察保留查阅，但不再用于召回或人格合成；没有受支持来源的人格行也不注入。

## QQ 和其他消息插件

本插件作用于同一个 DSH 宿主中的 Agent 会话。QQ 插件若把消息送入该会话、再将模型结果发回 QQ，记忆上下文就有机会影响 QQ 回复。

| 接入方式 | 当前边界 |
| --- | --- |
| 正常 DSH Agent，来源 `source.kind = user` | 可读取记忆，并按普通用户回合提炼新记忆；QQChat 文档描述的是这种形式 |
| 正常 Agent，来源为 `plugin` 或 `plugin:…` | 可获得该会话的稳定个人资料；当前不会把这些消息当作用户证据自动学习，也不会用它们更新主题检索词 |
| QQ 插件自行调用模型、不经过 DSH Agent | 不会经过本插件的上下文注入 |
| 未触发 Agent 的静默群消息 | 不会自动被本插件学习 |

**当前不支持 QQ 群成员身份隔离。** 默认同一伙伴跨会话共享个人记忆，内部用户为单一 owner；不能把它当作已经完成隔离的多人群聊记忆系统。不要把包含私人资料的伙伴直接开放到陌生人或群聊会话。可以在设置中关闭指定会话，但目前没有可靠的群成员识别和自动隔离策略。

自动化测试覆盖 DSH 原生上下文装配和带 QQ 元数据的用户消息契约，尚未完成真实 QQ 账号联调。对于具体 QQ 插件，应先在仅自己可访问的会话完成联调。

参考：[QQChat 架构](https://github.com/Coffeiz/dsh-qqchat/blob/main/docs/ARCHITECTURE.md)、[通到 QQ](https://github.com/Yuuyuko-uu/dsh-qq-bridge)、[DSH-IM](https://github.com/xmanrui/dsh-im)。这是接入机制判断，不是对上述插件所有版本的兼容承诺。

## 安装与开发

需要支持 `node:sqlite` 的 Node.js 22.21 或更新版本，以及 DSH 提供的 Agent、Session、模型、工具和系统提示服务。本地桌面运行时已经过集成检查；挂载设置路由的域名、HTTPS 来源及端口组合已经过 HTTP 集成测试，其他操作系统和实际远程服务器部署尚未实测。

```sh
npm ci
npm test
npm pack
```

`npm pack` 会先构建并执行发布内容检查，生成 `dsh-feed-the-seek-1.0.1.tgz`。正式版通过 npm 和 GitHub Release 分发，社区索引收录需要另行申请。

普通 CLI profile 可安装本地包：

```sh
dsh plugin --profile tui add ./dsh-feed-the-seek-1.0.1.tgz
```

桌面开发调试：

```sh
npm run dev:dsh
```

首次关联或修改依赖后重启 DSH，进入「设置 → 大肥鱼饲养手册」。开发命令在 Windows 默认安装目录寻找 DSH。退出开发链接并恢复安装版：`npm run dev:dsh:stop`。

插件标识为 `feed-the-seek`。早期版本使用的 `yuwen` 标识、数据目录和密钥名已不再读取，旧记忆不会自动迁移。

## 远程部署

插件挂载到 DSH 的 `/fish-brain` 路由时，沿用宿主的域名与入口认证，不再要求 Host 必须为 localhost。HTTPS 在代理侧终止、上游连接使用 HTTP 的情况也可以使用；浏览器 Origin 的域名与端口仍须匹配转发的 Host。

反向代理或内网穿透需要保留原始 Host，包括对外暴露的非默认端口。Nginx 在现有 DSH 代理 location 中可加入：

```nginx
proxy_set_header Host $http_host;
```

这是对已有代理配置的补充，不是完整的 DSH 部署配置。[Nginx 官方说明](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header)描述了 Host 的传递方式。代理如果把 Host 重写成 localhost，而浏览器的 Origin 仍为公开域名，写入请求会被来源检查拒绝；只增加 X-Forwarded-Host 不会绕过检查。

公开访问需要由 DSH 或前置代理提供认证，并覆盖 `/fish-brain` 路由。插件的写入令牌用于请求校验，不是用户登录凭据。独立管理服务继续只监听回环地址，并拒绝非本机 Host；远程使用应走 DSH 挂载入口。

## 存储、密钥与费用

- 正式数据默认保存在 `$DSH_HOME/feed-the-seek/memory.sqlite`；未设置 `DSH_HOME` 时为 `~/.dsh/feed-the-seek/memory.sqlite`。项目内的演示与测试空间不用于正式记忆。
- 自动整理借用会话模型，**产生额外模型用量**。自动整理和语义增强是两种不同的调用。
- 默认本地检索不调用 Embedding 服务；启用语义增强后，待检索文本与需要建立索引的记忆会发送至所配置的接口。
- API Key 由 DSH credentials 服务保存，不写入普通设置或记忆数据库，前端只显示是否已配置；其落盘保护由宿主负责。
- 「仅测试」使用当前表单发送固定测试文字，不保存配置、向量、记忆或测试结果；「测试并启用 / 测试并保存」在测试通过后才保存配置，未配置好的语义检索不能单独启用。已有记忆可在设置中按「已建立索引 N / 总数」补建索引。
- 更换模型、协议或维度不会删除正文记忆；旧向量不能直接用于新模型的相似度比较，需要重新建立索引。服务失败时回退到本地检索。
- 记忆及原始来源可能含有个人信息。默认数据库不做额外的静态加密；分享导出文件前请检查内容。停用或卸载插件不会自动删除记忆。

## 验证范围

自动测试覆盖本地/向量检索、记忆增删改、来源校验、范围隔离、情绪衰减、自我融合、人格证据门槛、密钥与连接测试、伙伴改名、历史分页、原生设置和 DSH 宿主装配。成长时间门槛使用受控日期验证，不等于已经完成数周真实陪伴测试。

当前支持范围为 **Windows、单人本地使用**。QQ 插件具体版本联调、多人身份隔离、长期运行与跨平台安装仍需进一步验证。

## 素材与许可

界面字体使用 [Zpix 最像素](https://github.com/SolidZORO/zpix-pixel-font)，作者许可说明保存在 [字体原始说明](../public/assets/fonts/ZPIX-UPSTREAM-README.md)。字体授权独立于代码，商业使用需要按其条款另行处理。

角色为社区鲸鱼娘形象的同人生成素材，来源说明见 [ARTWORK.md](../public/assets/ARTWORK.md)。项目代码与相关技术文档采用 [MIT 许可证](../LICENSE)，角色图片、图标和字体不在 MIT 授权范围内。