@cpm-lhj/dsh-feishu 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# @cpm-lhj/dsh-feishu
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+飞书长连接插件。白名单里的人发消息后，常驻的 dsh 在固定目录里执行；进度和批准显示在触发消息下的卡片上，最终回答回复在那条消息下面。
+
+适配 `@larksuiteoapi/node-sdk` 1.76。对照当前安装包，`im.message.receive_v1`、`card.action.trigger`、`client.im.message.reply`（含 `reply_in_thread`）、`client.im.message.patch` 和 `GET /open-apis/bot/v3/info` 的字段一致。话题 id 没有用一条真实群消息核对。键规则按设计实现：私聊是 `p2p:<chat_id>`；群里有 `thread_id` 时是 `group:<chat_id>:thread:<thread_id>`；否则是 `group:<chat_id>:root:<root_id 或 message_id>`。线上字段若不同，只改 `src/transport.ts` 和 `src/keys.ts`。
+
+## 安装
+
+运行中的 dsh 需要满足 `engines.dsh`：`>=0.2.2-rc.1 <0.3.0`。Node.js 需要 `>=24.9.0`。
+
+```sh
+dsh plugin --profile <name> add <本包>
+```
+
+`<本包>` 可以是本地目录、`github:` 地址、npm 包或 `pnpm pack` 打出的 tarball。profile 以 `@deepseek-ai/dsh-base` 为第一层，再追加本包。内置组合包从那台 dsh 的安装目录解析，不从本仓库解析。
+
+本包的 `cordis.patch.yml` 只插入自己：
+
+```yaml
+- insert:
+    - id: feishu
+      name: '@cpm-lhj/dsh-feishu'
+```
+
+装好之后，用带 Web 界面的同一个 profile 打开**插件**，进入 `@cpm-lhj/dsh-feishu`，点 `feishu` 这一行的**配置**。页面上填写工作目录、每行一个 open_id、App ID 和 App Secret，然后保存。App ID 和 App Secret 写入凭证库，配置里只留下 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 这两个名字。留空的凭证不会覆盖已经保存的值。目录必须是已存在的绝对路径；open_id 留空时没有人可以触发。保存后插件按新配置重新连接。
+
+这个配置页只出现在加载了 Web 客户端的 profile 里。没打开 Web 的常驻进程上看不到它。
+
+关掉 `tool-working-directory` 仍写在该 profile 自己的 `cordis.patch.yml`。后一层按整行替换，不是深合并：
+
+```yaml
+- id: tool-working-directory
+  disabled: true
+```
+
+不改 `sandbox-policy` 的 `workspaceRoot`。
+
+常驻 profile 只叠 base 和本插件。不要用 headless 当常驻进程，也不要在同一个 profile 上挂 Web 批准界面。同一套飞书应用和 domain 只跑一个进程；两个进程会各自处理消息。
+
+`@deepseek-ai/cordis`、`@deepseek-ai/schemastery` 和 `@deepseek-ai/dsh-llm` 是 peer，由正在运行的 dsh 提供。不要再装一份。本包直接依赖 `@larksuiteoapi/node-sdk` 和 `zod`。
+
+## 构建脚本
+
+优先发布 npm 包或 tarball。包内已经带有 `lib/`，安装时不必跑 `prepare`。
+
+从 git 安装时，`prepare` 用 Node 自带的类型剥离把 `src/` 转成 `lib/`，不需要旁边有一份 harness checkout。pnpm 会拦住依赖的构建脚本：
+
+| pnpm | 授权方式 |
+| --- | --- |
+| 10 | `pnpm approve-builds`，或在 profile 的 `pnpm-workspace.yaml` 里写 `onlyBuiltDependencies`。`allowBuilds` 在 pnpm 10 不生效 |
+| 11 | 安装失败时提示的 `allowBuilds`。Web 插件页可以用 “Allow these scripts and retry” |
+
+授权后重新执行一次 `dsh plugin add`。`prepare` 没跑时没有 `lib/index.js`，插件起不来。
+
+## 升级 dsh
+
+本包声明 `engines.dsh` 上限 `<0.3.0`。把 dsh 升到 0.3.x 之后，已安装的 profile 在启动时会静默跳过这个 bundle：结果记在 `skippedBundles`，终端不打印。机器人不再响应，仍处于执行中的卡片也不会被恢复。升级前先确认本包的兼容范围。安装和更新路径会直接拒绝范围外的 dsh；已经装好的机器才是静默跳过。
+
+## 固定文案
+
+这些句子不做成配置：
+
+| 场景 | 文字 |
+| --- | --- |
+| 不在名单 | 你不在可触发名单里，这条消息不会执行。 |
+| 这条线还在执行 | 这条会话还在执行，新消息不会执行。 |
+| 没有正文 | 请写下要处理的问题。 |
+| 卡片 | 执行中、已停止、同意、拒绝、停止、成功、失败 |
+
+## 开发
+
+```sh
+npm install
+npm test
+npm run typecheck
+npm run prepare
+```
+
+`npm test` 用 `node --experimental-strip-types` 跑 `tests/`。这些测试不启动父仓库的 agent loop，也不代替飞书客户端上的 AC-01 到 AC-16。`lib/` 和 `node_modules/` 不入库。
+
+`@deepseek-ai/dsh-llm` 只列为 peer。npm 上的该包版本不是 harness 的 `0.2.2-rc.1`，所以这里不把它装进 `devDependencies`。类型检查用 `types/dsh-llm.d.ts`。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: feishu
+      name: '@cpm-lhj/dsh-feishu'

package/lib/approval.js

@@ -0,0 +1,165 @@
+                                                         
+
+                  
+               
+                
+                                                                               
+                                  
+                     
+              
+                                                                          
+                                             
+                   
+ 
+
+/** One open card approval: the visible reason and the click that settles it. */
+export class ApprovalBook {
+                   waiters = new Map                             ()
+                   views = new Map                                            ()
+
+  /**
+   * Approval currently drawn on this session's card.
+   * @param sessionId - dsh session id.
+   * @returns The open approval, or `undefined` when the card should not show buttons.
+   */
+  view(sessionId        )                                                 {
+    return this.views.get(sessionId)
+  }
+
+  /**
+   * Remember the approval to draw. Arm the waiter before the card is shown.
+   * @param sessionId - dsh session id.
+   * @param callId - Tool call this click is allowed to settle.
+   * @param reason - Explanation shown on the card. Not copied onto the button.
+   */
+  setView(sessionId        , callId        , reason        )       {
+    this.views.set(sessionId, { callId, reason })
+  }
+
+  /**
+   * Drop the visible approval without settling a waiter.
+   * @param sessionId - dsh session id.
+   */
+  clear(sessionId        )       {
+    this.views.delete(sessionId)
+  }
+
+  /**
+   * Wait for the click that matches this session and call. Abort settles `cancelled`.
+   * The waiter accepts clicks only after {@link open}; an earlier click is kept and
+   * applied then. A second arm for the same pair cancels the previous promise.
+   * A failed show must call {@link unavailable} so a buffered click is not granted.
+   * @param sessionId - dsh session id whose view is cleared when this settles.
+   * @param callId - Button id. Unique only together with `sessionId`.
+   * @param signal - Tool signal. Aborting withdraws the question.
+   * @returns The single outcome for this request.
+   */
+  arm(sessionId        , callId        , signal                         )                           {
+    this.waiters.get(sessionId)?.get(callId)?.cancel(true)
+    const byCall = this.bucket(sessionId)
+    return new Promise((resolve) => {
+      let settled = false
+      let opened = false
+      let buffered                                  
+      const settle = (outcome                 , keepView = false) => {
+        if (settled) return
+        settled = true
+        const current = this.waiters.get(sessionId)?.get(callId)
+        if (current === waiter) {
+          byCall.delete(callId)
+          if (byCall.size === 0) this.waiters.delete(sessionId)
+        }
+        if (!keepView && this.views.get(sessionId)?.callId === callId) this.views.delete(sessionId)
+        signal?.removeEventListener('abort', onAbort)
+        resolve(outcome)
+      }
+      const onAbort = () => settle('cancelled')
+      const waiter         = {
+        allow: () => settle('allowed-once'),
+        reject: () => settle('rejected'),
+        cancel: (keepView) => settle('cancelled', keepView === true),
+        unavailable: () => settle('unavailable'),
+        open: () => {
+          if (settled || opened) return
+          opened = true
+          if (buffered === 'approve') settle('allowed-once')
+          else if (buffered === 'reject') settle('rejected')
+        },
+        buffer: (kind) => {
+          if (settled || opened || buffered !== undefined) return false
+          buffered = kind
+          return true
+        },
+        isOpen: () => opened,
+      }
+      byCall.set(callId, waiter)
+      if (signal?.aborted) {
+        settle('cancelled')
+        return
+      }
+      signal?.addEventListener('abort', onAbort, { once: true })
+    })
+  }
+
+  /**
+   * Apply a click that was buffered while the card patch was in flight.
+   * Does nothing when the waiter is missing or already settled.
+   * @param sessionId - dsh session id.
+   * @param callId - Button id.
+   */
+  open(sessionId        , callId        )       {
+    this.waiters.get(sessionId)?.get(callId)?.open()
+  }
+
+  /**
+   * Settle this show as `unavailable` and drop a click buffered during the failed patch.
+   * A waiter already settled by abort stays as it is.
+   * @param sessionId - dsh session id.
+   * @param callId - Button id.
+   */
+  unavailable(sessionId        , callId        )       {
+    this.waiters.get(sessionId)?.get(callId)?.unavailable()
+  }
+
+  /**
+   * Settle the waiter for this session and call. A missing or already settled waiter is a late click.
+   * A click that arrives before {@link open} is kept for that open.
+   * @param sessionId - Session that owns the card.
+   * @param callId - Id from the button.
+   * @param kind - Approve or reject. Stop is not an approval outcome.
+   * @returns Whether a waiter accepted the click.
+   */
+  click(sessionId        , callId        , kind                      )          {
+    const waiter = this.waiters.get(sessionId)?.get(callId)
+    if (waiter === undefined) return false
+    if (!waiter.isOpen()) return waiter.buffer(kind)
+    if (kind === 'approve') waiter.allow()
+    else waiter.reject()
+    return true
+  }
+
+  /**
+   * Cancel every waiter on this session and drop its view.
+   * @param sessionId - dsh session id.
+   */
+  cancelSession(sessionId        )       {
+    this.views.delete(sessionId)
+    const byCall = this.waiters.get(sessionId)
+    if (byCall === undefined) return
+    for (const waiter of [...byCall.values()]) waiter.cancel()
+  }
+
+  /** Settle every open approval as cancelled. Used when the plugin unloads. */
+  cancelAll()       {
+    this.views.clear()
+    for (const sessionId of [...this.waiters.keys()]) this.cancelSession(sessionId)
+  }
+
+          bucket(sessionId        )                      {
+    const existing = this.waiters.get(sessionId)
+    if (existing !== undefined) return existing
+    const created = new Map                ()
+    this.waiters.set(sessionId, created)
+    return created
+  }
+}

package/lib/card.js

@@ -0,0 +1,57 @@
+import { COPY } from './copy.js'
+                                                                 
+
+/**
+ * Render one progress card. Button values carry the action and id only.
+ * Settled cards keep the rows and omit the running and stopped status.
+ * @param doc - Card content derived from the line and the open approval, if any.
+ * @returns Feishu interactive card JSON.
+ */
+export function renderCard(doc              )           {
+  const elements                            = []
+  for (const row of doc.rows) elements.push(textElement(rowText(row)))
+  if (doc.approval !== undefined) {
+    if (doc.approval.reason !== '') elements.push(textElement(doc.approval.reason))
+    elements.push(actions([
+      button(COPY.approve, 'primary', { action: 'approve', callId: doc.approval.callId }),
+      button(COPY.reject, 'danger', { action: 'reject', callId: doc.approval.callId }),
+    ]))
+  }
+  if (doc.showStop) elements.push(actions([button(COPY.stop, 'default', { action: 'stop' })]))
+  const card           = {
+    config: { wide_screen_mode: true, update_multi: true },
+    elements,
+  }
+  if (doc.status === 'running' || doc.status === 'stopped') {
+    card.header = {
+      title: {
+        tag: 'plain_text',
+        content: doc.status === 'running' ? COPY.running : COPY.stopped,
+      },
+    }
+  }
+  return card
+}
+
+function rowText(row         )         {
+  if (row.result === 'pending') return `${row.toolName}  ${row.objectLabel}`
+  const result = row.result === 'success' ? COPY.success : COPY.failure
+  return `${row.toolName}  ${row.objectLabel}  ${result}`
+}
+
+function textElement(content        )                          {
+  return { tag: 'div', text: { tag: 'plain_text', content } }
+}
+
+function actions(items                           )                          {
+  return { tag: 'action', actions: items }
+}
+
+function button(label        , type        , value                        )                          {
+  return {
+    tag: 'button',
+    text: { tag: 'plain_text', content: label },
+    type,
+    value,
+  }
+}

package/lib/client/index.js

@@ -0,0 +1,213 @@
+/**
+ * Browser half. The Web page loads this file, and it registers the Feishu
+ * row's configuration form on the Plugins page.
+ */
+
+import { draftFromValue, planSave, ROW_CONFIG_KEY,                  } from './save.js'
+
+const NS = 'feishu'
+
+const en = {
+  summary: 'Set the working directory, who can start a session, and the Feishu app credentials.',
+  unavailable: 'This plugin is not running, so this page cannot save yet.',
+  directory: 'Working directory',
+  directoryHint: 'An existing absolute path. Every session runs in this directory.',
+  allow: 'People who can start a session',
+  allowHint: 'One Feishu open_id per line. An empty list means nobody can start one.',
+  appId: 'App ID',
+  appSecret: 'App Secret',
+  secretHint: 'Leave a credential blank to keep the saved value.',
+  save: 'Save',
+  saving: 'Saving…',
+  saved: 'Saved. The plugin reconnects with these settings.',
+  saveFailed: 'The settings were not saved.',
+  readOnly: 'This profile cannot change settings.',
+}
+
+const zh = {
+  summary: '填写工作目录、可以发起会话的人，以及飞书应用凭证。',
+  unavailable: '插件还没在运行，这个页面暂时不能保存。',
+  directory: '工作目录',
+  directoryHint: '一个已经存在的绝对路径。所有会话都在这个目录里执行。',
+  allow: '可以发起会话的人',
+  allowHint: '每行一个飞书 open_id。留空则没有人可以发起。',
+  appId: 'App ID',
+  appSecret: 'App Secret',
+  secretHint: '凭证留空表示保留已经保存的值。',
+  save: '保存',
+  saving: '正在保存…',
+  saved: '已保存。插件会用这些设置重新连接。',
+  saveFailed: '没有保存成功。',
+  readOnly: '这个 profile 不能修改设置。',
+}
+
+                    
+                                                                                     
+                                                                                 
+ 
+
+                     
+                                             
+                
+                              
+                   
+ 
+
+                     
+                          
+          
+                    
+                                                                                                               
+   
+                                 
+ 
+
+                         
+                                                
+                                                                                             
+          
+                                                                
+                                                                                                                       
+   
+           
+                  
+                                                                                            
+     
+   
+ 
+
+/** Services this page waits for. */
+export const inject = ['slots', 'locale', 'remote', 'remote.credentials']         
+
+/**
+ * Register the configuration page while the Plugins page is on screen.
+ * @param ctx - Browser plugin context.
+ */
+export function apply(ctx               )       {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }))
+  ctx.effect(() => ctx.slots.inject('plugins.row.config', () => ctx.slots.register({
+    name: 'plugins.row.config',
+    key: ROW_CONFIG_KEY,
+    locale: NS,
+  }, props => {
+    const React = require('react')            
+    return React.createElement(FeishuPage, { ...props, credentials: ctx.remote.credentials })
+  })))
+}
+
+                                       
+                                                     
+ 
+
+/** The row's summary line, or the form. */
+function FeishuPage(props           )          {
+  const { t } = props
+  if (props.view === 'summary') return t('summary')
+  const form = props.form
+  if (form === undefined || form.state.status !== 'ready') return t('unavailable')
+  const React = require('react')            
+  return React.createElement(FeishuForm, { ...props, form })
+}
+
+/** Directory, allow list, and the two credential fields. */
+function FeishuForm(props                                                      )          {
+  const React = require('react')            
+  const initial = draftFromValue(props.form.state.value)
+  const [directory, setDirectory] = React.useState(initial.directory)
+  const [allowText, setAllowText] = React.useState(initial.allowText)
+  const [appId, setAppId] = React.useState('')
+  const [appSecret, setAppSecret] = React.useState('')
+  const [status, setStatus] = React.useState                                        ('idle')
+  const [detail, setDetail] = React.useState('')
+  const disabled = !props.form.state.writable || status === 'saving'
+
+  const onSave = () => {
+    const draft              = { directory, allowText, appId, appSecret }
+    setStatus('saving')
+    setDetail('')
+    void save(props, draft).then(() => {
+      setAppId('')
+      setAppSecret('')
+      setStatus('saved')
+    }, (error         ) => {
+      setStatus('failed')
+      setDetail(error instanceof Error && error.message.length > 0 ? error.message : props.t('saveFailed'))
+    })
+  }
+
+  return React.createElement('form', {
+    onSubmit: (event                            ) => {
+      event.preventDefault()
+      onSave()
+    },
+    style: { display: 'grid', gap: '16px', maxWidth: '36rem' },
+  },
+    textField(props, 'feishu-directory', 'directory', 'directoryHint', directory, setDirectory, disabled),
+    textField(props, 'feishu-allow', 'allow', 'allowHint', allowText, setAllowText, disabled, 4),
+    secretField(props, 'feishu-app-id', 'appId', appId, setAppId, disabled),
+    secretField(props, 'feishu-app-secret', 'appSecret', appSecret, setAppSecret, disabled),
+    React.createElement('p', null, props.t('secretHint')),
+    props.form.state.writable ? null : React.createElement('p', { role: 'status' }, props.t('readOnly')),
+    React.createElement('button', { type: 'submit', disabled }, props.t(status === 'saving' ? 'saving' : 'save')),
+    status === 'saved' ? React.createElement('p', { role: 'status' }, props.t('saved')) : null,
+    status === 'failed' ? React.createElement('p', { role: 'status' }, detail || props.t('saveFailed')) : null,
+  )
+}
+
+function textField(
+  props           ,
+  id        ,
+  label                 ,
+  hint                 ,
+  value        ,
+  onChange                         ,
+  disabled         ,
+  rows = 1,
+)          {
+  const React = require('react')            
+  return React.createElement('label', { htmlFor: id, style: { display: 'grid', gap: '4px' } },
+    props.t(label),
+    React.createElement('textarea', {
+      id,
+      value,
+      rows,
+      disabled,
+      spellCheck: false,
+      onChange: (event                               ) => { onChange(event.target.value) },
+    }),
+    React.createElement('span', null, props.t(hint)),
+  )
+}
+
+function secretField(
+  props           ,
+  id        ,
+  label                 ,
+  value        ,
+  onChange                         ,
+  disabled         ,
+)          {
+  const React = require('react')            
+  return React.createElement('label', { htmlFor: id, style: { display: 'grid', gap: '4px' } },
+    props.t(label),
+    React.createElement('input', {
+      id,
+      type: 'password',
+      autoComplete: 'new-password',
+      value,
+      disabled,
+      spellCheck: false,
+      onChange: (event                               ) => { onChange(event.target.value) },
+    }),
+  )
+}
+
+async function save(props                                                      , draft             )                {
+  const plan = planSave(draft)
+  for (const secret of plan.secrets) {
+    const response = await props.credentials.set(secret.ref, secret.value)
+    if (!response.ok) throw new Error(response.error?.message ?? props.t('saveFailed'))
+  }
+  const accepted = await props.form.mutate(plan.ops, props.form.state.revision)
+  if (!accepted) throw new Error(props.t('saveFailed'))
+}

package/lib/client/save.js

@@ -0,0 +1,76 @@
+/** Credential ref the Plugins page writes the Feishu App ID under. */
+export const APP_ID_REF = 'FEISHU_APP_ID'
+
+/** Credential ref the Plugins page writes the Feishu App Secret under. */
+export const APP_SECRET_REF = 'FEISHU_APP_SECRET'
+
+/** `plugins.row.config` key: package name, then the row id from cordis.patch.yml. */
+export const ROW_CONFIG_KEY = '@cpm-lhj/dsh-feishu#feishu'
+
+/** One settings-form edit. */
+                           
+           
+                
+                          
+ 
+
+/** Values the page is about to save. Secret fields are empty when the user left them unchanged. */
+                              
+                   
+                   
+               
+                   
+ 
+
+/** Credential writes plus the volatile config fields the page owns. */
+                           
+                                           
+                 
+ 
+
+/**
+ * Read the directory and allow list out of a settings snapshot.
+ * App ID and App Secret are not in that snapshot.
+ * @param value - Host config section, when one has been accepted.
+ * @returns Directory text and one open_id per line.
+ */
+export function draftFromValue(value         )                                               {
+  const record = value !== null && typeof value === 'object' ? value                            : {}
+  const directory = typeof record.directory === 'string' ? record.directory : ''
+  const allow = Array.isArray(record.allowOpenIds)
+    ? record.allowOpenIds.filter((item)                 => typeof item === 'string')
+    : []
+  return { directory, allowText: allow.join('\n') }
+}
+
+/**
+ * Split the allow-list textarea into open_ids.
+ * @param text - One open_id per line.
+ * @returns Trimmed, non-empty ids.
+ */
+export function allowList(text        )           {
+  return text.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0)
+}
+
+/**
+ * Plan a save. Blank secret fields are left untouched. The config always
+ * stores the fixed credential ref names, never the secret values.
+ * @param draft - Current form fields.
+ * @returns Credential writes and config operations.
+ */
+export function planSave(draft             )           {
+  const secrets                                   = []
+  const appId = draft.appId.trim()
+  const appSecret = draft.appSecret.trim()
+  if (appId.length > 0) secrets.push({ ref: APP_ID_REF, value: appId })
+  if (appSecret.length > 0) secrets.push({ ref: APP_SECRET_REF, value: appSecret })
+  return {
+    secrets,
+    ops: [
+      { op: 'set', path: ['directory'], value: draft.directory.trim() },
+      { op: 'set', path: ['allowOpenIds'], value: allowList(draft.allowText) },
+      { op: 'set', path: ['appIdRef'], value: APP_ID_REF },
+      { op: 'set', path: ['appSecretRef'], value: APP_SECRET_REF },
+    ],
+  }
+}