# sisyphus-debatewiki-plugin 实现指南

## 1. 开发环境设置

### 1.1 依赖安装
```bash
# 安装TypeScript
npm install -g typescript

# 安装项目依赖
npm install

# 初始化TypeScript配置
npx tsc --init
```

### 1.2 项目结构
```
sisyphus-debatewiki-plugin/
├── src/
│   ├── agents/           # 智能体实现
│   │   ├── forum-agent.ts
│   │   ├── consensus-agent.ts
│   │   ├── wiki-agent.ts
│   │   └── grounded-theory-agent.ts
│   ├── tools/            # 工具实现
│   │   ├── debate-tools.ts
│   │   ├── consensus-tools.ts
│   │   ├── wiki-tools.ts
│   │   └── gt-tools.ts
│   ├── hooks/            # Hook实现
│   │   ├── debate-hooks.ts
│   │   ├── consensus-hooks.ts
│   │   ├── wiki-hooks.ts
│   │   └── gt-hooks.ts
│   ├── utils/            # 工具函数
│   │   ├── types.ts
│   │   └── helpers.ts
│   └── index.ts          # 主入口点
├── docs/                 # 文档
├── tests/                # 测试
├── package.json
├── tsconfig.json
└── README.md
```

## 2. 智能体开发指南

### 2.1 智能体开发原则
1. **单一职责**: 每个智能体只负责一个特定领域
2. **无状态**: 智能体不应维护内部状态
3. **幂等性**: 相同输入应产生相同输出
4. **错误处理**: 智能体应妥善处理错误情况

### 2.2 论坛智能体实现示例
```typescript
// src/agents/forum-agent.ts
import { sisyphus_task } from 'oh-my-opencode';

export interface ForumAgentOptions {
  agents?: string[];
  flows?: string[];
}

export interface DebateSession {
  id: string;
  topic: string;
  participants: string[];
  flow_type: string;
  phase: number;
  messages: Message[];
  created_at: Date;
  updated_at: Date;
  completed?: boolean;
}

export interface Message {
  agent_name: string;
  content: string;
  timestamp: Date;
}

/**
 * 启动辩论会话
 * 使用Sisyphus编排机制委托给专业智能体
 */
export async function startDebate(
  topic: string,
  participants: string[],
  flowType: string = 'free_debate',
  options?: ForumAgentOptions
): Promise<DebateSession> {
  // 通过sisyphus_task委托给专门的论坛智能体
  const result = await sisyphus_task({
    agent: "forum-engine",
    prompt: `Start a ${flowType} debate on topic: "${topic}" with participants: [${participants.join(', ')}]`,
    skills: ["forum-operations", "session-management", "message-aggregation"],
    run_in_background: false
  });

  return result.session as DebateSession;
}

/**
 * 执行辩论阶段
 */
export async function executePhase(
  sessionId: string,
  phaseNumber: number
): Promise<any> {
  const result = await sisyphus_task({
    agent: "forum-engine",
    prompt: `Execute phase ${phaseNumber} for debate session: ${sessionId}`,
    skills: ["phase-execution", "message-aggregation"],
    run_in_background: false
  });

  return result.phase_result;
}

/**
 * 添加消息到辩论会话
 */
export async function addMessage(
  sessionId: string,
  agentName: string,
  content: string
): Promise<void> {
  await sisyphus_task({
    agent: "forum-engine",
    prompt: `Add message from ${agentName} to session ${sessionId}: "${content}"`,
    skills: ["message-aggregation"],
    run_in_background: false
  });
}

/**
 * 获取辩论会话的所有消息
 */
export async function getMessages(sessionId: string): Promise<Message[]> {
  const result = await sisyphus_task({
    agent: "forum-engine",
    prompt: `Get all messages for debate session: ${sessionId}`,
    skills: ["message-aggregation"],
    run_in_background: false
  });

  return result.messages as Message[];
}

/**
 * 完成辩论会话
 */
export async function completeSession(sessionId: string): Promise<void> {
  await sisyphus_task({
    agent: "forum-engine",
    prompt: `Complete debate session: ${sessionId}`,
    skills: ["session-management"],
    run_in_background: false
  });
}
```

### 2.3 共识智能体实现示例
```typescript
// src/agents/consensus-agent.ts
import { sisyphus_task } from 'oh-my-opencode';

export interface ConsensusResult {
  achieved: boolean;
  agreement_ratio: number;
  summary: string;
  votes?: Record<string, boolean>;
}

export interface Message {
  agent_name: string;
  content: string;
  timestamp: Date;
}

/**
 * 计算投票共识
 */
export async function calculateVotingConsensus(
  messages: Message[],
  threshold: number = 0.7
): Promise<ConsensusResult> {
  const result = await sisyphus_task({
    agent: "consensus-engine",
    prompt: `Calculate voting consensus with threshold ${threshold} for messages: ${JSON.stringify(messages)}`,
    skills: ["voting-algorithm", "consensus-calculation"],
    run_in_background: false
  });

  return result.consensus as ConsensusResult;
}

/**
 * 计算审议共识
 */
export async function calculateDeliberationConsensus(
  messages: Message[],
  maxRounds: number = 10,
  convergenceThreshold: number = 0.85
): Promise<ConsensusResult> {
  const result = await sisyphus_task({
    agent: "consensus-engine",
    prompt: `Calculate deliberation consensus with max ${maxRounds} rounds and convergence threshold ${convergenceThreshold} for messages: ${JSON.stringify(messages)}`,
    skills: ["deliberation-algorithm", "consensus-calculation"],
    run_in_background: false
  });

  return result.consensus as ConsensusResult;
}

/**
 * 计算加权共识
 */
export async function calculateWeightedConsensus(
  messages: Message[],
  weights: Record<string, number> = {},
  threshold: number = 0.65
): Promise<ConsensusResult> {
  const result = await sisyphus_task({
    agent: "consensus-engine",
    prompt: `Calculate weighted consensus with threshold ${threshold} and weights ${JSON.stringify(weights)} for messages: ${JSON.stringify(messages)}`,
    skills: ["weighted-algorithm", "consensus-calculation"],
    run_in_background: false
  });

  return result.consensus as ConsensusResult;
}

/**
 * 提取投票
 */
export async function extractVotes(messages: Message[]): Promise<Record<string, boolean>> {
  const result = await sisyphus_task({
    agent: "consensus-engine",
    prompt: `Extract votes from messages: ${JSON.stringify(messages)}`,
    skills: ["vote-extraction", "consensus-calculation"],
    run_in_background: false
  });

  return result.votes as Record<string, boolean>;
}
```

## 3. 工具开发指南

### 3.1 工具开发原则
1. **可重用性**: 工具应设计为可重用
2. **无副作用**: 工具应避免不必要的副作用
3. **错误处理**: 工具应妥善处理错误
4. **性能**: 工具应高效执行

### 3.2 工具实现示例
```typescript
// src/tools/wiki-tools.ts
import { Tool } from 'oh-my-opencode';

export interface WikiPage {
  id: string;
  title: string;
  content: string;
  author: string;
  version: number;
  versions: WikiVersion[];
  created_at: Date;
  updated_at: Date;
  status: 'draft' | 'pending_review' | 'approved' | 'published';
}

export interface WikiVersion {
  version_number: number;
  content: string;
  author: string;
  timestamp: Date;
  changelog?: string;
}

// 创建维基页面工具
export class CreatePageTool implements Tool {
  name = "create_wiki_page";
  description = "Create a new wiki page with the specified title and content";
  
  async execute(params: { title: string; content: string; author: string }): Promise<WikiPage> {
    // 通过sisyphus_task委托给维基智能体
    const result = await sisyphus_task({
      agent: "wiki-engine",
      prompt: `Create a new wiki page titled "${params.title}" with content: "${params.content}", author: "${params.author}"`,
      skills: ["wiki-operations", "page-management"],
      run_in_background: false
    });
    
    return result.page as WikiPage;
  }
}

// 更新维基页面工具
export class UpdatePageTool implements Tool {
  name = "update_wiki_page";
  description = "Update an existing wiki page with new content";
  
  async execute(params: { page_id: string; content: string; author: string; changelog?: string }): Promise<WikiPage> {
    const result = await sisyphus_task({
      agent: "wiki-engine",
      prompt: `Update wiki page ${params.page_id} with new content: "${params.content}", author: "${params.author}", changelog: "${params.changelog || 'Updated content'}"`,
      skills: ["wiki-operations", "page-management", "version-control"],
      run_in_background: false
    });
    
    return result.page as WikiPage;
  }
}

// 获取维基页面工具
export class GetPageTool implements Tool {
  name = "get_wiki_page";
  description = "Get a wiki page by its ID";
  
  async execute(params: { page_id: string }): Promise<WikiPage> {
    const result = await sisyphus_task({
      agent: "wiki-engine",
      prompt: `Get wiki page with ID: ${params.page_id}`,
      skills: ["wiki-operations", "page-management"],
      run_in_background: false
    });
    
    return result.page as WikiPage;
  }
}
```

## 4. Hook开发指南

### 4.1 Hook开发原则
1. **事件驱动**: Hook应响应特定事件
2. **异步处理**: Hook应异步执行
3. **错误隔离**: Hook错误不应影响主流程
4. **性能考虑**: Hook应快速执行

### 4.2 Hook实现示例
```typescript
// src/hooks/wiki-hooks.ts
import { Hook } from 'oh-my-opencode';
import { WikiPage } from '../agents/wiki-agent';

// 页面创建Hook
export class PageCreatedHook implements Hook {
  event = "wiki.page_created";
  
  async handler(payload: { page: WikiPage }) {
    console.log(`[WikiHook] Page created: ${payload.page.title}`);
    
    // 可以在这里执行额外的处理逻辑
    // 例如：发送通知、更新索引、记录日志等
    await this.notifySubscribers(payload.page);
    await this.updateSearchIndex(payload.page);
  }
  
  private async notifySubscribers(page: WikiPage) {
    // 实现订阅者通知逻辑
    console.log(`[WikiHook] Notifying subscribers about new page: ${page.title}`);
  }
  
  private async updateSearchIndex(page: WikiPage) {
    // 实现搜索索引更新逻辑
    console.log(`[WikiHook] Updating search index for page: ${page.title}`);
  }
}

// 页面更新Hook
export class PageUpdatedHook implements Hook {
  event = "wiki.page_updated";
  
  async handler(payload: { page: WikiPage; previous_version: WikiPage }) {
    console.log(`[WikiHook] Page updated: ${payload.page.title}`);
    
    // 执行页面更新后的处理逻辑
    await this.recordChange(payload.page, payload.previous_version);
    await this.triggerReviewIfNeeded(payload.page);
  }
  
  private async recordChange(current: WikiPage, previous: WikiPage) {
    // 记录变更历史
    console.log(`[WikiHook] Recording change for page: ${current.title}`);
  }
  
  private async triggerReviewIfNeeded(page: WikiPage) {
    // 如果需要，触发审核流程
    if (page.status === 'draft') {
      console.log(`[WikiHook] Triggering review for page: ${page.title}`);
    }
  }
}
```

## 5. 测试指南

### 5.1 单元测试
```typescript
// tests/agents/forum-agent.test.ts
import { startDebate, addMessage, getMessages } from '../../src/agents/forum-agent';

describe('Forum Agent', () => {
  describe('startDebate', () => {
    it('should start a new debate session', async () => {
      const session = await startDebate(
        'AI Ethics',
        ['proponent', 'opponent', 'moderator'],
        'free_debate'
      );
      
      expect(session).toBeDefined();
      expect(session.topic).toBe('AI Ethics');
      expect(session.participants).toContain('proponent');
      expect(session.flow_type).toBe('free_debate');
    });
  });
  
  describe('addMessage and getMessages', () => {
    it('should add and retrieve messages', async () => {
      const session = await startDebate(
        'Test Topic',
        ['agent1', 'agent2'],
        'free_debate'
      );
      
      await addMessage(session.id, 'agent1', 'Test message');
      
      const messages = await getMessages(session.id);
      expect(messages).toHaveLength(1);
      expect(messages[0].agent_name).toBe('agent1');
      expect(messages[0].content).toBe('Test message');
    });
  });
});
```

### 5.2 集成测试
```typescript
// tests/integration/sisyphus-workflow.test.ts
import { sisyphus_task } from 'oh-my-opencode';

describe('Sisyphus Workflow Integration', () => {
  it('should delegate tasks to specialized agents', async () => {
    // 测试论坛智能体任务委托
    const debateResult = await sisyphus_task({
      agent: "forum-engine",
      prompt: "Start a debate on AI safety",
      skills: ["forum-operations"],
      run_in_background: false
    });
    
    expect(debateResult).toBeDefined();
    
    // 测试共识智能体任务委托
    const consensusResult = await sisyphus_task({
      agent: "consensus-engine",
      prompt: "Calculate consensus from mock messages",
      skills: ["consensus-calculation"],
      run_in_background: false
    });
    
    expect(consensusResult).toBeDefined();
    
    // 测试维基智能体任务委托
    const wikiResult = await sisyphus_task({
      agent: "wiki-engine",
      prompt: "Create a wiki page about the debate",
      skills: ["wiki-operations"],
      run_in_background: false
    });
    
    expect(wikiResult).toBeDefined();
  });
});
```

## 6. 部署指南

### 6.1 构建项目
```bash
# 构建TypeScript代码
npm run build

# 打包项目
npm pack
```

### 6.2 发布到npm
```bash
# 登录npm
npm login

# 发布包
npm publish
```

### 6.3 安装插件
```bash
# 全局安装
npm install -g sisyphus-debatewiki

# 或在项目中安装
npm install sisyphus-debatewiki
```

## 7. 最佳实践

### 7.1 智能体设计最佳实践
1. **明确职责**: 每个智能体应有明确的职责边界
2. **简洁接口**: 智能体接口应简洁明了
3. **错误处理**: 智能体应妥善处理各种错误情况
4. **性能考虑**: 智能体应高效执行，避免阻塞

### 7.2 Sisyphus Task最佳实践
1. **明确意图**: 任务描述应清晰明确
2. **适当技能**: 指定适当的技能集合
3. **合理超时**: 设置合理的超时时间
4. **后台执行**: 对于长时间任务使用后台执行

### 7.3 工具开发最佳实践
1. **单一功能**: 每个工具应只做一件事
2. **可组合性**: 工具应易于组合使用
3. **错误恢复**: 工具应能从错误中恢复
4. **性能优化**: 工具应高效执行

### 7.4 Hook开发最佳实践
1. **快速执行**: Hook应快速执行，避免长时间操作
2. **错误隔离**: Hook错误不应影响主流程
3. **异步处理**: 使用异步处理避免阻塞
4. **事件明确**: 事件名称应清晰明确