12 KiB

Raw Blame History

Neural Sync - 用户使用手册

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

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 (开发环境)

步骤一：启动 Ollama AI 服务

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

# 启动 Ollama 服务
ollama serve

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

步骤二：启动后端服务

cd backend

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

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

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

# 运行数据库迁移
alembic upgrade head

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

步骤三：启动前端界面

cd frontend

# 安装依赖
npm install

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

步骤四：访问系统

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

3. 核心功能使用

3.1 信号监控

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

如何使用

自动获取信号

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

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

手动添加信号

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

查看战略分析

点击左侧信号列表中的任意信号，右侧将显示：

AI 战略研判结果
置信度评分
多模型投票情况
相关知识引用
竞争力雷达图

优先级说明

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

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

3.2 实验管理

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

如何使用

创建新实验

点击"新建实验"按钮，填写：

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

追踪进度

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

查看实验列表

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

3.3 知识管理

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

如何使用

添加认知节点

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

# FLUX 图像生成模型

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

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

AI 自动分析

系统会自动：

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

语义检索

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

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 文件：

# 数据库配置
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 战略研判的核心基础，应根据实际情况配置：

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

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

5.3 Ollama 模型管理

查看已安装模型：

ollama list

下载新模型：

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

6. 常见问题

6.1 后端启动失败

问题：ModuleNotFoundError: No module named 'xxx'

解决：

cd backend
source venv/bin/activate
pip install -r requirements.txt

6.2 数据库连接失败

问题：could not connect to server

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

编辑 backend/.env：

DATABASE_URL=sqlite+aiosqlite:///./neural_sync.db

解决方案 B - PostgreSQL 配置：

# 启动 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 战略分析没有返回结果

检查步骤：

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

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

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

6.4 前端无法连接后端

检查配置：

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

6.5 向量相似度搜索不工作

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

解决方案：

确保认知节点有嵌入：

curl http://localhost:8000/context_nodes/

检查嵌入是否生成：

# 在 Python 中测试
from app.services.llm import llm_service
vec = llm_service.get_embedding("测试文本")
print(len(vec))  # 应该是 768

6.6 Plane 同步失败

问题：任务没有同步到 Plane

解决方案：

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

6.7 多模型投票不生效

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

检查：

确认影响分数 >= 0.8
确认模型已安装：

ollama list

检查环境变量配置：

VOTING_MODELS=llama3,qwen2.5,mistral
VOTING_THRESHOLD=0.8

7. API 参考

7.1 信号相关

# 获取所有信号
GET /signals/

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

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

7.2 实验相关

# 获取所有实验
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 知识节点相关

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

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

7.4 反馈相关

# 提交反馈
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日

12 KiB Raw Blame History Unescape Escape

Neural Sync - 用户使用手册

目录

1. 系统简介

1.1 什么是 Neural Sync？

1.2 核心价值

1.3 三大核心功能

2. 快速开始

2.1 安装部署

前置要求

步骤一：启动 Ollama AI 服务

步骤二：启动后端服务

步骤三：启动前端界面

步骤四：访问系统

3. 核心功能使用

3.1 信号监控

如何使用

优先级说明

3.2 实验管理

如何使用

3.3 知识管理

如何使用

4. 日常使用流程

4.1 每日信号审查流程

4.2 技术决策流程

4.3 知识沉淀流程

5. 系统配置

5.1 环境变量配置

5.2 业务上下文配置

5.3 Ollama 模型管理

6. 常见问题

6.1 后端启动失败

6.2 数据库连接失败

6.3 Ollama 连接失败

6.4 前端无法连接后端

6.5 向量相似度搜索不工作

6.6 Plane 同步失败

6.7 多模型投票不生效

7. API 参考

7.1 信号相关

7.2 实验相关

7.3 知识节点相关

7.4 反馈相关

8. 最佳实践

8.1 信号管理

8.2 实验管理

8.3 知识管理

9. 技术支持

附录：项目结构

12 KiB

Raw Blame History