# @falari/harness 中文文档

规范地址：https://npmcn.com/package/%40falari/harness/

版本：0\.8\.20
npm 元数据更新时间：2026-11-11T12:06:42.806Z
中文译文更新时间：2026-11-14T09:38:48.231Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40falari/harness
原文对照：https://npmcn.com/package/%40falari/harness/?lang=original
项目主页：https://falari.xyz/

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

- 包体积（解压后）：1.9 MB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-11-10T10:16:53.248Z
- 最新版本发布：2026-11-11T12:06:42.034Z
- 近 30 天下载量：2160（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

Falari Data客户端 DeepSeek Harness:代理密钥状态,数据上传和下载.

## 安装

```sh
npm install @falari/harness
```

也可以使用：`pnpm add @falari/harness`、`yarn add @falari/harness`、`bun add @falari/harness`

## README

# 法拉利哈内斯

Falari 数据客户端 **深搜索策略** (DSH):上传文件到 Falari 存储并下载回来,唯一的证书是Agent Key。 这个 相同的6个操作作为工具暴露于模型中,并作为工具暴露于用户 显示面板.

-   设计和里程碑日志: [文件/计划](https://npmcn.com/package/%40falari/harness/docs/plan.md)
-   测试计划: [文件/测试计划](https://npmcn.com/package/%40falari/harness/docs/test-plan.md)
-   释放注释 : [变动情况](https://npmcn.com/package/%40falari/harness/CHANGELOG.md)

插件带有 Falari 标记 : `icon.png` 是提供的389×389出物, (没有收成,没有透明度) 图像与其原WebP字节相同. 侧边栏绘制清晰的矢量艺术 `>_` 活在20px时.

## 状态

| 阶段 | 范围 | 状态 |
| --- | --- | --- |
| M0 导弹 | 站台、安装、面板/设置占位符 | 已完成——安装在 `desktop` 简介(2026-11-09) |
| M1级 | 代理密钥存储, `falari_status` 工具,设置页面 | 已完成(v.2.0) |
| M2级 | 引用、上传队列、上传面板, `falari_quote` 编号 : `falari_upload` 编号 : `falari_task` | 已完成(v0.3.0) |
| M3级 | 意向列表,下载/解密, `falari_list` 编号 : `falari_download` | 已完成(v. 4.0) |
| M4级 | 可编辑设置、单位测试、测试计划 | 已完成(v0.5.0); 测试网密钥前的现场接收 |
| M5型导弹 | 仓库布局、更改日志、许可证、清单检查 | 已完成(v0.5.0) |

活链验证仍然需要真正的测试网代理密钥:设置页面 每条路线/工具的路径 都包含在离线烟雾测试中 但什么都没有 此处已对测试网进行付费上传 .

全部设计在 [文件/计划](https://npmcn.com/package/%40falari/harness/docs/plan.md)。 。 。 .

## 项目

-   开发者 : **平面图**
-   网站: [https://falari.xyz (英语)](https://falari.xyz/)
-   软件包 : `@falari/harness`

## 解决问题: DSH 无法启动

早先的一栋建筑将被封存的代理密钥写成额外的字段 `api-key` 证书记录. 证书店拒绝未知的字段并拒绝 启动 :

```text
credentials-local: record "falari-harness/agent-key" in ~/.dsh/.credentials.yaml
has unknown field "v"
```

6.8.20 将信封保存在记录中 `key` 字段并迁移旧 启动时的记录。 如果 DSH 完全无法启动, 请将文件脱机修复 :

```sh
node scripts/repair-credentials.mjs --file ~/.dsh/.credentials.yaml
```

脚本只重写该记录, 首先支持文件, 并打印不 暗号.

## 安装( 开发)

打开 **插件 — 添加** 在DeepSeek Harness中将其指向这个目录,或者 从代理会话调用插件管理器工具 :

```text
plugin_manager action=install_bundle target=/path/to/clients/harness
```

捆绑是作为本地链接安装的(`link:...`) (中文(简体) ). 用于发布构建 `plugin_manager action=install_bundle target=@falari/harness@0.8.9`。主机代码更改需要 重新装入的插件行( 切换捆绑出/ 上, 或重新启动 DSH); 客户端代码 更改需要刷新页面.

存储时间可以是预设(永久失效連結/30d/90d/1y/5y/10y)或任何 按天数、月份或年份计算。 收费跟链子一样 `RequiredFee`数字 : 三十六年后的任何任期均需缴纳 永久价格而不是永远增长.

取消上传打开带有退款分解的确认对话框 (支出、注销率、扣付补偿、终止服务费、数额) 在签名前从链上读取.

状态读取为缓存: 主机的答案来自 `<dataDir>/status-cache.json` 财务报告和审定财务报表 刷新背景中的链条( 一个 15 s 窗口), 面板保留自己的 `localStorage` 复制后卡片会在第一个请求返回前制作 .

代理密钥已存储 **在 PIN 下加密**,从清晰的文字中选择: 从PIN中获取了AES-256-GCM密钥,解密后密钥只存在于记忆中, 和面板按要求或之后锁定 `lockIdleMinutes` 不活动 (默认60,预设或任何值从0到10080分). 插件行重装 在进程存在时保留解锁。 A 类 已持有平面键的配置文件被标记并重新封存.

Agent 密钥和存储默认在插件中配置, 绝不 全局设置对话框中:

-   **Falari 数据面板 — 设置标签** ——总是可用的,无论插件 页面使.
-   **插件 — Falari 数据** - 捆绑的页面卡,或行 **配置** 控制,由 `plugins.bundle.config` 编号 : `plugins.row.config` 插槽 . 两者都可能在安装后使用浏览器刷新后出现.

## 配置

该行接受可选 `config` 块( 显示默认值) 。 将覆盖置入 配置补丁 :

```yaml
- id: falari-harness
  name: '@falari/harness'
  config:
    network: testnet            # testnet | mainnet (mainnet is not live yet)
    defaultPrivacy: public      # public | private
    defaultDuration: permanent  # permanent | 30d | 90d | 1y | 5y | 10y
    maxFileSizeBytes: 2147483648
    allowUploadOutsideWorkspace: false
    allowRemoteRoutes: false     # keep the panel routes on loopback only
    # gatewayUrl / retrievalUrl / explorerUrl override the network presets
    # timeoutMs defaults to 60000
    # dataDir defaults to <DSH_PROFILE_DIR>/falari-harness
```

代理密钥是 **没有** 配置 : 它住在 DSH 证书存储器中 记录 `falari-harness/agent-key`。 。 。 .

## 工具

| 工具 | 目的 |
| --- | --- |
| `falari_status` | 关键状态、等级、津贴、余额、矿工`refresh: true` 绕过缓存) |
| `falari_quote` | 上传价格( E)`path` 或者说 `size_bytes`)和检查预算 |
| `falari_upload` | 队列工作空间文件; `wait: true` 最多两分钟 |
| `falari_task` | 读取一个任务或最近列表 |
| `falari_list` | 这个帐户的初衷是最新的 |
| `falari_download` | 下载一个意图, 验证根, 私下解密 |

插件配置页面通过配置文件将这些值写回 配置编辑器,所以保存重新启动插件行.

代理上传仅限于会话工作目录,除非 `allowUploadOutsideWorkspace` 已启用。 用户在面板中选择的文件是 不受那个警卫的支配.

## 构建

主机将未出版的Falari SDK(`@falari/agent`)和 预编译软件包 `lib/falari-sdk.cjs`因此,安装捆绑不需要 他们的 npm 包 :

```sh
npm run build:sdk
```

拖出新车后运行此功能 `sdk/sdk-agent-ts`。 。 。 .

## 仓库

项目位于此目录中, 并作为 npm 软件包发布 `@falari/harness`; 周围的 Falari 检出只托管它构建的 SDK 和它跟随的文件。 项目之家: [https://falari.xyz (英语)](https://falari.xyz/)。 。 。 .

软件包名称 `@falari/harness` 是捆绑的身份 : `package.json` `name`, (中文(简体) ), 装入器行入 `cordis.patch.yml` 编辑 `id` 转至 `window.__ModuleLoader__.load` 必须保持平等,因为客户模块 扫描与装入器规格匹配已安装的显示名称.

`package.json` 出口 `.`, (中文(简体) ), `./client`, (中文(简体) ), `./cordis.patch.yml`, (中文(简体) ), `./package.json`, (中文(简体) ), `./locale/*.json` 财务报告和审定财务报表 `./icon`,和船舶 `index.js`, (中文(简体) ), `client.js`, (中文(简体) ), `lib/**`,则 补丁, 地方, 图标, README, ChangGELOG 和 LICENSE. 其他的都一样 (单位:千美元)`scripts/`, (中文(简体) ), `docs/`)是只存储器. `npm pack --dry-run` 列出18个文件.

发布是将此目录推向新寄存器; 其它不包含 明显需要改变.

## 版式

```text
clients/harness/
├── .gitignore
├── CHANGELOG.md          # release notes per milestone
├── LICENSE               # MIT, © 2026 falari_labs
├── README.md
├── package.json          # dsh.bundle + dsh.client manifest, exports, files
├── cordis.patch.yml      # inserts the falari-harness row
├── icon.png
├── index.js              # Host entry: wiring
├── client.js             # Web client half: panel, tabs, settings
├── lib/
│   ├── config.js         # row config resolution + edit validation
│   ├── errors.js         # shared error shape and mapping
│   ├── routes.js         # /api/falari-harness/* (same-origin, loopback)
│   ├── sdk.js            # loads the bundled SDK
│   ├── service.js        # FalariDataService: key, quote, budget, uploads, downloads
│   ├── tools.js          # six falari_* Agent tools
│   └── falari-sdk.cjs    # generated by npm run build:sdk (committed on purpose)
├── scripts/
│   ├── build-sdk.sh      # esbuild bundle of @falari/agent + precompiles
│   ├── unit-host.mjs     # pure-helper unit tests
│   ├── smoke-host.mjs    # HTTP route smoke tests against a patched SDK
│   └── smoke-client.mjs  # client.js render smoke test in a VM
├── locale/{en,zh}.json   # plugin metadata
└── docs/
    ├── plan.md           # v0.1 design and milestone log
    └── test-plan.md      # automated, live and panel checks
```

## 测试

```sh
npm test            # unit + Host routes + client render, all offline
```

| 套间 | 它会做什么 |
| --- | --- |
| `scripts/unit-host.mjs` | 配置验证/ 默认、 名称消毒、 状态和错误映射 |
| `scripts/smoke-host.mjs` | 补丁 SDK 客户端并驱动每个 HTTP 路由 : 状态、 密钥、 引文、 原始上传、 任务动作、 意图、 下载、 配置保存、 来源和回路保护 |
| `scripts/smoke-client.mjs` | 负载 `client.js` 在 VM 中,服务器将三个插槽组件 |

83张支票今天通过。 手动和现场测试网台阶进入 [文件/测试计划](https://npmcn.com/package/%40falari/harness/docs/test-plan.md)。 。 。 .

## 警卫

-   代理密钥是持有上传权限的无记名证书. 它只储存在 主机证书存储; 浏览器从未接收或坚持原始 `far_...` 字符串, 没有路径返回它 .
-   上传路由只接受同源请求; 跨源写入为 以403拒绝.
-   路由只回答回回转端口, 除非 `allowRemoteRoutes` 启用,所以 绑定在较宽地址的收听器不能用于更改密钥或支付 上传.
-   浏览器在插件数据目录下将流上传到 0600 临时文件 并一旦任务完成或被取消就删除; 超过24个的文件 启动时会扫描小时.
-   面板显示一个私有文件上传完成后的数据密钥, 因为 失去它使得密码无法恢复.
-   下载只写在配置内 `downloadDir` (默认) `<dataDir>/downloads`(a) 减少 `out_path` 逃避它将被拒绝 已存在的文件名增益a `(1)` 后缀而不是被覆盖.

## 常见问题

### @falari/harness 是什么？

Falari Data客户端 DeepSeek Harness:代理密钥状态,数据上传和下载\.

### 如何安装 @falari/harness？

在项目目录运行 npm install @falari/harness，或使用 pnpm add / yarn add / bun add。

### @falari/harness 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/falari\_\_harness 是否存在。

### @falari/harness 支持 ESM 还是 CommonJS？

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

### @falari/harness 需要什么版本的 Node\.js？

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

### @falari/harness 可以商用吗？

@falari/harness 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @falari/harness 的下载量有多少？

根据 npm 官方下载统计，@falari/harness 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,160 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @falari/harness 还在维护吗？

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