客来 GuestCome

面向高客单行业商家的本地营销 Agent：把权威事实、用户关注与商家知识组合成可发布的多模态内容，并连接多台运营手机完成线索触达、私信汇总和回复辅助。

本仓库用于 GuestCome Hackathon 项目展示，GitHub topic 为 guikesong。GuestCome 是商业项目，本仓库公开可查看、可构建的前端源码与系统架构说明；后端、Agent 工具、设备自动化和其他商业核心实现不在公开范围内。

项目背景

高客单行业的线上获客通常存在三类割裂：

• 事实资料、用户真实问题和商家知识彼此分散，内容难以同时兼顾准确性与传播价值。
• 内容生成、人工发布、线索触达、私信承接和回复辅助不在同一条工作流中。
• 多账号、多手机运营缺乏统一状态，容易发生设备串用、重复发送或结果无法追溯。

GuestCome 尝试把这些环节放进一个本地运行、可审核、可追溯的工作台。Hackathon 演示行业为英国留学服务，主题聚焦 2027 英国留学规划。

核心能力

1. 三层内容情报：严格区分事实证据、传播素材和商家知识。
2. 知识驱动的多模态内容：支持文字、图片文字卡、图文、生成图片和短视频五种模式。
3. 人工发布交接：生成带文件清单和哈希的发布包，上传与发布仍由运营人工完成。
4. 多设备线索运营：一台电脑管理多台 Android 运营手机，不同设备并行，同一物理设备串行。
5. 统一私信中心：汇总多设备新私信，并基于已审核知识生成回复建议。
6. 证据分层：本地、模拟、外部 Provider 和真机结果分别记录，不以界面或提示词冒充真实终态。

核心业务链路

权威事实 + 用户问题与内容样本 + 商家知识
  → 审核后的知识条目、传播洞察和选题卡
  → Agent 检索证据并生成多模态内容
  → 形成发布包并交给运营人工发布
  → 多台运营手机扫描并承接线索
  → 新私信统一汇总
  → Agent 生成带依据的回复建议
  → 运营人工回复

技术架构

组件职责

层级	技术与职责
浏览器前端	React 19、TypeScript、React Router、TanStack Query；呈现六段业务流程、人工确认门和证据状态。
本地 API	Fastify；仅监听本机回环地址，负责输入校验、一次性授权消费、查询和持久化入队。
数据与资产	SQLite 保存业务状态、任务、审计事件和证据引用；图片、视频和发布包以本地文件形式保存。
异步执行	Worker 从持久队列领取精确任务，执行 Agent、媒体、OCR 和设备工作流。
Agent Runtime	DeepSeek Harness 负责受控的领域工具调用，文本推理与内容生成使用智谱 glm-5.3-flash。
媒体能力	图片通过 GLM-Image，短视频通过 MiniMax-H3；外部调用必须绑定当次任务和授权。
设备能力	Android + ADB；每台物理设备独立排队和加锁，不同设备可并行。
证据系统	把代码、本地、模拟、外部 Provider 和真机证据分层记录，保留业务 ID、时间和文件哈希。

关键设计原则

• 事实与传播分层：社交内容可以证明“用户关心什么”，不能单独证明政策、费用或录取事实。
• 人工控制高风险动作：发布、真实发送和回复始终保留人工确认。
• 持久化任务而非内存任务：API 只写入精确任务，Worker 独立消费，页面刷新或进程重启不会把临时界面状态当成业务终态。
• 同设备严格串行：同一手机上的 ADB、截图、OCR 和 UI 自动化共享设备锁；不同手机可以并行。
• 未知结果不自动重试：外部创建或真实发送一旦进入结果未知状态，不以自动重试制造重复内容或重复触达风险。
• 证据等级不互相替代：PASS_LOCAL、PASS_SIMULATED、PASS_EXTERNAL 和 PASS_DEVICE 分别表达不同事实。

真实运行界面

以下截图来自 GuestCome 正式本地构建、Fastify API 与 SQLite 数据的浏览器证据采集。页面会如实显示当次未运行或受阻的外部 Provider、社交平台和真机能力；截图不用于把模拟数据表述成真实经营结果。

知识与选题	内容工坊

证据状态说明

状态	含义
PASS_CODE	代码、类型或契约层验证通过。
PASS_LOCAL	本机真实构建、SQLite、OCR 或文件产物验证通过。
PASS_SIMULATED	使用明确标记的设备或业务 fixture 验证状态机，不代表真机通过。
PASS_EXTERNAL	外部 Provider 返回真实终态并完成本地回读。
PASS_DEVICE	指定真机在明确授权范围内完成操作并取得终态。
NOT_RUN / BLOCKED_EXTERNAL	尚未执行或缺少当次外部条件，不会显示为成功。

公开源码范围

本仓库包含

• frontend/src/：GuestCome React 页面、组件、样式、API Client 和 SSE 数据刷新逻辑。
• frontend/public/：前端静态资源。
• frontend/package.json、frontend/tsconfig.json、frontend/vite.config.ts：可独立验证前端构建的配置。
• docs/architecture.png：GuestCome 静态技术架构图。
• docs/screenshots/：经过筛选的真实本地运行截图。

本仓库不包含

• Fastify API、Worker、SQLite schema 与迁移代码。
• Agent 工具、Prompt、Provider 网关和媒体生成实现。
• ADB、OCR、设备锁、线索扫描和消息状态机实现。
• API Key、Token、Cookie、账号资料、真实联系人或本地数据库。
• 商业规则、测试数据、内部证据包和生产部署配置。

前端保留真实的 /api/v1 接口调用，以展示实际产品交互方式；完整业务运行需要未公开的 GuestCome 本地后端。本仓库不提供 mock 后端，也不会用静态成功数据冒充完整系统运行。

安全与隐私

• 前端源码不包含任何 Provider 凭据或真实账号密码。
• 正式后端仅监听本机回环地址，不作为公网服务暴露。
• API Key 只存在于本地运行环境，设置凭据不等于授权执行外部调用。
• README 和截图中的示例不能用于证明自然获客、业务转化或对外发布结果。

授权说明

本仓库是商业项目的部分源码披露，不是完整开源发行版。允许为本次 Hackathon 评审和非商业项目评估下载、构建与查看；其他复制、修改、分发或商业使用需另行取得授权，详见 LICENSE。