Local Text Insight — 本地文本智能提纯器

一个零第三方依赖、纯离线、跨宿主可调用的本地文本智能 skill。

它解决什么

把"又长又脏"的文本（网页 HTML、markdown、粘贴的文章）变成结构干净、要点清晰的产物：干净正文 + 大纲树 + 摘要 + 关键词 + 阅读时长。全程本地、无需联网、无需模型权重，因此天然满足"数据不出机"的生产力与隐私诉求。

何时使用

用户要清洗/摘要/提炼文章、网页、长文、文档
用户要提取大纲、目录、要点、关键词、估算阅读时长
用户需要离线、隐私安全的文本处理（不把内容发给云端 LLM）
任何宿主（WorkBuddy / Qoder / TRAE Work / 自定义脚本）想本地调用文本智能能力

使用方法（三条命令即可上手）

前置条件：本机装好 Python 3.8+ 即可，无需 pip install 任何依赖（核心引擎只用标准库）。

方式一 · 健康检查（确认 skill 可用）

# 跨平台（推荐，任何装了 Python 的机器）
python scripts/run.py --command health
# Windows 专用入口
powershell -File scripts/run.ps1 --command health
# Linux / macOS 专用入口
bash scripts/run.sh --command health

返回：{"command":"health","version":"1.0.0","engine":"core (Python standard library, zero dependencies)","llm_abstractive_available":false,"architecture":"single-client"}

方式二 · 处理一个本地文本 / markdown 文件

python scripts/run.py --file 你的文章.txt
# 也可指定输出项
python scripts/run.py --file 你的文章.txt --options '{"max_summary_sentences":5,"top_keywords":8}'

方式三 · 通过管道传入 JSON（最适合被程序 / 宿主调用）

echo '{"command":"process","text":"你的长文……","options":{"max_summary_sentences":5,"top_keywords":8,"language":"auto"}}' | python scripts/run.py --json

以上三种方式最终都向 stdout 输出单个 JSON，进度/日志走 stderr，不会污染结果，任意程序解析 stdout 即可。

输入参数

| 参数 | 说明 | 默认值 | |---|---|---| | command | process（处理文本）/ health（自检）/ version（版本） | 必填 | | text | 待处理文本（与 file 二选一，file 优先） | — | | file | 本地文本 / markdown 文件路径 | — | | options.extract_summary | 是否抽取摘要 | true | | options.max_summary_sentences | 摘要句数 | 5 | | options.extract_keywords | 是否提取关键词 | true | | options.top_keywords | 关键词个数 | 8 | | options.language | auto / zh / en | auto | | options.use_llm_summary | true 时尝试 OpenVINO 生成式摘要（无模型自动降级） | false |

输出字段（单个 JSON）

{
  "language": "zh",
  "clean_text": "…净化后的正文…",
  "title": "标题",
  "outline": [{"level": 1, "title": "…", "children": []}],
  "summary": ["摘要句1", "摘要句2"],
  "keywords": ["关键词1", "关键词2"],
  "reading_time_min": 3,
  "char_count": 1234,
  "summary_mode": "extractive"
}

| 字段 | 含义 | |---|---| | language | 检测到的语言 zh / en | | clean_text | 净化后的正文 | | title | 从文本/HTML 提取的标题 | | outline | 结构化大纲（标题树，含 level/title/children） | | summary | 摘要句列表 | | keywords | 关键词列表 | | reading_time_min | 估算阅读时长（分钟） | | char_count | 字符数 | | summary_mode | extractive（当前默认）/ abstractive（启用 LLM 时） |

被宿主 / 程序调用的方式

WorkBuddy / Qoder / TRAE Work：宿主按本文件 description 自动匹配；触发后执行 scripts/run.ps1（Windows）或 scripts/run.sh（Linux/macOS），传入 JSON、读取 stdout 的 JSON。
自定义脚本（Python 示例）：

import subprocess, json
p = subprocess.run(
    ["python", "scripts/run.py", "--json"],
    input=json.dumps({"command": "process", "text": "你的长文……",
                      "options": {"max_summary_sentences": 5, "top_keywords": 8}}),
    capture_output=True, text=True
)
result = json.loads(p.stdout)   # stdout 是单个 JSON，直接解析
print(result["summary"], result["keywords"])

为什么可移植（核心设计）

零依赖核心：engine.py 只用 Python 标准库。任何装了 Python 3.8+ 的机器无需 pip install 即可运行。
单一固定入口：宿主永远只调 run.ps1/run.sh/run.py，内部逻辑变化不影响调用方。
统一 JSON 协议：输入一个 JSON，输出一个 JSON（进度走 stderr），任意宿主解析 stdout 即可。
架构选择 single-client：核心引擎瞬时启动、无重型模型常驻，按官方标准选 single-client 而非 client-server，更简单也更稳。
可选 LLM 升级通道：llm_backend.py 懒加载，仅在 use_llm_summary=true 且检测到 OpenVINO 时启用；否则自动降级为抽取式摘要，行为不变。

目录结构

local-text-insight/
├── SKILL.md            # 路由说明（宿主按 description 匹配）——根目录唯一的 md 文件
├── info.json           # 运行时配置（venv / python / 依赖 / 入口）
├── meta.json           # 展示元数据（名称 / 图标 / use_cases）
├── requirements.txt    # 核心为空；可选 openvino/modelscope/numpy
├── docs/
│   ├── README.md       # 跨环境兼容说明与宿主调用示例
│   └── PUBLISH-FORM.md # 魔搭发布表单填写参考
├── scripts/
│   ├── run.ps1         # Windows 固定入口
│   ├── run.sh          # Linux/macOS 入口
│   ├── run.py          # 统一 CLI（stdin JSON / --text / --file / --command）
│   ├── engine.py       # 核心引擎（纯标准库）
│   └── llm_backend.py  # 可选 LLM 抽象式摘要（懒加载、自动降级）
└── tests/
    ├── test_sample.txt # 样例输入
    ├── test_run.py     # 引擎自测
    └── test.ps1        # 端到端：调用 run.ps1 校验退出码与 JSON