feat(dacli): render pitfalls rationale + clarify purpose JSDoc

This commit is contained in:
ssw committed 2026-07-16 17:07:46 +08:00
1 parent 319221148b
commit cfa3135986
2 files changed
+34 -1

No files matched your search

+9 -1
View File
@@ -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('')
}
+25
View File
@@ -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('→')
})
})