@gavinc-cn/touchstone-dsh 0.1.1 → 0.3.0

package/feishu.py

@@ -25,9 +25,14 @@ import urllib.error
 import urllib.request
 
 import db
+import feishu_conv
 import requests
 
 FEISHU_EVENTS = ("blocked_interaction", "task_failed", "card_review")
+# 未单独绑定项目时的默认事件集（与设置页 `GET /api/projects/<pid>/feishu-hook` 的
+# 默认回显一致：交互等待/任务失败开、卡片待审核默认关）。2026-10-10 之前回落分支
+# 写死全事件 ⇒ 界面显示「未勾选」而实际会推，是与设置页不一致的实障来源。
+FEISHU_DEFAULT_EVENTS = ("blocked_interaction", "task_failed")
 RETRY_DELAYS = (60, 300, 1800)     # 重试退避（秒）：3 次后标 failed 留痕
 SEND_TIMEOUT = 5                   # webhook POST 超时（秒）
 _TICK = 1.0                        # 发送线程轮询间隔（秒）
@@ -70,32 +75,71 @@ def user_config(user_id):
     return db.get_feishu_user_cfg(user_id)
 
 
+def notify_events(project_id):
+    """项目级推送事件闸门（**全通道共用**，2026-10-10 修「设置不生效」实障）。
+
+    群 webhook 文本推送（`push_event`）与飞书单聊交互卡片（`_dm_interaction_card`）
+    都只按本函数放行——此前单聊卡片是旁路发送、不受任何项目开关约束，用户把
+    「启用推送」与全部事件取消勾选后仍持续收到推送。
+
+    口径（先到先算）：
+    - **用户级总控 `push_enabled`**（设置页「飞书推送总控」，2026-10-10 新增）：
+      关 ⇒ 返回空集，**一票否决**——项目行开着也照样全通道静默。它必须先算：
+      旧用户级 `enabled` 只在下面的「无绑定行回落」分支参与判定，项目有绑定行时
+      完全不看它，故用户关掉旧开关仍会收到作答卡（实障观感「设置了不生效」）。
+      缺键按开处理（`.get(..., True)`）⇒ 存量配置升级后行为不变，零迁移。
+    - 有绑定行：`enabled=0` ⇒ **该项目全通道静默**（显式关闭，不回落用户配置）；
+      `enabled=1` ⇒ 取行内勾选的事件（可为空集＝都不推）。
+    - 无绑定行：回落项目所有者的默认集 `FEISHU_DEFAULT_EVENTS`，并受其用户级
+      旧开关 `enabled` 约束（关 ⇒ 空集）。项目被删（取不到 owner）时按 user_id=0
+      的配置判定，与 `hook_of` 同口径。
+
+    「按类别」开关不在本函数里另开用户级字段：项目行的 `events` 勾选即可分类
+    （作答卡片=`blocked_interaction`），且群与单聊卡片共用同一份。
+
+    返回 set[str]；空集 = 该项目不推任何事件。
+    """
+    row = db.get_feishu_hook(project_id)
+    proj = db.get_project(project_id)
+    owner_id = proj["user_id"] if proj else 0
+    cfg = user_config(owner_id)
+    if not cfg.get("push_enabled", True):   # 用户级总控：一票否决（先于项目行判定）
+        return set()
+    if row is not None:
+        if not row["enabled"]:
+            return set()
+        return {e for e in FEISHU_EVENTS if e in (row["events"] or "")}
+    if not cfg.get("enabled", True):
+        return set()
+    return set(FEISHU_DEFAULT_EVENTS)
+
+
 def hook_of(project_id):
-    """项目推送目的地：绑定行（enabled 且有 url）优先；显式 enabled=0 硬关闭
-    （不回落用户配置）；无绑定行或行内无 url 回落**项目所有者**的用户级配置
-    （其 enabled 总开关 + 默认 webhook）。附 base_url（通知「详情」链接）与
-    user_id（投递记录归属）。
+    """项目推送**群 webhook 目的地**：绑定行 URL 优先；行内无 url（或无绑定行）时
+    回落**项目所有者**的用户级默认 webhook（回落要求其总开关 enabled 开着且配了
+    `default_webhook`）。附 base_url（通知「详情」链接）与 user_id（投递记录归属）。
+
+    事件过滤不在这里判断——一律取 `notify_events`（群与单聊卡片同一闸门），
+    事件集为空即视为不推；这样「回落默认 webhook」时也尊重项目的事件勾选
+    （2026-10-10 前回落分支写死全事件）。
     返回 {"target","secret","events","base_url","user_id"} 或 None（不推）。"""
+    events = notify_events(project_id)
+    if not events:
+        return None
     row = db.get_feishu_hook(project_id)
     proj = db.get_project(project_id)  # 所有者为 0 时（项目被删）回落 user_config(0)={}
     owner_id = proj["user_id"] if proj else 0
     base_url = (user_config(owner_id).get("base_url") or "").rstrip("/") if proj else ""
-    if row is not None:
-        if not row["enabled"]:
-            return None
-        if row["webhook_url"]:
-            return {"target": row["webhook_url"],
-                    "secret": row["webhook_secret"] or "",
-                    "events": {e for e in FEISHU_EVENTS
-                               if e in (row["events"] or "")},
-                    "base_url": base_url, "user_id": owner_id}
+    if row is not None and row["webhook_url"]:
+        return {"target": row["webhook_url"], "secret": row["webhook_secret"] or "",
+                "events": events, "base_url": base_url, "user_id": owner_id}
     cfg = user_config(owner_id)
     if not cfg.get("enabled", True):
         return None
     if not cfg.get("default_webhook"):
         return None
     return {"target": cfg["default_webhook"], "secret": cfg.get("default_secret", ""),
-            "events": set(FEISHU_EVENTS), "base_url": base_url,
+            "events": events, "base_url": base_url,
             "user_id": owner_id}
 
 
@@ -453,6 +497,19 @@ def _build_interaction_card(ctx, project_name):
     kind = ctx.get("kind")
     cid = ctx.get("card_id")
     elements = []
+    # M6（2026-10-10）：方案先上——用户报障"仅凭选项无法决策"，故题面之前先给
+    # 折叠面板（Card 2.0 `collapsible_panel`；内部只放 markdown，飞书规定不能放
+    # form）+ 完整方案文档链接。两个字段都由 `_attach_plan` 挂在 ctx 上，
+    # 取不到方案（无会话/读不到转录）时整块不出现，卡片形状与旧版一致。
+    if ctx.get("plan_inline") and kind != "approval":
+        elements.append({
+            "tag": "collapsible_panel", "expanded": True,
+            "header": {"title": {"tag": "plain_text",
+                                 "content": "📄 agent 的方案 / 回答（点标题可折叠）"}},
+            "elements": [{"tag": "markdown", "content": ctx["plan_inline"]}]})
+    if ctx.get("plan_doc_url") and kind != "approval":
+        elements.append({"tag": "markdown",
+                         "content": f"📄 [查看完整方案（飞书文档）]({ctx['plan_doc_url']})"})
     if kind == "approval":
         lines = [f"**审批请求**：{ctx.get('action') or ctx.get('tool') or '工具调用'}"]
         if ctx.get("tool"):
@@ -528,11 +585,369 @@ def _build_interaction_card(ctx, project_name):
             "body": {"elements": elements}}
 
 
+# ---------- M6 作答方案：卡内摘要 + 完整方案飞书云文档（2026-10-10） ----------
+#
+# 用户报障（2026-10-10）：飞书作答卡片上只有题面（question 被 `_Q_TEXT_MAX=500`
+# 截断）与选项，agent 的方案/回答（末条 assistant 文本，实测 0–3217 字）与思考
+# （think，实测 122–18965 字）**一个字都不发** ⇒ 用户"仅凭选项无法决策"。
+# 本批把方案送进飞书，两条腿：
+#   ① 卡内折叠面板（`collapsible_panel`，Card 2.0）给摘要——不用跳转就能决策；
+#   ② 完整方案建飞书云文档（提问**全文** + 全部子题/选项/描述 + 回答 (+思考摘录)），
+#      链接放卡上——卡片放不下的部分在这里补全。
+#
+# 为什么不在文档里直接放选项让人点（2026-10-10 取证结论）：docx 块类型清单里没有
+# 投票/单选交互块（`lark-oapi` 生成的 `Block` 模型 63 个块字段无 poll/vote）；
+# 「文件编辑」事件 `P2DriveFileEditV1` 只带 file_token/操作者、**不含改了哪一块**；
+# 唯一"文档内点选"路线是内嵌多维表格 + `drive.file.bitable_record_changed_v1`
+# 事件（或文档评论事件），都要建表/授权/事件订阅 + 轮询，不适合"挂起等作答"的
+# 实时链路。故选项留在卡片上，文档承载方案与选项说明（文档内给文本补答语法）。
+
+PLAN_ENV = "TS_FEISHU_PLAN"        # =0 关闭本批全部新行为（回滚阀，回到只有题面+选项）
+_PLAN_INLINE_MAX = 1500            # 卡内折叠摘要上限（字符）
+_PLAN_DOC_MAX = 20000              # 文档正文上限（字符）
+_PLAN_THINK_MIN = 200              # assistant 回答短于该值 ⇒ 补 think 摘录
+_PLAN_THINK_MAX = 8000             # think 摘录上限（字符）
+_PLAN_DOC_TTL = 1800               # 建文档去重记录存活（秒）
+_PLAN_DOCS = {}                    # (card_id, qid) -> {"url": str, "at": float}
+_MD_BLOCK_MAX = 1800               # 文档单块文本上限（字符，超长块会被接口拒收）
+_ASK_TOOL = "ask_user_question"    # dsh 提问工具名（"提问前上下文"的切点）
+_DOC_TIMEOUT = 8                   # 文档类调用逐次超时（秒）
+
+
+def plan_enabled():
+    """作答方案增强总闸：`TS_FEISHU_PLAN=0` 关闭（一行回到"只有题面+选项"的现状）。"""
+    return (os.environ.get(PLAN_ENV) or "1") != "0"
+
+
+def _beijing_now():
+    """北京时间字符串：容器本地时区=UTC、用户/浏览器=Asia/Shanghai，给人看的文档
+    一律按 UTC+8 落（否则 22:00 的提问会写成 14:00，读者会误判成"8 小时前"）。"""
+    return time.strftime("%Y-%m-%d %H:%M", time.gmtime(time.time() + 8 * 3600))
+
+
+def _plan_session_texts(sid):
+    """会话转录 → 提问前的「方案/回答」文本 `{"assistant", "think"}`。
+
+    取「最后一次 `ask_user_question` **之前**」的末条 assistant 与末条 think——
+    多轮提问时只取当前这次提问的上下文（更早的回答不是本次的方案）。转录里还没有
+    该 tool_call（落盘滞后 / 旧会话）时回落整段末尾，语义相同（末尾即提问前内容）。
+
+    无 sid / 会话读不到 / 解析异常 ⇒ 两项皆空串：方案取数失败绝不影响卡片发送。
+    """
+    empty = {"assistant": "", "think": ""}
+    sid = str(sid or "").strip()
+    if not sid:
+        return empty
+    try:
+        import sessparse                     # 函数内懒 import：避免模块级循环依赖
+        res = sessparse.load("dsh", sid, "main") or {}
+        entries = res.get("entries") or []
+        if not res.get("found") or not entries:
+            return empty
+        cut = len(entries)
+        for i in range(len(entries) - 1, -1, -1):
+            e = entries[i] or {}
+            if e.get("kind") == "tool_call" and e.get("name") == _ASK_TOOL:
+                cut = i
+                break
+        assistant = think = ""
+        for e in reversed(entries[:cut]):
+            e = e or {}
+            if e.get("kind") == "assistant" and not assistant:
+                assistant = str(e.get("text") or "").strip()
+            elif e.get("kind") == "think" and not think:
+                think = str(e.get("text") or "").strip()
+            if assistant and think:
+                break
+        return {"assistant": assistant, "think": think}
+    except Exception:
+        return empty
+
+
+def _plan_inline_markdown(ctx, texts):
+    """卡内折叠摘要（上限 `_PLAN_INLINE_MAX`）：以末条 assistant 回答为主。
+
+    assistant 过短（< `_PLAN_THINK_MIN`）时补 think 摘录——实测这是常见形态：
+    回答只有一句"我给一份方案，你确认后再动手"、方案本体在 think 里（卡 949：
+    assistant 100 字 vs think 3513 字），不补的话卡上仍等于没有方案。
+    """
+    a = str((texts or {}).get("assistant") or "").strip()
+    t = str((texts or {}).get("think") or "").strip()
+    parts = []
+    if a:
+        parts.append(a)
+    if len(a) < _PLAN_THINK_MIN and t:
+        parts.append("**（思考摘录）**\n" + t)
+    if not parts:
+        return ""
+    md = "\n\n".join(parts)
+    if len(md) > _PLAN_INLINE_MAX:
+        md = md[:_PLAN_INLINE_MAX].rstrip() + "\n\n…（摘要已截断，完整内容见下方飞书文档）"
+    return md
+
+
+def _plan_question_md(ctx):
+    """提问**全文**（不截断）→ markdown：逐题题头/题面/补充说明/选项与描述/能力标注。
+
+    与卡片渲染（`_question_views` 按 `_Q_TEXT_MAX`/`_Q_OPT_MAX`/`_Q_DESC_MAX` 截断）
+    刻意分开：文档承载的正是卡片放不下的完整信息。旧调用面/测试替身只给平面字段
+    （question + 字符串选项）时按平面字段兜底。
+    """
+    qs = [q for q in (ctx.get("questions") or []) if q]
+    lines = []
+    if not qs:
+        q = str(ctx.get("question") or "").strip()
+        if q:
+            lines.append(q)
+        for i, o in enumerate(ctx.get("options") or [], 1):
+            lines.append(f"{i}) {_option_view(o)['label']}")
+        return "\n".join(lines)
+    n = len(qs)
+    for i, q in enumerate(qs, 1):
+        title = str(q.get("header") or q.get("question") or f"第 {i} 题")
+        lines.append(f"### {i}/{n} {title}")
+        if q.get("header") and q.get("question"):
+            lines.append(str(q["question"]))
+        body = str(q.get("body") or "").strip()
+        if body:
+            lines.append(body)
+        for j, o in enumerate(q.get("options") or [], 1):
+            ov = _option_view(o)
+            lines.append(f"{j}) {ov['label']}")
+            if ov["description"]:
+                lines.append(f"　　{ov['description']}")     # 全角缩进：描述次行
+        caps = []
+        if q.get("multi_select"):
+            caps.append("多选")
+        if q.get("allow_other"):
+            caps.append(f"可自定义：{q.get('other_label') or '其他'}")
+        if caps:
+            lines.append("（" + "；".join(caps) + "）")
+    return "\n".join(lines)
+
+
+def _plan_doc_title(ctx):
+    """文档标题：卡号 + 题头（云空间列表里能一眼认出是哪张卡哪次提问）。"""
+    head = str(ctx.get("header") or ctx.get("question") or "提问").strip()
+    head = (head.splitlines() or [""])[0]
+    return _clip_text(f"卡 {ctx.get('card_id')} · {head}", 80)
+
+
+def _plan_doc_markdown(ctx, texts, project_name=""):
+    """完整方案文档正文（markdown，经 `_md_blocks` 转飞书块）。
+
+    含：提问**全文**（卡片截断的部分在此补全）+ 末条 assistant 回答 + 作答指引
+    （文档内也能凭"回复序号"作答）+ 必要时的 think 摘录；整体按 `_PLAN_DOC_MAX` 截断。
+    """
+    cid = ctx.get("card_id")
+    a = str((texts or {}).get("assistant") or "").strip()
+    t = str((texts or {}).get("think") or "").strip()
+    lines = [f"# 卡 {cid} · agent 的方案与提问", "",
+             f"- 项目：{project_name or '—'}",
+             f"- 卡片：{str(ctx.get('title') or '')[:60]}",
+             f"- 时间：{_beijing_now()}（北京时间）"]
+    sid = str(ctx.get("session_id") or "").strip()
+    if sid:
+        lines.append(f"- 会话：{sid}")
+    if a:
+        lines += ["", "## agent 的方案 / 回答", "", a]
+    lines += ["", "## 提问（全文）", "", _plan_question_md(ctx)]
+    lines += ["", "## 如何作答", "",
+              "- 在飞书聊天里点卡片上的选项按钮 / 下拉即完成作答（多选题勾选后点「提交」）；",
+              f"- 也可以直接回复：「作答 {cid} <序号>」（多选逗号分隔，如 `作答 {cid} 1,3`），"
+              f"或「作答 {cid} <自定义文字>」写自由文本；",
+              "- 点选与文本作答可混用，已点选的题不必重复给。"]
+    if len(a) < _PLAN_THINK_MIN and t:
+        lines += ["", "## agent 的思考摘录", "", t[:_PLAN_THINK_MAX]]
+    md = "\n".join(lines)
+    if len(md) > _PLAN_DOC_MAX:
+        md = md[:_PLAN_DOC_MAX] + "\n\n…（正文已截断）"
+    return md
+
+
+def _md_plain(s):
+    """清掉 docx 文本块**不渲染**的行内 markdown 记号（`**粗**`/`*斜*`/反引号/`~~删~~`）：
+    留着只会以字面量出现在文档里（文档接口不做 markdown 渲染）。"""
+    s = re.sub(r"\*\*(.+?)\*\*", r"\1", s)
+    s = re.sub(r"(?<!\*)\*([^*\n]+?)\*(?!\*)", r"\1", s)
+    s = re.sub(r"~~(.+?)~~", r"\1", s)
+    return s.replace("`", "")
+
+
+def _md_blocks(text):
+    """极简 markdown → 飞书文档块（标题/项目符号/有序/引用/代码/分隔线/正文）。
+
+    - 强调符清掉（`_md_plain`）；表格分隔行（`| --- | --- |`）丢弃——飞书块不支持
+      表格，留着只有噪声；数据行按普通文本保留。
+    - 超长段落按 `_MD_BLOCK_MAX` 切块（单块过长会被文档接口拒收）。
+    - 产出恒为合法块形状，绝不抛（方案文档失败不该拖垮发卡链路）。
+    """
+    blocks, in_code, buf = [], False, []
+
+    def mk(bt, key, content):
+        return {"block_type": bt,
+                key: {"elements": [{"text_run": {
+                    "content": content,
+                    "text_element_style": {"bold": bt in (3, 4, 5)}}}],
+                    "style": {}}}
+
+    def add_text(bt, key, s):
+        if not s:
+            return
+        for i in range(0, len(s), _MD_BLOCK_MAX):
+            blocks.append(mk(bt, key, s[i:i + _MD_BLOCK_MAX]))
+
+    def flush_code():
+        if buf:
+            add_text(14, "code", "\n".join(buf))
+            buf.clear()
+
+    for raw in str(text or "").split("\n"):
+        line = raw.rstrip()
+        if line.strip().startswith("```"):
+            if in_code:
+                flush_code()
+                in_code = False
+            else:
+                in_code = True
+            continue
+        if in_code:
+            buf.append(line)
+            continue
+        s = _md_plain(line)
+        if not s.strip():
+            continue
+        if re.match(r"^\|[\s\-:|]+\|$", s.strip()):          # 表格分隔行：丢
+            continue
+        if s.startswith("### "):
+            add_text(5, "heading3", s[4:])
+        elif s.startswith("## "):
+            add_text(4, "heading2", s[3:])
+        elif s.startswith("# "):
+            add_text(3, "heading1", s[2:])
+        elif s.strip() == "---":
+            blocks.append({"block_type": 22, "divider": {}})
+        elif s.lstrip().startswith("> "):
+            add_text(15, "quote", s.lstrip()[2:])
+        elif re.match(r"^\s*[-*] ", s):
+            add_text(12, "bullet", re.sub(r"^\s*[-*] ", "", s))
+        elif re.match(r"^\s*\d+[.)] ", s):
+            add_text(13, "ordered", re.sub(r"^\s*\d+[.)] ", "", s))
+        else:
+            add_text(2, "text", s)
+    flush_code()
+    return blocks
+
+
+def _docx_create(title, md_text, cfg, open_id, timeout=_DOC_TIMEOUT):
+    """建飞书云文档并授权给用户 → 返回规范链接（任一步失败抛 FeishuRestError）。
+
+    配方（2026-10-10 真机实测通过）：
+    ① 建文档 `POST /docx/v1/documents`（需 `docx:document` 权限）；
+    ② 写正文 `POST /docx/v1/documents/{doc}/blocks/{doc}/children`（**单次 ≤50 块**）；
+    ③ `PATCH /drive/v1/permissions/{doc}/public?type=docx` 设「组织内可阅读」
+       ——**必做**：文档默认归应用所有，不做这步用户打不开；
+    ④ `POST /drive/v1/permissions/{doc}/members` 把用户加成协作者（**best-effort**：
+       失败只留痕，第③步已保证链接可读）；
+    ⑤ `POST /drive/v1/metas/batch_query`（body 带 `with_url=true`）取规范链接
+       ——漏 `with_url` 会 `code=0` 静默回空串，此时按租户域名兜底拼链接。
+    """
+    body = _rest("POST", "/open-apis/docx/v1/documents", json_body={"title": title},
+                 cfg=cfg, timeout=timeout) or {}
+    doc = (((body.get("data") or {}).get("document") or {}).get("document_id") or "")
+    if not doc:
+        raise FeishuRestError("建文档成功但没拿到 document_id")
+    blocks = _md_blocks(md_text)
+    for i in range(0, len(blocks), 50):
+        _rest("POST", f"/open-apis/docx/v1/documents/{doc}/blocks/{doc}/children",
+              json_body={"children": blocks[i:i + 50], "index": i},
+              cfg=cfg, timeout=timeout)
+    _rest("PATCH", f"/open-apis/drive/v1/permissions/{doc}/public",
+          params={"type": "docx"},
+          json_body={"link_share_entity": "tenant_readable",
+                     "external_access_entity": "open"}, cfg=cfg, timeout=timeout)
+    if open_id:
+        try:
+            # need_notification=false：文档链接已在卡上，再加一条"分享给你"的飞书
+            # 通知就是重复打扰（提问多时尤甚）；membership 只是链接分享被组织策略
+            # 限制时的兜底通道。
+            _rest("POST", f"/open-apis/drive/v1/permissions/{doc}/members",
+                  params={"type": "docx", "need_notification": "false"},
+                  json_body={"member_type": "openid", "member_id": open_id,
+                             "perm": "full_access"}, cfg=cfg, timeout=timeout)
+        except FeishuRestError as e:
+            print(f"feishu docx: 加协作者失败（第③步链接分享已可读，继续）: {e!r}",
+                  file=sys.stderr, flush=True)
+    meta = _rest("POST", "/open-apis/drive/v1/metas/batch_query",
+                 params={"user_id_type": "open_id"},
+                 json_body={"request_docs": [{"doc_token": doc, "doc_type": "docx"}],
+                            "with_url": True}, cfg=cfg, timeout=timeout) or {}
+    metas = (meta.get("data") or {}).get("metas") or []
+    url = (metas[0].get("url") if metas else "") or ""
+    return url or f"https://feishu.cn/docx/{doc}"     # 兜底：域名由飞书 301/302 重定向
+
+
+def _plan_doc_get(key):
+    """取该 (卡, 提问) 已建文档链接（顺带清过期记录，防无界增长）。"""
+    now = time.time()
+    for k in [k for k, v in _PLAN_DOCS.items() if now - v.get("at", 0) > _PLAN_DOC_TTL]:
+        _PLAN_DOCS.pop(k, None)
+    v = _PLAN_DOCS.get(key)
+    return v.get("url", "") if v else ""
+
+
+def _plan_doc_put(key, url):
+    """记账（同一提问只建一次文档；上限截断防无界增长）。"""
+    _PLAN_DOCS[key] = {"url": url, "at": time.time()}
+    while len(_PLAN_DOCS) > 128:
+        _PLAN_DOCS.pop(min(_PLAN_DOCS, key=lambda k: _PLAN_DOCS[k]["at"]), None)
+
+
+def _attach_plan(ctx, project_name, cfg, open_id=""):
+    """把「方案」挂到卡片上下文：`plan_inline`（卡内折叠摘要）+ `plan_doc_url`（文档链接）。
+
+    best-effort：**绝不外抛**——方案是锦上添花，卡本身必须发出去（历史上 form 元素
+    超限曾整卡静默丢失）。无会话（取不到方案）直接返回，不发无意义文档。
+    同一 (卡, 提问) 只建一次文档：调和器理论上一提问只调一次 `card_blocked`，此处是
+    重放/重试保险，且让重放复用同一链接。
+    """
+    try:
+        sid = str(ctx.get("session_id") or "").strip()
+        if not sid:
+            return
+        texts = _plan_session_texts(sid)
+        inline = _plan_inline_markdown(ctx, texts)
+        if inline:
+            ctx["plan_inline"] = inline
+        key = (int(ctx.get("card_id") or 0), str(ctx.get("qid") or ""))
+        cached = _plan_doc_get(key)
+        if cached:
+            ctx["plan_doc_url"] = cached
+            return
+        md = _plan_doc_markdown(ctx, texts, project_name)
+        if not md.strip():
+            return
+        url = _docx_create(_plan_doc_title(ctx), md, cfg, open_id)
+        if url:
+            _plan_doc_put(key, url)
+            ctx["plan_doc_url"] = url
+    except Exception as e:
+        print(f"feishu docx: 建方案文档失败（卡照发，仅卡内摘要）: {e!r}",
+              file=sys.stderr, flush=True)
+
+
 def _dm_interaction_card(project_id, ctx):
-    """旁路：向项目所有者的飞书单聊发交互卡片（绑定 + 应用凭据齐全才发）。
+    """旁路：向项目所有者的飞书单聊发交互卡片（**受 `notify_events` 闸门约束**，
+    再要求账号绑定 + 应用凭据齐全才发）。
+
+    2026-10-10 修实障：此前这里只看绑定与凭据 ⇒ 用户把项目「启用推送」与全部
+    事件取消勾选（甚至关掉用户级总开关）后，单聊卡片仍持续送达，设置形同虚设。
+    现在项目的 `blocked_interaction` 未开即直接不发（与群 webhook 同一闸门）。
     卡片是即时交互载体，不走 outbox（过期提问的分钟级重试无意义）；失败仅
     留痕——群 webhook 文本推送（push_event）始终是主通道，不受影响。"""
     try:
+        if "blocked_interaction" not in notify_events(project_id):
+            return
         proj = db.get_project(project_id)
         owner = (proj["user_id"] if proj else 0) or 0
         binding = db.get_feishu_binding_by_user(owner)
@@ -540,6 +955,10 @@ def _dm_interaction_card(project_id, ctx):
         if not binding or not cfg:
             return
         name = proj["name"] if proj else f"#{project_id}"
+        # M6：把 agent 的方案/回答挂到卡上（卡内折叠摘要 + 完整方案飞书文档链接）。
+        # 审批卡不做（它的"背景"由审批请求本身给出，建文档没意义）；开关可回滚。
+        if plan_enabled() and str(ctx.get("kind") or "") != "approval":
+            _attach_plan(ctx, name, cfg, binding["open_id"] or "")
         rest_send_card(binding["open_id"],
                        _build_interaction_card(ctx, name), cfg)
     except Exception as e:
@@ -562,6 +981,10 @@ def card_blocked(project_id, card, interaction):
     ctx = {
         "card_id": card["id"], "title": card.get("title") or "",
         "kind": kind,
+        # M6：方案取数（`_attach_plan` 读会话转录）与建文档去重都要这两个键；
+        # 缺了它们 M6 整块自动跳过（旧调用面/测试替身不受影响）。
+        "session_id": str(card.get("session_id") or ""),
+        "qid": str(interaction.get("qid") or ""),
         "question": interaction.get("question") or "",
         # 选项展示名取 label（交互归一后的字段，见 board._iw_interaction 的
         # dsh 分支；旧代码取不存在的 text 字段，推送里选项序号后恒空白）
@@ -669,8 +1092,9 @@ def _tenant_token(cfg):
     return out["tenant_access_token"]
 
 
-def _rest(method, path, *, params=None, json_body=None, cfg=None):
+def _rest(method, path, *, params=None, json_body=None, cfg=None, timeout=10):
     """飞书 REST 统一调用（按用户应用 cfg 鉴权）：非 0 业务码抛 FeishuRestError。
+    timeout 可按调用收敛（M6 建方案文档跑在 board 调和线程里，逐调用上限 8s）。
     路径规范化：调用方带/不带 /open-apis 前缀均恰好拼出一层（曾因调用方自带前缀
     + 此处再拼一层，请求打到 /open-apis/open-apis/... 恒 404 纯文本，且异常被吞
     表现为「机器人毫无反应」）。
@@ -687,7 +1111,7 @@ def _rest(method, path, *, params=None, json_body=None, cfg=None):
         try:
             r = requests.request(
                 method, url, params=params,
-                json=json_body, timeout=10,
+                json=json_body, timeout=timeout,
                 headers={"Authorization": f"Bearer {_tenant_token(cfg)}",
                          "Content-Type": "application/json"})
         except (OSError, ValueError) as e:
@@ -769,12 +1193,19 @@ def bot_open_id(cfg):
 
 SLASH_API = "/open-apis/application/v7/app_slash_commands"
 # (指令名, 中文说明, icon_key)：指令名与 _INTENT_RULES 的 /别名 一一对应（顺序即面板顺序）；
-# icon_key 取值见官方「Slash Command Icon Key 说明」，传错报 40000031
+# icon_key **必须**取 SLASH_ICON_KEYS（官方「Slash Command Icon Key 说明」全表）内的值，
+# 表外的键（含按语义自造的）创建即报 40000031
 SLASH_COMMANDS = (
     ("help",    "查看可用指令", "skill_outlined"),
     ("bind",    "绑定站点账号：/bind 绑定码", "member_outlined"),
     ("unbind",  "解除站点账号绑定", "clear_outlined"),
     ("project", "设置默认项目：/project 项目名", "home_outlined"),
+    ("current",  "查看默认项目与当前会话", "home_outlined"),
+    ("projects", "项目总览卡：点选设为默认项目", "database_outlined"),
+    ("sessions", "默认项目最近会话：点选绑定", "chat_outlined"),
+    ("new",      "在默认项目下新建会话并绑定：/new [标题]", "add-chat-ai_outlined"),
+    ("use",      "绑定已有会话：/use 序号|关键字|会话id前缀", "global-link_outlined"),
+    ("leave",    "解绑当前会话（保留默认项目）", "clear_outlined"),
     ("status",  "查看任务与看板摘要：/status [项目名]", "database_outlined"),
     ("cards",   "查找卡片：/cards 关键字（id 前缀 / 标题包含）", "codeblock_outlined"),
     ("approve", "通过待审核卡片：/approve 卡片", "flag_outlined"),
@@ -788,6 +1219,84 @@ _SLASH_NAMES = tuple(c for c, _, _ in SLASH_COMMANDS)
 _SLASH_PERM_CODES = (99991640, 99991672, 99991679)
 _SLASH_PERM_HINT = ("应用缺少「应用指令」权限：飞书开发者后台 → 权限管理，添加 "
                     "application:app_slash_command:read 与 write，创建并发布新版本后重试")
+_SLASH_ICON_HINT = "指令图标 icon_key 不合法（取值见官方 Slash Command Icon Key 说明）"
+# 官方「Slash Command Icon Key 说明」全量可选值（2026-10-09 抄自开放平台文档
+# https://open.feishu.cn/document/mcp_open_tools/agent-best-practices/agent-supports-slash-commands
+# 的同名章节，共 72 个；缺省 skill_outlined）。**表外的键一律非法**，创建/更新报业务码
+# 40000031——2026-10-09 真机取证：凭语义自造的 add_outlined / link_outlined 正是这样让
+# 同步停在 15/17 条（设置页红字即 _SLASH_ICON_HINT）。改图标前先在本表内选，
+# `tests/test_feishu_slash.py::test_slash_icons_are_official_keys` 会拦住表外的值。
+SLASH_ICON_KEYS = frozenset((
+    # AI 系（官方表前 31 项）
+    "skill_outlined", "light-ai_outlined", "chat-ai_outlined",
+    "ai-edit-continue_outlined", "education-ai_outlined", "ai-trans-switch_outlined",
+    "language-ai_outlined", "toolbar-more-ai_outlined", "image-ai_outlined",
+    "ai-agent_outlined", "ai-deepthink_outlined", "ai-style_outlined",
+    "ai-reminder_outlined", "ai-block_outlined", "ai-simplify-expression_outlined",
+    "promptword_outlined", "meeting-ai_outlined", "ai-improvewriting_outlined",
+    "slash-ai_outlined", "pa-cost-ai_outlined", "update-ai_outlined",
+    "diagnosis-ai_outlined", "ai-functions_outlined", "mic-ai_outlined",
+    "search-ai_outlined", "explanation-ai_outlined", "add-ai_outlined",
+    "add-chat-ai_outlined", "ai-notification_outlined", "dynamic-layout_outlined",
+    "ai-doc_outlined",
+    # 通用（官方表其余 41 项）
+    "home_outlined", "mail_outlined", "browser-mac_outlined", "flag_outlined",
+    "calendar-line_outlined", "sent_outlined", "gift_outlined", "tag_outlined",
+    "cloud_outlined", "bonus-payroll_outlined", "vote_outlined", "chat_outlined",
+    "emoji_outlined", "member_outlined", "robot_outlined", "mic_outlined",
+    "raisehand_outlined", "officephone_outlined", "effects_outlined", "labs_outlined",
+    "computer_outlined", "clear_outlined", "mouse_outlined", "cellphone_outlined",
+    "cursor_outlined", "plugin_outlined", "edit_outlined", "style-fillcolor_outlined",
+    "codeblock_outlined", "code_outlined", "folder_outlined", "file-link-word_outlined",
+    "file-link-sheet_outlined", "file-link-image_outlined", "global-link_outlined",
+    "champion_outlined", "local_outlined", "day_outlined", "waiting_outlined",
+    "database_outlined", "marketplace_outlined",
+))
+
+
+# ---------- M5 配置自动化：清单真源 / 事件打点 / 环境总闸 ----------
+# 2026-10-10：新用户「扫码一键接入 + 配置补齐 + 自检」批次（设计见
+# doc_ai/plan/202610/20261010_1700_飞书配置自动化（扫码一键接入与配置自检）.md）。
+# 下列清单是**唯一真源**：doctor 的逐项检查、register_app 的 addons 预置、
+# application/v7 config 的补齐三处共用同一份（改这里即可，勿在前端另抄一份）。
+PROVISION_ENV = "TS_FEISHU_PROVISION"   # =0 关闭全部写操作（doctor/status 只读不受影响）
+REQUIRED_SCOPES = (
+    ("im:message.p2p_msg:readonly", "tenant", "接收单聊消息"),
+    ("im:message.group_at_msg:readonly", "tenant", "接收群聊 @机器人 消息"),
+    ("im:message:send_as_bot", "tenant", "以机器人身份发消息/卡片"),
+    ("application:app_slash_command:read", "tenant", "读取斜杠指令"),
+    ("application:app_slash_command:write", "tenant", "注册斜杠指令"),
+)
+REQUIRED_EVENTS = (("im.message.receive_v1", "接收消息"),)
+REQUIRED_CALLBACKS = (("card.action.trigger", "卡片按钮回调"),)
+EVENT_FRESH_S = 300                     # doctor 判「事件订阅真生效」的新鲜窗口（秒）
+SEND_PROBE_MIN_S = 60                   # send_probe 每用户频控（秒），防连点刷屏
+PROVISION_TTL = 600                     # 扫码流程状态存活上限（秒），过期视为 idle
+
+# 应用配置/发布端点（官方 application/v7；能力开关在 ability 子路径）
+_APP_ABILITY_API = "/open-apis/application/v7/applications/%s/ability"
+_APP_CONFIG_API = "/open-apis/application/v7/applications/%s/config"
+_APP_PUBLISH_API = "/open-apis/application/v7/applications/%s/publish"
+_APP_VERSIONS_API = "/open-apis/application/v6/applications/%s/app_versions"
+# 补齐应用配置所需的权限（冷启动点：扫码新建的应用默认没有它，需控制台加一次或管理员免审）
+_PATCH_SCOPE = "application:application:patch"
+_PATCH_SCOPE_HINT = (f"应用缺少「{_PATCH_SCOPE}」权限：请到开发者后台 → 权限管理添加该权限"
+                     "并创建版本发布；或把该权限对应用设为免审后再试")
+
+_LAST_EVENT_TS = {}    # user_id -> 最近一次收到飞书事件（消息/卡片回调）的时刻
+
+
+def _touch_event(user_id):
+    """事件到达打点：入站长连接的 handler 入口调用（消息与卡片回调都算）。
+    doctor 的「事件订阅是否真生效」只能靠真实事件证明（订阅方式配错时连接照样
+    建得起来），此时间戳即唯一证据；仅进程内存态，重启归零。"""
+    _LAST_EVENT_TS[user_id] = time.time()
+
+
+def provision_enabled():
+    """配置自动化写操作（扫码建应用/补齐配置/提交发布）总闸：TS_FEISHU_PROVISION=0 关闭。
+    只读的 status/doctor 不受影响——关掉后仍可体检，只是不能改用户应用配置。"""
+    return (os.environ.get(PROVISION_ENV) or "1") != "0"
 
 
 def _slash_description(desc):
@@ -828,7 +1337,7 @@ def slash_error_hint(err):
     if code in _SLASH_PERM_CODES:
         return _SLASH_PERM_HINT
     if code == 40000031:
-        return "指令图标 icon_key 不合法（取值见官方 Slash Command Icon Key 说明）"
+        return _SLASH_ICON_HINT
     if code == 99992402:
         return "指令参数校验失败：指令名需为不含「/」的标识符，说明不可为空"
     return str(err)
@@ -938,6 +1447,11 @@ def sync_slash_commands(user_id):
     failed = []
     need_scope = False
     for name, desc, icon in SLASH_COMMANDS:
+        if icon not in SLASH_ICON_KEYS:
+            # 本地预检：表外的键飞书必回 40000031，先在此拦下——省一次请求，
+            # 且不让远端停在「同步到一半」的状态（同步是逐条进行的）
+            failed.append(f"{name}: {_SLASH_ICON_HINT}")
+            continue
         try:
             buckets[_slash_upsert(cfg, name, desc, icon, by_name)].append(name)
         except FeishuRestError as e:
@@ -1064,9 +1578,16 @@ def _on_slash_perm_action(sender, value, cfg):
 
 HELP_TEXT = (
     "Touchstone 指令（单聊可用）：\n"
+    "直接发普通文字 = 与当前会话对话（未绑定会在默认项目自动新建）。\n"
     "· 帮助 — 本说明\n"
     "· 绑定 <码> — 绑定站点账号（绑定码在站点侧栏「设置」→ 飞书设置 生成）\n"
     "· 解绑 — 解除绑定\n"
+    "· 当前 — 查看默认项目与当前会话\n"
+    "· 项目 — 项目总览卡（点选即设为默认项目）\n"
+    "· 会话 — 默认项目最近活跃的 10 个会话（点选即绑定）\n"
+    "· 新建会话 [标题] — 在默认项目下新建并绑定\n"
+    "· 绑定会话 <序号|标题关键字|会话id前缀> — 绑定已有会话\n"
+    "· 解绑会话 — 只解绑会话，保留默认项目\n"
     "· 默认项目 <项目名> — 设置默认项目\n"
     "· 状态 [项目名] — 任务与看板摘要\n"
     "· 卡片 <关键字> — 找卡片（id 前缀/标题包含）\n"
@@ -1210,11 +1731,13 @@ def _ws_run(user_id, cfg):
         return  # 依赖未装：入站禁用（M1 出站 webhook 不受影响）
 
     def _handler(data):
+        _touch_event(user_id)      # 事件到达打点（doctor 判「订阅是否真生效」）
         _on_message_event(data, cfg)
 
     def _on_card_sdk(data):
         # 返回值（toast）由 ws 客户端序列化回响应帧——丢弃则点击反馈（toast）
         # 恒不生效（SDK 路径此前即如此）
+        _touch_event(user_id)
         return _on_card_action(_card_sdk_to_dict(data), cfg)
 
     handler = (lark.EventDispatcherHandler.builder("", "")
@@ -1273,7 +1796,9 @@ def _seen_message(mid):
 def handle_message_event(evt, cfg=None):
     """入站消息主流程（M2 规则指令全为快路径，内联同步执行；M3 agent 解析需挪线程）：
     去重 → 群聊 @ 判定（未 @ 静默）→ 文本抽取（剥 @占位符）→ 绑定校验（未绑引导）
-    → 意图解析（未识别回帮助）→ 执行 → reply。任何异常吞掉。
+    → 意图解析 → 执行 → reply。**未识别文本**不是一律回帮助：单聊且通用对话开启
+    （`feishu_conv.enabled()`）时走 `feishu_conv.route_text` 投递给绑定的会话；群聊
+    与 `TS_FEISHU_CONV=0` 才回 `HELP_TEXT`（feishu.py:1337-1343）。任何异常吞掉。
     cfg = 连接所有者（收到消息的应用）的凭据，供回复/群聊判定使用。"""
     try:
         mid = evt.get("message_id")
@@ -1321,9 +1846,14 @@ def handle_message_event(evt, cfg=None):
                             "生成绑定码后在这里回复「绑定 <码>」完成绑定", cfg)
             return
         if intent is None:
-            rest_reply(mid, HELP_TEXT, cfg)
+            if evt.get("chat_type") != "group" and feishu_conv.enabled():
+                # 单聊未识别文本 → 通用对话路由（投递给当前会话；无会话按默认项目自动新建）
+                reply = feishu_conv.route_text(binding, text, cfg)
+            else:
+                reply = HELP_TEXT      # 群聊保持原行为：不落会话
+            rest_reply(mid, reply, cfg)
             return
-        reply = execute_intent(binding, intent, sender)
+        reply = execute_intent(binding, intent, sender, cfg)
         if reply:
             rest_reply(mid, reply, cfg)
     except Exception as e:
@@ -1355,7 +1885,8 @@ def _on_card_action(data, cfg):
     """卡片点击回调主流程：event_id 去重 → open_id 绑定校验（未绑 DM 引导）→
     动作分发（t=a 单题选项作答 / mq 多选类点选（多子题逐题点选、单题多选
     mini 表单）/ p 批准 / s 会话内批准 /
-    d 拒绝 / sc 快捷指令权限卡片「我已开通，重试注册」）→ 与文本指令共用的
+    d 拒绝 / sc 快捷指令权限卡片「我已开通，重试注册」/
+    dp 项目总览卡点选设默认项目 / ss 会话列表卡点选绑定会话）→ 与文本指令共用的
     _answer_by_token / _answer_multi_click / _decide_approval → DM 文本完整回执 + 返回 toast。
     value 精简键：t 动作（a 单题作答 / mq 多选类点选 / p 批准 / s 会话内批准 /
     d 拒绝）、c 卡号、n 题号（多题点选用）、i 选项序号（序号在执行器里重读服务端
@@ -1377,6 +1908,15 @@ def _on_card_action(data, cfg):
         # M4 权限引导卡片（t=sc）独立于卡片交互流：不带卡号，回调里重跑斜杠指令同步
         if t == "sc":
             return _on_slash_perm_action(sender, value, cfg)
+        # 通用对话卡片（t=dp 项目总览 / t=ss 会话列表）同样不带卡号：在既有看板
+        # 卡片白名单**之前**分流，看板回调（a/mq/p/s/d）路径一个字节都不动
+        if t in ("dp", "ss"):
+            binding = db.get_feishu_binding_by_open(sender)
+            if binding is None:
+                _dm_text(sender, "尚未绑定 Touchstone 账号：登录站点 → 侧栏「设置」→ "
+                                 "飞书设置，生成绑定码后在单聊回复「绑定 <码>」完成绑定", cfg)
+                return {"toast": {"type": "error", "content": "尚未绑定站点账号"}}
+            return feishu_conv.on_card_action(sender, binding, value, action, cfg)
         if t not in ("a", "mq", "p", "s", "d") or not key:
             return None
         binding = db.get_feishu_binding_by_open(sender)
@@ -1447,6 +1987,12 @@ _INTENT_RULES = (
     ("bind",            r"^(?:绑定|/bind)\s*([A-Za-z0-9]{4,8})$"),
     ("unbind",          r"^(?:解绑|/unbind)$"),
     ("default_project", r"^(?:默认项目|/project)\s+(\S+)$"),
+    ("current",         r"^(?:当前|/current)$"),
+    ("projects",        r"^(?:项目|/projects)$"),
+    ("sessions",        r"^(?:会话|/sessions)$"),
+    ("new",             r"^(?:新建会话|/new)(?:\s+(.+))?$"),
+    ("use",             r"^(?:绑定会话|/use)\s+(.+)$"),
+    ("leave",           r"^(?:解绑会话|/leave)$"),
     ("status",          r"^(?:状态|/status)(?:\s+(.+))?$"),
     ("card",            r"^(?:卡片|/cards?)\s+(.+)$"),
     ("approve",         r"^(?:通过|/approve)\s+(\S+)$"),
@@ -1489,9 +2035,10 @@ def bind_user(code, open_id):
     return None
 
 
-def execute_intent(binding, intent, sender_open_id):
+def execute_intent(binding, intent, sender_open_id, cfg=None):
     """绑定用户身份执行意图；返回回复文案（空串=不回复）。项目/卡片访问一律先过
-    归属（list_projects(user_id) 限用户项目），异常统一转友好文案。"""
+    归属（list_projects(user_id) 限用户项目），异常统一转友好文案。
+    cfg = 本次消息所属应用的凭据（转交通用对话层做卡片/回执）。"""
     action, g = intent["action"], intent["groups"]
     try:
         if action == "help":
@@ -1503,6 +2050,8 @@ def execute_intent(binding, intent, sender_open_id):
             return "已解绑。重新绑定请到站点生成新的绑定码"
         if action == "default_project":
             return _set_default_project(binding, g[0] or "")
+        if action in ("current", "projects", "sessions", "new", "use", "leave"):
+            return feishu_conv.conv_intent(binding, action, g, sender_open_id, cfg)
         return _execute_board_action(binding, intent, sender_open_id)
     except FeishuRestError:
         return "飞书接口调用失败，请稍后重试"
@@ -1510,18 +2059,23 @@ def execute_intent(binding, intent, sender_open_id):
         return "指令执行失败，请稍后重试"
 
 
-def _set_default_project(binding, name):
-    """设置单聊默认项目：精确名 → 唯一包含匹配；否则报项目不在列表。"""
+def _set_default_project(binding, name, project_id=0):
+    """设置单聊默认项目：`project_id` 非 0 时**按 id** 设（卡片点选 `t=dp` 路径），
+    否则按名匹配（精确名 → 唯一包含匹配）。两条路径共用
+    `feishu_conv.set_default_project`，换项目时自动清当前会话（设计 §3.2）。"""
+    if project_id:
+        project = feishu_conv._project_by_id(binding, project_id)
+        if project is None:
+            return "项目不在你的项目列表"
+        return feishu_conv.set_default_project(binding, project)
     user_id = binding["user_id"]
     projects = db.list_projects(user_id)
     for p in projects:
         if p["name"] == name:
-            db.set_feishu_default_project(binding["open_id"], p["id"])
-            return f"默认项目已设为「{name}」"
+            return feishu_conv.set_default_project(binding, p)
     hits = [p for p in projects if name in p["name"]]
     if len(hits) == 1:
-        db.set_feishu_default_project(binding["open_id"], hits[0]["id"])
-        return f"默认项目已设为「{hits[0]['name']}」"
+        return feishu_conv.set_default_project(binding, hits[0])
     return f"项目「{name}」不在你的项目列表"
 
 
@@ -2109,20 +2663,546 @@ def _send_loop():
 
 
 def start_notifier():
-    """幂等启动投递线程（server main 启动时调用一次；未配置时空转无害）。"""
+    """幂等启动投递线程（server main 启动时调用一次；未配置时空转无害）。
+
+    同时注册通用对话的消息终态钩子（feishu_conv.start，幂等）：答复回流靠它把
+    「跑完的会话消息」推回飞书 DM——这是本模块唯一的接线点（server.main 已调用
+    本函数），漏掉则回流全哑且无任何报错。
+    """
     global _SENDER_STARTED
     if _SENDER_STARTED:
         return
     _SENDER_STARTED = True
+    feishu_conv.start()                     # 幂等：注册 chat 的消息终态钩子
     threading.Thread(target=_send_loop, daemon=True,
                      name="feishu-notifier").start()
 
 
 # ---------- CLI（自测通道） ----------
 
+# ---------- M5 配置自动化：凭据快检 / 应用配置补齐 ----------
+
+def verify_credentials(user_id):
+    """凭据快检（保存凭据后的即时反馈）：token 可取 → 机器人信息可读，两步。
+
+    返回 {"ok": bool, "detail": str}，**绝不抛出**；无凭据时零请求。
+    今天保存凭据只写库不校验，错了只能翻日志——本函数是那个缺口的补口。"""
+    cfg = app_config(user_id)
+    if cfg is None:
+        return {"ok": False, "detail": "应用凭据未配置（App ID / App Secret）"}
+    try:
+        _tenant_token(cfg)   # 第一步：凭据正确性（失败码 10003/10014 等）
+        out = _rest("GET", "/open-apis/bot/v3/info", cfg=cfg)
+        # /bot/v3/info 的 bot 在响应**顶层**（无 data 包裹，同 bot_open_id 的读法）
+        bot = out.get("bot") or {}
+        name = bot.get("app_name") or "（未命名）"
+        act = bot.get("activate_status")
+        tail = "已启用" if act == 2 else f"启用状态={act}（可能未发布/未启用）"
+        return {"ok": True, "detail": f"凭据可用：机器人 {name}（{tail}）"}
+    except FeishuRestError as e:
+        return {"ok": False, "detail": str(e)}
+    except Exception as e:   # 兜底：网络/形态异常一律转文案，不抛到 HTTP 层
+        return {"ok": False, "detail": f"探测失败: {e!r}"}
+
+
+def _apply_error(e):
+    """补齐失败的文案：缺 patch 权限给精确开通引导，其余原样透出。"""
+    if _need_scope(e):
+        return _PATCH_SCOPE_HINT
+    return str(e)
+
+
+def provision_apply(user_id):
+    """把平台所需的**机器人能力 + 权限 + 长连接订阅 + 事件 + 回调**一次补齐到
+    用户自己的应用（只动本用户配置里的 app_id，前端永不传 app_id）。
+
+    两步：① PATCH .../ability 开机器人能力（{bot:{enable:true}}）；
+    ② PATCH .../config 一次带上 scope.add_scopes / event.subscription_type=websocket
+    + add_events / callback.add_callbacks。失败即停并如实报告（缺
+    application:application:patch 时给开通引导，不静默）。
+
+    返回 {"ok", "need_patch_scope", "error", "steps":[{key,label,ok,detail}]}。"""
+    if not provision_enabled():
+        return {"ok": False, "need_patch_scope": False, "steps": [],
+                "error": f"配置自动化已关闭（{PROVISION_ENV}=0）"}
+    cfg = app_config(user_id)
+    if cfg is None:
+        return {"ok": False, "need_patch_scope": False, "steps": [],
+                "error": "应用凭据未配置（App ID / App Secret），请先保存凭据"}
+    app_id = cfg["app_id"]
+    steps = []
+    # ① 机器人能力（错误码 210041 即「未开启机器人能力」，先开它）
+    try:
+        _rest("PATCH", _APP_ABILITY_API % app_id,
+              json_body={"bot": {"enable": True}}, cfg=cfg)
+        steps.append({"key": "ability", "label": "开启机器人能力",
+                      "ok": True, "detail": "已开启"})
+    except FeishuRestError as e:
+        steps.append({"key": "ability", "label": "开启机器人能力",
+                      "ok": False, "detail": str(e)})
+        return {"ok": False, "need_patch_scope": _need_scope(e),
+                "error": _apply_error(e), "steps": steps}
+    # ② 权限 + 订阅方式（长连接）+ 事件 + 回调（一次 PATCH，减少请求与半生效窗口）
+    body = {
+        "scope": {"add_scopes": [{"scope_name": n, "token_type": t}
+                                 for n, t, _ in REQUIRED_SCOPES]},
+        "event": {"subscription_type": "websocket",
+                  "add_events": [e for e, _ in REQUIRED_EVENTS]},
+        "callback": {"callback_type": "websocket",
+                     "add_callbacks": [c for c, _ in REQUIRED_CALLBACKS]},
+    }
+    try:
+        _rest("PATCH", _APP_CONFIG_API % app_id, json_body=body, cfg=cfg)
+        steps.append({"key": "config", "label": "权限 / 长连接订阅 / 事件 / 回调",
+                      "ok": True, "detail": "已写入（需发布新版本后生效）"})
+    except FeishuRestError as e:
+        steps.append({"key": "config", "label": "权限 / 长连接订阅 / 事件 / 回调",
+                      "ok": False, "detail": str(e)})
+        return {"ok": False, "need_patch_scope": _need_scope(e),
+                "error": _apply_error(e), "steps": steps}
+    return {"ok": True, "need_patch_scope": False, "error": "", "steps": steps}
+
+
+# ---------- M5 配置自动化：配置自检（doctor） ----------
+
+_LAST_PROBE_TS = {}    # user_id -> 上次发「测试消息」的时刻（send_probe 频控）
+
+
+def _doc_item(key, label, state, detail, hint=""):
+    """doctor 单项（state ∈ ok|fail|warn|skip；hint 是中文修复指引）。"""
+    return {"key": key, "label": label, "state": state, "detail": detail, "hint": hint}
+
+
+def doctor(user_id, send_probe=False):
+    """逐项配置体检（**只读为主**，绝不抛出）：把「存没存上、对不对、通不通」一次说清。
+
+    八项：creds（凭据齐全）/ token（凭据有效）/ bot（机器人能力与启用状态）/
+    inbound_ws（长连接线程在跑）/ inbound_event（**真实收到过事件**——订阅方式配错时
+    连接照样建得起来，此时间戳是唯一证据）/ slash_scope（斜杠指令权限）/
+    send_scope（发消息权限，send_probe=True 时才真发一条自检 DM，60s 频控）/
+    webhook（默认推送地址已配）。
+
+    返回 {"items":[{key,label,state,detail,hint}], "summary":{ok,fail,warn,skip}}。"""
+    cfg = dict(user_config(user_id) or {})
+    has_creds = bool(cfg.get("app_id") and cfg.get("app_secret"))
+    items = [_doc_item(
+        "creds", "应用凭据（App ID / App Secret）",
+        "ok" if has_creds else "fail",
+        "已配置" if has_creds else "未配置",
+        "" if has_creds else "在「飞书机器人配置」填入 App ID 与 App Secret 并保存")]
+
+    token_ok = False
+    if not has_creds:
+        items.append(_doc_item("token", "凭据有效性（tenant_access_token）",
+                               "skip", "凭据未配置，跳过", ""))
+    else:
+        try:
+            _tenant_token(cfg)
+            token_ok = True
+            items.append(_doc_item("token", "凭据有效性（tenant_access_token）",
+                                   "ok", "token 获取成功", ""))
+        except FeishuRestError as e:
+            items.append(_doc_item("token", "凭据有效性（tenant_access_token）",
+                                   "fail", str(e),
+                                   "核对取值：开发者后台 → 凭证与基础信息 的 App ID / App Secret"))
+        except Exception as e:
+            items.append(_doc_item("token", "凭据有效性（tenant_access_token）",
+                                   "fail", f"探测失败: {e!r}", "检查站点到 open.feishu.cn 的网络"))
+
+    if not token_ok:
+        items.append(_doc_item("bot", "机器人能力与启用状态",
+                               "skip", "凭据未通过，跳过", ""))
+    else:
+        try:
+            out = _rest("GET", "/open-apis/bot/v3/info", cfg=cfg)
+            bot = out.get("bot") or {}
+            act = bot.get("activate_status")
+            name = bot.get("app_name") or "（未命名）"
+            ok = act == 2
+            items.append(_doc_item(
+                "bot", "机器人能力与启用状态", "ok" if ok else "warn",
+                f"{name}（activate_status={act}）",
+                "" if ok else "应用能力 → 添加「机器人」，并在版本管理与发布里发布后生效"))
+        except FeishuRestError as e:
+            items.append(_doc_item("bot", "机器人能力与启用状态", "fail", str(e),
+                                   "应用能力 → 添加应用能力 → 机器人，然后创建版本发布"))
+        except Exception as e:
+            items.append(_doc_item("bot", "机器人能力与启用状态", "fail",
+                                   f"探测失败: {e!r}", "稍后重试"))
+
+    st = inbound_status(user_id)
+    if not has_creds:
+        items.append(_doc_item("inbound_ws", "入站长连接（长连接）", "skip",
+                               "凭据未配置，跳过", ""))
+    else:
+        items.append(_doc_item(
+            "inbound_ws", "入站长连接（长连接）",
+            "ok" if st.get("thread") else "fail",
+            "连接线程运行中" if st.get("thread") else "未运行",
+            "" if st.get("thread") else
+            "凭据保存后自动连接；仍不启动看站点日志，并确认事件订阅方式为「长连接」"))
+
+    last_ev = _LAST_EVENT_TS.get(user_id)
+    if not has_creds:
+        items.append(_doc_item("inbound_event", "事件订阅（真实收到过消息）", "skip",
+                               "凭据未配置，跳过", ""))
+    elif last_ev and (time.time() - last_ev) <= EVENT_FRESH_S:
+        items.append(_doc_item("inbound_event", "事件订阅（真实收到过消息）", "ok",
+                               f"{int(time.time() - last_ev)} 秒前收到过事件", ""))
+    else:
+        items.append(_doc_item(
+            "inbound_event", "事件订阅（真实收到过消息）", "warn",
+            "尚未收到过事件" if not last_ev else "最近一次事件已超过 5 分钟",
+            "给机器人**发一条消息**验证：开发者后台 → 事件与回调 → 订阅方式选「长连接」"
+            "并添加 im.message.receive_v1（按钮交互还需回调 card.action.trigger）"))
+
+    if not token_ok:
+        items.append(_doc_item("slash_scope", "斜杠指令权限", "skip", "凭据未通过，跳过", ""))
+    else:
+        try:
+            sl = slash_status(user_id)
+        except Exception as e:
+            # slash_status 只吞 FeishuRestError；响应形态意外（如 data 非 dict）会漏出
+            # 其他异常——doctor 承诺绝不外抛，这里降级为该项 fail。
+            items.append(_doc_item("slash_scope", "斜杠指令权限", "fail",
+                                   f"探测失败: {e!r}",
+                                   "稍后重试；仍失败可在「快捷指令」卡手动「注册 / 同步」看具体报错"))
+            sl = None
+        if sl is None:
+            pass                      # 探测异常：已在上面落 fail 项
+        elif sl.get("need_scope"):
+            items.append(_doc_item(
+                "slash_scope", "斜杠指令权限", "fail", sl.get("error") or "缺权限",
+                "权限管理 添加 application:app_slash_command:read 与 write，"
+                "并创建版本发布；开通后回设置页点「注册 / 同步到飞书」"))
+        elif sl.get("error"):
+            items.append(_doc_item("slash_scope", "斜杠指令权限", "warn",
+                                   str(sl["error"]), "可在设置页「快捷指令」卡重试"))
+        else:
+            items.append(_doc_item("slash_scope", "斜杠指令权限", "ok",
+                                   "权限可用", ""))
+
+    binding = None
+    try:
+        binding = db.get_feishu_binding_by_user(user_id)
+    except Exception:
+        binding = None
+    if not token_ok or not binding:
+        items.append(_doc_item(
+            "send_scope", "发消息权限（可选探测）", "skip",
+            "未绑定飞书账号，跳过" if not binding else "凭据未通过，跳过",
+            "" if binding else "先在下方生成绑定码并在飞书里发「绑定 <码>」"))
+    elif not send_probe:
+        items.append(_doc_item("send_scope", "发消息权限（可选探测）", "skip",
+                               "未探测（勾选「发送测试消息」后重跑自检）", ""))
+    elif (time.time() - (_LAST_PROBE_TS.get(user_id) or 0)) < SEND_PROBE_MIN_S:
+        items.append(_doc_item("send_scope", "发消息权限（可选探测）", "skip",
+                               f"{SEND_PROBE_MIN_S} 秒内已发过测试消息，稍后再试", ""))
+    else:
+        try:
+            rest_send_text(binding["open_id"],
+                           "🔍 Touchstone 配置自检：收到这条消息说明「发消息」权限已开通。",
+                           cfg)
+            _LAST_PROBE_TS[user_id] = time.time()
+            items.append(_doc_item("send_scope", "发消息权限（可选探测）", "ok",
+                                   "测试消息已发送，去飞书查看", ""))
+        except FeishuRestError as e:
+            items.append(_doc_item("send_scope", "发消息权限（可选探测）", "fail", str(e),
+                                   "权限管理 添加 im:message:send_as_bot 并创建版本发布"))
+        except Exception as e:
+            items.append(_doc_item("send_scope", "发消息权限（可选探测）", "fail",
+                                   f"探测失败: {e!r}", "稍后重试"))
+
+    hook = cfg.get("default_webhook") or ""
+    items.append(_doc_item(
+        "webhook", "默认推送 Webhook", "ok" if hook else "warn",
+        "已配置" if hook else "未配置（不影响机器人对话，只影响阻塞事件推送）",
+        "" if hook else "群设置 → 群机器人 → 添加自定义机器人，把 Webhook 填到设置页"))
+
+    summary = {"ok": 0, "fail": 0, "warn": 0, "skip": 0}
+    for it in items:
+        summary[it["state"]] = summary.get(it["state"], 0) + 1
+    return {"items": items, "summary": summary}
+
+
+# ---------- M5 配置自动化：扫码建应用（Device Flow 状态机） ----------
+
+_PROVISION = {}    # user_id -> {"state","url","error","app_id","steps","started_at","cancel"}
+_PROVISION_LOCK = threading.Lock()   # 「读状态 → 写状态」串行化（并发点两下只建一条流程）
+_REGISTER_MIN_VERSION = (1, 5, 5)   # register_app 的 lark-oapi 下限
+
+
+def _lark_min_ok():
+    """lark-oapi 版本是否达标——**只读包元数据，不 import SDK**。
+
+    为什么不 import：`lark_oapi.ws.client` 在模块级调 `asyncio.get_event_loop()`，
+    在非主线程首次 import 有拿不到事件循环的风险（且拖慢首次调用）；真正的 SDK
+    import 只发生在用户点「扫码创建」后的后台线程里（与既有 `_ws_run` 同路径）。"""
+    try:
+        import importlib.metadata as md
+        ver = md.version("lark-oapi")
+    except Exception:
+        return False
+    nums = []
+    for part in ver.split(".")[:3]:
+        digits = ""
+        for ch in part:
+            if not ch.isdigit():
+                break
+            digits += ch
+        nums.append(int(digits or 0))
+    return tuple(nums) >= _REGISTER_MIN_VERSION
+
+
+def _register_app_impl(on_qr_code, on_status_change, cancel_event, addons):
+    """SDK 调用的**可替换封装**（测试打桩点，也是唯一直接碰 SDK 的地方）。"""
+    if not _lark_min_ok():
+        raise RuntimeError("lark-oapi 版本过低或未安装（register_app 需 ≥1.5.5）")
+    import lark_oapi
+    return lark_oapi.register_app(on_qr_code=on_qr_code,
+                                  on_status_change=on_status_change,
+                                  cancel_event=cancel_event, addons=addons)
+
+
+def provision_supported():
+    """本机是否具备「扫码一键建应用」能力（lark-oapi ≥1.5.5 含 register_app）。"""
+    return _lark_min_ok()
+
+
+def _provision_addons():
+    """register_app 的 addons 载荷：**创建时**就把平台所需的权限/事件/回调带上。
+
+    这是绕开 `application:application:patch` 冷启动（新建应用默认没有该权限）
+    的主路径；preset=False 表示不要官方智能体模板（最小权限，只声明我们自己的清单）。"""
+    return {
+        "preset": False,
+        "scopes": {"tenant": [n for n, t, _ in REQUIRED_SCOPES if t == "tenant"]},
+        "events": {"items": {"tenant": [e for e, _ in REQUIRED_EVENTS]}},
+        "callbacks": {"items": [c for c, _ in REQUIRED_CALLBACKS]},
+    }
+
+
+def provision_status(user_id):
+    """扫码流程现状（设置页轮询口，只读）。等待超 TTL 即对外按失败呈现。
+
+    `app_id` = 在跑流程的应用优先，否则回落**用户配置里已接入的应用**——前端据此
+    决定「是否二次确认 + force」，只回进程内状态会让已有应用的用户永远发不出
+    force（扫码换应用死锁；站点重启后连扫码建过应用的用户也会掉进去）。"""
+    st = _PROVISION.get(user_id) or {}
+    state = st.get("state", "idle")
+    error = st.get("error", "")
+    if state == "waiting" and (time.time() - st.get("started_at", 0)) > PROVISION_TTL:
+        state = "failed"
+        error = error or "确认链接已超时（10 分钟有效），可重新发起"
+    # 回落取**配置里的 app_id**（不要求 secret 齐——只填了 App ID 也算「已接入」，
+    # 前端据此二次确认；真正的 force 闸门仍按 app_config（两件齐全）判定）
+    app_id = st.get("app_id") or ((user_config(user_id) or {}).get("app_id") or "")
+    return {"supported": provision_supported(), "enabled": provision_enabled(),
+            "state": state, "url": st.get("url", ""), "error": error,
+            "app_id": app_id, "steps": st.get("steps", []),
+            "age_s": int(time.time() - st["started_at"]) if st.get("started_at") else 0}
+
+
+def provision_start(user_id, force=False):
+    """发起扫码建应用（后台线程跑 Device Flow）。返回 {"ok","state","url","error"}。
+
+    闸门三条：总闸（TS_FEISHU_PROVISION=0）、SDK 可用性、已有应用需 force；
+    同一用户重复点击**不重复建流程**（返回既有流程的现状）。「读状态 → 写状态」
+    全程持 `_PROVISION_LOCK`：并发点两下不会各起一条 Device Flow（复阅 P1）。"""
+    if not provision_enabled():
+        return {"ok": False, "state": "idle", "url": "",
+                "error": f"配置自动化已关闭（{PROVISION_ENV}=0）"}
+    if not provision_supported():
+        return {"ok": False, "state": "idle", "url": "",
+                "error": "本机 lark-oapi 版本过低（register_app 需 ≥1.5.5），请升级依赖后重试"}
+    with _PROVISION_LOCK:
+        cur = _PROVISION.get(user_id) or {}
+        if cur.get("state") == "waiting" and \
+                (time.time() - cur.get("started_at", 0)) <= PROVISION_TTL:
+            return {"ok": True, "state": "waiting", "url": cur.get("url", ""), "error": ""}
+        cfg = app_config(user_id)
+        if cfg is not None and not force:
+            return {"ok": False, "state": "idle", "url": "",
+                    "error": f"已配置应用 {cfg.get('app_id')}；如需换应用请确认后重试"}
+        cancel = threading.Event()
+        _PROVISION[user_id] = {"state": "waiting", "url": "", "error": "", "app_id": "",
+                               "steps": [], "started_at": time.time(), "cancel": cancel}
+        threading.Thread(target=_provision_worker, args=(user_id, cancel), daemon=True,
+                         name=f"feishu-provision-{user_id}").start()
+    return {"ok": True, "state": "waiting", "url": "", "error": ""}
+
+
+def provision_cancel(user_id):
+    """取消进行中的扫码流程（置 cancel_event，SDK 侧即刻收尾）。"""
+    st = _PROVISION.get(user_id) or {}
+    if st.get("state") != "waiting":
+        return {"ok": False, "state": st.get("state", "idle"), "error": "当前没有进行中的扫码流程"}
+    st["cancel"].set()
+    st["state"] = "cancelled"
+    return {"ok": True, "state": "cancelled", "error": ""}
+
+
+def _provision_worker(user_id, cancel):
+    """后台主体：跑 Device Flow（回调里落链接/状态）→ 成功即写凭据 → 起长连接 →
+    自动补齐应用配置（能力/权限/事件/回调），全过程结果落 `_PROVISION` 供前端轮询。
+    凭据不入日志；任何异常都转状态文案，绝不外抛。"""
+    st = _PROVISION[user_id]
+
+    def on_qr(url):
+        st["url"] = url or ""
+
+    def on_status(info):
+        # 域切换（飞书/Lark）时链接作废，等 SDK 给新链接（旧 URL 已失效，不展示误导）
+        if isinstance(info, dict) and info.get("status") == "domain_switched":
+            st["url"] = ""
+
+    try:
+        out = _register_app_impl(on_qr, on_status, cancel, _provision_addons())
+    except Exception as e:
+        if st.get("state") != "cancelled":
+            st["state"] = "failed"
+            st["error"] = f"扫码创建失败: {e}"
+        return
+    if st.get("state") == "cancelled":
+        return
+    app_id = (out or {}).get("client_id") or ""
+    secret = (out or {}).get("client_secret") or ""
+    if not (app_id and secret):
+        st["state"] = "failed"
+        st["error"] = "扫码流程未返回应用凭据（可能超时或未确认），可重新发起"
+        return
+    # 合并写库：保留既有 enabled / webhook / base_url 等字段，只换应用凭据
+    cfg = dict(user_config(user_id) or {})
+    cfg["app_id"] = app_id
+    cfg["app_secret"] = secret
+    db.set_feishu_user_cfg(user_id, cfg)
+    _TOKEN_CACHE.pop(app_id, None)   # 新凭据：清同 app_id 的旧 token 缓存
+    st["app_id"] = app_id
+    try:
+        start_inbound_for(user_id)   # 起长连接（失败只留痕，状态里如实呈现）
+    except Exception as e:
+        print(f"feishu provision: 用户 {user_id} 长连接启动异常: {e!r}",
+              file=sys.stderr, flush=True)
+    applied = provision_apply(user_id)
+    st["steps"] = applied.get("steps") or []
+    st["state"] = "success"
+    st["error"] = "" if applied.get("ok") else \
+        f"应用已创建，但配置补齐未完成：{applied.get('error')}"
+
+
+# ---------- M5 配置自动化：提交发布 ----------
+
+def _next_version(items):
+    """版本号递增：取远端版本列表里的**最大语义版本**补丁位 +1（无版本回 1.0.0）。
+    解析失败的版本（非 x.y.z）忽略；比较用整数元组，避免 "1.0.10" < "1.0.3" 的字符串序陷阱。"""
+    best = None
+    for it in items or []:
+        raw = str((it or {}).get("version") or "").strip()
+        try:
+            nums = tuple(int(x) for x in raw.split("."))
+        except ValueError:
+            continue
+        if len(nums) != 3:
+            continue
+        if best is None or nums > best:
+            best = nums
+    if best is None:
+        return "1.0.0"
+    return "%d.%d.%d" % (best[0], best[1], best[2] + 1)
+
+
+def provision_publish(user_id, version=None, remark="", changelog=""):
+    """提交发布自建应用（POST application/v7/.../publish）：无待发布版本时由飞书自动建版本。
+
+    版本号缺省自动递增（见 `_next_version`）；发布后仍需**租户管理员审批**才线上生效
+    （无 API，走引导）。返回 {"ok","version","version_id","need_patch_scope","error"}。"""
+    if not provision_enabled():
+        return {"ok": False, "version": "", "version_id": "", "need_patch_scope": False,
+                "error": f"配置自动化已关闭（{PROVISION_ENV}=0）"}
+    cfg = app_config(user_id)
+    if cfg is None:
+        return {"ok": False, "version": "", "version_id": "", "need_patch_scope": False,
+                "error": "应用凭据未配置（App ID / App Secret），请先保存凭据"}
+    app_id = cfg["app_id"]
+    ver = str(version or "").strip()
+    try:
+        if not ver:
+            out = _rest("GET", _APP_VERSIONS_API % app_id, cfg=cfg)
+            items = ((out.get("data") or {}).get("items")) or []
+            ver = _next_version(items)
+        body = {"version": ver,
+                "remark": remark or "Touchstone 配置自动化",
+                "changelog": changelog or "自动配置：机器人能力 / 权限 / 长连接事件订阅 / 卡片回调",
+                "pc_default_ability": "bot", "mobile_default_ability": "bot"}
+        out = _rest("POST", _APP_PUBLISH_API % app_id, json_body=body, cfg=cfg)
+        data = out.get("data") or {}
+        return {"ok": True, "version": data.get("version") or ver,
+                "version_id": str(data.get("version_id") or ""),
+                "need_patch_scope": False, "error": ""}
+    except FeishuRestError as e:
+        return {"ok": False, "version": ver, "version_id": "",
+                "need_patch_scope": _need_scope(e), "error": _apply_error(e)}
+    except Exception as e:
+        return {"ok": False, "version": ver, "version_id": "",
+                "need_patch_scope": False, "error": f"发布失败: {e!r}"}
+
+
+# ---------- M5 配置自动化：保存配置（含凭据即时快检） ----------
+
+def save_user_config(user_id, body):
+    """保存用户飞书配置并即时反馈（服务端设置页唯一写口；语义与既有实现逐字一致）：
+    字段缺省=不改、显式空串=清除（前端对未编辑的 secret/webhook 不下发该键，防误清）。
+
+    新增：凭据齐全时立刻 `verify_credentials` 快检——今天保存凭据只写库不校验，
+    填错只能翻日志；`verify` 随响应回给页面做即时提示（凭据不全时为 None，零请求）。
+    返回 {"inbound_started": bool, "verify": {...}|None}。"""
+    cfg = user_config(user_id)
+    # 推送总控（2026-10-10）：与旧 `enabled` 是两个独立开关——旧键只管「无绑定行回落
+    # 默认 webhook」与入站，本键一票否决全部自动推送。缺省=不改（不在 body 里就不动）。
+    if "push_enabled" in body:
+        cfg["push_enabled"] = 1 if body["push_enabled"] else 0
+    if "enabled" in body:
+        cfg["enabled"] = 1 if body["enabled"] else 0
+    for key in ("default_webhook", "default_secret", "base_url",
+                "app_id", "app_secret"):
+        if key in body:
+            cfg[key] = str(body[key] or "").strip()
+    db.set_feishu_user_cfg(user_id, cfg)
+    started = start_inbound_for(user_id)
+    verify = verify_credentials(user_id) if app_config(user_id) else None
+    return {"inbound_started": bool(started), "verify": verify}
+
+
+def _cli_uid(val):
+    """CLI 的用户定位：显式 --user 优先；缺省时库中恰有一个用户即自动选中。
+    返回 (user_id, None)；定位失败返回 (None, 退出码)，原因已打印到 stderr。"""
+    if val:
+        return int(val), None
+    try:
+        users = db.list_users()
+    except Exception as e:
+        print(f"读取用户失败：{e}", file=sys.stderr)
+        return None, 1
+    if len(users) == 1:
+        return users[0]["id"], None
+    if not users:
+        print("库中还没有用户：先启动站点并创建账号", file=sys.stderr)
+        return None, 1
+    names = "、".join(f"{r['username']}(id={r['id']})" for r in users)
+    print(f"库中有多个用户，请用 --user 指定：{names}", file=sys.stderr)
+    return None, 1
+
+
 def _cli():
-    """python3 feishu.py selftest <pid> / send --url U --text T / outbox"""
-    ap = argparse.ArgumentParser(description="Touchstone 飞书出站推送（M1）")
+    """命令行入口（M1 出站 + M5 配置自动化）：
+
+      python3 feishu.py selftest <项目id> / send --url U --text T / outbox
+      python3 feishu.py doctor   [--user ID] [--send-probe]   # 配置自检（有 fail 退出码 1）
+      python3 feishu.py provision [--user ID] [--force] [--no-wait]  # 扫码建应用
+      python3 feishu.py apply    [--user ID]                  # 补齐应用配置
+      python3 feishu.py publish  [--user ID] [--version V]    # 提交发布
+    """
+    ap = argparse.ArgumentParser(description="Touchstone 飞书集成 CLI（出站推送 / 配置自动化）")
     sub = ap.add_subparsers(dest="cmd", required=True)
     p_st = sub.add_parser("selftest", help="向项目绑定 webhook 同步发一条测试消息")
     p_st.add_argument("project_id", type=int)
@@ -2131,6 +3211,18 @@ def _cli():
     p_send.add_argument("--secret", default="")
     p_send.add_argument("--text", required=True)
     sub.add_parser("outbox", help="查看最近投递记录")
+    p_doc = sub.add_parser("doctor", help="飞书配置自检（八项；有 fail 退出码 1）")
+    p_doc.add_argument("--user", type=int, default=None, help="用户 id（库中只有一个用户可省）")
+    p_doc.add_argument("--send-probe", action="store_true", help="额外发一条测试消息验证发消息权限")
+    p_prov = sub.add_parser("provision", help="扫码创建飞书应用（打印确认链接，手机飞书打开）")
+    p_prov.add_argument("--user", type=int, default=None)
+    p_prov.add_argument("--force", action="store_true", help="已配置应用时也重新创建")
+    p_prov.add_argument("--no-wait", action="store_true", help="发起后立即返回，不等扫码结果")
+    p_apply = sub.add_parser("apply", help="补齐应用配置（机器人能力/权限/事件/回调）")
+    p_apply.add_argument("--user", type=int, default=None)
+    p_pub = sub.add_parser("publish", help="提交发布（需管理员审批或已开免审）")
+    p_pub.add_argument("--user", type=int, default=None)
+    p_pub.add_argument("--version", default="", help="版本号（缺省自动递增）")
     a = ap.parse_args()
     db.init_db()
     if a.cmd == "selftest":
@@ -2150,6 +3242,77 @@ def _cli():
                              "payload": _payload(a.text), "id": 0, "retries": 0})
         print("OK" if ok else f"FAIL {err}")
         return 0 if ok else 1
+    if a.cmd == "doctor":
+        uid, rc = _cli_uid(a.user)
+        if uid is None:
+            return rc
+        out = doctor(uid, send_probe=a.send_probe)
+        marks = {"ok": "✅", "fail": "❌", "warn": "⚠️", "skip": "➖"}
+        for it in out["items"]:
+            print(f"{marks.get(it['state'], '?')} {it['label']}：{it['detail']}")
+            if it.get("hint"):
+                print(f"   提示：{it['hint']}")
+        s = out["summary"]
+        print(f"汇总：ok={s.get('ok', 0)} fail={s.get('fail', 0)} "
+              f"warn={s.get('warn', 0)} skip={s.get('skip', 0)}")
+        return 1 if s.get("fail") else 0
+    if a.cmd == "provision":
+        uid, rc = _cli_uid(a.user)
+        if uid is None:
+            return rc
+        out = provision_start(uid, force=a.force)
+        if not out.get("ok"):
+            print(f"发起失败：{out.get('error')}", file=sys.stderr)
+            return 1
+        if out.get("url"):
+            print(f"确认链接（手机飞书打开）：{out['url']}")
+        if a.no_wait:
+            print("已发起扫码流程（10 分钟内有效），稍后用 `doctor` 查看结果")
+            return 0
+        print("等待你在飞书里确认…（10 分钟有效）")
+        printed = out.get("url") or ""
+        st = provision_status(uid)
+        deadline = time.time() + PROVISION_TTL
+        while st.get("state") == "waiting" and time.time() < deadline:
+            time.sleep(2)
+            st = provision_status(uid)
+            if st.get("url") and st["url"] != printed:   # 链接可能稍后就绪/换域
+                printed = st["url"]
+                print(f"确认链接（手机飞书打开）：{printed}")
+        if st.get("state") != "success":
+            print(f"未完成（state={st.get('state')}）：{st.get('error') or '等待超时'}",
+                  file=sys.stderr)
+            return 1
+        print(f"✅ 应用已创建：{st.get('app_id')}")
+        for s in st.get("steps") or []:
+            print(f"  {'✅' if s.get('ok') else '❌'} {s.get('label')}：{s.get('detail')}")
+        if st.get("error"):
+            print(f"⚠️ {st['error']}")
+        return 0
+    if a.cmd == "apply":
+        uid, rc = _cli_uid(a.user)
+        if uid is None:
+            return rc
+        out = provision_apply(uid)
+        for s in out.get("steps") or []:
+            print(f"{'✅' if s.get('ok') else '❌'} {s.get('label')}：{s.get('detail')}")
+        if not out.get("ok"):
+            print(f"补齐失败：{out.get('error')}", file=sys.stderr)
+            return 1
+        print("✅ 应用配置已补齐（需创建版本发布后线上生效；可接着 `publish`）")
+        return 0
+    if a.cmd == "publish":
+        uid, rc = _cli_uid(a.user)
+        if uid is None:
+            return rc
+        out = provision_publish(uid, version=a.version or None)
+        if not out.get("ok"):
+            print(f"发布失败：{out.get('error')}", file=sys.stderr)
+            return 1
+        print(f"✅ 已提交发布：版本 {out.get('version')}"
+              f"（version_id={out.get('version_id') or '-'}）")
+        print("   发布需租户管理员审批（或管理员已开免审）后线上生效")
+        return 0
     for r in db.feishu_outbox_recent(30):
         print(r["id"], r["status"], r["retries"],
               (r["last_error"][:60] or "-"), r["created_at"])