@x-otto/interchange 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/context-fragment.d.ts

@@ -0,0 +1,37 @@
+//#region src/context-fragment.d.ts
+/**
+ * context-fragment.ts —— 有界上下文片段类型层（RFC-374 M3）。
+ *
+ * 借鉴 DeepSeek-TUI `fragments`（crates/core/src/fragments.rs:1-40）：每一类注入
+ * system prompt 的上下文片段都有 typed id + 字节硬顶 + 截断语义，杜绝各注入点
+ * 局部常量的漂移。otto 侧的排序权威在 `@x-otto/runtime` 的 SYSTEM_PROMPT_SECTIONS
+ * （priority + stable/volatile lane + 本类型的 budgetBytes），本文件只提供
+ * 「片段形状 + 截断原语」的纯类型/纯函数叶。
+ *
+ * 截断语义（安全红线，与 RFC-142 互补）：截断产物是**纯文本**（截断点 + 简短后缀），
+ * 绝不发明结构化 JSON 元数据键（模型会误学模仿引发上下文自我污染，见 docs/
+ * CODE-STYLE.md §6b）。片段内容被截断只损失尾部信息，不改变已注入部分的可读性。
+ */
+/** system prompt 注入片段的类型化 id（与 SYSTEM_PROMPT_SECTIONS 的字段一一对应）。 */
+type ContextFragmentId = 'toolGuidance' | 'skillLoopGuidance' | 'environment' | 'agentKnowledge' | 'memoryIndex' | 'skillCatalog' | 'lesson' | 'lessonRelevantHints' | 'memoryDelta' | 'todoReminder' | 'docSyncReminder' | 'internalize';
+/** 有界上下文片段：id + 内容。预算声明在 SYSTEM_PROMPT_SECTIONS（runtime 包）。 */
+interface ContextFragment {
+  id: ContextFragmentId;
+  content: string;
+}
+/** UTF-8 字节长度（预算口径——字节硬顶，与 DeepSeek-TUI MAX_FRAGMENT_BYTES 同语义）。 */
+declare function contextFragmentBytes(content: string): number;
+/**
+ * 把片段内容裁剪到字节预算内。超预算时保留前缀（已注入部分完整可读）并追加纯文本
+ * 截断后缀；未超预算原样返回。`budgetBytes <= 0` 时返回仅含后缀的片段（fail-closed
+ * 而非静默放行）。返回新对象，不修改入参。
+ *
+ * 实现：TextEncoder 按字节截断后回退到完整 UTF-8 字符边界（continuation byte 0b10xxxxxx
+ * 不回切），避免多字节字符（CJK 等）被劈成乱码。用 TextEncoder/TextDecoder（Web 标准、
+ * 浏览器+Node 通用）而非 Node 专属 Buffer，兑现本包「零 Node 依赖、天然浏览器安全」承诺
+ * （RFC-399 D5）。
+ */
+declare function boundFragment(fragment: ContextFragment, budgetBytes: number): ContextFragment;
+//#endregion
+export { ContextFragment, ContextFragmentId, boundFragment, contextFragmentBytes };
+//# sourceMappingURL=context-fragment.d.ts.map

package/dist/context-fragment.js

@@ -0,0 +1,2 @@
+function e(e){return new TextEncoder().encode(e).length}function t(e,t){let n=new TextEncoder().encode(e.content);if(n.length<=t)return e;let r=Math.max(0,t);for(;r>0&&r<n.length&&(n[r]&192)==128;)r--;let i=new TextDecoder(`utf-8`).decode(n.subarray(0,r));return{id:e.id,content:i.trimEnd()+`
+[context truncated: budget exceeded]`}}export{t as boundFragment,e as contextFragmentBytes};

package/dist/image.d.ts

@@ -0,0 +1,39 @@
+//#region src/image.d.ts
+/** Image: base64/mime/url model for image payloads (unified image type). */
+interface NormalizedImage {
+  /** 裸 base64（已去空白），不含 `data:...;base64,` 前缀。 */
+  base64: string;
+  /** 尽力得到的 MIME（小写），如 `image/png`；无法判定时为 ''。 */
+  mediaType: string;
+  /**
+   * base64 是否可解码：非空 + 合法 charset + 长度 %4≠1 + 不是字面量 "undefined"。
+   * 为 false 时调用方应**降级为文本占位**而非把坏数据发往 API（否则整请求 400）。
+   */
+  valid: boolean;
+}
+/**
+ * 把图片来源归一为 { 裸 base64, mediaType, valid }。
+ * 接受两种形态：完整 data URI 或裸 base64。
+ * mediaType 优先取 data URI 内声明的 mime，其次回退到显式传入的 mime。
+ */
+declare function normalizeImageData(source: string, mime?: string): NormalizedImage;
+/**
+ * 终局架构 review 建议优化项：类型名从 AnthropicImageMime 改为 CommonImageMime——这 4 种
+ * 格式（jpeg/png/gif/webp）是业界广泛支持的通用图片格式，非 Anthropic 独有（OpenAI 等
+ * provider 同样接受这 4 种）。保留 `toAnthropicImageMime` 函数名不变——该名字准确描述了
+ * 它的真实用途（"归一到 Anthropic API 要求的枚举值"，函数体内的兜底逻辑与 400 错误规避
+ * 都是针对 Anthropic API 的具体行为），改类型名不改函数名两者互不矛盾：类型是通用值域，
+ * 函数是该值域到 Anthropic 特定契约的映射。
+ */
+type CommonImageMime = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+/** @deprecated 改名为 CommonImageMime（类型语义修正，非厂商专属）。保留别名过渡，下个大版本移除。 */
+type AnthropicImageMime = CommonImageMime;
+/**
+ * 归一到 Anthropic 接受的 4 种图片 MIME 之一。
+ * 未知 mediaType 时按 base64 魔数嗅探，仍无法判定回退 image/png。
+ * **永不返回空**——避免 media_type 字段缺失被 Anthropic API 以 "Field required" 拒绝。
+ */
+declare function toAnthropicImageMime(mediaType: string, base64: string): CommonImageMime;
+//#endregion
+export { AnthropicImageMime, CommonImageMime, NormalizedImage, normalizeImageData, toAnthropicImageMime };
+//# sourceMappingURL=image.d.ts.map

package/dist/image.js

@@ -0,0 +1 @@
+const e=/^data:([^;,]*)(?:;[^,]*)?,(.*)$/s;function t(t,r){let i=e.exec(t),a=(i?i[2]??``:t).replace(/\s+/g,``);return{base64:a,mediaType:((i?i[1]:``)||r||``).toLowerCase(),valid:n(a)}}function n(e){return e.length===0||e===`undefined`||e.length%4==1?!1:/^[A-Za-z0-9+/]*={0,2}$/.test(e)}function r(e,t){switch(e.toLowerCase()){case`image/jpeg`:case`image/jpg`:return`image/jpeg`;case`image/png`:return`image/png`;case`image/gif`:return`image/gif`;case`image/webp`:return`image/webp`;default:return i(t)}}function i(e){return e.startsWith(`/9j/`)?`image/jpeg`:e.startsWith(`iVBOR`)?`image/png`:e.startsWith(`R0lGOD`)?`image/gif`:e.startsWith(`UklGR`)?`image/webp`:`image/png`}export{t as normalizeImageData,r as toAnthropicImageMime};