feat(local-files): 提供 Web 文件正文读取分发

.changeset/local-files-reader.md

@@ -0,0 +1,5 @@
+---
+'@inkcre/ext-local-files': patch
+---
+
+读取本地文件资料及已提取正文，展示原件失效与提取范围。

extensions/local-files/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InKCre contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

extensions/local-files/README.md

@@ -0,0 +1,5 @@
+# 本地文件读取分发
+
+解释 `inkcre/local-files` 的文件资料与 `body` 正文，展示 Peer 位置和原件状态。原件位置仅为文字，不将自定义 scheme 交给浏览器或远程取文件。目录监视与扫描 Job 由具备本机文件访问能力的分发执行；此包只注册 Resolver。
+
+共享合同见 InKCre/docs 的 `20-product-tdd/local-files-contract.md`。使用 `pnpm --filter @inkcre/ext-local-files build` 构建可重定位的 Module Federation 分发。

extensions/local-files/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>本地文件分发</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

extensions/local-files/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@inkcre/ext-local-files",
+  "version": "0.1.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "type-check": "vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@inkcre/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@inkcre/ext-dev-utils": "workspace:*",
+    "@inkcre/ui-web": "2.2.1",
+    "@module-federation/vite": "^1.1.0",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "@vue/tsconfig": "^0.7.0",
+    "typescript": "catalog:",
+    "vite": "^7.0.6",
+    "vue-tsc": "catalog:"
+  },
+  "peerDependencies": {
+    "@vueuse/core": "^14.0.0",
+    "pinia": "^3.0.0",
+    "vue": "^3.5.25",
+    "vue-router": "^4.5.0",
+    "zod": "^4.1.0"
+  },
+  "inkcre": {
+    "name": "inkcre/local-files",
+    "nickname": "本地文件",
+    "module_federation": {
+      "host_sdk": "@inkcre/core",
+      "host_sdk_version": ">=0.4.0 <0.5.0"
+    }
+  },
+  "intent": {
+    "skills": [
+      "@inkcre/ui-web"
+    ]
+  }
+}

extensions/local-files/src/DevApp.vue

@@ -0,0 +1,12 @@
+<template>
+  <main>
+    <h1>本地文件</h1>
+    <p>在 Web Peer 启用本分发后，可阅读已经收入的文件正文与原件位置。</p>
+  </main>
+</template>
+<style scoped>
+main {
+  margin: var(--sys-space-xl);
+  color: var(--sys-color-text-base);
+}
+</style>

extensions/local-files/src/FileContent.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { SolvedContentRendererProps } from '@inkcre/core'
+import type { LocalFileResolver } from './resolver'
+import { peerFileLocation, type SolvedFile } from './schema'
+const props = defineProps<SolvedContentRendererProps<SolvedFile, LocalFileResolver>>()
+const location = computed(() => peerFileLocation(props.solvedContent.metadata.location))
+</script>
+
+<template>
+  <article class="file-content">
+    <header>
+      <strong>{{ location.path.split('/').at(-1) }}</strong>
+      <p>{{ location.path }}</p>
+      <p>原件 Peer：{{ location.peer }}</p>
+    </header>
+    <p v-if="!solvedContent.metadata.available">原件已失效；已收入正文保留。</p>
+    <p v-if="solvedContent.metadata.issue">
+      {{ solvedContent.metadata.issue }}。以下为上次成功提取的正文。
+    </p>
+    <p v-if="solvedContent.metadata.revision?.scope === 'main_document'">
+      DOCX 主文档文字（不含脚注、批注）
+    </p>
+    <p v-else-if="solvedContent.metadata.revision?.scope === 'text_layer'">PDF 文字层</p>
+    <div v-if="solvedContent.text !== null" class="body">
+      {{ solvedContent.text || '空白文本' }}
+    </div>
+    <p v-else>尚无已收入正文</p>
+  </article>
+</template>
+
+<style scoped>
+.file-content {
+  display: grid;
+  gap: var(--sys-space-md);
+  color: var(--sys-color-text-base);
+  overflow-wrap: anywhere;
+}
+p {
+  margin: 0;
+  color: var(--sys-color-text-subtle);
+}
+header {
+  display: grid;
+  gap: var(--sys-space-xs);
+}
+.body {
+  white-space: pre-wrap;
+  border-top: 1px solid var(--sys-color-border-base);
+  padding-top: var(--sys-space-md);
+}
+</style>

extensions/local-files/src/FilePreview.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { SolvedContentRendererProps } from '@inkcre/core'
+import type { LocalFileResolver } from './resolver'
+import { peerFileLocation, type SolvedFile } from './schema'
+const props = defineProps<SolvedContentRendererProps<SolvedFile, LocalFileResolver>>()
+const name = computed(() =>
+  peerFileLocation(props.solvedContent.metadata.location).path.split('/').at(-1)
+)
+</script>
+<template>
+  <article>
+    <strong>{{ name }}</strong>
+    <p>{{ solvedContent.text ?? '尚无已收入正文' }}</p>
+    <span v-if="!solvedContent.metadata.available">原件失效</span
+    ><span v-else-if="solvedContent.metadata.issue">提取失败</span>
+  </article>
+</template>
+<style scoped>
+article {
+  display: grid;
+  gap: var(--sys-space-xs);
+  max-width: 360px;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+p {
+  margin: 0;
+  white-space: pre-wrap;
+  overflow: hidden;
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 3;
+}
+span {
+  color: var(--sys-color-text-subtle);
+}
+</style>

extensions/local-files/src/index.ts

@@ -0,0 +1,13 @@
+import { Resolver, type ExtensionModule } from '@inkcre/core'
+import { LocalFileResolver } from './resolver'
+
+const resolvers = [LocalFileResolver]
+const extension: ExtensionModule = {
+  async initialize() {
+    for (const resolver of resolvers) Resolver.register(resolver.type, resolver)
+  },
+  async dispose() {
+    for (const resolver of resolvers) Resolver.unregister(resolver.type, resolver)
+  },
+}
+export default extension

extensions/local-files/src/main.ts

@@ -0,0 +1,5 @@
+import { createApp } from 'vue'
+import '@inkcre/ui-web/styles'
+import DevApp from './DevApp.vue'
+
+createApp(DevApp).mount('#app')

extensions/local-files/src/resolver.ts

@@ -0,0 +1,43 @@
+import { markRaw } from 'vue'
+import { Block, Resolver, type ProjectionOptions } from '@inkcre/core'
+import { fileMetadata, type SolvedFile } from './schema'
+import FileContent from './FileContent.vue'
+import FilePreview from './FilePreview.vue'
+
+export class LocalFileResolver extends Resolver<string, SolvedFile> {
+  static readonly type = 'extensions.local_files.file.v1'
+  static readonly previewRenderer = markRaw(FilePreview)
+  static readonly solvedContentRenderer = markRaw(FileContent)
+
+  protected override async _getSolvedContent(options: ProjectionOptions): Promise<SolvedFile> {
+    const metadata = fileMetadata.parse(JSON.parse(await this.getRawContent(options)))
+    const relations = await this.getRelations({
+      includeIn: false,
+      includeOut: true,
+      refresh: options.refresh,
+    })
+    const bodies = relations.filter((item) => item.content === 'body')
+    if (bodies.length > 1 || (metadata.revision && !bodies.length))
+      throw new Error('文件资料的正文关系无效。')
+    const body = bodies[0]
+    if (!body) return { metadata, text: null, bodyID: null }
+    const block = await Block.find(body.to_)
+    if (!block || block.resolver !== 'core.text.v1' || block.storage !== null)
+      throw new Error('文件正文不存在或类型不符。')
+    return { metadata, text: block.content, bodyID: block.id }
+  }
+
+  override async getText(options: ProjectionOptions = {}): Promise<string> {
+    const { metadata, text } = await this.getSolvedContent({
+      ...options,
+      materializeMissing: false,
+    })
+    const parts = [`原件位置：${metadata.location}`]
+    if (!metadata.available) parts.push('原件已失效；保留最后收入的正文。')
+    if (metadata.issue) parts.push(`当前提取失败：${metadata.issue}。正文对应上次成功修订。`)
+    if (metadata.revision?.scope === 'main_document')
+      parts.push('DOCX 主文档文字，不含脚注、批注。')
+    if (text !== null) parts.push(text)
+    return parts.join('\n\n')
+  }
+}

extensions/local-files/src/schema.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+
+export function peerFileLocation(value: string): { peer: string; path: string } {
+  const url = new URL(value)
+  if (
+    url.protocol !== 'inkcre-peer-file:' ||
+    url.username ||
+    url.password ||
+    url.port ||
+    value.includes('?') ||
+    value.includes('#')
+  )
+    throw new Error('原件位置格式无效。')
+  const peer = z.uuid().parse(url.hostname)
+  const path = decodeURIComponent(url.pathname)
+  if (!path.startsWith('/') || path.includes('\0')) throw new Error('原件位置需要绝对路径。')
+  return { peer, path }
+}
+
+export const fileMetadata = z.strictObject({
+  location: z.string().refine((value) => {
+    try {
+      peerFileLocation(value)
+      return true
+    } catch {
+      return false
+    }
+  }),
+  format: z.enum(['pdf', 'docx', 'markdown', 'org', 'html', 'text']),
+  identity: z
+    .strictObject({
+      volume: z.string(),
+      number: z.number().int().nonnegative(),
+      created: z.iso.datetime(),
+    })
+    .optional(),
+  available: z.boolean(),
+  observed_at: z.iso.datetime(),
+  revision: z
+    .strictObject({
+      sha256: z.string().regex(/^[0-9a-f]{64}$/),
+      extractor: z.string(),
+      extracted_at: z.iso.datetime(),
+      scope: z.enum(['text', 'text_layer', 'main_document']),
+    })
+    .optional(),
+  issue: z.string().optional(),
+})
+
+export type SolvedFile = {
+  metadata: z.infer<typeof fileMetadata>
+  text: string | null
+  bodyID: number | null
+}

extensions/local-files/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "@vue/tsconfig/tsconfig.dom.json",
+  "compilerOptions": {
+    "outDir": "./dist/types",
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
+    "experimentalDecorators": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@inkcre/core": ["../../packages/core/src/index.ts"],
+      "@inkcre/core/*": ["../../packages/core/src/*"]
+    }
+  },
+  "include": ["src/**/*", "src/**/*.vue"]
+}

extensions/local-files/vite.config.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { federation } from '@module-federation/vite'
+import mfShared from '../mf-shared'
+import extensionPackage from './package.json'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    {
+      name: 'local-files-license',
+      generateBundle() {
+        this.emitFile({
+          type: 'asset',
+          fileName: 'LICENSE',
+          source: readFileSync(new URL('./LICENSE', import.meta.url), 'utf8'),
+        })
+      },
+    },
+    federation({
+      name: 'extension.localFiles',
+      filename: 'remoteEntry.js',
+      manifest: true,
+      exposes: { '.': fileURLToPath(new URL('./src/index.ts', import.meta.url)) },
+      shared: mfShared(extensionPackage.inkcre.module_federation.host_sdk_version),
+    }),
+  ],
+  base: './',
+  build: { target: 'es2022', outDir: 'dist/client-web', sourcemap: true },
+})