dsh-task-ledger 0.0.100 → 0.0.102

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

@@ -1,152 +0,0 @@
-"""历史表格的文本操作：拼十一列一行、解析十一列一行。
-
-**只认十一列这一种格式**：存量九列的文件按 `docs/history-creator-upgrade.md`
-那份手册一次性升级，脚本不做运行时迁移。
-"""
-
-from __future__ import annotations
-
-import re
-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 | owner_name | creator | creator_name | 完成了什么 | 过程文档 |"
-)
-HISTORY_SEP = "|---|---|---|---|---|---|---|---|---|---|---|"
-
-_LINK_RE = re.compile(r"\[[^\]]*\]\(([^)]*)\)")
-_TAG_SPLIT_RE = re.compile(r"[,，、]")
-
-Row = dict[str, Any]  # 一条历史行：见 parse_history 的返回
-
-
-def esc_cell(text: str) -> str:
-    """表格单元格：折叠空白并转义竖线，避免把历史表格写坏。"""
-    return " ".join((text or "").split()).replace("|", "\\|")
-
-
-def owner_cell(owner: str | None) -> str:
-    """owner 列的值：裸 uuid，**不加 `@`**（`@` 只加在名字列；匹配一律用裸 uuid）。"""
-    return owner or ""
-
-
-def creator_cell(creator: str | None) -> str:
-    """creator 列的值（与 owner_cell 同一约定：裸 uuid，不加 `@`）。"""
-    return creator or ""
-
-
-def name_cell(name: str | None) -> str:
-    """名字列的展示值：名字前加 `@`（与过程文档 `@名字 · uuid` 同一口径）。"""
-    return f"@{name}" if name else ""
-
-
-def split_row(line: str) -> list[str]:
-    """按 `|` 切表格行：转义竖线 `\\|` 不当分隔符，切完反转义、去首尾空单元。"""
-    cells = re.split(r"(?<!\\)\|", line.strip())
-    if cells and cells[0] == "":
-        cells = cells[1:]
-    if cells and cells[-1] == "":
-        cells = cells[:-1]
-    return [c.strip().replace("\\|", "|") for c in cells]
-
-
-def is_sep_row(cells: list[str]) -> bool:
-    return bool(cells) and all(re.fullmatch(r":?-+:?", c) for c in cells)
-
-
-def _looks_like_header(cells: list[str]) -> bool:
-    return bool(cells) and cells[0] in ("时间", "结案时间")
-
-
-def history_line(
-    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,
-    owner_name: str | None = None,
-    creator_name: str | None = None,
-) -> str:
-    """十一列的一行。`worklog` 收**相对 `ledger/`** 的路径，这里负责换成相对 `history/` 的链接。
-
-    owner / creator 传**裸 uuid**、名字传**裸名字**，两处都别先加 `@`：
-    `@` 由 `name_cell` 只加在名字列（与过程文档 `@名字 · uuid` 同一口径），uuid 列永远是裸值。
-    `owner_name` / `creator_name` 是**落盘的显示名快照**（结案那一刻的名字，之后改名不改旧行）。
-    """
-    log_rel = to_history_rel(worklog) if worklog else ""
-    tag_cell = esc_cell("、".join(tags) if tags else "")
-    link = f"[{log_rel}]({log_rel})" if log_rel else ""
-    return (
-        f"| {finished} | {created or ''} | {esc_cell(title)} "
-        f"| {esc_cell(category or '')} | {tag_cell} "
-        f"| {esc_cell(owner_cell(owner))} | {esc_cell(name_cell(owner_name))} "
-        f"| {esc_cell(creator_cell(creator))} | {esc_cell(name_cell(creator_name))} "
-        f"| {esc_cell(summary)} | {link} |\n"
-    )
-
-
-def parse_history(text: str) -> tuple[list[Row], list[str]]:
-    """解析十一列历史表 → (records, warnings)。坏行（列数不对 / 时间列不合法）跳过并警告。
-
-    返回的键：finished / created / title / category / tags / owner / owner_name /
-    creator / creator_name / summary / worklog / fmt / line。owner 与 creator 两列
-    **剥掉 `@`**（存储值是裸 uuid）；两个名字列剥掉展示用的 `@`（落盘快照，可能为空）。
-    """
-    records: list[Row] = []
-    warnings: list[str] = []
-    for lineno, raw in enumerate(text.splitlines(), 1):
-        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) != 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())
-        records.append(
-            {
-                "finished": finished,
-                "created": time_key(created) if created else None,
-                "title": title,
-                "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().removeprefix("@") or None,
-                "creator": creator.strip().removeprefix("@") or None,
-                "creator_name": creator_name.strip().removeprefix("@") or None,
-                "summary": summary,
-                "worklog": (m.group(1) if m else doc.strip()) or None,
-                "fmt": "v11",
-                "line": lineno,
-            }
-        )
-    return records, warnings

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

@@ -1,54 +0,0 @@
-"""身份这个值对象：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:
-    """一个人的身份。`uuid` 是唯一键，`name` 只用于显示。"""
-
-    uuid: str
-    name: str = ""
-
-    def label(self) -> str:
-        """显示名：没名字就用 uuid 前 8 位。只给人看（报错文案、界面）。"""
-        return self.name or self.uuid[:8]
-
-    def stamp(self) -> str:
-        """**落盘**用的身份串：`名字 · uuid` —— 名字在前给人读，uuid 在后给机器对。
-
-        与 `label()` 一样**不带 `@`**（`@` 由各落点自己加：头部各行拼 ` · @{stamp}`、
-        `exec_line` 拼 ` · @{who} · `）。
-
-        过程文档（创建行 / 状态行 / 封卷行 / 执行记录）是这个串唯一的落点：文件是最终产物，
-        创建人和封卷人可能不是同一个人、也可能中途改过名，所以**两个都要留**，不靠
-        历史表回链。没名字就只写 uuid。
-        """
-        if not self.name:
-            return self.uuid
-        return f"{self.name} · {self.uuid}"
-
-
-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`（uuid）是不是这个人。全站只认 uuid 这一个身份键。"""
-    return normalize(who or "") == normalize(identity.uuid)

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

@@ -1,58 +0,0 @@
-"""任务号：生成、形态校验。只做字符串换算。"""
-
-from __future__ import annotations
-
-import re
-import secrets
-from collections.abc import Mapping
-
-from ..errors import Fail
-from .time import now
-
-ID_RE = re.compile(r"[a-z0-9\u4e00-\u9fff][a-z0-9\u4e00-\u9fff-]*\Z")
-
-
-def slugify(title: str) -> str:
-    """任务号用：保留 ASCII 字母数字与汉字，其余转连字符，截到 40 字。"""
-    s = re.sub(r"[^a-z0-9\u4e00-\u9fff]+", "-", title.strip().lower())
-    return s.strip("-")[:40].strip("-")
-
-
-def id_stamp(created: str) -> str:
-    """`created`（YYYY-MM-DD HH:MM:SS）→ 任务号前缀 `YYYYMMDD-HHMM`（任务号只到分）。"""
-    return (
-        f"{created[0:4]}{created[5:7]}{created[8:10]}-{created[11:13]}{created[14:16]}"
-    )
-
-
-def make_id(title: str, tasks: Mapping[str, object], created: str | None = None) -> str:
-    """按标题生成一个不撞号的任务号。
-
-    随机码不能省：`make_id` 只在**在办**任务里去重，而结案的过程文档长期留在磁盘上，
-    去掉随机码会让新任务撞上已结案文档的名字。
-    """
-    slug = slugify(title)
-    if not slug:
-        raise Fail(
-            "标题里没有可用字符（字母、数字或汉字），无法自动生成任务号。"
-            f'用 --id 指定一个，例如 --id "task-{secrets.token_hex(2)}"。'
-        )
-    stamp = id_stamp(created or now())
-    for _ in range(20):
-        tid = f"{stamp}-{slug}-{secrets.token_hex(2)}"
-        if tid not in tasks:
-            return tid
-    raise Fail("任务号连续冲突 20 次，请检查台账是否异常。")
-
-
-def require_task_id(tid: str) -> str:
-    """任务号形态校验（全仓唯一入口）。不合法直接抛 Fail。"""
-    value = (tid or "").strip()
-    if not value:
-        raise Fail("任务号不能为空。")
-    if not ID_RE.fullmatch(value.lower()):
-        raise Fail(
-            f"任务号 {tid!r} 不合法：只能用小写字母、数字、汉字和连字符，"
-            "且不能以连字符开头或结尾。"
-        )
-    return value

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

@@ -1,90 +0,0 @@
-"""分类与标签：校验、拼行、拆行。只做文本换算。"""
-
-from __future__ import annotations
-
-import re
-from collections.abc import Iterable
-
-from ..errors import Fail
-
-STATUSES = ("open", "doing")
-FORMAT_VERSION = "20261022000000"
-
-LABEL_MAX_CHARS = 4  # 含 CJK 时按「字」算
-LABEL_MAX_WORDS_EN = 3  # 纯 ASCII 时按「词」算
-TAGS_MAX_COUNT = 5
-
-CJK_RE = re.compile(r"[\u4e00-\u9fff]")
-LABEL_CAT_RE = re.compile(r"分类\*\*\s*[：:]\s*([^｜|·]+)")
-LABEL_TAG_RE = re.compile(r"标签\*\*\s*[：:]\s*(.+)$")
-_SPLIT_RE = re.compile(r"[,，、]")
-
-
-def normalize_label(value: str, *, field: str) -> str:
-    """分类 / 单个标签的校验：去空白、限长。空串直接 Fail（给了就要有意义）。"""
-    text = (value or "").strip()
-    if not text:
-        raise Fail(f"{field} 不能为空。")
-    if CJK_RE.search(text):
-        if len(text) > LABEL_MAX_CHARS:
-            raise Fail(f"{field} {text!r} 太长：含中文时最多 {LABEL_MAX_CHARS} 个字。")
-    elif len(text.split()) > LABEL_MAX_WORDS_EN:
-        raise Fail(f"{field} {text!r} 太长：英文最多 {LABEL_MAX_WORDS_EN} 个词。")
-    return text
-
-
-def parse_tags(raw: str | Iterable[str] | None) -> tuple[str, ...]:
-    """标签串（「、」「,」「，」分隔）→ 去重保序的元组；超上限报错。"""
-    if raw is None:
-        return ()
-    items = list(raw) if not isinstance(raw, str) else _SPLIT_RE.split(raw)
-    out: list[str] = []
-    for item in items:
-        text = normalize_label(str(item).strip(), field="标签")
-        if text not in out:
-            out.append(text)
-    if len(out) > TAGS_MAX_COUNT:
-        raise Fail(f"标签最多 {TAGS_MAX_COUNT} 个，收到 {len(out)} 个。")
-    return tuple(out)
-
-
-def label_line(category: str | None, tags: Iterable[str] | None) -> str:
-    """过程文档头部的「分类 / 标签」行；两者皆空返回空串（此行不写）。"""
-    segs: list[str] = []
-    if category:
-        segs.append(f"**分类**：{category}")
-    tag_list = [t for t in (tags or ()) if t]
-    if tag_list:
-        segs.append(f"**标签**：{'、'.join(tag_list)}")
-    return "- " + " · ".join(segs) if segs else ""
-
-
-def parse_label_line(text: str) -> tuple[str | None, tuple[str, ...]]:
-    """从过程文档头部（第一个 `## ` 小节之前）解析分类与标签。
-
-    跳过 HTML 注释块：模板注释里举例写着「**分类**：…」，那不是数据。
-    """
-    in_comment = False
-    for line in text.splitlines():
-        if line.startswith("## "):
-            break
-        stripped = line.lstrip()
-        if in_comment:
-            if "-->" in stripped:
-                in_comment = False
-            continue
-        if stripped.startswith("<!--"):
-            in_comment = "-->" not in stripped
-            continue
-        mc = LABEL_CAT_RE.search(line)
-        mt = LABEL_TAG_RE.search(line)
-        if not (mc or mt):
-            continue
-        category = mc.group(1).strip() if mc else None
-        tags = (
-            tuple(t.strip() for t in _SPLIT_RE.split(mt.group(1).strip()) if t.strip())
-            if mt
-            else ()
-        )
-        return (category or None, tags)
-    return (None, ())

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

@@ -1,92 +0,0 @@
-"""路径与文件名怎么拼：只做换算，一个文件都不碰。
-
-**基准只有两个**：
-- 磁盘与 JSON 里存的（`task["worklog"]` 等）一律**相对 `ledger/`**；
-- 输出给人或给界面的（`Result.where`、`payload` 里的 `*_path`）一律**相对 repo**。
-
-换算只在这两个函数里做，任何层都不许自己拼 `..`。
-"""
-
-from __future__ import annotations
-
-import hashlib
-import re
-from pathlib import Path
-
-LEDGER_DIR = Path("ledger")
-
-POOL_REL = Path("pool.json")
-OWNERS_REL = Path("owners.json")
-OWNERS_DIR = Path("owners")
-HISTORY_DIR = Path("history")
-WORKLOG_DIR = Path("worklog")
-
-SHA_LEN = 12
-
-# 模板与资产的唯一定位基准：按自身位置算绝对路径，不依赖调用方 cwd。
-# ledgerkit/core/paths.py → parents: [core, ledgerkit, scripts, skill]
-SKILL_DIR = Path(__file__).resolve().parents[3]
-WORKLOG_TEMPLATE = SKILL_DIR / "assets" / "worklog.md"
-
-
-def to_repo_rel(ledger_rel: str | Path) -> Path:
-    """相对 `ledger/` 的路径 → 相对 repo 的路径。"""
-    return LEDGER_DIR / Path(ledger_rel)
-
-
-def to_ledger_rel(repo_rel: str | Path) -> str:
-    """相对 repo 的路径 → 相对 `ledger/` 的路径（已经是 `ledger/` 内的原样返回）。"""
-    p = Path(repo_rel)
-    if p.parts and p.parts[0] == LEDGER_DIR.name:
-        return Path(*p.parts[1:]).as_posix()
-    return p.as_posix()
-
-
-def to_history_rel(ledger_rel: str | Path) -> str:
-    """`ledger/` 内的路径 → 从 `ledger/history/<ym>.md` 出发的链接串。
-
-    深度固定（`history/` 与 `worklog/` 都在 `ledger/` 下），拼 `..` 只许在这一处。
-    """
-    return ("../" / Path(ledger_rel)).as_posix()
-
-
-def shard_rel(identity: str) -> Path:
-    """某人分片相对 `ledger/` 的路径：sha256(归一化身份)[:12] + .json。"""
-    digest = hashlib.sha256(identity.strip().lower().encode("utf-8")).hexdigest()
-    return OWNERS_DIR / f"{digest[:SHA_LEN]}.json"
-
-
-def month_of(stamp: str, *, fallback_now: str | None = None) -> str:
-    """存盘时间 → `YYYYMM`；取不到时用 `fallback_now`，再没有就抛错由调用方定夺。"""
-    month = re.sub(r"[^0-9]", "", (stamp or "")[:7])[:6]
-    if len(month) == 6:
-        return month
-    if fallback_now:
-        return re.sub(r"[^0-9]", "", fallback_now[:7])[:6]
-    return ""
-
-
-def worklog_dir_for(created: str) -> Path:
-    """过程文档的按月目录（相对 `ledger/`）：`worklog/<YYYYMM>/`。"""
-    return WORKLOG_DIR / month_of(created)
-
-
-def worklog_name(tid: str) -> str:
-    """过程文档的文件名：任务号剥掉前缀年月日，随机码保留。
-
-    父目录 `worklog/<YYYYMM>/` 已带年月，文件名里再写一遍是冗余；
-    自定义 `--id` 不以「8 位数字-」开头时，文件名就是任务号本身。
-    """
-    if len(tid) > 9 and tid[:8].isdigit() and tid[8] == "-":
-        return f"{tid[6:]}.md"
-    return f"{tid}.md"
-
-
-def worklog_rel(tid: str, created: str) -> str:
-    """过程文档相对 `ledger/` 的路径：任务对象与历史末列共用同一口径。"""
-    return (worklog_dir_for(created) / worklog_name(tid)).as_posix()
-
-
-def history_path_for(finished: str) -> Path:
-    """结案时间 → 历史文件相对 `ledger/` 的路径：`history/<YYYYMM>.md`。"""
-    return HISTORY_DIR / f"{month_of(finished)}.md"

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

@@ -1,74 +0,0 @@
-"""工作区根的判定：哪个目录才是「直接含有 `ledger/` 的那个根」。
-
-全仓唯一实现 —— `shell/` 与 `actions/` 都调这里，不各写一份（否则口径会漂）。
-判据是**结构**（含不含 `ledger/`、自己在不在 `ledger/` 里），不看目录里有哪些文件：
-项目根自带 `pool.json`、`history/` + `worklog/`、`owners.json` + `owners/` 这类同名文件
-或目录都很常见，按「里面有什么」判会把正常项目根误当成台账目录（2026-10-25 改）。
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from ..errors import Fail
-from .paths import LEDGER_DIR
-
-
-def _under_ledger(p: Path) -> bool:
-    """`p` 自己叫 `ledger`，或它落在某个 `ledger/` 目录里面。"""
-    if p.name == LEDGER_DIR.name:
-        return True
-    return any(anc.name == LEDGER_DIR.name for anc in p.parents)
-
-
-def as_root(repo: str | Path, *, source: str = "--repo") -> Path:
-    """校验「工作区根」，只看结构：
-
-    - 直接含 `ledger/` ⇒ 就是根。哪怕项目根自己叫 `ledger`、哪怕它自己也有 `pool.json`；
-    - 不含 `ledger/`、但自己叫 `ledger` 或落在某个 `ledger/` 下 ⇒ 是台账目录 / 台账里面，拒；
-    - 其余（含全新空目录）⇒ 收，第一条写命令会在它下面建 `ledger/`。
-    """
-    p = Path(repo).expanduser()
-    if not p.is_dir():
-        raise Fail(
-            f"{source} 指向的不是一个目录：{p}\n"
-            f"  处理：指向工作区根（直接含有 ledger/ 的那个目录，不是 ledger/ 本身）。"
-        )
-    if (p / LEDGER_DIR).is_dir():
-        return p.resolve()
-    if _under_ledger(p):
-        anc = next(a for a in (p, *p.parents) if a.name == LEDGER_DIR.name)
-        root = anc.parent
-        if anc is p:
-            what = f"指到了台账目录本身：{p}"
-            why = f"它的上一级 {root} 才是工作区根 —— 在它下面跑会再建出 {p / LEDGER_DIR}。"
-        else:
-            what = f"指到了台账目录里面：{p}"
-            why = f"它已经在 {anc} 这个台账目录底下 —— 工作区根是 {anc.parent}。"
-        raise Fail(
-            f"{source} {what}\n"
-            f"  {why}\n"
-            f"  处理：把 {source} 指到 {root}\n"
-            f"      例：progress.py list --repo {root}"
-        )
-    return p.resolve()
-
-
-def root_of(start: str | Path) -> Path | None:
-    """从 `start` 往上定位工作区根；找不到返回 None。
-
-    ① 自己在台账目录里（名字叫 `ledger`、且里面没有再套一层 `ledger/`）⇒ 根是它的上一级。
-       按位置判，不看里面有什么：项目根自带 `history/` + `worklog/` 不会被误当成台账目录。
-    ② 兜底：从**自己**开始往上，取最近的、直接含 `ledger/` 的目录。`start` 必须优先于
-       祖先，否则工作区根恰好叫 `ledger` 时会被父目录抢走（2026-10-25 改）。
-    """
-    here = Path(start).resolve()
-    for anc in (here, *here.parents):
-        if anc.name == LEDGER_DIR.name and not (anc / LEDGER_DIR).is_dir():
-            root = anc.parent
-            if (root / LEDGER_DIR).is_dir():
-                return root
-    for cand in (here, *here.parents):
-        if (cand / LEDGER_DIR).is_dir():
-            return cand
-    return None

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

@@ -1,103 +0,0 @@
-"""时间：本地墙钟 ↔ UTC 的换算、格式化、排序键。
-
-进门规则：不读文件、不写文件、不打印；只依赖 errors。
-所有**存盘**时间都是 UTC（`YYYY-MM-DD HH:MM:SS`，不带偏移量）；
-所有**对外输出**（人话表格与 `--json`）的时间字段都过 `fmt_local` 转本机时区，
-内部筛选 / 排序一律用存盘的 UTC —— 调用方拿到的时间不用再转。
-"""
-
-from __future__ import annotations
-
-import re
-from datetime import UTC, datetime
-
-from ..errors import Fail
-
-_UTC = UTC
-
-TIME_RE = re.compile(r"\d{4}-\d{2}-\d{2} \d{2}:\d{2}(?::\d{2})?\Z")
-_TIME_IN_RE = re.compile(
-    r"(\d{4})-(\d{1,2})-(\d{1,2})(?: +(\d{1,2}):(\d{1,2})(?::(\d{1,2}))?)?\Z"
-)
-
-
-def now() -> str:
-    """当前时刻（UTC，到秒）。"""
-    return datetime.now(_UTC).strftime("%Y-%m-%d %H:%M:%S")
-
-
-def normalize_time(
-    value: str | datetime,
-    *,
-    field: str = "时间",
-    tid: str | None = None,
-    date_only_ref: str | None = None,
-) -> str:
-    """把「正确但不完整」的写法归一化到 `YYYY-MM-DD HH:MM:SS`。
-
-    接受 `YYYY-MM-DD`、`YYYY-MM-DD HH:MM`、`YYYY-MM-DD HH:MM:SS`，容忍 `/` 与 `T`。
-    `date_only_ref`：只给了日期时用这个时刻顶替（`--until` 想含整天传 `23:59:59`）。
-    """
-    where = f"{tid}: " if tid else ""
-    if isinstance(value, datetime):
-        return value.strftime("%Y-%m-%d %H:%M:%S")
-    if not isinstance(value, str) or not value.strip():
-        raise Fail(f"{where}{field} 要是一个时间字符串，收到 {value!r}")
-    s = " ".join(
-        value.strip().replace("/", "-").replace("T", " ").replace("t", " ").split()
-    )
-    m = _TIME_IN_RE.fullmatch(s)
-    if not m:
-        raise Fail(
-            f"{where}{field} 时间格式不对：{value!r}"
-            "（可用 YYYY-MM-DD、YYYY-MM-DD HH:MM、YYYY-MM-DD HH:MM:SS）"
-        )
-    y, mo, d, hh, mm, ss = m.groups()
-    if date_only_ref is not None and hh is None:
-        out = f"{int(y):04d}-{int(mo):02d}-{int(d):02d} {date_only_ref}"
-    else:
-        out = (
-            f"{int(y):04d}-{int(mo):02d}-{int(d):02d} "
-            f"{int(hh or 0):02d}:{int(mm or 0):02d}:{int(ss or 0):02d}"
-        )
-    try:
-        datetime.strptime(out, "%Y-%m-%d %H:%M:%S")
-    except ValueError as exc:
-        raise Fail(f"{where}{field} 不是真实时间：{value!r}（{exc}）") from exc
-    return out
-
-
-def to_utc(
-    value: str,
-    *,
-    field: str,
-    tid: str | None = None,
-    date_only_ref: str | None = None,
-) -> str:
-    """用户按本地墙钟给的时间 → 存盘用的 UTC 串。只由外壳调用。"""
-    wall = normalize_time(value, field=field, tid=tid, date_only_ref=date_only_ref)
-    naive = datetime.strptime(wall, "%Y-%m-%d %H:%M:%S")
-    return naive.astimezone(_UTC).strftime("%Y-%m-%d %H:%M:%S")
-
-
-def fmt_local(stamp: object) -> str:
-    """存盘的 UTC → 查看者本地时间，只用于人看的输出。
-
-    存量老数据（2026-10-22 前写的是写入者本地时间、无标记）无法区分，
-    按 UTC 转会显示偏后若干小时 —— 这是已知例外，不在脚本里猜。
-    """
-    key = time_key(stamp)
-    if key is None:
-        return "" if stamp is None else str(stamp)
-    try:
-        dt = datetime.strptime(key, "%Y-%m-%d %H:%M:%S").replace(tzinfo=_UTC)
-    except ValueError:
-        return str(stamp)
-    return dt.astimezone().strftime("%Y-%m-%d %H:%M:%S")
-
-
-def time_key(value: object) -> str | None:
-    """已存时间（可能只到分）→ 秒精度串，用于比较/排序；不合法返回 None。"""
-    if not isinstance(value, str) or not TIME_RE.fullmatch(value):
-        return None
-    return value if len(value) == 19 else value + ":00"