From cbf0c0f7f9febcf4d3de390a0662764d46729bec Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 23 Apr 2026 05:00:04 +0800 Subject: [PATCH 1/2] docs: polish getting-started Signed-off-by: Chojan Shang --- README.md | 4 +- website/AGENTS.md | 4 +- .../docs/getting-started/equip-your-bub.mdx | 94 +++++++++++++++ .../docs/getting-started/first-plugin.mdx | 111 ++++++++++++++++++ .../docs/docs/getting-started/index.mdx | 59 +++++++++- .../docs/getting-started/installation.mdx | 27 ----- .../docs/getting-started/run-bub-locally.mdx | 97 +++++++++++++++ .../docs/getting-started/equip-your-bub.mdx | 94 +++++++++++++++ .../docs/getting-started/first-plugin.mdx | 111 ++++++++++++++++++ .../docs/zh-cn/docs/getting-started/index.mdx | 57 ++++++++- .../docs/getting-started/installation.mdx | 27 ----- .../docs/getting-started/run-bub-locally.mdx | 97 +++++++++++++++ 12 files changed, 712 insertions(+), 70 deletions(-) create mode 100644 website/src/content/docs/docs/getting-started/equip-your-bub.mdx create mode 100644 website/src/content/docs/docs/getting-started/first-plugin.mdx delete mode 100644 website/src/content/docs/docs/getting-started/installation.mdx create mode 100644 website/src/content/docs/docs/getting-started/run-bub-locally.mdx create mode 100644 website/src/content/docs/zh-cn/docs/getting-started/equip-your-bub.mdx create mode 100644 website/src/content/docs/zh-cn/docs/getting-started/first-plugin.mdx delete mode 100644 website/src/content/docs/zh-cn/docs/getting-started/installation.mdx create mode 100644 website/src/content/docs/zh-cn/docs/getting-started/run-bub-locally.mdx diff --git a/README.md b/README.md index 6e49fba5..30d186cd 100644 --- a/README.md +++ b/README.md @@ -123,8 +123,8 @@ Bub is shaped by one constraint: real collaboration is messier than a solo demo. Read more: -- [Why We Rewrote Bub](https://bub.build/posts/2026-04-07-why-we-rewrote-bub/) -- [Socialized Evaluation and Agent Partnership](https://bub.build/posts/2026-03-01-bub-socialized-evaluation-and-agent-partnership/) +- [Why We Rewrote Bub](https://bub.build/posts/why-rewrite-bub/) +- [Socialized Evaluation and Agent Partnership](https://bub.build/posts/socialized-evaluation/) - [Context from Tape](https://tape.systems) ## Docs diff --git a/website/AGENTS.md b/website/AGENTS.md index 5d201a91..73d38e75 100644 --- a/website/AGENTS.md +++ b/website/AGENTS.md @@ -137,8 +137,8 @@ The site has **three distinct i18n zones**. Each zone has its own translation me Follows the **exact pattern** from [`withastro/starlight/docs`](https://github.com/withastro/starlight/tree/main/docs). **Locale configuration** — `astro.config.mjs`: -- English is the **`root` locale** — content files live under `src/content/docs/docs/` (e.g., `docs/getting-started/installation.md`). -- Other locales get **subdirectories**: `src/content/docs/zh-cn/docs/getting-started/installation.md`. +- English is the **`root` locale** — content files live under `src/content/docs/docs/` (e.g., `docs/getting-started/run-bub-locally.mdx`). +- Other locales get **subdirectories**: `src/content/docs/zh-cn/docs/getting-started/run-bub-locally.mdx`. - The inner `docs/` directory creates the `/docs/` URL prefix — Starlight 0.38 has no `routePrefix` option, so this nesting is the standard way to namespace docs routes. - This keeps the URL scheme consistent: `/docs/…` for docs, `/posts/…` for blog. diff --git a/website/src/content/docs/docs/getting-started/equip-your-bub.mdx b/website/src/content/docs/docs/getting-started/equip-your-bub.mdx new file mode 100644 index 00000000..8f81f5b8 --- /dev/null +++ b/website/src/content/docs/docs/getting-started/equip-your-bub.mdx @@ -0,0 +1,94 @@ +--- +title: Equip Your Bub +description: Add workspace instructions, project skills, and only the contrib plugins your Bub workspace actually needs. +sidebar: + order: 2 +--- + +Use this page after [Run Bub Locally](/docs/getting-started/run-bub-locally/). It shows how to make one workspace more useful without changing Bub itself. + +You will add three things: + +1. durable workspace rules in `AGENTS.md` +2. reusable project procedures in `.agents/skills` +3. optional runtime extensions installed as plugins + +## 1. Add workspace rules + +Update `AGENTS.md` so the agent has a stable operating policy for this repository: + +```markdown +You are the Bub agent for this workspace. +Read code before proposing changes. +Prefer small, reviewable patches. +Report verification steps explicitly. +``` + +Bub reads this file on every turn, so the same rules apply every time. + +Because Bub follows [agents.md](https://agents.md/), an existing `AGENTS.md` file from another compatible setup is often a good starting point. + +## 2. Add a project skill + +Create one project-local skill under `.agents/skills`: + +```bash +mkdir -p .agents/skills/repo-map +cat > .agents/skills/repo-map/SKILL.md <<'EOF' +--- +name: repo-map +description: Read the local repository layout before changing code. +--- + +1. Start with `rg --files` to see the repository shape. +2. Open the smallest set of files that explains the task. +3. Summarize the modules you touched before editing code. +EOF +``` + +Verify that Bub discovers it: + +```bash +uv run bub run ",skill name=repo-map" +``` + +Project skills in `.agents/skills` are loaded before user-level or builtin skills, so local procedures win by default. + +Bub follows the [Agent Skills](https://agentskills.io/) format. If you already maintain skills for another compatible agent, you can usually reuse those skill directories here. + +## 3. Install one extension + +Use plugins for extra capabilities such as tape stores and channels. + +If you want to see what is already available, check [hub.bub.build](https://hub.bub.build/). It collects Bub plugins and skills that you can reuse before writing your own. + +Use `bub install` to add only the capability you want: + +```bash +uv run bub install bub-tapestore-sqlite@main +uv run bub install bub-wechat@main +``` + +The main behavior to know is: + +- Bub keeps plugin dependencies in a managed uv project under `~/.bub/bub-project` +- `name@ref` resolves a package from `bub-contrib` at `packages/` +- the active environment gets the plugin entry points, so the next Bub run can load them + +To inspect the active hook mapping after installation: + +```bash +uv run bub hooks +``` + +If a plugin provides channels through `provide_channels()`, `uv run bub gateway` will start them together with any other enabled non-`cli` channels. + +## Result + +Your workspace now has three layers: + +- `AGENTS.md` defines durable local rules +- `.agents/skills` adds reusable local procedures +- contrib plugins add optional runtime surfaces such as tape stores or channels + +Next, continue with [Build Your First Plugin](/docs/getting-started/first-plugin/) if the builtins and existing plugins are still not enough. diff --git a/website/src/content/docs/docs/getting-started/first-plugin.mdx b/website/src/content/docs/docs/getting-started/first-plugin.mdx new file mode 100644 index 00000000..d7148c83 --- /dev/null +++ b/website/src/content/docs/docs/getting-started/first-plugin.mdx @@ -0,0 +1,111 @@ +--- +title: Build Your First Plugin +description: Create a minimal Bub plugin, install it locally, and verify that it overrides the builtin runtime. +sidebar: + order: 3 +--- + +Use this page only after the builtins, your workspace files, and existing plugins are no longer enough. + +This tutorial builds a tiny local plugin that overrides Bub's model stage and echoes the incoming text. It is intentionally simple, so you can verify plugin loading without needing model credentials. + +## 1. Create the package skeleton + +```bash +mkdir bub-echo-plugin +cd bub-echo-plugin +mkdir -p src/bub_echo_plugin +touch src/bub_echo_plugin/__init__.py +``` + +Create `pyproject.toml`: + +```toml +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[project] +name = "bub-echo-plugin" +version = "0.1.0" +dependencies = ["bub"] + +[project.entry-points."bub"] +echo = "bub_echo_plugin.plugin:echo_plugin" + +[tool.hatch.build.targets.wheel] +packages = ["src/bub_echo_plugin"] +``` + +## 2. Implement the plugin + +Create `src/bub_echo_plugin/plugin.py`: + +```python +from __future__ import annotations + +from bub import hookimpl + + +class EchoPlugin: + @hookimpl + def build_prompt(self, message, session_id, state): + if hasattr(message, "content"): + return str(message.content) + if isinstance(message, dict): + return str(message.get("content", "")) + return str(message) + + @hookimpl + def run_model(self, prompt, session_id, state): + text = prompt if isinstance(prompt, str) else str(prompt) + return f"[echo:{session_id}] {text}" + + +echo_plugin = EchoPlugin() +``` + +This plugin does two things: + +- `build_prompt()` keeps the prompt equal to the original inbound text +- `run_model()` replaces the builtin model call with a deterministic echo response + +## 3. Install it into the active environment + +From the plugin directory: + +```bash +uv pip install -e . +``` + +Bub loads entry points from the active Python environment, so an editable install is enough for local development. + +## 4. Verify that Bub loads it + +Check the hook report: + +```bash +uv run bub hooks +``` + +You should see `echo` listed on both `build_prompt` and `run_model`. + +Now run one turn: + +```bash +uv run bub run "hello from plugin tutorial" +``` + +The rendered outbound should include: + +`[echo:cli:local] hello from plugin tutorial` + +## Result + +You now have: + +- a package entry point under the `bub` group +- two hook implementations that override builtin behavior +- a local editable install workflow for quick iteration + +From here, continue with [Plugins](/docs/extending/plugins/) and [Hooks](/docs/extending/hooks/) for the full plugin and hook reference. diff --git a/website/src/content/docs/docs/getting-started/index.mdx b/website/src/content/docs/docs/getting-started/index.mdx index 88ad938b..0c2cf353 100644 --- a/website/src/content/docs/docs/getting-started/index.mdx +++ b/website/src/content/docs/docs/getting-started/index.mdx @@ -1,12 +1,59 @@ --- title: Getting Started -description: Minimal path to install Bub and understand the main runtime commands. +description: Learn what Bub is, run it locally, add local rules and skills, and extend it with plugins only when needed. +sidebar: + order: 0 --- -Bub is designed to stay small at the core, so the first run is quick. +Bub is a small Python framework for building agents in shared environments. It gives you a clear turn pipeline, a simple workspace layout, and a normal Python packaging story for extensions. -- Install from PyPI or from source. -- Start an interactive session with `bub chat`. -- Run a one-shot turn with `bub run "hello"`. +If you are new to Bub, start here. This section helps you get one working setup first, then add only the pieces you actually need. -Continue with [Installation](/getting-started/installation/). +## What You Need To Know + +1. **A small core** + Bub runs each turn through a visible hook pipeline. You can replace one stage without rewriting the whole system. +2. **A shared workspace** + Put workspace instructions in `AGENTS.md` and repeatable local procedures in `.agents/skills`. +3. **Standard Python extensions** + Plugins are normal Python packages discovered through entry points. Skills can ship with plugins through regular build tooling, including PEP 517 build hooks. +4. **A migration path from other compatible tools** + Bub follows [agents.md](https://agents.md/) for workspace instructions and [Agent Skills](https://agentskills.io/) for skills. If you already use those conventions elsewhere, you can usually reuse your `AGENTS.md` file and skill directories. + +## Before You Start + +Have these ready: + +- Python 3.12+ +- `uv` +- one model access path for the model-backed step: + - an API key via `BUB_API_KEY`, or + - OAuth login via `uv run bub login openai` + +## What You Will Build + +By the end of this section, you will have: + +- one local Bub workspace +- one project skill under `.agents/skills` +- one installed extension from `bub-contrib` +- one minimal plugin package you can iterate on locally + +## Recommended Path + +1. [Run Bub Locally](/docs/getting-started/run-bub-locally/) + Install Bub, create a workspace, inspect the builtin kernel, and complete the first successful turn. +2. [Equip Your Bub](/docs/getting-started/equip-your-bub/) + Add rules in `AGENTS.md`, add one project skill, and install only the extension you actually need. +3. [Build Your First Plugin](/docs/getting-started/first-plugin/) + Create a minimal plugin package, install it locally, and verify that Bub loads its hook implementations. + +## If You Need Something Else First + +- Want the runtime model first: go to [Architecture](/docs/concepts/architecture/) +- Want command details: go to [CLI Reference](/docs/guides/cli/) +- Want to configure the builtin Telegram channel: go to [Telegram](/docs/guides/telegram/) +- Want deployment guidance: go to [Deployment](/docs/guides/deployment/) +- Want the full plugin and hook documentation: go to [Plugins](/docs/extending/plugins/) and [Hooks](/docs/extending/hooks/) + +This section is meant to get you started, not cover every option. Deployment details, full Telegram setup, and the complete plugin API stay in the Guides, Concepts, and Extending sections. diff --git a/website/src/content/docs/docs/getting-started/installation.mdx b/website/src/content/docs/docs/getting-started/installation.mdx deleted file mode 100644 index d5d7376a..00000000 --- a/website/src/content/docs/docs/getting-started/installation.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Installation -description: Install Bub from PyPI or clone the repo and run it from source. ---- - -## From PyPI - -```bash -pip install bub -``` - -## From source - -```bash -git clone https://github.com/bubbuild/bub.git -cd bub -uv sync -uv run bub chat -``` - -If you are setting up a contributor workspace rather than just running Bub from source, use `make install` instead. That also installs the website toolchain and `prek` hooks used by the repo. - -## Core commands - -- `uv run bub chat` starts the interactive CLI. -- `uv run bub run "summarize this repo"` runs a single turn through the full pipeline. -- `uv run bub gateway` starts channel listener mode. diff --git a/website/src/content/docs/docs/getting-started/run-bub-locally.mdx b/website/src/content/docs/docs/getting-started/run-bub-locally.mdx new file mode 100644 index 00000000..cb25751f --- /dev/null +++ b/website/src/content/docs/docs/getting-started/run-bub-locally.mdx @@ -0,0 +1,97 @@ +--- +title: Run Bub Locally +description: Install Bub, create a workspace, inspect the builtin kernel, and complete the first successful turn. +sidebar: + order: 1 +--- + +Use this page if you want to get Bub running before you think about skills, plugins, or deployment. + +This page assumes nothing beyond a Python environment. By the end, you will have a workspace, an `AGENTS.md` file, and one successful turn. + +## 1. Install Bub + +Pick one path: + +```bash +pip install bub +``` + +Or run from source: + +```bash +git clone https://github.com/bubbuild/bub.git +cd bub +uv sync +``` + +The commands below use `uv run bub`, so the same examples work from source and from an activated virtual environment. + +## 2. Create a workspace + +Create a directory for the agent and give it one instruction file: + +```bash +mkdir hello-bub +cd hello-bub +cat > AGENTS.md <<'EOF' +You are the Bub agent for this workspace. +Read files before editing them. +Keep replies short and specific. +EOF +``` + +Bub reads `AGENTS.md` on every turn. + +## 3. Check the builtin commands + +Before you add providers, skills, or plugins, check what Bub already gives you: + +```bash +uv run bub hooks +uv run bub run ",help" +``` + +These two commands verify two basic things: + +- hooks are loaded +- command mode works even without model credentials + +## 4. Run your first model-backed task + +Once your provider environment is configured, start an interactive session or run a one-shot task: + +```bash +uv run bub chat +uv run bub run "Summarize the purpose of this workspace." +``` + +If you want to use OpenAI Codex OAuth instead of an API key, log in first: + +```bash +uv run bub login openai +``` + +## Optional: try the builtin Telegram channel + +Telegram is built in. You do not need a plugin to use it. + +To enable it, set the token and start the channel listener: + +```bash +export BUB_TELEGRAM_TOKEN=... +uv run bub gateway --enable-channel telegram +``` + +See the [Telegram guide](/docs/guides/telegram/) for the full setup, allowlists, and deployment options. + +## Result + +You now have: + +- a local instruction file in `AGENTS.md` +- the builtin hook chain loaded +- a repeatable path for both interactive and one-shot runs +- an optional path to enable the builtin Telegram channel + +Next, continue with [Equip Your Bub](/docs/getting-started/equip-your-bub/) to add local rules, one project skill, and only the extension you actually need. diff --git a/website/src/content/docs/zh-cn/docs/getting-started/equip-your-bub.mdx b/website/src/content/docs/zh-cn/docs/getting-started/equip-your-bub.mdx new file mode 100644 index 00000000..1708d0b8 --- /dev/null +++ b/website/src/content/docs/zh-cn/docs/getting-started/equip-your-bub.mdx @@ -0,0 +1,94 @@ +--- +title: 武装你的 Bub +description: 为 Bub 工作区添加工作区指令、项目技能，以及真正需要的 contrib 插件。 +sidebar: + order: 2 +--- + +如果你已经完成[上手运行 Bub](/zh-cn/docs/getting-started/run-bub-locally/)，这一页会带你把 workspace 补完整。 + +你会加上三样东西： + +1. `AGENTS.md` 中长期稳定的本地规则 +2. `.agents/skills` 中可复用的项目流程 +3. 按需安装的运行时扩展插件 + +## 1. 添加工作区规则 + +先把 `AGENTS.md` 调整成这类仓库真正需要的工作约束： + +```markdown +You are the Bub agent for this workspace. +Read code before proposing changes. +Prefer small, reviewable patches. +Report verification steps explicitly. +``` + +Bub 每次 turn 都会读取这个文件，所以这些规则会一直生效。 + +因为 Bub 遵循 [agents.md](https://agents.md/)，如果你已经在其他兼容工具里维护了 `AGENTS.md`，这里通常可以直接复用。 + +## 2. 添加一个项目 skill + +在 `.agents/skills` 下添加一个项目级 skill： + +```bash +mkdir -p .agents/skills/repo-map +cat > .agents/skills/repo-map/SKILL.md <<'EOF' +--- +name: repo-map +description: Read the local repository layout before changing code. +--- + +1. Start with `rg --files` to see the repository shape. +2. Open the smallest set of files that explains the task. +3. Summarize the modules you touched before editing code. +EOF +``` + +验证 Bub 能否发现它： + +```bash +uv run bub run ",skill name=repo-map" +``` + +加载器会优先读取 `.agents/skills` 下的项目级 skill，所以本地流程默认优先。 + +Bub 遵循 [Agent Skills](https://agentskills.io/) 的技能格式。如果你已经在其他兼容工具中维护了一批 skills，通常可以直接把这些目录迁移过来。 + +## 3. 安装一个你真正需要的扩展 + +Tape store、channel 这类额外能力，通常用插件来加。需要什么，就装什么。 + +如果你想先看看已经有哪些现成的东西，可以先去 [hub.bub.build](https://hub.bub.build/) 看看。那里收集了 Bub 的一些插件和 skills，可以先复用，再决定要不要自己写。 + +通过 `bub install` 按需添加能力： + +```bash +uv run bub install bub-tapestore-sqlite@main +uv run bub install bub-wechat@main +``` + +这里有三个稳定行为： + +- Bub 会把插件依赖记录在 `~/.bub/bub-project` 这个托管 uv 项目里 +- `name@ref` 会从 `bub-contrib` 的 `packages/` 解析 +- 当前激活环境会得到对应 entry point，因此下一次 Bub 启动就能加载它们 + +安装后，用下面的命令检查当前 hook 映射： + +```bash +uv run bub hooks +``` + +如果某个插件通过 `provide_channels()` 提供 channel，那么执行 `uv run bub gateway` 时，它会和其他已启用的非 `cli` channel 一起启动。 + +## 结果 + +现在你的工作区已经有三层结构： + +- `AGENTS.md` 提供长期稳定的本地规则 +- `.agents/skills` 提供可复用的本地流程 +- contrib 插件按需提供 tape store、channel 等运行时能力 + +下一步，如果内置能力和现有插件仍然不够，请继续阅读[制作第一个插件](/zh-cn/docs/getting-started/first-plugin/)。 diff --git a/website/src/content/docs/zh-cn/docs/getting-started/first-plugin.mdx b/website/src/content/docs/zh-cn/docs/getting-started/first-plugin.mdx new file mode 100644 index 00000000..0921b6ce --- /dev/null +++ b/website/src/content/docs/zh-cn/docs/getting-started/first-plugin.mdx @@ -0,0 +1,111 @@ +--- +title: 制作第一个插件 +description: 创建一个最小 Bub 插件，做本地可编辑安装，并验证它已经覆写了内置运行时。 +sidebar: + order: 3 +--- + +当内置能力、工作区里的本地文件，以及现有插件仍然不够用时，再进入这一页。 + +本教程会做一个极小的本地插件，它直接覆写 Bub 的模型阶段并返回 echo 结果。这样你不需要模型凭据，也能验证插件是怎样被加载的。 + +## 1. 创建包骨架 + +```bash +mkdir bub-echo-plugin +cd bub-echo-plugin +mkdir -p src/bub_echo_plugin +touch src/bub_echo_plugin/__init__.py +``` + +创建 `pyproject.toml`： + +```toml +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[project] +name = "bub-echo-plugin" +version = "0.1.0" +dependencies = ["bub"] + +[project.entry-points."bub"] +echo = "bub_echo_plugin.plugin:echo_plugin" + +[tool.hatch.build.targets.wheel] +packages = ["src/bub_echo_plugin"] +``` + +## 2. 实现插件 + +创建 `src/bub_echo_plugin/plugin.py`： + +```python +from __future__ import annotations + +from bub import hookimpl + + +class EchoPlugin: + @hookimpl + def build_prompt(self, message, session_id, state): + if hasattr(message, "content"): + return str(message.content) + if isinstance(message, dict): + return str(message.get("content", "")) + return str(message) + + @hookimpl + def run_model(self, prompt, session_id, state): + text = prompt if isinstance(prompt, str) else str(prompt) + return f"[echo:{session_id}] {text}" + + +echo_plugin = EchoPlugin() +``` + +这个插件只做两件事： + +- `build_prompt()` 保证 prompt 就是原始输入文本 +- `run_model()` 用一个确定性的 echo 响应替换内置模型调用 + +## 3. 安装到当前环境 + +在插件目录中执行： + +```bash +uv pip install -e . +``` + +Bub 会从当前 Python 环境加载 entry point，所以本地开发阶段只需要 editable install。 + +## 4. 验证 Bub 已经加载它 + +先看 hook 报告： + +```bash +uv run bub hooks +``` + +你应该能在 `build_prompt` 和 `run_model` 这两个 hook 上看到 `echo`。 + +然后跑一次 turn： + +```bash +uv run bub run "hello from plugin tutorial" +``` + +输出内容里应该包含： + +`[echo:cli:local] hello from plugin tutorial` + +## 结果 + +现在你已经有了： + +- 注册到 `bub` entry point group 的包入口 +- 两个覆写内置行为的 hook 实现 +- 一个适合快速迭代的本地 editable install 流程 + +接下来，请继续阅读 [插件](/zh-cn/docs/extending/plugins/) 和 [Hooks](/zh-cn/docs/extending/hooks/)，查看完整的插件和 hook 参考文档。 diff --git a/website/src/content/docs/zh-cn/docs/getting-started/index.mdx b/website/src/content/docs/zh-cn/docs/getting-started/index.mdx index 9c014a50..112c0034 100644 --- a/website/src/content/docs/zh-cn/docs/getting-started/index.mdx +++ b/website/src/content/docs/zh-cn/docs/getting-started/index.mdx @@ -1,12 +1,57 @@ --- title: 快速开始 -description: 用最短路径安装 Bub，并理解最核心的命令入口。 +description: 先了解 Bub 是什么，再在本地跑通它，按需添加本地规则、skills 和插件。 +sidebar: + order: 0 --- -Bub 的核心非常小，所以第一次跑起来很直接。 +Bub 是一个面向共享环境的轻量 Python 框架。它提供一条清楚的 turn 流程、一套简单的工作区布局，以及一条尽量贴近标准 Python 打包的扩展路径。 -- 通过 PyPI 或源码安装。 -- 使用 `bub chat` 启动交互式会话。 -- 使用 `bub run "hello"` 触发单次 turn。 +如果你第一次打开文档，从这里开始就够了。这一节会先带你做出一个可工作的 Bub，再逐步加上真正需要的东西。 -继续阅读[安装指南](/zh-cn/getting-started/installation/)。 +## 先知道这几件事 + +1. **一个足够小的核心** + Bub 用一条可见的 hook pipeline 处理每个 turn。你可以只替换其中一段，而不必改整个系统。 +2. **一套共享的工作区布局** + 工作区说明放在 `AGENTS.md`，可重复的本地流程放在 `.agents/skills`。 +3. **一条自然的 Python 扩展路径** + Bub 的插件就是标准 Python 包，通过 entry points 被发现；skills 也可以通过正常构建机制随插件一起分发，包括 PEP 517 build hooks。 +4. **从其他兼容工具平滑迁移** + Bub 在工作区说明上遵循 [agents.md](https://agents.md/)，在技能格式上遵循 [Agent Skills](https://agentskills.io/)。如果你已经在其他兼容工具里使用这两套约定，通常可以把现有的 `AGENTS.md` 和 skill 目录迁移过来。 + +## 开始前需要准备什么 + +请先准备： + +- Python 3.12+ +- `uv` +- 一种模型访问方式，在进入模型驱动步骤时使用： + - 通过 `BUB_API_KEY` 提供 API key，或 + - 通过 `uv run bub login openai` 使用 OAuth 登录 + +## 完成这一节后，你会得到 + +- 一个本地 Bub 工作区 +- 一个位于 `.agents/skills` 的项目 skill +- 一个从 `bub-contrib` 安装的扩展 +- 一个可以在本地继续迭代的最小插件包 + +## 推荐起步路径 + +1. [上手运行 Bub](/zh-cn/docs/getting-started/run-bub-locally/) + 安装 Bub、创建工作区、检查内置内核，并跑通第一次成功的 turn。 +2. [武装你的 Bub](/zh-cn/docs/getting-started/equip-your-bub/) + 在 `AGENTS.md` 中加入本地规则，添加一个项目 skill，并按需安装扩展。 +3. [制作第一个插件](/zh-cn/docs/getting-started/first-plugin/) + 创建一个最小插件包，做本地安装，并验证 Bub 已经加载它的 hook 实现。 + +## 如果你当前优先要解决别的问题 + +- 想先理解运行时模型：看[架构](/zh-cn/docs/concepts/architecture/) +- 想看命令细节：看[CLI 参考](/zh-cn/docs/guides/cli/) +- 想配置内置的 Telegram channel：看[Telegram](/zh-cn/docs/guides/telegram/) +- 想看部署方式：看[部署](/zh-cn/docs/guides/deployment/) +- 想直接看完整的插件和 hook 文档：看[插件](/zh-cn/docs/extending/plugins/)和[Hooks](/zh-cn/docs/extending/hooks/) + +这一节的目标是先带你用起来，而不是一次覆盖所有选项。部署、完整的 Telegram 配置以及完整插件 API 仍然分别留在 Guides、Concepts 和 Extending 章节中。 diff --git a/website/src/content/docs/zh-cn/docs/getting-started/installation.mdx b/website/src/content/docs/zh-cn/docs/getting-started/installation.mdx deleted file mode 100644 index 50c9490e..00000000 --- a/website/src/content/docs/zh-cn/docs/getting-started/installation.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: 安装 -description: 通过 PyPI 或源码方式安装 Bub。 ---- - -## 通过 PyPI - -```bash -pip install bub -``` - -## 从源码运行 - -```bash -git clone https://github.com/bubbuild/bub.git -cd bub -uv sync -uv run bub chat -``` - -如果你是在准备贡献开发环境，而不只是从源码运行 Bub，请改用 `make install`。它还会安装仓库使用的站点工具链和 `prek` hooks。 - -## 常用命令 - -- `uv run bub chat` 启动交互式 CLI。 -- `uv run bub run "summarize this repo"` 执行单轮 turn。 -- `uv run bub gateway` 启动 channel listener。 diff --git a/website/src/content/docs/zh-cn/docs/getting-started/run-bub-locally.mdx b/website/src/content/docs/zh-cn/docs/getting-started/run-bub-locally.mdx new file mode 100644 index 00000000..6a1f3560 --- /dev/null +++ b/website/src/content/docs/zh-cn/docs/getting-started/run-bub-locally.mdx @@ -0,0 +1,97 @@ +--- +title: 上手运行 Bub +description: 安装 Bub、创建工作区、检查内置内核，并完成第一次成功的 turn。 +sidebar: + order: 1 +--- + +如果你现在只想先把 Bub 在本地跑起来，而不想立刻进入 skills、插件或部署，这一页就是起点。 + +这一页默认你只有一个 Python 环境。完成后，你会有一个可工作的 workspace、一份 `AGENTS.md`，以及一次成功的 turn。 + +## 1. 安装 Bub + +任选一种方式： + +```bash +pip install bub +``` + +或者从源码运行： + +```bash +git clone https://github.com/bubbuild/bub.git +cd bub +uv sync +``` + +下面的命令统一使用 `uv run bub`，这样从源码运行和在已激活虚拟环境中运行都保持一致。 + +## 2. 创建工作区 + +给 agent 准备一个目录，并写入一份最小的工作区说明： + +```bash +mkdir hello-bub +cd hello-bub +cat > AGENTS.md <<'EOF' +You are the Bub agent for this workspace. +Read files before editing them. +Keep replies short and specific. +EOF +``` + +Bub 每次 turn 都会读取 `AGENTS.md`。 + +## 3. 看看内置命令能做什么 + +在添加 provider、skill 或 plugin 之前，先确认 Bub 已经能正常工作： + +```bash +uv run bub hooks +uv run bub run ",help" +``` + +这两个命令分别验证两件事： + +- hook 链已经加载 +- 即使还没有模型凭据，命令模式也能工作 + +## 4. 跑你的第一个模型任务 + +当你的 provider 环境已经配置好之后，可以启动交互式会话，或者执行一次单轮任务： + +```bash +uv run bub chat +uv run bub run "Summarize the purpose of this workspace." +``` + +如果你想使用 OpenAI Codex OAuth，而不是直接配置 API key，可以先登录： + +```bash +uv run bub login openai +``` + +## 可选：试用内置 Telegram channel + +Telegram 是内置能力，不需要额外安装插件。 + +要启用它，先设置 token，再启动 channel listener： + +```bash +export BUB_TELEGRAM_TOKEN=... +uv run bub gateway --enable-channel telegram +``` + +完整的配置和部署方式，请继续阅读 [Telegram](/zh-cn/docs/guides/telegram/)。 + +## 结果 + +现在你已经有了： + +- 位于 `AGENTS.md` 的本地指令 +- 已加载的内置 hook 链 +- 同时支持交互式和单轮执行的基本路径 +- 一条启用内置 Telegram channel 的可选路径 + +下一步，请继续阅读[武装你的 Bub](/zh-cn/docs/getting-started/equip-your-bub/)，给这个 workspace 加上本地规则、一个项目 skill，以及真正需要的扩展。 From f7a6af3a471ee410145780970394c552260ebe02 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 23 Apr 2026 05:04:16 +0800 Subject: [PATCH 2/2] docs: minor update --- website/src/content/docs/docs/getting-started/index.mdx | 2 +- website/src/content/docs/zh-cn/docs/getting-started/index.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/website/src/content/docs/docs/getting-started/index.mdx b/website/src/content/docs/docs/getting-started/index.mdx index 0c2cf353..139accc3 100644 --- a/website/src/content/docs/docs/getting-started/index.mdx +++ b/website/src/content/docs/docs/getting-started/index.mdx @@ -17,7 +17,7 @@ If you are new to Bub, start here. This section helps you get one working setup Put workspace instructions in `AGENTS.md` and repeatable local procedures in `.agents/skills`. 3. **Standard Python extensions** Plugins are normal Python packages discovered through entry points. Skills can ship with plugins through regular build tooling, including PEP 517 build hooks. -4. **A migration path from other compatible tools** +4. **A migration path from other agents** Bub follows [agents.md](https://agents.md/) for workspace instructions and [Agent Skills](https://agentskills.io/) for skills. If you already use those conventions elsewhere, you can usually reuse your `AGENTS.md` file and skill directories. ## Before You Start diff --git a/website/src/content/docs/zh-cn/docs/getting-started/index.mdx b/website/src/content/docs/zh-cn/docs/getting-started/index.mdx index 112c0034..50df3302 100644 --- a/website/src/content/docs/zh-cn/docs/getting-started/index.mdx +++ b/website/src/content/docs/zh-cn/docs/getting-started/index.mdx @@ -17,8 +17,8 @@ Bub 是一个面向共享环境的轻量 Python 框架。它提供一条清楚 工作区说明放在 `AGENTS.md`，可重复的本地流程放在 `.agents/skills`。 3. **一条自然的 Python 扩展路径** Bub 的插件就是标准 Python 包，通过 entry points 被发现；skills 也可以通过正常构建机制随插件一起分发，包括 PEP 517 build hooks。 -4. **从其他兼容工具平滑迁移** - Bub 在工作区说明上遵循 [agents.md](https://agents.md/)，在技能格式上遵循 [Agent Skills](https://agentskills.io/)。如果你已经在其他兼容工具里使用这两套约定，通常可以把现有的 `AGENTS.md` 和 skill 目录迁移过来。 +4. **从其他 Agent 平滑迁移** + Bub 在工作区说明上遵循 [agents.md](https://agents.md/)，在技能格式上遵循 [Agent Skills](https://agentskills.io/)。如果你已经在其他兼容 Agent 里使用这两套约定，通常可以把现有的 `AGENTS.md` 和 skill 目录迁移过来。 ## 开始前需要准备什么