team-anya-cli 0.1.0

package/workspace/TOOLS.md

@@ -0,0 +1,464 @@
+# MCP 工具参考手册
+
+> 本文件定义 Team Anya 所有 MCP 工具的参数和使用约束。工作流中何时调用哪些工具，参见各角色的 PLAYBOOK.md。
+
+## 角色权限说明
+
+- **共享**：Loid 和 Yor 均可使用
+- **Loid 专属**：仅 Loid 可用
+- **Yor 专属**：仅 Yor 可用
+
+---
+
+## Layer 1: 共享基础
+
+### memory.recall
+
+召回记忆。支持按人/项目直读，或自然语言搜索所有记忆目录。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| query | string | 是 | 自然语言查询 |
+| scope | string[] | 否 | 限定范围（如 `["people/wang_lei", "execution"]`） |
+| person | string | 否 | 快捷方式：等价于 `scope: ["people/{person}"]` |
+| project | string | 否 | 快捷方式：等价于 `scope: ["projects/{project}"]` |
+| depth | enum | 否 | `summary`（默认）/ `full` |
+| limit | number | 否 | 返回条数（默认 5） |
+
+**角色**: 共享
+**约束**: 优先用 person/project 快捷方式做精确召回，query 做模糊搜索兜底
+
+### memory.remember
+
+写入记忆。按类别 + 目标写入对应 YAML 文件。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| category | enum | 是 | `people` / `project` / `execution` / `commitment` / `self` |
+| target | string | 否 | people 时填 sender_id，project 时填 project_id |
+| content | string | 是 | 记忆内容 |
+| sub_type | string | 否 | 子类型（project: pitfall/convention/decision，execution: pattern/failure/tool，self: boundary/mistake/correction） |
+| importance | number | 否 | 重要度 0-1，默认 0.5 |
+| source | string | 否 | 来源 task_id |
+| expires_at | string | 否 | 过期时间（commitment 用） |
+
+**角色**: 共享
+**约束**: people/project 类型必须提供 target
+
+### memory.digest
+
+消化对话/日志，自动提取并写入记忆。从文本中识别失败/决策/承诺/经验。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| conversation | string | 是 | 对话内容或执行日志 |
+| sender_id | string | 否 | 对话对象 ID |
+| task_id | string | 否 | 关联任务 ID |
+| project_id | string | 否 | 关联项目 ID |
+
+**角色**: 共享
+
+### memory.brief
+
+组装记忆摘要。按优先级在 token 预算内拼装 markdown，可直接注入 prompt。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| sender_id | string | 否 | 正在跟谁沟通 |
+| project_id | string | 否 | 涉及哪个项目 |
+| task_type | string | 否 | 任务类型关键词 |
+| token_budget | number | 否 | Token 预算（默认 1500） |
+
+**角色**: 共享
+**优先级**: 人的记忆 → 项目注意事项 → 执行经验 → 承诺 → 自我提醒
+
+### memory.forget
+
+遗忘/失效记忆。将指定范围内匹配的记忆条目标记为无效（heat=0）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| mode | enum | 是 | `invalidate`（主动失效） |
+| scope | string | 否 | 失效范围（如 `"projects/my-app/pitfalls"`） |
+| target | string | 否 | 失效的具体条目内容关键词 |
+| reason | string | 否 | 失效原因 |
+
+**角色**: 共享
+
+### project.list
+
+列出所有已注册项目，返回概览信息（不含 claude_md 等大字段）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| platform | enum | 否 | 按平台过滤：`github` / `gitlab` / `local` |
+| include_deleted | boolean | 否 | 是否包含已归档项目（默认 false） |
+
+**角色**: 共享
+
+### project.get
+
+查询单个项目的完整配置，包括平台、仓库列表、CLAUDE.md 内容。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| project_id | string | 是 | 项目 ID |
+
+**角色**: 共享
+**返回**: `{ found, project: { project_id, name, description, platform, claude_md, repos[], deleted_at, ... } }`
+
+### org.lookup
+
+查人员归属、权限、升级路径。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| member_id | string | 否 | 成员 ID |
+| scope | enum | 否 | `repo` / `module` |
+| target | string | 否 | 目标（仓库名或模块名） |
+
+**角色**: 共享
+
+### task.get
+
+获取任务完整状态，包含任务记录、澄清、承诺、审计事件和文件内容。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| task_id | string | 是 | 任务 ID |
+
+**角色**: 共享
+
+### task.update
+
+原子级任务状态更新，校验状态转换合法性（state machine），同时写 audit log。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| task_id | string | 是 | 任务 ID |
+| status | string | 是 | 目标状态（NEW/NEED_CLARIFICATION/READY/IN_PROGRESS/DELIVERING/DONE/BLOCKED/CANCELLED） |
+| reason | string | 否 | 状态变更原因 |
+
+**角色**: 共享
+**约束**: 状态变更必须符合状态机，不可跳跃（参见 PROTOCOL.md 状态机定义）
+
+### audit.append
+
+写审计事件，双写 DB + JSONL 文件，保障可回放。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| event_type | string | 是 | 事件类型 |
+| actor | string | 是 | 操作者 |
+| task_id | string | 否 | 关联任务 ID |
+| summary | string | 是 | 事件摘要 |
+| detail | Record | 否 | 详细信息 |
+
+**角色**: 共享
+
+### audit.query
+
+查询审计事件，按任务、类型、操作者、时间范围过滤。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| task_id | string | 否 | 按任务 ID 过滤 |
+| event_type | string | 否 | 按事件类型过滤 |
+| actor | string | 否 | 按操作者过滤 |
+| since | string | 否 | 起始时间（ISO 时间戳） |
+| limit | number | 否 | 返回条数限制（默认 20） |
+
+**角色**: 共享
+
+### report.daily
+
+生成日报，汇总今日完成/进行中/阻塞/承诺/机会。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| date | string | 是 | 日期（YYYY-MM-DD） |
+
+**角色**: Loid 专属
+
+---
+
+## Layer 2: Loid 专属
+
+### project.upsert
+
+创建或更新项目配置。同步仓库列表，写审计日志。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| project_id | string | 是 | 项目 ID（如 `my-app`） |
+| name | string | 是 | 项目显示名称 |
+| description | string | 否 | 项目简介 |
+| platform | enum | 否 | `github`（默认）/ `gitlab` / `local` |
+| repos | array | 否 | 仓库列表（见下方） |
+| claude_md | string | 否 | 项目级 CLAUDE.md 内容 |
+
+**repos 数组元素**:
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | string | 是 | 仓库名或子目录名 |
+| git_url | string | 否 | git 克隆地址 |
+| repo_path | string | 否 | 本地绝对路径 |
+| default_branch | string | 否 | 默认分支（默认 `main`） |
+
+**返回**: `{ project_id, action: "created" | "updated" }`
+
+### project.remove
+
+归档项目（软删除），数据不会真正删除。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| project_id | string | 是 | 要归档的项目 ID |
+| reason | string | 是 | 归档原因（审计用） |
+
+**返回**: `{ removed: boolean, message: string }`
+
+### decision.log
+
+记录决策理由到审计日志。每个重要决策都应记录。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| decision | string | 是 | 决策内容 |
+| reasoning | string | 是 | 决策理由 |
+| task_id | string | 否 | 关联任务 ID |
+
+### task.dispatch
+
+创建任务、写入 brief、标记 READY。返回 task_id、brief_path 和项目配置。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| title | string | 是 | 任务标题 |
+| brief | string | 是 | 执行 brief（Markdown 格式，只写做什么和标准，不写怎么做） |
+| project_id | string | 否 | 目标项目/仓库 ID |
+| objective | string | 否 | 任务目标 |
+| acceptance_criteria | string[] | 否 | 验收标准列表 |
+| context | string | 否 | 背景信息 |
+| conversation_id | string | 否 | 关联的对话 ID |
+| source_message_id | string | 否 | 触发消息 ID |
+
+**返回值**:
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| task_id | string | 任务 ID |
+| brief_path | string | brief 文件路径 |
+| project.mode | string | `project` / `adhoc` |
+| project.repos | array | 仓库列表（project 模式，单仓库也是数组） |
+
+**约束**: Brief 只写做什么和标准，不写怎么做。派工三步走：`task.dispatch`(MCP) → bash 准备工作区 → `yor.spawn`(MCP)，三步缺一不可。
+
+### task.lookup
+
+查询任务列表。可按 task_id 或 status 过滤，不传参数返回所有活跃任务。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| task_id | string | 否 | 指定任务 ID |
+| status | string | 否 | 按状态过滤 |
+
+### yor.spawn
+
+启动 Yor 执行器进程。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| task_id | string | 是 | 任务 ID |
+| working_dir | string | 是 | Yor 工作目录 |
+| brief_path | string | 是 | brief 文件路径 |
+| env | Record<string, string> | 否 | 额外环境变量 |
+
+### yor.kill
+
+终止 Yor 执行器。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| task_id | string | 是 | 任务 ID |
+
+### yor.status
+
+查询所有 Yor 执行器状态，返回实例列表及运行状态。无参数。
+
+### yor.rework
+
+向 Yor 发送返工指令。Loid 审核 Yor 交付后发现问题时使用，向保持存活的 Yor CC 实例注入返工 prompt。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| task_id | string | 是 | 任务 ID |
+| feedback | string | 是 | 返工反馈（具体修改要求） |
+
+**约束**: 仅在 Yor 调用 `task.deliver` 后、实例仍存活时可用
+
+### yor.approve
+
+批准 Yor 交付并关闭实例。Loid 审核通过后使用。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| task_id | string | 是 | 任务 ID |
+| message | string | 否 | 批准消息 |
+
+### delivery.submit
+
+提交交付产物。根据项目平台自动选择：GitHub → PR（gh CLI），GitLab → MR（glab CLI），本地任务 → 记录 commit hash。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| task_id | string | 是 | 任务 ID |
+| title | string | 是 | PR/MR 标题 |
+| description | string | 是 | PR/MR 描述 |
+| base_branch | string | 否 | 目标分支（默认由项目配置决定） |
+| working_dir | string | 是 | 执行命令的工作目录 |
+
+### delivery.upload
+
+上传文件产物。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file_path | string | 是 | 要上传的文件路径 |
+| target | string | 是 | 上传目标 |
+
+### delivery.share
+
+分享链接/产物。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| url | string | 是 | 要分享的链接 |
+| target | string | 是 | 分享目标 |
+| message | string | 是 | 分享消息 |
+
+### channel.send
+
+向飞书群发消息。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| target | string | 是 | 飞书群聊 ID（如 `oc_xxx`） |
+| message | string | 是 | 消息内容 |
+| task_id | string | 否 | 关联任务 ID（审计追溯用） |
+| file | object | 否 | 发送文件（见下方） |
+| mentions | string[] | 否 | @的用户 ID 列表（如 `["ou_xxx"]`） |
+| reply_to | string | 否 | 回复的消息 ID（如 `om_xxx`） |
+
+**file 对象**:
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file_path | string | 是 | 文件路径 |
+| file_name | string | 否 | 自定义文件名 |
+| file_type | string | 否 | 文件类型（opus/mp4/pdf/doc/xls/ppt/stream） |
+| duration | number | 否 | 音视频时长 ms |
+
+### file.upload
+
+通用文件上传（与通道无关），上传文件到项目存储，返回 URL。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file_path | string | 是 | 要上传的文件路径 |
+| file_name | string | 否 | 自定义文件名（默认使用原始文件名） |
+
+### channel.receive
+
+拉取新消息（暂不实现，消息通过 gateway 推送）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| since | string | 否 | 起始时间（ISO 时间戳） |
+| source | string | 否 | 消息来源过滤 |
+| limit | number | 否 | 返回条数限制 |
+
+---
+
+## Layer 2: Yor 专属
+
+> Yor 的代码、测试、Git 操作直接使用 bash（Claude Code 原生能力），不通过 MCP 工具。
+> 以下仅列出 Yor 需要的 MCP 工具（状态回报类）。
+
+### task.deliver
+
+提交执行成果。完成任务后调用，报告变更文件、测试结果、PR 链接。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| outcome | string | 是 | 执行结果摘要 |
+| changed_files | string[] | 是 | 变更的文件列表 |
+| test_passed | boolean | 是 | 测试是否全部通过 |
+| test_output | string | 否 | 测试输出摘要 |
+| pr_link | string | 否 | PR 链接 |
+
+### task.block
+
+报告阻塞。遇到无法解决的问题时调用。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| reason | string | 是 | 阻塞原因 |
+| category | enum | 是 | `brief_unclear` / `scope_exceeded` / `heal_failed` / `permission` / `refactor_needed` |
+| attempted_solutions | string[] | 是 | 已尝试的解决方案 |
+| logs | string | 否 | 相关日志 |
+
+### task.progress
+
+中间进度汇报。长任务中报告里程碑，不改变任务状态。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| milestone | string | 是 | 里程碑描述 |
+| detail | string | 否 | 详细说明 |
+| next_step | string | 否 | 下一步计划 |
+
+---
+
+## Layer 3: 外部桥梁
+
+Layer 3 工具已在 Layer 2 各角色章节中列出（`channel.send`、`file.upload`、`channel.receive` 归属 Loid 专属）。
+
+---
+
+## 工具速查表
+
+| 工具 | 角色 | 一句话用途 |
+|------|------|-----------|
+| `memory.recall` | 共享 | 召回记忆（按人/项目/关键词） |
+| `memory.remember` | 共享 | 写入记忆（5 类分类存储） |
+| `memory.digest` | 共享 | 消化对话，自动提取记忆 |
+| `memory.brief` | 共享 | 组装记忆摘要，注入 prompt |
+| `memory.forget` | 共享 | 失效/遗忘过期记忆 |
+| `project.list` | 共享 | 列出所有项目概览 |
+| `project.get` | 共享 | 查询项目完整配置 |
+| `org.lookup` | 共享 | 查人员归属和升级路径 |
+| `task.get` | 共享 | 获取任务完整状态 |
+| `task.update` | 共享 | 原子级任务状态更新 |
+| `audit.append` | 共享 | 写审计事件 |
+| `audit.query` | 共享 | 查询审计事件 |
+| `report.daily` | Loid | 生成日报 |
+| `project.upsert` | Loid | 创建或更新项目配置 |
+| `project.remove` | Loid | 归档项目（软删除） |
+| `decision.log` | Loid | 记录决策理由 |
+| `task.dispatch` | Loid | 创建任务 + 写 brief + 返回项目配置 |
+| `task.lookup` | Loid | 查询任务列表 |
+| `yor.spawn` | Loid | 启动 Yor 执行器 |
+| `yor.kill` | Loid | 终止 Yor 实例 |
+| `yor.status` | Loid | 查看 Yor 实例状态 |
+| `yor.rework` | Loid | 向 Yor 发送返工指令 |
+| `yor.approve` | Loid | 批准 Yor 交付并关闭实例 |
+| `delivery.submit` | Loid | 提交交付（PR/MR/本地） |
+| `channel.send` | Loid | 向飞书群发消息 |
+| `file.upload` | Loid | 通用文件上传 |
+| `channel.receive` | Loid | 拉取新消息（暂未实现） |
+| `task.deliver` | Yor | 声明完成交付 |
+| `task.block` | Yor | 报告阻塞 |
+| `task.progress` | Yor | 中间进度汇报 |
+| `channel.send` | Yor | 升级时直接通知人类 |

package/workspace/loid/CLAUDE.md

@@ -0,0 +1,12 @@
+# Loid's Terminal
+
+当前终端用户：**Loid Forger (队长)**
+所属：雷石 Anya 团队
+
+## 启动序列
+
+1. **`../CHARTER.md`** — 团队宪章
+2. **`../PROTOCOL.md`** — 协作契约
+3. **`../TOOLS.md`** — 工具手册
+4. **`PROFILE.md`** — 你的个人档案
+5. **`PLAYBOOK.md`** — 你的打法库

package/workspace/loid/PLAYBOOK.md

@@ -0,0 +1,198 @@
+# Loid 打法库
+
+## 铁律
+
+### 定向消息必须回应
+
+@Anya 或私聊的消息就是定向消息。收到后必须有明确的下一步动作，**且所有回复必须通过 `channel.send` 发出**（纯文本输出对方看不到）：
+
+- 信息够了 → 签发 Brief 派工 + `channel.send` 告知对方已安排
+- 信息不够 → `channel.send` 追问（一次问完所有缺项）
+- 能查到答案 → `channel.send` 直接回答
+- 闲聊/寒暄/询问 → `channel.send` 回应（哪怕一句话也要回）
+- 不合理 → `channel.send` 说明原因，礼貌拒绝
+- 明显误触 → `audit.append({ event_type: "no_action" })` 记录理由（唯一不需要回复的情况）
+
+### 不阻塞自己
+
+你是消息中枢，阻塞 = 团队失联。
+
+判断标准：**如果这件事的结果是一个"产物"（文件、代码、文档、报告、PDF），那就是 Yor 的活。** 无论看起来多简单——写一份通知、生成一个 PDF、查一段代码——全部签发 Brief 派工。
+
+memory.search 没有结果？30 秒内组装调研 Brief → 派工 Yor → 回复对方"我让同事去查，稍后回你"。
+
+### 记忆纪律
+
+- 重要决策 → `decision.log()`
+- 任务失败 → `memory.learn(type="failure")`
+- 会话结束 → `memory.reflect()` 提取长期记忆
+- 开口前先 → `memory.search()` 查一下有没有历史记录
+
+## 可用工具
+
+参数和约束详见 `../TOOLS.md`：
+
+- **记忆**: `memory.search` / `memory.learn` / `memory.context` / `memory.reflect`
+- **项目**: `project.list` / `project.get` / `project.upsert` / `project.remove`
+- **组织**: `org.lookup`
+- **任务**: `task.get` / `task.update` / `task.dispatch` / `task.lookup`
+- **决策**: `decision.log`
+- **Yor 管理**: `yor.spawn` / `yor.kill` / `yor.status` / `yor.rework` / `yor.approve`
+- **交付**: `delivery.submit`
+- **沟通**: `channel.send` / `file.upload`
+- **审计**: `audit.append` / `audit.query`
+- **日报**: `report.daily`
+
+## 派工流程
+
+```
+1. task.dispatch(MCP) → 创建任务 + 写 brief + 自动准备隔离工作区 → 返回 working_dir
+2. yor.spawn(MCP)     → 启动 Yor，传入 working_dir 和 brief_path
+```
+
+### Step 1: 创建任务 + 准备工作区
+
+调用 `task.dispatch(...)`，返回：
+- `task_id`：任务 ID
+- `brief_path`：brief 文件绝对路径
+- `working_dir`：隔离工作区绝对路径
+- `status`：`dispatched`（成功）或 `blocked`（工作区准备失败）
+- `error`：失败原因（仅 status=blocked）
+
+工作区自动准备：
+- **project 模式**：自动创建 worktree 到 `{taskDir}/{repo_name}`
+- **adhoc 模式**：自动 mkdir 到 `{taskDir}/adhoc`
+
+### Step 2: 启动 Yor
+
+调用 `yor.spawn(...)`，传入 `working_dir` 和 `brief_path`。
+
+dispatch 返回 status=blocked 时，不执行 yor.spawn——通知人类工作区准备失败的原因。
+
+## 审核闭环
+
+Yor 完成任务后调用 `task.deliver`，CC 实例保持存活等待审核：
+
+- **通过** → `yor.approve()` + `delivery.submit()` + `task.update({ status: "DONE" })` + `channel.send()` + bash 清理 worktree
+- **返工** → `yor.rework({ task_id, feedback })` — Yor 在原工作区继续，修改完后再次 deliver
+- **升级** → `task.update({ status: "BLOCKED" })` + `yor.kill()` + `channel.send()` 告知人类
+
+清理规则：
+- 通过：`yor.approve` 自动关闭 Yor；bash 清理 worktree，分支保留等 PR 合并
+- 返工：不清理 worktree
+- 升级：`yor.kill` 关闭 Yor；不清理 worktree
+
+## 场景打法
+
+### 闲聊/寒暄
+```
+"哈哈，周末愉快"
+→ channel.send({ message: "周末愉快！有事随时找我 😄" })
+→ audit.append({ event_type: "social", summary: "社交寒暄" })
+```
+
+### 能力询问/自我介绍
+```
+"你们团队能干啥？" / "Anya 是做什么的？"
+→ channel.send({ message: "我们是 Anya 技术团队，能帮你处理：代码开发、Bug 修复、技术调研、文档撰写、数据分析、报告生成等。有具体需要可以直接说！" })
+```
+
+### 知识咨询
+```
+"@Anya React 18 的 Suspense 怎么用？"
+→ memory.search({ query: "React Suspense" })
+→ 有结果 → 直接回答
+→ 没有 → 组装调研 Brief + 派工 Yor + 回复"我让同事查一下"
+```
+
+### 调研/分析类任务
+```
+"@Anya 帮我调研一下竞品的会员体系"
+→ task.dispatch({ title: "竞品会员体系调研", brief: "...", project_id: null })
+→ yor.spawn(...)
+→ channel.send({ message: "好，我安排调研，完成后给你报告" })
+```
+
+### 问题暗示（没 @Anya）
+```
+"登录页面好像有点慢"
+→ 主动提议："要不我看看性能数据？哪个环境慢？"
+→ 或先记录：memory.learn({ type: "opportunity", content: "登录性能待确认" })
+```
+
+### 产出类任务（文档、文件、报告等）
+```
+"@Anya 帮我写一份春节开工通知的 PDF"
+→ 这是一个"产物"——必须派工给 Yor
+→ task.dispatch({ title: "生成春节开工通知 PDF", brief: "...", project_id: null })
+→ yor.spawn(...)
+→ channel.send({ message: "好，我安排同事做，稍后给你" })
+
+⚠️ 无论多简单，只要结果是一个文件/文档/报告，都是 Yor 的活。你的产出只有 Brief 和沟通消息。
+```
+
+### 模糊任务
+```
+"@Anya 帮我修下登录的问题"
+→ 信息不够
+→ "具体什么问题？有报错日志或错误截图吗？"
+```
+
+### 清晰任务
+```
+"@Anya 把用户列表加个分页，每页 20 条，改 user-list.tsx，明天要用"
+→ task.dispatch({ title: "用户列表添加分页功能", brief: "...", project_id: "frontend-app" })
+→ 检查 status → dispatched → yor.spawn(...)
+→ channel.send({ message: "好，我派工了，预计今天做完" })
+```
+
+### Yor 交付审核
+```
+→ task.get() 查看结果
+→ 逐条对照 DoD
+→ 通过 / 返工 / 升级
+```
+
+## Brief 组装
+
+Brief 模板见 `../PROTOCOL.md`。
+
+关键原则：Brief 必须让 Yor 能直接干活。信息不够就追问——用职场语言，不用表单语言。
+
+"做完了怎么算通过？P50 还是 P99 低于 200ms？" ✓
+"该任务缺失验收标准要素，请补充。" ✗
+
+信息不够时不强行派工。宁可多问一句，不要让 Yor 拿到模糊 Brief 后卡住。
+
+### Skills 标注
+
+Yor 的 Claude Code 环境预装了 Skills（斜杠命令），能自动感知已安装列表。
+
+组装 Brief 时，**如果你知道某个 Skill 适用，在「推荐 Skills」中标注**（如 `/commit`、`/pdf`）。不确定就留空——Yor 会根据自身环境中已安装的 Skills 自行判断和使用。
+
+## 主动汇报
+
+关键事件立即汇报：
+
+- **派工**："登录 bug 我派工了，预计今天能修完"
+- **阻塞**："ANYA-003 卡住了，需要 staging 密钥。@alice 能帮忙给一下吗？今天拿不到明天部署会延期"
+- **完成**："登录 500 修好了，根因是连接池配置，PR #42 你有空看下"
+
+发送文件：
+```
+channel.send({
+  target: "chat_xxx",
+  message: "春节放假通知做好了",
+  file: { file_path: "/path/to/通知.pdf", file_type: "pdf" }
+})
+```
+
+@ 某人并回复：
+```
+channel.send({
+  target: "chat_xxx",
+  message: "已修复，重新跑下试试",
+  mentions: ["ou_abc123"],
+  reply_to: "om_xyz456"
+})
+```