counterspec · dagangtj · Feb 26, 2026
diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md
@@ -0,0 +1,19 @@
+# ISNAD 中文文档
+
+欢迎阅读 ISNAD 协议的中文文档。
+
+## 目录
+
+- [什么是 ISNAD](./what-is-isnad.md) — 协议概述与核心概念
+- [成为审计员](./auditors.md) — 质押代币、审计资源、赚取收益
+- [扫描器使用指南](./scanner.md) — CLI 工具使用说明
+
+## 快速链接
+
+- [官网](https://isnad.md)
+- [GitHub](https://github.com/counterspec/isnad)
+- [白皮书](../../WHITEPAPER.md)
+
+---
+
+*翻译由社区贡献*
diff --git a/docs/zh-CN/auditors.md b/docs/zh-CN/auditors.md
@@ -0,0 +1,103 @@
+# 成为审计员
+
+审计员通过质押 $ISNAD 代币为资源安全性背书，并通过准确的认证赚取收益。
+
+## 要求
+
+- **$ISNAD 代币**（Base 网络）
+- **钱包**已连接（MetaMask、Coinbase Wallet 等）
+- **技术能力**评估代码安全性
+- **愿意锁定**代币 7-90 天
+
+## 运作方式
+
+### 1. 审查资源
+质押前，彻底审查资源：
+- 阅读所有源代码
+- 检查恶意模式（数据外泄、未授权执行）
+- 验证外部 API 调用
+- 审查权限请求和能力要求
+- 审计依赖项
+
+### 2. 质押代币
+选择金额和锁定期限：
+- 质押越多 = 对信任分数贡献越大
+- 锁定越久 = 收益倍数越高
+
+### 3. 创建认证
+你的质押被记录在链上，为资源的信任分数做出贡献。
+
+### 4. 等待锁定期
+代币被锁定。如果资源被举报并发现是恶意的，你可能被罚没。
+
+### 5. 领取奖励
+锁定期结束后，从奖励池提取质押本金 + 赚取的收益。
+
+## 收益潜力
+
+收益基于以下因素计算：
+
+| 因素 | 影响 |
+|------|------|
+| 质押金额 | 代币越多 = 基础收益越高 |
+| 锁定期限 | 锁定越久 = 倍数越高 |
+| 池子 APY | 当前约 10% 基础（可通过治理调整） |
+
+### 锁定倍数
+
+| 期限 | 倍数 |
+|------|------|
+| 7 天 | 1.0x |
+| 30 天 | 1.0x |
+| 60 天 | 1.25x |
+| 90 天 | 1.5x |
+| 180 天 | 2.0x |
+| 365 天 | 3.0x |
+
+### 计算示例
+
+```
+1,000 $ISNAD 质押 90 天，APY 10%：
+→ 基础收益：1000 × 0.10 × (90/365) = 24.66 $ISNAD
+→ 1.5x 倍数后：36.99 $ISNAD
+```
+
+## 风险
+
+### 罚没
+如果你认证的资源被发现是恶意的，**你的全部质押将被销毁**。这是 ISNAD 运作的核心机制——审计员必须承担风险。
+
+### 锁定期
+代币在锁定期结束前无法提取。请选择你能接受的期限。
+
+### 智能合约风险
+与所有 DeFi 协议一样，存在固有的智能合约风险。合约已经过审计，但漏洞始终可能存在。
+
+## 最佳实践
+
+1. **只为你审查过的代码质押** — 不要仅凭声誉质押
+2. **从小额开始** — 先用小额质押积累经验
+3. **分散投资** — 不要把所有质押放在一个资源上
+4. **保持关注** — 监控被举报的资源以防申诉
+5. **记录审查** — 保留你审计内容的笔记
+
+## 什么会被罚没
+
+可能导致罚没的资源行为：
+
+- **数据外泄** — 向外部发送凭证、个人身份信息或敏感数据
+- **未授权执行** — 在声明范围外运行命令
+- **行为操纵** — 恶意改变智能体行为
+- **供应链攻击** — 被入侵的依赖项
+- **虚假陈述** — 元数据声称安全但代码行为不符
+
+## 开始使用
+
+1. 访问 https://isnad.md/stake
+2. 连接你的钱包
+3. 搜索你已审查的资源
+4. 设置质押金额和锁定期限
+5. 授权代币支出
+6. 创建你的认证
+
+详细步骤请参阅[质押指南](./staking.md)。
diff --git a/docs/zh-CN/scanner.md b/docs/zh-CN/scanner.md
@@ -0,0 +1,135 @@
+# ISNAD 扫描器
+
+ISNAD 信任协议的检测预言机。扫描 AI 资源（技能、提示词、配置）中的恶意模式，并向链上预言机提交举报。
+
+## 安装
+
+```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 主网
+- 即将推出
+
+## 许可证
+
+MIT
diff --git a/docs/zh-CN/what-is-isnad.md b/docs/zh-CN/what-is-isnad.md
@@ -0,0 +1,99 @@
+# 什么是 ISNAD？
+
+ISNAD（إسناد）是一个权益证明（Proof-of-Stake）认证协议，为 AI 资源创建信任层。其名称源自伊斯兰学术传统中的 *isnad*（传述链）——用于验证圣训真实性的传承链条。一句话的可信度取决于其传述者链条的可靠性。
+
+## 问题背景
+
+AI 智能体越来越依赖来自不可信来源的共享资源：
+- **技能（Skills）** — 可执行代码包、工具、API 集成
+- **配置（Configs）** — 智能体配置、网关设置
+- **提示词（Prompts）** — 系统提示词、人设、行为指令
+- **记忆（Memory）** — 知识库、RAG 文档
+- **模型（Models）** — 微调模型、LoRA、适配器
+
+单个被入侵的资源可能导致：
+- 窃取凭证和敏感数据
+- 执行未授权命令
+- 操纵智能体行为
+- 危及整个系统
+
+现有方案无法规模化：
+- **人工代码审查** — 大多数智能体无法审计
+- **中心化审批** — 单点故障，成为瓶颈
+- **信誉评分** — 容易被操纵，新作者难以起步
+- **沙箱隔离** — 不完整，许多资源需要真实权限
+
+## 解决方案
+
+ISNAD 通过经济激励创建市场定价的信任信号：
+
+1. **资源被铭刻**到 Base L2 链上，包含内容和元数据
+2. **审计员质押 $ISNAD 代币**为资源安全性背书
+3. **质押被锁定**一段时间（7-90 天）
+4. **如发现恶意**，陪审团审查后质押被罚没（销毁）
+5. **如确认安全**，审计员从奖励池获得收益
+
+### 为什么有效
+
+- **利益绑定** — 审计员承担真实风险。虚假认证会销毁代币。
+- **自我筛选专业性** — 只有有信心的审计员才会质押。市场自动筛选能力。
+- **永久可验证** — 一切上链。无需信任外部基础设施。
+- **抗攻击** — 女巫攻击需要资本。串谋会销毁所有串谋者的质押。
+
+## 链上铭刻
+
+与需要固定服务的 IPFS 方案不同，ISNAD 直接将资源铭刻到 Base L2 calldata：
+
+- **约 $0.01/KB** 铭刻成本
+- **永久**链上存储
+- **零**外部依赖
+
+资源使用 SHA-256 哈希进行内容寻址，确保完整性验证始终可行。
+
+## 核心概念
+
+### 信任分数（Trust Score）
+资源上的加权质押总额。质押越高 = 经济支持越多 = 信任度越高。
+
+### 信任等级（Trust Tier）
+基于信任分数的分类：
+- **UNVERIFIED（未验证）** — 无认证
+- **COMMUNITY（社区级）** — ≥100 $ISNAD 质押
+- **VERIFIED（已验证）** — ≥1,000 $ISNAD 质押
+- **TRUSTED（可信任）** — ≥10,000 $ISNAD 质押
+
+### 认证（Attestation）
+当审计员为资源质押时，创建包含以下信息的认证：
+- 质押金额
+- 锁定期限
+- 资源哈希
+- 审计员地址
+
+### 罚没（Slashing）
+如果资源被发现是恶意的：
+1. 任何人都可以举报（需 100 $ISNAD 押金）
+2. 随机选择 5 名审计员组成陪审团
+3. 陪审团投票（需 67% 绝对多数）
+4. 如判定有罪：该资源上的所有质押被销毁
+5. 举报者取回押金并获得奖励
+
+## 协议架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      ISNAD 协议                              │
+├──────────────┬──────────────┬──────────────┬───────────────┤
+│  ISNADToken  │ ISNADRegistry│ ISNADStaking │  ISNADOracle  │
+│  (ERC20 +    │  (铭刻 +     │  (质押 +     │  (举报 +      │
+│   投票)      │   元数据)    │   认证)      │   陪审团)     │
+├──────────────┴──────────────┴──────────────┴───────────────┤
+│  ISNADRewardPool            │        ISNADGovernor         │
+│  (收益分配)                 │        (DAO + 时间锁)        │
+└─────────────────────────────┴──────────────────────────────┘
+```
+
+## 下一步
+
+- [成为审计员](./auditors.md) — 开始质押并赚取收益
+- [质押指南](./staking.md) — 详细操作步骤
+- [集成指南](./integration.md) — 为你的智能体添加信任检查