# python 3.12.1 Date：2023年12月8日
是最新的维护版本，包含自 3.12.0 以来的 400 多个错误修复、构建改进和文档[更改](https://docs.python.org/3.12/contents.html)。

## 1. typing的优化：
```shell
from typing import Iterable, TypeVar
T = TypeVar('T')

def max[T](args: Iterable[T]) -> T:
    ...
class list[T]:
    def __getitem__(self, index: int, /) -> T:
        ...

    def append(self, item: T) -> None:
       ...
# py_3.10是用显示声明类型别名。Point: TypeAlias = tuple[float, float]
# py_3.9以及下的版本，是用直接赋值定义类型别名，Point = Tuple[float, float]
type Point = tuple[float, float]
# type 语句专门用于声明类型别名，让代码里类型定义的意图更加清晰明确。
type Point[T] = tuple[T, T]

```
### TypeVarTuple 和ParamSpec
```shell
type IntFunc[**P] = Callable[P, int]  # ParamSpec
type LabeledTuple[*Ts] = tuple[str, *Ts]  # TypeVarTuple
type HashableSequence[T: Hashable] = Sequence[T]  # TypeVar with bound
type IntOrStrSequence[T: (int, str)] = Sequence[T]  # TypeVar with constraints
```
以下将结合 Python 的类型注解和类型变量相关知识，对你给出的四个类型别名定义进行详细解释。这些定义主要使用了 Python 的类型系统新特性，如 `ParamSpec`、`TypeVarTuple`、`TypeVar` 等，并且这些特性大多从 Python 3.10 及以上版本开始引入，部分更高级特性如 `TypeVarTuple` 需 Python 3.11 及以上版本支持。

#### 1. `type IntFunc[**P] = Callable[P, int]  # ParamSpec`
```python
from typing import Callable, ParamSpec

P = ParamSpec('P')
type IntFunc[**P] = Callable[P, int]

# 示例函数
def add(a: int, b: int) -> int:
    return a + b

# 使用类型别名注解
func: IntFunc[[int, int]] = add
```
- **含义**：此类型别名 `IntFunc` 借助 `ParamSpec`（`P`）来表示一个可调用对象（函数），该对象可以接受任意数量和类型的参数（`P` 代表参数规范），但返回值类型必须是 `int`。
- **用途**：当你需要定义一系列函数，它们的返回值都是整数，不过参数类型和数量不确定时，就可以使用这个类型别名进行类型注解。

#### 2. `type LabeledTuple[*Ts] = tuple[str, *Ts]  # TypeVarTuple`
```python
from typing import TypeVarTuple

Ts = TypeVarTuple('Ts')
type LabeledTuple[*Ts] = tuple[str, *Ts]

# 示例元组
labeled_int_tuple: LabeledTuple[int] = ('label', 1)
labeled_int_str_tuple: LabeledTuple[int, str] = ('label', 1, 'value')
```
- **含义**：`LabeledTuple` 是一个泛型类型别名，利用 `TypeVarTuple`（`Ts`）表示它可以包含任意数量和类型的元素。这个元组的第一个元素类型固定为 `str`，后续元素的类型由 `Ts` 决定。
- **用途**：当你需要创建带有标签的元组，且标签之后的元素数量和类型不固定时，可使用此类型别名。

#### 3. `type HashableSequence[T: Hashable] = Sequence[T]  # TypeVar with bound`
```python
from collections.abc import Sequence
from typing import TypeVar
from collections.abc import Hashable

T = TypeVar('T', bound=Hashable)
type HashableSequence[T: Hashable] = Sequence[T]

# 示例序列
hashable_list: HashableSequence[int] = [1, 2, 3]
```
- **含义**：`HashableSequence` 是一个泛型类型别名，`TypeVar`（`T`）被约束为 `Hashable` 类型，意味着 `T` 必须是可哈希的类型。该类型别名表示一个序列，序列中的元素类型为可哈希的 `T`。
- **用途**：当你需要处理包含可哈希元素的序列时，可使用此类型别名，确保序列中的元素都能用于需要可哈希对象的场景，如作为字典的键。

#### 4. `type IntOrStrSequence[T: (int, str)] = Sequence[T]`
```python
from collections.abc import Sequence
from typing import TypeVar

T = TypeVar('T', int, str)
type IntOrStrSequence[T: (int, str)] = Sequence[T]

# 示例序列
int_sequence: IntOrStrSequence[int] = [1, 2, 3]
str_sequence: IntOrStrSequence[str] = ['a', 'b', 'c']
```
- **含义**：`IntOrStrSequence` 是一个泛型类型别名，`TypeVar`（`T`）被限制为只能是 `int` 或者 `str` 类型。该类型别名表示一个序列，序列中的元素类型只能是整数或者字符串。
- **用途**：当你需要处理只包含整数或字符串元素的序列时，可使用此类型别名，增强代码的类型安全性和可读性。

这些类型别名定义借助 Python 的类型系统，能够让代码的类型注解更加灵活和精确，提高代码的可读性和可维护性。 

## 2. 更灵活的f字符串解析
主要新功能：
- [更灵活的 f 字符串解析](https://docs.python.org/3.12/whatsnew/3.12.html#pep-701-syntactic-formalization-of-f-strings)，允许许多以前不允许的事情 （PEP 701）。
    
    - 引号重用：
    ```python
    >>> songs = ['Take me back to Eden', 'Alkaline', 'Ascensionism']
    >>> f"This is the playlist: {", ".join(songs)}"
    'This is the playlist: Take me back to Eden, Alkaline, Ascensionism'
    ```
    - 无限制的嵌套
    ```python
    >>> f"""{f'''{f'{f"{1+1}"}'}'''}"""
    '2'
    ```
    - 多行表达式和注释：
    ```python
    >>> f"This is the playlist: {", ".join([
    ...     'Take me back to Eden',  # My, my, those eyes like fire
    ...     'Alkaline',              # Not acid nor alkaline
    ...     'Ascensionism'           # Take to the broken skies at last
    ... ])}"
    'This is the playlist: Take me back to Eden, Alkaline, Ascensionism'
    ```
    - 反斜杠和unicode字符：
    ```python
    >>> print(f"This is the playlist: {"\n".join(songs)}")
    This is the playlist: Take me back to Eden
    Alkaline
    Ascensionism
    >>> print(f"This is the playlist: {"\N{BLACK HEART SUIT}".join(songs)}")
    This is the playlist: Take me back to Eden♥Alkaline♥Ascensionism
    ```
    - 错误更加准确
    
        但错误消息不包括错误在行中的确切位置，并且还人为地将表达式括在括号中。在 Python 3.12 中，由于使用 PEG 解析器解析 f 字符串，因此错误消息可以更精确并显示整行：
    ```python
    >>> my_string = f"{x z y}" + f"{1 + 1}"
      File "<stdin>", line 1
      my_string = f"{x z y}" + f"{1 + 1}"
                   ^^^
    SyntaxError: invalid syntax. Perhaps you forgot a comma?
    ```
## 3. 支持python代码中的缓冲区协议
- 支持 Python 代码中的缓冲区协议 （[PEP 688](https://peps.python.org/pep-0688/)）

## 4. 每个解释器GIL
PEP 684 引入了按解释者指定的 GIL，因此现在可以为每个解释者创建具有唯一 GIL 的子解释器。这允许 Python 程序充分利用多个 CPU 内核。目前只能通过 C-API 使用，但预计 3.13 中将提供 Python API。

从结果来看：多解释器的运行时间，提高了60倍，期待3.13的提升。可以考虑在CPU的密集型任务当中，加入此功能（改成一个装饰器）

```python
import time
import multiprocessing
import ctypes

# 加载 Python 动态链接库
python_lib = ctypes.CDLL(None)

# 定义 PyInterpreterConfig 结构体
class PyInterpreterConfig(ctypes.Structure):
    _fields_ = [
        ("check_multi_interp_extensions", ctypes.c_int),
        ("gil", ctypes.c_int)
    ]

# 定义常量
PyInterpreterConfig_OWN_GIL = 1

# 定义函数原型
python_lib.Py_NewInterpreterFromConfig.argtypes = [ctypes.POINTER(ctypes.c_void_p), ctypes.POINTER(PyInterpreterConfig)]
python_lib.Py_NewInterpreterFromConfig.restype = ctypes.c_int

python_lib.PyStatus_Exception.argtypes = [ctypes.c_int]
python_lib.PyStatus_Exception.restype = ctypes.c_int

# 模拟 CPU 密集型任务
def cpu_intensive_task():
    start_time = time.time()
    while time.time() - start_time < 5:
        _ = 1 + 1

# 单解释器运行任务
def single_interpreter():
    cpu_intensive_task()

# 多解释器运行任务
def multi_interpreter():
    config = PyInterpreterConfig()
    config.check_multi_interp_extensions = 1
    config.gil = PyInterpreterConfig_OWN_GIL

    tstate = ctypes.c_void_p()
    status = python_lib.Py_NewInterpreterFromConfig(ctypes.byref(tstate), ctypes.byref(config))
    if python_lib.PyStatus_Exception(status):
        return -1
    cpu_intensive_task()

if __name__ == "__main__":
    num_cores = multiprocessing.cpu_count()

    # 单解释器测试
    single_start_time = time.time()
    processes = [multiprocessing.Process(target=single_interpreter) for _ in range(num_cores)]
    for p in processes:
        p.start()
    for p in processes:
        p.join()
    single_end_time = time.time()
    single_total_time = single_end_time - single_start_time

    # 多解释器测试
    multi_start_time = time.time()
    processes = [multiprocessing.Process(target=multi_interpreter) for _ in range(num_cores)]
    for p in processes:
        p.start()
    for p in processes:
        p.join()
    multi_end_time = time.time()
    multi_total_time = multi_end_time - multi_start_time

    print(f"单解释器总时间: {single_total_time} 秒")
    print(f"多解释器总时间: {multi_total_time} 秒")
    if multi_total_time < single_total_time:
        print("多解释器利用多核 CPU 更高效。")
    else:
        print("单解释器和多解释器性能相近或单解释器更优。")


""""
运行结果：
单解释器总时间: 6.34592080116272 秒
多解释器总时间: 0.10944199562072754 秒
多解释器利用多核 CPU 更高效。
"""
```

## 5. 理解式内联

![image.png](/static/img/8b4e481581c95e1aaa28799cc6482cd5.image.webp)

从详细的图片可以看出，之前的版本会在列表推导式、字典推导式，进行创建一个一次性函数对象，用完之后，进行丢弃。

而新的版本是：不需要单独的代码对象，也不再需要创建一次性的函数对象，也不再需要创建和销毁python框架。

**locals包含外部变量**
```python
>>> def f(lst):
...    return [locals() for x in lst]
...
>>> f(1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 2, in f
TypeError: 'int' object is not iterable
>>> f([1])
[{'lst': [1], 'x': 1}]
>>>
```

对比3.11

```python
Python 3.11.10 (main, Oct  3 2024, 02:37:52) [Clang 14.0.6 ] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> def f(lst):
... ...    return [locals() for x in lst]
  File "<stdin>", line 2
    ...    return [locals() for x in lst]
    ^
IndentationError: expected an indented block after function definition on line 1
>>> def f(lst):
...    return [locals() for x in lst]
...
>>> f([1])
[{'.0': <list_iterator object at 0x10cb4e0b0>, 'x': 1}]
>>>
```

## 6. 与TypeHint相关的新功能
1.  PEP 692： 使用 TypedDict 进行更精确的 **kwargs 类型
在 PEP 484 引入的函数签名中键入 **kwargs 仅在所有 **kwargs 都属于相同类型的情况下才允许有效注释。

PEP 692 指定了一种更精确的键入 **kwargs 的方法，它依赖于类型化的字典：

```python
from typing import TypedDict, Unpack

class Movie(TypedDict):
  name: str
  year: int

def foo(**kwargs: Unpack[Movie]): ...
```


2. PEP 698： 覆盖静态类型的装饰器¶

增加一种，可以检查覆盖父类方法的，是否有调用。如果去掉override，在badchild中他是没有get_color,她就会调用base的方法。但实际上，你写的代码是为了调用badChild的。

so，这个方法还是对于你要覆盖父类方法有很大的用处
```python
from typing import override

class Base:
  def get_color(self) -> str:
    return "blue"

class GoodChild(Base):
  @override  # ok: overrides Base.get_color
  def get_color(self) -> str:
    return "yellow"

class BadChild(Base):
  @override  # type checker error: does not override Base.get_color
  def get_colour(self) -> str:
    return "red"


good = GoodChild()
bad = BadChild()
print(good.get_color())
print(bad.get_color())

```
## 7. canlendar的使用，增加月和日

[链接地址](https://docs.python.org/3.12/library/calendar.html#calendar.Month)
![image.png](/static/img/1e081f384bcad7d4c6c2a6aa88f52a30.image.webp)
## 8. itertools.batched，批量储量
将列表、字符串，批量分割成你规定的大小

```python
flattened_data = ['roses', 'red', 'violets', 'blue', 'sugar', 'sweet']
unflattened = list(batched(flattened_data, 2))
unflattened
[('roses', 'red'), ('violets', 'blue'), ('sugar', 'sweet')]

# batched('ABCDEFG', 3) → ABC DEF G

h
```
反过来：合并的方法是: `itertools.chain(*iterables)`



## 9. os.path.splitroot(path)

将路径名路径拆分为一个 3 项元组 （drive， root， tail），其中 drive 是设备名称或挂载点，root 是驱动器后面的一串分隔符，tail 是 root 之后的所有内容。这些项中的任何一项都可能是空字符串。在所有情况下，drive + root + tail 都将与 path 相同。

看情况，用起来是有点不准的。哈哈

```python
splitroot('C:/Users/Sam')
('C:', '/', 'Users/Sam')
splitroot('//Server/Share/Users/Sam')
('//Server/Share', '/', 'Users/Sam')
```

## 10. unittest,添加--durations,显示N个最慢的测试用例
```python
python3 -m unittest --durations=3 lib.tests.test_threading
.....
Slowest test durations
----------------------------------------------------------------------
1.210s     test_timeout (Lib.test.test_threading.BarrierTests)
1.003s     test_default_timeout (Lib.test.test_threading.BarrierTests)
0.518s     test_timeout (Lib.test.test_threading.EventTests)

(0.000 durations hidden.  Use -v to show these durations.)
----------------------------------------------------------------------
Ran 158 tests in 9.869s

OK (skipped=3)
```

## 11. uuid增加command-line 功能
```python
# generate a random uuid - by default uuid4() is used
$ python -m uuid

# generate a uuid using uuid1()
$ python -m uuid -u uuid1

# generate a uuid using uuid5
$ python -m uuid -u uuid5 -n @url -N example.com
```

将来有时间再加上3.12之前的PEP，还是挺有意思的👂🏻

📅 python3.12版本

🎯 一、文章目标：用不到150行Python代码构建一个全文搜索引擎

全文搜索（Full-text search）是现代信息检索系统的基础。Google、Amazon、Netflix 等平台都依赖它快速从海量非结构化文本中找出相关结果。



本文的目标不是构建一个生产级搜索引擎（如 Elasticsearch），而是通过极简代码展示搜索引擎的核心原理，让你理解：

- 如何高效索引文档？
- 如何解析用户查询？
- 如何匹配并排序结果（即“相关性排序”）？

整个系统基于 维基百科摘要数据集（约627万篇文档），在普通笔记本电脑上就能运行，并支持毫秒级响应。

🧱 二、整体架构：三步走

全文搜索引擎通常包含三个核心阶段：

1. 数据准备（Data Preparation）
2. 索引构建（Indexing）
3. 查询与排序（Searching & Ranking）

下面我们逐层拆解。

🔹 第一步：数据准备（Data）

数据来源
- 使用 English Wikipedia Abstracts
- 格式：Gzipped XML 文件（约785MB）
- 每条记录结构如下：
    
    Wikipedia: London Beer Flood
    https://en.wikipedia.org/wiki/London_Beer_Flood
    The London Beer Flood was an accident...
  
  

文档表示（Document Model）
使用 Python dataclass 定义文档结构：

from dataclasses import dataclass

@dataclass
class Abstract:
    ID: int
    title: str
    abstract: str
    url: str

    @property
    def fulltext(self):
        return ' '.join([self.title, self.abstract])

💡 fulltext 将标题和摘要拼接，作为全文搜索的内容。

流式加载（Memory-Efficient Parsing）
- 使用 lxml.etree.iterparse 流式解析 XML，避免一次性加载整个文件到内存。
- 为每篇文档分配唯一 ID（从1开始递增）。
- 解析后立即释放 XML 节点内存（element.clear()）。

✅ 关键思想：处理大数据时，流式处理 + 内存释放 是必须的。

🔹 第二步：文本分析与索引构建（Analysis & Indexing）

什么是“倒排索引”（Inverted Index）？

想象一本书后面的索引页：
beer → p.23, p.45, p.102  
london → p.12, p.23, p.89  

在计算机中，我们用字典模拟：
{
  "london": {1501027, 1828015, ...},
  "beer":   {1501027, 1828015, ...},
  "flood":  {1828015, ...}
}

→ 词 → 包含该词的文档ID集合

这就是倒排索引，是全文搜索的基石。

文本分析流程（Text Analysis Pipeline）

为了提高匹配准确率，原始文本需经过“分析”（analyze）变成标准化的词项（tokens）：

步骤如下（顺序很重要！）：

1. 分词（Tokenize）  
      def tokenize(text): return text.split()
   
   → 按空格切分（简单但有效）

2. 转小写（Lowercase）  
      def lowercase_filter(tokens): return [t.lower() for t in tokens]
   

3. 去除标点（Punctuation Removal）  
      import re, string
   PUNCTUATION = re.compile('[%s]' % re.escape(string.punctuation))
   def punctuation_filter(tokens):
       return [PUNCTUATION.sub('', t) for t in tokens]
   

4. 停用词过滤（Stopword Filtering）  
   移除高频无意义词（如 the, and, wikipedia）：
      STOPWORDS = {'the', 'be', 'to', ..., 'wikipedia'}
   def stopword_filter(tokens):
       return [t for t in tokens if t not in STOPWORDS]
   

5. 词干提取（Stemming）  
   使用 PyStemmer 将不同形式归一化：
   - "brewery" → "breweri"
   - "breweries" → "breweri"

      import Stemmer
   STEMMER = Stemmer.Stemmer('english')
   def stem_filter(tokens): return STEMMER.stemWords(tokens)
   

⚠️ 注意：停用词过滤必须在词干化之前，因为停用词列表是原始形式（如 "the"），而词干化后可能变成 "th"。

组合分析函数
def analyze(text):
    tokens = tokenize(text)
    tokens = lowercase_filter(tokens)
    tokens = punctuation_filter(tokens)
    tokens = stopword_filter(tokens)
    tokens = stem_filter(tokens)
    return [t for t in tokens if t]  # 去除空字符串

构建索引（Index Class）

class Index:
    def init(self):
        self.index = {}      # 倒排索引：token → set(doc_id)
        self.documents = {}  # doc_id → Abstract 对象

    def index_document(self, document):
        if document.ID not in self.documents:
            self.documents[document.ID] = document
            document.analyze()  # 计算词频（见下文）
        for token in analyze(document.fulltext):
            if token not in self.index:
                self.index[token] = set()
            self.index[token].add(document.ID)

✅ 此时已完成索引构建！后续查询只需查字典。

🔹 第三步：搜索与相关性排序（Search & Relevance）

1. 基础布尔搜索（Boolean Search）

def search(self, query, search_type='AND'):
    analyzed_query = analyze(query)
    results = [self.index.get(token, set()) for token in analyzed_query]
    
    if search_type == 'AND':
        doc_ids = set.intersection(*results)  # 所有词都出现
    elif search_type == 'OR':
        doc_ids = set.union(*results)         # 任一词出现
    
    return [self.documents[doc_id] for doc_id in doc_ids]

- AND：高精度（precision），结果少但相关
- OR：高召回（recall），结果多但噪声大

2. 相关性排序：TF-IDF

问题：布尔搜索返回的结果没有排序，用户仍需自己筛选。

解决方案：为每个文档打分 → TF-IDF（Term Frequency–Inverse Document Frequency）

（1）词频（Term Frequency, TF）
- 一个词在文档中出现次数越多，越相关。
- 在 Abstract 类中预计算：

from collections import Counter
def analyze(self):
    self.term_frequencies = Counter(analyze(self.fulltext))

def term_frequency(self, term):
    return self.term_frequencies.get(term, 0)

（2）逆文档频率（Inverse Document Frequency, IDF）
- 一个词在整个语料库中越罕见，区分度越高。
- 公式：
  
  text{IDF}(t) = log_{10} left( frac{N}{text{df}(t)} right)
  
  -  N ：总文档数
  -  text{df}(t) ：包含词  t  的文档数

def inverse_document_frequency(self, token):
    df = len(self.index.get(token, set()))
    return math.log10(len(self.documents) / df)

（3）最终得分：TF × IDF

def rank(self, analyzed_query, documents):
    results = []
    for doc in documents:
        score = sum(doc.term_frequency(t) * self.inverse_document_frequency(t)
                    for t in analyzed_query)
        results.append((doc, score))
    return sorted(results, key=lambda x: x[1], reverse=True)

✅ 这样，最相关的文档排在最前面！

🧪 示例效果

查询 "London Beer Flood"：

- 布尔 AND 搜索 → 返回2篇高度相关文档（如“Horse Shoe Brewery”）
- TF-IDF 排序 → 即使使用 OR 模式返回数万结果，也能把最相关的排在顶部

🛠 技术亮点总结
技术点   说明
倒排索引   核心数据结构，实现 O(1) 词查找

流式 XML 解析   处理大文件不爆内存

文本分析管道   分词 → 小写 → 去标点 → 停用词 → 词干化

布尔搜索（AND/OR）   灵活控制精度与召回

TF-IDF 排序   经典相关性算法，兼顾词频与稀有度

内存效率   所有数据结构用 Python 原生 dict/set，简洁高效

🚀 可扩展方向（Future Work）

作者也指出，这只是一个教学原型，可改进之处包括：

1. 字段加权：标题中的词比摘要中更重要（可乘以权重）
2. 更复杂的查询语法：支持 NOT、括号、短语搜索（"exact phrase"）
3. 持久化索引：当前全在内存，可序列化到磁盘
4. 使用更优分词器：如 spaCy、NLTK 替代空格分词
5. 避免词干化过度：考虑用 lemmatization（词形还原）替代 stemming

✅ 总结：你学到了什么？

1. 搜索引擎本质 = 倒排索引 + 查询解析 + 相关性排序
2. 150行代码足够展示核心思想，无需复杂框架
3. TF-IDF 是经典且有效的排序方法
4. 工程上要注意内存与效率（流式处理、及时释放）
5. 文本预处理顺序很重要（停用词在词干前）

这篇文章的价值不在于代码多精巧，而在于用最简方式揭示了 Google 背后的基本原理。

如果你想动手实践，作者已将代码开源：
👉 https://github.com/bartdegoede/python-searchengine

只需：
pip install -r requirements.txt
python run.py

倒排索引

# Skills 与 MCP 工具对比解析（基于 LlamaIndex 官方博客）
[博客地址](https://www.llamaindex.ai/blog/skills-vs-mcp-tools-for-agents-when-to-use-what?utm_source=socials&utm_medium=li_social)
## 一、核心定义：两类 Agent 能力载体的本质区别



### 1. MCP（Model Context Protocol，模型上下文协议）
- **核心定位**：为大语言模型（LLM）扩展能力的标准化协议，通过第三方服务提供工具、资源（文件式接口暴露的额外上下文）和参数化提示，本质是“Agent 与外部工具的通用连接层”。
- **关键特征**：
  - 依赖外部服务：工具调用需通过网络请求连接第三方服务器，存在网络 latency；
  - 执行确定性强：输入输出 schema 固定，相同条件下返回结果一致，如“给定 URL 调用网页爬取工具，必然返回对应页面内容”；
  - 开发者友好：设计面向有认证、传输协议、命令行基础的开发者，需理解 stdio 通信等技术概念。

### 2. Skills（技能）
- **核心定位**：Agent 本地加载的领域专属指令集合，以 Markdown 文档为载体，包含自然语言操作指南、代码片段及关联资源，本质是“Agent 的本地化行为说明书”。
- **关键特征**：
  - 本地无网络依赖：技能文件存储于本地目录，调用无网络 overhead，响应更快；
  - 指令自然语言化：无需技术背景，用日常语言定义操作逻辑，如“调用 scpr 命令时需传入 URL 参数”；
  - 结构模块化：每个技能对应独立文件夹，包含核心说明文件（SKILL.md）、可选脚本（如 Python 脚本）和参考文档（REFERENCE.md），典型目录结构如下：
    ```bash
    .claude/skills
    ├── pdf-parsing          # PDF 解析技能
    │   ├── script.py        # 辅助执行脚本
    │   └── SKILL.md         # 核心操作指令
    └── web-scraping         # 网页爬取技能
        └── SKILL.md
    ```


## 二、核心差异：从 setup 到执行的全方位对比
| **对比维度**       | **MCP**                                  | **Skills**                              |
|--------------------|------------------------------------------|-----------------------------------------|
| **部署复杂度**     | 中等（需开发者掌握认证、传输协议、CLI）  | 极低（仅需创建 Markdown 文件夹，无技术门槛） |
| **执行模式**       | 确定性 API 调用（固定输入输出 schema）   | LLM 解读自然语言指令（可能存在理解偏差） |
| **性能表现**       | 有网络延迟（依赖外部服务调用）           | 本地执行，无网络 overhead，响应更快     |
| **维护成本**       | 集中化（服务器更新自动同步到所有 Agent） | 手动化（需编辑本地 Markdown 文件更新） |
| **扩展性挑战**     | 工具数量增多时，发现与适配难度上升（需网关/中间件辅助） | 新增技能简单，但 LLM 选择技能的复杂度增加 |
| **失败风险**       | 仅“工具选择错误”一种核心风险             | 双重风险：技能选择错误 + 指令理解偏差   |


## 三、适用场景：何时选 MCP，何时选 Skills？
### 1. 优先选 MCP 的场景
- **精准、可预测的操作需求**：如网页爬取、数据库查询等输入输出明确的任务，需确保结果一致性；
- **多 Agent 共享工具**：多个 Agent 需调用同一外部服务（如共享文件存储、统一 API 接口），MCP 一次部署即可多端复用；
- **快速迭代的知识领域**：如频繁更新的 SDK 文档、实时数据接口，MCP 可通过服务器同步最新信息，无需手动修改每个 Agent 配置（典型案例：LlamaIndex 用文档 MCP 实时同步 SDK 最新用法）。

### 2. 优先选 Skills 的场景
- **行为引导类需求**：需用自然语言规范 Agent 操作逻辑，如“按企业品牌规范生成文档”“遵循特定代码风格写脚本”；
- **无技术背景用户使用**：非开发者无需理解协议、接口，仅需编辑 Markdown 即可定义 Agent 能力；
- **本地轻量操作**：如本地文件解析（PDF/Excel）、离线数据处理等无需外部服务的任务，Skills 无网络延迟优势更明显；
- **高度定制化流程**：如个人专属笔记整理、团队内部独特工作流，需灵活调整操作指令且无需共享给其他 Agent。


## 四、实战启示：LlamaAgents Builder 的经验总结
LlamaIndex 在开发 Agent 编码能力时，曾尝试“MCP + Skills 结合”方案，最终得出关键结论：
1. **MCP 更适合知识底座**：文档类 MCP 能提供更全面、实时的知识（如 SDK 用法），足以支撑 Agent 完成基础代码生成；
2. **Skills 增量价值有限**：在已有 MCP 提供知识的场景下，Skills 未显著提升结果质量，且需额外维护 Markdown 文件；
3. **核心决策依据**：若领域知识更新快（如频繁迭代的工具、实时数据），MCP 的“单一数据源同步”更高效；若需稳定的行为规范（如固定流程、品牌要求），Skills 的“本地轻量定制”更适配。

SKILL VS MCP

Prompt1：项目亮点提炼

我的项目：【项目名称及你的角色】
技术栈：【列出使用的技术】
请帮我提炼3个最能体现技术能力的亮点，每个亮点：



用一句话说明做了什么
用数据说明效果
突出技术难点或创新点
Prompt2：平淡项目包装

我有一个比较常规的项目，担心写在简历上没有亮点：
项目背景：【描述】
我的职责：【描述】
使用技术：【列出】
请帮我从以下角度挖掘亮点：
1. 技术选型的考量
2. 遇到的难点和解决方案
3. 可量化的成果（即使是小的提升）
4. 与其他方案的对比优势
输出3个版本的描述，从保守到略微包装（但不夸大事实）。

Prompt 3：弱化学历背景（双非/专科）

我的学历背景：【学校+专业】
可补充的亮点：【如：GPA、奖学金、竞赛（和计算机有关的）、项目等】
目标岗位对学历的要求：【如：本科及以上】
请帮我：
1. 设计教育经历的呈现方式（淡化学校，突出能力）
2. 在其他模块（项目、技能）如何体现学习能力

3.补充可以增加的模块（如GitHub、技术博客等）

Prompt4：简历动词优化

请将以下简历描述中的弱动词替换为更有力的技术动词：
原文：【粘贴简历片段】
参考动词库：
- 负责 → 设计、开发、实现、优化、重构
- 参与 → 主导、搭建、推动
- 做了 → 完成、交付、落地
要求：
1. 避免被动语态
2. 突出个人贡献
3. 保持真实性

Prompt 5：针对不同公司定制简历

我有一份通用简历，现在要投递【具体公司+岗位】，请帮我定制：
通用简历：【粘贴】
目标公司JD：【粘贴】
目标公司特点：【如：重视用户思维、强调创新、技术精益求精等】
请调整：
1. 项目经历的排序和侧重点
2. 技能标签的优先级
3. 自我评价的调整

作者：whiff@0908
链接：https://www.nowcoder.com/discuss/846411133899583488
来源：牛客网

ai-prompt优化简历

# 面向SOP文档的知识增强问答系统技术报告

## 摘要

本报告基于OG-RAG论文思想，系统性地探索了如何构建面向结构化SOP文档的知识增强问答系统。通过理论分析、架构设计、技术选型和实践验证，我们提出了一套融合超图表示、LLM推理和图数据库的混合解决方案。报告详细记录了从概念理解到实践落地的全过程，重点关注系统的可行性、有效性和可维护性。



## 1. 项目背景与目标

### 1.1 业务背景
- **领域**：汽车保养维修SOP文档管理
- **核心需求**：基于结构化SOP文档，提供准确、可靠、可追溯的智能问答服务
- **痛点分析**：
  - 传统RAG检索片段化，无法保证事实完整性
  - 业务规则复杂且频繁更新，需要版本管理
  - 回答需要可解释、可溯源，支持审计要求

### 1.2 技术目标
1. **准确性**：回答基于完整事实，减少LLM幻觉
2. **可解释性**：每个回答能追溯到具体SOP规则
3. **可维护性**：支持知识库的动态更新和版本控制
4. **高效性**：检索响应时间满足实时交互需求
5. **灵活性**：适应不同复杂度的SOP规则

### 1.3 核心挑战
```
1. 如何表示结构化的SOP知识？
2. 如何平衡LLM的灵活性与规则的严谨性？
3. 如何设计可演进的知识存储架构？
4. 如何实现高效的上下文检索？
```

---

## 2. 技术选型与架构设计

### 2.1 技术栈选择
| 组件 | 技术选型 | 选择理由 |
|------|----------|----------|
| **知识表示** | OG-RAG超图 | 完整事实表示，支持结构化检索 |
| **存储层** | Neo4j + 向量数据库 | 图结构存储 + 向量相似度检索 |
| **处理引擎** | LLM（GPT系列/开源模型） | 自然语言理解与生成 |
| **本体管理** | 轻量级术语表（非完整本体） | 平衡严谨性与实现成本 |
| **向量模型** | text-embedding-3-small | 平衡质量与性能 |

### 2.2 整体架构
```
三层架构设计：
1. 知识构建层（离线）
   ├── SOP文档输入
   ├── LLM事实提取
   ├── 超图构建
   └── 向量化存储

2. 知识存储层
   ├── Neo4j：存储超图结构（HyperEdge/HyperNode/CONTAINS）
   ├── 向量索引：存储HyperNode向量
   └── 版本管理：多版本SOP规则存储

3. 查询服务层（在线）
   ├── 查询理解
   ├── 超图检索
   ├── 上下文构建
   └── LLM生成
```

### 2.3 创新设计
```
1. 简化本体：使用术语表代替完整本体，降低构建成本
2. 混合检索：向量相似度 + 超边覆盖度，保证完整性与相关性
3. 增量更新：支持SOP规则的局部更新，无需重建全图
4. 双轨版本：支持历史查询和当前查询使用不同版本规则
```

---

## 3. 核心概念实现

### 3.1 HyperEdge（超边）设计
```python
class HyperEdge:
    def __init__(self, edge_id, description, sop_rule):
        self.id = edge_id  # 唯一标识符
        self.description = description  # 人类可读描述
        self.sop_rule = sop_rule  # 原始SOP规则文本
        self.hypernodes = []  # 包含的HyperNode列表
        self.metadata = {
            'sop_version': '1.0',
            'effective_date': '2024-01-01',
            'expiry_date': None,
            'confidence': 0.95,
            'source': 'sop_doc_3.2'
        }
    
    def add_hypernode(self, hypernode):
        """添加超节点，建立CONTAINS关系"""
        self.hypernodes.append(hypernode)
        hypernode.belongs_to.append(self.id)
    
    def to_context(self):
        """转换为LLM上下文"""
        context = f"规则描述: {self.description}\n"
        for node in self.hypernodes:
            context += f"{node.key}: {node.value}\n"
        return context
```

### 3.2 HyperNode（超节点）设计
```python
class HyperNode:
    def __init__(self, node_id, key, value, node_type):
        self.id = node_id
        self.key = key  # 格式："实体⊕属性" 如："车辆⊕类型"
        self.value = value  # 属性值
        self.type = node_type  # entity/text/number/operator
        self.embedding = None  # 向量表示
        self.belongs_to = []  # 所属的HyperEdge列表
        self.similar_to = []  # SIMILAR_TO关系列表
        
    def generate_embedding(self, vector_model):
        """生成向量嵌入"""
        text = f"{self.key}: {self.value}"
        self.embedding = vector_model.encode(text)
    
    def find_similar_nodes(self, all_nodes, threshold=0.7):
        """查找相似节点"""
        similar = []
        for node in all_nodes:
            if node.id != self.id and node.embedding is not None:
                similarity = cosine_similarity(self.embedding, node.embedding)
                if similarity > threshold:
                    similar.append({
                        'node': node,
                        'similarity': similarity,
                        'relation': 'SIMILAR_TO'
                    })
        return similar
```

### 3.3 CONTAINS关系实现
```
Neo4j实现：
CREATE (he:HyperEdge {
    id: $edge_id,
    description: $description
})
CREATE (hn:HyperNode {
    id: $node_id,
    key: $key,
    value: $value
})
CREATE (he)-[:CONTAINS {
    role: $role,  # subject/action/condition/requirement
    order: $order
}]->(hn)

优势：
1. 明确的组成关系
2. 支持角色标注
3. 支持排序
4. 快速反向查找
```

### 3.4 SIMILAR_TO关系实现
```cypher
// 静态预计算
MATCH (n1:HyperNode), (n2:HyperNode)
WHERE n1.id < n2.id
  AND n1.embedding IS NOT NULL
  AND n2.embedding IS NOT NULL
WITH n1, n2, 
     gds.similarity.cosine(n1.embedding, n2.embedding) AS sim
WHERE sim > 0.75
CREATE (n1)-[:SIMILAR_TO {
    score: sim,
    computed_at: timestamp()
}]->(n2)

// 动态查询时计算
WITH $query_vector AS query_vec
MATCH (hn:HyperNode)
WHERE hn.embedding IS NOT NULL
WITH hn, gds.similarity.cosine(hn.embedding, query_vec) AS sim
WHERE sim > 0.65
RETURN hn
ORDER BY sim DESC
LIMIT 10
```

---

## 4. 系统实现流程

### 4.1 知识构建流程
```
输入：SOP文档集合
    ↓
步骤1：文档预处理
    ├── 分段：按业务规则划分
    ├── 清理：标准化术语
    └── 标注：标记关键信息
    ↓
步骤2：LLM事实提取（基于术语表）
    ├── 输入：SOP段落 + 术语表
    ├── 处理：识别实体、属性、关系
    └── 输出：结构化事实列表
    ↓
步骤3：超图构建
    ├── 每个SOP规则 → 一个HyperEdge
    ├── 规则中的要素 → 多个HyperNode
    ├── 建立CONTAINS关系
    └── 生成向量嵌入
    ↓
步骤4：存储优化
    ├── Neo4j：存储图结构
    ├── 向量索引：存储嵌入向量
    └── 缓存层：热点数据缓存
```

### 4.2 查询处理流程
```
输入：用户自然语言查询
    ↓
步骤1：查询理解
    ├── 意图识别：保养咨询/故障诊断/规则查询
    ├── 实体抽取：车辆类型、部件、条件
    └── 时间解析：历史查询/当前查询/未来预测
    ↓
步骤2：超图检索
    ├── 向量检索：找到相似HyperNode
    ├── 图遍历：通过CONTAINS找到HyperEdge
    └── 贪心算法：选择最小覆盖超边集
    ↓
步骤3：上下文构建
    ├── 超边排序：按相关性排序
    ├── 格式转换：转换为自然语言上下文
    └── 元数据添加：版本、来源、置信度
    ↓
步骤4：LLM生成
    ├── 提示工程：结构化提示模板
    ├── 生成控制：温度、最大长度等参数
    └── 后处理：格式化输出
    ↓
输出：结构化答案 + 溯源信息
```

### 4.3 关键算法实现
```python
def greedy_hyperedge_selection(similar_nodes, hypergraph, max_edges=3):
    """
    贪心算法选择超边（论文核心算法）
    
    参数：
        similar_nodes: 与查询相似的超节点列表
        hypergraph: 超图对象
        max_edges: 最大返回超边数
    
    返回：
        选中的超边列表
    """
    # 未覆盖节点集合
    uncovered_nodes = set([n.id for n in similar_nodes])
    selected_edges = []
    
    while uncovered_nodes and len(selected_edges) < max_edges:
        best_edge = None
        best_coverage = 0
        
        # 找到覆盖最多未覆盖节点的超边
        for edge in hypergraph.edges:
            edge_nodes = set([n.id for n in edge.hypernodes])
            coverage = len(edge_nodes.intersection(uncovered_nodes))
            
            if coverage > best_coverage:
                best_coverage = coverage
                best_edge = edge
        
        if best_edge and best_coverage > 0:
            selected_edges.append(best_edge)
            # 更新未覆盖节点
            covered_nodes = set([n.id for n in best_edge.hypernodes])
            uncovered_nodes = uncovered_nodes - covered_nodes
        else:
            break
    
    return selected_edges
```

---

## 5. 关键技术挑战与解决方案

### 5.1 挑战一：本体复杂性与实用性的平衡
**问题**：完整本体构建成本高，但简单术语表无法支持复杂推理

**解决方案**：渐进式本体建设
```
阶段1：基础术语表（当前实施）
   ├── 实体列表：车辆、保养项目、配件
   ├── 属性列表：名称、型号、周期、条件
   └── 关系列表：需要、包含、基于

阶段2：轻量级本体（6个月后）
   ├── 类层次结构
   ├── 属性约束
   ├── 基本推理规则
   └── 版本管理

阶段3：完整本体（1年后，如有需要）
   ├── 形式化公理
   ├── 复杂推理
   ├── 跨领域集成
   └── 自动化维护
```

### 5.2 挑战二：LLM幻觉与事实准确性的矛盾
**问题**：LLM可能生成看似合理但不准确的信息

**解决方案**：多层验证机制
```
1. 源头控制：超图确保检索事实的完整性
2. 过程控制：结构化提示词约束LLM生成
3. 结果控制：基于规则的答案验证
4. 反馈循环：用户纠错机制持续改进

具体措施：
- 答案必须引用超边ID
- 关键数值必须与超节点一致
- 不确定时明确说明"规则未明确"
```

### 5.3 挑战三：版本管理与知识演化
**问题**：SOP规则频繁更新，需要支持多版本查询

**解决方案**：时间感知知识图谱
```python
class VersionedKnowledgeGraph:
    def __init__(self):
        self.versions = {}  # 版本号 -> 超图快照
        self.current_version = None
        self.version_mappings = {}  # 版本间映射关系
    
    def add_version(self, version_id, hypergraph, effective_date):
        """添加新版本"""
        self.versions[version_id] = {
            'hypergraph': hypergraph,
            'effective_date': effective_date,
            'status': 'active'  # active/deprecated/archived
        }
        self.current_version = version_id
    
    def query_with_version(self, query, query_time=None):
        """版本感知查询"""
        if query_time is None:
            # 使用当前版本
            target_version = self.current_version
        else:
            # 找到query_time时有效的版本
            target_version = self._find_version_for_time(query_time)
        
        # 使用对应版本的超图进行查询
        hypergraph = self.versions[target_version]['hypergraph']
        return hypergraph.query(query)
    
    def compare_versions(self, version1, version2, concept=None):
        """版本差异分析"""
        # 比较两个版本的知识差异
        # 可用于生成更新说明、迁移指南等
        pass
```

### 5.4 挑战四：检索效率与准确性的平衡
**问题**：贪心算法可能不是最优，计算复杂度高

**解决方案**：混合检索策略
```
一级检索：向量相似度（快速）
  ├── 目的：快速找到相关节点
  ├── 方法：ANN近似最近邻
  └── 返回：Top-50相似节点

二级检索：超边覆盖优化（精确）
  ├── 目的：找到最优超边组合
  ├── 方法：贪心算法 + 剪枝优化
  └── 返回：Top-3相关超边

性能优化：
- 建立向量索引加速相似度计算
- 缓存热点查询结果
- 并行处理独立子图
```

---

## 6. 测试与验证方案

### 6.1 测试数据集
```
来源：汽车保养维修SOP文档（实际业务数据）
规模：100+条完整SOP规则
覆盖：保养项目、故障诊断、配件管理、工时标准

测试查询集：
1. 简单事实查询：TSI车多少公里换火花塞？
2. 复杂条件查询：高原地区使用的柴油车在冬季保养注意事项？
3. 多规则推理：更换刹车片时需要同时检查哪些部件？
4. 版本相关查询：2023年的规定和现在的规定有什么不同？
5. 边界情况查询：规定中没有明确说明的情况如何处理？
```

### 6.2 评估指标
```python
评估指标体系：
1. 准确性指标（Accuracy）
   ├── 事实准确率：回答中事实正确的比例
   ├── 规则符合率：回答符合SOP规则的比例
   └── 数值精确率：数值型回答的精确度

2. 完整性指标（Completeness）
   ├── 信息覆盖率：查询涉及信息的覆盖程度
   ├── 上下文相关性：返回上下文的主题相关性
   └── 无遗漏率：重要信息未被遗漏的比例

3. 效率指标（Efficiency）
   ├── 响应时间：端到端响应时间
   ├── 检索准确率：检索到相关上下文的准确率
   └── 资源消耗：CPU/内存使用情况

4. 可用性指标（Usability）
   ├── 可解释性：答案的溯源清晰度
   ├── 用户满意度：人工评估分数
   └── 易用性：非技术人员使用便捷度
```

### 6.3 对比实验设计
```
实验组：OG-RAG超图方案
对照组1：传统RAG（向量检索）
对照组2：规则引擎（基于if-then规则）
对照组3：纯LLM（无检索增强）

评估维度：
1. 不同复杂度查询的表现
2. 不同数据规模下的扩展性
3. 知识更新后的适应性
4. 异常查询的鲁棒性
```

---

## 7. 未来工作展望

### 7.1 短期优化（1-3个月）
```
1. 性能优化
   ├── 向量索引优化
   ├── 图查询缓存
   └── 并发处理优化

2. 准确性提升
   ├── 错误分析反馈循环
   ├── 多模型投票机制
   └── 人工校验接口

3. 功能扩展
   ├── 多语言支持
   ├── 多模态输入（图片、表格）
   └── 个性化推荐
```

### 7.2 中期发展（3-12个月）
```
1. 自动化知识维护
   ├── SOP变更自动检测
   ├── 冲突规则自动识别
   └── 知识质量自动评估

2. 智能能力增强
   ├── 主动知识发现
   ├── 预测性维护建议
   └── 根因分析能力

3. 生态集成
   ├── 与ERP/MES系统对接
   ├── 移动端应用
   └── API开放平台
```

### 7.3 长期愿景（1-3年）
```
1. 自主知识演化系统
   ├── 自我学习与优化
   ├── 知识自动迁移
   └── 智能知识合成

2. 行业解决方案
   ├── 标准化知识图谱框架
   ├── 领域自适应技术
   └── 低代码配置平台

3. 商业模式
   ├── SaaS服务平台
   ├── 知识即服务
   └── 行业解决方案提供商
```

---

## 8. 风险评估与应对策略

### 8.1 技术风险
| 风险项 | 可能性 | 影响 | 应对策略 |
|--------|--------|------|----------|
| LLM性能下降 | 中 | 高 | 多模型备选，本地模型部署 |
| 知识库规模爆炸 | 高 | 中 | 分层存储，冷热数据分离 |
| 检索效率瓶颈 | 中 | 高 | 查询优化，缓存策略 |
| 版本冲突 | 高 | 中 | 冲突检测算法，人工仲裁机制 |

### 8.2 业务风险
| 风险项 | 可能性 | 影响 | 应对策略 |
|--------|--------|------|----------|
| SOP规则频繁变更 | 高 | 高 | 增量更新，变更管理流程 |
| 用户接受度低 | 中 | 高 | 渐进推广，用户体验优化 |
| 合规与审计要求 | 高 | 高 | 完整追溯，审计日志 |
| 数据安全与隐私 | 高 | 高 | 数据脱敏，访问控制 |

### 8.3 实施风险
| 风险项 | 可能性 | 影响 | 应对策略 |
|--------|--------|------|----------|
| 技术选型错误 | 中 | 高 | 原型验证，技术选型评审 |
| 团队技能不足 | 中 | 高 | 培训计划，外部专家支持 |
| 项目延期 | 高 | 中 | 敏捷开发，里程碑管理 |
| 预算超支 | 中 | 中 | 成本控制，优先级排序 |

---

## 9. 结论与建议

### 9.1 核心结论
1. **OG-RAG超图表示法**是解决SOP知识管理的有效方案，特别适合需要完整事实和可追溯性的场景
2. **简化本体+超图+LLM**的混合架构在实践中更可行，平衡了严谨性与实现成本
3. **时间感知知识管理**是工业知识系统的必要能力，需要从设计阶段考虑
4. **渐进式实施策略**可以降低风险，快速验证核心价值

### 9.2 实施建议
```
第一步（1个月）：MVP验证
   ├── 选择10个核心SOP规则
   ├── 实现基本超图构建与检索
   └── 验证准确性与性能基准

第二步（2-3个月）：功能完善
   ├── 扩展至全部SOP规则
   ├── 实现版本管理功能
   └── 优化用户界面与体验

第三步（4-6个月）：系统集成
   ├── 与现有业务系统对接
   ├── 建立持续改进流程
   └── 培训用户与运维团队

长期：持续优化与扩展
```

### 9.3 战略价值
1. **业务价值**：提升服务效率50%以上，降低错误率80%以上
2. **数据资产**：将非结构化SOP文档转化为可计算的知识资产
3. **竞争优势**：构建基于AI的智能服务能力，形成技术壁垒
4. **可扩展性**：框架可扩展至其他领域的知识管理需求

---

## 附录

### A. 技术术语表
| 术语 | 定义 | 在系统中的角色 |
|------|------|----------------|
| SOP | 标准作业程序 | 原始知识来源 |
| HyperEdge | 超边 | 完整事实单元 |
| HyperNode | 超节点 | 属性-值对 |
| CONTAINS | 包含关系 | 超边与超节点的连接 |
| SIMILAR_TO | 相似关系 | 语义相似的超节点连接 |
| 向量嵌入 | 文本的数值表示 | 相似度计算基础 |
| 贪心算法 | 近似最优解算法 | 超边选择策略 |

### B. 依赖组件版本
```
- Neo4j: 5.x 以上
- Apache Jena: 4.x (可选，用于高级推理)
- Python: 3.9+
- LLM API: OpenAI GPT-4 或同等能力开源模型
- 向量模型: text-embedding-3-small
- 图算法库: Neo4j GDS Library
```

### C. 关键成功因素
1. **领域专家的深度参与**：确保知识提取的准确性
2. **迭代式开发方法**：快速验证，持续改进
3. **用户反馈机制**：建立闭环优化流程
4. **跨部门协作**：确保系统与业务流程的整合
5. **技术债务管理**：定期重构，保持代码质量

---

**报告完成时间**：2024年12月  
**报告版本**：1.0  
**报告状态**：技术可行性分析  
**下一步**：MVP原型开发与验证

这份报告系统地总结了从OG-RAG论文研究到实际系统设计的全过程，为后续的开发和实施提供了清晰的技术路线图和实施指南。