Beancount-Trans for DeepSeek Harness

一个 bundle 接入 Beancount-Trans：

• 只读账本 MCP：连接 https://trans.dhr2333.cn/mcp，提供 mcp__bct__* 工具与 ledger://* 资源；
• 账本分析预设：新会话可选「Beancount-Trans 账本」，带月度复盘、洞察复盘、账本概览三个技能；
• 账本面板：左侧栏「账本」入口，展示最近一个月的日记账，并可把快捷提问带入新会话。

安装

1. 在 DeepSeek Harness 左侧打开 插件 → 添加插件。

2. 输入包名并安装：

   @beancount-trans/dsh

3. 按提示重启 Harness（Web 端刷新页面）。

4. 打开左侧栏的 账本。首次使用会在日记账区域显示 「连接账本」 表单；到 Beancount-Trans 的 个人设置 → 访问令牌 新建一个只读令牌（bct_...），粘贴并保存，然后重启 Harness。

也可以用插件管理工具安装：

plugin_manager install_bundle target="@beancount-trans/dsh"

从旧的两个包升级

旧版本把 MCP、预设和面板拆成了 beancount-trans-dsh 与 beancount-trans-panel。新版合并为 @beancount-trans/dsh，两者不要再同时安装，否则会出现重复的 mcp-bct / 面板行。先卸载旧包，再安装新包并重启。

令牌与安全

• 面板保存的令牌写入本机 ~/.dsh/secrets/bct-mcp.token（目录 700、文件 600），不经过浏览器存储，也不会上传。

• 启动时优先使用环境变量 BCT_MCP_TOKEN；未设置时读取上述文件。适合 CI 或临时排查：

  export BCT_MCP_TOKEN='bct_...'
  dsh web

• 令牌只读（scope ledger:read），不会写入账本。不要把令牌写进 cordis.patch.yml 或提交到仓库。

• 自托管用户不要直接改本包内的 cordis.patch.yml（升级会被覆盖），而是在 profile patch 里用同一 id: mcp-bct 的覆盖项把 url 指向自己的实例，例如 http://127.0.0.1:8000/mcp。

使用

• 预设：新建会话时选择「Beancount-Trans 账本」。技能为 ledger-overview、monthly-review、insight-review；BQL 语法、账户目录和标签目录始终由 MCP 资源提供。
• 面板：点击左侧栏账本图标。日记账来自 mcp__bct__get_journal，按日期倒序，每笔交易列出账户与金额；右上角「刷新」重新读取。三个快捷提问会把提示词预填到新会话输入框，不会自动发送。
• 最近一个月没有记录时：面板自动回退到账本最近 10 条日记账，标题会显示实际条数，说明行标注「最近一个月没有记录」。
• 面板只读；HTTP 路由复用 Web GUI 的浏览器会话校验，未带会话 Cookie 的请求返回 401。

组成

| 文件 | 作用 | |---|---| | package.json | bundle 清单；dsh.bundle.patch 装载补丁，dsh.client 声明 Web 半区 | | cordis.patch.yml | 插入 mcp-bct、preset-beancount 和面板行 | | index.js | Host 半区：GET /beancount-panel/journal、GET/POST /beancount-panel/token | | client.js | Web 半区：main 主面板与 sidebar.panellist 左侧栏入口、令牌表单 | | skills/ | ledger-overview、monthly-review、insight-review | | locale/ | 插件管理器标题与描述（中/英） | | icon.svg | 插件图标 |

本地开发与发布

# 在仓库根目录
cd dsh-plugin
npm pack --dry-run          # 检查发布内容
npm publish --access public # 需要已登录 npm，且拥有 @beancount-trans scope

本地联调也可以直接安装目录：

plugin_manager install_bundle target="/absolute/path/to/dsh-plugin"

发布前确认 package.json 的 name、version、repository.directory 与 publishConfig.access；npm 账号需已加入 @beancount-trans 组织。