# Neural Ledger · 神经账本

[English](README.md) | 中文

> **一句话：** 零侵入的 DSH 插件，把你和 AI 协作的会话变成一本可视化「神经账本」——Token 分析、智能洞察、趋势预测，一键生成日报/周报/月报。数据全来自你自己的会话，不碰 DSH 一行源码。

![img.png](screenshots/img.png)
![img_4.png](screenshots/img_4.png)

## 功能

- **📊 实时仪表盘** — 会话数、回合数、工具调用、Token 消耗、AI 耗时一眼看全。
- **💡 智能洞察** — 自动总结：哪个会话最烧钱、哪个最耗时、子代理协作占比、对话效率。
- **📈 Token 分析** — 每日消耗柱状图、Token 构成环形图（未缓存输入/缓存读取/输出）、各会话耗时与 Token 排行。
- **🔮 趋势预测** — 线性回归预测未来 7 天消耗、月预估，超预算（默认 50M token/月）自动警示。
- **🗂 工作区对比** — 跨项目 Token 对比图；三级树 `工作区 → 父agent → 子代理` 下钻。
- **📋 一键报告** — 导出日报/周报/月报 Markdown，含每一回合的「需求 → 产出」要点和子代理分工详情，可复制或下载。
- **📤 导出会话上下文** — 树形选择器（工作区 → 父agent → 子代理，可折叠、模糊搜索含工作区）→ 生成「提炼版上下文」（类似 prompt）：元信息、任务目标、逐回合需求/产出、工具摘要、可继续工作的 prompt，直接喂给另一个 AI agent 接着干。
- **🌐 国际化** — 一键切换中文/英文，覆盖整个界面和导出的报告（记住选择）。
- **🎬 示例模式** — 内置模拟数据集，无需真实数据即可预览完整仪表盘。
- **可拖拽悬浮球** — 右下角 🧠 悬浮按钮可拖到任意位置、记住位置、hover 标签实时跟随。
- **不修改 DSH 源码** — 仅 DOM 级集成，不碰任何 DSH 文件。

## 快速开始

### 从 GitHub 安装

```bash
dsh plugin --profile web add github:Elpsycoogroo/dsh-work-report
```

> **pnpm 默认拦截构建脚本**：从 GitHub 安装会执行项目自带的构建脚本，pnpm 默认不允许。直接跑一次命令，pnpm 会打印要加到 `~/.dsh/profiles/web/pnpm-workspace.yaml` 里 `allowBuilds` 的 key，加进去再装一次。

### 从 npm 安装

```bash
dsh plugin --profile web add dsh-work-report
```

### 本仓库手动安装

把插件放/克隆到 `dsh/plugins/dsh-work-report`，构建一次：

```bash
cd dsh/plugins/dsh-work-report
npm install
npm run build
```

> ⚠️ **不要只把 `lib/` 复制到 profile 的 `node_modules/`**——缺 `package.json`（和 `cordis.patch.yml`）的副本无法被 DSH loader 解析。要同步就同步整个包。持续开发用 `node dev.mjs`（监听 src/ → 自动构建 → 自动**整包**同步 profile）。

### 使用

1. 打开 DSH，点击右下角 **🧠 悬浮球**（可拖到任意位置）。
2. 神经账本全屏打开，展示你的会话真实数据。
3. 选报告类型（日报/周报/月报——自动切换时间窗口 1/7/30 天）。
4. 点 **📋 复制** 或 **⬇ 下载** 拿到 Markdown 报告。
5. **📤 导出上下文** — 从可折叠树（工作区 → 父agent → 子代理）选会话，或模糊搜索；然后复制/下载提炼版上下文作为另一个 agent 的 prompt。
6. **🌐 EN** — 一键把整个界面（和导出报告）切成英文。

### ⚠️ 二开前必读（踩坑实录）

1. **`package.json` 的 `exports` 必须包含 `"./package.json"`**：DSH 的 client-modules 用 `require.resolve('<包名>/package.json')` 读取插件清单。`exports` 未导出该子路径会抛 `ERR_PACKAGE_PATH_NOT_EXPORTED`，表现为**插件列表可见、但 client.js 永远不被注入**。
2. **三处 name 必须一致**：`package.json` 的 `name`、插件自带 `cordis.patch.yml` 的 `name`、profile bundle 里引用的名字。
3. **改完 manifest/重装后必须重启 dsh**：client-modules 的"非客户端插件"判定是进程内缓存，刷新页面不会生效。
4. **`sessionPersistence.readFrom()` 可能不可用**：server 端会回退到 projcache（`storages/session_projcache.json`）；子代理 token 缺失时从事件 `usage` 段聚合兜底。

## 给开源作者

本地开发、调试、接入指南见 [DEVELOPING.md](DEVELOPING.md) / [DEVELOPING.zh.md](DEVELOPING.zh.md)。

## 工作原理

### 架构

```
浏览器 (client 插件)
  ReportView ── StatCards / Insights / TokenCharts / ForecastCard
            ├── WorkspaceChart / EfficiencyCharts / ToolRanking
            └── SessionTimeline (工作区 → 父agent → 子代理)
                │
                └── fetch('/api/work-report?days=7&mock=1')   ← 由 ReportView 发起，所有卡片共享
Host (server 插件) [ctx.webServer.register({ kind: 'exact', path: '/api/work-report' })]
  ctx.get('sessions')                → 内存中的活跃会话
  ctx.get('sessionPersistence')      → 持久化的冷会话 + 事件
  storages/session_projcache.json    → tokenUsage / sessionStats / contextPressure / 子代理标签
  → buildReport(config) → { sessions, token, time, insights, forecast, dailyTokens, workspaceTokens }
```

### 数据源

- **活跃会话** — `ctx.sessions.list()`（内存中挂载的会话）。
- **冷会话** — `persistence.list()` + `persistence.readFrom(id, 0)` 拿事件和 `parentSession` 关联。`readFrom` 可选，缺失时元数据来自 projcache。
- **Token/统计** — projcache 投影（`tokenUsage.totals`、`sessionStats`、`contextPressure`），事件 `usage` 聚合做兜底。
- **子代理标签** — projcache `subagent.identity.label`（如 `Worker A - 代码开发`）；父子关联用 `meta.parentSession`。
- **归档过滤** — 用 `workspace.json` 的 `global.archivedSessionIds`；空会话（0 token 且 0 耗时）同样过滤。

### 报告生成

- **递归文本提取** — 从任意嵌套的消息结构提取「需求/产出」文本，跳过 `<system-reminder>`、`Current runtime context.` 等噪音。
- **回合故事线** — 每个回合记录用户需求、AI 产出、工具调用（✓/✗）、token 用量。
- **趋势预测** — 对每日 token 做线性回归，稀疏数据自动回退基线；预测未来 7 天 + 30 天预估对比预算。

## 文件结构

```
dsh-work-report/
├── package.json
├── tsconfig.json
├── tsdown.config.ts
├── cordis.patch.yml
├── README.md            # English docs
├── README.zh.md         # 中文文档
├── DEVELOPING.md        # English contributor guide
├── DEVELOPING.zh.md     # 中文开发者指南
├── CONTRIBUTING.md      # 中文贡献指南
├── CONTRIBUTING.en.md   # English contributing guide
├── GITHUB_SETUP.md      # GitHub 仓库设置清单
├── pull_request_template.md
├── pull_request_template.en.md
├── mock-report.json     # 内置示例数据集（🎬 示例模式）
├── screenshots/         # README 截图（仪表盘预览）
├── .github/             # ISSUE_TEMPLATE（bug_report.yml / feature_request.yml）
└── src/
    ├── index.ts             # Host 入口（再导出）
    ├── server/
    │   ├── index.ts         # webServer 路由 /api/work-report
    │   └── report-data.ts   # 数据收集、聚合、洞察、预测
    ├── client/
    │   ├── index.ts         # client 入口：可拖拽悬浮球 + 覆盖层挂载
    │   ├── i18n.tsx         # 中英字典 + 语言 Provider
    │   ├── ReportView.tsx   # 主仪表盘
    │   ├── StatCards.tsx    # 统计卡片
    │   ├── Insights.tsx     # 智能洞察卡片
    │   ├── TokenCharts.tsx  # 每日柱状 + 构成环形
    │   ├── ForecastCard.tsx # 趋势预测 + 预算提醒
    │   ├── WorkspaceChart.tsx # 工作区对比
    │   ├── EfficiencyCharts.tsx # 各会话耗时与 Token 排行
    │   ├── ToolRanking.tsx  # 会话类型 Token 占比
    │   ├── SessionTimeline.tsx # 三级树会话列表
    │   ├── ContextExporter.tsx # 导出会话上下文（树形选择器 + 搜索）
    │   ├── markdown.ts      # 日报/周报/月报生成器
    │   └── report-api.ts    # API 拉取 + 格式化工具
    └── types/
        └── dsh-env.d.ts     # 环境类型声明
```

## 构建与发布 npm

### 本地构建

```bash
cd dsh/plugins/dsh-work-report
npm run build     # tsdown：host ESM (lib/index.js) + browser CJS (lib/client.js)
node dev.mjs      # watch 模式：自动构建 + 自动整包同步 profile
```

> 浏览器产物内联 echarts（放在 `devDependencies` 让它被打包；模块表 external 只有 `react` / `@deepseek-ai/*`）。

### 发布 npm（在你拥有该包名之后）

```bash
npm login
exports_subpath=./package.json   # 保留 exports["./package.json"]——DSH client-modules 需要它
npm version patch -m "chore(release): v%s"
npm publish --access public
# 验证产物包含运行时必需文件：
npm pack --dry-run | grep -E "package.json|cordis.patch.yml|lib/(index|client)\.js|mock-report"
```

> 发布内容由 `package.json` 的 `files` 字段控制（`lib`、`src`、`mock-report.json`、`cordis.patch.yml`、文档）。首次发布前务必确认 `files` 包含所有运行时文件——DSH loader 运行时解析的是 `package.json` 和 `cordis.patch.yml`，不只是 `lib/`。

## 控制台日志


| 来源              | 级别  | 说明                             |
| ----------------- | ----- | -------------------------------- |
| `client/index.ts` | log   | 版本加载（`v0.1.0 loaded`）      |
| `server/index.ts` | log   | 路由注册（`host plugin loaded`） |
| `server/index.ts` | error | 战报构建失败                     |

## 许可证

MIT