№ · 专题 CH.08.10
主页 · 🏮 专题 · 同福客栈挂机游戏 · 文档总索引

同福客栈挂机游戏 · 文档总索引

📅 2026-08-10 · 📦 5.2 KB · 🏮 专题 · 📝 MD 文档 🆕 14d 🏷️ Buff🏷️ 拍卖🏷️ 联机🏷️ 剧情🏷️ 经济🏷️ 主线

本目录是项目的工程文档真值。 玩家文案、产品对外介绍见 pitch/;公开站点镜像见 ../docs-site/。

认路原则:看设计真值 → design/active/;看当前执行面 → handoff/index.md → plans/active/;看历史快照 → 各 archive-index/。

0. 阅读入口(按角色)

| 我是 | 先看这个 | | :--- | :--- | | 新加入的开发者 | specs/engineering/ + specs/ui/ + AGENTS.md | | PM / 调度 | handoff/index.md → handoff/recently-closed-business-cards.md → plans/active/ | | 设计师 | design/active/ + uirefactor/ + art/ | | 剧情 / 文案 | story/主线故事/ + story/characters/ + pitch/ | | 经济数值 | economy-sim/ + design/active/(经济章节) + release-notes/ | | 联机 / 拍卖 / 战斗 | design/active/ 对应章节 + release-notes/ | | 想看本周做了什么 | release-notes/ + daily-plans/(最近 7 天) |

1. 子目录分类(17 个)

1.1 工程规范(specs/)— 硬约束

  • specs/engineering/ 工程与代码规范
  • specs/ui/ UI/UX 设计规范
  • specs/data/ 数据规范
  • specs/workflow/ 工作流约定

1.2 设计真值(design/)— 当前/历史

  • design/active/ 当前真值(60+ 文件)
  • design/backlog/ 待办需求设计
  • design/completed/ 已落地设计
  • design/buff/ buff 系统
  • design/technical/ 技术方案
  • design/drafts/ 设计草稿
  • design/6.25玩法/ design/6.26玩法/ 早期玩法分册

1.3 剧情 / 文案(story/)— 数据 + 渲染稿

  • story/主线故事/ 月度主线对白稿(43 文件,月 05 ~ 月 20)
  • story/characters/ 角色档案
  • story/simulator/ 剧情模拟器

1.4 控制面 / 调度(handoff/ + plans/ + daily-plans/)

  • handoff/ PM 与 worker 之间的派发、回调、收口(见 handoff/README.md)
  • handoff/archive-index/ 按月归档索引(2026-08-10 新建)
  • plans/active/ 当前进行中的计划
  • plans/completed/ 已完成的计划
  • plans/backlog/ 待办需求
  • daily-plans/ 日版本计划(原路径保留)

1.5 实施 / 重构(uirefactor/ + 竖版UI重构/ + orchestration/)

  • uirefactor/ UI 重构历史与设计稿(49 文件,28.9 MB,大量 PNG)
  • 竖版UI重构/ 早期竖版方案(1 文件,基本被 uirefactor/ 取代)
  • orchestration/ 调度编排(用 index.md 而非 README)

1.6 经济 / 仿真(economy-sim/)

  • 七侠骰坊 + 一年 360 日平衡仿真报告 + CLI 工具

1.7 UI 工具(tools/)— 离线 HTML 工具

  • quest-editor / item-editor / buff-editor / agent-daily-flow-editor

1.8 历史归档(archive/)

  • 旧设计片段、废弃草稿、无法证明完成的源材料

1.9 杂项

  • art/ 美术与设计稿索引
  • audio/ 音频相关(目前仅 1 文件)
  • column/ 专栏文(武林周报等)
  • release-notes/ 版本更新公告
  • reviews/ 复盘记录
  • pitch/ 产品对外推介材料(3 个 HTML,2026-08-10 从根目录归档)

2. 真值优先级(冲突时)

release-notes/CHANGELOG  >  design/active/  >  handoff/index.md  >  plans/active/  >  story/主线故事/
       (最新发布)            (设计真值)        (当前控制面)         (当前计划)        (剧情最新)
  • 剧情真值:先 story/主线故事/,再 src/data/eventTables/(代码),开发期剧本可能领先代码。
  • 设计真值:design/active/ 是当前拍板,design/completed/ 是已落地但可能不再迭代。
  • 执行真值:handoff/index.md In-Flight 段是唯一活跃入口,recently-closed-business-cards.md 是结案指针。
  • 发布真值:release-notes/ 是给玩家看的更新日志,工程变更以 handoff/index.md 为准。

3. 命名约定

  • 数据 / 逻辑 / UI 三层分离:data/<domain>/ utils/<domain>/ components/<domain>/,详见 ../AGENTS.md § 1。
  • 不使用 @/ 别名;统一用相对路径。
  • 工具文件后缀 Logic(逻辑),数据文件裸名,UI 组件 PascalCase。
  • Markdown 用相对路径,不用绝对路径。

4. 文档维护节奏

  • 每周:核对 handoff/archive-index/<当月>/ 与 recently-closed-business-cards.md 一致。
  • 每月初:在 release-notes/ 写上月整合公告。
  • 设计拍板:design/drafts/ → design/active/(并清理 drafts)。
  • 执行完成:plans/active/ → plans/completed/(并清理 active)。
  • 剧情完结:story/主线故事/月XX-XXX.md 三版本(初版 / 节气增强版 / 对白稿)按需更新,旧版本不删,加 _legacy 后缀。

5. 与 docs-site/ 的关系

docs-site/ 是公开文档站的构建产物,内容从 docs/ 渲染。

  • 站点源 = 本目录(docs/) + pitch/
  • 站点构建 = scripts/docs-to-html/(待确认)
  • 站点产物 = docs-site/

详细边界与构建流程见 文档体系说明.md。

6. 不放本目录

  • 构建产物:dist/ dist-whimsy/ node_modules/ — 已在 .gitignore
  • 日志:../logs/(根目录)和 ../verify-reports/
  • CI / 临时调试:../tmp/ ../.codex-temp/ ../.codex/
  • 运行时资源:../public/ ../assets/
  • AI agent 资产:../.agents/ ../.mavis/ ../.wrangler/