manticore-smash 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29580da30a959d15d5ef119e83fb2062048515c86697f0a8b71a93e0f9ee3d18
-  data.tar.gz: 8b645dc02c6033d3a5bd44b9c4fb6b2f06748d22d9f161d400b96a57bcb6c442
+  metadata.gz: 4a1adfe6302e580436ab9ce4425c4eee450e50fd0b829860b18a8502df43840d
+  data.tar.gz: 1c222464dad90eb28cbd74949df88cb7b4b42c65be7cb3ace2195002121f041c
 SHA512:
-  metadata.gz: b60bf3812bc5452b59ad2824b4bbdc337a2b68d53667f3bc52d6d65127ab9f094d9801256481c95072147b675cc8d7d324f95469041089bfc6f94ebc1eff239a
-  data.tar.gz: ab2fbead94ec9cdd23e52d266d6f96ef45da5a4587cc7719aa37a2d457eae9a4e620db06f159120c500dcf873aa531bcd56c9021d7bd224c8f63afb129e6440e
+  metadata.gz: 3fdbce329abcf80d3795d962c5312a8f2cd7c9600a0c6f551fd189c526c578ebccfc3d6954e0e9f20c9f68ebe8d2630ea0559b7ae648667bbdf1e6f20a45cc3a
+  data.tar.gz: ae7f9b786e93314e26d2cb28da19c3fcf62732ce4da51d07c1303a8343c663c7dead2b08afb9d01772e5dcad82a8574d7b561d4c976c75e14a4e57bad3e1dfd6

data/README.md

@@ -1,3 +1,14 @@
+---
+AIGC:
+  ContentProducer: '001191110102MAD55U9H0F10002'
+  ContentPropagator: '001191110102MAD55U9H0F10002'
+  Label: '1'
+  ProduceID: 'd7d40ab1-e86f-427d-ba43-66c531be8265'
+  PropagateID: 'd7d40ab1-e86f-427d-ba43-66c531be8265'
+  ReservedCode1: '985db124-2271-48a4-9961-4dfea044cd2d'
+  ReservedCode2: '985db124-2271-48a4-9961-4dfea044cd2d'
+---
+
 # Manticore 
 
 ## XMLUtils Ruby XML 工具库（REXML 精简重写版）
@@ -55,9 +66,14 @@ lib/
 │   ├── xpath.rb             # XPath 简化查询引擎
 │   ├── formatters.rb        # 序列化与格式化输出
 │   └── xml_doc.rb           # 模型转换：XmlUtils DOM → XmlNode 
+├── xlsxkit/
+│   ├── zip_reader.rb        # 纯 Ruby ZIP32 读取器
+│   ├── sax_parser.rb        # SAX 流式 XML 解析器
+│   └── workbook.rb          # XLSX Workbook 高层 API
 ├── test/
 │   ├── xml_doc_test.rb      # xml_doc测试用例
-│   └── xmlutils_test.rb     # xmlutils测试用例
+│   ├── xmlutils_test.rb     # xmlutils测试用例
+│   └── xlsxkit_test.rb      # xlsxkit测试用例
 ├── manticore.gemspec        # Gem 打包配置
 ├── LICENSE                  # GNU AGPL-3.0 许可证
 └── README.md
@@ -202,7 +218,7 @@ Node
 
 ```bash
 gem build manticore.gemspec
-gem install --local manticore-3.0.0.gem
+gem install --local manticore-smash-3.0.0.gem
 ```
 
 测试脚本覆盖以下场景：
@@ -277,8 +293,169 @@ p node.to_triad, node.to_obj
 
 ---
 
+## XlsxKit — 纯 Ruby XLSX 读取器（零第三方依赖）
+
+`xlsxkit` 是 XLSX（Office Open XML Spreadsheet）读取组件，提供流式读取与多格式输出，不依赖 rubyzip、roo、creek 等第三方 gem。
+
+### 设计目标
+
+- **零依赖**：纯 Ruby 实现 ZIP32 解包 + SAX 流式 XML 解析，无需安装任何 gem。
+- **流式读取**：SAX 风格逐行处理，内存占用恒定，适合大文件（>100MB）。
+- **多格式输出**：原生 Ruby 二维数组、JSON 字符串/文件、CSV 字符串/文件。
+- **稀疏单元格补齐**：根据 `r` 属性（如 `A1`、`C1`）自动补齐缺失列为 `nil`。
+
+### 文件结构
+
+```
+lib/
+├── xlsxkit/
+│   ├── zip_reader.rb          # 纯 Ruby ZIP32 读取器（DEFLATE / STORED）
+│   ├── sax_parser.rb          # SAX 流式 XML 解析器（增量缓冲，64KB 块读取）
+│   └── workbook.rb            # Workbook 高层 API（read_rows / to_a / to_json / to_csv）
+├── test/
+│   └── xlsxkit_test.rb        # 测试套件（15 用例，含 XLSX 生成辅助方法）
+└── manticore.rb               # 统一入口，require 'manticore' 自动加载
+```
+
+### 架构原理
+
+```
+XLSX 文件（ZIP 容器）
+    │
+    ▼
+┌─────────────────┐
+│  ZipReader       │  ← 按需读取单个 ZIP 条目，不全量解包
+│  (ZIP32 读取器)  │     支持 DEFLATE (method 8) 与 STORED (method 0)
+└─────────────────┘
+    │
+    ▼
+┌─────────────────┐
+│  SAXParser       │  ← 流式 XML 解析，增量缓冲，不构建 DOM 树
+│  (SAX 解析器)    │     64KB 块读取，内存占用恒定
+└─────────────────┘
+    │
+    ▼
+┌─────────────────┐
+│  Workbook        │  ← 高层 API：Sheet 选择、Shared Strings 缓存
+│  (工作簿 API)    │     行回调 → 数组 / JSON / CSV 输出
+└─────────────────┘
+```
+
+### 核心实现要点
+
+#### 1. ZipReader（ZIP32 读取器）
+
+- 从文件末尾反向搜索 EOCD（End of Central Directory）签名，定位中央目录。
+- 解析中央目录条目，获取每个文件的元数据（压缩方式、大小、Local Header 偏移）。
+- 按需读取单个条目：定位 Local Header → 跳过头部 → Zlib::Inflate 解压。
+- 与全量解包不同，仅按 name 读取所需条目，避免将整个 ZIP 展开到内存或磁盘。
+
+#### 2. SAXParser（流式 XML 解析器）
+
+- 基于增量缓冲的 SAX 解析器，不构建完整 DOM 树。
+- 64KB 块读取，逐标签回调 `start_element` / `characters` / `end_element`。
+- 支持标签属性解析、自闭合标签、CDATA 区段、实体引用展开。
+- 内存占用恒定，适合大 XML 文件（如 >50MB 的 sheet 数据）。
+
+#### 3. Workbook（高层 API）
+
+- **Sheet 解析**：从 `xl/workbook.xml` 提取 sheet 名称列表，通过 `xl/_rels/workbook.xml.rels` 映射 rId → 文件路径。
+- **Shared Strings 缓存**：首次访问时加载 `xl/sharedStrings.xml`，后续复用。
+- **行处理**：SAX 回调驱动，每行输出为一个数组。根据单元格引用（`r` 属性如 `A1`、`C1`）自动补齐缺失列为 `nil`。
+- **数据类型**：支持 shared string（`t="s"`）、inline string（`t="inlineStr"`）、boolean（`t="b"`）、error（`t="e"`）、formula string（`t="str"`）、数值（默认）。
+
+### 使用示例
 
-## ReDiscount Markdown 解析器（rdiscount API 兼容层）
+#### 基础读取
+
+```ruby
+require 'manticore'
+
+wb = XlsxKit::Workbook.open('data.xlsx')
+
+# 获取所有 sheet 名称
+puts wb.sheet_names  # => ["Sheet1", "Sheet2"]
+
+# 流式逐行读取
+wb.read_rows('Sheet1') do |row|
+  puts row.inspect  # => ["Alice", 30, nil, "alice@example.com"]
+end
+
+# 读取全部到数组
+rows = wb.to_a('Sheet1')  # => [["Name", "Age"], ["Alice", 30], ...]
+```
+
+#### JSON / CSV 输出
+
+```ruby
+wb = XlsxKit::Workbook.open('data.xlsx')
+
+# JSON 字符串
+json = wb.to_json('Sheet1', pretty: true)
+
+# JSON 文件
+wb.to_json_file('output.json', 'Sheet1')
+
+# CSV 字符串
+csv = wb.to_csv('Sheet1')
+
+# CSV 文件（流式写入，适合大数据量）
+wb.to_csv_file('output.csv', 'Sheet1')
+```
+
+#### Headers 模式（首行作为表头）
+
+```ruby
+wb = XlsxKit::Workbook.open('data.xlsx')
+
+# read_rows + headers: 每行返回 Hash
+wb.read_rows(0, headers: true) do |row|
+  puts row  # => {"Name"=>"Alice", "Age"=>30}
+end
+
+# to_a + headers: 返回 Hash 数组
+data = wb.to_a(0, headers: true)  # => [{"Name"=>"Alice", "Age"=>30}, ...]
+
+# to_json + headers: 输出 JSON 对象数组
+json = wb.to_json(0, headers: true)
+# => [{"Name":"Alice","Age":30}, {"Name":"Bob","Age":25}]
+```
+
+#### Sheet 选择
+
+```ruby
+wb = XlsxKit::Workbook.open('data.xlsx')
+
+# 按名称选择
+wb.read_rows('Sheet2') { |row| ... }
+
+# 按序号选择（0-based）
+wb.read_rows(1) { |row| ... }  # 第二个 sheet
+
+# 默认选择第一个 sheet
+wb.read_rows { |row| ... }
+```
+
+### 测试
+
+```bash
+ruby -I lib test/xlsxkit_test.rb
+```
+
+测试套件覆盖 15 个用例：
+
+1. 基础读取（字符串、数值）
+2. 多 sheet 选择（按名称、按序号）
+3. 共享字符串与内联字符串
+4. 布尔值与错误值
+5. 特殊字符（引号、换行、Unicode）
+6. 稀疏单元格（空列补 nil）
+7. Headers 模式
+8. JSON / CSV 输出
+9. 大文件流式读取
+
+
+---## ReDiscount Markdown 解析器（rdiscount API 兼容层）
 
 `mdutils/rediscount` 是 Markdown 处理组件，提供 Markdown → HTML 文档解析转换，完全兼容 `rdiscount` Gem 的 API 接口，无需编译 C 扩展即可在任何 Ruby 3.0+ 环境中运行。
 
@@ -488,5 +665,4 @@ ruby -I lib test/mdutils_test.rb
 - 若未安装，则跳过比对测试，仅运行纯 Ruby 断言。
 
 
----
-
+---

data/lib/manticore.rb

@@ -22,3 +22,6 @@ require_relative 'xmlutils/xpath'
 require_relative 'xmlutils/formatters'
 require_relative 'xmlutils/xml_doc'
 require_relative 'mdutils/rediscount'
+require_relative 'xlsxkit/zip_reader'
+require_relative 'xlsxkit/sax_parser'
+require_relative 'xlsxkit/workbook'

data/lib/xlsxkit/sax_parser.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: false
+
+# Copyright (C) 2024 Manticore Authors
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+require 'stringio'
+
+module XlsxKit
+  ##
+  # 轻量 SAX 风格 XML 解析器，专为 XLSX 内部 XML 流式处理设计。
+  #
+  # 与 XmlUtils::TreeParser（DOM 全量建树）不同，本解析器不在内存中构建节点树，
+  # 而是逐标签触发回调（start_element / end_element / characters），内存占用恒定。
+  #
+  # 核心算法：增量缓冲 — 每次从 IO 读取一块数据追加到 @buf，
+  # 尝试提取已完整的标签/文本段并回调，不完整的尾部保留到下次。
+  # 这样即使数百 MB 的 sheet XML 也只占用几十 KB 内存。
+  #
+  # Handler 协议（鸭子类型，无需继承）：
+  #   start_element(name, attrs)   — 遇到开始标签
+  #   end_element(name)            — 遇到结束标签
+  #   characters(text)             — 遇到文本内容（可能分多次回调）
+
+  class SAXParser
+    BUFFER_SIZE = 65536  # 64KB 读取块
+
+    def self.parse(source, handler)
+      new(source, handler).parse
+    end
+
+    def initialize(source, handler)
+      @source  = source
+      @handler = handler
+      @buf     = ''.b
+      @eof     = false
+      @i       = 0  # 已消费位置
+    end
+
+    def parse
+      until @eof && @i >= @buf.length
+        fill_buffer if !@eof && (@buf.length - @i) < BUFFER_SIZE
+        step || (@eof = true)
+      end
+      # 尾部残余文本
+      if @i < @buf.length
+        text = @buf[@i..]
+        emit_text(text) unless text.strip.empty?
+      end
+    end
+
+    private
+
+    def fill_buffer
+      chunk = @source.read(BUFFER_SIZE)
+      if chunk && !chunk.empty?
+        @buf << chunk
+      else
+        @eof = true
+      end
+    end
+
+    ##
+    # 尝试从 @buf 的 @i 位置提取一个完整元素（文本段或标签），
+    # 成功返回 true（已消费），失败返回 nil（需要更多数据）。
+    def step
+      return nil if @i >= @buf.length
+
+      lt = @buf.index('<', @i)
+
+      # --- 情况一：当前位置是 '<'，解析标签 ---
+      if @i == lt
+        parse_tag
+      # --- 情况二：有 '<' 在前方，先处理文本 ---
+      elsif lt
+        text = @buf[@i...lt]
+        @i = lt
+        emit_text(text) unless text.strip.empty?
+        true  # 文本已消费，下次循环处理标签
+      # --- 情况三：无 '<'，整个缓冲区都是文本（或已到 EOF）---
+      else
+        if @eof
+          text = @buf[@i..]
+          @i = @buf.length
+          emit_text(text) unless text.strip.empty?
+          true
+        else
+          # 留最后 1 字节（可能是 '<' 的一半... 虽然不会发生），等下次
+          nil
+        end
+      end
+    end
+
+    #---------------------------------------------------------------------------
+    # 标签解析
+    #---------------------------------------------------------------------------
+
+    def parse_tag
+      # 确保 '>' 存在
+      return nil unless ensure_char('>')
+
+      ch = @buf[@i + 1]
+
+      case ch
+      when '!'
+        parse_special
+      when '?'
+        parse_pi
+      when '/'
+        parse_end_tag
+      else
+        parse_start_tag
+      end
+    end
+
+    def parse_start_tag
+      # 注意：属性值中可能包含 '>'，因此需逐字符扫描，跳过引号区域
+      gt_pos = find_tag_end(@i)
+      return nil unless gt_pos
+
+      raw = @buf[(@i + 1)...gt_pos]
+      @i = gt_pos + 1
+
+      self_closing = raw.end_with?('/')
+      raw = raw[0..-2] if self_closing
+
+      name, attrs = extract_name_and_attrs(raw)
+      @handler.start_element(name, attrs) if @handler.respond_to?(:start_element)
+      @handler.end_element(name) if self_closing && @handler.respond_to?(:end_element)
+
+      true
+    end
+
+    def parse_end_tag
+      gt_pos = @buf.index('>', @i)
+      return nil unless gt_pos
+
+      name = @buf[(@i + 2)...gt_pos].strip
+      @i = gt_pos + 1
+      @handler.end_element(name) if @handler.respond_to?(:end_element)
+      true
+    end
+
+    def parse_special
+      # <!-- comment --> 或 <![CDATA[ ... ]]>
+      if @buf[(@i + 2), 2] == '--'
+        end_idx = @buf.index('-->', @i)
+        return nil unless end_idx
+        @i = end_idx + 3
+      elsif @buf[(@i + 2), 7] == '[CDATA['
+        end_idx = @buf.index(']]>', @i)
+        return nil unless end_idx
+
+        data = @buf[(@i + 9)...end_idx]
+        emit_text(data)
+        @i = end_idx + 3
+      else
+        gt_pos = @buf.index('>', @i)
+        return nil unless gt_pos
+        @i = gt_pos + 1
+      end
+      true
+    end
+
+    def parse_pi
+      close = @buf.index('?>', @i)
+      if close
+        @i = close + 2
+      else
+        gt_pos = @buf.index('>', @i)
+        return nil unless gt_pos
+        @i = gt_pos + 1
+      end
+      true
+    end
+
+    #---------------------------------------------------------------------------
+    # 辅助：标签内扫描（跳过引号区域内的 '>'）
+    #---------------------------------------------------------------------------
+
+    def find_tag_end(start)
+      i = start + 1
+      in_quote = nil
+
+      while i < @buf.length
+        ch = @buf[i]
+
+        if in_quote
+          i += 1
+          in_quote = nil if ch == in_quote
+        elsif ch == '"' || ch == "'"
+          in_quote = ch
+          i += 1
+        elsif ch == '>'
+          return i
+        else
+          i += 1
+        end
+      end
+
+      # 未找到 '>'
+      nil
+    end
+
+    def ensure_char(target)
+      @buf.index(target, @i) ? true : false
+    end
+
+    def extract_name_and_attrs(raw)
+      # raw 形如: 'c r="A1" t="s"' 或 'c r="A1"/'
+      i = 0
+      i += 1 while raw[i] && raw[i] =~ /[A-Za-z0-9_:.\-]/
+      name = raw[0...i]
+
+      attrs = {}
+      while i < raw.length
+        i += 1 while raw[i] =~ /\s/
+        break if i >= raw.length
+
+        # 属性名
+        nstart = i
+        i += 1 while raw[i] && raw[i] !~ /[\s=\/]/
+        aname = raw[nstart...i]
+
+        # 跳过空格
+        i += 1 while raw[i] =~ /\s/
+
+        if raw[i] == '='
+          i += 1
+          i += 1 while raw[i] =~ /\s/
+          quote = raw[i]
+          if quote == '"' || quote == "'"
+            i += 1
+            vend = raw.index(quote, i)
+            attrs[aname] = unescape(raw[i...vend])
+            i = vend + 1
+          else
+            vstart = i
+            i += 1 while raw[i] && raw[i] !~ /[\s\/]/
+            attrs[aname] = raw[vstart...i]
+          end
+        else
+          attrs[aname] = nil
+        end
+      end
+
+      [name, attrs]
+    end
+
+    #---------------------------------------------------------------------------
+    # 实体反转义
+    #---------------------------------------------------------------------------
+
+    ENTITY_MAP = {
+      'amp'  => '&',
+      'lt'   => '<',
+      'gt'   => '>',
+      'quot' => '"',
+      'apos' => "'"
+    }.freeze
+
+    def emit_text(text)
+      decoded = unescape(text)
+      @handler.characters(decoded) if @handler.respond_to?(:characters)
+    end
+
+    def unescape(str)
+      return '' if str.nil? || str.empty?
+      str = str.dup.force_encoding('UTF-8')
+      str.gsub!(/&(amp|lt|gt|quot|apos|#\d+|#x[0-9A-Fa-f]+);/) do
+        m = $1
+        if m.start_with?('#x')
+          [m[2..].to_i(16)].pack('U')
+        elsif m.start_with?('#')
+          [m[1..].to_i].pack('U')
+        else
+          ENTITY_MAP[m] || "&#{m};"
+        end
+      end
+      str
+    end
+  end
+end

data/lib/xlsxkit/workbook.rb

@@ -0,0 +1,427 @@
+# frozen_string_literal: false
+
+# Copyright (C) 2024 Manticore Authors
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+require 'json'
+require 'stringio'
+require_relative 'zip_reader'
+require_relative 'sax_parser'
+
+module XlsxKit
+  ##
+  # XLSX Workbook 高层 API
+  #
+  # 用法：
+  #   wb = XlsxKit::Workbook.open('data.xlsx')
+  #   wb.sheet_names       # => ["Sheet1", "Sheet2"]
+  #   wb.read_rows('Sheet1') do |row|
+  #     puts row.inspect   # ["A1值", "B1值", ...]
+  #   end
+  #   wb.to_json('Sheet1') # => JSON 字符串
+  #   wb.to_a('Sheet1')    # => [[...], [...], ...] 原生 Ruby 数组
+  #
+
+  class Workbook
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+      @shared_strings = nil
+    end
+
+    def self.open(path)
+      wb = new(path)
+      yield wb if block_given?
+      wb
+    end
+
+    ##
+    # 返回所有 sheet 名称。
+    def sheet_names
+      @sheet_names ||= parse_workbook
+    end
+
+    ##
+    # 流式读取指定 sheet，逐行 yield。
+    #
+    # @param name [String, Integer] sheet 名称或序号（0-based）
+    # @param headers [Boolean] 第一行作为表头（返回 Hash 行）
+    # @yield [Array<value> 或 Hash] 数据行
+    def read_rows(name = 0, headers: false)
+      target = resolve_sheet(name)
+      return enum_for(:read_rows, name, headers: headers) unless block_given?
+
+      header_row = nil
+      row_handler = SheetRowHandler.new(load_shared_strings)
+
+      # 第一次扫描：解析 xml，逐行回调
+      ZipReader.open(@path) do |zip|
+        xml = zip.read_entry_utf8(target[:path])
+        return unless xml
+
+        io = StringIO.new(xml)
+        SAXParser.parse(io, row_handler)
+      end
+
+      rows = row_handler.rows
+      if headers && !rows.empty?
+        header_row = rows.first
+        rows[1..].each do |row|
+          yield hashify(header_row, row)
+        end
+      else
+        rows.each { |row| yield row }
+      end
+    end
+
+    ##
+    # 读取全部数据到原生 Ruby 二维数组。
+    def to_a(name = 0, headers: false)
+      rows = read_rows(name).to_a
+      return rows unless headers && rows.size > 1
+
+      header_row = rows.first
+      rows[1..].map { |row| hashify(header_row, row) }
+    end
+
+    ##
+    # 读取并转为 JSON 字符串。
+    def to_json(name = 0, headers: false, pretty: false)
+      data = to_a(name, headers: headers)
+      pretty ? JSON.pretty_generate(data) : JSON.generate(data)
+    end
+
+    ##
+    # 读取并写入 JSON 文件。
+    def to_json_file(path, name = 0, headers: false, pretty: false)
+      json = to_json(name, headers: headers, pretty: pretty)
+      File.write(path, json)
+    end
+
+    #---------------------------------------------------------------------------
+    # CSV 输出
+    #---------------------------------------------------------------------------
+
+    ##
+    # 读取并转为 CSV 字符串。
+    def to_csv(name = 0, headers: false)
+      out = +''
+      first = true
+      read_rows(name) do |row|
+        if headers && first
+          first = false
+          next
+        end
+        out << row.map { |c| csv_escape(c) }.join(',') << "\n"
+      end
+      out
+    end
+
+    ##
+    # 逐行生成 CSV（流式，适合大数据量直接写文件）。
+    def to_csv_file(path, name = 0, headers: false)
+      File.open(path, 'w:UTF-8') do |f|
+        first = true
+        read_rows(name) do |row|
+          if headers && first
+            first = false
+            next
+          end
+          f.puts(row.map { |c| csv_escape(c) }.join(','))
+        end
+      end
+    end
+
+    private
+
+    #---------------------------------------------------------------------------
+    # Workbook XML 解析：提取 sheet 名称与文件路径
+    #---------------------------------------------------------------------------
+
+    def parse_workbook
+      names = []
+      ZipReader.open(@path) do |zip|
+        wb_xml = zip.read_entry_utf8('xl/workbook.xml')
+        return names unless wb_xml
+
+        handler = WorkbookHandler.new
+        SAXParser.parse(StringIO.new(wb_xml), handler)
+        names = handler.sheets
+
+        # 解析 rels 映射 rId → target
+        rels_xml = zip.read_entry_utf8('xl/_rels/workbook.xml.rels')
+        if rels_xml
+          rels_handler = RelsHandler.new
+          SAXParser.parse(StringIO.new(rels_xml), rels_handler)
+          @rels = rels_handler.rels
+        end
+      end
+
+      # 将 rId 映射为实际路径
+      @sheet_info = names.map do |name, rid|
+        target = @rels[rid]
+        path = target ? "xl/#{target}" : "xl/worksheets/sheet#{names.index([name, rid]) + 1}.xml"
+        { name: name, path: path }
+      end
+
+      @sheet_info.map { |s| s[:name] }
+    end
+
+    def resolve_sheet(name)
+      sheet_names if @sheet_info.nil?
+      case name
+      when Integer
+        @sheet_info[name]
+      when String
+        @sheet_info.find { |s| s[:name] == name }
+      else
+        raise ArgumentError, "sheet name must be String or Integer"
+      end
+    end
+
+    #---------------------------------------------------------------------------
+    # Shared Strings 解析
+    #---------------------------------------------------------------------------
+
+    def load_shared_strings
+      return @shared_strings if @shared_strings
+
+      @shared_strings = []
+      ZipReader.open(@path) do |zip|
+        xml = zip.read_entry_utf8('xl/sharedStrings.xml')
+        return @shared_strings unless xml
+
+        handler = SharedStringsHandler.new
+        SAXParser.parse(StringIO.new(xml), handler)
+        @shared_strings = handler.strings
+      end
+      @shared_strings
+    end
+
+    #---------------------------------------------------------------------------
+    # 辅助方法
+    #---------------------------------------------------------------------------
+
+    def hashify(header_row, row)
+      hash = {}
+      header_row.each_with_index do |key, i|
+        hash[key] = row[i]
+      end
+      hash
+    end
+
+    def csv_escape(val)
+      return '' if val.nil?
+      s = val.to_s
+      if s.include?(',') || s.include?('"') || s.include?("\n")
+        '"' + s.gsub('"', '""') + '"'
+      else
+        s
+      end
+    end
+
+    #---------------------------------------------------------------------------
+    # Workbook XML SAX Handler
+    #---------------------------------------------------------------------------
+
+    class WorkbookHandler
+      attr_reader :sheets
+
+      def initialize
+        @sheets = []
+        @in_sheet = false
+      end
+
+      def start_element(name, attrs)
+        if name == 'sheet'
+          @sheets << [attrs['name'], attrs['r:id'] || attrs['id']]
+        end
+      end
+
+      def end_element(name); end
+      def characters(text); end
+    end
+
+    #---------------------------------------------------------------------------
+    # Rels XML SAX Handler
+    #---------------------------------------------------------------------------
+
+    class RelsHandler
+      attr_reader :rels
+
+      def initialize
+        @rels = {}
+      end
+
+      def start_element(name, attrs)
+        if name == 'Relationship'
+          @rels[attrs['Id']] = attrs['Target']
+        end
+      end
+
+      def end_element(name); end
+      def characters(text); end
+    end
+
+    #---------------------------------------------------------------------------
+    # Shared Strings SAX Handler
+    #---------------------------------------------------------------------------
+
+    class SharedStringsHandler
+      attr_reader :strings
+
+      def initialize
+        @strings = []
+        @in_si = false
+        @in_t  = false
+        @chars = nil
+      end
+
+      def start_element(name, attrs)
+        case name
+        when 'si' then @in_si = true; @chars = +''
+        when 't'  then @in_t = true
+        end
+      end
+
+      def characters(text)
+        @chars << text if @in_si && @in_t
+      end
+
+      def end_element(name)
+        case name
+        when 'si'
+          @strings << (@chars || '')
+          @in_si = false
+          @chars = nil
+        when 't'
+          @in_t = false
+        end
+      end
+    end
+
+    #---------------------------------------------------------------------------
+    # Sheet Row SAX Handler
+    #
+    # 解析 <sheetData> 下的 <row> → <c> → <v>/<is><t> 结构，
+    # 将每行的单元格值提取为数组，逐行收集。
+    #---------------------------------------------------------------------------
+
+    class SheetRowHandler
+      attr_reader :rows
+
+      def initialize(shared_strings)
+        @sst = shared_strings
+        @rows = []
+        @in_row = false
+        @in_cell = false
+        @in_v = false
+        @in_is = false
+        @in_is_t = false
+        @cell_type = nil
+        @cell_ref = nil
+        @chars = nil
+        @current_row = nil
+      end
+
+      def start_element(name, attrs)
+        case name
+        when 'row'
+          @in_row = true
+          @current_row = []
+        when 'c'
+          @in_cell = true
+          @cell_type = attrs['t']
+          @cell_ref = attrs['r']
+          @chars = +''
+        when 'v'
+          @in_v = true
+        when 'is'
+          @in_is = true
+        when 't'
+          @in_is_t = true if @in_is
+        end
+      end
+
+      def characters(text)
+        @chars << text if @in_cell && (@in_v || (@in_is && @in_is_t))
+      end
+
+      def end_element(name)
+        case name
+        when 'row'
+          @rows << @current_row
+          @in_row = false
+          @current_row = nil
+        when 'c'
+          val = resolve_cell_value
+          if @cell_ref
+            col = col_ref_to_index(@cell_ref)
+            @current_row.fill(nil, @current_row.length...col) if col > @current_row.length
+            @current_row[col] = val
+          else
+            @current_row << val
+          end
+          @in_cell = false
+          @cell_type = nil
+          @cell_ref = nil
+          @chars = nil
+        when 'v'
+          @in_v = false
+        when 'is'
+          @in_is = false
+        when 't'
+          @in_is_t = false if @in_is
+        end
+      end
+
+      private
+
+      def resolve_cell_value
+        raw = @chars ? @chars.strip : ''
+        return nil if raw.empty?
+
+        case @cell_type
+        when 's'        # shared string
+          idx = raw.to_i
+          @sst[idx] || nil
+        when 'str'       # formula string
+          raw
+        when 'inlineStr' # inline string
+          raw
+        when 'b'         # boolean
+          raw == '1'
+        when 'e'         # error
+          raw
+        else             # numeric
+          num?(raw) ? raw.to_f : raw
+        end
+      end
+
+      # "A1" → 0, "B3" → 1, "AA1" → 26
+      def col_ref_to_index(ref)
+        letters = ref[/^[A-Z]+/]
+        col = 0
+        letters.each_byte { |b| col = col * 26 + (b - 64) }
+        col - 1
+      end
+
+      def num?(s)
+        s =~ /^-?\d+(\.\d+)?(e[+-]?\d+)?$/i
+      end
+    end
+  end
+end

data/lib/xlsxkit/zip_reader.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: false
+
+# Copyright (C) 2024 Manticore Authors
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+require 'stringio'
+require 'zlib'
+
+module XlsxKit
+  ##
+  # 最小化 ZIP32 读取器，专为 XLSX 解包设计。
+  #
+  # 不依赖 rubyzip 等第三方 gem，仅支持 XLSX 中出现的两种压缩方式：
+  #   - DEFLATE (method 8): 通用压缩
+  #   - STORED  (method 0):  无压缩
+  #
+  # 实现思路：
+  #   1. 从文件末尾反向搜索 EOCD (End of Central Directory) 签名
+  #   2. 解析中央目录，获取所有条目的元数据与 Local Header 偏移
+  #   3. 按需读取单个条目：定位 Local Header → 跳过头部 → Zlib::Inflate 解压
+  #
+  # 与全量解包不同，本 reader 仅按 name 读取单个条目，避免将整个 ZIP 展开到内存或磁盘。
+
+  class ZipReader
+    # ZIP 格式签名（freeze 防止外部 << 修改）
+    EOCD_SIG     = "PK\x05\x06".b.freeze   # End of Central Directory
+    CDENTRY_SIG  = "PK\x01\x02".b.freeze   # Central Directory File Header
+    LOCAL_SIG    = "PK\x03\x04".b.freeze   # Local File Header
+
+    # 压缩方法
+    STORED  = 0
+    DEFLATE = 8
+
+    attr_reader :entries
+
+    ##
+    # 初始化 ZIP 读取器。
+    #
+    # @param io [IO, String] 文件路径或已打开的 IO（必须可 seek）
+    def initialize(io)
+      @io = io.is_a?(String) ? File.open(io, 'rb') : io
+      @entries = nil
+    end
+
+    ##
+    # 便捷类方法：打开文件并读取后关闭。
+    def self.open(path)
+      reader = new(path)
+      yield reader
+    ensure
+      reader&.close
+    end
+
+    ##
+    # 关闭底层 IO（若由本类打开）。
+    def close
+      @io.close unless @io.closed?
+    end
+
+    ##
+    # 解析中央目录，返回 {name => entry} 的 Hash。
+    # entry 为包含 :name, :method, :compressed_size, :uncompressed_size, :local_offset 的 Hash。
+    def entries
+      return @entries if @entries
+
+      offset = find_eocd
+      @io.seek(offset)
+      sig = @io.read(4)
+      raise "EOCD signature not found" unless sig == EOCD_SIG
+
+      _disk_num, _ent_disk, _ent_here, total_ent,
+        _cd_size, cd_offset = @io.read(16).unpack('vvvvVV')
+
+      @io.seek(cd_offset)
+      @entries = {}
+
+      total_ent.times do
+        sig = @io.read(4)
+        break unless sig == CDENTRY_SIG
+
+        _ver_made, _ver_need, _flags, method,
+          _mtime, _mdate, crc32, comp_size, uncomp_size,
+          name_len, extra_len, comm_len,
+          _disk, _iattr, _eattr, local_offset = @io.read(42).unpack('vvvvvvVVVvvvvvVV')
+
+        name = @io.read(name_len).force_encoding('UTF-8')
+        @io.read(extra_len + comm_len)  # 跳过 extra field 与 comment
+
+        @entries[name] = {
+          name: name,
+          method: method,
+          compressed_size: comp_size,
+          uncompressed_size: uncomp_size,
+          crc32: crc32,
+          local_offset: local_offset
+        }
+      end
+
+      @entries
+    end
+
+    ##
+    # 读取指定条目的原始字节（已解压）。
+    #
+    # @param name [String] 条目名（如 "xl/sharedStrings.xml"）
+    # @return [String, nil] 二进制内容；条目不存在时返回 nil
+    def read_entry(name)
+      entry = entries[name]
+      return nil unless entry
+
+      data_offset = resolve_data_offset(entry[:local_offset])
+      @io.seek(data_offset)
+      raw = @io.read(entry[:compressed_size])
+
+      case entry[:method]
+      when STORED
+        raw
+      when DEFLATE
+        Zlib::Inflate.new(-Zlib::MAX_WBITS).inflate(raw)
+      else
+        raise "Unsupported compression method: #{entry[:method]}"
+      end
+    end
+
+    ##
+    # 读取指定条目并强制 UTF-8 编码（用于 XML 文本）。
+    def read_entry_utf8(name)
+      data = read_entry(name)
+      return nil unless data
+      data.force_encoding('UTF-8')
+    end
+
+    private
+
+    ##
+    # 从文件末尾反向搜索 EOCD 签名。
+    # EOCD 最小 22 字节，最大 22 + 65535（comment 区段），从尾部向前扫。
+    def find_eocd
+      size = @io.size
+      scan_size = [size, 65557].min  # 22 + 65535
+      @io.seek(size - scan_size)
+      tail = @io.read(scan_size)
+      tail = tail.force_encoding('BINARY')
+
+      pat = EOCD_SIG.b  # dup 避免修改 frozen 常量
+      pos = tail.rindex(pat)
+      raise "EOCD record not found — not a valid ZIP file" unless pos
+
+      size - scan_size + pos
+    end
+
+    ##
+    # 解析 Local File Header，返回实际数据起始偏移。
+    def resolve_data_offset(local_offset)
+      @io.seek(local_offset)
+      sig = @io.read(4)
+      raise "Local file header signature not found at #{local_offset}" unless sig == LOCAL_SIG
+
+      _ver, _flags, _method, _mtime, _mdate,
+        _crc, _comp, _uncomp, name_len, extra_len = @io.read(26).unpack('vvvvvVVVvv')
+
+      local_offset + 30 + name_len + extra_len
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: manticore-smash
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Frampt
@@ -18,6 +18,9 @@ files:
 - README.md
 - lib/manticore.rb
 - lib/mdutils/rediscount.rb
+- lib/xlsxkit/sax_parser.rb
+- lib/xlsxkit/workbook.rb
+- lib/xlsxkit/zip_reader.rb
 - lib/xmlutils/formatters.rb
 - lib/xmlutils/node.rb
 - lib/xmlutils/tokenizer.rb
@@ -42,7 +45,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.19
 specification_version: 4
 summary: A multi-format toolkit
 test_files: []