yuque-doc-update

name	yuque-doc-update
description	为这个 Don't Starve Together 模组规划、撰写或配套截图准备语雀对外文档时使用。通过对照用户提供的对外日志、git log/PR、现有语雀页面结构和源码行为，生成按语雀页面拆分的玩家可读正文、截图占位和最少 DST 控制台截图指令；适用于更新日志、食物、建筑、工具、鲜活世界等页面，默认直接在对话中输出可复制 Markdown，只有用户明确要求时才生成 docx 或尝试直接更新语雀。

语雀文档更新

使用这个 skill 为本仓库整理语雀对外文档更新。目标是把代码变更翻译成玩家能读懂、维护者能核对的文档草稿，而不是复述实现细节。

用户偏好总结

• 默认直接在对话里给可复制的语雀 Markdown，不写 docx；只有用户明确要求“新建 Word / 更新 docx”时才使用 documents skill。
• 直接更新语雀前必须先说明计划并等待用户确认；如果语雀 API/MCP 不可用或要收费，改为手工复制草稿。
• 文案要像现有 wiki 条目，不像更新日志、PR 描述或系统说明书。
• 用户偏好结构化但不冗长：标题、图片/图片占位、引用块参数、2-4 个短段正文。
• 重点写玩家能看到、能操作、会关心的行为；少写组件名、继承链、内部实现。
• 截图配套的“测试代码”指最少 DST 控制台指令和少量手动步骤，不是新增 Lua 测试代码。
• 图片没有现成 URL 时只写占位，例如 【灯笼的截图】；不要生成图片。透明 PNG 粘贴到语雀变灰时，优先建议上传原文件而不是从预览器复制。

工作流程

1. 明确输入范围：
   • 优先使用用户给出的对外日志、日期范围、PR 号或提交范围。
   • 如果用户只给了最近日志，用日志日期作为起点，结合 git log 找到对应提交。
   • 如果用户要求“先计划”，只输出页面级更新计划，等用户确认后再写文档或草稿。
2. 收集 git 线索：
   • 运行 git --no-pager log --since=<日期> --oneline --decorate。
   • 对可疑提交运行 git --no-pager show --stat <sha> 或读取关联 diff。
   • 把提交归类成玩家可见主题，例如新增内容、行为调整、玩家可见修复。
3. 确认语雀页面结构：
   • 如果能访问语雀站点，先读取目录和现有页面标题，确认应该更新哪些页面。
   • 如果不能稳定访问，按本仓库常用页面拆分：关于《额外物品包》、食物、建筑、工具、鲜活世界。
   • 不要在未获用户确认时直接写入语雀；直接写文档前先说明要更新哪些页面。
4. 核对源码行为：
   • 食物与料理：查 scripts/prefabs/foods.lua、scripts/prefabs/foods_lang.lua。
   • 配方：查 scripts/recpiesHooker.lua。
   • 新 prefab 行为：查 scripts/prefabs/<prefab>.lua。
   • hook 与掉落：查 scripts/hooks/*.lua、scripts/prefabsHooker.lua。
   • 容器或展示规则：查 scripts/containersWrapper.lua 和对应 prefab。
   • 玩家故事或已有解释：查 scripts/aipStory/chinese.lua。
5. 写成语雀草稿：
   • 按页面分块输出，便于复制粘贴。
   • 每个条目优先包含：名称、代码、制作/烹饪、效果、玩家使用说明。
   • 更新日志用一整段中文，按“新增内容 -> 行为调整 -> 玩家可见修复”组织。
   • 食物效果可以写数值；复杂机制用玩家语言概括。
6. 交付方式：
   • 默认直接返回按语雀页面分组的 Markdown。
   • 如果用户明确要 Word/手工复制文档，使用 documents skill 生成或更新 .docx 草稿。
   • 如果用户要求直接更新语雀，先确认登录/API能力和更新范围；没有可靠免费 API 时，优先生成手工复制草稿。
7. 为文档截图生成准备内容：
   • 当用户说“截图配套测试代码”“生成截图需要的测试代码”时，解释为生成 DST 控制台指令和少量手动步骤，不要改 Lua 代码。
   • 使用 $dst-test-plan 的控制台命令规则，优先给最少的 c_give(...)、c_spawn(...)、原版世界事件或已存在 dev 辅助命令。
   • 只准备当前文档条目需要拍到的内容，不扩展成整轮功能回归清单。
   • 如果截图状态不能用公开控制台命令直接设置，先给最短游戏内操作；只有用户明确要求新增辅助入口时才修改代码。

写作规则

• 面向玩家和维护者，少写实现细节。
• wiki 正文参考现有语雀条目的组织方式：### 标题，下一行放图片或图片占位，然后用 > 引用块列配方、品质、影响范围等关键参数，正文再解释玩法。
• 如果没有真实图片，不要生成图片，使用占位写法，例如 【不同品质农作物的截图】、【灯笼架挂满灯笼的截图】。
• 正文语气要像 wiki 介绍，不像更新公告或系统说明书：先讲这个东西能做什么，再讲玩家应该注意什么。
• 文案可以有一点趣味，但要克制；不要把每条机制都写成“好玩”的宣传语。
• 重要限制或关键技巧可以用 **加粗**，非常关键的提示可以用 <font style="color:#DF2A3F;">...</font>，但不要滥用。
• 条目内列表只用于材料、效果来源、状态说明等确实适合扫描的内容；正文避免堆太多 bullet。
• 内容不要太长。普通条目通常控制在一张图、一个引用块、2-4 个短段和必要的少量列表。
• 食物页参考现有结构拆成 ## 食材 和 ## 配方：
  • 大资源点用 ### 名称，产物用 #### 名称。
  • 配方条目用 ### 名称。
  • 标题下一行放图片 URL；没有图时放 【名称的截图】 或 【名称的图片】。
  • 引用块每行使用 > + 字段：值，常用字段顺序为：代码、配方、生命、饥饿、理智。
  • 食材本体没有三维数值时，只写代码；可食用产物写生命、饥饿、理智。
  • 关键概率、天数、核心道具可使用 **<font style="color:#DF2A3F;">...</font>** 标注。
• 工具、建筑、鲜活世界页面也沿用同一条目风格：
  • ## 页面分区 可选，条目用 ### 名称。
  • 引用块优先写代码和配方/状态；没有配方的世界掉落或生态物只写代码、状态、来源等必要字段。
  • 正文先讲用途，再讲限制或特殊交互，例如清洁扫把换肤、挂载、潮湿切换、伙伴休憩。
• 不写 dev_mode、测试辅助、本地 Codex 配置、技能安装、内部脚本过程。
• 不写资源目录整理、格式化、清理旧文件等玩家无感知变更。
• 避免把内部规则写得过细；例如把“继承链路”改写成“品质会在种植、收获、烹饪等流程中自然延续”。
• 页面计划应先说明“要更新哪些页面”，再说明每页更新什么。
• 若用户只批准其中一项，只处理那一项。

截图准备规则

• 截图准备不是测试实现，不创建或修改测试代码。
• 输出以“目标 / 控制台指令 / 手动步骤 / 截图占位”为主。
• 控制台指令尽量少，一条截图只给能摆出画面的必要 prefab 和状态切换。
• 不使用 local 变量、循环、临时函数或直接改组件字段的 Lua 片段。
• 优先复用已有开发入口，例如 reskin_tool、c_aip_cozy_nest_guest(...)、c_spawn(...)、c_give(...)。
• 截图需要稳定明亮环境时，默认先给：
  • TheWorld:PushEvent("ms_setphase", "day")
  • TheWorld:PushEvent("overrideambientlighting", Point(1,1,1)) 拍完提醒可用 TheWorld:PushEvent("overrideambientlighting", nil) 恢复正常环境光。
• 需要成长、开花、季节、昼夜或湿度状态时，优先用公开事件或最短手动动作；不要为了截图写大段验证步骤。

本次 2026/05 分析记录

这次文档更新的分析路径如下，可作为后续同类任务模板：

1. 用户先给出两条对外日志：
   • 2026/05/18 生态装饰与水域内容更新。
   • 2026/05/02 农作物品质系统更新。
2. 用 git log 对齐到提交主题：
   • feat: 新增无尽之莲与莲子
   • feat: 新增灯笼架挂灯系统
   • feat: 新增海洋之泪世界掉落
   • Adjust oversized crop quality drops
   • Add grandfather clock decoration
   • add cozy nest container display
   • Add cozy nest decoration
3. 从语雀目录判断页面归属：
   • 关于《额外物品包》：追加两条更新日志。
   • 食物：农作物品质、莲系材料、莲系料理。
   • 建筑：温馨小窝、祖父钟（座钟）、灯笼架。
   • 工具：灯笼。
   • 鲜活世界：无尽之莲水域生态、海洋之泪世界掉落。
4. 从源码核对行为：
   • aip_farm_plant_hook.lua、aip_edible_hook.lua、aip_birdcage_hook.lua：品质传递、食用效果、鸟笼换种。
   • aip_endless_lotus.lua、prefabsHooker.lua：青蛙掉莲子、水面投种、采花、挖荷叶和莲藕。
   • foods.lua、foods_lang.lua：荷叶粥、荷叶糯米鸡、莲藕排骨汤、酸辣藕片、炸藕盒的配方和效果。
   • aip_lantern.lua、aip_lantern_stand.lua、containersWrapper.lua：灯笼燃料、挂灯数量、开关与光照。
   • aip_cozy_nest.lua：展示位，以及眼骨、星空、格罗姆花驱动切斯特、哈奇、格罗姆休憩。
   • aip_grandfather_clock.lua：座钟装饰与现实时间指针。
   • aip_ocean_tear.lua、prefabsHooker.lua：世界掉落、湿润/干枯状态与湿度变化。
5. 交付时先写入桌面 Word 草稿，按语雀页面分块，方便用户手工复制。