@undefineds.co/models 0.1.1 → 0.2.0

package/README.md

@@ -1,578 +1,188 @@
-# LinX 数据模型
+# `@undefineds.co/models`
 
-> 基于 Solid Pod 标准的 LinX 核心数据模型定义
-> 
-> 使用 `drizzle-solid` ORM，兼容标准 RDF 词汇表（VCARD, FOAF, SIOC, DCTerms 等）
+Solid-first shared SDK for `undefineds.co` data contracts.
 
----
+## 定位
 
-## 📋 目录
+`@undefineds.co/models` 不是单纯的 schema 仓库，它是一个 **SDK**：
 
-- [概述](#概述)
-- [标准词汇表](#标准词汇表)
-- [核心模型](#核心模型)
-- [使用示例](#使用示例)
-- [设计原则](#设计原则)
+- 提供共享的 Solid/RDF 数据模型、词汇表和类型
+- 提供 SDK 级的数据访问描述符与通用 helper
+- 提供影响面足够大的公开协议合同
+- 提供可跨产品复用的治理域 helper，例如审批 / 审计 / 通知投影
 
----
+它不负责：
 
-## 概述
+- UI
+- 具体运行时进程
+- 某个产品专属的 server / worker / transport 实现
+- 绑定 `xpod` 或 `linx` 的产品编排逻辑
 
-LinX 的所有数据存储在 Solid Pod 中，使用标准的 RDF 格式。本包定义了所有核心业务实体的数据模型，包括：
+## 核心原则
 
-### 核心功能模型
+- `models` 本身就是 SDK
+- 著名协议且影响面够大，可以先作为 SDK 能力进入
+- 等影响面足够大，再晋升成 `xpod` 一等 API
 
-1. **Profile** - 用户资料
-2. **Contact** - 联系人管理（支持自然人和 AI）
-3. **Chat & Message** - 聊天会话和消息
-4. **File** - 文件管理
-5. **Favorite** - 收藏夹
-6. **Settings** - 用户设置
-7. **AI Assistant** - AI 助手配置
+换句话说：
 
-### 其他模型
+- **协议合同** 可以进 `models`
+- **共享治理 helper** 可以进 `models`
+- **产品专属执行逻辑** 不应该进 `models`
 
-- **Session** - 会话管理
-- **Knowledge Folder** - 知识库文件夹
-- **Extension** - 扩展
-- **Model Credential** - 模型凭证
-- **Import Job** - 导入任务
+## 包含什么
 
----
+### 1. 共享数据模型
 
-## 标准词汇表
+例如：
 
-LinX 遵循 Solid 生态的最佳实践，优先使用标准 RDF 词汇表：
+- `profile`
+- `contact`
+- `chat` / `thread` / `message`
+- `workspace`
+- `favorite`
+- `settings`
+- `agent`
+- `approval` / `audit` / `grant` / `inboxNotification`
 
-### 已集成的标准词汇表
+这些模型描述的是稳定的 Pod 数据面，而不是某个 UI 或运行时实现。
 
-| 词汇表 | 用途 | 规范 |
-|--------|------|------|
-| **VCARD** | 联系人信息 | [RFC 6350](https://www.w3.org/TR/vcard-rdf/) |
-| **FOAF** | 人和社交关系 | [FOAF Vocabulary](http://xmlns.com/foaf/spec/) |
-| **SIOC** | 社交内容和讨论 | [SIOC Ontology](http://rdfs.org/sioc/spec/) |
-| **DCTerms** | 元数据（创建时间、作者等） | [Dublin Core](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/) |
-| **Schema.org** | 结构化数据 | [Schema.org](https://schema.org/) |
-| **LDP** | Linked Data Platform | [LDP Spec](https://www.w3.org/TR/ldp/) |
+### 2. RDF 词汇表与命名空间
 
-### LinX 自定义词汇表
+包内统一暴露标准词汇表和 `undefineds.co` 自定义词汇表，避免下游各自拼 IRI。
 
-命名空间：`https://linx.ai/ns#`
+例如：
 
-用于标准词汇表未覆盖的 LinX 特有功能（如 AI 助手配置、同步状态等）。
+- `VCARD`
+- `FOAF`
+- `SIOC`
+- `DCTerms`
+- `WF`
+- `UDFS`
+- `ApprovalVocab`
+- `AuditVocab`
 
----
+### 3. SDK 级 repository / helper
 
-## 核心模型
+`repository` 相关导出属于 SDK 能力的一部分，因为它们封装的是共享的数据访问约定，而不是某个产品运行时。
 
-### 1. Profile（用户资料）
+例如：
 
-**文件路径**: `src/profile.ts`
+- `definePodRepository`
+- `createRepositoryDescriptor`
+- `findExactRecord`
+- `updateExactRecord`
+- `deleteExactRecord`
 
-**RDF 类**: `foaf:Person`
+### 4. 协议合同
 
-**字段**:
-```typescript
-{
-  displayName: string;    // vcard:fn
-  nickname: string;       // foaf:nick
-  avatarUrl: string;      // vcard:hasPhoto
-  note: string;           // vcard:note
-  region: string;         // vcard:region
-  gender: string;         // vcard:gender
-  favorite: string;       // linx:favorite
-  inbox: string;          // ldp:inbox
-}
-```
+当某个协议具有足够公共性和影响面时，可以进入 `models` 作为 SDK 合同。
 
----
-
-### 2. Contact（联系人）
-
-**文件路径**: `src/contact/contact.schema.ts`
-
-**RDF 类**: `vcard:Individual`
-
-**支持类型**: `person`, `ai`, `organization`, `group`
-
-**核心字段**:
-```typescript
-{
-  // 姓名
-  fullName: string;       // vcard:fn ⭐ 必需
-  givenName: string;      // vcard:givenName
-  familyName: string;     // vcard:familyName
-  nickname: string;       // foaf:nick
-  
-  // 联系方式
-  email: string;          // vcard:hasEmail
-  telephone: string;      // vcard:hasTelephone
-  mobile: string;
-  
-  // 地址
-  homeAddress: string;    // vcard:hasAddress (JSON)
-  workAddress: string;
-  
-  // 组织
-  organization: string;   // vcard:organizationName
-  title: string;          // vcard:title
-  
-  // Solid 身份
-  webId: string;          // foaf:weblog
-  
-  // AI 联系人
-  aiAssistantId: string;  // linx:aiAssistant
-  
-  // 关系和标签
-  relationship: string;   // vcard:hasRelated
-  tags: string;           // dcterms:subject (JSON)
-}
-```
+当前这类能力放在：
 
-**常量**:
-- `CONTACT_TYPES`: `person`, `ai`, `organization`, `group`
-- `RELATIONSHIP_TYPES`: `friend`, `family`, `colleague`, `acquaintance`, `other`
-
----
-
-### 3. Chat（聊天会话）
-
-**文件路径**: `src/chat/chat.schema.ts`
-
-**RDF 类**: `schema:ConversationThread`
-
-**字段**:
-```typescript
-{
-  title: string;              // dcterms:title ⭐ 必需
-  description: string;        // dcterms:description
-  conversationType: string;   // linx:conversationType (direct, group, ai)
-  status: string;             // linx:status (active, archived, deleted)
-  participants: array;        // linx:participants (WebID 数组)
-  creator: string;            // dcterms:creator
-  createdAt: timestamp;       // dcterms:created
-  modifiedAt: timestamp;      // dcterms:modified
-  lastMessage: string;        // linx:lastMessage
-  lastMessageAt: timestamp;   // linx:lastMessageAt
-  pinnedAt: timestamp;        // linx:pinnedAt
-}
-```
+- `@undefineds.co/models/protocols`
 
----
-
-### 4. Message（聊天消息）
-
-**文件路径**: `src/chat/message.schema.ts`
-
-**RDF 类**: `schema:Message`
-
-**字段**:
-```typescript
-{
-  content: string;            // sioc:content ⭐ 必需 (支持 Markdown)
-  messageType: string;        // linx:messageType (text, image, file, system)
-  messageStatus: string;      // linx:messageStatus (sending, sent, delivered, read, failed)
-  conversationId: string;     // linx:conversation
-  replyTo: string;            // sioc:replyOf
-  sender: string;             // dcterms:creator (WebID)
-  senderName: string;         // foaf:name
-  createdAt: timestamp;       // dcterms:created
-  modifiedAt: timestamp;      // dcterms:modified (编辑时间)
-  deletedAt: timestamp;       // linx:deletedAt (软删除)
-  readBy: string;             // linx:readBy (JSON)
-  
-  // 附件（如果是文件/图片消息）
-  attachmentUri: string;      // schema:about
-  attachmentName: string;     // schema:name
-  attachmentSize: integer;    // schema:fileSize
-  attachmentMime: string;     // schema:encodingFormat
-}
-```
+例如当前的：
 
----
-
-### 5. File（文件管理）
-
-**文件路径**: `src/file/file.schema.ts`
-
-**RDF 类**: `schema:MediaObject`
-
-**字段**:
-```typescript
-{
-  name: string;               // schema:name ⭐ 必需
-  description: string;        // schema:description
-  mimeType: string;           // schema:encodingFormat
-  size: integer;              // schema:fileSize
-  hash: string;               // linx:fileHash (SHA-256)
-  podUri: string;             // dcterms:identifier (Pod 中的 URI)
-  localPath: string;          // linx:localPath (本地路径)
-  syncStatus: string;         // linx:syncStatus (synced, pending, conflict, error)
-  owner: string;              // dcterms:creator
-  sharedWith: string;         // linx:participants (JSON)
-  folder: string;             // linx:conversation
-  tags: string;               // dcterms:subject (JSON)
-  starred: boolean;           // linx:favorite
-  createdAt: timestamp;       // dcterms:created
-  modifiedAt: timestamp;      // dcterms:modified
-}
-```
+- 归一化运行时事件合同 `tool.call`
+- `session.state`
+- `tool.control`
+- `inbox.approval`
 
----
-
-### 6. Favorite（收藏）
-
-**文件路径**: `src/favorite/favorite.schema.ts`
-
-**RDF 类**: `schema:CreativeWork`
-
-**支持收藏类型**: `message`, `file`, `contact`, `link`, `note`
-
-**字段**:
-```typescript
-{
-  title: string;              // dcterms:title ⭐ 必需
-  description: string;        // dcterms:description
-  favoriteType: string;       // linx:favoriteType
-  targetUri: string;          // linx:favoriteTarget ⭐ 必需
-  
-  // 快照（避免查询原始资源）
-  snapshotContent: string;    // schema:text
-  snapshotAuthor: string;     // schema:author
-  snapshotCreatedAt: timestamp; // schema:dateCreated
-  
-  owner: string;              // dcterms:creator
-  folder: string;             // linx:conversation
-  tags: string;               // dcterms:subject (JSON)
-  favoredAt: timestamp;       // linx:favoredAt
-  createdAt: timestamp;       // dcterms:created
-  modifiedAt: timestamp;      // dcterms:modified
-  pinnedAt: timestamp;        // linx:pinnedAt
-}
-```
+这些合同描述“事件长什么样”，不描述“产品怎么处理它”。
 
----
+### 5. 治理域 helper
 
-### 7. Settings（用户设置）
+审批 / 审计 / 通知这类能力本身属于共享数据面，因此可以像 `favorite` 一样，提供 SDK 级 helper。
 
-**文件路径**: `src/settings/settings.schema.ts`
+当前这类能力放在：
 
-**RDF 类**: `schema:PropertyValue`
+- `@undefineds.co/models/governance`
 
-**字段**:
-```typescript
-{
-  key: string;                // linx:settingKey ⭐ 必需（唯一）
-  value: string;              // linx:settingValue (JSON 字符串)
-  valueType: string;          // linx:settingType (string, number, boolean, json)
-  category: string;           // dcterms:type (ui, ai, sync, privacy, notifications)
-  label: string;              // dcterms:title
-  description: string;        // dcterms:description
-  owner: string;              // dcterms:creator
-  isSensitive: boolean;       // linx:status (是否加密)
-  createdAt: timestamp;       // dcterms:created
-  modifiedAt: timestamp;      // dcterms:modified
-}
-```
+它们负责：
 
-**预定义设置键** (`SETTING_KEYS`):
-```typescript
-// UI 设置
-UI_THEME: "ui.theme"
-UI_LANGUAGE: "ui.language"
-UI_SIDEBAR_WIDTH: "ui.sidebar.width"
-UI_LIST_PANEL_WIDTH: "ui.listPanel.width"
-
-// AI 设置
-AI_DEFAULT_ASSISTANT: "ai.defaultAssistant"
-AI_AUTO_REPLY: "ai.autoReply"
-AI_STREAMING: "ai.streaming"
-
-// 同步设置
-SYNC_AUTO: "sync.auto"
-SYNC_INTERVAL: "sync.interval"
-SYNC_WIFI_ONLY: "sync.wifiOnly"
-
-// 隐私设置
-PRIVACY_READ_RECEIPTS: "privacy.readReceipts"
-PRIVACY_ONLINE_STATUS: "privacy.onlineStatus"
-PRIVACY_TYPING_INDICATOR: "privacy.typingIndicator"
-
-// 通知设置
-NOTIFICATIONS_ENABLED: "notifications.enabled"
-NOTIFICATIONS_SOUND: "notifications.sound"
-NOTIFICATIONS_DESKTOP: "notifications.desktop"
-
-// Pod 设置
-POD_AUTO_CONNECT: "pod.autoConnect"
-POD_CACHE_SIZE: "pod.cacheSize"
-```
+- 定义稳定的投影字段
+- 定义运行时事件到 Pod 行的共享映射规则
+- 提供纯函数级判断 helper
 
----
-
-### 8. AI Assistant（AI 助手配置）
-
-**文件路径**: `src/agent.schema.ts`
-
-**RDF 类**: `foaf:Agent`
-
-**字段**:
-```typescript
-{
-  // 基础信息
-  name: string;               // foaf:name ⭐ 必需
-  nickname: string;           // foaf:nick
-  description: string;        // dcterms:description
-  avatarUrl: string;          // foaf:depiction
-  assistantType: string;      // dcterms:type (system, custom, shared)
-  
-  // 模型配置
-  provider: string;           // linx:aiProvider (openai, anthropic, ollama, custom)
-  modelId: string;            // linx:aiModel (gpt-4, claude-3, llama2)
-  systemPrompt: string;       // linx:systemPrompt
-  
-  // 模型参数
-  temperature: float;         // linx:temperature (0-2)
-  maxTokens: integer;         // linx:maxTokens
-  topP: float;
-  frequencyPenalty: float;
-  presencePenalty: float;
-  
-  // 功能配置
-  enableStreaming: boolean;
-  enableFunctionCalling: boolean;
-  allowedFunctions: string;   // JSON 数组
-  
-  // Pod 访问权限
-  podAccessLevel: string;     // linx:status (read, write, full)
-  allowedContainers: string;  // JSON 数组
-  
-  // 共享
-  owner: string;              // dcterms:creator
-  isPublic: boolean;
-  sharedWith: string;         // JSON
-  
-  // 统计
-  messageCount: integer;
-  lastUsedAt: timestamp;
-  
-  status: string;             // linx:status (active, disabled, archived)
-  createdAt: timestamp;
-  modifiedAt: timestamp;
-}
-```
+它们不负责：
 
-**常量**:
-- `AI_PROVIDERS`: `openai`, `anthropic`, `google`, `ollama`, `custom`
-- `AI_MODELS`: 包含常见模型 ID（GPT-4, Claude-3, Gemini, Llama2 等）
+- 发请求
+- 起服务
+- 做本地/远端进程管理
+- 执行产品策略
 
----
+## 不包含什么
 
-## 使用示例
+以下内容不应进入 `models`：
 
-### 安装
+- `linx` 专属页面逻辑
+- `xpod` 专属运行时实现
+- 某个 ACP / Matrix 客户端的具体网络接入
+- 某个产品独有的自动审批策略
+- worker / 长驻运行时 / daemon 进程生命周期管理
 
-```bash
-yarn workspace @linq/models install
-```
+## 公开入口
 
-### 导入模型
+### 根入口
 
-```typescript
+```ts
 import {
-  // 词汇表
-  LINQ, SIOC, DCTerms, SCHEMA,
-  
-  // 模型表
-  contactTable,
   chatTable,
-  messageTable,
-  fileTable,
-  favoriteTable,
-  settingsTable,
-  aiAssistantTable,
-  
-  // 类型
-  type ContactRow,
-  type ChatRow,
-  type MessageRow,
-  
-  // 常量
-  CONTACT_TYPES,
-  SETTING_KEYS,
-  AI_PROVIDERS,
-} from "@linq/models";
-```
-
-### 查询示例
-
-```typescript
-// 查询联系人
-const contacts = await db
-  .select()
-  .from(contactTable)
-  .where(eq(contactTable.contactType, CONTACT_TYPES.PERSON));
-
-// 创建聊天会话
-const newChat = await db
-  .insert(chatTable)
-  .values({
-    title: "与 Alice 的对话",
-    conversationType: "direct",
-    participants: ["https://alice.solidcommunity.net/profile/card#me"],
-    creator: session.webId,
-    status: "active",
-  });
-
-// 发送消息
-const newMessage = await db
-  .insert(messageTable)
-  .values({
-    content: "你好，Alice！",
-    messageType: "text",
-    conversationId: chatId,
-    sender: session.webId,
-    senderName: "Bob",
-    messageStatus: "sent",
-  });
-
-// 查询设置
-const theme = await db
-  .select()
-  .from(settingsTable)
-  .where(eq(settingsTable.key, SETTING_KEYS.UI_THEME))
-  .limit(1);
-
-// 创建 AI 助手
-const assistant = await db
-  .insert(aiAssistantTable)
-  .values({
-    name: "LinX 助手",
-    provider: AI_PROVIDERS.OPENAI,
-    modelId: AI_MODELS.GPT_4,
-    systemPrompt: "你是 LinX 的智能助手...",
-    temperature: 0.7,
-    maxTokens: 2048,
-    owner: session.webId,
-  });
+  contactTable,
+  chatRepository,
+  definePodRepository,
+  ApprovalVocab,
+} from '@undefineds.co/models'
 ```
 
----
-
-## 设计原则
-
-### 1. 遵循 Solid 标准
-
-- ✅ 优先使用标准 RDF 词汇表（VCARD, FOAF, SIOC, DCTerms）
-- ✅ 仅在必要时使用自定义词汇表（`linx:` 命名空间）
-- ✅ 所有数据存储在 Pod 的 LDP 容器中
-- ✅ 使用标准 RDF 类（`vcard:Individual`, `schema:Message` 等）
-
-### 2. 类型安全
-
-- ✅ 使用 `drizzle-solid` 提供的类型推断
-- ✅ 导出 `Row`, `Insert`, `Update` 类型
-- ✅ 定义常量枚举（`CONTACT_TYPES`, `SETTING_KEYS` 等）
-
-### 3. 可扩展性
-
-- ✅ 支持软删除（`deletedAt` 字段）
-- ✅ 支持 JSON 字段存储复杂数据（标签、数组等）
-- ✅ 预留扩展字段（`tags`, `metadata`）
-
-### 4. 互操作性
-
-- ✅ 与其他 Solid 应用兼容
-- ✅ 使用标准的 RDF 谓词
-- ✅ 遵循 SolidOS 的数据规范
+### 协议入口
 
-### 5. 性能优化
-
-- ✅ 快照字段避免频繁查询（如 `Favorite.snapshotContent`）
-- ✅ 冗余字段提升列表显示性能（如 `Message.senderName`）
-- ✅ 索引常用查询字段
-
----
-
-## 开发指南
-
-### 添加新模型
-
-1. 在 `src/<entity>/` 创建 `<entity>.schema.ts`
-2. 使用 `podTable` 定义表结构
-3. 选择合适的 RDF 类和谓词
-4. 导出类型：`Row`, `Insert`, `Update`
-5. 在 `src/<entity>/index.ts` 导出
-6. 在 `src/index.ts` 添加导出
-7. 更新本 README
-
-### 修改现有模型
-
-⚠️ **注意**：修改模型可能影响现有数据！
-
-- 添加字段：安全（向后兼容）
-- 删除字段：危险（需要数据迁移）
-- 重命名字段：危险（需要数据迁移）
-- 修改类型：危险（需要数据迁移）
-
-### 测试
-
-```bash
-# 运行测试（待添加）
-yarn workspace @linq/models test
-
-# 类型检查
-yarn workspace @linq/models typecheck
+```ts
+import {
+  RuntimeEventSchema,
+  ToolCallEventSchema,
+} from '@undefineds.co/models/protocols'
 ```
 
----
-
-## 参考资料
-
-### Solid 规范
-- [Solid Protocol](https://solidproject.org/TR/protocol)
-- [Linked Data Platform (LDP)](https://www.w3.org/TR/ldp/)
-- [WebID Profile](https://www.w3.org/2005/Incubator/webid/spec/)
-
-### RDF 词汇表
-- [VCARD Ontology](https://www.w3.org/TR/vcard-rdf/)
-- [FOAF Vocabulary](http://xmlns.com/foaf/spec/)
-- [SIOC Ontology](http://rdfs.org/sioc/spec/)
-- [Dublin Core Terms](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/)
-- [Schema.org](https://schema.org/)
-
-### 工具
-- [Drizzle ORM](https://orm.drizzle.team/)
-- [Inrupt Solid Client](https://docs.inrupt.com/developer-tools/javascript/client-libraries/)
-
----
+### 治理入口
 
-## 更新日志
-
-| 日期 | 版本 | 更新内容 |
-|------|------|---------|
-| 2025-11-06 | 1.0.0 | 初始版本 - 创建所有核心模型 |
-|  |  | - 扩展 namespaces.ts（SIOC, DCTerms, SCHEMA, RDF） |
-|  |  | - 完善 Contact 模型（完整 VCARD 字段） |
-|  |  | - 创建 Chat & Message 模型 |
-|  |  | - 创建 File 模型 |
-|  |  | - 创建 Favorite 模型 |
-|  |  | - 创建 Settings 模型 |
-|  |  | - 创建 AI Assistant 模型 |
-|  |  | - 重组 index.ts 导出 |
-
----
-
-## 许可证
+```ts
+import {
+  RuntimeEventProjectionRules,
+  isToolWaitingApproval,
+} from '@undefineds.co/models/governance'
+```
 
-MIT License
+## 边界判断
 
+遇到新能力时，按下面判断：
 
+### 应该放进 `models`
 
+- 是共享数据结构
+- 是共享 RDF 词汇表
+- 是共享 repository / helper
+- 是公开协议合同
+- 是跨产品都可复用的纯函数级治理 helper
 
+### 不该放进 `models`
 
+- 只服务某一个产品
+- 需要依赖具体运行时环境
+- 本质是 transport / daemon / server 实现
+- 带有明显产品策略或产品默认行为
 
+## 与 `xpod` 的关系
 
+`models` 提供共享 SDK 面。
 
+`xpod` 可以在其上继续提供更高层的一等 API、服务实现和运行时能力。  
+当某个协议或治理流程稳定且影响面足够大时，再考虑晋升为 `xpod` 一等 API。
 
+## 开发约定
 
+- 优先使用 Solid / RDF 叙事，而不是 SQL 表叙事
+- 优先复用标准词汇表，缺失时再扩展 `UDFS`
+- 共享真相先进入 `models`
+- 产品特化行为留在产品层