docs: clean stale pages and update coding style (#1056)

Author: cosven

AGENTS.md

@@ -58,7 +58,8 @@ Notes:
 
 Primary docs:
 - `docs/source/dev_quickstart.rst`
-- `docs/source/coding_style.rst`
+- `docs/source/dev_best_practice.rst` (read on demand for coding style,
+  UI design, runtime debugging, and recent engineering practices)
 - `docs/source/contributing.rst`
 - `docs/source/arch.rst`
 
@@ -94,44 +95,3 @@ Responsive layout rule:
 - Let a page own its responsive reflow logic based on its own available width.
 - Avoid parent-coupled resize orchestration unless there is a proven structural
   need.
-
-## 6) Workflow
-
-Keep a lightweight todo list for the current task:
-- Update it before/after each meaningful step.
-- Mark items done as soon as they are completed.
-- Save it under `.tasks/` (for example, `.tasks/todo.md`).
-
-Keep a short proposal note for design changes:
-- Capture the intended approach, tradeoffs, and assumptions.
-- Use it to confirm alignment before coding.
-- Save it under `.tasks/` (for example, `.tasks/proposal.md`).
-
-Minimal templates:
-
-Todo:
-- [ ] Step 1
-- [ ] Step 2
-
-Proposal:
-- Approach: ...
-- Tradeoffs: ...
-- Assumptions: ...
-
-## 7) Recent Engineering Notes
-
-- Prefer semantic API names over scenario-specific ones:
-  - Good: `show_cover_with_source(artwork, source, uid)`
-  - Avoid: names that encode one caller context (for example `show_current_song_*`)
-- For cover/image loading, keep a clear boundary:
-  - Data/adapter layer should convert `(url, source)` into `Media`.
-  - Widget layer should consume `Media` directly (`show_cover_media`) whenever possible.
-- Avoid broad fallback branches that hide failures. If input contract is wrong,
-  fail early with explicit type/shape checks.
-- Before removing helper functions, run an explicit usage check (`rg`) and keep
-  shared helpers when they are still used in multiple GUI paths.
-- For GUI-heavy changes, run focused GUI/library test sets first; if full Qt/mpv
-  pytest is unstable in local environment, report it explicitly in PR notes.
-- When creating/updating PR descriptions via `gh`, prefer `--body-file` or GraphQL
-  `updatePullRequest` with a file-loaded body; avoid inline escaped `\n` strings
-  that may show up literally in the PR description.

docs/source/coding_style.rst

@@ -59,7 +59,7 @@ FeelUOwn 这个项目从 2015 年初开发到现在，已经 4 年有余，
 和大家同步并讨论，之后再动手开发。
 
 如果需要进行修改代码（包括文档等），可以参考 :doc:`dev_quickstart` ，
-代码风格请参考 :doc:`coding_style` ，一些 FeelUOwn
+开发最佳实践请参考 :doc:`dev_best_practice` ，一些 FeelUOwn
 架构设计相关的决策，可以参考 :doc:`arch` 和 :doc:`api` 等文档。
 
 最后值得一提的是，我们有一个开发者/用户交流群（邀请链接在 README_ 中），大家可以加入群里，

docs/source/contributing.rst

@@ -0,0 +1,91 @@
+开发最佳实践
+============
+
+
+代码风格
+--------
+
+注释
+~~~~
+
+- 注释统一用英文（老的中文注释应该逐渐更改）
+- docstring 使用 `Sphinx docstring format`_
+- FIXME, TODO, and HELP
+
+  - FIXME: 开发者明确知道某个地方代码不优雅
+  - HELP: 开发者写了一段自己不太理解，但是可以正确工作的代码
+  - TODO: 一些可以以后完成的事情
+  - 暂时不推荐使用 NOTE 标记
+
+测试
+~~~~
+
+- feeluown 包相关代码都应该添加相应测试。
+- GUI 改动优先运行 focused GUI/library 测试。如果本地环境中完整 Qt/mpv pytest
+  不稳定，应在 PR 说明中明确记录。
+
+错误处理
+~~~~~~~~
+
+- Qt 中同步调用资源提供方接口时，都应该处理 Exception 异常，否则应用可能会 crash。
+- 避免用宽泛的 fallback 分支隐藏失败。如果输入契约不符合预期，应通过明确的
+  类型或结构检查尽早失败。
+
+特殊风格
+~~~~~~~~
+
+- 标记了 alpha 的函数和类，它们的设计都是不确定的，外部应该尽少依赖。
+
+类
+~~
+
+- Qt Widget 的子类的 UI 相关设置初始化应该放在 ``_setup_ui`` 函数中。
+- 信号的 slot 方法应该设为 protected 方法。
+- 类的 public 方法放在类的前面，protected 和 private 方法放在类的最后面，
+  ``_setup_ui`` 函数除外。
+- QWidget 子类最好不要有 async 方法，因为目前无法很好的为它编写相关单元测试。
+
+
+UI 设计
+-------
+
+- 设计 UI 时要考虑 Linux、Windows、macOS 的兼容性。颜色应尽量来自系统
+  调色板，比如 ``QPalette`` 的 ``Window``、``Base``、``Text``、
+  ``WindowText``、``Highlight`` 等角色，而不是硬编码某一种颜色。
+
+
+运行时调试
+----------
+
+- 可以用 ``fuo exec`` 连接正在运行的应用，执行 Python 代码来调试界面状态、
+  构造测试场景或读取对象属性。启动应用时不要使用 ``-ns``，因为它表示
+  no-server，``fuo exec`` 将无法连接到应用。
+- ``fuo exec`` 支持从 stdin 接收多行 Python 代码。调试复杂流程时优先使用
+  这种方式，避免在 shell 参数中处理繁琐的引号和转义。示例::
+
+    # 在 tmux 中启动 GUI，并打开 server
+    uv run fuo -vv
+
+    # 在另一个 shell 中注入多行 Python 代码
+    uv run fuo exec <<'EOF'
+    print(type(app).__name__)
+    print(app.ui)
+    EOF
+
+
+工程经验
+--------
+
+- API 命名应优先表达语义，而不是绑定某个调用场景。例如
+  ``show_cover_with_source(artwork, source, uid)`` 比编码某个具体 caller
+  上下文的名字更清晰。
+- 封面和图片加载应保持清晰边界：数据/适配层负责把 ``(url, source)`` 转换为
+  ``Media``，widget 层尽量直接消费 ``Media``。
+- 删除 helper 函数前，先用 ``rg`` 明确检查使用点。如果它仍被多个 GUI 路径共享，
+  应保留这个 helper。
+- 通过 ``gh`` 创建或更新 PR 描述时，优先使用 ``--body-file``，或使用 GraphQL
+  ``updatePullRequest`` 并从文件读取正文；避免在命令行里内联转义 ``\n``，
+  否则 PR 描述可能出现字面量 ``\n``。
+
+
+.. _Sphinx docstring format: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#the-sphinx-docstring-format

docs/source/dev_best_practice.rst

@@ -19,8 +19,6 @@ FeelUOwn 是一个用户友好、可玩性强的播放器
    quickstart
    features
    fuorc
-   roadmap
-   faq
 
 
 .. toctree::
@@ -35,5 +33,5 @@ FeelUOwn 是一个用户友好、可玩性强的播放器
    glossary
    research
    philosophy
-   coding_style
+   dev_best_practice
    contributing

docs/source/faq.rst

@@ -72,7 +72,7 @@ Ubuntu
     pipx inject feeluown pyopengl
 
     # 运行 feeluown -h 来测试安装是否成功
-    # 如果提示 Commmand Not Found，请查看文档「常见问题」部分
+    # 如果提示 Command Not Found，请检查 pipx 的 PATH 配置
     feeluown -h
 
     # 生成桌面图标