conda activate ccserver
uv pip install -r requirements.txt
export ANTHROPIC_API_KEY=your_key

# 后端 API 服务（HTTP / SSE / WebSocket）
python server.py

# 终端直连模式（不经过 server.py，直接调用 Agent）
python tui.py

# Gradio 图形界面
python clients/gui.py

# HTTP 终端界面（用于测试接口）
python clients/tui_http.py

用户输入
  → 构建 messages 列表（含历史）
  → 调用 Anthropic API（messages + tools + system）
  → stop_reason == "tool_use"  → 执行工具 → 追加 tool_result → 继续
  → stop_reason == "end_turn"  → 输出文本 → 等待下一轮用户输入

ccserver/                   # 项目根目录
├── server.py               # 后端服务（HTTP / SSE / WebSocket）
├── tui.py                  # 终端直连模式（无需 server.py）
├── clients/
│   ├── gui.py              # Gradio 图形界面（需先启动 server.py）
│   └── tui_http.py         # HTTP 终端界面（需先启动 server.py）
├── Justfile                # 常用命令（just api / tui / gui / tui-http）
├── requirements.txt        # 依赖声明
└── ccserver/               # 源码包
    ├── main.py             # AgentRunner 公共入口
    ├── agent.py            # Agent 和 AgentContext 核心
    ├── session.py          # Session、TaskManager、SkillLoader
    ├── factory.py          # AgentFactory
    ├── config.py           # 全局配置
    ├── compactor.py        # 对话压缩
    ├── log.py              # 日志配置
    ├── model/              # 模型适配器（ModelAdapter / AnthropicAdapter）
    ├── prompts_lib/        # 提示词拼接库（多 lib 支持）
    │   ├── base.py         # PromptLib 基类
    │   ├── adapter.py      # 自动扫描注册入口
    │   └── cc_reverse/     # cc_reverse 系列实现
    ├── tools/              # 内置工具集
    ├── core/emitter/       # 事件发射器（TUI / SSE / WebSocket）
    ├── hooks/              # Hook 系统（生命周期拦截）
    ├── mcp/                # MCP 客户端管理
    ├── storage/            # 存储适配器
    └── pipeline/           # Pipeline Graph 执行引擎

消息列表 → LLM 调用 → 收集响应 → 检查 stop_reason
  → tool_use：执行工具 → 追加结果 → 继续循环
  → 其他（end_turn）：提取文本 → 返回

sessions/
└── {session_id}/
    ├── workdir/            # 代理操作的沙箱目录
    ├── messages.jsonl      # 消息历史（一行一条）
    └── transcripts/        # 压缩前的完整对话存档

from prompts_lib.base import PromptLib

class MyLibV100(PromptLib):

    def build_system(self, session, model, language, cch="",
                     injected_system=None, append_system=True, is_spawn=False) -> list:
        """
        构建 system prompt，返回传给 Anthropic API 的 content block 列表。
        - session: 当前会话对象
        - model: 使用的模型名
        - language: 响应语言
        - cch: 平台标识（如 "vscode"）
        - injected_system: 外部注入的 system 文本（来自 CCSERVER_SYSTEM_FILE）
        - append_system: True=追加到末尾，False=替换默认 system
        - is_spawn: 是否为子代理
        """
        return [{"type": "text", "text": "你是一个助手。"}]

    def build_user_message(self, text, session, context) -> list:
        """
        包装每条 user 消息，结果直接作为 message["content"]。
        context 字段：
        - is_first: 是否为本会话第一条用户消息
        - skills_override: None=使用全局 skills，[]= 无 skill，[str]=指定名称列表
        - hook_context: UserPromptSubmit hook 附加的上下文文本
        """
        return [{"type": "text", "text": text}]

    def build_compact_messages(self, summary, transcript_ref) -> list:
        """
        压缩完成后写回 history 的消息格式，需返回 [user消息, assistant消息]。
        - summary: LLM 生成的对话摘要
        - transcript_ref: 存档文件路径（供溯源）
        """
        return [
            {"role": "user",      "content": f"[摘要]\n{summary}"},
            {"role": "assistant", "content": "已了解，继续。"},
        ]

    def build_skill_catalog(self, skills) -> str:
        """
        将 skill 元数据列表格式化为注入消息的目录文本。
        skills 每项含 name / description / location 字段。
        返回空字符串表示不注入。
        """
        return "\n".join(f"- {s['name']}: {s['description']}" for s in skills)

    def build_command_message(self, cmd_info, session, history) -> list:
        """
        将 /command 调用包装为 content block 列表。
        cmd_info 字段：name / args / stdout / body
        """
        return [{"type": "text", "text": f"/{cmd_info['name']} {cmd_info.get('args', '')}"}]

    def patch_tool_schemas(self, schemas) -> list:
        """
        对工具 schema 列表做后处理，可替换工具描述文本。
        schemas 每项含 name / description / input_schema 字段。
        返回修改后的列表。
        """
        return schemas

{
  "lib_id": "my_lib:v1.0.0",
  "class": "MyLibV100"
}

CCSERVER_PROMPT_LIB=my_lib:v1.0.0 python server.py

POST   /sessions                    创建会话（可指定 session_id）
GET    /sessions                    列出所有会话
GET    /sessions/{session_id}       获取会话元数据

POST   /chat                        阻塞式请求，返回完整响应
GET    /chat/stream                 SSE 流式响应
WS     /chat/ws/{session_id}        WebSocket 双向通信

POST /chat
X-Session-Id: <session_id>

{"message": "帮我写一个 hello world"}

{"type": "token",       "content": "部分文本"}
{"type": "tool_start",  "tool": "Bash", "preview": "ls -la"}
{"type": "tool_result", "tool": "Bash", "output": "..."}
{"type": "done",        "content": "完整最终文本"}
{"type": "error",       "message": "错误信息"}

python tui.py
# 或
just tui

---
name: my-skill
description: 技能的简要描述
tags: [tag1, tag2]
---

# 技能内容

详细的技能说明和使用方式...

.ccserver/
├── agents/             # 自定义 subagent 定义（*.md，格式同 Claude Code agents）
├── skills/             # 技能文档（每个子目录含 SKILL.md）
├── hooks/              # 生命周期钩子脚本（HOOK.md 目录格式，兼容 CC settings.json hooks）
├── commands/           # 自定义斜杠命令（*.md）
├── settings.json       # 权限设置（allowed_tools / denied_tools 等）
└── settings.local.json # 本地覆盖（gitignore，优先级高于 settings.json）

graph TD
    subgraph API["API 层"]
        HTTP["HTTP Request"]
    end

    subgraph GRAPH["Graph（节点调度）"]
        direction LR
        subgraph NA["Node A"]
            LA["Agent 主循环"]
        end
        subgraph NB["Node B"]
            LB["Agent 主循环"]
        end
        subgraph NC["Node C"]
            LC["Agent 主循环"]
        end
        NA --> NB --> NC
        NC -->|"条件回边"| NB
    end

    subgraph AgentLoop["Agent 主循环"]
        LLM["Claude LLM"]
        subgraph AgentCap["能力"]
            BuiltinTools["内置工具\nBash / Read / Write / Grep ..."]
            MCPTools["MCP 工具\n(通过 .mcp.json 注册)"]
            SubAgent["子 Agent\n(.ccserver/agents/*.md)"]
        end
    end

    subgraph MCPProcess["MCP Servers（独立进程）"]
        MCP1["server A"]
        MCP2["server B"]
    end

    HTTP --> GRAPH
    HTTP --> AgentLoop
    MCPTools <-->|stdio JSON-RPC| MCPProcess
    SubAgent -->|递归| AgentLoop

anthropic>=0.40.0          # Anthropic API 客户端
fastapi>=0.115.0           # HTTP / SSE / WebSocket 服务端
uvicorn[standard]>=0.32.0  # ASGI 服务器
pydantic>=2.0.0            # 数据校验
loguru>=0.7.0              # 日志
python-dotenv>=0.21.0      # .env 文件加载
httpx>=0.24.0              # HTTP 客户端（WebFetch 工具 / clients/）
html2text>=2020.1.16       # HTML 转 Markdown（WebFetch 工具）

mcp       # MCP 工具支持
gradio    # clients/gui.py 图形界面
motor     # MongoDB 存储后端（异步驱动）
pymongo   # MongoDB 存储后端
redis     # Redis 缓存（配合 MongoDB 使用）

playground/
├── agents/                         # 独立 Agent 示例（可作为 subagent 复用）
│   ├── web_search/                 # 联网搜索 Agent
│   │   ├── web-search.md           # Agent system prompt
│   │   └── .mcp.json               # MCP 工具配置（search_web / search_news / get_weather）
│   ├── roleplay_agent/             # 角色扮演对话编排 Agent（经典版）
│   │   ├── roleplay_instruct.md    # Agent system prompt
│   │   └── .mcp.json               # MCP 工具配置（chat model 调用）
│   ├── roleplay_agent_neo/         # 角色扮演对话编排 Agent（新版，使用 hook 注入 conversation_id）
│   │   ├── roleplay_instruct.md    # Agent system prompt
│   │   ├── .mcp.json               # MCP 工具配置
│   │   ├── .ccserver/
│   │   │   ├── settings.local.json # 权限与 hooks 配置
│   │   │   └── hooks/              # UserPromptSubmit hook 脚本
│   │   │       └── get_conversation_id.py
│   │   └── mcp_servers/            # 内置 MCP 服务端
│   ├── quality_check/              # 对话质量检测 Agent
│   │   └── quality-check.md        # Agent system prompt
│   └── topic_suggest/              # 话题建议 Agent
│       └── topic-suggest.md        # Agent system prompt
└── graphs/                         # Graph 编排示例（多 Agent 协作）
    └── simple_roleplay_graph/      # 角色扮演对话 Graph
        ├── graph.py                # Graph 定义（节点 + 边）
        ├── nodes.py                # 节点实现
        ├── server.py               # 自定义 API 入口
        ├── gui.py                  # Gradio 界面
        ├── db.py                   # 会话数据库
        └── README.md               # 执行流程图

CCSERVER_PROJECT_DIR=/path/to/playground/agents/roleplay_agent_neo python server.py