1
0

Compare commits

...

4 Commits

Author SHA1 Message Date
86308675ea 统一skill命名 2026-02-12 17:57:05 +08:00
53707efaf0 新增docx解析 2026-02-12 16:23:23 +08:00
004ebe3d4f 创建docx-reader skill 2026-02-12 12:11:43 +08:00
cccb61e4b9 规范路径命名 2026-02-12 12:10:38 +08:00
40 changed files with 877 additions and 188 deletions

View File

@@ -1 +0,0 @@
../../skills/js-runner

View File

@@ -1 +0,0 @@
../../skills/python-runner

View File

@@ -57,7 +57,7 @@ uv是Astral开发的快速Python包管理器支持PEP 723内联元数据格
### Decision 2: 使用辅助脚本实现跨平台临时目录
**决策:** 创建`skills/python-runner/script/get_temp_path.py`辅助脚本使用Python标准库的`tempfile`模块在系统临时目录中创建空的Python脚本文件并返回脚本文件路径。**辅助脚本本身也使用uv run执行保持一致性。**
**决策:** 创建`skills/lyxy-runner-python/script/get_temp_path.py`辅助脚本使用Python标准库的`tempfile`模块在系统临时目录中创建空的Python脚本文件并返回脚本文件路径。**辅助脚本本身也使用uv run执行保持一致性。**
**理由:**
- `tempfile.gettempdir()`自动适配所有平台Windows/macOS/Linux
@@ -72,7 +72,7 @@ uv是Astral开发的快速Python包管理器支持PEP 723内联元数据格
- **功能**在系统临时目录创建空的Python脚本文件返回文件路径
- **无注释**:脚本只包含必要代码,没有文档字符串或注释
- **PEP 723格式**:包含空的依赖声明`# dependencies = []`
- **执行方式**`uv run skills/python-runner/script/get_temp_path.py`
- **执行方式**`uv run skills/lyxy-runner-python/script/get_temp_path.py`
- **输出**直接在stdout输出临时Python脚本文件的完整路径
- Linux/macOS: `/tmp/uv_script_xxx.py`
- Windows: `C:\Users\<username>\AppData\Local\Temp\uv_script_xxx.py`
@@ -220,13 +220,13 @@ uv是Astral开发的快速Python包管理器支持PEP 723内联元数据格
这是新skill的首次实现不存在迁移问题。
**部署步骤:**
1. 创建skill目录`skills/python-runner/`
2. 创建skill文件`skills/python-runner/SKILL.md`
1. 创建skill目录`skills/lyxy-runner-python/`
2. 创建skill文件`skills/lyxy-runner-python/SKILL.md`
3. 编写skill内容YAML元数据 + Markdown文档
4. 测试skill是否可以被正确加载和触发
**回滚策略:**
- 如有问题,直接删除`skills/python-runner/`目录即可
- 如有问题,直接删除`skills/lyxy-runner-python/`目录即可
- skill文件不影响系统或现有代码
## Open Questions

View File

@@ -9,9 +9,9 @@
## What Changes
**注:** 实现时将技能名称从 `python-runner` 简化为 `python-runner`,以保持命名更通用和简洁,避免与未来可能的其他 Python runner 实现名称冲突。
**注:** 实现时将技能名称从 `lyxy-runner-python` 简化为 `lyxy-runner-python`,以保持命名更通用和简洁,避免与未来可能的其他 Python runner 实现名称冲突。
- 创建新的skill`python-runner` (proposal中为 `python-runner`)
- 创建新的skill`lyxy-runner-python` (proposal中为 `lyxy-runner-python`)
- 指导大模型按照PEP 723规范编写Python脚本
- 提供临时文件创建和uv run执行的标准流程
- 严格错误处理模式
@@ -28,7 +28,7 @@
### New Capabilities
- `python-runner`: 通用Python脚本执行工具指导大模型使用uv的隔离环境特性来执行临时Python脚本无需在系统环境预安装依赖。适用于数据处理、API交互、文件操作、科学计算等各种任务。
- `lyxy-runner-python`: 通用Python脚本执行工具指导大模型使用uv的隔离环境特性来执行临时Python脚本无需在系统环境预安装依赖。适用于数据处理、API交互、文件操作、科学计算等各种任务。
### Modified Capabilities
@@ -36,7 +36,7 @@
## Impact
- **代码影响**新增skill文件 `skills/python-runner/SKILL.md`
- **代码影响**新增skill文件 `skills/lyxy-runner-python/SKILL.md`
- **依赖影响**要求系统安装uvhttps://docs.astral.sh/uv/
- **系统影响**skill只提供指导不直接修改系统
- **API影响**:无

View File

@@ -36,7 +36,7 @@ Skill SHALL指导LLM在系统临时目录中创建临时Python文件并使用
### 需求:跨平台临时目录支持
Skill SHALL使用`skills/python-runner/script/get_temp_path.py`辅助脚本来获取平台特定的临时目录。Skill SHALL在创建临时Python文件之前先调用此辅助脚本获取临时目录路径。Skill SHALL支持Windows、macOS、Linux三个平台。
Skill SHALL使用`skills/lyxy-runner-python/script/get_temp_path.py`辅助脚本来获取平台特定的临时目录。Skill SHALL在创建临时Python文件之前先调用此辅助脚本获取临时目录路径。Skill SHALL支持Windows、macOS、Linux三个平台。
#### 场景:获取临时目录路径
- **WHEN** LLM需要为Python脚本创建临时文件

View File

@@ -1,17 +1,17 @@
## 1. Skill结构设置
- [x] 1.1 创建skill目录`skills/python-runner/`
- [x] 1.2 创建script子目录`skills/python-runner/script/`
- [x] 1.3 创建辅助脚本:`skills/python-runner/script/get_temp_path.py`
- [x] 1.1 创建skill目录`skills/lyxy-runner-python/`
- [x] 1.2 创建script子目录`skills/lyxy-runner-python/script/`
- [x] 1.3 创建辅助脚本:`skills/lyxy-runner-python/script/get_temp_path.py`
- [x] 1.3.1 添加PEP 723元数据块`# dependencies = []`
- [x] 1.3.2 在系统临时目录创建空的Python脚本文件并返回路径
- [x] 1.3.3 直接在stdout输出脚本文件完整路径
- [x] 1.3.4 添加命令行支持,直接运行脚本
- [x] 1.4 创建skill文件`skills/python-runner/SKILL.md`
- [x] 1.4 创建skill文件`skills/lyxy-runner-python/SKILL.md`
## 2. 编写YAML前置元数据
- [x] 2.1 添加skill名称`python-runner`
- [x] 2.1 添加skill名称`lyxy-runner-python`
- [x] 2.2 添加英文skill描述
- [x] 2.3 添加参数提示不适用此skill无参数
@@ -33,7 +33,7 @@
- [x] 5.1.2 提供包含外部依赖的示例
- [x] 5.1.3 提供仅使用标准库的示例
- [x] 5.2 记录步骤2获取临时目录
- [x] 5.2.1 说明调用辅助脚本:`uv run skills/python-runner/script/get_temp_path.py`
- [x] 5.2.1 说明调用辅助脚本:`uv run skills/lyxy-runner-python/script/get_temp_path.py`
- [x] 5.2.2 说明辅助脚本直接在stdout输出临时目录路径
- [x] 5.2.3 说明大模型捕获stdout输出得到临时目录
- [x] 5.2.4 说明根据临时目录构造脚本文件路径:`<temp_dir>/uv_script_<timestamp>_<random>.py`

View File

@@ -1,32 +0,0 @@
## Why
当前项目已有基于uv的Python执行环境(python-runner)但缺少相应的JavaScript/TypeScript执行能力。Bun作为现代JavaScript运行时具有极快的启动速度、内置包管理器和对标准库的完整支持非常适合创建一个类似python-runner的隔离式JS/TS执行环境保持系统环境整洁。
## What Changes
- 完善现有的`skills/js-runner/`目录目前仅有test/axios.js文件
- 基于Bun实现JavaScript/TypeScript脚本执行能力使用临时文件和环境隔离
- 参考python-runner的工作流支持依赖管理通过package.json或内联声明
- 提供辅助脚本生成临时文件路径
- 创建完整的SKILL.md文档
## Capabilities
### New Capabilities
- `js-runner`: 提供基于Bun的JavaScript/TypeScript脚本执行能力支持依赖管理、环境隔离和临时文件清理
### Modified Capabilities
- None
## Impact
**新增文件**:
- `skills/js-runner/SKILL.md` - Skill文档
- `skills/js-runner/scripts/get_temp_path.js` - 临时路径生成辅助脚本
**外部依赖**:
- 需要安装Bun运行时https://bun.sh
**不影响的范围**:
- 不影响现有的python-runner skill
- 不修改其他skill的实现

View File

@@ -1,18 +1,18 @@
## Context背景
本项目在 `skills/` 目录下开发用于大模型工具的技能skills每个子目录代表一个技能。目前项目已经有一个 `python-runner` 技能,它使用 `uv` 提供了隔离的 Python 执行环境,支持依赖管理和临时文件隔离。
本项目在 `skills/` 目录下开发用于大模型工具的技能skills每个子目录代表一个技能。目前项目已经有一个 `lyxy-runner-python` 技能,它使用 `uv` 提供了隔离的 Python 执行环境,支持依赖管理和临时文件隔离。
`js-runner/` 目录已存在但未完成,只包含一个测试文件(`test/axios.js`)。目前项目中还没有功能完整的 JavaScript/TypeScript 执行能力。
`lyxy-runner-js/` 目录已存在但未完成,只包含一个测试文件(`test/axios.js`)。目前项目中还没有功能完整的 JavaScript/TypeScript 执行能力。
**当前状态:**
- `python-runner` 技能已完整实现(基于 uv 的隔离)
- `js-runner` 目录骨架存在但缺少实现
- `lyxy-runner-python` 技能已完整实现(基于 uv 的隔离)
- `lyxy-runner-js` 目录骨架存在但缺少实现
- 没有 JavaScript/TypeScript 的依赖管理机制
- 没有 JS/TS 脚本的临时文件生命周期管理
**约束条件:**
- 必须保持环境隔离(不污染系统包)
- 应遵循 `python-runner` 建立的模式以保持一致性
- 应遵循 `lyxy-runner-python` 建立的模式以保持一致性
- 技能结构必须符合项目规范(`skills/<skill-name>/`
- 必须同时支持 JavaScript 和 TypeScript 执行
@@ -22,13 +22,13 @@
- 提供辅助脚本供大模型调用(使用 JavaScript 编写,与 skill 主题一致)
- 在 SKILL.md 中清晰描述完整的调用流程
- 利用 Bun 的自动依赖管理能力
- 匹配 `python-runner` 的工作流程和用户体验,保持一致性
- 匹配 `lyxy-runner-python` 的工作流程和用户体验,保持一致性
**非目标:**
- 提供完整的 IDE 或开发环境
- 脚本的长期存储或持久化
- 超越 JavaScript/TypeScript 的多语言支持
- 替换或修改现有的 `python-runner` 技能
- 替换或修改现有的 `lyxy-runner-python` 技能
- 构建自定义的 Bun 运行时包装器(直接使用 Bun
## Decisions技术决策
@@ -46,7 +46,7 @@
### 2. 基于临时文件的执行模型
**理由:** 遵循 `python-runner` 的模式,在临时文件中执行脚本可以:
**理由:** 遵循 `lyxy-runner-python` 的模式,在临时文件中执行脚本可以:
- 在执行之间保持干净的隔离
- 自动清理产物
- 不需要跨运行的状态管理
@@ -81,7 +81,7 @@
**理由:** `get_temp_path.js` 辅助脚本将:
- 为脚本生成唯一的临时文件路径
- 遵循特定于操作系统的临时目录约定
- 使用 JavaScript 编写,与 js-runner 主题一致
- 使用 JavaScript 编写,与 lyxy-runner-js 主题一致
- 使用 Bun 运行(已确保环境就绪)
**实现方式:**
@@ -92,7 +92,7 @@ import { join } from "path";
export function getTempPath(extension) {
const timestamp = Date.now();
const random = Math.random().toString(36).substring(7);
return join(tmpdir(), `js-runner-${timestamp}-${random}.${extension}`);
return join(tmpdir(), `lyxy-runner-js-${timestamp}-${random}.${extension}`);
}
```
@@ -127,7 +127,7 @@ export function getTempPath(extension) {
- 记录错误处理和故障排除
**回滚策略:**
- 如果实现有问题,删除 `skills/js-runner/` 目录
- 如果实现有问题,删除 `skills/lyxy-runner-js/` 目录
- 对项目其他部分无影响,因为这是一个新的隔离技能
## Open Questions待解决的问题

View File

@@ -0,0 +1,32 @@
## Why
当前项目已有基于uv的Python执行环境(lyxy-runner-python)但缺少相应的JavaScript/TypeScript执行能力。Bun作为现代JavaScript运行时具有极快的启动速度、内置包管理器和对标准库的完整支持非常适合创建一个类似lyxy-runner-python的隔离式JS/TS执行环境保持系统环境整洁。
## What Changes
- 完善现有的`skills/lyxy-runner-js/`目录目前仅有test/axios.js文件
- 基于Bun实现JavaScript/TypeScript脚本执行能力使用临时文件和环境隔离
- 参考lyxy-runner-python的工作流支持依赖管理通过package.json或内联声明
- 提供辅助脚本生成临时文件路径
- 创建完整的SKILL.md文档
## Capabilities
### New Capabilities
- `lyxy-runner-js`: 提供基于Bun的JavaScript/TypeScript脚本执行能力支持依赖管理、环境隔离和临时文件清理
### Modified Capabilities
- None
## Impact
**新增文件**:
- `skills/lyxy-runner-js/SKILL.md` - Skill文档
- `skills/lyxy-runner-js/scripts/get_temp_path.js` - 临时路径生成辅助脚本
**外部依赖**:
- 需要安装Bun运行时https://bun.sh
**不影响的范围**:
- 不影响现有的lyxy-runner-python skill
- 不修改其他skill的实现

View File

@@ -16,7 +16,7 @@
- **THEN** 文件扩展名为 `.ts`
### Requirement: 文档描述完整调用流程
SKILL.md MUST 清晰描述大模型如何使用 js-runner 技能执行 JavaScript/TypeScript 脚本的完整流程。
SKILL.md MUST 清晰描述大模型如何使用 lyxy-runner-js 技能执行 JavaScript/TypeScript 脚本的完整流程。
#### Scenario: 执行脚本的标准流程
- **WHEN** 大模型阅读 SKILL.md
@@ -72,19 +72,19 @@ SKILL.md MUST 清晰描述大模型如何使用 js-runner 技能执行 JavaScrip
- **THEN** 系统使用退出码 0
### Requirement: 文档完整性
系统 MUST 包含完整的 SKILL.md 文档,说明如何使用 js-runner。
系统 MUST 包含完整的 SKILL.md 文档,说明如何使用 lyxy-runner-js
#### Scenario: SKILL.md 包含必要的 frontmatter
- **WHEN** 大模型阅读 SKILL.md
- **THEN** 文档顶部包含 YAML frontmatter
- **THEN** 包含 `name` 字段,值为 `js-runner`
- **THEN** 包含 `name` 字段,值为 `lyxy-runner-js`
- **THEN** 包含 `description` 字段,描述技能的功能和使用场景
- **THEN** 可选包含 `compatibility` 字段,说明 Bun 依赖
#### Scenario: 安装说明
- **WHEN** 用户阅读 SKILL.md
- **THEN** 文档包含 Bun 的安装说明和命令
- **THEN** 文档说明 js-runner 的依赖要求
- **THEN** 文档说明 lyxy-runner-js 的依赖要求
#### Scenario: 使用示例
- **WHEN** 用户阅读 SKILL.md

View File

@@ -1,13 +1,13 @@
## 1. 项目设置和目录结构
- [x] 1.1 验证 `skills/js-runner/` 目录结构
- [x] 1.2 创建 `skills/js-runner/scripts/` 目录(注意是复数 scripts/
- [x] 1.3 确认现有测试文件 `skills/js-runner/test/axios.js` 的状态
- [x] 1.1 验证 `skills/lyxy-runner-js/` 目录结构
- [x] 1.2 创建 `skills/lyxy-runner-js/scripts/` 目录(注意是复数 scripts/
- [x] 1.3 确认现有测试文件 `skills/lyxy-runner-js/test/axios.js` 的状态
- [x] 1.4 验证 Bun 运行时是否已安装(本地开发环境)
## 2. 实现临时路径生成辅助脚本
- [x] 2.1 创建 `skills/js-runner/scripts/get_temp_path.js` 文件(使用 JavaScript
- [x] 2.1 创建 `skills/lyxy-runner-js/scripts/get_temp_path.js` 文件(使用 JavaScript
- [x] 2.2 实现 `getTempPath(extension)` 函数
- [x] 2.3 确保函数生成唯一路径(包含时间戳和随机字符串)
- [x] 2.4 测试辅助脚本的输出格式正确性
@@ -15,9 +15,9 @@
## 3. 编写 SKILL.md 文档
- [x] 3.1 创建 `skills/js-runner/SKILL.md` 文档
- [x] 3.1 创建 `skills/lyxy-runner-js/SKILL.md` 文档
- [x] 3.2 添加必要的 YAML frontmatter
- `name: js-runner`
- `name: lyxy-runner-js`
- `description` 描述功能和场景
- 可选 `compatibility` 说明 Bun 依赖
- [x] 3.3 编写 Bun 安装说明和先决条件
@@ -36,7 +36,7 @@
## 4. 验证 SKILL.md 格式
- [x] 4.1 使用 `skills-ref validate ./skills/js-runner` 验证格式(如果可用)
- [x] 4.1 使用 `skills-ref validate ./skills/lyxy-runner-js` 验证格式(如果可用)
- [x] 4.2 确认 frontmatter 符合 Agent Skills 规范
- [x] 4.3 确认 name 字段格式正确(小写、数字、连字符)
- [x] 4.4 确认 description 字段长度在 1024 字符以内
@@ -47,5 +47,5 @@
- [x] 5.1 手动测试 `scripts/get_temp_path.js` 辅助脚本
- [x] 5.2 验证 SKILL.md 格式符合规范
- [x] 5.3 验证调用流程的可行性
- [x] 5.4 验证与 `python-runner` 模式的一致性
- [x] 5.4 验证与 `lyxy-runner-python` 模式的一致性
- [x] 5.5 提交所有更改到版本控制(如适用)

View File

@@ -1,27 +0,0 @@
## Why
当前 js-runner 技能的标准流程中,所有脚本执行都必须使用 `get_temp_path.js` 生成临时文件路径。这导致当用户想要运行已存在的脚本文件或希望将脚本持久化到特定位置时,流程不够灵活。大模型已经拥有可以直接创建文件的工具(如 Write 工具),不需要强制通过临时路径生成脚本。
## What Changes
- 增加条件判断逻辑:只有当用户没有指定脚本文件或没有指定脚本生成路径时,才使用 `get_temp_path.js` 生成临时路径
- 增加直接执行已存在脚本文件的使用场景
- 增加使用大模型工具在指定路径创建脚本的使用场景
- 保持向后兼容:不提供路径或脚本时,仍使用原有的临时文件路径生成逻辑
## Capabilities
### New Capabilities
无 - 本变更是在现有 js-runner 技能基础上的增强
### Modified Capabilities
- `js-runner`: 增加条件性使用临时路径的需求。这将修改现有的"文档描述完整调用流程"需求,增加新的场景:
- 场景1用户提供已存在的脚本文件路径 → 直接执行
- 场景2用户提供脚本生成路径 → 用大模型工具创建脚本到指定路径,然后执行
- 场景3用户未提供任何路径信息 → 使用 `get_temp_path.js` 生成临时路径(现有流程)
## Impact
- **文档更新**: `skills/js-runner/SKILL.md` 需要重新组织调用流程说明,增加条件判断逻辑和新的使用场景
- **规范更新**: `openspec/specs/js-runner/spec.md` 需要增加新的需求场景,描述不同条件下的执行路径选择
- **代码**: `get_temp_path.js` 保持不变,仅在未提供路径时调用

View File

@@ -1,6 +1,6 @@
## Context
js-runner 技能目前的标准流程假设所有脚本都需要通过临时文件执行。这种设计确保了脚本的隔离性和自动清理,但牺牲了灵活性。用户可能希望:
lyxy-runner-js 技能目前的标准流程假设所有脚本都需要通过临时文件执行。这种设计确保了脚本的隔离性和自动清理,但牺牲了灵活性。用户可能希望:
1. 执行已存在的脚本文件
2. 将脚本持久化到项目中的特定位置
3. 利用大模型已有的文件操作工具Write直接创建脚本
@@ -27,7 +27,7 @@ js-runner 技能目前的标准流程假设所有脚本都需要通过临时文
**决策选择:** 通过更新 SKILL.md 文档来定义新的使用流程,而不是修改代码实现。
**理由:**
- js-runner 的核心功能(脚本执行)已经完全由 Bun 运行时提供
- lyxy-runner-js 的核心功能(脚本执行)已经完全由 Bun 运行时提供
- 大模型根据 SKILL.md 的描述来选择操作方式
- 当前代码(`get_temp_path.js`)在临时路径场景下已经完全满足需求
- 直接使用大模型的 Write 工具创建文件比通过辅助脚本更灵活
@@ -80,15 +80,15 @@ js-runner 技能目前的标准流程假设所有脚本都需要通过临时文
**说明:**
- 用户获得了更多控制权(直接指定路径)
- 文档需要更详细地解释不同场景
- 但这符合 js-runner 作为"技能工具"的定位——为大模型提供灵活的执行选项
- 但这符合 lyxy-runner-js 作为"技能工具"的定位——为大模型提供灵活的执行选项
## Migration Plan
本变更仅涉及文档更新,无需代码迁移或部署步骤。
**更新步骤:**
1. 更新 `skills/js-runner/SKILL.md`,增加三种使用场景的说明
2. 更新 `openspec/specs/js-runner/spec.md`,增加新的需求场景
1. 更新 `skills/lyxy-runner-js/SKILL.md`,增加三种使用场景的说明
2. 更新 `openspec/specs/lyxy-runner-js/spec.md`,增加新的需求场景
3. 验证文档描述是否清晰,易于理解和执行
**回滚策略:**

View File

@@ -0,0 +1,27 @@
## Why
当前 lyxy-runner-js 技能的标准流程中,所有脚本执行都必须使用 `get_temp_path.js` 生成临时文件路径。这导致当用户想要运行已存在的脚本文件或希望将脚本持久化到特定位置时,流程不够灵活。大模型已经拥有可以直接创建文件的工具(如 Write 工具),不需要强制通过临时路径生成脚本。
## What Changes
- 增加条件判断逻辑:只有当用户没有指定脚本文件或没有指定脚本生成路径时,才使用 `get_temp_path.js` 生成临时路径
- 增加直接执行已存在脚本文件的使用场景
- 增加使用大模型工具在指定路径创建脚本的使用场景
- 保持向后兼容:不提供路径或脚本时,仍使用原有的临时文件路径生成逻辑
## Capabilities
### New Capabilities
无 - 本变更是在现有 lyxy-runner-js 技能基础上的增强
### Modified Capabilities
- `lyxy-runner-js`: 增加条件性使用临时路径的需求。这将修改现有的"文档描述完整调用流程"需求,增加新的场景:
- 场景1用户提供已存在的脚本文件路径 → 直接执行
- 场景2用户提供脚本生成路径 → 用大模型工具创建脚本到指定路径,然后执行
- 场景3用户未提供任何路径信息 → 使用 `get_temp_path.js` 生成临时路径(现有流程)
## Impact
- **文档更新**: `skills/lyxy-runner-js/SKILL.md` 需要重新组织调用流程说明,增加条件判断逻辑和新的使用场景
- **规范更新**: `openspec/specs/lyxy-runner-js/spec.md` 需要增加新的需求场景,描述不同条件下的执行路径选择
- **代码**: `get_temp_path.js` 保持不变,仅在未提供路径时调用

View File

@@ -18,7 +18,7 @@
## MODIFIED Requirements
### Requirement: 文档描述完整调用流程
SKILL.md MUST 清晰描述大模型如何使用 js-runner 技能执行 JavaScript/TypeScript 脚本的完整流程,并根据用户提供的路径信息选择不同的执行方式。
SKILL.md MUST 清晰描述大模型如何使用 lyxy-runner-js 技能执行 JavaScript/TypeScript 脚本的完整流程,并根据用户提供的路径信息选择不同的执行方式。
#### Scenario: 执行已存在的脚本文件
- **WHEN** 用户提供已存在的脚本文件路径

View File

@@ -1,6 +1,6 @@
## 1. 文档准备工作
- [x] 1.1 读取当前的 `skills/js-runner/SKILL.md` 文件,了解现有结构
- [x] 1.1 读取当前的 `skills/lyxy-runner-js/SKILL.md` 文件,了解现有结构
- [x] 1.2 确认文档中现有的安装说明和基本使用流程
## 2. 文档结构调整

View File

@@ -1,6 +1,6 @@
## Context
当前python-runner skill要求用户在Python脚本顶部添加PEP 723元数据块来声明依赖这需要修改用户现有的脚本文件降低了使用便利性。此外现有实现总是使用临时文件即使在用户明确指定路径时也是如此。
当前lyxy-runner-python skill要求用户在Python脚本顶部添加PEP 723元数据块来声明依赖这需要修改用户现有的脚本文件降低了使用便利性。此外现有实现总是使用临时文件即使在用户明确指定路径时也是如此。
该skill目前的工作流程
1. 要求LLM生成包含PEP 723元数据的Python脚本

View File

@@ -1,6 +1,6 @@
## Why
当前python-runner skill要求使用PEP 723规范在脚本顶部添加内联元数据块来声明依赖这需要修改用户现有的Python脚本降低了使用便利性。通过改用`uv run --with`语法并自动解析脚本内容中的依赖可以在不改动用户脚本的情况下利用uv的隔离环境直接运行脚本提升用户体验和灵活性。
当前lyxy-runner-python skill要求使用PEP 723规范在脚本顶部添加内联元数据块来声明依赖这需要修改用户现有的Python脚本降低了使用便利性。通过改用`uv run --with`语法并自动解析脚本内容中的依赖可以在不改动用户脚本的情况下利用uv的隔离环境直接运行脚本提升用户体验和灵活性。
## What Changes
@@ -23,12 +23,12 @@
- `uv-run-with-syntax`: 使用`uv run --with`语法执行Python脚本的能力包括自动依赖解析和智能项目检测
### Modified Capabilities
- `uv-python-runner`: 现有spec需要更新以反映新的执行流程包括移除PEP 723要求、新增依赖解析逻辑、新增智能路径和项目检测
- `uv-lyxy-runner-python`: 现有spec需要更新以反映新的执行流程包括移除PEP 723要求、新增依赖解析逻辑、新增智能路径和项目检测
## Impact
- **代码影响**
- 修改`skills/python-runner/SKILL.md`,更新执行工作流和示例
- 修改`skills/lyxy-runner-python/SKILL.md`,更新执行工作流和示例
- 保留现有的`get_temp_path.py`辅助脚本
- 不新增辅助脚本,项目检测直接使用命令行工具
- **行为影响**

View File

@@ -2,7 +2,7 @@
## Purpose
This is a delta spec documenting changes to the existing uv-python-runner capability to support `uv run --with` syntax and smart project detection.
This is a delta spec documenting changes to the existing uv-lyxy-runner-python capability to support `uv run --with` syntax and smart project detection.
## REMOVED Requirements

View File

@@ -1,7 +1,7 @@
## 1. 文档准备
- [x] 1.1 备份现有 SKILL.md 文件为 SKILL.md.backup
- [x] 1.2 阅读 python-runner skill 文档结构,了解现有内容组织方式
- [x] 1.2 阅读 lyxy-runner-python skill 文档结构,了解现有内容组织方式
## 2. 移除PEP 723相关内容

View File

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-02-12

View File

@@ -0,0 +1,106 @@
## Context
当前项目是一个专门用于开发大模型工具 skill 的项目。`skills/lyxy-reader-docx` 目录已经存在,其中包含:
- `scripts/docx_parser.py` - 完整的 DOCX 解析脚本支持多策略解析MarkItDown、python-docx、XML 原生)
- `docx_parser.md` - 脚本使用文档
需要将这些现有资源封装为一个标准的 skill让大模型能够识别并优先使用该工具处理 .docx 文件。
## Goals / Non-Goals
**Goals:**
- 创建 `skills/lyxy-reader-docx/skill.md` skill 定义文件,符合项目规范
- 封装 docx_parser.py 的核心功能为 skill 的能力描述
- 确保大模型在遇到 .docx 文件时能够识别并优先使用该 skill
- 执行时优先委托给 lyxy-runner-python skill利用其依赖管理和环境隔离能力
- 支持多种解析模式:全文提取、标题提取、章节内容提取、关键词搜索
**Non-Goals:**
- 修改现有的 docx_parser.py 脚本逻辑
- 添加图片或格式提取功能
- 实现 docx 文件的编辑或修改功能
- 支持 .doc 或其他文档格式
## Decisions
### 1. Skill 定义结构
**决策**: 采用标准的 skill.md 格式,包含 description、capabilities 等核心字段
**理由**: 遵循项目现有 skill 的统一规范,便于大模型理解和调用。查看 `skills/` 目录下的其他 skill 示例(如 `lyxy-runner-python``lyxy-runner-js`)可知项目有一致的定义格式。
### 2. 依赖声明
**决策**: 在 skill.md 的 Compatibility 字段中声明 Python 运行时依赖
**理由**: docx_parser.py 需要 Python 3.6+ 环境,并且需要至少安装 `markitdown``python-docx` 之一。明确这些依赖可以帮助大模型判断环境是否就绪。
### 3. 能力映射
**决策**: 将 docx_parser.py 的所有功能映射为 skill 的 capabilities
**理由**: 脚本提供了丰富的功能(全文、字数、行数、标题、章节、搜索),全部暴露给大模型可以提供更灵活的使用方式。能力包括:
- 全文转换为 Markdown
- 获取文档元信息(字数、行数)
- 标题列表提取
- 指定章节内容提取
- 正则表达式搜索
### 4. 触发器设计
**决策**: 设置明确的触发器Trigger phrases包括中文和英文
**理由**: 用户可能使用中文或英文请求解析 docx 文档。触发器包括:
- "读取 docx", "解析 docx", "打开 word 文档"(中文)
- "read docx", "parse docx", "extract from word document"(英文)
- 文件扩展名 `.docx` 出现时
### 5. 执行委托策略
**决策**: lyxy-reader-docx skill 执行时优先委托给 lyxy-runner-python skill
**理由**: lyxy-runner-python skill 提供了统一的 Python 脚本执行环境,具有以下优势:
- 使用 uv 管理依赖,自动安装 markitdown 或 python-docx
- 环境隔离,不污染系统 Python
- 跨平台兼容
**执行策略**:
此 skill 的执行决策由大模型在调用时判断,不在 skill 定义或脚本中实现检查逻辑。
当大模型决定执行 docx_reader skill 时:
- 如果环境中存在 lyxy-runner-python skill优先使用 lyxy-runner-python 执行 docx_parser.py
- 如果环境中不存在 lyxy-runner-python skill直接使用 Python 执行 docx_parser.py
**好处**:
- 最大化复用现有 skill
- 自动处理 Python 依赖管理(通过 lyxy-runner-python
- 提供更好的错误处理和用户体验
## Risks / Trade-offs
### 风险 1: lyxy-runner-python skill 不可用
**风险**: 目标环境可能没有安装 lyxy-runner-python skill 或其依赖uv 工具)
**缓解措施**:
- 大模型在执行时判断 lyxy-runner-python skill 是否存在
- 如果 lyxy-runner-python 不可用,自动降级为直接使用 Python 执行脚本
- 在 skill.md 中说明降级策略和直接执行的条件
### 风险 2: 依赖库未安装(降级场景)
**风险**: 当 lyxy-runner-python 不可用时,直接执行脚本可能遇到 `markitdown``python-docx` 未安装的情况
**缓解措施**:
- 在 skill.md 的 Compatibility 字段中明确列出可选依赖
- 在降级场景中脚本本身已实现多策略降级MarkItDown → python-docx → XML 原生)
- 提示用户安装 lyxy-runner-python 获得更好的体验
### 风险 2: 大文件处理性能
**风险**: 大型 .docx 文件解析可能耗时较长
**缓解措施**:
- 在能力描述中提示可以使用章节提取或关键词搜索来限制处理范围
- docx_parser.py 已实现流式处理,内存占用相对较低
### 权衡: 纯文本 vs 格式保留
**权衡**: 选择只提取纯文本,不保留图片和复杂格式
**理由**: 用户明确要求"只能将docx文档转换为文字",且大模型主要关注文本内容。虽然脚本支持 Markdown 格式转换(表格、粗体、斜体等),但图片会被自动移除,符合需求。
## Open Questions
无重大未决问题。设计清晰明确,可以直接进入实现阶段。

View File

@@ -0,0 +1,25 @@
## Why
大模型在处理 Word 文档时缺乏统一的解析工具,需要能够直接识别并解析 .docx 文件能力的 skill。现有的 docx_parser.py 脚本已经实现了完整的解析功能,将其封装为 skill 可以让大模型在遇到需要读取 docx 文档的场景时优先使用该工具。
## What Changes
- 新增 `lyxy-reader-docx` skill封装现有的 `skills/lyxy-reader-docx/scripts/docx_parser.py` 脚本
- 创建 skill 定义文件,支持将 .docx 文件转换为纯文本内容
- skill 定位为 docx 文档解析的优先选择工具
- 仅支持文本内容提取,不处理图片和格式信息
## Capabilities
### New Capabilities
- `docx-text-extraction`: 将 DOCX 文档转换为 Markdown 格式文本的能力,支持全文提取、标题提取、章节内容提取和关键词搜索
### Modified Capabilities
-
## Impact
- 新增 `skills/lyxy-reader-docx/skill.md` - skill 定义文件
- 依赖现有的 `skills/lyxy-reader-docx/scripts/docx_parser.py` 解析脚本
- 新增 Python 依赖:`markitdown``python-docx`(至少需要安装其一)
- 影响大模型的技能调用策略,在遇到 .docx 文件时会优先使用该 skill

View File

@@ -0,0 +1,132 @@
## ADDED Requirements
### Requirement: Delegate execution to lyxy-runner-python skill
当大模型执行 lyxy-reader-docx skill 时,应优先使用 lyxy-runner-python skill 来运行 docx_parser.py 脚本。如果 lyxy-runner-python skill 不可用,则直接使用 Python 执行。
#### Scenario: lyxy-runner-python available
- **WHEN** 大模型环境中存在 lyxy-runner-python skill
- **THEN** 大模型通过 lyxy-runner-python skill 执行 docx_parser.py
- **AND** 利用 lyxy-runner-python 的自动依赖管理功能安装所需的 Python 包markitdown 或 python-docx
#### Scenario: lyxy-runner-python unavailable
- **WHEN** 大模型环境中不存在 lyxy-runner-python skill
- **THEN** 大模型直接使用 Python 执行 docx_parser.py
- **AND** 提示用户正在使用直接执行模式(未使用 lyxy-runner-python
- **AND** 依赖 docx_parser.py 内部的多策略解析降级机制
### Requirement: Extract full text from DOCX file
系统 SHALL 能够将 DOCX 文件完整解析为 Markdown 格式的文本内容,移除所有图片但保留文本格式(如标题、列表、粗体、斜体、表格)。
#### Scenario: Successful full text extraction
- **WHEN** 用户请求解析一个有效的 .docx 文件
- **THEN** 系统返回完整的 Markdown 格式文本
- **AND** 所有文本内容被保留
- **AND** 所有图片被移除
- **AND** 表格、列表、粗体、斜体等格式被转换为 Markdown 语法
- **AND** 连续的空行被合并为一个空行
#### Scenario: Invalid DOCX file
- **WHEN** 提供的文件不是有效的 DOCX 格式或已损坏
- **THEN** 系统返回错误信息
- **AND** 错误信息明确说明文件格式问题
#### Scenario: Empty DOCX file
- **WHEN** 提供的 DOCX 文件为空或无文本内容
- **THEN** 系统返回空字符串或相应的提示信息
### Requirement: Extract document metadata
系统 SHALL 能够提供 DOCX 文档的元数据信息,包括字数和行数。
#### Scenario: Get word count
- **WHEN** 用户请求获取 DOCX 文档的字数
- **THEN** 系统返回文档的总字数(数字)
- **AND** 字数统计基于解析后的 Markdown 内容
#### Scenario: Get line count
- **WHEN** 用户请求获取 DOCX 文档的行数
- **THEN** 系统返回文档的总行数(数字)
- **AND** 行数统计基于解析后的 Markdown 内容
### Requirement: Extract document titles
系统 SHALL 能够提取 DOCX 文档中的所有标题1-6级标题并按原始层级关系返回。
#### Scenario: Extract all titles
- **WHEN** 用户请求提取 DOCX 文档的所有标题
- **THEN** 系统返回所有 1-6 级标题
- **AND** 每个标题以 Markdown 标题格式返回(如 `# 主标题``## 二级标题`
- **AND** 标题按文档中的原始顺序返回
- **AND** 保留原始标题层级关系
#### Scenario: Document with no titles
- **WHEN** DOCX 文档中不包含任何标题
- **THEN** 系统返回空列表或无标题提示
### Requirement: Extract chapter content by title name
系统 SHALL 能够根据标题名称提取指定章节的内容,包括完整的上级标题链和所有下级内容。
#### Scenario: Extract single chapter content
- **WHEN** 用户请求提取特定标题名称的章节内容
- **THEN** 系统返回该章节的完整内容
- **AND** 包含完整的上级标题链(如:主标题 -> 章标题 -> 小节)
- **AND** 包含该标题下的所有下级内容
- **AND** 返回内容使用 Markdown 格式
#### Scenario: Extract multiple chapters with same name
- **WHEN** 文档中存在多个同名标题且用户请求提取该标题内容
- **THEN** 系统返回所有同名标题的章节内容
- **AND** 每个章节都包含其完整的上级标题链
- **AND** 各章节内容之间有明确的分隔
#### Scenario: Title not found
- **WHEN** 用户请求提取的标题名称在文档中不存在
- **THEN** 系统返回未找到标题的错误信息
### Requirement: Search document with regex
系统 SHALL 能够使用正则表达式在 DOCX 文档中搜索关键词,并返回所有匹配结果及其上下文。
#### Scenario: Basic keyword search
- **WHEN** 用户使用关键词搜索 DOCX 文档
- **THEN** 系统返回所有匹配的文本片段
- **AND** 每个结果包含默认的上下文(前后各 2 行)
- **AND** 各结果之间使用 `---` 分隔
- **AND** 上下文行数不包含空行
#### Scenario: Custom context lines
- **WHEN** 用户指定上下文行数进行搜索
- **THEN** 系统按指定行数返回上下文
- **AND** 支持 0 行上下文(仅返回匹配行)
- **AND** 上下文行数不包含空行
#### Scenario: Regex pattern search
- **WHEN** 用户使用正则表达式模式搜索
- **THEN** 系统支持 Python 标准正则表达式语法
- **AND** 正确处理特殊字符的转义
- **AND** 返回所有匹配模式的文本片段
#### Scenario: No matches found
- **WHEN** 搜索关键词或模式在文档中无匹配
- **THEN** 系统返回未找到匹配的提示信息
#### Scenario: Invalid regex pattern
- **WHEN** 用户提供的正则表达式格式无效
- **THEN** 系统返回正则表达式无效的错误信息
### Requirement: Multi-strategy parsing fallback
系统 SHALL 按优先级尝试多种解析策略,确保最大的兼容性。
#### Scenario: Prefer MarkItDown parser
- **WHEN** 系统检测到 `markitdown` 库已安装
- **THEN** 系统优先使用 MarkItDown 解析器解析 DOCX 文件
#### Scenario: Fallback to python-docx
- **WHEN** MarkItDown 解析失败或未安装,且 `python-docx` 库已安装
- **THEN** 系统使用 python-docx 作为备选解析器
#### Scenario: Fallback to XML parsing
- **WHEN** MarkItDown 和 python-docx 均未安装或解析失败
- **THEN** 系统使用 XML 原生解析作为最后备选方案
#### Scenario: All parsers failed
- **WHEN** 所有解析策略均失败
- **THEN** 系统返回详细的失败信息
- **AND** 列出每种解析策略的失败原因

View File

@@ -0,0 +1,27 @@
## 1. 准备工作
- [x] 1.1 研究现有 skill 定义格式,查看 `skills/` 目录下的其他 skill 示例(如 `lyxy-runner-python``lyxy-runner-js`)了解标准结构
- [x] 1.2 阅读 `skills/lyxy-reader-docx/docx_parser.md` 了解解析脚本的详细功能和使用方式
## 2. 创建 skill 定义文件
- [x] 2.1 创建 `skills/lyxy-reader-docx/skill.md` 文件
- [x] 2.2 编写 skill 的 description 字段,描述该 skill 的用途和定位(优先解析 docx 文档)
- [x] 2.3 编写 skill 的 capabilities 字段,列出所有支持的解析功能:
- 全文转换为 Markdown
- 获取文档元信息(字数、行数)
- 标题列表提取
- 指定章节内容提取
- 正则表达式搜索
- [x] 2.4 编写 skill 的 Compatibility 字段,声明 Python 3.6+ 和依赖库要求markitdown 或 python-docx 至少安装其一)
- [x] 2.5 编写 skill 的 Triggers 字段,包含中文和英文触发短语:
- 中文:"读取 docx", "解析 docx", "打开 word 文档"
- 英文:"read docx", "parse docx", "extract from word document"
- 文件扩展名 ".docx"
## 3. 验证和测试
- [x] 3.1 验证 skill.md 文件格式是否符合项目规范
- [x] 3.2 确认 skill.md 中的触发器能够正确识别 docx 解析需求
- [x] 3.3 确认 skill.md 中的依赖说明清晰准确
- [x] 3.4 确认 skill.md 的 capabilities 覆盖了 docx_parser.py 的所有功能

View File

@@ -0,0 +1,132 @@
## Requirements
### Requirement: Delegate execution to lyxy-runner-python skill
当大模型执行 lyxy-reader-docx skill 时,应优先使用 lyxy-runner-python skill 来运行 docx_parser.py 脚本。如果 lyxy-runner-python skill 不可用,则直接使用 Python 执行。
#### Scenario: lyxy-runner-python available
- **WHEN** 大模型环境中存在 lyxy-runner-python skill
- **THEN** 大模型通过 lyxy-runner-python skill 执行 docx_parser.py
- **AND** 利用 lyxy-runner-python 的自动依赖管理功能安装所需的 Python 包markitdown 或 python-docx
#### Scenario: lyxy-runner-python unavailable
- **WHEN** 大模型环境中不存在 lyxy-runner-python skill
- **THEN** 大模型直接使用 Python 执行 docx_parser.py
- **AND** 提示用户正在使用直接执行模式(未使用 lyxy-runner-python
- **AND** 依赖 docx_parser.py 内部的多策略解析降级机制
### Requirement: Extract full text from DOCX file
系统 SHALL 能够将 DOCX 文件完整解析为 Markdown 格式的文本内容,移除所有图片但保留文本格式(如标题、列表、粗体、斜体、表格)。
#### Scenario: Successful full text extraction
- **WHEN** 用户请求解析一个有效的 .docx 文件
- **THEN** 系统返回完整的 Markdown 格式文本
- **AND** 所有文本内容被保留
- **AND** 所有图片被移除
- **AND** 表格、列表、粗体、斜体等格式被转换为 Markdown 语法
- **AND** 连续的空行被合并为一个空行
#### Scenario: Invalid DOCX file
- **WHEN** 提供的文件不是有效的 DOCX 格式或已损坏
- **THEN** 系统返回错误信息
- **AND** 错误信息明确说明文件格式问题
#### Scenario: Empty DOCX file
- **WHEN** 提供的 DOCX 文件为空或无文本内容
- **THEN** 系统返回空字符串或相应的提示信息
### Requirement: Extract document metadata
系统 SHALL 能够提供 DOCX 文档的元数据信息,包括字数和行数。
#### Scenario: Get word count
- **WHEN** 用户请求获取 DOCX 文档的字数
- **THEN** 系统返回文档的总字数(数字)
- **AND** 字数统计基于解析后的 Markdown 内容
#### Scenario: Get line count
- **WHEN** 用户请求获取 DOCX 文档的行数
- **THEN** 系统返回文档的总行数(数字)
- **AND** 行数统计基于解析后的 Markdown 内容
### Requirement: Extract document titles
系统 SHALL 能够提取 DOCX 文档中的所有标题1-6级标题并按原始层级关系返回。
#### Scenario: Extract all titles
- **WHEN** 用户请求提取 DOCX 文档的所有标题
- **THEN** 系统返回所有 1-6 级标题
- **AND** 每个标题以 Markdown 标题格式返回(如 `# 主标题``## 二级标题`
- **AND** 标题按文档中的原始顺序返回
- **AND** 保留原始标题层级关系
#### Scenario: Document with no titles
- **WHEN** DOCX 文档中不包含任何标题
- **THEN** 系统返回空列表或无标题提示
### Requirement: Extract chapter content by title name
系统 SHALL 能够根据标题名称提取指定章节的内容,包括完整的上级标题链和所有下级内容。
#### Scenario: Extract single chapter content
- **WHEN** 用户请求提取特定标题名称的章节内容
- **THEN** 系统返回该章节的完整内容
- **AND** 包含完整的上级标题链(如:主标题 -> 章标题 -> 小节)
- **AND** 包含该标题下的所有下级内容
- **AND** 返回内容使用 Markdown 格式
#### Scenario: Extract multiple chapters with same name
- **WHEN** 文档中存在多个同名标题且用户请求提取该标题内容
- **THEN** 系统返回所有同名标题的章节内容
- **AND** 每个章节都包含其完整的上级标题链
- **AND** 各章节内容之间有明确的分隔
#### Scenario: Title not found
- **WHEN** 用户请求提取的标题名称在文档中不存在
- **THEN** 系统返回未找到标题的错误信息
### Requirement: Search document with regex
系统 SHALL 能够使用正则表达式在 DOCX 文档中搜索关键词,并返回所有匹配结果及其上下文。
#### Scenario: Basic keyword search
- **WHEN** 用户使用关键词搜索 DOCX 文档
- **THEN** 系统返回所有匹配的文本片段
- **AND** 每个结果包含默认的上下文(前后各 2 行)
- **AND** 各结果之间使用 `---` 分隔
- **AND** 上下文行数不包含空行
#### Scenario: Custom context lines
- **WHEN** 用户指定上下文行数进行搜索
- **THEN** 系统按指定行数返回上下文
- **AND** 支持 0 行上下文(仅返回匹配行)
- **AND** 上下文行数不包含空行
#### Scenario: Regex pattern search
- **WHEN** 用户使用正则表达式模式搜索
- **THEN** 系统支持 Python 标准正则表达式语法
- **AND** 正确处理特殊字符的转义
- **AND** 返回所有匹配模式的文本片段
#### Scenario: No matches found
- **WHEN** 搜索关键词或模式在文档中无匹配
- **THEN** 系统返回未找到匹配的提示信息
#### Scenario: Invalid regex pattern
- **WHEN** 用户提供的正则表达式格式无效
- **THEN** 系统返回正则表达式无效的错误信息
### Requirement: Multi-strategy parsing fallback
系统 SHALL 按优先级尝试多种解析策略,确保最大的兼容性。
#### Scenario: Prefer MarkItDown parser
- **WHEN** 系统检测到 `markitdown` 库已安装
- **THEN** 系统优先使用 MarkItDown 解析器解析 DOCX 文件
#### Scenario: Fallback to python-docx
- **WHEN** MarkItDown 解析失败或未安装,且 `python-docx` 库已安装
- **THEN** 系统使用 python-docx 作为备选解析器
#### Scenario: Fallback to XML parsing
- **WHEN** MarkItDown 和 python-docx 均未安装或解析失败
- **THEN** 系统使用 XML 原生解析作为最后备选方案
#### Scenario: All parsers failed
- **WHEN** 所有解析策略均失败
- **THEN** 系统返回详细的失败信息
- **AND** 列出每种解析策略的失败原因

View File

@@ -1,8 +1,8 @@
# JS Runner Spec
# lyxy-runner-js Spec
## Purpose
Define requirements for the js-runner skill, which enables execution of JavaScript and TypeScript scripts using Bun runtime with automatic dependency management and temporary file handling.
Define requirements for the lyxy-runner-js skill, which enables execution of JavaScript and TypeScript scripts using Bun runtime with automatic dependency management and temporary file handling.
## Requirements
@@ -37,7 +37,7 @@ Define requirements for the js-runner skill, which enables execution of JavaScri
- **THEN** 文件扩展名为 `.ts`
### Requirement: 文档描述完整调用流程
SKILL.md MUST 清晰描述大模型如何使用 js-runner 技能执行 JavaScript/TypeScript 脚本的完整流程,并根据用户提供的路径信息选择不同的执行方式。
SKILL.md MUST 清晰描述大模型如何使用 lyxy-runner-js 技能执行 JavaScript/TypeScript 脚本的完整流程,并根据用户提供的路径信息选择不同的执行方式。
#### Scenario: 执行已存在的脚本文件
- **WHEN** 用户提供已存在的脚本文件路径
@@ -131,19 +131,19 @@ SKILL.md MUST 清晰描述大模型如何使用 js-runner 技能执行 JavaScrip
- **THEN** 系统使用退出码 0
### Requirement: 文档完整性
系统 MUST 包含完整的 SKILL.md 文档,说明如何使用 js-runner。
系统 MUST 包含完整的 SKILL.md 文档,说明如何使用 lyxy-runner-js
#### Scenario: SKILL.md 包含必要的 frontmatter
- **WHEN** 大模型阅读 SKILL.md
- **THEN** 文档顶部包含 YAML frontmatter
- **THEN** 包含 `name` 字段,值为 `js-runner`
- **THEN** 包含 `name` 字段,值为 `lyxy-runner-js`
- **THEN** 包含 `description` 字段,描述技能的功能和使用场景
- **THEN** 可选包含 `compatibility` 字段,说明 Bun 依赖
#### Scenario: 安装说明
- **WHEN** 用户阅读 SKILL.md
- **THEN** 文档包含 Bun 的安装说明和命令
- **THEN** 文档说明 js-runner 的依赖要求
- **THEN** 文档说明 lyxy-runner-js 的依赖要求
#### Scenario: 使用示例
- **WHEN** 用户阅读 SKILL.md

View File

@@ -2,7 +2,7 @@
## Purpose
Define requirements for the python-runner skill, which enables execution of Python scripts using uv with automatic dependency parsing, smart project detection, and flexible path handling.
Define requirements for the lyxy-runner-python skill, which enables execution of Python scripts using uv with automatic dependency parsing, smart project detection, and flexible path handling.
## Requirements

View File

@@ -0,0 +1,279 @@
---
name: lyxy-reader-docx
description: 优先解析 docx 文档的 skill将 DOCX 文件转换为纯文本内容,不支持图片和格式提取。
compatibility: Requires Python 3.6+ and at least one of: markitdown or python-docx
---
# DOCX 文档解析 Skill
将 Microsoft Word (.docx) 文档解析为纯文本内容,支持多种解析模式和检索功能。
## Purpose
**依赖选项**: 此 skill 可以使用 lyxy-runner-python skill推荐或直接使用 Python 执行。
### 优先使用 lyxy-runner-python
如果环境中存在 lyxy-runner-python skill应优先使用它来执行 docx_parser.py 脚本:
- lyxy-runner-python 使用 uv 管理依赖,自动安装 markitdown 或 python-docx
- 环境隔离,不污染系统 Python
- 跨平台兼容Windows/macOS/Linux
### 降级到直接执行
如果环境中不存在 lyxy-runner-python skill则直接使用 Python 执行 docx_parser.py
- 需要手动安装 markitdown 或 python-docx
- 脚本内部实现了多策略解析降级MarkItDown → python-docx → XML 原生
## When to Use
任何需要读取或解析 .docx 文件内容的任务都应使用此 skill。
### 典型场景
- **文档内容提取**: 将 Word 文档转换为可读的文本内容
- **文档元数据**: 获取文档的字数、行数等信息
- **标题分析**: 提取文档的标题结构
- **章节提取**: 提取特定章节的内容
- **内容搜索**: 在文档中搜索关键词或模式
### 不适用场景
- ✗ 需要提取图片内容(仅支持纯文本)
- ✗ 需要保留复杂的格式信息(如字体、颜色、布局)
- ✗ 需要编辑或修改 .docx 文件
- ✗ 需要处理 .doc 或其他文档格式
## Capabilities
### 1. 全文转换为 Markdown
将完整的 DOCX 文档解析为 Markdown 格式文本,移除所有图片但保留文本格式。
**支持格式转换**:
- 标题1-6级
- 列表(有序和无序)
- 表格
- 粗体、斜体、下划线
- 连续空行规范化
### 2. 获取文档元信息
提供文档的基本统计信息:
- 字数统计(使用 `-c` 参数)
- 行数统计(使用 `-l` 参数)
### 3. 标题列表提取
提取文档中的所有标题1-6级按原始层级关系返回。
### 4. 指定章节内容提取
根据标题名称提取特定章节的完整内容,包括:
- 完整的上级标题链
- 该标题下的所有下级内容
支持同名标题提取,返回所有匹配章节。
### 5. 正则表达式搜索
在文档中搜索关键词或模式:
- 支持标准正则表达式
- 可自定义上下文行数(默认前后各 2 行)
- 多个匹配结果用 `---` 分隔
- 上下文行数不包含空行
## Triggers
### 中文触发词
- "读取 docx"
- "解析 docx"
- "打开 word 文档"
- "提取 word 文档内容"
- "解析 word 文件"
### 英文触发词
- "read docx"
- "parse docx"
- "extract from word document"
- "parse word file"
- "read word document"
### 文件扩展名
- `.docx` 文件
## Execution
### 优先使用 lyxy-runner-python
**推荐执行方式**(如果 lyxy-runner-python skill 可用):
```bash
# 使用 lyxy-runner-python 执行(推荐)
uv run --with markitdown skills/lyxy-reader-docx/scripts/docx_parser.py /path/to/document.docx
# 或使用 python-docx
uv run --with python-docx skills/lyxy-reader-docx/scripts/docx_parser.py /path/to/document.docx
```
**大模型应优先检查 lyxy-runner-python skill 是否存在,如果存在则使用它执行。**
### 降级到直接执行
如果 lyxy-runner-python skill 不可用,则直接使用 Python
```bash
# 直接使用 Python 执行
python3 skills/lyxy-reader-docx/scripts/docx_parser.py /path/to/document.docx
```
**提示用户**: 建议用户安装 markitdown 或 python-docx 以获得更好的解析效果:
```
建议:安装 markitdown 或 python-docx 以获得更好的解析效果
安装命令:
pip install markitdown # 推荐
pip install python-docx # 备选
```
**禁止自动安装**: 不得自动执行 pip install 命令安装依赖。仅向用户提示安装建议即可。
**降级策略说明**: 脚本内部实现了多策略解析降级MarkItDown → python-docx → XML 原生),即使未安装第三方库也能通过 XML 原生解析工作,只是功能可能受限。
## Command Usage
### 基本语法
```bash
python3 docx_parser.py [options] <file_path>
```
### 参数说明
| 参数 | 说明 |
| ----------- | ------------------- |
| `file_path` | DOCX 文件的绝对路径 |
### 选项参数
| 参数 | 长参数 | 类型 | 默认值 | 说明 |
| ---- | ----------- | ---- | ------ | -------------------------------------------------------------- |
| `-n` | `--context` | 整数 | 2 | 与 `-s` 配合使用,指定每个检索结果包含的前后行数(不包含空行) |
### 互斥参数(只能使用其中一个)
| 参数 | 长参数 | 说明 |
| ----- | ----------------- | ----------------------------------------------------- |
| `-c` | `--count` | 返回解析后的 markdown 文档的总字数 |
| `-l` | `--lines` | 返回解析后的 markdown 文档的总行数 |
| `-t` | `--titles` | 返回解析后的 markdown 文档的标题行1-6级 |
| `-tc` | `--title-content` | 指定标题名称,输出该标题及其下级内容(不包含#号 |
| `-s` | --search | 使用正则表达式搜索文档,返回所有匹配结果(用---分隔) |
## Examples
### 示例 1: 提取完整文档内容
```bash
# 提取完整文档
python3 docx_parser.py /path/to/document.docx
```
输出:完整的 Markdown 格式文档内容
### 示例 2: 获取文档字数
```bash
# 获取字数
python3 docx_parser.py -c /path/to/document.docx
```
输出:文档总字数(数字)
### 示例 3: 提取所有标题
```bash
# 提取标题
python3 docx_parser.py -t /path/to/document.docx
```
输出:所有 1-6 级标题列表
### 示例 4: 提取指定章节
```bash
# 提取 "第一章" 内容
python3 docx_parser.py -tc "第一章" /path/to/document.docx
```
输出:该章节的完整内容(包含上级标题链和所有下级内容)
### 示例 5: 搜索关键词
```bash
# 搜索关键词(默认 2 行上下文)
python3 docx_parser.py -s "关键词" /path/to/document.docx
# 自定义 5 行上下文
python3 docx_parser.py -s "关键词" -n 5 /path/to/document.docx
```
输出:所有匹配结果及其上下文,用 `---` 分隔
## 依赖安装
### 推荐方式:使用 lyxy-runner-python
如果使用 lyxy-runner-python skill依赖会自动管理无需手动安装。
### 手动安装(降级模式)
如果直接使用 Python 执行,需要手动安装至少一个解析库:
```bash
# 安装 MarkItDown推荐
pip install markitdown
# 安装 python-docx备选
pip install python-docx
```
**重要限制**:
-**禁止自动安装**: 不得自动执行 pip install 命令安装依赖
-**仅提示即可**: 向用户展示安装建议,但由用户决定是否安装
-**不阻塞执行**: 即使未安装依赖,脚本也能通过 XML 原生解析运行
### 多策略解析
脚本自动尝试以下解析方法,确保最大兼容性:
1. **MarkItDown**(微软官方库,效果最佳)
2. **python-docx**(成熟的 Python 库)
3. **XML 原生解析**(备选方案,无需任何依赖)
即使未安装任何依赖库,脚本也会尝试使用 XML 原生解析,但功能可能受限。
## Error Handling
### 常见错误
| 错误类型 | 说明 | 解决方案 |
| --------- | ---- | -------- |
| 文件不存在 | 提供的文件路径无效 | 检查文件路径是否正确 |
| 无效的 DOCX | 文件不是有效的 DOCX 格式或已损坏 | 确认文件格式正确 |
| 未找到标题 | 指定的标题名称不存在 | 使用 `-t` 参数查看所有标题 |
| 正则表达式无效 | 提供的正则表达式格式错误 | 检查正则表达式语法 |
| 解析库未安装 | 未安装 markitdown 或 python-docx | 提示用户安装以获得更好的解析效果,但禁止自动安装。脚本会自动降级到 XML 原生解析。 |
## Notes
### 为什么选择 lyxy-runner-python
| 特性 | 优势 |
| ------ | ------ |
| 环境隔离 | 不污染系统 Python |
| 自动依赖 | 自动安装 markitdown 或 python-docx |
| 快速启动 | 比 venv 快 10-100 倍 |
| 跨平台 | 自动适配 Windows/macOS/Linux |
| 零配置 | 开箱即用,无需预安装依赖 |
### 最佳实践
1. **优先使用 lyxy-runner-python**: 如果环境中存在,应优先使用 lyxy-runner-python 执行脚本
2. **大文件处理**: 对于大文档,建议使用章节提取或关键词搜索来限制处理范围
3. **依赖管理**: 使用 lyxy-runner-python 可以自动管理依赖,避免环境配置问题
4. **错误处理**: 脚本会自动尝试多种解析方法,确保最大兼容性
5. **禁止自动安装**: 在降级到直接 Python 执行时,仅向用户提示安装依赖,不得自动执行 pip install
### 限制
- ✗ 不支持图片提取(仅纯文本)
- ✗ 不支持复杂的格式保留(字体、颜色、布局等)
- ✗ 不支持文档编辑或修改
- ✗ 仅支持 .docx 格式(不支持 .doc 或其他格式)

View File

@@ -37,27 +37,27 @@ python3 docx_parser.py [options] <file_path>
### 位置参数
| 参数 | 说明 |
|------|------|
| 参数 | 说明 |
| ----------- | ------------------- |
| `file_path` | DOCX 文件的绝对路径 |
### 选项参数
| 参数 | 长参数 | 类型 | 默认值 | 说明 |
|------|--------|------|--------|------|
| `-n` | `--context` | 整数 | 2 | 与 `-s` 配合使用,指定每个检索结果包含的前后行数(不包含空行) |
| 参数 | 长参数 | 类型 | 默认值 | 说明 |
| ---- | ----------- | ---- | ------ | -------------------------------------------------------------- |
| `-n` | `--context` | 整数 | 2 | 与 `-s` 配合使用,指定每个检索结果包含的前后行数(不包含空行) |
### 互斥参数
以下参数只能使用其中一个:
| 参数 | 长参数 | 说明 |
|------|--------|------|
| `-c` | `--count` | 返回解析后的 markdown 文档的总字数 |
| `-l` | `--lines` | 返回解析后的 markdown 文档的总行数 |
| `-t` | `--titles` | 返回解析后的 markdown 文档的标题行1-6级 |
| `-tc` | `--title-content` | 指定标题名称,输出该标题及其下级内容(不包含#号 |
| `-s` | `--search` | 使用正则表达式搜索文档,返回所有匹配结果(用---分隔) |
| 参数 | 长参数 | 说明 |
| ----- | ----------------- | ----------------------------------------------------- |
| `-c` | `--count` | 返回解析后的 markdown 文档的总字数 |
| `-l` | `--lines` | 返回解析后的 markdown 文档的总行数 |
| `-t` | `--titles` | 返回解析后的 markdown 文档的标题行1-6级 |
| `-tc` | `--title-content` | 指定标题名称,输出该标题及其下级内容(不包含#号 |
| `-s` | `--search` | 使用正则表达式搜索文档,返回所有匹配结果(用---分隔) |
## 使用示例
@@ -92,6 +92,7 @@ python3 docx_parser.py -t /path/to/document.docx
```
输出示例:
```
# 主标题
## 第一章
@@ -109,11 +110,13 @@ python3 docx_parser.py -tc "第一章" /path/to/document.docx
输出:包含所有上级标题的指定章节内容
**特点:**
- 支持多个同名标题
- 自动包含完整的上级标题链
- 包含所有下级内容
示例输出:
```
# 主标题
## 第一章
@@ -161,6 +164,7 @@ python3 docx_parser.py -s r"\d{4}-\d{2}-\d{2}" /path/to/document.docx
```
输出示例:
```
这是前一行
包含匹配关键词
@@ -231,22 +235,10 @@ python3 docx_parser.py -s "关键词" /path/to/document.docx > search_results.md
## 常见问题
### Q: 如何选择解析库?
A: 建议优先安装 `markitdown`,它是微软官方库,解析效果最好。如果需要更多控制或兼容性,可以同时安装 `python-docx`
### Q: 为什么某些文档解析不完整?
A: 可能原因:
1. 文档使用特殊格式或样式
2. 文档已损坏
3. 未安装合适的解析库
尝试安装多个解析库,或检查文档是否损坏。
### Q: 如何处理大文档?
A: 对于非常大的文档,建议:
1. 使用 `-tc` 参数只提取需要的章节
2. 使用 `-s` 参数搜索特定内容
3. 将输出重定向到文件进行处理
@@ -284,11 +276,15 @@ A: `-tc` 参数会返回所有同名标题,每个标题都包含其完整的
```markdown
# 主标题
## 同名标题 1
内容1
# 主标题
## 同名标题 2
内容2
```
@@ -296,36 +292,28 @@ A: `-tc` 参数会返回所有同名标题,每个标题都包含其完整的
### 标题识别规则
| 样式名称 | Markdown 标题级别 |
|---------|-------------------|
| Title | # |
| Heading 1 | # |
| Heading 2 | ## |
| Heading 3 | ### |
| Heading 4 | #### |
| Heading 5 | ##### |
| Heading 6 | ###### |
| 样式名称 | Markdown 标题级别 |
| --------- | ----------------- |
| Title | # |
| Heading 1 | # |
| Heading 2 | ## |
| Heading 3 | ### |
| Heading 4 | #### |
| Heading 5 | ##### |
| Heading 6 | ###### |
### 列表识别规则
| 样式名称 | Markdown 列表格式 |
|---------|------------------|
| List Bullet / Bullet | - (无序列表) |
| List Number / Number | 1. (有序列表) |
| 样式名称 | Markdown 列表格式 |
| -------------------- | ----------------- |
| List Bullet / Bullet | - (无序列表) |
| List Number / Number | 1. (有序列表) |
### 文本格式支持
| 格式 | 转换结果 |
|------|---------|
| 粗体 | `**文本**` |
| 斜体 | `*文本*` |
| 下划线 | `<u>文本</u>` |
| 表格 | Markdown 表格格式 |
## 许可证
本脚本遵循相关开源许可证。
## 贡献
欢迎提交问题和改进建议。
| 格式 | 转换结果 |
| ------ | ----------------- |
| 粗体 | `**文本**` |
| 斜体 | `*文本*` |
| 下划线 | `<u>文本</u>` |
| 表格 | Markdown 表格格式 |

View File

@@ -1,10 +1,10 @@
---
name: js-runner
name: lyxy-runner-js
description: Any task that requires Javascript/Typescript processing should use this skill.
compatibility: Requires Bun runtime (https://bun.sh)
---
# js-runner
# lyxy-runner-js
基于 Bun 的 JavaScript/TypeScript 执行技能,提供隔离的脚本执行和自动依赖管理。
@@ -24,7 +24,7 @@ compatibility: Requires Bun runtime (https://bun.sh)
### 安装 Bun
js-runner 需要安装 Bun。Bun 是一个快速的 JavaScript 运行时,内置包管理器。
lyxy-runner-js 需要安装 Bun。Bun 是一个快速的 JavaScript 运行时,内置包管理器。
**macOS/Linux:**
@@ -120,11 +120,11 @@ bun ./scripts/new-script.js
bun --version
# 步骤 2: 生成临时文件路径
TEMP_FILE=$(bun skills/js-runner/scripts/get_temp_path.js js)
TEMP_FILE=$(bun skills/lyxy-runner-js/scripts/get_temp_path.js js)
# 步骤 3: 将脚本内容写入临时文件
cat <<EOF > "$TEMP_FILE"
const greeting = "Hello from js-runner!";
const greeting = "Hello from lyxy-runner-js!";
console.log(greeting);
EOF
@@ -139,7 +139,7 @@ bun "$TEMP_FILE"
```bash
# 生成 TypeScript 临时文件
TEMP_TS=$(bun skills/js-runner/scripts/get_temp_path.js ts)
TEMP_TS=$(bun skills/lyxy-runner-js/scripts/get_temp_path.js ts)
# 写入 TypeScript 脚本
cat <<EOF > "$TEMP_TS"
@@ -192,19 +192,19 @@ const axios = require('axios')
**CLI 使用方式:**
```bash
bun skills/js-runner/scripts/get_temp_path.js <extension>
bun skills/lyxy-runner-js/scripts/get_temp_path.js <extension>
```
**参数:**
- `extension` (可选): 文件扩展名。默认为 `js`。常用值: `js`, `ts`, `mjs`, `mts`
**输出:** 返回类似 `/var/folders/.../js-runner-1234567890-abc123.js` 的路径
**输出:** 返回类似 `/var/folders/.../lyxy-runner-js-1234567890-abc123.js` 的路径
**路径格式:**
- 使用操作系统临时目录Unix 上为 `/tmp`Windows 上为 `%TEMP%`
- 前缀: `js-runner-`
- 前缀: `lyxy-runner-js-`
- 时间戳: 自纪元以来的毫秒数
- 随机字符串: 7 字符字母数字
- 扩展名: 参数中提供的值
@@ -212,11 +212,11 @@ bun skills/js-runner/scripts/get_temp_path.js <extension>
**示例:**
```bash
$ bun skills/js-runner/scripts/get_temp_path.js js
/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/js-runner-1770257905333-na6ujx.js
$ bun skills/lyxy-runner-js/scripts/get_temp_path.js js
/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/lyxy-runner-js-1770257905333-na6ujx.js
$ bun skills/js-runner/scripts/get_temp_path.js ts
/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/js-runner-1770257905333-v8yzt.ts
$ bun skills/lyxy-runner-js/scripts/get_temp_path.js ts
/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/lyxy-runner-js-1770257905333-v8yzt.ts
```
## 错误处理

View File

@@ -4,7 +4,7 @@ import { join } from "path";
export function getTempPath(extension) {
const timestamp = Date.now();
const random = Math.random().toString(36).substring(7);
return join(tmpdir(), `js-runner-${timestamp}-${random}.${extension}`);
return join(tmpdir(), `lyxy-runner-js-${timestamp}-${random}.${extension}`);
}
// CLI interface: accepts extension as first argument

View File

@@ -1,5 +1,5 @@
---
name: python-runner
name: lyxy-runner-python
description: Any task that requires Python processing should use this skill.
---
@@ -83,7 +83,7 @@ uv sync --dry-run
```bash
# 临时文件获取
temp_file_path=$(uv run ./script/get_temp_path.py)
temp_file_path=$(uv run ./scripts/get_temp_path.py)
```
## Execution Commands