> ## Documentation Index
> Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Email Assist 入门项目

<div className="not-prose my-4 rounded-md border border-gray-200 bg-gray-50 p-2 text-sm dark:border-gray-800 dark:bg-gray-900/40">
  <div className="mb-2 px-1 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">需要帮助？</div>

  <div className="flex flex-wrap gap-2">
    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://discord.gg/sDE2HhGTg4" target="_blank" rel="noreferrer">
      <Icon icon="discord" iconType="brands" size={14} />

      <span>在 Discord 提问</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/issues/new/choose" target="_blank" rel="noreferrer">
      <Icon icon="github" iconType="brands" size={14} />

      <span>提交 GitHub Issue</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/zh-Hans/SUPPORT.md" target="_blank" rel="noreferrer">
      <Icon icon="life-ring" size={14} />

      <span>支持指南</span>
    </a>
  </div>
</div>

## 摘要

这个入门项目把客户支持案例研究扩展成一个 connector-first 的本地工作流：
通过 Codex Gmail connector 读取 Gmail，先用确定性规则分类客户问题，再把
它们写入 SQLite，并通过本地 dashboard 审阅或批准回复。

## 状态

`starter`

源代码：[case-studies/examples/customer-email-assist-starter](https://github.com/Prompthon-IO/agent-systems-handbook/tree/main/case-studies/examples/customer-email-assist-starter)

## 存在原因

之前的 [Customer Support Email Agent Starter](/zh-Hans/case-studies/examples/customer-support-email-agent-starter)
展示了更安全的仅草稿边界。这个后续入门项目保持同样的本地优先姿态，
但加入了团队下一步通常需要的运行面：Gmail connector 导入、本地 SQLite
状态、客户审核队列，以及一个确定性的 dashboard。

## 相关实验室页面

* [Customer Support Agents](/zh-Hans/case-studies/customer-support-agents)
* [Customer Support Email Agent Starter](/zh-Hans/case-studies/examples/customer-support-email-agent-starter)
* [Case Studies Overview](/zh-Hans/case-studies)

## 文件夹结构

```text theme={null}
customer-email-assist-starter/
├── app/
│   ├── api/
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── index.mdx
├── package.json
├── scripts/
│   └── customer-email-assist.ts
├── skill/
│   └── SKILL.md
└── src/
    ├── components/
    ├── lib/
    └── test/
```

## 快速开始

安装依赖并启动本地 dashboard：

```bash theme={null}
npm install
npm run setup-local
npm run dev
```

默认的低 token 路径是让 Codex 通过 Gmail connector 生成 prepared inbound
batch，然后把这个 batch 导入本地 SQLite：

```bash theme={null}
tsx scripts/customer-email-assist.ts import-prepared-batch --input /tmp/prepared-inbound.json
```

中间 batch 优先写入文件，而不是把大段 JSON 直接打印到 stdout：

```bash theme={null}
tsx scripts/customer-email-assist.ts prepare-draft-batch --out /tmp/draft-batch.json
```

项目里仍保留了高级的本地 Gmail OAuth adapter，用于明确需要 standalone local
integration 的场景，但它不是默认设置路径：

```bash theme={null}
npm run sync:oauth
```

在 connector-first 模式下，dashboard 的批准动作会把 issue 存成
`approved_to_send`，等待 Codex Gmail connector runner 处理。如果本地 OAuth
已经通过 dashboard 的 `Connect Gmail` 完成连接，dashboard 会在 undo 倒计时
结束后立即执行确定性的发送路径。

## 最小 token 边界

这个入门项目专门为了尽量减少模型使用而设计。

* 硬逻辑负责 Gmail connector 导入整形、HTML 清洗、签名裁剪、引用历史移除、
  客户匹配、SQLite 持久化、分析统计和队列状态。
* 预期的 skill 工作流只为两个 JSON-only 表面保留模型使用：
  * 理解清洗后的客户来信
  * 生成回复模板字段 JSON
* 最终渲染出的回复文本和 HTML 在本地通过固定模板生成，而不是依赖自由
  文本模型输出。

## 包含的示例文件

* `skill/SKILL.md`：只为两个模型步骤保留 token 的 Codex 工作流说明
* `src/lib/email-processing.ts`：HTML 清洗、引用历史裁剪和启发式分类辅助工具
* `src/lib/repository.ts`：issues、customers、analytics 和审核动作的 SQLite 查询
* `src/lib/sync.ts`：确定性的来信批次导入、草稿批次和草稿渲染协调逻辑
* `app/page.tsx`：包含 issues、analysis、customer review 和 customer 管理的 Next.js dashboard

## 约束

* 正常工作流中的 Gmail 认证预期通过 Codex Gmail connector 完成。
* 直接 Gmail OAuth 作为 standalone local run 的高级 adapter 保留；只需要
  `GOOGLE_CLIENT_ID` 和 `GOOGLE_CLIENT_SECRET`，refresh token 会由 dashboard
  连接流程写入本地状态。
* v1 忽略附件和内联图片。
* 该 dashboard 面向单操作员和本地机器。
* `import-prepared-batch` 使用确定性的理解和起草兜底逻辑，因此即使没有实时模型调用也能运行。
* `npm run setup-local` 会把本地 SQLite 数据库重置为空状态。

## 验证

* `npm run lint`
* `npm run test`
* `npm run build`

## 后续步骤

* 在 `prepare-inbound-batch` 与 `persist-understanding` 之间接入真实的
  模型 `understand` 步骤。
* 在 `prepare-draft-batch` 与 `render-save-drafts` 之间接入真实的模型
  `draft-fields` 步骤。
* 增加一个基于固定样本的 Gmail 线程回放测试套件。