@nekro-nxt/contracts 0.1.0 → 0.2.0

package/src/community.ts

@@ -32,11 +32,18 @@ export const CommunityAccountSchema = z
   .strict()
 export type CommunityAccount = z.output<typeof CommunityAccountSchema>
 
+export const CommunityEnvironmentSchema = z.enum(['production', 'staging', 'development'])
+export type CommunityEnvironment = z.output<typeof CommunityEnvironmentSchema>
+
 export const CommunityStatusSchema = z
   .object({
     communityUrl: z.string().url(),
+    /** 社区自我声明的环境；连不上或旧版社区时为 null。 */
+    environment: CommunityEnvironmentSchema.nullable(),
     account: CommunityAccountSchema.nullable(),
     signedInAt: z.number().int().nullable(),
+    /** 最近一次更新检查发现的可更新扩展数量（只读缓存，不发起网络请求）。 */
+    updatesAvailable: z.number().int().nonnegative(),
   })
   .strict()
 export type CommunityStatus = z.output<typeof CommunityStatusSchema>
@@ -50,6 +57,8 @@ export const CommunityPermissionItemSchema = z
   })
   .strict()
 
+export type CommunityPermissionItem = z.output<typeof CommunityPermissionItemSchema>
+
 export const CommunityReleaseSchema = z
   .object({
     id: CommunityReleaseIdSchema,
@@ -64,6 +73,13 @@ export const CommunityReleaseSchema = z
   .strict()
 export type CommunityRelease = z.output<typeof CommunityReleaseSchema>
 
+/** 社区为官方扩展保留的发布者标识：官方扩展由多位官方成员维护，对外不显示个人账号。 */
+export const COMMUNITY_OFFICIAL_HANDLE = 'nekro-nxt'
+
+/** 发布者的展示文字：官方扩展显示「NekroNXT 官方」，其余显示 @账号。 */
+export const communityPublisherLabel = (handle: string): string =>
+  handle === COMMUNITY_OFFICIAL_HANDLE ? 'NekroNXT 官方' : `@${handle}`
+
 export const CommunityExtensionSummarySchema = z
   .object({
     id: ExtensionIdSchema,
@@ -71,6 +87,8 @@ export const CommunityExtensionSummarySchema = z
     displayName: z.string().max(200),
     summary: z.string().max(1000),
     tags: z.array(z.string().max(40)).max(16),
+    /** 由社区后台认定的官方扩展；此时发布者是社区保留的官方主页（`COMMUNITY_OFFICIAL_HANDLE`）。 */
+    official: z.boolean(),
     publisher: CommunityAccountSchema,
     latest: CommunityReleaseSchema.nullable(),
     downloads: z.number().int().nonnegative(),
@@ -95,6 +113,136 @@ export const CommunityExtensionDetailSchema = CommunityExtensionSummarySchema.ex
 }).strict()
 export type CommunityExtensionDetail = z.output<typeof CommunityExtensionDetailSchema>
 
+export const CommunityEndpointSchema = z
+  .object({
+    url: z.string().url(),
+    source: z.enum(['setting', 'environment', 'default']),
+    defaultUrl: z.string().url(),
+    environmentUrl: z.string().url().nullable(),
+    /** 当前地址是未加密的非本机地址。 */
+    insecure: z.boolean(),
+  })
+  .strict()
+export type CommunityEndpoint = z.output<typeof CommunityEndpointSchema>
+
+export const CommunitySourceSchema = z
+  .object({
+    kind: z.literal('community'),
+    communityUrl: z.string().url(),
+    releaseId: CommunityReleaseIdSchema,
+    publisherHandle: z.string().min(1).max(80),
+    installedAt: z.number().int().nonnegative(),
+  })
+  .strict()
+export type CommunitySource = z.output<typeof CommunitySourceSchema>
+
+export const CommunityInstalledItemSchema = z
+  .object({
+    extensionId: ExtensionIdSchema,
+    displayName: z.string(),
+    revisionId: z.string(),
+    source: CommunitySourceSchema,
+    /** 来源与当前社区地址一致时才能检查更新。 */
+    sameCommunity: z.boolean(),
+    /** 社区仍有这个条目。 */
+    found: z.boolean(),
+    delisted: z.boolean(),
+    delistedReason: z.string().nullable(),
+    releaseWithdrawn: z.boolean(),
+    latest: CommunityReleaseSchema.nullable(),
+    updateAvailable: z.boolean(),
+    addedPermissions: z.array(CommunityPermissionItemSchema),
+  })
+  .strict()
+export type CommunityInstalledItem = z.output<typeof CommunityInstalledItemSchema>
+
+export const CommunityInstalledSchema = z
+  .object({ checkedAt: z.number().int().nullable(), items: z.array(CommunityInstalledItemSchema) })
+  .strict()
+
+export const CommunityMyExtensionSchema = CommunityExtensionSummarySchema.extend({
+  releases: z.array(CommunityReleaseSchema.extend({ withdrawn: z.boolean() }).strict()),
+  delisted: z.boolean(),
+  delistedReason: z.string().nullable(),
+}).strict()
+export type CommunityMyExtension = z.output<typeof CommunityMyExtensionSchema>
+
+export const COMMUNITY_REVIEW_DIMENSIONS = [
+  'security',
+  'transparency',
+  'reliability',
+  'context_cost',
+  'usability',
+  'maintainability',
+  'compliance',
+] as const
+
+export const COMMUNITY_REVIEW_DIMENSION_LABELS: Readonly<Record<(typeof COMMUNITY_REVIEW_DIMENSIONS)[number], string>> =
+  {
+    security: '安全',
+    transparency: '源码透明',
+    reliability: '可靠性',
+    context_cost: '上下文与成本',
+    usability: '可用性',
+    maintainability: '可维护性',
+    compliance: '合规',
+  }
+
+/** 作者看到的完整审查报告。 */
+export const CommunityReviewReportSchema = z
+  .object({
+    releaseId: CommunityReleaseIdSchema,
+    status: CommunityReviewStatusSchema,
+    grade: CommunityGradeSchema.nullable(),
+    deterministic: z.array(
+      z
+        .object({
+          severity: z.enum(['info', 'warning', 'risk', 'block']),
+          title: z.string(),
+          detail: z.string(),
+          file: z.string().optional(),
+          line: z.number().int().optional(),
+        })
+        .strict(),
+    ),
+    ai: z
+      .object({
+        summary: z.string(),
+        verdict: z.string(),
+        grade: CommunityGradeSchema,
+        dimensions: z.array(
+          z
+            .object({ key: z.enum(COMMUNITY_REVIEW_DIMENSIONS), grade: CommunityGradeSchema, notes: z.string() })
+            .strict(),
+        ),
+        findings: z.array(
+          z
+            .object({
+              dimension: z.enum(COMMUNITY_REVIEW_DIMENSIONS),
+              severity: z.enum(['info', 'suggestion', 'warning', 'risk', 'critical']),
+              title: z.string(),
+              detail: z.string(),
+              file: z.string().optional(),
+              line: z.number().int().optional(),
+              suggestion: z.string().optional(),
+            })
+            .strict(),
+        ),
+        exploitability: z.string().optional(),
+      })
+      .strict()
+      .nullable(),
+    model: z.string().nullable(),
+    error: z.string().nullable(),
+    decisions: z.array(
+      z.object({ decision: z.string(), note: z.string(), by: z.string(), createdAt: z.number().int() }).strict(),
+    ),
+    finishedAt: z.number().int().nullable(),
+    reportUrl: z.string().url(),
+  })
+  .strict()
+export type CommunityReviewReport = z.output<typeof CommunityReviewReportSchema>
+
 /** 安装者看到的审查标签：只描述审查发现，不做「安全」担保。 */
 export const communityReviewLabel = (
   status: CommunityReviewStatus,

package/src/host-api.ts

@@ -36,6 +36,11 @@ import {
   CommunityReleaseIdSchema,
   CommunityReviewStatusSchema,
   CommunityStatusSchema,
+  CommunitySourceSchema,
+  CommunityEndpointSchema,
+  CommunityInstalledSchema,
+  CommunityMyExtensionSchema,
+  CommunityReviewReportSchema,
 } from './community.js'
 import {
   DshNxtHostUiSchema,
@@ -1169,6 +1174,8 @@ export const HostSnapshotSchema = z
                 ui: ExtensionUiContributionsSchema.default(EMPTY_EXTENSION_UI_CONTRIBUTIONS),
                 configSchema: ConfigSchemaDocumentSchema.optional(),
                 createdAt: z.number().int().safe().nonnegative(),
+                /** 从社区安装的保存记录的来源；本机保存与文件导入没有来源。 */
+                source: CommunitySourceSchema.optional(),
                 scope: z.enum(['agent', 'host-adapter', 'host-ui']),
                 contributions: z.array(z.string()),
                 verification: z
@@ -2539,6 +2546,84 @@ export const HostApiContracts = {
     error: HostApiErrorSchema,
   }),
   /** 下载社区发布并按包摘要校验，结果与本地文件导入的检查相同，再经 `commitExtensionImport` 确认。 */
+  getCommunityEndpoint: defineContract({
+    method: 'GET',
+    path: '/api/community/endpoint',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: CommunityEndpointSchema,
+    error: HostApiErrorSchema,
+  }),
+  /** 修改社区地址；`url: null` 恢复为环境变量或默认地址。非加密的局域网地址需要确认风险。 */
+  updateCommunityEndpoint: defineContract({
+    method: 'PUT',
+    path: '/api/community/endpoint',
+    params: EmptyParamsSchema,
+    request: z.object({ url: z.string().max(300).nullable(), acknowledgeInsecure: z.boolean() }).strict(),
+    response: CommunityEndpointSchema,
+    error: HostApiErrorSchema,
+  }),
+  testCommunityEndpoint: defineContract({
+    timeoutMs: 30_000,
+    method: 'POST',
+    path: '/api/community/endpoint/test',
+    params: EmptyParamsSchema,
+    request: z.object({ url: z.string().max(300), acknowledgeInsecure: z.boolean() }).strict(),
+    response: z
+      .object({
+        ok: z.boolean(),
+        message: z.string(),
+        name: z.string().optional(),
+        environment: z.enum(['production', 'staging', 'development']).optional(),
+      })
+      .strict(),
+    error: HostApiErrorSchema,
+  }),
+  listCommunityInstalled: defineContract({
+    timeoutMs: 30_000,
+    method: 'GET',
+    path: '/api/community/installed',
+    params: z.object({ refresh: z.enum(['1']).optional() }).strict(),
+    request: NoRequestBodySchema,
+    response: CommunityInstalledSchema,
+    error: HostApiErrorSchema,
+  }),
+  listCommunityMine: defineContract({
+    timeoutMs: 30_000,
+    method: 'GET',
+    path: '/api/community/mine',
+    params: EmptyParamsSchema,
+    request: NoRequestBodySchema,
+    response: z.object({ items: z.array(CommunityMyExtensionSchema) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  getCommunityReleaseReview: defineContract({
+    timeoutMs: 30_000,
+    method: 'GET',
+    path: '/api/community/releases/:releaseId/review',
+    params: z.object({ releaseId: CommunityReleaseIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: CommunityReviewReportSchema,
+    error: HostApiErrorSchema,
+  }),
+  requestCommunityReview: defineContract({
+    timeoutMs: 30_000,
+    method: 'POST',
+    path: '/api/community/releases/:releaseId/review',
+    params: z.object({ releaseId: CommunityReleaseIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: z.object({ ok: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
+  withdrawCommunityRelease: defineContract({
+    timeoutMs: 30_000,
+    method: 'POST',
+    path: '/api/community/releases/:releaseId/withdraw',
+    params: z.object({ releaseId: CommunityReleaseIdSchema }).strict(),
+    request: NoRequestBodySchema,
+    response: z.object({ ok: z.literal(true) }).strict(),
+    error: HostApiErrorSchema,
+  }),
   importCommunityRelease: defineContract({
     timeoutMs: 120_000,
     method: 'POST',