∏# 🤝 参与贡献

<p align="center">
  <strong>三省六部欢迎各路英雄好汉 ⚔️</strong><br>
  <sub>无论是修一个 typo 还是设计一个新的 Agent 角色，我们都万分感谢</sub>
</p>

---

## 📋 贡献方式

### 🐛 报告 Bug

请使用 [Bug Report](.github/ISSUE_TEMPLATE/bug_report.md) 模板提交 Issue，包含：
- OpenClaw 版本（`openclaw --version`）
- Python 版本（`python3 --version`）
- 操作系统
- 复现步骤（越详细越好）
- 期望行为 vs 实际行为
- 截图（如果涉及看板 UI）

### 💡 功能建议

使用 [Feature Request](.github/ISSUE_TEMPLATE/feature_request.md) 模板。

我们推荐用"旨意"的格式来描述你的需求 —— 就像给皇上写奏折一样 😄

### 🔧 提交 Pull Request

```bash
# 1. Fork 本仓库
# 2. 克隆你的 Fork
git clone https://github.com/<your-username>/edict.git
cd edict

# 3. 创建功能分支
git checkout -b feat/my-awesome-feature

# 4. 开发 & 测试
python3 dashboard/server.py  # 启动看板验证

# 5. 提交
git add .
git commit -m "feat: 添加了一个很酷的功能"

# 6. 推送 & 创建 PR
git push origin feat/my-awesome-feature
```

---

## 🏗️ 开发环境

### 前置条件
- [OpenClaw](https://openclaw.ai) 已安装
- Python 3.9+
- macOS / Linux

### 本地启动

```bash
# 安装
./install.sh

# 启动数据刷新（后台运行）
bash scripts/run_loop.sh &

# 启动看板服务器
python3 dashboard/server.py

# 打开浏览器
open http://127.0.0.1:7891
```

> 💡 **看板开箱即用**：`server.py` 内嵌 `dashboard/dashboard.html`，Docker 镜像包含预构建 React 前端

### 项目结构速览

| 目录/文件 | 说明 | 改动频率 |
|----------|------|--------|
| `dashboard/dashboard.html` | 看板前端（单文件，零依赖，开箱即用） | 🔥 高 |
| `dashboard/server.py` | API 服务器（stdlib，~2200 行） | 🔥 高 |
| `agents/*/SOUL.md` | 12 个 Agent 人格模板 | 🔶 中 |
| `dashboard/court_discuss.py` | 朝堂议政引擎（多官员 LLM 讨论） | 🔶 中 |
| `scripts/kanban_update.py` | 看板 CLI + 数据清洗 + 状态机校验（~350 行） | 🔶 中 |
| `scripts/*.py` | 数据同步 / 自动化脚本 | 🔶 中 |
| `tests/test_e2e_kanban.py` | E2E 看板测试（24 断言） | 🔶 中 |
| `install.sh` | 安装脚本 | 🟢 低 |

---

## 🏛️ 贡献者阶梯

我们采用渐进式权限模型，让社区成员能够逐步承担更多责任：

| 角色 | 条件 | 权限 |
|------|------|------|
| **🌱 Contributor** | 任何人 | Fork → PR → 等待 review |
| **🏷️ Triage** | 3+ merged PRs | 管理 Issue 标签、分配、关闭重复 Issue |
| **⚔️ Committer** | 5+ merged PRs + 活跃参与 review | Write 权限，可 merge 非核心路径的 PR |
| **👑 Maintainer** | 长期信任 + 架构理解 | 可 merge 核心路径，参与架构决策 |

### 晋升流程

1. 维护者会主动邀请活跃贡献者晋升
2. 也可以在 Issue 中自荐，说明你的贡献记录
3. 所有晋升决定公开透明

> **核心路径**（需 Maintainer review）：`dashboard/server.py`、`agents/`、`edict/backend/`、`scripts/`、`data/`
>
> **开放路径**（Committer 可自主 merge）：`docs/`、`examples/`、`README*.md`、UI 样式调整

---

## 📝 Commit 规范

我们使用 [Conventional Commits](https://www.conventionalcommits.org/)：

```
feat:     ✨ 新功能
fix:      🐛 修复 Bug
docs:     📝 文档更新
style:    🎨 代码格式（不影响逻辑）
refactor: ♻️ 代码重构
perf:     ⚡ 性能优化
test:     ✅ 测试
chore:    🔧 杂项维护
ci:       👷 CI/CD 配置
```

示例：
```
feat: 添加奏折导出为 PDF 功能
fix: 修复模型切换后 Gateway 未重启的问题
docs: 更新 README 截图
```

---

## 🎯 特别欢迎的贡献方向

### 🎨 看板 UI
- 深色/浅色主题切换
- 响应式布局优化
- 动画效果增强
- 可访问性（a11y）改进

### 🤖 新 Agent 角色
- 适合特定行业/场景的专职 Agent
- 新的 SOUL.md 人格模板
- Agent 间协作模式创新

### 📦 Skills 生态
- 各部门专用技能包
- MCP 集成技能
- 数据处理 / 代码分析 / 文档生成专项技能

### 🔗 第三方集成
- Notion / Jira / Linear 同步
- GitHub Issues / PR 联动
- Slack / Discord 消息渠道
- Webhook 扩展

### 🌐 国际化
- 日文 / 韩文 / 西班牙文翻译
- 看板 UI 多语言支持

### 📱 移动端
- 响应式适配
- PWA 支持
- 移动端操作优化

---

## 🧪 测试

```bash
# 编译检查
python3 -m py_compile dashboard/server.py
python3 -m py_compile scripts/kanban_update.py

# E2E 看板测试（9 场景 17 断言）
python3 tests/test_e2e_kanban.py

# 验证数据同步
python3 scripts/refresh_live_data.py
python3 scripts/sync_agent_config.py

# 启动服务器验证 API
python3 dashboard/server.py &
curl -s http://localhost:7891/api/live-status | python3 -m json.tool | head -20
```

---

## 📏 代码风格

- **Python**: PEP 8，使用 pathlib 处理路径
- **TypeScript/React**: 函数组件 + Hooks，CSS 变量命名以 `--` 开头
- **CSS**: 使用 CSS 变量（`--bg`, `--text`, `--acc` 等），BEM 风格的 class 名
- **Markdown**: 标题使用 `#`，列表使用 `-`，代码块标注语言

---

## 🙏 行为准则

本项目采用 [Contributor Covenant](CODE_OF_CONDUCT.md) 行为准则。参与本项目即表示你同意遵守其条款。

简要原则：
- 保持友善和建设性
- 尊重不同的观点和经验
- 接受建设性的批评
- 专注于对社区最有利的事情
- 对其他社区成员表示同理心

**我们对骚扰行为零容忍。** 详见 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。

---

## � 安全漏洞

发现安全问题？请**不要**通过公开 Issue 报告。详见 [SECURITY.md](SECURITY.md)。

---

## �📬 联系方式

- GitHub Issues: [提交问题](https://github.com/cft0808/edict/issues)
- GitHub Discussions: [社区讨论](https://github.com/cft0808/edict/discussions)

---

<p align="center">
  <sub>感谢每一位贡献者，你们是三省六部的基石 ⚔️</sub>
</p>