proxycast/AGENTS.md

AI Agent 指南

本文件为 AI Agent 在此代码库中工作时提供指导。

基本规则

1. 始终使用中文输出 - 所有回复、注释、文档都使用中文
2. 文件超过 20 行，分批输出 - 避免一次性输出过长内容
3. 先读后写 - 修改文件前必须先读取现有内容

详细文档

模块级详细文档位于 docs/aiprompts/：

文档	说明
overview.md	项目架构概览
providers.md	Provider 系统
credential-pool.md	凭证池管理
converter.md	协议转换
server.md	HTTP 服务器
flow-monitor.md	流量监控
components.md	组件系统
hooks.md	React Hooks
services.md	业务服务
commands.md	Tauri 命令
mcp.md	MCP 服务器
database.md	数据库层
terminal.md	内置终端
plugins.md	插件系统
lib.md	工具库

构建命令

# 构建 Tauri 应用
cd src-tauri && cargo build

# 构建前端
npm run build

# 开发模式
npm run tauri dev

测试命令

# 运行 Rust 测试
cd src-tauri && cargo test

# 运行前端测试
npm test

代码检查

# Rust 代码检查
cd src-tauri && cargo clippy

# 前端代码检查
npm run lint

项目架构

技术栈

• 前端：React + TypeScript + Vite + TailwindCSS
• 后端：Rust + Tauri
• 数据库：SQLite (rusqlite)

核心模块

1. Provider 系统 (src-tauri/src/providers/)

   • Kiro/CodeWhisperer OAuth 认证
   • Gemini OAuth 认证
   • Qwen OAuth 认证
   • Antigravity OAuth 认证
   • OpenAI/Claude API Key 认证

2. 凭证池管理 (src-tauri/src/services/provider_pool_service.rs)

   • 多凭证轮询负载均衡
   • 健康检查机制
   • Token 自动刷新

3. API 服务器 (src-tauri/src/server.rs)

   • OpenAI 兼容 API 端点
   • Claude 兼容 API 端点
   • 流式响应支持

4. 协议转换 (src-tauri/src/converter/)

   • OpenAI ↔ CodeWhisperer 转换
   • OpenAI ↔ Claude 转换

凭证管理策略（方案 B）

Kiro 凭证采用完全独立的副本策略：

• 上传凭证时，自动合并 clientIdHash 文件中的 client_id/client_secret 到副本
• 每个副本文件完全独立，支持多账号场景
• 刷新 Token 时只使用副本文件中的凭证，不依赖原始文件

开发指南

添加新 Provider

1. 在 src-tauri/src/providers/ 创建新的 provider 模块
2. 实现凭证加载、Token 刷新、API 调用方法
3. 在 CredentialData 枚举中添加新类型
4. 在 ProviderPoolService 中添加健康检查逻辑

修改凭证管理

• 凭证文件存储在 ~/Library/Application Support/proxycast/credentials/
• 数据库存储凭证元数据和状态
• Token 缓存在数据库中，避免频繁读取文件

调试技巧

• 日志输出使用 tracing 宏
• API 请求调试文件保存在 ~/.proxycast/logs/
• 使用 debug_kiro_credentials 命令调试凭证加载

文档维护

文档维护规范详见 .kiro/steering/doc-maintenance.md（Kiro 自动加载）。