feat: export core Hermes skills

skills/communication/multichannel-messaging-discipline/references/feishu-bot-silent-in-group-diagnosis.md

@@ -0,0 +1,56 @@
+# 飞书 bot 在群里静默、私聊却正常 —— 诊断配方
+
+实证：2026-06-22 群「小Maggie工作群」(`oc_a927f86118216c36cb9394b0e95f2a11`)。WeiWei/颜伽艺在群里 @小Maggie 无反应，私聊正常。
+
+## 症状
+- 用户在飞书**群**里 @小Maggie，bot 不回。
+- 但**私聊**（DM）发消息 bot 正常回复。
+- gateway 进程活着，飞书连接日志显示 `[Feishu] Connected in websocket mode`。
+
+## 根因类别（按概率排序）
+1. **身份不匹配（display-name 撞名）** — 群里被 @ 的「小Maggie」其实是**另一个 bot 身份**（不同 open_id），不是当前 gateway 跑的那个 app。常见触发：做过「新 Agent 迁移 / provisioning」，新身份被拉进群并占用了群里「小Maggie」的 @ 目标。群 @ 解析到新身份的 open_id，旧 gateway（旧 app_id）的事件流里根本收不到这条，所以"不回"。**DM 仍正常，因为 DM 按会话路由、不按 @ 身份。** ← 本会话确诊就是这一类。
+2. 订阅/连接在空窗后失效（同类：企微 errcode 846609 静默两小时）。
+3. 发送侧失败：历史上见过 `[99992402] field validation failed`（连 plain-text 兜底也失败）——这是**发**不出去，不是**收**不到，必须区分。
+
+## 诊断步骤（命令均已实测可用）
+所有 lark-cli 命令加 `LARK_CLI_NO_PROXY=1` 前缀，避免凭据走 HTTPS_PROXY。
+
+**1. 确认 bot 在哪些群、拿群 chat_id：**
+```bash
+LARK_CLI_NO_PROXY=1 lark-cli im +chat-list --as bot
+```
+
+**2. 查 gateway 实际收到了这个群的哪些 inbound：**
+```bash
+grep "oc_<群id>" ~/.hermes/logs/gateway.log | grep -iE "Inbound|inbound message"
+```
+若最后一条 inbound 停在很久以前、之后空白 → gateway 根本没收到新群消息（排除"收到但没回"）。
+
+**3. 拉群的真实消息历史，和第 2 步对照：**
+> bot 身份读群历史会因缺 scope 失败：`+chat-messages-list --as bot` → 230027 / 99991672，缺 `im:chat:readonly` `im:chat.members:read`。**改用 `--as user`**。
+```bash
+LARK_CLI_NO_PROXY=1 lark-cli im +chat-messages-list \
+  --chat-id oc_<群id> --as user --order desc --page-size 30 --no-reactions --format json
+```
+返回 JSON 字段：`data.messages[]`，每条含 `content`(直接是文本)、`create_time`、`sender.{id,sender_type,name}`、`mentions[].{id,name}`。**注意不是 `items`/`body`** —— 用错字段会得到 `count=0` 的假空，误判成"群里没人发"。
+
+**4. 关键判定 —— 看 @ 到的是谁的 open_id：**
+群消息的 `mentions[].id` 就是被 @ 对象的 open_id。和当前 gateway 的 bot 身份对比：
+```bash
+# 当前 gateway 用的飞书 app_id
+python3 -c "import yaml;c=yaml.safe_load(open('/home/maggie/.hermes/config.yaml'));print(c['gateway']['platforms']['feishu'].get('extra',{}).get('app_id'))"
+```
+- 对照法：第 2 步里 gateway 正常工作时段，bot 在群里发言的 sender 是 `app cli_<app_id>`。拿这个和第 4 步 mentions 里「小Maggie」的 open_id 比。
+- 若群历史里「小Maggie」被 @ 的 open_id ≠ 当前 gateway bot 的身份 → **确诊身份不匹配**：群里有两个同名「小Maggie」，大家 @ 错了。
+
+**5. 旁证：DM 是否正常。** 私聊 inbound 在 gateway.log 里照常出现 → 证明连接/订阅活着，问题收敛到"群 @ 身份"这一层。
+
+## 结论怎么报
+- 这是技术/配置问题，按铁律修复决策交给技术负责人（WeiWei/Scott），不自作主张改。
+- 给三个方向：①新 Agent 接管群（@ 目标对到新身份 / 把新身份订阅配通）；②仍由旧 bot 管群（移除或换回群里的新「小Maggie」）；③过渡期走私聊。
+
+## Pitfalls
+- **别一看 bot 没回就说"掉线了"** —— 先分清"没收到（群 @ 身份不对 / 订阅失效）" vs "收到但没发出去（send 失败 99992402）"。
+- **lark-cli 读群历史/群成员要用 `--as user`**，bot 身份缺 scope。要让 bot 自己能读，得在开放平台给 `cli_xxx` 补 `im:chat:readonly` `im:chat.group_info:readonly` `im:chat.members:read`。
+- **JSON 字段名**：`+chat-messages-list` 返回 `data.messages[].content`，不是 `items[].body`。用错字段会得到误导性的 `count=0`。
+- **重启时 DNS 抽风是环境问题，不是代码问题** —— 重启日志里若有 `Temporary failure in name resolution`（open.feishu.cn / openws.work.weixin.qq.com），那是当时网络/DNS 短暂故障；飞书多半自己重连上了，企微可能没重连成功，单独核实企微在线状态即可，别当成代码 bug 去改。

skills/communication/multichannel-messaging-discipline/references/feishu-group-send-and-mention.md

@@ -0,0 +1,88 @@
+# 飞书群发消息 + @人（已验证配方 2026-06-16）
+
+目标：把消息发到**正确的飞书群**并 **@ 正确的人**，一次做对。依赖 `lark-cli`（lark-im 技能）。
+
+## 步骤
+
+### 1. 找出 bot 实际所在的群（不要猜 chat_id）
+```bash
+cd ~ && lark-cli im +chat-list --as bot
+```
+返回每个群的 `chat_id`、`name`、`description`、`owner_id`。挑出你和目标人**共处**的那个群。
+- 本环境已知群："Doro, Maggie, 魏玮"（描述"小Maggie工作群"）= `oc_a927f86118216c36cb9394b0e95f2a11`。
+- 若有多个候选群，按成员和描述确认，仍不确定就问用户，别赌。
+
+### 2. @人的格式（两种已验证写法，均触发真实可点击 @ + 通知）
+- **text 模式**：`--msg-type text`，content 形如 `{"text":"<at>…</at> 正文"}`，@ 标签 `<at user_id="ou_xxx">显示名</at>`（用 **open_id**；嵌进 JSON 字符串时内层引号按 JSON 规则转义）。@所有人 `<at user_id="all"></at>`。
+- **post 模式**（多行/结构化汇报推荐，2026-06-16 已验证）：post JSON 里 @ 用 at 元素 `{"tag":"at","user_id":"ou_xxx"}`，与文本元素 `{"tag":"text","text":"…"}` **同行**拼接，配 `--msg-type post`。结构：
+  `{"zh_cn":{"content":[[{"tag":"at","user_id":"ou_757f053c9d7aff6c73b18aa60c337756"},{"tag":"text","text":" 进展汇报…"}],[{"tag":"text","text":"第二行"}]]}}`
+- **不要用 `--markdown`** 发 @：会强制转 post 且 @ 处理不可靠，用显式 post JSON 自己控制。
+
+### 3. 先 dry-run 验证 payload
+```bash
+lark-cli im +messages-send --chat-id oc_xxx --as bot \
+  --content '{"text":"<at user_id=\"ou_757f053c9d7aff6c73b18aa60c337756\">Doro</at> 正文…"}' \
+  --msg-type text --dry-run
+```
+检查 body 里 chat_id、msg_type、@标签是否正确。
+
+### 4. 去掉 --dry-run 正式发送
+成功返回 `message_id` + `create_time`。把 message_id 和**北京时间**报给用户便于核对。
+
+## 发送前如何核实「这个 open_id 确实是目标本人」
+@错人是红线。理想是查通讯录，但本 bot **常缺 contact / chat 读权限**，按可靠性从高到低：
+
+1. **gateway.log 取地面真值（最可靠，无需任何 scope）**——平台事件原始数据，比 API、比记忆都硬：
+   ```bash
+   grep "oc_<群id>" ~/.hermes/logs/gateway.log | grep -oE "ou_[a-z0-9]{20,}" | sort | uniq -c | sort -rn
+   ```
+   再看「当前这条消息」的入站行确认发送者：
+   ```bash
+   grep "inbound message: platform=feishu" ~/.hermes/logs/gateway.log | tail
+   # → user=ou_xxx chat=oc_xxx msg='…' 即是谁在这个群说了这句话
+   ```
+   把刚收到那句话的 `user=ou_xxx` 与已知映射比对，一致才发。
+2. **已知 open_id 映射**（下方表 + memory），ID 没映射到人 → 先问不猜。
+3. **通讯录 API（常被 scope 挡）**：`lark-cli contact +get-user --user-id ou_xxx --user-id-type open_id --as user`。本环境 2026-06-16 报缺 `contact:user.basic_profile:readonly`；`im chat.members get` 也缺 `im:chat.members:read` 等。缺权限是**正常状态**，别卡在这里——退回方法 1。
+
+## 已知 open_id（核对身份用，新增/纠正后同步到 memory）
+- Doro = `ou_757f053c9d7aff6c73b18aa60c337756`（与 bot 私聊 chat=`oc_9292e11bd98ddb5a69ea2c2da10d4f12`）
+- Scott(魏玮) = `ou_04fade9a9335c09ad09846da2051b3c0`
+
+## 注意
+- `--as bot`：消息以应用 bot 名义发出，bot 必须已在目标群里。
+- lark-cli 是 API 工具，不是消息网关；bot 身份不代理用户（Scott 已纠正）。
+- 终端里 lark-cli 输出常带 HTTPS_PROXY 的 WARN 和版本更新 notice，是噪音，不影响结果；可 `grep -v "WARN\|proxy"` 过滤。
+
+## 发文件附件到群里（md/pdf/docx 报告，已验证）
+
+要把一份**文件**（错误分析 md、合同 docx、报告 pdf）发到群里，用 `--file`。常见组合：**先发文件附件，再发一条 @某人 的 post 说明**（文件本身不能 @ 人，说明消息负责 @）。
+
+```bash
+# 先发文件（--file 接 cwd 相对路径），成功返回 message_id 并打印 "uploading file: xxx"
+cd ~/lark_send_tmp && lark-cli im +messages-send \
+  --chat-id oc_a927f86118216c36cb9394b0e95f2a11 \
+  --as bot --file "./报告.md" \
+  --dry-run 2>&1 | grep -v "WARN\|proxy"   # 先 dry-run，确认后去掉 --dry-run
+# 再发 @某人 的 post 说明（见上「@人的格式」post 模式），把文件背景+要点写清楚
+```
+
+### ⚠️ 关键坑：`--file` 只接 cwd 相对路径，绝对路径被拒
+lark-cli 安全限制：`--file`（及 `--image`/`--video`/`--audio`）**拒绝绝对路径**（如 `/tmp/x.md`），路径解析 `..`/symlink 后必须仍在 cwd 内。
+**解法**：把文件复制到干净工作目录，`cd` 进去用 `./文件名` 发：
+```bash
+mkdir -p ~/lark_send_tmp && cp "/tmp/报告.md" ~/lark_send_tmp/
+cd ~/lark_send_tmp && lark-cli im +messages-send --chat-id oc_xxx --as bot --file "./报告.md"
+rm -rf ~/lark_send_tmp   # 发完清理
+```
+- 本地文件 lark-cli 会**先自动上传**再发 file 消息，无需手动 `images.create`/拿 file_key。
+- dry-run 时 file_key 显示占位符 `file_dryrun_upload` 是正常的，正式发送才真上传。
+- 同理发图片用 `--image ./x.png`，视频 `--video ./x.mp4 --video-cover ./cover.png`。
+
+## 已知群与人 ID（核对身份用）
+| 对象 | ID |
+|------|-----|
+| 飞书工作群"Doro, Maggie, 魏玮"（小Maggie工作群） | `oc_a927f86118216c36cb9394b0e95f2a11` |
+| Doro | `ou_757f053c9d7aff6c73b18aa60c337756`（私聊 chat `oc_9292e11bd98ddb5a69ea2c2da10d4f12`，别和群混） |
+| Scott / 魏玮 | `ou_04fade9a9335c09ad09846da2051b3c0` |
+| @所有人 | `all` |

skills/communication/multichannel-messaging-discipline/references/wecom-proactive-notify-misrouting.md

@@ -0,0 +1,74 @@
+# 企微主动通知错投到错误的人 — 根因与诊断
+
+**症状**：一条本应私信给 A（如 Doro）的**主动通知**，落到了 B（如 JiaQian/Maggie）的企微私信里。
+实证（2026-06-17，Maggie 飞书原话）：私信收到"收到 JiaQian 发来的文件…请问如何处理？"——这条内容本应发给 Doro，却投到了 JiaQian 本人。
+
+**关键澄清：不是 userid 传错。** 会话 DB 里 `doro / JiaQian / WeiWei / ShaSha / QiuTing` 都是**各自独立的真实企微 userid**，`chat_id="doro"` 本身指向的就是 Doro。错投来自下面两个机制叠加，而非地址写错。
+
+## 根因 1：发送者归属靠"猜"（旧 `auto_notify_new_file.sh`）
+旧版 `get_sender()` 查 session DB 取"最近 5 分钟最后一个会话"：
+```sql
+SELECT user_id FROM sessions
+WHERE source='wecom' AND started_at > (now-300)
+ORDER BY started_at DESC LIMIT 1
+```
+多人**并发**时，这个"最近活跃会话"经常不是真正发文件的人 → 发件人张冠李戴。
+
+**已修复**：企微 adapter 落盘缓存文件时写 `.meta` 边车文件（`~/.hermes/cache/documents/<file>.meta`，字段 `sender_id / chat_id / chat_type`）。脚本改读 `${filepath}.meta`，不再靠"最近会话"猜。验证：`.meta` 内容形如 `sender_id=doro chat_id=doro type=dm`。
+
+## 根因 2：主动私信会"退化成回复"导致串号（adapter 层）
+`gateway/platforms/wecom.py` `WeComAdapter.send(chat_id, content)` 在做主动 `aibot_send_msg` 前有一段**回复优先兜底**（约 1430–1445 行）：
+```python
+reply_req_id = self._reply_req_id_for_message(reply_to)
+if not reply_req_id and chat_id in self._last_chat_req_ids:
+    reply_req_id = self._last_chat_req_ids[chat_id]   # ← 退化点
+if reply_req_id:
+    response = await self._send_reply_markdown(reply_req_id, content)  # 回复某条历史消息，而非主动私信
+else:
+    payload = {"chatid": chat_id, "msgtype": "markdown", ...}
+    if not chat_id.startswith("wr"):      # 群 ID 以 "wr" 开头；非 "wr" 当私聊
+        payload["chat_type"] = 1          # 主动单聊
+    response = await self._send_request(APP_CMD_SEND, payload)
+```
+`_last_chat_req_ids[chat_id]` 由**入站流量**填充（`_remember_chat_req_id`，约 533 行）。在长跑的 gateway 常驻进程里、多人并发时，某个 `chat_id` key 上记住的 `req_id` 可能绑定到**归属于另一个人的会话上下文**——于是"发给 doro"退化成"回复那条 req_id"，落到错误的人头上。
+
+> 注意两个独立的 dict：`_reply_req_ids`（按 **message_id** 存，给显式 `reply_to` 用）和 `_last_chat_req_ids`（按 **chat_id** 存，作群聊无 `reply_to` 时的兜底）。错投走的是后者这条 chat_id 兜底路径。
+
+## 谁还在踩这条路径（主动私信脚本）
+任何脚本调用 `_send_wecom(extra, 'doro', msg)` → `adapter.send()` 都会经过上面的回复兜底，存在同样的串号风险。已知：
+- `auto_notify_new_file.sh`：**主循环已不再调用** `notify_doro()`（非 QiuTing 文件只记日志、不通知任何人，符合信息隔离铁律；QiuTing 走静默 workflow 不发中间通知）。`notify_doro()` 函数仍**定义着**但无调用点 → 主路径安全。
+- `workflow-watchdog.sh`：其 `notify()` **仍在用** `_send_wecom(extra, 'doro', msg)`，workflow 崩溃重启时会触发，**未拆除的隐患**（低频但路径有风险）。
+
+## 修复方向（动手前须经用户确认，勿擅改代码/脚本）
+- **A（最稳）**：给 adapter 加"强制主动私信"参数，让脚本类通知**绕过 `_last_chat_req_ids` 回复兜底**，永远走 `chat_type=1` proactive 直发。一次修复，所有脚本受益。涉及代码库，宜拉熟代码的人（WeiWei）评审。
+- **B（最快）**：把 `workflow-watchdog.sh` 的通知目标改到本机日志/Scott，彻底不碰串号路径。改动小。
+- **C（最保守）**：先出一页纸根因+修复评审文档，定了再动。
+
+### ✅ 方向 A 已有现成实现：`~/.hermes/scripts/wecom_dm.py`（agent 可直接用）
+不必等改 adapter——这个独立脚本已经实现了"强制主动私信、绕过回复兜底"：自开 WebSocket，`aibot_subscribe` 认证后直接 `aibot_send_msg + chat_type=1`，**永不退化成回复**，一条消息=一次干净 proactive send、目标唯一。带 `--list` 白名单（别名↔userid 三方交叉验证）、`--dry-run`、回执 message_id。
+```bash
+python3 ~/.hermes/scripts/wecom_dm.py --list
+python3 ~/.hermes/scripts/wecom_dm.py --to doro --text "…" --dry-run
+python3 ~/.hermes/scripts/wecom_dm.py --to doro --text "…"
+```
+凡是 agent 会话里要私信某个企微人（绕开 home channel）的场景，**首选这个脚本**，而不是 `send_message(target='wecom:…')`（会静默落 home channel）或 `_send_wecom(extra,…)`（需 gateway 内部 `extra`，会话里拿不到）。`workflow-watchdog.sh` 等仍硬编码 `_send_wecom(extra,'doro',…)` 的脚本，理想改法就是切到这个干净发送器。
+
+## 诊断配方（只读，安全）
+```bash
+# 1. 脚本实际发了什么、发给谁（看 chat_id 与回执）
+tail -n 80 /tmp/auto_notify_new_file.log
+grep -aiE "Sending response .* to|aibot_send|chat_type|私信" ~/.hermes/logs/agent.log | tail -30
+
+# 2. 真实 userid ↔ 人 映射（确认不是地址写错）
+cd ~/.hermes/hermes-agent && source venv/bin/activate
+python3 -c "import sqlite3;d=sqlite3.connect('$HOME/.hermes/state.db');[print(r) for r in d.execute(\"SELECT user_id,COUNT(*),MAX(started_at) FROM sessions WHERE source='wecom' GROUP BY user_id ORDER BY 2 DESC\")]"
+
+# 3. .meta 边车归属是否正确
+find ~/.hermes/cache/documents -name '*.meta' -exec cat {} \;
+
+# 4. 谁还在用 doro 硬编码主动发送
+# search_files pattern: _send_wecom|DORO_ID="doro"  在 ~/.hermes/scripts
+```
+
+## 一句话结论
+"给 X 的消息错投给 Y"在企微里**首查 adapter 的 `_last_chat_req_ids` 回复兜底**与**脚本的发件人归属逻辑**，不要一上来就怀疑 userid 写错——userid 往往是对的，错在"主动私信退化成回复历史消息"。