Merge pull request #5 from AelfScanProject/codex/skill-unified-upgrade-20260227

kastale · web-flow · commit 3e2cde793a4f · 2026-03-05T01:50:12.000+08:00
Codex/skill unified upgrade 20260227
diff --git a/README.md b/README.md
@@ -120,6 +120,12 @@ RUN_LIVE_TESTS=1 bun run test:e2e
 - `AELFSCAN_MCP_MAX_CHARS` (default: `60000`)
 - `AELFSCAN_MCP_INCLUDE_RAW` (default: `false`)
 
+## Wallet Context Compatibility
+
+- This skill is read-only and does not consume signer/private-key context for on-chain writes.
+- It is compatible with the shared wallet-context protocol (`~/.portkey/skill-wallet/context.v1.json`) used by write-capable skills.
+- `bun run deps:check` validates wallet-context schema version when a local context file exists.
+
 ## License
 
 MIT
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -120,6 +120,12 @@ RUN_LIVE_TESTS=1 bun run test:e2e
 - `AELFSCAN_MCP_MAX_CHARS`（默认 `60000`）
 - `AELFSCAN_MCP_INCLUDE_RAW`（默认 `false`）
 
+## 钱包上下文兼容性
+
+- 本 skill 为只读，不消费 signer/private-key 上下文，也不执行链上写操作。
+- 兼容写能力 skill 使用的共享 wallet-context 协议（`~/.portkey/skill-wallet/context.v1.json`）。
+- 当本地存在 context 文件时，`bun run deps:check` 会校验 wallet-context schema 版本。
+
 ## License
 
 MIT
diff --git a/SKILL.md b/SKILL.md
@@ -16,8 +16,8 @@ description: "AelfScan explorer data retrieval and analytics skill for agents."
 
 ## Safe usage rules
 - Never print private keys, mnemonics, or tokens in channel outputs.
-- For write operations, require explicit user confirmation and validate parameters before sending transactions.
-- Prefer `simulate` or read-only queries first when available.
+- This skill is read-only; do not attempt to execute chain writes via this package.
+- If user intent requires writes, route to wallet + domain write skills and keep this skill for analytics.
 
 ## Command recipes
 - Start MCP server: `bun run mcp`
@@ -28,5 +28,6 @@ description: "AelfScan explorer data retrieval and analytics skill for agents."
 
 ## Limits / Non-goals
 - This skill focuses on domain operations and adapters; it is not a full wallet custody system.
+- It does not consume signer context for transaction signing.
 - Do not hardcode environment secrets in source code or docs.
 - Avoid bypassing validation for external service calls.
diff --git a/bin/setup.ts b/bin/setup.ts
@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { Command } from 'commander';
 import * as fs from 'node:fs';
+import packageJson from '../package.json';
 import {
   LOG,
   SERVER_NAME,
@@ -20,7 +21,7 @@ const program = new Command();
 program
   .name('aelfscan-setup')
   .description('Configure @aelfscan/agent-skills for Claude/Cursor/OpenClaw')
-  .version('0.1.0');
+  .version(packageJson.version);
 
 const withCommonMcpOptions = (command: Command) =>
   command
diff --git a/bun.lock b/bun.lock
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@aelfscan/agent-skills",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "AelfScan explorer skill toolkit for AI agents: MCP, CLI, and SDK interfaces.",
   "type": "module",
   "main": "index.ts",
@@ -70,6 +70,7 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "ajv": "^8.17.1",
     "typescript": "^5.7.0"
   }
 }
diff --git a/schemas/wallet-context.v1.schema.json b/schemas/wallet-context.v1.schema.json
@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/AElfProject/aelf-skills/docs/schemas/wallet-context.v1.schema.json",
+  "title": "WalletContextFileV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "activeProfileId",
+    "profiles",
+    "lastWriter"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "activeProfileId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "profiles": {
+      "type": "object",
+      "minProperties": 0,
+      "additionalProperties": {
+        "$ref": "#/$defs/activeProfile"
+      }
+    },
+    "lastWriter": {
+      "$ref": "#/$defs/lastWriter"
+    }
+  },
+  "$defs": {
+    "activeProfile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "walletType",
+        "source",
+        "updatedAt"
+      ],
+      "properties": {
+        "walletType": {
+          "type": "string",
+          "enum": [
+            "EOA",
+            "CA"
+          ]
+        },
+        "source": {
+          "type": "string",
+          "enum": [
+            "eoa-local",
+            "ca-keystore",
+            "env"
+          ]
+        },
+        "network": {
+          "type": "string"
+        },
+        "address": {
+          "type": "string"
+        },
+        "caAddress": {
+          "type": "string"
+        },
+        "caHash": {
+          "type": "string"
+        },
+        "walletFile": {
+          "type": "string"
+        },
+        "keystoreFile": {
+          "type": "string"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "lastWriter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "skill",
+        "version"
+      ],
+      "properties": {
+        "skill": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}
diff --git a/scripts/check-deps-baseline.ts b/scripts/check-deps-baseline.ts
@@ -1,6 +1,8 @@
 #!/usr/bin/env bun
 import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { resolve } from 'node:path';
+import Ajv from 'ajv';
 
 type Baseline = {
   dependencies: Record<string, string>;
@@ -14,6 +16,7 @@ function main() {
   const cwd = process.cwd();
   const baselinePath = resolve(cwd, 'deps-baseline.json');
   const packagePath = resolve(cwd, 'package.json');
+  const contextSchemaPath = resolve(cwd, 'schemas', 'wallet-context.v1.schema.json');
 
   if (!existsSync(baselinePath)) {
     console.error(`[deps:check] missing deps-baseline.json at ${baselinePath}`);
@@ -44,8 +47,31 @@ function main() {
     }
   }
 
+  const contextPath =
+    process.env.PORTKEY_SKILL_WALLET_CONTEXT_PATH ||
+    resolve(homedir(), '.portkey', 'skill-wallet', 'context.v1.json');
+  if (!existsSync(contextSchemaPath)) {
+    failures.push(`missing wallet-context schema: ${contextSchemaPath}`);
+  } else if (existsSync(contextPath)) {
+    try {
+      const schema = readJson<Record<string, unknown>>(contextSchemaPath);
+      const contextRaw = readJson<Record<string, unknown>>(contextPath);
+      const ajv = new Ajv({ allErrors: true, strict: false });
+      const validate = ajv.compile(schema);
+      if (!validate(contextRaw)) {
+        const details = (validate.errors || [])
+          .map((err) => `${err.instancePath || '/'} ${err.message || 'invalid'}`)
+          .join('; ');
+        failures.push(`wallet-context schema validation failed (${contextPath}): ${details}`);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      failures.push(`wallet-context parse/validation failed: ${message}`);
+    }
+  }
+
   if (failures.length > 0) {
-    console.error('[deps:check] dependency baseline mismatch:');
+    console.error('[deps:check] check failed:');
     for (const failure of failures) {
       console.error(`- ${failure}`);
     }

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@aelfscan/agent-skills",`
`3`		`- "version": "0.2.1",`
	`3`	`+ "version": "0.2.2",`
`4`	`4`	`"description": "AelfScan explorer skill toolkit for AI agents: MCP, CLI, and SDK interfaces.",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "index.ts",`
`@@ -70,6 +70,7 @@`
`70`	`70`	`},`
`71`	`71`	`"devDependencies": {`
`72`	`72`	`"@types/bun": "latest",`
	`73`	`+ "ajv": "^8.17.1",`
`73`	`74`	`"typescript": "^5.7.0"`
`74`	`75`	`}`
`75`	`76`	`}`