# lingshu
**Repository Path**: qianlongyutian/lingshu
## Basic Information
- **Project Name**: lingshu
- **Description**: 上海大赛参赛项目 - 灵枢 AI 协伴
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-26
- **Last Updated**: 2026-10-04
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 灵枢 · AI 协伴 V5.0
[English](./README.en.md)
> AI 团队的调度中枢 —— 让多个模型各司其职
> 🌐 项目主页:https://dragonskylord.cn/lingshu
> 📦 下载地址:https://gitee.com/qianlongyutian/lingshu/releases
> 📖 代码仓库:https://gitee.com/qianlongyutian/lingshu




---
## 📖 项目简介
「灵枢 · AI 协伴」是一款面向 AI 应用开发者、内容创作者的**桌面端 AI 协作调度平台**。
它不是"另一个 AI 对话框",而是**让 AI 自己管理 AI**——通过多 Agent 指挥官架构,让不同能力的模型各司其职,实现"任务拆解 → 分配执行 → 质量验收 → 决策下一步"的完整闭环。
**核心亮点**:
- 🤖 **多 Agent 指挥官调度**:架构师 → 开发者 → 审查员 → 汇总员,四级流水线
- 🎭 **伏笔系统**:将叙事状态数字化为变量和触发条件,跨章节追踪
- 🔌 **AgentProvider 抽象层**:多后端自动降级,保证任何环境下都能启动
- 💰 **动态成本控制**:简单任务用轻量模型,复杂任务用旗舰模型
- 📊 **运行时日志**:完整错误追踪,便于定位问题
本项目由**个人开发者独立完成**,代码约 2000+ 行,采用 Python + Tkinter 原生开发,开箱即用。
---
## 📸 界面预览
### 启动引导面板

*首次启动显示功能卡片导航,点击卡片直接进入对应功能。*
### 主界面 · 结构化 Prompt

*七位一体:平台 · 标题 · 场景 · 全局要求 · 子模块 · 任务 · 红线。*
### 多 Agent 指挥官调度

*输入需求后,架构师拆解 → 开发者执行 → 审查员验收 → 汇总员整合。*
### 伏笔系统

*创建故事变量,设置触发条件,系统自动提示伏笔回收时机。*
### 语音助手

*支持在线语音识别与文字输入,均可走多 Agent 调度。*
---
## ✨ 功能特性
| 功能模块 | 说明 |
|---------|------|
| 🤖 **多Agent指挥官调度** | 输入需求,自动完成拆解→执行→审查→汇总 |
| 🎭 **伏笔系统** | 变量管理 + 条件触发 + 自动回收指令 |
| 📝 **结构化 Prompt 生成** | 七位一体:平台·标题·场景·全局要求·子模块·任务·红线 |
| 📚 **规则引擎与红线库** | 场景化规则加载,AI 行为约束 |
| 👥 **群聊协同** | 多 AI 模型群聊,@ 唤起指定专家 Agent |
| 🎤 **语音助手** | 在线语音识别,自动连续对话 |
| 📤 **智能导出** | 支持 .txt / .md / .docx |
| 💾 **历史存档** | 保存并恢复工作状态 |
| 🔍 **代码检测** | pylint + 语法检查,生成修复建议 |
| 🧭 **启动引导面板** | 功能卡片导航,降低新用户门槛 |
---
## 🚀 快速开始
### 方式一:直接运行 EXE(推荐普通用户)
1. 从 [Gitee Releases](https://gitee.com/qianlongyutian/lingshu/releases) 下载 `灵枢AI协伴.exe`
2. 双击运行
3. 首次运行会在同目录生成 `ling_shu_runtime.log` 日志文件
### 方式二:从源码运行(开发者)
#### 环境要求
- **Python 3.10+**(推荐 3.11 或 3.12)
- **Windows 10/11 / macOS / Linux**
- **可选**:Node.js 22.19+ 或 24+(用于 DSH Web 模式)
#### 安装步骤
```bash
# 1. 克隆仓库
git clone https://gitee.com/qianlongyutian/lingshu.git
cd lingshu
# 2. 创建虚拟环境(推荐)
python -m venv venv
venv\Scripts\activate # Windows
source venv/bin/activate # macOS/Linux
# 3. 安装依赖
pip install -r requirements.txt
# 4. 运行程序(跨平台推荐入口)
python main.py
# Windows 用户也可以直接运行中文文件名
# python 灵枢_V5.0_完整版.py
配置 Agent 后端(可选)
灵枢支持三种 Agent 后端,按优先级自动选择:
方式 A:DSH Web UI(完整 Agent 能力)
bash
# 需要 Node.js 22.19+
npx -y @deepseek-ai/dsh web
# 在另一个终端运行灵枢
python main.py
方式 B:DeepSeek 直连 API(无需 Node.js)
powershell
# Windows PowerShell
$env:DEEPSEEK_API_KEY = "sk-你的密钥"
python main.py
方式 C:Mock 模拟模式(无网络演示)
无需任何配置,直接运行即可。系统会自动降级到 Mock 模式。
🛠️ 技术架构
整体架构
text
┌──────────────────────────────────────────────┐
│ 用户交互层(Tkinter GUI) │
├──────────────────────────────────────────────┤
│ AI 指挥官(CommanderRouter) │
│ 意图理解 · 战略拆解 · 质量验收 · 决策 │
├──────────────────────────────────────────────┤
│ 专家 Agent 池 │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐│
│ │ 架构师 │ │ 开发者 │ │ 审查员 │ │ 汇总员 ││
│ └────────┘ └────────┘ └────────┘ └────────┘│
├──────────────────────────────────────────────┤
│ AgentProvider 抽象层 │
│ ┌────────────┐ ┌────────────┐ ┌──────────┐│
│ │DSHWeb │ │DirectAPI │ │Mock ││
│ │Provider │ │Provider │ │Provider ││
│ └────────────┘ └────────────┘ └──────────┘│
└──────────────────────────────────────────────┘
技术栈
层级 技术选型
GUI 框架 Python Tkinter + ttk
Agent 调度 自研 AgentProvider 抽象层
DSH 集成 DSH Web UI(HTTP 通信)
语音识别 SpeechRecognition(Google Web Speech API)
语音合成 pyttsx3(Windows SAPI5)
文档处理 python-docx
代码检测 pylint
日志系统 Python logging
AgentProvider 自动降级逻辑
text
启动灵枢
↓
检测 DSH Web UI 是否可达(127.0.0.1:3080)
↓ 不可达
尝试自动启动 DSH Web UI
↓ 启动失败(无 Node.js)
降级到 DirectAPIProvider(直接调 DeepSeek API)
↓ 无 API Key
进入 MockProvider 模拟模式
🎯 使用示例
示例 1:多 Agent 调度
在群聊窗口中输入(不加 @):
text
帮我设计一个用户登录系统的实现方案
系统会自动执行四级流水线:
text
⚙️ 📋 阶段1:任务拆解中...
⚙️ ✅ 拆解完成
⚙️ 🔧 阶段2:分配任务并执行...
⚙️ ✅ 执行完成
⚙️ 🔍 阶段3:质量审查中...
⚙️ ✅ 审查完成
⚙️ 📦 阶段4:汇总最终结果...
⚙️ 🎉 完成
🤖 指挥官:...
示例 2:伏笔系统
打开「🎭 伏笔」界面
添加变量:信任值,类型 percent,初值 80
添加触发条件:名称 密信回收,条件 信任值 <= 50,指令 反派旧伤发作
将信任值改为 30,点击「🔍 检查所有条件」
系统自动把回收指令插入到当前章节
🎬 演示视频
上海开源大赛实操演示视频
视频访问链接:https://www.bilibili.com/video/BV183av6eEqr/
> 提示:稿件权限为仅自己可见,请复制上方链接登录B站后观看。
🤝 贡献指南
我们欢迎所有形式的贡献!
如何贡献
1. 报告 Bug
使用 Gitee Issues 提交
请包含:操作系统版本、Python 版本、复现步骤、错误日志
错误日志请从 ling_shu_runtime.log 中提取
2. 提交功能建议
在 Issues 中使用 [Feature Request] 标签
描述清楚:使用场景、期望效果、替代方案
3. 提交代码
bash
# 1. Fork 本仓库
# 2. 创建特性分支
git checkout -b feature/your-feature-name
# 3. 提交改动(遵循 Conventional Commits)
git commit -m "feat: 添加 XXX 功能"
# 4. 推送分支
git push origin feature/your-feature-name
# 5. 提交 Pull Request
代码规范
Python 代码遵循 PEP 8
提交前运行 pylint main.py 确保无严重警告
新增功能请补充对应的日志记录
涉及 UI 的改动请附上截图
Commit 消息规范
前缀 含义
feat: 新功能
fix: Bug 修复
docs: 文档更新
refactor: 代码重构
test: 测试相关
chore: 构建/工具变更
贡献者权益
所有贡献者将被列入 CONTRIBUTORS.md
重大贡献者将被邀请加入项目维护团队
📮 Issue 响应承诺
作为个人开源项目,我承诺对社区反馈保持及时响应:
类型 响应时间 处理方式
Bug 报告 48 小时内首次响应 确认问题 → 评估优先级 → 修复或给出解决方案
功能建议 72 小时内首次响应 评估可行性 → 纳入路线图或说明原因
文档问题 24 小时内首次响应 直接修正或补充说明
安全问题 12 小时内首次响应 优先处理,必要时发布补丁版本
Pull Request 72 小时内 Review 给出明确的合并/修改意见
维护承诺
长期维护:本项目为个人长期项目,无归档计划
版本迭代:每季度至少发布一个版本更新
兼容性:保持向后兼容,破坏性变更提前一个版本公告
透明度:所有 Issue 公开处理,欢迎社区监督
📄 许可证
本项目采用 MIT 许可证 —— 详见 LICENSE 文件
Copyright 2026 汪显林
📞 联系方式
项目地址:https://gitee.com/qianlongyutian/lingshu
项目主页:https://dragonskylord.cn/lingshu
作者:汪显林(个人开发者)
软著受理号:2026R11L2794534
🙏 致谢
感谢所有为开源社区做出贡献的开发者,也感谢每一位使用和反馈灵枢的用户。
开源向实,创新有我。
text
**↑ 代码块结束。以上是 README.md 的完整内容。**
---
## ⚠️ 上传前你需要先完成 4 件事
**1. 把 `images/` 文件夹改名为 `docs/`**
在 VS Code 资源管理器中,右键 `images` → 重命名 → 改为 `docs`。
**2. 新建 `main.py`**
在 `灵枢V5.0/` 下新建 `main.py`,内容如下:
```python
# -*- coding: utf-8 -*-
"""
灵枢 · AI 协伴 V5.0 跨平台启动入口
避免中文文件名在 Linux/macOS 下的编码问题
"""
import os
import sys
import runpy
# 切换到脚本所在目录
os.chdir(os.path.dirname(os.path.abspath(__file__)))
# 执行主程序
if __name__ == "__main__":
runpy.run_path("灵枢_V5.0_完整版.py", run_name="__main__")
3. 新建 README.en.md
英文精简版,先放最基础内容(后续再完善):
markdown
# LingShu · AI Companion V5.0
> AI Team Orchestration Hub — Let multiple models work together
[中文](./README.md)
## Overview
LingShu is a desktop AI collaboration platform for developers and content creators. It uses a multi-agent commander architecture to orchestrate different models for different tasks.
## Features
- 🤖 Multi-Agent Commander Orchestration
- 🎭 Foreshadowing System (narrative state tracking)
- 🔌 AgentProvider Abstraction Layer (auto-fallback)
- 💰 Dynamic Cost Control
- 📊 Runtime Logging
## Quick Start
### Option 1: Run EXE (Recommended)
Download from [Gitee Releases](https://gitee.com/qianlongyutian/lingshu/releases)
### Option 2: Run from Source
```bash
git clone https://gitee.com/qianlongyutian/lingshu.git
cd lingshu
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python main.py
License
MIT License — see LICENSE
Copyright 2026 Wang Xianlin
备注:**pypiwin32 仅 Windows 需要,Linux/macOS 可忽略此包安装报错**