diff --git a/src/core/help.ts b/src/core/help.ts index 7e2c521..504fff3 100644 --- a/src/core/help.ts +++ b/src/core/help.ts @@ -14,10 +14,12 @@ export interface DacliHelp { example?: string | string[] source?: { web?: string; api?: string; ref?: string } - /** 反模式: ❌ 错 / ✅ 对 配对 */ + /** 反模式: ❌ 错 / → 理由 / ✅ 对 三段式 (AI 学习用的关键知识) */ pitfalls?: Array<{ wrong: string right: string + /** 1-2 句解释: 为什么错的方式有问题 — 这是 AI 学习的核心知识 */ + rationale?: string severity?: 'P0' | 'P1' | 'P2' }> @@ -41,6 +43,9 @@ export type AiHelp = DacliHelp * 渲染 DacliHelp 为 Commander addHelpText('after', ...) 可接受的字符串. * 包含 4 新段: Pitfalls / Best Practices / Decision Tree / Related Refs. * 也渲染 example / source / notes (legacy) 段. + * + * Note: `help.purpose` is NOT rendered here — it is intended for Commander's + * `.description(help.purpose)` call, which commands should make separately. */ export function renderDacliHelp(help: DacliHelp): string { const sections: string[] = [] @@ -67,6 +72,9 @@ export function renderDacliHelp(help: DacliHelp): string { for (const p of help.pitfalls) { const sev = p.severity ? ` [${p.severity}]` : '' sections.push(` ❌ ${p.wrong}${sev}`) + if (p.rationale) { + sections.push(` → ${p.rationale.replace(/\n/g, '\n ')}`) + } sections.push(` ✅ ${p.right.replace(/\n/g, '\n ')}`) sections.push('') } diff --git a/tests/core/help.spec.ts b/tests/core/help.spec.ts index a5f5a35..90cfafd 100644 --- a/tests/core/help.spec.ts +++ b/tests/core/help.spec.ts @@ -66,3 +66,28 @@ describe('renderDacliHelp', () => { expect(out).not.toContain('Related Refs') }) }) + +describe('renderDacliHelp pitfalls rationale', () => { + it('should render rationale as intermediate → line when provided', () => { + const out = renderDacliHelp({ + purpose: 'Create a form', + pitfalls: [{ + wrong: 'wrong way', + right: 'right way', + rationale: 'AI defaults to wrong', + severity: 'P0', + }], + }) + expect(out).toContain('→ AI defaults to wrong') + expect(out).toContain('❌ wrong way [P0]') + expect(out).toContain('✅ right way') + }) + + it('should omit rationale line when not provided', () => { + const out = renderDacliHelp({ + purpose: 'Create a form', + pitfalls: [{ wrong: 'wrong', right: 'right', severity: 'P0' }], + }) + expect(out).not.toContain('→') + }) +})