# https://github.com/chonlim92/claude-code-project-template 项目说明书
生成时间：2026-06-01 03:19:51 UTC
## 目录
- [项目介绍](#page-introduction)
- [快速入门指南](#page-quick-start)
- [系统架构](#page-architecture)
- [项目目录结构](#page-project-structure)
- [Python智能体开发](#page-python-agents)
- [聊天智能体开发](#page-chat-agents)
- [技能开发](#page-skills)
- [MCP服务器配置](#page-mcp-servers)
- [CLI自动化工具](#page-cli-automation)
- [Python自动化管道](#page-python-pipeline)
## 项目介绍
### 相关页面
相关主题：[快速入门指南](#page-quick-start), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
- [CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
- [config/hello_world.yaml](https://github.com/chonlim92/claude-code-project-template/blob/main/config/hello_world.yaml)
- [config/sum_numbers.yaml](https://github.com/chonlim92/claude-code-project-template/blob/main/config/sum_numbers.yaml)
- [mcp/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/mcp/README.md)
- [agents/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/README.md)
- [config/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/config/README.md)
- [tools/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/tools/README.md)
- [agents/hello_world.py](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/hello_world.py)
- [requirements.txt](https://github.com/chonlim92/claude-code-project-template/blob/main/requirements.txt)
# 项目介绍
## 概述
Claude Code Project Template 是一个多智能体（Multi-Agent）项目模板，专为使用 VS Code Copilot 聊天机器人和基于 Python 的自动化场景而设计。该项目集成了 MCP（Model Context Protocol）服务器和 CLI 工具，可用于访问数据库和 API 服务。
资料来源：[README.md:1-3](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
## 项目目的与范围
### 核心目标
| 目标 | 说明 |
|------|------|
| 多智能体协作 | 支持 Python Agent 和 Chat Agent 两种类型的智能体协同工作 |
| MCP 协议集成 | 提供标准化的 Model Context Protocol 服务器实现 |
| CLI 工具支持 | 包含可独立运行或被智能体调用的命令行工具 |
| 数据库与 API 访问 | 通过 MCP 服务器安全地连接外部服务 |
资料来源：[CLAUDE.md:1-4](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
### 技术栈要求
| 组件 | 版本要求 |
|------|----------|
| Python | 3.10+ |
| VS Code | 需安装 GitHub Copilot 扩展 |
| Node.js | Claude Code CLI 需要 v18+ |
| npm | 用于安装 Claude Code CLI |
资料来源：[README.md:19-20](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
## 系统架构
### 目录结构
```
├── agents/ # Python 智能体脚本（运行时实现）
├── .claude/agents/ # 聊天智能体（.agent.md 用于 VS Code Copilot）
├── .claude/skills/ # 技能定义（按需工作流）
├── mcp/ # MCP 服务器实现
├── tools/ # CLI 工具和独立脚本
├── config/ # 环境配置和连接设置
├── docs/ # 项目文档
└── tests/ # 测试套件
```
资料来源：[README.md:9-17](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
### 架构流程图
```mermaid
graph TD
A[用户/开发者] --> B[Claude Code CLI]
B --> C[Chat Agent
.claude/agents/]
B --> D[Python Agent
agents/]
C --> E[Skills
.claude/skills/]
D --> F[MCP Server
mcp/server.py]
F --> G[External Services
数据库/API/GitHub]
D --> H[CLI Tools
tools/]
```
## 智能体类型
本项目支持两种类型的智能体系统。
资料来源：[AGENTS.md:11-12](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
### Python 智能体
Python 智能体是可执行的 Python 脚本，用于独立任务、CI 流水线以及 MCP 集成。
| 属性 | 说明 |
|------|------|
| 文件位置 | `agents/` 目录 |
| 配置文件 | `config/.yaml` |
| 运行方式 | 终端执行：`python agents/.py [args]` |
| 配置格式 | YAML 格式 |
资料来源：[AGENTS.md:14-18](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
**示例：Hello World 智能体**
```python
"""Agent that prints hello world."""
def run():
print("hello world")
if __name__ == "__main__":
run()
```
资料来源：[agents/hello_world.py:1-8](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/hello_world.py)
**配置文件示例**
```yaml
# Hello World Agent Configuration
name: hello_world
description: Agent that prints a hello world greeting
# Output settings
output:
message: "hello world"
```
资料来源：[config/hello_world.yaml:1-7](https://github.com/chonlim92/claude-code-project-template/blob/main/config/hello_world.yaml)
### Chat 智能体
Chat 智能体是 VS Code Copilot 的角色定义，通过 `@agent-name` 在聊天中调用。
| 属性 | 说明 |
|------|------|
| 文件位置 | `.claude/agents/` 目录 |
| 文件格式 | `.agent.md`（Markdown + YAML 前置元数据） |
| 配置位置 | YAML frontmatter（tools、model 等） |
| 调用方式 | 在 Copilot 聊天中使用 `@agent-name` |
资料来源：[AGENTS.md:24-30](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
**内置 Chat 智能体**
| 智能体 | 功能 |
|--------|------|
| `@texting` | 文本生成、问候语和消息处理 |
| `@calculating` | 数学运算和算术计算 |
| `@orchestrator` | 委托给专业智能体的编排器 |
资料来源：[README.md:62-66](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
## MCP 服务器
MCP（Model Context Protocol）服务器用于向智能体暴露工具接口。
资料来源：[mcp/README.md:1-3](https://github.com/chonlim92/claude-code-project-template/blob/main/mcp/README.md)
### 设计原则
| 原则 | 说明 |
|------|------|
| 清晰的工具描述 | 便于智能体发现和调用 |
| 错误处理 | 优雅处理错误并返回有意义的消息 |
| 独立可测试 | 每个 MCP 服务器可独立验证 |
资料来源：[mcp/README.md:4-7](https://github.com/chonlim92/claude-code-project-template/blob/main/mcp/README.md)
### MCP 交互流程
```mermaid
graph LR
A[Claude Code CLI] -->|MCP Protocol| B[MCP Server]
B --> C[GitHub API]
B --> D[Database]
B --> E[External APIs]
```
### MCP 服务器管理命令
```bash
# 添加远程 MCP 服务器
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp"}'
# 添加本地 MCP 服务器
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN= -- docker run -i --rm ghcr.io/github/github-mcp-server
# 添加自定义项目 MCP 服务器
claude mcp add-json mytools '{"command": "python", "args": ["mcp/server.py"]}'
# 列出所有服务器
claude mcp list
# 检查服务器配置和健康状态
claude mcp get
# 移除服务器
claude mcp remove
```
资料来源：[README.md:44-59](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
## CLI 工具
`tools/` 目录下的独立脚本可被智能体调用或独立运行。
资料来源：[tools/README.md:1-3](https://github.com/chonlim92/claude-code-project-template/blob/main/tools/README.md)
### 设计规范
| 规范 | 说明 |
|------|------|
| 独立运行 | 脚本应能作为独立 CLI 使用 |
| 参数配置 | 接受参数进行配置 |
| 结构化输出 | 推荐使用 JSON 格式，便于智能体消费 |
资料来源：[tools/README.md:5-8](https://github.com/chonlim92/claude-code-project-template/blob/main/tools/README.md)
## 配置管理
所有外部连接（数据库、API）的配置集中在 `config/` 目录。
资料来源：[config/README.md:1-3](https://github.com/chonlim92/claude-code-project-template/blob/main/config/README.md)
### 配置文件说明
| 文件 | 用途 |
|------|------|
| `.env.example` | 环境变量模板（已提交到版本控制） |
| `.env` | 实际密钥（不提交到版本控制） |
| `agent.yaml` | 智能体配置文件 |
资料来源：[config/README.md:5-7](https://github.com/chonlim92/claude-code-project-template/blob/main/config/README.md)
### 环境配置示例
```bash
# 安装依赖
pip install -r requirements.txt
# 配置环境变量
cp config/.env.example config/.env
# 编辑 .env 添加实际凭据
```
## 依赖项
项目依赖通过 `requirements.txt` 管理。
| 依赖包 | 版本要求 | 用途 |
|--------|----------|------|
| pytest | ≥7.0 | 测试框架 |
| python-dotenv | ≥1.0 | 环境变量加载 |
| pyyaml | ≥6.0 | YAML 配置文件解析 |
资料来源：[requirements.txt:1-3](https://github.com/chonlim92/claude-code-project-template/blob/main/requirements.txt)
## 快速开始
### 安装步骤
```bash
# 克隆仓库
git clone
cd claude-code-project-template
# 安装依赖
pip install -r requirements.txt
# 配置环境
cp config/.env.example config/.env
# 启动 MCP 服务器
python mcp/server.py
# 运行 Python 智能体
python agents/sum_numbers.py 3 5
# 运行测试
pytest
```
资料来源：[README.md:83-97](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
### Claude Code CLI 使用方式
```bash
# 启动交互式会话
claude
# 非交互式执行单条指令
claude --p "Analyze the files in this directory"
# 预批准工具权限
claude --p "Refactor utils.py" --approvedTool edit --approvedTool bash
# 运行特定聊天智能体
claude --p "What is 9 + 27" --agent calculating
```
资料来源：[README.md:100-115](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
## 扩展指南
### 添加新组件流程
| 组件类型 | 步骤 |
|----------|------|
| Python 智能体 | 创建 `agents/.py` + `config/.yaml` |
| Chat 智能体 | 创建 `.claude/agents/.agent.md`（含 YAML frontmatter） |
| 技能 | 创建 `.claude/skills//SKILL.md` |
| MCP 工具 | 在 `mcp/` 实现，注册到服务器，添加工具描述 |
| CLI 工具 | 在 `tools/` 创建脚本，确保独立可测试 |
资料来源：[README.md:68-77](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
## 安全规范
| 规范 | 说明 |
|------|------|
| 密钥管理 | 凭据存储在 `.env` 文件中 |
| 版本控制 | `.env` 和 `.mcp.json` 不提交到版本控制 |
| 配置文件 | 已添加到 `.gitignore` |
资料来源：[README.md:60-63](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
## 智能体执行规则
当通过 `runSubagent` 或其他方式委托给聊天智能体时，必须：
1. 读取并遵循 `.agent.md` 正文的完整行为指令
2. 不仅仅是使用描述进行路由
3. 包括：约束条件、步骤方法、技能检查程序、必需输出格式
4. 例如：当无技能匹配时使用 ⚠️ 前缀
资料来源：[CLAUDE.md:32-39](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
---
## 快速入门指南
### 相关页面
相关主题：[项目介绍](#page-introduction)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
- [requirements.txt](https://github.com/chonlim92/claude-code-project-template/blob/main/requirements.txt)
- [config/.env.example](https://github.com/chonlim92/claude-code-project-template/blob/main/config/.env.example)
- [CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
- [config/hello_world.yaml](https://github.com/chonlim92/claude-code-project-template/blob/main/config/hello_world.yaml)
- [config/sum_numbers.yaml](https://github.com/chonlim92/claude-code-project-template/blob/main/config/sum_numbers.yaml)
- [agents/hello_world.py](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/hello_world.py)
# 快速入门指南
## 项目概述
Claude Code Project Template 是一个多代理项目模板，集成了 MCP 服务器（Model Context Protocol）和 CLI 工具，用于访问数据库和 API。该项目专为 VS Code Copilot 聊天代理和基于 Python 的自动化场景设计。
资料来源：[README.md:1-8]()
## 系统架构
项目采用模块化架构，包含以下核心组件：
```mermaid
graph TD
subgraph "客户端层"
A["VS Code Copilot"]
B["Claude Code CLI"]
C["Python 脚本"]
end
subgraph "代理层"
D["Chat Agents
.claude/agents/"]
E["Python Agents
agents/"]
end
subgraph "工具层"
F["MCP Server
mcp/"]
G["CLI Tools
tools/"]
end
subgraph "外部服务"
H["Database/APIs"]
end
A --> D
B --> E
B --> F
C --> E
D --> F
E --> G
F --> H
style A fill:#e1f5fe
style B fill:#fff3e0
style F fill:#f3e5f5
```
资料来源：[README.md:9-20]()
## 前置条件
### 环境要求
| 组件 | 版本要求 | 说明 |
|------|----------|------|
| Python | 3.10+ | 项目运行环境 |
| Node.js | v18+ | Claude Code CLI 依赖 |
| npm | 最新版本 | Node.js 包管理器 |
| VS Code | 最新版本 | 配合 Copilot 扩展使用 |
| Git | 任意版本 | 版本控制（Windows 需单独安装）|
资料来源：[README.md:22-23]()
### 必需依赖
项目依赖通过 `requirements.txt` 管理，核心依赖包括：
| 依赖包 | 版本要求 | 用途 |
|--------|----------|------|
| pytest | ≥7.0 | 测试框架 |
| python-dotenv | ≥1.0 | 环境变量管理 |
| pyyaml | ≥6.0 | YAML 配置文件解析 |
资料来源：[requirements.txt:1-3]()
## 安装步骤
### 1. 克隆项目仓库
```bash
git clone
cd claude-code-project-template
```
### 2. 安装 Python 依赖
```bash
pip install -r requirements.txt
```
### 3. 配置环境变量
```bash
cp config/.env.example config/.env
```
然后编辑 `config/.env` 文件，填入实际的凭证信息。**重要**：`.env` 文件包含敏感信息，切勿提交到版本控制系统。
资料来源：[README.md:84-91]()
### 4. 安装 Claude Code CLI（可选）
如果需要使用 Claude Code 命令行工具：
**Windows 系统：**
```powershell
# 使用 winget 安装 Node.js
winget install OpenJS.NodeJS.LTS
# 安装 Claude Code
npm install -g @anthropic-ai/claude-code
```
**Linux 系统：**
```bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code
```
资料来源：[README.md:26-55]()
## 运行项目
### 启动 MCP 服务器
```bash
python mcp/server.py
```
### 运行 Python 代理
项目内置两个示例代理：
| 代理名称 | 文件路径 | 功能说明 |
|----------|----------|----------|
| hello_world | `agents/hello_world.py` | 打印问候语 |
| sum_numbers | `agents/sum_numbers.py` | 计算两个数字之和 |
#### 运行 hello_world 代理
```bash
python agents/hello_world.py
```
输出结果：
```
hello world
```
资料来源：[agents/hello_world.py:1-8]()
#### 运行 sum_numbers 代理
```bash
python agents/sum_numbers.py 3 5
```
## 代理类型详解
### Python 代理
Python 代理是位于 `agents/` 目录下的可执行脚本，用于独立任务、CI 流水线或 MCP 集成。
```mermaid
graph LR
A["创建代理文件
agents/.py"] --> B["创建配置文件
config/.yaml"]
B --> C["添加运行逻辑"]
C --> D["测试运行
python agents/.py"]
```
每个 Python 代理对应一个 YAML 配置文件，配置结构如下：
| 配置字段 | 说明 | 示例 |
|----------|------|------|
| name | 代理名称 | hello_world |
| description | 功能描述 | Agent that prints a hello world greeting |
| output.message | 输出消息（可选） | "hello world" |
| input.a | 输入参数 A（可选） | 0 |
| input.b | 输入参数 B（可选） | 0 |
资料来源：[config/hello_world.yaml:1-6]()
### Chat 代理
Chat 代理是 VS Code Copilot 的角色定义，位于 `.claude/agents/` 目录，使用 Markdown 格式配合 YAML 前置元数据。
| 代理名称 | 用途 |
|----------|------|
| @texting | 文本生成、问候语、消息 |
| @calculating | 数学运算和算术计算 |
| @orchestrator | 委托给专业代理 |
资料来源：[README.md:106-112]()
## 配置管理
### 环境变量配置
项目配置遵循以下约定：
- 所有外部连接（数据库、API）的配置放在 `config/` 目录
- 敏感信息存储在 `.env` 文件中
- `.env` 文件永不提交到版本控制
### YAML 配置文件格式
```yaml
# 代理配置示例
name: <代理名称>
description: <功能描述>
# 输出设置（可选）
output:
message: "输出消息"
# 输入设置（可选）
input:
a: 0
b: 0
```
资料来源：[config/sum_numbers.yaml:1-8]()
## MCP 服务器配置
### 添加 MCP 服务器
Claude Code 支持添加本地和远程 MCP 服务器：
```bash
# 添加远程 MCP 服务器（如 GitHub）
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer "}}'
# 添加本地 MCP 服务器
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN= -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
# 添加自定义项目 MCP 服务器
claude mcp add-json mytools '{"command": "python", "args": ["mcp/server.py"], "env": {}}'
```
### MCP 服务器管理命令
| 命令 | 功能 |
|------|------|
| `claude mcp list` | 列出所有已连接的 MCP 服务器 |
| `claude mcp get ` | 查看特定服务器的配置和健康状态 |
| `claude mcp remove ` | 移除指定的 MCP 服务器 |
### 作用域选项
| 选项 | 说明 |
|------|------|
| `--scope local` | 仅当前用户可见（默认） |
| `--scope project` | 共享给项目成员（写入 `.mcp.json`） |
| `--scope user` | 所有项目共享 |
资料来源：[README.md:58-75]()
## 自动化执行
### 非交互式执行
使用 `--p` 参数执行单条指令：
```bash
claude --p "Analyze the files in this directory and write a short summary to SUMMARY.md"
```
### 预授权工具
在自动化流水线中使用 `--approvedTool` 预授权工具，避免交互确认：
```bash
claude --p "Refactor utils.py" --approvedTool edit --approvedTool bash
```
### 指定代理执行
```bash
# 使用 calculating 代理计算
claude --p "What is 9 + 27" --agent calculating
# 使用 texting 代理打招呼
claude --p "Say hello to the world" --agent texting
# 使用 orchestrator 代理执行复合任务
claude --p "Calculate 5^2 then greet me" --agent orchestrator
```
资料来源：[README.md:93-105]()
## 测试
运行项目测试套件：
```bash
pytest
```
## 添加新组件指南
### 新增 Python 代理
| 步骤 | 操作 |
|------|------|
| 1 | 创建 `agents/.py` |
| 2 | 创建 `config/.yaml` |
| 3 | 实现运行逻辑 |
| 4 | 测试独立运行 |
### 新增 Chat 代理
| 步骤 | 操作 |
|------|------|
| 1 | 创建 `.claude/agents/.agent.md` |
| 2 | 添加 YAML 前置元数据 |
| 3 | 定义代理行为和约束 |
| 4 | 在 Copilot 聊天中用 `@agent-name` 调用 |
### 新增 MCP 工具
| 步骤 | 操作 |
|------|------|
| 1 | 在 `mcp/` 目录实现工具 |
| 2 | 在 MCP 服务器注册工具 |
| 3 | 添加工具描述（用于代理发现） |
| 4 | 测试工具可独立调用 |
资料来源：[README.md:113-125]()
## 最佳实践
1. **模块化设计**：优先复用现有工具，避免重复造轮子
2. **配置分离**：所有外部连接配置放在 `config/` 目录
3. **敏感信息安全**：凭证信息存储在 `.env` 文件，切勿提交
4. **工具描述清晰**：MCP 工具需提供清晰的名称和文档字符串，便于代理发现
5. **独立测试**：CLI 工具和 MCP 工具应能独立运行测试
资料来源：[README.md:126-131]()
---
## 系统架构
### 相关页面
相关主题：[项目介绍](#page-introduction), [项目目录结构](#page-project-structure), [Python智能体开发](#page-python-agents), [聊天智能体开发](#page-chat-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
- [CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
- [config/hello_world.yaml](https://github.com/chonlim92/claude-code-project-template/blob/main/config/hello_world.yaml)
- [config/sum_numbers.yaml](https://github.com/chonlim92/claude-code-project-template/blob/main/config/sum_numbers.yaml)
- [agents/hello_world.py](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/hello_world.py)
# 系统架构
## 项目概述
本项目是一个基于 Claude Code 的多智能体系统模板，集成了 MCP 服务器（Model Context Protocol）和 CLI 工具，用于访问数据库和 API。该模板专为 VS Code Copilot 聊天智能体和基于 Python 的自动化场景设计。
资料来源：[README.md:1-10]()
## 整体架构
系统采用模块化分层架构，各组件职责清晰分离：
```mermaid
graph TD
subgraph "表现层"
A["VS Code Copilot Chat"]
B["Claude Code CLI"]
C["终端/命令行"]
end
subgraph "智能体层"
D["Chat Agents
(.claude/agents/)"]
E["Python Agents
(agents/)"]
end
subgraph "工具层"
F["Skills
(.claude/skills/)"]
G["MCP Servers
(mcp/)"]
H["CLI Tools
(tools/)"]
end
subgraph "配置层"
I["配置文件
(config/)"]
J["环境变量
(.env)"]
end
A --> D
B --> D
B --> E
C --> E
D --> F
D --> G
E --> G
E --> H
G --> K["外部服务"]
H --> K
I --> D
I --> E
J --> G
J --> H
```
资料来源：[README.md:18-28]()
## 目录结构
| 目录 | 说明 | 资料来源 |
|------|------|----------|
| `agents/` | Python 智能体脚本（运行时实现） | [README.md:19]() |
| `.claude/agents/` | 聊天智能体（`.agent.md` 用于 VS Code Copilot） | [README.md:20]() |
| `.claude/skills/` | 技能模块（按需工作流） | [README.md:21]() |
| `mcp/` | MCP 服务器实现（Model Context Protocol） | [README.md:22]() |
| `tools/` | CLI 工具和独立脚本 | [README.md:23]() |
| `config/` | 环境配置和连接设置 | [README.md:24]() |
| `docs/` | 项目文档 | [README.md:24]() |
| `tests/` | 测试套件 | [README.md:24]() |
## 核心组件
### 1. Python 智能体
Python 智能体是可直接执行的 Python 脚本，用于独立任务、CI 流水线、MCP 集成等场景。
```mermaid
graph LR
A["配置文件
config/.yaml"] --> B["Python 脚本
agents/.py"]
B --> C["终端执行
python agents/.py"]
```
**特点：**
- 每个智能体对应一个 Python 文件
- 配置信息存储在 `config/` 目录下的 YAML 文件中
- 可通过命令行参数或配置文件进行参数传递
资料来源：[AGENTS.md:18-23]()
**配置示例：**
```yaml
# config/sum_numbers.yaml
name: sum_numbers
description: 计算两个数字之和的智能体
input:
a: 0
b: 0
```
资料来源：[config/sum_numbers.yaml:1-7]()
**代码实现示例：**
```python
# agents/hello_world.py
"""Agent that prints hello world."""
def run():
print("hello world")
if __name__ == "__main__":
run()
```
资料来源：[agents/hello_world.py:1-8]()
### 2. Chat 智能体
Chat 智能体是 VS Code Copilot 的角色定义，通过 `@agent-name` 在聊天中调用。
```mermaid
graph TD
A["用户输入
@agent-name"] --> B["VS Code Copilot"]
B --> C["解析 .agent.md"]
C --> D["执行技能/工具"]
D --> E["返回结果"]
```
**特点：**
- 使用 Markdown 格式定义，包含 YAML 前置元数据
- 元数据中定义工具列表、模型配置等
- 可通过 Skills 定义斜杠命令
资料来源：[AGENTS.md:24-32]()
**Chat 智能体类型：**
| 智能体 | 用途 | 资料来源 |
|--------|------|----------|
| `@texting` | 文本生成、问候语、消息 | [README.md:42]() |
| `@calculating` | 数学运算和算术计算 | [README.md:42]() |
| `@orchestrator` | 委托给专业智能体 | [README.md:42]() |
### 3. MCP 服务器
MCP 服务器实现 Model Context Protocol 标准，向智能体暴露各种工具。
```mermaid
graph LR
A["Claude Code CLI"] --> B["MCP Server
(mcp/server.py)"]
B --> C["外部服务
(GitHub, DB, API)"]
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#e8f5e8
```
**功能：**
- 暴露工具供智能体发现和调用
- 提供数据库、API 等外部服务访问能力
- 支持本地和远程 MCP 服务器配置
资料来源：[README.md:25-26]()
**服务器管理命令：**
| 命令 | 说明 | 资料来源 |
|------|------|----------|
| `claude mcp add` | 添加 MCP 服务器 | [README.md:69-75]() |
| `claude mcp list` | 列出所有服务器 | [README.md:89]() |
| `claude mcp get` | 获取服务器配置 | [README.md:89]() |
| `claude mcp remove` | 移除服务器 | [README来源：README.md:89]() |
### 4. CLI 工具
独立脚本，可独立运行或被智能体调用。
**特点：**
- 独立可测试
- 可接受配置参数
- 返回结构化输出（优先使用 JSON）
资料来源：[README.md:48-50]()
## 配置管理
### 配置架构
```mermaid
graph TD
A[".env.example"] -->|模板| B[".env"]
B --> C["环境变量"]
D[".yaml"] -->|智能体配置| E["运行时参数"]
C --> F["MCP Servers"]
C --> G["CLI Tools"]
E --> H["Python Agents"]
style B fill:#ffcdd2
style D fill:#c8e6c9
```
**配置文件位置：** `config/` 目录
| 文件 | 用途 | 资料来源 |
|------|------|----------|
| `.env.example` | 环境变量模板（提交到版本控制） | [config/README.md:3]() |
| `.env` | 实际密钥（不提交到版本控制） | [config/README.md:3]() |
| `.yaml` | 智能体配置文件 | [AGENTS.md:19]() |
资料来源：[config/README.md:1-6]()
### 安全规范
- 所有外部连接（数据库、API）在 `config/` 中配置
- 敏感信息存储在 `.env` 文件中
- `.env` 和 `.mcp.json` 必须添加到 `.gitignore`
资料来源：[README.md:51-52]()
## 智能体执行流程
### Python 智能体执行
```mermaid
sequenceDiagram
participant User
participant CLI
participant Agent
participant Config
participant External
User->>CLI: python agents/.py [args]
CLI->>Agent: 加载脚本
Agent->>Config: 读取 config/.yaml
Config-->>Agent: 返回配置参数
Agent->>External: 访问服务/API
External-->>Agent: 返回数据
Agent-->>User: 输出结果
```
### Chat 智能体执行
```mermaid
sequenceDiagram
participant User
participant Copilot
participant Agent
participant Skills
participant MCP
User->>Copilot: @agent-name <指令>
Copilot->>Agent: 加载 .agent.md
Agent->>Agent: 解析元数据和行为规则
Agent->>Skills: 检查技能匹配
Agent->>MCP: 调用工具
MCP-->>Agent: 工具返回结果
Agent-->>Copilot: 格式化输出
Copilot-->>User: 显示结果
```
资料来源：[CLAUDE.md:38-47]()
## 开发规范
### 添加新组件
| 组件类型 | 步骤 | 资料来源 |
|----------|------|----------|
| **Python 智能体** | 创建 `agents/.py` + `config/.yaml` | [README.md:54-55]() |
| **Chat 智能体** | 创建 `.claude/agents/.agent.md`（含 YAML 前置元数据） | [README.md:56-57]() |
| **技能模块** | 创建 `.claude/skills//SKILL.md` | [README.md:58-59]() |
| **MCP 工具** | 在 `mcp/` 实现，注册到服务器，添加工具描述 | [README.md:60-61]() |
| **CLI 工具** | 在 `tools/` 创建脚本，保持独立可测试性 | [README.md:62-63]() |
### 命名和文档规范
- MCP 工具必须具有清晰、描述性的名称和文档字符串
- 文档字符串用于智能体发现
- 优先组合现有工具而非创建新工具
资料来源：[README.md:64-66]()
## 依赖关系
### 项目依赖
```
pytest>=7.0
python-dotenv>=1.0
pyyaml>=6.0
```
资料来源：[requirements.txt:1-3]()
### 运行时依赖
- Python 3.10+
- Node.js 和 npm（用于 Claude Code CLI）
- VS Code 及 GitHub Copilot 扩展（用于聊天智能体）
资料来源：[README.md:31-33]()
## 技术栈总结
| 层级 | 技术/工具 | 说明 |
|------|-----------|------|
| 运行时环境 | Python 3.10+ | 核心编程语言 |
| 命令行工具 | Claude Code CLI | 智能体执行环境 |
| 开发环境 | VS Code + Copilot | 交互式智能体调用 |
| 通信协议 | MCP (Model Context Protocol) | 工具暴露标准 |
| 配置格式 | YAML | 配置文件格式 |
| 依赖管理 | pip + requirements.txt | Python 包管理 |
---
## 项目目录结构
### 相关页面
相关主题：[系统架构](#page-architecture), [Python智能体开发](#page-python-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
- [CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
- [mcp/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/mcp/README.md)
- [agents/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/README.md)
- [tools/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/tools/README.md)
- [config/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/config/README.md)
# 项目目录结构
## 概述
claude-code-project-template 是一个多智能体项目模板，集成了 MCP 服务器（Model Context Protocol）和 CLI 工具，用于访问数据库和 API。该项目专为 VS Code Copilot 聊天智能体和基于 Python 的自动化场景设计，支持交互式和自动化流水线执行。
资料来源：[README.md:1-10](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
## 整体架构
项目采用分层架构设计，各模块职责明确，通过标准协议实现解耦。
```mermaid
graph TD
A[用户/自动化系统] --> B[Claude Code CLI]
B --> C[Chat Agents
.claude/agents/]
B --> D[Python Agents
agents/]
D --> E[MCP Server
mcp/]
E --> F[External Services
GitHub, DB, APIs]
C --> G[Skills
.claude/skills/]
D --> H[CLI Tools
tools/]
I[Config
config/] --> D
I --> E
```
资料来源：[CLAUDE.md:1-20](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
## 目录结构详解
### 目录一览表
| 目录 | 用途说明 |
|------|----------|
| `agents/` | Python 智能体脚本（运行时实现） |
| `.claude/agents/` | 聊天智能体（.agent.md，用于 VS Code Copilot） |
| `.claude/skills/` | 技能模块（按需工作流，供聊天智能体调用） |
| `mcp/` | MCP 服务器实现（Model Context Protocol） |
| `tools/` | CLI 工具和独立脚本 |
| `config/` | 环境配置和连接设置 |
| `docs/` | 项目文档 |
| `tests/` | 测试套件 |
资料来源：[README.md:12-22](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
---
## agents/ — Python 智能体
### 定位与用途
Python 智能体是**可执行的 Python 脚本**，用于独立任务、CI 流水线、MCP 集成等场景。每个智能体独占一个文件，配置通过对应的 YAML 文件管理。
资料来源：[AGENTS.md:16-24](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
### 文件规范
- **定义文件**: `agents/.py`
- **配置文件**: `config/.yaml`
### 运行方式
```bash
python agents/.py [args]
```
### 内置智能体
| 智能体 | 功能描述 |
|--------|----------|
| `hello_world.py` | 打印问候语 |
| `sum_numbers.py` | 计算两个数字之和 |
### 代码示例
```python
"""Agent that prints hello world."""
def run():
print("hello world")
if __name__ == "__main__":
run()
```
资料来源：[agents/hello_world.py:1-8](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/hello_world.py)
### 配置示例
```yaml
# config/sum_numbers.yaml
name: sum_numbers
description: Agent that calculates the sum of two numbers
# Input settings
input:
a: 0
b: 0
```
资料来源：[config/sum_numbers.yaml:1-7](https://github.com/chonlim92/claude-code-project-template/blob/main/config/sum_numbers.yaml)
---
## .claude/agents/ — 聊天智能体
### 定位与用途
聊天智能体是 **VS Code Copilot 角色**，通过 `@agent-name` 在聊天中调用。每个智能体定义为一个 `.agent.md` 文件，包含 YAML frontmatter 配置。
资料来源：[AGENTS.md:26-33](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
### 文件格式
```
.claude/agents/.agent.md
```
### 核心配置项
| 配置项 | 说明 |
|--------|------|
| `name` | 智能体名称 |
| `description` | 功能描述 |
| `tools` | 允许调用的工具列表 |
| `agents` | 可委托的其他智能体 |
### 内置聊天智能体
| 智能体 | 用途 |
|--------|------|
| `@texting` | 文本生成、问候语、消息 |
| `@calculating` | 数学运算和算术计算 |
| `@orchestrator` | 委托给专家智能体的编排器 |
### 执行规则
> 当通过 `runSubagent` 委托给聊天智能体时，必须阅读并遵循其 `.agent.md` 正文中定义的完整行为指令，包括约束条件、步骤流程、技能检查程序和输出格式要求。
资料来源：[CLAUDE.md:53-58](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
---
## .claude/skills/ — 技能模块
### 定位与用途
技能是可复用的工作流，聊天智能体可按需调用。每个技能独占一个文件夹，包含 `SKILL.md` 定义文件。
资料来源：[README.md:48-52](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
### 目录结构
```
.claude/skills//
└── SKILL.md
```
### 调用方式
```
/hello-world
/sum
```
### 内置技能
| 技能 | 功能描述 |
|------|----------|
| `/hello-world` | 打印问候语 |
| `/sum` | 计算两个数字之和 |
---
## mcp/ — MCP 服务器
### 定位与用途
MCP 服务器实现了 **Model Context Protocol** 标准，向智能体暴露各种工具。每个 MCP 服务器应具备清晰的工具描述、优雅的错误处理和独立的可测试性。
资料来源：[mcp/README.md:1-8](https://github.com/chonlim92/claude-code-project-template/blob/main/mcp/README.md)
### 架构关系
```mermaid
graph LR
A[Claude Code CLI] --> B[MCP Server]
B --> C[External Services]
C --> D[GitHub API]
C --> E[Database]
C --> F[Other APIs]
```
### 核心要求
| 要求 | 说明 |
|------|------|
| 工具描述 | 必须有清晰、描述性的名称和文档字符串 |
| 错误处理 | 优雅处理错误，返回有意义的错误信息 |
| 独立测试 | 必须能够独立测试验证 |
### MCP 服务器管理命令
```bash
# 添加远程 MCP 服务器
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp"}'
# 添加本地 MCP 服务器
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN= -- docker run -i --rm ghcr.io/github/github-mcp-server
# 列出所有服务器
claude mcp list
# 查看服务器状态
claude mcp get
# 移除服务器
claude mcp remove
```
### 作用域选项
| 作用域 | 影响范围 |
|--------|----------|
| `--scope local` | 仅当前用户（默认） |
| `--scope project` | 项目共享（写入 `.mcp.json`） |
| `--scope user` | 所有项目（全局） |
资料来源：[README.md:62-85](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
---
## tools/ — CLI 工具
### 定位与用途
CLI 工具是**独立脚本**，既可独立运行，也可被智能体调用。
资料来源：[tools/README.md:1-8](https://github.com/chonlim92/claude-code-project-template/blob/main/tools/README.md)
### 设计原则
| 原则 | 说明 |
|------|------|
| 独立性 | 作为独立 CLI 脚本工作 |
| 参数化 | 接受配置参数 |
| 结构化输出 | 优先使用 JSON 格式返回结果 |
---
## config/ — 配置文件
### 定位与用途
所有外部连接（数据库、API）的配置集中管理，敏感信息通过 `.env` 文件处理。
资料来源：[config/README.md:1-12](https://github.com/chonlim92/claude-code-project-template/blob/main/config/README.md)
### 文件结构
| 文件 | 用途 | 版本控制 |
|------|------|----------|
| `.env.example` | 环境变量模板 | 提交 |
| `.env` | 实际敏感配置 | 不提交 |
| `agent.yaml` | 智能体配置 | 提交 |
### 安全规范
> **重要**: 敏感信息（如 API 密钥、访问令牌）必须存储在 `.env` 文件中，**严禁提交到版本控制系统**。
---
## docs/ — 文档目录
存放项目的完整文档，包括但不限于：
- Claude Code 安装与使用指南
- MCP 服务器配置详解
- GitHub MCP 服务器安装说明
资料来源：[CLAUDE.md:15-18](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
---
## tests/ — 测试套件
项目包含完整的测试套件，使用 pytest 作为测试框架。
资料来源：[requirements.txt:1](https://github.com/chonlim92/claude-code-project-template/blob/main/requirements.txt)
---
## 依赖关系图
```mermaid
graph TD
subgraph 用户层
U[用户]
A[自动化系统]
end
subgraph 交互层
CLI[Claude Code CLI]
MCP[MCP Server]
end
subgraph 智能体层
PA[Python Agents]
CA[Chat Agents]
SK[Skills]
end
subgraph 工具层
CT[CLI Tools]
end
subgraph 配置层
ENV[.env]
YAML[YAML Config]
end
U --> CLI
A --> CLI
CLI --> PA
CLI --> CA
CA --> SK
PA --> MCP
MCP --> CT
PA --> YAML
MCP --> ENV
```
---
## 新增组件指南
| 组件类型 | 步骤 |
|----------|------|
| **Python 智能体** | 创建 `agents/.py` + `config/.yaml` |
| **聊天智能体** | 创建 `.claude/agents/.agent.md`，包含 YAML frontmatter |
| **技能** | 创建 `.claude/skills//SKILL.md` |
| **MCP 工具** | 在 `mcp/` 实现，注册到服务器，添加工具描述 |
| **CLI 工具** | 在 `tools/` 创建脚本，确保可独立测试 |
资料来源：[README.md:54-62](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
---
## 快速启动
### 环境准备
```bash
# 克隆仓库
git clone
cd claude-code-project-template
# 安装依赖
pip install -r requirements.txt
# 配置环境
cp config/.env.example config/.env
```
### 运行组件
```bash
# 启动 MCP 服务器
python mcp/server.py
# 运行 Python 智能体
python agents/sum_numbers.py 3 5
# 运行测试
pytest
```
资料来源：[README.md:115-135](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
---
## Python智能体开发
### 相关页面
相关主题：[聊天智能体开发](#page-chat-agents), [技能开发](#page-skills)
相关源码文件
以下源码文件用于生成本页说明：
- [agents/hello_world.py](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/hello_world.py)
- [agents/sum_numbers.py](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/sum_numbers.py)
- [config/hello_world.yaml](https://github.com/chonlim92/claude-code-project-template/blob/main/config/hello_world.yaml)
- [config/sum_numbers.yaml](https://github.com/chonlim92/claude-code-project-template/blob/main/config/sum_numbers.yaml)
- [agents/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/README.md)
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
# Python智能体开发
## 概述
Python智能体（Python Agents）是本项目中的可执行Python脚本，用于处理独立任务、CI/CD流程、自动化管道以及MCP集成。智能体采用"一个智能体一个文件"的设计原则，每个智能体对应`agents/`目录下的一个`.py`文件，并配有`config/`目录下的对应YAML配置文件。
资料来源：[AGENTS.md:1-6]()
## 架构设计
### 智能体类型分类
本项目支持两种类型的智能体：
| 智能体类型 | 文件格式 | 配置方式 | 运行方式 | 适用场景 |
|-----------|---------|---------|---------|---------|
| Python智能体 | `.py`文件 | `config/*.yaml` | 终端执行或被调用 | 独立任务、CI、管道、MCP集成 |
| 聊天智能体 | `.agent.md`文件 | YAML frontmatter | VS Code Copilot中`@agent-name`调用 | 交互式AI助手 |
资料来源：[AGENTS.md:14-26]()
### Python智能体架构图
```mermaid
graph TD
A[用户/系统] --> B[终端/命令行]
B --> C[python agents/<name>.py]
C --> D[config/<name>.yaml]
C --> E[run 函数]
E --> F[业务逻辑处理]
F --> G[输出结果]
G --> H[返回值/打印输出]
style A fill:#e1f5fe
style C fill:#fff3e0
style D fill:#f3e5f5
```
## 目录结构规范
### 标准目录布局
```
├── agents/ # Python智能体脚本（运行时实现）
├── config/ # YAML配置文件
└── docs/ # 文档说明
```
- **agents/**：存放所有Python智能体实现，每个智能体一个`.py`文件
- **config/**：存放对应的YAML配置文件，采用`智能体名称.yaml`命名
资料来源：[AGENTS.md:7-11]()
## 智能体实现规范
### 基本结构要求
每个Python智能体必须满足以下结构规范：
1. **入口函数**：必须定义`run()`函数作为主入口
2. **直接执行**：在`if __name__ == "__main__":`块中调用`run()`函数
3. **参数解析**：使用`argparse`模块处理命令行参数（可选）
4. **返回值**：`run()`函数可返回处理结果供调用方使用
资料来源：[agents/hello_world.py:1-8]()
### 配置规范
智能体配置采用YAML格式，包含以下标准字段：
```yaml
name: 智能体名称
description: 智能体功能描述
# 根据智能体类型添加相应配置
output:
message: "输出消息"
```
| 配置字段 | 必填 | 说明 |
|---------|------|------|
| name | 是 | 智能体唯一标识符 |
| description | 是 | 智能体功能描述 |
| output | 否 | 输出相关配置 |
| input | 否 | 输入参数配置 |
资料来源：[config/hello_world.yaml:1-6]()[config/sum_numbers.yaml:1-11]()
## 开发示例
### 示例一：简单消息输出智能体
#### 源代码
```python
"""Agent that prints hello world."""
def run():
print("hello world")
if __name__ == "__main__":
run()
```
资料来源：[agents/hello_world.py:1-8]()
#### 配置文件
```yaml
# Hello World Agent Configuration
name: hello_world
description: Agent that prints a hello world greeting
# Output settings
output:
message: "hello world"
```
资料来源：[config/hello_world.yaml:1-6]()
#### 运行方式
```bash
python agents/hello_world.py
```
**输出结果**：`hello world`
### 示例二：带参数的计算智能体
#### 源代码
```python
"""Agent that calculates the sum of two numbers."""
import argparse
def run(a: float, b: float) -> float:
result = a + b
print(f"{a} + {b} = {result}")
return result
if __name__ == "__main__":
parser = argparse.ArgumentParser(description="Sum two numbers")
parser.add_argument("a", type=float, help="First number")
parser.add_argument("b", type=float, help="Second number")
args = parser.parse_args()
run(args.a, args.b)
```
资料来源：[agents/sum_numbers.py:1-19]()
#### 配置文件
```yaml
# Sum Numbers Agent Configuration
name: sum_numbers
description: Agent that calculates the sum of two numbers
# Input settings
input:
a: 0
b: 0
```
资料来源：[config/sum_numbers.yaml:1-9]()
#### 运行方式
```bash
python agents/sum_numbers.py 3 5
```
**输出结果**：`3.0 + 5.0 = 8.0`
#### 参数说明
| 参数 | 类型 | 说明 | 示例 |
|-----|------|------|-----|
| a | float | 第一个数值 | 3, 10.5, -2 |
| b | float | 第二个数值 | 5, 20.3, -1 |
## 智能体执行流程
```mermaid
graph LR
A[启动命令] --> B[参数解析]
B --> C[加载配置]
C --> D[执行业务逻辑]
D --> E{是否成功}
E -->|成功| F[返回结果]
E -->|失败| G[错误处理]
F --> H[输出到终端]
G --> I[输出错误信息]
style A fill:#e1f5fe
style D fill:#fff3e0
style F fill:#e8f5e9
style G fill:#ffebee
```
## 新增智能体开发指南
### 开发步骤
| 步骤 | 操作 | 说明 |
|-----|------|------|
| 1 | 创建`agents/.py` | 定义run函数和业务逻辑 |
| 2 | 创建`config/.yaml` | 编写智能体配置 |
| 3 | 测试运行 | 使用命令行执行验证 |
| 4 | 集成到管道 | 通过子进程调用或MCP集成 |
资料来源：[AGENTS.md:52-57]()
### 开发检查清单
- [ ] 智能体文件放在`agents/`目录下
- [ ] 配置文件放在`config/`目录下，文件名与智能体名一致
- [ ] 定义了`run()`函数作为入口
- [ ] 配置文件中包含`name`和`description`字段
- [ ] 已测试命令行执行
- [ ] 错误处理完善（适用于复杂智能体）
## 与其他组件的集成
### MCP集成架构
Python智能体可与MCP（Model Context Protocol）服务器集成，实现更强大的工具调用能力：
```mermaid
graph TD
A[Python智能体] --> B[MCP服务器]
B --> C[MCP工具]
C --> D[外部服务]
C --> E[数据库]
C --> F[API]
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#e8f5e9
```
### 子进程调用模式
在自动化管道中，Python智能体可通过`subprocess`模块被调用：
```python
import subprocess
def run_agent(agent_script: str, args: list) -> str:
command = ["python", agent_script] + args
result = subprocess.run(
command,
capture_output=True,
text=True,
check=True
)
return result.stdout
```
## 开发最佳实践
### 代码规范
1. **单一职责**：每个智能体只完成一个特定任务
2. **清晰的函数命名**：使用描述性的函数名
3. **完整的文档字符串**：为模块和函数添加docstring
4. **参数验证**：对输入参数进行必要的验证
### 配置管理
- 所有外部连接配置放在`config/`目录
- 敏感信息使用`.env`文件管理，绝不提交到版本控制
- 配置文件采用YAML格式，便于读取和维护
资料来源：[agents/README.md:1-5]()
## 总结
Python智能体是本项目的重要组成部分，采用简洁的文件结构和标准化配置。每个智能体通过统一的`run()`函数接口实现，配置通过YAML文件管理，便于维护和扩展。智能体支持独立命令行执行、子进程调用以及MCP协议集成，为构建复杂的AI自动化系统提供了灵活的基础架构。
---
## 聊天智能体开发
### 相关页面
相关主题：[Python智能体开发](#page-python-agents), [技能开发](#page-skills)
相关源码文件
以下源码文件用于生成本页说明：
- [.claude/agents/calculating.agent.md](https://github.com/chonlim92/claude-code-project-template/blob/main/.claude/agents/calculating.agent.md)
- [.claude/agents/orchestrator.agent.md](https://github.com/chonlim92/claude-code-project-template/blob/main/.claude/agents/orchestrator.agent.md)
- [.claude/agents/texting.agent.md](https://github.com/chonlim92/claude-code-project-template/blob/main/.claude/agents/texting.agent.md)
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
- [CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
# 聊天智能体开发
## 概述
聊天智能体（Chat Agent）是该多智能体项目模板中的核心组件之一，专为 VS Code Copilot 聊天界面设计的对话式 AI 角色。与 Python 代理不同，聊天智能体通过自然语言交互的方式工作，用户可以在 Copilot 聊天窗口中通过 `@agent-name` 语法直接调用特定的智能体。
聊天智能体的主要特点包括：
- 通过 Markdown 文件加 YAML 前置元数据定义
- 与 VS Code Copilot 深度集成
- 支持技能（Skills）扩展，通过斜杠命令触发
- 可实现多智能体协作和委派机制
资料来源：[CLAUDE.md]()
## 智能体类型对比
该项目支持两种类型的智能体，理解它们的区别对于正确选择和开发至关重要。
| 特性 | Python 代理 (`agents/`) | 聊天代理 (`.claude/agents/`) |
|------|-------------------------|------------------------------|
| 文件格式 | `.py` Python 脚本 | `.agent.md` Markdown 文件 |
| 配置方式 | YAML 配置文件 | YAML 前置元数据 |
| 调用方式 | 终端命令 `python agents/xxx.py` | `@agent-name` 在 Copilot 聊天中 |
| 交互模式 | 非交互式程序执行 | 自然语言对话交互 |
| 技能扩展 | 不支持 | 通过 `.claude/skills/` 支持 |
| 适用场景 | 独立任务、CI/CD 流水线 | 交互式 AI 助手 |
资料来源：[AGENTS.md]()
## 目录结构
聊天智能体统一存放在项目根目录的 `.claude/agents/` 目录下，采用 Markdown 格式定义。
```plaintext
.claude/
├── agents/ # 聊天智能体目录
│ ├── calculating.agent.md # 计算智能体
│ ├── texting.agent.md # 文本处理智能体
│ └── orchestrator.agent.md # 编排智能体
└── skills/ # 技能目录
└── /
└── SKILL.md # 技能定义文件
```
资料来源：[CLAUDE.md]()
## 智能体配置与定义
### 文件格式规范
聊天智能体采用 Markdown 文件格式，文件扩展名为 `.agent.md`。每个文件包含两部分：
1. **YAML 前置元数据** - 定义智能体的名称、描述、可用工具、模型等配置
2. **Markdown 正文** - 定义智能体的行为指令、约束条件和输出格式要求
### YAML 前置元数据字段
| 字段 | 说明 | 示例 |
|------|------|------|
| `name` | 智能体标识名称 | `calculating` |
| `description` | 智能体功能描述 | `数学运算和算术计算` |
| `tools` | 智能体可调用的工具列表 | `[Read, Edit, Bash]` |
| `model` | 使用的 AI 模型（可选） | `claude-sonnet-4-20250514` |
| `agents` | 可委派的下游智能体列表 | `[calculating, texting]` |
### 正文行为规范
智能体的 Markdown 正文定义了严格的运行时行为规范，包括：
- **约束条件**（Constraints）- 智能体必须遵守的规则
- **执行步骤**（Approach/Steps）- 完成任务的推荐流程
- **技能检查程序**（Skill-checking procedures）- 何时调用技能
- **输出格式要求**（Output formats）- 返回结果的格式规范
```markdown
---
name: calculating
description: 数学运算和算术计算
tools: [Read, Edit, Bash]
---
# 计算智能体
你是一个专门处理数学运算的智能体...
⚠️ 当没有匹配的技能时，必须使用此前缀提示用户
```
资料来源：[CLAUDE.md]()
## 核心智能体说明
### 计算智能体 (`@calculating`)
计算智能体专门负责数学运算和算术计算任务。
**配置示例：**
| 属性 | 值 |
|------|-----|
| 名称 | `@calculating` |
| 功能 | 数学运算和算术 |
| 调用方式 | 在 Copilot 聊天中输入 `@calculating <问题>` |
**典型用例：**
```
@calculating 9 + 27 等于多少？
@calculating 计算 5 的平方
```
### 文本智能体 (`@texting`)
文本智能体负责文本生成、问候语和消息处理。
**配置示例：**
| 属性 | 值 |
|------|-----|
| 名称 | `@texting` |
| 功能 | 文本生成、问候语、消息 |
| 调用方式 | 在 Copilot 聊天中输入 `@texting <指令>` |
**典型用例：**
```
@texting 生成一段欢迎新用户的问候语
@texting 向团队发送每日提醒消息
```
### 编排智能体 (`@orchestrator`)
编排智能体作为主控智能体，负责将任务委派给专业的下游智能体。
**配置示例：**
| 属性 | 值 |
|------|-----|
| 名称 | `@orchestrator` |
| 功能 | 委派任务给专业智能体 |
| 调用方式 | 在 Copilot 聊天中输入 `@orchestrator <复杂任务>` |
| 子智能体 | `[calculating, texting]` |
**工作原理：**
编排智能体分析用户请求，识别所需的专业能力，然后将任务路由到相应的专业智能体。例如，当用户请求"计算 5 的平方然后向我打招呼"时，编排智能体会先调用计算智能体，再调用文本智能体。
资料来源：[CLAUDE.md]()
## 智能体执行规则
### 委派行为规范
当智能体需要将任务委派给其他聊天智能体时（如通过 `runSubagent` 或类似机制），**必须**遵守以下规则：
1. **完整读取目标智能体的行为指令** - 不能仅根据描述进行路由
2. **遵循目标智能体的完整行为定义** - 包括约束条件、执行步骤、技能检查程序
3. **遵守输出格式要求** - 例如当没有匹配的技能时必须使用 ⚠️ 前缀
> ⚠️ `.agent.md` 正文定义的是严格的运行时行为规范，而不仅仅是角色标签。
资料来源：[CLAUDE.md]()
## 技能系统
技能（Skills）是聊天智能体的可扩展功能模块，以斜杠命令的形式提供。
### 技能目录结构
```plaintext
.claude/skills/
└── /
└── SKILL.md # 技能定义文件
```
### 内置技能
| 技能 | 命令 | 功能 |
|------|------|------|
| `hello-world` | `/hello-world` | 输出问候语 |
| `sum` | `/sum` | 计算两个数字的和 |
### 技能定义文件格式
技能通过 `.claude/skills//SKILL.md` 文件定义，包含：
- 技能名称和描述
- 输入参数规范
- 执行逻辑
- 输出格式要求
资料来源：[README.md]()
## 开发指南
### 创建新的聊天智能体
**步骤一：创建智能体文件**
在 `.claude/agents/` 目录下创建新的 `.agent.md` 文件：
```markdown
---
name: my-agent
description: 我的自定义智能体
tools: [Read, Edit, Bash]
agents: []
---
# 我的自定义智能体
你是...
## 约束条件
- 必须...
- 不得...
## 执行步骤
1. 分析用户请求
2. 确定所需工具
3. 执行并返回结果
```
**步骤二：配置智能体行为**
在 Markdown 正文中详细定义：
- 智能体的角色和职责
- 可接受的输入类型
- 输出格式规范
- 错误处理方式
- 与其他智能体的协作方式
### 智能体间协作模式
```mermaid
graph TD
A[用户请求] --> B[编排智能体
@orchestrator]
B --> C{任务分解}
C --> D[计算智能体
@calculating]
C --> E[文本智能体
@texting]
D --> F[执行算术运算]
E --> G[生成文本内容]
F --> H[结果聚合]
G --> H
H --> I[返回给用户]
```
编排智能体负责分析复杂请求，将其分解为多个子任务，然后委派给相应的专业智能体处理。这种设计实现了关注点分离，每个智能体专注于特定领域。
### 配置多智能体委派
在智能体的 YAML 前置元数据中使用 `agents` 字段声明可用的子智能体：
```yaml
---
name: orchestrator
description: 任务编排器
tools: [Read, Edit, Bash]
agents: [calculating, texting]
---
```
## 与 Python 代理的集成
聊天智能体可以与 Python 代理协同工作，形成完整的自动化解决方案：
| 场景 | 聊天智能体职责 | Python 代理职责 |
|------|---------------|----------------|
| 数据分析 | 理解用户需求并规划分析步骤 | 执行实际的数据处理计算 |
| API 调用 | 解析请求参数并生成调用指令 | 执行业务逻辑和外部 API 调用 |
| 报告生成 | 组织信息结构并格式化输出 | 处理数据并生成报告内容 |
Python 代理位于 `agents/` 目录，聊天智能体通过工具调用接口可以触发 Python 代理执行具体的程序任务。
资料来源：[AGENTS.md]()
## 调用方式
### 在 VS Code Copilot 中调用
在 VS Code 的 Copilot 聊天界面中，直接输入 `@` 符号后跟智能体名称：
```plaintext
@calculating 什么是复利计算？
@texting 为新注册用户生成欢迎邮件
@orchestrator 分析销售数据并生成周报
```
### 通过命令行调用
使用 Claude Code CLI 在终端中调用特定的聊天智能体：
```bash
claude --p "What is 9 + 27" --agent calculating
claude --p "Say hello to the world" --agent texting
claude --p "Calculate 5^2 then greet me" --agent orchestrator
```
参数说明：
| 参数 | 说明 |
|------|------|
| `--p "<提示>"` | 要执行的指令 |
| `--agent <名称>` | 指定要使用的智能体 |
资料来源：[README.md]()
## 最佳实践
### 设计原则
1. **单一职责** - 每个智能体应专注于特定的任务领域
2. **清晰的边界** - 明确定义智能体的输入输出接口
3. **可组合性** - 设计易于组合的智能体，支持复杂工作流
4. **错误处理** - 在正文定义中包含错误处理和降级策略
### 安全注意事项
- 敏感操作应在正文约束中明确禁止
- 外部 API 调用必须通过配置管理，不硬编码凭证
- 委派行为应遵循最小权限原则
- 定期审查智能体的行为定义，确保符合安全策略
### 命名规范
| 类型 | 命名格式 | 示例 |
|------|----------|------|
| 智能体名称 | 纯小写 + 下划线 | `calculating`, `text_generator` |
| 文件名 | `.agent.md` | `calculating.agent.md` |
| 技能名称 | 纯小写 + 连字符 | `hello-world`, `data-analysis` |
## 参考资料
- [CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md) - 项目指令与规范
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md) - 智能体开发指南
- [README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md) - 项目整体架构
---
## 技能开发
### 相关页面
相关主题：[聊天智能体开发](#page-chat-agents), [Python智能体开发](#page-python-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
- [.claude/skills/hello-world/SKILL.md](https://github.com/chonlim92/claude-code-project-template/blob/main/.claude/skills/hello-world/SKILL.md)
- [.claude/skills/sum/SKILL.md](https://github.com/chonlim92/claude-code-project-template/blob/main/.claude/skills/sum/SKILL.md)
- [CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
- [README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
# 技能开发
## 概述
技能（Skill）是 Claude Code 项目模板中的一种可复用工作流机制，允许聊天代理按需调用预定义的功能模块。技能以 slash 命令（`/skill-name`）的形式暴露给用户和 AI 代理，实现标准化的任务执行流程。
在多代理系统架构中，技能是连接聊天代理与具体业务逻辑的桥梁。当用户在 VS Code Copilot 聊天中输入 `/hello-world` 或 `/sum` 时，系统会触发对应的技能定义执行相应操作。资料来源：[AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
## 技能在架构中的位置
```
┌─────────────────────────────────────────────────────────────┐
│ Claude Code CLI │
└─────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────────┐
│ VS Code Copilot Chat │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ @texting │ │@calculating │ │@orchestrator│ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
└─────────┼────────────────┼────────────────┼─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────┐
│ 技能层 (Skills) │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ /hello-world │ │ /sum │ ... │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ 工具层 (Tools) │
│ CLI 脚本和独立工具 │
└─────────────────────────────────────────────────┘
```
技能层位于聊天代理与底层工具之间，提供了一层抽象，使得代理能够以统一的方式调用各种功能。资料来源：[CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
## 技能类型
项目中的技能按调用方式可分为以下两类：
| 技能类型 | 存储位置 | 调用方式 | 示例 |
|---------|---------|---------|------|
| 聊天技能 | `.claude/skills//SKILL.md` | slash 命令（如 `/hello-world`） | `/sum`、`/hello-world` |
| 编排技能 | `.claude/agents/` 中的 `.agent.md` | `@agent-name` 引用 | `@orchestrator` |
资料来源：[AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
## 技能目录结构
每个技能占用一个独立目录，采用统一的文件命名规范：
```
.claude/skills/
└── /
└── SKILL.md # 技能定义文件（必须）
```
### 命名规范
- 目录名称应使用 kebab-case（小写字母，单词间用连字符分隔）
- 目录名称即 slash 命令名称（如 `hello-world` 目录对应 `/hello-world` 命令）
- SKILL.md 文件名必须全大写
资料来源：[README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
## SKILL.md 文件结构
技能定义文件采用 Markdown 格式，包含以下核心组成部分：
### 基本结构
```markdown
# 技能名称
简短描述技能的功能和用途。
## 触发条件
描述何时应该调用此技能。
## 执行步骤
1. 步骤一说明
2. 步骤二说明
3. 步骤三说明
## 输出格式
描述技能的返回结果格式。
```
### 技能执行流程
```mermaid
graph TD
A[用户输入 /skill-name] --> B{技能定义解析}
B -->|找到 SKILL.md| C[读取技能指令]
B -->|未找到| D[返回错误提示]
C --> E[执行预定义步骤]
E --> F[格式化输出结果]
F --> G[返回给调用方]
```
## 创建新技能
### 操作步骤
| 步骤 | 操作 | 说明 |
|-----|------|------|
| 1 | 创建目录 | 在 `.claude/skills/` 下创建 `/` 目录 |
| 2 | 编写 SKILL.md | 创建技能定义文件，编写指令和执行逻辑 |
| 3 | 测试技能 | 在 Claude Code 会话中输入 `/skill-name` 验证 |
| 4 | 文档更新 | 更新相关文档说明新技能用途 |
资料来源：[README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
### 技能定义示例：hello-world
以下是一个简单技能的完整定义：
```markdown
# Hello World 技能
打印一条问候世界的信息。
## 触发条件
用户请求打印问候语或测试系统响应时调用。
## 执行步骤
1. 输出标准问候语 "hello world"
2. 返回执行成功状态
## 输出格式
纯文本字符串：hello world
```
### 技能定义示例：sum
以下是一个带参数的技能定义：
```markdown
# Sum 技能
计算两个数字的和。
## 触发条件
用户请求计算两个数的加法时调用。
## 输入参数
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| a | number | 是 | 第一个加数 |
| b | number | 是 | 第二个加数 |
## 执行步骤
1. 解析输入的两个数字
2. 执行加法运算：a + b
3. 返回计算结果
## 输出格式
JSON 对象：
{
"result": ,
"input": { "a": , "b": }
}
```
## 技能与聊天代理的关系
技能可以被聊天代理（`.agent.md`）引用和使用。代理的前置元数据（YAML frontmatter）可以声明其可用的技能列表：
```yaml
---
name: orchestrator
description: 编排代理，负责委派任务给专业代理
tools: [Read, Edit, Bash, Glob]
agents: [texting, calculating]
---
```
当编排代理需要执行特定任务时，可以调用对应的技能。资料来源：[CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
### 代理执行规则
在委托给聊天代理时，必须遵循以下规则：
1. **完整读取代理定义** - 使用 `runSubagent` 或其他方式委托时，必须读取并遵循 `.agent.md` 主体中的完整行为指令
2. **不仅依赖描述** - 不能仅使用描述进行路由，必须遵循约束、方法步骤和技能检查程序
3. **遵循输出格式** - 包括必需输出格式（如无匹配技能时使用 ⚠️ 前缀）
资料来源：[CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
## 技能调用机制
### Slash 命令调用
用户直接在聊天输入框中输入技能名称：
```
/hello-world
/sum 5 3
```
### 代理内部调用
代理可以在执行过程中调用技能，形成技能链：
```mermaid
graph LR
A[用户请求] --> B[@orchestrator]
B --> C[/sum 技能]
C --> D[/hello-world 技能]
D --> E[返回结果]
```
## 最佳实践
### 技能设计原则
| 原则 | 说明 | 示例 |
|-----|------|------|
| 单一职责 | 每个技能只完成一个明确任务 | `/sum` 仅做加法运算 |
| 清晰命名 | 技能名称应自解释其功能 | `/fetch-github-repos` |
| 良好文档 | SKILL.md 中详细说明触发条件和输出格式 | - |
| 独立可测 | 技能应能独立测试和验证 | - |
### 目录组织建议
```
.claude/skills/
├── hello-world/
│ └── SKILL.md
├── sum/
│ └── SKILL.md
└── /
└── SKILL.md
```
### 技能与工具的区别
| 特性 | 技能 (Skill) | 工具 (Tool) |
|-----|-------------|-------------|
| 存储位置 | `.claude/skills/` | `tools/` |
| 调用方式 | slash 命令 `/name` | CLI 命令或 API |
| 定位 | 面向 AI 代理的工作流定义 | 面向自动化脚本的独立功能 |
| 灵活性 | 高度可定制，支持复杂逻辑 | 通常执行单一明确任务 |
资料来源：[AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
## 总结
技能系统为 Claude Code 项目提供了灵活的可复用工作流机制。通过在 `.claude/skills//SKILL.md` 中定义技能，开发者可以创建标准化的任务执行单元，供聊天代理和用户在交互过程中调用。技能系统与聊天代理、Python 代理、MCP 工具共同构成了项目的多层次自动化体系。
---
## MCP服务器配置
### 相关页面
相关主题：[项目介绍](#page-introduction)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/mcp/README.md)
- [README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
- [CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
# MCP服务器配置
## 概述
MCP（Model Context Protocol，模型上下文协议）服务器是本项目的核心组件之一，负责为AI代理提供与外部服务和数据源交互的能力。通过MCP服务器，Claude Code CLI可以安全地访问GitHub、数据库、API等外部资源。
```mermaid
graph TD
A[Agent 代理] --> B[Claude Code CLI]
B --> C[MCP Server MCP服务器]
C --> D[External Service 外部服务]
C --> E[Database 数据库]
C --> F[API 接口]
style C fill:#e1f5fe
style D fill:#fff3e0
style E fill:#fff3e0
style F fill:#fff3e0
```
**作用域范围：** MCP服务器配置支持三种作用域级别，分别用于不同的共享范围和使用场景。
| 作用域 | 参数 | 说明 |
|--------|------|------|
| 本地 | `--scope local` | 仅当前用户可用（默认） |
| 项目 | `--scope project` | 通过`.mcp.json`在项目内共享 |
| 用户 | `--scope user` | 所有项目全局共享 |
资料来源：[README.md:92]()
---
## MCP服务器架构
### 组件结构
根据项目约定，每个MCP服务器应满足以下要求：
- 提供清晰的工具描述（tool descriptions）以便于代理发现
- 优雅地处理错误并返回有意义的错误信息
- 可独立进行测试
```mermaid
graph LR
subgraph MCP目录结构
A[mcp/] --> B[server.py]
A --> C[工具实现]
A --> D[配置文件]
end
subgraph 运行时
B --> E[注册工具]
E --> F[暴露给代理]
end
```
资料来源：[mcp/README.md:1-11]()
---
## MCP服务器类型
### 远程MCP服务器
远程MCP服务器通过HTTP协议与外部服务通信，适合云端API服务集成。
```bash
# 添加远程MCP服务器（例如GitHub）
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer "}}'
```
### 本地MCP服务器
本地MCP服务器通过Docker容器运行，适合需要隔离环境的工具集成。
```bash
# 添加本地MCP服务器（Docker方式）
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN= -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
```
### 自定义项目MCP服务器
对于项目专用的MCP服务器，可以使用Python脚本直接运行。
```bash
# 添加自定义项目MCP服务器
claude mcp add-json mytools '{"command": "python", "args": ["mcp/server.py"], "env": {}}'
```
---
## MCP服务器管理命令
### 核心操作
| 命令 | 功能 |
|------|------|
| `claude mcp add` | 添加新的MCP服务器 |
| `claude mcp add-json` | 通过JSON配置添加MCP服务器 |
| `claude mcp list` | 列出所有已连接的MCP服务器 |
| `claude mcp get ` | 获取指定服务器的配置和健康状态 |
| `claude mcp remove` | 移除指定的MCP服务器 |
资料来源：[README.md:73-91]()
### 验证MCP配置
添加服务器后，应验证其状态：
```bash
# 确认服务器已显示并处于"connected"状态
claude mcp list
# 检查特定服务器的配置和健康状态
claude mcp get
```
---
## MCP工具开发规范
### 命名规范
MCP工具必须具有清晰、描述性的名称，以便代理发现和调用。
```python
# 示例工具定义结构
@mcp.tool()
def get_github_repos(owner: str) -> dict:
"""
获取指定用户的GitHub仓库列表
参数:
owner: GitHub用户名
返回:
包含仓库信息的字典列表
"""
# 实现逻辑
pass
```
### 错误处理
MCP工具应优雅地处理错误并返回有意义的错误信息：
| 错误场景 | 处理方式 |
|----------|----------|
| 网络超时 | 返回超时提示，建议重试 |
| 认证失败 | 返回认证错误提示，检查令牌 |
| 资源不存在 | 返回404和具体资源标识 |
| 限流 | 返回限流提示，包含重试时间 |
---
## 安全配置
### 令牌管理
> **安全警告：** 永远不要将令牌硬编码在代码中。所有敏感凭证应使用`.env`文件管理，并添加到`.gitignore`中。
```bash
# 正确做法：使用环境变量
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=
# 错误做法：避免这样做
claude mcp add-json github '{"url": "...", "key": "actual_token_here"}'
```
### 环境文件配置
```bash
# 创建.env文件
cp config/.env.example config/.env
# .gitignore应包含
.env
.mcp.json
```
资料来源：[README.md:97-100]()
---
## MCP与代理集成
### 代理调用流程
```mermaid
sequenceDiagram
participant User as 用户
participant Claude as Claude Code
participant MCP as MCP服务器
participant Service as 外部服务
User->>Claude: 发送请求
Claude->>MCP: 调用MCP工具
MCP->>Service: 请求外部服务
Service-->>MCP: 返回数据
MCP-->>Claude: 返回工具结果
Claude-->>User: 生成响应
```
### 聊天会话中的MCP访问
在Claude Code会话中，输入`/mcp`命令可查看所有已连接的服务器及其可用工具。
资料来源：[README.md:93-96]()
---
## 添加新MCP工具的步骤
| 步骤 | 操作 | 说明 |
|------|------|------|
| 1 | 实现工具 | 在`mcp/`目录下创建工具实现 |
| 2 | 注册工具 | 在服务器中注册新工具 |
| 3 | 添加描述 | 为工具添加清晰的文档字符串 |
| 4 | 独立测试 | 验证工具可独立运行 |
| 5 | 集成测试 | 与代理集成后进行端到端测试 |
资料来源：[CLAUDE.md:44-45]()
---
## 快速参考
### 完整配置示例
```bash
# 1. 添加GitHub MCP服务器
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer ghp_xxxxx"}}'
# 2. 列出所有服务器
claude mcp list
# 3. 验证服务器状态
claude mcp get github
# 4. 在会话中查看可用工具
/mcp
```
### 常见问题排查
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 服务器未显示 | 配置未生效 | 运行`claude mcp list`确认 |
| 连接失败 | 令牌无效 | 检查`.env`文件中的令牌 |
| 工具不可见 | 工具未注册 | 检查`mcp/server.py`注册状态 |
---
## CLI自动化工具
### 相关页面
相关主题：[Python自动化管道](#page-python-pipeline)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
- [CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
- [tools/README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/tools/README.md)
- [config/sum_numbers.yaml](https://github.com/chonlim92/claude-code-project-template/blob/main/config/sum_numbers.yaml)
- [agents/hello_world.py](https://github.com/chonlim92/claude-code-project-template/blob/main/agents/hello_world.py)
# CLI自动化工具
本页面介绍项目中CLI（命令行界面）自动化工具的整体架构、功能特性及使用方法，涵盖Claude Code CLI、Python自动化管道和独立CLI工具三大核心组件。
## 概述
CLI自动化工具是本项目的核心能力之一，通过命令行接口实现任务的自动化执行。系统支持三种主要的CLI自动化模式：Claude Code CLI命令执行、Python子进程管道调用、以及独立的命令行脚本工具。这些组件共同构成了从简单脚本到复杂多步骤自动化流程的完整工具链。
项目架构中，`tools/`目录存放独立的CLI工具脚本，`agents/`目录包含Python agent实现，而Claude Code CLI则提供与大语言模型交互的桥梁。资料来源：[README.md:1-10]()
## Claude Code CLI工具
Claude Code CLI是Anthropic提供的命令行工具，支持与Claude大语言模型进行交互式或自动化对话。该工具需要Node.js和npm环境支持，安装后可通过`claude`命令直接调用。资料来源：[README.md:18-35]()
### 交互式与非交互式模式
Claude Code CLI提供两种基本运行模式。交互式模式启动完整的对话会话，用户可在REPL环境中与AI进行实时对话：
```bash
claude
```
非交互式模式（管道模式）允许通过命令行参数直接传递指令，适合自动化脚本和CI/CD流程：
```bash
claude --p "Analyze the files in this directory and write a short summary to SUMMARY.md"
```
参数`-p`（或`--print`）表示非交互式执行，指令完成后自动退出而非停留在REPL状态。资料来源：[README.md:88-96]()
### 工具权限预批准机制
在自动化流水线中，没有人工实时响应确认提示，因此Claude Code提供了`--approvedTool`参数来预批准特定工具的使用权限：
```bash
claude --p "Refactor utils.py" --approvedTool edit --approvedTool bash
```
该机制允许指定白名单内的工具（如`edit`、`bash`、`read`等）可以直接执行而无需人工确认。预批准工具是实现完全无人值守执行的关键配置。资料来源：[README.md:97-101]()
### 指定Agent执行
Claude Code支持运行预定义的chat agent，通过`--agent`参数指定：
```bash
claude --p "What is 9 + 27" --agent calculating
claude --p "Say hello to the world" --agent texting
claude --p "Calculate 5^2 then greet me" --agent orchestrator
```
预定义的chat agent包括`@texting`（文本生成）、`@calculating`（数学运算）和`@orchestrator`（任务编排）。agent通过`.claude/agents/`目录下的`.agent.md`文件定义。资料来源：[README.md:102-107]()
### MCP服务器管理命令
Claude Code集成了MCP（Model Context Protocol）协议，支持通过CLI管理MCP服务器：
```bash
# 列出所有MCP服务器
claude mcp list
# 查看特定服务器的配置和健康状态
claude mcp get
# 移除服务器
claude mcp remove
```
MCP服务器可以是远程HTTP服务或本地Docker容器，支持添加JSON配置或命令式配置。资料来源：[README.md:56-83]()
## Python自动化管道
除了直接调用CLI命令，项目还提供了Python封装接口，通过`subprocess`模块实现Claude Code的编程式调用。这种方式适合需要与Python应用深度集成的自动化场景。资料来源：[README.md:111-130]()
### 核心实现函数
项目定义了`run_claude_pipeline`函数作为Python与Claude Code之间的桥梁：
```python
import subprocess
import os
def run_claude_pipeline(prompt_text: str, agent: str = None) -> str:
env = os.environ.copy()
command = [
"claude", "--p", prompt_text,
"--approvedTool", "edit",
"--approvedTool", "bash",
"--approvedTool", "read",
]
if agent:
command.extend(["--agent", agent])
try:
result = subprocess.run(
command,
capture_output=True,
text=True,
check=True,
env=env
)
return result.stdout
except subprocess.CalledProcessError as e:
return e.stderr
```
该函数接受提示文本和可选的agent名称参数，返回命令的标准输出。错误信息通过`stderr`捕获并返回。资料来源：[README.md:111-130]()
### 环境变量传递
函数使用`os.environ.copy()`复制当前环境变量，确保Python进程的环境配置（如API密钥、路径设置）能够传递给子进程。这种模式保持了环境的一致性，同时允许在需要时添加或覆盖特定变量。资料来源：[README.md:113]()
## 独立CLI工具
`tools/`目录下的CLI工具是独立运行的脚本，具有两个关键特性：可以独立通过命令行执行，也可以被agents调用。这种设计确保了工具的灵活性和可复用性。资料来源：[tools/README.md:1-10]()
### 设计原则
每个CLI工具应满足以下设计要求：
| 要求 | 说明 |
|------|------|
| 独立运行 | 脚本可直接通过命令行执行，无需其他依赖 |
| 参数配置 | 支持命令行参数传入配置 |
| 结构化输出 | 返回JSON格式结果，便于agent解析 |
CLI工具优先使用JSON作为输出格式，因为结构化数据更易于被AI agent解析和处理。资料来源：[tools/README.md:7-9]()
### Python Agents的命令行接口
Python agents作为独立脚本运行时采用简单直接的设计模式。以`hello_world.py`为例：
```python
"""Agent that prints hello world."""
def run():
print("hello world")
if __name__ == "__main__":
run()
```
每个agent包含一个`run()`函数作为入口点，`if __name__ == "__main__"`块确保模块既可独立运行也可被导入使用。运行agent只需执行Python脚本并传入所需参数。资料来源：[agents/hello_world.py:1-10]()
### Agent配置管理
Python agents的配置通过`config/`目录下的YAML文件管理。例如`sum_numbers.yaml`定义了求和agent的输入参数：
```yaml
name: sum_numbers
description: Agent that calculates the sum of two numbers
input:
a: 0
b: 0
```
配置文件采用标准YAML格式，包含agent名称、描述和输入参数定义。这种配置与代码分离的设计允许在不修改源码的情况下调整agent行为。资料来源：[config/sum_numbers.yaml:1-8]()
## 工具组合与工作流
CLI自动化工具支持多种组合方式以适应不同场景：
```mermaid
graph TD
A[人工触发/定时任务] --> B[Claude Code CLI]
A --> C[Python subprocess]
A --> D[直接运行Python Agent]
B --> E[Chat Agents]
B --> F[MCP Servers]
C --> G[run_claude_pipeline函数]
G --> E
G --> F
D --> H[Python Agent执行]
H --> I[调用CLI工具]
I --> J[返回结构化结果]
E --> K[响应输出]
F --> L[外部服务集成]
J --> K
```
### 典型使用场景
| 场景 | 推荐工具 | 原因 |
|------|----------|------|
| 交互式代码审查 | Claude Code CLI交互模式 | 实时对话和迭代修改 |
| CI/CD自动化 | Claude Code `--p` + `--approvedTool` | 无人值守执行 |
| 深度Python集成 | subprocess管道调用 | 与现有Python应用结合 |
| 简单脚本任务 | 独立Python agent | 轻量级、无依赖 |
| 外部服务访问 | MCP服务器 | 标准化的工具暴露协议 |
## 环境配置与安全
CLI工具涉及敏感信息（如API密钥、访问令牌），项目制定了严格的安全规范。所有密钥必须存储在`.env`文件中，且`.env`和`.mcp.json`必须添加到`.gitignore`禁止提交到版本控制。资料来源：[README.md:85]()
配置文件的分离设计确保了本地开发环境与生产环境的安全隔离：
```bash
# 安装依赖
pip install -r requirements.txt
# 配置环境
cp config/.env.example config/.env
# 编辑.env填入实际凭证
```
依赖项包括`python-dotenv`（环境变量加载）、`pyyaml`（配置解析）和`pytest`（测试框架）。资料来源：[requirements.txt:1-4]()
## 扩展CLI工具
向项目中添加新的CLI工具需遵循既定的文件组织规范：
| 组件类型 | 创建步骤 |
|----------|----------|
| CLI工具 | 在`tools/`创建脚本，确保独立可运行 |
| Python Agent | 在`agents/`创建`.py`文件 + `config/`创建对应`.yaml` |
| Chat Agent | 在`.claude/agents/`创建`.agent.md` + YAML frontmatter |
| MCP工具 | 在`mcp/`实现，注册到server，添加工具描述 |
添加CLI工具时应确保其可独立测试，这是集成到自动化流程前的质量保障。资料来源：[AGENTS.md:47-52]()
---
## Python自动化管道
### 相关页面
相关主题：[CLI自动化工具](#page-cli-automation), [聊天智能体开发](#page-chat-agents)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/chonlim92/claude-code-project-template/blob/main/README.md)
- [CLAUDE.md](https://github.com/chonlim92/claude-code-project-template/blob/main/CLAUDE.md)
- [AGENTS.md](https://github.com/chonlim92/claude-code-project-template/blob/main/AGENTS.md)
# Python自动化管道
## 概述
Python自动化管道（Python Automated Pipeline）是`claude-code-project-template`项目中的核心组件之一，它通过Python的`subprocess`模块实现对Claude Code CLI的非交互式程序化调用。该管道允许开发者在Python应用程序或CI/CD流程中自动化执行Claude Code任务，无需人工干预即可完成代码分析、编辑和执行操作。
此功能的主要价值在于将Claude Code强大的AI辅助能力集成到现有的Python工作流中，使得批量处理、自动化测试和持续集成场景下的代码任务执行成为可能。资料来源：[README.md:1-10]()
## 架构设计
### 组件交互关系
Python自动化管道采用分层架构，各组件之间通过标准输入/输出流进行通信：
```mermaid
graph TD
A[Python应用] --> B[run_claude_pipeline 函数]
B --> C[subprocess.run]
C --> D[Claude Code CLI]
D --> E[--p 参数
非交互模式]
D --> F[--approvedTool
预授权工具]
D --> G[--agent
指定代理]
G --> H[Chat Agent
.claude/agents/]
H --> I[@calculating]
H --> J[@texting]
H --> K[@orchestrator]
```
### 管道执行流程
```mermaid
flowchart TD
A[启动run_claude_pipeline] --> B{agent参数
是否指定?}
B -->|是| C[添加--agent参数]
B -->|否| D[跳过agent配置]
C --> E[构建command列表]
D --> E
E --> F[复制环境变量]
F --> G[执行subprocess.run]
G --> H{执行成功?}
H -->|是| I[返回stdout输出]
H -->|否| J[捕获CalledProcessError]
J --> K[打印错误诊断信息]
K --> L[返回空字符串]
```
## 核心函数
### run_claude_pipeline
该函数是Python自动化管道的入口点，负责构建和执行Claude Code命令。
**函数签名：**
```python
def run_claude_pipeline(prompt_text: str, agent: str = None) -> str
```
**参数说明：**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `prompt_text` | `str` | 是 | - | 要执行的任务提示文本 |
| `agent` | `str` | 否 | `None` | 可选指定的聊天代理名称 |
**返回值：**
| 类型 | 说明 |
|------|------|
| `str` | 成功时返回Claude Code的标准输出；失败时返回空字符串 |
**源码实现：**
```python
# 资料来源：[README.md:120-150]()
def run_claude_pipeline(prompt_text: str, agent: str = None) -> str:
env = os.environ.copy()
command = [
"claude", "--p", prompt_text,
"--approvedTool", "edit",
"--approvedTool", "bash",
"--approvedTool", "read",
]
if agent:
command.extend(["--agent", agent])
try:
result = subprocess.run(
command,
capture_output=True,
text=True,
check=True,
env=env
)
return result.stdout
except subprocess.CalledProcessError as e:
print(f"Pipeline error status code: {e.returncode}")
print(f"Error Diagnostic Info:\n{e.stderr}")
return ""
```
### 预授权工具
管道默认预授权以下三个工具，确保Claude Code在自动化执行过程中不会因等待用户确认而阻塞：
| 工具名称 | 功能描述 |
|----------|----------|
| `edit` | 文件编辑操作 |
| `bash` | 执行Shell命令 |
| `read` | 读取文件内容 |
资料来源：[README.md:132-134]()
## 使用示例
### 示例一：执行默认Claude任务
最基本的用法，无需指定代理：
```python
import subprocess
import os
def run_claude_pipeline(prompt_text: str, agent: str = None) -> str:
env = os.environ.copy()
command = [
"claude", "--p", prompt_text,
"--approvedTool", "edit",
"--approvedTool", "bash",
"--approvedTool", "read",
]
if agent:
command.extend(["--agent", agent])
try:
result = subprocess.run(
command,
capture_output=True,
text=True,
check=True,
env=env
)
return result.stdout
except subprocess.CalledProcessError as e:
print(f"Pipeline error status code: {e.returncode}")
print(f"Error Diagnostic Info:\n{e.stderr}")
return ""
if __name__ == "__main__":
output = run_claude_pipeline("Review python script syntax errors in the current directory.")
print(f"Output:\n{output}")
```
资料来源：[README.md:150-170]()
### 示例二：调用特定聊天代理
通过`agent`参数指定具体的聊天代理执行任务：
```python
if __name__ == "__main__":
# 调用calculating代理执行数学运算
output = run_claude_pipeline("What is 9 + 27", agent="calculating")
print(f"Agent Output:\n{output}")
```
可用的聊天代理包括：
| 代理名称 | 用途 | 调用方式 |
|----------|------|----------|
| `@calculating` | 数学运算和算术计算 | `agent="calculating"` |
| `@texting` | 文本生成、问候语和消息 | `agent="texting"` |
| `@orchestrator` | 委托给专家代理协调任务 | `agent="orchestrator"` |
资料来源：[README.md:55-65]()
## 环境配置
### 环境变量处理
管道通过`os.environ.copy()`复制当前进程的环境变量，确保Claude Code能够访问必要的系统配置：
```python
env = os.environ.copy()
```
这种方法的优势在于：
- 保留所有现有的环境变量
- 允许在`env`字典中添加或覆盖特定变量
- 避免修改父进程的环境状态
### 执行环境要求
| 要求 | 说明 |
|------|------|
| Python版本 | Python 3.x |
| 外部依赖 | Claude Code CLI已安装并可在PATH中访问 |
| 系统要求 | Node.js和npm（Claude Code依赖） |
资料来源：[CLAUDE.md:1-15]()
## 错误处理机制
管道实现了健壮的错误处理策略，通过捕获`subprocess.CalledProcessError`异常来诊断执行失败：
```python
except subprocess.CalledProcessError as e:
print(f"Pipeline error status code: {e.returncode}")
print(f"Error Diagnostic Info:\n{e.stderr}")
return ""
```
**错误处理流程：**
| 异常属性 | 用途 |
|----------|------|
| `e.returncode` | 返回退出状态码，用于判断失败类型 |
| `e.stderr` | 捕获标准错误输出，提供详细诊断信息 |
| 返回值 | 失败时返回空字符串`""`，避免调用方处理None |
## 集成应用场景
### CI/CD流水线集成
Python自动化管道可无缝集成到持续集成/持续部署流程中：
```yaml
# 示例：CI配置文件
stages:
- code-review
code-review:
script:
- python -c "
from agents.sum_numbers import run
run(3, 5)
"
```
### 批量任务处理
通过循环调用实现批量代码分析：
```python
files_to_analyze = ["utils.py", "helpers.py", "models.py"]
for file in files_to_analyze:
result = run_claude_pipeline(f"Analyze {file} for potential bugs")
process_result(result)
```
### 多代理协同工作
利用`orchestrator`代理协调多个专家代理完成任务：
```python
result = run_claude_pipeline(
"Calculate 5^2 then greet me",
agent="orchestrator"
)
```
## 最佳实践
### 安全考虑
| 实践 | 说明 |
|------|------|
| 令牌管理 | 敏感信息通过环境变量传递，不硬编码在代码中 |
| 工具授权 | 仅预授权必要的工具，减少安全风险 |
| 错误日志 | 保留错误诊断信息便于问题排查 |
### 性能优化
- **批量处理**：将多个相关任务合并为单一提示
- **环境缓存**：避免重复创建环境变量副本
- **超时控制**：为长时间运行的任务设置适当超时
资料来源：[AGENTS.md:1-30]()
## 相关模块
| 模块 | 路径 | 功能 |
|------|------|------|
| Python Agents | `agents/` | 可执行的Python代理脚本 |
| Chat Agents | `.claude/agents/` | VS Code Copilot角色定义 |
| MCP服务器 | `mcp/` | Model Context Protocol服务器实现 |
| CLI工具 | `tools/` | 独立运行的命令行工具 |
资料来源：[CLAUDE.md:10-20]()
## 扩展阅读
- [Claude Code安装与使用文档](docs/claude-code-installation-usage.md)
- [MCP服务器配置指南](docs/mcp-github-server-install-claude.md)
- [项目主README](README.md)
---
---
## Doramagic 踩坑日志
项目：chonlim92/claude-code-project-template
摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1230815533 | https://github.com/chonlim92/claude-code-project-template | host_targets=mcp_host, claude, claude_code
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1230815533 | https://github.com/chonlim92/claude-code-project-template | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1230815533 | https://github.com/chonlim92/claude-code-project-template | last_activity_observed missing
## 4. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1230815533 | https://github.com/chonlim92/claude-code-project-template | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1230815533 | https://github.com/chonlim92/claude-code-project-template | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1230815533 | https://github.com/chonlim92/claude-code-project-template | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1230815533 | https://github.com/chonlim92/claude-code-project-template | release_recency=unknown