block / block/buzz

Proposal: define CLI/SDK @mention behavior next to CJK text

Open
#3,904 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
32.7k
Forks
4.3k
Avg merge
1d 13h
Merged PRs (30d)
253

Description

## Summary

The CLI/SDK mention parser only recognizes `@Name` when the `@` is at the start of the message or preceded by ASCII whitespace.

That rule is explicitly documented in `crates/buzz-sdk/src/mentions.rs` as protection against treating email-like text such as `user@host` as a mention. This proposal is therefore asking for product/grammar clarification rather than assuming the current behavior is a bug.

In languages that commonly omit spaces, the same rule makes natural agent-authored handoffs look like mentions while emitting no `p` tag:

| Content | Current result |
|---|---|
| `@Scout please review` | resolves Scout |
| `你好 @Scout` | resolves Scout |
| `交给@Scout处理` | no mention tag |
| `user@example.com` | no mention tag, intentionally |

The third case is easy for a human or agent to write in Chinese, but the recipient is not notified and a mention-gated ACP agent does not wake.

## Question for maintainers

Should CLI/SDK auto-resolution remain strictly token-delimited, with agent callers expected to use explicit `--mention ` whenever notification delivery matters?

Or should the known-channel-member path support `@Name` immediately preceded by CJK text, while keeping the unknown-name fallback and email-style ASCII cases conservative?

## Possible narrow direction

If CJK-adjacent mentions are desired, one conservative option would be:

- only relax the left boundary when `Name` exactly matches a known member of the target channel;
- keep ASCII word/email-local characters before `@` excluded, so `user@host` behavior is unchanged;
- keep unknown-name fallback parsing whitespace/start-delimited;
- preserve self-mention suppression and existing mention caps;
- add regression cases for CJK prefixes, ASCII emails, partial names, and code regions.

This still has a tradeoff: Unicode email local parts can contain non-ASCII characters, and prose that discusses `@Member` could create an unintended notification. I would prefer maintainer confirmation of the intended grammar before proposing code.

## Related work

- #2526 and PRs #2547 / #2684 cover Markdown emphasis, spoiler, and parenthesis delimiters in the Rust parser.
- PR #2465 covers CJK-adjacent mention detection in Desktop.
- #3015 and PR #3047 cover warnings for unresolved CLI mentions.
- PR #3330 added explicit repeatable `--mention`, which is the reliable current path for agent-authored notifications.

This issue is specifically about the CLI/SDK left boundary when CJK prose is immediately adjacent to `@Name`; it does not propose changing Desktop autocomplete or non-member mention policy.

Contributor guide

Open the contributing guide

Research direction

Start with the mention grammar documented in crates/buzz-sdk/src/mentions.rs, then review the related issues and pull requests listed in the proposal, especially the CJK Desktop work and explicit --mention behavior. This issue is ready for implementation only after maintainers decide whether CJK-adjacent known-member mentions should resolve while preserving conservative email and unknown-name handling.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.