dsh-world 0.6.6 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/CONTRIBUTING.md +163 -161
  3. package/NOTES.md +184 -152
  4. package/README.md +237 -227
  5. package/client/index.js +894 -738
  6. package/lib/archive.d.ts +3 -1
  7. package/lib/archive.js +6 -4
  8. package/lib/compaction.js +8 -0
  9. package/lib/compactionSwap.d.ts +29 -2
  10. package/lib/compactionSwap.js +62 -7
  11. package/lib/console/homeApply.d.ts +11 -2
  12. package/lib/console/homeApply.js +36 -7
  13. package/lib/console/routes.d.ts +13 -0
  14. package/lib/console/routes.js +43 -0
  15. package/lib/console/snapshot.d.ts +8 -0
  16. package/lib/console/snapshot.js +4 -2
  17. package/lib/ecosystem/bridge/route.d.ts +7 -0
  18. package/lib/ecosystem/bridge/route.js +30 -0
  19. package/lib/ecosystem/qq/route.d.ts +2 -1
  20. package/lib/ecosystem/qq/route.js +10 -2
  21. package/lib/ecosystem/qq-native/batch.d.ts +2 -0
  22. package/lib/ecosystem/qq-native/batch.js +3 -1
  23. package/lib/ecosystem/qq-native/index.d.ts +2 -0
  24. package/lib/ecosystem/qq-native/index.js +4 -0
  25. package/lib/ecosystem/qq-native/replies.d.ts +6 -1
  26. package/lib/ecosystem/qq-native/replies.js +19 -1
  27. package/lib/ecosystem/shared/context.d.ts +1 -1
  28. package/lib/ecosystem/shared/context.js +1 -1
  29. package/lib/ecosystem/shared/identity.d.ts +12 -0
  30. package/lib/ecosystem/shared/identity.js +17 -1
  31. package/lib/ecosystem/shared/turn.d.ts +8 -5
  32. package/lib/ecosystem/shared/turn.js +16 -17
  33. package/lib/ecosystem/wechat/archive.d.ts +2 -0
  34. package/lib/ecosystem/wechat/archive.js +3 -1
  35. package/lib/ecosystem/wechat/home.js +9 -4
  36. package/lib/ecosystem/wechat/messages.d.ts +11 -0
  37. package/lib/ecosystem/wechat/messages.js +9 -1
  38. package/lib/ecosystem/wechat/sending.js +36 -9
  39. package/lib/ecosystem/wechat/supervisor.d.ts +11 -2
  40. package/lib/ecosystem/wechat/supervisor.js +90 -9
  41. package/lib/history.d.ts +6 -4
  42. package/lib/history.js +61 -12
  43. package/lib/hostContract.d.ts +1 -0
  44. package/lib/index.js +41 -14
  45. package/lib/life/activity.d.ts +2 -0
  46. package/lib/life/activity.js +1 -1
  47. package/lib/life/alarm.d.ts +12 -4
  48. package/lib/life/alarm.js +21 -6
  49. package/lib/life/diary.d.ts +6 -0
  50. package/lib/life/diary.js +23 -2
  51. package/lib/life/runtime.d.ts +1 -0
  52. package/lib/life/runtime.js +57 -9
  53. package/lib/life/toolRegistry.d.ts +4 -3
  54. package/lib/life/toolRegistry.js +13 -3
  55. package/lib/life/types.d.ts +6 -1
  56. package/lib/memory.d.ts +57 -0
  57. package/lib/memory.js +207 -0
  58. package/lib/memoryFiles.d.ts +50 -0
  59. package/lib/memoryFiles.js +168 -0
  60. package/lib/memoryStore.d.ts +112 -0
  61. package/lib/memoryStore.js +159 -0
  62. package/lib/memoryTools.d.ts +31 -0
  63. package/lib/memoryTools.js +106 -0
  64. package/lib/promptSection.d.ts +2 -0
  65. package/lib/runtime.d.ts +1 -1
  66. package/lib/runtime.js +62 -75
  67. package/lib/sourceArchive.d.ts +1 -0
  68. package/lib/sourceArchive.js +4 -5
  69. package/lib/store.d.ts +15 -1
  70. package/lib/store.js +12 -2
  71. package/lib/types.d.ts +1 -4
  72. package/lib/worldPrompt.d.ts +6 -0
  73. package/lib/worldPrompt.js +8 -2
  74. package/lib/worldSwitch.d.ts +9 -1
  75. package/lib/worldSwitch.js +14 -1
  76. package/package.json +128 -117
  77. package/scripts/compact-home.mjs +29 -0
  78. package/scripts/update-world.mjs +6 -4
  79. package/src/ecosystem/wechat/windows/README.md +7 -5
  80. package/src/ecosystem/wechat/windows/adapter.py +86 -31
  81. package/src/ecosystem/wechat/windows/engine/NOTICE.md +1 -1
  82. package/src/ecosystem/wechat/windows/engine/bridge.cpp +9 -1
  83. package/src/ecosystem/wechat/windows/engine/build.ps1 +8 -2
  84. package/src/ecosystem/wechat/windows/engine/profiles.json +56 -0
  85. package/src/ecosystem/wechat/windows/native.py +4 -1
  86. package/src/ecosystem/wechat/windows/outgoing.py +21 -0
  87. package/src/ecosystem/wechat/windows/sender.py +26 -6
  88. package/templates/alarm.md +3 -4
  89. package/templates/world-prompt-memory.md +10 -0
  90. package/templates/world-prompt.md +7 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,44 @@
1
1
  # 更新日志
2
2
 
3
+ ## 0.7.1 — 2026-11-03
4
+
5
+ 本版修复 QQ / 微信回复偶发丢失(#34),记忆块和微信大幅省 token,归档或记忆出错时她照常说话,控制台可改每日回顾和早上醒来的时间,过去的日记改为只读,微信原生桥过期时插件自己重新构建。原生桥源码与 0.7.0 相同:0.7.0 时已经重新 Build 过的不用再编;没编过的,由插件管理的适配器会自己编。
6
+
7
+ - 修复 QQ / 微信回复偶发丢失(#34):话交进家里时,家正好在跑别的一轮(闹钟、提前停下的追问、压缩、别的入口的话),这句会并进那一轮、她也回了,但插件只按轮次编号等「自己那一轮」,一直等到 10 分钟超时,什么都不发。现在按先后等:话进去之后她说的就是回它的,下一个「这一轮结束」就是它的结束。
8
+ - 别人的话插进同一轮时,她在看到那句之前已经说完的话照样发出去;插话之后的内容可能是说给插话的人的,仍然不发。
9
+ - 记忆块变短(实测约少三分之一):每条只留角色、到分钟的时间和内容;微信 / QQ 的话注明是哪个聊天(`via`)、群里是谁(`who`),她发出去的话注明发没发到(`sent`),归档标识和渠道账号不再放进去。群里两个账号同名时带上尾号区分。
10
+ - 微信 / QQ 消息开头的来源头改成一行短的「【微信私聊「名字」,chatId …】」,不再把完整身份 JSON 放进每条消息;归档时新旧两种格式都认得并去掉。
11
+ - 微信省 token(实测一个窗口约少六成):去掉每条都带的固定收发说明,只有群上下文、图片、引用时才带;待发送记录只写条数,不再把正文重复一遍。
12
+ - 微信没发出或结果不明时,插件给发送的那个会话补一条通知,告诉她前几条已发、第几条不知道、后面没发,不要自动重发;她不用再一遍遍查回执。
13
+ - 归档写不进去、会话日志一时读不出来、记忆块建不出来时,她照常回话,问题进控制台健康;这期间的话在宿主日志里,问题解决后按断点补进归档,不会重复。只有宿主日志在磁盘上坏了、一直读不出来时补不回来。以前这些情况会让她这一轮直接失败。
14
+ - 启动不再从头读每个会话的整份日志(家里常有上万条事件)。
15
+ - 控制台新增「作息」卡片:每日回顾和早上醒来的时间可改,存在 `world.json`;留空回到 23:00 和配置里的 `fallbackWakeTime`。改动后已排好的回顾和早上闹钟立刻跟上,她自己定的闹钟不动;世界停着时改的,下次启动跟上。回顾定在中午以前,回顾的是前一天。已经开着的会话里,工具说明里的早上时间要等新开会话或重启 DSH 才更新。
16
+ - 过去的日记只读:日记目录里按日期命名的 `YYYY-MM-DD.md`,她用 `write` / `edit` 只能改今天的,以及回顾还没做完的那天;改旧日记会被拒绝,并告诉她在今天的日记里写下哪里记错了、现在怎么看。读日记、不按日期命名的文件不受影响;命令行写文件没法可靠分辨,不拦。插件自带的回顾说明补了这一句;世界里有自己 `alarm.md` 的照旧用自己的。
17
+ - 微信原生桥过期时(升级改了 `bridge.cpp`),由插件管理的适配器会自己用随包的 `engine/build.ps1` 重新构建一次,编好再启动,旧的构建目录随之删掉;没有 Visual Studio C++ 构建工具或编译失败时停下不再重试,原因进控制台健康。以前适配器会无声地反复重启,原因只写在适配器日志里。适配器因为别的原因退出时,控制台也显示它退出前说的最后一句。
18
+ - QQ 合批窗口(同一个人连着发几句多少秒内合成一次问)可在 QQ 页修改(PR #29),范围 0–30 秒,一批从第一句起最多等 30 秒;QQ 回复发出前去掉宿主混进来的时间行、来源头和传输引用。
19
+ - 内核整理:「普通会话」的判断合成一处;删掉没人用的 `self` / `knowledge` / `focus` 记忆来源、`memory_find` 的 `history` 参数(旧调用带着也只是被忽略)和多层目录遍历;删掉只在没有归档范围时才走的分支。
20
+
21
+ ## 0.7.0 — 2026-11-02
22
+
23
+ 本版让压缩在 DSH 桌面版上真正可用(含 75% 触发、回顾后压缩和失败可见),修复家和微信群建出空壳会话,微信改为逐聊天暂停并对所有对话缓冲合并,加入长期记忆查找,分清日记与「我是谁」,并加入微信 4.2 版本表。**升级后需在仓库里重新运行 `wechat.ps1 Build`。**
24
+
25
+ - 新增长期记忆的统一查找:`memory_find`、`memory_read` 两个工具(不依赖生活线,随世界会话注册)和控制台「档案」页,覆盖聊天原文和日记;不建索引,聊天在原表里直接按字面扫描、日记在查询时直接读,按字面文字、时间、种类和来源查找,聊天来源在排序和分页前按归档范围过滤。自述照旧全文注入,不进索引。
26
+ - 查找工具的返回变短:`memory_find` 默认 8 条、每条摘录约 200 字,去掉对她没用的字段,`memory_read` 默认读 2000 字;工具结果会在后面每一轮被重发,短一点能明显省输入。
27
+ - 世界提示词补充找回过去的说明;已有的自定义模板不被覆盖,控制台提示缺了哪些变量并给出片段。
28
+ - 修复 DSH 桌面版上「应用并压缩家会话」报“未加载压缩服务”、回顾后自动压缩静默不执行:桌面版把压缩放在会话预设的隔离组里,插件改为从家会话所用的预设取压缩服务,宿主层的服务只作退路(TUI,或在 profile 顶层插入压缩的配置)。
29
+ - 回顾后压缩、主动触发的压缩失败时不再无声:失败原因(含底层报错,如“system update without a preceding user or tool-result turn”)写进健康状态和日志,下次成功后清除。
30
+ - DSH 桌面版上也能换成“只留对话”压缩:profile 里没有原版压缩那一行时,通过 DSH 的配置编辑服务把世界所用的预设整份写进 profile,只换压缩那一行(先备份,重启生效)。代价是这份预设不再跟随 DSH 升级,NOTES.md 写了怎么重新换。
31
+ - 仍然换不成时,健康状态说明 75% 触发线没有生效、压缩仍由预设自带的那个负责;以前这种情况什么都不说。
32
+ - 修复“只留对话”压缩的摘要请求被 DeepSeek 拒绝(system update without a preceding user or tool-result turn):去掉工具结果后,夹在两段回复之间的系统更新(记忆块、工具增减)不再重放进摘要请求,它们在压缩后会重新提供。
33
+ - 修复家打不开、微信群 @ 她返回 503 并留下空壳会话(#27):新会话创建时,插件去读它的日志,部分环境下(Windows 桌面版上有人遇到)宿主此时还找不到这个会话,读取失败让整个创建失败,每次重试都多一个空壳、绑定也写不进去。现在读不到时按全新会话处理;记忆初始化即使失败也不再拖垮宿主建会话,第一次请求前会再试,失败仍留在健康状态里。
34
+ - 微信:一条消息结果不明待核对时,只暂停这一个聊天的接收,其他聊天照常;以前一个群出错会把私聊也一起停住,直到人工核对。
35
+ - 微信消息缓冲改为所有对话都有:收到要交给她的消息后先等 3 秒,同一个人又发来消息就重新计时,安静下来再合成一条交给她(最长 30 秒、最多 16 条、不超过 2000 字);群聊只有叫到她的那条会等。以前只有私聊图片会等一条说明文字。
36
+ - 微信适配器加入 4.2.0.11 / 4.2.0.12 的版本表(取自上游 helper,未经本项目实机验证)。4.2 上不能发原生 GIF 表情,表情包改为截取一帧(第一帧,空白时取最后一帧)作为图片发送。原生桥源码因此改动,**升级后需重新运行 `wechat.ps1 Build`**。
37
+ - 世界提示词与每日回顾把「日记」和「我是谁」分清:日记记发生过的事和当时的感受,不自动读给她;「我是谁」只写现在的她(性格、喜好、看法、说话方式、和伙伴的关系),不写日期和当天的事,每次全文读给她所以要短。每日回顾改为先写日记、再看自己有没有变,变化提炼成一两句合并进「我是谁」,不从日记搬内容。只改插件自带模板:世界目录里已有自己的 `world-prompt.md` / `alarm.md` 的,照旧用自己的,不被覆盖。
38
+ - 开发:必需的 DSH 对等依赖在开发依赖里锁到 0.2.1-rc.2,lock 文件改用官方源重新生成;以前 `npm ci` 会把对等依赖解析到 rc.5,与锁在 rc.2 的包冲突(ERESOLVE),CI 自 0.6.6 起装不上依赖。
39
+ - 更新器在 Git Bash 下也能读压缩包:GNU tar 会把 `C:` 当成远程主机,改为在压缩包所在目录里按文件名读取。
40
+ - 新增 `scripts/compact-home.mjs`:开启 `bridge` 后,可从本机(或计划任务)请求压缩一次家会话,与控制台的「应用并压缩」同一路径。
41
+
3
42
  ## 0.6.6 — 2026-10-30
4
43
 
5
44
  本版调整压缩触发与默认值、让每日回顾后的压缩更稳,把微信和 QQ 改为默认关闭,并把注意事项整理进 `NOTES.md`。
package/CONTRIBUTING.md CHANGED
@@ -1,161 +1,163 @@
1
- # 贡献协议
2
-
3
- 欢迎为 dsh-world 接入新的聊天平台、桌宠或其他外部程序,也欢迎改进内核。生态模块负责平台收发,复用现有身份、会话和归档能力,依赖一律可选;涉及内核的修改必须单独说明,改动生活线核心之前先开 Issue。
4
-
5
- ## 分支与 PR
6
-
7
- **所有 PR 统一提到 `dev` 分支**,不要直接提到 `main`。
8
-
9
- - `dev`:集成分支。从最新的 `dev` 切出你的分支,改完后向 `dev` 提 PR;维护者在这里合并、验证。
10
- - `main`:稳定分支,由维护者把 `dev` 的内容并入后发布,不直接接收 PR。
11
- - `test`:维护者本机试用的分支,不接收 PR,也不要基于它开发。
12
- - 已经把 PR 提到 `main` 的,请在 PR 页面右上角 **Edit** 里把 base 改成 `dev`;GitHub 默认会选 `main`,提交前请再看一眼目标分支。
13
- - 提 PR 前至少运行 `npm run typecheck` 和 `npm test`,PR 描述按下文「提交说明」填写,并写明是否涉及内核。
14
- - **一个 PR 只做一件事。** PR 开着期间只修这件事的问题,新功能另开 PR;不要在已开的 PR 上持续追加功能,也不要把已关闭 PR 的内容带进别的 PR。基于过旧分支、与当前版本大量冲突的 PR,维护者可能只采用其中的思路自行重写。
15
-
16
- ## 新模块放在哪里
17
-
18
- | 位置 | 职责 |
19
- | --- | --- |
20
- | `src/ecosystem/<channel>/` | 平台自己的接口、消息解析、收发编排、配置和说明文档。例如 QQ 放 `qq/`,B 站放 `bilibili/` |
21
- | `src/ecosystem/<channel>/windows/` 等平台子目录 | 确实需要的本机适配器、启动脚本或原生桥;目录按实际运行环境新增 |
22
- | `src/ecosystem/shared/` | 已有的通用身份、群上下文、会话路由和消息出口;新增公用函数应有实际复用方 |
23
- | `src/ecosystem/bridge/` | 桌宠等本地程序共用的桥;能使用现有协议时直接接入 |
24
- | `tests/` | TypeScript 回归测试;本机适配器测试可与适配器放在一起,按微信模块现有方式组织 |
25
- | `.host/<channel>/` | 本机配置、凭据、依赖环境、运行状态和构建产物,不提交、不打入发布包 |
26
-
27
- 每个平台在自己的目录提供 `README.md`,写清依赖、支持的消息类型、启停和配置方法、身份参数映射、验证范围及平台风险。同步更新 [生态目录说明](src/ecosystem/README.md) 和根 [介绍文档](README.md) 的入口。QQ、B 站目录是新增位置示例,不表示当前已接入。
28
-
29
- 需要新增配置、注册模块或清理资源时,在 `src/index.ts`、`src/types.ts` 等现有位置做必要的接线;平台解析和收发逻辑仍留在自身模块中。模块应能独立启停,关闭后释放监听、路由和连接,不影响其他生态。
30
-
31
- ## 统一身份、会话与记忆
32
-
33
- - 复用 `shared/identity.ts` 的 `SpeakerIdentity` 和校验函数,明确映射 `channel`、`accountId`、`conversationId`、`speakerId`;按平台能力提供聊天类型、消息 ID、显示名和真实 @ 列表。
34
- - ID 使用字符串,`speakerId`、`mentionIds` 使用 `<channel>:<平台用户 ID>`。身份来自经过校验的平台事件或账号数据,不从消息正文、昵称或模型输出推断,不因昵称相同合并用户。
35
- - 外部发言人保持 `role: user`,用结构化身份区分来源。群触发使用平台真实 @ 元数据,手打 `@昵称` 不等同于真实 @。
36
- - 会话按平台、登录账号、聊天类型和会话 ID 区分;群会话复用 `shared/sessions.ts`,放在家所在的工作区。平台模块不另建一份人设或共享记忆。
37
- - 正文通过现有归档服务保存,遵守 `home` / `workspace` 范围、配置轮数、消息实际时间排序和重启生效规则。普通工具参数、查询回执、群图片上下文不直接写入共享记忆;群图片保留在对应会话日志中。
38
- - 接收、投递和归档状态应明确区分;排队成功不能当作发送成功。重连保留去重游标和确认状态,结果不明的发送不能直接重试。
39
-
40
- 以上约定如需改变,应按下节说明内核影响,不能在某个平台内悄悄绕过。
41
-
42
- ## 世界的作用范围
43
-
44
- 她的世界只在房间工作区内生效。记忆块、世界提示词、世界线工具、各平台通道和归档,只进入工作区内匹配预设的普通会话;工作区外只允许两项影响:人设(映射到系统提示词)和启用后的只留对话压缩。新增的注入、工具和事件处理必须遵守这条边界:
45
-
46
- - 判断会话是否属于她的世界,用 `sourceArchive.ts` 的 `inWorld`;拦截、守卫和重新组装分别用 `src/worldScope.ts` 的 `admit`、`scopedTool`、`reassembleOnChange`。每次等待之后、注入之前都要重新判断,不能只在开始时查一次。
47
- - 监听 `session/event` 等全局事件时,先筛出她的会话(家会话或工作区内的会话),不能对所有会话生效。宿主里同时还有用户的其他工作,比如写代码的会话,插件不能读取、推送或改动它们。
48
-
49
- ## 生活线与她的主动性
50
-
51
- dsh-world 养的是一个伙伴,不是一个按日程执行的助手。**她的主动性来自她自己的安排,而不是插件推送的提醒。**
52
-
53
- - 生活线只有一个闹钟:她用 `plan_next` 说好做什么、做到几点,到点由她决定接着做还是换下一件。插件自己唤醒她的,只有新家的第一句话、重新开始的那句话、每日回顾和早上的兜底闹钟。不要另建第二套日程、习惯或提醒系统。
54
- - 插件不往对话里推提醒、清单或定时消息,尤其不能插在伙伴说话的那一轮前面。想让她留意某件事,应该给她能感知的事实(比如在她自己的闹钟消息里附上状态),去不去看、做不做,由她决定。
55
- - 工具给她能力,不替她做决定,也不替她读写自己的东西:日记、我是谁和房间里的文件,由她用宿主自带的文件工具读写(`read` 支持 `offset` / `limit`,`grep` 返回行号)。日记、我是谁和聊天记录的检索与索引,计划和记忆总归档一起设计,不接受只管单一来源的检索工具。
56
- - 已经移除的生活线功能(例如 `read_diary`、QQ 的“主动开口”引擎),不能在 PR 里直接加回来,要先开 Issue 说明为什么现有方式不够。
57
-
58
- 改动闹钟、家会话、每日回顾、世界提示词、记忆块注入,或者给她新增工具,都属于生活线核心改动:**先开 Issue 讨论,再写代码**,并在 PR 里按下节说明内核影响。
59
-
60
- ## 涉及内核时必须说明
61
-
62
- 这里的“内核”指 dsh-world 的公共行为,不仅指某个目录:
63
-
64
- | 影响区域 | 现有位置举例 |
65
- | --- | --- |
66
- | 记忆生成、归档范围、历史回填、存储和压缩 | `src/runtime.ts`、`archive*.ts`、`sourceArchive.ts`、`store.ts`、`history.ts`、`compaction*.ts` |
67
- | 世界的作用范围(工作区) | `src/worldScope.ts`、`archiveSelection.ts`、`workspacePermissions.ts` |
68
- | 人设、世界提示、时间上下文和世界开关 | `src/persona.ts`、`worldPrompt.ts`、`timeContext.ts`、`worldSwitch.ts` 等 |
69
- | 家会话、生活线、每日回顾和宿主适配 | `src/life/`、`src/hostContract.ts` |
70
- | 公共协议、配置、模块生命周期和控制台 | `src/ecosystem/shared/`、`src/index.ts`、`src/types.ts`、`src/console/`、`client/` |
71
-
72
- 提交说明中必须写明“是否涉及内核”。新增平台的配置与注册接线也要列出,说明是否改变已有行为。涉及内核时补充:
73
-
74
- 1. 修改了哪些文件、接口或数据格式,为什么现有扩展点不足以完成接入。
75
- 2. 修改前后的行为,以及对家、其他平台、归档范围、人设、生活线和权限的影响;不受影响的部分可合并说明。
76
- 3. 旧配置、旧会话、归档和待发送队列如何兼容;是否需要迁移或重启,升级失败如何保留原数据。
77
- 4. 对应回归测试、验证结果,以及未验证的宿主版本、平台或真实账号条件。
78
-
79
- 本项目内核与 DSH 宿主需要区分。若方案还依赖修改 DSH 本身,应另外列出宿主版本、补丁或依赖、安装方式和兼容范围,不能把它描述为插件即可独立使用。
80
-
81
- ## 代码设计
82
-
83
- - **先找已有的,再写新的。** 各平台“送一句话、等她这一轮的回复”用 `ecosystem/shared/turn.ts` 的 `askTurn` 和 `createChannelQueue`(排队、超时、取消);群上下文用 `shared/context.ts`;身份用 `shared/identity.ts`;作用范围见上文。不要在模块里再抄一份串行队列、回复判断或超时逻辑;已有实现不够用时,改它并说明原因。
84
- - **按职责拆文件。** 一个文件只负责一件事,解析、排队、重试、编排分开放。模块入口只做接线,不要把所有功能堆进一个几百行的 `index.ts`。
85
- - **不留历史痕迹。** 删除或替换功能时,连同配置、文档、测试、注释和面板控件一起清理;不留孤立注释、只写不读的变量和不再生效的配置项。
86
- - **用结构判断,不靠巧合。** 判断“这一轮是谁开的、回给谁”,看事件来源和会话归属,不要用“现在有没有正在处理的请求”“几秒内发过同样的文字”这类旁证去重或补救。
87
- - **配置和面板一致。** 面板上能改的设置要写进同一份覆盖文件,一次请求里给的几项一起生效;新增配置项同步更新 `src/types.ts`、配置 schema、README 的配置示例和对应文档。
88
-
89
- ## 外部依赖
90
-
91
- 插件主体必须在只装必要依赖的情况下装得上、跑得起来。生态模块一律按“可选”设计:
92
-
93
- - **默认不加新依赖。** 能用宿主服务、Node 内置模块或已有依赖完成的,不引入新包。确实需要时,先开 Issue 说明用途、体积、许可证和替代方案,得到同意再提交。
94
- - **平台 SDK 只能是可选依赖。** 由使用者另行安装的 SDK 声明为可选 peer(`peerDependenciesMeta.optional: true`),开发测试所需版本放在 `devDependencies`。只在模块被拨开时动态 `import`;模块默认关闭,没装 SDK 时只显示该模块不可用,不能影响插件本身和其他模块。不要通过安装脚本修补 SDK 文件。
95
- - **不自动安装或部署第三方程序。** 涉及启动外部程序(例如 SnowLuma)的功能,在模块文档和 PR 中写明其许可条款允许的方式,以及是否默认开启。
96
- - **SDK 按需安装必须由使用者明确开启模块触发。** 复用宿主包管理操作与 profile 写锁,禁用生命周期脚本,不修改 SDK 文件或自动升级 Node;安装失败保留原 profile 配置,安装后需要重启时明确提示。客户端程序的安装与登录仍由使用者处理。
97
-
98
- ## 实现与验证
99
-
100
- - 优先复用已有函数、宿主服务和依赖,通过参数或现有注入机制传入依赖。平台细节留在模块内,不为单个平台新增通用框架;替换旧实现时清理失效代码。
101
- - 查询接口搭配分页设计;配置、ID、路径和外部消息在边界校验,不硬编码真实账号或本机路径。错误应明确返回并保留必要状态,不吞错或伪报成功;成组的数据变更保持事务一致性。
102
- - 确认 `package.json` 的 `files`、导出和构建配置覆盖必要产物,同时排除凭据、数据库、聊天记录和个人媒体。
103
- - 代码修改按影响运行 `npm run typecheck`、`npm test`、`npm run build`,补充相关适配器测试。**每个新功能都要有回归测试**,非平凡逻辑至少一个有意义的用例;只改断言让旧测试通过不算覆盖新行为。测试不得启动或连接本机真实的第三方程序。仅文档修改检查格式与链接即可。
104
- - 真实账号测试与单元测试分开说明:使用什么环境、实际确认了什么、哪些条件尚未验证。涉及第三方协议或客户端内部调用时,在模块文档中说明版本限制、账号及数据风险,不能宣称保证不触发风控。
105
-
106
- ## CI 与安装包验证
107
-
108
- [CI](.github/workflows/ci.yml) 在 PR、`main` 推送和手动触发时运行 Windows / Linux 两条完整检查任务,使用满足开发测试 SDK 要求的 Node 24.22.1。两端执行禁用安装脚本的干净安装、类型检查、全部 Node 回归测试、编译和安装包验证;Windows 另用 Python 3.11 安装固定的微信适配器依赖并跑离线测试。另有 Node 22.16.0 核心入口检查,确认 SDK 不可用时核心仍能加载。相同分支的新运行会取消旧运行,各项独立报告结果。
109
-
110
- 本机可按以下 PowerShell 命令复现 Node 与安装包检查:
111
-
112
- ```powershell
113
- npm ci --ignore-scripts
114
- npm run typecheck
115
- npm test
116
- npm run build
117
- New-Item -ItemType Directory -Force artifacts | Out-Null
118
- npm pack --ignore-scripts --pack-destination artifacts
119
- npm run test:package
120
- ```
121
-
122
- 安装与打包均禁用生命周期脚本,类型检查和编译由前面的命令显式执行。`test:package` 在本仓库 `.host/` 下创建临时消费项目,安装真实 `.tgz` 及其生产依赖,复用父目录提供的 DSH 宿主依赖;先确认未安装 SDK 时核心入口可加载,再另行安装 SDK,检查编译后 QQ 驱动的本地 WebSocket 连接,全程不修补 SDK 文件,结束后清理临时项目。检查不需要 DSH profile、微信进程或真实账号。
123
-
124
- ### npm 发布(维护者)
125
-
126
- 使用上述检查生成的同一个 `.tgz` 发布,避免发布时重新构建出不同内容。包已通过 `publishConfig` 指定 npm 官方源和公开访问;先完成发布预检:
127
-
128
- ```powershell
129
- npm publish .\artifacts\dsh-world-0.6.5.tgz --dry-run --ignore-scripts --registry=https://registry.npmjs.org/
130
- ```
131
-
132
- 确定发布后,用有包发布权限的 npm 账号登录,按 npm 提示完成浏览器和二次验证,再执行:
133
-
134
- ```powershell
135
- npm login --registry=https://registry.npmjs.org/
136
- npm publish .\artifacts\dsh-world-0.6.5.tgz --ignore-scripts --access public --registry=https://registry.npmjs.org/
137
- ```
138
-
139
- 首次发布会创建该包;之后每次发布都要提升版本号,同一个包名和版本不能覆盖。发布成功后使用者可按 [安装说明](INSTALL.md#第一步把-dsh-world-装进-profile) 从 npm 安装或更新。后续版本替换示例中的版本号。流程依据 [npm 发布文档](https://docs.npmjs.com/cli/v11/commands/npm-publish/);npm 登录信息和令牌不要写进仓库。
140
-
141
- 每个平台检查通过后,CI 上传 `artifacts/` 中的 `.tgz` 供下载。CI 不替代桌面端和真实账号验收。
142
-
143
- ## 提交说明
144
-
145
- 可按以下结构提交 Issue 或 PR;未知内容写“未验证”,不要填成已完成:
146
-
147
- ```text
148
- 目标分支:dev(PR 必填)
149
- 新增或修改的生态:
150
- 模块目录与接入方式:
151
- 支持的消息、身份映射与会话路由:
152
- 是否涉及内核:否 / 是(文件、原因、行为和影响)
153
- 是否改动生活线核心或给她新增工具:否 / 是(对应的 Issue)
154
- 新增依赖:无 / 有(为什么必须、是否可选、默认是否加载、许可证、对应的 Issue)
155
- 依赖与许可:
156
- 兼容、迁移与重启要求:
157
- 验证命令与结果:
158
- 已知限制与未验证项:
159
- ```
160
-
161
- 贡献遵循对应文件现有许可。仓库主体采用 [MIT](LICENSE),微信原生发送引擎另有 [独立许可](src/ecosystem/wechat/windows/engine/LICENSE) 与 [来源说明](src/ecosystem/wechat/windows/engine/NOTICE.md),不可按根目录 MIT 许可重新分发该部分。提交第三方代码时保留原许可与来源,不提交无权公开的代码或数据。
1
+ # 贡献协议
2
+
3
+ 欢迎为 dsh-world 接入新的聊天平台、桌宠或其他外部程序,也欢迎改进内核。生态模块负责平台收发,复用现有身份、会话和归档能力,依赖一律可选;涉及内核的修改必须单独说明,改动生活线核心之前先开 Issue。
4
+
5
+ ## 分支与 PR
6
+
7
+ **所有 PR 统一提到 `dev` 分支**,不要直接提到 `main`。
8
+
9
+ - `dev`:集成分支。从最新的 `dev` 切出你的分支,改完后向 `dev` 提 PR;维护者在这里合并、验证。
10
+ - `main`:稳定分支,由维护者把 `dev` 的内容并入后发布,不直接接收 PR。
11
+ - `test`:维护者本机试用的分支,不接收 PR,也不要基于它开发。
12
+ - 已经把 PR 提到 `main` 的,请在 PR 页面右上角 **Edit** 里把 base 改成 `dev`;GitHub 默认会选 `main`,提交前请再看一眼目标分支。
13
+ - 提 PR 前至少运行 `npm run typecheck` 和 `npm test`,PR 描述按下文「提交说明」填写,并写明是否涉及内核。
14
+ - **一个 PR 只做一件事。** PR 开着期间只修这件事的问题,新功能另开 PR;不要在已开的 PR 上持续追加功能,也不要把已关闭 PR 的内容带进别的 PR。基于过旧分支、与当前版本大量冲突的 PR,维护者可能只采用其中的思路自行重写。
15
+
16
+ ## 新模块放在哪里
17
+
18
+ | 位置 | 职责 |
19
+ | --- | --- |
20
+ | `src/ecosystem/<channel>/` | 平台自己的接口、消息解析、收发编排、配置和说明文档。例如 QQ 放 `qq/`,B 站放 `bilibili/` |
21
+ | `src/ecosystem/<channel>/windows/` 等平台子目录 | 确实需要的本机适配器、启动脚本或原生桥;目录按实际运行环境新增 |
22
+ | `src/ecosystem/shared/` | 已有的通用身份、群上下文、会话路由和消息出口;新增公用函数应有实际复用方 |
23
+ | `src/ecosystem/bridge/` | 桌宠等本地程序共用的桥;能使用现有协议时直接接入 |
24
+ | `tests/` | TypeScript 回归测试;本机适配器测试可与适配器放在一起,按微信模块现有方式组织 |
25
+ | `.host/<channel>/` | 本机配置、凭据、依赖环境、运行状态和构建产物,不提交、不打入发布包 |
26
+
27
+ 每个平台在自己的目录提供 `README.md`,写清依赖、支持的消息类型、启停和配置方法、身份参数映射、验证范围及平台风险。同步更新 [生态目录说明](src/ecosystem/README.md) 和根 [介绍文档](README.md) 的入口。QQ、B 站目录是新增位置示例,不表示当前已接入。
28
+
29
+ 需要新增配置、注册模块或清理资源时,在 `src/index.ts`、`src/types.ts` 等现有位置做必要的接线;平台解析和收发逻辑仍留在自身模块中。模块应能独立启停,关闭后释放监听、路由和连接,不影响其他生态。
30
+
31
+ ## 统一身份、会话与记忆
32
+
33
+ - 复用 `shared/identity.ts` 的 `SpeakerIdentity` 和校验函数,明确映射 `channel`、`accountId`、`conversationId`、`speakerId`;按平台能力提供聊天类型、消息 ID、显示名和真实 @ 列表。
34
+ - ID 使用字符串,`speakerId`、`mentionIds` 使用 `<channel>:<平台用户 ID>`。身份来自经过校验的平台事件或账号数据,不从消息正文、昵称或模型输出推断,不因昵称相同合并用户。
35
+ - 外部发言人保持 `role: user`,用结构化身份区分来源。群触发使用平台真实 @ 元数据,手打 `@昵称` 不等同于真实 @。
36
+ - 会话按平台、登录账号、聊天类型和会话 ID 区分;群会话复用 `shared/sessions.ts`,放在家所在的工作区。平台模块不另建一份人设或共享记忆。
37
+ - 正文通过现有归档服务保存,遵守 `home` / `workspace` 范围、配置轮数、消息实际时间排序和重启生效规则。普通工具参数、查询回执、群图片上下文不直接写入共享记忆;群图片保留在对应会话日志中。
38
+ - 接收、投递和归档状态应明确区分;排队成功不能当作发送成功。重连保留去重游标和确认状态,结果不明的发送不能直接重试。
39
+
40
+ - 长期记忆(`memoryStore.ts`、`memory.ts`、`memoryTools.ts`)是聊天与日记的统一入口,直接扫描原表和文件,不存第二份数据、不建索引;读不到的来源只报告,不回滚、不删除已提交的聊天;查询必须参数绑定、分页、按调用者范围在排序前过滤聊天来源,身份和世界由宿主提供,工具参数不能指定它们。新的来源类型要说明它的时间含义(`timeBasis`)和范围规则,不另开一套检索。
41
+
42
+ 以上约定如需改变,应按下节说明内核影响,不能在某个平台内悄悄绕过。
43
+
44
+ ## 世界的作用范围
45
+
46
+ 她的世界只在房间工作区内生效。记忆块、世界提示词、世界线工具、各平台通道和归档,只进入工作区内匹配预设的普通会话;工作区外只允许两项影响:人设(映射到系统提示词)和启用后的只留对话压缩。新增的注入、工具和事件处理必须遵守这条边界:
47
+
48
+ - 判断会话是否属于她的世界,用 `sourceArchive.ts` 的 `inWorld`;拦截、守卫和重新组装分别用 `src/worldScope.ts` 的 `admit`、`scopedTool`、`reassembleOnChange`。每次等待之后、注入之前都要重新判断,不能只在开始时查一次。
49
+ - 监听 `session/event` 等全局事件时,先筛出她的会话(家会话或工作区内的会话),不能对所有会话生效。宿主里同时还有用户的其他工作,比如写代码的会话,插件不能读取、推送或改动它们。
50
+
51
+ ## 生活线与她的主动性
52
+
53
+ dsh-world 养的是一个伙伴,不是一个按日程执行的助手。**她的主动性来自她自己的安排,而不是插件推送的提醒。**
54
+
55
+ - 生活线只有一个闹钟:她用 `plan_next` 说好做什么、做到几点,到点由她决定接着做还是换下一件。插件自己唤醒她的,只有新家的第一句话、重新开始的那句话、每日回顾和早上的兜底闹钟。不要另建第二套日程、习惯或提醒系统。
56
+ - 插件不往对话里推提醒、清单或定时消息,尤其不能插在伙伴说话的那一轮前面。想让她留意某件事,应该给她能感知的事实(比如在她自己的闹钟消息里附上状态),去不去看、做不做,由她决定。
57
+ - 工具给她能力,不替她做决定,也不替她读写自己的东西:日记、我是谁和房间里的文件,由她用宿主自带的文件工具读写(`read` 支持 `offset` / `limit`,`grep` 返回行号)。日记、我是谁和聊天记录的检索,计划和记忆总归档一起设计,不接受只管单一来源的检索工具。
58
+ - 已经移除的生活线功能(例如 `read_diary`、QQ 的“主动开口”引擎),不能在 PR 里直接加回来,要先开 Issue 说明为什么现有方式不够。
59
+
60
+ 改动闹钟、家会话、每日回顾、世界提示词、记忆块注入,或者给她新增工具,都属于生活线核心改动:**先开 Issue 讨论,再写代码**,并在 PR 里按下节说明内核影响。
61
+
62
+ ## 涉及内核时必须说明
63
+
64
+ 这里的“内核”指 dsh-world 的公共行为,不仅指某个目录:
65
+
66
+ | 影响区域 | 现有位置举例 |
67
+ | --- | --- |
68
+ | 记忆生成、归档范围、历史回填、存储和压缩 | `src/runtime.ts`、`archive*.ts`、`sourceArchive.ts`、`store.ts`、`history.ts`、`compaction*.ts` |
69
+ | 世界的作用范围(工作区) | `src/worldScope.ts`、`archiveSelection.ts`、`workspacePermissions.ts` |
70
+ | 人设、世界提示、时间上下文和世界开关 | `src/persona.ts`、`worldPrompt.ts`、`timeContext.ts`、`worldSwitch.ts` 等 |
71
+ | 家会话、生活线、每日回顾和宿主适配 | `src/life/`、`src/hostContract.ts` |
72
+ | 公共协议、配置、模块生命周期和控制台 | `src/ecosystem/shared/`、`src/index.ts`、`src/types.ts`、`src/console/`、`client/` |
73
+
74
+ 提交说明中必须写明“是否涉及内核”。新增平台的配置与注册接线也要列出,说明是否改变已有行为。涉及内核时补充:
75
+
76
+ 1. 修改了哪些文件、接口或数据格式,为什么现有扩展点不足以完成接入。
77
+ 2. 修改前后的行为,以及对家、其他平台、归档范围、人设、生活线和权限的影响;不受影响的部分可合并说明。
78
+ 3. 旧配置、旧会话、归档和待发送队列如何兼容;是否需要迁移或重启,升级失败如何保留原数据。
79
+ 4. 对应回归测试、验证结果,以及未验证的宿主版本、平台或真实账号条件。
80
+
81
+ 本项目内核与 DSH 宿主需要区分。若方案还依赖修改 DSH 本身,应另外列出宿主版本、补丁或依赖、安装方式和兼容范围,不能把它描述为插件即可独立使用。
82
+
83
+ ## 代码设计
84
+
85
+ - **先找已有的,再写新的。** 各平台“送一句话、等她这一轮的回复”用 `ecosystem/shared/turn.ts` 的 `askTurn` 和 `createChannelQueue`(排队、超时、取消);群上下文用 `shared/context.ts`;身份用 `shared/identity.ts`;作用范围见上文。不要在模块里再抄一份串行队列、回复判断或超时逻辑;已有实现不够用时,改它并说明原因。
86
+ - **按职责拆文件。** 一个文件只负责一件事,解析、排队、重试、编排分开放。模块入口只做接线,不要把所有功能堆进一个几百行的 `index.ts`。
87
+ - **不留历史痕迹。** 删除或替换功能时,连同配置、文档、测试、注释和面板控件一起清理;不留孤立注释、只写不读的变量和不再生效的配置项。
88
+ - **用结构判断,不靠巧合。** 判断“这一轮是谁开的、回给谁”,看事件来源和会话归属,不要用“现在有没有正在处理的请求”“几秒内发过同样的文字”这类旁证去重或补救。
89
+ - **配置和面板一致。** 面板上能改的设置要写进同一份覆盖文件,一次请求里给的几项一起生效;新增配置项同步更新 `src/types.ts`、配置 schema、README 的配置示例和对应文档。
90
+
91
+ ## 外部依赖
92
+
93
+ 插件主体必须在只装必要依赖的情况下装得上、跑得起来。生态模块一律按“可选”设计:
94
+
95
+ - **默认不加新依赖。** 能用宿主服务、Node 内置模块或已有依赖完成的,不引入新包。确实需要时,先开 Issue 说明用途、体积、许可证和替代方案,得到同意再提交。
96
+ - **平台 SDK 只能是可选依赖。** 由使用者另行安装的 SDK 声明为可选 peer(`peerDependenciesMeta.optional: true`),开发测试所需版本放在 `devDependencies`。只在模块被拨开时动态 `import`;模块默认关闭,没装 SDK 时只显示该模块不可用,不能影响插件本身和其他模块。不要通过安装脚本修补 SDK 文件。
97
+ - **不自动安装或部署第三方程序。** 涉及启动外部程序(例如 SnowLuma)的功能,在模块文档和 PR 中写明其许可条款允许的方式,以及是否默认开启。
98
+ - **SDK 按需安装必须由使用者明确开启模块触发。** 复用宿主包管理操作与 profile 写锁,禁用生命周期脚本,不修改 SDK 文件或自动升级 Node;安装失败保留原 profile 配置,安装后需要重启时明确提示。客户端程序的安装与登录仍由使用者处理。
99
+
100
+ ## 实现与验证
101
+
102
+ - 优先复用已有函数、宿主服务和依赖,通过参数或现有注入机制传入依赖。平台细节留在模块内,不为单个平台新增通用框架;替换旧实现时清理失效代码。
103
+ - 查询接口搭配分页设计;配置、ID、路径和外部消息在边界校验,不硬编码真实账号或本机路径。错误应明确返回并保留必要状态,不吞错或伪报成功;成组的数据变更保持事务一致性。
104
+ - 确认 `package.json` 的 `files`、导出和构建配置覆盖必要产物,同时排除凭据、数据库、聊天记录和个人媒体。
105
+ - 代码修改按影响运行 `npm run typecheck`、`npm test`、`npm run build`,补充相关适配器测试。**每个新功能都要有回归测试**,非平凡逻辑至少一个有意义的用例;只改断言让旧测试通过不算覆盖新行为。测试不得启动或连接本机真实的第三方程序。仅文档修改检查格式与链接即可。
106
+ - 真实账号测试与单元测试分开说明:使用什么环境、实际确认了什么、哪些条件尚未验证。涉及第三方协议或客户端内部调用时,在模块文档中说明版本限制、账号及数据风险,不能宣称保证不触发风控。
107
+
108
+ ## CI 与安装包验证
109
+
110
+ [CI](.github/workflows/ci.yml) 在 PR、`main` 推送和手动触发时运行 Windows / Linux 两条完整检查任务,使用满足开发测试 SDK 要求的 Node 24.22.1。两端执行禁用安装脚本的干净安装、类型检查、全部 Node 回归测试、编译和安装包验证;Windows 另用 Python 3.11 安装固定的微信适配器依赖并跑离线测试。另有 Node 22.16.0 核心入口检查,确认 SDK 不可用时核心仍能加载。相同分支的新运行会取消旧运行,各项独立报告结果。
111
+
112
+ 本机可按以下 PowerShell 命令复现 Node 与安装包检查:
113
+
114
+ ```powershell
115
+ npm ci --ignore-scripts
116
+ npm run typecheck
117
+ npm test
118
+ npm run build
119
+ New-Item -ItemType Directory -Force artifacts | Out-Null
120
+ npm pack --ignore-scripts --pack-destination artifacts
121
+ npm run test:package
122
+ ```
123
+
124
+ 安装与打包均禁用生命周期脚本,类型检查和编译由前面的命令显式执行。`test:package` 在本仓库 `.host/` 下创建临时消费项目,安装真实 `.tgz` 及其生产依赖,复用父目录提供的 DSH 宿主依赖;先确认未安装 SDK 时核心入口可加载,再另行安装 SDK,检查编译后 QQ 驱动的本地 WebSocket 连接,全程不修补 SDK 文件,结束后清理临时项目。检查不需要 DSH profile、微信进程或真实账号。
125
+
126
+ ### npm 发布(维护者)
127
+
128
+ 使用上述检查生成的同一个 `.tgz` 发布,避免发布时重新构建出不同内容。包已通过 `publishConfig` 指定 npm 官方源和公开访问;先完成发布预检:
129
+
130
+ ```powershell
131
+ npm publish .\artifacts\dsh-world-0.6.5.tgz --dry-run --ignore-scripts --registry=https://registry.npmjs.org/
132
+ ```
133
+
134
+ 确定发布后,用有包发布权限的 npm 账号登录,按 npm 提示完成浏览器和二次验证,再执行:
135
+
136
+ ```powershell
137
+ npm login --registry=https://registry.npmjs.org/
138
+ npm publish .\artifacts\dsh-world-0.6.5.tgz --ignore-scripts --access public --registry=https://registry.npmjs.org/
139
+ ```
140
+
141
+ 首次发布会创建该包;之后每次发布都要提升版本号,同一个包名和版本不能覆盖。发布成功后使用者可按 [安装说明](INSTALL.md#第一步把-dsh-world-装进-profile) 从 npm 安装或更新。后续版本替换示例中的版本号。流程依据 [npm 发布文档](https://docs.npmjs.com/cli/v11/commands/npm-publish/);npm 登录信息和令牌不要写进仓库。
142
+
143
+ 每个平台检查通过后,CI 上传 `artifacts/` 中的 `.tgz` 供下载。CI 不替代桌面端和真实账号验收。
144
+
145
+ ## 提交说明
146
+
147
+ 可按以下结构提交 Issue 或 PR;未知内容写“未验证”,不要填成已完成:
148
+
149
+ ```text
150
+ 目标分支:dev(PR 必填)
151
+ 新增或修改的生态:
152
+ 模块目录与接入方式:
153
+ 支持的消息、身份映射与会话路由:
154
+ 是否涉及内核:否 / 是(文件、原因、行为和影响)
155
+ 是否改动生活线核心或给她新增工具:否 / 是(对应的 Issue)
156
+ 新增依赖:无 / 有(为什么必须、是否可选、默认是否加载、许可证、对应的 Issue)
157
+ 依赖与许可:
158
+ 兼容、迁移与重启要求:
159
+ 验证命令与结果:
160
+ 已知限制与未验证项:
161
+ ```
162
+
163
+ 贡献遵循对应文件现有许可。仓库主体采用 [MIT](LICENSE),微信原生发送引擎另有 [独立许可](src/ecosystem/wechat/windows/engine/LICENSE) 与 [来源说明](src/ecosystem/wechat/windows/engine/NOTICE.md),不可按根目录 MIT 许可重新分发该部分。提交第三方代码时保留原许可与来源,不提交无权公开的代码或数据。