wangzhuo-coding/geo-content-optimizer
GEO生成式引擎优化智能体 — 7类关键词+七层架构+EE-A-T权威框架+8维度降痕改写
安装Install
dsh plugin --profile web add github:wangzhuo-coding/geo-content-optimizer把 wangzhuo-coding/geo-content-optimizer 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
GEO Content Optimizer
English | 中文
输入企业文献资料 → 自动产出适配豆包/Kimi/DeepSeek/通义千问/GPT 等大模型向量库收录的高质量原创文章，并消除 AI 生成痕迹。
GEO（Generative Engine Optimization，生成式引擎优化）内容优化智能体 —— 跨平台、无平台依赖。区别于传统 SEO 面向搜索引擎爬虫，GEO 面向的是 AI 摘要器和答案引擎：让大模型"读得懂、愿意引、能溯源"。
功能特色
核心能力
| 能力 | 说明 |
|---|---|
| 📄 多格式文献解析 | 支持 PDF / Word / Excel / PPT / TXT，一键提取纯文本 |
| 🔑 7类关键词挖掘 | 核心搜索词、长尾场景词、地域实体词、人群标签词、问题描述词、品牌专属词、场景触发词，结构化输出强制（Pydantic schema），按优先级公式排序 |
| ✍️ 七层架构内容生成 | EE-A-T 权威性框架 + ACES 结论前置范式 + 三段式 Hook 开篇 + 语义实体密度网络 |
| 🧹 8维度 AI 降痕 | 句子结构/段落节奏/用词习惯/情感浓度/例证来源/完美度/个性化/关键词密度，3 级别分级处理 |
| 🛡️ Stage 5 质量守门 | 极限词 lint、品牌溯源密度、结构完整性、反幻觉守门（数值溯源核验）、可选 LLM-as-Judge 评分 |
| 📏 字数自动校准 | LLM 不会数数——程序侧实测字数，偏离「≥1800字/约1500字/不超过2000字」要求时定向扩写/压缩，最多 2 轮收敛到 ±10% 容差带 |
| 🌐 联网检索补充 | Tavily / Bing RSS / DuckDuckGo 三引擎自动切换，中国可用 |
| 📝 Word 文档导出 | Markdown → 格式化 Word（.docx），支持标题/表格/列表/代码块 |
| 🧩 MCP 协议集成 | 一行配置接入 Claude Desktop / Claude Code / WorkBuddy 等 AI 工具 |
| 📦 智能分块 | 长文本自动分块（≤60000字符/块，重叠500字符），分块结果合并后再进入下游 |
6种使用方式
CLI 交互模式 → 终端对话，适合快速试用
命令行直接处理 → --file/--text 参数，适合批量脚本
Streamlit Web UI → 浏览器操作，适合非技术用户
HTTP API → FastAPI 服务，适合集成到现有系统
MCP Server → 接入 Claude 等 AI 工具，对话式调用
DSH 插件 → DeepSeek Harness 原生工具（mcp__geo__*），见 docs/dsh-integration.md
架构
输入文献 → [Stage 0 联网检索(可选)] → [Stage 1 清洗切片] → [Stage 2 关键词提取] → [Stage 3 内容生成] → [Stage 4 降痕改写] → [Stage 5 质量守门] → 成品文章 + Word文档
| 阶段 | 功能 | 核心方法 |
|---|---|---|
| Stage 0 | 联网检索（可选） | 自动提取关键概念，三引擎搜索并行补充资料，丰富文献素材 |
| Stage 1 | 文献清洗与切片 | 过滤噪声、语义分块（段落/句子边界）、提取品牌信息；长文本自动分块并行处理 |
| Stage 2 | 关键词提取 | 7类关键词（结构化输出强制）+ 优先级公式（搜索量×相关性×竞争强度）三级排序 |
| Stage 3 | 内容生成 | EE-A-T 权威性框架 + ACES 结论前置 + 七层写作架构 + 语义实体密度 + FAQ/可引用事实块 |
| Stage 4 | 降痕改写 | 8维度 AI 去痕 + 3级别分级（轻度/中度/深度）+ 自检清单 |
| Stage 5 | 质量守门 | 极限词 lint + 品牌溯源密度 + 结构完整性 + 反幻觉守门 + 可选 LLM-as-Judge 评分（评分默认仅供参考、不阻断输出；传 strict=True 时低于达标线会在结果顶部显式标注「❌ 未达发布线」） |
快速开始
1. 安装
# 克隆仓库
git clone https://github.com/wangzhuo-coding/geo-content-optimizer.git
cd geo-content-optimizer
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# 安装核心依赖
pip install -e .
可选功能（按需安装）：
pip install -e ".[mcp]" # MCP Server（接入Claude等AI工具）
pip install -e ".[webui]" # Streamlit Web UI
pip install -e ".[postgres]" # PostgreSQL 持久化
pip install -e ".[s3]" # S3 文件存储
pip install -e ".[all]" # 全部可选功能
Windows 用户：直接运行
setup.bat一键安装。中国网络建议使用镜像源：pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple
2. 配置 API Key
cp .env.example .env # Windows: copy .env.example .env
编辑 .env 文件，填入你的 LLM API Key：
OPENAI_API_KEY=sk-xxx # 你的 API Key（必填）
OPENAI_BASE_URL=https://api.openai.com/v1 # API 地址
OPENAI_MODEL_NAME=gpt-4o # 模型名称
兼容的 API 供应商：
| 供应商 | Base URL | 模型示例 |
|---|---|---|
| OpenAI | https://api.openai.com/v1 |
gpt-4o |
| DeepSeek | https://api.deepseek.com |
deepseek-chat |
| 豆包（字节跳动） | https://ark.cn-beijing.volces.com/api/v3 |
doubao-seed-2-0-pro |
| 通义千问 | https://dashscope.aliyuncs.com/compatible-mode/v1 |
qwen-max |
| Kimi（月之暗面） | https://api.moonshot.cn/v1 |
moonshot-v1-8k |
3. 运行
方式一：CLI 交互模式
python -m src # 最简单
python src/cli.py # 等效
run.bat # Windows 一键启动
方式二：命令行直接处理
# 输入文本，自动保存到 output/ 目录
python src/cli.py --text "你的文献内容..."
# 处理文件 + 品牌信息
python src/cli.py --file document.pdf --brand "品牌名, 官网地址"
# 启用联网检索 + 导出 Word 文档
python src/cli.py --file doc.pdf --search --docx
# 全功能：文件 + 品牌 + 联网检索 + Word导出
python src/cli.py --file doc.pdf --brand "华为, https://www.huawei.com" --search --docx
| 参数 | 说明 |
|---|---|
--text "内容" |
直接输入文本 |
--file 路径 |
输入文件（PDF/Word/Excel/PPT/TXT） |
--brand "信息" |
品牌补充信息 |
--search |
启用联网检索（增加1-2分钟） |
--docx |
导出 Word 文档（.docx） |
--output 路径 |
指定 Markdown 输出路径 |
--verbose |
显示详细日志 |
方式三：Web UI
pip install -e ".[webui]"
streamlit run src/web_ui.py
浏览器打开后可上传文件、粘贴文本、勾选联网检索和 Word 导出，实时查看处理进度。
方式四：HTTP API 服务
python -m uvicorn src.main:app --host 127.0.0.1 --port 5000
| 接口 | 方法 | 说明 |
|---|---|---|
/run |
POST | 同步执行 Agent |
/stream_run |
POST | SSE 流式执行 |
/cancel/{run_id} |
POST | 取消任务 |
/v1/chat/completions |
POST | OpenAI 兼容接口 |
/health |
GET | 健康检查 |
/graph_parameter |
GET | Agent 图参数 |
Swagger 文档：启动后访问 http://127.0.0.1:5000/docs
调用示例：
curl -X POST http://127.0.0.1:5000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"messages": [{"role": "user", "content": "请优化这篇文献内容..."}]}'
方式五：MCP Server（接入 Claude 等 AI 工具）
pip install -e ".[mcp]"
# stdio 模式（Claude Desktop / Claude Code / WorkBuddy）
python src/mcp_server.py
# SSE HTTP 模式（Web 客户端）
python src/mcp_server.py --transport sse --port 5001
配置 Claude Desktop（%APPDATA%\Claude\claude_desktop_config.json）：
重要：不要在 MCP 配置中写
env字段传 API Key！Claude Code 的env会覆盖整个环境变量（包括 Windows 必需的PATH），导致 Python 找不到系统 DLL 而启动失败（错误码 -32000）。API Key 请在项目.env文件中配置，MCP Server 启动时自动读取。
{
"mcpServers": {
"geo-content-optimizer": {
"command": "python",
"args": ["src/mcp_server.py"],
"cwd": "/path/to/geo-content-optimizer"
}
}
}
配置 WorkBuddy（~/.workbuddy/mcp.json）：
{
"mcpServers": {
"geo-content-optimizer": {
"command": "/path/to/geo-content-optimizer/.venv/Scripts/python.exe",
"args": ["src/mcp_server.py"],
"cwd": "/path/to/geo-content-optimizer"
}
}
}
MCP 工具列表：
| 工具 | 参数 | 说明 |
|---|---|---|
parse_document |
file_path: str |
解析 PDF / Word(.docx) / TXT / CSV / Excel(.xlsx) / PPT(.pptx) 文件（旧版 .doc/.xls/.ppt 不保证支持） |
run_geo_pipeline |
cleaned_text, brand_info="", enable_search=false, user_requirements="", output_docx="" |
执行4阶段 GEO 流水线 |
web_search |
query: str, max_results=5 |
联网搜索 |
search_and_enrich |
text: str, brand_info="", max_queries=3 |
提取概念+搜索+合并 |
配置完成后，在 Claude/WorkBuddy 中直接对话即可调用：
用户: 请帮我优化这篇华为云的产品白皮书
Claude: → 调用 parse_document 解析文件
→ 调用 run_geo_pipeline 执行4阶段流水线
→ 返回成品文章
方式六：DSH 插件（DeepSeek Harness 原生工具）
本项目同时是一个 dsh-plugin：仓库内置 dsh-plugin/ 插件包，经 dsh plugin add
装入 DeepSeek Harness 的 web profile 后，DSH 会 spawn 项目的 FastMCP Server 并把
4 个工具注册为模型原生工具 mcp__geo__parse_document / run_geo_pipeline /
web_search / search_and_enrich（支持崩溃自动重连，长任务超时已预设 10 分钟）。
# 前置：装依赖 + 把运行实例指向“你的克隆”（见 dsh-plugin/README.md）
# python -m venv .venv && .venv\Scripts\python -m pip install -e ".[mcp]"
# scripts\dsh-plugin-setup.ps1 （Linux/macOS: bash scripts/dsh-plugin-setup.sh）
# 安装插件（与 profiles/web/cordis.patch.yml 直插行二选一；<你的克隆> 替换为实际路径）
dsh plugin --profile web add <你的克隆>/dsh-plugin
dsh web restart # 重启后新会话工具目录出现 mcp__geo__*
配套的「GEO 创作」agent preset 备份在 dsh-plugin/preset/；安装、可移植性与验收见
docs/dsh-integration.md 与 docs/dsh-validation.md。工作实例由 GEO_PROJECT_ROOT /
GEO_PYTHON 两个环境变量决定（默认指向你的克隆，未配置会显式报错而非静默无工具）；
API Key 由实例目录下的 .env 提供（mcp_server.py 自带 load_dotenv）。
用户特殊要求与双闸门（可选）
run_geo_pipeline 支持 user_requirements 参数（内容方向/目标人群/字数/风格/关键词/平台等）。传入后：
- 写作（Stage 3/4）按三层优先级裁定用户要求：合规/事实/黑帽红线（Tier 0）拒绝并给合规替代；GEO 底线（Tier 1，EE-A-T/ACES/语义实体密度）尽量双赢、二选一保 GEO；其他要求（Tier 2）在约束内最大化满足
- 评分（Stage 5）增独立第二轴"用户要求满足度"（0-100%），与 100 分 GEO 基线构成双闸门：GEO 达标 且 满足度≥80% 才可发布；合规冲突的要求被拒绝+给替代，不计入满足度（默认仅作评分卡建议、不阻断输出；
run_geo_pipeline(strict=True)时低于达标线会在结果顶部显式标注未达发布线）
不传 user_requirements 则行为不变（第二轴不激活），与生态中 geo-writer/geo-scorer 技能的机制一致。
字数自动校准（R3）
LLM 对"字数"没有稳定感知——同一个「≥1800字」要求可能产出 1200~4700 字。因此流水线不信任模型的字数自评，改为程序侧闭环校准：
- 从
user_requirements解析长度目标：≥1800字（下限）/不超过2500字（上限）/约1500字（贴近）/1800-2500字（区间）； - Stage 4 降痕改写后，程序用
len(text)实测字数； - 偏离容差带（默认 ±10%，
PIPELINE_LENGTH_TOLERANCE）时，定向执行「扩写/压缩」修正，最多PIPELINE_MAX_LENGTH_ATTEMPTS（默认 2）轮，收敛即停； - 修正仍未落带时如实告警并接受残余偏差，不会死循环。
无字数要求时该流程完全跳过，行为与旧版一致。
运行时长提示
单次运行 = 5 阶段串行 LLM + 可选 LLM 评分 + 可选联网检索。追求更快时可按需开关：
PIPELINE_QUALITY_JUDGE=false：跳过 LLM 评分（只跑确定性 lint，省一次 LLM 往返）；PIPELINE_SEARCH_MAX_QUERIES=1：联网检索只提取 1 个关键词（默认 3）；PIPELINE_MAX_LENGTH_ATTEMPTS=1：字数校准最多修正 1 轮（默认 2）。
结构化输出降级说明
若日志出现 with_structured_output failed ... response_format type is unavailable now：说明当前模型/接口不支持原生 JSON-Schema 结构化输出。流水线会自动降级为「自由文本 + Pydantic 修复解析」（功能可用，但 Stage1/2 的 schema 强制力下降）。建议改用支持 response_format=json_schema 的模型或 OpenAI 兼容接口。
常驻部署与自愈（R7 B6）
MCP server 默认由客户端（Claude Code 等）每次会话 spawn（stdio），无需常驻。若需常驻部署（服务器/开发机），推荐用进程托管实现"崩溃自动重启"：
- PM2（跨平台）：
npm i -g pm2 && pm2 start scripts/mcp_pm2.config.js（配置含autorestart+ 指数退避 + 内存上限重启；pm2 save && pm2 startup开机自启）。Windows 用.venv/Scripts/python.exe，Linux/macOS 改.venv/bin/python（见配置文件注释）。 - systemd（Linux）：
sudo cp scripts/mcp_mcp_server.service /etc/systemd/system/ && sudo systemctl enable --now geo-mcp-server（Restart=always，崩溃 3 秒后自动拉起）。
说明：-32000 Connection closed 断连后，自动重连是客户端侧行为（Claude Code 收到断连后重试）；server 侧通过 async + asyncio.to_thread 保持事件循环可响应（长任务不阻塞其他请求/ping），已在代码内实现。
环境变量
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
OPENAI_API_KEY |
是 | — | LLM API Key |
OPENAI_BASE_URL |
否 | https://api.openai.com/v1 |
API 地址 |
OPENAI_MODEL_NAME |
否 | gpt-4o |
模型名称 |
AGENT_TEMPERATURE |
否 | 0.7 |
Agent 温度 |
AGENT_MAX_TOKENS |
否 | 32768 |
Agent 最大 tokens |
PIPELINE_MAX_CHUNK_CHARS |
否 | 60000 |
单块最大字符数（语义分块） |
PIPELINE_LLM_MAX_RETRIES |
否 | 3 |
LLM 重试次数（仅瞬时网络/限流错误） |
PIPELINE_LLM_TIMEOUT |
否 | 600 |
Pipeline LLM 调用超时秒数 |
PIPELINE_LLM_MODEL |
否 | 空（同 OPENAI_MODEL_NAME） | Pipeline 专用模型 |
PIPELINE_MAX_CONCURRENCY |
否 | 4 |
分块处理 / 联网检索并行并发度 |
PIPELINE_MAX_INPUT_CHARS |
否 | 200000 |
流水线输入文本上限（字符），超过自动截断并告警；0 关闭（token 成本控制） |
PIPELINE_STAGE3_MAX_SLICES |
否 | 0 |
Stage 3 提示词最多嵌入的切片数（top-K 截断，降 token 成本）；0 不限制 |
PIPELINE_LENGTH_TOLERANCE |
否 | 0.10 |
字数校准容差（±10%）。在 user_requirements 中检测到字数要求（如「≥1800字」「约1500字」）时，流水线程序侧测字数并定向扩写/压缩直到落带 |
PIPELINE_MAX_LENGTH_ATTEMPTS |
否 | 2 |
字数校准最大修正轮数（模型不会数数，靠程序测量+定向修正收敛；超限后接受残余偏差并告警） |
PIPELINE_QUALITY_JUDGE |
否 | true |
是否启用 Stage 5 LLM 评分（关闭则只跑确定性 lint，零 token 成本、运行更快） |
PIPELINE_QUALITY_THRESHOLD |
否 | 80 |
GEO 基线达标线（默认 80，对齐项目硬要求 GEO≥80 才可发布；接入 judge prompt，并作为双闸门的 GEO 门） |
PIPELINE_SEARCH_MAX_QUERIES |
否 | 3 |
联网检索每个文本提取的查询数（调小可缩短联网阶段耗时） |
PIPELINE_GATE_HARD_DATA |
否 | false |
可选闸门：素材显著数字（≥1000）未出现在正文时拦截"硬数据模糊化"（默认关，避免误报） |
PIPELINE_TEMPERATURE_GEN / PIPELINE_TEMPERATURE_REWRITE |
否 | 0.8 / 0.4 |
Stage3 生成 / Stage4 改写的温度（设 0 可近似复现，便于调试） |
PIPELINE_REQUIREMENT_SATISFACTION_THRESHOLD |
否 | 80 |
用户要求满足度达标线（双闸门第二轴门，仅当传入 user_requirements 时启用） |
GEO_API_KEY |
否 | 空 | HTTP 写接口鉴权（配置后需 Authorization: Bearer；默认服务仅绑定 127.0.0.1，未配置 key 时启动会打印安全警告） |
TAVILY_API_KEY |
否 | - | Tavily 搜索 Key（不配则用免费引擎） |
PGDATABASE_URL |
否 | — | PostgreSQL 连接（配置后持久化） |
S3_* |
否 | — | S3 存储配置 |
HTTP_PORT |
否 | 5000 |
HTTP 服务端口 |
HTTP_HOST |
否 | 127.0.0.1 |
HTTP 服务绑定地址（默认仅本机；需对外暴露时改 0.0.0.0 并设置 GEO_API_KEY） |
MCP_SSE_HOST |
否 | 127.0.0.1 |
MCP SSE 服务绑定地址（默认仅本机） |
HTTP_RATE_LIMIT_PER_MINUTE |
否 | 60 |
每客户端 IP 每分钟最大请求数（写接口限流；0 关闭） |
MCP_SSE_PORT |
否 | 5001 |
MCP SSE 模式端口 |
开发与质量门禁
安装开发依赖后即可使用工具链：pip install -e ".[dev]"
| 工具 | 命令 | 作用 |
|---|---|---|
| pytest + pytest-cov | pytest |
全量测试 + 覆盖率报告（当前 --cov-fail-under=65 防回归门槛；ECC 目标 80%，缺口为 web_ui 回调 / main.py HTTP 边角，属后续回归计划） |
| ruff | ruff check src tests |
代码规范（lint + import 排序） |
| bandit | bandit -r src -ll |
安全静态扫描（仅中高危） |
以上三步已接入 GitHub Actions CI（.github/workflows/ci.yml），push / PR 时自动执行。
项目结构
geo-content-optimizer/
├── config/
│ └── agent_llm_config.json # Agent System Prompt + 模型配置
├── scripts/ # 运行脚本 (Linux/macOS)
├── src/
│ ├── __main__.py # python -m src 入口
│ ├── main.py # FastAPI HTTP 服务
│ ├── cli.py # CLI 交互模式
│ ├── mcp_server.py # MCP Server（接入Claude等AI工具）
│ ├── web_ui.py # Streamlit Web UI
│ ├── agents/
│ │ └── agent.py # Agent 构建（LangGraph）+ AgentState
│ ├── tools/
│ │ ├── geo_pipeline.py # 核心：4阶段流水线 + 智能分块 + Word导出
│ │ └── web_search.py # 联网检索（Tavily/Bing/DuckDuckGo）
│ ├── utils/
│ │ ├── file/
│ │ │ └── file.py # 文件解析（PDF/Word/Excel/PPT/TXT）
│ │ └── docx_export.py # Markdown → Word 文档转换
│ └── storage/
│ ├── memory/ # 内存持久化（默认）
│ ├── database/ # PostgreSQL（可选）
│ └── s3/ # S3 存储（可选）
├── run.bat # Windows 一键启动
├── setup.bat # Windows 一键安装
├── dsh-plugin/ # DSH 插件包（dsh plugin add 安装；含 preset/ 副本）
├── docs/ # 文档：dsh-integration.md（集成施工）/ dsh-validation.md（验证流程）
├── scripts/ # 含 sync_dsh_instance.ps1（DSH 工作实例同步）
├── .env.example # 环境变量模板
├── pyproject.toml # 依赖配置
├── LICENSE # MIT License
└── README.md
技术栈
| 层级 | 技术 |
|---|---|
| Agent 框架 | LangChain + LangGraph (create_react_agent) |
| LLM 调用 | ChatOpenAI（兼容所有 OpenAI API） |
| Web API | FastAPI + Uvicorn |
| Web UI | Streamlit（可选） |
| MCP 协议 | FastMCP（接入 Claude 等 AI 工具） |
| CLI | argparse + asyncio |
| 重试机制 | tenacity（指数退避 + JSON 自修复） |
| 持久化 | PostgreSQL（可选）+ S3（可选） |
Contributing
欢迎贡献！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交修改 (
git commit -m 'Add amazing feature') - 推送分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
开发环境设置：
python -m venv .venv
pip install -e ".[all]"
pip install pytest pytest-asyncio
Changelog
查看 CHANGELOG.md 了解完整版本变更记录。
License
MIT License — 自由使用、修改和分发。
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…