@pzy560117/codex-harness 0.1.2 → 0.1.4

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/github-research/SKILL.md

@@ -1,213 +0,0 @@
----
-name: github-research
-description: 系统化搜索、评估和深度分析 GitHub 仓库。全程使用 GitHub MCP 工具，无需安装 gh CLI。4 阶段流水线：搜索发现 → 评分筛选 → 深度分析 → 报告输出。
-argument-hint: [research-topic]
----
-
-# GitHub Research Skill（MCP 版）
-
-## 触发条件
-
-- "搜索 GitHub 上的 [主题] 项目"
-- "分析 [领域] 的开源实现"
-- "找 [算法/框架] 的 GitHub 仓库"
-- 使用 `/github-research <topic>` 斜杠命令
-
-## 概述
-
-通过 GitHub MCP 工具系统化地发现、评估和深度分析 GitHub 仓库，生成结构化分析报告。
-
-**无需任何外部工具** — 全程使用 `github-mcp-server` 提供的 MCP 工具 + Agent 自身分析能力。
-
-**输出**: 分析报告写入 `docs/<topic-slug>/` 目录。
-
----
-
-## 4 阶段流水线
-
-```
-Phase 1: 搜索发现  → 多关键词/多维度 GitHub 搜索，收集 30-100 个候选仓库
-Phase 2: 评分筛选  → 按公式评分排名，选出 Top 10-20
-Phase 3: 深度分析  → 通过 MCP 远程读取代码，逐仓库深度分析
-Phase 4: 报告输出  → 生成最终分析报告（对比矩阵 + 推荐方案）
-```
-
----
-
-## Phase 1: 搜索发现
-
-### 目标
-从多个角度搜索 GitHub，收集 30-100 个候选仓库。
-
-### 搜索策略矩阵
-
-针对用户给定的主题，按以下策略组合搜索：
-
-| 策略 | MCP 工具 | 查询示例 |
-|------|----------|----------|
-| 主题搜索 | `search_repositories` | `"auto research agent"` |
-| 关键词变体 | `search_repositories` | `"automated research LLM"` |
-| 技术栈过滤 | `search_repositories` | `"deep research" language:python` |
-| 代码搜索 | `search_code` | `"class ResearchAgent"` |
-| Awesome 列表 | `search_repositories` | `"awesome-research-agent"` |
-
-### 执行步骤
-
-1. **确定搜索关键词**：根据主题生成 3-5 组关键词（包含同义词/英文变体）
-2. **执行多轮搜索**：对每组关键词调用 `search_repositories`，按 `stars` 降序排列
-3. **代码搜索补充**：用 `search_code` 搜索特征性类名/函数名
-4. **去重合并**：按 `owner/name` 去重，合并搜索结果
-5. **初步记录**：将搜索结果记录为 Markdown 表格（名称、描述、Stars、语言、最后更新）
-
-### 检查点
-- 收集到 30-100 个不重复仓库
-- 搜索关键词和策略已记录
-
----
-
-## Phase 2: 评分筛选
-
-### 目标
-按评分公式排名，选出 Top 10-20 仓库进入深度分析。
-
-### 评分公式
-
-```
-composite_score = relevance × 0.4 + quality × 0.35 + activity × 0.25
-```
-
-**各维度计算方法**：
-
-| 维度 | 权重 | 计算规则 |
-|------|------|----------|
-| **relevance** (相关性) | 0.4 | Agent 根据描述/README 判断：0.9-1.0 直接相关，0.7-0.89 高度相关，0.5-0.69 部分相关，<0.5 弱相关 |
-| **quality** (质量) | 0.35 | `normalize(log(stars+1)×0.3 + log(forks+1)×0.2 + has_license×0.15 + not_archived×0.2 + has_description×0.15)` |
-| **activity** (活跃度) | 0.25 | 最近推送: <30天→0.9, 30-90天→0.7, 90-365天→0.4, >365天→0.1 |
-
-### 执行步骤
-
-1. **获取仓库详情**：对 Phase 1 中 Stars 排名前 40 的仓库，用 `get_file_contents` 读取 README 辅助判断相关性
-2. **评分排名**：计算每个仓库的 composite_score
-3. **选取 Top 10-20**：优先选择评分最高的仓库，同时确保类型多样性
-
-### 筛选输出格式
-
-```markdown
-| # | 仓库 | ⭐ Stars | 语言 | 相关性 | 质量 | 活跃度 | 综合分 |
-|---|------|---------|------|--------|------|--------|--------|
-| 1 | owner/name | 2959 | Python | 0.95 | 0.88 | 0.90 | 0.91 |
-```
-
-### 检查点
-- 评分表已生成
-- 选出 10-20 个仓库进入 Phase 3
-
----
-
-## Phase 3: 深度分析
-
-### 目标
-通过 MCP 远程读取仓库代码，对 Top 仓库进行深度技术分析。
-
-### 分析方法（无需克隆）
-
-使用以下 MCP 工具远程分析仓库：
-
-| 分析维度 | MCP 工具 | 操作 |
-|----------|----------|------|
-| 目录结构 | `get_file_contents(path="/")` | 获取根目录文件列表 |
-| README | `get_file_contents(path="README.md")` | 读取完整文档 |
-| 依赖项 | `get_file_contents(path="requirements.txt")` | 读取依赖文件 |
-| 核心代码 | `get_file_contents(path="src/...")` | 读取关键源文件 |
-| 配置文件 | `get_file_contents(path="config/...")` | 读取配置 |
-| 最近活动 | `list_commits(perPage=5)` | 查看最近提交 |
-
-### 每仓库分析模板
-
-```markdown
-## {owner/name}
-
-**概述**: {一句话描述}
-**Stars**: {N} | **语言**: {lang} | **许可证**: {license} | **最后活跃**: {date}
-
-### 架构
-- 入口: `{file}` → 核心模块: `{modules}`
-- 核心依赖: {key deps}
-
-### 关键特性
-- {feature 1}: 实现于 `{file}`
-- {feature 2}: ...
-
-### 代码质量
-- 文档: {差/一般/好/优秀}
-- 测试: {无/少量/中等/完善}
-- 代码风格: {评价}
-
-### 可复用性
-- 提取难度: {易/中/难}
-- 推荐组件: {可复用的部分}
-
-### 局限性
-- {limitation 1}
-```
-
-### 检查点
-- 每个 Top 仓库都有深度分析结果
-- 关键代码文件已实际阅读（不仅仅是 README）
-
----
-
-## Phase 4: 报告输出
-
-### 目标
-生成最终分析报告，包含对比矩阵和推荐方案。
-
-### 报告结构
-
-```markdown
-# {主题} GitHub 项目分析报告
-
-## 1. 研究概述
-- 搜索范围和方法
-- 发现的项目总数
-
-## 2. Top 项目排名
-- 评分表格（从 Phase 2）
-
-## 3. 深度分析
-- 每个 Top 项目的详细分析（从 Phase 3）
-
-## 4. 对比矩阵
-| 维度 | 项目A | 项目B | 项目C | ... |
-|------|-------|-------|-------|-----|
-
-## 5. 技术趋势
-- 常用技术栈
-- 架构模式
-- 发展方向
-
-## 6. 推荐方案
-- 最佳学习项目
-- 最佳生产级项目
-- 最佳创新项目
-
-## 7. 总结
-```
-
-### 输出位置
-- 报告文件: `docs/<topic-slug>/analysis_report.md`
-
-### 检查点
-- 最终报告已生成
-- 对比矩阵完整
-- 推荐方案明确
-
----
-
-## 质量规范
-
-1. **深度分析必须读代码** — 不能只看 README，必须通过 MCP 读取关键源文件
-2. **去重** — 按 `owner/name` 去重
-3. **增量保存** — 每阶段完成后立即写入文件
-4. **中文输出** — 报告使用中文撰写
-5. **评分透明** — 每个分数都有计算依据

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/glue-coding/SKILL.md

@@ -1,389 +0,0 @@
----
-name: Glue Coding
-description: 胶水编程开发方法 - 优先搜索 GitHub 完整项目并封装为接口，其次使用成熟库，快速实现功能。适用于开发新功能、集成第三方服务、构建 Bot/CLI/API 客户端等场景。当用户需要快速实现功能、集成多个库、或构建数据处理管道时使用此 skill。
----
-
-# 胶水编程 (Glue Coding)
-
-## 核心理念
-
-胶水编程是一种通过组合和连接现有成熟项目/库来快速实现功能的开发方法，而非从零开始编写实现。核心原则：
-
-- **优先搜索完整项目**：GitHub 上的完整项目已经组合好多个库、调优过、有最佳实践，比自己从零组装库更高效
-- **三级搜索策略**：GitHub 项目 → 成熟库 → 最小自定义实现
-- **最小化自定义代码**：胶水代码只做组合/调用/封装/适配
-- **禁止重复造轮子**：不复制依赖代码到项目中
-- **真实集成**：所有导入模块必须在运行期真实参与执行
-
-## 工作流程
-
-```
-需求明确 → 寻找轮子（三级搜索） → 理解接口 → 描述连接 → 验证运行
-```
-
----
-
-## 第一步：需求明确
-
-在开始寻找项目/库之前，必须明确：
-
-### 输出格式
-
-```markdown
-## 目标
-一句话描述要实现什么
-
-## 非目标
-明确不做什么
-
-## 输入
-- 数据来源
-- 数据格式
-
-## 输出
-- 期望结果
-- 输出格式
-```
-
----
-
-## 第二步：寻找轮子（三级搜索策略）
-
-### 搜索优先级
-
-```
-Level 1（最优先）: 搜索 GitHub 完整项目 → 找到能直接用的项目，封装为接口
-  ↓ 没有合适的完整项目
-Level 2: 搜索成熟库（pip/npm 包）→ 找到成熟库，封装 Adapter
-  ↓ 没有合适的库
-Level 3: 最小自定义实现（需提供调研证明）
-```
-
-> **核心思想**：别人封装好的完整项目，已经踩过坑、调过参、集成过多个库，比自己从零组装成熟库更可靠。
-
----
-
-### Level 1: GitHub 项目调研（最优先）
-
-#### 搜索策略
-
-使用 GitHub MCP 工具系统化搜索：
-
-| 策略 | MCP 工具 | 查询示例 |
-|------|----------|----------|
-| 主题搜索 | `search_repositories` | `"mahjong AI" stars:>100` |
-| 关键词变体 | `search_repositories` | `"tile recognition OCR"` |
-| 技术栈过滤 | `search_repositories` | `"mahjong bot" language:python` |
-| 代码搜索 | `search_code` | `"class MahjongEngine"` |
-| Awesome 列表 | `search_repositories` | `"awesome-mahjong"` |
-
-#### 执行步骤
-
-1. **生成搜索关键词**：根据需求生成 3-5 组关键词（含同义词、英文变体）
-2. **多轮搜索**：对每组关键词调用 `search_repositories`，按 `stars` 降序
-3. **代码搜索补充**：用 `search_code` 搜索特征性类名/函数名
-4. **评分筛选**：按以下公式排名
-
-```
-composite_score = relevance × 0.4 + quality × 0.35 + activity × 0.25
-```
-
-| 维度 | 权重 | 计算规则 |
-|------|------|----------|
-| **relevance** | 0.4 | 根据描述/README 判断相关性：0.9+ 直接相关，0.7-0.89 高度相关 |
-| **quality** | 0.35 | Stars、Forks、License、文档完整性的综合评分 |
-| **activity** | 0.25 | 最近推送 <30天→0.9, 30-90天→0.7, 90-365天→0.4 |
-
-5. **深度分析 Top 项目**：通过 MCP 远程读取代码（无需克隆）
-
-| 分析维度 | MCP 工具 | 操作 |
-|----------|----------|------|
-| 目录结构 | `get_file_contents(path="/")` | 获取根目录 |
-| README | `get_file_contents(path="README.md")` | 读取文档 |
-| 依赖项 | `get_file_contents(path="requirements.txt")` | 读取依赖 |
-| 核心代码 | `get_file_contents(path="src/...")` | 读取关键源文件 |
-| 最近活动 | `list_commits(perPage=5)` | 查看提交 |
-
-6. **封装友好度评估**（关键新增维度）：
-
-| 评估项 | 通过标准 |
-|--------|----------|
-| API 清晰度 | 有明确的入口函数/类，参数和返回值有类型标注 |
-| 依赖复杂度 | 依赖项 < 20 个，无系统级依赖冲突 |
-| 许可证兼容 | MIT/Apache/BSD 等宽松许可证 |
-| 可独立运行 | 可通过 pip install 或 git clone 直接使用 |
-| 文档完整性 | 有 README + API 文档或 examples |
-
-7. **选择最佳项目**：综合评分最高 + 封装友好度通过的项目
-
-#### Level 1 输出格式
-
-```markdown
-## GitHub 项目调研结果
-
-### 搜索关键词
-- [关键词1], [关键词2], ...
-
-### Top 项目排名
-| # | 仓库 | ⭐ Stars | 语言 | 综合分 | 封装友好度 |
-|---|------|---------|------|--------|-----------|
-| 1 | owner/name | 2959 | Python | 0.91 | ✅ 通过 |
-
-### 推荐项目
-**owner/project_name** — 推荐理由
-- 核心功能：...
-- 入口接口：`ClassName.method()`
-- 封装策略：...
-```
-
----
-
-### Level 2: 成熟库搜索
-
-仅当 Level 1 未找到合适项目时执行。
-
-#### 搜索策略
-
-1. 分析需求涉及的技术领域
-2. 推荐对应的 GitHub Topics 关键词
-3. 评估候选库的质量指标：
-   - Star 数量（>1000 优先）
-   - 最近更新时间（<6个月）
-   - Issue 活跃度
-   - 文档完整性
-   - 许可证兼容性
-
-#### 常用 Topics
-
-| 需求 | Topic |
-|:---|:---|
-| Telegram Bot | telegram-bot |
-| 数据分析 | data-analysis |
-| AI Agent | ai-agent |
-| CLI 工具 | cli |
-| Web 爬虫 | web-scraping |
-| API 客户端 | api-client |
-
----
-
-### Level 3: 最小自定义实现
-
-仅当 Level 1 和 Level 2 均无法满足需求时，才允许自定义实现。
-
-**必须提供调研证明**：
-- GitHub 搜索记录（关键词 + 结果数量）
-- 分析过的 Top 项目列表及不适用原因
-- 搜索过的库列表及不适用原因
-
----
-
-## 第三步：理解接口
-
-### 针对 GitHub 项目
-
-1. 通过 MCP 远程读取核心源文件
-2. 识别入口类/函数
-3. 梳理输入参数和输出格式
-4. 运行 examples 验证
-
-### 针对成熟库
-
-1. 阅读官方文档
-2. 让 AI 总结核心 API
-3. 明确输入和输出
-
-### 输出格式
-
-```markdown
-## 项目/库名称
-xxx
-
-## 来源
-GitHub 项目 / PyPI 库
-
-## 核心功能
-- 功能1：描述
-- 功能2：描述
-
-## 关键 API
-### API 1
-- 输入：参数类型和含义
-- 输出：返回值类型和含义
-- 示例：代码片段
-
-### API 2
-...
-```
-
----
-
-## 第四步：描述连接
-
-### 连接描述模板
-
-```markdown
-## 数据流
-A 的输出 → 转换逻辑 → B 的输入
-
-## 胶水代码职责
-1. 封装接口
-2. 统一输入输出格式
-3. 错误处理
-4. 日志记录
-```
-
-### 代码组织
-
-```
-project/
-├── libs/
-│   ├── external_projects/   # GitHub 项目（git submodule 或 pip install from git）
-│   │   ├── project_a/
-│   │   └── project_b/
-│   └── packages/            # pip/npm 包（通过 requirements.txt 管理）
-├── src/
-│   ├── glue/
-│   │   ├── project_adapters/  # 项目级适配器（封装 GitHub 项目）
-│   │   ├── adapters/          # 库级适配器（封装 pip/npm 包）
-│   │   └── connectors/        # 连接器（组合多个适配器）
-│   └── core/                  # 最小业务逻辑
-└── main.py
-```
-
----
-
-## 第五步：验证运行
-
-### 验证清单
-
-- [ ] 所有导入模块在运行期真实参与执行
-- [ ] 无"只导入不用"的伪集成
-- [ ] 无路径遮蔽或重名模块问题
-- [ ] 功能与预期一致
-- [ ] 错误处理正常
-- [ ] GitHub 项目的许可证已确认兼容
-
-### 调试流程
-
-```
-跑通 → 完成
-  ↓
-报错 → 复制完整错误 → 给 AI → 继续粘
-```
-
----
-
-## 约束检查清单
-
-### 开发前
-
-- [ ] 已完成 Level 1 GitHub 项目调研（记录搜索关键词和结果）
-- [ ] Level 1 无合适项目时，已完成 Level 2 库搜索
-- [ ] 确认选择的项目/库是生产级实现
-- [ ] 确认许可证兼容
-
-### 开发中
-
-- [ ] 未复制依赖库代码到项目
-- [ ] 未对依赖库进行功能裁剪
-- [ ] 未使用 Mock/Stub 替代真实实现
-- [ ] 胶水代码只做组合/调用/封装/适配
-
-### 开发后
-
-- [ ] 所有模块真实参与执行
-- [ ] 无未使用的导入
-- [ ] 功能完整性验证通过
-
----
-
-## 示例：将 GitHub 项目封装为 Adapter
-
-### 需求
-
-需要一个麻将牌识别模块
-
-### Level 1 调研结果
-
-搜索到 `github.com/example/mahjong-tile-detector`（⭐ 3200，Python，MIT 许可证），已集成 YOLOv8 + 数据增强 + 预训练模型。
-
-### 项目级 Adapter
-
-```python
-# src/glue/project_adapters/tile_detector_adapter.py
-
-"""
-麻将牌检测器适配器 - 封装 mahjong-tile-detector 项目
-
-来源: github.com/example/mahjong-tile-detector
-许可证: MIT
-版本: v2.1.0 (commit: abc1234)
-"""
-
-from mahjong_tile_detector import TileDetector, TileResult
-from src.core.models import Tile, DetectionResult
-from loguru import logger
-
-
-class TileDetectorAdapter:
-    """
-    封装 mahjong-tile-detector 项目，提供统一的牌检测接口
-
-    将第三方项目的 TileResult 转换为本项目的 Tile 数据模型
-    """
-
-    def __init__(self, model_path: str = "default"):
-        """
-        初始化检测器
-
-        Args:
-            model_path: 模型路径，"default" 使用项目自带预训练模型
-        """
-        self._detector = TileDetector(model=model_path)
-        logger.info(f"牌检测器初始化完成, model={model_path}")
-
-    def detect(self, screenshot: bytes) -> DetectionResult:
-        """
-        检测截图中的麻将牌
-
-        Args:
-            screenshot: PNG 格式的截图字节数据
-
-        Returns:
-            检测结果，包含牌列表和置信度
-        """
-        raw_results: list[TileResult] = self._detector.predict(screenshot)
-        tiles = [self._convert(r) for r in raw_results]
-        logger.debug(f"检测到 {len(tiles)} 张牌: {tiles}")
-        return DetectionResult(tiles=tiles, confidence=self._avg_conf(raw_results))
-
-    def _convert(self, result: TileResult) -> Tile:
-        """将第三方项目的 TileResult 转换为本项目的 Tile 模型"""
-        return Tile(suit=result.suit, rank=result.rank, position=result.bbox)
-
-    def _avg_conf(self, results: list[TileResult]) -> float:
-        """计算平均置信度"""
-        if not results:
-            return 0.0
-        return sum(r.confidence for r in results) / len(results)
-```
-
-### 对比效果
-
-| 维度 | 自己从零组装库 | 封装 GitHub 项目 |
-|------|--------------|----------------|
-| 代码量 | ~500 行 | ~50 行 Adapter |
-| 开发时间 | 1 周 | 2 小时 |
-| 可靠性 | 需自己调参 | 项目已调优 |
-| 预训练模型 | 需自己训练 | 项目自带 |
-
----
-
-## 最佳实践
-
-1. **项目优先于库**：完整的 GitHub 项目已经过实战验证，比组装原始库更可靠
-2. **深度分析再封装**：不要只看 Star 数，必须读核心代码确认质量
-3. **薄胶水层**：Adapter 只做接口转换，不加业务逻辑
-4. **记录来源**：每个 Adapter 头部注明 GitHub 项目地址、许可证、版本/commit
-5. **版本锁定**：对 GitHub 项目锁定到具体 commit hash 或 tag
-6. **验证真实性**：确保所有导入的模块都在实际执行中被调用