Compare commits

..

198 Commits

Author SHA1 Message Date
k88936 d4796a90ab 布局重构:
Project CI / Repository checks (pull_request) Failing after 11s
Project CI / Backend tests (pull_request) Failing after 10s
Project CI / Frontend tests (pull_request) Successful in 2m49s
Project CI / Native shell tests (pull_request) Failing after 15m15s
- 预览改为全区域背景层。
  - 左右面板、顶部流程条改为覆盖层,可遮挡预览。
  - 左右面板开合状态仅保存在当前 React 会话。
  - 增加左右面板“收起/展开”入口。
  - 编辑器关闭入口改为单独的 ×,继续通过 onBack 注入关闭逻辑。
  - 保留全局顶部栏与现有快捷键、业务状态、保存流程。
  - 底层页面仍由现有父级路由控制,不新增 URL 状态。
2026-09-12 19:13:02 +08:00
k88936 bd127846f7 允许分离流程在忙碌态保存结果
保留 isSeparating 属于 isAiRunning 的全局语义

为内部分离保存增加受控 allowDuringSeparation 选项
2026-09-12 13:36:30 +08:00
k88936 b1751784ba 修正切分状态写入日志格式
移除状态写入完成日志中多余的格式参数
2026-09-12 13:26:36 +08:00
k88936 379611d552 避免渲染阶段写入画布尺寸引用
在 ResizeObserver 尺寸更新回调中同步 canvasSizeRef
2026-09-12 13:20:30 +08:00
k88936 ef04a19d5a 抽取组件确认弹窗公共结构
统一替换与移除操作的确认弹窗布局

保留各操作独立文案与按钮样式
2026-09-12 13:19:59 +08:00
k88936 206b4830a1 复用原图编辑错误摘要
解析失败分支只计算一次截断响应并同时用于审计与错误返回
2026-09-12 13:19:10 +08:00
k88936 4b8e268816 统一重启切分失败通知
restartSeparation 失败时复用工作流完成上报并清理完成提示
2026-09-12 13:18:30 +08:00
k88936 7e7d6f1563 避免忙碌时继续切分隐藏恢复提示
在清理恢复对话框前检查分离与工作流忙碌状态
2026-09-12 13:18:13 +08:00
k88936 a4b1d81123 避免忙碌时重启切分丢失恢复状态
restartSeparation 在清理 sidecar 前复用并发工作流守卫
2026-09-12 13:17:52 +08:00
k88936 983b15c3a7 允许恢复流程识别已完成的素材回填
同一 Sprite 已绑定的节点直接跳过

仅对缺失 Image 或绑定其他素材报告错误
2026-09-12 13:17:38 +08:00
k88936 cdb6fcfe97 切换组件时重置检查面板展开状态
按组件身份变化同步展开状态,避免沿用上一个节点的折叠状态
2026-09-12 13:17:01 +08:00
k88936 d8a4e35232 减少切分状态写入的重复克隆
让状态写入接口借用状态并在阻塞任务中写入序列化字节

保留 schema 与大小校验,避免每批次复制完整状态树
2026-09-12 13:16:25 +08:00
k88936 0726106818 为图片分离请求设置超时
将原图编辑 HTTP 请求限制为 120 秒,避免工作流永久阻塞
2026-09-12 13:14:22 +08:00
k88936 8beade5b4d 为业务校验重试增加退避
校验失败重试复用请求错误的递增等待并记录日志
2026-09-12 13:13:56 +08:00
k88936 46984a4945 净化切分提示中的节点标识
复用提示文本清洗逻辑,阻断控制字符与反引号注入
2026-09-12 13:13:25 +08:00
k88936 a8a30ecbc8 修正切分恢复命令映射
finalize_separation 调用 finalize helper

discard_separation_recovery 调用 discard helper
2026-09-12 13:13:06 +08:00
k88936 48e669d167 合并主线并解决界面编辑器冲突
Project CI / Repository checks (pull_request) Successful in 2m44s
Project CI / Frontend tests (pull_request) Successful in 3m25s
Project CI / Backend tests (pull_request) Failing after 4m23s
Project CI / Native shell tests (pull_request) Successful in 17m48s
合并主线的 AGC Runtime、UI 工作流与开发脚本变更

保留现行 Prompt Runtime 结构并整合设计基础提示词契约断言

适配 CanvasWorld 逆缩放渲染并修正预览缩放回归测试

同步项目文档、共享契约与已退役策划资源清理
2026-09-12 11:38:50 +08:00
k88936 23fdc005fe 整理 Raw 编辑方案文档格式
Project CI / Repository checks (pull_request) Failing after 10s
Project CI / Backend tests (pull_request) Failing after 10s
Project CI / Frontend tests (pull_request) Successful in 3m10s
Project CI / Native shell tests (pull_request) Failing after 14m49s
分隔字节边界说明与代码拆分列表
2026-09-12 11:22:50 +08:00
k88936 b8a4523a4f 补充 Raw 编辑字节边界说明
记录 raw_edit 使用 Bytes streaming multipart 的零拷贝约束

明确既有图片链路继续保持 Vec 字节契约
2026-09-12 11:20:53 +08:00
k88936 9c04561419 明确 Raw 编辑零拷贝上传约束
补充 Bytes 所有权与 streaming multipart 注释

增加共享字节缓冲不转换的回归测试
2026-09-12 11:18:14 +08:00
k88936 551fb6609a 为 Raw 编辑建立独立字节类型
恢复旧图片链路的 Vec 字节契约

让新增 raw_edit 输入和结果类型独立于既有 ReferenceImage
2026-09-12 11:15:15 +08:00
k88936 d05440dcca 为 Raw 编辑建立独立字节类型
恢复旧图片链路的 Vec 字节契约

让新增 raw_edit 输入和结果类型独立于既有 ReferenceImage
2026-09-12 11:13:27 +08:00
k88936 7edf4a8f8b 恢复旧图片链路字节类型
Project CI / Repository checks (pull_request) Failing after 13s
Project CI / Backend tests (pull_request) Failing after 10s
Project CI / Frontend tests (pull_request) Successful in 2m43s
Project CI / Native shell tests (pull_request) Failing after 14m6s
撤回非 raw_edit 的全局 Bytes 迁移

保留既有 VectorEngine 与编辑器路径的 Vec 字节契约
2026-09-12 11:06:05 +08:00
k88936 afc9ecbd51 补充 WebP 源图转码测试
验证 WebP 输入可转换为 PNG 上传格式
2026-09-12 10:42:15 +08:00
k88936 fc2f4b71ce 支持分离流程转换非 PNG 源图
在上传图片编辑请求前将 JPEG 和 WebP 转码为 PNG

新增 JPEG 转 PNG 单元测试并将转码放入阻塞任务
2026-09-12 10:38:00 +08:00
k88936 545f64cf9e 补齐原图编辑失败追踪事件
provider 失败时记录 external_generation_run 失败状态

保留现有外部 API 失败审计与错误映射
2026-09-12 10:37:04 +08:00
k88936 2a50614c11 将分离恢复阻塞 I/O 移出异步线程
新增 spawn_blocking 状态读取封装

sidecar 目录创建改用阻塞任务执行
2026-09-12 10:23:32 +08:00
k88936 915006c98f 适配绑定区域类型错误调用方
在区域归一化边界转换 typed error 为展示文案
2026-09-12 10:23:21 +08:00
k88936 69ce232a74 为绑定区域校验引入类型错误
用 ZeroDimension 和 OutOfBounds 区分边界校验失败

补充 typed error 单元测试并保留展示层中文文案
2026-09-12 10:20:17 +08:00
k88936 319aa69d6e 统一分离树根节点坐标空间
子节点收集复用根节点实际解析矩形
2026-09-12 02:24:01 +08:00
k88936 bec468bdc9 统一分离终止节点判定
批次选择与提取提示复用同一终止节点集合
2026-09-12 02:23:02 +08:00
k88936 eada20c199 恢复自动切分前重新校验状态
继续分离前确认 sidecar 存在并检查前置条件

恢复入口异常统一写入工作流失败通知
2026-09-12 02:20:52 +08:00
k88936 e8cf773aac 统一自动切分失败完成提示
分离入口异常时写入工作流完成失败通知
2026-09-12 02:19:48 +08:00
k88936 12fbb61fad 限制分离恢复状态写入大小
写盘前校验与读取一致的八兆字节上限

超限时记录原因并拒绝不可恢复检查点
2026-09-12 02:17:55 +08:00
k88936 478e08fb92 将 PNG 依赖限定为测试环境
从生产依赖移除仅测试使用的 png crate

在 dev-dependencies 中声明 PNG 测试依赖
2026-09-12 02:13:52 +08:00
k88936 0e67fbf80a 停止对最终工作流步骤重复预检
资产分离作为最后步骤不再校验不存在的下一步
2026-09-12 02:12:15 +08:00
k88936 ed2cfbad36 避免预览容器变化重置缩放
自动适配仅在图片或逻辑尺寸变化时执行

通过尺寸引用保留初始视口兜底值
2026-09-12 02:11:22 +08:00
k88936 560422286b 稳定组件面板展开与移除交互
仅在组件存在性变化时自动展开面板

为移除组件增加确认并保留失败弹窗
2026-09-12 02:08:56 +08:00
k88936 e04075fd95 为分离模型请求增加重试退避
瞬时请求失败时按递增毫秒延迟后重试

将重试循环末尾改为不可达断言
2026-09-12 02:07:02 +08:00
k88936 d7776f2a17 修正文生绑定提示语法
改进分离要求和返工建议英文表述
2026-09-12 02:05:18 +08:00
k88936 4d9e69841e 加固分离提示词生成
绑定提示改用切片参数避免多余复制

清理提取提示中的描述与返工备注文本
2026-09-12 02:04:32 +08:00
k88936 49e88bbd9f 统一分离提示备注长度限制
复用模型层的重做备注字符上限

导出提示文本清理函数供投影复用
2026-09-11 21:55:15 +08:00
k88936 86c268eca3 分离恢复使用独立丢弃操作
新增独立的恢复状态丢弃入口

完成与 finalize 的共享状态删除逻辑
2026-09-11 21:54:17 +08:00
k88936 c86221e3da 添加 TODO 注释以提示恢复字符限制错误信息
Project CI / Repository checks (pull_request) Failing after 15s
Project CI / Backend tests (pull_request) Failing after 15s
Project CI / Frontend tests (pull_request) Successful in 3m3s
Project CI / Native shell tests (pull_request) Failing after 14m57s
2026-09-11 20:12:16 +08:00
k88936 e7af7cf4e4 校验处理图区域并明确 multipart 字节上传
将处理图真实尺寸传入视觉绑定校验,提前拒绝零尺寸和越界区域。

保持非法区域直接失败,不转换为 NeedRework。

将 image 和 mask multipart 部分改为 Part::bytes。
2026-09-11 20:11:11 +08:00
k88936 e7cd008d7c 调整文本组件的识别规则
简化多行文本节点逻辑,明确文字与图片组件的绑定要求。
2026-09-11 20:06:09 +08:00
k88936 c743ca146e 复用图像下载的共享字节缓冲
将 DownloadedImage.bytes 改为 bytes::Bytes。

让远程下载和图标切片下游避免不必要的完整复制。

同步更新图像处理实现与测试 fixture。
2026-09-11 19:53:14 +08:00
k88936 8c8b6cc75a 将自动切分状态写盘移出 Tokio worker
用 spawn_blocking 承载 JSON 序列化和文件写入,并在工作流中等待结果。
2026-09-11 19:44:01 +08:00
k88936 4cf3642b53 说明视觉绑定解析错误的有限重试策略
记录严格工具 schema 和响应损坏重试边界。
2026-09-11 19:41:48 +08:00
k88936 f933db169e 说明结构化重试的有限上下文边界
记录现役调用方的小重试次数和保留完整反馈的设计依据。
2026-09-11 19:41:21 +08:00
k88936 a5e936dd27 清理已退役的前端绑定模块
删除无现役导入的 binding.ts 及其 BindingDTO、BindingChange 类型。
2026-09-11 19:39:59 +08:00
k88936 53008959c5 修正自动切分结果的类型收窄
在异步闭包赋值后明确已完成结果的非空类型。
2026-09-11 19:09:22 +08:00
k88936 57dbb3de52 替换已有组件前增加确认
使用独立确认弹窗避免一次点击覆盖已配置组件。
2026-09-11 19:07:12 +08:00
k88936 e189aff485 更新设计基础提示词契约测试
将测试断言同步到当前按需图片生成与动态产物合同。
2026-09-11 19:05:57 +08:00
k88936 248c094da9 清理合并命令测试中的无用导入
移除组件类型未再使用的测试模块导入。
2026-09-11 19:05:03 +08:00
k88936 e66eb2fb55 切换预览图片时自动适配画布
在活动图片变化后重新按完整画布边界计算视口。
2026-09-11 19:04:33 +08:00
k88936 d455dc18a9 按实际保存快照更新脏状态签名
保存成功后直接记录持久化快照签名,避免闭包中的旧编辑器状态阻止清脏。
2026-09-11 19:03:51 +08:00
k88936 04a0d21351 避免原始 PNG 的重复解析
使用解码后的颜色类型校验位深,将读取限制统一留在 image 解码器。
2026-09-11 19:03:03 +08:00
k88936 a9358bf3ce 防止字体前置校验访问空值
对外部状态中的空字体引用返回正常校验结果而不是抛出异常。
2026-09-11 19:00:49 +08:00
k88936 c3de2ce958 为自动切分命令增加项目写权限校验
在启动分离工作流前复用 asset.register 权限门禁。
2026-09-11 19:00:19 +08:00
k88936 287d2f94da 限制自动切分恢复状态读取大小
在解析 sidecar state 前检查文件大小,避免异常分配。
2026-09-11 18:59:51 +08:00
k88936 1343f487d0 为自动切分工作流增加忙碌保护
统一直接调用入口的并发防护,避免状态锁冲突。
2026-09-11 18:59:10 +08:00
k88936 73fb89a8f4 阻止本地素材登记结果错位回填
资源导入返回数量与请求路径不一致时立即中止位置映射。
2026-09-11 18:58:35 +08:00
k88936 bf2ffd2bf9 拒绝保存无可见像素的切分区域
透明裁切区域直接返回可恢复错误,避免登记空素材。
2026-09-11 18:58:13 +08:00
k88936 3f55f043a1 拒绝切分产物路径中的非法节点标识
在写入 cut 图片前限制节点 ID 字符并确认路径仍位于 sidecar 内。
2026-09-11 18:57:19 +08:00
k88936 26677b193c 复用界面树组件计数值
在同一行中复用组件数量,避免重复计算。
2026-09-11 18:56:13 +08:00
k88936 b8691add3a 移除区域归一化日志路径中的恐慌
直接记录归一化结果,避免诊断日志调用 expect。
2026-09-11 18:55:28 +08:00
k88936 bfe010a192 让视觉绑定调试预览写入失败可降级
调试 PNG 写入失败时记录警告并继续绑定流程。
2026-09-11 18:55:06 +08:00
k88936 6db6de5b99 同步检查器组件面板展开状态
切换节点或组件时重置展开状态,避免复用旧节点的折叠状态。
2026-09-11 18:54:39 +08:00
k88936 87a7294a04 细化组件绑定载荷形状校验
在反序列化前拒绝空值和无效的节点组件外部枚举。
2026-09-11 18:54:21 +08:00
k88936 3774d7c1e1 移除修复重试流程中的隐式恐慌
在循环意外结束时返回可恢复错误而不是触发 unreachable。
2026-09-11 18:53:34 +08:00
k88936 8d15125f12 限制切分提示词中的节点备注
对用户备注清理控制字符和围栏符号并限制长度。
2026-09-11 18:52:59 +08:00
k88936 cf68b8212d 让提取提示词序列化错误可恢复
将提取提示词生成改为返回带上下文的错误。
2026-09-11 18:52:10 +08:00
k88936 8d7ccc0d75 简化工作流操作卡状态映射
使用步骤映射替代嵌套三元表达式。
2026-09-11 18:51:30 +08:00
k88936 2af3d9a965 修正结构识别步骤的前置校验
将结构识别活动步骤改为校验素材切分前置条件。
2026-09-11 18:50:59 +08:00
k88936 4749339bad 补齐图片字节类型导出与转换
Project CI / Repository checks (pull_request) Failing after 31s
Project CI / Backend tests (pull_request) Failing after 13s
Project CI / Frontend tests (pull_request) Successful in 3m56s
Project CI / Native shell tests (pull_request) Failing after 3m33s
导出共享 GPT 图片尺寸阈值常量。

修复编辑器参考图 Bytes 与 Vec 边界转换。
2026-09-11 18:02:04 +08:00
k88936 3e85c71060 整理图片代理代码格式
按 Rust 格式化规范整理 multipart 与响应解析代码。
2026-09-11 17:55:50 +08:00
k88936 da19bde99a 同步八位 PNG 与 b64 契约
记录八位 PNG 校验规则与稳定错误文案。

说明 GPT-Image-2 原生 b64_json,不发送 response_format。
2026-09-11 17:52:26 +08:00
k88936 4a32ee37c4 修复 Bytes 迁移后的图片类型边界
统一使用 Bytes 的只读引用并在旧 Vec 接口处显式转换。

修复编辑器参考图对齐与 Raw PNG 解码编译错误。
2026-09-11 17:52:00 +08:00
k88936 31fd1da495 修正 GPT 图片响应契约说明
仅保留 GPT-Image-2 原生 b64_json 行为的行内注释。

不发送 response_format 参数,也不引入 URL 兼容下载。
2026-09-11 17:48:55 +08:00
k88936 4c88e5e924 限制 Raw 图片仅接收八位 PNG
使用 png 解码器读取位深并在 image 解码前拒绝非八位输入。

统一返回稳定的 8-bit PNG 客户端错误并补充十六位 PNG 测试。
2026-09-11 17:48:01 +08:00
k88936 99f4961c5f 统一 GPT 图片尺寸计费阈值
提取共享的 1536 长边 tier 常量并复用到 raw 与编辑器计费。

同步 Raw 图片代理技术合同中的阈值来源。
2026-09-11 17:47:31 +08:00
k88936 0cebc39b6a 同步 Raw 图片代理契约
记录文本字段 16KiB 流式限制。

记录 GPT-Image-2 固定 b64_json 响应格式。
2026-09-11 17:37:58 +08:00
k88936 842d080a75 锁定图片缓冲依赖
将 platform-image 使用的 bytes 依赖写入 Cargo.lock。
2026-09-11 17:37:32 +08:00
k88936 8cd6e34af0 调整图片切分批次请求尺寸计算逻辑
基于批次源矩形总面积动态计算 image-edit 请求尺寸,新增面积对齐和最小/最大值限制,扩展相关模块和测试以支持调整后的工作流。
2026-09-11 17:33:26 +08:00
k88936 b357d36262 明确 GPT 图片编辑响应格式
原始图片编辑请求固定声明 response_format=b64_json。

补充 GPT-Image-2 仅返回 b64_json 的契约行内注释。
2026-09-11 17:29:11 +08:00
k88936 48c5638893 扩大原始图片文本字段上限
multipart 文本字段改为 chunk 流式读取并限制 16KB。

统一 UTF-8 校验和超限错误,避免先完整分配超长 prompt。
2026-09-11 17:28:13 +08:00
k88936 46df12c086 收敛原始图片 multipart 错误
服务端记录解析原始错误,客户端仅返回稳定分类文案。
2026-09-11 17:26:33 +08:00
k88936 4bdbab29c0 优化原始图片请求缓冲
将 ReferenceImage 与 multipart 输入改用 bytes::Bytes。

通过流式 multipart part 避免 reqwest 路径的额外整图复制。
2026-09-11 17:25:25 +08:00
k88936 9acc23b848 抽离 DFS 批次逻辑至独立模块,并优化节点面积计算与终端过滤流程
Project CI / Repository checks (pull_request) Failing after 15s
Project CI / Backend tests (pull_request) Failing after 15s
Project CI / Frontend tests (pull_request) Successful in 8m16s
Project CI / Native shell tests (pull_request) Failing after 11m7s
2026-09-11 15:34:30 +08:00
k88936 b9b4ebd38e 重命名图片编辑为提取模块并更新相关调用绘制流程
Project CI / Repository checks (pull_request) Failing after 16s
Project CI / Backend tests (pull_request) Failing after 15s
Project CI / Native shell tests (pull_request) Failing after 4m22s
Project CI / Frontend tests (pull_request) Successful in 11m36s
2026-09-11 15:18:05 +08:00
k88936 8f680ef376 视觉绑定增加透明标记预处理
新增视觉绑定 RGBA 预处理与阈值复用

在请求前生成不透明洋红标记图并记录耗时

更新英文提示词说明标记色语义
2026-09-11 15:09:44 +08:00
k88936 7c7d55dcab 重构提取提示词生成逻辑,移除文本拼接方式,新增 YAML 序列化结构与测试 2026-09-11 14:54:00 +08:00
k88936 1303592a86 重构UI编辑器素材切分工作流模块
Project CI / Repository checks (pull_request) Failing after 14s
Project CI / Backend tests (pull_request) Failing after 15s
Project CI / Frontend tests (pull_request) Successful in 5m17s
Project CI / Native shell tests (pull_request) Failing after 6m41s
拆分提取与绑定提示词模块

拆分图片编辑、视觉绑定、裁切和批次 patch 实现

同步技术方案实现组织说明并更新提示词测试
2026-09-11 13:54:33 +08:00
k88936 1db7597141 重构UI素材切分树与批次选择
移除文本遮罩和标记图生成流程,图片编辑直接读取原始界面图

引入节点类型并保留文字移除上下文,按前序DFS与面积预算选择图片批次

补充根节点、重叠节点、文字过滤和超面积推进测试并同步TypeScript类型
2026-09-11 12:55:53 +08:00
k88936 13701d0144 澄清UI自动切分的原图输入与调试产物
明确图片编辑直接使用原始界面图,不再生成辅助输入图

明确处理图与裁切图使用随机文件名并保留用于调试
2026-09-11 11:56:33 +08:00
k88936 5c83142fec 更新UI编辑器自动切分素材工作流方案
将多轮整图分层与DFS面积批次写入权威专题

明确TextRemovalOnly、视觉绑定和atlas输出合同

删除平行专题文档并保留后续TODO

补充UI编辑器自动分离多轮分层方案

新增整图语义分层与多轮 image-edit 方案

明确 DFS 批次、TextRemovalOnly 和视觉绑定合同

记录面积预算、恢复边界与后续 TODO
2026-09-11 11:10:51 +08:00
k88936 95ed49f264 调整素材切分边界像素上限
将视觉绑定区域每条边的调整上限改为固定 32px。

同步 UI 编辑器自动切分技术方案与项目决策记录。

更新边界测试以覆盖绝对像素限制。
2026-09-11 10:28:32 +08:00
k88936 b8d8072267 完善识别命令说明,新增禁止冗余背景节点的指引
Project CI / Repository checks (pull_request) Failing after 9s
Project CI / Backend tests (pull_request) Failing after 10s
Project CI / Frontend tests (pull_request) Successful in 2m44s
Project CI / Native shell tests (pull_request) Failing after 3m5s
2026-09-10 19:54:46 +08:00
k88936 462caa33c5 修复工作流完成弹窗的多行错误展示
让完成通知中的换行字符按实际换行渲染,避免多项回填错误挤成一行。

保持通知内容和弹窗交互不变。
2026-09-10 19:06:20 +08:00
k88936 4e1064266f 移除自动切分结果的冗余类型断言
依赖空值检查后的 TypeScript 类型收窄直接使用 SeparationDTO。

不改变自动切分流程或运行时行为。
2026-09-10 19:05:48 +08:00
k88936 a50cbfb6c8 过滤图片编辑响应中的空图像数据
忽略上游返回的空 b64_json 条目,避免把空字符串转发为图像结果。

新增空条目与有效条目混合响应的回归测试。
2026-09-10 19:04:40 +08:00
k88936 1eb4bd5ec0 明确拒绝无效的处理图数据地址
处理图缺少 data URL 分隔符时直接返回格式错误。

避免先写入空文件再在后续裁切阶段暴露误导性错误。
2026-09-10 19:03:29 +08:00
k88936 5b441d389c 忽略完全位于图片外的切分标记矩形
矩形起点超出图片边界时直接返回 None,避免在边缘绘制伪影。

新增越界矩形回归测试。
2026-09-10 19:02:40 +08:00
k88936 f200cb4d3c 避免标记图编码重复复制像素缓冲
复用同一个 DynamicImage 完成文件保存和返回数据编码。

保持标记图内容和错误处理不变。
2026-09-10 19:02:09 +08:00
k88936 ae2f5fc80b 记录 UI 编辑器重试中的请求错误
在结构化 LLM 请求的中间重试失败时写入尝试次数和错误日志。

保留原有重试次数、历史消息和最终错误语义。
2026-09-10 19:01:32 +08:00
k88936 b69bd88e5e 修正 UI 编辑器校验器命名
将 run_with_repair_history 的 Validater/validater 更正为 Validator/validator。

不改变重试流程和运行时行为。
2026-09-10 19:01:18 +08:00
k88936 c5c7339c4a 重命名分离模块 problem_descriptionadvice 并同步更新相关校验逻辑与测试
Project CI / Repository checks (pull_request) Failing after 13s
Project CI / Backend tests (pull_request) Failing after 9s
Project CI / Frontend tests (pull_request) Successful in 2m28s
Project CI / Native shell tests (pull_request) Failing after 14m32s
2026-09-10 18:54:10 +08:00
k88936 4bbc77fc32 增加UI自动切分耗时日志
补充 marker、area、LLM、图片编辑及 batch 阶段耗时观测
记录成功与失败路径的性能字段
同步自动切分工作流技术方案中的日志约定
2026-09-10 18:51:53 +08:00
k88936 8c521ca891 移除 UI 预览适配与缩放输入
删除预览工具栏适配按钮、适配回调与对应快捷键
将缩放百分比改为只读显示并移除输入组件及测试
2026-09-10 18:48:56 +08:00
k88936 69a0804c03 调整切分区域边界扩展上限
将像素边界每边调整上限常量设为百分之百

同步更新受影响的区域归一化测试

技术方案仅引用上限常量,不重复写死数值
2026-09-10 18:46:39 +08:00
k88936 74f726e65d 修正自动切分素材检查条件
移除自动切分对预先导入独立素材的错误要求。
统一自动切分前置与结果检查,并补齐图片和字体引用校验。
在新建和重新开始自动切分时执行前置检查,恢复流程继续尽力完成。
2026-09-10 18:43:31 +08:00
k88936 1509235c1b 统一自动切分素材工作流命名
将 UI 编辑器第三步和内部流程 ID 统一为自动切分素材。
重命名前端切分概览模块并更新完成、恢复和导航文案。
同步 Runtime 最终编辑器路由、测试与相关技术文档。
2026-09-10 15:11:29 +08:00
k88936 1c992c69fe 完善分离与识别命令说明,调整嵌套格式与结构化指引 2026-09-10 14:05:37 +08:00
k88936 d9b153ed78 完善分离命令说明,新增禁止未请求文本的指引 2026-09-10 13:15:42 +08:00
k88936 30c469e9a1 规范分离模块格式化写法 2026-09-10 13:15:34 +08:00
k88936 51f629b2f9 UI编辑器节点改为单组件模型
Project CI / Repository checks (pull_request) Failing after 14s
Project CI / Backend tests (pull_request) Failing after 14s
Project CI / Frontend tests (pull_request) Successful in 2m43s
Project CI / Native shell tests (pull_request) Failing after 14m29s
修改 Node、Binding DTO、识别与分离链路为 component 单字段

为识别和绑定 LLM 工具引入 PureNode/WithComponent 显式载荷

移除前端组件索引、排序和组件栈操作

同步生成 ts-rs TypeScript 类型、状态校验、测试与专题文档
2026-09-10 13:08:29 +08:00
k88936 d6c720ecdd 纠正分离模块导出提交边界
撤销误入的组件字段重命名测试改动

仅保留裁切工作流对面积归一化模块的直接依赖
2026-09-10 12:26:39 +08:00
k88936 086aa91d70 收窄分离区域模块导出
让裁切工作流直接依赖面积归一化模块

移除未使用的公共重导出,保持分离模块边界清晰
2026-09-10 12:24:18 +08:00
k88936 3733e86272 补充分离区域像素归一化约定
记录透明像素边界扫描、方向锁定与四边同步推进规则

明确 50% 与图像边界约束、透明图处理、日志字段和性能 TODO
2026-09-10 12:13:21 +08:00
k88936 5d0f3e6be6 UI编辑器分离区域像素边界归一化
新增独立 BindingArea 像素边界归一化模块与回归测试

在 cut 裁切前按透明像素收缩或扩展四条边并记录约束结果

接入分离工作流并保留原始与归一化区域日志
2026-09-10 12:13:04 +08:00
k88936 989440173f 完善绑定区域值类型约束
为 BindingArea 增加 Eq 以支持分离区域比较
2026-09-10 11:52:46 +08:00
k88936 22d9958d18 在分离标记图中遮罩普通文字
绘制文字紫色区域并保持绿色元素框在最上层

增加文字遮罩图层顺序测试
2026-09-10 10:57:50 +08:00
k88936 56f8c9a6a1 构造自动分离文字遮罩
按最近未绑定图片祖先收集 Text 布局像素矩形

补充嵌套图片与根图片遮罩构造测试
2026-09-10 10:49:45 +08:00
k88936 c84df3d88f 补充文字遮罩状态字段契约
明确 text_mask_areas 为当前 separation state 必选字段

保持开发阶段 v1 且不提供旧 sidecar 迁移回退
2026-09-10 10:49:07 +08:00
k88936 761d32cebf 拆分自动分离模型并增加文字遮罩区域
将 separation model 拆为 note、node、binding、result 模块

为 SeparationNode 增加 text_mask_areas 字段并同步 TypeScript 类型
2026-09-10 10:43:00 +08:00
k88936 b3d6543d73 补充自动分离文字遮罩方案
记录普通文字归属、遮罩字段与标记图绘制规则

明确不进入分离树、绑定结果和视觉模型契约
2026-09-10 10:32:34 +08:00
k88936 8cd7c43b9e 更新自动分离接入文档状态
将前端接入 TODO 更新为联调与失败注入测试待办。
2026-09-09 21:02:09 +08:00
k88936 7fb7d246c0 将视觉步骤切换为自动分离
前端仅调用一次 separate_ui,并完成 cut 图片登记、SpriteAsset 回填和 State 保存。

增加 sidecar 恢复选择面板,旧 bind_components 标记为未调用遗留命令。
2026-09-09 21:00:53 +08:00
k88936 5844afa14d 抽取自动分离素材状态变换
复用 SpriteAsset 校验并支持锁内构造下一份 State。

保留公开 addSpriteAssets 的锁保护与历史提交行为。
2026-09-09 20:17:11 +08:00
k88936 615d1a28cd 补齐自动分离恢复状态胶水
新增 separation 恢复探测、完成清理命令与 DTO。

持久化项目相对 cut 图片路径并保留 state sidecar 到最终提交。
2026-09-09 20:16:09 +08:00
k88936 3e1e172f9c 补充自动分离前端接入合同
明确 UI 编辑器单次调用 separation 与 sidecar 恢复弹窗

补充资源登记、State 回填、保存和 finalize 顺序

划定旧 binding 与 Runtime workflow 的本次不改范围
2026-09-09 20:03:27 +08:00
k88936 53a919e39b 优化 UI 分离工作流程的提示生成与历史处理
Project CI / Repository checks (pull_request) Failing after 14s
Project CI / Backend tests (pull_request) Failing after 14s
Project CI / Frontend tests (pull_request) Successful in 2m50s
Project CI / Native shell tests (pull_request) Failing after 3m4s
- 调整 initial_history 构建逻辑,增强系统与用户消息的一致性。
- 简化 SeparationNode 提示生成逻辑,仅保留节点 ID 与注释。
- 明确 extracted_area 的权威性为 processed 图像,并更新生成提示的规则。
2026-09-09 19:04:56 +08:00
k88936 d4b5f9fc14 重构 UI Editor LLM repair history
将 request_with_feedback 改为 run_with_repair_history 并统一 max_retries 与 validater 命名。

让 requester 接收 append-only LlmMessage history,业务校验失败追加序列化响应和错误反馈。

迁移 visual_binding 调用方并补充 retry-only 与业务反馈 history 测试。

同步 UI Editor 结构化请求 repair history 决策文档。
2026-09-09 16:46:29 +08:00
k88936 6e4f9a6f1f 完善 UI 自动分离返工意见链路
记录视觉模型 NeedRework 意见并注入后续提取提示

同步返工次数、problematic 终态和 512 字符校验

补充 separation DTO 类型、回归测试与技术方案
2026-09-09 16:29:54 +08:00
k88936 8a0dcf8be7 增强分离标记框的可视辨识度
Project CI / Backend tests (pull_request) Failing after 15s
Project CI / Repository checks (pull_request) Failing after 15s
Project CI / Frontend tests (pull_request) Successful in 3m4s
Project CI / Native shell tests (pull_request) Failing after 4m38s
为分离标记框增加两条绿色角到角交叉线。

新增 MARKER_LINE_WIDTH 常量统一配置标记线宽,并确保绘制结果裁剪在矩形内。

补充标记框像素级回归测试并同步更新自动分离专题文档。
2026-09-09 16:24:11 +08:00
k88936 aa2a78f7e0 重命名 separated_image_area 为 extracted_area,优化命名一致性并明确区域含义 2026-09-09 15:48:32 +08:00
k88936 7aa96e8438 统一分离标记图中文注释
说明紫色重建与绿色框绘制层级
2026-09-09 15:16:39 +08:00
k88936 feb6bc0ad4 修正分离失败恢复边界
图片编辑、写入和裁切失败保留状态并返回错误
仅视觉模型返工结果进入 problematic
2026-09-09 15:07:49 +08:00
k88936 f349350d60 同步分离状态 TypeScript 类型
加入 root_extractable 并将树字段统一为 trees
2026-09-09 15:03:48 +08:00
k88936 df3a172bc9 补充 Raw GPT Image 2 multipart 合同
明确分离图片编辑请求字段与旧协议边界
2026-09-09 14:57:55 +08:00
k88936 9b4924c73e 补充分离批次重叠筛选测试
验证 DFS 顺序下贪心跳过重叠叶节点
2026-09-09 14:54:37 +08:00
k88936 d30bc462c5 格式化自动分离 Rust 模块
统一树选择、标记图和批次流程代码风格
2026-09-09 14:50:19 +08:00
k88936 26b9ad7fad 重构分离树与非重叠批次选择
保留真实根节点并记录 root_extractable
按终态反查和 DFS 贪心筛选逻辑叶
拆出父子区域标记图生成模块
2026-09-09 14:48:18 +08:00
k88936 bc5398894e 补充分离树与批次算法约定
明确真实根节点、逻辑叶和非重叠贪心选择
补充父节点紫色重建与错误恢复边界
2026-09-09 14:29:38 +08:00
k88936 11d4d3d930 适配 UI 分离图片编辑 multipart 接口
Project CI / Frontend tests (pull_request) Successful in 4m57s
Project CI / Repository checks (pull_request) Failing after 10s
Project CI / Backend tests (pull_request) Failing after 11s
Project CI / Native shell tests (pull_request) Failing after 5m40s
将标记图 data URL 解码为 PNG 文件部件。

按 Raw GPT Image 2 新合同发送 prompt、尺寸和输出参数。

保留响应 data[].b64_json 解析与 separation 流程不变。
2026-09-09 13:17:36 +08:00
k88936 418d5732de 调整UI识别指令,细化粒度要求并优化组件返回规则 2026-09-09 13:12:51 +08:00
k88936 592b6b4ee7 简化识别树验证测试中的断言格式 2026-09-09 13:12:51 +08:00
k88936 99c19e3ed9 补充分离流程排障日志
记录 separation sidecar 状态读写与恢复阶段

记录树构造、批次选择、视觉绑定、裁切和 patch 结果

避免输出 base64、完整提示词和敏感凭据
2026-09-09 13:12:51 +08:00
k88936 15e30acb0f 调整UI识别指令细节,明确文字组件识别规则与粒度标准 2026-09-09 13:12:51 +08:00
k88936 56fff8325b 将自动分离图像处理移出异步执行器
在 spawn_blocking 中构建标记图并编码写入处理图

在 spawn_blocking 中完成处理图裁切与文件输出

保留 image-edit 和视觉绑定网络请求的 async 调度边界
2026-09-09 13:12:51 +08:00
k88936 884c5ec5ee 补充自动分离 sidecar 并发边界约束
记录前端单次运行与 runWithStateLocked 的并发前提

明确 sidecar 不参与正式资产写入和项目 revision

补充未来多窗口多进程场景的进程级锁 TODO

记录图像本地处理使用 spawn_blocking 的执行边界
2026-09-09 13:12:51 +08:00
k88936 207b0820dd 统一分离树文件格式
按仓库 rustfmt 规范整理 synthetic root 实现
2026-09-09 13:12:51 +08:00
k88936 19f3d62d78 隔离非法分离区域导致的批次失败
将裁切错误记录为 problematic 并继续流程
避免单个模型区域终止整页分离
2026-09-09 13:12:51 +08:00
k88936 3c1e7bd599 保留分离问题节点的真实重做次数
避免基础设施失败伪造达到上限
保持 problematic 节点诊断信息准确
2026-09-09 13:12:51 +08:00
k88936 dda6b3946a 阻止识别结果引用未授权字体素材
补齐识别阶段字体引用校验
增加伪造字体绑定回归测试
2026-09-09 13:12:51 +08:00
k88936 aff40f794d 修复分离树合成根节点 ID 冲突
避免单图根节点重复进入重做计数
补充根图片构造回归测试
2026-09-09 13:12:50 +08:00
k88936 187faa607d 保留原始分离提示并拆分模块
按模型、树、持久化、提示词和工作流拆分 separation

提取支持 more_turn 的反馈重试 harness

删除旧 separation.rs 文件
2026-09-09 13:12:50 +08:00
k88936 109cc81740 拆分UI自动分离命令模块
保留原始图片分离与绑定提示词

提取模型、树、持久化和工作流子模块

新增可配置 more_turn 反馈重试 harness
2026-09-09 13:12:50 +08:00
k88936 f796aef7e2 完善UI自动分离批次处理
复用资源ID安全路径并修正像素坐标

加入标记图、Raw编辑、视觉绑定修复与问题节点继续处理
2026-09-09 13:12:50 +08:00
k88936 4cc7f4dd64 实现UI自动分离命令
新增分离树、批次处理与sidecar状态

接入Raw GPT Image 2与视觉绑定重试

注册Tauri命令并补充识别组件草稿
2026-09-09 13:12:50 +08:00
k88936 b2d4690f94 补充UI编辑器自动分离工作流合同
新增自动分离、临时 sidecar 与视觉绑定设计合同

明确前端资产登记职责与恢复 TODO
2026-09-09 13:12:50 +08:00
k88936 0400103a19 将 Raw 图片编辑入站改为 multipart
移除 JSON/base64 入站兼容,仅接受 multipart 图片与参数字段

复用扣费前 PNG、尺寸、mask 和 prompt 校验并补充 multipart 测试

优化上游图片字节转发,避免再次克隆 image bytes

同步 Raw 图片编辑技术方案与 Axum multipart 依赖
2026-09-09 13:06:22 +08:00
k88936 c049d68b8e 收紧 Raw 成功响应字段类型
要求 data 与 b64_json 必填并移除无用 provider id

prompt 上限调整为 4 KiB 原始字节并同步文档
2026-09-09 12:03:03 +08:00
k88936 acfcf0c158 同步 platform-image 的 serde 锁定依赖
为 Raw typed 响应记录 serde workspace 依赖
2026-09-09 11:51:25 +08:00
k88936 5bbedd9a5c 限制 Raw prompt 原始字节大小
将 prompt UTF-8 原始字节限制为 16 KiB

补充超限回归测试并同步请求合同
2026-09-09 11:50:30 +08:00
k88936 40316d82c4 在扣费前校验 Raw mask 尺寸
解码时保留 image 与 mask 宽高并拒绝不一致输入

同步 Raw 图片编辑请求合同与回归测试
2026-09-09 11:45:44 +08:00
k88936 6c77de4a36 为 Raw 成功响应收紧类型透传
使用 typed JSON DTO 提取并原样转发 b64_json

不解码图片内容且忽略 output_format 回显
2026-09-09 11:44:31 +08:00
k88936 b3693765ef 透传 Raw 图片结果避免解码回显字段
仅转发上游 data.b64_json 并忽略 output_format

同步 Raw 技术方案并补充不解码回归测试
2026-09-09 11:34:41 +08:00
k88936 f7edc9d0ee 区分 Raw 图片 PNG 资源限制错误
Project CI / Frontend tests (pull_request) Successful in 4m43s
Project CI / Repository checks (pull_request) Failing after 11s
Project CI / Backend tests (pull_request) Failing after 10s
Project CI / Native shell tests (pull_request) Failing after 5m14s
将有效但超出解码限制的 PNG 映射为明确的 400 提示

补充超大合法 PNG 的回归测试
2026-09-09 11:04:44 +08:00
k88936 f60771dd00 提前检查 Raw 图片请求预算
在构造 multipart 表单前校验请求 deadline

避免预算耗尽时复制输入图片并缩短耗时统计范围
2026-09-09 10:58:48 +08:00
k88936 f7cccd8592 补充 Raw 图片客户端错误上下文
为 HTTP 客户端构造失败统一保留操作上下文

补充配置错误文案回归测试
2026-09-09 10:57:04 +08:00
k88936 5ee2d940c1 修正 Raw 图片尺寸校验错误语义
尺寸校验失败改用请求参数无效语义

补充错误文案回归测试
2026-09-09 10:55:36 +08:00
k88936 c75a7725ce Merge remote-tracking branch 'origin/master' into feat/expose-image2edit
Project CI / Repository checks (pull_request) Successful in 2m51s
Project CI / Native shell tests (pull_request) Failing after 4m9s
Project CI / Backend tests (pull_request) Failing after 4m58s
Project CI / Frontend tests (pull_request) Successful in 3m46s
2026-09-09 10:42:22 +08:00
k88936 3a95715990 同步 Raw 图片编辑技术方案
Project CI / Native shell tests (pull_request) Failing after 6m36s
Project CI / Backend tests (pull_request) Failing after 14s
Project CI / Repository checks (pull_request) Failing after 15s
Project CI / Frontend tests (pull_request) Successful in 4m22s
记录解码资源上限和阻塞线程策略
补充输出格式回退与成功追踪约定
2026-09-08 23:41:27 +08:00
k88936 ed86963de2 修正 Raw 图片追踪结果类型
明确输出数据集合类型
保持 API 编译检查通过
2026-09-08 23:38:25 +08:00
k88936 65e73eee02 补充 Raw 图片生成成功追踪
记录成功任务与输出数量
完善上游响应和失败阶段日志
2026-09-08 23:25:47 +08:00
k88936 6068eeda83 补充 Raw 图片编辑请求日志
记录上游响应状态与耗时
记录传输失败阶段和结构化上下文
2026-09-08 23:22:56 +08:00
k88936 0e244c64ea 统一 GPT Image 2 尺寸常量
集中维护像素边界和对齐规则
供生成与编辑路径共同引用
2026-09-08 22:11:35 +08:00
k88936 ad7c059603 遵守 Raw 图片请求截止时间
发送前裁剪有效超时预算
预算耗尽时提前返回结构化错误
2026-09-08 21:54:22 +08:00
k88936 55d2a393d1 完善 Raw 图片尺寸错误类型
为公开错误实现 Error trait
支持通用错误链处理
2026-09-08 21:52:15 +08:00
k88936 e7f66ce950 修正 Raw 图片传输失败阶段标记
区分请求发送和响应读取失败
让错误详情准确反映故障阶段
2026-09-08 20:03:13 +08:00
k88936 35dcfea3ef 修正 Raw 图片输出格式回退
忽略空值后再使用载荷级格式
补充空字符串和 null 回归测试
2026-09-08 19:56:41 +08:00
k88936 cea8bf77fa 减少 Raw 图片编辑请求拷贝
移动 multipart 选项字段而非克隆
降低掩码和字符串的峰值内存
2026-09-08 19:52:13 +08:00
k88936 0136bfe564 移出 Raw 图片同步解码
将请求预校验放入阻塞线程
避免占用 Tokio 异步工作线程
2026-09-08 19:48:58 +08:00
k88936 22785b4d7b 限制 Raw 图片解码资源
为 PNG 解码设置边长和分配上限
避免压缩图片膨胀导致内存耗尽
2026-09-08 19:45:02 +08:00
k88936 a86a2ee4d2 简化 Raw 图片编辑响应类型
移除无必要的 JSON Value 转换
保持响应结构由类型系统校验
2026-09-08 19:32:55 +08:00
k88936 b22eae2726 收紧 Raw 图片编辑输入契约
Project CI / Frontend tests (pull_request) Successful in 3m51s
Project CI / Native shell tests (pull_request) Successful in 20m20s
Project CI / Repository checks (pull_request) Failing after 14s
Project CI / Backend tests (pull_request) Failing after 14s
新增 3840 边长、16 像素对齐、3:1 比例和总像素范围校验

要求 image 与 mask 为可完整解码的 PNG 并在扣费前拒绝非法输入

将 Raw 路由 JSON body limit 提升至 64 MiB

同步 Raw 图片编辑技术方案和边界测试
2026-09-08 18:18:58 +08:00
k88936 35d0db6377 修复 Raw 图片失败审计与响应格式
Project CI / Frontend tests (pull_request) Successful in 6m7s
Project CI / Native shell tests (pull_request) Successful in 19m41s
Project CI / Repository checks (pull_request) Failing after 11s
Project CI / Backend tests (pull_request) Failing after 9s
为 Raw provider 失败分支补齐结构化 failure audit 并接入 api-server 记录链

使用 VectorEngine 响应 output_format 生成返回图片 MIME 与扩展名

补充响应格式和审计字段定向测试并同步技术方案
2026-09-08 16:19:29 +08:00
k88936 f087ba3e2b 隔离 Raw 图片代理实现
Project CI / Repository checks (pull_request) Failing after 14s
Project CI / Backend tests (pull_request) Failing after 14s
Project CI / Frontend tests (pull_request) Successful in 36m40s
Project CI / Native shell tests (pull_request) Successful in 54m1s
移除对现有图片编辑 client 与 curl transport 的复用

将 Raw GPT Image 2 请求、multipart 构造和响应解析收敛到独立文件

保持现有 editor 图片链路代码不变
2026-09-08 13:54:31 +08:00
k88936 7fc1b841be 收口 Raw 图片 base64 校验错误
客户端仅返回稳定的 base64 格式错误提示

补充测试避免泄露解码器内部诊断细节
2026-09-08 12:30:55 +08:00
k88936 a576fdcc37 移除未使用的 multipart 请求包装函数
无选项测试直接调用统一传输入口

避免生产构建保留未使用函数告警
2026-09-08 12:29:59 +08:00
k88936 4dcf38715b 补充图片编辑选项 multipart 测试
覆盖质量、背景、输出格式与 mask 文件字段

断言文件名、MIME 类型和字节内容均正确发送
2026-09-08 12:21:11 +08:00
k88936 d1f9f4e1ef 减少图片编辑 multipart 字节复制
将已克隆的选项按值传入阻塞传输函数

构造 mask 与参考图表单时直接移动字节缓冲
2026-09-08 12:16:00 +08:00
k88936 5836aaec26 简化图片编辑 multipart 请求分支
统一通过带选项的 multipart 传输函数发送请求

移除冗余包装函数调用与未使用导入
2026-09-08 12:10:56 +08:00
k88936 18d60feb04 补充 Raw 图片参数预检查
在计费前校验质量、背景和输出格式

规范化可选参数并保持单图请求契约
2026-09-08 10:40:09 +08:00
k88936 4e1316e272 实现 Raw GPT Image 2 图片编辑代理
新增受 Bearer 保护的 /api/raw/v1/images/edit JSON 路由

按单图 image 与可选 mask 转发 GPT Image 2 参数

固定 model 与 n 并返回仅含 data[].b64_json 的响应

复用钱包计费与退款边界并补充单元测试
2026-09-08 10:36:48 +08:00
k88936 302b4addae 补充 Raw GPT Image 2 代理方案
Project CI / Native shell tests (pull_request) Successful in 55m40s
Project CI / Backend tests (pull_request) Failing after 14s
Project CI / Repository checks (pull_request) Failing after 14s
Project CI / Frontend tests (pull_request) Successful in 23m43s
明确 JSON 请求与 data 数组响应

记录预检查和钱包事务边界

拆分 api-server 与 platform-image 文件职责
2026-09-07 16:33:34 +08:00
224 changed files with 6190 additions and 13947 deletions
-31
View File
@@ -232,37 +232,6 @@ jobs:
done
done
- name: Prepare standalone Rust crate dependencies
shell: bash
run: |
set -euo pipefail
# agent-runtime-core / agent-runtime-orchestration 被 server-rs/Cargo.toml 的
# exclude 排除,不参与上面的 workspace 锁文件,因此上面那次锁定 fetch 覆盖不到它们;
# 而 check:native-shells 会经 agent-runtime-*:check 用 `cargo test --manifest-path`
# 单独跑这两个 crate。不在这里预热的话,这两条测试会在测试阶段自己
# `Updating crates.io index`crates.io 一抖动整条 native shell 作业就红
# (见 #327 / PR #316 run 1950)。
# 两个 crate 都没有提交 Cargo.lock,所以这里只能做不带锁标志的 fetch:
# 加锁标志会因为缺少锁文件直接失败。生成的 Cargo.lock 落在两个 crate 目录内,
# 已被各自的 .gitignore 忽略,只留在容器里;随后的测试阶段因此能用锁定版本
# 解析,不再触碰 registry index。
for manifest_path in \
server-rs/crates/agent-runtime-core/Cargo.toml \
server-rs/crates/agent-runtime-orchestration/Cargo.toml; do
for attempt in $(seq 1 5); do
if cargo fetch \
--target x86_64-unknown-linux-gnu \
--manifest-path "${manifest_path}"; then
break
fi
if [[ "${attempt}" -eq 5 ]]; then
echo "standalone crate dependency fetch failed after 5 attempts: ${manifest_path}" >&2
exit 1
fi
sleep $((attempt * 2))
done
done
- name: Run native shell gates
run: npm run check:native-shells
@@ -108,13 +108,14 @@ const rustSharedContractSource = fs.readFileSync(
);
const allowedUncalledTauriCommands = [
'append_direct_project_conversation_message',
// TODO: Remove the retired binding command after the legacy runtime path is removed.
'bind_components',
'chat_with_game_creator_agent',
'check_ui_editor_font_glyph_coverage',
'create_ui_design_resource',
'open_game_creator_launcher_window',
'open_game_creator_workspace_window',
'read_direct_project_conversation',
'reset_design_agent_session',
'stop_local_game_preview_if_matches',
'start_game_creator_external_mcp',
'stop_game_creator_external_mcp',
@@ -1286,9 +1287,6 @@ if (tauriConfig.identifier !== 'world.genarrative.ai-game-creator') {
throw new Error('AI game creator shell identifier drifted');
}
const expectedBundledDesignAgentResources = {
'design-agent': 'design-agent',
};
const expectedBundledCodexResources = {
'resources/codex/win-x64/bin/codex.exe': 'codex/win-x64/bin/codex.exe',
'resources/codex/win-x64/bin/codex-code-mode-host.exe':
@@ -1304,33 +1302,16 @@ const expectedBundledCodexResources = {
'resources/codex/win-x64/NOTICE.md': 'codex/win-x64/NOTICE.md',
'resources/codex/win-x64/manifest.json': 'codex/win-x64/manifest.json',
};
assert.deepEqual(
tauriConfig.bundle?.resources,
expectedBundledDesignAgentResources,
'AI game creator shell base Tauri config must bundle the design-agent resource pack',
);
for (const key of Object.keys(tauriConfig.bundle?.resources ?? {})) {
if (String(key).includes('codex')) {
throw new Error(
'AI game creator shell base Tauri config must not require Windows-only Codex resources',
);
}
if (tauriConfig.bundle?.resources !== undefined) {
throw new Error(
'AI game creator shell base Tauri config must not require Windows-only Codex resources',
);
}
assert.deepEqual(
windowsTauriConfig.bundle?.resources,
expectedBundledCodexResources,
'AI game creator shell Windows Tauri config must bundle the complete pinned Codex resource set',
);
if (
Object.prototype.hasOwnProperty.call(
windowsTauriConfig.bundle?.resources ?? {},
'design-agent',
)
) {
throw new Error(
'design-agent resource pack must not be mixed into the Windows Codex sidecar bundle',
);
}
if (windowsTauriConfig.bundle?.useLocalToolsDir !== true) {
throw new Error(
'AI game creator shell Windows Tauri config must cache bundling tools in the project target directory',
@@ -20,10 +20,6 @@ import {
const appRoot = fileURLToPath(new URL('..', import.meta.url));
const repoRoot = resolve(appRoot, '../..');
const tauriCliPath = resolve(repoRoot, 'node_modules/@tauri-apps/cli/tauri.js');
const AGC_DESIGN_DEBUG_ENV = 'GENARRATIVE_AGC_DESIGN_DEBUG';
const AGC_DESIGN_DEBUG_VITE_ENV = 'VITE_GENARRATIVE_AGC_DESIGN_DEBUG';
const designDebugEnabled =
process.env[AGC_DESIGN_DEBUG_ENV]?.trim() === '0' ? '0' : '1';
function buildTauriArguments(argv, devUrl = readAgcDevEndpoint().url) {
const args = [...argv];
@@ -112,11 +108,7 @@ async function runTauriDev(
if (!prepared || shutdownSignal) return 1;
const tauriArguments = buildTauriArguments(argv, endpoint.url);
child = spawnCli(tauriArguments, {
env: {
...withAgcDevEndpointEnv(endpoint),
[AGC_DESIGN_DEBUG_ENV]: designDebugEnabled,
[AGC_DESIGN_DEBUG_VITE_ENV]: designDebugEnabled,
},
env: withAgcDevEndpointEnv(endpoint),
});
const childResult = waitForCli(child);
const outcome = await Promise.race([
@@ -165,13 +157,7 @@ async function prepareFrontendDev(endpoint, { onChild, signal }) {
const frontend = spawnChild(
process.platform === 'win32' ? 'npm.cmd' : 'npm',
['run', 'agc:serve'],
{
cwd: repoRoot,
env: {
...withAgcDevEndpointEnv(endpoint),
[AGC_DESIGN_DEBUG_VITE_ENV]: designDebugEnabled,
},
},
{ cwd: repoRoot, env: withAgcDevEndpointEnv(endpoint) },
);
onChild(frontend);
console.log(
@@ -1 +0,0 @@
当前阶段:系统架构。明确系统清单、职责边界、依赖和数据归属。
@@ -1,6 +0,0 @@
共享过程文件(如需维护,请使用这些相对路径):
- project/analysis.md
- project/决策台账.md
- project/dialog.md
不要把正式产物写在工作区根目录,也不要等审批失败后再迁移。
阶段审批工具:当你判断本阶段必需产物已完成时,必须提交阶段审批。用户批准后 Runtime 自动进入下一阶段;你不能自行切换阶段。
@@ -1 +0,0 @@
当前阶段:概念设计。明确游戏是什么、不是什么,并形成概念设计产物。
@@ -1,4 +0,0 @@
顾问阶段不需要继续自主推动项目或主动安排下一步;遵照用户的具体指示行动。
根据用户指示回答问题、读取相关文档、修改工作区文件,并说明改动可能影响的已有产物。
涉及方向性变化或多个可行方案时,先向用户说明影响并等待用户决定;不要替用户做决定。
顾问阶段没有下一层,也不需要提交阶段审批。
@@ -1 +0,0 @@
当前阶段:项目顾问。五个策划阶段已经完成,后续由用户指示驱动协作。
@@ -1,44 +0,0 @@
概念阶段定稿时,还必须创建或更新 `project/速览卡.md`。Runtime 只检查该文件是否存在,不检查内容。请使用下面的固定结构,不要加入审批操作说明或独立的决定状态段落:
# 速览卡:《游戏名》
## 1. 游戏名称
## 2. 游戏分类
## 3. 美术风格
- 视觉类型:
- 风格关键词:
- 色彩与氛围:
- MVP 美术边界:
## 4. 一句话描述
## 5. 游戏支柱
| 支柱 | 玩家感受 | 实现机制 |
|---|---|---|
## 6. 核心循环
## 7. 目标用户
- 核心用户:
- 游戏偏好:
- 单次游玩时长:
- 参考游戏与参考点:
## 8. 平台事实
## 9. 最小 MVP 系统
| 系统 | 最小功能 | 为什么必须有 | 验证方法 |
|---|---|---|---|
## 10. 给创作者的关键提示
- 先做:
- 暂时不做:
- 这样验证:
- 达标再扩展:
### 待原型验证项
- 问题:
- 原型:
- 观察:
@@ -1 +0,0 @@
当前阶段:系统文档。逐个完成已确定系统的内部规则、接口和验证标准。
@@ -1 +0,0 @@
当前阶段:技术文档。完成数据与配表、技术实现、美术圣经和总册。
@@ -1 +0,0 @@
当前阶段:顶层设计。明确玩家持续游玩的循环、资源流、节奏和系统范围。
File diff suppressed because one or more lines are too long
@@ -1,384 +0,0 @@
{
"version": 1,
"resources": [
{
"path": "skills/concept.md",
"id": "skills.concept",
"summary": "概念阶段写作规则。",
"category": "skills",
"title": "概念设计分册",
"inject_phases": [
"concept"
]
},
{
"path": "skills/top_design.md",
"id": "skills.top_design",
"summary": "顶层设计阶段写作规则。",
"category": "skills",
"title": "顶层设计分册",
"inject_phases": [
"top_design"
]
},
{
"path": "skills/architecture.md",
"id": "skills.architecture",
"summary": "系统架构阶段写作规则。",
"category": "skills",
"title": "系统架构分册",
"inject_phases": [
"architecture"
]
},
{
"path": "skills/systems.md",
"id": "skills.systems",
"summary": "系统文档阶段写作规则。",
"category": "skills",
"title": "系统文档分册",
"inject_phases": [
"systems"
]
},
{
"path": "skills/tdd.md",
"id": "skills.tdd",
"summary": "技术文档阶段写作规则。",
"category": "skills",
"title": "技术文档分册",
"inject_phases": [
"tdd"
]
},
{
"id": "templates.analysis",
"category": "templates",
"title": "analysis",
"summary": "策划文档结构模板。",
"path": "templates/analysis.md"
},
{
"id": "templates.architecture",
"category": "templates",
"title": "architecture",
"summary": "策划文档结构模板。",
"path": "templates/architecture.md"
},
{
"id": "templates.concept_design",
"category": "templates",
"title": "concept-design",
"summary": "策划文档结构模板。",
"path": "templates/concept-design.md"
},
{
"id": "templates.stardew_analysis",
"category": "templates",
"title": "stardew-analysis",
"summary": "策划文档结构模板。",
"path": "templates/stardew-analysis.md"
},
{
"id": "templates.tdd_art_bible",
"category": "templates",
"title": "tdd-art-bible",
"summary": "策划文档结构模板。",
"path": "templates/tdd-art-bible.md"
},
{
"id": "templates.tdd_data",
"category": "templates",
"title": "tdd-data",
"summary": "策划文档结构模板。",
"path": "templates/tdd-data.md"
},
{
"id": "templates.tdd_master",
"category": "templates",
"title": "tdd-master",
"summary": "策划文档结构模板。",
"path": "templates/tdd-master.md"
},
{
"id": "templates.tdd_tech",
"category": "templates",
"title": "tdd-tech",
"summary": "策划文档结构模板。",
"path": "templates/tdd-tech.md"
},
{
"id": "templates.top_design",
"category": "templates",
"title": "top-design",
"summary": "策划文档结构模板。",
"path": "templates/top-design.md"
},
{
"id": "exemplars.decision_log",
"category": "exemplars",
"title": "decision-log",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/decision-log.md"
},
{
"id": "exemplars.fast_gdd",
"category": "exemplars",
"title": "fast-gdd",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/fast-gdd.md"
},
{
"id": "exemplars.overview_card",
"category": "exemplars",
"title": "overview-card",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/overview-card.md"
},
{
"id": "exemplars.stardew_architecture",
"category": "exemplars",
"title": "stardew-architecture",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/stardew-architecture.md"
},
{
"id": "exemplars.stardew_concept",
"category": "exemplars",
"title": "stardew-concept",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/stardew-concept.md"
},
{
"id": "exemplars.stardew_s06_combat",
"category": "exemplars",
"title": "stardew-s06-combat",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/stardew-s06-combat.md"
},
{
"id": "exemplars.stardew_tdd_art_bible",
"category": "exemplars",
"title": "stardew-tdd-art-bible",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/stardew-tdd-art-bible.md"
},
{
"id": "exemplars.stardew_tdd_data",
"category": "exemplars",
"title": "stardew-tdd-data",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/stardew-tdd-data.md"
},
{
"id": "exemplars.stardew_tdd_master",
"category": "exemplars",
"title": "stardew-tdd-master",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/stardew-tdd-master.md"
},
{
"id": "exemplars.stardew_tdd_tech",
"category": "exemplars",
"title": "stardew-tdd-tech",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/stardew-tdd-tech.md"
},
{
"id": "exemplars.stardew_top_design",
"category": "exemplars",
"title": "stardew-top-design",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/stardew-top-design.md"
},
{
"id": "exemplars.tdd_art_bible_SKILL",
"category": "exemplars",
"title": "tdd-art-bible-SKILL",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/tdd-art-bible-SKILL.md"
},
{
"id": "exemplars.tdd_data_SKILL",
"category": "exemplars",
"title": "tdd-data-SKILL",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/tdd-data-SKILL.md"
},
{
"id": "exemplars.tdd_tech_SKILL",
"category": "exemplars",
"title": "tdd-tech-SKILL",
"summary": "策划文档范例或需求附件。",
"path": "exemplars/tdd-tech-SKILL.md"
},
{
"id": "system_types.核心玩法编排.skill",
"category": "system_types",
"title": "01_核心玩法编排 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/01_核心玩法编排/SKILL.md"
},
{
"id": "system_types.核心玩法编排.template",
"category": "system_types",
"title": "01_核心玩法编排 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/01_核心玩法编排/模板.md"
},
{
"id": "system_types.时间与日程.skill",
"category": "system_types",
"title": "02_时间与日程 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/02_时间与日程/SKILL.md"
},
{
"id": "system_types.时间与日程.template",
"category": "system_types",
"title": "02_时间与日程 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/02_时间与日程/模板.md"
},
{
"id": "system_types.生产种植经营.skill",
"category": "system_types",
"title": "03_生产种植经营 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/03_生产种植经营/SKILL.md"
},
{
"id": "system_types.生产种植经营.template",
"category": "system_types",
"title": "03_生产种植经营 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/03_生产种植经营/模板.md"
},
{
"id": "system_types.地图与探索.skill",
"category": "system_types",
"title": "04_地图与探索 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/04_地图与探索/SKILL.md"
},
{
"id": "system_types.地图与探索.template",
"category": "system_types",
"title": "04_地图与探索 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/04_地图与探索/模板.md"
},
{
"id": "system_types.采集与支线活动.skill",
"category": "system_types",
"title": "05_采集与支线活动 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/05_采集与支线活动/SKILL.md"
},
{
"id": "system_types.采集与支线活动.template",
"category": "system_types",
"title": "05_采集与支线活动 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/05_采集与支线活动/模板.md"
},
{
"id": "system_types.战斗与敌人.skill",
"category": "system_types",
"title": "06_战斗与敌人 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/06_战斗与敌人/SKILL.md"
},
{
"id": "system_types.战斗与敌人.template",
"category": "system_types",
"title": "06_战斗与敌人 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/06_战斗与敌人/模板.md"
},
{
"id": "system_types.物品背包与制作.skill",
"category": "system_types",
"title": "07_物品背包与制作 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/07_物品背包与制作/SKILL.md"
},
{
"id": "system_types.物品背包与制作.template",
"category": "system_types",
"title": "07_物品背包与制作 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/07_物品背包与制作/模板.md"
},
{
"id": "system_types.成长与技能.skill",
"category": "system_types",
"title": "08_成长与技能 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/08_成长与技能/SKILL.md"
},
{
"id": "system_types.成长与技能.template",
"category": "system_types",
"title": "08_成长与技能 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/08_成长与技能/模板.md"
},
{
"id": "system_types.NPC关系与任务.skill",
"category": "system_types",
"title": "09_NPC关系与任务 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/09_NPC关系与任务/SKILL.md"
},
{
"id": "system_types.NPC关系与任务.template",
"category": "system_types",
"title": "09_NPC关系与任务 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/09_NPC关系与任务/模板.md"
},
{
"id": "system_types.经济与商店.skill",
"category": "system_types",
"title": "10_经济与商店 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/10_经济与商店/SKILL.md"
},
{
"id": "system_types.经济与商店.template",
"category": "system_types",
"title": "10_经济与商店 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/10_经济与商店/模板.md"
},
{
"id": "system_types.事件与节日.skill",
"category": "system_types",
"title": "11_事件与节日 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/11_事件与节日/SKILL.md"
},
{
"id": "system_types.事件与节日.template",
"category": "system_types",
"title": "11_事件与节日 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/11_事件与节日/模板.md"
},
{
"id": "system_types.UI与文本呈现.skill",
"category": "system_types",
"title": "12_UI与文本呈现 skill",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/12_UI与文本呈现/SKILL.md"
},
{
"id": "system_types.UI与文本呈现.template",
"category": "system_types",
"title": "12_UI与文本呈现 template",
"summary": "系统类型写法规则或模板。",
"path": "modules/system-types/12_UI与文本呈现/模板.md"
}
]
}
@@ -1,66 +0,0 @@
# 决策台账:《星露谷物语》金样项目
版本:v3 | 规则:台账放活队列——design 只放结论、分析只放论证、决定与开放问题住这里。编号连续不复用;被推翻的行标 overturned 挂新行,不删行。
状态六态:`confirmed`(用户亲口/亲选)/ `auto_decided`(技术类代决,必带理由+推翻条件,用户一键可翻)/ `default_pending`(默认建议兜底,用户未点头)/ `prototype_pending`(待原型验证)/ `pending_user`(等用户拍板)/ `overturned`(被推翻,挂旧行编号)。
> 编号口径:D-01~D-13 与 exemplars/stardew-analysis.md 台账节选一致(D-04~D-06、D-08~D-10、D-12 原为"就地小权衡,直接登记未开条目",此处按登记口径展开);D-14 起为技术文档期新增,与 stardew-tdd-tech.md 开放问题回执互引。
## 当前待办(活队列)
### 等用户拍板(pending_user
| 编号 | 决定 | 层 | 谁 | 依据 | 推翻条件 | 状态 |
|---|---|---|---|---|---|---|
| D-14 | 体力与战斗共享单池 | TDD | user | 风险资源统一制造取舍(概念张力一);**暂按共享实现,改单拆只需改 S02 成本入口** | 战斗参与率实测过低(玩家回避矿井) | pending_user(暂按共享实现) |
| D-15 | 背包格子制 vs 重量制 | TDD | user | 格子制直觉、重量制焦虑感与 T5"休闲不打卡"冲突;暂按格子制实现、存档预留 capacity_type 字段 | 格子管理成为主要负面反馈 | pending_user(B 级阻断存档结构,暂按格子制) |
### 待原型验证(prototype_pending
| 编号 | 决定 | 层 | 谁 | 依据 | 推翻条件 | 状态 |
|---|---|---|---|---|---|---|
| D-13b | 战斗判定窗口手感(前摇帧数/无敌帧 450ms 基准) | 系统 | user | 数值可定、手感不可纸面验证 | 原型显示节奏拖慢/玩家困惑 | prototype_pending(规则本体见 D-13 confirmed |
### 默认建议兜底(default_pending
| 编号 | 决定 | 层 | 谁 | 依据 | 推翻条件 | 状态 |
|---|---|---|---|---|---|---|
| D-19 | 天气权重表具体数值(晴/雨/风暴按季节) | TDD | agent | 概念层只定"雨免浇水"定性;数值推内容期填 | 前 5 日出现连续 3 日雨/全无雨 | default_pending(默认值已进数据表,带 designer_note |
## 已采用决定
### 用户确认(confirmed
| 编号 | 决定 | 层 | 谁 | 依据 | 推翻条件 | 状态 |
|---|---|---|---|---|---|---|
| D-01 | 定调:牧场物语系参照、治愈慢节奏 | 概念 | user | 用户原始需求 | — | confirmed |
| D-02 | 单人体验,无多人 | 概念 | user | 概念层非目标 | — | confirmed |
| D-03 | 战斗保持伴生风险,不做装备驱动主轴 | 概念 | user | 概念期问题一 | 矿井流失率过半且归因战斗 | confirmed |
| D-07 | 日目标自设,季节与社区提供低频牵引 | 顶层 | user | 顶层期问题一 | 新手周流失归因无方向 | confirmed |
| D-11 | 采集/钓鱼/战斗统一"活动结果"接口 | 架构 | user | 架构期问题一 | 第三活动类型出现结构性差异 | confirmed |
| D-13 | 战斗采用节奏/指令判定 | 系统 | user | S06 问题一 | 原型显示节奏拖慢/玩家困惑 | confirmed(手感部分拆 D-13b prototype_pending |
### 技术代决(auto_decided——带理由与推翻条件,用户一键可翻)
| 编号 | 决定 | 层 | 谁 | 依据(理由) | 推翻条件 | 状态 |
|---|---|---|---|---|---|---|
| D-04 | 时间片制:700ms=10 游戏分钟 | 概念 | agent | 原作实证节拍;一天≈14 分钟真实时间贴合 T5"休闲" | 内测一天体感过短/过长 | auto_decided |
| D-05 | 分区域切换(区域独立场景,非连续地图) | 概念 | agent | 概念层"不是什么:无边界开放世界";区域小网络全部步行可达 | 场景切换成为移动负担反馈 | auto_decided |
| D-06 | 28 日/季、四季/年 | 顶层 | agent | 季节窗口制造"本季计划"节奏(支柱二) | 换季频率在测试中被无视 | auto_decided |
| D-09 | 商店营业时段走条件表 | 架构 | agent | 与配方/区域解锁共用 check(condition_id) 单一入口 | 条件表规模膨胀难维护 | auto_decided |
| D-10 | 出货箱日终统一结算 | 架构 | agent | 收入集中进日终面板,强化"一天一结算"叙事;商店现卖保留即时通道 | 玩家普遍绕开出货箱 | auto_decided |
| D-12 | 工具升级期间该工具不可用 | 系统 | agent | 升级=时间成本换效率(顶层张力二);备用旧工具暂不做(开放问题) | 升级期挫败感集中爆发 | auto_decided |
| D-16 | 矿井逐层生成本期不做(P2 | TDD | agent | GDD 已标"不做无限地牢";首期按布局池 8~12 模板拼装 | 内测要求深度爬塔玩法 | auto_decided |
| D-17 | 换装首期 5 层(基础体/裤/衣/发型/饰件),非 19 层 | TDD | agent | 外观自定义非首期卖点;层结构预留到 19 层 | 外观系统成核心诉求 | auto_decided |
| D-18 | 作物品质三档:普通/银/金 | TDD | agent | 经济分层需要(即时变现 vs 等待升值的取舍) | 银金档无人区分、一律普通出售 | auto_decided |
### 已推翻(overturned——旧行保留,挂新行)
| 编号 | 决定 | 层 | 谁 | 依据 | 推翻条件 | 状态 |
|---|---|---|---|---|---|---|
| D-08 | 作物品质两档:普通/银 | TDD | agent | 早期小权衡:两档最简 | — | **overturned → D-18**(经济分层不足,改三档;铱档留 P1) |
## 队列纪律(给 agent 的使用说明)
- 新决定入队:拿下一号(当前最大 D-19,下一号 D-20);就现代决可登记不开条目,但状态必须写 auto_decided 并带理由+推翻条件。
- 用户翻案:旧行标 overturned 挂新行,受影响文档节重写(本台账只记录,不代改)。
- 概念层变更定稿后:速览卡"决定状态与原型验证项"字段随本文件最新版同步(prompt 级纪律)。
@@ -1,124 +0,0 @@
# 脉冲荒原:节点争夺战
> Fast GDD v1 · 状态:ready\_for\_approval
> gddId`gdd-a5309290-edd4-4232-9c7c-d99024e0fa42`
> fingerprint`sha256-serde-json-v2:1d34b0cbee5f623a224102e4d832ad6ecc10ffbf27b876d9bc1e24a5483f06a3`
> approvalRequestId`gdd-approval-6f5de673-553d-499f-8ca1-8c32f4841bc0`
## 决定状态
- **初始需求**confirmeduser\_freeform,第 0 轮):用户提出制作原创、可落地的2D坦克大战MVP。
- **坦克对战的胜负目标**confirmeduser\_option,第 1 轮):采用区域争夺作为每局主要胜负目标。
- **区域争夺的占领方式**confirmeduser\_option,第 2 轮):采用少量多节点轮换占领,迫使双方在路线间转移争夺。
- **轮换节点的结束规则**confirmeduser\_option,第 3 轮):控制当前节点持续得分,任一方先达到目标分即获胜。
- **目标用户**default\_pendingdefault,第 0 轮):默认面向喜欢短局、直接操控、位置博弈和可重复挑战的休闲动作玩家。
- **美术方向**default\_pendingdefault,第 0 轮):默认采用风格化、轮廓清晰的原创战场与占位资产,优先验证可读性。
- **成长范围**default\_pendingdefault,第 0 轮):默认设置一条轻量成长线,仅提供少量战后选择,不影响单局闭环。
- **MVP内容边界**default\_pendingdefault,第 0 轮):默认首个版本只做单人对抗一名基础AI、单张地图和一套坦克配置。
## 一句话描述
驾驶原创装甲穿越掩体,在轮换能量节点间交火夺分,先达目标分者赢得一局紧凑的2D坦克区域争夺战。
## 游戏分类与美术
- 主类型:2D坦克区域争夺
- 融合类型:无
- 视觉类型:风格化俯视2D
- 关键词:轮廓清晰、几何掩体、弹道高亮、原创装甲
- 色彩氛围:冷青灰战场衬托橙蓝阵营高亮;节点被占领时产生清晰的环形脉冲,命中、受击和得分使用短促高对比反馈。
- MVP 美术边界:MVP 使用可复用的几何占位资产:一张俯视战场、两种原创装甲外形、节点与掩体模块;先保证阵营、弹道、占领状态在桌面和移动视口均清楚。
## 游戏支柱
### 移动夺势
- 玩家感受:始终知道下一处冲突在哪里,移动本身就是争夺优势而非赶路。
- 机制:节点位置与活跃状态持续改变,玩家必须在占领、转移、驻守和反攻之间做出即时选择。
- 决定状态:confirmed
### 掩体交火
- 玩家感受:每次探头、绕侧和开火都带来可读的风险回报。
- 机制:几何掩体阻挡弹道,玩家通过角度、射击窗口和绕行路线逼退对手,再进入节点控分。
- 决定状态:confirmed
### 清晰逆转
- 玩家感受:局势紧张但不迷惑,玩家理解自己为何领先或落后并愿意再开一局。
- 机制:目标分、活跃节点和控制状态持续可视化;落后方可通过夺回当前节点改变局势。
- 决定状态:confirmed
## 核心循环
1. 进入战场并观察当前活跃节点与敌方位置
2. 驾驶“棱虎机”在几何掩体间移动,瞄准并发射脉冲炮
3. 抵达活跃节点并在敌方干扰下完成占领或夺回
4. 控制节点持续积累“脉冲分”,节点轮换后转移路线
5. 先达到目标分的一方获胜,结算后可立即重开
## 目标用户
- 核心用户:偏好短局即时动作、方向操控、躲避射击和争夺空间的休闲玩家;可接受单人对抗基础AI。
- 偏好:喜欢规则一眼可懂、操作反馈直接、每局约十几分钟内完成,并能通过走位和时机而非复杂配装取胜。
- 单局时长:默认每局约10~20分钟;首个可玩闭环优先做到一局可完整开始、争夺、决胜和重开。
- 参考游戏:无
## Runtime 平台事实
- Runtimeself-contained-web
- 视口:desktop / mobile
- 输入:keyboard / touch
- 预览:local-http
## MVP 系统
### 坦克操控与射击
- 最小功能:提供八方向移动、旋转瞄准、单一脉冲炮射击、受击反馈与短暂失活重生,支持键盘和触控操作。
- 必要原因:直接构成坦克对战手感,也是区域争夺发生的主要冲突手段。
- 验证方式:试玩者能在一分钟内完成移动、瞄准、射击和躲入掩体,并能用射击驱离节点附近敌人。
- 决定状态:confirmed
### 轮换节点占领
- 最小功能:以少量节点组成单张战场,仅一个节点在任一时刻活跃;进入后按占优方推进占领,活跃节点轮换并提供清晰状态提示。
- 必要原因:落实用户确认的多节点轮换占领,并制造移动、停留和反攻决策。
- 验证方式:玩家无需额外说明即可找到活跃节点,读懂中立、己方和敌方控制状态,并在轮换后改变路线。
- 决定状态:confirmed
### 目标分胜负
- 最小功能:活跃节点由控制方持续获得脉冲分;任一方先达到目标分即胜,显示双方分数、当前节点和胜负结算。
- 必要原因:把占领行为闭合成清晰、可验证的单局目标。
- 验证方式:试玩者能预测哪方领先、理解如何逆转,并在达到目标分时明确知道对局结束。
- 决定状态:confirmed
### 俯视战场结构
- 最小功能:布置可绕行的几何掩体、节点路径与出生区域;掩体阻挡弹道并形成接近、驻守和侧袭路线。
- 必要原因:让位置博弈支撑区域争夺,避免节点规则沦为单纯站桩计分。
- 验证方式:观察玩家是否主动利用掩体接近节点或规避火力,而非只在开阔地互射。
- 决定状态:confirmed
### 基础对手AI
- 最小功能:提供一名基础AI对手:追踪活跃节点、靠近争夺、在射程内攻击并在失活后返回战场。
- 必要原因:在无多人条件下完成完整的对抗闭环并验证核心玩法。
- 验证方式:连续试玩中,AI应持续争夺节点并制造可理解的反攻机会,不出现长时间卡住或无目标游走。
- 决定状态:default\_pending
## 制作边界
- 多人联机与服务器
- 商城、赛季和复杂社交
- 开放世界与完整剧情
- 多地图、多武器树与复杂成长
- 可编辑关卡和排行榜
## 创作者提示
- 先做:先做单张紧凑俯视战场、玩家坦克、基础AI对手、移动瞄准射击、掩体碰撞、节点轮换、占领计分和胜负结算,确保一局可从开始玩到结束。
- 暂缓:暂缓多人联机、商城、服务器、开放世界、赛季、复杂社交、完整剧情、多武器树和多地图内容。
- 如何验证:用可操作原型观察玩家是否在首局主动驶向活跃节点、利用掩体交火、理解分数变化并完成一局;记录误读占领状态、无目标游走和胜负不明的情况。
- 何时扩展:仅当试玩者能无讲解理解活跃节点、占领状态和领先来源,并主动移动反攻时,再增加第二种坦克特性、第二张地图或轻量成长选择。
@@ -1,59 +0,0 @@
# 速览卡:《星露谷物语》金样项目
> 12 字段版本;渲染器照旧出卡走审批。字段来源见每节尾注(概念层/定调记录/台账投影)。概念层变更定稿后本卡必须同步更新(prompt 级纪律)。
## 1. 游戏名称
《星露谷物语》(金样项目沿用案例名;新项目由概念层第 1 节定名)←概念层§1
## 2. 一句话描述
继承一座荒废农场的乡村生活 RPG:安排每天的时间与体力,种田、探索、交朋友,把日子过成自己想要的样子。(←概念层§1 一句话概念,45~90 字)
## 3. 游戏分类
乡村生活模拟 RPG(经营+探索+社交;参照系牧场物语)←概念层§1
## 4. 美术风格(四件)←定调记录+概念层§4
- 视觉类型:手绘感像素风、俯视 45° 视角。
- 风格关键词:温暖、田园、四季分明、生活感。
- 色彩与氛围:暖土绿基底+季节信号色整体切换;治愈不压抑;无锐利科技感、无阴暗元素。
- MVP 美术边界:首期 3 区域 tileset、8 位 NPC(行走+立绘)、约 120 物品图标、玩家换装 5 层;不做 19 层全量换装与全区域。
## 5. 游戏支柱(3 条)←设计锚点提炼
| 支柱 | 玩家感受 | 实现机制 |
|---|---|---|
| 自己的节奏 | "今天想干嘛就干嘛,明天一切更顺手。" | 自由日程+时间体力预算;无失败结局 |
| 今天的选择让明天更从容 | "升级工具、攒钱扩建是有意义的。" | 长期投资线:工具升级/技能/设施 |
| 社区让独居变成归属 | "镇上的人在等我。" | NPC 关系/任务/社区修复目标 |
## 6. 核心循环(5 步)←锚点循环位展开
安排一天的时间与体力 → 农/采/钓/矿/战/社交任选组合 → 获得资源·金钱·经验·关系 → 投资工具·设施·种子·物品 → 解锁更高效或更丰富的活动。
## 7. 目标用户 ←概念层§5
牧场物语系慢节奏成长玩家+动森式"无压力日常"需求;单人、可反复、每次一至数个游戏日;不要求预先掌握复杂数值。
## 8. 平台事实 ←运行时注入,禁改
自包含 Web · 双视口(桌面/移动)· 键鼠/触屏双输入 · 本地 HTTP 预览(金样项目按 HTML 演示路线锁定)。
## 9. MVP 系统(5 个)←概念层"最小闭环粗清单"
| 系统 | 最小功能 | 为什么必须有 | 验证方法 |
|---|---|---|---|
| 时间与日程 | 时钟/日终结算/季节天气 | 全局节拍器 | 一个游戏日全流程可完成并结算 |
| 体力与状态 | 单池体力/昏倒惩罚 | 一切取舍的成本源 | 玩家主动在体力耗尽前收手 |
| 农场经营 | 锄种浇收+加工队列 | 核心产出与规划场 | "买种→收获→出售"闭环成立 |
| 物品与制作 | item_id/背包/配方解锁 | 资源身份与转化 | 拾取/堆叠/制作全链无回翻 GDD |
| 经济与商店 | 基准价+价差+出货箱 | 投资回报换算 | 第 4 日现金流回正(前五日验算) |
## 10. 制作边界 ←概念层"不是什么"表
不做:硬核生存(无饥饿/债务/死亡惩罚);效率至上的工厂经营;以战斗为核心的动作游戏;剧情驱动的任务链主线;多人竞争;无边界开放世界(区域小网络全步行可达)。
## 11. 创作者提示(先做与验证)←概念层"先做与验证"节
- 先做:第 1 日循环(买种→播种→浇灌→收获→出售→日终结算)+一个可进入的矿井遭遇。
- 暂不做:装备刷取、随机构筑、复杂剧情、节日全量、联机。
- 这样验证:测试者玩完第 1 日后是否主动说"再玩一天";能否说出"明天要先做什么"。
- 达标再扩展:玩家能自述明日计划后,才加社交深度与矿井分层。
## 12. 决定状态与原型验证项 ←台账投影(decision-log.md v3
- 已确认(confirmed):定调 D-01 / 单人 D-02 / 战斗伴生 D-03 / 日目标自设 D-07 / 活动统一接口 D-11 / 战斗节奏判定 D-13。
- 技术代决(auto_decided,可一键翻案):D-04 时间片 / D-05 分区域切换 / D-06 28 日季 / D-09 营业条件 / D-10 出货箱日终 / D-12 工具占用 / D-16 矿井生成 P2 / D-17 换装 5 层 / D-18 品质三档(推翻 D-08 两档)。
- 等拍板(pending_user):D-14 体力战斗是否共享单池(暂按共享实现);D-15 背包格子/重量(暂按格子制,B 级阻断存档结构)。
- 待原型(prototype_pending):D-13b 战斗判定窗口手感(前摇帧数/450ms 无敌帧基准)。
- 默认兜底(default_pending):D-19 天气权重数值(默认已入表,带 designer_note)。
@@ -1,200 +0,0 @@
# 系统架构:《星露谷物语》
## 架构定位与目标
本阶段确定"哪些系统支撑一轮玩法",不展开单系统内部规则。
划分原则:将生活模拟 RPG 拆成职责清晰、可独立讨论的规则系统,同时保留少量跨系统入口,避免"每个功能都能互相调用"造成架构失控。系统划分服务于顶层循环:安排一天、执行活动、获得进展、投入成长、解锁新选择。
一句话架构:
> 玩家在有限的时间与体力下,通过农场、探索与社交三组活动系统产出资源与关系,经物品与经济系统转化为投资,由时间系统推进日终,把一天的成果变成下一天的选择。
变更记录:
- 2026-09-05:战斗与敌人系统定为伴生风险定位,深度刻意受限,不进入最小闭环核心链(依据:概念分析 D-03)。
## 系统地图
| 编号 | 系统 | 一句话职责 | 优先级 |
|---|---|---|---|
| S01 | 时间与日程 | 推进游戏时间、日期、季节、天气、营业时间、NPC 日程和日终结算 | P0 |
| S02 | 体力与状态 | 管理体力、负面状态、恢复、昏倒和行动成本 | P0 |
| S03 | 农场经营 | 管理土地、作物、畜牧、农场设施和生产状态 | P0 |
| S04 | 探索与地图 | 管理区域、出入口、可交互资源点、地图解锁和移动 | P0(基础) |
| S05 | 采集与钓鱼 | 管理野外采集、钓鱼活动、资源品质和获得物 | P1 |
| S06 | 战斗与敌人 | 管理矿区或危险区域中的战斗、伤害、敌人行为和战利品 | P1 |
| S07 | 物品、背包与制作 | 管理物品实例、堆叠、工具、装备、配方和制作队列 | P0 |
| S08 | 成长与技能 | 管理技能经验、等级、工具升级、职业选择和能力解锁 | P0(基础) |
| S09 | 经济与商店 | 管理货币、买卖、价格、商店库存、订单和资金流 | P0 |
| S10 | NPC 与关系 | 管理 NPC 日程、对话、好感度、礼物偏好和关系事件 | P1 |
| S11 | 任务与社区目标 | 管理任务状态、阶段目标、奖励、社区修复和区域解锁条件 | P1 |
| S12 | 事件与节日 | 管理季节事件、节日活动、条件触发和特殊奖励 | P1 |
支撑层(不拥有核心规则):
- 存档与进度系统:保存跨日、跨季节和跨阶段的持久状态。
- UI 与文本呈现层:展示状态、提供操作入口、呈现反馈与文本。
P0 段:
| 系统 | 目的 | 输入 | 输出 | P0 原因 |
|---|---|---|---|---|
| S01 时间与日程 | 全局时钟与日终 | 各系统行动完成信号、日终触发 | 日期/季节/天气变化、日终结算、跨天 tick | 没有"一天",规划与取舍失去标尺 |
| S02 体力与状态 | 全局行动成本 | 各系统行动请求、食物与休息 | 体力变化、昏倒、状态效果 | 没有它,"想做的事多于做得到的"不成立 |
| S03 农场经营 | 核心产出与规划场 | 时间 tick、种子与工具、体力 | 作物畜产品、设施生产状态 | 概念核心承诺的载体 |
| S04 探索与地图 | 活动场景与空间约束 | 移动指令、区域解锁条件 | 位置、区域状态、资源点入口 | 没有空间结构,农/矿/镇一体失去意义 |
| S07 物品与制作 | 资源身份与转化 | 各系统获得物、配方请求 | 物品实例、制作结果 | 所有系统产出的公共语言 |
| S08 成长与技能 | 长期回报层 | 各活动经验提交 | 等级、能力与配方解锁 | 长期动机的最小载体 |
| S09 经济与商店 | 投资与回报换算 | 物品、金钱 | 价格、交易、库存 | 没有它,"变现 vs 投资"张力无载体 |
## 系统职责
| 系统 | 主要职责 | 不负责 → 移交谁 |
|---|---|---|
| S01 时间与日程 | 时间推进、日期、季节、天气、营业与日终 | 直接决定某项活动的奖励 → 各活动系统 |
| S02 体力与状态 | 行动消耗、恢复、昏倒、状态效果 | 农作物或敌人的具体配置 → S03/S06 |
| S03 农场经营 | 土地、作物、畜牧、设施生产 | 商店买卖规则和角色技能 → S09/S08 |
| S04 探索与地图 | 区域连接、进入条件、资源点位置、移动 | 具体掉落概率和战斗公式 → S05/S06 |
| S05 采集与钓鱼 | 采集和钓鱼行为、成功条件、获得物 | 物品价格和任务奖励 → S09/S11 |
| S06 战斗与敌人 | 战斗流程、敌人状态、伤害与战利品请求 | 角色长期成长和商店价格 → S08/S09 |
| S07 物品与制作 | 背包、物品、配方、制作与工具装备 | 物品最终经济价值的平衡目标 → S09 |
| S08 成长与技能 | 经验、等级、技能分支、能力解锁 | 单次行动的基础奖励 → 各活动系统 |
| S09 经济与商店 | 货币、交易、库存、订单、价格 | 任务剧情与 NPC 情感变化 → S10/S11 |
| S10 NPC 与关系 | 日程、互动、好感、关系事件 | 全局季节推进和商店库存 → S01/S09 |
| S11 任务与社区 | 目标、前置、奖励、社区进度和解锁 | NPC 的日常行为表现 → S10 |
| S12 事件与节日 | 周期事件、特殊流程和限定内容 | 常规日常行动的基础规则 → 各活动系统 |
职责说明:
### S01 时间与日程系统
负责一天制的节奏规则:什么时候推进日期、哪些系统收到跨天 tick、日终结算何时发生。它不负责奖励结算,也不负责作物成长规则——只负责"什么时候"和"谁被通知"。
### S06 战斗与敌人系统
负责战斗内状态、敌人行为与战利品请求。它不直接修改商店价格或 NPC 好感,不负责角色长期成长;战利品只提交请求,由 S07 物品系统入账。定位是矿井探索的风险与节奏变化,不是成长主轴(D-03)。
### S07 物品、背包与制作系统
负责物品身份、容器、堆叠与配方队列。它是全项目的公共语言层——任何系统的产出都以 `item_id` 入账;它不负责物品的经济价值平衡,价格只由 S09 维护。
## 依赖与数据流
```mermaid
flowchart TD
S1[S01 时间与日程] --> S2[S02 体力与状态]
S1 --> S3[S03 农场经营]
S1 --> S4[S04 探索与地图]
S1 --> S10[S10 NPC 与关系]
S1 --> S12[S12 事件与节日]
S3 --> S7[S07 物品与制作]
S4 --> S5[S05 采集与钓鱼]
S4 --> S6[S06 战斗与敌人]
S5 --> S7
S6 --> S7
S7 --> S9[S09 经济与商店]
S7 --> S8[S08 成长与技能]
S8 --> S7
S10 --> S11[S11 任务与社区]
S12 -.读取日期季节.-> S1
UI[UI 与文本呈现] -.读取状态.-> S1
UI -.读取状态.-> S3
UI -.读取状态.-> S7
SAVE[存档与进度] -.订阅持久状态.-> S1
```
```mermaid
flowchart LR
T[时间/体力] --> ACT[玩家行动]
ACT --> GAIN[物品·金钱·经验·关系·任务进度]
GAIN --> INV[制作·交易·升级·解锁]
INV --> NEW[新的行动选择]
NEW --> ACT
```
主要状态:
- 全局状态:日期、季节、天气、当前时间、已解锁区域、社区进度。
- 玩家状态:位置、体力、生命、技能等级、工具、装备、背包和金钱。
- 场景状态:土地、作物成长、设施生产、资源点、敌人和宝箱。
- 社会状态:NPC 位置、关系值、已触发事件、任务阶段和节日参与状态。
主数据归属规则:
- 规则文档描述"如何计算"和"何时发生";数据表描述"有哪些对象"和"每个对象的配置"。
- 系统之间通过稳定 ID 关联(物品 ID、NPC ID、区域 ID、任务 ID、配方 ID)。
- 任何系统都不复制另一系统的主数据;任务只引用物品 ID,不重新定义物品价格。
## 核心循环覆盖检查
| 顶层循环环节 | 认领系统 |
|---|---|
| 查看天气、日程与目标 | S01、S11、S12、UI |
| 选择活动并移动 | S04、S02 |
| 农务与生产 | S03、S07、S02 |
| 采集、钓鱼与战斗 | S04、S05、S06、S07 |
| 出售、购买与投资 | S09、S07、S03 |
| 社交与委托 | S10、S11、S07 |
| 日终结算与保存 | S01、S12、存档、UI |
## 目录映射
| 目录 | 本阶段定位 |
|---|---|
| 03_systems/S01_time_schedule/ | 时间推进、日期季节天气、营业时段、日终结算 |
| 03_systems/S02_stamina_status/ | 体力、状态效果、昏倒与恢复 |
| 03_systems/S03_farm_management/ | 土地、作物、畜牧、设施生产 |
| 03_systems/S04_exploration_map/ | 区域、连接、资源点、解锁与移动 |
| 03_systems/S05_foraging_fishing/ | 采集、钓鱼、品质与获得物 |
| 03_systems/S06_combat_enemies/ | 战斗、敌人行为、伤害与战利品请求 |
| 03_systems/S07_items_inventory_crafting/ | 物品、背包、配方与制作队列 |
| 03_systems/S08_progression_skills/ | 技能经验、等级、工具升级、能力解锁 |
| 03_systems/S09_economy_shop/ | 货币、买卖、价格、库存与订单 |
| 03_systems/S10_npc_relationship/ | NPC 日程、对话、好感与关系事件 |
| 03_systems/S11_quests_community/ | 任务、社区目标、奖励与解锁条件 |
| 03_systems/S12_events_festivals/ | 季节事件、节日、条件触发 |
| 支撑层不单开系统文档 | 存档与 UI 随实现层组织,规则不独立成文 |
## MVP 最小闭环
1. 玩家在一个游戏日内完成开垦、播种、浇灌,并看到成长状态反馈。
2. 在时间与体力约束下选择当日主目标(农场劳动或外出)。
3. 外出采集(或矿井轻度战斗)带回资源。
4. 通过出售或加工获得金钱,投资种子或工具。
5. 日终结算展示当日变化并保存。
6. 次日作物状态变化,玩家据此形成新计划。
7. 数个游戏日内出现第一次技能提升与配方解锁。
如果这条闭环不成立,不应继续增加钓鱼深度、节日、社区目标或更多区域。
## 统一数值基准
本案例采用"宽松治愈型"数值风格。全局单位:时间片、游戏日、货币、体力、经验;所有数值字段必须注明单位。
- 时间节奏基准:单次常规行动控制在短时间片内;玩家一天应能完成农务、一个主要外出目标和少量顺路活动;早期玩家不应因一次路线失误失去整天进度。
- 货币量级基准:主要货币只有一种;初期基础种子可用少量日常产出购买;一次普通收获不应立刻买下最高阶升级;任务奖励以补足短期资金为主,不替代生产交易。
- 成长回报基准:前几级在正常尝试一种活动的数个游戏日内出现;升级奖励优先采用节省时间体力、扩大选择和解锁配方,而非单纯提高伤害售价;专长分支宽松可恢复。
- 体力与风险基准:体力是规划提示不是严苛倒计时;普通农务与移动成本低,战斗、钓鱼和重型工具才产生明显取舍;失败成本采用时间、少量金钱或位置变化,不损毁进度。
(具体换算数值与前五日验算由技术文档层·数值策划承接。)
## 系统边界
- 农场经营只管理农场内的生产状态,不负责所有资源的通用背包逻辑。
- 探索与地图只管理"在哪里"和"能否进入",不管理每种活动的具体奖励。
- 战斗只管理战斗内状态和战利品请求,不直接修改商店价格或 NPC 好感。
- NPC 与关系负责互动和关系变化;任务与社区负责可验证目标,二者通过事件和条件连接。
- UI、文本和表现不反向承载核心规则;所有关键变化必须由规则系统确认。
- 本案例不拆出独立多人、拍卖、复杂天气模拟、动态市场或高复杂度叙事工具系统。
## 优先级与范围
- P0(最小可玩闭环):时间与日程、体力、农场、物品背包、经济、基础地图、基础成长和日终结算。
- P1(形成完整案例):采集、钓鱼、轻度战斗、NPC 关系、任务、社区目标、制作、商店、季节和节日。
- P2(扩展内容):更多区域、敌人、作物、配方、关系事件、节日小游戏和终局后的自由活动。
拆分系统不等于所有系统都要在最小版本同时实现;系统独立性是为了便于协作和后续裁剪。
## 风险与校验
| 风险 | 校验方式 |
|---|---|
| 农场变成例行公事,失去规划感 | 玩家是否在目标选择阶段出现真实取舍与计划调整 |
| 矿井战斗反客为主 | 战斗收益是否仍以"农场难以产出的材料"为主,而非直接金钱 |
| 时间压力变成打卡义务 | 休闲型玩家能否自由调低日程重量而不被惩罚 |
| 经济成长过快,后期失去决策 | 升级价格是否持续制造"效率 vs 规模"的选择 |
| UI 泄题,探索失去意义 | 关键信息是否保留为探索发现而非全量直读 |
| 系统间主数据重复维护 | 交叉检查:同一事实是否只有一个系统拥有写权 |
## 开放的结构问题
- 体力与生命是否保持为两个状态,还是在轻度战斗中共享一套风险资源?
- NPC 日程、任务条件和节日事件之间采用统一条件格式还是各自维护?
- 农场设施生产是否由农场系统统一管理,还是交给通用制作队列?
- 采集、钓鱼和战斗是否共享统一的"活动结果"接口?
- 哪些系统需要独立数据表,哪些小型配置应合并为一张内容表?
@@ -1,63 +0,0 @@
# 概念设计:《星露谷物语》
## 一句话概念
《星露谷物语》是一款以经营农场为基础、融合探索、采集、制作、轻度战斗、角色成长与社区叙事的乡村生活模拟 RPG;玩家通过安排每日时间与体力,把荒废农场逐步建设成理想家园,并与周围居民建立关系。
## 定调与设计锚点
### 定调记录
- 参照选择:以牧场物语系为主(无压力日常方面学动物森友会);不参考任何高难动作与生存类游戏。
- 调性滑杆:压力感 低 / 战斗比重 低 / 管理深度 中 / 叙事比重 中低 / 节奏 慢。
- 调性锚:
T1 轻松治愈、自己的节奏(目标体验);T2 不劝退、无唯一最优解(体验门槛);T3 战斗轻度、非高难动作(非目标);T4 以"游戏日"为单位、可反复的单人体验(情境);T5 时间体力有限但休闲不打卡(跑偏风险);T6 小团队可维护的规模(关键约束);T7 日常叙事而非宏大主线,隐藏信息不迫使玩家查攻略(非目标/跑偏风险)。
### 设计锚点
- 核心幻想:离开令人疲惫的城市生活,继承一片荒废土地,在自己的节奏中经营、探索、成长,并成为社区的一员。
玩家念头:"再玩一天就好——今天做完想做的事,明天的一切都会更顺手。"
- 目标体验:治愈、自由规划、持续成长、发现秘密,以及"今天的选择会让未来更轻松"的掌控感。
- 玩家动机:改善农场与生活条件;发现新区域和资源;完成社区目标;提升技能;与 NPC 建立关系;按照自己的偏好塑造生活方式。
- 核心循环:安排一天的时间与体力 → 进行农业、采集、钓鱼、采矿、战斗或社交 → 获得资源、金钱、经验与关系进展 → 投资工具、设施、种子和物品 → 解锁更高效或更丰富的活动。
- 跑偏风险:系统过多导致目标分散;时间与体力限制把休闲体验变成每日打卡;隐藏信息迫使玩家依赖外部攻略;经济成长过快使后期失去决策。
- 非目标:不做多人竞争、高难度动作战斗、唯一最优效率经营、主线剧情取代日常(详见《不是什么》)。
## 玩家身份与基调
- 玩家身份:一名辞职逃离城市、继承祖父荒废农场的归乡人——不是拯救世界的英雄,是重新学会生活的人。季节与节日构成一年的节拍,日落结算构成每天的呼吸。
- 情绪基调:温暖治愈,慢而踏实。可以有忙碌与轻度压力(时间、体力),不做生存焦虑(饥饿、债务倒计时)与黑暗题材;孤独感只作为被社区逐渐治愈的起点,不成为基调本身。
## 风格与世界观
复古像素风的温暖乡村世界。玩家来到一个正在现代化与传统生活之间摇摆的小镇,农场、商店、社区设施、自然区域和矿井共同构成可步行抵达的生活网络。世界观服务于生活模拟而非复杂设定解释:季节、天气、节日、居民日程和区域变化,让同一张地图随着时间产生生活感。叙事主要通过 NPC 日常对话、关系事件、任务和社区目标逐步展开。
## 目标玩家与情境
- 目标玩家:与牧场物语系受众高度重合——喜欢种田与小人际的慢节奏成长玩家;同时吸收动物森友会式"无压力日常整理"的需求(自定义、装饰、按自己的节奏玩)。但它不能变成纯装饰沙盒,因为农场经营的时间、体力与季节取舍,以及社区修复目标必须始终存在。
- 适合情境:单人、可反复游玩、每次一个游戏日或几个游戏日;可以高效规划,也可以把时间用于装饰、社交或探索。
- 体验门槛:需要理解基础资源转换和时间安排,不应要求预先掌握复杂数值或寻找唯一正确答案。
## 不是什么
| 不是 | 因为 |
|---|---|
| 硬核生存农场模拟 | 没有饥饿、债务、死亡惩罚;压力止于温和的时间与体力 |
| 效率至上的工厂经营 | 不要求唯一最优解,装饰与闲逛是合法玩法而非浪费 |
| 以战斗为核心的动作游戏 | 战斗只是采矿与探索的伴生风险,深度刻意受限 |
| 剧情驱动的叙事游戏 | 社区叙事是日常的背景与情感回报,不是任务链主线 |
| 多人社交平台 | 单人体验为前提,人际关系由 NPC 关系承载 |
| 无边界开放世界 | 地图是功能明确的小区域网络,全部可步行抵达 |
## 核心张力
- 时间与体力有限,但想做的事情很多:玩家必须决定今天的优先级。
- 立即变现与长期投资:出售资源能快速获得资金,制作设备和升级工具则能提高未来效率。
- 稳定经营与未知探索:农场提供可预测收益,矿井、钓鱼和新区域提供风险与发现。
- 个人效率与社区关系:把时间用于赚钱会挤压社交,但关系又会带来配方、剧情和新的情感目标。
- 自由生活与阶段目标:玩家可以自由安排日常,同时受到季节、节日、任务和社区修复目标的轻度牵引。
## 边界与约束
- 概念层只定义核心幻想、目标用户、体验基调与排除方向;具体战斗公式、作物成长天数、礼物偏好、掉落率、系统清单和 MVP 内容,留给顶层及以后决定。
- 设计规模以单人或小团队可理解、可维护为前提;地图采用多个功能明确的区域,而非无边界开放世界。
- 所有系统都必须回流到"安排一天并获得长期改善"的核心循环;独立小游戏或装饰功能不能成为主要范围扩张来源。
- 案例声明:本文以《星露谷物语》为案例展示设计的组织方式,不复制其具体角色、文本、美术、地图或数值。
## 概念定稿
《星露谷物语》的核心不是"种田赚钱",而是:
> 在自己的节奏里经营一片土地与一段生活——今天的选择让明天更从容,而社区让独居变成归属。
交给下一层的约束:时间与体力必须构成温和而非焦虑的取舍;战斗、采矿、社交等支线必须回流农场生活循环;成长权重要允许玩家自定义(效率型与休闲型玩家都成立)。
(调性已在第 2 节定死;顶层及以下一切开放问题先回定调记录的 T1~T7 级联。)
@@ -1,120 +0,0 @@
# 战斗与敌人系统:S06
## 系统目的
为危险区域提供轻度、可理解的战斗挑战,使玩家在探索中承担风险,并通过装备、补给和技能成长验证长期准备。战斗是生活模拟循环的支柱之一,不是游戏的唯一核心。
## 支撑的玩家体验
- 玩家能观察敌人行为,选择攻击、躲避、补给或撤退。
- 战斗结果主要取决于准备、判断和适度操作,而不是高强度连招。
- 深入危险区域会带来更高资源和成长回报,也会增加生命、时间和补给压力。
- 失败有明确原因和可恢复成本,不应摧毁长期农场进度。
## 进入与退出
### 进入
- 玩家进入允许战斗的危险区域或触发敌人遭遇。
- 检查区域、时间、装备、生命、背包和任务条件。
- 初始化当前战斗区域、敌人组合、战斗状态和可撤退条件。
### 退出
- 击败敌人并完成战斗奖励结算。
- 玩家主动撤退或离开战斗区域。
- 玩家生命归零,由体力与状态系统执行昏倒或失败惩罚。
- 特殊事件、日终或区域状态强制结束战斗。
## 玩家行动
- 移动、观察敌人攻击范围和行为状态。
- 普通攻击、重攻击或使用装备技能。
- 防御、闪避、格挡或利用场景短暂规避伤害。
- 使用食物、药剂等消耗品。
- 拾取战利品、调查宝箱或选择继续深入。
- 在满足条件时撤退,保留已结算的奖励。
通用流程:
`进入遭遇 → 读取敌人状态 → 玩家行动 → 敌人响应 → 结算伤害/效果 → 判断胜负或撤退`
## 取舍表
| 决策 | 立即收益 | 延迟收益 | 主要代价 |
|---|---|---|---|
| 继续深入还是安全撤退 | 更多资源 | 更高风险与返程压力 | 已得战利品可能损失 |
| 消耗品现在用还是留着 | 维持当前探索 | 应对更强敌人 | 局部战况恶化 |
| 快速击败还是稳健闪避 | 节省时间 | 降低受伤风险 | 补给与时间消耗 |
| 高伤高耗装备还是基础攻击 | 更快击杀 | 稳定与低消耗 | 资源消耗大 |
| 资金投武器防具还是农场设施 | 战斗能力 | 农场产能 | 另一侧进度放缓 |
## 状态与规则
### 玩家战斗状态
- 当前生命、最大生命和状态效果。
- 装备中的武器、防具、饰品和消耗品。
- 攻击、防御、移动、闪避和技能冷却状态。
- 当前战斗区域、遭遇编号和撤退状态。
### 敌人状态
敌人状态至少包括待机、警觉、攻击前摇、攻击中、受击、眩晕、死亡和撤退。
每个敌人的实例数据(生命、位置、目标、状态效果、掉落引用)的字段定义由技术文档层承接。
### 战斗规则
- 只有满足攻击距离、方向、冷却和装备条件时,攻击才可结算。
- 伤害由攻击来源属性、目标防御、技能倍率和状态效果共同决定。
- 敌人攻击必须有可识别的前摇或预警,给予玩家反应与撤退机会。
- 生命降至零时进入死亡或昏倒状态;具体惩罚由体力与状态系统处理。
- 敌人死亡后只结算一次经验与战利品,并写入遭遇状态,避免重复领取。
- 撤退后已完成的战斗奖励保留,未击败敌人按区域刷新规则处理。
### 区域遭遇
- 危险区域由敌人组、刷新规则、深度或阶段配置组成。
- 进入更深区域可以提高敌人强度、资源价值和特殊遭遇概率。
- 区域难度应通过可理解的装备、区域和任务条件表达,不依赖突然的数值墙。
- 宝箱、精英敌人和首领可作为独立遭遇类型,但不在最小版本中同时扩张。
## 数值与数据交接(→技术文档层)
本系统交由技术文档层(数值策划)定义的数据类别:敌人配置、敌人行为配置、武器配置、技能配置、遭遇配置、战利品配置、状态效果配置。
随交接附下的设计侧定性约束:
- 敌人数据拆分为"是什么 / 怎么行动 / 掉什么"三类,使难度与经济可独立调节。
- 普通敌人不应稳定掉落大量高价值物品;战斗收益主要由矿物、经验和区域发现组成。
- 稀有材料是"有明确用途的探索奖励",但必须保留任务、宝箱等补充渠道,避免战斗失败后无法推进。
- 基础战斗允许玩家一日内完成少量遭遇并安全返程,不要求连续刷怪。
- 失败保留已结算的普通战利品,主要损失是时间、位置或少量金钱,不清空背包。
- 自动化收益节省日常体力,但不能让玩家跳过农场维护的全部决策。
- 收益回流方向:区域 → 敌人 → 材料 → 加工 → 农场自动化;战斗不直接取代农场收入。
## 反馈
- 攻击命中、受击、闪避、格挡和暴击提供清晰的视觉与声音反馈。
- 敌人显示生命、预警、当前状态和可攻击时机。
- 玩家生命、补给、冷却和撤退可用性持续可见。
- 战斗胜利显示经验、战利品和区域进度。
- 失败说明主要原因,并明确损失、保留内容和可恢复路径。
## 内部循环
### 单次战斗循环
`观察敌人 → 选择攻击或防御 → 处理敌人响应 → 造成或承受伤害 → 调整策略 → 击败或撤退`
### 危险区域循环
`准备装备与补给 → 进入区域 → 战斗与搜刮 → 判断继续深入或返程 → 带回资源 → 升级能力`
### 长期循环
`获得战斗经验与装备 → 提升生存能力 → 挑战更深区域 → 获得稀有资源 → 解锁新制作、任务或地图`
## 输入、输出与依赖
### 输入
- 探索与地图系统提供战斗区域、位置和遭遇入口。
- 时间系统提供当前时间、季节和日终信号。
- 体力与状态系统提供生命、体力、状态效果和失败处理。
- 物品系统提供武器、防具、消耗品和战利品接收入口。
- 成长系统提供属性、技能和装备解锁。
- 玩家通过核心玩法系统提交战斗行动。
### 输出
- 向物品系统提交战利品和消耗品变化。
- 向成长系统提交战斗经验和能力进度。
- 向地图系统提交敌人、宝箱和遭遇状态。
- 向任务与社区系统提交击败、调查和区域进度。
- 向 UI 输出战斗状态、反馈、胜负和撤退结果。
## 边界与非目标
- 不负责通用生命与昏倒惩罚,只提交状态变化。
- 不负责武器物品的背包、耐久和售价主数据。
- 不负责字段定义、数值配置与表格结构——归技术文档层(数值策划)。
- 不做高难度动作连招、复杂多人战斗或精确帧竞速。
- 不让战斗成为获得普通农场资源的唯一方式。
- 不在本系统中定义全部敌人、武器和首领内容。
## 开放问题
- 战斗采用实时操作,还是更简化的节奏/指令判定?
- 体力是否影响攻击与闪避,还是只影响探索和农务?
- 武器是否有耐久度,还是通过升级与装备更换形成消耗?
- 战斗失败的主要成本采用金钱、位置、时间,还是有限组合?
@@ -1,82 +0,0 @@
# 美术圣经:《星露谷物语》(TDD 金样 · 美术圣经)
> 状态:reviewed | 定调锚:概念层@v1 第 2 节(定调记录:牧场物语系参照、压力低/节奏慢/治愈) | style_id`stardew_warm_rural_pixel`
> 实证规格来源:星露谷 1.6.15 解包知识库 v3(资产计数时点 2026-09-11,快照 stardew-1.6.15-7f1e5b8e)。写新项目时按本项目定调重译,数字仅作规模参照。
## 视觉风格总览
从定调记录翻译的视觉气质:**"被四季照亮的温暖小农场"**——手绘感像素、俯视 45° 视角,春夏绿意、秋日暖橙、冬季留白,颜色随季节整体切换而不是换贴图;物件轮廓圆润、无锐利科技感。玩家一看画面就该感到:这里节奏很慢,干活是安心的。参考图位 4 张(量产流程第 3 步产出锚点图)。
## 视觉锚
- 关键词:温暖、手绘像素、田园、四季分明、生活感。
- 禁用关键词:阴暗压抑、血腥恐怖、高饱和霓虹、写实渲染、锐利科技风(承概念层 T3"战斗轻度"、T7"日常叙事")。
- 色板:主色 暖土绿系(草地/耕地基底)60% / 辅色 暖木棕+瓦顶红 30% / 点缀 季节信号色(春樱粉/夏浓绿/秋橙/冬蓝白)10%。昼夜·天气·季节表现:季节=色调与植被整体切换;天气=雨天全屏冷色叠加(原作 OrangeRed×0.45 实证);昼夜=时刻线性插值环境光。
- 形状语言:圆润矩形轮廓,物件以 16px 网格对齐;无 1px 高光乱线。
- 比例与轮廓:物件 16px 一档;NPC 16×32(渲染放大 4 倍);玩家可完全自定义外观。
- 光照与材质:不做真实光照——低分辨率 lightmap 乘法混合;优先级链=矿井 tint>室内 ambient>室外 outdoor(时刻插值);十种光源贴图常量够用。
- 渲染口径:纯像素、无抗锯齿、整数倍缩放(程序侧能力边界同源)。
## 角色模板
- 基础规则:玩家=换装组合而非整图——19 个独立层(基础体/裤/衣/发型/饰件/配件…),每层独立图集,调色板像素 256-277 区域换色实现同图集多变色;层深=基准+层序×1e-6 保证叠加次序稳定。NPC=16×32 四方向小人+64×64 立绘(对话用)。
- 方向数:4 方向(左=右镜像:是——行走图按方向分行布局,如 64×448=4 列×14 行)。
- 动画状态:待机/走 walk=4 帧循环、每帧 200ms(帧表含毫秒级帧时长);受击/使用工具按动作逐条登记帧表。玩家帧表量大(原作 500+ 动画参数为 switch 硬编码),本项目帧表走数据表不走硬编码。
- 立绘表情:六表情索引 0-5$neutral/$happy/$sad/$unique/$love/$angry),对话文本中 `$表情` 标记驱动切换。
## 场景模板
- tileset 规格:16px tileTileSheets 级图集约 41 张+地形特征图集 38 张(作物/树);padding 1px 防渗色。
- 图层拆分:四层 Back/Buildings/Front/AlwaysFront(深度 -1/0.1/64+/-1)——地面/建筑/前景遮挡/最前;碰撞由 Buildings 层属性驱动;矿井布局池按模板拼装(原作 61 张模板,本项目首期 8~12 张)。
- 场景对象规则:多帧素材禁当静态贴图(作物生长/角色必须走帧表);单元素禁整图(区域由 tile 拼装,禁为每区域画整张立绘);地图数参照:原作 259 tmx+304 预览,本项目首期 3 区域(农场/小镇/矿井)。
## UI 视觉
承 UI 系统文档界面清单(HUD/背包/商店/对话/日终结算五界面)。视觉语言:木质面板底+纸张质感对话框;信息分层——价格信息永远暖金、锁定/禁用永远灰蓝、日终收入单列。字体用位图字体(原作 5 fnt 位图字体实证)。触控版式热区 ≥44px 与程序侧输入表同源。特效走程序动画(按帧表播图集区域)+粒子,不逐特效画整图(原作 LooseSprites 156 张 UI/杂项图集规模参照;最大图集实测 1920×1376)。
## 素材规格契约
| 素材 | 规格(尺寸/帧数/方向数) | 命名规则 | atlas 格式 | 验收 | 绑定 |
|---|---|---|---|---|---|
| 物品图标 | 16×161 帧 | `icon_{item_id}` | JSON atlas | 技术+视觉 | `item_*` 全量(参照原作 807;本项目首期 ~120 行) |
| 作物 | 16×32×相位帧(4~5 相位,每相位 1~2 帧) | `crop_{crop_id}` | JSON atlas | 技术+视觉 | `crop_*`(参照原作 50 |
| 玩家换装层 | 每层独立图集,walk 4 帧×4 方向 | `farmer_{layer}_{state}_{dir}` | JSON atlas | 技术+视觉 | 豁免(角色非物品,登记于本表) |
| NPC 行走+立绘 | 行走 16×32 四方向行布局;立绘 64×64×6 表情 | `npc_{id}_walk` / `npc_{id}_portrait_{expr}` | JSON atlas | 技术+视觉 | `npc_*`(参照原作 34 社交 NPC/101 立绘;本项目首期 8 位) |
| tileset | 16px,边缘连接变体 | `tile_{theme}_{variant}` | JSON atlas | 技术+视觉 | 豁免(场景组件) |
| UI 面板 | 9 宫格切片,3 态 | `ui_{element}_{state}` | JSON atlas | 技术+视觉 | 豁免(UI |
| BGM | ogg-18LUFS,循环点标记 | `bgm_{season}` 4 首+矿井 1 首 | — | 响度+循环 | 豁免(音频契约) |
| SFX | wav 单发 | `sfx_{event}`(事件↔音效映射表登记) | — | 同帧触发 | 豁免(音频契约) |
- 绘制工艺:陶泥儿 MCP 像素绘制路径逐类写参数(作物/图标/角色三类的封装流程);施工环境无产出通道时规格先行锁定、状态如实登记"缺失"。
- 音频契约说明:原作 XACT cue 名 435 候选/代码引用 230 个——本项目首期 SFX 事件 20 只起步,按事件总线 `sfx_event` 映射表登记,不逐 cue 复刻。
- 豁免类型仅限:程序化生成(矿井布局由表驱动拼装)/ UI 文本 / 本期不需要——每项豁免在契约行写明。
## 资产状态表(asset manifest
| asset_id | 规格 | 绑定 | 状态 | 验收记录 | contract_version |
|---|---|---|---|---|---|
| icon_item_*(首期 ~120 行,逐 item_id 一行) | 16×16 | `item_*` | 缺失 | — | 1 |
| crop_*50 行) | 16×32 相位帧 | `crop_*` | 缺失 | — | 1 |
| farmer_*19 层图集) | 4 帧×4 方向 | 豁免 | 缺失 | — | 1 |
| npc_*_walk / _portrait8 位×7 件) | 16×32 / 64×64×6 | `npc_*` | 缺失 | — | 1 |
| tile_*3 主题变体组) | 16px 变体 | 豁免 | 缺失 | — | 1 |
| ui_*(5 界面套件) | 9 宫格 3 态 | 豁免 | 缺失 | — | 1 |
| bgm_*5 首) | ogg -18LUFS | 豁免 | 缺失 | — | 1 |
| sfx_*20 只) | wav | 豁免 | 缺失 | — | 1 |
- 状态单向流转:缺失 → 草稿 → 已交付 → 已验收 → 已接入;驳回退回草稿并记原因。
- 验收两维:技术(尺寸/透明/帧数/命名)+ 视觉(对照视觉锚);两维都过才进"已验收"。
- **每个 gameplay 可见对象必有一行或显式豁免——没有第三种状态**:物品图标逐 item_id 与数据侧物品表逐行对账(参照规模:原作 Characters 215 png/Portraits 101/TileSheets 41/TerrainFeatures 38/LooseSprites 156)。
- 程序接入后填消费点(哪个模块加载、事件映射),`contract_version` 变更须重验收。
## 量产流程与验证
1. 概念候选 4 张(农场一角/角色/物品图标/UI 面板各 1 方向稿)→ 2. 人选方向(用户确认)→ 3. 锚点图 4 张 → 4. 锁圣经 → 5. 写契约(本文件已锁)→ 6. 小批 8 张(icon_item 子集:防风草种子/防风草/木材/石头/铜矿/锄头/水壶/出货箱)→ 7. 技术检查(尺寸/透明/命名/atlas 解析)→ 8. 接入程序(v0.1 里程碑)→ 9. 运行时截图验收(桌面/移动双视口下 16×16 图标与作物相位可辨、四季色调正确)→ 10. 扩产(8→120→全量)。
## 开放问题回执
| # | 问题 | 去向 |
|---|---|---|
| 1 | 换装系统首期是否做全 19 层(或缩到 5 层) | → 台账代决(建议首期 5 层:基础体/裤/衣/发型/饰件;台账 D-17) |
| 2 | 锚点图方向需用户确认 | → 施工期提案卡 |
| 3 | 位图字体 vs 矢量像素风字体 | → 小批阶段随 UI 套件定 |
@@ -1,98 +0,0 @@
# 数据与配表:《星露谷物语》(TDD 金样 · 数据与配表)
> 状态:accepted(结构定稿+首期全量填充验算通过) | 基于:各系统文档交接节汇总 + 归 TDD 素材两份提取件(S06 数值结构/架构字段字典) | 验收:check@C-2026-09-11-v1 结论 无 blocker
> 实证计数来源:星露谷 1.6.15 解包知识库 v3(13 张数据表,提取脚本断言通过;快照 stardew-1.6.15-7f1e5b8e)。写新项目时按本项目系统交接节重建,计数仅作规模参照。
## 数据表总清单
| 表格组 | 建议表名 | 主要维护系统 | 实证规模(原作 1.6.15) |
|---|---|---|---|
| 物品与经济 | 物品表、品质表、商店表、商店库存表、价格表 | 物品与制作、经济与商店 | 物品 807×29 类;商店 77 店 897 条库存(含店级 PriceModifiers |
| 农场内容 | 作物表、动物表、设施表、加工配方表 | 农场经营 | 作物 50 全字段;机器 39 台全 OutputRules |
| 活动内容 | 采集点表、钓鱼点表、鱼类表、敌人表、敌人行为表、遭遇表、战利品表 | 采集/钓鱼/战斗 | 怪物 51 条配置;怪物 AI 矩阵 30 类移动原型 |
| 物品制作 | 通用配方表、配方解锁表 | 物品与制作 | 配方 231(烹饪 81+工艺 150,全原料/产出/解锁) |
| 玩家成长 | 技能表、等级经验表、能力节点表、工具升级表、效果表 | 成长与技能 | 职业 30 全效果钩子(51 钩子+6 数据驱动);附魔 34 逐项数值;经验曲线代码常量 |
| NPC 与任务 | NPC 表、关系等级表、礼物偏好表、任务表、奖励表、事件条件表 | NPC/任务/事件 | NPC 送礼 34NPC×4 档+全局 5 档;事件 258/条件码 39 |
| 时间与世界 | 日期季节表、天气表、节日表、营业时段表 | 时间与日程、事件与节日 | —(代码常量+日程数据驱动) |
| 文本与展示 | 文本表、UI 提示表 | UI 与文本呈现及各内容系统 | 11 语言按后缀拆分(含 zh-CN) |
(表格拆分是生产组织方式,不改变主数据归属。原作同套模型同时服务本体与模组生态——静态表为结构化 JSON-in-XNB,由 DataLoader 按需缓存。)
## 字段字典与 ID 命名规范
- ID 命名:小写 snake_case`对象类型_名称_必要时加阶段`(如 `item_turnip`);全局唯一、废弃不复用。(原作实证:1.6 起用限定 ID 如 `(O)123` 统一引用 807 物品——原理同源:ID 不含人话、不随语言变。)
- 通用字段:`*_id` / `display_name_text_id` / `description_text_id` / `condition_id` / `enabled_state`active·draft·disabled·deprecated/ `sort_order` / `designer_note` / `unit`(数值字段必填:time_slice·game_day·currency·stamina·exp)。
- 常用后缀:`_amount`(配单位)/ `_cost` / `_rule_id` / `_condition` / `_time` / `_duration` / `_state` / `_text_id`
- 类型与空值:数值栏禁"约/无/待定";空值=不适用≠0≠无限(无限制库存用 `stock_type=unlimited`,不用 999999);布尔 true/false;多值一律关系子表(多材料配方禁拼一格)。
- 引用完整性:`item_id`→物品表;`location_id`→区域表;`npc_id`→NPC表;`quest_id`→任务表;`recipe_id`→配方表;`condition_id`→条件表;`text_id`→文本表。删除先置 `deprecated` 并查引用。
- 枚举实证注意:品质枚举值为 0/1/2/4(银=1、金=2、铱=4)——所有 `(1+0.25×quality)` 型公式乘数因此是 1.25/1.5/2.0;枚举值是语义约定,禁止想当然重排。
## 公共条件表
| condition_id | condition_type | target_id | operator | required_value | enabled_state | 备注 |
|---|---|---|---|---|---|---|
| `condition_day_2` | `date_day` | `season_spring` | `>=` | 2 | `active` | 春季第 2 日后可触发 |
| `condition_shop_unlocked` | `progress_flag` | `flag_general_store_open` | `==` | 1 | `active` | 杂货店已开放 |
| `condition_skill_farming_1` | `skill_level` | `skill_farming` | `>=` | 1 | `active` | 农务技能达到 1 级 |
| `condition_blacksmith_open` | `schedule_open` | `schedule_blacksmith_default` | `==` | 1 | `active` | 铁匠铺当前处于营业时段 |
| `condition_recipe_repair_path` | `quest_completed` | `quest_repair_path` | `==` | 1 | `active` | 修路任务完成后解锁基础洒水器配方 |
(复杂条件拆条件组+条件行;全项目只此一个条件入口,程序实现一次 `check(condition_id)`。实证参照:原作 258 事件共用 39 个条件码——条件收敛是可达到的规模。)
## 工作簿组织与建表顺序
| 工作簿 | 工作表 |
|---|---|
| `世界与地图.xlsx` | 日期季节、天气、日程、区域、区域连接、活动入口 |
| `农场与制作.xlsx` | 地块、作物、动物、设施、加工配方、通用配方 |
| `物品与经济.xlsx` | 物品、品质、装备、价格、商店、商店库存、货币 |
| `活动与战斗.xlsx` | 采集点、掉落、钓鱼点、鱼类、敌人、行为、遭遇 |
| `成长与任务.xlsx` | 技能、等级经验、能力节点、工具升级、NPC、关系、任务、目标、奖励 |
| `事件与文本.xlsx` | 节日事件、事件阶段、事件条件、文本、UI 提示、教程 |
建表顺序:①物品表(公共 item_id)→ ②作物表 → ③区域与连接表 → ④NPC 表 → ⑤配方表 → ⑥价格与商店库存表 → ⑦任务/目标/奖励表 → ⑧敌人/掉落/技能/事件表。
每完成一组查三件事:引用 ID 存在 / 条件有负责系统 / 同一数值只有一个系统维护。
## 表格-程序契约
1. 加载顺序按引用拓扑:主数据 → 关系 → 条件 → 文本(最后)。
2. 启动期全量校验(外键/枚举/单位);运行期全部 id→对象字典 O(1) 查找。(实证参照:原作按需缓存加载+`ContentHashes.json` 逐文件 MD5 校验拒损坏。)
3. 条件求值统一 `check(condition_id)`,全部系统复用。
4. enabled_state 生命周期:active 加载;draft 调试可见;disabled 不加载;deprecated 不加载但留 ID 占位。
5. 单位类型化(time_slice/game_day/currency/stamina/exp 进类型系统,同列禁混单位)。实证锚点:`700ms=10 游戏分钟`为运行时常量,配表侧时间单位统一 time_slice,禁现实秒混入。
6. 多值一律关系子表;运行期无"解析逗号拼接"代码路径。
7. 改表 → 验收过检(blocker=CI 红灯)→ 进包;`data_version` 为迁移依据(实证参照:原作存档迁移器按版本处理旧字段)。
8. 随机契约:影响掉落/品质的 roll 绑定「世界日+存档 ID+位置/主体」种子(防读档刷结果;原作行为级种子实证:收获 `CreateRandom(x×7, y×11, DaysPlayed, uniqueID)`)。
## 数值填充与验算
- 填充代决台账:
| 表 | 字段 | 默认值 | 依据 | 推翻条件 |
|---|---|---|---|---|
| 等级经验表 | skill_cumulative_xp | 100/380/770/1300/2150/3300/4800/6900/10000/15000 | 代码常量(Farmer.cs 实证) | 原型期曲线过陡/过缓 |
| 作物表 | 防风草 price/days/xp | 35 金/4 日/8 xp | 原作作物表实证(crop 472phases 1-1-1-1xp_per_harvest 8 | 前 5 日验算不闭合 |
| 经济表 | 买卖价差 | 商店价=2×基价×品质系数;出售所得=其半 | 原作一对出售方法实证 | 新手期现金流断裂 |
| 战斗表 | 受击无敌帧 | 450ms(按武器类型 2/3 除) | 原作 takeDamage 实证 | 手感测试受击连按 |
- 前五日闭环验算(防风草路线,起始 500 金实证口径):
| 日期 | 主目标 | 关键行动 | 主要成本 | 主要获得 | 结果 |
|---|---|---|---|---|---|
| 第 1 日 | 建立基础生产 | 购防风草种子×15(20 金/包)、开垦播种浇灌、采集少量木材 | 300 金;约 30 体力;约 8 时间片 | 15 块已播种地;少量木材;农务经验 | 进入等待成长阶段 |
| 第 2 日 | 接社区引导 | 浇灌、采集木材、与工匠对话推进修路任务 | 约 25 体力;约 8 时间片 | 任务材料进度;少量经验 | 任务明确指向自然区域 |
| 第 3 日 | 补足任务材料 | 浇灌、采集木材与铜矿、返回小镇 | 约 35 体力;约 12 时间片 | 木材 20、铜矿 5(或进度);采集/战斗经验 | 可提交修路任务 |
| 第 4 日 | 收获+解锁 | 收 15 防风草(35 金×15=525 金、8 xp×15=120 xp→农务 1 级)、提交任务领奖 | 任务材料;约 10 时间片 | 525 金;基础洒水器配方;林间区域开放 | 现金流回正+新活动选择 |
| 第 5 日 | 验证扩展循环 | 浇灌、赴林间采集或钓鱼、出售部分产物 | 约 30~45 体力;约 14 时间片 | 新资源、活动经验、可售物品 | 循环从单一农务扩展为农场+探索 |
- 收益链校验:`item_seed_parsnip(20金) → crop_parsnip(4 日) → item_parsnip(35 金) → 出货箱日终结算 → 种子复购(单包毛利 15 金)`(逐环引 ID,全链存在)。
- 验算结论:第 1 日不要求做完,播种即进展;第 4 日奖励同时给资金/配方/区域三样;第 5 日出现农场与探索取舍但两条路线都可行。
## 验收
- 验收记录:check_id / workbook / sheet / data_version / check_typeprimary_key·reference·enum·unit·range·business_rule·duplicate_ownership/ severityblocker·warning·note/ result / issue / owner / resolution。
- 五查必过:主键唯一不空;外键存在且目标非弃用;枚举有清单(品质枚举 0/1/2/4 单独登记);单位可判且同列不混;无违规负数、`duration=0` 仅即时。
- 两查复核:业务规则(季节窗口相容、目标有验证系统、奖励一次、配方输入可达——防风草种子→收获→出售链全通);重复归属(价格只由经济表维护、品质只由收获规则维护)。
- 三级处置:blocker 禁止扩内容;warning 记负责人与计划;note 不阻断。
- 工具化实证口径(参照知识库做法):提取脚本逐表断言(行数/字段/枚举);对账器做表间交叉对账(代表资产级 50 键全对账);反例套件 5/5 拒绝。
- 最近验收结论:check@C-2026-09-11-v1——五查全过、两查复核通过、blocker 清零(结构、规则或字段语义一变,受影响链路全部重验)。
@@ -1,59 +0,0 @@
# TDD 总册:《星露谷物语》
> 状态:activev0.1 里程碑期) | 基于 GDD:架构层@v3 + 各系统交接节
## 自足性检查(2026-09-06 生产态复评)
| # | 施工 agent 的问题 | 答案在哪 | 状态 |
|---|---|---|---|
| 1 | 七个 P0 系统怎么行为? | 01 收编章(P0 七系统规则全文已收编@v1S06 P1 要点已收) | **过** |
| 2 | 表里有多少行内容、文本全填了吗? | 03 全量填充(作物8/敌人3/NPC12/文本40/物品46/配方14 全填,第八查全绿) | **过** |
| 3 | 每个界面长什么样、怎么走? | 01 UI 交互规格(HUD/背包/商店/对话/结算五界面全) | **过** |
| 4 | 每份素材什么规格、谁验收过? | 02 资产状态表 42 行全登记(完成度 12/42,缺口=量产排期非规格缺口) | **过(规格)**/量产进行中 |
| 5 | 代码怎么组织、跑在哪? | 01 代码组织+能力边界(三态全落位) | **过** |
| 6 | 怎么算做完? | 01 里程碑三判据+三件验收 | **过** |
**结论:六问全过——TDD 规格已自足,施工 agent 可只凭本 TDD 开工。**
剩余非规格缺口(不阻塞开工,按里程碑推进):①P1 四系统(S05/S10/S11/S12)施工前补文档并收编;②资产表 30 行量产(按十步流程排期);③B 级两项(背包容量、生命体力共享)在 v0.1 存档实现前收口。
## 三件状态
| 件 | 状态 | 版本 | 读者 | 一句话结论 |
|---|---|---|---|---|
| 01 技术实现 | reviewed | v0.2 | 程序 | P0 铁底七件全部落位(native 4/emulated 3),无 gatedv0.1 判据=一个游戏日全流程 |
| 02 美术圣经 | locked(锚点已锁) | v1 | 美术 | 视觉锚七件套从 T1~T7 翻译完毕;资产表 ~40 行全登记,农夫已接入、芜菁已验收 |
| 03 数据与配表 | accepted | ck-001 | 数值+程序 | 七查过、无 blocker、2 warning(公共索引表未建、背包容量未定案);前五日验算通过 |
## 跨件契约速查
| 缝 | 契约 | 权威在 |
|---|---|---|
| 素材绑定 | 作物绑 `crop_{id}`、工具绑 `item_`、敌人绑 `enemy_{id}`、NPC 绑 `npc_{id}`(ID 全部查 03 字段字典指向的表) | 03 字段字典 |
| 视觉翻译链 | `cozy-pixel-countryside` 溯源概念层 T1/T4/T7;四季色板=日单位与季节推动的视觉形态 | 概念层@v3 第 2 节 |
| 加载顺序 | 主数据(物品/敌人)→ 关系(掉落/配方)→ 条件(condition 表)→ 文本(text 表最后) | 03 契约七条① |
| 帧表格式 | `farmer_{anim}_{dir}_{frame}` JSON 帧表:圣经契约列的格式=程序侧帧动画节直接解析的格式 | 01 §能力边界 |
| 交互热区 | 触控热区 ≥44px;圣经 UI 节与 01 输入表同源(热区按钮规格一字不差) | 01 输入表 |
| 音频规格 | BGM ogg 循环+循环点标记 -18LUFS、SFX wav 单发——圣经契约与 01 音频表触发实现一致 | 02 音频契约 |
| 昼夜色调 | `tint_{phase}` 四档程序色值表,豁免绑定、拥有者=美术圣经资产表 | 02 资产状态表 |
| 拥有者总则 | 数值事实归 03(价格只在经济表);生产状态归 02(素材验收记录);技术事实归 01(缩放档位) | 架构层@v3 |
## 开放问题回执汇总
| # | 来源件 | 问题 | 去向 | 状态 |
|---|---|---|---|---|
| 1 | **01** | 背包格子还是重量容量(阻断:影响存档与 UI) | 概念层决策卡 | **待用户(B 级置顶)** |
| 2 | 02 | NPC 对话立绘 +12 张(影响 UI 结构与工时) | 决策卡 | 待用户(B 级) |
| 3 | 01 | 矿井逐层生成是否本期 | 台账代决(建议 P2) | 待登记 |
| 4 | 02 | 节日专属装饰 P1/P2 | 台账代决(建议 P2) | 待登记 |
| 5 | 02 | 矿井色板 1 套 vs 3 套 | 台账代决(建议 1 套+亮度递减) | 待登记 |
| 6 | 03 | condition/text/station/behavior 公共索引表 | 03 warning(记负责人) | 进行中 |
## 验收总状态
| 件 | 最近验收 | blocker | 结论 |
|---|---|---|---|
| 01 | 构建通过+静态检查全绿;双视口验证待 v0.1 联调 | 0 | 结构合格 |
| 02 | ck-a01~a03:农夫接入✓、芜菁两维过(1 warning)、春瓦技术过视觉待锚点 | 0 | 小批已过闸,允许扩产 |
| 03 | ck-001 七查全跑 | 02 warning | 允许内容扩充 |
当前无任何 blocker:填数(03)、扩产(02)、v0.1 联调(01)三线并行合法。B 级第 1 条(背包容量)在 v0.1 存档实现前必须收口,否则冻结存档模块。
@@ -1,172 +0,0 @@
# 技术实现:《星露谷物语》(TDD 金样 · 技术实现)
> 状态:reviewed | 基于 GDD:架构层@v3 + P0 系统文档@v1(收编) | 数据侧契约:data/contracts@v2
> **目标运行时:HTML**(GDD 平台事实锁定;本项目选 HTML 演示自包含 Web 路线。Unity/Godot/Cocos 项目结构相同:能力边界按下表换判定列,预览改陶泥儿驱动引擎弹窗,导出改驱动引擎 CLI)
> 平台事实:双视口(桌面/移动)· 键鼠/触屏双输入 · 本地 HTTP 预览
> 实证数字来源:星露谷 1.6.15 反编译知识库 v3(快照 stardew-1.6.15-7f1e5b8e2026-09-11);写新项目时替换为本项目数值。
## 系统行为规格(收编章——施工只读这里,不回 GDD)
### S01 时间与日程(基于系统文档@v1 收编)
- 玩家行动:查看时间天气(HUD 常驻);使用床提前结束一天;等待营业时段。
- 状态与规则:时间以时间片计、现实驱动、暂停时停表;时间片耗尽或就寝→日终结算(顺序固定:作物生长 tick→设施产出→出货箱结算→NPC 日程推进→存档→日记界面)→日期+1;28 日/季、四季/年;天气每日按季节权重抽取(晴/雨/风暴),雨天免浇水;结算后向 S03/S07/S10 发跨天 tick。
- 反馈需求:HUD 时钟日期常驻;天气图标;日终面板逐项列当日变化。
- 实证参照(原作 1.6.15):`700ms = 10 游戏分钟`(累加器超 `7000 + 地点Extra×10`ms 触发十分钟拍,`timeOfDay += 10`,上限 2600);日结算顺序不可乱——出货先于邮件/任务(订单计数依赖)、地点 dayUpdate 先于玩家 dayupdate(作物推进后才有当日收获判定)。
### S02 体力与状态(基于系统文档@v1 收编)
- 玩家行动:进食恢复体力;食物附带状态效果;观察体力条决定收手。
- 状态与规则:单池体力(战斗共享风险资源——B 级待拍,暂按共享实现);成本分档:移动/普通农务≈0~低、耕作浇水低、砍伐采矿战斗钓鱼中高;恢复:食物立即+效果、就寝次日满、温泉持续;体力归零→昏倒:当日终止、次日上限下降、轻度金钱/物品损失(不清背包);状态效果有限枚举,由食物/装备写入、各系统结算。
- 反馈需求:体力条常驻+临界变色;昏倒过场说明原因与损失、给出可恢复路径。
- 实证参照:原作基础 MaxStamina=270、MaxHealth=100;午夜后体力惩罚为线性公式(Farmer.dayupdate);昏睡账单上限默认 1000g、姜岛 2500gLocationContexts 数据驱动,非硬编码)。
### S03 农场经营(基于系统文档@v1 收编)
- 玩家行动:锄地/播种/浇水/收获/铲除;喂动物收集畜产;放置使用设施;整理布局。
- 状态与规则:地块状态机 荒地→耕地→(播种+浇水)→生长 N 日→可收获→收获后回耕地;未浇水当日不生长;生长按日终 tick;雨天视为已浇水;作物有适宜季节、换季枯萎;动物每日喂食→周期产出、未喂不产出不死亡;洒水器每晨自动浇固定格;加工设备按配方+时间片队列产出;品质分普通/银/金(技能等级+概率)。
- 反馈需求:生长阶段视觉可辨;成熟提示标记;设施完成音效图标;日终列农场产出。
- 实证参照:耕地是网格状态拥有者,作物挂在耕地下(HoeDirt 拥有湿度/肥料/作物引用);收获单一入口;**品质 roll 先于数量 roll 且共用同一随机流**(顺序影响结果);保水判定在作物推进之后(当天浇的水当天有效)。
### S04 探索与地图(基于系统文档@v1 收编)
- 玩家行动:移动(8 向网格);穿出入口切换区域;查看地图;交互资源点入口(采集/钓鱼/战斗分别交 S05/S06)。
- 状态与规则:区域=独立场景、连接点切换淡入淡出≤1s;初始开放农场+小镇+海滩,林间/矿井由社区任务解锁(条件表);资源点固定刷新点按规则周期重生;隐藏信息保留为探索发现;矿井按层进入、固定池随机拼装+亮度递减。
- 反馈需求:地图标注已解锁区域与当前位置;解锁新区域明确提示与入口指引;资源点可交互高亮。
- 实证参照:原作矿井同日同层布局确定(每日世界种子 `DaysPlayed + 存档ID/2`);矿井布局池 61 张模板按层拼装;骷髅洞时间减速 28.6%(+200ms/分)仅单机生效。
### S07 物品、背包与制作(基于系统文档@v1 收编)
- 玩家行动:整理背包;使用/装备/丢弃;设施处提交配方;查看图鉴。
- 状态与规则:一切以 item_id 为准,类别枚举(工具/种子/素材/食物/装备/家具/礼物);同类同品质堆叠(容量结构待 B 级决策,暂按格子制实现、预留字段);工具等级制(基础→铜→铁…,升级交材料+金+天数);装备槽武器/防具各一;配方=材料子表→输出→设施→condition_id 解锁;制作队列按时间片推进、日终照常完成。
- 反馈需求:拾取飘字音效同帧;背包变更即时刷新;制作完成提示;图鉴进度。
- 实证参照:原作 807 物品统一限定 ID 引用(如 `(O)123`);品质枚举值为 0/1/2/4(银=1、金=2、铱=4),所有 `(1 + 0.25×quality)` 型公式的乘数因此是 1.25/1.5/2.0;出售语义一对方法承载:`salePrice()`=2×基价×品质系数,商店价)与 `sellToStorePrice()`=salePrice/2,玩家所得)。
### S08 成长与技能(基于系统文档@v1 收编)
- 玩家行动:查看技能面板;升级时选加成方向;提交工具升级委托。
- 状态与规则:技能五项(农务/采集/采矿/钓鱼/战斗)独立经验池;执行对应活动得经验、只增不减;等级效果三类——效率(省时省体力)/解锁(配方/区域/工具位)/选择(每若干级一次分支,宽松可回转);工具升级期间该工具不可用(备用旧工具=开放问题暂不备);升级奖励优先省时省力扩选择,不加数值伤害。
- 反馈需求:经验条与升级音效;升级面板三选一;工具完成由铁匠通知。
- 实证参照:原作技能累计经验曲线为代码常量 `100/380/770/1300/2150/3300/4800/6900/10000/15000`(10 级);经验取整用银行家舍入(边界值注意);满级后经验转全局精通点(第二成长曲线)。
### S09 经济与商店(基于系统文档@v1 收编)
- 玩家行动:出售(出货箱日终/商店现卖);购买;查看价格库存;接装箱订单(P1)。
- 状态与规则:货币唯一;基准价+买卖价差,价格只由本系统维护(其他系统只提交产物或消费请求);商店各有营业时段(条件表)、库存按周期补货、部分商品有购买条件;出货箱投入→日终统一结算计入当日收入;订单 P1 最低配=每周装箱单换奖金。
- 反馈需求:交易金额飘字音效;日终面板单列收入明细;商店营业状态门口可见。
- 实证参照:原作 77 店 897 条库存,店级 PriceModifiers 数据驱动;基础材料(木/石/煤/铜/铁/金)售价走年度特例(第 2 年起涨价)而非通用公式。
### S06 战斗与敌人(P1,基于系统文档@v1 收编要点)
进入危险区域遭遇→敌人状态机(待机/警觉/前摇/攻击/受击/眩晕/死亡)→攻击需满足距离方向冷却装备条件→伤害=来源属性+目标防御+倍率+状态→敌前摇必须可识别→死亡只结算一次经验战利品→战利品按 item_id 提交 S07 入账→撤退保留已结算奖励。全规则见系统文档@v1P1 施工时全文收编)。
实证参照:怪物 51 条配置拆 15 字段(HP/伤害/掉落对/防御/闪避/速度/经验…);受击 `max(1, 伤害−防御)`、450ms 基准无敌帧;伤害链顺序固定:roll→暴击→+攻击→职业→附魔→怪物防御(改序即改平衡);暴击乘区在 +Attack×3 之前(攻击力不吃暴击)。
## UI 交互规格
| 界面 | 元素与布局 | 流转 | 触控版式 |
|---|---|---|---|
| HUD | 体力条(左上)+时钟日期天气(右上)+金钱 | 常驻;点开时钟看季节日历 | 等比缩放,热区≥44px 的仅按钮 |
| 背包/工具栏 | 底部工具槽×8+Tab 全屏网格背包 | Tab/I 开→再关;槽位与物品表工具位同步 | 底栏加宽,点选代替快捷键 |
| 商店 | 商品列表(价格/库存/条件)+背包对照双栏 | 营业时段与店主对话进入→交易→Esc/返回退出 | 双栏改上下布局(移动) |
| 对话 | 底部文本框+头像位+选项列表 | 靠近 NPC 按 E→逐句→选项分支→结束 | 全屏按钮式选项(热区 44px) |
| 日终结算 | 全屏面板:收入明细/关系与技能变化/明日提示 | 就寝或时间耗尽自动→任意键进入次日 | 同桌面,纵向排布 |
(实证参照:原作对话文本中 `$表情` 标记驱动立绘切换,六表情索引 0-5;钓鱼小游戏是唯一不暂停时间的菜单。)
## 来自 GDD 的功能(P0 七系统)
| 系统 | 一句话职责 | 拥有的主数据 |
|---|---|---|
| S01 时间与日程 | 全局时钟与日终结算 | 日期、季节、天气、日程 |
| S02 体力与状态 | 全局行动成本与恢复 | 体力、状态效果 |
| S03 农场经营 | 核心产出与规划场 | 地块、作物、设施 |
| S04 探索与地图 | 场景与空间约束 | 区域、连接、资源点 |
| S07 物品与制作 | 资源身份与转化 | 物品、配方、背包 |
| S08 成长与技能 | 长期回报层 | 经验、等级、解锁 |
| S09 经济与商店 | 投资与回报换算 | 价格、交易、库存 |
## 技术目标与平台事实
- 首屏可玩 ≤ 5 秒(本地 HTTP,无网络依赖)。
- 移动视口稳定 60fps(作物满屏实例 ≤ 200 时)。
- 场景切换 ≤ 1 秒,无白屏。
## 技术风险
| 风险 | 影响 | 缓解 | 校验方式 |
|---|---|---|---|
| 非整数缩放导致像素模糊 | 全部视觉资产 | 整数倍缩放+letterbox | 双视口各跑 5 种常见分辨率截图比对 |
| 触屏点击判定过小 | 移动端交互不可用 | 交互热区 ≥ 44px;摇杆替代方向键 | 移动视口手测清单§3 |
| 存档结构变更丢档 | 用户进度 | schema_version 字段+迁移函数;写档先落临时名、成功后替换(旧档三级回退:正常→_old→_TMP) | 每版跑旧档加载测试 |
| 满屏作物逐帧重绘掉帧 | 移动端性能 | 脏矩形渲染;非动画作物静态层 | 性能面板:作物 200 实例压测 |
| 读档刷随机结果(SL 刷品质/掉落) | 经济与平衡崩坏 | 分层种子确定性随机:影响掉落/品质的 roll 一律绑定「世界日+存档 ID+位置/主体」 | 同日同格收获结果可复现测试 |
## 运行时能力边界(P0 七件,本例 HTML;引擎运行时对照见括号速记)
| 能力 | 落位 | 状态 | 说明 |
|---|---|---|---|
| 瓦片地图渲染 | Canvas 2D 分层渲染 + JSON 地图数据 | 自封装 | 四层:Back/Buildings/Front/AlwaysFront,深度 -1/0.1/64+/-1(原作 xTile 同构;Unity=Tilemap 原生/Godot=TileMap 节点原生/Cocos=TiledMap 组件) |
| 寻路 | A* 网格 | 自封装 | 仅 NPC 日程移动用(Unity=NavMeshGodot=NavigationServer 原生) |
| 2D 帧动画 | spritesheet atlas+帧表驱动(Canvas 逐帧绘制) | 自封装 | 帧表含毫秒级帧时长(原作 walk=4 帧循环、每帧 200ms |
| 分辨率适配 | CSS 整数倍缩放 + Canvas letterbox | 自封装 | 基准 16px 网格,NPC 16×32 放大 4 倍渲染(引擎侧用各自 Canvas/Viewport 适配方案) |
| 音频 | WebAudio 双通道(BGM/SFX) | 原生 | 循环无缝预解码;多场景换曲走六槽上下文仲裁后淡出(防场景竞争)(Unity=MixerGodot=AudioServer 总线/Cocos=AudioSource |
| 移动与碰撞 | 自研网格移动+碰撞检测 | 自封装 | 8 方向;碰撞体小于格子 2px 防卡边(Unity/Godot 物理系统原生) |
| 存档 | localStorage + JSON 文件导出 | 原生 | 版本迁移+临时名保护(引擎侧=文件系统/PlayerPrefs |
## 代码组织概览
- 承架构目录映射:`src/systems/s01_time/ … s12_events/`(每系统一目录:state/rules/api 三件);`src/scenes/` 场景注册;`src/core/` 循环、渲染、输入、存档。
- 入口 `main.ts` → 场景管理器(注册表制,场景切换走统一接口)。
- 边界约定:系统间只经公开 api 与事件总线通信,禁跨目录直改他人 state。
- 实证参照(原作,仅作组织参考):玩法逻辑全在一个 6.27MB 程序集,入口链 原生启动器→主 dll→GameRunner 帧循环(Update/Draw 非固定步长,真实毫秒累加器驱动逻辑);静态表/本地化文本/地图/运行状态/存档五类数据分置 Content、内存、Saves 目录,按需缓存加载。
## 外部库与 skill 引用
| 需求 | 用什么 | 来源与版本 | 实例化参数 |
|---|---|---|---|
| Web 游戏开发规范 | agc-web-game-development | `skill@当前版` | 双视口/双输入/本地预览/纯 HTML 交付 |
| 地图渲染 | Canvas 2D 自研渲染器 | 手写(JSON 地图数据) | 四层结构(对齐原作 xTile 层语义) |
| 音频 | 原生 WebAudio | 浏览器内置 API | BGM/SFX 双通道 |
## 场景与镜头
| 项 | 规定 | 依据 |
|---|---|---|
| 瓦片地图结构 | 16px 网格;农场 80×65、小镇 50×40、矿井按层生成 | 台账 D-05(区域分场景,非连续地图) |
| 镜头 | 跟随玩家+边界钳制;无缩放(固定整数倍) | GDD 顶层(无镜头玩法) |
| 场景切换 | 农场↔小镇↔矿井走连接点淡入淡出 ≤1s | 概念 D-05 定案"分区域切换" |
| 关卡数据 | `data/maps/*.json`(自定义 JSON:层/网格/对象点) | 契约 v2 |
## 输入与操作
| 动作 | 键盘 | 触控 | 备注 |
|---|---|---|---|
| 移动 | WASD/方向键 | 虚拟摇杆 | 8 方向 |
| 交互(对话/拾取/使用) | E / 空格 | 热区按钮(≥44px) | 场景对象注册热区 |
| 工具切换 | 1~8 / 滚轮 | 底栏工具槽 | 槽位与物品表工具位同步 |
| 背包/菜单 | Tab / I | 右上按钮 | 暂停世界时钟(对话与过场同样停表) |
## 音频
| 用途 | 格式/规格 | 触发点 | 依据 |
|---|---|---|---|
| 四季 BGM | ogg 循环,循环点标记,-18LUFS | 季节变更淡入淡出 2s | 美术圣经音频契约 |
| 矿井环境 | ogg 循环 | 进入矿井场景 | 同上 |
| SFX(收获/砍伐/受击/购买…) | wav 单发,同帧触发 | 事件总线 `sfx_event` | 事件↔音效映射表(资产表) |
(实证参照:原作音频 XACT 三件套,cue 名 435 候选、代码实际引用 230 个;音效带距离衰减、音乐六槽仲裁后淡出换曲。本项目音频契约见美术圣经。)
## 构建与验证
- 构建:`npm run agc build`(产物自包含,本地 HTTP 起服)。(引擎项目双轨:陶泥儿驱动引擎弹窗预览=开发期验证;驱动引擎 CLI 导出=交付构建——验证分级同下。)
- 自动:无头构建通过+静态检查(资源引用存在、表引用完整——CI 跑验收七查)。
- 半自动:双视口浏览器验证——桌面 1920×1080 与移动 390×844 各完成"新档→第 1 日流程→存读档",截图比对缩放整數性(引擎项目=弹窗预览内同流程)。
- 手测清单:①移动视口摇杆+热区全操作可完成第 1 日;②场景切换三次无白屏;③后台 5 分钟返回,时钟与存档一致。
## 版本里程碑
| 版本 | 内容 | 判据 |
|---|---|---|
| v0.1 | S01/S02/S03/S07+S04 基础 | 一个游戏日"买种→播种→浇灌→收获→出售"全流程可完成并触发日终结算 |
| v0.2 | 矿井+战斗(S06)+成长(S08) | 矿井进出一次、遭遇一场、掉落入账、经验到 1 级(累计 100xp) |
| v0.3 | NPC+任务+商店(S09/S10/S11) | 修路任务全链可交付并解锁洒水器配方 |
## 开放问题回执
| # | 问题 | 去向 |
|---|---|---|
| 1 | 背包格子还是重量容量(影响存档与 UI 结构) | → 概念层决策卡(B 级阻断,台账 D-15) |
| 2 | 矿井逐层生成是否本期做 | → 台账代决(建议 P2,GDD 已标"不做无限地牢";台账 D-16 |
| 3 | 体力是否与战斗共享单池 | → 台账 D-14(B 级待拍,暂按共享实现) |
@@ -1,182 +0,0 @@
# 顶层设计:《星露谷物语》
## 顶层定位与规模锚点
顶层不是做长线农场生产线,也不是做以探索战斗为主的活动清单,而是让玩家每天都在想:
> "今天做什么?——下雨天不用浇水,正好下矿井;回来的路上把罗宾的生日礼物送了。"
| 项 | 定义 |
|---|---|
| 循环单位 | 一个游戏日(约 10~20 分钟) |
| 段落构成 | 日初规划 → 白天执行(农务/探索/社交)→ 日落结算 |
| 操作复杂度 | 低——单人键鼠交互,无动作门槛 |
| 经营复杂度 | 中——时间、体力、资金三约束下的日程规划;不做生产线布局优化 |
| 长期主轴 | 第一:农场与生活方式成型;第二:社区修复与技能成长;角色数值只做辅助 |
## 设计目标
让玩家在一个没有唯一正确答案的乡村生活循环中,同时获得三种回报:
- 轻松生活:可以按自己的兴趣安排一天,通过农场、装饰、收集和社交获得稳定的正反馈。
- 规划掌控:时间、体力、季节和资金构成可理解的取舍,提前准备会让未来更高效。
- 探索成长:探索区域、战斗和资源发现提供变化与风险,并将成果转化为农场与角色的长期改善。
三者的关系不是并列小游戏,而是互相供给:农场提供稳定资源与恢复空间,探索提供稀有资源和发现,社交与社区目标提供方向和情感回报。
## 核心推动力
玩家每天拥有有限的时间与体力,但可以在一天结束后保留成果,并把收益投入到工具、设施、种子、装备和关系中。短期的"今天做什么"决策,持续转化为长期的"我的生活变得怎样"。
主要推动力按层次排列:
1. **即时推动**:完成一次采集、收获、战斗或对话,立即得到物品、金钱、经验、信息或关系进展。
2. **日程推动**:在日落或体力耗尽前完成今天最重要的目标。
3. **季节推动**:抓住作物、鱼类、节日和任务的时间窗口,准备下一阶段。
4. **长期推动**:改善农场、解锁区域和设施、完成社区目标、掌握技能,并建立属于自己的生活方式。
## 大循环
**规划一天 → 执行活动 → 获得资源与关系进展 → 出售、加工或投资 → 解锁更高效率与新内容 → 进入下一天。**
在更长周期中:**完成一个季节目标 → 调整生产与探索计划 → 迎接新季节 → 修复社区或解锁区域 → 扩大玩家可选择的生活方式。**
```mermaid
flowchart LR
A[规划一天] --> B[执行农务/探索/社交]
B --> C[获得资源·金钱·经验·关系]
C --> D[出售/加工/投资]
D --> E[解锁效率与新内容]
E --> F[进入下一天]
F --> A
```
## 小循环
### 农务循环
清理土地、播种或饲养 → 每日维护 → 等待成长 → 收获 → 出售或加工 → 将收益投入下一轮生产。
### 探索循环
选择目的地与携带物资 → 在有限体力和时间内采集、钓鱼或战斗 → 判断继续深入还是返程 → 带回资源 → 用于升级、制作或出售。
### 社交循环
寻找 NPC → 观察其日程与需求 → 对话、赠礼或完成委托 → 提升关系 → 解锁新对话、事件、配方或功能。
### 成长循环
重复使用某类能力 → 获得经验并提升技能 → 获得效率、工具或职业选择 → 以更低成本完成同类活动,并接触更高阶内容。
## 资源流与输入输出
```mermaid
flowchart LR
F[农场生产] -->|作物·畜产品| S[出售与加工]
E[采集·钓鱼·采矿·战斗] -->|原料·鱼类·矿物·战利品| S
S -->|金钱| I[工具·设施·种子·装备]
I -->|效率提升| F
E -->|经验| K[技能成长]
K -->|效率·配方| F
G[社交] -->|关系进展| R[新对话·事件·配方]
R --> G
```
- 主要输入:时间与体力;金钱、种子、原材料和消耗品;工具、装备和技能;NPC 关系、任务状态和社区进度;天气、季节、地图位置和活动开放状态。
- 主要输出:农产品、采集物、鱼类、矿物、战利品和加工品;金钱、技能经验、工具/设施升级;地图区域、配方、任务、事件和 NPC 关系解锁;农场外观、生产能力和社区状态变化。
- 反馈四层:
- 立即反馈:动画、音效、图标、数字、资源变更和状态变化。
- 短期反馈:背包、金钱、任务和技能面板更新。
- 中期反馈:设施完成、工具升级、关系事件和新区域开放。
- 长期反馈:农场自动化、社区恢复、生活方式成型和终局目标完成。
## 最小体验单位
一个约 10~20 分钟的"游戏日":查看状态 → 选一个主目标与一两个顺路次目标 → 执行 → 在时间或体力约束下结束 → 结算并获得当日反馈,决定明天是否继续当前计划或转换方向。
单个行动必须至少提供一种清晰反馈:资源增加、进度推进、能力提升、关系变化、地图信息或视觉状态变化。
## 核心活动流程
| 阶段 | 玩家行为 | 设计目的 |
|---|---|---|
| 日初 | 查看天气、季节、农场状态、商店或任务提示 | 给当天决策提供完整状态 |
| 目标选择 | 从生产、赚钱、探索、成长、社交和社区目标中确定优先级 | 制造当日取舍(张力兑现处) |
| 准备与出发 | 整理背包,携带工具、消耗品和必要装备 | 投入成本前置,增强方向感 |
| 执行活动 | 完成一组有空间关系或时间关系的行动 | 核心玩法发生地 |
| 中途调整 | 根据体力、时间、掉落和突发事件,决定继续、转向或返程 | 张力的实时兑现 |
| 结算与投资 | 出售或加工资源,购买材料,安排设施和下一轮生产 | 回流与长期化 |
| 日终反馈 | 记录技能、关系、任务、生产和解锁变化,进入下一天 | 闭合并钩住明天 |
## 取舍表
| 决策 | 立即收益 | 延迟收益 | 主要代价 |
|---|---|---|---|
| 出售原料还是加工(张力2) | 快速获得资金 | 更高价值或新用途 | 占用设备与等待时间 |
| 留在农场还是外出探索(张力3) | 稳定推进生产 | 稀有资源与发现 | 错过维护或消耗补给 |
| 深入探索还是及时返程(张力3) | 更多资源与经验 | 更高风险和返程压力 | 可能损失当日效率或物资 |
| 购买工具升级还是扩大生产(张力2) | 提高行动效率 | 增加产量与收入 | 当前资金减少 |
| 赚钱还是社交(张力4) | 直接经济进展 | 关系、剧情和配方回报 | 消耗可用于生产的时间 |
| 追求效率还是装饰与兴趣(张力5) | 更快成长 | 个性化与放松体验 | 放弃部分短期收益 |
(张力1"时间与体力有限"由目标选择阶段整体承载。)设计原则:这些选择应产生不同的合理生活方式,而不是把玩家逼向唯一最优路线。
## 节奏结构
- **日内节奏**:信息确认 → 连续行动 → 资源或发现反馈 → 体力/时间压力 → 日终结算。
- **周内节奏**:工作日进行生产与探索,商店营业、NPC 日程和周期事件制造计划变化。
- **季节节奏**:季初准备,季中稳定经营,季末收获与总结;季节变化带来资源、作物、天气和目标变化。
- **长期节奏**:从手工劳动起步,逐步获得工具升级、自动化设施、新区域和更复杂的关系目标。
整体情绪应在"安定的重复"和"偶尔的发现"之间摆动:农场与城镇提供恢复,探索与事件提供变化。
## 失败与回收
失败主要表现为"少拿与顺延",不毁掉既有积累。
| 情况 | 结果 |
|---|---|
| 当日计划未完成 | 成果顺延到明天,无惩罚;次日优先级重排 |
| 深夜未归昏倒 | 当日行动终止,次日体力受限,轻度损失 |
| 矿井中倒下 | 损失部分金钱或物品,保留大部分积累 |
| 季节更替未收获 | 该季作物枯萎——日历压力的主要形式 |
| 错过节日或窗口期 | 顺延至下个周期,制造轻度遗憾而非惩罚 |
## 系统范围
| 系统 | 顶层目的 | 边界(本层不做什么) |
|---|---|---|
| 农场经营 | 承载规划与回报的核心场 | 不做布局优化向的生产线 |
| 时间与体力 | 全局硬约束、日程的标尺 | 不做饥饿等生存需求式衰减 |
| 探索与采集(矿井/钓鱼/采集) | 提供风险与发现 | 不做程序生成的无限地牢 |
| 轻度战斗 | 矿井探索的风险与节奏变化 | 不做装备驱动的成长主轴 |
| 物品与制作 | 资源的转化与长期投资 | 不做复杂配方树管理 |
| 技能成长 | 使用即成长的回报层 | 不做技能树构筑 |
| NPC 关系与任务 | 社区叙事与情感回报 | 不做分支剧情引擎 |
| 经济与商店 | 连接产出与投资 | 不做玩家间交易市场 |
| 季节天气与节日 | 时间压力与变化来源 | 不做动态天气模拟 |
| 日终结算 | 闭合一天并钩住下一天 | — |
## 范围与非目标
最小完整版本包含:
- 一个可经营农场
- 一个小镇与若干功能区域
- 基础农务、采集、钓鱼、制作、轻度战斗和探索
- 有日程的 NPC、关系值、任务和社区目标
- 工具/技能成长、商店经济与基础加工链
- 季节、天气、节日和日终结算
不做清单:
- 不做无缝大型开放世界
- 不做复杂实时多人或玩家交易市场
- 不做以操作精度为核心的高难度战斗
- 不为每个系统都添加独立小游戏
- 不在本阶段确定具体数值、完整内容数量或实现方案
## 验证标准
| 验证点 | 成功标准 |
|---|---|
| 一天循环成立 | 玩家能复述"今天做了什么、为什么、明天想做什么" |
| 取舍真实存在 | 玩家在目标选择阶段出现可观察的犹豫或计划调整 |
| 时间压力温和 | 玩家感到"今天做不完"而不是"今天被逼着做" |
| 回流成立 | 玩家能把当日收益明确投入到下一轮计划 |
| 长期钩子成立 | 玩家能说出自己"在为什么长期目标积累" |
## 开放问题
- 休闲玩家与规划玩家的时间/体力压力如何共存?
- 战斗在整体游戏中的最低必要深度是什么,如何避免压过生活模拟?
- 社区目标应采用线性章节、可选收集,还是两者结合?
- 终局是明确的阶段性结算,还是允许玩家在结算后继续自由生活?
- 哪些信息必须通过 UI 直接展示,哪些信息可以保留为探索发现?
## 顶层定稿
顶层当前定稿为:以一个游戏日为循环单位,时间与体力构成温和硬约束,农场、探索、社交三线互相供给的慢节奏生活循环;矿井战斗保持伴生风险定位,失败只造成少拿与顺延。
后续架构必须围绕"一天"拆系统(时间/农场/探索/社交/经济/成长/结算);不得把战斗、制作或任何支线做成独立主轴,不得引入生存焦虑型惩罚。

Some files were not shown because too many files have changed in this diff Show More