coopie 0.1.1__tar.gz

coopie-0.1.1/.copier-answers.yml

@@ -0,0 +1,19 @@
+# Changes here will be overwritten by Copier
+_commit: 298f2f8
+_src_path: https://github.com/gookeryoung/coopie
+author_email: gooker_young@qq.com
+author_name: gooker_young
+coverage_fail_under: 95
+description: 基于 [copier](https://copier.readthedocs.io/) 的通用 Python 项目模板。
+license: MIT
+max_python_version: '3.14'
+min_python_version: '3.8'
+package_name: coopie
+project_name: coopie
+pypi_token_secret: PYPI_TOKEN
+use_cicd: true
+use_docker: true
+use_docs: true
+use_domestic_mirrors: true
+use_tox: true
+

coopie-0.1.1/.dockerignore

@@ -0,0 +1,46 @@
+# 版本控制
+.git
+.gitignore
+.github
+
+# Python 缓存与构建产物
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+*.egg-info
+*.egg
+dist
+build
+.eggs
+
+# 测试与覆盖率
+.pytest_cache
+.coverage
+htmlcov
+.tox
+coverage.xml
+
+# 虚拟环境
+.venv
+venv
+env
+
+# 工具缓存
+.uv-cache
+.ruff_cache
+.pyrefly_cache
+.mypy_cache
+
+# IDE 与编辑器
+.idea
+.vscode
+*.swp
+*.swo
+
+# 文档（按需保留）
+docs
+
+# 系统文件
+.DS_Store
+Thumbs.db

coopie-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff check
+        run: uv run ruff check src tests
+
+      - name: Ruff format check
+        run: uv run ruff format --check src tests
+
+      - name: Pyrefly check
+        run: uv run pyrefly check .
+
+  test:
+    name: Test (Python 3.8 & 3.14)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run pytest -m "not slow" --cov=coopie --cov-fail-under=95 --cov-report=term-missing

coopie-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*.*.*']
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Build & Publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token '${{ secrets.PYPI_TOKEN }}'
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG_NAME: ${{ github.ref_name }}
+        run: |
+          gh release create "$TAG_NAME" \
+            --title "Release $TAG_NAME" \
+            --notes "Automated release from CI" \
+            dist/*

coopie-0.1.1/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.coverage
+.idea
+*_profile.html
+
+# Sphinx 文档构建输出
+docs/_build/
+.trae/refs
+

coopie-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+# prek / pre-commit 配置
+# See https://pre-commit.com for more information
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff 版本 - 与 pyproject.toml 保持同步
+    rev: v0.15.4
+    hooks:
+      # 运行 linter
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: fix-byte-order-marker
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer

coopie-0.1.1/.python-version

@@ -0,0 +1 @@
+3.8

coopie-0.1.1/.readthedocs.yaml

@@ -0,0 +1,23 @@
+# ReadTheDocs 配置
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+# 构建配置
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.8"
+
+# Python 依赖与构建命令
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+# Sphinx 构建
+sphinx:
+  configuration: docs/conf.py
+  builder: html
+  fail_on_warning: false

coopie-0.1.1/.trae/.ignore

@@ -0,0 +1,15 @@
+# PYTHON
+.coverage
+.pytest_cache/
+.ruff_cache/
+.tox/
+.venv/
+__pycache__/
+
+# NODEJS
+node_modules/
+
+# IDE
+.idea
+.trae
+.vscode

coopie-0.1.1/.trae/rules/dev-workflow.md

@@ -0,0 +1,23 @@
+# 开发流程约束
+
+本规则补充 `self-driven.md`，定义执行过程记录与规则变更的两条硬约束。
+
+## 执行过程记录
+
+- **每次迭代**（一个完整的"计划 → 实现 → 测试 → 文档 → 验证"闭环）必须记录到
+  `.trae/docs/` 目录，文件名形如 `iter-NN-<主题>.md`，`NN` 为零填充序号。
+- 记录内容至少包括：本轮目标、改动文件清单、关键决策与依据、验证结果、遗留事项。
+- **每 5 次迭代后**清理 `.trae/docs/`：
+  - 把需要长期保留的整合性内容（可复用模式、踩坑总结、设计决策）
+    归档到 `.trae/skills/` 对应技能文档中；
+  - 其余过程性记录删除；
+  - docs 目录只保留最近未归档的迭代记录（即第 6 次迭代开始前，清理 1–5 号记录）。
+- 归档动作需在迭代记录中标注"已归档至 skills/<文件>"。
+
+## 规则变更约束
+
+- 任何对 `.trae/rules/` 下文件的修改（新增、编辑、删除）**必须先询问用户**，
+  获得明确授权后方可变动；**未授权前不得擅自修改 rules**。
+- 用户在对话中显式要求写入的规则内容（如"把 X 写入 rules"）视为已授权，
+  可直接写入，写入后在回复中说明改了哪个文件、加了什么。
+- 规则变更后需同步更新 `project_memory.md` 中的"开发约定"小节。

coopie-0.1.1/.trae/rules/git-commit-message.md

@@ -0,0 +1,11 @@
+---
+alwaysApply: true
+scene: git_message
+---
+
+在此处编写规则，自定义 AI 生成提交信息的风格。
+
+## 提交信息格式
+- 提交信息必须使用中文。
+- 提交信息必须包含变更的类型（例如 "fix"、"feat"、"refactor" 等）。
+- 提交信息必须尽简洁明了，不要超过一段落。

coopie-0.1.1/.trae/rules/python-standards.md

@@ -0,0 +1,155 @@
+# Python 开发规范
+
+本规范结合 Python 最佳实践，作为编写与审查 Python 代码的统一标准。
+
+## 工具链（以 pyproject.toml 为准）
+
+| 工具 | 用途 | 配置要点 |
+|------|------|---------|
+| **ruff** | lint + format | `line-length=120`，`target-version="py38"` |
+| **pyrefly** | 类型检查 | `preset="strict"`，`python-version="3.8"` |
+| **pytest** | 测试 | `asyncio_default_fixture_loop_scope="function"`，marker `slow` |
+| **coverage** | 覆盖率 | `branch=true`，`fail_under=95`，`concurrency=["thread"]` |
+| **pre-commit** | 提交前检查 | ruff `--fix` + trailing-whitespace + end-of-file-fixer |
+
+验证（每次修改后必做）：
+
+```bash
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run pyrefly check .
+uv run pytest -m "not slow" --cov=coopie --cov-fail-under=95
+```
+
+## 兼容性
+
+- **最低 Python 3.8**：用 `from __future__ import annotations` 延迟注解求值；
+  按版本用 `typing.List`(3.8) → 内置泛型(3.9) → `X | Y`(3.10) → `typing.override`(3.12)。
+- **版本守卫**：`if sys.version_info >= (3, X):` 引入高版本 API；低版本回退分支加 `# pragma: no cover`。
+- **优先标准库**：优先使用标准库实现功能；需 `typing-extensions` 用于 `override`/`TypeVar` 前向兼容
+  （`python_version < '3.13'` 时自动引入）。新增第三方依赖须审慎，优先用标准库。
+
+## 类型注解
+
+- **公共 API 必须有完整类型注解**，包括返回类型；私有函数也应有注解。
+- 泛型用 `TypeVar`；PEP 696 `default=` 仅 3.13+ 标准库支持，3.8–3.12 用 `typing_extensions.TypeVar`。
+- `Mapping`/`Sequence` 用于只读参数，`dict`/`list` 用于可变返回。
+- `Any` 仅用于真正动态场景；内部类型必须完全静态。
+- 禁用裸 `# type: ignore`；确需时加具体规则码（如 `# type: ignore[union-attr]`）。
+- **`TYPE_CHECKING` 守卫**：仅类型检查需要的导入放 `if TYPE_CHECKING:` 块内，避免循环依赖。
+- **类型收窄**：用 `assert isinstance(x, Y)` 辅助 pyrefly 推断；`cast()` 仅用于类型系统无法表达的场景。
+
+## 数据结构
+
+- **不可变优先**：配置/描述类用 `@dataclass(frozen=True)`；可变类属性标注 `RUF012` 豁免。
+- **缓存**：实例级用 `functools.cached_property`，按参数键控用 `functools.lru_cache`；
+  不可哈希参数需 try/except 回退。修改被缓存数据源后必须手动清空缓存。
+- **抽象基类**：接口用 `abc.ABC` + `@abstractmethod`。
+- **枚举**：状态/标志值用 `enum.Enum`，禁止裸字符串/魔术数字；枚举值用 `UPPER_SNAKE`。
+- **`__repr__`**：可变类实现 `__repr__`（含关键字段）；`frozen=True` dataclass 自动生成。
+
+## 模块与导入
+
+- **单一职责**：每模块只做一件事。禁止跨职责边界。
+- **导入顺序**（ruff isort）：`__future__` → 标准库 → 第三方 → 本地，各组间空行。
+- **惰性导入**：仅为打破循环依赖时使用，函数体内导入并注释说明；顶层导入是默认。
+- **`__all__`**：定义 `__all__` 显式声明导出符号，位置仅次于 `__future__` 之后。
+- **禁用 star imports**：`from x import *` 污染命名空间、破坏类型检查（`__init__.py` 聚合经 `__all__` 控制为例外）。
+- **避免 `utils.py`/`helpers.py`**：按职责归入对应模块。
+
+## 函数设计
+
+- **模块级函数优于 Mixin**：共享逻辑用模块级函数，类只持有状态与薄方法。
+- **静态方法慎用**：纯函数直接放模块级。
+- **参数 ≤ 5 个**为宜；超出用 dataclass 封装参数对象。
+- **单一职责**：一个函数做一件事；过长函数考虑拆分。
+- **异常范围要窄**：只捕获预期异常（如 `(TypeError, ValueError, KeyError, AttributeError)`），
+  **禁止** `except Exception` 掩盖 bug；捕获后至少 `logger.warning` 记录。
+- **可变默认参数**：`def f(x=[])` 是经典坑；用 `None` 哨兵或 `field(default_factory=list)`。
+
+## 异常处理
+
+- **自定义异常家族**：继承公共基类，按错误场景分类。
+- **异常包装**：`raise NewError(...) from exc` 保留因果链。
+- **不要吞异常**：捕获后必须处理（记录/包装/重抛），禁止空 `except: pass`。
+- **钩子/回调异常**：第三方回调异常仅记录，不影响主流程。
+
+## 并发与线程安全
+
+- **进程全局状态**（`os.environ`/`os.chdir`）在并发场景下必须用全局锁（`threading.RLock`）序列化。
+- **批量 I/O**：循环内多次写盘改为批量一次（`contextmanager` 包裹延迟落盘）。
+- **信号量限流**：按组限流时用 `Semaphore`。
+
+## 测试
+
+- **覆盖率 ≥ 95%**（branch coverage），不得下降。
+- **公共 API 优先测试**：用公共接口测试，不访问私有方法；
+  故障注入等场景可临时访问私有属性，docstring 注明原因。
+- **命名**：`test_<被测对象>_<场景>`。
+- **断言**：原生 `assert x == 1`，禁用 `self.assertEqual`；`pytest.raises` 必填 `match=`。
+- **Mock 优先级**：`monkeypatch` > 内联 stub > `unittest.mock` > `pytest-mock`。
+  禁用 `@patch` 装饰器、`mock.patch.object` 上下文、`pytest-mock` 的 `mocker` fixture。
+- **fixture**：`tmp_path`/`monkeypatch`/`capsys` 优先；autouse 仅全局必需时用。
+- **slow 标记**：耗时测试加 `@pytest.mark.slow`，CI 可 `-m "not slow"` 跳过。
+- **测试代码也跑 ruff**：`tests/**` 忽略 `ARG001`/`ARG002`。
+
+## 代码风格
+
+- **行宽 120**（ruff formatter 处理）。
+- **docstring**：公共 API 必须有；中文叙述 + 中文注释是本项目既有风格。
+- **打印和日志**：使用中文打印和日志，避免使用英文。
+- **命名**：`snake_case` 函数/变量，`PascalCase` 类，`UPPER_SNAKE` 常量，`_leading_underscore` 私有。
+- **字符串引号**：ruff 默认双引号。
+- **末尾单 `\n`**、**无尾随空格**（pre-commit 强制）。
+- **不用 emoji**：除非用户明确要求。
+
+## Pythonic 风格
+
+- **`is` 比较 `None`/`True`/`False`**：单例用 `is`，值用 `==`（PEP 8 E711/E712）。
+- **EAFP 优于 LBYL**：先尝试再处理异常，而非先检查再执行（避免竞态窗口）。
+- **truthiness**：`if items:` 优于 `if len(items) > 0:`。
+- **字符串格式化**：首选 f-string；`%` 仅用于 `logging` 延迟格式化。
+- **推导式**优于 `map`+`filter`；> 2 层拆为显式循环。
+- **`enumerate`** 替代 `range(len())`；**`zip`** 并行迭代（3.10+ 用 `strict=True`）。
+- **解包** `a, b = pair` 优于索引访问；忽略值用 `_`。
+- **海象运算符 `:=`**（3.8+）：赋值+判断合一，但不滥用。
+
+## 日志
+
+- **`logging.getLogger(__name__)`**：每模块独立 logger，禁用 `print` 调试残留。
+- **结构化上下文**：`extra={...}` 传字段；`logger.warning("task %r failed: %s", name, exc)` 优于 f-string（延迟格式化）。
+- **日志级别**：`DEBUG` 诊断 / `INFO` 关键流程 / `WARNING` 可恢复异常 / `ERROR` 需人工介入。
+- **禁止日志密码/密钥**：脱敏后再记录。
+
+## 路径与资源
+
+- **优先 `pathlib.Path`**：`Path("a") / "b"` 而非 `os.path.join`（ruff `PTH` 强制）；
+  禁止字符串拼接路径。类型注解用 `Path`，边界 `str` 立即包装。
+- **`with` 语句**：文件、锁、连接、临时目录一律用 `with` 或 `contextlib.contextmanager`；
+  多资源用 `contextlib.ExitStack`。
+- **显式关闭**：长生命周期对象（连接池、线程池）实现 `close()`，但优先 `with`。
+- **批量操作**：循环内多次 acquire/release 改为批量一次。
+
+## 安全
+
+- **禁用 `eval`/`exec`**：处理不可信输入时绝不使用；用 `ast.literal_eval` 或专用解析器。
+- **`subprocess`**：禁用 `shell=True` 除非命令完全可信；优先 `list[str]` 形式。
+- **凭证不入仓**：密钥/token/密码放 `.env` 或环境变量，`.gitignore` 必须包含 `.env`。
+- **日志脱敏**：记录请求/响应时移除 `Authorization`、`password` 等字段。
+- **依赖审计**：`uv lock` 后审阅新增依赖，避免引入已知 CVE 的包。
+
+## 性能要点
+
+- **避免重复计算**：循环内查询应缓存或预构建映射（如 `{name: spec}`）。
+- **避免双重查找**：`has(k)` + `get(k)` 改为单次 `get(k)` + `KeyError` 回退。
+- **统一校验**：入口校验一次，下游路径不重复。
+- **事件 emit**：生命周期必须 emit 完整状态转换，不要留死分支
+  （`# pragma: no cover` 是清理信号，应激活或删除）。
+
+## Git 与提交
+
+- **自动提交**：任务完成后自动 `git add`（按文件名）+ `git commit` + `git push`（仅当分支已跟踪远程时执行 push；新分支跳过 push 并在总结中说明）。
+- **不修改 git config**。
+- **不运行破坏性命令**（`push --force`/`reset --hard`/`clean -f`）除非用户明确要求。
+- **staging**：按文件名添加，不用 `git add -A`/`git add .`，避免误加敏感文件。
+- **commit message**：简洁，聚焦"为什么"而非"是什么"；遵循仓库既有风格。

coopie-0.1.1/.trae/rules/self-driven.md

@@ -0,0 +1,149 @@
+---
+alwaysApply: true
+---
+
+# 自驱动开发规则
+
+本规则定义一种"目标驱动、闭环执行"的工作模式：仅在任务开始时与用户确认一次目标与边界，后续由 Agent 自主完成"计划 → 编码 → 测试 → 文档 → 验证"的迭代循环，直到用户目标达成。
+
+## 核心原则
+
+- **目标导向**：始终以用户最终目标为准绳，所有阶段产出都应服务于该目标。
+- **闭环执行**：每个子任务必须走完"计划 → 实现 → 测试 → 文档 → 验证"五步；禁止跳步留半成品。
+- **自主决策**：初始确认之后，实现路径、API 形态、重构范围、文件命名、测试组织、错误修复策略等由 Agent 自行决断，不再逐项请示。**可逆操作（编辑文件、运行测试、修复 lint、调整实现）直接执行，不询问**；只有不可逆/高风险操作才暂停。
+- **透明沟通**：每个阶段开始前用一句话说明意图；关键节点（完成、阻塞、转向）给简短更新；不复述内部思考，**不在收尾时停下询问"是否继续"或"是否提交"**——直接输出总结并结束。
+- **安全边界**：仅在高风险、不可逆操作或真正阻塞时才暂停找用户。
+
+## 初始确认（一次性，仅在最开始）
+
+任务启动时，用 `AskUserQuestion` 一次性确认以下信息（已由项目规范覆盖的不必重复确认）：
+
+1. **目标与范围**：要解决什么问题？交付物是什么？显式列出不在范围内的内容。
+2. **验收标准**：怎样算"完成"？可观测的判定条件（功能、性能、覆盖率阈值）。
+3. **特殊约束**：除 `python-standards.md` 之外的约束（兼容性、依赖限制、API 兼容策略等）。
+4. **测试要求**：覆盖率门槛（项目默认 ≥95%，branch）；是否需要新增 `slow` 标记。
+
+**git commit/push 不在确认范围内**：任务完成后自动 commit + push（仅当分支已跟踪远程时执行 push；新分支跳过 push 并在总结中说明），遵循 `.trae/rules/git-commit-message.md` 风格。仅 force-push、reset --hard、clean -f、修改 git config 等真正破坏性操作才需暂停确认。
+
+确认后，将目标与验收标准固化进 `TaskCreate` 任务列表，后续不再就同一信息反复询问。
+
+## 迭代循环
+
+下列五个阶段构成一个完整闭环。未达验收标准时，回到「计划」开启下一轮；达标准时，进入「收尾」。
+
+### 1. 计划（Plan）
+
+- 用 Explore/Glob/Grep 研究相关代码与既有模式，避免凭空设计。
+- 用 `TaskCreate` 把目标拆为可独立验证的子任务；每完成一项立即 `TaskUpdate` 为 completed。
+- 优先复用现有抽象；不为本轮假想需求设计接口。
+- 不过早抽象：三处相似才考虑提取，否则就地写。
+
+### 2. 实现（Code）
+
+- 严格遵守 `.trae/rules/python-standards.md` 与既有代码风格。
+- 优先 Edit 现有文件；新增文件需有明确职责边界。
+- 公共 API 必须有完整类型注解与中文 docstring。
+- 不写未被要求的功能、不为未来场景预留扩展点。
+
+### 3. 测试（Test）
+
+- 新增/修改的公共 API 必须配套测试；优先通过公共接口测试，故障注入可访问私有属性并在 docstring 注明。
+- Mock 优先级：`monkeypatch` > 内联 stub > `unittest.mock` > `pytest-mock`；禁用 `@patch` 装饰器。
+- 必跑校验（每次修改后）：
+
+  ```bash
+  uv run ruff check src tests
+  uv run pytest -m "not slow" --cov=coopie --cov-fail-under=95
+  ```
+
+- 测试失败时定位根因再修复，不通过放宽断言或 `# pragma: no cover` 绕过。
+- 覆盖率不得低于上一次的值（项目门槛 95%，branch）。
+
+### 4. 文档（Docs）
+
+- 同步更新 docstring、README、模块结构说明。
+- 跨会话有价值的设计决策、约束、陷阱，追加到 memory（`project_memory.md` 或对应 `topics.md`）。
+- 不主动新建 `*.md` 文档；除非用户明确要求。
+
+### 5. 验证（Verify）
+
+- 逐条对照初始确认的「验收标准」核验；未满足则回到「计划」继续下一轮。
+- 全套门禁通过：ruff、pyrefly、pytest、coverage。
+- 给出本轮变更清单（改了哪些文件、为什么）。
+
+## 多阶段项目
+
+当项目按阶段（P0/P1/P2/...）划分时，初始确认的目标是**整个项目**，而非单个阶段。
+
+- **阶段是里程碑，不是边界**：确认"推进 P1"只是指定下一步重点，不缩小整体目标范围；
+  也不意味着 P1 完成后就可以停下。整体目标 = 所有阶段交付完毕。
+- **阶段完成不是停止条件**：某阶段验收标准全部满足后，**自动进入下一阶段的「计划」步骤**，
+  不停下来输出"是否继续"或"是否扩展范围"的询问。仅在阶段切换时用一句话说明
+  "进入 Pn，重点：…"，然后继续自驱动迭代。
+- **「收尾」仅适用于整个项目完成**：只有所有阶段（含最后一个）都交付后，才执行
+  「收尾」输出最终总结。单阶段完成 → 进入下一阶段的「计划」，不触发收尾。
+- **跨阶段依赖**：若下一阶段依赖外部资源（如新依赖审批、环境配置），属"不可恢复的失败"
+  暂停条件；否则一律连续推进。
+- **阶段范围超出预期**：执行中发现某阶段需要显著扩大范围或改变方向，
+  属"超出初始确认范围"暂停条件，需找用户确认。
+
+## 暂停条件（仅在以下情况中断自驱动找用户）
+
+1. **歧义无法自决**：需求存在多种合理解读且无既有约定可循。
+2. **高风险/不可逆操作**：删除非临时文件、`git push --force`、`reset --hard`、删表、修改 CI 配置、修改 git config、卸载依赖等。**普通 `git commit`/`push` 不属于此类**（任务完成后自动执行）。
+3. **不可恢复的失败**：根因不在本仓库、需外部环境/权限配合、或经两轮尝试仍无法定位。
+4. **超出初始确认范围**：用户目标在执行中发现需要显著扩大范围或改变方向。
+5. **用户主动询问**：用户在对话中提出新问题或要求澄清。
+
+**注意**："目标已达成"**不是**暂停条件——但"目标已达成"指**整个项目目标**（所有阶段交付完毕），而非单个阶段验收满足。单阶段验收满足后应自动进入下一阶段（见「多阶段项目」），不触发收尾。
+
+非以上情况，一律继续自驱动，不要为"求确认"而暂停。
+
+## 决策判据：该问还是自决
+
+遇到不确定时，按以下顺序判断：
+
+1. **是否不可逆/高风险？** 是 → 暂停确认（如删除文件、`push --force`、修改 CI 配置、卸载依赖）。否 → 继续。
+2. **是否在初始确认范围内？** 是 → 按确认执行，不询问。否 → 视为"超出初始确认范围"，暂停。
+3. **是否有既有约定可循？** 是 → 按约定执行（参考 `python-standards.md`、`project_memory.md`）。否 → 视为"歧义无法自决"，暂停。
+4. **是否可逆？** 是 → 直接执行，即使结果可能不完美（可在后续迭代修正）。否 → 暂停。
+
+**可直接自决（不询问）的典型情况**：
+
+- 测试失败、覆盖率不达标、lint/类型检查报错 → 定位根因并修复。
+- 代码风格选择（命名、模块划分、参数顺序）→ 自决。
+- 文件编辑、运行测试、运行校验命令 → 直接执行。
+- 任务完成后输出收尾总结 → 直接输出，不询问下一步。
+- 显式指定 `name` 参数以保持测试兼容性 → 自决。
+- 重命名局部变量以避免遮蔽 → 自决。
+
+**必须暂停询问的典型情况**：
+
+- 删除非临时文件、重命名公共模块/包。
+- `git push --force`、`reset --hard`、`clean -f`、修改 git config（普通 commit/push 自动执行，无需询问）。
+- 引入新的运行时依赖。
+- 修改 CI 配置、pre-commit 钩子、pyproject.toml 的工具链配置。
+- 卸载或降级既有依赖。
+
+## 沟通风格
+
+- 阶段切换时一句话说明即可；不要把内部推理写给用户看。
+- 完成子任务后用一两句总结改了什么、下一步做什么。
+- 遇到阻塞时直接说明：卡在哪、试了什么、需要用户做什么。
+- **不在收尾时询问"是否需要提交"或"是否扩展范围"**——直接输出总结并结束。用户后续若有新需求，由用户主动提出。
+- 不使用 emoji，除非用户明确要求。
+
+## 工具使用
+
+- 独立操作尽量并行调用（多个 Read/Grep/Glob 一批发出）。
+- 用 `TaskCreate`/`TaskUpdate` 维护进度，不批量推迟标记。
+- 长命令用后台运行（`run_in_background`），完成会自动通知。
+- 文件操作一律用专用工具：Read/Edit/Write/Glob/Grep，不用 `cat`/`sed`/`grep`/`find`。
+
+## 收尾
+
+- **仅当整个项目所有阶段都交付后**，才执行收尾：直接输出最终总结并结束任务（交付物、关键决策、遗留事项）。
+- 单阶段完成**不属于收尾**——见「多阶段项目」，应自动进入下一阶段的「计划」。
+- **自动提交**：收尾时自动 `git add`（按文件名）+ `git commit`（遵循 `.trae/rules/git-commit-message.md` 风格）+ `git push`（仅当分支已跟踪远程时执行；新分支跳过 push 并在总结中说明）；**不询问**"是否需要提交"或"是否扩展范围"。
+- 若验收标准未全部满足，回到「计划」继续下一轮，不停下询问。
+- 将本次会话的关键产出与决策更新到 memory，便于后续会话续接。

coopie-0.1.1/.vscode/settings.json

@@ -0,0 +1,35 @@
+{
+    "[python]": {
+        "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "always",
+            "source.organizeImports.ruff": "always",
+            "source.sort.json": "always"
+        },
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true
+    },
+    "[toml]": {
+        "editor.defaultFormatter": "tamasfe.even-better-toml",
+        "editor.formatOnSave": true
+    },
+    "evenBetterToml.formatter.alignComments": true,
+    "evenBetterToml.formatter.alignEntries": true,
+    "evenBetterToml.formatter.allowedBlankLines": 1,
+    "evenBetterToml.formatter.arrayAutoCollapse": true,
+    "evenBetterToml.formatter.arrayAutoExpand": true,
+    "evenBetterToml.formatter.arrayTrailingComma": true,
+    "evenBetterToml.formatter.compactEntries": false,
+    "evenBetterToml.formatter.indentEntries": false,
+    "evenBetterToml.formatter.indentTables": false,
+    "evenBetterToml.formatter.reorderArrays": true,
+    "evenBetterToml.formatter.reorderInlineTables": true,
+    "evenBetterToml.formatter.reorderKeys": true,
+    "python.languageServer": "None",
+    "python.testing.pytestArgs": [
+        "src",
+        "tests",
+    ],
+    "python.testing.pytestEnabled": true,
+    "python.testing.unittestEnabled": false,
+    "ruff.importStrategy": "fromEnvironment"
+}