dsh-dnshe-domain 1.0.0 → 1.0.1

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 (2) hide show
  1. package/README.md +89 -26
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,82 +1,145 @@
1
1
  # dsh-dnshe-domain
2
2
 
3
- DNSHE 免费域名 API(V2.0)的 DSH 插件。七件工具:账号与名额、子域名列表 / 详情、解析记录读取、记录增删改、子域注册 / 续期 / 删除、到期巡检、WHOIS。
3
+ DeepSeek Harness(DSH)插件:把 DNSHE 的免费域名 API V2.0 接进来——免费二级域名的注册 / 续期 / 删除,A / AAAA / CNAME / TXT / MX / SRV / CAA 解析的增删改查,名额用量、到期巡检、WHOIS,全部由 7 个工具覆盖。
4
4
 
5
5
  ```
6
6
  https://api005.dnshe.com/index.php?m=domain_hub&endpoint=<模块>&action=<动作>
7
7
  认证:X-API-Key + X-API-Secret
8
8
  ```
9
9
 
10
- ## 安装
10
+ ## 快速开始
11
11
 
12
- 从 npm 装:
12
+ 1)装插件
13
13
 
14
14
  ```bash
15
15
  dsh plugin --profile desktop add dsh-dnshe-domain
16
16
  ```
17
17
 
18
- 从本地目录装(改代码时这样最方便,装的是软链):
18
+ 改代码时也可以装本地目录(软链,改完即时生效):
19
19
 
20
20
  ```bash
21
21
  dsh plugin --profile desktop add D:\dsh\plugins\dsh-dnshe-domain
22
22
  ```
23
23
 
24
- 或者在 Plugins 面板里 Add plugin 选这个目录。装完开一个新会话,工具才会出现(本地 bundle 需要新的模块世代)。
24
+ 2)放凭据
25
25
 
26
- ## 凭据
26
+ 把 DNSHE 后台「免费域名管理 → API管理 → 导出」得到的 JSON 放到:
27
27
 
28
- `~/.dnshe/accounts.json`,就是 DNSHE 后台导出的原文件(`format: "dnshe-accounts"`)。本仓库里没有凭据;不要把它提交进 git。
28
+ ```
29
+ ~/.dnshe/accounts.json # Windows: C:\Users\<你>\.dnshe\accounts.json
30
+ ```
31
+
32
+ `format` 字段必须是 `dnshe-accounts`。它长这样(`apiSecret` 不要提交进 git):
33
+
34
+ ```json
35
+ {
36
+ "format": "dnshe-accounts",
37
+ "version": 1,
38
+ "exportedAt": 1794917083998,
39
+ "accounts": [
40
+ {
41
+ "name": "shizuku",
42
+ "apiKey": "cfsd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
43
+ "apiSecret": "(64 位 hex)",
44
+ "defaultRootDomain": "",
45
+ "memo": ""
46
+ }
47
+ ]
48
+ }
49
+ ```
50
+
51
+ 3)开一个新会话,直接说话
29
52
 
30
- ## 每个工具的参数
53
+ - 「我 DNSHE 上还有多少免费名额」→ `dnshe_accounts{ probe: true }`
54
+ - 「`shizuku.l.cd` 现在解析到哪」→ `dnshe_records{ domain: "shizuku.l.cd" }`
55
+ - 「给 `new.example.l.cd` 加一条 A 记录指向 1.2.3.4」→ `dnshe_record_write{ action: "create" }`
56
+ - 「把 `www` 那条改成新 IP」→ `dnshe_record_write{ action: "update" }`(先 `dnshe_records` 拿 id)
31
57
 
32
- ### dnshe_accounts
58
+ 装完要开新会话,工具才会出现(本地 bundle 需要新的模块世代)。
59
+
60
+ ## 七个工具
61
+
62
+ ### dnshe_accounts — 账号与名额
33
63
  `{ probe?: boolean, account?: string }`
64
+ 默认只读凭据文件;`probe: true` 会逐个账号问一次实时配额与域名数。
34
65
 
35
- ### dnshe_domains
66
+ ### dnshe_domains — 子域名列表 / 单域名详情
36
67
  `{ account?, detail?, search?, rootdomain?, status?, page?, perPage? }`
68
+ `detail: "<完整域名>"` 时返回该域名的详情 + 全部解析记录。到期时间会算好剩余天数。
37
69
 
38
- ### dnshe_records
70
+ ### dnshe_records — 解析记录
39
71
  `{ domain, account?, type? }`
72
+ 返回每条记录的 `id` —— 改和删都用它最稳。
40
73
 
41
- ### dnshe_record_write
74
+ ### dnshe_record_write — 记录增 / 改 / 删
42
75
  `{ action: create|update|delete, account?, domain?, recordId?, name?, type?, content?, priority?, ttl?, newName?, newType?, confirm? }`
43
76
 
44
77
  - create:`domain` + `type` + `content`(`name` 可选,默认 `@`)
45
78
  - update:`recordId`,或 `domain` + `name` + `type` 定位;然后给 `content` / `newName` / `newType` / `priority`
46
- - delete:定位同上 + `confirm: true`
79
+ - delete:定位同上 + `confirm: true`(不传只回一句「要删的是什么」,不动手)
47
80
 
48
- ### dnshe_domain_write
81
+ ### dnshe_domain_write — 子域注册 / 续期 / 删除
49
82
  `{ action: register|renew|delete, account?, subdomain?, rootdomain?, domain?, confirm? }`
50
83
 
51
84
  - register:`subdomain`(前缀)+ `rootdomain`,会先查 `quota.available`
52
85
  - renew / delete:`domain`(完整域名或 subdomain_id);delete 要 `confirm: true`
53
86
 
54
- ### dnshe_expiring
55
- `{ account?, days? }`
87
+ ### dnshe_expiring — 到期巡检
88
+ `{ account?, days? }` 默认 30 天,已过期的也列出来。
56
89
 
57
- ### dnshe_whois
90
+ ### dnshe_whois — WHOIS
58
91
  `{ domain, account? }`
59
92
 
93
+ ## 多个账号怎么办
94
+
95
+ 一个账号看不到别的账号的域名。插件默认用凭据文件里的第一个账号,但**域名解析会自动跨账号兜底**:找不到就挨个账号翻,找到后在输出里说明「这个域名挂在账号 X 下,已自动切过去」。也可以直接 `account: "shizuku"` 指定。
96
+
97
+ ## 配置(可选)
98
+
99
+ 不导出 Config schema,配置直接写在 profile 的 `cordis.patch.yml` 里就生效:
100
+
101
+ ```yaml
102
+ - id: dsh-dnshe-domain
103
+ config:
104
+ accountsFile: C:\Users\mynlp\.dnshe\accounts.json
105
+ defaultAccount: shizuku
106
+ timeoutMs: 30000
107
+ cacheTtlMs: 60000
108
+ prompt: true
109
+ ```
110
+
111
+ `cacheTtlMs` 是域名列表与配额的缓存(默认 60s,写操作后自动失效);`prompt` 控制是否注入常驻使用规则。
112
+
60
113
  ## 实测踩到的坑(代码里已经兜住)
61
114
 
62
- 1. `name` 只接受相对名或 `@` —— 传完整域名 400 `invalid_record_name`。插件用 `relName()` 自动折叠。
63
- 2. TTL 平台固定 600,写 60 / 120 无效。
64
- 3. `status` 值是 `Registered`,不是 `active`。
115
+ 1. `name` 只接受相对名或 `@` —— 传完整域名会 400 `invalid_record_name`。插件用 `relName()` 自动折叠。
116
+ 2. TTL 被平台固定成 600,写 60 / 120 无效。
117
+ 3. 子域名 `status` 的真实值是 `Registered`,不是文档里的 `active`(WHOIS 那边又报 `active`)。
65
118
  4. `subdomains/list` 用 page 分页;`dns_records/list` 用 cursor 分页(`next_cursor`),没有 total。
66
- 5. `dns_records/list` 忽略 `search` / `fields`,本地筛。
67
- 6. 没有根域名枚举接口。
68
- 7. 正常写操作后配额缓存与域名缓存会一起失效,避免读到旧值。
119
+ 5. `dns_records/list` 忽略 `search` / `fields`,永远全量返回,筛选在本地做。
120
+ 6. 没有根域名枚举接口(`endpoint=rootdomains|domains|roots` 全 404)。
121
+ 7. 写操作后配额缓存与域名缓存会一起失效,避免读到旧值。
69
122
 
70
123
  ## 限速与缓存
71
124
 
72
- - 单进程内串行,最小间隔 1000ms(保守按 60 次/分;文档正文写 30 次/分,错误体写 60 次/分)。
125
+ - 单进程内串行,最小间隔 1000ms(保守按 60 次/分;文档正文写 30 次/分、错误体写 60 次/分)。
73
126
  - 域名全量列表与配额各缓存 `cacheTtlMs`(默认 60s),写操作后清空。
74
127
 
128
+ ## 安全
129
+
130
+ - `apiSecret` 从不出现在任何工具输出里;`dnshe_accounts` 只显示脱敏的 apiKey。
131
+ - 删除类动作不带 `confirm: true` 一律只回复将要删除什么,不执行。
132
+ - 改完 DNS 会提示用 `dnshe_records` 回读确认;公网生效受 600 秒 TTL 影响,不承诺秒生效。
133
+
75
134
  ## 自检
76
135
 
77
136
  ```bash
78
137
  node _selftest.mjs
79
138
  ```
80
139
 
81
- 会在假 ctx 上加载插件,依次跑:账号列表 → 实时配额 → 域名列表 → 域名详情 → 记录列表 → **TXT 记录增 / 查 / 删往返**(删之前先确认一次 `confirm:false` 的行为)→ 到期巡检 → WHOIS。
82
- 自检会真的写一条 `_dsh-plugin-selftest` TXT 再删掉,介意的话把那段注释掉。
140
+ 在假 ctx 上加载插件,依次跑:账号列表 → 实时配额 → 域名列表 → 域名详情 → 记录列表 → **TXT 记录增 / 查 / 删往返**(删之前先确认一次 `confirm:false` 的行为)→ 到期巡检 → WHOIS。
141
+ 自检会真的写一条 `_dsh-plugin-selftest` TXT 再删掉,介意就把那段注释掉。
142
+
143
+ ## License
144
+
145
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-dnshe-domain",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "DNSHE 免费域名插件(DSH):把免费二级域名的注册/续期/解析管理接进 DeepSeek Harness —— A/AAAA/CNAME/TXT/MX/SRV/CAA 增删改查、配额、到期巡检、WHOIS。",
5
5
  "type": "module",
6
6
  "main": "index.js",