@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/arkts-library-documentation-quality-check/references/KB_QUERY_GUIDE.md

@@ -0,0 +1,108 @@
+# 知识库查询指南
+
+> 本文档说明在文档质量检视过程中，如何查询鸿蒙知识库补充检查标准，提升检视的准确性和完整性。
+
+---
+
+## 1. 何时查询知识库
+
+| 场景 | 是否查询 |
+|------|----------|
+| 通用文档格式规范（Markdown 语法） | ❌ 不需要 |
+| 鸿蒙 API 文档标准（@ohos.* 文档要求） | ✅ 需要 |
+| ArkTS JSDoc 注释规范 | ✅ 需要 |
+| 鸿蒙权限说明标准 | ✅ 需要 |
+| 鸿蒙化差异对比文档要求 | ✅ 需要 |
+| 鸿蒙设备兼容性说明 | ✅ 需要 |
+
+**判断原则**：当不确定鸿蒙特有的文档规范或最佳实践时，查询知识库。
+
+---
+
+## 2. 查询流程
+
+### 2.1 构建检索词
+
+从文档检视需求中提取关键词，组合检索词：
+
+**提取维度**：
+- 技术栈：ArkTS、OpenHarmony、HarmonyOS、ArkUI
+- 文档类型：API 文档、JSDoc、README、CHANGELOG
+- 鸿蒙专项：权限说明、差异对比、迁移指南、兼容性
+
+**组合示例**：
+```
+需求：检查鸿蒙化库的 @ohos.* API 文档完整性
+检索词：["@ohos 文档规范", "HarmonyOS API 文档要求", "ArkTS JSDoc 规范"]
+```
+
+### 2.2 调用知识库工具
+
+调用 `kb-server_` 前缀的知识检索工具（具体工具名通过 `gateway_list_tools` 获取，参见 [MCP 能力检索指南](MCP_TOOL_DISCOVERY.md)）。
+
+**调用策略**：
+- 一次查询一个关键词
+- 若返回不相关，调整关键词重试（最多3轮）
+- 记录查询过的关键词，避免重复
+
+### 2.3 结果处理
+
+对知识库返回的内容分类处理：
+
+| 内容类型 | 处理方式 | 放置位置 |
+|----------|----------|----------|
+| 文档检查清单 | 整合为检查项 | references/ 的检查文档 |
+| 代码注释规范示例 | 提取关键模式 | 评分时的参考标准 |
+| 鸿蒙文档最佳实践 | 精简引用 | SKILL.md body 对应 Phase |
+| 注意事项 | 精简引用 | SKILL.md body 或 references/ |
+| 常见文档缺失项 | 记录为检查项 | CHECK_DIMENSIONS.md 补充 |
+
+---
+
+## 3. 知识融合原则
+
+### 3.1 不照搬全文
+
+知识库返回的内容可能很长，**不要**完整复制到检视标准中。应：
+- 提取核心要点
+- 精简为 1-3 句话引用
+- 详细内容放入 references/，SKILL.md 中用链接引用
+
+### 3.2 标注来源
+
+在引用知识库内容时，标注来源：
+
+```markdown
+> 📖 来源：鸿蒙知识库，关键词"ArkTS 文档规范"
+```
+
+### 3.3 验证适用性
+
+知识库返回的内容需验证是否适用于文档检视场景：
+- API 版本是否匹配（API 12+ vs 更低版本）
+- 场景是否匹配（三方库文档 vs 系统应用文档）
+- 规范是否仍然有效
+
+---
+
+## 4. 常见文档检视知识库查询场景
+
+### 4.1 鸿蒙 JSDoc/TSDoc 规范
+
+检索词建议：
+- `ArkTS JSDoc 规范` — 注释格式要求
+- `@ohos API 文档要求` — 系统 API 文档标准
+- `ArkTS 注释最佳实践` — 注释编写指南
+
+### 4.2 鸿蒙权限文档
+
+检索词建议：
+- `HarmonyOS 权限说明` — 权限声明文档标准
+- `@ohos 权限列表` — 系统 API 权限映射
+
+### 4.3 鸿蒙化文档差异
+
+检索词建议：
+- `鸿蒙化适配文档` — 适配说明文档要求
+- `HarmonyOS 迁移指南` — 迁移文档标准
+- `OpenHarmony 兼容性说明` — 兼容性文档要求

package/vendor/Server/Skills/arkts-library-documentation-quality-check/references/MCP_TOOL_DISCOVERY.md

@@ -0,0 +1,124 @@
+# MCP 能力检索指南
+
+> 本文档说明在文档质量检视过程中，如何检索 MCP Gateway 中可复用的脚本工具和下游工具，避免重复造轮子。
+
+---
+
+## 1. MCP Gateway 架构概览
+
+MCP Gateway 位于 `3rdLibraryLoop/MCP/`，聚合三类工具：
+
+| 工具来源 | 命名前缀 | 注册方式 |
+|----------|----------|----------|
+| 脚本工具 | `script_` | 扫描 `MCP/scripts/` 目录，解析 `@tool` 注释 |
+| 下游工具 | `{serverName}_` | 连接下游 MCP Server，拉取工具列表 |
+| 内置工具 | `gateway_` | Gateway 自带管理工具 |
+
+---
+
+## 2. 检索工具列表
+
+### 2.1 调用 gateway_list_tools
+
+调用 MCP 工具 `gateway_list_tools` 获取所有已注册工具的完整列表。
+
+返回的工具对象包含：
+```json
+{
+  "name": "script_git操作",
+  "description": "[via scripts] 执行 Git 操作",
+  "inputSchema": { ... }
+}
+```
+
+### 2.2 分类筛选
+
+根据工具名前缀分类：
+
+- **脚本工具**：名称以 `script_` 开头 → 对应 `MCP/scripts/` 下的脚本
+- **知识库工具**：名称以 `kb-server_` 开头 → 鸿蒙知识库
+- **GitCode工具**：名称以 `gitcode_` 开头 → GitCode 平台操作
+- **内置工具**：名称以 `gateway_` 开头 → Gateway 管理功能
+
+---
+
+## 3. 文档检视相关脚本工具
+
+### 3.1 脚本头部注释约定
+
+脚本前20行必须包含 `@tool` 注释：
+
+```javascript
+#!/usr/bin/env node
+/**
+ * @tool {工具名}                        // 必填，工具名（中文可用）
+ * @description {描述}                    // 给AI的工具说明
+ * @param {参数名}: {类型} - {说明}       // 参数定义
+ */
+```
+
+> ⚠️ **脚本必须跨平台**：使用 Node.js（`.cjs`）或 Python（`.py`），禁止 Bash（`.sh`），确保 Windows/macOS 均可运行。
+
+### 3.2 参数传递方式
+
+Gateway 将参数序列化为 **JSON 字符串**，作为脚本**第一个命令行参数**传入：
+
+- node: `process.argv[2]` → `JSON.parse()` 解析
+- python: `sys.argv[1]` → `json.loads()` 解析
+
+### 3.3 文档检视可复用脚本
+
+| 工具名 | 脚本文件 | 能力 | 参数 |
+|--------|----------|------|------|
+| `script_git操作` | git 操作脚本 | 克隆仓库、读取文件 | `action`, `repo`, `path` |
+| `script_rn_scan_exports` | rn-scan-exports.cjs | 扫描RN三方库导出接口 | `dir`, `compare` |
+| `script_rn_extract_interfaces` | rn-extract-interfaces.cjs | 提取RN三方库接口信息 | `dir` |
+
+> 实际可用脚本以 `gateway_list_tools` 返回为准，此处为常见示例。
+
+### 3.4 创建新脚本
+
+若检视流程需要新的脚本能力（如自动统计 JSDoc 覆盖率）：
+
+1. 在 SKILL 的 `scripts/` 目录创建脚本（**必须跨平台**：Node.js `.cjs` 或 Python `.py`，禁止 `.sh`）
+2. 添加 `@tool` 头部注释
+3. 若需全局复用，复制到 `MCP/scripts/` 目录
+4. Gateway 热加载会自动注册（`hotReload: true`）
+
+---
+
+## 4. 下游工具详情
+
+### 4.1 kb-server（鸿蒙知识库）
+
+- **URL**: `https://mcp.huaness.tech/mcp`
+- **认证**: `Bearer test-secret`
+- **工具前缀**: `kb-server_`
+- **用途**: 鸿蒙/OpenHarmony/ArkTS 领域知识检索
+
+### 4.2 gitcode（GitCode MCP）
+
+- **URL**: `https://api.gitcode.com/mcp-server/v1/mcp`
+- **工具前缀**: `gitcode_`
+- **用途**: 仓库操作、PR管理、代码搜索
+
+---
+
+## 5. 在SKILL中引用MCP工具
+
+在检视流程中按以下方式引用：
+
+```markdown
+### 获取仓库信息
+
+调用 MCP 工具 `gitcode_获取仓库信息`，传入 `owner` 和 `repo` 参数。
+
+### 查询鸿蒙知识
+
+调用 MCP 工具 `kb-server_知识检索`，传入关键词查询。
+```
+
+引用要点：
+- 使用完整工具名（含前缀）
+- 说明调用参数
+- 说明返回数据的用途

package/vendor/Server/Skills/arkts-library-documentation-quality-check/references/REPORT_TEMPLATE.md

@@ -0,0 +1,90 @@
+# 文档质量检视报告模板
+
+本文件定义 `文档质量检视报告.md` 的标准格式和关键格式要求。
+
+---
+
+## 一、报告结构
+
+```markdown
+# {repoName} 文档质量检视报告
+
+## 一、检视概览
+
+| 字段 | 内容 |
+|------|------|
+| **仓库名称** | {repoName} |
+| **检视类型** | ArkTS 文档质量检视 |
+| **检视时间** | {timestamp} |
+| **扫描文档数** | {docCount} |
+| **扫描源码文件数** | {sourceFileCount} |
+
+## 二、综合评分
+
+**综合评分：{score}/100**
+
+> 评分等级：{grade}（{gradeDescription}）
+
+## 三、维度评分明细
+
+| 维度 | 子评分 | 权重 | 加权贡献 | Critical数 | Major数 | Minor数 |
+|------|--------|------|----------|-----------|---------|---------|
+| 文档完整性 | {完整性子评分}/100 | 30% | {完整性贡献} | {c1} | {m1} | {n1} |
+| 文档准确性 | {准确性子评分}/100 | 25% | {准确性贡献} | {c2} | {m2} | {n2} |
+| 文档易读性 | {易读性子评分}/100 | 15% | {易读性贡献} | {c3} | {m3} | {n3} |
+| 代码级文档质量 | {代码级子评分}/100 | 10% | {代码级贡献} | {c4} | {m4} | {n4} |
+| 鸿蒙化文档专项 | {鸿蒙化子评分}/100 | 20% | {鸿蒙化贡献} | {c5} | {m5} | {n5} |
+
+## 四、检视维度详情
+
+### 4.1 文档完整性（权重 30%）
+
+| 检查项 | 严重度 | 发现数量 | 详情 |
+|--------|--------|----------|------|
+
+> 完整性子评分：{完整性子评分}/100
+
+### 4.2 文档准确性（权重 25%）
+
+> 准确性子评分：{准确性子评分}/100
+
+### 4.3 文档易读性（权重 15%）
+
+> 易读性子评分：{易读性子评分}/100
+
+### 4.4 代码级文档质量（权重 10%）
+
+> 代码级文档子评分：{代码级子评分}/100
+
+### 4.5 鸿蒙化文档专项（权重 20%）
+
+> 鸿蒙化专项子评分：{鸿蒙化子评分}/100
+
+## 五、问题清单
+
+| # | 文档/文件 | 严重度 | 维度 | 描述 | 修复建议 |
+|---|-----------|--------|------|------|----------|
+
+## 六、改进建议
+
+……
+
+---
+
+**报告生成时间**：{timestamp}
+```
+
+---
+
+## 二、关键格式要求
+
+> ⚠️ 以下格式要求必须严格遵守，后端 `_parseArktsLibraryScore` 依赖自动解析。
+
+1. **综合评分行格式**：`**综合评分：数字/100**`
+   - 数字为 0-100 的整数
+   - 冒号使用**中文全角冒号** `：`
+   - 必须出现在"二、综合评分"章节的首行
+
+2. **维度评分明细表**：必须在综合评分之后紧邻展示
+
+3. **各维度子评分标注**：每个维度详情末尾必须标注 `> {维度}子评分：{分数}/100`

package/vendor/Server/Skills/arkts-library-documentation-quality-check/references/SCORING_FORMULA.md

@@ -0,0 +1,57 @@
+# 评分公式与等级标准
+
+本文件定义文档质量检视的评分计算公式、严苛扣分保障和等级标准。
+
+---
+
+## 一、各维度子评分计算
+
+每个维度独立计算子评分（0-100）：
+
+```
+维度子评分 = max(0, 100 - 该维度 Critical扣分 - 该维度 Major扣分 - 该维度 Minor扣分)
+
+各级别扣分标准（同一维度内叠加）：
+- Critical 级别：每项 -15 分
+- Major 级别：每项 -8 分
+- Minor 级别：每项 -3 分
+```
+
+---
+
+## 二、综合评分计算
+
+```
+综合评分 = max(0, round(
+  完整性子评分 × 0.30 +
+  准确性子评分 × 0.25 +
+  易读性子评分 × 0.15 +
+  代码级文档子评分 × 0.10 +
+  鸿蒙化专项子评分 × 0.20
+))
+```
+
+---
+
+## 三、严苛扣分上限保障
+
+为防止极端情况下评分虚高，设置总体扣分下限：
+
+```
+总扣分 = 100 - 综合评分
+若存在 ≥3 个 Critical 问题，总扣分最低为 40 分（综合评分最高 60）
+若存在 ≥1 个 Critical 且 ≥5 个 Major，总扣分最低为 50 分（综合评分最高 50）
+```
+
+---
+
+## 四、评分等级标准
+
+| 评分区间 | 等级 | 含义 |
+|----------|------|------|
+| 90-100 | 优秀 | 文档完善、准确、易读，鸿蒙化说明充分 |
+| 80-89 | 良好 | 存在少量 Minor 问题，不影响使用 |
+| 70-79 | 一般 | 存在 Major 级别文档缺失，需补充 |
+| 60-69 | 较差 | 关键文档缺失或不准确，严重影响使用 |
+| 50-59 | 不合格 | Critical 级别文档缺失，用户无法正常使用 |
+| <50 | 严重不足 | 多维度 Critical 问题，文档基本不可用 |

package/vendor/Server/Skills/arkts-library-documentation-quality-check/scripts/validate-skill.cjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * @tool validate-skill
+ * @description 校验SKILL目录是否符合Agent Skills规范，检查frontmatter、结构、渐进式披露。跨平台（Windows/macOS/Linux），仅需 Node.js。
+ * @param skillDir: string - SKILL目录绝对路径
+ * @hidden
+ * validate-skill.cjs
+ *
+ * 用法:
+ *   # CLI 模式
+ *   node validate-skill.cjs /path/to/skill
+ *
+ *   # MCP Gateway 模式（第一个参数为 JSON 字符串）
+ *   node validate-skill.cjs '{"skillDir":"/path/to/skill"}'
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ── 参数解析（兼容 MCP Gateway JSON 模式与 CLI 模式） ──────
+
+function parseArgs(argv) {
+  if (argv.length === 0) return {};
+  const first = argv[0];
+  if (typeof first === 'string' && first.startsWith('{')) {
+    try { return JSON.parse(first); } catch (e) { return {}; }
+  }
+  return { skillDir: first };
+}
+
+// ── 输出统计 ─────────────────────────────────────────────
+
+let PASS = 0;
+let FAIL = 0;
+let WARNINGS = 0;
+
+function checkPass(msg) { console.log(`  ✅ ${msg}`); PASS += 1; }
+function checkFail(msg) { console.log(`  ❌ ${msg}`); FAIL += 1; }
+function checkWarn(msg) { console.log(`  ⚠️  ${msg}`); WARNINGS += 1; }
+
+// ── Frontmatter 解析 ─────────────────────────────────────
+
+/**
+ * 解析 SKILL.md 的 frontmatter 与 body。
+ * 返回 { frontmatter: object|null, bodyLines: string[] }
+ */
+function parseFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (!lines[0] || lines[0].trim() !== '---') {
+    return { frontmatter: null, bodyLines: lines };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) {
+    return { frontmatter: null, bodyLines: lines };
+  }
+  const fmLines = lines.slice(1, end);
+  const fm = {};
+  let currentKey = null;
+  for (const line of fmLines) {
+    const m = line.match(/^([a-zA-Z_][\w-]*):\s*(.*)$/);
+    if (m) {
+      currentKey = m[1];
+      fm[currentKey] = m[2].trim();
+    } else if (currentKey && /^\s+\S/.test(line)) {
+      fm[currentKey] += '\n' + line.trim();
+    }
+  }
+  return { frontmatter: fm, bodyLines: lines.slice(end + 1) };
+}
+
+// ── 主流程 ───────────────────────────────────────────────
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const skillDir = args.skillDir || '';
+
+  if (!skillDir) {
+    console.log('Usage: node validate-skill.cjs <skillDir>');
+    console.log('Error: skillDir parameter is required');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(skillDir) || !fs.statSync(skillDir).isDirectory()) {
+    console.log(`Error: Directory does not exist: ${skillDir}`);
+    process.exit(1);
+  }
+
+  console.log('=== SKILL 规范校验 ===');
+  console.log(`目录: ${skillDir}`);
+  console.log('');
+
+  // ─── 1. SKILL.md 存在性 ───
+  console.log('--- 1. 文件结构检查 ---');
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  if (fs.existsSync(skillFile) && fs.statSync(skillFile).isFile()) {
+    checkPass('SKILL.md 存在');
+  } else {
+    checkFail('SKILL.md 不存在');
+    console.log('无法继续校验，SKILL.md 是必需文件');
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(skillFile, 'utf-8');
+  const { frontmatter, bodyLines } = parseFrontmatter(content);
+
+  // ─── 2. Frontmatter 检查 ───
+  console.log('');
+  console.log('--- 2. Frontmatter 检查 ---');
+
+  if (frontmatter) {
+    checkPass('YAML frontmatter 存在');
+  } else {
+    checkFail('缺少 YAML frontmatter（文件应以 --- 开头并以 --- 结束头部）');
+  }
+
+  const nameField = frontmatter ? String(frontmatter.name || '') : '';
+  if (nameField) {
+    checkPass(`name 字段存在: ${nameField}`);
+
+    // name 字符集校验
+    if (/^[a-z0-9]+(-[a-z0-9]+)*$/.test(nameField)) {
+      checkPass('name 字符集合规（仅小写字母/数字/连字符）');
+    } else {
+      checkFail('name 字符集不合规：应仅含 a-z/0-9/-，不能首尾连字符或连续连字符');
+    }
+
+    // name 长度校验
+    const nameLen = nameField.length;
+    if (nameLen >= 1 && nameLen <= 64) {
+      checkPass(`name 长度合规 (${nameLen} 字符)`);
+    } else {
+      checkFail(`name 长度不合规：应在 1-64 字符之间（当前 ${nameLen}）`);
+    }
+
+    // name 匹配目录名
+    const dirName = path.basename(path.resolve(skillDir));
+    if (nameField === dirName) {
+      checkPass(`name 匹配父目录名 (${dirName})`);
+    } else {
+      checkFail(`name 不匹配父目录名：name='${nameField}' vs 目录='${dirName}'`);
+    }
+  } else {
+    checkFail('name 字段缺失');
+  }
+
+  const descField = frontmatter ? String(frontmatter.description || '') : '';
+  if (descField) {
+    const descLen = descField.length;
+    if (descLen <= 1024) {
+      checkPass(`description 长度合规 (${descLen} 字符)`);
+    } else {
+      checkFail(`description 过长：应 ≤1024 字符（当前 ${descLen}）`);
+    }
+  } else {
+    checkFail('description 字段缺失或为空');
+  }
+
+  if (frontmatter && frontmatter.license) {
+    checkPass('license 字段存在');
+  } else {
+    checkWarn('license 字段缺失（推荐添加）');
+  }
+
+  if (frontmatter && frontmatter.metadata) {
+    checkPass('metadata 字段存在');
+  } else {
+    checkWarn('metadata 字段缺失（推荐添加 author/version）');
+  }
+
+  // ─── 3. Body 检查 ───
+  console.log('');
+  console.log('--- 3. Body 内容检查 ---');
+
+  const bodyLineCount = bodyLines.length;
+  if (bodyLineCount <= 500) {
+    checkPass(`body 行数合规 (${bodyLineCount} 行, ≤500)`);
+  } else {
+    checkWarn(`body 行数较多 (${bodyLineCount} 行，推荐 < 500，考虑拆分到 references/)`);
+  }
+
+  if (/任务参数|## .*参数|\|\s*参数/.test(content)) {
+    checkPass('包含任务参数说明');
+  } else {
+    checkWarn('未找到任务参数表（推荐添加）');
+  }
+
+  if (/工作流程|Phase|## Phase/.test(content)) {
+    checkPass('包含工作流程概览');
+  } else {
+    checkWarn('未找到工作流程概览（推荐添加）');
+  }
+
+  // ─── 4. 渐进式披露检查 ───
+  console.log('');
+  console.log('--- 4. 渐进式披露检查 ---');
+
+  const refsDir = path.join(skillDir, 'references');
+  if (fs.existsSync(refsDir) && fs.statSync(refsDir).isDirectory()) {
+    const refFiles = fs.readdirSync(refsDir)
+      .filter((f) => f.endsWith('.md') && fs.statSync(path.join(refsDir, f)).isFile());
+    checkPass(`references/ 目录存在 (${refFiles.length} 个文档)`);
+
+    // 检查引用深度（一层）
+    const nestedDirs = fs.readdirSync(refsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory()).length;
+    if (nestedDirs === 0) {
+      checkPass('references 保持一层深度');
+    } else {
+      checkFail(`references 存在嵌套子目录 (${nestedDirs} 个)，应保持一层深度`);
+    }
+  } else {
+    checkWarn('无 references/ 目录（详细内容建议拆分到此目录）');
+  }
+
+  const assetsDir = path.join(skillDir, 'assets');
+  if (fs.existsSync(assetsDir) && fs.statSync(assetsDir).isDirectory()) {
+    checkPass('assets/ 目录存在');
+  } else {
+    checkWarn('无 assets/ 目录（如需模板/资源可添加）');
+  }
+
+  const scriptsDir = path.join(skillDir, 'scripts');
+  if (fs.existsSync(scriptsDir) && fs.statSync(scriptsDir).isDirectory()) {
+    checkPass('scripts/ 目录存在');
+  } else {
+    checkWarn('无 scripts/ 目录（如需可执行脚本可添加）');
+  }
+
+  // 检查文件引用使用相对路径
+  const absRefs = (content.match(/\]\(\/[^)]+\)/g) || []).length;
+  if (absRefs === 0) {
+    checkPass('文件引用使用相对路径');
+  } else {
+    checkFail(`发现 ${absRefs} 个绝对路径引用，应使用相对路径`);
+  }
+
+  // ─── 5. 总结 ───
+  console.log('');
+  console.log('=== 校验总结 ===');
+  console.log(`  ✅ 通过: ${PASS}`);
+  console.log(`  ❌ 失败: ${FAIL}`);
+  console.log(`  ⚠️  警告: ${WARNINGS}`);
+  console.log('');
+
+  if (FAIL === 0) {
+    console.log('ALL CHECKS PASSED');
+    process.exit(0);
+  } else {
+    console.log(`VALIDATION FAILED: ${FAIL} 个必须修复的问题`);
+    process.exit(1);
+  }
+}
+
+main();