<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>文档 · 开发资料 on Banyan</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/articles/docs-dev/</link><description>Recent content in 文档 · 开发资料 on Banyan</description><generator>Hugo</generator><language>zh-Hans</language><lastBuildDate>Mon, 16 Nov 2026 00:00:00 +0800</lastBuildDate><atom:link href="https://f6e67316.banyan-git-test.pages.dev/zh/articles/docs-dev/index.xml" rel="self" type="application/rss+xml"/><item><title>01 本地开发</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/local-development/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/local-development/</guid><description>&lt;h2 id="仓库结构"&gt;仓库结构&lt;/h2&gt;&#10;&lt;p&gt;Banyan 仓库维护主题、Skill、源码测试、参考站点、使用指南、开发资料和版本说明。&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;banyan/&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── hugo.toml, go.mod #最小演示配置&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/articles/ #正文、文章分类、文档和版本说明&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/articles/docs-guide/ #使用指南&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/articles/docs-dev/ #开发资料&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/articles/changelog/ #主题和 Skill 版本说明&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/articles-all/ #文章汇总&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/products/ #产品分类与一份引用&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/products-all/ #产品汇总&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/{appearance,language,my,rss}/ #站点自有设置和说明页&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── assets/site/ #站点资源和交付配置&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── assets/i18n/ #由项目挂载的界面字典&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/powered-by/ #版本信息与预取诊断&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── content/_res/ #离线页和首页艺术包&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── module/ #布局、脚本和样式，不含站点内容&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;├── .agents/skills/swaw-banyan/ #本地工具和通用检查任务&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;└── tests/ #主题和工具源码测试&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Banyan 根 &lt;code&gt;go.mod&lt;/code&gt; 使用 &lt;code&gt;replace ... =&amp;gt; ./module&lt;/code&gt;，直接读取随仓库提供的主题源码，无需先发布 Module。其他站点可用本地 &lt;code&gt;replace&lt;/code&gt; 指向这份源码。&#10;站点定制留在各站点根目录，可复用主题行为放入 Banyan 的 &lt;code&gt;module/&lt;/code&gt;。&#10;独立站点发布时通常固定 Module 版本。完整仓库随附的 &lt;code&gt;./module&lt;/code&gt; 可参与托管构建；指向仓库外目录的本地替换路径则不可用。&lt;/p&gt;</description></item><item><title>02 项目结构与源码入口</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/partial-architecture/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/partial-architecture/</guid><description>&lt;h2 id="页面入口"&gt;页面入口&lt;/h2&gt;&#10;&lt;p&gt;以下路径相对 &lt;code&gt;module/&lt;/code&gt;。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;目录或入口&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;职责&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/baseof.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;页面整体装配&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/page-*.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;内容选择的页面布局&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;入口私有模板、功能模板与系统机制&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_shortcodes/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;正文短代码&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_markup/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Markdown 渲染&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/rss.xml&lt;/code&gt;、&lt;code&gt;sitemap.xml&lt;/code&gt;、&lt;code&gt;home.llms.txt&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;订阅与站点发现输出&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/&lt;/code&gt;、&lt;code&gt;assets/css/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;浏览器行为与样式&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;&lt;code&gt;page-*&lt;/code&gt; 是布局命名，不表示 Hugo 的 page 类型。集合布局用于普通栏目；首页另支持汇总图片墙。当前没有 taxonomy 和 term 的列表布局。配置方法见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/collection-lists/"&gt;列表与产品声明&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="partial-所有权"&gt;Partial 所有权&lt;/h2&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;目录（相对 &lt;code&gt;layouts/_partials/&lt;/code&gt;）&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;职责&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;entry-baseof/&lt;/code&gt;、&lt;code&gt;entry-page-home/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;入口独有的装配与检查&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-browse/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;内容成员、引用、列表、图片墙和导航&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-document/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;正文、元信息、章节与文章结构化数据&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-preferences/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;语言和外观选项&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-prefetch-debug/&lt;/code&gt;、&lt;code&gt;feature-site-status/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;诊断与状态显示&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-ui/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;公共列表、图标、控件与页面样式&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-assets/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;资源定位、处理、构建与发布&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-metadata/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;SEO、分享信息和 Agent 索引&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-delivery/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;SW、预取、缓存与部署配置&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-build/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;站点构建版本与时间&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;h2 id="依赖方向"&gt;依赖方向&lt;/h2&gt;&#10;&lt;p&gt;入口组合功能与系统模块；功能模块可以使用系统模块，系统模块不反向读取功能状态。跨功能依赖保持明确、单向，例如文章元信息读取内容归属。&lt;/p&gt;&#10;&lt;p&gt;公共 UI 接收功能模块生成的字段与链接，不负责发现成员。资源构建接收调用者指定的资源，不自行读取浏览来源。SEO 消费构建期模型，不以浏览器来源作为规范路径。&lt;/p&gt;&#10;&lt;p&gt;新增代码先放在所属入口或功能附近，出现实际复用后再提取。不要为目录对称增加空层或转发模板。&lt;/p&gt;&#10;&lt;h2 id="功能内部边界"&gt;功能内部边界&lt;/h2&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;重要约定&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;源码入口（相对 &lt;code&gt;layouts/_partials/&lt;/code&gt;）&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;列表、计数、RSS 与反向引用共用成员索引&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-browse/directory/index.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;引用不创建页面，不改变 Parent 与正文网址&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-browse/directory/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;结构路径与浏览来源分别维护&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;feature-browse/navigation/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;资源定位与发布分开，衍生图不必额外发布源图&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-assets/resolve-page.html&lt;/code&gt;、&lt;code&gt;publish-page.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;共享列表只装配公共控件&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;system-ui/list/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;内联脚本与 CSP 使用同一份最终正文&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;entry-baseof/inline-scripts.html&lt;/code&gt;、&lt;code&gt;system-delivery/deployment/csp-value.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;站点发现使用实际发布页面；引用不会产生新的规范地址。LLMS 可以把同一正文列入真实栏目和引用栏目，规则见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/discovery/"&gt;站点发现&lt;/a&gt;。&lt;/p&gt;</description></item><item><title>发布 · 主题版本</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/releasing/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/releasing/</guid><description>&lt;h2 id="变更记录"&gt;变更记录&lt;/h2&gt;&#10;&lt;p&gt;在 Banyan 仓库的 &lt;code&gt;content/articles/changelog/unreleased/index.md&lt;/code&gt;&#10;及其中文译文记录用户可见的变化、配置要求和实际修复。&#10;合并同类条目，不记录内部重构、测试细节或仅属于消费站点的变化。首次发布说明主要能力、使用要求和已知限制，不列开发期旧格式的迁移历史。后续版本只记录相对上一发布版的用户变化；需要操作时，说明受影响配置和处理步骤。&lt;/p&gt;&#10;&lt;p&gt;发布时将该 bundle 移至 Banyan 仓库的&#10;&lt;code&gt;content/articles/changelog/vX.Y.Z/&lt;/code&gt;，把 &lt;code&gt;title&lt;/code&gt; 设为 &lt;code&gt;vX.Y.Z&lt;/code&gt;、&#10;&lt;code&gt;url&lt;/code&gt; 设为 &lt;code&gt;p/vX.Y.Z/&lt;/code&gt;，把 &lt;code&gt;date&lt;/code&gt; 和 &lt;code&gt;lastmod&lt;/code&gt; 设为发布日期。&#10;新建 unreleased bundle，将 &lt;code&gt;date&lt;/code&gt; 和 &lt;code&gt;lastmod&lt;/code&gt; 设为新页面的首次发布日期；“未发布”指软件版本状态。集合布局会自动列出版本页面。&#10;版本说明发布在 &lt;code&gt;https://banyan.swaw.com/p/vX.Y.Z/&lt;/code&gt;，中文在&#10;&lt;code&gt;https://banyan.swaw.com/zh/p/vX.Y.Z/&lt;/code&gt;；内容目录移动不改变这些正文网址。&lt;/p&gt;&#10;&lt;h2 id="配套标签"&gt;配套标签&lt;/h2&gt;&#10;&lt;p&gt;在 Banyan 仓库更新 Skill 的 &lt;code&gt;metadata.version&lt;/code&gt; 和 &lt;code&gt;module/theme.toml&lt;/code&gt; 的 &lt;code&gt;version&lt;/code&gt;，&#10;使用同一本次版本号，将源码、文档和版本说明提交到同一个 Banyan 提交。&#10;两个发布标签都创建在 Banyan 仓库，指向该提交。&lt;/p&gt;&#10;&lt;p&gt;进入 Banyan 仓库根目录后执行。命令从当前提交读取版本，校验 Theme、Skill&#10;版本和 Module 标识，再向 &lt;code&gt;origin&lt;/code&gt; 原子发布配套标签：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban deploy/release/tag --check #校验并查看标签计划&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban deploy/release/tag #原子发布两个版本标签&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;命令读取已提交的版本文件。运行前提交本次源码和文档，并用 &lt;code&gt;--check&lt;/code&gt; 核对版本与目标仓库。&lt;/p&gt;&#10;&lt;p&gt;以版本 &lt;code&gt;0.1.0&lt;/code&gt; 为例，&lt;code&gt;v0.1.0&lt;/code&gt; 用于项目发布和提取 Skill；&#10;&lt;code&gt;module/v0.1.0&lt;/code&gt; 供 Go 将子目录 Module 识别为 &lt;code&gt;v0.1.0&lt;/code&gt;。&#10;因为 Module 根目录是 &lt;code&gt;module/&lt;/code&gt;，仅有项目标签不能提供该 Module 的语义版本。&#10;这是 &lt;a href="https://go.dev/ref/mod#vcs-version"&gt;Go 的子目录 Module 标签规则&lt;/a&gt;。&#10;GitHub Release 使用 &lt;code&gt;v0.1.0&lt;/code&gt;，无需再为 &lt;code&gt;module/v0.1.0&lt;/code&gt; 创建 Release。&#10;若附带 Skill ZIP，包含 Skill 目录和许可证，排除 &lt;code&gt;.tools&lt;/code&gt;、&lt;code&gt;node_modules&lt;/code&gt; 和缓存。&lt;/p&gt;</description></item><item><title>检查 · Service Worker 回归</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/service-worker-regression-checklist/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/service-worker-regression-checklist/</guid><description>&lt;p&gt;配置方法见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/delivery/"&gt;交付与缓存&lt;/a&gt;。本文用于修改 SW 实现后的检查，不重复配置表与命令参数。&lt;/p&gt;&#10;&lt;h2 id="源码入口"&gt;源码入口&lt;/h2&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;位置（相对 &lt;code&gt;module/&lt;/code&gt;）&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;职责&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/system-delivery/pwa/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;配置、离线页和程序资源装配&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/pwa/worker-enable.js.tmpl&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;缓存、程序生命周期和站点构建版本&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/pwa/manager-entry.js.tmpl&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;普通页面注册&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/site-status/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;Powered by 的程序与内容检查&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/pwa/worker-disable.js&lt;/code&gt;、&lt;code&gt;manager-disable.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;停用与清理&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/pwa/cache-names.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;受管缓存名称&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;h2 id="页面与程序更新"&gt;页面与程序更新&lt;/h2&gt;&#10;&lt;p&gt;普通页面加载完成后注册，预渲染页面在激活后注册。浏览器负责正常程序更新与激活；页面链接、刷新、历史导航和检查按钮不能提前激活 waiting 程序，也不能自动重载页面。&lt;/p&gt;&#10;&lt;p&gt;检查首次安装、存在活动程序时的更新、等待期间的内容更新，以及停用后重新启用。首次安装须取得有效站点构建版本和默认语言离线页；后续更新须保留有效离线回退。安装与激活期间的暂存处理以 worker 源码及生命周期测试为准。&lt;/p&gt;&#10;&lt;h2 id="站点构建版本"&gt;站点构建版本&lt;/h2&gt;&#10;&lt;p&gt;站点构建版本与 SW 程序版本分别变化。只改内容版本时，&lt;code&gt;sw.js&lt;/code&gt; 字节应保持不变。版本 JSON 须与内容一同部署；手动设置 &lt;code&gt;params.build.version&lt;/code&gt; 时，每次内容发布都要更新它。&lt;/p&gt;&#10;&lt;p&gt;达到检查间隔后的首次受管导航应启动后台检查，不等待导航成功，不阻塞导航响应；并发导航共用一次请求。失败时保留原版本。waiting 程序存在时，活动程序仍可检查内容。&lt;/p&gt;&#10;&lt;p&gt;发现新构建版本后，后续请求使用新缓存；已打开页面保持原状。版本切换清理旧版本缓存，保留指纹缓存。旧请求完成时不能重新创建已删除的缓存。&lt;/p&gt;&#10;&lt;h2 id="缓存契约"&gt;缓存契约&lt;/h2&gt;&#10;&lt;p&gt;缓存与 HTTP 响应头分别配置。版本缓存未命中时重新验证 HTTP 缓存，避免旧 HTML 写入新版本缓存。&lt;code&gt;sw.js&lt;/code&gt; 与 &lt;code&gt;sw-version.json&lt;/code&gt; 不进入页面或资源缓存桶。&lt;/p&gt;&#10;&lt;p&gt;首次访问尚未受 SW 控制，页面不追加缓存预热。受控导航缓存 HTML 并预热同源指纹资源。检查已缓存页面离线访问，以及未缓存页面的语言回退。&lt;/p&gt;&#10;&lt;h2 id="disable-模式"&gt;disable 模式&lt;/h2&gt;&#10;&lt;p&gt;&lt;code&gt;disable&lt;/code&gt; 使用独立的清理程序注销本站 SW，删除受管缓存，保留无关缓存。&lt;code&gt;off&lt;/code&gt; 不执行清理。正常更新不能调用停用流程。&lt;/p&gt;&#10;&lt;h2 id="自动化场景"&gt;自动化场景&lt;/h2&gt;&#10;&lt;p&gt;对已启用 SW 的生产构建运行代表检查；停用另行提供启用与停用两份实际构建：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site &amp;lt;build&amp;gt; --updates #检查代表页面与 SW 更新&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/pwa/disable &amp;lt;enabled&amp;gt; --next &amp;lt;disabled&amp;gt; #检查停用&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/http/security &amp;lt;url&amp;gt; #部署后检查响应头&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;准备方式、单项任务、页面要求和报告范围统一见 Skill 的&lt;a href="https://github.com/SwawHQ/banyan/blob/main/.agents/skills/swaw-banyan/references/browser-site.md"&gt;浏览器检查&lt;/a&gt;。两个实际代码版本的比较应使用实际构建对；临时生成的更新构建只用于检查更新机制。&lt;/p&gt;</description></item><item><title>检查 · 浏览器检查</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/browser-regression/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/browser-regression/</guid><description>&lt;p&gt;在目标站点根目录调用已安装的 &lt;code&gt;swban.cmd&lt;/code&gt;。参数、默认值和页面要求以任务的&#10;&lt;code&gt;--help&lt;/code&gt; 为准，检查范围见 Skill 的&lt;a href="https://github.com/SwawHQ/banyan/blob/main/.agents/skills/swaw-banyan/references/browser-site.md"&gt;浏览器说明&lt;/a&gt;。&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban base/browser/ensure #准备 Chromium&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site &amp;lt;build&amp;gt; #检查代表页面&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site &amp;lt;build&amp;gt; --updates #检查 SW 更新&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site &amp;lt;build&amp;gt; --updates --site &amp;lt;source&amp;gt; #指定更新构建源码&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site &amp;lt;build&amp;gt; --trace --out &amp;lt;report&amp;gt; #保存报告和 trace&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/pwa/disable &amp;lt;enabled&amp;gt; --next &amp;lt;disabled&amp;gt; #检查 SW 停用&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/csp &amp;lt;build&amp;gt; --page &amp;lt;path&amp;gt; #检查指定页面 CSP&#10;&lt;/span&gt;&lt;/span&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;swban check/browser/site --help #查看参数&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;检查服务已完成的构建，并应用其生成的 &lt;code&gt;_headers&lt;/code&gt;。报告列出所选路径、失败项和&#10;跳过范围；代表页面检查不覆盖每个页面或全部任务。普通 UI 检查阻止 SW，&#10;需要实际 worker 的 PWA 和预取检查单独启用。&lt;/p&gt;&#10;&lt;p&gt;检查会自动识别部署子目录和默认语言首页，无需为检查临时修改 &lt;code&gt;baseURL&lt;/code&gt; 或语言设置。单页检查的 &lt;code&gt;--page&lt;/code&gt; 使用实际访问路径，例如 &lt;code&gt;/blog/zh/p/example-product/&lt;/code&gt;。SW 停用检查也使用实际部署范围；未指定 &lt;code&gt;--page&lt;/code&gt; 时自动选择语言首页。&lt;/p&gt;</description></item><item><title>约定 · UI 命名与职责</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/ui-naming/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/ui-naming/</guid><description>&lt;p&gt;概念名称见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/glossary/"&gt;项目术语表&lt;/a&gt;。本文用于定位 UI 源码；配置示例见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/articles/docs-guide/"&gt;使用指南&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="公共页面列"&gt;公共页面列&lt;/h2&gt;&#10;&lt;p&gt;文档承载横向画幅，各页面列独立纵向滚动。根导航列、面包屑列、主内容列和文档辅助列使用同一布局体系；DOM 顺序与阅读顺序保持一致。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;module/assets/css/page-shell.css&lt;/code&gt; 负责列尺寸、滚动和打印布局，&lt;code&gt;breadcrumb-navigation.css&lt;/code&gt; 与 &lt;code&gt;document-aside.css&lt;/code&gt; 负责各自列内呈现。正文表格和代码的局部滚动不作为页面列。&lt;/p&gt;&#10;&lt;p&gt;修改面包屑列时，保留已有滚动容器，避免重置画幅。实现入口为 &lt;code&gt;module/assets/js/browse/breadcrumb-render.js&lt;/code&gt;；首帧位置与历史边界见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/breadcrumb-models/#%e5%b8%83%e5%b1%80%e4%b8%8e%e7%bb%b4%e6%8a%a4%e8%be%b9%e7%95%8c"&gt;面包屑导航模型&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="样式类与行为标记"&gt;样式类与行为标记&lt;/h2&gt;&#10;&lt;p&gt;样式类表达呈现，&lt;code&gt;data-*&lt;/code&gt; 表达脚本行为，ARIA 表达可访问语义。修改其中一类时，核对另外两类及共享片段读取端。&lt;/p&gt;&#10;&lt;p&gt;公共列表与完整条目由 &lt;code&gt;module/layouts/_partials/system-ui/list/&lt;/code&gt; 提供。功能模块决定成员、字段和链接，公共组件只负责装配。根导航、主列表、选择列表与共享导航片段复用条目组件。&lt;/p&gt;&#10;&lt;p&gt;链接与按钮保持原生控件，保留键盘操作、焦点和可访问名称。选择列表与可排序列表使用各自功能入口，不把业务判断放入公共控件。&lt;/p&gt;&#10;&lt;h2 id="css-源码与发布名"&gt;CSS 源码与发布名&lt;/h2&gt;&#10;&lt;p&gt;CSS 按视觉职责命名，不复制模板目录层级。源码职责与发布资源可以不同；依赖和合并顺序直接读取构建入口，避免另维护一份文件清单。&lt;/p&gt;&#10;&lt;p&gt;以下路径相对 &lt;code&gt;module/&lt;/code&gt;。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;修改内容&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;入口&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;公共样式与配色装配&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/css/page.css&lt;/code&gt;、&lt;code&gt;layouts/_partials/system-ui/page-styles.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;页面画幅与列尺寸&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/css/page-shell.css&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;列表字段、控件与图标&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/css/list-layout.css&lt;/code&gt;、&lt;code&gt;item.css&lt;/code&gt;、&lt;code&gt;icons.css&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;正文样式&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/css/prose.css&lt;/code&gt;、&lt;code&gt;layouts/_partials/feature-document/styles.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;元信息与章节目录&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-document/&lt;/code&gt;、&lt;code&gt;assets/css/document-aside.css&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;共享面包屑 HTML&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-browse/navigation/source/fragment.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;共享片段校验与显示&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/browse/breadcrumb-source.js&lt;/code&gt;、&lt;code&gt;breadcrumb-render.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;语言与外观选项&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-preferences/&lt;/code&gt;、&lt;code&gt;assets/js/preferences/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;站点状态控件&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_shortcodes/site-status.html&lt;/code&gt;、&lt;code&gt;assets/js/site-status/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;首页艺术包装配&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/page-home.html&lt;/code&gt;、&lt;code&gt;layouts/_partials/entry-page-home/&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;配色与艺术包由站点维护，修改方法见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/appearance-customization/"&gt;配色与首页定制&lt;/a&gt;。浏览来源与排序只在&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/navigation-state/"&gt;导航状态协议&lt;/a&gt;中定义；不要用 UI 命名或样式类替代该协议。&lt;/p&gt;</description></item><item><title>约定 · 导航状态协议</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/navigation-state/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/navigation-state/</guid><description>&lt;p&gt;内容归属由内容树决定，本次浏览状态由网址保存。发布网址不能用来推断内容归属。构建模型见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/breadcrumb-models/"&gt;面包屑导航模型&lt;/a&gt;，页面配置见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/layout-slots/"&gt;页面区域与布局&lt;/a&gt;。&lt;/p&gt;&#10;&lt;h2 id="url-状态"&gt;URL 状态&lt;/h2&gt;&#10;&lt;p&gt;&lt;code&gt;from&lt;/code&gt;、&lt;code&gt;sorts&lt;/code&gt; 和 &lt;code&gt;anchor&lt;/code&gt; 放在 URL 片段中，不进入 HTTP 或 SW 缓存地址。真实查询参数仍保留在 &lt;code&gt;?&lt;/code&gt; 后。&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" class="chroma"&gt;&lt;code class="language-text" data-lang="text"&gt;&lt;span class="line"&gt;&lt;span class="cl"&gt;/p/example-product/#from=products/examples&amp;amp;sorts=_,name-desc&amp;amp;anchor=installation&#10;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;h3 id="from"&gt;&lt;code&gt;from&lt;/code&gt;&lt;/h3&gt;&#10;&lt;p&gt;表示文章浏览来源，指向栏目内容路径，不指向文章。有效来源必须由页面索引提供，且对应栏目包含当前文章；无效来源回到文章默认归属。&lt;/p&gt;&#10;&lt;p&gt;来源只改变根入口选中项和面包屑列，不改变正文、规范地址或完整根入口列表。栏目与汇总列表使用自身路径，不保留冗余的 &lt;code&gt;from&lt;/code&gt;。&lt;/p&gt;&#10;&lt;h3 id="sorts"&gt;&lt;code&gt;sorts&lt;/code&gt;&lt;/h3&gt;&#10;&lt;p&gt;按当前有效内容路径从根级记录各栏目排序，包含主列表。根导航列、语言前缀和文章本身不占排序位置。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;_&lt;/code&gt; 表示对应栏目的默认排序；缺少的尾项也使用各自默认值。生成链接时省略尾部默认项，保留中间占位。每列只更新自己的排序，不增加历史记录。普通点击和新标签打开须得到相同状态。&lt;/p&gt;&#10;&lt;p&gt;排序状态按栏目保存。栏目链接保留祖先状态，不将当前排序复制到子栏目；未指定状态的栏目读取自己的默认排序。&lt;/p&gt;&#10;&lt;h3 id="章节与历史"&gt;章节与历史&lt;/h3&gt;&#10;&lt;p&gt;只有章节时使用原生 &lt;code&gt;#installation&lt;/code&gt;；与导航状态并存时使用 &lt;code&gt;anchor=installation&lt;/code&gt;。排序不触发章节重新定位，正文滚动不改写网址。历史恢复交给浏览器，不在导航协议中保存滚动位置。&lt;/p&gt;&#10;&lt;h3 id="系统页面与返回"&gt;系统页面与返回&lt;/h3&gt;&#10;&lt;p&gt;语言、外观等页面使用普通链接，返回使用浏览器历史，不另存原阅读网址。无上一条历史时返回当前语言首页。&lt;/p&gt;&#10;&lt;p&gt;语言选择替换当前设置页历史。返回内容时，优先打开所选语言的真实译文；缺少译文时保留原内容并显示说明。这次选择只作用于当前标签页的一次返回，不成为全站语言偏好。会话存储不可用时，普通链接和返回仍可用。&lt;/p&gt;&#10;&lt;h2 id="源码入口"&gt;源码入口&lt;/h2&gt;&#10;&lt;p&gt;以下路径相对 &lt;code&gt;module/assets/js/&lt;/code&gt;。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;修改内容&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;入口&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;片段字段与章节读写&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;browse/navigation-state.contract.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;内容路径与排序位置&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;browse/navigation-state.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;选择有效来源&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;browse/navigation-source.js&lt;/code&gt;、&lt;code&gt;breadcrumb-controller.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;链接生成与排序刷新&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;browse/breadcrumb-links.js&lt;/code&gt;、&lt;code&gt;breadcrumb-sort.js&lt;/code&gt;、&lt;code&gt;collection-sort.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;章节定位&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;document/anchors.js&lt;/code&gt;、&lt;code&gt;document/toc.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;设置页返回与译文选择&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;pages/back.js&lt;/code&gt;、&lt;code&gt;preferences/language-page.js&lt;/code&gt;、&lt;code&gt;preferences/language-return.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;列索引与共享片段的构建入口见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/breadcrumb-models/#%e9%9d%a2%e5%8c%85%e5%b1%91%e6%a8%a1%e5%9e%8b"&gt;面包屑模型&lt;/a&gt;。修改协议时，同时核对构建端、浏览器端及&lt;a href="https://github.com/SwawHQ/banyan/blob/main/tests/README.md"&gt;导航检查&lt;/a&gt;。&lt;/p&gt;</description></item><item><title>约定 · 面包屑导航模型</title><link>https://f6e67316.banyan-git-test.pages.dev/zh/p/breadcrumb-models/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0800</pubDate><guid>https://f6e67316.banyan-git-test.pages.dev/zh/p/breadcrumb-models/</guid><description>&lt;h2 id="第一列与进入路径"&gt;第一列与进入路径&lt;/h2&gt;&#10;&lt;p&gt;根导航列来自当前语言的首页和直属页面。结构根页面用于归属判断，可见入口只保留已发布 HTML 的页面；根入口可以是栏目，也可以是普通页面。&lt;/p&gt;&#10;&lt;p&gt;内容声明见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/layout-slots/"&gt;页面区域与布局&lt;/a&gt;。构建入口为 &lt;code&gt;module/layouts/_partials/feature-browse/navigation/root/&lt;/code&gt;。&lt;/p&gt;&#10;&lt;h2 id="选中规则"&gt;选中规则&lt;/h2&gt;&#10;&lt;p&gt;默认归属来自真实内容祖先。&lt;code&gt;_map.toml&lt;/code&gt; 增加引用关系，不创建新页面，也不修改原文的 Parent 或发布网址。&lt;/p&gt;&#10;&lt;p&gt;浏览来源只改变本次导航。来源有效性、排序与历史规则统一见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/navigation-state/"&gt;导航状态协议&lt;/a&gt;，不能据此改变规范地址或结构化数据中的真实路径。&lt;/p&gt;&#10;&lt;h2 id="面包屑模型"&gt;面包屑模型&lt;/h2&gt;&#10;&lt;p&gt;构建期区分路径项与列来源：路径项表示目标页面，列来源提供该级的同级条目。Hugo Page 只用于构建，不传入浏览器。&lt;/p&gt;&#10;&lt;p&gt;根导航、主列表与正文保留在页面 HTML 中。面包屑内容生成共享 HTML 片段，页面只携带所需列索引。共享片段提供内容和默认排序，不保存用户状态。&lt;/p&gt;&#10;&lt;p&gt;以下路径相对 &lt;code&gt;module/&lt;/code&gt;。&lt;/p&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;修改内容&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;入口&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;真实路径与结构面包屑&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-browse/navigation/breadcrumb/model.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;列模型与共享片段&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-browse/navigation/source/models.html&lt;/code&gt;、&lt;code&gt;fragment.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;片段发布与页面索引&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;layouts/_partials/feature-browse/navigation/source/publish.html&lt;/code&gt;、&lt;code&gt;pack.html&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;索引读取与来源选择&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/browse/navigation-source.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;片段校验、加载与显示&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;assets/js/browse/breadcrumb-source.js&lt;/code&gt;、&lt;code&gt;breadcrumb-controller.js&lt;/code&gt;、&lt;code&gt;breadcrumb-render.js&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;h2 id="布局与维护边界"&gt;布局与维护边界&lt;/h2&gt;&#10;&lt;p&gt;骨架须在片段加载前预留列宽。后续填充或排序复用已有容器；失败时显示说明，无效来源回到默认路径。DOM 与样式归属见&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/ui-naming/"&gt;UI 命名与职责&lt;/a&gt;。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;assets/js/browse/canvas-position.js&lt;/code&gt; 与 &lt;code&gt;assets/js/inline/canvas-position.js&lt;/code&gt; 处理同标签页进入下一文档时的横向位置。已有滚动位置、章节锚点与用户输入优先，历史恢复交给浏览器。&lt;/p&gt;&#10;&lt;p&gt;修改后按&lt;a href="https://f6e67316.banyan-git-test.pages.dev/zh/p/browser-regression/"&gt;浏览器检查&lt;/a&gt;选择来源、排序、章节、画幅和历史场景。浏览器层的下拉刷新差异仍需真机检查。&lt;/p&gt;</description></item></channel></rss>