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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-test-design/references/input-resources.md

@@ -0,0 +1,59 @@
+# 默认输入、文件资源与入口验证
+
+适用于带默认输入的测试载体，文件资源规则仅按项目声明启用，不根据库名、API、文件扩展名或错误文本推断。
+
+## 设计契约
+
+阶段 5 审查文件路径输入时，在现有 text 输入上声明 `file`，正常文件示例：
+
+```json
+{"kind":"text","label":"输入文件","default":"fixtures/sample.dat",
+ "file":{"state":"present","source":"source/tests/sample.dat","min_bytes":1}}
+```
+
+`source` 是工作区相对路径，必须指向实际存在的文件，不能越出工作区；默认至少 1 字节，测试合法空文件时声明 `min_bytes:0`。默认值是页面可编辑的路径表示，source 是该默认文件的实际字节来源，二者无需使用同一目录名。格式要求仍由用例 oracle 和真实断言验证。
+
+缺失文件负例声明 `file:{"state":"absent"}`，不能附 source。普通文本、命令参数、域名等不声明 file。阶段 5 只核实契约与真实资源，不在本阶段创建 demo 或修改被测源码。往返用例的 default 仍须等于前一步对同一原始数据生成的结果，按既有 oracle.conditions 记录关系。
+
+默认值的可测量边界由 `input.constraints` 声明，依据记录在 `oracle.basis`：`utf8_bytes` 测量 UTF-8 字节数，
+`nesting_depth` 测量声明的一对 opening/closing 标记的最大平衡嵌套深度。边界用 minimum/maximum 或
+exclusive_minimum/exclusive_maximum 表达；流水线按声明测量，不预设库级源码路径或阈值。异常样本须同时满足语法、触发条件及预期错误类别。
+
+## 生成与接线
+
+scaffold 将声明资源复制到 HAP rawfile，并生成 `OhptInputRunner.ets`。单条页面及 ArkTS 自判跑批共同通过此包装层调用原有 `OhptCaseRunner`；原有被测物分派继续保留。
+
+每次调用都从 rawfile 重新准备默认资源到 `<filesDir>/ohpt-inputs/<case-id>/`，该稳定目录独立于 native 清理的用例临时目录。正常文件校验长度和可读性，缺失负例移除该默认目标。包装层向被测物传绝对路径；父进程准备 stdin 和子进程读取文件均使用这个路径，不再分别依赖各自 cwd。用户输入自定义路径时保持输入含义，相对路径以 filesDir 为基准，准备失败即报告资源错误并停止业务调用，不替换为其他内置文件。
+
+接线不得在包装层完成之后再清理 `filesDir/ohpt-inputs`，也不得忽略绝对输入参数重新选择内置向量。原生/GUI 全套入队档仍须逐条验证详情入口，不能仅以整套入队结果代替默认输入证据。GUI 等没有可传参接口的形态须在其执行器实现等价资源契约，不冒用 ArkTS 包装层。
+
+增量 scaffold 保留已定制的旧页面和分派。保留页必须合并生成的默认输入调用和包装层 import，再重新构建。验证前检查与阶段 6 gate 共用 `demoInputContractProblems`，旧跑批传空值、旧详情页绕过准备层、包装层漂移、已打包资源与 source 字节不同均不能放行。
+
+## 执行与证据
+
+`verify-demo --cases` 默认先取整套证据，再对声明 input 的用例独立拉起详情页。批量结果仍保留在主记录，单条结果进入 `default_input_evidence`，原始日志另存 `default-input-raw.log`；两者不相互覆盖。单条与跑批结论不同、单条缺失判定点或日志通道异常时不满足完成门禁。
+单独 `--per-case` 复验时只继承同一指纹的已有跑批证据为 `batch_input_evidence`；没有跑批对照的单条 pass 不能代替双入口验收。规则按生成页面/驱动器能力启用，其他执行器保留各自证据契约。
+
+记录的 `input_contract_sha256` 绑定当前用例、demo 源码、资源及已有未签 HAP；任何一项变化都须重新取证。这个检查在阶段 6 完成/历史 passed 的 skip 之前执行，而不是仅返回 PostWrite 告警。缺少输入框的载体不按文本猜测默认值；声明默认输入的载体仍必须提供独立执行证据。
+验证前检查实际选中的未签 HAP 不早于页面、资源与接线源码；更新后须重建。重新签名不改变未签包指纹。`--no-install` 可用于诊断，但不证明设备安装的是当前本地包，因此不生成可放行的输入指纹。单条补证仍受整轮 timeout 约束，预算耗尽时缺失证据保持可见，不默认通过。
+
+## 外部前置
+
+外部服务或数据前置由载体内的 `preflight.json` 声明。执行器在装机/拉起之前校验全部步骤，再依序运行；
+脚本缺失或执行失败即停止，增量工程保留声明及脚本。服务协议、端口和 mock 由项目维护，此通道不代替每次调用的文件资源准备。
+
+| 字段 | 契约 |
+|---|---|
+| `version` | 当前为 `1` |
+| `steps` | 非空步骤数组 |
+| `steps[].runtime` | `python` 或 `node` |
+| `steps[].script` | 载体目录内的相对脚本路径 |
+| `steps[].args` | 可选字符串数组 |
+| `steps[].timeout_sec` | 可选，默认 45 秒，范围 1–60 秒 |
+
+上下文通过 `OHPT_WORKSPACE`、`OHPT_HDC`、`OHPT_DEVICE_TARGET` 传入；连接目标未指定时为空，由项目脚本解析唯一设备，
+不能把签名 UDID 当成 hdc 连接 target。准备失败、初始化/连接失败与业务失败分别报告。
+
+## 输出断言
+
+CLI 数据输出与 stderr 诊断分别保存，二进制标识只检查 stdout；输入准备错误与库业务错误分开报告。复合输出谓词逐项提供事实：返回码、是否存在、实际长度、格式标识或内容比较；“存在且非空”必须核验长度，不能仅用存在性代替。往返不一致时报告首个差异位置及预期/实际字节，不能只报告返回码和长度。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-test-design/references/network-protocol-mock.md

@@ -0,0 +1,131 @@
+---
+description: 网络协议库（IMAP/POP3/SMTP/HTTP/WebSocket 等）在鸿蒙 PC 设备上验证时，因无对端服务器被 blocked 的通解模式：hdc rport 反向端口转发 + 宿主侧 mock 服务器。
+---
+
+# 网络协议库验证前置：hdc rport + 宿主 mock 服务器
+
+## 问题
+
+验证邮件库（如 libetpan）、IMAP 客户端、SMTP 库等网络协议依赖的库时，设备侧**没有可达的邮件服务器对端**，属于 precondition-unmet。在 libetpan 适配中，19/38 条 PRD 用例（F-01~F-04 的协议链路类）因此被 blocked，包含：
+
+- TCP 连接/超时/取消（需真实对端握手）
+- TLS 握手（需 993/995/465 端口对端）
+- IMAP 登录/选邮箱/取邮件/标记删除
+- POP3 连接/列表/收信/删信
+- SMTP 握手/认证/发信
+
+简单断言「返回错误码」不够——真正的功能覆盖需要「能成功时确实成功，不能成功时返回合理错误码且不崩溃」。
+
+## 模式：宿主 mock 服务器 + hdc rport
+
+### 原理
+
+```
+┌──────────┐    hdc rport tcp:<设备端口> tcp:<宿主端口>    ┌──────────┐
+│ 鸿蒙设备  │ ←──────────────────────────────────────────→ │  宿主     │
+│ app 域    │   设备侧访问 localhost:<设备端口> 即到达      │  mock 服务器│
+│ 测试 ELF  │    宿主侧的 mock 服务器监听:<宿主端口>        │ (Python)  │
+└──────────┘                                              └──────────┘
+```
+
+`hdc rport tcp:<device_port> tcp:<host_port>` 设置反向端口转发——设备侧连接 `localhost:<device_port>` 时，数据被转发到宿主侧的 `localhost:<host_port>`。
+
+### 操作步骤
+
+```bash
+# 1. 宿主侧启动 mock 服务器（Python 3，内置 IMAP/POP3/SMTP）
+python -m smtpd -c DebuggingServer -n localhost:1025 &    # SMTP mock
+# 或自写 mock（见下方模板）
+
+# 2. 建立反向端口转发
+hdc rport tcp:1143 tcp:1143      # IMAP → 宿主 mock IMAP 1143
+hdc rport tcp:1110 tcp:1110      # POP3 → 宿主 mock POP3 1110
+hdc rport tcp:1025 tcp:1025      # SMTP → 宿主 mock SMTP 1025
+
+# 3. 设备侧测试 ELF 连接 localhost:1143/1110/1025
+# （测试用例的 host 地址设为 localhost，端口与转发一致）
+
+# 4. 验证完后清理
+hdc rport tcp:1143 tcp:1143 -r   # 移除转发
+```
+
+### mock 服务器模板（Python）
+
+```python
+#!/usr/bin/env python3
+"""mock_email_server.py — 一次性 IMAP/POP3/SMTP mock，用于设备验证用例。"""
+import asyncio
+
+# ===== IMAP mock（仅实现用例所需的最小命令集）=====
+class MockIMAPProtocol(asyncio.Protocol):
+    def connection_made(self, transport):
+        self.transport = transport
+        self.transport.write(b"* OK Mock IMAP server ready\r\n")
+
+    def data_received(self, data):
+        cmd = data.decode().strip().upper()
+        tag = cmd.split(" ")[0] if " " in cmd else cmd
+        if "LOGIN" in cmd:
+            self.transport.write(f"{tag} OK LOGIN completed\r\n".encode())
+        elif "LIST" in cmd:
+            self.transport.write(
+                b"* LIST (\\HasNoChildren) \"/\" INBOX\r\n"
+                f"{tag} OK LIST completed\r\n".encode()
+            )
+        elif "SELECT" in cmd:
+            self.transport.write(
+                b"* 3 EXISTS\r\n* 0 RECENT\r\n"
+                f"{tag} OK [READ-WRITE] SELECT completed\r\n".encode()
+            )
+        elif "FETCH" in cmd:
+            self.transport.write(
+                b"* 1 FETCH (FLAGS (\\Seen) BODY[HEADER.FIELDS (DATE FROM SUBJECT)] "
+                b"\"Date: Wed, 01 Jan 2025 00:00:00 +0000\r\nFrom: test@example.com\r\n"
+                b"Subject: Test\r\n\r\n\")\r\n"
+                f"{tag} OK FETCH completed\r\n".encode()
+            )
+        elif "STORE" in cmd or "EXPUNGE" in cmd:
+            self.transport.write(f"{tag} OK completed\r\n".encode())
+        elif "LOGOUT" in cmd:
+            self.transport.write(b"* BYE IMAP server logging out\r\n")
+            self.transport.write(f"{tag} OK LOGOUT completed\r\n".encode())
+            self.transport.close()
+        else:
+            self.transport.write(f"{tag} BAD unknown command\r\n".encode())
+
+# ===== 启动 =====
+async def main():
+    loop = asyncio.get_running_loop()
+    for port in [1143, 1110, 1025]:
+        await loop.create_server(MockIMAPProtocol, "127.0.0.1", port)
+    print(f"Mock email servers running on 127.0.0.1:1143 (IMAP), :1110 (POP3), :1025 (SMTP)")
+    await asyncio.Event().wait()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 用例设计要点
+
+启用 mock 服务器后，判定三类行为：
+
+| 行为 | 预期 | 判据 |
+|------|------|------|
+| 正常流程 | 握手/登录/操作/退出全链路成功 | 返回成功码，无崩溃/挂起 |
+| 错误凭据 | 登录返回认证失败错误码 | 进程不崩溃，退出码非 0 |
+| 不可达地址 | 连接失败返回错误码 | 超时从 90s 降到几秒内返回 |
+
+**注意**：
+- TLS 端口类用例仍需要 mock 支持 TLS 握手（或降级协议测试——通过测非 TLS 端口+连接失败路径覆盖）
+- 超时类用例在 mock 上可故意不响应来验证
+- 用例 precondition 要写清楚依赖 mock 服务器
+
+## 归因
+
+设备上 blocked 的协议用例，40% 可通过此模式转为 pass。剩余需真实多跳拓扑（SMTP 中继/DNS MX 查询）的，保持 `blocked` + `capability_gaps`。
+
+## 关联
+
+- `pc-device-verify/references/domain-hdc-shell.md`（hdc 能力边界）
+- `openharmony-device-porting/references-full/subsystems/subsys-toolchain-hdc-guide.md`（hdc rport 命令参考）
+- `pc-test-design/references/anti-fake-checklist.md`（反造假：blocked 必须进 capability_gaps，不能手写平替）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-test-design/references/render-preview-page.md

@@ -0,0 +1,30 @@
+---
+description: 渲染/出图类库的结果图上屏——机制已内置（05 声明 steps[].output → 执行器对比沙箱登记产物 → 结果区 Image 上屏 → 验收规则执法），本文只保留一个仍需人判断的取舍：渲染走 exec 子进程还是主进程 dlopen（libaribcaption 1.1.2 fontconfig 自举实证）。
+---
+
+# 结果图上屏：机制与唯一的取舍
+
+**上屏不再手写页面。** 曾经（libaribcaption 2026-09-15）这里是一整页 PreviewPage.ets 模板 + 两个入口
++ NAPI JSON 契约 + 三条红线；它是散文，挂在一个载体小节下，gmic（2026-09-23）走另一个载体就没有人读到。
+现在同一件事是机制，六个所有者各管一段：
+
+| 段 | 谁做 | 在哪 |
+|---|---|---|
+| 声明「这一步的产物是一张图」 | 阶段 5 | `05-testcases.json` 的 `steps[].output = {kind: image, label}` |
+| 观察用例写了什么 | 执行器/驱动器 | `entry/src/main/cpp/ohpt_artifacts.h`（scaffold 复制自 `templates/hap/_shared/`）：用例前后对比沙箱，bytes/FNV-1a64 由执行器算 |
+| 证据 | 执行器 → `verify-demo` | `OHPTCASE artifact id=… kind=image path=… bytes=… sha=…` → `test-demo/verify/<case>.json` 的 `artifacts[]` |
+| 上屏 | 生成的页面 | `OhptResultPanel` 按登记行 `Image('file://'+path)`；RunAll 行缩略图；信息区标「产物：图像·label」 |
+| 执法 | PostWrite 验收表 | `testdemo-artifact-evidenced`（声明 ⊆ 登记）、`testdemo-artifact-distinct`（各用例的图字节级互异） |
+| 报告 | 渲染方 | 「上屏产物（人工目视清单）」段由 verify JSON 派生 |
+
+接线方唯一要做的：**把结果图写进用例沙箱**（cli-hnp-runner 是执行器的 `cwd`，cpp-lib-demo 是 `filesDir`）。
+文件名带不带用例标识都行——归属按「这条用例执行期间写下/改写的文件」观察，不按文件名；
+同一路径被后一条用例改写，会正确记到后一条头上。
+
+## 唯一仍需你判断的：渲染在哪个进程里做
+
+**运行时数据自举类依赖（fontconfig / CA bundle 等）在 HAP 主进程内 dlopen 初始化可能失败，
+fork/execv 的子进程里自举完全正常**（libaribcaption fontconfig 真机实证）。渲染链路一旦依赖这类库，
+就让用例在**子进程**里出图（cli-hnp-runner 本就是 exec 形态；cpp-lib-demo 里则 fork/execv 一个渲染 ELF
+把图写进 filesDir），而不是主进程 dlopen 直接拿像素。库没有这类依赖时，主进程内直接写图即可。
+两条路线写出的文件都由执行器登记，页面无差别。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-test-design/references/test-contract-regressions.md

@@ -0,0 +1,57 @@
+# 测试线通用契约审查清单
+
+适用于阶段 5（测试设计）与阶段 6（Demo 接线及验证）。本清单提供审查方法，不预设任何库的结果或排除决定。具体库的根因、用例编号、源码位置及处理决定应记录在该库的阶段产物与证据中，不作为其他库的默认规则。
+
+## 1. 从实际接口确定预期
+
+- 核实当前版本的声明、文档、实现和上游测试。沿调用链读取最终返回、输出分支与提前返回，不能只依据函数名称、入口代码或依赖库行为推测包装接口的契约。
+- 区分相似接口的合法输入、对齐要求、比较方式、是否移动对象及失败返回。一个接口的保证不能直接套到另一个接口。
+- 区分库原始输出与应用展示层转换；默认值逐字段核对构造、初始化和复位代码。
+- 对尽力执行、保守误差界或允许失败的操作，验证契约保证的不变量。只有存在保证成功的条件和依据时，才断言必须成功。
+- 为每个有效用例填写 `oracle.basis`（当前工作区真实文件的 `file:line` 数组）及 `oracle.conditions`（输入、参数、状态、平台和结果成立条件）。源码行号必须以当前版本为准。
+
+## 2. 核实数值、编码与状态语义
+
+- 明确数学对象、定义域和边界条件；文档声明非法的输入不能被设计成要求稳定返回的正常用例。
+- 浮点输入须区分十进制描述、源值的二进制表示和目标精度。需要验证舍入时，证明目标精度下不可精确表示。
+- 复合返回值按规定的宏或字段解码，不能将打包整数的正负当成整体比较结果。
+- 状态修改后核对中间状态，再执行后续操作；不能默认精度调整、清空或重置仍保留旧值。
+- 字符转义和编码转换须核实参数作用下的最终字节输出、同编码短路以及实际输出通道。内存输出和文件写回不一定应用同一组选项。
+
+## 3. 固定并发观测状态
+
+线程、任务和队列的计数或长度用例须填写 `oracle.state_control`；无并发的队列也应明确单线程前提。
+
+- 阅读计数字段的初始化、所有递增/递减位置和 getter，区分等待数量、执行中数量及累计数量。只引用 getter 不足以证明语义。
+- 用锁、条件变量、屏障或完成通知固定观测状态。夹具任务与被测任务分别记录，确保读取计数时观测条件已经成立。
+- 实现有界等待和失败时的释放、取消或清理，避免夹具阻塞整个测试。
+- 不用固定 sleep 猜测状态，不反复重试到偶然通过，也不把确定性预期放宽成任意竞态范围。
+
+## 4. 核实载体与依赖接入
+
+- 阶段 5 只读主线交付范围、构建结果和豁免依据，区分核心逻辑、平台适配层和外部 SDK 的能力。发现缺口时记录具体依赖及可观测影响。
+- 核心数据验证不能冒充真实渲染、窗口几何或输入事件验证；桩实现、固定宽度和中性背景不能证明真实平台能力。
+- 原生通知与框架信号分别验证，不能用其中一个的成功代替另一个的事件路径。
+- 声明插件搜索路径、已启用后端、可写沙箱和运行环境等前置条件。宿主或 CLI 的环境设置与证据不能代替目标载体的真实接线及证据。
+- 动态加载应验证实际加载结果及符号所属库，不能让系统同名接口代替被测库；分配和释放接口必须配对。
+- 平台接入、测试载体或适配产物缺口不能归因为上游缺陷。没有明确、可追溯的范围决定时，保留受阻结果和能力缺口。
+
+## 5. 基于证据处理上游缺陷
+
+- 先证明问题存在于当前使用的原始上游版本，再区分预期错误、配置遗漏、适配新增问题和上游缺陷。测试失败本身不能证明来源。
+- 只有已明确接受暂不修复、且有源码及实际证据支持的上游缺陷，才按 schema 记录到 `exclusions[]`。是否接受必须依据当前任务或既有明确决定，不能从本清单或其他库的历史处理推导。
+- 记录原因、真实源码或导出配置的 `file:line`、可复核的本地证据文件。未知失败、错误预期和测试载体问题不能进入上游缺陷排除。
+- 排除不等于通过。按 feature/case 为统计单位排除复合用例时，注明受影响子路径和其余路径的验证情况，不宣称整个模块全覆盖。
+- 保留原始功能点数，按排除清单计算有效分母，报告单列排除数量及依据。阶段 6 原样继承阶段 5 的排除清单，不自行扩大范围。
+
+## 6. 修正设计并取得本轮证据
+
+- 源码证伪的字面量或条件可以修正，但须保留原验证目标，按 amendment 契约记录 before、after、basis 和 evidence_before。不能为得到 pass 修改真实契约。
+- 文件路径输入、默认值边界与外部前置按 [默认输入与资源契约](input-resources.md) 核实；声明及脚本由项目维护，不从库名、符号或错误文本推断。
+- 页面与跑批使用同一设计向量；修正时同步 default、页面与断言。往返数据逐字节一致，实际结果同时核对返回码、长度及内容，不能只改 native 回退或用长度相同代替内容正确。
+- 外部前置失败时停止依赖它的业务调用，区分准备失败、初始化/连接失败与业务失败；不把任意失败当作预期异常。
+- 阶段 6 根据当前有效 cases、oracle 条件及状态控制接线。设计变化后同步用例名册、页面预期和 native 断言，重新构建。
+- 阶段 5 设计与阶段 6 接线必须一致；发现新的契约错误时按既有修订流程处理，不在执行代码中静默更换预期。
+- 当前设计要求全量复测时，执行整个有效用例名册，生成本轮逐用例证据。证据时间不早于当前设计，记录结果与报告一致，日志通道满足验证协议；旧 pass 不能替代本轮执行。
+- 带默认输入的载体检查旧页面接线、资源字节、两入口结果及当前构建指纹，历史 pass 不免检；执行及证据字段见资源契约。
+- pass、fail、blocked 等结果及覆盖统计由实际逐用例记录计算，不能只修改计数或移除失败行来宣称通过。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-workspace-layout/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: pc-workspace-layout
+description: 适配工作区布局单一真源 + 工作区初始化脚本。当需要知道工作区目录结构、产物落哪、初始化工作区时使用。触发词：工作区、目录结构、workspace layout、产物落哪、repos-pc、source/patches/build/dist、tests-generated、harmony-demo、harmony-app、.ohos-adaptation-pc、产物归属、初始化工作区、workspace init、clone 源码、工作区骨架、补丁卫生、补丁导出、补丁可复现、patch 末尾换行、git am 验证、git apply corrupt patch、patches 换行符、补丁集重导出、configure 后置补丁。编排器初始化工作区调本 skill 的 scripts/workspace-init.mjs；所有 agent/skill 查布局都引用本 skill（不各自重写）。
+---
+
+# pc-workspace-layout：工作区布局单一真源
+
+## 何时用我
+
+- **编排器初始化工作区**：调 `scripts/workspace-init.mjs`（clone/快照 + 骨架 + manifest）
+- **任何 agent/skill 需要知道产物落哪**：查本 skill 的布局图 + 产物归属硬规则
+- **了解向社区交付的最小包**：哪些目录交付、哪些不交付
+
+> 本 skill 是工作区布局的**单一权威归属**：其他 agent prompt / skill 只引用本 skill，不重写布局。
+
+## CLI 两节点评审
+
+`gate.contract.human_review=true` 时，编排器和涉及改用例的阶段先读 [human-review.md](references/human-review.md)：方案完成后确认；失败修复只有改用例才确认。Web 不启用。记录由内部命令维护在 `.ohos-adaptation-pc/human-review.json`，获批名册修订仅对阶段 2 的指定请求开放。
+
+## 工作区布局
+
+工作区统一 `repos-pc/<lib-or-app>-<ver>/`，原型决定内部结构（库 vs 应用、有无原生依赖）：
+
+```
+repos-pc/<lib-or-app>-<ver>/
+├── source/            ← 上游源码（干净，commit 锁定）— 所有场景
+├── patches/           ← 对上游改造点（可 git am / 追溯）— 所有场景
+│                      ⚠ 补丁文件末尾必须有一个换行符（`\n`），否则 `git apply --check` 报
+│                      `corrupt patch at line N`。写 patch 文件时确保 `echo file >> patches/` 或
+│                      `git format-patch` 天然带换行；手动用文字写出时留意末行加 `\n`。
+├── build/             ← 构建方案（工具链配置 + 脚本 + README，可复现）— 所有场景
+├── tests-generated/   ← 补写的自验证用例（原库无用例时）— 所有场景
+├── dist/              ← 产物（可重建，不交付）— 所有场景
+│   ├── lib/           ← 库产物（.so/.cpython-312.so/.node/wheel/jar）— 库/CLI
+│   └── app/           ← 应用产物（hap/bin/resources）— 应用
+├── deps/              ← 依赖库子工作区（仅未鸿蒙化/需自编的）— 有原生依赖时
+│   └── <dep>-<ver>/{source,patches,build,harmony-demo?,dist}
+├── harmony-demo/      ← 库验证 demo（鸿蒙工程，随库交付）— 仅库
+├── harmony-demo-electron/ ← Node.js 库额外 Electron 基线示例（阶段 03）
+├── harmony-app/       ← 交付应用工程（鸿蒙外壳，提交新仓）— 仅应用
+├── test-demo/         ← PRD 功能点验证 demo（测试线独占）— 仅启用测试线时
+│   ├── build/         ← 该 demo 的构建脚本（不与顶层 build/ 混）
+│   ├── dist/app/      ← 该 demo 的 HAP
+│   └── verify/        ← ★ 测试线的设备证据（逐用例 JSON + device-raw.log）——**绝不落顶层 build/**
+├── test-demo-electron/ ← Node.js 库额外 Electron 功能示例（阶段 06，含独立 verify/）
+└── .ohos-adaptation-pc/   ← 适配过程产物（不交付）
+    ├── manifest.json          ← 总清单（输入 commit、原型、能力域命中、依赖闭包、source_origin）
+    ├── adaptation-report/     ← 适配点分析报告输入（ohos-migration-analysis 运行目录整拷：
+    │                            report.md + .data/；**用户放置，各阶段只读**；场景 skill 的报告驱动
+    │                            模式据此触发——如 Electron 报告驱动模式（pc-schemas 的 adaptation-report-mapping.md），在盘则映射、
+    │                            缺失回退常规扫描）
+    ├── registry-staging.json  ← 适配期暂存登记表（可选；登记候选实际由 summary 校验通过后的 Hook 自动生成到 knowledge/registry/，含 deps_built 逐依赖候选——staging 缺失属正常）
+    ├── adaptation-choice.json ← 方案选择记录（编排器写，无 schema；断点续跑凭它不再重复提问）
+    ├── 00-env.json            ← 环境能力快照（`ohpt-agent env` 写，无 schema；SDK/hvigorw/hdc/NDK/设备探测结果，各阶段直接消费；设备项易变，用前 `--device-only` 复测）
+    ├── 01-scan.json + 01-scan-report.md
+    ├── 02-baseline.json + 02-baseline-report.md
+    ├── gap-ledger.json        ← 阶段 2·补写用例集（L0 功能点 × API：all_apis/touched_apis/gap_apis/disposition[full-case|gap-case|supporting|covered]/supporting_reason/supporting_apis）。字段契约权威 = pc-roster-generation 的 gap-ledger 节；roster-l0-gap-ledger 执法对账
+    ├── run-host.log + run-host.json ← 阶段 2·宿主自证证据（host-run 自己写）
+    ├── cap-out-ledger.json    ← 阶段 2·L1/L2 cap-out 台账（entries[].symbols 是 roster-symbol-budget 对账键）
+    ├── results-partial.json   ← 阶段 3·被切轮次断点状态（completed[]/pending[]/last_alive/residual/ended_by[budget_total|budget_case|watchdog|manual]）。契约权威 = pc-device-verify 断点续跑节；执行器产出参数下批次落
+    ├── 03-adapt.json + 03-adapt-report.md   ← 含 runbook 章节
+    ├── 04-summary.json + 04-summary-report.md    ← 主线出口
+    ├── 05-testcases.json + 05-testcases-report.md  ← 测试线·设计（可选）
+    ├── 06-testdemo.json + 06-testdemo-report.md  ← 测试线出口·生成与真机验证
+    └── knowledge/             ← 经验候选（propose 落此，promote 进个人库）
+```
+
+## 补丁导出与验证协议（patches/ 卫生）
+
+从适配树导出补丁集的标准做法（2026-09-21 实证；对应 04-summary「补丁导出缺口」类 remaining_todo）：
+
+**导出**
+
+- 工作树 CRLF + 库内 LF 时（Windows 宿主常态）：用普通 `git diff`（autocrlf 的 clean filter 规范化，只出内容差异）；`git -c core.autocrlf=false diff` 反而整文件替换。补丁文件纯 LF、无 BOM（Node `writeFileSync`，勿用 PowerShell `Set-Content`）。
+- 新增文件先 `git add -N <file>`（intent-to-add）才进 `git diff`，导完 `git reset` 还原索引。
+- **补丁路径必须 source 相对**（`--- a/<path>`）：补丁验收从 `source/` 目录套用，工作区根视角路径（`a/source/...`）在验收方正反向都套不上。
+- **两段式**：git 跟踪文件 → 手写 mail 头 + `git diff` 拼 git am 格式（am 身份用 `git -c user.name=… -c user.email=…`，禁改任何 git config）；configure 生成物改动（config.h/rules.mk 类生成文件，不进 git）不能进 am 系列 → 重构 before 副本 + `git diff --no-index` + 头部路径改写，并在 README 注明应用时机（configure 之后于 source/ 执行）。能用 `config.cache` 预置 `ac_cv_*` 表达的优先走 cache（pre-configure 正规机制），post-configure 补丁只作手工固化的留痕。
+- `git diff --no-index` 发现差异时**退出码 1**——execSync 会当错误抛出，需捕获后取 `e.stdout`。
+
+**验证四件套**（导完必做）
+
+1. 干净 clone（锁定 commit）按序 `git am` 全部 am 格式补丁，逐条 exit 0；
+2. 内容一致性：am 后 HEAD blob 与适配工作树逐文件比对（工作树 CRLF→LF 归一化后须逐字节相等）；
+3. 反向套用：每条补丁在 source/ 上 `git apply -R --check` 通过（证明精确描述树内增量）；
+4. post-configure 补丁：对重构的 before 副本正向 `git apply --check` 通过；对已应用的当前文件应报 does not apply（非幂等是正确行为）。
+
+- 新文件的 `index 0000000..<hash>` 用 `git hash-object` 核验；空 blob 是 `e69de29`、空串是 `da39a3e`，别把真哈希误判成空（git 的 intent-to-add diff 的 index 行就是真哈希）。
+
+**内联改动防丢**：source/ 树内手工改动不导出成 patches/ ，交付包（patches/ + build/）重建即丢失——「改动已内联 source/（git diff 可追溯）但未导出」是 dist 可重建不变量的镜像缺陷。反向也要防造假：改动真实落点若在 build/ 脚本或 demo 工程（不在 source 树），别为凑数伪造 source 补丁，在 patches/README 写明去向。
+
+## 产物归属硬规则
+
+**代码/可执行物 → 工作区顶层**（source/patches/build/dist/deps/harmony-demo/harmony-app/tests-generated/test-demo）。
+**报告/清单/说明 → `.ohos-adaptation-pc/`**（阶段报告 + manifest + registry-staging + knowledge）。
+
+任何新场景产物必须有明确归属，遵循此规则。
+
+### 阶段归属：谁能写哪些子树
+
+按**流水线位序**列，**两条平级轨道各自成篇**（阶段号是身份不是序号）：
+
+**适配主线**（track=main）
+
+| 阶段 | 产出 | 拥有的子树 |
+|---|---|---|
+| 1 `pc-01-analyze` | 01-scan.json（含 PRD） | `.ohos-adaptation-pc/` |
+| 2 `pc-02-dev-test-cases` | 02-baseline.json（必跑名册） | `.ohos-adaptation-pc/`、`tests-generated/`、`patches/baseline-repair-*` |
+| 3 `pc-03-dev-adapt-code` | 03-adapt.json | `.ohos-adaptation-pc/`、`source/`、`patches/`、`build/`、`dist/`、`deps/`、`harmony-demo\|app/`、`tests-generated/` |
+| 4 `pc-04-summary` | 04-summary.json | `.ohos-adaptation-pc/` |
+
+**测试线**（track=test，可选，默认关）
+
+| 阶段 | 产出 | 拥有的子树 |
+|---|---|---|
+| 5 测试设计 | 05-testcases.json | `.ohos-adaptation-pc/` |
+| 6 Demo 生成与真机验证 | 06-testdemo.json | `.ohos-adaptation-pc/`、`test-demo/`、`tests-generated/`（仅限补写被 blocked 用例的缺失测试程序，见下注） |
+
+`patches/` 整棵属阶段 3，唯 **`patches/baseline-repair-*` 属阶段 2**——让上游在锁定 commit 能编过/能跑（宿主预跑时才可能用到）与鸿蒙化改造是两件事，补丁分开放，用例对照才干净。`tests-generated/` 阶段 2、3、6 共有：阶段 2 在这里补齐覆盖缺口的用例，阶段 3 在这里放设备侧改写，**阶段 6 在这里补写被 blocked 用例的缺失测试程序（归属例外，仅限最小验证程序，不借机改被测产物）**。
+
+测试线只有阶段 6 拥有工作区子树（`test-demo/`，阶段 5 的测试设计只写 `.ohos-adaptation-pc/`），**证据也在里面（`test-demo/verify/`）**：上屏证据判定会匹配顶层 `build/` 下任意 `.jpg/.png/.webp`（递归 3 层），往那里写证据会让阶段 3 的 `verify-verdict.json` 被时效表判过期、白跑一轮 `pc-03-dev-verify`。GUI 载体所需的 OWB 若顶层 `deps/` 已有则复用（只读不写），没有才装进 `test-demo/deps/`。
+
+**「已定稿」只在同轨道内成立**：`.ohos-adaptation-pc/` 里的产物按文件名判归属，而「改写已定稿产物」的判据只看**同一条轨道**里有没有更晚阶段的产物。跨轨道之间没有上下游关系——测试产物在盘时，主线阶段 4 正常写汇总不算篡改。
+
+> 本表由 `ohpt-agent` 的归属执法机制机器核对（PostWrite 时越界即时告警，不阻塞）——它与本表是同一约定的两处表达，任何一处变了另一处也要跟上。
+
+`.ohos-adaptation-pc/` 内**按文件判归属**：各阶段只写自己的 `0N-*.json` / `0N-*-report.md`；`manifest.json`、`00-env.json`、`adaptation-choice.json`、`env-decision.json`、`knowledge/`、`*.log` 为阶段无关的共享文件；`prescan-report.yaml`（编译前扫描报告，`ohpt-agent prescan` 写）与 `prescan-dispositions.json`（critical/high 命中的处置/豁免台账，格式见 pc-error-atlas 的 prescan 节）同为阶段无关的共享文件。**上游阶段的产物是下游的对照基准，改它等于篡改自己的评判标准**——与基准有出入应在本阶段产物里如实记录。判定按「已定稿」执行：某阶段产物在**更晚阶段产物已存在**之后还被改写，才算篡改（自己写自己的产物、方案变更后重扫都不算）。
+
+
+**dist 可重建不变量**：`dist/` 与设备上的运行时树是**可重建产物**——其中任何非上游文件（桩模块、后缀改名、生成物）必须能由 `patches/` 或 `build/` 脚本再生。只存在于 dist/ 或只做在设备上的改动，交付包（patches/ + build/）重建时即丢失。（实证：conda 案例的 menuinst 桩只写在 dist/、pycosat .so 改名只做在设备上——按自报交付包重建会得到缺件运行时。）
+
+## 命名规则
+
+- `harmony-app/` = 交付应用工程（仅应用工作区，是交付物）
+- `harmony-demo/` = 库验证 demo（仅库工作区，随库交付）
+- 两者不会同时出现，靠工作区原型区分（不靠 manifest 字段）。
+- `test-demo/` = **PRD 功能点验证 demo**（测试线产出）。与 `harmony-demo/` 目的不同、可并存：前者答「原库的功能是不是都还在」，后者答「产物能不能在设备上跑起来/上屏」。
+
+## 设备侧应用身份（bundleName / 显示名）
+
+scaffold 生成 demo HAP 时自动定两样**设备侧身份**，命名权威在 `scaffold.ts`（无需 agent 手工改，也不用背着这套规则）：
+
+| 身份 | 规则 | 主线 demo（缺省 out） | 测试线 demo（`test-demo`） |
+|---|---|---|---|
+| bundleName | `com.ohpt.<lib>.<out>` | `com.ohpt.<lib>.harmony_demo` | `com.ohpt.<lib>.test_demo` |
+| 显示名（launcher） | `<lib> demo` / `<lib> test demo` | `<lib> demo` | `<lib> test demo` |
+
+- 显示名落 `AppScope/…/string.json` 的 `app_name`（模板占位 `__APPNAME__`）。主线/测试线加 `test` 后缀是为了桌面可分辨（cximage 2026-09-16 反馈）。
+- **命名只在「全新生成」生效**：`test-demo/` 已存在时 scaffold 走增量同步，不重写 `string.json`/`app.json5`/`module.json5`，旧工程的显示名恒不变（scaffold 增量模式已加告警）。更细的排查边（hvigor 构建缓存、启动器名称缓存）见 `pc-test-design/references/demo-wiring-pc.md` §0。
+
+## 向社区（我们的新代码仓）交付的最小自包含包
+
+剥离 `.ohos-adaptation-pc/`（适配过程产物）和 `dist/`（可重建）后：
+- **库**：`patches/ + build/ + harmony-demo/`
+- **应用**：`patches/ + build/ + harmony-app/`
+- **依赖**：同库（各自 `patches/ + build/ + harmony-demo/`）
+- 启用测试线时另含 `test-demo/`（功能点验证工程，让使用者能自行复跑功能覆盖）
+
+社区使用者：clone 上游 → apply patches → 跑 build → 得产物 / 跑 harmony-demo 验证。
+
+## 路径约定（子 agent 必读）
+
+- **工作区绝对路径由编排器在调用子 agent 的 prompt 首行注入**（Task 工具不传 cwd，子 agent 不依赖 cwd）。
+- 子 agent 每条 bash 命令先 `cd "$WORKSPACE"` 或用绝对路径前缀；所有产物写工作区内。
+- 读 manifest：`$WORKSPACE/.ohos-adaptation-pc/manifest.json`。
+- 读上游源码：`$WORKSPACE/source/`（保持干净，改动走 `patches/`）。
+
+## 初始化工作区（编排器用）
+
+编排器调本 skill 的脚本创建工作区（不放 CLI，CLI 是用户面向的）：
+
+```bash
+node <pc-workspace-layout skill 目录>/scripts/workspace-init.mjs <input> <lib> [version] [--source-ref <分支或标签>] --repos-root <repos-pc 父路径> --json
+```
+
+- `input`：git url / 本地路径 / 当前目录路径
+- 脚本完成：三态识别（git-url/local-repo/local-snapshot）+ source 落位（clone 或 robocopy/cp 拷贝，排除 .git）+ commit 锁定 + 建 `.ohos-adaptation-pc/` + 写 manifest（含 source_origin）+ 校验像不像源码根。
+- **clone 自动重试**：git-url 的克隆失败多为网络/代理/SSL 瞬态（github/savannah/freedesktop 等国外主机直连抖动），脚本自动重试 3 次（间隔 2s，重试前清掉半成品 source/），最终失败才抛错并附可执行排查提示。
+- **源码根校验是根级+嵌套两级探测**：不少上游把构建入口放子目录（7zip 在 `CPP/7zip/makefile`，Windows 工程在 `*.sln`）——根级清单没有命中时，脚本再扫两级子目录（跳过 .git/node_modules/doc/example 等弱证据目录）。命中的入口**持久化进 manifest 的 `build_entry` 字段**（相对 source/ 的路径），续跑会话直接消费、不再人工核实「是不是源码根」。`looksLikeSourceRoot=false` 仅在两级都探不到时出现（真该停下换输入的场合）。
+- **版本探测（省略 version 位置参数时默认开启，`--no-detect-version` 关闭）**：脚本从根目录可信版本文件、构建清单或当前提交的精确语义化标签中保守探测项目版本；分支/标签仅通过 `--source-ref` 传入并只控制 clone。git-url 只 clone 一次（先克隆到 reposRoot 下的 `.staging-*`，探测后 `renameSync` 移入最终目录），**编排器不必、也不应自己 clone 或读源码找版本**。
+- `--json` 返回 `workspaceDir`、`detectedVersion` 与 `versionSource`（探测不到时后二者为 null，工作区按库名命名，属正常）。编排器据 `workspaceDir` 注入子 agent prompt。
+- `alreadyExists=true` → 复用已有工作区不覆盖。未传版本时，脚本先用**续跑探针**按盘上 manifest 的 `(lib, source.ref)` 找已注册工作区——**与输入形态无关**（git url 与本地路径一视同仁），命中唯一则复用、零克隆，命中多个则以退出码 2 报错、需显式传版本号消歧。**目录名只是首次建区时的一次性派生，此后不参与寻址**：源码里的版本变了、`.git` 没了、探测规则升级了，工作区都不改名。
+- **只建 `.ohos-adaptation-pc/` + source/，不预建产物目录**——patches/build/dist/deps/harmony-demo/harmony-app/tests-generated 由 agent 写产物时按需 `mkdir -p`（避免预建一堆空目录）。
+
+脚本自包含（纯 node，不依赖 TS 编译链），符合 `pc-device-verify` skill 自带 scripts 的先例。
+
+
+## 手动远程构建轨道（阶段 7）
+
+默认关闭，仅通过 `OHPT_TRACKS=remote` 显式启用。其他生态、应用和纯运行时库在本地停止。
+独立报告为 `.ohos-adaptation-pc/07-remotebuild.json` 和 `07-remotebuild-report.md`。
+远程配置不进工作区；环境事实存 `00-remote-env.json`。
+`remote-build/` 保存配方、最小构建输入快照、清单和执行 session，不进入阶段 1～6 的判定。
+阶段 7 仅新增 `dist/remote/**` 子树归属（比主线 dist 更具体，优先匹配），并声明上游输入 readOnly，即使主线/测试线未开启也禁止修改，产物落 `<electron-line>/<run_id>/`，不覆盖本地产物。
+不改 source/、build/、dist/lib/、demo 或阶段 1～6 结论；按当前范围不进行 demo 替换或复验。每个远程任务目录随产物保留 README.md 与 artifacts.json 来源说明。
+
+阶段 7 的独立准备 agent 与执行 agent 共享只读边界：输入准备仅写 `.ohos-adaptation-pc/remote-build/`，不修改主线文件；缺配方时自动准备，已有配方校验复用。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-workspace-layout/references/human-review.md

@@ -0,0 +1,63 @@
+# CLI 两节点人工评审
+
+仅 `gate --json` 的 `contract.human_review=true` 时执行本协议。`ohpt start` 默认开启；Web 显式关闭。不得因为用户笼统说“自动/别问”而伪造批准；用户明确关闭本次评审时才关闭开关。没有新增名册评审、普通修复评审或最终交付评审。
+
+## 编排器：功能分析与方案
+
+阶段 1 输出合格 scan 后，gate 返回 `review.checkpoint=plan`、`decision=ask`。即使 easy 也须展示功能范围/排除项、推荐路线、依赖、风险、验证思路和报告路径。原困难路线选择合并在此，不再另外问一次。
+
+- 用户通过当前方案：记录 `approved`。
+- 要求改方案：记录 `changes-requested`，按 `review.next_stage=1` 重调分析，注入用户意见。修订后的具体版本重新确认。选择不同路线时仍写 adaptation-choice.json，再重扫。
+- 不适配：记录 `rejected`，只进入阶段 4 如实总结；不要把人工停止写成技术 infeasible。
+
+答复只由编排器依据**实际收到的用户消息**记录。先写临时 JSON `{ "id": "<gate.review.id>", "decision": "approved|rejected|changes-requested", "response": "<用户原话>" }`，再执行：
+
+```bash
+ohpt-agent human-review -w "$WORKSPACE" --action decide --file <答复JSON绝对路径> --json
+```
+
+不要让模型把自己的推荐意见当答复，不把“继续”自动当作批准；明确批准的当前版本不再重复询问。命令拒绝旧版本时重新展示当前内容，不能删除评审文件。
+
+## 阶段 3：步骤 1–3 全程适用的用例修改评审
+
+产品源码、构建配置、运行时和部署修复自动执行。拟修改测试源码（包括初始化语法和 API 调用参数）、断言、预期值、输入/夹具、测试步骤、选集、超时、豁免/排除时，必须先形成具体候选，再等待确认。首次构建还没跑设备用例时同样适用，不能以“编译修复”“未改断言”为由跳过。日志/注释、既有的等价设备路径映射不单独问。API 契约或功能范围变化回到方案评审，不包装成 fixed-test。
+
+- **历史测试补丁**：从登记库或其他工作区复制时先检查实际 diff。候选可以放到 `build/review-candidates/` 留证，批准前不得复制到会被构建脚本自动应用的 `patches/`，也不得复用已应用该补丁的测试二进制充当本轮结果。历史技术验证不代替本轮批准。
+- **新增豁免**：保留真实 `blocked/not-run` 结果；决定把它作为合法豁免前，展示用例、缺口证据、继续补齐的可行性及覆盖损失。阶段 2 的“可以豁免”备注不是用户批准。纯记录阻塞不必问，不得把 `blocked` 改成 `pass`。
+- **阶段 1/2 已完成的工作不重做**：本检查点仍是“失败归因与修复计划”，没有新增名册生成评审；只在阶段 3 准备改变已有测试或新增豁免时触发。
+
+修改生效文件之前，写提案 JSON（所有字段必填；文件/证据是工作区相对路径）。`files` 列出所有拟修改或新建的生效文件，新文件允许不存在，命令以 `absent` 绑定其未创建状态；`evidence` 必须已经在盘，首次构建可用编译日志和候选补丁作为证据，无需伪造设备日志。提交前先保存真实阶段状态；提交后不要改动被绑定的材料。
+
+```json
+{
+  "loop": 3,
+  "resume_stage": 3,
+  "cases": ["case-name"],
+  "failure": "实际失败结果和对应位置",
+  "diagnosis": "为什么是测试缺陷而非产品缺陷",
+  "before": "原断言/步骤，可附候选 diff 路径",
+  "after": "拟改断言/步骤的精确内容",
+  "basis": ["平台实现/上游依据 file:line 或链接"],
+  "evidence": ["build/device-raw.log"],
+  "files": ["tests-generated/case.c"],
+  "retest": "重建、重部署、受影响用例和回归验证计划"
+}
+```
+
+`ohpt-agent human-review -w "$WORKSPACE" --action request --file <提案JSON绝对路径> --json`。成功后**立即返回编排器**；不改用例、不启动下一轮、不自行答复。提案 schema 为 pc-schemas 下的 test-change-proposal.schema.json。同批修改一次询问。
+
+首次构建时 `loop` 填计划使用的下一轮编号（尚无历史为 1），`failure` 写真实编译失败或材料缺口，`resume_stage=3`；`retest` 写明从步骤 1/2 的哪个缺口恢复及后续设备验证。新增豁免的 `files` 包含 `.ohos-adaptation-pc/03-adapt.json`，`before/after` 列出具体豁免差异。禁止为提交提案预先应用补丁或先写入豁免。
+
+编排器读取 gate.review，展示提案的五项核心材料：失败事实、归因、修改前后、依据影响、重测计划。结束回合等待同意/拒绝/修改意见，使用上面的 decide 命令保存真实答复；此 ask 不写 env-decision.json。
+
+## 获批后的限定恢复
+
+`review.action` 优先于一般的验收分流。按 `review.next_stage` 重跑目标 gate，再调 `review.agent`，注入完整 review；不得因为 03 已存在而起 verifier。
+
+- `approved`：先用 `{ "id": "<id>" }` 调 `--action begin --file <JSON>`，命令验证批准绑定的 scan、baseline、目标文件和证据未变；成功后只应用已展示的修改。`applying` 表示已经 begin，可断点续跑，不重复应用已完成的修改。
+- `rejected`：用 `{ "id": "<id>", "stage": 3 }` 调 `--action complete` 关闭请求（命令确认用例没变），按原标准修产品或如实记录阻塞。
+- `changes-requested` 或材料过期：只补证/修改提案，重新 request 和确认，不能应用旧批准。
+- 改 `02-baseline.json` 时提案必须 `resume_stage=2` 且 files 列明该文件。编排器交阶段 2 限定修订；阶段 3 不得私改名册。阶段 2 begin 后修改获准内容，写合格名册，再以 `{ "id": "<id>", "stage": 2 }` complete，gate 会转阶段 3 重建重测。不要删下游产物。
+- 阶段 3 应用后按原流程重建、部署、真实重测，更新 03 和工具结果（失败仍如实记录），最后 `{ "id": "<id>", "stage": 3 }` complete。首次构建按提案补齐步骤 1/2，不假定旧产物已经可用；获准豁免的用例仍保留真实阻塞结果和依据。随后重新 gate，独立验收依旧执行。
+
+`human-review.json` 由命令写入，保留历史和内容摘要；不可直接手改/删除。查询 `--action status --json` 只读。命令异常（含锁文件冲突）保留现场，先排查，不把失败当批准。等待不进入最终总结；明确终止仍按既有流程处理。派发层对没有新测试结果/补丁的提案轮退回预扣，恢复只计一次，不清空历史额度。