dsh-apis-plugin 0.1.8 → 0.1.10
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 +8 -1
- package/api-tools.js +21 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -67,6 +67,8 @@ apis=
|
|
|
67
67
|
|
|
68
68
|
agent 调用 `{prefix}_api_doc` 时按路径命中对应小节返回。
|
|
69
69
|
|
|
70
|
+
💡 建议:在「通用说明」里注明 *“本文档与线上服务一一对应,以此为准”*,并写清字段语义(如 `status=0 编辑中,1 待审核`)——工具描述已声明文档为权威依据,写清楚后 agent 会直接按文档调用,不会再去翻后端源码核实。
|
|
71
|
+
|
|
70
72
|
### 3. 部署侧 cordis.patch.yml(可选覆盖)
|
|
71
73
|
|
|
72
74
|
```yaml
|
|
@@ -100,7 +102,12 @@ agent 调用 `{prefix}_api_doc` 时按路径命中对应小节返回。
|
|
|
100
102
|
| `api_api_doc` | 查接口文档:传 `path` 返回该接口的参数与响应说明;不传返回通用说明和已配置接口目录 |
|
|
101
103
|
| `api_api_request` | 真正调用接口:`path` 必须在白名单内,GET 用 `query`,POST 用 `body` |
|
|
102
104
|
|
|
103
|
-
超出 api.cfg
|
|
105
|
+
超出 api.cfg 范围的请求(无论查文档还是发请求)会被直接拒绝,并提示可用接口列表。
|
|
106
|
+
|
|
107
|
+
安全机制:
|
|
108
|
+
|
|
109
|
+
- **删除接口二次确认**:调用 `DELETE` 时首次只返回确认提示,不会执行;需携带 `confirm=true` 再次调用才会真正执行
|
|
110
|
+
- **写操作警告**:`POST` / `PUT` / `PATCH` 的返回结果前会附带警告块,明示将执行的接口、完整地址与参数
|
|
104
111
|
|
|
105
112
|
## 排查
|
|
106
113
|
|
package/api-tools.js
CHANGED
|
@@ -167,7 +167,7 @@ export function defineApiPlugin(options) {
|
|
|
167
167
|
// 工具 1:查接口文档,让模型了解每个接口的参数与响应(prompt 按领域名拼接)
|
|
168
168
|
ctx.tools.register({
|
|
169
169
|
name: `${prefix}_api_doc`,
|
|
170
|
-
description: `查询${domainName}
|
|
170
|
+
description: `查询${domainName}接口文档。api_doc.md 与部署的服务一一对应,是这些接口的权威依据。传 path(如 /users/page)返回该接口的详细参数与响应说明;不传 path 返回通用说明和全部已配置接口目录。发起请求前先用它确认参数,按文档直接调用即可,不要再去查阅后端源码或其他材料核实接口行为。`,
|
|
171
171
|
parameters: {
|
|
172
172
|
path: { type: 'string', description: '接口路径,如 /users/{id}' },
|
|
173
173
|
},
|
|
@@ -178,6 +178,10 @@ export function defineApiPlugin(options) {
|
|
|
178
178
|
return '【通用说明】\n' + (docSections[0] ?? '') + '\n\n【已配置接口目录】\n' + list.join('\n')
|
|
179
179
|
}
|
|
180
180
|
const norm = ('/' + args.path.trim().replace(/^\/+/, '')).split('?')[0]
|
|
181
|
+
// 查询范围严格限制在已配置列表内:列表外的接口一律拒绝
|
|
182
|
+
if (!list.some((e) => matchEndpoint(norm, e))) {
|
|
183
|
+
return `接口 ${norm} 不在已配置列表中,已拒绝查询。可用接口:\n` + list.join('\n')
|
|
184
|
+
}
|
|
181
185
|
const hit = docSections.filter((s) => s.includes('`' + norm + '`'))
|
|
182
186
|
if (hit.length) return hit.join('\n\n---\n\n')
|
|
183
187
|
return `文档中未找到 ${norm}。已配置接口目录:\n` + list.join('\n')
|
|
@@ -187,12 +191,13 @@ export function defineApiPlugin(options) {
|
|
|
187
191
|
// 工具 2:真正调用接口拿数据(prompt 按领域名拼接)
|
|
188
192
|
ctx.tools.register({
|
|
189
193
|
name: `${prefix}_api_request`,
|
|
190
|
-
description: `调用${domainName}接口并返回 JSON 数据。path 必须是已配置的接口(支持 /orders/{id} 这类模板路径,模板段填实际值);GET 用 query 传参,POST 用 body 传 JSON
|
|
194
|
+
description: `调用${domainName}接口并返回 JSON 数据。path 必须是已配置的接口(支持 /orders/{id} 这类模板路径,模板段填实际值);GET 用 query 传参,POST 用 body 传 JSON。DELETE 属于危险操作:首次调用只返回确认提示,需携带 confirm=true 再次调用才会真正执行。请依据 ${prefix}_api_doc 返回的文档构造请求,文档即权威,无需从源码核实接口行为。`,
|
|
191
195
|
parameters: {
|
|
192
196
|
path: { type: 'string', required: true, description: '接口路径,如 /users/detail 或 /orders/123' },
|
|
193
197
|
method: { type: 'string', description: 'HTTP 方法,默认 GET' },
|
|
194
198
|
query: { type: 'json', description: 'query 参数对象,如 { "keyword": "abc" }' },
|
|
195
199
|
body: { type: 'json', description: 'POST 请求体(JSON 对象)' },
|
|
200
|
+
confirm: { type: 'boolean', description: '删除操作的二次确认标记:首次调用 DELETE 只返回确认提示,用户确认后需带 confirm=true 重新调用' },
|
|
196
201
|
},
|
|
197
202
|
output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
|
|
198
203
|
async execute(args) {
|
|
@@ -215,6 +220,17 @@ export function defineApiPlugin(options) {
|
|
|
215
220
|
url.searchParams.set(k, String(v))
|
|
216
221
|
}
|
|
217
222
|
|
|
223
|
+
// 删除操作:二次确认,首次调用不执行,仅返回确认提示
|
|
224
|
+
if (method === 'DELETE' && args.confirm !== true) {
|
|
225
|
+
return `⚠️【危险操作确认】本次将执行删除接口:\n ${method} ${url.toString()}\n` +
|
|
226
|
+
'该操作可能不可恢复。请先向用户二次确认;用户同意后,携带 confirm=true 重新调用本工具才会真正执行。'
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
// 写操作:在结果前向用户明示将执行哪个接口
|
|
230
|
+
const writeWarn = ['POST', 'PUT', 'PATCH'].includes(method)
|
|
231
|
+
? `⚠️【写操作警告】本次请求将执行接口:${method} ${url.toString()}(query: ${JSON.stringify(args.query ?? {})};body: ${JSON.stringify(args.body ?? null)})\n\n`
|
|
232
|
+
: ''
|
|
233
|
+
|
|
218
234
|
const response = await fetch(url, {
|
|
219
235
|
method,
|
|
220
236
|
headers: { Accept: 'application/json', ...(args.body != null ? { 'Content-Type': 'application/json' } : {}) },
|
|
@@ -223,10 +239,11 @@ export function defineApiPlugin(options) {
|
|
|
223
239
|
const text = await response.text()
|
|
224
240
|
|
|
225
241
|
if (!response.ok) {
|
|
226
|
-
return `HTTP ${response.status} ${response.statusText}\n` + text.slice(0, 4000)
|
|
242
|
+
return writeWarn + `HTTP ${response.status} ${response.statusText}\n` + text.slice(0, 4000)
|
|
227
243
|
}
|
|
228
244
|
// 非文件流接口直接返回 JSON 文本,超长截断
|
|
229
|
-
|
|
245
|
+
const result = text.length > 30000 ? text.slice(0, 30000) + '\n…(超长截断)' : text
|
|
246
|
+
return writeWarn + result
|
|
230
247
|
},
|
|
231
248
|
})
|
|
232
249
|
|