架构

BeeWeave 有两条关键边界：仓库源码文件和运行时工作区文件。

源码仓库

beeweave/       # Python CLI 和辅助逻辑
.skills/        # 源 skill 定义
bootstrap/      # Agent bootstrap 模板
extensions/     # 浏览器扩展资源
tests/          # pytest 测试
openspec/       # 提案和活跃变更
docs/           # MkDocs 源文档

Python 包提供 bwe CLI。Wheel 会把源 skills 和 bootstrap 模板作为包数据打进去，这样用户不需要克隆仓库也能安装 Agent 文件。

运行时工作区

运行时目录由 bwe setup 在用户选择的工作区创建：

project/
+-- vault/                  # 稳定 Markdown 知识库
+-- workbench/              # 捕获、素材、草稿和 inbox 内容

这些目录是用户数据，不是源码文档，也不应该提交到 BeeWeave 仓库根目录。

主要组件

• CLI 生命周期：beeweave/cli.py 创建运行上下文、分发解析后的命令、执行 横切通知并映射预期错误。
• 命令适配层：beeweave/commanding.py 与 beeweave/commands/ 定义显式 有序的 argparse 命令树、交互和结果展示。
• 运行基础设施：runtime.py、configuration.py 和 catalog.py 提供不可变 路径、profile/config 规则和类型化资源元数据。
• Setup 应用层：beeweave/setup/ 分离选择、资源定位、workspace 初始化、 安装、规划、执行和状态检查。
• Skills：.skills/wiki/ 和 .skills/workbench/ 保存安装到 Agent 的源 skill 包。
• Bootstrap：bootstrap/ 保存复制到用户工作区的 Agent 规则和说明。
• 浏览器扩展：extensions/brain-capture/ 把网页选中内容捕获到 workbench inbox。
• OpenSpec：openspec/ 在实现前记录提案、设计、规格和任务。

强制依赖方向为：

cli -> 命令适配层 -> 应用服务 -> 领域/文件系统

应用与领域代码不依赖 argparse 或终端展示。AppContext 在执行时创建， 只提供运行环境数据，不承载任意服务。人类结果通过 ui.py 展示；机器命令 只向 stdout 写入其已约定的 JSON 或纯文本负载。

设计边界

MkDocs 从 docs/ 构建本 wiki，并输出到 site/。site/ 是本地构建产物，由 CI 发布到 gh-pages，不作为 main 分支源码维护。