---

jargon-engine 是什么？

新人进一个行业，最懵的就是满屏黑话。jargon-engine 把「赋能业务、形成闭环、颗粒度对齐」翻译成人话——既给正经解释，也给带梗的搞笑版，还能整句重写。

它基于 AC 自动机 实现毫秒级匹配，内置 10,388 条去重词条，覆盖互联网 + AI 全行业 12 大分类。提供 Python SDK / REST API / CLI 三种接入方式，可独立部署，也可作为路由嵌入任意 FastAPI 项目。

from jargon_engine import Engine

engine = Engine()
result = engine.translate("这个方案要赋能业务，形成闭环")
print(result.translated)
# 这个写满套路的PDF要给你装个外挂，让你干得更溜。，绕一圈回来，接头了，没断线。

---

特性

能力	说明
🚀 毫秒级检索	AC 自动机一次扫描匹配全部词条，万级词库 translate 仅 4ms
🧠 万级词库	10,388 条去重词条，12 大行业，生产管线持续扩充
😂 三种风格	funny 搞笑人话版 / plain 正经版 / explain 带例句详解
🔌 三种接入	Python SDK / REST API / CLI，任选其一
🧩 可嵌入	FastAPI 路由可 include_router 进任意现有项目
🛡️ API 健壮	Pydantic 校验、CORS、API Key 鉴权、统一错误处理、404/400/422
⚡ 高性能	lookup O(1) 字典索引、search 预计算缓存
📦 数据分离	引擎运行时与词库生产管线物理隔离，互不依赖

---

快速开始

安装

pip install jargon-engine            # SDK + CLI
pip install "jargon-engine[api]"     # 加上 REST API（FastAPI + uvicorn）

Python SDK

from jargon_engine import Engine

engine = Engine()
result = engine.translate("要赋能业务，形成闭环，注意颗粒度")

print(result.translated)   # 翻译后的人话
print(result.hits)         # 命中词条详情
print(result.elapsed_ms)   # 耗时（毫秒）

REST API

jargon-engine serve --port 7861

curl -X POST http://localhost:7861/api/jargon/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"赋能业务形成闭环","style":"funny"}'

CLI

jargon-engine translate "赋能业务形成闭环"
jargon-engine lookup "赋能"
jargon-engine stats
jargon-engine serve --port 7861

---

REST API

端点总览

方法	路径	功能	状态码
GET	/api/health	健康检查（免鉴权）	200
GET	/api/jargon/translate/health	子路由健康	200
POST	/api/jargon/translate	整段黑话 → 人话	200 / 400 / 422
GET	/api/jargon/terms/{word}	单个词条详情	200 / 404
GET	/api/jargon/search	模糊搜索词库	200 / 422
GET	/api/jargon/stats	词库统计	200

鉴权

设置环境变量 JARGON_API_KEY 后，所有 /api/jargon/* 端点需携带请求头：

X-API-Key: <你的key>
# 或
Authorization: Bearer <你的key>

未设置该变量时不启用鉴权（开发模式）。/api/health 始终免鉴权，供负载均衡探活。

POST /api/jargon/translate

请求体：

字段	类型	必填	默认	说明
text	string	是	-	待翻译文本，长度 ≥ 1
style	string	否	funny	funny / plain / explain
industry	string	否	null	限定行业；支持别名 developer→tech
llm_polish	bool	否	false	是否 LLM 润色（需注入润色器）
include_untracked	bool	否	false	是否返回未收录候选词

响应（毫秒级）：

{
  "ok": true,
  "original": "这个方案要赋能业务，形成闭环",
  "translated": "这个写满套路的PDF要给你装个外挂，让你干得更溜",
  "hits": [
    {
      "word": "赋能",
      "plain": "为个人或组织提供能力或条件",
      "funny": "给你装个外挂，让你干得更溜",
      "industry": "internet",
      "example": "我们要赋能一线团队 → 给他们工具和权限，让他们自己飞",
      "aliases": ["加持", "赋能业务", "持续赋能"]
    }
  ],
  "untracked": [],
  "stats": {
    "total_terms": 10388,
    "matched": 2,
    "elapsed_ms": 4.1,
    "mode": "dictionary"
  }
}

GET /api/jargon/search

curl "http://localhost:7861/api/jargon/search?q=agent&industry=ai&limit=10"

参数	类型	默认	约束
q	string	""	关键字
industry	string	-	合法行业
limit	int	20	1-100

错误处理

所有错误统一 JSON 格式：

状态码	场景	响应
400	industry 不存在	{"detail": "未知的 industry: xyz..."}
401	API Key 无效	{"detail": "无效或缺失的 API Key"}
404	词条不存在	{"detail": "词条 xxx 不存在"}
422	参数校验失败	{"detail": [{"loc": [...], "msg": "..."}]}
500	内部错误	{"ok": false, "error": "内部服务错误"}

---

Python SDK

from jargon_engine import Engine

engine = Engine()                          # 内置词库
engine = Engine(extra_tsv_dir="./my")      # 合并自定义词库

result = engine.translate(
    "赋能业务，形成闭环",
    style="funny",           # funny / plain / explain
    industry=None,           # None=全部，或指定行业
    llm_polish=False,
    include_untracked=False,
)

engine.lookup("赋能")         # O(1) 查词
engine.search("agent", industry="ai", limit=10)  # 模糊搜索
engine.stats()                # {"total": int, "by_industry": dict}

注入 LLM 润色器

def my_polish(text: str, hits: list) -> str | None:
    # 调用任意 LLM 返回润色整句；返回 None 则保留词典模式结果
    ...

engine = Engine(llm_polish=my_polish)
engine.translate("...", llm_polish=True)

---

词库

词库以 TSV 存储在 data/seed/，每行一条，按行业分文件。加词 = 加一行，PR 合并即可，git diff 友好。

字段	说明
word	主词
industry	所属行业 id
aliases	别名（分号分隔，匹配时一并命中）
plain	正经解释
funny	搞笑人话版
example	例句对比（黑话 → 人话）
weight	匹配权重（越大越优先）
source	来源（数据归属追溯）

行业分类

单一事实来源在 src/jargon_engine/industries.py，新增行业只需在此登记。

id	名称	id	名称
internet	互联网通用	marketing	市场与增长
product	产品	operations	运营
tech	技术	design	设计与体验
ai	AI 与大模型	finance	商业与投融资
data	数据	workplace	职场与管理
hr	人力资源	ecommerce	电商与零售

别名：developer → tech。

---

架构

┌─────────────────────────────────────────────┐
│            API 层（FastAPI）                 │
│  app.py · deps.py · cli.py                  │
│  Pydantic 校验 · CORS · API Key · 错误兜底  │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│            Engine（引擎入口）                │
│  加载词库 → 构建索引 → 翻译/查词/搜索        │
│  O(1) lookup · 预计算 search · 行业 resolve │
└──────┬──────────────────┬───────────────────┘
       │                  │
┌──────▼──────┐  ┌────────▼────────┐
│ Translator  │  │    Matcher      │
│ 词典命中→   │◄─│ AC 自动机       │
│ 语境重组→   │  │ 最长优先·fail链 │
│ LLM 润色    │  │ 行业过滤·去重叠 │
└─────────────┘  └─────────────────┘
       │                  │
┌──────▼──────────────────▼───────────────────┐
│        Store · Models · Industries          │
│  TSV 加载 · merge 合并 · Pydantic v2        │
└─────────────────────────────────────────────┘

词库生产管线（独立组件，与引擎运行时隔离）：
┌─────────────────────────────────────────────┐
│            tools/pipeline/                  │
│  expand_wordlists · llm_generate · merge    │
│  validate · import/*（外部数据源）          │
└─────────────────────────────────────────────┘

关键设计：

• 引擎与生产管线分离：src/jargon_engine/ 是运行时（打进 wheel），tools/pipeline/ 是离线词库生产（不打包），两者无共享执行环境
• 启动时建索引：加载词库 + AC 自动机 + dict 索引 + search 缓存，一次构建反复用
• Engine 单例：lru_cache 避免每请求重建
• 无状态抓取：生产管线不生成/存储完成状态指标，仅读已有输出续跑

---

词库生产管线

万级词库靠管线生产，位于 tools/pipeline/（与引擎运行时物理隔离）：

合并开源词表（MIT/CC BY-SA 来源）
    ↓
LLM 扩充行业词单（expand_wordlists.py）
    ↓
LLM 批量生成释义（llm_generate.py：funny/plain/example/aliases）
    ↓
合并去重（merge.py）+ 校验（validate.py）
    ↓
人工审校 + 社区共建（PR 持续加词）

python tools/pipeline/validate.py data/seed/*.tsv
python tools/pipeline/merge.py --sources a.tsv b.tsv --out merged.tsv
python tools/pipeline/expand_wordlists.py \
  --wordlist tools/pipeline/import/wordlists/ai.txt --industry ai --target 900 \
  --out tools/pipeline/import/wordlists/ai.txt
python tools/pipeline/llm_generate.py \
  --wordlist tools/pipeline/import/wordlists/ai.txt --industry ai \
  --out data/seed/ai_generated.tsv

需配置 DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL / DEEPSEEK_MODEL。外部数据来源见 THIRD_PARTY_NOTICES.md。

---

配置

变量	默认	说明
JARGON_API_KEY	-	API Key 鉴权，未设置则不启用
JARGON_CORS_ORIGINS	*	允许的跨域来源，逗号分隔；生产请收紧
JARGON_EXTRA_TSV_DIR	-	额外 TSV 词库目录，合并到内置词库
DEEPSEEK_API_KEY	-	词库生产管线用，引擎运行不需要

---

部署

独立部署

pip install "jargon-engine[api]"
JARGON_API_KEY=your-secret jargon-engine serve --host 0.0.0.0 --port 7861

嵌入现有 FastAPI 项目

from fastapi import FastAPI
from jargon_engine.api.app import create_router

app = FastAPI()
app.include_router(create_router(), prefix="/api/jargon")

生产建议

• uvicorn jargon_engine.api.app:create_app --factory --workers 4 多进程
• Nginx 反向代理做 TLS、限流、缓存
• 收紧 JARGON_CORS_ORIGINS 为实际前端域名
• 启用 JARGON_API_KEY 防止 llm_polish 被滥用产生 LLM 费用

---

开发

pip install -e ".[dev,api]"
pytest                 # 46 用例
ruff check .           # lint
jargon-engine serve --port 7861   # 开发服务

---

路线图

里程碑	状态	内容
v0.1 基础引擎	✅ 已发布	AC 自动机匹配、词典翻译、REST API、CLI、12 大行业
v1.0 工程化	✅ 已发布	API 规范化（Pydantic/CORS/鉴权/错误处理）、O(1) 索引、测试覆盖、CI/CD、引擎与生产管线分离
v1.1 生态	🚧 进行中	PyPI 发布、Docker 部署、前端接入、更多行业（法律/教育/医疗）
v2.0 国际化	📋 规划中	英文社区支持、中英双向翻译、多语言释义
v2.x 智能化	📋 规划中	LLM 润色内置、分词改进、SQLite FTS5 倒排、词条贡献后台

近期 TODO

• 补 translator LLM 润色分支与 CLI 的集成测试
• 加 pre-commit hook（ruff + pytest）
• Dockerfile 与 docker-compose 示例
• 词库去重审计：跨文件同义词统一 aliases

---

贡献

1. Fork 仓库并拉取分支
2. 加词：在 data/seed/<行业>.tsv 追加一行，跑 python tools/pipeline/validate.py data/seed/*.tsv 校验
3. 加行业：在 src/jargon_engine/industries.py 的 INDUSTRIES 登记
4. 改代码：跑 pytest 与 ruff check . 确保通过
5. 提 PR，描述变更与动机

词库贡献请确保 funny 版接地气、不生硬、不冒犯；外部数据来源请在 THIRD_PARTY_NOTICES.md 登记版权。

---

许可证

MIT — Copyright © 2026 renhuayixia

本项目基于 MIT 协议开源，允许任意改造、二次开发、商用，但必须在衍生项目中保留原作者版权声明与许可声明。词库数据来源及版权见 THIRD_PARTY_NOTICES.md。