@ohos-cpf/3rdloop 0.0.1 → 0.0.3

package/vendor/Server/Skills/knowledge-import/references/MCP_TOOL_USAGE.md

@@ -1,165 +1,165 @@
-# MCP 工具调用指南
-
-> 知识导入过程中如何调用 MCP Gateway 提供的知识库工具。
-
----
-
-## 0. MCP Gateway 可用性验证（前置步骤）
-
-在执行任何知识库操作前，**必须先验证 MCP Gateway 和所需工具可用**：
-
-### 0.1 健康检查
-
-```
-工具: gateway_health
-参数: 无
-```
-
-检查返回的 `totalTools` > 0 且 `downstream` 中各 Server 状态为 `connected`。
-
-### 0.2 工具列表确认
-
-```
-工具: gateway_list_tools
-参数: 无
-```
-
-在返回的工具列表中确认以下工具存在：
-- `kb_add_document`（builtin）— 知识库写入
-- `kb_search`（builtin）— 知识库搜索验证
-- `kb-server_*`（downstream，可选）— 远程知识库
-
-> ⚠️ **若 `kb_add_document` 不在工具列表中**：
-> - 知识类导入标记为跳过
-> - 在结果文件中记录"MCP Gateway 未配置或 kb_add_document 工具未注册"
-> - 提醒用户检查 `~/.config/opencode/opencode.json` 中是否配置了 `mcp-gateway`
-> - SKILL类导入（如有）继续执行
-
-### 0.3 MCP Gateway 配置方法
-
-若 MCP Gateway 未配置，需在 `~/.config/opencode/opencode.json` 的 `mcp` 节点中添加：
-
-```json
-"mcp-gateway": {
-  "command": [
-    "node",
-    "/Users/lalhan/Desktop/3rdLibraryLoop/3rdLibraryLoop/MCP/src/index.js",
-    "--config",
-    "/Users/lalhan/Desktop/3rdLibraryLoop/3rdLibraryLoop/MCP/config.json"
-  ],
-  "enabled": true,
-  "type": "local"
-}
-```
-
-配置后需**重启 opencode** 才能让 AI 会话发现并调用 MCP 工具。
-
----
-
-## 1. 可用工具概览
-
-知识导入过程中会用到以下 MCP 工具：
-
-| 工具名 | 来源 | 用途 |
-|--------|------|------|
-| `kb_add_document` | builtin (KBToolProvider) | 向本地知识库引擎添加文档 |
-| `kb_search` | builtin (KBToolProvider) | 搜索本地知识库（验证导入效果） |
-| `kb-server_*` | downstream (远程知识库) | 远程知识库的增删查工具 |
-| `gateway_list_tools` | builtin (Gateway) | 列出所有工具（确认工具名） |
-| `gateway_health` | builtin (Gateway) | 健康检查（Gateway 状态） |
-
----
-
-## 2. 工具调用方式
-
-opencode CLI 执行 SKILL 时，AI 已通过 MCP 协议获取所有工具定义。
-SKILL 指令中只需说明**调用哪个工具、传什么参数**，AI 会自动完成调用。
-
-### 2.1 调用 kb_add_document
-
-```
-工具: kb_add_document
-参数:
-  documentId (string, 必填): 文档唯一标识，如 "experiences/react-native-track-player-upstream-diff"。禁止使用知识条目ID（kn_xxx），应使用知识内容的简明概括作为文档名
-  catalog (string, 必填): 所属目录，如 "best-practices"
-  title (string, 选填): 文档标题
-  content (string, 必填): 文档 Markdown 原文（必须结构化整理，非原始文档）
-```
-
-> ⚠️ content 参数必须按"问题现象/解决方案/结果"结构整理，禁止传入原始经验文档。
-
-### 2.2 调用 kb_search（导入验证）
-
-```
-工具: kb_search
-参数:
-  query (string, 必填): 搜索关键词
-  catalog (string, 选填): 限定目录，如 "best-practices"
-  limit (number, 选填): 返回数量上限，默认 10
-```
-
-### 2.3 调用 kb-server 远程工具
-
-先通过 `gateway_list_tools` 确认远程知识库的实际工具名（前缀为 `kb-server_`），然后调用：
-
-```
-工具: kb-server_create_entry （实际名称以 gateway_list_tools 返回为准）
-参数:
-  title: 经验文档标题
-  content: 知识类内容
-  tags: ["经验沉淀", "相关技术领域"]
-  source: "knowledge-import"
-```
-
-> ⚠️ 远程知识库工具可能不支持 create 操作（测试阶段可能只读）。调用失败时记录警告，不影响整体导入流程。
-
----
-
-## 3. 目录(catalog)说明
-
-本地知识库引擎支持以下目录：
-
-| 目录ID | 用途 | 适用场景 |
-|--------|------|----------|
-| `guides` | 指南文档 | 操作指南、使用教程 |
-| `references` | 参考文档 | API参考、技术规格 |
-| `best-practices` | 最佳实践 | 经验总结、最佳实践、踩坑记录 |
-| `faqs` | 常见问题 | FAQ、疑难解答 |
-| `releases` | 发布说明 | 版本发布、变更记录 |
-| `roadmap` | 路线图 | 规划、路线图 |
-
-知识导入默认使用 `best-practices`，因为经验沉淀本质是最佳实践。
-
----
-
-## 4. 知识库内容结构化格式
-
-导入知识库的 content 必须按以下结构整理，禁止传入原始经验文档：
-
-```markdown
-# {经验标题}
-
-## {条目1标题}
-
-### 问题现象
-{描述遇到的具体问题、困惑或错误表现}
-
-### 解决方案
-{描述如何解决该问题，包括具体方法、命令、配置等}
-
-### 结果
-{描述解决后的效果、验证方式或可复用的结论}
-
----
-
-## {条目2标题}
-
-### 问题现象
-...
-```
-
-**整理规则**：
-- 将原始文档中的"关键发现""踩坑记录""可复用建议"拆解为独立条目
-- 每个条目聚焦一个问题，按"问题现象 → 解决方案 → 结果"三段式重组
-- 去除与问题无直接关联的背景描述，保留可复用的核心信息
-- 多个独立问题用 `---` 分隔
+# MCP 工具调用指南
+
+> 知识导入过程中如何调用 MCP Gateway 提供的知识库工具。
+
+---
+
+## 0. MCP Gateway 可用性验证（前置步骤）
+
+在执行任何知识库操作前，**必须先验证 MCP Gateway 和所需工具可用**：
+
+### 0.1 健康检查
+
+```
+工具: gateway_health
+参数: 无
+```
+
+检查返回的 `totalTools` > 0 且 `downstream` 中各 Server 状态为 `connected`。
+
+### 0.2 工具列表确认
+
+```
+工具: gateway_list_tools
+参数: 无
+```
+
+在返回的工具列表中确认以下工具存在：
+- `kb_add_document`（builtin）— 知识库写入
+- `kb_search`（builtin）— 知识库搜索验证
+- `kb-server_*`（downstream，可选）— 远程知识库
+
+> ⚠️ **若 `kb_add_document` 不在工具列表中**：
+> - 知识类导入标记为跳过
+> - 在结果文件中记录"MCP Gateway 未配置或 kb_add_document 工具未注册"
+> - 提醒用户检查 `~/.config/opencode/opencode.json` 中是否配置了 `mcp-gateway`
+> - SKILL类导入（如有）继续执行
+
+### 0.3 MCP Gateway 配置方法
+
+若 MCP Gateway 未配置，需在 `~/.config/opencode/opencode.json` 的 `mcp` 节点中添加：
+
+```json
+"mcp-gateway": {
+  "command": [
+    "node",
+    "/Users/lalhan/Desktop/3rdLibraryLoop/3rdLibraryLoop/MCP/src/index.js",
+    "--config",
+    "/Users/lalhan/Desktop/3rdLibraryLoop/3rdLibraryLoop/MCP/config.json"
+  ],
+  "enabled": true,
+  "type": "local"
+}
+```
+
+配置后需**重启 opencode** 才能让 AI 会话发现并调用 MCP 工具。
+
+---
+
+## 1. 可用工具概览
+
+知识导入过程中会用到以下 MCP 工具：
+
+| 工具名 | 来源 | 用途 |
+|--------|------|------|
+| `kb_add_document` | builtin (KBToolProvider) | 向本地知识库引擎添加文档 |
+| `kb_search` | builtin (KBToolProvider) | 搜索本地知识库（验证导入效果） |
+| `kb-server_*` | downstream (远程知识库) | 远程知识库的增删查工具 |
+| `gateway_list_tools` | builtin (Gateway) | 列出所有工具（确认工具名） |
+| `gateway_health` | builtin (Gateway) | 健康检查（Gateway 状态） |
+
+---
+
+## 2. 工具调用方式
+
+opencode CLI 执行 SKILL 时，AI 已通过 MCP 协议获取所有工具定义。
+SKILL 指令中只需说明**调用哪个工具、传什么参数**，AI 会自动完成调用。
+
+### 2.1 调用 kb_add_document
+
+```
+工具: kb_add_document
+参数:
+  documentId (string, 必填): 文档唯一标识，如 "experiences/react-native-track-player-upstream-diff"。禁止使用知识条目ID（kn_xxx），应使用知识内容的简明概括作为文档名
+  catalog (string, 必填): 所属目录，如 "best-practices"
+  title (string, 选填): 文档标题
+  content (string, 必填): 文档 Markdown 原文（必须结构化整理，非原始文档）
+```
+
+> ⚠️ content 参数必须按"问题现象/解决方案/结果"结构整理，禁止传入原始经验文档。
+
+### 2.2 调用 kb_search（导入验证）
+
+```
+工具: kb_search
+参数:
+  query (string, 必填): 搜索关键词
+  catalog (string, 选填): 限定目录，如 "best-practices"
+  limit (number, 选填): 返回数量上限，默认 10
+```
+
+### 2.3 调用 kb-server 远程工具
+
+先通过 `gateway_list_tools` 确认远程知识库的实际工具名（前缀为 `kb-server_`），然后调用：
+
+```
+工具: kb-server_create_entry （实际名称以 gateway_list_tools 返回为准）
+参数:
+  title: 经验文档标题
+  content: 知识类内容
+  tags: ["经验沉淀", "相关技术领域"]
+  source: "knowledge-import"
+```
+
+> ⚠️ 远程知识库工具可能不支持 create 操作（测试阶段可能只读）。调用失败时记录警告，不影响整体导入流程。
+
+---
+
+## 3. 目录(catalog)说明
+
+本地知识库引擎支持以下目录：
+
+| 目录ID | 用途 | 适用场景 |
+|--------|------|----------|
+| `guides` | 指南文档 | 操作指南、使用教程 |
+| `references` | 参考文档 | API参考、技术规格 |
+| `best-practices` | 最佳实践 | 经验总结、最佳实践、踩坑记录 |
+| `faqs` | 常见问题 | FAQ、疑难解答 |
+| `releases` | 发布说明 | 版本发布、变更记录 |
+| `roadmap` | 路线图 | 规划、路线图 |
+
+知识导入默认使用 `best-practices`，因为经验沉淀本质是最佳实践。
+
+---
+
+## 4. 知识库内容结构化格式
+
+导入知识库的 content 必须按以下结构整理，禁止传入原始经验文档：
+
+```markdown
+# {经验标题}
+
+## {条目1标题}
+
+### 问题现象
+{描述遇到的具体问题、困惑或错误表现}
+
+### 解决方案
+{描述如何解决该问题，包括具体方法、命令、配置等}
+
+### 结果
+{描述解决后的效果、验证方式或可复用的结论}
+
+---
+
+## {条目2标题}
+
+### 问题现象
+...
+```
+
+**整理规则**：
+- 将原始文档中的"关键发现""踩坑记录""可复用建议"拆解为独立条目
+- 每个条目聚焦一个问题，按"问题现象 → 解决方案 → 结果"三段式重组
+- 去除与问题无直接关联的背景描述，保留可复用的核心信息
+- 多个独立问题用 `---` 分隔

package/vendor/Server/Skills/knowledge-import/references/SKILL_LOCATOR_GUIDE.md

@@ -1,91 +1,91 @@
-# SKILL 定位指南
-
-> 当经验条目没有关联的 skillDir 时，如何判断是否需要定位 SKILL 以及如何定位。
-
----
-
-## 1. 定位流程
-
-```
-Step 1: 检查知识条目的 skillDir 字段
-    ├── 非null → 直接使用该路径
-    └── null → 进入 Step 2
-
-Step 2: 检查经验内容是否显式提及SKILL
-    ├── 经验中直接提到SKILL名称或步骤名 → 进入 Step 3
-    └── 未显式提及 → 停止定位，所有内容归为知识类
-
-Step 3: 精确定位（非语义推断）
-    ├── 在经验内容中提取显式提及的SKILL名称 → 直接关联
-    ├── 提取显式提及的步骤名/流程环节 → 搜索包含该步骤的SKILL
-    └── 仍无法精确匹配 → 停止定位，内容归为知识类
-
-Step 4: 确认关联
-    ├── 精确匹配到 → 使用该SKILL目录
-    └── 未精确匹配到 → 不进行SKILL修改，内容归为知识类
-```
-
-> ⚠️ **核心原则**：SKILL定位基于**显式证据**（经验中明确提到的SKILL名/步骤名），而非主题相关性或语义推断。主题相关不等于流程缺陷。
-
----
-
-## 2. 显式提及的判断标准
-
-经验内容满足以下任一条件才算"显式提及SKILL"：
-
-| 判断条件 | 示例 | 说明 |
-|----------|------|------|
-| 直接提到SKILL的name | "TPCXTSCodeSkill应增加..." | 明确指向特定SKILL |
-| 直接提到SKILL的具体步骤 | "阶段零的探查步骤遗漏了..." | 指向特定流程环节 |
-| 直接提到SKILL的检查项 | "应增加对XX的检查" | 指向特定检查环节 |
-
-**不算显式提及的情况**（以下不触发SKILL定位）：
-- 经验提到某技术领域（如"测试""覆盖率"）但未指向具体SKILL
-- 经验提到某工具行为（如"devecocli docs search不稳定"）但未指向SKILL流程
-- 经验提到最佳实践（如"版本标注应同时..."）但未指向SKILL步骤缺陷
-
----
-
-## 3. 关键词提取（仅用于已确认需要定位时）
-
-当 Step 2 确认经验**显式提及了SKILL**后，提取关键词用于精确定位：
-
-### 3.1 从经验内容提取
-
-- 显式提到的SKILL名称（如 "TPCXTSCodeSkill"）
-- 显式提到的步骤名（如 "阶段零""步骤1"）
-- 显式提到的检查项或流程环节
-
-### 3.2 从 taskDescription 提取（辅助）
-
-- 原始任务描述中的操作动词和领域名词，用于辅助确认定位准确性
-
----
-
-## 4. 匹配规则
-
-### 4.1 精确名称匹配
-
-经验内容直接提及某个SKILL的name → 直接关联。
-
-### 4.2 步骤名匹配
-
-经验内容提及某个步骤名/流程环节 → 在所有SKILL中搜索包含该步骤的SKILL。
-
-> ⚠️ **禁止使用关键词重叠匹配**：即使经验关键词与某SKILL的description有大量重叠，只要经验未显式提及该SKILL的名称或步骤，就不进行关联。
-
----
-
-## 5. 现有SKILL分类参考
-
-| 分类 | SKILL | 典型关键词 |
-|------|-------|-----------|
-| task-planning | task-analysis, task-decomposition | 任务分析、拆解、验收标准 |
-| meta-skill | skill-generator, knowledge-import | SKILL生成、知识导入、自我迭代 |
-| 代码检视 | arkts-code-check, arkts-library-*-check | 代码质量、内存泄漏、稳定性、覆盖率 |
-| 原生库 Demo | arkts-library-demo-* | Demo代码、覆盖率、场景 |
-| 原生库 XTS | arkts-library-xts-* | XTS测试、用例、执行 |
-| 接口规范 | arkts-library-interface-spec | 接口提取、规格 |
-| 验收 | acceptance-check | 准出审核、验收测试 |
-
-> 此表仅用于辅助理解SKILL分类，**不用于语义推断关联**。定位仍以显式提及为前提。
+# SKILL 定位指南
+
+> 当经验条目没有关联的 skillDir 时，如何判断是否需要定位 SKILL 以及如何定位。
+
+---
+
+## 1. 定位流程
+
+```
+Step 1: 检查知识条目的 skillDir 字段
+    ├── 非null → 直接使用该路径
+    └── null → 进入 Step 2
+
+Step 2: 检查经验内容是否显式提及SKILL
+    ├── 经验中直接提到SKILL名称或步骤名 → 进入 Step 3
+    └── 未显式提及 → 停止定位，所有内容归为知识类
+
+Step 3: 精确定位（非语义推断）
+    ├── 在经验内容中提取显式提及的SKILL名称 → 直接关联
+    ├── 提取显式提及的步骤名/流程环节 → 搜索包含该步骤的SKILL
+    └── 仍无法精确匹配 → 停止定位，内容归为知识类
+
+Step 4: 确认关联
+    ├── 精确匹配到 → 使用该SKILL目录
+    └── 未精确匹配到 → 不进行SKILL修改，内容归为知识类
+```
+
+> ⚠️ **核心原则**：SKILL定位基于**显式证据**（经验中明确提到的SKILL名/步骤名），而非主题相关性或语义推断。主题相关不等于流程缺陷。
+
+---
+
+## 2. 显式提及的判断标准
+
+经验内容满足以下任一条件才算"显式提及SKILL"：
+
+| 判断条件 | 示例 | 说明 |
+|----------|------|------|
+| 直接提到SKILL的name | "TPCXTSCodeSkill应增加..." | 明确指向特定SKILL |
+| 直接提到SKILL的具体步骤 | "阶段零的探查步骤遗漏了..." | 指向特定流程环节 |
+| 直接提到SKILL的检查项 | "应增加对XX的检查" | 指向特定检查环节 |
+
+**不算显式提及的情况**（以下不触发SKILL定位）：
+- 经验提到某技术领域（如"测试""覆盖率"）但未指向具体SKILL
+- 经验提到某工具行为（如"devecocli docs search不稳定"）但未指向SKILL流程
+- 经验提到最佳实践（如"版本标注应同时..."）但未指向SKILL步骤缺陷
+
+---
+
+## 3. 关键词提取（仅用于已确认需要定位时）
+
+当 Step 2 确认经验**显式提及了SKILL**后，提取关键词用于精确定位：
+
+### 3.1 从经验内容提取
+
+- 显式提到的SKILL名称（如 "TPCXTSCodeSkill"）
+- 显式提到的步骤名（如 "阶段零""步骤1"）
+- 显式提到的检查项或流程环节
+
+### 3.2 从 taskDescription 提取（辅助）
+
+- 原始任务描述中的操作动词和领域名词，用于辅助确认定位准确性
+
+---
+
+## 4. 匹配规则
+
+### 4.1 精确名称匹配
+
+经验内容直接提及某个SKILL的name → 直接关联。
+
+### 4.2 步骤名匹配
+
+经验内容提及某个步骤名/流程环节 → 在所有SKILL中搜索包含该步骤的SKILL。
+
+> ⚠️ **禁止使用关键词重叠匹配**：即使经验关键词与某SKILL的description有大量重叠，只要经验未显式提及该SKILL的名称或步骤，就不进行关联。
+
+---
+
+## 5. 现有SKILL分类参考
+
+| 分类 | SKILL | 典型关键词 |
+|------|-------|-----------|
+| task-planning | task-analysis, task-decomposition | 任务分析、拆解、验收标准 |
+| meta-skill | skill-generator, knowledge-import | SKILL生成、知识导入、自我迭代 |
+| 代码检视 | arkts-code-check, arkts-library-*-check | 代码质量、内存泄漏、稳定性、覆盖率 |
+| 原生库 Demo | arkts-library-demo-* | Demo代码、覆盖率、场景 |
+| 原生库 XTS | arkts-library-xts-* | XTS测试、用例、执行 |
+| 接口规范 | arkts-library-interface-spec | 接口提取、规格 |
+| 验收 | acceptance-check | 准出审核、验收测试 |
+
+> 此表仅用于辅助理解SKILL分类，**不用于语义推断关联**。定位仍以显式提及为前提。