create-yss-spec 2.1.5 → 2.1.7

package/template/.agents/skills/kb-retriever/references/pdf_reading.md

@@ -1,362 +0,0 @@
-# PDF 读取与分析
-
-> ⚠️ **使用本文档前请注意**：本文档应在实际处理 PDF 文件之前完整阅读，以选择最合适的工具和方法。不要在未阅读本文档的情况下盲目尝试处理 PDF。
-
-用于从 PDF 文件中提取文本、表格和元数据的方法。
-
-## 快速决策表
-
-| 场景 | 推荐工具 | 原因 | 命令/代码示例 |
-|------|----------|------|--------------|
-| 纯文本提取（最常见） | pdftotext 命令 | 最快最简单 | `pdftotext input.pdf output.txt` |
-| 需要保留布局 | pdftotext -layout | 保持原始排版 | `pdftotext -layout input.pdf output.txt` |
-| 需要提取表格 | pdfplumber | 表格识别能力强 | `page.extract_tables()` |
-| 需要元数据 | pypdf | 轻量级 | `reader.metadata` |
-| 扫描PDF（图片） | OCR (pytesseract) | 无其他选择 | 先转图片再OCR |
-
-## 文本提取优先级
-
-**推荐优先级（从高到低）**：
-1. **pdftotext 命令行工具**（最快，适合大多数 PDF）
-2. pdfplumber（适合需要保留布局或提取表格）
-3. pypdf（轻量级，适合简单提取）
-4. OCR（仅用于扫描PDF或无法直接提取文本的情况）
-
-## 快速开始：使用 pdftotext（推荐）
-
-> ⚠️ **重要**：必须将输出保存到文件，不要直接输出到终端（stdout），否则会占用大量 token！
-
-```bash
-# ✅ 正确：提取文本到文件（最快最简单）
-pdftotext input.pdf output.txt
-
-# ✅ 正确：保留布局并输出到文件
-pdftotext -layout input.pdf output.txt
-
-# ✅ 正确：提取特定页面到文件
-pdftotext -f 1 -l 5 input.pdf output.txt  # 第1-5页
-
-# ❌ 错误：不要使用 stdout（会占用大量 token）
-# pdftotext input.pdf -
-```
-
-**使用流程**：
-1. 使用 pdftotext 提取文本到临时文件
-2. 使用 grep 或 Read 工具对生成的文本文件进行检索
-3. 只读取匹配部分的上下文，而非全文
-
-如果需要在 Python 中处理：
-
-```python
-from pypdf import PdfReader
-
-# 读取 PDF
-reader = PdfReader("document.pdf")
-print(f"Pages: {len(reader.pages)}")
-
-# 提取文本
-text = ""
-for page in reader.pages:
-    text += page.extract_text()
-```
-
-## Python 库
-
-### pypdf - 基本文本提取
-
-```python
-from pypdf import PdfReader
-
-reader = PdfReader("document.pdf")
-
-# 提取全部文本
-for page in reader.pages:
-    text = page.extract_text()
-    print(text)
-
-# 提取元数据
-meta = reader.metadata
-print(f"Title: {meta.title}")
-print(f"Author: {meta.author}")
-print(f"Subject: {meta.subject}")
-print(f"Creator: {meta.creator}")
-```
-
-### pdfplumber - 带布局的文本和表格提取
-
-#### 提取文本（保留布局）
-
-```python
-import pdfplumber
-
-with pdfplumber.open("document.pdf") as pdf:
-    for page in pdf.pages:
-        text = page.extract_text()
-        print(text)
-```
-
-#### 提取表格
-
-```python
-with pdfplumber.open("document.pdf") as pdf:
-    for i, page in enumerate(pdf.pages):
-        tables = page.extract_tables()
-        for j, table in enumerate(tables):
-            print(f"Table {j+1} on page {i+1}:")
-            for row in table:
-                print(row)
-```
-
-#### 高级表格提取（转为 DataFrame）
-
-```python
-import pandas as pd
-
-with pdfplumber.open("document.pdf") as pdf:
-    all_tables = []
-    for page in pdf.pages:
-        tables = page.extract_tables()
-        for table in tables:
-            if table:  # 检查表格非空
-                df = pd.DataFrame(table[1:], columns=table[0])
-                all_tables.append(df)
-
-# 合并所有表格
-if all_tables:
-    combined_df = pd.concat(all_tables, ignore_index=True)
-    combined_df.to_excel("extracted_tables.xlsx", index=False)
-```
-
-#### 带坐标的精确文本提取
-
-```python
-import pdfplumber
-
-with pdfplumber.open("document.pdf") as pdf:
-    page = pdf.pages[0]
-    
-    # 提取所有字符及其坐标
-    chars = page.chars
-    for char in chars[:10]:  # 前10个字符
-        print(f"Char: '{char['text']}' at x:{char['x0']:.1f} y:{char['y0']:.1f}")
-    
-    # 按边界框提取文本 (left, top, right, bottom)
-    bbox_text = page.within_bbox((100, 100, 400, 200)).extract_text()
-```
-
-#### 复杂表格的高级设置
-
-```python
-import pdfplumber
-
-with pdfplumber.open("complex_table.pdf") as pdf:
-    page = pdf.pages[0]
-    
-    # 自定义表格提取设置
-    table_settings = {
-        "vertical_strategy": "lines",
-        "horizontal_strategy": "lines",
-        "snap_tolerance": 3,
-        "intersection_tolerance": 15
-    }
-    tables = page.extract_tables(table_settings)
-    
-    # 可视化调试
-    img = page.to_image(resolution=150)
-    img.save("debug_layout.png")
-```
-
-### pypdfium2 - 快速渲染和文本提取
-
-```python
-import pypdfium2 as pdfium
-
-# 加载 PDF
-pdf = pdfium.PdfDocument("document.pdf")
-
-# 提取文本
-for i, page in enumerate(pdf):
-    text = page.get_text()
-    print(f"Page {i+1} text length: {len(text)} chars")
-```
-
-#### 将 PDF 页面渲染为图片
-
-```python
-import pypdfium2 as pdfium
-from PIL import Image
-
-pdf = pdfium.PdfDocument("document.pdf")
-
-# 渲染单页
-page = pdf[0]  # 第一页
-bitmap = page.render(
-    scale=2.0,  # 高分辨率
-    rotation=0  # 不旋转
-)
-
-# 转换为 PIL Image
-img = bitmap.to_pil()
-img.save("page_1.png", "PNG")
-
-# 处理多页
-for i, page in enumerate(pdf):
-    bitmap = page.render(scale=1.5)
-    img = bitmap.to_pil()
-    img.save(f"page_{i+1}.jpg", "JPEG", quality=90)
-```
-
-## 命令行工具
-
-### pdftotext (poppler-utils)
-
-> ⚠️ **性能优化**：始终输出到文件，避免占用 token
-
-```bash
-# ✅ 提取文本到文件
-pdftotext input.pdf output.txt
-
-# ✅ 保留布局提取到文件
-pdftotext -layout input.pdf output.txt
-
-# ✅ 提取特定页面到文件
-pdftotext -f 1 -l 5 input.pdf output.txt  # 第1-5页
-
-# ✅ 提取带坐标的文本到 XML 文件（用于结构化数据）
-pdftotext -bbox-layout document.pdf output.xml
-
-# ❌ 避免：不要省略输出文件名（会输出到 stdout）
-# pdftotext input.pdf
-```
-
-### 高级图片转换 (pdftoppm)
-
-```bash
-# 转换为 PNG，指定分辨率
-pdftoppm -png -r 300 document.pdf output_prefix
-
-# 转换特定页面范围，高分辨率
-pdftoppm -png -r 600 -f 1 -l 3 document.pdf high_res_pages
-
-# 转换为 JPEG，指定质量
-pdftoppm -jpeg -jpegopt quality=85 -r 200 document.pdf jpeg_output
-```
-
-### 提取嵌入图片 (pdfimages)
-
-```bash
-# 提取所有图片
-pdfimages -j input.pdf output_prefix
-
-# 列出图片信息（不提取）
-pdfimages -list document.pdf
-
-# 以原始格式提取
-pdfimages -all document.pdf images/img
-```
-
-## OCR 提取（扫描PDF）
-
-```python
-# 需要: pip install pytesseract pdf2image
-import pytesseract
-from pdf2image import convert_from_path
-
-# PDF 转图片
-images = convert_from_path('scanned.pdf')
-
-# OCR 每一页
-text = ""
-for i, image in enumerate(images):
-    text += f"Page {i+1}:\n"
-    text += pytesseract.image_to_string(image)
-    text += "\n\n"
-
-print(text)
-```
-
-## 处理加密 PDF
-
-```python
-from pypdf import PdfReader
-
-try:
-    reader = PdfReader("encrypted.pdf")
-    if reader.is_encrypted:
-        reader.decrypt("password")
-    
-    # 解密后可正常提取文本
-    for page in reader.pages:
-        text = page.extract_text()
-        print(text)
-except Exception as e:
-    print(f"Failed to decrypt: {e}")
-```
-
-```bash
-# 使用 qpdf 解密（需要知道密码）
-qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf
-
-# 检查加密状态
-qpdf --show-encryption encrypted.pdf
-```
-
-## 批量处理
-
-```python
-import os
-import glob
-from pypdf import PdfReader
-import logging
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-def batch_extract_text(input_dir):
-    """批量提取文本"""
-    pdf_files = glob.glob(os.path.join(input_dir, "*.pdf"))
-    
-    for pdf_file in pdf_files:
-        try:
-            reader = PdfReader(pdf_file)
-            text = ""
-            for page in reader.pages:
-                text += page.extract_text()
-            
-            output_file = pdf_file.replace('.pdf', '.txt')
-            with open(output_file, 'w', encoding='utf-8') as f:
-                f.write(text)
-            logger.info(f"Extracted text from: {pdf_file}")
-            
-        except Exception as e:
-            logger.error(f"Failed to extract text from {pdf_file}: {e}")
-            continue
-```
-
-## 性能优化
-
-1. **文件输出优先**：始终将 pdftotext 输出保存到文件，然后用 grep/Read 检索，避免直接输出到终端占用大量 token
-2. **大型PDF**：使用流式方式逐页处理，避免一次性加载整个文件
-3. **文本提取**：`pdftotext` 最快；pdfplumber 适合结构化数据和表格
-4. **图片提取**：`pdfimages` 比渲染页面快得多
-5. **内存管理**：逐页或分块处理大文件
-
-## 快速参考
-
-| 任务 | 最佳工具 | 命令/代码 |
-|------|----------|-----------|
-| 提取文本 | pdfplumber | `page.extract_text()` |
-| 提取表格 | pdfplumber | `page.extract_tables()` |
-| 命令行提取 | pdftotext | `pdftotext -layout input.pdf` |
-| OCR 扫描PDF | pytesseract | 先转图片再OCR |
-| 提取元数据 | pypdf | `reader.metadata` |
-| PDF转图片 | pypdfium2 | `page.render()` |
-
-## 可用包
-
-- **pypdf** - 基本操作（BSD 许可）
-- **pdfplumber** - 文本和表格提取（MIT 许可）
-- **pypdfium2** - 快速渲染和提取（Apache/BSD 许可）
-- **pytesseract** - OCR（Apache 许可）
-- **pdf2image** - PDF转图片
-- **poppler-utils** - 命令行工具（GPL-2 许可）

package/template/.agents/skills/kb-retriever/scripts/convert_pdf_to_images.py

@@ -1,35 +0,0 @@
-import os
-import sys
-
-from pdf2image import convert_from_path
-
-
-# Converts each page of a PDF to a PNG image.
-
-
-def convert(pdf_path, output_dir, max_dim=1000):
-    images = convert_from_path(pdf_path, dpi=200)
-
-    for i, image in enumerate(images):
-        # Scale image if needed to keep width/height under `max_dim`
-        width, height = image.size
-        if width > max_dim or height > max_dim:
-            scale_factor = min(max_dim / width, max_dim / height)
-            new_width = int(width * scale_factor)
-            new_height = int(height * scale_factor)
-            image = image.resize((new_width, new_height))
-        
-        image_path = os.path.join(output_dir, f"page_{i+1}.png")
-        image.save(image_path)
-        print(f"Saved page {i+1} as {image_path} (size: {image.size})")
-
-    print(f"Converted {len(images)} pages to PNG images")
-
-
-if __name__ == "__main__":
-    if len(sys.argv) != 3:
-        print("Usage: convert_pdf_to_images.py [input pdf] [output directory]")
-        sys.exit(1)
-    pdf_path = sys.argv[1]
-    output_directory = sys.argv[2]
-    convert(pdf_path, output_directory)

package/template/.agents/skills/yss-db2mybatis/SKILL.md

@@ -1,94 +0,0 @@
----
-name: yss-db2mybatis
-description: Use when 用于从数据库元数据或 DDL 生成 YSS 风格的 Domain Gateway、PO、Repository、Convertor 和 GatewayImpl。当用户要求按表结构、DDL、metadata 或数据库连接批量生成持久层代码时调用。
----
-
-# yss-db2mybatis
-
-这是一个生成器型 skill。优先复用脚本 `scripts/db2mybatis.py`，不要在对话里手写大段样板代码替代脚本。
-
-## 何时使用
-
-- 用户给出数据库表、DDL、metadata，要求生成 YSS 持久层代码。
-- 用户要求批量生成 `PO / Repository / Convertor / GatewayImpl / Domain Gateway`。
-- 用户要从 MySQL、PostgreSQL、Oracle、OpenGauss、OceanBase 提取元数据。
-- 用户要先从 DDL 离线生成 metadata，再生成代码。
-
-## 不适用
-
-- 复杂 SQL 优化、手写 XML Mapper。
-- 联合主键需要特殊建模且用户未确认策略。
-- 用户只想补某个领域行为，而不是批量落持久层。
-
-## 优先流程
-
-1. 识别输入来源：`metadata.json`、数据库连接、DDL 文件、DDL 文本。
-2. 先执行 `validate` 或 `extract` / `ddl2metadata`，不要直接盲生成。
-3. 生成前优先用 `--dry-run` 预览。
-4. 生成后检查输出路径、命名、主键策略和类型映射。
-5. 如用户要继续补 Domain 或 Web，再衔接 `yss-domain`、`yss-web-controller`。
-
-## 推荐命令
-
-### 从数据库提取 metadata
-
-```bash
-python3 scripts/db2mybatis.py extract \
-  --datasource-config references/datasource-config.example.json \
-  --datasource-name your-datasource \
-  --tables t_example \
-  --output /tmp/metadata.json
-```
-
-### 从 DDL 生成 metadata
-
-```bash
-python3 scripts/db2mybatis.py ddl2metadata \
-  --ddl-file /path/schema.sql \
-  --db-type mysql \
-  --database demo \
-  --output /tmp/metadata.json
-```
-
-### 生成代码
-
-```bash
-python3 scripts/db2mybatis.py scaffold \
-  --skill-root /path/to/.agents/skills/yss-db2mybatis \
-  --metadata-file /tmp/metadata.json \
-  --base-package com.yss.demo \
-  --domain-segment example \
-  --domain-java-root /path/project-domain/src/main/java \
-  --infra-java-root /path/project-infra/src/main/java \
-  --dry-run
-```
-
-## 关键参数
-
-- 表过滤：`--tables`、`--include-tables-regex`、`--exclude-tables-regex`
-- 安全控制：`--dry-run`、`--overwrite`
-- 输入来源：`--metadata-file`、`--ddl-file`、`--ddl-sql`
-- 主键策略：`--pk-strategy error|first`
-- 项目约定：`--convention-file`
-
-## 输出预期
-
-- `domain/{segment}/gateway/*Gateway.java`
-- `repository/entity/*PO.java`
-- `repository/*Repository.java`
-- `repository/convertor/*Convertor.java`
-- `repository/gateway/impl/*GatewayImpl.java`
-
-## 质量要求
-
-- 遇到无法推断的类型时，给出明确告警，不要静默猜测。
-- 联合主键默认报错，除非用户明确接受 `first` 策略。
-- 默认先生成可编译骨架，再由调用方补复杂查询。
-- 输出前检查生成路径是否真的对齐当前工程。
-
-## 按需读取
-
-- 主脚本：`scripts/db2mybatis.py`
-- 类型映射：`references/type-mapping.json`
-- 数据源示例：`references/datasource-config.example.json`
-- 项目约定示例：`references/project-convention.example.json`

package/template/.agents/skills/yss-db2mybatis/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS DB2MyBatis"
-  short_description: "数据库元数据生成 YSS 持久层与代码脚手架落地规范"
-  default_prompt: "Use $yss-db2mybatis to generate YSS domain gateway, repository, convertor, and gateway implementation code from database metadata."

package/template/.agents/skills/yss-db2mybatis/assets/$.java

@@ -1,19 +0,0 @@
-package ${base_package}.repository.entity;
-
-import com.baomidou.mybatisplus.annotation.IdType;
-import com.baomidou.mybatisplus.annotation.TableField;
-import com.baomidou.mybatisplus.annotation.TableId;
-import com.baomidou.mybatisplus.annotation.TableName;
-import lombok.Data;
-import lombok.EqualsAndHashCode;${extra_imports}
-
-/**
- * ${table_comment}
- */
-@Data
-@EqualsAndHashCode
-@TableName("${table_name}")
-public class ${domain_name}PO {
-
-${fields_block}
-}

package/template/.agents/skills/yss-db2mybatis/assets/convertor.java.template

@@ -1,22 +0,0 @@
-package ${base_package}.repository.convertor;
-
-import ${model_pkg}.${domain_name};
-import ${base_package}.repository.entity.${domain_name}PO;
-import org.mapstruct.Mapper;
-import org.mapstruct.NullValueCheckStrategy;
-import org.mapstruct.NullValuePropertyMappingStrategy;
-import org.mapstruct.factory.Mappers;
-
-import java.util.List;
-
-@Mapper(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE, nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS)
-public interface ${domain_name}Convertor {
-
-    ${domain_name}Convertor INSTANCE = Mappers.getMapper(${domain_name}Convertor.class);
-
-    ${domain_name}PO toPO(${domain_name} source);
-
-    ${domain_name} toDomain(${domain_name}PO source);
-
-    List<${domain_name}> toDomainList(List<${domain_name}PO> source);
-}

package/template/.agents/skills/yss-db2mybatis/assets/domain_gateway.java.template

@@ -1,45 +0,0 @@
-package ${gateway_pkg};
-
-import com.yss.cloud.dto.page.PageQuery;
-import com.yss.cloud.dto.result.PageResult;
-import ${model_pkg}.${domain_name};
-
-import java.util.Optional;
-
-public interface ${domain_name}Gateway{
-    /**
-     * Add ${domain_name}
-     *
-     * @param entity entity
-     * @return id
-     */
-    ${pk_java_type} ${method_add}(${domain_name} entity);
-    /**
-     * Update ${domain_name}
-     *
-     * @param entity entity
-     * @return boolean
-     */
-    boolean ${method_update}(${domain_name} entity);
-    /**
-     * Delete ${domain_name}
-     *
-     * @param ${pk_field_name} id
-     * @return boolean
-     */
-    boolean ${method_delete}(${pk_java_type} ${pk_field_name});
-    /**
-     * Get ${domain_name} by id
-     *
-     * @param ${pk_field_name} id
-     * @return optional
-     */
-    Optional<${domain_name}> ${method_get}(${pk_java_type} ${pk_field_name});
-    /**
-      * Page ${domain_name}
-      *
-      * @param query query
-      * @return page result
-      */
-    PageResult<${domain_name}> ${method_page}(PageQuery query);
-}

package/template/.agents/skills/yss-db2mybatis/assets/domain_model.java.template

@@ -1,16 +0,0 @@
-package ${model_pkg};
-
-import lombok.Data;
-import java.io.Serializable;
-${extra_imports}
-
-/**
- * ${table_comment}
- */
-@Data
-public class ${domain_name} implements Serializable {
-
-    private static final long serialVersionUID = 1L;
-
-    ${fields_block}
-}

package/template/.agents/skills/yss-db2mybatis/assets/gateway_impl.java.template

@@ -1,62 +0,0 @@
-package ${base_package}.repository.gateway.impl;
-
-import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
-import com.baomidou.mybatisplus.core.metadata.IPage;
-import com.baomidou.mybatisplus.core.toolkit.Wrappers;
-import com.yss.cloud.dto.page.PageQuery;
-import com.yss.cloud.dto.result.PageResult;
-import ${gateway_pkg}.${domain_name}Gateway;
-import ${model_pkg}.${domain_name};
-import ${base_package}.repository.${domain_name}Repository;
-import ${base_package}.repository.convertor.${domain_name}Convertor;
-import ${base_package}.repository.entity.${domain_name}PO;
-import ${base_package}.repository.util.PageUtil;
-import lombok.RequiredArgsConstructor;
-import org.springframework.stereotype.Repository;
-
-import java.util.List;
-import java.util.Optional;
-import java.util.stream.Collectors;
-
-@Repository
-@RequiredArgsConstructor
-public class ${domain_name}GatewayImpl implements ${domain_name}Gateway {
-
-    private final ${domain_name}Repository ${repository_field_name};
-
-    @Override
-    public ${pk_java_type} ${method_add}(${domain_name} entity) {
-        ${domain_name}PO po = ${domain_name}Convertor.INSTANCE.toPO(entity);
-        ${repository_field_name}.insert(po);
-        //fixme 补充返回数据唯一id
-        return null;
-    }
-
-    @Override
-    public boolean ${method_update}(${domain_name} entity) {
-        return ${repository_field_name}.updateById(${domain_name}Convertor.INSTANCE.toPO(entity)) > 0;
-    }
-
-    @Override
-    public boolean ${method_delete}(${pk_java_type} ${pk_field_name}) {
-        return ${repository_field_name}.deleteById(${pk_field_name}) > 0;
-    }
-
-    @Override
-    public Optional<${domain_name}> ${method_get}(${pk_java_type} ${pk_field_name}) {
-        return Optional.ofNullable(${repository_field_name}.selectById(${pk_field_name})).map(this::toDomain);
-    }
-
-    @Override
-    public PageResult<${domain_name}> ${method_page}(PageQuery query) {
-        LambdaQueryWrapper<${domain_name}PO> wrapper = Wrappers.lambdaQuery(${domain_name}PO.class);
-        ${logic_delete_condition}
-        IPage<${domain_name}PO> result = ${repository_field_name}.selectPage(PageUtil.page(query), wrapper);
-        List<${domain_name}> records = result.getRecords().stream().map(this::toDomain).collect(Collectors.toList());
-        return PageResult.of(records, result.getTotal(), result.getSize(), result.getCurrent());
-    }
-
-    private ${domain_name} toDomain(${domain_name}PO source) {
-        return ${domain_name}Convertor.INSTANCE.toDomain(source);
-    }
-}

package/template/.agents/skills/yss-db2mybatis/assets/po.java.template

@@ -1,18 +0,0 @@
-package ${base_package}.repository.entity;
-
-import com.baomidou.mybatisplus.annotation.IdType;
-import com.baomidou.mybatisplus.annotation.TableField;
-import com.baomidou.mybatisplus.annotation.TableId;
-import com.baomidou.mybatisplus.annotation.TableName;
-import lombok.Data;
-import lombok.EqualsAndHashCode;${extra_imports}
-
-/**
- * ${table_comment}
- */
-@Data
-@EqualsAndHashCode
-@TableName("${table_name}")
-public class ${domain_name}PO {
-    ${fields_block}
-}

package/template/.agents/skills/yss-db2mybatis/assets/repository.java.template

@@ -1,7 +0,0 @@
-package ${base_package}.repository;
-
-import com.yss.cloud.mybatis.support.BasePlusRepository;
-import ${base_package}.repository.entity.${domain_name}PO;
-
-public interface ${domain_name}Repository extends BasePlusRepository<${domain_name}PO> {
-}