OpenHuman Tiny Place 账本 UX 补齐资产过滤、In/Out 方向过滤与 Tx ID 一键复制的前端设计【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman本文以 docs/superpowers/specs/2026-07-30-ledger-ux-filters-design.md 设计规格为骨架展开面向在 OpenHuman 中维护或扩展 Tiny Place「Agent World」公共交易账本面板的前端工程师说明补齐 Ledger 审计项三大交互缺口的完整方案按资产筛选交易、按收/支方向筛选交易、以及复制交易 ID。读完你将掌握一套「纯客户端、基于已加载数据行、内存过滤 无匹配兜底 UI」的账本交互设计思路以及与之配套的 Vitest 测试清单、i18n 键位与无 PII 调试日志规范。1. 背景Tiny Place 审计大项 #4776 的 Ledger 子切片本设计是 Tiny Place 审计 epic#4776 §4Ledger 账本的一个子切片sub-slice。同一审计批次下的兄弟设计文档可以佐证其上下文与代码风格约定例如 2026-07-30-directory-search-pagination-design.md§6 Directory 的搜索与分页以及 2026-07-30-tinyplace-feed-post-media-web-only-design.md§2 Feed 的媒体字段 web-only 决策它们共享同一套「先设计、后 TDD 实现」的工作流superpowers specs 目录与相同的代码约定。在进入本切片之前账本面板LedgerSection已经具备分页能力pagination already landed——即用户已经可以通过 Load more 模式逐页拉取公共交易账本。本次要补齐的剩余 §4 UX 缺口集中在三处没有资产筛选无法按资产USDC / SOL / …过滤可见交易没有收/支方向筛选无法只看「收到的」或「发出的」交易交易 ID 无法复制Tx ID 只是纯文本旁边仅有一个 View on chain 区块链浏览器跳转链接缺少复制操作入口。值得注意的是本规格明确标注Frontend only纯前端改动不涉及服务端、不涉及 Rust core 变更因此实施范围小、回归风险集中在 React 层。2. 问题分析为什么三种缺口都选客户端解决设计文档在 Problem 段落先界定了现状再在 Solution 段落给出关键架构决策三种能力全部做成 client-side客户端侧作用在已经加载到内存的transactions数组之上并明确放弃 server-side filtering服务端过滤。这一点是有意为之理由如下。2.1 资产字段不是单一形态tx.asset在数据层可能是**资产符号symbol或铸币地址mint address**两种形态之一。设计文档强调assets.resolveAssetSymbol这一解析函数可以同时处理这两种形态——即把 mint address 也解析回人类可读的符号。若做服务端asset过滤过滤值无法可靠匹配存储形态的差异而客户端在拿到行数据后统一经resolveAssetSymbol归一化再比较才是可靠路径。这与 OpenHuman 的 Solana/web3 底座相呼应在 src/openhuman/web3/wallet/defaults.rs 中可以确认项目以「cluster网络 USDC SPL-token mint address」的形式定义资产配置代码注释 USDC SPL-token mint address for the cluster即资产既有符号又有链上 mint 地址两个维度二者天然不能假设相等。2.2 方向是「观察者相关」的概念一笔交易是 In 还是 Out取决于它相对谁的钱包地址而言——to myAddr是 Infrom myAddr是 Out。对一个公共账本public ledger而言方向并不属于服务端可表达的概念服务端面对的是全体访问者没有「当前查看者」的概念。因此方向判断只能下沉到客户端、基于「当前用户的钱包地址」与行的to/from字段做比较。3. 解决方案详解3.1 复制 Tx IDcopy tx-id在展开后的交易详情里于 Tx ID 旁增加一个复制按钮复制动作调用 Web Clipboard APInavigator.clipboard.writeText(tx.txId)复制成功后进入瞬态 Copied 状态持续约1.5s后自动还原文案走 i18n按钮与 Copied 提示分属两个键copyTxId与copied优雅降级若环境不支持 clipboard API复制动作静默失败不抛错、不打断用户操作degrade silently。这一设计与仓库中既有的剪贴板相关交互保持一致的容错基调UI 功能在能力缺失时应降级而非报错。3.2 资产过滤client-side用一个select下拉框实现首项固定为 All全部资产其余选项来自当前已加载行数据中经resolveAssetSymbol(tx.asset)归一化后的去重值集合distinct values关键设计复用渲染侧同一个解析函数来生成选项标签从根本上保证「下拉选项文本」与「行内实际展示的资产文本」永远一致不会出现选项是符号而行内是 mint 地址或反之的错位问题选中某个资产后渲染列表被收窄到仅含该资产的行。3.3 方向过滤client-sidewallet-gated用All / In / Out三段式分段控件segmented control实现myAddr当前查看者钱包地址来源于fetchWalletStatus()返回的 Solana 账户地址行分类规则Into myAddrOutfrom myAddr钱包门控wallet-gated当拿不到钱包地址时该控件整体隐藏——因为公共账本在没有「我」的地址时方向这一「观察者相关」概念无从谈起展示一个无法工作的过滤器只会造成误导。仓库中可以找到fetchWalletStatus的真实实现与调用证据app/src/services/walletApi.ts 定义了fetchWalletStatus其单元测试见 app/src/services/walletApi.test.tsapp/src/hooks/useWalletConfigured.ts 展示了它在组件侧的标准用法调用fetchWalletStatus()得到钱包配置状态并正确处理 rejectedRPC 传输失败等分支测试见 app/src/hooks/useWalletConfigured.test.ts。可见「先探测钱包状态、再决定是否渲染钱包相关 UI」在 OpenHuman 中已有成熟先例Ledger 方向过滤的门控可复用同一服务与错误语义。3.4 交互细节与诚实的设计取舍两个过滤条件在渲染前统一施加到已加载的transactions上并使用memoized记忆化计算避免不必要的重渲染Load more 继续按原始分页拉取新的原始页面每次追加后过滤条件会重新施加到扩大的数据集上即过滤总是基于「当前已加载的全部行」而不是某一次快照当过滤条件把所有已加载行都隐藏时渲染独立的 no transactions match these filters 提示文案与「账本本身为空」的空账本文案empty-ledger copy明确区分开——两种空态含义不同用户应当能分辨「真没有数据」与「数据存在但被过滤掉了」同时在无匹配提示出现时过滤控件仍然保持可见让用户能随时调整/清除条件而不是陷入死胡同设计文档用一个短语概括了这一取舍并称之为显式、诚实的权衡filters act on loaded rows, not the entire server ledger——过滤器只作用于已加载的行而不是服务端账本的全量数据。这是刻意不引入服务端过滤所带来的直接后果当用户尚未加载足够多页时过滤结果只是「当前已加载范围内」的子集。4. 明确的 Out of scope为避免范围蔓延scope creep本规格主动划清边界以下内容不属于本切片账本上的钱包余额展示wallet-balance-on-ledger实时更新real-time updatesCSV 导出CSV export——以上三项是 §4 的其他审计项服务端过滤server-side filtering。这一「先明确不做」的做法与同目录其他设计文档一脉相承例如 Directory 规格同样把 type filter 明确列为 out of scope是避免子切片无限膨胀的关键纪律。5. 测试方案Vitest, TDD按设计文档要求本切片**以测试先行TDD**方式扩展LedgerSection.test.tsx共 5 条用例覆盖了功能、门控与空态语义三层复制按钮点击后把tx.txId写入剪贴板并展示 Copied 反馈资产过滤选择某一资产后列表收窄为仅含该资产的行方向过滤在 mock 钱包的情况下切换到 In 只显示收到的行、切换到 Out 只显示发出的行钱包门控当fetchWalletStatus未返回地址时方向控件不渲染零结果空态过滤后行数为 0 时渲染 no match 消息而不是空账本文案且过滤控件保持可见。第 5 条尤其重要——它把「过滤无结果」与「账本为空」在测试层锁死为两种不同状态防止将来重构时两种文案被错误合并。6. i18n 约定新增文案统一走国际化在 app/src/lib/i18n/en.ts 以及全部 13 个 locale 文件中同步添加以下 10 个键键用途filterAsset资产过滤下拉的标签filterAllAssetsAll全部资产选项文本direction方向过滤分段的标签directionAll方向分段 AlldirectionIn方向分段 In收到的directionOut方向分段 Out发出的copyTxId复制 Tx ID 按钮copied复制成功的瞬态反馈 CopiednoMatch过滤后无匹配的主文案noMatchHint过滤后无匹配的辅助提示同时遵守与同批兄弟规格一致的硬性规则键值文案中不得使用 em dash长破折号即 —— 这类字符以保证文案在终端/窄宽度场景下的排版与搜索一致性。仓库现有 i18n 结构与此约定一致locale 文件按de / es / fr / hi / ja / ko / pt / ru / zh-CN / …等多语言平铺于 app/src/lib/i18n/新增键需要逐一补齐避免个别语言回退时出现缺键。7. 调试日志规范复用既有的命名空间debug(agentworld:ledger)该命名空间在 Directory 切片中同样以debug(agentworld:directory)的形式出现属于 Agent World 统一的调试命名约定记录过滤条件变更选中的资产符号、选中的方向与复制操作的成败结果不记录任何 PII——日志中的地址维持已有的缩写形式addresses already abbreviated in logs避免将完整钱包地址或交易细节落入日志。8. 从设计到落地的关键路径回顾综合上述设计一个可落地的实现路径可以归纳为在账本面板的已加载数据上引入两个纯客户端过滤维度资产、方向均通过记忆化计算在渲染前派生可见行集合复制按钮严格走navigator.clipboard.writeText 1.5s 瞬态反馈 静默降级资产选项复用resolveAssetSymbol保证选项与行内展示一致方向判断以fetchWalletStatus()返回的myAddr为准无钱包地址即隐藏控件用独立的noMatch空态区分「无数据」与「被过滤空」并保留控件可操作性以 5 条 Vitest 用例先行锁定行为再补齐 10 个 i18n 键en 13 locales与无 PII 的调试日志。从仓库现状看fetchWalletStatus钱包探测链路walletApi.ts useWalletConfigured.ts与 Solana 资产配置底座defaults.rs已经就绪本切片在此之上补齐的是查看层viewer-relative的交互体验。对任何参与 Tiny Place 集成或需要为公共账本类 UI 增加客户端过滤能力的开发者而言这份设计的「钱包门控 复用解析器 诚实空态」三原则都是可以直接迁移的模式。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考