dsh-sansheng-liubu/ds-bot/PATCHES.md

212 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 上游补丁记录
上游:`Fei2411/DS-Bot`,固定基线 `84c3cb86b997aec53281b842fd162f3f6b4ee7be`(= npm `ds-bot@0.3.2`)。
本目录是 npm 发布内容(`files` 白名单)加下述补丁,另附仓库根 `NOTICE`。
## M-01:向伴侣插件暴露运行时
```diff
export function apply(ctx, config = {}) {
- createRuntime(ctx, config)
+ const rt = createRuntime(ctx, config)
+ // sansheng M-01: expose the runtime so a companion plugin can create Bots, bind
+ // model settings, and read authoritative goal state. See PATCHES.md.
+ ctx.provide('dsbot-runtime', rt)
}
```
原因:`createRuntime` 的返回值原本直接丢弃,第三方插件无法创建 Bot、设置模型或
读取 `room.goal` 的权威状态。`ctx.provide` 是宿主 cordis 的公开服务注册 API
(`@deepseek-ai/cordis` `ctx.provide(name, value)`),不修改任何业务逻辑。
伴侣插件用法:
```js
const rt = ctx.get('dsbot-runtime', false) // 未安装打过补丁的 ds-bot 时为 undefined
```
影响面:只新增一个服务名 `dsbot-runtime`;不与上游已有服务冲突(全仓无同名)。
行为、工具、页面、状态文件均未改动。
## M-02:保留 DSH 原生设置页
```diff
- id: web
config:
searchProvider: auto
fetchProvider: http
-
-# DS Bot's settings shell holds the sidebar's settings seat ...
-- id: ui-settings-general
- disabled: true
```
原因:上游把 DSH 自己的设置页关掉,改由 DS Bot 的设置壳在 Bot 页面里绘制。
新装、还没有 Bot 时,侧栏就一个设置入口都没有,用户会以为设置页被删了。
本补丁保留宿主原生设置页;DS Bot 自己的设置仍可在其页面里使用。
## M-03:浏览器端 slots 冲突不再让整个插件「failed」
`client.js`(构建产物)里,`settings.trigger` 的注册没有兜底:
```diff
- slots.inject("settings.trigger", () => slots.register({ name: "settings.trigger" }, TriggerContent))
+ slots.inject("settings.trigger", () => {
+ try {
+ return slots.register({ name: "settings.trigger" }, TriggerContent)
+ } catch (error) {
+ console.warn("[ds-bot] settings.trigger already registered by the host shell; DS Bot trigger skipped", error)
+ return () => {}
+ }
+ })
```
原因:宿主原生设置壳(我们保留的 M-02)已经占用了 `settings.trigger`,ds-bot 再注册会抛
`single slot ... already has a registration at priority 0`;该异常从 `apply` 抛出后,宿主把它记为
`ds-bot: failed`,整个插件(含 Bot 页面)都不加载,随后宿主把 profile 回退成只挂 base + web-app,
表现就是"插件全没了 / 启动崩溃"。`sidebar.settings` 那处上游本来就有 try/catch,不必改。
改的是构建产物,重新构建上游后需重放本补丁。
## M-04:项目投递边界(Bot 间消息)
三个文件各有一个本地 helper(不新增共享模块):
```diff
+const sanshengGovernance = () => {
+ try { return ctx.get?.('sansheng-governance', false) } catch { return undefined }
+}
```
`delivery.js` 的 `deliver()`:解析出目标 Bot 之后、任何 `ensureCapabilities`/`followup` 之前:
```diff
const to = rt.botOf(toId)
if (to === undefined) throw new Error(`Unknown Bot ${toId}`)
+ const verdict = sanshengGovernance()?.checkDelivery?.({ fromId, toId, roomId })
+ if (verdict && verdict.allow === false) {
+ throw Object.assign(new Error(verdict.reason ?? '跨项目投递被拒绝'), { code: 'sansheng/forbidden' })
+ }
```
`tools.js` 的 `message_bot`:私聊路径(`room === undefined`,即 `send()` 所走的分支)在真正投递前做同样的检查;群内路径已有 `groupRefusal`,不重复:
```diff
+ const verdict = sanshengGovernance()?.checkDelivery?.({ fromId: sender.id, toId: target.id, roomId: undefined })
+ if (verdict && verdict.allow === false) return verdict.reason ?? '跨项目投递被拒绝'
return request === undefined ? await send() : answer(await rt.admitRequest(request, send))
```
原因:DS Bot 的 `deliver` 是 Bot 间投递的最终入口,`message_bot` 只是其中一条上层路径;
只挡工具调用会留下内部调用(例如派发恢复、自动投递)的绕过口。治理服务按项目判断
`fromId`/`toId` 是否同属一个项目,跨项目时返回 `{ allow: false, reason }`,底座在
任何 Session 写入前以 `sansheng/forbidden` 拒绝。
影响面:只在 `ctx.get('sansheng-governance', false)` 返回治理服务时生效;`fromId` 为
用户或为空时由治理实现决定 allow。无治理服务时 optional chaining 返回 `undefined`,
投递路径、异常类型、return 值与上游完全一致。群内 `@Name` 的 `callInGroup` 由
`groupRefusal` 先行限制,本补丁不重复加检查。
## M-05:项目记忆域(team 作用域隔离)
`memory.js` 内新增同一 helper,并在写入、读取、提示注入与自动召回等处加治理判断:
```diff
function writeDenied(scope, botId) {
+ if (botId && botId !== 'user') {
+ const verdict = sanshengGovernance()?.checkMemoryScope?.({ botId, scope: scope.kind, roomId: scope.kind === 'group' ? scope.roomId : undefined })
+ if (verdict && verdict.allow === false) return verdict.reason ?? '项目记忆边界拒绝此操作。'
+ }
if (scope.kind === 'team') return writesTeam(botId) ? undefined : '...'
```
```diff
function readScopes(raw, botId, sessionRoomId) {
...
+ if (scope && scope.kind === 'bot' && scope.botId !== botId && botId && botId !== 'user') {
const verdict = sanshengGovernance()?.checkMemoryScope?.({ botId, scope: 'bot', targetBotId: scope.botId })
if (verdict && verdict.allow === false) return { error: verdict.reason ?? '...' }
}
let scopes = scope === undefined ? (...) : [scope]
+ if (botId && botId !== 'user' && scopes.some(item => item.kind === 'team')) {
+ const verdict = sanshengGovernance()?.checkMemoryScope?.({ botId, scope: 'team' })
+ if (verdict && verdict.allow === false) {
+ scopes = scopes.filter(item => item.kind !== 'team')
+ if (scopes.length === 0) return { error: '项目 Bot 不能读取跨项目共享记忆。' }
+ }
+ }
```
```diff
function memorySection(bot) {
...
+ const teamAllowed = !bot.id || bot.id === 'user'
+ ? true
+ : sanshengGovernance()?.checkMemoryScope?.({ botId: bot.id, scope: 'team' })?.allow !== false
const team = teamAllowed ? sectionRead(join(dirOf(TEAM), MAIN)) : { text: '' }
...
- teamRule(rt.isMain(bot.id), writesTeam(bot.id), rt.isPrivate(bot.id)),
+ ...(teamAllowed ? [teamRule(...)] : []),
...
+ ...(teamAllowed ? ['', '## Team memory, ...', ...] : []),
```
`sectionFor` 的 `marks`/`holds` 同步跳过 team rule,避免已冻结的旧快照继续带出 team 段。
```diff
function autoRecall(agent, bot, roomId, decision) {
- const scopes = [own, ...(roomId === undefined ? [] : [groupScope(roomId)]), TEAM]
+ const scopes = [own, ...(roomId === undefined ? [] : [groupScope(roomId)]), ...(teamAllowedFor(bot.id) ? [TEAM] : [])]
```
```diff
function memoryUpdate(sessionId, bot, roomId) {
- const keys = new Set([scopeKey(own), scopeKey(TEAM), ...])
+ const keys = new Set([scopeKey(own), ...(teamAllowedFor(bot.id) ? [scopeKey(TEAM)] : []), ...])
```
原因:`team` 作用域是 DS Bot 所有 Bot 共享的记忆,正好是跨项目泄漏点(00-baseline
§3.4)。项目 Bot 不能读写 team 记忆;`own`/`group` 不受影响。治理只在 `botId` 为
真实 Bot 时检查,`actor.id === 'user'` 的用户操作保持上游权限。
影响面:`remember`/`forget` 的 team 写入、`recall` 的 team 读取、系统提示的 team
段与 `teamRule` 行、自动召回(autoRecall)与记忆变更提示(memoryUpdate)的 team
键;不改变 own/group 记忆、不改变文件格式。无治理服务时 `teamAllowedFor` 为 true、
`readScopes` 原样返回,行为与上游一致。
## M-06:保留宿主左侧项目树,Bot 切换移到右栏
`client.js`(构建产物)的 `installShell` 原本无条件 shadow `sidebar.workspaces` 为
`TeamSidebar`,导致安装三省六部后左栏被 DS Bot 的 Bot 列表替换。补丁改为:当宿主
`sidebarRightTabs` 中已存在 `sansheng-roles`(三省六部右栏页签)时跳过 TeamSidebar
的 shadow,保留宿主 workspace-groups 项目树;Bot/群切换由右栏「Bot 切换」折叠列表
承担(数据来自 `/sansheng/state` 的只读花名册)。
```diff
- () => shadow("sidebar.workspaces", { priority: BOT_PRIORITY, inject: face }, TeamSidebar),
+ () => {
+ try {
+ if (ctx.sidebarRightTabs?.get?.("sansheng-roles") !== undefined) return;
+ } catch (error) { /* no workbench: keep the team sidebar */ }
+ return shadow("sidebar.workspaces", { priority: BOT_PRIORITY, inject: face }, TeamSidebar)();
+ },
```
原因:用户明确要求左侧沿用现有项目树,Bot 切换不要占左栏。
影响面:只影响与 `dsh-sansheng-sansheng` 同时安装时的左栏;未装三省六部时行为与上游一致。
恢复:删除该条件,恢复原始 `shadow("sidebar.workspaces", ...)` 行即可。
## 升级步骤
1. 取新版本 npm tarball,解压覆盖本目录(保留本文件与 `NOTICE`)。
2. 重放 M-01;若上游已自行暴露运行时(例如 `ctx.set('dsbot', rt)`),删除本补丁
并同步修改 `sansheng/src/runtime.js` 的取用名。
3. 逐一重放其余补丁:M-02 检查 `cordis.patch.yml`,M-03 重放 `client.js` 的
`settings.trigger` try/catch,M-04/M-05 按本文件 diff 恢复 `delivery.js`、
`memory.js`、`tools.js` 的治理检查,M-06 重放 `client.js` 的 TeamSidebar 条件
shadow(保留左侧项目树);对三个 JS 文件跑 `node --check`。
4. 跑 `sansheng` 的单元测试与安装冒烟(见 `docs/install.md`)。
## 回退
删除本目录、改装 npm `ds-bot@0.3.2` 即可;三省六部在拿不到运行时句柄时仍可
`bind` 已存在的 Bot,只是不能自动建 Bot / 改模型(工具会返回明确错误)。