task-ledger 1.3.5 → 1.3.6

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: task-ledger
 description: 本地任务台账，跨会话记录在办任务的归属、进度与起止。当用户要登记一件新的事（新建任务 / 建个坑 / 这活我领了）、记录已有任务的进展（接着做 / 记一条进展 / 这轮先记下）、查看任务状态或历史（现在该做什么 / 这活谁在做 / 上周做过什么）、给任务结案或退回（做完了 / 验收通过 / 不做了 / 退回待认领）、整理标签或检查台账一致性时加载；只是改代码、讨论方案时不要用。
-version: 1.3.5
+version: 1.3.6
 allowed-tools: Read,Edit,Bash,Grep
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "task-ledger",
-	"version": "1.3.5",
+	"version": "1.3.6",
 	"description": "Task-ledger skill for coding agents: per-workspace progress tracking (ledger/pool.json + owners/<hash>.json shards + owners.json index, history, worklog) driven by a CLI script. Standalone install for CodeBuddy and other agents; also bundled inside the dsh-task-ledger DSH plugin.",
 	"keywords": [
 		"skill",

package/references/state-model.md

@@ -25,8 +25,8 @@ close             → 历史层 + 封卷 + 移出自己名下
   - 注意：任务号前缀与 worklog 月份目录按 **UTC** 推 —— UTC+8 下裸日期 `--created 2026-01-05` 存成 `2026-01-04 16:00:00`，任务号前缀变成 `20260104-1600`；临午夜补录要连时间一起传。
 - **筛选语义**：`list` 的 `--since` / `--until` 按**创建时间**；`history` 的按**结案时间**（历史文件按结案月归档，按创建时间比较会漏「上月建、本月结」的记录）。只给日期时起 = 当天 `00:00:00`、止 = 当天 `23:59:59`（含当天）。
 - **时区**：存盘为 UTC 的只有 —— 任务号、worklog 目录 / 文件名、台账 JSON 的 `created`/`started`/`updated`/`finished`、history 行、worklog 头部「创建」行。**执行记录行、封卷行、`list` / `history` 的人话输出都是本机本地时间**（给人看的日志行）；`--json` 原样给 UTC，由消费方自己转。存量老数据（2026-10-22 前）写的是写入者本地时间、无标记，无法与 UTC 区分。
-- **history 文件 9 列**：结案时间 / 创建时间 / 工作包（= `new --title` 的任务标题）/ 分类 / 标签 / owner / creator / 摘要 / 过程文档；排序与 `--since` / `--until` 按**结案时间**。（`history` 命令的人话输出只展示其中几列：结案时间、负责人、标题。）
-- **owner / creator 两列存的是 uuid**（与任务里一致，身份只认 uuid）；人话输出与 `--json` 里的 `owner_name` / `creator_name` 是读的时候按 `owners.json` 名册现查补上的显示名，不落盘。名册里查不到就退回裸 uuid。
+- **history 文件 11 列**：结案时间 / 创建时间 / 工作包（= `new --title` 的任务标题）/ 分类 / 标签 / owner / owner_name / creator / creator_name / 摘要 / 过程文档；排序与 `--since` / `--until` 按**结案时间**。（`history` 命令的人话输出只展示其中几列：结案时间、负责人、标题。）
+- **owner / creator 两列存的是 uuid**（与任务里一致，身份只认 uuid）；紧随其后的 `owner_name` / `creator_name` 两列**落盘**结案那一刻的显示名 —— 改名不回写旧行，看历史看到的就是当时那个名字。老行（升级前落的）没有名字时按名册兜底补一次展示值，**不回写文件**。
 
 ## 任务号
 
@@ -42,7 +42,7 @@ close             → 历史层 + 封卷 + 移出自己名下
 
 ## 历史层
 
-- 按**结案时间**分月存放，9 列（creator 在 owner 之后）；`close` 从任务直写分类 / 标签终值。
+- 按**结案时间**分月存放，11 列（列序：owner 之后是 `owner_name`，再是 creator、`creator_name`）；`close` 从任务直写分类 / 标签终值。
 - 存量平铺历史文件只读兼容、永不重写；`history` 连同它在内、按下面的月份区间合并。
 - **查询区间**：`history` 先由时间参数算出要读的月份文件，再逐个「存在才读、缺月跳过」，不扫磁盘。无时间参数默认最近 3 个自然月；`--months N`（近 N 月）与 `--since/--until`（结案时间闭区间）二选一；一次最多读 13 个历史文件（按月分文件，不区分连续/分散，只数总数），超出直接报错、不读任何文件。末列文档链接只按**文件名**消费（取 basename），链接里的 `../worklog/<年月>/` 前缀只为阅读器跳转服务，解析时忽略。
-- `history --json` 直接按文件现状解析，旧行没有的列不编造；`close` 追加历史行时才会把旧行升级补上 creator。
+- `history --json` 直接按文件现状解析，旧行没有的列不编造（名字列为空就按名册补展示值，不回写）；存量九列的历史文件按 `docs/history-creator-upgrade.md` 一次性升级，脚本不认旧列数。

package/scripts/ledgerkit/actions/claim.py

@@ -72,7 +72,7 @@ def claim(repo: Path, me: Identity, tid: str) -> Result:
     logs = WorklogStore(repo)
     path = logs.find(tid, moved.get("worklog"))
     if path is not None:
-        logs.append_exec(path, exec_line(now(), me.label(), "claim", "认领 → doing"))
+        logs.append_exec(path, exec_line(now(), me.stamp(), "claim", "认领 → doing"))
         note = None
     return Result(
         changed=("owner", "started", "updated"),

package/scripts/ledgerkit/actions/close_task.py

@@ -95,9 +95,9 @@ def close_task(
             if doc_path is not None:
                 text = logs.read(doc_path)
                 if not has_frozen_line(text):
-                    frozen = stamp_frozen(text, finished, me.label())
+                    frozen = stamp_frozen(text, finished, me.stamp())
                     frozen = append_exec_log(
-                        frozen, exec_line(finished, me.label(), "close", "结案封卷")
+                        frozen, exec_line(finished, me.stamp(), "close", "结案封卷")
                     )
                     logs.write(doc_path, frozen)
                     notes.append("补齐上次未完成的封卷。")
@@ -138,10 +138,14 @@ def close_task(
                 "title": task.get("title") or "",
                 "category": final_category,
                 "tags": final_tags,
-                # 历史两列只存 **uuid**（身份唯一键）；显示名在读的时候按名册换，
-                # 不落盘 —— 否则 `history --owner <uuid>` / `--mine` 永远比不到东西。
+                # 历史里 uuid 与名字**都落盘**：uuid 是判定键（`@` + 裸 uuid，
+                # `--owner` / `--mine` 比它），名字是**结案那一刻的快照** —— 之后改名
+                # 不回写旧行，看历史看到的就是当时那个名字。
+                # 取值优先用任务行里认领 / 建任务时写下的那份；老任务没有就留空，不编造。
                 "owner": me.uuid,
+                "owner_name": task.get("owner_name") or me.name,
                 "creator": task.get("creator") or me.uuid,
+                "creator_name": task.get("creator_name"),
                 "summary": text_summary,
                 "worklog": task.get("worklog") if doc_path else None,
             },
@@ -152,9 +156,9 @@ def close_task(
         if doc_path is not None:
             text = logs.read(doc_path)
             if not has_frozen_line(text):
-                frozen = stamp_frozen(text, finished, me.label())
+                frozen = stamp_frozen(text, finished, me.stamp())
                 frozen = append_exec_log(
-                    frozen, exec_line(finished, me.label(), "close", "结案封卷")
+                    frozen, exec_line(finished, me.stamp(), "close", "结案封卷")
                 )
                 logs.write(doc_path, frozen)
 

package/scripts/ledgerkit/actions/handoff.py

@@ -39,7 +39,9 @@ def handoff(repo: Path, me: Identity, tid: str, *, to: str) -> Result:
             "  处理：跑 validate 看台账是不是脏了。"
         )
     to_name = str(record.get("name") or "") or None  # 只用于显示
-    who = to_name or to_key
+    who = to_name or to_key  # 给人看：命令输出、提示语
+    # 落盘用「名字 · uuid」：接收人拿什么键去分片里找，比执行者更需要 uuid
+    who_stamp = Identity(uuid=to_key, name=to_name or "").stamp()
     to_store = TaskStore(repo, shard_rel(to_key))
     moved = dict(task)
     moved["owner"] = to_key
@@ -58,7 +60,8 @@ def handoff(repo: Path, me: Identity, tid: str, *, to: str) -> Result:
         path = logs.find(tid, moved.get("worklog"))
         if path is not None:
             logs.append_exec(
-                path, exec_line(now(), me.label(), "set", f"交接给 {who}（补齐）")
+                path,
+                exec_line(now(), me.stamp(), "set", f"交接给 @{who_stamp}（补齐）"),
             )
         return Result(
             already_done=True,
@@ -76,7 +79,9 @@ def handoff(repo: Path, me: Identity, tid: str, *, to: str) -> Result:
     if path is None:
         note = f"任务 {tid} 已交给 {who}，但过程文档没找到，跳过执行记录。"
     else:
-        logs.append_exec(path, exec_line(now(), me.label(), "set", f"交接给 {who}"))
+        logs.append_exec(
+            path, exec_line(now(), me.stamp(), "set", f"交接给 @{who_stamp}")
+        )
     return Result(
         changed=("owner", "owner_name", "updated"),
         where=rel(repo, to_store.path),

package/scripts/ledgerkit/actions/log_progress.py

@@ -46,7 +46,7 @@ def log_progress(repo: Path, me: Identity, tid: str, note: str) -> Result:
                 "提示：这条任务没有过程文档，已跳过执行记录（分片的最后更新已刷）。",
             ),
         )
-    ok = logs.append_exec(path, exec_line(now(), me.label(), "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

@@ -99,11 +99,11 @@ def new_task(
             tid=tid,
             title=clean_title,
             created=created,
-            creator=me.label(),
+            creator=me.stamp(),
             category=category,
             tags=tag_list,
             first_exec=exec_line(
-                created, me.label(), "new", "创建任务并认领" if mine else "创建任务"
+                created, me.stamp(), "new", "创建任务并认领" if mine else "创建任务"
             ),
         )
         target.put(tid, task)

package/scripts/ledgerkit/actions/query_history.py

@@ -143,16 +143,23 @@ def query_history(repo: Path, me: Identity, q: HistoryQuery) -> HistoryResult:
         key = normalize(q.owner)
         records = [r for r in records if normalize(r.get("owner") or "") == key]
     if q.owner_name:
-        # 名字只在名册里模糊匹配出 uuid 集合，命中判定仍比 uuid
-        keys_of_name = index.keys_of_name(q.owner_name)
+        # 名字已经落在历史行里 ⇒ 直接比它（子串、不分大小写）。落的是**当时**那个名字，
+        # 改名后的旧行仍留旧名 ⇒ 按新名筛不到旧行，这是快照语义，不是漏。
+        # 老行（升级前落的）没有名字列，退回按 uuid 片段比，不至于一条都筛不出来。
+        needle = q.owner_name.strip().lower()
         records = [
-            r for r in records if normalize(r.get("owner") or "") in keys_of_name
+            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`）只在这层补上，不落盘：
-    # 历史文件里 owner / creator 两列存的一律是 uuid，读出来给人看时才换成名字。
+    # 名字**已经落盘**（`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:

package/scripts/ledgerkit/actions/release.py

@@ -63,7 +63,7 @@ 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.label(), "release", "释放回公共池"))
+        logs.append_exec(path, exec_line(now(), me.stamp(), "release", "释放回公共池"))
     return Result(
         changed=("owner", "owner_name", "status", "updated"),
         where=rel(repo, pool.path),

package/scripts/ledgerkit/core/history_md.py

@@ -1,6 +1,7 @@
-"""历史表格的文本操作：拼九列一行、解析九列一行。
+"""历史表格的文本操作：拼十一列一行、解析十一列一行。
 
-**只认九列这一种格式**（开发期没发布，不做任何旧列数 / 旧列语义的迁移）。
+**只认十一列这一种格式**：存量九列的文件按 `docs/history-creator-upgrade.md`
+那份手册一次性升级，脚本不做运行时迁移。
 """
 
 from __future__ import annotations
@@ -13,8 +14,11 @@ 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 = "|---|---|---|---|---|---|---|---|---|---|---|"
 
 _LINK_RE = re.compile(r"\[[^\]]*\]\(([^)]*)\)")
 _TAG_SPLIT_RE = re.compile(r"[,，、]")
@@ -65,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 传**裸 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 "")
@@ -76,16 +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 parse_history(text: str) -> tuple[list[Row], list[str]]:
-    """解析九列历史表 → (records, warnings)。坏行（列数不对 / 时间列不合法）跳过并警告。
+    """解析十一列历史表 → (records, warnings)。坏行（列数不对 / 时间列不合法）跳过并警告。
 
-    返回的键：finished / created / title / category / tags / owner / creator / summary /
-    worklog / fmt / line。owner 与 creator 一律**剥掉 `@`**（存储值是裸 uuid）。
+    返回的键：finished / created / title / category / tags / owner / owner_name /
+    creator / creator_name / summary / worklog / fmt / line。owner 与 creator 一律
+    **剥掉 `@`**（存储值是裸 uuid）；两个名字列是**原值**（落盘快照，可能为空）。
     """
     records: list[Row] = []
     warnings: list[str] = []
@@ -95,12 +105,22 @@ 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
-        if len(cells) != 9:
-            warnings.append(f"第 {lineno} 行不是九列（历史表只认九列），已跳过")
+        if len(cells) != 11:
+            warnings.append(f"第 {lineno} 行不是十一列（历史表只认十一列），已跳过")
             continue
-        finished, created, title, category, tag_cell, owner, creator, summary, doc = (
-            cells
-        )
+        (
+            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
@@ -115,10 +135,12 @@ def parse_history(text: str) -> tuple[list[Row], list[str]]:
                     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": (m.group(1) if m else doc.strip()) or None,
-                "fmt": "v9",
+                "fmt": "v11",
                 "line": lineno,
             }
         )

package/scripts/ledgerkit/core/identity.py

@@ -21,9 +21,23 @@ class Identity:
     name: str = ""
 
     def label(self) -> str:
-        """显示名：没名字就用 uuid 前 8 位。"""
+        """显示名：没名字就用 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:
     """归一化：去首尾空白 + 转小写。全仓只此一处。"""

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

package/scripts/ledgerkit/store/history_store.py

@@ -99,9 +99,11 @@ class HistoryStore:
             row.get("owner"),
             row.get("summary") or "",
             row.get("worklog"),
-            row.get("category"),
-            row.get("tags"),
-            row.get("creator"),
+            category=row.get("category"),
+            tags=row.get("tags"),
+            creator=row.get("creator"),
+            owner_name=row.get("owner_name"),
+            creator_name=row.get("creator_name"),
         )
         return {"text": _append_line(text, line), "duplicate": duplicate}
 
@@ -117,7 +119,7 @@ def _name_of(worklog: str | None) -> str | None:
 
 
 def _fresh_table() -> str:
-    """当月第一次结案：按九列表头起表（表头的真源只有 `history_md` 一处）。"""
+    """当月第一次结案：按十一列表头起表（表头的真源只有 `history_md` 一处）。"""
     return (
         f"{history_md.HISTORY_TITLE}\n\n"
         f"{history_md.HISTORY_HEADER}\n{history_md.HISTORY_SEP}\n"