初始化：每个终端接入邮箱时第一个调用。 做两件事： 1. 在当前目录生成必读文件 AGENTS.md（AI 每次对话都会自动读到它， 里面写着协作纪律，等于给 AI 装上"开工前先看板"的规矩）； 2. 创建本项目的共享公告文件（如果还没有）。 幂等：必读文件和共享公告已存在时不会覆盖，所以可以放心反复调用。

参数： project 项目名，不传就自动识别（git remote -> 标记文件 -> 文件夹名） include_claude 设为 True 时额外生成 CLAUDE.md（给 Claude Code 用）

非 git 目录下会自动生成 .board-project 标记文件（内容 = 项目名）， 文件夹从此绑定固定项目身份：以后从任何副本/目录进入都解析到同一块板。

看板：读取本项目的共享公告全文（认领区 + 共享决策 + 最新变更）。 开工前必看。返回的就是那个 Markdown 文件的内容。

参数 agent（可选，建议填）：填上你的代号后，本工具会把"发给你的未读定向消息" 贴在最前面，并把它们标记为已送达（下次不再重复出现）。别人用 send_note 派给你的活， 就是靠这里收到的。不填 agent = 老行为，完全不碰消息。

认领：声明"我是谁、我在做什么、我要动哪些文件"。 files 用逗号分隔，例如：src/auth/login.py, src/auth/schemas.py 如果这些文件和别的终端的占用中认领重叠，会被直接拒绝，并告诉你撞了谁。 同 agent 重复认领 = 续期：与本次文件重叠的旧声明作废、TTL 重新计时； 不重叠的认领保留（同 agent 可同时持有多个文件组的认领）。

参数： agent 你的名字/代号（比如 T1、coder-1） task 一句话说明任务 files 要动的文件或目录，逗号分隔

汇报：干完了。做三件事： 1. 把自己的占用中认领标记为"已汇报"（释放文件）； 2. 在"最新变更"里写一条流水（最多保留 MAX_HISTORY 条，旧的自动剪掉）； 3. 自动检查这次改动有没有和别人撞车（如果撞了会提醒，不拦截）。 如果自己的认领已超 TTL 过期，会提示先重新 claim_files 再汇报。

参数： agent 你的名字/代号（要和认领时一致） summary 干了什么、结果如何 files 这次实际改动的文件，逗号分隔（建议填，用于自动查冲突）

查冲突：开工前或收尾前调用，确认这些文件没有被别人占用。 files 用逗号分隔。返回冲突清单；没有冲突会明说"没有冲突"。 过期认领（超 TTL 已自动释放）不算冲突，但会提示原属终端。

取消认领：把某个终端的所有占用中认领标记为"已取消"，释放文件。 用在：任务取消了、终端掉线了、认领卡住没人动。 注意：只能取消占用中的认领；已汇报/已取消的不受影响。 认领已过期（超 TTL 自动释放）时无需再取消，工具会提示。

写决策：往共享决策区追加一条约定，所有终端 get_board 时都能读到。 用于定协议、记方案取舍、留踩坑结论——凡是"需要别人看见并遵守"的内容。

共享决策区的内容会被保留和累积，不随认领表滚动清理； 追加时带上 agent 和时间戳，方便追溯是谁、在什么时候定的。

参数： agent 你的名字/代号（要和认领时一致） decision 决策内容，一句话讲清楚"定了什么、为什么"

定向消息：给指定终端发一条点对点消息（对方 get_board 或 read_notes 时收到）。 用在：派活、报缺陷、接口变更通知、要回执的协调。

和 post_decision 的分工： post_decision = 广播：所有终端都该看到并遵守的约定 -> 进共享公告的决策区。 send_note = 定向：只发给某几个终端的一件事 -> 进收件箱，带未读计数和回执。

参数： agent 你的代号（发送方） to 收件人代号，逗号分隔（如 "D-1, D-2"）；填 * 表示全体 text 正文。派活时请写全：任务号、文件绝对路径、基线 SHA、完成条件 task 可选任务号（如 DS-MVP-D1-FRONT-MODULE-02），便于检索 request_id 可选重试标识；同发送方、同标识、同内容返回原消息，不重复发送

收件箱/发件箱：读定向消息。

参数： agent 你的代号 box 'inbox'（默认）= 别人发给我的；'outbox' = 我发出的（带谁回了执） limit 未读优先按最早顺序分页；无未读时返回最近历史（默认 50，上限 200） peek 仅 inbox 有效：True = 只看不推进未读游标（消息仍算未读）

get_board(agent=...) 也会自动贴出未读消息并标记送达； 本工具用于回看历史、确认没漏读、检查自己发出的消息有没有被回执。

记录回执状态；空 ids 只确认本 agent 已送达且未回执的消息。

status: received / processing / completed / blocked；已完成不能退回其他状态。 更新已有回执必须显式指定 ids；received 不代表任务完成。