政务简易打包

基于 WOP 平台的政务二次包自动化构建工具，按功能场景划分为独立工作流。

前置条件

pip install -r <SKILL_ROOT>/requirements.txt

> = 本 SKILL.md 所在目录（如 .cursor/skills/Fantasy工具包），下同。

Python 3.10+，登录采集需本机有 Chrome 或 Edge。

网络与安全声明

本 Skill 需要网络访问，用途如下：

| 目标 | 用途 | 方向 |

|------|------|------|

| 127.0.0.1:8066 | 本地 Web 管理服务，前端 JS 通过 /api/* 与后端通信 | 本地回环 |

| fantasy.wps.cn | WOP 平台 API（S3 查询、任务创建/运行/查询） | 出站 GET/POST |

| 用户配置的 Webhook URL | 打包完成通知（仅在用户主动配置后触发） | 出站 POST |

隐藏/运行时文件说明：

| 文件 | 用途 | 是否纳入分发 |

|------|------|-------------|

| .env | 存储 FANTASY_TOKEN 凭证，首次使用时由用户通过 Web 页面登录生成 | 否（.gitignore） |

| .runtime/.server.pid | Web 服务进程 PID，运行时自动生成 | 否（.gitignore） |

| .runtime/task_ids.json | 打包任务 ID 缓存，运行时自动生成 | 否（.gitignore） |

常用术语

| 术语 | 含义 |

|------|------|

| 主干分支 | master_kso_v12 |

| 公文版 | 文件名含 EnHance_VBA_GB 的安装包 |

| 统一版 | 文件名以 setup_ 开头、Unified.exe 结尾的安装包 |

场景路由

收到用户请求后，根据意图匹配场景。只有需要执行打包任务时才启动 Web 服务，其他场景通过 CLI 或 API 直接完成。

| 场景 | 触发关键词 | 处理方式 |

|------|-----------|---------|

| 快速打包 | 打包、帮我打包、请帮我打包 | 安装依赖 → 启动 Web 服务 → 引导用户在浏览器操作 |

| Win 打包（CLI） | win 打包、IP 包、二次包 | 读取 references/win打包/flow.md |

| Linux 打包（CLI） | linux 打包、Linux 二次包 | 读取 references/linux打包/flow.md |

| 查找基础包 | 找包、查基础包、帮我找个包 | CLI 直接调用（见下方），不启动 Web 服务 |

| OEM 注释 | OEM 注释、帮我注释、加注释、注释这个 OEM 、帮我解释这些OEM、这些OEM什么功能| 用户发送 OEM 内容 → 运行 annotate_oem.py → 返回注释后内容 → 询问是否保存为模板 |

| 知识问答 | OEM 配置、怎么配置、什么意思 | 读取 references/知识问答/flow.md，不启动 Web 服务 |

| 知识更新 | 知识更新、更新知识库 | 读取 references/知识更新/flow.md，不启动 Web 服务 |

| Web 管理 | 打包页面、打包管理、网页打包 | 安装依赖 → 启动 Web 服务 |

查找基础包（CLI）

用户说"帮我找个包"、"查一下基础包"等，直接通过 CLI 完成，不需要启动 Web 服务。

由于 apis/s3.py 使用相对导入，需通过 Python 代码调用而非直接运行脚本。

查找 Win 包

在 scripts/ 目录下运行：

python -c "import sys;sys.path.insert(0,'.');from apis.s3 import s3_find_package;import json;r=s3_find_package('master_kso_v12');print(json.dumps(r,ensure_ascii=False,indent=2))"

参数说明（按需修改函数调用参数）：

• branch（必填）：分支名，主干分支为 master_kso_v12
• version：指定版本号，None 取最新
• filename_contains：默认 EnHance_VBA_GB（公文版）
• arch：x64 / x86

查找 Linux 包

在 scripts/ 目录下运行：

python -c "import sys;sys.path.insert(0,'.');from apis.s3 import s3_find_linux_package;import json;r=s3_find_linux_package('master_kso_v12','aarch64');print(json.dumps(r,ensure_ascii=False,indent=2))"

函数签名：s3_find_linux_package(branch, arch='x64', category='domestic', version=None, date_from=None, date_to=None)

• branch（必填）：分支名，主干分支为 master_kso_v12
• arch：架构前缀（x64/aarch64/loongson64/loongarch64），默认 x64
• category：domestic（专业版/私网） 或 unified（统一版/365版），默认 domestic
• version：指定版本号，None 自动取最新
• date_from / date_to：日期范围过滤（YYYY-MM-DD）

示例

用户说"帮我找一个主干分支的 linux 基础包，arm 架构的"，在 scripts/ 目录下执行：

python -c "import sys;sys.path.insert(0,'.');from apis.s3 import s3_find_linux_package;import json;r=s3_find_linux_package('master_kso_v12','aarch64');print(json.dumps(r,ensure_ascii=False,indent=2))"

返回 JSON 包含 version、filename、download_url 等信息，直接告知用户结果即可。

OEM 注释与模板

当用户发送一段 OEM 配置内容并要求注释（或用户意图明显是希望理解 OEM 配置含义）时执行此流程。

步骤 1：保存用户内容到临时文件

将用户发送的 OEM 内容保存为临时文件（如 _temp_oem.txt），放在 scripts/ 目录下。

步骤 2：运行注释脚本

在 scripts/ 目录下运行：

python annotate_oem.py -f _temp_oem.txt --json

脚本利用 OEM 知识库自动为每个配置项查找说明并添加 # 注释 行。

输出 JSON 包含 annotated（注释后全文）和 stats（统计信息）。

步骤 3：展示结果

将注释后的 OEM 内容展示给用户，附上统计：已注释数、已有注释保留数、未收录数。

对未收录的配置项，提示用户可通过 oem_db.py add 补充到知识库。

步骤 4：询问是否保存为模板

询问用户是否将注释后的内容保存为 OEM 模板。若用户确认：

python annotate_oem.py -f _temp_oem.txt --save "模板名称" --no-print

模板保存到 references/oems/模板名称.txt，可在 Web 打包页面直接选用。

步骤 5：清理

删除临时文件 _temp_oem.txt。

打包能力优势

相比直接使用 WOP 平台打包，本工具额外提供：

• 便捷 OEM 编辑：可视化添加/修改 OEM 配置项，内置常用配置开关
• 一键政务插件：勾选即自动复制 WPS 政务插件，无需手动处理文件
• 快捷政务 Logo：支持一键定制政务版 Logo 和文案
• 基础包查找：自动按分支/日期/架构定位最新基础包，省去手动翻找 S3

快速打包流程

当用户需要执行打包时（"帮我打包"、"请帮我打包"、"打个包"），执行以下流程：

步骤 1：安装依赖

pip install -r <SKILL_ROOT>/requirements.txt

步骤 2：启动 Web 打包管理服务

cd <SKILL_ROOT>/scripts && python -m server start

命令默认以后台模式运行，不阻塞终端，启动后立即返回并输出 PID 和日志路径。服务监听 http://localhost:8066。

若端口被占用，先停止旧进程：

cd <SKILL_ROOT>/scripts && python -m server stop
cd <SKILL_ROOT>/scripts && python -m server start

如需前台调试运行（阻塞终端，Ctrl+C 停止）：

cd <SKILL_ROOT>/scripts && python -m server start --foreground

步骤 3：引导用户使用

服务启动成功后，告知用户：

• 浏览器打开 http://localhost:8066 进入打包管理页面
• 首页有预设卡片可快速选择 Win/Linux 打包
• 首次使用需要在页面右上角完成 Fantasy 登录
• 选择分支、填入基础包路径（或使用"查找基础包"功能）、配置 OEM 后点击"开始打包"
• 打包记录和轮询状态会自动管理

步骤 4：检查凭证

若用户反馈登录问题，可通过以下方式检查：

cd <SKILL_ROOT>/scripts && python -c "from apis import ensure_token; print('Token OK' if ensure_token() else 'Token missing')"

注意事项

• 服务默认以后台守护进程运行，关闭终端不影响；日志输出到 .runtime/server.log
• 使用 python -m server stop 停止服务，python -m server status 查看运行状态
• 所有打包配置（OEM 模板、预设、历史记录）通过浏览器页面管理
• 如需纯命令行打包（无 Web UI），读取对应平台的 flow.md 执行

文件结构

Fantasy工具包/
├── SKILL.md
├── requirements.txt
├── .env                            # 凭证（FANTASY_TOKEN 等）
├── scripts/
│   ├── apis/
│   │   ├── __init__.py             # 统一导出
│   │   ├── _http.py                # 常量、凭证、HTTP 工具
│   │   ├── s3.py                   # S3 文件查询（含 CLI）
│   │   └── wop.py                  # WOP 任务管理（含 CLI）
│   ├── build.py                    # 打包编排层（BuildParams + execute）
│   ├── annotate_oem.py              # OEM 文件自动注释
│   ├── oem_db.py                   # OEM 配置项数据库
│   └── server/
│       ├── __init__.py             # 进程生命周期（start/stop/status）
│       ├── __main__.py             # python -m server 入口
│       ├── _handler.py             # HTTP 请求分发
│       ├── routes/
│       │   ├── __init__.py         # 显式路由表
│       │   ├── auth.py             # 登录 / Token 管理
│       │   ├── build_routes.py     # 打包 API
│       │   ├── oem.py              # OEM 模板管理
│       │   └── presets.py          # 预设 CRUD
│       └── static/
│           ├── index.html          # 前端 HTML + CSS
│           ├── app.js              # 前端逻辑
│           └── presets.json        # 预设数据
└── references/
    ├── api-reference.md            # API 接口文档
    ├── defaults/                   # 默认配置（JSON）
    │   ├── win_oem.json
    │   ├── win_task_extend.json
    │   └── linux_del_confs.json
    ├── oems/                       # OEM 模板文件（统一目录）
    │   ├── win私网ip包.txt
    │   ├── win私网域名.txt
    │   └── linux私网ip.txt
    ├── win打包/
    │   ├── flow.md
    │   └── win-packaging-api.md
    ├── linux打包/
    │   └── flow.md
    ├── 知识问答/
    │   ├── flow.md
    │   └── 知识库/
    └── 知识更新/
        └── flow.md

核心架构

三层结构，职责分离：

| 层 | 入口 | 职责 |

|----|------|------|

| 原子 API | scripts/apis/ | S3 查询、WOP 任务管理，每个函数做一件事 |

| 编排层 | scripts/build.py | 接受 BuildParams，编排 API 调用，完成端到端打包 |

| Web 层 | scripts/server/ | HTTP 服务、路由、前端，调用编排层 |

BuildParams（打包参数契约）

所有入口（Web / AI / CLI）统一使用 BuildParams dataclass：

from build import BuildParams, SourceConfig, AddressConfig, OemConfig

params = BuildParams(
    platform="win",
    source=SourceConfig(mode="branch", branch="master_kso_v12"),
    address=AddressConfig(type="ip", value="http://10.213.84.60/"),
    oem=OemConfig(template="win私网ip包"),
)

共享脚本速查

API 函数（scripts/apis/）

| 函数 | 用途 |

|------|------|

| s3_list(path, search?) | 列目录 |

| s3_search(dir, keyword) | 模糊搜索 |

| s3_latest_version(branch, top_dir?, date?) | 最新版本号（支持日期过滤） |

| s3_find_package(branch) | 定位 Win 安装包 |

| s3_find_linux_package(branch, arch?, category?) | 定位 Linux 基础包 |

| parse_s3_url(url) | 解析 S3 URL 为 (branch, version, filename) |

| s3_validate_package(url) | 校验 S3 包路径有效性 |

| wop_create_task(name, base, target, ...) | 创建任务 |

| wop_run_task(id, platform?, sign?) | 运行任务（支持签名） |

| wop_query_tasks(name?) | 查询任务列表 |

| wop_job_detail(id) | 作业详情 |

| ensure_task(name, base, target, ...) | 创建或复用同名任务 |

| poll_job(task_name, interval?) | 轮询作业状态直到完成 |

独立工具脚本

| 脚本 | 用途 | 用法 |

|------|------|------|

| python -m server start | 后台启动 Web 打包管理服务（默认） | 在 scripts/ 目录下运行 |

| python -m server start --foreground | 前台启动（阻塞终端，调试用） | 在 scripts/ 目录下运行 |

| python -m server stop | 停止服务 | 在 scripts/ 目录下运行 |

| python -m server status | 查看服务状态 | 在 scripts/ 目录下运行 |

| S3 查询 | 查找基础包、列目录 | from apis.s3 import ... 调用（见「查找基础包」章节） |

| WOP 任务 | 创建/运行/查询任务 | from apis.wop import ... 调用 |

| python build.py params.json | CLI 打包 | 传入 BuildParams JSON 文件 |

| python oem_db.py | OEM 数据库 | oem_db.py search\|add\|stats\|init |

| python annotate_oem.py | OEM 自动注释 | -f file [--save name] [--json] |

认证

凭证存储在 Skill 内部 .env 文件。所有接口仅需 fantasy-token 请求头。

| .env 变量 | 采集方式 | 用于 |

|----------|---------|------|

| FANTASY_TOKEN | Web 页面登录或 scripts/server/routes/auth.py | 全部接口（S3 + WOP） |

完整 API 文档

接口参数、返回值详见 references/api-reference.md。