chyuovo/WorthPath
0
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: simplify agent permissions and require current ZIP backups

Browse Source
This commit is contained in:
陈煜 committed 2026-10-04 01:46:47 +08:00
1 parent efc2c7c734
commit 91c489513a
51 files changed
+1680 -1270
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+2 -2
View File
@@ -41,7 +41,7 @@ pnpm check:staged # git add 后，提交前检查本地凭证和禁止提交的
设计见 [数据模型与结构](docs/architecture.md)，已验证范围与后续工作见 [首版验收](docs/acceptance.md)。生产需要 HTTPS、COOKIE_SECURE=true、WEB_ORIGIN 为准确站点地址；前端构建由反向代理托管并代理 /api。API 生产启动：在 `apps/api` 中执行 `node dist/main.js`。生产认证限速需迁移到共享存储，数据库用户需最小权限，部署与运行监控尚未配置。
备份下载为 ZIP：manifest、settings、currencies、accounts、assets、debts、history、links、rates、icons、transfers 各一个 JSON 文件，包含隐藏项目及全部历史，不含密码或会话凭据。导入先上传并预览，再确认追加；旧 JSON 备份继续兼容。不限制项目、历史、关联或汇率条数；上传文件最大 512 MB，ZIP 解压总计最大 1 GB，用于保护服务器资源。
备份下载为 ZIP：manifest、settings、currencies、accounts、assets、debts、history、links、rates、icons、transfers 各一个 JSON 文件，包含隐藏项目及全部历史，不含密码或会话凭据。导入先上传并预览，再确认追加；仅接受当前 ZIP v9，所有 JSON 备份和旧 ZIP 均不支持。不限制项目、历史、关联或汇率条数；上传文件最大 512 MB，ZIP 解压总计最大 1 GB，用于保护服务器资源。
内网穿透临时测试：本地 `apps/api/.env` 可设置 `WEB_ORIGIN=*` 并重启 API，允许来自任意 HTTP/HTTPS 站点的浏览器写入请求，仍需登录身份并校验数据归属。缺失或无效 Origin 仍拒绝；`NODE_ENV=production` 禁止此通配符。测试结束后恢复准确的站点地址。
@@ -55,7 +55,7 @@ ZIP 格式 v5 增加 transfers.json（转账双方、金额、手续费及配对
账户页面和账户详情提供“账户间转账”，详情自动选择当前账户。双方余额和历史在同一数据库事务中更新；正手续费额外扣除，负手续费表示优惠（绝对值不超过本金），同币种到账金额等于转出金额，跨币种填写实际到账金额。转账不调用银行或支付平台，不执行真实资金划转。重复提交使用请求 ID 防止重复记账，并发写冲突有限重试。转账时间不能早于双方最新余额；后续余额调整不能插入已有配对操作之前。
债务分为借入（应付负债）和借出（应收资产），支持借入到账、借出付款、收回应收和偿还应付。账户与债务在同一事务中记账并自动关联；双方详情和往来记录可互相导航。已有债务可录入剩余余额，新发生借贷可先建零余额债务再使用联动操作。ZIP v6 保留操作类型，兼容旧 v3/v4/v5 ZIP 和 v1/v2 JSON。
债务分为借入（应付负债）和借出（应收资产），支持借入到账、借出付款、收回应收和偿还应付。账户与债务在同一事务中记账并自动关联；双方详情和往来记录可互相导航。已有债务可录入剩余余额，新发生借贷可先建零余额债务再使用联动操作。当前 ZIP v9 保留操作类型，不保留任何旧备份兼容。
支持简中、English、繁中，在登录页或顶部切换，语言保存在当前浏览器。用户名称和备注保留原文。账户/资产/债务按页查询当前余额，历史和往来使用最多 100 条的游标分页；趋势默认最近 90 天，支持日、周、月。查询实现、迁移步骤、实测性能和验证边界见 [性能与联动验收](docs/performance.md)。
apps/api/prisma/migrations/20261004090000_agent_permanent_tokens/migration.sql
+1
View File
@@ -0,0 +1 @@
ALTER TABLE `AgentGrant` MODIFY `expiresAt` DATETIME(3) NULL COMMENT '访问令牌到期时间，UTC；空表示可撤销的永久个人令牌';
apps/api/prisma/migrations/20261004103000_agent_connection_permissions/migration.sql
+3
View File
@@ -0,0 +1,3 @@
-- Metadata only. Preserve existing policy rows; the application no longer reads them.
ALTER TABLE `AgentPolicy` COMMENT = '已停用的历史 Agent 策略数据，保留原数据但不参与权限判定';
ALTER TABLE `AgentGrant` MODIFY `scopes` JSON NOT NULL COMMENT '权限列表：read、draft 或 write；隐藏账户附加权限 hidden_read、hidden_write';
apps/api/prisma/schema.prisma
+4 -4
View File
@@ -68,7 +68,7 @@ model AgentCall {
@@index([userId,createdAt])
}
/// 用户的 Agent 写入策略
/// 已停用的历史 Agent 策略数据，保留原数据但不参与权限判定
model AgentPolicy {
/// 所属用户标识，用于数据隔离
userId String @id @db.Char(36)
@@ -117,7 +117,7 @@ model AgentGrant {
clientId String? @db.Char(36)
/// 用户可见连接名称
name String @db.VarChar(100)
/// 权限列表：read、draft、write、sensitive
/// 权限列表：read、draft 或 write；隐藏账户附加权限 hidden_read、hidden_write
scopes Json
/// 令牌适用的规范 MCP 资源地址
resource String @db.VarChar(500)
@@ -125,8 +125,8 @@ model AgentGrant {
accessDigest String @unique @db.Char(64)
/// 刷新令牌 SHA-256 摘要，使用后轮换
refreshDigest String? @unique @db.Char(64)
/// 到期时间，UTC
expiresAt DateTime
/// 访问令牌到期时间，UTC；空表示可撤销的永久个人令牌
expiresAt DateTime?
/// 刷新授权到期时间，UTC
refreshExpiresAt DateTime?
/// 撤销时间，UTC；空表示未撤销
apps/api/src/backup-format.ts
+2
View File
@@ -0,0 +1,2 @@
// Only the current ZIP container format is supported.
export const BACKUP_ZIP_VERSION = 9;
apps/api/src/backup.ts
+100 -109
View File
@@ -1,5 +1,6 @@
import { BACKUP_ZIP_VERSION } from './backup-format';
import { Injectable } from '@nestjs/common';
import { metalConfig, metalPriceInput } from './metals';
import { metalConfig, metalPriceInput, storedMetalPurity } from './metals';
import { scheduleInput } from './schedules';
import { movementDeltas } from './movement';
import { pairedReasons } from './validation';
@@ -21,7 +22,7 @@ import { Response } from 'express';
import { FileInterceptor } from '@nestjs/platform-express';
import { diskStorage } from 'multer';
import { tmpdir } from 'node:os';
import { unlink, open, readFile, readdir, stat } from 'node:fs/promises';
import { unlink, readdir, stat } from 'node:fs/promises';
import { join } from 'node:path';
import { randomUUID } from 'node:crypto';
import { archiveBackup, readBackupZip, MAX_UPLOAD_BYTES } from './zip';
@@ -56,22 +57,31 @@ const timestamp = z.iso
);
const record = positionMeta
.extend({
metalType: z.enum(['gold', 'silver']).nullable().optional(),
metalGrams: amount.nullable().optional(),
metalCostPerGram: metalConfig.shape.metalCostPerGram,
metalPurity: metalConfig.shape.metalPurity.optional(),
autoValuation: z.boolean().optional(),
groupName: z.string().max(60),
included: z.boolean(),
iconId: z.string().uuid().nullable(),
notes: z.string().max(2000),
archived: z.boolean(),
hidden: z.boolean(),
metalType: z.enum(['gold', 'silver']).nullable(),
metalGrams: amount.nullable(),
metalCostPerGram: metalConfig.shape.metalCostPerGram.nonoptional(),
metalPurity: storedMetalPurity,
autoValuation: z.boolean(),
kind: z.enum(['account', 'asset', 'debt']),
side: z.enum(['asset', 'liability']),
currency,
id: z.string().uuid(),
importedFromId: z.string().uuid().nullable().optional(),
importedFromId: z.string().uuid().nullable(),
createdAt: timestamp,
updatedAt: timestamp,
revisions: z.array(
revisionInput.extend({
id: z.string().uuid(),
sequence: z.number().int().positive().max(2147483647).optional(),
notes: z.string().max(2000),
reason: revisionInput.shape.reason.unwrap(),
date: revisionInput.shape.date.refine((s) => s.length === 16, '备份业务时间必须精确到分钟'),
sequence: z.number().int().positive().max(2147483647),
createdAt: timestamp,
updatedAt: timestamp,
}),
@@ -81,68 +91,65 @@ const record = positionMeta
const backupSchema = z
.object({
format: z.literal('worthpath'),
version: z.union([z.literal(1), z.literal(2)]),
version: z.literal(BACKUP_ZIP_VERSION, { error: '备份数据必须来自当前 ZIP v9 格式' }),
exportedAt: z.iso.datetime(),
baseCurrency: currency,
currencies: z.array(currency).max(10),
preferences: z
.object({
showSidebar: z.boolean().optional(),
hiddenMenus: hiddenMenus.optional(),
accountGroupOrder: accountGroupOrder.optional(),
sessionHours: sessionHours.optional(),
requireHiddenPassword: z.boolean().optional(),
overviewCards: overviewCards.optional(),
includeIndependentAssets: z.boolean().optional(),
showNotes: z.boolean().optional(),
hiddenMenus: hiddenMenus,
accountGroupOrder: accountGroupOrder,
sessionHours: sessionHours,
requireHiddenPassword: z.boolean(),
overviewCards: overviewCards,
includeIndependentAssets: z.boolean(),
showNotes: z.boolean(),
idleMinutes: z.number().int().min(0).max(1440),
})
.strict()
.optional(),
icons: z
.array(
z
.object({
id: z.string().uuid(),
name: iconName,
shared: z.boolean(),
image: z.string().max(3 * 1024 * 1024),
hash: z.string().regex(/^[a-f0-9]{64}$/),
})
.strict(),
)
.optional(),
transfers: z
.array(
transferInput.safeExtend({
.strict(),
icons: z.array(
z
.object({
id: z.string().uuid(),
importedFromId: z.string().uuid().nullable().optional(),
sourceRevisionId: z.string().uuid(),
targetRevisionId: z.string().uuid(),
sourceCurrency: currency,
targetCurrency: currency,
createdAt: timestamp,
}),
)
.optional(),
schedules: z
.array(
scheduleInput.safeExtend({
id: z.string().uuid(),
importedFromId: z.string().uuid().nullable().optional(),
enabled: z.boolean(),
completed: z.boolean().default(false),
}),
)
.optional(),
metalPrices: z
.array(
metalPriceInput.extend({
source: z.enum(['manual', 'goldapi']),
quotedAt: timestamp,
}),
)
.optional(),
name: iconName,
shared: z.boolean(),
image: z.string().max(3 * 1024 * 1024),
hash: z.string().regex(/^[a-f0-9]{64}$/),
})
.strict(),
),
transfers: z.array(
transferInput.safeExtend({
id: z.string().uuid(),
importedFromId: z.string().uuid().nullable(),
operation: transferInput.shape.operation.unwrap(),
fee: transferInput.shape.fee.unwrap(),
notes: z.string().max(2000),
date: transferInput.shape.date.refine((s) => s.length === 16),
sourceRevisionId: z.string().uuid(),
targetRevisionId: z.string().uuid(),
sourceCurrency: currency,
targetCurrency: currency,
createdAt: timestamp,
}),
),
schedules: z.array(
scheduleInput.safeExtend({
id: z.string().uuid(),
importedFromId: z.string().uuid().nullable(),
enabled: z.boolean(),
completed: z.boolean(),
targetId: z.string().uuid().nullable(),
received: amount,
notes: z.string().max(2000),
}),
),
metalPrices: z.array(
metalPriceInput.extend({
source: z.enum(['manual', 'goldapi']),
quotedAt: timestamp,
}),
),
positions: z.array(record),
links: z.array(z.object({ sourceId: z.string().uuid(), targetId: z.string().uuid() }).strict()),
rates: z.array(rateInput.safeExtend({ source: z.enum(['manual', 'frankfurter']) })),
@@ -155,11 +162,11 @@ export function validateBackup(raw: unknown) {
if (ids.size !== b.positions.length) throw new BadRequestException('重复项目 ID');
const origins = b.positions.map((p) => p.importedFromId || p.id);
if (new Set(origins).size !== origins.length) throw new BadRequestException('备份内包含重复项目');
const quoteKeys = (b.metalPrices || []).map((q) => q.metalType + q.currency + q.date);
const quoteKeys = b.metalPrices.map((q) => q.metalType + q.currency + q.date);
if (new Set(quoteKeys).size !== quoteKeys.length) throw new BadRequestException('重复贵金属报价');
const iconIds = new Set((b.icons || []).map((i) => i.id));
const iconIds = new Set(b.icons.map((i) => i.id));
if (
iconIds.size !== (b.icons || []).length ||
iconIds.size !== b.icons.length ||
b.positions.some((p) => p.iconId && !iconIds.has(p.iconId))
)
throw new BadRequestException('图标关联无效');
@@ -172,8 +179,7 @@ export function validateBackup(raw: unknown) {
metalType: p.metalType,
metalGrams: p.metalGrams,
metalCostPerGram: p.metalCostPerGram,
metalPurity: p.metalPurity || '1',
autoValuation: p.autoValuation || false,
autoValuation: p.autoValuation,
});
}
positionInput.parse({
@@ -203,7 +209,7 @@ export function validateBackup(raw: unknown) {
if (p.kind !== 'account' && p.revisions.some((r) => r.amount.startsWith('-')))
throw new BadRequestException('仅账户支持负余额');
const planIds = new Set<string>();
for (const plan of b.schedules || []) {
for (const plan of b.schedules) {
const source = ids.get(plan.sourceId),
target = plan.targetId ? ids.get(plan.targetId) : null;
if (
@@ -222,7 +228,7 @@ export function validateBackup(raw: unknown) {
}
const transferIds = new Set<string>(),
usedRevisions = new Set<string>();
for (const t of b.transfers || []) {
for (const t of b.transfers) {
const source = ids.get(t.sourceId),
target = ids.get(t.targetId);
const origin = t.importedFromId || t.id;
@@ -328,16 +334,7 @@ export class BackupBusinessService implements OnModuleDestroy, OnModuleInit {
await this.prune(true);
}
private async uploadedData(path: string) {
const handle = await open(path, 'r');
const prefix = Buffer.alloc(2);
try {
await handle.read(prefix, 0, 2, 0);
} finally {
await handle.close();
}
return prefix.toString() === 'PK'
? readBackupZip(path)
: JSON.parse((await readFile(path, 'utf8')).replace(/^\uFEFF/, ''));
return readBackupZip(path);
}
constructor(private db: Database) {}
async snapshot(userId: string) {
@@ -429,7 +426,7 @@ export class BackupBusinessService implements OnModuleDestroy, OnModuleInit {
const schedules = await client.schedule.findMany({ where: { userId } });
return backupSchema.parse({
format: 'worthpath',
version: 2,
version: BACKUP_ZIP_VERSION,
exportedAt: new Date().toISOString(),
baseCurrency: user.baseCurrency,
preferences: {
@@ -569,13 +566,13 @@ export class BackupBusinessService implements OnModuleDestroy, OnModuleInit {
data.rates.sort((a, b) =>
(a.currency + a.baseCurrency + a.date).localeCompare(b.currency + b.baseCurrency + b.date),
);
data.metalPrices?.sort((a, b) =>
data.metalPrices.sort((a, b) =>
(a.metalType + a.currency + a.date).localeCompare(b.metalType + b.currency + b.date),
);
data.currencies.sort();
data.transfers?.sort((a, b) => a.id.localeCompare(b.id));
data.schedules?.sort((a, b) => a.id.localeCompare(b.id));
data.icons?.sort((a, b) => a.id.localeCompare(b.id));
data.transfers.sort((a, b) => a.id.localeCompare(b.id));
data.schedules.sort((a, b) => a.id.localeCompare(b.id));
data.icons.sort((a, b) => a.id.localeCompare(b.id));
return createHash('sha256').update(JSON.stringify(data)).digest('hex');
}
async clearStatus(r: UserRequest) {
@@ -611,15 +608,15 @@ export class BackupBusinessService implements OnModuleDestroy, OnModuleInit {
async preview(r: UserRequest, raw: unknown) {
const b = validateBackup(raw),
existing = await this.data(r.userId);
for (const i of b.icons || []) await validateStoredIcon(i.image, i.hash);
for (const i of b.icons) await validateStoredIcon(i.image, i.hash);
this.conflicts(b, existing);
return {
positions: b.positions.length,
revisions: b.positions.reduce((n, p) => n + p.revisions.length, 0),
rates: b.rates.length,
icons: (b.icons || []).length,
transfers: (b.transfers || []).length,
schedules: (b.schedules || []).length,
icons: b.icons.length,
transfers: b.transfers.length,
schedules: b.schedules.length,
baseCurrency: b.baseCurrency,
currentBaseCurrency: existing.baseCurrency,
message:
@@ -650,7 +647,7 @@ export class BackupBusinessService implements OnModuleDestroy, OnModuleInit {
.parse(raw),
b = validateBackup(backup);
const iconData = new Map<string, Buffer>();
for (const i of b.icons || []) iconData.set(i.id, await validateStoredIcon(i.image, i.hash));
for (const i of b.icons) iconData.set(i.id, await validateStoredIcon(i.image, i.hash));
return this.db.$transaction(
async (tx) => {
const ps = await tx.position.findMany({
@@ -671,7 +668,7 @@ export class BackupBusinessService implements OnModuleDestroy, OnModuleInit {
} as unknown as Backup;
this.conflicts(b, existing);
const iconMapping = new Map<string, string>();
for (const i of b.icons || []) {
for (const i of b.icons) {
const row = await tx.icon.upsert({
where: { ownerId_hash_shared: { ownerId: r.userId, hash: i.hash, shared: false } },
create: {
@@ -742,7 +739,7 @@ export class BackupBusinessService implements OnModuleDestroy, OnModuleInit {
});
originals.forEach((v, i) => revisionMapping.set(v.id, restored[i].id));
}
for (const q of b.metalPrices || []) {
for (const q of b.metalPrices) {
const key = {
userId: r.userId,
metalType: q.metalType,
@@ -759,7 +756,7 @@ export class BackupBusinessService implements OnModuleDestroy, OnModuleInit {
data: { ...key, price: q.price, source: q.source, quotedAt: new Date(q.quotedAt) },
});
}
for (const t of b.transfers || [])
for (const t of b.transfers)
await tx.transfer.create({
data: {
userId: r.userId,
@@ -779,7 +776,7 @@ export class BackupBusinessService implements OnModuleDestroy, OnModuleInit {
createdAt: new Date(t.createdAt),
},
});
for (const plan of b.schedules || []) {
for (const plan of b.schedules) {
const { id, importedFromId, ...v } = plan;
await tx.schedule.create({
data: {
@@ -814,17 +811,17 @@ export class BackupBusinessService implements OnModuleDestroy, OnModuleInit {
where: { id: r.userId },
data: {
baseCurrency: b.baseCurrency,
idleMinutes: b.preferences?.idleMinutes,
hiddenMenus: b.preferences?.hiddenMenus?.join(','),
showNotes: b.preferences?.showNotes,
accountGroupOrder: b.preferences?.accountGroupOrder,
sessionHours: b.preferences?.sessionHours,
requireHiddenPassword: b.preferences?.requireHiddenPassword,
overviewCards: b.preferences?.overviewCards,
includeIndependentAssets: b.preferences?.includeIndependentAssets,
idleMinutes: b.preferences.idleMinutes,
hiddenMenus: b.preferences.hiddenMenus.join(','),
showNotes: b.preferences.showNotes,
accountGroupOrder: b.preferences.accountGroupOrder,
sessionHours: b.preferences.sessionHours,
requireHiddenPassword: b.preferences.requireHiddenPassword,
overviewCards: b.preferences.overviewCards,
includeIndependentAssets: b.preferences.includeIndependentAssets,
},
});
if (!ps.length && !rs.length && b.preferences?.requireHiddenPassword !== undefined)
if (!ps.length && !rs.length)
await tx.session.updateMany({ where: { userId: r.userId }, data: { revealUntil: null } });
return { ok: true, positions: b.positions.length };
},
@@ -861,10 +858,4 @@ export class BackupController {
@Post('clear') async clear(@Req() r: UserRequest, @Body() raw: unknown) {
return this.service.clear(r, raw);
}
@Post('preview') async preview(@Req() r: UserRequest, @Body() raw: unknown) {
return this.service.preview(r, raw);
}
@Post('import') async restore(@Req() r: UserRequest, @Body() raw: unknown) {
return this.service.restore(r, raw);
}
}
apps/api/src/mcp/catalogue.ts
+8 -60
View File
@@ -6,9 +6,8 @@ import { TransfersBusinessService } from '../transfers';
import { SchedulesBusinessService, scheduleInput } from '../schedules';
import { CalendarBusinessService } from '../calendar';
import { SettingsBusinessService } from '../rates';
import { MetalsBusinessService, metalConfig, metalHoldingInput, metalPriceInput } from '../metals';
import { MetalsBusinessService, metalConfig, metalHoldingInput } from '../metals';
import { IconsBusinessService } from '../icons';
import { BackupBusinessService } from '../backup';
import {
positionInput,
positionMeta,
@@ -49,9 +48,8 @@ export type ToolDefinition = {
name: string;
description: string;
schema: z.ZodObject<any>;
scope: 'read' | 'write' | 'sensitive';
scope: 'read' | 'write';
destructive?: boolean;
web?: 'credentials' | 'reveal' | 'clear';
run?: (r: UserRequest, p: any) => Promise<unknown>;
};
@Injectable()
@@ -65,7 +63,6 @@ export class AgentCatalogue {
settings: SettingsBusinessService,
metals: MetalsBusinessService,
icons: IconsBusinessService,
backup: BackupBusinessService,
) {
const read = (
name: string,
@@ -282,13 +279,13 @@ export class AgentCatalogue {
),
write(
'settings_update',
'修改个人设置、本位币、分组排序、登录时长及纳入统计配置。隐私设置变更需网页确认。',
settingsInput,
'修改个人设置、本位币、分组排序、登录时长及纳入统计配置。安全设置仅在网站修改。',
settingsInput.safeExtend({
requireHiddenPassword: z.never().optional(),
sessionHours: z.never().optional(),
}),
(r, p) => settings.update(r, p, undefined as any),
),
write('rates_refresh', '重试公共日汇率更新，失败保留原币和历史汇率。', empty, (r) =>
settings.refresh(r),
),
write(
'metal_holding_create',
'按克数创建金银资产，无需市场价格；买入每克成本可选，缺少报价时待估值。日期为 UTC+8 业务时间。',
@@ -296,18 +293,9 @@ export class AgentCatalogue {
(r, p) => metals.create(r, p),
),
read('metals_prices', '最近 100 条金银每克报价和更新状态。', empty, (r) => metals.list(r)),
write('metals_refresh', '刷新贵金属报价并沿用现有自动估值规则。', empty, (r) =>
metals.refresh(r),
),
write(
'metal_price_set',
'设置指定日期、币种、品种每克价格；price 十进制字符串，可能触发自动估值历史。',
metalPriceInput,
(r, p) => metals.manual(r, p),
),
write(
'metal_configure',
'设置金银重量、纯度和自动估值，复用现有估值规则。',
'设置金银重量和自动估值，复用现有估值规则。',
z.object({ id, data: metalConfig }).strict(),
(r, p) => metals.configure(r, p.id, p.data),
),
@@ -328,46 +316,6 @@ export class AgentCatalogue {
.strict(),
(r, p) => icons.list(r, p.q, String(p.page)),
),
{
name: 'backup_import',
description:
'提交已上传备份的追加恢复。先 file_upload_request → 上传 → import_preview；强制网页展示影响并确认，事务失败不保留部分账目。',
schema: z.object({ token: id }).strict(),
scope: 'sensitive',
destructive: true,
run: (r, p) => backup.restoreUpload(r, p.token),
},
read(
'import_preview',
'预检已上传备份并显示追加影响、冲突和条数。',
z.object({ token: id }).strict(),
async (r, p) => (await backup.inspectUpload(r, p.token)).preview,
),
{
name: 'credentials_change_request',
description:
'发起账号或密码修改，返回网页入口。当前密码及新密码仅在网页输入，不传给 Agent。完成后 operation_get 查询结果。',
schema: empty,
scope: 'sensitive',
web: 'credentials',
},
{
name: 'hidden_unlock_request',
description:
'发起隐藏项目解锁。网页用户验证密码后本连接解锁 5 分钟；operation_get 查询结果。',
schema: empty,
scope: 'sensitive',
web: 'reveal',
},
{
name: 'data_clear_request',
description:
'发起清空本账号财务数据。网页须先下载当前备份、验证密码并输入“确定清空”，展示数量；账号保留。',
schema: empty,
scope: 'sensitive',
web: 'clear',
destructive: true,
},
];
}
get(name: string) {
apps/api/src/mcp/files.ts
+11 -49
View File
@@ -8,28 +8,20 @@ import {
} from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import { Request, Response, Express } from 'express';
import multer, { diskStorage, memoryStorage } from 'multer';
import { tmpdir } from 'node:os';
import { unlink } from 'node:fs/promises';
import multer, { memoryStorage } from 'multer';
import { AgentOAuth, urls } from './oauth';
import { UserRequest } from '../auth';
import { BackupBusinessService } from '../backup';
import { IconsBusinessService } from '../icons';
import { MAX_UPLOAD_BYTES } from '../zip';
import { Database } from '../database';
import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
type Ticket = {
userId: string;
grantId: string;
expires: number;
kind: 'backup' | 'icon' | 'download' | 'image';
snapshot?: string;
kind: 'icon' | 'image';
iconId?: string;
buffer?: Buffer;
name?: string;
preview?: unknown;
token?: string;
};
@Injectable()
export class AgentFiles implements OnModuleDestroy {
@@ -39,9 +31,7 @@ export class AgentFiles implements OnModuleDestroy {
}, 60000).unref();
constructor(
private oauth: AgentOAuth,
private backup: BackupBusinessService,
private icons: IconsBusinessService,
private db: Database,
) {}
onModuleDestroy() {
clearInterval(this.timer);
@@ -60,19 +50,15 @@ export class AgentFiles implements OnModuleDestroy {
kind,
iconId,
expires: Date.now() + 600000,
...(kind === 'download' ? { snapshot: await this.backup.snapshot(r.userId) } : {}),
});
return {
fileId: id,
url: new URL('/api/agent/files/' + id, urls().issuer).toString(),
method: kind === 'download' || kind === 'image' ? 'GET' : 'POST',
method: kind === 'image' ? 'GET' : 'POST',
headers: { Authorization: 'Bearer <your access token>' },
expiresAt: new Date(Date.now() + 600000).toISOString(),
maxBytes: kind === 'backup' ? MAX_UPLOAD_BYTES : 2 * 1024 * 1024,
format:
kind === 'backup'
? 'multipart/form-data; field file; WorthPath ZIP/JSON'
: 'multipart/form-data; field file; image',
maxBytes: 2 * 1024 * 1024,
format: kind === 'image' ? 'image/png' : 'multipart/form-data; field file; image',
};
}
private ticket(r: UserRequest, grantId: string, id: string) {
@@ -94,9 +80,7 @@ export class AgentFiles implements OnModuleDestroy {
const t = this.ticket(r, grantId, id);
return {
fileId: id,
uploaded: !!t.buffer || !!t.token,
token: t.token,
preview: t.preview,
uploaded: !!t.buffer,
expiresAt: new Date(t.expires).toISOString(),
};
}
@@ -117,13 +101,6 @@ export class AgentFiles implements OnModuleDestroy {
};
}
install(app: Express) {
const disk = multer({
storage: diskStorage({
destination: tmpdir(),
filename: (_r, _f, cb) => cb(null, 'worthpath-import-' + randomUUID() + '.zip'),
}),
limits: { fileSize: MAX_UPLOAD_BYTES, files: 1, fields: 0 },
}).single('file');
const memory = multer({
storage: memoryStorage(),
limits: { fileSize: 2 * 1024 * 1024, files: 1, fields: 0 },
@@ -136,38 +113,23 @@ export class AgentFiles implements OnModuleDestroy {
res.status(405).end();
return;
}
if ((req.method === 'POST') !== (t.kind === 'backup' || t.kind === 'icon')) {
if ((req.method === 'POST') !== (t.kind === 'icon')) {
res.status(405).end();
return;
}
if (req.method === 'GET') {
if (t.kind === 'download') await this.backup.download(r, res, t.snapshot);
else await this.icons.image(r, t.iconId!, res);
await this.icons.image(r, t.iconId!, res);
return;
}
const selected = grant.scopes as string[];
if (!selected.includes('draft') && !selected.includes('write'))
throw new ForbiddenException('上传需要 draft 或 write 权限');
if (
(await this.db.agentPolicy.findUnique({ where: { userId: grant.userId } }))?.mode ===
'readonly'
)
throw new ForbiddenException('当前策略为只读');
await new Promise<void>((resolve, reject) =>
(t.kind === 'backup' ? disk : memory)(req, res, (e) => (e ? reject(e) : resolve())),
memory(req, res, (e) => (e ? reject(e) : resolve())),
);
if (!req.file) throw new BadRequestException('请选择文件');
try {
if (t.kind === 'backup') {
const v = await this.backup.upload(r, req.file);
t.token = v.token;
t.preview = v;
} else t.buffer = req.file.buffer;
res.json(await this.inspect(r, grant.id, String(req.params.id)));
} catch (e) {
if (req.file.path) await unlink(req.file.path).catch(() => {});
throw e;
}
t.buffer = req.file.buffer;
res.json(await this.inspect(r, grant.id, String(req.params.id)));
} catch (e) {
if (!res.headersSent)
res
apps/api/src/mcp/information.ts
+27
View File
@@ -0,0 +1,27 @@
// Protocol utility tools registered by AgentTransport, also exposed in the management catalogue.
export const protocolTools = [
{
name: 'state_get',
description: '读取当前账目并发版本，作为下一次写入的 expectedState。',
scope: 'read',
},
{
name: 'operation_get',
description: '查询本连接发起的草稿、确认状态和最终结果。',
scope: 'read',
},
{
name: 'file_upload_request',
description: '请求受保护的私有图标上传入口，不直接修改账目。',
scope: 'write',
},
{ name: 'file_status', description: '查询本连接上传文件状态和导入预检。', scope: 'read' },
{ name: 'icon_image', description: '请求受保护的图标图片读取入口。', scope: 'read' },
{ name: 'connection_info', description: '查看本连接权限、期限和隐藏账户授权。', scope: 'read' },
{
name: 'connection_revoke',
description: '撤销本连接；只读权限下也可主动撤销自身。',
scope: 'read',
},
] as const;
export const tokenDays = [1, 3, 7, 30, 365] as const;
apps/api/src/mcp/management.ts
+16 -21
View File
@@ -2,7 +2,6 @@ import {
Controller,
Get,
Post,
Put,
Delete,
Req,
Param,
@@ -18,6 +17,7 @@ import { Database } from '../database';
import { AuthService, UserRequest } from '../auth';
import { AgentOAuth, urls, scopeInput } from './oauth';
import { AgentOperations } from './operations';
import { protocolTools, tokenDays } from './information';
@Controller('api/agent')
export class AgentManagementController {
constructor(
@@ -62,34 +62,26 @@ export class AgentManagementController {
});
return {
mcpUrl: urls().resource.toString(),
mode:
(await this.db.agentPolicy.findUnique({ where: { userId: r.userId } }))?.mode || 'draft',
capabilities: [
...this.operations.tools.map((t) => ({
name: t.name,
description: t.description,
scope: t.scope,
destructive: !!t.destructive,
})),
...protocolTools,
],
grants,
operations,
calls,
};
}
@Put('policy') async policy(@Req() r: UserRequest, @Body() raw: unknown) {
const { mode, password } = z
.object({ mode: z.enum(['readonly', 'draft', 'direct']), password: z.string().max(72) })
.strict()
.parse(raw);
this.auth.limit(r);
const u = await this.db.user.findUniqueOrThrow({ where: { id: r.userId } });
if (!(await compare(password, u.passwordHash))) throw new ForbiddenException('密码错误');
await this.db.agentPolicy.upsert({
where: { userId: r.userId },
create: { userId: r.userId, mode },
update: { mode },
});
return { mode };
}
@Post('tokens') async token(@Req() r: UserRequest, @Body() raw: unknown) {
const p = z
.object({
name: z.string().trim().min(1).max(100),
scopes: scopeInput,
days: z.number().int().min(1).max(90),
days: z.union([z.literal(null), ...tokenDays.map((d) => z.literal(d))]),
password: z.string().max(72),
})
.strict()
@@ -118,8 +110,11 @@ export class AgentManagementController {
@Param('id') id: string,
@Body() raw: unknown,
) {
const { approve } = z.object({ approve: z.boolean() }).strict().parse(raw);
return this.oauth.consent(r.userId, z.string().uuid().parse(id), approve);
const { approve, scopes } = z
.object({ approve: z.boolean(), scopes: scopeInput.optional() })
.strict()
.parse(raw);
return this.oauth.consent(r.userId, z.string().uuid().parse(id), approve, scopes);
}
@Get('operations/:id') preview(@Req() r: UserRequest, @Param('id') id: string) {
return this.operations.preview(r.userId, z.string().uuid().parse(id));
apps/api/src/mcp/oauth.ts
+50 -11
View File
@@ -20,12 +20,19 @@ import {
InvalidTargetError,
} from '@modelcontextprotocol/sdk/server/auth/errors.js';
export const scopes = ['read', 'draft', 'write', 'sensitive'] as const;
export const scopes = ['read', 'draft', 'write', 'hidden_read', 'hidden_write'] as const;
export const scopeInput = z
.array(z.enum(scopes))
.min(1)
.max(4)
.refine((v) => v.includes('read') && new Set(v).size === v.length);
.refine(
(v) =>
v.includes('read') &&
new Set(v).size === v.length &&
!(v.includes('draft') && v.includes('write')) &&
(!v.includes('hidden_write') ||
(v.includes('hidden_read') && (v.includes('draft') || v.includes('write')))),
);
export const digest = (s: string) => createHash('sha256').update(s).digest('hex');
const secret = () => randomBytes(32).toString('base64url');
export function urls() {
@@ -115,7 +122,15 @@ export class AgentOAuth implements OAuthServerProvider {
async authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response) {
this.resource(params.resource);
const selected = params.scopes?.length ? params.scopes : ['read'];
if (!scopeInput.safeParse(selected).success) throw new InvalidScopeError('Unsupported scope');
if (
!z
.array(z.enum(scopes))
.min(1)
.max(scopes.length)
.refine((v) => v.includes('read') && new Set(v).size === v.length)
.safeParse(selected).success
)
throw new InvalidScopeError('Unsupported scope');
const row = await this.db.agentAuthorization.create({
data: {
clientId: client.client_id,
@@ -141,10 +156,15 @@ export class AgentOAuth implements OAuthServerProvider {
resource: p.resource,
};
}
async consent(userId: string, id: string, approved: boolean) {
async consent(userId: string, id: string, approved: boolean, selected?: string[]) {
return this.db.atomic(async () => {
await this.pending(id);
const row = await this.db.agentAuthorization.findUniqueOrThrow({ where: { id } });
const parameters = row.parameters as any;
const allowed = selected || ['read'];
scopeInput.parse(allowed);
if (allowed.some((scope: string) => !parameters.scopes.includes(scope)))
throw new BadRequestException('不能授予客户端未请求的权限');
const code = secret();
const changed = await this.db.agentAuthorization.updateMany({
where: { id, status: 'pending', expiresAt: { gt: new Date() } },
@@ -152,6 +172,7 @@ export class AgentOAuth implements OAuthServerProvider {
userId,
status: approved ? 'approved' : 'denied',
codeDigest: approved ? digest(code) : null,
parameters: { ...parameters, scopes: allowed },
},
});
if (!changed.count) throw new BadRequestException('授权请求已处理');
@@ -175,14 +196,25 @@ export class AgentOAuth implements OAuthServerProvider {
throw new InvalidGrantError('Invalid authorization code');
return (row.parameters as any).codeChallenge as string;
}
async issue(userId: string, name: string, selected: string[], days: number, clientId?: string) {
async issue(
userId: string,
name: string,
selected: string[],
days: number | null,
clientId?: string,
) {
if (clientId && days === null) throw new BadRequestException('OAuth 连接必须有期限');
const access = secret(),
refresh = clientId ? secret() : undefined,
sessionId = digest(secret());
const expiresAt = new Date(Date.now() + days * 86400000),
const expiresAt = days === null ? null : new Date(Date.now() + days * 86400000),
refreshExpiresAt = clientId ? new Date(Date.now() + 30 * 86400000) : null;
await this.db.session.create({
data: { id: sessionId, userId, expiresAt: refreshExpiresAt || expiresAt },
data: {
id: sessionId,
userId,
expiresAt: refreshExpiresAt || expiresAt || new Date(Date.now() + 86400000),
},
});
const grant = await this.db.agentGrant.create({
data: {
@@ -203,7 +235,7 @@ export class AgentOAuth implements OAuthServerProvider {
tokens: {
access_token: access,
token_type: 'Bearer',
expires_in: Math.floor(days * 86400),
...(days === null ? {} : { expires_in: Math.floor(days * 86400) }),
scope: selected.join(' '),
...(refresh ? { refresh_token: refresh } : {}),
} as OAuthTokens,
@@ -296,7 +328,7 @@ export class AgentOAuth implements OAuthServerProvider {
if (
!row ||
row.revokedAt ||
row.expiresAt <= new Date() ||
(row.expiresAt ? row.expiresAt <= new Date() : !!row.clientId) ||
row.resource !== urls().resource.toString()
)
throw new InvalidTokenError('Expired, revoked or invalid resource token');
@@ -304,7 +336,9 @@ export class AgentOAuth implements OAuthServerProvider {
token,
clientId: row.clientId || row.id,
scopes: row.scopes as string[],
expiresAt: Math.floor(+row.expiresAt / 1000),
// SDK bearer middleware requires a finite verified-authentication expiry.
// A permanent PAT stays expiry-free in storage; every request rechecks revocation.
expiresAt: Math.floor((row.expiresAt?.getTime() ?? Date.now() + 3600000) / 1000),
resource: new URL(row.resource),
extra: { grantId: row.id, userId: row.userId },
};
@@ -320,7 +354,12 @@ export class AgentOAuth implements OAuthServerProvider {
}
async grant(id: string, userId?: string) {
const row = await this.db.agentGrant.findFirst({
where: { id, ...(userId ? { userId } : {}), revokedAt: null, expiresAt: { gt: new Date() } },
where: {
id,
...(userId ? { userId } : {}),
revokedAt: null,
OR: [{ expiresAt: { gt: new Date() } }, { expiresAt: null, clientId: null }],
},
});
if (!row) throw new ForbiddenException('Agent 连接已过期或撤销');
return row;
apps/api/src/mcp/operations.ts
+43 -113
View File
@@ -6,12 +6,10 @@ import {
NotFoundException,
} from '@nestjs/common';
import { Prisma, AgentGrant } from '@prisma/client';
import { compare } from 'bcryptjs';
import { Response } from 'express';
import { z } from 'zod';
import { Database } from '../database';
import { AuthBusinessService, UserRequest } from '../auth';
import { BackupBusinessService } from '../backup';
import { UserRequest } from '../auth';
import { AgentOAuth, digest, webLink } from './oauth';
import { AgentCatalogue, ToolDefinition, empty } from './catalogue';
import { AgentFiles } from './files';
@@ -46,41 +44,23 @@ export class AgentOperations {
private db: Database,
private oauth: AgentOAuth,
catalogue: AgentCatalogue,
private auth: AuthBusinessService,
private backup: BackupBusinessService,
private files: AgentFiles,
) {
this.tools = [
...catalogue.tools,
{
name: 'backup_export',
description:
'创建短期受 Bearer 保护的完整 ZIP 备份下载入口，包含隐藏项目；网页验证密码并确认后 operation_get 获取入口，URL 本身不是凭证。',
schema: empty,
scope: 'sensitive',
run: async (r) => this.files.issue(r, r.agentGrantId!, 'download'),
},
{
name: 'icon_publish',
description:
'保存已上传图标，shared=true 发布到共享库，须中文名称及网页确认。先 file_upload_request(kind=icon)。',
description: '保存已上传私有图标，不允许发布共享图标。先 file_upload_request(kind=icon)。',
schema: z
.object({
fileId: z.string().uuid(),
name: z.string().min(1).max(100),
shared: z.boolean().default(false),
shared: z.literal(false).default(false),
})
.strict(),
scope: 'write',
run: (r, p) => this.files.publishIcon(r, r.agentGrantId!, p.fileId, p.name, p.shared),
},
{
name: 'hidden_lock',
description: '立即锁定本连接的隐藏项目授权。',
schema: empty,
scope: 'write',
run: async (r) => this.auth.lock(r),
},
];
}
get(name: string) {
@@ -88,13 +68,32 @@ export class AgentOperations {
if (!t) throw new BadRequestException('未知工具');
return t;
}
async context(grant: AgentGrant) {
const s = await this.db.session.findUnique({ where: { id: grant.sessionId } });
async context(grant: AgentGrant, writing = false) {
let s = await this.db.session.findUnique({ where: { id: grant.sessionId } });
// A permanent PAT is the credential. Its internal business session has a bounded
// lifetime and may be recreated after the normal expired-session cleanup.
if (!grant.expiresAt && !grant.clientId && (!s || s.expiresAt <= new Date())) {
await this.oauth.grant(grant.id, grant.userId);
s = await this.db.session.upsert({
where: { id: grant.sessionId },
create: {
id: grant.sessionId,
userId: grant.userId,
expiresAt: new Date(Date.now() + 86400000),
},
update: {
expiresAt: new Date(Date.now() + 86400000),
revealUntil: null,
backupDigest: null,
backupExpiresAt: null,
},
});
}
if (!s || s.expiresAt <= new Date()) throw new ForbiddenException('连接会话失效，请重新授权');
return {
userId: grant.userId,
sessionId: grant.sessionId,
revealed: !!s.revealUntil && +s.revealUntil > Date.now(),
revealed: (grant.scopes as string[]).includes(writing ? 'hidden_write' : 'hidden_read'),
agent: true,
agentGrantId: grant.id,
cookies: {},
@@ -134,35 +133,26 @@ export class AgentOperations {
]);
return digest(stable(plain(data)));
}
private sensitive(t: ToolDefinition, p: any) {
return (
t.scope === 'sensitive' ||
(t.name === 'settings_update' && p.requireHiddenPassword !== undefined) ||
(t.name === 'icon_publish' && p.shared)
);
}
private async permission(grant: AgentGrant, t: ToolDefinition, p: any) {
const selected = grant.scopes as string[],
mode =
(await this.db.agentPolicy.findUnique({ where: { userId: grant.userId } }))?.mode ||
'draft';
const selected = grant.scopes as string[];
if (!selected.includes('read')) throw new ForbiddenException('缺少 read 权限');
if (t.scope === 'read') return { mode, sensitive: false };
const sensitive = this.sensitive(t, p);
if (sensitive && !selected.includes('sensitive'))
throw new ForbiddenException('此操作需要 sensitive 权限');
if (!sensitive && !selected.includes('write') && !selected.includes('draft'))
throw new ForbiddenException('缺少 draft 或 write 权限');
if (mode === 'readonly' && !['backup_export', 'hidden_unlock_request'].includes(t.name))
throw new ForbiddenException('当前用户写入策略为只读');
return { mode, sensitive };
const mode = selected.includes('write')
? 'direct'
: selected.includes('draft')
? 'draft'
: 'readonly';
if (t.scope === 'read') return { mode };
if (mode === 'readonly') throw new ForbiddenException('本连接只有只读权限');
if (!selected.includes('hidden_write') && (p.hidden === true || p.data?.hidden === true))
throw new ForbiddenException('缺少隐藏账户修改权限');
return { mode };
}
async call(grantId: string, name: string, input: any) {
const t = this.get(name);
const parsed = (t.scope === 'read' ? t.schema : t.schema.safeExtend(writing)).parse(input);
const { idempotencyKey, expectedState, ...p } = parsed as any;
const grant = await this.oauth.grant(grantId),
permission = await this.permission(grant, t, p);
const grant = await this.oauth.grant(grantId);
await this.permission(grant, t, p);
if (t.scope === 'read') return t.run!(await this.context(grant), p);
const hash = digest(stable({ tool: name, parameters: p, expectedState }));
return this.db.atomic(async () => {
@@ -192,11 +182,7 @@ export class AgentOperations {
expiresAt: new Date(Date.now() + 600000),
},
});
if (
access.sensitive ||
access.mode === 'draft' ||
!(fresh.scopes as string[]).includes('write')
)
if (access.mode === 'draft' || !(fresh.scopes as string[]).includes('write'))
return this.view(row);
const result = await this.execute(t, fresh, p);
return this.view(
@@ -208,7 +194,7 @@ export class AgentOperations {
});
}
private async execute(t: ToolDefinition, grant: AgentGrant, p: any) {
return t.run!(await this.context(grant), p);
return t.run!(await this.context(grant, true), p);
}
private view(row: any) {
return {
@@ -234,22 +220,9 @@ export class AgentOperations {
const t = this.get(row.tool),
grant = await this.oauth.grant(row.grantId, userId);
let impact: unknown = { parameters: row.parameters, message: t.description };
if (t.name === 'backup_import')
impact = (
await this.backup.inspectUpload(await this.context(grant), (row.parameters as any).token)
).preview;
if (t.web === 'clear')
impact = {
positions: await this.db.position.count({ where: { userId } }),
history: await this.db.revision.count({ where: { position: { userId } } }),
schedules: await this.db.schedule.count({ where: { userId } }),
message: '清空账户、资产、债务、历史、私有图标和汇率；保留账号和个人设置。先下载当前备份。',
};
return {
...this.view(row),
impact,
web: t.web,
sensitive: this.sensitive(t, row.parameters),
description: t.description,
};
}
@@ -257,10 +230,6 @@ export class AgentOperations {
const input = z
.object({
approve: z.boolean(),
password: z.string().max(72).optional(),
username: z.string().max(64).optional(),
newPassword: z.string().max(72).optional(),
confirmation: z.string().max(20).optional(),
})
.strict()
.parse(raw);
@@ -280,44 +249,10 @@ export class AgentOperations {
const grant = await this.oauth.grant(row.grantId, r.userId),
t = this.get(row.tool),
p = row.parameters as any;
const access = await this.permission(grant, t, p);
if (access.sensitive) {
const u = await this.db.user.findUniqueOrThrow({ where: { id: r.userId } });
if (!input.password || !(await compare(input.password, u.passwordHash)))
throw new ForbiddenException('请验证当前密码');
}
await this.permission(grant, t, p);
if ((await this.state(r.userId)) !== row.snapshot)
throw new ConflictException('账目已变化，请取消并重新创建操作');
let result: unknown;
if (t.web === 'credentials') {
result = await this.auth.changeCredentials(
r,
{
currentPassword: input.password,
username: input.username,
newPassword: input.newPassword,
},
res,
);
await this.db.agentGrant.updateMany({
where: { userId: r.userId, id: { not: grant.id } },
data: { revokedAt: new Date() },
});
await this.db.session.create({
data: { id: grant.sessionId, userId: r.userId, expiresAt: new Date(Date.now() + 300000) },
});
await this.db.agentGrant.update({
where: { id: grant.id },
data: { scopes: ['read'], expiresAt: new Date(Date.now() + 300000), refreshDigest: null },
});
} else if (t.web === 'reveal')
result = await this.auth.reveal(
Object.assign(Object.create(r), { sessionId: grant.sessionId }),
{ password: input.password },
);
else if (t.web === 'clear')
result = await this.backup.clear(r, { confirmation: input.confirmation });
else result = await this.execute(t, grant, p);
const result = await this.execute(t, grant, p);
return this.view(
await this.db.agentOperation.update({
where: { id },
@@ -326,16 +261,11 @@ export class AgentOperations {
);
}, 300000);
}
async uploadRequest(grantId: string, kind: 'backup' | 'icon') {
async uploadRequest(grantId: string, kind: 'icon') {
const grant = await this.oauth.grant(grantId);
const selected = grant.scopes as string[];
if (!selected.includes('draft') && !selected.includes('write'))
throw new ForbiddenException('上传需要 draft 或 write 权限');
if (
(await this.db.agentPolicy.findUnique({ where: { userId: grant.userId } }))?.mode ===
'readonly'
)
throw new ForbiddenException('当前策略为只读');
return this.files.issue(await this.context(grant), grantId, kind);
}
async fileStatus(grantId: string, id: string) {
apps/api/src/mcp/transport.ts
+10 -6
View File
@@ -183,13 +183,13 @@ export class AgentTransport {
register(
'file_upload_request',
'创建受 Bearer 保护的短期文件上传入口；multipart/form-data 的 file 字段。',
z.object({ kind: z.enum(['backup', 'icon']) }).strict(),
z.object({ kind: z.enum(['icon']) }).strict(),
(p) => this.operations.uploadRequest(grantId, p.kind),
false,
);
register(
'file_status',
'查看此连接文件上传状态、预检结果和备份导入 token。',
'查看此连接私有图标上传状态，不返回令牌。',
z.object({ fileId: z.string().uuid() }).strict(),
(p) => this.operations.fileStatus(grantId, p.fileId),
);
@@ -201,7 +201,7 @@ export class AgentTransport {
);
register(
'connection_info',
'查询本连接权限、到期时间、资源和用户写入策略；不返回任何令牌。',
'查询本连接权限、到期时间、资源及隐藏账户权限；不返回任何令牌。',
z.object({}).strict(),
async () => {
const g = await this.oauth.grant(grantId);
@@ -210,9 +210,13 @@ export class AgentTransport {
scopes: g.scopes,
expiresAt: g.expiresAt,
resource: g.resource,
writePolicy:
(await this.db.agentPolicy.findUnique({ where: { userId: g.userId } }))?.mode ||
'draft',
permission: (g.scopes as string[]).includes('write')
? 'write'
: (g.scopes as string[]).includes('draft')
? 'draft'
: 'read',
readHidden: (g.scopes as string[]).includes('hidden_read'),
writeHidden: (g.scopes as string[]).includes('hidden_write'),
};
},
);
apps/api/src/metals.ts
+10 -44
View File
@@ -30,14 +30,15 @@ import {
} from './validation';
import { businessTime, businessDay } from './calculation';
export const metalType = z.enum(['gold', 'silver']);
// Historical stored ratios remain part of valuation and ZIP data, not user input.
export const storedMetalPurity = z
.string()
.regex(/^(0|1)(\.\d{1,8})?$/)
.refine((v) => new Decimal(v).gt(0) && new Decimal(v).lte(1), '纯度应大于 0 且不超过 1');
export const metalConfig = z
.object({
metalType,
metalGrams: amount.refine((v) => new Decimal(v).gt(0), '重量必须大于零'),
metalPurity: z
.string()
.regex(/^(0|1)(\.\d{1,8})?$/)
.refine((v) => new Decimal(v).gt(0) && new Decimal(v).lte(1), '纯度应大于 0 且不超过 1'),
metalCostPerGram: rateValue
.nullable()
.optional()
@@ -152,8 +153,7 @@ export class MetalsService implements OnModuleInit, OnModuleDestroy {
},
});
if (!p) throw new NotFoundException('贵金属资产不存在或已归档');
if (!p.metalType || !p.metalGrams)
throw new BadRequestException('请先设置贵金属品种、重量和纯度');
if (!p.metalType || !p.metalGrams) throw new BadRequestException('请先设置贵金属品种和重量');
const quote = await tx.metalPrice.findFirst({
where: {
userId,
@@ -163,7 +163,7 @@ export class MetalsService implements OnModuleInit, OnModuleDestroy {
},
orderBy: { date: 'desc' },
});
if (!quote) throw new BadRequestException('缺少该币种的贵金属价格，请刷新或手动录价');
if (!quote) throw new BadRequestException('缺少该币种的贵金属价格，请刷新报价后重试');
const value = metalValue(
p.metalGrams.toString(),
p.metalPurity.toString(),
@@ -286,17 +286,17 @@ export class MetalsService implements OnModuleInit, OnModuleDestroy {
if (p.autoValuation) await this.apply(tx, userId, p.id, true);
}
});
const message = '贵金属参考价已更新；同日手动价格已保留，已开启的自动估价已记入历史';
const message = '贵金属参考价已更新，已开启的自动估价已记入历史';
this.attempts.set(userId, today());
this.outcomes.set(userId, { state: 'ok', message, attemptedAt: new Date().toISOString() });
return { message };
} catch {
this.outcomes.set(userId, {
state: 'error',
message: '贵金属价格更新失败，已有价格与估值已保留，可手动录价',
message: '贵金属价格更新失败，已有价格与估值已保留，请稍后重试',
attemptedAt: new Date().toISOString(),
});
throw new BadGatewayException('贵金属价格更新失败，已有价格与估值已保留，可手动录价');
throw new BadGatewayException('贵金属价格更新失败，已有价格与估值已保留，请稍后重试');
} finally {
this.running.delete(userId);
}
@@ -323,37 +323,6 @@ export class MetalsBusinessService {
refresh(r: UserRequest) {
return this.metals.refresh(r.userId);
}
async manual(r: UserRequest, body: unknown) {
const v = metalPriceInput.parse(body);
const key = {
userId: r.userId,
metalType: v.metalType,
currency: v.currency,
date: new Date(v.date),
};
return this.db.serial(async (tx) => {
await tx.$queryRaw(Prisma.sql`SELECT id FROM User WHERE id=${r.userId} FOR UPDATE`);
await tx.metalPrice.upsert({
where: { userId_metalType_currency_date: key },
create: { ...key, price: v.price, source: 'manual', quotedAt: new Date() },
update: { price: v.price, source: 'manual', quotedAt: new Date() },
});
const ps = await tx.position.findMany({
where: {
userId: r.userId,
kind: 'asset',
category: 'gold',
metalType: v.metalType,
currency: v.currency,
archived: false,
autoValuation: true,
...(r.revealed ? {} : { hidden: false }),
},
});
for (const p of ps) await this.metals.apply(tx, r.userId, p.id, r.revealed);
return { message: '贵金属价格已保存' };
});
}
async create(r: UserRequest, body: unknown) {
const v = metalHoldingInput.parse(body);
const when = toBusinessDate(v.date);
@@ -436,9 +405,6 @@ export class MetalsController {
@Post('refresh') refresh(@Req() r: UserRequest) {
return this.service.refresh(r);
}
@Post('prices') async manual(@Req() r: UserRequest, @Body() body: unknown) {
return this.service.manual(r, body);
}
@Put(':id') async configure(
@Req() r: UserRequest,
@Param('id') id: string,
apps/api/src/openapi.ts
+2 -10
View File
@@ -1,6 +1,6 @@
import { INestApplication } from '@nestjs/common';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { metalConfig, metalPriceInput } from './metals';
import { metalConfig, metalHoldingInput } from './metals';
import { scheduleInput } from './schedules';
import { z } from 'zod';
import {
@@ -47,7 +47,7 @@ export function setupOpenApi(app: INestApplication) {
'PATCH /api/schedules/{id}': z.object({ enabled: z.boolean() }).strict(),
'PATCH /api/settings': settingsInput,
'PUT /api/metals/{id}': metalConfig,
'POST /api/metals/prices': metalPriceInput,
'POST /api/metals/holdings': metalHoldingInput,
'POST /api/backup/clear': z.object({ confirmation: z.literal('确定清空') }),
'POST /api/backup/import-file': z.object({
token: z.string().uuid(),
@@ -155,14 +155,6 @@ export function setupOpenApi(app: INestApplication) {
},
};
}
if (['/api/backup/preview', '/api/backup/import'].includes(path))
operation.requestBody = {
required: true,
description: '旧版 JSON 兼容入口；新版请使用 upload + import-file（支持完整 ZIP 备份）',
content: {
'application/json': { schema: { type: 'object', additionalProperties: true } },
},
};
}
}
SwaggerModule.setup('api/docs', app, document, {
apps/api/src/zip.ts
+15 -41
View File
@@ -3,8 +3,8 @@ import * as yauzl from 'yauzl';
import { createHash } from 'node:crypto';
import { BadRequestException } from '@nestjs/common';
import { z } from 'zod';
import { BACKUP_ZIP_VERSION } from './backup-format';
import type { Backup } from './backup';
import { accountGroupOrder, sessionHours, overviewCards } from './validation';
export const MAX_UPLOAD_BYTES = 512 * 1024 * 1024;
const MAX_EXPANDED_BYTES = 1024 * 1024 * 1024;
const files = [
@@ -38,9 +38,9 @@ export function packBackup(b: Backup) {
),
'links.json': b.links,
'rates.json': b.rates,
'icons.json': b.icons || [],
'transfers.json': b.transfers || [],
'schedules.json': b.schedules || [],
'icons.json': b.icons,
'transfers.json': b.transfers,
'schedules.json': b.schedules,
};
const contents = Object.fromEntries(
files.map((name) => [name, JSON.stringify(data[name], null, 2)]),
@@ -48,7 +48,7 @@ export function packBackup(b: Backup) {
contents['manifest.json'] = JSON.stringify(
{
format: 'worthpath',
version: 8,
version: BACKUP_ZIP_VERSION,
exportedAt: b.exportedAt,
files: files.map((name) => ({ name, sha256: sha(contents[name]) })),
},
@@ -123,30 +123,17 @@ export async function readBackupZip(input: string | Buffer): Promise<unknown> {
const manifest = z
.object({
format: z.literal('worthpath'),
version: z.union([
z.literal(3),
z.literal(4),
z.literal(5),
z.literal(6),
z.literal(7),
z.literal(8),
]),
version: z.literal(BACKUP_ZIP_VERSION),
exportedAt: z.iso.datetime(),
files: z
.array(
z.object({ name: z.enum(files), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict(),
)
.min(files.length - 3)
.max(files.length),
.length(files.length),
})
.strict()
.parse(parse('manifest.json'));
const expected = files.filter(
(f) =>
(manifest.version >= 4 || f !== 'icons.json') &&
(manifest.version >= 5 || f !== 'transfers.json') &&
(manifest.version >= 7 || f !== 'schedules.json'),
);
const expected = files;
if (
contents.size !== expected.length + 1 ||
new Set(manifest.files.map((f) => f.name)).size !== expected.length ||
@@ -157,21 +144,8 @@ export async function readBackupZip(input: string | Buffer): Promise<unknown> {
const settings = z
.object({
baseCurrency: z.string(),
metalPrices: z.array(z.record(z.string(), z.unknown())).optional(),
preferences: z
.object({
showSidebar: z.boolean().optional(),
hiddenMenus: z.array(z.string()).optional(),
accountGroupOrder: accountGroupOrder.optional(),
sessionHours: sessionHours.optional(),
requireHiddenPassword: z.boolean().optional(),
overviewCards: overviewCards.optional(),
includeIndependentAssets: z.boolean().optional(),
showNotes: z.boolean().optional(),
idleMinutes: z.number().int().min(0).max(1440),
})
.strict()
.optional(),
metalPrices: z.array(z.record(z.string(), z.unknown())),
preferences: z.record(z.string(), z.unknown()),
})
.strict()
.parse(parse('settings.json'));
@@ -194,20 +168,20 @@ export async function readBackupZip(input: string | Buffer): Promise<unknown> {
}
return {
format: 'worthpath',
version: 2,
version: BACKUP_ZIP_VERSION,
exportedAt: manifest.exportedAt,
...settings,
currencies: parse('currencies.json'),
positions: positions.map((p) => ({ ...p, revisions: grouped.get(p.id) || [] })),
links: parse('links.json'),
rates: parse('rates.json'),
...(manifest.version >= 5 ? { transfers: parse('transfers.json') } : {}),
...(manifest.version >= 7 ? { schedules: parse('schedules.json') } : {}),
...(manifest.version >= 4 ? { icons: parse('icons.json') } : {}),
transfers: parse('transfers.json'),
schedules: parse('schedules.json'),
icons: parse('icons.json'),
};
} catch {
throw new BadRequestException(
'备份 ZIP 无效：请检查 JSON 文件、完整性及文件大小（上传 512 MB，解压总计 1 GB；不限制记录条数）',
'备份 ZIP 无效：仅接受当前 v9 格式，不支持旧备份。请检查 JSON 文件、完整性及文件大小（上传 512 MB，解压总计 1 GB；不限制记录条数）',
);
} finally {
zip.close();
apps/api/test/backup-fixture.ts
+34
View File
@@ -0,0 +1,34 @@
import { archiveBackup } from '../src/zip';
// Test-only aliases build ZIP fixtures and exercise the public upload/confirmation flow.
export async function fixtureFetch(url: string, init?: RequestInit): Promise<Response> {
if (!url.endsWith('/backup/restore-fixture') && !url.endsWith('/backup/preview-fixture'))
return fetch(url, init);
const restore = url.endsWith('/backup/restore-fixture');
const input = JSON.parse(String(init?.body));
const chunks: Buffer[] = [];
const archive = archiveBackup(restore ? input.backup : input);
const completed = new Promise<Buffer>((resolve, reject) => {
archive.on('data', (chunk) => chunks.push(chunk));
archive.on('end', () => resolve(Buffer.concat(chunks)));
archive.on('error', reject);
});
await archive.finalize();
const form = new FormData();
form.set(
'file',
new Blob([new Uint8Array(await completed)], { type: 'application/zip' }),
'fixture.zip',
);
const headers = new Headers(init?.headers);
headers.delete('Content-Type');
const base = url.slice(0, url.lastIndexOf('/backup/'));
const uploaded = await fetch(base + '/backup/upload', { method: 'POST', headers, body: form });
if (!uploaded.ok || !restore) return uploaded;
const preview = await uploaded.json();
headers.set('Content-Type', 'application/json');
return fetch(base + '/backup/import-file', {
method: 'POST',
headers,
body: JSON.stringify({ token: preview.token, confirmed: input.confirmed }),
});
}
apps/api/test/calculation.test.ts
+15 -1
View File
@@ -144,7 +144,21 @@ test('reject invalid dates, negative values and credit card assets', () => {
test('backup rejects auth data and broken relations', () => {
const b = {
format: 'worthpath',
version: 1,
version: 9,
preferences: {
hiddenMenus: [],
showNotes: true,
idleMinutes: 0,
accountGroupOrder: [],
sessionHours: 168,
requireHiddenPassword: true,
overviewCards: ['net'],
includeIndependentAssets: true,
},
icons: [],
transfers: [],
schedules: [],
metalPrices: [],
exportedAt: new Date().toISOString(),
baseCurrency: 'CNY',
currencies: ['CNY'],
apps/api/test/credit-balance.test.ts
+3 -2
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import assert from 'node:assert/strict';
@@ -25,7 +26,7 @@ test('liability account credit balances survive revisions, replay, calendar, pri
return { id: u.id, cookie: 'wp_session=' + token };
}
async function call(path: string, cookie: string, method = 'GET', body?: unknown) {
const res = await fetch(base + path, {
const res = await fixtureFetch(base + path, {
method,
headers: {
Cookie: cookie,
@@ -163,7 +164,7 @@ test('liability account credit balances survive revisions, replay, calendar, pri
assert.equal(zip.status, 200);
const backup: any = await readBackupZip(Buffer.from(await zip.arrayBuffer()));
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup })).status,
(await call('/backup/restore-fixture', b.cookie, 'POST', { confirmed: true, backup })).status,
201,
);
const restored = (await call('/overview', b.cookie)).data;
apps/api/test/debts.test.ts
+4 -3
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import assert from 'node:assert/strict';
@@ -25,7 +26,7 @@ test('borrow/lend/collect/repay pair balances atomically and survive concurrency
return { id: row.id, token };
}
async function call(token: string, path: string, method = 'GET', body?: unknown) {
const response = await fetch(base + path, {
const response = await fixtureFetch(base + path, {
method,
headers: {
Cookie: 'wp_session=' + token,
@@ -151,11 +152,11 @@ test('borrow/lend/collect/repay pair balances atomically and survive concurrency
200,
);
const backup = (await call(a.token, '/backup')).data;
assert.equal(JSON.parse(packBackup(backup)['manifest.json']).version, 8);
assert.equal(JSON.parse(packBackup(backup)['manifest.json']).version, 9);
assert.equal(backup.transfers.length, 5);
assert.ok(backup.transfers.some((p: any) => p.operation === 'lend' && p.fee === '-2'));
assert.equal(
(await call(b.token, '/backup/import', 'POST', { confirmed: true, backup })).status,
(await call(b.token, '/backup/restore-fixture', 'POST', { confirmed: true, backup })).status,
201,
);
assert.equal(
apps/api/test/group-order.test.ts
+7 -6
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import assert from 'node:assert/strict';
@@ -5,7 +6,7 @@ import { randomUUID, randomBytes, createHash } from 'node:crypto';
import { PrismaClient } from '@prisma/client';
import { readBackupZip } from '../src/zip';
const base = process.env.TEST_API_URL || 'http://127.0.0.1:3100/api';
test('group order persists per user, validates input and survives ZIP and legacy imports', async () => {
test('group order persists per user, validates input and survives ZIP and reject incomplete imports', async () => {
const db = new PrismaClient(),
ids: string[] = [];
const origin = process.env.WEB_ORIGIN === '*' ? 'http://localhost:5173' : process.env.WEB_ORIGIN!;
@@ -25,7 +26,7 @@ test('group order persists per user, validates input and survives ZIP and legacy
return { id: u.id, cookie: 'wp_session=' + token };
}
async function call(path: string, cookie: string, method = 'GET', body?: unknown) {
const res = await fetch(base + path, {
const res = await fixtureFetch(base + path, {
method,
headers: {
Cookie: cookie,
@@ -80,20 +81,20 @@ test('group order persists per user, validates input and survives ZIP and legacy
const backup: any = await readBackupZip(Buffer.from(await zip.arrayBuffer()));
assert.deepEqual(backup.preferences.accountGroupOrder, order);
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup })).status,
(await call('/backup/restore-fixture', b.cookie, 'POST', { confirmed: true, backup })).status,
201,
);
assert.deepEqual((await call('/auth/me', b.cookie)).data.accountGroupOrder, order);
await call('/settings', b.cookie, 'PATCH', { accountGroupOrder: ['日常'] });
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup })).status,
(await call('/backup/restore-fixture', b.cookie, 'POST', { confirmed: true, backup })).status,
409,
);
assert.deepEqual((await call('/settings', b.cookie)).data.accountGroupOrder, ['日常']);
delete backup.preferences.accountGroupOrder;
assert.equal(
(await call('/backup/import', c.cookie, 'POST', { confirmed: true, backup })).status,
201,
(await call('/backup/restore-fixture', c.cookie, 'POST', { confirmed: true, backup })).status,
400,
);
assert.deepEqual((await call('/auth/me', c.cookie)).data.accountGroupOrder, []);
const comments: any[] = await db.$queryRawUnsafe(
apps/api/test/icons.test.ts
+11 -5
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import assert from 'node:assert/strict';
@@ -11,7 +12,7 @@ test('private and shared icons, account reuse and complete ZIP restoration prese
names: string[] = [],
publicIds: string[] = [];
async function call(path: string, cookie = '', method = 'GET', data?: unknown) {
const res = await fetch(base + path, {
const res = await fixtureFetch(base + path, {
method,
headers: {
Cookie: cookie,
@@ -153,16 +154,21 @@ test('private and shared icons, account reuse and complete ZIP restoration prese
assert.doesNotMatch(JSON.stringify(backup.data), /passwordHash|sessionId|ownerId|token/i);
const broken = structuredClone(backup.data);
broken.icons[0].image = 'invalid';
assert.equal((await call('/backup/preview', b.cookie, 'POST', broken)).status, 400);
assert.equal((await call('/backup/preview-fixture', b.cookie, 'POST', broken)).status, 400);
const before = await db.icon.count();
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup: broken })).status,
(await call('/backup/restore-fixture', b.cookie, 'POST', { confirmed: true, backup: broken }))
.status,
400,
);
assert.equal(await db.icon.count(), before);
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup: backup.data }))
.status,
(
await call('/backup/restore-fixture', b.cookie, 'POST', {
confirmed: true,
backup: backup.data,
})
).status,
201,
);
const imported = await db.position.findMany({
apps/api/test/inclusion-metals.test.ts
+59 -38
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import { request } from 'node:http';
@@ -28,6 +29,14 @@ async function fixture() {
// Give this fixture suite its own loopback source address so independent auth
// scenarios do not consume the existing suite's per-IP production rate limit.
async function call(path: string, cookie: string, method = 'GET', body?: unknown) {
if (path.endsWith('-fixture')) {
const response = await fixtureFetch(base + path, {
method,
headers: { Cookie: cookie, Origin: origin, 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
return { status: response.status, data: await response.json(), cookie: null };
}
const data = body === undefined ? undefined : JSON.stringify(body);
return new Promise<{ status: number; data: any; cookie: string | null }>((resolve, reject) => {
const req = request(
@@ -200,7 +209,6 @@ test('inclusion preferences and precious metal settings, valuation and quotes re
await call('/metals/' + cash, a.cookie, 'PUT', {
metalType: 'gold',
metalGrams: '10',
metalPurity: '0.999',
autoValuation: true,
})
).status,
@@ -211,7 +219,6 @@ test('inclusion preferences and precious metal settings, valuation and quotes re
await call('/metals/' + metal, b.cookie, 'PUT', {
metalType: 'gold',
metalGrams: '10',
metalPurity: '0.999',
autoValuation: true,
})
).status,
@@ -222,24 +229,26 @@ test('inclusion preferences and precious metal settings, valuation and quotes re
await call('/metals/' + metal, a.cookie, 'PUT', {
metalType: 'gold',
metalGrams: '10.86420978',
metalPurity: '0.999',
autoValuation: true,
})
).status,
200,
);
await db.position.update({ where: { id: metal }, data: { metalPurity: '0.999' } }); // Existing stored valuations are preserved, not an editable setting.
const d = new Date(Date.now() + 8 * 3600000).toISOString().slice(0, 10);
assert.equal(
(
await call('/metals/prices', a.cookie, 'POST', {
metalType: 'gold',
currency: 'CNY',
price: '700.864209789012',
date: d,
})
).status,
201,
);
assert.equal((await call('/metals/prices', a.cookie, 'POST', {})).status, 404);
await db.metalPrice.create({
data: {
userId: a.id,
metalType: 'gold',
currency: 'CNY',
price: '700.864209789012',
date: new Date(d),
source: 'manual',
quotedAt: new Date(),
},
});
await call('/metals/' + metal + '/value', a.cookie, 'POST', {});
const expected = (await import('../src/metals')).metalValue(
'10.86420978',
'0.999',
@@ -250,12 +259,7 @@ test('inclusion preferences and precious metal settings, valuation and quotes re
expected.replace(/0+$/, '').replace(/\.$/, ''),
);
const count = await db.revision.count({ where: { positionId: metal } });
await call('/metals/prices', a.cookie, 'POST', {
metalType: 'gold',
currency: 'CNY',
price: '700.864209789012',
date: d,
});
await call('/metals/' + metal + '/value', a.cookie, 'POST', {});
assert.equal(await db.revision.count({ where: { positionId: metal } }), count);
const controller = new (await import('../src/backup')).BackupBusinessService(db as any);
const backup = await (controller as any).data(a.id);
@@ -267,8 +271,12 @@ test('inclusion preferences and precious metal settings, valuation and quotes re
await done;
const restoredBackup = await readBackupZip(Buffer.concat(chunks));
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup: restoredBackup }))
.status,
(
await call('/backup/restore-fixture', b.cookie, 'POST', {
confirmed: true,
backup: restoredBackup,
})
).status,
201,
);
assert.equal((await call('/auth/me', b.cookie)).data.includeIndependentAssets, false);
@@ -294,7 +302,7 @@ test('inclusion preferences and precious metal settings, valuation and quotes re
await db.$disconnect();
}
});
test('gram-only creation, optional exact purchase cost, pending totals and backward-compatible backups', async () => {
test('gram-only creation, optional exact purchase cost, pending totals and strict current backups', async () => {
const a = await fixture(),
b = await fixture();
try {
@@ -303,13 +311,22 @@ test('gram-only creation, optional exact purchase cost, pending totals and backw
currency: 'CNY',
metalType: 'gold',
metalGrams: '2.5',
metalPurity: '0.8',
autoValuation: true,
date: '2026-10-01T12:00',
metalCostPerGram: '12.8',
};
assert.equal(
(await call('/metals/holdings', a.cookie, 'POST', { ...input, metalPurity: '0.8' })).status,
400,
);
const created = await call('/metals/holdings', a.cookie, 'POST', input);
assert.equal(created.status, 201, JSON.stringify(created.data));
assert.equal(
(
await db.position.findUniqueOrThrow({ where: { id: created.data.id } })
).metalPurity.toString(),
'1',
);
assert.equal(created.data.valuationAvailable, false);
const id = created.data.id;
let p = (await call('/positions/' + id, a.cookie)).data;
@@ -326,36 +343,40 @@ test('gram-only creation, optional exact purchase cost, pending totals and backw
await call('/metals/' + id, b.cookie, 'PUT', {
metalType: 'gold',
metalGrams: '2.5',
metalPurity: '0.8',
autoValuation: true,
})
).status,
404,
);
const price = await call('/metals/prices', a.cookie, 'POST', {
metalType: 'gold',
currency: 'CNY',
price: '20',
date: '2026-10-01',
await db.metalPrice.create({
data: {
userId: a.id,
metalType: 'gold',
currency: 'CNY',
price: '20',
date: new Date('2026-10-01'),
source: 'goldapi',
quotedAt: new Date(),
},
});
assert.equal(price.status, 201, JSON.stringify(price.data));
assert.equal((await call('/metals/' + id + '/value', a.cookie, 'POST', {})).status, 201);
p = (await call('/positions/' + id, a.cookie)).data;
assert.equal(p.amount, '40');
assert.equal(p.metalProfit, '8.00000000');
assert.equal(p.amount, '50');
assert.equal(p.metalProfit, '18.00000000');
assert.equal(p.valuationAvailable, true);
const cfg = { metalType: 'gold', metalGrams: '2.5', metalPurity: '0.8', autoValuation: true };
const cfg = { metalType: 'gold', metalGrams: '2.5', autoValuation: true };
assert.equal((await call('/metals/' + id, a.cookie, 'PUT', cfg)).status, 200);
assert.equal((await call('/positions/' + id, a.cookie)).data.metalCostPerGram, '12.8');
const controller = new (await import('../src/backup')).BackupBusinessService(db as any);
const backup = await (controller as any).data(a.id);
assert.equal(backup.positions[0].metalCostPerGram, '12.8');
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup })).status,
(await call('/backup/restore-fixture', b.cookie, 'POST', { confirmed: true, backup })).status,
201,
);
const restored = (await call('/positions?kind=asset', b.cookie)).data[0];
assert.equal(restored.metalCostPerGram, '12.8');
assert.equal(restored.metalProfit, '8.00000000');
assert.equal(restored.metalProfit, '18.00000000');
const invalidCost = structuredClone(backup);
Object.assign(invalidCost.positions[0], {
metalType: null,
@@ -367,7 +388,7 @@ test('gram-only creation, optional exact purchase cost, pending totals and backw
);
const old = structuredClone(backup);
delete old.positions[0].metalCostPerGram;
assert.doesNotThrow(() =>
assert.throws(() =>
(require('../src/backup') as typeof import('../src/backup')).validateBackup(old),
);
assert.equal(
@@ -382,7 +403,7 @@ test('gram-only creation, optional exact purchase cost, pending totals and backw
});
assert.equal(next.status, 201);
assert.equal(next.data.valuationAvailable, true);
assert.equal((await call('/positions/' + next.data.id, a.cookie)).data.amount, '40');
assert.equal((await call('/positions/' + next.data.id, a.cookie)).data.amount, '50');
assert.equal(
(await call('/metals/holdings', a.cookie, 'POST', { ...input, metalGrams: '0' })).status,
400,
apps/api/test/integration.test.ts
+14 -12
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import assert from 'node:assert/strict';
@@ -11,7 +12,7 @@ test('real MySQL: authentication, isolation, history, backup and atomic failures
const db = new PrismaClient(),
created: { id: string; username: string }[] = [];
async function call(path: string, method = 'GET', body?: unknown, cookie = '') {
const res = await fetch(base + path, {
const res = await fixtureFetch(base + path, {
method,
headers: {
Origin: origin,
@@ -281,16 +282,17 @@ test('real MySQL: authentication, isolation, history, backup and atomic failures
JSON.stringify(backup),
/"(?:password|passwordHash|token|userId|session|sessionId|sessions|cookie)"\s*:/i,
);
assert.equal((await call('/backup/preview', 'POST', backup, a.cookie)).status, 409);
assert.equal((await call('/backup/preview', 'POST', backup, b.cookie)).status, 201);
assert.equal((await call('/backup/preview-fixture', 'POST', backup, a.cookie)).status, 409);
assert.equal((await call('/backup/preview-fixture', 'POST', backup, b.cookie)).status, 201);
assert.equal(
(await call('/backup/import', 'POST', { confirmed: false, backup }, b.cookie)).status,
(await call('/backup/restore-fixture', 'POST', { confirmed: false, backup }, b.cookie))
.status,
400,
);
assert.equal(
(
await call(
'/backup/import',
'/backup/restore-fixture',
'POST',
{
confirmed: true,
@@ -303,7 +305,7 @@ test('real MySQL: authentication, isolation, history, backup and atomic failures
);
assert.equal((await call('/positions', 'GET', undefined, b.cookie)).data.length, 0);
assert.equal(
(await call('/backup/import', 'POST', { confirmed: true, backup }, b.cookie)).status,
(await call('/backup/restore-fixture', 'POST', { confirmed: true, backup }, b.cookie)).status,
201,
);
assert.equal((await call('/overview', 'GET', undefined, b.cookie)).data.net, o.net);
@@ -326,7 +328,7 @@ test('real MySQL: authentication, isolation, history, backup and atomic failures
sameDay.map((h: { after: string }) => h.after),
);
assert.equal(
(await call('/backup/import', 'POST', { confirmed: true, backup }, b.cookie)).status,
(await call('/backup/restore-fixture', 'POST', { confirmed: true, backup }, b.cookie)).status,
409,
);
assert.equal((await call('/positions', 'GET', undefined, b.cookie)).data.length, 4);
@@ -346,21 +348,21 @@ test('real MySQL: authentication, isolation, history, backup and atomic failures
b.cookie,
);
assert.equal(
(await call('/backup/import', 'POST', { confirmed: true, backup }, b.cookie)).status,
(await call('/backup/restore-fixture', 'POST', { confirmed: true, backup }, b.cookie)).status,
409,
);
const c = await account();
const racing = await Promise.all([
call('/backup/import', 'POST', { confirmed: true, backup }, c.cookie),
call('/backup/import', 'POST', { confirmed: true, backup }, c.cookie),
call('/backup/restore-fixture', 'POST', { confirmed: true, backup }, c.cookie),
call('/backup/restore-fixture', 'POST', { confirmed: true, backup }, c.cookie),
]);
assert.deepEqual(racing.map((r) => r.status).sort(), [201, 409]);
assert.deepEqual(racing.map((r) => r.status).sort(), [201, 400]);
assert.equal((await call('/positions', 'GET', undefined, c.cookie)).data.length, 4);
assert.equal((await call('/auth/logout', 'POST', undefined, a.cookie)).status, 201);
assert.equal((await call('/auth/me', 'GET', undefined, a.cookie)).status, 401);
assert.equal((await call('/backup', 'GET', undefined, a.cookie)).status, 401);
assert.equal(
(await call('/backup/import', 'POST', { confirmed: true, backup }, a.cookie)).status,
(await call('/backup/restore-fixture', 'POST', { confirmed: true, backup }, a.cookie)).status,
401,
);
const login = await call('/auth/login', 'POST', { username: a.username, password: a.password });
apps/api/test/mcp.test.ts
+221 -135
View File
@@ -13,7 +13,7 @@ const root = process.env.TEST_API_URL?.replace(/\/api$/, '') || 'http://127.0.0.
const resource = process.env.MCP_PUBLIC_URL || 'http://localhost:3100/mcp';
const origin = process.env.WEB_ORIGIN === '*' ? 'http://localhost:5173' : process.env.WEB_ORIGIN!;
test('official SDK Streamable HTTP: real MySQL full business paths, drafts, isolation, files and sensitive confirmation', async () => {
test('official SDK Streamable HTTP: real MySQL full business paths, drafts, isolation, hidden permissions and removed capabilities', async () => {
const db = new PrismaClient(),
users: string[] = [],
clients: Client[] = [];
@@ -33,15 +33,22 @@ test('official SDK Streamable HTTP: real MySQL full business paths, drafts, isol
cookie: response.headers.get('set-cookie')?.split(';')[0] || cookie,
};
}
async function fixture(mode = 'direct', selected = ['read', 'draft', 'write', 'sensitive']) {
async function fixture(
mode = 'direct',
selected = mode === 'direct'
? ['read', 'write']
: mode === 'draft'
? ['read', 'draft']
: ['read'],
) {
const username = 'mcp_test_' + randomUUID().slice(0, 12),
password = randomBytes(20).toString('hex');
const registered = await web('', '/auth/register', 'POST', { username, password });
assert.equal(registered.status, 201);
const user = await db.user.findUniqueOrThrow({ where: { username } });
users.push(user.id);
await db.agentPolicy.create({ data: { userId: user.id, mode: 'readonly' } }); // Historical policy must not override connection permissions.
const cookie = registered.cookie;
assert.equal((await web(cookie, '/agent/policy', 'PUT', { mode, password })).status, 200);
const token = await web(cookie, '/agent/tokens', 'POST', {
name: 'Official SDK integration',
days: 1,
@@ -82,7 +89,6 @@ test('official SDK Streamable HTTP: real MySQL full business paths, drafts, isol
async function confirm(a: any, operation: any, extra: any = {}) {
const v = await web(a.cookie, '/agent/operations/' + operation.operationId, 'POST', {
approve: true,
password: a.password,
...extra,
});
assert.equal(v.status, 201, JSON.stringify(v.data));
@@ -113,11 +119,10 @@ test('official SDK Streamable HTTP: real MySQL full business paths, drafts, isol
const a = await fixture(),
b = await fixture(),
d = await fixture('draft', ['read', 'draft']);
await write(a, 'rates_refresh');
await write(a, 'metals_refresh');
await call(a, 'connection_info');
const discovered = await a.client.listTools();
assert.equal(discovered.tools.length, 49);
assert.equal(discovered.tools.length, 39);
assert.ok(!discovered.tools.some((t) => t.name === 'metal_price_set'));
assert.equal(
discovered.tools.find((t) => t.name === 'positions_list')!.annotations!.readOnlyHint,
true,
@@ -310,15 +315,20 @@ test('official SDK Streamable HTTP: real MySQL full business paths, drafts, isol
id: metal,
data: { name: 'gold', category: 'gold', notes: '', archived: false, hidden: false },
});
await write(a, 'metal_price_set', {
metalType: 'gold',
currency: 'CNY',
price: '10.876543210987',
date: day,
await db.metalPrice.create({
data: {
userId: a.id,
metalType: 'gold',
currency: 'CNY',
price: '10.876543210987',
date: new Date(day),
source: 'goldapi',
quotedAt: new Date(),
},
});
await write(a, 'metal_configure', {
id: metal,
data: { metalType: 'gold', metalGrams: '2', metalPurity: '1', autoValuation: true },
data: { metalType: 'gold', metalGrams: '2', autoValuation: true },
});
assert.equal((await call(a, 'position_get', { id: metal })).amount, '21.75308642');
await write(a, 'metal_value', { id: metal });
@@ -328,7 +338,6 @@ test('official SDK Streamable HTTP: real MySQL full business paths, drafts, isol
currency: 'CNY',
metalType: 'gold',
metalGrams: '2',
metalPurity: '1',
autoValuation: true,
metalCostPerGram: '9',
date: day,
@@ -362,9 +371,8 @@ test('official SDK Streamable HTTP: real MySQL full business paths, drafts, isol
assert.notEqual((await call(a, 'position_get', { id: cash })).amount, before);
assert.equal((await write(a, 'schedules_run')).result.executed, 0);
await write(a, 'schedule_delete', { id: plan });
const hidden = (
await write(a, 'position_create', { ...position, name: 'hidden', hidden: true })
).result.id;
const hidden = (await write(a, 'position_create', { ...position, name: 'hidden' })).result.id;
await db.position.update({ where: { id: hidden }, data: { hidden: true } });
await fail(a, 'position_get', { id: hidden });
await fail(a, 'debt_links_set', {
id: debt,
@@ -377,80 +385,45 @@ test('official SDK Streamable HTTP: real MySQL full business paths, drafts, isol
expectedState: (await call(d, 'state_get')).state,
idempotencyKey: randomUUID(),
});
const unlock = await write(a, 'hidden_unlock_request');
await confirm(a, unlock);
for (const removed of [
'rates_refresh',
'metals_refresh',
'metal_price_set',
'backup_export',
'backup_import',
'credentials_change_request',
'hidden_unlock_request',
'hidden_lock',
'data_clear_request',
'import_preview',
]) {
assert.ok(!discovered.tools.some((t) => t.name === removed));
await fail(a, removed);
}
await db.agentGrant.update({
where: { id: a.grantId },
data: { scopes: ['read', 'write', 'hidden_read'] },
});
assert.equal((await call(a, 'position_get', { id: hidden })).id, hidden);
await write(a, 'hidden_lock');
await fail(a, 'position_get', { id: hidden });
const exported = await write(a, 'backup_export');
assert.equal(exported.status, 'pending');
const out = (await confirm(a, exported)).result;
assert.equal((await fetch(out.url)).status, 401);
assert.equal(
(await fetch(out.url, { headers: { Authorization: 'Bearer ' + b.token } })).status,
403,
);
const download = await fetch(out.url, { headers: { Authorization: 'Bearer ' + a.token } });
assert.equal(download.status, 200);
const zipped = Buffer.from(await download.arrayBuffer());
const backup: any = await readBackupZip(zipped);
assert.ok(backup.positions.find((p: any) => p.id === hidden));
assert.equal(JSON.stringify(backup).includes(a.token), false);
const target = await fixture('draft'),
upload = await call(target, 'file_upload_request', { kind: 'backup' }),
form = new FormData();
form.append('file', new Blob([zipped]), 'backup.zip');
const uploaded = await fetch(upload.url, {
method: 'POST',
headers: { Authorization: 'Bearer ' + target.token },
body: form,
await fail(a, 'position_update', {
id: hidden,
data: { name: 'forbidden', category: 'cash', hidden: true },
expectedState: (await call(a, 'state_get')).state,
idempotencyKey: randomUUID(),
});
await db.agentGrant.update({
where: { id: a.grantId },
data: { scopes: ['read', 'write', 'hidden_read', 'hidden_write'] },
});
await write(a, 'position_update', {
id: hidden,
data: { name: 'authorized hidden', category: 'cash', hidden: true },
});
assert.equal(uploaded.status, 200);
const info = await uploaded.json();
assert.ok(info.token);
await call(target, 'file_status', { fileId: upload.fileId });
await call(target, 'import_preview', { token: info.token });
const imported = await write(target, 'backup_import', { token: info.token });
await confirm(target, imported);
assert.equal(
await db.position.count({ where: { userId: target.id } }),
backup.positions.length,
);
const retry = await write(target, 'backup_import', { token: info.token });
assert.equal(
(
await web(target.cookie, '/agent/operations/' + retry.operationId, 'POST', {
approve: true,
password: target.password,
})
).status,
409,
);
assert.equal(
await db.position.count({ where: { userId: target.id } }),
backup.positions.length,
);
const clear = await write(target, 'data_clear_request');
assert.equal(
(
await web(target.cookie, '/agent/operations/' + clear.operationId, 'POST', {
approve: true,
password: target.password,
confirmation: '确定清空',
})
).status,
400,
);
const save = await fetch(root + '/api/backup', { headers: { Cookie: target.cookie } });
assert.equal(save.status, 200);
await save.arrayBuffer();
await confirm(target, clear, { confirmation: '确定清空' });
assert.equal(await db.position.count({ where: { userId: target.id } }), 0);
assert.equal(
(await web(a.cookie, '/agent/policy', 'PUT', { mode: 'readonly', password: a.password }))
.status,
200,
(await db.position.findUniqueOrThrow({ where: { id: hidden } })).name,
'authorized hidden',
);
await db.agentGrant.update({ where: { id: a.grantId }, data: { scopes: ['read'] } });
await fail(a, 'position_create', {
...position,
expectedState: (await call(a, 'state_get')).state,
@@ -495,7 +468,7 @@ test('official SDK Streamable HTTP: real MySQL full business paths, drafts, isol
}
});
test('real concurrent MCP idempotency, stale writes, icon workflow, nested rollback and credentials completion', async () => {
test('real concurrent MCP idempotency, stale writes, icon workflow, nested rollback', async () => {
const db = new PrismaClient();
const username = 'mcp_extra_' + randomUUID().slice(0, 10),
password = randomBytes(20).toString('hex');
@@ -534,12 +507,11 @@ test('real concurrent MCP idempotency, stale writes, icon workflow, nested rollb
try {
assert.equal((await web('/auth/register', 'POST', { username, password })).status, 201);
userId = (await db.user.findUniqueOrThrow({ where: { username } })).id;
await web('/agent/policy', 'PUT', { mode: 'direct', password });
const grant = (
await web('/agent/tokens', 'POST', {
name: 'extra',
days: 1,
scopes: ['read', 'draft', 'write', 'sensitive'],
scopes: ['read', 'write'],
password,
})
).data;
@@ -602,18 +574,15 @@ test('real concurrent MCP idempotency, stale writes, icon workflow, nested rollb
iconIds.push(published.id);
const image = await call(c, 'icon_image', { id: published.id });
assert.equal((await fetch(image.url, { headers })).status, 200);
const shared = await write(c, 'icon_publish', {
const forbiddenShared = await tool(c, 'icon_publish', {
fileId: upload.fileId,
name: '测试共享图标',
shared: true,
expectedState: (await call(c, 'state_get')).state,
idempotencyKey: randomUUID(),
});
assert.equal(shared.status, 'pending');
assert.equal(
(await web('/agent/operations/' + shared.operationId, 'POST', { approve: true, password }))
.status,
201,
);
iconIds.push((await call(c, 'operation_get', { operationId: shared.operationId })).result.id);
assert.equal(forbiddenShared.isError, true);
assert.equal(await db.icon.count({ where: { ownerId: userId, shared: true } }), 0);
// A failed paired transfer leaves neither side changed, including inside outer
// idempotency transaction and nested service savepoints.
const account = one.result.id,
@@ -670,36 +639,6 @@ test('real concurrent MCP idempotency, stale writes, icon workflow, nested rollb
const management = (await web('/agent')).data;
assert.ok(management.calls.some((v: any) => v.status === 'error'));
assert.equal(JSON.stringify(management).includes(grant.token), false);
const operation = await write(c, 'credentials_change_request');
const replacement = randomBytes(20).toString('hex');
assert.equal(
(
await web('/agent/operations/' + operation.operationId, 'POST', {
approve: true,
password,
newPassword: replacement,
})
).status,
201,
);
assert.equal(
(await call(c, 'operation_get', { operationId: operation.operationId })).status,
'completed',
);
assert.equal(
(
await tool(c, 'position_create', {
...position,
idempotencyKey: randomUUID(),
expectedState: (await call(c, 'state_get')).state,
})
).isError,
true,
);
assert.equal(
(await web('/auth/login', 'POST', { username, password: replacement })).status,
201,
);
} finally {
for (const c of clients) await c.close().catch(() => {});
await db.icon.deleteMany({ where: { id: { in: iconIds } } });
@@ -726,7 +665,7 @@ test('official SDK OAuth discovery, DCR, PKCE, consent, one-use codes, rotation
grant_types: ['authorization_code', 'refresh_token'],
response_types: ['code'],
token_endpoint_auth_method: 'none',
scope: 'read draft write sensitive',
scope: 'read write',
},
clientInformation: () => saved,
saveClientInformation: (v) => {
@@ -766,19 +705,22 @@ test('official SDK OAuth discovery, DCR, PKCE, consent, one-use codes, rotation
const registered = await post('/api/auth/register', { username, password });
assert.equal(registered.status, 201);
userId = (await db.user.findUniqueOrThrow({ where: { username } })).id;
assert.equal(
await auth(provider, { serverUrl: resource, scope: 'read draft write sensitive' }),
'REDIRECT',
);
assert.equal(await auth(provider, { serverUrl: resource, scope: 'read write' }), 'REDIRECT');
assert.ok(authorization);
const redirected = await fetch(authorization!, { redirect: 'manual' });
assert.equal(redirected.status, 302);
const location = new URL(redirected.headers.get('location')!);
const id = location.searchParams.get('agent_authorization');
assert.ok(id);
const deniedEscalation = await post(
'/api/agent/authorizations/' + id,
{ approve: true, scopes: ['read', 'write', 'hidden_read'] },
registered.cookie,
);
assert.equal(deniedEscalation.status, 400);
const consent = await post(
'/api/agent/authorizations/' + id,
{ approve: true },
{ approve: true, scopes: ['read', 'write'] },
registered.cookie,
);
assert.equal(consent.status, 201);
@@ -795,7 +737,7 @@ test('official SDK OAuth discovery, DCR, PKCE, consent, one-use codes, rotation
await client.connect(
new StreamableHTTPClientTransport(new URL(resource), { authProvider: provider }),
);
assert.ok((await client.listTools()).tools.length >= 40);
assert.ok((await client.listTools()).tools.length === 39);
await client.close();
async function exchange(params: Record<string, string>) {
const r = await fetch(root + '/token', {
@@ -888,3 +830,147 @@ test('official SDK OAuth discovery, DCR, PKCE, consent, one-use codes, rotation
await db.$disconnect();
}
});
test('fixed PAT durations, permanent session renewal, expiry, isolation and revocation are real', async () => {
const db = new PrismaClient(),
users: string[] = [],
clients: Client[] = [];
const { createHash } = await import('node:crypto'),
{ hash } = await import('bcryptjs');
const password = 'Temporary-pat-test-Only!';
async function fixture() {
const u = await db.user.create({
data: {
username: 'pat_' + randomUUID(),
passwordHash: await hash(password, 4),
idleMinutes: 0,
},
});
users.push(u.id);
const token = randomBytes(32).toString('hex');
await db.session.create({
data: {
id: createHash('sha256').update(token).digest('hex'),
userId: u.id,
expiresAt: new Date(Date.now() + 86400000),
},
});
return { id: u.id, cookie: 'wp_session=' + token };
}
async function web(u: any, path: string, method = 'GET', body?: unknown) {
const r = await fetch(root + '/api' + path, {
method,
headers: {
Origin: origin,
Cookie: u.cookie,
...(body ? { 'Content-Type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
return { status: r.status, data: await r.json() };
}
try {
const a = await fixture(),
b = await fixture();
let permanent: any;
const issuedTokens = new Map<string, string>();
for (const days of [1, 3, 7, 30, 365, null]) {
const issued = await web(a, '/agent/tokens', 'POST', {
name: 'expiry fixture',
scopes: ['read'],
days,
password,
});
assert.equal(issued.status, 201, JSON.stringify(issued.data));
issuedTokens.set(issued.data.id, issued.data.token);
const row = await db.agentGrant.findUniqueOrThrow({ where: { id: issued.data.id } });
assert.equal(row.accessDigest, createHash('sha256').update(issued.data.token).digest('hex'));
if (days === null) {
assert.equal(row.expiresAt, null);
permanent = issued.data;
} else {
assert.ok(row.expiresAt);
assert.ok(Math.abs(+row.expiresAt! - Date.now() - days * 86400000) < 5000);
}
}
assert.equal(
(
await web(a, '/agent/tokens', 'POST', {
name: 'invalid duration',
scopes: ['read'],
days: 2,
password,
})
).status,
400,
);
for (const scopes of [
['read', 'sensitive'],
['read', 'draft', 'write'],
['read', 'hidden_write'],
]) {
assert.equal(
(
await web(a, '/agent/tokens', 'POST', {
name: 'invalid scopes',
scopes,
days: 1,
password,
})
).status,
400,
);
}
assert.equal((await web(a, '/agent/policy', 'PUT', { mode: 'direct', password })).status, 404);
const management = await web(a, '/agent');
assert.equal(management.data.capabilities.length, 39);
assert.ok(!management.data.capabilities.some((t: any) => t.name === 'metal_price_set'));
assert.equal((await web(b, '/agent')).data.grants.length, 0);
assert.equal((await web(b, '/agent/connections/' + permanent.id, 'DELETE')).status, 200);
assert.equal(
(await db.agentGrant.findUniqueOrThrow({ where: { id: permanent.id } })).revokedAt,
null,
);
const row = await db.agentGrant.findUniqueOrThrow({ where: { id: permanent.id } });
await db.session.delete({ where: { id: row.sessionId } });
const client = new Client({ name: 'Permanent PAT test', version: '1.31.0' });
clients.push(client);
await client.connect(
new StreamableHTTPClientTransport(new URL(resource), {
requestInit: { headers: { Authorization: 'Bearer ' + permanent.token } },
}),
);
const result: any = await client.callTool({ name: 'connection_info', arguments: {} });
assert.ok(!result.isError, JSON.stringify(result));
assert.equal(result.structuredContent.data.expiresAt, null);
const business: any = await client.callTool({
name: 'positions_list',
arguments: { limit: 1 },
});
assert.ok(!business.isError, JSON.stringify(business));
assert.ok(
(await db.session.findUniqueOrThrow({ where: { id: row.sessionId } })).expiresAt > new Date(),
);
assert.equal((await web(a, '/agent/connections/' + permanent.id, 'DELETE')).status, 200);
await assert.rejects(() => client.listTools());
const finite = management.data.grants.find((g: any) => g.expiresAt);
await db.agentGrant.update({ where: { id: finite.id }, data: { expiresAt: new Date(0) } });
const expiredClient = new Client({ name: 'Expired PAT test', version: '1.31.0' });
clients.push(expiredClient);
await assert.rejects(() =>
expiredClient.connect(
new StreamableHTTPClientTransport(new URL(resource), {
requestInit: { headers: { Authorization: 'Bearer ' + issuedTokens.get(finite.id) } },
}),
),
);
const expired = await web(a, '/agent');
assert.equal(
expired.data.grants.find((g: any) => g.id === finite.id).expiresAt,
'1970-01-01T00:00:00.000Z',
);
} finally {
for (const c of clients) await c.close().catch(() => {});
await db.user.deleteMany({ where: { id: { in: users } } });
await db.$disconnect();
}
});
apps/api/test/privacy.test.ts
+14 -7
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import assert from 'node:assert/strict';
@@ -9,7 +10,7 @@ test('privacy, minute history, backup-gated clear and idle sessions remain user
const db = new PrismaClient(),
names: string[] = [];
async function call(path: string, method = 'GET', data?: unknown, cookie = '') {
const res = await fetch(base + path, {
const res = await fixtureFetch(base + path, {
method,
headers: {
Origin: process.env.WEB_ORIGIN === '*' ? 'http://localhost:5173' : process.env.WEB_ORIGIN!,
@@ -118,7 +119,7 @@ test('privacy, minute history, backup-gated clear and idle sessions remain user
);
assert.equal(history[1].delta, '15');
const backup = (await call('/backup', 'GET', undefined, a.cookie)).data;
assert.equal(backup.version, 2);
assert.equal(backup.version, 9);
assert.equal(backup.positions.find((p: { id: string }) => p.id === hidden).hidden, true);
assert.equal(
backup.positions.find((p: { id: string }) => p.id === hidden).revisions[0].date,
@@ -192,7 +193,7 @@ test('privacy, minute history, backup-gated clear and idle sessions remain user
);
assert.equal((await call('/overview', 'GET', undefined, c.cookie)).data.net, '20.00');
assert.equal(
(await call('/backup/import', 'POST', { confirmed: true, backup }, b.cookie)).status,
(await call('/backup/restore-fixture', 'POST', { confirmed: true, backup }, b.cookie)).status,
201,
);
assert.equal((await call('/overview', 'GET', undefined, b.cookie)).data.net, '27.00');
@@ -267,11 +268,17 @@ test('privacy, minute history, backup-gated clear and idle sessions remain user
assert.equal((await call('/auth/me', 'GET', undefined, otherSession.cookie)).status, 200);
const login = await call('/auth/login', 'POST', { username: a.username, password: a.password });
assert.equal(
(await call('/backup/import', 'POST', { confirmed: true, backup: legacy }, login.cookie))
.status,
201,
(
await call(
'/backup/restore-fixture',
'POST',
{ confirmed: true, backup: legacy },
login.cookie,
)
).status,
400,
);
assert.equal((await call('/positions', 'GET', undefined, login.cookie)).data.length, 2);
assert.equal((await call('/positions', 'GET', undefined, login.cookie)).data.length, 0);
} finally {
for (const username of names) await db.user.deleteMany({ where: { username } });
await db.$disconnect();
apps/api/test/queries.test.ts
+6 -3
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import assert from 'node:assert/strict';
@@ -15,7 +16,9 @@ test('bounded APIs preserve seeds, predecessor balances, pagination, archive and
sessionId = createHash('sha256').update(token).digest('hex');
let restoredUserId: string | undefined;
async function call(path: string) {
const response = await fetch(base + path, { headers: { Cookie: 'wp_session=' + token } });
const response = await fixtureFetch(base + path, {
headers: { Cookie: 'wp_session=' + token },
});
return { status: response.status, data: await response.json() };
}
try {
@@ -142,7 +145,7 @@ test('bounded APIs preserve seeds, predecessor balances, pagination, archive and
date: '2026-09-03T00:01',
};
const post = async (path: string, body: unknown, cookie = token) => {
const response = await fetch(base + path, {
const response = await fixtureFetch(base + path, {
method: 'POST',
headers: {
Cookie: 'wp_session=' + cookie,
@@ -179,7 +182,7 @@ test('bounded APIs preserve seeds, predecessor balances, pagination, archive and
},
});
assert.equal(
(await post('/backup/import', { confirmed: true, backup }, restoredToken)).status,
(await post('/backup/restore-fixture', { confirmed: true, backup }, restoredToken)).status,
201,
);
const restoredTransfer = await db.transfer.findFirstOrThrow({ where: { userId: restored.id } });
apps/api/test/security-backup.test.ts
+31 -3
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import assert from 'node:assert/strict';
@@ -11,7 +12,7 @@ test('credentials rotate sessions; deleting paired and empty histories preserves
ids: string[] = [];
const origin = process.env.WEB_ORIGIN === '*' ? 'http://localhost:5173' : process.env.WEB_ORIGIN!;
async function call(path: string, cookie = '', method = 'GET', body?: unknown) {
const res = await fetch(base + path, {
const res = await fixtureFetch(base + path, {
method,
headers: {
Cookie: cookie,
@@ -141,6 +142,30 @@ test('credentials rotate sessions; deleting paired and empty histories preserves
const backup: any = await readBackupZip(bytes);
assert.equal(backup.positions.find((p: any) => p.id === emptyId).revisions.length, 0);
assert.equal(backup.positions.find((p: any) => p.id === sourceId).revisions[0].amount, '-10');
const beforeRejected = await db.position.count({ where: { userId: b.id } });
for (const version of [1, 2, 3, 9]) {
const unsupported = new FormData();
unsupported.set(
'file',
new Blob([JSON.stringify({ ...backup, version })], { type: 'application/json' }),
'backup.json',
);
const rejected = await fetch(base + '/backup/upload', {
method: 'POST',
headers: { Cookie: b.cookie, Origin: origin },
body: unsupported,
});
assert.equal(rejected.status, 400);
}
for (const path of ['/backup/import', '/backup/preview']) {
const removed = await fetch(base + path, {
method: 'POST',
headers: { Cookie: b.cookie, Origin: origin, 'Content-Type': 'application/json' },
body: JSON.stringify({ confirmed: true, backup }),
});
assert.equal(removed.status, 404);
}
assert.equal(await db.position.count({ where: { userId: b.id } }), beforeRejected);
const form = new FormData();
form.append('file', new Blob([bytes]), 'backup.zip');
const upload = await fetch(base + '/backup/upload', {
@@ -234,10 +259,13 @@ test('credentials rotate sessions; deleting paired and empty histories preserves
emptyAccountData.positions.find((p: any) => p.id === sourceId).revisions.at(-1).amount,
'-5',
);
assert.equal((await call('/backup/preview', b.cookie, 'POST', emptyAccountData)).status, 409);
assert.equal(
(await call('/backup/preview-fixture', b.cookie, 'POST', emptyAccountData)).status,
409,
);
const fresh = await user();
assert.equal(
(await call('/backup/preview', fresh.cookie, 'POST', emptyAccountData)).status,
(await call('/backup/preview-fixture', fresh.cookie, 'POST', emptyAccountData)).status,
201,
);
} finally {
apps/api/test/settings-plans.test.ts
+12 -3
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import { request } from 'node:http';
@@ -28,6 +29,14 @@ async function fixture() {
// Give this fixture suite its own loopback source address so independent auth
// scenarios do not consume the existing suite's per-IP production rate limit.
async function call(path: string, cookie: string, method = 'GET', body?: unknown) {
if (path.endsWith('-fixture')) {
const response = await fixtureFetch(base + path, {
method,
headers: { Cookie: cookie, Origin: origin, 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
return { status: response.status, data: await response.json(), cookie: null };
}
const data = body === undefined ? undefined : JSON.stringify(body);
return new Promise<{ status: number; data: any; cookie: string | null }>((resolve, reject) => {
const req = request(
@@ -127,7 +136,7 @@ test('session duration boundaries, privacy isolation and card settings survive b
assert.equal(backup.preferences.sessionHours, 720);
assert.equal(backup.preferences.requireHiddenPassword, false);
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup })).status,
(await call('/backup/restore-fixture', b.cookie, 'POST', { confirmed: true, backup })).status,
201,
);
const imported = (await call('/settings', b.cookie)).data;
@@ -138,8 +147,8 @@ test('session duration boundaries, privacy isolation and card settings survive b
delete backup.preferences.requireHiddenPassword;
delete backup.preferences.overviewCards;
assert.equal(
(await call('/backup/import', c.cookie, 'POST', { confirmed: true, backup })).status,
201,
(await call('/backup/restore-fixture', c.cookie, 'POST', { confirmed: true, backup })).status,
400,
);
const legacy = (await call('/settings', c.cookie)).data;
assert.equal(legacy.sessionHours, 168);
apps/api/test/transfers.test.ts
+6 -4
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import assert from 'node:assert/strict';
@@ -11,7 +12,7 @@ test('transfers are atomic, scoped, retry-safe, decimal exact and included in ba
const db = new PrismaClient(),
names: string[] = [];
async function call(path: string, cookie = '', method = 'GET', data?: unknown) {
const r = await fetch(base + path, {
const r = await fixtureFetch(base + path, {
method,
headers: {
Cookie: cookie,
@@ -227,12 +228,13 @@ test('transfers are atomic, scoped, retry-safe, decimal exact and included in ba
const broken = structuredClone(backup);
broken.transfers[0].amount = '999';
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup: broken })).status,
(await call('/backup/restore-fixture', b.cookie, 'POST', { confirmed: true, backup: broken }))
.status,
400,
);
assert.equal(await db.transfer.count({ where: { userId: b.id } }), 0);
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup })).status,
(await call('/backup/restore-fixture', b.cookie, 'POST', { confirmed: true, backup })).status,
201,
);
const restored = (await call('/backup', b.cookie)).data;
@@ -241,7 +243,7 @@ test('transfers are atomic, scoped, retry-safe, decimal exact and included in ba
assert.equal((await call('/settings', b.cookie)).data.showNotes, true);
const c = await account();
assert.equal(
(await call('/backup/import', c.cookie, 'POST', { confirmed: true, backup })).status,
(await call('/backup/restore-fixture', c.cookie, 'POST', { confirmed: true, backup })).status,
201,
);
assert.equal((await call('/settings', c.cookie)).data.showNotes, false);
apps/api/test/update-integration.test.ts
+3 -2
View File
@@ -1,3 +1,4 @@
import { fixtureFetch } from './backup-fixture';
import 'dotenv/config';
import { test } from 'node:test';
import assert from 'node:assert/strict';
@@ -12,7 +13,7 @@ test('real MySQL: groups, scheduled atomic execution, calendar, privacy and ZIP
const minute = (delta = 0) =>
new Date(Date.now() + delta + 8 * 3600000).toISOString().slice(0, 16);
async function call(path: string, cookie = '', method = 'GET', body?: unknown) {
const res = await fetch(base + path, {
const res = await fixtureFetch(base + path, {
method,
headers: {
Cookie: cookie,
@@ -186,7 +187,7 @@ test('real MySQL: groups, scheduled atomic execution, calendar, privacy and ZIP
const backup = (await call('/backup', a.cookie)).data;
assert.equal(backup.schedules.length, 3);
assert.equal(
(await call('/backup/import', b.cookie, 'POST', { confirmed: true, backup })).status,
(await call('/backup/restore-fixture', b.cookie, 'POST', { confirmed: true, backup })).status,
201,
);
assert.equal((await call('/schedules/run', b.cookie, 'POST', {})).data.executed, 0);
apps/api/test/zip.test.ts
+50 -99
View File
@@ -7,14 +7,24 @@ import { packBackup, readBackupZip } from '../src/zip';
const empty = () =>
validateBackup({
format: 'worthpath',
version: 2,
version: 9,
exportedAt: new Date().toISOString(),
baseCurrency: 'CNY',
preferences: { hiddenMenus: ['asset'], showNotes: false, idleMinutes: 9 },
preferences: {
hiddenMenus: ['asset'],
showNotes: false,
idleMinutes: 9,
accountGroupOrder: [],
sessionHours: 168,
requireHiddenPassword: true,
overviewCards: ['net'],
includeIndependentAssets: true,
},
currencies: ['CNY'],
icons: [],
transfers: [],
schedules: [],
metalPrices: [],
positions: [],
rates: [],
links: [],
@@ -48,7 +58,10 @@ test('ZIP contains separate JSON files and restores settings without authenticat
'settings.json',
'transfers.json',
]);
assert.doesNotMatch(JSON.stringify(contents), /password|token|session|userId/i);
assert.doesNotMatch(
Object.values(contents).join('\n'),
/"(?:passwordHash|password|token|sessionId|userId|accessDigest|refreshDigest)"/i,
);
assert.deepEqual(validateBackup(await readBackupZip(await archive(contents))), b);
});
test('ZIP rejects incomplete files, tampering, unknown entries and invalid entry names', async () => {
@@ -69,6 +82,15 @@ test('backup accepts over 1000 positions, 10000 revisions per position and 20000
const position = (count: number) => ({
id: randomUUID(),
name: 'count acceptance',
groupName: '',
iconId: null,
included: true,
importedFromId: null,
metalType: null,
metalGrams: null,
metalCostPerGram: null,
metalPurity: '1',
autoValuation: false,
kind: 'asset',
side: 'asset',
category: 'other',
@@ -100,102 +122,31 @@ test('backup accepts over 1000 positions, 10000 revisions per position and 20000
);
});
test('legacy v3 ZIP remains readable without icons', async () => {
const contents = packBackup(empty());
delete contents['icons.json'];
delete contents['transfers.json'];
delete contents['schedules.json'];
const manifest = JSON.parse(contents['manifest.json']);
manifest.version = 3;
manifest.files = manifest.files.filter(
(f: { name: string }) => !['icons.json', 'transfers.json', 'schedules.json'].includes(f.name),
);
contents['manifest.json'] = JSON.stringify(manifest);
const restored = validateBackup(await readBackupZip(await archive(contents)));
assert.equal(restored.icons, undefined);
assert.deepEqual(restored.positions, []);
test('all historical ZIP versions and JSON formats are rejected', async () => {
for (const version of [3, 4, 5, 6, 7, 8]) {
const contents = packBackup(empty());
const manifest = JSON.parse(contents['manifest.json']);
manifest.version = version;
contents['manifest.json'] = JSON.stringify(manifest);
await assert.rejects(async () => readBackupZip(await archive(contents)));
}
for (const version of [1, 2, 3]) assert.throws(() => validateBackup({ ...empty(), version }));
});
test('legacy v4 ZIP remains readable without transfers', async () => {
const contents = packBackup(empty());
delete contents['transfers.json'];
delete contents['schedules.json'];
const manifest = JSON.parse(contents['manifest.json']);
manifest.version = 4;
manifest.files = manifest.files.filter(
(f: { name: string }) => !['transfers.json', 'schedules.json'].includes(f.name),
);
contents['manifest.json'] = JSON.stringify(manifest);
const restored = validateBackup(await readBackupZip(await archive(contents)));
assert.deepEqual(restored.icons, []);
assert.equal(restored.transfers, undefined);
assert.equal(restored.preferences?.showNotes, false);
assert.deepEqual(restored.preferences?.hiddenMenus, ['asset']);
});
test('ZIP v7 restores groups and schedules while v6 remains readable', async () => {
const id = randomUUID(),
stamp = new Date().toISOString();
const b = validateBackup({
...empty(),
positions: [
{
id,
name: '账户',
groupName: '日常',
kind: 'account',
side: 'asset',
category: 'bank',
currency: 'CNY',
notes: '',
archived: false,
hidden: false,
createdAt: stamp,
updatedAt: stamp,
revisions: [
{
id: randomUUID(),
amount: '-10',
date: '2026-09-01T10:00',
notes: '',
reason: 'balance',
createdAt: stamp,
updatedAt: stamp,
},
],
},
],
schedules: [
{
id: randomUUID(),
name: '租金',
operation: 'expense',
sourceId: id,
targetId: null,
amount: '100',
received: '0',
nextAt: '2026-11-01T10:00',
intervalDays: 30,
enabled: true,
notes: '',
},
],
});
const contents = packBackup(b);
assert.deepEqual(validateBackup(await readBackupZip(await archive(contents))), b);
delete contents['schedules.json'];
const manifest = JSON.parse(contents['manifest.json']);
manifest.version = 6;
manifest.files = manifest.files.filter((f: { name: string }) => f.name !== 'schedules.json');
contents['manifest.json'] = JSON.stringify(manifest);
assert.equal(validateBackup(await readBackupZip(await archive(contents))).schedules, undefined);
});
test('ZIP settings retain group order while missing legacy order remains optional', async () => {
test('current backups require complete settings and metadata, with no legacy defaults', async () => {
const b = empty();
b.preferences!.accountGroupOrder = ['理财', '', '未分组', '日常'];
const restored = validateBackup(await readBackupZip(await archive(packBackup(b))));
assert.deepEqual(restored.preferences!.accountGroupOrder, b.preferences!.accountGroupOrder);
const legacy = validateBackup(await readBackupZip(await archive(packBackup(empty()))));
assert.equal(legacy.preferences!.accountGroupOrder, undefined);
b.preferences.accountGroupOrder = ['日常', ''];
assert.deepEqual(validateBackup(await readBackupZip(await archive(packBackup(b)))), b);
for (const key of Object.keys(b.preferences)) {
const incomplete = structuredClone(b);
delete (incomplete.preferences as any)[key];
assert.throws(() => validateBackup(incomplete));
}
for (const key of ['icons', 'transfers', 'schedules', 'metalPrices']) {
const incomplete = structuredClone(b);
delete (incomplete as any)[key];
assert.throws(() => validateBackup(incomplete));
}
assert.throws(() =>
validateBackup({ ...b, preferences: { ...b.preferences, showSidebar: false } }),
);
});
apps/web/src/AgentConnections.tsx
+527 -242
View File
@@ -5,14 +5,14 @@ type Connection = {
id: string;
name: string;
scopes: string[];
expiresAt: string;
expiresAt: string | null;
revokedAt: string | null;
clientId: string | null;
};
type Operation = { id: string; tool: string; status: string; expiresAt: string; createdAt: string };
type Management = {
capabilities: { name: string; description: string; scope: string; destructive?: boolean }[];
mcpUrl: string;
mode: string;
grants: Connection[];
operations: Operation[];
calls: { id: string; tool: string; status: string; createdAt: string }[];
@@ -23,8 +23,6 @@ type Preview = {
status: string;
description: string;
impact: unknown;
web?: string;
sensitive: boolean;
result?: unknown;
};
type Consent = {
@@ -34,6 +32,72 @@ type Consent = {
redirectUri: string;
resource: string;
};
const scopeDetails = [
{
id: 'read',
title: '只读查询',
summary: '查看账目和状态，不修改金额',
detail:
'查询账户、资产、债务、关联、余额和历史、净资产趋势、日历、计划与执行记录、汇率、贵金属报价、设置和图标；读取本连接操作及文件状态。隐藏账户默认不允许读取，须额外授权。',
},
{
id: 'draft',
title: '创建草稿',
summary: '提出普通修改，等待你在网页确认',
detail:
'可提出创建或编辑持仓、余额/估值更新、转账和借贷还款、历史更正/删除、计划管理、分组排序、设置修改及私有图标上传等普通操作。草稿明确保存参数和影响，10 分钟过期；不会直接入账。',
},
{
id: 'write',
title: '普通写入',
summary: '普通修改直接执行',
detail:
'覆盖普通修改和创建草稿的操作。授予 write 后普通修改直接执行；draft 等待网页确认；read 拒绝修改。归档、历史删除和转账撤销也属于普通写入，请按所需范围授权。',
},
];
const durationOptions = [
['1', '1 天'],
['3', '3 天'],
['7', '7 天'],
['30', '30 天'],
['365', '1 年（365 天）'],
['permanent', '永久（可撤销）'],
];
const capabilityGroups = [
{
title: '账户、资产与债务',
pattern: /^(positions_|position_|balance_|metal_holding|metal_configure|metal_value)/,
summary: '创建和管理持仓、分组、图标、归档与计入开关；贵金属按克数管理。',
},
{
title: '资金变化与历史',
pattern: /^(transfer|loan|debt|history|revision)/,
summary: '转账、借入借出、收款还款、记录更正、删除与撤销，沿用金额重算规则。',
},
{
title: '统计、汇率与计划',
pattern: /^(overview|trend|calendar|schedule|rates|metals_)/,
summary: '净资产与趋势、日历筛选、定时计划及执行记录、汇率和参考报价。',
},
{
title: '设置与私有图标',
pattern: /^(settings|icons|icon_|backup|import|data_|credentials|hidden|file_)/,
summary: '非安全类用户设置、私有图库上传与读取；敏感操作仅在网站执行。',
},
];
function instructions(url: string) {
return [
'请使用已连接的 WorthPath MCP 服务处理我的资产与负债，服务地址：' + url,
'接入使用 Streamable HTTP。支持 OAuth 的客户端使用该地址发现授权服务，并由我在 WorthPath 网页登录授权；支持自定义 Bearer 头的客户端可在安全的凭据设置中填写个人令牌。不要让我把密码或令牌粘贴到对话中。',
'先 tools/list 发现工具，调用 connection_info 核对权限：read 只读，draft 创建待网页确认的草稿，write 直接普通写入。隐藏账户读写以连接附加授权为准。',
'查询：用 positions_list 搜索对象；遇到同名先让我选择稳定 ID；按 limit/offset 或 cursor 翻页。金额和克数使用十进制字符串，业务时间是 UTC+8 的 YYYY-MM-DD 或 YYYY-MM-DDTHH:mm。',
'写入：先 state_get 取得 state，使用 expectedState 与唯一 idempotencyKey 调用所需工具。网络重试保持键和全部参数一致；状态冲突则重新查询并换键。不要把估值更新、转账、还款或负债变化互相替代。',
'若返回 pending，把 confirmationUrl 给我，由我在网页审阅并确认；用 operation_get 轮询最终结果，不能用 confirmed=true 代替人类确认，也不能把草稿称为已完成。',
'MCP 不提供密码修改、清空数据、备份导出恢复、共享图标发布及汇率或报价修改；这些流程由我在网站操作。',
'我接下来会告诉你具体任务；在我提出任务前先不要修改数据。未发现的工具或未授予的权限请如实告知，不要猜测成功。',
].join('\n\n');
}
export function AgentConnections() {
const [data, setData] = useState<Management | null>(null),
[error, setError] = useState(''),
@@ -41,7 +105,14 @@ export function AgentConnections() {
[token, setToken] = useState(''),
[preview, setPreview] = useState<Preview | null>(null),
[consent, setConsent] = useState<Consent | null>(null),
[busy, setBusy] = useState(false);
[busy, setBusy] = useState(false),
[tokenPermission, setTokenPermission] = useState('read'),
[tokenHiddenRead, setTokenHiddenRead] = useState(false),
[tokenHiddenWrite, setTokenHiddenWrite] = useState(false),
[agentView, setAgentView] = useState('connect'),
[consentLevel, setConsentLevel] = useState('read'),
[consentHiddenRead, setConsentHiddenRead] = useState(false),
[consentHiddenWrite, setConsentHiddenWrite] = useState(false);
const load = async () => setData(await api<Management>('/agent'));
const act = async (work: () => Promise<unknown>) => {
if (busy) return;
@@ -68,216 +139,417 @@ export function AgentConnections() {
if (operation) await show(operation);
});
}, []);
const copy = async (text: string, label: string) => {
try {
await navigator.clipboard.writeText(text);
setMessage(label);
} catch {
setError('复制失败，请从下方可选中文本手动复制');
}
};
return (
<section className="panel agent-panel">
<h2>连接 Agent</h2>
<div className="agent-heading">
<div>
<h2>连接 Agent</h2>
<p className="muted">管理接入、操作权限和需要你确认的修改。</p>
</div>
{data && <span className="badge">{data.capabilities.length} 个工具 · 按连接授权</span>}
</div>
{error && (
<p role="alert" className="danger-text">
{error}
</p>
)}
{message && <p role="status">{message}</p>}
{message && (
<p role="status" className="agent-notice">
{message}
</p>
)}
{data && (
<>
<p>远程 MCP 地址</p>
<code className="agent-address">{data.mcpUrl}</code>
<button
className="secondary"
type="button"
onClick={() => void navigator.clipboard.writeText(data.mcpUrl)}
>
复制地址
</button>
<p className="muted">
支持 Streamable HTTP。OAuth 客户端使用此地址发现授权信息，浏览器登录 WorthPath
后审核连接名称、回调地址和权限。访问令牌每小时过期，刷新令牌最多 30
天并在使用时轮换。个人令牌适用于支持 Bearer 头的客户端。
</p>
<p className="muted">
已验证客户端：官方 TypeScript SDK 1.31.0（OAuth / Bearer）。其他 Agent
尚未验证；不会保证任意客户端兼容。
</p>
<details>
<summary>官方 SDK 的已验证接入配置</summary>
<pre>{`new StreamableHTTPClientTransport(new URL(${JSON.stringify(data.mcpUrl)}), {\n requestInit: { headers: { Authorization: 'Bearer ' + process.env.MCP_ACCESS_TOKEN } }\n});`}</pre>
<button
className="secondary"
type="button"
onClick={() =>
void navigator.clipboard.writeText(
`$env:MCP_SERVER_URL=${JSON.stringify(data.mcpUrl)}\npnpm --filter @worthpath/api mcp:probe`,
<div className="agent-layout">
<nav className="agent-tabs agent-wide" aria-label="Agent 功能分区">
{[
['connect', '开始连接'],
['tools', '权限与工具'],
['connections', '连接管理'],
['operations', '操作记录'],
].map(([value, label]) => (
<button
key={value}
type="button"
className={agentView === value ? 'primary' : 'secondary'}
aria-pressed={agentView === value}
onClick={() => setAgentView(value)}
>
{label}
{value === 'operations' &&
data.operations.some(
(o) => o.status === 'pending' && new Date(o.expiresAt) > new Date(),
)
}
>
复制本项目诊断客户端命令
</button>
<p className="muted">
先在终端设置 MCP_ACCESS_TOKEN，再运行复制的命令。完整 OAuth 示例及安全存储说明见
docs/mcp.md；此配置仅针对官方 SDK 1.31.0。
</p>
</details>
<form
onSubmit={(e) => {
e.preventDefault();
const f = new FormData(e.currentTarget),
form = e.currentTarget;
void act(async () => {
await api('/agent/policy', 'PUT', {
mode: f.get('mode'),
password: f.get('password'),
});
form.reset();
setMessage('写入策略已保存');
});
}}
>
<h3>写入策略</h3>
<select name="mode" defaultValue={data.mode} key={data.mode}>
<option value="readonly">只读</option>
<option value="draft">创建草稿，由网页确认</option>
<option value="direct">已授权 write 的连接可直接普通写入</option>
</select>
<input
name="password"
type="password"
autoComplete="current-password"
required
placeholder="当前密码"
/>
<button className="secondary" disabled={busy}>
保存策略
</button>
</form>
<h3>OAuth 授权与个人令牌</h3>
<p className="muted">
read 查询；draft 创建草稿；write 按写入策略执行普通写入；sensitive
发起敏感操作，仍须网页验证密码。令牌到期可新建并撤销旧令牌。
</p>
<form
onSubmit={(e) => {
e.preventDefault();
const form = e.currentTarget,
f = new FormData(form);
void act(async () => {
const v = await api<{ token: string }>('/agent/tokens', 'POST', {
name: f.get('name'),
days: Number(f.get('days')),
password: f.get('password'),
scopes: f.getAll('scope'),
});
setToken(v.token);
form.reset();
});
}}
>
<input name="name" required maxLength={100} placeholder="连接名称" />
<input
name="days"
type="number"
min={1}
max={90}
defaultValue={30}
required
aria-label="有效天数"
/>
{['read', 'draft', 'write', 'sensitive'].map((s) => (
<label key={s}>
<input
type="checkbox"
name="scope"
value={s}
defaultChecked={s === 'read'}
required={s === 'read'}
/>
{s}
</label>
? ' · 待确认'
: ''}
</button>
))}
<input
name="password"
type="password"
required
autoComplete="current-password"
placeholder="当前密码"
/>
<button className="secondary" disabled={busy}>
创建个人令牌
</button>
</form>
{token && (
<div role="status">
<p>完整令牌仅显示这一次，请妥善保存。</p>
<code className="agent-address">{token}</code>
<button
className="secondary"
type="button"
onClick={() => void navigator.clipboard.writeText(token)}
>
复制令牌
</button>
<button className="secondary" type="button" onClick={() => setToken('')}>
隐藏令牌
</button>
</div>
</nav>
{agentView === 'connect' && (
<>
<section className="agent-card agent-wide">
<h3>开始连接</h3>
<p>远程 MCP 地址</p>
<div className="agent-copy-row">
<code className="agent-address">{data.mcpUrl}</code>
<button
className="secondary"
type="button"
onClick={() => void copy(data.mcpUrl, 'MCP 地址已复制')}
>
复制地址
</button>
</div>
<p className="muted">在客户端添加地址，完成网页授权，再复制教程并描述任务。</p>
<details className="agent-details">
<summary>查看连接步骤</summary>
<ol className="agent-steps">
<li>
<strong>配置连接</strong>：在支持远程 MCP OAuth 的客户端中填写地址，选择
Streamable HTTP；在 WorthPath 网页登录后审核名称、回调和权限。
</li>
<li>
<strong>选择连接权限</strong>：先从 read
或草稿模式开始，根据需要增加权限。OAuth 访问令牌 1 小时，刷新授权最多 30
天并轮换。
</li>
<li>
<strong>把操作说明交给 Agent</strong>
：复制下方教程，不包含任何密码或令牌，再描述具体任务。
</li>
<li>
<strong>确认并查看结果</strong>：草稿在网页确认，Agent
可查询完成状态。随时在“已授权连接”撤销。
</li>
</ol>
</details>
<div className="agent-copy-row">
<h4>可直接复制给 Agent 的教程</h4>
<button
className="primary"
type="button"
onClick={() => void copy(instructions(data.mcpUrl), 'Agent 使用教程已复制')}
>
复制 Agent 使用教程
</button>
</div>
<details className="agent-details">
<summary>预览 Agent 使用教程</summary>
<textarea
className="agent-tutorial"
aria-label="Agent 使用教程"
readOnly
value={instructions(data.mcpUrl)}
rows={8}
/>
</details>
<details className="agent-details">
<summary>支持 Bearer 头的客户端与已验证 SDK 配置</summary>
<p>
在下方创建个人令牌，把完整值填入客户端的安全凭据设置；请求头为 Authorization:
Bearer &lt;令牌&gt;。个人令牌只显示一次，不能作为通用 OAuth 的替代。
</p>
<pre>{`new StreamableHTTPClientTransport(new URL(${JSON.stringify(data.mcpUrl)}), {\n requestInit: { headers: { Authorization: 'Bearer ' + process.env.MCP_ACCESS_TOKEN } }\n});`}</pre>
<button
className="secondary"
type="button"
onClick={() =>
void copy(
`$env:MCP_SERVER_URL=${JSON.stringify(data.mcpUrl)}\npnpm --filter @worthpath/api mcp:probe`,
'诊断命令已复制',
)
}
>
复制诊断客户端命令
</button>
<p className="muted">
先安全设置 MCP_ACCESS_TOKEN。实际验证客户端：官方 TypeScript SDK 1.31.0（OAuth /
Bearer）；其他 Agent 尚未验证，不提供未经验证的产品配置格式。
</p>
</details>
</section>
</>
)}
<h3>已授权连接（最近 100 条）</h3>
{data.grants.map((g) => (
<div key={g.id} className="agent-row">
<span>
{g.name} · {g.clientId ? 'OAuth' : '个人令牌'} · {g.scopes.join(', ')} ·{' '}
{new Date(g.expiresAt).toLocaleString()} · {g.revokedAt ? '已撤销' : ''}
</span>
{!g.revokedAt && (
<button
className="secondary"
disabled={busy}
type="button"
onClick={() =>
void act(async () => {
await api('/agent/connections/' + g.id, 'DELETE');
setMessage('连接已撤销');
})
}
>
撤销
</button>
)}
</div>
))}
<h3>待确认及最近操作（最近 100 条）</h3>
<button
className="secondary"
disabled={busy}
type="button"
onClick={() => void act(load)}
>
刷新状态
</button>
{data.operations.map((o) => (
<div key={o.id} className="agent-row">
<span>
{o.tool} ·{' '}
{o.status === 'pending' && new Date(o.expiresAt) < new Date()
? 'expired'
: o.status}{' '}
· {new Date(o.createdAt).toLocaleString()}
</span>
<button
className="secondary"
type="button"
disabled={busy}
onClick={() => void act(() => show(o.id))}
>
查看影响和结果
</button>
</div>
))}
<h3>最近调用（不保存参数和敏感内容）</h3>
{data.calls.map((c) => (
<div key={c.id} className="agent-row">
{c.tool} · {c.status} · {new Date(c.createdAt).toLocaleString()}
</div>
))}
</>
{agentView === 'tools' && (
<>
<section className="agent-card agent-wide">
<h3>Agent 可以做什么</h3>
<p className="muted">
这里列出服务实际提供的工具。能否执行还取决于连接权限、隐藏账户授权、项目归属和草稿确认。
</p>
<div className="agent-capabilities">
{capabilityGroups.map((g) => (
<details className="agent-details" key={g.title}>
<summary>{g.title}</summary>
<p>{g.summary}</p>
<ul>
{data.capabilities
.filter((t) => g.pattern.test(t.name))
.map((t) => (
<li key={t.name}>
<code>{t.name}</code> · {t.scope}
{t.destructive ? ' · 会删除数据' : ''}
<p>{t.description}</p>
</li>
))}
</ul>
</details>
))}
</div>
<details className="agent-details">
<summary>查看全部 {data.capabilities.length} 个工具（含连接与状态工具）</summary>
<ul>
{data.capabilities.map((t) => (
<li key={t.name}>
<code>{t.name}</code> · {t.scope}
<p>{t.description}</p>
</li>
))}
</ul>
</details>
</section>
<section className="agent-card agent-wide">
<details className="agent-details">
<summary>权限说明：read / draft / write</summary>
<p>选择一种连接权限：只读、草稿修改或直接写入。隐藏账户可单独授权读取和修改。</p>
<div className="agent-scope-grid">
{scopeDetails.map((s) => (
<article key={s.id}>
<h4>
{s.id} · {s.title}
</h4>
<strong>{s.summary}</strong>
<p>{s.detail}</p>
</article>
))}
</div>
</details>
</section>
</>
)}
{agentView === 'connections' && (
<>
<section className="agent-card">
<details className="agent-details">
<summary>创建个人访问令牌（可选）</summary>
<p className="muted">
适用于支持 Bearer
头的客户端。固定期限到期后新建并撤销旧令牌；永久令牌不会自动过期，仍可撤销。
</p>
<form
className="agent-form"
onSubmit={(e) => {
e.preventDefault();
const form = e.currentTarget,
f = new FormData(form);
void act(async () => {
const v = await api<{ token: string }>('/agent/tokens', 'POST', {
name: f.get('name'),
days: f.get('days') === 'permanent' ? null : Number(f.get('days')),
password: f.get('password'),
scopes: [
'read',
...(f.get('permission') !== 'read'
? [String(f.get('permission'))]
: []),
...(f.get('hiddenRead') ? ['hidden_read'] : []),
...(f.get('hiddenWrite') ? ['hidden_write'] : []),
],
});
setToken(v.token);
form.reset();
setTokenPermission('read');
setTokenHiddenRead(false);
setTokenHiddenWrite(false);
});
}}
>
<label>
连接名称
<input name="name" required maxLength={100} placeholder="例如：桌面助手" />
</label>
<label>
令牌有效期
<select name="days" defaultValue="30">
{durationOptions.map(([v, label]) => (
<option key={v} value={v}>
{label}
</option>
))}
</select>
</label>
<label>
连接权限
<select
name="permission"
value={tokenPermission}
onChange={(e) => {
setTokenPermission(e.target.value);
if (e.target.value === 'read') setTokenHiddenWrite(false);
}}
>
<option value="read">只读</option>
<option value="draft">草稿修改（网页确认）</option>
<option value="write">直接写入</option>
</select>
</label>
<fieldset className="agent-scope-options">
<legend>隐藏账户权限（默认关闭）</legend>
<label>
<input
type="checkbox"
name="hiddenRead"
checked={tokenHiddenRead}
onChange={(e) => {
setTokenHiddenRead(e.target.checked);
if (!e.target.checked) setTokenHiddenWrite(false);
}}
/>
允许读取隐藏账户
</label>
<label>
<input
type="checkbox"
name="hiddenWrite"
disabled={!tokenHiddenRead || tokenPermission === 'read'}
checked={tokenHiddenWrite}
onChange={(e) => setTokenHiddenWrite(e.target.checked)}
/>
允许修改隐藏账户（同时勾选读取，且选择草稿或直接写入）
</label>
</fieldset>
<label>
验证当前密码
<input
name="password"
type="password"
required
autoComplete="current-password"
/>
</label>
<button className="secondary" disabled={busy}>
创建个人令牌
</button>
</form>
{token && (
<div role="status" className="agent-secret">
<p>完整令牌仅显示这一次，请妥善保存到客户端凭据设置。</p>
<code className="agent-address">{token}</code>
<div className="actions">
<button
className="secondary"
type="button"
onClick={() => void copy(token, '令牌已复制')}
>
复制令牌
</button>
<button className="secondary" type="button" onClick={() => setToken('')}>
隐藏令牌
</button>
</div>
</div>
)}
</details>
</section>
<section className="agent-card agent-wide">
<div className="agent-copy-row">
<h3>已授权连接（最近 100 条）</h3>
<button
className="secondary"
disabled={busy}
type="button"
onClick={() => void act(load)}
>
刷新状态
</button>
</div>
{!data.grants.length && (
<p className="muted">尚未授权连接。通过 OAuth 接入，或创建个人令牌。</p>
)}
{data.grants.map((g) => (
<div key={g.id} className="agent-row">
<div>
<strong>{g.name}</strong>
<p>
{g.clientId ? 'OAuth' : '个人令牌'} · {g.scopes.join(', ')} ·{' '}
{g.revokedAt
? '已撤销'
: g.expiresAt && new Date(g.expiresAt) <= new Date()
? '已过期'
: '有效'}
</p>
<small>
{g.expiresAt
? '到期：' + new Date(g.expiresAt).toLocaleString()
: '永久 · 不会自动过期'}
</small>
</div>
{!g.revokedAt && (
<button
className="secondary"
disabled={busy}
type="button"
onClick={() =>
void act(async () => {
await api('/agent/connections/' + g.id, 'DELETE');
setMessage('连接已撤销');
})
}
>
撤销
</button>
)}
</div>
))}
</section>
</>
)}
{agentView === 'operations' && (
<>
<section className="agent-card agent-wide">
<h3>待确认及最近操作</h3>
{!data.operations.length && (
<p className="muted">暂无操作。Agent 发起的草稿会出现在这里。</p>
)}
{data.operations.map((o) => (
<div key={o.id} className="agent-row">
<span>
{o.tool} ·{' '}
{o.status === 'pending' && new Date(o.expiresAt) < new Date()
? 'expired'
: o.status}{' '}
· {new Date(o.createdAt).toLocaleString()}
</span>
<button
className="secondary"
type="button"
disabled={busy}
onClick={() => void act(() => show(o.id))}
>
查看影响和结果
</button>
</div>
))}
<details className="agent-details">
<summary>最近调用 · 不保存参数、密码或令牌</summary>
{!data.calls.length && <p className="muted">暂无调用记录。</p>}
{data.calls.map((c) => (
<div key={c.id} className="agent-row">
{c.tool} · {c.status} · {new Date(c.createdAt).toLocaleString()}
</div>
))}
</details>
</section>
</>
)}
</div>
)}
{consent && (
<div className="agent-confirm">
@@ -287,6 +559,46 @@ export function AgentConnections() {
<p>资源：{consent.resource}</p>
<p>回调地址：{consent.redirectUri}</p>
<p className="muted">只批准你正在连接的客户端；请核对回调地址。</p>
<label>
授予此连接的权限
<select
value={consentLevel}
onChange={(e) => {
setConsentLevel(e.target.value);
if (e.target.value === 'read') setConsentHiddenWrite(false);
}}
>
<option value="read">只读</option>
{consent.scopes.includes('draft') && (
<option value="draft">草稿修改（网页确认）</option>
)}
{consent.scopes.includes('write') && <option value="write">直接写入</option>}
</select>
</label>
{consent.scopes.includes('hidden_read') && (
<label>
<input
type="checkbox"
checked={consentHiddenRead}
onChange={(e) => {
setConsentHiddenRead(e.target.checked);
if (!e.target.checked) setConsentHiddenWrite(false);
}}
/>
允许读取隐藏账户
</label>
)}
{consent.scopes.includes('hidden_write') && (
<label>
<input
type="checkbox"
disabled={!consentHiddenRead || consentLevel === 'read'}
checked={consentHiddenWrite}
onChange={(e) => setConsentHiddenWrite(e.target.checked)}
/>
允许修改隐藏账户
</label>
)}
{[true, false].map((approve) => (
<button
className="secondary"
@@ -298,7 +610,16 @@ export function AgentConnections() {
const v = await api<{ redirect: string }>(
'/agent/authorizations/' + consent.id,
'POST',
{ approve },
{
approve,
scopes: consent.scopes.filter(
(s) =>
s === 'read' ||
s === consentLevel ||
(s === 'hidden_read' && consentHiddenRead) ||
(s === 'hidden_write' && consentHiddenWrite),
),
},
);
location.assign(v.redirect);
})
@@ -321,15 +642,10 @@ export function AgentConnections() {
<form
onSubmit={(e) => {
e.preventDefault();
const f = new FormData(e.currentTarget),
form = e.currentTarget;
const form = e.currentTarget;
void act(async () => {
await api('/agent/operations/' + preview.operationId, 'POST', {
approve: true,
...(f.get('password') ? { password: f.get('password') } : {}),
...(f.get('username') ? { username: f.get('username') } : {}),
...(f.get('newPassword') ? { newPassword: f.get('newPassword') } : {}),
...(f.get('confirmation') ? { confirmation: f.get('confirmation') } : {}),
});
form.reset();
await show(preview.operationId);
@@ -337,37 +653,6 @@ export function AgentConnections() {
});
}}
>
{preview.web === 'clear' && (
<>
<a href="/api/backup" download>
先下载当前账号备份
</a>
<p>确认备份已保存后输入“确定清空”。</p>
<input name="confirmation" required placeholder="确定清空" />
</>
)}
{preview.web === 'credentials' && (
<>
<input name="username" placeholder="新账号（可选）" autoComplete="username" />
<input
name="newPassword"
type="password"
minLength={10}
maxLength={72}
placeholder="新密码（可选）"
autoComplete="new-password"
/>
</>
)}
{preview.sensitive && (
<input
name="password"
type="password"
required
placeholder="当前密码"
autoComplete="current-password"
/>
)}
<button className="secondary" disabled={busy}>
确认执行上述操作
</button>
apps/web/src/App.tsx
+1 -6
View File
@@ -1538,7 +1538,6 @@ export default function App() {
<ArrowUpRight size={18} />
</div>
<h3>{p.name}</h3>
{p.groupName && <span className="badge">{p.groupName}</span>}
{(p.included === false ||
(p.kind === 'asset' && user.includeIndependentAssets === false)) && (
<span className="badge">{tr('不计入总览')}</span>
@@ -2268,7 +2267,7 @@ export default function App() {
{tr('选择备份并验证')}
<input
type="file"
accept=".zip,application/zip,.json,application/json"
accept=".zip,application/zip"
disabled={busy}
onChange={async (e) => {
setBackup(null);
@@ -2685,7 +2684,6 @@ export default function App() {
date: v.date,
metalType: v.metalType,
metalGrams: v.metalGrams,
metalPurity: v.metalPurity,
metalCostPerGram: v.metalCostPerGram || null,
autoValuation: true,
hidden: f.has('hidden'),
@@ -2866,9 +2864,6 @@ export default function App() {
pattern="(0|[1-9][0-9]{0,15})([.][0-9]{1,8})?"
/>
</Field>
<Field label={tr('纯度（0–1，例如 0.999）')}>
<input name="metalPurity" required defaultValue="1" inputMode="decimal" />
</Field>
<Field label={tr('买入价（每克，选填）')}>
<input
name="metalCostPerGram"
apps/web/src/MetalPanel.tsx
+3 -68
View File
@@ -1,5 +1,5 @@
import { useEffect, useRef, useState } from 'react';
import { api, money, type Position, currencies } from './api';
import { api, money, type Position } from './api';
import { t as tr } from './i18n';
import { useToast } from './Toast';
type Quote = { metalType: string; currency: string; price: string; date: string; source: string };
@@ -87,7 +87,7 @@ export function MetalPanel({
<h2>{tr('贵金属估价')}</h2>
<p className="muted">
{tr(
'黄金与白银按重量、纯度及每克参考价估值。每日尝试更新，失败保留旧价；参考价不含工费与回收折价。',
'黄金与白银按重量及每克参考价估值。每日尝试更新，失败保留旧价；参考价不含工费与回收折价。',
)}
</p>
{position && (
@@ -96,7 +96,6 @@ export function MetalPanel({
position.id +
String(position.metalGrams) +
String(position.autoValuation) +
String(position.metalPurity) +
String(position.metalType) +
String(position.metalCostPerGram)
}
@@ -109,7 +108,6 @@ export function MetalPanel({
metalType: f.get('metalType'),
metalGrams: f.get('metalGrams'),
metalCostPerGram: f.get('metalCostPerGram') || null,
metalPurity: f.get('metalPurity'),
autoValuation: f.has('autoValuation'),
}),
'贵金属估价设置已保存',
@@ -133,18 +131,6 @@ export function MetalPanel({
defaultValue={position.metalGrams || ''}
/>
</label>
<label>
{tr('纯度（0–1，例如 0.999）')}
<input
name="metalPurity"
required
type="number"
min="0.00000001"
max="1"
step="0.00000001"
defaultValue={position.metalPurity || '1'}
/>
</label>
<label>
{tr('买入价（每克，选填）')}（{position.currency}）
<input
@@ -155,7 +141,7 @@ export function MetalPanel({
/>
</label>
<p className="muted">
{tr('买入成本按实物总克数计算；参考估值按克数和纯度计算。清空买入价后不显示盈亏。')}
{tr('买入成本按总克数计算；新持仓按克数和参考价估值。清空买入价后不显示盈亏。')}
</p>
{position.metalCost != null && (
<p>
@@ -205,57 +191,6 @@ export function MetalPanel({
<p className={data?.status.state === 'error' ? 'danger-text' : 'muted'}>
{tr(data?.status.message || '尚未尝试更新')}
</p>
<details>
<summary>{tr('手动录入贵金属价格')}</summary>
<form
onSubmit={(e) => {
e.preventDefault();
const f = new FormData(e.currentTarget);
void act(
() => api('/metals/prices', 'POST', Object.fromEntries(f)),
'贵金属价格已保存',
);
}}
>
<label>
{tr('贵金属品种')}
<select name="metalType" defaultValue={position?.metalType || 'gold'}>
<option value="gold">{tr('黄金')}</option>
<option value="silver">{tr('白银')}</option>
</select>
</label>
<label>
{tr('币种')}
<select name="currency" defaultValue={position?.currency || 'CNY'}>
{currencies.map((c) => (
<option key={c}>{c}</option>
))}
</select>
</label>
<label>
{tr('每克纯金属价格')}
<input
name="price"
required
inputMode="decimal"
pattern="(0|[1-9][0-9]{0,11})([.][0-9]{1,12})?"
/>
</label>
<label>
{tr('报价日期')}
<input
name="date"
type="date"
required
max={new Date(Date.now() + 8 * 3600000).toISOString().slice(0, 10)}
defaultValue={new Date(Date.now() + 8 * 3600000).toISOString().slice(0, 10)}
/>
</label>
<button className="primary" disabled={busy}>
{tr('保存参考价')}
</button>
</form>
</details>
{!position && (
<div className="table-wrap">
<table>
apps/web/src/locales/en.json
+3 -1
View File
@@ -558,5 +558,7 @@
"估值盈亏": "Valuation profit/loss",
"待估值": "Awaiting valuation",
"按克数添加，参考价自动估值；缺少报价时显示待估值，不计为已知零价值。": "Add by grams with automatic market valuation. Missing quotes mean awaiting valuation, not a known zero value.",
"缺少报价，当前总额不完整。": "Quotes are missing; current totals are incomplete."
"缺少报价，当前总额不完整。": "Quotes are missing; current totals are incomplete.",
"黄金与白银按重量及每克参考价估值。每日尝试更新，失败保留旧价；参考价不含工费与回收折价。": "Gold and silver are valued by weight and the reference price per gram. Daily updates retain prior prices on failure; fees and resale discounts are excluded.",
"买入成本按总克数计算；新持仓按克数和参考价估值。清空买入价后不显示盈亏。": "Purchase cost uses total grams. New holdings use grams and reference prices for valuation. Clearing purchase price hides profit and loss."
}
apps/web/src/locales/zh-Hant.json
+3 -1
View File
@@ -558,5 +558,7 @@
"估值盈亏": "估值盈虧",
"待估值": "待估值",
"按克数添加，参考价自动估值；缺少报价时显示待估值，不计为已知零价值。": "按克數添加，參考價自動估值；缺少報價時顯示待估值，不計為已知零價值。",
"缺少报价，当前总额不完整。": "缺少報價，當前總額不完整。"
"缺少报价，当前总额不完整。": "缺少報價，當前總額不完整。",
"黄金与白银按重量及每克参考价估值。每日尝试更新，失败保留旧价；参考价不含工费与回收折价。": "黃金與白銀按重量及每克參考價估值。每日嘗試更新，失敗保留舊價；參考價不含工費與回收折價。",
"买入成本按总克数计算；新持仓按克数和参考价估值。清空买入价后不显示盈亏。": "買入成本按總克數計算；新持倉按克數和參考價估值。清空買入價後不顯示盈虧。"
}
apps/web/src/style.css
+155
View File
@@ -1880,3 +1880,158 @@ textarea,
.agent-panel form > label input[type='checkbox'] {
width: auto;
}
.agent-heading,
.agent-copy-row {
display: flex;
align-items: center;
justify-content: space-between;
gap: 1rem;
flex-wrap: wrap;
}
.agent-heading h2,
.agent-card h3 {
margin: 0;
}
.agent-layout {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 1.25rem;
margin-top: 1rem;
}
.agent-wide {
grid-column: 1 / -1;
}
.agent-card {
min-width: 0;
border: 1px solid var(--line);
border-radius: 14px;
padding: 1.25rem;
}
.agent-card p {
line-height: 1.65;
}
.agent-copy-row .agent-address {
flex: 1;
min-width: 12rem;
}
.agent-steps {
padding-left: 1.25rem;
line-height: 1.75;
}
.agent-steps li {
margin: 0.6rem 0;
}
.agent-tutorial {
width: 100%;
resize: vertical;
line-height: 1.65;
user-select: text;
margin-top: 0.75rem;
}
.agent-details {
border-top: 1px solid var(--line);
padding-top: 1rem;
margin-top: 1rem;
}
.agent-details summary {
cursor: pointer;
font-weight: 600;
line-height: 1.6;
}
.agent-details pre,
.agent-details code {
white-space: pre-wrap;
overflow-wrap: anywhere;
user-select: text;
}
.agent-details ul {
padding-left: 1.25rem;
line-height: 1.6;
}
.agent-details li p {
margin: 0.25rem 0 0.75rem;
}
.agent-capabilities,
.agent-scope-grid {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 1rem;
}
.agent-scope-grid article {
background: var(--bg);
border: 1px solid var(--line);
border-radius: 10px;
padding: 1rem;
}
.agent-panel .agent-form {
display: flex;
flex-direction: column;
align-items: stretch;
}
.agent-panel .agent-form > label {
display: flex;
flex-direction: column;
align-items: stretch;
gap: 0.4rem;
}
.agent-scope-options {
border: 1px solid var(--line);
border-radius: 10px;
display: grid;
gap: 0.75rem;
padding: 0.8rem;
}
.agent-scope-options label {
display: flex;
align-items: flex-start;
gap: 0.6rem;
}
.agent-scope-options input {
width: auto;
flex: none;
margin-top: 0.3rem;
}
.agent-scope-options small {
display: block;
margin-top: 0.25rem;
line-height: 1.5;
}
.agent-secret,
.agent-notice {
padding: 1rem;
background: var(--bg);
border: 1px solid var(--line);
border-radius: 10px;
}
.agent-row > div {
min-width: 0;
overflow-wrap: anywhere;
}
.agent-row p {
margin: 0.3rem 0;
}
@media (max-width: 800px) {
.agent-layout,
.agent-capabilities,
.agent-scope-grid {
grid-template-columns: 1fr;
}
.agent-wide {
grid-column: auto;
}
.agent-card {
padding: 1rem;
}
.agent-row {
flex-wrap: wrap;
}
}
.agent-tabs {
display: flex;
flex-wrap: wrap;
gap: 8px;
}
.agent-tabs button {
min-height: 40px;
}
docs/acceptance.md
+2
View File
@@ -1,5 +1,7 @@
# 首版验收（2026-10-01，Asia/Hong_Kong）
> 历史验收记录：2026-10-04 起所有旧备份兼容与单文件 JSON 支持已删除，当前仅接受 ZIP v9；本文旧版本测试记录不代表现行功能。现行 MCP 权限与工具范围见 [本次更新](update-agent-backup-2026-10-04.md)。
代码位于 E:\WorthPath，远程 origin 为用户指定 GitHub 仓库，分支 main。初始目录和仓库为空；没有覆盖已有项目文件。已有其他程序占用 API 默认端口，因此本项目使用 3100，前端使用 5173。
已验证：
docs/architecture.md
+2 -2
View File
@@ -1,6 +1,6 @@
# WorthPath 首版设计
2026-10-02 更新：查询、历史分页、趋势重放、借入借出联动及三语言的当前实现和实测见 [性能与联动验收](performance.md)。以下首版设计中的历史 ZIP v3/v4 说明保留作格式沿革；当前导出为 v7，兼容读取 v3/v4/v5/v6/v7 ZIP 和旧 JSON。
2026-10-04 更新：当前仅支持完整 ZIP v9 备份，不支持任何单文件 JSON 或旧 ZIP。本文旧版结构说明作为历史记录，现行权限与验证以 [本次更新](update-agent-backup-2026-10-04.md) 和 [MCP 接入](mcp.md) 为准。
本轮账户分组、定时计划、收支日历、迁移步骤与验证边界见 [更新说明](update-2026-10-02.md)。
@@ -34,7 +34,7 @@ Revision 保存按业务日期生效的绝对金额，每次金额更新新增
Icon 存储 name、ownerId、shared、SHA-256、规范静态 PNG 的 MediumBlob 和可选公开来源；Position.iconId 外键 SetNull，多个账户共享同一图片。所有图标接口使用已验证身份，读取/检索/赋值均限定 shared=true 或 ownerId=当前用户，响应不返回 ownerId。个人上传默认私有；共享发布须中文名称和明确公开确认。拒绝 SVG、动图、损坏图片、超限像素/文件，重编码移除元数据。内置图标固定 ID 追加初始化；在线请求不会发送用户财务数据。
备份逻辑增加可选 icons 数组（旧格式缺失可兼容），v4 ZIP 将图标内容放入 icons.json；内容校验和解码在导入事务前完成，图标在事务内以当前用户私有范围重建，账户关联重映射。清空删除私有图标，公开共享图标不因发布者清空而消失。用户删除时图标 ownerId SetNull，不影响他人已引用的公共图标。
当前备份要求完整 icons 数组，ZIP v9 将图标内容放入 icons.json；内容校验和解码在导入事务前完成，图标在事务内以当前用户私有范围重建，账户关联重映射。清空删除私有图标，公开共享图标不因发布者清空而消失。用户删除时图标 ownerId SetNull，不影响他人已引用的公共图标。
## 转账及显示偏好
docs/database-comments.json
+3 -3
View File
@@ -28,7 +28,7 @@
},
{
"TABLE_NAME": "agentpolicy",
"TABLE_COMMENT": "用户的 Agent 写入策略"
"TABLE_COMMENT": "已停用的历史 Agent 策略数据，保留原数据但不参与权限判定"
},
{
"TABLE_NAME": "exchangerate",
@@ -215,7 +215,7 @@
{
"TABLE_NAME": "agentgrant",
"COLUMN_NAME": "scopes",
"COLUMN_COMMENT": "权限列表：read、draft、write、sensitive"
"COLUMN_COMMENT": "权限列表：read、draft 或 write；隐藏账户附加权限 hidden_read、hidden_write"
},
{
"TABLE_NAME": "agentgrant",
@@ -235,7 +235,7 @@
{
"TABLE_NAME": "agentgrant",
"COLUMN_NAME": "expiresAt",
"COLUMN_COMMENT": "到期时间，UTC"
"COLUMN_COMMENT": "访问令牌到期时间，UTC；空表示可撤销的永久个人令牌"
},
{
"TABLE_NAME": "agentgrant",
docs/mcp-coverage.md
+59 -57
View File
@@ -1,69 +1,71 @@
# 现有功能 → MCP 覆盖与验证矩阵
> 2026-10-04 最新边界：MCP 提供 39 个工具。用户明确要求撤下敏感操作、汇率和贵金属报价修改；备份、清空、密码与隐藏解锁流程仍在网站完成。单文件 JSON 及旧 ZIP 全部拒绝。此要求取代最初“全部业务均可由 MCP 完成”的范围。
盘点来源：App.tsx、Calendar、SchedulePanel、MetalPanel、IconLibrary、TransferForm、DebtPaymentForm、GroupOrderList 及所有 API Controller 路由。架构沿用 NestJS/Express/Prisma/MySQL/Zod，不新增消费账本或 AI 框架。
验证记号：**M** `test/mcp.test.ts` 第一组真实官方 SDK/MySQL；**C** 第二组并发/图标/密码修改；**O** 第三组 OAuth；**R** 18 组真实 REST/MySQL 回归；**U** 原单元计算/行情/ZIP 测试。均有实际业务断言。M 中公共刷新验证无需要更新资产时的真实调用；外部行情响应和失败回退由 U 验证，未声称行情供应商稳定可用。
验证记号：**M** 第一组官方 SDK 普通业务/草稿/隐藏权限；**C** 第二组幂等/并发/私有图标/回滚；**O** 第三组 OAuth；**P** 第四组期限/永久令牌/隔离/撤销；**R** 18 组真实 REST/MySQL；**U** 34 项单元计算/行情/ZIP 测试。均有真实业务断言，外部行情成功/失败路径由 U 验证。
**B**：2026-10-03 22:55（UTC+8）真实浏览器验证黄金/白银创建、可选买入价与盈亏、清空成本、估值历史及报价完成后自动同步，临时用户已清理。
普通写入需要 draft 或 write，且受用户 readonly/draft/direct 策略约束；敏感操作额外要求 sensitive 并强制网页确认。所有写入工具要求幂等键和 expectedState。每项都先检查可信用户归属；annotations 不替代权限。
当前权限为 read（只读）、read+draft（网页确认后提交）、read+write（直接普通修改）。hidden_read/hidden_write 是独立附加授权。没有网站全局写入策略。所有写入均校验可信身份、归属、幂等键和 expectedState。
| 现有页面/API 与功能 | MCP 操作路径 | 权限 | 确认方式 | 验证 |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------- | --------------------------------------------------------- |
| 账户/独立资产/债务列表 GET positions | positions_list：kind、名称、归档、方向、币种、分组、排序、offset/limit | read | 无 | M：查询、重名、分页和外用户隔离 |
| 项目详情 GET positions/:id | position_get | read | 隐藏项目须连接独立网页解锁 | M：当前余额、隐藏/外用户拒绝 |
| 创建项目 POST positions | position_create，保留账户/资产/债务初始绝对余额语义 | draft/write | 策略决定草稿或直接 | M/C：3 类对象、重复调用、无效金额、并发 |
| 按克数创建贵金属 POST metals/holdings | metal_holding_create | draft/write | 策略 | M/R/U/B：待估值、报价、成本盈亏、旧备份 |
| 元数据、分类、分组、图标、归档/恢复、隐藏、计入开关 PATCH positions/:id | position_update，完整 metadata；币种与方向固定 | draft/write | 策略 | M：分组、归档禁止金额更新与恢复；R：隐藏和开关 |
| 分组拖拽排序 PATCH settings | settings_update.accountGroupOrder | draft/write | 策略 | M/R：持久化、排序、备份 |
| 类别选项、名称与分组配置 | position_create/update；positions_list 读取现有值，Schema/描述提供规则 | read + draft/write | 策略 | M/R；当前没有独立分类/分组实体 CRUD |
| 新增余额、资产估值、负债余额及单边还款 POST revisions | balance_record，reason 区分；amount 为变更后余额 | draft/write | 策略 | M：精确余额；R/U：负债、估值、业务时间 |
| 历史全局/单项目 GET history、positions/:id/history | history_list.positionId、cursor、from/to | read | 无 | M/R：页大小、游标、前序余额、日期范围 |
| 更正普通历史 PUT revisions | history_update | draft/write | 策略 | M/R：重放、精度、日历联动 |
| 删除/撤销历史 DELETE revisions | history_delete；配对记录删除完整双边 | draft/write | 策略，destructive annotation | M/R：余额重算及双边撤销 |
| 债务关联账户/资产 PUT links | debt_links_set.targetIds | draft/write | 策略 | M：合法关联、隐藏目标拒绝；R：外用户拒绝 |
| 资金往来列表 GET transfers | movements_list：cursor、日期过滤 | read | 无 | M/R |
| 按历史找双边记录 GET transfers/revision/:revisionId | movement_by_revision | read | 无 | M/R |
| 转账、借入、借出、收款、还款 POST transfers | movement_create.operation：transfer/borrow/lend/collect/repay | draft/write | 策略，双边事务 | M：转账、repay、信用卡溢缴；R：全部 5 种语义；C：错误回滚 |
| 修改配对记录 PUT transfers/:id | movement_update | draft/write | 策略，后续历史重放 | M/R |
| 删除/撤销配对记录 DELETE transfers/:id | movement_delete | draft/write | 策略，双边撤销 | M/R |
| 净资产、总额、结构、变化归因 GET overview | overview_get，明细分页、保留全局总额 | read | 隐藏项目按本连接可见范围 | M/R/U：总额、开关、外币缺失 |
| 轨迹、日期与统计粒度 GET trend | trend_get：day/week/month 及 from/to | read | 无 | M/R/U：范围、首日、期末、归因 |
| 本位币、币种、实际汇率与更新状态 GET settings | settings_get，固定币种枚举且金额无浮点计算 | read | 无 | M/R/U |
| 本位币切换、显示菜单、备注、闲置退出、登录时长、总览卡片、独立资产计入 PATCH settings | settings_update | draft/write | 策略 | M/R |
| 是否查看隐藏资产需密码 PATCH settings | settings_update.requireHiddenPassword | sensitive | 强制网页密码确认 | M：draft 权限无法改变；R：会话锁定规则 |
| 自动/重试日汇率 POST rates/refresh | rates_refresh；已有后台定时更新保留 | draft/write | 策略 | M：真实工具调用；U：成功解析、手工优先、失败保留 |
| 金银报价与状态 GET metals | metals_prices，最近 100 条 | read | 无；查询 MCP 不触发隐式自动更新 | M/U/R |
| 金银报价刷新 POST metals/refresh | metals_refresh | draft/write | 策略，沿用自动估值 | M：无配置资产调用；U：外部响应和失败回退 |
| 每克报价手动回退 POST metals/prices | metal_price_set，Decimal 价格 | draft/write | 策略 | M/R/U：手动优先、精确估值 |
| 克数、品种、纯度、买入成本、自动估价 PUT metals/:id | metal_configure | draft/write | 策略 | M/R/U：估值历史和去重 |
| 应用估价 POST metals/:id/value | metal_value | draft/write | 策略 | M/R/U |
| 收支月日历 GET calendar | calendar_month，YYYY-MM | read | 无 | M/R/U |
| 单日日历明细 GET calendar/day | calendar_day，业务日和分页 | read | 无 | M/R/U：历史修改、转账排除、Decimal |
| 计划列表/状态 GET schedules | schedules_list，按到期排序分页；history_list 查看执行历史 | read | 无 | M/R |
| 新建/修改支出或转账计划 POST/PUT schedules | schedule_create/update | draft/write | 策略 | M/R：真实执行及编辑限制 |
| 启用/停用 PATCH schedules/:id | schedule_toggle | draft/write | 策略 | M/R |
| 删除计划 DELETE schedules/:id | schedule_delete，保留执行历史 | draft/write | 策略 | M/R |
| 按需运行到期计划 POST schedules/run | schedules_run，最多 20 项、hasMore；MCP 失败整批回滚 | draft/write | 策略，幂等事务 | M/C/R/U |
| 登录个人资料 GET auth/me | settings_get；connection_info 提供 Agent 授权资料 | read | 无 | M/C |
| 修改用户名和密码 PATCH auth/credentials | credentials_change_request → 网页 → operation_get | sensitive | 网站验证当前密码、输入新值，Agent 不收到密码 | C/R：真实密码登录、原会话轮换、Agent 降权结果查询 |
| 隐藏资产密码核验 POST auth/reveal | hidden_unlock_request → 网页 → operation_get | sensitive | 网页当前密码，当前连接 5 分钟 | M/R：锁定、隔离、失效规则 |
| 锁定隐藏资产 POST auth/lock | hidden_lock | draft/write | 策略；也可网页锁定 | M/R |
| 退出登录 POST auth/logout | connection_revoke 退出当前 MCP 连接；网页退出仍在原页面 | 当前连接认证 | 撤销是即时缩小授权，不受写入策略阻碍 | M/O/R：后续 401 |
| 注册/登录、网页 activity | OAuth 网页入口复用原注册/登录，Agent 令牌不依赖网页 Cookie；activity 为网页会话维护 | 网页认证/OAuth | 用户登录或注册及授权 | O/R、浏览器验证管理入口 |
| 图标搜索 GET icons | icons_list，60/页、q | read | 无 | M/C/R |
| 图标图片 GET icons/:id/image | icon_image → 同连接 Bearer GET | read | 无 | C/R：PNG 和归属 |
| 上传图标 POST icons/upload | file_upload_request(kind=icon) → POST file → icon_publish | draft/write；共享须 sensitive | 私有按策略；共享网页确认及中文名 | C/R：私有和共享实际保存 |
| 导出备份 GET backup | backup_export → 网页 → operation_get → Bearer 下载 | sensitive | 网页密码，短期授权入口 | M/R：完整 ZIP、隐藏数据、令牌排除、跨用户及未登录拒绝 |
| 上传备份 POST backup/upload | file_upload_request(kind=backup) → Bearer multipart → file_status | draft/write | 用户控制上传；不提交账目 | M/R：真实 ZIP 传输 |
| 预检 POST backup/preview | import_preview(token)，上传同时预检 | read（上传需要 draft/write） | 不修改账目 | M/R/U：结构/校验/重复/冲突 |
| 追加恢复 POST backup/import、import-file | backup_import(token) → 网页 → operation_get | sensitive | 强制网页密码及数量/冲突预览 | M/R：真实恢复、重复冲突不改变数据 |
| 清空资格 GET backup/clear-status | data_clear_request 网页确认时复用现有备份资格及指纹 | sensitive | 网站先下载最新备份 | M/R |
| 清空财务数据 POST backup/clear | data_clear_request → 网页 → operation_get | sensitive | 密码、备份指纹及“确定清空” | M/R：未下载拒绝、真实清空、保留账号 |
| 新增接入管理、权限、PAT、撤销、调用日志和待确认页 | /api/agent 管理；connection_info、operation_get、state_get；OAuth 标准路径 | 网站身份/本连接 Bearer | PAT/策略验证密码；操作归属校验 | M/C/O、真实浏览器管理页 |
| 现有页面/API 与功能 | MCP 操作路径 | 权限 | 确认方式 | 验证 |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------- | --------------------------------------------------------- |
| 账户/独立资产/债务列表 GET positions | positions_list：kind、名称、归档、方向、币种、分组、排序、offset/limit | read | 无 | M：查询、重名、分页和外用户隔离 |
| 项目详情 GET positions/:id | position_get | read | 隐藏项目须连接独立网页解锁 | M：当前余额、隐藏/外用户拒绝 |
| 创建项目 POST positions | position_create，保留账户/资产/债务初始绝对余额语义 | draft/write | 连接权限决定草稿或直接 | M/C：3 类对象、重复调用、无效金额、并发 |
| 按克数创建贵金属 POST metals/holdings | metal_holding_create | draft/write | 连接权限 | M/R/U/B：待估值、报价、成本盈亏、旧备份 |
| 元数据、分类、分组、图标、归档/恢复、隐藏、计入开关 PATCH positions/:id | position_update，完整 metadata；币种与方向固定 | draft/write | 连接权限 | M：分组、归档禁止金额更新与恢复；R：隐藏和开关 |
| 分组拖拽排序 PATCH settings | settings_update.accountGroupOrder | draft/write | 连接权限 | M/R：持久化、排序、备份 |
| 类别选项、名称与分组配置 | position_create/update；positions_list 读取现有值，Schema/描述提供规则 | read + draft/write | 连接权限 | M/R；当前没有独立分类/分组实体 CRUD |
| 新增余额、资产估值、负债余额及单边还款 POST revisions | balance_record，reason 区分；amount 为变更后余额 | draft/write | 连接权限 | M：精确余额；R/U：负债、估值、业务时间 |
| 历史全局/单项目 GET history、positions/:id/history | history_list.positionId、cursor、from/to | read | 无 | M/R：页大小、游标、前序余额、日期范围 |
| 更正普通历史 PUT revisions | history_update | draft/write | 连接权限 | M/R：重放、精度、日历联动 |
| 删除/撤销历史 DELETE revisions | history_delete；配对记录删除完整双边 | draft/write | 连接权限，destructive annotation | M/R：余额重算及双边撤销 |
| 债务关联账户/资产 PUT links | debt_links_set.targetIds | draft/write | 连接权限 | M：合法关联、隐藏目标拒绝；R：外用户拒绝 |
| 资金往来列表 GET transfers | movements_list：cursor、日期过滤 | read | 无 | M/R |
| 按历史找双边记录 GET transfers/revision/:revisionId | movement_by_revision | read | 无 | M/R |
| 转账、借入、借出、收款、还款 POST transfers | movement_create.operation：transfer/borrow/lend/collect/repay | draft/write | 连接权限，双边事务 | M：转账、repay、信用卡溢缴；R：全部 5 种语义；C：错误回滚 |
| 修改配对记录 PUT transfers/:id | movement_update | draft/write | 连接权限，后续历史重放 | M/R |
| 删除/撤销配对记录 DELETE transfers/:id | movement_delete | draft/write | 连接权限，双边撤销 | M/R |
| 净资产、总额、结构、变化归因 GET overview | overview_get，明细分页、保留全局总额 | read | 隐藏项目按本连接可见范围 | M/R/U：总额、开关、外币缺失 |
| 轨迹、日期与统计粒度 GET trend | trend_get：day/week/month 及 from/to | read | 无 | M/R/U：范围、首日、期末、归因 |
| 本位币、币种、实际汇率与更新状态 GET settings | settings_get，固定币种枚举且金额无浮点计算 | read | 无 | M/R/U |
| 本位币切换、显示菜单、备注、闲置退出、总览卡片、独立资产计入 PATCH settings | settings_update | draft/write | 连接权限 | M/R |
| 是否查看隐藏资产需密码 PATCH settings | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 自动/重试日汇率 POST rates/refresh | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 金银报价与状态 GET metals | metals_prices，最近 100 条 | read | 无；查询 MCP 不触发隐式自动更新 | M/U/R |
| 金银报价刷新 POST metals/refresh | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 贵金属手动报价 | 已从网页、REST、MCP 移除 | 无 | 无 | R：原 REST 路由 404；M：无工具 |
| 克数、品种、买入成本、自动估价 PUT metals/:id | metal_configure | draft/write | 连接权限 | M/R/U：估值历史和去重 |
| 应用估价 POST metals/:id/value | metal_value | draft/write | 连接权限 | M/R/U |
| 收支月日历 GET calendar | calendar_month，YYYY-MM | read | 无 | M/R/U |
| 单日日历明细 GET calendar/day | calendar_day，业务日和分页 | read | 无 | M/R/U：历史修改、转账排除、Decimal |
| 计划列表/状态 GET schedules | schedules_list，按到期排序分页；history_list 查看执行历史 | read | 无 | M/R |
| 新建/修改支出或转账计划 POST/PUT schedules | schedule_create/update | draft/write | 连接权限 | M/R：真实执行及编辑限制 |
| 启用/停用 PATCH schedules/:id | schedule_toggle | draft/write | 连接权限 | M/R |
| 删除计划 DELETE schedules/:id | schedule_delete，保留执行历史 | draft/write | 连接权限 | M/R |
| 按需运行到期计划 POST schedules/run | schedules_run，最多 20 项、hasMore；MCP 失败整批回滚 | draft/write | 连接权限，幂等事务 | M/C/R/U |
| 登录个人资料 GET auth/me | settings_get；connection_info 提供 Agent 授权资料 | read | 无 | M/C |
| 修改用户名和密码 PATCH auth/credentials | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 隐藏资产密码核验 POST auth/reveal | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 锁定隐藏资产 POST auth/lock | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 退出登录 POST auth/logout | connection_revoke 退出当前 MCP 连接；网页退出仍在原页面 | 当前连接认证 | 撤销是即时缩小授权，不受写入连接权限阻碍 | M/O/R：后续 401 |
| 注册/登录、网页 activity | OAuth 网页入口复用原注册/登录，Agent 令牌不依赖网页 Cookie；activity 为网页会话维护 | 网页认证/OAuth | 用户登录或注册及授权 | O/R、浏览器验证管理入口 |
| 图标搜索 GET icons | icons_list，60/页、q | read | 无 | M/C/R |
| 图标图片 GET icons/:id/image | icon_image → 同连接 Bearer GET | read | 无 | C/R：PNG 和归属 |
| 上传图标 POST icons/upload | file_upload_request(kind=icon) → POST file → icon_publish | draft/write；共享仅网站 | 私有按连接权限；共享仅网站 | C：私有保存及共享拒绝；R：网站共享保存 |
| 导出备份 GET backup | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 上传备份 POST backup/upload | 仅网站上传当前 ZIP v9，MCP 不发行备份上传入口 | 无 MCP 权限 | 网站预检与确认 | R：JSON 拒绝、ZIP 恢复及文件归属 |
| 预检 POST backup/upload 自动预检 | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 追加恢复 POST backup/import-file | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 清空资格 GET backup/clear-status | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 清空财务数据 POST backup/clear | 按用户最新要求仅在网站操作；MCP 不提供该流程 | 无 MCP 权限 | 网站原确认流程 | R/U；M：相关工具不存在且调用拒绝 |
| 新增接入管理、权限、PAT、撤销、调用日志和待确认页 | /api/agent 管理；connection_info、operation_get、state_get；OAuth 标准路径 | 网站身份/本连接 Bearer | PAT 创建验证密码；操作归属校验 | M/C/O、真实浏览器管理页 |
不存在的业务不列作“已实现”：单个持仓永久删除、账户注销、覆盖导入、批量删除、独立分类/分组对象 CRUD 均不在当前页面/API 中。历史删除、资金往来撤销、计划删除、归档及备份保护清空全部已有路径均已覆盖。
不存在的业务不列作“已实现”：单个持仓永久删除、账户注销、覆盖导入、批量删除、独立分类/分组对象 CRUD 均不在当前页面/API 中。历史删除、资金往来撤销、计划删除、归档仍由上述 MCP 工具覆盖；备份保护清空在网站保留，按最新要求退出 MCP 范围。
共享服务：PortfolioBusinessService、TransfersBusinessService、SchedulesBusinessService、CalendarBusinessService、SettingsBusinessService、MetalsBusinessService、IconsBusinessService、BackupBusinessService、AuthBusinessService。REST Controller 仅转发并保留原参数、文件拦截器、认证和路由；SDK Catalogue 调用同一服务，不复制金额或重放。
共享服务：PortfolioBusinessService、TransfersBusinessService、SchedulesBusinessService、CalendarBusinessService、SettingsBusinessService、MetalsBusinessService、IconsBusinessService。AuthBusinessService 与 BackupBusinessService 保留网站/REST 流程。REST Controller 仅转发并保留原参数、文件拦截器、认证和路由；SDK Catalogue 调用同一服务，不复制金额或重放。
金额状态、OAuth、scope、Origin/Host、文件生命周期和客户端限制见 [接入文档](mcp.md)。当前官方客户端验证通过；未验证其他产品配置和生产 HTTPS 反向代理。
docs/mcp.md
+42 -97
View File
@@ -1,50 +1,42 @@
# WorthPath 远程 MCP 接入
## 开始使用
2026-10-04：服务提供 39 个工具。按用户最新要求，MCP 不再提供敏感操作、汇率或贵金属报价修改。网站保留备份、清空、密码修改和自动行情功能。完整覆盖矩阵见 [功能覆盖](mcp-coverage.md)，本次迁移及验证见 [更新记录](update-agent-backup-2026-10-04.md)。
网站「设置与备份 → 连接 Agent」显示实际 MCP 地址、写入策略、OAuth 连接、个人令牌、待确认操作和最近调用。默认写入策略为草稿。现有网页登录、REST 和数据计算规则保留。
## 开始连接
1. 支持远程 OAuth 的客户端填写页面显示的 MCP 地址，选择 Streamable HTTP。
2. 客户端通过 `401 WWW-Authenticate` 或 `/.well-known/oauth-protected-resource/mcp` 发现授权服务。支持 OAuth 2.1 授权码、S256 PKCE、RFC 8707 resource、动态注册的公开客户端。
3. 浏览器进入 WorthPath，登录或注册，核对客户端名称、回调地址、资源和权限后授权。网站会回到注册的精确回调地址并保留 state。
4. 只请求需要的权限：`read` 查询；`draft` 创建草稿；`write` 普通写入；`sensitive` 发起敏感流程。所有授权包含 read。敏感权限仍要求网页验证当前密码，不能用工具参数确认。
5. 查询用稳定 UUID。写入先调用 `state_get`，把返回的 state 作为 `expectedState`，同时提供同用户唯一 `idempotencyKey`。状态变化后重新查询并使用新键；网络重试必须保持同键、同参数、同 expectedState。
6. 返回 pending 时打开 `confirmationUrl`，用户审核影响并提交或取消。Agent 使用 `operation_get(operationId)` 查询 completed、cancelled、expired 及最终结果。提交失败保留草稿并返回最近失败原因，用户可以重试或取消。
在「设置与备份 → 连接 Agent」复制实际 MCP 地址和“Agent 使用教程”。支持远程 OAuth 的客户端填写此地址，选择 Streamable HTTP；在 WorthPath 网页登录，审核客户端名称、回调地址、资源，并选择连接权限。网页会回到已注册的精确回调地址并保留 state。客户端自行验证 state。
密码只在网站填写。账号或密码修改后其他连接撤销，当前发起连接只保留 5 分钟 read 权限以读取完成结果，不可刷新；需要重新授权才能继续写入。隐藏资产解锁仅持续 5 分钟并限定当前连接，网站的解锁不自动授予 Agent。
OAuth 使用发现元数据、动态注册的公开客户端、授权码、S256 PKCE、RFC 8707 resource。每次 MCP 请求独立验证 Bearer；网页登录 Cookie、MCP 会话 ID 均不作为认证凭证。发现入口为 `/.well-known/oauth-protected-resource/mcp`，未授权响应提供 `WWW-Authenticate`。
## 贵金属按克数接入
| 连接权限 | OAuth/PAT scopes | 普通修改行为 |
| -------- | ---------------- | -------------------------------- |
| 只读 | read | 查询，拒绝修改和上传 |
| 草稿修改 | read draft | 保存十分钟草稿，由用户在网页确认 |
| 直接写入 | read write | 普通修改在事务中直接完成 |
新增 `metal_holding_create`：name、currency、metalType(gold/silver)、metalGrams、metalPurity、autoValuation、date，买入价 metalCostPerGram 可省略或 null；无需填写金额或市场价格。写入仍需 expectedState 和 idempotencyKey，并遵循写入策略。有对应业务日或更早报价时复用估值逻辑创建历史，没有报价时返回 valuationAvailable=false，查询总额 complete=false 与 missingValuations。position_get/list 返回可选 metalCost 和 metalProfit，均为原币十进制字符串。成本按实物重量计算，市场价值按重量×纯度×每克纯金属报价计算。
选择一种权限等级，draft 和 write 不能同时授予。没有网站全局写入策略。hidden_read 额外允许读取隐藏账户；hidden_write 额外允许修改，必须同时拥有 hidden_read 和 draft/write。两个附加权限默认关闭，OAuth 网页也可选择关闭。服务在查询和修改时分别构造业务上下文，网页解锁状态不自动授予 Agent。
metal_configure 省略 metalCostPerGram 保留旧成本，传 null 清除。克数或成本修改与其他写入一样参与并发状态校验；盈亏由共享业务服务计算，不存储额外浮点累计值。[更新与验证](update-metal-grams-2026-10-03.md)。
敏感操作（密码/账号修改、清空、备份导出恢复、公开图标发布、安全设置变更）仅在网站进行，不存在 sensitive scope。汇率和参考报价可以查询，MCP 不能修改或主动刷新。贵金属仍可按克数创建、设置成本和重量，并用已有报价更新资产估值；估值历史与报价是不同业务。
## 开发启动与环境
个人访问令牌仅作为支持自定义 Bearer 头客户端的补充。在网站验证当前密码，选择权限和 1、3、7、30 天、365 天或永久。完整值仅创建时展示，数据库只存 SHA-256 摘要。永久令牌数据库到期日为空，每个请求仍重新检查撤销和资源；为兼容 SDK 中间件，每次认证上下文有有限期验证断言，不改变令牌期限。永久令牌内部业务会话按天续期。OAuth 访问令牌一小时、刷新授权三十天，刷新时轮换摘要；不支持永久 OAuth。
```powershell
cd E:\WorthPath
.\scripts\pnpm.ps1 install
# 保留已有 apps/api/.env，按 .env.example 增加下面三项配置。
.\scripts\pnpm.ps1 db:generate
.\scripts\pnpm.ps1 db:migrate
.\scripts\pnpm.ps1 dev
```
旧连接有 write 时，现在直接执行普通修改；旧全局策略不再阻止它。只想创建草稿时，撤销旧连接并重新授权 read draft。历史策略行保留但不参与任何权限判断；旧敏感工具草稿不可提交。
生成 Prisma 前暂停 API，Windows 会锁定其引擎 DLL。迁移仅 deploy，不 reset。
## Agent 操作
| 变量 | 本地示例 | 用途 |
| ------------------- | ------------------------- | ---------------------------------------------------- |
| MCP_PUBLIC_URL | http://localhost:3100/mcp | 固定的 OAuth resource；生产必须 HTTPS，路径必须 /mcp |
| MCP_WEB_URL | http://localhost:5173 | 网页授权和操作确认入口；生产必须 HTTPS |
| MCP_ALLOWED_ORIGINS | http://localhost:5173 | 精确浏览器 Origin 列表，逗号分隔，不支持通配符 |
查询使用稳定 UUID；名称重名时先让用户选择。列表 limit 最大 100；图标固定 60；历史和资金往来使用 cursor。日期为 UTC+8 业务日期 `YYYY-MM-DD` 或 `YYYY-MM-DDTHH:mm`，返回时间戳使用 UTC ISO。金额、克数、汇率与报价为十进制字符串，沿用 Decimal 和 DECIMAL 规则。
生产继续要求 COOKIE_SECURE=true、准确的 WEB_ORIGIN。MCP 请求以独立 Bearer 验证，不接受网页登录 Cookie 作为授权，不把会话 ID 当凭证。未带 Origin 的非浏览器客户端允许接入；带 Origin 的请求必须匹配列表。Host 必须匹配规范资源地址。反向代理应传递规范的 Host，不以任意转发头构造资源 URL。
写入先 `state_get`，再传 expectedState、唯一 idempotencyKey 与具体工具参数。重试必须保持同键、同参数、同状态；状态冲突后重新查询并换键。同用户同键不同参数或不同连接明确拒绝。资金转账、借贷还款、资产估值和绝对余额录入保留原业务语义。
## 已验证的客户端配置
draft 返回 operationId、pending、confirmationUrl；用户在网站审阅影响后确认或取消，Agent 用 `operation_get` 查询最终结果。confirmed=true 不能绕过确认。提交重新检查权限、过期/撤销、账目版本、归属和业务规则。写入记录与业务修改在同一 Serializable 事务提交，失败回滚。MCP 到期计划按批事务执行，REST 原逐计划执行语义保留。
实际验证：官方 `@modelcontextprotocol/sdk@1.31.0`，StreamableHTTPClientTransport；Bearer PAT 和 OAuth 动态注册/发现/PKCE/刷新/撤销均经真实本地服务测试。服务协商 SDK 1.31.0 支持的协议，默认最新 `2025-11-25`。选择维护中的 v1 API 并精确锁定版本，未混用 v2 示例。[官方 SDK](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x)、[对应授权规范](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)。
私有图标使用 `file_upload_request(kind=icon)` → 同一 Bearer multipart 上传 file → `file_status` → `icon_publish`。最多 2 MiB，入口十分钟有效，绑定用户和连接。`icon_image` 返回同一 Bearer 保护的短期图片入口。MCP 不发行备份文件入口。
下面是测试使用的官方 SDK 构造形式：
贵金属 `metal_holding_create` 无需填写市场金额；metalCostPerGram 可省略或 null。没有报价时 valuationAvailable=false，总额 complete=false 且包含 missingValuations。成本按实物重量计算，新持仓价值按重量×每克参考报价计算，既有持仓历史系数保留，盈亏由共享服务计算。metal_configure 省略成本保留旧值，null 清除。创建与配置均不接受 metalPurity 参数，新持仓使用默认比例 1；既有持仓的历史比例不改写。
## 已验证客户端
真实验证官方 `@modelcontextprotocol/sdk@1.31.0` 的 StreamableHTTPClientTransport：Bearer、OAuth 发现/DCR/PKCE、轮换、撤销与业务操作。精确锁定 v1 SDK，默认协议 2025-11-25。[官方 SDK](https://github.com/modelcontextprotocol/typescript-sdk/tree/v1.x)、[授权规范](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)。
```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
@@ -59,83 +51,36 @@ console.log(await client.listTools());
await client.close();
```
本项目提供只读协议诊断客户端，完整个人令牌在网站创建时仅展示一次：
OAuth 客户端使用 authProvider，浏览器回调后 finishAuth(code) 再连接；真实 provider 示例在 `apps/api/test/mcp.test.ts` 第三组。客户端安全保存 verifier、注册和令牌，禁止跨用户共享。
```powershell
$env:MCP_SERVER_URL='http://localhost:3100/mcp'
# 在本机终端设置 MCP_ACCESS_TOKEN；不要写进仓库或聊天。
# 在终端安全设置 MCP_ACCESS_TOKEN，不写入仓库或聊天。
pnpm --filter @worthpath/api mcp:probe
Remove-Item Env:MCP_ACCESS_TOKEN
```
OAuth 客户端使用 `authProvider` 代替手工 Bearer 头；实现 SDK 的 OAuthClientProvider，在 `redirectToAuthorization` 打开浏览器，在回调后调用 transport.finishAuth(code) 再连接。真实的 provider、发现和交换实现见 `apps/api/test/mcp.test.ts` 第三组测试。生产客户端还应独立校验 state，安全持久化 verifier、客户端注册和令牌，禁止跨用户共享。WorthPath 返回原 state，但客户端必须自行验证。
未验证 MCP Inspector、Claude、ChatGPT、Cursor、Codex 等商业客户端的配置和 OAuth 实际行为，不提供推测配置。生产 HTTPS 代理未部署验证。
没有验证 MCP Inspector、Claude、ChatGPT、Cursor、Codex 或其他产品的实际 OAuth/config 格式，不提供猜测配置或普遍兼容承诺。HTTPS 代理环境也未实际部署验证。
## 启动与部署
## 写入、权限和一致性
| 用户策略 | draft 权限 | write 权限 | sensitive 权限 |
| ------------- | ------------- | ------------- | -------------------------------------------------- |
| readonly | 拒绝写入/上传 | 拒绝写入/上传 | 仅允许网页确认的完整备份导出和隐藏解锁，不修改账目 |
| draft（默认） | 保存草稿 | 保存草稿 | 强制网页确认 |
| direct | 保存草稿 | 执行普通写入 | 强制网页确认 |
草稿 10 分钟到期，保存用户、连接、具体参数、账目摘要和状态。提交重新检查连接过期/撤销、scope、当前策略、账目状态、数据归属及业务规则。`confirmed=true` 被严格 Schema 拒绝。修改隐藏密码要求的设置、发布共享图标也升级为敏感确认。
幂等记录和业务变更在同一 Serializable 数据库事务提交，用户唯一键保证重试不重复入账。同键不同参数或不同连接明确拒绝。所有普通直接写入和草稿提交通过状态摘要防止覆盖 REST 或其他 Agent 的并发修改。状态包括全部用户账目、历史、计划、汇率、金属报价及相关设置，只返回摘要，不返回隐藏数据。
复用现有 Decimal、余额计算、转账和历史重放。AsyncLocalStorage 仅保存当前数据库事务，认证信息来自每请求的 Bearer 上下文。现有服务中的嵌套事务加入 MCP 外层事务；MCP 计划执行任一失败会回滚整批，REST 仍保留逐计划执行和失败列表语义。
金额为十进制字符串，现有 DECIMAL(24,8) 和报价/汇率 DECIMAL(24,12) 保留。`balance_record.amount` 为绝对余额；转账本金/到账/手续费是增量。负债账户数据库正数为欠款，负数为溢缴存款；网站显示相反符号。独立资产和借贷本金非负。业务日期 `YYYY-MM-DD` 或 `YYYY-MM-DDTHH:mm` 为 UTC+8；返回时间戳为 UTC ISO。计划 nextAt 可在未来，余额记录日期不可在未来。
查询页 limit 最多 100；图标固定 60；历史和资金往来使用 cursor，列表使用 offset。净资产轨迹沿用范围上限：日 366 天、周 3 年、月 10 年。金属和汇率返回最近 100 条。大备份通过文件入口传输。
## 备份、图标和敏感操作
备份追加：`file_upload_request(kind=backup)` → 使用返回 URL 和当前 Bearer 以 multipart/form-data 的 file 字段上传 ZIP/旧 JSON → 获取 token 或 `file_status` → `import_preview` → `backup_import` → 网页核对影响并验证密码 → `operation_get`。文件上传上限 512 MiB，ZIP 解压上限沿用现有 1 GiB；实际预检与追加恢复沿用现有严格校验和事务，任何冲突不修改账目。
完整导出：`backup_export` → 网页密码确认 → `operation_get` 获得 10 分钟有效的 GET URL → 同一连接 Bearer 下载 ZIP。URL 单独不可下载，其他用户/连接不可下载，账目变化必须重新确认。备份包含隐藏项目，但不含密码、Cookie 或 MCP 令牌。Agent 授权、草稿和调用日志不属于财务备份。
图标：`file_upload_request(kind=icon)` 上传不超过 2 MiB 的图像 → `icon_publish` 保存私有图标；shared=true 需敏感权限、中文名称、网页明确确认 → `icon_image` 获取受 Bearer 保护的 PNG URL。
清空数据：`data_clear_request` → 网页展示项目/历史/计划数量 → 先在网页下载最新备份 → 验证当前密码并输入“确定清空” → 提交 → `operation_get`。已有备份指纹与 10 分钟有效期规则保留，任何账目变化都要求重新备份。登录账号和共享图标保留。
当前产品不存在账户注销、任意单个持仓删除、覆盖导入、批量删除和另外的分类实体；因此不新增此类业务。已有删除路径是历史、资金往来、计划删除及备份保护的全量清空，完整支持。名称、分组、分类、图标、归档和统计开关通过 position_update/settings_update 设置。完整覆盖和逐项证据见 [覆盖矩阵](mcp-coverage.md)。
## 服务和代理
采用无状态 Streamable HTTP：每个 POST 新建 server/transport，独立 Bearer 认证；关闭响应时释放 transport。响应为 SDK 标准 JSON MCP 结果，支持初始化、协商、工具发现和调用。GET/DELETE 返回 405，没有长期 SSE 会话或会话凭证。当前没有订阅通知需求。
现有备份上传及 MCP 文件票据在进程内，10–15 分钟过期；进程重启或切换节点后需重新上传/生成入口。**当前部署必须单 API 实例**，不能直接在多节点间轮询文件请求；OAuth、令牌、草稿、幂等和审计本身已持久化。日志不保存工具参数、密码、令牌或财务内容，管理页只展示用户自己的最近 100 条。
反向代理参考（示例未经实际部署，修改为自己的 HTTPS 域名及上游）：
```nginx
location = /mcp {
proxy_pass http://127.0.0.1:3100;
proxy_set_header Host $host;
proxy_buffering off;
proxy_read_timeout 330s;
proxy_send_timeout 330s;
}
location /api/ {
proxy_pass http://127.0.0.1:3100;
proxy_set_header Host $host;
client_max_body_size 512m;
proxy_read_timeout 330s;
}
# 同样代理 /.well-known/、/authorize、/token、/register、/revoke。
# 前端静态站点与 MCP_WEB_URL 应位于已配置的 HTTPS origin。
```powershell
cd E:\WorthPath
.\scripts\pnpm.ps1 install
# 生成 Prisma 前暂停 API，Windows 会锁定引擎 DLL。
.\scripts\pnpm.ps1 db:generate
.\scripts\pnpm.ps1 db:migrate
.\scripts\pnpm.ps1 dev
```
用户认证数据不进入全局共享变量。SDK OAuth 路由包含进程内限流，现有登录限流也保留，已认证动作按用户及来源 IP 限流。生产单实例应另外配置代理级流量限制和日志保留策略；不得在代理访问日志中记录 Authorization、上传正文或敏感查询参数。数据库账号需要现有 DDL 迁移权限及正常业务 DML 权限。
| 环境变量 | 本地示例 | 用途 |
| ------------------- | ------------------------- | ------------------------------------ |
| MCP_PUBLIC_URL | http://localhost:3100/mcp | 规范资源 URL，路径必须 /mcp |
| MCP_WEB_URL | http://localhost:5173 | 网页授权及草稿确认入口 |
| MCP_ALLOWED_ORIGINS | http://localhost:5173 | 精确 Origin 列表，逗号分隔，无通配符 |
## 实际验证与交付
本次没有新增环境变量。保留本机 .env；示例不含凭据。生产必须 HTTPS、COOKIE_SECURE=true、准确 WEB_ORIGIN。Host 匹配规范资源；带 Origin 的请求匹配白名单，无 Origin 的非浏览器客户端允许接入。不得用任意转发头构造授权地址。
迁移：`20261003090000_agent_access` 新增授权/令牌/策略/操作 5 表；`20261003100000_agent_audit` 新增无参数调用审计；`20261003110000_agent_comments` 补齐 6 张新表字段的 MySQL 注释。原有财务表与记录保留。已经 migrate deploy，未执行 reset。
服务采用无状态 Streamable HTTP，请求结束关闭 transport/server；不共享用户认证上下文，不支持长期 GET SSE 或持久会话。代理转发规范 Host，禁用 MCP 响应缓冲，超时建议 330 秒；同时代理 /.well-known/、/authorize、/token、/register、/revoke 和 /api/。网站备份上传上限 512 MiB，ZIP 解压总计 1 GiB，代理配置对应 body 限制。日志不能保存 Authorization、密码、令牌或上传正文。
主要修改：原 8 个业务模块及 auth 抽取 BusinessService；database 增加事务上下文；新增 `src/mcp/{oauth,catalogue,operations,files,management,transport}.ts`；设置页新增 AgentConnections；SDK 精确版本和 pnpm lock；新增真实 MCP 测试及只读 probe。
实际通过：前后端 typecheck/build、36 项单元检查、18 组真实 REST/MySQL 回归、3 组真实官方 MCP SDK 端到端检查，工具发现验证 49 个工具（原 mcp:probe 的 48 个工具上增加 metal_holding_create）。新迁移 deploy 成功，实际 MySQL 17 张表（含 Prisma 迁移表）、159 个字段注释完整。测试真实连接 MySQL，使用随机临时用户并清理，未替代现有 REST 回归。贵金属创建、待估值、买入成本、盈亏及报价完成后的页面自动同步已通过真实浏览器验证，测试用户已清理。端到端文件传输、事务回滚、归属、金额精度、幂等、并发、失效/撤销和 OAuth 均在测试中检查；外部行情源的正常和失败路径由原业务单元测试验证，不保证外部报价服务实时可用。
部署未执行；未推送代码；其他客户端及实际 HTTPS/代理兼容性尚未验证。
当前实际通过前后端类型检查/构建、34 项单元测试、18 组 REST/MySQL、4 组官方 SDK 测试。24 项迁移已 deploy；17 张表、159 个字段注释完整。未部署或推送。
docs/update-2026-10-02.md
+2
View File
@@ -1,5 +1,7 @@
# 2026-10-02 更新验收与使用
> 历史验收记录：2026-10-04 起所有旧备份兼容与单文件 JSON 支持已删除，当前仅接受 ZIP v9；本文旧版本测试记录不代表现行功能。现行 MCP 权限与工具范围见 [本次更新](update-agent-backup-2026-10-04.md)。
## 本次范围
按主目录 `update.md` 的要求完成 13 项代码更新，包括执行期间追加的红色金额和收支日历；完成时间为 2026-10-02 17:37（Asia/Hong_Kong）。
docs/update-2026-10-03.md
+2
View File
@@ -1,5 +1,7 @@
# 2026-10-03 账号、删除与备份更新
> 历史验收记录：2026-10-04 起所有旧备份兼容与单文件 JSON 支持已删除，当前仅接受 ZIP v9；本文旧版本测试记录不代表现行功能。现行 MCP 权限与工具范围见 [本次更新](update-agent-backup-2026-10-04.md)。
## 已完成
- 设置分类新增“账号与密码”。可单独修改账号、密码或同时修改，须验证当前密码；新密码须二次输入。服务端沿用账号格式、密码长度和认证限流，重复账号返回冲突；在事务中撤销全部旧会话并重新签发当前会话，财务数据和个人设置保留。
docs/update-agent-backup-2026-10-04.md
+60
View File
@@ -0,0 +1,60 @@
# 2026-10-04 Agent、备份与界面更新
本次按 update.md 和聊天补充要求完成。MCP 工具由 49 个调整为 39 个；敏感操作与汇率、贵金属报价修改退出 MCP 范围。该范围变更取代最初的全部业务 MCP 覆盖要求，网站原业务入口保留。
## 用户使用
进入「设置与备份 → 连接 Agent」。默认仅显示服务地址与复制教程，其他内容分为「权限与工具」「连接管理」「操作记录」。教程、SDK 配置与个人令牌表单按需展开。工具清单来自实际后端注册内容。复制教程不会包含密码或令牌。
OAuth 授权选择只读、草稿修改或直接写入；个人令牌创建也选择相同三档。read 为必需基础权限；draft 与 write 互斥。隐藏账户读取与修改为独立附加授权，默认关闭；修改还要求读取权限及 draft/write。网页解锁不会自动授予 Agent。旧全局策略入口及运行时判断已移除；已有 write 连接现在直接执行普通修改，如需草稿应撤销并重新授权 read draft。
个人令牌期限为 1、3、7、30、365 天或永久；只展示一次完整值，数据库保存摘要。永久令牌每次请求检查资源与撤销；内部会话有界续期。OAuth 仍使用一小时访问令牌和三十天刷新授权，刷新轮换。实际接入步骤、环境示例和经过验证的官方 SDK 配置见 [MCP 接入](mcp.md)。
贵金属手动报价入口已从网页、REST 与 MCP 删除。创建、编辑和 MCP Schema 也不再提供纯度输入，新持仓按默认比例 1 估值；保留已有比例、报价来源及历史金额，不静默改写既有账目。重量、可选买入成本、盈亏、自动估值和网站报价刷新保留。账户卡片不重复显示分组徽标，分组标题、筛选与排序保留。
## 仅支持当前 ZIP v9
网站「备份与恢复」下载新的 ZIP，并通过上传预检、影响预览、确认追加恢复。单文件 JSON（包括 v3）全部拒绝；ZIP v3–v8 也拒绝，不保留补字段、缺文件回退或版本分支。旧 /api/backup/import 与 /api/backup/preview JSON 路由删除；仅保留 /api/backup、/upload、/import-file 与原清空资格流程。
ZIP 内仍有可读 JSON 数据文件及校验摘要，但不能将单文件 JSON 作为备份上传。manifest version=9，所有当前文件、设置和元数据必须完整。上传 512 MiB、解压总计 1 GiB；文件绑定用户与会话、十五分钟失效。预检失败删除临时上传；正式恢复冲突或失败在事务中回滚。
升级前导出的旧备份无法再导入，请从升级后的网站重新导出。此次没有删除用户保存的备份文件，也没有改写财务记录。备份操作仅在网站完成，MCP 不提供导出、恢复或备份上传。
## 迁移、文件与启动
两项新增迁移已在本机 MySQL 应用：
- 20261004090000_agent_permanent_tokens：AgentGrant.expiresAt 可为空，表示可撤销的永久 PAT。
- 20261004103000_agent_connection_permissions：更新权限字段及已停用策略表的说明，不删除旧策略行。
自动审批拒绝了 DROP TABLE 和批量取消待确认操作的提案，原因是具体数据副作用未获授权。因此采用保留原数据的实现；历史 AgentPolicy 表不参与权限判断，已撤下工具的旧草稿无法提交。未执行 reset、drop 或批量取消。
当前 24 项迁移状态最新；17 张表（含 Prisma 迁移表）、159 个字段注释全部核验通过。核验清单在 [database-comments.json](database-comments.json)。无新增环境变量、无新依赖、无硬编码数据库或授权凭据。
主要修改文件组：
- API：backup.ts、backup-format.ts、zip.ts、metals.ts、openapi.ts。
- MCP：catalogue.ts、oauth.ts、operations.ts、files.ts、management.ts、transport.ts、information.ts。
- 网页：AgentConnections.tsx、MetalPanel.tsx、App.tsx、style.css 及两份翻译字典。
- 数据：Prisma Schema 和两项迁移。
- 测试：ZIP、MCP、贵金属与设置及所有使用备份恢复的 REST 测试；backup-fixture.ts 将测试数据打包成 ZIP，实际调用上传/确认 API，没有调用已删除 JSON 路由。
```powershell
cd E:\WorthPath
# 暂停 API 后生成客户端；保留现有 apps/api/.env。
.\scripts\pnpm.ps1 db:generate
.\scripts\pnpm.ps1 db:migrate
.\scripts\pnpm.ps1 dev
```
现有开发地址 http://localhost:5173，MCP http://localhost:3100/mcp。本次隔离回归用 3101/3102；临时测试服务完成后关闭。没有修改本机 .env，没有部署或推送。README、update.md 原有删除及 Vite 的用户修改保持未提交，只提交与此次功能直接相关的文档更改。
## 实际验证
- 前后端 typecheck 与生产 build 通过。
- 34 项单元测试通过：精确金额、历史重放、行情失败保留、完整 ZIP 校验、旧版本拒绝、大量记录、无缺字段回退。
- 18 组真实 REST/MySQL 通过：全部原业务、配对余额、历史、计划、隐私、设置和 ZIP 恢复；实际上传 JSON v1/v2/v3/v9 都返回 400，旧 JSON 路由返回 404，目标数据不变。
- 4 组官方 SDK 1.31.0 MCP 测试通过：39 工具、初始化/发现/调用、普通写入和草稿、幂等/并发/回滚、只读拒绝写入、隐藏读取不授予修改、永久令牌会话续期、期限和撤销、资源/来源限制、OAuth DCR/PKCE/一次性码/轮换及越范围授权拒绝。
- 临时账户真实浏览器验证：默认页面分区、折叠表单、固定期限、三档权限、隐藏权限默认关闭、复制教程成功提示、账户卡片无分组徽标，贵金属新增与编辑无纯度或手动报价输入。截图在工作区外的验证目录，docs 不保存图片；临时用户及虚构账户清理。
没有验证商业 Agent 配置、MCP Inspector 或生产 HTTPS 反向代理；未声称所有客户端兼容。外部行情供应商实时可用性不作为本次通过条件。完整当前功能覆盖与撤下项见 [覆盖矩阵](mcp-coverage.md)。
docs/update-group-drag-2026-10-03.md
+2
View File
@@ -1,5 +1,7 @@
# 2026-10-03 分组拖拽与账户分行
> 历史验收记录：2026-10-04 起所有旧备份兼容与单文件 JSON 支持已删除，当前仅接受 ZIP v9；本文旧版本测试记录不代表现行功能。现行 MCP 权限与工具范围见 [本次更新](update-agent-backup-2026-10-04.md)。
## 使用方式
分组排序弹窗移除上下移动按钮，改为带拖拽手柄、分组名称和序号的列表。按住手柄拖到目标位置即可调整顺序，拖拽时高亮当前分组，靠近列表边缘自动滚动。点击保存后，账户页、分组筛选及账户选择弹窗同步使用新顺序；取消弹窗不会保存。
docs/update-group-order-2026-10-03.md
+2
View File
@@ -1,5 +1,7 @@
# 2026-10-03 账户分组排序
> 历史验收记录：2026-10-04 起所有旧备份兼容与单文件 JSON 支持已删除，当前仅接受 ZIP v9；本文旧版本测试记录不代表现行功能。现行 MCP 权限与工具范围见 [本次更新](update-agent-backup-2026-10-04.md)。
当前排序界面已改为拖拽；最新操作及全部账户分行行为见 [后续更新](update-group-drag-2026-10-03.md)。以下保留首轮验收记录。
## 使用方式
docs/update-inclusion-metals-2026-10-03.md
+2
View File
@@ -1,5 +1,7 @@
# 账户转账、计入总览与贵金属估价
> 历史验收记录：2026-10-04 起所有旧备份兼容与单文件 JSON 支持已删除，当前仅接受 ZIP v9；本文旧版本测试记录不代表现行功能。现行 MCP 权限与工具范围见 [本次更新](update-agent-backup-2026-10-04.md)。
完成与验收：2026-10-03 18:56（UTC+8）。
## 账户转账
docs/update-metal-grams-2026-10-03.md
+2
View File
@@ -1,5 +1,7 @@
# 贵金属克数与数据库注释更新
> 历史验收记录：2026-10-04 起所有旧备份兼容与单文件 JSON 支持已删除，当前仅接受 ZIP v9；本文旧版本测试记录不代表现行功能。现行 MCP 权限与工具范围见 [本次更新](update-agent-backup-2026-10-04.md)。
独立资产新增弹窗选择「贵金属」后，填写黄金/白银、克数、纯度、原币和业务时间，无需填写金额或市场单价。默认随参考价自动估值；没有有效报价时为「待估值」，总览提示不完整，不把未知价值作为已知零值。后续自动/手动报价继续沿用现有 MetalsService 和历史逻辑。
买入价为可选的每克实物成本（原币）。成本 = 总克数 × 买入价；估值 = 总克数 × 纯度 × 对应币种纯金属每克报价；盈亏 = 当前估值 − 成本。全程 Decimal，金额 8 位小数四舍五入；每克成本最多 12 位整数、12 位小数且必须大于零。它是估值盈亏，不包含未记录的税费/已实现卖出收益。省略或清空价格不显示盈亏，缺少估值时盈亏待定。旧贵金属资产可在详情补充成本。
update.md
+14
View File
@@ -54,6 +54,20 @@
- ~~独立资产中贵金属支持估价，更新方式和汇率一致~~ — 已完成并验证：2026-10-03 18:56
- ~~贵金属为克数，不用设置价格，可以设置买入价格（当设置了之后会显示盈亏）~~ — 已完成并通过真实 REST/MCP 测试：2026-10-03 22:40（UTC+8）；浏览器补充验证与自动估价同步修复完成：2026-10-03 22:55（UTC+8），见 docs/update-metal-grams-2026-10-03.md
- ~~所有MySQL数据表要补充注释~~ — 已完成并验证：2026-10-03 22:40（UTC+8），17 张表、159 个字段，包括 Prisma 迁移表。
- ~~删除贵金属估价手动录入功能~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~优化MCP使用方法，在页面显示使用教程（可以直接复制到agent）~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~优化MCP令牌时间设置方法（有固定的选项1 3 7 30day 1yaer 永久）~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~MCP 页面可以显示可以操作的事情~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~页面中需要可以详细描述read draft write sensitive可操作的具体事情（可不显示）~~ — 已完成并验证：2026-10-04 01:43（UTC+8）；按后续要求保留三档权限说明，sensitive 已撤下。
- ~~优化MCP设置界面~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~MCP删除敏感操作的功能，删除修改汇率，贵金属报价的功能~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~可以设置是否允许读取修改隐藏账号，~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~删除网站写入策略，直接按照连接权限设置即可（包含3种权限读 草稿修改 直接写入）~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~删除贵金属的纯度设置~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~优化Agent界面，当前页面显示的太复杂，太乱了，用户不需要一次看到这么多东西~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~在账号页的账号卡片中，不需要显示这个卡片的分组~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~删除所有旧备份兼容，仅支持当前 ZIP v9~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
- ~~删除单文件 JSON 备份支持，包括 JSON v3~~ — 已完成并验证：2026-10-04 01:43（UTC+8）
验证与部署边界见 [更新说明](docs/update-2026-10-02.md)。