金大哥 - list-files Skill 详情

<list-files> <process>

流程强制约束（必须遵守）

Step 执行规则：Step 必须按 Step 1→Step 2 的顺序执行，不得跳过、合并或重排。Step 1禁止以预检查或准备执行为理由提前加载references/ 、scripts/、templates/及其他文件，提前执行检查依赖或构造命令，要跟随Step 1→Step 2中操作的要求进行相应执行相应加载和命令。
规则优先级：本 SKILL 的强制规则具有最高优先级；references/ 文件仅用于补充业务细节、参数说明和脚本用法，不得覆盖、弱化或绕过本 SKILL 的强制规则；当 references/ 默认行为与本 SKILL 强制规则冲突时，必须以本 SKILL 强制规则为准；不得以 reference 默认行为、经验判断或执行便利性为理由绕过本规则。
错误终止命中约定：<error> 用于流程未能按本 SKILL 要求完成的情况。只要当前流程命中 <error> 中定义的任一错误类型 E01 至 E09，必须立即停止当前流程，进入 <error>，并严格使用“错误输出卡片”模板作为唯一最终回复；不得在错误输出卡片前后追加分析、解释、建议、追问或自定义内容；不得继续调用工具、写入文件、补救、重试或执行后续步骤。

执行步骤

Step 1 - 参数收集与确认

准入条件：
- 无（流程起始步骤）
操作：
- 依据<input>章节的规范要求执行step1相关操作
- 加载 templates/skill-context.schema.json 获取上下文变量规范，完成参数收集、默认值应用与校验。
- 生成最终生效参数集。
- 当 confirmation_required=true 时，按 <input> 模板展示参数确认卡片。
质量门禁：
- 所有操作均已按顺序执行完成。
- 所有缺失的 required 字段均已向用户追问且在确认卡片中展示。
- 当 confirmation_required=false 时，仅在满足以下条件时才可进入 Step 2，否则必须停止并请求用户确认：
  - 必填参数完整，且 <input_dir> 为绝对目录路径；
  - 对 <input_dir> 执行目录存在性检查，且检查结果通过；
  - 操作不会改动文件/目录
产出：
- 最终生效参数集
- 参数确认卡片（仅当 confirmation_required=true 时）

Step 2 - 工具选择与执行

准入条件：
- Step 1 已按顺序完成全部操作，并已生成最终生效参数集、完成 confirmation_required 判断：
  - 当 confirmation_required=true 时，已展示参数确认卡片并取得用户明确确认；
  - 当 confirmation_required=false 时，已明确记录“无需确认，允许进入 Step 2。
操作
- 依据<tools>章节的规范要求执行step2相关操作
- 依据已解析的Reference文件路径读取对应文件
- 完整读取 <skill_root>/templates/list-files-output.json
- 根据所选 Reference 文件中的说明和最终生效参数集，确定待调用的脚本
- 根据所选 Reference 文件的可用性检查命令，验证待调用脚本和环境依赖
- 将最终生效参数集绑定至业务执行命令序列的对应参数，完成占位符替换后执行
- 依据<output>章节的规范要求输出内容输出卡片
质量门禁：
- Step 2操作均已按顺序执行完成
- 聊天展示内容输出卡片与生效参数集和业务脚本输出保持一致
- 输出渲染结果后，未继续调用任何工具读取、解析、补充、复核或重构结果文件，包括 read、Get-Content、jq、Python
产出：
- 内容输出卡片

</process> <input>

强制规则（必须遵守）:

参数定义依据：具体上下文变量定义见 templates/skill-context.schema.json。通过分析用户输入确定参数取值，required 参数必须完成收集与校验，若缺失则必须追问用户并在确认卡片中展示；optional 参数按 schema 默认值静默处理，无需追问或向用户逐一收集；针对于参数中的相对路径则需调用cwd命令转换为绝对路径，所有路径参数必须使用已解析的绝对路径并以双引号包裹；不得使用环境变量、~ 或其他路径简写形式。
skill_root 路径使用约定：<skill_root> 表示当前 Skill 根目录，必须根据当前已加载的 SKILL.md 文件位置确定。在 Step 1 中，<skill_root> 仅作为读取 <skill_root>/templates/skill-context.schema.json 的白名单路径占位符使用，不得单独解析、检查或输出。Step 2 准入条件满足后，才允许在 Step 2 首个需要使用 <skill_root> 的操作前，将其解析为真实存在的绝对路径；不得使用 ~/.openclaw/...、$HOME/...、%USERPROFILE%\... 等依赖 shell 展开的路径。
input_dir 提取约定：<input_dir> 只能由用户原始输入或用户确认内容中清晰标出的完整目录路径唯一提取而来；不得通过 cwd/pwd、当前工作目录、workspace路径、环境变量、历史记忆、目录枚举、相似目录搜索或模型猜测补全。无法唯一提取 <input_dir> 时，必须立即停止；不得继续读取 schema/Reference/模板等相关文件，不得执行路径拼接、路径规范化、路径检查或目录枚举；最终回复必须且只能输出：无法从输入中确定完整目录路径，请用双引号、代码块、单独一行或“路径：...”提供完整目录路径。
input_dir 路径检查约定：解析时仅允许对已明确形成的 <input_dir> 做路径格式规范化。Step 1 仅允许对已明确形成的 <input_dir> 做一次目录存在性检查；若检查结果为不存在、不是目录或返回 false，必须停止并请求用户确认正确目录路径，不得进入 Step 2，不得输出错误输出卡片，禁止检查父目录、兄弟目录、子目录或相似目录，禁止使用 Get-ChildItem、dir、ls、find 等命令排查路径，也不得以 confirmation_required=false 为由继续执行。

参数确认卡片如下：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 参数确认 ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 📂 最终输入预览

| Item | Value |
| --- | --- |
| Input Dir | [input_dir] |
| Operation | [operation] |
| Action | [action] |
| Recursive | [user_constraints.recursive；未提供则显示“未指定（由 Step 2 应用工具默认值）”] |
| Risk Level | [risk_assessment.level] |
| Confirmation Required | [confirmation_required] |

</input> <tools>

强制规则（必须遵守）:

工具范围及使用边界限制：工具执行必须遵循严格的工具调用边界。不得自由组合命令、不得绕过专用脚本、不得在状态未决时继续执行后续步骤。所有结论必须来自真实工具输出或已加载 references/ 文件中的明确说明，不得虚构未发生的工具调用、参数、返回值或文件清单。
- 情况1：禁止替代文件操作脚本：Agent 不得直接调用通用文件枚举能力绕过refrences脚本，包括但不限于：使用 os.listdir()、os.walk()、pathlib.iterdir() 自行遍历文件；使用任何 python -c 内联脚本枚举、搜索或统计文件；使用 dir、ls、find、Get-ChildItem 等枚举文件。以及通过 subprocess 间接调用上述命令。
- 情况2：禁止自写脚本替代结果处理脚本：结果校验与展示必须使用本 Skill 声明的 scripts/render-result.py，绝对禁止自写 JSON、CSV 等解析、校验或渲染脚本替代，包括但不限于使用 ConvertFrom-Json、临时 jq 表达式或其他通用命令解析输出。即使判断“自己写脚本更简单”，也必须使用本 Skill 的 scripts/render-result.py 处理业务结果，违反本条即视为执行失败。
Python 环境一致性约定：根据当前操作系统执行对应命令：Windows 执行 Write-Output "PYTHON=$env:PYTHON"；Linux/macOS 执行 printf 'PYTHON=%s\n' "$PYTHON"，将 <Python解释器> 解析为环境变量 PYTHON 指向的现有绝对文件路径。安装依赖、检查依赖和运行脚本时，必须始终使用该解释器，不得切换到其他 Python 环境，例如：<Python解释器> -m pip。如若 PYTHON 缺失、为空、不是绝对路径，或指向的解释器不存在，必须按 <error> 的 E04 处理。禁止退回使用裸 python、python3、pip 或 pip3。
检查类命令执行约定：路径检查、依赖检查、--help 可用性检查等检查类命令必须使用 background=false 前台执行。检查类命令必须设置 timeout=60000（60000 毫秒），禁止执行常驻命令，禁止交互式执行，必须使用非交互参数。<input_dir> 路径检查失败按 <input_dir> 路径检查约定处理；其他路径检查失败按 E02 处理；依赖或可用性检查失败按 E04 处理；检查命令超时按 E06 处理；违反检查边界按 E09 处理。
业务命令执行约定：业务执行命令序列必须使用 background=true 后台托管运行，不得使用 background=false 前台执行。
- 启动时设置 yieldMs=2000（2000 毫秒）、timeout=600000（600000 毫秒），并保存 sessionId；一次用户请求只能启动一个业务后台任务，后续 process 操作只能作用于该 sessionId。
- 启动后仅允许使用 process(action="poll") 轮询状态，每次 timeout=60000（60000 毫秒）。
- 仅在任务仍运行且需要查看过程输出时，允许使用 process(action="log") 增量读取日志，每次设置 limit=200 和递增 offset。
- 状态为 completed 时，只能根据任务返回的渲染结果决定下一步；若渲染结果不符合、疑似不符合或无法确认符合用户意图、operation、<output> 模板，必须立即按 E08 处理，禁止读取任何结果文件进行确认或补救。
- 状态为 failed、timeout、cancelled，或出现命令失败、渲染失败、缺失结果文件、等待交互、结果不可用等异常时，必须按 <error> 的对应错误类型处理。
- 禁止使用 submit，禁止启动第二条业务命令、提高 timeout、改写命令、替代执行或自行补救；仅异常时允许 kill 当前 sessionId。
业务脚本调用限制：业务脚本只能作为完整“业务执行命令序列”中的 <business_command> 执行一次。禁止单独预运行、调试或重复执行业务脚本。对结果结构或展示内容存在疑问时，仍须严格执行规定的完整命令序列；业务命令失败或结果不符合要求时按 E05/E08 处理，越界补救或重试按 E09 处理。
超时处理约定：前台执行返回 timed out 或超过规定时间上限时，必须按 <error> 的 E06 处理；禁止提高 timeout 重试、启动替代命令或继续执行后续步骤。
文件写入限制：除业务执行命令序列产生的文件外，大模型不得写入其他任何文件，除非用户明确要求。
业务执行命令序列执行约定：无法遵守业务执行命令序列拼接规则时，必须按 <error> 的 E09 处理。

选择与集成逻辑规则:

本 SKILL 领域知识封装在 references/ 文件中，仅在任务真正涉及该领域时才加载对应文件，避免无关规则污染上下文。根据最终生效参数集中的 operation 参数确定加载的 reference文件路径：

| operation参数 | Reference文件路径 | | ------------------------------------------------ | ------------------------------------ | | list / search / sort / count / analyze | references/local-file-organizer.md | | deduplicate | references/deduplicate-files.md | | 结果校验与展示 | references/render-result.md |

所选 reference 文件是对应业务操作、参数映射、条件参数和业务结果结构的唯一事实来源。
必须严格执行所选 reference 文件声明的操作与参数约束；不得自行补写、简化、替换或重新推导业务参数。
reference 文件缺失、读取失败、内容截断、未声明目标操作、缺少必要参数规则、能力不匹配或与本 SKILL 强制规则冲突时，必须按 <error> 的 E03 处理。

依赖检查命令与顺序：

依赖检查必须按下表顺序逐项执行。每项只能单独调用一次。当前依赖检查通过后，才允许检查下一项。依赖检查失败按 <error> 的 E04 处理；违反检查顺序、并行检查或串联检查命令按 <error> 的 E09 处理。

| 顺序 | 检查项 | 检查方式 | | ---- | ----------------------------------- | ------------------------------------------------------------ | | 1 | 所选 reference 声明的业务脚本可用性检查 | 按所选 reference 的“依赖项检查 / 可用性检查”说明执行 | | 2 | render-result.py | 执行 <Python解释器> scripts/render-result.py --help |

业务执行命令序列拼接规范：

Linux/macOS 环境命令序列拼接约定：Linux/macOS 必须使用以下命令序列。将 <business_command> 替换为所选 reference 指定的单一业务脚本调用，将 <render_output_path> 替换为最终展示文件的绝对路径；scripts/render-result.py 的 stdout 必须通过 tee 同时写入最终展示文件并输出至当前命令上下文。

set -uo pipefail; 
skill_root="<skill_root>"; 
result_path="<result_path>"; 
render_data_path="<render_data_path>"; 
validation_output_path="<validation_output_path>";
render_output_path="<render_output_path>";
python="<Python解释器>"; 
business_output="$({ <business_command>; } 2>&1)" || { code=$?; printf '%s\n' "$business_output" >&2; exit "$code"; };
test -f "$result_path" || { printf '%s\n' "Expected result JSON not generated: $result_path" >&2; exit 1; };
"$python" "$skill_root/scripts/render-result.py" --result-path "$result_path" --render-data-path "$render_data_path" --validation-output-path "$validation_output_path" --render-output-path "$render_output_path" | tee "$render_output_path" || { code=$?; printf '%s\n' "Failed to render result" >&2; exit "$code"; };
test -f "$render_output_path" || { printf '%s\n' "Expected rendered output not generated: $render_output_path" >&2; exit 1; }

Windows 环境命令序列拼接约定：Windows 环境必须使用以下命令拼接序列；<business_command> 必须替换为所选 reference 指定的单一业务脚本调用，<render_output_path> 必须替换为最终展示文件的绝对路径。scripts/render-result.py 的渲染结果必须先捕获到当前命令上下文，再使用 UTF-8 WriteAllText 写入最终展示文件并同步输出；不得使用 Tee-Object 或 cmd。

$ErrorActionPreference="Stop"; $skillRoot="<skill_root>"; $resultPath="<result_path>"; $renderDataPath="<render_data_path>"; $validationOutputPath="<validation_output_path>"; $renderOutputPath="<render_output_path>"; $python="<Python解释器>"; $business={ <business_command> }; $ErrorActionPreference="Continue"; $businessOutput=& $business 2>&1; $businessCode=$LASTEXITCODE; $ErrorActionPreference="Stop"; if($businessCode -ne 0){[Console]::Error.WriteLine(($businessOutput -join [Environment]::NewLine)); exit $businessCode}; if(-not (Test-Path -LiteralPath $resultPath -PathType Leaf)){[Console]::Error.WriteLine("Expected result JSON not generated: " + $resultPath); exit 1}; $renderScript=Join-Path $skillRoot "scripts/render-result.py"; if(-not (Test-Path -LiteralPath $renderScript -PathType Leaf)){[Console]::Error.WriteLine("Expected render script not found: " + $renderScript); exit 1}; $utf8=[Text.UTF8Encoding]::new($false); [Console]::OutputEncoding=$utf8; [Console]::InputEncoding=$utf8; $OutputEncoding=$utf8; $env:PYTHONIOENCODING="utf-8"; $env:PYTHONUTF8="1"; $ErrorActionPreference="Continue"; $rendered=& $python $renderScript --result-path $resultPath --render-data-path $renderDataPath --validation-output-path $validationOutputPath --render-output-path $renderOutputPath 2>&1; $renderCode=$LASTEXITCODE; $ErrorActionPreference="Stop"; $renderedText=$rendered -join [Environment]::NewLine; if($renderCode -ne 0){[Console]::Error.WriteLine($renderedText); exit $renderCode}; [Console]::Out.WriteLine($renderedText); if(-not (Test-Path -LiteralPath $renderOutputPath -PathType Leaf)){[Console]::Error.WriteLine("Expected rendered output not generated: " + $renderOutputPath); exit 1}; exit 0

</tools> <output>

强制规则（必须遵守）:

仅当业务命令序列和 scripts/render-result.py 均成功返回、当前命令上下文中存在可信渲染内容，且该渲染内容与用户意图、operation 和 <output> 模板一致时，才允许进入 <output>；否则必须按 <error> 的 E08 处理。进入 <output> 后，必须直接使用当前命令上下文中的渲染内容作为最终回复并立即结束 Step 2。
templates/list-files-output.json 定义任务结果的路由方式、通用校验规则、展示状态及通用输出参数；
{{ details }} 必须由 scripts/render-result.py 按 operation 渲染：文件清单类操作渲染文件列表，list-types 渲染类型数量/占比表，space-stats 和 type-space-stats 渲染空间占用聚合表，deduplicate 渲染重复文件组表。Agent 不得自行改写、补充或替代 {{ details }}。
结果展示规则如下，同时命中多条规则时，按照“结果不可验证 > 部分成功/警告 > 提示 > 正常”的优先级确定最终状态：
- 结果不为空且完整：展示任务信息、结果摘要和问题与提示；无问题时，问题与提示显示“无”。
- 结果为空：展示任务信息、结果摘要和问题与提示，并在结果摘要中显示“当前未检索到匹配文件”。当扫描范围、执行参数和原始结果均校验通过时，空结果不视为执行失败。
- 结果不为空但完整性无法确认：展示任务信息、结果摘要和问题与提示。本规则只适用于“结果有疑点但仍能由 scripts/render-result.py 正常渲染”的情况，例如：完整性字段缺失、分页或截断状态不明确、统计数据存在疑问、扫描范围说明不足、部分数据读取失败。若 JSON 无法解析、调用参数不一致、脚本异常退出、结果文件缺失或关键字段缺失，说明结果已不可信，必须按 <error> 处理。
- 结果不为空且仅存在展示类或说明类提示：正常展示任务信息和结果摘要，并在问题与提示中如实披露提示信息。展示类或说明类提示指不会改变结果数量、统计范围、匹配结论或结果可信度的信息，例如仅展示前 10 条、完整结果路径、排序方式说明等。
- 结果不为空但缺少部分内容：展示任务信息、当前可用的结果摘要和错误与跳过项，状态标记为“警告”或“部分成功”。权限错误、跳过项、损坏文件、路径过长、文件占用等问题，必须由 scripts/render-result.py 从本次业务结果中提取并渲染，说明缺失内容、影响范围和处理建议。仅当结果 JSON 可解析、调用参数一致、必要字段存在、缺失信息来自本次业务结果且渲染成功时，才允许按本规则展示；否则必须按 <error> 处理。
- 结果数量超过聊天展示上限：展示任务信息、结果摘要、结果明细和问题与提示。可展示条目数超过 10 条时，结果明细中仅展示前 10 条，问题与提示中说明“仅展示前 10 条，完整结果见：<result_path>”。该情况属于正常提示，不得标记为失败、警告或部分成功；不得为了展示更多结果重新执行命令、增大 --limit 或绕过渲染结果。

结果展示使用内容输出卡片：

--------------------------------------------------
# 执行结果 ✓
--------------------------------------------------

## 📁 任务信息

| Item | Value |
| --- | --- |
| Tool | {{ tool }} |
| Operation | {{ operation }} |
| Input Dir | {{ input_dir }} |
| Status | {{ status }} |

## 📊 结果摘要

{{ summary }}

## 📋 结果明细

{{ details }}

## ⚠️ 问题与提示

{{ issues }}

## 📄 完整结果

完整 JSON 结果已保存至："{{ result_path }}"

</output> <error>

强制规则（必须遵守）:

错误回复只能基于当前已获得的信息生成；未知项填写 unknown。禁止为补齐错误内容继续读取文件、调用工具、解析原始 JSON、读取 <render_output_path>、检查中间结果、重构展示或推断未发生的事实。
错误类型如下，同时命中多条规则时，按照“流程违规 > 渲染结果异常 > 业务执行错误 > 环境依赖错误 > Reference 选择错误 > 目标路径错误 > 输入参数错误 > 部分扫描异常 > 超时错误”的优先级确定最终错误类型：
- E01｜输入参数错误：未能读取 templates/skill-context.schema.json、无法形成最终生效参数集、参数校验失败、关键参数缺失或无法推导。
- E02｜目标路径错误：用于非 <input_dir> 目标路径不存在、不是目录、无法访问，或其他路径检查失败。
- E03｜Reference 选择错误：工具或 Reference 选择错误、Reference 文件缺失、能力不匹配，或所选 Reference 未声明业务脚本调用规则。
- E04｜环境依赖错误：环境或依赖缺失、依赖检查失败、Python 解释器缺失或无效、业务脚本不存在或不可执行。
- E05｜业务执行错误：业务脚本返回非零退出状态、原始结果文件未生成、结果文件不是本次执行新生成、结果文件无法读取、无法解析、关键字段缺失或与本次调用不一致。
- E06｜超时错误：工具调用返回 timed out、超过本 SKILL 规定的超时上限，或出现其他不可恢复的超时错误。
- E07｜部分扫描异常：权限不足、文件占用、符号链接循环、损坏文件或路径过长导致部分扫描失败，且异常导致结果无法可信展示、无法由 scripts/render-result.py 渲染为“警告/部分成功”，或可能影响统计结论但无法明确影响范围。若部分扫描异常已被 scripts/render-result.py 从本次业务结果中提取并可可信渲染，则按 <output> 规则 05 展示为“警告”或“部分成功”，不得进入本错误类型。
- E08｜渲染结果异常：scripts/render-result.py 不存在、无法读取、执行失败、渲染结果为空，或业务命令序列成功返回后，当前命令上下文中的渲染内容为空、格式异常、不完整，或与用户意图、operation 类型、<output> 模板要求不一致。禁止读取原始 JSON、<render_output_path> 或中间结果文件进行补救。
- E09｜流程违规：违反步骤准入、章节边界、依赖检查顺序、命令执行边界、结果读取边界，或在应停止时继续补救、重试、读取、验证、检查、解析、重构结果。

错误展示使用错误输出卡片：

--------------------------------------------------
# 执行失败 ✗
--------------------------------------------------

## ❌ 错误信息

| Item | Value |
| --- | --- |
| Error Code | {{ error_code }} |
| Error Type | {{ error_type }} |
| Step | {{ step }} |
| Status | failed |

## 📌 失败原因

{{ reason }}

## ⚠️ 影响范围

{{ impact }}

## 🔧 需要处理

{{ required_action }}

</error>

</list-files>