task-ledger 1.3.4 → 1.3.6

package/scripts/ledgerkit/actions/init_identity.py

@@ -0,0 +1,90 @@
+"""init：初始化本机身份（写 `~/.taskledger/identity.json`，一台机器只一次）。
+
+只做逻辑，不打印、不读 stdin；交互/机器读在 shell 层。
+- `claim`：认领名册里已有的 uuid（连 name 一起复制，不输入）。
+- `new`  ：新建 uuid（必须给 name）。
+- 都不给且名册有人：返回候选列表，交给调用方去问用户。
+"""
+
+from __future__ import annotations
+
+import json
+import uuid as uuidlib
+from pathlib import Path
+from typing import Any
+
+from .. import env
+from ..core.identity import Identity, looks_like_uuid, normalize
+from ..core.paths import OWNERS_REL, to_repo_rel
+from ..errors import Fail
+
+
+def _read_workers(repo: Path | None) -> dict[str, Any]:
+    if repo is None:
+        return {}
+    try:
+        raw = (repo / to_repo_rel(OWNERS_REL)).read_text(encoding="utf-8")
+        data = json.loads(raw)
+    except (OSError, ValueError):
+        return {}
+    return (data or {}).get("workers", {}) or {}
+
+
+def init_identity(
+    repo: Path | None, *, claim: str | None, new: bool, name: str
+) -> dict[str, Any]:
+    path = env.identity_file()
+    existing = env.read_identity()
+    if existing is not None:
+        # 已初始化 = 幂等空转（与 release/claim/close 的重跑口径一致）：退 0、零写。
+        # 只有「认领另一个 uuid」才是真冲突——换身份不归 init 管。
+        if claim is None or normalize(claim) == existing.uuid:
+            return {
+                "already": True,
+                "uuid": existing.uuid,
+                "name": existing.name,
+                "path": str(path),
+            }
+        raise Fail(
+            f"这台机器已经是 {existing.uuid}（{path}），不能再认领 {claim.strip()}。\n"
+            "  处理：要换身份请手动改该文件的 uuid；一台机器一个身份。"
+        )
+
+    workers = _read_workers(repo)
+    if claim:
+        key = normalize(claim)  # 名册键一律小写；--claim 抄来的大小写不影响
+        # 认领目标必须是 uuid：老台账的键还可能是个邮箱 / 名字，认来会让整台机器
+        # 拿非 uuid 当身份写进每一处（--owner 反倒拒收自己）
+        if not looks_like_uuid(key):
+            raise Fail(
+                f"认领目标不是 uuid：{claim.strip()}\n"
+                "  处理：老台账（身份键是邮箱 / 名字）请改走 `init --new --name=<名字>`；"
+                "先把那本台账迁到 uuid 身份，再谈认领。"
+            )
+        record = workers.get(key)
+        if record is None:
+            raise Fail(
+                f"名册里没有 uuid={claim}。\n"
+                "  处理：不带参数跑一次 init 看可选用户，再 --claim 选一个。"
+            )
+        identity = Identity(uuid=key, name=str(record.get("name") or ""))
+    elif workers and not new:
+        return {
+            "need_choose": True,
+            "path": str(path),
+            "options": [
+                {"uuid": key, "name": str((rec or {}).get("name") or "")}
+                for key, rec in workers.items()
+            ],
+        }
+    else:
+        if not name.strip():
+            raise Fail("新建身份必须输入一个名字（--name=<名字>）。")
+        identity = Identity(uuid=str(uuidlib.uuid4()), name=name.strip())
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"uuid": identity.uuid, "name": identity.name}
+    path.write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    return {"uuid": identity.uuid, "name": identity.name, "path": str(path)}

package/scripts/ledgerkit/actions/list_tasks.py

@@ -2,20 +2,35 @@
 
 from __future__ import annotations
 
+from dataclasses import replace
 from pathlib import Path
 from typing import Any
 
 from ..core.identity import Identity
+from ..core.labels import STATUSES
 from ..core.paths import POOL_REL
+from ..errors import Fail
 from ..store.owners_index import OwnersIndex
 from ..store.task_store import TaskStore
-from .guard import in_scope, owner_of, status_of
+from .guard import in_scope, owner_of, require_uuid, status_of
 from .query import ListQuery
 from .result import ListResult, TaskRow, rel
 
 
 def list_tasks(repo: Path, me: Identity, q: ListQuery) -> ListResult:
     """合并顺序定死：先池、再按索引键排序的各分片，同一任务号由分片那份胜出。"""
+    # `--owner` 只认 uuid，且**给了就必须生效**：和 --mine / --pool 同传直接报错，
+    # 不许出现「传了 uuid 却被范围参数静默吃掉」（--owner "" 也算给了，同样报错）。
+    if q.owner is not None:
+        if q.scope in ("mine", "pool"):
+            raise Fail("--owner 不能和 --mine / --pool 一起用：一次只按一种范围筛。")
+        q = replace(q, owner=require_uuid(q.owner, field="--owner"))
+    # `--status` 只认白名单：`--status blocked` 这种早该消失的值不许静默返回空表
+    unknown = [s for s in q.statuses if s not in STATUSES]
+    if unknown:
+        raise Fail(
+            f"--status 只认 {' / '.join(STATUSES)}（收到 {', '.join(unknown)}）。"
+        )
     rows: dict[str, dict[str, Any]] = {}
     where: dict[str, Path] = {}
 
@@ -33,13 +48,16 @@ def list_tasks(repo: Path, me: Identity, q: ListQuery) -> ListResult:
             rows[tid] = task
             where[tid] = store.path
 
-    kept = {tid: t for tid, t in rows.items() if in_scope(t, q, me=me)}
+    name_keys = index.keys_of_name(q.owner_name) if q.owner_name else set()
+    kept = {
+        tid: t for tid, t in rows.items() if in_scope(t, q, me=me, name_keys=name_keys)
+    }
     table = tuple(
         TaskRow(
             tid=tid,
             title=str(task.get("title") or ""),
             status=status_of(task),
-            owner=owner_of(task),
+            owner=task.get("owner_name") or owner_of(task),
             created=task.get("created"),
             started=task.get("started"),
             category=task.get("category"),

package/scripts/ledgerkit/actions/log_progress.py

@@ -11,6 +11,7 @@ from ..core.worklog_md import exec_line
 from ..errors import Fail
 from ..store.task_store import TaskStore
 from ..store.worklog_store import WorklogStore
+from .guard import require_owner
 from .result import Result, rel
 
 
@@ -23,10 +24,12 @@ def log_progress(repo: Path, me: Identity, tid: str, note: str) -> Result:
     text = " ".join((note or "").split())
     if not text:
         raise Fail("--note 不能为空。")
-    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    mine = TaskStore(repo, shard_rel(me.uuid), identity=me)
     task = mine.get(tid)  # 锁内重读
     if task is None:
         raise Fail(f"任务 {tid} 不在我的分片里（只能给自己的任务记进展）。")
+    # 分片里有、行内 owner 却不是我 ⇒ 台账脏了（validate ⑤），先拦下来
+    require_owner(task, tid, me)
 
     updated = dict(task)
     updated["updated"] = now()
@@ -43,7 +46,7 @@ def log_progress(repo: Path, me: Identity, tid: str, note: str) -> Result:
                 "提示：这条任务没有过程文档，已跳过执行记录（分片的最后更新已刷）。",
             ),
         )
-    ok = logs.append_exec(path, exec_line(now(), me.email, "log", text))
+    ok = logs.append_exec(path, exec_line(now(), me.stamp(), "log", text))
     if not ok:
         return Result(
             changed=("updated",),

package/scripts/ledgerkit/actions/new_task.py

@@ -50,7 +50,7 @@ def new_task(
     category = normalize_label(category, field="分类") if category else None
     tag_list = parse_tags(tags)
 
-    mine_store = TaskStore(repo, shard_rel(me.email), identity=me)
+    mine_store = TaskStore(repo, shard_rel(me.uuid), identity=me)
     pool = TaskStore(repo, POOL_REL)
     target = mine_store if mine else pool
 
@@ -66,8 +66,10 @@ def new_task(
     # O(1)，不必扫历史文件。上面分片 / 池是并发安全闸门，这里补文件级的精确判重。
     if (repo / to_repo_rel(worklog_rel(tid, created))).exists():
         raise Fail(
-            f"任务号 {tid} 的过程文档已经存在（同名号的在办 / 已结案任务占着同一篇文档）"
-            "⇒ 换一个 --id，别复用历史号。"
+            f"任务号 {tid} 的过程文档已经存在（同名号的在办 / 已结案任务占着同一篇文档）。\n"
+            "  处理：换一个 --id，别复用历史号。\n"
+            "  若上次 new 崩在中间（文档已写、台账没落），这篇就是它留下的：确认内容要保留就换号重建；"
+            "非要复用这一号，先把那篇文档挪走再重跑。"
         )
 
     doc_rel = worklog_rel(tid, created)  # 别叫 rel：那是 result.rel 的函数名
@@ -80,8 +82,10 @@ def new_task(
         "created": created,
         # --self = 建并认领：直接归自己名下就必须是在做，不留 open 半成品
         "status": "doing" if mine else "open",
-        "owner": me.email if mine else None,
-        "creator": me.email,
+        "owner": me.uuid if mine else None,
+        "owner_name": me.name if mine else None,
+        "creator": me.uuid,
+        "creator_name": me.name,
         "category": category,
         "tags": list(tag_list),
         "worklog": doc_rel,
@@ -95,11 +99,11 @@ def new_task(
             tid=tid,
             title=clean_title,
             created=created,
-            creator=me.email,
+            creator=me.stamp(),
             category=category,
             tags=tag_list,
             first_exec=exec_line(
-                created, me.email, "new", "创建任务并认领" if mine else "创建任务"
+                created, me.stamp(), "new", "创建任务并认领" if mine else "创建任务"
             ),
         )
         target.put(tid, task)

package/scripts/ledgerkit/actions/query.py

@@ -8,7 +8,8 @@ from dataclasses import dataclass
 @dataclass(frozen=True)
 class ListQuery:
     scope: str = "all"  # "all" / "pool" / "mine" / "owner"
-    owner: str | None = None  # scope="owner" 时生效
+    owner: str | None = None  # scope="owner" 时生效；**只收 uuid**
+    owner_name: str | None = None  # 显示名模糊筛（子串、不分大小写）；只筛不判定
     statuses: tuple[str, ...] = ()
     category: str | None = None
     tag: str | None = None
@@ -19,7 +20,8 @@ class ListQuery:
 
 @dataclass(frozen=True)
 class HistoryQuery:
-    owner: str | None = None
+    owner: str | None = None  # **只收 uuid**
+    owner_name: str | None = None  # 显示名模糊筛（子串、不分大小写）
     mine: bool = False
     category: str | None = None
     tag: str | None = None

package/scripts/ledgerkit/actions/query_history.py

@@ -6,16 +6,19 @@
 
 from __future__ import annotations
 
+from dataclasses import replace
 from datetime import datetime, timedelta
 from pathlib import Path
 from typing import Any
 
 from ..core import history_md
 from ..core.identity import Identity, normalize
-from ..core.paths import HISTORY_DIR, LEGACY_HISTORY_REL, month_of, to_repo_rel
+from ..core.paths import HISTORY_DIR, month_of, to_repo_rel
 from ..core.time import now, time_key
 from ..errors import Fail
 from ..store.history_store import HistoryStore
+from ..store.owners_index import OwnersIndex
+from .guard import require_uuid
 from .query import COUNT_CAP, HistoryQuery
 from .result import HistoryResult, rel
 
@@ -102,14 +105,19 @@ def _target_month_keys(q: HistoryQuery) -> list[str]:
 
 
 def _candidate_paths(repo: Path, keys: list[str]) -> list[Path]:
-    """按月键【直接拼】`history/<年月>.md`（不扫磁盘）；存量平铺文件按固定路径顺带一看。"""
-    paths = [repo / to_repo_rel(HISTORY_DIR / f"{ym}.md") for ym in keys]
-    paths.append(repo / to_repo_rel(LEGACY_HISTORY_REL))
-    return paths
+    """按月键【直接拼】`history/<年月>.md`（不扫磁盘）。"""
+    return [repo / to_repo_rel(HISTORY_DIR / f"{ym}.md") for ym in keys]
 
 
 def query_history(repo: Path, me: Identity, q: HistoryQuery) -> HistoryResult:
-    """`--owner` / `--mine` 一律**精确相等**（不做前缀 / 子串）；`--since` / `--until` 比 `finished`（结案时间）。"""
+    """`--owner` / `--mine` 一律按 **uuid 精确相等**；名字只能走 `--owner-name` 模糊筛。
+
+    `--since` / `--until` 比 `finished`（结案时间）。
+    """
+    if q.owner is not None:
+        if q.mine:
+            raise Fail("--owner 不能和 --mine 一起用：一次只按一种范围筛。")
+        q = replace(q, owner=require_uuid(q.owner, field="--owner"))
     keys = _target_month_keys(q)
     store = HistoryStore(repo)
     records: list[dict[str, Any]] = []
@@ -126,12 +134,36 @@ def query_history(repo: Path, me: Identity, q: HistoryQuery) -> HistoryResult:
             row["finished"] = time_key(row.get("finished") or "") or row.get("finished")
             records.append(row)
 
+    index = OwnersIndex(repo)
+    roster = index.all()
     if q.mine:
-        wanted = {normalize(me.email)}
+        wanted = {normalize(me.uuid)}
         records = [r for r in records if normalize(r.get("owner") or "") in wanted]
     elif q.owner:
         key = normalize(q.owner)
         records = [r for r in records if normalize(r.get("owner") or "") == key]
+    if q.owner_name:
+        # 名字已经落在历史行里 ⇒ 直接比它（子串、不分大小写）。落的是**当时**那个名字，
+        # 改名后的旧行仍留旧名 ⇒ 按新名筛不到旧行，这是快照语义，不是漏。
+        # 老行（升级前落的）没有名字列，退回按 uuid 片段比，不至于一条都筛不出来。
+        needle = q.owner_name.strip().lower()
+        records = [
+            r
+            for r in records
+            if needle in str(r.get("owner_name") or "").lower()
+            or needle in normalize(r.get("owner") or "")
+        ]
+
+    # 名字**已经落盘**（`owner_name` / `creator_name` 两列）。这里只给没名字的**老行**
+    # 按名册兜底补一次 —— 补的是读时展示值，不回写文件。
+    for row in records:
+        for field, target in (("owner", "owner_name"), ("creator", "creator_name")):
+            if row.get(target):
+                continue
+            key = normalize(row.get(field) or "")
+            name = str((roster.get(key) or {}).get("name") or "")
+            if name:
+                row[target] = name
     if q.category:
         records = [r for r in records if (r.get("category") or "") == q.category]
     if q.tag:
@@ -142,19 +174,33 @@ def query_history(repo: Path, me: Identity, q: HistoryQuery) -> HistoryResult:
     lo_key, hi_key = min(keys), max(keys)
     eff_since = q.since or f"{lo_key[0:4]}-{lo_key[4:6]}-01 00:00:00"
     eff_until = q.until or _month_end(hi_key)
+    if eff_since > eff_until:
+        raise Fail(
+            f"时间区间反了：--since（{eff_since}）晚于 --until（{eff_until}）。\n"
+            "  处理：把两端换过来；只给一端就只给一端。"
+        )
     records = [r for r in records if (r.get("finished") or "") >= eff_since]
     records = [r for r in records if (r.get("finished") or "") <= eff_until]
 
     records.sort(key=lambda r: str(r.get("finished") or ""), reverse=True)
+    if q.count_only and q.limit is not None:
+        raise Fail("--count-only 与 --limit 不能同时用：计数不截断，列表才截断。")
+    limit: int | None = None
+    if q.limit is not None:
+        limit = int(q.limit)
+        if limit < 1:
+            raise Fail(f"--limit 必须 ≥ 1（收到 {limit}）。")
     capped = False
     if q.count_only and len(records) > COUNT_CAP:
         capped = True
         records = records[:COUNT_CAP]
-    elif q.limit:
-        records = records[: int(q.limit)]
+    elif limit is not None:
+        capped = len(records) > limit  # 截断了要让调用方知道「还有更多」
+        records = records[:limit]
 
     filters = {
         "owner": q.owner,
+        "owner_name": q.owner_name,
         "mine": q.mine,
         "category": q.category,
         "tag": q.tag,

package/scripts/ledgerkit/actions/registry.py

@@ -43,7 +43,7 @@ ACTIONS: dict[str, ActionSpec] = {
     "set": ActionSpec(
         set_task.set_task,
         "result",
-        params=("tid", "owner"),
+        params=("tid", "owner", "release"),
         lock_action="set",
     ),
     "log": ActionSpec(log_progress.log_progress, "result", params=("tid", "note")),

package/scripts/ledgerkit/actions/release.py

@@ -11,16 +11,25 @@ from ..core.worklog_md import exec_line
 from ..errors import Fail
 from ..store.task_store import TaskStore
 from ..store.worklog_store import WorklogStore
+from .guard import owner_of, require_owner, status_of
 from .result import Result, rel
 
 
 def release(repo: Path, me: Identity, tid: str) -> Result:
     """写序：写回池（已有同号就不覆盖）→ 删我分片那行 → 过程文档记一笔。"""
     pool = TaskStore(repo, POOL_REL)
-    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    mine = TaskStore(repo, shard_rel(me.uuid), identity=me)
     task = mine.get(tid)  # 锁内重读
     if task is None:
-        if pool.get(tid) is not None:
+        in_pool = pool.get(tid)
+        if in_pool is not None:
+            # 幂等分支也要验「池里那条真的已经是没人要的开放任务」，
+            # 否则池里混进带 owner 的脏行时，release 会报「无需重复释放」而任务实际仍被占
+            if owner_of(in_pool) or status_of(in_pool) != "open":
+                raise Fail(
+                    f"任务 {tid} 在公共池里，但身上还挂着 owner / 不是 open —— 台账脏了。\n"
+                    "  处理：跑 validate 看清单，别用 release 强行覆盖。"
+                )
             return Result(
                 already_done=True,
                 where=rel(repo, pool.path),
@@ -28,12 +37,24 @@ def release(repo: Path, me: Identity, tid: str) -> Result:
             )
         raise Fail(f"任务 {tid} 不在我的分片里，也没在公共池里。")
 
+    # 分片里在、但行内 owner 不是我 ⇒ 台账脏了（validate ⑤）：不许把别人的行推进池
+    require_owner(task, tid, me)
+
     back = dict(task)
     back["owner"] = None
+    back["owner_name"] = None  # 冗余显示名跟着 owner 一起清，否则池里那条仍显示原负责人
     back["status"] = "open"
     back["updated"] = now()
     if pool.get(tid) is None:
         pool.put(tid, back)
+    else:
+        # 池里已有同号：那份必须是干净的空位，否则不写回（它的 owner/owner_name 会被旧值带脏）
+        existing = pool.get(tid) or {}
+        if owner_of(existing) or status_of(existing) != "open":
+            raise Fail(
+                f"公共池里已经有一条 {tid}，且它带着 owner / 不是 open —— 台账脏了。\n"
+                "  处理：跑 validate 看清单，先确认哪条是真的。"
+            )
     mine.drop(tid)
 
     logs = WorklogStore(repo)
@@ -42,9 +63,9 @@ def release(repo: Path, me: Identity, tid: str) -> Result:
     if path is None:
         note = f"任务 {tid} 已退回公共池，但过程文档没找到，跳过执行记录。"
     else:
-        logs.append_exec(path, exec_line(now(), me.email, "release", "释放回公共池"))
+        logs.append_exec(path, exec_line(now(), me.stamp(), "release", "释放回公共池"))
     return Result(
-        changed=("owner", "status", "updated"),
+        changed=("owner", "owner_name", "status", "updated"),
         where=rel(repo, pool.path),
         message=f"释放 {tid}：{back.get('title') or ''}".strip(),
         notices=(note,) if note else (),

package/scripts/ledgerkit/actions/set_task.py

@@ -19,21 +19,32 @@ from ..store.task_store import TaskStore
 from . import claim as claim_mod
 from . import handoff as handoff_mod
 from . import release as release_mod
+from .guard import require_uuid
 from .result import Result, rel
 
 
-def set_task(repo: Path, me: Identity, tid: str, *, owner: str | None) -> Result:
-    """路由：空串 = 释放；别人 = 交接；自己 = 已认领则空转、没认领先认领。"""
+def set_task(
+    repo: Path,
+    me: Identity,
+    tid: str,
+    *,
+    owner: str | None = None,
+    release: bool = False,
+) -> Result:
+    """路由：`--release` = 释放；别人的 uuid = 交接；自己的 uuid = 已认领则空转、没认领先认领。"""
+    if release:
+        if owner is not None:
+            raise Fail("--release 与 --owner 不能同时给：释放不带人，交接不带释放。")
+        return release_mod.release(repo, me, tid)
     if owner is None:
         raise Fail(
-            "set 必须带 --owner：空串 = 释放回公共池；对方身份 = 交接（预留通道，agent 不用）。"
+            "set 必须二选一：`--release`（释放回公共池）或 `--owner <对方 uuid>`（交接）。"
         )
-    target = owner.strip()
-    if not target:
-        return release_mod.release(repo, me, tid)
+    # 交接目标只收 uuid：名字查不到就当场报错，绝不去猜「他大概是这个人」
+    target = require_uuid(owner, field="--owner")
     if not is_me(me, target):
         return handoff_mod.handoff(repo, me, tid, to=target)
-    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    mine = TaskStore(repo, shard_rel(me.uuid), identity=me)
     if mine.get(tid) is not None:
         return Result(
             already_done=True,

package/scripts/ledgerkit/actions/validate.py

@@ -16,7 +16,6 @@ from ..core.identity import Identity
 from ..core.labels import STATUSES
 from ..core.paths import (
     LEDGER_DIR,
-    LEGACY_HISTORY_REL,
     OWNERS_REL,
     POOL_REL,
     to_repo_rel,
@@ -200,9 +199,6 @@ def validate(repo: Path, me: Identity, deep: bool = False) -> ValidationReport:
     )
     checked += _check_worklog(repo, logs, problems, notices, deep=deep)
 
-    legacy = repo / to_repo_rel(LEGACY_HISTORY_REL)
-    if legacy.exists():
-        notices.append(f"存量平铺文件 {rel(repo, legacy)} 只读兼容，不会重写。")
     if not (repo / to_repo_rel(OWNERS_REL)).exists():
         notices.append("还没有 owners.json（索引）：跑一条写命令会自动建。")
     stray = repo / LEDGER_DIR / LEDGER_DIR