feat(gates): context summary + K checkpoint phase-aware (Task 9, webapi hardening)

- Add 'dacli app context --summary' for AI-friendly slim context (drops menuList/permissionTree, caps warnings at 5)
- Add src/commands/_gates/_checkpoint_k.ts: phase-aware gate (design=not-applicable, summary=live-lookup verify)
- 5 new unit tests (2 context summary, 3 K checkpoint)
This commit is contained in:
ssw committed 2026-07-28 20:26:11 +08:00
1 parent a8474cdb42
commit 5fb00ec6db
5 files changed
+218 -2

No files matched your search

+59
View File
@@ -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<string | null>
}
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<KResult> {
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 }
}
+39
View File
@@ -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,
}
}
+9 -2
View File
@@ -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 <appCode>', '覆盖 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',
+51
View File
@@ -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)
})
})
+60
View File
@@ -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' }])
})
})