@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/ohos-lib-pr-push/assets/PR_ISSUE_TEMPLATE.md

@@ -0,0 +1,105 @@
+# PR / Issue / 报告模板（ohos-lib-pr-push）
+
+本文件包含三段模板：Issue body、PR body、最终报告。`{占位符}` 由执行时填充。
+
+> 约定：Issue 标题格式为 `{分类}：{摘要}`，分类只能是 `Demo 需求` / `bug` / `咨询` 三选一，禁止 `[auto]` 等无意义前缀；PR 标题直接用 commitMessage 摘要（无前缀）；所有 body 临时文件写入 `/tmp`，流程结束后删除——工作目录只产出最终报告一个文档。
+
+---
+
+## 一、Issue Body 模板
+
+```markdown
+## {一句话说明本次提交的作用}
+
+对 `{owner}/{repo}` 的自动修改提交。
+
+### 提交作用
+
+{2-5 句说明：为什么改、解决什么问题、达到什么效果}
+
+### 修改点
+
+| 序号 | 文件路径 | 修改类型 | 修改说明 |
+|------|---------|---------|---------|
+| 1 | {path} | 新增/修改/删除 | {具体修改说明} |
+
+### 验证情况
+
+{如有：测试用例执行结果、编译/覆盖率数据；如无写"见 PR CI"}
+
+---
+> 此 Issue 由 ohos-lib-pr-push 工作流自动创建
+```
+
+---
+
+## 二、PR Body 模板
+
+```markdown
+## {一句话说明本次提交的作用}
+
+### 修改内容
+
+{2-5 句概述}
+
+### 修改文件列表
+
+| 序号 | 文件路径 | 修改类型 | 修改说明 |
+|------|---------|---------|---------|
+| 1 | {path} | 新增/修改/删除 | {具体修改说明} |
+
+### 关联 Issue
+
+Closes #{issue_number}
+
+---
+> 此 PR 由 ohos-lib-pr-push 工作流自动生成
+```
+
+> **必须**：`Closes #{issue_number}` 在创建 PR 时写入 body，不做事后 PATCH。
+
+---
+
+## 三、最终报告模板（ohos-lib-pr-push-report.md）
+
+```markdown
+# 三方库自动提 PR 报告
+
+## 基本信息
+
+| 项目 | 内容 |
+|------|------|
+| 源仓库（上游） | {upstreamUrl} |
+| fork 仓库 | {forkRepoUrl} |
+| 提交模式 | fork → 源仓库跨仓 PR |
+| 工作分支（PR head） | {当前分支}（未切换分支） |
+| PR 目标分支（base） | {上游同名分支 / default_branch（回退时标注）} |
+| 执行时间 | {currentTime} |
+
+## 执行结果
+
+| 项目 | 内容 |
+|------|------|
+| 状态 | 成功 / 失败（{失败阶段}） |
+| PR 地址 | {prUrl} |
+| PR 编号 | !{prNumber} |
+| Issue 地址 | {issueUrl} |
+| Issue 编号 | #{issueNumber}（标题分类：{Demo 需求/bug/咨询}） |
+| Issue 绑定 | 是 / 否（PR body 含 `Closes #{issueNumber}`） |
+| CI 触发 | 是 / 否（评论 `Start build` 于原仓库 PR） |
+| CHANGELOG | 已更新（英文条目含 Issue 链接）/ 跳过（未修改三方库内部源码） |
+
+## 修改文件清单
+
+| 序号 | 文件路径 | 修改类型 | 修改说明 |
+|------|---------|---------|---------|
+| 1 | {path} | 新增/修改/删除 | {具体修改说明} |
+
+## CHANGELOG 更新
+
+{判定为"需要"时：写入 CHANGELOG.md 的英文条目原文（含 Issue 链接）；判定为"不需要"时：跳过原因，如"本次仅涉及 demo 页面与测试用例，未修改三方库内部源码"}
+
+## 错误信息
+
+{如有失败步骤：失败阶段、原因、已完成的产物编号与链接}
+```

package/vendor/Server/Skills/ohos-lib-pr-push/references/GITCODE_API.md

@@ -0,0 +1,127 @@
+# GitCode API 参考（ohos-lib-pr-push）
+
+所有 API 均可通过对应子命令执行 `node scripts/gitcode-api.cjs <cmd> --help` 查看参数。脚本内部统一使用 `application/x-www-form-urlencoded` + UTF-8 发送写请求，避免中文乱码。
+
+Base: `https://gitcode.com/api/v5`
+
+认证方式：查询参数 `access_token={token}` 或 Header `Authorization: Bearer {token}`（脚本已内置）。
+
+---
+
+## API 一览
+
+| 操作 | 方法 | 端点 | 关键参数 |
+|------|------|------|---------|
+| 获取用户信息 | GET | `/user` | 返回 `username`、`name`、`email` |
+| 获取仓库信息 | GET | `/repos/{owner}/{repo}` | 返回 `id`（project_id）、`default_branch`、fork 仓库响应含 `parent.path_with_namespace`（源仓库推断依据） |
+| 探测分支存在 | GET | `/repos/{owner}/{repo}/branches/{branch}` | 200 存在 / 404 不存在，用于 PR base 同名分支探测 |
+| Fork 仓库 | POST | `/repos/{owner}/{repo}/forks` | `name`（fork 仓库名），仅当工作区不是 fork 克隆时用于补建 fork |
+| 创建 Issue | POST | `/repos/{owner}/{repo}/issues` | `title`、`body` |
+| 创建跨仓库 PR | POST | `/repos/{forkOwner}/{repo}/pulls` | `fork_repo`（原仓库）、`target_project_id`（原仓库 id） |
+| PR 评论 | POST | `/repos/{owner}/{repo}/pulls/{number}/comments` | `body=Start build`；owner/repo 用**原仓库** |
+| 关闭 PR | PATCH | `/repos/{forkOwner}/{repo}/pulls/{number}` | `state=closed`（仅参数错误的 PR 需关闭重建时用） |
+
+---
+
+## 踩坑记录（来自 LibraryIntelligentFixSkill 实战）
+
+### 1. 跨仓库 PR 必须传 target_project_id
+
+从 fork 向源仓库（上游）提 PR 时，调用 **fork 仓库**的 pulls API，且必须传：
+
+- `fork_repo` = 源仓库 `{upstreamOwner}/{repo}`
+- `target_project_id` = 源仓库的 `id`
+
+缺失任一参数，GitCode 会把 PR 的 source/target 都设为 fork 仓库（fork 内部 PR），源仓库看不见、无法合并。
+
+**验证方法**：检查响应 `target_project.path_with_namespace` 是否等于源仓库路径；不等则关闭该 PR 重试。
+
+### 1.5 fork → 上游是唯一主路径
+
+- 本 SKILL 的工作区恒为 fork 仓库的克隆（本地 origin 指向 fork），Issue/PR/CI 评论均落在**源仓库（上游）**，禁止提交到 fork 自身
+- 源仓库推断优先级：`upstreamUrl` 参数 > `upstream` remote > 同名不同 owner 的 remote > fork 仓库 API 的 `parent` 字段
+- head = 当前分支（禁止切分支）；base = 上游同名分支（用 `GET /repos/{upstreamOwner}/{repo}/branches/{branch}` 探测），无同名分支时回退 `default_branch` 并在报告标注
+
+### 1.6 head 分支不在 fork 远端时的处理
+
+若 API 报 head 分支不存在，先确认 `git push -u origin HEAD` 是否成功推到 fork；跨仓库 PR 的 head 必须已存在于 fork 仓库。
+
+### 2. Issue 必须先于 CHANGELOG 提交与 PR 创建
+
+两处都需要在"落盘/创建时"引用 Issue：
+
+- CHANGELOG 条目末尾附 Issue 链接 —— 条目随分支提交，必须在 commit/push 前拿到 issue_number
+- PR body 需在创建时就包含 `Closes #{issue_number}` 才能自动绑定；创建后再 PATCH 原仓库 PR 补写可能因权限不足返回 400
+
+### 3. 中文 body 的编码问题
+
+- ❌ 不要用 `Content-Type: application/json` 发含中文的 body —— 部分中文字符会显示为 `?` 或乱码
+- ✅ 使用 `application/x-www-form-urlencoded`，body 值经 `encodeURIComponent`（脚本已内置）
+
+### 4. POST 写操作认证必须用 Bearer 头（2026-08 ohos_checksum 实战）
+
+- ❌ POST（创建 Issue/PR/评论）时把 token 放在 form body 的 `access_token` 字段会被拒：`401 token not found`（脚本旧实现即此问题，尚未修复）
+- ✅ POST 一律用 Header `Authorization: Bearer {token}`；GET 读操作用 query 参数或 Bearer 头均可
+- 规避：用 curl + `--data-urlencode` + Bearer 头替代脚本执行写操作
+
+### 5. 组织迁移导致 API 路径分裂（2026-08 ohos_checksum 实战）
+
+仓库从旧组织迁移到新组织后（如 `CPF-ApplicationTPC` → `openharmony-sig`）：
+- 读 API（GET repo/issues/pulls/branches）新旧路径均可用
+- 写 API（POST 创建 Issue/评论等）**只能用旧组织路径**，新路径返回 `1003 项目不存在`
+- 排查方法：仓库 issue 的 `html_url` 会暴露真正的写入口（旧组织路径）；提交信息中 `See merge request: {org}/{repo}!N` 也可指示
+
+### 6. PATCH 更新 PR 的字段名与权限（2026-08 ohos_checksum 实战）
+
+- PR 描述字段名是 **`body`**，不是 `description`：用 `description` PATCH 返回 200 但**静默不生效**，用 `body` 才真正更新
+- PATCH 更新 PR 必须同时带 `title`，否则报 400 参数缺失
+- 跨仓 PR 作者**无权关闭自己的 PR**（`403 you can only update the title or description`）；同一 source branch 只能有 1 个打开的 PR（新创建返 409）
+- 误建探测 PR 无法关闭时，可 PATCH 其 title/body 收编为正式 PR（分支方向一致即可）
+- Issue 的 PATCH 类似：需同时带 `title`+`body`，关闭用 `state_event=close` 或 `state=close`
+
+### 4. PR 网页地址格式
+
+GitCode 的 PR 网页路径是 `/merge_requests/{number}`（非 GitHub 风格的 `/pull/{number}`）。
+
+### 5. 提交人身份
+
+不设置仓库级 `git config user.name/user.email` 时，提交人使用本地全局配置，可能与 Token 所属用户不一致。克隆/Fork 后立即设置：
+
+```bash
+git config user.name "{name}"
+git config user.email "{email}"
+```
+
+### 6. Fork 已存在的处理
+
+Fork API 在 fork 已存在时可能报错。策略：
+
+1. 先 `GET /repos/{currentUser}/{repo}` 探测是否已 fork
+2. 已存在且无未合并分支 → 删除后重 Fork（保持与上游同步）
+3. 已存在且有在用分支 → 直接复用，推送前 `git pull --rebase` 同步上游
+
+---
+
+## Fork 模式完整流程（工作区非 fork 克隆时补建 fork）
+
+> 主路径是工作区已是 fork 克隆（直接从步骤 5 开始）。仅当工作区是源仓库直克隆且无写权限时，才从步骤 1 开始补建 fork。
+
+```
+1. POST /repos/{upstreamOwner}/{repo}/forks     # Fork 源仓库
+2. git remote add fork https://{token}@gitcode.com/{currentUser}/{repo}.git
+3. git config user.name/email                   # Token 用户身份
+4. GET  /repos/{upstreamOwner}/{repo}           # 记 id、default_branch；探测同名分支
+5. POST /repos/{upstreamOwner}/{repo}/issues    # 先建 Issue（CHANGELOG 与 PR 均需引用）
+6. 更新 CHANGELOG.md                            # 仅当库本身有修改，条目带 Issue 链接
+7. git add -A && git commit && git push -u {fork|origin} HEAD   # 当前分支，禁止切分支
+8. POST /repos/{forkOwner}/{repo}/pulls         # 跨仓库 PR（head=当前分支，base=上游对应分支，带 fork_repo + target_project_id）
+9. POST /repos/{upstreamOwner}/{repo}/pulls/{n}/comments  # body: Start build
+```
+
+> Token 出现在 clone URL 中属于正常用法，但**不得**写入报告、日志正文或 issue/PR 内容。
+
+## Start build 评论规范
+
+- 评论内容固定为 `Start build`（有的组织流水线要求首字母大写，不要写全小写）
+- 必须评论在**原仓库**的 PR 上；评论在 fork 仓库不会触发原仓库门禁
+- 评论失败不影响 PR 有效性，报告中如实记录 CI 触发状态即可

package/vendor/Server/Skills/ohos-lib-pr-push/scripts/gitcode-api.cjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * @tool gitcode-api
+ * @description ohos-lib-pr-push SKILL 的 GitCode API 辅助脚本：封装用户/仓库查询、Issue 创建、PR 创建（含跨仓库参数）、PR 评论。所有写请求使用 form-urlencoded + UTF-8，避免中文乱码。
+ * @param token: string - GitCode API Token（也可用环境变量 GIT_TOKEN）
+ * @param owner: string - 仓库所属空间（owner/组织）
+ * @param repo: string - 仓库名
+ * 子命令:
+ *   get-user                                  获取 Token 用户信息
+ *   get-repo --owner x --repo y               获取仓库信息（id、default_branch；fork 仓库含 parent 源仓库）
+ *   get-branch --owner x --repo y --branch b  探测分支是否存在（用于 PR base 同名分支探测）
+ *   create-issue --title t --body-file f      创建 Issue，返回 number
+ *   create-pr --head b --base m --title t --body-file f
+ *            [--fork-repo o/r --target-project-id id]  创建 PR（跨仓库时传后两项）
+ *   comment-pr --pr n --body "Start build"    在 PR 评论（CI 触发）
+ * 用法示例:
+ *   node gitcode-api.cjs get-user --token "$GIT_TOKEN"
+ *   node gitcode-api.cjs create-pr --token "$GIT_TOKEN" --owner me --repo lib \
+ *     --head fix-Branch --base master --title "fix" --body-file /tmp/pr.md \
+ *     --fork-repo CPF-RN/lib --target-project-id 12345
+ */
+
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { URLSearchParams } = require('url');
+
+const BASE = 'https://gitcode.com/api/v5';
+
+// ---------- 参数解析 ----------
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { args.help = true; continue; }
+    if (a.startsWith('--')) {
+      const key = a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      args[key] = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function die(msg, code = 1) {
+  console.error(JSON.stringify({ ok: false, error: msg }, null, 2));
+  process.exit(code);
+}
+
+// ---------- HTTP ----------
+async function api(method, endpoint, params, token) {
+  const url = new URL(BASE + endpoint);
+  const search = new URLSearchParams();
+  if (token) search.set('access_token', token);
+  let body = null;
+  const headers = {};
+  if (method === 'GET') {
+    for (const [k, v] of Object.entries(params || {})) search.set(k, String(v));
+  } else {
+    headers['Content-Type'] = 'application/x-www-form-urlencoded';
+    body = new URLSearchParams();
+    if (token) body.set('access_token', token);
+    for (const [k, v] of Object.entries(params || {})) body.set(k, String(v));
+    body = body.toString();
+  }
+  url.search = search.toString();
+  const res = await fetch(url, { method, headers, body });
+  const text = await res.text();
+  let json;
+  try { json = JSON.parse(text); } catch { json = { raw: text }; }
+  if (!res.ok) {
+    die(`GitCode API ${method} ${endpoint} -> HTTP ${res.status}: ${text.slice(0, 500)}`);
+  }
+  return json;
+}
+
+// ---------- Token 加载 ----------
+function resolveToken(args) {
+  if (args.token && args.token !== true) return args.token;
+  if (process.env.GIT_TOKEN) return process.env.GIT_TOKEN;
+  // 从 SKILL 目录向上回溯读取 Server/.env 的 GIT_TOKEN
+  // 本脚本位于 Server/Skills/ohos-lib-pr-push/scripts/ → .env 在 ../../../.env
+  let dir = __dirname;
+  for (let i = 0; i < 4; i++) {
+    const envPath = path.join(dir, '.env');
+    if (fs.existsSync(envPath)) {
+      const m = fs.readFileSync(envPath, 'utf8').match(/^GIT_TOKEN=(.+)$/m);
+      if (m) return m[1].trim().replace(/^["']|["']$/g, '');
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function readBody(args) {
+  if (args.bodyFile && args.bodyFile !== true) {
+    return fs.readFileSync(path.resolve(args.bodyFile), 'utf8');
+  }
+  if (typeof args.body === 'string') return args.body;
+  return '';
+}
+
+// ---------- 子命令 ----------
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0];
+  if (args.help || !cmd) {
+    console.log(fs.readFileSync(__filename, 'utf8').split('*/')[0]);
+    return;
+  }
+  const token = resolveToken(args);
+  if (!token) die('未找到 Token：请传 --token，或设置环境变量 GIT_TOKEN，或确保 Server/.env 中存在 GIT_TOKEN');
+
+  switch (cmd) {
+    case 'get-user': {
+      const u = await api('GET', '/user', {}, token);
+      console.log(JSON.stringify({ ok: true, username: u.login, name: u.name, email: u.email, id: u.id }, null, 2));
+      break;
+    }
+    case 'get-repo': {
+      requireParam(args, ['owner', 'repo']);
+      const r = await api('GET', `/repos/${args.owner}/${args.repo}`, {}, token);
+      const parent = r.parent && (r.parent.path_with_namespace || r.parent.full_path) || null;
+      console.log(JSON.stringify({
+        ok: true,
+        id: r.id,
+        pathWithNamespace: r.full_path || r.path_with_namespace || `${args.owner}/${args.repo}`,
+        defaultBranch: r.default_branch || 'master',
+        parent: parent, // fork 仓库的源仓库（上游），用于 upstream 推断
+      }, null, 2));
+      break;
+    }
+    case 'get-branch': {
+      requireParam(args, ['owner', 'repo', 'branch']);
+      // 探测分支是否存在：200 存在 / 404 不存在（不作为错误退出）
+      try {
+        const b = await api('GET', `/repos/${args.owner}/${args.repo}/branches/${encodeURIComponent(args.branch)}`, {}, token);
+        console.log(JSON.stringify({ ok: true, exists: true, branch: b.name || args.branch }, null, 2));
+      } catch (e) {
+        if (/HTTP 404/.test(e.message)) {
+          console.log(JSON.stringify({ ok: true, exists: false, branch: args.branch }, null, 2));
+        } else {
+          throw e;
+        }
+      }
+      break;
+    }
+    case 'create-issue': {
+      requireParam(args, ['owner', 'repo', 'title']);
+      const iss = await api('POST', `/repos/${args.owner}/${args.repo}/issues`, {
+        title: args.title,
+        body: readBody(args),
+      }, token);
+      console.log(JSON.stringify({ ok: true, number: iss.number, url: `https://gitcode.com/${args.owner}/${args.repo}/issues/${iss.number}` }, null, 2));
+      break;
+    }
+    case 'create-pr': {
+      requireParam(args, ['owner', 'repo', 'head', 'base', 'title']);
+      const params = {
+        title: args.title,
+        head: args.head,
+        base: args.base,
+        body: readBody(args),
+      };
+      // 跨仓库 PR：必须同时传 fork_repo（原仓库）与 target_project_id（原仓库 id），
+      // 否则 PR 会变成 fork 仓库内部 PR，原仓库不可见。见 references/GITCODE_API.md。
+      if (args.forkRepo && args.targetProjectId) {
+        params.fork_repo = args.forkRepo;
+        params.target_project_id = args.targetProjectId;
+      } else if (args.forkRepo || args.targetProjectId) {
+        die('跨仓库 PR 需要同时提供 --fork-repo 与 --target-project-id');
+      }
+      const pr = await api('POST', `/repos/${args.owner}/${args.repo}/pulls`, params, token);
+      const targetPath = (pr.target_project && (pr.target_project.path_with_namespace || pr.target_project.full_path)) || '';
+      const result = {
+        ok: true,
+        number: pr.number,
+        url: `https://gitcode.com/${args.owner}/${args.repo}/merge_requests/${pr.number}`,
+        targetProject: targetPath,
+      };
+      // 跨仓库场景自动校验 PR 目标是否指向原仓库
+      if (args.forkRepo && targetPath && targetPath !== args.forkRepo) {
+        result.warning = `PR 目标仓库(${targetPath})与原仓库(${args.forkRepo})不一致，请人工核对`;
+      }
+      console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+    case 'comment-pr': {
+      requireParam(args, ['owner', 'repo', 'pr', 'body']);
+      const c = await api('POST', `/repos/${args.owner}/${args.repo}/pulls/${args.pr}/comments`, {
+        body: args.body,
+      }, token);
+      console.log(JSON.stringify({ ok: true, commentId: c.id || null, body: c.body || args.body }, null, 2));
+      break;
+    }
+    default:
+      die(`未知子命令: ${cmd}（可用: get-user | get-repo | get-branch | create-issue | create-pr | comment-pr）`);
+  }
+}
+
+function requireParam(args, names) {
+  for (const n of names) {
+    if (!args[n] || args[n] === true) die(`缺少必填参数 --${n.replace(/([A-Z])/g, '-$1').toLowerCase()}`);
+  }
+}
+
+main().catch((e) => die(e.message));