Banyan

本地开发

Mon, 01 Jan 0001 00:00:00 +0000

仓库结构

仓库根目录是文档站点，也是本地主题 Module 的使用方。

banyan/
├── hugo.toml, go.mod #文档站点配置
├── content/docs/ #使用指南和开发资料
├── content/changelog/ #主题和 Skill 变更记录
├── data/ #站点数据
├── module/ #发布的 Hugo Module 和默认文件
├── .agents/skills/swaw-banyan/ #本地工具和检查任务
└── tests/ #主题和工具源码测试

根 go.mod 使用 replace ... => ./module，因此预览不需要已发布的 Module。站点定制留在根目录，可复用主题行为放入 module/。

预览

克隆仓库后进入根目录。下文 swban 代表 .\.agents\skills\swaw-banyan\swban.cmd，使用时按路径调用。命令行目前支持 Windows x64。直接执行预览命令；入口会复用兼容工具，并按需下载 JS 运行时、Git、Go 和 Hugo。

swban base/hugo server -D --disableFastRender --port 13241 #预览站点

打开 http://127.0.0.1:13241/。Hugo 监听本地 Module，模板和资源变化会触发重建。开发构建默认不压缩；若站点在开发环境也启用压缩，可用 --minify=false 关闭。不需要在站点安装 npm 包。工具选择和依赖位置见 Skill 使用说明。

开始使用

Mon, 01 Jan 0001 00:00:00 +0000

Banyan 分为两部分：Hugo Module 提供主题，swaw-banyan Agent Skill 提供本地工具和检查。站点内容、配置和品牌资料由使用主题的站点维护。

安装前

本项目正在准备首次发布。下面的 v0.1.0 是首发版本示例；远程安装须等对应标签发布。发布前可按 Skill 的本地 Module 示例验证临时站点，或预览本仓库。

主题要求 Hugo 0.157.0 或更新版本。Skill 命令行目前支持 Windows x64，优先复用兼容的系统工具，缺少时下载便携工具。Skill 使用 Node 运行， JS 依赖由 npm 按需准备，无需在站点根目录添加 package.json 或执行 npm install。

选择安装入口

先装 Skill： 从仓库的 v0.1.0 标签提取 .agents/skills/swaw-banyan/，放到站点的同名目录。也可使用支持指定 ref 的 Skill 安装器。让 Agent 按 Skill 配置站点并安装匹配的 Module。复制 Skill 本身不会运行命令。
已有 Module： 在站点中查看 hugo mod graph，从对应仓库标签安装 Skill。仅安装配套 Skill 不需要升级 Module。
两者均已安装： 从站点根目录运行 swban doctor。版本不匹配时，使用配套 Skill，或按计划升级 Module。

以 theme = "banyan" 加载本地主题目录时，doctor 也会检查其 theme.toml 版本；缺少版本时报告 unverified。

站点配置

Mon, 01 Jan 0001 00:00:00 +0000

根配置

在站点根 hugo.toml 中设置 baseURL、title 和语言。 Hugo 的 [outputs]、[taxonomies] 和 [permalinks] 也须由站点声明。 Banyan 提供 [outputFormats] 定义，站点仍须通过 [outputs] 启用对应输出。

保留以下设置。它防止 HTML 压缩改变用于 CSP 哈希的内联 JS：

[minify]
disableJS = true

新站点使用 Skill 的起始配置。现有站点按需合并配置，保留自己的内容和 URL 规则。

站点说明与语言

[params]
description = "Your site description."

[languages.en.params]
locale = "en_US"
icon = { text = "EN" }

[languages.zh.params]
description = "站点中文说明。"
locale = "zh_CN"

params.description 提供全站说明。各语言可用 languages.<lang>.params.description 覆盖。页面 front matter 的 description 优先于站点说明，用于 SEO 和社交卡片；llms.txt 的介绍和首页条目也使用站点说明。

locale 用于 Open Graph。可选 icon 为语言选择列表提供短标记；未设置时使用语言图标。为每种启用的语言声明根配置，并创建对应的首页和分类 bundle。

覆盖主题文件

站点中的同路径内容、资源和数据覆盖 Module 默认文件。品牌、账号和法律文本放在站点中；可复用主题行为放在 Module 中。发布的主题只包含 module/，不包含本仓库的文档内容和工具。

内容 - 全部

Mon, 01 Jan 0001 00:00:00 +0000

未发布

Tue, 20 Oct 2026 00:00:00 +0800

新增

官网提供中文使用指南和开发资料，站点生产地址为 https://banyan.swaw.com/。
通过 github.com/SwawHQ/banyan/module 发布 Hugo Module， swaw-banyan Skill 使用对应版本。doctor [目录] 检查 Module 和主题目录的版本配对、vendor 依赖及本地开发状态。主题目录的版本读取自 theme.toml。doctor 同时检查已选工具和运行时启动器；启动器或绑定文件损坏时仍可诊断，并提供手动恢复步骤。普通任务不再检查配对。检查开关和修复提示由 references/doctor.toml 维护。整仓源码 ZIP 中的 Skill 与 module/ 按 module/theme.toml 版本配对，无需 .git。修复提示包含项目地址、主题源码 ZIP 和 Module 版本调整命令。
提供 Windows x64 命令行工具，支持 Node/npm、Git、Go、Hugo 和可选的 Bun、GitHub CLI。便携版下载使用校验和验证。 uv 和 Python 3.13 在 Skill 内隔离运行脚本和 CLI，支持站点已有 uv 项目，不修改系统 PATH 或 Python 注册表。 sync/ext 和内容检查用 npm 按需准备 Skill 内的解析依赖，与父工作区隔离；站点构建不需要 npm 依赖。
新增名称列表和产品列表，复用多列导航和排序。产品分类由站点定义。
Powered by 页面显示实际主题版本、Hugo 版本、站点构建信息，以及 PWA 状态和更新检查控件。
演示站点按版本组织 content/changelog/ 下的发布记录。 params.theme_changelog 设置 Powered by 页面的变更记录地址。
浏览器检查覆盖导航、布局、语言设置、图片、预取和 PWA。支持 Chromium，部分检查支持 WebKit。check/browser/site 自动查找代表页面，并报告未检查的范围。
静态检查和 HTTP 检查覆盖内容声明、HTML、站点地图、robots、LLMS、图片、CSP、SRI、缓存响应头和预取。提供资源体积和页面数据体积报告。 HTML 检查也验证文章日期行、路径顺序、侧栏控制脚本和静态更新控件。 check/delivery 检查生成的平台格式、指纹策略一致性和发布文件名，不读取资源正文。子目录部署使用 --base-path 指定 URL 前缀；路径字符和 EdgeOne 域名重定向按平台语法处理。
sync/ext 同步声明的外部资源；deploy/edgeone/sync 同步构建生成的部署配置。
deploy/cloudflare/cli 和 deploy/cloudflare/wrangler 运行固定版本的 Cloudflare CLI，透传原生参数；各自提供 ensure [--force] 和本地 check。普通命令按需准备依赖，授权可使用各 CLI 的原生用户凭据，或 Windows 凭据管理器中的共用 API Token。原生配置、登录凭据及存储方式由 CLI 管理，可沿用系统中同一工具的已有登录。 auth/token/check 也可检查用户手工添加的凭据。修复资源名称和显式布尔参数值导致的凭据误选。 auth whoami 与资源命令使用相同的凭据优先级。 cf 和 Wrangler 命令及授权页的登录和状态检查，分别使用固定的 %TEMP%/swaw/banyan/cf/ 和 %TEMP%/swaw/banyan/wrangler/ 工作目录，保留目录及缓存。本地路径以这些目录为基准；文件参数用绝对路径， Wrangler 项目用原生 --cwd 指定绝对路径。 cf 资源管理命令使用空配置；开发和构建需要实际项目配置。
deploy/tencent/cli 在 Skill 独立环境中自动准备 uv/Python 和固定版本的 tccli，提供 ensure [--force] 与本地只读 check，透传腾讯云和 EdgeOne 原生命令。登录和凭据刷新强制校验 TLS 证书。 auth/key/check 在本机凭据缺失时返回非零退出码。配置和登录沿用 tccli 原生规则；授权页说明登录凭据明文存储，推荐使用 Windows 保管的 API 密钥。 tccli 命令及授权页的登录和状态检查使用固定的 %TEMP%/swaw/banyan/tccli/ 目录并保留缓存；本地路径用绝对路径。
deploy/auth/setup 打开 Cloudflare 和腾讯云共用的本机授权页；各平台的 auth/setup 入口直接选中对应选项卡。页面支持原生登录、 Windows 保管的 API 凭据和只读环境变量状态，显示凭据优先级、站点原色图标，并按系统语言显示中英文；标题栏可切换语言，保留输入和进度，不保存语言选择，刷新后重新按系统语言显示。授权页采用黑白灰配色，移除面板外框，保留两栏细分隔线；优先级说明放在标题下，关闭按钮放在右上角。补充说明统一放在操作区或变量表格后；登录和 API Token 说明用编号列表列出设置步骤、授权范围和凭据保存方式。进入登录授权页后后台准备工具，显示准备状态并支持重试；准备完成后检查 cf 和 Wrangler 的已有登录，以及 tccli 原生凭据是否可用；刷新或重开页面会重新检查，授权按钮即时显示请求进度。 tccli 登录与检查使用同一 profile，通过原生 STS 身份查询确认凭据可用；不区分已保存的登录和密钥，也不检查业务权限。下载和检查期间仍可设置 API Token，关闭页面会停止准备、检查和登录。页面不再自动超时；各 CLI 的授权超时保持原生规则。授权页避免使用浏览器禁用的端口。保存连接断开时，取消仍会在凭据写入完成后结束会话。窄屏上下排列，两个平台均使用 API Token 标签。腾讯云访问密钥使用 swban/tencent/default；auth/key/check 检查本机凭据是否存在。
仓库、Module 和 Skill 均包含 MIT 许可证，并保留第三方许可声明。

调整

Skill 基础工具使用 base/<tool>、base/<tool>/check 和 base/<tool>/ensure。入口使用 Node，按需准备 Node/npm 和所需工具； Bun 保留为独立工具。移除 base/ensure。 Hugo 和 Go 按需准备 Git；主题不再启用未使用的 Git 页面信息。 GitHub CLI 在使用时准备；npm 和 npx 分别使用 base/node/npm 和 base/node/npx。 Python 命令使用 base/uv/python、base/uv/python/check 和 base/uv/python/ensure；常用帮助将 uv 标为 Python 工具管理器。离线使用前，可用 base/packages/ensure 准备解析依赖；加 --force 重新安装。 doctor 只报告依赖缺失，不执行安装。浏览器准备改用 base/browser/ensure 和 base/browser/ensure.webkit。 help/en [depth|path [depth]] 和 help/zh [depth|path [depth]] 按层级列出命令和分类，支持从指定路径向下计算深度并保留完整路径，分类路径以 / 结尾，或显示指定路径的完整帮助；不带参数时显示常用命令，含构建、预览和发布示例。 help 默认使用系统语言。帮助文件格式错误时，提示文件路径及 JSON 解析原因或具体字段。

可预测的内容模型

Thu, 01 Jan 2026 00:00:00 +0800

这个页面刻意保持简短，用来验证一个干净的使用方站点能够正常渲染文章、元信息、分类链接和路径导航。

结构先于装饰

Banyan 从真实页面和 taxonomy 推导导航。页面声明自己是什么，主题负责如何呈现这些结构。

本文同时属于 AI 和开发工具两条独立标签路径，证明一篇文章无需复制内容也能进入多个分类。

Service Worker 回归检查

Mon, 01 Jan 0001 00:00:00 +0000

本清单描述当前行为。使用根站点内容构建测试。

页面与程序更新

普通页面只在 load 后注册 SW。预渲染页面等到激活后再注册。
普通页面不装配更新面板、不补缓存，也不拦截链接或发送主动激活消息。
Powered by 页面自行读取 registration，显示状态并提供手动检查。按钮只检查，不激活程序、不重载页面。
程序自动更新检查和激活交给浏览器。waiting 程序保留默认等待行为，不因站内链接、刷新或历史导航而提前激活。
浏览器激活新程序时，不额外刷新已打开页面；滚动、历史和输入内容由页面与浏览器保留。
已有活动程序时，新程序安装先准备离线页和指纹资源，不切换当前内容版本。每次安装先清空本程序的暂存，并记录当时的内容版本；缺少版本时先请求 JSON。激活时读取最终内容版本；仍无版本时，用暂存初始化。等待期间内容版本已变化时，保留当前桶已有的有效离线页，仅从暂存补齐缺失路径。内容版本未变化时，仍用暂存刷新离线页。激活不等待网络；准备失败则保留旧程序。

内容版本

站点构建版本写入固定地址 sw-version.json。仅内容版本改变时，sw.js 字节不变，不触发程序安装或激活。版本 JSON 必须与该版本内容一同部署；若手动设置 params.build.version，每次内容发布都需更新该值。

在站点的 data/delivery.toml 中设置最小检查间隔：

[service_worker]
mode = "enable"
content_check_interval = 5
offline_notice_path = "offline/"

此表整体替换模块默认值。间隔单位为分钟，默认 5 分钟。达到间隔后的首次成功导航响应会安排 15 秒后的检查；后续导航不重复安排，也不重置延迟。没有导航时不检查。JSON 请求由 SW 发出，不依赖页面通知，不阻塞导航响应。

当前内容版本与上次检查尝试时间持久保存；待执行任务仅保存在内存中。
请求超时、失败或 JSON 无效时，保留原版本；下次检查仍受最小间隔限制。
检查时间缺失、无效或晚于当前时间时，允许重新检查。
存在 waiting 程序时，活动程序仍执行内容检查。
发现新版本后，准备新缓存和离线页，再切换后续请求并清理旧内容缓存。进行中的旧版本请求不得重新创建已删除的缓存。
内容切换不刷新当前页面；新版本只影响后续请求。手动按钮仍只检查 SW 程序更新。

页面脚本边界

assets/js/pwa/manager-entry.js.tmpl 只负责注册。
assets/js/updates/page.js 只在 Powered by 页查询注册和装配面板。三语言 content/powered-by/index*.md 提供文案。
页面不创建全局 BanyanServiceWorkerManagerRuntime。
待更新程序直接读取 registration.waiting。

缓存契约

缓存路径规则只来自 data/delivery.toml。启用时，sw-policy.json 复制 sw.js 中实际使用的 path/bucket 数组，首个匹配项优先；关闭或停用时不输出副本。
navigation：cache-first，缓存名按内容版本区分。
导航缓存未命中时，HTTP 请求使用 cache: no-cache 重新验证，避免旧 HTTP HTML 写入新版 SW 缓存。
assets：cache-first，指纹资源跨版本保留。
sw.js 不进入 Cache Storage，sw-version.json 不进入内容缓存桶；两者每次请求均校验。 sw-content-state 单独保存当前版本和上次检查时间。
内容版本切换清理旧 navigation/versioned 缓存；指纹缓存跨版本保留。
首次访问发生在 SW 控制页面之前，页面不追加缓存预热。后续受控导航由 SW 缓存 HTML，并预热其中引用的指纹 CSS/JS。
未缓存页面离线时使用对应语言的离线页；缓存命中的页面离线可读。
navigation preload 保持关闭。

自动化场景

对已启用 SW 的生产构建运行 swban check/browser/site <build> --updates。脚本自动发现更新面板及相互连接的根入口，临时构建不同版本，并生成程序修订以检查 SW 更新。内容版本变化单独检查。其他位置的源码通过 --site 指定。缺少合适页面或配置时明确失败。也可以直接调用下面的独立任务，按其 --help 指定实际路径及前后两份构建：

UI 命名与职责

Mon, 01 Jan 0001 00:00:00 +0000

名称按当前职责组织，不再描述已经退役的主菜单、顶部面包屑和下拉布局。

实体	名称与位置
第一列根入口	`browse/root-navigation.js`、`feature-browse/navigation/root/model.html` 与 `root/render.html`；由真实页面的 `root_nav` 声明产生
可见路径列	`browse/path-render.js`、`path-navigation.css`；语义导航 `nav.path-navigation[data-slot="breadcrumb"]`、单列 `.path-column`
集合页面	`layouts/page-collection.html`、`feature-browse/collection/render-page.html`；列表内容由 `feature-browse/collection/render.html` 渲染
公共列表与条目	`system-ui/list/render.html` 与 `item.html` 装配完整列表和条目；`item.css` 负责控件和状态，`list-layout.css` 负责列表与固定字段宽度
文档元信息与章节目录	`document-aside.css`；负责 `.document-meta`、`.document-toc` 和辅助列内的列表条目适配，不属于正文组件
正文右侧辅助列	`page-shell.css` 控制 `.document-aside` 的尺寸与独立纵向滚动，`document-aside.css` 控制列内内容
正文中的有序／无序列表	`prose-lists.css`；只作用于正文 `ul/ol/li`
首页	`layouts/page-home.html`、`entry-page-home/model.html`、`page-home.css`；交互入口为 `js/pages/home.js`，风向袋为 `assets/page-home/windsock.svg`
区域开关	`slot_flags`、`slotFlags`；值是布尔值，不再是 fragment 来源
浏览来源与排序状态	`browse/navigation-state.js`、`browse/navigation-state.contract.js`
语言和外观偏好	`preferences/language-page.js` 仅用于选择页；`preferences/language-return.js` 与 `preferences/theme.js` 负责跨页面行为；静态选项和返回链接在模板输出
PWA 状态与检查	`updates/page.js` 查询本页 registration 并显示状态；模板为 `feature-updates/panel.html`、`feature-updates/labels.html`

内容声明

集合页统一声明 layout: page-collection。例如更新目录只显示名称：

layout: page-collection
list: name

layout 选择页面模板，list 选择列表展示；集合成员来自 Hugo 的目录／分类结构，或 aggregate 指向的集合。更名没有改变这三个职责，也没有提供 article-list 旧模板别名。根站点与模块内容使用同一命名。

Web App Manifest 与图标

Mon, 01 Jan 0001 00:00:00 +0000

Manifest

Banyan 默认生成带指纹的 web app manifest，并在渲染关键资源之后输出链接。在站点根 hugo.toml 中选择模式：

[params.web_app_manifest]
mode = "defer"

模式	行为
`link`	在 head 中较早输出链接，尽早发现 manifest
`defer`	在 head 末尾输出链接，优先发现渲染关键资源
`off`	不生成或链接 manifest

Manifest 与 SW 缓存独立配置。SW 设置见交付与缓存。

图标

源文件	用途
`static/favicon.ico`、`static/favicon.svg`	发布为根路径 favicon，供浏览器回退使用
`assets/site/pwa/favicon.svg`	页面显式链接的指纹 SVG favicon
`assets/site/pwa/icon-180.png`	Apple touch 图标
`assets/site/pwa/icon-192.png`、`icon-256.png`、`icon-512.png`	Manifest 图标

assets/site/pwa/ 中的文件由 Hugo 作为指纹资源发布。在站点根目录提供同路径、同名文件，即可覆盖主题的 favicon 和 PWA 图标。

安全策略与 CSP

Mon, 01 Jan 0001 00:00:00 +0000

生成与配置

Hugo 生成 HTML，并为已启用的平台生成 _headers 或 edgeone.json。主题 JS 由 js.Build 构建；生产构建使用 esbuild 压缩。站点根 hugo.toml 须保留：

[minify]
disableJS = true

entry-baseof/inline-scripts.html 返回内联脚本的最终正文， system-delivery/deployment/csp-value.html 从同一份正文计算 SHA-256。 HTML 压缩不能再次改写 JS，否则 CSP 哈希失效。

脚本边界

内联入口位于 module/assets/js/inline/：

theme-boot.js 同步首帧主题。
breadcrumb-pending.js、breadcrumb-skeleton.js 预留路径列。
root-navigation.js 同步根入口选中状态。
canvas-position.js 保存和恢复横向画幅。

新增内联脚本须在 entry-baseof/inline-scripts.html 注册，并使用其返回正文。自定义模板中的裸内联 JS 不会自动获得授权；优先使用外链 JS。页面差异通过 data-* 或 JSON 提供。application/json 和 application/ld+json 数据块不纳入可执行 JS 哈希。更新面板用 textContent 呈现页面文案，不把文案写入 HTML。

策略来源

默认 HTML 策略由 system-delivery/deployment/csp-value.html 声明，可执行内联 JS 使用哈希授权。外链 JS 提供 integrity。 /*.xml 使用 cache policy 中的独立 CSP，允许 RSS/XSL 样式。

布局与 partial 架构

Mon, 01 Jan 0001 00:00:00 +0000

Banyan 使用 Hugo 0.146 之后的模板目录结构。主题要求 Hugo 0.157.0 或更高版本：页面入口直接放在 layouts/，可复用模板放在 layouts/_partials/，短代码放在 layouts/_shortcodes/，Markdown render hooks 放在 layouts/_markup/。不再保留 _default/、partials/、shortcodes/ 的旧兼容目录。

页面入口

layouts/ 根目录只有 Hugo 自动选择的入口和 front matter 显式选择的页面布局：

layouts/
├─ baseof.html
├─ page-home.html
├─ page-article.html
├─ page-collection.html
├─ page-language.html
├─ page-appearance.html
├─ page-my.html
├─ page-offline.html
├─ page-prefetch-debug.html
├─ page-powered-by.html
├─ home.llms.txt
├─ robots.txt
├─ sitemap.xml
├─ 404.html
├─ _markup/
├─ _partials/
└─ _shortcodes/

内容通过 layout: page-article、layout: page-collection 等名称选择入口。page-* 是本项目为自定义 layout 采用的命名前缀，不表示 Hugo 的 page Kind；例如 page-collection 同时供 section、taxonomy 和其他需要集合呈现的页面使用。入口负责装配，不重新实现集合、导航、文章或发布算法。只有入口确实拥有私有 helper 时才建立 entry-* partial 目录；不能为了目录对称增加单行转发层。

导航状态协议

Mon, 01 Jan 0001 00:00:00 +0000

目的

这份文档只说明一件事：

当前 breadcrumb / collection browser 相关状态，应该如何理解
哪些是页面语义
哪些是运行时视图状态
哪些是构建期产物

它不是产品说明，而是后续维护时的“协议与边界备忘录”。

核心判断

当前导航体系分成 3 层：

页面语义层
- 当前页面在真实内容结构中属于哪个根入口
- breadcrumb 各层分别对应哪个 collection
页面数据层
- 当前页面把可进入来源的当前层与祖先层 collection payload 内嵌一次
运行时状态层
- 当前从哪条路径进入：from
- 当前 collection 的排序：sort
- 当前路径上每层冻结排序：sorts

不要把这 3 层混在一起。

URL 状态

from、sort、sorts 是前端视图状态，统一放在 URL 的 # 后：

/p/example/#from=d/products&sort=name-asc&sorts=_,date-desc&anchor=installation

字段名是代码协议，不再通过 navigation-state-default.toml 配置。读取和写入共用 navigation-state.contract.js。真实查询参数仍保留在 ? 后。前端不读取旧查询参数中的导航状态，也不自动迁移旧地址。

anchor 表示正文目标元素的 ID。没有其他状态时，仍使用原生 #installation。带导航状态的章节链接使用 &anchor=installation；JS 负责定位，同时保留来源和排序。滚动正文只更新目录高亮，不改写 URL。

同页片段导航通过 hashchange 更新来源列、根入口、排序和章节位置。排序控件继续使用 history.replaceState()，并主动刷新受影响的列；该接口不会触发 hashchange，也不会增加历史记录。

片段不进入 HTTP 请求，HTTP 和 SW 缓存不需要再忽略这些参数。真实查询参数仍属于缓存地址。章节和导航状态由每个标签页的 URL 保存。

发布版本

Mon, 01 Jan 0001 00:00:00 +0000

变更记录

在 content/changelog/unreleased/index.md 记录用户可见的变化、配置要求和实际修复。合并同类条目，不记录内部重构、测试细节或仅属于消费站点的变化。

发布时将该 bundle 移至 content/changelog/vX.Y.Z/index.md，把 title 和 slug 设为 vX.Y.Z，把 date 和 lastmod 设为发布日期。新建 unreleased bundle。集合布局会自动列出版本页面。

配套标签

将 SKILL.md 的 metadata.version 和 module/theme.toml 的 version 更新为同一本次版本号并提交。在同一提交上创建两个标签；下面以 0.1.0 和当前 HEAD 为例：

swban base/git tag v0.1.0 HEAD #标记项目版本
swban base/git tag module/v0.1.0 HEAD #标记 Go Module 版本
swban base/git push --atomic --no-follow-tags origin tag v0.1.0 tag module/v0.1.0 #发布两个标签

此处 swban 代表已准备的 Skill 入口。两个标签都指向整个仓库的同一提交。v0.1.0 用于项目发布和提取 Skill； module/v0.1.0 供 Go 将子目录 Module 识别为 v0.1.0。因为 Module 根目录是 module/，仅有项目标签不能提供该 Module 的语义版本。这是 Go 的子目录 Module 标签规则。 GitHub Release 使用 v0.1.0，无需再为 module/v0.1.0 创建 Release。若附带 Skill ZIP，包含 Skill 目录和许可证，排除 .tools、node_modules 和缓存。

分类法

Mon, 01 Jan 0001 00:00:00 +0000

默认模型

Banyan 推荐用两层结构组织内容：

目录树 / section：主结构，回答“它放在哪一枝上”
tags：主题分类，回答“它涉及哪些领域”

站点根配置：

[taxonomies]
tag = "tags"
tool = "tools"

tools 使用平面分类，根配置位于 content/tools/_index*.md，文章声明 tools: [free, first-party]。content/all-tools/ 以 aggregate: /tools 汇总成员；list: products 只控制价格／用途列，与分类法名称无关。具体约定见列表与产品声明。

一篇文章可以属于多条独立路径：

tags:
 - ai
 - tooling/devtools/windows

Hugo 原生把每个 taxonomy term 当成独立字符串。Banyan 约定用 / 表达路径，并在界面中把这些字符串渲染成树。

就地定义

Banyan 不提供 taxonomy 名称或渲染配置的通用兜底。每个 taxonomy 由站点自己的 branch bundle 定义：

content/<plural>/_index.<lang>.md：定义 taxonomy 根页及 Banyan 渲染参数
content/<plural>/<term>/_index.<lang>.md：定义 term 页的标题、正文和页面资源

taxonomy 必须先在站点根 hugo.toml 的 [taxonomies] 中声明。仅创建同名内容目录只会得到普通 section。

根 bundle 契约：

必须提供非空 title
可选 linkTitle 作为导航、breadcrumb、列表和文章元信息中的短名称；未填写时回退到 title
必须提供 [banyan_taxonomy]
必须显式填写 mode、article_weight、normalize、article_mode
第一列是否显示来自页面的 root_nav，顺序来自页面 weight

示例：

交付与缓存

Mon, 01 Jan 0001 00:00:00 +0000

配置来源

在站点的 data/delivery.toml 中设置交付策略，Module 默认文件为 module/data/delivery.toml。Hugo 按顶层字段替换，嵌套表不继承遗漏字段。修改某个表时复制完整的顶层表；站点声明 routes 后会替换整个默认数组， routes = [] 表示清空。运行时配置应用到所有语言。

部署平台

[platform.cloudflare.pages]
enabled = true

[platform.edgeone.makers]
enabled = true
installCommand = ""
buildCommand = "hugo --minify --gc --cleanDestinationDir"
outputDirectory = "public"
nodeVersion = "22.11.0"

声明 platform 会替换所有平台设置；未列出的平台被关闭。 Cloudflare Pages 启用时生成 _headers 和 _redirects； EdgeOne Makers 启用时生成 edgeone.json。 EdgeOne 的 hugoVersion 默认来自构建所用的 Hugo 版本，也可在平台表中指定。修改源配置，不直接编辑生成文件。

托管构建使用平台自己的 Hugo、Go 和 Git，不安装 Skill。本地构建、检查与 EdgeOne 配置同步见本地开发。

路由和 HTTP 响应头

通用规则在前，例外在后。以下只展示路由格式；编辑站点时保留所需的全部默认路由：

[[routes]]
path = "/*"
http.headers.Cache-Control = "public, max-age=900, must-revalidate"
sw.bucket = "versioned"

[[routes]]
path = "/js/*"
http.headers.Cache-Control = "public, max-age=31536000, immutable"
http.cloudflare.pages.unset = ["Cache-Control"]
sw.bucket = "fingerprinted"

[[routes]]
path = "/sw.js"
sw.bucket = "off"

path 可为精确路径，或在任意位置包含一个 *，例如 /*.xml。通配符可匹配空字符串，也可跨越 /。 SW 匹配区分大小写的 URL pathname，保留百分号编码，不含查询参数和片段；非 ASCII 路径使用编码形式。

列表与产品声明

Mon, 01 Jan 0001 00:00:00 +0000

页面的 list 只声明子项怎么展示。内容集合的成员来自页面本身的目录或 Hugo 分类关系；选择页的选项由对应布局提供。入口归属继续由真实根页面及有效 from 决定，不在内容 front matter 中写菜单。

第一列名称使用页面的 linkTitle，未声明时使用 title。语言、外观、我的的三语言主题页面直接使用无“系统－／系統－／System -”前缀的 title，入口与页内标题共用同一名称，无需重复声明 linkTitle。

第一列采用显式加入：只有根页面顶层声明布尔值 root_nav: true 才显示；未声明、false 或字符串 "true" 均不显示。首页自身也遵守该规则。此字段只对首页及其直接子页／分类根生效，不能把深层文章提升成根入口；不要放入 cascade。项目覆盖主题页面时，每种语言各自保留该声明。

入口名称和顺序由站点各语言页面的 title／linkTitle 与 weight 决定。

使用工具分类时，在站点 hugo.toml 注册 tool = "tools"，文章用 tools: [free, first-party] 归类，全部入口声明 aggregate: /tools。主题默认入口位于 content/tools/、content/all-tools/。list: products、offer、products_* 文案键与 product 图标保留通用产品展示语义，与分类法名称独立。

/d/ 不声明 root_nav。它继续渲染目录页，文章的目录来源、集合成员、排序、from 及路径列均保留。隐藏来源没有对应的第一列选中项；直接访问正文时若实际根为隐藏的 /d/，同样不选中第一列。可见入口过滤发生在 feature-browse/navigation/root/model.html，root/pages.html 保留完整结构供归属与来源模型使用；root/render.html 装配导航和公共列表。

在哪里改列表

文件（每种语言分别配置）	当前声明	列出的对象
主题 `content/d/_index.zh.md`	`list: directory`	目录的直接子目录、文章
项目 `content/d/wsl/_index.zh.md`	未声明，继承 `/d/`	WSL 目录的直接子项
项目 `content/tags/_index.zh.md`	`list: directory`	现有标签树的子项
项目 `content/tools/_index.zh.md`	`list: directory`	Hugo 的工具分类词项，包含显式空分类
上述文件的 `cascade`，目标 `kind: term`	`list: products`	每个分类的 `.Pages`，无需逐类写来源
项目 `content/all/index.zh.md`	`list: all`、`aggregate: /d`	`/d/` 下全部内容
项目 `content/all-tools/_index.zh.md`	`list: products`、`aggregate: /tools`	工具分类成员的去重并集
主题 `content/language/index.zh.md`	`list: choice`	`hugo.toml` 已启用的语言
主题 `content/appearance/index.zh.md`	`list: choice`	跟随系统、浅色、深色

比如要让 WSL 目录使用产品表，在项目 content/d/wsl/_index.zh.md 原有 front matter 内加一行：

浏览器检查

Mon, 01 Jan 0001 00:00:00 +0000

在目标站点根目录调用已安装的 swban.cmd。参数、默认值和页面要求以任务的 --help 为准，检查范围见 Skill 的浏览器说明。

swban base/browser/ensure #准备 Chromium
swban check/browser/site <build> #检查代表页面
swban check/browser/site <build> --updates #检查 SW 更新
swban check/browser/site <build> --updates --site <source> #指定更新构建源码
swban check/browser/site <build> --trace --out <report> #保存报告和 trace
swban check/browser/pwa/disable <enabled> --next <disabled> #检查 SW 停用
swban check/browser/csp <build> --page <path> #检查指定页面 CSP
swban check/browser/site --help #查看参数

检查服务已完成的构建，并应用其生成的 _headers。报告列出所选路径、失败项和跳过范围；代表页面检查不覆盖每个页面或全部任务。普通 UI 检查阻止 SW，需要实际 worker 的 PWA 和预取检查单独启用。

--updates 读取源码站点的正常配置，只覆盖构建版本，临时构建新版。源码和受检产物须来自同一站点及配置。测试两次实际代码变化时，给单项 PWA 任务传入两份构建。默认临时产物在结束时清理；报告按 --out 选择保留位置。

路径导航模型

Mon, 01 Jan 0001 00:00:00 +0000

第一列与进入路径

第一列是当前语言站点的真实根页面列表。feature-browse/navigation/root/pages.html 将 Home、Home.Pages 与直接属于 Home 的 taxonomy 根页面取并集，再按页面 weight 排序，保留完整结构供归属与来源模型使用。

feature-browse/navigation/root/model.html 从结构根页面生成可见入口，负责 root_nav: true 过滤、名称、地址、图标和默认选中状态。名称取 LinkTitle / Title，地址取 RelPermalink；build.list: local 的系统页面也可以参与。root/render.html 只装配 nav 与公共列表。

首页自身作为普通根入口，名称与图标由站点首页声明。页面不声明主菜单归属，也没有独立的菜单项目白名单。新增入口时，创建真实的根页面并设置 root_nav: true、名称和权重；新增某个入口的子项时，把它放在相应内容目录中。

选中规则

feature-browse/navigation/root/selected.html 从当前页面及真实内容祖先中找根入口，提供静态 HTML 的默认选中项。公开 URL 可以与内容路径不同，因此不能根据 URL 前缀猜所属入口。例如 content/d/products/xvenv/ 发布在 /p/xvenv/，仍属于真实目录；目录隐藏时第一列不选中。content/powered-by/ 是独立根页面，选中自己的入口，无子页路径列。

有效的 from 指向当前页面已发布的来源集合。运行时根据浏览器来源的 rootItem 调整第一列选中项，完整入口列表始终保留。从“标签”进入同一篇文章就选中“标签”，从“产品－全部”进入就选中“产品－全部”。不存在或不属于当前文章的来源不参与选中，继续使用内容祖先。系统页面选中自己的根入口，使用普通页面网址；返回按钮使用浏览器历史记录，不另存原阅读地址。语言选择后的返回行为见导航状态协议。首页作为显式根入口时选中自己；没有根入口祖先的内部页不强制选中一项。

路径模型

feature-browse/navigation/path/model.html 根据普通页面、首页或 taxonomy 的真实结构构建模型。该模型只用于构建期：

root_item：第一列应选中的根页面。
schema_items：结构化数据中的页面路径。
nodes：根页面之后的结构节点，每项为 {item, owner}。

nodes[].item 是纯路径项，owner 是提供兄弟条目的 Hugo Page；没有所属页面时为空。两者的地址含义不同。例如“WSL”项目指向 /d/wsl/，其兄弟列表来自 owner /d/。Hugo Page 不进入浏览器投影。

页面区域与布局

Mon, 01 Jan 0001 00:00:00 +0000

当前约定

第一列入口由内容树生成，页面无需声明菜单归属。slots 只控制路径和元信息是否装配；框架负责布局。正文 main 是内建区域，不通过 front matter 指向 fragment。

slots.breadcrumb 装配 shell 内的 nav.slot.path-navigation[data-slot="breadcrumb"]，其子节点是路径列。data-slot="breadcrumb" 保留区域语义；屏幕上 nav 使用 display: contents，各列直接参与 .page-shell 的横向 Grid。列尺寸和打印分组见公共页面列。

布局、路径列、集合与更新模块的命名见 UI 命名与职责。内部 slot_flags 保存区域开关，不再表示片段来源。

第一列入口

当前语言的根页面集合包含首页自身及直接子页 Home.Pages，再合并父页面为首页的 taxonomy 根页；这份结构集合完整保留，用于路径归属。第一列只显示其中顶层声明布尔值 root_nav: true 的页面，默认不显示。名称取 LinkTitle／Title，网址取 RelPermalink，顺序取页面 weight。来源变化只更新选中项，不替换可见入口列表。

入口可在自己的 front matter 中用 icon: folder 声明 SVG，或用 icon: { text: "©" } 声明字符图标；省略时使用 folder，不存在的图标会让构建失败。当前语言、外观、我的入口分别声明 language、theme、my，更新入口声明 icon: { text: "↻" }。

不能只取 Home.Sections，因为语言、外观、我的和 /all/ 入口是普通页面。
不能只取 Site.Pages，因为 build.list: local 的系统页只列在其父页集合中。
taxonomy 根需要单独合并，不能假定它们都在 Home.Pages 中。
build.list: never 的内部节点不作为入口。
weight 只需在入口本身定义，不应 cascade 到所有文章。

首页在 content/_index*.md 声明 root_nav: true、linkTitle、icon 和 weight，使用普通条目组件，正文使用 page-home。站点自己的根页面决定可见入口和文案。

预取配置

Mon, 01 Jan 0001 00:00:00 +0000

在站点的 data/delivery.toml 中配置。模块默认值在 module/data/delivery.toml。Hugo 按顶层字段替换；站点声明 [prefetch] 后，须填写完整的预取表，未填写的图标和范围不继承模块值。配置应用到所有语言。

预取按条目主图标名称和列范围匹配。Hugo 生成一份共享 CSS 选择器： Speculation Rules 直接匹配文档；自实现 JS 用同一选择器收集链接。链接不输出预取属性，导航数据不再包含预取分类。

图标与列范围

folder 表示集合入口策略，file 表示内容页面策略。这些名称是预取提示；更换条目图标也会改变策略。只匹配条目链接内的主 SVG 图标，正文装饰图标不参与图标分类。未配置图标、文字、图片和其他页面链接使用 default。

普通链接可直接输出 <a href="…">，无需调用预取专用片段或添加预取属性。图标和列范围策略读取已有条目结构：主链接带 data-list-entry，主 SVG 图标位于其直接子元素 .item-icon 中。共享列表片段负责样式、选中态和可访问属性，模板也可直接输出相同结构。

范围	含义
`root`	根导航，第 0 列
`tail`	最后的条目列；集合页为主集合列表，文章页为最右路径列表
`"root+N"`	从根导航向右 N 个条目列
`"tail-N"`	从尾列向左 N 个条目列
`all`	此图标未被其他范围覆盖的条目链接

只计算导航和集合条目列。文章正文、章节和元信息不参与编号。横向滚动不改变编号。没有路径列的文章页，根导航同时是尾列。 N 使用正整数；偏移到根导航时可匹配它，超出实际列数时不匹配。偏移键统一加引号；+ 不能用于 TOML 裸键。

重叠优先级固定为：root > tail > tail-N > root+N > all > default。例如三列页面的 root+1 和 tail-1 指向同一列，使用 tail-1。两端的明确配置优先；显式 off 阻止回落，配置声明顺序不影响结果。基础预取和预渲染分别解析。基础预取为 off 的链接不参与预渲染。两份规则各自生成互斥选择器，共用列定位方法，不需要手写选择器。

站点发现与来源链接

Mon, 01 Jan 0001 00:00:00 +0000

Sitemap

Sitemap 收录已渲染且可索引的 HTML 页面，包括 build.list: local 和 build.list: never 页面。页面 front matter 可用以下设置排除收录：

sitemap:
 disable: true

在 section bundle 使用 cascade.sitemap.disable: true，可排除该目录和后代。该设置不阻止 HTML 渲染或搜索引擎索引。 robots: noindex、robots: none、翻译占位页和 404 页自动排除，也不会进入其他页面的替代语言链接。

预览时使用 hugo server --disableFastRender 检查 sitemap 变化，快速预览可能保留旧 XML。自定义 HTML 布局须继承 Banyan 的 baseof.html，由它登记已渲染页面。

Agent 索引

多语言站点的默认语言位于根路径时，/llms.txt 为全局索引。 Banyan 同时发布 /<default-language>/llms.txt，路径形式与多语言 sitemap 一致。

各语言索引直接链接规范 HTML 页面，收录语言首页、/about/ 和 d 内容 section 的普通文章。工具页和分类索引不进入精选索引，无需为每页设置输出开关。站点说明配置见站点配置。

GitHub 来源

在站点根 hugo.toml 中指定内容仓库：