Skip to content

Commit b428269

Browse files
authored
chore(dsh-provider-usage): 过期文档以当前架构为准清理 + 源码注释去过程标记(#681) (#686)
* docs(dsh-provider-usage): 过期重构文档以当前架构为准清理(plan 改现状、契约基线同步目录化路径、交接文档归档)(#681) - layer-architecture-next-session.md(纯交接 prompt,重构已完成使命结束): 归档至 docs/archive/ 而非删除——保留 git 历史可追溯,docs/ 不入发布物 files 白名单(仅 lib/shared/**/*.d.ts/cordis.patch.yml/README/LICENSE), 无其它文档/README 引用该路径,无需改引用 - refactor-implementation-plan.md 由「实施计划」改写为「当前架构与决策的静态说明」 (文件名保留使 diagrams 图内引用与 test 注释路径不断链):删除阶段方案表 (阶段零→收尾)、阶段 PR 序列、双专家评审/必改 8 项、实施跟踪等过程叙述; 保留并校正决策表 D1-D17、目录树(补 errsurf/list-dirs/aggregate-rows/ aggregate-query,去未实施的 prompts.ts 与 apply 拆分残余)、35 文件映射表、 冲突裁决结论(interface.ts 最小面具名导出、死面清理完成态、import 边界门禁现状) - layer-architecture.md 契约基线:契约表「文件 · 符号」引用路径全部同步目录化后 (report/config.ts→domain2/schedule/config.ts、trend/aggregator.ts→ domain2/aggregate/aggregator.ts、core/history.ts→domain1/history/history.ts、 apply.ts→apply/apply.ts、routes/ui.ts→domain2/routes/ui.ts 等,按实际 grep 逐条校正); 去评审过程叙述(双专家评审合并版/G2 评分/⚠️修订标注)、基线快照 e64f859 证据引用; 决策表补 D-17;目录化已完成故图索引只列现状图并注明「图含目录化前路径, 契约以符号锚为准」;源文件注释中的 §2/§2.3/§4 章节引用保持有效 - 同步 test/ 4 处注释中的文档引用至新章节(§2/§2 E2) 关联 issue:#681(C1 过期文档同步)、#670(重构跟踪) * refactor(dsh-provider-usage): 源码注释清理——去阶段/issue 来源标记与废话,只留技术 why(#681) 清理口径与保留标准: - 删除「阶段/子项」与 issue 编号来源标记(#503/#633/#654/#662/#625/#626/#670 等, 以及 M1/M2/A1/B1/D8/E3 等子项代号、评审 P1-x/复核 M1 等过程编号)——编号只 记录「哪个阶段哪个 issue 做的」,属提交信息而非代码注释的职责; - 编号前缀之后的非显然技术内容(坑/竞态/边界/跨文件口径锚点)原样保留,仅去编号; - 删除描述性「正确的废话」与纯流程性行注释; - 文件头「模块职责 + 关键口径」总述保留,去过程尾巴(如 D2 拆分、阶段四目录化归位); - 功能性指令注释(dsh-gate:allow-homedir)、字符串/模板文本(提示词模板、HTML 实体 示例 {、microsoft/TypeScript#63960 外部引用)一律不动。 来源上下文:本提交为 #681(dsh-provider-usage 注释清理跟踪)的「注释清理」单元; 源码中的阶段标记(阶段二/三/四、#670 阶段三 B、D8 归位等)对应 #670「阶段四 两级目录化」工作——这些过程信息已随 #670 各提交的 commit message 记录, 无需在注释中重复。 门禁:typecheck / build / test(21 套)全绿。 * fix(dsh-provider-usage): 恢复三处 dsh-gate:allow-homedir 豁免注释的 issue 编号(#681) 注释清理误删了豁免注释中的 #NNN——forbid-homedir-src 的 EXEMPT_RE 要求豁免注释必须携带 issue 编号(dsh-gate:allow-homedir #NNN 理由), 该编号是豁免登记的必要格式而非过程标记。恢复 apply.ts(#517)、 path-resolve.ts(#87)、provider-config.ts(#525)。 Related: #681
1 parent 524c3f2 commit b428269

73 files changed

Lines changed: 693 additions & 736 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

packages/dsh-provider-usage/docs/layer-architecture-next-session.md renamed to packages/dsh-provider-usage/docs/archive/layer-architecture-next-session.md

File renamed without changes.

‎packages/dsh-provider-usage/docs/layer-architecture.md‎

Lines changed: 74 additions & 76 deletions
Large diffs are not rendered by default.

‎packages/dsh-provider-usage/docs/refactor-implementation-plan.md‎

Lines changed: 77 additions & 115 deletions
Large diffs are not rendered by default.

‎packages/dsh-provider-usage/src/apply/apply.ts‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
* - GET /api/dsh-provider-usage/report-models 报告模型候选
1717
* - GET /api/dsh-provider-usage/reports 报告历史索引
1818
* - GET /api/dsh-provider-usage/reports/detail 报告详情
19-
* - POST /api/dsh-provider-usage/reports/generate 手动生成报告(#625:立即返回 202+taskId)
19+
* - POST /api/dsh-provider-usage/reports/generate 手动生成报告(立即返回 202+taskId)
2020
* - GET /api/dsh-provider-usage/reports/generate/status 生成任务状态轮询
2121
*/
2222

@@ -215,8 +215,8 @@ export async function apply(ctx: Context, rawConfig: Record<string, unknown> = {
215215
// dsh-gate:allow-homedir #517 展示层脱敏:把诊断文本中的 home 前缀折叠为 ~,不产生读写面
216216
s.split(dshHome()).join("~/.dsh").split(homedir()).join("~");
217217

218-
// #670 阶段三 B:域2每层错误面(aggregate/schedule/execute)——装配层组合根创建,
219-
// 经各对象既有 warn 诊断出口接线(层代码零改动,避免与 aggregator 拆分任务 A 冲突);
218+
// 域2每层错误面(aggregate/schedule/execute)——装配层组合根创建,
219+
// 经各对象既有 warn 诊断出口接线(层代码零改动);
220220
// health per-layer 段经 UiRoutesContext 注入 routes/ui.ts 读取。
221221
const layerErrors = makeLayerErrorSurface();
222222

@@ -295,14 +295,14 @@ export async function apply(ctx: Context, rawConfig: Record<string, unknown> = {
295295
const trend = await TrendTracker.start({
296296
root: join(historyRoot, "trend"),
297297
retentionDays: config.trendRetentionDays,
298-
// #670 阶段三 B:aggregate 层错误面接线——压实失败/刷盘失败/归属异常等
298+
// aggregate 层错误面接线——压实失败/刷盘失败/归属异常等
299299
// 趋势层运行时错误全部汇聚到 TrendTracker 的 warn 诊断出口,此处同时上报。
300300
warn: (msg) => {
301301
const safe = sanitizeDiagnostic(msg);
302302
layerErrors.record("aggregate", safe);
303303
console.warn(`[dsh-provider-usage] trend: ${safe}`);
304304
},
305-
// #633 A1:目录归属主源 = 官方 store 的会话创建元数据(SessionHeader.cwd)。
305+
// 目录归属主源 = 官方 store 的会话创建元数据(SessionHeader.cwd)。
306306
// SessionId 为官方品牌类型(string & BRAND),裸 string 经 get 参数位断言桥接
307307
// (官方品牌桥接须 import type @deepseek-ai/dsh-brand——catalog 已锁 0.1.2-rc.1,
308308
// 但本包 package.json 未声明该 peer,pnpm 严格隔离下类型不可达;引入须先过
@@ -321,16 +321,16 @@ export async function apply(ctx: Context, rawConfig: Record<string, unknown> = {
321321
trendDisposers.push(ctx.on("session/flush", () => trend.flushNow()));
322322
trendDisposers.push(ctx.on("session/disposed", (session) => trend.handleDisposed(session)));
323323

324-
// D8 阶段二:reportCfg 双源收口为 ReportConfigService(内存权威 + 串行写链,
325-
// 并发 POST 不交错 lost-update);执行器移入 E4 工厂(executor.ts),装配只留接线。
324+
// reportCfg 双源收口为 ReportConfigService(内存权威 + 串行写链,
325+
// 并发 POST 不交错 lost-update);执行器移入工厂(executor.ts),装配只留接线。
326326
const reportCfgService = new ReportConfigService({
327327
root: historyRoot,
328328
initial: await readReportConfig(historyRoot),
329329
onUpdate: (cfg) => reportScheduler.updateConfig(cfg),
330330
});
331331

332-
// #625/#626:任务队列 = 定时 tick 与手动「立即生成」的单一执行入口。
333-
// 执行器职责(幂等下沉/生成/lastRun 推进/失败不推进/脱敏)在 E4 工厂契约内固化,
332+
// 任务队列 = 定时 tick 与手动「立即生成」的单一执行入口。
333+
// 执行器职责(幂等下沉/生成/lastRun 推进/失败不推进/脱敏)在工厂契约内固化,
334334
// 队列只负责串行单飞与去重(tasks.ts)。
335335
const reportQueue = new ReportTaskQueue({
336336
executor: makeDueReportExecutor({
@@ -340,7 +340,7 @@ export async function apply(ctx: Context, rawConfig: Record<string, unknown> = {
340340
historyRoot,
341341
sanitizeDiagnostic,
342342
}),
343-
// #670 阶段三 B:execute 层错误面接线——任务执行失败(含 executor 脱敏后错误)
343+
// execute 层错误面接线——任务执行失败(含 executor 脱敏后错误)
344344
// 经队列 warn 出口汇聚于此。
345345
warn: (msg) => {
346346
const safe = sanitizeDiagnostic(msg);
@@ -352,12 +352,12 @@ export async function apply(ctx: Context, rawConfig: Record<string, unknown> = {
352352
const reportScheduler = ReportScheduler.start({
353353
root: historyRoot,
354354
config: reportCfgService.get(),
355-
// #625:tick 只提交任务(非阻塞,队列去重吸收同窗口堆积),不再等待生成
355+
// tick 只提交任务(非阻塞,队列去重吸收同窗口堆积),不再等待生成
356356
onDue: (due) => {
357357
reportQueue.submit(due);
358358
return Promise.resolve();
359359
},
360-
// #670 阶段三 B:schedule 层错误面接线——tick 异常/提交失败经调度器
360+
// schedule 层错误面接线——tick 异常/提交失败经调度器
361361
// warn 出口汇聚于此。
362362
warn: (msg) => {
363363
const safe = sanitizeDiagnostic(msg);
@@ -416,7 +416,7 @@ export async function apply(ctx: Context, rawConfig: Record<string, unknown> = {
416416
historyRoot,
417417
reportQueue,
418418
reportCfgService,
419-
// D8:目录候选清单收敛为注入查询面(makeListDirs 工厂,apply 零隐藏可变状态)
419+
// 目录候选清单收敛为注入查询面(makeListDirs 工厂,apply 零隐藏可变状态)
420420
listDirs: makeListDirs(trend),
421421
},
422422
),

‎packages/dsh-provider-usage/src/apply/index.ts‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* dsh-provider-usage — 用量统计插件(宿主端组合根,v2 重构版)。
33
*
4-
* 结构(#276 方案 A 阶段 3 拆分):职责按模块拆分(contracts / registry /
4+
* 结构:职责按模块拆分(contracts / registry /
55
* adapters / core / pipeline / provider-config / path-resolve / hotreload /
66
* placement-math / config / ui-config / user-adapters / apply),本文件保留
77
* 插件契约转发(apply 与路由表)与全部公共符号 re-export(导出面不变,
@@ -17,10 +17,10 @@
1717
* - GET /api/dsh-provider-usage/health 健康检查 + 适配器快照
1818
* - GET/POST /api/dsh-provider-usage/ui-config 胶囊位置配置(读取/保存,保存后 SSE 广播)
1919
* - GET /api/dsh-provider-usage/events SSE 事件通道(ui-config-changed 等,客户端即时热更新)
20-
* - GET/POST /api/dsh-provider-usage/report-config 报告配置(读/写,#503 M3)
21-
* - GET /api/dsh-provider-usage/reports 报告历史索引(#503 M3)
22-
* - GET /api/dsh-provider-usage/reports/detail 报告详情(#503 M3)
23-
* - POST /api/dsh-provider-usage/reports/generate 手动生成报告(#503 M3)
20+
* - GET/POST /api/dsh-provider-usage/report-config 报告配置(读/写)
21+
* - GET /api/dsh-provider-usage/reports 报告历史索引
22+
* - GET /api/dsh-provider-usage/reports/detail 报告详情
23+
* - POST /api/dsh-provider-usage/reports/generate 手动生成报告
2424
*/
2525

2626
// ------------------------------------------------------------------ 对外 re-export
@@ -66,7 +66,7 @@ export type {
6666
} from "../shared/interface.ts";
6767
export { makeAdapterRegistry } from "../domain1/registry/interface.ts";
6868
export type { AdapterSource, AdapterErrorInfo, AdapterInfo, ReplaceFileResult, AdapterRegistry } from "../domain1/registry/interface.ts";
69-
// #215 共享图表工具库(AdapterUtils/ADAPTER_UTILS 等)——外部 TS 消费者可经 index 导入。
69+
// 共享图表工具库(AdapterUtils/ADAPTER_UTILS 等)——外部 TS 消费者可经 index 导入。
7070
// dayKey/lastNDayKeys 与 deepseek-official.mjs 文件级导出重名(测试导入面),
7171
// 此处显式排除,deepseek-official.mjs 的导出保留(同源副本,语义一致)。
7272
export {
@@ -89,7 +89,7 @@ export {
8989
ADAPTER_UTILS,
9090
} from "../shared/interface.ts";
9191
export type { AdapterUtils } from "../shared/interface.ts";
92-
// #215 内置适配器 mjs 化:.mjs 为权威实现,.d.mts 提供类型声明(bundle 后 index 内联
92+
// 内置适配器 mjs 化:.mjs 为权威实现,.d.mts 提供类型声明(bundle 后 index 内联
9393
// 保留具名导出面——unit-contract/unit-deepseek-official 等测试从 lib/index.js 导入不变)
9494
export { OPENCODE_GO_PROVIDER, OPENCODE_GO_ADAPTER_ID, DEFAULT_BASE_URL, OPENCODE_GO_WINDOWS, pickWindow, parseUsageResponse, fetchOpenCodeGoV2, miniChartSvgMarkup, openCodeGoAdapter } from "../domain1/adapters/interface.ts";
9595
export { DEEPSEEK_OFFICIAL_PROVIDER, DEEPSEEK_OFFICIAL_ADAPTER_ID, BASE_URL, parseAmount, resolveEndpoint, GAP_MS, TOL, ANOMALY_NEG, PEAK_WINDOWS_UTC, isPeakUtc, nextPeakTransition, peakBadgeHtml, fetchDeepSeekOfficialV2, formatCapsuleWithBadge, classifyIntervalDs, aggregateDaily, dailyBarTitle, niceCeil, dayKey, lastNDayKeys, deepSeekOfficialAdapter } from "../domain1/adapters/interface.ts";
@@ -106,7 +106,7 @@ export { splitProviderList, providerBadgeText } from "../shared/interface.ts";
106106
export { runV2Pipeline, runV2PanelPipeline, panelCacheKey, normalizeRangeDay, isPanelCacheStale, PANEL_CACHE_TTL_MS } from "../domain1/pipeline/interface.ts";
107107
export type { PanelCacheEntry } from "../domain1/pipeline/interface.ts";
108108
export { HotReloadableAdapter, loadAndValidateAdapter, readStamp, stampEqual } from "../domain1/registry/interface.ts";
109-
// #503 会话用量趋势(M1 数据层):trend 模块公共面(测试/外部消费者从 lib/index.js 导入)
109+
// 会话用量趋势:trend 模块公共面(测试/外部消费者从 lib/index.js 导入)
110110
export { TrendTracker } from "../domain2/aggregate/interface.ts";
111111
export type { TrendTrackerOptions } from "../domain2/aggregate/interface.ts";
112112
export { TrendCollector, TREND_FOLD_TTL_MS, TREND_DONE_MAX } from "../domain2/collect/interface.ts";
@@ -117,7 +117,7 @@ export { TrendStore } from "../domain2/aggregate/interface.ts";
117117
// isValidShardRow/safeToken/safeId:分片行校验与防御提取纯函数(单测从 lib/index.js 导入)
118118
export { TREND_ROW_VERSION, TREND_UNIDENTIFIED, TREND_DIR_MAX, sumToken, isValidShardRow, safeToken, safeId, sanitizeDirName, hourOfDay } from "../domain2/collect/interface.ts";
119119
export type { TrendAttribution, TrendTokens, TrendDetailRow, TrendCounterRow, TrendAggRow, TrendDirRow, TrendHourRow, TrendCell } from "../domain2/collect/interface.ts";
120-
// #503 会话用量报告(M3 接线):report 模块公共面(测试/外部消费者从 lib/index.js 导入)
120+
// 会话用量报告:report 模块公共面(测试/外部消费者从 lib/index.js 导入)
121121
export { candidateWindow, pendingReports, presetLastRunForNewlyEnabled, previousClosedWindow, deriveLastRun, isClosedWindowRecord, LAST_RUN_SCHEMA } from "../domain2/schedule/interface.ts";
122122
export type { DueReport, LastRunRecord } from "../domain2/schedule/interface.ts";
123123
export { parseHHMM, normalizeReportConfig, normalizeReportDirectories, DEFAULT_REPORT_CONFIG, DEFAULT_PROMPT_TEMPLATE, readReportConfig, writeReportConfig, reportConfigFile } from "../domain2/schedule/interface.ts";
@@ -129,27 +129,27 @@ export type { ReportPrompts } from "../domain2/schedule/interface.ts";
129129
export type { ReportMeta, ReportResult, ReportStatsSnapshot, ReportLlmService, ReportTokenUsage } from "../domain2/execute/interface.ts";
130130
export { ReportScheduler } from "../domain2/schedule/interface.ts";
131131
export { readLastRun, writeLastRun, updateLastRun, ensureLastRunMigrated, __lastRunChainForTests } from "../domain2/common/interface.ts";
132-
// D8 阶段二:执行器工厂与报告配置服务(E4/装配面公共符号,测试/外部消费者从 lib 导入)
132+
// 执行器工厂与报告配置服务(装配面公共符号,测试/外部消费者从 lib 导入)
133133
export { makeDueReportExecutor } from "../domain2/execute/interface.ts";
134134
export type { DueExecutorDeps } from "../domain2/execute/interface.ts";
135135
export { ReportConfigService } from "./report-config-service.ts";
136136
export type { ReportConfigServiceOptions } from "./report-config-service.ts";
137-
// #625/#626 任务队列(手动生成与定时共用执行入口)
137+
// 任务队列(手动生成与定时共用执行入口)
138138
export { ReportTaskQueue } from "../domain2/schedule/interface.ts";
139139
export type { ReportTask, ReportTaskInput, ReportTaskResult, ReportTaskStatus } from "../domain2/schedule/interface.ts";
140-
// 读侧投影(#626:一行/窗口=最新版)与公共解析(解析原语在 report-index.ts,D8 归位)
140+
// 读侧投影(一行/窗口=最新版)与公共解析(解析原语在 report-index.ts)
141141
export { readReportIndex, prevWindowTotal, runDueReport, persistReport, reportHtmlFile, reportMetaFile, notifyReport, __clearReportIndexCacheForTests, __reportIndexCacheStatsForTests } from "../domain2/execute/interface.ts";
142142
export { parseReportIndexLines } from "../domain2/common/interface.ts";
143143
// 路径解析纯函数透出(供测试与调用方复用同一展开/解析规则,无行为变更)
144144
export { resolvePath, pluginHome, expandHomePath } from "../domain1/registry/interface.ts";
145-
// 配置归一化(#276 方案 A 阶段 3 拆出:默认值 / schemastery schema / normalizeConfig)
145+
// 配置归一化(默认值 / schemastery schema / normalizeConfig)
146146
export { DEFAULT_CONFIG, Config, normalizeConfig } from "../shared/interface.ts";
147147
export type { NormalizedConfig } from "../shared/interface.ts";
148148

149149
// ------------------------------------------------------------------ 类型
150150

151151
export const name = "provider-usage";
152-
// #633 修复:`sessions` 必须声明——apply 的 resolveCwd 经 ctx.sessions.get(id)?.header.cwd
152+
// `sessions` 必须声明——apply 的 resolveCwd 经 ctx.sessions.get(id)?.header.cwd
153153
// 取会话工作目录(目录维度归属主源)。cordis 4 对未在 inject 声明的服务属性直访抛
154154
// 「cannot get property "sessions" without inject」;该异常会被 resolveCwd 的 catch 吞掉,
155155
// 于是每个会话恒归未识别桶、目录维度全链路失效(历史与当期数据双失)。缺声明是静默
@@ -175,15 +175,15 @@ export {
175175
export type { FloatBreakpoint, ViewportPoint, RectLike } from "../shared/interface.ts";
176176
// 面板锚点判定同为纯函数,随定位数学一起从单一事实源 re-export。
177177
export { panelAnchorForPlacement } from "../shared/interface.ts";
178-
// 胶囊位置 UI 配置(#276 方案 A 阶段 3 拆出:纯函数 + 持久化读写)
178+
// 胶囊位置 UI 配置(纯函数 + 持久化读写)
179179
export { DEFAULT_UI_CONFIG, normalizeUiConfig, panelTopForAnchor, uiConfigFile, readUiConfig, writeUiConfig } from "../shared/interface.ts";
180180
export type { UiPlacementConfig } from "../shared/interface.ts";
181-
// sseData 已收敛 shared/host-utils.js(#472):单独改指共享层,导出面保持不变
181+
// sseData 已收敛 shared/host-utils.js:单独改指共享层,导出面保持不变
182182
export { sseData } from "../../../../shared/host-utils.js";
183-
// 用户适配器持久化(#276 方案 A 阶段 3 拆出:清单/启用状态读写 + add 文件校验)
183+
// 用户适配器持久化(清单/启用状态读写 + add 文件校验)
184184
export { userAdaptersFile, adapterStateFile, parseUserAdapters, readUserAdapters, readAdapterState, resolveAddAdapterFile } from "../domain1/registry/interface.ts";
185185
export type { UserAdapterRecord } from "../domain1/registry/interface.ts";
186186
// 插件契约转发(apply 主流程 + 路由表实现于 apply.ts)
187187
export { apply, ROUTES } from "./apply.ts";
188-
// 路由 handler 直出(#629 P2:status 响应 reused 透传的单元断言面)
188+
// 路由 handler 直出(status 响应 reused 透传的单元断言面)
189189
export { handleReportStatus } from "../domain2/routes/interface.ts";

‎packages/dsh-provider-usage/src/apply/interface.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
2-
* dsh-provider-usage — apply/ 装配层目录门面(#670 D9/C 梯队)。
2+
* dsh-provider-usage — apply/ 装配层目录门面。
33
*
4-
* 目录化约定(#670 D9):目录外(domain2/domain1/shared)引用 apply/ 一律经本
4+
* 目录化约定:目录外(domain2/domain1/shared)引用 apply/ 一律经本
55
* 文件消费。apply/ 是装配层组合根(特权目录),对外面 = apply() 主函数、
66
* inject 与 lib 导出面——但 lib 入口仍是 apply/index.ts(bundle-host 锚点,
77
* 经 lib/index.js 对外),本文件只服务「目录外源码引用」这一场景。

‎packages/dsh-provider-usage/src/apply/report-config-service.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
2-
* dsh-provider-usage/report — 报告配置服务(阶段二 D8:reportCfg 闭包双源收口)。
2+
* dsh-provider-usage/report — 报告配置服务(reportCfg 双源收口)。
33
*
4-
* 内存权威 + 串行写链(复用 updateLastRun 的 per-root promise 链模式,#629 教训):
4+
* 内存权威 + 串行写链(复用 updateLastRun 的 per-root promise 链模式):
55
* 并发 POST report-config 的「写盘 + 内存 + scheduler 热更」不再交错(原 apply 闭包
66
* setReportCfg/writeReportConfig 无串行化,与 lastRun 曾有 lost-update 同类)。
77
* 磁盘读(GET/启动)仍以文件为权威——进程外修改可见;写路径统一走 update() 串行。

0 commit comments

Comments
 (0)