nx-kv 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,133 @@
 
 本文件记录对外可见的变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [0.14.0] - 2026-11-03 wait 收尾指令模板化 + 回调提示词/持续 get 可配多条 + timegoal 面板入口 + 前缀归组改一次性命令 + 删全局默认时长
+
+### Changed
+
+- **回调提示词可配多条**：`localtask config` 的收尾指令从单条升级为**列表**
+  （`settings.taskSuffix` 存 `string[]`，上限 10 条、单条 ≤2000 字）。设置面板
+  「模板与任务工具」改为按条编辑（每条一个文本框 + 删除，「添加一条…」追加，
+  一次保存整体生效）；CLI 新增 `--suffix-add "<指令>"` 追加一条、
+  `--suffix-remove <序号>` 按序号删一条（与 `--suffix` / `--no-suffix` / `--reset-suffix`
+  互斥）。交付语义不变：多条按空行拼接后统一分流——任一条含 `{{` 整体渲染进
+  `instruction` 字段，纯文本仍追加正文末尾；删光 = 关闭。
+  - 兼容：旧单条 store（string）读入时整体迁为一列、不拆段；`--suffix "<文本>"`
+    仍是「整体替换为这一条」；设置视图同时暴露 `taskSuffix`（多条拼接串，旧消费者
+    无感）与 `taskSuffixList`（canonical 列表，UI/CLI 按条编辑用）。
+  - **项目级「持续 get」模板同步支持多条**（`getLoop.template` 存 `string[]`，同上限
+    规则）：设置面板「项目级设置」的持续 get 区块同款按条编辑；交付时多条按空行
+    拼接后统一渲染，全部留空 = 用默认模板；`getLoopForCwd` 暴露 `template`（拼接串）
+    与 `templateList`（列表）。CLI `--get-loop-template` 仍是「整体替换为这一条」。
+
+- **timegoal 时长删除全局默认，只在发布任务时设置**：任务时间目标的时长只在
+  `localtask add --duration` 显式给出（发布时校验写法），不再有「发布没给时长就按
+  全局默认计时」的兜底。设置面板「模板与任务工具」的「任务时间目标默认时长」输入框
+  与 CLI `localtask config --default-duration / --clear-default-duration` 一并移除。
+  - ⚠️ 升级注意：存量 store 里的 `settings.defaultDuration` 残留值被忽略（下次落盘
+    丢弃）；此前靠默认时长隐式带时间目标的任务，现在发布时需显式 `--duration`。
+
+- **timegoal 面板入口补齐（发布 + 编辑都可设）**：此前带时长的任务只能 CLI 发布——
+  面板任务编辑页没有时间目标入口。现在编辑页标题栏下新增「⏱ 时间目标」行（时长 +
+  可选附加要求）：草稿提交即带声明（POST `/api/localtasks` 的 `duration`/`goalPrompt`
+  字段本来就已支持）；**未领取**的任务在编辑页可改/清声明（`localtask update` 新增
+  `--duration` / `--goal-prompt` / `--clear-goal`，`--text` 在只改时间目标时可省）；
+  已领取计时中的任务声明冻结（要调先 reopen 重开）。目录任务表任务标题旁显示
+  `⏱ <时长>` 徽标（悬停看附加要求）。
+  - 语义约束：`--clear-goal` 与 `--duration` 互斥；只带附加要求不带时长在发布端报错；
+    改时长不带 `--goal-prompt` 则保留原附加要求。
+
+- **按前缀归组改为一次性命令，废除常驻规则**：原「仓库名以某前缀开头 → 自动算成员」
+  的前缀分组规则（`board prefix list/add/remove`、仓库页「按前缀分组」区块）整块移除，
+  改为一条一次性命令 `nx-kv board prefix <prefix> [--board <看板>]`——跑一次就把名字
+  以 `<prefix>` 开头（大小写不敏感）的已登记仓库**固化成目标看板的显式成员**（与手工
+  挂的完全同权）；`--board` 省略 = 按前缀名自动建同名看板。成员关系从此只有显式成员
+  一个来源；之后新登记的仓库要再跑一次命令。组详情页随之去掉「归属（手动/按前缀）」列。
+  - ⚠️ 升级注意：存量 `prefixGroups` 规则不再生效、下次落盘时被丢弃；原来由规则
+    动态归组的仓库会回到未分组——需要的话对每个前缀各跑一次 `board prefix` 补回。
+
+- **wait 收尾指令模板化（task / waittask / timegoal 融合）**：`localtask config --suffix`
+  从「固定追加语」升级为**占位符模板**。含 `{{` 的值在 wait 返回时由服务端渲染成融合
+  指令，放进返回载荷的新字段 `instruction`；默认模板 = 该目录 timegoal 状态
+  （`〔时间目标「目录名」剩余 X〕`，到点显示「已到点（已超时 X）」）+ 原收尾要求。
+  **模板模式下 `task.text` 保持库存原文、不再追加指令**（正文与指令分区打印）。
+  - 兼容：纯文本（无 `{{`）维持 v0.x 的 task.text 追加行为（旧 skill 副本不失效）；
+    `''` 仍 = 关闭；显式存过旧默认文本的 store 需 `localtask config --reset-suffix`
+    才拿到新默认模板。
+  - 占位符：`{{goal.name}} {{goal.remainingHuman}} {{goal.deadline}} {{goal.prompt}}
+    {{task.id}} {{task.text}} {{source}} {{summary}} {{cwd}} {{name}}`；段落
+    `{{#goal}}…{{/goal}}`、`{{#task}}…{{/task}}` 上下文缺失时整段消失。渲染是服务端
+    **单遍确定性替换**——goal.prompt / task.text 里的 `{{...}}` 逐字保留、绝不二次
+    展开（防漂移契约延伸到字符串层）。
+  - 新核心模块 `src/core/instruction-template.js`（纯函数、零依赖）；模板长度上限
+    500 → 2000（渲染产物不设限）。渲染走 `showTimegoal` 只读路径，不写盘、不影响
+    `timegoal check` 契约与到点自动收尾（goal_expired）行为。
+  - ⚠️ 降级注意：旧版 nx-kv 打开存了新默认模板的 store 会把原始 `{{...}}` 当纯文本
+    追加进 task.text（自定义模板超过旧版 500 上限的还会被截断）——请整版升级，
+    不要混跑新旧二进制。
+
+## [0.13.0] - 2026-10-31 任务模板可配置 + 完成任务可删除 + 无队列仓库可从侧边栏新建任务 + 仓库前缀分组
+
+### Added
+
+- **点项目组/项目目录 = 看表格**：
+  - 新增**项目组详情**（`#/group/<看板 id>`）：组里的**子目录**以表格呈现 ——
+    目录 / 路径 / 说明 / 待领取 / 归属（手动 vs 按前缀）。点组行进这里，点表行进该目录。
+  - 目录工作台的落地页改成**子任务表**（表格）：编号 / 任务 / 状态 / 创建 / 领取 /
+    删除。列表把「什么时候建、什么时候被领走」压成一行就丢了，表格才看得到。
+  - 侧栏点击语义分开：**点行 = 去看内容**（组 → 组表，目录 → 子任务表），
+    **点 chevron = 在树里展开/收起**。以前两者抢同一个点击，展开就没法兼得。
+- **仓库按前缀分组**：「仓库名以 nx 开头 → 归成一类」这类规则现在有了。
+  - 规则只改**成员关系**，看板仍是唯一分组载体 —— 侧边栏分组、仓库页看板筛选、
+    成员管理全都自动跟着生效，不用各改一遍。
+  - 规则存服务端（仓库 store 的 `prefixGroups`），换浏览器/换机一致；
+    规则同时记看板 id 与 key（改名不失效、导入换机有兜底）。
+  - CLI：`board prefix list` / `board prefix add <前缀> [--board <看板>]` /
+    `board prefix remove <前缀>`；HTTP 同构：
+    `GET/POST /api/boards/prefix-groups`、`DELETE /api/boards/prefix-groups/:prefix`。
+    目标看板留空 = 按前缀名**自动建同名看板**（如 `board prefix add nx`）。
+  - 面板：仓库管理页「看板」区新增「按前缀分组」区块（规则 chip + 前缀/看板输入 + 添加）。
+  - 删规则时，**规则建的空看板**一并清掉；看板里有手动成员则只删规则、不动看板。
+- **侧边栏分组读成组**：看板的成员行原本混在全局名称序里（组标题与成员不相邻，
+  「nx 一类」看着只是一堆缩进行）。现在成员紧跟在自己的看板行下面，未归组的仓库
+  排在所有组之后。
+- **任务模板（`template` 命令族 + 面板管理）**：MD 工作台「新建页」的起始正文不再写死。
+  - 存 `~/.nx-kv/templates.json`（`NX_KV_TEMPLATES_STORE` 可覆盖）；内置一条默认模板
+    （不可删），删掉自定义默认后默认回落到内置。
+  - 面板：管理入口在**侧边栏设置**（齿轮 → 「任务模板…」弹窗：新增 / 编辑 / 删除 /
+    设为默认）。弹窗头部写明新建页默认用哪个模板；每行给正文前几行的等宽预览；
+    正文用 **MD 编辑器**（源码 + 实时预览 + 格式工具条 B/I/代码/链接/列表/待办/引用/
+    H2/H3，Ctrl/⌘+B/I/E/K，视图可切并排/源码/预览）——模板本身就是 Markdown，
+    配置它不该是一个裸 textarea；编辑是行内表单（Ctrl/⌘+Enter 保存）；删除带确认。
+    落地页「模板 ▾」菜单按模板直接开新页（✓ 标默认）。「新建页」「新任务」一律取
+    默认模板正文，API 不可达时退回内置骨架（与旧版行为一致）。设置与工作台共享
+    同一份模板数据，改完即时生效。
+  - CLI：`template list` / `template add <name> [--body <md> | --body-file <文件> | --body -]`
+    `[--setDefault]` / `template update <id> [--name] [--body|--body-file]` /
+    `template remove <id>` / `template default <id>`；HTTP 同构：
+    `GET/POST /api/templates`、`PATCH /api/templates/:id`、
+    `DELETE /api/templates/:id`、`PATCH /api/templates/default`。
+    多行 Markdown 正文在 cmd.exe 里塞不进参数，所以给了 `--body-file`（读文件）与
+    `--body -`（读标准输入）——这两条**只在 CLI 生效**，HTTP 不暴露读本机文件。
+- **设置齿轮图标画错**：原来的 `gear` 是「圆心 + 八向光线」的日芒/亮度形状，不像设置。
+  重画为标准齿轮（中心圆 + 齿圈）。
+- **旧版 serve 进程配新版面板资产时，模板弹窗只说「加载失败」**：路由在进程启动时加载、
+  静态资产从磁盘现读——跑着旧进程时新 UI 会拿到 `/api/templates` 404。现在识别出
+  「接口不存在」这种版本偏差，弹窗明说「本机面板服务较旧，重启面板后重试」并隐藏
+  必然失败的表单，只留「重试」；普通瞬时失败同样给「重试」。
+
+### Fixed
+
+- **绑定的仓库没有任务队列时，侧边栏展不开也建不了任务**：仓库行的展开键在无队列时
+  是空串，渲染判断永远为 false——「＋ 新建页」子行根本不出现；直接跳工作台又会因
+  找不到队列主题落「目录不存在」。现在点无队列仓库能正常展开，点「新建页」/行菜单
+  「打开详情」/收起态 rail 图标会先自动登记该目录为任务队列（幂等、防 prune），再进
+  工作台。
+- **本地任务完成后没有任何删除入口**：完成（consumed）的任务此前只能留存在列表里。
+  现在两处都可删：落地页列表行悬停出「✕」；打开的页面在工具栏「更多」里有「删除」。
+  删除是**软删除**（`deletedAt` 标记，CLI `localtask task restore` 可恢复），已打开的
+  页签会随手关闭。
+
 ## [0.12.1] - 2026-10-30 key 归一化修复 + remote 对齐反馈
 
 ### Fixed
@@ -57,6 +184,25 @@
     `repo remote check`（`git ls-remote` 检查远端是否存在，**存在 / 不存在 /
     不可达**三种结论分清）。面板上每行有「remote」按钮，弹窗里下拉切换 + 存在性徽标。
 
+- **MD 工作台编辑器专业对齐（10 轮 UI/UX 循环，纪要见 `plan/LOOP-MD-EDITOR.md`）**：
+  - **标题不再截断**：live 与源码两态的标题改为自动增高 textarea，长标题按宽度软换行；
+    Enter 不产生换行、直接把焦点交给正文（live 进首块 / 源码回正文 0 位）
+  - **工具栏分层**：模式 | 格式 | 插入三簇 hairline 分组，格式组去灰底容器（hover 才显底），
+    次级动作去描边转文本态，视觉重量留给主按钮
+  - **自适应改容器查询**：`.mdw-main` 声明 container，工具栏/纸面按「编辑列」实际宽度三级折叠
+    （1280 收转变组 / 960 收进溢出菜单 / 640 纸面紧凑）——修掉右侧进程 rail 一开就静默裁按钮的缺陷
+  - **溢出菜单 portal 到 body**：修 `···`/`更多` 菜单被工具栏 `overflow:hidden` 整条裁掉的缺陷
+  - **阅读态补题头**：三态标题呈现统一，题头与正文同轴同宽
+  - **空文档幽灵引导**：空文档渲染 Notion 式引导条，点击直接聚焦首块
+  - **撤销/重做**：新增文档级历史栈——受控 textarea 的程序化改写会冲掉浏览器原生 undo 栈，
+    原先「Ctrl+B 加粗 → Ctrl+Z」毫无反应；现在格式操作、输入段均可撤销/重做，
+    且撤销后光标回到改动处（源码精确，live 跨块自动跳转并接管焦点）
+  - **Ctrl/⌘S 保存 + 页签未保存圆点**：改动即在页签挂一颗点，保存/提交后摘除
+  - **快捷键速查面板**：Ctrl/⌘ / 或工具栏问号唤起，15 条键位分三组
+  - **实时预览块级查找**：Ctrl/⌘F 在预览态可用，n/m 计数 + 命中块高亮 + 滚动定位
+  - **无障碍**：编辑区 aria-label 补齐、状态栏小字对比度提到 WCAG AA
+
+
 - **仓库获得全局唯一 key，导入导出改以 key 为身份（v3）+ 全屏导入导出面板**：
   - **key**：归一化远程地址派生（`git@c:o/r.git`、`https://c/o/r`、
     `ssh://git@ssh.github.com:443/o/r.git`、带端口、带 `.git` 都是同一个

package/assets/groups.json

@@ -3,32 +3,28 @@
   "$comment": "group 名 → skill 名列表的别名表。当前 group 名 ≡ skill 名（一对一）；skills 是数组，为「一个 group 含多个 skill」预留。路径恒由 assets/<skills[i]>/ 推导——本文件只做聚合，不是第二条事实源。",
   "groups": {
     "nx-kv": {
-      "skills": ["nx-kv"],
+      "skills": [
+        "nx-kv"
+      ],
       "summary": "KV 清单管理中枢主 skill（默认 install 装的就是这个）：todo / group / 工作空间（远程，需登录）"
     },
-    "kv-waittask": {
-      "skills": ["kv-waittask"],
-      "summary": "对话内实时人机接力（等待侧）——agent 阻塞 wait，用户在网页回填"
+    "kv-get": {
+      "skills": [
+        "kv-get"
+      ],
+      "summary": "领取与完成本机任务：get 领活 / wait 等人回填 / 时间目标 check 门禁 / done 完成 / reopen 按反馈重开"
     },
     "kv-submit": {
-      "skills": ["kv-submit"],
-      "summary": "总结上下文、提炼用户需求，提交到别的目录队列委托其它 agent（提交侧）"
-    },
-    "kv-localget": {
-      "skills": ["kv-localget"],
-      "summary": "领取排给本目录的本地任务 + 队列管理（领取侧）"
-    },
-    "kv-timegoal": {
-      "skills": ["kv-timegoal"],
-      "summary": "把「持续运行 N 小时」任务固化到 nx-kv：每轮回显原文提示词防偏移 + 时间到点自动停手"
+      "skills": [
+        "kv-submit"
+      ],
+      "summary": "总结上下文、提炼用户需求，提交到别的目录队列委托其它 agent（提交侧）；可带 --duration 时间目标"
     },
     "kv-repo": {
-      "skills": ["kv-repo"],
-      "summary": "仓库组识别与关系报告——/kv-repo <组名> 一步加载看板相关项目；board/repo 查询、读并维护领域描述（中心/终端、关键路径、搜索关键词）"
-    },
-    "kv-repo-mmx-gitrepo": {
-      "skills": ["kv-repo-mmx-gitrepo"],
-      "summary": "mmx 深度搜索并克隆参考仓库——repo ref clone 统一落 gitRepoRoot、remote 为 key 登记绑定，替代散装的 git clone + git.remote 清单流程"
+      "skills": [
+        "kv-repo"
+      ],
+      "summary": "仓库组识别与关系报告；克隆外源参考仓库并强制读（读参考实现不许只凭搜索摘要）"
     }
   }
 }

package/assets/kv-get/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: kv-get
+description: 领取与完成排给本工作目录的本地任务（别人通过 kv-submit 委托的、用户在面板/弹窗排队的，都落在「目录名即主题」的队列里）——用 localtask get 取活（默认直接领；项目开启「持续 get」后自动阻塞等人回填）、localtask wait 挂着等人接力、localtask done 标记完成（带时间目标的任务未到点会被拒绝，提示派 sub agent 重提需求）、localtask reopen 把用户的修改反馈送回队列重新执行。触发词：领取本地任务、看看有没有排给我的任务、本地队列、领取委托任务、拿任务、本目录的任务、排队任务、localtask get、localtask wait、标记完成、任务完成、修改反馈、重新执行、kv-get。凡「主动获取排给本目录的任务」以及「把任务标记完成/按反馈重开」的场景都走本 skill。反例：把需求提交/委托给别的目录用 kv-submit；查本机仓库分组与参考仓库用 kv-repo；操作远程 KV 清单（todo）用 nx-kv。
+---
+
+# kv-get — 领取、执行、完成（领取侧）
+
+一个 skill 覆盖本机任务的**完整生命周期**：领 → 干 → 标完成 → 按反馈重开。
+细节拆在 references 里，按需读：
+
+- [[localget]] — 领取侧：队列管理、单条查看/编辑/删除/调序
+- [[waitloop]] — 等待侧契约：wait 是本轮最后一步，唯一合法出口是 timeout
+- [[timegoal]] — 时间目标：目录级与**任务级**（领取即计时）的 check 门禁
+- [[wait-workflow]] / [[timegoal-workflow]] — 两套循环的细则
+
+## 三个动作，三种语义（别混用）
+
+| 动作 | 命令 | 语义 |
+| --- | --- | --- |
+| **领活** | `nx-kv localtask get --summary "<现状>" --json` | 队列有任务**立即领走**；没有就**立即返回 timeout**（不阻塞、不开窗）——「暂时没活」是正常业务结果 |
+| **等人** | `nx-kv localtask wait --summary "<现状>" --timeout 30 --json` | 阻塞等人回填；**本轮最后一步**，唯一合法出口是 timeout |
+| **挂着领** | 同上，但项目开启了「持续 get」 | `get` 升级为 waitgoal：无任务自动唤起（打开目录页面 + 项目配置的分钟数），期间用户回填就直接领到；领到的交付文本自带「继续 get 直到超时」的项目模板 |
+
+「持续 get」是**项目级**开关（设置面板 → 项目级设置，或 `repo update --get-loop on`），
+默认关闭——默认就是「直接 get」。
+
+## 领取到的东西必须读全
+
+```bash
+nx-kv localtask get --summary "<本轮现状>" --json
+# → { status:"ok", task:{id,text,...}, instruction:"…" }
+```
+
+- `task.text` = 任务正文（Markdown），**永远读它**；
+- `instruction` = 服务端渲染的指令段，**有则必读**（与 task.text 一起构成这一轮的根指令）：
+  - **项目组上下文**（领的是组内仓库时）：组定位、组介绍、本项目在组里的位置、兄弟成员的角色、组绑定参考文件的**可读路径**——这些路径是磁盘上的真实文件，需要细节就直接读；
+  - **收尾指令**（可配置，默认「本轮最后再 wait 一次」）；
+  - **任务级时间目标的 check 指令**（见下）。
+
+## 时间目标：领取即计时，未到点不许标完成
+
+发布方可以给单条任务带时长（`localtask add … --duration 2h`）。这种任务被领取时
+**自动起表**，交付文本里带一条固定指令：
+
+```bash
+nx-kv timegoal check --task task:<topicKey>:<taskId> --summary "<本轮现状>" --progress "<进展/下一步>"
+```
+
+每轮推进先跑一次 check（它会原文回显时间目标提示词，防长对话漂移）。
+**时间未到不能标完成**——`localtask done` 会返回业务结果（不是错误）：
+
+```json
+{ "status": "blocked", "reason": "goal_not_reached", "remainingSec": 1830,
+  "hint": "时间未到，不能标记完成——请派出 sub agent 重新提出新的需求；到点后…再来标完成" }
+```
+
+此时**不要**硬标完成、也不要自己改时间：按提示**派 sub agent 重新提出新的需求**，
+再继续推进；到点（check 返回 `reached:true`）后再 `done`：
+
+```bash
+nx-kv localtask done --id <n> --summary "<完成总结>" --json
+```
+
+没有时间目标的任务直接 done 即可。目录级 timegoal（`timegoal set --cwd …`）是另一回事：
+它是「这个目录整体要跑多久」的预算，见 [[timegoal]]。
+
+## 完成与反馈：闭环的两端
+
+```bash
+# 标记完成（完成总结必填——它就是下一轮 agent 能看到的「上轮做了什么」）
+nx-kv localtask done --id <n> --summary "<完成总结>" [--progress "<完成度/下一步>"]
+
+# 用户看了结果提修改意见 → 任务回到待领取，agent 可再次领取（执行循环继续）
+nx-kv localtask reopen --id <n> [--text "<改后的正文（Markdown）>"] --json
+```
+
+`reopen` 会作废领取时间（新一轮从**再次领取**开始重新计时）、清掉完成标记，
+但**保留上一轮的完成总结**——下一轮接手时 agent 能看到自己上轮做到哪。
+
+## 硬规则
+
+1. **同一个目录同一时刻只挂一个 wait**（waiters 是进程内注册表，一个 key 只能有一个）。
+2. **timeout 是业务结果，不是错误**（exit 0）：按「暂时没活」收尾，**不要**当失败重试。
+3. **wait 是本轮最后一步**：拿到任务或超时之前，不要提前结束本轮。
+4. **instruction 有则必读**：里面的组上下文/时间目标/收尾要求都是硬约束。
+5. **带时间目标的任务不许提前标完成**——被拒绝就按提示派 sub agent 重提需求。
+6. **同一时刻只挂一个 wait**；`get` 与 `wait` 不要并发跑（都在同一队列上抢任务）。
+
+## 队列管理（需要时）
+
+```bash
+nx-kv localtask list --json                # 全部主题：目录、现状、等待中、待领取数
+nx-kv localtask show   --id <n> --json      # 查看单条（get 已是「领取」动词）
+nx-kv localtask update --id <n> --text "<新内容>" --json   # 改正文；--duration 2h 设时间目标、--clear-goal 清除（仅未领取时可改）
+nx-kv localtask remove --id <n> --json      # 软删除（CLI restore 可恢复）
+nx-kv localtask reorder --id <n> --before-id <m> --json
+nx-kv localtask topic remove --cwd "<目录>" # 删整个主题（等待中需 --force）
+```
+
+以上都不传 `--cwd` 时按进程当前目录定位。

package/assets/{kv-localget/SKILL.md → kv-get/references/localget.md}

@@ -16,24 +16,41 @@ description: 领取排给本工作目录的本地任务——别人通过 kv-sub
 nx-kv localtask list --json
 # → {topics:[{key,cwd,name,summary,waiting,pending,total,tasks:[...]}], waiting, settings}
 
-# 2. 有待领取 → 取走最早的一条（队列非空时 wait 立即返回，不开窗不阻塞）
-nx-kv localtask wait --summary "<本轮现状，如：空闲，领取新任务>" --timeout 30 --json
+# 2. 有待领取 → 取走最早的一条（默认「直接 get」：队列非空立即返回，不开窗不阻塞）
+nx-kv localtask get --summary "<本轮现状，如：空闲，领取新任务>" --json
 # → {status:"ok", queued:true, task:{id,text,...}}
 
+# 2b. 想挂着等活（阻塞等人回填）→ 用 wait（kv-waittask 的循环契约）
+nx-kv localtask wait --summary "<本轮现状>" --timeout 30 --json
+
 # 3. 执行 task.text（内容永远读 task.text，id 只是编号），产出落在本目录
+
+# 4. 干完标记完成（带时间目标的任务：未到点会被拒绝）
+nx-kv localtask done --id <n> --summary "<完成总结>" --json
 ```
 
 - `queued:true` = 从队列取到任务，直接执行。
+- 返回可能带 `instruction` 字段（收尾指令模板的渲染结果，默认含该目录 timegoal 的
+  剩余预算 +「计划最后再 wait 一次」）——有则必读，与 `task.text` 一起构成这一轮的
+  根指令；字段缺席 = 已关闭或本轮没有可渲染内容（如模板只有 goal 段而该目录无目标）。
 - `{status:"timeout"}`（exit 0，不是错误）= 时限内没有新任务：想继续等就再
   wait（挂起等待，期间别人提交的会立刻送达），不想等就收工。
+- **get 的两种形态**：默认「直接 get」（没任务立即返回 timeout，不阻塞）；项目在设置
+  面板里开启「持续 get（waitgoal）」后，get 变成**阻塞唤起**——自动打开对应目录页面、
+  等项目配置的分钟数，期间用户回填就直接领到；领到的交付文本自带「继续 get 直到
+  超时」的项目模板（不用自己记循环）。
+- **带时间目标的任务**（发布时 `--duration 2h`）：领取即计时，交付的 instruction 里
+  带 `timegoal check --task …` 指令；**时间未到不许标记完成**——`localtask done`
+  会返回 `{status:"blocked", reason:"goal_not_reached"}`，此时应派出 sub agent
+  重新提出新的需求再继续，而不是硬标完成。
 - `--timeout <秒>`：阻塞上限（缺省用页面配置 180 秒，最大 600）；「查完就走」
   用短超时，「挂着等活」用长超时。
 
 ## 队列管理（需要时）
 
 ```bash
-nx-kv localtask get    --id <n>                        # 查看单条
-nx-kv localtask update --id <n> --text "<新内容>"       # 改写任务内容
+nx-kv localtask show   --id <n>                        # 查看单条（get 已改为领取动作）
+nx-kv localtask update --id <n> --text "<新内容>"       # 改写任务内容；--duration/--clear-goal 改时间目标（仅未领取时）
 nx-kv localtask remove --id <n>                        # 删除单条
 nx-kv localtask reorder --id <n> --before-id <m>       # 调整领取顺序（或 --after-id）
 nx-kv localtask topic remove --cwd "<目录>"             # 删除整个主题（等待中需 --force）

package/assets/{kv-timegoal/references/workflow.md → kv-get/references/timegoal-workflow.md}

@@ -1,6 +1,6 @@
 # kv-timegoal · 时序与完整示例
 
-按需加载：只是想看命令的话回到 [[kv-timegoal|SKILL.md]]，不必读这份。
+按需加载：只是想看命令的话回到 [[timegoal]]，不必读这份。
 下面给一份能复刻的"3 小时调研 Redis 差距并自迭代实现生产级数据库"任务
 完整时序，含可直接抄走的 prompt 模板。
 

package/assets/{kv-timegoal/SKILL.md → kv-get/references/timegoal.md}

@@ -171,10 +171,23 @@ nx-kv timegoal log    --cwd <dir>                                    # 回看每
 
 **没有依赖关系。** timegoal 只做两件事：算时间、回显提示词原文。
 
-- 不调用 `localtask wait`：等不到任务是别的事，与是否到点无关
+- 不调用 `localtask wait`：等不到任务是别的事，与是否到点有关
+- **两种 timegoal**：目录级（`--cwd`，与目录一对一）与**任务级**（`--task
+  task:<topicKey>:<taskId>`，发布时 `localtask add --duration 2h` 随任务携带，
+  **领取即计时**）。任务级的 goal key 会随任务交付的 instruction 一起给你，
+  直接照抄执行即可；`timegoal check --task <key> --summary … --progress …` 记日志，
+  未到点 `localtask done` 会拒绝标记完成。
 - 不阻塞任何东西：可以同时跑人机接力、派任务给别的 agent、外部 cron
 - 不需要登录 KV 后端：纯本机
 
+**与 wait 的融合（只读，单向）**：这个目录挂着 timegoal 时，`localtask wait`
+返回的 `instruction` 字段会带上目标状态（默认模板：`〔时间目标「目录名」剩余 X〕`；
+到点后显示「已到点」）——kv-waittask 循环里的 agent 不调 check 也能看到预算。
+融合是**渲染时只读**（`showTimegoal` 只读路径，不写盘、不写 check 日志、不影响
+计时与到点判定），timegoal 自身的命令族与契约完全不变；`check` 的 prompt 原文
+回显仍是防漂移的唯一正式通道。要到 wait 的 instruction 里携带 prompt 原文，
+用 `localtask config --suffix` 自定义模板并写入 `{{goal.prompt}}`。
+
 你可以把它当成一个独立计时器 + 便签本：`set` 把便签写进文件，`check` 读出来
 顺便告诉你还剩多少时间。
 

package/assets/{kv-waittask/references/kv-waittask-workflow.md → kv-get/references/wait-workflow.md}

@@ -1,6 +1,6 @@
 # kv-waittask-workflow — 阻塞等待用户回填任务的完整 SOP
 
-> 归属 [[kv-waittask]]。当你要在一个对话里**不结束本轮**、靠一个阻塞工具
+> 归属 [[waitloop]]。当你要在一个对话里**不结束本轮**、靠一个阻塞工具
 > 调用等浏览器里继续回填任务时，按本 SOP 走。
 >
 > **循环是强制的：每完成一步、提交结果后，结束动作只能是 wait——领取新任务。
@@ -21,7 +21,8 @@
         自动打开浏览器弹窗，然后阻塞。
 4. 用户在弹窗/面板看清现状，回填新任务 → 提交（Enter 或按钮）。
 5. wait 解除阻塞，stdout(--json) 返回 {status:"ok", task}，进程退出。
-6. agent 从工具结果读 task.text，继续干活、提交结果；做完【必须】回到第 2 步——
+6. agent 从工具结果读 task.text（任务本体）与 instruction（收尾指令模板的渲染结果，
+   有则必读），继续干活、提交结果；做完【必须】回到第 2 步——
    循环，不许自行中断。
 7. 若阻塞时限（默认 180 秒）内没有回填：wait 返回 {status:"timeout"}（exit 0），
    agent 不再等待，收尾并结束本轮——这是整个循环唯一的合法出口。
@@ -78,6 +79,7 @@ wait 必带一句当前现状总结（≤2000 字，连续空白会折叠为单
   "task": { "id": 3, "text": "选择工作空间 A", "status": "consumed",
             "createdAt": "2026-10-11 10:00:00", "consumedAt": "2026-10-11 10:00:04",
             "roundSummary": "已完成登录，等待选择工作空间" },
+  "instruction": "〔时间目标「demo」剩余 2.5 小时〕规划计划，然后完成这个任务；计划的最后一个动作，是再次调用 nx-kv localtask wait（带上 --cwd 当前工作目录、--summary 当前现状、--json）收尾本轮，在拿到下一条任务或超时之前不要提前结束。",
   "delivered": true,
   "queued": false,
   "source": "local"
@@ -88,6 +90,13 @@ wait 必带一句当前现状总结（≤2000 字，连续空白会折叠为单
 - `source` = 任务来自哪个队列：`"local"`（本目录队列，含实时回填）或 `"global"`
   （全局任务池）；agent 不必区分，照常执行 `task.text`。
 - **任务内容永远读 `task.text`**，多行换行原样保留。
+- **`instruction` 有则必读**：收尾指令模板的服务端渲染结果——默认含该目录 timegoal
+  的剩余预算（没挂目标则无这段）+「计划最后再 wait 一次」。模板含 `{{task.text}}`
+  时 instruction 自包含（正文以它为准）。字段缺席 = 已关闭或本轮没有可渲染内容，只执行任务。
+- **配置**：`nx-kv localtask config --suffix "<模板>"`（占位符
+  `{{goal.name}} {{goal.remainingHuman}} {{goal.prompt}} {{task.text}} {{source}} {{name}}…`，
+  段落 `{{#goal}}…{{/goal}}` 上下文缺失整段消失；`--no-suffix` 关闭、
+  `--reset-suffix` 恢复默认）。字段缺席 = 已关闭或本轮没有可渲染内容。
 
 超时（exit 0，业务结果而非错误）：
 

package/assets/{kv-waittask/SKILL.md → kv-get/references/waitloop.md}

@@ -83,6 +83,15 @@ nx-kv localtask wait --summary "<当前现状总结>" --json
 成功结果里带 `cwd` 与 `summary`；`task` 形如
 `{id, text, status, createdAt, consumedAt, roundSummary}`，**任务内容在 `task.text`**。
 
+**`instruction` 字段（有则必读）**：配置了收尾指令**模板**（默认即是）时，wait 返回
+额外带 `instruction` —— 服务端渲染的**本轮根指令**：默认含时间目标状态
+（`〔时间目标「目录名」剩余 X〕`，该目录挂了 timegoal 才出现）+ 收尾要求
+（计划最后再 wait 一次）。规则：
+
+- `task.text` 永远是任务本体原文；`instruction` 是**包裹它的执行指令**，两者一起读。
+- 自定义模板可含 `{{task.text}}`（此时 instruction 自包含，正文以它为准）。
+- 该目录的 timegoal 到点后，instruction 会显示「已到点」——预算用完，本轮该收尾了。
+
 ## 一次循环长什么样
 
 ```
@@ -114,7 +123,7 @@ agent：工具结果拿到 task.text → 干活 → 提交结果
 nx-kv localtask list                                   # 主题总览（各目录、现状、待领取数）
 nx-kv localtask add  "<回填内容>" --cwd "<目录>"        # 给某目录的队列排任务
 nx-kv localtask get   --id <n> [--cwd "<目录>"]         # 查看单条
-nx-kv localtask update --id <n> --text "<新内容>"       # 编辑任务内容
+nx-kv localtask update --id <n> --text "<新内容>"       # 编辑任务内容；--duration/--clear-goal 改时间目标（仅未领取时）
 nx-kv localtask remove --id <n> [--cwd "<目录>"]        # 删除单条任务
 nx-kv localtask reorder --id <n> --before-id <m>        # 调整待领取优先级（或 --after-id）
 nx-kv localtask topic remove --cwd "<工作目录>"          # 删除整个主题（等待中需 --force）

package/assets/kv-repo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kv-repo
-description: 识别并汇报本机仓库的相关分组（仓库组）——快捷入口 `/kv-repo <组名>`：一步到位加载该看板的成员仓库、领域描述与配合关系，输出关系报告。用 nx-kv repo / board 命令回答「这台机器上有哪些仓库、按领域怎么分组、组内谁是中心谁是终端、关键路径与搜索关键词在哪」。看板的领域描述（desc）+ 成员仓库的组内描述（note：它在组里的角色）共同构成写给 agent 读的上下文——领域侧重、仓库间配合关系（如 fr 组内 API 关联、go-ah 为 OIDC 中心其余为终端）、入口路径、搜什么关键词。触发词：/kv-repo、kv-repo、仓库组、相关仓库、这个仓库属于哪个组、组里都有什么、它们什么关系、中心/终端、领域描述、关键路径、加载 fr 的看板、看板相关项目、board list、repo list。反例：登记/扫描/增删仓库与看板用 nx-kv 主 skill 的 repo-registry；git 状态与 diff 一律找 git 自己。
+description: 本机仓库上下文的两件事——①识别并汇报仓库分组（看板/项目组）与组内关系，一键加载成员、领域描述与配合关系；②克隆外源参考仓库并**强制读完**它（clone 落到统一 gitRepoRoot，登记为 ref，之后用 Read 工具真读关键文件再回答/实现，不许只凭搜索摘要下结论）。用 nx-kv repo / board 命令拿分组与描述，用 nx-kv repo ref clone 克隆参考仓库。触发词：/kv-repo、kv-repo、仓库组、相关仓库、这个仓库属于哪个组、组里都有什么、它们什么关系、中心/终端、领域描述、关键路径、读并维护领域描述、克隆参考仓库、clone 参考仓库、调研开源项目、找参考实现、强制读、读完再答。反例：登记/扫描/增删仓库与看板用 nx-kv 主 skill 的 repo-registry；git 状态与 diff 一律找 git 自己。
 ---
 
 # kv-repo — 仓库组识别与关系报告
@@ -68,6 +68,32 @@ nx-kv repo ref check                 # 参考仓库完整性：目录/origin 一
 定位顺序：拿到任务/目录 → `repo list` 按**路径或目录名**找到仓库
 → 它的 `boards[]` 给出所属组 → 回 `board list` 读该组的 `desc` 与**兄弟仓库**。
 
+## 克隆外源参考仓库 + **强制读**（第二件事）
+
+当任务需要「看看别人怎么做的」，参考仓库**要真读**，不是搜两眼摘要就下结论。
+
+```bash
+# 1) 克隆并登记为参考仓库（落到统一 gitRepoRoot，remote 为唯一 key）
+nx-kv repo ref clone <git-url> --json
+# → { repo:{ key, path, name, … } }     # path 就是本机落盘位置
+
+# 2) 绑定到当前仓库或看板（可选，但强烈建议——下次自动带出上下文）
+nx-kv repo bind <ref-key> --repo <本仓库id> --note "参考它的 xxx 实现" --json
+
+# 3) **强制读**：用 Read 工具真读关键文件——README、docs/、契约文件、入口实现
+#    （落盘路径从第 1 步的 path 取；先看文件清单再决定读哪几个）
+```
+
+**强制读的纪律**：
+
+- clone 完**必须读**：至少 README + 与任务直接相关的源文件/契约文件，并把**读到的具体位置**
+  （文件路径 + 关键行/函数名）写进结论；
+- **不许**只凭 `grep` 命中的一行或搜索摘要就下结论——摘要会把上下文丢掉；
+- 读完再回答/实现；引用参考实现时说明「参考的是哪个仓库的哪个文件」。
+
+多路并行调研时的纪律（搜索纪律见 [[mmx-gitclone]]）：3–5 路并行深搜、最多 clone 2 个最有价值的项目、
+SSH 优先失败双向回退、`--depth 1` 浅克隆。
+
 ## 维护：发现过期就修（这是本 skill 的另一半职责）
 
 读到的 desc 与代码现实不符（路径变了、关系变了、压根没写）时，顺手补上：
@@ -86,6 +112,7 @@ nx-kv board note <仓库id|路径> --board <看板id> --note "这个仓库在组
 
 ## 边界
 
-- 本 skill **只读分组与描述**；登记/扫描/增删仓库看板走 nx-kv 主 skill（repo-registry）。
+- 本 skill 读分组与描述、克隆参考仓库并强制读；**登记/扫描/增删仓库看板**走 nx-kv 主 skill（repo-registry）。
+- 参考仓库的**写入/同步**（pull、完整性检查）走 `nx-kv repo ref sync/check`。
 - 不碰 git：状态 / diff / pull / push 一律直接用 git 自己。
 - 数据按 groupId 隔离，查询前先确认工作空间对不对（`nx-kv group current`）。

package/assets/kv-submit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kv-submit
-description: 把当前对话里的需求打包成任务，通过 nx-kv localtask add 提交到另一个工作目录的队列，委托在那里的 agent 完成——先总结上下文（聊了什么、定了什么、涉及哪些文件）、再提炼出用户的真实需求（目标、约束、验收标准），写成不依赖本对话就能执行的自包含任务文本再提交；可给正在等待的 agent 实时补任务，也可给不在等待的目录排队。触发词：提交任务、委托、派任务、丢给另一个 agent、交给那边做、转发需求、整理成任务提交、总结上下文提交、提炼需求、长对话提炼、保存会话、会话交接、localtask add、kv-submit。凡「把这个对话里的东西变成任务交给别的 agent」的场景都走本 skill。反例：你自己在等用户回填用 kv-waittask；主动领取排给本目录的任务用 kv-localget；操作远程 KV 清单（todo）用 nx-kv。
+description: 把当前对话里的需求打包成任务，通过 nx-kv localtask add 提交到另一个工作目录的队列，委托在那里的 agent 完成——先总结上下文（聊了什么、定了什么、涉及哪些文件）、再提炼出用户的真实需求（目标、约束、验收标准），写成不依赖本对话就能执行的自包含任务文本再提交；可给正在等待的 agent 实时补任务，也可给不在等待的目录排队。触发词：提交任务、委托、派任务、丢给另一个 agent、交给那边做、转发需求、整理成任务提交、总结上下文提交、提炼需求、长对话提炼、保存会话、会话交接、localtask add、kv-submit。凡「把这个对话里的东西变成任务交给别的 agent」的场景都走本 skill。反例：你自己在等用户回填、或要领取/完成/重开本目录的任务用 kv-get；操作远程 KV 清单（todo）用 nx-kv。
 ---
 
 # kv-submit — 提炼需求，委托其它 agent（提交侧）
@@ -30,6 +30,9 @@ nx-kv localtask add "<任务文本>" --cwd "<目标目录>" --summary "<该目
 # 不限定接收方、谁闲谁领 → 推到全局任务池（--cwd 被忽略）：
 # 任何目录的 agent 在本地队列空时都会自动领取（返回 source:"global"）
 nx-kv localtask add --global "<任务文本>" --json
+
+# 带时间目标（可选）：领取即计时，未到点不许标记完成
+nx-kv localtask add "<任务文本>" --cwd "<目标工作目录>" --duration 2h --goal-prompt "<附加要求>" --json
 ```
 
 返回 `{status:"ok", task:{id,text,...}, queued|delivered}`：
@@ -39,6 +42,18 @@ nx-kv localtask add --global "<任务文本>" --json
   全局任务池，任何目录空闲的 agent 自动领取。
 - 记下 `task.id`，向用户报告「已提交到哪个目录（或全局池）、第几号任务」。
 
+## 用户看完结果要改 → 重开那条任务
+
+任务被领走、干完（`localtask done`）之后，用户提了修改意见——**那条任务要重开**，
+否则 agent 看不到新一轮的诉求（已领取的任务不会再被派发）：
+
+```bash
+nx-kv localtask reopen --id <n> --text "<改后的正文（Markdown）>" --json
+```
+
+重开 = 回到待领取 + 领取时间作废（新一轮重新计时），上一轮的完成总结保留。
+`--text` 不给则只重开、不改正文。重开的细节见 kv-get skill。
+
 ## 任务文本怎么写（一句话版）
 
 接收方没有你的上下文，任务文本按这个顺序组织成一段（单行，用 ①②③ 编号，
@@ -66,8 +81,8 @@ nx-kv localtask add --global "<任务文本>" --json
 
 | 场景 | 用哪个 |
 | --- | --- |
-| 你自己干完活、等用户在浏览器回填下一条 | kv-waittask（wait） |
-| 主动领取排给**本目录**的任务 | kv-localget |
+| 你自己干完活、等用户在浏览器回填下一条 | kv-get（wait / done / reopen） |
+| 主动领取排给**本目录**的任务 | kv-get（get） |
 | 操作远程 KV 后端的 todo 清单（需登录） | nx-kv |
 | 给**正在等待**的 agent 补一条任务 | 本 skill（add 到它的目录） |
 | 不限定接收方、让任何空闲 agent 自取 | 本 skill（`add --global` 推全局任务池） |
@@ -77,13 +92,12 @@ nx-kv localtask add --global "<任务文本>" --json
 三者共享同一份本机任务存储与按目录划分的队列（`~/.nx-kv/localtasks.json`）：
 
 - **kv-submit（本 skill）**：提交侧——总结上下文、提炼需求、投递到别的目录。
-- **kv-waittask**：等待侧——目标目录的 agent 用 wait 阻塞接任务（人机接力）。
-- **kv-localget**：领取侧——目标目录的 agent 主动领队列里的任务。
+- **kv-get**：领取侧——目标目录的 agent 领活（get）、等人接力（wait）、标完成（done）、按反馈重开（reopen）。
 - **nx-kv**：远程 KV 后端的 todo 清单（需登录、按 groupId 隔离），与本机队列无关。
 
 ## 安装
 
 ```bash
 nx-kv skill install kv-submit         # 装到 ~/.claude/skills/kv-submit
-nx-kv skill list                       # 列出 nx-kv / kv-waittask / kv-submit / kv-localget
+nx-kv skill list                       # 列出 nx-kv / kv-get / kv-submit / kv-repo
 ```

package/assets/nx-kv/references/repo-registry.md

@@ -8,7 +8,7 @@
 - 需要把某个目录登记为受管仓库，或扫描某目录批量发现仓库
 - 需要维护仓库的元信息：名称、描述、备注，或改登记路径
 - **需要 git 状态、差异、拉取、推送时不要进这里**——开发仓库不做 git 操作（见下）
-- **要搜索并克隆参考项目时用 [[kv-repo-mmx-gitrepo]]**——那是参考仓库的克隆 SOP
+- **要搜索并克隆参考项目时用 [[kv-repo]]**——那是参考仓库的克隆与**强制读** SOP
 - **只查分组与关系（不改动）时用 [[kv-repo]]**——那是仓库组的查询/报告侧
 
 ## 边界：git 操作只给参考仓库
@@ -76,7 +76,7 @@ git -C <path> pull --no-edit
 mmx-research-gitclone 的整体吸纳（2026-10-27）：远程 clone 下来学习/参考的仓库与
 开发仓库同住中心清单，但统一存放在 `gitRepoRoot`（`nx-kv setting set --gitRepoRoot <非C盘目录>`，
 **不设置则 clone 显式拒绝**——绝不默默堆进用户目录）。完整搜索→克隆 SOP 见
-[[kv-repo-mmx-gitrepo]]；这里登记命令面的速查：
+[[kv-repo]]；这里登记命令面的速查：
 
 ```bash
 nx-kv repo ref clone <url> [--name N] [--desc D] [--board <看板id>] [--bind <开发仓库>] [--depth 1] [--no-bind]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-kv",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "nx-kv — KV 清单管理中枢（远程）+ 本机本地任务队列（localtask）：serve 驱动 CLI 与 Web 面板，同源同构，附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务",
   "type": "module",
   "bin": {
@@ -52,6 +52,7 @@
     "vite": "^8.3.0"
   },
   "dependencies": {
+    "flexlayout-react": "0.11.1",
     "react": "^19.3.0",
     "react-dom": "^19.3.0"
   }