@nekro-nxt/contracts 0.4.0 → 0.6.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>
 
@@ -180,6 +203,13 @@ export const CommunityExtensionDetailSchema = CommunityExtensionSummarySchema.ex
 })
 export type CommunityExtensionDetail = z.output<typeof CommunityExtensionDetailSchema>
 
+/**
+ * 本机缓存的社区目录读取附带的时间：`fetchedAt` 是这份内容从社区取回的时间；`stale` 表示社区这次没能读取，
+ * 返回的是较早的一份。
+ */
+export const CommunityFreshnessSchema = z.object({ fetchedAt: z.number().int().nonnegative(), stale: z.boolean() })
+export type CommunityFreshness = z.output<typeof CommunityFreshnessSchema>
+
 /**
  * 发布时随包提交的条目信息（作者自己写的介绍）。首次发布用于建条目；之后提供了哪项就覆盖哪项，未提供的保持不变。
  */
@@ -220,6 +250,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/config-schema.ts

@@ -6,8 +6,9 @@ import { JsonValueSchema, type JsonValue } from './domain.js'
  * product form can render and the Host can validate without executing Schema callbacks.
  *
  * Supported nodes: object (dict), string, number, natural, percent, boolean, const, union of consts (enum) and
- * array of primitives. `meta.role: 'secret'` marks a write-only credential. NekroNXT reads three extra meta keys:
- * `hint` (help text), `advanced` (collapsed by default) and `visibleWhen` (show only when a sibling equals a value).
+ * array of primitives. `meta.role: 'secret'` marks a write-only credential. NekroNXT reads four extra meta keys:
+ * `hint` (help text), `advanced` (collapsed by default), `visibleWhen` (show only when a sibling equals a value) and
+ * `agentWritable: false` (only an administrator may change the field, in the console).
  */
 export const CONFIG_SCHEMA_MAX_BYTES = 64 * 1024
 
@@ -27,6 +28,8 @@ export const ConfigSchemaMetaSchema = z
     pattern: z.object({ source: z.string().max(500), flags: z.string().max(8).optional() }).optional(),
     advanced: z.boolean().optional(),
     group: z.string().max(40).optional(),
+    /** `false` keeps the field out of the agent's reach: only an administrator changes it, in the console. */
+    agentWritable: z.boolean().optional(),
     visibleWhen: z
       .object({ key: z.string().min(1).max(64), equals: JsonValueSchema })
       .strict()
@@ -105,9 +108,27 @@ export interface ConfigField {
   readonly advanced: boolean
   readonly group?: string
   readonly options?: readonly { readonly value: JsonValue; readonly label: string }[]
+  /** Declared `meta.agentWritable: false`: only an administrator changes it. */
+  readonly adminOnly: boolean
   readonly node: ConfigSchemaNode
 }
 
+/**
+ * How much a change to one field matters when an agent makes it: `admin` fields are changed in the console only,
+ * `secret` fields hold credentials, `network` fields decide where the extension may connect, the rest are `normal`.
+ */
+export type ConfigFieldLevel = 'normal' | 'network' | 'secret' | 'admin'
+
+export const configFieldLevel = (
+  field: Pick<ConfigField, 'key' | 'kind' | 'adminOnly'>,
+  networkFields: ReadonlySet<string> | readonly string[],
+): ConfigFieldLevel => {
+  if (field.adminOnly) return 'admin'
+  if (field.kind === 'secret') return 'secret'
+  const network = networkFields instanceof Set ? networkFields : new Set(networkFields)
+  return network.has(field.key) ? 'network' : 'normal'
+}
+
 export const configDescription = (meta: ConfigSchemaMeta | undefined): string | undefined => {
   const description = meta?.description
   if (typeof description === 'string') return description
@@ -155,10 +176,17 @@ export const configFields = (document: ConfigSchemaDocument): readonly ConfigFie
       advanced: node.meta?.advanced === true,
       ...(node.meta?.group === undefined ? {} : { group: node.meta.group }),
       ...(options === undefined ? {} : { options }),
+      adminOnly: node.meta?.agentWritable === false,
       node,
     }
   })
 
+/** Fields declared `meta.agentWritable: false`. */
+export const adminOnlyConfigKeys = (document: ConfigSchemaDocument): readonly string[] =>
+  configFields(document)
+    .filter((field) => field.adminOnly)
+    .map((field) => field.key)
+
 export const configSecretKeys = (document: ConfigSchemaDocument): readonly string[] =>
   configFields(document)
     .filter((field) => field.kind === 'secret')
@@ -302,6 +330,8 @@ interface FieldOptions<Value extends JsonValue> {
   readonly required?: boolean
   readonly advanced?: boolean
   readonly group?: string
+  /** `false` for billing or moderation switches only an administrator should change. */
+  readonly agentWritable?: boolean
 }
 
 const fieldMeta = <Value extends JsonValue>(title: string, options: FieldOptions<Value> = {}): ConfigSchemaMeta => ({
@@ -311,6 +341,7 @@ const fieldMeta = <Value extends JsonValue>(title: string, options: FieldOptions
   ...(options.required === undefined ? {} : { required: options.required }),
   ...(options.advanced === undefined ? {} : { advanced: options.advanced }),
   ...(options.group === undefined ? {} : { group: options.group }),
+  ...(options.agentWritable === undefined ? {} : { agentWritable: options.agentWritable }),
 })
 
 /** Builds serialized Schemastery documents without depending on the Schemastery runtime. */