refactor(officefile): 按 md/latex/word 三层结构重组文档目录
将 Markdown 源文件移入 md/，LaTeX 工作目录保留在 latex/， Word 导出移入 word/；删除临时脚本、调试截图和空 stub。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,348 @@
|
||||
# 实践案例00：搭建你的第一个空间AI助手
|
||||
|
||||
## 目标
|
||||
|
||||
通过本实践，你将：
|
||||
1. 配置Claude Code环境
|
||||
2. 创建一个简单的空间查询技能
|
||||
3. 理解Agent如何调用工具
|
||||
4. 建立对后续学习的信心
|
||||
|
||||
---
|
||||
|
||||
## 步骤1：环境准备
|
||||
|
||||
### 安装Claude Code
|
||||
|
||||
```bash
|
||||
# 使用npm安装
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
|
||||
# 验证安装
|
||||
claude --version
|
||||
```
|
||||
|
||||
### 配置API密钥
|
||||
|
||||
```bash
|
||||
# 设置API密钥
|
||||
claude config set api_key your_anthropic_api_key
|
||||
|
||||
# 或使用环境变量
|
||||
export ANTHROPIC_API_KEY=your_key
|
||||
```
|
||||
|
||||
### 安装Python依赖
|
||||
|
||||
```bash
|
||||
# 创建虚拟环境
|
||||
python -m venv venv
|
||||
source venv/bin/activate # Linux/Mac
|
||||
# 或
|
||||
venv\Scripts\activate # Windows
|
||||
|
||||
# 安装依赖
|
||||
pip install geopandas shapely matplotlib pandas
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步骤2：创建空间查询技能
|
||||
|
||||
### 2.1 创建技能目录
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/skills
|
||||
```
|
||||
|
||||
### 2.2 编写技能文件
|
||||
|
||||
创建 `.claude/skills/spatial-query.md`：
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: spatial-query
|
||||
description: 执行基础空间查询和分析
|
||||
parameters:
|
||||
- data_file: 空间数据文件路径
|
||||
- query_type: 查询类型（buffer/intersect/nearest）
|
||||
- distance: 缓冲距离（用于buffer查询）
|
||||
---
|
||||
|
||||
## 空间查询技能
|
||||
|
||||
当用户需要进行空间查询时，使用此技能。
|
||||
|
||||
### 支持的查询类型
|
||||
|
||||
1. **buffer**: 缓冲区分析
|
||||
2. **intersect**: 相交分析
|
||||
3. **nearest**: 最近邻查找
|
||||
|
||||
### 执行流程
|
||||
|
||||
1. 读取空间数据
|
||||
2. 根据查询类型执行相应操作
|
||||
3. 返回结果和统计信息
|
||||
4. 可选：生成可视化
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步骤3：实现技能逻辑
|
||||
|
||||
创建 `examples/spatial_helper.py`：
|
||||
|
||||
```python
|
||||
"""
|
||||
简单的空间分析助手
|
||||
演示AI如何理解并执行空间任务
|
||||
"""
|
||||
|
||||
import geopandas as gpd
|
||||
from shapely.geometry import Point
|
||||
import matplotlib.pyplot as plt
|
||||
|
||||
class SpatialHelper:
|
||||
"""空间分析助手类"""
|
||||
|
||||
def __init__(self, data_path=None):
|
||||
self.data = None
|
||||
if data_path:
|
||||
self.load_data(data_path)
|
||||
|
||||
def load_data(self, path):
|
||||
"""加载空间数据"""
|
||||
try:
|
||||
self.data = gpd.read_file(path)
|
||||
return f"成功加载 {len(self.data)} 个空间要素"
|
||||
except Exception as e:
|
||||
return f"加载失败: {str(e)}"
|
||||
|
||||
def buffer_analysis(self, distance, crs=None):
|
||||
"""缓冲区分析"""
|
||||
if self.data is None:
|
||||
return "请先加载数据"
|
||||
|
||||
if crs:
|
||||
# 转换到适合距离计算的坐标系
|
||||
self.data = self.data.to_crs(crs)
|
||||
|
||||
buffered = self.data.buffer(distance)
|
||||
result = gpd.GeoDataFrame(geometry=buffered, crs=self.data.crs)
|
||||
|
||||
return {
|
||||
'count': len(result),
|
||||
'total_area': result.geometry.area.sum(),
|
||||
'geometry': result
|
||||
}
|
||||
|
||||
def intersect_analysis(self, other_data):
|
||||
"""相交分析"""
|
||||
if self.data is None:
|
||||
return "请先加载数据"
|
||||
|
||||
intersection = self.data.intersection(other_data)
|
||||
valid_results = intersection[~intersection.is_empty]
|
||||
|
||||
return {
|
||||
'intersecting_count': len(valid_results),
|
||||
'geometries': valid_results
|
||||
}
|
||||
|
||||
def nearest_neighbor(self, point, n=1):
|
||||
"""最近邻查找"""
|
||||
if self.data is None:
|
||||
return "请先加载数据"
|
||||
|
||||
if isinstance(point, (tuple, list)):
|
||||
point = Point(point)
|
||||
|
||||
distances = self.data.geometry.distance(point)
|
||||
nearest_indices = distances.nsmallest(n).index
|
||||
|
||||
results = []
|
||||
for idx in nearest_indices:
|
||||
results.append({
|
||||
'index': idx,
|
||||
'distance': distances[idx],
|
||||
'geometry': self.data.loc[idx].geometry
|
||||
})
|
||||
|
||||
return results
|
||||
|
||||
def summarize(self):
|
||||
"""数据摘要"""
|
||||
if self.data is None:
|
||||
return "请先加载数据"
|
||||
|
||||
return {
|
||||
'count': len(self.data),
|
||||
'crs': str(self.data.crs),
|
||||
'bounds': self.data.total_bounds,
|
||||
'geometry_types': self.data.geometry.type.value_counts().to_dict()
|
||||
}
|
||||
|
||||
def visualize(self, output_path=None):
|
||||
"""可视化"""
|
||||
if self.data is None:
|
||||
return "请先加载数据"
|
||||
|
||||
fig, ax = plt.subplots(figsize=(10, 10))
|
||||
self.data.plot(ax=ax, alpha=0.5, edgecolor='k')
|
||||
ax.set_title('Spatial Data Visualization')
|
||||
ax.set_axis_off()
|
||||
|
||||
if output_path:
|
||||
plt.savefig(output_path, bbox_inches='tight', dpi=300)
|
||||
return f"图表已保存到 {output_path}"
|
||||
|
||||
plt.show()
|
||||
return "图表已显示"
|
||||
|
||||
# 创建一个示例数据集用于测试
|
||||
def create_sample_data():
|
||||
"""创建示例空间数据"""
|
||||
import numpy as np
|
||||
|
||||
np.random.seed(42)
|
||||
|
||||
# 创建一些随机点
|
||||
points = [Point(np.random.uniform(-100, 100),
|
||||
np.random.uniform(-100, 100))
|
||||
for _ in range(20)]
|
||||
|
||||
# 转换为GeoDataFrame
|
||||
gdf = gpd.GeoDataFrame({
|
||||
'id': range(20),
|
||||
'value': np.random.randint(1, 100, 20),
|
||||
'category': np.random.choice(['A', 'B', 'C'], 20)
|
||||
}, geometry=points, crs='EPSG:4326')
|
||||
|
||||
# 保存为GeoJSON
|
||||
gdf.to_file('sample_data.geojson', driver='GeoJSON')
|
||||
return gdf
|
||||
|
||||
if __name__ == "__main__":
|
||||
# 创建示例数据
|
||||
print("创建示例数据...")
|
||||
create_sample_data()
|
||||
|
||||
# 测试SpatialHelper
|
||||
print("\n初始化空间助手...")
|
||||
helper = SpatialHelper('sample_data.geojson')
|
||||
|
||||
print("\n数据摘要:")
|
||||
print(helper.summarize())
|
||||
|
||||
print("\n缓冲区分析:")
|
||||
buffer_result = helper.buffer_analysis(10)
|
||||
print(f"缓冲区数量: {buffer_result['count']}")
|
||||
print(f"总缓冲面积: {buffer_result['total_area']:.2f}")
|
||||
|
||||
print("\n最近邻查找:")
|
||||
nearest = helper.nearest_neighbor((0, 0), n=3)
|
||||
for i, n in enumerate(nearest, 1):
|
||||
print(f" {i}. 距离: {n['distance']:.2f}")
|
||||
|
||||
print("\n生成可视化...")
|
||||
print(helper.visualize('spatial_visualization.png'))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步骤4：在Claude Code中使用
|
||||
|
||||
### 4.1 启动Claude Code
|
||||
|
||||
```bash
|
||||
cd /path/to/CC4SI
|
||||
claude
|
||||
```
|
||||
|
||||
### 4.2 与Claude对话
|
||||
|
||||
```
|
||||
你: 我有一个空间数据文件sample_data.geojson，帮我分析一下
|
||||
|
||||
Claude: 让我先读取这个文件看看...
|
||||
|
||||
[读取 sample_data.geojson]
|
||||
|
||||
这是一个包含20个点要素的GeoJSON文件，坐标系统为WGS84 (EPSG:4326)。
|
||||
每个点都有id、value和category属性。
|
||||
|
||||
你想要进行什么分析？
|
||||
|
||||
你: 找出距离原点最近的3个点
|
||||
|
||||
Claude: 我来帮你找出距离原点最近的点。
|
||||
|
||||
[调用 spatial-query 技能]
|
||||
|
||||
结果：
|
||||
1. 最近点 (id=7): 距离约 15.2 单位
|
||||
2. 第二近点 (id=12): 距离约 23.8 单位
|
||||
3. 第三近点 (id=3): 距离约 31.5 单位
|
||||
|
||||
需要我生成可视化吗？
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步骤5：理解工作原理
|
||||
|
||||
### AI系统的思考过程
|
||||
|
||||
```
|
||||
用户请求 ──→ [意图识别] ──→ [任务分解]
|
||||
│ │
|
||||
↓ ↓
|
||||
这是空间查询 需要执行：
|
||||
任务 1. 加载数据
|
||||
2. 计算距离
|
||||
3. 排序取前N
|
||||
│ │
|
||||
↓ ↓
|
||||
[选择技能] ──→ [调用工具]
|
||||
│ │
|
||||
↓ ↓
|
||||
spatial-query spatial_helper.py
|
||||
│ │
|
||||
└───────┬───────┘
|
||||
↓
|
||||
[整合结果]
|
||||
↓
|
||||
[返回用户]
|
||||
```
|
||||
|
||||
### 关键概念验证
|
||||
|
||||
| 概念 | 实践体现 |
|
||||
|-----|---------|
|
||||
| Agent | Claude Code作为智能体，理解意图并协调执行 |
|
||||
| Skill | spatial-query技能封装了空间分析能力 |
|
||||
| Tool | spatial_helper.py是具体实现工具 |
|
||||
|
||||
---
|
||||
|
||||
## 反思问题
|
||||
|
||||
1. **理解验证**：你能在脑海中复述一遍AI执行这个任务的流程吗？
|
||||
|
||||
2. **扩展思考**：如果要让这个助手支持更多空间操作，应该如何设计？
|
||||
|
||||
3. **局限性**：当前实现有哪些不足？如何改进？
|
||||
|
||||
4. **迁移应用**：这个模式可以应用到你的专业领域吗？
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
完成这个实践后，你已经：
|
||||
- ✅ 配置了Claude Code环境
|
||||
- ✅ 创建了第一个空间分析技能
|
||||
- ✅ 理解了Agent的基本工作方式
|
||||
|
||||
准备好进入下一章：**01-foundations（基础原理）**
|
||||
Reference in New Issue
Block a user