Skip to content

Commit 4f9119a

Browse files
yyg-maxyyg-max
committed
chore(github): add issue/PR templates and PR governance workflow
- issue 模板:Bug 报告、需求提案(需求说明必填)、文档问题,禁用空白 issue - PR 模板与 CONTRIBUTING:先 issue 后 PR,要求关联 issue、改动范围与截图预览 - pr-governance workflow:未关联 issue、UI 改动无截图、与基线冲突的 PR 自动转 draft
1 parent 75374a9 commit 4f9119a

7 files changed

Lines changed: 472 additions & 0 deletions

File tree

‎.github/CONTRIBUTING.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# LiveAgent 贡献指南
2+
3+
感谢你对 LiveAgent 的关注!为了让协作高效、降低审核成本,本项目对 issue 与 PR 有明确的流程要求。**不符合流程的 PR 会被自动转为 draft**,补齐后再点击 "Ready for review" 即可重新触发检查。
4+
5+
## 核心流程:先 Issue,后 PR
6+
7+
1. **先提 issue**:无论缺陷还是新功能,先用对应的 issue 模板提交,写清需求说明 / 复现步骤。
8+
2. **等待确认**:功能类提案请等维护者确认方向后再动手,避免白做。
9+
3. **再提 PR**:PR 正文必须用 `Closes #123` / `Fixes #123` 关联对应 issue。
10+
4. 内部维护者的日常开发同样遵守"PR 关联 issue"——差别只是可以自己先补一个简要 issue 再提 PR。
11+
12+
不允许无 issue 直接提 PR。琐碎修复(错别字、注释、明显笔误)可在 PR 说明中注明豁免理由,由维护者判断。
13+
14+
## PR 硬性要求(自动检查)
15+
16+
以下任一不满足,PR 会被自动转为 draft 并附检查报告:
17+
18+
| 检查项 | 要求 |
19+
| --- |----------------------------------------------------------------------------------------------------|
20+
| 关联 issue | 正文包含 `Closes #N` / `Fixes #N` / `Resolves #N` |
21+
| 截图 / 预览 | UI 改动必须附截图或录屏(强制);后端 / CLI 改动附请求响应示例或运行日志等文字材料即可,由人工审核把关 |
22+
| 无合并冲突 | 与目标分支冲突时请先在自己的分支解决(merge 或 rebase 基线),维护者不代为解冲突 |
23+
24+
被转为 draft 后:按报告补齐 → 点击 **Ready for review** → 重新检查。
25+
26+
## PR 内容要求
27+
28+
- **保持聚焦**:一个 PR 只做一件事,不混入无关重构或格式化。
29+
- **写清改动范围**:按模板列出涉及模块与关键路径(`agent-gui` / `agent-gateway` / `src-tauri`),降低审核复杂度,也便于 AI review。
30+
- **通过 CI**:提交前在本地跑对应模块的检查:
31+
- Gateway(Go):`cd crates/agent-gateway && go test ./...`,proto 变更需 `make proto-check`
32+
- GUI 前端:`cd crates/agent-gui && pnpm build && pnpm lint && pnpm test:frontend`
33+
- Tauri(Rust):`cargo check --manifest-path crates/agent-gui/src-tauri/Cargo.toml --tests`
34+
- Gateway WebUI:`cd crates/agent-gateway/web && pnpm build && pnpm lint && pnpm test`
35+
- **不提交敏感信息**:API Key、token、个人数据、`.env`、本地配置一律不入库。
36+
- **同步文档与注释**:影响用户行为、部署或配置的变更,同步更新文档;修改代码后同步修改受影响的注释。
37+
38+
## Issue 要求
39+
40+
- Bug 报告:提供版本、环境、最小复现步骤、预期与实际行为。
41+
- 需求提案:写清要解决的问题与期望方案——**需求说明是必填项**,只有一句"希望支持 XXX"的 issue 会被要求补充。
42+
- 安全漏洞:**不要**发公开 issue,请通过 [Security Advisories](https://github.com/Stack-Cairn/LiveAgent/security/advisories/new) 私下报告。
43+
44+
## 许可
45+
46+
提交贡献即表示你同意你的代码以本仓库的 [MIT License](../LICENSE) 发布。

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
name: Bug 报告 / Bug report
2+
description: 报告 LiveAgent 的缺陷。请提供完整的复现信息,信息不全的 issue 可能被要求补充后才会处理。
3+
title: "[Bug] "
4+
labels:
5+
- bug
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
感谢反馈!请勿在此报告安全漏洞——请通过 [Security Advisories](https://github.com/Stack-Cairn/LiveAgent/security/advisories/new) 私下提交。
11+
提交前请先搜索现有 issue,避免重复。
12+
- type: dropdown
13+
id: area
14+
attributes:
15+
label: 影响范围
16+
description: 选择该问题主要影响的模块。
17+
options:
18+
- 桌面端 UI(agent-gui / React)
19+
- 桌面端内核(Tauri / Rust)
20+
- 网关(agent-gateway / Go)
21+
- Agent 会话 / 流式输出
22+
- 工具执行 / MCP / Skills
23+
- 模型接入 / Provider
24+
- 打包 / 发布 / 安装
25+
- 文档
26+
- 其他
27+
validations:
28+
required: true
29+
- type: input
30+
id: version
31+
attributes:
32+
label: 版本或 commit
33+
description: 发布版本号、Docker 镜像 tag、分支或 commit SHA。
34+
placeholder: v0.3.2 / main@f69f24dc
35+
validations:
36+
required: true
37+
- type: textarea
38+
id: environment
39+
attributes:
40+
label: 运行环境
41+
description: 操作系统与版本、部署方式(桌面端 / 网关自部署)、使用的模型 Provider 等。
42+
placeholder: |
43+
OS: macOS 15.2 (Apple Silicon)
44+
部署方式: 桌面端
45+
模型 Provider: Anthropic API
46+
validations:
47+
required: true
48+
- type: textarea
49+
id: reproduce
50+
attributes:
51+
label: 复现步骤
52+
description: 能稳定复现问题的最小操作序列。
53+
placeholder: |
54+
1. 打开设置页……
55+
2. 点击……
56+
3. 观察到……
57+
validations:
58+
required: true
59+
- type: textarea
60+
id: expected
61+
attributes:
62+
label: 预期行为
63+
validations:
64+
required: true
65+
- type: textarea
66+
id: actual
67+
attributes:
68+
label: 实际行为
69+
validations:
70+
required: true
71+
- type: textarea
72+
id: logs
73+
attributes:
74+
label: 日志 / 截图
75+
description: 相关日志、报错信息或截图,可直接拖拽上传。请先移除密钥、token 等敏感信息。
76+
validations:
77+
required: false
78+
- type: checkboxes
79+
id: checklist
80+
attributes:
81+
label: 提交前确认
82+
options:
83+
- label: 我已搜索现有 issue 和 PR,确认没有重复。
84+
required: true
85+
- label: 内容中不包含 API Key、token、密码等敏感信息。
86+
required: true
87+
- label: 这不是安全漏洞(安全问题请走 Security Advisories 私下报告)。
88+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: 安全漏洞报告 / Security vulnerability
4+
url: https://github.com/Stack-Cairn/LiveAgent/security/advisories/new
5+
about: 请勿在公开 issue 中报告安全漏洞,请通过 GitHub Security Advisories 私下提交。
6+
- name: 贡献指南 / Contributing guidelines
7+
url: https://github.com/Stack-Cairn/LiveAgent/blob/main/.github/CONTRIBUTING.md
8+
about: 提交 issue 或 PR 之前,请先阅读贡献指南。
9+
- name: 使用咨询 / Questions & discussions
10+
url: https://github.com/Stack-Cairn/LiveAgent/discussions
11+
about: 使用问题、想法讨论请使用 Discussions,issue 仅用于缺陷报告与需求提案。

‎.github/ISSUE_TEMPLATE/documentation.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: 文档问题 / Documentation
2+
description: 报告文档的错误、过时、缺失或表述不清的问题。
3+
title: "[Docs] "
4+
labels:
5+
- documentation
6+
body:
7+
- type: dropdown
8+
id: type
9+
attributes:
10+
label: 问题类型
11+
options:
12+
- 内容有误(与实际行为不符)
13+
- 内容过时(功能已变更但文档未更新)
14+
- 内容缺失(该有说明但没有)
15+
- 表述不清 / 易产生误解
16+
- 其他
17+
validations:
18+
required: true
19+
- type: input
20+
id: location
21+
attributes:
22+
label: 文档位置
23+
description: 相关文档的链接或文件路径。
24+
placeholder: docs/xxx.md 或 README.md 的某一节
25+
validations:
26+
required: true
27+
- type: textarea
28+
id: problem
29+
attributes:
30+
label: 问题描述
31+
description: 说明哪里有问题。是内容错误的话,请一并说明实际的正确行为。
32+
validations:
33+
required: true
34+
- type: textarea
35+
id: suggestion
36+
attributes:
37+
label: 修改建议
38+
description: 如果你有建议的写法,写在这里;愿意直接提 PR 修复也请注明。
39+
validations:
40+
required: false
41+
- type: checkboxes
42+
id: checklist
43+
attributes:
44+
label: 提交前确认
45+
options:
46+
- label: 我已搜索现有 issue,确认没有重复。
47+
required: true

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: 需求提案 / Feature request
2+
description: 提出新功能或改进。所有功能类 PR 必须先有对应的需求 issue,请在这里写清需求说明。
3+
title: "[Feature] "
4+
labels:
5+
- enhancement
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
本项目要求 **先 issue 后 PR**:功能开发前请先提交本表单并等待维护者确认,再开始编码。
11+
未关联需求 issue 的 PR 会被直接转为 draft。
12+
- type: dropdown
13+
id: area
14+
attributes:
15+
label: 影响范围
16+
description: 选择该提案主要涉及的模块。
17+
options:
18+
- 桌面端 UI(agent-gui / React)
19+
- 桌面端内核(Tauri / Rust)
20+
- 网关(agent-gateway / Go)
21+
- Agent 会话 / 流式输出
22+
- 工具执行 / MCP / Skills
23+
- 模型接入 / Provider
24+
- 打包 / 发布 / 安装
25+
- 文档
26+
- 其他
27+
validations:
28+
required: true
29+
- type: textarea
30+
id: problem
31+
attributes:
32+
label: 需求说明(要解决什么问题)
33+
description: 描述当前的痛点或限制、受影响的用户场景。这是需求评审的核心依据,请写具体。
34+
placeholder: 当前……导致……,影响到……场景。
35+
validations:
36+
required: true
37+
- type: textarea
38+
id: proposal
39+
attributes:
40+
label: 期望的方案或行为
41+
description: 描述期望的交互、API、配置或行为变化。UI 相关的提案建议附草图或参考截图。
42+
validations:
43+
required: true
44+
- type: textarea
45+
id: scope
46+
attributes:
47+
label: 预计改动范围
48+
description: 如果你打算自己实现,请列出预计涉及的模块 / 目录 / 文件,便于评估复杂度。
49+
placeholder: |
50+
crates/agent-gui/src/...
51+
crates/agent-gateway/internal/...
52+
validations:
53+
required: false
54+
- type: textarea
55+
id: alternatives
56+
attributes:
57+
label: 备选方案
58+
description: 考虑过的其他方案或现有替代做法。
59+
validations:
60+
required: false
61+
- type: checkboxes
62+
id: checklist
63+
attributes:
64+
label: 提交前确认
65+
options:
66+
- label: 我已搜索现有 issue 和 PR,确认没有重复。
67+
required: true
68+
- label: 本提案聚焦单一功能或改进,没有混杂多个不相关需求。
69+
required: true
70+
- label: 我了解需先经维护者确认后再提交实现 PR,否则 PR 会被转为 draft。
71+
required: true

‎.github/pull_request_template.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
<!--
2+
提交前请阅读 .github/CONTRIBUTING.md。
3+
不满足以下任一条的 PR 会被自动转为 draft:
4+
1. 正文中通过 Closes/Fixes/Resolves #123 关联需求 issue;
5+
2. UI / 新功能 / 后端行为变更提供截图或运行效果预览;
6+
3. 与目标分支无合并冲突。
7+
-->
8+
9+
## 关联 Issue
10+
11+
<!-- 必填。功能与缺陷 PR 必须关联对应 issue,使用关闭关键字以便合并后自动关闭。 -->
12+
13+
Closes #
14+
15+
## 变更说明
16+
17+
<!-- 解决了什么问题、采用什么方案。保持 PR 聚焦,不要混入无关重构。 -->
18+
19+
## 变更类型
20+
21+
- [ ] Bug 修复
22+
- [ ] 新功能
23+
- [ ] 重构 / 性能优化
24+
- [ ] 文档
25+
- [ ] 构建 / CI / 依赖
26+
- [ ] 其他
27+
28+
## 改动范围
29+
30+
<!-- 列出涉及的模块与关键文件/目录,帮助 reviewer 快速定位。 -->
31+
32+
- 模块:<!-- 例:agent-gui / agent-gateway / src-tauri -->
33+
- 关键路径:
34+
35+
## 截图 / 效果预览
36+
37+
<!-- UI、新功能、后端行为变更必须提供:UI 改动附前后对比截图;后端/CLI 改动附请求响应示例或运行日志(移除敏感信息)。纯重构/文档可写"不适用"并说明原因。 -->
38+
39+
## 验证方式
40+
41+
<!-- 列出你运行过的检查,例如:
42+
gateway: cd crates/agent-gateway && go test ./...
43+
gui: cd crates/agent-gui && pnpm test
44+
-->
45+
46+
## 提交前确认
47+
48+
- [ ] 已关联需求 issue(或该 PR 属于无需 issue 的琐碎修复,已在变更说明中说明)。
49+
- [ ] 已与目标分支同步,无合并冲突。
50+
- [ ] 改动聚焦,未混入无关变更。
51+
- [ ] 不包含密钥、token 或个人敏感数据。
52+
- [ ] 影响用户行为、部署或配置的变更已同步更新文档。

0 commit comments

Comments
 (0)