first commit

content-ops/content-ops-agent/references/prompt-service-architecture.md

@@ -0,0 +1,132 @@
+# Prompt 服务架构参考
+
+> 基于 2026-05-05 代码分析，源码位于 `/home/ubuntu/projects/ephron.ren/prompt/`
+
+## 项目结构
+
+```
+prompt/
+├── src/
+│   ├── main.py              # FastAPI 入口，挂载路由和中间件
+│   ├── config.py             # 环境变量配置（AUTH_SECRET_KEY, DATABASE_PATH）
+│   ├── routes/
+│   │   ├── pages.py          # 页面路由（Jinja2 模板渲染，HTMLResponse）
+│   │   ├── api.py            # 公开 API（/api/prompts, /api/prompts/{key}）
+│   │   ├── admin.py          # 管理后台路由（/admin/*，需 Cookie 认证）
+│   │   └── service_api.py    # 服务端 API（/api/service/*，需 Bearer Token）
+│   └── services/
+│       ├── prompts.py        # 提示词 CRUD + 版本管理
+│       ├── db.py             # SQLite 连接 + 建表
+│       └── auth.py           # 认证辅助
+├── templates/
+│   ├── base.html             # 基础模板（暗色主题、Inter + JetBrains Mono）
+│   ├── public/
+│   │   ├── index.html        # 列表页（搜索、分类筛选、标签过滤、卡片网格）
+│   │   └── detail.html       # 详情页（内容展示、复制按钮、示例区域）
+│   └── admin/
+│       ├── index.html        # 管理列表
+│       ├── edit.html         # 编辑表单
+│       ├── new.html          # 新建表单
+│       └── versions.html     # 版本历史
+├── static/
+│   ├── css/ds/               # 设计系统 CSS（tokens, components, layout, motion）
+│   └── js/ds/ui.js           # UI 交互（modal、toast、通用组件）
+└── tests/
+```
+
+## 数据模型
+
+### prompts 表
+```sql
+CREATE TABLE prompts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    key TEXT NOT NULL UNIQUE,              -- URL 标识，如 "deep-research-prompt"
+    title TEXT NOT NULL,
+    description TEXT,
+    category TEXT NOT NULL DEFAULT '未分类',
+    tags TEXT,                             -- 逗号分隔
+    is_template INTEGER NOT NULL DEFAULT 0,
+    variables TEXT,                        -- 模板变量（逗号分隔）
+    example_input TEXT,
+    example_output TEXT,
+    recommended_model TEXT NOT NULL DEFAULT '通用',
+    is_active INTEGER NOT NULL DEFAULT 1,
+    draft INTEGER NOT NULL DEFAULT 0,
+    created_by TEXT,
+    updated_by TEXT,
+    ownership_type TEXT NOT NULL DEFAULT 'human',  -- 'human' | 'service'
+    handoff_to_human INTEGER NOT NULL DEFAULT 0,
+    current_version_id INTEGER,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+```
+
+### prompt_versions 表
+```sql
+CREATE TABLE prompt_versions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    prompt_key TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    content TEXT NOT NULL,
+    created_by TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    FOREIGN KEY (prompt_key) REFERENCES prompts(key) ON DELETE CASCADE,
+    UNIQUE(prompt_key, version)
+);
+```
+
+## API 端点
+
+### 公开 API（无需认证）
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/prompts` | 列表（支持 search, tag, category, limit, offset） |
+| GET | `/api/prompts/{key}` | 详情（支持 version 查询参数） |
+
+### 服务端 API（Bearer Token）
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/service/prompts` | 列表 |
+| GET | `/api/service/prompts/{key}` | 详情 |
+| POST | `/api/service/prompts` | 创建草稿 |
+| PATCH | `/api/service/prompts/{key}` | 更新草稿 |
+| DELETE | `/api/service/prompts/{key}` | 删除草稿 |
+
+### 页面路由（返回 HTML）
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/` 或 `/prompts` | 列表页（支持 q, category, tag 查询参数） |
+| GET | `/prompts/{key}` | 详情页 |
+| GET | `/admin/*` | 管理后台（需登录 + 权限） |
+
+## 设计系统
+
+- **主题**: 暗色（bg-primary: #09090b, accent: #3b82f6）
+- **字体**: Inter（正文）+ JetBrains Mono（代码）
+- **CSS 变量**: 定义在 `:root` 中，所有组件引用变量
+- **卡片组件**: `.prompt-card` 使用 `bg-secondary` + border + hover 效果
+- **标签**: `.tag` 类，带 `tag-bg` 背景
+- **复制按钮**: `.copy-btn`，绝对定位在内容块右上角
+- **CSP**: `connect-src 'self'`，`script-src 'self' 'unsafe-inline'`，`cdn.jsdelivr.net` 已白名单
+
+## 现有功能特性
+
+1. **版本管理**: 每次编辑创建新版本，支持版本切换
+2. **模板变量**: `is_template=true` 时，`variables` 字段定义可替换变量
+3. **草稿系统**: `draft` 字段 + `ownership_type` 区分人类/服务创建
+4. **搜索过滤**: 支持关键词搜索、分类筛选、标签过滤
+5. **复制功能**: 前端 `navigator.clipboard.writeText()` 实现
+
+## 待实现功能（PRD 已写）
+
+- **调用测试**: 详情页测试 Tab，填变量 → 调 LLM → 流式输出
+- **集合**: `collections` + `collection_items` 表，组织相关提示词
+
+## 开发注意事项
+
+- 路由区分：`response_class=HTMLResponse` → 页面路由，返回 dict/Pydantic → API
+- Key 自动生成：创建 prompt 时 key 可能被截取/简化，以响应返回值为准
+- Key 不可变：PATCH 不能修改 key 字段
+- 服务端只能编辑自己创建的草稿（`created_by == actor_id` + `ownership_type == "service"` + `draft == true`）
+- 所有时间使用 SQLite `datetime('now')` 存储