From 25e36d67c2dcc43821cda5fc8afe6864f6eec006 Mon Sep 17 00:00:00 2001
From: oliver <zhoutianjun127@126.com>
Date: Mon, 4 May 2026 12:17:04 +0800
Subject: [PATCH] docs: add CONTRIBUTING and GitHub issue templates

Document fork/PR workflow for external contributors; add bug and feature issue templates.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .github/ISSUE_TEMPLATE/bug_report.md      | 31 ++++++++++++++
 .github/ISSUE_TEMPLATE/config.yml         |  1 +
 .github/ISSUE_TEMPLATE/feature_request.md | 22 ++++++++++
 CONTRIBUTING.md                           | 49 +++++++++++++++++++++++
 README.md                                 |  4 ++
 5 files changed, 107 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md
 create mode 100644 CONTRIBUTING.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 00000000..71ab5f1e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,31 @@
+---
+name: 缺陷报告
+about: 报告可复现的问题
+title: "[bug] "
+labels: ["bug"]
+---
+
+## 环境
+
+- OS（如 Windows 11）：
+- Python 版本（如 3.11.x）：
+- 分支 / 提交（可选）：
+
+## 现象
+
+（实际发生了什么？）
+
+## 预期
+
+（你期望发生什么？）
+
+## 复现步骤
+
+1. 
+2. 
+3. 
+
+## 补充
+
+- 日志片段、截图（可打码）：
+- 是否改过 `_local/system.env` / `oclaw.json`（仅说明类型，勿贴密钥）：
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 00000000..0086358d
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1 @@
+blank_issues_enabled: true
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 00000000..74669d00
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,22 @@
+---
+name: 功能建议
+about: 提议新能力或改进
+title: "[feat] "
+labels: ["enhancement"]
+---
+
+## 背景 / 动机
+
+（要解决什么问题？谁受益？）
+
+## 建议方案
+
+（你认为可以怎么做？可粗可细。）
+
+## 替代方案
+
+（如有想过的其它做法，可简写。）
+
+## 其它
+
+- 是否愿意自行提交 PR：（是 / 否 / 未确定）
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..b0c1dfc1
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,49 @@
+# 参与贡献
+
+感谢你有兴趣改进本项目。下面是从 Fork 到合并的最常见路径；本地环境与命令仍以仓库根目录 `README.md`、`docs/RUNBOOK.md` 为准。
+
+## 协作方式
+
+- 本仓库**默认不**对陌生人开放直接 `push` 权限。外部贡献请走 **Fork → 新建分支 → 打开 Pull Request（PR）**。
+- 维护者审阅、CI 通过后合并到主分支；你在本机用 `git pull` 即可同步。
+
+## 建议流程
+
+1. **Fork** 本仓库到你自己的 GitHub 账号下。
+2. 克隆你的 Fork，并添加上游（便于同步）：
+
+   ```text
+   git remote add upstream https://github.com/<原仓库>/oclaw.git
+   ```
+
+3. 从 `main` 拉最新，并创建功能分支（命名清晰，如 `fix/...`、`feat/...`）：
+
+   ```text
+   git fetch upstream
+   git checkout -b feat/your-topic upstream/main
+   ```
+
+4. 修改后提交；推送 **到你的 Fork**：
+
+   ```text
+   git push -u origin feat/your-topic
+   ```
+
+5. 在 GitHub 上从你的 Fork 向原仓库发起 **Pull Request**，说明动机、变更范围；有关联 Issue 可在描述里写 `Fixes #123`。
+
+## 合并前自检
+
+- 尽量保持改动聚焦单一主题，避免无关格式化或大范围重命名。
+- 仓库根目录已配置 CI（`.github/workflows/ci.yml`）；请在本地尽量跑通相关测试或 lint，减少往返。
+- **切勿**提交密钥、令牌、个人 `_local/system.env`、数据库路径等敏感内容；环境请以 `_local/system.env.example` 为模板本地自建。
+
+## 文档与风格
+
+- 环境变量登记规则见 `_local/system.env.example` 头部说明；相关文档需同步 `docs/ENVIRONMENT_VARIABLES.md`（如适用）。
+- 提示词与工作区约定见 `docs/PROMPT_STYLE_GUIDE.md`、`docs/ARCHITECTURE_OVERVIEW.md`（按改动类型选读）。
+
+## 问题反馈
+
+- 使用 GitHub **Issues**（见仓库内 Issue 模板）。尽量写清复现步骤、环境（OS、Python 版本、相关配置是否改）与预期/实际行为。
+
+若仅作内部使用、暂不接受外部 PR，可在仓库说明中注明；本文件仍可作为团队内协作参考。
diff --git a/README.md b/README.md
index 0219c0e4..e249e63d 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,10 @@ powershell -ExecutionPolicy Bypass -File .\scripts\start_all.ps1 -Background
 
 若要在 ops 专家模式下调 **netx** 告警库，需单独启动 netx 服务，并在 `_local/system.env` 中配置 `OCLAW_NETX_BASE_URL`（及可选的 `OCLAW_NETX_API_TOKEN`）。说明见 `docs/NETX_MCP_INTEGRATION.md`。
 
+### 外部贡献
+
+若仓库对外开源并接受 Pull Request，协作方式与合并前自检见根目录 `CONTRIBUTING.md`。
+
 ---
 
 ## Quickstart (Open Source)