nx-kv
v0.65.4
Published
nx-kv — 本机任务队列(localtask)+ 文档库 + 仓库登记:serve 驱动 CLI 与 Web 面板,同源同构,附带可安装 skill 供 agent 提交 / 领取 / 阻塞接收任务
Maintainers
Readme
nx-kv
本机任务队列 + 文档库 + 仓库登记的一体化工具。一个 npx 命令起一个 Web 面板,同时提供同构 CLI——
面板上的每个按钮,底层都是同一条 CLI 命令,输出 --json 即可被任何 agent 直接消费。
所有数据都在本机 SQLite(~/.nx-kv/nxkv.db,schema v8),不需要登录、不访问任何后端。
附件同样只落本机附件仓;没有云端图床、没有同步开关。
任务正文可以直接嵌图片与文档(标准 markdown: / [文件名](fileId)):
- 图片 / 文件:字节在本机附件仓(
~/.nx-kv/attachments/local/),交付时直接给绝对路径; - 文档(ref):DB 实体(
refs+ref_bodies+ref_bindings),有 desc 与归属,没有文件路径。
术语(速查)
完整术语以 assets/nx-kv/SKILL.md 为准。
- 主题(topic):任务队列容器,由「完整 cwd + 项目组」派生;一个主题只属于一个仓库。
- 本地任务(task):
tasks行,主题内用seq编号;生命周期 pending / claimed / done / cancelled。 - 项目组(group):
repos.type='group';CLI 命令名沿用board,概念名统一为项目组。 - 仓库(repo):
repos.type='repo',UI 里也叫「项目」。 - 参考仓库(ref repo):
repos里参考身份的行(storetype=ref),可绑项目组或仓库;不是文档库。 - 文档(ref):
refs行 + 正文(ref_bodies)+ 归属(ref_bindings);id 是稳定地址,desc 是快速定位。 - 附件(attachment):
attachments行,kind 为 file / url / task / ref / mdfile。 - md 文件(mdfile):磁盘上的外部
.md路径指针,属于附件逻辑;与文档(ref)是两回事。 - 看板(board):项目组的历史别名;CLI / frontmatter 保留,实体名用项目组。
- 提示词区块(block):context / attachment / timecheck / goalhint / ext / ack / getloop,共用一份 ctx。
快速开始
给 agent(全自动安装):把下面这段原文丢给任何 agent,它会自己配环境、装包、装 skill、 启动面板并自检——参考现代 agent 产品的一键入场做法:
「读取 https://raw.githubusercontent.com/On-DevPlan/nx-kv/main/assets/nx-kv/QUICKSTART.md , 按 SOP 安装 nx-kv(没有 node/npm 就先配环境),安装 nx-kv skill 到你的用户 skills 目录, 启动面板并告诉我它能做什么。」
SOP 全文见 assets/nx-kv/QUICKSTART.md
(npm 包内同路径;安装后位于 $(npm root -g)/nx-kv/assets/nx-kv/)。
给人类(本机开发):
pnpm install
# 开发模式(一条命令:vite + 后端一起起,ctrl-c 一起退)
pnpm dev # vite :5181 + 后端 :7877,/api 自动代理到后端实际端口
# 只想跑其中一半时
pnpm run dev:serve # 只起后端 :7877
pnpm run vite # 只起 Vite :5181(等价于 npx vite)
# 生产模式
pnpm start # 构建 + 起面板
# 校验:lint + 类型检查 + 构建 + 98 项端到端冒烟 + 934 项单元/一致性测试
pnpm test常用命令
# 领活:有任务立即领走;没有立即 timeout(不阻塞)
nx-kv localtask get --json
# → { status:"ok", task:{ id, text, attachments? }, instruction:"…" } 或 { status:"timeout" }
# 等人:阻塞等到下一条任务(本轮最后一步;timeout 是业务结果,exit 0)
nx-kv localtask get --timeout 180 --json
# 查看 / 投递 / 完成 / 重开
nx-kv localtask show --id <n> --json
nx-kv localtask add "正文(Markdown)" --json
nx-kv localtask add "长任务" --duration 2h --goal-prompt "先写测试" --json
nx-kv localtask done --id <n> --summary "改了什么 / 怎么验证 / 遗留问题" --json
nx-kv localtask reopen --id <n> --text "<新正文>" --jsonget 是领取动词(改状态、带时间目标会起表);查看一律用 show,要预览交付又不领取用 preview。
完整命令表由 action 声明自动生成:nx-kv help;命令与 HTTP 端点互相可查:nx-kv routes。
队列与主题
nx-kv localtask list --json # 全部主题:目录、现状、等待中、待领取数
nx-kv localtask update --id <n> --text "<新内容>" # 改正文(未领取时)
nx-kv localtask reorder --id <n> --before-id <m> # 调序
nx-kv localtask remove --id <n> # 软删除(task restore 可恢复)
nx-kv localtask chain --id <n> --json # 任务链(history + fork)
nx-kv localtask topic add --cwd <目录> # 建主题
nx-kv localtask topic remove --cwd <目录> --force # 删主题(有未领取任务默认拒绝)
nx-kv localtask prune --days 30 --json # 清理旧终态任务不带 --cwd / --key 时按进程当前目录定位。同一目录同一时刻只挂一个 wait;
get 与 wait 不要并发跑(都在同一队列上抢任务)。
附件(全部本机)
任务正文用标准 markdown 引用附件:
修一下首页 logo  # 图片
补充材料见 [需求说明.docx](b71e…04.docx) # 其他文件括号里是本机附件仓的 fileId(32 位 hex)。http(s)://、相对路径不算附件。
nx-kv file upload --path "D:\设计\首页.png" --json # 落本机附件仓,返回 fileId + markdown 片段
nx-kv localtask attach --id 3 --path "D:\doc\需求.docx" # 上传并嵌入正文
nx-kv localtask attach --id 3 --fileId <fileId> # 引用已有附件
nx-kv localtask attach --id 3 --url https://example.com # 外链
nx-kv localtask attach --id 3 --task 7 # 同主题任务引用
nx-kv localtask attach --id 3 --ref <refId> [--inline] # 文档绑定(--inline 交付带全文)
nx-kv localtask attach --id 3 --mdfile "D:\doc\方案.md" # 本地 md 路径指针
nx-kv localtask attach --id 3 --path "D:\doc\需求.docx" --no-embed # 只挂附件区
nx-kv localtask attachments --id 3 --json # 清单(含本地绝对路径)
nx-kv localtask detach --id 3 --attachment <id> # 解除关系没有 file sync、没有自动下载开关、没有云端图床:上传即落盘,命中即给 localPath;
未命中时清单会明确写「本机附件仓没有这个文件」。
清理无主资源:
nx-kv file orphans --json # 没有被任何任务/文档引用的上传
nx-kv file prune --dry-run # 先看
nx-kv file prune # 回收(DB 行 + 附件根内的字节)文档库(refs)
ref 是 DB 实体:refs(id / locator / desc / 归属)+ ref_bodies(正文)+ ref_bindings(挂在哪)。
没有文件路径,也没有逻辑名:地址只有 refs.id(ref_<16hex>)与 refs.locator
(外部文件 / URL 的实际位置);读取一律按 refId:
nx-kv docs list --json
nx-kv docs get --ref <refId> --json # 取正文(只认 refId)
nx-kv docs bindings --host <repoKey> --json # 这个仓库挂了哪些文档
nx-kv docs bindings --group <组> --json # 这个组挂了哪些文档
nx-kv docs ref add --desc "一句话描述" --owner repo --repo <key> # 新建直接 ref
nx-kv docs ref unbind --ref <refId> # 解绑(不删文档)提示词模板只会自动内嵌仓库主篇;其余文档给 refId + desc,由 agent 自己
nx-kv docs get --ref <refId> 按需取。ref.desc 是快速定位标签,ref.title 是正文首行标题。
时间目标(timegoal)
把「AI 持续运行 N 小时」这类长任务固化到工具里,而不是散落在外部脚本:
# 目录级:3 小时 + 完整提示词(提示词原文固化)
nx-kv timegoal set --cwd "$PWD" --duration 3h --prompt "<完整全局提示词>" --json
# 每轮调一次:算出还剩多少时间,并原文回显提示词
nx-kv timegoal check --cwd "$PWD" --summary "<当前现状>" --json
# 任务级:领取即计时,未到点 done 会被 blocked
nx-kv localtask add "长任务" --duration 2h --json
nx-kv timegoal check --task task:<topicKey>:<taskId> --summary "<本轮现状>" --json到点(reached:true)后再 done;未到点被拒绝时按 hint 派 sub agent 重提需求,不要硬标完成。
目录级目标存 settings.tg.cwd.<topicKey>,任务级存 goals / goal_checks 表;两者可同时跑。
定位与排错
- 主题内任务用
--id <n>;跨主题引用写"<topicKey>:<id>"。 - 不带
--cwd/--key时按进程当前目录定位;先localtask list确认主题。 localtask get --timeout N的timeout是业务结果(exit 0),不是错误;不要当失败重试。- 带时间目标的任务未到点
done返回{status:"blocked"}(exit 0),按 hint 处理。 - 详细命令、返回结构、避坑见 assets/nx-kv/references/localtask-commands.md。
架构:action 三端同源
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Web 面板 │ │ agent CLI │ │ HTTP API │
└───────┬──────┘ └───────┬──────┘ └───────┬──────┘
└──────────────────┼──────────────────┘
▼
┌──────────────────────────────────────────┐
│ action 声明(每个功能域的 actions/) │
│ { cli: [...], http: [...], run, render } │
└──────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────┐
│ service 层(唯一业务真相源) │
└──────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────┐
│ core:SQLite / 本机附件 / 配置 / 错误 │
└──────────────────────────────────────────┘一条 action 同时声明 CLI 命令路径与 HTTP 路由,二者写在同一处, 所以「Web 上能做的,CLI 都能做」是结构保证而非口头约定。
src/core/ 零业务语义:db(SQLite) / localatt / filekind / config / errors / paths
src/shared/ 同构纯函数:附件语法 / 双链 / frontmatter / 提示词区块——Node 与浏览器加载同一份,零依赖
src/modules/ 功能域:system / setting / bundled / db / docs / file / localtask / repos / tasktool / templates
src/runtime/ 装配层:registry / spec / cli / api / server
src/web/frontend/ React 壳(视图全在这里,后端不知道它们的路径)
assets/nx-kv/ 内置 skill:本机任务 / 文档 / 仓库总手册
assets/kv-get/ 内置 skill:领取本目录本地任务
assets/kv-submit/ 内置 skill:需求提炼与委托提交
assets/kv-repo/ 内置 skill:仓库 / 项目组 / 参考仓库管理分层由 eslint.config.js 的 no-restricted-imports 与 tests/unit/layering.test.mjs 双重强制:
core ← 谁都不依赖 shared ← 零依赖(不许 node: / 第三方包)
modules ← core + shared runtime ← 装配全部 web ← 只有 shared前端够不着 modules / runtime / core——它消费后端的唯一方式就是 HTTP /api。
tests/unit/registry.test.mjs 断言模块目录 ↔ 后端注册表 ↔ 前端视图注册表三方对齐,
并检查面板里出现的每个 /api 路径都真实存在。
给 agent 用
nx-kv skill install # 装到 ~/.claude/skills/nx-kv(本机任务总手册)
nx-kv skill install kv-get # 领取侧:主动领取排给本目录的任务
nx-kv skill install kv-submit # 提交侧:总结上下文、提炼需求,委托别的 agent
nx-kv skill install kv-repo # 仓库 / 项目组 / 参考仓库管理
nx-kv skill list # 列出可装 skill、默认安装项与可装 group
nx-kv skill groups # 列出 group → 包含哪些 skill
nx-kv skill install --group=<key> # 一键装整组(与 <name> 二选一)
nx-kv skill get [name] [ref] # 输出 skill 全文,外部 agent 一键拿上下文装好后 agent 就能按 skill 里的 SOP 领任务、读 instruction、完成后回填结果;
或在一个对话里靠 localtask get --timeout N 阻塞等待、连续接收用户任务,
把需求提炼成任务 add 到别的目录委托其它 agent。
License
MIT
