Skill BreakdownDeFi Vault OpsNo AI Required
Add Vault Note：为 DeFi vault 添加结构化备注
把 add-vault-note 技能从原始脚本变成可执行流程：输入模板、flag 决策矩阵、flag.py 修改与 PR 规范，一页完成。
这里的 vault 指 DeFi 金库数据，不是密码管理或笔记应用中的 vault。
必需输入
准备好这三项即可开始执行。
Vault 合约地址（EVM 地址，小写写入 flag.py）
人类可读备注（说明原因/风险）
可选 VaultFlag（未指定则 None）
输出结果
最终产物是一次可追溯的 PR。
VAULT_FLAGS_AND_NOTES 新增记录
备注常量 + flag 组合
notes 前缀 PR（无 changelog）
输入模板
可直接复制并填充。
Vault address: 0x... Message: "原因/风险说明" Flag: None | VaultFlag.illiquid | VaultFlag.broken | ...
地址必须以 0x 开头并保持小写。
Workflow
四步完成 add-vault-note 提交
从数据解析到 PR 命名，每一步都有明确要求。
解析 vault 名称
从官方 vault 列表中定位地址对应的名称，避免人工猜测。
主要来源：top_vaults_by_chain.json（体积较大，用搜索定位记录）或官方 vault 列表页面；必要时可用 check-vault-onchain.py。
Search top_vaults_by_chain.json by address → extract name (do not open the full JSON).
更新 flag.py
新增常量 + 记录到 VAULT_FLAGS_AND_NOTES，地址必须小写。
为备注创建常量；若未指定 flag，设置为 None。
# eth_defi/vault/flag.py
NEW_VAULT_NOTE = "Reason for flag"
VAULT_FLAGS_AND_NOTES = {
"0x...": (VaultFlag.illiquid, NEW_VAULT_NOTE), # Vault Name
}格式化与校验
运行 ruff，确保格式统一并避免 lint 失败。
只需格式化目标文件即可。
ruff format eth_defi/vault/flag.py
提交 PR
PR 标题前缀必须是 notes，且无需 changelog。
让审核者一眼识别这是数据备注更新。
Prefix PR title with "notes" (not feat). No changelog required.
VaultFlag Matrix
快速判断 flag 应用场景
BAD_FLAGS 代表高风险，必须有证据支撑。
| 类别 | 相关 Flags | 说明 |
|---|---|---|
| 运营状态 | deposit, redeem, paused, trading, idle | 描述资金是否可进出、是否在交易模式。 |
| 风险/异常 | illiquid, broken, malicious, abnormal_tvl, abnormal_price_on_low_tvl | 高风险警示；与 BAD_FLAGS 对齐，需谨慎使用。 |
| 结构/来源 | proprietary_trading, wrapped_asset, unofficial, subvault | 说明 vault 结构或来源问题，需补充备注。 |
风险提示
illiquid / broken / malicious 等 BAD_FLAGS 会影响用户判断，必须附带可核验依据。
Vault Summary JSON
定位 name/address/chain 的最短路径
字段解释来自 Trading Strategy 文档，用于对齐备注来源。
| 字段 | 含义 | 用途 |
|---|---|---|
| name | Vault 人类可读名称（可能包含链信息） | 作为备注行注释，避免同名混淆。 |
| address | Vault 合约地址 | 与输入地址对齐，确认无误写入。 |
| chain / chain_id | 链名称与链 ID | 同名 vault 去重，避免跨链混写。 |
| protocol | Vault 所属协议 | 辅助判断风险/备注背景。 |
| risk | 技术风险分类 | 用于判断是否需要 BAD_FLAGS。 |
| denomination | 计价资产（如 USDC） | 确认 vault 类型与资产口径。 |
使用提示
top_vaults_by_chain.json 体积很大，使用搜索定位记录，不要直接打开整文件。
自检清单
提交前必须全部通过。
地址已小写，并确认未重复出现在 VAULT_FLAGS_AND_NOTES。
为备注创建常量，并在字典中引用该常量。
flag 选择有证据支撑，未指定则 None。
已运行 ruff 格式化目标文件。
PR 标题前缀为 notes，且未新增 changelog。
评分标准
满分 6 分，6 分以上可提交。
0-3 分：流程不完整，需补充证据。
4-5 分：可提交但需复核。
6-7 分：达到提交标准。
Self-Test
5 道题快速验证掌握程度
每题 1-2 分，答对才能提交。
如何确认 vault 名称？
分值：2
从官方 vault 列表 JSON 或 vaults 页面检索地址。
为什么必须小写地址？
分值：1
flag.py 使用 lowercased key 做匹配，大小写不一致会失效。
未指定 flag 时应该写什么？
分值：1
将 flag 设置为 None，并保留备注常量。
PR 命名有什么要求？
分值：1
前缀使用 notes，而不是 feat。
提交前必须做的格式化动作？
分值：1
运行 ruff format 目标文件。
Resources
所有权威来源都在这里
引用这些资料即可复核每一步。
Source Kit
一键获取来源与合规信息
满足开源合规要求，减少上下文切换。
| Skill 源文件 | https://github.com/tradingstrategy-ai/web3-ethereum-defi/blob/master/.claude/skills/add-vault-note/SKILL.md |
| 克隆命令 | git clone https://github.com/tradingstrategy-ai/web3-ethereum-defi.git |
| 许可证 | MIT（README 明示） |
Notes PR 示例
用真实 PR 校准命名与备注风格
这些 PR 体现了 notes 前缀实践与备注语气。
FAQ
常见问题
遇到疑问时优先看这里。