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:
1 parent
a8474cdb42
commit
5fb00ec6db
5 files changed
+218
-2
No files matched your search
@@ -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 }
|
||||
}
|
||||
@@ -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,
|
||||
}
|
||||
}
|
||||
@@ -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',
|
||||
|
||||
@@ -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)
|
||||
})
|
||||
})
|
||||
@@ -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' }])
|
||||
})
|
||||
})
|
||||
Reference in new issue
Block a user