dsh-lark-bot 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +34 -13
  2. package/SECURITY.md +4 -0
  3. package/dist/cli.js +1004 -43
  4. package/dist/cli.js.map +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -42,7 +42,7 @@ npm install -g dsh-feishu-bot
42
42
 
43
43
  安装完成后，对应命令分别为 `dsh-lark-bot` 和 `dsh-feishu-bot`。
44
44
 
45
- ### 2. 启动并绑定飞书
45
+ ### 2. 启动后台服务并绑定飞书
46
46
 
47
47
  ```bash
48
48
  dsh-lark-bot start
@@ -54,7 +54,7 @@ dsh-lark-bot start
54
54
  dsh-feishu-bot start
55
55
  ```
56
56
 
57
- 首次启动会：
57
+ `start` 会自动在本机安装一个**后台服务**：加入系统开机自启列表，并在进程退出、崩溃或出错时自动重启。首次启动会：
58
58
 
59
59
  1. 在终端显示二维码。
60
60
  2. 用飞书 / Lark App 扫码。
@@ -62,6 +62,8 @@ dsh-feishu-bot start
62
62
  4. 绑定成功后，bot 会向你的私聊发送欢迎卡片。
63
63
  5. 私聊直接发消息；群聊或话题里 `@bot`。
64
64
 
65
+ 绑定完成后 bot 转入后台运行，终端可以随时关闭。
66
+
65
67
  如果你已经有 PersonalAgent 应用，也可以跳过扫码：
66
68
 
67
69
  ```bash
@@ -71,7 +73,18 @@ dsh-lark-bot start \
71
73
  --tenant feishu
72
74
  ```
73
75
 
74
- ### 3. 基本使用
76
+ ### 3. 服务管理命令
77
+
78
+ | 命令 | 作用 |
79
+ | :--- | :--- |
80
+ | `dsh-lark-bot start` | 安装后台服务、加入开机自启并启动（首次运行会先扫码绑定） |
81
+ | `dsh-lark-bot status` | 查看服务状态（退出码 0=运行中，1=未运行） |
82
+ | `dsh-lark-bot restart` | 重启后台服务（保留开机自启） |
83
+ | `dsh-lark-bot stop` | 停止后台服务并移出开机自启 |
84
+
85
+ 后台服务的运行日志写入 `~/.dsh-lark/profiles/<profile>/logs/bot.log`。
86
+
87
+ ### 4. 基本使用
75
88
 
76
89
  在飞书里向 bot 发送普通消息即可开始工作，常用命令：
77
90
 
@@ -82,20 +95,22 @@ dsh-lark-bot start \
82
95
  | `/ws list` | 查看命名工作空间 |
83
96
  | `/ws save <name>` | 保存当前工作空间 |
84
97
  | `/ws use <name>` | 切换到命名工作空间 |
98
+ | `/ws remove <name>` | 删除命名工作空间 |
85
99
  | `/status` | 查看当前状态 |
86
100
  | `/resume` | 查看当前会话最近上下文 |
87
101
  | `/stop` | 终止当前任务 |
88
- | `/timeout [N|off|default]` | 查看或设置当前会话运行超时 |
89
- | `/density [compact|standard|detailed]` | 查看或设置卡片密度 |
102
+ | `/timeout [N\|off\|default]` | 查看或设置当前会话运行超时 |
103
+ | `/density [compact\|standard\|detailed]` | 查看或设置卡片密度 |
90
104
  | `/ask <问题>` | 发送问答卡，回答写入会话上下文 |
91
- | `/invite user|admin|group <id>`、`/invite list`、`/invite remove user|group <id>` | 管理访问白名单 |
105
+ | `/invite user\|admin\|group <id>`、`/invite list`、`/invite remove user\|group <id>` | 管理访问白名单 |
92
106
  | `/help` | 查看帮助 |
93
107
 
94
108
  飞书消息中的图片会下载到本地 media 目录并传给 dsh；文本类文件会读取内容并注入任务上下文。
95
109
 
96
- ### 4. 卸载
110
+ ### 5. 卸载
97
111
 
98
112
  ```bash
113
+ dsh-lark-bot stop
99
114
  npm uninstall -g dsh-lark-bot
100
115
  rm -rf ~/.dsh-lark
101
116
  ```
@@ -116,8 +131,8 @@ rm -rf ~/.dsh-lark
116
131
 
117
132
  ## 目标 · Goals
118
133
 
119
- - **一条命令启动**：clone 后一键安装运行，最终发布到 npm，`npx dsh-lark-bot` 即可拉起。
120
- - **飞书原生体验**：流式卡片、交互按钮、图片 / 文件、文档评论，全程双语。
134
+ - **一条命令启动**：clone 后一键安装运行，最终发布到 npm，`npm i -g dsh-lark-bot && dsh-lark-bot start` 即可拉起后台服务。
135
+ - **飞书原生体验**：流式卡片、交互按钮、图片 / 文件，全程双语（文档评论为规划中能力）。
121
136
  - **完整工作区管理**：多项目隔离、git worktree、项目级规则注入、上下文持久化。
122
137
 
123
138
  - **One-command start**: clone and run in one step, eventually published to npm as `npx dsh-lark-bot`.
@@ -129,7 +144,7 @@ rm -rf ~/.dsh-lark
129
144
  - **DeepSeek Harness（`dsh`）**：已验证 **dsh 0.1.0-rc.6**（2026-08-14：SDK JSON-RPC / ACP runtime 握手 +
130
145
  真实任务流式验证），通过官方 `@deepseek-ai/dsh-sdk-client` / `@deepseek-ai/dsh-acp` 接入；
131
146
  具体锁定版本与漂移策略见 [`docs/adapter-notes.md`](docs/adapter-notes.md)。
132
- - **运行时**：Node.js ≥ 22（桥接层要求 ≥ 20.12，统一采用 ≥ 22）。
147
+ - **运行时**：Node.js ≥ 22.19（见 `package.json` engines）。
133
148
  - **平台**：Linux / macOS / Windows（飞书 WebSocket 出站长连接，免公网服务器 / 域名 / 内网穿透）。
134
149
  - 默认 adapter 为官方 **`@deepseek-ai/dsh-sdk-client`**（SDK JSON-RPC runtime，原生 session 续跑 +
135
150
  token 级流式事件）；`DSH_LARK_ADAPTER=acp` 切到官方 **ACP server**（审批卡）；`headless` 保留旧版
@@ -153,6 +168,7 @@ rm -rf ~/.dsh-lark
153
168
  | :--- | :--- | :--- |
154
169
  | `DSH_LARK_HOME` | `~/.dsh-lark` | 本地状态根目录 |
155
170
  | `DSH_LARK_TENANT` | `feishu` | `feishu` 或 `lark` |
171
+ | `DSH_LARK_WORKSPACE` | 未设置 | 新会话默认工作目录 |
156
172
  | `DSH_LARK_DSH_COMMAND` | `自动发现` | dsh 启动命令；通常无需设置 |
157
173
  | `DSH_LARK_DSH_ARGS` | `自动发现` | dsh 启动参数，逗号分隔；通常无需设置 |
158
174
  | `DSH_LARK_ADAPTER` | `sdk` | `sdk`（默认）/ `acp`（审批）/ `headless`（legacy） |
@@ -187,7 +203,8 @@ rm -rf ~/.dsh-lark
187
203
  - **agent 无响应**：发送 `/status` 查看当前 scope、cwd 和 active run；发送 `/stop` 终止当前任务；超过 `DSH_LARK_RUN_TIMEOUT_MS` 时看门狗会自动终止。
188
204
  - **首次扫码失败**：确认本机时间准确、网络可访问飞书开放平台；已拿到 App ID/Secret 时可用 `--app-id` / `--app-secret` 跳过扫码。
189
205
 
190
- 日志当前为 stderr JSON Lines，`~/.dsh-lark/profiles/<profile>/logs/` 为后续文件日志保留目录。
206
+ 以后台服务方式运行时，日志写入 `~/.dsh-lark/profiles/<profile>/logs/bot.log`（JSON Lines，
207
+ stdout 与 stderr 合并）；当前进程的 stderr 仍为 JSON Lines。
191
208
 
192
209
  ## 开发 · Development
193
210
 
@@ -236,6 +253,7 @@ pnpm publish:dual
236
253
  | [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md) | 生态兼容与交付标准（实现工程师必读）<br>Ecosystem & delivery standards (for engineers) |
237
254
  | [`docs/roadmap.md`](docs/roadmap.md) | 路线图与里程碑<br>Roadmap & milestones |
238
255
  | [`docs/PLAN.md`](docs/PLAN.md) | 主线开发计划与验收标准<br>Development plan & acceptance criteria |
256
+ | [`SECURITY.md`](SECURITY.md) | 安全模型与报告渠道<br>Security model & reporting |
239
257
  | [`AGENTS.md`](AGENTS.md) | AI Agent 开发工作流规范<br>AI agent workflow spec |
240
258
 
241
259
  ## 架构 · Architecture
@@ -258,13 +276,16 @@ The core idea: **decouple the Feishu channel from the agent backend**. The bridg
258
276
  | `src/onboard/` | 首次扫码创建 / 绑定 PersonalAgent 应用<br>First-run QR onboarding |
259
277
  | `src/session/` | 会话路由、排队、访问控制<br>Session routing, queueing, access control |
260
278
  | `src/workspace/` | 项目工作区、git worktree 隔离与规则注入<br>Project workspace, git worktree isolation & rule injection |
261
- | `src/adapters/` | agent 后端适配器（dsh 优先）<br>Agent backend adapters (dsh first) |
279
+ | `src/adapters/` | agent 后端适配器（sdk 默认 / acp 审批 / headless legacy）<br>Agent backend adapters (sdk / acp / headless) |
262
280
  | `src/card/` | 流式卡片状态与渲染<br>Streaming card state & rendering |
263
- | `src/bot/` | 运行注册、消息排队<br>Run registry & message queueing |
281
+ | `src/bot/` | 运行注册、消息排队、审批/问答注册表<br>Run registry, queueing, approval/question registries |
264
282
  | `src/commands/` | 斜杠命令（/cd /ws /new …）<br>Slash commands |
283
+ | `src/cli/` | CLI 入口与 start / status / restart / stop / doctor 命令<br>CLI entry & service commands |
265
284
  | `src/config/` | profile / 配置管理<br>Profile & config |
266
285
  | `src/core/` | 结构化日志<br>Structured logging |
286
+ | `src/media/` | 附件下载与文本注入<br>Attachment download & text injection |
267
287
  | `src/platform/` | 跨平台原子写入<br>Cross-platform atomic writes |
288
+ | `src/service/` | 后台服务管理（systemd / launchd / 计划任务 / 便携 supervisor）<br>Background service management |
268
289
  | `docs/` | 架构、路线图等文档<br>Architecture, roadmap & docs |
269
290
  | `reference/` | 参考研究用的克隆仓库（不提交）<br>Cloned reference repos (not committed) |
270
291
 
package/SECURITY.md CHANGED
@@ -35,6 +35,10 @@
35
35
 
36
36
  - 本地配置 `~/.dsh-lark/config.json` 以 `0600` 权限写入。
37
37
  - 飞书凭据明文保存在本机配置文件；日志与卡片不输出真实密钥。
38
+ - 后台服务把 `DEEPSEEK_API_KEY`、`DSH_LARK_*`、`PATH` 等环境快照到
39
+ `~/.dsh-lark/service/service.env`（`0600`）；systemd / launchd 单元文件中的 `EnvironmentFile`
40
+ 只引用该文件，不内联密钥。
41
+ - 后台运行日志写入 `~/.dsh-lark/profiles/<profile>/logs/bot.log`（JSON Lines，密钥字段脱敏后输出）。
38
42
  - 所有数据仅在本机、飞书开放平台与 DeepSeek API 之间流转；无遥测。
39
43
 
40
44
  ## 报告渠道 · Reporting