docs: document register_custom_filter in listen-message-event guide

[AraragiEro]

What

Adds a Custom Filters section to the plugin guide (docs/zh and docs/en → dev/star/guides/listen-message-event.md) documenting filter.custom_filter / CustomFilter.

Why

register_custom_filter is implemented in astrbot/core/star/register/star_handler.py and exposed through astrbot.api.event.filter, but the guide only lists the built-in filters (event_message_type, platform_adapter_type, permission_type) and the event hooks. There is currently no documented way for plugin authors to write their own HandlerFilter.

Contents

• Writing a filter: subclass filter.CustomFilter, implement the synchronous filter(event, cfg) -> bool, keep raise_error when overriding __init__.
• Attachment points: a single command, a whole command group, or one sub-command — including the decorator order requirement (custom_filter must be placed above command).
• Combining filters with & / |.
• Behavior notes: a False result skips the handler silently, exceptions are caught by the framework and reported as Plugin <name>: <error>, and group/sub-command filters also hide blocked entries from the command tree.
• Cross-link from Multiple Filters, and @filter.custom_filter added to the event-hook incompatibility tip.

Notes

• Docs only, no code changes.
• Chinese and English guides are kept in sync (same section, same line layout).

Summary by Sourcery

Document how plugin authors can define and use custom filters in the listen-message-event guides.

Enhancements:

• Document custom filter creation, attachment points, composition, and runtime behavior in the English and Chinese listen-message-event plugin guides.

Documentation:

• Add synchronized English and Chinese documentation for filter.custom_filter and CustomFilter, including command, group, and sub-command usage plus event-hook compatibility guidance.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/en/dev/star/guides/listen-message-event.md" line_range="291" />
<code_context>
+
+#### Attaching to a Command Group
+
+When decorated on a `command_group`, every sub-command in the group is constrained:
+
+```python
</code_context>
<issue_to_address>
**Group restrictions do not apply**

When the group filter rejects a message matching one of its subcommands, the waking check skips the group handler but evaluates the matching subcommand independently; its `CommandFilter` does not check the group filter, so the subcommand can still run despite the guide promising a group-wide restriction.

Update the guide to clarify that a group-level custom filter constrains only the group handler, not its subcommands.

Also at `docs/zh/dev/star/guides/listen-message-event.md:291`, `docs/zh/dev/star/guides/listen-message-event.md:331`, `docs/en/dev/star/guides/listen-message-event.md:331`.
</issue_to_address>

Sourcery assessment

Approval pending. 1 finding to address first.

Blocking findings: docs/en/dev/star/guides/listen-message-event.md:291

---

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

• X
• Mastodon
• LinkedIn
• Facebook

[sourcery-ai]

Sourcery assessment

Approved.

[AraragiEro]

Good catch — confirmed and fixed in 2cd66a0.

The review is correct: a filter decorated on a command_group ends up in CommandGroupFilter.custom_filter_list and is only consulted by CommandGroupFilter.filter(), i.e. by the group handler. Sub-command handlers own a separate CommandFilter, whose filter() checks only its own custom_filter_list (astrbot/core/star/filter/command.py), so the parent group's filter is never evaluated for them.

Verified with a minimal probe against the filter classes on current master:

case	group handler	sub-command handler
group-level filter denies	False	—
group-level filter denies, name matches sub-command	—	True (still runs)
sub-command has its own filter that denies	—	False

Docs updated:

• Attaching to a Command Group now states the filter constrains the group handler only and does not cascade, with a warning explaining why and showing the per-sub-command pattern.
• The command-tree note now distinguishes the two cases: sub-command-level filters hide blocked entries, while a group-level deny blocks the group handler itself so no tree is rendered.
• Intro wording changed from "a command group" to "a command-group handler".

Separately: if the current behavior is not intended, the framework could let a sub-command's CommandFilter consult its parent group's filters. That would be a code change rather than a docs change, so I left it out of this PR — happy to open a separate issue if maintainers agree it is a bug.