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,327 @@
|
||||
# 贡献指南
|
||||
|
||||
感谢你有兴趣为《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)中。
|
||||
|
||||
感谢你让这本书变得更好！
|
||||
Reference in New Issue
Block a user