feat(hub): usage fact breakdown API + admin usage/session UI + release v0.0.34

Expose UsageFact kind/capability rollups on org and project usage reports,
and add admin pages that separate model tokens from external-capability meters.

hub/admin-web/src/lib/api.ts

@@ -168,6 +168,16 @@ export interface FeishuApplicationConnection {
 	updatedAt: string;
 }
 
+export interface CapabilityConnection {
+	id: string;
+	capabilityId: string;
+	status: 'DRAFT' | 'ACTIVE' | 'DISABLED';
+	activeVersion: number | null;
+	keyId: string | null;
+	createdAt: string;
+	updatedAt: string;
+}
+
 export interface UsageTotals {
 	runCount: number;
 	runsWithCost: number;
@@ -183,13 +193,81 @@ export interface ProjectUsageRow extends UsageTotals {
 	folderId: string | null;
 }
 
+/** Ledger slice from UsageFact (ADR-0026): separates model tokens vs external meters. */
+export interface UsageBreakdownRow {
+	kind: string;
+	provider: string;
+	model: string | null;
+	capabilityId: string | null;
+	unit: string | null;
+	factCount: number;
+	factsWithCost: number;
+	factsWithoutCost: number;
+	inputTokens: number;
+	outputTokens: number;
+	quantity: number | null;
+	costUsd: number | null;
+}
+
 export interface UsageReport {
 	from: string | null;
 	to: string | null;
 	projects: ProjectUsageRow[];
 	totals: UsageTotals;
+	breakdown: UsageBreakdownRow[];
 }
 
+export interface ProjectUsageReport extends ProjectUsageRow {
+	from: string | null;
+	to: string | null;
+	breakdown: UsageBreakdownRow[];
+}
+
+export interface UsageFactRow {
+	id: string;
+	occurredAt: string;
+	kind: string;
+	provider: string;
+	model: string | null;
+	inputTokens: number | null;
+	outputTokens: number | null;
+	quantity: number | null;
+	unit: string | null;
+	costUsd: number | null;
+	costSource: string;
+	capabilityId: string | null;
+	correlationId: string | null;
+}
+
+export interface SessionRunRow {
+	id: string;
+	status: string;
+	model: string;
+	provider: string;
+	inputTokens: number | null;
+	outputTokens: number | null;
+	costUsd: number | null;
+	costSource: string | null;
+	startedAt: string;
+	finishedAt: string | null;
+	error: string | null;
+	usageFacts: UsageFactRow[];
+}
+
+export interface SessionDetail {
+	id: string;
+	provider: string;
+	roleId: string;
+	model: string;
+	title: string | null;
+	createdAt: string;
+	updatedAt: string;
+	archivedAt: string | null;
+	project: { id: string; name: string };
+	runs: SessionRunRow[];
+}
+
+
 export type CapacityDimension =
 	| 'requestRate'
 	| 'requestBodySize'
@@ -343,6 +421,8 @@ export const api = {
 		get(`${orgBase(slug)}/projects/${projectId}/sessions${limit !== undefined ? `?limit=${limit}` : ''}`) as Promise<{
 			sessions: SessionSummary[];
 		}>,
+	session: (slug: string, sessionId: string) =>
+		get(`${orgBase(slug)}/sessions/${encodeURIComponent(sessionId)}`) as Promise<SessionDetail>,
 	usage: (slug: string, params?: { from?: string; to?: string; folderId?: string }) => {
 		const q = new URLSearchParams();
 		if (params?.from) q.set('from', params.from);
@@ -351,6 +431,16 @@ export const api = {
 		const qs = q.toString();
 		return get(`${orgBase(slug)}/usage${qs ? `?${qs}` : ''}`) as Promise<UsageReport>;
 	},
+	projectUsage: (slug: string, projectId: string, params?: { from?: string; to?: string }) => {
+		const q = new URLSearchParams();
+		if (params?.from) q.set('from', params.from);
+		if (params?.to) q.set('to', params.to);
+		const qs = q.toString();
+		return get(
+			`${orgBase(slug)}/projects/${encodeURIComponent(projectId)}/usage${qs ? `?${qs}` : ''}`,
+		) as Promise<ProjectUsageReport>;
+	},
+
 
 	providerConnections: (slug: string) =>
 		get(`${orgBase(slug)}/provider-connections`) as Promise<{ connections: ProviderConnectionRow[] }>,
@@ -381,6 +471,21 @@ export const api = {
 	disableFeishuApplication: (slug: string) =>
 		del(`${orgBase(slug)}/feishu-application-connection`) as Promise<FeishuApplicationConnection>,
 
+	capabilityConnections: (slug: string) =>
+		get(`${orgBase(slug)}/capability-connections`) as Promise<{ connections: CapabilityConnection[] }>,
+	capabilityConnection: (slug: string, capabilityId: string) =>
+		get(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`) as Promise<{
+			connection: CapabilityConnection | null;
+		}>,
+	rotateCapabilityConnection: (
+		slug: string,
+		capabilityId: string,
+		body: { accessKeyId: string; accessKeySecret: string; endpoint: string },
+	) =>
+		put(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`, body) as Promise<CapabilityConnection>,
+	disableCapabilityConnection: (slug: string, capabilityId: string) =>
+		del(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`) as Promise<CapabilityConnection>,
+
 	capacityPolicy: (slug: string) => get(`${orgBase(slug)}/capacity-policy`) as Promise<CapacityPolicyView>,
 	setCapacityPolicy: (slug: string, body: { limits: Partial<Record<CapacityDimension, number | null>> }) =>
 		put(`${orgBase(slug)}/capacity-policy`, body) as Promise<CapacityPolicyView>,

hub/admin-web/src/lib/format.ts

@@ -29,6 +29,52 @@ export function fmtNum(n: number): string {
 	return n.toLocaleString();
 }
 
+const USAGE_KIND_LABELS: Record<string, string> = {
+	model_completion: '模型完成',
+	external_capability: '外部能力',
+	tool_proxy: '工具代理',
+};
+
+const METER_UNIT_LABELS: Record<string, string> = {
+	pages: '页',
+	audio_seconds: '音频秒',
+	invocations: '次调用',
+};
+
+export function usageKindLabel(kind: string): string {
+	return USAGE_KIND_LABELS[kind] ?? kind;
+}
+
+export function meterUnitLabel(unit: string | null | undefined): string {
+	if (!unit) return '—';
+	return METER_UNIT_LABELS[unit] ?? unit;
+}
+
+export function fmtQuantity(quantity: number | null | undefined, unit: string | null | undefined): string {
+	if (quantity === null || quantity === undefined) return '—';
+	const u = meterUnitLabel(unit);
+	return u === '—' ? fmtNum(quantity) : `${fmtNum(quantity)} ${u}`;
+}
+
+export function fmtTokens(input: number | null | undefined, output: number | null | undefined): string {
+	const hasIn = input !== null && input !== undefined;
+	const hasOut = output !== null && output !== undefined;
+	if (!hasIn && !hasOut) return '—';
+	return `${fmtNum(input ?? 0)} / ${fmtNum(output ?? 0)}`;
+}
+
+export function runStatusLabel(status: string): string {
+	const key = status.toUpperCase();
+	if (key === 'COMPLETED') return '完成';
+	if (key === 'FAILED') return '失败';
+	if (key === 'CANCELED') return '取消';
+	if (key === 'TIMED_OUT') return '超时';
+	if (key === 'RUNNING') return '运行中';
+	if (key === 'QUEUED') return '排队';
+	return status;
+}
+
+
 export function orgRoleLabel(role: string): string {
 	const key = role.toUpperCase() as OrgRole;
 	return ORG_ROLE_LABELS[key] ?? role;

hub/admin-web/src/routes/+layout.svelte

@@ -20,6 +20,7 @@
 
 	const navItems = [
 		{ key: 'overview', label: '概览', icon: 'overview' as const },
+		{ key: 'usage', label: '用量', icon: 'overview' as const },
 		{ key: 'members', label: '成员', icon: 'members' as const },
 		{ key: 'teams', label: '团队', icon: 'teams' as const },
 		{ key: 'projects', label: '项目', icon: 'projects' as const },
@@ -28,6 +29,7 @@
 		{ key: 'skills', label: '技能', icon: 'roles' as const },
 		{ key: 'roles', label: '角色', icon: 'roles' as const },
 		{ key: 'feishu', label: '飞书', icon: 'feishu' as const },
+		{ key: 'capabilities', label: '能力', icon: 'provider' as const },
 	];
 
 	function isAdmin(org: OrgMembership): boolean {
@@ -80,10 +82,10 @@
 		if (key === 'overview') return `/admin/org/${slug}`;
 		return `/admin/org/${slug}/${key}`;
 	}
-
 	function pageTitle(): string {
 		const key = activeKey();
 		if (key === 'overview' || key === '') return '概览';
+		if (key === 'sessions') return '会话详情';
 		return navItems.find((i) => i.key === key)?.label ?? '管理后台';
 	}
 

hub/admin-web/src/routes/admin/org/[slug]/+page.svelte

@@ -94,19 +94,56 @@
 	<div class="mb-4 flex items-end justify-between gap-3">
 		<div>
 			<h2 class="saas-section-title">用量概览</h2>
-			<p class="saas-muted">全组织智能体运行汇总</p>
+			<p class="saas-muted">totals 含全部 UsageFact；分账明细见用量页。</p>
 		</div>
+		<a class="saas-btn-secondary py-1.5! text-sm" href={`/admin/org/${orgSlug}/usage`}>完整用量报告</a>
 	</div>
 
 	<div class="mb-6 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
 		<StatCard label="运行总数" value={fmtNum(usage.totals.runCount)} />
 		<StatCard label="有成本运行" value={fmtNum(usage.totals.runsWithCost)} />
-		<StatCard label="无成本运行" value={fmtNum(usage.totals.runsWithoutCost)} />
+		<StatCard label="无成本运行" value={fmtNum(usage.totals.runsWithoutCost)} hint="未知 ≠ $0" />
 		<StatCard label="输入 tokens" value={fmtNum(usage.totals.inputTokens)} />
 		<StatCard label="输出 tokens" value={fmtNum(usage.totals.outputTokens)} />
 		<StatCard label="成本 (USD)" value={fmtCost(usage.totals.costUsd)} />
 	</div>
 
+	{#if usage.breakdown.length > 0}
+		<div class="saas-card overflow-hidden mb-6">
+			<div class="border-b border-surface-200 px-5 py-3 flex items-center justify-between gap-3">
+				<div>
+					<h3 class="text-sm font-semibold text-surface-800">消费来源（Top）</h3>
+					<p class="saas-muted text-xs">模型完成 vs 外部能力，按成本降序前 5</p>
+				</div>
+				<a class="text-sm text-primary-700 hover:underline" href={`/admin/org/${orgSlug}/usage`}>查看全部分账</a>
+			</div>
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>类型</th>
+							<th>供应方</th>
+							<th>模型 / 能力</th>
+							<th>次数</th>
+							<th>成本</th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each [...usage.breakdown].sort((a, b) => (b.costUsd ?? -1) - (a.costUsd ?? -1)).slice(0, 5) as row}
+							<tr>
+								<td class="text-sm">{row.kind === 'external_capability' ? '外部能力' : row.kind === 'model_completion' ? '模型完成' : row.kind}</td>
+								<td class="font-mono text-xs">{row.provider}</td>
+								<td class="font-mono text-xs">{row.capabilityId ?? row.model ?? '—'}</td>
+								<td class="tabular-nums">{fmtNum(row.factCount)}</td>
+								<td class="tabular-nums">{fmtCost(row.costUsd)}</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		</div>
+	{/if}
+
 	<div class="saas-card overflow-hidden">
 		<div class="border-b border-surface-200 px-5 py-3">
 			<h3 class="text-sm font-semibold text-surface-800">按项目用量</h3>
@@ -129,7 +166,11 @@
 					<tbody>
 						{#each usage.projects as p}
 							<tr>
-								<td class="font-medium">{p.projectName}</td>
+								<td class="font-medium">
+									<a class="hover:text-primary-700 hover:underline" href={`/admin/org/${orgSlug}/projects/${p.projectId}`}>
+										{p.projectName}
+									</a>
+								</td>
 								<td class="tabular-nums">{fmtNum(p.runCount)}</td>
 								<td class="tabular-nums text-surface-600">{fmtNum(p.inputTokens)} / {fmtNum(p.outputTokens)}</td>
 								<td class="tabular-nums">{fmtCost(p.costUsd)}</td>

hub/admin-web/src/routes/admin/org/[slug]/capabilities/+page.svelte

@@ -0,0 +1,202 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type CapabilityConnection } from '$lib/api';
+	import { fmtDate } from '$lib/format';
+	import { Label } from 'bits-ui';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const slug = $derived(page.params.slug ?? '');
+
+	const KNOWN_CAPABILITIES = [
+		{ id: 'pdf_to_md_bundle', label: 'PDF → Markdown', description: '将 PDF 转换为带图片的 Markdown bundle（阿里云文档智能，含公式 LaTeX 识别）' },
+		{ id: 'audio_video_to_text', label: '音视频 → 文本', description: '将音频/视频转写为文本（阿里云文档智能，按秒计费）' },
+	] as const;
+
+	let connections = $state<Map<string, CapabilityConnection>>(new Map());
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let editingCap = $state<string | null>(null);
+	let accessKeyId = $state('');
+	let accessKeySecret = $state('');
+	let endpoint = $state('docmind-api.cn-hangzhou.aliyuncs.com');
+	let saving = $state(false);
+	let disabling = $state<string | null>(null);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const res = await api.capabilityConnections(slug);
+			connections = new Map(res.connections.map((c) => [c.capabilityId, c]));
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function startEdit(capId: string) {
+		editingCap = capId;
+		accessKeyId = '';
+		accessKeySecret = '';
+		endpoint = 'docmind-api.cn-hangzhou.aliyuncs.com';
+	}
+
+	function cancelEdit() {
+		editingCap = null;
+	}
+
+	async function save(capId: string) {
+		if (accessKeyId.trim() === '' || accessKeySecret.trim() === '' || endpoint.trim() === '') {
+			toastError('AccessKey ID、AccessKey Secret、Endpoint 均为必填');
+			return;
+		}
+		saving = true;
+		try {
+			const result = await api.rotateCapabilityConnection(slug, capId, {
+				accessKeyId: accessKeyId.trim(),
+				accessKeySecret: accessKeySecret.trim(),
+				endpoint: endpoint.trim(),
+			});
+			connections.set(capId, result);
+			connections = new Map(connections);
+			editingCap = null;
+			toastSuccess('能力凭据已保存');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	async function disable(capId: string) {
+		if (!confirm('停用后该能力将不可用，确定停用？')) return;
+		disabling = capId;
+		try {
+			const result = await api.disableCapabilityConnection(slug, capId);
+			connections.set(capId, result);
+			connections = new Map(connections);
+			toastSuccess('已停用能力连接');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			disabling = null;
+		}
+	}
+
+	function statusBadge(status: string): string {
+		if (status === 'ACTIVE') return 'saas-badge-primary';
+		if (status === 'DISABLED') return 'saas-badge-error';
+		return 'saas-badge-muted';
+	}
+
+	function statusLabel(status: string): string {
+		if (status === 'ACTIVE') return '已启用';
+		if (status === 'DISABLED') return '已停用';
+		return '草稿';
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader
+	title="外部能力"
+	description="管理文档/媒体转换服务的组织级凭据（ADR-0027）。凭据按组织隔离、版本化信封存储，缺失或校验失败即 fail-closed。"
+/>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	<div class="space-y-6">
+		{#each KNOWN_CAPABILITIES as cap}
+			{@const conn = connections.get(cap.id)}
+			<div class="saas-card-pad">
+				<div class="mb-3 flex items-start justify-between gap-3">
+					<div>
+						<div class="flex items-center gap-2">
+							<h3 class="saas-section-title">{cap.label}</h3>
+							{#if conn}
+								<span class={statusBadge(conn.status)}>{statusLabel(conn.status)}</span>
+							{:else}
+								<span class="saas-badge-muted">未配置</span>
+							{/if}
+						</div>
+						<p class="saas-muted mt-1 text-sm">{cap.description}</p>
+						<p class="mt-0.5 font-mono text-xs text-surface-500">{cap.id}</p>
+					</div>
+					<div class="flex items-center gap-2">
+						{#if conn?.status === 'ACTIVE'}
+							<button
+								class="saas-btn-ghost text-sm"
+								onclick={() => disable(cap.id)}
+								disabled={disabling === cap.id}
+							>
+								{disabling === cap.id ? '停用中…' : '停用'}
+							</button>
+						{/if}
+						<button
+							class="saas-btn-primary text-sm"
+							onclick={() => startEdit(cap.id)}
+							disabled={editingCap === cap.id}
+						>
+							{conn ? '轮换凭据' : '配置凭据'}
+						</button>
+					</div>
+				</div>
+
+				{#if conn}
+					<dl class="space-y-1.5 text-sm text-surface-700">
+						<div class="flex justify-between">
+							<dt class="text-surface-500">版本</dt>
+							<dd class="font-mono">{conn.activeVersion ?? '—'}</dd>
+						</div>
+						<div class="flex justify-between">
+							<dt class="text-surface-500">密钥 ID</dt>
+							<dd class="font-mono text-xs">{conn.keyId ?? '—'}</dd>
+						</div>
+						<div class="flex justify-between">
+							<dt class="text-surface-500">更新时间</dt>
+							<dd>{fmtDate(conn.updatedAt)}</dd>
+						</div>
+					</dl>
+				{/if}
+
+				{#if editingCap === cap.id}
+					<div class="mt-4 border-t border-surface-100 pt-4">
+						<p class="saas-muted mb-3 text-sm">
+							阿里云 RAM 用户的 AccessKey。密钥仅写入新版本，旧版本归档。
+						</p>
+						<div class="grid gap-4">
+							<div>
+								<Label.Root class="saas-label" for="ak-id-{cap.id}">AccessKey ID</Label.Root>
+								<input id="ak-id-{cap.id}" class="saas-input font-mono text-sm" bind:value={accessKeyId} />
+							</div>
+							<div>
+								<Label.Root class="saas-label" for="ak-secret-{cap.id}">AccessKey Secret</Label.Root>
+								<input id="ak-secret-{cap.id}" class="saas-input" type="password" bind:value={accessKeySecret} />
+							</div>
+							<div>
+								<Label.Root class="saas-label" for="endpoint-{cap.id}">Endpoint</Label.Root>
+								<input id="endpoint-{cap.id}" class="saas-input font-mono text-sm" bind:value={endpoint} />
+							</div>
+						</div>
+						<div class="mt-4 flex items-center justify-end gap-3">
+							<button class="saas-btn-ghost" onclick={cancelEdit} disabled={saving}>取消</button>
+							<button class="saas-btn-primary" onclick={() => save(cap.id)} disabled={saving}>
+								{saving ? '保存中…' : '保存'}
+							</button>
+						</div>
+					</div>
+				{/if}
+			</div>
+		{/each}
+	</div>
+{/if}

hub/admin-web/src/routes/admin/org/[slug]/projects/[projectId]/+page.svelte

@@ -7,8 +7,17 @@
 		type TeamRow,
 		type SessionSummary,
 		type ExplorerData,
+		type ProjectUsageReport,
 	} from '$lib/api';
-	import { fmtDate, permissionRoleLabel } from '$lib/format';
+	import {
+		fmtCost,
+		fmtDate,
+		fmtNum,
+		fmtQuantity,
+		fmtTokens,
+		permissionRoleLabel,
+		usageKindLabel,
+	} from '$lib/format';
 	import { PERMISSION_ROLES, PERMISSION_ROLE_LABELS } from '$lib/constants';
 	import PageHeader from '$lib/components/PageHeader.svelte';
 	import LoadingState from '$lib/components/LoadingState.svelte';
@@ -26,6 +35,7 @@
 	let proj = $state<ProjectDetail | null>(null);
 	let access = $state<TeamAccessEntry[]>([]);
 	let sessions = $state<SessionSummary[]>([]);
+	let projectUsage = $state<ProjectUsageReport | null>(null);
 	let teams = $state<TeamRow[]>([]);
 	let explorer = $state<ExplorerData | null>(null);
 	let loading = $state(true);
@@ -49,14 +59,18 @@
 			// Team list is needed for grant UI whenever the actor has project MANAGE
 			// (org admin or member). Sessions/explorer stay org-admin oversight only.
 			const needTeams = p.actorIsOrgAdmin === true || p.actorCanManageProject === true;
-			const [s, t, e] = await Promise.all([
+			const [s, t, e, u] = await Promise.all([
 				p.actorIsOrgAdmin ? api.sessions(slug, projectId) : Promise.resolve({ sessions: [] as SessionSummary[] }),
 				needTeams ? api.teams(slug) : Promise.resolve({ teams: [] as TeamRow[] }),
 				p.actorIsOrgAdmin ? api.explorer(slug) : Promise.resolve(null as ExplorerData | null),
+				p.actorIsOrgAdmin
+					? api.projectUsage(slug, projectId)
+					: Promise.resolve(null as ProjectUsageReport | null),
 			]);
 			sessions = s.sessions;
 			teams = t.teams;
 			explorer = e;
+			projectUsage = u;
 			if (p.actorIsOrgAdmin) {
 				moveFolder = p.folderId ?? '';
 			}
@@ -269,9 +283,67 @@
 	</div>
 
 	{#if actorIsOrgAdmin}
+		{#if projectUsage}
+			<div class="saas-card overflow-hidden mb-6">
+				<div class="border-b border-surface-200 px-5 py-3 flex items-center justify-between gap-3">
+					<div>
+						<h3 class="text-sm font-semibold">项目用量分账</h3>
+						<p class="saas-muted mt-0.5 text-xs">
+							{fmtNum(projectUsage.runCount)} 次运行 · 成本 {fmtCost(projectUsage.costUsd)} · tokens
+							{fmtTokens(projectUsage.inputTokens, projectUsage.outputTokens)}
+						</p>
+					</div>
+					<a class="text-sm text-primary-700 hover:underline" href={`/admin/org/${slug}/usage`}>组织报告</a>
+				</div>
+				{#if projectUsage.breakdown.length === 0}
+					<div class="px-5 py-4 text-sm text-surface-600">尚无 UsageFact。</div>
+				{:else}
+					<div class="overflow-x-auto">
+						<table class="data-table">
+							<thead>
+								<tr>
+									<th>类型</th>
+									<th>供应方</th>
+									<th>模型 / 能力</th>
+									<th>次数</th>
+									<th>计量</th>
+									<th>成本</th>
+								</tr>
+							</thead>
+							<tbody>
+								{#each projectUsage.breakdown as row}
+									<tr>
+										<td>
+											<span
+												class={row.kind === 'external_capability' ? 'saas-badge-primary' : 'saas-badge-success'}
+											>
+												{usageKindLabel(row.kind)}
+											</span>
+										</td>
+										<td class="font-mono text-xs">{row.provider}</td>
+										<td class="font-mono text-xs">{row.capabilityId ?? row.model ?? '—'}</td>
+										<td class="tabular-nums">{fmtNum(row.factCount)}</td>
+										<td class="tabular-nums text-xs">
+											{#if row.unit}
+												{fmtQuantity(row.quantity, row.unit)}
+											{:else}
+												{fmtTokens(row.inputTokens, row.outputTokens)}
+											{/if}
+										</td>
+										<td class="tabular-nums">{fmtCost(row.costUsd)}</td>
+									</tr>
+								{/each}
+							</tbody>
+						</table>
+					</div>
+				{/if}
+			</div>
+		{/if}
+
 		<div class="saas-card overflow-hidden">
 			<div class="border-b border-surface-200 px-5 py-3">
 				<h3 class="text-sm font-semibold">智能体会话</h3>
+				<p class="saas-muted mt-0.5 text-xs">点进会话可查看每次 run 的 UsageFact 分账（模型 / 外部能力）。</p>
 			</div>
 			{#if sessions.length === 0}
 				<EmptyState title="暂无会话" description="飞书侧触发智能体后会显示在此。" />
@@ -283,6 +355,7 @@
 							<th>模型</th>
 							<th>运行次数</th>
 							<th>更新</th>
+							<th></th>
 						</tr>
 					</thead>
 					<tbody>
@@ -292,6 +365,14 @@
 								<td class="font-mono text-xs">{s.model}</td>
 								<td class="tabular-nums">{s.runCount}</td>
 								<td class="text-surface-700">{fmtDate(s.updatedAt)}</td>
+								<td class="text-right">
+									<a
+										class="text-sm text-primary-700 hover:underline"
+										href={`/admin/org/${slug}/sessions/${s.id}`}
+									>
+										详情
+									</a>
+								</td>
 							</tr>
 						{/each}
 					</tbody>

hub/admin-web/src/routes/admin/org/[slug]/sessions/[sessionId]/+page.svelte

@@ -0,0 +1,235 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type SessionDetail, type SessionRunRow, type UsageFactRow } from '$lib/api';
+	import {
+		fmtCost,
+		fmtDate,
+		fmtNum,
+		fmtQuantity,
+		fmtTokens,
+		runStatusLabel,
+		usageKindLabel,
+	} from '$lib/format';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+	import Icon from '$lib/components/Icon.svelte';
+
+	const slug = $derived(page.params.slug ?? '');
+	const sessionId = $derived(page.params.sessionId ?? '');
+
+	let detail = $state<SessionDetail | null>(null);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+	let expandedRunId = $state<string | null>(null);
+
+	async function load() {
+		if (!slug || !sessionId) return;
+		loading = true;
+		error = null;
+		try {
+			detail = await api.session(slug, sessionId);
+			if (detail.runs.length > 0) {
+				expandedRunId = detail.runs[0]!.id;
+			}
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function statusClass(status: string): string {
+		const key = status.toUpperCase();
+		if (key === 'COMPLETED') return 'saas-badge-success';
+		if (key === 'FAILED' || key === 'TIMED_OUT' || key === 'CANCELED') return 'saas-badge-error';
+		return 'saas-badge-primary';
+	}
+
+	function factMeter(f: UsageFactRow): string {
+		if (f.unit) return fmtQuantity(f.quantity, f.unit);
+		if (f.inputTokens !== null || f.outputTokens !== null) {
+			return fmtTokens(f.inputTokens, f.outputTokens);
+		}
+		return '—';
+	}
+
+	function factSource(f: UsageFactRow): string {
+		if (f.capabilityId) return f.capabilityId;
+		if (f.model) return f.model;
+		return '—';
+	}
+
+	function runCostHint(run: SessionRunRow): string {
+		const factCost = run.usageFacts.reduce<number | null>((acc, f) => {
+			if (f.costUsd === null) return acc;
+			return (acc ?? 0) + f.costUsd;
+		}, null);
+		const cache = run.costUsd;
+		if (factCost !== null && cache !== null && Math.abs(factCost - cache) > 1e-9) {
+			return `运行缓存 ${fmtCost(cache)}；事实合计 ${fmtCost(factCost)}（缓存可能未含外部能力）`;
+		}
+		if (factCost !== null) return `事实合计 ${fmtCost(factCost)}`;
+		if (cache !== null) return `运行缓存 ${fmtCost(cache)}`;
+		return '成本未知';
+	}
+
+	function toggleRun(id: string) {
+		expandedRunId = expandedRunId === id ? null : id;
+	}
+
+	$effect(() => {
+		if (slug && sessionId) void load();
+	});
+</script>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else if detail}
+	<div class="mb-2">
+		<a
+			class="inline-flex items-center gap-1 text-sm text-surface-700 hover:text-primary-700"
+			href={`/admin/org/${slug}/projects/${detail.project.id}`}
+		>
+			<Icon name="arrow-left" class="h-4 w-4" />
+			返回项目 {detail.project.name}
+		</a>
+	</div>
+
+	<PageHeader
+		title={detail.title?.trim() || '未命名会话'}
+		description={`${detail.provider} · ${detail.roleId} · ${detail.model}`}
+	/>
+
+	<div class="saas-card-pad mb-6">
+		<dl class="grid gap-x-8 gap-y-3 text-sm sm:grid-cols-2 lg:grid-cols-3">
+			<div>
+				<dt class="text-surface-600">会话 ID</dt>
+				<dd class="mt-0.5 break-all font-mono text-xs">{detail.id}</dd>
+			</div>
+			<div>
+				<dt class="text-surface-600">项目</dt>
+				<dd class="mt-0.5">
+					<a class="text-primary-700 hover:underline" href={`/admin/org/${slug}/projects/${detail.project.id}`}>
+						{detail.project.name}
+					</a>
+				</dd>
+			</div>
+			<div>
+				<dt class="text-surface-600">创建 / 更新</dt>
+				<dd class="mt-0.5 text-surface-800">{fmtDate(detail.createdAt)} · {fmtDate(detail.updatedAt)}</dd>
+			</div>
+			{#if detail.archivedAt}
+				<div>
+					<dt class="text-surface-600">已归档</dt>
+					<dd class="mt-0.5">{fmtDate(detail.archivedAt)}</dd>
+				</div>
+			{/if}
+			<div>
+				<dt class="text-surface-600">运行数</dt>
+				<dd class="mt-0.5 tabular-nums">{fmtNum(detail.runs.length)}</dd>
+			</div>
+		</dl>
+	</div>
+
+	<div class="mb-3">
+		<h2 class="saas-section-title">运行与计费事实</h2>
+		<p class="saas-muted">每条 UsageFact 是一次可计费消费；外部能力与模型完成分开列出。</p>
+	</div>
+
+	{#if detail.runs.length === 0}
+		<div class="saas-card">
+			<EmptyState title="尚无运行" description="此会话还没有 Agent run。" />
+		</div>
+	{:else}
+		<div class="space-y-3">
+			{#each detail.runs as run (run.id)}
+				{@const open = expandedRunId === run.id}
+				<div class="saas-card overflow-hidden">
+					<button
+						type="button"
+						class="flex w-full items-start justify-between gap-3 px-5 py-4 text-left hover:bg-surface-50"
+						onclick={() => toggleRun(run.id)}
+					>
+						<div class="min-w-0 space-y-1">
+							<div class="flex flex-wrap items-center gap-2">
+								<span class={statusClass(run.status)}>{runStatusLabel(run.status)}</span>
+								<span class="font-mono text-xs text-surface-700">{run.provider} / {run.model}</span>
+								<span class="font-mono text-[11px] text-surface-500">{run.id}</span>
+							</div>
+							<div class="text-xs text-surface-700">
+								{fmtDate(run.startedAt)}
+								{#if run.finishedAt}
+									→ {fmtDate(run.finishedAt)}
+								{/if}
+							</div>
+							<div class="text-xs text-surface-600">{runCostHint(run)}</div>
+							{#if run.error}
+								<div class="text-xs text-error-700">{run.error}</div>
+							{/if}
+						</div>
+						<div class="shrink-0 text-right text-sm">
+							<div class="tabular-nums text-surface-800">{fmtTokens(run.inputTokens, run.outputTokens)}</div>
+							<div class="tabular-nums font-medium">{fmtCost(run.costUsd)}</div>
+							<div class="mt-1 text-[11px] text-surface-600">{open ? '收起事实' : `${run.usageFacts.length} 条事实`}</div>
+						</div>
+					</button>
+
+					{#if open}
+						<div class="border-t border-surface-200">
+							{#if run.usageFacts.length === 0}
+								<div class="px-5 py-4">
+									<p class="text-sm text-surface-600">此 run 没有 UsageFact（可能尚未结束或未记费）。</p>
+								</div>
+							{:else}
+								<div class="overflow-x-auto">
+									<table class="data-table">
+										<thead>
+											<tr>
+												<th>时间</th>
+												<th>类型</th>
+												<th>供应方</th>
+												<th>模型 / 能力</th>
+												<th>计量</th>
+												<th>成本</th>
+												<th>来源</th>
+												<th>关联 ID</th>
+											</tr>
+										</thead>
+										<tbody>
+											{#each run.usageFacts as fact}
+												<tr>
+													<td class="whitespace-nowrap text-xs text-surface-700">{fmtDate(fact.occurredAt)}</td>
+													<td>
+														<span
+															class={fact.kind === 'external_capability'
+																? 'saas-badge-primary'
+																: 'saas-badge-success'}
+														>
+															{usageKindLabel(fact.kind)}
+														</span>
+													</td>
+													<td class="font-mono text-xs">{fact.provider}</td>
+													<td class="font-mono text-xs">{factSource(fact)}</td>
+													<td class="tabular-nums text-xs">{factMeter(fact)}</td>
+													<td class="tabular-nums">{fmtCost(fact.costUsd)}</td>
+													<td class="font-mono text-[11px] text-surface-600">{fact.costSource}</td>
+													<td class="max-w-[10rem] truncate font-mono text-[11px] text-surface-500" title={fact.correlationId ?? ''}>
+														{fact.correlationId ?? '—'}
+													</td>
+												</tr>
+											{/each}
+										</tbody>
+									</table>
+								</div>
+							{/if}
+						</div>
+					{/if}
+				</div>
+			{/each}
+		</div>
+	{/if}
+{/if}

hub/admin-web/src/routes/admin/org/[slug]/usage/+page.svelte

@@ -0,0 +1,238 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type UsageReport, type UsageBreakdownRow } from '$lib/api';
+	import {
+		fmtCost,
+		fmtDateOnly,
+		fmtNum,
+		fmtQuantity,
+		fmtTokens,
+		usageKindLabel,
+	} from '$lib/format';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import StatCard from '$lib/components/StatCard.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+
+	const slug = $derived(page.params.slug ?? '');
+
+	let usage = $state<UsageReport | null>(null);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+	let from = $state('');
+	let to = $state('');
+
+	function toIsoStart(dateLocal: string): string | undefined {
+		if (!dateLocal) return undefined;
+		const d = new Date(`${dateLocal}T00:00:00`);
+		return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+	}
+
+	function toIsoEnd(dateLocal: string): string | undefined {
+		if (!dateLocal) return undefined;
+		const d = new Date(`${dateLocal}T23:59:59.999`);
+		return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+	}
+
+	async function load() {
+		if (!slug) return;
+		loading = true;
+		error = null;
+		try {
+			usage = await api.usage(slug, {
+				...(toIsoStart(from) !== undefined ? { from: toIsoStart(from) } : {}),
+				...(toIsoEnd(to) !== undefined ? { to: toIsoEnd(to) } : {}),
+			});
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function clearRange() {
+		from = '';
+		to = '';
+		void load();
+	}
+
+	function sourceLabel(row: UsageBreakdownRow): string {
+		if (row.capabilityId) return row.capabilityId;
+		if (row.model) return row.model;
+		return '—';
+	}
+
+	function meterCell(row: UsageBreakdownRow): string {
+		if (row.unit) return fmtQuantity(row.quantity, row.unit);
+		if (row.inputTokens > 0 || row.outputTokens > 0) return fmtTokens(row.inputTokens, row.outputTokens);
+		return '—';
+	}
+
+	function meterHint(row: UsageBreakdownRow): string {
+		if (row.unit) return '非 token 计量';
+		if (row.inputTokens > 0 || row.outputTokens > 0) return 'in / out tokens';
+		return '无计量';
+	}
+
+	$effect(() => {
+		if (slug) void load();
+	});
+</script>
+
+{#if loading && !usage}
+	<LoadingState />
+{:else if error && !usage}
+	<ErrorBanner message={error} onretry={load} />
+{:else if usage}
+	<PageHeader
+		title="用量报告"
+		description="按 UsageFact 分账：模型完成与外部能力（PDF→MD、ASR 等）分开汇总。缺失成本计为未知，不为 0。"
+	/>
+
+	<div class="saas-card-pad mb-6">
+		<div class="flex flex-wrap items-end gap-3">
+			<div>
+				<label class="saas-label" for="usage-from">从</label>
+				<input id="usage-from" class="saas-input" type="date" bind:value={from} />
+			</div>
+			<div>
+				<label class="saas-label" for="usage-to">到</label>
+				<input id="usage-to" class="saas-input" type="date" bind:value={to} />
+			</div>
+			<button class="saas-btn-primary py-1.5! text-sm" type="button" onclick={load} disabled={loading}>
+				{loading ? '加载中…' : '应用筛选'}
+			</button>
+			<button class="saas-btn-secondary py-1.5! text-sm" type="button" onclick={clearRange} disabled={loading}>
+				清除
+			</button>
+			{#if usage.from || usage.to}
+				<p class="saas-muted grow text-right text-xs">
+					窗口：
+					{usage.from ? fmtDateOnly(usage.from) : '—'}
+					→
+					{usage.to ? fmtDateOnly(usage.to) : '—'}
+				</p>
+			{/if}
+		</div>
+		{#if error}
+			<p class="mt-3 text-sm text-error-700">{error}</p>
+		{/if}
+	</div>
+
+	<div class="mb-6 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+		<StatCard label="运行总数" value={fmtNum(usage.totals.runCount)} />
+		<StatCard
+			label="有成本 / 无成本"
+			value={`${fmtNum(usage.totals.runsWithCost)} / ${fmtNum(usage.totals.runsWithoutCost)}`}
+			hint="无成本 = 成本未知，不是 $0"
+		/>
+		<StatCard label="成本 (USD)" value={fmtCost(usage.totals.costUsd)} hint="仅汇总已知 costUsd" />
+		<StatCard label="输入 tokens" value={fmtNum(usage.totals.inputTokens)} hint="主要来自模型完成" />
+		<StatCard label="输出 tokens" value={fmtNum(usage.totals.outputTokens)} hint="主要来自模型完成" />
+		<StatCard
+			label="分账条目"
+			value={fmtNum(usage.breakdown.reduce((n, b) => n + b.factCount, 0))}
+			hint={`${fmtNum(usage.breakdown.length)} 个分项`}
+		/>
+	</div>
+
+	<div class="saas-card overflow-hidden mb-6">
+		<div class="border-b border-surface-200 px-5 py-3">
+			<h3 class="text-sm font-semibold text-surface-800">按来源分账</h3>
+			<p class="saas-muted mt-0.5 text-xs">
+				kind × provider × model/capability。外部能力显示页数/秒等计量，不与 tokens 混排。
+			</p>
+		</div>
+		{#if usage.breakdown.length === 0}
+			<EmptyState title="暂无用量事实" description="跑过智能体后，模型与外部能力消费会出现在此。" />
+		{:else}
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>类型</th>
+							<th>供应方</th>
+							<th>模型 / 能力</th>
+							<th>次数</th>
+							<th>计量</th>
+							<th>有成本 / 未知</th>
+							<th>成本</th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each usage.breakdown as row}
+							<tr>
+								<td>
+									<span
+										class={row.kind === 'external_capability'
+											? 'saas-badge-primary'
+											: row.kind === 'model_completion'
+												? 'saas-badge-success'
+												: 'saas-badge-primary'}
+									>
+										{usageKindLabel(row.kind)}
+									</span>
+								</td>
+								<td class="font-mono text-xs">{row.provider}</td>
+								<td class="font-mono text-xs">{sourceLabel(row)}</td>
+								<td class="tabular-nums">{fmtNum(row.factCount)}</td>
+								<td class="tabular-nums">
+									<div>{meterCell(row)}</div>
+									<div class="text-[11px] text-surface-600">{meterHint(row)}</div>
+								</td>
+								<td class="tabular-nums text-surface-700">
+									{fmtNum(row.factsWithCost)} / {fmtNum(row.factsWithoutCost)}
+								</td>
+								<td class="tabular-nums font-medium">{fmtCost(row.costUsd)}</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		{/if}
+	</div>
+
+	<div class="saas-card overflow-hidden">
+		<div class="border-b border-surface-200 px-5 py-3">
+			<h3 class="text-sm font-semibold text-surface-800">按项目</h3>
+			<p class="saas-muted mt-0.5 text-xs">项目仍是权限边界；行内成本已含该项目全部 fact 类型。</p>
+		</div>
+		{#if usage.projects.length === 0}
+			<EmptyState title="暂无项目" description="创建项目并触发智能体后会出现用量。" />
+		{:else}
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>项目</th>
+							<th>运行</th>
+							<th>有成本 / 未知</th>
+							<th>in / out tokens</th>
+							<th>成本</th>
+							<th></th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each usage.projects as p}
+							<tr>
+								<td class="font-medium">{p.projectName}</td>
+								<td class="tabular-nums">{fmtNum(p.runCount)}</td>
+								<td class="tabular-nums text-surface-700">
+									{fmtNum(p.runsWithCost)} / {fmtNum(p.runsWithoutCost)}
+								</td>
+								<td class="tabular-nums text-surface-600">{fmtTokens(p.inputTokens, p.outputTokens)}</td>
+								<td class="tabular-nums">{fmtCost(p.costUsd)}</td>
+								<td class="text-right">
+									<a class="text-sm text-primary-700 hover:underline" href={`/admin/org/${slug}/projects/${p.projectId}`}>
+										查看项目
+									</a>
+								</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		{/if}
+	</div>
+{/if}

hub/package-lock.json

@@ -1,13 +1,16 @@
 {
   "name": "@paradigm/hub",
-  "version": "0.0.31",
+  "version": "0.0.34",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@paradigm/hub",
-      "version": "0.0.31",
+      "version": "0.0.34",
       "dependencies": {
+        "@alicloud/credentials": "^2.4.5",
+        "@alicloud/docmind-api20220711": "^1.4.15",
+        "@alicloud/tea-util": "^1.4.11",
         "@anthropic-ai/claude-agent-sdk": "^0.3.202",
         "@fastify/cookie": "^11.0.2",
         "@larksuiteoapi/node-sdk": "^1.70.0",
@@ -74,6 +77,175 @@
         "zod": "^3.25.76 || ^4.1.8"
       }
     },
+    "node_modules/@alicloud/credentials": {
+      "version": "2.4.5",
+      "resolved": "https://registry.npmjs.org/@alicloud/credentials/-/credentials-2.4.5.tgz",
+      "integrity": "sha512-od1ufCxOO7cP2R4EVFliOB0kGo9lUXCibyj/mzmI6yLhxeqhqsegTzVsx5p2NJJsceKJnYcmye7FWKyLJAFBkw==",
+      "license": "MIT",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.8.0",
+        "httpx": "^2.3.3",
+        "ini": "^1.3.5",
+        "kitx": "^2.0.0"
+      }
+    },
+    "node_modules/@alicloud/darabonba-array": {
+      "version": "0.1.2",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-array/-/darabonba-array-0.1.2.tgz",
+      "integrity": "sha512-ZPuQ+bJyjrd8XVVm55kl+ypk7OQoi1ZH/DiToaAEQaGvgEjrTcvQkg71//vUX/6cvbLIF5piQDvhrLb+lUEIPQ==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.7.1"
+      }
+    },
+    "node_modules/@alicloud/darabonba-encode-util": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-encode-util/-/darabonba-encode-util-0.0.2.tgz",
+      "integrity": "sha512-mlsNctkeqmR0RtgE1Rngyeadi5snLOAHBCWEtYf68d7tyKskosXDTNeZ6VCD/UfrUu4N51ItO8zlpfXiOgeg3A==",
+      "license": "ISC",
+      "dependencies": {
+        "moment": "^2.29.1"
+      }
+    },
+    "node_modules/@alicloud/darabonba-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-map/-/darabonba-map-0.0.1.tgz",
+      "integrity": "sha512-2ep+G3YDvuI+dRYVlmER1LVUQDhf9kEItmVB/bbEu1pgKzelcocCwAc79XZQjTcQGFgjDycf3vH87WLDGLFMlw==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.7.1"
+      }
+    },
+    "node_modules/@alicloud/darabonba-signature-util": {
+      "version": "0.0.4",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-signature-util/-/darabonba-signature-util-0.0.4.tgz",
+      "integrity": "sha512-I1TtwtAnzLamgqnAaOkN0IGjwkiti//0a7/auyVThdqiC/3kyafSAn6znysWOmzub4mrzac2WiqblZKFcN5NWg==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/darabonba-encode-util": "^0.0.1"
+      }
+    },
+    "node_modules/@alicloud/darabonba-signature-util/node_modules/@alicloud/darabonba-encode-util": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-encode-util/-/darabonba-encode-util-0.0.1.tgz",
+      "integrity": "sha512-Sl5vCRVAYMqwmvXpJLM9hYoCHOMsQlGxaWSGhGWulpKk/NaUBArtoO1B0yHruJf1C5uHhEJIaylYcM48icFHgw==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.7.1",
+        "moment": "^2.29.1"
+      }
+    },
+    "node_modules/@alicloud/darabonba-string": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-string/-/darabonba-string-1.0.3.tgz",
+      "integrity": "sha512-NyWwrU8cAIesWk3uHL1Q7pTDTqLkCI/0PmJXC4/4A0MFNAZ9Ouq0iFBsRqvfyUujSSM+WhYLuTfakQXiVLkTMA==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.5.1"
+      }
+    },
+    "node_modules/@alicloud/docmind-api20220711": {
+      "version": "1.4.15",
+      "resolved": "https://registry.npmjs.org/@alicloud/docmind-api20220711/-/docmind-api20220711-1.4.15.tgz",
+      "integrity": "sha512-QmjSDPV52d2B5bd/Dk3Zeofu+cJFPKYS+MphIHqlulfYsOynLgOaDqTRMGTK/RhcmVCwG14CyZ/15GBF00GRFw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@alicloud/credentials": "^2.4.2",
+        "@alicloud/openapi-core": "^1.0.0",
+        "@darabonba/typescript": "^1.0.0"
+      }
+    },
+    "node_modules/@alicloud/endpoint-util": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/@alicloud/endpoint-util/-/endpoint-util-0.0.1.tgz",
+      "integrity": "sha512-+pH7/KEXup84cHzIL6UJAaPqETvln4yXlD9JzlrqioyCSaWxbug5FUobsiI6fuUOpw5WwoB3fWAtGbFnJ1K3Yg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.5.1",
+        "kitx": "^2.0.0"
+      }
+    },
+    "node_modules/@alicloud/gateway-pop": {
+      "version": "0.0.6",
+      "resolved": "https://registry.npmjs.org/@alicloud/gateway-pop/-/gateway-pop-0.0.6.tgz",
+      "integrity": "sha512-KF4I+JvfYuLKc3fWeWYIZ7lOVJ9jRW0sQXdXidZn1DKZ978ncfGf7i0LBfONGk4OxvNb/HD3/0yYhkgZgPbKtA==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/credentials": "^2",
+        "@alicloud/darabonba-array": "^0.1.0",
+        "@alicloud/darabonba-encode-util": "^0.0.2",
+        "@alicloud/darabonba-map": "^0.0.1",
+        "@alicloud/darabonba-signature-util": "^0.0.4",
+        "@alicloud/darabonba-string": "^1.0.2",
+        "@alicloud/endpoint-util": "^0.0.1",
+        "@alicloud/gateway-spi": "^0.0.8",
+        "@alicloud/openapi-util": "^0.3.2",
+        "@alicloud/tea-typescript": "^1.7.1",
+        "@alicloud/tea-util": "^1.4.8"
+      }
+    },
+    "node_modules/@alicloud/gateway-spi": {
+      "version": "0.0.8",
+      "resolved": "https://registry.npmjs.org/@alicloud/gateway-spi/-/gateway-spi-0.0.8.tgz",
+      "integrity": "sha512-KM7fu5asjxZPmrz9sJGHJeSU+cNQNOxW+SFmgmAIrITui5hXL2LB+KNRuzWmlwPjnuA2X3/keq9h6++S9jcV5g==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/credentials": "^2",
+        "@alicloud/tea-typescript": "^1.7.1"
+      }
+    },
+    "node_modules/@alicloud/openapi-core": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@alicloud/openapi-core/-/openapi-core-1.0.8.tgz",
+      "integrity": "sha512-xs8LdgMDcEUqv13kZ4nl+Vd+Fc1mixTF0g1lm5QSrNWDaLUUD5vqpuMtvUZnKNnq9PITfUQ+8KunAvNQJpFo8g==",
+      "hasInstallScript": true,
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/credentials": "^2.4.2",
+        "@alicloud/gateway-pop": "0.0.6",
+        "@alicloud/gateway-spi": "^0.0.8",
+        "@darabonba/typescript": "^1.0.5"
+      }
+    },
+    "node_modules/@alicloud/openapi-util": {
+      "version": "0.3.3",
+      "resolved": "https://registry.npmjs.org/@alicloud/openapi-util/-/openapi-util-0.3.3.tgz",
+      "integrity": "sha512-vf0cQ/q8R2U7ZO88X5hDiu1yV3t/WexRj+YycWxRutkH/xVXfkmpRgps8lmNEk7Ar+0xnY8+daN2T+2OyB9F4A==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.7.1",
+        "@alicloud/tea-util": "^1.3.0",
+        "kitx": "^2.1.0",
+        "sm3": "^1.0.3"
+      }
+    },
+    "node_modules/@alicloud/tea-typescript": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@alicloud/tea-typescript/-/tea-typescript-1.8.0.tgz",
+      "integrity": "sha512-CWXWaquauJf0sW30mgJRVu9aaXyBth5uMBCUc+5vKTK1zlgf3hIqRUjJZbjlwHwQ5y9anwcu18r48nOZb7l2QQ==",
+      "license": "ISC",
+      "dependencies": {
+        "@types/node": "^12.0.2",
+        "httpx": "^2.2.6"
+      }
+    },
+    "node_modules/@alicloud/tea-typescript/node_modules/@types/node": {
+      "version": "12.20.55",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-12.20.55.tgz",
+      "integrity": "sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==",
+      "license": "MIT"
+    },
+    "node_modules/@alicloud/tea-util": {
+      "version": "1.4.11",
+      "resolved": "https://registry.npmjs.org/@alicloud/tea-util/-/tea-util-1.4.11.tgz",
+      "integrity": "sha512-HyPEEQ8F0WoZegiCp7sVdrdm6eBOB+GCvGl4182u69LDFktxfirGLcAx3WExUr1zFWkq2OSmBroTwKQ4w/+Yww==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.5.1",
+        "@darabonba/typescript": "^1.0.0",
+        "kitx": "^2.0.0"
+      }
+    },
     "node_modules/@anthropic-ai/claude-agent-sdk": {
       "version": "0.3.202",
       "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.3.202.tgz",
@@ -234,6 +406,24 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@darabonba/typescript": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/@darabonba/typescript/-/typescript-1.0.5.tgz",
+      "integrity": "sha512-pfxHFVM8I3h8K2o8skpDQLMmR5iAeQ2eNpP1HrKDEm/9ZPF8aKwDKPwwEszT1NnIo0Y3++E7x1YsVkVpGjA/xw==",
+      "license": "Apache License 2.0",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.5.1",
+        "http-proxy-agent": "^5.0.0",
+        "https-proxy-agent": "^5.0.1",
+        "httpx": "^2.3.2",
+        "lodash": "^4.17.21",
+        "moment": "^2.30.1",
+        "moment-timezone": "^0.5.45",
+        "socks-proxy-agent": "^6.2.1",
+        "ws": "^8.18.0",
+        "xml2js": "^0.6.2"
+      }
+    },
     "node_modules/@emnapi/core": {
       "version": "1.11.2",
       "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.2.tgz",
@@ -1396,6 +1586,15 @@
       "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
       "license": "MIT"
     },
+    "node_modules/@tootallnate/once": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@tootallnate/once/-/once-2.0.1.tgz",
+      "integrity": "sha512-HqmEUIGRJ5fSXchkVgR5F7qn48bDBzv0kWj/Kfu5e6uci4UlEeng4331LnBkWffb++Ei3FOVLxo8JJWMFBDMeQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 10"
+      }
+    },
     "node_modules/@tybys/wasm-util": {
       "version": "0.10.3",
       "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.3.tgz",
@@ -2830,6 +3029,20 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/http-proxy-agent": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-5.0.0.tgz",
+      "integrity": "sha512-n2hY8YdoRE1i7r6M0w9DIw5GgZN0G25P8zLCRQ8rjXtTU3vsNFBI/vWK/UIeE6g5MUUz6avwAPXmL6Fy9D/90w==",
+      "license": "MIT",
+      "dependencies": {
+        "@tootallnate/once": "2",
+        "agent-base": "6",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/https-proxy-agent": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz",
@@ -2843,6 +3056,25 @@
         "node": ">= 6"
       }
     },
+    "node_modules/httpx": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/httpx/-/httpx-2.3.3.tgz",
+      "integrity": "sha512-k1qv94u1b6e+XKCxVbLgYlOypVP9MPGpnN5G/vxFf6tDO4V3xpz3d6FUOY/s8NtPgaq5RBVVgSB+7IHpVxMYzw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "^20",
+        "debug": "^4.1.1"
+      }
+    },
+    "node_modules/httpx/node_modules/@types/node": {
+      "version": "20.19.43",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",
+      "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
     "node_modules/iconv-lite": {
       "version": "0.7.3",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.3.tgz",
@@ -2867,12 +3099,17 @@
       "license": "ISC",
       "peer": true
     },
+    "node_modules/ini": {
+      "version": "1.3.8",
+      "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz",
+      "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==",
+      "license": "ISC"
+    },
     "node_modules/ip-address": {
       "version": "10.2.0",
       "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
       "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">= 12"
       }
@@ -2972,6 +3209,15 @@
       "license": "BSD-2-Clause",
       "peer": true
     },
+    "node_modules/kitx": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/kitx/-/kitx-2.2.0.tgz",
+      "integrity": "sha512-tBMwe6AALTBQJb0woQDD40734NKzb0Kzi3k7wQj9ar3AbP9oqhoVrdXPh7rk2r00/glIgd0YbToIUJsnxWMiIg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "^22.5.4"
+      }
+    },
     "node_modules/light-my-request": {
       "version": "6.6.0",
       "resolved": "https://registry.npmjs.org/light-my-request/-/light-my-request-6.6.0.tgz",
@@ -3270,6 +3516,12 @@
         "url": "https://opencollective.com/parcel"
       }
     },
+    "node_modules/lodash": {
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
+      "license": "MIT"
+    },
     "node_modules/lodash.identity": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/lodash.identity/-/lodash.identity-3.0.0.tgz",
@@ -3357,6 +3609,27 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/moment": {
+      "version": "2.30.1",
+      "resolved": "https://registry.npmjs.org/moment/-/moment-2.30.1.tgz",
+      "integrity": "sha512-uEmtNhbDOrWPFS+hdjFCBfy9f2YoyzRpwcl+DqpC6taX21FzsTLQVbMV/W7PzNSX6x/bhC1zA3c2UQ5NzH6how==",
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/moment-timezone": {
+      "version": "0.5.48",
+      "resolved": "https://registry.npmjs.org/moment-timezone/-/moment-timezone-0.5.48.tgz",
+      "integrity": "sha512-f22b8LV1gbTO2ms2j2z13MuPogNoh5UzxL3nzNAYKGraILnbGc9NEE6dyiiiLv46DGRb8A4kg8UKWLjPthxBHw==",
+      "license": "MIT",
+      "dependencies": {
+        "moment": "^2.29.4"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -3976,6 +4249,15 @@
       "license": "MIT",
       "peer": true
     },
+    "node_modules/sax": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/sax/-/sax-1.6.0.tgz",
+      "integrity": "sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA==",
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": ">=11.0.0"
+      }
+    },
     "node_modules/secure-json-parse": {
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/secure-json-parse/-/secure-json-parse-4.1.0.tgz",
@@ -4193,6 +4475,50 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/sm3": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/sm3/-/sm3-1.0.3.tgz",
+      "integrity": "sha512-KyFkIfr8QBlFG3uc3NaljaXdYcsbRy1KrSfc4tsQV8jW68jAktGeOcifu530Vx/5LC+PULHT0Rv8LiI8Gw+c1g==",
+      "license": "MIT"
+    },
+    "node_modules/smart-buffer": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz",
+      "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 6.0.0",
+        "npm": ">= 3.0.0"
+      }
+    },
+    "node_modules/socks": {
+      "version": "2.8.9",
+      "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.9.tgz",
+      "integrity": "sha512-LJhUYUvItdQ0LkJTmPeaEObWXAqFyfmP85x0tch/ez9cahmhlBBLbIqDFnvBnUJGagb0JbIQrkBs1wJ+yRYpEw==",
+      "license": "MIT",
+      "dependencies": {
+        "ip-address": "^10.1.1",
+        "smart-buffer": "^4.2.0"
+      },
+      "engines": {
+        "node": ">= 10.0.0",
+        "npm": ">= 3.0.0"
+      }
+    },
+    "node_modules/socks-proxy-agent": {
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/socks-proxy-agent/-/socks-proxy-agent-6.2.1.tgz",
+      "integrity": "sha512-a6KW9G+6B3nWZ1yB8G7pJwL3ggLy1uTzKAgCb7ttblwqdz9fMGJUuTy3uFzEP48FAs9FLILlmzDlE2JJhVQaXQ==",
+      "license": "MIT",
+      "dependencies": {
+        "agent-base": "^6.0.2",
+        "debug": "^4.3.3",
+        "socks": "^2.6.2"
+      },
+      "engines": {
+        "node": ">= 10"
+      }
+    },
     "node_modules/sonic-boom": {
       "version": "4.2.1",
       "resolved": "https://registry.npmjs.org/sonic-boom/-/sonic-boom-4.2.1.tgz",
@@ -4700,6 +5026,28 @@
         }
       }
     },
+    "node_modules/xml2js": {
+      "version": "0.6.2",
+      "resolved": "https://registry.npmjs.org/xml2js/-/xml2js-0.6.2.tgz",
+      "integrity": "sha512-T4rieHaC1EXcES0Kxxj4JWgaUQHDk+qwHcYOCFHfiwKz7tOVPLq7Hjq9dM1WCMhylqMEfP7hMcOIChvotiZegA==",
+      "license": "MIT",
+      "dependencies": {
+        "sax": ">=0.6.0",
+        "xmlbuilder": "~11.0.0"
+      },
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/xmlbuilder": {
+      "version": "11.0.1",
+      "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-11.0.1.tgz",
+      "integrity": "sha512-fDlsI/kFEx7gLvbecc0/ohLG50fugQp8ryHzMTuW9vSa1GJ0XYWKnhsUx7oie3G98+r56aTQIUB4kht42R3JvA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4.0"
+      }
+    },
     "node_modules/zod": {
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",

hub/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@paradigm/hub",
-  "version": "0.0.31",
+  "version": "0.0.34",
   "private": true,
   "type": "module",
   "engines": {
     "node": ">=24"
   },
   "dependencies": {
+    "@alicloud/credentials": "^2.4.5",
+    "@alicloud/docmind-api20220711": "^1.4.15",
+    "@alicloud/tea-util": "^1.4.11",
     "@anthropic-ai/claude-agent-sdk": "^0.3.202",
     "@fastify/cookie": "^11.0.2",
     "@larksuiteoapi/node-sdk": "^1.70.0",

hub/scripts/smoke-docmind.ts

@@ -0,0 +1,89 @@
+/**
+ * Smoke test: real Aliyun docmind API call using createReadStream.
+ * Run: node --experimental-strip-types scripts/smoke-docmind.ts <pdf-path>
+ */
+import DocmindClient from "@alicloud/docmind-api20220711";
+import { RuntimeOptions } from "@alicloud/tea-util";
+import { createReadStream } from "node:fs";
+import { basename } from "node:path";
+
+const accessKeyId = process.env["ALIBABA_CLOUD_ACCESS_KEY_ID"];
+const accessKeySecret = process.env["ALIBABA_CLOUD_ACCESS_KEY_SECRET"];
+if (accessKeyId === undefined || accessKeySecret === undefined) {
+  console.error("Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET env vars.");
+  process.exit(1);
+}
+
+const pdfPath = process.argv[2] ?? "../examples/trial/prime_sieve.pdf";
+console.log(`Parsing: ${pdfPath}`);
+
+const client = new DocmindClient.default({
+  endpoint: "docmind-api.cn-hangzhou.aliyuncs.com",
+  accessKeyId,
+  accessKeySecret,
+  type: "access_key",
+  regionId: "cn-hangzhou",
+} as never);
+
+const fileStream = createReadStream(pdfPath);
+const runtime = new RuntimeOptions({});
+
+console.log("Submitting job...");
+const submitResp = await client.submitDocParserJobAdvance(
+  new DocmindClient.SubmitDocParserJobAdvanceRequest({
+    fileUrlObject: fileStream,
+    fileName: basename(pdfPath),
+    outputFormat: ["markdown"],
+    formulaEnhancement: true,
+  }),
+  runtime,
+);
+const jobId = submitResp.body?.data?.id;
+console.log("Job ID:", jobId);
+
+if (jobId === undefined) {
+  console.error("No job id:", JSON.stringify(submitResp.body));
+  process.exit(1);
+}
+
+console.log("Polling...");
+const deadline = Date.now() + 5 * 60_000;
+let status = "";
+let markdownUrl = "";
+let pageCount = 0;
+while (Date.now() < deadline) {
+  await new Promise((r) => setTimeout(r, 10_000));
+  const resp = await client.queryDocParserStatus(
+    new DocmindClient.QueryDocParserStatusRequest({ id: jobId }),
+  );
+  const data = (resp.body as { data?: { status?: string; pageCountEstimate?: number; outputFormatResult?: Array<{ outputFileUrl?: string; outputType?: string }> } }).data;
+  status = data?.status ?? "";
+  console.log(`  status: ${status}`);
+  if (status === "success") {
+    const md = data?.outputFormatResult?.find((r) => r.outputType === "markdown");
+    markdownUrl = md?.outputFileUrl ?? "";
+    pageCount = data?.pageCountEstimate ?? 0;
+    break;
+  }
+  if (status === "fail") {
+    console.error("Job failed!");
+    process.exit(1);
+  }
+}
+
+if (status !== "success" || markdownUrl === "") {
+  console.error("Failed or timed out:", status);
+  process.exit(1);
+}
+
+console.log("Downloading markdown from OSS...");
+const mdResp = await fetch(markdownUrl);
+const markdown = await mdResp.text();
+
+console.log("--- Result ---");
+console.log("Pages:", pageCount);
+console.log("Cost (USD, est):", ((pageCount > 0 ? pageCount : 1) * 0.0056).toFixed(4));
+console.log("Job ID:", jobId);
+console.log("Markdown length:", markdown.length, "chars");
+console.log("--- Markdown (first 1000 chars) ---");
+console.log(markdown.slice(0, 1000));

hub/skills/pdf-to-md/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pdf-to-md
+description: >
+  Convert PDF documents to Markdown bundles using the convert_pdf_to_md tool.
+  Handles PDFs from Feishu messages, local workspace files, and produces
+  high-quality Markdown with LaTeX formulas and extracted images.
+---
+
+# PDF to Markdown Conversion
+
+## When to use
+
+Use this skill when the user asks to convert a PDF to Markdown, extract text
+from a PDF, or turn a PDF document into an editable format.
+
+## How it works
+
+The `convert_pdf_to_md` tool (provided by the `cph_hub` MCP server) calls
+Alibaba Cloud Document Mind to parse the PDF. It:
+
+- Extracts text in reading order (handles multi-column, scanned, and
+  multi-language documents)
+- Converts mathematical formulas to **LaTeX** (`$...$` inline, `$$...$$` block)
+- Extracts tables as Markdown tables
+- Downloads embedded images into the output directory
+- Writes a single `document.md` file plus image files
+
+## Workflow
+
+### PDF from a Feishu message
+
+1. Use `feishu_read_context` to find the `file_key` of the PDF attachment.
+2. Use `feishu_download_resource` to download it into the workspace.
+3. Use `convert_pdf_to_md` with the downloaded file path and an output directory.
+
+### PDF already in the workspace
+
+1. Use `convert_pdf_to_md` directly with the file path and an output directory.
+
+## Important rules
+
+- **Always** use `convert_pdf_to_md` for PDF→Markdown. Do NOT attempt to parse
+  PDFs yourself with Read, Bash, Python, or any other method. The tool provides
+  accurate formula, table, and image extraction that manual methods cannot
+  match.
+- If `convert_pdf_to_md` fails because no capability connection is configured,
+  tell the user to ask their organization admin to configure the Aliyun
+  docmind credential in the admin web UI (组织后台 → 能力).
+- The output directory will be created if it does not exist.
+- After conversion, use `send_file` to send the generated markdown back to the
+  user if they requested it.
+
+## Output
+
+The tool returns a list of generated files:
+- `document.md` — the main markdown file
+- `*.jpg` / `*.png` — extracted images, referenced from the markdown
+
+## Cost
+
+The conversion is billed per page (0.04 CNY/page ≈ $0.0056/page for the
+enhanced formula mode). The cost is automatically recorded on the run's
+usage ledger.

hub/src/admin/routes/capabilityConnectionRoutes.ts

@@ -0,0 +1,131 @@
+/**
+ * ADR-0027: Admin routes for organization-scoped capability connections.
+ * GET    /api/org/:orgSlug/capability-connections           — list all
+ * GET    /api/org/:orgSlug/capability-connections/:capId    — read one
+ * PUT    /api/org/:orgSlug/capability-connections/:capId    — rotate/create
+ * DELETE /api/org/:orgSlug/capability-connections/:capId    — disable
+ */
+import type { PrismaClient } from "@prisma/client";
+import type { FastifyInstance } from "fastify";
+import { CapabilityConnectionService } from "../../capability/capabilityConnectionService.js";
+import { CapabilityReadinessError, type CapabilityReadinessProbe } from "../../capability/capabilityReadiness.js";
+import type { LocalSecretEnvelope } from "../../security/secretEnvelope.js";
+import { requireOrgRole, type GuardDeps } from "../auth/guards.js";
+import { handleRouteError } from "../errors.js";
+
+export interface CapabilityConnectionRouteConfig {
+  readonly prisma: PrismaClient;
+  readonly sessionSecret: string;
+  readonly secretEnvelope: LocalSecretEnvelope;
+  readonly readinessProbe?: CapabilityReadinessProbe;
+}
+
+export async function registerCapabilityConnectionRoutes(
+  app: FastifyInstance,
+  config: CapabilityConnectionRouteConfig,
+): Promise<void> {
+  const guardDeps: GuardDeps = { prisma: config.prisma, sessionSecret: config.sessionSecret };
+  const connections = new CapabilityConnectionService(
+    config.prisma,
+    config.secretEnvelope,
+    config.readinessProbe,
+  );
+
+  app.get("/api/org/:orgSlug/capability-connections", async (request, reply) => {
+    try {
+      const { orgSlug } = request.params as { orgSlug: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      return { connections: await connections.list(auth.organization.id) };
+    } catch (error) {
+      request.log.error({ requestId: request.id, operation: "capability_connection.list" }, "list failed");
+      return handleRouteError(reply, error);
+    }
+  });
+
+  app.get("/api/org/:orgSlug/capability-connections/:capabilityId", async (request, reply) => {
+    try {
+      const { orgSlug, capabilityId } = request.params as { orgSlug: string; capabilityId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      return { connection: await connections.read(auth.organization.id, capabilityId) };
+    } catch (error) {
+      request.log.error({ requestId: request.id, operation: "capability_connection.read" }, "read failed");
+      return handleRouteError(reply, error);
+    }
+  });
+
+  app.put("/api/org/:orgSlug/capability-connections/:capabilityId", async (request, reply) => {
+    try {
+      const { orgSlug, capabilityId } = request.params as { orgSlug: string; capabilityId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const body = parseBody(request.body);
+      const result = await connections.rotate({
+        organizationId: auth.organization.id,
+        capabilityId,
+        actorUserId: auth.user.id,
+        ...body,
+      });
+      request.log.info({
+        organizationId: auth.organization.id,
+        capabilityId,
+        connectionId: result.id,
+        status: result.status,
+        secretVersion: result.activeVersion,
+      }, result.created ? "Capability Connection created" : "Capability Connection rotated");
+      const { created, ...metadata } = result;
+      return reply.status(created ? 201 : 200).send(metadata);
+    } catch (error) {
+      const facts = error instanceof CapabilityReadinessError
+        ? {
+            errorCode: error.code,
+            failureCategory: error.category,
+            ...(error.upstreamStatus !== undefined ? { upstreamStatus: error.upstreamStatus } : {}),
+          }
+        : { errorCode: "capability_connection_write_failed" };
+      request.log.error({ requestId: request.id, operation: "capability_connection.rotate", ...facts }, "rotate failed");
+      return handleRouteError(reply, error);
+    }
+  });
+
+  app.delete("/api/org/:orgSlug/capability-connections/:capabilityId", async (request, reply) => {
+    try {
+      const { orgSlug, capabilityId } = request.params as { orgSlug: string; capabilityId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const result = await connections.disable({
+        organizationId: auth.organization.id,
+        capabilityId,
+        actorUserId: auth.user.id,
+      });
+      request.log.info({
+        organizationId: auth.organization.id,
+        capabilityId,
+        connectionId: result.id,
+        status: result.status,
+      }, "Capability Connection disabled");
+      return reply.send(result);
+    } catch (error) {
+      request.log.error({ requestId: request.id, operation: "capability_connection.disable" }, "disable failed");
+      return handleRouteError(reply, error);
+    }
+  });
+}
+
+function parseBody(value: unknown): { readonly accessKeyId: string; readonly accessKeySecret: string; readonly endpoint: string } {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("invalid capability credential body");
+  }
+  const body = value as Record<string, unknown>;
+  for (const name of ["accessKeyId", "accessKeySecret", "endpoint"] as const) {
+    if (typeof body[name] !== "string" || (body[name] as string).trim() === "") {
+      throw new Error(`${name} is required`);
+    }
+  }
+  return {
+    accessKeyId: body["accessKeyId"] as string,
+    accessKeySecret: body["accessKeySecret"] as string,
+    endpoint: body["endpoint"] as string,
+  };
+}

hub/src/admin/routes/orgRoutes.ts

@@ -22,6 +22,8 @@ import type { LocalSecretEnvelope } from "../../security/secretEnvelope.js";
 import type { ProviderReadinessProbe } from "../../connections/providerReadiness.js";
 import type { FeishuReadinessProbe } from "../../connections/feishuReadiness.js";
 import { registerFeishuApplicationConnectionRoutes } from "./feishuApplicationConnectionRoutes.js";
+import { registerCapabilityConnectionRoutes } from "./capabilityConnectionRoutes.js";
+import type { CapabilityReadinessProbe } from "../../capability/capabilityReadiness.js";
 
 export interface OrgRouteConfig {
   readonly prisma: PrismaClient;
@@ -30,6 +32,7 @@ export interface OrgRouteConfig {
   readonly secretEnvelope: LocalSecretEnvelope;
   readonly providerReadinessProbe?: ProviderReadinessProbe;
   readonly feishuConnectionReadinessProbe?: FeishuReadinessProbe;
+  readonly capabilityReadinessProbe?: CapabilityReadinessProbe;
 }
 
 export async function registerOrgRoutes(app: FastifyInstance, config: OrgRouteConfig): Promise<void> {
@@ -138,4 +141,12 @@ export async function registerOrgRoutes(app: FastifyInstance, config: OrgRouteCo
       ? { readinessProbe: config.feishuConnectionReadinessProbe }
       : {}),
   });
+  await registerCapabilityConnectionRoutes(app, {
+    prisma: config.prisma,
+    sessionSecret: config.sessionSecret,
+    secretEnvelope: config.secretEnvelope,
+    ...(config.capabilityReadinessProbe !== undefined
+      ? { readinessProbe: config.capabilityReadinessProbe }
+      : {}),
+  });
 }

hub/src/agent/roleTools.ts

@@ -14,6 +14,7 @@ export const CPH_HUB_MCP_TOOL_IDS = [
   "feishu_read_context",
   "feishu_download_resource",
   "request_approval",
+  "convert_pdf_to_md",
 ] as const;
 
 export type CphHubMcpToolId = (typeof CPH_HUB_MCP_TOOL_IDS)[number];
@@ -50,10 +51,12 @@ const ROLE_TOOL_TO_CPH_HUB_MCP_TOOL = new Map<string, CphHubMcpToolId>([
   ["feishu_read_context", "feishu_read_context"],
   ["feishu_download_resource", "feishu_download_resource"],
   ["request_approval", "request_approval"],
+  ["convert_pdf_to_md", "convert_pdf_to_md"],
   ["mcp__cph_hub__send_file", "send_file"],
   ["mcp__cph_hub__feishu_read_context", "feishu_read_context"],
   ["mcp__cph_hub__feishu_download_resource", "feishu_download_resource"],
   ["mcp__cph_hub__request_approval", "request_approval"],
+  ["mcp__cph_hub__convert_pdf_to_md", "convert_pdf_to_md"],
 ]);
 
 const SUPPORTED_ROLE_TOOLS = new Set([

hub/src/capability/capabilityConnectionService.ts

@@ -0,0 +1,266 @@
+/**
+ * ADR-0027: Organization-scoped capability connection service. Manages the
+ * lifecycle (rotate / read / disable) of capability credentials stored in
+ * ADR-0024 encrypted envelopes with purpose="capability".
+ *
+ * Mirrors FeishuApplicationConnectionService, but keyed by (organizationId,
+ * capabilityId) instead of 1:1 — an org may have multiple capabilities.
+ */
+import { randomUUID } from "node:crypto";
+import type { Prisma, PrismaClient } from "@prisma/client";
+import { lockActiveOrganization } from "../org/status.js";
+import { LocalSecretEnvelope } from "../security/secretEnvelope.js";
+import { probeDocmindCredential, type CapabilityReadinessProbe } from "./capabilityReadiness.js";
+import type { CapabilitySecretPayload } from "./types.js";
+
+const CAPABILITY_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const KNOWN_CAPABILITY_IDS = new Set(["pdf_to_md_bundle", "audio_video_to_text"]);
+
+export interface CapabilityCredentialInput {
+  readonly accessKeyId: string;
+  readonly accessKeySecret: string;
+  readonly endpoint: string;
+}
+
+export interface RotateCapabilityInput extends CapabilityCredentialInput {
+  readonly organizationId: string;
+  readonly capabilityId: string;
+  readonly actorUserId: string;
+}
+
+export interface CapabilityConnectionMetadata {
+  readonly id: string;
+  readonly capabilityId: string;
+  readonly status: "DRAFT" | "ACTIVE" | "DISABLED";
+  readonly activeVersion: number | null;
+  readonly keyId: string | null;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+
+export interface CapabilityConnectionWriteResult extends CapabilityConnectionMetadata {
+  readonly created: boolean;
+}
+
+export type CapabilitySecretPayloadV1 = CapabilitySecretPayload;
+
+export class CapabilityConnectionService {
+  constructor(
+    private readonly prisma: PrismaClient,
+    private readonly secrets: LocalSecretEnvelope,
+    private readonly readinessProbe: CapabilityReadinessProbe = probeDocmindCredential,
+  ) {}
+
+  async rotate(input: RotateCapabilityInput): Promise<CapabilityConnectionWriteResult> {
+    if (!CAPABILITY_ID_PATTERN.test(input.capabilityId)) {
+      throw new Error(`invalid capabilityId: ${input.capabilityId}`);
+    }
+    const payload = validateCredential(input);
+    await this.prisma.$transaction(async (tx) => {
+      await requireCapabilityAdmin(tx, input);
+    });
+    await this.readinessProbe({
+      endpoint: payload.endpoint,
+      accessKeyId: payload.accessKeyId,
+      accessKeySecret: payload.accessKeySecret,
+    });
+
+    return this.prisma.$transaction(async (tx) => {
+      await requireCapabilityAdmin(tx, input);
+      const connection = await tx.organizationCapabilityConnection.upsert({
+        where: {
+          organizationId_capabilityId: {
+            organizationId: input.organizationId,
+            capabilityId: input.capabilityId,
+          },
+        },
+        update: {},
+        create: {
+          id: randomUUID(),
+          organizationId: input.organizationId,
+          capabilityId: input.capabilityId,
+          status: "DRAFT",
+        },
+      });
+      await tx.$queryRaw`SELECT "id" FROM "OrganizationCapabilityConnection" WHERE "id" = ${connection.id} FOR UPDATE`;
+      const locked = await tx.organizationCapabilityConnection.findUniqueOrThrow({
+        where: { id: connection.id },
+        include: {
+          activeSecretVersion: true,
+          secretVersions: { orderBy: { version: "desc" }, take: 1, select: { version: true } },
+        },
+      });
+      if (locked.organizationId !== input.organizationId) {
+        throw new Error("Capability Connection scope changed during rotation");
+      }
+      const version = (locked.secretVersions[0]?.version ?? 0) + 1;
+      const secretVersionId = randomUUID();
+      const envelope = this.secrets.encryptJson(
+        {
+          purpose: "capability",
+          organizationId: input.organizationId,
+          connectionId: locked.id,
+          secretVersionId,
+        },
+        payload,
+      );
+      const now = new Date();
+      const secretVersion = await tx.capabilityCredentialVersion.create({
+        data: {
+          id: secretVersionId,
+          connectionId: locked.id,
+          version,
+          envelopeVersion: envelope.version,
+          keyId: envelope.keyId,
+          envelope: envelope as unknown as Prisma.InputJsonValue,
+          createdByUserId: input.actorUserId,
+        },
+      });
+      if (locked.activeSecretVersion !== null) {
+        await tx.capabilityCredentialVersion.update({
+          where: { id: locked.activeSecretVersion.id },
+          data: { retiredAt: now },
+        });
+      }
+      const activated = await tx.organizationCapabilityConnection.update({
+        where: { id: locked.id },
+        data: {
+          status: "ACTIVE",
+          activeSecretVersionId: secretVersion.id,
+          activatedAt: now,
+          disabledAt: null,
+        },
+      });
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          actorUserId: input.actorUserId,
+          action: version === 1 ? "capability.created" : "capability.rotated",
+          metadata: {
+            connectionId: locked.id,
+            capabilityId: input.capabilityId,
+            status: "ACTIVE",
+            secretVersion: version,
+            keyId: envelope.keyId,
+          },
+        },
+      });
+      return {
+        ...toMetadata(activated, { version, keyId: secretVersion.keyId }),
+        created: version === 1,
+      };
+    });
+  }
+
+  async list(organizationId: string): Promise<CapabilityConnectionMetadata[]> {
+    const connections = await this.prisma.organizationCapabilityConnection.findMany({
+      where: { organizationId },
+      include: { activeSecretVersion: { select: { version: true, keyId: true } } },
+      orderBy: { capabilityId: "asc" },
+    });
+    return connections.map((c) => toMetadata(c, c.activeSecretVersion));
+  }
+
+  async read(organizationId: string, capabilityId: string): Promise<CapabilityConnectionMetadata | null> {
+    const connection = await this.prisma.organizationCapabilityConnection.findFirst({
+      where: { organizationId, capabilityId },
+      include: { activeSecretVersion: { select: { version: true, keyId: true } } },
+    });
+    return connection === null ? null : toMetadata(connection, connection.activeSecretVersion);
+  }
+
+  async disable(input: {
+    readonly organizationId: string;
+    readonly capabilityId: string;
+    readonly actorUserId: string;
+  }): Promise<CapabilityConnectionMetadata> {
+    return this.prisma.$transaction(async (tx) => {
+      await requireCapabilityAdmin(tx, input);
+      const connection = await tx.organizationCapabilityConnection.findFirst({
+        where: { organizationId: input.organizationId, capabilityId: input.capabilityId },
+        select: { id: true },
+      });
+      if (connection === null) throw new Error("Capability Connection not found");
+      await tx.$queryRaw`SELECT "id" FROM "OrganizationCapabilityConnection" WHERE "id" = ${connection.id} FOR UPDATE`;
+      const locked = await tx.organizationCapabilityConnection.findUniqueOrThrow({
+        where: { id: connection.id },
+        include: { activeSecretVersion: { select: { version: true, keyId: true } } },
+      });
+      if (locked.status === "DISABLED") return toMetadata(locked, locked.activeSecretVersion);
+      const disabled = await tx.organizationCapabilityConnection.update({
+        where: { id: locked.id },
+        data: { status: "DISABLED", disabledAt: new Date() },
+      });
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          actorUserId: input.actorUserId,
+          action: "capability.disabled",
+          metadata: {
+            connectionId: locked.id,
+            capabilityId: input.capabilityId,
+            previousStatus: locked.status,
+            status: "DISABLED",
+          },
+        },
+      });
+      return toMetadata(disabled, locked.activeSecretVersion);
+    });
+  }
+}
+
+function validateCredential(input: RotateCapabilityInput): CapabilitySecretPayloadV1 {
+  if (!KNOWN_CAPABILITY_IDS.has(input.capabilityId)) {
+    throw new Error(`unsupported capabilityId: ${input.capabilityId}`);
+  }
+  const accessKeyId = nonEmpty(input.accessKeyId, "accessKeyId");
+  const accessKeySecret = nonEmpty(input.accessKeySecret, "accessKeySecret");
+  const endpoint = nonEmpty(input.endpoint, "endpoint");
+  return { schemaVersion: 1, accessKeyId, accessKeySecret, endpoint };
+}
+
+function toMetadata(
+  connection: {
+    readonly id: string;
+    readonly capabilityId: string;
+    readonly status: string;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+  },
+  secret: { readonly version: number; readonly keyId: string } | null,
+): CapabilityConnectionMetadata {
+  return {
+    id: connection.id,
+    capabilityId: connection.capabilityId,
+    status: connection.status as CapabilityConnectionMetadata["status"],
+    activeVersion: secret?.version ?? null,
+    keyId: secret?.keyId ?? null,
+    createdAt: connection.createdAt,
+    updatedAt: connection.updatedAt,
+  };
+}
+
+async function requireCapabilityAdmin(
+  tx: Prisma.TransactionClient,
+  input: { readonly organizationId: string; readonly actorUserId: string },
+): Promise<void> {
+  await lockActiveOrganization(tx, input.organizationId);
+  const membership = await tx.organizationMembership.findFirst({
+    where: {
+      organizationId: input.organizationId,
+      userId: input.actorUserId,
+      role: { in: ["OWNER", "ADMIN"] },
+      revokedAt: null,
+    },
+    select: { id: true },
+  });
+  if (membership === null) {
+    throw new Error("only Organization OWNER or ADMIN may manage capability connections");
+  }
+}
+
+function nonEmpty(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (trimmed === "") throw new Error(`${label} must not be empty`);
+  return trimmed;
+}

hub/src/capability/capabilityConnections.ts

@@ -63,8 +63,8 @@ export async function resolveCapabilityCredential(
     organizationId: connection.organizationId,
     capabilityId: connection.capabilityId,
     schemaVersion: 1,
-    baseUrl: payload.baseUrl,
+    accessKeyId: payload.accessKeyId,
-    apiToken: payload.apiToken,
+    accessKeySecret: payload.accessKeySecret,
-    projectId: payload.projectId,
+    endpoint: payload.endpoint,
   };
 }

hub/src/capability/capabilityReadiness.ts

@@ -0,0 +1,69 @@
+/**
+ * ADR-0027: Capability readiness probe. Validates the Alibaba Cloud docmind
+ * credential by calling QueryDocParserStatus with a dummy id — a 400 (bad
+ * request) means the credential is valid (the API accepted auth but rejected
+ * the id); a 401/403 means the credential is bad.
+ */
+import { classifyNetworkFailure, type NetworkFailureCategory } from "../connections/networkFailure.js";
+
+export interface CapabilityReadinessInput {
+  readonly endpoint: string;
+  readonly accessKeyId: string;
+  readonly accessKeySecret: string;
+}
+
+export type CapabilityReadinessProbe = (input: CapabilityReadinessInput) => Promise<void>;
+
+export class CapabilityReadinessError extends Error {
+  constructor(
+    readonly code: "capability_readiness_unsupported" | "capability_readiness_unreachable" | "capability_readiness_rejected",
+    message: string,
+    readonly category: NetworkFailureCategory | "configuration" | "http",
+    readonly upstreamStatus?: number,
+  ) {
+    super(message);
+    this.name = "CapabilityReadinessError";
+  }
+}
+
+/**
+ * Probe the Alibaba Cloud docmind credential. We call QueryDocParserStatus
+ * with a dummy id. The API will return:
+ *   - 400 (InvalidParameter) → credential valid, just a bad id → probe passes
+ *   - 401/403 (InvalidAccessKey/Forbidden) → credential invalid → probe fails
+ *   - network error → unreachable
+ */
+export const probeDocmindCredential: CapabilityReadinessProbe = async (input) => {
+  const url = `https://${input.endpoint}/?Action=QueryDocParserStatus&Id=probe-test&Version=2022-07-11`;
+  const authHeader = makeBasicAuth(input.accessKeyId, input.accessKeySecret);
+
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      headers: { authorization: authHeader, accept: "application/json" },
+      redirect: "manual",
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch (error) {
+    throw new CapabilityReadinessError(
+      "capability_readiness_unreachable",
+      "docmind credential readiness check could not reach the API",
+      classifyNetworkFailure(error),
+    );
+  }
+  await response.body?.cancel();
+  if (response.status === 401 || response.status === 403) {
+    throw new CapabilityReadinessError(
+      "capability_readiness_rejected",
+      `docmind credential rejected: status ${response.status}`,
+      "http",
+      response.status,
+    );
+  }
+};
+
+function makeBasicAuth(accessKeyId: string, accessKeySecret: string): string {
+  const credentials = Buffer.from(`${accessKeyId}:${accessKeySecret}`).toString("base64");
+  return `Basic ${credentials}`;
+}

hub/src/capability/docmindClient.ts

@@ -0,0 +1,231 @@
+/**
+ * ADR-0027: Alibaba Cloud Document Mind (docmind) client.
+ *
+ * Uses the official @alicloud/docmind-api20220711 SDK to call the document
+ * parsing (large model version) API. The API is asynchronous:
+ *   1. SubmitDocParserJobAdvance — upload local file as a stream, get job id
+ *   2. QueryDocParserStatus — poll until data.status === "success";
+ *      the markdown output URL is returned in outputFormatResult
+ *   3. Download markdown from OSS, extract and download referenced images
+ *
+ * Pricing (2025-07, aliyun docmind):
+ *   - 图文文档基础链路: 0.02元/页
+ *   - 图文文档增强链路 (含公式 LaTeX): 0.04元/页
+ *   - 视频: 0.002元/秒
+ *   - 音频: 0.00035元/秒
+ */
+import $DocmindClient, {
+  SubmitDocParserJobAdvanceRequest,
+  QueryDocParserStatusRequest,
+} from "@alicloud/docmind-api20220711";
+import { RuntimeOptions } from "@alicloud/tea-util";
+import { createReadStream } from "node:fs";
+import { basename } from "node:path";
+import type { CapabilitySecretPayload } from "./types.js";
+
+/** A single extracted image downloaded from the markdown's OSS image URLs. */
+export interface DocmindExtractedImage {
+  readonly filename: string;
+  readonly data: Uint8Array;
+}
+
+/** The structured result of parsing one document. */
+export interface DocmindParseResult {
+  readonly markdown: string;
+  readonly images: readonly DocmindExtractedImage[];
+  readonly pageCount: number;
+  readonly costUsd: number | null;
+  readonly requestId: string | null;
+}
+
+export interface DocmindParseOptions {
+  readonly inputFilePath: string;
+}
+
+export interface CapabilityProviderClient {
+  parse(credential: CapabilitySecretPayload, options: DocmindParseOptions): Promise<DocmindParseResult>;
+}
+
+export class DocmindClientError extends Error {
+  constructor(
+    message: string,
+    readonly code: "docmind_unreachable" | "docmind_rejected" | "docmind_invalid_response" | "docmind_no_output" | "docmind_timeout",
+    readonly upstreamStatus?: number,
+  ) {
+    super(message);
+    this.name = "DocmindClientError";
+  }
+}
+
+/** Cost per page in USD (0.04 CNY/page ≈ 0.0056 USD). */
+const COST_PER_PAGE_USD = 0.0056;
+const POLL_INTERVAL_MS = 10_000;
+const POLL_TIMEOUT_MS = 5 * 60_000;
+
+type DocmindConfig = ConstructorParameters<typeof $DocmindClient.default>[0];
+
+export class AliyunDocmindClient implements CapabilityProviderClient {
+  async parse(credential: CapabilitySecretPayload, options: DocmindParseOptions): Promise<DocmindParseResult> {
+    const config: DocmindConfig = {
+      endpoint: credential.endpoint,
+      accessKeyId: credential.accessKeyId,
+      accessKeySecret: credential.accessKeySecret,
+      type: "access_key",
+      regionId: "cn-hangzhou",
+    } as DocmindConfig;
+    const client = new $DocmindClient.default(config);
+
+    // 1. Submit job with local file as a ReadStream (not a Buffer — the SDK
+    //    serializes Buffers as JSON {type:"Buffer",data:[...]} which the API
+    //    can't read; a Stream is uploaded as multipart form data).
+    const fileName = basename(options.inputFilePath);
+    const fileStream = createReadStream(options.inputFilePath);
+    const advanceRequest = new SubmitDocParserJobAdvanceRequest({
+      fileUrlObject: fileStream,
+      fileName,
+      outputFormat: ["markdown"],
+      formulaEnhancement: true,
+    });
+    const runtime = new RuntimeOptions({});
+    let submitResponse;
+    try {
+      submitResponse = await client.submitDocParserJobAdvance(advanceRequest, runtime);
+    } catch (e) {
+      throw new DocmindClientError(
+        e instanceof Error ? e.message : String(e),
+        "docmind_unreachable",
+      );
+    }
+    const jobId = submitResponse.body?.data?.id;
+    if (jobId === undefined || jobId === null || jobId === "") {
+      throw new DocmindClientError("docmind submit returned no job id", "docmind_invalid_response");
+    }
+
+    // 2. Poll QueryDocParserStatus until data.status === "success" or "fail".
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    let status = "";
+    let markdownUrl: string | null = null;
+    let pageCount = 0;
+    while (Date.now() < deadline) {
+      await sleep(POLL_INTERVAL_MS);
+      const statusReq = new QueryDocParserStatusRequest({ id: jobId });
+      const statusResponse = await client.queryDocParserStatus(statusReq);
+      const body = statusResponse.body as {
+        data?: {
+          status?: string;
+          pageCountEstimate?: number;
+          outputFormatResult?: Array<{ outputFileUrl?: string; outputType?: string }>;
+        };
+      };
+      status = body.data?.status ?? "";
+      if (status === "success") {
+        const mdResult = body.data?.outputFormatResult?.find((r) => r.outputType === "markdown");
+        markdownUrl = mdResult?.outputFileUrl ?? null;
+        pageCount = body.data?.pageCountEstimate ?? 0;
+        break;
+      }
+      if (status === "fail") {
+        throw new DocmindClientError(`docmind job ${jobId} failed`, "docmind_rejected");
+      }
+    }
+    if (status !== "success") {
+      throw new DocmindClientError(`docmind job ${jobId} timed out (status: ${status})`, "docmind_timeout");
+    }
+    if (markdownUrl === null) {
+      throw new DocmindClientError("docmind returned no markdown output URL", "docmind_no_output");
+    }
+
+    // 3. Download the markdown file from OSS.
+    let markdown: string;
+    try {
+      const mdResp = await fetch(markdownUrl);
+      if (!mdResp.ok) {
+        throw new DocmindClientError(`failed to download markdown: HTTP ${mdResp.status}`, "docmind_unreachable");
+      }
+      markdown = await mdResp.text();
+    } catch (e) {
+      if (e instanceof DocmindClientError) throw e;
+      throw new DocmindClientError(
+        e instanceof Error ? e.message : String(e),
+        "docmind_unreachable",
+      );
+    }
+    if (markdown === "") {
+      throw new DocmindClientError("docmind returned empty markdown", "docmind_no_output");
+    }
+
+    // 4. Download images referenced in the markdown (OSS URLs).
+    //    Markdown contains ![filename](http://...oss.../image.png?...) entries.
+    //    We rewrite them to local relative paths and download the images.
+    const images: DocmindExtractedImage[] = [];
+    const imageRefRegex = /!\[([^\]]*)\]\((https?:\/\/[^)]+)\)/g;
+    const localMarkdown = markdown.replace(imageRefRegex, (match, altText: string, url: string) => {
+      const idx = images.findIndex((img) => img.filename === extractFilename(altText, url, images.length));
+      if (idx >= 0) {
+        const img = images[idx]!;
+        return `![${altText}](${img.filename})`;
+      }
+      return match;
+    });
+
+    // Collect all image URLs first, then download.
+    const imageUrls: Array<{ url: string; altText: string }> = [];
+    let match: RegExpExecArray | null;
+    const collectRegex = /!\[([^\]]*)\]\((https?:\/\/[^)]+)\)/g;
+    while ((match = collectRegex.exec(markdown)) !== null) {
+      imageUrls.push({ url: match[2]!, altText: match[1]! });
+    }
+
+    for (let i = 0; i < imageUrls.length; i++) {
+      const { url, altText } = imageUrls[i]!;
+      const filename = extractFilename(altText, url, i);
+      try {
+        const imgResp = await fetch(url);
+        if (!imgResp.ok) continue;
+        const data = new Uint8Array(await imgResp.arrayBuffer());
+        images.push({ filename, data });
+      } catch {
+        // Best-effort: skip images that fail to download.
+      }
+    }
+
+    // Rewrite markdown with local image paths.
+    let finalMarkdown = markdown;
+    let imageIdx = 0;
+    finalMarkdown = finalMarkdown.replace(imageRefRegex, (match, altText: string, _url: string) => {
+      if (imageIdx < images.length) {
+        const img = images[imageIdx]!;
+        imageIdx++;
+        return `![${altText}](${img.filename})`;
+      }
+      return match;
+    });
+
+    if (pageCount === 0) {
+      pageCount = Math.max(1, images.length);
+    }
+    const costUsd = (pageCount > 0 ? pageCount : 1) * COST_PER_PAGE_USD;
+
+    return { markdown: finalMarkdown, images, pageCount, costUsd, requestId: jobId };
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/** Derive a clean filename from the alt text or URL. */
+function extractFilename(altText: string, url: string, index: number): string {
+  // Try alt text first (docmind often puts the original filename).
+  if (altText !== "" && altText.length < 100) {
+    const cleaned = altText.replace(/[^a-zA-Z0-9._-]/g, "_");
+    if (cleaned.length > 0) return cleaned;
+  }
+  // Fall back to URL path.
+  const urlPath = new URL(url).pathname;
+  const base = basename(urlPath);
+  if (base !== "" && base !== "/") return base;
+  return `image_${index + 1}.png`;
+}

hub/src/capability/mineruClient.ts

@@ -1,66 +0,0 @@
-/**
- * ADR-0027: MinerU client interface. Isolates the real HTTP client so the
- * adapter is testable without network access. The real implementation (filling
- * in actual MinerU API calls) is deferred until credentials and pricing are
- * confirmed; the interface and a mock implementation land now so the adapter
- * wiring, UsageFact attribution, and workspace containment are provable.
- *
- * MinerU cloud API shape (from mineru.net docs / GitHub README):
- *   - REST API, async task endpoint POST /tasks (v3.0+) + sync POST /file_parse
- *   - Auth: Bearer token (apiToken)
- *   - Output: Markdown + extracted images, returned as a zip or structured JSON
- *   - Cost: reported per-page (pricing requires account confirmation)
- *
- * The interface models the synchronous parse path for simplicity; the real
- * client may poll the async endpoint internally and is free to do so behind
- * this signature.
- */
-import type { CapabilitySecretPayload } from "./types.js";
-
-/** A single extracted image from the parsed document. */
-export interface MineruExtractedImage {
-  /** Suggested relative filename (e.g. "page_1_fig_0.jpg"). */
-  readonly filename: string;
-  /** Raw image bytes. */
-  readonly data: Uint8Array;
-}
-
-/** The structured result of parsing one document. */
-export interface MineruParseResult {
-  /** Markdown text with image references (relative to output dir). */
-  readonly markdown: string;
-  /** Images extracted from the document, to be written alongside the md. */
-  readonly images: readonly MineruExtractedImage[];
-  /** Number of pages processed (for UsageFact quantity, unit "pages"). */
-  readonly pageCount: number;
-  /** USD cost if the API reported it; null if unknown (ADR-0022). */
-  readonly costUsd: number | null;
-  /** External task/request id for the UsageFact correlationId. */
-  readonly requestId: string | null;
-}
-
-/** Options passed to the client. */
-export interface MineruParseOptions {
-  /** Absolute path to the input PDF on the Hub's filesystem. */
-  readonly inputFilePath: string;
-}
-
-/**
- * Client interface for the MinerU document parsing service. The real
- * implementation makes authenticated HTTP calls; tests inject a mock.
- */
-export interface MineruClient {
-  parse(credential: CapabilitySecretPayload, options: MineruParseOptions): Promise<MineruParseResult>;
-}
-
-/** Errors raised by the MinerU client. */
-export class MineruClientError extends Error {
-  constructor(
-    message: string,
-    readonly code: "mineru_unreachable" | "mineru_rejected" | "mineru_invalid_response" | "mineru_no_output",
-    readonly upstreamStatus?: number,
-  ) {
-    super(message);
-    this.name = "MineruClientError";
-  }
-}

hub/src/capability/pdfToMdBundle.ts

@@ -20,7 +20,7 @@ import { join, resolve, relative, isAbsolute } from "node:path";
 import type { PrismaClient } from "@prisma/client";
 import { LocalSecretEnvelope } from "../security/secretEnvelope.js";
 import { resolveCapabilityCredential } from "./capabilityConnections.js";
-import { MineruClientError, type MineruClient } from "./mineruClient.js";
+import { DocmindClientError, type CapabilityProviderClient } from "./docmindClient.js";
 import {
   CAPABILITIES,
   type CapabilityAdapter,
@@ -30,7 +30,7 @@ import {
 } from "./types.js";
 
 const CAPABILITY_ID = "pdf_to_md_bundle" as const;
-const PROVIDER_ID = "mineru";
+const PROVIDER_ID = "aliyun_docmind";
 
 /** Thrown when a requested path escapes the workspace root (ADR-0018). */
 export class CapabilityPathEscape extends Error {
@@ -59,11 +59,11 @@ function confineToWorkspace(requestedPath: string, workspaceDir: string): string
 
 export interface PdfToMdBundleDeps {
   readonly secrets: LocalSecretEnvelope;
-  readonly client: MineruClient;
+  readonly client: CapabilityProviderClient;
   readonly prisma: PrismaClient;
 }
 
-/** Build the pdf_to_md_bundle adapter. The MineruClient is injectable for testing. */
+/** Build the pdf_to_md_bundle adapter. The client is injectable for testing. */
 export function createPdfToMdBundleAdapter(deps: PdfToMdBundleDeps): CapabilityAdapter {
   return {
     capabilityId: CAPABILITY_ID,
@@ -85,14 +85,14 @@ export function createPdfToMdBundleAdapter(deps: PdfToMdBundleDeps): CapabilityA
       try {
         result = await deps.client.parse(credential, { inputFilePath: absoluteInput });
       } catch (e) {
-        if (e instanceof MineruClientError) throw e;
+        if (e instanceof DocmindClientError) throw e;
-        throw new MineruClientError(
+        throw new DocmindClientError(
           e instanceof Error ? e.message : String(e),
-          "mineru_unreachable",
+          "docmind_unreachable",
         );
       }
       if (result.markdown === "") {
-        throw new MineruClientError("MinerU returned empty markdown", "mineru_no_output");
+        throw new DocmindClientError("docmind returned empty markdown", "docmind_no_output");
       }
 
       // 4. Write outputs into the workspace.

hub/src/capability/types.ts

@@ -80,12 +80,13 @@ export interface CapabilityAdapter {
   invoke(input: CapabilityInvocationInput): Promise<CapabilityInvocationResult>;
 }
 
-/** Decrypted capability credential (CapabilitySecretPayloadV1, ADR-0027). */
+/** Decrypted capability credential (CapabilitySecretPayloadV1, ADR-0027).
+ * Alibaba Cloud Document Mind (docmind) uses AccessKey ID + Secret + endpoint. */
 export interface CapabilitySecretPayload {
   readonly schemaVersion: 1;
-  readonly baseUrl: string;
+  readonly accessKeyId: string;
-  readonly apiToken: string;
+  readonly accessKeySecret: string;
-  readonly projectId: string | null;
+  readonly endpoint: string;
 }
 
 /** Thrown when an org has no ACTIVE capability connection (fail-closed, ADR-0024). */

hub/src/feishu/fileDeliveryTool.ts

@@ -7,11 +7,16 @@ import { readFeishuContext } from "./read.js";
 import type { ApprovalManager } from "./approval.js";
 import { CPH_HUB_MCP_TOOL_IDS, type CphHubMcpToolId } from "../agent/roleTools.js";
 import { WorkspaceFileBoundaryError } from "../security/workspaceFiles.js";
+import type { PrismaClient } from "@prisma/client";
+import type { LocalSecretEnvelope } from "../security/secretEnvelope.js";
+import { createPdfToMdBundleAdapter } from "../capability/pdfToMdBundle.js";
+import { AliyunDocmindClient } from "../capability/docmindClient.js";
 
 export interface FileDeliveryToolOptions {
   readonly rt: FeishuRuntime;
   readonly chatId: string;
   readonly projectId: string;
+  readonly organizationId: string;
   readonly runId: string;
   readonly workspaceRoot?: string | undefined;
   readonly workspaceDir: string;
@@ -20,6 +25,8 @@ export interface FileDeliveryToolOptions {
   readonly approvalManager: ApprovalManager;
   readonly onDelivered?: (path: string) => void;
   readonly tools?: readonly CphHubMcpToolId[] | undefined;
+  readonly prisma: PrismaClient;
+  readonly secretEnvelope: LocalSecretEnvelope;
 }
 
 export function createFileDeliveryMcpServer(options: FileDeliveryToolOptions): McpSdkServerConfigWithInstance {
@@ -230,6 +237,51 @@ export function createFileDeliveryMcpServer(options: FileDeliveryToolOptions): M
     );
   }
 
+  if (enabledTools.has("convert_pdf_to_md")) {
+    const adapter = createPdfToMdBundleAdapter({
+      secrets: options.secretEnvelope,
+      client: new AliyunDocmindClient(),
+      prisma: options.prisma,
+    });
+    tools.push(
+      tool(
+        "convert_pdf_to_md",
+        "Convert a PDF file in the workspace to a Markdown bundle (markdown + extracted images) using Alibaba Cloud Document Mind. The PDF must already be in the workspace (use feishu_download_resource first if it came from Feishu). Returns the path to the generated markdown file and the list of extracted image paths. Mathematical formulas are converted to LaTeX.",
+        {
+          input_path: z.string().describe("Relative path to the input PDF within the workspace."),
+          output_dir: z.string().describe("Relative directory within the workspace to write the markdown and images into. Will be created if it does not exist."),
+        },
+        async (args) => {
+          try {
+            const result = await adapter.invoke({
+              runId: options.runId,
+              organizationId: options.organizationId,
+              projectId: options.projectId,
+              workspaceDir: options.workspaceDir,
+              inputPath: args.input_path,
+              outputDir: args.output_dir,
+              prisma: options.prisma,
+            });
+            const lines = [`Converted PDF to markdown. ${result.artifacts.length} files written:`];
+            for (const artifact of result.artifacts) {
+              lines.push(`  - ${artifact.path} (${artifact.kind})`);
+            }
+            lines.push(`Pages: ${result.consumption.quantity}, Cost: $${(result.consumption.costUsd ?? 0).toFixed(4)}`);
+            return {
+              content: [{ type: "text", text: lines.join("\n") }],
+            };
+          } catch (e) {
+            return {
+              isError: true,
+              content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+            };
+          }
+        },
+        { alwaysLoad: true },
+      ),
+    );
+  }
+
   const instructions = mcpInstructions(enabledTools);
   return createSdkMcpServer({
     name: "cph_hub",
@@ -260,5 +312,12 @@ function mcpInstructions(enabledTools: ReadonlySet<CphHubMcpToolId>): string {
   if (enabledTools.has("request_approval")) {
     instructions.push("Use request_approval when explicit human approval or confirmation is required before continuing.");
   }
+  if (enabledTools.has("convert_pdf_to_md")) {
+    instructions.push(
+      "Use convert_pdf_to_md when the user asks to convert a PDF to Markdown.",
+      "If the PDF came from a Feishu message, first use feishu_download_resource to save it to the workspace, then call convert_pdf_to_md.",
+      "Do NOT attempt to parse PDFs yourself with Read or Bash — always use convert_pdf_to_md for accurate text, formula, and image extraction.",
+    );
+  }
   return instructions.join(" ");
 }

hub/src/feishu/trigger.ts

@@ -14,6 +14,7 @@ import { join } from "node:path";
 import type { Prisma, PrismaClient } from "@prisma/client";
 import { z } from "zod";
 import type { FastifyBaseLogger } from "fastify";
+import type { LocalSecretEnvelope } from "../security/secretEnvelope.js";
 import {
   sendText,
   sendTextMessage,
@@ -93,6 +94,7 @@ interface TriggerDeps {
   readonly prisma: PrismaClient;
   readonly settings: RuntimeSettings;
   readonly logger: FastifyBaseLogger;
+  readonly secretEnvelope: LocalSecretEnvelope;
   readonly runAgent?: (req: RunRequest) => Promise<RunResult>;
   readonly authorizer?: PermissionAuthorizer | undefined;
   readonly messageBatcherOptions?: MessageBatcherOptions | undefined;
@@ -486,6 +488,7 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
     // Streaming agent card: single interactive card through the full run
     // lifecycle (thinking → tool calls → streaming text → complete).
     // Shows tool-use trace panel + reasoning panel + answer text.
+    const deliveredFiles: string[] = [];
     const card = new StreamingAgentCard({
       runId: run.id,
       rt,
@@ -494,11 +497,11 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       patchIntervalMs: undefined,
       maxMessageLength: undefined,
     });
-    const deliveredFiles: string[] = [];
     const fileDeliveryMcpServer = createFileDeliveryMcpServer({
       rt,
       chatId,
       projectId,
+      organizationId: siloOrganizationId,
       runId: run.id,
       workspaceRoot: projectWorkspaceRoot,
       workspaceDir: project.workspaceDir,
@@ -506,6 +509,8 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
       sendOptions,
       approvalManager,
       tools: cphHubMcpToolsForRole(roleTools),
+      prisma: deps.prisma,
+      secretEnvelope: deps.secretEnvelope,
       onDelivered: (path) => {
         deliveredFiles.push(path);
       },

hub/src/hub.ts

@@ -162,6 +162,7 @@ export async function startHub(): Promise<void> {
       prisma,
       settings: runtimeSettings,
       logger: app.log,
+      secretEnvelope,
       projectWorkspaceRoot,
       publicBaseUrl,
       siloOrganizationId: siloOrganization.id,

hub/src/org/usage.ts

@@ -9,13 +9,14 @@
  * external-capability consumption (PDF→MD, ASR, …) is attributed correctly,
  * not just the main model loop. A run with no cost-bearing fact is
  * `runsWithoutCost` — ADR-0022: missing cost ≠ zero.
+ *
+ * Breakdown buckets keep kind / provider / model / capability / unit, so the
+ * admin UI can separate model tokens from non-token external meters instead of
+ * collapsing everything into a single input/output token total.
  */
 import type { Prisma, PrismaClient } from "@prisma/client";
 
-export interface ProjectUsageRow {
+export interface UsageTotals {
-  readonly projectId: string;
-  readonly projectName: string;
-  readonly folderId: string | null;
   readonly runCount: number;
   readonly runsWithCost: number;
   readonly runsWithoutCost: number;
@@ -24,21 +25,50 @@ export interface ProjectUsageRow {
   readonly costUsd: number | null;
 }
 
+export interface ProjectUsageRow extends UsageTotals {
+  readonly projectId: string;
+  readonly projectName: string;
+  readonly folderId: string | null;
+}
+
+/** One ledger slice: kind + provider + model + capability + unit. */
+export interface UsageBreakdownRow {
+  readonly kind: string;
+  readonly provider: string;
+  readonly model: string | null;
+  readonly capabilityId: string | null;
+  readonly unit: string | null;
+  readonly factCount: number;
+  readonly factsWithCost: number;
+  readonly factsWithoutCost: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  /** Sum of quantity when unit is non-null; null when this bucket is token-only. */
+  readonly quantity: number | null;
+  readonly costUsd: number | null;
+}
+
 export interface UsageReport {
   readonly from: string | null;
   readonly to: string | null;
   readonly projects: readonly ProjectUsageRow[];
-  readonly totals: {
+  readonly totals: UsageTotals;
-    readonly runCount: number;
+  readonly breakdown: readonly UsageBreakdownRow[];
-    readonly runsWithCost: number;
+}
-    readonly runsWithoutCost: number;
+
-    readonly inputTokens: number;
+export interface ProjectUsageReport extends ProjectUsageRow {
-    readonly outputTokens: number;
+  readonly from: string | null;
-    readonly costUsd: number | null;
+  readonly to: string | null;
-  };
+  readonly breakdown: readonly UsageBreakdownRow[];
 }
 
 type FactRow = {
+  readonly kind: string;
+  readonly provider: string;
+  readonly model: string | null;
+  readonly capabilityId: string | null;
+  readonly unit: string | null;
+  readonly quantity: unknown;
   readonly inputTokens: number | null;
   readonly outputTokens: number | null;
   readonly costUsd: unknown;
@@ -49,26 +79,91 @@ type RunWithFacts = {
   readonly usageFacts: readonly FactRow[];
 };
 
-/** A run is "recorded with cost" if any of its facts carries a known costUsd. */
+type MutableTotals = {
-function runHasRecordedCost(facts: readonly FactRow[]): boolean {
+  runCount: number;
-  return facts.some((f) => f.costUsd !== null && f.costUsd !== undefined);
+  runsWithCost: number;
-}
+  runsWithoutCost: number;
+  inputTokens: number;
+  outputTokens: number;
+  costUsd: number | null;
+};
+
+type MutableBreakdown = {
+  kind: string;
+  provider: string;
+  model: string | null;
+  capabilityId: string | null;
+  unit: string | null;
+  factCount: number;
+  factsWithCost: number;
+  factsWithoutCost: number;
+  inputTokens: number;
+  outputTokens: number;
+  quantity: number | null;
+  costUsd: number | null;
+};
+
+type MutableProjectRow = MutableTotals & {
+  readonly projectId: string;
+  readonly projectName: string;
+  readonly folderId: string | null;
+};
+
+const FACT_SELECT = {
+  kind: true,
+  provider: true,
+  model: true,
+  capabilityId: true,
+  unit: true,
+  quantity: true,
+  inputTokens: true,
+  outputTokens: true,
+  costUsd: true,
+} as const;
 
-/** Decimal→number for Prisma Decimal; null/undefined → null. */
 function factCostUsdToNumber(value: unknown): number | null {
   if (value === null || value === undefined) return null;
   const n = typeof value === "number" ? value : Number(value);
   return Number.isFinite(n) ? n : null;
 }
 
-interface RunRollup {
+function factQuantityToNumber(value: unknown): number | null {
+  if (value === null || value === undefined) return null;
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function breakdownKey(f: FactRow): string {
+  return [
+    f.kind,
+    f.provider,
+    f.model ?? "",
+    f.capabilityId ?? "",
+    f.unit ?? "",
+  ].join("\u0000");
+}
+
+function emptyMutableTotals(): MutableTotals {
+  return {
+    runCount: 0,
+    runsWithCost: 0,
+    runsWithoutCost: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    costUsd: null,
+  };
+}
+
+function addCost(existing: number | null, add: number): number {
+  return (existing ?? 0) + add;
+}
+
+function rollupRunTokensAndCost(facts: readonly FactRow[]): {
   readonly hasCost: boolean;
   readonly inputTokens: number;
   readonly outputTokens: number;
   readonly costUsd: number | null;
-}
+} {
-
-function rollupRun(facts: readonly FactRow[]): RunRollup {
   let inputTokens = 0;
   let outputTokens = 0;
   let costUsd: number | null = null;
@@ -79,12 +174,118 @@ function rollupRun(facts: readonly FactRow[]): RunRollup {
     const c = factCostUsdToNumber(f.costUsd);
     if (c !== null) {
       hasCost = true;
-      costUsd = (costUsd ?? 0) + c;
+      costUsd = addCost(costUsd, c);
     }
   }
   return { hasCost, inputTokens, outputTokens, costUsd };
 }
 
+function accumulateBreakdown(
+  buckets: Map<string, MutableBreakdown>,
+  facts: readonly FactRow[],
+): void {
+  for (const f of facts) {
+    const key = breakdownKey(f);
+    let bucket = buckets.get(key);
+    if (bucket === undefined) {
+      bucket = {
+        kind: f.kind,
+        provider: f.provider,
+        model: f.model,
+        capabilityId: f.capabilityId,
+        unit: f.unit,
+        factCount: 0,
+        factsWithCost: 0,
+        factsWithoutCost: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        quantity: null,
+        costUsd: null,
+      };
+      buckets.set(key, bucket);
+    }
+    bucket.factCount += 1;
+    bucket.inputTokens += f.inputTokens ?? 0;
+    bucket.outputTokens += f.outputTokens ?? 0;
+    const qty = factQuantityToNumber(f.quantity);
+    if (qty !== null) {
+      bucket.quantity = (bucket.quantity ?? 0) + qty;
+    }
+    const c = factCostUsdToNumber(f.costUsd);
+    if (c !== null) {
+      bucket.factsWithCost += 1;
+      bucket.costUsd = addCost(bucket.costUsd, c);
+    } else {
+      bucket.factsWithoutCost += 1;
+    }
+  }
+}
+
+function freezeBreakdown(buckets: Map<string, MutableBreakdown>): UsageBreakdownRow[] {
+  return [...buckets.values()]
+    .map((b) => ({
+      kind: b.kind,
+      provider: b.provider,
+      model: b.model,
+      capabilityId: b.capabilityId,
+      unit: b.unit,
+      factCount: b.factCount,
+      factsWithCost: b.factsWithCost,
+      factsWithoutCost: b.factsWithoutCost,
+      inputTokens: b.inputTokens,
+      outputTokens: b.outputTokens,
+      quantity: b.quantity,
+      costUsd: b.costUsd,
+    }))
+    .sort((a, b) => {
+      const kindCmp = a.kind.localeCompare(b.kind);
+      if (kindCmp !== 0) return kindCmp;
+      const provCmp = a.provider.localeCompare(b.provider);
+      if (provCmp !== 0) return provCmp;
+      const capA = a.capabilityId ?? "";
+      const capB = b.capabilityId ?? "";
+      const capCmp = capA.localeCompare(capB);
+      if (capCmp !== 0) return capCmp;
+      const modelA = a.model ?? "";
+      const modelB = b.model ?? "";
+      return modelA.localeCompare(modelB);
+    });
+}
+
+function freezeTotals(t: MutableTotals): UsageTotals {
+  return {
+    runCount: t.runCount,
+    runsWithCost: t.runsWithCost,
+    runsWithoutCost: t.runsWithoutCost,
+    inputTokens: t.inputTokens,
+    outputTokens: t.outputTokens,
+    costUsd: t.costUsd,
+  };
+}
+
+function applyRunToTotals(totals: MutableTotals, facts: readonly FactRow[]): void {
+  const roll = rollupRunTokensAndCost(facts);
+  totals.runCount += 1;
+  if (roll.hasCost) {
+    totals.runsWithCost += 1;
+    totals.costUsd = addCost(totals.costUsd, roll.costUsd ?? 0);
+  } else {
+    totals.runsWithoutCost += 1;
+  }
+  totals.inputTokens += roll.inputTokens;
+  totals.outputTokens += roll.outputTokens;
+}
+
+function emptyReport(from?: Date, to?: Date): UsageReport {
+  return {
+    from: from?.toISOString() ?? null,
+    to: to?.toISOString() ?? null,
+    projects: [],
+    totals: freezeTotals(emptyMutableTotals()),
+    breakdown: [],
+  };
+}
+
 export async function getOrgUsage(
   prisma: PrismaClient,
   input: {
@@ -108,101 +309,65 @@ export async function getOrgUsage(
   }
 
   const projectIds = projects.map((p) => p.id);
-  const runWhere: Prisma.AgentRunWhereInput = {
-    projectId: { in: projectIds },
-    ...(input.from !== undefined || input.to !== undefined
-      ? {
-          startedAt: {
-            ...(input.from !== undefined ? { gte: input.from } : {}),
-            ...(input.to !== undefined ? { lte: input.to } : {}),
-          },
-        }
-      : {}),
-  };
-
   // Date range filters by run.startedAt, matching the pre-ADR-0026 semantics:
   // a run is in or out of the window based on when it started, and all of its
   // facts come along. Filtering facts by occurredAt independently would let a
   // run contribute partial cost to a window it doesn't belong to.
   const runs = await prisma.agentRun.findMany({
-    where: runWhere,
+    where: {
+      projectId: { in: projectIds },
+      ...(input.from !== undefined || input.to !== undefined
+        ? {
+            startedAt: {
+              ...(input.from !== undefined ? { gte: input.from } : {}),
+              ...(input.to !== undefined ? { lte: input.to } : {}),
+            },
+          }
+        : {}),
+    },
     select: {
       projectId: true,
       usageFacts: {
-        select: { inputTokens: true, outputTokens: true, costUsd: true },
+        select: FACT_SELECT,
         orderBy: { occurredAt: "asc" },
       },
     },
   });
 
-  type MutableRow = {
+  const byProject = new Map<string, MutableProjectRow>();
-    readonly projectId: string;
-    readonly projectName: string;
-    readonly folderId: string | null;
-    runCount: number;
-    runsWithCost: number;
-    runsWithoutCost: number;
-    inputTokens: number;
-    outputTokens: number;
-    costUsd: number | null;
-  };
-
-  const byProject = new Map<string, MutableRow>();
   for (const p of projects) {
     byProject.set(p.id, {
       projectId: p.id,
       projectName: p.name,
       folderId: p.folderId,
-      runCount: 0,
+      ...emptyMutableTotals(),
-      runsWithCost: 0,
-      runsWithoutCost: 0,
-      inputTokens: 0,
-      outputTokens: 0,
-      costUsd: null,
     });
   }
 
+  const breakdownBuckets = new Map<string, MutableBreakdown>();
   for (const run of runs as readonly RunWithFacts[]) {
     const row = byProject.get(run.projectId);
     if (row === undefined) continue;
-    const roll = rollupRun(run.usageFacts);
+    applyRunToTotals(row, run.usageFacts);
-    row.runCount += 1;
+    accumulateBreakdown(breakdownBuckets, run.usageFacts);
-    if (roll.hasCost) {
-      row.runsWithCost += 1;
-      row.costUsd = (row.costUsd ?? 0) + (roll.costUsd ?? 0);
-    } else {
-      row.runsWithoutCost += 1;
-    }
-    row.inputTokens += roll.inputTokens;
-    row.outputTokens += roll.outputTokens;
   }
 
   const projectsOut: ProjectUsageRow[] = [...byProject.values()].map((r) => ({
     projectId: r.projectId,
     projectName: r.projectName,
     folderId: r.folderId,
-    runCount: r.runCount,
+    ...freezeTotals(r),
-    runsWithCost: r.runsWithCost,
-    runsWithoutCost: r.runsWithoutCost,
-    inputTokens: r.inputTokens,
-    outputTokens: r.outputTokens,
-    costUsd: r.costUsd,
   }));
 
-  let runCount = 0;
+  const totals = emptyMutableTotals();
-  let runsWithCost = 0;
-  let runsWithoutCost = 0;
-  let inputTokens = 0;
-  let outputTokens = 0;
-  let costUsd: number | null = null;
   for (const row of projectsOut) {
-    runCount += row.runCount;
+    totals.runCount += row.runCount;
-    runsWithCost += row.runsWithCost;
+    totals.runsWithCost += row.runsWithCost;
-    runsWithoutCost += row.runsWithoutCost;
+    totals.runsWithoutCost += row.runsWithoutCost;
-    inputTokens += row.inputTokens;
+    totals.inputTokens += row.inputTokens;
-    outputTokens += row.outputTokens;
+    totals.outputTokens += row.outputTokens;
     if (row.costUsd !== null) {
-      costUsd = (costUsd ?? 0) + row.costUsd;
+      totals.costUsd = addCost(totals.costUsd, row.costUsd);
     }
   }
 
@@ -210,14 +375,8 @@ export async function getOrgUsage(
     from: input.from?.toISOString() ?? null,
     to: input.to?.toISOString() ?? null,
     projects: projectsOut,
-    totals: {
+    totals: freezeTotals(totals),
-      runCount,
+    breakdown: freezeBreakdown(breakdownBuckets),
-      runsWithCost,
-      runsWithoutCost,
-      inputTokens,
-      outputTokens,
-      costUsd,
-    },
   };
 }
 
@@ -229,7 +388,7 @@ export async function getProjectUsage(
     readonly from?: Date | undefined;
     readonly to?: Date | undefined;
   },
-): Promise<ProjectUsageRow> {
+): Promise<ProjectUsageReport> {
   const project = await prisma.project.findFirst({
     where: { id: input.projectId, organizationId: input.organizationId },
     select: { id: true, name: true, folderId: true },
@@ -237,39 +396,41 @@ export async function getProjectUsage(
   if (project === null) {
     throw new Error(`project not found: ${input.projectId}`);
   }
-  const report = await getOrgUsage(prisma, {
-    organizationId: input.organizationId,
-    from: input.from,
-    to: input.to,
-  });
-  const row = report.projects.find((p) => p.projectId === project.id);
-  return (
-    row ?? {
-      projectId: project.id,
-      projectName: project.name,
-      folderId: project.folderId,
-      runCount: 0,
-      runsWithCost: 0,
-      runsWithoutCost: 0,
-      inputTokens: 0,
-      outputTokens: 0,
-      costUsd: null,
-    }
-  );
-}
 
-function emptyReport(from?: Date, to?: Date): UsageReport {
+  const runs = await prisma.agentRun.findMany({
-  return {
+    where: {
-    from: from?.toISOString() ?? null,
+      projectId: project.id,
-    to: to?.toISOString() ?? null,
+      ...(input.from !== undefined || input.to !== undefined
-    projects: [],
+        ? {
-    totals: {
+            startedAt: {
-      runCount: 0,
+              ...(input.from !== undefined ? { gte: input.from } : {}),
-      runsWithCost: 0,
+              ...(input.to !== undefined ? { lte: input.to } : {}),
-      runsWithoutCost: 0,
+            },
-      inputTokens: 0,
+          }
-      outputTokens: 0,
+        : {}),
-      costUsd: null,
     },
+    select: {
+      usageFacts: {
+        select: FACT_SELECT,
+        orderBy: { occurredAt: "asc" },
+      },
+    },
+  });
+
+  const totals = emptyMutableTotals();
+  const breakdownBuckets = new Map<string, MutableBreakdown>();
+  for (const run of runs) {
+    applyRunToTotals(totals, run.usageFacts as readonly FactRow[]);
+    accumulateBreakdown(breakdownBuckets, run.usageFacts as readonly FactRow[]);
+  }
+
+  return {
+    projectId: project.id,
+    projectName: project.name,
+    folderId: project.folderId,
+    ...freezeTotals(totals),
+    from: input.from?.toISOString() ?? null,
+    to: input.to?.toISOString() ?? null,
+    breakdown: freezeBreakdown(breakdownBuckets),
   };
 }

hub/test/integration/capability-pdf-to-md.test.ts

@@ -4,11 +4,11 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { prisma, resetDb, seedTestOrganization, testSecretEnvelope, DEFAULT_ORG_ID } from "./helpers.js";
 import { createPdfToMdBundleAdapter, CapabilityPathEscape } from "../../src/capability/pdfToMdBundle.js";
-import { MineruClientError, type MineruClient, type MineruParseResult } from "../../src/capability/mineruClient.js";
+import { DocmindClientError, type CapabilityProviderClient, type DocmindParseResult } from "../../src/capability/docmindClient.js";
 import type { CapabilitySecretPayload } from "../../src/capability/types.js";
 
 const CAPABILITY_ID = "pdf_to_md_bundle";
-const PROVIDER_ID = "mineru";
+const PROVIDER_ID = "aliyun_docmind";
 
 /**
  * ADR-0027: pdf_to_md_bundle adapter contract tests. Proves:
@@ -16,8 +16,8 @@ const PROVIDER_ID = "mineru";
  *   - fail-closed credential resolution (no ACTIVE connection → error)
  *   - UsageFact attribution with non-token meter (pages), costSource rules
  *   - outputs (md + images) written into workspace
- *   - MinerU client errors propagate
+ *   - docmind client errors propagate
- * The MineruClient is mocked; the prisma + envelope + filesystem are real.
+ * The client is mocked; the prisma + envelope + filesystem are real.
  */
 describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
   let workspaceRoot: string;
@@ -58,9 +58,9 @@ describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
   async function seedActiveCapabilityConnection(): Promise<void> {
     const payload: CapabilitySecretPayload = {
       schemaVersion: 1,
-      baseUrl: "https://mineru.test/api",
+      accessKeyId: "LTAI-test-key-id",
-      apiToken: "mineru-secret-token",
+      accessKeySecret: "test-secret-never-log",
-      projectId: null,
+      endpoint: "docmind-api.cn-hangzhou.aliyuncs.com",
     };
     const connection = await prisma.organizationCapabilityConnection.create({
       data: {
@@ -95,23 +95,23 @@ describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
     });
   }
 
-  function mockMineruClient(result: Partial<MineruParseResult> = {}): MineruClient {
+  function mockDocmindClient(result: Partial<DocmindParseResult> = {}): CapabilityProviderClient {
-    const full: MineruParseResult = {
+    const full: DocmindParseResult = {
-      markdown: "# Parsed Document\n\nHello world.\n\n![fig](page_1_fig_0.jpg)\n",
+      markdown: "# Parsed Document\n\nHello world.\n\n![fig](page_1.jpg)\n",
       images: [
-        { filename: "page_1_fig_0.jpg", data: new Uint8Array([0xff, 0xd8, 0xff, 0xe0]) },
+        { filename: "page_1.jpg", data: new Uint8Array([0xff, 0xd8, 0xff, 0xe0]) },
       ],
       pageCount: 3,
-      costUsd: 0.015,
+      costUsd: 0.0168,
-      requestId: "mineru-task-abc",
+      requestId: "docmind-job-abc",
       ...result,
     };
     return {
-      parse: vi.fn(async (): Promise<MineruParseResult> => full),
+      parse: vi.fn(async (): Promise<DocmindParseResult> => full),
     };
   }
 
-  function makeAdapter(client: MineruClient) {
+  function makeAdapter(client: CapabilityProviderClient) {
     return createPdfToMdBundleAdapter({
       secrets: testSecretEnvelope,
       client,
@@ -130,7 +130,7 @@ describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
   it("writes md + images into the workspace and records a UsageFact", async () => {
     await seedActiveCapabilityConnection();
     const inputPath = await seedInputPdf();
-    const client = mockMineruClient();
+    const client = mockDocmindClient();
     const adapter = makeAdapter(client);
 
     const result = await adapter.invoke({
@@ -147,12 +147,12 @@ describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
     const md = await readFile(join(workspaceRoot, "output", "document.md"), "utf8");
     expect(md).toContain("# Parsed Document");
     expect(result.artifacts.some((a) => a.kind === "markdown" && a.path === "output/document.md")).toBe(true);
-    expect(result.artifacts.some((a) => a.kind === "image" && a.path === "output/page_1_fig_0.jpg")).toBe(true);
+    expect(result.artifacts.some((a) => a.kind === "image" && a.path === "output/page_1.jpg")).toBe(true);
 
     // Client received the decrypted credential, not the env.
     const call = (client.parse as ReturnType<typeof vi.fn>).mock.calls[0]?.[0] as CapabilitySecretPayload;
-    expect(call.apiToken).toBe("mineru-secret-token");
+    expect(call.accessKeyId).toBe("LTAI-test-key-id");
-    expect(call.baseUrl).toBe("https://mineru.test/api");
+    expect(call.endpoint).toBe("docmind-api.cn-hangzhou.aliyuncs.com");
 
     // UsageFact written with non-token meter and provider_reported cost.
     const facts = await prisma.usageFact.findMany({ where: { runId } });
@@ -163,15 +163,15 @@ describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
     expect(fact.capabilityId).toBe(CAPABILITY_ID);
     expect(Number(fact.quantity)).toBe(3);
     expect(fact.unit).toBe("pages");
-    expect(Number(fact.costUsd!)).toBeCloseTo(0.015, 8);
+    expect(Number(fact.costUsd!)).toBeCloseTo(0.0168, 8);
     expect(fact.costSource).toBe("provider_reported");
-    expect(fact.correlationId).toBe("mineru-task-abc");
+    expect(fact.correlationId).toBe("docmind-job-abc");
   });
 
-  it("writes UsageFact with costSource=unknown when MinerU reports no cost", async () => {
+  it("writes UsageFact with costSource=unknown when docmind reports no cost", async () => {
     await seedActiveCapabilityConnection();
     const inputPath = await seedInputPdf();
-    const client = mockMineruClient({ costUsd: null, requestId: null });
+    const client = mockDocmindClient({ costUsd: null, requestId: null });
     const adapter = makeAdapter(client);
 
     await adapter.invoke({
@@ -194,7 +194,7 @@ describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
   it("fails closed when the org has no ACTIVE capability connection", async () => {
     // No connection seeded.
     const inputPath = await seedInputPdf();
-    const adapter = makeAdapter(mockMineruClient());
+    const adapter = makeAdapter(mockDocmindClient());
 
     await expect(adapter.invoke({
       runId,
@@ -213,7 +213,7 @@ describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
 
   it("rejects an input path that escapes the workspace", async () => {
     await seedActiveCapabilityConnection();
-    const adapter = makeAdapter(mockMineruClient());
+    const adapter = makeAdapter(mockDocmindClient());
 
     await expect(adapter.invoke({
       runId,
@@ -229,7 +229,7 @@ describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
   it("rejects an output path that escapes the workspace", async () => {
     await seedActiveCapabilityConnection();
     const inputPath = await seedInputPdf();
-    const adapter = makeAdapter(mockMineruClient());
+    const adapter = makeAdapter(mockDocmindClient());
 
     await expect(adapter.invoke({
       runId,
@@ -242,12 +242,12 @@ describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
     })).rejects.toBeInstanceOf(CapabilityPathEscape);
   });
 
-  it("propagates MinerU client errors without writing a UsageFact", async () => {
+  it("propagates docmind client errors without writing a UsageFact", async () => {
     await seedActiveCapabilityConnection();
     const inputPath = await seedInputPdf();
-    const client: MineruClient = {
+    const client: CapabilityProviderClient = {
-      parse: vi.fn(async (): Promise<MineruParseResult> => {
+      parse: vi.fn(async (): Promise<DocmindParseResult> => {
-        throw new MineruClientError("upstream 502", "mineru_rejected", 502);
+        throw new DocmindClientError("upstream 502", "docmind_rejected", 502);
       }),
     };
     const adapter = makeAdapter(client);
@@ -269,7 +269,7 @@ describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
   it("rejects empty markdown output as a parse failure", async () => {
     await seedActiveCapabilityConnection();
     const inputPath = await seedInputPdf();
-    const client = mockMineruClient({ markdown: "" });
+    const client = mockDocmindClient({ markdown: "" });
     const adapter = makeAdapter(client);
 
     await expect(adapter.invoke({

hub/test/integration/usage.test.ts

@@ -71,7 +71,7 @@ describe("usage rollup from UsageFact (ADR-0026)", () => {
           occurredAt: new Date(startedAt.getTime() + i * 1000),
           kind: f.kind ?? "model_completion",
           provider: f.provider ?? "openrouter",
-          model: f.model ?? "mock-model",
+          model: f.model !== undefined ? f.model : "mock-model",
           inputTokens: f.inputTokens ?? null,
           outputTokens: f.outputTokens ?? null,
           costUsd: f.costUsd ?? null,
@@ -158,6 +158,32 @@ describe("usage rollup from UsageFact (ADR-0026)", () => {
     expect(report.totals.inputTokens).toBe(100);
     expect(report.totals.outputTokens).toBe(50);
     expect(report.totals.costUsd).toBeCloseTo(0.035, 8);
+    // ADR-0026 breakdown: model tokens vs external non-token meter must not collapse.
+    expect(report.breakdown).toHaveLength(2);
+    const modelBucket = report.breakdown.find((b) => b.kind === "model_completion");
+    const capBucket = report.breakdown.find((b) => b.kind === "external_capability");
+    expect(modelBucket).toMatchObject({
+      provider: "openrouter",
+      model: "mock-model",
+      capabilityId: null,
+      inputTokens: 100,
+      outputTokens: 50,
+      quantity: null,
+      costUsd: 0.02,
+      factCount: 1,
+    });
+    expect(capBucket).toMatchObject({
+      provider: "mineru",
+      model: null,
+      capabilityId: "pdf_to_md_bundle",
+      unit: "pages",
+      quantity: 12,
+      inputTokens: 0,
+      outputTokens: 0,
+      costUsd: 0.015,
+      factCount: 1,
+    });
+
   });
 
   it("a run with no facts at all is runsWithoutCost and contributes nothing", async () => {
@@ -180,6 +206,8 @@ describe("usage rollup from UsageFact (ADR-0026)", () => {
     expect(row.projectId).toBe("proj-x");
     expect(row.runCount).toBe(1);
     expect(row.costUsd).toBeCloseTo(0.1, 8);
+    expect(row.breakdown).toHaveLength(1);
+    expect(row.breakdown[0]).toMatchObject({ kind: "model_completion", costUsd: 0.1, inputTokens: 1 });
   });
 
   it("returns an empty report for an org with no projects", async () => {
@@ -187,5 +215,7 @@ describe("usage rollup from UsageFact (ADR-0026)", () => {
     expect(report.projects).toHaveLength(0);
     expect(report.totals.runCount).toBe(0);
     expect(report.totals.costUsd).toBeNull();
+    expect(report.breakdown).toEqual([]);
+
   });
 });