dsh-miloco-bridge 0.1.4 → 0.1.6
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.
- package/README.md +28 -11
- package/cordis.patch.yml +13 -2
- package/docs/ARCHITECTURE.md +96 -17
- package/docs/INSTALL.md +29 -13
- package/docs/TOOLS.md +1 -1
- package/docs/VERIFICATION.md +50 -18
- package/docs/images/miloco-overview.png +0 -0
- package/docs/images/miloco-settings.png +0 -0
- package/docs/images/miloco-setup.png +0 -0
- package/lib/client.js +1386 -54
- package/lib/home.js +319 -0
- package/lib/index.js +57 -1
- package/lib/miloco-client.js +13 -5
- package/lib/overlay.js +53 -7
- package/lib/paths.js +18 -0
- package/lib/push.js +328 -48
- package/lib/settings-api.js +435 -7
- package/lib/state.js +62 -2
- package/lib/tools-entry.js +3 -1
- package/lib/tools.js +37 -7
- package/package.json +7 -2
package/README.md
CHANGED
|
@@ -11,11 +11,13 @@
|
|
|
11
11
|
|
|
12
12
|
## 截图
|
|
13
13
|
|
|
14
|
-
| Agent 预设 | Miloco
|
|
15
|
-
|
|
16
|
-
|  |  |  |  |  |
|
|
17
17
|
|
|
18
18
|
> 截图使用演示数据;真实账号、内网地址与 token 用量已脱敏。
|
|
19
|
+
> 初始化页是「还没连上 Miloco」或「连上了但还没绑定米家账号」时看到的独立引导页,
|
|
20
|
+
> 与配好之后的家庭概览不是同一套版式。
|
|
19
21
|
|
|
20
22
|
## 它解决什么问题
|
|
21
23
|
|
|
@@ -23,9 +25,18 @@
|
|
|
23
25
|
普通对话看不到 `miloco_*` 工具,也不会被注入 Miloco 技能。
|
|
24
26
|
- **完整能力**:设备、场景、感知、规则、任务、身份、宠物、家庭档案、通知、token 用量。
|
|
25
27
|
- **推送闭环**:Miloco 的感知事件、规则触发、任务到期可以主动推送到 DSH 会话。
|
|
28
|
+
- **家庭概览**:侧栏「Miloco 家庭助手」打开家庭概览(账号、设备、摄像头、规则/任务、
|
|
29
|
+
感知与 token 用量)、设备/房间、最近事件、推送记录与连接状态。
|
|
30
|
+
- **初始化引导**:没连上 Miloco、或连上了但还没绑定米家账号时,页面是一张独立的
|
|
31
|
+
居中引导页(三步清单 + 绑定入口),不是配好之后的仪表盘;
|
|
32
|
+
绑定可以直接跳到 Miloco 自己的页面,也可以在本页粘贴小米回调页的授权内容完成。
|
|
33
|
+
- **家庭工作区**:家庭工作区默认置顶显示,可在配置里修改目录、被误删后 30 秒内自动恢复;
|
|
34
|
+
关闭「启用置顶工作区」后不再注册工作区,其中的会话归到「未分组」。
|
|
35
|
+
- **推送归档**:推送默认进入专用归档会话 `miloco-archive`,也可在配置里改为任意指定会话;
|
|
36
|
+
会话内以折叠卡片展示,结构与 DSH 自动化任务触发卡片一致。
|
|
26
37
|
- **感知过滤**:按 `low / medium / high` 事件优先级过滤,低于阈值的感知建议不产生 DSH turn。
|
|
27
|
-
-
|
|
28
|
-
|
|
38
|
+
- **可视化配置**:家庭工作区目录、推送目标、感知等级、运行模式、连接与卸载,
|
|
39
|
+
都在侧栏「Miloco 家庭助手」页面点「配置」完成。
|
|
29
40
|
- **可独立安装**:没有 Miloco 也能装插件;之后可在 UI 一键部署或连接已有实例。
|
|
30
41
|
|
|
31
42
|
## 安装
|
|
@@ -48,7 +59,7 @@ dsh plugin --profile web add github:exa160/dsh-miloco-bridge
|
|
|
48
59
|
|
|
49
60
|
```bash
|
|
50
61
|
# 发布包
|
|
51
|
-
dsh plugin --profile web add file:dist/dsh-miloco-bridge-0.1.
|
|
62
|
+
dsh plugin --profile web add file:dist/dsh-miloco-bridge-0.1.6.tgz
|
|
52
63
|
|
|
53
64
|
# 本地开发(link)
|
|
54
65
|
./install.sh --profile web
|
|
@@ -67,12 +78,16 @@ systemctl --user restart dsh-web.service
|
|
|
67
78
|
|
|
68
79
|
## 快速开始
|
|
69
80
|
|
|
70
|
-
1. 打开 DSH WebUI
|
|
81
|
+
1. 打开 DSH WebUI → 侧栏「Miloco 家庭助手」。
|
|
82
|
+
- 还没配置时看到的是初始化页:按三步走(部署或连接 Miloco → 绑定米家账号 → 启用推送)。
|
|
83
|
+
- 点「开始配置」可打开配置弹窗;点「在 Miloco 中绑定 ↗」直接去 Miloco 自己的页面绑定账号。
|
|
71
84
|
2. 没有 Miloco:点「一键部署 Miloco」;已有实例:点「连接已有的 Miloco」。
|
|
72
|
-
3. 新建会话时选择 **「Miloco
|
|
73
|
-
4.
|
|
85
|
+
3. 新建会话时选择 **「Miloco 家庭助手」**,或用概览页的「新建家庭会话」。
|
|
86
|
+
4. 在配置弹窗里选择运行模式(只读 / 管家)、推送会话、可选模型与感知等级,并可修改家庭工作区目录。
|
|
74
87
|
5. 想收 Miloco 主动推送时,确认 Miloco 的 `agent.platform=dsh`,并使用同一枚 Bearer token。
|
|
75
88
|
|
|
89
|
+
> 隐私:插件只与本机 Miloco 通信,不上传账号、令牌或家庭数据;绑定建议优先用 Miloco 自己的流程。
|
|
90
|
+
|
|
76
91
|
## 权限与风险
|
|
77
92
|
|
|
78
93
|
- 写入 `$DSH_HOME`(配置、状态、可选部署源码)和 `$MILOCO_HOME`(adapter)。
|
|
@@ -80,10 +95,12 @@ systemctl --user restart dsh-web.service
|
|
|
80
95
|
- 「一键部署」会运行上游 Miloco 安装器,可能安装 Python 依赖并占用磁盘。
|
|
81
96
|
- **默认只读**:写工具不注册;切换到管家模式后才会暴露设备控制、规则/任务创建等能力。
|
|
82
97
|
- 插件不包含遥测,不内置任何账号或 token;推送入口无令牌时 fail closed。
|
|
98
|
+
- 绑定米家账号时,插件只把一次性授权码转交给本机 Miloco:不落日志、不回显浏览器,
|
|
99
|
+
也不会把账号、令牌或家庭数据上传到任何第三方。
|
|
83
100
|
|
|
84
101
|
## 兼容性
|
|
85
102
|
|
|
86
|
-
- DSH:`0.2.
|
|
103
|
+
- DSH:`0.2.2-rc.5` 实测通过;建议 `>= 0.2.2-rc.5`。
|
|
87
104
|
- Node.js:`>= 22`。
|
|
88
105
|
- Miloco:2.0 HTTP API(`/api/*`,`/api/admin/status`、`/api/perception/*` 等)。
|
|
89
106
|
- 平台:Linux / macOS;Web profile(`dsh --profile web`)。
|
|
@@ -102,7 +119,7 @@ systemctl --user restart dsh-web.service
|
|
|
102
119
|
## 开发
|
|
103
120
|
|
|
104
121
|
```bash
|
|
105
|
-
npm test #
|
|
122
|
+
npm test # 157 项测试
|
|
106
123
|
npm run selftest # 离线自检
|
|
107
124
|
npm run verify:readonly # 真实 Miloco 只读接口
|
|
108
125
|
npm run pack:bundle # 生成 dist/*.tgz
|
package/cordis.patch.yml
CHANGED
|
@@ -24,8 +24,18 @@
|
|
|
24
24
|
# 留空 = 自动读取 $MILOCO_HOME/config.json 的 server.url / server.token。
|
|
25
25
|
baseUrl: ""
|
|
26
26
|
token: ""
|
|
27
|
+
# Miloco 后端安装目录。
|
|
27
28
|
home: "~/.miloco"
|
|
28
29
|
timeoutMs: 30000
|
|
30
|
+
# 家庭助手专属工作区:插件自己创建这个目录并注册成宿主工作区,
|
|
31
|
+
# 该工作区下的会话一律使用 `agentPreset` 指定的 Agent 预设。
|
|
32
|
+
workspace:
|
|
33
|
+
# 空 = $DSH_HOME/plugin-data/dsh-miloco-bridge/home
|
|
34
|
+
dir: ""
|
|
35
|
+
# false = 不再注册/自愈家庭工作区;用于有意移除(卸载插件亦可)。
|
|
36
|
+
enabled: true
|
|
37
|
+
title: "家庭助手"
|
|
38
|
+
agentPreset: "miloco"
|
|
29
39
|
# 留空 = $DSH_HOME/miloco-plugin.json / $DSH_HOME/miloco-plugin.state.json
|
|
30
40
|
overlayFile: ""
|
|
31
41
|
stateFile: ""
|
|
@@ -38,9 +48,10 @@
|
|
|
38
48
|
token: ""
|
|
39
49
|
waitForResult: true
|
|
40
50
|
target:
|
|
41
|
-
#
|
|
51
|
+
# archive = 投到插件管理的专用归档会话;session = 用下面的 sessionId。
|
|
52
|
+
mode: "archive"
|
|
53
|
+
# session 模式下为空 = 投到「上一次触发 miloco 的会话」。
|
|
42
54
|
sessionId: ""
|
|
43
|
-
# 新建推送会话时使用的 Agent 预设。
|
|
44
55
|
agentPreset: "miloco"
|
|
45
56
|
model:
|
|
46
57
|
# 空 = 跟随目标对话自己选的模型;provider+model 都填才覆盖。
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -35,6 +35,7 @@ lib/
|
|
|
35
35
|
├── skills.js SKILL.md 读取与 ctx.skills.register
|
|
36
36
|
├── miloco-client.js Miloco HTTP 客户端(连接优先级、envelope 解包)
|
|
37
37
|
├── push.js 入站推送:鉴权、目标解析、会话恢复、等待 turn
|
|
38
|
+
├── home.js 家庭工作区:创建目录、注册、置顶、改名
|
|
38
39
|
├── settings-api.js 设置 API 路由
|
|
39
40
|
├── deploy.js 一键部署(启动已有 / 下载 release 安装器 / 写 adapter)
|
|
40
41
|
├── uninstall.js 卸载 Miloco(停服务 / 移除 adapter / 可选删数据或源码)
|
|
@@ -61,7 +62,63 @@ adapter/dsh_adapter.py Miloco 侧 agent_platform adapter
|
|
|
61
62
|
第 1 层是运行时层,Web 设置页“连接已有的 Miloco”写的就是它,所以两个半边
|
|
62
63
|
(全局与预设)都能立即读到新连接,不需要重启。
|
|
63
64
|
|
|
64
|
-
|
|
65
|
+
### 3.1 运行时 overlay
|
|
66
|
+
|
|
67
|
+
`$DSH_HOME/miloco-plugin.json`(0600)是唯一可在运行时改写的配置层:
|
|
68
|
+
|
|
69
|
+
| 字段 | 含义 |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `connection.baseUrl` / `connection.token` | 连接覆盖,优先于静态配置 |
|
|
72
|
+
| `push.token` | 入站 Bearer;为空时回退静态 `push.token` |
|
|
73
|
+
| `push.target.mode` | 推送投递方式:`archive`(默认)/ `session` |
|
|
74
|
+
| `push.target.sessionId` | `session` 模式下的目标会话;空 = 上次触发 Miloco 的会话 |
|
|
75
|
+
| `home.dir` | 家庭工作区目录,覆盖静态 `workspace.dir` |
|
|
76
|
+
| `push.model` / `push.perception.minLevel` | 模型覆盖与感知阈值 |
|
|
77
|
+
|
|
78
|
+
写入是合并式的:只改一个字段不会丢掉其他字段。
|
|
79
|
+
|
|
80
|
+
## 4. 家庭工作区与概览
|
|
81
|
+
|
|
82
|
+
`home.js` 维护一个家庭工作区:概览页「新建家庭会话」建出的会话、以及推送创建/复用的
|
|
83
|
+
归档会话,工作目录都是它。会话本身仍可带自己的 cwd——例如手动把「Miloco 家庭助手」
|
|
84
|
+
预设挂到别的工作区的会话上,那个会话保留自己的 workspace cwd,不会迁到这里。
|
|
85
|
+
|
|
86
|
+
- 目录解析顺序:`overlay.home.dir` → 静态 `workspace.dir` →
|
|
87
|
+
`$DSH_HOME/plugin-data/dsh-miloco-bridge/home`;
|
|
88
|
+
- 启动时创建目录、注册为宿主 Workspace、改名为 `workspace.title`(默认「家庭助手」),
|
|
89
|
+
每次 `ensure()` 都会重新置顶,避免被后建的工作区挤到下面;
|
|
90
|
+
- 设置页“修改目录”写 overlay 后**注册一个新的工作区**;旧目录的工作区注册
|
|
91
|
+
**不会**被移除,旧目录与其中的会话都不受影响(与设置页同一段文案);
|
|
92
|
+
- 设置页“启用置顶工作区”写 `overlay.workspace.enabled`(默认 `true`):关闭后
|
|
93
|
+
`ensure()` 调 `workspaceRegistry.delete()` 注销工作区,其中的会话随之落到「未分组」,
|
|
94
|
+
重新打开时再注册并置顶;
|
|
95
|
+
- 宿主没有 `workspaceRegistry` 时只建目录,`workspaceId` 为空,不报错。
|
|
96
|
+
|
|
97
|
+
概览页(侧栏「Miloco 家庭助手」)读 `GET /home/overview`:后端状态与版本、家庭概览统计
|
|
98
|
+
(账号、设备、摄像头、规则/任务、感知源、token 用量)、设备与房间分组、最近事件、
|
|
99
|
+
最近推送记录、归档会话是否存在。每个远端接口独立结算,单个接口不可达不会涂黑整页。
|
|
100
|
+
|
|
101
|
+
`/home/overview` 另带一个 `setup` 段,描述“装好没有”:连接是否可达、账号是否绑定、
|
|
102
|
+
推送令牌是否就绪、Miloco 自己的页面地址。页面按它分成四种互斥形态:
|
|
103
|
+
|
|
104
|
+
| 形态 | 触发条件 | 版式 |
|
|
105
|
+
|---|---|---|
|
|
106
|
+
| 加载中 | 还没有第一次响应 | 整页居中的转圈提示(不渲染仪表盘头部) |
|
|
107
|
+
| 读取失败 | 整个请求失败 | 整页居中的错误说明 + 「重试」/「打开配置」 |
|
|
108
|
+
| 初始化 | 连不上 Miloco,或连上了但账号未绑定 | 整页居中的三步清单 + 绑定入口 |
|
|
109
|
+
| 仪表盘 | 连得上且账号已绑定 | 家庭概览、设备房间、事件与推送 |
|
|
110
|
+
|
|
111
|
+
未配置与已配置**不共用一套版式**:没有账号时仪表盘本来就是空的,不如给一页独立的
|
|
112
|
+
初始化引导。绑定账号有两条路,按推荐顺序排:
|
|
113
|
+
|
|
114
|
+
1. 「在 Miloco 中绑定 ↗」——打开 Miloco 自己的页面,用它现成的绑定向导(推荐);
|
|
115
|
+
2. 「在本页绑定」——插件代走一遍:`POST /miot/bind` 拿小米授权链接,用户在小米页
|
|
116
|
+
授权后把回调页给出的整段内容粘回来,插件解出 `code`/`state` 再交给 Miloco。
|
|
117
|
+
|
|
118
|
+
插件只与本机 Miloco 通信,不上传账号、令牌或家庭数据;授权码是一次性凭据,
|
|
119
|
+
只转发给 Miloco,不落日志、不回显给浏览器。
|
|
120
|
+
|
|
121
|
+
## 5. 设置 API
|
|
65
122
|
|
|
66
123
|
前缀:`/dsh-miloco-bridge/api`
|
|
67
124
|
|
|
@@ -74,10 +131,15 @@ adapter/dsh_adapter.py Miloco 侧 agent_platform adapter
|
|
|
74
131
|
| GET | `/deploy` | 部署状态与日志 |
|
|
75
132
|
| POST | `/deploy` | 启动部署 |
|
|
76
133
|
| POST | `/connect` | 写连接与推送令牌,立即生效 |
|
|
134
|
+
| GET | `/home` | 家庭工作区快照(路径、标题、dirSource、归档会话 id、enabled) |
|
|
135
|
+
| POST | `/home` | 修改家庭工作区目录或置顶开关(写 overlay,注册/注销工作区) |
|
|
136
|
+
| GET | `/home/overview` | 家庭概览聚合(状态、版本、概览统计、设备、事件、推送记录)+ `setup` 段(连接/账号/推送是否就绪) |
|
|
137
|
+
| POST | `/miot/bind` | 取小米授权链接(`{oauthUrl, state}`),供初始化页绑定账号 |
|
|
138
|
+
| POST | `/miot/authorize` | 提交回调页给出的授权内容,解出 `code`/`state` 交给 Miloco 完成绑定 |
|
|
77
139
|
|
|
78
140
|
写操作要求同源;令牌不会回显给浏览器。
|
|
79
141
|
|
|
80
|
-
##
|
|
142
|
+
## 6. 状态文件
|
|
81
143
|
|
|
82
144
|
`$DSH_HOME/miloco-plugin.state.json`:
|
|
83
145
|
|
|
@@ -88,6 +150,9 @@ adapter/dsh_adapter.py Miloco 侧 agent_platform adapter
|
|
|
88
150
|
"lastSessionAt": 1793119479596,
|
|
89
151
|
"sessions": [
|
|
90
152
|
{ "id": "miloco-agent-main-miloco", "at": 1793119479596 }
|
|
153
|
+
],
|
|
154
|
+
"pushLog": [
|
|
155
|
+
{ "at": 1793119480000, "title": "感知", "summary": "门口有人停留", "sessionId": "miloco-archive", "status": "ok", "runId": "…" }
|
|
91
156
|
]
|
|
92
157
|
}
|
|
93
158
|
```
|
|
@@ -95,11 +160,13 @@ adapter/dsh_adapter.py Miloco 侧 agent_platform adapter
|
|
|
95
160
|
- 两个半边在不同作用域,不能共享内存,所以用文件;
|
|
96
161
|
- `lastSession` 由工具执行时记录:`exec.agent.session.header.id`;
|
|
97
162
|
- 同一会话 60 秒内只写一次,避免频繁落盘;
|
|
163
|
+
- `pushLog`:最近 20 条推送元数据(时间、标题、摘要、目标会话、状态、runId),新的在前;
|
|
164
|
+
解析目标失败的那次推送不记录;
|
|
98
165
|
- 只存会话 id 与时间,不存对话内容。
|
|
99
166
|
|
|
100
|
-
##
|
|
167
|
+
## 7. 推送协议
|
|
101
168
|
|
|
102
|
-
###
|
|
169
|
+
### 7.1 入站
|
|
103
170
|
|
|
104
171
|
```http
|
|
105
172
|
POST /miloco/webhook
|
|
@@ -130,20 +197,25 @@ Content-Type: application/json
|
|
|
130
197
|
- `action: "get_trace"`:返回已知结果或 `status: "unknown"`
|
|
131
198
|
- `action: "reset_sessions"`:清掉对应 sessionKey 的记忆
|
|
132
199
|
|
|
133
|
-
###
|
|
200
|
+
### 7.2 目标解析
|
|
134
201
|
|
|
135
202
|
```
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
203
|
+
mode = overlay.push.target.mode || push.target.mode || 'archive'
|
|
204
|
+
|
|
205
|
+
mode = archive → sessionId = miloco-archive
|
|
206
|
+
mode = session → sessionId = overlay.push.target.sessionId
|
|
207
|
+
|| static push.target.sessionId
|
|
208
|
+
|| state.lastSession
|
|
209
|
+
|| derive(sessionKey)
|
|
140
210
|
```
|
|
141
211
|
|
|
142
|
-
-
|
|
212
|
+
- `archive`(默认):所有推送进同一个专用归档会话 `miloco-archive`,首次推送时创建,
|
|
213
|
+
带家庭工作区目录与 `miloco` 预设,标题「Miloco 推送归档」,之后一直复用;
|
|
214
|
+
- `session`:显式配置的会话不存在 → 创建它;
|
|
143
215
|
- 默认的 lastSession 已被删除 → 回退到派生 id,再创建;
|
|
144
216
|
- 新建会话默认挂 `miloco` 预设(可通过 `push.target.agentPreset` 改)。
|
|
145
217
|
|
|
146
|
-
###
|
|
218
|
+
### 7.3 感知过滤
|
|
147
219
|
|
|
148
220
|
推送到达 DSH 后、解析目标会话前,先按感知优先级过滤:
|
|
149
221
|
|
|
@@ -159,13 +231,13 @@ push.perception.minLevel = all | low | medium | high
|
|
|
159
231
|
- Miloco adapter 会把解析出的 urgency 放进 payload;即使使用旧 adapter,
|
|
160
232
|
DSH 也能从消息文本里解析。
|
|
161
233
|
|
|
162
|
-
###
|
|
234
|
+
### 7.4 模型
|
|
163
235
|
|
|
164
236
|
- `provider` 与 `model` 都为空:**不调用** `selectModel`,完全跟随会话;
|
|
165
237
|
- 两者都有:`selectModel`,只影响该会话;
|
|
166
238
|
- 只填一个:设置页拒绝;工具层也拒绝,避免“半配置”导致误判。
|
|
167
239
|
|
|
168
|
-
###
|
|
240
|
+
### 7.5 等待 turn
|
|
169
241
|
|
|
170
242
|
`waitForResult: true` 时:
|
|
171
243
|
|
|
@@ -174,11 +246,18 @@ push.perception.minLevel = all | low | medium | high
|
|
|
174
246
|
3. 只有同一 turn 的 `turn/end` 才结算;
|
|
175
247
|
4. 超时返回 `status: "timeout"`,不阻塞后续推送。
|
|
176
248
|
|
|
177
|
-
###
|
|
249
|
+
### 7.6 单归档会话的限制
|
|
250
|
+
|
|
251
|
+
所有推送默认进入同一个归档会话,因此前一次 turn 还没结束时到达的推送会和它挤在同一条会话里:
|
|
252
|
+
等待结果的调用可能报 `status: "timeout"`,也可能把回复归到另一次推送头上。推送本身仍会送达会话,
|
|
253
|
+
只是“哪条回复属于哪次推送”不再可辨。需要按次对齐回复时,把投递方式改为指定会话,
|
|
254
|
+
或把连发的推送拉开间隔。
|
|
255
|
+
|
|
256
|
+
### 7.7 幂等
|
|
178
257
|
|
|
179
258
|
`idempotencyKey`(或 `traceId`)在 10 分钟内只执行一次;重复请求返回相同 `runId` 并带 `idempotent: true`。
|
|
180
259
|
|
|
181
|
-
##
|
|
260
|
+
## 8. adapter
|
|
182
261
|
|
|
183
262
|
`adapter/dsh_adapter.py` 由 Miloco 的 `agent_platform` loader 动态加载:
|
|
184
263
|
|
|
@@ -188,7 +267,7 @@ push.perception.minLevel = all | low | medium | high
|
|
|
188
267
|
- 传输失败抛 `AdapterTransportError`(后端同进程时复用其公共异常类);
|
|
189
268
|
- 不 import Miloco 业务模块,不复制上游代码。
|
|
190
269
|
|
|
191
|
-
##
|
|
270
|
+
## 9. 一键部署
|
|
192
271
|
|
|
193
272
|
`deploy.js` 的步骤:
|
|
194
273
|
|
|
@@ -209,7 +288,7 @@ push.perception.minLevel = all | low | medium | high
|
|
|
209
288
|
`--agent-finish` → 启动服务 → 写 adapter/webhook。升级状态与日志独立于部署,
|
|
210
289
|
日志在 `$MILOCO_HOME/log/dsh-miloco-upgrade.log`;命令参数和子进程输出都会脱敏。
|
|
211
290
|
|
|
212
|
-
##
|
|
291
|
+
## 10. 安全边界
|
|
213
292
|
|
|
214
293
|
- Web 设置页的写操作同源校验;
|
|
215
294
|
- 入站 webhook 常量时间比较 Bearer;
|
package/docs/INSTALL.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
## 0. 前置条件
|
|
4
4
|
|
|
5
5
|
- Node.js ≥ 22
|
|
6
|
-
- 可用的 DSH(本项目在 `0.2.
|
|
6
|
+
- 可用的 DSH(本项目在 `0.2.2-rc.5` 上验证)
|
|
7
7
|
- 可选:已安装或准备安装 Xiaomi Miloco
|
|
8
8
|
- 可选:`git`、`python3`(一键部署与 adapter 语法检查)
|
|
9
9
|
|
|
@@ -33,14 +33,14 @@ npm 新包可能处于审核期;若 `dsh plugin add dsh-miloco-bridge` 暂时
|
|
|
33
33
|
|
|
34
34
|
```bash
|
|
35
35
|
npm run pack:bundle
|
|
36
|
-
# dist/dsh-miloco-bridge-0.1.
|
|
37
|
-
dsh plugin --profile web add "file:/path/to/dist/dsh-miloco-bridge-0.1.
|
|
36
|
+
# dist/dsh-miloco-bridge-0.1.6.tgz
|
|
37
|
+
dsh plugin --profile web add "file:/path/to/dist/dsh-miloco-bridge-0.1.6.tgz"
|
|
38
38
|
```
|
|
39
39
|
|
|
40
40
|
或:
|
|
41
41
|
|
|
42
42
|
```bash
|
|
43
|
-
./install.sh --profile web --bundle dist/dsh-miloco-bridge-0.1.
|
|
43
|
+
./install.sh --profile web --bundle dist/dsh-miloco-bridge-0.1.6.tgz
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
### 1.3 手动配置
|
|
@@ -90,7 +90,7 @@ install.sh
|
|
|
90
90
|
## 3. 未安装 Miloco:一键部署
|
|
91
91
|
|
|
92
92
|
1. 安装并重启 DSH;
|
|
93
|
-
2.
|
|
93
|
+
2. 打开侧栏「Miloco 家庭助手」→ 右上角「配置」;
|
|
94
94
|
3. 点「一键部署 Miloco」;
|
|
95
95
|
4. 面板会实时显示部署日志。流程:
|
|
96
96
|
- 若检测到已安装的 `miloco-cli` 与 `$MILOCO_HOME/config.json`,先尝试 `service start`;
|
|
@@ -103,6 +103,12 @@ install.sh
|
|
|
103
103
|
- 安装本插件的 adapter,生成/复用推送令牌,写入 overlay。
|
|
104
104
|
5. 部署完成后按面板提示绑定米家账号、开启摄像头感知。
|
|
105
105
|
|
|
106
|
+
> 部署期间侧栏「Miloco 家庭助手」页面显示的是**初始化引导页**(不是家庭概览):
|
|
107
|
+
> 它会列出「部署或连接 Miloco / 绑定米家账号 / 接收 Miloco 推送」三步的完成状态,
|
|
108
|
+
> 账号没绑时页面上直接给出绑定入口——「在 Miloco 中绑定 ↗」跳到 Miloco 自己的页面,
|
|
109
|
+
> 或「在本页绑定」粘贴小米回调页给出的授权内容。
|
|
110
|
+
> 详见 [VERIFICATION.md](VERIFICATION.md#25-绑定米家账号可选路径)。
|
|
111
|
+
|
|
106
112
|
> **MILOCO_HOME 必须可写**:默认 `~/.miloco`,部署前会显式检查并给出中文错误。
|
|
107
113
|
> release 部署不再创建源码目录;`deploy.sourceDir` 仅用于旧源码部署或卸载清理。
|
|
108
114
|
|
|
@@ -115,7 +121,7 @@ install.sh
|
|
|
115
121
|
|
|
116
122
|
### 4.1 WebUI
|
|
117
123
|
|
|
118
|
-
|
|
124
|
+
「Miloco 家庭助手」页面 →「配置」→「连接已有的 Miloco」:
|
|
119
125
|
|
|
120
126
|
- `baseUrl`:例如 `http://192.0.2.10:1810`
|
|
121
127
|
- `token`:`$MILOCO_HOME/config.json` 的 `server.token`(如果后端未启用鉴权可留空)
|
|
@@ -168,7 +174,7 @@ adapter 是 duck-typed 的,只要求 `name` / `send_turn` / `read_trace_meta`
|
|
|
168
174
|
|---|---|---|
|
|
169
175
|
| bundle 默认 | `node_modules/dsh-miloco-bridge/cordis.patch.yml` | 工具/预设/推送默认值 |
|
|
170
176
|
| profile 覆盖 | `$DSH_HOME/profiles/<profile>/cordis.patch.yml` | 用户级静态覆盖 |
|
|
171
|
-
| 运行时 overlay | `$DSH_HOME/miloco-plugin.json` |
|
|
177
|
+
| 运行时 overlay | `$DSH_HOME/miloco-plugin.json` | 连接、推送令牌、推送目标、家庭目录;立即生效 |
|
|
172
178
|
| 共享状态 | `$DSH_HOME/miloco-plugin.state.json` | 运行模式、最近触发 Miloco 的会话 |
|
|
173
179
|
|
|
174
180
|
`$DSH_HOME` 默认 `~/.dsh`;设置环境变量后会跟随。
|
|
@@ -178,25 +184,35 @@ overlay 示例:
|
|
|
178
184
|
```json
|
|
179
185
|
{
|
|
180
186
|
"connection": { "baseUrl": "http://192.0.2.10:1810", "token": "…" },
|
|
187
|
+
"home": { "dir": "~/miloco-home" },
|
|
181
188
|
"push": {
|
|
182
189
|
"token": "…",
|
|
183
|
-
"target": { "sessionId": "" },
|
|
190
|
+
"target": { "mode": "archive", "sessionId": "" },
|
|
184
191
|
"model": { "provider": "", "model": "", "reasoningEffort": "" },
|
|
185
192
|
"perception": { "minLevel": "all" }
|
|
186
193
|
}
|
|
187
194
|
}
|
|
188
195
|
```
|
|
189
196
|
|
|
190
|
-
- `
|
|
197
|
+
- `home.dir`:家庭工作区目录,覆盖静态 `workspace.dir`;留空则用
|
|
198
|
+
`$DSH_HOME/plugin-data/dsh-miloco-bridge/home`。设置页改目录写的就是这一项;
|
|
199
|
+
- `target.mode`:`archive`(默认,所有推送进专用归档会话 `miloco-archive`)或
|
|
200
|
+
`session`(进下面 `sessionId` 指定的会话);
|
|
201
|
+
- `target.sessionId` 空 = 上一次触发 Miloco 的会话(仅 `session` 模式);
|
|
191
202
|
- `model` 空 = 跟随该对话;
|
|
192
203
|
- `perception.minLevel` = `all` / `low` / `medium` / `high`,低于该等级的感知建议不投递;
|
|
193
204
|
- `push.token` 与 Miloco 的 `agent.auth_bearer` 必须一致。
|
|
194
205
|
|
|
206
|
+
> 归档会话只有一个:前一次 turn 未结束时又到的推送会挤在同一会话里,等待结果可能
|
|
207
|
+
> 报 `timeout`,回复也可能归到另一次推送。推送本身仍会送达;需要按次对齐时改用
|
|
208
|
+
> `session` 模式,或把连发的推送拉开间隔。详见
|
|
209
|
+
> [ARCHITECTURE.md](ARCHITECTURE.md) 的 7.6。
|
|
210
|
+
|
|
195
211
|
---
|
|
196
212
|
|
|
197
213
|
## 6. 运行模式
|
|
198
214
|
|
|
199
|
-
|
|
215
|
+
「Miloco 家庭助手」页面 →「配置」→「Miloco 家庭助手 · 运行模式」:
|
|
200
216
|
|
|
201
217
|
| 模式 | 工具 |
|
|
202
218
|
|---|---|
|
|
@@ -249,7 +265,7 @@ systemctl --user restart dsh-web.service
|
|
|
249
265
|
|
|
250
266
|
### 8.1 卸载 Miloco(保留 DSH 插件)
|
|
251
267
|
|
|
252
|
-
|
|
268
|
+
「Miloco 家庭助手」页面 →「配置」→「运行状态 → 卸载 Miloco」:
|
|
253
269
|
|
|
254
270
|
1. 输入 `UNINSTALL` 确认;
|
|
255
271
|
2. 可选勾选:
|
|
@@ -273,7 +289,7 @@ systemctl --user restart dsh-web.service
|
|
|
273
289
|
|
|
274
290
|
```bash
|
|
275
291
|
npm run pack:bundle
|
|
276
|
-
dsh plugin --profile web add "file:dist/dsh-miloco-bridge-0.1.
|
|
292
|
+
dsh plugin --profile web add "file:dist/dsh-miloco-bridge-0.1.6.tgz"
|
|
277
293
|
systemctl --user restart dsh-web.service
|
|
278
294
|
```
|
|
279
295
|
|
|
@@ -308,7 +324,7 @@ rm -rf "$MILOCO_HOME/agent_platform/dsh"
|
|
|
308
324
|
| webhook 503 | 推送令牌为空(fail closed);在 WebUI 连接时填 `pushToken` |
|
|
309
325
|
| webhook 401 | DSH 与 Miloco 的令牌不一致 |
|
|
310
326
|
| 普通会话也有 miloco 工具 | 预设未生效;检查 `preset-miloco.plugins` |
|
|
311
|
-
| 推送落到了错误会话 |
|
|
327
|
+
| 推送落到了错误会话 | 默认 `archive` 模式下 `target.sessionId` 被忽略,所有推送都进归档会话 `miloco-archive`。要改投递目标,先在设置页「推送目标 → 投递方式」改为「指定会话」(`session`),再清空 `target.sessionId`(= 上一次触发 Miloco 的会话)或填入目标会话 id |
|
|
312
328
|
| 模型没跟随对话 | 检查 overlay 里是否残留 provider/model |
|
|
313
329
|
| `~` 路径读不到 | 升级到包含 `lib/paths.js` 的版本;路径会按 `$DSH_HOME` 展开 |
|
|
314
330
|
| Miloco 首页 404、但 `/api/*` 仍响应 | 后端进程可能还挂在旧源码路径(静态目录随源码移动而失效)。用 `supervisorctl reread/update` 重载配置后重启;若报 `No module named miloco`,检查 venv 的 editable `.pth` 是否仍指向旧路径 |
|
package/docs/TOOLS.md
CHANGED
|
@@ -70,7 +70,7 @@
|
|
|
70
70
|
| `miloco_pet_reference_crops` | `pet_id`, `files[]`, `mode?` | 落库参照图;multipart 字段为 `crops` |
|
|
71
71
|
| `miloco_register_preview` | `media_b64?`, `media_b64_list?`, `media_kind?`, `cluster_id?`, `member_id?`, `topk?` | 身份样本预览 |
|
|
72
72
|
| `miloco_register_commit` | `register_session_id_pending`, `indices?`, `member_name?`, `member_role?` | 身份样本落库 |
|
|
73
|
-
| `miloco_push_target_set` | `sessionId?`, `provider?`, `model?`, `reasoningEffort?`, `perceptionLevel?` |
|
|
73
|
+
| `miloco_push_target_set` | `mode?`, `sessionId?`, `provider?`, `model?`, `reasoningEffort?`, `perceptionLevel?` | 修改推送目标与感知等级;`mode` = `archive`(默认,忽略 `sessionId`)/ `session` |
|
|
74
74
|
|
|
75
75
|
## DSH 侧工具
|
|
76
76
|
|
package/docs/VERIFICATION.md
CHANGED
|
@@ -13,9 +13,9 @@
|
|
|
13
13
|
```bash
|
|
14
14
|
cd dsh-miloco-bridge
|
|
15
15
|
npm test
|
|
16
|
-
#
|
|
16
|
+
# 124 tests, 0 fail
|
|
17
17
|
npm run selftest
|
|
18
|
-
#
|
|
18
|
+
# 9 项离线自检
|
|
19
19
|
python3 -m py_compile adapter/dsh_adapter.py
|
|
20
20
|
```
|
|
21
21
|
|
|
@@ -23,7 +23,7 @@ python3 -m py_compile adapter/dsh_adapter.py
|
|
|
23
23
|
|
|
24
24
|
- 连接/overlay/state 的路径与权限(`0600`);
|
|
25
25
|
- 只读 30 工具、管家 56 工具;
|
|
26
|
-
-
|
|
26
|
+
- 推送目标:归档会话(默认)/ 上次会话 / 显式会话 / 派生会话 / 模型留空不调 `selectModel`;
|
|
27
27
|
- 感知过滤:结构化 urgency、文本“事件优先级”、批量取最高、ignore、阈值比较;
|
|
28
28
|
- webhook:无令牌 503、错令牌 401、正确令牌通过、幂等、turn 等待;
|
|
29
29
|
- 设置 API:概览、会话列表、`/target`、`/connect`、`/mode`、`/uninstall`;
|
|
@@ -116,18 +116,37 @@ curl -s -X POST http://127.0.0.1:3086/miloco/webhook \
|
|
|
116
116
|
### 2.4 浏览器 UI
|
|
117
117
|
|
|
118
118
|
1. 打开日志里的 `http://127.0.0.1:3086/?token=…`;
|
|
119
|
-
2.
|
|
120
|
-
|
|
121
|
-
-
|
|
122
|
-
-
|
|
119
|
+
2. 侧栏 **Miloco 家庭助手**。页面按当前状态给四种互斥的形态:
|
|
120
|
+
- **加载中**:整页居中的转圈提示,没有仪表盘头部(不会看到悬在顶上的「新建家庭会话 / 配置」);
|
|
121
|
+
- **读取失败**:整页居中的错误说明,带「重试」与「打开配置」;
|
|
122
|
+
- **初始化页**:连不上 Miloco、或连上了但账号未绑定时出现——三步清单
|
|
123
|
+
(部署或连接 Miloco / 绑定米家账号 / 接收 Miloco 推送),带完成状态,
|
|
124
|
+
并提供「在 Miloco 中绑定 ↗」与「在本页绑定」两个入口,底部是隐私说明;
|
|
125
|
+
- **家庭概览**:连得上且账号已绑定时的仪表盘。
|
|
126
|
+
3. 点右上角「配置」,应看到:
|
|
127
|
+
- 第一格:运行状态,后端地址是可点击链接,含「卸载 Miloco」入口;
|
|
128
|
+
- 家庭工作区:目录输入框 +「启用置顶工作区」开关(默认开启;关闭后家庭会话归到「未分组」);
|
|
129
|
+
- 家庭概览(账号、设备、摄像头、规则/任务、感知、token)在侧栏「Miloco 家庭助手」页面上;
|
|
123
130
|
- 运行模式:只读 / 管家(不再有聊天模式),每条模式说明独立换行;
|
|
124
131
|
- 「查看模式说明与用法」可展开等价说明(DSH 只给内置预设提供帮助弹窗);
|
|
125
132
|
- 推送目标:会话输入框(可下拉)、模型下拉只有「跟随该对话自己选的模型」;
|
|
126
133
|
- 推理强度只在所选模型确实提供 efforts 时显示;没有选项时整行隐藏;
|
|
127
134
|
- 「感知等级」可选择全部 / 低及以上 / 中及以上 / 仅高优先级;
|
|
128
|
-
4.
|
|
135
|
+
4. 窄窗口下标题「家庭助手」与「新建家庭会话 / 配置」仍在同一行(标题先让位,不会换行);
|
|
136
|
+
5. 新建会话的预设菜单里应出现 **Miloco 家庭助手**。
|
|
129
137
|
|
|
130
|
-
|
|
138
|
+
### 2.5 绑定米家账号(可选路径)
|
|
139
|
+
|
|
140
|
+
初始化页的「在本页绑定」走的是 Miloco 自己的三步 OAuth:
|
|
141
|
+
|
|
142
|
+
1. `POST /dsh-miloco-bridge/api/miot/bind` → 返回 `{ oauthUrl, state }`;
|
|
143
|
+
2. 浏览器打开 `oauthUrl`,在小米页授权后,回调页会给出整段 base64 内容;
|
|
144
|
+
3. 粘贴回页面 → `POST /dsh-miloco-bridge/api/miot/authorize`(插件解出 `code`/`state` 转发给 Miloco)。
|
|
145
|
+
|
|
146
|
+
验证点:授权链接能打开;粘贴非法内容时接口返回 400 且不向 Miloco 转发;
|
|
147
|
+
非法授权码返回 Miloco 的错误信息;授权码不落日志、不回显浏览器。
|
|
148
|
+
|
|
149
|
+
本次实现已按上述步骤实测通过(DSH `0.2.2-rc.5`)。
|
|
131
150
|
|
|
132
151
|
---
|
|
133
152
|
|
|
@@ -165,15 +184,23 @@ schema(required、additionalProperties、enum)。所有 HTTP 工具的路径
|
|
|
165
184
|
|
|
166
185
|
### 4.1 目标语义
|
|
167
186
|
|
|
187
|
+
投递方式由 `push.target.mode` 决定,默认是 `archive`:
|
|
188
|
+
|
|
168
189
|
| 配置 | 预期 |
|
|
169
190
|
|---|---|
|
|
170
|
-
| `target.
|
|
171
|
-
| `target.sessionId=""
|
|
172
|
-
| `target.sessionId="
|
|
191
|
+
| `target.mode="archive"`(默认,省略即此值) | 所有推送进归档会话 `miloco-archive`;首次推送时懒创建,工作目录 = 家庭工作区,挂 `miloco` 预设,标题「Miloco 推送归档」,之后一直复用;`target.sessionId` 被忽略 |
|
|
192
|
+
| `target.mode="session"`,`target.sessionId=""`,最近调用过 `miloco_*` 工具 | 投到该会话 |
|
|
193
|
+
| `target.mode="session"`,`target.sessionId=""`,没有记录 | 投到 `miloco-agent-main-miloco`(按 `sessionKey` 派生) |
|
|
194
|
+
| `target.mode="session"`,`target.sessionId="<id>"` | 投到该会话;不存在则创建并挂 `miloco` 预设 |
|
|
173
195
|
| `model` 空 | 不调用 `selectModel`,跟随会话 |
|
|
174
196
|
| `provider+model` | 对目标会话调用 `selectModel` |
|
|
175
197
|
|
|
176
|
-
|
|
198
|
+
`archive` 下 `target.sessionId` 不参与解析:想按会话投递,要先把投递方式改为
|
|
199
|
+
「指定会话」(`target.mode: "session"`),配置的会话 → 上次触发 Miloco 的会话 →
|
|
200
|
+
`sessionKey` 派生这条回退链才会重新生效。
|
|
201
|
+
|
|
202
|
+
离线测试已覆盖上表全部分支;真实环境可用下面的 curl 检查(`message` 为空不会触发 LLM)。
|
|
203
|
+
下面的请求不带 `mode`,所以按默认落进归档会话 `miloco-archive`:
|
|
177
204
|
|
|
178
205
|
```bash
|
|
179
206
|
curl -s -X POST http://127.0.0.1:3086/miloco/webhook \
|
|
@@ -191,7 +218,9 @@ miloco-cli config get agent.webhook_url
|
|
|
191
218
|
# http://<dsh-host>:3080/miloco/webhook
|
|
192
219
|
```
|
|
193
220
|
|
|
194
|
-
在 Miloco
|
|
221
|
+
在 Miloco 面板触发一次规则或任务:默认 `archive` 模式下,推送以折叠卡片出现在
|
|
222
|
+
「Miloco 推送归档」(`miloco-archive`)会话里,概览页的推送记录也会多一条。
|
|
223
|
+
DSH 日志应出现:
|
|
195
224
|
|
|
196
225
|
```text
|
|
197
226
|
dsh-miloco-bridge: push delivery failed ... # 仅在失败时
|
|
@@ -211,8 +240,8 @@ dsh-miloco-bridge: push delivery failed ... # 仅在失败时
|
|
|
211
240
|
|
|
212
241
|
如果标准会话出现 `miloco_*`,检查 `preset-miloco` 是否被正确装载。
|
|
213
242
|
|
|
214
|
-
> DSH `0.2.
|
|
215
|
-
> 第三方预设只显示 `description` 和「查看配置」;Miloco
|
|
243
|
+
> DSH `0.2.2-rc.5` 的「模式说明 / 如何使用」按钮只为内置预设(standard/ptc/minimal/cordis)硬编码。
|
|
244
|
+
> 第三方预设只显示 `description` 和「查看配置」;Miloco 的等价说明放在「Miloco 家庭助手 → 配置 → 查看模式说明与用法」。
|
|
216
245
|
|
|
217
246
|
---
|
|
218
247
|
|
|
@@ -220,7 +249,7 @@ dsh-miloco-bridge: push delivery failed ... # 仅在失败时
|
|
|
220
249
|
|
|
221
250
|
```bash
|
|
222
251
|
npm run pack:bundle
|
|
223
|
-
tar -tzf dist/dsh-miloco-bridge-0.1.
|
|
252
|
+
tar -tzf dist/dsh-miloco-bridge-0.1.6.tgz | head -30
|
|
224
253
|
```
|
|
225
254
|
|
|
226
255
|
预期包含:`package/lib/*`、`package/skills/*/SKILL.md`、`package/adapter/dsh_adapter.py`、
|
|
@@ -230,13 +259,16 @@ tar -tzf dist/dsh-miloco-bridge-0.1.4.tgz | head -30
|
|
|
230
259
|
|
|
231
260
|
```bash
|
|
232
261
|
DSH_HOME=/tmp/dsh-miloco-bundle-verify \
|
|
233
|
-
dsh plugin --profile web add "file:$PWD/dist/dsh-miloco-bridge-0.1.
|
|
262
|
+
dsh plugin --profile web add "file:$PWD/dist/dsh-miloco-bridge-0.1.6.tgz"
|
|
234
263
|
```
|
|
235
264
|
|
|
236
265
|
---
|
|
237
266
|
|
|
238
267
|
## 7. 已知边界
|
|
239
268
|
|
|
269
|
+
- 默认 `archive` 模式下所有推送共用同一个归档会话:前一次 turn 未结束时又来的推送会挤在同一会话里,
|
|
270
|
+
等待结果的调用可能报 `status: "timeout"`,回复也可能归到另一次推送;需要按次对齐时改用
|
|
271
|
+
「指定会话」(`session`),或把连发的推送拉开间隔(详见 [ARCHITECTURE.md](ARCHITECTURE.md) 的 7.6)。
|
|
240
272
|
- 隔离 profile 没有模型 API Key,因此没有在真实 UI 里跑完整 LLM turn;
|
|
241
273
|
推送 turn 的等待/回复逻辑由离线测试覆盖。
|
|
242
274
|
- 一键部署会运行上游安装器,耗时取决于网络与 Python 依赖;本次未在干净机器上从零跑完整安装。
|
|
Binary file
|
|
Binary file
|
|
Binary file
|