Agent Skills 管理与实时状态展示功能

[detongz]

Cherry Studio 当前使用 @anthropic-ai/claude-agent-sdk@0.1.76。Anthropic 在 2025 年 10 月推出了 Agent Skills 功能，并在 SDK v0.2.6 中提供了完整支持。升级 SDK 并引入新功能可以大幅提升用户体验：

1. Skills 系统：允许用户创建和管理可复用的 agent 能力模块
2. 实时状态展示：让用户更直观地了解 agent 运行状态

目标

主要目标

1. 升级 Claude Agent SDK 从 0.1.76 到 0.2.6，获取最新的 Skills 支持和状态字段
2. 实现 Skills 管理功能：用户可以可视化地创建、编辑、启用/禁用 skills
3. 实现实时状态展示：Context 使用率、Thinking Block、Background Tasks 面板

成功指标

• 用户可以通过 UI 创建和管理 .claude/skills/ 目录中的 skills
• 用户可以在输入框上方看到实时的 Context 使用率
• 用户可以在消息流中看到可折叠的 Thinking Block
• 用户可以通过底部浮窗查看和管理后台任务

功能需求

1. SDK 升级 (Phase 1)

描述: 升级 @anthropic-ai/claude-agent-sdk 到 v0.2.6

技术细节:

• 更新 package.json 中的依赖版本
• 更新 patch 文件 patches/@anthropic-ai__claude-agent-sdk@0.2.6.patch
• 确认现有 fork 模式 patch 仍然兼容

验收标准:

• 现有 agent 功能正常工作
• 会话恢复功能正常

2. Skills 管理功能 (Phase 2-4)

2.1 Skills 类型定义

描述: 创建 Skills 相关的 TypeScript 类型

数据结构:

interface Skill {
  id: string           // 目录名
  name: string         // 从 frontmatter 解析
  description: string  // 从 frontmatter 解析
  path: string         // 完整路径
  type: 'builtin' | 'custom'
  enabled: boolean
  frontmatter: SkillFrontmatter
}

interface SkillFrontmatter {
  name: string
  description: string
  user_invocable?: boolean
  allowed_tools?: string[]
  agent?: string
  context?: 'fork' | 'inherit'
}

2.2 Skills 服务层

描述: 创建 SkillsService 处理 skills 的 CRUD 操作

API:

• listSkills(projectPath: string): Promise<Skill[]>
• getSkill(skillPath: string): Promise<Skill>
• createSkill(skill: Partial<Skill>): Promise<Skill>
• updateSkill(skill: Skill): Promise<Skill>
• deleteSkill(skillId: string): Promise<void>
• parseSkillFrontmatter(content: string): SkillFrontmatter
• generateSkillTemplate(type: string): string

2.3 Skills 设置 UI

描述: 在 Agent 设置中添加 Skills 管理页面

功能:

• 左侧 Skills 列表（显示 name、description、enabled 状态）
• 搜索/过滤功能
• "新建 Skill" 和 "导入模板" 按钮
• 右侧 Skill 编辑器（支持 YAML frontmatter 和 Markdown 内容）
• 启用/禁用开关

模板系统:

• 内置模板: 代码审查、文档生成、测试生成等基础模板
• 社区模板导入: 支持从 GitHub URL 或本地文件导入
  • 参考 Claude Code Templates
  • 支持 hackathon、podcast 等社区模板

3. 实时状态展示 (Phase 5)

3.1 Context 使用率组件

描述: 在输入框上方显示 Context 使用情况

功能:

• 进度条显示已用/总 token 数
• 百分比数值显示
• 颜色编码:
  • 绿色 < 70%
  • 黄色 70-90%
  • 红色 >= 90%

位置: 集成到 src/renderer/src/pages/home/Inputbar/ 区域

3.2 Thinking Block 查看器

描述: 在消息流中显示 Claude 的推理过程

功能:

• 解析 reasoning-start、reasoning-delta、reasoning-end 事件
• 可折叠显示
• 语法高亮
• 复制功能

位置: 在消息流中渲染（src/renderer/src/pages/home/Messages/）

3.3 Background Tasks 面板

描述: 底部浮窗显示后台任务状态

功能:

• 收起状态: 显示任务数量和图标
• 展开状态: 任务列表（状态、进度、取消按钮）
• 使用 framer-motion 实现展开/收起动画
• 任务完成通知

位置: 固定在屏幕底部

技术架构

新增文件

src/renderer/src/
├── types/
│   └── skill.ts                          # Skills 类型定义
├── pages/settings/AgentSettings/
│   └── SkillsSettings.tsx                # Skills 设置页面
├── components/Agent/
│   ├── SkillEditor.tsx                   # Skill 编辑器
│   ├── ContextUsageIndicator.tsx         # Context 使用率组件
│   ├── ThinkingBlockViewer.tsx           # Thinking Block 查看器
│   └── BackgroundTasksPanel.tsx          # 后台任务面板
└── store/
    └── skills.ts                          # Skills Redux store

src/main/services/agents/services/skills/
└── SkillsService.ts                       # Skills 服务层

修改文件

src/renderer/src/
├── types/agent.ts                         # 扩展 Agent 类型
├── pages/settings/AgentSettings/
│   └── AgentSettingsPopup.tsx            # 添加 Skills 菜单项
└── locales/
    ├── zh-CN/agent.json                   # 中文翻译
    └── en-US/agent.json                   # 英文翻译

src/main/
├── services/agents/services/claudecode/
│   ├── index.ts                           # 更新 SDK Options
│   └── transform.ts                       # 扩展事件处理
└── apiServer/routes/agents/               # 添加 Skills API 路由

实施计划

第一批: 基础设施

• SDK 升级
• 类型定义
• 服务层
• API 路由

第二批: Skills 管理 UI

• SkillsSettings 页面
• Skill 编辑器
• 集成到设置弹窗

第三批: 实时状态展示

• Context 使用率组件
• Thinking Block 查看器
• Background Tasks 面板

第四批: 完善与测试

• Redux 集成
• 国际化
• 测试

非功能性需求

性能

• Skills 列表加载时间 < 500ms
• 实时状态更新延迟 < 100ms

兼容性

• 向后兼容现有 agent 配置
• Skills 目录不存在时降级处理

安全性

• 只扫描 .claude/skills/ 和 ~/.claude/skills/ 目录
• 导入的模板需要验证来源

参考

• Agent Skills - Claude Docs
• Equipping agents for the real world with Agent Skills
• Claude Code Templates

---

标签: enhancement, agents, sdk-upgrade
优先级: Medium