agentworkshop 0.8.4 → 0.8.5

package/server/types/pg.d.ts

@@ -1,49 +1,49 @@
-/**
- * pg 的最小环境声明(补第三方**缺失的类型**,不是屏蔽错误)。
- *
- * 依据(实测 node_modules/pg@8.23.0):
- *  - package.json 无 "types"/"typings" 字段,files 只有 lib / esm/SPONSORS.md —— 包内**零 .d.ts**;
- *    仓库也未安装 @types/pg(实测 node_modules/@types 只有 js-yaml / node / three),
- *    所以 `import type { Pool } from 'pg'` 必然 TS7016(隐式 any)。
- *  - exports["."].import → ./esm/index.mjs(TS7016 报的就是该文件);运行时导出面见 lib/index.js
- *    (Pool / Client / types 等),本文件只声明代码真正用到的成员。
- *  - 行值形状由 SQL 与 pg 的 type parser 在运行时决定(timestamptz → Date、float8 → number、
- *    count(*) → string),查询期无法静态得知 —— 与官方 @types/pg 一致,用索引签名表达"逐查询动态";
- *    需要窄化的查询点在调用侧显式断言(见 timescale.adapter.ts queryTagged 的 rows as Array<{...}>)。
- *
- * 覆盖范围:server/services/workshop/daq/storage/timescale.adapter.ts 的用法
- * (Pool 构造 / query(sql[, values]) / connect()→query+release / end())。新增用法时按需扩展。
- */
-declare module 'pg' {
-  /** 行对象形状逐查询动态(官方 @types/pg 同样用索引签名表达) */
-  export interface QueryResultRow {
-    [column: string]: any
-  }
-
-  export interface QueryResult<R extends QueryResultRow = QueryResultRow> {
-    rows: R[]
-    rowCount: number | null
-    command: string
-  }
-
-  export interface PoolConfig {
-    connectionString?: string
-    max?: number
-    min?: number
-    idleTimeoutMillis?: number
-    connectionTimeoutMillis?: number
-  }
-
-  /** 池借出的连接:复合语句事务(BEGIN/COMMIT/ROLLBACK)与参数化查询 */
-  export interface PoolClient {
-    query<R extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<QueryResult<R>>
-    release(err?: Error | boolean): void
-  }
-
-  export class Pool {
-    constructor(config?: PoolConfig)
-    query<R extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<QueryResult<R>>
-    connect(): Promise<PoolClient>
-    end(): Promise<void>
-  }
-}
+/**
+ * pg 的最小环境声明(补第三方**缺失的类型**,不是屏蔽错误)。
+ *
+ * 依据(实测 node_modules/pg@8.23.0):
+ *  - package.json 无 "types"/"typings" 字段,files 只有 lib / esm/SPONSORS.md —— 包内**零 .d.ts**;
+ *    仓库也未安装 @types/pg(实测 node_modules/@types 只有 js-yaml / node / three),
+ *    所以 `import type { Pool } from 'pg'` 必然 TS7016(隐式 any)。
+ *  - exports["."].import → ./esm/index.mjs(TS7016 报的就是该文件);运行时导出面见 lib/index.js
+ *    (Pool / Client / types 等),本文件只声明代码真正用到的成员。
+ *  - 行值形状由 SQL 与 pg 的 type parser 在运行时决定(timestamptz → Date、float8 → number、
+ *    count(*) → string),查询期无法静态得知 —— 与官方 @types/pg 一致,用索引签名表达"逐查询动态";
+ *    需要窄化的查询点在调用侧显式断言(见 timescale.adapter.ts queryTagged 的 rows as Array<{...}>)。
+ *
+ * 覆盖范围:server/services/workshop/daq/storage/timescale.adapter.ts 的用法
+ * (Pool 构造 / query(sql[, values]) / connect()→query+release / end())。新增用法时按需扩展。
+ */
+declare module 'pg' {
+  /** 行对象形状逐查询动态(官方 @types/pg 同样用索引签名表达) */
+  export interface QueryResultRow {
+    [column: string]: any
+  }
+
+  export interface QueryResult<R extends QueryResultRow = QueryResultRow> {
+    rows: R[]
+    rowCount: number | null
+    command: string
+  }
+
+  export interface PoolConfig {
+    connectionString?: string
+    max?: number
+    min?: number
+    idleTimeoutMillis?: number
+    connectionTimeoutMillis?: number
+  }
+
+  /** 池借出的连接:复合语句事务(BEGIN/COMMIT/ROLLBACK)与参数化查询 */
+  export interface PoolClient {
+    query<R extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<QueryResult<R>>
+    release(err?: Error | boolean): void
+  }
+
+  export class Pool {
+    constructor(config?: PoolConfig)
+    query<R extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<QueryResult<R>>
+    connect(): Promise<PoolClient>
+    end(): Promise<void>
+  }
+}

package/server/utils/approval-gate.ts

@@ -1,67 +1,67 @@
-/**
- * R3:高危管理操作双人复核闸门(maker-checker)。
- *
- * approvalGate 关闭(config.yml security.approvalGate,默认关)→ 直接放行,零开销;
- * 开启后:首次调用创建待审记录(pending)返回 { pending: true },
- * 另一 admin 经 POST /api/workshop/approvals/:id/decide 批准(申请人≠批核人硬校验),
- * 申请人再携 approvalId 重放原请求 → 校验匹配且未消费 → 一次性核销放行。
- * 全程经 audit() 留痕(与 R1 统一审计视图)。
- */
-import { randomUUID } from 'node:crypto'
-import { AppError } from './errors'
-import { audit, getOps } from '../services/workshop/ops/ops'
-import type { ResolvedUser } from '../api/workshop/caller'
-
-/** 闸门主体:动作 + 目标(与 approval_requests 表的 action/target_id 对齐) */
-export interface GateSubject {
-  action: string
-  targetId: string
-  summary: string
-}
-
-export type GateVerdict = { pending: true, requestId: string } | { pending: false }
-
-/** 高危操作闸门:返回 pending = true 时端点应 202 短路返回;否则继续执行原逻辑 */
-export function gateDangerous(
-  approvalGate: boolean,
-  user: ResolvedUser,
-  subject: GateSubject,
-  approvalId?: string,
-): GateVerdict {
-  const repo = getOps()?.approvalRequests
-  if (!approvalGate || !repo) return { pending: false }
-
-  // 重放路径:携批准记录放行
-  if (approvalId) {
-    const req = repo.get(approvalId)
-    if (!req || req.action !== subject.action || req.targetId !== subject.targetId) {
-      throw new AppError(400, 'APPROVAL_INVALID', '复核记录不存在或与本次操作不匹配')
-    }
-    if (req.status !== 'approved') {
-      throw new AppError(403, 'APPROVAL_NOT_APPROVED', '复核尚未批准(或已被拒绝)')
-    }
-    if (req.requestedBy !== user.id) {
-      throw new AppError(403, 'APPROVAL_REQUESTER_MISMATCH', '仅申请人本人可携批准记录重放操作')
-    }
-    if (!repo.consume(approvalId)) {
-      throw new AppError(409, 'APPROVAL_CONSUMED', '该批准记录已被使用(一次性核销)')
-    }
-    audit({ actor: user.id, actorName: user.name, actorKind: 'user', action: `${subject.action}.approved-exec`, targetKind: 'approval-request', targetId: approvalId, detail: { targetId: subject.targetId } })
-    return { pending: false }
-  }
-
-  // 首次路径:创建待审记录
-  const id = `ar-${randomUUID().slice(0, 8)}`
-  repo.request({
-    id,
-    action: subject.action,
-    targetId: subject.targetId,
-    payload: {},
-    summary: subject.summary,
-    byUserId: user.id,
-    byName: user.name,
-    at: new Date().toISOString(),
-  })
-  audit({ actor: user.id, actorName: user.name, actorKind: 'user', action: `${subject.action}.request`, targetKind: 'approval-request', targetId: id, detail: { targetId: subject.targetId } })
-  return { pending: true, requestId: id }
-}
+/**
+ * R3:高危管理操作双人复核闸门(maker-checker)。
+ *
+ * approvalGate 关闭(config.yml security.approvalGate,默认关)→ 直接放行,零开销;
+ * 开启后:首次调用创建待审记录(pending)返回 { pending: true },
+ * 另一 admin 经 POST /api/workshop/approvals/:id/decide 批准(申请人≠批核人硬校验),
+ * 申请人再携 approvalId 重放原请求 → 校验匹配且未消费 → 一次性核销放行。
+ * 全程经 audit() 留痕(与 R1 统一审计视图)。
+ */
+import { randomUUID } from 'node:crypto'
+import { AppError } from './errors'
+import { audit, getOps } from '../services/workshop/ops/ops'
+import type { ResolvedUser } from '../api/workshop/caller'
+
+/** 闸门主体:动作 + 目标(与 approval_requests 表的 action/target_id 对齐) */
+export interface GateSubject {
+  action: string
+  targetId: string
+  summary: string
+}
+
+export type GateVerdict = { pending: true, requestId: string } | { pending: false }
+
+/** 高危操作闸门:返回 pending = true 时端点应 202 短路返回;否则继续执行原逻辑 */
+export function gateDangerous(
+  approvalGate: boolean,
+  user: ResolvedUser,
+  subject: GateSubject,
+  approvalId?: string,
+): GateVerdict {
+  const repo = getOps()?.approvalRequests
+  if (!approvalGate || !repo) return { pending: false }
+
+  // 重放路径:携批准记录放行
+  if (approvalId) {
+    const req = repo.get(approvalId)
+    if (!req || req.action !== subject.action || req.targetId !== subject.targetId) {
+      throw new AppError(400, 'APPROVAL_INVALID', '复核记录不存在或与本次操作不匹配')
+    }
+    if (req.status !== 'approved') {
+      throw new AppError(403, 'APPROVAL_NOT_APPROVED', '复核尚未批准(或已被拒绝)')
+    }
+    if (req.requestedBy !== user.id) {
+      throw new AppError(403, 'APPROVAL_REQUESTER_MISMATCH', '仅申请人本人可携批准记录重放操作')
+    }
+    if (!repo.consume(approvalId)) {
+      throw new AppError(409, 'APPROVAL_CONSUMED', '该批准记录已被使用(一次性核销)')
+    }
+    audit({ actor: user.id, actorName: user.name, actorKind: 'user', action: `${subject.action}.approved-exec`, targetKind: 'approval-request', targetId: approvalId, detail: { targetId: subject.targetId } })
+    return { pending: false }
+  }
+
+  // 首次路径:创建待审记录
+  const id = `ar-${randomUUID().slice(0, 8)}`
+  repo.request({
+    id,
+    action: subject.action,
+    targetId: subject.targetId,
+    payload: {},
+    summary: subject.summary,
+    byUserId: user.id,
+    byName: user.name,
+    at: new Date().toISOString(),
+  })
+  audit({ actor: user.id, actorName: user.name, actorKind: 'user', action: `${subject.action}.request`, targetKind: 'approval-request', targetId: id, detail: { targetId: subject.targetId } })
+  return { pending: true, requestId: id }
+}

package/server/utils/mojibake-guard.ts

@@ -1,29 +1,29 @@
-/**
- * 乱码输入护栏:U+FFFD(REPLACEMENT CHARACTER)是 UTF-8 解码失败的产物,
- * 正常用户输入几乎不会出现。含大量 FFFD 的文本一旦进入 Agent 上下文,模型会
- * 陷入"字节考古"式思考(实测单会话空转 25 分钟+烧掉海量 token),必须在
- * 入口处拒绝并给出可读原因,而不是静默喂给 LLM。
- */
-import { AppError } from './errors'
-
-const FFFD = /\uFFFD/g
-
-/** 返回文本中 U+FFFD 的出现次数 */
-export function countReplacementChars(text: string): number {
-  return (text.match(FFFD) ?? []).length
-}
-
-/**
- * 断言文本不是乱码:超过阈值即拒绝(400 INVALID_TEXT)。
- * 阈值默认 3:容忍极个别解码噪声,拦截成片损坏。
- */
-export function assertNotMojibake(text: string, { threshold = 3, source = 'text' }: { threshold?: number, source?: string } = {}): void {
-  const n = countReplacementChars(text)
-  if (n >= threshold) {
-    throw new AppError(
-      400,
-      'INVALID_TEXT',
-      `${source} 含 ${n} 个损坏字符(U+FFFD),疑似客户端编码错误(如 GBK/UTF-8 混用),已拒绝投递:此类内容会诱导模型空转。请以 UTF-8 编码重新发送`,
-    )
-  }
-}
+/**
+ * 乱码输入护栏:U+FFFD(REPLACEMENT CHARACTER)是 UTF-8 解码失败的产物,
+ * 正常用户输入几乎不会出现。含大量 FFFD 的文本一旦进入 Agent 上下文,模型会
+ * 陷入"字节考古"式思考(实测单会话空转 25 分钟+烧掉海量 token),必须在
+ * 入口处拒绝并给出可读原因,而不是静默喂给 LLM。
+ */
+import { AppError } from './errors'
+
+const FFFD = /\uFFFD/g
+
+/** 返回文本中 U+FFFD 的出现次数 */
+export function countReplacementChars(text: string): number {
+  return (text.match(FFFD) ?? []).length
+}
+
+/**
+ * 断言文本不是乱码:超过阈值即拒绝(400 INVALID_TEXT)。
+ * 阈值默认 3:容忍极个别解码噪声,拦截成片损坏。
+ */
+export function assertNotMojibake(text: string, { threshold = 3, source = 'text' }: { threshold?: number, source?: string } = {}): void {
+  const n = countReplacementChars(text)
+  if (n >= threshold) {
+    throw new AppError(
+      400,
+      'INVALID_TEXT',
+      `${source} 含 ${n} 个损坏字符(U+FFFD),疑似客户端编码错误(如 GBK/UTF-8 混用),已拒绝投递:此类内容会诱导模型空转。请以 UTF-8 编码重新发送`,
+    )
+  }
+}

package/server/utils/stability-severity.ts

@@ -1,77 +1,77 @@
-/**
- * 致命异常严重性判定(稳定性护栏的唯一判据来源)。
- *
- * 为什么独立成文件:判定逻辑必须可被 **纯 node 回归测试** 直接加载断言。
- * 放在 `server/plugins/dev-stability-guard.ts` 里就只能靠起真实服务观察,
- * 而"哪类异常该退进程"恰恰是最不该靠观察来确认的一类逻辑。
- *
- * 四级严重性,只有 `fatal` 会退进程:
- *
- *  1. `socket`   —— 浏览器/客户端硬断(WS、keep-alive)。最高频的瞬态噪声,
- *                   Node 默认策略会直接击穿进程,从而拖垮所有并发会话。
- *  2. `db-busy`  —— SQLite 忙/锁。多写竞争的瞬态错误,应重试而非退出。
- *  3. `upstream` —— **外部设备/上游服务不可达**:ECONNREFUSED / ENOTFOUND /
- *                   EHOSTUNREACH / ENETUNREACH / 连接超时。
- *                   这是运维常态(设备下电、模拟器未启、容器重启),
- *                   绝不能让"某一台设备没开"带走整个监控平台 ——
- *                   DAQ 驱动本身把这类失败记为节点 lastError 并继续轮询,
- *                   护栏再补一刀 exit 1 就构成可用性事故。
- *                   ⚠️ 与"连上了但业务失败"区分:后者不在此列,仍走 fatal。
- *  4. `engine`   —— Agent 引擎边界错误(opencode/omp/codex/dsh 的 RPC 失败)。
- *                   只影响对应 agent 会话,服务端同时承载数采/数控,不可退进程。
- *
- * 其余一律 `fatal`:安全插件的 fail-fast(如生产密钥校验失败拒绝启动)依赖异常
- * 中止进程,绝不能被护栏吞掉。
- */
-
-/** socket 级断连噪声 */
-export const SOCKET_NOISE = /ECONNRESET|EPIPE|ECONNABORTED|ETIMEDOUT|ERR_STREAM_PREMATURE_CLOSE|ERR_STREAM_WRITE_AFTER_END/
-
-/** 外部设备/上游不可达(运维常态,非程序缺陷) */
-export const UPSTREAM_UNREACHABLE = /ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|ERR_SOCKET_CONNECTION_TIMEOUT|UND_ERR_CONNECT_TIMEOUT/i
-
-/**
- * 人类可读的"设备不可达"文本兜底。
- *
- * 修复动因(实测事故):部分工业驱动库(Modbus/OPC UA 客户端)在链路超时时
- * **不抛 errno code**,只给可读 message("TCP Connection Timed Out")。
- * 旧实现只认 errno token / ERR_SOCKET_CONNECTION_TIMEOUT,该 message 一路落到
- * `fatal` → 整个生产实例 exit 1(实测 13 分钟内即发生一次),与守卫自述的
- * "设备下电/模拟器未启不该带走平台"直接矛盾。
- */
-export const UPSTREAM_UNREACHABLE_TEXT = /TCP Connection Timed Out|connection timed out|connect(?:ion)? timeout|socket hang ?up/i
-
-/** SQLite 忙/锁(hardening ST-1) */
-export const SQLITE_BUSY = /SQLITE_BUSY|SQLITE_LOCKED|database is locked/i
-
-/** Agent 引擎边界错误(harness 容错) */
-export const ENGINE_BOUNDARY = /\b(opencode|omp|codex|dsh) API\b/i
-
-export type FatalSeverity = 'socket' | 'db-busy' | 'upstream' | 'engine' | 'fatal'
-
-/** 错误→可读文本;Error 取 message + 截断 stack,其余 String() */
-export function describeReason(reason: unknown): string {
-  return reason instanceof Error
-    ? `${reason.message}\n${reason.stack?.slice(0, 600) ?? ''}`
-    : String(reason)
-}
-
-/**
- * 判定一次"致命候选"的真实严重性。
- * 命中顺序即优先级:code 字段优先(经典 errno),再全文兜底
- * (undici 等包装错误 code 可能是 UND_ERR_*,但 message/stack 仍带原文)。
- */
-export function classifyFatalCandidate(reason: unknown): FatalSeverity {
-  if (reason == null) return 'fatal'
-  const err = reason as NodeJS.ErrnoException
-  const code = typeof err.code === 'string' ? err.code : ''
-  const text = `${code}\n${describeReason(reason)}`
-
-  if (SOCKET_NOISE.test(text)) return 'socket'
-  if (SQLITE_BUSY.test(text)) return 'db-busy'
-  if (UPSTREAM_UNREACHABLE.test(text) || UPSTREAM_UNREACHABLE_TEXT.test(text)) return 'upstream'
-  // 引擎边界只看首行:避免 stack 里偶然出现的引擎名把真实错误降级
-  const head = describeReason(reason).split('\n')[0] ?? ''
-  if (ENGINE_BOUNDARY.test(head)) return 'engine'
-  return 'fatal'
-}
+/**
+ * 致命异常严重性判定(稳定性护栏的唯一判据来源)。
+ *
+ * 为什么独立成文件:判定逻辑必须可被 **纯 node 回归测试** 直接加载断言。
+ * 放在 `server/plugins/dev-stability-guard.ts` 里就只能靠起真实服务观察,
+ * 而"哪类异常该退进程"恰恰是最不该靠观察来确认的一类逻辑。
+ *
+ * 四级严重性,只有 `fatal` 会退进程:
+ *
+ *  1. `socket`   —— 浏览器/客户端硬断(WS、keep-alive)。最高频的瞬态噪声,
+ *                   Node 默认策略会直接击穿进程,从而拖垮所有并发会话。
+ *  2. `db-busy`  —— SQLite 忙/锁。多写竞争的瞬态错误,应重试而非退出。
+ *  3. `upstream` —— **外部设备/上游服务不可达**:ECONNREFUSED / ENOTFOUND /
+ *                   EHOSTUNREACH / ENETUNREACH / 连接超时。
+ *                   这是运维常态(设备下电、模拟器未启、容器重启),
+ *                   绝不能让"某一台设备没开"带走整个监控平台 ——
+ *                   DAQ 驱动本身把这类失败记为节点 lastError 并继续轮询,
+ *                   护栏再补一刀 exit 1 就构成可用性事故。
+ *                   ⚠️ 与"连上了但业务失败"区分:后者不在此列,仍走 fatal。
+ *  4. `engine`   —— Agent 引擎边界错误(opencode/omp/codex/dsh 的 RPC 失败)。
+ *                   只影响对应 agent 会话,服务端同时承载数采/数控,不可退进程。
+ *
+ * 其余一律 `fatal`:安全插件的 fail-fast(如生产密钥校验失败拒绝启动)依赖异常
+ * 中止进程,绝不能被护栏吞掉。
+ */
+
+/** socket 级断连噪声 */
+export const SOCKET_NOISE = /ECONNRESET|EPIPE|ECONNABORTED|ETIMEDOUT|ERR_STREAM_PREMATURE_CLOSE|ERR_STREAM_WRITE_AFTER_END/
+
+/** 外部设备/上游不可达(运维常态,非程序缺陷) */
+export const UPSTREAM_UNREACHABLE = /ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|ERR_SOCKET_CONNECTION_TIMEOUT|UND_ERR_CONNECT_TIMEOUT/i
+
+/**
+ * 人类可读的"设备不可达"文本兜底。
+ *
+ * 修复动因(实测事故):部分工业驱动库(Modbus/OPC UA 客户端)在链路超时时
+ * **不抛 errno code**,只给可读 message("TCP Connection Timed Out")。
+ * 旧实现只认 errno token / ERR_SOCKET_CONNECTION_TIMEOUT,该 message 一路落到
+ * `fatal` → 整个生产实例 exit 1(实测 13 分钟内即发生一次),与守卫自述的
+ * "设备下电/模拟器未启不该带走平台"直接矛盾。
+ */
+export const UPSTREAM_UNREACHABLE_TEXT = /TCP Connection Timed Out|connection timed out|connect(?:ion)? timeout|socket hang ?up/i
+
+/** SQLite 忙/锁(hardening ST-1) */
+export const SQLITE_BUSY = /SQLITE_BUSY|SQLITE_LOCKED|database is locked/i
+
+/** Agent 引擎边界错误(harness 容错) */
+export const ENGINE_BOUNDARY = /\b(opencode|omp|codex|dsh) API\b/i
+
+export type FatalSeverity = 'socket' | 'db-busy' | 'upstream' | 'engine' | 'fatal'
+
+/** 错误→可读文本;Error 取 message + 截断 stack,其余 String() */
+export function describeReason(reason: unknown): string {
+  return reason instanceof Error
+    ? `${reason.message}\n${reason.stack?.slice(0, 600) ?? ''}`
+    : String(reason)
+}
+
+/**
+ * 判定一次"致命候选"的真实严重性。
+ * 命中顺序即优先级:code 字段优先(经典 errno),再全文兜底
+ * (undici 等包装错误 code 可能是 UND_ERR_*,但 message/stack 仍带原文)。
+ */
+export function classifyFatalCandidate(reason: unknown): FatalSeverity {
+  if (reason == null) return 'fatal'
+  const err = reason as NodeJS.ErrnoException
+  const code = typeof err.code === 'string' ? err.code : ''
+  const text = `${code}\n${describeReason(reason)}`
+
+  if (SOCKET_NOISE.test(text)) return 'socket'
+  if (SQLITE_BUSY.test(text)) return 'db-busy'
+  if (UPSTREAM_UNREACHABLE.test(text) || UPSTREAM_UNREACHABLE_TEXT.test(text)) return 'upstream'
+  // 引擎边界只看首行:避免 stack 里偶然出现的引擎名把真实错误降级
+  const head = describeReason(reason).split('\n')[0] ?? ''
+  if (ENGINE_BOUNDARY.test(head)) return 'engine'
+  return 'fatal'
+}