bagisto-documentation

Bagisto 文档

Bagisto 的文档存放在与代码库分开的仓库中，每种受众各有一个仓库。所有文档站点都以相同方式使用 VitePress 构建，因此本技能中的操作方法适用于所有站点——开发者文档、商家用户指南，以及今后添加的任何指南。

第 1 步：确定读者是谁

其他一切都取决于此，因此请在动笔之前先确定。根据受众判断，而不是根据你恰好打开了哪个仓库来判断——同一个仓库中的页面可能面向不同的读者，判断错误会让页面虽然技术上准确，却对读者毫无用处。

询问	如果是	加载
读者会针对 Bagisto 编写代码吗——例如软件包、主题、集成或 API 客户端？	开发者文档	developer-docs.md
读者会通过管理面板运营商店，而不接触代码吗？	用户指南	user-guide.md

如果某个页面似乎需要同时面向两种受众，那就应该拆成两个页面。商家看到类名会跳过；开发者看到点击路径会不再信任页面。按受众拆分，并在页面之间添加链接。

如果出现新的文档仓库——例如市场指南、自托管指南——它仍然面向这两类读者之一，只是名称不同。使用相同的方法判断，并参考相同的文档。

第 2 步：找到仓库，不要猜测

每个站点都是一个独立仓库，而不是 Bagisto 应用中的文件夹，因此请在编辑任何内容之前先找到它：

find . ~ -maxdepth 6 -type d -path '*/src' -path '*doc*' 2>/dev/null | head

如果仓库尚未克隆，请向用户询问路径或请其克隆。切勿编造路径，也不要误将页面写入 Bagisto 应用——应用没有 src/ 文档目录，因此在那里创建的页面会悄然丢失。

写作前先阅读相邻页面

打开你要添加内容的章节中两到三个现有页面，并遵循它们的深度、标题节奏和语气。即使页面中的每项事实都正确，若读起来与相邻页面不同，也是一处缺陷。

同时检查是否有内容重复：如果某个主题已经在别处部分涵盖，请扩展该页面或添加交叉链接，不要另立一个事实来源。两个页面若对同一个问题各有部分解答，久而久之就会互相矛盾。

参考文件

文件	在以下情况下加载
developer-docs.md	为编写代码的读者写作时——语气、结构、代码示例
user-guide.md	为运营商店的读者写作时——语气、页面形式、操作步骤
screenshots.md	页面需要图片时——截图、干净的设置、命名
publishing.md	添加、移动或删除页面时——侧边栏、重定向、验证
site-structure.md	了解文档仓库的结构时——布局、命令、各站点的差异
common-mistakes.md	审查已完成的更改时

每个站点都是 VitePress 站点：页面位于 src/ 下，侧边栏配置在 .vitepress/config.mts 中，旧版 URL 配置在 .vitepress/_redirects.ts 中。使用 npm run docs:dev 预览；npm run docs:build 是必要的检查关卡。各站点的组件和重定向前缀各不相同，因此请先了解你所在的站点——site-structure.md。

不可妥协的要求

• 为一位读者而写。 第 1 步确定的受众决定了用词、需要解释的内容和可以默认读者了解的知识。这条规则决定了文档页面是好用还是毫无用处。
• 已发布的 URL 永不失效。 凡是可能导致页面 URL 变化的操作——重命名文件、将其移到其他章节、更改其别名、拆分页面或删除页面——都需要在 .vitepress/_redirects.ts 中添加一条记录，将旧 URL 指向内容的新位置，并且 将所有指向旧 URL 的现有重定向改为指向新位置。没有人会替你更新他们的链接。请参阅 publishing.md。
• 除非先为该 URL 设置了重定向，否则绝不删除占用 URL 的页面。 有些页面的存在只是为了让旧路径继续有效；它们看起来像是多余的，实际上却不可或缺。
• 侧边栏是唯一的导航方式。 未出现在 .vitepress/config.mts 的 sidebar 数组中的页面，只能通过输入 URL 访问。添加页面时，须在同一次更改中添加对应条目。
• 所有文件名都使用 kebab-case。 文件名须全部小写、以连字符分隔，不含空格，不使用 camelCase，也不使用下划线——页面和图片都一样。较早的文件是在此规则出台前创建的；新文件应遵守规则，而不是仿照相邻文件，也不要顺手重命名无关文件。
• 先检查实现，再查看现有页面。 你要更新的页面所描述的功能可能已经迁移、更名或移除。应从代码、配置文件、语言文件和正在运行的管理后台入手；将旧文案视为待验证的假设，而不是依据。
• 根据代码库验证陈述，而不是依赖记忆。 笃定却错误的句子比没有页面更糟糕，因为读者会相信它。页面上的每条命令、路径、配置键、类、方法、路由、标签和行为，都必须依据本次会话中读取的文件或运行的命令。打开文件、运行命令、核对字符串。
• 代码示例须通过 Pint 检查。 PHP 示例的格式必须与项目的 pint.json（laravel 预设）完全一致——=> 两侧各有一个空格、保留尾随逗号、排序导入语句、不对齐列——并且应符合生产环境中的 Bagisto 代码风格。应对提取出的示例运行 Pint，而不是凭肉眼判断；操作流程见 developer-docs.md。
• 顺序操作应列为编号步骤。 只要读者必须按顺序完成多项操作，就应在说明目标的标题下用编号列表，每步只写一项操作。将“前往 X、点击 Y、输入 Z 并保存”串在一个句子中，属于商家端的缺陷，也会让开发者端显得不妥。对于不分先后的选项、属性和前置条件，才使用项目符号。
• 所有版本共用一套文档。 不为不同版本建立独立页面树，不使用“2.5 beta”标签，也不写“当前开发版本”：当前版本称为 Bagisto 2.5。只有行为或可用性存在差异时才注明版本，并在同一段中说明当前行为，这样页面在下一个版本发布后仍然准确。请参阅 developer-docs.md 中的 Versions 一节。
• AI 术语必须有实现依据。 “生成式 AI”仅用于能够生成内容的功能——页面和标题应写作“生成式 AI (Magic AI)”，只有管理后台自身的标签和软件包中才单独使用“Magic AI”。“Agentic AI”用于由 Agent 通过工具执行操作的功能（WebMCP、使用技能的编码 Agent）。切勿声称代码并不具备的自主能力：Magic AI 不会在未经管理员操作的情况下应用任何内容。请参阅两份参考文件中的 AI 章节。
• 用户指南应遵循商家的使用流程，Configure 应遵循管理后台自身的 Configuration 页面；市场指南面向三类读者；配置页面应从 config('core') 树入手，而不是从旧页面开始。每项内容对应的章节见 user-guide.md。除非用户要求，否则不要重新组织开发者文档的导航。
• 最后进行独立审查。 编辑完成后，以未参与编写的审阅者身份核查结果：根据代码核验每条陈述，让每个示例通过 Pint 检查，确认每个链接和图片都能正常解析，确认侧边栏与 llms.txt 一致，然后运行构建，最后查看 common-mistakes.md。只写完而未经检查的更改，不算完成。
• 手动编写 llms.txt 和 llms-full.txt。 不会有任何工具自动生成它们。添加、移动或删除页面时，也必须编辑这两个文件。
• 构建是最终关卡。 npm run docs:build 会报告它写入的每条重定向。未经构建的更改，就还没有经过检查。 必需的子技能： 在宣布任何更改完成之前，使用 bagisto-change-verification。