edict/CONTRIBUTING.md

∏# 🤝 参与贡献

三省六部欢迎各路英雄好汉 ⚔️
_{无论是修一个 typo 还是设计一个新的 Agent 角色，我们都万分感谢}

---

📋 贡献方式

🐛 报告 Bug

请使用 Bug Report 模板提交 Issue，包含：

• OpenClaw 版本（openclaw --version）
• Python 版本（python3 --version）
• 操作系统
• 复现步骤（越详细越好）
• 期望行为 vs 实际行为
• 截图（如果涉及看板 UI）

💡 功能建议

使用 Feature Request 模板。

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

🔧 提交 Pull Request

# 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 已安装
• Python 3.9+
• macOS / Linux

本地启动

# 安装
./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：

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 支持
• 移动端操作优化

---

🧪 测试

# 编译检查
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。

---

<EFBFBD> 安全漏洞

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

---

<EFBFBD>📬 联系方式

• GitHub Issues: 提交问题
• GitHub Discussions: 社区讨论

---

_{感谢每一位贡献者，你们是三省六部的基石 ⚔️}