文档站内容维护工作流

本页让接手 F:\MiragEdge-DocWeb 的 AI agent 能在不破坏现有信息架构、视觉风格和生成产物的前提下，完成内容新增、事实修订、页面迁移和导航调整。

先做事实核对，再修改源码页面；不要把旧页面、记忆或插件名称当成当前行为依据。

开始前的固定动作

git status --short
rg -n "关键词或旧路径" start play plugins plugin-guides developer .vitepress --glob '*.md' --glob '*.ts' --glob '*.mts'
Get-Content -Raw package.json

1. 先确认工作区已有改动；它们属于其他任务或用户，除非本次任务明确涉及，否则不得覆盖、恢复或格式化。
2. 搜索现有页面、侧栏入口、交叉链接和历史跳转，避免重复建页或留下失效路径。
3. 涉及服务器玩法、插件行为、数据包资源或配置值时，先读取当前源码、配置、日志或用户提供的事实摘要。旧玩家手册只能作为待核对材料。
4. 在修改前确定受众：普通玩家、服主/维护者，或开发者。一个页面不要同时承担三种读者的说明任务。
5. 涉及数据包玩家玩法时，检查 F:\FCelestial\datapacks\ 下是否有对应的玩家玩法交接稿（handoff 文档）。交接稿以当前部署包为基准复核，列明已确认的、待实机确认的和禁止撰写的三类内容，是写玩家玩法文档时的首选事实依据。

页面落位

内容性质	优先目录	写作边界
入服、账号、社区、客户端兼容与长期游玩	start/	玩家行动路径，不写实现细节
生存玩法、探索、装备、经济与生活系统	play/	解释有什么、怎么用、限制和风险
当前服务器已开放的功能	plugins/	面向玩家；只写可确认的游戏内行为
可独立部署的原创插件说明	plugin-guides/	可写安装、配置、命令、维护与排错；每个插件单独目录
开发流程、资源包、数据包、跨插件集成与站点维护	developer/workflows/、developer/website/、developer/reference/	可写技术契约、配置与验收
已废弃、待核对或不承诺上线的内容	developer/archive/	明确其历史状态，不能作为当前玩法入口

页面迁移到新目录时，先迁源码 Markdown，再调整侧栏，并在 .vitepress/legacy-redirects.ts 为旧路由建立跳转。不要保留两份正文来“兼容”旧地址。

写作规则

玩家页面

• 使用自然中文，按玩家会遇到的顺序组织，不要机械重复“想解决什么 / 怎么使用 / 为什么这样设计”。
• 只描述触发条件、操作、提示、消耗、冷却、限制、失败原因和异常处理。不要出现配置字段、权限节点、内部 ID、类名、数据库、事件监听或实现原理。
• 只承诺已经确认的行为。掉率、属性、开放区域或尚未实服验收的规则必须保持条件化表述，或移动到开发归档。
• Java 与基岩版共通时写在同一页；只有操作或兼容性不同才单独标注。

开发者与原创插件页面

• 首先写适用版本、事实来源和边界，再给出配置或命令示例。
• YAML、命令和路径必须来自当前项目或已核对环境；示例中的占位符要清楚标出，不能伪造可直接部署的配置。
• 把静态检查和实服验收分开说明。构建通过不能证明客户端资源包、跨端表现、事件触发或经济结算正确。

目录、链接与视觉

• 顶栏只放稳定的大分区；独立插件入口位于“更多”中的原创插件文档，不要塞回玩家功能导航。
• 侧栏一级分组可使用一个 emoji，子项与正文标题保持纯文本。默认展开当前读者最常查的内容，避免整栏全部折叠。
• 新页面必须有准确的侧栏入口。新增或移动页面后，检查相关首页卡片、上级索引和交叉链接。
• 站内图片优先使用现有 SmartImage、McItem 等组件和 public/ 中已核对的资源。组件中的根路径必须适配 VitePress base；不要直接引用临时文件或未验证的网络图片。
• 文本链接应保持现有主题的链接样式；需要让读者保留当前阅读上下文时，用新标签打开外部资料或跨主题参考，不要滥用彩色链接模拟按钮。

使用交接稿（玩家玩法交接文档）

交接稿是服务器数据包部署内容的权威事实摘要，放在 F:\FCelestial\datapacks\ 目录下，以部署 ZIP 为基准复核。每条内容按三类标注：

• 已确认：可以按文字直接写入玩家页面，使用自然中文表述。
• 待实机确认：只能以条件化形式写入，应有"当前版本可……"、"需服务器实测"等限定语，或直接归档到 developer/archive/。
• 文档禁区：声明为旧机制、异常路径或已注释代码的内容，不得写入玩家页面或当前功能。例外：在 developer/archive/ 中记录历史状态时需注明"当前版本不可用"。

交接稿还包含"限制与冲突"说明（如 CraftEngine/Aiyatsbus 可能拦截的数据包物品组件），在写玩家页的"限制"段落时直接引用，不要凭空猜测插件兼容性。

修改闭环

轻量操作：待办维护

待办是数据驱动的例外。新增、调整、完成或归档待办时，先读待办维护约定，通常只修改 public/data/todo.json：不新增页面，不动侧栏、重定向、TodoList 组件，也不手工改写 public/ 中的生成 Markdown。

可直接把下面的话交给 AI：

在 F:\MiragEdge-DocWeb 的待办中新增：<内容>

同一模式也适用于 把待办“<标题或 ID>”调整为：<内容>、把待办“<标题或 ID>”标记完成 和 归档超过 15 天的已完成待办。AI 必须先读取 JSON，沿用现有分组、字段和状态；信息不足、标题重名或无法确定截止日期时应先询问，不能编造事实。新待办 ID 使用 w-YYYY-MM-DD-短英文标识；完成记录应填写真实完成日期。

1. 建立事实清单

把本次变更拆成可验证条目：事实来源、目标读者、页面位置、是否需要导航、是否需要旧路由跳转、是否需要图片或组件、哪些内容暂不承诺。手头有交接稿时，以交接稿标注的"已确认"为事实依据、"等待实机"为有条件表述、"文档禁区"为禁止写入的内容。

2. 只改源码

正常内容修改的目标是 Markdown 源文件、.vitepress/config.mts、.vitepress/legacy-redirects.ts 和必要的 Vue 组件/稳定资源。不要手工编辑以下生成物：

• public/ 下由 scripts/generate-llms.mjs 生成的 Markdown、llms.txt 与 llms-full.txt
• .vitepress/dist/ 下的站点构建产物
• 测试报告与构建时采集的数据

需要更新它们时运行对应脚本，再确认差异只反映本次源码改动。构建可能改写 public/data/contributors-activity.json；只有确认它是本次验证产生、且不是用户改动时才恢复。

3. 同步信息架构

新增页面时同步完成以下检查：

1. 在 .vitepress/config.mts 添加或更新唯一的侧栏入口。
2. 为独立插件补充 plugin-guides/index.md 卡片和插件侧栏分组。
3. 移动或改名页面时，在 .vitepress/legacy-redirects.ts 添加精确或前缀跳转。
4. 搜索旧路径和旧术语，更新真正指向该内容的源码链接。
5. 已归档内容不再出现在当前玩家入口；当前正式方案不应继续标为归档。

4. 生成与验证

按改动风险执行，所有内容/导航任务至少运行前两项：

pnpm run audit:routes
pnpm run typecheck
pnpm run llms
pnpm exec vitepress build
git diff --check

改动 Vue 组件、脚本、路由插件或主题行为时，额外运行：

pnpm test
pnpm run build

pnpm run build 还会执行图片水印、LLM 索引和版本产物。若水印或外部资料处理报告资源锁定、网络回退等非阻断问题，不能把它们写成“完全通过”；要说明核心 VitePress 构建是否成功，以及残余问题是否影响本次页面。

5. 交付检查

最终报告应包含：

• 修改的源码页面、导航与重定向文件。
• 新页面路由和已覆盖的关键内容。
• 实际运行过的验证命令及结果。
• 不能由静态检查证明的实服、浏览器、资源包或跨端事项。
• 明确说明保留的已有工作区改动，不把它们混入本次成果。

可直接交给 AI 的任务模板

在 F:\MiragEdge-DocWeb 完成以下文档变更：

目标读者：玩家 / 服主维护者 / 开发者
事实来源：当前源码、配置、日志、已确认玩法摘要
目标内容：<列出必须覆盖的规则或功能>
建议位置：<如有；没有则先搜索并选择最合适现有页>
路由要求：<保留、迁移或新增；是否需要旧地址跳转>
禁止内容：<未确认规则、技术细节或玩家页不应出现的内容>

执行要求：
1. 先检查 git 状态、现有页面、侧栏、交叉链接和旧路径。
2. 只修改源码与必要稳定资源；保留其他已有改动。
3. 同步侧栏、首页索引和 legacy redirect。
4. 运行 pnpm run audit:routes、pnpm run typecheck、pnpm run llms、pnpm exec vitepress build、git diff --check；涉及代码时再跑 pnpm test。
5. 回报改动文件、页面链接、验证结果和仍需实服确认的事项。

不可违反的边界

• 不要为了“内容更完整”补写未经确认的玩法、数值、掉率、区域或兼容性承诺。
• 不要把面向玩家的玩法页改成配置手册，也不要把开发者文档塞进玩家导航。
• 不要删除、恢复或覆盖与本次任务无关的用户改动。
• 不要只改正文而遗漏侧栏、索引、旧链接和 AI 索引。
• 不要把静态构建结果包装成真实服务器或客户端验收。
• 交接稿的"文档禁区"列出的内容不得写入当前玩法页面；即使交接稿包含详细描述，也必须在 developer/archive/ 中声明历史状态，而非作为功能入口。