docs: codify free PyArmor Trial packaging guidance

CHANGELOG.md

@@ -9,6 +9,11 @@
 - 小节正文写用户能看懂的变化（新能力、修复、注意事项），避免堆砌内部实现细节
 - 打 tag 前**必须**为即将发布的版本新增一节；找不到匹配小节时，本次发布不会更新 changelog 字段
 
+## 1.0.125
+
+- 固化免费 PyArmor Trial 发布约定：行数门槛是预防线；实际失败时按日志定位模块并按职责拆分，保留兼容门面，以 Gitea Trial 加密结果验收
+- 记录 field_locator 拆分后同一免费 Trial 链路成功的复盘案例；不使用未经验证的统一字节数阈值
+
 ## 1.0.124
 
 - 沉淀宿主能力：Excel 导入模板按列元数据自动加下拉（有可选集合的列展示 label；CSV 无下拉）；技能只需声明 `_jiangchang_columns` 选项即可受益

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 技能开发模板（通用业务版）
 description: "OpenClaw 通用业务技能开发模板，供复制后定制新业务 skill。定制步骤见 development/DEVELOPMENT.md。"
-version: 1.0.124
+version: 1.0.125
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:

development/DEVELOPMENT.md

@@ -213,6 +213,14 @@ release workflow 会对 `scripts/` 下的 Python 源码做加密/打包。当前
 - 不要把完整 RPA 主流程、DOM 选择器、数据库、CLI、日志全部堆进一个大文件。
 - 正确做法是拆分到 `scripts/cli/`、`scripts/service/`、`scripts/db/`、`scripts/util/`。
 
+以上行数是预防性硬门槛，**不是 Trial 加密成功的充分条件**。PyArmor Trial 对具体源码模块的限制不能用一个未经验证的字节数阈值代替；即使文件低于 1000 行，实际加密仍可能因单个模块过大或过于复杂而失败。免费模式下的处理约定：
+
+1. 以 Gitea release workflow 使用的 Trial 加密步骤和目标平台为准做实际验证；查看日志确认失败发生在哪个 `.py` 文件，不以本地行数检查通过推断加密一定成功。
+2. 若日志指出某个模块加密失败（例如 Trial license / big script 一类限制），按职责把该模块拆成更小的实现模块；原文件保留为兼容门面，重导出原有公开函数、类或常量，避免改坏已有 import 路径。
+3. 拆分后先跑完整测试，再升补丁版本并 release；检查 Gitea job 中所有 Python 模块均已加密、加密包成功生成/上传且 job 最终成功。失败时继续针对日志定位的模块拆分并重新验证，不放宽免费模式、不猜统一字节上限。
+
+模板案例：得一智慧审单的 `field_locator.py` 在免费 Trial 加密阶段失败；按职责拆分为多个实现模块并保留原文件兼容门面后，同一免费 Trial 发布链路成功。这个案例用于说明应对**具体失败模块做职责拆分并复验**，不作为其他技能的固定文件字节数阈值。
+
 `examples/` 里的 Python 示例也建议保持模块化，但**行数限制不作为 examples 的发布硬约束**；不要对 README、HTML、测试数据等文档/资源套用 PyArmor 行数规则。
 
 **文本编码（UTF-8 without BOM）**

development/POLICY_MATRIX.md

@@ -24,7 +24,7 @@
 | POLICY-RPA-005 | 必须保留 AI + RPA 总纲，明确 Agent / RPA 职责、授权范围、禁止破解/逆向/私有协议/安全验证绕过、人工介入、状态等待；真实业务默认动作节奏为 1～3 秒 | development/AI_RPA.md §4–§6；development/RPA.md §0.0/§0.3 | hard（文档与默认配置） / soft（真实行为） | 检查总纲关键边界；解析 `.env.example` 的 `STEP_DELAY_MIN=1.0` / `STEP_DELAY_MAX=3.0` | `tests/test_development_policy_guard.py::TestPolicyRpa005` |
 | POLICY-RPA-006 | 浏览器 RPA 必须保留 account-manager 生命周期标准；所有样例账号选择路径都须返回非空 `profile_dir + lease_token`，指定数字账号 ID 不得退化为无租约 `account get` | development/ACCOUNT_MANAGER.md；development/ADAPTER.md §兄弟依赖；development/RPA.md §0.2 | hard | 检查标准文档关键标记；扫描真实/仿真 `account_client.py` 的指定 ID 带租约实现并禁止空租约赋值 | `tests/test_development_policy_guard.py::TestPolicyRpa006` |
 | POLICY-RPA-007 | 网页 RPA 启动须 `no_viewport=True` + `--start-maximized`；禁止 `viewport=None`、CDP/JS 中途改窗；`RPA.md` §1.2.1 须保留窗口标准 | development/RPA.md §1.2.1；development/RPA_BROWSER.md §4；examples/real_browser_rpa | hard | 文档标记 + 扫描含 `launch_persistent_*` 的 Python 禁止模式；校验 real_browser 示例 | `tests/test_development_policy_guard.py::TestPolicyRpa007` |
-| POLICY-PACKAGING-001 | `scripts/**/*.py` 单文件 < 1000 行 | development/DEVELOPMENT.md §3.4 发布打包约束；development/RUNTIME.md §发布打包约束 | hard | 行数统计 | **已有测试覆盖**：`tests/test_release_packaging_constraints.py::test_scripts_py_files_under_pyarmor_line_limit` |
+| POLICY-PACKAGING-001 | `scripts/**/*.py` 单文件 < 1000 行；该门槛不保证 Trial 加密成功。免费 Trial 实际失败时按报错模块拆分职责、保留兼容门面，并以 Gitea 实际加密 job 成功作为发布验收 | development/DEVELOPMENT.md §3.4 发布打包约束；development/RUNTIME.md §发布打包约束 | hard | 行数测试 + Trial 发布 job 结果 | **已有测试覆盖**：`tests/test_release_packaging_constraints.py::test_scripts_py_files_under_pyarmor_line_limit`、`test_trial_packaging_guidance_is_documented`；实际加密由 Gitea release workflow 验证 |
 | POLICY-PACKAGING-002 | 文本文件 UTF-8 without BOM，无 `U+FEFF` | development/DEVELOPMENT.md §3.4；development/RUNTIME.md §编码与输出 | hard | BOM / 解码检查 | **已有测试覆盖**：`tests/test_release_packaging_constraints.py::test_text_files_are_utf8_without_bom` |
 | POLICY-RELEASE-001 | 发布 tag（去掉前缀）必须等于 `SKILL.md` 的 `version:` 且等于 `scripts/util/constants.py` 的 `SKILL_VERSION`；`release.ps1` 打 tag 前硬失败，不自动改写字段 | development/DEVELOPMENT.md §15 发布；宿主市场「最新版本」来自 tag、「当前版本」来自包内 `SKILL.md` | hard | `release.ps1` 门禁 + 日常版本字段对齐测试 | `release.ps1`（`Assert-SkillReleaseVersionAlignment`）；`tests/test_development_policy_guard.py::TestPolicyRelease001`；`tests/test_skill_metadata.py::test_skill_version_alignment` |
 | POLICY-DOCS-001 | 本矩阵存在且包含上述全部 `policy_id` | 本次规范化约定 | hard | 解析 `development/POLICY_MATRIX.md` | `tests/test_development_policy_guard.py::TestPolicyDocs001` |

development/RUNTIME.md

@@ -140,6 +140,8 @@ RPA 录屏成片（`RpaVideoSession`）、ffmpeg 路径、背景音乐探测均
 
 release workflow 加密 `scripts/` 源码时，可能运行在 PyArmor 免费/试用模式：
 
-- `scripts/**/*.py` 单文件必须 **< 1000 行**（`>= 1000` 可能在 CI 失败）；推荐 **< 900 行**。
-- 接近上限时拆分到 `cli/`、`service/`、`db/`、`util/`，不要把 RPA 主流程、选择器、DB、CLI 堆进单文件。
+- `scripts/**/*.py` 单文件必须 **< 1000 行**（`>= 1000` 可能在 CI 失败）；推荐 **< 900 行**。这是预防性硬门槛，不代表低于该行数就一定能被 Trial 加密。
+- 模块应按职责拆分到 `cli/`、`service/`、`db/`、`util/`；不要把 RPA 主流程、选择器、DB、CLI 堆进单文件。发现某个文件在免费 Trial 加密时报错时，按报错定位该文件并继续拆分其职责，重新走实际加密验证；不要通过猜测统一的源码字节数阈值代替验证。
+- 拆分已有模块时，尽量保留原模块作为兼容门面（re-export / 委托到新模块），避免破坏现有 import 路径；先跑测试，再发布验证。
+- 发布验收以 Gitea release workflow 中实际的 PyArmor Trial 加密结果为准：确认全部 `scripts/**/*.py` 均成功加密、加密包成功生成/上传且 job 成功。若 PyArmor 步骤失败，不得把版本视为已发布成功；按日志中的失败文件拆分、升补丁版本并重新 release。
 - 此行数限制**仅适用于** `scripts/**/*.py`；不限制 README 等文档行数，也不把 examples 里的 HTML/README 纳入 PyArmor 行数约束。

development/TESTING.md

@@ -32,7 +32,7 @@
 - Skill Action manifest：`assets/actions.json` 结构、CLI 映射、placements 与 inputSchema 守护（见 `test_actions_manifest.py`）；
 - 标准时间字段：`created_at` / `updated_at` 默认值、trigger 维护与 `datetime_unix_seconds` 元数据（见 `test_timestamp_columns.py`）；
 - **adapter profile**：[`tests/test_adapter_profile_policy.py`](../tests/test_adapter_profile_policy.py) + [`adapter_test_utils`](../tests/adapter_test_utils.py) ——验证在未授权情况下绝不误判开启真实网络/RPA。
-- **发布打包守护**：[`tests/test_release_packaging_constraints.py`](../tests/test_release_packaging_constraints.py) ——`scripts/**/*.py` 单文件 < 1000 行、文本文件 UTF-8 without BOM。
+- **发布打包守护**：[`tests/test_release_packaging_constraints.py`](../tests/test_release_packaging_constraints.py) ——`scripts/**/*.py` 单文件 < 1000 行、PyArmor Trial 拆分/实际发布验证约定、文本文件 UTF-8 without BOM。行数通过只表示通过预防性门槛；免费 Trial 是否能加密成功仍以 Gitea 实际加密 job 为准。
 - **开发规范守护（hard policy）**：[`tests/test_development_policy_guard.py`](../tests/test_development_policy_guard.py) ——规则索引见 [`development/POLICY_MATRIX.md`](POLICY_MATRIX.md)，只执行可机器检测的 hard 规则。
 - **slug 语义**：[`tests/test_slug_naming.py`](../tests/test_slug_naming.py) ——动词-名词命名；平台可选，`default` 不再作为占位。
 - **HTML 报告壳**：[`tests/test_html_page_service.py`](../tests/test_html_page_service.py) 守护 `assets/html/example-report.html` 的数据管理 iframe 预览布局基线，并守护 ACTIONS.md 里的壳子页目录 `assets/html/pages` 与 `jiangchang.call`。业务技能若有自定义 `assets/html/*.html` 或 `pages/*.html`，建议在自有仓库加同类静态断言（见 `references/ACTIONS.md`「宿主预览布局」）。不要把 `example-report.html` 放进 `pages/`。

scripts/util/constants.py

@@ -1,6 +1,6 @@
 """技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""
 
 SKILL_SLUG = "your-skill-slug"
-SKILL_VERSION = "1.0.124"
+SKILL_VERSION = "1.0.125"
 LOG_LOGGER_NAME = "openclaw.skill.your_skill_slug"
 PLATFORM_KIT_MIN_VERSION = "1.2.11"

tests/test_release_packaging_constraints.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""发布打包守护：PyArmor 单文件行数与 UTF-8 without BOM。"""
+"""发布打包守护：PyArmor Trial 约定、单文件行数与 UTF-8 without BOM。"""
 from __future__ import annotations
 
 import os
@@ -89,6 +89,26 @@ def _iter_scripts_py_files(skill_root: str) -> list[str]:
 
 
 class TestReleasePackagingConstraints(unittest.TestCase):
+    def test_trial_packaging_guidance_is_documented(self) -> None:
+        skill_root = get_skill_root()
+        runtime_path = os.path.join(skill_root, "development", "RUNTIME.md")
+        development_path = os.path.join(skill_root, "development", "DEVELOPMENT.md")
+        with open(runtime_path, encoding="utf-8") as f:
+            runtime = f.read()
+        with open(development_path, encoding="utf-8") as f:
+            development = f.read()
+
+        required_guidance = {
+            "free/trial mode": (runtime + development, "Trial"),
+            "line limit is not sufficient": (runtime + development, "不是 Trial 加密成功的充分条件"),
+            "split the failing module by responsibility": (runtime + development, "按职责"),
+            "preserve compatibility imports": (runtime + development, "兼容门面"),
+            "verify real release encryption": (runtime + development, "实际加密"),
+            "inspect Gitea release result": (runtime + development, "Gitea"),
+        }
+        missing = [label for label, (text, needle) in required_guidance.items() if needle not in text]
+        self.assertEqual(missing, [], msg=f"Missing PyArmor Trial guidance: {missing}")
+
     def test_scripts_py_files_under_pyarmor_line_limit(self) -> None:
         skill_root = get_skill_root()
         offenders: list[str] = []
@@ -104,8 +124,9 @@ class TestReleasePackagingConstraints(unittest.TestCase):
             offenders,
             [],
             msg=(
-                "PyArmor trial/free mode may fail when a single Python file reaches "
-                f"{SCRIPTS_MAX_LINES} lines; split this file into smaller modules. "
+                "PyArmor trial/free mode has a preventive single-file line guard; "
+                "passing it does not guarantee Trial encryption succeeds. Split any "
+                "module identified by the actual Trial release error. "
                 f"Recommended keep each file < {SCRIPTS_RECOMMENDED_MAX_LINES} lines. "
                 f"Offenders: {offenders}"
             ),