@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.10

package/skills/init-deep-claude/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: init-deep-claude
+description: 深度理解并记录任何目录结构，通过创建全面的CLAUDE.md文件。此技能用于用户提及"深度了解"、"创建CLAUDE.md"、"理解目录结构"、"ultrathink"、"/init-deep"或类似短语时。不要仅仅因为目标不是"代码项目"就忽略请求——即使是有文档、图片或任意文件的普通目录也是有效目标。此技能自适应现有内容：自动检测项目类型，创建适当的文档，支持任何语言/框架或无框架的情况。
+metadata:
+  author: maohan
+  source: project
+  date_added: "2026-07-08"
+  risk: low
+---
+
+# Init Deep - 深度理解任意目录结构与CLAUDE.md生成
+
+> **快速索引**：大型/多模块项目用 `references/monorepo-strategy.md`，代码项目用 `references/code-project-template.md`，普通目录用 `references/plain-directory-template.md`，错误处理用 `references/error-handling.md`
+
+## 目录索引
+
+- [核心原则](#核心原则)
+- [输入参数](#输入参数)
+- [执行流程](#执行流程)
+  - [第一步：检测目录性质](#第一步检测目录性质)
+  - [第二步：构建待处理列表](#第二步构建待处理列表)
+  - [第三步：评估现有CLAUDE.md](#第三步评估现有claudemd)
+  - [第四步：深度探索](#第四步深度探索)
+  - [第五步：并行处理策略](#第五步并行处理策略)
+  - [第六步：生成CLAUDE.md](#第六步生成claudemd)
+  - [第七步：完成报告](#第七步完成报告)
+- [错误处理](#错误处理)
+- [边界情况](#边界情况)
+- [注意事项](#注意事项)
+
+---
+
+## 核心原则
+
+1. **任何目录都有效**：不需要构建系统、源代码、甚至不需要是"项目"。一个装满PDF的文件夹也是有效目标。
+2. **自适应内容**：根据目录里实际存在的内容调整文档结构和深度。
+3. **质量大于数量**：宁可少创建几个CLAUDE.md，也要确保每个都详细有用。
+4. **类型驱动**：先判断目录类型，再选择对应的处理策略和模板。
+
+---
+
+## 输入参数
+
+- `--max-depth <N>`: 可选，指定探索深度（默认3层）
+  - `max-depth=1`: 仅当前目录
+  - `max-depth=2`: 当前 + 直接子目录
+  - `max-depth=3+`: 完整探索（默认）
+- 无参数：使用默认值3
+
+**大型项目提示**：如果目录非常庞大（上百个子目录），建议先用 `--max-depth=2` 测试，避免一次处理过多。
+
+**用户指定路径时**：如果用户指定了具体路径（如 `/init-deep /some/path`），则以该路径为起点计算深度。
+
+### 用户意图识别优先级
+
+| 表述示例 | 推断意图 | 执行操作 |
+|----------|----------|----------|
+| "只看当前目录"、"当前目录"、"不递归" | max-depth=1 | **只创建当前目录的CLAUDE.md，不进子目录** |
+| "深度了解"、"详细分析"、无参数 | max-depth=3 | 完整探索（默认） |
+| `/init-deep --max-depth=2` | 明确参数 | 严格按参数执行 |
+
+> **⚠️ 重要警告**：max-depth=1 意味着**只处理当前目录**，绝对不能递归创建子目录的 CLAUDE.md。即使发现子目录很有价值，也要克制！用户明确说了只看当前目录。
+
+---
+
+## 执行流程
+
+### 第一步：检测目录性质
+
+**必须跳过以下目录**（在第一步就排除）：
+- `.git/`、`.svn/`、`.hg/`（即使在根目录也跳过）
+- `node_modules/`、`__pycache__/`、`.venv/`、`venv/`
+- `vendor/`、`target/`、`build/`、`dist/`、`out/`
+- `*.class`、`*.o`、`*.so`（编译产物）
+- 隐藏目录（以 `.` 开头）通常跳过，除非用户明确指定
+
+使用 `Glob` 或 `Bash ls` 快速感知目录结构，判断是：
+
+| 类型 | 特征 | 处理策略 |
+|------|------|----------|
+| **代码项目** | 有构建文件(pom.xml/package.json/go.mod等)或源码目录(src/cmd/lib等) | 使用 `references/code-project-template.md`，深度探索源码 |
+| **纯数据目录** | 无构建文件，有文档/数据/配置文件(.pdf/.xlsx/.csv/.json等) | 使用 `references/plain-directory-template.md`，直接分析文件 |
+| **混合项目** | 同时有代码和数据 | 按主要类型处理，可混合使用两种模板 |
+| **空目录/极少文件** | 跳过或仅创建浅层描述 | 创建简短CLAUDE.md |
+
+### 第二步：构建待处理列表
+
+1. 列出当前目录下的直接子目录
+2. 对每个子目录计算深度（当前目录=深度0，子目录=深度1，以此类推）
+3. 只保留 `深度 <= max-depth` 的目录
+4. 排除第一步中标记为跳过的目录
+
+### 第三步：评估现有CLAUDE.md
+
+对每个待处理目录：
+1. 检查是否存在 `CLAUDE.md`
+2. 如果存在，读取内容判断是否"足够详细"
+3. **足够详细的判断标准**：
+   - 有实质性内容（非模板填充）
+   - 包含的子目录/文件说明与实际相符
+   - 内容深度与目录复杂度匹配
+   - 建议最小行数：代码项目150行+，普通目录100行+
+
+### 第四步：深度探索
+
+**普通目录**（纯文件集合）：
+- 使用 `Glob` 列出关键文件
+- 分析文件类型分布
+- 识别命名规律和用途分类
+- **不需要Agent**，直接分析即可
+
+**代码项目**：
+- 用 `Explore` Agent深度探索
+- 阅读构建配置和关键源码
+- 理解模块架构
+
+```
+探索任务模板（用于代码项目）：
+
+目录路径：{full_path}
+目录名：{name}
+判断的类型：{detected_type}
+
+探索要求：
+1. 列出所有直接子目录和主要文件
+2. 识别目录的核心用途
+3. 如果是代码项目：
+   - 阅读构建配置（pom.xml/package.json/go.mod等）
+   - 识别关键源文件并阅读
+   - 理解模块功能和架构
+4. 总结该目录在整体中的角色
+
+输出：
+- 目录结构概览（关键节点，非全部递归）
+- 核心发现（功能/内容/用途）
+- 与其他目录的关系（如明显）
+```
+
+### 第五步：并行处理策略
+
+**核心原则**：独立分支可以并行，有依赖关系的必须串行。
+
+| 场景 | 并行策略 |
+|------|----------|
+| 普通目录 | 直接处理，不需要Agent，可并行多个 |
+| 深度1的代码项目目录 | 可并行（最多5个Agent） |
+| 深度2+的代码项目目录 | 等待深度1完成后，识别依赖关系再处理 |
+| 有父子关系的目录 | 不能并行，必须先父后子 |
+
+**大型项目（>20个子目录或>30个待创建CLAUDE.md）**：参见 `references/monorepo-strategy.md` 的分批处理策略。
+
+### 第六步：生成CLAUDE.md
+
+根据探索结果生成文档。**不要僵硬套用模板**——让内容自然适配实际发现：
+
+**自适应结构指南**：
+
+| 实际发现 | 文档重点 |
+|----------|----------|
+| 有构建文件 | 详细列出依赖、技术栈、模块关系 |
+| 有明确源码 | 分析类/函数结构，说明核心逻辑 |
+| 纯文件集合 | 说明文件类型分布、命名规律、用途分类 |
+| 有层次结构 | 说明层级关系、每层的作用 |
+| 有配置文件 | 列出配置项及其含义 |
+| 数据目录 | 说明数据格式、来源、更新频率 |
+
+**代码项目**：使用 `references/code-project-template.md` 作为结构指南（至少200-300行）
+**普通目录**：使用 `references/plain-directory-template.md` 作为结构指南
+
+**CLAUDE.md基本框架**（可增删）：
+
+```markdown
+# {目录名}
+
+## 概述
+（1-3句话说明这是什么）
+
+## 结构
+（目录树，重点标注关键节点）
+
+## 关键发现
+### {重要子目录/文件}
+说明其作用
+
+## 关系
+（与上下级目录的关联，如有）
+
+## 注意
+（特殊文件、格式、限制等）
+```
+
+### 第七步：完成报告
+
+**必须将报告保存为文件**，以便后续验证和查看：
+
+```markdown
+## 处理完成
+
+- 扫描目录：X个
+- 创建CLAUDE.md：Y个
+- 更新：Z个
+- 跳过：W个（已完整或被排除）
+
+排除的目录：.git, node_modules等
+
+## 失败/跳过汇总
+
+| 目录 | 原因 | 处理方式 |
+|------|------|----------|
+| /path/a | 权限不足 | 跳过 |
+| /path/b | 路径不存在 | 跳过并通知用户 |
+
+**重要**：如果有任何失败项，必须在报告中明确列出，不得隐瞒。
+```
+
+**保存位置**：在用户指定目录或当前目录下创建 `init-deep-report.md`（如果用户未指定输出位置，则保存到当前目录）。
+
+### 完成自检清单
+
+创建完所有 CLAUDE.md 后，逐项确认：
+
+- [ ] **深度检查**：本次处理的深度是否 = max-depth？有没有越界？
+- [ ] **数量检查**：创建的 CLAUDE.md 数量是否与预期一致？
+- [ ] **跳过检查**：.git、node_modules 等无意义目录是否被正确跳过？
+- [ ] **质量检查**：每个 CLAUDE.md 是否达到最低行数要求（代码项目150+，普通目录100+）？
+- [ ] **内容检查**：文档内容是否与实际目录结构相符？
+
+如果发现任何一项不符合，返回重做。
+
+---
+
+## 错误处理
+
+完整指南见 `references/error-handling.md`。核心原则：
+
+| 错误类型 | 处理方式 |
+|----------|----------|
+| 权限不足 | 跳过，记录为"跳过-权限不足" |
+| 目录不存在 | 验证路径，跳过并标注 |
+| 符号链接 | 跳过Skip列表目录，解析有效目标 |
+| 循环检测 | 立即停止该分支，记录并继续其他 |
+| 文件过大 | 只读前N行，标注"部分读取" |
+| 二进制文件 | 不读取内容，只记录存在性 |
+| 编码问题 | 尝试UTF-8/GBK/ISO-8859-1，失败标记"部分内容" |
+
+---
+
+## 边界情况
+
+| 情况 | 处理方式 |
+|------|----------|
+| 空目录 | 创建简短CLAUDE.md（概述+说明为空） |
+| 只有1-2个文件 | 简短描述，不强制长文档 |
+| 极深嵌套(>10层) | 只按max-depth处理，不强制全部 |
+| 无法读取(权限) | 记录为"跳过-权限不足" |
+| 混合大量不同类型 | 按主要类型处理，注明混合 |
+| **用户指定文件路径** | 提示用户应指定目录路径，文件本身不是目标 |
+| **用户指定不存在路径** | 记录为"跳过-路径不存在"，通知用户 |
+| **路径带尾斜杠** | 自动去除尾斜杠后处理 |
+
+---
+
+## 注意事项
+
+1. **跳过无意义目录**：.git、node_modules、__pycache__、target、build等不要深入
+2. **不要过度扫描**：不是列出每个文件，而是理解结构后选择性深入
+3. **自适应模板**：根据实际内容调整文档结构，不是机械套用
+4. **用户意图优先**：用户说"只看这个目录"就只看这个，不递归
+5. **增量友好**：已有CLAUDE.md且内容正确时不要重写
+6. **大型项目分批**：超过阈值时按 `references/monorepo-strategy.md` 的策略分批处理

package/skills/init-deep-claude/_meta.json

@@ -0,0 +1,14 @@
+{
+  "name": "init-deep-claude",
+  "version": "1.3.0",
+  "description": "深度理解并记录任何目录结构，通过创建全面的CLAUDE.md文件。支持代码项目和普通目录。",
+  "created_at": "2026-04-27",
+  "updated_at": "2026-04-28",
+  "author": "user",
+  "references": [
+    "code-project-template.md",
+    "plain-directory-template.md",
+    "monorepo-strategy.md",
+    "error-handling.md"
+  ]
+}

package/skills/init-deep-claude/evals/evals.json

@@ -0,0 +1,60 @@
+{
+  "skill_name": "init-deep",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "/init-deep --max-depth=2",
+      "expected_output": "为当前项目下2层深度内的所有模块创建或更新CLAUDE.md文件",
+      "files": [],
+      "expectations": [
+        "CLAUDE.md文件被创建在多个模块目录下（或正确复用已有详细文档）",
+        "每个CLAUDE.md包含模块概述、目录结构、核心组件说明",
+        "处理结果报告显示了处理的模块数量",
+        "跳过了node_modules、.git等无意义目录"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "深度了解当前工程代码，在每个module下都创建一个完整、详细的CLAUDE.md",
+      "expected_output": "为项目中所有模块创建详细的CLAUDE.md文档",
+      "files": [],
+      "expectations": [
+        "项目的核心/主要模块都有详细文档",
+        "CLAUDE.md内容详细，包含核心类方法和依赖配置"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "/init-deep",
+      "expected_output": "使用默认深度(3)深度理解工程代码并创建CLAUDE.md",
+      "files": [],
+      "expectations": [
+        "处理深度为3层内的所有模块",
+        "生成的CLAUDE.md内容详尽(代码项目200+行)",
+        "包含模块依赖关系和使用场景说明"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "深度了解这个目录:/tmp（假设/tmp下有多个子目录包含文档和图片）",
+      "expected_output": "为/tmp下的子目录创建适合非代码项目的CLAUDE.md",
+      "files": [],
+      "expectations": [
+        "识别为普通文件集合而非代码项目",
+        "生成的CLAUDE.md描述文件类型分布和用途",
+        "不会尝试查找pom.xml或package.json等构建文件"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "我想了解当前目录下有哪些内容，帮我创建CLAUDE.md",
+      "expected_output": "仅在当前目录创建CLAUDE.md，不递归子目录",
+      "files": [],
+      "expectations": [
+        "使用max-depth=1的逻辑",
+        "只创建当前目录的CLAUDE.md",
+        "不会递归创建子目录的CLAUDE.md"
+      ]
+    }
+  ]
+}

package/skills/init-deep-claude/references/code-project-template.md

@@ -0,0 +1,57 @@
+# 代码项目 CLAUDE.md 模板
+
+## 目的
+这份文档是为了让AI能够快速理解这个代码项目的结构、功能和技术栈。
+
+## 模板结构
+
+```markdown
+# {项目/模块名称}
+
+## 概述
+- 一句话说明项目功能
+- 主要技术栈和版本
+- 在整体架构中的位置
+
+## 项目结构
+（完整的目录树，标注关键文件类型）
+
+## 核心组件
+
+### {关键模块/包}
+- **职责**：...
+- **主要类/函数**：
+  - `ClassName.method()`: 功能描述
+  - `anotherMethod()`: 功能描述
+- **依赖关系**：...
+
+## 构建配置
+（关键依赖、版本信息）
+
+## 使用场景
+1. ...
+2. ...
+
+## 模块关系
+（用文字描述依赖关系，如：service → operator → plugin）
+
+## 特殊说明
+- 配置注意事项
+- 已知限制
+- 特殊架构决策及原因
+```
+
+## 质量标准
+
+| 指标 | 最低要求 | 推荐 |
+|------|----------|------|
+| 行数 | 150+ | 300+ |
+| 核心类覆盖 | 80% | 100% |
+| 依赖说明 | 有 | 完整 |
+
+## 识别特征
+
+代码项目通常包含以下特征：
+- 构建文件：pom.xml, package.json, go.mod, build.gradle, Cargo.toml
+- 源码目录：src/, lib/, cmd/, internal/, pkg/
+- 包管理：node_modules/, vendor/, .venv/

package/skills/init-deep-claude/references/error-handling.md

@@ -0,0 +1,118 @@
+# 错误处理与恢复指南
+
+## 常见错误及处理
+
+### 1. 权限不足
+
+**症状**：无法读取目录或文件
+
+**处理顺序**：
+1. 尝试只读访问
+2. 跳过该目录/文件
+3. 记录为"跳过-权限不足"
+4. 继续处理其他内容
+
+**替代方案**：
+- 如果是构建产物，尝试从其他位置获取信息
+- 如果是关键目录，通知用户
+
+### 2. 目录不存在/已删除
+
+**症状**：Glob 或 ls 找不到目录
+
+**处理**：
+1. 验证路径是否正确
+2. 检查是否已被其他进程删除
+3. 跳过，继续处理
+4. 在报告中标注
+
+### 3. 符号链接/快捷方式
+
+**症状**：发现指向其他位置的链接
+
+**处理**：
+1. 检测是否为符号链接（Unix）或快捷方式（Windows）
+2. 如果指向 Skip 列表中的目录（.git, node_modules），跳过
+3. 如果指向有效目标，尝试解析
+4. 如果无法解析，记录并跳过
+
+### 4. 死循环风险
+
+**症状**：目录结构形成循环引用
+
+**预防**：
+1. 维护已访问路径集合
+2. 检测深度是否超过 max-depth
+3. 检测是否有目录被多次访问
+
+**处理**：
+1. 发现循环时立即停止该分支
+2. 记录为"跳过-循环检测"
+3. 继续处理其他分支
+
+### 5. 文件过大
+
+**症状**：文件过大无法读取
+
+**处理**：
+1. 设置最大读取大小（如 10MB）
+2. 超过限制时只读取前 N 行
+3. 在 CLAUDE.md 中标注"部分读取"
+4. 记录原始文件大小
+
+### 6. 二进制文件
+
+**症状**：尝试读取二进制文件
+
+**处理**：
+1. 通过文件扩展名检测二进制（.exe, .dll, .so, .class）
+2. 二进制文件不读取内容
+3. 只记录文件存在和基本信息
+
+### 7. 编码问题
+
+**症状**：文本文件读取乱码
+
+**处理**：
+1. 尝试常见编码：UTF-8, GBK, ISO-8859-1
+2. 如果全部失败，标记为"部分内容"
+3. 不因为编码问题停止处理
+
+## 恢复机制
+
+### 检查点保存
+
+处理大型项目时，定期保存进度：
+```json
+{
+  "checkpoint": {
+    "processed": ["path1", "path2"],
+    "pending": ["path3", "path4"],
+    "failed": [{"path": "path5", "reason": "permission"}]
+  }
+}
+```
+
+### 增量恢复
+
+从检查点恢复：
+1. 读取检查点文件
+2. 跳过已处理的目录
+3. 从 pending 列表继续
+4. 清理检查点（完成后）
+
+## 错误报告格式
+
+```markdown
+## 错误报告
+
+### 处理失败
+| 目录/文件 | 错误类型 | 原因 | 处理方式 |
+|------------|----------|------|----------|
+| /path/a | 权限不足 | 只读文件系统 | 跳过 |
+| /path/b | 循环检测 | 符号链接循环 | 停止该分支 |
+
+### 部分成功
+- 某些内容可能不完整
+- 建议手动检查失败项
+```

package/skills/init-deep-claude/references/monorepo-strategy.md

@@ -0,0 +1,100 @@
+# 大型项目/多模块项目处理策略
+
+## 什么时候触发
+
+以下情况需要特殊处理：
+- 直接子目录数量 > 20
+- 预计需要创建 CLAUDE.md 的目录 > 30
+- 项目深度 > 5 层
+
+## 分批处理策略
+
+### 策略1：按深度分批
+
+```
+批次1：深度0-1（根目录 + 直接子目录）
+批次2：深度2-3
+批次3：深度4+
+```
+
+**优点**：层级清晰
+**缺点**：可能遗漏跨目录依赖
+
+### 策略2：按模块类型分批
+
+```
+批次1：核心模块（base, utils, service, core）
+批次2：业务模块
+批次3：插件/扩展
+```
+
+**优点**：符合项目结构
+**缺点**：需要识别模块类型
+
+### 策略3：按工作流分批
+
+```
+批次1：独立的基础设施（config, docs, scripts）
+批次2：核心业务逻辑
+批次3：外围扩展
+```
+
+**优点**：风险最小
+**缺点**：处理时间长
+
+## 并行处理规则
+
+### 什么可以并行
+- 深度1的独立目录
+- 没有依赖关系的并行模块
+- 不同子系统的组件
+
+### 什么不能并行
+- 有父子关系的目录
+- 有 import/依赖关系的模块
+- 共享配置的组件
+
+### 并行数量建议
+
+| 目录复杂度 | 最大并行数 | 说明 |
+|------------|-----------|------|
+| 简单（<10文件）| 8 | 直接分析即可 |
+| 中等（10-50文件）| 5 | 用Agent探索 |
+| 复杂（>50文件）| 3 | 深度探索 |
+| 巨型（>100文件）| 1 | 专用策略 |
+
+## 协调机制
+
+### 全局状态跟踪
+维护一个待处理目录列表：
+1. 先处理根目录
+2. 识别依赖关系
+3. 按依赖顺序处理
+4. 记录已处理目录
+
+### 避免重复
+- 记录已处理的绝对路径
+- 跳过已处理的目录
+- 避免循环引用
+
+## 超时处理
+
+| 目录规模 | 建议超时 | 降级策略 |
+|----------|----------|----------|
+| 小型（<10子目录）| 60s | 简略描述 |
+| 中型（10-50）| 180s | 核心组件优先 |
+| 大型（>50）| 300s | 分批处理 |
+| 巨型（>100）| 自定义 | 专用策略 |
+
+## 进度报告
+
+每批处理完成后报告：
+```markdown
+## 批次N处理完成
+
+- 本批处理：X个目录
+- 成功：Y个
+- 失败：Z个（列出原因）
+- 累计处理：W个
+- 预计剩余：V个
+```

package/skills/init-deep-claude/references/plain-directory-template.md

@@ -0,0 +1,62 @@
+# 普通目录 CLAUDE.md 模板
+
+## 目的
+这份文档是为了让AI能够快速理解这个目录的内容和用途。
+
+## 模板结构
+
+```markdown
+# {目录名称}
+
+## 概述
+- 一句话说明目录用途
+- 包含的内容类型（文档/数据/配置/资源等）
+- 在整体中的作用
+
+## 内容结构
+（目录树，标注文件类型）
+
+## 内容详解
+
+### {子目录/文件组}
+- **内容类型**：...
+- **主要文件**：...
+- **用途说明**：...
+
+### {按类型分类}
+| 类型 | 数量 | 示例 |
+|------|------|------|
+| 文档 | X | .pdf, .docx |
+| 数据 | X | .csv, .xlsx |
+| 配置 | X | .json, .yaml |
+| 图片 | X | .jpg, .png |
+
+## 使用场景
+1. ...
+2. ...
+
+## 数据格式（如适用）
+- 格式类型：...
+- 来源：...
+- 更新频率：...
+
+## 注意事项
+- 格式说明
+- 访问权限
+- 其他特殊说明
+```
+
+## 质量标准
+
+| 指标 | 最低要求 | 推荐 |
+|------|----------|------|
+| 行数 | 80+ | 150+ |
+| 类型覆盖 | 主要类型 | 全部类型 |
+| 用途说明 | 有 | 详细 |
+
+## 识别特征
+
+普通目录的特征：
+- 无构建文件
+- 有文档/数据/配置文件（.pdf, .xlsx, .csv, .json等）
+- 无明确的源码结构