dsh-task-ledger 0.0.100 → 0.0.102

package/skill/scripts/ledgerkit/actions/relabel.py

@@ -1,105 +0,0 @@
-"""改分类 / 标签：分片那两个字段 + 过程文档头部那行，一次改动两处同步。
-
-只动「分类 / 标签」这一件事，不碰归属与状态 —— 归属走 `--owner` / `--release`，
-状态只随命令语义变。已结案的任务不在任何分片里，改不了（历史行是快照）。
-"""
-
-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 shard_rel
-from ..core.time import now
-from ..core.worklog_md import (
-    StatusLine,
-    append_exec_log,
-    exec_line,
-    rewrite_label_line,
-    rewrite_status_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
-
-
-def _describe(category: str | None, tags: list[str]) -> str:
-    """执行记录里那一句说明：`建设 · DSH、台账`。"""
-    parts = [category] if category else []
-    if tags:
-        parts.append("、".join(tags))
-    return " · ".join(parts)
-
-
-def relabel(
-    repo: Path,
-    me: Identity,
-    tid: str,
-    *,
-    category: str | None = None,
-    tags: str | tuple[str, ...] | None = None,
-) -> Result:
-    """写序：算最终值 → 过程文档（标签行 + 执行记录 + 状态行，一次写）→ 分片。
-
-    `tags` 收字符串（顿号 / 逗号分隔）或已切好的元组 —— 外壳可能已经切过一遍。
-    """
-    new_category = normalize_label(category, field="分类") if category else None
-    new_tags = parse_tags(tags) if tags else None
-    if new_category is None and new_tags is None:
-        raise Fail(
-            "改分类 / 标签至少要给一个：`--category <分类>` 或 `--tags <a、b>`。"
-        )
-
-    mine = TaskStore(repo, shard_rel(me.uuid), identity=me)
-    task = mine.get(tid)  # 锁内重读
-    if task is None:
-        raise Fail(
-            f"任务 {tid} 不在我的分片里（只能改自己名下在办的任务；已结案的任务改不了）。"
-        )
-    require_owner(task, tid, me)
-
-    # 没给的沿用原值：分类与标签是一行里的两段，写一次就得给全
-    final_category = new_category if new_category else task.get("category")
-    final_tags: list[str] = (
-        [str(tag) for tag in new_tags]
-        if new_tags is not None
-        else [str(tag) for tag in (task.get("tags") or ())]
-    )
-    if not final_category and not final_tags:
-        raise Fail("分类与标签都是空的，没有可写的值。")
-
-    when = now()
-    updated = dict(task)
-    updated["category"] = final_category
-    updated["tags"] = final_tags
-    updated["updated"] = when
-
-    logs = WorklogStore(repo)
-    path = logs.find(tid, task.get("worklog"))
-    if path is None:
-        mine.put(tid, updated)
-        return Result(
-            changed=("category", "tags", "updated"),
-            where=rel(repo, mine.path),
-            message=f"{tid}：改分类 / 标签",
-            notices=("提示：这条任务没有过程文档，只改了分片，文档与历史里看不到。",),
-        )
-
-    text = logs.read(path)
-    note = "改分类 / 标签：" + _describe(final_category, final_tags)
-    text = rewrite_label_line(text, final_category, final_tags)
-    text = append_exec_log(text, exec_line(when, me.stamp(), "set", note))
-    text = rewrite_status_line(
-        text, StatusLine(task.get("status") or "doing", me.name, me.uuid, when)
-    )
-    logs.write(path, text)
-    mine.put(tid, updated)
-
-    return Result(
-        changed=("category", "tags", "updated"),
-        where=rel(repo, mine.path),
-        message=f"{tid}：改分类 / 标签",
-    )

package/skill/scripts/ledgerkit/actions/release.py

@@ -1,76 +0,0 @@
-"""释放：写回公共池，再删我分片那行，再记一笔。"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..core.identity import Identity
-from ..core.paths import POOL_REL, shard_rel
-from ..core.time import now
-from ..core.worklog_md import StatusLine, 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.uuid), identity=me)
-    task = mine.get(tid)  # 锁内重读
-    if task is 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),
-                notices=(f"任务 {tid} 已经在公共池里，无需重复释放。",),
-            )
-        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)
-    path = logs.find(tid, back.get("worklog"))
-    note = None
-    if path is None:
-        note = f"任务 {tid} 已退回公共池，但过程文档没找到，跳过执行记录。"
-    else:
-        logs.append_exec(
-            path,
-            exec_line(now(), me.stamp(), "release", "释放回公共池"),
-            status=StatusLine("open", None, None, now()),
-        )
-    return Result(
-        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/skill/scripts/ledgerkit/actions/result.py

@@ -1,90 +0,0 @@
-"""动作的返回值长什么样。字段名是**公开契约**，插件看板直接读，外壳不许重新算。
-
-写动作返回 `Result`，只读动作返回各自的视图对象（不再套一层统一的壳）。
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any
-
-
-def rel(repo: Path, path: Path) -> str:
-    """绝对路径 → 相对 repo 的字符串（输出给人 / 给界面的一律这个基准）。"""
-    try:
-        return str(Path(path).resolve().relative_to(Path(repo).resolve()))
-    except ValueError:
-        return str(path)
-
-
-@dataclass(frozen=True)
-class WorklogView:
-    """「这条任务的过程文档要怎么显示」。"""
-
-    path: str | None = None  # 相对 repo
-    text: str | None = None  # 全文；读不到时为 None
-    error: str | None = None  # 读不到的原因（缺失 / 读不了），给人看
-
-
-@dataclass(frozen=True)
-class Result:
-    """写动作的返回。"""
-
-    changed: tuple[str, ...] = ()  # 改了哪些**字段名**（不是文件名、不是任务号）
-    where: str | None = None  # 主要落在哪个文件（**相对 repo**）
-    already_done: bool = False  # 重跑发现已经做过 ⇒ 退出码仍是 0
-    message: str | None = None  # git 提交说明；None ⇒ 外壳用默认模板
-    worklog: WorklogView | None = None
-    payload: dict[str, Any] = field(default_factory=dict)
-    notices: tuple[str, ...] = ()
-
-
-@dataclass(frozen=True)
-class TaskRow:
-    """人话表格的一行（9 字段投影）。`--json` 吐的是 `rows`（原样任务对象），不是它。"""
-
-    tid: str
-    title: str
-    status: str
-    owner: str | None = None  # 显示名
-    created: str | None = None
-    started: str | None = None
-    category: str | None = None
-    tags: tuple[str, ...] = ()
-    where: str | None = None  # 所在文件（相对 repo）
-
-
-@dataclass(frozen=True)
-class ListResult:
-    rows: dict[str, dict[str, Any]] = field(default_factory=dict)  # tid → 原样任务对象
-    table: tuple[TaskRow, ...] = ()
-    notices: tuple[str, ...] = ()
-
-
-@dataclass(frozen=True)
-class ShowResult:
-    task: dict[str, Any] = field(default_factory=dict)
-    worklog: WorklogView | None = None
-    others: tuple[str, ...] = ()  # 同一个任务号还出现在哪些文件里
-    #: 字段是从**在办索引**读来的（老文档没有状态行 / 文档丢了），不是文档自述
-    legacy: bool = False
-    notices: tuple[str, ...] = ()
-
-
-@dataclass(frozen=True)
-class HistoryResult:
-    count: int = 0
-    filters: dict[str, Any] = field(default_factory=dict)  # 回显生效的筛选
-    records: tuple[dict[str, Any], ...] = ()
-    warnings: tuple[str, ...] = ()
-    capped: bool = False
-
-
-@dataclass(frozen=True)
-class ValidationReport:
-    problems: tuple[str, ...] = ()  # 只有它影响退出码
-    notices: tuple[str, ...] = ()  # 只提示，不改退出码
-    checked_files: int = 0
-    total_tasks: int = 0
-    deep: bool = False  # 本次是深度检查（--deep）还是默认浅度

package/skill/scripts/ledgerkit/actions/set_task.py

@@ -1,73 +0,0 @@
-"""改归属的入口：只看 `--owner`，决定走哪个动作，**自己不加锁、不改任何文件**。
-
-它是全树唯一的跨动作引用点（import `release` / `handoff` / `claim`）。
-
-任务状态只随命令语义变（认领 → 进行中、释放 → 待认领、结案 → 历史），
-**没有单独的「改状态」入口**：`--status` 于 2026-10-23 删除 —— 全仓没有任何
-产品调用方（看板只有 claim / release / close 三个写路由），且它能制造
-「归我名下、状态却还是待认领」的坏状态（看板上显示成没人认领）。
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..core.identity import Identity, is_me
-from ..core.paths import shard_rel
-from ..errors import Fail
-from ..store.task_store import TaskStore
-from . import claim as claim_mod
-from . import handoff as handoff_mod
-from . import relabel as relabel_mod
-from . import release as release_mod
-from .guard import require_uuid
-from .result import Result, rel
-
-_MIXED = (
-    "--category / --tags 不能与 --release / --owner 同时给："
-    "一个是改分类标签，一个是改归属，分两次跑。"
-)
-
-
-def set_task(
-    repo: Path,
-    me: Identity,
-    tid: str,
-    *,
-    owner: str | None = None,
-    release: bool = False,
-    category: str | None = None,
-    tags: str | tuple[str, ...] | None = None,
-) -> Result:
-    """路由：`--release` = 释放；别人的 uuid = 交接；自己的 uuid = 已认领则空转、没认领先认领；
-    `--category` / `--tags` = 改分类与标签（只动文档头部那行与分片字段）。
-    """
-    relabel_wanted = bool(category or tags)
-    if release:
-        if owner is not None:
-            raise Fail("--release 与 --owner 不能同时给：释放不带人，交接不带释放。")
-        if relabel_wanted:
-            raise Fail(_MIXED)
-        return release_mod.release(repo, me, tid)
-    if owner is not None:
-        if relabel_wanted:
-            raise Fail(_MIXED)
-    else:
-        if relabel_wanted:
-            return relabel_mod.relabel(repo, me, tid, category=category, tags=tags)
-        raise Fail(
-            "set 必须给一样：`--release`（释放回公共池）/ `--owner <对方 uuid>`（交接）/ "
-            "`--category <分类>` 或 `--tags <a、b>`（改分类标签）。"
-        )
-    # 交接目标只收 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.uuid), identity=me)
-    if mine.get(tid) is not None:
-        return Result(
-            already_done=True,
-            where=rel(repo, mine.path),
-            notices=(f"任务 {tid} 已经在你名下，无需操作。",),
-        )
-    return claim_mod.claim(repo, me, tid)

package/skill/scripts/ledgerkit/actions/show_task.py

@@ -1,55 +0,0 @@
-"""只读：看一条任务。**文档优先**——读到文档就知道状态，不再翻索引（2026-10-27）。
-
-两条路径：
-- 文档存在且头部有状态行 ⇒ 完全按文档自述回答（`status` / 负责人 / 更新时间 / 标题），
-  pool、分片、历史一个都不读，已结案的任务同样看得到；
-- 文档没有状态行（老文档）或根本没有文档 ⇒ 回退 `load_task` 查在办索引，
-  返回里标 `legacy=True`，让调用方知道这些字段不是文档自述的。
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..core import worklog_md
-from ..core.identity import Identity
-from ..store.worklog_store import WorklogStore
-from .guard import load_task
-from .result import ShowResult, WorklogView, rel
-
-
-def show_task(repo: Path, me: Identity, tid: str) -> ShowResult:
-    logs = WorklogStore(repo)
-    path = logs.find(tid)  # 只按任务号找文件名：不碰 pool / 分片 / 历史
-    text = logs.read(path) if path is not None else ""
-    status = worklog_md.read_status(text) if text else None
-    if status is not None and path is not None:
-        head_tid, title = worklog_md.head_title(text)
-        return ShowResult(
-            task={
-                "tid": head_tid or tid,
-                "title": title,
-                "status": status.status,
-                "owner": status.uuid,
-                "owner_name": status.name,
-                "created": worklog_md.head_created(text),
-                "updated": status.when,
-                "finished": worklog_md.head_frozen(text),
-            },
-            worklog=WorklogView(path=rel(repo, path), text=text, error=None),
-        )
-
-    # 老文档 / 文档缺失：回退查在办（找不到会抛，文案与既往一致）
-    task, where = load_task(repo, tid)
-    if path is None:
-        view = WorklogView(
-            path=None, text=None, error="这条任务没有过程文档（或文档已不在原处）。"
-        )
-    else:
-        view = WorklogView(path=rel(repo, path), text=text or None, error=None)
-    return ShowResult(
-        task=task,
-        worklog=view,
-        others=tuple(rel(repo, p) for p in where),
-        legacy=True,
-    )

package/skill/scripts/ledgerkit/actions/validate.py

@@ -1,189 +0,0 @@
-"""只读：台账体检。两档：默认浅度只查格式，`--deep` 才读全部历史。
-
-浅度（默认）：池 + 各分片的字段格式、索引与文件对不对得上、**当月**历史。
-深度（`--deep`）：历史不止当月（全部月份）。
-
-**两档都不读过程文档正文**（2026-10-27 用户拍板）：过程文档是附件、存量可以上万篇，
-逐篇读全文换不来体检结论，只白花时间；文档自身的格式与内容不在体检范围。
-
-只查格式，不查业务（该谁结案、逾期与否都不管）；也不查「同一任务号落在多个文件」——
-读侧只显示一次（`list` / `show` 都不重复）、写侧已有防护，撞上了不关体检的事（2026-10-24 用户拍板）。
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..core import history_md
-from ..core.identity import Identity
-from ..core.labels import STATUSES
-from ..core.paths import (
-    LEDGER_DIR,
-    OWNERS_REL,
-    POOL_REL,
-    to_repo_rel,
-)
-from ..core.time import now
-from ..store.history_store import HistoryStore
-from ..store.owners_index import OwnersIndex
-from ..store.task_store import TaskStore
-from .guard import owner_of, status_of
-from .result import ValidationReport, rel
-
-
-def _read_tasks(repo: Path, store: TaskStore, problems: list[str]) -> dict:
-    """读一个任务文件；撞上**程序自留**的冲突标记 ⇒ 记一条 problem 继续。
-
-    推送被拒后 rebase 给 JSON 留的 `<<<<<<<` 是程序自己产的坏数据，validate
-    要能指出来（退 1 给清单），而不是整条命令退 3（2026-10-24 修）。
-    其余读错误（用户手改坏）不在此列，照旧抛出。
-    """
-    try:
-        return store.all()
-    except ValueError:
-        text = store.path.read_text(encoding="utf-8", errors="replace")
-        if "<<<<<<<" in text:
-            problems.append(
-                f"{rel(repo, store.path)} 带着冲突标记"
-                "（推送被拒后 rebase 没解完）：先解决冲突，再跑 validate。"
-            )
-            return {}
-        raise
-
-
-def _check_task_files(
-    repo: Path, index: OwnersIndex, problems: list[str]
-) -> tuple[int, int]:
-    """池 + 各分片的字段格式（owner / status / 分片归属）；返回 (查了几个文件, 几条任务)。"""
-    checked = 0
-    total = 0
-
-    pool = TaskStore(repo, POOL_REL)
-    if pool.path.exists():
-        checked += 1
-        for tid, task in _read_tasks(repo, pool, problems).items():
-            total += 1
-            if owner_of(task):
-                problems.append(
-                    f"公共池里的 {tid} 带着 owner（池里的行必须无人认领）。"
-                )
-            if task.get("status") not in STATUSES:
-                problems.append(f"公共池里的 {tid} 状态 {task.get('status')!r} 非法。")
-
-    for key, path in index.shards().items():
-        if not path.exists():
-            problems.append(f"索引登记了 {key}，但分片文件 {path.name} 不存在。")
-            continue
-        checked += 1
-        store = TaskStore(repo, Path(path).relative_to(repo / "ledger"))
-        for tid, task in _read_tasks(repo, store, problems).items():
-            total += 1
-            owner = owner_of(task)
-            if not owner:
-                problems.append(f"分片 {key} 里的 {tid} 没有 owner。")
-            elif owner != key:
-                problems.append(
-                    f"分片 {key} 里的 {tid} 的 owner 是 {owner}（分片主人与分区键不一致）。"
-                )
-            status = status_of(task)
-            if status not in STATUSES:
-                problems.append(f"分片 {key} 里的 {tid} 状态 {status!r} 非法。")
-
-    return checked, total
-
-
-def _check_orphan_shards(index: OwnersIndex, problems: list[str]) -> None:
-    """目录里有、索引没登记的分片（全仓唯一扫目录的地方）。"""
-    registered = {p.name for p in index.shards().values()}
-    for path in index.disk_shards():
-        if path.name not in registered:
-            problems.append(
-                f"owners/ 里的 {path.name} 没有在索引里登记（对它人等于不存在）。"
-            )
-
-
-def _history_paths(store: HistoryStore, *, deep: bool) -> list[Path]:
-    """要读的历史文件：浅度只读当月那个月文件（存量平铺文件不读），深度读全部。"""
-    sources = store.sources()
-    if deep:
-        return sources
-    month = now()[0:4] + now()[5:7]
-    return [p for p in sources if store.month_key(p) == month]
-
-
-def _check_history(
-    repo: Path,
-    paths: list[Path],
-    open_docs: set[str],
-    store: HistoryStore,
-    notices: list[str],
-) -> int:
-    """历史文件的格式与对账：解析警告、行尾文档链接对得上在办任务没。"""
-    checked = 0
-    for path in paths:
-        checked += 1
-        rows, warns = history_md.parse_history(store.read(path))
-        notices.extend(f"{rel(repo, path)}：{w}" for w in warns)
-        for row in rows:
-            name = Path(row.get("worklog") or "").name
-            if name and name in open_docs:
-                notices.append(
-                    f"历史里有「{row.get('title') or name}」的结案行，"
-                    "但它还挂在在办台账里。"
-                )
-    return checked
-
-
-def validate(repo: Path, me: Identity, deep: bool = False) -> ValidationReport:
-    problems: list[str] = []
-    notices: list[str] = []
-    checked = 0
-    total = 0
-
-    index = OwnersIndex(repo)
-    history = HistoryStore(repo)
-
-    files, tasks = _check_task_files(repo, index, problems)
-    checked += files
-    total += tasks
-    _check_orphan_shards(index, problems)
-
-    checked += _check_history(
-        repo,
-        _history_paths(history, deep=deep),
-        _open_worklog_names(repo, index),
-        history,
-        notices,
-    )
-
-    if not (repo / to_repo_rel(OWNERS_REL)).exists():
-        notices.append("还没有 owners.json（索引）：跑一条写命令会自动建。")
-    stray = repo / LEDGER_DIR / LEDGER_DIR
-    if stray.is_dir():
-        problems.append(
-            f"{rel(repo, stray)} 是错位的台账目录（根被当成 ledger/ 时写出来的幻影）；"
-            "确认哪份是真台账后删掉多余的，命令一律带 --repo <工作区根>。"
-        )
-
-    return ValidationReport(
-        problems=tuple(problems),
-        notices=tuple(notices),
-        checked_files=checked,
-        total_tasks=total,
-        deep=deep,
-    )
-
-
-def _open_worklog_names(repo: Path, index: OwnersIndex) -> set[str]:
-    """在办任务的过程文档**文件名**集合（池 + 全部分片）：历史行按它对账。"""
-    stores = [TaskStore(repo, POOL_REL)]
-    for path in index.shards().values():
-        if path.exists():
-            stores.append(TaskStore(repo, Path(path).relative_to(repo / "ledger")))
-    out: set[str] = set()
-    for store in stores:
-        for task in store.all().values():
-            name = Path((task.get("worklog") or "").strip()).name
-            if name:
-                out.add(name)
-    return out