12 KiB
12 KiB
PromptX 统一资源协议架构设计文档
目录
- 1. 概述
- 2. 核心设计理念
- 3. DPML协议体系设计
- 4. 多层级资源发现架构
- 5. 统一注册表设计
- 6. 协议解析执行流程
- 7. 资源生命周期管理
- 8. 扩展性设计
- 9. 错误处理与容错机制
- 10. 性能优化策略
1. 概述
PromptX采用统一资源协议架构，支持多层级资源发现与动态注册机制。该架构通过DPML（Domain-Specific Prompt Markup Language）协议实现资源的统一标识、发现、注册和解析。
2. 核心设计理念
2.1 分层架构原则
- 协议层: 统一的@协议标识体系
- 发现层: 多源资源发现机制
- 注册层: 统一的资源注册表
- 解析层: 协议到文件系统的映射
2.2 职责分离原则
- Registry: 专注资源映射存储和查询
- Discovery: 专注特定来源的资源发现
- Protocol: 专注协议解析和路径转换
- Manager: 专注流程编排和生命周期管理
3. DPML协议体系设计
3.1 协议语法结构
graph LR
A["@[semantic][protocol]://[resource_path]"] --> B[加载语义]
A --> C[协议类型]
A --> D[资源路径]
B --> B1["@ - 默认加载"]
B --> B2["@! - 热加载"]
B --> B3["@? - 懒加载"]
C --> C1["package - NPM包资源"]
C --> C2["project - 项目本地资源"]
C --> C3["user - 用户全局资源"]
C --> C4["internet - 网络资源"]
C --> C5["file - 文件系统"]
C --> C6["thought - 思维模式"]
C --> C7["execution - 执行模式"]
C --> C8["role - AI角色"]
C --> C9["knowledge - 知识库"]
3.2 协议层级设计
classDiagram
class ProtocolSystem {
<<interface>>
+parseReference(ref: string)
+resolve(ref: string)
}
class BasicProtocol {
+package
+project
+user
+internet
+file
}
class LogicalProtocol {
+thought
+execution
+role
+knowledge
+memory
}
ProtocolSystem <|-- BasicProtocol
ProtocolSystem <|-- LogicalProtocol
BasicProtocol : +直接文件映射
BasicProtocol : +路径解析
LogicalProtocol : +注册表查询
LogicalProtocol : +逻辑资源映射
4. 多层级资源发现架构
4.1 发现层级结构
graph TD
A[资源发现生态系统] --> B[包级发现 PackageDiscovery]
A --> C[项目级发现 ProjectDiscovery]
A --> D[用户级发现 UserDiscovery]
A --> E[网络级发现 InternetDiscovery]
B --> B1[NPM包内置资源]
B --> B2[src/resource.registry.json]
B --> B3[prompt/ 目录结构]
C --> C1[项目本地资源]
C --> C2[.promptx/resource/]
C --> C3[动态角色发现]
D --> D1[用户全局资源]
D --> D2[~/promptx/resource/]
D --> D3[用户自定义角色]
E --> E1[远程资源库]
E --> E2[Git仓库资源]
E --> E3[在线角色市场]
4.2 发现优先级机制
sequenceDiagram
participant RM as ResourceManager
participant PD as PackageDiscovery
participant PRD as ProjectDiscovery
participant UD as UserDiscovery
participant ID as InternetDiscovery
participant RR as ResourceRegistry
RM->>+PD: discover() [优先级: 1]
PD->>-RM: 系统内置资源列表
RM->>+PRD: discover() [优先级: 2]
PRD->>-RM: 项目本地资源列表
RM->>+UD: discover() [优先级: 3]
UD->>-RM: 用户全局资源列表
RM->>+ID: discover() [优先级: 4]
ID->>-RM: 网络资源列表
Note over RM: 按优先级合并，后发现的覆盖先发现的
RM->>RR: 批量注册所有发现的资源
5. 统一注册表设计
5.1 注册表核心结构
classDiagram
class ResourceRegistry {
-Map~string,string~ index
-Map~string,ResourceMeta~ metadata
+register(id: string, reference: string)
+resolve(id: string): string
+merge(other: ResourceRegistry)
+has(id: string): boolean
+list(protocol?: string): string[]
}
class ResourceMeta {
+source: DiscoverySource
+priority: number
+timestamp: Date
+metadata: object
}
class DiscoverySource {
<<enumeration>>
PACKAGE
PROJECT
USER
INTERNET
}
ResourceRegistry --> ResourceMeta
ResourceMeta --> DiscoverySource
5.2 注册表合并策略
flowchart TD
A[多源资源发现] --> B{资源ID冲突检测}
B -->|无冲突| C[直接注册]
B -->|有冲突| D[优先级比较]
D --> E{优先级策略}
E -->|用户 > 项目 > 包 > 网络| F[高优先级覆盖]
E -->|同优先级| G[时间戳比较]
F --> H[更新注册表]
G --> H
C --> H
H --> I[生成统一资源索引]
6. 协议解析执行流程
6.1 完整解析序列
sequenceDiagram
participant U as User
participant RM as ResourceManager
participant RR as ResourceRegistry
participant PR as ProtocolResolver
participant PP as PackageProtocol
participant PRP as ProjectProtocol
participant FS as FileSystem
U->>RM: loadResource("role:xiaohongshu-copywriter")
Note over RM: 1. 资源ID解析阶段
RM->>RR: resolve("role:xiaohongshu-copywriter")
RR->>RM: "@project://.promptx/resource/domain/xiaohongshu-copywriter/xiaohongshu-copywriter.role.md"
Note over RM: 2. 协议解析阶段
RM->>PR: parseReference("@project://...")
PR->>RM: {semantic: "@", protocol: "project", path: "..."}
Note over RM: 3. 路径解析阶段
RM->>PRP: resolve(".promptx/resource/domain/...")
PRP->>FS: 定位项目根目录
FS->>PRP: "/user/project/"
PRP->>RM: "/user/project/.promptx/resource/domain/xiaohongshu-copywriter/xiaohongshu-copywriter.role.md"
Note over RM: 4. 文件加载阶段
RM->>FS: readFile(absolutePath)
FS->>RM: 文件内容
RM->>U: {success: true, content: "...", path: "..."}
6.2 嵌套引用解析
sequenceDiagram
participant SR as SemanticRenderer
participant RM as ResourceManager
participant RR as ResourceRegistry
Note over SR: 发现嵌套引用 @!thought://remember
SR->>RM: resolve("@!thought://remember")
Note over RM: 1. 解析加载语义 @!
RM->>RM: 识别热加载模式
Note over RM: 2. 解析逻辑协议 thought
RM->>RR: resolve("thought:remember")
RR->>RM: "@package://prompt/core/thought/remember.thought.md"
Note over RM: 3. 解析基础协议 @package
RM->>RM: 委托给PackageProtocol
Note over RM: 4. 返回解析结果
RM->>SR: 思维模式内容
Note over SR: 5. 渲染到最终输出
7. 资源生命周期管理
7.1 初始化流程
stateDiagram-v2
[*] --> Uninitialized
Uninitialized --> Discovering: initialize()
Discovering --> PackageDiscovery: 发现包资源
PackageDiscovery --> ProjectDiscovery: 发现项目资源
ProjectDiscovery --> UserDiscovery: 发现用户资源
UserDiscovery --> InternetDiscovery: 发现网络资源
InternetDiscovery --> Registering: 开始注册
Registering --> Merging: 合并资源
Merging --> Indexing: 建立索引
Indexing --> Ready: 完成初始化
Ready --> Resolving: resolve()
Resolving --> Ready: 返回结果
Ready --> Refreshing: refresh()
Refreshing --> Discovering: 重新发现
Ready --> [*]: destroy()
7.2 缓存与更新策略
flowchart TD
A[资源访问请求] --> B{缓存检查}
B -->|命中| C[检查加载语义]
B -->|未命中| D[触发发现流程]
C --> E{加载语义判断}
E -->|at 默认| F[返回缓存内容]
E -->|a! 热加载| G[强制重新加载]
E -->|a? 懒加载| H[延迟加载策略]
D --> I[执行Discovery]
G --> I
H --> I
I --> J[更新注册表]
J --> K[更新缓存]
K --> L[返回最新内容]
F --> M[返回给用户]
L --> M
8. 扩展性设计
8.1 新协议扩展机制
classDiagram
class ProtocolExtension {
<<interface>>
+name: string
+resolve(path: string): string
+validate(path: string): boolean
}
class DatabaseProtocol {
+name: "database"
+resolve(path): string
+validate(path): boolean
}
class GitProtocol {
+name: "git"
+resolve(path): string
+validate(path): boolean
}
class S3Protocol {
+name: "s3"
+resolve(path): string
+validate(path): boolean
}
ProtocolExtension <|-- DatabaseProtocol
ProtocolExtension <|-- GitProtocol
ProtocolExtension <|-- S3Protocol
8.2 新发现源扩展
classDiagram
class DiscoveryExtension {
<<interface>>
+source: DiscoverySource
+priority: number
+discover(): Promise~Resource[]~
}
class GitDiscovery {
+source: GIT
+priority: 5
+discover(): Promise~Resource[]~
}
class DatabaseDiscovery {
+source: DATABASE
+priority: 6
+discover(): Promise~Resource[]~
}
class MarketplaceDiscovery {
+source: MARKETPLACE
+priority: 7
+discover(): Promise~Resource[]~
}
DiscoveryExtension <|-- GitDiscovery
DiscoveryExtension <|-- DatabaseDiscovery
DiscoveryExtension <|-- MarketplaceDiscovery
9. 错误处理与容错机制
9.1 分层错误处理
flowchart TD
A[用户请求] --> B[ResourceManager]
B --> C{Discovery阶段}
C -->|发现失败| D[降级到缓存]
C -->|部分失败| E[记录错误，继续处理]
C -->|完全失败| F[返回空注册表]
B --> G{Registry阶段}
G -->|注册失败| H[跳过失败项]
G -->|冲突解决失败| I[使用默认策略]
B --> J{Protocol阶段}
J -->|协议不支持| K[尝试文件协议]
J -->|路径解析失败| L[返回详细错误]
B --> M{FileSystem阶段}
M -->|文件不存在| N[返回空内容标记]
M -->|权限错误| O[尝试替代路径]
D --> P[用户获得部分功能]
E --> P
H --> P
I --> P
K --> P
F --> Q[用户获得错误信息]
L --> Q
N --> Q
O --> Q
10. 性能优化策略
10.1 并行发现优化
| 模式 | PackageDiscovery | ProjectDiscovery | UserDiscovery | InternetDiscovery | 合并注册 |
|---|---|---|---|---|---|
| 串行模式 | 0-200ms | 200-400ms | 400-600ms | 600-1000ms | - |
| 并行模式 | 0-200ms | 0-250ms | 0-180ms | 0-800ms | 800-850ms |
10.2 缓存分层策略
graph TD
A[L1: 内存缓存] --> B[L2: 文件缓存]
B --> C[L3: 远程缓存]
A --> A1[热点资源]
A --> A2[最近访问]
B --> B1[用户资源]
B --> B2[项目资源]
C --> C1[网络资源]
C --> C2[共享资源]
D[缓存失效策略] --> D1[TTL过期]
D --> D2[版本变更]
D --> D3[手动刷新]
总结
这个架构设计确保了PromptX资源系统的高度可扩展性、跨平台兼容性和优秀的性能表现，同时保持了清晰的职责分离和统一的访问接口。
核心优势
- 统一协议体系: 通过DPML协议实现资源的标准化访问
- 多层级发现: 支持包、项目、用户、网络多个层级的资源发现
- 智能注册表: 自动处理资源冲突和优先级管理
- 高性能设计: 并行发现和多层缓存策略
- 强容错性: 完善的错误处理和降级机制
- 易扩展性: 支持新协议和新发现源的动态扩展