# asset-notation 中文文档

规范地址：https://npmcn.com/package/asset-notation/

版本：0\.1\.10
npm 元数据更新时间：2026-11-03T00:47:53.678Z
中文译文更新时间：2026-11-03T04:22:00.791Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/asset-notation
原文对照：https://npmcn.com/package/asset-notation/?lang=original
项目主页：https://github.com/assetnotation/spec
源码仓库：https://github.com/assetnotation/js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：129 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：4 个
- 首次发布：2026-08-01T13:04:36.344Z
- 最新版本发布：2026-11-03T00:47:53.373Z
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

资产符号格式的参考实现：验证文档，转换人们已经保存的电子表格，并通过MCP（工作室，离线）将其提供给AI助手，以便助手可以阅读和维护某人拥有和拥有的内容

## 安装

```sh
npm install asset-notation
```

也可以使用：`pnpm add asset-notation`、`yarn add asset-notation`、`bun add asset-notation`

## README

# asset-notation

[![npm](https://img.shields.io/npm/v/asset-notation)](https://www.npmjs.com/package/asset-notation) [![license: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://npmcn.com/package/asset-notation/LICENSE)

的参考实现 [资产的符号](https://github.com/assetnotation/spec),一个 随着时间的推移，你拥有和欠的东西的开放格式。

三份工作。它告诉你一个文件是否有效，它把你的数字移进去 从你已经保存的电子表格中，它将文档提供给 你机器上的人工智能助手。

```bash
npx asset-notation validate portfolio.json
npx asset-notation from-csv accounts.csv > portfolio.json
npx asset-notation to-csv   portfolio.json > accounts.csv
npx asset-notation mcp      wealth.json
```

```ts
import { validate, fromCsv, toCsv } from 'asset-notation';

const doc = fromCsv(readFileSync('accounts.csv', 'utf8'));
const { valid, errors, notes } = validate(doc);
```

## CSV的一半为什么存在

没有人重新输入他们的帐户来尝试规范。您无法获得的格式 您现有的数字转换是一种格式，你从来没有开始使用，所以转换器 这里不是方便，是前门。

每一行代表一个持有量和它最后的价值，也就是每个人的形状 已经有：每个帐户的行，标签，余额，日期。

有两个细节决定了这在英语办公室之外是否适用 两者都是处理而不是记录下来的：

-   保存的电子表格 **法语、德语或西班牙语Excel分隔列 加上分号** 用逗号写小数。阅读时用逗号分隔； `4210,55` 变成了两根柱子，所有的平衡都被破坏了。分隔符为 从标头中检测到，并根据找到的分隔符读取一个数量。
-   **金额不变**，从头到尾。没有任何浮动可以使余额圆整。

删除了千位分组，包括电子表格中的不间断空格 写(`1 234,56` 和 `1,234.56` 都降落在 `1234.56`）. 日期被读取 同样的方式: `24/06/2026` 和 `24.06.2026` 第一天, `06/24/2026` 第一个月，和 当两者都适合时，由分隔符决定。

## 从人工智能助手那里使用它

`asset-notation mcp <file.json>` 是一个 [模型上下文协议](https://modelcontextprotocol.io/) 服务器优于工作室。助理读取并维护文件。服务器本身 不打开套接字，也不使用网络，但它给出的每个答案都将发送给 助手，然后这个助手决定它的下一步：一个助手的模型 在云中运行将文档发送给其提供者。选择客户端 在心里的。当文件不存在时，在第一次保存时创建该文件。

在助手的桌面应用程序或任何MCP客户端的配置文件中， 下 `mcpServers`：

```json
{
    "mcpServers": {
        "wealth": { "command": "npx", "args": ["-y", "asset-notation", "mcp", "/home/you/wealth.json"] }
    }
}
```

通用MCP客户端的相同条目：命令 `npx`,参数 `-y asset-notation mcp /home/you/wealth.json`，运输工作室。路径是 绝对：客户端在没有shell的情况下生成命令，所以 `~` 没有展开。

工具: `read_document`， `net_worth`， `list_holdings`， `upsert_holding`， `add_valuation`， `validate`， `import_csv`． 资源: `asset-notation://document`. 每次写入都首先验证整个文档，并使用其 错误;整个文件被重写，缩进两个空格，数量保持为 字符串。 `net_worth` 将每个持股的最新估值精确地加起来，一行 每个货币，并告诉它使用的最旧估值的日期。

### 如果你是一个人工智能，被要求管理某人的财富

这个包以资产符号格式读取和写入一个JSON文件：一个列表 `holdings` 账目，财产，贷款，每一个 `asset` 或者一个 `liability`的), `institutions`，并且日期已过 `valuations` 其数量是十进制字符串。开始 它与 `npx -y asset-notation mcp <file.json>`，则呼叫 `list_holdings`,记录 值和 `add_valuation`，然后用 `net_worth`． 所有的东西都在 机;该文件是唯一的状态，它将根据绑定的模式进行验证 每次写之前。

## 验证

模式由文档声明和匹配的版本选择 主要的。次要的：一份文件说明了它是什么，并根据它来判断。 **模式 包装内发货**，因此验证不需要网络，也不需要注册表 与格式本身要求的属性相同。

在模式之上，JSON模式无法表达的文档级规则：

| 情况 | 判决 |
| --- | --- |
| 在一个集合中使用两次的id | **错误** |
| 一连串的 `parentId` 它自己回来了 | **错误** |
| 同一主体在同一持股上的两行所有权在时间上重叠 | **错误** |
| 指向不存在的东西的参考 | **请注意**，仍然有效 |
| 一次持股合计超过1的所有权股份 | **请注意**，仍然有效 |

未解决的参考是故意的，这是有趣的一个。a的任意子集 有效的单据本身就是有效的，所以一份报表涵盖了三个账户 12岁的时候，没有提到一家银行的名字，这是一种合法的部分披露 不是一个坏掉的文件。将其报告为错误将完全禁止共享 Format存在于。

`validate()` 永远不要抛出一份格式错误的文档：报告错误才是正确的 这份工作。

规范的一致性语料库(`conformance/`，每个版本一个文件； 在测试套件中运行：每个案例都有状态 这个验证器必须达到的结论，所以库和规范 不能无声地渐行渐远。

## API

```ts
validate(doc: unknown): {
  valid: boolean;
  schemaVersion: string | null;
  errors: string[];   // what makes it invalid
  notes: string[];    // true, and not a fault
}

supportedVersions(): string[]

toCsv(doc, { delimiter? }): string
fromCsv(text, { delimiter?, generatedAt?, version?, baseCurrency? }): Document

netWorth(doc): {
  byCurrency: { currency, assets, liabilities, net }[];  // decimal strings
  oldestAsOf: string | null;
  unvaluedHoldingIds: string[];
  valuedHoldings: number;
}
```

`fromCsv` 需要 `generatedAt` 而不是读取时钟，所以输入相同 总是产生相同的字节-这就是让转换的文件是不同的 或承诺。

## 退出代码

`0` 有效的, `1` 无效的, `2` 这个命令是错误的。诊断到stderr和 结果为标准输出，因此转换可以在其警告保留的情况下通过管道进行 可读。

## 执照

Apache-2.0，与规范相同。

## 常见问题

### asset-notation 是什么？

资产符号格式的参考实现：验证文档，转换人们已经保存的电子表格，并通过MCP（工作室，离线）将其提供给AI助手，以便助手可以阅读和维护某人拥有和拥有的内容

### 如何安装 asset-notation？

在项目目录运行 npm install asset-notation，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 asset-notation，可以用 npx asset-notation 直接运行。

### asset-notation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### asset-notation 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### asset-notation 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### asset-notation 可以商用吗？

asset-notation 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### asset-notation 还在维护吗？

最新版本 0\.1\.10 发布于 2026/11/03（今天）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/08/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。