使用说明

项目简介

Cangjie Magic 是一个基于 Cangjie 语言开发的 Agent 应用框架，旨在帮助开发者快速构建具备智能和创造力的应用程序。它通过领域特定语言 (DSL) 简化了 Agent 的定义和能力扩展，并且可以将 Agent 部署为 MCP (Model Context Protocol) 服务器，对外提供标准化的上下文服务。

主要功能点

Agent DSL: 使用简洁的 DSL 定义 Agent 角色和行为，例如示例中的 'BlackCatAssistant'。
Prompt 模板: 通过 '@prompt' 注解声明 Prompt 模板，方便定制 Agent 与大语言模型的交互方式。
工具集成: 支持集成外部功能作为 Agent 的工具 (Tools)，例如示例中提到的 "文件管理助手，接入开源 MCP 工具" 和 "Wiki Search 工具" ( 'external_scripts/wiki_search_impl.py' )。
资源管理: 框架具备资源 (Resources) 管理能力，虽然文档中没有详细展开，但从 MCP 服务器的定义来看，这是其应有的功能。
MCP 服务器: 可以将定义的 Agent 实例作为 MCP 服务器运行 (如 'src/examples/mcp_server' 示例所示)，通过 JSON-RPC 协议与客户端通信，提供上下文服务。

安装步骤

安装 Cangjie SDK: 根据仓库 'README.md' 的指示，安装兼容的 Cangjie SDK 版本 (推荐 0.56.4 或 0.53.18/4)。

创建 Cangjie 项目: 使用 Cangjie 包管理器 'cjpm' 初始化一个新的项目：

cjpm init my_agent_app
cd my_agent_app

添加 CangjieMagic 依赖: 修改项目根目录下的 'cjpm.toml' 文件，添加对 CangjieMagic 的依赖。推荐使用 Git 依赖：

[dependencies]
  magic = { git = "https://gitcode.com/Cangjie-TPC/CangjieMagic.git", branch = "dev" }

编写 Agent 代码: 在 'main.cj' 或其他 '.cj' 文件中编写 Agent 代码，可以参考 'README.md' 或 'src/examples' 目录下的示例。

运行 Agent: 使用 'cjpm run' 命令运行 Agent 应用。例如，运行 'README.md' 中的示例：

cjpm run --name my_agent_app

要运行 'mcp_server' 示例，可以使用：

cjpm run --name magic.examples.mcp_server

服务器配置 (MCP Client 配置)

当 Cangjie Magic Agent 作为 MCP 服务器运行时，MCP 客户端需要配置连接信息。以下是连接 'src/examples/mcp_server' 示例的 MCP 服务器配置示例：

{
  "serverName": "CangjieMagicServer",
  "command": "cjpm",
  "args": [
    "run",
    "--name",
    "magic.examples.mcp_server"
  ],
  "description": "Cangjie Magic Agent MCP Server Example",
  "protocol": "json-rpc",
  "transport": "stdio"
}

配置参数说明:

'serverName': 自定义的服务器名称，用于在客户端标识不同的 MCP 服务器连接。
'command': 启动 MCP 服务器的命令，这里使用 'cjpm' (Cangjie 包管理器)。
'args': 传递给 'cjpm' 命令的参数，用于指定要运行的 Cangjie 包名，这里指向 'magic.examples.mcp_server' 示例。请确保此包名与您实际运行的 MCP 服务器程序包名一致。
'description': 对该服务器连接的简要描述，方便客户端用户识别。
'protocol': MCP 通信协议，Cangjie Magic 框架很可能使用 'json-rpc'。
'transport': MCP 服务器使用的传输方式，'stdio' 表示标准输入输出流，是常用的简单传输方式。请根据 Cangjie Magic 实际的 MCP 服务器实现选择合适的传输方式，例如 'websocket' 或 'sse' (Server-Sent Events)，如果适用。

基本使用方法

启动 MCP 服务器: 在 Cangjie Magic 项目中，运行 'mcp_server' 示例或其他您自定义的 Agent 服务器程序。服务器将开始监听 MCP 客户端的请求。
配置 MCP 客户端: 在您的 MCP 客户端应用中，根据上述 "服务器配置" 示例，配置连接到 Cangjie Magic MCP 服务器。
客户端与服务器交互: MCP 客户端通过 JSON-RPC 协议向 Cangjie Magic MCP 服务器发送请求，例如请求资源信息、调用已注册的工具或获取 Prompt 模板。具体的请求格式和 API 请参考 Cangjie Magic 框架的 API 手册以及 MCP 协议规范。

关键词