dsh-task-ledger 0.0.131 → 0.0.132

package/dist/index.d.ts

@@ -1,4 +1,19 @@
 export declare const name = "dsh-task-ledger";
+/**
+ * 插件配置 schema —— 插件详情页配置区的唯一来源（dsh 0.1.7+：settings 服务按活跃
+ * entry 的 `Config` 派生表单，命名空间 = `cordis.patch.yml` 那条 insert 的 id = 包名）。
+ *
+ * · 只有 `.volatile()` 字段会进表单，且由宿主**原位热更新 + 持久化**（写到 profile
+ *   patch 文档）；插件不自己落盘、不碰 localStorage。
+ * · `entryMode`：`first` = 左侧第一级（默认，= 既有位置）/ `more` = 「更多」菜单。
+ * · `displayName`：空串 = 用词典里的默认名（见 client/locales.ts 的 `panelTitle`）。
+ *
+ * 刻意不带 `z<Config>` 类型标注：`.volatile()` 改变推导类型，带上反而 TS2322。
+ */
+export declare const Config: import("@deepseek-ai/schemastery").Schema<{
+    entryMode: string;
+    displayName: string;
+}> | undefined;
 /** 插件上下文的最小面（结构声明，不 import 官方包）。 */
 interface PluginContext {
     inject(deps: readonly string[], callback: (ctx: Record<string, unknown>) => void): void;

package/dist/index.js

@@ -2,8 +2,9 @@
  * dsh-task-ledger host 半入口：装配层，不写业务逻辑。
  *
  * 已落地：数据面路由（任务 3，routes.ts）、内嵌 skill 全局注册（任务 2，
- * skill-registration.ts）。入口 / 图标 / 设置页（任务 1）与按钮会话交接
- * （任务 4）各自落地时再往本文件加装配，业务逻辑一律进 host/ 对应文件。
+ * skill-registration.ts）、插件配置 schema（`Config`，宿主托管的设置区）、
+ * 只读文件路由。按钮会话交接（任务 4）落地时再往本文件加装配，业务逻辑一律进
+ * host/ 对应文件。
  *
  * 服务等待写在 apply 内的 ctx.inject（参考插件真机教训：顶层 inject 声明组合
  * 满足不了的依赖会令 entry 一直 pending、卡死整个 dsh 启动）；两条注入线
@@ -13,6 +14,40 @@ import { serveFsRoute } from "dsh-plugin-core/host";
 import { FS_ROUTE, registerRoutes } from "./host/routes.js";
 import { buildSkillRegistration, } from "./host/skill/registration.js";
 export const name = "dsh-task-ledger";
+/**
+ * 取官方 schema 库。**动态 import + 兜底**而不是静态 import：静态 import 一旦解析不到，
+ * 整个 server entry 加载失败，插件管理页把它标成「异常」——连侧栏与整页一起没了
+ * （dsh-plugin-core demo 2026-10-25 真机事故的同一坑）。退化成 undefined 的代价只是
+ * 「详情页没有配置区」，入口照常可用。
+ */
+async function loadSchemastery() {
+    try {
+        return (await import("@deepseek-ai/schemastery")).default;
+    }
+    catch {
+        return undefined;
+    }
+}
+const z = await loadSchemastery();
+if (z === undefined)
+    console.warn("[task-ledger] @deepseek-ai/schemastery 解析失败：插件详情页没有配置区（侧栏入口与看板不受影响）");
+/**
+ * 插件配置 schema —— 插件详情页配置区的唯一来源（dsh 0.1.7+：settings 服务按活跃
+ * entry 的 `Config` 派生表单，命名空间 = `cordis.patch.yml` 那条 insert 的 id = 包名）。
+ *
+ * · 只有 `.volatile()` 字段会进表单，且由宿主**原位热更新 + 持久化**（写到 profile
+ *   patch 文档）；插件不自己落盘、不碰 localStorage。
+ * · `entryMode`：`first` = 左侧第一级（默认，= 既有位置）/ `more` = 「更多」菜单。
+ * · `displayName`：空串 = 用词典里的默认名（见 client/locales.ts 的 `panelTitle`）。
+ *
+ * 刻意不带 `z<Config>` 类型标注：`.volatile()` 改变推导类型，带上反而 TS2322。
+ */
+export const Config = z === undefined
+    ? undefined
+    : z.object({
+        entryMode: z.string().default("first").volatile(),
+        displayName: z.string().default("").volatile(),
+    });
 /**
  * 「继续」用的宿主服务读取器：**现取、不预先注入**。
  *

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+	"meta": {
+		"title": "Whale Ledger (dsh-task-ledger)",
+		"description": "Tasks are created, claimed, advanced and closed by the agent and written straight into a plain-text ledger in the workspace, so the owner, the current state and the next step are always on record. It is not limited to development work — research, documentation, presentations and video production all fit. No cloud service is involved: everything is managed locally. Single-user and multi-user both work, with Git synchronisation, and every action is on record. The control panel summarises in-flight, overdue and stalled work with weekly trends."
+	}
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+	"meta": {
+		"title": "蓝鲸任务台账(dsh-task-ledger)",
+		"description": "建任务、认领、记进展、结案均由 Agent 主动写入工作区的纯文本台账，负责人、当前进度与下一步随时可查；不限于开发工作，调研、文档、演示、视频制作等均可建立任务。无需云服务，纯本地管理。单人、多人均可使用，支持 Git 同步，各项操作均有记录；控制面板汇总在办、逾期、停滞与按周趋势。"
+	}
+}

package/package.json

@@ -1,7 +1,8 @@
 {
 	"name": "dsh-task-ledger",
-	"version": "0.0.131",
-	"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.",
+	"version": "0.0.132",
+	"description": "Tasks are created, claimed, advanced and closed by the agent and written straight into a plain-text ledger in the workspace, so the owner, the current state and the next step are always on record. It is not limited to development work — research, documentation, presentations and video production all fit. No cloud service is involved: everything is managed locally. Single-user and multi-user both work, with Git synchronisation, and every action is on record. The control panel summarises in-flight, overdue and stalled work with weekly trends.",
+	"icon": "./assets/icon.svg",
 	"keywords": [
 		"deepseek",
 		"harness",
@@ -15,11 +16,14 @@
 	"exports": {
 		".": "./dist/index.js",
 		"./client": "./dist/client.js",
+		"./locale/*.json": "./locale/*.json",
 		"./package.json": "./package.json"
 	},
 	"files": [
 		"dist",
 		"skill",
+		"assets",
+		"locale",
 		"cordis.patch.yml",
 		"README.md"
 	],
@@ -52,11 +56,15 @@
 			"inject": [
 				"@deepseek-ai/dsh-client-locale",
 				"@deepseek-ai/dsh-client-ui-renderer",
-				"@deepseek-ai/dsh-client-ui-layout"
+				"@deepseek-ai/dsh-client-ui-layout",
+				"@deepseek-ai/dsh-client-ui-settings",
+				"@deepseek-ai/dsh-client-ui-plugin-manager",
+				"@deepseek-ai/dsh-client-ui-sidebar"
 			]
 		}
 	},
 	"dependencies": {
-		"dsh-plugin-core": "^0.30.2"
+		"@deepseek-ai/schemastery": "^3.18.5",
+		"dsh-plugin-core": "^0.33.2"
 	}
 }

package/skill/README.md

@@ -1,53 +1,145 @@
 # task-ledger
 
-> 给人看的概览与索引。给 agent 的执行说明在 `SKILL.md`（每次会话整份注入），两者不重复；本文件不进 agent 上下文、不占 token。
+**English** · [简体中文](https://github.com/cq-guojia/dsh-task-ledger/blob/main/packages/skill/README.zh-CN.md)
 
-## 它做什么
+A task ledger for AI coding agents. The agent records what it is working on — who owns it, how far it has got, when it was opened and when it was closed — as plain text inside the repository, so the answer survives the end of the conversation.
 
-管一个工作区 / 项目的任务进度（开发活、琐事、调研、备忘都算），一共三件东西：
+The package is a skill: a `SKILL.md` file, a prebuilt command-line tool, and reference material. It runs on any agent that loads the open `SKILL.md` format: Claude Code, Cursor, Codex, CodeBuddy, WorkBuddy, Trae, Doubao Work and others.
 
-- **谁在做、做到哪**：状态只在台账 JSON —— `ledger/pool.json`（公共池）+ 每人一份 `ledger/owners/<hash>.json` 分片，索引 `ledger/owners.json`。
-- **过程正文**：全在 `ledger/worklog/<年月>/<月日>-<时分>-<说明>-<码>.md`（六节），agent 直接编辑前五节，末节「执行记录」只由脚本写。
-- **已结案**：一行一条在 `ledger/history/<年月>.md`（16 列），只由脚本写。
+Four properties define it:
 
-状态改动与正文重写分开、全部经脚本改 —— 不另建副本、不手改状态表和历史。覆盖动作：建任务、认领、释放、结案、查在办、查历史、标签归并、体检。
+| Property | What it means |
+|---|---|
+| **Task lifecycle tracking** | Tasks are created, claimed, resumed, handed over and closed. Every transition carries a timestamp and an owner; progress, the conclusion and open issues are written into the task document. |
+| **Local by design** | No account, no hosted backend, no service marketplace. The ledger is JSON and Markdown committed with the repository; it works offline and is reviewable in a pull request. |
+| **Single-user and multi-user** | One person on one machine, or a team sharing one repository. Ownership state is sharded per person, so concurrent work never writes the same file. |
+| **Version control as the sync layer** | Git is the transport. Push, pull and merge carry the ledger between machines and contributors. |
 
-## 文件布局（脚本只写这些）
+![Task document](https://raw.githubusercontent.com/cq-guojia/dsh-task-ledger/main/assets/screenshots/worklog.png)
 
-| 文件 | 装什么 |
-|---|---|
-| `ledger/pool.json` | 公共池：未认领任务（owner 空） |
-| `ledger/owners.json` | 索引：身份 uuid → 分片文件（`name` 只做显示 / 模糊筛） |
-| `ledger/owners/<hash>.json` | 每人一份分片：自己认领的任务 |
-| `ledger/worklog/<年月>/*.md` | 任务正文（六节） |
-| `ledger/history/<年月>.md` | 已结案（一行一条，16 列） |
+## Install
+
+### With a skill manager
 
-## 为什么这么设计
+The [skills CLI](https://skills.sh) (Vercel) detects the agents installed on the machine, writes the skill into the right directory for each, and can update it later:
 
-跨项目固定用 `ledger/`（不占项目的 `docs/`）；状态用 JSON 而非 Markdown（改动面最小）；状态与过程正文分离（互不踩）；一人一份分片把并发冲突面从整份文件缩到公共池里几行；**所有存盘时间（含过程文档里的日志行）一律 UTC**，脚本输出时统一转本机时区（人话与 `--json` 一致）。
+```bash
+npx skills add https://github.com/cq-guojia/dsh-task-ledger/tree/main/packages/skill
+```
 
-## 怎么用（执行规则在 SKILL.md）
+The path is part of the command: this repository is a monorepo holding two copies of the skill, and `packages/skill` selects the source. Add `-g` to install for every project rather than the current one, and `--agent` to restrict the targets.
 
-直接跑：
+[SkillHub](https://skillhub.cn) — the market behind CodeBuddy and WorkBuddy — installs a skill once it is listed there. When search does not find `task-ledger`, use the client's local import and point it at `packages/skill`, or add this repository as a GitHub source in the SkillHub desktop application.
+
+### Manually
+
+Installing means copying the skill directory into the directory your agent reads. Fetch the source once:
 
 ```bash
-<SKILL.md 所在目录>/scripts/progress <子命令> --repo <工作区根>
+git clone --depth 1 https://github.com/cq-guojia/dsh-task-ledger.git /tmp/task-ledger-src
 ```
 
-`scripts/progress` 按平台 exec `scripts/bin/ledger-<os>-<arch>`（静态二进制；已带 linux/amd64、darwin/arm64 与 windows/amd64）。
+Then copy it for the agent you use. User-level paths apply to every project; project-level paths apply to one repository and can be committed, which is how a team shares one skill.
+
+| Agent | User-level directory | Command |
+|---|---|---|
+| **Claude Code** | `~/.claude/skills/` | `mkdir -p ~/.claude/skills && cp -R /tmp/task-ledger-src/packages/skill ~/.claude/skills/task-ledger` |
+| **Cursor** | `~/.cursor/skills/` | `mkdir -p ~/.cursor/skills && cp -R /tmp/task-ledger-src/packages/skill ~/.cursor/skills/task-ledger` |
+| **Codex CLI** | `~/.codex/skills/` | `mkdir -p ~/.codex/skills && cp -R /tmp/task-ledger-src/packages/skill ~/.codex/skills/task-ledger` |
+| **CodeBuddy** | `~/.codebuddy/skills/` | `mkdir -p ~/.codebuddy/skills && cp -R /tmp/task-ledger-src/packages/skill ~/.codebuddy/skills/task-ledger` |
+| **WorkBuddy** | `~/.workbuddy/skills/` | `mkdir -p ~/.workbuddy/skills && cp -R /tmp/task-ledger-src/packages/skill ~/.workbuddy/skills/task-ledger` |
+| **Trae** | `~/.trae/skills/` (Trae CN: `~/.trae-cn/skills/`) | `mkdir -p ~/.trae/skills && cp -R /tmp/task-ledger-src/packages/skill ~/.trae/skills/task-ledger` |
+
+**Project-level installation.** The same copy works inside a repository: `.claude/skills/`, `.cursor/skills/`, `.codebuddy/skills/`, `.trae/skills/`, or `.agents/skills/` — the cross-agent convention read by Codex and Cursor. Committed alongside the code, it gives every contributor the same instructions.
+
+**Doubao Work (豆包工作).** Import the folder from the application: open the sidebar, choose Skills, and import `packages/skill` as a local skill. The application does not document a user-level skills directory, so in-app import is the supported route.
+
+**Other agents.** Place the directory under `.agents/skills/task-ledger/`, or wherever the agent scans for `SKILL.md`. Nothing in the package depends on the host: the CLI is a static binary, the content is Markdown.
+
+**Windows.** Substitute `%USERPROFILE%\` for `~`. The CLI ships binaries for Linux (amd64), macOS (arm64) and Windows (amd64); the wrapper script selects the right one.
+
+## First run
+
+Once per machine, initialise the identity that signs every ledger entry. The step is interactive and must be run by you — the agent is not allowed to create or rewrite an identity on your behalf:
+
+```bash
+~/.claude/skills/task-ledger/scripts/progress init --new --name "Your Name"
+```
 
-**不需要安装任何东西**：直接执行上面那个路径就行。它是个 `sh` 脚本——若某个安装环节丢了可执行位（报 `Permission denied`），前面加 `sh ` 照样能跑：`sh <SKILL.md 所在目录>/scripts/progress <子命令> --repo <工作区根>`。
+On a second machine, run `init` without arguments and claim the identity already present in the ledger roster, so that both machines write under the same account.
 
-子命令：`new` `claim` `set` `log` `close` `delete` `list` `history` `show` `whoami` `validate`。命令参考（参数 / 一句话 / 举例）、任务生命周期、纪律（数据完整性 / 人类授权 / 故障处置）全在 `SKILL.md`；参数细节看 `<子命令> --help`（不要凭记忆编）。
+No runtime, package manager or network access is required afterwards.
 
-## 深入参考（references/，按需读）
+## Using it
 
-| 文件 | 看什么 |
+There are no commands for you to type. The ledger is driven by what you say to the agent: when a request matches one of the intents below, the agent runs the corresponding operation and records it.
+
+| You say | What the agent does | Result |
+|---|---|---|
+| "Open a task: get the release pipeline working" | creates the task with the tags you gave | In the shared pool, state `open`, unclaimed |
+| "Open a task and start on it" | creates and claims it | Owned by you, state `doing` |
+| "I'll take that one" / "continue with X" | claims the task | Moved to your name, state `doing` |
+| *(while working)* | writes the task document, then appends an execution record | Progress, conclusions and blockers on record |
+| "Blocked for now" / "leave it for a while" | records the blocker, leaves the state alone | Still `doing` — a pause is neither a release nor a cancellation |
+| "Hand it back" | releases it | Returns to the shared pool for anyone to claim |
+| "Close this task" | closes it with your summary | One row written to history; read-only afterwards |
+| "Cancel it" | closes it as void, with the reason | Closed, not completed |
+| "Delete it" | asks you to confirm, then deletes | Removed permanently — no undo, no restore |
+| "What should I be doing?" / "what did we close last week?" | lists in-flight tasks, one task, or history | Query only, nothing written |
+
+Creating a task requires two inputs: **what the work is** — one sentence, without category or project prefixes — and **what it touches** — one to five tags. A category may be given at creation; it is immutable afterwards.
+
+Four rules bind the agent:
+
+- It never creates, claims, releases, closes or deletes a task on its own initiative. Each of those needs an explicit instruction from you, and a vague "done" is answered with a question rather than a closure.
+- It never edits state files, the history file or the execution log. Only the task document's first five sections are its to write.
+- It completes the written record before closing: a closed task cannot be written to again.
+- When it cannot find a task for the work at hand, it asks whether to create one instead of registering work you did not ask for.
+
+## What gets written
+
+```
+ledger/
+├── pool.json                 unclaimed tasks (shared)
+├── owners.json               index: identity → shard file
+├── owners/<hash>.json        one shard per person: the tasks they own
+├── worklog/<YYYYMM>/*.md     task documents, six fixed sections
+└── history/<YYYYMM>.md       closed tasks, one row each
+```
+
+State and prose are kept apart: JSON records ownership and state, Markdown records the reasoning. Only the CLI writes state, history and the execution log; the agent writes the first five sections of a task document and nothing else. All timestamps are stored in UTC and rendered in local time.
+
+## Commands
+
+| Command | Purpose |
 |---|---|
-| [`references/state-model.md`](references/state-model.md) | 状态机、时间口径（UTC / 本地、补录、筛选）、任务号、身份 |
-| [`references/log-note.md`](references/log-note.md) | 执行记录什么算一个节点、`--note` 怎么写（正 / 反例） |
-| [`references/troubleshooting.md`](references/troubleshooting.md) | 退出码、常见错误、硬约束、环境要求（git ≥ 2.27） |
+| `init` | Initialise or claim the machine identity (once per machine) |
+| `new` | Create a task |
+| `claim` | Take ownership of a task |
+| `set` | Change state, owner, tags or notes |
+| `log` | Append an execution record to a task document |
+| `close` | Close a task and write its history row |
+| `delete` | Delete a task created in error |
+| `list` | List in-flight tasks |
+| `show` | Show one task |
+| `history` | List closed tasks |
+| `stats` | Aggregate counters and trend |
+| `owners` | List known identities |
+| `root` | Detect whether a directory holds a ledger |
+| `whoami` | Show the current identity |
+| `validate` | Check ledger consistency |
+
+Run `scripts/progress <command> --help` for parameters. The agent-facing workflow lives in `SKILL.md`.
+
+## Multiple users
+
+Ownership is sharded: each person's tasks live in their own file, so two people advancing two tasks never touch the same file. Git merges the shards, the worklog documents and the history file. Where two people edit the same task document, the conflict is confined to that one file.
+
+## Links
+
+- Repository and full documentation: <https://github.com/cq-guojia/dsh-task-ledger>
+- The dsh plugin, which bundles this skill with a board UI: [`dsh-task-ledger`](https://www.npmjs.com/package/dsh-task-ledger)
 
-## 本仓自己的台账
+## Licence
 
-本仓库（`dsh-task-ledger`）也用自己的这套脚本（`scripts/progress` → `src/` 编译出的二进制）管自己的活，台账数据在 `ledger/`；它和本 skill 源码 `packages/skill/` 是两回事 —— **改 skill 请别动 `ledger/`**。
+MIT