Skip to content

docs: improve installation, deployment, and API guides - #1374

Open
Teingi wants to merge 3 commits into
oceanbase:masterfrom
Teingi:dev_0826
Open

docs: improve installation, deployment, and API guides#1374
Teingi wants to merge 3 commits into
oceanbase:masterfrom
Teingi:dev_0826

Conversation

@Teingi

@Teingi Teingi commented Aug 27, 2026

Copy link
Copy Markdown
Member

Which issue or RFC does this PR close?

N/A.

Rationale for this change

The user documentation mixed released-package and source-installation assumptions, lacked a practical deployment path and human-oriented HTTP API entry point, and presented unpublished adapters as directly installable. This made common installation and integration tasks harder to follow and could lead to failed installs or unsafe network exposure.

What changes are included in this PR?

  • Standardize current source installation examples on the master Git ref.
  • Add English and Chinese Server deployment guides covering persistence, Docker, authentication, TLS boundaries, health checks, and backups.
  • Add English and Chinese HTTP API guides with authentication, curl examples, operation groups, error handling, and OpenAPI discovery.
  • Add Hermes integration guides and expand the interface/navigation coverage for supported Agent hosts.
  • Align the installation and interface references with setup select, doctor integrations, and the explicit WorkBuddy commands now present on master.
  • Clarify the current preview or source-only status of the Pydantic AI, LangChain, and LangGraph integrations.
  • Align Docker and configuration guidance with the shared loopback-only plaintext HTTP transport policy.
  • Distinguish the generated Python API reference from the HTTP API reference.
  • Update the Pydantic AI packaging test so public guides cannot reintroduce an unavailable PyPI install command.

No runtime code, OpenAPI contract, generated source, dependency, or persisted-data format is changed.

Are there any user-facing changes?

Yes. Installation, deployment, API, Docker, and integration documentation is reorganized and corrected in English and Chinese. The normal Git-based installation path now follows master; unpublished adapters no longer show commands that imply a PyPI release exists. There are no breaking API or persisted-format changes.

How was this change tested?

  • make check
  • make docs-test
  • make contract-test (29 passed)
  • uv run pytest tests/test_doctor_integrations.py tests/test_setup_select.py (33 passed)
  • uv run pytest tests/pydantic_ai_adapter/test_packaging.py (4 passed)
  • uv run pytest tests/test_docs_remote_access_contract.py tests/test_docker_contract.py (9 passed)
  • Manual local Server checks for liveness/readiness, Memory remember/search, validation errors, and bearer authentication
  • Manual uv dependency resolution confirmed that the unreleased Pydantic AI adapter cannot currently resolve against the public or master core package
  • make test: 892 passed, 9 skipped, and 1 host E2E failed because the installed OpenCode 1.18.21 did not invoke the capture hook. The same failure was reproduced from an unmodified origin/master archive in this environment.

AI usage statement

OpenAI Codex (GPT-5) assisted with the documentation audit, editing, merge conflict resolution, and validation. The resulting commands, links, package status, OpenAPI behavior, and Server behavior were checked against the repository and local runtime.

Teingi added 3 commits August 27, 2026 12:47
# Conflicts:
#	docs/en/docs/how-to/install-and-run.md
#	docs/en/docs/reference/interfaces.md
#	docs/zh/docs/how-to/install-and-run.md
#	docs/zh/docs/reference/interfaces.md
@AsperforMias

Copy link
Copy Markdown
Collaborator

conflict on docs

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.

2 participants