@nekro-nxt/contracts 0.3.0 → 0.5.0

package/src/community-feedback.ts

@@ -0,0 +1,289 @@
+import { z } from 'zod'
+
+export const COMMUNITY_FEEDBACK_STATUSES = [
+  'new',
+  'needs_info',
+  'triaged',
+  'planned',
+  'fixed',
+  'duplicate',
+  'wontfix',
+  'withdrawn',
+] as const
+export const CommunityFeedbackStatusSchema = z.enum(COMMUNITY_FEEDBACK_STATUSES)
+export type CommunityFeedbackStatus = z.output<typeof CommunityFeedbackStatusSchema>
+export const COMMUNITY_FEEDBACK_STATUS_LABELS: Readonly<Record<CommunityFeedbackStatus, string>> = {
+  new: '新反馈',
+  needs_info: '需要补充',
+  triaged: '已确认',
+  planned: '已计划',
+  fixed: '已修复',
+  duplicate: '重复',
+  wontfix: '不处理',
+  withdrawn: '已撤回',
+}
+export const CommunityFeedbackKindSchema = z.enum(['bug', 'suggestion', 'question'])
+export const CommunityFeedbackIdSchema = z
+  .string()
+  .regex(/^fbk_[0-9a-z]{26}$/u)
+  .brand<'CommunityFeedbackId'>()
+export const CommunityFeedbackRefSchema = z.string().regex(/^FB-[1-9][0-9]*$/u)
+export const CommunityFeedbackTargetSchema = z.union([
+  z.literal('nxt'),
+  z.object({ extensionId: z.string().regex(/^ext_[0-9A-Za-z]+$/u), version: z.string().max(120).optional() }).strict(),
+])
+const version = z.string().trim().min(1).max(120)
+const timestamp = z.number().int().nonnegative()
+
+export const CommunityFeedbackExtensionDiagnosticSchema = z
+  .object({
+    extensionId: z.string().max(100),
+    version,
+    accessLevel: z.string().max(80).optional(),
+    activation: z.enum(['host', 'agent']).optional(),
+  })
+  .strict()
+export const CommunityFeedbackDiagnosticEntrySchema = z
+  .object({
+    kind: z.enum(['compatibility', 'extension', 'connection']),
+    summary: z.string().max(2000),
+    extensionId: z.string().max(100).optional(),
+  })
+  .strict()
+
+/** An explicit allowlist: credentials, account grants and arbitrary host configuration never cross this boundary. */
+export const CommunityFeedbackDiagnosticsSchema = z
+  .object({
+    nxtVersion: version.optional(),
+    releaseChannel: z.enum(['stable', 'preview', 'development']).optional(),
+    hostKind: z.enum(['desktop', 'server']).optional(),
+    platform: z.string().max(80).optional(),
+    arch: z.string().max(40).optional(),
+    dshVersion: version.optional(),
+    adapters: z.array(z.string().max(100)).max(64).optional(),
+    agent: z
+      .object({
+        accessLevel: z.string().max(80),
+        subagents: z.boolean(),
+        fileTools: z.boolean(),
+        webSearch: z.boolean(),
+        dynamicCreation: z.boolean(),
+        developmentShell: z.boolean(),
+        unrestrictedFileAccess: z.boolean(),
+        scheduledTasks: z.boolean(),
+        codeRun: z.boolean(),
+        commandNetwork: z.boolean(),
+        communityFeedbackAuto: z.boolean(),
+      })
+      .strict()
+      .optional(),
+    extensions: z.array(CommunityFeedbackExtensionDiagnosticSchema).max(256).optional(),
+    entries: z.array(CommunityFeedbackDiagnosticEntrySchema).max(32).optional(),
+    instanceId: z.string().min(1).max(100).optional(),
+  })
+  .strict()
+export type CommunityFeedbackDiagnostics = z.output<typeof CommunityFeedbackDiagnosticsSchema>
+
+export const CommunityFeedbackExcerptSchema = z
+  .array(
+    z
+      .object({
+        speaker: z.string().max(80),
+        text: z.string().max(6000),
+      })
+      .strict(),
+  )
+  .max(8)
+export type CommunityFeedbackExcerpt = z.output<typeof CommunityFeedbackExcerptSchema>
+
+export const CommunityFeedbackCreateSchema = z
+  .object({
+    clientRequestId: z.string().min(1).max(160),
+    kind: CommunityFeedbackKindSchema,
+    target: CommunityFeedbackTargetSchema,
+    title: z.string().trim().min(1).max(120),
+    body: z.string().trim().min(1).max(8000),
+    diagnostics: CommunityFeedbackDiagnosticsSchema.default({}),
+    excerpt: CommunityFeedbackExcerptSchema.optional(),
+    excerptSharedWithAuthor: z.boolean().default(false),
+    source: z.enum(['assistant', 'assistant_auto', 'form', 'web']),
+    instanceId: z.string().min(1).max(100).optional(),
+  })
+  .strict()
+export type CommunityFeedbackCreate = z.output<typeof CommunityFeedbackCreateSchema>
+export const CommunityFeedbackMessageInputSchema = z
+  .object({
+    body: z.string().trim().min(1).max(4000),
+    audience: z.enum(['everyone', 'staff']).default('everyone'),
+  })
+  .strict()
+export const CommunityFeedbackSupplementSchema = z
+  .object({
+    diagnostics: CommunityFeedbackDiagnosticsSchema.optional(),
+    excerpt: CommunityFeedbackExcerptSchema.optional(),
+    excerptSharedWithAuthor: z.boolean().optional(),
+  })
+  .strict()
+export const CommunityFeedbackWithdrawSchema = z.object({ deleteText: z.boolean().default(false) }).strict()
+export const CommunityFeedbackConfirmSchema = z.object({ clientVersion: version }).strict()
+export const CommunityFeedbackReopenSchema = z.object({ note: z.string().trim().min(1).max(2000) }).strict()
+export const CommunityFeedbackAffectedSchema = z
+  .object({
+    diagnostics: CommunityFeedbackDiagnosticsSchema.optional(),
+    nxtVersion: version.optional(),
+  })
+  .strict()
+export const CommunityFeedbackTransitionSchema = z
+  .object({
+    status: CommunityFeedbackStatusSchema,
+    fixedIn: version.optional(),
+    duplicateOf: CommunityFeedbackRefSchema.optional(),
+    note: z.string().trim().max(2000).optional(),
+  })
+  .strict()
+export type CommunityFeedbackTransition = z.output<typeof CommunityFeedbackTransitionSchema>
+export const CommunityFeedbackLabelsSchema = z
+  .object({
+    labels: z.array(z.string().trim().min(1).max(40)).max(20),
+    priority: z.enum(['low', 'normal', 'high']).nullable(),
+  })
+  .strict()
+export const CommunityFeedbackLinkSchema = z
+  .object({
+    githubUrl: z
+      .string()
+      .url()
+      .max(1000)
+      .refine((value) => /^https:\/\/github\.com\/[^/]+\/[^/]+\/issues\/[1-9][0-9]*$/u.test(value))
+      .nullable(),
+  })
+  .strict()
+export const CommunityFeedbackVisibilitySchema = z.object({ visibility: z.enum(['private', 'public']) }).strict()
+
+export const CommunityFeedbackEventDataSchema = z
+  .object({
+    from: CommunityFeedbackStatusSchema.optional(),
+    to: CommunityFeedbackStatusSchema.optional(),
+    fixedIn: version.nullable().optional(),
+    duplicateOf: CommunityFeedbackRefSchema.nullable().optional(),
+    note: z.string().max(2000).optional(),
+    labels: z.array(z.string()).optional(),
+    priority: z.enum(['low', 'normal', 'high']).nullable().optional(),
+    visibility: z.enum(['private', 'public']).optional(),
+    clientVersion: version.optional(),
+    messageId: z.string().optional(),
+    audience: z.enum(['everyone', 'staff']).optional(),
+    deleteText: z.boolean().optional(),
+    affected: z.boolean().optional(),
+  })
+  .strict()
+export const CommunityFeedbackEventSchema = z.object({
+  seq: z.number().int().positive(),
+  ref: CommunityFeedbackRefSchema,
+  type: z.enum([
+    'created',
+    'message',
+    'status_changed',
+    'labeled',
+    'priority_changed',
+    'linked_issue',
+    'duplicate_marked',
+    'fixed_in_set',
+    'visibility_changed',
+    'affected_added',
+    'withdrawn',
+    'reopened',
+    'supplemented',
+    'fix_confirmed',
+  ]),
+  actorKind: z.enum(['user', 'admin', 'author', 'token', 'system']).optional(),
+  actor: z.string().optional(),
+  tokenId: z.string().optional(),
+  data: CommunityFeedbackEventDataSchema,
+  createdAt: timestamp,
+  title: z.string().optional(),
+  status: CommunityFeedbackStatusSchema.optional(),
+})
+export type CommunityFeedbackEvent = z.output<typeof CommunityFeedbackEventSchema>
+export const CommunityFeedbackMessageSchema = z.object({
+  id: z.string(),
+  authorKind: z.enum(['user', 'admin', 'author', 'system']),
+  author: z.string().nullable(),
+  audience: z.enum(['everyone', 'staff']),
+  body: z.string(),
+  createdAt: timestamp,
+})
+
+export const CommunityFeedbackSummarySchema = z.object({
+  id: CommunityFeedbackIdSchema,
+  ref: CommunityFeedbackRefSchema,
+  title: z.string(),
+  kind: CommunityFeedbackKindSchema.optional(),
+  target: CommunityFeedbackTargetSchema.optional(),
+  status: CommunityFeedbackStatusSchema,
+  fixedIn: version.nullable(),
+  affectedCount: z.number().int().nonnegative(),
+  source: CommunityFeedbackCreateSchema.shape.source.optional(),
+  confirmedCount: z.number().int().nonnegative().optional(),
+  createdAt: timestamp.optional(),
+  updatedAt: timestamp.optional(),
+})
+export type CommunityFeedbackSummary = z.output<typeof CommunityFeedbackSummarySchema>
+
+/** Optional private fields are emitted only by the server's role-specific projection. */
+export const CommunityFeedbackSchema = CommunityFeedbackSummarySchema.extend({
+  access: z.enum(['owner', 'admin', 'author', 'subscriber', 'public']),
+  body: z.string().optional(),
+  diagnostics: CommunityFeedbackDiagnosticsSchema.optional(),
+  excerpt: CommunityFeedbackExcerptSchema.nullable().optional(),
+  excerptSharedWithAuthor: z.boolean().optional(),
+  messages: z.array(CommunityFeedbackMessageSchema).optional(),
+  events: z.array(CommunityFeedbackEventSchema).optional(),
+  submitter: z.string().optional(),
+  instanceId: z.string().nullable().optional(),
+  priority: z.enum(['low', 'normal', 'high']).nullable().optional(),
+  labels: z.array(z.string()).optional(),
+  visibility: z.enum(['private', 'public']).optional(),
+  duplicateOf: CommunityFeedbackRefSchema.nullable().optional(),
+  githubUrl: z.string().nullable().optional(),
+  closedAt: timestamp.nullable().optional(),
+  purgedAt: timestamp.nullable().optional(),
+  confirmed: z.boolean().default(false),
+  affected: z.boolean().default(false),
+  affectedDiagnostics: z
+    .array(
+      z.object({
+        user: z.string(),
+        diagnostics: CommunityFeedbackDiagnosticsSchema.nullable(),
+        nxtVersion: version.nullable(),
+        createdAt: timestamp,
+      }),
+    )
+    .optional(),
+})
+export type CommunityFeedback = z.output<typeof CommunityFeedbackSchema>
+export const CommunityFeedbackListSchema = z.object({
+  items: z.array(CommunityFeedbackSummarySchema),
+  cursor: z.string().nullable(),
+})
+export const CommunityFeedbackChangesSchema = z.object({
+  events: z.array(CommunityFeedbackEventSchema),
+  cursor: z.number().int().nonnegative(),
+  hasMore: z.boolean(),
+})
+export type CommunityFeedbackChanges = z.output<typeof CommunityFeedbackChangesSchema>
+export const CommunityFeedbackDigestSchema = z.object({
+  since: timestamp,
+  counts: z.object({
+    status: z.record(CommunityFeedbackStatusSchema, z.number().int().nonnegative()),
+    kind: z.record(CommunityFeedbackKindSchema, z.number().int().nonnegative()),
+    target: z.record(z.enum(['nxt', 'extension']), z.number().int().nonnegative()),
+    extensions: z.record(z.string(), z.number().int().nonnegative()),
+  }),
+  newItems: z.array(CommunityFeedbackSummarySchema),
+  awaitingReply: z.array(CommunityFeedbackSummarySchema),
+  mostAffected: z.array(CommunityFeedbackSummarySchema),
+  unconfirmedFixes: z.array(CommunityFeedbackSummarySchema),
+  fixedCount: z.number().int().nonnegative(),
+})
+export type CommunityFeedbackDigest = z.output<typeof CommunityFeedbackDigestSchema>

package/src/community.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod'
-import { ExtensionIdSchema } from './domain.js'
+import { ExtensionIdSchema, ExtensionRevisionIdSchema } from './domain.js'
 
 /**
  * NekroNXT 社区在本机的投影。Host 代理社区开放接口并把结果归一到这些结构；社区新增的字段在 Host 处丢弃，
@@ -90,6 +90,8 @@ export const CommunityExtensionSortSchema = z.enum(['updated', 'score', 'downloa
 export const CommunityReleaseIdSchema = z.string().regex(/^rel_[0-9A-Za-z]+$/u)
 
 export const CommunityAccountSchema = z.object({
+  /** Immutable community identity; absent when connected to a community predating feedback support. */
+  id: z.string().min(1).max(100).optional(),
   handle: z.string().min(1).max(80),
   displayName: z.string().max(200),
   avatarUrl: z.string().url().nullable(),
@@ -100,6 +102,7 @@ export const CommunityEnvironmentSchema = z.enum(['production', 'staging', 'deve
 export type CommunityEnvironment = z.output<typeof CommunityEnvironmentSchema>
 
 export const CommunityStatusSchema = z.object({
+  features: z.array(z.string()).optional(),
   communityUrl: z.string().url(),
   /** 社区自我声明的环境；连不上或旧版社区时为 null。 */
   environment: CommunityEnvironmentSchema.nullable(),
@@ -131,6 +134,12 @@ export const CommunityReleaseSchema = z.object({
   requiresSdk: z.number().int().positive().nullable(),
   notes: z.string().max(2000),
   createdAt: z.number().int(),
+  /** Release number on the community line; absent from older communities. */
+  number: z.number().int().positive().optional(),
+  /** Revision the release contains and its lineage, so NekroNXT can tell fast-forward from divergence. */
+  revisionId: ExtensionRevisionIdSchema.optional(),
+  parentRevisionId: ExtensionRevisionIdSchema.nullable().optional(),
+  ancestry: z.array(ExtensionRevisionIdSchema).max(256).optional(),
 })
 export type CommunityRelease = z.output<typeof CommunityReleaseSchema>
 
@@ -157,6 +166,20 @@ export const CommunityExtensionSummarySchema = z.object({
   downloads: z.number().int().nonnegative(),
   updatedAt: z.number().int(),
   pageUrl: z.string().url(),
+  /**
+   * The extension and version this one is a branch of; null for an original line or an older community. Without a
+   * displayName the origin is not public on the community.
+   */
+  branchOf: z
+    .object({
+      extensionId: ExtensionIdSchema,
+      revisionId: ExtensionRevisionIdSchema.nullable(),
+      displayName: z.string().max(200).nullable(),
+    })
+    .nullable()
+    .optional(),
+  /** Public branches made from this extension. */
+  branchCount: z.number().int().nonnegative().optional(),
 })
 export type CommunityExtensionSummary = z.output<typeof CommunityExtensionSummarySchema>
 
@@ -220,6 +243,38 @@ export const CommunitySourceSchema = z.object({
 })
 export type CommunitySource = z.output<typeof CommunitySourceSchema>
 
+/**
+ * How this machine's current version of one extension relates to the community's newest public release, with the
+ * action that relation calls for. `role` says whether this machine may publish the line or only follows it.
+ */
+export const CommunitySyncItemSchema = z.object({
+  extensionId: ExtensionIdSchema,
+  displayName: z.string(),
+  communityUrl: z.string().url(),
+  role: z.enum(['owner', 'subscriber']),
+  currentRevisionId: ExtensionRevisionIdSchema,
+  currentVersionLabel: z.string(),
+  /** Release the current version is, when it is one. */
+  currentRelease: z.object({ id: CommunityReleaseIdSchema, number: z.number().int().positive().nullable() }).nullable(),
+  /** `remote-ahead`: update; `local-ahead`: publish (owner) or local changes (subscriber); `diverged`: merge first. */
+  status: z.enum(['same', 'remote-ahead', 'local-ahead', 'diverged', 'unrelated', 'unknown']),
+  found: z.boolean(),
+  delisted: z.boolean(),
+  delistedReason: z.string().nullable(),
+  /** The release the current version came from was withdrawn by its author. */
+  releaseWithdrawn: z.boolean(),
+  latest: CommunityReleaseSchema.nullable(),
+  /** The user chose to keep local changes over `latest`; it is not offered again. */
+  dismissed: z.boolean(),
+  addedPermissions: z.array(CommunityPermissionItemSchema),
+})
+export type CommunitySyncItem = z.output<typeof CommunitySyncItemSchema>
+
+export const CommunitySyncSchema = z.object({
+  checkedAt: z.number().int().nullable(),
+  items: z.array(CommunitySyncItemSchema),
+})
+
 export const CommunityInstalledItemSchema = z.object({
   extensionId: ExtensionIdSchema,
   displayName: z.string(),

package/src/domain.ts

@@ -1,5 +1,26 @@
 import { z } from 'zod'
 
+/** Rendered send-tool result consumed by both the agent and the product detail view. */
+export const MessageDeliverySummarySchema = z
+  .object({
+    status: z.enum(['sent', 'partially-sent', 'failed', 'unknown']),
+    issues: z
+      .array(
+        z
+          .object({
+            status: z.enum(['failed', 'unknown']),
+            message: z.string().max(1000),
+            kind: z.enum(['transient', 'permanent', 'rate-limited', 'authentication', 'invalid']).optional(),
+            action: z.string().max(120).optional(),
+            retcode: z.number().int().safe().optional(),
+          })
+          .strict(),
+      )
+      .max(20),
+    omittedIssues: z.number().int().nonnegative().optional(),
+  })
+  .strict()
+
 const brandedId = <Prefix extends string, Brand extends string>(prefix: Prefix, brand: Brand) =>
   z
     .string()
@@ -28,8 +49,10 @@ export const DshPluginEntryIdSchema = brandedId('dse', 'DshPluginEntryId')
 export const HostUiPageInstanceIdSchema = brandedId('hup', 'HostUiPageInstanceId')
 export const AuthoringTaskIdSchema = brandedId('aut', 'AuthoringTaskId')
 export const AuthoringAttemptIdSchema = brandedId('aua', 'AuthoringAttemptId')
+export const SubConversationIdSchema = brandedId('cnv', 'SubConversationId')
 
 export type AgentId = z.infer<typeof AgentIdSchema>
+export type SubConversationId = z.infer<typeof SubConversationIdSchema>
 export type AgentRevisionId = z.infer<typeof AgentRevisionIdSchema>
 export type ConnectionId = z.infer<typeof ConnectionIdSchema>
 export type ConnectionEventId = z.infer<typeof ConnectionEventIdSchema>
@@ -259,7 +282,18 @@ export const RichTargetUrlSchema = z
 export const MessagePartSchema = z.discriminatedUnion('type', [
   z.object({ type: z.literal('text'), text: z.string() }).strict(),
   z.object({ type: z.literal('mention'), memberId: ChannelMemberIdSchema }).strict(),
-  z.object({ type: z.literal('image'), assetId: AssetIdSchema, alt: z.string().optional() }).strict(),
+  z
+    .object({
+      type: z.literal('image'),
+      assetId: AssetIdSchema,
+      alt: z.string().optional(),
+      /**
+       * The platform reported the picture as a sticker. A hint only: a sticker dragged in from a desktop client and
+       * pictures from platforms without this signal arrive unmarked.
+       */
+      sticker: z.literal(true).optional(),
+    })
+    .strict(),
   z.object({ type: z.literal('file'), assetId: AssetIdSchema, name: z.string().optional() }).strict(),
   z.object({ type: z.literal('audio'), assetId: AssetIdSchema }).strict(),
   z.object({ type: z.literal('quote'), messageId: LogicalMessageIdSchema }).strict(),
@@ -287,19 +321,24 @@ export function parseMessageParts(input: unknown): MessagePart[] {
   return MessagePartsSchema.parse(input)
 }
 
-const collectRichAssetIds = (value: JsonValue | undefined, into: AssetId[]): void => {
+const collectRichAssetIds = (value: JsonValue | undefined, into: AssetId[], imagesOnly = false): void => {
   if (value === null || value === undefined || typeof value === 'boolean' || typeof value === 'number') return
   if (typeof value === 'string') return
   if (Array.isArray(value)) {
-    for (const item of value) collectRichAssetIds(item, into)
+    for (const item of value) collectRichAssetIds(item, into, imagesOnly)
     return
   }
   for (const [key, child] of Object.entries(value)) {
-    if ((key === 'imageAssetId' || key === 'previewAssetId') && typeof child === 'string') {
+    if (
+      (key === 'imageAssetId' ||
+        key === 'previewAssetId' ||
+        (!imagesOnly && (key === 'audioAssetId' || key === 'fileAssetId'))) &&
+      typeof child === 'string'
+    ) {
       const parsed = AssetIdSchema.safeParse(child)
       if (parsed.success) into.push(parsed.data)
     } else {
-      collectRichAssetIds(child, into)
+      collectRichAssetIds(child, into, imagesOnly)
     }
   }
 }
@@ -315,6 +354,15 @@ export const messagePartAssetIds = (part: MessagePart): readonly AssetId[] => {
 
 export const messagePartAssetId = (part: MessagePart): AssetId | undefined => messagePartAssetIds(part)[0]
 
+/** Only actual pictures enter visual context; forwarded files and recordings retain their own media kind. */
+export const messagePartImageAssetIds = (part: MessagePart): readonly AssetId[] => {
+  if (part.type === 'image') return [part.assetId]
+  if (part.type !== 'rich') return []
+  const ids: AssetId[] = part.previewAssetId ? [part.previewAssetId] : []
+  collectRichAssetIds(part.extension, ids, true)
+  return ids
+}
+
 const asJsonRecord = (value: JsonValue | undefined): Readonly<Record<string, JsonValue>> | undefined =>
   value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined
 
@@ -332,7 +380,12 @@ const richItemLine = (value: JsonValue): string | undefined => {
         : undefined
   const imageName = typeof item['imageName'] === 'string' ? item['imageName'] : undefined
   const imageText = typeof item['imageAssetId'] === 'string' ? `[图片${imageName ? ` ${imageName}` : ''}]` : undefined
-  const body = [text, cardSummary ? `[卡片] ${cardSummary}` : undefined, imageText]
+  const audioText = typeof item['audioAssetId'] === 'string' ? `[语音 ${item['audioAssetId']}]` : undefined
+  const fileText =
+    typeof item['fileAssetId'] === 'string'
+      ? `[${typeof item['fileMediaType'] === 'string' && item['fileMediaType'].startsWith('video/') ? '视频' : '文件'} ${item['fileAssetId']}${typeof item['fileName'] === 'string' ? `：${item['fileName']}` : ''}]`
+      : undefined
+  const body = [text, cardSummary ? `[卡片] ${cardSummary}` : undefined, imageText, audioText, fileText]
     .filter((part): part is string => Boolean(part && part.length > 0))
     .join(' ')
   if (!sender && !body) return undefined