dsh-world 0.7.5 → 0.8.0

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 (115) hide show
  1. package/CHANGELOG.md +541 -446
  2. package/CONTRIBUTING.md +174 -163
  3. package/INSTALL.md +314 -314
  4. package/NOTES.md +98 -5
  5. package/README.md +332 -258
  6. package/client/index.js +1126 -986
  7. package/lib/compaction.d.ts +7 -1
  8. package/lib/compaction.js +8 -3
  9. package/lib/console/routes.d.ts +11 -3
  10. package/lib/console/routes.js +12 -7
  11. package/lib/console/snapshot.d.ts +2 -0
  12. package/lib/console/snapshot.js +1 -0
  13. package/lib/ecosystem/computer/browser/browser.d.ts +34 -0
  14. package/lib/ecosystem/computer/browser/browser.js +101 -0
  15. package/lib/ecosystem/computer/browser/cdp.d.ts +22 -0
  16. package/lib/ecosystem/computer/browser/cdp.js +91 -0
  17. package/lib/ecosystem/computer/browser/edge.d.ts +15 -0
  18. package/lib/ecosystem/computer/browser/edge.js +80 -0
  19. package/lib/ecosystem/computer/browser/page.d.ts +41 -0
  20. package/lib/ecosystem/computer/browser/page.js +140 -0
  21. package/lib/ecosystem/computer/browser/pageLib.d.ts +7 -0
  22. package/lib/ecosystem/computer/browser/pageLib.js +106 -0
  23. package/lib/ecosystem/computer/desktop/desktop.d.ts +91 -0
  24. package/lib/ecosystem/computer/desktop/desktop.js +322 -0
  25. package/lib/ecosystem/computer/desktop/driver.d.ts +34 -0
  26. package/lib/ecosystem/computer/desktop/driver.js +197 -0
  27. package/lib/ecosystem/computer/desktop/processes.d.ts +5 -0
  28. package/lib/ecosystem/computer/desktop/processes.js +15 -0
  29. package/lib/ecosystem/computer/desktop/recording.d.ts +77 -0
  30. package/lib/ecosystem/computer/desktop/recording.js +187 -0
  31. package/lib/ecosystem/computer/desktop/screen.d.ts +33 -0
  32. package/lib/ecosystem/computer/desktop/screen.js +182 -0
  33. package/lib/ecosystem/computer/desktop/turns.d.ts +58 -0
  34. package/lib/ecosystem/computer/desktop/turns.js +94 -0
  35. package/lib/ecosystem/computer/desktop/watching.d.ts +25 -0
  36. package/lib/ecosystem/computer/desktop/watching.js +81 -0
  37. package/lib/ecosystem/computer/inbox/inbox.d.ts +32 -0
  38. package/lib/ecosystem/computer/inbox/inbox.js +142 -0
  39. package/lib/ecosystem/computer/index.d.ts +82 -0
  40. package/lib/ecosystem/computer/index.js +133 -0
  41. package/lib/ecosystem/computer/procedures/alarm.d.ts +13 -0
  42. package/lib/ecosystem/computer/procedures/alarm.js +46 -0
  43. package/lib/ecosystem/computer/procedures/archive.d.ts +32 -0
  44. package/lib/ecosystem/computer/procedures/archive.js +68 -0
  45. package/lib/ecosystem/computer/procedures/catalog.d.ts +7 -0
  46. package/lib/ecosystem/computer/procedures/catalog.js +75 -0
  47. package/lib/ecosystem/computer/procedures/format.d.ts +167 -0
  48. package/lib/ecosystem/computer/procedures/format.js +332 -0
  49. package/lib/ecosystem/computer/procedures/library.d.ts +53 -0
  50. package/lib/ecosystem/computer/procedures/library.js +178 -0
  51. package/lib/ecosystem/computer/procedures/run.d.ts +80 -0
  52. package/lib/ecosystem/computer/procedures/run.js +245 -0
  53. package/lib/ecosystem/computer/tools.d.ts +21 -0
  54. package/lib/ecosystem/computer/tools.js +197 -0
  55. package/lib/ecosystem/qq-native/images.d.ts +8 -1
  56. package/lib/ecosystem/qq-native/images.js +34 -15
  57. package/lib/ecosystem/qq-native/index.js +5 -5
  58. package/lib/ecosystem/shared/turn.d.ts +3 -0
  59. package/lib/ecosystem/shared/turn.js +13 -3
  60. package/lib/ecosystem/wechat/home.d.ts +1 -0
  61. package/lib/ecosystem/wechat/home.js +9 -3
  62. package/lib/ecosystem/wechat/images.js +3 -5
  63. package/lib/ecosystem/wechat/index.d.ts +6 -0
  64. package/lib/ecosystem/wechat/index.js +3 -1
  65. package/lib/ecosystem/wechat/presence.d.ts +5 -1
  66. package/lib/ecosystem/wechat/presence.js +22 -13
  67. package/lib/ecosystem/wechat/reading.d.ts +1 -1
  68. package/lib/ecosystem/wechat/reading.js +2 -2
  69. package/lib/elsewhere.d.ts +34 -0
  70. package/lib/elsewhere.js +40 -0
  71. package/lib/history.d.ts +5 -0
  72. package/lib/history.js +7 -1
  73. package/lib/hostContract.d.ts +6 -0
  74. package/lib/images.d.ts +30 -0
  75. package/lib/images.js +101 -0
  76. package/lib/index.d.ts +4 -0
  77. package/lib/index.js +98 -6
  78. package/lib/life/photoTools.js +4 -15
  79. package/lib/life/runtime.d.ts +12 -2
  80. package/lib/life/runtime.js +93 -12
  81. package/lib/life/toolRegistry.d.ts +9 -3
  82. package/lib/life/toolRegistry.js +46 -27
  83. package/lib/life/turnCost.d.ts +16 -0
  84. package/lib/life/turnCost.js +44 -0
  85. package/lib/life/types.d.ts +17 -0
  86. package/lib/memoryTools.d.ts +4 -2
  87. package/lib/memoryTools.js +25 -5
  88. package/lib/mood.d.ts +5 -1
  89. package/lib/mood.js +25 -8
  90. package/lib/promptSection.d.ts +3 -0
  91. package/lib/promptSection.js +29 -42
  92. package/lib/runtime.js +44 -17
  93. package/lib/sessionNews.d.ts +17 -0
  94. package/lib/sessionNews.js +55 -0
  95. package/lib/store.d.ts +6 -0
  96. package/lib/store.js +17 -3
  97. package/lib/types.d.ts +4 -0
  98. package/lib/worldAdd.d.ts +9 -0
  99. package/lib/worldAdd.js +39 -0
  100. package/lib/worldPrompt.d.ts +3 -2
  101. package/lib/worldPrompt.js +3 -2
  102. package/lib/worldRoutes.d.ts +5 -2
  103. package/lib/worldRoutes.js +29 -4
  104. package/lib/worldSwitch.d.ts +8 -2
  105. package/lib/worldSwitch.js +11 -5
  106. package/package.json +132 -129
  107. package/src/ecosystem/README.md +2 -1
  108. package/src/ecosystem/computer/NOTICE.md +27 -0
  109. package/src/ecosystem/computer/README.md +244 -0
  110. package/src/ecosystem/computer/desktop/win32.ps1 +858 -0
  111. package/src/ecosystem/wechat/windows/README.md +4 -2
  112. package/src/ecosystem/wechat/windows/engine/NOTICE.md +6 -0
  113. package/src/ecosystem/wechat/windows/engine/profiles.json +28 -0
  114. package/templates/world-prompt-memory.md +10 -10
  115. package/templates/world-prompt.md +65 -65
package/CONTRIBUTING.md CHANGED
@@ -1,163 +1,174 @@
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 许可重新分发该部分。提交第三方代码时保留原许可与来源,不提交无权公开的代码或数据。
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 站等网页平台不单独建目录,由她用 `computer/` 自己学 |
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、微信已经接入,`<channel>/` 是新平台通用的目录位置。
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
+ 接入新的平台或外部程序时,先分清它带来的是哪一类,再放到对应的位置(排法和原因见 [注意事项](NOTES.md#她每一步看到的上下文)):
65
+
66
+ - **对她说的话**:作为一条用户消息交给她,带结构化身份(见上节)。
67
+ - **随这句话来的上下文**(之前的聊天、引用、图片):贴在那句话前面,标明属于哪条消息,不放到末尾。
68
+ - **不需要她回答的动静**(群里没叫她的消息、通知、另一个会话里的新发言):属于事件,统一进「别处的动静」,不在上下文末尾另加一块。每个来源只报有多少条她还没看到、最后是谁、过了多久,不带正文;写明她用哪个工具去看,读到最新后清零。不写待办、不写「你应该」,要不要看、要不要回由她决定。
69
+ - **状态**(像心情值、时间,每一步都要是最新的):每一步跟在末尾。新增一种状态属于生活线核心改动,先开 Issue。
70
+
71
+ 这几类都只往后追加,不替换、不删除历史里已有的,压缩时清掉,不进归档。新来源要写明它的动静能流到哪些会话,并遵守上一节的世界边界。这一块不带正文;群会话里凡是会见到别处原话或指向别处的地方(近期记忆、别处的动静),都要附上 `history.ts` 的 `GROUP_PRIVACY`,不另写一份措辞。
72
+
73
+ ## 涉及内核时必须说明
74
+
75
+ 这里的“内核”指 dsh-world 的公共行为,不仅指某个目录:
76
+
77
+ | 影响区域 | 现有位置举例 |
78
+ | --- | --- |
79
+ | 记忆生成、归档范围、历史回填、存储和压缩 | `src/runtime.ts`、`archive*.ts`、`sourceArchive.ts`、`store.ts`、`history.ts`、`compaction*.ts` |
80
+ | 世界的作用范围(工作区) | `src/worldScope.ts`、`archiveSelection.ts`、`workspacePermissions.ts` |
81
+ | 人设、世界提示、时间上下文和世界开关 | `src/persona.ts`、`worldPrompt.ts`、`timeContext.ts`、`worldSwitch.ts` 等 |
82
+ | 家会话、生活线、每日回顾和宿主适配 | `src/life/`、`src/hostContract.ts` |
83
+ | 公共协议、配置、模块生命周期和控制台 | `src/ecosystem/shared/`、`src/index.ts`、`src/types.ts`、`src/console/`、`client/` |
84
+
85
+ 提交说明中必须写明“是否涉及内核”。新增平台的配置与注册接线也要列出,说明是否改变已有行为。涉及内核时补充:
86
+
87
+ 1. 修改了哪些文件、接口或数据格式,为什么现有扩展点不足以完成接入。
88
+ 2. 修改前后的行为,以及对家、其他平台、归档范围、人设、生活线和权限的影响;不受影响的部分可合并说明。
89
+ 3. 旧配置、旧会话、归档和待发送队列如何兼容;是否需要迁移或重启,升级失败如何保留原数据。
90
+ 4. 对应回归测试、验证结果,以及未验证的宿主版本、平台或真实账号条件。
91
+
92
+ 本项目内核与 DSH 宿主需要区分。若方案还依赖修改 DSH 本身,应另外列出宿主版本、补丁或依赖、安装方式和兼容范围,不能把它描述为插件即可独立使用。
93
+
94
+ ## 代码设计
95
+
96
+ - **先找已有的,再写新的。** 各平台“送一句话、等她这一轮的回复”用 `ecosystem/shared/turn.ts` 的 `askTurn` 和 `createChannelQueue`(排队、超时、取消);群上下文用 `shared/context.ts`;身份用 `shared/identity.ts`;作用范围见上文。不要在模块里再抄一份串行队列、回复判断或超时逻辑;已有实现不够用时,改它并说明原因。
97
+ - **按职责拆文件。** 一个文件只负责一件事,解析、排队、重试、编排分开放。模块入口只做接线,不要把所有功能堆进一个几百行的 `index.ts`。
98
+ - **不留历史痕迹。** 删除或替换功能时,连同配置、文档、测试、注释和面板控件一起清理;不留孤立注释、只写不读的变量和不再生效的配置项。
99
+ - **用结构判断,不靠巧合。** 判断“这一轮是谁开的、回给谁”,看事件来源和会话归属,不要用“现在有没有正在处理的请求”“几秒内发过同样的文字”这类旁证去重或补救。
100
+ - **配置和面板一致。** 面板上能改的设置要写进同一份覆盖文件,一次请求里给的几项一起生效;新增配置项同步更新 `src/types.ts`、配置 schema、README 的配置示例和对应文档。
101
+
102
+ ## 外部依赖
103
+
104
+ 插件主体必须在只装必要依赖的情况下装得上、跑得起来。生态模块一律按“可选”设计:
105
+
106
+ - **默认不加新依赖。** 能用宿主服务、Node 内置模块或已有依赖完成的,不引入新包。确实需要时,先开 Issue 说明用途、体积、许可证和替代方案,得到同意再提交。
107
+ - **平台 SDK 只能是可选依赖。** 由使用者另行安装的 SDK 声明为可选 peer(`peerDependenciesMeta.optional: true`),开发测试所需版本放在 `devDependencies`。只在模块被拨开时动态 `import`;模块默认关闭,没装 SDK 时只显示该模块不可用,不能影响插件本身和其他模块。不要通过安装脚本修补 SDK 文件。
108
+ - **不自动安装或部署第三方程序。** 涉及启动外部程序(例如 SnowLuma)的功能,在模块文档和 PR 中写明其许可条款允许的方式,以及是否默认开启。
109
+ - **SDK 按需安装必须由使用者明确开启模块触发。** 复用宿主包管理操作与 profile 写锁,禁用生命周期脚本,不修改 SDK 文件或自动升级 Node;安装失败保留原 profile 配置,安装后需要重启时明确提示。客户端程序的安装与登录仍由使用者处理。
110
+
111
+ ## 实现与验证
112
+
113
+ - 优先复用已有函数、宿主服务和依赖,通过参数或现有注入机制传入依赖。平台细节留在模块内,不为单个平台新增通用框架;替换旧实现时清理失效代码。
114
+ - 查询接口搭配分页设计;配置、ID、路径和外部消息在边界校验,不硬编码真实账号或本机路径。错误应明确返回并保留必要状态,不吞错或伪报成功;成组的数据变更保持事务一致性。
115
+ - 确认 `package.json` 的 `files`、导出和构建配置覆盖必要产物,同时排除凭据、数据库、聊天记录和个人媒体。
116
+ - 代码修改按影响运行 `npm run typecheck`、`npm test`、`npm run build`,补充相关适配器测试。**每个新功能都要有回归测试**,非平凡逻辑至少一个有意义的用例;只改断言让旧测试通过不算覆盖新行为。测试不得启动或连接本机真实的第三方程序。仅文档修改检查格式与链接即可。
117
+ - 真实账号测试与单元测试分开说明:使用什么环境、实际确认了什么、哪些条件尚未验证。涉及第三方协议或客户端内部调用时,在模块文档中说明版本限制、账号及数据风险,不能宣称保证不触发风控。
118
+
119
+ ## CI 与安装包验证
120
+
121
+ [CI](.github/workflows/ci.yml) 在 PR、`main` 推送和手动触发时运行 Windows / Linux 两条完整检查任务,使用满足开发测试 SDK 要求的 Node 24.22.1。两端执行禁用安装脚本的干净安装、类型检查、全部 Node 回归测试、编译和安装包验证;Windows 另用 Python 3.11 安装固定的微信适配器依赖并跑离线测试。另有 Node 22.16.0 核心入口检查,确认 SDK 不可用时核心仍能加载。相同分支的新运行会取消旧运行,各项独立报告结果。
122
+
123
+ 本机可按以下 PowerShell 命令复现 Node 与安装包检查:
124
+
125
+ ```powershell
126
+ npm ci --ignore-scripts
127
+ npm run typecheck
128
+ npm test
129
+ npm run build
130
+ New-Item -ItemType Directory -Force artifacts | Out-Null
131
+ npm pack --ignore-scripts --pack-destination artifacts
132
+ npm run test:package
133
+ ```
134
+
135
+ 安装与打包均禁用生命周期脚本,类型检查和编译由前面的命令显式执行。`test:package` 在本仓库 `.host/` 下创建临时消费项目,安装真实 `.tgz` 及其生产依赖,复用父目录提供的 DSH 宿主依赖;先确认未安装 SDK 时核心入口可加载,再另行安装 SDK,检查编译后 QQ 驱动的本地 WebSocket 连接,全程不修补 SDK 文件,结束后清理临时项目。检查不需要 DSH profile、微信进程或真实账号。
136
+
137
+ ### npm 发布(维护者)
138
+
139
+ 使用上述检查生成的同一个 `.tgz` 发布,避免发布时重新构建出不同内容。包已通过 `publishConfig` 指定 npm 官方源和公开访问;先完成发布预检:
140
+
141
+ ```powershell
142
+ npm publish .\artifacts\dsh-world-0.8.0.tgz --dry-run --ignore-scripts --registry=https://registry.npmjs.org/
143
+ ```
144
+
145
+ 确定发布后,用有包发布权限的 npm 账号登录,按 npm 提示完成浏览器和二次验证,再执行:
146
+
147
+ ```powershell
148
+ npm login --registry=https://registry.npmjs.org/
149
+ npm publish .\artifacts\dsh-world-0.8.0.tgz --ignore-scripts --access public --registry=https://registry.npmjs.org/
150
+ ```
151
+
152
+ 首次发布会创建该包;之后每次发布都要提升版本号,同一个包名和版本不能覆盖。发布成功后使用者可按 [安装说明](INSTALL.md#第一步把-dsh-world-装进-profile) 从 npm 安装或更新。后续版本替换示例中的版本号。流程依据 [npm 发布文档](https://docs.npmjs.com/cli/v11/commands/npm-publish/);npm 登录信息和令牌不要写进仓库。
153
+
154
+ 每个平台检查通过后,CI 上传 `artifacts/` 中的 `.tgz` 供下载。CI 不替代桌面端和真实账号验收。
155
+
156
+ ## 提交说明
157
+
158
+ 可按以下结构提交 Issue 或 PR;未知内容写“未验证”,不要填成已完成:
159
+
160
+ ```text
161
+ 目标分支:dev(PR 必填)
162
+ 新增或修改的生态:
163
+ 模块目录与接入方式:
164
+ 支持的消息、身份映射与会话路由:
165
+ 是否涉及内核:否 / 是(文件、原因、行为和影响)
166
+ 是否改动生活线核心或给她新增工具:否 / 是(对应的 Issue)
167
+ 新增依赖:无 / 有(为什么必须、是否可选、默认是否加载、许可证、对应的 Issue)
168
+ 依赖与许可:
169
+ 兼容、迁移与重启要求:
170
+ 验证命令与结果:
171
+ 已知限制与未验证项:
172
+ ```
173
+
174
+ 贡献遵循对应文件现有许可。仓库主体采用 [MIT](LICENSE),微信原生发送引擎另有 [独立许可](src/ecosystem/wechat/windows/engine/LICENSE) 与 [来源说明](src/ecosystem/wechat/windows/engine/NOTICE.md),不可按根目录 MIT 许可重新分发该部分。提交第三方代码时保留原许可与来源,不提交无权公开的代码或数据。