dsh-task-ledger 0.0.78 → 0.0.80

package/skill/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

package/skill/scripts/ledgerkit/core/history_md.py

@@ -1,25 +1,25 @@
-"""历史表格的文本操作：拼行、解析、旧列数升级。
+"""历史表格的文本操作：拼十一列一行、解析十一列一行。
 
-**自己不开文件**：升级要回链 worklog 读头部，那件事由调用方传 `read_worklog`
-回调进来（`str -> str | None`），core 只做文本换算。
+**只认十一列这一种格式**：存量九列的文件按 `docs/history-creator-upgrade.md`
+那份手册一次性升级，脚本不做运行时迁移。
 """
 
 from __future__ import annotations
 
 import re
-from collections.abc import Callable, Iterable
-from pathlib import Path
+from collections.abc import Iterable
 from typing import Any
 
 from .paths import to_history_rel
 from .time import TIME_RE, time_key
 
 HISTORY_TITLE = "# 进度历史（已结案）"
-HISTORY_HEADER = "| 结案时间 | 创建时间 | 工作包 | 分类 | 标签 | owner | creator | 完成了什么 | 过程文档 |"
-HISTORY_SEP = "|---|---|---|---|---|---|---|---|---|"
+HISTORY_HEADER = (
+    "| 结案时间 | 创建时间 | 工作包 | 分类 | 标签 "
+    "| owner | owner_name | creator | creator_name | 完成了什么 | 过程文档 |"
+)
+HISTORY_SEP = "|---|---|---|---|---|---|---|---|---|---|---|"
 
-# 最旧格式把 owner 缝在工作包末尾：最右一个「空格 + @」之后整段是 owner。
-OLD_OWNER_RE = re.compile(r"^(?P<title>.*\S)\s+@(?P<owner>\S.*)$")
 _LINK_RE = re.compile(r"\[[^\]]*\]\(([^)]*)\)")
 _TAG_SPLIT_RE = re.compile(r"[,，、]")
 
@@ -32,7 +32,7 @@ def esc_cell(text: str) -> str:
 
 
 def owner_cell(owner: str | None) -> str:
-    """owner 列的展示值：人名前加 @（`@` 只是展示约定，匹配一律用裸标识）。"""
+    """owner 列的展示值：人名前加 @（`@` 只是展示约定，匹配一律用裸 uuid）。"""
     return f"@{owner}" if owner else ""
 
 
@@ -56,7 +56,6 @@ def is_sep_row(cells: list[str]) -> bool:
 
 
 def _looks_like_header(cells: list[str]) -> bool:
-    # 按内容判、不按位置判：无表头的老文件首行就是数据，按位置判会把第一条记录当表头删掉。
     return bool(cells) and cells[0] in ("时间", "结案时间")
 
 
@@ -70,10 +69,14 @@ def history_line(
     category: str | None = None,
     tags: Iterable[str] | None = None,
     creator: str | None = None,
+    owner_name: str | None = None,
+    creator_name: str | None = None,
 ) -> str:
-    """九列的一行。`worklog` 收**相对 `ledger/`** 的路径，这里负责换成相对 `history/` 的链接。
+    """十一列的一行。`worklog` 收**相对 `ledger/`** 的路径，这里负责换成相对 `history/` 的链接。
 
-    owner / creator 传**裸标识**（`@` 由 owner_cell / creator_cell 加），外面别先加。
+    owner / creator 传**裸 uuid**（`@` 由 owner_cell / creator_cell 加），外面别先加。
+    `owner_name` / `creator_name` 是**落盘的显示名快照**（结案那一刻的名字，之后改名不改旧行），
+    原值写入、**不加 `@`** —— `@` 只属于 uuid 那两列。
     """
     log_rel = to_history_rel(worklog) if worklog else ""
     tag_cell = esc_cell("、".join(tags) if tags else "")
@@ -81,71 +84,18 @@ def history_line(
     return (
         f"| {finished} | {created or ''} | {esc_cell(title)} "
         f"| {esc_cell(category or '')} | {tag_cell} "
-        f"| {esc_cell(owner_cell(owner))} | {esc_cell(creator_cell(creator))} "
+        f"| {esc_cell(owner_cell(owner))} | {esc_cell(owner_name or '')} "
+        f"| {esc_cell(creator_cell(creator))} | {esc_cell(creator_name or '')} "
         f"| {esc_cell(summary)} | {link} |\n"
     )
 
 
-def history_line_for_cols(
-    cols: int,
-    finished: str,
-    created: str | None,
-    title: str,
-    owner: str | None,
-    summary: str,
-    worklog: str | None,
-    category: str | None = None,
-    tags: Iterable[str] | None = None,
-    creator: str | None = None,
-) -> str:
-    """「历史层有无法解析的行、不敢整体升级」时按现有列数追加一行，避免列错位。
-
-    GFM 按首行列数渲染，列数写错会被静默丢弃 / 错位。少列的文件硬塞 9 列会把整行挤歪。
-    """
-    log_rel = to_history_rel(worklog) if worklog else ""
-    link = f"[{log_rel}]({log_rel})" if log_rel else ""
-    if cols <= 4:
-        who = f" @{owner}" if owner else ""
-        return (
-            f"| {finished} | {esc_cell(title + who)} | {esc_cell(summary)} | {link} |\n"
-        )
-    if cols == 5:
-        return (
-            f"| {finished} | {esc_cell(title)} | {esc_cell(owner_cell(owner))} "
-            f"| {esc_cell(summary)} | {link} |\n"
-        )
-    if cols == 6:
-        return (
-            f"| {finished} | {created or ''} | {esc_cell(title)} "
-            f"| {esc_cell(owner_cell(owner))} | {esc_cell(summary)} | {link} |\n"
-        )
-    return history_line(
-        finished, created, title, owner, summary, worklog, category, tags, creator
-    )
-
-
-def history_cols(text: str) -> int:
-    """现有历史表格数据行的列数（取众数、平局取较大）；无数据行时按 6。"""
-    counts: dict[int, int] = {}
-    for raw in text.splitlines():
-        if not raw.strip().startswith("|"):
-            continue
-        cells = split_row(raw)
-        if not cells or is_sep_row(cells) or _looks_like_header(cells):
-            continue
-        if len(cells) >= 4:
-            counts[len(cells)] = counts.get(len(cells), 0) + 1
-    if not counts:
-        return 6
-    return max(counts, key=lambda k: (counts[k], k))
-
-
 def parse_history(text: str) -> tuple[list[Row], list[str]]:
-    """解析历史表 → (records, warnings)。**逐行按自己的列数判别**，表头只用来跳过。
+    """解析十一列历史表 → (records, warnings)。坏行（列数不对 / 时间列不合法）跳过并警告。
 
-    兼容 9 / 8 / 6 / 5（两种）/ 4 列；坏行（列数不在列、时间列不合法）跳过并警告，不中断。
-    返回的键：finished / created / title / category / tags / owner / creator / summary /
-    worklog / fmt / line。owner 与 creator 一律**剥掉 `@`**（匹配用裸标识）。
+    返回的键：finished / created / title / category / tags / owner / owner_name /
+    creator / creator_name / summary / worklog / fmt / line。owner 与 creator 一律
+    **剥掉 `@`**（存储值是裸 uuid）；两个名字列是**原值**（落盘快照，可能为空）。
     """
     records: list[Row] = []
     warnings: list[str] = []
@@ -155,196 +105,43 @@ def parse_history(text: str) -> tuple[list[Row], list[str]]:
         cells = split_row(raw)
         if not cells or is_sep_row(cells) or _looks_like_header(cells):
             continue
-        created = ""
-        category: str | None = None
-        tags: list[str] = []
-        creator: str | None = None
-        if len(cells) == 9:
-            (
-                finished,
-                created,
-                title,
-                category,
-                tag_cell,
-                owner,
-                creator,
-                summary,
-                doc,
-            ) = cells
-            fmt = "v9"
-            category = category.strip() or None
-            tags = [t.strip() for t in _TAG_SPLIT_RE.split(tag_cell) if t.strip()]
-            creator = creator.strip().removeprefix("@") or None
-        elif len(cells) == 8:
-            finished, created, title, category, tag_cell, owner, summary, doc = cells
-            fmt = "v8"
-            category = category.strip() or None
-            tags = [t.strip() for t in _TAG_SPLIT_RE.split(tag_cell) if t.strip()]
-        elif len(cells) == 6:
-            finished, created, title, owner, summary, doc = cells
-            fmt = "v6"
-        elif len(cells) == 5 and TIME_RE.fullmatch(cells[1]):
-            # 旧 ledger 格式（结案 / 创建 / 工作包 / 摘要 / 文档）：行内自带创建时间。
-            finished, created, title, summary, doc = cells
-            owner = ""
-            fmt = "v5ledger"
-        elif len(cells) == 5:
-            finished, title, owner, summary, doc = cells
-            fmt = "v5"
-        elif len(cells) == 4:
-            finished, title, summary, doc = cells
-            m = OLD_OWNER_RE.match(title)
-            owner = m.group("owner") if m else ""
-            if m:
-                title = m.group("title")
-            fmt = "v4"
-        else:
-            warnings.append(f"第 {lineno} 行列数不是 4 / 5 / 6 / 8 / 9，已跳过")
+        if len(cells) != 11:
+            warnings.append(f"第 {lineno} 行不是十一列（历史表只认十一列），已跳过")
             continue
+        (
+            finished,
+            created,
+            title,
+            category,
+            tag_cell,
+            owner,
+            owner_name,
+            creator,
+            creator_name,
+            summary,
+            doc,
+        ) = cells
         if not TIME_RE.fullmatch(finished):
             warnings.append(f"第 {lineno} 行时间列 {finished!r} 不合法，已跳过")
             continue
         m = _LINK_RE.fullmatch(doc.strip())
-        log = m.group(1) if m else doc.strip()
         records.append(
             {
                 "finished": finished,
                 "created": time_key(created) if created else None,
                 "title": title,
-                "category": category,
-                "tags": tuple(tags),
-                "owner": (owner or "").strip().removeprefix("@") or None,
-                "creator": creator,
+                "category": category.strip() or None,
+                "tags": tuple(
+                    t.strip() for t in _TAG_SPLIT_RE.split(tag_cell) if t.strip()
+                ),
+                "owner": owner.strip().removeprefix("@") or None,
+                "owner_name": owner_name.strip() or None,
+                "creator": creator.strip().removeprefix("@") or None,
+                "creator_name": creator_name.strip() or None,
                 "summary": summary,
-                "worklog": log or None,
-                "fmt": fmt,
+                "worklog": (m.group(1) if m else doc.strip()) or None,
+                "fmt": "v11",
                 "line": lineno,
             }
         )
     return records, warnings
-
-
-def _drop_trailing_blank(out: list[str]) -> None:
-    """去掉已在结果里的尾部空行（丢弃重复表头时用）：中间的空行会把 GFM 表格截断。"""
-    while out and not out[-1].strip():
-        out.pop()
-
-
-def upgrade_history(
-    text: str,
-    *,
-    read_worklog: Callable[[str], dict[str, Any] | None],
-    fallback_created: str,
-) -> tuple[str, int] | None:
-    """旧格式（4 / 5 / 6 / 8 列）→ v9。**全部数据行可解析才返回 (新文本, 转换行数)**，否则 None。
-
-    `None` 的语义是「不敢动」：调用方必须退回 `history_line_for_cols` 按原列数追加并明示，
-    绝不半升级、绝不猜。分类 / 标签 / creator / 缺的创建时间都靠 `read_worklog` 回链补，
-    读不到就留空（创建时间除外：留空会让排序失效，所以退化到 `fallback_created`）。
-
-    `read_worklog` 的契约：`(log_name: str) -> dict | None` —— 收**文件名**（历史末列的
-    basename，不是路径），返回 `{"created", "creator", "category", "tags"}`。core 只消费
-    返回值，自己不开文件。
-    """
-    out: list[str] = []
-    converted = 0
-    seen_header = False
-    seen_sep = False
-    for raw in text.splitlines():
-        if not raw.strip().startswith("|"):
-            out.append(raw)
-            continue
-        cells = split_row(raw)
-        if not cells:
-            out.append(raw)
-            continue
-        if is_sep_row(cells):
-            if seen_sep:
-                _drop_trailing_blank(out)
-                continue
-            seen_sep = True
-            out.append(HISTORY_SEP)
-            continue
-        if _looks_like_header(cells):
-            if seen_header:
-                _drop_trailing_blank(out)
-                continue
-            seen_header = True
-            out.append(HISTORY_HEADER)
-            continue
-        if len(cells) == 9:
-            if time_key(cells[0]) is None:
-                return None
-            out.append("| " + " | ".join(cells) + " |")
-            continue
-        explicit_created: str | None = None
-        creator: str | None = None
-        if len(cells) == 8:
-            finished, created, title, category, tag_cell, owner, summary, doc = cells
-            if time_key(finished) is None:
-                return None
-            created_key = time_key(created.strip())
-            tags = [t.strip() for t in _TAG_SPLIT_RE.split(tag_cell) if t.strip()]
-            creator = (_meta_of(doc, read_worklog) or {}).get("creator")
-            out.append(
-                f"| {finished} | {created_key or ''} | {esc_cell(title)} "
-                f"| {esc_cell(category.strip())} "
-                f"| {esc_cell('、'.join(tags) if tags else '')} "
-                f"| {esc_cell(owner_cell(owner.lstrip('@')))} "
-                f"| {esc_cell(creator_cell(creator))} "
-                f"| {esc_cell(summary)} | {doc} |"
-            )
-            converted += 1
-            continue
-        if len(cells) == 6:
-            finished, created, title, owner, summary, doc = cells
-            owner = owner.lstrip("@")
-            explicit_created = time_key(created.strip())
-        elif len(cells) == 5 and TIME_RE.fullmatch(cells[1]):
-            finished, created_cell, title, summary, doc = cells
-            owner = ""
-            explicit_created = time_key(created_cell.strip())
-        elif len(cells) == 5:
-            finished, title, owner, summary, doc = cells
-            owner = owner.lstrip("@")
-        elif len(cells) == 4:
-            finished, title, summary, doc = cells
-            m = OLD_OWNER_RE.match(title)
-            owner = m.group("owner") if m else ""
-            if m:
-                title = m.group("title")
-        else:
-            return None
-        finished_key = time_key(finished)
-        if finished_key is None:
-            return None
-        meta = _meta_of(doc, read_worklog)
-        created = explicit_created or (meta or {}).get("created") or fallback_created
-        category = (meta or {}).get("category")
-        tags = tuple((meta or {}).get("tags") or ())
-        creator = (meta or {}).get("creator")
-        out.append(
-            f"| {finished_key} | {created} | {esc_cell(title)} "
-            f"| {esc_cell(category or '')} "
-            f"| {esc_cell('、'.join(tags) if tags else '')} "
-            f"| {esc_cell(owner_cell(owner))} "
-            f"| {esc_cell(creator_cell(creator))} "
-            f"| {esc_cell(summary)} | {doc} |"
-        )
-        converted += 1
-    return "\n".join(out) + "\n", converted
-
-
-def _link_target(cell: str) -> str:
-    m = _LINK_RE.fullmatch((cell or "").strip())
-    return (m.group(1) if m else (cell or "")).strip()
-
-
-def _meta_of(
-    doc: str, read_worklog: Callable[[str], dict[str, Any] | None]
-) -> dict[str, Any] | None:
-    """顺着历史行的文档链接取回 worklog 头部四样（`read_worklog` 收文件名）。"""
-    target = _link_target(doc)
-    if not target:
-        return None
-    return read_worklog(Path(target).name)

package/skill/scripts/ledgerkit/core/identity.py

@@ -1,20 +1,42 @@
-"""身份这个值对象：归一化与比较规则。**只做字符串换算，不读 git**（读 git 归 env.py）。"""
+"""身份这个值对象：uuid 是唯一键，name 只用于显示与查询筛选。
+
+**只做字符串换算，不读文件**（读身份归 env.py）。名字永远不参与归属判定：
+认领 / 释放 / 交接 / 查「我的」，一律只比 uuid。
+"""
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass
 
+#: 合法身份键的形态（8-4-4-4-12 的十六进制 UUID）。`--owner` 只收这种值。
+UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
 
 @dataclass(frozen=True)
 class Identity:
-    """一个人的身份。`email` 是分区键（归一化后的裸标识），`name` 只用于显示。"""
+    """一个人的身份。`uuid` 是唯一键，`name` 只用于显示。"""
 
-    email: str
+    uuid: str
     name: str = ""
 
     def label(self) -> str:
-        """显示名：没名字就用邮箱。"""
-        return self.name or self.email
+        """显示名：没名字就用 uuid 前 8 位。只给人看（报错文案、界面）。"""
+        return self.name or self.uuid[:8]
+
+    def stamp(self) -> str:
+        """**落盘**用的身份串：`名字 · uuid` —— 名字在前给人读，uuid 在后给机器对。
+
+        与 `label()` 一样**不带 `@`**（`@` 由各落点自己加：模板创建行是 `（@<creator>）`、
+        `exec_line` 拼 ` · @{who} · `、`stamp_frozen` 拼 `（@{who}）`）。
+
+        过程文档（创建行 / 封卷行 / 执行记录）是这个串唯一的落点：文件是最终产物，
+        创建人和封卷人可能不是同一个人、也可能中途改过名，所以**两个都要留**，不靠
+        历史表回链。没名字就只写 uuid。
+        """
+        if not self.name:
+            return self.uuid
+        return f"{self.name} · {self.uuid}"
 
 
 def normalize(who: str) -> str:
@@ -22,6 +44,11 @@ def normalize(who: str) -> str:
     return (who or "").strip().lower()
 
 
+def looks_like_uuid(who: str | None) -> bool:
+    """是不是一个 UUID 形态的身份键（名字、邮箱一律 False）。"""
+    return bool(UUID_RE.match(normalize(who or "")))
+
+
 def is_me(identity: Identity, who: str | None) -> bool:
-    """`who`（邮箱）是不是这个人。全站只认邮箱这一个身份键。"""
-    return normalize(who or "") == normalize(identity.email)
+    """`who`（uuid）是不是这个人。全站只认 uuid 这一个身份键。"""
+    return normalize(who or "") == normalize(identity.uuid)

package/skill/scripts/ledgerkit/core/labels.py

@@ -8,7 +8,6 @@ from collections.abc import Iterable
 from ..errors import Fail
 
 STATUSES = ("open", "doing")
-LEGACY_STATUSES = ("blocked",)  # 旧数据：读侧当进行中，不写回
 FORMAT_VERSION = "20261022000000"
 
 LABEL_MAX_CHARS = 4  # 含 CJK 时按「字」算

package/skill/scripts/ledgerkit/core/paths.py

@@ -20,7 +20,6 @@ OWNERS_REL = Path("owners.json")
 OWNERS_DIR = Path("owners")
 HISTORY_DIR = Path("history")
 WORKLOG_DIR = Path("worklog")
-LEGACY_HISTORY_REL = Path("PROGRESS-HISTORY.md")  # 存量平铺文件：只读不写
 
 SHA_LEN = 12
 

package/skill/scripts/ledgerkit/core/worklog_md.py

@@ -10,6 +10,7 @@ from collections.abc import Iterable
 from itertools import takewhile
 
 from ..errors import Fail
+from .identity import UUID_RE
 from .labels import label_line, parse_label_line
 from .time import fmt_local, normalize_time
 
@@ -21,7 +22,9 @@ EXEC_HINT = (
 FROZEN_MARK = "✅ 完成封卷"
 FROZEN_RE = re.compile(r"^>\s*" + FROZEN_MARK, re.MULTILINE)
 CREATED_RE = re.compile(r"^\s*>\s*\*\*创建\*\*")
-# 头部「创建」行：`> **创建**：2026-10-06 00:00（@某人）` —— 创建时间与发起人两个来源。
+# 头部「创建」行：`> **创建**：2026-10-06 00:00（@某人 · uuid）` —— 创建时间与发起人两个来源。
+# 括号里落 `Identity.stamp()`（`@名字 · uuid`）：名字在前给人读，uuid 在后给机器对。
+# 老文档只有名字（没有 uuid）时，下面两个函数各自返回它能读到的那一段，不报错。
 CREATED_AT_RE = re.compile(
     r"^\s*>\s*\*\*创建\*\*\s*[：:]\s*"
     r"(\d{4}-\d{2}-\d{2}(?: +\d{1,2}:\d{1,2}(?::\d{1,2})?)?)"
@@ -224,9 +227,26 @@ def head_created(text: str) -> str | None:
 
 
 def head_creator(text: str) -> str | None:
-    """头部「创建」行括号里的发起人（裸标识，不带 @）；读不到返回 None。"""
+    """头部「创建」行括号里的发起人**名字**（不带 @、不带 uuid）；读不到返回 None。"""
     for line in text.splitlines():
         m = CREATOR_RE.match(line)
         if m and m.group(1).strip():
-            return m.group(1).strip()
+            return m.group(1).split(" · ")[0].strip()
+    return None
+
+
+def head_creator_uuid(text: str) -> str | None:
+    """头部「创建」行括号里的发起人 **uuid**；老文档没落 uuid 时返回 None。
+
+    `UUID_RE` 带 `^$` 锚点，只能整串匹配 —— 所以先按 ` · ` 切出尾段再判，不能 search。
+    """
+    for line in text.splitlines():
+        m = CREATOR_RE.match(line)
+        if not m:
+            continue
+        parts = m.group(1).split(" · ")
+        if len(parts) > 1:
+            uuid = parts[-1].strip()
+            if UUID_RE.fullmatch(uuid):
+                return uuid
     return None