> 本文记录我在 **WorkBuddy**（一款生产力级 AI Agent 工具，与 Qoder、TRAE Work 同类）里跑通 `local-text-insight` skill 的完整路径，所有截图都来自真实交互。文章里出现的版本号、字符数、阅读时长，都是本机实测数据，不是纸面推导。
>
---
## 〇、先交代背景：为什么是 skill
过去一年，AI Agent 工具的能力边界一直靠两样东西撑着：**大模型本身**和**function calling（工具调用）**。但工具调用有个老问题——它高度依赖"宿主怎么定义工具"，换个框架就得重写，A 家的 MCP 到了 B 家未必兼容。

**Skill 是想解决"可移植性"这件事。** 一个 skill 往往被设计成一个自包含的目录：一个入口脚本、一个说明文档、若干配置，Agent 只要"能跑这个脚本、能解析 stdout"，就能用。它不关心宿主是 WorkBuddy 还是 Qoder 还是 TRAE Work，也不关心模型是哪个。

`local-text-insight`（ModelScope `Neolnfra/local-text-insight`，Apache-2.0）就是这么一个典型的 skill：**核心引擎只用 Python 标准库、零第三方依赖**，干的是"文本提纯"这件事——把又长又脏的网页/长文/markdown 变成干净正文、大纲树、摘要、关键词、阅读时长。

我挑它试手，是因为它身上正好叠着几个我想验证的问题：

1. 一个**零依赖、纯本地**的 skill，在生产力级 Agent 里到底能不能闭环？
2. skill 的每一项能力（净化、大纲、摘要、关键词……）**在真实、带噪声的输入上，表现到底如何？**
3. 当 skill 的能力有边界（不读 PDF、不跑 JS），**Agent 是硬撑还是能优雅补齐？**

下面就是完整记录。

---

## 一、skill 架构剖析：它为什么能"零依赖可移植"
动手之前，我先把它拆开看了一眼。这个 skill 的文件结构不复杂，但设计上有几处值得记：

```plain
local-text-insight/
├── SKILL.md            # 路由说明（Agent 按 description 匹配）
├── info.json           # 运行时配置（venv / python / 依赖 / 入口）
├── meta.json           # 展示元数据（名称 / 图标 / use_cases）
├── config.json         # 可选配置（摘要句数 / 关键词数 / use_llm_summary）
├── requirements.txt    # 核心为空；可选 openvino-genai / optimum / transformers
├── scripts/
│   ├── run.ps1 / run.sh  # 固定入口（Windows / Linux·macOS）
│   ├── run.py            # 统一 CLI（stdin JSON / --text / --file / --url / --dir）
│   ├── engine.py         # 核心引擎（纯标准库）
│   └── llm_backend.py    # 可选 LLM 生成式摘要（懒加载，自动降级）
└── tests/                # 自测 + 全功能测试
```

**架构是分层的**——`health` 命令直接把它说破了：

```plain
adapter (run.py)
  -> core-engine (scripts/engine.py, stdlib)
  -> optional llm-bridge (subprocess, isolated venv)
```

这套设计有几个明确意图：

| 设计 | 目的 |
| --- | --- |
| **单一固定入口** | 宿主永远只调 `run.ps1`/`run.sh`/`run.py`，内部逻辑怎么变都不影响调用方 |
| **统一 JSON 协议** | 输入一个 JSON → 输出一个 JSON，进度走 stderr 不污染结果，任何宿主解析 stdout 即可 |
| **core 零依赖** | `engine.py` 只用标准库，任何装了 Python 3.8+ 的机器 `pip install` 都不用跑 |
| **LLM 通道懒加载** | `llm_backend.py` 只在 `use_llm_summary=true` 时才被 import；没有模型就自动降级回抽取式摘要 |


这套设计把"确定性的规则能力"和"不确定的生成能力"解耦了——前者是 `engine.py`（零成本、可复现、毫秒级），后者是可选挂载的 LLM（重、慢、不可复现但能"理解"）。

---

## 二、skill 功能详解
这个 skill 的能力可以概括为一句话：**把"又长又脏"的文本，变成"结构干净、要点清晰"的产物**。下面逐一拆解它的功能（每项都对应一条真实命令）。

### 2.1 HTML 净化 + 正文主体抽取
**做什么**：喂进一段网页 HTML，输出干净正文。分两层——先删噪声，再抽正文。

+ **删噪声**：整段移除 `script / style / noscript / svg / iframe / form / header / nav / footer / aside / figure / canvas` 等标签，同时按 `class`/`id` 识别广告块（`ad` / `advert` / `banner` / `sponsor` / `sidebar` / `share` / `comment` 等）。
+ **抽正文**：用 `HTMLParser` 构建 DOM 树，给每个节点算文本密度分（`text - link*8`），定位"文本最密、链接最稀"的内容块，丢弃导航/侧栏/页脚这些样板。

```bash
python scripts/run.py --url https://example.com/article.html
# 或本地 HTML 文件
python scripts/run.py --file 页面.html
```

**输出**：`clean_text`（净化后正文）+ `title`（从 `<title>` 提取）。

### 2.2 结构化大纲（标题树）
**做什么**：识别 markdown `# ~ ######` 标题，构建一棵有层级的标题树。每个节点还挂两个额外信息：

+ `lead`：该章节的"段首要点"（第一句，用于快速预览）
+ `char_range`：该章节在正文里的字符偏移（用于"从大纲跳回原文"）

```json
"outline": [
  {"level": 1, "title": "第一章", "lead": "首句要点…",
   "children": [
     {"level": 2, "title": "1.1 小节", "lead": "…", "children": []}
   ]}
]
```

### 2.3 抽取式摘要（TextRank）
**做什么**：基于 TextRank 图算法，从原文里挑出最"代表全文"的若干句（默认 5 句）。它的价值在于**每一句都是原文原句，不会胡编**。

+ 句子相似度用余弦相似度（基于 char n-gram / 词频向量）
+ 加了**位置加权**（开头/结尾句更重）、**标题加权**（含 `#` 的句子更重）、**长度惩罚**（过长/过短句降权）
+ 每句摘要带 `summary_spans`（原文句序号 + 字符偏移），可做"点摘要跳原文"

```bash
python scripts/run.py --file 文章.txt --options '{"max_summary_sentences":5}'
```

### 2.4 关键词提取
**做什么**：抽 top-N 关键词（默认 8 个）。

+ **英文**：词频统计 + 停用词过滤 + 二元词组（bigram）
+ **中文**：因为零依赖不能引 jieba，用 char n-gram（2/3/4 字）+ 停用词 + **标题加权** + **单字位移并查集归并**（把"本地文本/地文本智/文本智能…"这类相邻碎片收成一个代表词）+ **子串去重**

```bash
python scripts/run.py --file 文章.txt --options '{"top_keywords":8}'
```

### 2.5 语言自动检测
**做什么**：在**清洗后的正文**上检测语言（不是原始 HTML——避免标签稀释中文比例误判成英文）。中文 CJK 字符占比 > 0.15 判 `zh`，否则 `en`。

### 2.6 阅读时长估算
**做什么**：按字符/词数估算阅读分钟数——中文按 300 字/分钟，英文按 200 词/分钟。输出 `reading_time_min`。

### 2.7 批量目录处理
**做什么**：一次提纯整个文件夹里的所有 `.txt / .md / .html / .htm`，stdout 输出一个 JSON 数组；加 `--output-dir` 还能把每个文件的结果写成 `<原名>.json`。

```bash
python scripts/run.py --dir ./我的文章集 --output-dir ./提纯结果
```

### 2.8 可选 LLM 生成式摘要（OpenVINO）
**做什么**：默认是抽取式摘要（零依赖）。如果你在 AI PC 上装了 OpenVINO 模型，可以开启生成式摘要——`llm_backend.py` 按 `openvino-genai`（首选）→ `optimum-intel` 顺序尝试真实加载模型生成摘要；**没有模型就自动降级**回抽取式，`summary_mode` 字段标记 `extractive` / `abstractive` / `extractive-fallback` 三种状态，行为契约不变。

```bash
pip install openvino-genai
export OPEN_VINO_MODEL_PATH=/path/to/qwen-ov-ir
echo '{"command":"process","text":"长文…","options":{"use_llm_summary":true}}' | python scripts/run.py --json
```

### 2.9 统一的输出契约
无论走哪条路，最终都向 stdout 输出**一个 JSON**：

```json
{
  "language": "zh",
  "title": "标题",
  "clean_text": "净化后的正文",
  "outline": [/* 标题树 */],
  "summary": ["摘要句1", "摘要句2"],
  "summary_spans": [{"text":"…","sentence_index":3,"char_start":120,"char_end":168}],
  "keywords": ["关键词1", "关键词2"],
  "keywords_detail": [{"term":"…","count":4,"score":4,"first_pos":11}],
  "reading_time_min": 3,
  "char_count": 1234,
  "summary_mode": "extractive"
}
```

加 `--format markdown` 还能直接输出一份「大纲 + 摘要 + 关键词」的人读报告，贴进文档就能用。

---

## 三、实践路径（5 步，截图按序对应）
### Step 1 · 安装与冷启动验证
第一件事：让 WorkBuddy 去 ModelScope 把 skill 拉下来、装上、跑一次健康检查。  
![image](https://developer.qcloudimg.com/http-save/yehe-11941136/bbfcbb58731abd23a7136ad600304830.png)

这一步真正的价值在于：**一个 skill 装上之后，第一件事不是"开始用"，而是"跑一次 health 自检"**。它验证了 Python 环境、入口脚本、引擎能正常启动，把环境问题挡在业务之前。

### Step 2 · 摸清能力边界
第二步：让模型把 skill "它是干嘛的"摊开给我看，确认能力清单跟我的使用场景对得上。  
![image](https://developer.qcloudimg.com/http-save/yehe-11941136/14962efe788ea603e47afacc54dce033.png)

模型返回了 8 项能力表格——HTML 净化 / 正文主体抽取 / 结构化大纲 / 抽取式摘要 / 关键词提取 / 语言检测 / 阅读时长估算 / 可选 LLM 摘要。

### Step 3 · HTML 净化：完整链路打通
第三步我拿了一个真实场景来验：**ModelScope 这个 skill 详情页本身**，让 skill 帮它做 HTML 净化。

这一关暴露了一个真实边界——skill 自带的 `--url` 是用 Python 标准库 `urllib` 抓的，**不跑 JS**，所以 ModelScope 这种 SPA（正文在 JS 渲染里）抓不到，只拿到 `<title>`：

```plain
{"language":"zh","title":"Skill 详情 - 开发工具 - local-text-insight",
 "clean_text":"Skill 详情 - 开发工具 - local-text-insight", ...}
```

为了让"HTML 净化"真的发生，我搭了一条双链路：

> 1. **Jina Reader**（`curl -H "X-Return-Format: html" https://r.jina.ai/<URL>`）拿渲染后完整 HTML（这次 5.2MB）
> 2. 把 HTML 存成本地 `.html`，喂给 `python scripts/run.py --file <它>`
>
![image](https://developer.qcloudimg.com/http-save/yehe-11941136/95350949c49a5c6d40df4f9d3c5d2adc.png)

完整链路跑通后，WorkBuddy 回复"这次真正完成了 HTML 净化，拿到了完整正文。
![image](https://developer.qcloudimg.com/http-save/yehe-11941136/e85eaaff66b772df537bec4cc68a2e37.png)
这是上一条导出的 markdown 报告开头——大纲树"Local Text Insight → 它解决什么 / 何时使用 / 使用方法 / 输入参数 / 为什么可移植 / 目录结构 / 版本记录 / 许可证"完整还原了文档结构。

**这一步是全文最重要的一个转折**：它证明"skill 的能力有边界"不代表"任务做不成"。边界之外找工具补齐，而不是让 skill 或模型硬扛。**

### Step 4 · Markdown 格式文章提取
接下来用一个真实项目里的小文章——`Thinkphp 注入漏洞.md`（技术文章，含 10 张截图引用）验 markdown 提取。  
![image](https://developer.qcloudimg.com/http-save/yehe-11941136/e85eaaff66b772df537bec4cc68a2e37.png)
_WorkBuddy 20s 完成，输出：_`zh / 1202 字符 / 1 分钟阅读 / 标题"漏洞影响"`_，大纲三层"漏洞影响 / 漏洞分析 / 漏洞复现"，5 句摘要——"漏洞源于框架的链式查询机制中对排序条件的直接拼接"。_

### Step 5 · PDF 格式文档提取
最后压轴的是 PDF——`实验二 Web 漏洞检测.pdf`，一份 14 页、2MB 的实验指导文档（Web 漏洞扫描实操）。
![image](https://developer.qcloudimg.com/http-save/yehe-11941136/0cbca5de83a6b7f0de3aa2c0bc2b2e1e.png)
关键说明——"skill 本身不直接支持 PDF（只支持 txt/md/html），我先用 pypdf 把 PDF 转成文本（14 页），再喂给 skill 做结构化提取"。*
![image](https://developer.qcloudimg.com/http-save/yehe-11941136/f2d47a13eda5a374b998091c86b34d36.png)
识别出文档真实章节结构——"实验二 Web 漏洞检测 → 学习目标 / 项目导入 / 任务 1 AppScan（→ 情境描述/任务要求/知识准备/任务实施）/ 任务 2 OWASP ZAP（同上）"。摘要 5 句覆盖了"实验目标→nmap/AppScan→OWASP ZAP→导出报告"的主线。关键词："扫描、漏洞扫描、扫描结果、漏洞检测、安全评估、功能"。*

---

## 四、总结
回顾这一整轮实践，跑通了一个"零依赖、纯本地"的文本提纯 skill，从安装、摸清能力，到 HTML 净化、Markdown 提取、PDF 提取，一路闭环。几个关键结论：

1. **"零依赖可移植"不是口号，是能落地的设计。** skill 靠"单一入口脚本 + 一个 JSON 出 stdout"的契约，做到了宿主无关能用，换 Qoder、TRAE Work 或任何脚本一样能调。这是 skill 这类"可移植能力单元"相对传统工具调用的核心优势。
2. **能力边界靠"组合"补齐，而不是硬扛。** skill 不跑 JS，就用 Jina 先把 SPA 渲染掉；skill 不读 PDF，就用 pypdf 先转文本。每个环节交给最擅长的工具，Agent 负责调度和整合——这条"边界之外找工具"的思路，比"一个模型包打天下"务实得多。
3. **真实输入才能暴露真实问题。** markdown 图片语法被当成正文、JS 渲染页抓不到正文，这些都是干净样例永远测不出来的坑。实践的价值，恰恰在于用带噪声的真实内容去检验一个工具。

一句话：**在生产力级 AI Agent 里，skill 是"可移植的能力单元"，Agent 是调度者，专用小工具是边界补充——三者组合，才是一个能落地的 Hybrid AI 工作流。**



---


本文记录我在 WorkBuddy（一款生产力级 AI Agent 工具，与 Qoder、TRAE Work 同类）里跑通 local-text-insight skill 的完整路径，所有截图都来自真实交互。文章里出现的版本号、字符数、阅读时长，都是本机实测数据，不是纸面推导。

WorkBuddy 平台下生产力级 Agent 本地文本分析落地指南

人工智能

开发工具

编程语言

在WorkBuddy中成功跑通local-text-insight技能，验证零依赖本地文本提纯的完整闭环。实测HTML净化、Markdown提取、PDF转换，展示能力边界与工具组合补齐策略，确认skill可移植性设计有效。

漏洞扫描

代码解释

WorkBuddy 

Windows

路由

Python

Linux

Agent

JSON

WorkBuddy企业版限时双倍 Credits 活动

workbuddy

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

WorkBuddy 平台下生产力级 Agent 本地文本分析落地指南-腾讯云开发者社区-腾讯云

WorkBuddy 平台下生产力级 Agent 本地文本分析落地指南

WorkBuddy 平台下生产力级 Agent 本地文本分析落地指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐