01 本地开发
仓库结构
Banyan 仓库维护主题、Skill、源码测试、参考站点、使用指南、开发资料和版本说明。
banyan/
├── hugo.toml, go.mod #最小演示配置
├── content/articles/ #正文、文章分类、文档和版本说明
├── content/articles/docs-guide/ #使用指南
├── content/articles/docs-dev/ #开发资料
├── content/articles/changelog/ #主题和 Skill 版本说明
├── content/articles-all/ #文章汇总
├── content/products/ #产品分类与一份引用
├── content/products-all/ #产品汇总
├── content/{appearance,language,my,rss}/ #站点自有设置和说明页
├── assets/site/ #站点资源和交付配置
├── assets/i18n/ #由项目挂载的界面字典
├── content/powered-by/ #版本信息与预取诊断
├── content/_res/ #离线页和首页艺术包
├── module/ #布局、脚本和样式,不含站点内容
├── .agents/skills/swaw-banyan/ #本地工具和通用检查任务
└── tests/ #主题和工具源码测试
Banyan 根 go.mod 使用 replace ... => ./module,直接读取随仓库提供的主题源码,无需先发布 Module。其他站点可用本地 replace 指向这份源码。
站点定制留在各站点根目录,可复用主题行为放入 Banyan 的 module/。
独立站点发布时通常固定 Module 版本。完整仓库随附的 ./module 可参与托管构建;指向仓库外目录的本地替换路径则不可用。
预览
进入要预览的站点根目录。下文 swban 代表 Banyan 仓库中的
.agents/skills/swaw-banyan/swban.cmd,从其他站点调用时使用该入口的实际路径。
命令行支持 Windows x64、Linux x64 和 macOS x64/ARM64。Linux 和 macOS 在仓库根目录使用 sh swban。首次准备工具见开始使用。Windows 可在当前终端定义入口:
function swban { & .\.agents\skills\swaw-banyan\swban.cmd @args } #从 Banyan 仓库根目录调用
swban dev #本机预览,启动时建立搜索索引
swban dev/lan #供局域网和手机预览
swban dev/pagefind.off #跳过搜索索引
swban dev -p 13241 #指定端口
swban dev -D=false #不包含草稿
默认打开 http://127.0.0.1:5678/。Hugo 监听本地 Module,模板和资源变化会触发完整重建和浏览器刷新。
每次启动建立一次搜索索引,修改内容后需重启命令更新索引。开发产物使用独立临时目录,退出后清理,不覆盖 public/。
dev/lan 默认监听 ::,系统支持时同时接收 IPv4。手机使用电脑的局域网地址和端口访问;可用 --bind 0.0.0.0 仅监听 IPv4。
追加的参数传给 Hugo,并覆盖对应默认值。启动日志显示实际命令,保留 Hugo 和 Pagefind 输出。
开发构建默认不压缩;若站点在开发环境也启用压缩,可用 --minify=false 关闭。
不需要在站点安装 npm 包。工具选择和依赖位置见
Skill 使用说明。
构建与检查
下面使用的 <build>、缓存、资源和报告均放在系统临时目录的
swaw/banyan/<task>/。缓存和资源可通过 HUGO_CACHEDIR 和
HUGO_RESOURCEDIR 设置。完成后只清理本任务的过程文件,保留 CLI 固定目录与缓存。
swban build --destination <build> #生产构建与搜索索引
swban check/delivery <build> #检查交付配置与发布路径
swban check/csp <build> #检查 CSP 和脚本完整性
swban check/sri <build> #检查资源 integrity
swban check/html/metadata <build> #检查页面元数据
swban check/html/styles <build> #检查样式契约
swban check/llms <build> #检查 Agent 索引
swban report/size/html <build> --top 5 #报告最大 HTML 页面
swban report/size/assets <build> #报告资源体积
按改动选择检查。检查违反契约时返回非零退出码;体积报告独立输出测量值。
产物任务默认读取 public/,第一个参数可指定其他目录。
安装或调整主题、工具后,运行 swban doctor;普通任务不检查版本配对。
内容字段和响应式图片检查读取 Hugo 解析后的配置。
用 swban help 查找任务,用 swban <command> --help 查看参数。
浏览器检查需要先运行 swban base/browser/ensure,见浏览器检查。
源码测试和故障 fixture 留在 Banyan 仓库,见
tests/README.md。
消费站点的业务文案、账号和专用路由预期留在各自仓库测试中。
同步与部署准备
swban sync/ext #同步全部外部资源
swban sync/ext <resource-id> #按声明 id 同步外部资源
swban help/zh deploy #查看各平台的部署准备方案
外部资源由站点的 assets/site/external-resources.yaml 声明;演示站点默认为空列表。
下载目标 target 相对站点根:全站资源放 assets/site/,正文资源放 content/<页面>/ 内容包。
同步任务自带依赖,不需要站点执行 npm install。
EdgeOne 部署方式见
EdgeOne 说明。
Banyan 参考站点部署在 https://banyan.swaw.com/;文档入口为
https://banyan.swaw.com/articles/docs-guide/,版本说明入口为
https://banyan.swaw.com/articles/changelog/。构建时保留各站点自己的 baseURL。
下一步
参考站点运行后,阅读02 项目结构与源码入口,定位要修改的模块。