@undefineds.co/linx 0.2.15 → 0.2.17

package/dist/skills/drizzle-solid/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: drizzle-solid
+description: Drizzle Solid ORM 专家，处理 Pod 数据 CRUD、Schema 定义、查询优化、SPARQL 端点配置等问题
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# Drizzle Solid ORM 专家
+
+你是 XPod 项目的 Drizzle Solid ORM 专家。帮助设计和实现基于 drizzle-solid 的 Pod 数据访问层。
+
+## 核心概念
+
+### drizzle-solid 是什么
+
+drizzle-solid 是一个为 Solid Pod 设计的类型安全 ORM，基于 Drizzle ORM 构建，让你能够像操作传统数据库一样操作 Solid Pod 中的 RDF 数据。
+
+### 服务器支持
+
+| 能力 | 原生 CSS | xpod |
+|------|----------|------|
+| **基础 CRUD** | ✅ LDP 模式 | ✅ LDP 模式 |
+| **SPARQL SELECT** | ❌ 不支持（Comunica 客户端执行） | ✅ 服务端索引下推 |
+| **SPARQL UPDATE** | ⚠️ 仅 BGP 写入 | ✅ 完整支持 |
+| **条件查询** (where) | Comunica 读文件到内存 | 索引下推（单 Pod） |
+| **聚合函数** (count/sum/avg) | Comunica 读文件到内存 | 索引下推（单 Pod） |
+| **SPARQL 端点** | ❌ 不支持 | ✅ `/-/sparql` Sidecar |
+
+## Schema 定义
+
+### podTable 配置
+
+```typescript
+import { podTable, string, int, datetime, uri } from '@undefineds.co/drizzle-solid';
+
+const userTable = podTable('users', {
+  id: string('id').primaryKey(),
+  name: string('name'),
+  email: string('email'),
+  age: int('age'),
+  createdAt: datetime('createdAt'),
+}, {
+  base: '/data/users/',           // 容器或资源路径
+  type: 'https://schema.org/Person',  // RDF 类型
+  namespace: UDFS_NAMESPACE,      // 自定义命名空间
+  subjectTemplate: '{id}.ttl#this',   // subject URI 模板
+  sparqlEndpoint: '/data/users/-/sparql',  // xpod SPARQL 端点
+  typeIndex: 'private',           // TypeIndex 注册
+  autoRegister: true,             // 自动注册到 TypeIndex
+});
+```
+
+### subjectTemplate 模式
+
+#### Document 模式（每条记录独立文件）
+
+```typescript
+// 每个用户一个文件: /users/alice.ttl, /users/bob.ttl
+const userTable = podTable('users', { ... }, {
+  base: '/users/',
+  subjectTemplate: '{id}.ttl',  // 或 '{id}.ttl#this'
+});
+
+// 按日期分片: /logs/2026/01/17/log-001.ttl
+const logTable = podTable('logs', { ... }, {
+  base: '/logs/',
+  subjectTemplate: '{yyyy}/{MM}/{dd}/{id}.ttl',
+});
+```
+
+#### Fragment 模式（多条记录共享文件）
+
+```typescript
+// 所有消息在同一文件: /chat/room.ttl#msg-1, /chat/room.ttl#msg-2
+const messageTable = podTable('messages', { ... }, {
+  base: '/chat/room.ttl',
+  subjectTemplate: '#{id}',  // 强制 fragment 模式
+});
+```
+
+### 关联表设计（同文件存储）
+
+当需要将关联数据存储在同一文件时：
+
+```typescript
+// Thread 和 Message 存储在同一文件
+const ChatThread = podTable('ChatThread', {
+  id: string('id').primaryKey(),
+  title: string('title'),
+}, {
+  base: '/chat/',
+  subjectTemplate: '{id}.ttl#this',  // /chat/thread-1.ttl#this
+});
+
+const ChatMessage = podTable('ChatMessage', {
+  id: string('id').primaryKey(),
+  threadId: string('threadId'),
+  content: string('content'),
+}, {
+  base: '/chat/',
+  subjectTemplate: '{threadId}.ttl#{id}',  // /chat/thread-1.ttl#msg-1
+});
+```
+
+**注意**：使用 `{threadId}` 等外键变量时，查询需要配合 `sparqlEndpoint` 才能跨文件查询。
+
+## SPARQL 端点配置（xpod 专用）
+
+### Fragment Mode（推荐）
+
+LDP 和 SPARQL 完全兼容：
+
+```typescript
+const postsTable = podTable('posts', { ... }, {
+  base: '/data/posts.ttl',
+  subjectTemplate: '#{id}',
+  sparqlEndpoint: '/data/posts.ttl/-/sparql',
+});
+```
+
+### Document Mode + 容器端点
+
+用于跨文件查询：
+
+```typescript
+const usersTable = podTable('users', { ... }, {
+  base: '/data/users/',
+  subjectTemplate: '{id}.ttl#this',
+  sparqlEndpoint: '/data/users/-/sparql',  // 容器级 SPARQL 端点
+});
+```
+
+**重要**：Document Mode 下，SPARQL 写操作与 LDP 文件视图不兼容！
+- SPARQL INSERT 不会创建 LDP 文件
+- SPARQL UPDATE 不会更新 LDP 文件
+- 建议：写操作用 LDP，读操作可用 SPARQL 聚合查询
+
+## 查询操作
+
+### 基础 CRUD
+
+```typescript
+import { drizzle, eq, and, gte } from '@undefineds.co/drizzle-solid';
+
+const db = drizzle(session, { schema });
+
+// 查询所有
+const users = await db.select().from(userTable);
+
+// 条件查询
+const adults = await db.select()
+  .from(userTable)
+  .where(gte(userTable.age, 18));
+
+// 复合条件
+const result = await db.select()
+  .from(userTable)
+  .where(and(
+    eq(userTable.status, 'active'),
+    gte(userTable.age, 18)
+  ));
+
+// 插入
+await db.insert(userTable).values({
+  id: 'user-1',
+  name: 'Alice',
+  email: 'alice@example.com',
+});
+
+// 更新
+await db.update(userTable)
+  .set({ name: 'Alice Smith' })
+  .where(eq(userTable.id, 'user-1'));
+
+// 删除
+await db.delete(userTable)
+  .where(eq(userTable.id, 'user-1'));
+```
+
+### Drizzle 风格查询
+
+```typescript
+const db = drizzle(session, { schema });
+
+// findMany
+const users = await db.query.users.findMany({
+  where: { verified: true },
+  orderBy: [{ column: schema.users.name, direction: 'asc' }],
+  with: { posts: true },  // 关联查询
+});
+
+// findFirst
+const user = await db.query.users.findFirst({
+  where: eq(schema.users.id, 'user-1'),
+});
+
+// findByIri
+const alice = await db.findByIri(schema.users, 'https://pod.example/data/users.ttl#alice');
+```
+
+### 聚合查询
+
+```typescript
+import { count, max, sum, avg } from '@undefineds.co/drizzle-solid';
+
+const stats = await db
+  .select({
+    totalUsers: count(),
+    oldestAge: max(userTable.age),
+  })
+  .from(userTable);
+```
+
+## 初始化与容器创建
+
+```typescript
+// 初始化表（创建容器、资源，注册 TypeIndex）
+await db.init([userTable, postTable]);
+
+// 手动确保容器存在
+// drizzle-solid 会自动处理，但如果需要手动控制：
+// 1. 先 HEAD 检查容器是否存在
+// 2. 不存在则 PUT 创建
+```
+
+## 常见问题
+
+### 1. 查询返回空数组
+
+**可能原因**：
+- Document Mode 下没有配置 `sparqlEndpoint`
+- 容器不存在
+- 数据存储在不同文件，但没有使用容器级 SPARQL 端点
+
+**解决方案**：
+```typescript
+// 配置容器级 SPARQL 端点
+const table = podTable('items', { ... }, {
+  base: '/data/items/',
+  sparqlEndpoint: '/data/items/-/sparql',
+});
+```
+
+### 2. 写入后查询不到数据
+
+**可能原因**：Document Mode 下混用了 SPARQL 写入和 LDP 读取
+
+**解决方案**：
+- 使用 Fragment Mode（推荐）
+- 或者统一使用 LDP 操作
+
+### 3. subjectTemplate 中的变量不生效
+
+**正确用法**：
+```typescript
+// 使用 {id} 引用主键
+subjectTemplate: '{id}.ttl#this'
+
+// 使用其他字段（如 threadId）
+subjectTemplate: '{threadId}.ttl#{id}'
+```
+
+**注意**：变量必须是 schema 中定义的字段名。
+
+### 4. TypeIndex 注册失败
+
+**检查**：
+- 确保 `typeIndex: 'private'` 或 `'public'` 已设置
+- 确保 `autoRegister: true`（默认）
+- 确保用户有权限写入 TypeIndex
+
+## 最佳实践
+
+### 1. 优先使用 Fragment Mode
+
+```typescript
+// 推荐：所有数据在一个文件
+const table = podTable('items', { ... }, {
+  base: '/data/items.ttl',
+  subjectTemplate: '#{id}',
+  sparqlEndpoint: '/data/items.ttl/-/sparql',
+});
+```
+
+### 2. 需要文件隔离时使用 Document Mode + SPARQL 端点
+
+```typescript
+// 每条记录独立文件，但通过 SPARQL 端点聚合查询
+const table = podTable('items', { ... }, {
+  base: '/data/items/',
+  subjectTemplate: '{id}.ttl#this',
+  sparqlEndpoint: '/data/items/-/sparql',
+});
+```
+
+### 3. 关联数据存储在同一文件
+
+```typescript
+// Thread 和 Message 在同一文件，便于原子操作
+const ChatThread = podTable('ChatThread', { ... }, {
+  base: '/chat/',
+  subjectTemplate: '{id}.ttl#this',
+});
+
+const ChatMessage = podTable('ChatMessage', { ... }, {
+  base: '/chat/',
+  subjectTemplate: '{threadId}.ttl#{id}',
+});
+```
+
+### 4. 使用 namespace 统一管理自定义谓词
+
+```typescript
+import { UDFS_NAMESPACE } from '@/vocab';
+
+const table = podTable('items', {
+  status: string('status'),  // 映射到 udfs:status
+}, {
+  namespace: UDFS_NAMESPACE,
+});
+```
+
+## 参考资料
+
+- drizzle-solid README: `node_modules/@undefineds.co/drizzle-solid/README.md`
+- 项目 vocab 定义: `src/vocab/`
+- 现有 schema 示例: `src/api/chatkit/schema.ts`, `src/credential/schema/tables.ts`
+
+## 问题反馈
+
+如果发现 drizzle-solid 设计不合理或存在 bug，通过 git MCP 向 drizzle-solid 仓库提 issue：
+
+```
+仓库: undefinedsco/drizzle-solid
+```
+
+提 issue 时请包含：
+1. 问题描述
+2. 复现步骤
+3. 期望行为 vs 实际行为
+4. 相关代码片段

package/dist/skills/pod-storage/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: pod-storage
+description: Pod 文件系统操作 — 使用 pod_read/pod_write 读写用户 Pod 中的数据。
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, pod_read, pod_write
+---
+
+# Pod 文件系统
+
+用户的数据存储在 Pod 中。访问 Pod 文件使用 `pod_read` / `pod_write`（不是本地 read/write）。
+
+## 路径约定
+
+```
+/alice/
+  ├── settings/           # 配置和凭据
+  │   ├── credentials.ttl # 第三方 API key
+  │   └── preferences.ttl # 用户偏好
+  ├── logs/               # 工具/Agent 输出日志
+  │   └── tasks/          # 按任务组织
+  ├── repos/              # git 仓库工作区
+  └── data/               # 用户自己的数据
+```
+
+## 读写
+
+```
+pod_read /alice/settings/credentials.ttl
+pod_write /alice/settings/credentials.ttl "content"
+```
+
+用 `pod_read` 读 Pod 文件，`pod_write` 写 Pod 文件。Content-Type 由扩展名自动推断（.ttl → text/turtle）。
+
+## 凭据约定
+
+第三方 API key 存在 `/alice/settings/credentials.ttl`，每条一个节点：
+
+```turtle
+@prefix xpod: <https://undefineds.co/xpod#> .
+
+<#jina> xpod:apiKey "jina_xxx" .
+<#openai> xpod:apiKey "sk-xxx" .
+```
+
+需要 key 时先用 `pod_read` 读这个文件。没有就引导用户去对应网站注册，拿到后用 `pod_write` 写入。
+
+写入时注意保留已有内容，只修改目标凭据行。
+
+## 查找
+
+不知道文件在哪时用 `bash` 配合 Pod HTTP API，或用 Grep 搜索本地 Pod mirror。
+
+## 日志
+
+工具执行结果写入 `/alice/logs/`，按任务 ID 分目录：
+
+```
+/alice/logs/tasks/task-001/
+  ├── stdout.log
+  └── result.json
+```

package/dist/skills/solid-modeling/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: solid-modeling
+description: Solid/RDF 数据建模专家，处理 Pod 数据结构设计、类继承、属性定义、命名空间等问题
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# Solid/RDF 数据建模专家
+
+你是 XPod 项目的 Solid/RDF 数据建模专家。帮助设计符合 Solid 规范和 RDF 最佳实践的数据模型。
+
+## 核心原则
+
+### 数据主权
+
+用户数据存储在用户自己的 Pod 中，服务器不存储用户数据。
+
+### 标准词汇表优先
+
+优先复用已有的标准词汇表，只在必要时定义自定义词汇。
+
+| 用途 | 词汇表 | 前缀 | 导入 |
+|------|--------|------|------|
+| 自定义 | Undefineds Namespace | `udfs:` | `import { UDFS } from '@/vocab'` |
+| RDF 基础 | RDF/RDFS | `rdf:`, `rdfs:` | `import { RDF, RDFS } from '@/vocab'` |
+| 时间/元数据 | Dublin Core | `dc:` | `import { DCTerms } from '@/vocab'` |
+| 容器/资源 | LDP | `ldp:` | `import { LDP } from '@/vocab'` |
+| 个人信息 | FOAF | `foaf:` | `import { FOAF } from '@/vocab'` |
+| 访问控制 | ACL | `acl:` | `import { ACL } from '@/vocab'` |
+| 数据类型 | XSD | `xsd:` | `import { XSD } from '@/vocab'` |
+
+## 命名规范
+
+### 词汇表命名
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| **Class** | PascalCase (大写开头) | `Credential`, `Provider`, `Model` |
+| **Property** | camelCase (小写开头) | `apiKey`, `baseUrl`, `createdAt` |
+| **实例 ID** | kebab-case | `#my-entity`, `#instance-001` |
+
+### 使用 Vocab 定义
+
+项目使用 `src/vocab/` 统一管理词汇表：
+
+```typescript
+// src/vocab/udfs.ts - UDFS 词汇表
+export const UDFS = createNamespace('udfs', 'https://undefineds.co/ns#', {
+  // Classes (大写)
+  Credential: 'Credential',
+  Provider: 'Provider',
+  Model: 'Model',
+
+  // Properties (小写)
+  apiKey: 'apiKey',
+  baseUrl: 'baseUrl',
+  status: 'status',
+});
+```
+
+**使用方式**：
+
+```typescript
+import { UDFS, UDFS_NAMESPACE } from '@/vocab';
+
+// 使用 Class
+const type = UDFS.Credential;  // 'https://undefineds.co/ns#Credential'
+
+// 使用 Property
+const prop = UDFS.apiKey;  // 'https://undefineds.co/ns#apiKey'
+
+// 动态构建 URI
+const custom = UDFS('CustomTerm');  // 'https://undefineds.co/ns#CustomTerm'
+```
+
+## drizzle-solid Schema 定义
+
+项目级业务语义不要写进这个 skill 文件。
+
+- 这类定义应放在仓库的 models/schema/docs 里，由代码和 shared docs 作为单一真相。
+- 这个 skill 只保留通用 Solid/RDF 建模原则、drizzle-solid 约束和可复用的模式。
+- 如果某个产品需要定义 `chat` / `thread` / `session` 的具体含义，应写回对应 package 的 schema 注释和 shared docs，而不是放到 skill。
+
+### 基本结构
+
+```typescript
+import { podTable, string, uri, datetime, int } from 'drizzle-solid';
+import { UDFS, UDFS_NAMESPACE } from '../vocab';
+
+/**
+ * Credential - 凭据
+ *
+ * 存储位置: /settings/credentials.ttl
+ */
+export const Credential = podTable(
+  'Credential',  // 表名用 PascalCase
+  {
+    id: string('id').primaryKey(),
+    provider: uri('provider'),
+    apiKey: string('apiKey'),
+    status: string('status'),
+    createdAt: datetime('createdAt'),
+  },
+  {
+    base: '/settings/credentials.ttl',
+    type: UDFS.Credential,  // 使用 vocab 而不是硬编码字符串
+    namespace: UDFS_NAMESPACE,
+    subjectTemplate: '#{id}',
+  },
+);
+```
+
+### 关系定义
+
+```typescript
+import { relations } from 'drizzle-solid';
+
+export const CredentialRelations = relations(Credential, ({ one }) => ({
+  provider: one(Provider, {
+    fields: [Credential.provider],
+    references: [Provider.id],
+  }),
+}));
+```
+
+## 类设计
+
+### 使用 Class 继承表达用途分类
+
+当实体有共同特征但不同用途时，使用 `rdfs:subClassOf`：
+
+```turtle
+# 基类
+udfs:Provider a rdfs:Class ;
+  rdfs:label "Provider" ;
+  rdfs:comment "服务供应商基类" .
+
+# 子类 - 按用途区分
+udfs:AgentProvider rdfs:subClassOf udfs:Provider ;
+  rdfs:label "Agent Provider" .
+```
+
+### 用属性区分实现细节
+
+具体实现方式用属性表达，不用子类：
+
+```turtle
+# 正确：用属性区分实现类型
+<#provider-a> a udfs:Provider ;
+  udfs:executorType "claude" .
+
+<#provider-b> a udfs:Provider ;
+  udfs:executorType "openai" .
+
+# 错误：不要为每种实现创建子类
+# udfs:ClaudeProvider rdfs:subClassOf udfs:Provider .  ❌
+```
+
+**规则**：
+- Class 继承区分**用途/功能**
+- 属性区分**具体实现**
+
+### 定义与实例分离
+
+静态定义（模板）和运行时实例分开建模：
+
+```turtle
+# 定义（模板） - 静态配置，描述"是什么"
+<#agent-config> a udfs:AgentConfig ;
+    udfs:displayName "Indexing Agent" ;
+    udfs:systemPrompt "..." .
+
+# 实例 - 运行时状态，描述"正在做什么"
+<#agent-status> a udfs:AgentStatus ;
+    udfs:agentId "indexing" ;
+    udfs:status "running" ;
+    udfs:currentTaskId "task-123" .
+```
+
+## 属性设计
+
+### 使用 URI 引用关联实体
+
+实体间关系用 URI 引用，不用字符串：
+
+```turtle
+# 正确：URI 引用
+<#credential> a udfs:Credential ;
+  udfs:provider </settings/ai/providers.ttl#google> .
+
+# 错误：字符串值
+<#credential> a udfs:Credential ;
+  udfs:provider "google" .  ❌
+```
+
+### 时间字段统一用 datetime
+
+```typescript
+// 正确
+createdAt: datetime('createdAt'),
+updatedAt: datetime('updatedAt'),
+
+// 错误 - 不要用 string 存时间
+startedAt: string('startedAt'),  // ❌
+```
+
+### 布尔值
+
+drizzle-solid 目前用 string 存储布尔值：
+
+```typescript
+enabled: string('enabled'),  // 存储 "true" / "false"
+```
+
+代码中需要手动比较：`enabled === 'true'`
+
+## 文件组织
+
+### 按功能分文件
+
+```
+pod:/settings/
+├── ai/
+│   ├── providers.ttl      # AI 供应商
+│   ├── models.ttl         # AI 模型
+│   ├── agent-providers.ttl # Agent 供应商
+│   ├── agents.ttl         # Agent 配置
+│   ├── agent-status.ttl   # Agent 状态
+│   ├── config.ttl         # Pod 级 AI 配置
+│   ├── vector-stores.ttl  # 向量知识库
+│   └── indexed-files.ttl  # 已索引文件
+├── credentials.ttl        # 凭据（敏感信息单独存放）
+└── prefs.ttl              # 用户偏好设置
+```
+
+### 文件引用规则
+
+同文件用 `#fragment`，跨文件用完整路径：
+
+```turtle
+# 同文件引用
+<#entity-a> udfs:relatedTo <#entity-b> .
+
+# 跨文件引用
+<#credential> udfs:provider </settings/ai/providers.ttl#google> .
+
+# 跨 Pod 引用
+<#entity-a> udfs:relatedTo <https://other.pod/file.ttl#entity-b> .
+```
+
+## 检查清单
+
+设计新数据模型时：
+
+- [ ] 是否有可复用的标准词汇表？
+- [ ] 新词汇是否已添加到 `src/vocab/udfs.ts`？
+- [ ] Class 名是否大写开头？Property 名是否小写开头？
+- [ ] 类继承是否按用途区分（不是按实现）？
+- [ ] 定义和实例是否分离？
+- [ ] 实体关系是否用 URI 引用（不是字符串）？
+- [ ] 时间字段是否用 `datetime()` 类型？
+- [ ] 敏感数据是否单独存放？
+- [ ] Schema 是否使用 `UDFS.ClassName` 而不是硬编码字符串？
+
+## 参考文件
+
+- **Vocab 定义**: `src/vocab/udfs.ts`, `src/vocab/external.ts`
+- **Credential Schema**: `src/credential/schema/tables.ts`
+- **Embedding Schema**: `src/embedding/schema/tables.ts`
+- **Agent Schema**: `src/agents/schema/`
+- **Task Schema**: `src/task/schema.ts`
+- **Credential Schema**: `src/credential/schema/tables.ts`
+- **Embedding Schema**: `src/embedding/schema/tables.ts`
+- **Agent Schema**: `src/agents/schema/`
+- **Task Schema**: `src/task/schema.ts`