第八章：上下文与人类协作

// 来自 packages/interaction/user-approval/src/index.ts
class ApprovalService {
  /** 请求批准 */
  async request(options: ApprovalRequest): Promise<ApprovalResult> {
    // 1. 构建批准请求
    const request = {
      id: generateRequestId(),
      type: options.type,
      description: options.description,
      risk: options.risk,
      details: options.details
    }
    
    // 2. 发送事件
    ctx.emit('approval/request', request)
    
    // 3. 等待用户响应
    const result = await waitForApproval(request.id)
    
    return result
  }
}

interface ApprovalRequest {
  /** 请求 ID */
  id: string
  /** 请求类型 */
  type: 'tool-execution' | 'file-modification' | 'network-access' | 'process-spawn'
  /** 描述 */
  description: string
  /** 风险等级 */
  risk: 'low' | 'medium' | 'high' | 'critical'
  /** 详细信息 */
  details: Record<string, unknown>
}

interface ApprovalResult {
  /** 是否批准 */
  approved: boolean
  /** 用户选择 */
  choice: 'always' | 'once' | 'never'
  /** 备注 */
  note?: string
}

// 来自 packages/interaction/user-questions/src/index.ts
class UserQuestionService {
  /** 提问 */
  async ask(options: QuestionOptions): Promise<QuestionResult> {
    // 1. 构建问题
    const question = {
      id: generateQuestionId(),
      question: options.question,
      type: options.type,  // 'text' | 'choice' | 'confirm'
      options: options.choices
    }
    
    // 2. 发送事件
    ctx.emit('question/ask', question)
    
    // 3. 等待用户回答
    const answer = await waitForAnswer(question.id)
    
    return answer
  }
}

type QuestionType = 'text' | 'choice' | 'confirm'

interface QuestionOptions {
  /** 问题文本 */
  question: string
  /** 问题类型 */
  type: QuestionType
  /** 选择题选项 */
  choices?: string[]
  /** 默认值 */
  default?: string | boolean
}

// 来自 packages/sandbox/sandbox/src/escalation.ts
interface EscalationApprover {
  /** 请求权限提升 */
  request(options: EscalationRequest): Promise<EscalationResult>
}

interface EscalationRequest {
  /** 请求的权限 */
  permissions: string[]
  /** 原因 */
  reason: string
  /** 风险等级 */
  risk: 'low' | 'medium' | 'high'
}

interface EscalationResult {
  /** 是否批准 */
  approved: boolean
  /** 授予的权限 */
  granted: string[]
}

// 来自 packages/sandbox/sandbox-local/src/index.ts
class LocalSandboxProvider {
  /** 在沙箱中执行命令 */
  async confine(command: string, options: SandboxOptions): Promise<SandboxResult> {
    // 1. 解析命令
    const [cmd, ...args] = this.parseCommand(command)
    
    // 2. 应用限制
    const confinedArgs = this.applyRestrictions(args, options.restrictions)
    
    // 3. 执行
    const result = await this.subprocess.spawn(cmd, confinedArgs, {
      cwd: options.cwd,
      env: options.env,
      timeout: options.timeout
    })
    
    return result
  }
}

// 来自 packages/context/agent-instructions/src/index.ts
class AgentInstructionsService {
  /** 获取指令 */
  getInstructions(agentId: string): string {
    // 从配置或存储中获取 Agent 指令
    return this.instructions.get(agentId) ?? ''
  }
  
  /** 设置指令 */
  setInstructions(agentId: string, instructions: string): void {
    this.instructions.set(agentId, instructions)
  }
}

// 来自 packages/context/time-context/src/index.ts
class TimeContextService {
  /** 获取当前时间上下文 */
  getTimeContext(): TimeContext {
    return {
      now: new Date(),
      timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
      locale: Intl.DateTimeFormat().resolvedOptions().locale
    }
  }
}

// 来自 packages/context/references/src/index.ts
class ReferencesService {
  /** 添加引用 */
  addReference(reference: Reference): void {
    this.references.push(reference)
  }
  
  /** 获取所有引用 */
  getReferences(): Reference[] {
    return this.references
  }
}

interface Reference {
  /** 引用类型 */
  type: 'file' | 'url' | 'code' | 'document'
  /** 引用内容 */
  content: string
  /** 元数据 */
  metadata: Record<string, unknown>
}

// 来自 packages/guard/repeat-call-guard/src/index.ts
class RepeatCallGuard {
  private callHistory = new Map<string, number>()
  
  /** 检查是否重复调用 */
  check(toolName: string, params: Record<string, unknown>): GuardResult {
    const key = this.buildKey(toolName, params)
    const count = this.callHistory.get(key) ?? 0
    
    if (count >= this.maxRepeats) {
      return {
        allowed: false,
        reason: `Tool "${toolName}" has been called ${count} times with the same parameters`
      }
    }
    
    this.callHistory.set(key, count + 1)
    return { allowed: true }
  }
}

// 来自 packages/guard/tool-timeout-guard/src/index.ts
class ToolTimeoutGuard {
  /** 包装工具执行，添加超时 */
  async wrapExecution<T>(
    toolName: string,
    execution: () => Promise<T>,
    timeoutMs: number
  ): Promise<T> {
    return Promise.race([
      execution(),
      new Promise<never>((_, reject) => {
        setTimeout(() => {
          reject(new Error(`Tool "${toolName}" timed out after ${timeoutMs}ms`))
        }, timeoutMs)
      })
    ])
  }
}

interface Plan {
  /** Plan ID */
  id: string
  /** Plan 标题 */
  title: string
  /** Plan 步骤 */
  steps: PlanStep[]
  /** 当前状态 */
  status: 'draft' | 'active' | 'completed' | 'failed'
  /** 创建时间 */
  createdAt: Date
  /** 更新时间 */
  updatedAt: Date
}

interface PlanStep {
  /** 步骤 ID */
  id: string
  /** 步骤描述 */
  description: string
  /** 步骤状态 */
  status: 'pending' | 'in-progress' | 'completed' | 'failed'
  /** 依赖的步骤 */
  dependsOn?: string[]
}

// 创建 Plan
const plan = ctx.plan.create({
  title: '实现用户认证',
  steps: [
    { id: '1', description: '设计 API 接口' },
    { id: '2', description: '实现数据库模型', dependsOn: ['1'] },
    { id: '3', description: '实现认证逻辑', dependsOn: ['2'] },
    { id: '4', description: '编写测试', dependsOn: ['3'] }
  ]
})

// 更新步骤状态
ctx.plan.updateStep(plan.id, '1', { status: 'completed' })

// 获取当前计划
const currentPlan = ctx.plan.getCurrent()

# cordis.patch.yml
- id: user-approval
  config:
    # 审批模式
    mode: 'interactive'  # 'interactive' | 'auto-approve' | 'auto-deny'
    
    # 自动批准的工具列表
    autoApprove:
      - 'file_read'
      - 'bash'
    
    # 自动拒绝的工具列表
    autoDeny:
      - 'system_command'

# cordis.patch.yml
- id: guard
  config:
    # 重复调用限制
    repeatCall:
      maxRepeats: 3
    
    # 工具超时
    toolTimeout:
      defaultMs: 30000
      overrides:
        bash: 60000
        file_write: 10000