docs: standardize Context class documentation formatting

[Li-shi-ling]

• Unified all method docstrings to standard format
• Fixed mixed language and formatting issues
• Added complete parameter and return descriptions
• Enhanced developer experience for plugin creators
• Fixes [Feature] 关于astrbot.core.star 的 Context 类别提供合适的代码注释 #4429

Fixes #4429：改进Context类的代码注释，解决语言不统一、格式不统一的问题，提高插件开发者的使用体验。

Modifications / 改动点

修改了 astrbot/core/star/context.py 文件中的 Context 类文档字符串：

1. 统一了大部分方法的docstring格式为标准格式
2. 修复了混合语言和格式问题（如混合使用@param和标准格式）
3. 添加了完整的参数和返回值描述
4. 提高了文档的可读性和一致性

1. 检查所有方法是否使用统一的docstring格式
2. 验证没有混合使用@param、@return等非标准格式
3. 确认大部分公共方法都有完整的参数说明
4. 确保代码能够正常导入和编译
5. 运行ruff检查确保符合代码规范

• This is NOT a breaking change. / 这不是一个破坏性变更。

Screenshots or Test Results / 运行截图或测试结果

代码规范检查通过：

$ ruff format astrbot/core/star/context.py
All done! 0 files reformatted, 1 file left unchanged.

$ ruff check astrbot/core/star/context.py
All checks passed!

能够正常运行astrbot

---

Checklist / 检查清单

• 😊 如果 PR 中有新加入的功能，已经通过 Issue / 邮件等方式和作者讨论过。/ If there are new features added in the PR, I have discussed it with the authors through issues/emails, etc.
• 没有引入新功能只修改了注释
• 👀 我的更改经过了良好的测试，并已在上方提供了“验证步骤”和“运行截图”。/ My changes have been well-tested, and "Verification Steps" and "Screenshots" have been provided above.
  • 提供了详细的验证步骤和测试结果
  • 修改只涉及注释，不影响代码功能
• 🤓 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到了 requirements.txt 和 pyproject.toml 文件相应位置。/ I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in requirements.txt and pyproject.toml.
  • 本次修改只涉及代码注释，未引入任何新依赖
• 😮 我的更改没有引入恶意代码。/ My changes do not introduce malicious code.
• 修改仅限于文档字符串，不包含任何代码逻辑更改

额外说明

• 本PR只修改注释，不改变任何代码逻辑
• 保持了100%的向后兼容性
• 遵循项目的代码规范标准

Summary by Sourcery

标准化并丰富 Context 类的文档，以提升针对插件和 SDK 用户的清晰度和一致性。

文档更新：

• 统一 Context 方法的文档字符串风格，将原先混杂的格式替换为一致的参数化风格，并包含返回值和错误信息。
• 明确说明提供方选择、工具启用、消息处理、配置访问以及弃用说明等内容，以便更好地指导插件开发者。

Original summary in English

Summary by Sourcery

Standardize and enrich documentation for the Context class to improve clarity and consistency for plugin and SDK users.

Documentation:

• Unify docstring style across Context methods, replacing mixed formats with a consistent, parameterized style including return and error information.
• Clarify descriptions for provider selection, tool activation, messaging, configuration access, and deprecation notes to better guide plugin developers.

[sourcery-ai]

Hey - 我发现了两个问题，并给出了一些总体层面的反馈：

• 一些公共 SDK 方法之前使用了 Sphinx 指令，例如 .. versionadded:: 4.5.7 (sdk)，现在被转换成了普通的文本说明；如果这些内容会被网站端的 Sphinx/autodoc 使用，建议保留原来的指令格式，以免破坏文档的渲染效果。
• 废弃标记被统一成了叙述式的 Note 段落（例如 [DEPRECATED] → 该方法已弃用）；请再次确认项目偏好的废弃标注风格，并让这些 docstring 与现有的模式或装饰器保持一致，这样工具和用户才能一致地检测到已废弃的 API。

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Several public SDK methods previously used Sphinx directives like `.. versionadded:: 4.5.7 (sdk)` which have been converted into plain text notes; if these are consumed by Sphinx/autodoc for the website, consider keeping the directive format to avoid breaking the rendered docs.
- The deprecation markers were normalized into narrative `Note` sections (e.g. `[DEPRECATED]` → `该方法已弃用`); double-check the project’s preferred deprecation style and align these docstrings with any existing patterns or decorators so that tooling and users can consistently detect deprecated APIs.

## Individual Comments

### Comment 1
<location> `astrbot/core/star/context.py:164` </location>
<code_context>
     async def tool_loop_agent(
</code_context>

<issue_to_address>
**issue (bug_risk):** Clarify how **kwargs are propagated (to agent runner vs directly to the LLM) to avoid misuse.

The previous docstring made it clear that `**kwargs` are handled by the agent runner (e.g., `stream`, `agent_hooks`, `agent_context`, and other `runner.reset()` args) and are not passed through to the LLM. The new Chinese docstring lists params but omits this, which could mislead users into thinking arbitrary kwargs are forwarded to the LLM API. Please reintroduce a brief note that `**kwargs` are consumed by the agent loop/runner rather than transparently sent to the LLM.
</issue_to_address>

### Comment 2
<location> `astrbot/core/star/context.py:122-126` </location>
<code_context>
+            ChatProviderNotFoundError: 指定的聊天提供者 ID 未找到。
+            Exception: LLM 生成过程中的其他错误。
+
+        Note:
+            版本 4.5.7 新增。
         """
</code_context>

<issue_to_address>
**nitpick (typo):** Typo in `MessageSesion` type name in the note.

This appears to be a misspelling of `MessageSession` (missing the second "s"), which could confuse readers searching for the type. Please correct the spelling for clarity in the docs.

Suggested implementation:

```python
MessageSession

```

If `MessageSesion` is also used elsewhere in this file (for example, in other docstrings, comments, or type hints), the same replacement to `MessageSession` should be applied there as well to keep everything consistent.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

Original comment in English

Hey - I've found 2 issues, and left some high level feedback:

• Several public SDK methods previously used Sphinx directives like .. versionadded:: 4.5.7 (sdk) which have been converted into plain text notes; if these are consumed by Sphinx/autodoc for the website, consider keeping the directive format to avoid breaking the rendered docs.
• The deprecation markers were normalized into narrative Note sections (e.g. [DEPRECATED] → 该方法已弃用); double-check the project’s preferred deprecation style and align these docstrings with any existing patterns or decorators so that tooling and users can consistently detect deprecated APIs.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Several public SDK methods previously used Sphinx directives like `.. versionadded:: 4.5.7 (sdk)` which have been converted into plain text notes; if these are consumed by Sphinx/autodoc for the website, consider keeping the directive format to avoid breaking the rendered docs.
- The deprecation markers were normalized into narrative `Note` sections (e.g. `[DEPRECATED]` → `该方法已弃用`); double-check the project’s preferred deprecation style and align these docstrings with any existing patterns or decorators so that tooling and users can consistently detect deprecated APIs.

## Individual Comments

### Comment 1
<location> `astrbot/core/star/context.py:164` </location>
<code_context>
     async def tool_loop_agent(
</code_context>

<issue_to_address>
**issue (bug_risk):** Clarify how **kwargs are propagated (to agent runner vs directly to the LLM) to avoid misuse.

The previous docstring made it clear that `**kwargs` are handled by the agent runner (e.g., `stream`, `agent_hooks`, `agent_context`, and other `runner.reset()` args) and are not passed through to the LLM. The new Chinese docstring lists params but omits this, which could mislead users into thinking arbitrary kwargs are forwarded to the LLM API. Please reintroduce a brief note that `**kwargs` are consumed by the agent loop/runner rather than transparently sent to the LLM.
</issue_to_address>

### Comment 2
<location> `astrbot/core/star/context.py:122-126` </location>
<code_context>
+            ChatProviderNotFoundError: 指定的聊天提供者 ID 未找到。
+            Exception: LLM 生成过程中的其他错误。
+
+        Note:
+            版本 4.5.7 新增。
         """
</code_context>

<issue_to_address>
**nitpick (typo):** Typo in `MessageSesion` type name in the note.

This appears to be a misspelling of `MessageSession` (missing the second "s"), which could confuse readers searching for the type. Please correct the spelling for clarity in the docs.

Suggested implementation:

```python
MessageSession

```

If `MessageSesion` is also used elsewhere in this file (for example, in other docstrings, comments, or type hints), the same replacement to `MessageSession` should be applied there as well to keep everything consistent.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[Li-shi-ling]

from astrbot.core.platform.astr_message_event import AstrMessageEvent, MessageSesion
我去,原本代码这里MessageSesion就是少了个s啊,是原本代码就打错了？

[Soulter]

from astrbot.core.platform.astr_message_event import AstrMessageEvent, MessageSesion 我去,原本代码这里MessageSesion就是少了个s啊,是原本代码就打错了？

对的，当然 MessageSession 也是对的，MessageSesion 是其 alias。

[Soulter]

需要将注释更改为英文。

[Li-shi-ling]

需要将注释更改为英文。

已经修改
把llm_generate和tool_loop_agent方法的注释改回成为英文了
但是原代码中get_current_chat_provider_id方法的注释也是英文,我认为这个是会话管理器的一部分,并不是开发者API,所以依然保持中文