pengxiao
219232de74
以讲义内容为骨架迁移到标准目录格式： - officefile/ 主内容（12章 + 附录 + CC4SI补充） - dofile/ 代码示例（11个Python脚本） - data/ 图片资源 - output/ 生成输出（忽略） - Archive/ 归档旧目录（忽略） - .claude/skills/ 保留markdown-to-docx工具链 - .pandoc/ 保留CSL和本地化配置 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
328 lines
5.6 KiB
Markdown
328 lines
5.6 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你有兴趣为《Claude Code for Spatial Intelligence and Autonomous Design》做出贡献！
|
||
|
||
---
|
||
|
||
## 如何贡献
|
||
|
||
### 报告问题
|
||
|
||
如果你发现了书中的错误或有改进建议：
|
||
|
||
1. 在GitHub Issues中搜索是否已有相关问题
|
||
2. 如果没有，创建新Issue并包含：
|
||
- 清晰的标题
|
||
- 错误位置（章节、文件）
|
||
- 问题描述
|
||
- 建议的改进方式
|
||
- 相关标签（bug, enhancement, content等）
|
||
|
||
### 提交内容
|
||
|
||
#### 内容贡献类型
|
||
|
||
1. **修正错误**
|
||
- 事实错误
|
||
- 代码错误
|
||
- 排版问题
|
||
|
||
2. **新增内容**
|
||
- 新的示例代码
|
||
- 新的案例分析
|
||
- 新的实践项目
|
||
|
||
3. **改进现有内容**
|
||
- 更好的解释
|
||
- 更清晰的代码
|
||
- 更好的组织
|
||
|
||
4. **翻译**
|
||
- 英文内容的中译
|
||
- 中文内容的英译
|
||
|
||
#### 提交流程
|
||
|
||
```bash
|
||
# 1. Fork仓库
|
||
# 点击GitHub上的Fork按钮
|
||
|
||
# 2. 克隆你的fork
|
||
git clone https://github.com/your-username/CC4SI.git
|
||
cd CC4SI
|
||
|
||
# 3. 创建分支
|
||
git checkout -b feature/your-feature-name
|
||
|
||
# 4. 做出修改
|
||
# 编辑文件...
|
||
|
||
# 5. 提交修改
|
||
git add .
|
||
git commit -m "描述你的修改"
|
||
|
||
# 6. 推送到你的fork
|
||
git push origin feature/your-feature-name
|
||
|
||
# 7. 创建Pull Request
|
||
# 在GitHub上创建PR
|
||
```
|
||
|
||
#### 提交信息规范
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
**类型（type）**：
|
||
- `fix`: 修复bug
|
||
- `feat`: 新功能
|
||
- `docs`: 文档修改
|
||
- `style`: 格式修改
|
||
- `refactor`: 代码重构
|
||
- `test`: 测试相关
|
||
- `chore`: 构建/工具相关
|
||
|
||
**示例**：
|
||
```
|
||
fix(01-foundations): 修正状态机示例中的变量名错误
|
||
|
||
- 将 `state_machine` 改为 `workflow_state`
|
||
- 更新相关注释
|
||
|
||
Closes #123
|
||
```
|
||
|
||
---
|
||
|
||
## 内容规范
|
||
|
||
### Markdown格式
|
||
|
||
```markdown
|
||
# 一级标题（章节标题）
|
||
|
||
## 二级标题（小节标题）
|
||
|
||
### 三级标题（子小节）
|
||
|
||
#### 四级标题（通常不需要）
|
||
|
||
**粗体**用于强调
|
||
*斜体*用于术语
|
||
`代码`使用反引号
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
Python代码示例应遵循：
|
||
|
||
1. **PEP 8**风格指南
|
||
2. **类型提示**：函数签名包含类型
|
||
3. **文档字符串**：重要函数有docstring
|
||
4. **注释**：关键逻辑有解释
|
||
|
||
```python
|
||
from typing import List, Dict, Optional
|
||
|
||
def analyze_ecological_network(
|
||
sources: List[Dict],
|
||
resistance_surface: np.ndarray,
|
||
threshold: float = 0.5
|
||
) -> Dict:
|
||
"""
|
||
分析生态网络
|
||
|
||
Args:
|
||
sources: 源地列表
|
||
resistance_surface: 阻力面
|
||
threshold: 连接阈值
|
||
|
||
Returns:
|
||
分析结果字典
|
||
"""
|
||
# 实现逻辑...
|
||
pass
|
||
```
|
||
|
||
### 示例代码要求
|
||
|
||
1. **可运行**：示例代码应该能直接运行
|
||
2. **自包含**：包含必要的import
|
||
3. **有输出**：展示预期输出
|
||
4. **有注释**：解释关键步骤
|
||
|
||
### 图表和可视化
|
||
|
||
优先使用代码生成图表：
|
||
|
||
```python
|
||
import matplotlib.pyplot as plt
|
||
|
||
# 创建图表
|
||
fig, ax = plt.subplots(figsize=(10, 6))
|
||
ax.plot([1, 2, 3], [1, 4, 9])
|
||
ax.set_title("示例图表")
|
||
ax.set_xlabel("X轴")
|
||
ax.set_ylabel("Y轴")
|
||
|
||
# 保存（如果需要）
|
||
# plt.savefig('output.png', dpi=300)
|
||
|
||
plt.show()
|
||
```
|
||
|
||
---
|
||
|
||
## 写作指南
|
||
|
||
### 章节模板
|
||
|
||
每章遵循以下结构：
|
||
|
||
```markdown
|
||
# 章节标题
|
||
|
||
## 核心问题
|
||
> 用1-2个引人思考的问题开场
|
||
|
||
## 概念讲解
|
||
（原理阐述，配合示例）
|
||
|
||
## 设计原理
|
||
（为什么这样设计，权衡是什么）
|
||
|
||
## 代码示例
|
||
```python
|
||
# 可运行代码
|
||
```
|
||
|
||
## 案例分析
|
||
（真实项目解析）
|
||
|
||
## 反思与延伸
|
||
### 思考问题
|
||
### 延伸阅读
|
||
|
||
## 关键要点
|
||
（总结本章核心）
|
||
```
|
||
|
||
### 语言风格
|
||
|
||
1. **清晰直接**：避免冗长的句子
|
||
2. **专业准确**：术语使用正确
|
||
3. **读者友好**：从读者角度写作
|
||
4. **主动语态**：多用主动语态
|
||
|
||
---
|
||
|
||
## 实践项目规范
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
projects/project-name/
|
||
├── README.md # 项目说明
|
||
├── requirements.txt # 依赖
|
||
├── data/ # 示例数据
|
||
├── src/ # 源代码
|
||
│ └── __init__.py
|
||
├── notebooks/ # Jupyter notebooks（可选）
|
||
├── tests/ # 测试
|
||
│ └── __init__.py
|
||
└── outputs/ # 预期输出
|
||
```
|
||
|
||
### README规范
|
||
|
||
```markdown
|
||
# 项目名称
|
||
|
||
## 目标
|
||
（项目要达成的目标）
|
||
|
||
## 涉及技术
|
||
（列表说明使用的技术和方法）
|
||
|
||
## 实现步骤
|
||
1. 步骤一
|
||
2. 步骤二
|
||
...
|
||
|
||
## 运行方法
|
||
```bash
|
||
# 命令示例
|
||
```
|
||
|
||
## 预期输出
|
||
（展示预期结果）
|
||
|
||
## 扩展方向
|
||
（可选的改进方向）
|
||
```
|
||
|
||
---
|
||
|
||
## 审查流程
|
||
|
||
### Pull Request检查清单
|
||
|
||
提交PR前确认：
|
||
|
||
- [ ] 代码符合风格规范
|
||
- [ ] 包含必要的文档
|
||
- [ ] 示例代码可运行
|
||
- [ ] 没有新的警告
|
||
- [ ] 更新了相关文档
|
||
|
||
### 审查标准
|
||
|
||
PR将被评估：
|
||
|
||
1. **准确性**：内容是否正确
|
||
2. **清晰性**：是否易于理解
|
||
3. **完整性**：是否有遗漏
|
||
4. **一致性**：与现有内容风格一致
|
||
5. **价值**：是否为读者增加价值
|
||
|
||
---
|
||
|
||
## 许可
|
||
|
||
贡献的内容将遵循项目的许可证：CC BY-NC-SA 4.0
|
||
|
||
贡献即表示你同意：
|
||
- 你的贡献将按照此许可证发布
|
||
- 你拥有贡献内容的权利
|
||
- 你的贡献是自愿的，无报酬的
|
||
|
||
---
|
||
|
||
## 社区
|
||
|
||
### 行为准则
|
||
|
||
1. **尊重**：尊重所有贡献者
|
||
2. **包容**：欢迎不同背景的贡献者
|
||
3. **建设性**：提供建设性反馈
|
||
4. **协作**：以合作精神工作
|
||
|
||
### 沟通渠道
|
||
|
||
- **GitHub Issues**: 报告问题和讨论
|
||
- **Pull Requests**: 代码和内容贡献
|
||
- **Discussions**: 一般性讨论
|
||
|
||
---
|
||
|
||
## 致谢
|
||
|
||
所有贡献者将被列在项目首页的[Contributors](CONTRIBUTORS.md)中。
|
||
|
||
感谢你让这本书变得更好！
|