MCP / CLI 接入
授权、安装、查询、记账与错误处理。
长禾用于记录家庭资产、投资持仓和交易，并结合已有数据查看投资盈亏、配置策略及公司关注。实例管理员可授权其他使用者，通过 MCP 和 CLI 访问同一套家庭数据；使用者可以连接自己的 AI 助手，也可以通过命令行或脚本查询和记账。
状态：首版代码已实现，2026-10-23；具体站点升级以 GitHub Actions 部署记录为准，CLI 尚未公开发布。 MCP、CLI、访问授权管理与配套 Skill 已在隔离环境验证。使用前需要管理员升级网站；工具包目前由管理员从本仓库打包分发，不提供未发布的 npm registry 安装地址。
本页面向实例管理员与被授权的使用者。部署与开发说明由管理员在工程仓库查阅。
长禾有哪些功能
| 功能 | 当前网页能力 | MCP 与 CLI 的开放安排 |
|---|---|---|
| 家庭资产概览 | 汇总账户总额、负债、净资产、盘点进度与四笔钱 | 第二阶段提供概览查询 |
| 资产账户与持仓 | 按账户记录投资持仓、成本、币种和投资账户内现金 | 首版查询账户与持仓；在已有投资账户下新增按数量与单价计价的持仓 |
| 普通交易 | 记录买入、卖出与手续费，重算持仓数量和成本 | 首版查询、预览和新增；错误交易在网页删除后重新录入 |
| 资产盘点 | 独立记录账户总额，保存当时的盘点报告 | 首版账户查询返回最新总额及来源；盘点写入和报告查询后续扩展 |
| 投资分析与盈亏日历 | 查看已记录期间盈亏、贡献、持仓结构和数据覆盖情况 | 第二阶段提供期间盈亏与结构查询 |
| 组合策略 | 查看目标节点、持仓映射、偏离和新增资金计划 | 第二阶段提供查询及新增资金试算 |
| 组合整体记账 | 记录组合的转入、转出和总资产，计算相应累计盈亏 | 后续扩展；不使用普通买卖交易工具写入 |
| 定投 | 维护计划及执行记录，与普通交易共同重算持仓 | 后续扩展；首版普通交易列表不包含定投流水 |
| 公司关注 | 关注公司、买卖计划、投资日志和每日到价提醒 | 后续开放查询，再扩展新增日志与计划维护 |
| 基金雷达 | 查看场内溢价和场外额度等信息及其来源 | 后续扩展 |
| 目标与历史研究 | 维护目标；查询保留的历史研究资料 | 后续按需求开放；历史研究保持只读 |
| 备份与恢复 | 网页管理完整业务备份、恢复与清空 | 保留在管理员入口，不纳入首版开放工具 |
网页的主要入口是 /assets 家庭资产概览、/assets/inventory 资产盘点、/assets/investment 投资记账、/returns 投资分析、/returns/calendar 盈亏日历、/allocation 组合策略和 /research 公司关注。
选择 MCP 或 CLI
| 入口 | 适合的使用方式 | 提供形式 |
|---|---|---|
| MCP | 在 AI 对话中查持仓、记交易、做复盘 | 网站的 Streamable HTTP 端点 /api/mcp，公开工具名称、说明和参数结构 |
| CLI | 手动查询、脚本调用、保存 JSON 结果 | changhe 命令，通过网站 HTTP 接口访问数据 |
| Skill | 让 AI 按长禾的记账与分析规则完成任务 | 可分发的「长禾记账与复盘」Skill，使用已配置的 MCP 或 CLI |
MCP 和 CLI 都访问指定的长禾实例，不要求使用者复制 SQLite 文件。Skill 提供操作方法，实际访问权限由服务器检查。
首版面向能配置 Bearer Token 的 HTTP 客户端。只支持 OAuth 登录的客户端，需要后续完成 OAuth 接入才能使用；支持 MCP 协议不代表已经完成该客户端的认证兼容验证。已验证官方 MCP TypeScript SDK 1.29.0 Client 的握手、发现与工具调用，以及 Node.js 22 CLI；其他 AI 产品的客户端配置尚未逐一实测。
如何获得授权
实例管理员负责部署和管理长禾，为每位使用者建立独立的授权身份及访问凭据。使用者接收站点地址和自己的凭据即可配置 MCP 或 CLI，无需部署网站、复制数据库或取得管理员的网页登录密码。
管理员可以授予只读访问，按需增加新增交易或新增持仓权限，并设置有效期。不同使用者分别管理凭据；同一使用者也可以为不同应用使用独立令牌，便于单独撤销。操作记录根据凭据识别被授权的使用者、客户端入口和所操作的记录。
首版授权按功能划分，适用于管理员实例中的同一套家庭数据，不提供按家庭成员或单个账户授权。获得资产读取权限的调用者能够读取该实例开放的账户、持仓和交易；管理员创建授权时会看到这个数据范围。
管理员可撤销单个令牌或停用某位使用者的全部访问。撤销会阻止后续访问，不会删除已保存的交易或收回此前读取的数据。分享工具包或本文不会分享访问权限；读取到的数据会交给所连接的 AI 客户端或脚本处理。
这里的授权仅用于 MCP 和 CLI，不自动开通网站登录或管理员权限。接口返回的网页路径仍受原有网页登录保护，未获网页权限的使用者通过 MCP 或 CLI 查看保存回执和记录详情。
首版工具与命令
以下 9 项能力已实现。命令中的参数和返回值与 MCP 保持一致，--json 用于机器读取。
| 能力 | MCP 工具 | CLI 命令 | 所需权限 |
|---|---|---|---|
| 查看版本与可用能力 | get_capabilities | changhe capabilities | 有效凭据 |
| 查询资产账户 | list_accounts | changhe accounts list | assets:read |
| 查询持仓 | list_holdings | changhe holdings list | assets:read |
| 查看一项持仓 | get_holding | changhe holdings get <id> | assets:read |
| 查询普通交易 | list_trades | changhe trades list | assets:read |
| 查看一笔普通交易 | get_trade | changhe trades get <id> | assets:read |
| 预览交易影响 | preview_trade | changhe trades preview | assets:read |
| 新增普通交易 | create_trade | changhe trades add | assets:read 与 trades:create |
| 新增空持仓 | create_holding | changhe holdings add | assets:read 与 holdings:create |
查询列表支持分页，默认每页 50 条、最多 200 条。持仓可按账户或证券代码过滤；交易可按持仓、方向和日期过滤。同一证券在不同账户中是不同持仓，新增交易使用具体的持仓 ID。
账户查询区分账户类型、用途和记录方式；持仓查询默认与网页投资记账一样，只覆盖投资理财用途账户。定投、组合资金流水与普通交易具有不同记录类型，不能把普通交易列表理解成完整资金流水。
get_capabilities 返回服务器版本、接口版本、实例标识、数据代次、业务时区、可用功能和当前凭据权限。数据代次用于区分恢复或清空前后的数据状态。AI 和脚本应据此判断某项功能是否可用，避免仅凭本文的清单发起调用。
首次接入流程
管理员先完成以下设置：
- 升级站点，并在服务端运行环境配置
CHANGHE_PUBLIC_URL=https://你的站点域名（只写 origin，不带路径）。生产服务通过/etc/changhe/changhe.env读取环境；按现有部署流程更新，不将令牌写入环境示例或 Git。 - 登录网页，进入「设置 → 外部访问」(
/settings/integrations)，为每位使用者建立授权身份。默认只读；记账增加trades:create，建立空持仓再增加holdings:create。 - 为该使用者的每个应用生成独立令牌，指定到期日期。明文只显示一次，交付后关闭展示；之后可撤销单个令牌或停用该使用者。
- 本地运行
npm run integrations:pack，将dist/integrations/changhe-cli-0.1.0.tgz与本文交给使用者。包内含 CLI 和skills/changhe/SKILL.md，不含数据库、环境文件或访问令牌。
使用者安装 Node.js 22 后，从管理员取得工具包与 HTTPS 站点地址，通过私密渠道取得自己的令牌：
# 指向管理员交付的实际文件路径
npm install -g ./changhe-cli-0.1.0.tgz
changhe --version
changhe --help
export CHANGHE_URL='https://你的站点域名'
# CHANGHE_TOKEN 通过本机密钥管理或进程环境注入，不放入命令参数、截图或 Skill
changhe auth status --json
changhe capabilities --json
changhe accounts list --jsonCLI 的环境变量覆盖 ~/.config/changhe/config.json 中的非敏感 { "url": "https://你的站点域名" } 配置。令牌仅从 CHANGHE_TOKEN 读取；auth status 不回显令牌。各子命令加 --help 查看完整参数，也可阅读包内自动生成的 capabilities.json。
MCP 客户端需支持 Streamable HTTP 及自定义 Bearer Header。配置服务地址 https://你的站点域名/api/mcp，将 Authorization: Bearer <自己的令牌> 保存在客户端秘密配置中；不同产品的配置文件格式不同。先调用 get_capabilities 核对实例和权限，然后查询账户与持仓。只支持 OAuth 的客户端目前不能直接接入。
Skill 位于 CLI 分发包的 skills/changhe/SKILL.md，安装到所用 AI 客户端支持的 Skill 目录即可；它只说明工作方法，仍需配置 MCP 或 CLI。自动化调用不依赖交互式询问，缺少信息时返回结构化错误。
新增交易如何使用
对已有持仓记账
自然语言示例：
帮我记一笔：2026-10-23，在示例证券账户买入示例 ETF 1000 份，成交价 1.25 人民币，手续费 5 人民币。
AI 先匹配账户和持仓，再核对交易方向、日期、数量、成交单价、币种与手续费。用户明确要求记账且信息完整时可以提交；同名账户、证券匹配不唯一或手续费等信息缺失时，先补问。成交价格采用用户提供的成交信息，不能用当前行情替代。
CLI 示例，假设已授权的站点中持仓 42 是该示例 ETF。请替换为自己的记录及实际成交信息：
changhe holdings list --account-id 7 --json
changhe trades preview --holding-id 42 --direction buy \
--date 2026-10-23 --quantity 1000 --price 1.25 --currency CNY --fee 5 --json
changhe trades add --holding-id 42 --direction buy \
--date 2026-10-23 --quantity 1000 --price 1.25 --currency CNY --fee 5 \
--request-id 8cb25bd1-645a-4c37-929a-768f4fe34301 --json预览不保存交易。正式写入时重新校验账本，并返回交易 ID、保存状态、成交金额、手续费、含费收支、持仓数量和单位成本的变化，以及受网页登录保护的网页路径。
上述示例的成交金额为 1250 元，手续费为 5 元，买入支出为 1255 元。新持仓的期初为零时，买入后有 1000 份，含费单位成本为 1.255 元；已有持仓则按原账本重算。交易记录不会自动改变其他现金持仓或独立记录的账户总额。
首次买入一种产品
先在已有投资账户中建立空持仓，再新增买入交易。空持仓记录名称、证券代码、产品类型、底层资产类别和币种，期初数量与成本均为零。未知的底层资产类别保留待分类。
首版 create_holding 只处理这种空持仓建立，不通过它初始化旧有持仓、直接估值产品或组合整体记账。已有持仓的期初核对在网页完成。新增持仓与新增交易分别返回结果；若持仓建立成功但交易失败，保留空持仓并只重试交易。
超时与重复请求
一次业务操作对应一个固定 request_id。网络超时后使用同一个 ID 和相同内容重试，服务器返回原保存结果；重复使用同一 ID 提交不同内容会报冲突。两笔内容相同但确实分别发生的交易应使用不同 ID。
CLI 重试和 MCP 调用都必须保留原请求 ID。CLI 不自动重试写入。CLI 还会保存该请求最初绑定的实例与数据代次，用于进程重启后的核对。切换实例，或实例恢复、清空数据后，旧请求上下文失效；客户端不会悄悄把旧交易重新记入新的数据状态。
结果应该怎样理解
- 账户总额与持仓明细分别记录，不能相加；新增交易重算明细，已盘点账户总额仍按盘点记录展示。
- 每项账户金额保留其记录日期。响应生成时间不表示全部账户刚刚确认过。
- 当前盘点报告冻结资产账户记录，不包含负债快照，不能将其直接视为当日完整净资产报告。
- 行情时间、抓取时间和币种折算依据分别返回；估算汇率保留估算标记，缺失值为
null，不能改成零。 - 投资盈亏只覆盖已记录并有估值依据的投资。期间结果须同时查看覆盖范围、缺失日期和未结算状态；它不等于家庭净资产变化。
- 明细或汇率不完整时，策略接口返回无法分析的原因；已有目标规则仍可说明，但不生成伪完整的实际权重和新增资金计划。
- 普通交易与定投共同影响持仓，同一笔定投只记一次。公司投资日志和买卖计划表达观察或意图，不作为实际成交记入持仓。
常见错误与处理
以下为稳定错误代码；HTTP、CLI 和 MCP 保留相同业务含义。
| 错误 | 含义与处理 |
|---|---|
UNAUTHENTICATED | 凭据缺失、过期或已撤销；检查当前实例及凭据 |
FORBIDDEN | 已连接，但没有该操作权限；由管理员调整权限 |
VALIDATION_ERROR | 参数不完整或格式错误；根据字段说明修正 |
NOT_FOUND | 指定记录不存在；重新查询对应账户或持仓 |
LEDGER_REVIEW_REQUIRED | 旧账本需要先在网页核对期初 |
INSUFFICIENT_HOLDING | 在交易所属日期发生超卖；检查期初及历史交易 |
IDEMPOTENCY_CONFLICT | 请求 ID 已用于其他内容；先核对原请求，确认是新操作后再换 ID |
STALE_STATE | 预览依赖的持仓状态已变化；重新查询并核对影响 |
DATA_GENERATION_CHANGED | 恢复或清空已改变数据代次；旧请求停止重试，核对当前数据 |
MAINTENANCE / RATE_LIMITED | 维护中或请求过快；按返回的等待时间重试，写入保留原请求 ID |
网络超时只说明客户端没有取得结果，不能据此判断交易失败。没有明确保存回执时，AI 应说明状态待核实，并用原请求核对，不能报告“已记账”。
后续开放安排
第二阶段同时扩展 MCP 与 CLI：get_overview / changhe overview、get_returns / changhe returns、get_strategy_analysis / changhe strategy analyze。后者接受可选新增资金金额，仅计算计划，不产生交易。
后续再按实际需求扩展公司关注、投资日志、定投、组合流水、盘点与基金雷达。批量导入、交易更正和删除需要各自明确的校验与回执，不以首版新增交易的循环调用冒充已经支持的批量能力。
公开分发与更多客户端兼容性验证仍待完成。生产部署使用仓库现有 GitHub Actions 工作流，升级结果以对应运行记录为准。后续版本继续单独标注已实现能力和计划范围。