Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions zh-cn/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Manboster Documentation

This is the documentation repository of Manboster.

[Manboster Contributing Guideline](https://github.com/manboster/manboster/blob/master/CONTRIBUTING.md) also applies to this repository.

If you want to get more information about Manboster, please go to [the main repository](https://github.com/manboster/manboster)

## License

We use [CC-BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) as our documentation's license.
3 changes: 3 additions & 0 deletions zh-cn/docs/configure/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Manboster Configuration Documentation

This document aims to help you manually manage your `config.yaml`.
13 changes: 5 additions & 8 deletions zh-cn/docs/container.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,9 @@

本文档旨在帮助您在容器中运行 Manboster,使其易于部署和获取。

> [!NOTE]
> 此翻译部分内容由 Gemini 3.1 Pro 提供,如果有任何疏忽和遗漏,欢迎[向我们提交PR](https://github.com/manboster/docs/pull/new)进行修改!

## 容器镜像在哪里?

Manboster 的容器镜像是通过 GitHub Actions 自动生成的。它发布在 ghcr (GitHub Container Registry) 上。
Manboster 的容器镜像是通过 GitHub Actions 自动生成的。它发布在 ghcr (GitHub Container Registry) 上。 It is published in ghcr.

官方容器镜像地址为:

Expand Down Expand Up @@ -39,7 +36,7 @@ docker run -dit -v ./manboster-data:/app/manboster/ --restart=unless-stopped --n
podman run -dit -v ./manboster-data:/app/manboster/ --restart=unless-stopped --name manboster-container ghcr.io/manboster/manboster
```

如果您想启动配置 TUI(终端用户界面),请在 Manboster 停止后运行以下命令,否则会提示运行错误:
如果您想启动配置 TUI,请在 Manboster 停止后运行以下命令,否则会提示运行错误:

```shell
# 如果您使用的是 Docker:
Expand All @@ -51,7 +48,7 @@ podman stop manboster-container
podman run --remove -it -v ./manboster-data:/app/manboster/ ghcr.io/manboster/manboster manboster config
```

别忘了在配置完成后重新启动它们!
Don't forget to get them up!

如果您使用的是 Docker Compose 或 Podman Compose,您可以将以下内容添加到 `docker-compose.yml` 文件的 `services` 字段中:

Expand Down Expand Up @@ -87,7 +84,7 @@ docker compose up -d
podman compose up -d
```

如果您想启动配置 TUI,请在 Manboster 停止后运行以下命令,否则会提示运行错误:
如果您想启动配置 TUI(终端用户界面),请在 Manboster 停止后运行以下命令,否则会提示运行错误:

```shell
# Docker Compose
Expand All @@ -99,4 +96,4 @@ podman compose stop manboster
podman compose run --rm manboster manboster config
```

别忘了在配置完成后重新启动它们!
Don't forget to get them up!
130 changes: 130 additions & 0 deletions zh-cn/docs/contribute/architecture.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# Manboster Architecture Documentation

In this document, we will introduce Manboster's file structure and explain why it is that. It may help you add new features or fix new bugs in a proper way.

## File Tree Overview

This is a tree for Manboster application currently, it provides a comprehensive architecture preview of the Manboster:

```
├── build -> This is the build repo
│   └── manboster
├── build.sh
├── cmd
│   ├── manbodev
│   └── manboster -> The entrypoint of Manboster
├── internal
│   ├── chat -> Where is the chat provider lives
│   │   ├── all -> Aonoymous import chat providers here
│   │   ├── feishu
│   │   ├── registry.go
│   │   ├── telegram
│   │   └── web
│   ├── cli -> The cli interface of Manboster & Manbodev
│   │   ├── helper -> Helper function for the Client Interface
│   │   ├── manbodev
│   │   ├── manboster
│   │   │   ├── app -> Main application entrypoint using Cobra(or plain text response)
│   │   │   ├── ctx -> Daemon context
│   │   │   ├── daemon -> Commands related to daemon
│   │   │   ├── init.go
│   │   │   └── interact -> Interactive User Interface for Manboster (Mainly onboard and edit configuration)
│   │   └── provider -> Interactive Interface Providers Instance
│   │   └── huh
│   ├── config -> Configuration parser & helper functions
│   │   ├── model -> Model Information collected in database
│   │   ├── prompt -> where the Default Prompt stores
│   ├── database -> Database module
│   │   └── types -> ORM Types
│   ├── downloader -> Download helper with checkpoint and speed hints
│   ├── engine -> The main engine of Manboster
│   │   ├── chatdata -> Chat Data Manager(Compact, write it to database)
│   │   ├── command -> Command Handler
│   │   ├── distribute.go -> Distribute chat message based on its type
│   │   ├── engine.go -> The declaration
│   │   ├── gatekeeper -> Gatekeeper Module
│   │   ├── gateway -> Gateway Module (With retries, send message & get message)
│   │   ├── handler -> Message Handler Module
│   │   ├── handler.go -> The main message handler loop lies
│   │   ├── hook -> Hooks manager
│   │   ├── load.go -> Load SessionID
│   │   ├── onboard -> Onboard manager, used when first run
│   │   ├── processor -> Preprocess messages received from Chat Provider and decide whether to handle or not
│   │   ├── runner -> Runner for cronjob handler
│   │   ├── runner.go -> Runner for main message session handler
│   │   ├── safeguard -> Evaluation tools for checking permission
│   │   └── soul -> The system prompt building module
│   ├── fs -> A helper module for storage file in disk for caching
│   ├── hachimi -> The Hachimi module
│   │   ├── all -> All providers registrar
│   ├── i18n -> i18n module
│   │   ├── keys -> i18n variable keys defined in Manboster Application
│   │   ├── locales -> i18n json stored in here
│   │   │   ├── en -> Languages...
│   │   │   └── zh-cn
│   ├── llm -> llm providers module
│   │   ├── all -> llm provider registrar
│   │   ├── oai_compat -> provider
│   │   ├── openrouter
│   │   └── universal
│   ├── loader -> provider loader & app loader
│   │   ├── chat.go -> load chat providers
│   │   ├── hachimi.go -> load hachimi providers
│   │   ├── llm.go -> load llm providers
│   │   ├── load.go -> load application
│   │   ├── loader.go
│   │   ├── model.go -> load models
│   │   ├── run_chat.go -> polling chats
│   │   ├── skill.go -> load skills
│   │   └── tool.go -> load tools
│   ├── plugin -> WASM plugin module (TODO)
│   ├── repository -> ORM Repository middleware
│   │   ├── types -> DTO Types
│   ├── session -> Session Manager
│   ├── skill -> skills compatibility layer
│   ├── tool -> Tool provider
│   │   ├── all -> tool registrar
│   │   ├── browser
│   │   ├── ...
│   │   └── vision
│   ├── util -> utilities used in Manboster
│   ├── vault -> vault services used in Manboster (TODO)
│   └── wasm -> wasm applications used in Manboster (TODO)
├── sdk -> Manboster Software Development Kit for go wasm plugins (TODO)
└── spec -> definitions of types
├── chat
├── cli
├── config
├── llm
├── plugin
└── schema
```

## How a Manboster Application starts

Its execution flows like this:

```
`/cmd/manboster/main.go`(check i18n) -> `/internal/cli/manboster/app` -> `/internal/loader` -> `/internal/engine`
```

1. Manboster's entrypoint file is `/cmd/manboster/main.go`. It will first activate i18n and then continue.
2. Then it will activate cobra and handle you to different commands. (Next is the description of `main`.)
3. `/internal/loader` loads Chat Providers(open new goroutines to poll, initialize and more), LLM Providers, Tool Providers and more.
4. If loaded, loader will open engine and wait for the message feed.

## How a message was handled in Manboster Engine

Its execution flows like this:

```
Chat Provider -> PreProcessor -> distribute.go -> handler.go -> handler -> chatProvider.Send ...
```

1. Chat Provider triggers a message event
2. Our PreProcessor checks out whether this message should be processed or not
3. distribute.go distribute messages to handler or other places based on its type
4. Handler will handle text, image and tool call and more.
5. Once end, we will make responses via `chatProvider.Send` and send back messages

We use Channels to help us manage incoming message from chat providers. It ensures the sequence of messages. And we defined session type in `/internal/session`, so you can get a preview in there.
15 changes: 15 additions & 0 deletions zh-cn/docs/contribute/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Manboster Contribute Documentation

Welcome to the Manboster Contribute Documentation!

Before contributing this repository, we strongly recommend you to read it!

## First Read

- [Manboster Contributing Guideline](https://github.com/manboster/manboster/blob/master/CONTRIBUTING.md)

## Then Read

- [Project Architecture](/docs/contribute/architecture.md)
- [How to start](/docs/contribute/start.md)
- [Versioning](/docs/contribute/versioning.md)
49 changes: 49 additions & 0 deletions zh-cn/docs/contribute/packaging.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Manboster Packaging Documentation

This is a documentation for packagers of Manboster, intending to introducing Manboster's releases and how it is assembled.

## Release Channels

It's suggested to contain these channels in your package:

| Channel | Versions Contained |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Stable | Stable Versions (i.e. v0.1.0, v0.2.0,...) |
| Beta | Beta Versions (i.e. v0.1.0-beta.1, v0.1.0-rc, ...) |
| Canary(optional) | Canary Versions (GitHub Tag `canary`) |

For better experience, a `canary` version is good to go.

## Release Version Standards

Based on the [Contributing Guideline], we have 3 types of releasing:

1. Stable release: Tagged as `v0.x.x`, this is the stable and safe version for all users
2. Release Candidate: Tagged as `v0.x.x-rc`, this is a version with features frozen and only accept bug fixes.
3. Beta: Tagged as `v0.x.x-beta.1`, `v0.x.x-beta.x`, this is a version with experimental features and not stable as well.
4. Canary: Tagged as `canary`, it provides latest developer preview of Manboster.

## Release Artifact Standards

After `v0.2.0`, we have unify the overall release artiface of Manboster, it would be that:

```
checksums.txt
manboster_0.2.0_darwin_amd64.tar.gz
manboster_0.2.0_darwin_arm64.tar.gz
manboster_0.2.0_linux_amd64.tar.gz
manboster_0.2.0_linux_arm64.tar.gz
manboster_0.2.0_linux_riscv64.tar.gz
manboster_0.2.0_windows_amd64.zip
manboster_0.2.0_windows_arm64.zip
```

Its structure would be like `manboster_{version}_{platform}_{architecture}.tar.gz(for windows it's .zip)`.

For canary, it would be like `{version}_{commithash}`.

Inside this compress there is a `manboster(.exe)` executable file so just move it to executable.

Also, you can define `MANBOSTER_HOME` variable to determine Manboster's home, it will create a `.manboster` in that directory but in next version we will remove `.manboster` and use it directly.

checksums.txt contains sha256 checksum for Manboster.
3 changes: 3 additions & 0 deletions zh-cn/docs/contribute/providers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Manboster Providers Documentation

This documentation aims to describe providers in Manboster and explains why we need it and guides you through the definition of types and functions.
62 changes: 62 additions & 0 deletions zh-cn/docs/contribute/start.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Start to contribute Manboster?

This document guides you contribute Manboster in ease.

## Fork the repo

Fork the Manboster repository to your GitHub account.

## Clone the repo down you your machine

Use this command to clone Manboster (git required and configure SSH keys in advance)

```shell
git clone git@github.com:/your-username/manboster.git
```

## Install development dependencies

When modifying Manboster, you need to install development dependencies or you can't run Manboster.

Install [the Go Programming Language](https://go.dev/) and Makefile is enough.

Use this command to install modules:

```shell
go mod download
```

And use `make` to start developing:

```shell
make run (params)
```

## Pick a good-first-issue to fix

If you're first to contribute, don't hesitate to get some `good-first-issues` from [our issues](https://github.com/manboster/manboster/issues) list.

## Open a new branch

We strongly recommend you to do that.

Use this command to open a new branch to fix this problem:

```shell
git branch fix/your-branch-name
git checkout fix/your-branch-name
```

## Fix the code

We don't care what AI Agent you are using, but we will reject AI slops with no value.

## Push & Open a new pull request

Use this to push it back to your repository:

```shell
git push origin fix/your-branch-name
```

Then [open a new pull request](https://github.com/manboster/manboster/pulls/new) to us.
29 changes: 29 additions & 0 deletions zh-cn/docs/contribute/versioning.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# The versioning and branch standard of Manboster

## Versioning

Manboster versioning is based on `SemVer`. And we use these git tags to release:

`v1.0.0` means the stable version

`v1.0.0-rc` means the RC(Release candidate) version

`v1.0.0-beta` means the Beta version

`v1.0.0-alpha` means the Alpha version

`nightly-2026xxxx` means the Nightly version, `2026xxxx` means its release date

`canary` means the developing canary version

For more information, read [the guideline](https://github.com/manboster/manboster/blob/master/CONTRIBUTING.md).

## Branch Standard

We only open 3 branches:

`master`: the main branch of current stable version (when versioning, it will be merged)

`0.x.0-fix`: the fixing version branch (used for last version's safety patches)

`dev`: the developing branch of the next version
20 changes: 10 additions & 10 deletions zh-cn/docs/gatekeeper.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,27 +3,27 @@
> [!NOTE]
> 此翻译部分内容由 Kimi K2.6 和 Gemini 3.1 Pro 提供,如果有任何疏忽和遗漏,欢迎[向我们提交PR](https://github.com/manboster/docs/pull/new)进行修改!


## Manboster 中的 Gatekeeper 是什么?

Gatekeeper 是 Manboster 中一个 **强制启用、内置的安全模块** 。它默认基于可配置的**零信任架构**运行,作为系统操作的安全中间层。虽然你可以随时自定义其安全策略,但 Gatekeeper 模块本身已深度集成到系统中,**无法被禁用**。
Gatekeeper 是 Manboster 中一个 **强制启用、内置的安全模块** 。它默认基于可配置的**零信任架构**运行,作为系统操作的安全中间层。虽然你可以随时自定义其安全策略,但 Gatekeeper 模块本身已深度集成到系统中,**无法被禁用**。 Operating on a configurable Zero Trust architecture by default, it acts as a secure intermediary for system operations. While you can customize its security policies at any time, the Gatekeeper module itself is deeply integrated into the system and cannot be disabled.

## 执行流程

当系统处理工具调用请求时,Gatekeeper 会执行严格的验证与授权流程:

1. 系统接收到云端大语言模型的响应消息。如果其中包含工具调用请求,该请求会立即被路由到 Gatekeeper 模块。
1. The system receives a response message from the cloud LLM. If it contains a tool call request, it is immediately routed to the Gatekeeper module.
2. Gatekeeper 根据已定义的工具声明,验证请求参数。
3. Gatekeeper 评估用户的访问权限级别。如果用户未达到该工具的最低权限要求,请求将被自动拒绝。
3. Gatekeeper 评估用户的访问权限级别。如果用户未达到该工具的最低权限要求,请求将被自动拒绝。 If the user does not meet the tool's minimum permission requirements, the request is automatically rejected.
4. 如果权限充足,Gatekeeper 会检查授权缓存,查看用户此前是否已批准过该操作。
5. 如果缓存中无授权记录,Gatekeeper 会向用户展示决策表单。
6. 授权表单的有效期为 **10 分钟**。如果用户在此期间未采取任何操作,该工具调用将被自动拒绝。
5. If no cached approval exists, Gatekeeper surfaces a decision form to the user.
6. 授权表单的有效期为 **10 分钟**。如果用户在此期间未采取任何操作,该工具调用将被自动拒绝。 If the user takes no action within this window, the tool call is automatically rejected.
7. 用户可选择以下操作:
- **批准(Approve):** 批准接下来 10 分钟内的所有工具调用,或批准该特定工具 30–120 分钟(具体时长取决于工具的安全等级)。
- **委托给 Hachimi(Delegate to Hachimi):** 交由 Hachimi 安全模块处理这一次请求,或允许它在接下来一小时内自动处理所有请求。如果 Hachimi 判定请求安全,将自动执行。
- **拒绝(Reject):** 拒绝该特定工具 15 分钟,或在当前会话期间屏蔽所有工具调用。

8. 如果获得批准,流程将继续执行。如果用户手动拒绝,系统将中止操作并返回"用户手动拒绝"错误。
- **批准(Approve):** 批准接下来 10 分钟内的所有工具调用,或批准该特定工具 30–120 分钟(具体时长取决于工具的安全等级)。
- **委托给 Hachimi(Delegate to Hachimi):** 交由 Hachimi 安全模块处理这一次请求,或允许它在接下来一小时内自动处理所有请求。如果 Hachimi 判定请求安全,将自动执行。 If Hachimi deems a request safe, it will proceed automatically.
- **拒绝(Reject):** 拒绝该特定工具 15 分钟,或在当前会话期间屏蔽所有工具调用。

8. If approved, the process continues. 如果获得批准,流程将继续执行。如果用户手动拒绝,系统将中止操作并返回"用户手动拒绝"错误。

> [!NOTE]
> 在当前会话中屏蔽工具调用**仅作用于该特定会话**;其他活跃的聊天会话完全不受影响。
Loading