@masstensor/diagnose 0.3.0 → 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.
- package/README.md +77 -111
- package/USER_GUIDE.md +567 -0
- package/deploy/Caddyfile +15 -1
- package/dist/agent-command.d.ts +4 -0
- package/dist/agent-command.js +33 -0
- package/dist/agent.d.ts +2 -0
- package/dist/agent.js +115 -0
- package/dist/cli.js +178 -22
- package/dist/discover.js +1 -1
- package/dist/engine.d.ts +2 -0
- package/dist/engine.js +37 -4
- package/dist/history.d.ts +13 -0
- package/dist/history.js +57 -0
- package/dist/journal.d.ts +23 -1
- package/dist/journal.js +82 -5
- package/dist/maintenance.d.ts +2 -0
- package/dist/maintenance.js +46 -0
- package/dist/mcp.d.ts +1 -1
- package/dist/mcp.js +21 -18
- package/dist/operator.d.ts +2 -0
- package/dist/operator.js +17 -5
- package/dist/pairing.d.ts +40 -0
- package/dist/pairing.js +92 -0
- package/dist/peer.d.ts +4 -0
- package/dist/peer.js +10 -3
- package/dist/resources.js +47 -26
- package/dist/schema.d.ts +2 -0
- package/dist/schema.js +2 -2
- package/dist/skill.d.ts +8 -0
- package/dist/skill.js +58 -0
- package/dist/transfers.js +28 -11
- package/dist/util.d.ts +2 -0
- package/dist/util.js +16 -3
- package/examples/skills/device-troubleshooting/SKILL.md +35 -0
- package/examples/skills/device-troubleshooting/references/device-profile.md +16 -0
- package/examples/skills/owon.md +27 -0
- package/npm-shrinkwrap.json +215 -5
- package/package.json +23 -5
- package/scripts/setup-node.ps1 +54 -0
- package/scripts/setup-node.sh +52 -0
- package/src/agent-command.ts +25 -0
- package/src/agent.ts +79 -0
- package/src/cli.ts +53 -20
- package/src/discover.ts +1 -1
- package/src/engine.ts +19 -4
- package/src/history.ts +43 -0
- package/src/journal.ts +41 -5
- package/src/maintenance.ts +30 -0
- package/src/mcp.ts +18 -16
- package/src/operator.ts +15 -6
- package/src/pairing.ts +64 -0
- package/src/peer.ts +6 -4
- package/src/resources.ts +35 -13
- package/src/schema.ts +4 -4
- package/src/skill.ts +44 -0
- package/src/transfers.ts +14 -3
- package/src/util.ts +14 -3
- package/test/agent.test.ts +104 -0
- package/test/pairing.test.ts +124 -0
- package/test/review.test.ts +128 -0
- package/test/setup.test.ts +16 -0
- package/test/skill.test.ts +25 -0
package/README.md
CHANGED
|
@@ -1,161 +1,127 @@
|
|
|
1
1
|
# Diagnose
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Diagnose and fix problems remotely with your AI agent.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Diagnose is an open-source tool for agent-led remote troubleshooting and problem resolution. It gives Codex, Claude Code, Gemini CLI, or another MCP client the remote tools to investigate a user's computer or connected device, apply authorized fixes, and verify the result. A user-controlled probe and an end-to-end encrypted relay provide the connection.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
[User guide](USER_GUIDE.md) · [Source](https://github.com/zkwasm/diagnose) · [npm](https://www.npmjs.com/package/@masstensor/diagnose) · [Website](https://diagnose.fenginwind.com)
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
npm install -g @masstensor/diagnose
|
|
11
|
-
diagnose start
|
|
12
|
-
```
|
|
9
|
+
Requires **Node.js 20.10+**. MIT licensed. TypeScript source is included in the npm package. macOS probes and the Linux relay have been tested. CI covers macOS/Linux and targeted Windows regressions; Windows interactive terminals and physical USB/serial behavior still need real-environment validation.
|
|
13
10
|
|
|
14
|
-
|
|
11
|
+
## Quick start
|
|
15
12
|
|
|
16
|
-
|
|
13
|
+
On the computer being diagnosed:
|
|
17
14
|
|
|
18
15
|
```sh
|
|
19
|
-
diagnose
|
|
16
|
+
npx @masstensor/diagnose@latest start
|
|
20
17
|
```
|
|
21
18
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
**权限选择**(只在用户本机决定):
|
|
19
|
+
Keep the terminal open and privately share its complete `D1.…` pairing code with the diagnostician.
|
|
25
20
|
|
|
26
|
-
|
|
27
|
-
- 配对时输入 `a`:明确授权本次会话**自动执行并自动发送**,后续任务不再弹确认。命令有当前OS用户权限;输出会直接提供给诊断者及其AI。终端持续显示任务及发送摘要,审计继续记录。文本脱敏仍不是秘密识别保证,二进制不会自动脱敏。
|
|
28
|
-
- 会话中输入 `permissions` 查看模式;`permissions ask` 撤销自动权限、取消正在运行的任务/整批,后续恢复审批。已发送内容不能撤回。
|
|
29
|
-
- 想在会话中开启自动模式:先输入 `permissions auto` 阅读说明,再在60秒内输入 `permissions allow-auto` 明确确认。远端请求没有切换权限的字段。
|
|
30
|
-
- `cancel` 取消当前任务/整批,保留当前权限模式;`Ctrl+C` 或 `exit` 结束会话。新会话恢复默认逐次审批,不继承自动授权。
|
|
21
|
+
On the diagnostician's computer, start an already installed and authenticated agent:
|
|
31
22
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
{"operation":"system.inspect","arguments":{},"reason":"检查电脑与串口环境"}
|
|
36
|
-
{"operation":"process.run","arguments":{"executable":"/usr/bin/sw_vers","args":[],"timeoutMs":10000},"reason":"查看 macOS 版本"}
|
|
37
|
-
{"operation":"file.read","arguments":{"path":"/absolute/path/to/log","offset":0,"length":65536},"reason":"检查用户指定日志"}
|
|
38
|
-
{"operation":"serial.capture","arguments":{"path":"/dev/cu.usbserial-2110","baudRate":115200,"durationMs":20000},"reason":"采集设备启动日志;串口可能导致重启"}
|
|
23
|
+
```sh
|
|
24
|
+
npx @masstensor/diagnose@latest agent codex
|
|
25
|
+
# Or: agent claude / agent gemini
|
|
39
26
|
```
|
|
40
27
|
|
|
41
|
-
|
|
28
|
+
The agent launcher requires **0.3.1+**. It loads Diagnose MCP for this launch without adding a permanent MCP entry. Tell the agent:
|
|
42
29
|
|
|
43
|
-
|
|
30
|
+
> Use Diagnose to connect to this pairing code: D1.… . Help resolve the user's application startup failure. First investigate without changing anything. Explain the cause, proposed fix, and risks. Apply only authorized changes, then check whether the application starts successfully and report anything still unresolved.
|
|
44
31
|
|
|
45
|
-
|
|
32
|
+
The user must approve the connection locally. They choose per-task approval or automatic execution **and transmission** for this temporary session. Possessing a pairing code does not establish the diagnostician's real identity.
|
|
46
33
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
```json
|
|
50
|
-
{
|
|
51
|
-
"operation": "batch.run",
|
|
52
|
-
"reason": "一次采集系统环境和运行时信息",
|
|
53
|
-
"arguments": {
|
|
54
|
-
"steps": [
|
|
55
|
-
{"operation":"system.inspect","arguments":{}},
|
|
56
|
-
{"operation":"process.script","arguments":{"interpreter":"node","script":"const os = require('node:os');\nconsole.log(JSON.stringify({uptime: os.uptime(), freeMemory: os.freemem()}));","timeoutMs":10000}}
|
|
57
|
-
],
|
|
58
|
-
"stopOnError": true,
|
|
59
|
-
"timeoutMs": 60000
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
|
-
```
|
|
34
|
+
For repeated use:
|
|
63
35
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
{"operation":"process.script","arguments":{"interpreter":"/bin/sh","script":"uname -a\nprintf '\\n--- Disk ---\\n'\ndf -h\n","timeoutMs":30000},"reason":"一次采集系统和磁盘信息"}
|
|
36
|
+
```sh
|
|
37
|
+
npm install -g @masstensor/diagnose@latest
|
|
38
|
+
diagnose start
|
|
39
|
+
# On the diagnostician's machine:
|
|
40
|
+
diagnose agent codex
|
|
70
41
|
```
|
|
71
42
|
|
|
72
|
-
|
|
43
|
+
## Pair once, return later
|
|
73
44
|
|
|
74
|
-
|
|
45
|
+
Requires **0.5.0+ on both computers**. The user keeps `diagnose start` running. On the diagnostician's computer:
|
|
75
46
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
{"mcpServers":{"diagnose":{"command":"diagnose","args":["mcp"]}}}
|
|
47
|
+
```sh
|
|
48
|
+
diagnose pair --name alice-pc
|
|
49
|
+
# Enter the temporary code and your label/provider; user confirms remembering.
|
|
50
|
+
diagnose agent codex --device alice-pc --skill ./devices/owon.md
|
|
51
|
+
# Same options for claude or gemini; --skill is optional.
|
|
82
52
|
```
|
|
83
53
|
|
|
84
|
-
|
|
54
|
+
Restart the agent whenever needed without a new code. Pairing persists across probe restarts, but access requires the foreground probe. Task approval remains the default. The user may grant automatic execution and transmission for one hour, or explicitly until revoked. Local `pause`, `permissions ask`, and `unpair` control access. Interrupted modifications are never automatically replayed. See the [pairing guide](USER_GUIDE.md#keep-a-device-paired-for-future-diagnosis).
|
|
85
55
|
|
|
86
|
-
##
|
|
56
|
+
## Start with a device skill or Markdown task
|
|
87
57
|
|
|
88
|
-
|
|
58
|
+
Requires **0.4.0+**. Use the same option with every supported agent:
|
|
89
59
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
| diagnose_process | 创建普通进程或PTY;指定cwd/env、timeoutMs、retainOnDisconnect |
|
|
95
|
-
| diagnose_resource | list/status/read/input/resize/signal/close;从返回cursor继续读取,检查ended及exitCode |
|
|
96
|
-
| diagnose_resume | 用原资源ID和resumeToken请求恢复;不重跑命令 |
|
|
97
|
-
| diagnose_transfer | upload/download后台无损传输,status/cancel查询进度;SHA-256校验、续传、显式覆盖 |
|
|
98
|
-
| diagnose_forward | 在获准net.forward句柄上启动、查看或关闭本地端点 |
|
|
99
|
-
|
|
100
|
-
创建实时资源时,先在本机批准操作及**持续原始输入输出**,之后同一句柄内输入、读取、调整尺寸、信号或连接不逐次弹窗。自动模式仍仅由用户本机开启。创建成功只表示句柄已建立,进程是否成功须查看退出码。
|
|
101
|
-
|
|
102
|
-
终端JSON示例:
|
|
103
|
-
|
|
104
|
-
```json
|
|
105
|
-
{"operation":"process.open","arguments":{"executable":"/bin/sh","pty":true,"retainOnDisconnect":true,"timeoutMs":0},"reason":"持续交互诊断,断线后保留原进程"}
|
|
106
|
-
{"operation":"net.forward","arguments":{"direction":"local","host":"192.168.31.217","port":11500},"reason":"访问用户局域网内的网关TCP服务"}
|
|
60
|
+
```sh
|
|
61
|
+
diagnose agent codex --skill ./devices/owon.md
|
|
62
|
+
diagnose agent claude --skill ./devices/owon.md
|
|
63
|
+
diagnose agent gemini --skill ./devices/owon.md
|
|
107
64
|
```
|
|
108
65
|
|
|
109
|
-
`
|
|
110
|
-
|
|
111
|
-
转发包括local固定远端目标、remote用户侧回环监听转至诊断者目标,以及socks诊断者侧SOCKS5 TCP代理。SOCKS的allowedHosts默认["*"]表示任意目标,应按需求缩小。监听仅限回环;不支持UDP、TUN或公共监听。
|
|
112
|
-
|
|
113
|
-
`upload {"localPath":"/local/file","remotePath":"/remote/file","reason":"上传诊断文件"}`;download交换源/目标含义。MCP同样传路径,不让大段base64进入AI上下文。上传先写私有暂存文件,完整SHA校验及目标旧哈希匹配后替换;下载使用.diagnose.part和0600恢复侧文件,完成校验后替换。文件路径/权限管理另有file.stat/list/mkdir/remove/rename/chmod;rename默认拒绝覆盖。
|
|
66
|
+
A directory is also accepted: `--skill ./skills/my-device` reads its `SKILL.md`. Relative references remain based on that file's original directory. Diagnose snapshots the entry and supplies a startup task that tells the agent to read it and begin, instead of waiting for you to repeat the task. It asks for a pairing code or other missing target details when needed.
|
|
114
67
|
|
|
115
|
-
|
|
68
|
+
This is a session task, not a global native-skill installation or an additional permission grant. User approvals and the agent's own tool permissions still apply. Instructions can be sent to your AI provider. See the [guide](USER_GUIDE.md#start-with-a-device-skill-or-markdown-task) and [examples](https://github.com/zkwasm/diagnose/tree/main/examples/skills).
|
|
116
69
|
|
|
117
|
-
|
|
70
|
+
## From problem to verified result
|
|
118
71
|
|
|
119
|
-
|
|
72
|
+
1. **Define the problem:** agree on the symptom and what a successful outcome looks like.
|
|
73
|
+
2. **Investigate:** inspect the environment, gather evidence, and identify the likely cause.
|
|
74
|
+
3. **Plan the fix:** explain the proposed changes, their impact, and recovery options where available.
|
|
75
|
+
4. **Act with permission:** use approved commands, scripts, or file changes to carry out the fix.
|
|
76
|
+
5. **Verify and hand off:** repeat the original check, summarize changes, and identify any remaining issues.
|
|
120
77
|
|
|
121
|
-
|
|
78
|
+
This is an agent-guided workflow using the existing tools and permission model. Diagnose does not automatically prove a repair succeeded or roll back arbitrary changes. See the [troubleshooting workflow](USER_GUIDE.md#from-a-reported-problem-to-a-verified-result).
|
|
122
79
|
|
|
123
|
-
##
|
|
80
|
+
## Remote tools
|
|
124
81
|
|
|
125
|
-
|
|
|
126
|
-
|
|
127
|
-
|
|
|
128
|
-
| process.run
|
|
129
|
-
| process.
|
|
130
|
-
|
|
|
131
|
-
|
|
|
132
|
-
|
|
|
133
|
-
|
|
|
134
|
-
| serial
|
|
82
|
+
| Capability | Interface |
|
|
83
|
+
| --- | --- |
|
|
84
|
+
| Inspect OS, runtime, commands, privileges, and serial ports | `system.inspect` |
|
|
85
|
+
| Execute commands or complete scripts; submit up to 32 sequential steps | `process.run`, `process.script`, `batch.run` |
|
|
86
|
+
| Stream output, send stdin, resize a real PTY, and send signals | `process.open`, resource controls |
|
|
87
|
+
| Keep an explicitly retained job running across network loss | `resource.resume` with its ID and recovery credential |
|
|
88
|
+
| Transfer exact binary files with SHA-256 verification and resume | `file.transfer`, `diagnose_transfer` |
|
|
89
|
+
| Read, write, list, inspect, create, remove, rename, and change file permissions | `file.*` |
|
|
90
|
+
| Forward TCP locally or in reverse; use SOCKS5 TCP | `net.forward`, `diagnose_forward` |
|
|
91
|
+
| Capture a serial port or send explicitly authorized bytes | `serial.capture`, `serial.exchange` |
|
|
92
|
+
| Use a native remote terminal without an AI agent | `diagnose terminal` |
|
|
135
93
|
|
|
136
|
-
|
|
94
|
+
No device-specific integration is required in the probe. An approved script can use tools already available on the user's computer. Diagnose does not implement the SSH wire protocol or accept `ssh`, `scp`, or `sftp` clients. It does not provide a desktop viewer, SSH agent/X11 forwarding, UDP, TUN, or public forwarding listeners.
|
|
137
95
|
|
|
138
|
-
|
|
96
|
+
## Trust and data boundaries
|
|
139
97
|
|
|
140
|
-
|
|
98
|
+
- Both endpoints initiate outbound connections to the relay, normally over HTTPS/WSS on port 443. No inbound port or SSH server is required on the user's computer.
|
|
99
|
+
- The Noise protocol encrypts commands and results between the endpoints. The relay cannot read their contents, but can observe connection metadata and interrupt service.
|
|
100
|
+
- Approved processes have the current OS user's permissions. **Diagnose is not a sandbox.** It does not automatically elevate privileges or install a background service.
|
|
101
|
+
- Finite text results receive best-effort credential redaction. Live terminals, exact file transfers, and TCP traffic are raw and **not redacted**.
|
|
102
|
+
- Results are visible to the diagnostician and the AI provider they use. End-to-end encryption does not hide data from those recipients.
|
|
103
|
+
- Local audit logs record decisions, targets, hashes, byte counts, and outcomes. Encrypted history keeps exact task requests, finite collected results, approvals, and send events: use `diagnose history`, `diagnose show ID`, and `diagnose cleanup --days 0`. History and resource journals each have a 256 MiB / 2,000-record budget and seven-day inactive retention. They do not reconstruct every side effect of an arbitrary program. Changes are not automatically rolled back.
|
|
104
|
+
- `permissions ask`, `cancel`, and `Ctrl+C` are local controls. Data already transmitted cannot be recalled.
|
|
141
105
|
|
|
142
|
-
|
|
106
|
+
Read the [user guide](USER_GUIDE.md#security-and-local-data) before operating a session. The protocol has not received an independent security audit.
|
|
143
107
|
|
|
144
|
-
|
|
108
|
+
## Development
|
|
145
109
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
有限任务的采集文本先做常见凭据脱敏并移除终端控制字符;实时终端、文件传输与TCP通道保持原始字节,不脱敏。人工模式在本机合并预览并确认发送;自动模式依据用户本地已授予的会话权限直接发送。正则不能识别所有秘密,二进制不自动脱敏。采集与发送分别审计。进程输出在本地有上限地缓冲,得到本次或会话发送授权后才传输。Ctrl+C撤销待审请求、取消任务并结束会话。
|
|
149
|
-
|
|
150
|
-
## 开发、测试、部署
|
|
110
|
+
Development scripts use Node.js 22.18+ to run TypeScript directly. Installed CLI runtime support starts at Node.js 20.10; users do not need to upgrade an existing compatible runtime.
|
|
151
111
|
|
|
152
112
|
```sh
|
|
153
113
|
npm ci
|
|
154
|
-
npm test
|
|
155
114
|
npm run check
|
|
115
|
+
npm test
|
|
156
116
|
npm pack
|
|
157
117
|
```
|
|
158
118
|
|
|
159
|
-
|
|
119
|
+
Tests exercise the actual encrypted protocol, approval boundaries, native terminals, transfers, forwarding, recovery, and the stdio MCP interface. The Noise tests include a public Cacophony interoperability vector. Hardware acceptance scripts and device logs are not distributed.
|
|
120
|
+
|
|
121
|
+
The `site/` directory contains the static landing page, a small TypeScript interaction module, and a build script that renders the guide. Run `npm run build:site` and `npm run check:site`; serve `.site-dist/` to preview. No analytics, third-party scripts, or cookies are required. The website features a 60-second English animation covering the current agent launcher, permissions, encrypted relay, investigation, authorized repair, and result verification. Its repair story is illustrative, not a live diagnosis. Reproduce it with `npm run video:render`; see [video documentation](https://github.com/zkwasm/diagnose/blob/main/video/README.md). The earlier Chinese video is retained unchanged.
|
|
122
|
+
|
|
123
|
+
## Relay deployment
|
|
124
|
+
|
|
125
|
+
`deploy/ecosystem.config.cjs`, `deploy/start-relay.sh`, and `deploy/Caddyfile` provide deployment templates. The relay binds to `127.0.0.1:8792`; Caddy terminates TLS. Its launcher disables core dumps. The service has no database or runtime decryption keys, does not persist diagnostic content, and does not enable Caddy access logging.
|
|
160
126
|
|
|
161
|
-
|
|
127
|
+
The production domain serves the landing page and guide while `/v1/connect`, `/healthz`, and `/downloads/*` continue to reach the relay. Deploy only the package's allowlisted files and public website assets. Never synchronize a diagnostic workspace, credentials, or hardware logs to the server.
|