docs: 添加项目文档和 AgentSkills

- 添加架构文档 (ARCHITECTURE.md) - 添加 API 文档 (API.md) - 添加文档索引 (docs/README.md) - 添加部署技能 (skills/city-manual-deploy/SKILL.md) - 添加测试技能 (skills/city-manual-test/SKILL.md) - 添加内容管理技能 (skills/city-manual-content/SKILL.md)
2026-04-12 13:36:21 +00:00
parent 572a06a12c
commit 81632c1b35
6 changed files with 1772 additions and 0 deletions
--- a/city-manual/skills/city-manual-content/SKILL.md
+++ b/city-manual/skills/city-manual-content/SKILL.md
@@ -0,0 +1,282 @@
+# Skill: city-manual-content
+
+## Description
+
+城市手册内容管理技能。用于管理城市内容、文章和特色服务。
+
+## Location
+
+`/root/.openclaw/workspace/city-manual/skills/city-manual-content/`
+
+## Capabilities
+
+- 创建和编辑文章
+- 管理特色服务
+- 内容审核
+- 版块管理
+- 内容导入导出
+
+## Usage
+
+当用户提到以下关键词时激活此技能：
+- "创建文章"
+- "编辑内容"
+- "管理特色服务"
+- "内容审核"
+- "版块管理"
+
+## Database Schema
+
+### 文章表 (articles_article)
+
+```sql
+CREATE TABLE articles_article (
+    id SERIAL PRIMARY KEY,
+    title VARCHAR(200) NOT NULL,
+    content TEXT NOT NULL,
+    region_id INTEGER REFERENCES regions_region(id),
+    category VARCHAR(50),
+    author_id INTEGER REFERENCES users_user(id),
+    moderator_id INTEGER REFERENCES users_user(id),
+    status VARCHAR(20),
+    view_count INTEGER DEFAULT 0,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP
+);
+```
+
+### 特色服务表 (services_featuredservice)
+
+```sql
+CREATE TABLE services_featuredservice (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(200) NOT NULL,
+    description TEXT,
+    region_id INTEGER REFERENCES regions_region(id),
+    category VARCHAR(50),
+    address VARCHAR(500),
+    contact VARCHAR(200),
+    rating DECIMAL(3,2),
+    status VARCHAR(20),
+    author_id INTEGER REFERENCES users_user(id),
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP
+);
+```
+
+## Content Categories
+
+### 文章分类
+
+- `history` - 历史
+- `culture` - 文化
+- `practical` - 实用信息
+- `life` - 生活指南
+
+### 特色服务分类
+
+- `clothing` - 衣
+- `food` - 食
+- `accommodation` - 住
+- `transportation` - 行
+- `entertainment` - 娱乐
+- `tourism` - 旅游
+- `culture` - 文化
+
+## Workflows
+
+### 内容创建流程
+
+```
+1. 用户创建内容
+   ↓
+2. 保存到数据库（status=draft）
+   ↓
+3. 提交审核（status=pending）
+   ↓
+4. 版主初审
+   ↓
+5. AI 审核
+   ↓
+6. 发布（status=published）
+```
+
+### 内容审核规则
+
+**版主审核权限：**
+- 版主只能审核管辖范围内的内容
+- 上级版主可以审核下级版块内容
+- 管理员可以审核所有内容
+
+**AI 审核规则：**
+- 检查敏感词
+- 检查内容质量
+- 检查重复内容
+- 检查违规信息
+
+## Commands
+
+### 创建文章
+
+```bash
+cd /root/.openclaw/workspace/city-manual/backend
+python manage.py shell
+
+>>> from apps.articles.models import Article
+>>> article = Article.objects.create(
+...     title="文章标题",
+...     content="文章内容",
+...     region_id=1,
+...     category="history",
+...     author_id=1,
+...     status="draft"
+... )
+```
+
+### 批量导入内容
+
+```python
+import json
+
+with open('content.json', 'r', encoding='utf-8') as f:
+    data = json.load(f)
+
+for item in data:
+    Article.objects.create(
+        title=item['title'],
+        content=item['content'],
+        region_id=item['region_id'],
+        category=item['category'],
+        status='published'
+    )
+```
+
+### 内容审核
+
+```python
+# 版主审核
+article = Article.objects.get(id=1)
+article.moderator_id = 1
+article.moderator_reviewed_at = timezone.now()
+article.moderator_status = 'approved'
+article.status = 'pending_ai'
+article.save()
+
+# AI 审核
+article.ai_status = 'approved'
+article.ai_reviewed_at = timezone.now()
+article.status = 'published'
+article.save()
+```
+
+### 内容导出
+
+```python
+import json
+from django.core.serializers import serialize
+
+articles = Article.objects.filter(status='published')
+data = serialize('python', articles)
+
+with open('articles_export.json', 'w', encoding='utf-8') as f:
+    json.dump(data, f, ensure_ascii=False, indent=2)
+```
+
+## Content Templates
+
+### 城市信息模板
+
+```markdown
+# {城市名称}
+
+## 基础信息
+- 地理位置：
+- 人口：
+- 气候：
+- 行政区划：
+
+## 历史
+{城市历史介绍}
+
+## 文化
+- 方言：
+- 习俗：
+- 节庆：
+- 特色小吃：
+
+## 实用信息
+- 交通：
+- 教育：
+- 医疗：
+- 商业：
+
+## 生活推荐
+- 餐厅：
+- 景点：
+- 活动：
+- 攻略：
+```
+
+### 特色服务模板
+
+```markdown
+# {服务名称}
+
+## 基本信息
+- 分类：
+- 地址：
+- 联系方式：
+- 营业时间：
+
+## 介绍
+{服务详细介绍}
+
+## 特色
+{服务特色}
+
+## 评价
+{用户评价摘要}
+
+## 图片
+[图片链接]
+```
+
+## Quality Guidelines
+
+### 内容质量标准
+
+1. **准确性**
+   - 信息真实可靠
+   - 数据来源可查
+   - 及时更新
+
+2. **完整性**
+   - 关键信息不缺失
+   - 结构清晰
+   - 分类正确
+
+3. **可读性**
+   - 语言流畅
+   - 格式规范
+   - 排版美观
+
+4. **实用性**
+   - 对用户有价值
+   - 信息可操作
+   - 本地化特色
+
+### 审核检查清单
+
+- [ ] 标题准确反映内容
+- [ ] 内容无错别字
+- [ ] 分类正确
+- [ ] 图片清晰
+- [ ] 联系方式有效
+- [ ] 无违规内容
+- [ ] 无敏感信息
+- [ ] 格式规范
+
+## References
+
+- [API.md](../../docs/API.md)
+- [ARCHITECTURE.md](../../docs/ARCHITECTURE.md)
--- a/city-manual/skills/city-manual-deploy/SKILL.md
+++ b/city-manual/skills/city-manual-deploy/SKILL.md
@@ -0,0 +1,156 @@
+# Skill: city-manual-deploy
+
+## Description
+
+城市手册项目部署技能。用于自动化部署城市手册项目到生产环境。
+
+## Location
+
+`/root/.openclaw/workspace/city-manual/skills/city-manual-deploy/`
+
+## Capabilities
+
+- 检查部署环境
+- 配置 Nginx 反向代理
+- 启动 Gunicorn 服务
+- 数据库迁移
+- 静态文件收集
+- 服务健康检查
+
+## Usage
+
+当用户提到以下关键词时激活此技能：
+- "部署城市手册"
+- "deploy city manual"
+- "上线项目"
+- "生产环境配置"
+
+## Scripts
+
+### deploy.sh
+
+```bash
+#!/bin/bash
+# 城市手册部署脚本
+
+set -e
+
+PROJECT_DIR="/root/.openclaw/workspace/city-manual"
+VENV_DIR="$PROJECT_DIR/backend/venv"
+GUNICORN_SOCKET="$PROJECT_DIR/gunicorn.sock"
+GUNICORN_LOG="$PROJECT_DIR/gunicorn.log"
+
+echo "=== 城市手册部署开始 ==="
+
+# 1. 激活虚拟环境
+source $VENV_DIR/bin/activate
+
+# 2. 数据库迁移
+cd $PROJECT_DIR/backend
+python manage.py migrate
+
+# 3. 收集静态文件
+python manage.py collectstatic --noinput
+
+# 4. 重启 Gunicorn
+pkill -f gunicorn || true
+sleep 2
+cd $PROJECT_DIR
+./gunicorn_start.sh
+
+# 5. 检查服务状态
+sleep 3
+if pgrep -f gunicorn > /dev/null; then
+    echo "✅ Gunicorn 启动成功"
+else
+    echo "❌ Gunicorn 启动失败"
+    exit 1
+fi
+
+# 6. Nginx 配置检查
+nginx -t
+if [ $? -eq 0 ]; then
+    systemctl reload nginx
+    echo "✅ Nginx 重载成功"
+else
+    echo "❌ Nginx 配置错误"
+    exit 1
+fi
+
+echo "=== 部署完成 ==="
+```
+
+## Configuration
+
+### 环境变量
+
+```bash
+# .env 文件
+DJANGO_SETTINGS_MODULE=config.settings.production
+DJANGO_SECRET_KEY=your-secret-key
+DATABASE_URL=postgres://user:pass@localhost:5432/cssc
+ALLOWED_HOSTS=cssc.datalibstar.com,127.0.0.1
+DEBUG=False
+```
+
+### Nginx 配置
+
+```nginx
+server {
+    listen 80;
+    server_name cssc.datalibstar.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    location /static/ {
+        alias /root/.openclaw/workspace/city-manual/backend/static/;
+    }
+
+    location /media/ {
+        alias /root/.openclaw/workspace/city-manual/backend/media/;
+    }
+}
+```
+
+## Health Check
+
+```bash
+# 检查 Gunicorn
+curl http://127.0.0.1:8000/admin/
+
+# 检查数据库
+psql -h localhost -U coder -d cssc -c "SELECT 1"
+
+# 检查 Nginx
+curl http://cssc.datalibstar.com/
+```
+
+## Troubleshooting
+
+### Gunicorn 启动失败
+
+1. 检查端口占用：`lsof -i :8000`
+2. 查看日志：`tail -f gunicorn.log`
+3. 检查虚拟环境：`source backend/venv/bin/activate`
+
+### 数据库连接失败
+
+1. 检查 PostgreSQL 服务：`systemctl status postgresql`
+2. 验证连接：`psql -h localhost -U coder -d cssc`
+3. 检查 .env 配置
+
+### 静态文件 404
+
+1. 重新收集：`python manage.py collectstatic --noinput`
+2. 检查 Nginx 配置路径
+3. 重载 Nginx：`systemctl reload nginx`
+
+## References
+
+- [DEPLOYMENT.md](../../DEPLOYMENT.md)
+- [scripts/deploy.sh](../../deploy.sh)
+- [scripts/gunicorn_start.sh](../../gunicorn_start.sh)
--- a/city-manual/skills/city-manual-test/SKILL.md
+++ b/city-manual/skills/city-manual-test/SKILL.md
@@ -0,0 +1,229 @@
+# Skill: city-manual-test
+
+## Description
+
+城市手册项目测试技能。用于运行项目测试和 API 验证。
+
+## Location
+
+`/root/.openclaw/workspace/city-manual/skills/city-manual-test/`
+
+## Capabilities
+
+- 运行 Django 测试
+- API 端点测试
+- 数据库连接测试
+- 前端构建测试
+- 性能测试
+
+## Usage
+
+当用户提到以下关键词时激活此技能：
+- "测试城市手册"
+- "run tests"
+- "API 测试"
+- "验证功能"
+
+## Scripts
+
+### test_api.py
+
+```python
+#!/usr/bin/env python3
+"""
+城市手册 API 测试脚本
+"""
+
+import requests
+import json
+
+BASE_URL = "http://127.0.0.1:8000/api"
+
+def test_auth():
+    """测试认证 API"""
+    print("=== 测试认证 API ===")
+    
+    # 登录
+    response = requests.post(f"{BASE_URL}/auth/token/", json={
+        "username": "demo",
+        "password": "demo123"
+    })
+    
+    if response.status_code == 200:
+        token = response.json()["access"]
+        print("✅ 登录成功")
+        return token
+    else:
+        print(f"❌ 登录失败：{response.status_code}")
+        return None
+
+def test_users(token):
+    """测试用户 API"""
+    print("\n=== 测试用户 API ===")
+    
+    headers = {"Authorization": f"Bearer {token}"}
+    
+    # 获取当前用户
+    response = requests.get(f"{BASE_URL}/users/me/", headers=headers)
+    if response.status_code == 200:
+        print(f"✅ 获取用户信息成功：{response.json()['username']}")
+    else:
+        print(f"❌ 获取用户信息失败：{response.status_code}")
+
+def test_regions(token):
+    """测试版块 API"""
+    print("\n=== 测试版块 API ===")
+    
+    # 获取版块列表
+    response = requests.get(f"{BASE_URL}/regions/")
+    if response.status_code == 200:
+        data = response.json()
+        print(f"✅ 获取版块列表成功：共 {data['count']} 个版块")
+        if data['results']:
+            print(f"   第一个版块：{data['results'][0]['name']}")
+    else:
+        print(f"❌ 获取版块列表失败：{response.status_code}")
+
+def test_articles(token):
+    """测试文章 API"""
+    print("\n=== 测试文章 API ===")
+    
+    # 获取文章列表
+    response = requests.get(f"{BASE_URL}/articles/")
+    if response.status_code == 200:
+        data = response.json()
+        print(f"✅ 获取文章列表成功：共 {data['count']} 篇文章")
+    else:
+        print(f"❌ 获取文章列表失败：{response.status_code}")
+
+def test_services(token):
+    """测试特色服务 API"""
+    print("\n=== 测试特色服务 API ===")
+    
+    # 获取特色服务列表
+    response = requests.get(f"{BASE_URL}/services/")
+    if response.status_code == 200:
+        data = response.json()
+        print(f"✅ 获取特色服务列表成功：共 {data['count']} 个服务")
+    else:
+        print(f"❌ 获取特色服务列表失败：{response.status_code}")
+
+def test_database():
+    """测试数据库连接"""
+    print("\n=== 测试数据库连接 ===")
+    
+    import psycopg2
+    
+    try:
+        conn = psycopg2.connect(
+            host="10.2.0.100",
+            port=5432,
+            database="cssc",
+            user="coder",
+            password="825670wl"
+        )
+        cur = conn.cursor()
+        cur.execute("SELECT 1")
+        cur.close()
+        conn.close()
+        print("✅ 数据库连接成功")
+        return True
+    except Exception as e:
+        print(f"❌ 数据库连接失败：{e}")
+        return False
+
+def main():
+    """主函数"""
+    print("城市手册 API 测试开始\n")
+    
+    # 测试数据库
+    test_database()
+    
+    # 测试认证
+    token = test_auth()
+    if not token:
+        print("\n❌ 认证失败，停止测试")
+        return
+    
+    # 测试各 API
+    test_users(token)
+    test_regions(token)
+    test_articles(token)
+    test_services(token)
+    
+    print("\n=== 测试完成 ===")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Commands
+
+### 运行 Django 测试
+
+```bash
+cd /root/.openclaw/workspace/city-manual/backend
+python manage.py test
+```
+
+### 运行 API 测试
+
+```bash
+cd /root/.openclaw/workspace/city-manual
+python test_api.py
+```
+
+### 运行前端测试
+
+```bash
+cd /root/.openclaw/workspace/city-manual/frontend
+npm test
+```
+
+### 数据库连接测试
+
+```bash
+psql -h 10.2.0.100 -U coder -d cssc -c "SELECT 1"
+```
+
+## Health Check
+
+```bash
+# 检查所有服务
+curl http://127.0.0.1:8000/admin/
+curl http://127.0.0.1/
+psql -h 10.2.0.100 -U coder -d cssc -c "SELECT 1"
+```
+
+## Test Cases
+
+### 用户认证测试
+1. 正常登录
+2. 错误密码
+3. 令牌刷新
+4. 令牌过期
+
+### 版块管理测试
+1. 获取版块列表
+2. 获取版块详情
+3. 创建版块（管理员）
+4. 版块层级查询
+
+### 内容管理测试
+1. 获取文章列表
+2. 获取文章详情
+3. 创建文章
+4. 更新文章
+5. 删除文章
+6. 文章审核流程
+
+### 互动功能测试
+1. 发表评论
+2. 评分
+3. 点赞
+4. 收藏
+
+## References
+
+- [TESTING.md](../../TESTING.md)
+- [test_api.py](../../test_api.py)