dsh-apis-plugin 0.1.6 → 0.1.8

package/README.md

@@ -13,36 +13,42 @@ dsh plugin --profile web add dsh-apis-plugin
 安装后重启 `dsh web` 生效。指定版本：
 
 ```sh
-dsh plugin --profile web add dsh-apis-plugin@0.1.5
+dsh plugin --profile web add dsh-apis-plugin@0.1.6
 ```
 
 ## 配置
 
+建议把 `api.cfg` 和 `api_doc.md` 一起放在同一个目录下（如项目的 `config/` 目录），然后在插件配置页把「API配置」指向该目录：
+
+```
+config/
+├── api.cfg      # 接口清单
+└── api_doc.md   # 接口文档
+```
+
 ### 1. api.cfg（接口清单，必需）
 
-在插件配置页指定的 API 目录下创建 `api.cfg`（key=value 行，`#` 注释，UTF-8 编码）：
+key=value 行格式，`#` 注释，UTF-8 编码：
 
 ```ini
 # 接口服务前缀：域名 + nginx 前缀 + 网关路由段
 baseUrl=http://your-host/prod-api
 
-# 接口列表：逗号分隔同行书写
-apis=/users/page,/users/{id}
-
-# 或逐行列举
+# 接口列表：apis= 下面逐行一个接口
 apis=
+  /users/page
+  /users/{id}
   /outline/page
   /outline/detailByNos
-  /basicTargetChar/item/listByTargetCharId
 ```
 
 - `baseUrl`：请求时拼接在接口路径前（改文件即生效，无需重启）
 - `apis`：接口白名单，支持 `{param}` 模板段（如 `/users/{id}`），agent 请求时填实际值
-- **增删接口只改这个文件**，改完点插件配置页的「加载API」（或重启）生效
+- **增删接口只改这个文件**，改完点插件配置页的「扫描」（或重启）生效
 
 ### 2. api_doc.md（接口文档，建议提供）
 
-与 `api.cfg` 同目录。用 `---` 分节，每节描述一个接口，节内用反引号标注接口路径：
+与 `api.cfg` 放在一起。用 `---` 分节，每节描述一个接口，节内用反引号标注接口路径：
 
 ```markdown
 ## 通用说明
@@ -82,7 +88,7 @@ agent 调用 `{prefix}_api_doc` 时按路径命中对应小节返回。
 | 操作 | 说明 |
 |---|---|
 | API 配置 | 填 api.cfg / api_doc.md 所在目录，**失焦或回车自动保存** |
-| 加载API | 重扫目录：接口列表严格等于当前 api.cfg 内容 |
+| 扫描 | 重扫目录：接口列表严格等于当前 api.cfg 内容；**目录留空点击则清空列表** |
 | 接口列表 | 只读展示，增删请在 api.cfg 中操作 |
 
 ### Agent 工具
@@ -105,7 +111,7 @@ dsh 控制台日志：
 ```
 
 - `endpoints=0`：检查 API 目录路径是否正确、api.cfg 是否与目录同级
-- 加载后列表与 api.cfg 不一致：确认已在配置页点过「加载API」
+- 加载后列表与 api.cfg 不一致：确认已在配置页点过「扫描」
 - 提示未配置 baseUrl：在 api.cfg 写入 `baseUrl=http://...`
 
 ## License

package/client.js

@@ -1,6 +1,6 @@
 // 浏览器半侧：在「插件配置」标签页为 dsh-apis-plugin 命名空间注册一张展示卡片
-// 接口的增删以 api.cfg 为唯一来源：这里只读展示列表，编辑请改 api.cfg 后点「加载API」重扫
-// API 目录失焦或点「加载API」时自动保存，无页脚按钮
+// 接口的增删以 api.cfg 为唯一来源：这里只读展示列表，编辑请改 api.cfg 后点「扫描」重扫
+// API 目录失焦或点「扫描」时自动保存，无页脚按钮
 // 样式与 DOM 结构对齐原生 PluginCard（li 卡片 + SVG 箭头）
 window.__ModuleLoader__.load({
 	id: "dsh-apis-plugin",
@@ -81,8 +81,8 @@ window.__ModuleLoader__.load({
 		function ApisCard(props) {
 			const state = props.useApisCard((s) => s);
 			const [dirDraft, setDirDraft] = react.useState(null); // 文档目录，null 表示未编辑
-			const [loading, setLoading] = react.useState(false); // 加载API 扫描中
-			const [loaded, setLoaded] = react.useState(false); // 加载API 完成后短暂提示
+			const [loading, setLoading] = react.useState(false); // 扫描进行中
+			const [loaded, setLoaded] = react.useState(false); // 扫描完成后短暂提示
 			const [open, setOpen] = react.useState(false); // 折叠态只显示标题行
 			const ready = state.status === "ready" && state.writable;
 
@@ -93,15 +93,15 @@ window.__ModuleLoader__.load({
 			const shownDir = dirDraft ?? savedDir;
 			const dirDirty = dirDraft !== null && dirDraft !== savedDir;
 
-			/** 目录失焦时自动保存（点「加载API」也会先写入目录） */
+			/** 目录失焦时自动保存（点「扫描」也会先写入目录） */
 			function commitDir() {
 				if (dirDirty && ready) scope.set("apiDir", dirDraft);
 				setDirDraft(null);
 			}
 
-			/** 加载API：把目录写入配置并翻转 scanToken，服务端 watch 重扫 apis.txt 后回写接口列表 */
+			/** 扫描：把目录写入配置并翻转 scanToken，服务端重扫 api.cfg 后回写接口列表；目录为空则清空列表 */
 			async function loadApis() {
-				if (loading || !ready || !shownDir.trim()) return;
+				if (loading || !ready) return;
 				setLoading(true);
 				try {
 					if (dirDirty) await scope.set("apiDir", shownDir.trim());
@@ -143,7 +143,7 @@ window.__ModuleLoader__.load({
 					}),
 					// 展开体：API配置目录行 + 分隔线 + 接口行列表（只读）
 					open && react_jsx_runtime.jsxs("div", { className: "apis-body", children: [
-						// API配置：文档目录（api.cfg / api_doc.md 所在目录，失焦自动保存）+ 加载API 重扫按钮
+						// API配置：文档目录（api.cfg / api_doc.md 所在目录，失焦自动保存）+ 扫描按钮（目录为空则清空列表）
 						react_jsx_runtime.jsxs("div", { className: "apis-row", children: [
 							react_jsx_runtime.jsx("div", { className: "apis-rowLabel apis-rowLabelWide", children: "API配置" }),
 							react_jsx_runtime.jsx("input", {
@@ -151,19 +151,19 @@ window.__ModuleLoader__.load({
 								onChange: (e) => setDirDraft(e.target.value),
 								onBlur: commitDir,
 								onKeyDown: (e) => { if (e.key === "Enter") e.currentTarget.blur(); },
-								placeholder: "api.cfg / api_doc.md 所在目录",
+								placeholder: "api.cfg / api_doc.md 所在目录，留空扫描即清空列表",
 								className: "apis-input",
 							}),
 							react_jsx_runtime.jsx("button", {
-								type: "button", disabled: !ready || loading || !shownDir.trim(),
+								type: "button", disabled: !ready || loading,
 								onClick: loadApis,
-								className: "apis-btn apis-discard", children: loading ? "扫描中…" : "加载API",
+								className: "apis-btn apis-discard", children: loading ? "扫描中…" : "扫描",
 							}),
-							loaded && react_jsx_runtime.jsx("span", { className: "apis-saved", children: "已加载" }),
+							loaded && react_jsx_runtime.jsx("span", { className: "apis-saved", children: "已扫描" }),
 						] }),
 						react_jsx_runtime.jsx("hr", { className: "apis-hr" }),
 						!state.writable && react_jsx_runtime.jsx("span", { className: "apis-description", children: "只读" }),
-						list.length ? list.map(row) : react_jsx_runtime.jsx("span", { className: "apis-empty", children: "暂无接口：请在 API 目录下的 api.cfg 中配置 apis，然后点击「加载API」" }),
+						list.length ? list.map(row) : react_jsx_runtime.jsx("span", { className: "apis-empty", children: "暂无接口：请在 API 目录下的 api.cfg 中配置 apis，然后点击「扫描」" }),
 					] }),
 				],
 			});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-apis-plugin",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "通用接口管理插件：把任意一套 HTTP 接口注册成 agent 可用的文档查询与请求双工具",
   "type": "module",
   "license": "MIT",