npm - @xopcai/xopc - Versions diffs - 0.0.102 → 0.0.104 - Mend

@xopcai/xopc 0.0.102 → 0.0.104

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (995) hide show

package/skills/documents/pptx/scripts/thumbnail.py DELETED Viewed

@@ -1,289 +0,0 @@
-"""Create thumbnail grids from PowerPoint presentation slides.
-Creates a grid layout of slide thumbnails for quick visual analysis.
-Labels each thumbnail with its XML filename (e.g., slide1.xml).
-Hidden slides are shown with a placeholder pattern.
-Usage:
-    python thumbnail.py input.pptx [output_prefix] [--cols N]
-Examples:
-    python thumbnail.py presentation.pptx
-    # Creates: thumbnails.jpg
-    python thumbnail.py template.pptx grid --cols 4
-    # Creates: grid.jpg (or grid-1.jpg, grid-2.jpg for large decks)
-"""
-import argparse
-import subprocess
-import sys
-import tempfile
-import zipfile
-from pathlib import Path
-import defusedxml.minidom
-from office.soffice import get_soffice_env
-from PIL import Image, ImageDraw, ImageFont
-THUMBNAIL_WIDTH = 300
-CONVERSION_DPI = 100
-MAX_COLS = 6
-DEFAULT_COLS = 3
-JPEG_QUALITY = 95
-GRID_PADDING = 20
-BORDER_WIDTH = 2
-FONT_SIZE_RATIO = 0.10
-LABEL_PADDING_RATIO = 0.4
-def main():
-    parser = argparse.ArgumentParser(
-        description="Create thumbnail grids from PowerPoint slides."
-    )
-    parser.add_argument("input", help="Input PowerPoint file (.pptx)")
-    parser.add_argument(
-        "output_prefix",
-        nargs="?",
-        default="thumbnails",
-        help="Output prefix for image files (default: thumbnails)",
-    )
-    parser.add_argument(
-        "--cols",
-        type=int,
-        default=DEFAULT_COLS,
-        help=f"Number of columns (default: {DEFAULT_COLS}, max: {MAX_COLS})",
-    )
-    args = parser.parse_args()
-    cols = min(args.cols, MAX_COLS)
-    if args.cols > MAX_COLS:
-        print(f"Warning: Columns limited to {MAX_COLS}")
-    input_path = Path(args.input)
-    if not input_path.exists() or input_path.suffix.lower() != ".pptx":
-        print(f"Error: Invalid PowerPoint file: {args.input}", file=sys.stderr)
-        sys.exit(1)
-    output_path = Path(f"{args.output_prefix}.jpg")
-    try:
-        slide_info = get_slide_info(input_path)
-        with tempfile.TemporaryDirectory() as temp_dir:
-            temp_path = Path(temp_dir)
-            visible_images = convert_to_images(input_path, temp_path)
-            if not visible_images and not any(s["hidden"] for s in slide_info):
-                print("Error: No slides found", file=sys.stderr)
-                sys.exit(1)
-            slides = build_slide_list(slide_info, visible_images, temp_path)
-            grid_files = create_grids(slides, cols, THUMBNAIL_WIDTH, output_path)
-            print(f"Created {len(grid_files)} grid(s):")
-            for grid_file in grid_files:
-                print(f"  {grid_file}")
-    except Exception as e:
-        print(f"Error: {e}", file=sys.stderr)
-        sys.exit(1)
-def get_slide_info(pptx_path: Path) -> list[dict]:
-    with zipfile.ZipFile(pptx_path, "r") as zf:
-        rels_content = zf.read("ppt/_rels/presentation.xml.rels").decode("utf-8")
-        rels_dom = defusedxml.minidom.parseString(rels_content)
-        rid_to_slide = {}
-        for rel in rels_dom.getElementsByTagName("Relationship"):
-            rid = rel.getAttribute("Id")
-            target = rel.getAttribute("Target")
-            rel_type = rel.getAttribute("Type")
-            if "slide" in rel_type and target.startswith("slides/"):
-                rid_to_slide[rid] = target.replace("slides/", "")
-        pres_content = zf.read("ppt/presentation.xml").decode("utf-8")
-        pres_dom = defusedxml.minidom.parseString(pres_content)
-        slides = []
-        for sld_id in pres_dom.getElementsByTagName("p:sldId"):
-            rid = sld_id.getAttribute("r:id")
-            if rid in rid_to_slide:
-                hidden = sld_id.getAttribute("show") == "0"
-                slides.append({"name": rid_to_slide[rid], "hidden": hidden})
-        return slides
-def build_slide_list(
-    slide_info: list[dict],
-    visible_images: list[Path],
-    temp_dir: Path,
-) -> list[tuple[Path, str]]:
-    if visible_images:
-        with Image.open(visible_images[0]) as img:
-            placeholder_size = img.size
-    else:
-        placeholder_size = (1920, 1080)
-    slides = []
-    visible_idx = 0
-    for info in slide_info:
-        if info["hidden"]:
-            placeholder_path = temp_dir / f"hidden-{info['name']}.jpg"
-            placeholder_img = create_hidden_placeholder(placeholder_size)
-            placeholder_img.save(placeholder_path, "JPEG")
-            slides.append((placeholder_path, f"{info['name']} (hidden)"))
-        else:
-            if visible_idx < len(visible_images):
-                slides.append((visible_images[visible_idx], info["name"]))
-                visible_idx += 1
-    return slides
-def create_hidden_placeholder(size: tuple[int, int]) -> Image.Image:
-    img = Image.new("RGB", size, color="#F0F0F0")
-    draw = ImageDraw.Draw(img)
-    line_width = max(5, min(size) // 100)
-    draw.line([(0, 0), size], fill="#CCCCCC", width=line_width)
-    draw.line([(size[0], 0), (0, size[1])], fill="#CCCCCC", width=line_width)
-    return img
-def convert_to_images(pptx_path: Path, temp_dir: Path) -> list[Path]:
-    pdf_path = temp_dir / f"{pptx_path.stem}.pdf"
-    result = subprocess.run(
-        [
-            "soffice",
-            "--headless",
-            "--convert-to",
-            "pdf",
-            "--outdir",
-            str(temp_dir),
-            str(pptx_path),
-        ],
-        capture_output=True,
-        text=True,
-        env=get_soffice_env(),
-    )
-    if result.returncode != 0 or not pdf_path.exists():
-        raise RuntimeError("PDF conversion failed")
-    result = subprocess.run(
-        [
-            "pdftoppm",
-            "-jpeg",
-            "-r",
-            str(CONVERSION_DPI),
-            str(pdf_path),
-            str(temp_dir / "slide"),
-        ],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0:
-        raise RuntimeError("Image conversion failed")
-    return sorted(temp_dir.glob("slide-*.jpg"))
-def create_grids(
-    slides: list[tuple[Path, str]],
-    cols: int,
-    width: int,
-    output_path: Path,
-) -> list[str]:
-    max_per_grid = cols * (cols + 1)
-    grid_files = []
-    for chunk_idx, start_idx in enumerate(range(0, len(slides), max_per_grid)):
-        end_idx = min(start_idx + max_per_grid, len(slides))
-        chunk_slides = slides[start_idx:end_idx]
-        grid = create_grid(chunk_slides, cols, width)
-        if len(slides) <= max_per_grid:
-            grid_filename = output_path
-        else:
-            stem = output_path.stem
-            suffix = output_path.suffix
-            grid_filename = output_path.parent / f"{stem}-{chunk_idx + 1}{suffix}"
-        grid_filename.parent.mkdir(parents=True, exist_ok=True)
-        grid.save(str(grid_filename), quality=JPEG_QUALITY)
-        grid_files.append(str(grid_filename))
-    return grid_files
-def create_grid(
-    slides: list[tuple[Path, str]],
-    cols: int,
-    width: int,
-) -> Image.Image:
-    font_size = int(width * FONT_SIZE_RATIO)
-    label_padding = int(font_size * LABEL_PADDING_RATIO)
-    with Image.open(slides[0][0]) as img:
-        aspect = img.height / img.width
-    height = int(width * aspect)
-    rows = (len(slides) + cols - 1) // cols
-    grid_w = cols * width + (cols + 1) * GRID_PADDING
-    grid_h = rows * (height + font_size + label_padding * 2) + (rows + 1) * GRID_PADDING
-    grid = Image.new("RGB", (grid_w, grid_h), "white")
-    draw = ImageDraw.Draw(grid)
-    try:
-        font = ImageFont.load_default(size=font_size)
-    except Exception:
-        font = ImageFont.load_default()
-    for i, (img_path, slide_name) in enumerate(slides):
-        row, col = i // cols, i % cols
-        x = col * width + (col + 1) * GRID_PADDING
-        y_base = (
-            row * (height + font_size + label_padding * 2) + (row + 1) * GRID_PADDING
-        )
-        label = slide_name
-        bbox = draw.textbbox((0, 0), label, font=font)
-        text_w = bbox[2] - bbox[0]
-        draw.text(
-            (x + (width - text_w) // 2, y_base + label_padding),
-            label,
-            fill="black",
-            font=font,
-        )
-        y_thumbnail = y_base + label_padding + font_size + label_padding
-        with Image.open(img_path) as img:
-            img.thumbnail((width, height), Image.Resampling.LANCZOS)
-            w, h = img.size
-            tx = x + (width - w) // 2
-            ty = y_thumbnail + (height - h) // 2
-            grid.paste(img, (tx, ty))
-            if BORDER_WIDTH > 0:
-                draw.rectangle(
-                    [
-                        (tx - BORDER_WIDTH, ty - BORDER_WIDTH),
-                        (tx + w + BORDER_WIDTH - 1, ty + h + BORDER_WIDTH - 1),
-                    ],
-                    outline="gray",
-                    width=BORDER_WIDTH,
-                )
-    return grid
-if __name__ == "__main__":
-    main()

package/skills/documents/xlsx/SKILL-zh.md DELETED Viewed

@@ -1,292 +0,0 @@
----
-name: xlsx
-description: "在任何以电子表格文件为主要输入或输出的任务中使用本技能。这意味着用户想要：打开、读取、编辑或修复现有的 .xlsx、.xlsm、.csv 或 .tsv 文件（如添加列、计算公式、格式化、制图、清理混乱数据）；从头开始或从其他数据源创建新电子表格；或在表格文件格式之间进行转换。特别是当用户按名称或路径引用电子表格文件时——即使是随口一提（如\"我下载文件夹里的那个 xlsx\"）——并希望对它进行操作或从中生成内容时触发。也用于将混乱的表格数据文件（格式错误的行、错位的标题、垃圾数据）清理或重构为规范的电子表格。交付物必须是电子表格文件。当主要交付物是 Word 文档、HTML 报告、独立 Python 脚本、数据库管道或 Google Sheets API 集成时，即使涉及表格数据，也不要触发。"
-license: 专有。完整条款见 LICENSE.txt
----
-# 输出要求
-## 所有 Excel 文件
-### 专业字体
-- 除非用户另有指示，对所有交付物使用一致的专业字体（如 Arial、Times New Roman）
-### 零公式错误
-- 每个 Excel 模型交付时必须包含零公式错误（#REF!、#DIV/0!、#VALUE!、#N/A、#NAME?）
-### 保留现有模板（更新模板时）
-- 修改文件时研究和精确匹配现有格式、样式和约定
-- 绝不对已有既定模式的文件强加标准格式
-- 现有模板的约定始终优先于这些指南
-## 财务模型
-### 颜色编码标准
-除非用户或现有模板另有说明
-#### 行业标准颜色约定
-- **蓝色文字（RGB：0,0,255）**：硬编码输入，以及用户会为不同场景更改的数字
-- **黑色文字（RGB：0,0,0）**：所有公式和计算
-- **绿色文字（RGB：0,128,0）**：从同一工作簿中其他工作表链接的数据
-- **红色文字（RGB：255,0,0）**：指向其他文件的外部链接
-- **黄色背景（RGB：255,255,0）**：需要注意的关键假设或需要更新的单元格
-### 数字格式标准
-#### 必需的格式规则
-- **年份**：格式化为文本字符串（如"2024"而非"2,024"）
-- **货币**：使用 $#,##0 格式；始终在标题中指定单位（"收入（$mm）"）
-- **零值**：使用数字格式使所有零显示为"-"，包括百分比（如"$#,##0；($#,##0)；-"）
-- **百分比**：默认为 0.0% 格式（一位小数）
-- **倍数**：估值倍数（EV/EBITDA、P/E）格式化为 0.0x
-- **负数**：使用括号（123）而非负号 -123
-### 公式构建规则
-#### 假设条件放置
-- 将所有假设条件（增长率、利润率、倍数等）放在单独的假设单元格中
-- 在公式中使用单元格引用而非硬编码值
-- 示例：使用 =B5*(1+$B$6) 而非 =B5*1.05
-#### 公式错误预防
-- 验证所有单元格引用正确
-- 检查范围中的差一错误
-- 确保所有预测期间的公式一致
-- 用极端值（零值、负数）测试
-- 验证没有意外的循环引用
-#### 硬编码的文档化要求
-- 在单元格中或旁边注释（如果在表格末尾）。格式："来源：[系统/文档]，[日期]，[具体引用]，[URL（如适用）]"
-- 示例：
-  - "来源：公司 10-K 年报，FY2024，第 45 页，收入注释，[SEC EDGAR URL]"
-  - "来源：公司 10-Q 季报，Q2 2025，附件 99.1，[SEC EDGAR URL]"
-  - "来源：Bloomberg 终端，2025/8/15，AAPL US Equity"
-  - "来源：FactSet，2025/8/20，一致预期界面"
-# XLSX 创建、编辑和分析
-## 概述
-用户可能要求你创建、编辑或分析 .xlsx 文件的内容。针对不同任务，有不同的工具和工作流可用。
-## 重要要求
-**LibreOffice 用于公式重新计算**：假设已安装 LibreOffice，可通过 `scripts/recalc.py` 脚本重新计算公式值。该脚本在首次运行时自动配置 LibreOffice，包括在 Unix socket 受限的沙箱环境中（由 `scripts/office/soffice.py` 处理）。
-## 读取和分析数据
-### 使用 pandas 进行数据分析
-对于数据分析、可视化和基本操作，使用 **pandas**，它提供了强大的数据处理能力：
-```python
-import pandas as pd
-# 读取 Excel
-df = pd.read_excel('file.xlsx')  # 默认：第一个工作表
-all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # 所有工作表（字典形式）
-# 分析
-df.head()      # 预览数据
-df.info()      # 列信息
-df.describe()  # 统计信息
-# 写入 Excel
-df.to_excel('output.xlsx', index=False)
-```
-## Excel 文件工作流
-## 关键：使用公式，而非硬编码值
-**始终使用 Excel 公式，而不是在 Python 中计算值并硬编码。** 这确保电子表格保持动态和可更新性。
-### ❌ 错误 - 硬编码计算值
-```python
-# 糟糕：在 Python 中计算并硬编码结果
-total = df['Sales'].sum()
-sheet['B10'] = total  # 硬编码 5000
-# 糟糕：在 Python 中计算增长率
-growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
-sheet['C5'] = growth  # 硬编码 0.15
-# 糟糕：Python 计算平均值
-avg = sum(values) / len(values)
-sheet['D20'] = avg  # 硬编码 42.5
-```
-### ✅ 正确 - 使用 Excel 公式
-```python
-# 好：让 Excel 计算总和
-sheet['B10'] = '=SUM(B2:B9)'
-# 好：增长率为 Excel 公式
-sheet['C5'] = '=(C4-C2)/C2'
-# 好：使用 Excel 函数计算平均值
-sheet['D20'] = '=AVERAGE(D2:D19)'
-```
-这适用于所有计算——总计、百分比、比率、差异等。电子表格应在源数据更改时能够重新计算。
-## 常见工作流
-1. **选择工具**：数据处理用 pandas，公式/格式用 openpyxl
-2. **创建/加载**：创建工作簿或加载现有文件
-3. **修改**：添加/编辑数据、公式和格式
-4. **保存**：写入文件
-5. **重新计算公式（如果使用公式则必须执行）**：使用 scripts/recalc.py 脚本
-   ```bash
-   python scripts/recalc.py output.xlsx
-   ```
-6. **验证并修复任何错误**：
-   - 脚本返回包含错误详情的 JSON
-   - 如果 `status` 为 `errors_found`，检查 `error_summary` 获取具体错误类型和位置
-   - 修复发现的错误并重新计算
-   - 需要修复的常见错误：
-     - `#REF!`：无效的单元格引用
-     - `#DIV/0!`：除零错误
-     - `#VALUE!`：公式中数据类型错误
-     - `#NAME?`：无法识别的公式名称
-### 创建新的 Excel 文件
-```python
-# 使用 openpyxl 处理公式和格式
-from openpyxl import Workbook
-from openpyxl.styles import Font, PatternFill, Alignment
-wb = Workbook()
-sheet = wb.active
-# 添加数据
-sheet['A1'] = '你好'
-sheet['B1'] = '世界'
-sheet.append(['行', '的', '数据'])
-# 添加公式
-sheet['B2'] = '=SUM(A1:A10)'
-# 格式化
-sheet['A1'].font = Font(bold=True, color='FF0000')
-sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
-sheet['A1'].alignment = Alignment(horizontal='center')
-# 列宽
-sheet.column_dimensions['A'].width = 20
-wb.save('output.xlsx')
-```
-### 编辑现有的 Excel 文件
-```python
-# 使用 openpyxl 保留公式和格式
-from openpyxl import load_workbook
-# 加载现有文件
-wb = load_workbook('existing.xlsx')
-sheet = wb.active  # 或 wb['SheetName'] 获取特定工作表
-# 处理多个工作表
-for sheet_name in wb.sheetnames:
-    sheet = wb[sheet_name]
-    print(f"工作表：{sheet_name}")
-# 修改单元格
-sheet['A1'] = '新值'
-sheet.insert_rows(2)  # 在第 2 行位置插入行
-sheet.delete_cols(3)  # 删除第 3 列
-# 添加新工作表
-new_sheet = wb.create_sheet('新工作表')
-new_sheet['A1'] = '数据'
-wb.save('modified.xlsx')
-```
-## 重新计算公式
-由 openpyxl 创建或修改的 Excel 文件包含公式字符串但不包含计算值。使用提供的 `scripts/recalc.py` 脚本重新计算公式：
-```bash
-python scripts/recalc.py <excel_file> [timeout_seconds]
-```
-示例：
-```bash
-python scripts/recalc.py output.xlsx 30
-```
-该脚本：
-- 首次运行时自动设置 LibreOffice 宏
-- 重新计算所有工作表中的所有公式
-- 扫描所有单元格以查找 Excel 错误（#REF!、#DIV/0! 等）
-- 返回包含详细错误位置和计数的 JSON
-- 可在 Linux 和 macOS 上运行
-## 公式验证清单
-确保公式正确运行的快速检查：
-### 基本验证
-- [ ] **测试 2-3 个示例引用**：在构建完整模型前验证它们引用了正确的值
-- [ ] **列映射**：确认 Excel 列匹配（如第 64 列 = BL，不是 BK）
-- [ ] **行偏移**：记住 Excel 行从 1 开始（DataFrame 第 5 行 = Excel 第 6 行）
-### 常见陷阱
-- [ ] **NaN 处理**：使用 `pd.notna()` 检查空值
-- [ ] **靠右的列**：财务数据通常在 50+ 列
-- [ ] **多处匹配**：搜索所有出现，不只是第一个
-- [ ] **除零错误**：在公式中使用 `/` 前检查分母（#DIV/0!）
-- [ ] **错误引用**：验证所有单元格引用指向预期单元格（#REF!）
-- [ ] **跨工作表引用**：使用正确格式（Sheet1!A1）链接工作表
-### 公式测试策略
-- [ ] **从小开始**：在广泛应用前先对 2-3 个单元格测试公式
-- [ ] **验证依赖**：检查公式中引用的所有单元格都存在
-- [ ] **测试边界情况**：包括零、负数和非常大的值
-### 解读 scripts/recalc.py 输出
-脚本返回包含错误详情的 JSON：
-```json
-{
-  "status": "success",           // 或 "errors_found"
-  "total_errors": 0,              // 错误总数
-  "total_formulas": 42,           // 文件中的公式数量
-  "error_summary": {              // 仅当发现错误时存在
-    "#REF!": {
-      "count": 2,
-      "locations": ["Sheet1!B5", "Sheet1!C10"]
-    }
-  }
-}
-```
-## 最佳实践
-### 库选择
-- **pandas**：最适合数据分析、批量操作和简单数据导出
-- **openpyxl**：最适合复杂格式、公式和 Excel 特定功能
-### 使用 openpyxl
-- 单元格索引从 1 开始（row=1，column=1 指单元格 A1）
-- 使用 `data_only=True` 读取计算值：`load_workbook('file.xlsx', data_only=True)`
-- **警告**：如果以 `data_only=True` 打开并保存，公式将被值替换且永久丢失
-- 对大文件：使用 `read_only=True` 读取或 `write_only=True` 写入
-- 公式会保留但不会求值——使用 scripts/recalc.py 更新值
-### 使用 pandas
-- 指定数据类型以避免推断问题：`pd.read_excel('file.xlsx', dtype={'id': str})`
-- 对大文件，读取特定列：`pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])`
-- 正确处理日期：`pd.read_excel('file.xlsx', parse_dates=['date_column'])`
-## 代码风格指南
-**重要**：生成用于 Excel 操作的 Python 代码时：
-- 编写简洁的 Python 代码，无需不必要的注释
-- 避免冗长的变量名和冗余操作
-- 避免不必要的 print 语句
-**对于 Excel 文件本身**：
-- 为包含复杂公式或重要假设的单元格添加注释
-- 记录硬编码值的数据来源
-- 为关键计算和模型章节添加说明

package/skills/engineering/diagnose/SKILL-zh.md DELETED Viewed

@@ -1,117 +0,0 @@
----
-name: diagnose
-description: 针对难以解决的错误和性能回归的有纪律的诊断循环。重现 → 最小化 → 假设 → 检测 → 修复 → 回归测试。当用户说"诊断这个"/"调试这个"、报告错误、说某东西坏了/抛出异常/失败、或描述性能回归时使用。
----
-# 诊断
-针对难以解决的错误的方法论。只有在明确有理由时才跳过阶段。
-探索代码库时，使用项目的领域词汇表来建立相关模块的清晰心智模型，并检查你所触及区域的 ADR。
-## 阶段 1 — 构建反馈回路
-**这是核心技能。** 其他都是机械性的。如果你有一个快速、确定性的、可由代理运行的针对该错误的是/否信号，你就能找到原因——二分搜索、假设测试和检测都只是在消费这个信号。如果你没有这个信号，再看多少代码也没用。
-把不成比例的努力花在这里。**要激进。要创新。拒绝放弃。**
-### 构建反馈回路的方法——大致按此顺序尝试
-1. **失败的测试**——在能触及 bug 的任何接缝处——单元测试、集成测试、端到端测试。
-2. **Curl / HTTP 脚本**——针对正在运行的开发服务器。
-3. **CLI 调用**——使用预置输入，将标准输出与已知良好的快照进行对比。
-4. **无头浏览器脚本**（Playwright / Puppeteer）——驱动 UI，在 DOM/控制台/网络上进行断言。
-5. **重放捕获的跟踪。** 将真实的网络请求/负载/事件日志保存到磁盘；在隔离环境中通过代码路径重放。
-6. **一次性测试工具。** 搭建系统的最小子集（一个服务，模拟依赖），通过单个函数调用执行 bug 代码路径。
-7. **属性/模糊测试循环。** 如果 bug 是"有时输出错误"，运行 1000 个随机输入并寻找故障模式。
-8. **二分搜索工具。** 如果 bug 出现在两个已知状态之间（提交、数据集、版本），自动化"在状态 X 启动，检查，重复"，以便你可以运行 `git bisect run`。
-9. **差分循环。** 将相同的输入通过旧版本 vs 新版本（或两种配置）运行，并对比输出。
-10. **人机协作 bash 脚本。** 最后手段。如果必须有人点击，用 `scripts/hitl-loop.template.sh` 来驱动**他们**，使循环仍然有结构。捕获的输出反馈给你。
-构建正确的反馈回路，bug 就解决了 90%。
-### 迭代循环本身
-把循环当作产品来对待。一旦你有了一个循环，问：
-- 能更快吗？（缓存设置、跳过无关初始化、缩小测试范围。）
-- 信号能更明确吗？（针对特定症状断言，而不是"没有崩溃"。）
-- 能更确定吗？（固定时间、种子化 RNG、隔离文件系统、冻结网络。）
-一个 30 秒的不稳定循环比没有循环好不了多少。一个 2 秒的确定性循环是调试超能力。
-### 非确定性错误
-目标不是干净的复现，而是**更高的复现率**。循环触发器 100 次、并行化、增加压力、缩小时间窗口、注入延迟。50% 飘忽的 bug 是可调试的；1% 不是——不断提高比率直到可调试为止。
-### 当你真的无法构建循环时
-停下来并明确说明。列出你尝试过的方法。向用户请求：(a) 访问复现所需的环境、(b) 捕获的制品（HAR 文件、日志转储、核心转储、带时间戳的屏幕录制），或 (c) 添加临时生产检测的权限。**没有循环就不要继续到假设阶段。**
-在拥有你相信的循环之前，不要进入阶段 2。
-## 阶段 2 — 重现
-运行循环。观察 bug 出现。
-确认：
-- [ ] 循环产生**用户**描述的故障模式——而不是碰巧附近的另一个不同故障。错误的 bug = 错误的修复。
-- [ ] 故障在多次运行中是可重现的（或者对于非确定性 bug，在足够高的比率下可重现以便调试）。
-- [ ] 你已经捕获了确切的症状（错误消息、错误输出、缓慢的时间），以便后续阶段可以验证修复确实解决了它。
-在重现 bug 之前不要继续。
-## 阶段 3 — 假设
-在测试任何一个假设之前，生成 **3-5 个排序的假设**。单一假设生成会锚定在第一个看似合理的想法上。
-每个假设必须是**可证伪的**：陈述它所做的预测。
-> 格式："如果 <X> 是原因，那么 <改变 Y> 将使 bug 消失 / <改变 Z> 将使 bug 更严重。"
-如果你无法陈述预测，那这个假设只是一种感觉——放弃它或让它更精确。
-**在测试之前向用户展示排序列表。** 他们通常有领域知识可以立即重新排序（"我们刚部署了 #3 的更改"），或者知道他们已经排除的假设。廉价检查点，节省大量时间。如果用户不在，不要阻塞——按你的排序继续。
-## 阶段 4 — 检测
-每个探测必须映射到阶段 3 的具体预测。**一次只改变一个变量。**
-工具偏好：
-1. **调试器 / REPL 检查**——如果环境支持。一个断点胜过十个日志。
-2. **针对性日志**——在能够区分假设的边界处。
-3. 绝不"记录一切然后 grep"。
-**给每个调试日志打上唯一前缀标签**，例如 `[DEBUG-a4f2]`。最后清理时一次 grep 搞定。未标记的日志保留；标记的日志删除。
-**性能分支。** 对于性能回归，日志通常是错误的。改为：建立基线测量（时间测试工具、`performance.now()`、性能分析器、查询计划），然后二分搜索。先测量，后修复。
-## 阶段 5 — 修复 + 回归测试
-**在修复之前**编写回归测试——但只有在有一个**正确的接缝**时才这样做。
-一个正确的接缝是测试可以像在调用点一样执行**真实 bug 模式**。如果唯一可用的接缝太浅（单个调用者的测试当 bug 需要多个调用者时，无法复现触发 bug 的链的单元测试），在那里的回归测试会给出虚假的信心。
-**如果没有正确的接缝，这本身就是发现。** 记下它。代码库架构阻止了将该 bug 锁定。将其标记出来供下一个阶段使用。
-如果存在正确的接缝：
-1. 将最小化的复现转化为该接缝处的失败测试。
-2. 观察它失败。
-3. 应用修复。
-4. 观察它通过。
-5. 针对原始（未最小化的）场景重新运行阶段 1 的反馈回路。
-## 阶段 6 — 清理 + 事后分析
-在宣布完成之前必须完成：
-- [ ] 原始复现不再复现（重新运行阶段 1 的循环）
-- [ ] 回归测试通过（或接缝缺失已记录）
-- [ ] 所有 `[DEBUG-...]` 检测已移除（grep 前缀）
-- [ ] 一次性原型已删除（或移到明确标记的调试位置）
-- [ ] 正确的假设在提交/PR 消息中说明——以便下一个调试者学习
-**然后问：什么本来可以防止这个 bug？** 如果答案涉及架构变更（没有好的测试接缝、调用者纠缠、隐藏耦合），将具体内容交给 `/improve-codebase-architecture` 技能。在修复**之后**提出建议，而不是之前——你现在拥有的信息比开始时更多。