@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.1

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/templates/upgrade-spec.md

@@ -0,0 +1,58 @@
+# 行为适配方案模板
+
+由[U05](../references/upgrade/upgrade-workflow.md#u05-汇总-spec-并取得确认)在全部评估任务返回后生成本批次 upgrade/spec.md。主 agent 合并冲突，不直接拼接矛盾建议。本文是修复批准依据；实际差异和验收另写总报告。
+
+```markdown
+# API 行为变更适配方案
+
+工程：<实际工程>；product：<产品>；范围：<模块/目录及 HAP/HAR/原生>
+原 targetSdkVersion：<原值>；目标：<值>；compatibleSdkVersion：<原值，保持不变>
+编译 SDK/IDE：<实际版本>；行为区间：<精确 (from,to] 或无新增区间及理由>
+目标：尽量保持升级前的功能、视觉和交互体验。
+状态：<待确认/全部批准/部分批准/暂不修改；仅凭真实答复填写>
+
+## 输入与评估覆盖
+
+- 原扫描及副本路径、SHA-256、逻辑行数；重复行分别保留。
+- 全部评估任务及实际返回情况，已评估/未完成文件和调用点；工具/资料缺口。
+- 无需适配、可选适配、必须适配、待分类及范围外的原始逻辑行统计。
+- 原始源码/配置与已有改动；HAR 历史基线、宿主和消费关系（适用时）。
+
+## 变更：<名称、准确规则身份、来源与精确版本>
+
+<官方旧新行为、触发条件、target隔离、业务影响及实际阅读证据>
+
+| 方案条目 | 物理文件、调用位置及 rowIds | 分类或缺口 | 修改方案或无需修改依据 | 业务预期、证据和验证 |
+| --- | --- | --- | --- | --- |
+| <可唯一指认的条目> | <实际值> | <逐调用分类> | <具体参数/逻辑调整或真实无需修改理由> | <源码、SDK、官方章节；保持的业务行为> |
+
+说明保留原体验的方式、成本、兼容处理和替代方案；证据不足或业务未决定单独列出，不把任务返回当作问题解决。
+
+## 合并后的共享修改
+
+| 共享条目 | 文件/配置/helper/跨文件接口 | 关联方案与批准依赖 | 合并方案及冲突处理 |
+| --- | --- | --- | --- |
+
+列清哪个执行者修改哪个物理文件；未解决冲突不直接进入修复，不扩大到未授权模块或宿主。
+
+## 验证安排
+
+- 已选择的方式及答复来源：<不运行/仅修改后验证/前后对比>。
+- 测试分类范围：<三类任意组合或全部，关联 rowIds；待分类单列>。
+- 功能、视觉、回调/返回值等预期行为；所选无需适配条目也检查正常功能。
+- 选择对比：修改前真实构建并归档原源码/原配置 before 包，测试可在修复后生成并依次执行 before/after；同设备系统及数据复位安排。
+- 跨系统、HAR 宿主、原生 ABI 等已授权范围及未验证边界。
+
+## 待决定与证据缺口
+
+<具体问题、已查内容、影响范围、可行选择和下一步；不能以笼统待处理替代>
+
+## 用户确认
+
+- 实际答复及可定位来源：<未答复时保持未取得>。
+- 批准全部/明确部分/暂不修改：<具体方案条目、rowIds 和共享修改>。
+- 测试范围答复：<所选分类及具体范围>。
+- 未批准或未解决项：<保留原因，不记为无需修复或范围外>。
+```
+
+只分析或全部无需修改且没有配置调整时展示结论，不额外要求不存在的修复批准。新增范围、目标或实质方案变化时更新受影响部分并重新确认；用户修改过的文件另存版本，不覆盖其编辑。批准前源码和构建配置保持不变。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/templates/upgrade-test-report.md

@@ -0,0 +1,47 @@
+# 行为适配测试报告模板
+
+供[U08](../references/upgrade/upgrade-workflow.md#u08-按需测试与报告)在本批次 upgrade 目录生成 test-report.md，用例和原始证据位于 evidence。未选择设备验证不新增设备任务；已选择但受阻时仍记录实际未执行阶段。
+
+```markdown
+# API 行为适配测试报告
+
+工程/product：<实际值>；spec：<实际路径>；测试方式：<仅修改后验证/前后对比>
+授权范围与答复来源：<分类、条目及 rowIds>。
+总体结果：<通过/失败/部分完成/未执行/不可比，附依据>。
+
+## 阶段包与执行环境
+
+| 项目 | before（仅对比） | after |
+| --- | --- | --- |
+| 原始来源与归档路径 | <原源码/原配置的真实构建> | <最终源码/配置的真实构建> |
+| 包身份、product/模块、target/compatible | <实际值> | <实际值> |
+| SHA-256、构建命令/日志及退出码 | <证据> | <证据> |
+| 签名/实际安装与设备/系统 | <实际结果> | <实际结果> |
+| HAR 消费/ABI（适用时） | <真实依赖关系> | <真实依赖关系> |
+
+原包归档完成与原包测试完成分别说明；不以包存在推断已运行。多模块列实际包集合，不把 HAR 当可运行宿主。
+
+## 测试用例与前置条件
+
+| 用例 | 关联变更、文件和全部 rowIds | 分类 | 数据/复位及操作 | 业务预期与采集方式 |
+| --- | --- | --- | --- | --- |
+
+用例依据 spec 预期生成，优先使用两个阶段包都支持的外部操作。涉及新增入口或埋点、动态资源、外部服务或不可复位数据时说明对比限制。
+
+## 实际执行
+
+| 用例 | before 实际值与断言（仅对比） | after 实际值与断言 | 日志/图片及时间 | 差异、业务结果与可比性 |
+| --- | --- | --- | --- | --- |
+
+对比先执行 before，再复位约定数据执行 after。同设备系统、同语义用例及有效阶段包才可比较；两个阶段表现相同也须分别满足业务预期。仅修改后验证不填写虚假 before。
+
+## 覆盖与未完成项
+
+- 实际覆盖的用例、rowIds 和分类；所选无需适配条目的正常功能结果。
+- 未选、待分类、未执行、失败和不可比范围及具体原因。
+- 设备/安装/签名/工具/测试入口/数据复位等阻断与下一步。
+- 代码或配置再次变化后的 after 重建、受影响重测情况；原 before 归档保持不变。
+- 本次启动实例的清理结果；已有实例和真机保留。
+```
+
+启动成功、单页截图、零用例或脚本退出0均不代替业务验收。缺包、异系统、证据缺失和模型中断分别报告，不回退源码补造 before，不把设备失败改写为源码适配失败或通过。总报告引用此文件，分别表达评估、修改、构建和设备结果。

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-knowledge/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: harmonyos-knowledge
+description: 搜索 HarmonyOS SDK、Flutter、React Native / RNOH 与三方库适配知识，获取相关文档。
+---
+
+# 知识库查询
+
+直接通过 HTTP POST 查询知识库，调用工具或语言自行选择。
+
+请求地址：`https://connect-api.cloud.huawei.com/api/developerknowledge/mcp`。搜索和全文请求均使用以下 headers：
+
+```json
+{
+  "Content-Type": "application/json",
+  "Accept": "application/json, text/event-stream",
+  "sceneName": "third-party",
+  "x-gray-flag": "1"
+}
+```
+
+返回 JSON-RPC，业务数据直接读取 `result.structuredContent`，或将 `result.content` 中 `type: "text"` 的 `text` 解析为 JSON。业务 `code: 0` 表示成功；若返回 SSE，先提取事件 `data:` 中的 JSON-RPC 消息。
+
+## 搜索策略
+
+- **拆分主题**：每次只搜索一个具体问题。多个主题堆在一个 query 中，容易命中宽泛，具体答案反而难以检出。
+- **渐进定位**：不知道 API 时先搜场景与目标行为，再用命中片段中的 Kit、模块或 API 细化下一次查询；已知 API 时直接围绕具体用法、参数或错误搜索。结合已知的平台、框架和目标版本消歧。
+- **多次精准搜索**：结果宽泛、偏题或缺少答案时，围绕同一问题换用更具体的动作、同义词或已知 API 名重新搜索。
+- **筛选全文**：按片段内容、文档标识、框架和目标版本筛选，只获取支撑当前问题的文章；片段足够时直接使用。
+
+## 搜索文档
+
+`searchDocuments` 请求体，`topK` 为可选的返回结果数量，默认 10：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "searchDocuments",
+    "arguments": {
+      "SearchDocumentsReq": { "query": "xxxx", "topK": 10 }
+    }
+  }
+}
+```
+
+业务结果 `resultList` 中，`content` 是检索命中的正文片段，`parent` 是所属文档标识。
+
+## 获取全文
+
+将筛选后的 `parent` 去重后完整填入 `names`，每次 1–10 篇。
+
+`getDocumentsById` 请求体：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "getDocumentsById",
+    "arguments": {
+      "GetDocumentsByIdRequest": { "names": ["相关文档的 parent"] }
+    }
+  }
+}
+```
+
+返回的业务 `resultList` 始终为数组，单篇也如此。每项包含 `name`（文档标识）、`title`、`uri`（可能为空）和 `content`（Markdown 正文），按 `name` 区分文档。

package/node_modules/@hmos-library-adapter/executer/src/config.js

@@ -10,8 +10,8 @@ export const ENTRY_AGENT_NAME = 'hmos-library-adapter-executer'
 export const ENTRY_DESCRIPTION =
   'HarmonyOS 三方库适配统一入口 — 自动判定当前仓库是 Flutter 插件 / React Native 模块 / 原生 Android 库，路由到对应 agent 完成鸿蒙适配。仅处理三方库鸿蒙适配相关问题。'
 
-/** 公共能力源目录（doc 检索 skill，三平台共用，只装一份）。 */
-export const COMMON_DIRNAME = 'agent-core'
+/** 公共能力源目录（doc 检索 skill 等，三平台共用，只装一份）。扁平结构：每个子目录是一个 skill。 */
+export const COMMON_DIRNAME = 'common-skills'
 
 /**
  * 平台注册表。每项：
@@ -61,8 +61,7 @@ export const NEEDS_PYTHON = true
 
 /** doctor 校验「关键 skill 是否齐」用的名单（含公共 + 各平台代表）。 */
 export const REQUIRED_SKILLS = [
-  'harmonyos-docs-lookup',
-  'harmonyos-sdk-api-lookup',
+  'harmonyos-knowledge',
   'rn-ohos-template',
   'hardemo-template',
   'ohos-coding-guide',

package/node_modules/@hmos-library-adapter/executer/src/doctor.js

@@ -44,7 +44,7 @@ export function doctor() {
   info('[Package / agent 内容源]')
   info(`  version:      ${PKG_VERSION}`)
   info(`  package root: ${PACKAGE_ROOT}`)
-  info(`  mode:         ${IS_PACKAGED ? 'packaged（读 shared/）' : 'dev（直读 sibling agent-*-fast + agent-core）'}`)
+  info(`  mode:         ${IS_PACKAGED ? 'packaged（读 shared/）' : 'dev（直读 sibling agent-*-fast + common-skills）'}`)
   if (fs.existsSync(ROUTER_PROMPT)) ok(`顶层路由 prompt: ${ROUTER_PROMPT}`)
   else warn(`顶层路由 prompt 缺失: ${ROUTER_PROMPT}`)
 

package/node_modules/@hmos-library-adapter/executer/src/install.js

@@ -23,7 +23,7 @@ const PLUGIN_MARKER = `managed-by: ${MANAGED}`
 export function install({ target = 'opencode', dryRun = false, force = false } = {}) {
   const log = (s) => console.log(s)
   log(`hmos-library-adapter-executer v${PKG_VERSION} install (target=${target}, dry-run=${dryRun}, force=${force})`)
-  log(`  mode: ${IS_PACKAGED ? 'packaged (shared/)' : 'dev (直读 sibling agent-*-fast + agent-core)'}`)
+  log(`  mode: ${IS_PACKAGED ? 'packaged (shared/)' : 'dev (直读 sibling agent-*-fast + common-skills)'}`)
   log(`  入口: ${ENTRY_AGENT_NAME}（用户唯一调用，检测 + 路由）`)
   log('')
 

package/node_modules/@hmos-library-adapter/executer/src/paths.js

@@ -127,13 +127,13 @@ export function platformClaudeMd(platformId) {
 /**
  * skill 源目录。
  * packaged：单一 shared/skills（已含全部平台 + 公共，去重后）。
- * dev：每个平台 .claude/skills + agent-core/.claude/skills。
+ * dev：每个平台 .claude/skills + common-skills（扁平 skill 目录）。
  */
 export const SKILL_SOURCE_DIRS = IS_PACKAGED
   ? [path.join(PACKAGED_SHARED, 'skills')]
   : [
       ...cfg.PLATFORMS.filter((p) => !p.selfHosted).map((p) => path.join(WORKSPACE, p.agentDir, '.claude', 'skills')),
-      path.join(WORKSPACE, cfg.COMMON_DIRNAME, '.claude', 'skills'),
+      path.join(WORKSPACE, cfg.COMMON_DIRNAME),
     ]
 
 /** 展开所有 skill：[{ name, src }]，按 name 去重（公共 doc skill 只出现一次）。 */
@@ -152,7 +152,7 @@ export function listSkills() {
 /**
  * 平台 → skill 名单映射。
  *   packaged：读 shared/skill-map.json（stage 时生成）。
- *   dev：从 sibling 各平台 .claude/skills + agent-core/.claude/skills 目录派生。
+ *   dev：从 sibling 各平台 .claude/skills + common-skills 目录派生。
  * 形状：{ platforms: { <id>: string[] }, common: string[] }
  */
 export function loadSkillMap() {
@@ -170,7 +170,7 @@ export function loadSkillMap() {
     const d = path.join(WORKSPACE, p.agentDir, '.claude', 'skills')
     platforms[p.id] = fs.existsSync(d) ? fs.readdirSync(d).filter((n) => !n.startsWith('.')) : []
   }
-  const cd = path.join(WORKSPACE, cfg.COMMON_DIRNAME, '.claude', 'skills')
+  const cd = path.join(WORKSPACE, cfg.COMMON_DIRNAME)
   const common = fs.existsSync(cd) ? fs.readdirSync(cd).filter((n) => !n.startsWith('.')) : []
   return mergeSkillInclude({ platforms, common })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmos-library-adapter/fast",
-  "version": "0.0.17-beta.0",
+  "version": "0.0.17-beta.1",
   "description": "鸿蒙三方库适配/升级/修复统一调度入口 — 自动识别适配、升级或修复意图，分发到对应子包完成鸿蒙适配、升级或问题修复。安装到 OpenCode 宿主。",
   "type": "module",
   "main": "src/plugin.js",