@xdxer/dingtalk-agent 0.1.0

package/src/init.js

@@ -0,0 +1,84 @@
+// init —— 在工作区里铺一个数字员工。
+//
+// 包里带的是【工具 + 行为范式】；本体和运行记录是 init 在【你的工作区】里生成的。
+// 所以这个包能发 npm，而你的 agent 是你自己的 git 仓库。
+
+import { mkdirSync, cpSync, existsSync, writeFileSync, symlinkSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import * as cfg from './config.js'
+
+const PKG = dirname(dirname(fileURLToPath(import.meta.url)))
+
+export function init(root) {
+  if (cfg.load(root)) {
+    console.log('已经初始化过了。看看: dingtalk-agent kb list')
+    return
+  }
+
+  // 行为范式（skills）+ 本体模板（ontology/self 三件套）
+  cpSync(join(PKG, 'skills'), join(root, 'skills'), { recursive: true })
+  cpSync(join(PKG, 'templates', 'ontology'), join(root, 'ontology'), { recursive: true })
+  for (const d of ['ontology/sources', 'ontology/wiki', 'runs', '.cache/kb']) {
+    mkdirSync(join(root, d), { recursive: true })
+  }
+
+  // AGENTS.md ← skills/AGENTS.md；CLAUDE.md 是它的符号链接
+  // **任何 Coding Agent 读到的协议完全一致。**
+  const agents = join(root, 'AGENTS.md')
+  if (!existsSync(agents)) {
+    writeFileSync(agents, `<!-- 正本在 skills/AGENTS.md -->\n\n` +
+      `# 先读这个\n\n` +
+      `\`\`\`bash\ndingtalk-agent boot\n\`\`\`\n\n` +
+      `然后读 [skills/AGENTS.md](skills/AGENTS.md) —— 我是谁、我怎么做事。\n\n` +
+      `**BOOT FAIL 时禁答身份/能力/记忆/知识类问题。** 不要猜，不要找替代路径。\n`)
+  }
+  const claude = join(root, 'CLAUDE.md')
+  if (!existsSync(claude)) {
+    try { symlinkSync('AGENTS.md', claude) } catch { cpSync(agents, claude) }
+  }
+
+  const gi = join(root, '.gitignore')
+  if (!existsSync(gi)) {
+    writeFileSync(gi, [
+      '# 知识库缓存：external 的真值在远端，本地这份【可丢弃】',
+      '.cache/',
+      '',
+      '# 运行记录：含对话原文、人名。本地留档，不进仓库',
+      'runs/*',
+      '!runs/.gitkeep',
+      '',
+      '# 配置：含硬 ID，一岗一份',
+      '.dingtalk-agent/',
+      '',
+      '# 原始证据里的敏感原文',
+      'ontology/sources/private/',
+      '',
+      'node_modules/',
+      '.DS_Store',
+      '',
+    ].join('\n'))
+  }
+  writeFileSync(join(root, 'runs', '.gitkeep'), '')
+
+  cfg.save(root, cfg.DEFAULT)
+
+  console.log(`✅ 铺好了
+
+  AGENTS.md         先读这个（CLAUDE.md 是它的符号链接）
+  skills/           行为范式：消息 · 任务 · 心跳 · 知识 · 钉钉 · 评测
+  ontology/self/    ★ 三件套 —— 我是谁 · 工牌 · 工位
+  ontology/wiki/    编译层（越干越有经验的地方）
+  runs/             运行记录（三个硬 ID，反查得到才算数）
+
+接下来三步（**顺序不能换**）:
+
+  1. 填 ontology/self/ 的三件套。**没填完 boot 会拒绝启动。**
+     一个「半个记忆」的员工，比一个明确说「我还没醒」的员工危险得多。
+
+  2. 挂知识库:
+     dingtalk-agent kb mount --name 公司知识库 --from dingtalk:doc:<folderId> --own external
+     dingtalk-agent kb mount --name 本体 --from dingtalk:doc:<folderId> --own owned --local ontology
+
+  3. dingtalk-agent boot     ← 它会【真去摸一遍工位】，拉不到就 BOOT FAIL`)
+}

package/src/kb.js

@@ -0,0 +1,221 @@
+// 知识库挂载与同步。
+//
+// ════════════════════════════════════════════════════════════════════
+// 【核心判断】所有权决定真值方向。
+// ════════════════════════════════════════════════════════════════════
+//
+//                owned（我的本体）           external（别人维护的）
+//   真值在        **Git**（本地）             **钉钉**（远端）
+//   同步方向      push  本地 → 钉钉           pull  钉钉 → 本地
+//   为什么        给人看（人机同源）           给我 grep（快、能看上下文）
+//   冲突了        远端被人改过 → **停**       远端赢，本地缓存可丢弃
+//   落在          ontology/（入 Git）         .cache/kb/<name>/（gitignore）
+//
+// 这就是「Git 内核 × 钉钉暴露层」：**Git 是常量层，钉钉是可替换的暴露层。**
+//
+// ════════════════════════════════════════════════════════════════════
+// 【三个硬约束】—— 全是踩出来的
+// ════════════════════════════════════════════════════════════════════
+//
+// 1. **绝不双向自动 merge。** 一个方向是真值，另一个是投影。
+//    自动合并两个都在变的东西 = 灾难，而且是【静默】灾难。
+//
+// 2. **重排版不是漂移。** 判据是「剥掉 markdown 符号后的文字流」，不是行级 diff。
+//    用行级 diff → 每次 sync 都误报 → **你就会开始无脑 --force，真漂移也一起覆盖掉。**
+//
+// 3. **缓存不新鲜就不许用（fail-closed）。** external KB 是快照。
+//    **拿着过期快照回答，比说「我不知道」危险得多。**
+
+import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync } from 'node:fs'
+import { readdirSync } from 'node:fs'
+import { join, dirname, relative, basename } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import * as dws from './dws.js'
+
+export const OWNED = 'owned', EXTERNAL = 'external'
+export const PULL = 'pull', PUSH = 'push', NONE = 'none'
+
+/** external 缓存超过这么久就算过期。过期 → kb search 会警告并要求先 sync。 */
+export const STALE_HOURS = 24
+
+const now = () => new Date(Date.now() + 8 * 3600e3).toISOString().replace('Z', '+08:00').slice(0, 19)
+
+/** dingtalk:doc:<folderId> · dingtalk:wiki:<spaceId> · local:<path> */
+export function parseSource(s) {
+  let m = /^dingtalk:(doc|wiki):(.+)$/.exec(s)
+  if (m) return { kind: m[1], id: m[2] }
+  m = /^local:(.+)$/.exec(s)
+  if (m) return { kind: 'local', id: m[1].replace(/^~/, process.env.HOME) }
+  throw new Error(
+    `挂载源写错了: ${s}\n` +
+    `  支持三种:\n` +
+    `    dingtalk:doc:<folderId>    文档文件夹（最常见 —— 很多组织根本没建"知识库"）\n` +
+    `    dingtalk:wiki:<spaceId>    钉钉知识库空间\n` +
+    `    local:<路径>               本地目录（只读挂载，比如另一个仓库的 wiki/）`)
+}
+
+// ════════════════ pull：钉钉 → 本地缓存 ════════════════
+function walkDoc(folder, prefix = '') {
+  const out = []
+  for (const n of dws.nodes(dws.run(['doc', 'list', '--folder', folder, '--page-size', '50']))) {
+    const name = n.name || '', nid = n.nodeId
+    if (n.nodeType === 'folder') { out.push(...walkDoc(nid, join(prefix, name))); continue }
+    if (n.contentType && n.contentType !== 'ALIDOC') continue      // 二进制附件不是知识
+    out.push({ rel: join(prefix, name.endsWith('.md') ? name : `${name}.md`),
+               nid, mtime: n.updateTime || 0 })
+  }
+  return out
+}
+
+function walkWiki(space, folder, prefix = '') {
+  const args = ['wiki', 'node', 'list', '--workspace', space, '--limit', '50']
+  if (folder) args.push('--folder', folder)
+  const out = []
+  for (const n of dws.nodes(dws.run(args))) {
+    const name = n.name || '', nid = n.nodeId
+    if (n.nodeType === 'folder' || n.hasChildren) out.push(...walkWiki(space, nid, join(prefix, name)))
+    out.push({ rel: join(prefix, name.endsWith('.md') ? name : `${name}.md`),
+               nid, mtime: n.updateTime || 0 })
+  }
+  return out
+}
+
+/** 钉钉 → 本地缓存。**远端赢**（external 的真值在远端）。增量靠 updateTime。 */
+export function pull(kb, root, force = false) {
+  const { kind, id } = parseSource(kb.from)
+  if (kind === 'local') { console.log(`  local  ${kb.name}  就在本地，不用同步`); return }
+
+  const dest = join(root, kb.local)
+  const items = kind === 'doc' ? walkDoc(id) : walkWiki(id)
+  if (!items.length) {
+    throw new Error(
+      `「${kb.name}」远端一个节点都没有 —— **不许当成【这个知识库是空的】。**\n` +
+      `  可能是: ID 写错 / 没权限 / 它真的空。先用 dws 手工确认再说。`)
+  }
+  kb._state ??= {}
+  let pulled = 0, skipped = 0
+  for (const { rel, nid, mtime } of items) {
+    const p = join(dest, rel)
+    if (!force && kb._state[nid]?.mtime === mtime && existsSync(p)) { skipped++; continue }
+    const md = dws.readDoc(nid)
+    mkdirSync(dirname(p), { recursive: true })
+    // 头三行钉住来源 —— **没有指针的知识，用的时候不敢信。**
+    writeFileSync(p,
+      `<!-- 来自钉钉 · 只读缓存 · 不要在这里改，改了下次 sync 会被覆盖 -->\n` +
+      `<!-- nodeId: ${nid} -->\n<!-- 拉取: ${now()} -->\n\n${md}`)
+    kb._state[nid] = { rel, mtime }
+    pulled++
+  }
+  kb._syncedAt = now()
+  console.log(`  pull   ${kb.name.padEnd(14)} 拉了 ${pulled} 篇 · 没变 ${skipped} 篇`)
+}
+
+// ════════════════ push：本地 → 钉钉（人机同源）════════════════
+function walkLocal(dir, base = dir) {
+  const out = []
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name)
+    if (e.isDirectory()) { out.push(...walkLocal(p, base)); continue }
+    if (e.name.endsWith('.md')) out.push({ path: p, rel: relative(base, p) })
+  }
+  return out
+}
+
+/**
+ * 本地 → 钉钉。**Git 赢**（owned 的真值在 Git）。
+ *
+ * ⚠️ **推之前先查漂移** —— 远端被人改过就【停下来问】，绝不盲覆盖。
+ *    人在钉钉里改了东西，说明他有话要说。**盲覆盖 = 把人的意见删了。**
+ */
+export function push(kb, root, force = false) {
+  const { kind, id } = parseSource(kb.from)
+  if (kind !== 'doc') {
+    throw new Error('push 目前只支持 dingtalk:doc:<folderId>（文档文件夹）。\n' +
+                    '  知识库空间的写入面还没验过 —— **不许假装支持。**')
+  }
+  const src = join(root, kb.local)
+  if (!existsSync(src)) throw new Error(`本地目录不存在: ${src}`)
+
+  kb._state ??= {}
+  const drift = []
+  let pushed = 0, unchanged = 0
+
+  for (const { path, rel } of walkLocal(src)) {
+    const body = readFileSync(path, 'utf8')
+    let nid = Object.keys(kb._state).find((k) => kb._state[k].rel === rel)
+    if (!nid) {
+      nid = dws.createDoc(id, basename(rel), path)
+      kb._state[nid] = { rel, pushedWords: dws.words(body) }
+      pushed++; console.log(`    + 新建 ${rel}`); continue
+    }
+    const remote = dws.readDoc(nid)
+    if (dws.same(remote, body)) { unchanged++; continue }
+
+    // 远端 ≠ 我上次推上去的 → **有人在钉钉里改过**
+    const last = kb._state[nid].pushedWords
+    if (last && dws.words(remote) !== last && !force) { drift.push({ rel, nid }); continue }
+
+    dws.updateDoc(nid, path)
+    if (!dws.same(dws.readDoc(nid), body)) {
+      throw new Error(`推了 ${rel} 但回读不一致 —— **写操作报错≠失败，回读定成败。**`)
+    }
+    kb._state[nid].pushedWords = dws.words(body)
+    pushed++; console.log(`    ↑ 更新 ${rel}`)
+  }
+
+  if (drift.length) {
+    console.log(`\n  ⚠️ **远端被人改过**，默认拒绝覆盖（${drift.length} 篇）:`)
+    for (const { rel, nid } of drift) console.log(`      ${rel}   nodeId=${nid}`)
+    console.log(`  人在钉钉里改了东西，说明他有话要说。**先去看一眼**，别盲覆盖。`)
+    console.log(`  确认要覆盖: dingtalk-agent kb sync --name ${kb.name} --force`)
+    const e = new Error('有漂移，拒绝覆盖'); e.exitCode = 1; throw e
+  }
+  kb._syncedAt = now()
+  console.log(`  push   ${kb.name.padEnd(14)} 推了 ${pushed} 篇 · 一致 ${unchanged} 篇`)
+}
+
+// ════════════════ search：跨所有挂载点 ════════════════
+export function stale(kb) {
+  if (kb.own !== EXTERNAL || kb.sync === NONE) return false
+  if (!kb._syncedAt) return true
+  const age = (Date.now() - Date.parse(kb._syncedAt)) / 3600e3
+  return age > STALE_HOURS
+}
+
+/**
+ * 跨所有挂载的 KB 搜。**本地 grep 为主** —— 快、确定、能看到上下文。
+ *
+ * fail-closed：不新鲜的缓存会【警告】。
+ * **拿着过期快照回答，比说「我不知道」危险得多。**
+ */
+export function search(cfg, root, kw, top = 20) {
+  const hits = [], warned = []
+  for (const kb of cfg.kb || []) {
+    const base = kb.local.startsWith('/') ? kb.local : join(root, kb.local)
+    if (!existsSync(base)) continue
+    if (stale(kb)) warned.push(kb.name)
+    const r = spawnSync('grep', ['-ril', '--include=*.md', kw, base], { encoding: 'utf8' })
+    for (const p of (r.stdout || '').split('\n').filter(Boolean)) {
+      const ctx = spawnSync('grep', ['-i', '-n', '-m', '2', kw, p], { encoding: 'utf8' }).stdout || ''
+      hits.push({ kb: kb.name, file: relative(root, p), ctx: ctx.trim() })
+    }
+  }
+
+  if (warned.length) {
+    console.log(`⚠️ 这些知识库的缓存【超过 ${STALE_HOURS} 小时没同步】了: ${warned.join('、')}`)
+    console.log(`   **拿着过期快照回答，比说「我不知道」危险得多。**`)
+    console.log(`   先跑: dingtalk-agent kb sync\n`)
+  }
+  if (!hits.length) {
+    console.log(`没搜到「${kw}」。`)
+    console.log(`**搜不到就说搜不到 —— 不要编。** 挂了哪些库: dingtalk-agent kb list`)
+    return []
+  }
+  console.log(`命中 ${hits.length} 处:`)
+  for (const h of hits.slice(0, top)) {
+    console.log(`\n── [${h.kb}] ${h.file}`)
+    for (const l of h.ctx.split('\n').slice(0, 2)) console.log(`     ${l.slice(0, 110)}`)
+  }
+  console.log(`\n**别只看这几行就作答** —— 打开命中的那一页读完再说。`)
+  return hits
+}

package/src/runs.js

@@ -0,0 +1,77 @@
+// 留痕与集中进化 —— runs/YYYY-MM-DD.md，一天一档 jsonl。
+//
+// 每行钉住【三个硬 ID】—— 出问题才反查得到：
+//   issue → 平台派单 id，翻得出整个运行过程
+//   conv  → 会话 id，**filter 得出整条对话流（这就是训练素材）**
+//   msg   → 触发消息 id，定位到那一句
+// **缺了这三个，记录就只是一堆"我做了什么"，出了问题什么也追不到。**
+//
+// r  = 【引擎层】成败（跑通没有）
+// fb = 【用户层】成败（主人认不认）
+// **两者必须分开** —— 引擎跑通 ≠ 答对 ≠ 主人满意。
+// 只看 r，你会看到一片绿，然后什么也进化不了。
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const FB_OK = '认可', FB_MORE = '追问', FB_FIX = '纠正'
+const MARKER = 'AGENT_RUN_LOG_V1'
+
+const cst = (d = new Date()) => new Date(d.getTime() + 8 * 3600e3)
+export const today = () => cst().toISOString().slice(0, 10)
+export const now = () => cst().toISOString().replace('Z', '+08:00').slice(0, 19)
+export const todayZero = () => today() + 'T00:00:00+08:00'
+
+/** 【今晚跑过没有】= 数据水位 ≥ 今天 00:00。纯【数据派生】——
+ *  不记状态、不建标记文件、不看会话记忆。重启/换实例/漏拍都不受影响。 */
+export const ranTonight = (wm) => Boolean(wm) && String(wm) >= todayZero()
+
+const file = (root, day) => join(root, 'runs', `${day}.md`)
+
+export function read(root, day) {
+  const p = file(root, day)
+  if (!existsSync(p)) return []
+  const out = []
+  for (const line of readFileSync(p, 'utf8').split('\n')) {
+    const s = line.trim()
+    if (!s.startsWith('{')) continue
+    try { out.push(JSON.parse(s)) }
+    catch { console.error(`  ⚠️ 运行记录有坏行，跳过但【不当成空】: ${s.slice(0, 60)}`) }
+  }
+  return out
+}
+
+export function write(root, day, rows) {
+  mkdirSync(join(root, 'runs'), { recursive: true })
+  const body = rows.map((r) => JSON.stringify(r)).join('\n')
+  writeFileSync(file(root, day), `${MARKER} · ${day}\n\n\`\`\`jsonl\n${body}\n\`\`\`\n`)
+}
+
+/** 追加一行 + 回读校验。**写了没落上 = 这次没发生过，要说出来。** */
+export function append(root, row) {
+  const day = today()
+  const rows = read(root, day)
+  rows.push(row)
+  write(root, day, rows)
+  const ok = read(root, day).some((r) => r.t === row.t && r.did === row.did)
+  if (!ok) console.error('  ⚠️ 运行记录写后回读不到 —— 动作照常，但【留痕失败】')
+  return ok ? row.t : ''
+}
+
+export function scan(root, days = 1) {
+  const out = []
+  for (let i = 0; i < Math.max(1, days); i++) {
+    const d = new Date(Date.now() - i * 86400e3)
+    const day = cst(d).toISOString().slice(0, 10)
+    for (const r of read(root, day)) out.push({ ...r, _day: day })
+  }
+  return out.sort((a, b) => (a._day + a.t).localeCompare(b._day + b.t))
+}
+
+export function logq(root, { did, kind = '问答', secs = 0, r = 'pass', ev = '',
+                            ch = '钉钉单聊', asked = '', issue = '', conv = '', msg = '' }) {
+  const row = { t: now().slice(11, 19), ch, kind, did: String(did).slice(0, 300), secs: +secs, r }
+  for (const [k, v] of [['asked', asked], ['issue', issue], ['conv', conv], ['msg', msg], ['ev', ev]]) {
+    if (v) row[k] = String(v).slice(0, 600)
+  }
+  return append(root, row)
+}

package/templates/ontology/index.md

@@ -0,0 +1,24 @@
+# 本体 · 冷启动入口
+
+**这是我的 ontology —— 我是谁 + 我知道什么。`git clone` 就带走的东西。**
+
+| 层 | 是什么 | 谁维护 |
+|---|---|---|
+| `self/` | **我是谁** —— 岗位说明书 · 工牌 · 工位 | 人（fork 后必填） |
+| `sources/` | **原始证据** —— 听记 / 群聊 / 文章原文。**只增不删、不可改** | ingest 时写入 |
+| `wiki/` | **编译层** —— concepts / people / matters。**可随时重建** | LLM 全权维护（夜间编译） |
+
+## 冷启动读什么
+
+1. `self/` 三件套 —— **一篇不能少**。`dingtalk-agent boot` 会检查。
+2. 剩下的**命中路由才读**。**渐进披露：用不上的正文一个字都不读。**
+
+**BOOT FAIL 时禁答身份/能力/记忆/知识类问题。** 不要猜，不要找替代路径。
+
+## 查知识
+
+```bash
+dingtalk-agent kb search "<关键词>"
+```
+
+**不是只读索引。** 索引是一行摘要，信息量不足以支撑判断——**打开命中的那一页读完再说。**

package/templates/ontology/self/access.md

@@ -0,0 +1,38 @@
+# 工牌（Access Bundle）
+
+> 回答第三个判定：**它干的事，能查、能撤、能追责吗？**
+> `<待填>` 没填完 `boot` 会拒绝启动。
+
+## 身份
+
+- 我的 userId：`<待填>` ← **ID 变更只能从命令返回更新，不能猜**
+- 主人的 userId：`<待填>`
+
+## 副作用分级
+
+```
+只读  >  干跑  >  写给自己  >  外发（最高）
+```
+
+**外发** = 发群 / 发人 / DING / 催办 / 删除 / 改权限。**无明确授权不外发。**
+
+| 谁让我做的 | 我能做到哪 |
+|---|---|
+| 主人 | 明确范围内执行；危险动作仍需确认 |
+| 同事 | **只读 / 查询 / 汇总。外发、催办、删除 → 先问主人** |
+| 未知来源 | **只回执，不执行高影响动作** |
+
+## 我能碰什么
+
+| | |
+|---|---|
+| **能读** | `<待填>` |
+| **能写** | `<待填>` |
+| **绝对不能碰** | `<待填>` |
+
+## 可追责
+
+- 每个写操作**留定位键**（nodeId / recordId / taskId / messageId）—— **从命令返回取，不编造**。
+- 每次交互**落一行运行记录**（`issue` / `conv` / `msg` 三个硬 ID）。
+
+> **追不到责的动作，等于没发生过。**

package/templates/ontology/self/role-spec.md

@@ -0,0 +1,34 @@
+# 岗位说明书（Role Spec）
+
+> **它是"谁"** —— 三个判定（事件 / 存储 / 身份）的前提。没有它，另外两个无从谈起。
+> **`<待填>` 没填完 `boot` 会拒绝启动。**
+
+## 我是谁
+
+- 名字 / 花名：`<待填>`
+- 我的 userId：`<待填 —— 从 dws contact 取，不要猜>`
+- 主人的 userId：`<待填>`
+- 所在组织：`<待填>`
+
+## 我对什么负责（一句话北极星）
+
+`<待填>`
+
+## 我的边界
+
+| | |
+|---|---|
+| **我做什么** | `<待填>` |
+| **我明确不做什么** | `<待填 —— 这一行最重要。没有边界 = 迟早越界>` |
+| **拿不准时** | `<待填 —— 找谁？>` |
+
+## 我的职责怎么被驱动
+
+| 类型 | 有哪些 | 靠什么 |
+|---|---|---|
+| **固定职责**（永远做不完的义务） | `<待填>` | **值班**（心跳，不是待办） |
+| **被动响应**（等人问的） | `<待填>` | 消息 / 派单 |
+
+## 什么算做完了
+
+`<待填 —— 可查询、可判定的完成条件。"我试过了"不算做完。>`

package/templates/ontology/self/workspace.md

@@ -0,0 +1,41 @@
+# 工位（Workspace Context）
+
+> 回答：**它看到的世界是对的吗？**
+> `boot` 会拿这里的资源**真去摸一遍** —— 拉不到就 BOOT FAIL。
+> `<待填>` 没填完 `boot` 会拒绝启动。
+
+## 我的资源
+
+**裸 ID 不许单独出现 —— 人也要看得懂。**（格式：中文名 · ID · 可点击链接）
+
+| 是什么 | 中文名 | 硬 ID | 打开 |
+|---|---|---|---|
+| 文档树根 | `<待填>` | `<待填>` | `<待填>` |
+| 知识库 | `<待填>` | `<待填>` | `<待填>` |
+| AI 表格 | `<待填>` | `<待填>` | `<待填>` |
+| 我的群 | `<待填>` | `<待填>` | — |
+
+## 哪些是真值源，哪些是派生物
+
+| | |
+|---|---|
+| **真值源**（不能乱动） | `<待填>` |
+| **派生物**（随时能重算） | `<待填>` |
+
+## 我的钟从哪来
+
+**钉钉侧没有 cron。** 心跳的钟必须来自外部（定时器 / 自动化 / 常驻进程）。
+
+- 我的钟：`<待填>` · 拍距：`<待填>`
+
+## ⚠️ 已知缺口
+
+**交付类值班的幂等判据靠本地 `runs/`。**
+换实例 / 换容器 / 清了本地档 → **今天的群消息会再发一遍。群里刷屏不可撤销。**
+
+对策（按可靠性排序）：
+1. 发之前**先回读目标本身**（群里今天已经有这条了吗）—— 证据在**外面的世界**，不在我的本地档
+2. `runs/` 落共享存储，让多实例看到同一份
+3. 至少：发之前先 `duty --check`，人眼确认
+
+**在 1 或 2 落地之前，只有单实例是安全的。**