# dialog-survey 中文文档

规范地址：https://npmcn.com/package/dialog-survey/

版本：1\.13\.5
npm 元数据更新时间：2026-11-03T09:35:21.016Z
中文译文更新时间：2026-11-03T11:56:20.508Z
软件包许可：未声明

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/dialog-survey
原文对照：https://npmcn.com/package/dialog-survey/?lang=original
项目主页：https://github.com/boyingliu01/dialog-survey#readme
源码仓库：https://github.com/boyingliu01/dialog-survey

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.9 MB，435 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：27 个
- 首次发布：2026-06-17T01:37:12.095Z
- 最新版本发布：2026-11-03T09:35:20.623Z
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

人工智能调查对话机器人，通过钉钉进行异步多回合对话

## 安装

```sh
npm install dialog-survey
```

也可以使用：`pnpm add dialog-survey`、`yarn add dialog-survey`、`bun add dialog-survey`

## README

# Dialog Survey

> **把钉钉对话转化成结构化洞察。**
> 
> 一款 AI 驱动的异步对话机器人，通过钉钉自动进行多轮问卷对话——具备 LLM 智能追问、跨消息上下文记忆、以及自动化报告生成能力。

[![Version](https://img.shields.io/badge/version-1.10.0-blue)](https://github.com/boyingliu01/dialog-survey) ![Node](https://img.shields.io/badge/node-%3E%3D20.19-brightgreen) ![License](https://img.shields.io/badge/license-MIT-green)

* * *

## 快速开始

```bash
# 一键安装——交互式提示填入各项配置
npx dialog-survey install

# 启动服务
npx dialog-survey start

# 完成。你的对话机器人已经在钉钉上就绪。
```

**环境要求：** Node.js >= 20.19、PostgreSQL 14+、一个钉钉应用（Client ID / Secret / Agent ID）

* * *

## Why — 为什么做这个项目？

**一对一交流的效果非常好。** 优秀的沟通者能建立信任、听懂弦外之音、在恰当时刻追问关键问题——但和几百上千人逐一深谈，成本太高，难以规模化。

**问卷调查能覆盖大量人群**，但深度有限——固定的问卷无法在受访者说出意料之外的答案时灵活追问。

Dialog Survey 填补了这两者之间的空白：**比问卷深入，比人工对话广泛。** AI 驱动的对话机器人能像人类一样对有价值的回答进行深入追问，同时通过钉钉并行触达成百上千位参与者。它不会取代真实的对话——但当需要从大规模人群中获取结构化的一手信息时，这是最接近人工沟通体验的选择。

* * *

## What — 这个项目是什么？

Dialog Survey 是一个**驻留在钉钉里的异步对话机器人**。你设计一个问卷模板、邀请参与者，AI 就会和每个人进行多轮对话——提出初始问题、在有价值的回答上深入追问、跨消息跨天数地记住上下文。

### 核心能力

| 能力 | 说明 |
| --- | --- |
| **AI 智能追问** | 基于 LLM 的深层追问——当参与者说到有趣的内容时，机器人会自动深入挖掘 |
| **多轮上下文记忆** | 跨越数天、数十条消息的连贯对话，而非孤立的 Q&A |
| **异步消息对话** | 参与者在钉钉上利用碎片时间回答——无需排期通话，没有压迫感 |
| **自动生成报告** | 对话结束后自动生成 Markdown 报告，支持 PDF/Excel 导出（基于 Playwright） |
| **私有部署** | 所有数据留在你的基础设施中。你的 PostgreSQL、你的 LLM（ollama / vLLM / 云端）、你的钉钉应用 |

### 近期更新 (v1.10.x)

-   **v1.10.0** — Prisma 6 → 7 升级，改用 driver adapters。测试不再依赖 PostgreSQL：整套测试跑在 PGlite（每个测试文件独立的 WASM 数据库）上，`npm test` 零手动步骤即可运行。Node.js 要求提升至 >= 20.19.0
-   **v1.8.1** — 文档大刷新：AGENTS.md 从 597 行压缩至 88 行，新增子目录 AGENTS.md
-   **v1.8.0** — 移除未使用的 ASR 语音识别。修复 COMPLETED 状态对话陷入 CONTINUE 循环的 bug。修复 maxFollowups 未持久化到数据库的问题。修复添加成员时错误信息被静默吞掉的问题
-   **v1.7.9** — CI 稳定性：修复不稳定的集成测试，清理示例配置中的敏感信息
-   **v1.7.8** — 统一 tsconfig.json，修复 35 个文件中的 81 个类型错误

> 完整变更日志见 [CHANGELOG.md](https://npmcn.com/package/dialog-survey/CHANGELOG.md)。

* * *

## How — 怎么使用这个项目？

### 技术栈

| 层级 | 技术 |
| --- | --- |
| **对话引擎** | 自研 LangGraph 工作流 |
| **LLM** | OpenAI 兼容 API——ollama / vLLM / LocalAI / 云端 |
| **消息平台** | 钉钉 Stream Mode (WebSocket) |
| **数据库** | PostgreSQL + Prisma 7（driver adapters） |
| **Web 框架** | Fastify 5.x |
| **模板引擎** | Nunjucks（管理后台 UI） |
| **语言** | TypeScript（严格模式，ESM） |

* * *

### 安装方式

#### 方式 A：CLI 快捷安装（生产环境推荐）

```bash
# 交互式安装
npx dialog-survey install

# 非交互式安装（CI / 自动化）
npx dialog-survey install \
  --db-url "postgresql://user:pass@localhost:5432/dialog_survey" \
  --dingtalk-client-id "xxx" \
  --dingtalk-client-secret "xxx" \
  --dingtalk-agent-id "xxx"
```

CLI 会自动生成 `.env`、通过 `prisma migrate deploy` 应用数据库迁移（Prisma 7）、并配置 PM2（Linux/macOS）或直接 node 启动（Windows）。

#### 方式 B：Docker Compose（评估推荐）

```bash
git lfs install && git lfs pull    # 中文字体是 Git LFS 对象（见下）
cp .env.example .env
# 填入钉钉 + LLM 配置，并设置 POSTGRES_PASSWORD
docker compose up -d
curl -i http://localhost:3001/health/ready   # 配置完整才返回 200
```

三个能省下一个晚上的提示：

-   **`.env` 里的 `ADMIN_PASSWORD_HASH` 要用 `$$` 而不是 `$`。** compose 会对 `env_file` 的值做变量插值，`$2b$12$...` 被截断成 `$2b$12`，管理员登录对**正确**的口令也返回 401。 应写成 `ADMIN_PASSWORD_HASH=$$2b$$12$$<salt><digest>`。直接安装（`npx dialog-survey install`、PM2、`docker run -e`）不走插值，用的是单个 `$` 形式。
-   **`git lfs pull` 不是可选项。** 不执行时检出的只是 133 字节的指针文件，导出的 PDF 中文全是空白方框。现在 Docker 构建遇到这种状态会直接失败。
-   **`/health` 对 degraded 部署仍返回 200**（进程活着，但凭据缺失），要探活请看 `/health/ready`。详见 [DEPLOY.md](https://npmcn.com/package/dialog-survey/DEPLOY.md#health-checks)。

#### 方式 C：手动安装（开发环境）

```bash
git clone https://github.com/boyingliu01/dialog-survey
cd dialog-survey
npm install
cp .env.example .env
# 编辑 .env 填入你的配置
npx prisma generate && npx prisma migrate dev
npm run dev
```

* * *

### 生命周期管理

```bash
npx dialog-survey start      # 启动服务
npx dialog-survey stop       # 停止服务
npx dialog-survey status     # 查看状态
npx dialog-survey uninstall  # 完全卸载（保留数据）
npx dialog-survey help       # 查看所有命令
```

* * *

### 配置说明

关键环境变量（完整列表见 `.env.example`）：

| 变量 | 说明 | 示例 |
| --- | --- | --- |
| `DATABASE_URL` | PostgreSQL 连接串 | `postgresql://user:pass@localhost:5432/dialog_survey` |
| `LLM_BASE_URL` | LLM 服务地址（OpenAI 兼容）—— 必须是完整的 chat completions 端点 | `http://localhost:11434/v1/chat/completions` |
| `LLM_MODEL` | 模型名称 | `qwen2.5` |
| `DINGTALK_CLIENT_ID` | 钉钉 Client ID | 从钉钉开放平台获取 |
| `DINGTALK_CLIENT_SECRET` | 钉钉 Client Secret | 从钉钉开放平台获取 |
| `DINGTALK_AGENT_ID` | 钉钉 Agent ID | 从钉钉开放平台获取 |
| `DISABLE_STARTUP_RESEND` | 跳过启动时未发消息补发（`1`/`true`/`yes`） | `1` |
| `ADMIN_API_KEY` | 管理后台 API Key | 自定义密钥 |

> 留空 `LLM_API_KEY` 则默认使用本地 LLM（`http://localhost:11434/v1/chat/completions`）。 `LLM_BASE_URL` 必须是**完整的** chat completions 端点（`…/v1/chat/completions`），而非网关基址——填基址会让 `/health` 和每次 LLM 调用返回 HTTP 404。 未配置 `DINGTALK_CLIENT_ID`/`DINGTALK_CLIENT_SECRET` 时服务以只读模式启动（不建立 Stream 连接、不发送任何出站消息）；启动补发还需 `DINGTALK_AGENT_ID`。

* * *

### 生产部署

**Linux / macOS** (PM2)：

```bash
npm run build
pm2 start dist/src/server-entry.js --name dialog-survey
pm2 save && pm2 startup
```

**Windows**（直接 node 启动）：

```bash
npm run build
node dist/src/server-entry.js
```

**Docker**：

```bash
docker compose up -d
docker compose logs -f app
```

健康检查：`curl http://localhost:3001/health`（存活）与 `curl -i http://localhost:3001/health/ready`（就绪，容器健康检查应当用这个）。

> **安全提示**: `pm2 save` 会把进程的完整环境变量持久化到 `~/.pm2/dump.pm2` （权限跟随 umask，通常为 0644，全局可读）。安装器与 `npx dialog-survey start` 会在每次启动时剥离密钥并用 `--update-env` 刷新 PM2 子进程环境（#193）—— 但裸的 `pm2 restart dialog-survey` **不会**刷新环境变量。如果你曾在导出着 密钥的 shell 里执行过 `pm2 save`，请立即收紧权限、用 `pm2 restart dialog-survey --update-env` 重启，并轮换相关密钥：
> 
> ```bash
> chmod 700 ~/.pm2 && chmod 600 ~/.pm2/dump.pm2
> ```

* * *

### 开发命令

```bash
npx prisma generate  # 生成 Prisma Client（检出后必跑）
npm run dev          # 热重载开发服务器，端口 :3001
npm run type-check   # TypeScript 类型检查
npm test             # Vitest watch 模式；一次性运行用 npx vitest run — 不需要 PostgreSQL（PGlite）
npm run lint         # Biome 代码检查
npm run build        # 编译到 dist/
npm run smoke        # 快速验证（类型检查 + lint + 核心测试）
```

* * *

### 项目结构

```
dialog-survey/
├── src/
│   ├── api/          # Fastify 路由
│   ├── core/         # 图工作流引擎
│   ├── services/     # 业务逻辑（18 个服务）
│   ├── repositories/ # 数据访问层 (Prisma)
│   ├── integrations/ # 钉钉 + LLM 客户端
│   ├── middleware/   # Fastify 中间件
│   ├── views/        # Nunjucks 管理后台 (HTMX + Alpine.js)
│   ├── generated/    # Prisma Client 生成物（gitignore；npx prisma generate）
│   └── utils/        # 工具函数（日志、安全、PII 等）+ Prisma 门面/工厂
├── tests/            # 118 个测试文件，~1283 个测试用例（Vitest + PGlite，无需 PostgreSQL）
├── scripts/          # CLI 入口 + 部署脚本
├── prisma/           # Schema + 迁移 + 种子数据
└── docs/             # 架构与设计文档
```

* * *

### 进一步阅读

-   [DEPLOY.md](https://npmcn.com/package/dialog-survey/DEPLOY.md) — 详细部署指南
-   [AGENTS.md](https://npmcn.com/package/dialog-survey/AGENTS.md) — AI Agent 代码库地图
-   [CHANGELOG.md](https://npmcn.com/package/dialog-survey/CHANGELOG.md) — 完整发布历史
-   [Architecture](https://npmcn.com/package/dialog-survey/architecture.yaml) — 架构验证规则

* * *

## License

MIT

## 常见问题

### dialog-survey 是什么？

人工智能调查对话机器人，通过钉钉进行异步多回合对话

### 如何安装 dialog-survey？

在项目目录运行 npm install dialog-survey，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 dialog-survey，可以用 npx dialog-survey 直接运行。

### dialog-survey 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dialog-survey 是否存在。

### dialog-survey 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### dialog-survey 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### dialog-survey 可以商用吗？

dialog-survey 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### dialog-survey 还在维护吗？

最新版本 1\.13\.5 发布于 2026/11/03（今天）；至今共发布 30 个版本，其中过去 12 个月发布了 30 个；首次发布于 2026/06/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。