openlist

Execute safe file operations via OpenList API with preview-apply workflow for browsing, moving, renaming, deleting, offline tasks, and audit logging.

Security Scan

The skill generally matches its stated OpenList file-management purpose, but there are several inconsistencies (registry metadata vs SKILL.md), and the runtime reads repository .env files (possible surprise access to unrelated secrets); review before use.

Purpose & Capability

The name/description and the included Python CLI implement browsing, move/rename/delete previews and apply, offline tasks, and audit logging against an OpenList HTTP API — this is coherent with the stated purpose. However the published registry metadata claims no required environment variables while SKILL.md (and the code) require OPENLIST_BASE_URL and OPENLIST_TOKEN. That metadata mismatch is unexpected and should be corrected/clarified.

Instruction Scope

SKILL.md instructs the agent to run the bundled Python script and to read configuration from environment variables and from .env files at the repository root and skill folder. The code loads repo_root()/.env and skills/openlist/.env automatically; that can expose unrelated repository secrets if present. Apart from that, instructions limit network calls to the OpenList endpoints and require a preview/apply workflow for state changes which is appropriate. The .env reading behavior is a scope creep risk and should be explicitly acknowledged by the user.

Install Mechanism

There is no install spec or external download. The skill is delivered with a Python script that will run in the agent environment. No remote install or URL-based code pull was observed, which lowers installation risk.

Credentials

Requiring OPENLIST_BASE_URL and OPENLIST_TOKEN is reasonable for a service client. But the registry metadata omits these requirements (declares none), creating an inconsistency. Additionally, the script will merge OS environment variables with .env files and therefore can read any env var present; automatic reading of repo .env files could surface unrelated secrets — this is disproportionate if users assume only the two OpenList variables will be accessed.

Persistence & Privilege

The skill is not always: true and not requesting elevated platform privileges. It writes an audit JSONL to ~/.codex/openlist/audit.jsonl (declared in docs) but does not appear to modify other skills or global agent configuration. Autonomous invocation is enabled by default on the platform, which is normal; no extra persistence flags are present.

What to consider before installing

This skill appears to implement the OpenList preview-then-apply workflow and uses OPENLIST_BASE_URL and OPENLIST_TOKEN — which is appropriate — but the registry metadata incorrectly lists no required env vars. Before installing: (1) verify the skill's source/trustworthiness (homepage unknown, owner ID only), (2) ensure OPENLIST_TOKEN you provide is scoped minimally (not a full admin token if not needed), (3) understand that the script will read .env at the repository root and skills/openlist/.env (remove or audit those files first to avoid leaking unrelated secrets), (4) review the full openlist.py source to confirm there are no unexpected network calls or telemetry, and (5) run the skill in an isolated environment or with a token that has only the necessary permissions. If the publisher can correct the registry metadata and explicitly document .env reading and audit contents/redaction behavior, that would reduce concern.

OpenList 自动化 Skill

本 Skill 用于让 AI Agent 通过 OpenList HTTP API 以可审计、可确认的方式执行常见操作：浏览路径、移动、重命名、单路径删除、创建离线任务，以及查询/取消任务。默认不支持覆盖写入、批量删除或其他高风险不可逆动作。

配置

必需环境变量：

• OPENLIST_BASE_URL：OpenList 根地址，例如 http://localhost:5244 或 https://example.com/openlist
• OPENLIST_TOKEN：OpenList Token 原文，请求头使用 Authorization: <token>，不要加 Bearer

可选环境变量：

• OPENLIST_TIMEOUT_SECONDS：默认 30
• OPENLIST_VERIFY_TLS：默认 true，自签名证书环境可设为 false
• OPENLIST_AUDIT_PATH：默认 ~/.codex/openlist/audit.jsonl

支持从仓库根 .env 或 skills/openlist/.env 读取配置；环境变量优先级更高。请不要把 .env 提交到仓库。

命令清单

脚本入口：python skills/openlist/scripts/openlist.py

只读命令：

• ping
• whoami
• fs-get --path <path>
• fs-list --path <dir> [--refresh]
• offline-tools
• task-info --task-type <move|offline_download> --tid <tid>
• task-list --task-type <move|offline_download> [--state undone|done]
• audit-show [--event-id <id>] [--plan-id <id>] [--tid <tid>]

变更命令：

• preview-move --src-path <path> --dst-dir <dir> [--conflict-policy fail|auto_rename|skip]
• preview-rename --path <path> --new-name <name> [--conflict-policy fail|auto_rename]
• preview-delete --path <path>
• preview-offline-create --url <url> [--url <url> ...] --dst-dir <dir> [--tool <tool>] [--delete-policy <policy>]
• apply --plan-file <file>
• task-cancel --task-type offline_download --tid <tid>

两步确认

所有会修改状态的操作都必须走两步：

1. 先执行 preview-* 生成 OperationPlan
2. 用户确认后，再对同一份 plan 执行 apply

典型流程：

python skills/openlist/scripts/openlist.py preview-move `
  --src-path "/from/report.pdf" `
  --dst-dir "/to/" `
  --json > move.plan.json

python skills/openlist/scripts/openlist.py apply --plan-file move.plan.json --json

preview-* --json 的 stdout 只输出单个 JSON 对象；apply --json 的 stdout 也只输出单个 JSON 对象。错误会保留在 stderr，方便 Agent 读取。

删除操作额外要求：

1. 只能先执行 preview-delete
2. Agent 必须向用户展示 规范化后的精确路径 与 对象类型（file/dir）
3. Agent 必须明确说明“删除不可逆”
4. 只有在用户明确确认后，才能对该 plan 执行 apply

Move / Rename 示例

移动文件：

python skills/openlist/scripts/openlist.py preview-move `
  --src-path "/from/report.pdf" `
  --dst-dir "/archive/" `
  --conflict-policy fail `
  --json > move.plan.json

python skills/openlist/scripts/openlist.py apply --plan-file move.plan.json --json

重命名文件：

python skills/openlist/scripts/openlist.py preview-rename `
  --path "/archive/report.pdf" `
  --new-name "report-2026.pdf" `
  --json > rename.plan.json

python skills/openlist/scripts/openlist.py apply --plan-file rename.plan.json --json

冲突策略说明：

• fail：默认策略。发现同名冲突时只生成带冲突信息的 plan，apply 会拒绝执行
• auto_rename：自动生成稳定的新名称，例如 report (1).pdf
• skip：仅 preview-move 支持。目标已存在时，最终执行会跳过该项

无变更检测：

• 如果源条目已经位于目标目录，preview-move 会标记为 no-op
• 如果新名称与当前名称一致，preview-rename 会标记为 no-op
• no-op plan 的 apply 会返回成功并写审计，不会调用写接口

删除示例

预览删除：

python skills/openlist/scripts/openlist.py preview-delete `
  --path "/archive/report.pdf" `
  --json > delete.plan.json

Agent 在执行 apply 前必须向用户明确展示：

• 规范化路径，例如 /archive/report.pdf
• 对象类型，例如 file 或 dir
• 删除不可逆，且该命令只允许删除单个显式路径

用户确认后执行：

python skills/openlist/scripts/openlist.py apply --plan-file delete.plan.json --json

删除执行前会再次在线校验：

• 路径仍然存在
• 当前对象类型与 preview 时一致

任一条件不满足时，apply 会拒绝执行并提示重新 preview-delete。

离线任务示例

先查看可用工具：

python skills/openlist/scripts/openlist.py offline-tools --json

预览创建任务：

python skills/openlist/scripts/openlist.py preview-offline-create `
  --url "https://example.com/file.iso" `
  --dst-dir "/downloads/" `
  --json > offline.plan.json

执行并查询：

python skills/openlist/scripts/openlist.py apply --plan-file offline.plan.json --json
python skills/openlist/scripts/openlist.py task-list --task-type offline_download --json
python skills/openlist/scripts/openlist.py task-info --task-type offline_download --tid "<tid>" --json
python skills/openlist/scripts/openlist.py task-cancel --task-type offline_download --tid "<tid>" --json

默认工具选择规则：

• 若实例启用了 SimpleHttp，优先选择 SimpleHttp
• 否则选择列表中的第一个工具
• 默认 delete_policy=delete_never

审计与回退指引

每一次 preview、apply、deny 和只读命令都会写入 JSONL 审计。默认位置：

~/.codex/openlist/audit.jsonl

审计记录包含：

• event_id
• timestamp
• phase
• request_id
• plan_id
• operation_type
• inputs
• outcome

敏感字段如 Authorization、token、password、secret 会被脱敏。

查询示例：

python skills/openlist/scripts/openlist.py audit-show --event-id "<event-id>" --json
python skills/openlist/scripts/openlist.py audit-show --plan-id "<plan-id>" --json
python skills/openlist/scripts/openlist.py audit-show --tid "<task-id>" --json

回退指引：

• move/rename 的 preview 和 apply 结果会给出反向操作建议
• offline task 会提示优先尝试 task-cancel
• delete 为不可逆操作，不提供回退指引

安全边界

• 不允许 overwrite=true
• 删除仅支持 /api/fs/remove 的单路径显式删除，不支持批量路径
• 不允许删除根目录 /
• apply 只允许执行白名单 endpoint：
  • /api/fs/move
  • /api/fs/rename
  • /api/fs/remove
  • /api/fs/add_offline_download
• 如果 plan 预检失败、仍有冲突或被手工篡改为危险字段，apply 会拒绝执行并写 deny 审计

常见排查

• 路径不存在：先执行 fs-get 或 fs-list
• 权限不足：确认 Token 是否具备对应目录或任务权限
• 同名冲突：重新 preview，并选择 auto_rename 或 skip
• 删除前对象发生变化：重新执行 preview-delete，再次确认路径与对象类型
• 看起来 HTTP 成功但结果仍失败：检查 JSON 中的 openlist_code 与 message
• 离线任务不可用：执行 offline-tools，确认实例已经启用下载工具
• TLS 失败或自签名证书：设置 OPENLIST_VERIFY_TLS=false