dsh-offhours 0.1.0 → 0.1.2

package/README.md

@@ -3,7 +3,7 @@
 DeepSeek Harness 社区插件：把看板里的待办，在**低谷/夜间**自动做掉。
 
 - 只做一件事：`todo` 卡 → 每卡一个独立 git worktree → headless worker 干活并自证 → 证据写回卡 → 合并回收。
-- 不需要 cron/systemd：插件进程内按 interval 自己扫；也可以手动 `offhours run --once`。
+- 不需要 cron/systemd：插件进程内按 interval 自己扫；也可以手动 `npx dsh-offhours run --once`。
 - 你的数据只在本地：看板是 `KANBAN.json`，状态/日志在 `stateDir`，不上传。
 
 ## 安装
@@ -14,26 +14,32 @@ dsh plugin --profile web add dsh-offhours
 
 装完重启一次 `dsh web`（或让 HMR 生效），左侧出现「夜间跑批」面板。
 
+> 为什么下面的命令写 `npx dsh-offhours`：安装插件不会把 CLI 加进全局 PATH；`npx` 会直接运行刚装好的同一个入口（首次会从 npm 取包）。如果你已经全局安装，可以简写成 `offhours`。
+
 ## 三步开始
 
 ```bash
 # 1) 在你要跑批的 git 仓库里初始化（写配置 + 建/关联特性 + 生成看板）
 cd ~/code/myapp
-offhours init --repo . --name myapp
+npx dsh-offhours init --repo . --name myapp
 
 # 2) 体检（依赖、路径、worker 权限）
-offhours doctor
+npx dsh-offhours doctor
 
 # 3) 建一张卡（自动盖当前会话；没有 session 的卡跑批不会捡）
-offhours card add "给登录页补错误提示" \
+npx dsh-offhours card add "给登录页补错误提示" \
   --summary "目标：登录失败有提示。判据：npm test 通过。不做什么：不改后端。"
 ```
 
-之后低谷时段自动跑；也可以用面板「立即跑」或 `offhours run --once`。
+之后低谷时段自动跑；也可以用面板「立即跑」或 `npx dsh-offhours run --once`。
+
+如果打开面板看到「先完成一次性初始化」，说明配置还没生成：在项目仓库执行上面的 `init`，刷新面板即可；不需要重装插件。
+
+装完/升级插件后记得重启一次 `dsh web`，面板才会加载新代码。
 
 ## 配置
 
-`~/.dsh/offhours/config.json`（`offhours init` 生成）：
+`~/.dsh/offhours/config.json`（`npx dsh-offhours init` 生成）：
 
 ```json
 {
@@ -62,13 +68,15 @@ offhours card add "给登录页补错误提示" \
 
 | 命令 | 作用 |
 |---|---|
-| `offhours init --repo .` | 初始化配置/看板/特性 |
-| `offhours doctor` | 依赖与权限体检（失败退出非 0） |
-| `offhours card add "<标题>" --summary "<目标/判据/边界>"` | 建卡并盖章当前会话 |
-| `offhours card list` | 列卡 |
-| `offhours run --once` / `--dry-run` | 手动跑一轮 / 只看会挑哪张 |
-| `offhours status` | 看板计数、心跳、最近状态（JSON） |
-| `offhours boards` | 看板列表 |
+| `npx dsh-offhours init --repo .` | 初始化配置/看板/特性 |
+| `npx dsh-offhours doctor` | 依赖与权限体检（失败退出非 0） |
+| `npx dsh-offhours card add "<标题>" --summary "<目标/判据/边界>"` | 建卡并盖章当前会话 |
+| `npx dsh-offhours card list` | 列卡 |
+| `npx dsh-offhours run --once` / `--dry-run` | 手动跑一轮 / 只看会挑哪张 |
+| `npx dsh-offhours status` | 看板计数、心跳、最近状态（JSON） |
+| `npx dsh-offhours boards` | 看板列表 |
+
+> 不想走 npx：装完后 CLI 也在 profile 的 `node_modules/.bin/offhours`（例如 `~/.dsh/profiles/web/node_modules/.bin/offhours`），可以直接用绝对路径调用。
 
 ## 依赖
 

package/bin/offhours.mjs

@@ -20,15 +20,16 @@ import {
 
 const HELP = `dsh-offhours —— 夜间/低谷自动跑批（配一个 git 仓库就能用）
 
-用法：
-  offhours init --repo <git仓库路径> [--name 名称] [--board KANBAN.json] [--feature 特性名]
-  offhours doctor
-  offhours card add "<标题>" --summary "<目标/判据>" [--tags auto] [--board id]
-  offhours card list [--board id]
-  offhours run [--once] [--dry-run] [--force] [--board id]
-  offhours status [--board id]
-  offhours boards
+装完插件后不需要全局安装 CLI，用 npx 调用即可：
+  npx dsh-offhours init --repo <git仓库路径> [--name 名称] [--board KANBAN.json] [--feature 特性名]
+  npx dsh-offhours doctor
+  npx dsh-offhours card add "<标题>" --summary "<目标/判据>" [--tags auto] [--board id]
+  npx dsh-offhours card list [--board id]
+  npx dsh-offhours run [--once] [--dry-run] [--force] [--board id]
+  npx dsh-offhours status [--board id]
+  npx dsh-offhours boards
 
+如果你已经全局安装了本包，也可以把 npx dsh-offhours 换成 offhours。
 全局：--config <path>（默认 ~/.dsh/offhours/config.json）
 
 约束：worker 需要 dsh、python3、bash、git、jq、flock；zstd 可选（成本统计）。
@@ -53,14 +54,14 @@ function parse(argv) {
 }
 
 function die(msg, code = 1) {
-  console.error(`offhours: ${msg}`)
+  console.error(`dsh-offhours: ${msg}`)
   process.exit(code)
 }
 
 function loadOrDie(flags) {
   const { config, path, exists } = loadConfig(flags.config)
-  if (!exists) die(`没有配置：${path}\n先运行：offhours init --repo <git仓库路径>`)
-  if (!config.boards.length) die(`配置里没有看板：${path}\n先运行：offhours init --repo <git仓库路径>`)
+  if (!exists) die(`没有配置：${path}\n先运行：npx dsh-offhours init --repo <你的 git 仓库>`)
+  if (!config.boards.length) die(`配置里没有看板：${path}\n先运行：npx dsh-offhours init --repo <你的 git 仓库>`)
   return { cfg: config, path }
 }
 
@@ -104,8 +105,13 @@ function cmdInit(flags) {
     writeFileSync(boardFile, '{\n  "version": 1,\n  "cards": []\n}\n', 'utf8')
   }
   mkdirSync(cfg.featuresRoot, { recursive: true })
+  // 合并已有登记表：init 一个新仓库不能把用户之前登记的仓库冲掉。
+  let registry = {}
+  try { registry = JSON.parse(readFileSync(join(cfg.featuresRoot, '.repos.json'), 'utf8')) || {} } catch { /* 首次初始化 */ }
+  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) registry = {}
+  registry[name] = { path: repo, baseBranch: base }
   writeFileSync(join(cfg.featuresRoot, '.repos.json'),
-    JSON.stringify({ [name]: { path: repo, baseBranch: base } }, null, 2) + '\n', 'utf8')
+    JSON.stringify(registry, null, 2) + '\n', 'utf8')
   saveConfig(cfgPath, cfg)
 
   const env = {
@@ -118,6 +124,13 @@ function cmdInit(flags) {
   let r = spawnSync(fb, args, { env, encoding: 'utf8' })
   if (r.status !== 0) r = spawnSync(fb, ['ensure', feature, '--repos', name], { env, encoding: 'utf8' })
   const featOut = String((r.stdout || r.stderr || '').trim()).split('\n').slice(-2).join('\n')
+  // feature CLI 可能把登记表改写成字符串；补回 baseBranch，且不丢已有仓库。
+  try {
+    let reg2 = JSON.parse(readFileSync(join(cfg.featuresRoot, '.repos.json'), 'utf8')) || {}
+    if (!reg2 || typeof reg2 !== 'object' || Array.isArray(reg2)) reg2 = {}
+    reg2[name] = { path: repo, baseBranch: base }
+    writeFileSync(join(cfg.featuresRoot, '.repos.json'), JSON.stringify(reg2, null, 2) + '\n', 'utf8')
+  } catch { /* 保留 feature 的写法 */ }
 
   console.log(`✓ 配置：${cfgPath}`)
   console.log(`✓ 仓库：${name} → ${repo}（基准分支 ${base}）`)
@@ -126,13 +139,17 @@ function cmdInit(flags) {
   if (featOut) console.log(featOut)
   console.log('')
   console.log('下一步：')
-  console.log(`  offhours doctor`)
-  console.log(`  offhours card add "第一张卡" --summary "目标/判据/不做什么"`)
-  console.log(`  offhours run --once`)
+  console.log('  npx dsh-offhours doctor')
+  console.log('  npx dsh-offhours card add "第一张卡" --summary "目标/判据/不做什么"')
+  console.log('  npx dsh-offhours run --once')
 }
 
 function cmdDoctor(flags) {
-  const { config: cfg, path } = loadConfig(flags.config)
+  const { config: cfg, path, exists } = loadConfig(flags.config)
+  if (!exists) {
+    console.log(`未配置：${path}`)
+    console.log('先运行：npx dsh-offhours init --repo <你的 git 仓库>')
+  }
   const rows = []
   const fail = []
   const hard = (name, ok, detail = '') => {

package/lib/client.js

@@ -1001,6 +1001,7 @@ window.__ModuleLoader__.load({
       const reviews = Array.isArray(data.reviews) ? data.reviews : []
       const running = Array.isArray(data.running) ? data.running : []
       const recent = data.recent || {}
+      const setup = data.setup || {}
       const problems = (Array.isArray(data.problems) ? data.problems : []).filter(
         // 「定时器当前是 active」是正常状态，不该显示成提示（旧版宿主会多带一个换行）
         (p) => !/当前是\s*active\b/.test(String(p)),
@@ -1065,7 +1066,7 @@ window.__ModuleLoader__.load({
             h('span', { style: { fontSize: 12, color: T.textSub } }, t('boardLabel')),
             ...(Array.isArray(snap.data && snap.data.boards) && snap.data.boards.length
               ? snap.data.boards
-              : [{ key: 'ops', label: 'ops', path: '/root/ops/KANBAN.json' }]
+              : []
             ).map((b) =>
               h(
                 Button,
@@ -1086,6 +1087,33 @@ window.__ModuleLoader__.load({
           h('div', { style: { display: 'flex', gap: 6, flexWrap: 'wrap', marginTop: 4 } }, chips),
         ),
 
+        setup.configured === false
+          ? h(
+              'div',
+              {
+                style: {
+                  ...cardStyle, borderColor: T.brand, fontSize: 12, lineHeight: 1.65,
+                  display: 'flex', flexDirection: 'column', gap: 6,
+                },
+              },
+              h('div', { style: { fontWeight: 700, fontSize: 13, color: T.text } }, t('setupTitle')),
+              h('div', { style: { color: T.textSub } }, t('setupBody')),
+              h(
+                'code',
+                {
+                  style: {
+                    fontSize: 12, padding: '7px 9px', borderRadius: 8, background: T.fill,
+                    border: `1px solid ${T.borderStrong}`, wordBreak: 'break-all',
+                  },
+                },
+                setup.initCommand || 'npx dsh-offhours init --repo .',
+              ),
+              h('div', { style: { color: T.textSub } }, t('setupAfter')),
+              setup.configPath
+                ? h('div', { style: { color: T.textSub, wordBreak: 'break-all' } }, `${t('setupConfigPath')} ${setup.configPath}`)
+                : null,
+            )
+          : null,
         snap.error
           ? h('div', { style: { ...cardStyle, borderColor: T.danger, color: T.danger, fontSize: 12 } }, snap.error)
           : null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-offhours",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "DSH 社区插件：把看板待办在低谷/夜间自动做掉（挑卡 → 独占 worktree → worker → 证据 → 合并回收），只依赖配置里的 git 仓库。",
   "type": "module",
   "license": "MIT",
@@ -11,7 +11,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "offhours": "./bin/offhours.mjs"
+    "offhours": "./bin/offhours.mjs",
+    "dsh-offhours": "./bin/offhours.mjs"
   },
   "files": [
     "bin/offhours.mjs",
@@ -69,10 +70,10 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jingyichushi/dsh-offhours.git"
+    "url": "git+https://github.com/shuke52tt/dsh-offhours.git"
   },
-  "homepage": "https://github.com/jingyichushi/dsh-offhours#readme",
+  "homepage": "https://github.com/shuke52tt/dsh-offhours#readme",
   "bugs": {
-    "url": "https://github.com/jingyichushi/dsh-offhours/issues"
+    "url": "https://github.com/shuke52tt/dsh-offhours/issues"
   }
 }

package/panel/client.js

@@ -1001,6 +1001,7 @@ window.__ModuleLoader__.load({
       const reviews = Array.isArray(data.reviews) ? data.reviews : []
       const running = Array.isArray(data.running) ? data.running : []
       const recent = data.recent || {}
+      const setup = data.setup || {}
       const problems = (Array.isArray(data.problems) ? data.problems : []).filter(
         // 「定时器当前是 active」是正常状态，不该显示成提示（旧版宿主会多带一个换行）
         (p) => !/当前是\s*active\b/.test(String(p)),
@@ -1065,7 +1066,7 @@ window.__ModuleLoader__.load({
             h('span', { style: { fontSize: 12, color: T.textSub } }, t('boardLabel')),
             ...(Array.isArray(snap.data && snap.data.boards) && snap.data.boards.length
               ? snap.data.boards
-              : [{ key: 'ops', label: 'ops', path: '/root/ops/KANBAN.json' }]
+              : []
             ).map((b) =>
               h(
                 Button,
@@ -1086,6 +1087,33 @@ window.__ModuleLoader__.load({
           h('div', { style: { display: 'flex', gap: 6, flexWrap: 'wrap', marginTop: 4 } }, chips),
         ),
 
+        setup.configured === false
+          ? h(
+              'div',
+              {
+                style: {
+                  ...cardStyle, borderColor: T.brand, fontSize: 12, lineHeight: 1.65,
+                  display: 'flex', flexDirection: 'column', gap: 6,
+                },
+              },
+              h('div', { style: { fontWeight: 700, fontSize: 13, color: T.text } }, t('setupTitle')),
+              h('div', { style: { color: T.textSub } }, t('setupBody')),
+              h(
+                'code',
+                {
+                  style: {
+                    fontSize: 12, padding: '7px 9px', borderRadius: 8, background: T.fill,
+                    border: `1px solid ${T.borderStrong}`, wordBreak: 'break-all',
+                  },
+                },
+                setup.initCommand || 'npx dsh-offhours init --repo .',
+              ),
+              h('div', { style: { color: T.textSub } }, t('setupAfter')),
+              setup.configPath
+                ? h('div', { style: { color: T.textSub, wordBreak: 'break-all' } }, `${t('setupConfigPath')} ${setup.configPath}`)
+                : null,
+            )
+          : null,
         snap.error
           ? h('div', { style: { ...cardStyle, borderColor: T.danger, color: T.danger, fontSize: 12 } }, snap.error)
           : null,

package/panel/index.js

@@ -322,6 +322,7 @@ async function buildStatus(boardArg) {
     if (Number.isFinite(n)) windowLeft = n
   } catch { /* 忽略：面板降级为不显示余量 */ }
   const COOLDOWN_MIN = cooldownMinFor(board)
+  const configured = !!(CFG._path && existsSync(CFG._path) && Array.isArray(CFG.boards) && CFG.boards.length > 0)
   const out = {
     ok: true,
     now: fmtLocal(now),
@@ -341,6 +342,13 @@ async function buildStatus(boardArg) {
     running: [],
     recent: { log: [], receipt: null, runs: [] },
     problems: [],
+    setup: {
+      configured,
+      configPath: CFG._path || '',
+      initCommand: 'npx dsh-offhours init --repo .',
+      doctorCommand: 'npx dsh-offhours doctor',
+      restartHint: '安装或更新插件后重启 dsh，面板才会加载新代码。',
+    },
   }
 
   // SCHEDULER-REPORT：按配置的调度方式如实报告（systemd / 插件内 interval）。
@@ -379,7 +387,7 @@ async function buildStatus(boardArg) {
       }
     } catch { out.problems.push('systemctl 查询失败（定时器状态未知）') }
   }
-  if (CFG.scheduler === 'plugin' && out.timer.active === 'unknown') {
+  if (configured && CFG.scheduler === 'plugin' && out.timer.active === 'unknown') {
     out.problems.push('插件内调度器没有心跳（确认 dsh 进程在跑，或 schedule.enabled=false）')
   }
 
@@ -544,6 +552,15 @@ async function buildStatus(boardArg) {
     out.recent.runs = []
   }
 
+  if (!configured) {
+    // 未配置时只展示 setup 卡片；不要把空 path 触发的“看板读不到/冷却未知”当错误吓用户。
+    out.problems = []
+    out.todos = []
+    out.reviews = []
+    out.running = []
+    out.recent = { log: [], receipt: null, runs: [] }
+    out.timer.raw = 'unconfigured'
+  }
   return out
 }
 

package/panel/locale/en.json

@@ -77,6 +77,10 @@
     "liveEmpty": "No output yet",
     "liveFollow": "auto-follow",
     "runningNowText": "Running now:",
-    "openWorkerSession": "Open worker session"
+    "openWorkerSession": "Open worker session",
+    "setupTitle": "One-time setup",
+    "setupBody": "Run this inside the git repository you want to batch:",
+    "setupAfter": "Then reload or restart dsh. The board appears here; work only starts off-peak while the machine is idle.",
+    "setupConfigPath": "Config file:"
   }
 }

package/panel/locale/zh.json

@@ -77,6 +77,10 @@
     "liveEmpty": "还没有输出（等它开始吐字）",
     "liveFollow": "自动跟随最新",
     "runningNowText": "正在跑批：",
-    "openWorkerSession": "打开处理会话（对话/轨迹）"
+    "openWorkerSession": "打开处理会话（对话/轨迹）",
+    "setupTitle": "先完成一次性初始化",
+    "setupBody": "在要跑批的 git 仓库里运行：",
+    "setupAfter": "然后刷新或重启 dsh；左侧会出现看板，只有低谷且机器空闲时才会自动跑。",
+    "setupConfigPath": "配置文件："
   }
 }

package/skills/offhours/SKILL.md

@@ -17,10 +17,11 @@ description: "夜间/低谷自动跑批（dsh-offhours）：把看板待办在
 ## 建卡（唯一正确入口）
 
 ```bash
-offhours card add "<标题>" --summary "<目标 + 判据(命令) + 涉及面 + 不做什么>"
+npx dsh-offhours card add "<标题>" --summary "<目标 + 判据(命令) + 涉及面 + 不做什么>"
 ```
 
 - 必须在 dsh 会话里执行：它会用 `DSH_SESSION_ID` 盖章 `sourceSessionId`；
+- CLI 没进全局 PATH：统一用 `npx dsh-offhours ...`（或 profile 里的 `node_modules/.bin/offhours`）。
   **没有 sourceSessionId 的卡跑批永远不会捡**（不是 bug，是隔离要求）。
 - 用 dsh-kanban 的 `board_add` 建的卡不带 session，只适合人工看板，不适合跑批。
 - 判据必须是命令，不是形容词；一张卡 = 一个可独立合并的成果。
@@ -28,10 +29,10 @@ offhours card add "<标题>" --summary "<目标 + 判据(命令) + 涉及面 +
 ## 查状态 / 手动跑
 
 ```bash
-offhours doctor          # 依赖、配置、权限体检（先跑这个）
-offhours status          # 看板计数 + 心跳 + 最近状态（JSON）
-offhours run --once      # 手动跑一轮（生产调度器之外）
-offhours run --dry-run   # 只看会挑哪张，不启动 worker
+npx dsh-offhours doctor          # 依赖、配置、权限体检（先跑这个）
+npx dsh-offhours status          # 看板计数 + 心跳 + 最近状态（JSON）
+npx dsh-offhours run --once      # 手动跑一轮（生产调度器之外）
+npx dsh-offhours run --dry-run   # 只看会挑哪张，不启动 worker
 ```
 
 面板：dsh Web 左侧「夜间跑批」；`/offhours` 命令也可查状态。