85. 文档-代码差距补全 (Documentation-Code Gap Fill v1.0)

状态: ✅ 已完成日期: 2026-04-12 完成日期: 2026-04-12 作用范围: desktop-app-vue/src/main/, packages/cli/关联文档: 53. 零知识证明引擎 · 56. 隐私计算框架 · 23. Nostr桥接系统 · 58. 低代码平台

1. 概述

对 84 个设计文档与实际代码进行全面比对后，发现绝大部分功能（95%+）已完整实现。本模块记录剩余 7 处需要补全的差距项，按优先级逐项实施。

1.1 差距来源分析

类别	数量	说明
外部依赖未接入	2	Nostr WebSocket、TTS 模型下载
CLI 命令占位符	1	`lowcode deploy`
核心算法简化	2	ZKP mock 证明、隐私计算 mock 聚合
功能逻辑缺失	1	协作引擎好友可见性
存储验证缺失	1	Filecoin 存储证明

1.2 非目标

不重构已有架构 — 所有修改在现有文件内完成
不引入新的外部依赖 — 仅使用已有的 ws、crypto 等模块
不改变 IPC 通道定义 — 现有 IPC 接口保持不变

2. 任务清单

2.1 P1: Nostr Bridge — 真实 WebSocket 连接

问题: nostr-bridge.js:217-227 使用 mock WebSocket 对象，publishEvent() 的 ws.send() 为注释 stub，事件实际未发送到 relay。

文件: desktop-app-vue/src/main/social/nostr-bridge.js (506 行, ESM)

方案:

javascript

// 替换 mock 对象为真实 WebSocket
import WebSocket from "ws";

async connectRelay(url) {
  // ...
  const ws = new WebSocket(url);

  ws.on("open", () => {
    relay.status = "connected";
    this.emit("relay:connected", { url });
  });

  ws.on("message", (data) => {
    this._handleRelayMessage(url, data);
  });

  ws.on("close", () => {
    relay.status = "disconnected";
    this.emit("relay:disconnected", { url });
    this._scheduleReconnect(url);
  });

  ws.on("error", (err) => {
    relay.status = "error";
    logger.error(`[NostrBridge] WebSocket error for ${url}:`, err.message);
  });

  relay.ws = ws;
}

新增方法:

_handleRelayMessage(url, data) — 处理 NIP-01 消息: ["EVENT", ...], ["EOSE", ...], ["NOTICE", ...], ["OK", ...]
_scheduleReconnect(url) — 指数退避重连 (1s → 2s → 4s → ... → 60s max)

测试: tests/unit/social/nostr-bridge-ws.test.js

2.2 P1: Low-Code Deploy 命令

问题: lowcode.js:307-319 是占位符，输出 "coming in a future release"。

文件: packages/cli/src/commands/lowcode.js + packages/cli/src/lib/app-builder.js

方案:

javascript

// app-builder.js 新增
export function deployApp(db, appId, options = {}) {
  const app = getApp(db, appId);
  if (!app) throw new Error(`App ${appId} not found`);
  if (app.status !== "published") throw new Error(`App must be published first`);

  const outputDir = options.outputDir || path.join(configDir, "deploys", appId);
  // 生成 index.html + app.js + style.css
  const files = generateStaticBundle(app, components, dataSources);
  // 写入文件
  for (const [name, content] of Object.entries(files)) {
    fs.writeFileSync(path.join(outputDir, name), content, "utf-8");
  }
  // 更新状态
  db.prepare("UPDATE lowcode_apps SET status = 'deployed' WHERE id = ?").run(appId);
  return { appId, outputDir, files: Object.keys(files), deployedAt: new Date().toISOString() };
}

测试: __tests__/unit/lowcode-deploy.test.js

2.3 P2: ZKP 引擎 — 真实证明逻辑

问题: zkp-engine.js 使用 mock-a-/mock-b-/mock-c- 占位，verifyProof() 恒返回 true。

文件: desktop-app-vue/src/main/crypto/zkp-engine.js (192 行)

方案: 在有限域 F_p (p = 大素数) 上实现简化 R1CS + Groth16 风格证明:

compileCircuit(): 将约束定义转换为 R1CS 矩阵 (A, B, C)
generateProof():
- 从私有输入 + 公开输入计算 witness 向量
- 使用 witness 和 R1CS 生成证明元素 { pi_a, pi_b, pi_c }
- 证明 = HMAC-SHA256 绑定的承诺值（简化版，非椭圆曲线配对）
verifyProof():
- 重新计算公开输入的承诺
- 验证 pi_c == HMAC(pi_a || pi_b || public_inputs, verification_key)

测试: 扩展现有测试，验证"生成 → 验证"闭环、篡改检测

2.4 P2: 隐私计算 — 联邦聚合 & MPC & 差分隐私

问题: privacy-computing.js 的三个核心方法返回硬编码结果。

文件: desktop-app-vue/src/main/crypto/privacy-computing.js (175 行)

方案:

联邦学习 (FedAvg):
- 新增 submitUpdate(modelId, participantId, { gradients, sampleCount })
- 当所有参与者提交后自动执行加权平均聚合
- 轮次递进: currentRound++
MPC (Shamir 秘密共享):
- mpcCompute() 实现真实 Shamir 分片: 在 F_p 上构造 (t, n) 多项式
- 支持 sum/average/max/min 操作
- 从任意 t 个 shares 重构秘密
差分隐私 (Laplace 噪声):
- dpPublish() 对数值数据添加 Laplace(0, sensitivity/epsilon) 噪声
- 追踪累积隐私预算 (sequential composition)

测试: 验证聚合正确性、秘密重构精度、噪声统计特性

2.5 P2: 协作引擎 — 好友可见性

问题: collab-engine.js:650 对 FRIENDS 可见性使用邀请检查作为 fallback。

文件: desktop-app-vue/src/main/social/collab-engine.js

方案: 查询 social_contacts 表检查好友关系:

javascript

if (document.visibility === Visibility.FRIENDS) {
  const ownerDid = document.owner_did;
  const friend = db.prepare(
    `SELECT id FROM social_contacts WHERE owner_did = ? AND contact_did = ? AND type = 'friend'`
  ).get(ownerDid, userDid);
  return !!friend;
}

2.6 P3: Filecoin 存储 — 证明验证 & 续约

问题: filecoin-storage.js (141 行) 仅有交易创建，缺少存储证明验证。

文件: desktop-app-vue/src/main/ipfs/filecoin-storage.js

新增方法:

verifyStorageProof(dealId, proof) — 验证 PoRep/PoSt 证明结构，更新 verified 字段
renewDeal(dealId, additionalEpochs) — 延长交易期限，更新 expires_at
listDeals(filters) — 按 status/CID/miner 过滤查询

2.7 P3: TTS 模型自动下载

问题: local-tts-client.js 要求用户手动下载 Piper 模型。

文件: desktop-app-vue/src/main/speech/local-tts-client.js

新增方法:

downloadModel(modelName, options) — 通过 Node.js https 模块从 GitHub Releases 下载
- 下载 .onnx 模型文件 + .json 配置文件
- 通过事件 download:progress 报告进度
- 保存到 modelsDir
- 支持断点续传（检查文件大小）

3. 执行顺序

序号	任务	优先级	预估规模	文件
1	Nostr WebSocket	P1	~80 行 + 测试	`social/nostr-bridge.js`
2	Lowcode Deploy	P1	~60 行 + 测试	`commands/lowcode.js`, `lib/app-builder.js`
3	ZKP 真实证明	P2	~120 行 + 测试	`crypto/zkp-engine.js`
4	隐私计算算法	P2	~100 行 + 测试	`crypto/privacy-computing.js`
5	好友可见性	P2	~10 行	`social/collab-engine.js`
6	Filecoin 证明	P3	~60 行 + 测试	`ipfs/filecoin-storage.js`
7	TTS 下载	P3	~80 行 + 测试	`speech/local-tts-client.js`

4. 验证方法

每个任务完成后运行对应测试文件:

bash

# Task 1
cd desktop-app-vue && npx vitest run tests/unit/social/nostr-bridge-ws

# Task 2
cd packages/cli && npx vitest run __tests__/unit/lowcode-deploy

# Task 3
cd desktop-app-vue && npx vitest run tests/unit/crypto/zkp-engine

# Task 4
cd desktop-app-vue && npx vitest run tests/unit/crypto/privacy-computing

# Task 5
cd desktop-app-vue && npx vitest run tests/unit/social/collab-engine

# Task 6
cd desktop-app-vue && npx vitest run tests/unit/ipfs/filecoin-storage

# Task 7
cd desktop-app-vue && npx vitest run src/main/speech/__tests__/local-tts-client

5. 实施结果

全部 7 项任务已完成 (2026-04-12)

5.1 代码变更汇总

任务	修改文件	新增测试文件	新增测试数
1. Nostr WebSocket	`social/nostr-bridge.js`	`tests/unit/social/nostr-bridge-ws.test.js`	26
2. Lowcode Deploy	`commands/lowcode.js`, `lib/app-builder.js`	`__tests__/unit/app-builder.test.js` (扩展)	10
3. ZKP 真实证明	`crypto/zkp-engine.js` (重写)	`tests/unit/crypto/zkp-engine.test.js`	27
4. 隐私计算	`crypto/privacy-computing.js` (重写)	`tests/unit/crypto/privacy-computing.test.js`	42
5. 好友可见性	`social/collab-engine.js`	— (现有 56 测试通过)	0
6. Filecoin 证明	`ipfs/filecoin-storage.js`	`tests/unit/ipfs/filecoin-storage.test.js` (扩展)	20
7. TTS 下载	`speech/local-tts-client.js`	`src/main/speech/__tests__/local-tts-client.test.js`	14
集成测试	—	`tests/integration/crypto-privacy-integration.test.js`	7
集成测试	—	`tests/integration/filecoin-nostr-integration.test.js`	4
集成测试	—	`__tests__/integration/lowcode-deploy.test.js`	6
E2E 测试	—	`__tests__/e2e/gap-fill-commands.test.js`	10
合计	9 个文件	10 个测试文件	166 新增测试

5.2 关键技术实现

ZKP: BN254 有限域 (256-bit) 上的 R1CS 约束系统 + Fiat-Shamir 启发式证明
隐私计算: Shamir 秘密共享 (128-bit 素数域) + Lagrange 插值重构 + Laplace 噪声机制
联邦学习: FedAvg 加权梯度聚合 + 轮次管理 + 自动聚合触发
Nostr: 真实 WebSocket 连接 + NIP-01 消息处理 + 指数退避重连
Filecoin: PoRep/PoSt 证明验证 + SHA-256 承诺检查 + 交易续约
TTS: HTTPS 下载 + 重定向跟随 + 事件进度通知 + _deps 注入可测试性

5.3 验证通过

单元测试:  139 新增 (7 个文件)
集成测试:   17 新增 (3 个文件)
E2E 测试:   10 新增 (1 个文件)
回归测试:  534 测试全部通过 (desktop-app-vue crypto/ipfs/social/speech)
CLI 测试:   48 测试全部通过 (app-builder unit + integration)

85. 文档-代码差距补全 (Documentation-Code Gap Fill v1.0) ​

1. 概述 ​

1.1 差距来源分析 ​

1.2 非目标 ​

2. 任务清单 ​

2.1 P1: Nostr Bridge — 真实 WebSocket 连接 ​

2.2 P1: Low-Code Deploy 命令 ​

2.3 P2: ZKP 引擎 — 真实证明逻辑 ​

2.4 P2: 隐私计算 — 联邦聚合 & MPC & 差分隐私 ​

2.5 P2: 协作引擎 — 好友可见性 ​

2.6 P3: Filecoin 存储 — 证明验证 & 续约 ​

2.7 P3: TTS 模型自动下载 ​

3. 执行顺序 ​

4. 验证方法 ​

5. 实施结果 ​

5.1 代码变更汇总 ​

5.2 关键技术实现 ​

5.3 验证通过 ​

85. 文档-代码差距补全 (Documentation-Code Gap Fill v1.0)

1. 概述

1.1 差距来源分析

1.2 非目标

2. 任务清单

2.1 P1: Nostr Bridge — 真实 WebSocket 连接

2.2 P1: Low-Code Deploy 命令

2.3 P2: ZKP 引擎 — 真实证明逻辑

2.4 P2: 隐私计算 — 联邦聚合 & MPC & 差分隐私

2.5 P2: 协作引擎 — 好友可见性

2.6 P3: Filecoin 存储 — 证明验证 & 续约

2.7 P3: TTS 模型自动下载

3. 执行顺序

4. 验证方法

5. 实施结果

5.1 代码变更汇总

5.2 关键技术实现

5.3 验证通过