From 6a1cc49c5408703c4911994847b91c52ea436305 Mon Sep 17 00:00:00 2001 From: huanghuoguoguo <1051233107@qq.com> Date: Sun, 27 Sep 2026 10:27:48 +0800 Subject: [PATCH] docs(agent): document standalone LangBot CLI (#2571) --- AGENTS.md | 2 ++ ARCHITECTURE.md | 2 ++ README.md | 1 + README_CN.md | 1 + docs/API_KEY_AUTH.md | 5 +++++ skills/skills/langbot-dev/SKILL.md | 5 ++++- 6 files changed, 15 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 760cf06b6..4fb546042 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,6 +46,7 @@ Run the narrowest useful test first, then broader checks when confidence is need - Dev environment guide: https://langbot.app/docs/zh/develop/dev-config. - Plugin runtime / CLI / SDK debugging: https://langbot.app/docs/zh/develop/plugin-runtime. - API-key auth: `docs/API_KEY_AUTH.md`. +- Service API CLI: [`langbot-cli`](https://github.com/langbot-app/langbot-cli) (`lbctl`) manages running Workspaces; it is separate from the SDK's `lbp` CLI. - Box deep-dive notes: `docs/review/box-architecture.md` and related files. - In-repo skills: `skills/` is the single source of truth for LangBot agent skills. - SDK repo: `../langbot-plugin-sdk/` when changing shared entities, plugin APIs, action protocol, `lbp rt`, or `lbp box`. @@ -83,6 +84,7 @@ Config keys to verify in `data/config.yaml` / `src/langbot/templates/config.yaml ## Change Rules - HTTP API changes that should be agent-accessible must update the matching MCP tool in `src/langbot/pkg/api/mcp/server.py` and the relevant skill under `skills/` in the same pass. +- When changing Service API routes or capabilities used by `lbctl`, check compatibility with the separate `langbot-cli` repository. - New schema changes use Alembic under `src/langbot/pkg/persistence/alembic/versions/`. LangBot 4.x does not support upgrading 3.x databases. - New platform behavior belongs in platform adapters only for platform translation; pipeline/business logic belongs in `pkg/pipeline/` or services. - User-facing strings must support i18n (`en_US`, `zh_Hans`; include `ja_JP` where the repo already does). diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 688d8f5c1..e6eaa9a72 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -23,6 +23,7 @@ LangBot is not a single-repo system. - `LangBot/` is the main product: backend, web UI, platform adapters, pipeline engine, HTTP API, MCP server, RAG, persistence, skills integration, and the bridge code that talks to runtimes. - `langbot-plugin-sdk/` is published as `langbot-plugin` and pinned in `LangBot/pyproject.toml`. It contains plugin developer APIs, shared entities, `lbp`, the Plugin Runtime (`lbp rt`), and the Box Runtime (`lbp box`). +- [`langbot-cli`](https://github.com/langbot-app/langbot-cli) is a separately released `lbctl` client for managing a running Workspace through the HTTP Service API; it is not part of the LangBot server or the SDK's `lbp` CLI. - Plugins import SDK APIs from `langbot_plugin.*`; the LangBot main process imports the same package for shared entities and runtime protocols. This split matters. If a change modifies SDK entities, component APIs, action protocols, `lbp rt`, or `lbp box`, verify the sibling SDK repo and install the local SDK into LangBot's virtualenv when testing cross-repo behavior. @@ -252,6 +253,7 @@ LangBot is deliberately agent-friendly. The agent-facing surfaces are part of th - `skills/` is the single source of truth for in-repo skills. - `pkg/api/mcp/server.py` exposes the LangBot MCP server at `/mcp`. +- `lbctl` calls the authenticated HTTP Service API from a terminal; its source and releases live in `langbot-cli`. - `api.global_api_key` authenticates API/MCP access without a browser login. - `AGENTS.md` and `ARCHITECTURE.md` tell coding agents how the repo works. diff --git a/README.md b/README.md index 81277fd54..6a36e7b94 100644 --- a/README.md +++ b/README.md @@ -164,6 +164,7 @@ docker compose --profile all up -d LangBot is **agent-friendly by design** — your coding agents (Claude Code, Codex, Copilot, Cursor, …) can operate, extend, and deploy LangBot with first-class support: - **MCP Server** — LangBot exposes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) endpoint at `/mcp`, mirroring the HTTP API so an agent can manage bots, pipelines, plugins, and models programmatically. Authenticate with the same API key (set a global key in `config.yaml` or use a per-user key) — no login flow required. Configure it in the Web panel's **API & MCP** tab. +- **CLI (`lbctl`)** — The standalone [LangBot CLI](https://github.com/langbot-app/langbot-cli) lets agents manage a running LangBot Workspace from a terminal through the Service API. It uses an API key and supports bots, pipelines, knowledge bases, models, plugins, skills, and MCP servers. See the CLI repository for installation and commands. - **In-repo Skills** — The [`skills/`](skills/) directory is the **single source of truth** for working with LangBot: plugin development, core development, end-to-end testing, deployment, and operating the LangBot / LangBot Space MCP servers. Point your agent at this directory and it knows how to build. - **AGENTS.md** — Every repo ships an [`AGENTS.md`](AGENTS.md) (symlinked to `CLAUDE.md`) describing architecture, conventions, and the rule that API changes must keep the MCP server and skills in sync. - **`llms.txt`** — Machine-readable project context for LLMs is published on the website. diff --git a/README_CN.md b/README_CN.md index d49799cf6..33b92645e 100644 --- a/README_CN.md +++ b/README_CN.md @@ -180,6 +180,7 @@ docker compose --profile all up -d LangBot **从设计上就对 Agent 友好** —— 你的编码 Agent（Claude Code、Codex、Copilot、Cursor 等）可以一等公民般地操作、扩展和部署 LangBot： - **MCP Server** —— LangBot 内置 [Model Context Protocol](https://modelcontextprotocol.io/) 端点 `/mcp`，与 HTTP API 对齐，Agent 可编程式管理机器人、流水线、插件和模型。使用同一套 API Key 鉴权（可在 `config.yaml` 配置全局 Key，或使用用户 Key），无需登录流程。在 Web 面板的 **API 与 MCP** 标签页中配置。 +- **CLI（`lbctl`）** —— 独立的 [LangBot CLI](https://github.com/langbot-app/langbot-cli) 让 Agent 在终端通过 Service API 管理已运行实例中的 Workspace。它使用 API Key，支持管理机器人、流水线、知识库、模型、插件、Skill 和 MCP Server。安装方法和命令以 CLI 仓库为准。 - **仓库内 Skills** —— [`skills/`](skills/) 目录是使用 LangBot 的**唯一事实来源**：插件开发、核心开发、端到端测试、部署，以及操作 LangBot / LangBot Space MCP Server。把 Agent 指向这个目录，它就知道如何动手。 - **AGENTS.md** —— 每个仓库都提供 [`AGENTS.md`](AGENTS.md)（软链到 `CLAUDE.md`），描述架构、规范，以及「API 变更必须同步更新 MCP Server 和 skills」的约定。 - **`llms.txt`** —— 面向 LLM 的机器可读项目上下文已发布在官网。 diff --git a/docs/API_KEY_AUTH.md b/docs/API_KEY_AUTH.md index f825ea0a5..3eac9eb10 100644 --- a/docs/API_KEY_AUTH.md +++ b/docs/API_KEY_AUTH.md @@ -55,6 +55,11 @@ Behavior: ## Using API Keys +The standalone [`lbctl` CLI](https://github.com/langbot-app/langbot-cli) uses +these API keys to manage a running LangBot Workspace through the Service API. +It can check the key's Workspace identity and server capabilities before +managing resources. See the CLI repository for installation and commands. + ### Authentication Headers Include your API key in the request header using one of these methods: diff --git a/skills/skills/langbot-dev/SKILL.md b/skills/skills/langbot-dev/SKILL.md index 77a988ce8..dbcdb0625 100644 --- a/skills/skills/langbot-dev/SKILL.md +++ b/skills/skills/langbot-dev/SKILL.md @@ -94,7 +94,9 @@ discovered by `importutil.import_modules_in_pkg`. 3. **If the endpoint should be agent-accessible, add/adjust the matching MCP tool in `pkg/api/mcp/server.py` and update the `langbot-mcp-ops` skill.** API and MCP surface must stay aligned (see `AGENTS.md`). -4. Update `docs/service-api-openapi.json` if you maintain the OpenAPI overview. +4. If `lbctl` uses the route or capability, check the separate + [`langbot-cli`](https://github.com/langbot-app/langbot-cli) client for compatibility. +5. Update `docs/service-api-openapi.json` if you maintain the OpenAPI overview. ## Database migrations (Alembic) @@ -127,3 +129,4 @@ uv run python tests/manual/mcp_smoke.py # MCP server e2e smoke - `langbot-testing` — WebUI/e2e QA harness (`bin/lbs`). - `langbot-deploy` — Docker/compose deployment + config. - `langbot-mcp-ops` — operating the LangBot MCP server. +- [`langbot-cli`](https://github.com/langbot-app/langbot-cli) — `lbctl`, a standalone Service API client for managing running Workspaces.