lyxy-document/openspec/specs/skill-packaging/spec.md at aaa1171e602abcf62334b8fba9951d571fbc7738

Files

lanyuanxiaoyao d860e17b2c feat: 添加 PyArmor 代码混淆支持

- 新增 --obfuscate 命令行参数，支持使用 PyArmor 混淆代码
- 通过 uv run --with pyarmor 按需加载 PyArmor，不污染主机环境
- 添加友好的错误提示，引导用户正确使用 --with pyarmor
- 保持非混淆模式完全向后兼容
- 更新 skill-packaging spec，新增混淆相关需求

2026-03-09 14:36:52 +08:00

3.9 KiB

Raw Blame History

Purpose

提供自动化的 skill 打包能力，将 skill/SKILL.md 和 scripts/ 目录打包到 build/ 目录，便于 skill 分发。

Requirements

Requirement: build.py 一键打包

系统 SHALL 提供 build.py 脚本，运行后完成 skill 的完整打包流程。

Scenario: 运行 build.py 成功

WHEN 用户执行 uv run python build.py
THEN 脚本完成所有打包步骤并输出成功信息

Requirement: 构建目录清理重建

系统 SHALL 在每次构建前删除整个 build 目录，然后重建空的 build 目录。

Scenario: 删除并重建 build 目录

WHEN 构建开始
THEN 脚本删除整个 build 目录（如有），然后创建新的空 build 目录

Requirement: SKILL.md 复制

系统 SHALL 将 skill/SKILL.md 直接复制到 build/SKILL.md，不保留 skill 这一级目录。

Scenario: SKILL.md 成功复制

WHEN 构建执行
THEN build/SKILL.md 文件存在且内容与 skill/SKILL.md 一致

Requirement: scripts 目录复制

系统 SHALL 将 scripts/ 目录完整复制到 build/scripts/，保持目录结构。

Scenario: scripts 目录结构保留

WHEN 构建执行
THEN build/scripts/ 下的子目录结构与原 scripts/ 一致

Requirement: 仅复制 Python 文件

系统 SHALL 只复制 .py 扩展名的文件，其他文件类型自然被过滤。

Scenario: 只保留 py 文件

WHEN 原目录包含多种文件类型
THEN build/scripts/ 中只存在 .py 文件

Requirement: 时间戳版本号

系统 SHALL 生成 YYYYMMDD_HHMMSS 格式的时间戳作为构建版本标识。

Scenario: 时间戳格式正确

WHEN 构建在 2025年3月9日 14点30分22秒执行
THEN 生成的版本号为 20250309_143022

Requirement: 输出构建信息

系统 SHALL 在构建完成后打印版本号和构建结果信息。

Scenario: 显示构建信息

WHEN 构建成功完成
THEN 控制台输出版本号和构建文件清单

Requirement: --obfuscate 参数支持

系统 SHALL 支持 --obfuscate 命令行参数，用于启用代码混淆功能。

Scenario: 使用 --obfuscate 参数

WHEN 用户执行 uv run --with pyarmor python build.py --obfuscate
THEN 系统使用 PyArmor 对 scripts 目录代码进行混淆

Scenario: 不使用 --obfuscate 参数

WHEN 用户执行 uv run python build.py（不带 --obfuscate）
THEN 系统执行原有的复制行为，不进行混淆

Requirement: PyArmor 混淆执行

系统 SHALL 在 --obfuscate 模式下调用 PyArmor 工具对 scripts 目录进行混淆。

Scenario: PyArmor 成功执行

WHEN 启用 --obfuscate 且 PyArmor 可用
THEN 系统执行 pyarmor gen --recursive 命令

Scenario: 混淆后文件输出

WHEN PyArmor 混淆完成
THEN build/scripts/ 目录包含混淆后的文件

Scenario: pyarmor_runtime 包含

WHEN PyArmor 混淆完成
THEN build/scripts/ 目录包含 pyarmor_runtime_xxxxxx 子目录

Requirement: PyArmor 未安装友好提示

系统 SHALL 在 PyArmor 未安装时提供清晰的错误提示，引导用户正确使用 uv run --with pyarmor。

Scenario: PyArmor ImportError

WHEN 启用 --obfuscate 但未通过 --with pyarmor 加载
THEN 系统显示友好错误信息，提示正确命令

Requirement: SKILL.md 保持明文

系统 SHALL 在混淆模式下仍然将 SKILL.md 作为明文文件复制，不进行混淆。

Scenario: SKILL.md 保持明文

WHEN 启用 --obfuscate 执行构建
THEN build/SKILL.md 文件为明文，内容与原文件一致

Requirement: 混淆错误处理

系统 SHALL 在 PyArmor 混淆失败时捕获错误并显示详细信息。

Scenario: PyArmor 命令失败

WHEN pyarmor 命令执行返回非零退出码
THEN 系统显示退出码、标准输出和错误输出信息

3.9 KiB Raw Blame History Unescape Escape