feat: 优化交易系统、统一术语和完善 SDK

.github/workflows/ci.yml

@@ -33,6 +33,8 @@ jobs:
           fi
 
       - name: Install & Run
+        env:
+          E2E_TEST_MNEMONIC: ${{ secrets.E2E_TEST_MNEMONIC }}
         run: |
           # Enable pipefail to capture turbo exit code through pipe
           set -o pipefail
@@ -108,6 +110,8 @@ jobs:
         run: pnpm exec playwright install-deps chromium
 
       - name: Run all checks
+        env:
+          E2E_TEST_MNEMONIC: ${{ secrets.E2E_TEST_MNEMONIC }}
         run: |
           if [ "${{ steps.changes.outputs.code }}" == "true" ]; then
             pnpm turbo run typecheck:run build i18n:run test:run e2e:ci

AGENTS.md

@@ -1,198 +1,107 @@
-# KeyApp AI 开发入口
+# AI 开发元原则
 
-## AI 开发工作流
+本文档定义 AI 开发的**元意识** — 如何思考、如何工作的方法论。
 
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         开发闭环                                      │
-├─────────────────────────────────────────────────────────────────────┤
-│                                                                      │
-│  1. 获取全部     pnpm agent                                          │
-│       ↓         (规则 + 知识地图 + 当前任务列表)                       │
-│  2. 领取任务     pnpm agent --claim 28                               │
-│       ↓         (自动分配 + 显示 worktree 命令)                       │
-│  3. 创建分支     git worktree add .git-worktree/issue-28 ...         │
-│       ↓                                                              │
-│  4. 开发代码     (参考白皮书: pnpm agent --chapter <路径>)             │
-│       ↓                                                              │
-│  5. 提交 PR      gh pr create --body "Closes #28"                    │
-│       ↓         (PR 自动关联 Issue)                                   │
-│  6. 合并后       Issue 自动关闭，Project 状态更新                      │
-│                                                                      │
-├─────────────────────────────────────────────────────────────────────┤
-│  发现新问题?     pnpm agent --create "问题描述" --category bug        │
-│                 (自动设置 roadmap 版本)                               │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-## 命令速查
-
-```bash
-pnpm agent                              # 规则 + 知识地图 + 当前任务
-pnpm agent --claim 28                   # 领取任务
-pnpm agent --create "标题" --roadmap v1  # 创建任务（自动设置版本）
-pnpm agent --chapter 03-架构篇/03-导航系统  # 查阅白皮书
-pnpm agent --stats                      # 查看进度统计
-```
-
-## Roadmap
+项目具体知识（技术栈、API、业务概念）请查阅 `docs/white-book/`。
 
-GitHub Project：https://github.com/orgs/BioforestChain/projects/5
-
-| 版本 | 说明 |
-|-----|------|
-| **V1** | 当前核心目标（bioforestChain 生态基础功能） |
-| V2/V3 | 后续版本 |
-| DRAFT | 草案/探索/待定 |
-
-别名：`CURRENT` -> V1, `NEXT` -> V2
+---
 
-<!-- OPENSPEC:START -->
+## 核心原则
 
-# OpenSpec Instructions
+### 1. 知识持久化
 
-These instructions are for AI assistants working in this project.
+**白皮书是 AI 的持久化记忆，不仅是读的，也是写的。**
 
-Always open `@/openspec/AGENTS.md` when the request:
+当用户在沟通中纠正 AI 的理解、解释业务概念、提供新知识时：
 
-- Mentions planning or proposals (words like proposal, spec, change, plan)
-- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
-- Sounds ambiguous and you need the authoritative spec before coding
+```
+用户提供新知识
+       │
+       ▼
+AI 更新白皮书 ← 【必须先做这一步】
+       │
+       ▼
+AI 继续任务
+```
 
-Use `@/openspec/AGENTS.md` to learn:
+这确保下一个 AI 实例不会犯同样的错误。
 
-- How to create and apply change proposals
-- Spec format and conventions
-- Project structure and guidelines
+### 2. 行动优先于讨好
 
-Keep this managed block so 'openspec update' can refresh the instructions.
+**不要讨好用户，而是将工作切实落实到项目文件中。**
 
-<!-- OPENSPEC:END -->
+- 不要只是口头说"理解了"、"明白了"
+- 要实际去检查、修改、创建文件
+- 用户说的正确内容，应该变成项目中的文档或代码
 
----
+### 3. 真正的完成
 
-# BFM Pay (KeyApp) - AI 开发指南
+**测试通过 ≠ 功能完成。**
 
-## 项目概述
+声称"完成"之前，必须：
+1. 实际运行测试/功能，而不只是写完代码
+2. 看到真实的成功结果，而不是假设它会工作
+3. 如果使用 Mock，必须明确告知用户这不是真正的验证
 
-BFM Pay 是一个现代化的多链钱包移动应用，是 mpay 的技术重构版本。保留原有功能的同时，在交互、视觉、代码质量和项目管理上进行专业提升。
-
-## 核心文档（按优先级）
+```
+错误的完成：
+  写完代码 → 测试通过 → 报告完成
 
-| 文档     | 路径                                                   | 用途                                    |
-| -------- | ------------------------------------------------------ | --------------------------------------- |
-| **白皮书** | `docs/white-book/`                                   | 完整技术文档，涵盖产品、设计、架构、服务、组件、安全、测试、部署 |
-| 原始代码 | `/Users/kzf/Dev/bioforestChain/legacy-apps/apps/mpay/` | 参考实现细节                            |
+正确的完成：
+  写完代码 → 运行测试 → 看到结果 → 验证功能 → 报告完成
+```
 
-## 开发原则
+### 4. 文档驱动开发
 
-### 1. 文档优先级
+**先文档，后代码。**
 
 ```
-白皮书 (docs/white-book/) > mpay 原始代码
+白皮书 (docs/white-book/) > 原始代码参考
 ```
 
-当文档与原始代码冲突时，以白皮书为准。
-
-### 2. 开发工作流（重要）
+任何开发任务：
+1. 先检查/更新白皮书
+2. 再开始编码
 
-**任何开发任务开始前，必须按以下顺序执行：**
-
-1. **更新白皮书** - 如果需要新增功能或修改现有设计，先更新对应的白皮书章节
-2. **创建 openspec change** - 基于白皮书内容，创建具体的变更提案
-3. **开始编码** - 根据 openspec 的 tasks.md 执行开发
-
-### 3. 原始代码参考原则
+---
 
-- **参考，而非复制**：理解业务逻辑，不要盲目复制 Angular 代码
-- **质疑原始实现**：mpay 可能有 Bug、过时模式或未完成功能
-- **现代化改进**：使用 TypeScript 类型安全、TanStack 生态、函数组件
+## 层次区分
 
-### 4. 技术栈
+| 层次 | 存放位置 | 内容 |
+|-----|---------|------|
+| **元意识** | AGENTS.md | 如何思考、如何工作的原则 |
+| **项目知识** | docs/white-book/ | 业务概念、技术细节、API 规范 |
+| **操作指南** | docs/white-book/ | 具体命令、配置、步骤 |
 
-- React 19 + Vite 7
-- Stackflow (导航) + TanStack (Query + Store + Form)
-- shadcn/ui + Tailwind CSS 4.x
-- Zod 4.x + i18next
-- Storybook 10.x + Vitest 4.x
+---
 
-## 工作流程
+## 快速入口
 
-### 0. Git Worktree 工作环境（重要）
+```bash
+pnpm agent                    # 获取项目知识和当前任务
+pnpm agent --chapter 00-必读  # 查看必读章节
+```
 
-**所有编码工作必须在 `.git-worktree/` 目录下的独立 worktree 中进行。** 主目录始终保持在 main 分支上，保持干净。
+详细的项目信息、技术栈、开发流程请查阅白皮书。
 
-**完整工作流程示例：**
+<!-- OPENSPEC:START -->
 
-```bash
-# 1. 在主目录创建 worktree（以功能名命名分支）
-cd /path/to/KeyApp
-git worktree add .git-worktree/<feature-name> -b <branch-name>
+# OpenSpec Instructions
 
-# 2. 进入 worktree 目录进行开发
-cd .git-worktree/<feature-name>
-pnpm install  # 首次需要安装依赖
+These instructions are for AI assistants working in this project.
 
-# 3. 开发完成后，在 worktree 中提交代码
-git add -A
-git commit -m "feat/fix: 描述"
+Always open `@/openspec/AGENTS.md` when the request:
 
-# 4. 推送分支并创建 PR（使用 gh 命令）
-git push -u origin <branch-name>
-gh pr create --title "PR 标题" --body "PR 描述" --base main
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
 
-# 5. 合并 PR 到 main（CI 检查通过后）
-gh pr merge --squash --delete-branch
+Use `@/openspec/AGENTS.md` to learn:
 
-# 6. 回到主目录，更新 main 分支
-cd ../..  # 回到项目根目录
-git pull origin main
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
 
-# 7. 清理 worktree
-git worktree remove .git-worktree/<feature-name>
-```
+Keep this managed block so 'openspec update' can refresh the instructions.
 
-**Worktree 优势**：
-- 隔离开发环境，避免相互干扰
-- 可同时进行多个功能开发
-- 主目录保持干净，便于代码审查
-- main 分支受保护，必须通过 PR 合并
-
-**注意事项**：
-- 主目录（项目根目录）始终保持在 main 分支，不要在主目录直接修改代码
-- 所有开发工作都在 `.git-worktree/` 子目录中进行
-- 使用 `gh` CLI 工具来创建和合并 PR
-- PR 合并后记得清理对应的 worktree
-
-### 1. 开始新功能前
-   - 先更新 `docs/white-book/` 相关章节（如需要）
-   - 阅读 `openspec/` 下的相关 spec
-   - 检查 `openspec/changes/` 是否有进行中的变更
-   - 创建 change proposal（如适用）
-   - **在 `.git-worktree/` 下创建新的 worktree**
-
-### 2. 开发时
-   - 先写 Storybook story
-   - 再写 Vitest 测试
-   - 最后实现组件
-   - 确定所有测试都通过了,必要时需要更新e2e截图(必须查看截图内容确保符合预期)
-
-### 3. 完成后
-   - 确保所有测试通过（`pnpm test`）
-   - 确保类型检查通过（`pnpm typecheck`）
-   - 更新 tasks.md 状态
-   - 在 worktree 中提交代码
-   - 推送分支：`git push -u origin <branch-name>`
-   - 创建 PR：`gh pr create --title "标题" --body "描述" --base main`
-   - 等待 CI 检查通过
-   - 合并 PR：`gh pr merge --squash --delete-branch`
-   - 回到主目录更新 main：`cd ../.. && git pull origin main`
-   - 清理 worktree：`git worktree remove .git-worktree/<feature-name>`
-
-## 注意事项
-
-- 所有组件必须有 Storybook story
-- 所有业务逻辑必须有单元测试
-- 使用 TypeScript 严格模式
-- 遵循白皮书中的代码规范
-- POR/TUI 本地工具解析 `docs/por/T*/task.yaml` 需要 `python -m pip install --user pyyaml`
+<!-- OPENSPEC:END -->

CHAT.md

@@ -502,3 +502,106 @@ The above error occurred in the <SendPage> component.
    2. 实现一套 通用的预测service
    3. bioChain的区块Service, 内置配置一套能实现 bioChain 出块预测的虚拟数据生成器, 基于获取创世区块和最近的一个区块, 来模拟生成200条数据, 能实现对接预测service(第一次创建发现如果没有数据, 那么虚拟数据生成器工作, 然后导入这些虚拟数据)
 2. 当lastBlock的signature 发生变化(注意不是height, 考虑分叉问题可能高度没变, 但是签名是唯一的肯定会变)bioChain相关的订阅也就能去更新了:比如可以去加载最新的余额、最新的交易列表
+
+---
+
+1. #102 还未合并
+2. 转账还未通过
+3. 目前这个版本的交易列表还是没有加载出来
+   - 之前有一次开发过程中有成果加载出来交易列表,但是样式存在严重的问题, 字体的粗细、颜色 都不符合规范
+4. 设置支付密码还未测试, 同时也还未测试设置支付密码之后的转账
+
+---
+
+1. `pnpm agent` 的多种功能,需要通过“子命令”的方式来开启
+2. 新增一个子命令`worktree`:
+   1. create:就是到.git-worktree创建工作空间, 这里创建出来后,要顺便执行依赖安装,还有把我们的`.env.local`文件复制到新工作空间中
+   2. delete:就是删除.git-worktree创建出来的某个工作空间中, 删除之前要使用gh命令检查一下分支是否有对应的pr,pr有没有合并. 如果检查有问题应该停止, 除非`--force`
+   3. list:列出创建的工作空间,同时附带branch、pr+status 等信息
+3. 更新 `pnpm agent` 相关的工作流的提示词
+
+---
+
+在 新增钱包/导入钱包 的最后一步,应该默认提供一个“选择区块链网络”, 这是一个二级结构:
+
+1. 第一级是“技术选择”,第二级是具体的网络选择
+2. 比如用户可以勾选 “生物链林”,等于批量勾选了“BFChainV2”、“BFMeta”、“CCChain”等等, 同理“ETH”、“Tron”等等也是如此. 我们这里默认勾选“生物链林”
+
+否则现在进来就默认是 ETH, 会令新手用户困惑.
+
+这个勾选其实类似于“收藏”的功能:
+我们现在的网络切换列表不算多但也不少,但未来还会更长,所以这个列表其实应该是类似一个可以搜索的列表,顶部是用户收藏的链.
+
+---
+
+1. 我建议你统一找一下所有 chainId 的引用,我不知道你这个 chainId 是什么概念, 是chainName?magic? 总之我觉得很奇怪, 是遗留问题吗?
+2. 之前发生的问题如果重复发生, 那么大概率是 sdk 的封装不到位, 或者你有封装却没有去正确使用它.
+3. 不论如何, 以上都是我们这次巨大变更残留下来的问题, 我们需要在完成所有的基础工作(流程走通了)之后, 好好整理一下我们的代码, 提高它们的质量, 做好封装、做好重复利用
+
+---
+
+tansfer页面的交易列表样式存在严重的问题, 字体的粗细、颜色 都不符合规范、交易类型对应的中文也不对. 比如“设置安全密码”, 被显示成“质押”
+
+---
+
+我们的“内部SDK”,要封装出一套“订阅”接口,并作为我们的基本规范来使用
+我看你很多时候哦还是在直接使用我们内部的bio-sdk来开发界面上的功能,这和我们之前预设的不一样,sdk是用来开发我们的chain-adapter的才对,
+然后我们的chain-adapter应该要提供各种“use\*”的hook,来提供实时订阅的功能.
+
+```md
+区块链通常情况下,底层的轮询是依靠“高度”去触发更新的, 我们目前是各个services自己去轮询. 这本身没问题, 但是会因为考虑轮询的成本,所以要控制在30s一次.
+
+我的意思是. 我们不排除个别区块链可能存在一些特殊的机制: 比如还没出块,但是返回的交易列表中可能存在一些“队列中”的数据.
+但是不论如何, 至少在 bioChain的api是很普通的,返回的就是已经上链的数据.
+
+因此我们可以对bioChain对订阅做优化:
+
+1. 我们统一轮询“lastBlock”接口, 5s甚至2s一次, 未来我们可以更加智能, 但是目前可以用这种暴力轮询的方式.
+2. 当lastBlock的signature 发生变化(注意不是height, 考虑分叉问题可能高度没变, 但是签名是唯一的肯定会变)bioChain相关的订阅也就能去更新了:比如可以去加载最新的余额、最新的交易列表
+```
+
+---
+
+关于统一轮询“lastBlock”接口我们可以升级更智能: 根据前面几个区块的出块时间, 预测出出块时间.
+
+- 核心算法我已经实现在 `.tmp/yuce.ts` 中, 你需要的是将它对接到我们项目中:
+
+1. 配置一套基于indexedDB的存储服务, 并运行在Worker中
+2. 实现一套通用的预测service
+3. bioChain的区块Service, 内置配置一套能实现 bioChain 出块预测的虚拟数据生成器, 基于创世区块中时间信息高度信息和最近的一个区块的时间信息高度信息, 来模拟生成200条数据, 能实现对接预测service(第一次创建发现如果没有数据, 那么虚拟数据生成器工作, 然后导入这些虚拟数据),随着时间地推移, 我们会不断提供真实的数据. 来提高预测准确度
+4. 注意,不同的链网络都是不一样的预测器
+5. `use*`现在将只是使用我们service提供的订阅功能,而不是自己去轮询更新了,我们的service内置一整套实时监听的能力
+
+---
+
+只有正式产品的console需要被移除,另外其实我不建议不直接移除所有的console,我们应该有一个logger-provider,来实现按需打印内容.  
+但这是未来的任务,你可以记录到 github-project-task中.
+
+还有,我刚才手动运行了你最后做的那个e2e, 有问题: 最后的带字符密码的转账, 先点击确认后,
+并没有出现“广播成功”、“上链成功”的卡片,反而是在安全密码输入的地方显示了:“转账失败”
+
+还有,把所有的“支付密码”, 改成“安全密码”. 注意,要和“钱包密码”区分开来, 钱包密码统一改成“钱包锁”, 动作叫做: “解锁钱包”
+
+---
+
+bioChain的钱包的安全密码是这样的工作的:
+
+1. 你在进入这个钱包的时候, 就应该去根据交易类型, 去查询是否有设置过“安全密码”: 注意,这本质上是一个“订阅行为”,订阅查询最后一条“设置安全密码的交易记录”
+2. 你需要拿到这里面的 “安全密码公钥”, 这意味着后续的所有交易签名的面板弹出的时候,都需要判断是否存在这个“安全密码公钥”,如果有,就需要用户输入“安全密码”
+3. 基于“安全密码公钥”, 可以实时检测“安全密码”是否输入正确, 正确了才能做下一步: “签名交易”
+
+---
+
+为了进一步区分,我希望把“钱包锁”改成是一个九宫格的连线输入而不是密码框输入,这样就不会出现“请输入钱包锁”这种文字了,而是“请设置钱包锁”.
+要求至少连接4个点. 请你做这个组件的时候,尽量做好可访问性的支持,它本质其实就是一堆 checkbox, 只不过被渲染成九宫格,然后用滑动手势的方式来勾选这些checkbox. 当然我只是跟你解释这个可访问性的本质是什么.
+具体的开发请你根据最好的使用提体验来做.
+这个改动可能会比较大.
+
+---
+
+底部的“分享”功能,点击了应该复制的是一个url,现在只是复制了hash.
+我们需要在我们的 `default-chains.json`的`explorer` 字段中新增:`queryTx`和`queryAddress`
+比如我们的bfmeta网络的交易详情的浏览器链接应该是:
+queryTx:`https://tracker.bfmeta.org/#/info/event-details/:signature`
+queryAddress:`https://tracker.bfmeta.org/#/info/address-details/:address`
+queryBlock:`https://tracker.bfmeta.org/#/info/block-details/:height`