diff --git a/docs/09-foundation.md b/docs/09-foundation.md index d8c0a90..240b5e6 100644 --- a/docs/09-foundation.md +++ b/docs/09-foundation.md @@ -29,7 +29,8 @@ wheel随包携带JSON及小型升级土地素材,不包含legacy、玩家数 - 注册500初始币、6地块;可靠识别为初始3块的旧号一次性补3块, 保留已开垦成果。详见land-rules.md;价格/产量/成熟时间沿用目录。 -- 旧作物库202条记录完整导出且保留源 SHA-256。 +- 初始作物库202条记录完整迁入Service;当前数据发布和启动更新见 + [作物数据维护](catalogue-updates.md),旧库基线独立保留。 - 多季再生长间隔明确保留去重 phase[1:] 求和,未重平衡数值。 - F01/F02:余额和经验只增加本次增量。 - F03:每块地单独加成、向下取整,再求和。 diff --git a/docs/10-rendering.md b/docs/10-rendering.md index 63681c7..692a985 100644 --- a/docs/10-rendering.md +++ b/docs/10-rendering.md @@ -109,9 +109,10 @@ RenderService默认一个绘图任务,最多8个活跃/排队的不同请求 ## 素材完整性与来源 -scripts/export_render_assets.py将已有素材原样打包,附202种作物 -展示配置、旧布局和统一定位规则;额外打包新提取的 40 张网页素材。 ---check比对确定性输出与原图哈希,不修改旧基线。 +现行素材及展示配置由Service的catalogue/source维护,作为完整版本发布, +插件启动时统一选择;见[作物数据维护](catalogue-updates.md)。 +scripts/export_render_assets.py仅保留显式旧基线导出;默认--check核对 +当前bootstrap,不再把日常配置绑定到旧库。 素材包约束为安装资源,不按用户输入路径访问任意文件、不解压到磁盘。 保留GPL及原始归属;历史素材分发权仍需在公开发布前核实。 diff --git a/docs/README.md b/docs/README.md index f6da9e7..916b934 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ | 文档 | 用途 | |---|---| +| [catalogue-updates.md](catalogue-updates.md) | Service 作物维护、发布、启动更新、缓存与兼容回滚 | | [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) | 共享图片工具、农场绘制、缓存、编码与接入 | diff --git a/docs/catalogue-updates.md b/docs/catalogue-updates.md new file mode 100644 index 0000000..7b525ab --- /dev/null +++ b/docs/catalogue-updates.md @@ -0,0 +1,51 @@ +# 作物数据维护与启动更新 + +作物的可编辑源已迁入独立 Service 仓库的 `catalogue/source/`。 +插件内只保留首次离线启动所需的轻量基线;日常改价、调整生长参数和新增作物 +不需要重新发布插件。图片、展示配置、作物定义及升级土地图作为同一版本发布。 + +## 日常更新 + +1. 在 Service 修改 `catalogue/source/plants.json`。新增作物使用未占用的正整数 + ID,在 `catalogue/source/images/` 添加对应图片;布局在 `metadata.json`。 +2. 在 Service 根目录生成一个新的版本标签: + + ```text + python scripts/prepare_catalogue.py --source catalogue/source --output catalogue --version crops-20261026-01 + python scripts/prepare_catalogue.py --source catalogue/source --output catalogue --version crops-20261026-01 --check + ``` + +3. 审查并发布 Service 中的源文件、`catalogue/manifest.json` 和新生成的 + `catalogue/releases/` 历史版本。Github/Gitea 源需将文件发布到相应仓库; + HTTP 源需配置 `FARM_CATALOGUE_DIR` 指向完整 `catalogue`,并重启 Service + 以加载新快照。详细操作见 Service 的 `docs/catalogue.md`。 +4. 重启或重载农场插件。三框架共用启动流程,按配置的资源源检查一次更新; + 运行期间不轮询,不改变当前进程已加载的版本。改用 HTTP 源时使用有效的 + HTTPS Service 基础地址。 + +不可删除或改名已发布的作物 ID,也不可删除既有图片路径。停售或停止播种应 +调整对应开关。同一版本标签不可复用于不同内容。回滚应从旧配置生成新的兼容 +版本,保留已经发布的 ID、名称和图片;不要直接退回缺少新增 ID 的旧版本。 + +## 缓存与玩家数据 + +启动会核对清单、大小、SHA-256、JSON 契约和 ZIP 图片内容,成功后才原子切换 +数据目录下的 `catalogue/current.json`。断网、404 或版本无效时优先使用已经 +验证的缓存,再使用插件基线。日志位于同一数据目录的 `farm-preview.log`。 + +备份应包含完整数据目录及其 `catalogue` 缓存。玩家库存或地块若引用基线没有的 +新作物 ID,而可用缓存和远端均不能提供这些 ID,插件会明确拒绝启动,避免 +丢失库存。不要通过删除玩家数据解决版本问题,应恢复缓存或提供兼容发布版本。 +已播种作物继续按播种时的快照结算;出售使用当前加载版本的价格。 + +## 插件维护者刷新离线基线 + +只有准备发布新版插件时才需更新内置基线。在 Farm 根目录执行: + +```text +python scripts/sync_catalogue_bootstrap.py --source D:/Work/farm_service/catalogue +python scripts/check_catalogue_bootstrap.py +``` + +同步前请确认 Service 发布版本已审查。CI 独立核对 Farm 内置产物,不依赖相邻 +Service 工作区或在线下载。旧库导出工具只保留为显式迁移参考,不再是日常数据源。 diff --git a/docs/superpowers/plans/2026-10-26-catalogue-service.md b/docs/superpowers/plans/2026-10-26-catalogue-service.md new file mode 100644 index 0000000..cb90fc2 --- /dev/null +++ b/docs/superpowers/plans/2026-10-26-catalogue-service.md @@ -0,0 +1,113 @@ +# 作物目录Service与启动更新 Implementation Plan + +> **For agentic workers:** 使用subagent-driven-development负责Service边界, +> 主代理负责紧密耦合的Farm加载、生命周期和发布产物;最后统一只读审查。 + +**Goal:** Service独立维护完整作物资源版本,三框架仅启动检查更新并安全回退。 +**Architecture:** Service的catalogue/source为唯一可编辑源,生成不可变发布版本; +Farm离线核心只解析目录,共享接入层下载、校验和选择版本后初始化数据库及绘图。 +**Tech Stack:** Python3.10+标准库/Pillow,Rust/Axum,SQLite,unittest/cargo test。 +**Spec:** D:/Work/farm_service/docs/crop-catalogue-design.md;用户明确要求实施。 + +## Global Constraints + +不修改legacy、不操作真实玩家数据、不推送部署、不创建定时更新;现有已播种 +结算快照和当前价格出售规则保留。当前目录为用户此前选择的工作区;本轮不提交。 +图索引过期,已知scripts excluded/src metadata_changed,所有结论回到FastCtx源文件。 + +## Protocol / Interfaces + +发布根catalogue/,latest位于manifest.json;历史位于releases//。 +manifest严格schema=1、version(1..64字母数字._-)、release(64位小写SHA256)、 +files;files精确四项plants.json、metadata.json、assets.zip、land-soils.zip, +各为size_bytes正整数和sha256。release=SHA256(files对象的排序紧凑UTF8 JSON)。 +manifest<=16KiB,plants<=2MiB,metadata<=4MiB,各ZIP<=64MiB, +解压总量<=256MiB。不得任意URL/路径,不自动跨源。 +Github/Gitea根由现有固定Service仓库raw路径拼接catalogue/。 +HTTP /v1/catalogue/manifest.json 和 /v1/catalogue/releases/{release}/{file}。 +每历史版本含相同manifest.json。Service启动读完整目录快照,运行中不重读。 +发布工具调用:python scripts/prepare_catalogue.py --source catalogue/source +--output catalogue --version