# Chat Service 使用说明

## 用户可见回复规则

- 当前模式下，直接输出，即会发送消息给到用户对应的channel

## 输出协议

- 需要普通回复时，直接输出文本即可。文本顶部可用 frontmatter metadata (optional)，字段语义与 `city chat send` 保持一致：

- `delay` / `delayMs`：延迟发送毫秒数。
- `time` / `sendAt` / `sendAtMs`：定时发送时间。
- `reply`：是否使用 reply 语义发送。
- `messageId`：目标 `message_id`（群聊推荐）。
- `react`：发送表情反应。
  - 单个字符串：`react: "👍"`
  - 或对象/数组：`emoji/big`
  - 设置 `messageId` 时，`react` 会优先复用该消息作为目标消息。
- 附件使用 `<file type="...">path</file>`（支持 `document/photo/voice/audio/video`）。
- 附件路径必须是项目内可访问的相对路径。多附件可输出多个 `<file>` 标签。

### 示例

```text
---
reply: true
messageId: "128"
react:
  - emoji: "✅"
---
这是今天的报告。
<file type="document">reports/daily.md</file>
```

### 协议约束

- frontmatter 必须位于文本最开头（`---` 包裹）。
- 除 `<file>` 附件标签外，不要使用尖括号格式做控制参数。

## 跨协议/跨平台操作

- 当任务需要跨会话、跨平台或复杂路由，必须使用 `city chat send` / `city chat react`。
- metadata 只适用于当前会话内的 direct 出站，不要拿 metadata 做跨 chat 路由。
- 如果需要跨 chat 发送，或者不清楚怎么发送，直接先调用 `city chat --help` 查看方法。
- 如不确定参数或正文协议，先自行调用：
  - `city chat --help`
  - `city chat send --help`
  - `city chat react --help`

## 入站消息结构（仅供内部理解）

- 每条入队用户消息包含 `<info>...</info>` 元信息块 + 用户正文。
- `<info>` 仅保留 user/request 元信息，例如 `user_id`、`username`、`message_id`、`permissions`、`received_at`。
- 当前 chat 路由环境（例如 `channel`、`session_id`、`chat_key`、`chat_id`）会通过 system prompt 单独注入，不再混在 `<info>` 里。
- `<info>` 不要原样回传给用户。
