@f2a/network 0.1.2 → 0.2.0

package/docs/reputation-guide.md

@@ -1,396 +0,0 @@
-# F2A 信誉系统用户指南
-
-信誉系统是 F2A 网络的核心组件，用于评估和管理 Agent 节点的可信度。通过信誉分，网络可以自动调节节点的权限、优先级和资源分配。
-
-## 目录
-
-- [快速开始](#快速开始)
-- [信誉分基础](#信誉分基础)
-- [信誉等级与权限](#信誉等级与权限)
-- [信誉分变化规则](#信誉分变化规则)
-- [评审机制](#评审机制)
-- [安全机制](#安全机制)
-- [自治经济](#自治经济)
-- [API 参考](#api-参考)
-- [常见问题](#常见问题)
-
-## 快速开始
-
-### 查看节点信誉
-
-```typescript
-import { F2A } from 'f2a-network';
-
-const f2a = await F2A.create({ displayName: 'My Agent' });
-await f2a.start();
-
-// 查看某节点的信誉信息
-const reputation = f2a.reputationManager.getReputation('12D3KooW...');
-console.log(reputation);
-// {
-//   peerId: '12D3KooW...',
-//   score: 75,
-//   tier: 'contributor',
-//   tasksCompleted: 42,
-//   tasksFailed: 3,
-//   lastUpdated: 1709846400000
-// }
-```
-
-### 获取高信誉节点
-
-```typescript
-// 获取信誉分 >= 60 的节点
-const trustedNodes = f2a.reputationManager.getHighReputationNodes(60);
-console.log(`找到 ${trustedNodes.length} 个高信誉节点`);
-```
-
-## 信誉分基础
-
-### 分数范围
-
-- **范围**: 0-100
-- **初始值**: 70（新节点加入时）
-- **更新频率**: 每次任务完成后实时更新
-
-### 分数影响因素
-
-| 因素 | 影响 |
-|------|------|
-| 任务成功完成 | +信誉分 |
-| 任务失败 | -信誉分 |
-| 任务拒绝 | -信誉分（较少） |
-| 评审参与 | +信誉分 |
-| 恶意行为 | 大幅 -信誉分 |
-
-## 信誉等级与权限
-
-### 等级划分
-
-| 分数范围 | 等级 | 英文名 | 说明 |
-|---------|------|--------|------|
-| 0-20 | 受限者 | Restricted | 权限受限，需要提升信誉 |
-| 20-40 | 新手 | Novice | 基础权限，积累信誉中 |
-| 40-60 | 参与者 | Participant | 标准权限，可参与评审 |
-| 60-80 | 贡献者 | Contributor | 高级权限，享受发布折扣 |
-| 80-100 | 核心成员 | Core | 最高权限，最大折扣 |
-
-### 权限对照表
-
-| 权限 | 受限者 | 新手 | 参与者 | 贡献者 | 核心成员 |
-|------|:------:|:----:|:------:|:------:|:--------:|
-| 发布任务请求 | ❌ | ✅ | ✅ | ✅ | ✅ |
-| 执行任务 | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 参与评审 | ❌ | ❌ | ✅ | ✅ | ✅ |
-| 发布折扣 | - | 100% | 100% | 90% | 70% |
-| 优先执行权 | 低 | 低 | 中 | 高 | 最高 |
-
-### 检查权限
-
-```typescript
-// 检查节点是否有发布权限
-const canPublish = f2a.reputationManager.hasPermission(
-  '12D3KooW...',
-  'publish'
-);
-
-// 检查节点是否可以参与评审
-const canReview = f2a.reputationManager.hasPermission(
-  '12D3KooW...',
-  'review'
-);
-```
-
-## 信誉分变化规则
-
-### 任务成功
-
-```typescript
-// 记录任务成功
-f2a.reputationManager.recordSuccess(
-  '12D3KooW...',  // peerId
-  'task-uuid',    // taskId
-  10              // delta (可选，默认根据难度计算)
-);
-```
-
-**加分规则**:
-- 基础加分: +5 ~ +15 分
-- 高难度任务: 额外加成
-- 快速完成: 额外加成
-- 高质量结果: 评审加分
-
-### 任务失败
-
-```typescript
-// 记录任务失败
-f2a.reputationManager.recordFailure(
-  '12D3KooW...',
-  'task-uuid',
-  'Timeout exceeded',  // 失败原因
-  15                   // delta (可选)
-);
-```
-
-**扣分规则**:
-- 基础扣分: -10 ~ -20 分
-- 无故失败: 更大扣分
-- 重复失败: 累进扣分
-
-### 任务拒绝
-
-```typescript
-// 记录任务拒绝
-f2a.reputationManager.recordRejection(
-  '12D3KooW...',
-  'task-uuid',
-  'Capability not supported',
-  5  // delta (可选，通常比失败少)
-);
-```
-
-**扣分规则**:
-- 合理拒绝: -2 ~ -5 分
-- 无理由拒绝: -10 分
-- 频繁拒绝: 额外惩罚
-
-## 评审机制
-
-评审机制确保任务评价的公平性，避免单点操纵。
-
-### 网络规模与评审人数
-
-| 网络规模 | 评审人数 | 机制 |
-|---------|---------|------|
-| 3-10 节点 | 1 | 固定 1 人评审 |
-| 10-50 节点 | 3 | 去掉最高最低，取平均 |
-| 50+ 节点 | 5-7 | 完整评审机制 + 偏离检测 |
-
-### 评审流程
-
-```
-任务完成
-    │
-    ▼
-┌─────────────┐
-│ 请求者评价   │ ── 初步评分
-└─────────────┘
-    │
-    ▼
-┌─────────────┐
-│ 评审委员会   │ ── 独立评审
-└─────────────┘
-    │
-    ▼
-┌─────────────┐
-│ 综合计算     │ ── 最终信誉分
-└─────────────┘
-```
-
-### 参与评审
-
-只有信誉分 >= 40 的节点才能参与评审：
-
-```typescript
-// 检查是否有评审资格
-if (f2a.reputationManager.hasPermission(peerId, 'review')) {
-  // 可以参与评审
-}
-```
-
-### 评审奖励
-
-参与评审可以获得信誉奖励：
-
-- 完成评审: +2 分
-- 高质量评审（与最终结果一致）: +5 分
-- 发现问题或风险: +10 分
-
-## 安全机制
-
-### Phase 3 安全特性
-
-#### 1. 邀请制加入
-
-新节点需要现有成员邀请才能加入网络：
-
-```typescript
-// 邀请新节点
-f2a.reputationManager.invitePeer(
-  '12D3KooW...',  // 新节点 peerId
-  '12D3KooX...'   // 邀请人 peerId
-);
-```
-
-邀请人担保规则：
-- 被邀请人信誉良好，邀请人获得奖励
-- 被邀请人恶意行为，邀请人连带惩罚
-
-#### 2. 挑战机制
-
-验证节点的真实能力：
-
-```typescript
-// 发起挑战
-const challenge = await f2a.reputationManager.challengePeer(
-  '12D3KooW...',
-  'code-generation'  // 能力类型
-);
-```
-
-挑战失败后果：
-- 第一次失败: 警告，扣 10 分
-- 重复失败: 禁用该能力声明
-- 恶意欺骗: 大幅扣分或封禁
-
-#### 3. 签名信誉事件
-
-所有信誉事件都有签名，防止篡改：
-
-```typescript
-// 信誉事件结构
-interface ReputationEvent {
-  id: string;
-  type: 'success' | 'failure' | 'rejection';
-  peerId: string;
-  taskId: string;
-  delta: number;
-  timestamp: number;
-  signature: string;  // 防篡改签名
-}
-```
-
-## 自治经济
-
-### Phase 4: 信誉消耗与激励
-
-信誉不仅是评分，也是一种"货币"：
-
-#### 发布任务消耗
-
-```typescript
-// 计算发布折扣
-const discount = f2a.reputationManager.getPublishDiscount('12D3KooW...');
-
-// 核心成员只需消耗 70% 信誉
-// 新手需要消耗 100% 信誉
-```
-
-#### 执行任务奖励
-
-```typescript
-// 获取执行优先级
-const priority = f2a.reputationManager.getPublishPriority('12D3KooW...');
-
-// 高信誉节点优先获得任务
-// 完成后获得更多奖励
-```
-
-#### 信誉流转
-
-```
-┌──────────┐    发布任务    ┌──────────┐
-│ 请求者    │ ──────────────▶│ 任务池   │
-│ (消耗信誉) │               │          │
-└──────────┘                └──────────┘
-                                 │
-                                 │ 分配
-                                 ▼
-┌──────────┐    完成任务    ┌──────────┐
-│ 执行者    │ ◀──────────────│ 任务池   │
-│ (获得信誉) │               │          │
-└──────────┘                └──────────┘
-```
-
-## API 参考
-
-### ReputationManager
-
-```typescript
-class ReputationManager {
-  // 查询
-  getReputation(peerId: string): ReputationInfo;
-  getTier(score: number): ReputationTier;
-  hasPermission(peerId: string, permission: Permission): boolean;
-  getHighReputationNodes(minScore?: number): ReputationInfo[];
-  
-  // 发布相关
-  getPublishPriority(peerId: string): number;
-  getPublishDiscount(peerId: string): number;
-  
-  // 记录
-  recordSuccess(peerId: string, taskId: string, delta?: number): void;
-  recordFailure(peerId: string, taskId: string, reason?: string, delta?: number): void;
-  recordRejection(peerId: string, taskId: string, reason?: string, delta?: number): void;
-  
-  // 安全
-  invitePeer(newPeerId: string, inviterPeerId: string): void;
-  challengePeer(peerId: string, capability: string): Promise<ChallengeResult>;
-}
-```
-
-### 类型定义
-
-```typescript
-interface ReputationInfo {
-  peerId: string;
-  score: number;
-  tier: ReputationTier;
-  tasksCompleted: number;
-  tasksFailed: number;
-  tasksRejected: number;
-  lastUpdated: number;
-}
-
-type ReputationTier = 
-  | 'restricted'  // 0-20
-  | 'novice'      // 20-40
-  | 'participant' // 40-60
-  | 'contributor' // 60-80
-  | 'core';       // 80-100
-
-type Permission = 'publish' | 'execute' | 'review';
-```
-
-## 常见问题
-
-### Q: 新节点初始信誉是多少？
-
-A: 新节点初始信誉为 70 分，属于"参与者"等级。这允许新节点立即参与大部分网络活动。
-
-### Q: 信誉分会过期吗？
-
-A: 长期不活跃的节点信誉分会缓慢下降，鼓励持续参与。下降速率：每天 -0.1 分（不活跃超过 30 天后）。
-
-### Q: 如何从"受限者"等级恢复？
-
-A: 需要成功完成任务来提升信誉。建议：
-1. 执行简单任务积累信誉
-2. 避免拒绝或失败任务
-3. 寻求高信誉节点的邀请奖励
-
-### Q: 评审如何保证公平？
-
-A: 评审机制设计：
-1. 多人评审，避免单点操纵
-2. 去掉最高最低分，减少极端影响
-3. 评审记录公开透明
-4. 恶意评审会被惩罚
-
-### Q: 信誉分可以转让吗？
-
-A: 不可以。信誉分与节点绑定，不可转让，防止信誉交易和操纵。
-
-### Q: 如何处理恶意节点？
-
-A: 多层防护：
-1. 低信誉节点权限受限
-2. 挑战机制验证能力
-3. 黑名单机制封禁
-4. 邀请人连带责任
-
-## 相关文档
-
-- [RFC-001: 去中心化信誉系统](./rfcs/001-reputation-system.md) - 详细技术设计
-- [中间件使用指南](./middleware-guide.md) - 安全过滤与消息处理
-- [安全设计](./security-design.md) - 整体安全架构