neo-skill 0.1.16 → 0.1.18

package/.github/README.md

@@ -0,0 +1,11 @@
+# .github
+
+本目录存放 GitHub 相关配置。
+
+## 包含内容
+
+- **workflows/**：GitHub Actions 工作流（CI/CD）。
+
+## 约定
+
+- 仅存放 GitHub 平台所需配置文件；与核心功能无关的文档不要放在此处。

package/.shared/README.md

@@ -0,0 +1,12 @@
+# .shared
+
+本目录存放跨技能复用的共享资源（shared assets），用于降低重复、保持各技能的一致性。
+
+## 包含内容
+
+- **skill-creator/**：skill-creator 的共享核心资源（数据索引与确定性脚本）。
+
+## 约定
+
+- 放在 `.shared/` 下的内容应尽量具备可复用性、稳定性与可维护性。
+- 避免放置一次性生成物或体积过大的文件（生成物应落在目标平台目录或 `dist/` 等输出目录）。

package/.shared/skill-creator/README.md

@@ -0,0 +1,13 @@
+# .shared/skill-creator
+
+本目录存放跨技能复用的 **skill-creator 核心资源**（会被 `omni-skill` 同步到使用方仓库）。
+
+## 包含内容
+
+- **data/**：结构化索引数据（CSV/JSON），供搜索与校验使用。
+- **scripts/**：确定性工具脚本（搜索、生成、校验、打包）。
+
+## 约定
+
+- 该目录是 `.shared/` 下的例外：需要纳入版本控制并保持稳定。
+- 不要在这里放一次性生成物或大体积文件。

package/.shared/skill-creator/data/README.md

@@ -0,0 +1,16 @@
+# .shared/skill-creator/data
+
+本目录存放 `skill-creator` 使用的结构化数据索引。
+
+## 文件类型
+
+- **domains.json**：定义 domain/stack 到数据文件的映射与描述。
+- **\*.csv**：各类模式库与规则库（workflow/output/trigger/resource/validation 等）。
+
+## 用途
+
+- 被 `.shared/skill-creator/scripts/search.py` 与 `validate.py` 等脚本读取。
+
+## 约定
+
+- 数据应保持字段稳定、可增量扩展；修改字段需同步更新脚本解析逻辑。

package/.shared/skill-creator/data_packs/README.md

@@ -0,0 +1,80 @@
+# Data Packs
+
+数据包目录，包含 skill-creator 的所有数据资源。
+
+## 目录结构
+
+```
+data_packs/
+├── universal/          # 必需数据包（不可删除）
+│   ├── questions.level1.json
+│   ├── schema.skill.json
+│   ├── output_packs/
+│   └── minimal_checklists/
+├── recipes/            # 可选：蓝图库
+├── tools/              # 可选：库推荐库
+├── domains/            # 可选：领域知识（待扩展）
+├── tasks/              # 可选：任务模式（待扩展）
+├── checklists_ext/     # 可选：扩展 checklist（待扩展）
+├── acceptance_templates/  # 可选：验收模板（待扩展）
+└── profiles/           # 可选：环境 profile（待扩展）
+```
+
+## 数据包说明
+
+### universal/（必需）
+核心数据包，包含：
+- **questions.level1.json**: Level 1 固定问题集（5-7问）
+- **schema.skill.json**: Skill 输出的 schema 定义
+- **output_packs/**: 5 个输出格式包（plain_text_message, markdown_report, json_result, code_snippet, generic）
+- **minimal_checklists/**: 3 个基本 checklist（automation_basic, web_scraping_basic, notification_basic）
+
+### recipes/（可选）
+成熟方案蓝图库，每个 recipe 包含：
+- workflow_steps: 步骤序列
+- recommended_libraries: 推荐库栈
+- config_keys: 配置键
+- acceptance_template: 验收模板
+
+### tools/（可选）
+第三方库推荐库，每个 tool 包含：
+- purpose: 用途说明
+- reason: 推荐理由
+- pypi_link + docs_link: 文档链接
+- minimal_usage_notes: 最小使用说明（10-20行）
+
+## 扩展方式
+
+### 添加新 Recipe
+1. 在 `recipes/` 下创建 `{recipe_id}.json`
+2. 更新 `recipes/index.json`
+3. 无需修改代码
+
+### 添加新 Tool
+1. 在 `tools/` 下创建 `{tool_id}.json`
+2. 更新 `tools/index.json`
+3. 无需修改代码
+
+## 索引文件格式
+
+所有 `index.json` 遵循统一格式：
+
+```json
+{
+  "version": "1.0",
+  "description": "...",
+  "items": {
+    "item_id": {
+      "file": "item_file.json",
+      "task_types": ["..."],
+      "tags": ["..."],
+      "keywords": ["..."]
+    }
+  }
+}
+```
+
+## 相关文档
+
+- [重构设计文档](../../../docs/skill-creator-refactoring/README.md)
+- [端到端演示](../../../docs/skill-creator-refactoring/END_TO_END_DEMO.md)

package/.shared/skill-creator/data_packs/recipes/README.md

@@ -0,0 +1,59 @@
+# Recipes（蓝图库）
+
+可选增强数据包，提供成熟方案骨架。
+
+## 当前 Recipes
+
+### rss_to_email
+抓取 RSS/Atom feed 并发送邮件通知的成熟方案。
+
+**适用场景**:
+- task_types: rss_monitoring, notification, scheduled_task
+- tags: rss, email_smtp, scheduler_local
+
+**包含内容**:
+- 4 步 workflow（fetch_feed → filter_new → format_email → send_email）
+- 推荐库栈（feedparser, smtplib, schedule）
+- 配置键（feed_url, email_to, smtp_server 等）
+- 验收模板（3条）
+- 假设和风险清单
+
+## Recipe 文件结构
+
+```json
+{
+  "id": "recipe_id",
+  "name": "Recipe Name",
+  "description": "...",
+  "task_types": ["..."],
+  "tags": ["..."],
+  "workflow_steps": [...],
+  "recommended_libraries": [...],
+  "config_keys": [...],
+  "acceptance_template": [...],
+  "assumptions": [...],
+  "risks": [...]
+}
+```
+
+## 添加新 Recipe
+
+1. 创建 `{recipe_id}.json` 文件
+2. 更新 `index.json`，添加索引条目：
+   ```json
+   {
+     "recipe_id": {
+       "file": "recipe_id.json",
+       "task_types": ["..."],
+       "tags": ["..."],
+       "keywords": ["..."]
+     }
+   }
+   ```
+3. 无需修改代码，系统会自动检索
+
+## 设计原则
+
+- **成熟验证**: 只添加经过验证的方案
+- **完整性**: 包含完整的 workflow + libraries + config
+- **可选性**: Recipe 缺失时安全降级为 generic recipe

package/.shared/skill-creator/data_packs/recipes/index.json

@@ -0,0 +1,18 @@
+{
+  "version": "1.0",
+  "description": "Recipe/Blueprint 索引（可选增强）",
+  "items": {
+    "rss_to_email": {
+      "file": "rss_to_email.json",
+      "task_types": ["rss_monitoring", "notification", "scheduled_task"],
+      "tags": ["rss", "email_smtp", "scheduler_local"],
+      "keywords": ["rss", "feed", "email", "notify", "daily"]
+    },
+    "web_scrape_report": {
+      "file": "web_scrape_report.json",
+      "task_types": ["web_scraping", "report_generation"],
+      "tags": ["http_fetch", "html_parse", "markdown", "report_gen"],
+      "keywords": ["scrape", "web", "report", "summary"]
+    }
+  }
+}

package/.shared/skill-creator/data_packs/recipes/rss_to_email.json

@@ -0,0 +1,114 @@
+{
+  "id": "rss_to_email",
+  "name": "RSS Feed to Email",
+  "description": "抓取 RSS/Atom feed 并发送邮件通知的成熟方案",
+  "task_types": ["rss_monitoring", "notification", "scheduled_task"],
+  "tags": ["rss", "email_smtp", "scheduler_local"],
+  "workflow_steps": [
+    {
+      "id": "fetch_feed",
+      "title": "抓取 RSS Feed",
+      "kind": "action",
+      "description": "使用 feedparser 解析 RSS/Atom feed",
+      "commands": [],
+      "notes": "处理网络超时、解析错误、空 feed 等情况"
+    },
+    {
+      "id": "filter_new",
+      "title": "过滤新条目",
+      "kind": "action",
+      "description": "与上次抓取结果对比，找出新条目",
+      "commands": [],
+      "notes": "需要持久化上次抓取的条目 ID 或时间戳"
+    },
+    {
+      "id": "format_email",
+      "title": "格式化邮件内容",
+      "kind": "action",
+      "description": "将新条目格式化为邮件正文",
+      "commands": [],
+      "notes": "包含标题、链接、摘要、发布时间"
+    },
+    {
+      "id": "send_email",
+      "title": "发送邮件",
+      "kind": "action",
+      "description": "通过 SMTP 发送邮件",
+      "commands": [],
+      "notes": "处理发送失败、凭证错误等情况"
+    }
+  ],
+  "recommended_libraries": [
+    {
+      "name": "feedparser",
+      "purpose": "解析 RSS/Atom feed",
+      "reason": "成熟稳定，支持多种 feed 格式",
+      "pypi_link": "https://pypi.org/project/feedparser/",
+      "docs_link": "https://feedparser.readthedocs.io/",
+      "fallback": "使用 requests + xml.etree.ElementTree 手动解析"
+    },
+    {
+      "name": "smtplib",
+      "purpose": "发送邮件",
+      "reason": "Python 内置库，无需额外依赖",
+      "pypi_link": "https://docs.python.org/3/library/smtplib.html",
+      "docs_link": "https://docs.python.org/3/library/smtplib.html",
+      "builtin": true
+    }
+  ],
+  "config_keys": [
+    {
+      "key": "feed_url",
+      "description": "RSS feed URL",
+      "required": true,
+      "example": "https://example.com/feed.xml"
+    },
+    {
+      "key": "email_to",
+      "description": "收件人邮箱",
+      "required": true,
+      "example": "user@example.com"
+    },
+    {
+      "key": "email_from",
+      "description": "发件人邮箱",
+      "required": true,
+      "example": "bot@example.com"
+    },
+    {
+      "key": "smtp_server",
+      "description": "SMTP 服务器地址",
+      "required": true,
+      "example": "smtp.gmail.com"
+    },
+    {
+      "key": "smtp_port",
+      "description": "SMTP 端口",
+      "required": false,
+      "default": "587"
+    },
+    {
+      "key": "state_file",
+      "description": "状态文件路径（记录已发送条目）",
+      "required": false,
+      "default": ".rss_state.json"
+    }
+  ],
+  "acceptance_template": [
+    "成功抓取 feed 并解析出条目",
+    "只发送新条目，不重复发送",
+    "feed 无新条目时不发送邮件",
+    "feed 抓取失败时记录错误但不崩溃",
+    "邮件发送失败时记录错误"
+  ],
+  "assumptions": [
+    "可以联网访问 RSS feed",
+    "有可用的 SMTP 服务器",
+    "可以在本地写入状态文件"
+  ],
+  "risks": [
+    "feed 格式变化可能导致解析失败",
+    "SMTP 凭证过期或被封禁",
+    "状态文件损坏导致重复发送"
+  ]
+}

package/.shared/skill-creator/data_packs/tools/README.md

@@ -0,0 +1,66 @@
+# Tools（库推荐库）
+
+可选增强数据包，提供第三方库推荐信息。
+
+## 当前 Tools
+
+### feedparser
+- **用途**: 解析 RSS/Atom feed
+- **理由**: 成熟稳定，支持多种 feed 格式
+- **链接**: [PyPI](https://pypi.org/project/feedparser/) | [Docs](https://feedparser.readthedocs.io/)
+
+### requests
+- **用途**: 发起 HTTP 请求
+- **理由**: Python 最流行的 HTTP 库，API 简洁
+- **链接**: [PyPI](https://pypi.org/project/requests/) | [Docs](https://requests.readthedocs.io/)
+
+### beautifulsoup4
+- **用途**: 解析 HTML/XML
+- **理由**: 最流行的 HTML 解析库，容错性强
+- **链接**: [PyPI](https://pypi.org/project/beautifulsoup4/) | [Docs](https://www.crummy.com/software/BeautifulSoup/bs4/doc/)
+
+### schedule
+- **用途**: 简单的任务调度
+- **理由**: 轻量级，API 简洁
+- **链接**: [PyPI](https://pypi.org/project/schedule/) | [Docs](https://schedule.readthedocs.io/)
+
+## Tool 文件结构
+
+```json
+{
+  "id": "tool_id",
+  "name": "tool_name",
+  "purpose": "用途说明",
+  "reason": "推荐理由",
+  "pypi_link": "https://pypi.org/project/...",
+  "docs_link": "https://...",
+  "github_link": "https://github.com/...",
+  "minimal_usage_notes": "简短使用说明（10-20行）",
+  "fallback": "零依赖/离线替代方案",
+  "tags": ["..."],
+  "stability": "high|medium|low",
+  "last_updated": "2023"
+}
+```
+
+## 添加新 Tool
+
+1. 创建 `{tool_id}.json` 文件
+2. 更新 `index.json`，添加索引条目：
+   ```json
+   {
+     "tool_id": {
+       "file": "tool_id.json",
+       "tags": ["..."],
+       "keywords": ["..."]
+     }
+   }
+   ```
+3. 无需修改代码，系统会自动检索
+
+## 设计原则
+
+- **链接优先**: 提供 PyPI + Docs 链接，不拉取 README
+- **微摘要**: minimal_usage_notes 控制在 10-20 行
+- **稳定性**: 优先推荐成熟稳定的库
+- **Fallback**: 提供零依赖/离线替代方案

package/.shared/skill-creator/data_packs/tools/beautifulsoup4.json

@@ -0,0 +1,14 @@
+{
+  "id": "beautifulsoup4",
+  "name": "beautifulsoup4",
+  "purpose": "解析 HTML/XML",
+  "reason": "最流行的 HTML 解析库，容错性强，API 简洁",
+  "pypi_link": "https://pypi.org/project/beautifulsoup4/",
+  "docs_link": "https://www.crummy.com/software/BeautifulSoup/bs4/doc/",
+  "github_link": "https://code.launchpad.net/beautifulsoup",
+  "minimal_usage_notes": "from bs4 import BeautifulSoup\nsoup = BeautifulSoup(html, 'html.parser')\ntitle = soup.find('h1').text\nlinks = [a['href'] for a in soup.find_all('a')]\n# 支持 CSS 选择器: soup.select('.class')\n# 容错性强，可处理不规范的 HTML",
+  "fallback": "使用 html.parser (Python 内置) 或 lxml",
+  "tags": ["html_parse"],
+  "stability": "high",
+  "last_updated": "2023"
+}

package/.shared/skill-creator/data_packs/tools/feedparser.json

@@ -0,0 +1,14 @@
+{
+  "id": "feedparser",
+  "name": "feedparser",
+  "purpose": "解析 RSS/Atom feed",
+  "reason": "成熟稳定，支持多种 feed 格式，自动处理编码和格式差异",
+  "pypi_link": "https://pypi.org/project/feedparser/",
+  "docs_link": "https://feedparser.readthedocs.io/",
+  "github_link": "https://github.com/kurtmckee/feedparser",
+  "minimal_usage_notes": "import feedparser\nfeed = feedparser.parse('http://example.com/feed.xml')\nfor entry in feed.entries:\n    print(entry.title, entry.link)\n# 自动处理编码、日期解析、多种 feed 格式\n# 返回统一的数据结构，无需关心 RSS vs Atom 差异",
+  "fallback": "使用 requests + xml.etree.ElementTree 手动解析 XML",
+  "tags": ["rss", "xml_parse"],
+  "stability": "high",
+  "last_updated": "2023"
+}

package/.shared/skill-creator/data_packs/tools/index.json

@@ -0,0 +1,26 @@
+{
+  "version": "1.0",
+  "description": "Tool Catalog 索引（库推荐库，可选增强）",
+  "items": {
+    "feedparser": {
+      "file": "feedparser.json",
+      "tags": ["rss", "xml_parse"],
+      "keywords": ["rss", "atom", "feed", "parse"]
+    },
+    "requests": {
+      "file": "requests.json",
+      "tags": ["http_fetch"],
+      "keywords": ["http", "request", "api", "fetch"]
+    },
+    "beautifulsoup4": {
+      "file": "beautifulsoup4.json",
+      "tags": ["html_parse"],
+      "keywords": ["html", "parse", "scrape", "beautifulsoup"]
+    },
+    "schedule": {
+      "file": "schedule.json",
+      "tags": ["scheduler_local"],
+      "keywords": ["schedule", "cron", "periodic", "task"]
+    }
+  }
+}

package/.shared/skill-creator/data_packs/tools/requests.json

@@ -0,0 +1,14 @@
+{
+  "id": "requests",
+  "name": "requests",
+  "purpose": "发起 HTTP 请求",
+  "reason": "Python 最流行的 HTTP 库，API 简洁，功能完善",
+  "pypi_link": "https://pypi.org/project/requests/",
+  "docs_link": "https://requests.readthedocs.io/",
+  "github_link": "https://github.com/psf/requests",
+  "minimal_usage_notes": "import requests\nresponse = requests.get('https://api.example.com', timeout=30)\nresponse.raise_for_status()  # 检查状态码\ndata = response.json()  # 或 response.text\n# 支持 headers, params, auth, proxies 等\n# 自动处理 cookies, redirects, encoding",
+  "fallback": "使用 urllib (Python 内置)，但 API 较复杂",
+  "tags": ["http_fetch"],
+  "stability": "high",
+  "last_updated": "2023"
+}

package/.shared/skill-creator/data_packs/tools/schedule.json

@@ -0,0 +1,14 @@
+{
+  "id": "schedule",
+  "name": "schedule",
+  "purpose": "简单的任务调度",
+  "reason": "轻量级，API 简洁，适合简单的定时任务",
+  "pypi_link": "https://pypi.org/project/schedule/",
+  "docs_link": "https://schedule.readthedocs.io/",
+  "github_link": "https://github.com/dbader/schedule",
+  "minimal_usage_notes": "import schedule\nimport time\ndef job():\n    print('Running task...')\nschedule.every().day.at('10:00').do(job)\nwhile True:\n    schedule.run_pending()\n    time.sleep(60)\n# 支持 every().hour, every().monday, every(10).minutes 等",
+  "fallback": "使用系统 cron (Linux/Mac) 或 Task Scheduler (Windows)",
+  "tags": ["scheduler_local"],
+  "stability": "high",
+  "last_updated": "2023"
+}

package/.shared/skill-creator/data_packs/universal/README.md

@@ -0,0 +1,52 @@
+# Universal Data Pack
+
+必需数据包（不可删除），包含 skill-creator 的核心资源。
+
+## 文件说明
+
+### questions.level1.json
+Level 1 固定问题集（5-7问），覆盖核心槽位：
+- goal: 目标
+- input: 输入来源
+- output: 输出形态
+- environment: 运行环境
+- constraints: 硬约束
+- acceptance: 验收用例
+
+### schema.skill.json
+Skill 输出的 schema 定义，用于校验：
+- required_fields: 必需字段
+- field_types: 字段类型
+- workflow_step_schema: workflow step 的 schema
+- validation_rules: 校验规则
+
+## 子目录
+
+### output_packs/
+输出格式包（5个，必需且不可禁用）：
+- **plain_text_message**: 纯文本消息（邮件/IM）
+- **markdown_report**: Markdown 报告
+- **json_result**: JSON 结果
+- **code_snippet**: 代码片段/脚本
+- **generic**: 通用格式（兜底）
+
+每个 pack 包含：
+- output_structure: 输出结构定义
+- workflow_pattern: 工作流模式
+- recommended_libraries: 推荐库
+- acceptance_template: 验收模板
+
+### minimal_checklists/
+最小 checklist（3个，必需）：
+- **automation_basic**: 自动化任务基本可靠性检查
+- **web_scraping_basic**: 网页抓取基本可靠性检查
+- **notification_basic**: 通知发送基本可靠性检查
+
+每个 checklist 包含：
+- rules: 规则列表（id, title, description, severity, example）
+
+## 设计原则
+
+1. **不可禁用**: universal 数据包是不变量，必须存在
+2. **安全降级**: 其他数据包缺失时，使用 universal 中的资源
+3. **可扩展**: 可以添加新的 output_packs 和 checklists

package/.shared/skill-creator/data_packs/universal/minimal_checklists/automation_basic.json

@@ -0,0 +1,42 @@
+{
+  "id": "automation_basic",
+  "name": "Automation Basic Checklist",
+  "description": "自动化任务的基本可靠性检查（必需）",
+  "rules": [
+    {
+      "id": "timeout",
+      "title": "设置超时",
+      "description": "所有网络请求和长时间操作必须设置超时",
+      "severity": "error",
+      "example": "requests.get(url, timeout=30)"
+    },
+    {
+      "id": "retry",
+      "title": "实现重试机制",
+      "description": "对于可能失败的操作（网络请求、文件读写），实现重试机制",
+      "severity": "warning",
+      "example": "使用 tenacity 或手动实现 retry 逻辑"
+    },
+    {
+      "id": "error_handling",
+      "title": "错误处理",
+      "description": "所有关键操作必须有 try-except，并记录错误",
+      "severity": "error",
+      "example": "try: ... except Exception as e: logger.error(f'Failed: {e}')"
+    },
+    {
+      "id": "logging",
+      "title": "日志记录",
+      "description": "记录关键步骤和错误，便于调试",
+      "severity": "warning",
+      "example": "import logging; logger = logging.getLogger(__name__)"
+    },
+    {
+      "id": "graceful_degradation",
+      "title": "优雅降级",
+      "description": "无数据或失败时，不应崩溃，而是返回空结果或默认值",
+      "severity": "error",
+      "example": "if not data: return default_value"
+    }
+  ]
+}

package/.shared/skill-creator/data_packs/universal/minimal_checklists/index.json

@@ -0,0 +1,24 @@
+{
+  "version": "1.0",
+  "description": "最小 Checklist 索引（必需，不可禁用）",
+  "items": {
+    "automation_basic": {
+      "file": "automation_basic.json",
+      "task_types": ["automation", "scheduled_task", "monitoring"],
+      "tags": ["automation", "scheduler_local"],
+      "keywords": ["automation", "workflow", "task"]
+    },
+    "web_scraping_basic": {
+      "file": "web_scraping_basic.json",
+      "task_types": ["web_scraping", "rss_monitoring"],
+      "tags": ["http_fetch", "html_parse", "rss"],
+      "keywords": ["web", "scrape", "fetch", "rss"]
+    },
+    "notification_basic": {
+      "file": "notification_basic.json",
+      "task_types": ["notification"],
+      "tags": ["email_smtp"],
+      "keywords": ["email", "notify", "alert"]
+    }
+  }
+}

package/.shared/skill-creator/data_packs/universal/minimal_checklists/notification_basic.json

@@ -0,0 +1,35 @@
+{
+  "id": "notification_basic",
+  "name": "Notification Basic Checklist",
+  "description": "通知发送的基本可靠性检查",
+  "rules": [
+    {
+      "id": "credentials",
+      "title": "凭证安全",
+      "description": "不要硬编码邮箱密码，使用环境变量或配置文件",
+      "severity": "error",
+      "example": "password = os.getenv('EMAIL_PASSWORD')"
+    },
+    {
+      "id": "send_failure",
+      "title": "发送失败处理",
+      "description": "邮件发送失败时记录错误，不应导致整个流程崩溃",
+      "severity": "error",
+      "example": "try: send_email() except SMTPException as e: logger.error(e)"
+    },
+    {
+      "id": "empty_message",
+      "title": "空消息处理",
+      "description": "无数据时，决定是发送空消息还是跳过",
+      "severity": "warning",
+      "example": "if not message_body: return  # 或发送占位符"
+    },
+    {
+      "id": "recipient_validation",
+      "title": "收件人验证",
+      "description": "验证收件人邮箱格式",
+      "severity": "warning",
+      "example": "使用正则或 email-validator 库"
+    }
+  ]
+}