# Neural Sync - 用户使用手册

> **面向 AI 技术团队的智能项目管理平台**
> 版本：v1.0
> 更新日期：2024年2月

---

## 目录

1. [系统简介](#1-系统简介)
2. [快速开始](#2-快速开始)
3. [核心功能使用](#3-核心功能使用)
4. [日常使用流程](#4-日常使用流程)
5. [系统配置](#5-系统配置)
6. [常见问题](#6-常见问题)

---

## 1. 系统简介

### 1.1 什么是 Neural Sync？

**Neural Sync** 是一个专为 AI/ML 技术团队设计的项目管理平台，与传统项目管理工具不同，它专注于管理"活体上下文"——外部信号、AI 实验和认知知识节点。

### 1.2 核心价值

| 传统 PM 工具 | Neural Sync |
|--------------|-------------|
| 管理静态任务 | 管理动态知识 |
| 人工优先级判断 | AI 自动战略研判 |
| 离散的工具链 | 统一的 AI 工作流 |

### 1.3 三大核心功能

```
┌─────────────────────────────────────────────────────────────┐
│  信号监控              实验管理              知识管理          │
│                      │                          │          │
│  外部技术情报           AI 实验追踪            认知节点         │
│  - HackerNews        - 假设验证               - 版本控制         │
│  - 行业动态           - 评分系统               - 向量检索         │
│  - 竞品更新           - 关联任务               - AI 洞察提取       │
└─────────────────────────────────────────────────────────────┘
```

---

## 2. 快速开始

### 2.1 安装部署

#### 前置要求

- Python 3.10+
- Node.js 18+
- PostgreSQL 15+ (推荐) 或 SQLite (开发环境)

#### 步骤一：选择 LLM 提供商

**选项 A：使用云端 API（推荐，电脑配置低）**

编辑 `backend/.env` 文件：

```bash
# 使用 DeepSeek（便宜，¥1/百万 tokens）
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=你的API密钥

# 或使用 OpenAI
# LLM_PROVIDER=openai
# OPENAI_API_KEY=你的API密钥

# 或使用阿里云通义千问
# LLM_PROVIDER=qwen
# QWEN_API_KEY=你的API密钥
```

获取 API 密钥：
- DeepSeek: https://platform.deepseek.com/api_keys
- OpenAI: https://platform.openai.com/api-keys
- 阿里云: https://dashscope.console.aliyun.com/apiKey

**选项 B：使用本地 Ollama（免费，但占用 CPU/内存）**

```bash
# 安装 Ollama (如果尚未安装)
# macOS: brew install ollama
# Linux: curl -fsSL https://ollama.com/install.sh | sh

# 启动 Ollama 服务
ollama serve

# 拉取所需模型 (新终端窗口)
ollama pull llama3:8b
ollama pull nomic-embed-text
```

编辑 `backend/.env` 文件：

```bash
LLM_PROVIDER=ollama
OLLAMA_HOST=http://127.0.0.1:11434
```

#### 步骤二：启动后端服务

```bash
cd backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量 (可选，使用默认配置)
cp .env.example .env

# 编辑 .env 设置你的 LLM 提供商和 API 密钥
vim .env

# 运行数据库迁移
alembic upgrade head

# 启动后端
uvicorn app.main:app --reload --port 8000
```

#### 步骤三：启动前端界面

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev -- --host
```

#### 步骤四：访问系统

打开浏览器访问：`http://localhost:5173`

---

## 3. 核心功能使用

### 3.1 信号监控

**用途**：捕获和分析外部技术信号，评估其对团队的战略影响。

#### 如何使用

1. **自动获取信号**

访问前端页面，系统会自动从 HackerNews 获取最新技术动态。

```bash
# 手动触发信号获取
curl -X POST http://localhost:8000/signals/fetch
```

2. **手动添加信号**

```bash
curl -X POST http://localhost:8000/signals/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "source": "手动输入",
    "content": "OpenAI 发布了新的视频生成模型 Sora",
    "impact_score": 0.9
  }'
```

3. **查看战略分析**

点击左侧信号列表中的任意信号，右侧将显示：
- AI 战略研判结果
- 置信度评分
- 多模型投票情况
- 相关知识引用
- 竞争力雷达图

#### 优先级说明

系统会自动根据影响分数分配优先级：

| 优先级 | 图标 | 影响分数 | 处理方式 |
|--------|------|----------|----------|
| 🔴 紧急 | critical | ≥ 0.9 | 立即处理 + 通知 |
| 🟠 高优 | high | 0.7-0.9 | 异步处理 + 通知 |
| 🟡 中等 | medium | 0.5-0.7 | 异步处理 |
| 🟢 低优 | low | < 0.5 | 仅记录 |

### 3.2 实验管理

**用途**：管理 AI 实验的科学方法，通过假设-验证循环驱动技术决策。

#### 如何使用

1. **创建新实验**

点击"新建实验"按钮，填写：
- **标题**：实验名称
- **假设**：例如"切换到 DeepSeek-V3 后，准确率预计提升 5%"
- **目标指标**：accuracy、latency、cost 等
- **关联知识**：选择相关的认知节点

2. **追踪进度**

- 实验状态：草稿 → 进行中 → 成功/失败
- 当前评分：基于目标指标的实时评分
- 状态自动更新：根据关联知识节点的变化自动标记"已过时"

3. **查看实验列表**

访问前端实验看板，查看所有进行中和已完成的实验。

### 3.3 知识管理

**用途**：管理团队的技术认知，作为 AI 战略研判的知识库。

#### 如何使用

1. **添加认知节点**

点击"新增认知"，输入 Markdown 格式的知识内容：

```markdown
# FLUX 图像生成模型

## 技术规格
- 推理速度: ~8s/张
- 分辨率: 1024x1024
- 风格: FLUX.1-dev

## 核心优势
- 无需复杂的 prompt 工程
- 遵循能力强
- 开源免费
```

2. **AI 自动分析**

系统会自动：
- 生成向量嵌入（用于语义检索）
- 提取核心洞察（护城河、技术参数）
- 计算技术栈关键词

3. **语义检索**

当新信号进入时，系统会自动找到最相关的知识节点辅助判断。

---

## 4. 日常使用流程

### 4.1 每日信号审查流程

```
1. 早上打开系统 → 查看信号监控面板
2. 点击高优先级信号 → 查看战略分析
3. 对于战略级信号：
   - 查看 AI 建议的任务列表
   - 点击"授权下发"同步到 Plane
   - 团队接收 Lark 通知
4. 提交反馈 → 帮助 AI 学习
```

### 4.2 技术决策流程

```
1. 外部技术变化（如新模型发布）
   ↓
2. 创建实验验证假设
   ↓
3. 关联相关知识节点
   ↓
4. 运行实验，收集评分数据
   ↓
5. 根据结果决定是否跟进
```

### 4.3 知识沉淀流程

```
1. 技术调研/架构决策
   ↓
2. 添加到认知节点
   ↓
3. AI 自动提取洞察
   ↓
4. 成为后续研判的知识基础
```

---

## 5. 系统配置

### 5.1 环境变量配置

编辑 `backend/.env` 文件：

```bash
# 数据库配置
DATABASE_URL=sqlite+aiosqlite:///./neural_sync.db

# Ollama AI 服务
OLLAMA_HOST=http://127.0.0.1:11434

# 业务上下文（AI 战略研判的基础）
BUSINESS_CONTEXT=你的产品/团队描述

# 多模型投票配置
VOTING_MODELS=llama3,qwen2.5,mistral
VOTING_THRESHOLD=0.8

# Plane PM 工具集成（可选）
PLANE_API_URL=
PLANE_API_KEY=
PLANE_WORKSPACE_SLUG=
PLANE_PROJECT_ID=

# Lark 飞书集成（可选）
LARK_APP_ID=
LARK_APP_SECRET=
LARK_VERIFICATION_TOKEN=
```

### 5.2 业务上下文配置

**BUSINESS_CONTEXT** 是 AI 战略研判的核心基础，应根据实际情况配置：

```bash
# 示例：短视频生成平台
BUSINESS_CONTEXT="我们是一个 AI 短视频自动生成平台。核心功能：输入主题→AI 生成脚本→AI 生成图片→语音合成→视频合成。技术栈：Python, Vue, FastAPI, ComfyUI。"

# 示例：AI 漫剧平台
BUSINESS_CONTEXT="我们是一个 AI 漫剧创作平台。核心功能：漫画转视频、角色一致性、多语言翻译。技术栈：Stable Diffusion, RAG, Llama 3。"
```

### 5.3 LLM 提供商对比

| 提供商 | 优点 | 缺点 | 成本 | 适用场景 |
|--------|------|------|------|----------|
| **DeepSeek** | 便宜、效果好、国内稳定 | 需要联网 | ¥1/百万 tokens | **推荐首选** |
| **OpenAI** | GPT-4 效果最好 | 价格较贵 | 约 ¥15/百万 tokens | 高质量分析需求 |
| **Qwen** | 阿里云、国内稳定 | 效果略逊 GPT-4 | ¥0.5/百万 tokens | 预算有限 |
| **Ollama** | 完全免费、数据隐私 | 占用 CPU/内存、电脑发热 | 免费 | 电脑配置高 |

**建议**：
- 电脑配置低 → 使用 **DeepSeek**（最便宜）
- 追求效果 → 使用 **OpenAI**
- 数据敏感 → 使用 **Ollama**（本地运行）

### 5.4 Ollama 模型管理（仅本地模式）

查看已安装模型：

```bash
ollama list
```

下载新模型：

```bash
ollama pull qwen2.5    # 通用模型
ollama pull mistral     # 代码分析模型
ollama pull deepseek-coder  # 编程专用模型
```

### 5.5 其他网络访问（跨 WiFi / 手机流量）

让不在同一 WiFi 的设备（如手机流量、其他地方的电脑）也能访问：

若设备在同一局域网，`./start.sh` 启动后直接使用「局域网」地址，例如 `http://192.168.x.x:5174`（前端）、`http://192.168.x.x:8000`（后端）。

---

## 6. 常见问题

### 6.1 后端启动失败

**问题**：`ModuleNotFoundError: No module named 'xxx'`

**解决**：
```bash
cd backend
source venv/bin/activate
pip install -r requirements.txt
```

### 6.2 数据库连接失败

**问题**：`could not connect to server`

**解决方案 A - 使用 SQLite（开发环境）**：

编辑 `backend/.env`：
```bash
DATABASE_URL=sqlite+aiosqlite:///./neural_sync.db
```

**解决方案 B - PostgreSQL 配置**：

```bash
# 启动 PostgreSQL
brew services start postgresql  # macOS
sudo systemctl start postgresql  # Linux

# 创建数据库
createdb neural_sync
psql neural_sync -c "CREATE EXTENSION vector;"
```

### 6.3 Ollama 连接失败

**问题**：AI 战略分析没有返回结果

**检查步骤**：

```bash
# 1. 确认 Ollama 服务运行
ps aux | grep ollama

# 2. 测试连接
curl http://127.0.0.1:11434/api/tags

# 3. 测试模型
ollama run llama3 "测试"
```

### 6.4 前端无法连接后端

**检查配置**：

1. 确认后端运行在 `http://localhost:8000`
2. 检查浏览器控制台的网络请求
3. 确认没有 CORS 错误

### 6.5 向量相似度搜索不工作

**问题**：RAG 检索没有返回相关知识

**解决方案**：

1. 确保认知节点有嵌入：
```bash
curl http://localhost:8000/context_nodes/
```

2. 检查嵌入是否生成：
```python
# 在 Python 中测试
from app.services.llm import llm_service
vec = llm_service.get_embedding("测试文本")
print(len(vec))  # 应该是 768
```

### 6.6 Plane 同步失败

**问题**：任务没有同步到 Plane

**解决方案**：

1. 检查 API 配置是否正确
2. 如果没有配置 API Key，系统运行在模拟模式（仅打印日志）
3. 查看后端日志确认同步状态

### 6.7 多模型投票不生效

**问题**：高影响信号没有使用多模型投票

**检查**：

1. 确认影响分数 >= 0.8
2. 确认模型已安装：
```bash
ollama list
```

3. 检查环境变量配置：
```bash
VOTING_MODELS=llama3,qwen2.5,mistral
VOTING_THRESHOLD=0.8
```

---

## 7. API 参考

### 7.1 信号相关

```bash
# 获取所有信号
GET /signals/

# 手动添加信号
POST /signals/ingest
Body: {
  "source": "HackerNews",
  "content": "OpenAI 发布 Sora",
  "impact_score": 0.95
}

# 触发信号获取
POST /signals/fetch
```

### 7.2 实验相关

```bash
# 获取所有实验
GET /experiments/

# 创建实验
POST /experiments/
Body: {
  "title": "FLUX 图像生成测试",
  "hypothesis": "FLUX 比 SDXL 快 2 倍",
  "target_metric": "latency",
  "linked_context_nodes": ["uuid-1", "uuid-2"]
}

# 更新实验评分
PATCH /experiments/{id}
Body: {
  "current_score": 8.5
}
```

### 7.3 知识节点相关

```bash
# 获取所有认知节点
GET /context_nodes/

# 创建认知节点
POST /context_nodes/
Body: {
  "content": "# FLUX 模型\n\n技术规格..."
}
```

### 7.4 反馈相关

```bash
# 提交反馈
POST /signals/{signal_id}/feedback
Body: {
  "was_strategic": true,
  "reason": "判断准确，确实需要跟进",
  "user_id": "user@example.com"
}

# 获取反馈统计
GET /feedbacks/stats
```

---

## 8. 最佳实践

### 8.1 信号管理

- **定期审查**：每天查看高优先级信号
- **及时反馈**：帮助 AI 系统学习
- **关注置信度**：低置信度的判断需要人工复核

### 8.2 实验管理

- **假设要具体**：避免模糊的假设
- **指标可量化**：使用可测量的指标
- **关联知识**：链接相关认知节点

### 8.3 知识管理

- **定期更新**：技术变化时及时更新节点
- **结构化格式**：使用 Markdown 标题和列表
- **包含技术规格**：帮助 AI 理解技术细节

---

## 9. 技术支持

如有问题，请联系技术团队或查看：
- 后端日志：`backend/app/main.py` 输出
- 前端日志：浏览器控制台
- API 文档：`http://localhost:8000/docs`

---

## 附录：项目结构

```
Neural Sync/
├── backend/               # Python 后端
│   ├── app/
│   │   ├── main.py       # FastAPI 主应用
│   │   ├── models.py     # 数据模型
│   │   ├── database.py   # 数据库连接
│   │   └── services/     # 业务逻辑
│   ├── alembic/          # 数据库迁移
│   ├── requirements.txt
│   └── .env.example     # 环境变量模板
│
├── frontend/              # Vue 3 前端
│   ├── src/
│   │   ├── components/  # Vue 组件
│   │   ├── App.vue      # 主应用
│   │   └── main.ts      # 入口文件
│   ├── package.json
│   └── vite.config.ts
│
├── CLAUDE.md             # Claude Code 指导
└── README.md            # 项目说明
```

---

**文档版本**：v1.0
**最后更新**：2024年2月19日