GEO Content Optimizer

输入企业文献资料 → 自动产出适配豆包/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 分钟）。

# 安装插件（与 profiles/web/cordis.patch.yml 直插行二选一）
dsh plugin --profile web add C:/Users/Lenovo/Desktop/geo-content-optimizer/dsh-plugin
dsh web restart   # 重启后新会话工具目录出现 mcp__geo__*

配套的「GEO 创作」agent preset 备份在 dsh-plugin/preset/；工作实例与实时工作版的边界、源码同步与验收见 docs/dsh-integration.md 与 docs/dsh-validation.md。 API Key 由工作实例项目目录下的 .env 提供，也可用 GEO_PYTHON / GEO_PROJECT_ROOT 环境变量覆盖插件默认路径。

用户特殊要求与双闸门（可选）

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 — 自由使用、修改和分发。

GEO Content Optimizer

English | 中文

输入企业文献资料 → 自动产出适配豆包/Kimi/DeepSeek/通义千问/GPT 等大模型向量库收录的高质量原创文章，并消除 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 原生工具）

# 安装插件（与 profiles/web/cordis.patch.yml 直插行二选一）
dsh plugin --profile web add C:/Users/Lenovo/Desktop/geo-content-optimizer/dsh-plugin
dsh web restart   # 重启后新会话工具目录出现 mcp__geo__*

用户特殊要求与双闸门（可选）

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）。

结构化输出降级说明

常驻部署与自愈（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 秒后自动拉起）。

环境变量

变量	必填	默认值	说明
`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 — 自由使用、修改和分发。

geo-content-optimizer

GEO Content Optimizer

功能特色

核心能力

6种使用方式

架构

快速开始

1. 安装

2. 配置 API Key

3. 运行

方式一：CLI 交互模式

方式二：命令行直接处理

方式三：Web UI

方式四：HTTP API 服务

方式五：MCP Server（接入 Claude 等 AI 工具）

方式六：DSH 插件（DeepSeek Harness 原生工具）

用户特殊要求与双闸门（可选）

字数自动校准（R3）

运行时长提示

结构化输出降级说明

常驻部署与自愈（R7 B6）

环境变量

开发与质量门禁

项目结构

技术栈

Contributing

Changelog

License

Community comments

geo-content-optimizer

GEO Content Optimizer

功能特色

核心能力

6种使用方式

架构

快速开始

1. 安装

2. 配置 API Key

3. 运行

方式一：CLI 交互模式

方式二：命令行直接处理

方式三：Web UI

方式四：HTTP API 服务

方式五：MCP Server（接入 Claude 等 AI 工具）

方式六：DSH 插件（DeepSeek Harness 原生工具）

用户特殊要求与双闸门（可选）

字数自动校准（R3）

运行时长提示

结构化输出降级说明

常驻部署与自愈（R7 B6）

环境变量

开发与质量门禁

项目结构

技术栈

Contributing

Changelog

License

Community comments