From 6bc8ccb8cdb1519b7f5198d8ff8952ddc9a78a0b Mon Sep 17 00:00:00 2001 From: sungdark Date: Thu, 26 Feb 2026 12:13:24 +0000 Subject: [PATCH] docs: add Simplified Chinese docs for issue #4 bounty --- README.md | 1 + README.zh-CN.md | 40 ++++++++++++ docs/README.md | 2 + docs/README.zh-CN.md | 50 +++++++++++++++ scanner/README.md | 2 + scanner/README.zh-CN.md | 135 ++++++++++++++++++++++++++++++++++++++++ 6 files changed, 230 insertions(+) create mode 100644 README.zh-CN.md create mode 100644 docs/README.zh-CN.md create mode 100644 scanner/README.zh-CN.md diff --git a/README.md b/README.md index f37f44c2..6bce0956 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ $ISNAD applies this ancient wisdom to code provenance. ## Documentation - [Whitepaper](WHITEPAPER.md) — Full protocol specification +- [简体中文 README](README.zh-CN.md) — 中文版项目简介 ## Status diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 00000000..5c2db903 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,40 @@ +# $ISNAD + +**AI 代理互联网的信任层** + +一个面向智能体网络的 PoS（权益证明）审计协议。审计者质押代币为代码安全背书；若发现恶意代码会被罚没；干净代码则可获得收益。 + +## 问题 + +AI 代理会从不受信任来源安装技能（skills）。一个恶意技能就可能窃取凭据、外传数据或入侵系统。当前缺少统一、可验证的信任评估机制。 + +## 方案 + +**基于质押的审计机制：** +- 审计者质押 `$ISNAD` 为技能背书 +- 若后续发现恶意行为，质押会被罚没 +- 干净技能会给审计者带来收益 +- 用户安装前可先查看信任评分 + +## 词源 + +*Isnad*（إسناد）在阿拉伯语中意为“传承链/支持链”。在伊斯兰学术传统中，会通过传述链条验证圣训真伪：一句话是否可信，取决于传述者链条是否可靠。 + +`$ISNAD` 将这套古老而严谨的方法应用到代码溯源与可信度验证中。 + +## 文档 + +- [白皮书](WHITEPAPER.md) — 协议完整规范 + +## 当前状态 + +🚧 **草案阶段** — 上线前征求反馈中。 + +## 链接 + +- Moltbook: [moltbook.com/u/Rapi](https://moltbook.com/u/Rapi) +- X: [@0xRapi](https://x.com/0xRapi) + +--- + +*由 [Rapi](https://github.com/0xRapi) 构建 ⚡* diff --git a/docs/README.md b/docs/README.md index a3cf87c3..2b4f26aa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,8 @@ ISNAD (إسناد) is a decentralized trust layer for AI resources. This documen ## Quick Links +- **[简体中文文档总览](./README.zh-CN.md)** — 中文版入门与目录 + - **[What is ISNAD?](./what-is-isnad.md)** — Overview and core concepts - **[For Auditors](./auditors.md)** — How to stake and earn yield - **[Staking Guide](./staking.md)** — Step-by-step staking instructions diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md new file mode 100644 index 00000000..23426d7c --- /dev/null +++ b/docs/README.zh-CN.md @@ -0,0 +1,50 @@ +# ISNAD 文档 + +ISNAD（إسناد）是面向 AI 资源的去中心化信任层。本文档覆盖使用协议与参与贡献所需的核心信息。 + +## 快速入口 + +- **[什么是 ISNAD？](./what-is-isnad.md)** — 核心概念与整体介绍 +- **[给审计者](./auditors.md)** — 如何质押并获得收益 +- **[质押指南](./staking.md)** — 分步骤质押流程 +- **[陪审团机制](./jury.md)** — 惩罚（slashing）与申诉机制 +- **[API 参考](./api.md)** — REST API 文档 +- **[智能合约](./contracts.md)** — 链上架构说明 + +## 快速开始 + +### 查询信任评分 + +最简单的使用方式是先查询资源的信任分： + +```bash +# 通过 API +curl https://api.isnad.md/api/v1/trust/0x1234...abcd + +# 通过网页 +访问 https://isnad.md/check +``` + +### 成为审计者 + +1. 在 Base 网络准备 `$ISNAD` 代币 +2. 在 https://isnad.md/stake 连接钱包 +3. 审核目标资源的代码 +4. 质押代币并创建证明（attestation） +5. 锁定期结束后获得收益 + +## 信任等级 + +| 等级 | 最低质押 | 含义 | +|------|---------|------| +| UNVERIFIED | 0 | 暂无证明 | +| COMMUNITY | 100 $ISNAD | 已获得部分社区信任 | +| VERIFIED | 1,000 $ISNAD | 多位审计者参与且质押量较高 | +| TRUSTED | 10,000 $ISNAD | 经过大量审计，高置信度 | + +## 资源链接 + +- **官网：** https://isnad.md +- **API：** https://api.isnad.md +- **GitHub：** https://github.com/counterspec/isnad +- **X / Twitter：** https://x.com/isnad_protocol diff --git a/scanner/README.md b/scanner/README.md index 4c735c00..c593cdea 100644 --- a/scanner/README.md +++ b/scanner/README.md @@ -2,6 +2,8 @@ Detection oracle for the ISNAD trust protocol. Scans AI resources (skills, prompts, configs) for malicious patterns and submits flags to the on-chain oracle. +[简体中文版本](./README.zh-CN.md) + ## Installation ```bash diff --git a/scanner/README.zh-CN.md b/scanner/README.zh-CN.md new file mode 100644 index 00000000..e0c9e9de --- /dev/null +++ b/scanner/README.zh-CN.md @@ -0,0 +1,135 @@ +# ISNAD Scanner + +ISNAD 信任协议的检测预言机。用于扫描 AI 资源（skills、prompts、配置等）中的恶意模式，并将风险标记提交到链上预言机。 + +## 安装 + +```bash +cd scanner +npm install +npm run build +``` + +## 用法 + +### 扫描单个文件 + +```bash +# 基础扫描 +npm run scan -- scan ./path/to/skill.js + +# JSON 输出 +npm run scan -- scan ./path/to/skill.js --json + +# 指定自定义资源哈希 +npm run scan -- scan ./path/to/skill.js --hash 0x123... +``` + +### 扫描多个文件 + +```bash +# 扫描目录中的所有 JS 文件 +npm run scan -- batch "./skills/**/*.js" + +# 发现首个高风险即停止 +npm run scan -- batch "./skills/**/*.js" --fail-fast +``` + +### 生成证据 + +```bash +npm run scan -- evidence ./malicious-skill.js +``` + +### 向预言机提交标记 + +```bash +# 试运行（分析但不提交） +npm run scan -- flag ./malicious-skill.js --dry-run + +# 提交到测试网 +npm run scan -- flag ./malicious-skill.js --network testnet + +# 提交到主网 +npm run scan -- flag ./malicious-skill.js --network mainnet +``` + +### 作为服务运行 + +```bash +# 设置环境变量 +export ISNAD_PRIVATE_KEY=0x... +export ISNAD_AUTO_FLAG=false # 设为 true 可自动提交 + +# 启动服务 +npm start +``` + +## 环境变量 + +| 变量 | 说明 | 默认值 | +|------|------|--------| +| `ISNAD_PRIVATE_KEY` | 用于提交标记的私钥 | 必填 | +| `ISNAD_REGISTRY_ADDRESS` | Registry 合约地址 | Sepolia 默认 | +| `ISNAD_ORACLE_ADDRESS` | Oracle 合约地址 | Sepolia 默认 | +| `ISNAD_NETWORK` | `testnet` 或 `mainnet` | `testnet` | +| `ISNAD_AUTO_FLAG` | 是否自动提交标记 | `false` | +| `ISNAD_MIN_CONFIDENCE` | 自动标记的最小置信度 | `0.7` | + +## 检测模式 + +扫描器会检测以下风险： + +### Critical（严重） +- 动态代码执行（`eval`、`Function`） +- Shell 命令执行（`exec`、`spawn`） +- 子进程相关导入 +- VM 模块使用 +- 钥匙串/凭据存储访问 +- 系统目录写入 + +### High（高） +- 数据外传（webhook、base64 发送） +- 敏感文件读取（`.env`、`.ssh`、凭据文件） +- 原始套接字访问 +- 基于 DNS 的数据外传 +- 安全绕过尝试 +- 加密货币挖矿行为 + +### Medium（中） +- 环境变量访问 +- 递归目录读取 +- 用户主目录访问 +- 代码混淆模式 + +### Low（低） +- Unicode 转义序列 +- 轻度可疑模式 + +## API + +```typescript +import { analyzeContent, formatResult } from '@isnad/scanner'; + +const result = analyzeContent(code, resourceHash); +console.log(formatResult(result)); + +// 返回结果包含： +// - riskLevel: 'critical' | 'high' | 'medium' | 'low' | 'clean' +// - riskScore: number +// - confidence: 0-1 +// - findings: 命中模式详情 +``` + +## 合约地址 + +### Base Sepolia（测试网） +- Registry: `0x8340783A495BB4E5f2DF28eD3D3ABcD254aA1C93` +- Oracle: `0x4f1968413640bA2087Db65d4c37912d7CD598982` + +### Base Mainnet（主网） +- 即将上线 + +## 许可证 + +MIT