Gaubee · Jan 8, 2026 · Jan 7, 2026 · Jan 7, 2026 · Jan 7, 2026 · Jan 7, 2026
diff --git a/.factory/mcp.json b/.factory/mcp.json
@@ -3,6 +3,10 @@
     "shadcn": {
       "command": "npx",
       "args": ["-y", "shadcn@latest", "mcp"]
+    },
+    "workflow": {
+      "command": "pnpm",
+      "args": ["agent:mcp"]
     }
   }
 }
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,152 +1,113 @@
-# AI 开发元原则
+# AI 开发元原则 (AI-Native Workflow 3.0)
 
-1. 本文档定义 AI 开发的**元意识** — 如何思考、如何工作的方法论。
-2. 项目具体知识（技术栈、API、业务概念）请查阅 `docs/white-book/`。
+1. **Schema-first**: 一切服务与数据结构设计，始于 Schema (Zod) 定义。
+2. **Issue-Driven**: 每一个改动都对应一个 Issue，每一个执行都对应一个 PR。
+3. **Full-Lifecycle**: 从 `investigate` 到 `document`，全流程自动化。
 
+项目具体知识（技术栈、API、业务概念）请查阅 `docs/white-book/`。
 
 ---
 
-## 元意识（自检与自更新）
+## pnpm agent 工具体系
 
-AI 必须具备以下自检与自更新能力，并在工作中显式执行：
+我们不再手动执行 git 命令，而是通过 `pnpm agent` 驱动全生命周期。
 
-1. **进度自检**：随时能说明当前在做什么、卡点在哪里、下一步是什么。
-2. **知识自更新**：用户提供新知识或纠正时，先更新 `docs/white-book/`，再继续任务。
-3. **项目自管理**：用 Roadmap/Issue/Worktree/PR 管理工作流，保证可追踪、可回滚。
-4. **最佳实践自维护**：发现可复用规律，及时更新白皮书或最佳实践提示。
+### 核心工作流
 
----
-
-## pnpm agent 工具（AI 启动入口）
-
-**每次新上下文启动必须执行：**
-
-```bash
-pnpm agent readme
-```
-
-`pnpm agent readme` 是白皮书导览入口，白皮书具体路径与阅读建议以该命令输出为准。
-最佳实践文件位于 `docs/white-book/00-必读/best-practices.md`，由 `pnpm agent practice` 维护。
+| 阶段 | 命令 | 作用 |
+|------|------|------|
+| **1. 调查** | `pnpm agent investigate analyze --type <type> --topic "..."` | 分析需求，阅读白皮书，生成 RFC |
+| **2. 启动** | `pnpm agent task start --type <type> --title "..."` | 创建 Issue/Branch/Worktree/Draft PR |
+| **3. 同步** | `pnpm agent task sync "..."` | 将本地进度同步到 GitHub Issue |
+| **4. 检查** | `pnpm agent review verify` | 运行 Lint/Typecheck/Test |
+| **5. 提交** | `pnpm agent task submit` | 推送代码，标记 PR 为 Ready |
+| **6. 文档** | `pnpm agent document sync` | 检查变更，推荐白皮书更新 |
 
-常用命令：
+### 辅助工具
 
 ```bash
-pnpm agent readme              # 启动入口（索引 + 知识地图 + 最佳实践）
-pnpm agent --help              # 查看帮助
-pnpm agent roadmap current     # 当前 Roadmap
-pnpm agent toc                 # 白皮书目录
-pnpm agent chapter <路径>       # 读取白皮书章节
-pnpm agent practice list       # 最佳实践列表
-pnpm agent practice add "<内容>"
-pnpm agent practice remove <序号|内容>
-pnpm agent practice update <序号> "<内容>"
-pnpm agent claim <issue#>       # 领取任务
-pnpm agent worktree create <name> --branch <branch> --base main
-pnpm agent worktree list
-pnpm agent worktree delete <name>
+pnpm agent readme              # 白皮书导览
+pnpm agent search "keyword"    # 搜索白皮书
+pnpm agent chapter <path>      # 阅读章节
+pnpm agent roadmap current     # 查看当前任务
 ```
 
 ---
 
-## 角色化工作流程（多场景）
+## 角色化工作流程
 
-### 1) 新上下文启动（必做）
+### 1) 需求澄清 (Investigate)
 
-```bash
-pnpm agent readme
-pnpm agent roadmap current
-pnpm agent toc
-pnpm agent chapter 00-必读
-```
-
-完成后自检：
-- 当前任务目标是否清晰？
-- 是否需要读更多白皮书章节？
-- 是否需要查看 openspec 规范？
-
-### 2) 继续未完成任务（接手/续写）
+**场景**: 收到模糊需求，或需要进行架构设计。
 
 ```bash
-pnpm agent readme
-pnpm agent roadmap current
-pnpm agent worktree list
-# 进入已有 worktree，检查 git status / 进度
-```
-
-自检：确认已有 worktree 的分支、PR 状态、CI 状态是否需要处理。
+# 1. 分析需求 & 查阅白皮书
+pnpm agent investigate analyze --type service --topic "New Auth Service"
 
-### 3) 需求澄清 / 方案设计（产品/架构角色）
-
-```bash
-pnpm agent readme
-pnpm agent toc
-pnpm agent chapter <需求相关章节>
+# 2. (可选) 搜索更多资料
+pnpm agent search "authentication"
 ```
 
-- 若涉及新能力/架构变更，先查看 `openspec/AGENTS.md` 并走提案流程。
-- 记录结论到白皮书或 openspec 变更中。
+### 2) 任务开发 (Task Loop)
 
-### 4) 实现开发（工程师角色）
+**场景**: 开始编码实现。
 
 ```bash
-pnpm agent readme
-pnpm agent claim <issue#>
-pnpm agent worktree create issue-<id> --branch feat/issue-<id> --base main
-cd .git-worktree/issue-<id>
-pnpm agent chapter <路径>
-# 开发 + 测试
-pnpm dev
-pnpm test
-pnpm typecheck
+# 1. 启动任务 (自动环境准备)
+pnpm agent task start --type service --title "Implement Auth Service"
+# -> 输出: cd .git-worktree/issue-123
+
+# 2. 进入开发环境
+cd .git-worktree/issue-123
+
+# 3. 开发循环
+# ... coding ...
+pnpm agent task sync "- [x] Schema defined" 
+# ... coding ...
+pnpm agent review verify
 ```
 
-```bash
-# 提交与 PR
- git add -A
- git commit -m "feat/fix: 描述"
- git push -u origin <branch>
- gh pr create --title "标题" --body "Closes #<issue#>" --base main
-```
+### 3) 完工交付 (Submit)
 
-### 5) Bug 修复 / 回归（维护者角色）
+**场景**: 代码完成，准备 Review。
 
 ```bash
-pnpm agent readme
-pnpm agent roadmap current
-pnpm agent worktree create fix-<id> --branch fix/<id> --base main
-```
-
-- 先复现并记录原因。
-- 必要时更新白皮书，说明修复背景与影响。
+# 1. 最后一次检查
+pnpm agent review checklist --type service
+pnpm agent review verify
 
-### 6) 评审 / 质量保证（Reviewer 角色）
-
-```bash
-pnpm agent readme
-pnpm agent chapter <测试/规范相关章节>
+# 2. 提交 & 触发 CI
+pnpm agent task submit
 ```
 
-- 关注回归风险、测试覆盖、接口兼容性。
-- 有问题先写明事实，再给出修复建议。
+### 4) 维护者 (Reviewer/Integrator)
 
-### 7) 合并收尾（集成角色）
+**场景**: Review 代码或合并 PR。
 
 ```bash
-gh pr checks <pr#> --watch
+# 1. 检查文档一致性
+pnpm agent document sync
+
+# 2. 合并 PR (使用 gh cli)
 gh pr merge <pr#> --squash --delete-branch
-pnpm agent worktree delete <name>
 ```
 
-合并门禁（必须执行）：  
-- **在合并之前必须询问用户**，并明确告知当前工作目录（worktree 路径）。  
-- 用户 review 确认后才允许执行合并。  
+---
+
+## 任务类型 (Type)
+
+- `ui`: 组件库、UI 交互 (自动关联 Storybook 检查)
+- `service`: 业务逻辑、API (自动关联 Unit Test 检查)
+- `page`: 页面路由、导航 (自动关联 Router 配置)
+- `hybrid`: 混合开发 (通用模板)
 
 ---
 
 ## 重要提醒
 
-- 白皮书是唯一权威来源：用户补充/纠正知识，必须先更新 `docs/white-book/`。
-- 不允许在主目录直接开发，所有代码必须在 `.git-worktree/` 中进行。
+- **白皮书是唯一权威**: 开发前必读相关章节 (`investigate` 会自动推荐)。
+- **严禁主目录开发**: 必须使用 `task start` 创建的 Worktree。
+- **Schema-first**: 服务开发必须先定义 `types.ts`。
 
 <!-- OPENSPEC:START -->
 

diff --git a/CHAT.md b/CHAT.md
@@ -1163,5 +1163,74 @@ worktree new task:
 ---
 
 将 WalletTab 中的下半部分：关于某个地址某个网络中的资产列表和交易列表，封装成一套组件。我要在 stories 中看到这套组件，并绑定真实的 chainProvider。
-提供两个 stories 测试，一个是 `bfmeta:bCfAynSAKhzgKLi3BXyuh5k22GctLR72j` ；一个是 `eth:bCfAynSAKhzgKLi3BXyuh5k22GctLR72j`
+提供两个 stories 测试，一个是 `biochain-bfmeta:b9gB9NzHKWsDKGYFCaNva6xRnxPwFfGcfx` ；一个是 `eth-eth:0x75a6F48BF634868b2980c97CcEf467A127597e08`
 我要确保能看到真实的数据。
+
+---
+
+使用 walletapi 继续完善我们的底层 api 的支持，比如实现 tronwallet-v1/ethwallet-v1/btcwallet-v1，并用它来作为我们的 fallback方案。
+参考：`/Users/kzf/Dev/bioforestChain/legacy-apps/libs/wallet-base/services/wallet/bitcoin`/`/Users/kzf/Dev/bioforestChain/legacy-apps/libs/wallet-base/services/wallet/ethereum`/`/Users/kzf/Dev/bioforestChain/legacy-apps/libs/wallet-base/services/wallet/binance`/`/Users/kzf/Dev/bioforestChain/legacy-apps/libs/wallet-base/services/wallet/tron`
+
+1. getMethod 返回的是一个能自动 fallback 的函数，比如一个函数有多个 provider，那么 Provider1 失败(`比如 response.ok()===false，或者其它错误结构`)，自动使用 Provider2 进行重试
+   1. 优先使用第三方，失败就 fallback 到 `*wallet-v1`，
+   2. 基于 default-chains.json 中 api 的配置顺序：破坏性更新！将 api 字段改成数组 apis。
+2. 完善测试，在 walletaddressportfolio 中补充测试各种 provider（独立对 Provider 进行测试）：
+   1. 比如在 real-data-ethereum 中，同时提供所有支持的 provider
+   2. 然后在测试中，确保至少有一个 Provider 真确显示出了非空的交易列表、非 0 的资产
+3. 这是我的 trongrid-api-key： c2c43cea-d490-4ba8-bab1-2ebf4ce81bae，我们可以优先使用 无 APIKEY 的 trongrid 免费接口，失败了再用有 api-key 的接口，再失败了再回退成使用 tronwallet-v1
+4. 先办法优化请求的调用次数，比如说这个方案：默认情况下余额和交易列表都是独立地去拉取，比如说 60s 轮询一次，但这会导致并发问题，可以优化成，如果余额变动了，那么交易列表再去触发拉取，否则交易列表的默认拉取时间是 5 分钟。
+   1. 以上这个方案我只是举一个粗糙的例子，这种代码实现可能会导致很多问题。这里我给出一些优化上的原则，不可以违背这些原则：
+   2. 不可以为了优化而影响代码的可靠性和可维护性。比如我上面的例子，具体要实现的时候，得从 fetch 函数入手：通过篡改 fetch 函数，来得知余额变更，否则优先返回列表缓存。这样的好处是这些优化策略都是可以动态插拔的，不会影响业务。
+   3. 还有一些链，可能出块比较慢，那么需要可以等区块变更了，再去做后续的拉取。这里的核心逻辑是：将“轮询”封装成“订阅”，基于订阅机制去做按需更新
+   4. 每种策略要足够独立，通过交叉优化来逐步改进
+5. 更新白皮书
+
+/Users/kzf/.factory/specs/2026-01-05-walletapi-fallback-providers-ordered-apis-request-optimization.md
+/Users/kzf/.factory/specs/2026-01-06-merge-walletapi-fallback-worktree-to-main.md
+
+这是我的 etherscan-api-key: UN6TIKGANUFRYYPNSD1SCHRAZ3NABF52XS,KXX7MGJR3U6IEZNSY1ESMCXWUGX6Z8QEU6,TMMTZHU2XN2YM2A5YIXTXA9EKJS1GPC3GD
+每次会话随机锁定其中一个，要能自动根据`,`分隔 api-key，然后随机选中其中一个（应用启动后，随机选中一次不会再变）
+这种随机选中 api-key 的逻辑，也在 trongrid 适用。
+
+---
+
+1. 基于 spec 文件： /Users/kzf/.factory/specs/2026-01-05-option-b1-evm-hash-token.md 开始进行 review
+2. 参考这份 spec，给出一份关于binance、tron、bitcoin 等优化方案： /Users/kzf/.factory/specs/2026-01-05-other-network-better-trs-list.md
+
+---
+
+更新完成交易列表，我们需要更新交易详情页，请你给我一份详细的交易详情页的更新计划
+
+/Users/kzf/.factory/specs/2026-01-05-update-transaction-detail-page-provider-schema.md
+/Users/kzf/.factory/specs/2026-01-06-chain-adapter-ssot-guard-at-the-gate-safeparse-transactions.md
+
+---
+
+我打开 storybook，发现大量的警告：
+
+```
+Use of an unknown prop (creditcard) in the Icons component. The Icons component is deprecated. Please use the @storybook/icons component directly. For more informations, see the migration notes at https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#icons-is-deprecat
+```
+
+---
+
+刚才你已经成功将 tron 的两个接口都修复了，并学会了使用测试驱动开发(#173)。
+接下来，我需要你开始修复其它接口：
+
+1. eth: https://eth.blockscout.com/api 预期是交易和资产都能查询到；目前是能查询到交易但是资产错误显示0。
+2. eth: https://ethereum-rpc.publicnode.com 预期是资产能查询到，不支持交易查询；目前是能查询资产，但是交易查询一直 loading。
+3. eth: https://api.etherscan.io/v2/api 预期是交易和资产都能查询到；目前是能查询到交易但是资产错误显示0。
+4. bnb: https://bsc-rpc.publicnode.com 预期是资产能查询到，不支持交易查询；目前是能查询资产，但是交易查询一直 loading。
+5. bsc: https://api.etherscan.io/v2/api 预期是交易和资产都能查询到；目前是能查询到交易但是资产错误显示0。
+
+walletapi相关的接口：
+
+6. eth: https://walletapi.bfmeta.info/wallet/eth 预期是交易和资产都能查询到；但是目前资产错误显示0，交易显示`Invalid API response`
+   参考文件： /Users/kzf/Dev/bioforestChain/legacy-apps/libs/wallet-base/services/wallet/ethereum/ethereum.service.ts
+7. tron: https://walletapi.bfmeta.info/wallet/tron 预期是交易和资产都能查询到；但是目前资产错误请求了`http://STORYBOOK_HOST/wallet/getaccount`，交易界面显示`Upstream API error`，我看网络面板是看到参数填写错误
+   参考文件： /Users/kzf/Dev/bioforestChain/legacy-apps/libs/wallet-base/services/wallet/tron/tron.service.ts
+8. bitcoin: https://walletapi.bfmeta.info/wallet/btc 预期是交易和资产都能查询到；但是目前资产和交易都错误请求了`https://walletapi.bfmeta.info/wallet/btc/blockbook`，并且界面上没有正确显示错误信息
+9. bsc: https://walletapi.bfmeta.info/wallet/bsc 预期是交易和资产都能查询到；目前是能查询资产，但是显示没有交易记录（查询了`https://walletapi.bfmeta.info/wallet/bsc/trans/normal/history`，然后返回：`{"success":true,"result":{"status":"0","message":"NOTOK","result":[]}}`）
+   参考文件： /Users/kzf/Dev/bioforestChain/legacy-apps/libs/wallet-base/services/wallet/binance/binance.service.ts
+
+/Users/kzf/.factory/specs/2026-01-06-api-walletapi.md