@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +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标题}
+
+### 问题现象
+...
+```
+
+**整理规则**：
+- 将原始文档中的"关键发现""踩坑记录""可复用建议"拆解为独立条目
+- 每个条目聚焦一个问题，按"问题现象 → 解决方案 → 结果"三段式重组
+- 去除与问题无直接关联的背景描述，保留可复用的核心信息
+- 多个独立问题用 `---` 分隔

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

@@ -0,0 +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分类，**不用于语义推断关联**。定位仍以显式提及为前提。

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

@@ -0,0 +1,127 @@
+# SKILL 优化规范
+
+> 修改现有 SKILL 文件时的规范和约束。
+
+---
+
+## 1. 修改原则
+
+| 原则 | 说明 |
+|------|------|
+| 最小改动 | 只修改与经验直接相关的部分，不做无关重构 |
+| 保持结构 | 不破坏现有的 Phase 结构和渐进式披露层次 |
+| 版本递增 | 每次修改递增 frontmatter 中的 version |
+| 向后兼容 | 不删除现有步骤，只新增或优化 |
+
+---
+
+## 2. 版本号规则
+
+采用语义化版本（SemVer）：
+
+| 变更类型 | 版本变更 | 示例 |
+|----------|----------|------|
+| 新增步骤/检查项 | minor +1 | 1.0.0 → 1.1.0 |
+| 修改现有步骤描述 | patch +1 | 1.0.0 → 1.0.1 |
+| 重构流程结构 | major +1 | 1.0.0 → 2.0.0 |
+
+> 知识导入场景通常为新增步骤或检查项，使用 minor +1。
+
+---
+
+## 3. 修改位置定位
+
+根据经验内容类型，定位 SKILL.md 中的修改位置：
+
+### 3.1 步骤补充
+
+经验表明 SKILL 缺少某个执行步骤：
+
+```
+定位: SKILL.md body 中最相关的 Phase
+操作: 在该 Phase 的步骤列表末尾新增子步骤
+格式: ### N.M {新步骤名}\n{步骤说明}
+```
+
+### 3.2 检查项新增
+
+经验表明 SKILL 应增加某项检查：
+
+```
+定位: SKILL.md body 中检查相关的 Phase 或输出阶段
+操作: 新增检查项说明
+格式: - [ ] {检查项描述}
+```
+
+### 3.3 注意事项更新
+
+经验发现新的注意事项：
+
+```
+定位: SKILL.md body 中最相关的 Phase
+操作: 添加 > ⚠️ 提示
+格式: > ⚠️ {注意事项描述}
+```
+
+### 3.4 参数补充
+
+经验表明 SKILL 缺少某参数说明：
+
+```
+定位: SKILL.md body 中的任务参数表
+操作: 在表格末尾新增参数行
+格式: | `{paramName}` | {type} | ❌ | {说明} |
+```
+
+---
+
+## 4. 拆分到 references
+
+如果优化内容超过 50 行，应拆分到 `references/` 目录：
+
+```
+SKILL.md body 中:
+> 详细检查清单参见 [扩展检查项](references/EXTENDED_CHECKS.md)
+
+references/EXTENDED_CHECKS.md:
+# 扩展检查项
+...详细内容...
+```
+
+---
+
+## 5. 修改后验证
+
+修改完成后，进行以下验证：
+
+| 检查项 | 方法 |
+|--------|------|
+| frontmatter 合规 | name 匹配目录名、description ≤1024字符 |
+| body 行数 | < 500 行 |
+| references 深度 | 一层，无嵌套 |
+| 文件引用 | 使用相对路径 |
+| 版本号 | 已递增 |
+
+> 完整合规检查清单参见 skill-generator 的 [合规检查清单](../../skill-generator/references/COMPLIANCE_CHECKLIST.md)
+
+---
+
+## 6. 禁止添加变更记录
+
+> ⚠️ **修改 SKILL 文件时，禁止在 SKILL.md 末尾添加"变更记录"章节。**
+
+版本变更信息仅体现在 frontmatter 的 `version` 字段中，不需要在 body 中维护变更记录表格。
+
+**反面示例**（以下操作禁止）：
+
+```markdown
+---
+
+## 变更记录
+
+| 版本 | 日期 | 变更内容 |
+|------|------|----------|
+| 1.1.0 | 2026-08-05 | 新增 Phase 3 中的输入验证步骤 |
+```
+
+如果目标 SKILL.md 中已存在"变更记录"章节，**不要追加新行**，也不要删除已有内容——仅做不新增处理。

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

@@ -0,0 +1,301 @@
+---
+name: ohos-lib-pr-push
+description: 'GitCode 三方库自动提 PR 工具。工作区为 fork 仓库克隆：在代码修改完成后复用当前分支提交推送，自动总结修改点、在源仓库（上游）创建 Issue、必要时同步更新 CHANGELOG（条目附 Issue 链接）、从 fork 向源仓库创建绑定 Issue 的 PR、评论 Start build 触发 CI。USE FOR: 三方库适配/修复/用例补充等本地修改完成后，从 fork 向 GitCode 源仓库（如 CPF-RN 组织仓库）自动提交 PR。'
+license: Apache-2.0
+compatibility: 需要 Node.js 18+（执行 scripts/gitcode-api.cjs），需要 git 命令行，需要 GitCode API Token（默认读取 3rdLibraryLoop/Server/.env 的 GIT_TOKEN）
+metadata:
+  author: LoopEngine
+  version: "1.2.0"
+  category: gitcode-pr
+---
+
+# OHOS Lib PR Push — 三方库自动提 PR
+
+将本地工作区（**fork 仓库的克隆**）的代码修改自动提交为**源仓库（上游）**的 PR，并创建绑定 Issue、触发 CI 门禁。
+
+> ⚠️ **核心原则：① 工作区是 fork 仓库，PR 必须“从 fork 提交到源仓库”，禁止提交到 fork 自身；② 不修改分支——当前在哪个分支，就在该分支上提交并推送，PR head 就是该分支；③ 不修改任何业务代码，只做"总结修改 → 提交 → 建 Issue → 建 PR → 触发 CI"的发布链路；④ Token 绝不写入日志和报告。**
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `workspaceDir` | string | ✅ | 本地工作区（git 仓库根目录）绝对路径，修改已在该目录完成 |
+| `upstreamUrl` | string | ❌ | 源仓库（上游）URL（如 `https://gitcode.com/CPF-RN/rntpc_react-native-image-crop-picker`）。不提供时按 Phase 1.1 的上游推断规则确定 |
+| `token` | string | ❌ | GitCode Token。不提供时读取 `3rdLibraryLoop/Server/.env` 的 `GIT_TOKEN`（见 Phase 1） |
+| `baseBranch` | string | ❌ | PR 目标（上游）分支。默认为上游与当前分支同名的分支（见 Phase 1.5） |
+| `branchName` | string | ❌ | **已废弃自动生成新分支**：默认使用当前分支。仅当用户明确要求指定分支名时才生效，且仍不得切换已有工作分支 |
+| `commitMessage` | string | ❌ | 提交信息。默认由修改点总结自动生成 |
+| `changelog` | string | ❌ | 默认 `auto`：按 Phase 2.4 判定是否更新 CHANGELOG；`true` 强制更新；`false` 强制跳过 |
+| `dryRun` | boolean | ❌ | 默认 `false`。`true` 时只总结修改点和生成报告，不执行 Issue/CHANGELOG 写入/提交推送/PR/CI |
+
+## 输入依赖
+
+- 前置SKILL: 无（通常在 `rnoh-lib-code-adapt` / `rnoh-cptf-demo-test` 等修改类 SKILL 完成后调用）
+- 输入文件: `workspaceDir` 内的未提交/已提交修改（`git status` / `git log` 可见）
+- 输入前提: `workspaceDir` 是某 GitCode 仓库的 **fork 克隆**（本地 origin 指向 fork；可能另有 upstream remote 指向源仓库）
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 确定工作区与 Token
+    ↓
+Phase 2: 总结代码修改点（含 CHANGELOG 必要性判定）
+    ↓
+Phase 3: 创建 Issue
+    ↓
+Phase 4: 更新 CHANGELOG（仅当三方库内部源码有修改，英文条目带 Issue 链接）
+    ↓
+Phase 5: 提交并推送分支
+    ↓
+Phase 6: 创建绑定 Issue 的 PR
+    ↓
+Phase 7: 评论 Start build 触发 CI
+    ↓
+Phase 8: 生成报告
+```
+
+> 各阶段使用的 GitCode API 细节、参数表与踩坑记录统一参见 [GitCode API 参考](references/GITCODE_API.md)
+
+---
+
+## Phase 1：确定工作区与 Token
+
+### 1.1 确定工作区与上游关系（fork → 源仓库）
+
+1. 将 `workspaceDir` 设为当前工作目录
+2. 校验是 git 仓库：执行 `git rev-parse --show-toplevel`
+3. 记录当前分支：`git branch --show-current`（**此分支即提交分支与 PR head，禁止切换**）；remote 信息：`git remote -v`
+4. **确定 fork 仓库与源仓库**：
+   - 本地 `origin`（或其它 remote）指向的仓库视为 fork 仓库（如 `https://gitcode.com/{user}/rntpc_react-native-image-crop-picker`）
+   - 源仓库（上游）按优先级确定：
+     a. 用户传入的 `upstreamUrl`
+     b. 本地名为 `upstream` 的 remote 指向的仓库
+     c. `git remote -v` 中与 origin **同名不同 owner** 的 GitCode 仓库（如 origin 是 `{user}/rntpc_react-native-image-crop-picker`，另一 remote 或仓库推导出 `CPF-RN/rntpc_react-native-image-crop-picker`）
+     d. 通过 GitCode API 查询 fork 仓库的 `parent` 字段（`GET /repos/{forkOwner}/{repo}`，取响应中 `parent.path_with_namespace`）
+5. 无法确定源仓库 → **终止并询问用户**，禁止默认提交到 fork 自身
+6. **Monorepo 判断**：若 `upstreamUrl` 含 `/tree/{branch}/{subpath}`，记录子库路径，Phase 2 总结修改时标注其在仓库内的相对位置
+
+### 1.2 确定 Token
+
+按优先级取值：
+
+1. 用户显式传入的 `token` 参数
+2. 读取 `{3rdLibraryLoop根目录}/3rdLibraryLoop/Server/.env` 中的 `GIT_TOKEN`（该目录通常是 `/Users/lalhan/Desktop/3rdLibraryLoop/3rdLibraryLoop/Server/.env`，亦可从本 SKILL 目录向上回溯：`SKILL 目录 = Server/Skills/ohos-lib-pr-push`，故 `.env` 位于 `../../../.env`）
+3. 都没有 → **终止并提示用户提供 Token**
+
+### 1.3 获取 Token 用户信息
+
+执行（用 Token 换取提交人身份，用于 git config）：
+
+```bash
+node scripts/gitcode-api.cjs get-user --token "$GIT_TOKEN"
+```
+
+记录返回的 `username`（登录名）、`name`、`email`。
+
+### 1.4 获取源仓库（上游）信息
+
+```bash
+node scripts/gitcode-api.cjs get-repo --token "$GIT_TOKEN" --owner {upstreamOwner} --repo {repo}
+```
+
+记录：`id`（源仓库 project_id，Phase 6 必需）、`default_branch`、`path_with_namespace`。
+
+### 1.5 确定 PR base 分支（上游目标分支）
+
+按优先级确定 PR 的 `base`：
+
+1. 用户传入的 `baseBranch`
+2. 上游存在与**当前分支同名**的分支 → 用同名分支（典型场景：当前在 `br_rnoh0.82`，上游也有 `br_rnoh0.82`）。API 探测：`GET /repos/{upstreamOwner}/{repo}/branches/{branch}` 存在即用
+3. 上游无同名分支 → 使用上游 `default_branch`，并在报告中**明显标注**"当前分支 {branch} 在上游无同名分支，PR base 回退到 {default_branch}"
+
+
+
+---
+
+## Phase 2：总结代码修改点
+
+### 2.1 采集修改
+
+在工作区内依序执行并汇总：
+
+| 命令 | 用途 |
+|------|------|
+| `git status --porcelain` | 未提交修改文件清单 |
+| `git diff --stat` + `git diff` | 未暂存修改的统计与详情 |
+| `git diff --cached --stat` | 已暂存修改 |
+| `git log --oneline origin/{defaultBranch}..HEAD`（无 upstream 时用 `git log -10 --oneline`） | 本分支相对目标分支的提交 |
+
+> 注意：若用户已在某分支做过提交，不要重复提交；只需 `git log` 提取已有提交。
+
+### 2.2 归纳修改点清单
+
+对每个修改文件/提交，整理为：
+
+| 序号 | 文件路径 | 修改类型（新增/修改/删除） | 修改说明 |
+|------|---------|--------------------------|---------|
+
+修改说明需具体（如"新增 ImageCropPicker.openPicker 的 crop 场景 CPTF 用例 12 条"），避免笼统的"更新文件"。
+
+### 2.3 生成提交文案
+
+- `commitMessage`（未提供时）：一句话概括 + 修改点数量，如 `feat: 补充 image-crop-picker 裁剪场景 CPTF 用例并完善 demo`
+- PR 标题：`{commitMessage 摘要}`（不加 `[auto]` 之类前缀）
+- Issue 标题：`{分类}：{摘要}`，分类按修改性质从以下三类中选择，**禁止使用 `[auto]` 等无意义前缀**：
+  - `Demo 需求`：新增/补充 demo 演示、示例页面、用例展示
+  - `bug`：缺陷修复
+  - `咨询`：问题咨询、方案确认类
+- PR/Issue body：按 [报告模板](assets/PR_ISSUE_TEMPLATE.md) 填写修改点表格；body 内容一律写入 `/tmp` 临时文件，流程结束后删除，**不得写入工作目录**
+
+### 2.4 判定是否需要更新 CHANGELOG
+
+逐条审视 2.2 的修改点清单，按涉及范围判定：
+
+| 判定 | 涉及范围（示例） | 结果 |
+|------|------------------|------|
+| **需要** | **三方库内部源码**：库源码目录（如 `library/`、`src/` 主代码）、harmony 模块、package 业务代码、进入交付产物的缺陷修复/行为变更 | Phase 4 更新 CHANGELOG |
+| **不需要** | demo/example 页面、测试用例、README 等文档、CI 配置、注释等**不涉及三方库内部**的修改 | 跳过，报告记录"未修改三方库内部源码，跳过 CHANGELOG" |
+
+边界拿不准或用户传了 `changelog` 参数时，以用户为准。
+
+> CHANGELOG 格式遵循 [Keep a Changelog](https://keepachangelog.com/)（与 `rn-lib-update-doc` SKILL 的 Step 6 约定一致）。
+
+---
+
+## Phase 3：创建 Issue
+
+> **必须在提交与 PR 之前创建**：CHANGELOG 条目（Phase 4）与 PR body（Phase 6）都要引用 Issue 编号/链接；绑定关系必须创建时写入，后续 PATCH PR 可能因权限不足失败。
+
+```bash
+node scripts/gitcode-api.cjs create-issue \
+  --token "$GIT_TOKEN" --owner {upstreamOwner} --repo {repo} \
+  --title "{issue标题}" --body-file /tmp/issue-body.md
+```
+
+- body 内容：本次提交的作用 + Phase 2 的修改点清单（模板见 [assets/PR_ISSUE_TEMPLATE.md](assets/PR_ISSUE_TEMPLATE.md)）
+- 记录返回的 `number`（Issue 编号），Phase 4 与 Phase 6 使用
+
+---
+
+## Phase 4：更新 CHANGELOG（仅当三方库内部源码有修改）
+
+按 Phase 2.4 的判定执行（`changelog` 参数为 `true`/`false` 时强制覆盖判定）：
+
+**判定为"不需要"** → 跳过本阶段，报告中记录"未修改三方库内部源码，跳过 CHANGELOG"。
+
+**判定为"需要"** → 在 `{workspaceDir}/CHANGELOG.md` 新增条目：
+
+1. 遵循仓库现有 CHANGELOG 格式：Keep a Changelog 格式时写入 `## [Unreleased]` 下对应分类（`### Added` / `### Changed` / `### Fixed` / `### Deprecated`），无该节则创建；仓库为其他格式时遵循现状；无 CHANGELOG.md 时按 Keep a Changelog 新建
+2. 条目描述**使用英文书写**，与 Phase 2 修改点一致，具体到模块/场景（禁止笼统的 "update code"）
+3. **条目末尾必须附上 Phase 3 创建的 Issue 链接**：`- {英文描述} ([#{issueNumber}](https://gitcode.com/{upstreamOwner}/{repo}/issues/{issueNumber}))`
+4. 该文件修改随 Phase 5 一并提交（`git add -A` 自然包含）
+
+条目示例：
+
+```markdown
+## [Unreleased]
+
+### Added
+- Add 12 CPTF crop-scenario test cases for image-crop-picker and enhance the demo ([#42](https://gitcode.com/CPF-RN/rntpc_react-native-image-crop-picker/issues/42))
+```
+
+---
+
+## Phase 5：在当前分支提交并推送（禁止切换分支）
+
+1. `dryRun=true` → 跳过 Phase 3~7，直接进 Phase 8
+2. 设置仓库级提交人（与 Token 用户一致，避免本地全局配置冒名）：
+
+```bash
+cd "{workspaceDir}"
+git config user.name "{name}"
+git config user.email "{email}"
+```
+
+3. **在当前分支直接提交**（含 Phase 4 的 CHANGELOG 修改）。**禁止 `git checkout -b` / `git switch` 创建或切换分支**：
+
+```bash
+git add -A
+git commit --signoff -m "{commitMessage}"
+# 仅当工作区完全干净（无待提交内容且有已存在提交）时，跳过 commit
+```
+
+4. 推送**当前分支**到 origin（fork 仓库）：
+
+```bash
+git push -u origin HEAD
+```
+
+推送失败（fork 无写权限/无 fork remote）→ 参照 [GitCode API 参考](references/GITCODE_API.md) 的"Fork 模式"章节，用 Token Fork 后添加 remote 再推，仍推送当前分支。
+
+---
+
+## Phase 6：从 fork 向源仓库创建绑定 Issue 的 PR
+
+```bash
+node scripts/gitcode-api.cjs create-pr \
+  --token "$GIT_TOKEN" --owner {forkOwner} --repo {repo} \
+  --head "{当前分支名}" --base "{Phase 1.5 确定的上游 base 分支}" \
+  --title "{pr标题}" --body-file /tmp/pr-body.md \
+  --fork-repo "{upstreamOwner}/{repo}" --target-project-id "{源仓库 project_id}"
+```
+
+关键规则（详细踩坑说明见 [GitCode API 参考](references/GITCODE_API.md)）：
+
+1. **PR 方向恒为 fork → 源仓库（上游）**：调用 fork 仓库的 pulls API，**必须传 `--fork-repo`（源仓库路径）和 `--target-project-id`（源仓库 id）**，否则 PR 变成 fork 仓库内部 PR，源仓库不可见。**禁止**向 fork 自身提 PR
+2. **`head` = 当前分支**（Phase 1.1 记录，随推送更新到 fork）；**`base` = Phase 1.5 确定的上游分支**，不默认使用 `default_branch`
+3. PR body 中**必须**包含 `Closes #{issue_number}`（创建时写入，不事后 PATCH）
+4. body 从 `--body-file` 读取，脚本内部以 UTF-8 form-encoded 发送，避免中文乱码
+
+验证：检查响应 `target_project.path_with_namespace` 是否为源仓库（`{upstreamOwner}/{repo}`）；记录 PR `number` 与网页地址（格式 `https://gitcode.com/{upstreamOwner}/{repo}/merge_requests/{number}`）。
+
+---
+
+## Phase 7：评论 Start build 触发 CI
+
+在**源仓库（上游）**的 PR 下评论（注意 owner/repo 用源仓库，不是 fork）：
+
+```bash
+node scripts/gitcode-api.cjs comment-pr \
+  --token "$GIT_TOKEN" --owner {upstreamOwner} --repo {repo} \
+  --pr "{prNumber}" --body "Start build"
+```
+
+记录评论是否成功（报告的 CI 状态字段）。
+
+---
+
+## Phase 8：生成报告
+
+在 `{workspaceDir}` 下生成 `ohos-lib-pr-push-report.md`——**这是整个流程在工作目录产出的唯一文档**（Issue/PR body 等中间文件一律放 `/tmp` 并在流程结束后删除），模板见 [assets/PR_ISSUE_TEMPLATE.md](assets/PR_ISSUE_TEMPLATE.md)，包含：
+
+- 基本信息（仓库、分支、时间、模式：直推/Fork）
+- 执行结果（PR 地址与编号、Issue 地址与编号、Issue 绑定状态、CI 触发状态）
+- CHANGELOG 状态（已更新并附 Issue 链接；或跳过及原因，如"未修改三方库本身内容"）
+- 修改文件清单（Phase 2 成果）
+- 错误信息（如有）
+
+> **Token 安全**：报告中不得出现 Token 明文。
+
+---
+
+## 注意事项
+
+- **只发布不修改**：发现代码问题应停下报告，不顺手改代码
+- **PR 方向**：恒为 fork → 源仓库（上游）。Issue 建、PR 提、CI 评论均在**源仓库**进行；禁止提交到 fork 自身
+- **分支不变**：当前在哪个分支，就在该分支提交、推送并作为 PR head；禁止 `checkout -b`/`git switch` 创建或切换分支（用户明确指定 `branchName` 并说明目标时除外）
+- **修改点先行**：Issue/PR 的标题与 body 必须基于 Phase 2 的真实修改总结，禁止编造
+- **CHANGELOG 条件更新**：仅当修改了**三方库内部源码**（如 `library/` 目录、harmony 模块、交付产物行为变更）才更新 CHANGELOG，条目使用**英文**描述且必须附 Issue 链接；demo 页面、测试用例、文档、CI 配置等不涉及库内部的修改一律跳过并在报告说明原因
+- **Issue 分类**：Issue 标题必须以 `Demo 需求：` / `bug：` / `咨询：` 之一开头，禁止 `[auto]` 等无意义前缀
+- **单一产出到工作目录**：整个流程只允许在 `{workspaceDir}` 下生成 `ohos-lib-pr-push-report.md` 一个文档；Issue/PR body 等中间文件一律放 `/tmp`，流程结束后删除
+- **Monorepo**：PR body 中标注子库路径；分支名建议带子库名前缀
+- **顺序不可颠倒**：Issue（Phase 3）→ CHANGELOG（Phase 4）→ 提交推送（Phase 5）→ PR（Phase 6）→ CI 评论（Phase 7）
+- **失败恢复**：某步失败时保留已完成产物的编号与链接写入报告，终止后续步骤
+
+## 流程步骤顺序速查
+
+1. 确定工作区 + fork/上游关系 + 当前分支 → 2. 确定 Token（用户传入 or `Server/.env` 的 `GIT_TOKEN`）→ 3. 获取用户与源仓库信息（project_id、base 分支探测）→ 4. 总结修改点（判定 CHANGELOG 必要性：仅三方库内部源码修改才更新）→ **5. 在源仓库创建 Issue（标题带分类前缀：`Demo 需求：`/`bug：`/`咨询：`）** → 6. 更新 CHANGELOG（仅三方库内部源码有修改时，英文条目带 Issue 链接）→ 7. **在当前分支提交并推送到 fork（禁止切分支）** → 8. 从 fork 向源仓库创建 PR（head=当前分支， base=上游对应分支， body 含 `Closes #{issue_number}`）→ 9. 在源仓库评论 Start build → 10. 生成报告（工作目录唯一产出文档，清理 /tmp 中间文件）