优化skill提示词
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-25
|
||||
@@ -0,0 +1,76 @@
|
||||
## Context
|
||||
|
||||
当前项目包含 4 个 skills（lyxy-runner-python、lyxy-runner-js、lyxy-reader-office、lyxy-kb），每个 SKILL.md 文件内容在 200-300 行之间。根据 `document/the-complete-guide-to-building-skill.md` 中的渐进式披露原则，SKILL.md 应保持精简（建议 5000 字以内），详细文档应放在 `references/` 目录中。
|
||||
|
||||
**当前状态**：
|
||||
- SKILL.md 包含完整的工作流程、示例、错误处理、最佳实践等所有内容
|
||||
- 无 references/ 目录结构
|
||||
- 每次 Claude 加载 skill 时需要处理全部内容
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 遵循三层渐进式披露结构：YAML 前置元数据 → SKILL.md 核心指令 → references/ 详细文档
|
||||
- 减少 skill 加载时的 token 消耗
|
||||
- 保持 lyxy-runner-python 和 lyxy-runner-js 的 description 宽泛性
|
||||
- 为 4 个现有 skills 创建 references/ 目录并迁移内容
|
||||
|
||||
**Non-Goals:**
|
||||
- 不修改 skill 的功能逻辑
|
||||
- 不修改 scripts/ 目录中的可执行代码
|
||||
- 不新增 skill 或删除现有 skill
|
||||
|
||||
## Decisions
|
||||
|
||||
### 决策 1：三层结构内容划分
|
||||
|
||||
| 层级 | 位置 | 内容 | 加载时机 |
|
||||
|-----|------|------|---------|
|
||||
| 第一层 | YAML 前置元数据 | name、description、compatibility | 始终加载到系统提示 |
|
||||
| 第二层 | SKILL.md 正文 | 核心工作流、关键命令、快速参考 | Claude 判断相关时加载 |
|
||||
| 第三层 | references/*.md | 详细示例、错误处理、最佳实践、API 参考 | 按需导航和发现 |
|
||||
|
||||
**理由**：遵循官方指南的渐进式披露原则，最小化 token 消耗的同时保持完整能力。
|
||||
|
||||
### 决策 2：SKILL.md 保留内容
|
||||
|
||||
每个 SKILL.md 正文保留以下核心部分：
|
||||
1. **Purpose**：简要说明用途和关键依赖
|
||||
2. **When to Use**：适用/不适用场景（简化版）
|
||||
3. **Quick Reference**：核心命令表格或流程图
|
||||
4. **Workflow**：简化的执行步骤
|
||||
5. **References 链接**：指向 references/ 中详细文档的链接
|
||||
|
||||
**理由**：保留足够信息让 Claude 完成任务，详细内容按需加载。
|
||||
|
||||
### 决策 3：references/ 目录结构
|
||||
|
||||
```
|
||||
references/
|
||||
├── examples.md # 详细示例
|
||||
├── error-handling.md # 错误处理和故障排除
|
||||
├── best-practices.md # 最佳实践和注意事项
|
||||
└── api-reference.md # API/命令参数详细说明（可选）
|
||||
```
|
||||
|
||||
**理由**：按主题分类，便于 Claude 按需定位和加载。
|
||||
|
||||
### 决策 4：Description 格式
|
||||
|
||||
采用统一格式：`[做什么] + [何时使用] + [关键能力]`
|
||||
|
||||
- lyxy-runner-python：保持 "Any task that requires Python processing should use this skill."（宽泛）
|
||||
- lyxy-runner-js：保持 "Any task that requires Javascript/Typescript processing should use this skill."（宽泛）
|
||||
- lyxy-reader-office：保持当前描述，已包含具体文件类型和操作
|
||||
- lyxy-kb：可优化添加用户触发短语
|
||||
|
||||
**理由**：runner skills 需要宽泛以匹配所有相关任务，reader/kb skills 可以更具体以精准触发。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
| 风险 | 缓解措施 |
|
||||
|-----|---------|
|
||||
| references/ 文件未被 Claude 发现 | 在 SKILL.md 中明确列出 references/ 文件并说明用途 |
|
||||
| 拆分后信息不完整 | 核心工作流程保留在 SKILL.md，确保基本任务可完成 |
|
||||
| 迁移过程中遗漏内容 | 逐个 skill 处理，对比前后内容确保完整性 |
|
||||
| 文件数量增加 | references/ 文件按需加载，不影响初始 token 消耗 |
|
||||
@@ -0,0 +1,30 @@
|
||||
## Why
|
||||
|
||||
当前 skills 的 SKILL.md 文件内容较长（200-300 行），未遵循渐进式披露（Progressive Disclosure）原则。根据 skill 编写指南，应采用三层结构：YAML 前置元数据（触发判断）→ SKILL.md 正文（核心指令）→ references/（详细文档）。这样可以减少 token 消耗，提高 Claude 的响应效率。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **结构优化**：为每个 skill 创建 `references/` 目录，将详细文档、示例、错误处理等内容从 SKILL.md 正文移至 references/
|
||||
- **SKILL.md 精简**：保留核心工作流程和关键指令，将详细说明改为链接到 references/ 中的文档
|
||||
- **Description 优化**：确保 description 同时包含「做什么」和「何时使用」两部分，便于 Claude 判断是否加载
|
||||
- **lyxy-runner-python/js 保持宽泛**：这两个 runner skill 的 description 需要保持宽泛，以便匹配所有 Python/JS 处理任务
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `skill-progressive-disclosure`: 定义 skill 渐进式披露的三层结构规范，包括 YAML 前置元数据、SKILL.md 正文、references/ 目录的职责划分和内容组织方式
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
（无现有 spec 需要修改）
|
||||
|
||||
## Impact
|
||||
|
||||
- **文件结构变更**：每个 skill 目录新增 `references/` 子目录
|
||||
- **SKILL.md 重构**：4 个 skills 的 SKILL.md 文件需要精简，详细内容迁移到 references/
|
||||
- `skills/lyxy-runner-python/SKILL.md`
|
||||
- `skills/lyxy-runner-js/SKILL.md`
|
||||
- `skills/lyxy-reader-office/SKILL.md`
|
||||
- `skills/lyxy-kb/SKILL.md`
|
||||
- **向后兼容**：功能不变，仅优化文档结构，**无破坏性变更**
|
||||
@@ -0,0 +1,77 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 三层渐进式披露结构
|
||||
|
||||
每个 skill 目录 SHALL 采用三层渐进式披露结构，按加载时机分为：第一层（YAML 前置元数据）、第二层（SKILL.md 正文）、第三层（references/ 目录）。
|
||||
|
||||
#### Scenario: skill 目录包含完整三层结构
|
||||
- **WHEN** 检查任意 skill 目录结构
|
||||
- **THEN** 目录 SHALL 包含 SKILL.md 文件和 references/ 子目录
|
||||
|
||||
#### Scenario: 第一层始终加载
|
||||
- **WHEN** Claude 启动会话时
|
||||
- **THEN** 所有 skill 的 YAML 前置元数据 SHALL 被加载到系统提示中
|
||||
|
||||
### Requirement: YAML 前置元数据内容规范
|
||||
|
||||
YAML 前置元数据 SHALL 仅包含触发判断所需的最小信息，使 Claude 能够判断何时使用该 skill。
|
||||
|
||||
#### Scenario: 必需字段
|
||||
- **WHEN** 编写 SKILL.md 的 YAML 前置元数据
|
||||
- **THEN** SHALL 包含 name 和 description 字段
|
||||
|
||||
#### Scenario: description 格式
|
||||
- **WHEN** 编写 description 字段
|
||||
- **THEN** SHALL 同时包含「做什么」和「何时使用」两部分信息
|
||||
|
||||
#### Scenario: description 长度限制
|
||||
- **WHEN** 检查 description 字段
|
||||
- **THEN** 内容 SHALL 少于 1024 个字符
|
||||
|
||||
#### Scenario: runner skill 的 description 宽泛性
|
||||
- **WHEN** skill 用途为通用脚本执行（如 Python/JavaScript runner）
|
||||
- **THEN** description SHALL 保持宽泛，以匹配所有相关处理任务
|
||||
|
||||
### Requirement: SKILL.md 正文内容规范
|
||||
|
||||
SKILL.md 正文 SHALL 包含核心工作流程和关键指令，保持精简以减少 token 消耗。
|
||||
|
||||
#### Scenario: SKILL.md 必需章节
|
||||
- **WHEN** 编写 SKILL.md 正文
|
||||
- **THEN** SHALL 包含以下章节：Purpose、When to Use、Quick Reference、Workflow、References 链接
|
||||
|
||||
#### Scenario: SKILL.md 长度建议
|
||||
- **WHEN** 检查 SKILL.md 总字数
|
||||
- **THEN** 建议控制在 5000 字以内（含 YAML 前置元数据）
|
||||
|
||||
#### Scenario: 详细内容迁移
|
||||
- **WHEN** SKILL.md 包含详细示例、完整错误处理、最佳实践等冗长内容
|
||||
- **THEN** 这些内容 SHALL 迁移到 references/ 目录，SKILL.md 中保留链接引用
|
||||
|
||||
### Requirement: references 目录结构规范
|
||||
|
||||
每个 skill SHALL 包含 references/ 子目录，用于存放按需加载的详细文档。
|
||||
|
||||
#### Scenario: references 目录存在性
|
||||
- **WHEN** 检查 skill 目录结构
|
||||
- **THEN** SHALL 存在 references/ 子目录
|
||||
|
||||
#### Scenario: references 文件分类
|
||||
- **WHEN** 组织 references/ 目录内容
|
||||
- **THEN** SHALL 按主题分类为独立的 markdown 文件，如 examples.md、error-handling.md、best-practices.md
|
||||
|
||||
#### Scenario: SKILL.md 引用 references
|
||||
- **WHEN** SKILL.md 需要引用详细文档
|
||||
- **THEN** SHALL 在 SKILL.md 中明确列出 references/ 中的文件并说明用途
|
||||
|
||||
### Requirement: 内容迁移完整性
|
||||
|
||||
从 SKILL.md 迁移内容到 references/ 时，SHALL 确保所有原有信息被完整保留。
|
||||
|
||||
#### Scenario: 迁移前后对比
|
||||
- **WHEN** 完成单个 skill 的内容迁移
|
||||
- **THEN** references/ 中的文件 SHALL 包含原 SKILL.md 中被移除的所有详细内容
|
||||
|
||||
#### Scenario: 功能不变性
|
||||
- **WHEN** 完成结构优化后
|
||||
- **THEN** skill 的功能逻辑 SHALL 保持不变，仅文档结构发生变化
|
||||
@@ -0,0 +1,45 @@
|
||||
## 1. lyxy-runner-python 结构优化
|
||||
|
||||
- [x] 1.1 创建 `skills/lyxy-runner-python/references/` 目录
|
||||
- [x] 1.2 提取示例代码到 `references/examples.md`
|
||||
- [x] 1.3 提取错误处理内容到 `references/error-handling.md`
|
||||
- [x] 1.4 提取最佳实践和注意事项到 `references/best-practices.md`
|
||||
- [x] 1.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
|
||||
- [x] 1.6 在 SKILL.md 末尾添加 References 链接章节
|
||||
- [x] 1.7 验证 description 保持宽泛（"Any task that requires Python processing..."）
|
||||
|
||||
## 2. lyxy-runner-js 结构优化
|
||||
|
||||
- [x] 2.1 创建 `skills/lyxy-runner-js/references/` 目录
|
||||
- [x] 2.2 提取示例代码到 `references/examples.md`
|
||||
- [x] 2.3 提取错误处理内容到 `references/error-handling.md`
|
||||
- [x] 2.4 提取最佳实践和输出处理到 `references/best-practices.md`
|
||||
- [x] 2.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
|
||||
- [x] 2.6 在 SKILL.md 末尾添加 References 链接章节
|
||||
- [x] 2.7 验证 description 保持宽泛（"Any task that requires Javascript/Typescript processing..."）
|
||||
|
||||
## 3. lyxy-reader-office 结构优化
|
||||
|
||||
- [x] 3.1 创建 `skills/lyxy-reader-office/references/` 目录
|
||||
- [x] 3.2 提取详细示例到 `references/examples.md`
|
||||
- [x] 3.3 提取解析器说明和依赖安装到 `references/parsers.md`
|
||||
- [x] 3.4 提取错误处理和限制说明到 `references/error-handling.md`
|
||||
- [x] 3.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
|
||||
- [x] 3.6 在 SKILL.md 末尾添加 References 链接章节
|
||||
|
||||
## 4. lyxy-kb 结构优化
|
||||
|
||||
- [x] 4.1 创建 `skills/lyxy-kb/references/` 目录
|
||||
- [x] 4.2 提取目录结构和文件格式详细说明到 `references/structure.md`
|
||||
- [x] 4.3 提取文档生命周期和处理策略到 `references/workflow.md`
|
||||
- [x] 4.4 提取渐进式查询策略到 `references/query-strategy.md`
|
||||
- [x] 4.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
|
||||
- [x] 4.6 在 SKILL.md 末尾添加 References 链接章节
|
||||
- [x] 4.7 优化 description 添加用户触发短语
|
||||
|
||||
## 5. 验证与收尾
|
||||
|
||||
- [x] 5.1 对比每个 skill 的原始 SKILL.md 和重构后内容，确保信息完整
|
||||
- [x] 5.2 验证每个 skill 的 references/ 目录包含必要文件
|
||||
- [x] 5.3 验证每个 SKILL.md 的 References 章节正确链接到 references/ 文件
|
||||
- [x] 5.4 验证所有 description 符合格式要求（<1024 字符）
|
||||
83
openspec/specs/skill-progressive-disclosure/spec.md
Normal file
83
openspec/specs/skill-progressive-disclosure/spec.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# skill-progressive-disclosure
|
||||
|
||||
## Purpose
|
||||
|
||||
定义 skill 的渐进式披露（Progressive Disclosure）结构规范，将 skill 内容按加载时机分为三层：YAML 前置元数据、SKILL.md 正文、references/ 详细文档。通过分层加载减少 token 消耗，提高 Claude 的响应效率。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 三层渐进式披露结构
|
||||
|
||||
每个 skill 目录 SHALL 采用三层渐进式披露结构，按加载时机分为：第一层（YAML 前置元数据）、第二层（SKILL.md 正文）、第三层（references/ 目录）。
|
||||
|
||||
#### Scenario: skill 目录包含完整三层结构
|
||||
- **WHEN** 检查任意 skill 目录结构
|
||||
- **THEN** 目录 SHALL 包含 SKILL.md 文件和 references/ 子目录
|
||||
|
||||
#### Scenario: 第一层始终加载
|
||||
- **WHEN** Claude 启动会话时
|
||||
- **THEN** 所有 skill 的 YAML 前置元数据 SHALL 被加载到系统提示中
|
||||
|
||||
### Requirement: YAML 前置元数据内容规范
|
||||
|
||||
YAML 前置元数据 SHALL 仅包含触发判断所需的最小信息，使 Claude 能够判断何时使用该 skill。
|
||||
|
||||
#### Scenario: 必需字段
|
||||
- **WHEN** 编写 SKILL.md 的 YAML 前置元数据
|
||||
- **THEN** SHALL 包含 name 和 description 字段
|
||||
|
||||
#### Scenario: description 格式
|
||||
- **WHEN** 编写 description 字段
|
||||
- **THEN** SHALL 同时包含「做什么」和「何时使用」两部分信息
|
||||
|
||||
#### Scenario: description 长度限制
|
||||
- **WHEN** 检查 description 字段
|
||||
- **THEN** 内容 SHALL 少于 1024 个字符
|
||||
|
||||
#### Scenario: runner skill 的 description 宽泛性
|
||||
- **WHEN** skill 用途为通用脚本执行（如 Python/JavaScript runner）
|
||||
- **THEN** description SHALL 保持宽泛，以匹配所有相关处理任务
|
||||
|
||||
### Requirement: SKILL.md 正文内容规范
|
||||
|
||||
SKILL.md 正文 SHALL 包含核心工作流程和关键指令，保持精简以减少 token 消耗。
|
||||
|
||||
#### Scenario: SKILL.md 必需章节
|
||||
- **WHEN** 编写 SKILL.md 正文
|
||||
- **THEN** SHALL 包含以下章节：Purpose、When to Use、Quick Reference、Workflow、References 链接
|
||||
|
||||
#### Scenario: SKILL.md 长度建议
|
||||
- **WHEN** 检查 SKILL.md 总字数
|
||||
- **THEN** 建议控制在 5000 字以内（含 YAML 前置元数据）
|
||||
|
||||
#### Scenario: 详细内容迁移
|
||||
- **WHEN** SKILL.md 包含详细示例、完整错误处理、最佳实践等冗长内容
|
||||
- **THEN** 这些内容 SHALL 迁移到 references/ 目录，SKILL.md 中保留链接引用
|
||||
|
||||
### Requirement: references 目录结构规范
|
||||
|
||||
每个 skill SHALL 包含 references/ 子目录，用于存放按需加载的详细文档。
|
||||
|
||||
#### Scenario: references 目录存在性
|
||||
- **WHEN** 检查 skill 目录结构
|
||||
- **THEN** SHALL 存在 references/ 子目录
|
||||
|
||||
#### Scenario: references 文件分类
|
||||
- **WHEN** 组织 references/ 目录内容
|
||||
- **THEN** SHALL 按主题分类为独立的 markdown 文件，如 examples.md、error-handling.md、best-practices.md
|
||||
|
||||
#### Scenario: SKILL.md 引用 references
|
||||
- **WHEN** SKILL.md 需要引用详细文档
|
||||
- **THEN** SHALL 在 SKILL.md 中明确列出 references/ 中的文件并说明用途
|
||||
|
||||
### Requirement: 内容迁移完整性
|
||||
|
||||
从 SKILL.md 迁移内容到 references/ 时，SHALL 确保所有原有信息被完整保留。
|
||||
|
||||
#### Scenario: 迁移前后对比
|
||||
- **WHEN** 完成单个 skill 的内容迁移
|
||||
- **THEN** references/ 中的文件 SHALL 包含原 SKILL.md 中被移除的所有详细内容
|
||||
|
||||
#### Scenario: 功能不变性
|
||||
- **WHEN** 完成结构优化后
|
||||
- **THEN** skill 的功能逻辑 SHALL 保持不变，仅文档结构发生变化
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: lyxy-kb
|
||||
description: 基于文件的个人知识库管理 skill，提供知识项目的目录结构规范、文档解析入库、渐进式问答等底层能力定义。配合 commands/lyxy-kb/ 下的 command 使用。
|
||||
description: 基于文件的个人知识库管理 skill。当用户说"创建知识库"、"初始化知识项目"、"入库文档"、"知识问答"、"基于文档回答"时使用。支持文档解析入库、增量摘要、渐进式问答。配合 /lyxy-kb-init、/lyxy-kb-ingest、/lyxy-kb-ask 等 command 使用。
|
||||
compatibility: 依赖 lyxy-reader-office skill 解析 office 文档（.docx/.pdf/.pptx/.xlsx），依赖 lyxy-runner-python skill 执行 Python 脚本。
|
||||
---
|
||||
|
||||
@@ -30,7 +30,7 @@ compatibility: 依赖 lyxy-reader-office skill 解析 office 文档（.docx/.pdf
|
||||
- 需要跨多个知识项目关联查询
|
||||
- 需要多人协作或权限控制
|
||||
|
||||
## 配套 Commands
|
||||
## Quick Reference
|
||||
|
||||
| Command | 触发方式 | 说明 |
|
||||
|---------|----------|------|
|
||||
@@ -39,255 +39,38 @@ compatibility: 依赖 lyxy-reader-office skill 解析 office 文档（.docx/.pdf
|
||||
| rebuild | `/lyxy-kb-rebuild <name>` | 全量重新生成 project.md |
|
||||
| ask | `/lyxy-kb-ask <name>` | 基于知识库进行会话问答 |
|
||||
|
||||
## 项目名称规则
|
||||
## Workflow
|
||||
|
||||
项目名称只允许使用以下字符：
|
||||
- 中文字符
|
||||
- 英文字母（a-z、A-Z）
|
||||
- 数字（0-9）
|
||||
- 短横线（-）
|
||||
- 下划线（_）
|
||||
|
||||
**不允许包含空格或其他特殊字符。** 不符合规则时应提示用户修改。
|
||||
|
||||
## 知识项目目录结构
|
||||
|
||||
每个知识项目是当前工作目录（CWD）下的一个子目录，包含以下固定结构：
|
||||
### 知识项目目录结构
|
||||
|
||||
```
|
||||
<project-name>/
|
||||
├── project.md # 高度摘要 + 文件索引
|
||||
├── manifest.json # 增量追踪
|
||||
├── parsed/ # 解析后的 markdown（中间产物）
|
||||
├── parsed/ # 解析后的 markdown
|
||||
├── sources/ # 待处理区（用户放入原始文档）
|
||||
└── archive/ # 原始文件备份（带时间戳）
|
||||
```
|
||||
|
||||
### 各目录/文件职责
|
||||
### 基本工作流程
|
||||
|
||||
| 路径 | 职责 |
|
||||
|------|------|
|
||||
| `project.md` | 项目的高度摘要和文件索引，作为问答时的入口文件 |
|
||||
| `manifest.json` | 记录已处理文件的元信息，用于增量检测和版本追踪 |
|
||||
| `parsed/` | 存放解析后的 markdown 文件，便于大模型读取分析 |
|
||||
| `sources/` | 用户放入待处理文档的目录，解析后文件会被移走 |
|
||||
| `archive/` | 原始文件的备份，每个文件都带时间戳后缀 |
|
||||
1. **初始化**：使用 `/lyxy-kb-init <name>` 创建项目目录结构
|
||||
2. **入库**：将文档放入 `sources/`，执行 `/lyxy-kb-ingest <name>`
|
||||
3. **问答**：使用 `/lyxy-kb-ask <name>` 基于知识库回答问题
|
||||
|
||||
### 结构完整性验证
|
||||
|
||||
执行任何 command（ingest / rebuild / ask）时，必须先验证项目目录结构是否完整，即以下 5 项是否全部存在：
|
||||
- `<project-name>/project.md`
|
||||
- `<project-name>/manifest.json`
|
||||
- `<project-name>/parsed/`
|
||||
- `<project-name>/sources/`
|
||||
- `<project-name>/archive/`
|
||||
|
||||
若不完整，提示用户先执行 `/lyxy-kb-init <project-name>`，终止当前操作。
|
||||
|
||||
## project.md 格式规范
|
||||
|
||||
```markdown
|
||||
# <项目名称>
|
||||
|
||||
## 概述
|
||||
（高度总结的项目信息，几百字以内）
|
||||
|
||||
## 关键信息
|
||||
（从所有文档中提炼的核心要点）
|
||||
|
||||
## 文件索引
|
||||
|
||||
| 文件名 | 解析文件 | 最新归档 | 摘要 |
|
||||
|--------|----------|----------|------|
|
||||
| 需求文档 | parsed/需求文档.md | archive/需求文档_202602181600.docx | 简要摘要... |
|
||||
|
||||
## 更新记录
|
||||
- 2026-02-18 16:00: 解析 需求文档.docx
|
||||
```
|
||||
|
||||
### 更新策略
|
||||
|
||||
**增量追加**（默认，由 ingest 触发）：
|
||||
- 新文件：在文件索引表追加新行，在更新记录追加条目
|
||||
- 已有文件更新：覆盖文件索引表中对应行的最新归档路径和摘要
|
||||
- 概述和关键信息部分**不**自动更新
|
||||
|
||||
**全量重写**（由 rebuild 触发）：
|
||||
- 读取所有 parsed/*.md 文件
|
||||
- 重新生成概述、关键信息、文件索引
|
||||
- 保留历史更新记录，追加本次 rebuild 条目
|
||||
|
||||
## manifest.json 结构
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "<项目名称>",
|
||||
"created_at": "2026-02-18T16:00",
|
||||
"last_ingest": "2026-02-18T17:25",
|
||||
"files": [
|
||||
{
|
||||
"name": "需求文档",
|
||||
"ext": ".docx",
|
||||
"parsed": "parsed/需求文档.md",
|
||||
"versions": [
|
||||
{
|
||||
"archived": "archive/需求文档_202602181600.docx",
|
||||
"hash": "sha256:abc123...",
|
||||
"ingested_at": "2026-02-18T16:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 字段说明
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `project` | 项目名称 |
|
||||
| `created_at` | 项目创建时间 |
|
||||
| `last_ingest` | 最近一次 ingest 的时间 |
|
||||
| `files[].name` | 文件名（不含扩展名） |
|
||||
| `files[].ext` | 原始文件扩展名 |
|
||||
| `files[].parsed` | 解析产物的相对路径 |
|
||||
| `files[].versions` | 版本历史数组 |
|
||||
| `files[].versions[].archived` | 归档文件的相对路径 |
|
||||
| `files[].versions[].hash` | 文件内容的 SHA-256 哈希（使用 `sha256sum` 命令计算） |
|
||||
| `files[].versions[].ingested_at` | 该版本的入库时间 |
|
||||
|
||||
## 文件类型解析策略
|
||||
|
||||
| 文件类型 | 解析方式 |
|
||||
|----------|----------|
|
||||
| `.docx`, `.pdf`, `.pptx`, `.xlsx` | 使用名为 **lyxy-reader-office** 的 skill 解析 |
|
||||
| 其他所有文件（`.md`, `.txt`, `.csv`, `.json`, `.xml`, `.yaml`, `.yml`, `.log`, `.html` 等） | 直接读取文件内容 |
|
||||
|
||||
### Office 文档解析
|
||||
|
||||
解析 office 文档时，必须查找当前环境中名为 **lyxy-reader-office** 的 skill，阅读其 SKILL.md 获取具体的执行方式和命令。
|
||||
|
||||
**如果环境中不存在 lyxy-reader-office skill，且没有其他可替代的文档解析 skill，则提示用户无法处理 office 文档，中止整个 ingest 流程。**
|
||||
|
||||
### sources/ 扫描规则
|
||||
|
||||
扫描 sources/ 时**递归检查所有子目录**中的文件。parsed 产物的路径仍为 `parsed/<文件名>.md`（扁平化存放），不保留 sources 中的子目录结构。
|
||||
|
||||
### 空文件处理
|
||||
|
||||
sources/ 中 0 字节的空文件应**跳过处理**，不解析、不归档、不更新 manifest。处理完成后向用户列出被跳过的空文件列表，提示用户检查。
|
||||
|
||||
### 解析失败处理
|
||||
|
||||
如果某个文件解析失败（如文档损坏、解析器报错），该文件**保留在 sources/ 中不移动**，报告错误信息，继续处理其他文件。
|
||||
|
||||
## parsed 文件元信息标记
|
||||
|
||||
每个 parsed markdown 文件头部必须包含元信息注释：
|
||||
|
||||
```markdown
|
||||
<!-- source: 技术方案.pdf -->
|
||||
<!-- archived: archive/技术方案_202602181725.pdf -->
|
||||
<!-- parsed_at: 2026-02-18 17:25 -->
|
||||
|
||||
# 技术方案
|
||||
（文档正文内容...）
|
||||
```
|
||||
|
||||
| 元信息 | 说明 |
|
||||
|--------|------|
|
||||
| `source` | 原始文件名（含扩展名） |
|
||||
| `archived` | 对应的归档文件相对路径 |
|
||||
| `parsed_at` | 解析时间（YYYY-MM-DD HH:mm 格式） |
|
||||
|
||||
## 文档生命周期
|
||||
|
||||
```
|
||||
用户放入 sources/（支持子目录）
|
||||
│
|
||||
▼
|
||||
检查文件（跳过空文件、检测冲突）
|
||||
│
|
||||
▼
|
||||
解析文件内容（失败则保留在 sources/）
|
||||
│
|
||||
├──▶ 写入 parsed/<文件名>.md（含头部元信息）
|
||||
│
|
||||
├──▶ 移动原始文件到 archive/<文件名_YYYYMMDDHHmm>.<ext>
|
||||
│
|
||||
├──▶ 更新 manifest.json
|
||||
│
|
||||
└──▶ 增量更新 project.md（追加文件索引和更新记录）
|
||||
```
|
||||
|
||||
### 归档命名规则
|
||||
|
||||
所有进入 archive 的文件都必须带时间戳后缀，格式为 `<文件名_YYYYMMDDHHmm>.<扩展名>`，即使只有一个版本。
|
||||
|
||||
示例：
|
||||
- `需求文档.docx` → `archive/需求文档_202602181600.docx`
|
||||
- `技术方案.pdf`（第二次入库）→ `archive/技术方案_202602181725.pdf`
|
||||
|
||||
### 同名文件更新
|
||||
|
||||
同名同扩展名的文件再次入库时：
|
||||
- `parsed/` 中的 markdown 文件被覆盖为最新版本
|
||||
- `archive/` 中保留所有历史版本（每个版本独立的时间戳文件）
|
||||
- `manifest.json` 中该文件条目的 `versions` 数组追加新版本记录
|
||||
|
||||
## 同名不同扩展名冲突检测
|
||||
|
||||
因为 parsed 产物以文件名（不含扩展名）+ `.md` 命名，同名不同扩展名的文件会产生冲突。
|
||||
|
||||
### 检测规则
|
||||
|
||||
1. **sources/ 内部检测**：扫描 sources/ 中所有文件（含子目录），如果存在同名但不同扩展名的文件（如 `技术方案.pdf` 和 `技术方案.docx`），拒绝处理并提示用户重命名
|
||||
2. **与已入库文件检测**：将 sources/ 中文件的名称（不含扩展名）与 manifest.json 中已有记录对比，如果名称相同但扩展名不同，拒绝处理并提示用户重命名
|
||||
|
||||
### 处理方式
|
||||
|
||||
冲突文件不予处理，保留在 sources/ 中，提示用户重命名后重新执行 ingest。非冲突文件正常处理。
|
||||
|
||||
## 渐进式查询策略
|
||||
|
||||
问答时采用分层加载策略，节省 token：
|
||||
### 渐进式查询策略
|
||||
|
||||
1. **读取 project.md**：获取项目概述和文件索引（低 token 开销）
|
||||
2. **判断相关文件**：根据用户问题和文件索引中的摘要，判断需要查阅哪些 parsed 文件
|
||||
2. **判断相关文件**：根据用户问题和摘要判断需要查阅哪些 parsed 文件
|
||||
3. **按需加载**：读取相关 parsed 文件的全部或部分内容
|
||||
4. **回答并标注来源**：基于获取的信息回答问题
|
||||
|
||||
### 来源引用格式
|
||||
## References
|
||||
|
||||
回答中引用具体信息时，使用以下格式标注来源：
|
||||
详细文档请参阅 `references/` 目录：
|
||||
|
||||
```
|
||||
根据《文件名》(parsed/文件名.md)，...
|
||||
```
|
||||
|
||||
多个来源时分别标注各信息点的来源文件。
|
||||
|
||||
### 无相关信息
|
||||
|
||||
当知识库中未找到与用户问题相关的信息时，明确告知用户，不编造答案。
|
||||
|
||||
### 空知识库
|
||||
|
||||
如果 project.md 文件索引为空（尚无已入库文件），应告知用户知识库为空，建议先使用 `/lyxy-kb-ingest` 入库文档。
|
||||
|
||||
## Notes
|
||||
|
||||
### 依赖关系
|
||||
|
||||
| 依赖 | 用途 |
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| lyxy-reader-office | 解析 .docx、.pdf、.pptx、.xlsx 文件为 markdown |
|
||||
| lyxy-runner-python | 通过 uv 执行 lyxy-reader-office 的 Python 解析脚本 |
|
||||
|
||||
### 限制
|
||||
|
||||
- 不支持向量化语义搜索
|
||||
- 不支持跨知识项目关联查询
|
||||
- 不支持文档版本对比或 diff
|
||||
- 不支持多用户协作或权限控制
|
||||
- 大量文件全量重写时 token 消耗较高
|
||||
| `references/structure.md` | 目录结构规范、project.md 格式、manifest.json 结构、parsed 元信息标记 |
|
||||
| `references/workflow.md` | 文档生命周期、归档命名规则、冲突检测、解析策略 |
|
||||
| `references/query-strategy.md` | 渐进式查询策略、来源引用格式、依赖关系、限制说明 |
|
||||
|
||||
43
skills/lyxy-kb/references/query-strategy.md
Normal file
43
skills/lyxy-kb/references/query-strategy.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# 渐进式查询策略
|
||||
|
||||
## 分层加载策略
|
||||
|
||||
问答时采用分层加载策略，节省 token：
|
||||
|
||||
1. **读取 project.md**：获取项目概述和文件索引（低 token 开销）
|
||||
2. **判断相关文件**：根据用户问题和文件索引中的摘要，判断需要查阅哪些 parsed 文件
|
||||
3. **按需加载**：读取相关 parsed 文件的全部或部分内容
|
||||
4. **回答并标注来源**：基于获取的信息回答问题
|
||||
|
||||
## 来源引用格式
|
||||
|
||||
回答中引用具体信息时，使用以下格式标注来源：
|
||||
|
||||
```
|
||||
根据《文件名》(parsed/文件名.md)，...
|
||||
```
|
||||
|
||||
多个来源时分别标注各信息点的来源文件。
|
||||
|
||||
## 无相关信息
|
||||
|
||||
当知识库中未找到与用户问题相关的信息时，明确告知用户，不编造答案。
|
||||
|
||||
## 空知识库
|
||||
|
||||
如果 project.md 文件索引为空（尚无已入库文件），应告知用户知识库为空，建议先使用 `/lyxy-kb-ingest` 入库文档。
|
||||
|
||||
## 依赖关系
|
||||
|
||||
| 依赖 | 用途 |
|
||||
|------|------|
|
||||
| lyxy-reader-office | 解析 .docx、.pdf、.pptx、.xlsx 文件为 markdown |
|
||||
| lyxy-runner-python | 通过 uv 执行 lyxy-reader-office 的 Python 解析脚本 |
|
||||
|
||||
## 限制
|
||||
|
||||
- 不支持向量化语义搜索
|
||||
- 不支持跨知识项目关联查询
|
||||
- 不支持文档版本对比或 diff
|
||||
- 不支持多用户协作或权限控制
|
||||
- 大量文件全量重写时 token 消耗较高
|
||||
125
skills/lyxy-kb/references/structure.md
Normal file
125
skills/lyxy-kb/references/structure.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# 知识项目目录结构
|
||||
|
||||
## 目录结构
|
||||
|
||||
每个知识项目是当前工作目录（CWD）下的一个子目录，包含以下固定结构：
|
||||
|
||||
```
|
||||
<project-name>/
|
||||
├── project.md # 高度摘要 + 文件索引
|
||||
├── manifest.json # 增量追踪
|
||||
├── parsed/ # 解析后的 markdown（中间产物）
|
||||
├── sources/ # 待处理区（用户放入原始文档）
|
||||
└── archive/ # 原始文件备份（带时间戳）
|
||||
```
|
||||
|
||||
### 各目录/文件职责
|
||||
|
||||
| 路径 | 职责 |
|
||||
|------|------|
|
||||
| `project.md` | 项目的高度摘要和文件索引，作为问答时的入口文件 |
|
||||
| `manifest.json` | 记录已处理文件的元信息，用于增量检测和版本追踪 |
|
||||
| `parsed/` | 存放解析后的 markdown 文件，便于大模型读取分析 |
|
||||
| `sources/` | 用户放入待处理文档的目录，解析后文件会被移走 |
|
||||
| `archive/` | 原始文件的备份，每个文件都带时间戳后缀 |
|
||||
|
||||
### 结构完整性验证
|
||||
|
||||
执行任何 command（ingest / rebuild / ask）时，必须先验证项目目录结构是否完整，即以下 5 项是否全部存在：
|
||||
- `<project-name>/project.md`
|
||||
- `<project-name>/manifest.json`
|
||||
- `<project-name>/parsed/`
|
||||
- `<project-name>/sources/`
|
||||
- `<project-name>/archive/`
|
||||
|
||||
若不完整，提示用户先执行 `/lyxy-kb-init <project-name>`，终止当前操作。
|
||||
|
||||
## 项目名称规则
|
||||
|
||||
项目名称只允许使用以下字符：
|
||||
- 中文字符
|
||||
- 英文字母（a-z、A-Z）
|
||||
- 数字（0-9）
|
||||
- 短横线（-）
|
||||
- 下划线（_）
|
||||
|
||||
**不允许包含空格或其他特殊字符。** 不符合规则时应提示用户修改。
|
||||
|
||||
## project.md 格式规范
|
||||
|
||||
```markdown
|
||||
# <项目名称>
|
||||
|
||||
## 概述
|
||||
（高度总结的项目信息，几百字以内）
|
||||
|
||||
## 关键信息
|
||||
（从所有文档中提炼的核心要点）
|
||||
|
||||
## 文件索引
|
||||
|
||||
| 文件名 | 解析文件 | 最新归档 | 摘要 |
|
||||
|--------|----------|----------|------|
|
||||
| 需求文档 | parsed/需求文档.md | archive/需求文档_202602181600.docx | 简要摘要... |
|
||||
|
||||
## 更新记录
|
||||
- 2026-02-18 16:00: 解析 需求文档.docx
|
||||
```
|
||||
|
||||
## manifest.json 结构
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "<项目名称>",
|
||||
"created_at": "2026-02-18T16:00",
|
||||
"last_ingest": "2026-02-18T17:25",
|
||||
"files": [
|
||||
{
|
||||
"name": "需求文档",
|
||||
"ext": ".docx",
|
||||
"parsed": "parsed/需求文档.md",
|
||||
"versions": [
|
||||
{
|
||||
"archived": "archive/需求文档_202602181600.docx",
|
||||
"hash": "sha256:abc123...",
|
||||
"ingested_at": "2026-02-18T16:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 字段说明
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `project` | 项目名称 |
|
||||
| `created_at` | 项目创建时间 |
|
||||
| `last_ingest` | 最近一次 ingest 的时间 |
|
||||
| `files[].name` | 文件名（不含扩展名） |
|
||||
| `files[].ext` | 原始文件扩展名 |
|
||||
| `files[].parsed` | 解析产物的相对路径 |
|
||||
| `files[].versions` | 版本历史数组 |
|
||||
| `files[].versions[].archived` | 归档文件的相对路径 |
|
||||
| `files[].versions[].hash` | 文件内容的 SHA-256 哈希（使用 `sha256sum` 命令计算） |
|
||||
| `files[].versions[].ingested_at` | 该版本的入库时间 |
|
||||
|
||||
## parsed 文件元信息标记
|
||||
|
||||
每个 parsed markdown 文件头部必须包含元信息注释：
|
||||
|
||||
```markdown
|
||||
<!-- source: 技术方案.pdf -->
|
||||
<!-- archived: archive/技术方案_202602181725.pdf -->
|
||||
<!-- parsed_at: 2026-02-18 17:25 -->
|
||||
|
||||
# 技术方案
|
||||
（文档正文内容...）
|
||||
```
|
||||
|
||||
| 元信息 | 说明 |
|
||||
|--------|------|
|
||||
| `source` | 原始文件名（含扩展名） |
|
||||
| `archived` | 对应的归档文件相对路径 |
|
||||
| `parsed_at` | 解析时间（YYYY-MM-DD HH:mm 格式） |
|
||||
86
skills/lyxy-kb/references/workflow.md
Normal file
86
skills/lyxy-kb/references/workflow.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# 文档生命周期和处理策略
|
||||
|
||||
## 文档生命周期
|
||||
|
||||
```
|
||||
用户放入 sources/（支持子目录）
|
||||
│
|
||||
▼
|
||||
检查文件（跳过空文件、检测冲突）
|
||||
│
|
||||
▼
|
||||
解析文件内容（失败则保留在 sources/）
|
||||
│
|
||||
├──▶ 写入 parsed/<文件名>.md（含头部元信息）
|
||||
│
|
||||
├──▶ 移动原始文件到 archive/<文件名_YYYYMMDDHHmm>.<ext>
|
||||
│
|
||||
├──▶ 更新 manifest.json
|
||||
│
|
||||
└──▶ 增量更新 project.md（追加文件索引和更新记录）
|
||||
```
|
||||
|
||||
## 归档命名规则
|
||||
|
||||
所有进入 archive 的文件都必须带时间戳后缀，格式为 `<文件名_YYYYMMDDHHmm>.<扩展名>`，即使只有一个版本。
|
||||
|
||||
示例：
|
||||
- `需求文档.docx` → `archive/需求文档_202602181600.docx`
|
||||
- `技术方案.pdf`（第二次入库）→ `archive/技术方案_202602181725.pdf`
|
||||
|
||||
## 同名文件更新
|
||||
|
||||
同名同扩展名的文件再次入库时：
|
||||
- `parsed/` 中的 markdown 文件被覆盖为最新版本
|
||||
- `archive/` 中保留所有历史版本（每个版本独立的时间戳文件）
|
||||
- `manifest.json` 中该文件条目的 `versions` 数组追加新版本记录
|
||||
|
||||
## 同名不同扩展名冲突检测
|
||||
|
||||
因为 parsed 产物以文件名（不含扩展名）+ `.md` 命名，同名不同扩展名的文件会产生冲突。
|
||||
|
||||
### 检测规则
|
||||
|
||||
1. **sources/ 内部检测**：扫描 sources/ 中所有文件（含子目录），如果存在同名但不同扩展名的文件（如 `技术方案.pdf` 和 `技术方案.docx`），拒绝处理并提示用户重命名
|
||||
2. **与已入库文件检测**：将 sources/ 中文件的名称（不含扩展名）与 manifest.json 中已有记录对比，如果名称相同但扩展名不同，拒绝处理并提示用户重命名
|
||||
|
||||
### 处理方式
|
||||
|
||||
冲突文件不予处理，保留在 sources/ 中，提示用户重命名后重新执行 ingest。非冲突文件正常处理。
|
||||
|
||||
## 文件类型解析策略
|
||||
|
||||
| 文件类型 | 解析方式 |
|
||||
|----------|----------|
|
||||
| `.docx`, `.pdf`, `.pptx`, `.xlsx` | 使用名为 **lyxy-reader-office** 的 skill 解析 |
|
||||
| 其他所有文件（`.md`, `.txt`, `.csv`, `.json`, `.xml`, `.yaml`, `.yml`, `.log`, `.html` 等） | 直接读取文件内容 |
|
||||
|
||||
### Office 文档解析
|
||||
|
||||
解析 office 文档时，必须查找当前环境中名为 **lyxy-reader-office** 的 skill，阅读其 SKILL.md 获取具体的执行方式和命令。
|
||||
|
||||
**如果环境中不存在 lyxy-reader-office skill，且没有其他可替代的文档解析 skill，则提示用户无法处理 office 文档，中止整个 ingest 流程。**
|
||||
|
||||
### sources/ 扫描规则
|
||||
|
||||
扫描 sources/ 时**递归检查所有子目录**中的文件。parsed 产物的路径仍为 `parsed/<文件名>.md`（扁平化存放），不保留 sources 中的子目录结构。
|
||||
|
||||
### 空文件处理
|
||||
|
||||
sources/ 中 0 字节的空文件应**跳过处理**，不解析、不归档、不更新 manifest。处理完成后向用户列出被跳过的空文件列表，提示用户检查。
|
||||
|
||||
### 解析失败处理
|
||||
|
||||
如果某个文件解析失败（如文档损坏、解析器报错），该文件**保留在 sources/ 中不移动**，报告错误信息，继续处理其他文件。
|
||||
|
||||
## 更新策略
|
||||
|
||||
**增量追加**（默认，由 ingest 触发）：
|
||||
- 新文件：在文件索引表追加新行，在更新记录追加条目
|
||||
- 已有文件更新：覆盖文件索引表中对应行的最新归档路径和摘要
|
||||
- 概述和关键信息部分**不**自动更新
|
||||
|
||||
**全量重写**（由 rebuild 触发）：
|
||||
- 读取所有 parsed/*.md 文件
|
||||
- 重新生成概述、关键信息、文件索引
|
||||
- 保留历史更新记录，追加本次 rebuild 条目
|
||||
@@ -14,21 +14,6 @@ compatibility: Requires Python 3.6+. DOCX/PPTX/XLSX 无需额外依赖（XML 原
|
||||
|
||||
**依赖选项**：此 skill 必须优先使用 lyxy-runner-python skill 执行，不可用时降级到直接 Python 执行。
|
||||
|
||||
### 必须使用 lyxy-runner-python
|
||||
|
||||
如果环境中存在 lyxy-runner-python skill，**必须**使用它来执行 parser.py 脚本：
|
||||
- lyxy-runner-python 使用 uv 管理依赖，自动安装所需的第三方库
|
||||
- 环境隔离，不污染系统 Python
|
||||
- 跨平台兼容（Windows/macOS/Linux）
|
||||
|
||||
### 降级到直接执行
|
||||
|
||||
**仅当** lyxy-runner-python skill 不存在时，才降级到直接 Python 执行：
|
||||
- 需要用户手动安装依赖
|
||||
- DOCX/PPTX/XLSX 无需依赖也可通过 XML 原生解析工作
|
||||
- PDF 至少需要安装 pypdf
|
||||
- **禁止自动执行 pip install**，仅向用户提示安装建议
|
||||
|
||||
## When to Use
|
||||
|
||||
任何需要读取或解析 .docx、.xlsx、.pptx、.pdf 文件内容的任务都应使用此 skill。
|
||||
@@ -41,100 +26,12 @@ compatibility: Requires Python 3.6+. DOCX/PPTX/XLSX 无需额外依赖（XML 原
|
||||
- **内容搜索**：在文档中搜索关键词或模式
|
||||
- **PDF OCR**：对扫描版 PDF 启用 OCR 高精度解析
|
||||
|
||||
### 不适用场景
|
||||
- 需要提取图片内容（仅支持纯文本）
|
||||
- 需要保留复杂的格式信息（字体、颜色、布局）
|
||||
- 需要编辑或修改文档
|
||||
- 需要处理 .doc、.xls、.ppt 等旧格式
|
||||
|
||||
### 触发词
|
||||
- 中文："读取/解析/打开 docx/word/xlsx/excel/pptx/pdf 文档"
|
||||
- 英文："read/parse/extract docx/word/xlsx/excel/pptx/powerpoint/pdf"
|
||||
- 文件扩展名：`.docx`、`.xlsx`、`.pptx`、`.pdf`
|
||||
|
||||
**中文触发词**
|
||||
- "读取/解析/打开 docx/word 文档"
|
||||
- "读取/解析/打开 xlsx/excel 文件"
|
||||
- "读取/解析/打开 pptx/ppt 文件"
|
||||
- "读取/解析/打开 pdf 文件"
|
||||
|
||||
**英文触发词**
|
||||
- "read/parse/extract docx/word/xlsx/excel/pptx/powerpoint/pdf"
|
||||
|
||||
**文件扩展名**
|
||||
- `.docx`、`.xlsx`、`.pptx`、`.pdf`
|
||||
|
||||
## Capabilities
|
||||
|
||||
### 1. 全文转换为 Markdown
|
||||
将完整文档解析为 Markdown 格式，移除图片但保留文本格式（标题、列表、表格、粗体、斜体等）。
|
||||
|
||||
各格式的输出特点：
|
||||
- **DOCX**：标准 Markdown 文档结构
|
||||
- **PPTX**：每张幻灯片以 `## Slide N` 为标题，幻灯片之间以 `---` 分隔
|
||||
- **XLSX**：以 `## SheetName` 区分工作表，数据以 Markdown 表格呈现
|
||||
- **PDF**：纯文本流，使用 `--high-res` 可启用 OCR 版面分析识别标题
|
||||
|
||||
### 2. 获取文档元信息
|
||||
- 字数统计（`-c` 参数）
|
||||
- 行数统计（`-l` 参数）
|
||||
|
||||
### 3. 标题列表提取
|
||||
提取文档中所有 1-6 级标题（`-t` 参数），按原始层级关系返回。
|
||||
|
||||
### 4. 指定章节内容提取
|
||||
根据标题名称提取特定章节的完整内容（`-tc` 参数），包含上级标题链和所有下级内容。
|
||||
|
||||
### 5. 正则表达式搜索
|
||||
在文档中搜索关键词或模式（`-s` 参数），支持自定义上下文行数（`-n` 参数，默认 2 行）。
|
||||
|
||||
### 6. PDF OCR 高精度模式
|
||||
对 PDF 文件启用 OCR 版面分析（`--high-res` 参数），适用于扫描版 PDF 或需要识别标题层级的场景。
|
||||
|
||||
## Execution
|
||||
|
||||
### 详细用法参考
|
||||
|
||||
**执行前请阅读 `scripts/README.md`**，其中包含：
|
||||
- 完整的命令行参数说明
|
||||
- 各格式的依赖安装指南（pip 和 uv 方式）
|
||||
- 解析器优先级和对比
|
||||
- 输出格式说明
|
||||
- 错误处理和常见问题
|
||||
|
||||
### 基本语法
|
||||
|
||||
```bash
|
||||
python parser.py <file_path> [options]
|
||||
```
|
||||
|
||||
### 使用 lyxy-runner-python 执行（必须优先使用）
|
||||
|
||||
```bash
|
||||
# DOCX - 推荐依赖
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
|
||||
|
||||
# PPTX - 推荐依赖
|
||||
uv run --with "markitdown[pptx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.pptx
|
||||
|
||||
# XLSX - 推荐依赖
|
||||
uv run --with "markitdown[xlsx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.xlsx
|
||||
|
||||
# PDF - 推荐依赖
|
||||
uv run --with "markitdown[pdf]" --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/file.pdf
|
||||
|
||||
# PDF OCR 高精度模式
|
||||
uv run --with docling --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/file.pdf --high-res
|
||||
```
|
||||
|
||||
> **注意**：以上为最小推荐依赖，更多解析器依赖和完整安装命令请查阅 `scripts/README.md` 的安装部分。
|
||||
|
||||
### 降级到直接 Python 执行
|
||||
|
||||
仅当 lyxy-runner-python skill 不存在时使用：
|
||||
|
||||
```bash
|
||||
python3 skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
|
||||
```
|
||||
|
||||
### 互斥参数
|
||||
## Quick Reference
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
@@ -142,71 +39,36 @@ python3 skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
|
||||
| `-c` | 字数统计 |
|
||||
| `-l` | 行数统计 |
|
||||
| `-t` | 提取所有标题 |
|
||||
| `-tc <name>` | 提取指定标题的章节内容（name 不含 # 号） |
|
||||
| `-tc <name>` | 提取指定标题的章节内容 |
|
||||
| `-s <pattern>` | 正则表达式搜索 |
|
||||
| `-n <num>` | 与 `-s` 配合，指定上下文行数（默认 2） |
|
||||
| `-n <num>` | 与 `-s` 配合，指定上下文行数 |
|
||||
| `--high-res` | PDF 专用，启用 OCR 版面分析 |
|
||||
|
||||
## Examples
|
||||
## Workflow
|
||||
|
||||
1. **检查依赖**：优先使用 lyxy-runner-python，否则降级到直接 Python 执行
|
||||
2. **选择格式**：根据文件扩展名自动识别格式
|
||||
3. **执行解析**：调用 `scripts/parser.py` 并传入参数
|
||||
4. **输出结果**：返回 Markdown 格式内容或统计信息
|
||||
|
||||
### 基本语法
|
||||
|
||||
### 提取完整文档内容
|
||||
```bash
|
||||
# DOCX
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/report.docx
|
||||
# 使用 lyxy-runner-python（推荐）
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
|
||||
|
||||
# PPTX
|
||||
uv run --with "markitdown[pptx]" skills/lyxy-reader-office/scripts/parser.py /path/to/slides.pptx
|
||||
|
||||
# XLSX
|
||||
uv run --with "markitdown[xlsx]" skills/lyxy-reader-office/scripts/parser.py /path/to/data.xlsx
|
||||
|
||||
# PDF
|
||||
uv run --with "markitdown[pdf]" --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/doc.pdf
|
||||
# 降级到直接执行
|
||||
python3 skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
|
||||
```
|
||||
|
||||
### 获取文档字数
|
||||
```bash
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -c /path/to/report.docx
|
||||
```
|
||||
## References
|
||||
|
||||
### 提取所有标题
|
||||
```bash
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -t /path/to/report.docx
|
||||
```
|
||||
详细文档请参阅 `references/` 目录：
|
||||
|
||||
### 提取指定章节
|
||||
```bash
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -tc "第一章" /path/to/report.docx
|
||||
```
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| `references/examples.md` | 各格式完整提取、字数统计、标题提取、章节提取、搜索等示例 |
|
||||
| `references/parsers.md` | 解析器说明、依赖安装、各格式输出特点、能力说明 |
|
||||
| `references/error-handling.md` | 限制说明、最佳实践、依赖执行策略 |
|
||||
|
||||
### 搜索关键词
|
||||
```bash
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -s "关键词" -n 3 /path/to/report.docx
|
||||
```
|
||||
|
||||
### PDF OCR 高精度解析
|
||||
```bash
|
||||
uv run --with docling --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/scanned.pdf --high-res
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
### 多策略解析降级
|
||||
|
||||
每种文件格式配备多个解析器，按优先级依次尝试，前一个失败自动回退到下一个。详细的解析器优先级和对比请查阅 `scripts/README.md`。
|
||||
|
||||
### 限制
|
||||
|
||||
- 不支持图片提取（仅纯文本）
|
||||
- 不支持复杂的格式保留（字体、颜色、布局等）
|
||||
- 不支持文档编辑或修改
|
||||
- 仅支持 .docx、.xlsx、.pptx、.pdf 格式（不支持 .doc、.xls、.ppt 等旧格式）
|
||||
- PDF 无内置 XML 原生解析，至少需要安装 pypdf
|
||||
|
||||
### 最佳实践
|
||||
|
||||
1. **必须优先使用 lyxy-runner-python**：如果环境中存在，必须使用 lyxy-runner-python 执行脚本
|
||||
2. **查阅 README**：详细参数、依赖安装、解析器对比等信息请阅读 `scripts/README.md`
|
||||
3. **大文件处理**：对于大文档，建议使用章节提取（`-tc`）或搜索（`-s`）来限制处理范围
|
||||
4. **PDF 标题**：PDF 是版面描述格式，默认不含语义化标题；需要标题层级时使用 `--high-res`
|
||||
5. **禁止自动安装**：降级到直接 Python 执行时，仅向用户提示安装依赖，不得自动执行 pip install
|
||||
> **详细用法**：请阅读 `scripts/README.md` 获取完整的命令行参数和依赖安装指南。
|
||||
|
||||
41
skills/lyxy-reader-office/references/error-handling.md
Normal file
41
skills/lyxy-reader-office/references/error-handling.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# 错误处理和限制说明
|
||||
|
||||
## 限制
|
||||
|
||||
- 不支持图片提取（仅纯文本）
|
||||
- 不支持复杂的格式保留（字体、颜色、布局等）
|
||||
- 不支持文档编辑或修改
|
||||
- 仅支持 .docx、.xlsx、.pptx、.pdf 格式（不支持 .doc、.xls、.ppt 等旧格式）
|
||||
- PDF 无内置 XML 原生解析，至少需要安装 pypdf
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **必须优先使用 lyxy-runner-python**：如果环境中存在，必须使用 lyxy-runner-python 执行脚本
|
||||
2. **查阅 README**：详细参数、依赖安装、解析器对比等信息请阅读 `scripts/README.md`
|
||||
3. **大文件处理**：对于大文档，建议使用章节提取（`-tc`）或搜索（`-s`）来限制处理范围
|
||||
4. **PDF 标题**：PDF 是版面描述格式，默认不含语义化标题；需要标题层级时使用 `--high-res`
|
||||
5. **禁止自动安装**：降级到直接 Python 执行时，仅向用户提示安装依赖，不得自动执行 pip install
|
||||
|
||||
## 依赖执行策略
|
||||
|
||||
### 必须使用 lyxy-runner-python
|
||||
|
||||
如果环境中存在 lyxy-runner-python skill，**必须**使用它来执行 parser.py 脚本：
|
||||
- lyxy-runner-python 使用 uv 管理依赖，自动安装所需的第三方库
|
||||
- 环境隔离，不污染系统 Python
|
||||
- 跨平台兼容（Windows/macOS/Linux）
|
||||
|
||||
### 降级到直接执行
|
||||
|
||||
**仅当** lyxy-runner-python skill 不存在时，才降级到直接 Python 执行：
|
||||
- 需要用户手动安装依赖
|
||||
- DOCX/PPTX/XLSX 无需依赖也可通过 XML 原生解析工作
|
||||
- PDF 至少需要安装 pypdf
|
||||
- **禁止自动执行 pip install**，仅向用户提示安装建议
|
||||
|
||||
## 不适用场景
|
||||
|
||||
- 需要提取图片内容（仅支持纯文本）
|
||||
- 需要保留复杂的格式信息（字体、颜色、布局）
|
||||
- 需要编辑或修改文档
|
||||
- 需要处理 .doc、.xls、.ppt 等旧格式
|
||||
55
skills/lyxy-reader-office/references/examples.md
Normal file
55
skills/lyxy-reader-office/references/examples.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# 示例
|
||||
|
||||
## 提取完整文档内容
|
||||
|
||||
```bash
|
||||
# DOCX
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/report.docx
|
||||
|
||||
# PPTX
|
||||
uv run --with "markitdown[pptx]" skills/lyxy-reader-office/scripts/parser.py /path/to/slides.pptx
|
||||
|
||||
# XLSX
|
||||
uv run --with "markitdown[xlsx]" skills/lyxy-reader-office/scripts/parser.py /path/to/data.xlsx
|
||||
|
||||
# PDF
|
||||
uv run --with "markitdown[pdf]" --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/doc.pdf
|
||||
```
|
||||
|
||||
## 获取文档字数
|
||||
|
||||
```bash
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -c /path/to/report.docx
|
||||
```
|
||||
|
||||
## 提取所有标题
|
||||
|
||||
```bash
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -t /path/to/report.docx
|
||||
```
|
||||
|
||||
## 提取指定章节
|
||||
|
||||
```bash
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -tc "第一章" /path/to/report.docx
|
||||
```
|
||||
|
||||
## 搜索关键词
|
||||
|
||||
```bash
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -s "关键词" -n 3 /path/to/report.docx
|
||||
```
|
||||
|
||||
## PDF OCR 高精度解析
|
||||
|
||||
```bash
|
||||
uv run --with docling --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/scanned.pdf --high-res
|
||||
```
|
||||
|
||||
## 降级到直接 Python 执行
|
||||
|
||||
仅当 lyxy-runner-python skill 不存在时使用：
|
||||
|
||||
```bash
|
||||
python3 skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
|
||||
```
|
||||
58
skills/lyxy-reader-office/references/parsers.md
Normal file
58
skills/lyxy-reader-office/references/parsers.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# 解析器说明和依赖安装
|
||||
|
||||
## 多策略解析降级
|
||||
|
||||
每种文件格式配备多个解析器，按优先级依次尝试，前一个失败自动回退到下一个。
|
||||
|
||||
详细的解析器优先级和对比请查阅 `scripts/README.md`。
|
||||
|
||||
## 依赖安装
|
||||
|
||||
### 使用 uv（推荐）
|
||||
|
||||
```bash
|
||||
# DOCX - 推荐依赖
|
||||
uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
|
||||
|
||||
# PPTX - 推荐依赖
|
||||
uv run --with "markitdown[pptx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.pptx
|
||||
|
||||
# XLSX - 推荐依赖
|
||||
uv run --with "markitdown[xlsx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.xlsx
|
||||
|
||||
# PDF - 推荐依赖
|
||||
uv run --with "markitdown[pdf]" --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/file.pdf
|
||||
|
||||
# PDF OCR 高精度模式
|
||||
uv run --with docling --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/file.pdf --high-res
|
||||
```
|
||||
|
||||
> **注意**：以上为最小推荐依赖，更多解析器依赖和完整安装命令请查阅 `scripts/README.md` 的安装部分。
|
||||
|
||||
## 各格式输出特点
|
||||
|
||||
- **DOCX**：标准 Markdown 文档结构
|
||||
- **PPTX**：每张幻灯片以 `## Slide N` 为标题，幻灯片之间以 `---` 分隔
|
||||
- **XLSX**：以 `## SheetName` 区分工作表，数据以 Markdown 表格呈现
|
||||
- **PDF**：纯文本流，使用 `--high-res` 可启用 OCR 版面分析识别标题
|
||||
|
||||
## 能力说明
|
||||
|
||||
### 1. 全文转换为 Markdown
|
||||
将完整文档解析为 Markdown 格式，移除图片但保留文本格式（标题、列表、表格、粗体、斜体等）。
|
||||
|
||||
### 2. 获取文档元信息
|
||||
- 字数统计（`-c` 参数）
|
||||
- 行数统计（`-l` 参数）
|
||||
|
||||
### 3. 标题列表提取
|
||||
提取文档中所有 1-6 级标题（`-t` 参数），按原始层级关系返回。
|
||||
|
||||
### 4. 指定章节内容提取
|
||||
根据标题名称提取特定章节的完整内容（`-tc` 参数），包含上级标题链和所有下级内容。
|
||||
|
||||
### 5. 正则表达式搜索
|
||||
在文档中搜索关键词或模式（`-s` 参数），支持自定义上下文行数（`-n` 参数，默认 2 行）。
|
||||
|
||||
### 6. PDF OCR 高精度模式
|
||||
对 PDF 文件启用 OCR 版面分析（`--high-res` 参数），适用于扫描版 PDF 或需要识别标题层级的场景。
|
||||
@@ -8,319 +8,69 @@ compatibility: Requires Bun runtime (https://bun.sh)
|
||||
|
||||
基于 Bun 的 JavaScript/TypeScript 执行技能，提供隔离的脚本执行和自动依赖管理。
|
||||
|
||||
## 快速参考
|
||||
## Purpose
|
||||
|
||||
根据您的需求选择使用方式：
|
||||
**必需依赖**: 此 skill 需要 Bun 运行时，不兼容其他 JavaScript 运行时。
|
||||
|
||||
Bun 特性：
|
||||
- 自动检测和下载依赖（无需 package.json）
|
||||
- 即时转译 TypeScript
|
||||
- 跨平台兼容（Windows/macOS/Linux）
|
||||
|
||||
**重要**: 如果 Bun 未安装，立即停止任务并引导用户安装。禁止使用 nodejs、npm、yarn、pnpm 等替代工具。
|
||||
|
||||
## When to Use
|
||||
|
||||
任何 JavaScript/TypeScript 处理任务都应使用此 skill。
|
||||
|
||||
### 典型场景
|
||||
- **数据处理**: JSON/CSV 解析、数据转换
|
||||
- **API 交互**: HTTP 请求、Web API 调用
|
||||
- **文件操作**: 文件读写、批量处理
|
||||
- **脚本自动化**: 构建脚本、任务自动化
|
||||
|
||||
### 不适用场景
|
||||
- ✗ 需要 Node.js 特定 API（如部分原生模块）
|
||||
- ✗ 需要持久化进程（如服务器）
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| 场景 | 描述 | 命令 |
|
||||
| --------- | ------------------------ | ---------------------------------- |
|
||||
| **场景1** | 直接执行已存在的脚本文件 | `bun <script-file>` |
|
||||
| **场景2** | 在指定路径创建脚本并执行 | 使用 Write 工具创建 → `bun <path>` |
|
||||
| **场景3** | 使用临时路径执行（默认） | 生成临时路径 → `bun <temp-file>` |
|
||||
|------|------|------|
|
||||
| 场景1 | 直接执行已存在的脚本 | `bun <script-file>` |
|
||||
| 场景2 | 在指定路径创建脚本并执行 | 使用 Write 工具创建 → `bun <path>` |
|
||||
| 场景3 | 使用临时路径执行（默认） | 生成临时路径 → `bun <temp-file>` |
|
||||
|
||||
**重要提示：** 所有场景在执行脚本前都必须先检查 Bun 环境：`bun --version`
|
||||
**重要**: 所有场景执行前必须先检查 Bun 环境：`bun --version`
|
||||
|
||||
## 前置条件
|
||||
## Workflow
|
||||
|
||||
### 安装 Bun
|
||||
1. **检查 Bun 环境**：执行 `bun --version`，失败则停止并提示安装
|
||||
2. **选择执行场景**：根据用户意图选择场景1/2/3
|
||||
3. **执行脚本**：使用 `bun <script>` 运行
|
||||
4. **捕获输出**：stdout/stderr 分别处理
|
||||
|
||||
lyxy-runner-js 需要安装 Bun。Bun 是一个快速的 JavaScript 运行时，内置包管理器。
|
||||
|
||||
**macOS/Linux:**
|
||||
### 临时路径执行（场景3）
|
||||
|
||||
```bash
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
|
||||
```powershell
|
||||
powershell -c "irm bun.sh/install.ps1 | iex"
|
||||
```
|
||||
|
||||
**验证安装:**
|
||||
|
||||
```bash
|
||||
bun --version
|
||||
```
|
||||
|
||||
## 使用流程
|
||||
|
||||
**执行流程决策树：**
|
||||
|
||||
1. **步骤1：检查 Bun 环境**
|
||||
- 执行：`bun --version`
|
||||
- 失败 → 输出错误信息（包含安装说明）并停止执行
|
||||
- 成功 → 进入下一步
|
||||
- **重要：** 禁止使用 nodejs、npm、yarn、pnpm 等其他工具
|
||||
|
||||
2. **步骤2：选择执行场景**
|
||||
- 场景1：用户提供了已存在的脚本文件路径？
|
||||
- 是 → 直接执行：`bun <script-file>`
|
||||
- 否 → 进入下一步
|
||||
- 场景2：用户指定了脚本的生成路径？
|
||||
- 是 → 使用 Write 工具创建脚本，然后执行
|
||||
- 否 → 进入场景3
|
||||
|
||||
3. **场景3（默认）**：使用临时路径执行
|
||||
- 生成临时文件路径
|
||||
- 将脚本内容写入临时文件
|
||||
- 使用 Bun 运行脚本
|
||||
- 临时文件由系统自动处理
|
||||
|
||||
---
|
||||
|
||||
### 场景1：执行已存在的脚本文件
|
||||
|
||||
```bash
|
||||
# 步骤 1: 检查 Bun 是否已安装
|
||||
bun --version
|
||||
|
||||
# 步骤 2: 直接执行已存在的脚本
|
||||
bun ./scripts/my-script.js
|
||||
|
||||
# 脚本的输出将自动显示
|
||||
```
|
||||
|
||||
**关键特点：**
|
||||
- ✅ **无需生成临时文件** - 直接执行用户提供的脚本
|
||||
- ✅ **保持脚本位置** - 脚本留在原位置，不会被移动或复制
|
||||
- ✅ **简洁快速** - 跳过文件生成步骤，直接执行
|
||||
|
||||
### 场景2：在指定路径创建并执行脚本
|
||||
|
||||
```bash
|
||||
# 步骤 1: 检查 Bun 是否已安装
|
||||
bun --version
|
||||
|
||||
# 步骤 2: 使用 Write 工具在指定路径创建脚本
|
||||
# (以下步骤由大模型使用 Write 工具完成)
|
||||
# write content to "./scripts/new-script.js"
|
||||
|
||||
const greeting = "Hello from custom path!";
|
||||
console.log(greeting);
|
||||
|
||||
# 步骤 3: 执行脚本
|
||||
bun ./scripts/new-script.js
|
||||
```
|
||||
|
||||
**关键特点：**
|
||||
- ✅ **自定义路径** - 脚本创建到用户指定的位置
|
||||
- ✅ **持久化存储** - 脚本文件保存在指定位置，不会被自动清理
|
||||
- ✅ **灵活控制** - 用户可以精确控制脚本位置和命名
|
||||
|
||||
### 场景3：使用临时路径执行（默认流程）
|
||||
|
||||
当用户未提供任何路径信息时，使用临时路径执行脚本（默认流程）：
|
||||
|
||||
#### 基础示例
|
||||
|
||||
```bash
|
||||
# 步骤 1: 检查 Bun 是否已安装
|
||||
bun --version
|
||||
|
||||
# 步骤 2: 生成临时文件路径
|
||||
# 生成临时文件路径
|
||||
TEMP_FILE=$(bun skills/lyxy-runner-js/scripts/get_temp_path.js js)
|
||||
|
||||
# 步骤 3: 将脚本内容写入临时文件
|
||||
# 写入脚本内容
|
||||
cat <<EOF > "$TEMP_FILE"
|
||||
const greeting = "Hello from lyxy-runner-js!";
|
||||
console.log(greeting);
|
||||
console.log("Hello from lyxy-runner-js!");
|
||||
EOF
|
||||
|
||||
# 步骤 4: 执行脚本
|
||||
# 执行脚本
|
||||
bun "$TEMP_FILE"
|
||||
|
||||
# 步骤 5: 输出已在上面捕获
|
||||
# 临时文件将由系统自动清理
|
||||
```
|
||||
|
||||
#### TypeScript 示例
|
||||
## References
|
||||
|
||||
```bash
|
||||
# 生成 TypeScript 临时文件
|
||||
TEMP_TS=$(bun skills/lyxy-runner-js/scripts/get_temp_path.js ts)
|
||||
详细文档请参阅 `references/` 目录：
|
||||
|
||||
# 写入 TypeScript 脚本
|
||||
cat <<EOF > "$TEMP_TS"
|
||||
const message: string = 'TypeScript execution';
|
||||
console.log(message);
|
||||
EOF
|
||||
|
||||
# 执行 - Bun 会自动转译 TypeScript
|
||||
bun "$TEMP_TS"
|
||||
```
|
||||
|
||||
**Bun 自动处理：**
|
||||
- 检测 `import` 语句
|
||||
- 即时转译 TypeScript
|
||||
- 下载并缓存依赖（到 `~/.bun/install/cache`）
|
||||
- 无需 `package.json` 或手动安装
|
||||
|
||||
## 依赖管理
|
||||
|
||||
Bun 提供自动依赖管理，无需手动配置：
|
||||
|
||||
### 导入外部包
|
||||
|
||||
```javascript
|
||||
// ESM import（推荐）
|
||||
import axios from 'axios'
|
||||
import lodash from 'lodash'
|
||||
|
||||
// CommonJS import（也支持）
|
||||
const axios = require('axios')
|
||||
```
|
||||
|
||||
首次执行带有外部导入的脚本时，Bun 会：
|
||||
|
||||
1. 分析导入
|
||||
2. 从 npm 下载缺失的依赖
|
||||
3. 全局缓存到 `~/.bun/install/cache`
|
||||
4. 后续运行使用缓存版本
|
||||
|
||||
### 不需要 package.json
|
||||
|
||||
与 Node.js 不同，你无需创建 `package.json` 或单独运行 `bun install`。Bun 在运行时自动处理所有操作。
|
||||
|
||||
## 辅助函数 API
|
||||
|
||||
### `get_temp_path.js`
|
||||
|
||||
为脚本执行生成唯一的临时文件路径。
|
||||
|
||||
**CLI 使用方式:**
|
||||
|
||||
```bash
|
||||
bun skills/lyxy-runner-js/scripts/get_temp_path.js <extension>
|
||||
```
|
||||
|
||||
**参数:**
|
||||
|
||||
- `extension` (可选): 文件扩展名。默认为 `js`。常用值: `js`, `ts`, `mjs`, `mts`
|
||||
|
||||
**输出:** 返回类似 `/var/folders/.../lyxy-runner-js-1234567890-abc123.js` 的路径
|
||||
|
||||
**路径格式:**
|
||||
|
||||
- 使用操作系统临时目录（Unix 上为 `/tmp`，Windows 上为 `%TEMP%`）
|
||||
- 前缀: `lyxy-runner-js-`
|
||||
- 时间戳: 自纪元以来的毫秒数
|
||||
- 随机字符串: 7 字符字母数字
|
||||
- 扩展名: 参数中提供的值
|
||||
|
||||
**示例:**
|
||||
|
||||
```bash
|
||||
$ bun skills/lyxy-runner-js/scripts/get_temp_path.js js
|
||||
/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/lyxy-runner-js-1770257905333-na6ujx.js
|
||||
|
||||
$ bun skills/lyxy-runner-js/scripts/get_temp_path.js ts
|
||||
/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/lyxy-runner-js-1770257905333-v8yzt.ts
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 未安装 Bun
|
||||
|
||||
**症状:** `bun --version` 失败或返回 "command not found: bun"
|
||||
|
||||
**错误处理：**
|
||||
|
||||
当检测到 Bun 未安装时，必须：
|
||||
|
||||
1. **停止执行** - 不进行任何后续操作
|
||||
2. **输出明确错误信息** - 清晰说明 "Bun 运行时未安装" 或类似提示
|
||||
3. **提供安装说明** - 参考"前置条件"章节的安装命令
|
||||
|
||||
**重要限制：**
|
||||
|
||||
- ❌ **禁止自动安装** - 不要尝试自动安装 Bun，由用户自行决定
|
||||
- ❌ **禁止使用其他工具** - 不要尝试使用 nodejs、npm、yarn、pnpm 等其他 JavaScript 运行时或包管理工具
|
||||
- ❌ **禁止格式转换** - 不要建议用户将脚本转换为其他运行时格式
|
||||
|
||||
**正确做法：**
|
||||
|
||||
- ✅ 仅输出错误信息和安装说明
|
||||
- ✅ 等待用户安装 Bun 后再继续
|
||||
- ✅ 保持使用 Bun 作为唯一运行时
|
||||
|
||||
### 脚本语法错误
|
||||
|
||||
Bun 提供详细的语法错误信息：
|
||||
|
||||
```bash
|
||||
$ bun "$TEMP_FILE"
|
||||
error: Unexpected token
|
||||
--> /var/folders/.../script.js:2:10
|
||||
|
|
||||
2 | const = 123;
|
||||
| ^
|
||||
```
|
||||
|
||||
错误信息包括：
|
||||
|
||||
- 文件路径和行号
|
||||
- 错误的确切位置
|
||||
- 问题描述
|
||||
|
||||
### 运行时错误
|
||||
|
||||
运行时错误包含完整的堆栈跟踪：
|
||||
|
||||
```bash
|
||||
$ bun "$TEMP_FILE"
|
||||
ReferenceError: foo is not defined
|
||||
at script.js:3:5
|
||||
at main (script.js:1:1)
|
||||
```
|
||||
|
||||
### 其他错误
|
||||
|
||||
其他任何形式的错误都原样输出
|
||||
|
||||
## 输出处理
|
||||
|
||||
### 标准输出
|
||||
|
||||
所有 `console.log()`, `console.info()`, `console.warn()` 输出都到 stdout：
|
||||
|
||||
```bash
|
||||
bun "$TEMP_FILE" # stdout 由调用代码捕获
|
||||
```
|
||||
|
||||
### 错误输出
|
||||
|
||||
`console.error()` 输出到 stderr：
|
||||
|
||||
```bash
|
||||
bun "$TEMP_FILE" 2>error.log # 单独捕获 stderr
|
||||
```
|
||||
|
||||
### 退出码
|
||||
|
||||
脚本可以设置自定义退出码：
|
||||
|
||||
```javascript
|
||||
process.exit(1) // 错误
|
||||
process.exit(0) // 成功
|
||||
```
|
||||
|
||||
调用者接收这些退出码以确定执行状态。
|
||||
|
||||
## 临时文件管理
|
||||
|
||||
执行后 **不会主动删除** 临时文件。这是设计使然：
|
||||
|
||||
- 操作系统自动管理临时目录空间
|
||||
- 文件可以保留用于调试目的
|
||||
- 大多数操作系统定期清理旧的临时文件
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **始终先检查 Bun 环境** - 所有场景第一步都执行 `bun --version`
|
||||
2. **根据用户意图选择场景** - 查看快速参考选择合适的使用方式
|
||||
3. **单独处理 stdout/stderr** - 以区分输出和错误
|
||||
4. **检查退出码** - 以检测脚本失败
|
||||
5. **使用 ESM imports** - 使用 `import from` 编写现代 JavaScript
|
||||
6. **捕获并显示错误** - 以帮助用户调试问题
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| `references/examples.md` | 各场景完整示例、TypeScript 示例、依赖管理示例 |
|
||||
| `references/error-handling.md` | Bun 未安装、语法错误、运行时错误处理 |
|
||||
| `references/best-practices.md` | 输出处理、临时文件管理、辅助函数 API |
|
||||
|
||||
83
skills/lyxy-runner-js/references/best-practices.md
Normal file
83
skills/lyxy-runner-js/references/best-practices.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# 最佳实践和输出处理
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **始终先检查 Bun 环境** - 所有场景第一步都执行 `bun --version`
|
||||
2. **根据用户意图选择场景** - 查看快速参考选择合适的使用方式
|
||||
3. **单独处理 stdout/stderr** - 以区分输出和错误
|
||||
4. **检查退出码** - 以检测脚本失败
|
||||
5. **使用 ESM imports** - 使用 `import from` 编写现代 JavaScript
|
||||
6. **捕获并显示错误** - 以帮助用户调试问题
|
||||
|
||||
## 输出处理
|
||||
|
||||
### 标准输出
|
||||
|
||||
所有 `console.log()`, `console.info()`, `console.warn()` 输出都到 stdout：
|
||||
|
||||
```bash
|
||||
bun "$TEMP_FILE" # stdout 由调用代码捕获
|
||||
```
|
||||
|
||||
### 错误输出
|
||||
|
||||
`console.error()` 输出到 stderr：
|
||||
|
||||
```bash
|
||||
bun "$TEMP_FILE" 2>error.log # 单独捕获 stderr
|
||||
```
|
||||
|
||||
### 退出码
|
||||
|
||||
脚本可以设置自定义退出码：
|
||||
|
||||
```javascript
|
||||
process.exit(1) // 错误
|
||||
process.exit(0) // 成功
|
||||
```
|
||||
|
||||
调用者接收这些退出码以确定执行状态。
|
||||
|
||||
## 临时文件管理
|
||||
|
||||
执行后 **不会主动删除** 临时文件。这是设计使然：
|
||||
|
||||
- 操作系统自动管理临时目录空间
|
||||
- 文件可以保留用于调试目的
|
||||
- 大多数操作系统定期清理旧的临时文件
|
||||
|
||||
## 辅助函数 API
|
||||
|
||||
### `get_temp_path.js`
|
||||
|
||||
为脚本执行生成唯一的临时文件路径。
|
||||
|
||||
**CLI 使用方式:**
|
||||
|
||||
```bash
|
||||
bun skills/lyxy-runner-js/scripts/get_temp_path.js <extension>
|
||||
```
|
||||
|
||||
**参数:**
|
||||
|
||||
- `extension` (可选): 文件扩展名。默认为 `js`。常用值: `js`, `ts`, `mjs`, `mts`
|
||||
|
||||
**输出:** 返回类似 `/var/folders/.../lyxy-runner-js-1234567890-abc123.js` 的路径
|
||||
|
||||
**路径格式:**
|
||||
|
||||
- 使用操作系统临时目录（Unix 上为 `/tmp`，Windows 上为 `%TEMP%`）
|
||||
- 前缀: `lyxy-runner-js-`
|
||||
- 时间戳: 自纪元以来的毫秒数
|
||||
- 随机字符串: 7 字符字母数字
|
||||
- 扩展名: 参数中提供的值
|
||||
|
||||
**示例:**
|
||||
|
||||
```bash
|
||||
$ bun skills/lyxy-runner-js/scripts/get_temp_path.js js
|
||||
/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/lyxy-runner-js-1770257905333-na6ujx.js
|
||||
|
||||
$ bun skills/lyxy-runner-js/scripts/get_temp_path.js ts
|
||||
/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/lyxy-runner-js-1770257905333-v8yzt.ts
|
||||
```
|
||||
71
skills/lyxy-runner-js/references/error-handling.md
Normal file
71
skills/lyxy-runner-js/references/error-handling.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# 错误处理
|
||||
|
||||
## 未安装 Bun
|
||||
|
||||
**症状:** `bun --version` 失败或返回 "command not found: bun"
|
||||
|
||||
**错误处理：**
|
||||
|
||||
当检测到 Bun 未安装时，必须：
|
||||
|
||||
1. **停止执行** - 不进行任何后续操作
|
||||
2. **输出明确错误信息** - 清晰说明 "Bun 运行时未安装" 或类似提示
|
||||
3. **提供安装说明** - 参考下方安装命令
|
||||
|
||||
**安装 Bun：**
|
||||
|
||||
**macOS/Linux:**
|
||||
```bash
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```powershell
|
||||
powershell -c "irm bun.sh/install.ps1 | iex"
|
||||
```
|
||||
|
||||
**重要限制：**
|
||||
|
||||
- ❌ **禁止自动安装** - 不要尝试自动安装 Bun，由用户自行决定
|
||||
- ❌ **禁止使用其他工具** - 不要尝试使用 nodejs、npm、yarn、pnpm 等其他 JavaScript 运行时或包管理工具
|
||||
- ❌ **禁止格式转换** - 不要建议用户将脚本转换为其他运行时格式
|
||||
|
||||
**正确做法：**
|
||||
|
||||
- ✅ 仅输出错误信息和安装说明
|
||||
- ✅ 等待用户安装 Bun 后再继续
|
||||
- ✅ 保持使用 Bun 作为唯一运行时
|
||||
|
||||
## 脚本语法错误
|
||||
|
||||
Bun 提供详细的语法错误信息：
|
||||
|
||||
```bash
|
||||
$ bun "$TEMP_FILE"
|
||||
error: Unexpected token
|
||||
--> /var/folders/.../script.js:2:10
|
||||
|
|
||||
2 | const = 123;
|
||||
| ^
|
||||
```
|
||||
|
||||
错误信息包括：
|
||||
|
||||
- 文件路径和行号
|
||||
- 错误的确切位置
|
||||
- 问题描述
|
||||
|
||||
## 运行时错误
|
||||
|
||||
运行时错误包含完整的堆栈跟踪：
|
||||
|
||||
```bash
|
||||
$ bun "$TEMP_FILE"
|
||||
ReferenceError: foo is not defined
|
||||
at script.js:3:5
|
||||
at main (script.js:1:1)
|
||||
```
|
||||
|
||||
## 其他错误
|
||||
|
||||
其他任何形式的错误都原样输出。
|
||||
104
skills/lyxy-runner-js/references/examples.md
Normal file
104
skills/lyxy-runner-js/references/examples.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# 示例
|
||||
|
||||
## 场景1：执行已存在的脚本文件
|
||||
|
||||
```bash
|
||||
# 步骤 1: 检查 Bun 是否已安装
|
||||
bun --version
|
||||
|
||||
# 步骤 2: 直接执行已存在的脚本
|
||||
bun ./scripts/my-script.js
|
||||
|
||||
# 脚本的输出将自动显示
|
||||
```
|
||||
|
||||
**关键特点：**
|
||||
- ✅ **无需生成临时文件** - 直接执行用户提供的脚本
|
||||
- ✅ **保持脚本位置** - 脚本留在原位置，不会被移动或复制
|
||||
- ✅ **简洁快速** - 跳过文件生成步骤，直接执行
|
||||
|
||||
## 场景2：在指定路径创建并执行脚本
|
||||
|
||||
```bash
|
||||
# 步骤 1: 检查 Bun 是否已安装
|
||||
bun --version
|
||||
|
||||
# 步骤 2: 使用 Write 工具在指定路径创建脚本
|
||||
# (以下步骤由大模型使用 Write 工具完成)
|
||||
# write content to "./scripts/new-script.js"
|
||||
|
||||
const greeting = "Hello from custom path!";
|
||||
console.log(greeting);
|
||||
|
||||
# 步骤 3: 执行脚本
|
||||
bun ./scripts/new-script.js
|
||||
```
|
||||
|
||||
**关键特点：**
|
||||
- ✅ **自定义路径** - 脚本创建到用户指定的位置
|
||||
- ✅ **持久化存储** - 脚本文件保存在指定位置，不会被自动清理
|
||||
- ✅ **灵活控制** - 用户可以精确控制脚本位置和命名
|
||||
|
||||
## 场景3：使用临时路径执行（默认流程）
|
||||
|
||||
### 基础示例
|
||||
|
||||
```bash
|
||||
# 步骤 1: 检查 Bun 是否已安装
|
||||
bun --version
|
||||
|
||||
# 步骤 2: 生成临时文件路径
|
||||
TEMP_FILE=$(bun skills/lyxy-runner-js/scripts/get_temp_path.js js)
|
||||
|
||||
# 步骤 3: 将脚本内容写入临时文件
|
||||
cat <<EOF > "$TEMP_FILE"
|
||||
const greeting = "Hello from lyxy-runner-js!";
|
||||
console.log(greeting);
|
||||
EOF
|
||||
|
||||
# 步骤 4: 执行脚本
|
||||
bun "$TEMP_FILE"
|
||||
|
||||
# 步骤 5: 输出已在上面捕获
|
||||
# 临时文件将由系统自动清理
|
||||
```
|
||||
|
||||
### TypeScript 示例
|
||||
|
||||
```bash
|
||||
# 生成 TypeScript 临时文件
|
||||
TEMP_TS=$(bun skills/lyxy-runner-js/scripts/get_temp_path.js ts)
|
||||
|
||||
# 写入 TypeScript 脚本
|
||||
cat <<EOF > "$TEMP_TS"
|
||||
const message: string = 'TypeScript execution';
|
||||
console.log(message);
|
||||
EOF
|
||||
|
||||
# 执行 - Bun 会自动转译 TypeScript
|
||||
bun "$TEMP_TS"
|
||||
```
|
||||
|
||||
## 依赖管理示例
|
||||
|
||||
### 导入外部包
|
||||
|
||||
```javascript
|
||||
// ESM import（推荐）
|
||||
import axios from 'axios'
|
||||
import lodash from 'lodash'
|
||||
|
||||
// CommonJS import（也支持）
|
||||
const axios = require('axios')
|
||||
```
|
||||
|
||||
首次执行带有外部导入的脚本时，Bun 会：
|
||||
|
||||
1. 分析导入
|
||||
2. 从 npm 下载缺失的依赖
|
||||
3. 全局缓存到 `~/.bun/install/cache`
|
||||
4. 后续运行使用缓存版本
|
||||
|
||||
### 不需要 package.json
|
||||
|
||||
与 Node.js 不同，你无需创建 `package.json` 或单独运行 `bun install`。Bun 在运行时自动处理所有操作。
|
||||
@@ -38,55 +38,7 @@ description: Any task that requires Python processing should use this skill.
|
||||
- ✗ 需要命令行参数
|
||||
- ✗ 需要从stdin读取
|
||||
|
||||
## Automatic Dependency Parsing
|
||||
|
||||
分析import语句，提取外部包名，排除标准库。
|
||||
|
||||
### 标准库（排除）
|
||||
**核心**: os, sys, pathlib, shutil, json, csv, re, datetime, math
|
||||
**网络**: http.client, urllib, socket, io, logging
|
||||
**高级**: itertools, functools, typing, dataclasses, enum
|
||||
|
||||
### 解析规则
|
||||
1. 提取：`import pandas` → `pandas`, `from numpy import array` → `numpy`
|
||||
2. 排除标准库
|
||||
3. 去重
|
||||
|
||||
### 示例
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import json # 标准库，排除
|
||||
from pathlib import Path # 标准库，排除
|
||||
|
||||
# 结果: [pandas, numpy]
|
||||
```
|
||||
|
||||
## Smart Project Detection
|
||||
|
||||
### 检测命令
|
||||
```bash
|
||||
uv sync --dry-run
|
||||
```
|
||||
|
||||
### 判断逻辑
|
||||
- Exit code 0 → uv项目
|
||||
- 非零退出码 → 非uv项目
|
||||
- 失败 → 回退到非uv项目模式（使用`--with`），不阻塞执行
|
||||
|
||||
## Path Handling
|
||||
|
||||
### 三层逻辑
|
||||
1. **用户指定存储路径** → 写入指定路径
|
||||
2. **用户指定现有脚本** → 直接执行
|
||||
3. **未指定** → 临时文件
|
||||
|
||||
```bash
|
||||
# 临时文件获取
|
||||
temp_file_path=$(uv run ./scripts/get_temp_path.py)
|
||||
```
|
||||
|
||||
## Execution Commands
|
||||
## Quick Reference
|
||||
|
||||
| 场景 | 命令 |
|
||||
|------|------|
|
||||
@@ -94,154 +46,20 @@ temp_file_path=$(uv run ./scripts/get_temp_path.py)
|
||||
| 非uv+有依赖 | `uv run --with pkg1 --with pkg2 <script_path>` |
|
||||
| 非uv+无依赖 | `uv run <script_path>` |
|
||||
|
||||
**特点**:
|
||||
- uv项目：使用项目环境，无`--with`
|
||||
- 非uv有依赖：每个`--with`创建隔离环境
|
||||
- 非uv无依赖：使用标准Python环境
|
||||
|
||||
## Workflow
|
||||
|
||||
**步骤1**: 解析依赖（见"Automatic Dependency Parsing"）
|
||||
1. **解析依赖**：分析import语句，提取外部包名（排除标准库）
|
||||
2. **检测项目**：执行`uv sync --dry-run`判断是否为uv项目
|
||||
3. **确定路径**：用户指定路径 → 现有脚本 → 临时文件
|
||||
4. **构造命令**：根据项目类型和依赖构造执行命令
|
||||
5. **执行脚本**：运行并捕获输出
|
||||
|
||||
**步骤2**: 检测项目（见"Smart Project Detection"）
|
||||
## References
|
||||
|
||||
**步骤3**: 确定路径（见"Path Handling"）
|
||||
详细文档请参阅 `references/` 目录：
|
||||
|
||||
**步骤4**: 构造并执行命令（见"Execution Commands"）
|
||||
|
||||
执行命令并捕获输出。
|
||||
|
||||
## Error Handling
|
||||
|
||||
### uv未安装
|
||||
|
||||
**检测**: `uv`命令失败
|
||||
|
||||
**错误消息**:
|
||||
```
|
||||
uv not found
|
||||
|
||||
此skill依赖uv工具运行Python脚本。
|
||||
|
||||
请安装uv: https://docs.astral.sh/uv/getting-started/installation/
|
||||
|
||||
安装命令示例：
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh # Linux/macOS
|
||||
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows
|
||||
```
|
||||
|
||||
**重要提示**:
|
||||
- **立即停止任务**，等待用户安装uv后再继续
|
||||
- **不要尝试使用**：python, pip, poetry, venv, virtualenv等
|
||||
- **不要自动安装**uv
|
||||
- 用户安装uv完成后，可以重新执行任务
|
||||
|
||||
**操作**: 立即停止所有执行，等待用户安装uv
|
||||
|
||||
### 其他错误
|
||||
|
||||
| 场景 | 错误消息 | 操作 |
|
||||
|------|---------|------|
|
||||
| 项目检测失败 | 回退到非uv模式，使用`--with` | 警告后继续 |
|
||||
| 依赖解析不准确 | 依赖可能不完整<br>Traceback: [traceback] | 停止，保留脚本调试 |
|
||||
| 语法错误 | Python语法错误: [描述]<br>文件: <path><br>行号: <line> | 停止 |
|
||||
| 路径权限问题 | 无法写入: <path><br>建议: 使用临时文件模式 | 回退到临时文件 |
|
||||
|
||||
## Examples
|
||||
|
||||
### 示例1: 数据分析
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
|
||||
df = pd.read_csv('data.csv')
|
||||
print(f"形状: {df.shape}")
|
||||
print(df.describe())
|
||||
```
|
||||
**执行**: `uv run --with pandas --with numpy /tmp/script_xxx.py`
|
||||
|
||||
### 示例2: API交互
|
||||
```python
|
||||
import requests
|
||||
|
||||
resp = requests.get('https://api.github.com/repos/python/cpython')
|
||||
data = resp.json()
|
||||
print(f"仓库: {data['full_name']}, Stars: {data['stargazers_count']}")
|
||||
```
|
||||
**执行**: `uv run --with requests /tmp/script_xxx.py`
|
||||
|
||||
### 示例3: 文件操作
|
||||
```python
|
||||
import os
|
||||
import glob
|
||||
|
||||
for i, file in enumerate(glob.glob('*.txt')):
|
||||
os.rename(file, f"file_{i:03d}.txt")
|
||||
```
|
||||
**执行**: `uv run /tmp/script_xxx.py`（无依赖）
|
||||
|
||||
### 示例4: uv项目内执行
|
||||
```python
|
||||
import pandas as pd
|
||||
from my_project import helper
|
||||
|
||||
df = pd.read_csv('data.csv')
|
||||
result = helper.process(df)
|
||||
print(result)
|
||||
```
|
||||
**执行**: `uv run scripts/data_process.py`（使用项目环境）
|
||||
|
||||
### 示例5: 用户指定路径
|
||||
```python
|
||||
import requests
|
||||
|
||||
resp = requests.get('https://api.example.com/data')
|
||||
print(f"处理完成: {len(resp.json())} 条")
|
||||
```
|
||||
**执行**: `uv run --with requests scripts/api_analyzer.py`（写入指定路径）
|
||||
|
||||
## Notes
|
||||
|
||||
### 为什么使用uv？
|
||||
| 特性 | 优势 |
|
||||
| 文件 | 内容 |
|
||||
|------|------|
|
||||
| 环境隔离 | 不污染系统Python |
|
||||
| 自动依赖 | `--with`语法，无需pip install |
|
||||
| 快速启动 | 比venv快10-100倍 |
|
||||
| 项目集成 | 自动检测uv项目 |
|
||||
| 零配置 | 开箱即用，无需PEP 723 |
|
||||
|
||||
### 最佳实践
|
||||
1. **依赖解析**: 排除标准库；失败时检查遗漏依赖；复杂项目用uv项目模式
|
||||
2. **路径**: 用户指定优先；临时文件用于自主生成；跨平台由辅助脚本保证
|
||||
3. **错误**: 预期错误脚本内处理；意外错误立即停止；检测失败自动回退
|
||||
4. **清理**: 临时文件使用系统目录，自动清理，失败时手动删除
|
||||
|
||||
### 限制
|
||||
- ✗ 不支持命令行参数、stdin输入、持久化环境
|
||||
- ✗ 使用uv默认Python版本（项目可在pyproject.toml指定）
|
||||
- ✗ 依赖解析可能不完整（动态导入、条件导入可能遗漏）
|
||||
- ✗ 项目检测可能误判（网络问题导致回退）
|
||||
|
||||
### uv工具要求
|
||||
|
||||
- **uv是此skill的必需依赖，不可替代**
|
||||
- **不支持**: python, pip, poetry, venv, virtualenv
|
||||
- 如果检测到uv未安装，必须停止任务并引导用户安装
|
||||
- 不要尝试使用替代方案或自动安装uv
|
||||
|
||||
## Workflow Summary
|
||||
|
||||
**完整流程**:
|
||||
1. 解析import语句，提取外部包名（排除标准库）
|
||||
2. 执行`uv sync --dry-run`检测项目
|
||||
3. 确定脚本路径（用户指定/现有脚本/临时文件）
|
||||
4. 构造执行命令（根据项目类型和依赖）
|
||||
5. 执行并捕获输出
|
||||
|
||||
**关键特点**:
|
||||
- 自动依赖解析：分析import自动提取
|
||||
- 智能项目检测：自动识别uv项目
|
||||
- 灵活路径：支持指定/现有/临时三种模式
|
||||
- 跨平台：自动适配Windows/macOS/Linux
|
||||
- 环境隔离：独立虚拟环境
|
||||
| `references/examples.md` | 数据分析、API交互、文件操作等完整示例 |
|
||||
| `references/error-handling.md` | uv未安装、依赖解析失败等错误处理指南 |
|
||||
| `references/best-practices.md` | 依赖解析、路径处理、项目检测等最佳实践 |
|
||||
|
||||
86
skills/lyxy-runner-python/references/best-practices.md
Normal file
86
skills/lyxy-runner-python/references/best-practices.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# 最佳实践和注意事项
|
||||
|
||||
## 为什么使用uv？
|
||||
|
||||
| 特性 | 优势 |
|
||||
|------|------|
|
||||
| 环境隔离 | 不污染系统Python |
|
||||
| 自动依赖 | `--with`语法，无需pip install |
|
||||
| 快速启动 | 比venv快10-100倍 |
|
||||
| 项目集成 | 自动检测uv项目 |
|
||||
| 零配置 | 开箱即用，无需PEP 723 |
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **依赖解析**: 排除标准库；失败时检查遗漏依赖；复杂项目用uv项目模式
|
||||
2. **路径**: 用户指定优先；临时文件用于自主生成；跨平台由辅助脚本保证
|
||||
3. **错误**: 预期错误脚本内处理；意外错误立即停止；检测失败自动回退
|
||||
4. **清理**: 临时文件使用系统目录，自动清理，失败时手动删除
|
||||
|
||||
## 限制
|
||||
|
||||
- ✗ 不支持命令行参数、stdin输入、持久化环境
|
||||
- ✗ 使用uv默认Python版本（项目可在pyproject.toml指定）
|
||||
- ✗ 依赖解析可能不完整（动态导入、条件导入可能遗漏）
|
||||
- ✗ 项目检测可能误判（网络问题导致回退）
|
||||
|
||||
## uv工具要求
|
||||
|
||||
- **uv是此skill的必需依赖，不可替代**
|
||||
- **不支持**: python, pip, poetry, venv, virtualenv
|
||||
- 如果检测到uv未安装，必须停止任务并引导用户安装
|
||||
- 不要尝试使用替代方案或自动安装uv
|
||||
|
||||
## 自动依赖解析详细说明
|
||||
|
||||
分析import语句，提取外部包名，排除标准库。
|
||||
|
||||
### 标准库（排除）
|
||||
|
||||
**核心**: os, sys, pathlib, shutil, json, csv, re, datetime, math
|
||||
**网络**: http.client, urllib, socket, io, logging
|
||||
**高级**: itertools, functools, typing, dataclasses, enum
|
||||
|
||||
### 解析规则
|
||||
|
||||
1. 提取：`import pandas` → `pandas`, `from numpy import array` → `numpy`
|
||||
2. 排除标准库
|
||||
3. 去重
|
||||
|
||||
### 示例
|
||||
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
import json # 标准库，排除
|
||||
from pathlib import Path # 标准库，排除
|
||||
|
||||
# 结果: [pandas, numpy]
|
||||
```
|
||||
|
||||
## 智能项目检测
|
||||
|
||||
### 检测命令
|
||||
|
||||
```bash
|
||||
uv sync --dry-run
|
||||
```
|
||||
|
||||
### 判断逻辑
|
||||
|
||||
- Exit code 0 → uv项目
|
||||
- 非零退出码 → 非uv项目
|
||||
- 失败 → 回退到非uv项目模式（使用`--with`），不阻塞执行
|
||||
|
||||
## 路径处理
|
||||
|
||||
### 三层逻辑
|
||||
|
||||
1. **用户指定存储路径** → 写入指定路径
|
||||
2. **用户指定现有脚本** → 直接执行
|
||||
3. **未指定** → 临时文件
|
||||
|
||||
```bash
|
||||
# 临时文件获取
|
||||
temp_file_path=$(uv run ./scripts/get_temp_path.py)
|
||||
```
|
||||
35
skills/lyxy-runner-python/references/error-handling.md
Normal file
35
skills/lyxy-runner-python/references/error-handling.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# 错误处理
|
||||
|
||||
## uv未安装
|
||||
|
||||
**检测**: `uv`命令失败
|
||||
|
||||
**错误消息**:
|
||||
```
|
||||
uv not found
|
||||
|
||||
此skill依赖uv工具运行Python脚本。
|
||||
|
||||
请安装uv: https://docs.astral.sh/uv/getting-started/installation/
|
||||
|
||||
安装命令示例：
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh # Linux/macOS
|
||||
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows
|
||||
```
|
||||
|
||||
**重要提示**:
|
||||
- **立即停止任务**，等待用户安装uv后再继续
|
||||
- **不要尝试使用**：python, pip, poetry, venv, virtualenv等
|
||||
- **不要自动安装**uv
|
||||
- 用户安装uv完成后，可以重新执行任务
|
||||
|
||||
**操作**: 立即停止所有执行，等待用户安装uv
|
||||
|
||||
## 其他错误
|
||||
|
||||
| 场景 | 错误消息 | 操作 |
|
||||
|------|---------|------|
|
||||
| 项目检测失败 | 回退到非uv模式，使用`--with` | 警告后继续 |
|
||||
| 依赖解析不准确 | 依赖可能不完整<br>Traceback: [traceback] | 停止，保留脚本调试 |
|
||||
| 语法错误 | Python语法错误: [描述]<br>文件: <path><br>行号: <line> | 停止 |
|
||||
| 路径权限问题 | 无法写入: <path><br>建议: 使用临时文件模式 | 回退到临时文件 |
|
||||
62
skills/lyxy-runner-python/references/examples.md
Normal file
62
skills/lyxy-runner-python/references/examples.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# 示例
|
||||
|
||||
## 示例1: 数据分析
|
||||
|
||||
```python
|
||||
import pandas as pd
|
||||
import numpy as np
|
||||
|
||||
df = pd.read_csv('data.csv')
|
||||
print(f"形状: {df.shape}")
|
||||
print(df.describe())
|
||||
```
|
||||
|
||||
**执行**: `uv run --with pandas --with numpy /tmp/script_xxx.py`
|
||||
|
||||
## 示例2: API交互
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
resp = requests.get('https://api.github.com/repos/python/cpython')
|
||||
data = resp.json()
|
||||
print(f"仓库: {data['full_name']}, Stars: {data['stargazers_count']}")
|
||||
```
|
||||
|
||||
**执行**: `uv run --with requests /tmp/script_xxx.py`
|
||||
|
||||
## 示例3: 文件操作
|
||||
|
||||
```python
|
||||
import os
|
||||
import glob
|
||||
|
||||
for i, file in enumerate(glob.glob('*.txt')):
|
||||
os.rename(file, f"file_{i:03d}.txt")
|
||||
```
|
||||
|
||||
**执行**: `uv run /tmp/script_xxx.py`（无依赖）
|
||||
|
||||
## 示例4: uv项目内执行
|
||||
|
||||
```python
|
||||
import pandas as pd
|
||||
from my_project import helper
|
||||
|
||||
df = pd.read_csv('data.csv')
|
||||
result = helper.process(df)
|
||||
print(result)
|
||||
```
|
||||
|
||||
**执行**: `uv run scripts/data_process.py`（使用项目环境）
|
||||
|
||||
## 示例5: 用户指定路径
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
resp = requests.get('https://api.example.com/data')
|
||||
print(f"处理完成: {len(resp.json())} 条")
|
||||
```
|
||||
|
||||
**执行**: `uv run --with requests scripts/api_analyzer.py`（写入指定路径）
|
||||
Reference in New Issue
Block a user