dsh-apis-plugin 0.1.9 → 0.1.11

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 CHANGED
@@ -102,7 +102,12 @@ agent 调用 `{prefix}_api_doc` 时按路径命中对应小节返回。
102
102
  | `api_api_doc` | 查接口文档:传 `path` 返回该接口的参数与响应说明;不传返回通用说明和已配置接口目录 |
103
103
  | `api_api_request` | 真正调用接口:`path` 必须在白名单内,GET 用 `query`,POST 用 `body` |
104
104
 
105
- 超出 api.cfg 范围的请求会被直接拒绝,并提示可用接口列表。
105
+ 超出 api.cfg 范围的请求(无论查文档还是发请求)会被直接拒绝,并提示可用接口列表。
106
+
107
+ 安全机制:
108
+
109
+ - **删除接口二次确认**:调用 `DELETE` 时首次只返回确认提示,不会执行;需携带 `confirm=true` 再次调用才会真正执行
110
+ - **写操作警告**:`POST` / `PUT` / `PATCH` 的返回结果前会附带警告块,明示将执行的接口、完整地址与参数
106
111
 
107
112
  ## 排查
108
113
 
package/api-tools.js CHANGED
@@ -164,6 +164,9 @@ export function defineApiPlugin(options) {
164
164
  return bootEndpoints
165
165
  }
166
166
 
167
+ // 删除操作的待确认记录(key: "DELETE <完整地址>"):只有先收到过确认提示,confirm=true 才会放行
168
+ const pendingDeletes = new Set()
169
+
167
170
  // 工具 1:查接口文档,让模型了解每个接口的参数与响应(prompt 按领域名拼接)
168
171
  ctx.tools.register({
169
172
  name: `${prefix}_api_doc`,
@@ -178,6 +181,10 @@ export function defineApiPlugin(options) {
178
181
  return '【通用说明】\n' + (docSections[0] ?? '') + '\n\n【已配置接口目录】\n' + list.join('\n')
179
182
  }
180
183
  const norm = ('/' + args.path.trim().replace(/^\/+/, '')).split('?')[0]
184
+ // 查询范围严格限制在已配置列表内:列表外的接口一律拒绝
185
+ if (!list.some((e) => matchEndpoint(norm, e))) {
186
+ return `接口 ${norm} 不在已配置列表中,已拒绝查询。可用接口:\n` + list.join('\n')
187
+ }
181
188
  const hit = docSections.filter((s) => s.includes('`' + norm + '`'))
182
189
  if (hit.length) return hit.join('\n\n---\n\n')
183
190
  return `文档中未找到 ${norm}。已配置接口目录:\n` + list.join('\n')
@@ -187,12 +194,13 @@ export function defineApiPlugin(options) {
187
194
  // 工具 2:真正调用接口拿数据(prompt 按领域名拼接)
188
195
  ctx.tools.register({
189
196
  name: `${prefix}_api_request`,
190
- description: `调用${domainName}接口并返回 JSON 数据。path 必须是已配置的接口(支持 /orders/{id} 这类模板路径,模板段填实际值);GET 用 query 传参,POST 用 body 传 JSON。请依据 ${prefix}_api_doc 返回的文档构造请求,文档即权威,无需从源码核实接口行为。`,
197
+ description: `调用${domainName}接口并返回 JSON 数据。path 必须是已配置的接口(支持 /orders/{id} 这类模板路径,模板段填实际值);GET 用 query 传参,POST 用 body 传 JSON。安全规则:① DELETE 属于危险操作,首次调用只返回确认提示不会执行,必须先向用户二次确认,用户明确同意后才能携带 confirm=true 再次调用;② 返回结果若以 ⚠️ 开头(写操作警告/危险操作确认),必须在回复中原样向用户展示警告块内容(含接口、方法、完整地址与参数),不得省略、转述或只报结果。请依据 ${prefix}_api_doc 返回的文档构造请求,文档即权威,无需从源码核实接口行为。`,
191
198
  parameters: {
192
199
  path: { type: 'string', required: true, description: '接口路径,如 /users/detail 或 /orders/123' },
193
200
  method: { type: 'string', description: 'HTTP 方法,默认 GET' },
194
201
  query: { type: 'json', description: 'query 参数对象,如 { "keyword": "abc" }' },
195
202
  body: { type: 'json', description: 'POST 请求体(JSON 对象)' },
203
+ confirm: { type: 'boolean', description: '删除操作的二次确认标记:仅在与用户确认且收到过确认提示后才能传 true;未经确认提示不得传' },
196
204
  },
197
205
  output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
198
206
  async execute(args) {
@@ -215,6 +223,24 @@ export function defineApiPlugin(options) {
215
223
  url.searchParams.set(k, String(v))
216
224
  }
217
225
 
226
+ // 删除操作:两段式确认。首次调用只返回确认提示并记录待确认项;
227
+ // 即使模型首次就带 confirm=true,只要没有对应的待确认记录也一律拒绝执行
228
+ if (method === 'DELETE') {
229
+ const key = method + ' ' + url.toString()
230
+ if (args.confirm === true && pendingDeletes.has(key)) {
231
+ pendingDeletes.delete(key)
232
+ } else {
233
+ pendingDeletes.add(key)
234
+ return `⚠️【危险操作确认】本次将执行删除接口:\n ${method} ${url.toString()}\n` +
235
+ '该操作可能不可恢复。请先向用户二次确认;用户同意后,携带 confirm=true 重新调用本工具才会真正执行。'
236
+ }
237
+ }
238
+
239
+ // 写操作:在结果前向用户明示将执行哪个接口
240
+ const writeWarn = ['POST', 'PUT', 'PATCH'].includes(method)
241
+ ? `⚠️【写操作警告】本次请求将执行接口:${method} ${url.toString()}(query: ${JSON.stringify(args.query ?? {})};body: ${JSON.stringify(args.body ?? null)})\n\n`
242
+ : ''
243
+
218
244
  const response = await fetch(url, {
219
245
  method,
220
246
  headers: { Accept: 'application/json', ...(args.body != null ? { 'Content-Type': 'application/json' } : {}) },
@@ -223,10 +249,11 @@ export function defineApiPlugin(options) {
223
249
  const text = await response.text()
224
250
 
225
251
  if (!response.ok) {
226
- return `HTTP ${response.status} ${response.statusText}\n` + text.slice(0, 4000)
252
+ return writeWarn + `HTTP ${response.status} ${response.statusText}\n` + text.slice(0, 4000)
227
253
  }
228
254
  // 非文件流接口直接返回 JSON 文本,超长截断
229
- return text.length > 30000 ? text.slice(0, 30000) + '\n…(超长截断)' : text
255
+ const result = text.length > 30000 ? text.slice(0, 30000) + '\n…(超长截断)' : text
256
+ return writeWarn + result
230
257
  },
231
258
  })
232
259
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-apis-plugin",
3
- "version": "0.1.9",
3
+ "version": "0.1.11",
4
4
  "description": "通用接口管理插件:把任意一套 HTTP 接口注册成 agent 可用的文档查询与请求双工具",
5
5
  "type": "module",
6
6
  "license": "MIT",