Dev

.github/workflows/staging-lint.yml

@@ -16,7 +16,6 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.10"
-          cache: pip
 
       - name: Install ruff
         run: pip install ruff
@@ -36,7 +35,6 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.10"
-          cache: pip
 
       - name: Byte-compile source tree
         run: python -m compileall -q app agent_core agents decorators skills

.ruff.toml

@@ -0,0 +1,17 @@
+extend-exclude = [
+    "app/data/living_ui_template",
+]
+
+# E402 (module-level imports not at top) is triggered in files that deliberately
+# run setup code before imports — logging suppression, sys.path manipulation,
+# asyncio compatibility shims, or state-registry initialization that other
+# modules depend on at import time. These orderings are load-bearing.
+[lint.per-file-ignores]
+"agent_core/core/impl/context/engine.py" = ["E402"]
+"agent_core/core/prompts/__init__.py" = ["E402"]
+"agents/dog_agent/data/action/dog_behaviour.py" = ["E402"]
+"app/action/action_framework/run_actions_tests.py" = ["E402"]
+"app/config.py" = ["E402"]
+"app/llm_interface.py" = ["E402"]
+"app/main.py" = ["E402"]
+"craftos_integrations/__init__.py" = ["E402"]

CONTRIBUTING.md

@@ -52,54 +52,187 @@ git clone https://github.com/<your-github-username>/CraftBot.git
 cd CraftBot
 ```
 
-### Create a Branch
+---
+
+# 📋 Workflow SOPs
+
+Keep it simple. The point is shared rhythm, not bureaucracy.
+
+## 3. 🌿 Branches
+
+- Base off `dev`, never `main` or `staging`.
+- Name: `type/short-description` — kebab-case.
+  - Types: `feat`, `fix`, `chore`, `refactor`, `docs`, `hotfix`
+  - Examples: `feat/discord-role-sync`, `fix/webhook-retry-loop`
+- One branch = one focused change. If it grows past ~400 lines or two days of work, split it.
+- Delete the branch after merge.
+
+Flow: `dev` → `staging` → `main`. Never push directly to `staging` or `main`.
 
 Create a new branch for your work:
 ```shell
-git checkout -b feature/your-feature-name
+git checkout -b feat/your-feature-name
 ```
 
 To help fix a bug:
 ```shell
-git checkout -b bug/bug-name
+git checkout -b fix/bug-name
 ```
 
-Always branch from the `dev` branch.
+## 4. ✅ Commits
 
-## 3. 🎯 Making Changes
+**Format:**
+```
+<type> <issue number if exists eg: #245>: <short summary in imperative mood>
 
-1. **Code Style**: Follow the project's coding standards
-2. **Documentation**: Update relevant documentation
-3. **Tests**: Add tests for new features
-4. **Commits**: Write clear and detail commit messages
+<optional body — why, not what>
+```
+
+- Types: `feat`, `fix`, `chore`, `refactor`, `docs`, `test`, `style`
+- Summary ≤ 72 chars, no period, imperative ("add" not "added").
+- Body explains **why** the change was needed if it's not obvious. The diff shows *what*.
+- Commit often, but each commit should pass lint/build on its own.
+
+**Good:**
+- `fix: prevent duplicate role assignment on rejoin`
+- `feat: add /ban-history slash command`
 
-## 4. 📤 Submitting Changes
+**Bad:**
+- `update stuff`
+- `WIP`
+- `fixed the thing John mentioned`
 
-1. Install ruff on your system
-2. Run ```ruff format .``` and ``` ruff check ``` and fix the issues
-3. Push your changes:
+Before committing, run lint — see [section 5](#5--linting). Then:
 ```shell
 git add .
-git commit -s -m "Description of your changes"
+git commit -s -m "feat: your descriptive message"
 git push origin your-branch-name
 ```
 
-2. Create a Pull Request:
-   - Go to the [**CraftBot** repository](https://github.com/CraftOS-dev/CraftBot)
-   - Click "Compare & Pull Request" and open a PR against dev branch
-   - Fill in the PR template with details about your changes
+## 5. 🧹 Linting
+
+CraftBot uses [**ruff**](https://docs.astral.sh/ruff/) for both formatting and linting. The same checks run in CI on the `staging` branch (see [`.github/workflows/staging-lint.yml`](.github/workflows/staging-lint.yml)).
+
+Install if you don't have it:
+```shell
+pip install ruff
+```
+
+**Run before every commit:**
+```shell
+ruff format .         # auto-format your code
+ruff check .          # lint
+```
+
+**Auto-fix what ruff can fix:**
+```shell
+ruff check . --fix
+```
+
+**CI smoke test** (catches broken imports and syntax errors that ruff misses):
+```shell
+python -m compileall -q app agent_core agents decorators skills
+```
+
+### Common errors and how to fix them
+
+| Code  | What it means                          | Fix                                                                 |
+|-------|----------------------------------------|---------------------------------------------------------------------|
+| F401  | Unused import                          | Delete it. If it's an `__init__.py` re-export, add to `__all__`.    |
+| F841  | Unused local variable                  | Delete it. If it's the return of a side-effecting call, drop the LHS (`foo()` instead of `x = foo()`). |
+| F821  | Undefined name                         | **Real bug.** Missing import or typo.                               |
+| F402  | Import shadowed by loop variable       | **Real bug.** Rename the loop variable.                             |
+| E402  | Import not at top of file              | Move it up. If ordering is load-bearing (sys.path setup, logging suppression, asyncio shims), add the file to `[lint.per-file-ignores]` in [`.ruff.toml`](.ruff.toml). |
+| E712  | `== True` / `== False` comparison      | Use `if x:` / `if not x:`. For SQLAlchemy filters use `.is_(True)`. |
+| E722  | Bare `except:`                         | Replace with `except Exception:` (still catches everything you want, lets `KeyboardInterrupt`/`SystemExit` propagate). |
+| E741  | Ambiguous variable name (`l`, `I`, `O`)| Rename — e.g. `l` → `line`, `label`, `loop`, depending on context.  |
+
+### About `.ruff.toml`
+
+The repo ships a [`.ruff.toml`](.ruff.toml) that:
+- **Excludes** `app/data/living_ui_template/` — that directory contains Jinja templates with `{{placeholders}}`, not valid Python.
+- **Ignores E402 per-file** for a small set of files (logging setup, asyncio shims, registry init) where import ordering is deliberate.
+
+**Do not** add new entries casually. If you hit E402 in a new file, prefer moving the import; only add the file to the ignore list if the ordering is genuinely load-bearing, and explain why in your commit.
+
+## 6. 🔀 Pull Requests
+
+**Title:** same format as a commit (`feat: …`, `fix: …`). Keep under ~70 chars.
+
+**Description template:**
+```markdown
+## What
+1-3 bullets on what changed.
+
+## Why
+The problem this solves or the goal. Link the issue: Closes #123
+
+## How to test
+Steps to verify locally. Include any env vars, seed data, or commands.
+
+## Screenshots / Logs
+If UI or behavior changed.
+```
+
+**Rules:**
+- Open as **Draft** until it's ready for review.
+- Keep PRs small — under ~400 lines of diff where possible. Big PRs get stale and miss bugs.
+- Self-review your own diff before requesting review. Catch the obvious stuff first.
+- At least 1 approval before merge. No self-merging on shared branches.
+- Squash-merge into `dev` (keeps history clean). Merge-commit into `staging`/`main`.
+- Resolve all conversations before merging.
+- If CI is red, fix it — don't merge around it.
+
+**Open a PR:**
+- Go to the [**CraftBot** repository](https://github.com/CraftOS-dev/CraftBot)
+- Click "Compare & Pull Request" and open a PR against `dev`
+- Fill in the PR template with details about your changes
+
+## 7. 🐛 Issues
+
+**Bug template:**
+```markdown
+**What happened:**
+**What I expected:**
+**Steps to reproduce:**
+1.
+2.
+**Environment:** (browser, OS, server, version/commit)
+**Logs / screenshots:**
+```
+
+**Feature template:**
+```markdown
+**Problem:** What user pain are we solving?
+**Proposal:** What should it do?
+**Out of scope:** What we're *not* doing.
+**Acceptance:** How we know it's done.
+```
+
+**Labels (use at least one):**
+- `bug`, `feature`, `chore`, `docs`
+- Priority: `p0` (drop everything), `p1` (this sprint), `p2` (soon), `p3` (whenever)
+- `blocked`, `needs-info`, `good-first-issue`
+
+**Rules:**
+- Search before opening — avoid duplicates.
+- One problem per issue. Split if it's two things.
+- Assign yourself when you start working on it.
+- Close with the PR (use `Closes #123` in the PR body).
+
+---
 
-## 5. 🤝 Community Guidelines
+## 8. 🤝 Community Guidelines
 
 - Be respectful and inclusive
 - Help others learn and grow
 - Provide constructive feedback
 - Ask questions when unsure
 - Enjoy building agents
 
-## 6. 📫 To Get Help
+## 9. 📫 To Get Help
 
 - Open an [issue](https://github.com/CraftOS-dev/CraftBot)
 - Join our Discord community
 
-Thank you for contributing to **CraftBot**! 🌟
+Thank you for contributing to **CraftBot**! 🌟

README.cn.md

@@ -59,7 +59,7 @@ CraftBot 静候你的指令，现在就部署属于你的 CraftBot 吧。
 - **跨平台** — 完整支持 Windows、macOS 和 Linux，具有平台特定代码变体和 Docker 容器化。
 
 > [!IMPORTANT]
-> **GUI 模式已弃用。** CraftBot 不再支持 GUI（桌面自动化）模式。请改用 Browser、TUI 或 CLI 模式。
+> **GUI 模式已弃用。** CraftBot 不再支持 GUI（桌面自动化）模式。请改用 Browser 或 CLI 模式。
 
 <div align="center">
     <img src="assets/craftbot_readme_features.png" alt="CraftBot Banner" width="1280"/>
@@ -171,7 +171,7 @@ python run.py
 首次运行会引导你完成 API Key 设置和偏好配置。
 
 > [!NOTE]
-> 如果未安装 Node.js，安装器会提供详细指引。你也可以完全跳过浏览器模式，直接使用 TUI 模式——无需 Node.js：`python run.py --tui`
+> 如果未安装 Node.js，安装器会提供详细指引。你也可以完全跳过浏览器模式，直接使用 CLI 模式——无需 Node.js：`python run.py --cli`
 
 ### 安装完成后你可以做什么？
 - 用自然语言与代理交流
@@ -190,10 +190,9 @@ CraftBot 支持多种 UI 模式。根据你的偏好选择：
 | 模式 | 命令 | 要求 | 最适合 |
 |------|---------|--------------|----------|
 | **浏览器** | `python run.py` | Node.js 18+ | 现代 Web 界面，最易使用 |
-| **TUI** | `python run.py --tui` | 无 | 终端 UI，无需额外依赖 |
 | **CLI** | `python run.py --cli` | 无 | 命令行，轻量级 |
 
-**浏览器模式**是默认的推荐模式。如果你没有 Node.js，安装器会提供安装指引，或者你可以使用 **TUI 模式**。
+**浏览器模式**是默认的推荐模式。如果你没有 Node.js，安装器会提供安装指引，或者你可以使用 **CLI 模式**。
 
 ---
 
@@ -258,7 +257,6 @@ CraftBot 嵌入在每个 Living UI 中，并**感知其状态**：
 | **任务管理器** | 管理任务定义，支持简单和复杂任务模式，创建待办事项，多步骤工作流跟踪。 |
 | **技能管理器** | 加载并将可插拔技能注入代理上下文。 |
 | **MCP 适配器** | 模型上下文协议集成，将 MCP 工具转换为原生动作。 |
-| **TUI 界面** | 基于 Textual 框架构建的终端用户界面，用于交互式命令行操作。 |
 
 ---
 
@@ -285,7 +283,6 @@ CraftBot 嵌入在每个 Living UI 中，并**感知其状态**：
 | 参数 | 说明 |
 |------|-------------|
 | （无） | 以**浏览器**模式运行（推荐，需要 Node.js） |
-| `--tui` | 以**终端 UI** 模式运行（无需额外依赖） |
 | `--cli` | 以 **CLI** 模式运行（轻量级） |
 
 **安装示例：**
@@ -303,9 +300,6 @@ python install.py --conda
 # 浏览器模式（默认，需要 Node.js）
 python run.py
 
-# TUI 模式（不需要 Node.js）
-python run.py --tui
-
 # CLI 模式（轻量级）
 python run.py --cli
 
@@ -321,9 +315,6 @@ conda run -n craftbot python run.py
 # 浏览器模式（默认，需要 Node.js）
 python run.py
 
-# TUI 模式（不需要 Node.js）
-python run.py --tui
-
 # CLI 模式（轻量级）
 python run.py --cli
 
@@ -365,7 +356,7 @@ python craftbot.py logs     # 查看最近日志输出
 > 执行 `craftbot.py start` 或 `craftbot.py install` 后，系统会自动创建 **CraftBot 桌面快捷方式**。如果不小心关闭了浏览器，双击快捷方式即可重新打开。
 
 > [!NOTE]
-> **安装：** 安装器会在缺少依赖时提供清晰的指引。如果未找到 Node.js，会提示你安装或切换到 TUI 模式。安装会自动检测 GPU 可用性，必要时回退到仅 CPU 模式。
+> **安装：** 安装器会在缺少依赖时提供清晰的指引。如果未找到 Node.js，会提示你安装或切换到 CLI 模式。安装会自动检测 GPU 可用性，必要时回退到仅 CPU 模式。
 
 > [!TIP]
 > **首次设置：** CraftBot 会引导你完成引导流程，配置 API Key、代理名称、MCP 和技能。
@@ -383,9 +374,9 @@ python craftbot.py logs     # 查看最近日志输出
 2. 安装并重启终端
 3. 再次运行 `python run.py`
 
-**替代方案：** 使用 TUI 模式（不需要 Node.js）：
+**替代方案：** 使用 CLI 模式（不需要 Node.js）：
 ```bash
-python run.py --tui
+python run.py --cli
 ```
 
 ### 依赖安装失败