X Growth Desk

X Growth Desk 是一个本地运行的 X 内容增长工作台，用来把素材、互动案例和公开数据整理成可审核、可改写、可发布的中文内容草稿。

它不会自动发帖、自动回复或自动操作你的 X 账号。所有生成内容都需要人工审核，所有发布动作都由你手动完成。

项目定位

这个工具适合把日常看到的热点、评论、链接摘要、截图 OCR 和账号数据，整理成一套可反复使用的内容工作流：

• 把今日素材生成短帖、回复、长文和互关文案。
• 沉淀高互动案例，辅助下一次创作。
• 用本地 SQLite 记录 X 公开数据和内容实验结果。
• 用 Chrome 扩展手动采集本人账号或参考账号的公开帖子数据。
• 基于历史表现和参考账号策略，辅助判断下一轮内容方向。

功能速览

入口	用途
短帖	把热点、评论、链接摘要或截图 OCR 改写成可互动短帖。
案例库	保存高互动帖子案例，分析结构规律，并在创作时引用。
回复	基于原帖和评论区氛围生成短小、自然的回复。
长文	把素材整理成 X 长文草稿和 Notion 友好的 Markdown。
互关	生成自然克制的互关互动文案。
数据分析	查看本地采集数据、内容表现、实验草稿和发布匹配。
参考账号	观察公开参考账号，提炼可测试的表达策略和内容机会。
Chrome 采集扩展	在打开 X 页面时，手动采集本人或参考账号的公开页面数据。

快速开始

1. 安装依赖

npm install

2. 准备环境变量

cp .env.example .env

编辑 .env，填入你的 OpenAI-compatible 模型配置：

OPENAI_API_KEY=sk-your-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4.1-mini
ANALYTICS_DATABASE_PATH=data/x-growth.sqlite

3. 启动本地服务

npm run dev

这个命令会同时启动：

• 本地 API：http://localhost:8787
• Vite Web 工作台：终端里显示的本地访问地址，通常是 http://localhost:5173

如果只想分别启动，也可以运行：

npm run dev:api
npm run dev:ui

环境变量

变量	说明	默认或示例
OPENAI_API_KEY	模型接口密钥。缺少时无法生成内容。	sk-your-key
OPENAI_BASE_URL	OpenAI-compatible chat completions 接口地址。	https://api.openai.com/v1
OPENAI_MODEL	使用的模型名称。	gpt-4.1-mini
ANALYTICS_DATABASE_PATH	本地 SQLite 数据库路径。	data/x-growth.sqlite

API 服务端口默认是 8787。如果需要修改，可以通过 PORT 环境变量覆盖；但 Chrome 扩展当前固定访问 http://localhost:8787，日常使用建议保持默认端口。

日常使用流程

1. 在项目根目录运行 npm run dev。
2. 打开终端里显示的 Vite Web 工作台地址。
3. 配置并启用 Chrome 扩展，扩展目录是 extension。
4. 在 Chrome 中登录 X，打开本人主页或参考账号主页。
5. 点击扩展弹窗里的采集按钮，等待公开页面数据写入本地 API。
6. 回到 Web 工作台，在“数据分析”或“参考账号”里刷新和查看数据。
7. 使用“短帖”“案例库”“回复”“长文”等入口生成草稿。
8. 人工审核、修改和手动发布内容。

浏览器扩展

扩展安装步骤见 extension/README.md。

简要流程：

1. 先启动本地服务：npm run dev。
2. 打开 Chrome 的 chrome://extensions。
3. 开启“开发者模式”。
4. 点击“加载已解压的扩展程序”。
5. 选择本项目的 extension 目录。

扩展只在你点击采集按钮时工作。它会读取当前打开的 x.com 或 twitter.com 页面可见内容，并把结果发送到 http://localhost:8787。

数据与隐私

• 默认 SQLite 数据库路径是 data/x-growth.sqlite。
• .env、data/、dist/、node_modules/ 和 TypeScript 构建缓存不会进入版本管理。
• Chrome 扩展不保存账号密码、Cookie，也不会自动发帖或回复。
• 采集数据保存在本机 SQLite 中，用于数据分析、参考账号观察和内容实验匹配。
• 模型生成通过你配置的 OpenAI-compatible endpoint 完成，请按你的模型服务隐私政策使用。

常用命令

命令	用途
npm run dev	同时启动本地 API 和 Vite Web 工作台。
npm run dev:api	只启动本地 API，默认监听 http://localhost:8787。
npm run dev:ui	只启动 Vite Web 工作台。
npm test	运行 Vitest 自动化测试。
npm run build	运行 TypeScript 检查并构建前端生产包。

基础 FAQ

页面提示无法连接本地服务怎么办？

确认 npm run dev 或 npm run dev:api 正在运行，并且 API 地址是 http://localhost:8787。

点击生成时提示 OPENAI_API_KEY is not configured 怎么办？

确认已经从 .env.example 复制出 .env，并填写了 OPENAI_API_KEY。修改 .env 后需要重启本地 API。

Chrome 扩展采集失败怎么办？

确认本地 API 已启动，Chrome 当前标签页是 https://x.com/... 或 https://twitter.com/...，并且加载的是项目里的 extension 目录。

数据库文件在哪里？

默认在 data/x-growth.sqlite。如果 .env 中设置了 ANALYTICS_DATABASE_PATH，则使用你指定的路径。