v2026.05.12

.flocks/plugins/skills/browser-use/SKILL.md

@@ -68,11 +68,7 @@ browser: not connected — 请确保 Chrome / Chromium / Edge 已打开，然后
 说明当前环境不适合 `CDP 直连`。此时要：
 
 1. 明确告诉用户是哪一项不满足，提示需要做什么操作才能达到要求
-2. 切换到 `agent-browser` 模式
-3. 立即阅读：
-   - `references/agent-browser.md`
-
-不要继续尝试 CDP。
+2. 提示用户切换到 `agent-browser` 模式
 
 ## 执行规则
 

.github/workflows/windows-packaging-publish.yml

@@ -47,20 +47,25 @@ jobs:
             -RepoRoot "${{ github.workspace }}" `
             -AppVersion $appVersion
           $uvExe = Join-Path $out "tools/uv/uv.exe"
+          $pythonExe = Join-Path $out "tools/python/python.exe"
           $nodeExe = Join-Path $out "tools/node/node.exe"
           $chromeExe = Get-ChildItem -Path (Join-Path $out "tools/chrome") -Recurse -Filter "chrome.exe" -File -ErrorAction SilentlyContinue |
             Where-Object { $_.FullName -match "chrome-win" } |
             Select-Object -First 1
           if (-not (Test-Path $uvExe)) {
             throw "uv executable not found in staging: $uvExe"
           }
+          if (-not (Test-Path $pythonExe)) {
+            throw "python executable not found in staging: $pythonExe"
+          }
           if (-not (Test-Path $nodeExe)) {
             throw "node executable not found in staging: $nodeExe"
           }
           if (-not $chromeExe) {
             throw "chrome executable not found in staging under tools/chrome"
           }
           $uvVersion = (& $uvExe --version).Trim()
+          $pythonVersion = (& $pythonExe --version).Trim()
           $nodeVersion = (& $nodeExe --version).Trim()
           $chromeVersion = (Get-Item -LiteralPath $chromeExe.FullName).VersionInfo.ProductVersion
           if ([string]::IsNullOrWhiteSpace($chromeVersion)) {
@@ -71,13 +76,18 @@ jobs:
           }
           Write-Host "[runtime] pinned uv version: $($manifest.uv.version)"
           Write-Host "[runtime] bundled uv version: $uvVersion"
+          Write-Host "[runtime] pinned python version: $($manifest.python.version)"
+          Write-Host "[runtime] bundled python version: $pythonVersion"
           Write-Host "[runtime] pinned node version: $($manifest.nodejs.version)"
           Write-Host "[runtime] bundled node version: $nodeVersion"
           Write-Host "[runtime] pinned chrome version: $($manifest.chrome_for_testing.version)"
           Write-Host "[runtime] bundled chrome version: $chromeVersion"
           if ($uvVersion -notmatch ("^uv\s+" + [regex]::Escape($manifest.uv.version) + "(\s|$)")) {
             throw "Bundled uv version does not match pinned version in manifest"
           }
+          if ($pythonVersion -ne ("Python " + $manifest.python.version)) {
+            throw "Bundled python version does not match pinned version in manifest"
+          }
           if ($nodeVersion -ne ("v" + $manifest.nodejs.version)) {
             throw "Bundled node version does not match pinned version in manifest"
           }

.github/workflows/windows-packaging.yml

@@ -42,20 +42,25 @@ jobs:
           $manifest = Get-Content -Path $manifestPath -Raw -Encoding utf8 | ConvertFrom-Json
           & "${{ github.workspace }}/packaging/windows/build-installer.ps1" -OutputDir $out -RepoRoot "${{ github.workspace }}"
           $uvExe = Join-Path $out "tools/uv/uv.exe"
+          $pythonExe = Join-Path $out "tools/python/python.exe"
           $nodeExe = Join-Path $out "tools/node/node.exe"
           $chromeExe = Get-ChildItem -Path (Join-Path $out "tools/chrome") -Recurse -Filter "chrome.exe" -File -ErrorAction SilentlyContinue |
             Where-Object { $_.FullName -match "chrome-win" } |
             Select-Object -First 1
           if (-not (Test-Path $uvExe)) {
             throw "uv executable not found in staging: $uvExe"
           }
+          if (-not (Test-Path $pythonExe)) {
+            throw "python executable not found in staging: $pythonExe"
+          }
           if (-not (Test-Path $nodeExe)) {
             throw "node executable not found in staging: $nodeExe"
           }
           if (-not $chromeExe) {
             throw "chrome executable not found in staging under tools/chrome"
           }
           $uvVersion = (& $uvExe --version).Trim()
+          $pythonVersion = (& $pythonExe --version).Trim()
           $nodeVersion = (& $nodeExe --version).Trim()
           $chromeVersion = (Get-Item -LiteralPath $chromeExe.FullName).VersionInfo.ProductVersion
           if ([string]::IsNullOrWhiteSpace($chromeVersion)) {
@@ -66,13 +71,18 @@ jobs:
           }
           Write-Host "[runtime] pinned uv version: $($manifest.uv.version)"
           Write-Host "[runtime] bundled uv version: $uvVersion"
+          Write-Host "[runtime] pinned python version: $($manifest.python.version)"
+          Write-Host "[runtime] bundled python version: $pythonVersion"
           Write-Host "[runtime] pinned node version: $($manifest.nodejs.version)"
           Write-Host "[runtime] bundled node version: $nodeVersion"
           Write-Host "[runtime] pinned chrome version: $($manifest.chrome_for_testing.version)"
           Write-Host "[runtime] bundled chrome version: $chromeVersion"
           if ($uvVersion -notmatch ("^uv\s+" + [regex]::Escape($manifest.uv.version) + "(\s|$)")) {
             throw "Bundled uv version does not match pinned version in manifest"
           }
+          if ($pythonVersion -ne ("Python " + $manifest.python.version)) {
+            throw "Bundled python version does not match pinned version in manifest"
+          }
           if ($nodeVersion -ne ("v" + $manifest.nodejs.version)) {
             throw "Bundled node version does not match pinned version in manifest"
           }

.gitignore

@@ -100,15 +100,13 @@ tmp/
 
 # Documentation
 docs/_build/
-docs/*.md
 site/
 
 # Node.js (TUI)
 node_modules/
 tui/node_modules/
 bun.lockb
 .bun/
-docs/*
 !docs/CHANGELOG.md
 
 # TUI build

README.md

@@ -306,6 +306,10 @@ Scan the QR code with **WeChat** to join our official discussion group.
 
 ![WeCom official community QR code](assets/community-wecom-qr.png)
 
-## 6. License
+## 6. Contributing
+
+See [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) for development setup, coding standards, testing expectations, and Pull Request guidelines.
+
+## 7. License
 
 Apache License 2.0

README_zh.md

@@ -271,6 +271,10 @@ flocks start --server-host 127.0.0.1 --webui-host 0.0.0.0
 
 ![企业微信官方交流群二维码](assets/community-wecom-qr.png)
 
-## 6. 开源协议
+## 6. 参与贡献
+
+开发环境、代码规范、测试要求和 Pull Request 流程请参考 [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md)。
+
+## 7. 开源协议
 
 Apache License 2.0

docs/CONTRIBUTING.md

@@ -0,0 +1,197 @@
+# Contributing Guide
+
+Thank you for contributing to `flocks`. We welcome bug fixes, documentation improvements, tests, UX polish, new features, and other well-scoped changes that make the project better.
+
+This guide explains how to contribute in a way that is easy to review, maintain, and merge.
+
+## Ways to Contribute
+
+You can contribute by:
+
+- reporting bugs with clear reproduction steps
+- proposing features or design improvements
+- improving documentation, examples, and developer experience
+- fixing issues and adding regression coverage
+- improving the WebUI, CLI, workflows, plugins, tools, or platform integrations
+
+If your change is large or affects architecture, public behavior, or user workflows, please open an Issue first so the direction can be discussed before implementation starts.
+
+## Before You Start
+
+Before writing code, please:
+
+1. Search existing Issues and Pull Requests to avoid duplicate work.
+2. Confirm the scope for larger features, refactors, or behavior changes.
+3. Keep each contribution focused on one topic whenever possible.
+
+## Development Environment
+
+The main development stack for `flocks` currently includes:
+
+- Python `3.12`
+- `uv` for Python environment and dependency management
+- Node.js `22+`
+- `npm` for frontend dependencies
+
+Recommended setup:
+
+```bash
+uv sync --group dev
+cd webui && npm ci
+```
+
+If you work on browser-related features, you may also need the browser runtime dependencies described in the project README.
+
+## Common Commands
+
+Use `uv run` for Python-related commands whenever possible.
+
+### Backend / Python
+
+```bash
+uv run ruff check .
+uv run pytest
+```
+
+If your change is scoped to a smaller area, run the most relevant tests first:
+
+```bash
+uv run pytest tests/session
+uv run pytest tests/cli/test_service_manager.py
+```
+
+### Frontend / WebUI
+
+```bash
+cd webui
+npm run lint
+npm run build
+```
+
+If your change touches both Python and frontend code, please run checks for both parts.
+
+## Coding Standards
+
+Please make sure your changes follow the repository conventions:
+
+- Follow the Google Python Style Guide for Python code.
+- Use `ruff` for linting and formatting-related checks.
+- New features and bug fixes must include or update tests.
+- Keep all test code under `tests/`.
+- Except for the repository root `README.md`, feature guides, usage docs, and summary markdown files should go under `docs/`.
+- Run Python commands with `uv run`, or from the project's active virtual environment.
+- Any `.ps1` file in scripts must use **UTF-8 with BOM** encoding and **CRLF** line endings.
+
+Please also follow these general principles:
+
+- Keep changes focused and avoid unrelated refactors.
+- Add type hints, error handling, and regression coverage where they meaningfully improve maintainability.
+- Introduce new dependencies only when necessary, and explain why they are needed.
+- Add brief comments for non-obvious logic, but avoid low-value commentary.
+
+## Branching and Commits
+
+Create your working branch from the latest `dev` branch. Do not develop directly on `main`, and do not open contribution PRs against `main` unless a maintainer explicitly asks for it.
+
+Suggested branch naming examples:
+
+- `feat/add-session-export`
+- `fix/webui-login-redirect`
+- `docs/contributing-guide`
+- `refactor/mcp-client-cache`
+- `test/add-workflow-route-cases`
+
+Write commit messages in clear English. A Conventional Commits style is recommended:
+
+```text
+feat(cli): add service restart timeout option
+fix(auth): preserve session after password reset
+docs: add contributing guide
+test(session): cover runner retry path
+```
+
+A good commit should:
+
+- focus on one main change
+- describe intent clearly in the title
+- include extra context in the body when behavior, compatibility, or motivation needs explanation
+
+## Testing Expectations
+
+Please validate your change according to its scope:
+
+- Documentation changes: verify links, commands, filenames, and paths.
+- Python changes: run the relevant tests; for shared infrastructure changes, run broader coverage.
+- Frontend changes: run at least `npm run lint` and `npm run build`.
+- Cross-cutting changes: include enough automated or manual verification to show that the change works as intended.
+
+If you are fixing a bug, prefer adding a regression test that reproduces the issue before or alongside the fix.
+
+## Pull Request Guidelines
+
+All contribution PRs for `flocks` should target the `dev` branch.
+
+When opening a PR, make it easy for reviewers to understand:
+
+1. What problem the change solves.
+2. What the scope of the change is.
+3. Why the chosen approach is appropriate.
+4. How you validated the change.
+5. Whether there are compatibility, migration, or configuration impacts.
+
+If the PR changes UI or interaction behavior, include screenshots, recordings, or a clear before/after explanation.
+
+Recommended PR description template:
+
+```markdown
+## Summary
+- ...
+
+## Why
+- ...
+
+## Test Plan
+- [x] uv run pytest ...
+- [x] npm run lint
+- [ ] Manual verification
+```
+
+Please keep PRs as small and focused as practical. Multiple reviewable PRs are usually easier to merge than one large mixed change.
+
+## Issue Reporting
+
+This repository already provides GitHub Issue templates. Please choose the most appropriate template and include enough detail to make triage efficient:
+
+- Bug reports: reproduction steps, expected behavior, actual behavior, logs, and version information
+- Feature requests: motivation, proposed solution, alternatives considered, and expected impact
+- Plugin / tool requests: target use case, inputs, outputs, and relevant constraints
+
+High-quality Issues significantly improve response time and implementation quality.
+
+## Security Issues
+
+If you discover a security vulnerability or any issue that could expose users or deployments to risk, please do not disclose sensitive details in a public Issue. Contact the maintainers through an approved private channel first, then coordinate on disclosure after a fix is available.
+
+## Communication
+
+Please keep communication respectful, specific, and constructive:
+
+- discuss the problem, not the person
+- provide evidence and context, not just conclusions
+- stay open to review feedback, and split changes if needed
+
+We strongly prefer incremental, testable, reviewable contributions over large rewrites.
+
+## Pre-PR Checklist
+
+Before opening a PR, please confirm:
+
+- [ ] the change is focused and does not include unrelated edits
+- [ ] code, naming, and documentation style match the repository
+- [ ] new features or bug fixes include appropriate tests
+- [ ] relevant local checks have passed
+- [ ] the PR clearly explains background, approach, and validation
+- [ ] the PR targets `dev`
+- [ ] any new markdown documentation has been added under `docs/` when applicable
+
+Thank you for helping improve `flocks`.