dsh-lark-bot 0.2.8 → 0.3.0

package/README.md

@@ -86,6 +86,8 @@ dsh-lark-bot start \
 | `/resume` | 查看当前会话最近上下文 |
 | `/stop` | 终止当前任务 |
 | `/timeout [N|off|default]` | 查看或设置当前会话运行超时 |
+| `/density [compact|standard|detailed]` | 查看或设置卡片密度 |
+| `/ask <问题>` | 发送问答卡，回答写入会话上下文 |
 | `/invite user|admin|group <id>`、`/invite list`、`/invite remove user|group <id>` | 管理访问白名单 |
 | `/help` | 查看帮助 |
 
@@ -124,10 +126,14 @@ rm -rf ~/.dsh-lark
 
 ## 兼容性 · Compatibility
 
-- **DeepSeek Harness（`dsh`）**：developer preview（v0.1，2026-08 发布），通过 ACP / JSON-RPC SDK 接入。
+- **DeepSeek Harness（`dsh`）**：已验证 **dsh 0.1.0-rc.6**（2026-08-14：SDK JSON-RPC / ACP runtime 握手 +
+  真实任务流式验证），通过官方 `@deepseek-ai/dsh-sdk-client` / `@deepseek-ai/dsh-acp` 接入；
+  具体锁定版本与漂移策略见 [`docs/adapter-notes.md`](docs/adapter-notes.md)。
 - **运行时**：Node.js ≥ 22（桥接层要求 ≥ 20.12，统一采用 ≥ 22）。
 - **平台**：Linux / macOS / Windows（飞书 WebSocket 出站长连接，免公网服务器 / 域名 / 内网穿透）。
-- 当前 adapter 采用 **headless 子进程 fallback**，通过可配置的 `dsh` 命令与参数驱动，尚未锁定具体 dsh mainline commit；接入 ACP / SDK 的正式版本将在 P2 锁版后声明。
+- 默认 adapter 为官方 **`@deepseek-ai/dsh-sdk-client`**（SDK JSON-RPC runtime，原生 session 续跑 +
+  token 级流式事件）；`DSH_LARK_ADAPTER=acp` 切到官方 **ACP server**（审批卡）；`headless` 保留旧版
+  子进程 fallback。首次启动自动在 `~/.dsh/profiles/dsh-lark`（或 `dsh-lark-acp`）创建 runtime profile。
 
 ## 配置 · Configuration
 
@@ -138,7 +144,8 @@ rm -rf ~/.dsh-lark
 
 会话运行在 Git 仓库中时，会自动在 `~/.dsh-lark/profiles/<profile>/worktrees/<scope>/` 创建隔离 worktree，并复制项目级 `AGENTS.md`。
 
-每个飞书 scope 会保存最近 40 条对话消息，下一次消息会作为上下文传入 dsh headless，从而在无状态 headless 子进程上实现会话记忆。
+每个飞书 scope 会保存最近 40 条对话消息；SDK 模式下 dsh 原生 session 续跑，headless 模式
+则把历史注入下一次 prompt 实现近似记忆。
 
 当前核心环境变量：
 
@@ -148,8 +155,12 @@ rm -rf ~/.dsh-lark
 | `DSH_LARK_TENANT` | `feishu` | `feishu` 或 `lark` |
 | `DSH_LARK_DSH_COMMAND` | `自动发现` | dsh 启动命令；通常无需设置 |
 | `DSH_LARK_DSH_ARGS` | `自动发现` | dsh 启动参数，逗号分隔；通常无需设置 |
+| `DSH_LARK_ADAPTER` | `sdk` | `sdk`（默认）/ `acp`（审批）/ `headless`（legacy） |
 | `DSH_LARK_PROVIDER` | `deepseek-official` | 模型 provider |
 | `DSH_LARK_MODEL` | `deepseek-v4-flash` | 默认模型 |
+| `DSH_LARK_MAX_TOKENS` | 未设置 | SDK agent 每请求输出 token 上限 |
+| `DSH_LARK_ACCESS_DEFAULT_DENY` | `false` | 无白名单时拒绝私聊 |
+| `DSH_LARK_EVENT_FRESHNESS_MS` | `600000` | 过期消息拒绝窗口（0 关闭） |
 | `DSH_LARK_RUN_TIMEOUT_MS` | `300000` | 单次运行墙钟超时 |
 | `DSH_LARK_STOP_GRACE_MS` | `5000` | SIGTERM 后等待优雅退出再 SIGKILL 的宽限期 |
 
@@ -162,7 +173,7 @@ rm -rf ~/.dsh-lark
 - **飞书凭据**：PersonalAgent 应用的 `app_id` / `app_secret`，明文写入本机 `~/.dsh-lark/config.json`（文件权限 600）。
 - **文件系统**：读取 / 写入你通过 `/cd`、`/ws` 指定的工作目录（含执行 shell 命令、修改文件）。
 - **网络**：向飞书开放平台建立 WebSocket 出站长连接收发消息；向 DeepSeek API 发送任务上下文。
-- **进程**：spawn 本机 `dsh` 子进程执行 agent 任务。
+- **进程**：spawn 本机 `dsh` runtime 子进程（`dsh-sdk-jsonrpc-server` / `dsh-acp` profile）执行 agent 任务。
 
 所有数据仅在本机与飞书、DeepSeek 之间流转，不收集、不上传任何遥测。密钥不会提交进仓库（见 `.gitignore`）。
 
@@ -205,6 +216,8 @@ pnpm publish:dual
 
 - **许可证**：GNU Affero General Public License v3.0（见 `LICENSE`）。
 - **安全报告**：如发现安全漏洞，请通过 GitHub Security Advisory 私下报告，勿公开 issue。
+- **安全模型**：默认拒绝、密钥脱敏、路径 containment、SSRF 防护、过期事件拒绝与交互工具
+  默认禁用——详见 [`SECURITY.md`](SECURITY.md)。
 
 ## 文档 · Documentation
 
@@ -233,9 +246,9 @@ pnpm publish:dual
 飞书 / Lark ──WebSocket 长连接──▶ bridge/ ──▶ session/ ──▶ workspace/ ──▶ adapters/ ──▶ dsh ──▶ DeepSeek V4
 ```
 
-核心思路：**飞书通道与 agent 后端解耦**。桥接层复刻 `lark-channel-bridge` 的成熟做法（WebSocket 长连接 + 流式卡片 + 会话路由），agent 后端通过 adapter 抽象，默认挂接 DeepSeek Harness（当前 headless fallback，ACP 正式接入规划在 P2），可切换 claude / codex / opencode。
+核心思路：**飞书通道与 agent 后端解耦**。桥接层复刻 `lark-channel-bridge` 的成熟做法（WebSocket 长连接 + 流式卡片 + 会话路由），agent 后端通过 adapter 抽象，默认挂接官方 DeepSeek Harness SDK（`DSH_LARK_ADAPTER=sdk`），可选 ACP 审批模式与 legacy headless。
 
-The core idea: **decouple the Feishu channel from the agent backend**. The bridge layer follows the battle-tested `lark-channel-bridge` approach (WebSocket long-connection + streaming cards + session routing); the agent backend is abstracted behind an adapter, defaulting to DeepSeek Harness (currently headless fallback, with ACP planned for P2) and swappable to claude / codex / opencode.
+The core idea: **decouple the Feishu channel from the agent backend**. The bridge layer follows the battle-tested `lark-channel-bridge` approach (WebSocket long-connection + streaming cards + session routing); the agent backend is abstracted behind an adapter, defaulting to the official DeepSeek Harness SDK (`DSH_LARK_ADAPTER=sdk`), with an optional ACP approval mode and the legacy headless fallback.
 
 ## 目录结构 · Directory Structure
 

package/SECURITY.md

@@ -0,0 +1,42 @@
+# 安全说明 · Security
+
+> dsh-lark-bot 把本机 DeepSeek Harness（`dsh`）暴露给飞书 / Lark IM。本文件说明威胁模型、
+> 默认安全姿态与报告渠道。Security model for a bridge that exposes a local coding agent to Feishu / Lark.
+
+## 威胁模型 · Threat model
+
+- **凭据泄露**：飞书 `app_id` / `app_secret`、DeepSeek API key、会话内容可能在日志、卡片或进程环境中出现。
+- **越权访问**：未授权用户 / 群聊驱动本机 coding agent 执行命令、读写文件。
+- **路径逃逸 / 符号链接逃逸**：附件、worktree、`/cd` 相关路径穿越到 bot 状态目录之外。
+- **SSRF**：agent 或桥接层被诱导访问内网 / 环回地址。
+- **消息重放 / 过期事件**：旧消息或重复事件被当作新指令处理。
+- **交互工具不可达**：`ask_user_question`、终端类工具在 IM 场景下无法回达，应默认禁用。
+
+## 安全姿态 · Security posture
+
+1. **默认拒绝**：
+   - 群聊 / 话题必须 `@bot` 才响应（传输层强制，`requireMention: true`）。
+   - 配置了白名单后，私聊切换为 allowlist 模式（`dmMode: 'allowlist'`）。
+   - 可通过 `DSH_LARK_ACCESS_DEFAULT_DENY=1` 在无白名单时也拒绝私聊（默认关闭以兼容首次扫码绑定）。
+2. **密钥脱敏**：结构化日志按字段名（`secret/token/password/api_key`）脱敏；
+   自由文本日志与卡片文本对 `Bearer …`、`sk-…`、`api_key=…` 做正则脱敏（`src/config/security.ts`）。
+3. **路径 containment**：媒体下载目标、git worktree 目标必须落在各自根目录内
+   （realpath 校验，拒绝符号链接逃逸，`isPathWithin`）。
+4. **UTF-8 安全截断**：附件文本、卡片摘要按字节截断且不切断多字节字符（`truncateUtf8Safe`）。
+5. **过期事件拒绝**：消息时间戳超出窗口即拒绝（`isEventFresh`）。
+6. **SSRF 防护**：仅允许 http(s) 公网地址；环回、私有、链路本地、CGNAT、IPv6 ULA 全部拒绝
+   （`isSafeHttpUrl`）。
+7. **交互工具默认禁用**：SDK / ACP runtime profile 禁用 `user-questions`；
+   `DEFAULT_DENIED_INTERACTIVE_TOOLS` 提供工具级黑名单。
+8. **审批**：ACP 模式下敏感操作通过 `session/request_permission` 以飞书审批卡一问一答；
+   run 结束 / dispose 时所有挂起审批卡结算为拒绝（`src/bot/approvals.ts`）。
+
+## 数据与凭据 · Data & credentials
+
+- 本地配置 `~/.dsh-lark/config.json` 以 `0600` 权限写入。
+- 飞书凭据明文保存在本机配置文件；日志与卡片不输出真实密钥。
+- 所有数据仅在本机、飞书开放平台与 DeepSeek API 之间流转；无遥测。
+
+## 报告渠道 · Reporting
+
+发现安全漏洞请通过 GitHub Security Advisory 私下报告，**不要**公开 issue。