dsh-hams 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hams",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "HAMS：DeepSeek Harness 内的人机工作台插件（项目 / 任务 / 人机成员 / 知识 / 记忆）",
   "type": "module",
   "license": "MIT",
@@ -32,12 +32,13 @@
     "schema:split": "node scripts/split-schema.mjs",
     "schema:check": "node scripts/split-schema.mjs --check",
     "store:init": "node scripts/init-store.mjs",
-    "store:backup": "node scripts/backup-store.mjs"
+    "store:backup": "node scripts/backup-store.mjs",
+    "build": "esbuild src/index.js --bundle --platform=node --format=esm --target=node24 --outfile=dist/index.js --external:@deepseek-ai/*"
   },
-  "main": "./src/index.js",
+  "main": "./dist/index.js",
   "exports": {
     ".": {
-      "default": "./src/index.js"
+      "default": "./dist/index.js"
     },
     "./client": {
       "default": "./client/index.js"
@@ -46,7 +47,7 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "src",
+    "dist",
     "client/index.js",
     "cordis.patch.yml",
     "README.md",
@@ -72,5 +73,8 @@
     "@deepseek-ai/cordis": "~4.1.0",
     "@deepseek-ai/dsh-tools": "*",
     "@deepseek-ai/schemastery": "*"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
   }
 }

package/src/domain/check.ts

@@ -1,193 +0,0 @@
-/**
- * 复查时点与模板策略解析。
- *
- * 三种复查节奏（backend-design §4.3 / 画板 ③）：
- * - `next_day_at`：次日当地 `HH:mm`（默认 09:00）；
- * - `after_hours`：N 小时后；
- * - `next_working_day`：下一工作日当地 `HH:mm`。
- *
- * 时区换算不引依赖：用 `Intl.DateTimeFormat` 取某时区的挂钟分量，再用
- * 「把挂钟当 UTC 求偏移、迭代两次」的方式把挂钟时间转回 UTC 瞬时。跨 DST 的
- * 边界会落在 ±1 小时以内，对「次日 09:00 复查」这种粒度足够；真需要分钟级
- * 精确的场合应改用带时区库，这一点写在这里而不是偷偷假设。
- */
-import { stateInvalid } from './errors.ts'
-
-export type CheckMode = 'next_day_at' | 'after_hours' | 'next_working_day'
-
-export interface CheckPolicy {
-  mode: CheckMode
-  time: string
-  tz: string
-  hours: number
-  maxRechecks: number | null
-}
-
-export interface ReviewPolicy {
-  /** `owner` 或 `position:<id>`。 */
-  approver: string
-  expiresHours: number
-  autoClose: boolean
-}
-
-const DEFAULT_TZ = 'Asia/Shanghai'
-
-function two(n: number): string {
-  return String(n).padStart(2, '0')
-}
-
-function parseClock(time: string): { hour: number; minute: number } {
-  const match = /^([01]\d|2[0-3]):([0-5]\d)$/.exec(time.trim())
-  if (!match) throw stateInvalid(`时间格式必须是 HH:mm，收到 ${time}`)
-  return { hour: Number(match[1]), minute: Number(match[2]) }
-}
-
-function zoneParts(ms: number, timeZone: string): {
-  year: number
-  month: number
-  day: number
-  hour: number
-  minute: number
-  second: number
-} {
-  const formatter = new Intl.DateTimeFormat('en-US', {
-    timeZone,
-    year: 'numeric',
-    month: '2-digit',
-    day: '2-digit',
-    hour: '2-digit',
-    minute: '2-digit',
-    second: '2-digit',
-    hour12: false,
-  })
-  const parts = formatter.formatToParts(new Date(ms))
-  const pick = (type: string): number => Number(parts.find((part) => part.type === type)?.value ?? '0')
-  return {
-    year: pick('year'),
-    month: pick('month'),
-    day: pick('day'),
-    hour: pick('hour') % 24,
-    minute: pick('minute'),
-    second: pick('second'),
-  }
-}
-
-function offsetAt(ms: number, timeZone: string): number {
-  const parts = zoneParts(ms, timeZone)
-  const wallAsUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second)
-  return wallAsUtc - Math.floor(ms / 1000) * 1000
-}
-
-/** 把某时区的挂钟时间转成 UTC 毫秒。 */
-export function wallToUtc(
-  timeZone: string,
-  year: number,
-  month: number,
-  day: number,
-  hour: number,
-  minute: number,
-): number {
-  const guess = Date.UTC(year, month - 1, day, hour, minute)
-  let candidate = guess - offsetAt(guess, timeZone)
-  // DST 切换附近，候选时刻的偏移可能和 guess 处不同；只有挂钟分量对不上时才再校准一次。
-  const local = zoneParts(candidate, timeZone)
-  if (local.hour !== hour || local.minute !== minute) {
-    candidate = guess - offsetAt(candidate, timeZone)
-  }
-  return candidate
-}
-
-function normalizeDate(year: number, month: number, day: number): { year: number; month: number; day: number } {
-  const date = new Date(Date.UTC(year, month - 1, day))
-  return { year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate() }
-}
-
-function weekdayOf(year: number, month: number, day: number): number {
-  return new Date(Date.UTC(year, month - 1, day)).getUTCDay()
-}
-
-export function parseCheckPolicy(json: string | null | undefined): CheckPolicy {
-  const fallback: CheckPolicy = {
-    mode: 'after_hours',
-    time: '09:00',
-    tz: DEFAULT_TZ,
-    hours: 24,
-    maxRechecks: null,
-  }
-  if (!json || !json.trim()) return fallback
-  let raw: unknown
-  try {
-    raw = JSON.parse(json)
-  } catch {
-    throw stateInvalid(`check_policy_json 不是合法 JSON：${json}`)
-  }
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return fallback
-  const item = raw as Record<string, unknown>
-  const mode = typeof item.mode === 'string' ? (item.mode as CheckMode) : fallback.mode
-  if (!['next_day_at', 'after_hours', 'next_working_day'].includes(mode)) {
-    throw stateInvalid(`未知的复查节奏：${String(item.mode)}`)
-  }
-  const tz = typeof item.tz === 'string' && item.tz.trim() ? item.tz.trim() : DEFAULT_TZ
-  const time = typeof item.time === 'string' && item.time.trim() ? item.time.trim() : fallback.time
-  parseClock(time)
-  try {
-    new Intl.DateTimeFormat('en-US', { timeZone: tz })
-  } catch {
-    throw stateInvalid(`未知时区：${tz}`)
-  }
-  const hours = item.hours === undefined ? fallback.hours : Number(item.hours)
-  if (!Number.isFinite(hours) || hours <= 0) throw stateInvalid(`复查间隔小时数必须是正数：${String(item.hours)}`)
-  const maxRaw = item.max_rechecks ?? item.maxRechecks
-  const maxRechecks =
-    maxRaw === undefined || maxRaw === null ? null : Number.isInteger(Number(maxRaw)) && Number(maxRaw) >= 0 ? Number(maxRaw) : null
-  return { mode, time, tz, hours, maxRechecks }
-}
-
-export function nextCheckAt(policy: CheckPolicy, fromMs: number): number {
-  if (policy.mode === 'after_hours') return fromMs + policy.hours * 3_600_000
-
-  const { hour, minute } = parseClock(policy.time)
-  const local = zoneParts(fromMs, policy.tz)
-
-  if (policy.mode === 'next_day_at') {
-    const nextDay = normalizeDate(local.year, local.month, local.day + 1)
-    return wallToUtc(policy.tz, nextDay.year, nextDay.month, nextDay.day, hour, minute)
-  }
-
-  for (let offset = 1; offset <= 8; offset += 1) {
-    const candidate = normalizeDate(local.year, local.month, local.day + offset)
-    const weekday = weekdayOf(candidate.year, candidate.month, candidate.day)
-    if (weekday === 0 || weekday === 6) continue
-    return wallToUtc(policy.tz, candidate.year, candidate.month, candidate.day, hour, minute)
-  }
-  throw stateInvalid('无法计算下一工作日：日期滚动超过 8 天')
-}
-
-export function parseReviewPolicy(json: string | null | undefined): ReviewPolicy {
-  const fallback: ReviewPolicy = { approver: 'owner', expiresHours: 24, autoClose: false }
-  if (!json || !json.trim()) return fallback
-  let raw: unknown
-  try {
-    raw = JSON.parse(json)
-  } catch {
-    throw stateInvalid(`review_policy_json 不是合法 JSON：${json}`)
-  }
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return fallback
-  const item = raw as Record<string, unknown>
-  const approver = typeof item.approver === 'string' && item.approver.trim() ? item.approver.trim() : fallback.approver
-  if (approver !== 'owner' && !/^position:.+$/.test(approver)) {
-    throw stateInvalid(`review_policy.approver 只支持 owner 或 position:<id>，收到 ${approver}`)
-  }
-  const expiresRaw = item.expires_hours ?? item.expiresHours ?? fallback.expiresHours
-  const expiresHours = Number(expiresRaw)
-  if (!Number.isFinite(expiresHours) || expiresHours <= 0) {
-    throw stateInvalid(`review_policy.expires_hours 必须是正数：${String(expiresRaw)}`)
-  }
-  const autoClose = item.auto_close === true || item.autoClose === true
-  return { approver, expiresHours, autoClose }
-}
-
-export function formatClock(time: string): string {
-  const { hour, minute } = parseClock(time)
-  return `${two(hour)}:${two(minute)}`
-}

package/src/domain/errors.ts

@@ -1,59 +0,0 @@
-/**
- * 错误码：与 backend-design §9 的 15 类错误一一对应。
- *
- * 这 15 个码是界面文案的分支依据，**不要随手新增**——新增一个码就意味着界面要
- * 多一个分支说明。内部配置/实现错误尽量复用到语义最近的码，并在 message 里写清，
- * 例如「模板的复查策略无法解析」用 STATE_INVALID 而不是造一个 CONFIG_INVALID。
- */
-export const HAMS_ERROR_CODES = [
-  'VERSION_CONFLICT',
-  'EVIDENCE_CHANGED',
-  'APPROVAL_EXPIRED',
-  'NOT_APPROVER',
-  'POLICY_DENIED',
-  'STATE_INVALID',
-  'EPOCH_STALE',
-  'APPROVAL_REQUIRED',
-  'EVIDENCE_INCOMPLETE',
-  'LEASE_LOST',
-  'IDEMPOTENCY_MISMATCH',
-  'CURSOR_EXPIRED',
-  'DATA_STALE',
-  'EXTERNAL_RESULT_UNKNOWN',
-  'HOST_CAPABILITY_MISSING',
-] as const
-
-export type HamsErrorCode = (typeof HAMS_ERROR_CODES)[number]
-
-export class HamsError extends Error {
-  code: HamsErrorCode
-  nextStep: string | undefined
-  detail: unknown
-
-  constructor(code: HamsErrorCode, message: string, options: { nextStep?: string; detail?: unknown } = {}) {
-    super(message)
-    this.name = 'HamsError'
-    this.code = code
-    this.nextStep = options.nextStep
-    this.detail = options.detail
-  }
-}
-
-export function isHamsError(error: unknown): error is HamsError {
-  return error instanceof HamsError
-}
-
-export function denied(message: string, nextStep?: string): HamsError {
-  return new HamsError('POLICY_DENIED', message, { nextStep })
-}
-
-export function stateInvalid(message: string, nextStep?: string): HamsError {
-  return new HamsError('STATE_INVALID', message, { nextStep })
-}
-
-export function evidenceIncomplete(message: string, detail?: unknown): HamsError {
-  return new HamsError('EVIDENCE_INCOMPLETE', message, {
-    detail,
-    nextStep: '补齐缺的证据后重新申请',
-  })
-}

package/src/domain/evidence.ts

@@ -1,134 +0,0 @@
-/**
- * 证据集与关单判据。
- *
- * 两条规则来自 backend-design §4.6 / §6：
- * 1. `evidence_set_hash` 只覆盖 `status='active'` 的证据，按 id 固定排序拼接后取 sha256；
- *    id 是 ULID，所以「固定顺序」= 追加顺序，任何人重算都能得到同一个值。
- * 2. 关单需要的证据种类与最低条数写在 `work_template_version.required_evidence_json`，
- *    形如 `[{kind:'reading',min_count:2,max_age_hours:24}]`。缺一项就是 EVIDENCE_INCOMPLETE，
- *    不靠人肉记忆。
- *
- * 已知缺口（记在 progress §9）：证据行没有数值字段，所以「连续两次读数 ≥ 80%」这类
- * 数值判据目前只能靠具名验证器从 `ref` 指向的外部内容里读，或改用 metric_observation。
- * 本文件只做「种类 / 条数 / 时效」这层可判定的部分，并在 requestClosure 里对未注册的
- * 验证器**失败关闭**（HOST_CAPABILITY_MISSING），不假装已经校验过。
- */
-import { createHash } from 'node:crypto'
-
-export interface EvidenceSnapshotRow {
-  id: string
-  kind: string
-  contentHash: string
-  observedAt: number
-  status: string
-}
-
-export interface EvidenceRequirement {
-  kind: string
-  minCount: number
-  maxAgeHours: number | null
-}
-
-export interface RequirementMissing {
-  kind: string
-  need: number
-  have: number
-  reason: 'count' | 'stale'
-}
-
-export interface RequirementCheck {
-  satisfied: boolean
-  missing: RequirementMissing[]
-  used: number
-  totalActive: number
-}
-
-export function evidenceSetHash(rows: EvidenceSnapshotRow[]): string {
-  const active = rows
-    .filter((row) => row.status === 'active')
-    .map((row) => `${row.id}:${row.kind}:${row.contentHash}:${row.observedAt}`)
-    .sort()
-  return createHash('sha256').update(active.join('\n')).digest('hex')
-}
-
-function toRequirement(raw: unknown): EvidenceRequirement | null {
-  if (!raw || typeof raw !== 'object') return null
-  const item = raw as Record<string, unknown>
-  const kind = typeof item.kind === 'string' ? item.kind.trim() : ''
-  if (!kind) return null
-  const minCountRaw = item.min_count ?? item.minCount ?? 1
-  const maxAgeRaw = item.max_age_hours ?? item.maxAgeHours ?? null
-  const minCount = Number(minCountRaw)
-  const maxAgeHours = maxAgeRaw === null || maxAgeRaw === undefined ? null : Number(maxAgeRaw)
-  if (!Number.isInteger(minCount) || minCount < 1) {
-    throw new Error(`required_evidence 的 min_count 必须是 ≥1 的整数：${JSON.stringify(raw)}`)
-  }
-  if (maxAgeHours !== null && (!Number.isFinite(maxAgeHours) || maxAgeHours <= 0)) {
-    throw new Error(`required_evidence 的 max_age_hours 必须是正数：${JSON.stringify(raw)}`)
-  }
-  return { kind, minCount, maxAgeHours }
-}
-
-export function parseEvidenceRequirements(json: string | null | undefined): EvidenceRequirement[] {
-  if (!json || !json.trim()) return []
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(json)
-  } catch {
-    throw new Error(`required_evidence_json 不是合法 JSON：${json}`)
-  }
-  if (!Array.isArray(parsed)) throw new Error('required_evidence_json 必须是数组')
-  return parsed.map(toRequirement).filter((item): item is EvidenceRequirement => item !== null)
-}
-
-export function evaluateRequirements(
-  rows: EvidenceSnapshotRow[],
-  requirements: EvidenceRequirement[],
-  nowMs: number,
-): RequirementCheck {
-  const active = rows.filter((row) => row.status === 'active')
-  const missing: RequirementMissing[] = []
-  let used = 0
-
-  for (const requirement of requirements) {
-    const ofKind = active.filter((row) => row.kind === requirement.kind)
-    const fresh =
-      requirement.maxAgeHours === null
-        ? ofKind
-        : ofKind.filter((row) => nowMs - row.observedAt <= requirement.maxAgeHours! * 3_600_000)
-    if (fresh.length >= requirement.minCount) {
-      used += requirement.minCount
-      continue
-    }
-    missing.push({
-      kind: requirement.kind,
-      need: requirement.minCount,
-      have: fresh.length,
-      reason: fresh.length < ofKind.length ? 'stale' : 'count',
-    })
-  }
-
-  return { satisfied: missing.length === 0, missing, used, totalActive: active.length }
-}
-
-/** 判据快照：写进 approval.criteria_json，让「批的是哪一版规则」可回看。 */
-export interface CriteriaSnapshot {
-  templateVersionId: string | null
-  requirements: EvidenceRequirement[]
-  result: RequirementCheck
-  evidenceSetHash: string
-}
-
-export function buildCriteriaSnapshot(
-  templateVersionId: string | null,
-  requirements: EvidenceRequirement[],
-  rows: EvidenceSnapshotRow[],
-  nowMs: number,
-): CriteriaSnapshot {
-  return {
-    templateVersionId,
-    requirements,
-    result: evaluateRequirements(rows, requirements, nowMs),
-    evidenceSetHash: evidenceSetHash(rows),
-  }
-}

package/src/domain/ids.ts

@@ -1,31 +0,0 @@
-/**
- * 主键：ULID 文本（26 位 Crockford Base32，前 10 位毫秒时间戳）。
- *
- * 没有引入依赖：ULID 的规范只有两段——时间前缀 + 80 位随机数。这里不做同毫秒单调
- * 递增的严格实现（同一毫秒内靠随机位去重），因为所有插入都发生在单写者事务里，
- * 冲突由主键约束兜底。
- */
-const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
-
-export type IdFactory = () => string
-
-export function ulidAt(nowMs: number, random: () => number = Math.random): string {
-  if (!Number.isFinite(nowMs) || nowMs < 0) throw new Error(`非法时间戳：${nowMs}`)
-  let timePart = ''
-  let rest = Math.floor(nowMs)
-  for (let i = 0; i < 10; i += 1) {
-    timePart = ENCODING[rest % 32] + timePart
-    rest = Math.floor(rest / 32)
-  }
-  let randomPart = ''
-  for (let i = 0; i < 16; i += 1) {
-    randomPart += ENCODING[Math.floor(random() * 32)]
-  }
-  return timePart + randomPart
-}
-
-export function createIdFactory(now: () => number, random: () => number = Math.random): IdFactory {
-  return () => ulidAt(now(), random)
-}
-
-export const ULID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/