Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
252 changes: 252 additions & 0 deletions docs/dsh-integration.md

Large diffs are not rendered by default.

38 changes: 35 additions & 3 deletions src/mex/integration/dsh/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,38 @@ dsh web

新开一个会话,让 agent"读一下我的画像",应能返回 `mex profile` 的内容(对应 `mex_profile` 工具)。

## meX 记忆面板(Client half)

插件自带一个浏览器 UI 面板,默认停靠在页面**右下角**:

- 每轮对话(dsh 的 Turn)结束后,面板提示"本轮对话已结束,可加入记忆";
- 点击 **Add to MeX** 按钮:插件触发一轮全新的 agent 对话,自动把
**抽取记忆 prompt + 本轮对话文本**交给该 agent,由 agent 调用 `mex_add` /
`mex_update` 等工具把值得记住的信息写入 meX;
- 抽取 prompt 依据 `src/mex/llm/prompts.py` 的抽取规范精简而成:画像 vs
画像外区分、置信度五档(禁止 confirmed)、质量标准(具体/独立/有用/不重复)、
时间规范(具体日期),并引导 agent 先用 `mex_profile` / `mex_list` 查重。

**透明可见(非黑盒)**:点击后面板自动打开抽取子代理的**会话视图**——用户
实时看到抽取 agent 的思考过程与每一步工具调用(`mex_search` / `mex_add` 等),
与查看普通对话完全一致。抽取子代理**保留**在当前会话的侧边栏子代理目录中
(运行状态圆点:进行中 → 完成),可随时点开回看这次抽取做了什么;面板同时
显示"抽取中…"与"查看运行过程"按钮,完成后显示"已写入 N 条记忆"。

实现:Host half(`panel.js`)监听 `agent/turn-stopping` 事件缓存本轮对话,
注册 `/mex/panel-state`(状态轮询)与 `/mex/extract`(触发抽取)两个 HTTP 接口,
并监听 `subagent/end` 标记抽取完成;Client half(`client.js`)注册到
`shell.overlay` 浮动层并调用这两个接口,通过 `sessions.openSubagent` 打开
子代理会话视图。面板是**可拖动浮窗**(标题栏拖拽,位置记忆在 localStorage,
默认停靠右下角);颜色跟随 dsh 主题——深色用主题 token,浅色微调为更浅的
灰底与更深绿提示,保证可读性。

> **注意**:抽取依赖 spawn 子代理(`dsh-subagent-spawn-in-process`,dsh 默认
> 装配),且每次抽取以"最近一轮对话"为单位——多轮未点只抽取最近一轮,点一次抽一轮。
>
> **完整实现细节**(触发链路、prompt 设计、防重复机制、与 ADR-12 的关系等)
> 见设计文档 [`docs/dsh-integration.md`](../../../../docs/dsh-integration.md)。

## 提供的工具(13 个)

| 工具 | 对应 mex 命令 | 说明 |
Expand Down Expand Up @@ -83,11 +115,11 @@ dsh web

## 开发与更新插件(mex 开发者)

插件的**唯一源码位置**是 `src/mex/integration/dsh/` 下的四个模板文件(`index.js` / `package.json` / `cordis.patch.yml` / `README.md`)。`mex-dsh-plugin/` 是 `mex integrate dsh` 的**生成产物**(已 gitignore),**不要直接改它**——改了会在下次重新生成时被覆盖丢失。
插件的**唯一源码位置**是 `src/mex/integration/dsh/` 下的六个模板文件(`index.js` / `panel.js` / `client.js` / `package.json` / `cordis.patch.yml` / `README.md`)。`mex-dsh-plugin/` 是 `mex integrate dsh` 的**生成产物**(已 gitignore),**不要直接改它**——改了会在下次重新生成时被覆盖丢失。

### 更新生效三步

1. **改模板**:编辑 `src/mex/integration/dsh/index.js`(工具实现)或 `cordis.patch.yml`(补丁层)。
1. **改模板**:编辑 `src/mex/integration/dsh/` 下的源码(`index.js` 工具实现、`panel.js` Host 面板逻辑、`client.js` 浏览器面板)或 `cordis.patch.yml`(补丁层)。
开发环境是 `pip install -e .`(editable 安装),改完即生效,无需重装。
2. **重新生成**:在 mex 项目根目录执行:

Expand All @@ -108,7 +140,7 @@ dsh web
- **一致性检查**:重新生成后确认模板与产物无漂移:

```sh
diff -q src/mex/integration/dsh/index.js mex-dsh-plugin/index.js
diff -rq src/mex/integration/dsh/ mex-dsh-plugin/ # 排除 node_modules/package-lock.json
```

若不一致,说明有人改过生成产物或模板未重新生成——以模板为准,重新生成一次。
Expand Down
Loading
Loading