@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/arkts-library-demo-scenario/references/TEMPLATE.md

@@ -0,0 +1,185 @@
+# 测试 Demo 描述文档模板
+
+本文件提供生成输出文档时使用的标准模板结构，可直接复制并填入真实内容。
+
+---
+
+## 输出文档模板
+
+```markdown
+# {库名} 测试 Demo 描述文档
+
+## 概述
+
+本文档基于 `{库名}` 库的接口规格说明文档（`{规格文档文件名}`）自动生成，
+提供各接口的 ArkTS 测试 Demo 描述，供开发者参考实现功能验证 Demo 页面。
+
+> 文档基于接口规格文档真实内容生成，所有接口名称、参数类型与规格文档保持一致。
+
+## Demo 总览
+
+| Demo 数量 | 覆盖接口数量 | 生成日期 |
+|----------|------------|---------|
+| {N} 个    | {M} 个      | {YYYY-MM-DD} |
+
+## 测试 Demo 描述列表
+
+| 序号 | 测试 Demo 名称 | 测试 Demo 描述 | 测试 Demo 步骤 | 测试 Demo 预期结果 | 对应函数接口 |
+|-----|--------------|--------------|--------------|-----------------|------------|
+| 1 | {Demo名称1} | {Demo描述1} | {步骤1} | {预期结果1} | {接口列表1} |
+| 2 | {Demo名称2} | {Demo描述2} | {步骤2} | {预期结果2} | {接口列表2} |
+
+## 接口覆盖矩阵
+
+| 序号 | 接口名称 | 所在 Demo | 覆盖状态 |
+|-----|---------|----------|---------|
+| 1 | `{接口签名}` | {Demo名称} | ✅ 已覆盖 |
+```
+
+---
+
+## 各字段填写规范
+
+### 测试 Demo 名称
+
+**格式**：`[功能动词/名词][操作对象][可选场景描述]Demo`
+
+**命名示例：**
+
+| 场景 | 推荐名称 |
+|-----|---------|
+| 单一核心功能 | `图片压缩处理Demo` |
+| 生命周期管理 | `实例创建与销毁Demo` |
+| 配置类接口 | `参数配置与验证Demo` |
+| 异步操作 | `异步数据加载Demo` |
+| 错误处理 | `异常捕获与恢复Demo` |
+| 多接口组合 | `完整处理流程Demo` |
+
+**注意：**
+- 不超过 20 字
+- 避免使用泛化词语（如"基础Demo"、"测试Demo"）
+- 名称应能让开发者直接判断 Demo 的核心目的
+
+---
+
+### 测试 Demo 描述
+
+**模板：**
+
+```
+{Demo名称}展示了如何使用 {接口名称} 实现 {功能描述}。
+通过本 Demo，开发者可以了解 {接口的核心用法/参数含义/返回值处理方式}。
+[可选：本 Demo 同时涵盖 {其他关联接口}，展示 {它们之间的调用关系/业务场景}。]
+```
+
+**示例：**
+
+```
+"本 Demo 展示 BlurManager 的完整生命周期管理流程，包括构造（传入 radius 参数）、
+动态更新 radius 属性（setRadius/getRadius 读写）及最终资源释放（release）。
+帮助开发者理解 BlurManager 实例从创建到销毁的正确使用方式，以及 radius 属性的读写一致性。"
+```
+
+---
+
+### 测试 Demo 步骤
+
+**步骤结构模板：**
+
+```
+1. 创建 Demo 页面，添加 [UI组件列表：按钮、输入框、展示区、日志区等]。
+2. [用户操作]，触发 `{接口名称}({参数示例})` 调用。
+3. 将接口返回值 / 状态变化展示在 [展示区域名称]。
+4. [下一步操作，如有]，验证 [具体行为]。
+[可选] 5. 对比 / 补充验证步骤。
+```
+
+**步骤描述规范：**
+
+| 维度 | 要求 | 示例 |
+|-----|-----|-----|
+| 页面构建 | 说明需要哪些 UI 组件 | "添加 radius 输入框、'执行'按钮和图片显示区域" |
+| 交互触发 | 明确用户操作和调用时机 | "点击'执行'按钮，调用 `blur(pixelMap)`" |
+| 参数传递 | 说明传入参数来源/示例值 | "传入 radius=15，pixelMap 为图库选取的图片" |
+| 结果展示 | 说明如何在页面显示结果 | "将返回的 PixelMap 显示在结果区域" |
+| 验证方式 | 说明如何判断成功 | "确认图片宽高与原图一致，视觉出现模糊效果" |
+
+---
+
+### 测试 Demo 预期结果
+
+**模板：**
+
+```
+1. [页面/UI 状态]：{可观测的界面变化描述}。
+2. [接口返回值]：{返回值类型/内容/范围} 符合预期。
+3. [功能效果]：{功能方面的可验证效果}。
+4. [异常/边界]：{无异常抛出 / 错误码正确返回}。
+[可选] 5. [性能]：{操作耗时在合理范围内}。
+```
+
+**预期结果描述规范：**
+- 必须可观测（能在 Demo 页面上直接看到或测量）
+- 必须具体（避免"正确返回"这样的模糊描述）
+- 推荐包含数值范围（如尺寸不变、耗时 < N秒）
+- 必须包含"无异常/无崩溃"验证项
+
+**示例：**
+
+```
+1. 点击"执行异步模糊"后，按钮立即变为禁用状态，Loading 指示器出现，表明异步任务已启动。
+2. `blur()` 返回的 Promise 正常 resolve，Loading 消失，模糊后图片正确显示在结果区域。
+3. 模糊后图片的宽高像素数与原图完全一致，视觉效果出现模糊。
+4. UI 主线程在等待期间不冻结（可正常操作页面其他控件）。
+5. 无 Promise reject 或未捕获异常；页面日志显示耗时。
+```
+
+---
+
+### 对应函数接口
+
+**格式**：每行一个接口，使用代码格式（反引号），包含完整函数签名。
+
+```
+`functionName(paramName: ParamType): ReturnType`
+`ClassName.methodName(param: Type): ReturnType`
+`new ClassName(param: Type)`
+`CONSTANT_NAME: Type`（常量）
+`InterfaceName`（接口类型，仅被其他接口用作参数/返回值时列出）
+```
+
+---
+
+## 接口分组决策树
+
+使用以下决策树判断接口是否应合并到同一 Demo：
+
+```
+接口 A 和接口 B 是否应合并？
+│
+├─ A 的返回值是 B 的入参？ ──→ 是 ──→ 合并
+│
+├─ A 和 B 共同完成一个完整业务场景？ ──→ 是 ──→ 合并
+│   （如: init + execute + cleanup）
+│
+├─ A 和 B 都属于同一对象的状态读写？ ──→ 是 ──→ 合并
+│   （如: setter + getter）
+│
+├─ A 不调用 B，B 不调用 A，功能方向不同？ ──→ 是 ──→ 分开
+│
+└─ 默认：分开（每个接口独立 Demo）
+```
+
+---
+
+## 常见接口模式与推荐 Demo 封装方式
+
+| 接口模式 | 推荐 Demo 封装 |
+|---------|--------------|
+| `constructor + method + release` | 封装为"完整生命周期 Demo" |
+| `async` 方法（返回 Promise） | 独立 Demo，展示异步等待与结果处理 |
+| `sync` 方法 | 独立 Demo，或与对应 async 方法对比展示 |
+| `getter + setter` 一对 | 合并为"属性读写 Demo" |
+| `init + execute` 依赖链 | 合并为"初始化与执行 Demo" |
+| 多个枚举值影响同一方法行为 | 在同一 Demo 中用选择器切换枚举值展示 |
+| 错误码返回的接口 | 在对应 Demo 中增加"异常输入"验证步骤 |

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

@@ -0,0 +1,234 @@
+---
+name: arkts-library-documentation-quality-check
+description: 对已鸿蒙化的 ArkTS 库进行文档质量检视，覆盖完整性、准确性、易读性、代码级文档（JSDoc/TSDoc）和鸿蒙化专项五个维度，生成评分报告（0-100分）。作为 ArkTS 仓库检视流程的第五阶段使用，当需要审计鸿蒙化库的 README/API 文档质量或评估发版前文档覆盖率时使用。
+license: Apache-2.0
+compatibility: Requires access to Git repos and ability to read Markdown, ETS, TS, and JSON5 files
+metadata:
+  version: "1.0.0"
+  category: harmonyos-development
+---
+
+# ArkTS 库文档质量检视技能
+
+对**已鸿蒙化的 ArkTS 库**的文档质量进行检视，评估文档的完整性、准确性、易读性、代码级文档质量和鸿蒙化说明的充分性。
+
+> ⚠️ **核心定位**：检视鸿蒙化库的**所有文档**，包括 README、API 文档、使用指南、CHANGELOG、代码内 JSDoc/TSDoc 注释等。文档质量直接影响库的可采纳性，缺失或不准确的文档等同于功能缺失。
+
+---
+
+## 任务参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `repoUrl` | ✅ | Git 仓库地址 |
+| `outputDir` | ✅ | 输出目录绝对路径 |
+| `repoName` | ✅ | 仓库名称 |
+
+---
+
+## 输入依赖
+
+- **前置 SKILL**: `arkts-library-interface-spec`（生成接口规格说明）
+- **输入文件**: `接口规格说明.md`（位于 `outputDir`，提供公开接口列表）
+- **仓库源码**: 已克隆到 `{outputDir}/source/`
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 文档范围识别（目录探测 → 全量扫描 → 鸿蒙化说明定位 → 文档分类映射）
+    ↓
+Phase 2: 逐文档五维度质量分析（完整性/准确性/易读性/代码级/鸿蒙化）
+    ↓
+Phase 3: 文档质量评分计算（维度加权 + 分级扣分 + 严苛保障）
+    ↓
+Phase 4: 报告生成（综合评分 + 问题清单 + 修复建议）
+    ↓
+Phase 5: 合规性自检（对照检查清单 + 校验脚本）
+```
+
+---
+
+## Phase 1：文档范围识别
+
+### 1.1 目录结构探测
+
+先探明仓库的目录布局，为后续智能查找提供依据：
+
+```bash
+# 查看顶层目录结构
+find {{outputDir}}/source -maxdepth 1 -type d | sort
+
+# 查看前两层目录结构（识别文档目录、鸿蒙化目录、源码目录的位置）
+find {{outputDir}}/source -maxdepth 2 -type d | sort
+```
+
+> `workdir: "{{outputDir}}"`
+
+根据目录结构，智能识别以下关键目录的**实际位置**：
+
+| 目录类型 | 常见名称候选 | 识别策略 |
+|----------|-------------|----------|
+| 文档目录 | `docs/`、`doc/`、`documentation/`、`api/`、`wiki/`、`guides/` | 优先选择含最多 .md 文件的目录；若无独立目录则文档在项目根 |
+| 鸿蒙化目录 | `ohos/`、`harmony/`、`harmonyos/`、`openharmony/`、`ohosmodule/` | 含 oh-package.json5 或 ETS 源码的目录 |
+| 源码目录 | `src/`、`entry/src/`、`src/main/ets/`、`src/main/ts/`、`lib/` | 含 .ets/.ts 且有 index.ets/index.ts 的目录 |
+| 示例工程 | `example/`、`demo/`、`sample/`、`samples/`、`Entry/` | 含独立 oh-package.json5 的可运行工程 |
+
+### 1.2 全量文件扫描
+
+基于 1.1 的探测结果，扫描所有文档和源码文件：
+
+```bash
+# 文档文件（全量递归，不受目录层级限制）
+find {{outputDir}}/source -type f \( -name "README*" -o -name "*.md" -o -name "*.txt" -o -name "*.rst" -o -name "CHANGELOG*" -o -name "*.json5" \)
+
+# 源码文件（用于 JSDoc/TSDoc 检查和文档-代码一致性验证）
+find {{outputDir}}/source -type f \( -name "*.ets" -o -name "*.ts" \)
+```
+
+### 1.3 鸿蒙化说明定位
+
+鸿蒙化说明文档位置高度不固定，按以下优先级依次查找：
+
+```bash
+# 优先级 1：独立鸿蒙化 README（常见于 CPF 仓库）
+find {{outputDir}}/source -maxdepth 1 -type f \( -name "README.OpenHarmony*" -o -name "README_OpenHarmony*" -o -name "README.Harmony*" -o -name "README_Harmony*" -o -name "README.ohos*" \)
+
+# 优先级 2：鸿蒙化子目录中的 README
+find {{outputDir}}/source -type f -path "*/ohos/README*" -o -path "*/harmony/README*" -o -path "*/harmonyos/README*" -o -path "*/openharmony/README*"
+
+# 优先级 3：主 README 中的鸿蒙化章节（最后手段）
+# 检查 README.md / README_zh.md 中是否包含 "鸿蒙"/"HarmonyOS"/"OpenHarmony" 等关键词的章节
+grep -n -i -E '(鸿蒙|harmony|openharmony|ohos)' {{outputDir}}/source/README*.md 2>/dev/null | head -30
+```
+
+**判定规则**：取优先级最高的匹配结果作为鸿蒙化说明文档。若多个位置均存在，则全部纳入检视范围。
+
+### 1.4 文档分类映射
+
+将扫描到的文件按类别归类（不假设固定路径，依据文件名模式和内容特征判断）：
+
+| 类别 | 识别模式 | 说明 |
+|------|----------|------|
+| 入口文档 | 文件名匹配 `README*` | 项目概览与入门；注意可能有多语言版本 |
+| API 文档 | 位于文档目录下的 `.md` 文件，或文件名含 `api`/`interface`/`reference` | 公开接口说明；可能散布在多个目录 |
+| 鸿蒙化说明 | 1.3 定位到的文件 | 鸿蒙适配说明；位置不固定，必须通过 1.3 专门定位 |
+| 构建配置 | 文件名匹配 `oh-package.json5` / `build-profile.json5` / `hvigorfile.ts` | 依赖与构建说明；可在多级子目录 |
+| 导出声明 | 文件名 `index.ets` / `index.ts`（排除 node_modules） | 模块导出文档；需识别实际导出入口 |
+| 示例工程 | 含独立 `oh-package.json5` 的 example/demo/sample 目录 | 可运行示例；验证示例代码可运行性 |
+| 代码注释 | `*.ets` / `*.ts` 中 JSDoc/TSDoc | 代码级文档；需过滤掉 node_modules 和第三方依赖 |
+
+同时读取 `接口规格说明.md`，提取所有公开接口列表，用于评估文档覆盖率。
+
+> 文档分类的完整检查清单参见 [参考文档](references/CHECK_DIMENSIONS.md)
+
+### Phase 2：逐文档质量分析
+
+对每个文档和源码文件进行**五维度**质量检视。各维度的完整检查项和判定标准参见 [references/CHECK_DIMENSIONS.md](references/CHECK_DIMENSIONS.md)（按需加载）。
+
+| 维度 | 权重 | 核心关注 |
+|------|------|----------|
+| 文档完整性 | 30% | 关键文档是否缺失（README、鸿蒙化说明、API 文档、示例代码） |
+| 文档准确性 | 25% | 文档描述与代码实现是否一致（API 签名、示例代码可运行性） |
+| 文档易读性 | 15% | 结构、格式、语言是否规范 |
+| 代码级文档质量 | 10% | JSDoc/TSDoc 注释是否完善 |
+| 鸿蒙化文档专项 | 20% | 权限说明、差异对比、迁移指南、兼容性说明 |
+
+**执行要点**：
+- 对照 `接口规格说明.md` 的公开接口列表，逐个检查是否有文档覆盖
+- 示例代码必须检查可运行性（导入路径、API 签名、异步处理）
+- JSDoc 检查重点：导出函数/类是否有注释、参数/返回值是否描述、@ohos.* API 是否标注权限/版本
+- 鸿蒙化专项重点：权限说明（Critical）、差异对比、迁移指南、兼容性范围
+
+> 如需查询鸿蒙知识库补充检查标准，参见 [知识库查询指南](references/KB_QUERY_GUIDE.md)
+
+### Phase 3：文档质量评分计算
+
+基于检视结果进行**严苛评分**（0-100分），采用维度加权 + 分级扣分机制。评分公式和等级标准参见 [references/SCORING_FORMULA.md](references/SCORING_FORMULA.md)（按需加载）。
+
+**快速参考**：
+
+```
+维度子评分 = max(0, 100 - Critical×15 - Major×8 - Minor×3)
+
+综合评分 = max(0, round(
+  完整性×0.30 + 准确性×0.25 + 易读性×0.15 + 代码级×0.10 + 鸿蒙化×0.20
+))
+
+严苛保障：≥3个Critical → 最高60分；≥1 Critical + ≥5 Major → 最高50分
+```
+
+### Phase 4：报告生成
+
+在 `{outputDir}` 下生成 `文档质量检视报告.md`。报告模板参见 [assets/REPORT_TEMPLATE.md](assets/REPORT_TEMPLATE.md)，格式要求参见 [references/REPORT_TEMPLATE.md](references/REPORT_TEMPLATE.md)（按需加载）。
+
+**关键格式要求**（后端自动解析依赖）：
+
+1. 综合评分行格式：`**综合评分：数字/100**`（中文全角冒号 `：`）
+2. 维度评分明细表紧随综合评分之后
+3. 各维度详情末尾标注子评分
+
+### Phase 5：合规性自检
+
+报告生成后，对照 [references/COMPLIANCE_CHECKLIST.md](references/COMPLIANCE_CHECKLIST.md) 执行自检，确认：
+
+- 五维度检视完整（无遗漏维度）
+- 评分计算正确（维度加权 + 严苛保障）
+- 报告格式合规（后端可自动解析）
+
+可运行校验脚本进行自动化检查（跨平台，仅需 Node.js）：
+
+```bash
+node {skillDir}/scripts/validate-skill.cjs {skillDir}
+```
+
+---
+
+## 输出产物
+
+| 产物 | 文件名 | 说明 |
+|------|--------|------|
+| 文档质量检视报告 | `文档质量检视报告.md` | 综合评分 + 维度子评分 + 问题清单 + 修复建议 |
+
+所有产物写入 `{outputDir}` 目录。
+
+> ⚠️ **输出文件自检**：写入结果文件前，先确认 `文档质量检视报告.md` 已存在且内容完整（**独立文件，禁止只写入 result 执行结果文件**）。若报告内容仅在草稿中，必须先将其保存为上述独立文件。
+
+### 结构化指标输出（必须执行）
+
+执行环境会在任务 prompt 中下发一个**结构化指标文件输出路径**（`stepId{X}_loop{L}_meta_{N}.json`）。
+检视完成后，**必须**将最终评分以下述 JSON 对象写入该路径：
+
+```json
+{
+  "documentationScore": 85,
+  "scoreReason": "README缺失鸿蒙化说明-15等（一句话判定依据，≤50字；触发严苛保障时必须注明）"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `documentationScore` | number | 文档质量评分（0-100 整数，与报告中 `**综合评分：XX/100**` 的数值一致） |
+| `scoreReason` | string | 评分判定依据摘要（可选，前端悬浮提示展示；0 分时强烈建议写明触发的严苛保障规则） |
+
+**说明**：该文件由执行框架自动收割入库（前端/历史列表直接读取评分，无需解析报告文本）。若 prompt 未下发该路径则跳过本节。
+
+---
+
+## 常见陷阱
+
+- **示例代码可运行性**：导入路径错误（`import lottie from` vs `import { lottie } from`）是最常见的 Critical 问题
+- **权限说明遗漏**：使用 @ohos.network 等系统 API 但未在文档中说明权限要求
+- **文档-代码不一致**：README 描述的参数类型/返回值与源码实际签名不匹配
+- **双 README 不同步**：README_zh.md 与 README.md 内容差异，需双向检查
+- **隐含行为未文档化**：生命周期方法中的自动 API 调用（如 `aboutToDisappear` 调用 `destroy()`）容易遗漏
+- **oh-package.json5 不是严格 JSON**：允许注释和尾逗号，不能按 JSON 解析
+- **鸿蒙化文档位置不固定**：不要假设鸿蒙化说明在 `ohos/` 或 `harmony/` 下，必须通过 Phase 1 1.3 的三级优先级搜索定位；CPF 仓库常在项目根目录放 `README.OpenHarmony.md`，Gitee 仓库常用 `README_OpenHarmony.md`，部分仓库鸿蒙化说明嵌在主 README 的某个章节中
+- **API 文档可能不在 docs/ 下**：部分库将 API 文档放在 `doc/`、`api/`、`documentation/`、`guides/` 或直接在项目根目录；必须基于目录探测结果动态识别，而非硬编码路径
+
+---
+
+## 综合评分权重
+
+本 SKILL 在 ArkTS 仓库检视综合评分中权重为 **15%**。

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

@@ -0,0 +1,103 @@
+# 文档质量检视报告模板（输出产物）
+
+> 生成 `文档质量检视报告.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`
+
+---
+
+## 评分等级参考
+
+| 评分区间 | 等级 | 含义 |
+|----------|------|------|
+| 90-100 | 优秀 | 文档完善、准确、易读，鸿蒙化说明充分 |
+| 80-89 | 良好 | 存在少量 Minor 问题，不影响使用 |
+| 70-79 | 一般 | 存在 Major 级别文档缺失，需补充 |
+| 60-69 | 较差 | 关键文档缺失或不准确，严重影响使用 |
+| 50-59 | 不合格 | Critical 级别文档缺失，用户无法正常使用 |
+| <50 | 严重不足 | 多维度 Critical 问题，文档基本不可用 |

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

@@ -0,0 +1,89 @@
+# 文档质量检视检查维度
+
+本文件定义文档质量检视的五个维度、检查项和严重度判定标准。
+
+---
+
+## 维度一：文档完整性（权重 30%）
+
+| 检查项 | 严重度 | 说明 |
+|--------|--------|------|
+| README 缺失 | Critical | 无 README 或 README 为空，用户无法了解库的基本信息 |
+| 鸿蒙化说明缺失 | Critical | 缺少鸿蒙化适配说明文档（ohos/README 或等价文档） |
+| API 文档缺失 | Major | 公开接口无文档说明（对照接口规格说明.md） |
+| 安装指南缺失 | Major | 缺少鸿蒙化库的安装/引入说明（ohpm install 等） |
+| 使用示例缺失 | Major | 缺少使用示例代码或 Demo 工程 |
+| 中文文档缺失 | Major | 鸿蒙化库面向中文生态，缺少中文文档（README_zh.md 等） |
+| 导出声明文档缺失 | Major | index.ets 导出接口无文档说明 |
+| 版本说明缺失 | Minor | 无 CHANGELOG 或版本记录 |
+| oh-package.json5 说明缺失 | Minor | 依赖配置文件缺少注释/说明 |
+| Demo/示例工程缺失 | Minor | 无完整可运行的示例工程 |
+
+---
+
+## 维度二：文档准确性（权重 25%）
+
+| 检查项 | 严重度 | 说明 |
+|--------|--------|------|
+| 错误示例代码 | Critical | 示例代码无法运行或有明显错误（导入路径错、API 不存在等） |
+| API 签名不一致 | Major | 文档描述与实际代码接口签名不匹配（参数名、类型、返回值） |
+| 导出声明与文档不匹配 | Major | index.ets 导出的接口与文档描述不一致 |
+| 废弃 API 未标注 | Major | 文档中仍引用已废弃的 API 或已移除的鸿蒙 API |
+| 鸿蒙 API 说明与代码不一致 | Major | 文档声称使用某 @ohos.* API 但代码实际使用了不同 API |
+| 代码注释与文档矛盾 | Major | JSDoc 注释描述与 README/API 文档描述互相矛盾 |
+| 版本号不一致 | Minor | 文档版本号与 oh-package.json5 版本不匹配 |
+| 依赖说明与实际不匹配 | Minor | 文档描述的依赖与 oh-package.json5 不匹配 |
+| 链接失效 | Minor | 文档中的外部链接无法访问（404 等） |
+
+---
+
+## 维度三：文档易读性（权重 15%）
+
+| 检查项 | 严重度 | 说明 |
+|--------|--------|------|
+| 结构混乱 | Major | 文档缺少章节划分，内容杂乱无层次 |
+| 缺少目录导航 | Minor | 长文档（>500 行）无目录索引 |
+| 语言不通顺 | Minor | 表述模糊、语法错误或逻辑不连贯 |
+| 缺少图表 | Minor | 复杂流程/架构未用图表说明 |
+| 格式不规范 | Minor | Markdown 格式错误（未闭合标签、错误链接语法等） |
+| 中英文混杂无规范 | Minor | 同一文档中中英文混杂，未遵循统一语言规范 |
+| 术语不一致 | Minor | 同一概念在不同文档中使用不同术语 |
+
+---
+
+## 维度四：代码级文档质量（权重 10%）
+
+| 检查项 | 严重度 | 说明 |
+|--------|--------|------|
+| 公开接口无 JSDoc | Major | 导出的函数/类/接口缺少 JSDoc/TSDoc 注释 |
+| JSDoc 参数描述缺失 | Major | 函数注释中缺少参数说明或返回值说明 |
+| 鸿蒙特有 API 未注释 | Major | @ohos.* 调用缺少权限/版本等必要注释 |
+| 注释过时 | Minor | 代码变更后注释未同步更新 |
+| 注释格式不规范 | Minor | JSDoc 格式不符合 ArkTS 编程规范 |
+
+---
+
+## 维度五：鸿蒙化文档专项（权重 20%）
+
+| 检查项 | 严重度 | 说明 |
+|--------|--------|------|
+| 权限说明缺失 | Critical | 使用系统 API（如 sensor、network、geolocation）但未说明所需权限 |
+| 鸿蒙化构建配置说明缺失 | Major | build-profile.json5 / hvigorfile.ts 中的鸿蒙特有配置未说明 |
+| 鸿蒙特性行为说明缺失 | Major | 缺少鸿蒙平台特有行为/限制说明（如线程模型差异） |
+| 差异对比文档缺失 | Major | 缺少鸿蒙化与原库的差异说明（行为差异、接口差异） |
+| 鸿蒙化迁移指南缺失 | Major | 缺少从原库迁移到鸿蒙化版本的指南 |
+| 兼容性说明缺失 | Major | 缺少支持的鸿蒙版本/API 版本范围说明 |
+| 鸿蒙化已知限制说明缺失 | Major | 鸿蒙化后存在的已知功能限制未文档化 |
+| 性能限制说明缺失 | Minor | 缺少鸿蒙化后的性能差异/瓶颈说明 |
+| 鸿蒙化第三方依赖说明缺失 | Minor | oh-package.json5 中的鸿蒙特有依赖未说明用途 |
+| 鸿蒙化测试说明缺失 | Minor | 缺少鸿蒙化特有测试方法/环境说明 |
+
+---
+
+## 严重度判定标准
+
+| 严重度 | 扣分 | 判定依据 |
+|--------|------|----------|
+| Critical | -15 分/项 | 导致用户完全无法使用或严重误解库的功能 |
+| Major | -8 分/项 | 关键信息缺失或错误，显著影响用户使用体验 |
+| Minor | -3 分/项 | 描述不精确但不影响核心使用 |

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

@@ -0,0 +1,62 @@
+# 文档质量检视合规检查清单
+
+> 检视完成后，对照本清单确认报告完整性与格式合规性，确保后端可自动解析。
+
+---
+
+## 1. 检视范围检查
+
+| # | 检查项 | 通过条件 |
+|---|--------|----------|
+| 1.1 | 文档全量扫描 | 已扫描所有 README、.md、.txt、.rst、CHANGELOG、.json5 文件 |
+| 1.2 | 源码扫描 | 已扫描所有 .ets/.ts 文件（排除 node_modules） |
+| 1.3 | 鸿蒙化说明定位 | 已通过三级优先级搜索定位鸿蒙化说明文档 |
+| 1.4 | 接口规格对照 | 已读取 `接口规格说明.md` 并提取公开接口列表 |
+| 1.5 | 文档分类映射 | 已按类别归类（入口/API/鸿蒙化/构建配置/导出声明/示例/代码注释） |
+
+---
+
+## 2. 五维度检视检查
+
+| # | 维度 | 通过条件 |
+|---|------|----------|
+| 2.1 | 文档完整性 | 已检查 README、鸿蒙化说明、API 文档、安装指南、使用示例、中文文档 |
+| 2.2 | 文档准确性 | 已核对 API 签名、示例代码可运行性、导出声明一致性、废弃 API |
+| 2.3 | 文档易读性 | 已检查结构、目录导航、语言、图表、格式规范 |
+| 2.4 | 代码级文档质量 | 已检查 JSDoc/TSDoc 覆盖、参数/返回值描述、鸿蒙特有 API 注释 |
+| 2.5 | 鸿蒙化文档专项 | 已检查权限说明、构建配置、差异对比、迁移指南、兼容性说明 |
+
+---
+
+## 3. 评分计算检查
+
+| # | 检查项 | 通过条件 |
+|---|--------|----------|
+| 3.1 | 维度子评分 | 每个维度独立计算 `max(0, 100 - Critical×15 - Major×8 - Minor×3)` |
+| 3.2 | 综合评分 | 按权重加权：30/25/15/10/20 |
+| 3.3 | 严苛保障 | ≥3 Critical → 最高60分；≥1 Critical + ≥5 Major → 最高50分 |
+| 3.4 | 等级标注 | 已按 90-100/80-89/70-79/60-69/50-59/<50 标注等级 |
+
+---
+
+## 4. 报告格式检查（后端解析依赖）
+
+| # | 检查项 | 通过条件 |
+|---|--------|----------|
+| 4.1 | 综合评分行 | `**综合评分：数字/100**`，中文全角冒号 `：`，位于"二、综合评分"首行 |
+| 4.2 | 维度评分明细表 | 紧随综合评分之后展示 |
+| 4.3 | 维度子评分标注 | 每个维度详情末尾标注 `> {维度}子评分：{分数}/100` |
+| 4.4 | 问题清单 | 包含文档/文件、严重度、维度、描述、修复建议 |
+| 4.5 | 改进建议 | 提供可执行的改进建议 |
+
+---
+
+## 5. 常见遗漏检查
+
+| # | 检查项 | 说明 |
+|---|--------|------|
+| 5.1 | 示例代码可运行性 | 导入路径错误是最常见 Critical，务必逐个验证 |
+| 5.2 | 权限说明 | 使用 @ohos.network 等系统 API 必须检查权限说明 |
+| 5.3 | 双 README 同步 | README_zh.md 与 README.md 需双向检查 |
+| 5.4 | 隐含行为文档化 | 生命周期自动 API 调用（如 aboutToDisappear → destroy()） |
+| 5.5 | oh-package.json5 解析 | 允许注释和尾逗号，不能按严格 JSON 解析 |