init

2026-03-13 19:14:37 +08:00
commit 3e54f994fd
59 changed files with 7238 additions and 0 deletions
--- a/src/modules/project-api.ts
+++ b/src/modules/project-api.ts
@@ -0,0 +1,404 @@
+import { createQueryApi } from '@kevisual/query/api';
+import { query }  from '@/modules/query.ts';
+const api = {
+  "project": {
+    /**
+     * 注册并启动项目监控：开始监听项目目录的文件变更，并将所有文件全量同步到 Meilisearch 搜索索引
+     *
+     * @param data - Request parameters
+     * @param data.filepath - {string} 项目根目录的绝对路径，必填
+     * @param data.repo - {string} 代码仓库标识，用于搜索结果展示和过滤，格式如 owner/repo，例如 kevisual/cnb，选填（默认自动从 git 配置读取）
+     * @param data.name - {string} 项目显示名称，用于搜索结果展示，选填（默认使用目录名）
+     */
+    "add": {
+      "path": "project",
+      "key": "add",
+      "description": "注册并启动项目监控：开始监听项目目录的文件变更，并将所有文件全量同步到 Meilisearch 搜索索引",
+      "metadata": {
+        "args": {
+          "filepath": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "string",
+            "description": "项目根目录的绝对路径，必填"
+          },
+          "repo": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "代码仓库标识，用于搜索结果展示和过滤，格式如 owner/repo，例如 kevisual/cnb，选填（默认自动从 git 配置读取）",
+            "type": "string",
+            "optional": true
+          },
+          "name": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "项目显示名称，用于搜索结果展示，选填（默认使用目录名）",
+            "type": "string",
+            "optional": true
+          }
+        },
+        "url": "/root/v1/cnb-dev",
+        "source": "query-proxy-api"
+      }
+    },
+    /**
+     * 移除项目：停止文件变更监听，并清除该项目在 Meilisearch 索引中的所有数据
+     *
+     * @param data - Request parameters
+     * @param data.filepath - {string (minLength: 1)} 要移除的项目根目录绝对路径，必填
+     */
+    "remove": {
+      "path": "project",
+      "key": "remove",
+      "description": "移除项目：停止文件变更监听，并清除该项目在 Meilisearch 索引中的所有数据",
+      "metadata": {
+        "args": {
+          "filepath": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "string",
+            "minLength": 1,
+            "description": "要移除的项目根目录绝对路径，必填"
+          }
+        },
+        "url": "/root/v1/cnb-dev",
+        "source": "query-proxy-api"
+      }
+    },
+    /**
+     * 暂停项目的文件变更监听，暂停后文件修改将不再实时同步；可通过 add 接口重新启动监听
+     *
+     * @param data - Request parameters
+     * @param data.filepath - {string (minLength: 1)} 要暂停监听的项目根目录绝对路径，必填
+     */
+    "stop": {
+      "path": "project",
+      "key": "stop",
+      "description": "暂停项目的文件变更监听，暂停后文件修改将不再实时同步；可通过 add 接口重新启动监听",
+      "metadata": {
+        "args": {
+          "filepath": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "string",
+            "minLength": 1,
+            "description": "要暂停监听的项目根目录绝对路径，必填"
+          }
+        },
+        "url": "/root/v1/cnb-dev",
+        "source": "query-proxy-api"
+      }
+    },
+    /**
+     * 获取指定项目的详细信息，包括路径、仓库名称、项目名称及当前监听状态等
+     *
+     * @param data - Request parameters
+     * @param data.filepath - {string (minLength: 1)} 要查询的项目根目录绝对路径，必填
+     */
+    "get": {
+      "path": "project",
+      "key": "get",
+      "description": "获取指定项目的详细信息，包括路径、仓库名称、项目名称及当前监听状态等",
+      "metadata": {
+        "args": {
+          "filepath": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "string",
+            "minLength": 1,
+            "description": "要查询的项目根目录绝对路径，必填"
+          }
+        },
+        "url": "/root/v1/cnb-dev",
+        "source": "query-proxy-api"
+      }
+    },
+    /**
+     * 列出所有已注册的项目及其当前运行状态（路径、仓库名称、监听是否活跃等）
+     */
+    "list": {
+      "path": "project",
+      "key": "list",
+      "description": "列出所有已注册的项目及其当前运行状态（路径、仓库名称、监听是否活跃等）",
+      "metadata": {
+        "url": "/root/v1/cnb-dev",
+        "source": "query-proxy-api"
+      }
+    },
+    /**
+     * 更新项目的自定义描述信息（name / title / tags / summary / description / link），用于丰富项目元数据以便更好地展示和检索
+     *
+     * @param data - Request parameters
+     * @param data.filepath - {string (minLength: 1)} 要更新的项目根目录绝对路径，必填
+     * @param data.name - {string} 项目显示名称，选填
+     * @param data.title - {string} 项目标题，用于展示，选填
+     * @param data.tags - {array} 项目标签列表，用于分类过滤，选填
+     * @param data.summary - {string} 项目摘要，简短描述项目用途，选填
+     * @param data.description - {string} 项目详细描述，选填
+     * @param data.link - {string} 项目关联的外部链接（如官网、文档等），选填
+     */
+    "update": {
+      "path": "project",
+      "key": "update",
+      "description": "更新项目的自定义描述信息（name / title / tags / summary / description / link），用于丰富项目元数据以便更好地展示和检索",
+      "metadata": {
+        "args": {
+          "filepath": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "string",
+            "minLength": 1,
+            "description": "要更新的项目根目录绝对路径，必填"
+          },
+          "name": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "项目显示名称，选填",
+            "type": "string",
+            "optional": true
+          },
+          "title": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "项目标题，用于展示，选填",
+            "type": "string",
+            "optional": true
+          },
+          "tags": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "项目标签列表，用于分类过滤，选填",
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "optional": true
+          },
+          "summary": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "项目摘要，简短描述项目用途，选填",
+            "type": "string",
+            "optional": true
+          },
+          "description": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "项目详细描述，选填",
+            "type": "string",
+            "optional": true
+          },
+          "link": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "项目关联的外部链接（如官网、文档等），选填",
+            "type": "string",
+            "optional": true
+          }
+        },
+        "url": "/root/v1/cnb-dev",
+        "source": "query-proxy-api"
+      }
+    }
+  },
+  "project-search": {
+    /**
+     * 在已索引的项目文件中执行全文搜索，支持按仓库、目录、标签等字段过滤，以及自定义排序和数量限制
+     *
+     * @param data - Request parameters
+     * @param data.q - {string} 搜索关键词，选填；留空或不传则返回全部文件
+     * @param data.projectPath - {string} 按项目根目录路径过滤，仅返回该项目下的文件，选填
+     * @param data.repo - {string} 按代码仓库标识过滤（如 owner/repo），选填
+     * @param data.title - {string} 按人工标注的标题字段过滤，选填
+     * @param data.tags - {array} 按人工标注的标签列表过滤，选填
+     * @param data.summary - {string} 按人工标注的摘要字段过滤，选填
+     * @param data.description - {string} 按人工标注的描述字段过滤，选填
+     * @param data.link - {string} 按人工标注的外部链接字段过滤，选填
+     * @param data.sort - {array} 排序规则数组，格式为 ["字段:asc"] 或 ["字段:desc"]，选填，当 q 为空时默认为 ["projectPath:asc"]
+     * @param data.limit - {number} 返回结果数量上限，选填，当 q 为空时默认为 1000
+     * @param data.getContent - {boolean} 是否返回文件内容，默认为 false；如果为 true，则在结果中包含 content 字段，内容以 base64 编码返回，适用于前端预览或下载场景
+     */
+    "files": {
+      "path": "project-search",
+      "key": "files",
+      "description": "在已索引的项目文件中执行全文搜索，支持按仓库、目录、标签等字段过滤，以及自定义排序和数量限制",
+      "metadata": {
+        "args": {
+          "q": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "搜索关键词，选填；留空或不传则返回全部文件",
+            "type": "string",
+            "optional": true
+          },
+          "projectPath": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "按项目根目录路径过滤，仅返回该项目下的文件，选填",
+            "type": "string",
+            "optional": true
+          },
+          "repo": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "按代码仓库标识过滤（如 owner/repo），选填",
+            "type": "string",
+            "optional": true
+          },
+          "title": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "按人工标注的标题字段过滤，选填",
+            "type": "string",
+            "optional": true
+          },
+          "tags": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "按人工标注的标签列表过滤，选填",
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "optional": true
+          },
+          "summary": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "按人工标注的摘要字段过滤，选填",
+            "type": "string",
+            "optional": true
+          },
+          "description": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "按人工标注的描述字段过滤，选填",
+            "type": "string",
+            "optional": true
+          },
+          "link": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "按人工标注的外部链接字段过滤，选填",
+            "type": "string",
+            "optional": true
+          },
+          "sort": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "排序规则数组，格式为 [\"字段:asc\"] 或 [\"字段:desc\"]，选填，当 q 为空时默认为 [\"projectPath:asc\"]",
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "optional": true
+          },
+          "limit": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "返回结果数量上限，选填，当 q 为空时默认为 1000",
+            "type": "number",
+            "optional": true
+          },
+          "getContent": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "是否返回文件内容，默认为 false；如果为 true，则在结果中包含 content 字段，内容以 base64 编码返回，适用于前端预览或下载场景",
+            "type": "boolean",
+            "optional": true
+          }
+        },
+        "url": "/root/v1/cnb-dev",
+        "source": "query-proxy-api"
+      }
+    }
+  },
+  "project-file": {
+    /**
+     * 读取指定路径的项目文件内容，以 base64 格式返回，适用于前端预览或下载场景
+     *
+     * @param data - Request parameters
+     * @param data.filepath - {string (minLength: 1)} 要读取的文件绝对路径，必填
+     */
+    "get": {
+      "path": "project-file",
+      "key": "get",
+      "description": "读取指定路径的项目文件内容，以 base64 格式返回，适用于前端预览或下载场景",
+      "metadata": {
+        "args": {
+          "filepath": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "string",
+            "minLength": 1,
+            "description": "要读取的文件绝对路径，必填"
+          }
+        },
+        "url": "/root/v1/cnb-dev",
+        "source": "query-proxy-api"
+      }
+    },
+    /**
+     * 更新指定文件的自定义描述信息（title / tags / summary / description / link），用于人工标注和补充文件元数据
+     *
+     * @param data - Request parameters
+     * @param data.filepath - {string (minLength: 1)} 要更新的文件绝对路径，必填
+     * @param data.title - {string} 文件标题，用于展示和搜索，选填
+     * @param data.tags - {array} 文件标签列表，用于分类过滤，选填
+     * @param data.summary - {string} 文件摘要，简短描述文件内容，选填
+     * @param data.description - {string} 文件详细描述，选填
+     * @param data.link - {string} 与文件关联的外部链接（如文档、Issue 等），选填
+     */
+    "update": {
+      "path": "project-file",
+      "key": "update",
+      "description": "更新指定文件的自定义描述信息（title / tags / summary / description / link），用于人工标注和补充文件元数据",
+      "metadata": {
+        "args": {
+          "filepath": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "string",
+            "minLength": 1,
+            "description": "要更新的文件绝对路径，必填"
+          },
+          "title": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "文件标题，用于展示和搜索，选填",
+            "type": "string",
+            "optional": true
+          },
+          "tags": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "文件标签列表，用于分类过滤，选填",
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "optional": true
+          },
+          "summary": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "文件摘要，简短描述文件内容，选填",
+            "type": "string",
+            "optional": true
+          },
+          "description": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "文件详细描述，选填",
+            "type": "string",
+            "optional": true
+          },
+          "link": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "description": "与文件关联的外部链接（如文档、Issue 等），选填",
+            "type": "string",
+            "optional": true
+          }
+        },
+        "url": "/root/v1/cnb-dev",
+        "source": "query-proxy-api"
+      }
+    },
+    /**
+     * 从搜索索引中删除指定路径的文件记录，文件本身不受影响
+     *
+     * @param data - Request parameters
+     * @param data.filepath - {string (minLength: 1)} 要删除的文件绝对路径，必填
+     */
+    "delete": {
+      "path": "project-file",
+      "key": "delete",
+      "description": "从搜索索引中删除指定路径的文件记录，文件本身不受影响",
+      "metadata": {
+        "args": {
+          "filepath": {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "type": "string",
+            "minLength": 1,
+            "description": "要删除的文件绝对路径，必填"
+          }
+        },
+        "url": "/root/v1/cnb-dev",
+        "source": "query-proxy-api"
+      }
+    }
+  }
+} as const;
+const queryApi = createQueryApi({ api, query });
+
+export { queryApi };