dsh-apis-plugin 0.2.2 → 0.3.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 +33 -75
- package/api-tools.js +81 -49
- package/client.js +21 -19
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -1,87 +1,58 @@
|
|
|
1
1
|
# dsh-apis-plugin
|
|
2
2
|
|
|
3
|
-
通用接口管理插件(
|
|
3
|
+
通用接口管理插件(DSH 插件):把任意一套 HTTP 接口注册成 agent 可用的**文档查询 + 请求调用**双工具。
|
|
4
4
|
|
|
5
|
-
核心约定:**`api.cfg`
|
|
5
|
+
核心约定:**`api.cfg` 是接口的唯一权威范围**——范围外的请求一律拒绝。
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## 版本兼容
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
dsh plugin --profile web add dsh-apis-plugin
|
|
11
|
-
```
|
|
9
|
+
需要 **DSH >=0.1.7-rc.2**(详情页徽章据此显示)。DSH 0.1.5 / 0.1.6 请用旧版 `dsh-apis-plugin@0.2.3`。
|
|
12
10
|
|
|
13
|
-
|
|
11
|
+
## 安装
|
|
14
12
|
|
|
15
13
|
```sh
|
|
16
|
-
dsh plugin --profile web add dsh-apis-plugin@0.
|
|
14
|
+
dsh plugin --profile web add dsh-apis-plugin@0.3.0
|
|
17
15
|
```
|
|
18
16
|
|
|
19
17
|
## 配置
|
|
20
18
|
|
|
21
|
-
「API
|
|
19
|
+
「API配置」指向一个**集合父目录**,插件递归扫描其下所有 `*.cfg`,**每个 cfg 是一个集合**(集合名取 cfg 的 `host` 字段):
|
|
22
20
|
|
|
23
21
|
```
|
|
24
22
|
config/
|
|
25
|
-
├── site-a.example.com/
|
|
26
|
-
│ ├── api.cfg #
|
|
23
|
+
├── site-a.example.com/
|
|
24
|
+
│ ├── api.cfg # host=site-a.example.com
|
|
27
25
|
│ └── api_doc.md # 该集合的接口文档
|
|
28
26
|
└── site-b.example.com/
|
|
29
|
-
├── api.cfg
|
|
27
|
+
├── api.cfg
|
|
30
28
|
└── api_doc.md
|
|
31
29
|
```
|
|
32
30
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
### 1. xxx.cfg(每个集合一份,必需)
|
|
36
|
-
|
|
37
|
-
key=value 行格式,`#` 注释,UTF-8 编码:
|
|
31
|
+
### api.cfg(每个集合一份,必需)
|
|
38
32
|
|
|
39
33
|
```ini
|
|
40
|
-
#
|
|
34
|
+
# 集合标识(如域名),用于展示与「集合名/路径」消歧
|
|
41
35
|
host=site-a.example.com
|
|
42
36
|
|
|
43
|
-
#
|
|
44
|
-
title
|
|
37
|
+
# 集合用途说明(可选),展示在接口目录与手风琴中
|
|
38
|
+
title=xxx
|
|
45
39
|
|
|
46
|
-
#
|
|
40
|
+
# 该集合的接口服务前缀
|
|
47
41
|
baseUrl=http://your-host/api
|
|
48
42
|
|
|
49
|
-
#
|
|
43
|
+
# 接口白名单:逐行一个,支持 {param} 模板段
|
|
50
44
|
apis=
|
|
51
45
|
/users/page
|
|
52
46
|
/users/{id}
|
|
53
47
|
```
|
|
54
48
|
|
|
55
|
-
|
|
56
|
-
- `title`:集合用途说明(可选),AI 查目录与 UI 手风琴均会展示
|
|
57
|
-
- `baseUrl`:请求时拼接在该集合的接口路径前(改文件即生效,无需重启)
|
|
58
|
-
- `apis`:该集合的接口白名单,支持 `{param}` 模板段(如 `/users/{id}`),agent 请求时填实际值
|
|
59
|
-
- **增删接口只改这个文件**,改完点插件配置页的「扫描」(或重启)生效
|
|
60
|
-
|
|
61
|
-
### 2. api_doc.md(接口文档,建议提供)
|
|
62
|
-
|
|
63
|
-
与 `api.cfg` 放在一起。用 `---` 分节,每节描述一个接口,节内用反引号标注接口路径:
|
|
64
|
-
|
|
65
|
-
```markdown
|
|
66
|
-
## 通用说明
|
|
67
|
-
|
|
68
|
-
所有接口返回 JSON,需携带 token。
|
|
49
|
+
改 cfg 后点插件详情页的「扫描」(或重启)生效。
|
|
69
50
|
|
|
70
|
-
|
|
51
|
+
### api_doc.md(接口文档,建议提供)
|
|
71
52
|
|
|
72
|
-
|
|
73
|
-
- 参数:keyword(可选)、page、pageSize
|
|
53
|
+
与 `api.cfg` 放在一起,用 `---` 分节,每节描述一个接口,节内用反引号标注路径(如 `` `/users/page` ``)。agent 调用 `{prefix}_api_doc` 时按路径命中对应小节返回。
|
|
74
54
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
- 路径:`/users/{id}`(GET)
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
agent 调用 `{prefix}_api_doc` 时按路径命中对应小节返回。
|
|
81
|
-
|
|
82
|
-
💡 建议:在「通用说明」里注明 *“本文档与线上服务一一对应,以此为准”*,并写清字段语义(如 `status=0 编辑中,1 待审核`)——工具描述已声明文档为权威依据,写清楚后 agent 会直接按文档调用,不会再去翻后端源码核实。
|
|
83
|
-
|
|
84
|
-
### 3. 部署侧 cordis.patch.yml(可选覆盖)
|
|
55
|
+
### 部署侧 cordis.patch.yml(可选)
|
|
85
56
|
|
|
86
57
|
```yaml
|
|
87
58
|
- insert:
|
|
@@ -90,54 +61,41 @@ agent 调用 `{prefix}_api_doc` 时按路径命中对应小节返回。
|
|
|
90
61
|
config:
|
|
91
62
|
domain: "用户中心" # 领域名:拼进工具描述 prompt
|
|
92
63
|
toolPrefix: api # 工具名前缀:生成 api_api_doc / api_api_request
|
|
93
|
-
apiDir: "" #
|
|
94
|
-
endpoints: [] #
|
|
64
|
+
apiDir: "" # 集合父目录默认值(留空则在 UI 里填)
|
|
65
|
+
endpoints: [] # 额外固定接口(不随扫描回写)
|
|
95
66
|
baseUrl: "" # 服务前缀兜底(api.cfg 优先)
|
|
96
67
|
```
|
|
97
68
|
|
|
98
69
|
## 使用
|
|
99
70
|
|
|
100
|
-
### Web UI(设置 → 插件 →
|
|
71
|
+
### Web UI(设置 → 插件 → 插件详情页)
|
|
101
72
|
|
|
102
73
|
| 操作 | 说明 |
|
|
103
74
|
|---|---|
|
|
104
|
-
| API
|
|
105
|
-
| 扫描 |
|
|
106
|
-
| 集合手风琴 |
|
|
75
|
+
| API配置 | 填集合父目录,失焦或回车自动保存 |
|
|
76
|
+
| 扫描 | 重扫目录;**目录留空点击则清空列表** |
|
|
77
|
+
| 集合手风琴 | 展示集合名、用途、接口数、baseUrl 与接口列表(只读,增删请在 cfg 中操作) |
|
|
107
78
|
|
|
108
79
|
### Agent 工具
|
|
109
80
|
|
|
110
|
-
插件向 agent 注册两个工具(`{prefix}` 默认 `api`):
|
|
111
|
-
|
|
112
81
|
| 工具 | 用途 |
|
|
113
82
|
|---|---|
|
|
114
|
-
| `api_api_doc` | 查接口文档:传 `path`
|
|
115
|
-
| `api_api_request` |
|
|
116
|
-
|
|
117
|
-
多集合规则:
|
|
118
|
-
|
|
119
|
-
- path 默认写接口路径(如 `/users/page`),在全部集合中查找;**跨集合同名接口需用「集合名/路径」消歧**(如 `site-a.example.com/users/page`)
|
|
120
|
-
- 每个集合使用自己 api.cfg 里的 baseUrl 发请求,互不混淆
|
|
121
|
-
- 接口文档也按集合独立查找(各集合自己的 api_doc.md)
|
|
122
|
-
|
|
123
|
-
超出 api.cfg 范围的请求(无论查文档还是发请求)会被直接拒绝,并提示可用接口列表。
|
|
124
|
-
|
|
125
|
-
安全机制:
|
|
83
|
+
| `api_api_doc` | 查接口文档:传 `path` 返回该接口的参数与响应说明;不传返回全部接口目录 |
|
|
84
|
+
| `api_api_request` | 调用接口:`path` 必须在白名单内,GET 用 `query`,POST 用 `body` |
|
|
126
85
|
|
|
127
|
-
-
|
|
128
|
-
-
|
|
86
|
+
- path 默认写接口路径(如 `/users/page`);**跨集合同名接口用「集合名/路径」消歧**(如 `site-a.example.com/users/page`)
|
|
87
|
+
- 安全机制:`DELETE` 需二次确认(首次只返回确认提示,确认后带 `confirm=true` 再调);写操作返回结果附带警告块
|
|
129
88
|
|
|
130
89
|
## 排查
|
|
131
90
|
|
|
132
91
|
dsh 控制台日志:
|
|
133
92
|
|
|
134
93
|
```
|
|
135
|
-
[dsh-apis-plugin] loaded; endpoints=N, collections=a.com,b.com
|
|
94
|
+
[dsh-apis-plugin] loaded; apiDir=/path/to/config, endpoints=N, collections=a.com,b.com
|
|
136
95
|
```
|
|
137
96
|
|
|
138
|
-
- `endpoints=0`:检查
|
|
139
|
-
-
|
|
140
|
-
- 提示未配置 baseUrl:在对应集合的 cfg 文件写入 `baseUrl=http://...`
|
|
97
|
+
- `endpoints=0`:检查 apiDir 是否正确、其下是否有含 apis 的 `*.cfg`
|
|
98
|
+
- 列表与 cfg 不一致:点「扫描」或重启
|
|
141
99
|
|
|
142
100
|
## License
|
|
143
101
|
|
package/api-tools.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
// 可复用的「接口工具插件」工厂:把任意一套 HTTP 接口注册成 agent 的 {prefix}_api_doc / {prefix}_api_request 双工具
|
|
2
2
|
// 领域差异(settings 命名空间、工具名前缀、领域名、文档目录、baseUrl、默认接口列表)由调用方注入,
|
|
3
3
|
// 其中 domain / toolPrefix / apiDir 也可在部署侧 cordis.patch.yml 的 config 里覆盖
|
|
4
|
+
// DSH 0.1.7+:插件 Config 即设置表单,apiDir / scanToken / collections 声明为 volatile 字段;
|
|
5
|
+
// 服务端扫描结果经 ctx.settings.update 写回,客户端卡片经 configForms 表单读写
|
|
4
6
|
import { readFileSync, writeFileSync, readdirSync } from 'node:fs'
|
|
5
7
|
import { join, dirname, basename } from 'node:path'
|
|
6
8
|
import Schema from '@deepseek-ai/schemastery'
|
|
@@ -26,10 +28,9 @@ function loadCfgFile(file) {
|
|
|
26
28
|
return cfg
|
|
27
29
|
}
|
|
28
30
|
|
|
29
|
-
//
|
|
31
|
+
// 扫描目录下的「接口集合」:递归遍历目录下所有 *.cfg(含根目录直放与任意深度子文件夹),
|
|
30
32
|
// 集合名取 cfg 的 host 字段(缺失时依次回退 baseUrl 的主机名、文件所在文件夹名)
|
|
31
33
|
function scanCollections(dir) {
|
|
32
|
-
if (!dir) return []
|
|
33
34
|
const out = []
|
|
34
35
|
const hostFromUrl = (url) => {
|
|
35
36
|
try {
|
|
@@ -42,16 +43,20 @@ function scanCollections(dir) {
|
|
|
42
43
|
const cfg = loadCfgFile(file)
|
|
43
44
|
if (cfg.apis.length) out.push({ name: cfg.host || hostFromUrl(cfg.baseUrl) || basename(dirname(file)), title: cfg.title || '', file, dir: dirname(file), baseUrl: cfg.baseUrl || '', apis: cfg.apis })
|
|
44
45
|
}
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
46
|
+
// 递归下钻,限深 5 层防符号链接成环
|
|
47
|
+
const walk = (d, depth) => {
|
|
48
|
+
if (depth > 5) return
|
|
49
|
+
let entries
|
|
50
|
+
try {
|
|
51
|
+
entries = readdirSync(d, { withFileTypes: true })
|
|
52
|
+
} catch { /* 目录不可读时跳过 */ }
|
|
53
|
+
for (const entry of entries ?? []) {
|
|
54
|
+
const p = join(d, entry.name)
|
|
55
|
+
if (entry.isDirectory()) walk(p, depth + 1)
|
|
56
|
+
else if (entry.isFile() && entry.name.endsWith('.cfg')) push(p)
|
|
53
57
|
}
|
|
54
|
-
}
|
|
58
|
+
}
|
|
59
|
+
if (dir) walk(dir, 0)
|
|
55
60
|
return out
|
|
56
61
|
}
|
|
57
62
|
|
|
@@ -100,6 +105,11 @@ export function syncClientNs(dir, ns) {
|
|
|
100
105
|
if (updated !== code) writeFileSync(file, updated)
|
|
101
106
|
}
|
|
102
107
|
|
|
108
|
+
/** 取 volatile 配置引用的当前快照;非引用原样返回 */
|
|
109
|
+
function val(v) {
|
|
110
|
+
return v !== null && typeof v === 'object' && typeof v.get === 'function' ? v.get() : v
|
|
111
|
+
}
|
|
112
|
+
|
|
103
113
|
/**
|
|
104
114
|
* 构造一个可被 cordis 直接加载的插件模块:{ Config, inject, apply }
|
|
105
115
|
* @param {object} options
|
|
@@ -113,60 +123,82 @@ export function syncClientNs(dir, ns) {
|
|
|
113
123
|
export function defineApiPlugin(options) {
|
|
114
124
|
const { ns, toolPrefix = 'api', domain = '', apiDir = '', defaultBaseUrl = '', defaultEndpoints = [] } = options
|
|
115
125
|
|
|
126
|
+
// DSH 0.1.7 写回通道:扫描结果要写回 settings(进 profile patch)供客户端卡片展示,
|
|
127
|
+
// 但 HMR 事务期间(loader/volatile-update 事件、live 重载触发的重应用都在事务内)禁止再开
|
|
128
|
+
// 写事务("HMR transactions cannot be nested"),且事务的 AsyncLocalStorage 会沿定时器等异步链
|
|
129
|
+
// 传播、无法用 defer 逃逸。启动时的首次 apply 不在事务内,故写回定时器只在首次 apply 时创建,
|
|
130
|
+
// 其回调永远不带事务上下文;apply / 事件回调只置 pending 标记与待写内容,由定时器落盘。
|
|
131
|
+
let flushState = null // { ctx, config, serialized }
|
|
132
|
+
let flushPending = false
|
|
133
|
+
let flushStarted = false
|
|
134
|
+
|
|
116
135
|
const Config = Schema.object({
|
|
117
136
|
domain: Schema.string().default(domain), // 领域名:拼进工具描述 prompt
|
|
118
137
|
toolPrefix: Schema.string().default(toolPrefix), // 工具名前缀:生成 {prefix}_api_doc / {prefix}_api_request
|
|
119
|
-
apiDir: Schema.string().default(apiDir), // cfg 与 api_doc.md 所在目录(留空则只用 endpoints
|
|
120
|
-
endpoints: Schema.array(Schema.string()).default([]),
|
|
138
|
+
apiDir: Schema.string().default(apiDir).volatile(), // cfg 与 api_doc.md 所在目录(留空则只用 endpoints);客户端卡片可写
|
|
139
|
+
endpoints: Schema.array(Schema.string()).default([]), // 部署侧固定接口(yml config 注入,不随扫描回写)
|
|
121
140
|
baseUrl: Schema.string().default(defaultBaseUrl), // 接口服务前缀(路径本身已含服务前缀)
|
|
122
|
-
scanToken: Schema.string().default(''), //
|
|
123
|
-
collections: Schema.string().default(''), // 内部字段:扫描到的集合 JSON [{name, baseUrl, apis}],客户端只读展示
|
|
141
|
+
scanToken: Schema.string().default('').volatile(), // 内部字段:客户端「扫描」按钮改写它触发配置变更重应用
|
|
142
|
+
collections: Schema.string().default('').volatile(), // 内部字段:扫描到的集合 JSON [{name, baseUrl, apis}],客户端只读展示
|
|
124
143
|
})
|
|
125
144
|
|
|
126
|
-
const inject = ['
|
|
145
|
+
const inject = ['tools', 'settings']
|
|
127
146
|
|
|
128
147
|
function apply(ctx, config) {
|
|
129
148
|
const prefix = config.toolPrefix || toolPrefix
|
|
130
149
|
const domainName = config.domain || domain
|
|
131
|
-
|
|
132
|
-
//
|
|
150
|
+
// DSH 0.1.7:volatile 字段(apiDir/scanToken/collections)在 config 里是稳定 Volatile 引用,
|
|
151
|
+
// 值更新不重跑 apply,而是原地写入引用并发出 loader/volatile-update 事件;
|
|
152
|
+
// .get() 取当前快照,事件回调里重扫即可让「扫描」与目录修改实时生效
|
|
153
|
+
// 部署侧固定接口(yml config.endpoints + 工厂默认);cfg 扫描结果只落在 collections,二者运行时取并集
|
|
133
154
|
const staticEndpoints = [...new Set([...defaultEndpoints, ...(config.endpoints ?? [])])]
|
|
134
155
|
// 集合持久化为 JSON(客户端只读展示;文档分节不落盘)
|
|
135
156
|
const plain = (cs) => JSON.stringify(cs.map(({ name, title, baseUrl, apis }) => ({ name, title, baseUrl, apis })))
|
|
136
157
|
const mergedEndpoints = (cs) => [...new Set([...cs.flatMap((c) => c.apis), ...staticEndpoints])]
|
|
137
158
|
|
|
138
|
-
|
|
139
|
-
//
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
159
|
+
// 按当前 apiDir 重扫 cfg;结果与配置不一致时经 settings.update 写回 profile patch(写回会触发
|
|
160
|
+
// 一次 volatile 更新,下一轮扫描结果与配置一致即收敛,不会循环)。
|
|
161
|
+
// 写回不在当前调用栈直接执行:loader/volatile-update 事件与 live 重载的重应用都在 HMR 事务内,
|
|
162
|
+
// 事务内再开写事务会被拒绝,故只置 pending 标记,由首次 apply 创建的定时器(事务外)落盘
|
|
163
|
+
function rescan() {
|
|
164
|
+
const dir = val(config.apiDir) || apiDir
|
|
165
|
+
const cs = loadCollections(dir)
|
|
166
|
+
const serialized = plain(cs)
|
|
167
|
+
if (serialized !== val(config.collections)) {
|
|
168
|
+
flushState = { ctx, config, serialized }
|
|
169
|
+
flushPending = true
|
|
170
|
+
}
|
|
171
|
+
return cs
|
|
172
|
+
}
|
|
146
173
|
|
|
147
|
-
//
|
|
148
|
-
|
|
149
|
-
|
|
174
|
+
// 写回定时器只在首次 apply 创建(boot 的 apply 不在 HMR 事务内,其回调永无事务上下文);
|
|
175
|
+
// flushing 锁保证写回串行——上一笔 update 完成前不放行下一笔,避免乱序覆盖
|
|
176
|
+
if (!flushStarted) {
|
|
177
|
+
flushStarted = true
|
|
178
|
+
let flushing = false
|
|
179
|
+
setInterval(async () => {
|
|
180
|
+
if (!flushPending || flushing) return
|
|
181
|
+
flushPending = false
|
|
182
|
+
flushing = true
|
|
183
|
+
const { ctx, config, serialized } = flushState
|
|
150
184
|
try {
|
|
151
|
-
|
|
152
|
-
if (dir !== docDir || next.scanToken !== lastScanToken) {
|
|
153
|
-
docDir = dir
|
|
154
|
-
collections = loadCollections(dir)
|
|
155
|
-
}
|
|
156
|
-
if (next.scanToken !== lastScanToken) {
|
|
157
|
-
lastScanToken = next.scanToken
|
|
158
|
-
const patch = {}
|
|
159
|
-
const merged = mergedEndpoints(collections)
|
|
160
|
-
if (merged.join('\n') !== (Array.isArray(next.endpoints) ? next.endpoints : []).join('\n')) patch.endpoints = merged
|
|
161
|
-
if (plain(collections) !== next.collections) patch.collections = plain(collections)
|
|
162
|
-
if (Object.keys(patch).length) scope.update(patch)
|
|
163
|
-
}
|
|
185
|
+
if (serialized !== val(config.collections)) await ctx.settings.update(ns, { collections: serialized })
|
|
164
186
|
} catch (err) {
|
|
165
|
-
console.error(`[${ns}]
|
|
187
|
+
console.error(`[${ns}] settings sync error:`, err)
|
|
188
|
+
} finally {
|
|
189
|
+
flushing = false
|
|
166
190
|
}
|
|
167
|
-
})
|
|
168
|
-
|
|
169
|
-
|
|
191
|
+
}, 50)
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
let collections = rescan()
|
|
195
|
+
ctx.effect(() => ctx.on('loader/volatile-update', () => {
|
|
196
|
+
try {
|
|
197
|
+
collections = rescan()
|
|
198
|
+
} catch (err) {
|
|
199
|
+
console.error(`[${ns}] rescan error:`, err)
|
|
200
|
+
}
|
|
201
|
+
}), `${ns}: volatile rescan`)
|
|
170
202
|
|
|
171
203
|
// 已配置接口目录(按集合分组展示,title 说明集合用途;部署侧静态接口不在任何集合时单独一组)
|
|
172
204
|
function catalogText() {
|
|
@@ -194,13 +226,13 @@ export function defineApiPlugin(options) {
|
|
|
194
226
|
if (hits.length > 1) return { ambiguous: hits }
|
|
195
227
|
if (hits.length === 1) return { c: hits[0], path: norm }
|
|
196
228
|
if (staticEndpoints.some((e) => matchEndpoint(norm, e))) {
|
|
197
|
-
return { c: { name: '_static', baseUrl:
|
|
229
|
+
return { c: { name: '_static', baseUrl: config.baseUrl || '', apis: staticEndpoints, sections: [] }, path: norm }
|
|
198
230
|
}
|
|
199
231
|
return null
|
|
200
232
|
}
|
|
201
233
|
|
|
202
234
|
// 集合的服务前缀:实时重读该集合的 cfg 文件(改文件即生效,无需重启),回退扫描快照
|
|
203
|
-
const baseUrlOf = (c) => c.name === '_static' ?
|
|
235
|
+
const baseUrlOf = (c) => c.name === '_static' ? config.baseUrl || '' : loadCfgFile(c.file).baseUrl || c.baseUrl || ''
|
|
204
236
|
const ambiguousMsg = (norm, hits) => `接口 ${norm} 在多个集合中命中(${hits.map((c) => c.name).join('、')}),请用「集合名/路径」精确指定,如:${hits[0].name}${norm}`
|
|
205
237
|
const normPath = (p) => ('/' + p.trim().replace(/^\/+/, '')).split('?')[0]
|
|
206
238
|
|
|
@@ -277,7 +309,7 @@ export function defineApiPlugin(options) {
|
|
|
277
309
|
},
|
|
278
310
|
})
|
|
279
311
|
|
|
280
|
-
console.log(`[${ns}] loaded; endpoints=${mergedEndpoints(
|
|
312
|
+
console.log(`[${ns}] loaded; apiDir=${val(config.apiDir) || '(未配置)'}, endpoints=${mergedEndpoints(collections).length}, collections=${collections.map((c) => c.name).join(',') || '(无)'}`)
|
|
281
313
|
}
|
|
282
314
|
|
|
283
315
|
return { Config, inject, apply }
|
package/client.js
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
|
-
//
|
|
1
|
+
// 浏览器半侧:在「插件」页的本插件详情页注册一张展示卡片
|
|
2
2
|
// 接口的增删以 cfg 文件为唯一来源:这里只读展示集合手风琴,编辑请改 cfg 后点「扫描」重扫
|
|
3
|
-
// API
|
|
3
|
+
// API 目录失焦或点「扫描」时经 configForms 表单写入(DSH 0.1.7+ 的 plugins.bundle.config 槽位),无页脚按钮
|
|
4
4
|
window.__ModuleLoader__.load({
|
|
5
5
|
id: "dsh-apis-plugin",
|
|
6
6
|
factory: (require) => {
|
|
7
7
|
const { jsx, jsxs } = require("react/jsx-runtime");
|
|
8
8
|
const react = require("react");
|
|
9
9
|
|
|
10
|
-
/**
|
|
10
|
+
/** 本卡片读写的 settings 命名空间,须与宿主侧 index.js 按 cordis.patch.yml 的 id 回写一致(亦即 Host 插件条目 id) */
|
|
11
11
|
const NS = "dsh-apis-plugin";
|
|
12
12
|
|
|
13
|
-
/** bind
|
|
14
|
-
let
|
|
13
|
+
/** bind 后的配置表单(apply 时赋值):读快照、写字段都经由它 */
|
|
14
|
+
let form;
|
|
15
15
|
|
|
16
16
|
// 精简样式(类名自持,不依赖原生卡片哈希类)
|
|
17
17
|
const css = `
|
|
@@ -131,16 +131,18 @@ window.__ModuleLoader__.load({
|
|
|
131
131
|
] });
|
|
132
132
|
};
|
|
133
133
|
|
|
134
|
-
/**
|
|
134
|
+
/** 扫描:目录有改动先落盘,再写 scanToken 触发配置变更重应用,服务端重扫 cfg 并把集合写回;目录为空则清空列表 */
|
|
135
135
|
async function scan() {
|
|
136
|
-
if (loading || !ready) return;
|
|
136
|
+
if (loading || !ready || !form) return;
|
|
137
137
|
setLoading(true);
|
|
138
138
|
try {
|
|
139
|
-
if (dirDirty) await
|
|
140
|
-
await
|
|
139
|
+
if (dirDirty) await form.set("apiDir", shownDir.trim());
|
|
140
|
+
await form.set("scanToken", String(Date.now()));
|
|
141
141
|
setDirDraft(null);
|
|
142
142
|
setLoaded(true);
|
|
143
143
|
setTimeout(() => setLoaded(false), 2000);
|
|
144
|
+
} catch {
|
|
145
|
+
// 写入被拒(如 revision 冲突恢复失败)时静默结束,避免 unhandled rejection
|
|
144
146
|
} finally {
|
|
145
147
|
setLoading(false);
|
|
146
148
|
}
|
|
@@ -167,7 +169,7 @@ window.__ModuleLoader__.load({
|
|
|
167
169
|
value: shownDir, disabled: !ready || loading,
|
|
168
170
|
onChange: (e) => setDirDraft(e.target.value),
|
|
169
171
|
onBlur: () => {
|
|
170
|
-
if (dirDirty && ready)
|
|
172
|
+
if (dirDirty && ready && form) form.set("apiDir", dirDraft).catch(() => {});
|
|
171
173
|
setDirDraft(null);
|
|
172
174
|
},
|
|
173
175
|
onKeyDown: (e) => e.key === "Enter" && e.currentTarget.blur(),
|
|
@@ -190,19 +192,19 @@ window.__ModuleLoader__.load({
|
|
|
190
192
|
] });
|
|
191
193
|
}
|
|
192
194
|
|
|
193
|
-
/**
|
|
194
|
-
const inject = ["slots", "
|
|
195
|
+
/** 需要的浏览器侧服务:configForms 由 ui-settings 提供,封装 Host settings 的读快照与写字段 */
|
|
196
|
+
const inject = ["slots", "configForms"];
|
|
195
197
|
|
|
196
198
|
/**
|
|
197
|
-
*
|
|
198
|
-
*
|
|
199
|
+
* 以本插件包名为 key 注册到 plugins.bundle.config 槽位:
|
|
200
|
+
* DSH 0.1.7+ 的「插件」页会把 keyed 槽位的卡片渲染在对应包的详情页配置区
|
|
199
201
|
*/
|
|
200
202
|
function apply(ctx) {
|
|
201
|
-
|
|
202
|
-
const store = createStore(
|
|
203
|
-
ctx.effect(() =>
|
|
204
|
-
ctx.effect(() => ctx.slots.inject("
|
|
205
|
-
name: "
|
|
203
|
+
form = ctx.configForms.get(NS);
|
|
204
|
+
const store = createStore(form.getSnapshot());
|
|
205
|
+
ctx.effect(() => form.subscribe(() => store.set(form.getSnapshot())));
|
|
206
|
+
ctx.effect(() => ctx.slots.inject("plugins.bundle.config", () => ctx.slots.register({
|
|
207
|
+
name: "plugins.bundle.config",
|
|
206
208
|
key: NS,
|
|
207
209
|
inject: () => ({ hooks: { apisCard: store } }),
|
|
208
210
|
}, ApisCard)));
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-apis-plugin",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "通用接口管理插件:把任意一套 HTTP 接口注册成 agent 可用的文档查询与请求双工具",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -18,6 +18,9 @@
|
|
|
18
18
|
"tools"
|
|
19
19
|
],
|
|
20
20
|
"main": "index.js",
|
|
21
|
+
"peerDependencies": {
|
|
22
|
+
"@deepseek-ai/dsh": ">=0.1.7-rc.2"
|
|
23
|
+
},
|
|
21
24
|
"exports": {
|
|
22
25
|
".": "./index.js",
|
|
23
26
|
"./client": "./client.js"
|
|
@@ -37,6 +40,6 @@
|
|
|
37
40
|
}
|
|
38
41
|
},
|
|
39
42
|
"dependencies": {
|
|
40
|
-
"@deepseek-ai/schemastery": "^3.18.
|
|
43
|
+
"@deepseek-ai/schemastery": "^3.18.4"
|
|
41
44
|
}
|
|
42
45
|
}
|