dsh-task-ledger 0.0.111 → 0.0.112

package/dist/client.js

@@ -4883,8 +4883,8 @@ body[data-ds-dark-theme]{
 				onClick: onBack
 			}, `← ${t("backToConversation")}`), (0, react.createElement)("div", { style: titleStyle }, t("panelTitle"), (0, react.createElement)("span", {
 				style: buildTagStyle,
-				title: `v0.0.110 · 261027-190516-420`
-			}, `v0.0.110 261027-190516-420`))), (0, react.createElement)("div", { style: {
+				title: `v0.0.112 · 261028-073333-709`
+			}, `v0.0.112 261028-073333-709`))), (0, react.createElement)("div", { style: {
 				display: "flex",
 				alignItems: "center",
 				gap: "var(--dtl-space-2)"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dsh-task-ledger",
-	"version": "0.0.111",
+	"version": "0.0.112",
 	"description": "Task ledger board for dsh (DeepSeek Harness): read-only board over task-ledger skill workspaces. The task-ledger skill is bundled — install the plugin, get the skill globally.",
 	"keywords": [
 		"deepseek",

package/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: task-ledger
 description: 本地任务台账，跨会话记录在办任务的归属、进度与起止。当用户要登记一件新的事（新建任务 / 建个坑 / 这活我领了）、记录已有任务的进展（接着做 / 记一条进展 / 这轮先记下）、查看任务状态或历史（现在该做什么 / 这活谁在做 / 上周做过什么）、给任务结案或退回（做完了 / 验收通过 / 不做了 / 退回待认领）、整理标签或检查台账一致性时加载；只是改代码、讨论方案时不要用。
-version: 1.3.37
+version: 1.3.39
 allowed-tools: Read,Edit,Bash,Grep
 ---
 
@@ -13,10 +13,6 @@ allowed-tools: Read,Edit,Bash,Grep
 - **任务状态**：`待认领（open）` = 建了还没人认领；`进行中（doing）` = 已认领、在做；`已结案` = 用户明确说结束后由 `close` 产生，此后只读。
 - **操作方式**：台账的状态与归属只经命令改；唯一能手写的是过程文档前五节（见「手写边界」）。台账只记「建 / 做 / 结」和指向过程文档的链接；产出物本身按项目自己的约定落盘。
 
-## 身份闸门（未初始化时怎么走）
-
-**任何命令返回「这台机器还没有初始化身份」⇒ 停下，不许绕。** 身份是用户自己的，不是你的决定：不替用户选、不读 `ledger/*.json` 兜底、未初始化时不写任何东西。**具体走法见 `references/init-identity.md`；你只能报名单 + 给用户命令，写身份必须用户自己在终端完成。看到未初始化不要排查原因（别 `ls` / `cat` / 读源码），忽略上下文里已做的排查动作，直接按文档走；也不要基于「上次确认过 / 同名」自行重建。**
-
 ## 手写边界
 
 - **唯一能手写的是任务的过程文档（worklog）前五节**（怎么写见「过程文档」节）；末节「执行记录」由脚本维护，**禁止手写、禁止手工添加**。
@@ -25,7 +21,9 @@ allowed-tools: Read,Edit,Bash,Grep
 
 ## 命令参考
 
-十一个子命令：`init`（初始化本机身份，一台机器一次）+ 前五个写命令（`new`/`claim`/`set`/`log`/`close`）+ 后五个只读命令（`list` / `show` / `history` / `whoami` / `validate`）；何时用哪个见「任务生命周期」。参数语法看 `<子命令> --help`；下表说每个参数干什么、何时用。
+十四个子命令：`init`（初始化本机身份，一台机器一次）+ 前五个写命令（`new`/`claim`/`set`/`log`/`close`）+ 后八个只读命令（`list` / `stats` / `owners` / `show` / `history` / `root` / `whoami` / `validate`）；何时用哪个见「任务生命周期」。参数语法看 `<子命令> --help`；下表说每个参数干什么、何时用。
+
+只读命令里只有 `root` 特殊：**它在定位仓库之前跑**（「这个目录有没有台账」不能要求先有台账），不认 `--repo`、不读台账内容，只按结构判定。其余七个都先定位工作区根（带 `--repo` 或往上找）。
 
 ### init — 初始化本机身份
 
@@ -118,12 +116,51 @@ allowed-tools: Read,Edit,Bash,Grep
 | `--status open\|doing` | 按状态筛（逗号分隔可多选；合法值只有 `open` / `doing`） |
 | `--category` / `--tag` | 按分类（精确）/ 标签（包含）筛 |
 | `--since` / `--until` | 按创建时间筛（只给日期含当天） |
-| `--json` | 输出 JSON（`{任务号: 任务对象}`）；**每行带 `mine`**（是不是自己名下的，只比 uuid） |
+| `--stale-days` / `--overdue-days` / `--backlog-days` `<N>` | 覆盖年龄阈值（默认停滞 3 / 逾期 14 / 积压 30 天）；**可选**，不传就用内置默认 |
+| `--json` | 输出 JSON（`{任务号: 任务对象}`）；**每行带 `mine`**（是不是自己名下的，只比 uuid）和下面那六个年龄派生字段 |
 
 干什么：合并公共池 + 各人名下的任务，列出在办。**默认就是全量**，没有 `--all` 参数；收窄用 `--mine` / `--pool`。
 
+`--json` 的每行除台账原字段外，多给六个**只读派生值**（按任务算、不落盘，界面别自己再算一遍）：
+
+| 字段 | 含义 |
+|---|---|
+| `stale` | 停滞：进行中，最后更新至今 ≥ `--stale-days` 天（看 `updated`，缺则回退 `started` → `created`） |
+| `overdue` | 逾期：进行中，接任务至今 ≥ `--overdue-days` 天（看 `started`，缺则回退 `created`；中途更新不洗时钟） |
+| `backlog` | 积压：待认领，创建至今 ≥ `--backlog-days` 天 |
+| `age_days` / `idle_days` / `waiting_days` | 上面三个判据各自的天数（给悬停文案说人话用）；用不上的那个状态是 `null`（进行中没有 `waiting_days`，待认领没有 `age_days` / `idle_days`） |
+
+三个标记**互不覆盖**，一条可以同时中两个（进行中且既逾期又停滞）；老数据里的 `blocked` 一律按进行中判。时间取不到时天数是 `null`、标记是 `false` —— 不编造 0。人话表格里它们显示为行尾后缀（如 `… 发布流程走通 [停滞、逾期]`），不中的行不长这个尾巴。
+
+阈值 `<N>` 给 **0** 等于把这条判据关掉（只要有这个时间戳就算命中），一般不要这么传；给正整数才是「满 N 天」。
+
 举例：「现在该做什么」→ `list --mine`；「有哪些没人认领的」→ `list --pool`。
 
+### stats — 在办计数
+
+| 参数 | 含义 |
+|---|---|
+| `--mine` / `--pool` / `--owner <uuid>` / `--owner-name <片段>` | 与 `list` 完全同义（范围优先级也是 mine → pool → owner） |
+| `--status` / `--category` / `--tag` / `--since` / `--until` | 与 `list` 完全同义 |
+| `--stale-days` / `--overdue-days` / `--backlog-days` `<N>` | 同上，覆盖年龄阈值（可选） |
+| `--json` | 输出 JSON（各面计数 + 本次生效的阈值） |
+
+干什么：按**名义状态**（待认领 / 进行中）+ **年龄阈值**（停滞 / 逾期 / 积压）数出各面有多少条 —— 只数数、不吐行；要「一行一个任务」用 `list`。筛选与 `list` 同一套口径，不影响历史（范围只作用在办任务）。
+
+`--json` 的形状：`{"total","open","doing","stale","overdue","backlog","mine","my_doing","my_stale","my_overdue","oldest_open_days","thresholds"}`。`thresholds` 回显本次实际生效的三个阈值（`{"stale_days","overdue_days","backlog_days"}`）—— 界面文案照它显示，不要自己硬编码。`oldest_open_days` 是最老一条待认领躺了多少天（没有待认领是 `null`）。`mine` = 归我的在办，`my_doing` = 归我的进行中。
+
+举例：「我这有几条卡住了」→ `stats --mine`；「整体积压多严重」→ `stats --json`。
+
+### owners — 花名册
+
+| 参数 | 含义 |
+|---|---|
+| `--json` | `{"count","owners"}`：`owners` 是 `{uuid: {file, name, joined, mine}}` |
+
+干什么：把这个工作区里登记过的**所有人**都给出来（含当前没有任务的人），每条额外带 `mine`（是不是本机身份）。人选列表要列全时用它 —— 从 `list` 的在办任务里只能派生出「当前有任务的人」。
+
+举例：「筛人的下拉要列全」→ `owners --json`。
+
 ### show — 看一条任务
 
 | 参数 | 含义 |
@@ -152,6 +189,23 @@ allowed-tools: Read,Edit,Bash,Grep
 
 举例：「上周做过什么」→ `history --since <上周一日期>`；「今年都结掉哪些」→ `history --months 12`（超过 13 个月要分段查）。
 
+### root — 台账根检测
+
+| 参数 | 含义 |
+|---|---|
+| `--dir <目录>` | 检测哪个目录（不给 = 当前目录） |
+| `--json` | `{"dir","root","repo","ledger","reason"}` |
+
+干什么：回答「这个目录是不是已初始化的台账根」，**不读里面的台账文件** —— 判据只看结构：**直接含有 `ledger/` 就是根**（`ledger/` 本身与它下面的目录都不是），与脚本定位工作区根完全同一个口径，有没有 `pool.json` / `owners.json` 都不影响。
+
+- `root`（布尔）：这个是最终答案；
+- `repo`：顺带给出往上找到的工作区根（自己就是根时等于 `dir`，一个都没有时是 `null`）—— 拿到它就可以直接喂给其它命令的 `--repo`；
+- `reason`：一句人话说明（界面直接显示它）。
+
+它与 `whoami` 同类：**在定位仓库之前跑**，不认 `--repo`、不依赖身份、不报错退出（目录不存在也只是「不是根」，退 0）。
+
+举例：「这个目录有台账吗」→ `root --dir <候选目录> --json`。
+
 ### whoami — 我是谁
 
 | 参数 | 含义 |
@@ -159,9 +213,11 @@ allowed-tools: Read,Edit,Bash,Grep
 | （无） | 打印本机身份：`@名字　uuid` |
 | `--json` | `{"uuid","name"}`；**未初始化给双 null**（照常退 0，不是错误） |
 
-干什么：本机身份的只读查询，**不依赖 `--repo`、不写任何文件**，回答「这台机器上我是谁」。判断要不要引导用户 `init` 就看这条命令，别去解析 `~/.taskledger/identity.json`。
+干什么：本机身份的只读查询，**不依赖 `--repo`、不写任何文件**，回答「这台机器上我是谁」。需要自己的 uuid 时用它（转述给别人、核对 `list --owner` 的查询结果），别去解析 `~/.taskledger/identity.json`。
 
-举例：`whoami --json` 拿到 `uuid` 是 `null` ⇒ 这台机器还没初始化身份，先引导用户跑 `init`。
+**它不是执行前的检查项**：跑命令前不用先跑它探一次 —— 未初始化会在你真正要跑的那条命令上当场报「这台机器还没有初始化身份。」，那时再按「身份闸门」那条分支走。
+
+举例：「我的 uuid 是多少」→ `whoami --json`。
 
 ### validate — 台账体检
 
@@ -186,10 +242,21 @@ allowed-tools: Read,Edit,Bash,Grep
 
 - 定位项目：`--repo <工作区根>`（**直接含有 `ledger/` 的那个目录**）给了就校验后用；不给就从当前目录逐级向上找。`ledger/` 本身、以及它下面的任何子目录都不是根，指过去会被直接拒绝（判据只看位置，不看目录里有哪些文件 —— 项目根自带 `pool.json`、`history/`、`worklog/` 都不影响）。
 - `--no-sync`（放在子命令**前**）：用户明确要求「先别同步」时才用；之后自己 `git add ledger && commit && push`。
-- `--json` 只对只读命令（`list` / `show` / `history` / `whoami` / `validate`）有意义；写命令不接收 `--json`，传了是用法错。
+- `--json` 只对只读命令（`list` / `stats` / `owners` / `show` / `history` / `root` / `whoami` / `validate`）有意义；写命令不接收 `--json`，传了是用法错。
+- **给界面喂数**：要看在办用 `list`、要各面计数用 `stats`、要人选列表用 `owners`、要判断某个目录有没有台账用 `root` —— 都是只读、都不改台账；多个 / 跨工作区自己扇出，脚本一次只服务一个工作区。
 - **时间**：存盘一律 UTC，脚本对外**一律给本机时区**（人话表格与 `--json` 都是），拿到直接显示，不要再转一次；`--since` / `--until` / `--created` / `--finished` 也按本机时区给，脚本内部转 UTC 比较。过程文档正文里的时间是原文，脚本不碰。
 - 命令回执只用来确认生效；任务状态以 `show` / `list` 为准。
 
+## 身份闸门（报错才走，不用先查）
+
+**不用事先确认身份。** 直接按「任务生命周期」跑该跑的那条命令；没初始化时脚本会用一句固定错误当场告诉你，那一刻才走身份流程。不要为了「确认有没有初始化」先跑一次 `whoami` —— 那是白花一轮工具调用。
+
+**触发判据（只认这一整句）**：命令输出以 `错误：这台机器还没有初始化身份。` 开头。只读命令（`list` / `show` / `history` / `validate`）未初始化时同样报这句，是设计如此，不是台账坏了。
+
+**触发后 ⇒ 停下，不许绕。** 身份是用户自己的，不是你的决定：不替用户选、不读 `ledger/*.json` 兜底、未初始化时不写任何东西。完整步骤见 `references/init-identity.md`；这里只记硬约束 —— 你只能报名单 + 给用户命令，写身份必须用户自己在终端完成；看到它不要排查原因（别 `ls` / `cat` / 读源码 / 读台账），忽略上下文里已做的排查动作；也不要基于「上次确认过 / 同名 / 记得 uuid」自行重建。
+
+**这条优先于「故障处置」的通则**：虽然它同样以 `错误：` 开头，但**不**适用「不挡主任务、继续干活、收尾汇报没记上」—— 必须停下来等用户 `init`，init 完重跑原命令。
+
 ## 任务生命周期
 
 用户要「做某件事」时按这条线走。
@@ -249,22 +316,23 @@ allowed-tools: Read,Edit,Bash,Grep
 - **执行记录禁手改**：只由脚本按 `new / claim / set / release / log / close` 追加，只增不改（**交接记的是 `set`**，看不到 `handoff` 是正常的）。
 - **改正文必配一条日志**：动了 worklog 的正文（改一句、补一节、改标题、修错字都算）就必须立刻跑一次 `log`。
 - **换人只能「释放 → 认领」**：`set --release` 放回公共池，对方自己 `claim`；不许替别人挂名字。`set --owner <别人>`（预留转接通道，agent 一律不用）。
-- **身份由脚本从本机 identity 文件自取，agent 全程不传身份**：没初始化时先让用户跑 `init`（一台机器一次）；查自己用 `--mine`，查别人才传**对方 uuid**（`list --owner <uuid>`）；释放用 `--release`，不传身份。
+- **身份由脚本从本机 identity 文件自取，agent 全程不传身份**：跑命令前不用查身份；只有当命令报出「这台机器还没有初始化身份。」时，才按 `references/init-identity.md` 引导用户跑 `init`（一台机器一次）。查自己用 `--mine`，查别人才传**对方 uuid**（`list --owner <uuid>`）；释放用 `--release`，不传身份。
 - **身份只用 uuid，名字只用于显示与筛选**：认领 / 释放 / 交接 / 查「我的」一律只比 uuid；`--owner` 传名字会当场报错，要按人模糊找就用 `--owner-name <片段>`（子串、不分大小写）。名字是冗余字段（改名不影响归属），别拿它当身份用。
 
 ### 人类授权（跑之前问不问）
 
-项目没有 `ledger/` ⇒ 先问「要不要建个台账记这活？」，不许自建。用户同意 ⇒ 直接跑第一条写命令，且**必须带 `--repo <工作区根>`**（根是直接含有 `ledger/` 的那个目录，`ledger/` 本身不是根、指到它会被拒绝）：不带时脚本只从当前目录逐级往上找第一个含 `ledger/` 的目录，一个都没有就退 1 报「找不到台账」，绝不就地建；台账由这条写命令顺带建出来；但**必须先 `init` 过一次**（一台机器一次，写本机身份，与台账无关）——没 init 任何命令都会报「这台机器还没有初始化身份」。之后可以不带 `--repo`，但查找是**逐级往上**的 —— 在本项目的子目录里跑可能命中上层项目的台账，拿不准就一直带 `--repo <工作区根>`。
+项目没有 `ledger/` ⇒ 先问「要不要建个台账记这活？」，不许自建。用户同意 ⇒ 直接跑第一条写命令，且**必须带 `--repo <工作区根>`**（根是直接含有 `ledger/` 的那个目录，`ledger/` 本身不是根、指到它会被拒绝）：不带时脚本只从当前目录逐级往上找第一个含 `ledger/` 的目录，一个都没有就退 1 报「找不到台账」，绝不就地建；台账由这条写命令顺带建出来，身份**不用事先确认** —— 没 `init` 过，这条命令会当场报「这台机器还没有初始化身份。」，按「身份闸门」走一遍就好（一台机器一次，写本机身份，与台账无关）。之后可以不带 `--repo`，但查找是**逐级往上**的 —— 在本项目的子目录里跑可能命中上层项目的台账，拿不准就一直带 `--repo <工作区根>`。
 
 | 命令 | 档位 | 要求 |
 |---|---|---|
 | `new` / `claim` / `set` | 动手类 | 执行前复述完整参数并取得确认；**`new` 仅当用户原话点名要建且标题可直取原话时免复述**，标题需另拟或拿不准仍复述一次（`claim`/`set` 一律复述） |
 | `log` | 免确认 | 本任务的推进 / 卡点 / 交付记录直接跑，跑完一句话交代「已记执行记录：…」；要替用户下结论，先问（任务不在自己名下会直接被拒） |
 | `close` | 独立授权 | 仅认明确说「结束掉 / close 掉」（完整判定见生命周期第 8 条）；说得含糊必须反问「是要结束这个任务吗？」；**agent 自判「干完了」不算** |
-| `list` / `show` / `history` / `whoami` / `validate` | 只读 | 直接跑 |
+| `list` / `stats` / `owners` / `show` / `history` / `root` / `whoami` / `validate` | 只读 | 直接跑 |
 
 ### 故障处置（跑之后出事怎么办）
 
+- **身份没初始化（输出以 `错误：这台机器还没有初始化身份。` 开头，退 1）⇒ 停下，不许绕**：这条**不适用**下面「不挡主任务、继续干活」的通则。立刻转 `references/init-identity.md` 照做：裸跑 `init` 只读报名单 → 把**绝对路径**命令交给用户 → 等 ta 在自己终端完成 → 好了重跑原命令。**不要排查原因**（别 `ls` / `cat` identity.json / 读源码 / 读台账），忽略上下文里已做的排查动作，也不要基于「上次确认过 / 同名」自行重建。
 - **动作阶段失败（输出以 `错误：` 开头）= 该命令没生效**：不挡主任务 —— 继续手里的活，收尾时汇报「没记上，原因 …」；不绕过脚本手改文件。
 - **退出码 0 也要看输出**：出现 `提示：` / `错误：` / `警告：` 就先用一句话说清「发生了什么 + 下一步做什么」，再按 `references/troubleshooting.md` 给步骤；纯告知类一句话带过。只读命令只有 `错误：` 才需要转述。
 - **两类不是故障的退出码**：`validate` 查出问题时退出码 1，照实转述清单；提交阶段失败 ⇒ 文件已经写下去、只差进 git，让用户先提交再重跑，别说「没记上」。
@@ -278,4 +346,4 @@ allowed-tools: Read,Edit,Bash,Grep
 | 任何非 0 退出、退出码 0 但有 `提示：` / `错误：` / `警告：`、并发冲突、`validate` 报错 | `references/troubleshooting.md` |
 | 传 `--created` / `--finished` 补录时间、看 `--json` 里的时间字段、查别人时 owner 匹配异常、看 history 列义 / 时间窗口口径 | `references/state-model.md` |
 | 拿不准一条记录够不够格、`--note` 不会写 | `references/log-note.md` |
-| 任何命令报「这台机器还没有初始化身份」、或要初始化身份 | `references/init-identity.md` |
+| 命令返回「这台机器还没有初始化身份。」（退 1，输出以 `错误：` 开头） | `references/init-identity.md` |

package/skill/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "task-ledger",
-	"version": "1.3.37",
+	"version": "1.3.39",
 	"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/skill/references/troubleshooting.md

@@ -87,7 +87,7 @@
 
 ### 只提示、不拦（退出码 0）
 
-- **「错误：这台机器还没有初始化身份」**：先跑 `init`（一台机器一次），输入名字；没初始化任何命令都不执行。
+- **（「这台机器还没有初始化身份。」不在此列** —— 它是退 1 的硬拦，见「身份闸门」。）
 - **「提示：格式版本是 … 当前是 …；不拦，但字段可能有出入」**：数据是旧版本写的，功能照常；想统一就按提示升版本。
 - **「提示：写前把本地快进到 …（N 个提交，仅 fast-forward）」**：纯告知。
 - **「提示：写前快进到 … 没成功（工作树有未提交改动），改为只刷新本次要写的台账文件」**：没碍事，照写。
@@ -108,7 +108,7 @@ notices（只提示）：历史解析警告、历史有结案行但任务还在
 
 ## 读命令只读本地（跨机器要先取最新）
 
-- **读命令（`list` / `show` / `history` / `whoami` / `validate`）不会自动 `git pull`**：看到的是**这台机器上一次同步后的**台账（`whoami` 连台账都不读，只看本机身份）。
+- **读命令（`list` / `stats` / `owners` / `show` / `history` / `whoami` / `validate`）不会自动 `git pull`**：看到的是**这台机器上一次同步后的**台账（`whoami` 连台账都不读，只看本机身份；`root` 连台账数据都不读，只看目录结构）。
 - 想看别的机器刚写的东西：先 `git pull`，或者跑任意一条写命令（写命令进入时会先取最新）。
 
 ## 写前取最新与写后同步（机制）