dsh-aiterm 0.0.0-stage → 0.5.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 (52) hide show
  1. package/CONTRACTS.md +794 -0
  2. package/LICENSE +21 -0
  3. package/README.md +401 -2
  4. package/client/AuditPopover.jsx +140 -0
  5. package/client/ConnectForm.jsx +528 -0
  6. package/client/HistoryPanel.jsx +562 -0
  7. package/client/ProfilesPanel.jsx +551 -0
  8. package/client/QuickScripts.jsx +302 -0
  9. package/client/ScriptsPanel.jsx +1230 -0
  10. package/client/Terminal.jsx +424 -0
  11. package/client/api.js +1273 -0
  12. package/client/index.js +91 -0
  13. package/client/locale.js +872 -0
  14. package/client/macroLang.js +267 -0
  15. package/client/panel.jsx +873 -0
  16. package/client/reset.js +111 -0
  17. package/client/scriptDialect.js +55 -0
  18. package/client/scriptLang.js +337 -0
  19. package/client/scriptOrder.js +139 -0
  20. package/client/store.js +809 -0
  21. package/client/styles.js +1419 -0
  22. package/client/terminal-theme.js +136 -0
  23. package/client/ui.jsx +653 -0
  24. package/cordis.patch.yml +17 -0
  25. package/icon.svg +16 -0
  26. package/lib/client.js +400 -0
  27. package/lib/host/autolog.js +407 -0
  28. package/lib/host/batch.js +455 -0
  29. package/lib/host/config.js +98 -0
  30. package/lib/host/exporter.js +386 -0
  31. package/lib/host/history-store.js +909 -0
  32. package/lib/host/outputlog.js +550 -0
  33. package/lib/host/permission.js +241 -0
  34. package/lib/host/profiles.js +657 -0
  35. package/lib/host/prompt.js +38 -0
  36. package/lib/host/promptdetect.js +73 -0
  37. package/lib/host/registry.js +1990 -0
  38. package/lib/host/routes.js +482 -0
  39. package/lib/host/screen.js +892 -0
  40. package/lib/host/screendiff.js +60 -0
  41. package/lib/host/script-lang.js +1464 -0
  42. package/lib/host/scripts.js +453 -0
  43. package/lib/host/tools.js +1441 -0
  44. package/lib/host/transports/ssh.js +980 -0
  45. package/lib/host/transports/telnet.js +711 -0
  46. package/lib/host/util.js +297 -0
  47. package/lib/index.js +132 -0
  48. package/locale/en.json +6 -0
  49. package/locale/zh.json +6 -0
  50. package/package.json +75 -4
  51. package/scripts/build-client.mjs +116 -0
  52. package/scripts/smoke-client.mjs +2986 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 yejianping
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,402 @@
1
- # Temporary Holding Version
1
+ # dsh-aiterm · SSH / Telnet 终端(人与 AI 协同)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ DeepSeek Harness(DSH)插件:把 SSH 和 Telnet 会话放进 Harness 右侧栏的终端面板,**人**和 **AI** 共用同一个真实终端,并按会话控制 AI 能做什么。
4
+
5
+ Give your agent hands on real servers. **aiterm** puts SSH and Telnet sessions in DSH's right
6
+ sidebar — one real terminal **shared by you and the AI**, not an AI-only pipe: per-session AI
7
+ permissions (read-only / write-only / read-write), a single control token, token-cheap delta
8
+ reads, searchable history, batch scripts and a full audit trail.
9
+
10
+ > **改名说明(0.5.0 起)**:包名由 `@dsh/dsh-ssh-telnet` → `@dsh/aiterm` → 公开发布名 **`dsh-aiterm`**,整套标识一起改到位:模型工具名 `aiterm_*`、HTTP 路由 `/aiterm`、数据目录 `~/.dsh/aiterm`、凭据作用域 `aiterm/`、前端存储键 `dsh.aiterm.*`、面板标签类型 `aiterm`。0.4.0 只改了包名,0.5.0 是**破坏性改名**,从 0.3.x/0.4.0 升级要迁移数据与提示词,见下方「从 ssh-telnet 升级」。
11
+
12
+ - **多会话**:同时打开多台主机,标签页切换;终端输出实时滚动,支持重连回放。
13
+ - **省 token 的读取**:默认 **增量读**(只回上次之后的新输出),另有「只看变化行」的屏幕读、带时间戳的历史搜索、以及"等到有输出/提示符/退出"的等待读,不再反复重传整屏。
14
+ - **历史可查**:输出按会话落盘(默认 24 小时),会话关闭、甚至重启后仍可按时间范围或关键字检索。
15
+ - **批量与脚本**:一次调用跑多步(发送 → 等待 → 只读新输出),支持多会话扇出;可保存脚本并在面板里一键运行。
16
+ - **SSH + Telnet**:SSH 走 `ssh2`(密码 / 私钥 / agent),Telnet 为原生实现(完整 IAC 协商、TERMINAL-TYPE、NAWS 窗口尺寸)。
17
+ - **AI 权限按会话设置**:
18
+ - `只读(ro)`:AI 能看屏幕/输出,**不能**输入;
19
+ - `只写(wo)`:AI 能输入,**不能**看输出;
20
+ - `读写(rw)`:两者都可。
21
+ - **AI 操作时屏蔽人工写**:AI 一开始输入就持有「控制权」,人工键盘输入被拒绝并显示提示;AI 空闲超时自动释放,或人工点「接管」立即夺回控制。
22
+ - **双向互斥**:人工「接管」后,AI 的写入被拒绝,直到人工「交还 AI」。
23
+ - **审计**:每次读、写、拒绝、控制权变更都记录来源(human / ai),面板内可查,AI 也能用工具查。
24
+ - **凭据隔离**:保存的密码/私钥存在 Host 侧(优先 DSH 加密凭据库),不会进入模型上下文、工具结果或日志。
25
+
26
+ > 这是权限与协作层面的护栏,不是远程主机的安全沙箱。对敏感环境请给 AI 设 `只读`,或让 AI 仅通过保存的 profile 连接。
27
+
28
+ ## 安装
29
+
30
+ 公开发布后(npm):
31
+
32
+ ```bash
33
+ dsh plugin --profile web add dsh-aiterm
34
+ # 重启 DSH Web
35
+ ```
36
+
37
+ 本地开发:先打包再装**真实包**,不要用 `link:` / 软链——宿主在 profile 目录下按 importer
38
+ 路径做包解析,软链会让内核包解析到 profile 之外而启动失败(`ERR_MODULE_NOT_FOUND`)。
39
+
40
+ ```bash
41
+ npm install && npm run build # 需要 esbuild / xterm 才能重建 lib/client.js
42
+ npm pack # → dsh-aiterm-0.5.0.tgz
43
+ # 然后 plugin_manager(action:"install_bundle", target:"<tgz 绝对路径>")
44
+ ```
45
+
46
+ 装好后浏览器 `Ctrl+F5` 硬刷新一次:客户端半边由宿主重打包,SPA 内切页不够。
47
+
48
+ ### 从 ssh-telnet 升级(破坏性)
49
+
50
+ 0.5.0 把工具名、路由、数据目录、凭据作用域和存储键全部从 `ssh-telnet` 改成 `aiterm`,**不保留旧别名**。
51
+ 从 0.3.x / 0.4.0 升级时按序执行:
52
+
53
+ ```bash
54
+ # 1) 停掉 DSH Web(改名期间旧进程还在往旧目录写)
55
+ # 2) 迁移数据目录(历史、脚本、导出的日志、已知主机、回退密钥都在里面)
56
+ mv ~/.dsh/ssh-telnet ~/.dsh/aiterm
57
+
58
+ # 3) 凭据库记录改作用域(先备份;这个文件写坏会让 DSH 下次起不来)
59
+ cp ~/.dsh/.credentials.yaml ~/.dsh/.credentials.yaml.bak
60
+ sed -i 's#^ ssh-telnet/# aiterm/#' ~/.dsh/.credentials.yaml
61
+
62
+ # 4) 若用的是文件回退(没有 credentials 服务),同步 secrets.json 的键前缀
63
+ sed -i 's#"ssh-telnet/#"aiterm/#' ~/.dsh/aiterm/secrets.json
64
+ ```
65
+
66
+ 然后卸载旧包、安装 `dsh-aiterm@0.5.0` 并重启 DSH Web,浏览器 `Ctrl+F5`。不要新旧并存——两者注册同名工具会冲突。
67
+
68
+ 升级后需要自己改的地方:
69
+
70
+ - **提示词 / 脚本 / 外部调用**里写死的 `ssh_telnet_*` 改成 `aiterm_*`(模型工具名变了)。
71
+ - **反向代理 / 书签**里的 `/dsh-ssh-telnet` 路由改成 `/aiterm`。
72
+ - **前端本地偏好**(脚本面板的排序、方言选择、快捷条分组可见性)用的是新键 `dsh.aiterm.*`,旧值不迁移,重新设置一次即可。
73
+
74
+ ## 使用
75
+
76
+ 1. 右侧栏打开 aiterm 面板 → **新建连接**,或先保存一个主机档案(profile)。
77
+ 2. 选择连接方式:SSH(密码 / 私钥 / ssh-agent)或 Telnet。
78
+ 3. 连接成功后即可直接输入;顶部工具条可随时调整 AI 权限。
79
+ 4. 让 AI 操作:在对话里让它「读一下 st-1 的屏幕」「在 st-2 上执行 `df -h`」。AI 开始操作时,面板顶部出现 **AI 正在操作 · 人工输入已屏蔽** 提示;点 **接管** 立刻拿回键盘,AI 的后续写入会被拒绝。
80
+
81
+ ## AI 权限模型
82
+
83
+ 每个会话独立维护两件事:
84
+
85
+ | 维度 | 取值 | 含义 |
86
+ | --- | --- | --- |
87
+ | `aiAccess` | `ro` / `wo` / `rw` | AI 的读/写能力(只有人能改) |
88
+ | `lockOwner` | `null` / `ai` / `human` | 当前控制权归属 |
89
+
90
+ 规则(Host 侧统一执行,AI 工具与浏览器按键走同一入口):
91
+
92
+ - AI 读:`ro`、`rw` 允许;`wo` 拒绝 → `AI_READ_DENIED`。
93
+ - AI 写:`wo`、`rw` 允许;`ro` 拒绝;`lockOwner === 'human'` 也拒绝 → `AI_WRITE_DENIED`。
94
+ - 人工读:永远允许。
95
+ - 人工写:`lockOwner === 'ai'` 且 `blockHumanWhileAi: true` 时拒绝 → `HUMAN_WRITE_BLOCKED`。
96
+ - AI 一次成功写入即取得控制权;`aiLockIdleMs`(默认 30s)无 AI 写入后自动释放;人工点「接管」立即改为 `human`,AI 调用 `aiterm_release_control` 只能交还自己持有的控制权。
97
+
98
+ 只有人能做:修改 AI 权限、接管、交还控制、保存/删除档案。这些操作不提供模型工具。
99
+
100
+ ## 模型工具
101
+
102
+ | 工具 | 作用 |
103
+ | --- | --- |
104
+ | `aiterm_list` | 列出会话、状态、AI 权限、控制权 |
105
+ | `aiterm_connect` | 通过保存的 profile(推荐)或 ad-hoc agent/none 建立连接 |
106
+ | `aiterm_status` | 查看某会话的权限与控制权 |
107
+ | `aiterm_read` | **默认增量读**(`mode:"delta"`,只回新输出);也可 `screen` / `history` / `tail` |
108
+ | `aiterm_screen` | 可见屏幕文本;`changedOnly:true` 只回变化行(带行号) |
109
+ | `aiterm_screenshot` | `aiterm_screen` 的兼容别名(已精简载荷,不再重复整屏) |
110
+ | `aiterm_wait` | 等到「输出停顿 / 出现匹配 / 会话退出」,只回这期间的新输出 |
111
+ | `aiterm_history` | 按时间范围/正则检索历史(含已关闭会话与重启后的历史) |
112
+ | `aiterm_send` | 发送文本/按键(`\u0003` = Ctrl-C),可选等待并在审计中记录一次 `read:tail` 回读 |
113
+ | `aiterm_batch` | 一次调用执行多步(send → waitFor → 只读新输出),可多会话扇出 |
114
+ | `aiterm_script_list` | 列出保存的脚本(按分组) |
115
+ | `aiterm_script_run` | 运行脚本(支持延迟/变量/if/循环/断言,`{{参数}}` 替换) |
116
+ | `aiterm_script_save` | 保存/覆盖脚本(删除仍仅限人在面板操作) |
117
+ | `aiterm_resize` | 调整远端子终端尺寸 |
118
+ | `aiterm_release_control` | 主动交还控制权给人工 |
119
+ | `aiterm_audit` | 读权限审计记录 |
120
+ | `aiterm_disconnect` | 断开但保留会话(可重连) |
121
+ | `aiterm_reconnect` | 重连该会话(同一 id,历史保留) |
122
+ | `aiterm_close` | 关闭会话(终止并从列表移除) |
123
+
124
+ AI 不能提供密码或私钥:需要密码/私钥的连接必须使用保存的 profile,由 Host 侧解析。
125
+
126
+ ## 配置
127
+
128
+ 在 `~/.dsh/profiles/<profile>/cordis.patch.yml` 覆盖本插件行(合并语义:给整段 `config`):
129
+
130
+ ```yaml
131
+ - id: aiterm
132
+ name: 'dsh-aiterm'
133
+ config:
134
+ aiAccessDefault: ro # 新会话默认 AI 权限:ro | wo | rw
135
+ aiAutoLock: true # AI 写入时是否自动取得控制权
136
+ aiLockIdleMs: 30000 # AI 控制权空闲自动释放时间
137
+ blockHumanWhileAi: true # 核心行为:AI 操作时屏蔽人工写
138
+ humanCanPreempt: true # 是否允许人工随时接管
139
+ maxSessions: 16
140
+ scrollback: 4000
141
+ replayBufferBytes: 262144 # 重连回放保留的原始输出字节数
142
+ aiReadMaxBytes: 65536
143
+ connectTimeoutMs: 20000
144
+ keepaliveMs: 15000
145
+ routePath: /aiterm
146
+ knownHostsPolicy: accept-new # accept-new | strict | insecure
147
+ terminalType: xterm-256color
148
+ # v2 读取 / 历史 / 脚本
149
+ promptPattern: '(?:^|[\s\])])[#$%>❯»]\s*
150
+
151
+ ## 读取方式与 token 成本
152
+
153
+ | 场景 | 建议用法 | 典型开销 |
154
+ | --- | --- | --- |
155
+ | 追一条长时间命令的输出 | `aiterm_read`(默认 delta)+ 上次返回的 `cursor` | 只有新输出,几十到几百字符 |
156
+ | 判断命令是否跑完 | `aiterm_wait {until:"idle"}` 或 `{until:"pattern"}` | 一次调用 + 新输出 |
157
+ | 看 vim/top 之类全屏界面 | `aiterm_screen {changedOnly:true}` | 只回变化的行 |
158
+ | 排查"刚才发生了什么" | `aiterm_history {since:"10m", search:"ERROR"}` | 命中行 + 时间戳 |
159
+ | 一组固定操作 | `aiterm_batch` 或保存脚本 | 一次调用,逐步只回新输出 |
160
+
161
+ ## 首次打开
162
+
163
+ 没有会话时,面板**默认打开配置管理**(连接库),可在其中选择已有配置连接,或点「新建连接」。
164
+ 不会再一进来就是一张空表单。
165
+
166
+ ## 界面导航
167
+
168
+ 所有非终端页面(新建/编辑连接、配置管理、历史、脚本)共用同一个页头:**← 返回 · 标题 · × 关闭**。
169
+
170
+ - **返回回到来处**:面板内部维护一个视图栈。配置管理 → 编辑某条配置 → 返回,回到配置管理;
171
+ 终端 → 历史 → 返回,回到终端。根视图是终端(或没有会话时的配置管理),不会被弹空。
172
+ - **Esc = 一次退一层**:整个面板只有一个 Esc 处理者;行内编辑/行内确认条会先吃掉 Esc(取消自己),
173
+ 不会一次退两层。
174
+ - **终端视图有常显入口**:标签行右侧的「配置管理」按钮带文字,不再只是一个图标。
175
+ - **按钮尺寸**:文本按钮高 32px、图标按钮 30px(会话标签行的关闭按钮 26px)、控件字号 12–13px,
176
+ 命中区域按触摸场景放宽。
177
+
178
+ ### 增删改的确认方式
179
+
180
+ - **删除配置**、**关闭会话**、**删除脚本**都改成**行内确认条**(`确认删除 xxx?[确认][取消]`),
181
+ 不再用「3 秒内点两次」的定时器:既不会误触,也不会因为犹豫几秒就得重来。
182
+ - 删除配置后会清掉对应的密码/私钥/口令;关闭会话会断开连接并从列表移除(不可恢复)。
183
+ - 保存配置后自动回到列表,并**高亮刚保存的那一行**。
184
+ - 配置行操作常显:`连接`(主)/ `编辑` / `重命名` / `移动文件夹` / `删除`,不靠 hover 才出现。
185
+
186
+ ## 会话中断与重连
187
+
188
+ - **中断**(`sessions.disconnect` / 工具 `aiterm_disconnect`):断开传输但**保留会话**——同一 `id`、标题、
189
+ AI 权限、输出历史、审计都还在,列表里标记为 `disconnected`。
190
+ - **重连**(`sessions.reconnect` / 工具 `aiterm_reconnect`):复用同一 `id` 重新连接,`generation` +1,
191
+ AI 权限与历史延续;远端是新的 shell,所以**屏幕会重置**(客户端清屏并提示),但历史检索仍覆盖断开前的内容。
192
+ - **掉线不再丢会话**:远端主动断开或网络中断时,会话进入 `disconnected`(记录 `closeReason`),点一下即可恢复;
193
+ 只有显式「关闭」才会移除。
194
+ - 重连的认证材料:有配置走配置(会重新读取,密码轮换也能生效);ad-hoc 会话的凭据只留在 Host 进程内存,
195
+ 从不落盘/回传;两者都没有时返回 `RECONNECT_NO_CREDENTIALS`,请用配置重连。
196
+ - 保留上限:同时最多保留 `maxDetachedSessions`(默认 20)个断开会话,超出按最早断开修剪。
197
+
198
+ ## 配置管理
199
+
200
+ 面板里的 **配置管理** 支持按文件夹分组维护连接配置:
201
+
202
+ - 新建 / 编辑 / 重命名 / 删除配置;删除会同时清掉该配置的密码、私钥与口令。
203
+ - 移动到分组、取消分组;新建分组;连接表单保存时可直接选分组。
204
+ - 重命名只改显示名,**id 不变**(id 是凭据键的一部分,改了会丢密码)。
205
+ - 编辑时密码/私钥留空表示"保持原值",只有显式清空才会删除。
206
+ - 所有配置写操作仅限人工(AI 无法读写你的凭据)。
207
+
208
+ ## 终端与 AI 会话的归属
209
+
210
+ **每个 DSH(AI)会话单独维护自己的 SSH/Telnet 终端**:在对话 A 里打开的终端,切到对话 B 就看不到,
211
+ 也不会被 B 的 AI 读到或操作。
212
+
213
+ - 客户端把当前 DSH 会话 id 作为 `owner` 带在每次会话相关调用上,SSE 流也按 `?owner=` 过滤
214
+ - 宿主侧按 `owner` 隔离:`sessions.list`、读写、断线重连、权限、审计、历史查询、日志导出**全部按 owner 过滤**;
215
+ 用别的对话的 id 去访问一律 404,且文案与「id 不存在」完全一致(不泄露存在性)
216
+ - `maxSessions` / `maxDetachedSessions` **按每个 AI 会话分别计数**,一个对话开满不会影响另一个
217
+ - AI 通过工具创建的终端,归属**调用它的那个 AI 会话**(工具 schema 里没有 owner 参数,模型无需关心)
218
+ - 身份取自 DSH 的 `agent.id`(兼容 `agent.session.id`);**子代理**开的终端归到它所属的那个对话,
219
+ **fork** 出来的新对话则各管各的
220
+ - 万一宿主读不出调用方身份,工具会直接报 `OWNER_UNKNOWN` 而不是造一个谁都看不见的终端
221
+ - 哪些是宿主级、不按会话隔离:连接配置(`profiles`)、保存的脚本(`scripts`)、自动写日志开关、
222
+ `导出全部`(显式跨会话操作)
223
+
224
+ > 切换 DSH 会话时面板会清空并重新拉取,这是设计行为——不会把上一个对话的终端带过来。
225
+ > 已关闭终端的归属在宿主进程内记忆;**DSH 重启后**磁盘上的旧历史按「无归属」处理(只有不带 owner 的调用可见)。
226
+
227
+ ## 会话与协议
228
+
229
+ - 会话标签上是**带颜色的协议徽标**:`SSH` 用强调色、`TELNET` 用告警色;徽标同样出现在侧栏 tab 标题里,
230
+ 同一条 rail 上同时挂 SSH 和 Telnet 会话时一眼可分。
231
+ - 每个会话独立:各自的标题/主机/端口、断线重连、AI 权限、审计、输出历史互不影响。
232
+
233
+ ## 日志导出与自动写文件
234
+
235
+ **导出**(历史面板底部):
236
+
237
+ | 按钮 | 作用 |
238
+ |---|---|
239
+ | 导出当前 | 把当前选中会话的输出写成一个文本文件 |
240
+ | 导出全部 | 每个会话各写一个文件(含已关闭的) |
241
+
242
+ - 输出目录:`~/.dsh/aiterm/exports/`,文件名 `<会话id>-<标题>-<时间戳>.log`
243
+ - 内容:头注释(协议 / `user@host:port` / 标题 / 开始时间)+ 每行 `<ISO 时间戳> <输出行>`
244
+ - 文件写在**宿主机**上(不是浏览器下载),用 DSH 的文件面板取走即可;导出结果面板会列出路径、大小、行数
245
+ - 导出失败会显示原因;若提示「重启 DSH 后可用」,说明宿主代码还是旧代际
246
+
247
+ **自动写日志文件**(默认关闭):
248
+
249
+ - 历史面板里的「自动把每个会话写进日志文件」开关,打开后每个会话实时追加写入
250
+ `~/.dsh/aiterm/logs/`(可在 Host 侧改目录)
251
+ - 开关状态存在 `~/.dsh/aiterm/settings.json`,重启后保持;写失败只会告警一次并自动停写,
252
+ 不影响会话本身
253
+ - AI 也可以用工具 `aiterm_export` / `aiterm_autolog` 触发同样的能力
254
+
255
+ ## 脚本
256
+
257
+ 脚本是**纯数据**(不执行任意代码),支持多脚本、分组与参数:
258
+
259
+ | 能力 | 写法 |
260
+ |---|---|
261
+ | 发送命令 / 等待 / 回读 | `{ send, enter, waitFor:{pattern,idleMs,timeoutMs}, read:'delta'\|'screen'\|'none' }` |
262
+ | 延迟 | `{ delay: 500 }`(毫秒) |
263
+ | 变量 | `{ set: "name", value: "{{param}}-x" }`,所有字符串支持 `{{name}}` |
264
+ | 条件分支 | `{ if: {match:"ok"\|contains:"x"\|variable:"v",equals:"y"}, then:[...], else:[...] }` |
265
+ | 循环 | `{ loop: { count: 3 }\|{ while: Cond }\|{ until: Cond, maxIterations: 20 }, steps:[...] }` |
266
+ | 断言 | `{ expect: Cond, onFail: 'stop'\|'continue' }` |
267
+ | 日志 | `{ log: "..." }` |
268
+
269
+ - 条件看的是"自上次条件判断以来的输出",所以 `发送 → 立刻 if/expect` 能看到刚产生的输出。
270
+ - **步骤之间是严格顺序执行的,但 `send` 默认不等待**:写完就进入下一步,不会自动等远端输出。
271
+ 想"等命令跑完再发下一条",二选一:
272
+ - 在该步骤里写 `waitFor`:`{ send:"ls", enter:true, waitFor:{ idleMs:250, timeoutMs:5000 } }`(等输出停顿)
273
+ 或 `waitFor:{ pattern:"\\$\\s*$", timeoutMs:5000 }`(等提示符回来);
274
+ - 或在两条命令之间插 `{ delay: 500 }` 固定间隔。
275
+ `delay` 会真的睡满;`expect` / `if` / `loop.while` / `loop.until` 会读取输出(有读窗口)。
276
+ 多目标时每个目标各自顺序执行;`parallel: true` 才是目标之间并发。
277
+ - 面板进度里的 `#0`、`#1` 是**步骤序号**(嵌套步骤显示成 `3.2` 这样的路径,并标注 send/delay/if/loop 类型)。
278
+ 如果进度里出现"未知",那是事件来自 AI 工具(`aiterm_batch`)而非面板运行——工具事件只带序号,
279
+ 不带步骤类型,面板就回退显示 `#n · 未知`。
280
+ - 上限:500 步、嵌套 5 层、单循环 1000 次(默认 100)、50 个变量、单变量 8 KiB、整脚本 10 分钟。
281
+ - 每次 `send` 仍走权限闸口:AI 只读会失败,人工接管会中止。
282
+ - 其他工具:`aiterm_script_list` / `_run` / `_save`(删除仅限人在面板操作)。
283
+
284
+ ## 快捷脚本条
285
+
286
+ 终端底部有一条**快捷脚本**条(点「⚡ 快捷脚本」展开):脚本按文件夹分组,点一下就用在当前会话上,
287
+ 参数取脚本里声明的默认值。日常「查个负载/看个磁盘」不用再开面板。脚本在「脚本」面板里维护,
288
+ 保存后展开快捷条即可看到。
289
+
290
+ ## 脚本编写:逐行命令(推荐)
291
+
292
+ 新建脚本默认是**逐行命令**:一行一条,直接发送;`@` 开头是控制行。
293
+
294
+ ```text
295
+ # 注释
296
+ uname -a
297
+ @wait 300
298
+ df -h
299
+ @expect continue Filesystem
300
+ @python
301
+ print('hello from the remote host')
302
+ @end
303
+ ```
304
+
305
+ | 写法 | 含义 |
306
+ |---|---|
307
+ | 普通行 | 发送该命令(带回车) |
308
+ | `@raw 文本` | 发送但不带回车 |
309
+ | `@wait 500` / `@wait 2s` | 暂停 |
310
+ | `@set name = value` | 定义变量(`{{name}}` 可在任意字符串里用) |
311
+ | `@log 文本` | 写进运行日志 |
312
+ | `@expect 文本` / `@expect continue 文本` | 断言输出匹配,失败时停止 / 继续 |
313
+ | `@python … @end` | 把代码发到**远端** python3 执行 |
314
+
315
+ - 命令**按行原样发送**,不会自动等待:想等命令跑完再发下一条,就在中间写 `@wait`(或在该行之后加
316
+ `@expect` 断言);`@wait 500` / `@wait 2s` 都可以。
317
+ - 需要 `if` / `loop` 等结构时改用 **高级脚本**(新建时选择类型);两种类型各自独立,不互相转换。
318
+ - 编译在浏览器侧完成,存进 Host 的仍是同一份步骤数组,安全与权限规则完全不变。
319
+ - **为什么不用真正的 Python 写脚本**:那等于在 Harness 进程里执行任意代码(安全退步),
320
+ 且本镜像没有 `python3`。要用 Python,就写 `@python … @end`,让**远端服务器**的 python3 跑。
321
+
322
+ ## 脚本分组与两种编写方式
323
+
324
+ **两种写法各自独立,互不转换**(按脚本创建时选择):
325
+
326
+ | 类型 | 适合 | 编辑器 |
327
+ |---|---|---|
328
+ | 逐行命令 | 一串要按顺序发的命令 | 一行一条,`@` 开头是控制行 |
329
+ | 高级脚本 | 需要 `if` / `loop` 结构 | JSON 步骤数组 |
330
+
331
+ - 新建时选类型(**新建 · 逐行命令** / **新建 · 高级脚本**);列表里每行带方言小标签。
332
+ - 编辑器顶部显示当前脚本的方言,不再提供互相切换的开关。
333
+ - **分组管理**:编辑器里有「名称 / 分组」(分组可内联新建);列表的分组表头可以**重命名分组**、
334
+ **删除分组**(删除时组内脚本移到未分组)。
335
+ - **快捷脚本条的分组可见性**:快捷条头部的「分组显示」勾选清单决定哪些分组出现在快捷条上,
336
+ 选择会记住。
337
+
338
+ ### 脚本面板(主从管理)
339
+
340
+ - 顶部 `分组:` 下拉 + [添加分组][重命名分组][删除分组]
341
+ - 左栏底部「+ 新建」——点了才弹出**类型菜单**(`逐行命令` / `JSON(高级)`),选哪个就按哪种类型创建;
342
+ 已打开脚本的类型显示在右栏的只读标签里(不做互转)
343
+ - 左栏:当前分组的脚本列表;下方 [+新建][−删除][▲上移][▼下移][复制]
344
+ - 右栏:名称 / 分组 / 类型(只读)/ 模板 / 内容 + [保存][取消];内容框会**撑满剩余高度**,不再固定 120px
345
+ - 运行区在下方:运行目标(当前 / 选定 / 全部)+ 参数 + 运行
346
+
347
+ > **模板下拉随类型变化**:逐行命令只列宏模板(发送命令 / @wait / @set / @log / @expect / Python),
348
+ > 高级脚本只列 JSON 骨架(send / delay / set / log / expect / if / loop)。
349
+ > ▲▼ 的排序是**本机显示顺序**(存在浏览器 localStorage),不影响脚本执行;换浏览器会回到默认顺序。
350
+
351
+ ### 运行结果
352
+
353
+ 运行只占一行摘要(`运行完成 · N 步 · 共 X 个会话,Y 个成功`)。点 **[查看结果]** 弹出独立窗口看完整
354
+ 步骤明细:运行中会自动打开,Esc 或 × 只关这个窗口(不会把脚本面板一起关掉)。
355
+
356
+ ## 数据与安全
357
+
358
+ > **凭据文档是共享的。** 本插件只通过 **records**(`aiterm/<id>`)写自己的条目,并在写入后回读校验;
359
+ > 同时把每个密钥镜像到 `~/.dsh/aiterm/secrets.json`(0600)。若凭据库无记录,读取会回落到镜像,
360
+ > 因此"保存了却显示没有密码"不会静默发生。其他插件若把 API key 填进 `apiKeyEnv` 之类的
361
+ > "环境变量名"字段,会写坏整个文档(详见 VERIFICATION §12),那不是本插件能控制的。
362
+
363
+ - 主机档案(非机密字段):`~/.dsh/aiterm/profiles.json`(0600)。
364
+ - SSH 主机指纹:`~/.dsh/aiterm/known_hosts`,不写入用户自己的 `~/.ssh/known_hosts`。
365
+ - 密码 / 私钥 / 私钥口令:走 Host `credentials` 服务的 **records** 通道,键形如
366
+ `aiterm/<profile>`(私钥 `-key`、口令 `-pass`)。DSH 的 `records:` 只接受
367
+ `<scope>/<id>` 且每段匹配 `/^[a-z][a-z0-9-]*$/`,本插件只通过
368
+ `credentialKeyFor()` 生成键并在写入前校验;不可用时回退到
369
+ `~/.dsh/aiterm/secrets.json`(0600)并打印告警。
370
+ - ⚠️ **不要改回 `credentials.set('aiterm/…')`**:`refs:` 段只接受 POSIX 标识符
371
+ (`/^[A-Za-z_][A-Za-z0-9_]*$/`),写入当时不报错,但会让凭据文档在**下次启动**时
372
+ 无法解析,导致 DSH 起不来(本项目曾因此事故)。`test/secrets.test.mjs` 会拦截这种回退。
373
+ - RPC 与 SSE 路由经 `connection.admit()` 认证(可信来源 + 签名 Cookie),非授权请求返回 401/403。
374
+ - 审计只记录输入预览(控制字符剔除、≤200 字符),不记录机密内容。
375
+
376
+ ## 已知限制
377
+
378
+ - AI 截屏基于 headless 终端模拟,全屏 TUI 的鼠标/图片类内容无法表达。
379
+ - Telnet 协议本身明文传输(建议只在可信网络使用)。
380
+ - 浏览器端把 RPC 前缀硬编码为默认的 `/aiterm`;若改了 `routePath`,需要同步修改 `client/api.js` 并 `npm run build`。
381
+ - 历史检索对**已关闭/重启前**的会话不做权限判定(其权限状态已随会话消失);活跃会话的读取(含历史检索)仍严格受 AI 权限约束。
382
+ - 提示符识别是正则启发式,非标准 shell 集成;可通过 `promptPattern` 按需调整。
383
+ - 面板视觉验证需要浏览器环境;本项目环境无浏览器控制能力,界面仅做了构建与注册级验证。
384
+
385
+ ## 开发
386
+
387
+ ```bash
388
+ npm install # 运行时依赖 ssh2 / @xterm/headless / @xterm/addon-serialize,
389
+ # 以及构建用 devDeps:esbuild、@xterm/xterm、@xterm/addon-fit
390
+ npm run build # 从 client/**.jsx 重新生成 lib/client.js(模块 id 取自 package.json 的 name)
391
+ npm run lint # node --check 全部 Host 端源码
392
+ npm test # 客户端冒烟:槽位注册、locale 键、RPC 方法覆盖
393
+ ```
394
+
395
+ 改了 `client/` 一定要重新 `build` 并提交 `lib/client.js`:`lib/` 是仓库的一部分,
396
+ 用户装包时不跑构建。
397
+
398
+ 接口契约见 [CONTRACTS.md](./CONTRACTS.md)。
399
+
400
+ ## License
401
+
402
+ MIT © yejianping
@@ -0,0 +1,140 @@
1
+ /**
2
+ * Bounded per-session audit popover.
3
+ *
4
+ * The popover reads `audit.list` through RPC when it opens, then keeps growing
5
+ * from the live `audit` frames the session SSE stream delivers (pushed into the
6
+ * shared store by the terminal view).
7
+ */
8
+
9
+ import { useEffect, useRef, useState } from 'react'
10
+ import { errorMessage, fmt } from './locale.js'
11
+ import { rpc } from './api.js'
12
+ import { setAudit, useAppState } from './store.js'
13
+ import { C, S } from './styles.js'
14
+
15
+ const ACTION_KEYS = {
16
+ read: 'auditRead',
17
+ write: 'auditWrite',
18
+ deny: 'auditDeny',
19
+ lock: 'auditLock',
20
+ }
21
+
22
+ function timeLabel(at) {
23
+ try {
24
+ return new Date(at).toLocaleTimeString(undefined, { hour12: false })
25
+ } catch {
26
+ return ''
27
+ }
28
+ }
29
+
30
+ function oneLine(text) {
31
+ return String(text || '').replace(/\s+/g, ' ').trim()
32
+ }
33
+
34
+ /**
35
+ * Render the audit popover.
36
+ *
37
+ * @param props.t - locale translate function.
38
+ * @param props.sessionId - selected session id (null hides the popover).
39
+ * @param props.open - whether the popover is open.
40
+ * @param props.onClose - close handler.
41
+ * @param props.rootRef - element containing both the trigger and the popover.
42
+ * @returns the popover, or null when closed.
43
+ */
44
+ export function AuditPopover({ t, sessionId, open, onClose, rootRef }) {
45
+ const state = useAppState()
46
+ const popoverRef = useRef(null)
47
+ const [loading, setLoading] = useState(false)
48
+ const [error, setError] = useState(null)
49
+
50
+ useEffect(() => {
51
+ if (!open || !sessionId) return undefined
52
+ let cancelled = false
53
+ setLoading(true)
54
+ setError(null)
55
+ rpc('audit.list', { id: sessionId, limit: 100 })
56
+ .then((result) => {
57
+ if (cancelled) return
58
+ const entries = result && Array.isArray(result.entries) ? result.entries : []
59
+ setAudit(sessionId, entries)
60
+ })
61
+ .catch((failure) => {
62
+ if (!cancelled) setError(errorMessage(failure))
63
+ })
64
+ .finally(() => {
65
+ if (!cancelled) setLoading(false)
66
+ })
67
+ return () => {
68
+ cancelled = true
69
+ }
70
+ }, [open, sessionId])
71
+
72
+ useEffect(() => {
73
+ if (!open) return undefined
74
+ const onPointerDown = (event) => {
75
+ const root = rootRef && rootRef.current
76
+ if (root && event.target instanceof Node && root.contains(event.target)) return
77
+ onClose()
78
+ }
79
+ const onKeyDown = (event) => {
80
+ if (event.key !== 'Escape') return
81
+ // The popover is the topmost layer: close it and stop here, otherwise the
82
+ // panel's view-stack listener would also pop a level on the same press.
83
+ event.stopPropagation()
84
+ if (typeof event.preventDefault === 'function') event.preventDefault()
85
+ onClose()
86
+ }
87
+ document.addEventListener('mousedown', onPointerDown, true)
88
+ document.addEventListener('keydown', onKeyDown, true)
89
+ return () => {
90
+ document.removeEventListener('mousedown', onPointerDown, true)
91
+ document.removeEventListener('keydown', onKeyDown, true)
92
+ }
93
+ }, [open, onClose, rootRef])
94
+
95
+ if (!open || !sessionId) return null
96
+
97
+ const entries = (state.audit[sessionId] || []).slice().reverse()
98
+
99
+ return (
100
+ <div ref={popoverRef} style={S.popover} role="dialog" aria-label={t('audit')}>
101
+ <div style={S.popoverHeader}>
102
+ <span style={{ flex: 1, minWidth: 0 }}>{t('audit')}</span>
103
+ </div>
104
+ <div style={S.auditList}>
105
+ {loading && entries.length === 0 ? <div style={S.auditEmpty}>{t('auditLoading')}</div> : null}
106
+ {!loading && entries.length === 0 ? <div style={S.auditEmpty}>{t('auditEmpty')}</div> : null}
107
+ {entries.map((entry, index) => {
108
+ const actionKey = ACTION_KEYS[entry.action] || 'auditRead'
109
+ const source = entry.source === 'ai' ? t('sourceAi') : t('sourceHuman')
110
+ const detail = oneLine(entry.detail)
111
+ return (
112
+ <div key={`${entry.at}-${index}`} style={S.auditRow} title={detail || undefined}>
113
+ <span style={S.auditTime}>{timeLabel(entry.at)}</span>
114
+ <span
115
+ style={{
116
+ ...S.auditBadge,
117
+ color: entry.source === 'ai' ? C.warnLabel : C.labelSecondary,
118
+ }}
119
+ >
120
+ {source}
121
+ </span>
122
+ <span
123
+ style={{
124
+ ...S.auditBadge,
125
+ color: entry.action === 'deny' ? C.danger : C.labelSecondary,
126
+ }}
127
+ >
128
+ {t(actionKey)}
129
+ </span>
130
+ <span style={S.auditDetail}>{detail || '—'}</span>
131
+ </div>
132
+ )
133
+ })}
134
+ </div>
135
+ {error ? (
136
+ <div style={{ ...S.formError, margin: 6 }}>{fmt(t, 'auditFailed', { message: error })}</div>
137
+ ) : null}
138
+ </div>
139
+ )
140
+ }