docs: define DSH provider and conversation management improvements

This commit is contained in:
abaishu0730 committed 2026-10-28 08:46:43 +08:00
1 parent 59e0a44bcc
commit adfeb4affc
2 files changed
+135

No files matched your search

@@ -0,0 +1,83 @@
# DSH Providers and Conversation Management Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 复用官方 DSH 多供应商能力,完成助手设置/对话模型选择、会话回收站,以及醒目的返回工具按钮。
**Architecture:** 独立 ProviderRegistry 复用 assistant 数据库与加密,官方 DeepSeek/pi-ai 分别承担协议路由。会话新增删除状态、模型选择与独立额度记账;浏览器设置、模型控件与目录菜单通过现有 API 适配。
**Tech Stack:** CommonJS、原生 JS/Tabler、SQLite/AES-GCM、DSH0.2.1-rc.2、Playwright、Node test runner。
**Spec:** [approved design](../specs/2026-10-28-dsh-providers-conversations-design.md)
## Global Constraints
- 用户已明确批准执行和助手设置/返回按钮补充;不再请求同项批准。
- 使用现有 `dsh` 分支,保留三个未跟踪业务文档,不改业务发送/归档/审批规则。
- DSH 固定0.2.1-rc.2,复用 dsh-llm-pi-ai;原生 Shell/文件/MCP/插件工具保持未挂载。
- 密钥加密只写、不回显;更换端点/协议重新输入密钥;供应商修改仅管理员。
- 回收站无自动清空;永久删除需本人显式确认,不释放调用额度、不删除操作审计。
- 测试使用独立临时 LOCALAPPDATA;通过 junction 引用已安装运行包,不复用运行服务凭据目录。
- 只更新已授权本机测试副本,先备份;不启用真实模型、不发送测试以外的业务操作。
## Task 1: Provider registry and official protocol adaptation
**Files:** Create `src/modules/assistant/providers.cjs`, `provider-catalog.cjs`, tests `providers.test.cjs`, `providers-runtime.test.cjs`; modify `dsh-runtime.cjs` only. Store/API/service are integrated by root in Task2.
**Interfaces:** `new ProviderRegistry(store)`, methods `list()`, `save(input)`, `chooseDefault(input)`, `remove(id,input)`, `resolve(selection?)`, `syncLegacy(settings)`, `discover(id,{version,signal}={})`. `list()` returns `{version,providers,defaultSelection,catalog}`; providers expose `{id,version,name,preset,protocol,apiBase,enabled,hasApiKey,models:[{id,name,contextWindow?,maxTokens?}]}`. `resolve` returns private config `{providerId,providerName,providerVersion,preset,protocol,apiBase,apiKey,model,modelName,contextWindow,maxTokens}`. Fixed legacy provider ID is `deepseek`.
- [ ] Write tests proving migration from old DeepSeek configuration retains secret/default; multiple providers stay isolated/encrypted; address/protocol changes require a new key; version conflicts/disabled/missing models fail. Run red before implementation.
```js
const registry=new ProviderRegistry(store);
registry.syncLegacy({apiBase:'https://api.deepseek.com/anthropic',model:'legacy',apiKey:'TEST_KEY'});
assert.equal(registry.resolve().model,'legacy');
assert.equal(registry.list().providers[0].apiKey,undefined);
```
- [ ] Implement encrypted provider records and independently versioned defaults. Limit30 providers/100 models, validate names/IDs/endpoints/model bounds; save id absent creates stable ID, new version0 and stale existing version reject. Blank key preserves existing, no source/environment key discovery.
- [ ] Reuse installed native catalogue metadata where possible; expose DeepSeek/OpenAI/Anthropic/custom presets. Explicit `discover` lists models with a bounded GET using only that provider's key; unsupported response fails without saving.
- [ ] Adapt `profilePatch`/environment to selected route: legacy DeepSeek remains byte-compatible in behavior, other protocols mount only native `dsh-llm-pi-ai` with the chosen explicit route/model and fixed private credential reference. No tools or additional ambient credentials. Honor timeout/output limits.
```js
const profile=profilePatch({...config,protocol:'openai-responses',providerId:'fixture'});
assert.match(profile,/dsh-llm-pi-ai/);
assert.doesNotMatch(profile,/TEST_KEY/);
```
- [ ] Test actual fixed official DSH against local fake Messages, Chat Completions and Responses endpoints, ensure zero native tools, correct route, credentials and cancellation cleanup. Run previous dsh-runtime/dsh-events tests and commit owned paths only.
## Task 2: Conversation lifecycle, settings and routing integration
**Files:** Modify assistant `store.cjs`, `service.cjs`, `conversation-history.cjs`, `conversation-search.cjs`, `api.cjs`, `event-stream.cjs`; backup `restore.cjs`; add `conversation-trash.test.cjs`, `provider-http.test.cjs`, `assistant-restore.test.cjs`.
**Interfaces:** store.providers is ProviderRegistry; service.resolve per-conversation or default selection before each new run; existing settings API fields remain compatible. Conversation model choice endpoint updates encrypted metadata with version. Store methods `trash`, `restoreDeleted`, `purge` implement deleted scope; `usage()` reads durable ledger.
- [ ] Write failing tests for deleted filtering/restoration, owner/version/busy guards, quota retained after purge, continued child usable after parent deletion, and model selection pinned to a running turn.
```js
const c=store.create('owner'),turn=store.beginTurn(c.id,'owner','fixture');
store.updateTurn(turn.id,'success',{reply:'done'});
const used=store.usage().calls;
const deleted=store.trash(c.id,'owner',{version:store.conversation(c.id,'owner').version});
store.purge(c.id,'owner',{version:deleted.version,confirm:'delete'});
assert.equal(store.usage().calls,used);
```
- [ ] Add deleted_at and call ledger migration. Exclude deleted rows from active/search/send/actions; explicit deleted scope permits read-only history. Inherit three successful turns into child metadata before parent removal. Delete events/requests/turns atomically on purge, independent audit/ledger survive.
- [ ] Integrate registry in store; legacy saveFields sync only explicit legacy writes. New runtime settings omit old endpoint/key fields. Enabling checks selected usable config, preserving old tests and stored settings.
- [ ] Integrate provider/default/model endpoints with same-origin, admin/owner, secure credential transport, version and running provider-delete guards. Pin private provider config to each run and persist only public per-turn selection metadata.
- [ ] Update SSE/polling with conversation_removed terminal control, no authentication logout on deleted conversation. Update backup payload AAD mapping for config/providers/defaults/events/requests and verify backup/restore roundtrip.
- [ ] Run focused HTTP, lifecycle, old assistant and backup tests. Commit only task paths after Task1 implementation agent has committed.
## Task 3: Settings/model menu, row actions and return controls
**Files:** Create `web/modules/assistant/providers.js`, `model-picker.js`; modify assistant `view.js`, `layout.js`, `workspace.css`, `commands.js`, `events-client.js`, `web/app.js`, assets/index, user guide; add browser tests `providers-ui.test.cjs`, `conversation-trash-ui.test.cjs`.
- [ ] Add failing UI tests: add/edit supplier via actual assistant-settings route; models fetched into draft then saved; default and composer selection consistent; trash/archive visible from row menus; recover/purge confirmation; return controls44px high and target tools on desktop/mobile.
- [ ] Build supplier rows/one expanded editor, protocol presets, write-only key input, editable model rows, explicit model discovery, default model chooser. Keep runtime/permissions in a separate existing settings form and honor dirty draft guards.
- [ ] Add grouped searchable picker and `/model`, showing unavailable selection honestly. Selecting updates conversation version; the next request uses it while a running turn retains the previous choice. No key reaches browser pickers.
- [ ] Add `⋯` row actions and deleted scope; owner-confirmation dialog for permanent deletion; stop and discard event subscriptions when current conversation is deleted elsewhere. Preserve existing draft/search/scroll and archive/continue behavior.
- [ ] Emphasize return button with text/arrow,44px height and110px minimum width, `#tools`; adapt tools subpage breadcrumb consistently and verify narrow screens.
- [ ] Run new+old UI, assistant suite and isolated fresh `npm test`; perform independent final review and fix important findings. Preserve known full-suite baseline limitations from prior verification, avoid unrelated fixes.
- [ ] Update guide/design/verification, commit and push dsh. Stop local test copy, verified backup, deploy tracked files, retain config/dependencies, restart healthy and open both settings/assistant for visual review; no actual credential setup or real model calls.
@@ -0,0 +1,52 @@
# DSH 供应商、模型与会话管理
日期:2026-10-28(Asia/Shanghai)。用户已批准供应商列表、模型管理、对话选模型、归档/删除与回收站方案,并补充:助手设置必须同步适配,返回工具按钮要更大、更显眼。沿 `dsh` 分支实施。
## 界面与行为
- “系统设置 → 助手设置”分为模型供应商、默认模型、运行与权限三部分。供应商以 DSH 式列表/展开卡片呈现;添加支持 DeepSeek、OpenAI、Anthropic 预设及自定义兼容 API。
- 每个供应商独立保存显示名、协议、API 根地址、只写密钥、启用状态和模型列表。支持编辑、停用、删除,手动添加模型和显式获取模型目录。获取结果先填入草稿,保存才生效;目录获取不是模型调用成功的证明。
- 自定义协议为 `openai-completions`、`openai-responses`、`anthropic-messages`。现有 DeepSeek Messages 仍走已验证官方直连适配器,其他路由复用固定 `0.2.1-rc.2` 的 `dsh-llm-pi-ai`。
- 输入区模型控件与 `/model` 共用按供应商分组的可用模型目录。所有已登录成员只能选管理员启用、密钥已配置且模型存在的路由;供应商维护和工作台默认模型仅管理员操作。
- 模型选择保存到个人会话,下一轮生效。每轮记录使用的供应商/模型名称、ID 和配置版本。运行中请求使用启动时配置;被移除的选项显示不可用并要求重新选择,不静默换到其他供应商。
- 会话列表每行 `⋯` 菜单;活跃会话提供归档、删除,归档会话提供恢复、删除。增加“回收站”,可恢复或经确认永久删除。当前会话标题区保留可达的管理入口,窄屏可操作。
- 不自动定期清空回收站。永久删除仅针对本人已移入回收站的会话;提示将删除正文/消息/诊断快照,独立执行审计和已经延续到其他会话的上下文保留。
- 有模型回复或操作执行中的会话先阻断归档、删除和永久删除,提示停止回复或等待操作结束。删除不执行旧卡片、不重放操作、不释放当日额度。
- 返回工具使用带左箭头与明确文字的按钮,至少 44px 高、约 110px 宽、主色描边/浅底、加粗文本;手机上也可见。目标为 `#tools`,不是记录列表;工具区其他子页沿用一致返回样式。
## 数据与兼容
- 保留现有全局运行配置、权限、额度与加密方式。单供应商配置迁为 `deepseek` 供应商和默认模型,保留现有地址/模型/密钥,不启用未启用的助手。
- 供应商配置与默认选择存在同一 assistant SQLite 的独立加密记录中。密钥读接口只返回 hasApiKey,留空保留;修改协议或地址需重新填写密钥,防止旧凭据被发送到新目的地。
- 供应商 ID 稳定且唯一,版本冲突返回 409。最多 30 个供应商、每个最多 100 个唯一模型,字段均有限长;端点遵循既有 HTTPS/本机 HTTP 规则。
- 旧 settings API/旧测试的单供应商字段保持兼容,legacy 更新只同步到 legacy DeepSeek 行。新设置表单不发送这些旧凭据字段,避免覆盖其他供应商。
- 默认选择有独立版本。删除默认供应商时清空选择,提示选择可用模型;不擅自启用其他路由。实际调用前复核当前可用性,运行配置和选择被复制为该轮固定快照。
- 会话新增 deleted_at,软删除保留原 archived 状态;恢复按原状态还原,活跃会话额度仍为 50。正常列表、搜索、模型发送和操作路由排除回收站会话,回收站读取通过显式 scope。
- 使用独立调用记账表保留每日调用次数,迁移时回填已有 turn ID/day。永久删除可移除 turns、events、requests,但不删除额度记账和独立操作审计。
- 延续会话在子会话保存最近 3 轮继承上下文;旧延续链在删除前补齐继承快照,避免删除父会话破坏子会话连续性。继承内容继续加密,不暴露到其他用户。
- SSE/轮询遇到其他标签页删除会话时发布 conversation_removed 并终止订阅;UI 清除该会话草稿和正文,刷新目录,不错误触发全局退出或无限重连。
- 备份恢复识别供应商、默认模型、会话事件和请求记录的实际加密 AAD,覆盖新增表的恢复往返;不能因新增表破坏可恢复性。
## 接口契约
| 接口 | 作用 |
|---|---|
| GET /api/assistant/providers | 已登录可见供应商/模型目录;管理员含编辑元数据但不含密钥 |
| POST /api/assistant/providers | 管理员新增/更新,包含 provider version |
| POST /api/assistant/providers/:id/delete | 管理员删除配置,检查版本与正在使用的调用 |
| POST /api/assistant/providers/:id/models | 管理员显式获取模型目录,检查版本/超时/响应大小 |
| POST /api/assistant/providers/default | 管理员设置默认供应商和模型,检查目录版本 |
| POST /api/assistant/conversations/:id/model | 本人会话选择,包含会话 version/providerId/modelId |
| POST .../:id/delete、restore-deleted、purge | 本人会话的回收站生命周期;purge 还需 confirm=delete |
| GET .../conversations?scope=deleted | 本人的回收站目录,继续支持标题搜索和分页 |
| GET .../conversations/:id?scope=deleted | 本人的回收站会话只读详情,不开事件订阅 |
现有 settings、archive/restore/continue/messages/cancel/execute 路径保持兼容。所有修改沿同源与角色检查,凭据维护沿部署机本地或可信 HTTPS 约束。
## 实施与验证
供应商模块、官方运行时适配、会话生命周期、模型选择/助手设置分别保持小模块边界。使用 TDD、独立审查、私有临时 LOCALAPPDATA 和既有 DSH 运行包;避免测试凭据写入历史运行目录。
验证三种协议的官方 DSH + 本地假模型、密钥隔离/脱敏/配置变更、会话切换/回收站/跨用户/并发/调用额度/继承链/SSE、完整助手专项、业务回归、备份恢复及桌面/手机界面。删除测试只操作虚构会话。
完成后提交并同步 `dsh`。按已授权本机测试副本流程先停服、备份、逐文件更新、保留配置/业务数据、启动并实际打开助手设置与助手界面;不操作正式服务机,不自动启用模型或输入真实供应商凭据。