mirror of
https://github.com/Shu-Ying/main_plugin_farm.git
synced 2026-10-31 06:49:59 +08:00
chore(native): archive farm-core-foundation
This commit is contained in:
@@ -0,0 +1,107 @@
|
||||
# Farm Core Foundation
|
||||
|
||||
本规格定义第一批框架无关基础核心的完整行为，覆盖注册、配置、
|
||||
资产库存、种植交易、文本展示和本地持久化。
|
||||
真实机器人入口、联机和旧玩家数据迁移不在本 capability 范围内。
|
||||
|
||||
## Runtime and migration boundary
|
||||
|
||||
共享代码位于 src/farm_core，包内部相对导入；加载模块不执行网络、
|
||||
创建数据库或启动线程。可注入显式配置、时钟与存储生命周期。
|
||||
静态作物目录从保留的旧作物库离线导出，发布或安装后不依赖 legacy。
|
||||
完整静态目录与玩家数据库分开保存，旧基线保持只读。
|
||||
SQLite 工作在线程中执行且每个用例拥有完整事务，异步调用可等待结果。
|
||||
|
||||
Scenario: Independent core and preserved baseline
|
||||
Acceptance: A1
|
||||
基线离线校验通过，包独立导入、安装、调用不需要三种宿主或 legacy。
|
||||
|
||||
## Catalogue
|
||||
|
||||
迁移基线含202条作物且当时名称唯一；运行时以稳定本地ID为身份，
|
||||
允许同名，名称查询拒绝歧义，支持#编号。映射id/name/level/buy/isVip/vipBuy/
|
||||
experience/harvest/price/time/crop/phase 等必要数据，规范整数数值，
|
||||
异常的字段或版本错误明确拒绝。购买使用对应币种，按等级校验。
|
||||
不下载远程目录，不将素材路径或绘图偏移当作业务依赖。
|
||||
多季再生长间隔保持旧去重 phase[1:] 求和规则，不在首轮重新平衡。
|
||||
|
||||
Scenario: Reproducible catalogue migration
|
||||
Acceptance: A2
|
||||
离线导出再生成内容一致；202 条与源值匹配；损坏输入被拒绝。
|
||||
|
||||
## Registration and account model
|
||||
|
||||
调用方提供 deployment/realm/platform/user 字符串身份，核心不推断账号
|
||||
等价性或跨群共享。首次注册赠送500 point、0 vipPoint、0 exp、6空地。
|
||||
唯一身份只能领取一次初始资产。查询总是基于已提交数据库状态。
|
||||
可靠识别为初始3块的旧用户一次性追加3块普通空地，保留已开垦成果；
|
||||
并发、重试和重启不得重复补偿，来源不明和数量异常明确拒绝。
|
||||
经验等级门槛为 200*k*(k+1)//2，使用整数边界计算。
|
||||
货币、数量和时间范围必须适合 SQLite 整数及应用限制。
|
||||
bool 不作为合法整数参数，不允许负数归零后当作交易成功。
|
||||
|
||||
Scenario: Immediate registration and scope isolation
|
||||
Acceptance: A3
|
||||
首次注册立即查询得到默认值；重复注册无增发；不同作用域相互独立。
|
||||
|
||||
## Purchase and sowing
|
||||
|
||||
购买种子时在同一用例事务内检查注册、作物、数量、等级和余额，
|
||||
扣款并增加库存，失败整体回滚。播种检查空地和库存，在同一事务内
|
||||
消耗实际种子、创建作物实例，保存结算所需目录数据避免后续版本改变
|
||||
已播种作物。显式数量超过可用资源返回明确结果，全部操作使用明确
|
||||
参数而不是允许任意负数。返回真实操作数、余额及剩余库存。
|
||||
|
||||
Scenario: Purchase and sow atomically with validated inputs
|
||||
Acceptance: A4
|
||||
非法数量、余额不足、等级不足和库存不足不产生任何部分状态。
|
||||
|
||||
## Harvest and crop lifecycle
|
||||
|
||||
首熟为播种时间加 time*3600；使用可注入时钟，当前时间等于成熟时可收。
|
||||
每块地独立计算 floor(base*(100+bonus)/100) 后相加，不对累计值加成。
|
||||
经验只增加本次增量。播种每地另加2经验、铲除每地另加2经验；
|
||||
“历史100”指收获操作前已提交的经验。
|
||||
产物入库、经验变动、收获次数和下一季状态
|
||||
在同一事务提交。最后一季后枯萎；铲除只清理枯萎地块。
|
||||
再次重试不重复收获。展示结果不再次修改数据。
|
||||
|
||||
Scenario: Correct experience and multi-crop settlement
|
||||
Acceptance: A5
|
||||
历史100加本次20等于120；地块排序不影响总收益；成熟边界及多季状态正确。
|
||||
|
||||
## Inventory locking and selling
|
||||
|
||||
指定出售和全部出售均保护锁定物品。出售收入在事务内增加一次，
|
||||
库存减少为实际成交数量。没有可出售物品时有明确结果。
|
||||
查询及返回结构化账户/库存/地块数据，基础文本仅渲染结果，避免模板
|
||||
占位不匹配；文本不依赖任何消息框架。
|
||||
|
||||
Scenario: Consistent locking and exact sale proceeds
|
||||
Acceptance: A6
|
||||
100余额出售收入20变为120；锁定物品无法通过任一出售入口消耗。
|
||||
|
||||
## Persistence, idempotency and failures
|
||||
|
||||
每个写用例有稳定 operation_id、动作和规范化参数指纹。
|
||||
同作用域同标识相同请求返回已提交结果，不再次扣款或发奖；
|
||||
不同参数冲突拒绝。状态改变、资产流水和结果持久化在同一事务。
|
||||
数据库异常应回滚并传播为明确错误，不能转成不存在/无农场。
|
||||
支持并发调用，通过事务、条件更新及唯一约束避免超卖和重复结算。
|
||||
关闭后重开可读取已提交数据；未知/高版本 schema 拒绝。
|
||||
调用取消不能无记录重复交易，已提交结果可通过相同操作标识恢复。
|
||||
|
||||
Scenario: Rollback, replay and concurrent safety
|
||||
Acceptance: A7
|
||||
故障注入无部分数据；重试幂等；冲突被拒绝；并发不透支；重启后状态一致。
|
||||
|
||||
## Verification and user documentation
|
||||
|
||||
离线测试采用构造数据，覆盖上述全部验收示例以及源目录一致性。
|
||||
提供本地运行/演示入口，不宣称可放入三种框架插件目录加载。
|
||||
记录本轮新实现与旧缺陷对应关系，不把历史设计文档误标为全面完成。
|
||||
不安装或操作真实机器人，不访问远程仓库，不导入真实玩家数据库。
|
||||
|
||||
Scenario: Repeatable local verification and accurate status
|
||||
Acceptance: A8
|
||||
安装及离线测试命令可复现，使用说明清楚标明未实现的接入与发布部分。
|
||||
@@ -0,0 +1,77 @@
|
||||
# Farm Render
|
||||
|
||||
## Independent image layer
|
||||
|
||||
farm_render 使用 Pillow 实现同步画布操作；farm_core 不依赖 Pillow。
|
||||
工具支持透明合成、复制、缩放、裁剪、文本测量与超长省略，以及
|
||||
WebP/JPEG/PNG 编码。JPEG 合并透明背景，输出携带 MIME、尺寸与字节。
|
||||
WebP 默认采用有损质量75、method=2；高清质量为max(配置质量,85)。格式与尺寸独立，
|
||||
auto 根据调用方声明的平台能力选择 WebP 或 JPEG，本机无 WebP 编码
|
||||
支持时 auto 回退 JPEG，显式 WebP 则清楚报错。PNG 保留无损选项。
|
||||
开发素材独立生成，不在运行时引用 legacy 或宿主。插件携带轻量元数据
|
||||
及绑定摘要的素材清单，大型 assets.zip 从所选源校验下载并缓存，
|
||||
不打入插件发布包；小型升级土地素材仍随包提供。中文字体支持显式
|
||||
配置，或独立校验下载原版小赖字体及完整 OFL 许可，不复制 Windows
|
||||
商业字体。无可用素材或字体时接入层降级文字，不输出缺字占位图。
|
||||
|
||||
Scenario: Framework-independent packaged renderer
|
||||
Acceptance: A9
|
||||
从 wheel 安装到临时目录，无 legacy 和框架，显式提供已校验的外部
|
||||
素材及字体后仍可生成图片；下载与校验止于接入/资源准备层。
|
||||
|
||||
## Snapshot and layout
|
||||
|
||||
入口从业务服务取得一次一致快照；绘图纯消费快照与统一 now，不查库。
|
||||
复用旧30块地布局、季节静态背景、草地/普通地和作物阶段素材。
|
||||
首季阶段锚点由保存的 mature_at-growth_seconds 推导，再季使用
|
||||
mature_at-regrowth_seconds，按本季时长映射展示阶段，成熟优先、
|
||||
枯萎优先于成熟。阶段仅影响外观，不修改交易规则和数据库。
|
||||
作物定位采用 schema=4 的 visible_contact_center 统一公式，按本地
|
||||
土地中心落点，保留完整纹理和直立等比缩放，不使用旧 offset 字段
|
||||
或逐阶段手调锚点。地块位置按当前稳定编号映射。缺失作物资源使用
|
||||
显式占位并记录警告。
|
||||
用户信息显示真实快照余额、点券和经验，头像仅接收字节，无头像时
|
||||
绘制默认图；拒绝超大或无效头像并降级。主题由调用方明确提供。
|
||||
|
||||
Scenario: Farm states and target profiles
|
||||
Acceptance: A10
|
||||
空地、生长、成熟、再生长、枯萎和未解锁地可生成图片，普通与高清
|
||||
使用同一布局；统一时间下同一阶段稳定，边界切换正确。
|
||||
|
||||
## Resource and result cache
|
||||
|
||||
普通图默认宽1024，高清宽1536；画布与坐标从开始按比例处理。
|
||||
解码后素材、底图和成图使用有界 LRU，超限条目不入缓存。
|
||||
素材缓存键含路径及目标尺寸，缓存图片只读或复制后修改。
|
||||
成图键含完整身份、可见地块阶段/账户/头像摘要、主题、质量与格式；
|
||||
同阶段可复用，下一阶段或成熟时间到达必须改变键，静态素材版本
|
||||
由渲染器实例绑定；资源更新后重新创建实例。默认缓存不落盘。
|
||||
|
||||
Scenario: Bounded and correct caching
|
||||
Acceptance: A11
|
||||
缓存总字节不超上限；跨账号不串图，阶段、余额、头像变化不命中旧图；
|
||||
普通图绘制画布即为1024宽，无3072宽中间合成画布。
|
||||
|
||||
## Controlled asynchronous entry
|
||||
|
||||
提供异步入口，将整张图的合成与编码交给后台线程；默认最多一个
|
||||
任务运行，等待队列有上限。相同身份/状态请求共享任务。调用取消
|
||||
不取消正在运行的共享绘制，也不提前释放容量。关闭等待任务排空。
|
||||
日志只记录查询/排队/合成/编码耗时、字节、尺寸和缓存结果，不记录
|
||||
真实用户标识、姓名、头像、凭据或完整快照。
|
||||
|
||||
Scenario: Concurrency, cancellation and diagnostics
|
||||
Acceptance: A12
|
||||
慢绘图时事件循环仍可工作；同时运行数有界，重复请求共享任务，
|
||||
失败可重试；取消后后台完成并正确释放容量，关闭无残留任务。
|
||||
|
||||
## Verification and usage
|
||||
|
||||
提供明确中文字体路径的离线示例，使用构造数据和临时数据库，
|
||||
报告冷暖耗时、尺寸、三种编码字节及缓存占用。测量仅代表本机样例，
|
||||
不宣称低配服务器耗时或真实平台上传性能。保留核心离线验证与
|
||||
旧基线校验，不接入/重启真实机器人，不访问远端。
|
||||
|
||||
Scenario: Repeatable offline rendering
|
||||
Acceptance: A13
|
||||
离线样例可解码，性能报告真实可复现，文档提供接入调用和未验证边界。
|
||||
@@ -0,0 +1,96 @@
|
||||
# 真寻可安装预览包
|
||||
|
||||
## 接入边界
|
||||
|
||||
全部图片采用统一整数编码质量（1～95，默认75）。真寻网页配置名称为
|
||||
“农场图片质量”，普通NoneBot接入使用FARM_IMAGE_QUALITY。真寻请求时
|
||||
读取配置；无效值明确拒绝并保留已有有效配置，不静默夹取范围。
|
||||
只有“我的农场 高清”可覆盖默认尺寸至1536宽，质量max(配置值,85)。
|
||||
地块编号、详情、种子商店、我的种子和我的作物拒绝高清参数，保留既有
|
||||
分页和仓库文字查询。编码质量随各类渲染输入传递并进入图片缓存键。
|
||||
PNG继续无损输出，质量参数不改变PNG清晰度。默认其他图片尺寸不变。
|
||||
|
||||
Scenario: 全局图片质量及仅农场高清
|
||||
Acceptance: A19
|
||||
配置1和95可用；0、96、布尔及小数拒绝。所有图片按配置编码且不同质量
|
||||
不共享成图。农场高清为1536宽，质量至少85且不低于配置；其他命令高清
|
||||
返回明确参数错误，仓库分页和文字仍可用，帮助不再宣称其他命令支持高清。
|
||||
|
||||
本 capability 验收真寻接入；NoneBot/AstrBot 已有独立接入与打包，
|
||||
不将其当前存在误报为未实现。业务和图片仍来自主仓库共享源码。接入层加载插件
|
||||
私有_vendor命名空间，渲染层对farm_core的引用在构建时改为私有相对
|
||||
导入，不修改开发源码、不污染全局sys.path或sys.modules别名。
|
||||
命令不增加测试前缀，沿用开通农场、我的农场、农场帮助、我的种子、
|
||||
我的作物、购买种子、播种、收获、铲除、作物加锁、作物解锁、出售作物
|
||||
等原指令，覆盖帮助、注册、我的农场、仓库、购买、
|
||||
播种、收获、铲除、锁定/解锁和出售；复用已有规则，不移植旧损坏模块。
|
||||
部署标识由配置给出，同一平台玩家在本预览部署内共享农场，不跨平台
|
||||
绑定；测试数据位置与旧版不同。事件标识包含机器人、平台、用户及
|
||||
原消息标识；无法获得稳定消息标识时写操作明确拒绝，不能随机重试。
|
||||
在启动时初始化存储、渲染器，在关闭时等待任务排空后关闭存储；字体
|
||||
支持显式配置合法中文字体，或校验下载原版小赖字体及完整许可。
|
||||
资源源可选 Github、Gitea、farm_service，默认 Github；服务地址独立
|
||||
保留。缺少资源或字体时保留文字功能，日志明确原因。头像失败降级，
|
||||
不让头像下载无限等待。本次不包含作物目录远程更新。
|
||||
|
||||
Scenario: 真寻命令与生命周期
|
||||
Acceptance: A14
|
||||
模拟宿主验证命令路由、身份/幂等标识、异常反馈与启动关闭，使用独立库；
|
||||
不把模拟宿主测试报告为真实平台发图成功。
|
||||
|
||||
## 产物
|
||||
|
||||
scripts/build_zhenxun.py按白名单复制真寻接入、farm_core、farm_render、
|
||||
对应轻量数据、升级土地素材、LICENSE及NOTICE；大型图片及字体 ZIP
|
||||
不进入插件包。ZIP含单一插件根目录，仓库导出目录
|
||||
可作为真寻发布仓库根。生成来源manifest与独立SHA256附件，清单不
|
||||
自包含哈希；本地工作区脏时标识dirty，不能冒充源HEAD的纯净构建。
|
||||
输入版本严格校验，ZIP排序/时间固定，目标存在则拒绝或显式选择新路径。
|
||||
不打包其他适配器、运行库、凭据、缓存、legacy或全局字体。
|
||||
|
||||
Scenario: 可复现白名单打包
|
||||
Acceptance: A15
|
||||
重复构建内容相同，独立目录导入私有模块成功，无旧目录和其他框架依赖。
|
||||
|
||||
## 安装验证
|
||||
|
||||
独立verify脚本校验manifest中每个文件与ZIP精确一致，拒绝多余/重复项、
|
||||
绝对路径、反斜线穿越、符号链接、不可信插件根名、哈希错误。
|
||||
安装器只安装到用户显式提供的插件父目录，既有目标拒绝覆盖，不删旧
|
||||
插件、不接触旧数据、不安装依赖、不启动/重启机器人；先校验再写入，
|
||||
失败清理自己新建的临时目录。提供明确安装步骤和停止机器人提示。
|
||||
|
||||
Scenario: 安全校验与安装
|
||||
Acceptance: A16
|
||||
临时目录测试有效包可安装，坏包/穿越/已有目标均拒绝且不留下半成品。
|
||||
|
||||
## 工作流和发布
|
||||
|
||||
主仓库CI在PR/push及手动触发时执行检查，构建ZIP/清单/校验附件并上传
|
||||
Actions artifact。工作流权限默认只读；不可信PR不触发跨仓库写入。
|
||||
跨仓库同步依当前工作流，在 main 的 push 或显式 publish 手动输入时
|
||||
执行，PR 不触发；使用专用 Secret/受保护 environment，固定目标为
|
||||
Shu-Ying/zhenxun_plugin_farm 的 main 分支。脚本默认 dry-run，只有显式
|
||||
发布才联网；只进行普通更新，不 force、不修改旧标签；并发分支改变
|
||||
时失败。此次本地归档不执行发布。发布仓库只含生成的
|
||||
可安装内容、来源和验证工具，以及验证工作流，不在那里维护业务源码。
|
||||
下载ZIP测试不要求先同步仓库，不要求用户先给令牌。
|
||||
|
||||
Scenario: 测试附件与可控同步
|
||||
Acceptance: A17
|
||||
静态检查工作流触发/权限和输入边界；模拟服务验证固定目标、冲突保护、
|
||||
令牌不落盘与默认dry-run。此任务不执行真实GitHub发布。
|
||||
|
||||
## 兼容与文档
|
||||
|
||||
真寻本地配置要求Pillow>=10,<11，本预览使用与其相交的>=10.4版本；
|
||||
CI测试最低10.4和本项目支持当前版本，Windows/Linux。不得静默强制
|
||||
升级宿主到12。文档列出本机实际检查、模拟与真实宿主的差别，并提供
|
||||
主仓库生成、发布仓库布局、下载/依赖安装、字体、数据库、测试命令、
|
||||
与旧版避免冲突、备份/卸载和可选同步的凭据最小权限步骤。沿用原
|
||||
指令时必须由用户停用旧插件，不静默更名指令，不自动禁用旧插件。
|
||||
|
||||
Scenario: 可复现的真寻测试交付
|
||||
Acceptance: A18
|
||||
产物可离线验证，文档能按步骤启动人工测试；明确真实机器人与GitHub
|
||||
工作流仍未实际执行，不宣称已经上线或已兼容全部平台。
|
||||
Reference in New Issue
Block a user