LuminaSight

多会话、自进化的 Agent 知识库产品 — 在对话中积累知识，让知识反哺 Agent。

核心理念： AI 做效率工具，人做最终决策；知识库即文件系统，工具无关可移植；信息源多源化，SOP 作为研究引导层。

目录

• 架构介绍
• 功能介绍
• 产品特色
• 开发流程
• 使用方式
• 项目结构
• 技术栈

架构介绍

LuminaSight 基于 Pi Agent 构建，采用对话驱动架构（非工作流引擎），分层设计保证高内聚低耦合与跨宿主可移植性。

┌─────────────────────────────────────────────────────┐
│  Pi Agent（对话主引擎）                              │
│  ├─ 交互层：自然对话 + /commands + /skills + 进度文件 │
│  ├─ 扩展层：core（本项目）+ 数据源扩展（ds_* 槽位）  │
│  ├─ 技能层：6 个投研框架 skill                       │
│  └─ 信息源：KB → 数据源槽位（ds_*）→ web_search      │
├─────────────────────────────────────────────────────┤
│  LuminaSight core 扩展（.pi/extensions/core）        │
│  ├─ 知识库：kb-index（FTS5 检索）/ kb 工具            │
│  ├─ 研究：progress（进度）/ research（对话引导）      │
│  ├─ 数据：data-cache（缓存）/ pdf-extract（PDF文本）  │
│  ├─ 监控：monitor（跟踪/提醒）                        │
│  ├─ 自进化：organize（知识提炼）/ skill-evolution     │
│  └─ 通用：save-discussion / ticker-pool                    │
├─────────────────────────────────────────────────────┤
│  数据层（~/LuminaVault 纯文件，Obsidian 兼容）          │
│  投资/ 工作/ 学习/ 生活/ 知识卡/ 专业访谈/ 待归档     │
└─────────────────────────────────────────────────────┘

架构分层

| 层 | 说明 | 可移植性 | |---|---|---| | 交互层 | Pi 扩展（工具/命令/事件） | 绑定 Pi | | 逻辑层 | 纯 TS 模块（FTS5/缓存/进度等） | 可抽离为独立库（P4） | | 数据层 | ~/LuminaVault 纯文件 | 完全可移植（Obsidian 兼容） |

设计原则

• 对话驱动：Agent 与用户对话式协作，非僵化批处理
• 信息源分层：知识库（记忆）→ 结构化 API（事实）→ 网页（实时）
• KB 即缓存：文件系统即真相源，避免重复获取
• 自进化双循环：在线记录证据 + 离线整理提炼（/organize）
• 人做最终决策：新建目录、skill 更新均需用户确认

功能介绍

通用能力（核心层）

| 功能 | 说明 | |---|---| | 自然对话 | 任意主题对话，Agent 使用多信息源 | | 知识保存 /save | 会话内容保存进 KB（指定分类或自动归类） | | 自动分类 | 未指定分类 → 待归档 → Agent 识别主题移动 | | 自动建目录 | 无合适目录时提议新建，用户批准后创建 | | 跨会话记忆 | 会话自动检索 KB 相关内容作为参考 | | 知识检索 | FTS5 全文检索（中文 3 字 + 2 字回退 + 同义词 + 高亮） | | 保存提示 | 对话较深时提示 /save 沉淀知识 | | 知识整理 /organize | 聚类 → 提炼知识卡 → 用户确认（自进化） |

投资研究层（专项）

| 功能 | 说明 | |---|---| | /research <symbol> | 对话式五步 SOP 研究（初筛→深度→验证→决策→跟踪） | | 进度跟踪 | 每公司进度文件（投资/研究进度/{symbol}.md），支持跨会话续研 | | 标的池管理 | 6 阶段流转，随研究进度自动同步 | | 数据获取 | 数据源槽位（ds_company/financials/shareholders/capital/trade/announcements/lookup/reports）+ 网页搜索；可插拔，支持自定义数据源接入 | | 数据缓存 | 财报按期间（年报/中报/季报）+ 发布日历判断新鲜度 | | PDF 管理 | 公告/研报去重下载 + 文本化进可检索层 | | 监控闭环 | 跟踪日志 + 持仓状态检查 + 异常提醒 |

自进化（v0.4）

| 功能 | 说明 | |---|---| | 知识提炼 | 同主题 3+ 文件 → 提炼结构化知识卡 | | 双循环整理 | 在线记录 + 离线 /organize 合并/修剪/提炼 | | skill 进化 | 方法改进候选累计 3+ 次 → 用户确认更新 skill | | 检索评估 | R3 三层次基准（基础回忆/多会话/主动服务） |

产品特色

1. 自进化知识库 — 不只是"会记"，而是"会学"：对话沉淀 → 离线提炼 → 知识反哺
2. 多源信息 — 本地 KB + 结构化数据 API + 实时网页，三层信息源
3. 纯文件可移植 — KB 是 Markdown/JSON/PDF，Obsidian/VS Code 直接打开，工具无关
4. 对话式研究 — 五步 SOP 作为引导而非僵化流程，可打断、可深入、可续研
5. 人机协作 — AI 提效，人做决策；所有系统变更（建目录/skill 更新）需用户确认
6. 缓存智能 — 财报按发布日历（年报 4/30、中报 8/31 等）判断新鲜度，避免重复获取
7. 中文优先 — FTS5 trigram 中文检索 + 同义词表 + 2 字 LIKE 回退
8. 测试保障 — 55+ 用例覆盖全部核心逻辑，npm test 一键回归

开发流程

文档驱动

需求分析 → 计划 → 方案 → 开发 → 测试
docs/requirements/  docs/plans/  docs/design/

开发规范

# 1. 每项需求对应 FR 编号（docs/requirements/）
# 2. 先写测试再实现（TDD）
# 3. 类型检查 + 测试通过后提交
cd .pi/extensions/core
./node_modules/.bin/tsc --noEmit          # 类型检查
npm test                                   # 55+ 测试回归

提交规范

• feat(vX.Y): 描述 — 新功能
• fix(vX.Y): 描述 — 缺陷修复
• refactor: 描述 — 重构
• docs: 描述 — 文档

各版本里程碑进度见 路线图。

安装

方式一：作为 Pi 包安装（推荐）

任何 Pi Agent 用户可直接安装，构建自己的知识库（数据存放在你自己的 ~/LuminaVault/，互不干扰）：

① 安装核心包（扩展 + 14 个 skills）
pi install npm:lumina-sight

# 或从 GitHub 安装（指定版本 tag）
# pi install git:github.com/huakui/[email protected]

② 安装数据源扩展（投资研究功能需要，独立项目）
pi install /path/to/pi-ext-cninfo       # 财务/公告/股东数据
pi install /path/to/pi-ext-eastmoney    # 券商研报
pi install npm:pi-web-access            # 网页搜索（Exa 零配置）

③ 启动
pi

首次启动自动创建 ~/LuminaVault/ 目录结构；可用 LUMINA_VAULT_ROOT 环境变量自定义知识库位置。

方式二：开发者本地运行

① 安装依赖包
pi install /path/to/pi-ext-cninfo       # 财务/公告/股东数据（独立项目）
pi install /path/to/pi-ext-eastmoney    # 券商研报（独立项目）
pi install npm:pi-web-access            # 网页搜索（Exa 零配置）

② 配置 LLM
# ~/.pi/agent/settings.json（全局 Pi 配置）
{
  "defaultProvider": "opencode-go",
  "defaultModel": "deepseek-v4-flash"
}
# ~/.pi/agent/auth.json（API key，Pi 自动管理）

③ 启动
cd ~/projects/lumina-sight && pi

依赖清单

| 包 | 用途 | 类型 | |---|---|---| | pi-ext-cninfo | 财务/公告/股东/资本/交易数据（cninfo API） | 独立项目，pi install | | pi-ext-eastmoney | 券商研报搜索（eastmoney API） | 独立项目，pi install | | pi-web-access | 网页搜索/内容提取（多 provider，Exa 零配置兜底） | npm | | pi-subagents | 子代理并行委派（可选，研究 fan-out） | npm | | better-sqlite3 | FTS5 检索索引（项目内） | npm（扩展内） | | pdfjs-dist | PDF 文本提取（项目内） | npm（扩展内） |

数据源扩展（cninfo/eastmoney）保持独立项目 — 不纳入本仓库，任何项目可复用。

使用方式

前置：已完成快速开始的安装与配置。

常用命令

| 命令 | 用途 | |---|---| | /research <symbol> <name> | 启动投资研究（续研模式自动识别） | | /save [分类] [标题] | 保存当前会话到知识库 | | /pool list [--stage X] | 查看标的池 | | /kb search <query> [--category X] | 检索知识库 | | /kb reindex / /kb status | 重建/查看索引 | | /organize | 知识整理（聚类→提炼知识卡） |

典型场景

# 场景1：日常对话沉淀知识
聊 AI 行业 → /save 产业资料 AI行业分析 → 后续会话自动引用

# 场景2：投资研究（对话式五步 SOP）
/research 300308 中际旭创
→ 初筛（Litmus 5）→ 深度研究（5维度）→ 验证 → 决策 → 跟踪
→ 每步更新进度文件，可中途退出/续研

# 场景3：知识自进化
多次保存同一主题 → /organize → 提炼知识卡 → 用户确认

数据目录

~/LuminaVault/
├── 投资/          标的池/研究笔记/决策记录/跟踪日志/研究进度/
│                  财报(JSON)/研报(PDF)/公告(PDF)/公司简况/产业资料
├── 工作/          工作笔记
├── 学习/书籍/      读书笔记
├── 生活/          生活记录
├── 知识卡/        提炼的结构化知识
├── 专业访谈/      访谈记录
└── 待归档/        未分类（待 Agent 整理）

项目结构

~/projects/lumina-sight/
├── .pi/
│   ├── settings.json          # 项目配置
│   ├── extensions/core/       # LuminaSight core 扩展
│   │   ├── index.ts           # 入口：命令/事件/工具注册
│   │   ├── kb-index.ts        # FTS5 检索索引
│   │   ├── knowledge-base.ts  # kb 工具
│   │   ├── progress.ts        # 研究进度
│   │   ├── data-cache.ts      # 数据缓存
│   │   ├── pdf-extract.ts     # PDF 文本化
│   │   ├── monitor.ts         # 监控
│   │   ├── organize.ts        # 知识提炼
│   │   ├── skill-evolution.ts # 方法改进
│   │   ├── save-discussion.ts # 会话保存
│   │   ├── ticker-pool.ts     # 标的池
│   │   ├── vault-util.ts      # 公共路径
│   │   └── tests/             # 55+ 用例
│   └── skills/                # 6 个投研框架
├── docs/
│   ├── requirements/          # 需求文档
│   ├── plans/                 # 开发计划
│   └── design/                # 技术方案
└── scripts/                   # 辅助脚本

技术栈

| 层 | 技术 | |---|---| | 平台 | Pi Agent（TUI + 扩展机制） | | 语言 | TypeScript（jiti 加载，免编译） | | 检索 | SQLite FTS5（better-sqlite3 + trigram） | | PDF | pdfjs-dist | | 数据源 | cninfo / eastmoney（独立扩展）+ web_search | | 测试 | vitest | | 存储 | ~/LuminaVault 纯文件（MD/JSON/PDF） |

路线图

已完成里程碑

| 版本 | 内容 | 状态 | |---|---|---| | v0.1 核心验证 | FTS5 索引、/save 链路、中文检索 | ✅ | | v0.2 投资层 | 进度文件、对话式研究、标的池联动、数据缓存 | ✅ | | v0.3 完善 | PDF 文本化、检索增强、监控闭环、检索评估 | ✅ | | v0.4 自进化 | 知识提炼、/organize 双循环、skill 进化 | ✅ |

远期方向（P4+，按需启动）

| 方向 | 内容 | 触发条件 | |---|---|---| | P4 逻辑层解耦 | 核心逻辑抽为 @luminasight/core 独立包，Pi 扩展变薄壳 | 核心逻辑稳定 / 跨宿主需求 | | P5 MCP 服务化 | 25+ 工具包成 MCP server，支持多 Agent 客户端 | 明确多宿主使用需求 |

设计原则：数据层永远是资产（LuminaVault 纯文件），逻辑层可随时抽离，交互层按宿主适配。 现阶段保持 Pi 深度集成优先（交互体验最佳），解耦作为远期储备。

许可证与贡献

内部项目 · 个人使用。欢迎基于文档驱动流程迭代改进。