Neural Ledger · 神经账本

English | 中文

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

功能

• 📊 实时仪表盘 — 会话数、回合数、工具调用、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 耗时）同样过滤。

报告生成

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

本地构建

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