项目概览与架构

一、项目定位与目标

filecoin-pin 是一个将数据存储到 Filecoin Onchain Cloud 的参考实现与工具集。它通过封装底层的 Synapse SDK，为开发者提供一致、简单且可复用的接口，将文件以 IPFS 内容寻址方式上传至 Filecoin 网络并生成可检索的 CID。

项目的核心定位包括三方面（资料来源：README.md:1-15）：

1. 多种用户交互形式：CLI 命令行工具、JavaScript 库、可复用的 GitHub Action，以及一个处于 Beta 阶段的 IPFS Pinning Server（filecoin-pin server）。
2. 共享核心库：所有交互层复用 filecoin-pin/core/* 模块，确保行为一致。
3. 遥测与可观测性：内置遥测默认开启，但始终支持用户禁用（README 明确说明 "Telemetry always has a way to be disabled"）。

📦 安装方式：npm install --save filecoin-pin（资料来源：README.md:10-15）

二、整体系统架构

项目在用户交互层与 Filecoin Onchain Cloud 智能合约、存储提供者（SP）之间建立了一个清晰的分层。CLI、GitHub Action 与 JS 库均通过共享的 core/ 模块调用 Synapse SDK，再由 SDK 与 PDP 服务、WarmStorage 合约以及 Filecoin Pay 合约交互。

flowchart TB
    subgraph 用户层["User-facing Affordances"]
        CLI["filecoin-pin CLI"]
        LIB["filecoin-pin (JS Library)"]
        ACT["upload-action (GitHub Action)"]
        SVR["filecoin-pin server (IPFS Pinning API)"]
    end

    subgraph 核心层["Shared Core Library (src/core)"]
        SYNAPSE["core/synapse"]
        UPLOAD["core/upload"]
        DATA["core/data-set"]
        PAY["core/payments"]
        CAR["core/car"]
        UTIL["core/utils"]
    end

    subgraph 外部["Filecoin Onchain Cloud"]
        SDK["@filoz/synapse-sdk"]
        WS["WarmStorage 合约"]
        FP["Filecoin Pay 合约"]
        SP["存储提供者 (PDP)"]
    end

    CLI --> SYNAPSE
    LIB --> SYNAPSE
    ACT --> UPLOAD
    SVR --> SYNAPSE

    SYNAPSE --> SDK
    UPLOAD --> SDK
    DATA --> SDK
    PAY --> SDK
    CAR --> UPLOAD
    UTIL --> PAY

    SDK --> WS
    SDK --> FP
    SDK --> SP

资料来源：README.md:55-80、src/core/payments/README.md:1-25

三、核心模块组成

src/core/ 是所有用户交互层共享的业务逻辑入口。下表列出主要子模块及其职责。

支付层定义了一组关键常量，如 MIN_FIL_FOR_GAS、DEFAULT_LOCKUP_DAYS、USDFC_DECIMALS 等，统一集中于 src/core/payments/constants.ts:1-30，便于在 CLI、库与 Action 中保持一致行为。

四、CLI 与 GitHub Action 用户层

4.1 CLI 命令行

filecoin-pin CLI 提供多种命令组，覆盖上传、检索、支付、数据集管理与服务器模式。社区近期关注点包括：

• 命令分组与快速入门（#576）：建议重排 --help 输出，将 add、import 提前，并提示 payments 需在首次上传前完成。
• data-set list 紧凑视图（#578）：v1.1.0 中已实现紧凑摘要输出，详细数据通过 data-set show <id> 获取。
• --dry-run 预估算（#591）：用户希望在真正上传前获得 packed size 与费用估算。
• 检索闭环（#575）：提议新增 filecoin-pin get 命令，从 SP 拉回存储内容。

4.2 GitHub Action（upload-action）

upload-action/ 是一个独立的 GitHub Action，使用语义化版本标签发布（@v0、@v0.9.1 等）。它接收 PR 上下文、构建产物（CAR），并通过 core/upload 完成上传（资料来源：upload-action/README.md:1-60、upload-action/src/types.ts:1-80）。

关键安全约束包括：

• 拒绝 fork PR 的上传事件，防止非维护者 PR 触发钱包操作。
• 强制硬编码 minRunwayDays 和 maxBalance，禁止在不可信工作流中放宽。
• 使用 GitHub Environments 进行人工审批，规避资金滥用风险。
• 对 pull_request_target 触发器与 workflow_run 的产物进行来源校验（资料来源：upload-action/README.md:30-80）。

五、社区与近期发展

v1.1.0（2026-06-25）主要变更（资料来源：GitHub Releases v1.1.0）：

• ✅ data-set list 紧凑摘要输出
• ✅ 重排 CLI --help 分组与快速入门示例
• ✅ 升级 synapse-sdk 到 v1.0.1、synapse-core 到 v0.7.0（含 BREAKING CHANGES）

社区持续讨论的开放议题：

• #527：将 upload-action 提取为独立仓库以实现独立版本管理。
• #589：调研 1Password / LastPass / Bitwarden 等私密保险库对私钥的集成。
• #306：跟进 IPIP-499 提案的 unixfs-v1-2025 现代 CID 配置，评估目录包裹与隐藏文件策略。
• #464：将 --egress-provider beam 作为 add/import 的默认行为。
• #581：确认 data-set terminate 中 skipProvider: true 是否仍是正确默认。

See Also

• Behind the Scenes of Adding a File — 深入解析 add 流程的底层细节。
• Filecoin Pin Glossary — 统一术语表（Synapse、PDP、FWSS 等）。
• Content Routing FAQ — IPNI 缓存、Provider 管理与索引器常见问题。
• Retrieving Your Data — 从 SP、信任网关或 IPFS CID 检索数据的方法。
• Progress Events — 库级 onProgress 事件类型约定。
• DEVELOPMENT.md — 本地开发、脚本、HTTP 追踪与未发布 Synapse SDK 的工作流。

概述与设计目标

filecoin-pin 是一个面向 Filecoin Onchain Cloud 的"即插即用"工具集，CLI 是其主要交互形式之一。CLI 以 Commander.js 框架为基础构建，按"命令组（command groups）+ 共享选项（shared options）+ 全局标志（global flags）"的模式组织：每个命令暴露统一的身份认证、网络与 RPC、Provider / DataSet 选择与元数据选项，确保 CLI、GitHub Action 与 JavaScript 库三者行为一致。

CLI 的核心目标可以归纳为以下几点：

• 降低 Filecoin 存储的接入门槛：通过 add、import、get 等少数命令完成"打包 → 上链 → 检索"完整闭环，无需用户直接处理 Synapse SDK、合约、Provider 选择等底层细节。
• 保证多入口一致性：CLI 与 filecoin-pin JavaScript 库 共享 src/core/ 下的业务逻辑层。
• 支持脚本化与 CI 场景：通过 applyVerboseLogLevel、环境变量回退（PRIVATE_KEY、SESSION_KEY、RPC_URL 等）以及非 TTY 输出降级，CLI 能在 CI 与交互终端下表现一致。
• 可观测性：CLI 自带遥测开关；通过 -v/--verbose 在调试时打开 LOG_LEVEL=debug，参见 src/utils/cli-logger.ts:14-23。

v1.1.0 版本（release notes）重点重构了 --help 输出：使用命令组（例如 Upload、Payments、Data sets）并附 quick-start 示例，回应了社区长期反馈（如 #576 "reorganize --help output with command groups"）。

全局标志与共享选项

CLI 大多数命令都会复用以下选项，集中在 src/utils/ 中以 Commander.js 工厂函数形式提供：

注意 --network 与 --rpc-url 二者不能同时设置，否则报错；当使用 --rpc-url 时，CLI 会在启动时探测 eth_chainId 并自动推断所属链（mainnet / calibration / 已配置的 devnet），见 README.md。

命令组与典型工作流

CLI 命令按职责归类（v1.1.0 起 --help 改用命令组视图）。下面是按组归类后的常用命令及其作用：

上传与导入（Upload / Import）

• filecoin-pin add <path>：读取本地文件或目录，通过 Helia 打包为 UnixFS CAR，再经 core/upload 经由 Synapse SDK 推送到所选 Provider。社区正在提议的 --dry-run（#591）允许在真正提交前估算 packed size 与成本。
• filecoin-pin import <car>：跳过打包阶段，直接上传已存在的 CAR 文件，适合在 CI 里把构建产物直接转给 Filecoin。

add 与 import 还可能消费 --egress-provider（#464）：默认 beam（通过 Beam 中转加速回源），可通过 --egress-provider none 关闭。

数据集管理（Data sets）

• data-set list：列出当前钱包持有的全部数据集。v1.1.0 后默认采用紧凑摘要视图，详细数据需通过 data-set show <datasetID> 查阅，对应 #578。
• data-set show <datasetID>：展示指定数据集的完整信息；当数据集较大时输出容易膨胀，社区讨论中的 piece-status 分页（#579）正是为了解决相同根因。
• data-set terminate <datasetID>：调用 Synapse SDK 的 terminateService 终止合约；CLI 显式传入 skipProvider: true（参见 #581），跳过 Provider 端动作，直接走链上结算路径。

支付与预付金（Payments）

payments 子命令组封装 src/core/payments/index.ts 中的 Synapse 支付操作，主要项目括：

• 查询 native FIL（用于 gas）与 USDFC（用于服务费）余额；
• 计算锁仓（lockup）与按 --min-runway-days / --max-balance 决定的额外充值金额（参见 src/core/payments/funding.ts 中 planFilecoinPayFunding）；
• 与 Service 合约之间的 approve / deposit / withdraw / set-approval-for-all 流程。

社区普遍反馈 payments 应当被列在 --help 顶部，并明确提示"必须先充值再上传"，该诉求正是 #576 的核心内容。

检索与守护进程（Get / Server）

• filecoin-pin get <cid>：基于上传得到的 IPFS Root CID 从 Provider 处拉回内容，闭环"上传 → 检索"，对应 #575。
• filecoin-pin server：在本地启动符合 IPFS Pinning Service API 规范 的 daemon，使 ipfs pin remote 等标准工具能直接对接 Filecoin（参见 README.md，处于 Beta 阶段）。

元数据（Metadata）

--metadata 与 --data-set-metadata 是上传命令最常用的元数据注入入口；src/utils/cli-options-metadata.ts 中的 parseKeyValuePairs 会校验 key=value 格式、禁止空键与重复键，避免下游 Synapse SDK 收到非法输入。元数据最终会通过 core/upload 关联到 Piece 或 DataSet 上。

典型工作流

下面是一个最小化的"充值 → 上传 → 检索"流程示例（命令可在 TTY 与 CI 两种环境下运行）：

# 1. 配置网络与钱包（环境变量方式）
export NETWORK=calibration
export PRIVATE_KEY=0x...

# 2. 检查 / 调整支付（locks up + deposit）
filecoin-pin payments status
filecoin-pin payments deposit --auto-fund --min-runway-days 30 --max-balance 100

# 3. 上传本地目录
filecoin-pin add ./dist --provider-id 1 --metadata "env=ci" --metadata "commit=$GITHUB_SHA"

# 4. 检索内容（v1.1.0 起的 get 命令对应 #575）
filecoin-pin get <root-cid> --output ./downloaded

若需要更强的可观测性，可以在脚本里追加 -v：

filecoin-pin -v add ./dist
# 等价于: LOG_LEVEL=debug filecoin-pin add ./dist

失败模式与社区关注的限制

• GitHub Action 版本引用：README 与早期文档建议 filecoin-project/filecoin-pin@v1，但 @v1 在 monorepo 阶段不可用；正确入口是 filecoin-project/filecoin-pin/[email protected]（见 #130）。社区已在 #527 中提议将 upload-action/ 拆分为独立仓库，以允许其独立发版。
• CLI 错误码矩阵尚未自动化：v1.x 之前手写 15 个错误场景 bash 扫描验证；#470 提议把它沉淀为可复用的 smoke test 套件。
• 私钥来源：当前私钥来源仅支持直接提供（环境变量 / 文件）；#589 与 #457 跟踪 1Password / Bitwarden 等安全保险库的接入。
• UnixFS CID 概况：CLI 仍以"包一层命名目录"的 UnixFS 形式生成 CAR，与 IPIP-499 默认 unixfs-v1-2025 存在差异，见 #306。

See Also

• README.md — 项目总览与安装方式
• documentation/behind-the-scenes-of-adding-a-file.md — add 命令的底层流程
• documentation/retrieval.md — 检索相关概念与 filecoin-pin get
• documentation/progress-events.md — 程序化使用时的进度事件
• src/core/payments/README.md — Synapse SDK 支付集成示例
• upload-action/README.md — GitHub Action 安全与版本说明

目的与定位

filecoin-pin 仓库同时交付 CLI、GitHub Action 与 IPFS Pinning Server，但 JavaScript 库是所有这些交互方式共享的“业务核心”。README 指出，库被组织为两层：高层的 import { … } from 'filecoin-pin' 覆盖最常见的用例，而底层的 import { … } from 'filecoin-pin/core/*' 则暴露 CAR 文件、支付、Synapse SDK、Upload、UnixFS 等子模块，供需要更细粒度控制的开发者复用。资料来源：README.md

这种分层使得 CLI 命令、Action 步骤、dApp Demo 都共享同一份业务逻辑，避免在多个 affordance 中重复实现上传与支付流程。documentation/README.md 进一步将文档划分为 Cookbook、API Reference、Progress Events、Events & Metrics 等多个专题，库 API 是其中“如果你要在程序中调用”这条主线的入口。资料来源：documentation/README.md

模块结构与导出

package.json 中 exports 字段明确划分了若干子路径，最关键的有：

资料来源：package.json

bin 字段同时声明了 filecoin-pin 可执行命令，意味着同一个打包产物既可作为库导入，也可作为 CLI 运行——这是该仓库“单一代码库、双重消费模式”设计的直接体现。

Synapse 生命周期与 SDK 封装

core/synapse 模块承担 SDK 初始化的全部职责，README 与源代码都强调：Synapse 是与 Filecoin Onchain Cloud 智能合约、存储服务提供方交互的主要库。src/core/payments/README.md 列举了 SDK 初始化的核心模式，包括网络选择、RPC URL、私钥管理、存储上下文创建、事件回调与 WebSocket 资源回收。资料来源：src/core/payments/README.md

CLI 侧通过 src/utils/cli-auth.ts 中的 CLIAuthOptions 接口将 --private-key、--wallet-address、--session-key、--view-address 等多种认证方式统一抽象，并在解析阶段把 --provider-id 与已废弃的 --provider-ids（逗号分隔）合并到同一个数组，--data-set-id 同理。资料来源：src/utils/cli-auth.ts

flowchart LR
  A[CLI/Action/库调用方] --> B[cli-auth 解析]
  B --> C[initializeSynapse]
  C --> D[Synapse SDK]
  D --> E[Filecoin Onchain Cloud]
  D --> F[Service Providers]

上传与数据集管理

core/upload 模块提供“统一的 CAR 上传接口”，把 CAR 文件推送到 Filecoin，并暴露上传进度、Piece 添加、确认等回调。src/core/payments/README.md 描述了它在上传过程中会关联 IPFS CID 与 Filecoin Piece，并返回存储服务提供方的直连下载 URL。资料来源：src/core/payments/README.md

数据集侧，src/core/data-set/list-data-sets.ts 暴露的 listDataSets(synapse, options?) 会通过 synapse.storage.findDataSets({ address }) 拉取当前地址的全部数据集，并通过 DEFAULT_DATA_SET_METADATA 标记哪些数据集是由 filecoin-pin 创建的。资料来源：src/core/data-set/list-data-sets.ts。社区正在讨论的 feat: add compact summary view to data-set list (#578) 与 feat: add pagination to piece-status (#579) 直接影响该 API 的输出形态与性能特征，建议在调用前查阅最新版本。

支付与充值

支付模块基于 Filecoin Pay（ERC-20 USDFC）实现两阶段充值：approve + deposit，并管理服务运营商的额度授权。src/core/payments/index.ts 顶部注释明确了核心常量：DEFAULT_LOCKUP_DAYS、MAX_LOCKUP_ALLOWANCE、MAX_RATE_ALLOWANCE、MIN_FIL_FOR_GAS 等，并对价格非零做了强校验。资料来源：src/core/payments/index.ts

src/core/payments/funding.ts 中的 formatFundingReason() 把底层 reason code（none、piece-upload、runway-insufficient、runway-with-piece、target-deposit、withdrawal-excess）翻译成人类可读的提示，方便 CLI 输出与库消费者复用。planFilecoinPayFunding() 接受外部传入的 PaymentStatus 与 accountSummary，可在不发起网络请求的情况下计算纯函数形式的资金计划。资料来源：src/core/payments/funding.ts

src/core/payments/top-up.ts 则提供 clampDepositToLimit() 这类纯函数——当用户指定了 maxBalance 上限时，把请求的充值额截断到不会超过上限的值，并返回 passthrough / already-at-limit / clamped 三种 reason。CLI 中的 --max-balance 行为直接复用此函数。资料来源：src/core/payments/top-up.ts

通用工具与已知限制

core/utils/format.ts 暴露的 formatFIL() 会根据数值动态扩展小数位，避免把极小的 tFIL/FIL 余额四舍五入显示成 0，并区分主网与测试网的单位（FIL vs tFIL）。资料来源：src/core/utils/format.ts。src/utils/cli-options-metadata.ts 则把 --with-piece-metadata、--with-dataset-metadata、ERC-8004 artifact 等元数据相关 CLI 旗标集中注册，库消费者也可以复用同一份 MetadataOptionConfig。

社区中值得关注的限制与演进方向：

• 上传前预估成本：feat: add --dry-run flag to filecoin-pin add (#591) 计划在提交前计算 packed size 与预估费用，目前只能通过完整 add 流程得知。
• 检索闭环：feat: add filecoin-pin get retrieval command (#575) 提议补齐“上传—存储—检索”闭环，库 API 也将相应扩展。
• 私钥管理：investigate support for 1pass/lastpass/bitwarden secure vaults (#589) 关注在库与 CLI 中接入第三方密钥库。
• 终止语义：data-set terminate: confirm skipProvider as the default (#581) 跟踪 src/data-set/run.ts:314 的 skipProvider: true 行为，使用 terminateDataSet() 时需确认默认路径。
• GitHub Action 独立版本化：Extract upload-action into a standalone repository (#527) 一旦完成，Action 标签 filecoin-project/filecoin-pin/upload-action@… 将脱离主仓库版本（#130 已记录过类似混淆）。

See Also

• documentation/README.md — 文档总览与各专题入口
• src/core/payments/README.md — 支付模块的 Synapse SDK 映射说明
• behind-the-scenes-of-adding-a-file.md — add 命令的端到端执行细节
• progress-events.md — onProgress 事件命名与消费约定
• events-and-metrics.md — 匿名遥测事件与指标清单

一、配置体系

1.1 认证与网络选项

CLI 与库共享同一组认证入参，集中在 src/utils/cli-auth.ts 的 CLIAuthOptions 接口中：

RPC 端点解析逻辑在 src/common/get-rpc-url.ts 中实现：当指定 rpcUrl 时优先使用；否则根据 NETWORK_CHAINS 选择主网或校准网的默认端点；针对本地开发场景，函数 resolveDevnetConfig 会读取 LOTUS_RPC_URL/LOTUS_WS_URL 等环境变量来拼接 devnet 配置。

1.2 支付相关常量与限制

src/core/payments/index.ts 中导出了一组用于支付与资金规划的运行时常量，包括 DEFAULT_LOCKUP_DAYS、MAX_LOCKUP_ALLOWANCE、MAX_RATE_ALLOWANCE、MIN_FIL_FOR_GAS、STORAGE_SCALE_MAX、USDFC_DECIMALS 等。这些常量被 planFilecoinPayFunding 用以决定 USDFC 充值上限与锁仓周期。读者在调整运行时参数时应以这些常量为基准，避免绕开内置的安全护栏（资料来源：src/core/payments/index.ts:1-80）。

1.3 遥测与版本检查

• 遥测：src/read-telemetry-config-from-env.ts 解析 FILECOIN_PIN_TELEMETRY_DISABLED、DO_NOT_TRACK 等环境变量，文件 README 强调"遥测默认开启但始终可禁用、且不收集 PII"（资料来源：README.md:1-200）。
• 版本检查：每次 CLI 启动会查询 npm，命中更新时打印提醒；可通过 --no-update-check 关闭（资料来源：README.md:1-200）。

二、部署形态

filecoin-pin 仓库同时承载多种交付物，package.json 中通过 exports 字段将以下入口暴露给消费方：

"bin":        { "filecoin-pin": "dist/cli.js" }
"./core/*":   核心模块（payments、upload、synapse、unixfs、utils、data-set）
"./version-check"
"./read-telemetry-config-from-env"

下表总结四种主要部署形态及其状态：

社区反馈（#130）指出旧文档中 filecoin-project/filecoin-pin@v1 标签并不存在；正确引用方式为 filecoin-project/filecoin-pin/upload-action@<version>。

2.1 GitHub Action 部署模式

upload-action/README.md 与 upload-action/examples/README.md 描述了三种工作流模板：

• 双工作流模式（推荐）：build.yml 在不可信上下文中构建产物，upload-to-filecoin.yml 在可信上下文中使用 FILECOIN_WALLET_KEY 拉取构件并上传。
• 单工作流模式：构建与上传合并到同一可信工作流，仅适用于受信仓库。
• CLI 配方：upload-action/examples/cli-recipe/README.md 演示在自定义步骤中直接调用 filecoin-pin add，以便与第三方打包步骤组合。

不论采用哪种模板，upload-action/src/types.ts 中 PaymentConfig 的 minStorageDays 与 filecoinPayBalanceLimit（即运行时的 --min-runway-days / --max-balance）都必须硬编码在可信工作流中，禁止通过 PR 输入注入，以防止恶意 PR 触发超额充值（资料来源：upload-action/src/types.ts:1-120）。

2.2 数据集操作入口

src/core/data-set/index.ts 统一导出对数据集的查询与操作函数（list-data-sets、get-data-set-pieces、get-detailed-data-set、calculate-actual-storage、resolve-by-metadata），CLI 子命令 data-set list/show/terminate/piece-status 均构建于其上。社区已通过 #581 确认 data-set terminate 默认采用 skipProvider: true 的本地终止路径：两端最终都会触发相同的链上调用，但 filecoin-pin 选择跳过提供商请求路径以加快回收速度。

三、运维与排错

3.1 资金规划工作流

src/core/payments/funding.ts 提供 planFilecoinPayFunding 与纯计算版 calculateFilecoinPayFunding，输出形如：

• runway-insufficient：当前 runway 不足，需补足到 targetRunwayDays
• runway-with-piece：考虑本次上传后的 runway
• withdrawal-excess：可提取的余额
• target-deposit：达到 targetDeposit 的差额

formatFundingReason 会把这些原因码转译为中英文友好的提示，方便在 CLI 与 Action 日志中直接呈现。

3.2 安全与密钥管理

• 私钥注入：PRIVATE_KEY/FILECOIN_WALLET_KEY 通过环境变量传入；强烈建议结合 GitHub Environments + 人工审批门禁（资料来源：upload-action/README.md:1-200）。
• 密钥保管扩展：社区正在讨论 1Password/LastPass/Bitwarden 等隐私保险库与 OpenWallet 标准的兼容方案（#589），目前仍需用户手动将密钥注入 secrets。
• 分支保护：建议在 main 分支启用必须由维护者审阅的规则，并配置 CODEOWNERS 强制安全团队批准工作流变更（资料来源：upload-action/README.md:1-200）。

3.3 常见故障与提示

• action 版本错误：参考上文 2.1，使用 [email protected]（#130）。
• 大数据集输出冗长：data-set show 与 piece-status 默认无界抓取所有 piece，社区已记录此问题（#579），可通过分页或过滤缓解。
• 成本预估缺失：用户希望在上传前看到打包大小与存储成本，社区已提议 --dry-run 标志（#591），目前需手动复核资金计划。
• 回环缺口：上传完成后无内置检索命令，社区正在设计 filecoin-pin get（#575），当前需使用 Kubo、curl 或公共信任网关。
• CLI 错误矩阵：CLI 错误码验证仍依赖手工脚本（#470），开发 PR 涉及 CliFatal 行为时请同步更新 smoke test。

四、参考阅读

• Builder Cookbook（官方逐步指南）
• DEVELOPMENT.md（开发与调试）
• Behind the scenes of adding a file（add 命令内部流程）
• Retrieving Your Data（检索方式）
• Content Routing FAQ（IPNI 与路由）
• Filecoin Pin 术语表

See Also

• Add a file (CLI) — filecoin-pin add 的详细参数与示例
• Data Set management — 数据集生命周期与 piece 查询
• GitHub Action integration — 双工作流模式与安全最佳实践
• Payments & Funding — Filecoin Pay 充值与 runway 管理

Pitfall Log / 踩坑日志

项目：filecoin-project/filecoin-pin

摘要：发现 28 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：feat: add filecoin-pin get retrieval command。

1. 安装坑 · 来源证据：feat: add `filecoin-pin get` retrieval command

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: add filecoin-pin get retrieval command
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/575 | 来源类型 github_issue 暴露的待验证使用条件。

2. 运行坑 · 来源证据：feat: add pagination to `piece-status`

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：feat: add pagination to piece-status
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/579 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安全/权限坑 · 失败模式：security_permissions: Add CLI error-scenario smoke test matrix for devs

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Add CLI error-scenario smoke test matrix for devs
• 对用户的影响：Developers may expose sensitive permissions or credentials: Add CLI error-scenario smoke test matrix for devs
• 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/470 | Add CLI error-scenario smoke test matrix for devs

4. 安全/权限坑 · 来源证据：Add CLI error-scenario smoke test matrix for devs

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add CLI error-scenario smoke test matrix for devs
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/470 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

5. 安全/权限坑 · 来源证据：Extract upload-action into a standalone repository for independent versioning

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Extract upload-action into a standalone repository for independent versioning
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/527 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

6. 安装坑 · 失败模式：installation: Extract upload-action into a standalone repository for independent versioning

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Extract upload-action into a standalone repository for independent versioning
• 对用户的影响：Developers may fail before the first successful local run: Extract upload-action into a standalone repository for independent versioning
• 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/527 | Extract upload-action into a standalone repository for independent versioning

7. 安装坑 · 失败模式：installation: feat: add compact summary view to `data-set list`

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: feat: add compact summary view to data-set list
• 对用户的影响：Developers may fail before the first successful local run: feat: add compact summary view to data-set list
• 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/578 | feat: add compact summary view to data-set list

8. 安装坑 · 失败模式：installation: v0.22.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.22.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.22.1
• 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.1 | v0.22.1

9. 安装坑 · 失败模式：installation: v0.23.2

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.23.2
• 对用户的影响：Upgrade or migration may change expected behavior: v0.23.2
• 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.23.2 | v0.23.2

10. 安装坑 · 来源证据：feat: add compact summary view to `data-set list`

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: add compact summary view to data-set list
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/578 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

11. 配置坑 · 失败模式：configuration: v0.22.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.22.3
• 对用户的影响：Upgrade or migration may change expected behavior: v0.22.3
• 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.3 | v0.22.3

12. 配置坑 · 失败模式：configuration: v0.23.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.23.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.23.0
• 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.23.0 | v0.23.0

13. 配置坑 · 失败模式：configuration: v1.0.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.0.1
• 对用户的影响：Upgrade or migration may change expected behavior: v1.0.1
• 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v1.0.1 | v1.0.1

14. 能力坑 · 来源证据：feat: reorganize `--help` output with command groups and quick-start example

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：feat: reorganize --help output with command groups and quick-start example
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/filecoin-project/filecoin-pin/issues/576 | 来源类型 github_issue 暴露的待验证使用条件。

15. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/filecoin-project/filecoin-pin | README/documentation is current enough for a first validation pass.

16. 运行坑 · 失败模式：runtime: feat: add pagination to `piece-status`

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: feat: add pagination to piece-status
• 对用户的影响：Developers may hit a documented source-backed failure mode: feat: add pagination to piece-status
• 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/579 | feat: add pagination to piece-status

17. 维护坑 · 失败模式：migration: v0.21.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v0.21.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.21.0
• 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.21.0 | v0.21.0

18. 维护坑 · 失败模式：migration: v0.22.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v0.22.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.22.0
• 证据：failure_mode_cluster:github_release | https://github.com/filecoin-project/filecoin-pin/releases/tag/v0.22.0 | v0.22.0

19. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/filecoin-project/filecoin-pin | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/filecoin-project/filecoin-pin | no_demo; severity=medium

21. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/filecoin-project/filecoin-pin | no_demo; severity=medium

22. 能力坑 · 失败模式：capability: data-set terminate: confirm skipProvider as the default termination path

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: data-set terminate: confirm skipProvider as the default termination path
• 对用户的影响：Developers may hit a documented source-backed failure mode: data-set terminate: confirm skipProvider as the default termination path
• 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/581 | data-set terminate: confirm skipProvider as the default termination path

23. 能力坑 · 失败模式：capability: feat: add `--dry-run` flag to `filecoin-pin add` for pre-upload cost estimates

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: feat: add --dry-run flag to filecoin-pin add for pre-upload cost estimates
• 对用户的影响：Developers may hit a documented source-backed failure mode: feat: add --dry-run flag to filecoin-pin add for pre-upload cost estimates
• 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/591 | feat: add --dry-run flag to filecoin-pin add for pre-upload cost estimates

24. 能力坑 · 失败模式：capability: feat: reorganize `--help` output with command groups and quick-start example

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: feat: reorganize --help output with command groups and quick-start example
• 对用户的影响：Developers may hit a documented source-backed failure mode: feat: reorganize --help output with command groups and quick-start example
• 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/576 | feat: reorganize --help output with command groups and quick-start example

25. 能力坑 · 失败模式：capability: investigate support for 1pass/lastpass/bitwarden secure vaults for private keys

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: investigate support for 1pass/lastpass/bitwarden secure vaults for private keys
• 对用户的影响：Developers may hit a documented source-backed failure mode: investigate support for 1pass/lastpass/bitwarden secure vaults for private keys
• 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/589 | investigate support for 1pass/lastpass/bitwarden secure vaults for private keys

26. 能力坑 · 失败模式：conceptual: feat: add `filecoin-pin get` retrieval command

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: feat: add filecoin-pin get retrieval command
• 对用户的影响：Developers may hit a documented source-backed failure mode: feat: add filecoin-pin get retrieval command
• 证据：failure_mode_cluster:github_issue | https://github.com/filecoin-project/filecoin-pin/issues/575 | feat: add filecoin-pin get retrieval command

27. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/filecoin-project/filecoin-pin | issue_or_pr_quality=unknown

28. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/filecoin-project/filecoin-pin | release_recency=unknown