docs: refresh contribution guide and GitHub community entrypoints (#246)

2026-10-02 02:34:34 +08:00 · 2026-09-30 22:00:30 +08:00
parent 7fd70c9919
commit 70e4f42495
10 changed files with 77 additions and 294 deletions
@@ -3,13 +3,13 @@ body:
  - type: markdown
    attributes:
      value: |
-        说明你要的模型或供应商。设置页可选 Qwen、OpenAI、Gemini、DeepSeek、Doubao Seed、Kimi、GLM、Grok，以及本机的 Ollama / LM Studio（自备 API Key）。兼容接口可配置 Base URL。
+        说明你要的模型或供应商，以及用途：分析、视觉、封面或字幕转写。当前支持与配置以[模型指南](https://github.com/zhouxiaoka/autoclip/blob/main/docs/AI_MODEL_CONFIGURATION.md)和设置页为准；本地转写包括 Whisper 与 SenseVoice。
        只是「名单里没有这一项」、但兼容接口已经能填的，请在正文里写明，避免重复开需求。
  - type: input
    id: model
    attributes:
      label: 模型或供应商
-      placeholder: "Gemini 2.5 / Doubao Seed / Qwen 某个具体型号"
+      placeholder: "服务商与具体型号；本地转写注明模型名称"
    validations:
      required: true
  - type: dropdown
@@ -27,6 +27,6 @@ body:
    id: detail
    attributes:
      label: 补充
-      description: 报错请打码，不要贴 API Key。
+      description: 报错请先脱敏，移除 API Key、Cookie 和私人素材内容；可复现故障请使用 Bug 模板。
    validations:
      required: false
@@ -8,7 +8,7 @@ body:
    id: version
    attributes:
      label: 版本
-      placeholder: "v1.3.0"
+      placeholder: "实际发布版本 vX.Y.Z；未发布的源码更新请注明"
    validations:
      required: true
  - type: textarea
@@ -21,6 +21,6 @@ body:
    id: env
    attributes:
      label: 版本 / 平台 / 模型
-      placeholder: "v1.2.1 · Windows · 通义千问 qwen-plus"
+      placeholder: "实际版本或 commit SHA · 平台 · 相关服务商与模型"
    validations:
      required: false
@@ -24,16 +24,17 @@ body:
    id: version
    attributes:
      label: AutoClip 版本 / Version
-      description: 设置页底部或「关于」里可见 / Shown in Settings → About
-      placeholder: "v1.2.1"
+      description: 填写实际安装版本；源码用户附提交 SHA / Installed version, or commit SHA for source builds
+      placeholder: "vX.Y.Z；源码附 commit SHA / include commit SHA for source"
    validations:
      required: true

  - type: input
    id: model
    attributes:
-      label: 使用的模型提供商 / LLM provider
-      placeholder: "例如 Qwen / OpenAI / Gemini / DeepSeek / Doubao Seed / Kimi / GLM / Grok / 自定义 OpenAI 兼容"
+      label: 相关模型 / Relevant models
+      description: 分析服务与具体型号；转写问题附 Whisper / SenseVoice 型号。尚未配置或不相关可注明 / Provider and model; include transcription model when relevant
+      placeholder: "分析：服务商 + 型号；转写：Whisper / SenseVoice / 不相关"
    validations:
      required: true

@@ -66,5 +67,5 @@ body:
    attributes:
      label: 日志 / 截图 / Logs or screenshots
      description: |
-        桌面版日志位置：macOS `~/Library/Application Support/AutoClip/logs`，Windows `%APPDATA%\AutoClip\logs`。粘贴最后 50 行即可，注意删掉 API Key。
+        桌面版日志位置：macOS `~/Library/Application Support/AutoClip/logs`，Windows `%APPDATA%\AutoClip\logs`。粘贴失败前后相关日志即可，删除 API Key、Cookie、邮箱、私人路径与素材内容。Docker/源码用户请注明运行方式与日志来源。安全问题按 SECURITY.md 私下联系。
      render: text
@@ -9,3 +9,6 @@ contact_links:
  - name: 🙋 使用提问 / Q&A
    url: https://github.com/zhouxiaoka/autoclip/discussions/categories/q-a
    about: 怎么用、模型怎么选、切片效果怎么调。能复现的故障仍开 Issue。
+  - name: 🔒 安全问题 / Security
+    url: https://github.com/zhouxiaoka/autoclip/blob/main/SECURITY.md
+    about: 漏洞或凭据泄露请按安全政策私下联系，不公开敏感细节 / Follow the security policy for private contact.
@@ -0,0 +1,11 @@
+## 问题与结果
+
+<!-- 描述触发条件、原行为和修复后的行为。关联 Issue 或讨论链接（如有）。 -->
+
+## 验证
+
+<!-- 写出实际运行的检查、平台和结果；未覆盖的步骤也请说明。纯文档改动可说明命令与链接核对结果。 -->
+
+## 兼容或迁移说明（如有）
+
+<!-- 涉及数据、配置、依赖、安装或平台行为时说明影响；否则可删除此节。 -->
@@ -30,9 +30,9 @@ jobs:
              '',
              '- 当前状态与已知问题：#96',
              '- Issue 只收能复现的故障，以及维护者确认后放进路线图的需求。希望支持什么、你的用法、想要哪个模型，请发到 [Discussions](https://github.com/zhouxiaoka/autoclip/discussions)。',
-              '- bug 缺少 **版本 / 平台 / 模型** 时会被打上 `needs-info`，14 天内没补充会自动关闭（补充后重开即可）。',
+              '- bug 缺少 **版本 / 平台 / 模型** 时会被打上 `needs-info`，14 天内没人补充会先标记为 stale，再过 7 天仍无回复才自动关闭；补充后由维护者确认是否重开。',
              '',
-              '_Issues are for reproducible bugs and accepted roadmap items. Ideas belong in Discussions. Bugs missing version / platform / model get `needs-info` and auto-close after 14 days without a reply._'
+              '_Issues are for reproducible bugs and accepted roadmap items. Ideas belong in Discussions. Bugs missing version / platform / model get `needs-info`, are marked stale after 14 days without a reply, then close after 7 more days._'
            ].join('\n');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
@@ -53,8 +53,8 @@ jobs:
          days-before-pr-stale: -1
          days-before-pr-close: -1
          stale-issue-label: stale
-          stale-issue-message: "还缺少复现所需的信息（版本 / 平台 / 模型 / 日志），7 天内没有补充会自动关闭。补充后会自动重开处理。"
-          close-issue-message: "因长期缺少复现信息已关闭。补充信息后回复即可重开。"
+          stale-issue-message: "还缺少复现所需的信息（版本 / 平台 / 模型 / 日志），7 天内没有补充会自动关闭。补充后由维护者确认是否重开。"
+          close-issue-message: "因长期缺少复现信息已关闭。可在此回复补充信息，由维护者确认是否重开。"
          remove-stale-when-updated: true
          operations-per-run: 100

@@ -1,313 +1,80 @@
 # 贡献指南

-感谢您对AutoClip项目的关注！我们欢迎所有形式的贡献，包括但不限于：
+AutoClip 接受故障修复、文档与翻译改进，以及已经确认范围的功能贡献。首次参与可先看 [README](README.md)、[仓库目录说明](docs/REPOSITORY_LAYOUT.md) 和 [当前状态](HANDOFF.md)。个人业余维护，回复时间不固定。

- 🐛 Bug修复
- ✨ 新功能开发
- 📚 文档改进
- 🧪 测试用例
- 💡 功能建议
- 🎨 UI/UX改进
+## 先选择反馈入口

-## 开发环境设置
+- 可复现故障：[Bug 报告](https://github.com/zhouxiaoka/autoclip/issues/new/choose)。提供实际版本或源码提交、平台、相关模型、复现步骤、预期与实际结果，以及脱敏日志。
+- 使用提问：[Q&A](https://github.com/zhouxiaoka/autoclip/discussions/categories/q-a)。先查 [FAQ](docs/FAQ.md) 与 [已知问题](https://github.com/zhouxiaoka/autoclip/issues/96)。
+- 新想法与功能建议：[Ideas](https://github.com/zhouxiaoka/autoclip/discussions/categories/ideas)。说明场景与遇到的问题；较大的功能先讨论范围，再开始实现。
+- 安全问题：按 [SECURITY.md](SECURITY.md) 私下联系，不在公开帖子中披露漏洞细节或凭据。

-### 1. Fork并克隆项目
+Discussions 中的想法不代表开发承诺，确认后的工作才进入 Issue 与路线图，见 [社区看板](docs/COMMUNITY_BOARD.md)。
+
+## 准备开发环境
+
+Fork 本仓库并克隆你的 Fork，添加上游：

 ```bash
-# Fork 项目到您的 GitHub 账户，再将下面的 your-username 替换为您的用户名
-git clone https://github.com/your-username/autoclip.git
 cd autoclip
-
-# 添加上游仓库
 git remote add upstream https://github.com/zhouxiaoka/autoclip.git
+git fetch upstream
+git switch -c fix/your-change upstream/main
 ```

-### 2. 设置开发环境
+源码 Web 环境以 [STARTUP_GUIDE.md](STARTUP_GUIDE.md) 为准；当前 CI 验证 Python 3.11 和 Node.js 20。Python 依赖统一在根目录 `requirements.txt`，Node 依赖只在 `frontend/`，安装时使用锁定依赖：

 ```bash
-# 创建虚拟环境
 python3 -m venv venv
-source venv/bin/activate  # Linux/macOS
-# 或 venv\Scripts\activate  # Windows
-
-# 安装依赖
-pip install -r requirements.txt
-cd frontend && npm install && cd ..
-
-# 配置环境变量
+source venv/bin/activate
+python -m pip install -r requirements.txt
+(cd frontend && npm ci)
 cp env.example .env
-# 编辑.env文件，填入必要的配置
 ```

-### 3. 启动开发服务器
+以上命令适用于 macOS/Linux。Windows 桌面开发与打包按 [BUILD_GUIDE.md](BUILD_GUIDE.md) 和 [scripts/README.md](scripts/README.md) 准备工具链，不要直接套用 POSIX Web 启动脚本。
+
+Web 开发需要 Redis，准备后用 `./start_autoclip.sh`；管理命令和手动启动方式见启动指南。桌面后端由 Tauri 管理，入口是 `backend/desktop_main.py`；容器部署见 [DOCKER.md](DOCKER.md)，CLI/MCP 见 [对应指南](docs/CLI_AND_MCP.md)。
+
+## 修改与验证
+
+保持改动聚焦，遵循相关模块已有的结构和命名。说明解决了什么问题，以及哪些条件会触发它。UI 修改遵循 [DESIGN.md](DESIGN.md)，涉及行为变化时附截图或操作说明。翻译修改遵循 [翻译维护](docs/i18n.md)。
+
+后端测试从仓库根目录运行：

 ```bash
-# 启动Redis
-brew services start redis  # macOS
-# 或 sudo systemctl start redis-server  # Linux
-
-# 启动后端
-python -m uvicorn backend.main:app --reload --port 8000
-
-# 启动Celery Worker（必须带 -Q，否则只消费默认 `celery` 队列，流水线任务无人执行）
-celery -A backend.core.celery_app worker --loglevel=info -Q celery,processing,video,notification,upload
-
-# 启动前端
-cd frontend && npm run dev
+python -m pytest backend/tests -q
+# 开发时可先运行与改动相关的现有测试文件
 ```

-## 开发流程
-
-### 1. 创建功能分支
-
-```bash
-# 从main分支创建新分支
-git checkout main
-git pull upstream main
-git checkout -b feature/your-feature-name
-```
-
-### 2. 开发规范
-
-#### 代码风格
-
-**Python (后端)**
- 遵循PEP 8规范
- 使用Black进行代码格式化
- 使用isort进行导入排序
- 函数和类需要添加docstring
-
-```python
-def example_function(param1: str, param2: int) -> bool:
-    """
-    示例函数的文档字符串
-    
-    Args:
-        param1: 参数1的描述
-        param2: 参数2的描述
-        
-    Returns:
-        返回值的描述
-    """
-    pass
-```
-
-**TypeScript (前端)**
- 使用ESLint和Prettier
- 组件需要添加JSDoc注释
- 使用函数组件和Hooks
- 遵循Ant Design设计规范
-
-```typescript
-/**
- * 示例组件的描述
- */
-interface ExampleProps {
-  /** 属性描述 */
-  title: string;
-  /** 可选属性描述 */
-  optional?: boolean;
-}
-
-const ExampleComponent: React.FC<ExampleProps> = ({ title, optional = false }) => {
-  return <div>{title}</div>;
-};
-```
-
-#### 提交信息规范
-
-使用约定式提交格式：
-
-```
-<type>(<scope>): <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-**类型 (type):**
- `feat`: 新功能
- `fix`: Bug修复
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建过程或辅助工具的变动
-
-**示例:**
-```
-feat(api): add video download endpoint
-fix(ui): resolve upload modal display issue
-docs(readme): update installation instructions
-```
-
-### 3. 测试
-
-#### 后端测试
-
-```bash
-# 运行所有测试
-pytest
-
-# 运行特定测试文件
-pytest tests/test_api.py
-
-# 生成覆盖率报告
-pytest --cov=backend --cov-report=html
-```
-
-#### 前端测试
+前端验证使用 `frontend/package.json` 中的真实脚本：

 ```bash
 cd frontend
-
-# 运行测试
-npm test
-
-# 运行lint检查
 npm run lint
-
-# 类型检查
-npm run type-check
+npm run typecheck
+npm test
+npm run build
 ```

-### 4. 提交代码
+CI 的后端 lint 使用 Ruff，目前是非阻塞检查；测试及前端检查仍需通过。项目没有统一配置 Black、isort 或 Prettier，不要为无关修改重新格式化整个仓库。修复可复现的代码故障时补充有意义的回归覆盖；纯文档修改检查命令、链接和对应实现即可。
+
+涉及启动、Docker、桌面安装或平台差异时，应验证受影响路线并记录平台与结果。CI 通过不等于安装包已完成界面或真实出片验收，发布必须遵守 [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md)。
+
+## 提交 Pull Request
+
+先检查改动，再按文件添加；下例用 `git add -p` 选择已有文件的修改，新文件需按实际路径添加。提交标题可使用 `fix:`、`feat:`、`docs:`、`refactor:`、`test:` 或 `chore:`，简述具体变化。推送分支后向本仓库 `main` 发起 PR：

 ```bash
-# 添加更改
-git add .
-
-# 提交更改
-git commit -m "feat(api): add video download endpoint"
-
-# 推送分支
-git push origin feature/your-feature-name
+git add -p
+git commit -m "fix: describe the problem being resolved"
+git push -u origin fix/your-change
 ```

-### 5. 创建Pull Request
+按 [PR 模板](.github/PULL_REQUEST_TEMPLATE.md) 说明问题、最终行为和验证结果；有相关 Issue 时附链接。验证未覆盖的平台或步骤应明确写出，避免把未运行的检查标为通过。不要提交 `.env`、API Key、Cookie、私人素材、运行数据库、模型缓存或构建产物；文件归档规则见 [归档规范](docs/REPOSITORY_ARCHIVE_POLICY.md)。

-1. 在GitHub上创建Pull Request
-2. 填写PR模板
-3. 确保所有检查通过
-4. 等待代码审查
+收到审查反馈后在同一 PR 更新。较大的方案调整先在对应讨论中说明，避免把无关改动混在一起。合入源码与正式安装包发布是不同步骤；发布信息以 [Releases](https://github.com/zhouxiaoka/autoclip/releases) 为准。

-## 代码审查流程
+## 社区与联系

-### 审查标准
-
- ✅ 代码符合项目规范
- ✅ 功能正常工作
- ✅ 测试用例覆盖
- ✅ 文档已更新
- ✅ 无安全漏洞
- ✅ 性能影响评估
-
-### 审查反馈
-
- 积极回应审查意见
- 及时修复问题
- 保持PR更新
- 与审查者保持沟通
-
-## 问题报告
-
-### Bug报告
-
-使用GitHub Issues报告Bug时，请包含：
-
-1. **环境信息**
-   - 操作系统版本
-   - Python版本
-   - Node.js版本
-   - 浏览器版本
-
-2. **重现步骤**
-   - 详细的操作步骤
-   - 预期结果
-   - 实际结果
-
-3. **错误信息**
-   - 完整的错误日志
-   - 截图或录屏
-
-4. **附加信息**
-   - 相关配置文件
-   - 网络环境
-   - 其他可能相关的信息
-
-### 功能建议
-
-提出新功能建议时，请说明：
-
-1. **功能描述**
-   - 详细的功能说明
-   - 使用场景
-   - 预期效果
-
-2. **实现方案**
-   - 技术实现思路
-   - 可能的挑战
-   - 替代方案
-
-3. **影响评估**
-   - 对现有功能的影响
-   - 性能影响
-   - 用户体验影响
-
-## 文档贡献
-
-### 文档类型
-
- 📖 用户文档
- 🔧 开发者文档
- 🚀 部署指南
- ❓ 常见问题
- 📝 API文档
-
-### 文档规范
-
- 使用Markdown格式
- 添加目录结构
- 包含代码示例
- 保持内容更新
- 使用清晰的标题层级
-
-## 想法放哪里
-
-希望 AutoClip 支持什么、你的用法、想要哪个模型，发到 [GitHub Discussions](https://github.com/zhouxiaoka/autoclip/discussions)。
-能复现的故障用 Issue 里的 bug 模板。已经决定要做的需求才会出现在公开路线图上。
-分类、六列和 Agent 的操作见 [社区看板](docs/COMMUNITY_BOARD.md)。
-
-## 社区行为准则
-
-### 我们的承诺
-
-为了营造开放和友好的环境，我们承诺：
-
- 尊重所有贡献者
- 接受建设性批评
- 关注社区最佳利益
- 对其他社区成员表示同理心
-
-### 不可接受的行为
-
- 使用性暗示的语言或图像
- 人身攻击或侮辱性评论
- 公开或私下骚扰
- 未经许可发布他人私人信息
- 其他在专业环境中不当的行为
-
-## 联系方式
-
-个人业余维护，回复时间不固定。请先查看 [常见问题](docs/FAQ.md)。
-
-邮箱：[christine_zhouye@163.com](mailto:christine_zhouye@163.com)
-
-## 致谢
-
-感谢所有为AutoClip项目做出贡献的开发者！您的贡献让这个项目变得更好。
-
---
-
-**再次感谢您的贡献！** 🎉
+尊重其他参与者，围绕问题和证据讨论；不接受骚扰、人身攻击或公开他人私人信息。一般提问优先使用社区入口，私密联系可发送至 [christine_zhouye@163.com](mailto:christine_zhouye@163.com)。
@@ -4,7 +4,7 @@

 ## 报告问题

-项目目前未开启 GitHub 私密漏洞报告。可使用[文档中心公布的维护者邮箱](docs/README.md#联系)私下联系；如通过 Issue 联系，只描述需要建立安全联系，不公开漏洞利用步骤、API Key、Cookie、私人素材或含密钥的日志。建立私密渠道后，再提供影响版本、复现条件和脱敏证据。
+项目目前未开启 GitHub 私密漏洞报告。可使用维护者公开联系邮箱 [christine_zhouye@163.com](mailto:christine_zhouye@163.com)私下联系；如通过 Issue 联系，只描述需要建立安全联系，不公开漏洞利用步骤、API Key、Cookie、私人素材或含密钥的日志。建立私密渠道后，再提供影响版本、复现条件和脱敏证据。

 本项目没有公布专用安全邮箱、响应时限或第三方审计承诺。已公开的安全信息以[安全公告](https://github.com/zhouxiaoka/autoclip/security/advisories)、发布说明及对应修复记录为准。

@@ -25,6 +25,7 @@
 | `init_database.py` | 手动维护入口仍有用途，但重复建表且提示不存在的启动脚本。保留为共享初始化入口，导入时不改变工作目录，失败返回非零值。 |
 | `status_autoclip.sh` / `stop_autoclip.sh` | 仍被启动指南使用。改为兼容转发器，验证当前 checkout 的进程归属及创建时间，不再全局 `pkill`。 |
 | `start_autoclip.sh` / `quick_start.sh` | Web 源码开发仍需要。实现移至 `scripts/runtime/start.sh`，合并启动逻辑，快速入口只负责后台模式；失败不再宣称启动成功。 |
+| `CONTRIBUTING.md` / `.github/` 社区模板 | 贡献入口仍需维护。按现行 CI 修正测试命令与工具要求，补充 PR 模板；社区表单不再依赖旧版本号和过时供应商清单。 |
 | `SECURITY.md` | 原文件含占位邮箱、伪 CVE、过时支持表和未履行承诺。重写为真实维护与联系政策。 |

 保留文件名是为了让已有命令、书签和使用习惯继续生效；实现只维护一份。桌面客户端不需要用户手动运行这些 Web 管理脚本。