M1: 底座 —— @contracts 首版 + event / ledger / org / llm

@contracts 首版(§8.1 九个文件): - id 品牌 ID / terminal 终态五名与归侧四标签 / envelope 信封六字段与四类事件 - card 工单两模式 + 对话卡族(形状对齐 2026-07-26 原型定稿) - contract7 契约七件 / ledger 三级寻址与写三分 / process-package 流程包 DSL 与触发器三类 - manifest 活动包清单六区(含 CMMN·DMN·步序声明的资产形状)/ org / api 路由契约模块(L1): - event 信封存储、归属解析三级短路、投递五诺、监听注册表、三级消费裁定 - ledger schema 自生长(最大化合并/最宽类型/只增不破坏)、任务视图叠加、写三分、冲突检查 - org 岗位授权(客体三类×动作三种)、停用前置检查、会话、种子播种 - llm 四元绑定、ModelGateway 三模式(live/record/replay)—— 两缝之一 app 装配:Hono 服务 + 鉴权中间件 + 治理台/工作台路由;drizzle 迁移;AES-256-GCM 凭证密封 ADR-007 工具链与门禁 · ADR-008 投递队列 · ADR-009 凭证加密 (ADR 编号自 007 续:编码规范 §14 已用到 006,README 写「从 005 续」是笔误) 门禁五道全绿;96 个测试通过,含对真实 PG 的 ledger 集成测试 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m
2026-07-27 00:59:14 +08:00
parent 7cd664af3a
commit 14d4fa046a
120 changed files with 15236 additions and 78 deletions
@@ -0,0 +1,82 @@
+/**
+ * llm 用例 —— LLM 实例的四元绑定管理(编码规范 §5.3;语义出处 OS 02 系统管理)。
+ */
+import type { LlmInstanceView } from '@contracts';
+import type { LlmService, UpsertLlmInstance } from '../../contract.ts';
+import type { Clock, IdGenerator, LlmInstanceRepository, ProviderInvoker, SecretBox } from '../../port.ts';
+import { pickSystemUse, toPublicView, validateBinding } from '../domain/model-binding.ts';
+import type { ModelBinding } from '../domain/model-binding.ts';
+
+export type LlmServiceDeps = {
+  readonly instances: LlmInstanceRepository;
+  readonly provider: ProviderInvoker;
+  readonly secrets: SecretBox;
+  readonly clock: Clock;
+  readonly ids: IdGenerator;
+};
+
+export function createLlmService(deps: LlmServiceDeps): LlmService {
+  return {
+    async list(): Promise<LlmInstanceView[]> {
+      const all = await deps.instances.list();
+      return all.map(toPublicView);
+    },
+
+    async upsert(input: UpsertLlmInstance): Promise<LlmInstanceView> {
+      const existing = input.id === undefined ? undefined : await deps.instances.findById(input.id);
+      // 只写不读:apiKey 留空即保持原密文(ADR-009 #4)
+      const apiKeyCipher =
+        input.apiKey !== undefined && input.apiKey !== ''
+          ? deps.secrets.seal(input.apiKey)
+          : existing?.apiKeyCipher;
+
+      const binding: ModelBinding = {
+        id: existing?.id ?? input.id ?? deps.ids.next(),
+        name: input.name,
+        provider: input.provider,
+        baseUrl: input.baseUrl,
+        model: input.model,
+        apiKeyCipher,
+        systemUse: input.systemUse,
+        enabled: input.enabled,
+      };
+      const saved = await deps.instances.upsert(binding);
+      return toPublicView(saved);
+    },
+
+    async remove(id) {
+      await deps.instances.remove(id);
+    },
+
+    async probe(id) {
+      const binding = await deps.instances.findById(id);
+      if (binding === undefined) return { ok: false, error: '实例不存在' };
+      const violations = validateBinding(binding);
+      if (violations.length > 0) {
+        return { ok: false, error: violations.map((v) => `${v.field}:${v.message}`).join('; ') };
+      }
+      const started = deps.clock.now().getTime();
+      try {
+        await deps.provider.invoke({
+          binding,
+          apiKey: deps.secrets.open(binding.apiKeyCipher!),
+          call: { model: binding.name, prompt: 'ping', maxOutputTokens: 8, label: 'probe' },
+        });
+        return { ok: true, latencyMs: deps.clock.now().getTime() - started };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    },
+
+    async assertNamesBound(names) {
+      const all = await deps.instances.list();
+      const bound = new Set(all.filter((b) => validateBinding(b).length === 0 && b.enabled).map((b) => b.name));
+      const missing = [...new Set(names)].filter((n) => !bound.has(n));
+      return { ok: missing.length === 0, missing };
+    },
+
+    async systemUseBinding() {
+      return pickSystemUse(await deps.instances.list());
+    },
+  };
+}