diff --git a/src/commands/_gates/_checkpoint_k.ts b/src/commands/_gates/_checkpoint_k.ts new file mode 100644 index 0000000..986a533 --- /dev/null +++ b/src/commands/_gates/_checkpoint_k.ts @@ -0,0 +1,59 @@ +/** + * commands/_gates/_checkpoint_k.ts + * + * K 关卡 (webapi hardening, v0.23+) + * + * 设计: + * - 设计阶段 (phase='design'): 不实施检查, 返回 not-applicable (退出 0). + * 理由: 设计阶段还没创建资源, summaryResources 为空是预期的. + * - 总结阶段 (phase='summary'): 回查 summaryResources 实际是否仍存在, 缺则非零退出. + * 理由: 总结文档引用的资源可能已被中途删/改, 引用失效的 doc 价值低. + * + * 设计原则: + * - 纯函数 (除 liveLookup 外零 I/O): caller 注入 lookup, 模块不依赖 webapi loader / dict / menu + * - liveLookup 默认 null → 视为缺失 (缺省情况, 总结阶段无 lookup 不通过) + * - 失败信息: 列出 missing 资源 (供 caller 写日志/stdout) + */ +export interface KInput { + phase: 'design' | 'summary' + appCode: string + /** 设计阶段声明的资源 (设计阶段此字段在 doc 里, summary 阶段可对照) */ + designResources: Array<{ kind: string; id: string }> + /** 总结阶段声明的资源 (必须回查存在) */ + summaryResources: Array<{ kind: string; id: string }> + /** 注入: 实际查询函数, 返回 id 表示存在, null 表示缺失 */ + liveLookup?: (res: { kind: string; id: string }) => Promise +} + +export interface KResult { + status: 'not-applicable' | 'ok' | 'failure' + exitCode: 0 | 1 + missing?: Array<{ kind: string; id: string }> + reason?: string +} + +/** + * K 关卡主函数 + * - phase=design: 永远 not-applicable (退出 0) + * - phase=summary: 逐个回查 summaryResources, 全部存在 → ok; 任一缺失 → failure (退出 1) + 列出 missing + */ +export async function checkKCheckpoint(input: KInput): Promise { + if (input.phase === 'design') { + return { status: 'not-applicable', exitCode: 0 } + } + const lookup = input.liveLookup ?? (async () => null) + const missing: KResult['missing'] = [] + for (const r of input.summaryResources) { + const got = await lookup(r) + if (!got) missing.push(r) + } + if (missing.length > 0) { + return { + status: 'failure', + exitCode: 1, + missing, + reason: `${missing.length} resource(s) missing at summary`, + } + } + return { status: 'ok', exitCode: 0 } +} diff --git a/src/commands/app/_context_summary.ts b/src/commands/app/_context_summary.ts new file mode 100644 index 0000000..b2fcd47 --- /dev/null +++ b/src/commands/app/_context_summary.ts @@ -0,0 +1,39 @@ +/** + * commands/app/_context_summary.ts + * + * `dacli app context --summary` 摘要 (webapi hardening, v0.23+) + * + * 设计: + * - AI 工作流通常只需要: appCode / dbLinkId / tokenStatus / user / resourceCounts / warnings + * - 完整 context 含 menuList / permissionTree / existingEnCodes (可能数百条), 占用 AI context window + * - 摘要模式剔除重字段, warnings 限长 ≤5 + * + * 注意: 这是一个**纯函数** (零 I/O, 零副作用), 方便 vitest 单测 + 任何 caller 复用. + */ +export interface ContextSummary { + appCode: string + systemId: string + dbLinkId: string + tokenStatus: 'ok' | 'expired' | 'unknown' + user: { id: string; account: string; realName?: string } + resourceCounts?: { forms: number; flows: number; menus: number; dicts: number } + warnings: Array<{ kind: string; message: string }> +} + +/** 摘要 — 剔除 menuList/permissionTree, warnings 限长 ≤5 */ +export function buildContextSummary(full: any): ContextSummary { + const warnings = Array.isArray(full?.warnings) ? full.warnings.slice(0, 5) : [] + return { + appCode: full?.appCode ?? '', + systemId: full?.systemId ?? '', + dbLinkId: full?.dbLinkId ?? '', + tokenStatus: (full?.tokenStatus ?? 'unknown') as ContextSummary['tokenStatus'], + user: { + id: full?.user?.id ?? '', + account: full?.user?.account ?? '', + realName: full?.user?.realName, + }, + resourceCounts: full?.resourceCounts, + warnings, + } +} diff --git a/src/commands/app/context.ts b/src/commands/app/context.ts index ac59d13..1586d83 100644 --- a/src/commands/app/context.ts +++ b/src/commands/app/context.ts @@ -24,6 +24,7 @@ import { formatSystemMissingHint, } from './_check_system.ts' import { getUserInfoApi } from '../../webapi/user.ts' +import { buildContextSummary } from './_context_summary.ts' // v0.23+ (webapi hardening): --summary 摘要模式 // 复用 cli.ts 的 VERSION 常量 — 避免重复硬编码, 也避免外部依赖 (cat package.json) // 路径相对 src/commands/app/context.ts → ../../../src/cli.ts @@ -39,6 +40,7 @@ const PAGE_SIZE = 500 // 一次拉完, 避免分页遗漏 interface ContextOpts { json?: boolean app?: string + summary?: boolean // v0.23+ (webapi hardening): AI 友好摘要模式, 剔除重字段 } /** 从 src/cli.ts 源码中提取 const VERSION = '...' */ @@ -371,6 +373,7 @@ export function buildAppContextCommand(): Command { .option('--json', '单行 JSON 输出 (AI 友好)', false) .option('--verbose', '完整输出 (含 loadAppContext 内部 API 调用日志)', false) .option('--app ', '覆盖 token 中的 appCode (供快速切换测试)') + .option('--summary', 'AI 友好摘要 (剔除重字段, warnings 限长 ≤5). 搭配 --json 使用.', false) // v0.23+ (webapi hardening) .action(async (opts: ContextOpts & { verbose?: boolean }) => { // v2.1+ L1: stdout 三模式 (default=quiet, --verbose=完整, --json=单行 JSON; --json 优先) setupOutputFilter(opts) @@ -385,8 +388,11 @@ export function buildAppContextCommand(): Command { // 输出 if (opts.json) { + // v0.23+ (webapi hardening): --summary 模式产出 ContextSummary (剔除重字段) + // 顺序: --summary 优先于 --json (summary 本身就小, 默认单行 JSON) + const out = opts.summary ? buildContextSummary(ctx) : ctx // 单行 JSON (AI 友好, 便于 grep/管道) - console.log(JSON.stringify(ctx)) + console.log(JSON.stringify(out)) // v2.1+ L3: 落 CommandLog (即使 --json, CommandLog 仍落, 供 dacli log last 查询) printCommandEnd({ command: 'app context', @@ -459,8 +465,9 @@ export function buildAppContextCommand(): Command { optional: { '--json': '单行 JSON 输出 (推荐 AI 使用)', '--app': '覆盖 token 中的 appCode (供快速切换测试)', + '--summary': 'AI 友好摘要 (剔除重字段, 搭配 --json 使用)', }, - example: ['dacli app context --json', 'dacli app context --app=tds --json'], + example: ['dacli app context --json', 'dacli app context --app=tds --json', 'dacli app context --json --summary'], source: { api: 'GET /api/visualdev/Base, /api/system/DataModel/{dbLinkId}/Tables, /api/system/Menu/ModuleBySystem', ref: 'doc/ai-optimization-plan.md §2.1, doc/ai-error-analysis.md §B', diff --git a/tests/unit/app_context_summary.test.ts b/tests/unit/app_context_summary.test.ts new file mode 100644 index 0000000..7592786 --- /dev/null +++ b/tests/unit/app_context_summary.test.ts @@ -0,0 +1,51 @@ +/** + * tests/unit/app_context_summary.test.ts + * + * 覆盖 src/commands/app/_context_summary.ts + * (webapi hardening: 摘要模式不输出完整 menuList/permissionTree, AI 友好) + * + * 设计: + * - buildContextSummary 接受 full AppContext (含 warnings 数组等) + * - 返回 ContextSummary: 剔除重字段, warnings 限长 ≤5 + * - 不应包含 menuList/permissionTree (重负载字段) + * - 必须保留 user / appCode / dbLinkId / tokenStatus (AI 工作流必读) + * + * v0.23+ (Task 9, webapi hardening): 加 --summary 模式, 减少 AI context window 占用 + */ +import { describe, expect, it } from 'vitest' +import { buildContextSummary } from '../../src/commands/app/_context_summary.ts' + +describe('app context --summary (Task 9a)', () => { + it('摘要模式不含完整 menuList/permissionTree', () => { + const full = { + appCode: 'tdd5', + systemId: '847', + dbLinkId: '208', + tokenStatus: 'ok', + user: { id: 'u1', account: 'admin' }, + menuList: Array(50).fill({ enCode: 'm' }), + permissionTree: { /* huge */ }, + warnings: [], + } + const summary = buildContextSummary(full) + expect(summary.appCode).toBe('tdd5') + expect(summary.dbLinkId).toBe('208') + expect(summary.tokenStatus).toBe('ok') + expect(summary).not.toHaveProperty('menuList') + expect(summary).not.toHaveProperty('permissionTree') + expect(summary).toHaveProperty('user') + }) + + it('warnings 保留 + 不超过 5 条', () => { + const full = { + warnings: Array(10).fill({ kind: 'x', message: 'y' }), + appCode: 'x', + systemId: 'y', + dbLinkId: 'z', + tokenStatus: 'ok', + user: { id: '1', account: 'a' }, + } as any + const s = buildContextSummary(full) + expect(s.warnings.length).toBeLessThanOrEqual(5) + }) +}) diff --git a/tests/unit/checkpoint_k_semantics.test.ts b/tests/unit/checkpoint_k_semantics.test.ts new file mode 100644 index 0000000..76055e9 --- /dev/null +++ b/tests/unit/checkpoint_k_semantics.test.ts @@ -0,0 +1,60 @@ +/** + * tests/unit/checkpoint_k_semantics.test.ts + * + * 覆盖 src/commands/_gates/_checkpoint_k.ts + * (webapi hardening: K 关卡 phase 感知 — 设计阶段 not-applicable, 总结阶段回查资源) + * + * 设计: + * - phase='design': summaryResources 为空 → not-applicable (退出 0) + * - phase='summary': summaryResources 全部 lookup 成功 → ok + * - phase='summary': 某资源 lookup 失败 → failure + 列出 missing + * + * v0.23+ (Task 9, webapi hardening): K 关卡 phase 语义修复, 防止总结阶段引用已删资源 + */ +import { describe, expect, it } from 'vitest' +import { checkKCheckpoint } from '../../src/commands/_gates/_checkpoint_k.ts' + +describe('K 关卡语义 (Task 9b)', () => { + it('设计阶段 (resources=[]) → not-applicable', async () => { + const r = await checkKCheckpoint({ + phase: 'design', + appCode: 'tdd5', + designResources: [], + summaryResources: [], + }) + expect(r.status).toBe('not-applicable') + expect(r.exitCode).toBe(0) + }) + + it('总结阶段有 summaryResources → 校验每个资源仍在', async () => { + const r = await checkKCheckpoint({ + phase: 'summary', + appCode: 'tdd5', + designResources: [], + summaryResources: [ + { kind: 'form', id: 'F1' }, + { kind: 'flow', id: 'W1' }, + { kind: 'menu', id: 'M1' }, + ], + liveLookup: async (res) => res.id, // 模拟 lookup + }) + expect(r.status).toBe('ok') + expect(r.exitCode).toBe(0) + }) + + it('总结阶段某资源 lookup 失败 → failure + 列出 missing', async () => { + const r = await checkKCheckpoint({ + phase: 'summary', + appCode: 'tdd5', + designResources: [], + summaryResources: [ + { kind: 'form', id: 'F1' }, + { kind: 'flow', id: 'MISSING' }, + ], + liveLookup: async (res) => (res.id === 'F1' ? 'F1' : null), + }) + expect(r.status).toBe('failure') + expect(r.exitCode).toBe(1) + expect(r.missing).toEqual([{ kind: 'flow', id: 'MISSING' }]) + }) +})