Claude Code Plugin v1.0.0

AstrBot 的 Claude Code 双 Agent 系统插件。

系统架构

┌─────────────────────────────────────────────┐
│  用户 (微信/QQ/WebChat)                      │
│  "帮我写一个登录页面"  /  "y" (放行)         │
└─────────────┬───────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────┐
│  AstrBot (管理者 Agent)                       │
│  · 会话管理 (创建/切换/恢复/删除)             │
│  · 问题转发 (AskUserQuestion → 用户)         │
│  · 命令审批 (拦截危险命令 → 用户决定放行)     │
│  · 流式进度推送 (实时更新)                    │
│  · 超时控制                                  │
└─────────────┬───────────────────────────────┘
              │ asyncio.create_subprocess_exec
              ▼
┌─────────────────────────────────────────────┐
│  Claude Code (执行者 Agent)                   │
│  · 代码编写 / 调试 / 重构                     │
│  · 文件读写 / Shell 命令                      │
│  · AskUserQuestion 向用户提问                 │
│  · 流式输出 (stream-json 格式)               │
│  · 工具调用 (Bash, Read, Write, etc.)        │
└─────────────────────────────────────────────┘

通信流程

Claude Code (stream-json) ──→ StreamProcessor (chunk 解析)
    ├── text chunk → TextContent → AstrBot ChainManager (逐段推送)
    ├── thinking chunk → ThinkingContent → 暂存，等待 text
    ├── tool_use chunk → ToolUseContent → 工具调用通知
    ├── result chunk → ExecutionResult → 最终结果
    └── AskUserQuestion → 本地自动审批 / 转发用户

核心功能

• 双 Agent 协作: AstrBot 管理 + Claude Code 执行，职责分离
• 流式通信: Claude Code 流式输出实时推送到聊天平台（Thinking/ToolUse/Text 分段展示）
• 实时问答: Claude Code 提问时，AstrBot 转发给用户，等待真实回复
• 命令审批: 危险命令被拦截后，用户可选择放行或拒绝
• 自动审批: 本地会话自动放行 AskUserQuestion（可配置）
• 多轮对话: 支持上下文保持的多轮交互
• 会话管理: 创建、切换、恢复、删除会话
• 自动审查: 12 条内置安全规则，拦截高危命令
• Markdown 简述: 每个会话维护一份描述文件

LLM 工具

claude_code

执行 Claude Code 任务。支持多轮对话、实时问答、命令审批和会话选择。

触发条件： 用户要求写代码、改代码、修bug、重构、实现功能、创建项目、读写文件、执行Shell命令等编程任务。

不触发： 闲聊、简单问答、非编程任务、1-2行代码片段直接回复即可。

参数:

• task (string): 任务描述，传入用户的原始请求
• session_id (string, 可选): 指定会话 UUID 以续接特定会话

会话选择逻辑:

1. 新任务：直接 claude_code(task=...)，不传 session_id
2. 续接旧任务：先调 load_session_descriptions 获取列表，再 claude_code(task=..., session_id="UUID")
3. session_id 必须是标准UUID格式（如 dd313f2a-7227-4cae-a61e-faadadd3a427）

错误码处理：

错误码	含义	建议回复用户
CC-001	会话不存在	检查会话ID，或建议创建新任务
CC-003	命令被拦截	命令被安全规则阻止
CC-004	执行超时	任务太复杂，建议拆分
CC-005	CLI未安装	联系管理员安装
CC-006	API Key未配置	联系管理员配置
CC-007	提问轮数超限	需求不够明确，建议重新描述
CC-009	进程异常	稍后重试

load_session_descriptions

加载所有 Claude Code 历史会话列表。当用户想查看历史任务、选择续接某个任务时调用。

触发条件： 用户说"继续之前的任务"、"上次的工作"、"有哪些任务在跑"、"查看历史会话"。

不触发： 用户要开始全新编程任务（直接调 claude_code）；用户已提供 session_id。

完整工作流程：

1. 调用 load_session_descriptions → 获取会话列表
2. 根据用户意图选择会话，提取 Session ID
3. 调用 claude_code(task=..., session_id=...) 执行任务
4. 调用 unload_session_descriptions 释放上下文

unload_session_descriptions

卸载会话简述，释放上下文窗口空间。在 load_session_descriptions 之后必须调用的配对清理操作。

用户命令

命令	说明
/claude_sessions	列出所有会话
/claude_switch N	切换到第 N 个会话
/claude_delete N	删除第 N 个会话
/claude_review	查看命令审查日志
/claude_rules	查看禁止命令规则
/claude_update	更新 Claude Code CLI

交互模式

问答模式 (AskUserQuestion)

当 Claude Code 需要用户输入时：

💬 **Claude Code 需要你的输入**

你想用什么框架？React、Vue 还是原生？

请直接回复你的答案。

用户直接回复即可，无需任何命令前缀。

命令审批模式

当检测到危险命令时：

⚠️ **命令安全审查**

Claude Code 想执行以下命令：
`Bash: rm -rf /tmp/test`

该命令已被安全规则拦截。
回复 **y/是/允许/放行** 放行，其他内容拒绝。

错误码参考

错误码	含义	处理方式
CC-001	会话不存在	创建新会话
CC-003	命令被拦截	用户可选择放行
CC-004	执行超时	简化任务或增加超时
CC-005	CLI 未安装	运行 /claude_update
CC-006	API Key 未配置	在设置中填写 API Key
CC-007	超过最大提问轮数	简化任务要求
CC-009	进程异常退出	检查日志

配置参数

配置	默认值	说明
workspace_root	workspace	工作目录
api_key	(空)	Anthropic API Key
api_base_url	(空)	API 基础地址
model	(空)	模型名称
permission_mode	acceptEdits	权限模式
max_turns	30	单次最大执行轮数
timeout_seconds	600	超时时间（秒）
question_timeout_seconds	300	问答等待超时（秒）
approval_timeout_seconds	120	命令审批等待超时（秒）
enable_interactive_mode	true	启用多轮对话
max_question_rounds	10	最大提问轮数
session_expire_days	36135	会话过期天数
session_description_max_chars	200	会话简述最大字数
auto_review_enabled	true	启用自动审查
enable_streaming	true	启用流式通信
streaming_text_debounce_sec	0.5	流式文本推送间隔（秒）
streaming_max_queue	100	流式队列最大长度
streaming_max_text_length	2000	单次推送最大文本长度
auto_approve_local	true	本地会话自动审批问答

安全审查规则

插件自动拦截以下高危命令：

• rm -rf / — 删除根目录
• mkfs — 格式化磁盘
• curl|bash — 远程脚本执行
• drop database — 删除数据库
• chmod 777 / — 根目录全开
• dd if=/dev/zero — 磁盘覆写
• :(){:|:&};: — Fork 炸弹
• shutdown/reboot — 系统关机
• systemctl stop — 停止服务
• kill -9 1 — 杀死 init 进程
• 其他共 12 条安全规则

被拦截的命令会发送审批请求，用户可选择放行或拒绝。

快速开始

1. 安装插件到 AstrBot 的 plugins 目录
2. 在 AstrBot 设置中配置 API Key（可选）
3. 使用 /claude_update 命令安装 Claude Code CLI
4. 开始使用：发送"帮我写一个登录页面"等编程任务

依赖要求

• AstrBot v2.0+
• Python 3.10+
• Claude Code CLI（自动安装）
• Anthropic API Key（可选，可使用系统级配置）

许可证

本项目基于 MIT 许可证开源。