Merge pull request #1 from AElfProject/codex/align-skill-1-5

refactor

Author: hzz780

.env.example

@@ -13,3 +13,8 @@ AELF_NODE_TIMEOUT_MS=10000
 
 # Optional retries for REST calls
 AELF_NODE_RETRY=1
+
+# Optional cache limits
+AELF_SDK_INSTANCE_CACHE_MAX=32
+AELF_SDK_CONTRACT_CACHE_MAX=256
+AELF_REST_CLIENT_CACHE_MAX=64

.github/workflows/publish.yml

@@ -1,11 +1,7 @@
 name: Publish to npm
 
 on:
-  pull_request:
   push:
-    branches:
-      - main
-      - master
     tags:
       - 'v*'
 
@@ -25,15 +21,7 @@ jobs:
 
       - run: bun install
 
-      - run: bun run test:unit:coverage:gate
-        env:
-          CORE_COVERAGE_THRESHOLD: '70'
-
-      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
-        with:
-          files: ./coverage/lcov.info
-          fail_ci_if_error: false
+      - run: bun run test:unit
 
   publish:
     if: startsWith(github.ref, 'refs/tags/v')

.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Unit Test
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  unit-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - run: bun install
+
+      - run: bun run test:unit:coverage:gate
+        env:
+          CORE_COVERAGE_THRESHOLD: '80'
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage/lcov.info
+          fail_ci_if_error: false

README.md

@@ -2,7 +2,7 @@
 
 [English](./README.md) | [中文](./README.zh-CN.md)
 
-AElf Node Skill provides MCP, CLI, and SDK interfaces for AElf public nodes with a `SDK-first + REST fallback` architecture.
+AElf Node Skill provides MCP, CLI, and SDK interfaces for AElf public nodes with `REST for reads, SDK for contract execution, and selective fallback for fee estimate`.
 
 ## Features
 
@@ -85,9 +85,13 @@ cp .env.example .env
 ```
 
 - `AELF_PRIVATE_KEY`: required for write operations
+- `AELF_PRIVATE_KEY` is read from environment only in MCP mode (no private key tool input)
 - `AELF_NODE_AELF_RPC_URL`: optional override for AELF node
 - `AELF_NODE_TDVV_RPC_URL`: optional override for tDVV node
 - `AELF_NODE_REGISTRY_PATH`: optional custom registry path
+- `AELF_SDK_INSTANCE_CACHE_MAX`: optional max SDK instance cache size (default `32`)
+- `AELF_SDK_CONTRACT_CACHE_MAX`: optional max SDK contract cache size (default `256`)
+- `AELF_REST_CLIENT_CACHE_MAX`: optional max REST client cache size (default `64`)
 
 ## Tool List
 

README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [中文](./README.zh-CN.md) | [English](./README.md)
 
-AElf Node Skill 提供 MCP、CLI、SDK 三种接口，基于 `SDK-first + REST fallback` 架构访问 AElf 公共节点。
+AElf Node Skill 提供 MCP、CLI、SDK 三种接口，采用“读走 REST、合约执行走 SDK、手续费估算选择性 fallback”的架构访问 AElf 公共节点。
 
 ## 功能
 
@@ -85,9 +85,13 @@ cp .env.example .env
 ```
 
 - `AELF_PRIVATE_KEY`：写操作必填
+- MCP 模式仅从环境变量读取 `AELF_PRIVATE_KEY`（不接受 tool 入参传私钥）
 - `AELF_NODE_AELF_RPC_URL`：可选，覆盖 AELF 节点
 - `AELF_NODE_TDVV_RPC_URL`：可选，覆盖 tDVV 节点
 - `AELF_NODE_REGISTRY_PATH`：可选，自定义节点注册表路径
+- `AELF_SDK_INSTANCE_CACHE_MAX`：可选，SDK 实例缓存上限（默认 `32`）
+- `AELF_SDK_CONTRACT_CACHE_MAX`：可选，SDK 合约缓存上限（默认 `256`）
+- `AELF_REST_CLIENT_CACHE_MAX`：可选，REST 客户端缓存上限（默认 `64`）
 
 ## Tool 列表
 

bin/check-core-coverage.ts

@@ -46,7 +46,7 @@ function parseCoreLineHits(lcovText: string): LineHits {
 
 function main() {
   const lcovFile = process.env.CORE_COVERAGE_FILE || 'coverage/lcov.info';
-  const threshold = Number(process.env.CORE_COVERAGE_THRESHOLD || '70');
+  const threshold = Number(process.env.CORE_COVERAGE_THRESHOLD || '80');
   const lcovPath = resolve(process.cwd(), lcovFile);
 
   if (!existsSync(lcovPath)) {

bin/setup.ts

@@ -19,7 +19,7 @@ const program = new Command();
 
 program
   .name('aelf-node-setup')
-  .description('Configure @aelfproject/aelf-node-skill for Claude/Cursor/OpenClaw')
+  .description('Configure @blockchain-forever/aelf-node-skill for Claude/Cursor/OpenClaw')
   .version('0.1.0');
 
 const withCommonMcpOptions = (command: Command) =>

bun.lock

@@ -13,7 +13,7 @@ export { callContractView, sendContractTransaction } from './src/core/contract.j
 export { importNode, listNodes } from './src/core/node-registry.js';
 
 export { resolveNode, listAvailableNodes } from './lib/node-router.js';
-export { clearSdkCaches } from './lib/sdk-client.js';
+export { clearSdkCaches, clearSdkCacheForRpc } from './lib/sdk-client.js';
 export type {
   SkillResponse,
   SkillError,

index.ts

@@ -1,4 +1,55 @@
 declare module 'aelf-sdk' {
-  const AElf: any;
+  export interface AelfWallet {
+    address: string;
+    [key: string]: unknown;
+  }
+
+  export interface AelfTxResult {
+    Status?: string;
+    [key: string]: unknown;
+  }
+
+  export interface AelfContractMethod {
+    (params?: Record<string, unknown>): Promise<unknown>;
+    call?: (params?: Record<string, unknown>) => Promise<unknown>;
+    getSignedTx?: (params?: Record<string, unknown>) => string;
+  }
+
+  export interface AelfContract {
+    [methodName: string]: AelfContractMethod | unknown;
+  }
+
+  export interface AelfChainApi {
+    contractAt(contractAddress: string, wallet: AelfWallet): Promise<AelfContract>;
+    getTxResult(transactionId: string): Promise<AelfTxResult>;
+    calculateTransactionFee(rawTransaction: string): Promise<unknown>;
+  }
+
+  export interface AelfInstance {
+    chain: AelfChainApi;
+  }
+
+  export interface HttpProviderConstructor {
+    new (rpcUrl: string, timeoutMs?: number): unknown;
+  }
+
+  export interface AelfWalletApi {
+    createNewWallet(): AelfWallet;
+    getWalletByPrivateKey(privateKey: string): AelfWallet;
+  }
+
+  export interface AelfStaticApi {
+    providers: {
+      HttpProvider: HttpProviderConstructor;
+    };
+    wallet: AelfWalletApi;
+  }
+
+  export interface AelfConstructor {
+    new (provider: unknown): AelfInstance;
+  }
+
+  const AElf: AelfConstructor & AelfStaticApi;
+
   export default AElf;
 }