docs: add qq-ai-bot integration guide#20
Open
happysnaker wants to merge 3 commits into
Open
Conversation
审阅者指南为将 qq-ai-bot 集成到 LLOneBot 添加了文档，包括新的框架卡片，以及配置 OneBot11 WS 和 ACP agent 集成的分步指南。 文件级更改
提示和命令与 Sourcery 交互
自定义你的体验访问你的 dashboard 来：
获取帮助Original review guide in EnglishReviewer's GuideAdds documentation for integrating qq-ai-bot with LLOneBot, including a new framework card and a step-by-step guide to configure OneBot11 WS and ACP agent integration. File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
嗨，我发现了 1 个问题，并留下了一些整体反馈：
- 在
.env片段中，建议明确说明ONEBOT_ACCESS_TOKEN必须与 LLOneBot 的 OneBot11 WS 配置里的token值保持一致，以避免常见的连接/认证错误。 - 建议为
ACP_AGENT_COMMAND/ACP_AGENT_ARGS_JSON添加一个简短的具体示例（例如一个典型的traecli或其他 agent 命令），这样用户在接自己的 agent 时会有一个更清晰的起点。
给 AI Agents 的提示词
Please address the comments from this code review:
## Overall Comments
- In the `.env` snippet, it might help to explicitly call out that `ONEBOT_ACCESS_TOKEN` must match the `token` value in the LLOneBot OneBot11 WS config to avoid common connection/auth errors.
- Consider adding a short concrete example for `ACP_AGENT_COMMAND`/`ACP_AGENT_ARGS_JSON` (e.g., a typical `traecli` or other agent command) so users have a clearer starting point for wiring their own agent.
## Individual Comments
### Comment 1
<location path="content/docs/install_qq_ai_bot.mdx" line_range="43-52" />
<code_context>
+
+ONEBOT_MODE=forward
+ONEBOT_FORWARD_WS_URL=ws://127.0.0.1:3001
+ONEBOT_ACCESS_TOKEN=change-me
+ONEBOT_ALLOW_GROUP=true
+ONEBOT_REQUIRE_MENTION_IN_GROUP=true
+ONEBOT_ALLOW_PRIVATE=true
+ONEBOT_GROUP_CONFIG_FILE=./examples/group-rules.local.json
+ONEBOT_PROGRESS_MODE=message
+
+ACP_AGENT_COMMAND=your-acp-agent-command
+ACP_AGENT_ARGS_JSON=[]
+ACP_AGENT_WORKDIR=/path/to/your/workdir
+ACP_REUSE_SESSION=true
+ACP_VERBOSE_MODE=verbose
+```
+
+<Callout type="info">
+这里使用 **正向 WS**，因为 LLOneBot 会作为 OneBot11 服务端，`qq-ai-bot` 作为客户端去连接它。
+</Callout>
+</Step>
+
+<Step>
+### 配置 LLOneBot
+
+在 LLOneBot 中启用 OneBot11，添加 **正向 WS** 配置：
+
+```json5
+{
+ "type": "ws",
+ "enable": true,
+ "host": "127.0.0.1",
+ "port": 3001,
+ "token": "change-me",
+ "messageFormat": "array",
+ "reportSelfMessage": false
</code_context>
<issue_to_address>
**suggestion (bug_risk):** 明确说明 OneBot 访问令牌必须在 qq-ai-bot 和 LLOneBot 之间保持一致
这里 `.env` 的 `ONEBOT_ACCESS_TOKEN` 和 LLOneBot 配置中的 `token` 都用了 `change-me` 作为占位符，建议在其中一处明确标注“需与 LLOneBot OneBot11 配置中的 token 完全一致”，避免用户以为只是示例字符串，实际使用时填成不一致导致连接失败。
</issue_to_address>请帮我变得更有用！欢迎在每条评论上点 👍 或 👎，我会根据你的反馈改进后续评审。
Original comment in English
Hey - I've found 1 issue, and left some high level feedback:
- In the
.envsnippet, it might help to explicitly call out thatONEBOT_ACCESS_TOKENmust match thetokenvalue in the LLOneBot OneBot11 WS config to avoid common connection/auth errors. - Consider adding a short concrete example for
ACP_AGENT_COMMAND/ACP_AGENT_ARGS_JSON(e.g., a typicaltraeclior other agent command) so users have a clearer starting point for wiring their own agent.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the `.env` snippet, it might help to explicitly call out that `ONEBOT_ACCESS_TOKEN` must match the `token` value in the LLOneBot OneBot11 WS config to avoid common connection/auth errors.
- Consider adding a short concrete example for `ACP_AGENT_COMMAND`/`ACP_AGENT_ARGS_JSON` (e.g., a typical `traecli` or other agent command) so users have a clearer starting point for wiring their own agent.
## Individual Comments
### Comment 1
<location path="content/docs/install_qq_ai_bot.mdx" line_range="43-52" />
<code_context>
+
+ONEBOT_MODE=forward
+ONEBOT_FORWARD_WS_URL=ws://127.0.0.1:3001
+ONEBOT_ACCESS_TOKEN=change-me
+ONEBOT_ALLOW_GROUP=true
+ONEBOT_REQUIRE_MENTION_IN_GROUP=true
+ONEBOT_ALLOW_PRIVATE=true
+ONEBOT_GROUP_CONFIG_FILE=./examples/group-rules.local.json
+ONEBOT_PROGRESS_MODE=message
+
+ACP_AGENT_COMMAND=your-acp-agent-command
+ACP_AGENT_ARGS_JSON=[]
+ACP_AGENT_WORKDIR=/path/to/your/workdir
+ACP_REUSE_SESSION=true
+ACP_VERBOSE_MODE=verbose
+```
+
+<Callout type="info">
+这里使用 **正向 WS**，因为 LLOneBot 会作为 OneBot11 服务端，`qq-ai-bot` 作为客户端去连接它。
+</Callout>
+</Step>
+
+<Step>
+### 配置 LLOneBot
+
+在 LLOneBot 中启用 OneBot11，添加 **正向 WS** 配置：
+
+```json5
+{
+ "type": "ws",
+ "enable": true,
+ "host": "127.0.0.1",
+ "port": 3001,
+ "token": "change-me",
+ "messageFormat": "array",
+ "reportSelfMessage": false
</code_context>
<issue_to_address>
**suggestion (bug_risk):** Explicitly call out that the OneBot access token must match between qq-ai-bot and LLOneBot
这里 `.env` 的 `ONEBOT_ACCESS_TOKEN` 和 LLOneBot 配置中的 `token` 都用了 `change-me` 作为占位符，建议在其中一处明确标注“需与 LLOneBot OneBot11 配置中的 token 完全一致”，避免用户以为只是示例字符串，实际使用时填成不一致导致连接失败。
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Author
|
已按反馈补充：
更新已推到当前分支。 |
Author
|
补了一个更容易踩坑的说明：当前这条 LLOneBot → qq-ai-bot 的 forward WS 示例里， |
Author
|
Follow-up on the earlier Sourcery review notes: the current patch now includes both of the suggested clarifications:
Also, on the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
qq-ai-botguide under the framework integration docsqq-ai-botACP-based scaffoldProject page: https://happysnaker.github.io/qq-ai-bot/
Why
qq-ai-botis a relevant self-hosted QQ bot workflow for the LLOneBot ecosystem: it is not another low-level SDK, but a deployment-oriented TypeScript bot scaffold that separates transport, session orchestration, progress reporting, and ACP agent integration.由 Sourcery 提供的摘要
将 qq-ai-bot 记录为新的框架集成选项，并指导用户通过 OneBot11 WebSocket 和基于 ACP 的 agents 将其连接到 LLOneBot。
文档：
Original summary in English
Summary by Sourcery
Document qq-ai-bot as a new framework integration option and guide users through connecting it to LLOneBot via OneBot11 WebSocket and ACP-based agents.
Documentation: