神经账本 Elpsycoogroo/dsh-work-report

Neural Ledger · 神经账本

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

img.png
img_4.png

功能

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

快速开始

从 GitHub 安装

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

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

从 npm 安装

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

本仓库手动安装

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

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.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 耗时）同样过滤。

报告生成

- 递归文本提取 — 从任意嵌套的消息结构提取「需求/产出」文本，跳过 、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

本地构建

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（在你拥有该包名之后）

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