feat(hub): 真实飞书读取 + 状态卡片 + 权限 gate + 部署脚本

FeishuRead(ADR-0003): feishuContextTool 从 stub 换成真实 lark
  im.v1.message.get(单条 trigger/reply/status_card)+ list(thread 回复);
  ADR-0003 chat 授权不变式不变(handler 已 gate)。
StatusCard: sendCard + buildRunStatusCard——完成/出错发 interactive card
  (status 文案 + model 选择器 + 取消按钮带 runId),替代纯文本。
Permission(ADR-0004, project-wise): triggerAgent 查 PermissionGrant 对
  project 的 edit+ 能力(manage⊇edit 单调);sender open_id 当 principal
  (子类型学 OPEN,务实选择,permission.ts 标注);per-artifact OPEN;
  settings 组合规则 OPEN。无权限回 '无权限触发'。
Deploy: cph-hub.service systemd unit(ExecStartPre 跑 prisma migrate)+
  install_service.sh(idempotent,seed env)+ deploy_platform.sh
  (rsync + npm ci + build + restart + healthz)。
client.ts 抽 createLarkClient/startFeishuListenerWithClient,tools 与
  ws 共用同一 client。
tsc rc=0;prisma validate 通过;deploy 脚本 bash -n 通过。

hub/src/feishu/client.ts

@@ -61,31 +61,96 @@ export async function sendText(rt: FeishuRuntime, chatId: string, text: string):
   });
 }
 
+/** Send an interactive card to a chat. `card` is the lark card schema object. */
+export async function sendCard(
+  rt: FeishuRuntime,
+  chatId: string,
+  card: unknown,
+): Promise<string | null> {
+  const client = rt.client as unknown as {
+    im: { v1: { message: { create: (p: unknown) => Promise<{ data?: { message_id?: string } }> } } };
+  };
+  const res = await client.im.v1.message.create({
+    params: { receive_id_type: "chat_id" },
+    data: {
+      receive_id: chatId,
+      msg_type: "interactive",
+      content: JSON.stringify(card),
+    },
+  });
+  return res.data?.message_id ?? null;
+}
+
+/** Build a run-status card: status text + model selector + cancel button. */
+export function buildRunStatusCard(opts: {
+  readonly status: string;
+  readonly model: string;
+  readonly models: readonly { readonly id: string; readonly label: string }[];
+  readonly runId: string;
+}): unknown {
+  return {
+    config: { wide_screen_mode: true },
+    header: {
+      title: { tag: "plain_text", content: `@Claude · ${opts.status}` },
+      template: opts.status === "处理完成" ? "green" : opts.status === "处理出错" ? "red" : "blue",
+    },
+    elements: [
+      { tag: "div", text: { tag: "lark_md", content: `**model:** ${opts.model}` } },
+      {
+        tag: "action",
+        actions: [
+          {
+            tag: "select",
+            placeholder: { tag: "plain_text", content: "切换 model" },
+            options: opts.models.map((m) => ({ text: { tag: "plain_text", content: m.label }, value: m.id })),
+            value: opts.model,
+          },
+          {
+            tag: "button",
+            text: { tag: "plain_text", content: "取消" },
+            type: "danger",
+            value: JSON.stringify({ action: "cancel", runId: opts.runId }),
+          },
+        ],
+      },
+    ],
+  };
+}
+
 /**
  * Start the lark WebSocket client and route `im.message.receive_v1` events to
  * `onMessage`. The ws connection lives in the background; this resolves the
  * runtime handle.
  */
-export function startFeishuListener(
-  config: FeishuConfig,
-  logger: FastifyBaseLogger,
-  onMessage: (event: MessageReceiveEvent, rt: FeishuRuntime) => Promise<void>,
-): FeishuRuntime {
-  const client = new lark.Client({
+/** Build a lark Client (HTTP API surface). Used before the ws starts, so tools
+ * that need to call Feishu APIs can hold it from server boot. */
+export function createLarkClient(config: FeishuConfig): lark.Client {
+  return new lark.Client({
     appId: config.appId,
     appSecret: config.appSecret,
     appType: lark.AppType.SelfBuild,
   });
+}
 
+export interface FeishuListener {
+  readonly runtime: FeishuRuntime;
+  readonly stop: () => Promise<void>;
+}
+
+/** Start the ws listener using an already-built client. Returns the runtime. */
+export function startFeishuListenerWithClient(
+  config: FeishuConfig,
+  client: lark.Client,
+  logger: FastifyBaseLogger,
+  onMessage: (event: MessageReceiveEvent, rt: FeishuRuntime) => Promise<void>,
+): FeishuRuntime {
   const wsClient = new lark.WSClient({
     appId: config.appId,
     appSecret: config.appSecret,
     domain: lark.Domain.Feishu,
     loggerLevel: lark.LoggerLevel.info,
   });
-
   const rt: FeishuRuntime = { client, logger };
-
   void wsClient.start({
     eventDispatcher: new lark.EventDispatcher({}).register({
       "im.message.receive_v1": async (data) => {
@@ -97,6 +162,12 @@ export function startFeishuListener(
       },
     }),
   });
-
   return rt;
 }
+export function startFeishuListener(
+  config: FeishuConfig,
+  logger: FastifyBaseLogger,
+  onMessage: (event: MessageReceiveEvent, rt: FeishuRuntime) => Promise<void>,
+): FeishuRuntime {
+  return startFeishuListenerWithClient(config, createLarkClient(config), logger, onMessage);
+}

hub/src/feishu/read.ts

@@ -0,0 +1,97 @@
+/**
+ * Feishu context reader — the real implementation behind `feishuContextTool`.
+ *
+ * ADR-0003: Hub stores only anchors, reads Feishu context on demand. The tool
+ * (`feishu_read_context`) is already chat-authorized by `tools.ts` (chat must
+ * match the project binding). Here we actually call lark's `im.v1.message`:
+ *
+ *  - `trigger_message` / `reply`: `message.get` by message_id.
+ *  - `status_card`: the run's status card message — same `message.get` by id.
+ *  - `thread`: lark's thread replies. The SDK exposes `message.list` with a
+ *    `parent_message_id` filter; we map "thread" to that.
+ *
+ * The lark SDK's `im.v1.message` methods are dynamic at runtime (weak types);
+ * we cast through a known request/response shape and return a compact JSON for
+ * the model. All calls use the chat-authorized `client` from the runtime — no
+ * separate credential path, so the ADR-0003 invariant holds end-to-end.
+ */
+import type { FeishuRuntime } from "./client.js";
+import type { FeishuContextArgs } from "../agent/tools.js";
+import type { ToolContext } from "../agent/tools.js";
+
+/** Pragmatic shape of the lark message object we consume. */
+interface LarkMessage {
+  message_id?: string;
+  msg_type?: string;
+  content?: string;
+  create_time?: string;
+  sender?: { id?: string; sender_type?: string };
+  chat_id?: string;
+  parent_message_id?: string;
+  root_id?: string;
+}
+
+interface ImV1Message {
+  get: (p: { path: { message_id: string } }) => Promise<{ data?: { items?: LarkMessage[]; message?: LarkMessage } }>;
+  list: (p: {
+    params: { container_id_type: string; container_id: string; page_size?: number };
+  }) => Promise<{ data?: { items?: LarkMessage[] } }>;
+}
+
+function im(rt: FeishuRuntime): ImV1Message {
+  return (rt.client as unknown as { im: { v1: { message: ImV1Message } } }).im.v1.message;
+}
+
+/** Read on-demand Feishu context for the current run. Entry point for the tool. */
+export async function readFeishuContext(
+  args: FeishuContextArgs,
+  _ctx: ToolContext,
+  rt: unknown,
+): Promise<string> {
+  const runtime = rt as FeishuRuntime;
+  const api = im(runtime);
+  try {
+    switch (args.anchor) {
+      case "trigger_message":
+      case "status_card":
+      case "reply": {
+        // All three are single-message reads by id.
+        const res = await api.get({ path: { message_id: args.id } });
+        const msg = res.data?.message ?? res.data?.items?.[0];
+        if (msg === undefined) return JSON.stringify({ error: "message not found", id: args.id });
+        return JSON.stringify(compact(msg));
+      }
+      case "thread": {
+        // Thread = replies to a parent message. `container_id` is the parent's
+        // message_id; container_id_type=message_id scopes the list to that thread.
+        const res = await api.list({
+          params: {
+            container_id_type: "message_id",
+            container_id: args.id,
+            page_size: 50,
+          },
+        });
+        const items = res.data?.items ?? [];
+        return JSON.stringify(items.map(compact));
+      }
+      default:
+        return JSON.stringify({ error: `unknown anchor type: ${args.anchor as string}` });
+    }
+  } catch (e) {
+    return JSON.stringify({ error: e instanceof Error ? e.message : String(e) });
+  }
+}
+
+/** Project a lark message down to the fields the model actually needs. */
+function compact(m: LarkMessage): Record<string, unknown> {
+  return {
+    message_id: m.message_id,
+    msg_type: m.msg_type,
+    content: m.content,
+    create_time: m.create_time,
+    sender_id: m.sender?.id,
+    parent_message_id: m.parent_message_id,
+    root_id: m.root_id,
+  };
+}
+

hub/src/feishu/trigger.ts

@@ -15,12 +15,13 @@
  */
 import type { PrismaClient } from "@prisma/client";
 import type { FastifyBaseLogger } from "fastify";
-import { sendText, type FeishuRuntime, type MessageReceiveEvent } from "./client.js";
+import { sendText, sendCard, buildRunStatusCard, type FeishuRuntime, type MessageReceiveEvent } from "./client.js";
 import type { AgentProvider } from "../agent/provider.js";
 import type { ToolRegistry } from "../agent/tools.js";
 import type { ModelRegistry } from "../agent/models.js";
 import { runAgent, type ProjectContext } from "../agent/runner.js";
 import { acquireLock, currentLockRunId, releaseLock } from "../lock.js";
+import { canTriggerAgent } from "../permission.js";
 
 interface TriggerDeps {
   readonly prisma: PrismaClient;
@@ -56,6 +57,17 @@ export function makeTriggerHandler(deps: TriggerDeps) {
       return;
     }
     const projectId = binding.projectId;
+    // ADR-0004: triggerAgent requires edit on the project. principal=sender
+ // open_id (sub-typology OPEN — pragmatic choice, see permission.ts).
+    const senderOpenId = event.sender.sender_id.open_id ?? "";
+    if (senderOpenId !== "") {
+      const perm = await canTriggerAgent(deps.prisma, projectId, senderOpenId);
+      if (!perm.allowed) {
+        deps.logger.info({ projectId, senderOpenId, reason: perm.reason }, "feishu trigger: permission denied");
+        await sendText(rt, chatId, "无权限触发。");
+        return;
+      }
+    }
 
     // ADR-0002: if locked by another run, reply busy.
     const existing = await currentLockRunId(deps.prisma, projectId);
@@ -160,14 +172,24 @@ export function makeTriggerHandler(deps: TriggerDeps) {
             finishedAt: new Date(),
           },
         });
-        await sendText(rt, chatId, statusReply(result.status));
+        await sendCard(rt, chatId, buildRunStatusCard({
+          status: statusReply(result.status),
+          model,
+          models: deps.models.listModels(),
+          runId: run.id,
+        }));
       })
       .catch(async (e) => {
         await deps.prisma.agentRun.update({
           where: { id: run.id },
           data: { status: "FAILED", error: String(e), finishedAt: new Date() },
         });
-        await sendText(rt, chatId, "处理出错,已释放项目锁。");
+        await sendCard(rt, chatId, buildRunStatusCard({
+          status: "处理出错",
+          model,
+          models: deps.models.listModels(),
+          runId: run.id,
+        }));
       })
       .finally(async () => {
         await releaseLock(deps.prisma, run.id);