docs: sync farm installation and maintenance guidance

2026-10-27 12:40:01 +08:00 · 2026-10-26 12:41:46 +08:00
parent ac0209f010
commit e5ec38e9d9
6 changed files with 189 additions and 43 deletions
@@ -1,6 +1,6 @@
 # 第一批基础核心实现

-日期：2026-10-15。对应 Comet change：farm-core-foundation。
+更新日期：2026-10-26。对应Comet change：farm-core-foundation。
 已确认规格位于 comet/changes/farm-core-foundation。
 本文件记录实现与开发期测试，不替代 Runtime 的独立验收报告。

@@ -22,11 +22,13 @@
 按职责先采用小模块；随着用例增加再拆分目录，
 不为了贴合远期目录树生成大量空包。
 核心只用标准库，不导入三框架，包内部相对导入。
-wheel 随包携带 JSON，不包含 legacy、图片、玩家数据库或其他框架入口。
+wheel随包携带JSON及小型升级土地素材，不包含legacy、玩家数据库或
+其他框架入口；大型图片ZIP通过匹配的外部资源提供。

 ## 已迁移与修复

- 沿用500初始币、3地块、等级门槛及源作物价格/产量/经验/成熟时间。
+- 注册500初始币、6地块；可靠识别为初始3块的旧号一次性补3块，
+  保留已开垦成果。详见land-rules.md；价格/产量/成熟时间沿用目录。
 - 旧作物库202条记录完整导出且保留源 SHA-256。
 - 多季再生长间隔明确保留去重 phase[1:] 求和，未重平衡数值。
 - F01/F02：余额和经验只增加本次增量。
@@ -66,8 +68,9 @@ SchemaError 表示外来或不兼容库。接入层不能把后两者当作未

 ## 持久化与取消语义

-新库使用独立 application_id、schema_version=1：
-accounts、inventory、plots、operations、ledger。
+新库使用独立application_id，当前schema_version=5，包含accounts、
+inventory、plots、operations、ledger及thefts。受支持旧schema按顺序
+事务升级；迁移失败整体回滚，不手工改版本号。
 未知表集、外来库或更高版本被拒绝，不把旧 farm.db 自动当新库打开。

 每次写用例使用新连接与 BEGIN IMMEDIATE；提交前统一写幂等结果。
@@ -93,12 +96,11 @@ close 拒绝新请求并等待在途任务，无导入时线程或持久数据
 - 首次事务测试有2项因测试代码未关闭连接而在Windows清理失败；
  修复测试资源释放后通过，不隐藏该失败。
 - 最终结果以 Comet 管理的 verification.md 为准。
- 真实框架、旧玩家库、联机、图片和远程发布没有测试或启用。
+- 上述计数为初期历史检查，不是当前完整套件计数；图片、接入与迁移
+  已有后续源码及离线测试，不因此声称真实宿主或生产玩家库已验证。

 ## 正式验收结果

-Runtime已执行完整离线检查并通过。
-独立只读Verifier核对A1至A8后全部判定通过，结果已由Runtime接收；
-正式报告为 comet/changes/farm-core-foundation/verification.md。
-通用Skill桥接不能机器认证独立执行身份，当前等待用户接受结果，
-尚未归档、提交或推送。此状态不等于三框架插件已发布。
+正式结果以Comet生成报告为准，不在本说明预先宣称本轮验收通过。
+当前真寻安装与维护见[zhenxun-preview-current.md](zhenxun-preview-current.md)。
+离线测试、模拟宿主与生产安装/远端发布分别记录，不互相替代。
@@ -1,7 +1,7 @@
 # 共享图片工具与“我的农场”

-状态：共享渲染已实现并通过离线检查和独立只读验收；等待用户接受。
-真实宿主命令与上传仍未接入。
+更新日期：2026-10-26。共享渲染和宿主接入已有实现；实际验收结果
+由Comet报告记录，模拟测试不能证明真实宿主消息发送或客户端显示。
 Python 语法基线3.10；本机实测 Windows/Python3.12.14/Pillow12.3.0。

 ## 安装与职责
@@ -25,7 +25,8 @@ NoneBot、AstrBot、真寻均可调用，不导入任何宿主对象。
 默认使用由 farm_service 分发并缓存的小赖字体（lxgw/kose-font v3.126），原版字体与
 完整 SIL OFL 1.1 许可一同分发，版权声明见
 `src/farm_render/data/OFL-Xiaolai.txt`。插件固定使用小赖字体，不提供
-字体路径配置；开发测试可通过 FARM_TEST_FONT 指定路径。当前
+字体路径网页配置；共享Runtime/绘图API支持显式路径，开发测试可通过
+FARM_TEST_FONT指定路径。当前
 实现校验字体可加载，不保证任意字体具备所有中文、Emoji 字形。

 ## 调用
@@ -33,7 +34,10 @@ NoneBot、AstrBot、真寻均可调用，不导入任何宿主对象。
 ```python
 from farm_render import FarmRenderer, RenderOptions, RenderService

-renderer = FarmRenderer("/path/to/chinese-font.ttf")
+# 素材准备在接入层完成；此处传入与包内清单匹配的本地缓存路径。
+renderer = FarmRenderer(
+    "/path/to/chinese-font.ttf", bundle_path=verified_bundle_path,
+)
 rendering = RenderService(renderer, concurrency=1, max_pending=8)
 try:
    picture = await rendering.my_farm(
@@ -60,7 +64,8 @@ now, options)，统一 now 使用UTC秒整数。正常未注册/存储故障仍

 ## 尺寸、格式和质量

- 普通：1024×624、quality75；RenderOptions.high() 为1536×936、85。
+- 普通默认1024×624、质量75；质量配置整数1～95、默认75。
+- 仅我的农场支持高清1536×936，质量max(配置值,85)，其他查询拒绝高清。
 - 编码格式独立：AUTO、WEBP、JPEG、PNG；WebP method默认2。
 - AUTO仅根据接入层声明的 supported 和本机编码能力选择，默认
  supported只有JPEG。确认平台支持后传入WEBP，才会优先使用它。
@@ -81,8 +86,9 @@ now, options)，统一 now 使用UTC秒整数。正常未注册/存储故障仍

 布局使用旧30块地坐标。新播种及新一季使用虫害工作量计算阶段，
 未启用虫害的迁移前当前季仍从成熟时间和基础时长推导。
-枯萎优先于成熟。作物采用完整画布底边中点统一公式，
-不再使用人工阶段锚点和旧 offset 字段，详见 `15-crop-position-formula.md`。
+枯萎优先于成熟。作物采用schema=4的visible_contact_center统一落点，
+直立等比缩放、保留完整纹理，不再使用人工阶段锚点和旧offset字段。
+当前规则见 `22-crop-scene-mapping.md`；15号文档记录公式演变历史。
 虫子使用场景包中的固定坐标与稳定选帧，规则见 `16-pest-mechanics.md`。

 素材LRU默认32MiB，成图LRU默认8MiB；零预算禁用对应缓存，超限
@@ -113,21 +119,20 @@ scripts/export_render_assets.py将已有素材原样打包，附202种作物
 缺失时显示问号占位并记录静态警告，避免整个命令失败；尚未补齐
 缺失图片，也不推测相近作物素材替代。不会声称202种作物均有完整图片。

-## 原版用户面板恢复（2026-10-16）
+## 当前用户面板（2026-10-26核对）

-使用旧版 `background/userInfo.png` 与 `background/frame/frame.png`，
-按原有顺序叠放底板、140×150头像、头像框和昵称/经验/等级/货币。
-不再用通用圆角信息卡，不额外显示地块数量。无效头像继续安全降级。
-用户确认按原底图校正旧坐标：经验条位于原素材经验槽内，等级与两种
-货币不越出底板。普通、高清图统一按3072基准坐标缩放。
+面板使用metadata.json的panel配置及网页场景切片，按reference_canvas
+映射位置、头像、字段与经验条，不再按旧底板固定坐标绘制。
+头像无效时安全降级，普通与高清按同一面板配置缩放。

-保留旧版经验计算口径：本级已获经验为累计经验减本级累计门槛，
-分母仍为下一级累计经验门槛；等级门槛没有变化。点券取真实账户余额，
+本级已获经验为累计经验减200*level*(level+1)//2，
+分母为本级升级所需经验200*(level+1)，不使用下一级累计门槛。
+点券取真实账户余额，
 不继承旧版硬编码0。素材按目标尺寸缓存，查询仍只读一次一致快照；
 头像字节限制、缓存失效、后台限流和格式选项保留。

-本次离线测量见 `render-panel-restored-benchmark.json`，
-样图在 `runtime/panel-restored`；不代表真实平台发送耗时。
+`render-panel-restored-benchmark.json`及runtime/panel-restored是历史
+面板恢复测量，不代表当前面板或真实平台发送耗时。

 ## 测量与验证

@@ -137,7 +142,10 @@ python scripts/export_render_assets.py --check
 python scripts/verify_foundation.py
 ```

-本轮测量原始结果见 [render-benchmark.json](render-benchmark.json)。
+下表为早期历史测量，原始结果见[render-benchmark.json](render-benchmark.json)。
+2026-10-26新测位于runtime/archive-foundation-20261026/benchmark.json，
+使用当前源码生成六幅1024/1536的WebP、JPEG和PNG图并验证解码与暖缓存；
+本机环境为Windows/Python3.12.14/Pillow12.3。输出目录不进入Git。
 样例为构造的18块解锁地，包含空地、生长、成熟、枯萎与锁定地。
 输出和日志位于runtime/render-demo，不进入Git。

@@ -160,8 +168,6 @@ python scripts/verify_foundation.py
 字节与成图命中，不记录真实姓名、作用域、头像或完整快照。
 上传阶段由适配器单独记录，不能将发送接口返回当作客户端已显示。

-正式检查结果：45项测试全部通过，827文件基线与两类可复现导出
-检查通过。独立只读Verifier核对完整核心/渲染规格和源码后，A1-A13
-全部通过。验收报告见 [Comet报告](
-comet/changes/farm-core-foundation/verification.md)。通用Skill桥接不提供
-机器独立身份认证，流程仍要求用户明确接受后才归档。
+45项测试和早期A1-A13结论属于历史记录；本轮正式结果以Comet生成
+报告为准，不由旧报告推定。真实平台、其他CI矩阵与远端资源可用性
+不属于本机绘图样例的证明范围。
@@ -1,14 +1,16 @@
 # 文档索引

-记录日期：2026-10-15。状态：已形成设计草案，待关键产品决策确认；
-第一批基础核心已实施；多框架接入、发布和真实数据迁移尚未实施。
+更新日期：2026-10-26。共享核心、绘图和三框架接入/打包已有实现；
+本轮仅做本地归档验收，不代表真实宿主、生产数据迁移或远端发布已验证。
+长期设计草案及历史页面须与现行使用说明区分。

 | 文档 | 用途 |
 |---|---|
 | [23-seasonal-events-and-rust-service.md](23-seasonal-events-and-rust-service.md) | 节日活动交互备选、Rust 发布中心、同步、资产事务、过期清理与上线规划（草案） |
 | [09-foundation.md](09-foundation.md) | 已实现的第一批核心、API、测试与限制 |
 | [10-rendering.md](10-rendering.md) | 共享图片工具、农场绘制、缓存、编码与接入 |
-| [11-zhenxun-preview.md](11-zhenxun-preview.md) | 真寻原指令预览、构建/校验/安装和可选同步 |
+| [zhenxun-preview-current.md](zhenxun-preview-current.md) | 当前真寻构建、依赖、安装、配置、数据备份/回退/卸载及发布Secrets |
+| [11-zhenxun-preview.md](11-zhenxun-preview.md) | 旧版页面留档，不作为当前功能和安装依据 |
 | [zhenxun-preview-checks.json](zhenxun-preview-checks.json) | 最终测试包大小/哈希及实际验证边界 |
 | [render-benchmark.json](render-benchmark.json) | 本机合成数据的冷暖缓存与编码测量 |
 | [01-roadmap.md](01-roadmap.md) | 长期目标、实施顺序、里程碑与验收 |
@@ -34,4 +36,4 @@
 - 发布仓库是分发目标，不是 Git 子模块；各框架使用相互独立的插件包。
 - 主仓库远程为 Shu-Ying/main_plugin_farm；本轮未执行远程操作。
 - 用户已撤回拉取要求，且要求删除本地克隆；三个本地检出已删除，不再访问远程。
- 本轮仅修正迁移副本中的硬编码凭据；业务缺陷记录在审查报告，没有隐式修复。
+- 历史迁移预检与后续实现分开记录；当前行为以源码、现行说明和正式验收为准。
@@ -0,0 +1,120 @@
+# 当前真寻农场：构建、安装与维护
+
+更新日期：2026-10-26。本文按当前源码编写；`11-zhenxun-preview.md`
+保留为旧版资料，不能作为当前版本的功能或安装依据。
+
+## 支持范围
+
+主仓库维护共享核心，真寻发布仓库接收生成内容。不要把主仓库的
+`integrations/zhenxun` 直接复制到插件目录：其中没有构建生成的私有
+共享模块和版本文件。使用生成的预览包或对应发布仓库完整内容。
+
+当前支持注册、农场/地块/详情、种子商店、仓库、购买、播种、收获、
+铲除、加锁/解锁、出售，以及已接入的土地操作、虫害和偷菜命令。
+实际参数以“农场帮助”为准。新账号初始500农场币、6块普通空地。
+签到、活动和作物目录在线更新尚未实现；图片/字体下载不等于作物更新。
+
+## 构建和验证
+
+开发或CI环境需要Python3.10及以上、Pillow、PyYAML、setuptools、wheel，
+完整共享测试还需要 `integrations/astrbot/requirements.txt` 中的依赖。
+真寻部署环境沿用宿主提供的NoneBot、真寻和Uninfo；仅安装插件的
+`requirements.txt`，其Pillow约束为 `>=10.4,<11`，不要强制升级宿主到12。
+
+主仓库根目录执行，输出目录必须尚不存在：
+
+```text
+python scripts/ci_font.py
+python scripts/check_workflows.py
+python scripts/verify_foundation.py
+python scripts/build_zhenxun.py --output dist/zhenxun-manual
+python scripts/verify_zhenxun.py dist/zhenxun-manual/zhenxun_plugin_farm_preview-<版本>.zip
+```
+
+将 `<版本>` 替换为构建实际输出的版本。字体脚本优先复用本地合法字体，
+否则下载默认字体；全量测试可显式设置 `FARM_TEST_FONT` 为已准备字体。
+源码方式调用渲染工具时设置 `PYTHONPATH=src`。构建帮助图和图片测试
+需要可用中文字体。完全离线时应提前准备依赖、字体和所需图片缓存。
+
+CI构建任务会上传 `zhenxun-preview` 附件，解包后包含插件ZIP、哈希文件、
+生成仓库及辅助脚本。ZIP和 `FARM-MANIFEST.json` 用于内容一致性验证，
+不能把它们当作发布者身份的密码学签名。
+
+## 安装与升级
+
+1. 停止机器人；备份插件代码和完整数据目录，停用会注册相同原指令的
+   旧农场插件。命令不加测试前缀，不能同时启用旧版和预览版。
+2. 在宿主自己的Python环境安装预览包 `requirements.txt`，保留宿主
+   原有依赖约束。安装脚本不会代为安装依赖或启动机器人。
+3. 使用主仓库辅助脚本，或附件中配套的同名脚本安装：
+
+```text
+python scripts/install_zhenxun.py <插件ZIP完整路径> --plugins-dir <现有插件父目录>
+```
+
+目标目录名为 `zhenxun_plugin_farm_preview`；父目录必须已存在。
+安装器拒绝已有目标、坏哈希、路径穿越及符号链接，不覆盖旧插件或玩家数据。
+升级时停止机器人，手工备份并移走上一版插件目录，再安装已验证的新包。
+
+4. 配置宿主加载该插件，检查下述数据目录及资源配置，再手工启动。
+5. 使用构造的测试账号检查“农场帮助”“开通农场”“我的农场”等命令，
+   查看日志；本仓库的模拟测试不代替该真实宿主验证。
+
+## 配置、数据及日志
+
+| 项目 | 当前行为 |
+| --- | --- |
+| 农场图片质量 | 真寻网页配置，整数1～95、默认75，请求时读取；PNG无损不受影响 |
+| 高清 | 仅“我的农场 高清”，宽1536，质量max(配置值,85)；其他查询拒绝高清 |
+| 资源获取地址 | Github、Gitea、farm_service，默认Github，修改后重载 |
+| farm_service 地址 | 独立HTTPS基础地址，选择服务源时必须有效，不使用示例占位域名 |
+| FARM_PREVIEW_DATA_DIR | 可选宿主启动配置；未设置时使用真寻DATA_PATH下的farm_db目录 |
+| FARM_PREVIEW_DEPLOYMENT | 默认zhenxun-preview；改变它会改变玩家身份作用域，不用于改显示名 |
+| FARM_PREVIEW_IMAGE_FORMAT | 默认AUTO；编码与分辨率分别设置，按宿主能力选择 |
+
+共享核心数据库为数据目录内的 `farm.sqlite3`，运行日志为
+`farm-preview.log`；素材和字体缓存在同一数据目录的独立子目录。
+旧 `farm.db` 与新库不是同一种格式，不得直接覆盖或改名冒充新库。
+生产旧库迁移应使用独立迁移流程和副本预检，不是安装器的行为。
+
+公开素材和小赖字体由Service仓库分发，默认下载后按大小及SHA256校验，
+缓存完整OFL许可。网页不提供自定义字体路径配置；共享Runtime/绘图API
+及开发测试支持显式字体路径。下载失败时保留文字业务并记录原因，
+修改源后重载插件重试。插件包不包含大型素材及字体ZIP。
+
+作物目录仍随插件内置，当前没有启动检查作物目录更新或定时更新。
+已播种规则按快照保存；出售使用当前目录价格，旧库存也受调价影响。
+
+## 备份、回退与卸载
+
+- 备份：先停止机器人，复制完整插件目录与完整数据目录；若存在SQLite
+  的WAL/SHM文件，随数据一起保存，不能在运行中仅复制主数据库文件。
+- 回退：先停止机器人，恢复匹配的代码与停机备份。旧程序可能拒绝新
+  schema，不把新数据库强行交给旧代码，也不删除或重置库来使它启动。
+  恢复旧数据会丢失备份之后的进度，先保留当前副本。
+- 卸载：停止机器人并取消加载，备份后移走本插件代码即可。保留数据
+  和缓存供恢复，不要求删除玩家数据库或旧插件目录。
+
+## 工作流发布与Secrets
+
+主仓库 `main` 的push，或手动运行工作流且选择 `publish=true`，在test与
+build通过后可触发同步；PR只测试构建，不执行跨仓库发布。
+发布固定为 `Shu-Ying/zhenxun_plugin_farm` 的 `main`，并非旧farm-preview。
+它会把目标分支内容更新为生成仓库，发布前应核对目标确为分发仓库。
+
+发布任务使用受保护的 `zhenxun-preview` environment，从Secrets读取
+`FARM_RELEASE_TOKEN`；按组织规则授予固定目标仓库所需的最小写权限。
+不把令牌写进源码、包、命令示例或日志。缺令牌时发布失败，离线
+构建和验证仍不需要发布凭据。
+
+`scripts/publish_zhenxun.py <插件ZIP>` 默认离线dry-run；只有显式
+`--publish` 才联网，并拒绝脏来源包。普通更新不force，检测分支并发
+变化后失败。本轮归档不运行真实发布，不新增或读取任何令牌。
+
+## 本轮证据边界
+
+2026-10-26在Windows/Python3.12.14/Pillow12.3进行了本地离线检查，
+实际命令和验收结论以Comet生成报告为准。NoneBot宿主配置的一项测试
+因本地缺Pydantic而跳过；不能将其说成通过。CI声明Windows/Linux及
+Pillow10.4/12.3矩阵，本机未运行全部矩阵。真实真寻启动、消息发送、
+公开资源下载和GitHub发布均不由本地测试证明。
@@ -50,8 +50,24 @@

 ## 如何安装

-方法一（推荐）：在小真寻后台的插件商店下载即可<br>
-方法二：下载源码放在小真寻`plugin`目录下
+使用真寻分发仓库的完整生成内容或Actions中的真寻预览包，不能直接
+复制主仓库的integrations目录。先停止机器人，备份代码与数据，停用
+会注册同名命令的旧插件，再在宿主环境安装本插件requirements.txt。
+Pillow要求>=10.4,<11，不强制升级宿主到12。安装后手工启动并检查日志。
+
+默认数据目录为真寻DATA_PATH下的farm_db，新库为farm.sqlite3，日志为
+farm-preview.log；旧farm.db不得直接改名覆盖。资源源默认Github，可在
+网页配置选择Gitea/farm_service；服务地址独立保留，修改资源源后重载。
+图片质量默认75、整数1～95，仅“我的农场 高清”支持高清且质量至少85。
+资源或字体下载失败时文字业务仍可用，详细原因见日志。
+
+升级前停机备份完整代码与数据目录；安装器拒绝覆盖，先移走旧目录。
+回退需匹配代码和数据库备份，不让旧代码强行打开新schema；恢复旧数据
+会丢失备份后进度。卸载时停止加载并移走插件代码，保留数据供恢复。
+
+开发者构建、包验证、安全安装、配置、备份卸载与Secrets详见
+[当前维护说明](https://github.com/Shu-Ying/main_plugin_farm/blob/main/docs/zhenxun-preview-current.md)。
+本地离线验证不代表真实真寻宿主、公开资源或远端发布已验证。

 ---

@@ -64,8 +80,8 @@

 - [x] 完善我的农场图片，例如左上角显示用户数据
 - [ ] 完善升级数据、作物数据、作物图片
- [x] 签到功能
- [x] 在线更新作物信息
+- [ ] 签到功能
+- [ ] 在线更新作物信息（当前作物目录仍随插件内置）
 - [ ] 添加渔场功能
 - [ ] 增加活动、交易行功能
 - [ ] 增加交易行总行功能
@@ -10,7 +10,7 @@
      "observed_default_branch": "main",
      "entry_directory": "integrations/zhenxun",
      "enabled": true,
-      "preview_branch": "farm-preview",
+      "preview_branch": "main",
      "publish_by_default": false
    },
    {