clams

技能目录

此技能中的所有 scripts/ 路径均相对于包含此 SKILL.md 文件的目录。运行任何脚本前，请先解析此技能目录的绝对路径。例如，如果此文件位于 ~/.claude/skills/clams/SKILL.md，那么脚本位于 ~/.claude/skills/clams/scripts/。

规则

1. 在会话中首次运行 clams 命令前，请先加载用户的 shell 配置文件，确保 PATH 已设置：source ~/.zshenv 2>/dev/null; source ~/.bashrc 2>/dev/null。每个会话只需执行一次。
2. 运行命令前，务必先阅读相关参考文件。 不要猜测标志或语法——请先查阅参考文件。
3. 对于需要解析输出或将输出传递给脚本的命令，使用 --machine --format json。
4. 用户希望在终端中查看报告输出时，使用 --format plain——直接显示 CLI 输出，不要重新排版。
5. 处理顺序：同步 → clams rates sync → clams journals process → 报告
6. 默认报告格式：显示类报告（资产负债表、余额历史记录、投资组合摘要）使用 --format plain，数据类报告（资本利得、日记账分录）使用 --format csv --output <path>。只有用户明确要求时才生成 PDF。
7. 对于 PDF 报告（仅限用户要求时）：将 JSON 通过管道传递给 <skill-dir>/scripts/render-<report>.sh --pdf <path>。需要 weasyprint。
8. 绝不概述或重新排版 CLI 输出中的金额——使用渲染脚本、--format plain 或 --format csv，让 CLI 负责格式化。
9. 绝不对财务数值进行算术运算。 不要对 CLI 输出求和、相减、取平均值或推导新数值——只显示 Clams 自行计算并格式化的数值。
10. 不存在 clams reports export 命令——PDF 和 CSV 按上述方式生成。
11. 遇到错误时：先阅读错误 JSON（code 和 message 字段），再诊断问题——不要猜测原因。如果错误信息不明确，请使用 --debug 重试命令，以获取更详细的输出。

注意事项

• 报告为空？ 你忘了运行 clams journals process。每次同步/导入后、生成任何报告前都必须运行它。这是最常见的错误。
• 金额单位为 millisatoshis。 切勿转换、四舍五入、汇总或显示原始 JSON 金额。始终通过渲染脚本处理，或使用 --format csv。
• 不存在 clams reports export。 如需 PDF，请将 JSON 通过管道传给 <skill-dir>/scripts/render-*.sh。如需 CSV，请在报告命令中使用 --format csv --output <path>。
• clams init 仅支持交互模式。 它不支持 --machine 模式。请改用 onboarding.md 中的各项命令。
• clams setup 适用于服务管理员。 不要在 CLI 工作流中使用它——它配置的是 Clams 服务，而不是客户端。
• 链上钱包需要先有链上来源。 XPub、Descriptor 和 Address 连接若没有链上来源，将无法同步。请在引导流程（第 7 步）中创建该来源。创建这些连接时，请自动解析链上来源和网络——参见 connections.md 中的“解析链上来源和网络”。除非确实存在歧义，否则不要询问用户。
• 元数据变更后需重新处理。 备注、标签、排除项、汇率覆盖和账户调整，只有再次运行 clams journals process 后才会生效。
• 省略 --excluded 会移除排除状态。 clams metadata records excluded set --event-id <ID> 若不带 --excluded 标志，会取消排除该事件——这是有意设计的，但不太符合直觉。
• 隔离状态会导致报告不准确。 未解决的隔离事件不会纳入报告。若数字看起来有误，请务必检查 clams journals quarantined。
• 所有 JSON 响应都包装在 data 信封中。 其结构为 {"kind": "...", "schema_version": 1, "data": ...}。始终访问 .data 以获取实际载荷——列表可能位于 .data（数组）或 .data.items（分页数据）中。
• --machine 需要搭配 --format json。 切勿将 --machine 与 --format csv 或 --format plain 组合使用，否则会报错。编写脚本时请使用 --machine --format json，或者省略 --machine，直接使用 --format plain / --format csv。
• 并非所有报告都支持 CSV。 只有资本利得和日记账分录支持 CSV 输出。资产负债表和投资组合摘要仅支持纯文本和 PDF。请参见 reports.md 中的格式支持表。
• 快速连续调用 CLI 会触发速率限制。 短时间内发送大量请求（例如，分页读取事件）会导致后端返回空响应。这些响应看起来像是身份验证错误，但只是暂时性的。分页时，请在每页之间延迟 0.5 秒，并在响应为空时重试（最多 3 次，每次间隔 2 秒）。请参见 journal-processing.md 中的分页部分。
• 事件数量可能很多。 Lightning 连接可能包含数万个事件。切勿假设第一页就是全部数据——始终检查 JSON 响应中的 next_cursor。如果用户询问数量，而第一页返回了完整的 500 条记录，那么几乎可以确定还有更多页面。

数据层级

workspace → profile → connections → journals → reports
                    → onchain sources (for on-chain wallets)
                    → metadata (notes, tags, exclusions)

报告选择

用户询问的内容……	报告
成本基础、净资产、未实现收益、投资组合价值、平均成本	投资组合摘要
已实现收益/损失、税务申报、处置、资本利得	资本利得
按账户/连接划分的当前余额、资产与负债	资产负债表
余额随时间的变化、余额趋势	余额历史
原始交易数据、账本导出	日记账分录

工作流路由

用户想要……	参考文档
登录、创建工作区/个人资料、配置设置、设置链上数据源	onboarding.md
添加钱包、列出/更新/删除连接、同步、导入 CSV/JSON	connections.md
管理链上数据源（Esplora、Electrum、Bitcoin RPC）、Tor 代理	onchain.md
通过自定义映射（csv_mapping）导入交易所 CSV、自定义连接	custom-connections.md
按 txid 或事件 ID 查找/检查特定交易	journal-processing.md
处理日记账记录、检查隔离区、解决被隔离的事件	journal-processing.md
添加备注、标签、排除项、汇率覆盖或账户调整	metadata.md
生成资产负债表、余额历史记录、投资组合摘要、资本利得、日记账分录	reports.md
验证 CLI 是否就绪、在工作流前后检查状态	verification.md
诊断错误或结果为空的问题	troubleshooting.md

回退

clams --help
clams <subcommand> --help