开发¶

修改 BeeWeave 本身时使用源码 checkout。

仓库结构¶

beeweave/       # Python CLI、命令适配器、应用服务和领域逻辑
  commands/     # argparse 适配与展示，使用显式注册
  setup/        # 类型化 setup 规划与执行组件
.skills/        # 源 skill 定义
bootstrap/      # 用户项目 bootstrap 模板
extensions/     # 浏览器扩展和资源
tests/          # pytest 测试
openspec/       # 提案和活跃变更规格
docs/           # MkDocs 源文档

CLI 架构¶

CLI 遵循单向依赖：

beeweave.cli -> commanding/commands -> 应用服务 -> 领域/文件系统

beeweave/cli.py 只负责创建 AppContext、解析和分发命令、执行生命周期通知，以及把预期异常映射为退出码。beeweave/commanding.py 负责友好的 parser 和稳定命令树。beeweave/commands/ 下每个模块拥有一个功能命令组，并在 commands/__init__.py 中显式注册。argparse.Namespace 不得越过命令适配层。

运行路径在 main() 执行时通过不可变 AppContext 解析。配置与 profile 规则集中在 configuration.py，Agent 与内置资源元数据集中在 catalog.py； setup 通过 SetupService 使用类型化的 SetupOptions、SetupPlan 和 SetupResult 完成编排。

人类可读命令把 Rich 和 prompt 构造委托给 ui.py。机器命令使用无装饰 serializer，并把 stdout 专用于 JSON 或纯文本负载。

CLI 契约矩阵¶

根帮助顺序固定为：setup、uninstall、upgrade、list、info、 external、profile、illustrate、graph-query、batch-plan、 graph-analyse、cache-check、cache-update、cache-hash、 ast-extract。无参数或省略 setup 直接传 setup 选项时，均路由到 setup。根版本参数为 -V、-v 和 --version。

人类可读命令契约：

setup [--vault PATH] [--profile NAME] [--project [DIR]] [--agents LIST] [--no-global] [--global-extra LIST] [--no-project-local] [--copy]。默认使用当前项目、default profile、确定性的非 TTY Agent 默认值、不选择可选 global Skill，并使用 symlink 模式。
uninstall [--agents LIST] [--project [DIR]] [--no-global] [--no-project-local] [--all] [--keep-config] [-y|--yes]。Agent 默认为 all；非 TTY 必须显式提供 --yes。
upgrade [--check]、info，以及输出逐行 Skill 名称的 list。
external install SOURCE [--skill NAME] [--path PATH] [--all] [--ref REF] [--link-project PATH]；external link SKILL [--project DIR]；external list；external info SKILL；external update [SKILL]；external remove SKILL。
profile set-default NAME；覆盖已有默认配置需要交互式输入精确确认，非交互环境拒绝覆盖。
illustrate doctor --provider PROVIDER [--project PATH] [--profile NAME] [--probe-image] [--force]；profile 默认为 default。

机器可读命令契约：

graph-query VAULT QUESTION [--top 8] [--max-read 3] [--pretty]。
batch-plan VAULT SOURCE_DIR [--max-mb 2.0] [--max-files 20] [--no-cache] [--include-code] [--pretty]。
graph-analyse VAULT [--top 20] [--pretty]。
cache-check VAULT SOURCES... [--pretty]。
cache-update VAULT SOURCE [--pages [PAGE...]] 与 cache-hash PATH。
ast-extract PATH [--pretty]。

JSON 命令输出一个 JSON 值和末尾换行；--pretty 只改变空白格式。 list 保持逐行纯文本。机器负载不得包含 banner、Rich panel、summary 或更新通知，诊断信息写入 stderr。

退出码语义固定为：成功 0，预期领域错误或拒绝操作 1，argparse 错误 2，键盘中断 130。用户错误写入 stderr。人类输出允许 Rich 样式不同，但 NO_COLOR 与非 TTY 输出必须无 ANSI 且保留相同关键字段。

增加命令¶

在所属 beeweave/commands/ 模块中增加参数注册和 handler(args, context) -> int。
将注册函数加入 commands/__init__.py 的有序 tuple。
调用应用或领域逻辑前，把复合输入转换为不可变 options；领域层返回结构化 result，再由适配层展示。
人类输出使用 ui.py，机器输出使用 serializer，并补充命令契约测试与聚焦领域测试。

不要通过重新导出旧 beeweave.cli helper 来增加行为。其未文档化常量、私有函数和 handler 属于内部 API，可发生变化；受支持的兼容面是 CLI 与持久化格式。

检查命令¶

标准本地质量检查使用 Makefile：

make format
make check

这些目标会依次运行 Ruff 格式化 / lint、mypy 类型检查和 pytest：

uv run ruff format beeweave tests
uv run ruff check beeweave tests --fix
uv run ruff format --check beeweave tests
uv run ruff check beeweave tests
uv run mypy
uv run python -m pytest

快速检查 CLI 时，也运行：

uv run bwe setup --help
uv run bwe info

测试分为三层：直接调用领域/服务的单元测试、通过 main(argv, context=...) 执行的 CLI 契约测试，以及临时文件系统集成测试。架构测试会阻止应用/领域模块反向导入 CLI 或展示层。

本地 CLI 安装¶

把当前源码 checkout 安装为开发中的 bwe 工具：

make dev-install

该命令会基于 Makefile 所在位置自动解析仓库根目录，并执行 uv tool install --reinstall --editable <repo-root>。只有需要把新安装包里的 agent skills 刷新到目标工作区时，才在之后手动运行 bwe setup。

文档¶

MkDocs 工具只属于文档开发和 CI，不属于 BeeWeave 运行时依赖：

uv sync --group docs

也可以在文档环境中用 pip 安装：

pip install "mkdocs-material>=9.6,<9.7"

本地预览：

uv run --group docs mkdocs serve

严格构建：

uv run --group docs mkdocs build --strict

生成的 site/ 是构建产物，不应该提交到 main 分支。

GitHub Pages¶

文档发布地址是 https://ptonlix.github.io/beeweave/。GitHub 仓库设置中 Pages 应配置为：

Source: Deploy from a branch
Branch: gh-pages
Folder: /root

Workflow 会从源文件构建站点，并把生成结果发布到 gh-pages 分支。

OpenSpec¶

行为或工作流变更使用 OpenSpec 管理：

openspec validate <change-name> --strict

只有在实现和验证都完成后才归档变更。