前言¶
在 DeepSeek Harness（DSH）裏讓 Agent 讀寫飛書消息、日曆、雲文檔或多維表格，常見做法是自行拼裝 OpenAPI 調用、維護 token 與 scope。飛書官方提供了 lark-cli，命令行覆蓋多個業務域，但要在 DSH 側邊欄裏完成掃碼登錄、查看身份狀態，並在對話裏穩定執行 CLI，仍需要一層與 Host 的集成。
下面介紹社區插件 dsh-feishu-cli（維護者 hoyin-law）：把官方 CLI 接入 DSH Desktop / Web，增加「飛書」側邊欄面板，並向 Agent 註冊 feishu_cli、feishu_auth 兩個工具。插件本身不替代飛書 API，能力邊界與 lark-cli 一致。
這是什麼¶
dsh-feishu-cli 是 DSH 的客戶端類插件：在 Web UI 掛載飛書面板，負責定位或下載 lark-cli、展示登錄二維碼與命令輸出；Host 側封裝 CLI 的執行與登錄會話。真正訪問飛書的是官方 larksuite/cli，登錄與授權以你本機飛書賬號及所授 scope 爲準。README 明確說明這是社區插件，不是飛書或 DeepSeek 官方產品。
核心功能¶
面板與登錄¶
- 應用初始化：首次可在面板走官方 CLI 的一鍵建應用流程（掃碼或打開鏈接），應用信息寫入本機
lark-cli配置。 - 賬號登錄：面板展示二維碼與授權鏈接，完成後顯示已登錄狀態；可按業務域選擇權限範圍（消息、日曆、雲文檔、多維表格、郵箱、任務、會議、通訊錄等），或申請常用權限全集。
- 身份狀態：展示 App ID、登錄用戶、Open ID、已授權 scope 數量與過期時間，支持退出與取消進行中的登錄。
- 命令控制台：在面板輸入
lark-cli之後的命令，輸出以等寬文本展示，並提供常用命令快捷入口。 - CLI 安裝引導：本機無
lark-cli時，面板可觸發下載安裝（約 50MB，有進度與階段提示）。
Agent 工具¶
feishu_cli：執行任意lark-cli命令（不經過 shell，不支持管道與重定向）。feishu_auth：查看狀態、發起應用初始化或賬號登錄、等待授權、退出、列出用戶、取消登錄。
README 歸納的覆蓋面：18 個業務域、200+ 高層命令（+shortcut），以及通過 lark-cli api 調用的全量 OpenAPI（如 im、docs、base、sheets、calendar、mail、task、vc、審批、通訊錄、雲空間、知識庫等）。Meegle（飛書項目）需單獨 meegle-cli，不在本插件範圍內。
環境與依賴¶
- DSH Desktop 或
dsh web，且能安裝 profile bundle；package.json中engines.dsh爲>=0.2.1-rc.2 <0.3.0-0。 - Windows（x64 / ARM64）、macOS（Intel / Apple 芯片）、Linux（x64 / ARM64 / RISC-V）。
- 首次使用需聯網下載對應平臺的官方
lark-cli（README 寫明推薦版本 1.0.98，解壓至$DSH_HOME/feishu-cli/bin，並按 SHA-256 校驗）；企業或離線環境可通過LARK_CLI_BIN、FEISHU_CLI_HOME、FEISHU_CLI_DOWNLOAD_BASE等環境變量控制二進制位置與下載源。
界面語言跟隨 DSH 設置，支持中文與英文。
安裝與啓用¶
推薦從 GitHub 安裝 main 分支源碼包。Desktop 用戶將命令中的 web 換成 desktop：
dsh plugin --profile web add github:hoyin-law/dsh-feishu-cli
dsh plugin --profile desktop add github:hoyin-law/dsh-feishu-cli
若已發佈到 npm，也可按包名安裝：
dsh plugin --profile web add dsh-feishu-cli
也可下載 v1.0.0 Release 中的 dsh-feishu-cli.tgz 後本地安裝：
dsh plugin --profile web add ./dsh-feishu-cli.tgz
安裝完成後重啓 DSH，側邊欄會出現「飛書」入口。卸載示例：
dsh plugin --profile web remove dsh-feishu-cli
典型用法¶
首次使用：兩步掃碼¶
- 初始化應用（僅第一次）：側邊欄打開「飛書」→「第 1 步 · 初始化飛書應用」→ 按提示在瀏覽器或飛書 App 中創建應用並授權。
- 登錄賬號：在「登錄飛書賬號」卡片掃碼或打開鏈接確認授權；面板顯示「已登錄 · 你的名字」即完成。之後通常只需第 2 步；過期時面板會提示重新登錄。
面板命令控制台¶
輸入內容爲 lark-cli 之後的 argv，例如：
calendar +agenda— 今日議程task +list— 我的任務im +chats-list— 羣列表docs +search --query 週報— 搜索雲文檔base +records-list --app-token xxx --table-id xxx— 讀取多維表格記錄api GET /open-apis/calendar/v4/calendars— 直接調用 OpenAPI
Agent 調用示例¶
執行 CLI：
feishu_cli command="calendar +agenda"
feishu_cli command="im +messages-send --chat-id oc_xxx --text 你好"
feishu_cli command="docs +search --query 週報"
feishu_cli command="api GET /open-apis/calendar/v4/calendars"
可選參數包括 cwd、timeout_ms（默認 120000，範圍 1000–600000）、stdin。
登錄與身份：
feishu_auth action="status"
feishu_auth action="login_start" mode="init"
feishu_auth action="login_start" mode="login"
feishu_auth action="login_wait" login_id="..."
feishu_auth action="logout"
feishu_auth action="list"
feishu_auth action="login_cancel" login_id="..."
約定要點：默認輸出 JSON，成功看 ok == true；寫操作可先 --dry-run；退出碼 10 表示 high-risk-write，需確認後在命令末尾加 --yes 重試。文件路徑參數僅接受工作目錄下的相對路徑，必要時用 cwd 指定目錄。
適用場景與注意¶
適合：已在 DSH 中開發 Agent，希望用同一套官方 CLI 語法操作飛書/Lark，並在 UI 裏完成掃碼登錄與命令試跑；需要覆蓋多業務域 shortcut 或直接 api 調 OpenAPI 的團隊個人工作流。
權限與安全（摘自 README）：
- Agent 以你登錄時授權的用戶身份調用 API，請按需選擇最小 scope；企業租戶下創建自建應用或 scope 可能需要管理員審批。
- 憑據由
lark-cli存放在~/.lark-cli，插件不額外保存 app secret 或 access token。 - 面板 Web API（
/feishu-cli/api/*）僅接受同源、application/json的 POST。 - 第三方插件以當前 DSH 進程的用戶權限運行；安裝前請審閱源碼與 SECURITY.md、PRIVACY.md。插件代碼以 MIT 許可發佈（當前 npm 包版本 1.0.0）。
DSH 生態採用「一切皆插件」；社區目錄 SkillHub 插件頁 爲獨立站點條目，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-feishu-cli 把飛書官方 CLI 搬進 DSH：側邊欄二維碼登錄、命令控制台，以及 feishu_cli / feishu_auth 供 Agent 複用同一套命令與 OpenAPI。經過上面的步驟安裝並重啓後，即可按「初始化應用 → 登錄賬號」完成首次配置，再在面板或對話中執行具體業務命令。
