@undefineds.co/linx 0.3.5 → 0.3.8

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

@@ -1,274 +0,0 @@
----
-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`

package/dist/skills/xpod-componentsjs/SKILL.md

@@ -1,284 +0,0 @@
----
-name: xpod-componentsjs
-description: Xpod Components.js 变量和组件配置专家，处理 CLI 参数、变量解析、组件配置等问题
-allowed-tools: Read, Write, Edit, Grep, Glob, Bash
----
-
-# Xpod Components.js 配置专家
-
-你是 Xpod 项目的 Components.js 配置专家。Xpod 基于 Community Solid Server (CSS)，使用 Components.js 进行依赖注入。
-
-## 核心知识
-
-### 变量解析流程
-
-```
-环境变量 (CSS_XXX) 
-    ↓
-YargsCliExtractor (cli.json) - 解析 CLI 参数
-    ↓
-ShorthandResolver (resolver.json) - 将参数映射到 Components.js 变量
-    ↓
-Variable (配置文件中) - 在组件配置中引用变量
-```
-
-### 关键文件
-
-| 文件 | 作用 |
-|------|------|
-| `config/cli.json` | 声明 CLI 参数（YargsParameter） |
-| `config/resolver.json` | 将 CLI 参数映射到 Components.js 变量（KeyExtractor） |
-| `config/*.json` | 使用 `"@type": "Variable"` 引用变量 |
-| `dist/components/context.jsonld` | 自动生成的组件 context，包含参数名映射 |
-
-## 添加新变量的完整步骤
-
-### 步骤 1: cli.json 声明参数
-
-```json
-// config/cli.json
-{
-  "@type": "YargsParameter",
-  "name": "myNewParam",
-  "options": { 
-    "type": "string",
-    "hidden": true
-  }
-}
-```
-
-参数名使用 camelCase，对应环境变量自动转换：`myNewParam` → `CSS_MY_NEW_PARAM`
-
-### 步骤 2: resolver.json 添加 KeyExtractor（最容易遗漏！）
-
-```json
-// config/resolver.json
-{
-  "CombinedShorthandResolver:_resolvers_key": "urn:solid-server:default:variable:myNewParam",
-  "CombinedShorthandResolver:_resolvers_value": {
-    "@type": "KeyExtractor",
-    "key": "myNewParam",
-    "defaultValue": ""
-  }
-}
-```
-
-### 步骤 3: 配置文件中使用变量
-
-```json
-{
-  "myConfig": {
-    "@id": "urn:solid-server:default:variable:myNewParam",
-    "@type": "Variable"
-  }
-}
-```
-
-## 抽象类和接口的处理
-
-### 关键规则：Generator 只处理导出的类
-
-Components.js Generator (`componentsjs-generator`) 只会为 **从 `src/index.ts` 导出的类** 生成 `.jsonld` 文件。
-
-### 问题场景
-
-当一个类继承抽象基类或实现接口时：
-
-```typescript
-// 子类生成的 jsonld 会包含 extends 引用
-"extends": ["undefineds:dist/path/to/BaseClass.jsonld#BaseClass"]
-```
-
-如果 `BaseClass` 没有被导出，Generator 不会为它生成 jsonld，启动时会报错：
-
-```
-Error: Resource .../BaseClass.jsonld#BaseClass is not a valid component
-```
-
-### 解决方案
-
-**1. 确保抽象类/基类从 index.ts 导出**
-
-```typescript
-// src/index.ts
-import { MyBaseClass } from './path/to/MyBaseClass';
-import { MyImplClass } from './path/to/MyImplClass';
-
-export default {
-  MyBaseClass,      // ← 必须导出基类！
-  MyImplClass,
-};
-```
-
-**2. 使用 abstract class 而不是 interface**
-
-Generator **不会为 TypeScript interface 生成 jsonld**。如果有类 `implements` 一个 interface，必须将 interface 改为 abstract class：
-
-```typescript
-// ❌ 错误 - interface 不会生成 jsonld
-export interface QuintStore {
-  get(pattern: QuintPattern): Promise<Quint[]>;
-  put(quint: Quint): Promise<void>;
-}
-
-export class MyStore implements QuintStore { ... }
-```
-
-```typescript
-// ✅ 正确 - abstract class 会生成 jsonld
-export abstract class QuintStore {
-  abstract get(pattern: QuintPattern): Promise<Quint[]>;
-  abstract put(quint: Quint): Promise<void>;
-}
-
-export class MyStore extends QuintStore { ... }
-```
-
-**3. 子类继承时添加 super() 和 override**
-
-```typescript
-export class MyStore extends QuintStore {
-  constructor(options: Options) {
-    super();  // ← 必须调用 super()
-    this.options = options;
-  }
-  
-  override async get(pattern: QuintPattern): Promise<Quint[]> {
-    // 如果基类有可选方法的实现，需要 override 修饰符
-  }
-}
-```
-
-### 检查清单
-
-添加新的抽象类/基类时：
-
-- [ ] 使用 `abstract class` 而不是 `interface`
-- [ ] 在 `src/index.ts` 中导出该类
-- [ ] 子类使用 `extends` 而不是 `implements`
-- [ ] 子类构造函数调用 `super()`
-- [ ] 覆盖父类方法时添加 `override` 修饰符
-- [ ] 运行 `yarn build` 验证 jsonld 生成
-
-## 常见错误诊断
-
-### 错误: Resource is not a valid component
-
-```
-Error: Resource .../types.jsonld#QuintStore is not a valid component, 
-either it is not defined, has no type, or is incorrectly referenced
-```
-
-**原因**: 
-1. 使用了 TypeScript interface（Generator 不处理 interface）
-2. 抽象类/基类没有从 index.ts 导出
-
-**解决**: 
-1. 将 interface 改为 abstract class
-2. 在 index.ts 中导出该类
-3. 运行 `yarn build`
-
-### 错误: Could not find (valid) component types
-
-```
-ErrorResourcesContext: Could not find (valid) component types for config "urn:xxx:MyComponent" among its types, or a requireName
-```
-
-**原因**: 新增或重命名了 TypeScript 类，但没有重新生成 Components.js 的 `.jsonld` 组件定义文件
-**解决**: 运行完整编译 `npm run build`（不是 `npm run build:ts`），让 `componentsjs-generator` 生成新的 `.jsonld` 文件
-
-```bash
-# 错误 - 只编译 TypeScript，不会生成 .jsonld
-npm run build:ts
-
-# 正确 - 完整编译，包括 componentsjs-generator
-npm run build
-```
-
-### 错误: Undefined variable
-
-```
-Error: Undefined variable: urn:solid-server:default:variable:xxx
-```
-
-**原因**: resolver.json 中缺少对应的 KeyExtractor
-**解决**: 在 resolver.json 中添加变量映射
-
-### 错误: Multiple values for parameter
-
-```
-ErrorResourcesContext: Detected multiple values for parameter ... YargsCliExtractor_options
-```
-
-**原因**: xpod 的 cli.json 和 CSS 的 cli.json 都定义了 `options` 块
-**解决**: xpod 的 cli.json 不要添加 `options` 块，CSS 已经配置了 `envVarPrefix` 和 `loadFromEnv`
-
-### 错误: xxx.map is not a function
-
-```
-TypeError: options.routes.map is not a function
-```
-
-**原因**: 组件参数名格式不正确
-**解决**: 查看 `dist/components/context.jsonld` 中的正确参数名，使用简写形式
-
-```json
-// 正确
-{ "@type": "MyComponent", "routes": [...], "fallback": {...} }
-
-// 错误
-{ "@type": "MyComponent", "MyComponent:_options_routes": [...] }
-```
-
-## 配置文件 @context 规范
-
-### 正确写法
-
-```json
-{
-  "@context": [
-    "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^8.0.0/components/context.jsonld",
-    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
-  ]
-}
-```
-
-### 禁止自定义覆盖
-
-不要在 @context 中添加与 dist/components/context.jsonld 冲突的自定义映射。
-
-## 调试命令
-
-```bash
-# 验证环境变量加载
-node_modules/.bin/dotenv -e .env.cluster -- node -e "console.log(process.env.CSS_MY_PARAM)"
-
-# 直接传递 CLI 参数测试
-community-solid-server -c config/xxx.json -m . --myNewParam test-value
-
-# 查看组件参数名
-grep -A 10 '"MyComponent"' dist/components/context.jsonld
-
-# 检查某个类的 jsonld 是否生成
-ls dist/path/to/MyClass.jsonld
-
-# 检查 components.jsonld 是否包含某个类的 import
-grep "MyClass" dist/components/components.jsonld
-```
-
-## 检查清单
-
-添加新变量时必须完成：
-
-- [ ] `config/cli.json` - 添加 YargsParameter
-- [ ] `config/resolver.json` - 添加 KeyExtractor
-- [ ] `.env.xxx` - 添加环境变量（如需要）
-- [ ] 组件配置文件 - 使用 `"@type": "Variable"` 引用
-- [ ] 运行 `yarn build` 重新生成 components
-
-添加新的抽象类/基类时：
-
-- [ ] 使用 `abstract class` 而不是 `interface`
-- [ ] 在 `src/index.ts` 中导出该类
-- [ ] 子类使用 `extends` 而不是 `implements`
-- [ ] 运行 `yarn build` 验证 jsonld 生成