task-ledger 1.2.9 → 1.3.1

package/scripts/ledgerkit/actions/close_task.py

@@ -0,0 +1,180 @@
+"""结案：历史加一行 → 封卷过程文档 → **最后**删分片那行。
+
+`finished` 必填、由外壳算好（同一个值也用于算锁集与刷取范围）—— 业务层不许再调时钟，
+这是跨月刷错月份的唯一根因。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity
+from ..core.labels import normalize_label, parse_tags
+from ..core.paths import history_path_for, shard_rel, to_repo_rel, worklog_name
+from ..core.worklog_md import (
+    append_exec_log,
+    exec_line,
+    has_frozen_line,
+    rewrite_label_line,
+    stamp_frozen,
+)
+from ..errors import Fail
+from ..store.atomic import ensure_dir, fingerprint, restore, snapshot
+from ..store.history_store import HIT, UNDECIDABLE, HistoryStore
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .result import Result, rel
+
+_COLS_FALLBACK_HINT = "警告：历史表列数不是 9 且无法整体升级，本次按现有列数追加。"
+
+
+def close_task(
+    repo: Path,
+    me: Identity,
+    tid: str,
+    *,
+    summary: str,
+    finished: str,
+    category: str | None = None,
+    tags: tuple[str, ...] | None = None,
+) -> Result:
+    """写序四步：改标签行 → 历史加一行 → 封卷 → 删分片（永远是最后一步）。"""
+    if not finished:
+        raise Fail("结案必须由外壳先算好时间（内部错误：finished 为空）。")
+    text_summary = " ".join((summary or "").split())
+    if not text_summary:
+        raise Fail("结案要写一句「完成了什么」（--summary 不能为空）。")
+    new_category = normalize_label(category, field="分类") if category else None
+    new_tags = parse_tags(tags) if tags else None
+
+    logs = WorklogStore(repo)
+    history = HistoryStore(repo)
+    hist_path = repo / to_repo_rel(history_path_for(finished))
+
+    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    task = mine.get(tid)  # 锁内重读
+    if task is None:
+        # 分片里已经没有这条：上次崩在「删分片」之后。只按过程文档名判重，命中即已结案
+        state = history.has_log(
+            hist_path, log_name=worklog_name(tid), created=None, title=None
+        )
+        if state == HIT:
+            return Result(
+                already_done=True,
+                where=rel(repo, hist_path),
+                notices=(f"任务 {tid} 已经结过案，无需重复。",),
+            )
+        raise Fail(f"任务 {tid} 不在我的分片里（只能结案自己的任务）。")
+
+    # 历史行那两列取**最终值**：给了参数用新值，没给用任务原值，两处必须一致
+    final_category = new_category if new_category else task.get("category")
+    final_tags = tuple(new_tags) if new_tags else tuple(task.get("tags") or ())
+
+    doc_path = logs.find(tid, task.get("worklog"))
+
+    # 写前核对：指纹任一变了就中止，同时留三份字节备用
+    paths = [p for p in (mine.path, hist_path, doc_path) if p is not None]
+    stamps = {p: fingerprint(p) for p in paths}
+    backups = {p: snapshot(p) for p in paths}
+
+    try:
+        log_name = Path(doc_path).name if doc_path else None
+        state = history.has_log(
+            hist_path,
+            log_name=log_name,
+            created=task.get("created"),
+            title=task.get("title"),
+        )
+        if state == HIT:
+            # 崩在②（历史行已写）之后、③/④之前：历史里已有，但分片行可能还在、
+            # 过程文档可能还没封卷。不补齐就留下「已结案却仍在办」的僵尸 ——
+            # 它还能收 log，甚至被释放推回公共池让别人认领（2026-10-24 修）。
+            notes = [f"任务 {tid} 已经结过案，无需重复。"]
+            if doc_path is not None:
+                text = logs.read(doc_path)
+                if not has_frozen_line(text):
+                    frozen = stamp_frozen(text, finished, me.email)
+                    frozen = append_exec_log(
+                        frozen, exec_line(finished, me.email, "close", "结案封卷")
+                    )
+                    logs.write(doc_path, frozen)
+                    notes.append("补齐上次未完成的封卷。")
+            if mine.get(tid) is not None:
+                mine.drop(tid)
+                notes.append("补齐上次未完成的移出分片。")
+            return Result(
+                already_done=True,
+                where=rel(repo, hist_path),
+                notices=tuple(notes),
+            )
+        if state == UNDECIDABLE:
+            raise Fail(
+                f"历史里有一条没有过程文档链接的旧行，判不出是不是 {tid} ⇒ 已中止，"
+                f"请人工看一眼 {rel(repo, hist_path)} 再重跑。"
+            )
+        # 写前核对（2026-10-23 补）：三个文件的指纹与读到时不一致 ⇒ 有人在锁外动过，
+        # 一个字节都不写（snapshot 那份留着给下面的异常分支按字节退回）。
+        for path in paths:
+            if fingerprint(path) != stamps[path]:
+                raise Fail(
+                    f"{rel(repo, path)} 在本命令执行期间被改动过"
+                    "（可能是编辑器或 git 操作），已中止、未写入任何内容；重跑一次即可。"
+                )
+
+        # ① 改标签行（给了 --category / --tags 才做，且必须在封卷之前）
+        if doc_path is not None and (new_category or new_tags):
+            text = logs.read(doc_path)
+            logs.write(doc_path, rewrite_label_line(text, final_category, final_tags))
+
+        # ② 历史加一行（先 ensure_dir：首次结案时 history/ 可能还不存在）
+        ensure_dir(hist_path.parent)
+        out = history.append_row(
+            hist_path,
+            {
+                "finished": finished,
+                "created": task.get("created"),
+                "title": task.get("title") or "",
+                "category": final_category,
+                "tags": final_tags,
+                "owner": me.email,
+                "creator": task.get("creator") or me.email,
+                "summary": text_summary,
+                "worklog": task.get("worklog") if doc_path else None,
+            },
+        )
+        history.write(hist_path, out["text"])
+
+        # ③ 封卷（没有过程文档就跳过）
+        if doc_path is not None:
+            text = logs.read(doc_path)
+            if not has_frozen_line(text):
+                frozen = stamp_frozen(text, finished, me.email)
+                frozen = append_exec_log(
+                    frozen, exec_line(finished, me.email, "close", "结案封卷")
+                )
+                logs.write(doc_path, frozen)
+
+        # ④ 删我分片那行（永远最后）
+        mine.drop(tid)
+    except Exception:
+        for path in paths:
+            if path in backups:
+                restore(path, backups[path])
+        raise
+
+    notices: list[str] = []
+    if out.get("fallback_cols"):
+        notices.append(_COLS_FALLBACK_HINT)
+    if doc_path is None:
+        notices.append(f"提示：任务 {tid} 没有过程文档，已跳过封卷，历史末列留空。")
+    return Result(
+        changed=("status", "finished"),
+        where=rel(repo, hist_path),
+        message=f"结案 {tid}：{task.get('title') or ''}".strip(),
+        payload={
+            "history_path": rel(repo, hist_path),
+            "worklog_path": rel(repo, doc_path) if doc_path else None,
+            "fallback_cols": out.get("fallback_cols"),
+        },
+        notices=tuple(notices),
+    )

package/scripts/ledgerkit/actions/guard.py

@@ -0,0 +1,140 @@
+"""业务校验的共用件：任务号形态、任务存不存在、「这条是不是你的」。
+
+**`owner` / `status` 的读取只走这里的四个谓词**：`store/` 里不许出现 `get("owner")`，
+`actions/` 里除本文件外也不许裸写字段名比较。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from ..core.identity import Identity, is_me, normalize
+from ..core.labels import LEGACY_STATUSES
+from ..core.paths import POOL_REL
+from ..errors import Fail
+from ..store.owners_index import OwnersIndex
+from ..store.task_store import TaskStore
+from .query import ListQuery
+
+
+def current_identity(repo: Path) -> Identity:
+    """env 的本机身份 + `owners.json` 里这个身份的 `aliases`（不写盘、不登记）。"""
+    from .. import env
+    from ..core.identity import with_aliases
+
+    me = env.current(repo)
+    record = OwnersIndex(repo).get(me.email) or {}
+    aliases = tuple(record.get("aliases") or ())
+    return with_aliases(me, aliases) if aliases else me
+
+
+def require_task(tasks: Mapping[str, Any], tid: str, *, where: Path) -> dict[str, Any]:
+    """取一条任务；缺失时给可读原因（带所在文件）。"""
+    task = tasks.get(tid)
+    if task is None:
+        raise Fail(f"任务 {tid} 不在 {_show(where)} 里。")
+    if not isinstance(task, dict):
+        raise Fail(f"任务 {tid} 在 {_show(where)} 里不是一条对象，台账可能坏了。")
+    return dict(task)
+
+
+def require_owner(task: Mapping[str, Any], tid: str, me: Identity) -> None:
+    """只有当前 owner 能改。"""
+    owner = owner_of(task)
+    if not owner:
+        raise Fail(f"任务 {tid} 还没有人认领（在公共池里），先 claim 再改。")
+    if not is_me(me, owner):
+        raise Fail(f"任务 {tid} 的负责人是 {owner}，不是你（{me.label()}）。")
+
+
+def same_task_ignoring_stamp(a: Mapping[str, Any], b: Mapping[str, Any]) -> bool:
+    """两份内容是不是只差 `updated`（交接重跑时以对方那份为准的判据）。"""
+    left = {k: v for k, v in a.items() if k not in ("updated", "updated_by")}
+    right = {k: v for k, v in b.items() if k not in ("updated", "updated_by")}
+    return left == right
+
+
+def owner_of(task: Mapping[str, Any]) -> str | None:
+    """读 `owner` 的唯一入口。"""
+    value = task.get("owner")
+    return normalize(value) if isinstance(value, str) and value.strip() else None
+
+
+def status_of(task: Mapping[str, Any]) -> str:
+    """读 `status` 的唯一入口；老数据 `blocked` 当进行中。"""
+    value = task.get("status")
+    if not isinstance(value, str) or not value.strip():
+        return "open"
+    value = value.strip().lower()
+    return "doing" if value in LEGACY_STATUSES else value
+
+
+def is_mine(task: Mapping[str, Any], me: Identity) -> bool:
+    """这条任务是不是我的（含 aliases）。"""
+    return is_me(me, owner_of(task) or "")
+
+
+def in_scope(task: Mapping[str, Any], q: ListQuery, *, me: Identity) -> bool:
+    """`list` 的过滤谓词：范围、状态、分类、标签、创建时间闭区间。"""
+    if q.scope == "mine" and not is_mine(task, me):
+        return False
+    if q.scope == "pool" and owner_of(task):
+        return False
+    if q.scope == "owner" and q.owner and normalize(q.owner) != owner_of(task):
+        return False
+    if q.statuses:
+        status = status_of(task)
+        wanted = {s for s in q.statuses}
+        if status not in wanted and not (
+            "doing" in wanted and status in LEGACY_STATUSES
+        ):
+            return False
+    if q.category and (task.get("category") or "") != q.category:
+        return False
+    if q.tag and q.tag not in (task.get("tags") or ()):
+        return False
+    created = task.get("created")
+    if q.since and isinstance(created, str) and created[:19] < q.since[:19]:
+        return False
+    return not (q.until and isinstance(created, str) and created[:19] > q.until[:19])
+
+
+def _show(path: Path) -> str:
+    try:
+        return str(Path(path).name)
+    except Exception:  # noqa: BLE001
+        return str(path)
+
+
+def load_task(repo: Path, tid: str) -> tuple[dict[str, Any], list[Path]]:
+    """在池 + 索引登记的全部分片里找这条任务（只读），返回 (任务, 出现过的文件)。"""
+    index = OwnersIndex(repo)
+    index.assert_present()
+    found: dict[str, Any] | None = None
+    where: list[Path] = []
+    pool = TaskStore(repo, POOL_REL)
+    if pool.get(tid):
+        found = pool.get(tid)
+        where.append(pool.path)
+    for rel in _shard_rels(repo, index):
+        store = TaskStore(repo, rel)
+        task = store.get(tid)
+        if task:
+            where.append(store.path)
+            if found is None:
+                found = task
+    if found is None:
+        raise Fail(f"找不到任务 {tid}（池与已登记的分片里都没有）。")
+    return found, where
+
+
+def _shard_rels(repo: Path, index: OwnersIndex) -> list[Path]:
+    out: list[Path] = []
+    for path in index.shards().values():
+        try:
+            out.append(path.relative_to(repo / "ledger"))
+        except ValueError:  # pragma: no cover
+            continue
+    return out

package/scripts/ledgerkit/actions/handoff.py

@@ -0,0 +1,74 @@
+"""交接：先写进对方分片，再删我分片那行，再记一笔。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity, normalize
+from ..core.paths import shard_rel
+from ..core.time import now
+from ..core.worklog_md import exec_line
+from ..errors import Fail
+from ..store.owners_index import OwnersIndex
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .guard import same_task_ignoring_stamp
+from .result import Result, rel
+
+
+def handoff(repo: Path, me: Identity, tid: str, *, to: str) -> Result:
+    """写序：对方分片 → 删我分片那行 → 过程文档记一笔。"""
+    index = OwnersIndex(repo)
+    record = index.get(to)
+    if record is None:
+        raise Fail(
+            f"{to} 还没在索引里登记过 ⇒ 不能交接给他（写出一份对别人不存在的分片，他自己也看不到）。"
+        )
+    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    task = mine.get(tid)  # 锁内重读
+    if task is None:
+        raise Fail(f"任务 {tid} 不在我的分片里，交接不了。")
+
+    to_key = normalize(to)
+    to_store = TaskStore(repo, shard_rel(to_key))
+    moved = dict(task)
+    moved["owner"] = to_key
+    moved["updated"] = now()
+
+    existing = to_store.get(tid)
+    if existing is not None:
+        if not same_task_ignoring_stamp(existing, moved):
+            raise Fail(
+                f"任务 {tid} 在 {to_key} 的分片里已经存在，且内容与本次不一致 ⇒ 拒绝交接。"
+            )
+        # 重跑：以对方那份为准，只补删我这边
+        mine.drop(tid)
+        logs = WorklogStore(repo)
+        path = logs.find(tid, moved.get("worklog"))
+        if path is not None:
+            logs.append_exec(
+                path, exec_line(now(), me.email, "set", f"交接给 {to_key}（补齐）")
+            )
+        return Result(
+            already_done=True,
+            where=rel(repo, to_store.path),
+            message=f"交接 {tid} → {to_key}：补齐上次未完成的清理",
+            notices=(f"任务 {tid} 已在对方分片里（内容一致），本次只补删我分片那行。",),
+        )
+
+    to_store.put(tid, moved)
+    mine.drop(tid)
+
+    logs = WorklogStore(repo)
+    path = logs.find(tid, moved.get("worklog"))
+    note = None
+    if path is None:
+        note = f"任务 {tid} 已交给 {to_key}，但过程文档没找到，跳过执行记录。"
+    else:
+        logs.append_exec(path, exec_line(now(), me.email, "set", f"交接给 {to_key}"))
+    return Result(
+        changed=("owner", "updated"),
+        where=rel(repo, to_store.path),
+        message=f"交接 {tid} → {to_key}",
+        notices=(note,) if note else (),
+    )

package/scripts/ledgerkit/actions/list_tasks.py

@@ -0,0 +1,53 @@
+"""只读：查在办任务（池 + 分片，后读到的为准）。不拿锁、不跑自举、不做取最新。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..core.identity import Identity
+from ..core.paths import POOL_REL
+from ..store.owners_index import OwnersIndex
+from ..store.task_store import TaskStore
+from .guard import in_scope, owner_of, status_of
+from .query import ListQuery
+from .result import ListResult, TaskRow, rel
+
+
+def list_tasks(repo: Path, me: Identity, q: ListQuery) -> ListResult:
+    """合并顺序定死：先池、再按索引键排序的各分片，同一任务号由分片那份胜出。"""
+    rows: dict[str, dict[str, Any]] = {}
+    where: dict[str, Path] = {}
+
+    pool = TaskStore(repo, POOL_REL)
+    for tid, task in pool.all().items():
+        rows[tid] = task
+        where[tid] = pool.path
+
+    index = OwnersIndex(repo)
+    index.assert_present()
+    for key in sorted(index.shards()):
+        path = index.shards()[key]
+        store = TaskStore(repo, Path(path).relative_to(repo / "ledger"))
+        for tid, task in store.all().items():
+            rows[tid] = task
+            where[tid] = store.path
+
+    kept = {tid: t for tid, t in rows.items() if in_scope(t, q, me=me)}
+    table = tuple(
+        TaskRow(
+            tid=tid,
+            title=str(task.get("title") or ""),
+            status=status_of(task),
+            owner=owner_of(task),
+            created=task.get("created"),
+            started=task.get("started"),
+            category=task.get("category"),
+            tags=tuple(task.get("tags") or ()),
+            where=rel(repo, where[tid]),
+        )
+        for tid, task in sorted(
+            kept.items(), key=lambda kv: str(kv[1].get("created") or "")
+        )
+    )
+    return ListResult(rows=kept, table=table)

package/scripts/ledgerkit/actions/log_progress.py

@@ -0,0 +1,60 @@
+"""记进展：刷分片的「最后更新」，再往过程文档追加一行。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity
+from ..core.paths import shard_rel
+from ..core.time import now
+from ..core.worklog_md import exec_line
+from ..errors import Fail
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .result import Result, rel
+
+
+def log_progress(repo: Path, me: Identity, tid: str, note: str) -> Result:
+    """写序：刷 `updated` → 过程文档追加一行。
+
+    文档写不进（`append_exec` 回 False）⇒ **不算失败**：分片已经刷了就照常提交，
+    只留一条警告 —— 抛错让外壳回滚会变成「改了又不提交」，下一条命令被写前 guard 拦死。
+    """
+    text = " ".join((note or "").split())
+    if not text:
+        raise Fail("--note 不能为空。")
+    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    task = mine.get(tid)  # 锁内重读
+    if task is None:
+        raise Fail(f"任务 {tid} 不在我的分片里（只能给自己的任务记进展）。")
+
+    updated = dict(task)
+    updated["updated"] = now()
+    mine.put(tid, updated)
+
+    logs = WorklogStore(repo)
+    path = logs.find(tid, updated.get("worklog"))
+    if path is None:
+        return Result(
+            changed=("updated",),
+            where=rel(repo, mine.path),
+            message=f"{tid}：记进展",
+            notices=(
+                "提示：这条任务没有过程文档，已跳过执行记录（分片的最后更新已刷）。",
+            ),
+        )
+    ok = logs.append_exec(path, exec_line(now(), me.email, "log", text))
+    if not ok:
+        return Result(
+            changed=("updated",),
+            where=rel(repo, mine.path),
+            message=f"{tid}：记进展",
+            notices=(
+                "警告：分片的最后更新已刷，过程文档补不上（文件不可写）；已写的分片照常提交，文档那行要手动补。",
+            ),
+        )
+    return Result(
+        changed=("updated",),
+        where=rel(repo, mine.path),
+        message=f"{tid}：记进展",
+    )

package/scripts/ledgerkit/actions/new_task.py

@@ -0,0 +1,120 @@
+"""建任务：拿外壳算好的任务号写过程文档、写进池（或直接写进自己的分片）。
+
+`tid` / `created` 由外壳算好传进来（锁层要靠它们算出那篇文档的路径），
+业务层不许现算现用；缺了就是外壳的 bug，直接 Fail。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity
+from ..core.ids import require_task_id
+from ..core.labels import normalize_label, parse_tags
+from ..core.paths import (
+    POOL_REL,
+    shard_rel,
+    to_repo_rel,
+    worklog_rel,
+)
+from ..core.worklog_md import exec_line
+from ..errors import Fail
+from ..store.atomic import ensure_dir, restore, snapshot
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .result import Result, WorklogView, rel
+
+FIELDS = ("created", "title", "status", "owner", "creator", "worklog")
+
+
+def new_task(
+    repo: Path,
+    me: Identity,
+    *,
+    title: str,
+    tid: str,
+    created: str,
+    category: str | None = None,
+    tags: tuple[str, ...] = (),
+    mine: bool = False,
+) -> Result:
+    """写序：`ensure_dir(当月文档目录)` → 过程文档（含首条记录）→ 台账。"""
+    if not (title or "").strip():
+        raise Fail("标题不能为空。")
+    if not tid:
+        raise Fail("建任务必须由外壳先算好任务号（内部错误：tid 为空）。")
+    if not created:
+        raise Fail("建任务必须由外壳先算好创建时间（内部错误：created 为空）。")
+    tid = require_task_id(tid)
+    clean_title = " ".join(title.strip().split())
+    category = normalize_label(category, field="分类") if category else None
+    tag_list = parse_tags(tags)
+
+    mine_store = TaskStore(repo, shard_rel(me.email), identity=me)
+    pool = TaskStore(repo, POOL_REL)
+    target = mine_store if mine else pool
+
+    # 查重：池 + 我自己的分片，**并且在锁内重读**（锁外的快照只配决定锁多宽）
+    if target.get(tid) is not None:
+        raise Fail(f"任务号 {tid} 已经存在了（这不是重跑，是重号）。")
+    other = pool if mine else mine_store
+    if other.get(tid) is not None:
+        raise Fail(f"任务号 {tid} 已经存在了（这不是重跑，是重号）。")
+    # 已结案的号也不能复用，且跨月同号互不干扰：直接看过程文档路径在不在。
+    # 在办任务的文档在磁盘上、已结案任务的文档也留在磁盘上 ⇒ 文档存在即这个号被占过
+    # （撞的是同一篇 worklog 文件，会覆盖 / 日后让 close 误判 already_done 变僵尸）。
+    # O(1)，不必扫历史文件。上面分片 / 池是并发安全闸门，这里补文件级的精确判重。
+    if (repo / to_repo_rel(worklog_rel(tid, created))).exists():
+        raise Fail(
+            f"任务号 {tid} 的过程文档已经存在（同名号的在办 / 已结案任务占着同一篇文档）"
+            "⇒ 换一个 --id，别复用历史号。"
+        )
+
+    doc_rel = worklog_rel(tid, created)  # 别叫 rel：那是 result.rel 的函数名
+    path = repo / to_repo_rel(doc_rel)
+    logs = WorklogStore(repo)
+    before_doc = snapshot(path)
+
+    task = {
+        "title": clean_title,
+        "created": created,
+        # --self = 建并认领：直接归自己名下就必须是在做，不留 open 半成品
+        "status": "doing" if mine else "open",
+        "owner": me.email if mine else None,
+        "creator": me.email,
+        "category": category,
+        "tags": list(tag_list),
+        "worklog": doc_rel,
+        "started": created if mine else None,
+        "updated": created,
+        "finished": None,
+    }
+    try:
+        ensure_dir(path.parent)
+        _ = logs.create(
+            tid=tid,
+            title=clean_title,
+            created=created,
+            creator=me.email,
+            category=category,
+            tags=tag_list,
+            first_exec=exec_line(
+                created, me.email, "new", "创建任务并认领" if mine else "创建任务"
+            ),
+        )
+        target.put(tid, task)
+    except Exception:
+        # 同一个 atom 内收尾：台账那条 drop 掉，文档原本不存在 ⇒ restore(None) 删掉
+        target.drop(tid)
+        restore(path, before_doc)
+        raise
+
+    text = logs.read(path)
+    return Result(
+        changed=FIELDS,
+        where=rel(repo, target.path),
+        message=f"新建任务 {tid}：{clean_title}",
+        worklog=WorklogView(path=rel(repo, path), text=text, error=None),
+        payload={"tid": tid},
+        notices=(f"新建过程文档：{rel(repo, path)}",),
+    )

package/scripts/ledgerkit/actions/query.py

@@ -0,0 +1,33 @@
+"""查询条件长什么样。外壳把命令行装成它，界面直接构造它 —— **动作层不认识 argparse**。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ListQuery:
+    scope: str = "all"  # "all" / "pool" / "mine" / "owner"
+    owner: str | None = None  # scope="owner" 时生效
+    statuses: tuple[str, ...] = ()
+    category: str | None = None
+    tag: str | None = None
+    since: str | None = None  # UTC 串，闭区间
+    until: str | None = None  # 同上
+    # `since` / `until` **一律比 `created`**（含边界，只给其一也行），不比 started / updated。
+
+
+@dataclass(frozen=True)
+class HistoryQuery:
+    owner: str | None = None
+    mine: bool = False
+    category: str | None = None
+    tag: str | None = None
+    since: str | None = None  # UTC 串，闭区间；比 finished（结案时间），不比 created
+    until: str | None = None  # 同上
+    limit: int | None = None
+    months: int | None = None  # 最近 N 个自然月；与 since/until 互斥
+    count_only: bool = False  # 只要计数，不要 records
+
+
+COUNT_CAP = 10_000  # --count-only 的封顶：超过就 capped=True