From 7cae9936374410a2063f8230254e1d1c08f71d89 Mon Sep 17 00:00:00 2001
From: sungdark <sungdark@users.noreply.github.com>
Date: Thu, 26 Feb 2026 20:43:25 +0000
Subject: [PATCH] docs: add Simplified Chinese docs for
 README/getting-started/scanner

---
 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..bec368a8 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.zh-CN.md) — 中文版项目简介
 
 ## Status
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 00000000..379afaac
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,40 @@
+# $ISNAD
+
+**AI 智能体的信任层**
+
+一个面向智能体互联网的权益证明（Proof-of-Stake）审计协议。审计员通过质押代币为代码安全背书；发现恶意代码会触发罚没；干净代码则为审计员带来收益。
+
+## 问题
+
+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..efc5bf33 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,7 @@
 # ISNAD Documentation
 
+[中文文档入口](./README.zh-CN.md)
+
 ISNAD (إسناد) is a decentralized trust layer for AI resources. This documentation covers everything you need to know about using and contributing to the protocol.
 
 ## Quick Links
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
new file mode 100644
index 00000000..e975b449
--- /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)** — 罚没与申诉机制
+- **[API 参考](./api.md)** — REST API 文档
+- **[智能合约](./contracts.md)** — 链上架构说明
+
+## 快速开始
+
+### 查看信任分数
+
+使用 ISNAD 最简单的方式，就是先查看某个资源的信任分数：
+
+```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
+- **Twitter：** https://x.com/isnad_protocol
diff --git a/scanner/README.md b/scanner/README.md
index 4c735c00..7cc2c5a1 100644
--- a/scanner/README.md
+++ b/scanner/README.md
@@ -1,5 +1,7 @@
 # ISNAD Scanner
 
+[中文文档](./README.zh-CN.md)
+
 Detection oracle for the ISNAD trust protocol. Scans AI resources (skills, prompts, configs) for malicious patterns and submits flags to the on-chain oracle.
 
 ## Installation
diff --git a/scanner/README.zh-CN.md b/scanner/README.zh-CN.md
new file mode 100644
index 00000000..fa82e720
--- /dev/null
+++ b/scanner/README.zh-CN.md
@@ -0,0 +1,135 @@
+# ISNAD Scanner
+
+ISNAD 信任协议的检测预言机（Detection Oracle）。用于扫描 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
+# Dry run（仅分析不提交）
+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` |
+
+## 检测模式
+
+Scanner 可检测以下风险：
+
+### Critical（严重）
+- 动态代码执行（`eval`、`Function`）
+- Shell 命令执行（`exec`、`spawn`）
+- `child_process` 导入
+- `vm` 模块使用
+- 钥匙串/凭证存储访问
+- 系统目录写入
+
+### High（高）
+- 数据外传（webhook、base64 发送）
+- 敏感文件读取（`.env`、`.ssh`、凭证）
+- 原始 socket 访问
+- 基于 DNS 的外传
+- 安全绕过尝试
+- 加密货币挖矿
+
+### Medium（中）
+- 环境变量访问
+- 递归目录读取
+- Home 目录访问
+- 混淆代码模式
+
+### 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