Skip to content

docs(pages): add user-facing OctoBus integration quick start - #651

Open
Byc4i wants to merge 1 commit into
chaitin:mainfrom
Byc4i:docs/octobus-quickstart
Open

docs(pages): add user-facing OctoBus integration quick start#651
Byc4i wants to merge 1 commit into
chaitin:mainfrom
Byc4i:docs/octobus-quickstart

Conversation

@Byc4i

@Byc4i Byc4i commented Sep 1, 2026

Copy link
Copy Markdown

PR: docs: add OctoBus integration quick start guide

Closes #80

Summary

Adds a user-facing OctoBus Integration Quick Start guide (English + 中文) to the
GitHub Pages documentation site, walking a new user from a local agent-compose +
OctoBus deployment all the way to a verified capability call from inside a sandbox.

The existing documentation under docs/design/ describes the internal architecture;
this guide is the operational tutorial issue #80 asks for.

What the guide covers

All seven points requested in #80:

#80 requirement Where
How to start agent-compose and OctoBus locally Step 1
Daemon env vars, esp. CAP_GRPC_LISTEN / CAP_GRPC_TARGET Step 3b + concepts table
How to configure the Capability Gateway in the settings page Step 3a
How to confirm a capset is readable by agent-compose Step 3a (status probe), Step 5
How to bind a capset when creating a session/agent Step 4 (capset_ids, incl. project-scoped servers)
How to confirm capability config was injected into the session Step 5 (env vars, tags, catalog.md)
Minimal verification example (see capset + call a simple capability) Step 2 (publish dev capset) + Step 6 (call calculator, expect 42)

Plus: a concepts table mapping OctoBus ↔ agent-compose terminology, the data-plane
diagram, a troubleshooting matrix for the 7 most common misconfigurations, and the
security boundary notes (token never leaves the daemon; CAP_TOKEN vs OctoBus token).

Accuracy

Every command, env var, path, and behavior in the guide was verified against:

  • docs/design/octobus_integration.md and docs/design/project_octobus_servers_design.md
  • pkg/capabilities/gateway.go (CAP_GRPC_TARGET / CAP_TOKEN injection, guide rendering)
  • pkg/capability/client.go (/admin/v1/* control-plane probes)
  • pkg/agentcompose/api/capability_v2.go (status response fields)
  • docs/pages/agent-compose-yaml-manual.md (octobus_servers, capset_ids semantics)
  • the OctoBus repository README (service import / instance / capset workflow)

Files changed

File Change
docs/pages/octobus-quickstart.md New. English quick start
docs/pages/zh-CN/octobus-quickstart.md New. 中文版.
tools/genpages/render-pages.mjs Register both pages in the manual list + top navigation.
tools/genpages/check-pages.mjs Add the two pages to manualNames / expectedOutput whitelists.

The two script edits are required: check-pages.mjs asserts the exact set of files
in docs/pages/, so any new page must be whitelisted or CI fails.

Testing

cd tools/genpages
npm ci --no-audit --no-fund
npm run build   # node --test && render-pages && check-pages

Result: Pages checks passed for 69 YAML schema fields and 12 public files (was 10
files before this change). This is the same command the pages.yml workflow runs.

Notes for reviewers

  • Internal cross-links use .html targets because the Pages link checker resolves
    links against the rendered output; links to README / docs/design/ use GitHub
    absolute URLs (skipped by the checker), matching the existing convention in
    guest-image-abi.md.
  • No anchor fragments in cross-links: marked does not emit heading ids, so
    fragment links would fail the checker's anchor validation.
  • Taskfile.yml docs:build.generates does not list the new HTML outputs; it also
    omits the pre-existing connect-transport-matrix.html, so this PR leaves it
    untouched to keep the change scoped. Happy to add all missing entries if preferred.

@monkeyscan

monkeyscan Bot commented Sep 1, 2026

Copy link
Copy Markdown

PR Title: docs(pages): add user-facing OctoBus integration q...

Commit: 96ed084

本次变更新增了 OctoBus 集成快速开始文档(英文 docs/pages/octobus-quickstart.md 与中文 docs/pages/zh-CN/octobus-quickstart.md,各 214 行),并在文档站点构建/校验工具中登记这两份新页面:render-pages.mjs 的 manuals 数组新增 EN/ZH 两条渲染条目(含 title、lang、alternate 互链),check-pages.mjs 的 manualNames 与 expectedOutput 同步新增源文件与输出 HTML。

审查结论:改动整体正确且自洽。构建链路方面,新增条目与 check-pages.mjs 的 checkSourceLayout(根与 zh-CN 目录 markdown 集合必须与 manualNames 完全一致)、checkOutputWhitelist(输出文件集合必须与 expectedOutput 一致)、checkInternalLinks(语言互链 alternate 可正确解析)、checkEnglishManuals(英文文档不含 CJK 字符)等校验均能通过;两页面的 alternate 链接相对路径与既有页面模式一致。文档内容方面,与 docs/design/octobus_integration.md 实现说明核对后,控制面/数据面、CAP_GRPC_LISTEN/CAP_GRPC_TARGET/CAP_TOKEN、catalog.md 注入、best-effort 语义等关键描述均一致;文档引用的仓库内文件(docs/design/octobus_integration.md、README.zh-CN.md、yaml manual 等)均存在。唯一发现是新增的 quickstart 页面没有接入 renderPage 的站点导航(navItems 为硬编码的四项),也未出现在首页中,发布后只能通过直接 URL 访问,存在可发现性缺口(低严重度)。

title: "OctoBus Integration Quick Start",
lang: "en",
alternate: "zh-CN/octobus-quickstart.html",
},

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

新增 OctoBus 快速开始页面未接入站点导航,发布后无法从文档站导航发现

本次变更把 octobus-quickstart.html 注册进渲染与白名单校验,页面会被发布;但 renderPage 的站点导航仍是硬编码的四项(Home/CLI Manual/YAML Manual/Connect Transport),未包含新增的 octobus 页面,且 docs/pages/index.html 也未在本变更中链接该页面。结果是该快速开始文档只能通过直接 URL 访问,浏览文档站的用户无法从导航发现它,削弱了 quickstart 的引导价值;这也与其它公开手册(command-line、agent-compose-yaml、connect-transport-matrix)均出现在导航中的既有模式不一致。

Problem code:

Changed code at tools/genpages/render-pages.mjs:33-39

Recommendation:
在 renderPage 的 labels 与 navItems 中加入 octobus-quickstart 导航项(EN/ZH 各一个条目),使新页面在站点头部导航中可达。注意保持 zh-CN 页面的相对 href 仍解析到 zh-CN/octobus-quickstart.html,并确认不会触发 checkNavigation 的 guest-image-abi 限制。

Suggested diff:

diff --git a/tools/genpages/render-pages.mjs b/tools/genpages/render-pages.mjs
--- a/tools/genpages/render-pages.mjs
+++ b/tools/genpages/render-pages.mjs
@@ -108,11 +108,13 @@ function renderPage(manual, body) {
   const root = nested ? "../" : "./";
   const labels = lang === "zh-CN"
-    ? ["首页", "命令行手册", "YAML 配置手册", "Connect 传输矩阵"]
-    : ["Home", "CLI Manual", "YAML Manual", "Connect Transport"];
+    ? ["首页", "命令行手册", "YAML 配置手册", "Connect 传输矩阵", "OctoBus 快速开始"]
+    : ["Home", "CLI Manual", "YAML Manual", "Connect Transport", "OctoBus Quick Start"];
   const navItems = [
     [root, labels[0], ""],
     ["command-line-manual.html", labels[1], "command-line-manual.html"],
     ["agent-compose-yaml-manual.html", labels[2], "agent-compose-yaml-manual.html"],
     ["connect-transport-matrix.html", labels[3], "connect-transport-matrix.html"],
+    ["octobus-quickstart.html", labels[4], "octobus-quickstart.html"],
   ];

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: 补充面向用户的 OctoBus 集成 Quick Start 文档

1 participant