@undefineds.co/models 0.2.19 → 0.2.22

package/README.md

@@ -1,593 +1,249 @@
-# LinX 数据模型
+# LinX Models
 
-> 基于 Solid Pod 标准的 LinX 核心数据模型定义
->
-> 使用 `drizzle-solid` ORM，兼容标准 RDF 词汇表（VCARD, FOAF, SIOC, DCTerms 等）
+`@undefineds.co/models` is the shared Solid Pod data model contract for LinX
+apps, desktop, CLI, sidecars, and future workers.
 
----
+Application shells should use these schemas, repositories, and helpers directly.
+Do not duplicate shared predicates, subject templates, Turtle serializers,
+resource state machines, or cross-app use-case logic in `apps/*`.
 
-## 📋 目录
+## Package
 
-- [概述](#概述)
-- [标准词汇表](#标准词汇表)
-- [核心模型](#核心模型)
-- [使用示例](#使用示例)
-- [设计原则](#设计原则)
-
----
-
-## 概述
-
-LinX 的所有数据存储在 Solid Pod 中，使用标准的 RDF 格式。本包定义了所有核心业务实体的数据模型，包括：
-
-### 核心功能模型
-
-1. **Profile** - 用户资料
-2. **Contact** - 联系人管理（支持自然人和 AI）
-3. **Chat & Message** - 聊天会话和消息
-4. **File** - 文件管理
-5. **Favorite** - 收藏夹
-6. **Settings** - 用户设置
-7. **AI Assistant** - AI 助手配置
-
-### 其他模型
-
-- **Session** - 会话管理
-- **Knowledge Folder** - 知识库文件夹
-- **Extension** - 扩展
-- **Model Credential** - 模型凭证
-- **Import Job** - 导入任务
-
----
-
-## Chat / Thread / Message / Session 语义
-
-这组语义是 CLI、App、watch/runtime 共享的 models 级业务真相，不应在 UI、CLI 壳层或 skill 文件中重新定义。
-
-- **Chat** 表示对话对象/counterpart：用户正在和谁或什么对话，例如默认 AI secretary、某个人、群组、Codex、Claude Code，或后续具体 AI 身份。
-- **Thread** 表示具体场所、时间线和 runtime context：workspace、watch 场景、AI 产品运行时 session、外部 agent session 等上下文都归在 thread 上。
-- **Message** 同时属于一个 `chat` 和一个 `thread`：chat 回答“跟谁聊”，thread 回答“在哪个运行/时间线里聊”。
-- **Session** 表示通用 AI 产品/agent runtime 的运行生命周期投影：它必须指向对应的 `chat` URI 和 `thread` URI，不能作为另一套对话根。
-
-存储层规则：
-
-- Pod schema 使用 `chat`、`thread` 这类 URI-valued RDF relation 字段。
-- `chatId`、`threadId` 只允许作为 UI 状态、函数参数、runtime protocol 字段或 metadata 中的兼容信息，不允许作为持久 RDF link 字段。
-- 新增 shared model 代码优先使用 `chatResource`、`threadResource`、`messageResource`、`sessionResource` 等 Solid resource 命名；`*Table` 只作为兼容 alias 逐步退出。
-- 如果壳层需要新的查询、upsert、resolve-by-uri、审计或审批状态变更能力，优先在本包新增 repository/helper 和 tests；不要在 CLI/App 中复制 predicate、subject template、Turtle 读写或 shared 状态机。
-- `approval` / `grant` / `audit` / `inboxNotification` / `session` 等跨端控制面也属于本包的 shared resource 语义。CLI/App 只负责把 Pi/Codex/Claude 等运行时事件映射成本包定义的 insert/update DTO，不能另建一套存储路径或审批策略。
-- approval 的倒计时和可选决策也属于 shared resource 语义：使用 `approvalResource.expiresAt` 表示截止时间，使用 `approvalResource.approvalOptions` 存储上游原生协议给出的可选决策（例如 `allow_once` / `allow_always` / `reject_once`）。CLI/App 不得各自用私有 predicate 或本地状态推断这些字段。
-- grant 是可维护的 LLM Wiki 文档资源，不是一次请求的 fingerprint。`grantResource` 使用 `/settings/autonomy/grants/{id}.ttl`，文档 URI 本身就是 RDF subject；通过 `title/summary/body/schema/pageKind/wikiStatus/tags/source/sourceHash/compiledAt/compiledFrom/related/context` 描述页面语义、来源和上下文。
-- `grant.schema` 使用 `dcterms:conformsTo` 指向 Solid schema/shape URI，例如 `/settings/autonomy/schema/grant.ttl#GrantWikiPage`；它不是 `path`/`wikiPath` 字符串，TTL wiki page 也不需要 `.meta` subject。
-- `grant.target`、`grant.action`、`grant.riskCeiling` 只用于候选筛选或排序，不得作为最终自动审批判定。最终是否覆盖必须看 wiki page 的 `body/summary/tags/source/provenance/context` 与当前请求的语义匹配结果。
-- CLI/App 不得为 shared 控制面字段自定义业务 predicate。新增 approval/grant/audit 字段必须先在本包的 namespace、vocab、schema 和 tests 中定义。
-- structured user-input 与 approval 一样属于 watch 共享协议：AI secretary 只能在答案能从请求上下文明确推出时代答，否则必须回到人工输入。
-
----
-
-## 标准词汇表
-
-LinX 遵循 Solid 生态的最佳实践，优先使用标准 RDF 词汇表：
-
-### 已集成的标准词汇表
-
-| 词汇表 | 用途 | 规范 |
-|--------|------|------|
-| **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/) |
-
-### LinX 自定义词汇表
-
-命名空间：`https://linx.ai/ns#`
-
-用于标准词汇表未覆盖的 LinX 特有功能（如 AI 助手配置、同步状态等）。
-
----
-
-## 核心模型
-
-### 1. Profile（用户资料）
-
-**文件路径**: `src/profile.ts`
-
-**RDF 类**: `foaf:Person`
-
-**字段**:
-```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
-}
+```bash
+yarn workspace @undefineds.co/models build
+yarn workspace @undefineds.co/models test
 ```
 
----
-
-### 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)
-}
+```ts
+import {
+  UDFS,
+  XPOD_AI,
+  XPOD_CREDENTIAL,
+  agentResource,
+  aiModelResource,
+  aiProviderResource,
+  chatResource,
+  contactResource,
+  credentialResource,
+  messageResource,
+  selectAIConfigCredential,
+  threadResource,
+} from '@undefineds.co/models'
 ```
 
-**常量**:
-- `CONTACT_TYPES`: `person`, `ai`, `organization`, `group`
-- `RELATIONSHIP_TYPES`: `friend`, `family`, `colleague`, `acquaintance`, `other`
-
----
-
-### 3. Chat（聊天会话）
+## Namespaces
 
-**文件路径**: `src/chat/chat.schema.ts`
+LinX-owned predicates and classes use the company namespace:
 
-**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
-}
+```text
+https://undefineds.co/ns#
 ```
 
----
-
-### 4. Message（聊天消息）
-
-**文件路径**: `src/chat/message.schema.ts`
+Use `udfs:` terms in models-level RDF contracts.
 
-**RDF 类**: `schema:Message`
+AI service catalog resources currently use the Xpod AI vocabularies:
 
-**字段**:
-```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
-}
+```text
+https://vocab.xpod.dev/ai#
+https://vocab.xpod.dev/credential#
 ```
 
----
-
-### 5. File（文件管理）
+## Core Runtime Semantics
 
-**文件路径**: `src/file/file.schema.ts`
+The shared chat/runtime model is:
 
-**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
-}
+```text
+Chat       = who or what the user is talking with
+Thread     = the concrete timeline/place/runtime context under a Chat
+Message    = a message in both a Chat and a Thread
+Session    = one Agent runtime execution bound to Agent + Thread + Workspace
+Agent      = executable capability root with its own home/config filesystem
+Workspace  = concrete working code area/worktree metadata
+Repository = durable source-control metadata, not the working directory
 ```
 
----
+Detailed Agent-centered runtime, Repository/Workspace, branch/ref, Agent home,
+and Session binding rules live in:
 
-### 6. Favorite（收藏）
+- [`docs/agent-runtime-model.md`](docs/agent-runtime-model.md)
 
-**文件路径**: `src/favorite/favorite.schema.ts`
+## Agent vs AI Config
 
-**RDF 类**: `schema:CreativeWork`
+`agentResource` and `ai-config` intentionally both mention provider/model, but
+they are not the same resource.
 
-**支持收藏类型**: `message`, `file`, `contact`, `link`, `note`
+`agentResource` answers: which executable actor is this, and what defaults
+should it use at runtime?
 
-**字段**:
-```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
-}
-```
-
----
-
-### 7. Settings（用户设置）
-
-**文件路径**: `src/settings/settings.schema.ts`
-
-**RDF 类**: `schema:PropertyValue`
+Current Agent fields include:
 
-**字段**:
-```typescript
+```ts
 {
-  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
+  name: string
+  description?: string
+  avatarUrl?: string
+  instructions?: string
+  provider?: string
+  model?: string
+  temperature?: number
+  tools?: string[]
+  contextRound?: number
+  ttsModel?: string
+  videoModel?: string
 }
 ```
 
-**预定义设置键** (`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"
-```
-
----
-
-### 8. AI Assistant（AI 助手配置）
+Agent owns runtime preference and capability state. It should not own shared
+API keys, endpoint catalogs, provider model lists, or credential rotation
+policy.
 
-**文件路径**: `src/agent.schema.ts`
+`ai-config` answers: which AI services are available, which models belong to a
+provider, and which credential should be used for a provider call?
 
-**RDF 类**: `foaf:Agent`
+The resources are:
 
-**字段**:
-```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;
-}
+```text
+aiProviderResource   /settings/providers/{providerId}.ttl
+aiModelResource      /settings/providers/{providerId}.ttl#{modelId}
+credentialResource   /settings/credentials.ttl#{credentialId}
 ```
 
-**常量**:
-- `AI_PROVIDERS`: `openai`, `anthropic`, `google`, `ollama`, `custom`
-- `AI_MODELS`: 包含常见模型 ID（GPT-4, Claude-3, Gemini, Llama2 等）
+The separation is:
 
----
+```text
+Agent.provider / Agent.model
+  runtime default selection for one Agent
 
-## 使用示例
+AI Provider
+  endpoint/catalog/family metadata such as baseUrl, proxyUrl, defaultModel
 
-### 安装
+AI Model
+  provider-provided model metadata linked by isProvidedBy
 
-```bash
-yarn workspace @linq/models install
+Credential
+  named secret and routing state linked to a provider
 ```
 
-### 导入模型
-
-```typescript
-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";
-```
+Credential selection uses the shared helper:
 
-### 查询示例
-
-```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,
-  });
+```ts
+const selected = selectAIConfigCredential('openai', credentialRows, providerRows)
 ```
 
----
-
-## 设计原则
+Selection semantics:
 
-### 1. 遵循 Solid 标准
+- Only active `service = "ai"` credentials with an API key are candidates.
+- A credential marked `isDefault` is preferred.
+- If multiple defaults exist, the oldest `lastUsedAt` wins.
+- If no default exists, credentials rotate by oldest `lastUsedAt`.
+- `failCount` and stable id are tie breakers.
+- Callers should update `lastUsedAt` after using the selected credential.
 
-- ✅ 优先使用标准 RDF 词汇表（VCARD, FOAF, SIOC, DCTerms）
-- ✅ 仅在必要时使用自定义词汇表（`linx:` 命名空间）
-- ✅ 所有数据存储在 Pod 的 LDP 容器中
-- ✅ 使用标准 RDF 类（`vcard:Individual`, `schema:Message` 等）
+This means `ai-config` is a shared service/credential pool. Agent records only
+refer to a provider/model default and runtime parameters.
 
-### 2. 类型安全
+## Contact / Person / Agent
 
-- ✅ 使用 `drizzle-solid` 提供的类型推断
-- ✅ 导出 `Row`, `Insert`, `Update` 类型
-- ✅ 定义常量枚举（`CONTACT_TYPES`, `SETTING_KEYS` 等）
+Contact, Person, and Agent are distinct:
 
-### 3. 可扩展性
+```text
+Contact = address-book/social projection shown in Contacts and Chat
+Person  = natural human identity
+Agent   = executable runtime/capability root with an Agent home
+```
 
-- ✅ 支持软删除（`deletedAt` 字段）
-- ✅ 支持 JSON 字段存储复杂数据（标签、数组等）
-- ✅ 预留扩展字段（`tags`, `metadata`）
+AI Secretary has both:
 
-### 4. 互操作性
+```text
+Contact
+  contactType: agent
+  entityUri: Agent profile URI
 
-- ✅ 与其他 Solid 应用兼容
-- ✅ 使用标准的 RDF 谓词
-- ✅ 遵循 SolidOS 的数据规范
+Agent
+  home: /.data/agents/secretary/
+  profile: /.data/agents/secretary/profile.ttl
+```
 
-### 5. 性能优化
+External people, services, or bots may appear as Contacts without being LinX
+Agents. If something is modeled as an executable LinX Agent, it must have an
+Agent home container.
+
+## Resource Ownership
+
+Use Resource-first names in shared code:
+
+```text
+contactResource
+chatResource
+threadResource
+messageResource
+agentResource
+aiProviderResource
+aiModelResource
+credentialResource
+sessionResource
+approvalResource
+grantResource
+auditResource
+inboxNotificationResource
+```
 
-- ✅ 快照字段避免频繁查询（如 `Favorite.snapshotContent`）
-- ✅ 冗余字段提升列表显示性能（如 `Message.senderName`）
-- ✅ 索引常用查询字段
+`*Table` exports are compatibility aliases for existing drizzle-solid call
+sites. New shared model code should prefer `*Resource`.
 
----
+## Pod Storage Patterns
 
-## 开发指南
+Representative paths:
 
-### 添加新模型
+```text
+/.data/contacts/{contactId}.ttl
+/.data/chat/{chatId}/index.ttl#this
+/.data/chat/{chatId}/index.ttl#{threadId}
+/.data/chat/{chatId}/{yyyy}/{MM}/{dd}/messages.ttl#{messageId}
+/.data/agents/{agentId}/profile.ttl
+/.data/sessions/{yyyy}/{MM}/{dd}/{sessionId}.ttl
+/settings/providers/{providerId}.ttl
+/settings/providers/{providerId}.ttl#{modelId}
+/settings/credentials.ttl#{credentialId}
+```
 
-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
+Schema fields that are RDF relations should store resource URIs, not hidden
+`xxxId` foreign keys. Short ids are acceptable at repository/helper boundaries
+when the helper derives the canonical URI internally.
 
-### 修改现有模型
+## Design Rules
 
-⚠️ **注意**：修改模型可能影响现有数据！
+- Prefer standard RDF vocabularies such as VCARD, FOAF, SIOC, DCTerms,
+  Schema.org, LDP, and Solid Chat vocabularies.
+- Use `UDFS` only when a standard predicate does not describe the product
+  concept.
+- Keep UI-only state outside the Pod.
+- Put durable shared state in Pod resources owned by this package.
+- Add missing query/mutation helpers here before copying storage logic into
+  CLI, web, desktop, or plugins.
+- Do not store API secrets on Agent, Chat, Thread, Session, or Workspace.
+- Do not duplicate repository/Git metadata on Session; keep it on Workspace
+  metadata and snapshot it when audit requires reproducibility.
 
-- 添加字段：安全（向后兼容）
-- 删除字段：危险（需要数据迁移）
-- 重命名字段：危险（需要数据迁移）
-- 修改类型：危险（需要数据迁移）
+## Development Checklist
 
-### 测试
+When adding or changing a durable model:
 
-```bash
-# 运行测试（待添加）
-yarn workspace @linq/models test
+1. Add or update the schema/resource in `src/`.
+2. Add namespace terms in `src/namespaces.ts` when needed.
+3. Export the resource, row, insert, update, and repository/helper from
+   `src/index.ts`.
+4. Add tests for RDF predicates, subject templates, and cross-app helper
+   semantics.
+5. Update this README or the focused document under `docs/`.
 
-# 类型检查
-yarn workspace @linq/models typecheck
-```
+## References
 
----
-
-## 参考资料
-
-### Solid 规范
 - [Solid Protocol](https://solidproject.org/TR/protocol)
-- [Linked Data Platform (LDP)](https://www.w3.org/TR/ldp/)
+- [Linked Data Platform](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/)
+- [VCARD RDF](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 导出 |
-
----
-
-## 许可证
-
-MIT License