diff --git a/scripts/seed-kb.ts b/scripts/seed-kb.ts new file mode 100644 index 0000000..4861020 --- /dev/null +++ b/scripts/seed-kb.ts @@ -0,0 +1,187 @@ +/** + * scripts/seed-kb.ts — 4 域初始数据 (非交互) + * + * 运行: cd dacli && npx tsx scripts/seed-kb.ts + * + * 幂等: 重复运行会清掉旧数据重建 (DELETE 域级联 entries/source_files) + * + * 4 域: dacli, jnpf, ssw-loop, ssw-e2e-test + * 条目数: 每域 12-16, 累计 ~55 + */ + +import { query, execute, transaction, close, SCHEMA } from '../src/commands/kb/_client.ts'; + +interface SeedDomain { + domain: string; + title: string; + tags: string[]; + keywords: string[]; + sources: string[]; + entries: Array<{ section: string; content: string; expiresOn?: string }>; +} + +const SEED: SeedDomain[] = [ + { + domain: 'dacli', + title: 'dacli CLI 工具 KB', + tags: ['dacli', 'cli', 'jnpf'], + keywords: ['dacli form create', 'dacli menu create', 'dacli webapi', 'dacli-ts skill'], + sources: [ + 'dacli/src/cli.ts', + 'dacli/docs/cmd-review/_summary.md', + 'dacli/docs/cmd-review/form.md', + 'dacli/docs/cmd-review/menu.md', + 'dacli/docs/cmd-review/workflow.md', + 'dacli/docs/cmd-review/dm.md', + '.claude/skills/dacli-ts/SKILL.md', + '.claude/skills/dacli-ts/references/commands.md', + '.claude/skills/dacli-ts/references/blindspots.md', + ], + entries: [ + { section: '业务背景', content: 'dacli 是 JNPF 平台 CLI 入口, 22 父命令/116 子命令, v0.14+ 镜像 web 端 (webapi/)' }, + { section: '关键决策', content: '**decision**: dacli form create --ai 用 NCPF backend (复用 JNPF AI 端点, 不需独立 LLM 配置)' }, + { section: '关键决策', content: '**decision**: dacli webapi 镜像架构 v0.11+ 落地, 0 复刻 web 端 (commit d4506fe)' }, + { section: '关键决策', content: '**decision**: ssw-common 提供 SSW 修复层, dacli 端优先 webapi, fallback 才走 ssw AI 修复端点' }, + { section: '踩坑教训', content: '**lesson**: form create AI 输出截断时失败 → ssw-common JsonRepairUtil 兜底 (BS-新30, commit 038bd98)' }, + { section: '踩坑教训', content: '**lesson**: webapi visualDev.ts import 替换 #/api/request → _defhttp_shim.ts' }, + { section: '踩坑教训', content: '**lesson**: form create 简版 --fields 缺 use*Permission 关键字段 → "Database exception" (BS-48)' }, + { section: '踩坑教训', content: '**lesson**: form create 失败残留 enCode → "Encoding cannot be repeated" (BS-49), 解: 加 _v2 后缀或 form delete 重建' }, + { section: '踩坑教训', content: '**lesson**: menu create --formId 缺主表时走低级模式 --type=3 --urlAddress=model/{enCode} (BS-50)' }, + { section: '踩坑教训', content: '**lesson**: dm list 报 400 "Database connection failed" → dacli app init -- --appCode=X --force-rebuild --restart (BS-C.5.8)' }, + { section: '复用清单', content: 'dacli form create --ai "<描述>" --autoRelease 端到端建表+发布 (v0.13+ 推荐, BS-新28 后唯一推荐路径)' }, + { section: '复用清单', content: 'dacli menu create --formId= --type=3 --urlAddress=model/ (BS-50 fallback)' }, + { section: '复用清单', content: 'dacli dict dataList 看已有字典, 新建走 enCode/fullName 复检避免 BS-47' }, + { section: '对应技术架构', content: '模块: dacli/src/commands/{form,menu,dm,di,...}; webapi/_loader.ts; webapi/visualDev.ts' }, + ], + }, + { + domain: 'jnpf', + title: 'JNPF 平台基线 KB', + tags: ['jnpf', 'platform', 'baseline'], + keywords: ['scanBasePackages', 'TemplateCodeVue3', 'ServiceImpMarco', 'MybatisPlusConfig'], + sources: [ + '.claude/CLAUDE.md', + 'jnpf/后端/jnpf-java-boot/jnpf-admin/src/main/java/jnpf/JnpfAdminApplication.java', + 'jnpf/静态资源/jnpf-resources/TemplateCodeVue3/PublicMacro/ServiceImpMarco.vm', + 'dacli/docs/web-patches/_jnpf-admin-scanBasePackages-ssw.md', + 'dacli/docs/web-patches/_codegen-ServiceImpMarco-virtual-field.md', + ], + entries: [ + { section: '业务背景', content: 'JNPF 是低代码平台, jnpf/ 目录是官方源代码 (只读), 业务行为调整走 boot/ssw-common/ 扩展层' }, + { section: '关键决策', content: '**decision**: 业务行为调整走 boot/ssw-common/ 扩展层, 不改 jnpf 源码 (CLAUDE.md §代码修改权限)' }, + { section: '关键决策', content: '**decision**: @SpringBootApplication scanBasePackages 加 \'ssw\' 才能扫到 ssw-common bean (BS-14 集中化后由 SswMapperConfig 接管)' }, + { section: '关键决策', content: '**decision**: MybatisPlusConfig @MapperScan 只扫 jnpf.*.mapper / jnpf.mapper / xxl.mapper, 不扫 ssw.*.mapper' }, + { section: '踩坑教训', content: '**lesson**: JNPF 升级几乎每次覆盖 JnpfAdminApplication.java, scanBasePackages 必须重新应用 (web-patches/_jnpf-admin-scanBasePackages-ssw.md)' }, + { section: '踩坑教训', content: '**lesson**: ServiceImpMarco.vm 虚拟字段 (searchList 不在主表) 会输出字面 ${} 到 Java → javac 失败' }, + { section: '踩坑教训', content: '**lesson**: jnpf-common-ai/SendAiMessage.java:148 硬编码 maxTokens=1500 且不修复 LLM 输出 → ssw-common JsonRepairUtil + SswLLMClient + AIRepairService 兜底' }, + { section: '踩坑教训', content: '**lesson**: 表名 f_version 是系统关键字, 禁止使用 (CLAUDE.md §3)' }, + { section: '踩坑教训', content: '**lesson**: 类名 PascalCase 不重复 appCode, 包名已带; web/uniapp 文件名小写' }, + { section: '复用清单', content: 'Java 8 only, 禁止 var/records/text blocks (CLAUDE.md §8)' }, + { section: '复用清单', content: 'Ant Design Vue only, 禁止 Element Plus (CLAUDE.md §7)' }, + { section: '复用清单', content: '业务行为调整走 ssw-common-biz/util/service + ssw-common-controller /api/ssw/... 暴露端点' }, + { section: '对应技术架构', content: 'jnpf 模块: jnpf-common-ai/SendAiMessage.java:148, jnpf-resources/TemplateCodeVue3/PublicMacro/ServiceImpMarco.vm' }, + { section: '对应技术架构', content: '扩展层: boot/ssw-common/ssw-common-biz/config/SswMapperConfig.java + ssw-common-ai/JsonRepairUtil' }, + ], + }, + { + domain: 'ssw-loop', + title: 'ssw-loop 开发循环 KB', + tags: ['ssw-loop', 'workflow', 'process'], + keywords: ['7 阶段', '4 关卡 CI', '子代理派发', 'HTML 产物'], + sources: [ + '.claude/skills/ssw-loop/SKILL.md', + '.claude/skills/ssw-loop/references/stages.md', + '.claude/skills/ssw-loop/references/lessons-from-apps.md', + '.claude/skills/ssw-loop/references/anti-patterns.md', + '.claude/skills/ssw-loop/references/html-assets-rules.md', + '.claude/skills/ssw-loop/references/stage-prompts.md', + '.claude/skills/ssw-loop/references/dacli-doc-pattern.md', + '.claude/skills/ssw-loop/references/subagent-must-do.md', + ], + entries: [ + { section: '业务背景', content: 'ssw-loop 是 JNPF 应用的 H5 开发主流程, 7 阶段 + 4 关卡 CI (init→design→review→execute→test→summary→iterate)' }, + { section: '关键决策', content: '**decision**: 阶段 7.2 用真实业务数据 CRUD, 不接受 test fixture (BS-109~111)' }, + { section: '关键决策', content: '**decision**: HTML 产物放 docs/{app}/, 不入 git (CI 关卡 G 警告)' }, + { section: '关键决策', content: '**decision**: 零应用信息硬编码, 所有上下文通过 dacli app context --json / dacli form info 动态获取' }, + { section: '关键决策', content: '**decision**: 主 SKILL.md 只保留规则/用法, 详细参考放 references/ (SKILL.md > 800 行 → 抽出低频内容)' }, + { section: '踩坑教训', content: '**lesson**: 子代理派发要给出完整上下文, 否则盲点扩散 (anti-patterns.md §2.6)' }, + { section: '踩坑教训', content: '**lesson**: 应用特定信息(form ID / 菜单结构 / DB 凭证 / 字段名)写 docs/{app_code}/ 不入 CLAUDE.md / skill' }, + { section: '踩坑教训', content: '**lesson**: 复现的盲点先在测试场 (testspace) 跑通验证, 再固化到 dacli / skill, 禁止用 developSystem/workSystem 验证' }, + { section: '踩坑教训', content: '**lesson**: AI prompt 是 JSON 生成器, JSON 是契约 (MEMORY ai-prompt-is-just-json-generator)' }, + { section: '踩坑教训', content: '**lesson**: 改 web 端 Vue 组件要保存到 dacli/docs/web-patches/.md (MEMORY feedback-web-patch-docs)' }, + { section: '复用清单', content: 'dacli form create + menu create + di create 一气呵成, 不手写 schema' }, + { section: '复用清单', content: '派子代理前给完整上下文: appCode + dbLinkId + existingEnCodes + 关键 skill 路径' }, + { section: '复用清单', content: 'HTML 产物: docs/{app}/{design|testcase|plan|debug|summary}.html + assets/' }, + { section: '对应技术架构', content: '7 阶段: init → design → review → execute → test → summary → iterate; 4 关卡 CI: A/B/C/D' }, + ], + }, + { + domain: 'ssw-e2e-test', + title: 'ssw-e2e-test 测试模式 KB', + tags: ['e2e', 'playwright', 'testing'], + keywords: ['TC-A', 'TC-B', 'webapi', 'real-data'], + sources: [ + '.claude/skills/ssw-e2e-test/SKILL.md', + '.claude/skills/ssw-e2e-test/references/tc-ab-real-test.md', + ], + entries: [ + { section: '业务背景', content: 'ssw-e2e-test 是 Playwright + dacli 的端到端测试 skill, TC-A/B/C 分级' }, + { section: '关键决策', content: '**decision**: TC-B 构造/查找/触发/注入走 webapi (快), 验证走浏览器 (真实) (MEMORY feedback-tc-b-webapi-setup)' }, + { section: '关键决策', content: '**decision**: test fixture 不能当业务验证, 必须真实数据 (dacli-test-run-real-data-upgrade-2026-06-28)' }, + { section: '关键决策', content: '**decision**: 默认 ON real-data + keep-data + 关联表真实 ID lookup + 跨表 join + 业务规则' }, + { section: '踩坑教训', content: '**lesson**: test fixture 当业务验证 → 后续真实场景全失败 (BS-109)' }, + { section: '踩坑教训', content: '**lesson**: 不重复已有基础设施 (MEMORY feedback-no-duplicate-infra)' }, + { section: '踩坑教训', content: '**lesson**: API 替换必须服务 AI 痛点, 不为替换而替换 (MEMORY feedback-api-replace-must-serve-ai)' }, + { section: '复用清单', content: 'TC-B 复用 webapi 镜像能力, 跨表 join, 关联表真实 ID lookup' }, + { section: '复用清单', content: 'webapi 构造数据 + 浏览器验证两步走, 测试快且真实' }, + { section: '复用清单', content: 'playwright Node.js: cd $ccWorkDir/test && npx playwright test --project=chromium' }, + { section: '对应技术架构', content: 'TC-A: 浏览器纯操作; TC-B: webapi 构造 + 浏览器验证; TC-C: 跨进程多端协同' }, + { section: '对应技术架构', content: 'webapi 模块: webapi/_loader.ts (动态加载 web 端模块), webapi/visualDev.ts (form schema 生成)' }, + ], + }, +]; + +async function seed() { + console.log(`Seeding ${SEED.length} domains into ${SCHEMA}...\n`); + + await transaction(async (client) => { + // 1. 清旧 seed 数据 (幂等) + for (const s of SEED) { + await client.query(`DELETE FROM ${SCHEMA}.domains WHERE domain = $1`, [s.domain]); + } + console.log('✓ Cleared old seed data\n'); + + // 2. 插 4 域 + source_files + entries + for (const s of SEED) { + const { rows: [d] } = await client.query<{ id: number }>( + `INSERT INTO ${SCHEMA}.domains (domain, title, tags, keywords) VALUES ($1, $2, $3, $4) RETURNING id`, + [s.domain, s.title, s.tags, s.keywords] + ); + console.log(`✓ Domain '${s.domain}' (id=${d.id}) — ${s.entries.length} entries, ${s.sources.length} sources`); + + for (const path of s.sources) { + await client.query( + `INSERT INTO ${SCHEMA}.source_files (domain_id, path, kind) VALUES ($1, $2, 'source')`, + [d.id, path] + ); + } + + for (let i = 0; i < s.entries.length; i++) { + const e = s.entries[i]; + await client.query( + `INSERT INTO ${SCHEMA}.entries (domain_id, section, content, sort_order, expires_on) + VALUES ($1, $2, $3, $4, $5)`, + [d.id, e.section, e.content, i, e.expiresOn || null] + ); + } + } + }); + + console.log(`\n=== Seeded ${SEED.length} domains, ${SEED.reduce((s, d) => s + d.entries.length, 0)} entries ===`); + await close(); +} + +seed().catch(e => { + console.error('✗ Seed failed:', e); + process.exit(1); +}); \ No newline at end of file diff --git a/src/commands/kb/add.ts b/src/commands/kb/add.ts index 2b12ba6..e14b2c4 100644 --- a/src/commands/kb/add.ts +++ b/src/commands/kb/add.ts @@ -7,7 +7,8 @@ function ask(rl: readline.Interface, q: string): Promise { } export function buildKbAddCommand(): Command { - return new Command('add ') + return new Command('add') + .argument('', 'Domain name (e.g. dacli)') .description('Add a new KB domain (interactive)') .action(async (domain: string) => { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); diff --git a/src/commands/kb/archive.ts b/src/commands/kb/archive.ts index d714c78..ac85718 100644 --- a/src/commands/kb/archive.ts +++ b/src/commands/kb/archive.ts @@ -2,7 +2,8 @@ import { Command } from 'commander'; import { execute, SCHEMA } from './_client.ts'; export function buildKbArchiveCommand(): Command { - return new Command('archive ') + return new Command('archive') + .argument('', 'Entry id') .description('Archive an entry (hidden from active_entries view)') .option('-r, --reason ', 'Archive reason') .action(async (id: string, opts: any) => { diff --git a/src/commands/kb/audit.ts b/src/commands/kb/audit.ts index c11ae91..deef926 100644 --- a/src/commands/kb/audit.ts +++ b/src/commands/kb/audit.ts @@ -2,7 +2,8 @@ import { Command } from 'commander'; import { query, SCHEMA } from './_client.ts'; export function buildKbAuditCommand(): Command { - return new Command('audit [type]') + return new Command('audit') + .argument('[type]', 'Audit type', 'stale') .description('Audit KB health (type: stale, default)') .action(async (type: string = 'stale') => { if (type !== 'stale') { diff --git a/src/commands/kb/deprecate.ts b/src/commands/kb/deprecate.ts index 19a040e..33c2087 100644 --- a/src/commands/kb/deprecate.ts +++ b/src/commands/kb/deprecate.ts @@ -2,7 +2,8 @@ import { Command } from 'commander'; import { execute, SCHEMA } from './_client.ts'; export function buildKbDeprecateCommand(): Command { - return new Command('deprecate ') + return new Command('deprecate') + .argument('', 'Entry id (the one being deprecated)') .description('Deprecate an entry (link to replacement)') .requiredOption('-r, --replaced-by ', 'New entry id that replaces this') .option('--reason ', 'Deprecation reason') diff --git a/src/commands/kb/entry.ts b/src/commands/kb/entry.ts index f3abc01..bdbc147 100644 --- a/src/commands/kb/entry.ts +++ b/src/commands/kb/entry.ts @@ -7,7 +7,8 @@ function ask(rl: readline.Interface, q: string): Promise { } export function buildKbEntryCommand(): Command { - return new Command('entry ') + return new Command('entry') + .argument('', 'Domain name') .description('Add an entry to a domain (interactive)') .option('-s, --section
', 'Section name', '关键决策') .option('-c, --content ', 'Content (markdown)') diff --git a/src/commands/kb/expire.ts b/src/commands/kb/expire.ts index bcd5e78..8fbffa4 100644 --- a/src/commands/kb/expire.ts +++ b/src/commands/kb/expire.ts @@ -2,7 +2,8 @@ import { Command } from 'commander'; import { execute, SCHEMA } from './_client.ts'; export function buildKbExpireCommand(): Command { - return new Command('expire ') + return new Command('expire') + .argument('', 'Entry id') .description('Set expiry date on an entry') .requiredOption('-o, --on ', 'Expiry date (YYYY-MM-DD)') .action(async (id: string, opts: any) => { diff --git a/src/commands/kb/remove.ts b/src/commands/kb/remove.ts index 082aaaf..3464165 100644 --- a/src/commands/kb/remove.ts +++ b/src/commands/kb/remove.ts @@ -2,7 +2,8 @@ import { Command } from 'commander'; import { execute, SCHEMA } from './_client.ts'; export function buildKbRemoveCommand(): Command { - return new Command('remove ') + return new Command('remove') + .argument('', 'Entry id') .alias('rm') .description('Permanently delete an entry') .option('-f, --force', 'Skip confirmation') diff --git a/src/commands/kb/renew.ts b/src/commands/kb/renew.ts index f107d2a..6fe6d8b 100644 --- a/src/commands/kb/renew.ts +++ b/src/commands/kb/renew.ts @@ -2,7 +2,8 @@ import { Command } from 'commander'; import { execute, SCHEMA } from './_client.ts'; export function buildKbRenewCommand(): Command { - return new Command('renew ') + return new Command('renew') + .argument('', 'Entry id') .description('Update last_reviewed = NOW() (reset staleness timer)') .action(async (id: string) => { const n = await execute( diff --git a/src/commands/kb/search.ts b/src/commands/kb/search.ts index cbdca08..e8f6f6b 100644 --- a/src/commands/kb/search.ts +++ b/src/commands/kb/search.ts @@ -2,7 +2,8 @@ import { Command } from 'commander'; import { search } from './_search.ts'; export function buildKbSearchCommand(): Command { - return new Command('search ') + return new Command('search') + .argument('', 'Search query string') .description('Full-text search via tsvector (BM25-like ranking)') .option('-d, --domain ', 'Filter by domain') .option('-l, --limit ', 'Limit results', '10') diff --git a/src/commands/kb/show.ts b/src/commands/kb/show.ts index 3fd3201..bfd7133 100644 --- a/src/commands/kb/show.ts +++ b/src/commands/kb/show.ts @@ -2,7 +2,8 @@ import { Command } from 'commander'; import { query, SCHEMA } from './_client.ts'; export function buildKbShowCommand(): Command { - return new Command('show ') + return new Command('show') + .argument('', 'Domain name (e.g. dacli)') .description('Show full KB content for a domain') .action(async (domain: string) => { const meta = await query( diff --git a/src/commands/kb/update.ts b/src/commands/kb/update.ts index b9ca41e..71c1d3a 100644 --- a/src/commands/kb/update.ts +++ b/src/commands/kb/update.ts @@ -2,7 +2,8 @@ import { Command } from 'commander'; import { execute, SCHEMA } from './_client.ts'; export function buildKbUpdateCommand(): Command { - return new Command('update ') + return new Command('update') + .argument('', 'Entry id') .description('Update entry content/section') .option('-s, --section
', 'New section') .option('-c, --content ', 'New content')