# dacli KB (PostgreSQL) — 实施计划 > 来源: 用户会话 2026-07-02 多轮迭代, 已批准 > 本文档是**自包含实施手册**, 执行者无需历史对话上下文即可实施 ## 0. 背景 **目标**: 给 dacli 装一个"大脑" (KB), 文档直接入 PostgreSQL, 通过 `dacli kb` 命令操作, 自动日期/过期/检索过滤, 避免文件系统散落过时 Markdown 干扰 AI 检索。 **核心范式**: - 文档**不写**到文件系统, 直接入 PostgreSQL - 自动日期戳 (created_on / last_reviewed) - 自动过期 (expires_on + status='archived') - 检索自动过滤 (active_entries 视图) - 陈旧自动检测 (stale_candidates 视图) **基础设施**: 复用用户已有 pg 容器 (`PGHOST=postgres`, PGPORT=5432, PGUSER=ssw, PGDATABASE=ssw`), 表放 `ssw_kb` schema 隔离。 **4 个技术基础设施域** (本期初始化, 无业务信息): 1. **dacli** — CLI 工具 (命令/架构/盲点) 2. **jnpf** — 平台基线 (约束/机制) 3. **ssw-loop** — 开发循环 (7 阶段/4 关卡) 4. **ssw-e2e-test** — 测试模式 (TC-A/B) --- ## 1. 实施前环境检查 ### 1.1 pg 容器可达性 ```bash # 试多种连接方式 PGPASSWORD=ssw123456 psql -h postgres -U ssw -d ssw -c "SELECT version();" 2>&1 # 或 PGPASSWORD=ssw123456 psql -h localhost -U ssw -d ssw -c "SELECT version();" 2>&1 ``` **期望**: PostgreSQL version 信息, 类似 `PostgreSQL 16.x ...` **失败处理**: - 找不到 `psql`: 跳过 (pg 客户端是 `node-postgres`, 不依赖 psql) - 连接失败: 检查 `PGHOST`/`PGUSER`/`PGPASSWORD`/`PGDATABASE` 环境变量 ### 1.2 dacli 现状 ```bash cd /home/ubuntu/ccWorkDir/dacli ls src/commands/ # 应有 form/, menu/, dm/, di/, ... 等 cat package.json | grep -A 5 '"dependencies"' ``` **期望**: 已有 `form/`, `menu/` 等命令目录, dependencies 含 `tsx`, `commander`, `axios` 等 ### 1.3 dacli CLI 注册位置 ```bash cat src/cli.ts | head -50 ``` **期望**: 看到现有命令注册, 了解 `program.command(...).description(...)` 模式 --- ## 2. Commit 1: pg 客户端 + schema + init 命令 ### 2.1 文件清单 | 路径 | 动作 | 内容 | |------|------|------| | `dacli/src/commands/kb/_client.ts` | 新建 | pg Pool + query/execute/transaction/trackAccess | | `dacli/src/commands/kb/_schema.ts` | 新建 | PostgreSQL DDL (4 表 + 触发器 + 2 视图) | | `dacli/src/commands/kb/_init.ts` | 新建 | `dacli kb init` 命令 | | `dacli/.env.example` | 编辑 | 追加 PG* + KB_SCHEMA 配置 | | `dacli/package.json` | 编辑 | 加 `pg` 依赖 | ### 2.2 `_client.ts` 完整代码 ```typescript /** * _client.ts — PostgreSQL 客户端 (dacli KB) * * 设计: pg Pool 单例, 自动从环境变量读取连接信息 * 表放 ssw_kb schema 隔离 (避免污染主库) */ import { Pool, PoolClient } from 'pg'; const SCHEMA = process.env.KB_SCHEMA || 'ssw_kb'; const pool = new Pool({ host: process.env.PGHOST || 'postgres', port: parseInt(process.env.PGPORT || '5432'), user: process.env.PGUSER || 'ssw', password: process.env.PGPASSWORD || '', database: process.env.PGDATABASE || 'ssw', max: 10, idleTimeoutMillis: 30000, }); export { SCHEMA }; /** 执行查询 (SELECT) */ export async function query(sql: string, params: any[] = []): Promise { const { rows } = await pool.query(sql, params); return rows as T[]; } /** 执行写操作 (INSERT/UPDATE/DELETE) */ export async function execute(sql: string, params: any[] = []): Promise { const result = await pool.query(sql, params); return result.rowCount ?? 0; } /** 批量更新访问计数 (search 后调用) */ export async function trackAccess(entryIds: (number | bigint)[]): Promise { if (entryIds.length === 0) return; await pool.query( `UPDATE ${SCHEMA}.entries SET access_count = access_count + 1, last_accessed = NOW() WHERE id = ANY($1::bigint[])`, [entryIds] ); } /** 事务 (多语句原子) */ export async function transaction( fn: (client: PoolClient) => Promise ): Promise { const client = await pool.connect(); try { await client.query('BEGIN'); const result = await fn(client); await client.query('COMMIT'); return result; } catch (e) { await client.query('ROLLBACK'); throw e; } finally { client.release(); } } /** 健康检查 */ export async function ping(): Promise { try { await pool.query('SELECT 1'); return true; } catch { return false; } } /** 关闭连接 (进程退出时调用) */ export async function close(): Promise { await pool.end(); } ``` ### 2.3 `_schema.ts` 完整代码 ```typescript /** * _schema.ts — PostgreSQL KB Schema (4 表 + 1 触发器 + 2 视图) * * ssw_kb schema 隔离, 不污染主库 * 自动特性: * - created_on / last_reviewed 自动 NOW() * - search_vector 触发器自动维护 (tsvector) * - active_entries 视图自动过滤过期 * - stale_candidates 视图自动检测陈旧 (90 天 + 0 访问) */ import { SCHEMA } from './_client'; export const SCHEMA_DDL = [ `CREATE SCHEMA IF NOT EXISTS ${SCHEMA}`, // 1. 域 `CREATE TABLE IF NOT EXISTS ${SCHEMA}.domains ( id BIGSERIAL PRIMARY KEY, domain TEXT UNIQUE NOT NULL, title TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'active', created_on TIMESTAMPTZ NOT NULL DEFAULT NOW(), last_reviewed TIMESTAMPTZ NOT NULL DEFAULT NOW(), tags TEXT[], keywords TEXT[] )`, // 2. 源文件映射 `CREATE TABLE IF NOT EXISTS ${SCHEMA}.source_files ( id BIGSERIAL PRIMARY KEY, domain_id BIGINT NOT NULL REFERENCES ${SCHEMA}.domains(id) ON DELETE CASCADE, path TEXT NOT NULL, kind TEXT NOT NULL DEFAULT 'source' )`, // 3. 条目 (核心) `CREATE TABLE IF NOT EXISTS ${SCHEMA}.entries ( id BIGSERIAL PRIMARY KEY, domain_id BIGINT NOT NULL REFERENCES ${SCHEMA}.domains(id) ON DELETE CASCADE, section TEXT NOT NULL, content TEXT NOT NULL, sort_order INTEGER DEFAULT 0, created_on TIMESTAMPTZ NOT NULL DEFAULT NOW(), last_reviewed TIMESTAMPTZ NOT NULL DEFAULT NOW(), expires_on TIMESTAMPTZ, status TEXT NOT NULL DEFAULT 'active', access_count INTEGER NOT NULL DEFAULT 0, last_accessed TIMESTAMPTZ, search_vector tsvector )`, // 4. 替换关系 `CREATE TABLE IF NOT EXISTS ${SCHEMA}.replacements ( old_entry_id BIGINT PRIMARY KEY REFERENCES ${SCHEMA}.entries(id) ON DELETE CASCADE, new_entry_id BIGINT NOT NULL REFERENCES ${SCHEMA}.entries(id) ON DELETE CASCADE, replaced_on TIMESTAMPTZ NOT NULL DEFAULT NOW(), reason TEXT )`, // 索引 `CREATE INDEX IF NOT EXISTS idx_entries_domain ON ${SCHEMA}.entries(domain_id)`, `CREATE INDEX IF NOT EXISTS idx_entries_status ON ${SCHEMA}.entries(status)`, `CREATE INDEX IF NOT EXISTS idx_entries_expires ON ${SCHEMA}.entries(expires_on)`, `CREATE INDEX IF NOT EXISTS idx_entries_search ON ${SCHEMA}.entries USING GIN(search_vector)`, `CREATE UNIQUE INDEX IF NOT EXISTS idx_domains_domain ON ${SCHEMA}.domains(domain)`, // tsvector 触发器函数 `CREATE OR REPLACE FUNCTION ${SCHEMA}.entries_search_trigger() RETURNS trigger AS $$ BEGIN NEW.search_vector := setweight(to_tsvector('simple', COALESCE(NEW.content, '')), 'A') || setweight(to_tsvector('simple', COALESCE(NEW.section, '')), 'B'); RETURN NEW; END $$ LANGUAGE plpgsql`, `DROP TRIGGER IF EXISTS entries_search_update ON ${SCHEMA}.entries`, `CREATE TRIGGER entries_search_update BEFORE INSERT OR UPDATE ON ${SCHEMA}.entries FOR EACH ROW EXECUTE FUNCTION ${SCHEMA}.entries_search_trigger()`, // 视图: 活跃条目 (自动过滤过期) `CREATE OR REPLACE VIEW ${SCHEMA}.active_entries AS SELECT e.*, d.domain, d.title AS domain_title FROM ${SCHEMA}.entries e JOIN ${SCHEMA}.domains d ON d.id = e.domain_id WHERE e.status = 'active' AND (e.expires_on IS NULL OR e.expires_on > NOW())`, // 视图: 陈旧候选 (90 天未审查 + 0 访问) `CREATE OR REPLACE VIEW ${SCHEMA}.stale_candidates AS SELECT e.*, d.domain, d.title AS domain_title, EXTRACT(EPOCH FROM (NOW() - e.last_reviewed)) / 86400.0 AS days_since_review FROM ${SCHEMA}.entries e JOIN ${SCHEMA}.domains d ON d.id = e.domain_id WHERE e.status = 'active' AND NOW() - e.last_reviewed > INTERVAL '90 days' AND (e.access_count = 0 OR e.last_accessed < e.last_reviewed)`, ]; ``` ### 2.4 `_init.ts` 完整代码 ```typescript /** * _init.ts — `dacli kb init` 命令 * * 首次启动时建 ssw_kb schema (4 表 + 1 触发器 + 2 视图) * 幂等: 可重复运行 */ import { Command } from 'commander'; import { query, SCHEMA } from './_client'; import { SCHEMA_DDL } from './_schema'; export function registerInit(program: Command) { program .command('init') .description(`Initialize ${SCHEMA} schema (idempotent)`) .action(async () => { console.log(`Initializing schema '${SCHEMA}'...`); try { for (const sql of SCHEMA_DDL) { await query(sql); } // 验证 const tables = await query<{ table_name: string }>( `SELECT table_name FROM information_schema.tables WHERE table_schema = $1 ORDER BY table_name`, [SCHEMA] ); const triggers = await query<{ trigger_name: string }>( `SELECT trigger_name FROM information_schema.triggers WHERE trigger_schema = $1`, [SCHEMA] ); const views = await query<{ table_name: string }>( `SELECT table_name FROM information_schema.views WHERE table_schema = $1 ORDER BY table_name`, [SCHEMA] ); console.log(`✓ Schema '${SCHEMA}' initialized:`); console.log(` - Tables (${tables.length}): ${tables.map(t => t.table_name).join(', ')}`); console.log(` - Triggers (${triggers.length}): ${triggers.map(t => t.trigger_name).join(', ')}`); console.log(` - Views (${views.length}): ${views.map(v => v.table_name).join(', ')}`); } catch (e: any) { console.error(`✗ Init failed: ${e.message}`); process.exit(1); } }); } ``` ### 2.5 `.env.example` 追加 ```bash # === dacli KB (PostgreSQL backend) === # 复用已有 pg 容器, schema 隔离 PGHOST=postgres PGPORT=5432 PGUSER=ssw PGPASSWORD= PGDATABASE=ssw KB_SCHEMA=ssw_kb ``` ### 2.6 `package.json` 追加依赖 ```json { "dependencies": { "pg": "^8.11.0", ... } } ``` 执行 `cd /home/ubuntu/ccWorkDir/dacli && npm install` ### 2.7 Commit 1 提交 ```bash cd /home/ubuntu/ccWorkDir/dacli git add src/commands/kb/_client.ts src/commands/kb/_schema.ts src/commands/kb/_init.ts .env.example package.json package-lock.json git commit -m "dacli(kb): pg 客户端 + ssw_kb schema + init 命令 (commit 1/3) - src/commands/kb/_client.ts: pg Pool 单例, query/execute/transaction/trackAccess - src/commands/kb/_schema.ts: 4 表 + 1 触发器 + 2 视图 (active_entries / stale_candidates) - src/commands/kb/_init.ts: 'dacli kb init' 命令, 幂等建表 - .env.example: 追加 PG* + KB_SCHEMA 配置 - package.json: 加 pg ^8.11.0 依赖 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude " git push origin main ``` ### 2.8 Commit 1 验证 ```bash cd /home/ubuntu/ccWorkDir/dacli export PGHOST=postgres PGPORT=5432 PGUSER=ssw PGPASSWORD=<实际密码> PGDATABASE=ssw npx tsx src/cli.ts kb init # 期望: "Schema 'ssw_kb' initialized: Tables (4): ... Triggers (1): ... Views (2): ..." ``` --- ## 3. Commit 2: 16 个 kb 命令 ### 3.1 文件清单 | 路径 | 动作 | 命令 | |------|------|------| | `src/commands/kb/_search.ts` | 新建 | 检索封装 (含访问计数) | | `src/commands/kb/list.ts` | 新建 | `kb list` | | `src/commands/kb/show.ts` | 新建 | `kb show ` | | `src/commands/kb/search.ts` | 新建 | `kb search ` | | `src/commands/kb/map.ts` | 新建 | `kb map` | | `src/commands/kb/audit.ts` | 新建 | `kb audit [stale\|renew]` | | `src/commands/kb/add.ts` | 新建 | `kb add ` | | `src/commands/kb/entry.ts` | 新建 | `kb entry ` | | `src/commands/kb/update.ts` | 新建 | `kb update ` | | `src/commands/kb/remove.ts` | 新建 | `kb remove ` | | `src/commands/kb/expire.ts` | 新建 | `kb expire ` | | `src/commands/kb/renew.ts` | 新建 | `kb renew ` | | `src/commands/kb/archive.ts` | 新建 | `kb archive ` | | `src/commands/kb/deprecate.ts` | 新建 | `kb deprecate ` | | `src/commands/kb/rebuild-fts.ts` | 新建 | `kb rebuild-fts` | | `src/commands/kb/serve.ts` | 新建 | `kb serve` (REST wrapper, 可选) | | `src/commands/kb/index.ts` | 新建 | 统一注册 (kb 父命令) | | `src/cli.ts` | 编辑 | 注册 `kb` 子命令 | ### 3.2 `_search.ts` 检索封装 ```typescript /** * _search.ts — tsvector 检索 + 访问计数 * * 自动: * - 默认仅返回 active (status='active' AND 未过期) * - 命中后自动更新 access_count + last_accessed * - ts_headline 生成 高亮 snippet */ import { query, trackAccess, SCHEMA } from './_client'; export interface SearchOptions { query: string; domain?: string; // 域过滤 includeAll?: boolean; // 含过期/archived limit?: number; } export interface SearchResult { id: number; domain: string; section: string; content: string; rank: number; snippet: string; } export async function search(opts: SearchOptions): Promise { const limit = opts.limit ?? 10; const tsquery = opts.query .split(/\s+/) .filter(Boolean) .map(t => t.replace(/[^\w一-龥-]/g, '')) .filter(Boolean) .join(' & '); if (!tsquery) return []; const useActiveView = !opts.includeAll; const source = useActiveView ? `${SCHEMA}.active_entries` : `${SCHEMA}.entries`; let sql = ` SELECT e.id, d.domain, e.section, e.content, ts_rank(e.search_vector, query) AS rank, ts_headline('simple', e.content, query, 'StartSel=, StopSel=, MaxFragments=2, MaxWords=20, MinWords=5') AS snippet FROM ${source} e JOIN ${SCHEMA}.domains d ON d.id = e.domain_id, to_tsquery('simple', $1) query WHERE e.search_vector @@ query `; const params: any[] = [tsquery]; if (opts.domain) { sql += ` AND d.domain = $2`; params.push(opts.domain); } sql += ` ORDER BY rank DESC LIMIT $${params.length + 1}`; params.push(limit); const rows = await query(sql, params); // 自动更新访问计数 if (rows.length > 0) { await trackAccess(rows.map(r => r.id)); } return rows; } ``` ### 3.3 `list.ts` 列表 ```typescript import { Command } from 'commander'; import { query, SCHEMA } from './_client'; export function registerList(program: Command) { program .command('list') .alias('ls') .description('List all KB domains') .action(async () => { const rows = await query(` SELECT d.domain, d.title, d.status, COUNT(DISTINCT e.id) FILTER (WHERE e.status = 'active') AS entries, COUNT(DISTINCT sf.id) AS sources, COUNT(DISTINCT e.id) FILTER ( WHERE e.status = 'active' AND NOW() - e.last_reviewed > INTERVAL '90 days' AND (e.access_count = 0 OR e.last_accessed < e.last_reviewed) ) AS stale FROM ${SCHEMA}.domains d LEFT JOIN ${SCHEMA}.entries e ON e.domain_id = d.id LEFT JOIN ${SCHEMA}.source_files sf ON sf.domain_id = d.id GROUP BY d.id, d.domain, d.title, d.status ORDER BY d.domain `); if (rows.length === 0) { console.log('No domains. Run `dacli kb init` first, then `dacli kb add `.'); return; } console.log('DOMAIN STATUS ENTRIES SOURCES STALE'); console.log('─'.repeat(55)); for (const r of rows) { console.log( `${r.domain.padEnd(15)} ${r.status.padEnd(9)} ${String(r.entries).padEnd(8)} ${String(r.sources).padEnd(8)} ${r.stale}` ); } const totalEntries = rows.reduce((s, r) => s + Number(r.entries), 0); console.log(`\nTotal: ${rows.length} domains, ${totalEntries} active entries`); }); } ``` ### 3.4 `show.ts` 单域详情 ```typescript import { Command } from 'commander'; import { query, SCHEMA } from './_client'; export function registerShow(program: Command) { program .command('show ') .description('Show full KB content for a domain') .action(async (domain: string) => { const meta = await query( `SELECT domain, title, status, created_on, last_reviewed FROM ${SCHEMA}.domains WHERE domain = $1`, [domain] ); if (meta.length === 0) { console.error(`✗ Domain '${domain}' not found`); process.exit(1); } const m = meta[0]; console.log(`Domain: ${m.domain}`); console.log(`Title: ${m.title}`); console.log(`Status: ${m.status}`); console.log(`Created: ${m.created_on.toISOString()}`); console.log(`Last reviewed: ${m.last_reviewed.toISOString()}`); const sources = await query<{ path: string; kind: string }>( `SELECT path, kind FROM ${SCHEMA}.source_files sf JOIN ${SCHEMA}.domains d ON d.id = sf.domain_id WHERE d.domain = $1 ORDER BY kind, path`, [domain] ); console.log(`\nSource files (${sources.length}):`); for (const s of sources) { console.log(` - ${s.path} (${s.kind})`); } const entries = await query<{ section: string; content: string }>( `SELECT section, content FROM ${SCHEMA}.active_entries WHERE domain = $1 ORDER BY section, sort_order, id`, [domain] ); const sections = new Map(); for (const e of entries) { if (!sections.has(e.section)) sections.set(e.section, []); sections.get(e.section)!.push(e.content); } console.log(`\nEntries (${entries.length} active):`); for (const [section, contents] of sections) { console.log(`\n## ${section} (${contents.length})`); for (const c of contents) { console.log(`- ${c.split('\n')[0].slice(0, 100)}`); } } }); } ``` ### 3.5 `search.ts` 检索命令 ```typescript import { Command } from 'commander'; import { search } from './_search'; export function registerSearch(program: Command) { program .command('search ') .description('Full-text search via tsvector (BM25-like ranking)') .option('-d, --domain ', 'Filter by domain') .option('-l, --limit ', 'Limit results', '10') .option('--all', 'Include expired/archived entries') .option('--json', 'Output as JSON') .action(async (queryStr: string, opts: any) => { const results = await search({ query: queryStr, domain: opts.domain, includeAll: opts.all, limit: parseInt(opts.limit), }); if (opts.json) { console.log(JSON.stringify(results, null, 2)); return; } if (results.length === 0) { console.log(`No results for "${queryStr}"`); return; } const filterDesc = opts.all ? 'all' : 'active only'; console.log(`Found ${results.length} results (${filterDesc}):\n`); for (const r of results) { console.log(`[${r.domain}/${r.section}] (rank: ${r.rank.toFixed(3)})`); console.log(` ${r.snippet.replace(/\n/g, ' ').trim()}`); console.log(); } }); } ``` ### 3.6 `map.ts` 映射表 ```typescript import { Command } from 'commander'; import { query, SCHEMA } from './_client'; export function registerMap(program: Command) { program .command('map') .description('Show domain ↔ source file mapping') .action(async () => { const domains = await query(` SELECT d.domain, sf.path, sf.kind FROM ${SCHEMA}.domains d LEFT JOIN ${SCHEMA}.source_files sf ON sf.domain_id = d.id ORDER BY d.domain, sf.kind, sf.path `); const grouped = new Map>(); for (const r of domains) { if (!grouped.has(r.domain)) grouped.set(r.domain, []); if (r.path) grouped.get(r.domain)!.push({ path: r.path, kind: r.kind }); } console.log('DOMAIN → SOURCE FILES\n'); for (const [domain, files] of grouped) { console.log(`${domain} →`); for (const f of files) { console.log(` - ${f.path}${f.kind === 'related' ? ' (related)' : ''}`); } console.log(); } // 反向索引 console.log('\nSOURCE FILE → DOMAINS (reverse)\n'); const reverse = new Map(); for (const r of domains) { if (!r.path) continue; if (!reverse.has(r.path)) reverse.set(r.path, []); reverse.get(r.path)!.push(r.domain); } for (const [path, domains] of reverse) { console.log(`${path} → ${domains.join(', ')}`); } }); } ``` ### 3.7 `audit.ts` 陈旧审计 ```typescript import { Command } from 'commander'; import { query, SCHEMA } from './_client'; export function registerAudit(program: Command) { program .command('audit [type]') .description('Audit KB health (type: stale, default)') .action(async (type: string = 'stale') => { if (type !== 'stale') { console.error(`✗ Unknown audit type '${type}'. Supported: stale`); process.exit(1); } const rows = await query(` SELECT id, domain, section, SUBSTRING(content, 1, 80) AS preview, days_since_review::int AS days, access_count FROM ${SCHEMA}.stale_candidates ORDER BY days_since_review DESC `); if (rows.length === 0) { console.log('✓ No stale entries (all entries reviewed within 90 days).'); return; } console.log(`Found ${rows.length} stale candidates (90+ days no review, low access):\n`); for (const r of rows) { console.log(`[#${r.id}] [${r.domain}/${r.section}] "${r.preview}..."`); console.log(` ${r.days} days, ${r.access_count} access`); console.log(` → dacli kb renew ${r.id} | archive ${r.id} | deprecate ${r.id}\n`); } }); } ``` ### 3.8 `add.ts` 新建域 ```typescript import { Command } from 'commander'; import * as readline from 'readline'; import { query, execute, SCHEMA } from './_client'; function ask(rl: readline.Interface, q: string): Promise { return new Promise(resolve => rl.question(q, resolve)); } export function registerAdd(program: Command) { program .command('add ') .description('Add a new KB domain (interactive)') .action(async (domain: string) => { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); try { const title = await ask(rl, '? Title: '); const tagsStr = await ask(rl, '? Tags (comma-separated): '); const keywordsStr = await ask(rl, '? Keywords (comma-separated): '); const sourcesStr = await ask(rl, '? Source files (comma-separated paths): '); const tags = tagsStr.split(',').map(s => s.trim()).filter(Boolean); const keywords = keywordsStr.split(',').map(s => s.trim()).filter(Boolean); const sources = sourcesStr.split(',').map(s => s.trim()).filter(Boolean); // 1. INSERT domain await execute( `INSERT INTO ${SCHEMA}.domains (domain, title, tags, keywords) VALUES ($1, $2, $3, $4) ON CONFLICT (domain) DO NOTHING`, [domain, title, tags, keywords] ); // 2. INSERT source_files const domainRow = await query<{ id: number }>( `SELECT id FROM ${SCHEMA}.domains WHERE domain = $1`, [domain] ); const domainId = domainRow[0].id; for (const path of sources) { await execute( `INSERT INTO ${SCHEMA}.source_files (domain_id, path, kind) VALUES ($1, $2, 'source')`, [domainId, path] ); } console.log(`✓ Domain '${domain}' created with ${sources.length} source files.`); } finally { rl.close(); } }); } ``` ### 3.9 `entry.ts` 新增条目 ```typescript import { Command } from 'commander'; import * as readline from 'readline'; import { query, execute, SCHEMA } from './_client'; function ask(rl: readline.Interface, q: string): Promise { return new Promise(resolve => rl.question(q, resolve)); } export function registerEntry(program: Command) { program .command('entry ') .description('Add an entry to a domain (interactive)') .option('-s, --section
', 'Section name', '关键决策') .option('-c, --content ', 'Content (markdown)') .option('-e, --expires-on ', 'Expiry date (YYYY-MM-DD)') .action(async (domain: string, opts: any) => { const rl = readline.createInterface({ input: process.stdin, output: process.stdout }); try { let content = opts.content; if (!content) { content = await ask(rl, '? Content (markdown, single line or \\n for newline):\n> '); } let expiresOn = opts.expiresOn; if (!expiresOn) { expiresOn = await ask(rl, '? Expires on (YYYY-MM-DD, blank=never): '); } const domainRow = await query<{ id: number }>( `SELECT id FROM ${SCHEMA}.domains WHERE domain = $1`, [domain] ); if (domainRow.length === 0) { console.error(`✗ Domain '${domain}' not found`); process.exit(1); } const domainId = domainRow[0].id; const result = await query<{ id: number }>( `INSERT INTO ${SCHEMA}.entries (domain_id, section, content, expires_on) VALUES ($1, $2, $3, $4) RETURNING id`, [domainId, opts.section, content, expiresOn || null] ); const expiresDesc = expiresOn ? `, expires ${expiresOn}` : ''; console.log(`✓ Entry #${result[0].id} added to '${domain}' (${opts.section})${expiresDesc}.`); } finally { rl.close(); } }); } ``` ### 3.10 `update.ts` / `remove.ts` / `renew.ts` / `expire.ts` / `archive.ts` / `deprecate.ts` 简洁模板 (每个 ~15 行): ```typescript // update.ts import { Command } from 'commander'; import { execute, query, SCHEMA } from './_client'; export function registerUpdate(program: Command) { program .command('update ') .description('Update entry content/section') .option('-s, --section
', 'New section') .option('-c, --content ', 'New content') .option('-e, --expires-on ', 'New expiry date') .action(async (id: string, opts: any) => { const sets: string[] = ['last_reviewed = NOW()']; const params: any[] = []; if (opts.section) { params.push(opts.section); sets.push(`section = $${params.length}`); } if (opts.content) { params.push(opts.content); sets.push(`content = $${params.length}`); } if (opts.expiresOn !== undefined) { params.push(opts.expiresOn || null); sets.push(`expires_on = $${params.length}`); } params.push(parseInt(id)); const n = await execute( `UPDATE ${SCHEMA}.entries SET ${sets.join(', ')} WHERE id = $${params.length}`, params ); console.log(n > 0 ? `✓ Entry #${id} updated.` : `✗ Entry #${id} not found.`); }); } ``` ```typescript // remove.ts import { Command } from 'commander'; import { execute, SCHEMA } from './_client'; export function registerRemove(program: Command) { program .command('remove ') .alias('rm') .description('Permanently delete an entry') .option('-f, --force', 'Skip confirmation') .action(async (id: string, opts: any) => { if (!opts.force) { console.log(`⚠ This will permanently delete entry #${id}. Use --force to confirm.`); return; } const n = await execute(`DELETE FROM ${SCHEMA}.entries WHERE id = $1`, [parseInt(id)]); console.log(n > 0 ? `✓ Entry #${id} deleted.` : `✗ Entry #${id} not found.`); }); } ``` ```typescript // renew.ts import { Command } from 'commander'; import { execute, SCHEMA } from './_client'; export function registerRenew(program: Command) { program .command('renew ') .description('Update last_reviewed = NOW() (reset staleness timer)') .action(async (id: string) => { const n = await execute( `UPDATE ${SCHEMA}.entries SET last_reviewed = NOW() WHERE id = $1`, [parseInt(id)] ); console.log(n > 0 ? `✓ Entry #${id} renewed.` : `✗ Entry #${id} not found.`); }); } ``` ```typescript // expire.ts import { Command } from 'commander'; import { execute, SCHEMA } from './_client'; export function registerExpire(program: Command) { program .command('expire ') .description('Set expiry date on an entry') .requiredOption('-o, --on ', 'Expiry date (YYYY-MM-DD)') .action(async (id: string, opts: any) => { const n = await execute( `UPDATE ${SCHEMA}.entries SET expires_on = $1, last_reviewed = NOW() WHERE id = $2`, [opts.on, parseInt(id)] ); console.log(n > 0 ? `✓ Entry #${id} expires on ${opts.on}.` : `✗ Entry #${id} not found.`); }); } ``` ```typescript // archive.ts import { Command } from 'commander'; import { execute, SCHEMA } from './_client'; export function registerArchive(program: Command) { program .command('archive ') .description('Archive an entry (hidden from active_entries view)') .option('-r, --reason ', 'Archive reason') .action(async (id: string, opts: any) => { const n = await execute( `UPDATE ${SCHEMA}.entries SET status = 'archived', last_reviewed = NOW() WHERE id = $1`, [parseInt(id)] ); console.log(n > 0 ? `✓ Entry #${id} archived.${opts.reason ? ` Reason: ${opts.reason}` : ''}` : `✗ Entry #${id} not found.`); }); } ``` ```typescript // deprecate.ts import { Command } from 'commander'; import { execute, SCHEMA } from './_client'; export function registerDeprecate(program: Command) { program .command('deprecate ') .description('Deprecate an entry (link to replacement)') .requiredOption('-r, --replaced-by ', 'New entry id that replaces this') .option('--reason ', 'Deprecation reason') .action(async (id: string, opts: any) => { const oldId = parseInt(id); const newId = parseInt(opts.replacedBy); // 1. UPDATE entries SET status='deprecated' const n = await execute( `UPDATE ${SCHEMA}.entries SET status = 'deprecated', last_reviewed = NOW() WHERE id = $1`, [oldId] ); if (n === 0) { console.error(`✗ Entry #${id} not found`); process.exit(1); } // 2. INSERT replacements await execute( `INSERT INTO ${SCHEMA}.replacements (old_entry_id, new_entry_id, reason) VALUES ($1, $2, $3) ON CONFLICT (old_entry_id) DO UPDATE SET new_entry_id = $2, reason = $3, replaced_on = NOW()`, [oldId, newId, opts.reason || null] ); console.log(`✓ Entry #${id} deprecated, replaced by #${newId}.${opts.reason ? ` Reason: ${opts.reason}` : ''}`); }); } ``` ### 3.11 `rebuild-fts.ts` 重建 tsvector ```typescript import { Command } from 'commander'; import { execute, SCHEMA } from './_client'; export function registerRebuildFts(program: Command) { program .command('rebuild-fts') .description('Force rebuild search_vector for all entries (trigger fallback)') .action(async () => { // 触发器是 BEFORE INSERT/UPDATE, 只需 UPDATE 内容相同即可重建 const n = await execute( `UPDATE ${SCHEMA}.entries SET content = content WHERE id > 0` ); console.log(`✓ search_vector rebuilt for ${n} entries.`); }); } ``` ### 3.12 `serve.ts` REST wrapper (可选) ```typescript /** * serve.ts — `dacli kb serve` 启动 REST API (可选, 跨进程用) * * 默认关闭. 启用: `dacli kb serve --port=4100` * 端点: GET /api/kb/list | /api/kb/show/:domain | /api/kb/search?q=... */ import { Command } from 'commander'; import * as http from 'http'; import { query } from './_client'; import { search } from './_search'; import { SCHEMA } from './_client'; export function registerServe(program: Command) { program .command('serve') .description('Start REST API server for KB (optional, cross-process)') .option('-p, --port ', 'HTTP port', '4100') .action(async (opts: any) => { const port = parseInt(opts.port); const server = http.createServer(async (req, res) => { res.setHeader('Content-Type', 'application/json'); const url = new URL(req.url || '/', `http://localhost:${port}`); try { if (url.pathname === '/api/kb/list') { const rows = await query(`SELECT domain, title, status FROM ${SCHEMA}.domains ORDER BY domain`); res.end(JSON.stringify(rows)); } else if (url.pathname.startsWith('/api/kb/show/')) { const domain = url.pathname.split('/').pop(); const rows = await query(`SELECT * FROM ${SCHEMA}.active_entries WHERE domain = $1`, [domain]); res.end(JSON.stringify(rows)); } else if (url.pathname === '/api/kb/search') { const q = url.searchParams.get('q') || ''; const domain = url.searchParams.get('domain') || undefined; const limit = parseInt(url.searchParams.get('limit') || '10'); const results = await search({ query: q, domain, limit }); res.end(JSON.stringify(results)); } else { res.statusCode = 404; res.end(JSON.stringify({ error: 'Not found' })); } } catch (e: any) { res.statusCode = 500; res.end(JSON.stringify({ error: e.message })); } }); server.listen(port, () => { console.log(`KB REST API listening on http://localhost:${port}`); console.log(` GET /api/kb/list`); console.log(` GET /api/kb/show/:domain`); console.log(` GET /api/kb/search?q=...&domain=...&limit=10`); }); }); } ``` ### 3.13 `index.ts` 统一注册 ```typescript /** * index.ts — 注册所有 kb 子命令到 kb 父命令 */ import { Command } from 'commander'; import { registerInit } from './_init'; import { registerList } from './list'; import { registerShow } from './show'; import { registerSearch } from './search'; import { registerMap } from './map'; import { registerAudit } from './audit'; import { registerAdd } from './add'; import { registerEntry } from './entry'; import { registerUpdate } from './update'; import { registerRemove } from './remove'; import { registerExpire } from './expire'; import { registerRenew } from './renew'; import { registerArchive } from './archive'; import { registerDeprecate } from './deprecate'; import { registerRebuildFts } from './rebuild-fts'; import { registerServe } from './serve'; export function registerKb(program: Command) { const kb = program .command('kb') .description('Knowledge base (PostgreSQL-backed) — auto date/expiry/search filter'); registerInit(kb); registerList(kb); registerShow(kb); registerSearch(kb); registerMap(kb); registerAudit(kb); registerAdd(kb); registerEntry(kb); registerUpdate(kb); registerRemove(kb); registerExpire(kb); registerRenew(kb); registerArchive(kb); registerDeprecate(kb); registerRebuildFts(kb); registerServe(kb); } ``` ### 3.14 `src/cli.ts` 注册 找到现有 cli.ts 中类似 `program.command('form').description(...)` 的位置, 添加: ```typescript import { registerKb } from './commands/kb'; // 在其他命令注册处添加: registerKb(program); ``` ### 3.15 Commit 2 提交 ```bash cd /home/ubuntu/ccWorkDir/dacli git add src/commands/kb/ src/cli.ts git commit -m "dacli(kb): 16 个 kb 命令 (commit 2/3) 5 检索: list, show, search, map, audit 10 写入: add, entry, update, remove, expire, renew, archive, deprecate, rebuild-fts 1 服务: serve (REST wrapper, 可选) 1 init: 建 ssw_kb schema 自动特性: created_on/last_reviewed NOW(), expires_on 自动过期, active_entries 视图自动过滤, stale_candidates 视图自动检测 90 天陈旧, search 自动更新 access_count/last_accessed。 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude " git push origin main ``` --- ## 4. Commit 3: 初始数据 + 测试 + 文档 ### 4.1 初始 4 域 + ~65 条目 通过 `dacli kb add` + `dacli kb entry` 命令手工初始化。建议先创建 4 域, 再各域添加 10-20 条目蒸馏 source_files。 **dacli 域** (source_files): ``` 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 dacli/docs/cmd-review/di.md .claude/skills/dacli/SKILL.md .claude/skills/dacli/references/commands.md .claude/skills/dacli/references/blindspots.md dacli/docs/web-patches/README.md ``` **jnpf 域** (source_files): ``` .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 ``` **ssw-loop 域** (source_files): ``` .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 ``` **ssw-e2e-test 域** (source_files): ``` .claude/skills/ssw-e2e-test/SKILL.md .claude/skills/ssw-e2e-test/references/tc-ab-real-test.md ``` **条目蒸馏模板** (示例): dacli 域示例条目: ```bash dacli kb entry dacli --section 关键决策 -c "**decision**: dacli form create --ai 用 NCPF backend (复用 JNPF AI 端点, 不需独立 LLM 配置)" --expires-on 2027-01-01 dacli kb entry dacli --section 关键决策 -c "**decision**: dacli webapi 镜像架构 v0.11+ 落地, 0 复刻 web 端 (commit d4506fe)" dacli kb entry dacli --section 踩坑教训 -c "**lesson**: form create AI 输出截断时失败 → ssw-common JsonRepairUtil 兜底 (BS-新30, commit 038bd98)" dacli kb entry dacli --section 踩坑教训 -c "**lesson**: webapi visualDev.ts import 替换 #/api/request → _defhttp_shim.ts" dacli kb entry dacli --section 复用清单 -c "dacli form create --ai \"<描述>\" --autoRelease 端到端建表+发布 (v0.11+ 推荐)" dacli kb entry dacli --section 复用清单 -c "dacli menu create --formId= --type=3 --urlAddress=model/ (BS-50 fallback)" dacli kb entry dacli --section 业务背景 -c "dacli 是 JNPF 平台 CLI 入口, 22 父命令/116 子命令, v0.14+ 镜像 web 端 (webapi/)" dacli kb entry dacli --section 对应技术架构 -c "模块: dacli/src/commands/{form,menu,dm,di,...}; webapi/_loader.ts; webapi/visualDev.ts" dacli kb entry jnpf --section 关键决策 -c "**decision**: 业务行为调整走 boot/ssw-common/ 扩展层, 不改 jnpf 源码 (CLAUDE.md §代码修改权限)" dacli kb entry jnpf --section 关键决策 -c "**decision**: @SpringBootApplication scanBasePackages 加 'ssw' 才能扫到 ssw-common bean" dacli kb entry jnpf --section 踩坑教训 -c "**lesson**: JNPF 升级几乎每次覆盖 JnpfAdminApplication.java, scanBasePackages 必须重新应用 (web-patches/)" dacli kb entry jnpf --section 踩坑教训 -c "**lesson**: ServiceImpMarco.vm 虚拟字段 (searchList 不在主表) 会输出字面 ${} 到 Java → javac 失败" dacli kb entry jnpf --section 对应技术架构 -c "jnpf 模块: jnpf-common-ai/SendAiMessage.java:148, jnpf-resources/TemplateCodeVue3/PublicMacro/ServiceImpMarco.vm" dacli kb entry ssw-loop --section 业务背景 -c "ssw-loop 是 JNPF 应用的 H5 开发主流程, 7 阶段 + 4 关卡 CI" dacli kb entry ssw-loop --section 关键决策 -c "**decision**: 阶段 7.2 用真实业务数据 CRUD, 不接受 test fixture (BS-109~111)" dacli kb entry ssw-loop --section 关键决策 -c "**decision**: HTML 产物放 docs/{app}/, 不入 git (CI 关卡 G 警告)" dacli kb entry ssw-loop --section 踩坑教训 -c "**lesson**: 子代理派发要给出完整上下文, 否则盲点扩散 (anti-patterns.md §2.6)" dacli kb entry ssw-loop --section 复用清单 -c "dacli form create + menu create + di create 一气呵成, 不手写 schema" dacli kb entry ssw-e2e-test --section 业务背景 -c "ssw-e2e-test 是 Playwright + dacli 的端到端测试 skill, TC-A/B/C 分级" dacli kb entry ssw-e2e-test --section 关键决策 -c "**decision**: TC-B 构造/查找/触发/注入走 webapi (快), 验证走浏览器 (真实)" dacli kb entry ssw-e2e-test --section 踩坑教训 -c "**lesson**: test fixture 不能当业务验证, 必须真实数据 (dacli-test-run-real-data-upgrade-2026-06-28)" dacli kb entry ssw-e2e-test --section 复用清单 -c "TC-B 复用 webapi 镜像能力, 跨表 join, 关联表真实 ID lookup" ``` (每域 ~10-20 条目, 累计 ~50-60 条) ### 4.2 `tests/test-kb.ts` 闭环测试 ```typescript /** * test-kb.ts — KB 闭环测试 (假设 pg 已运行) * 运行: cd dacli && npx tsx tests/test-kb.ts */ import { query, execute, close, SCHEMA } from '../src/commands/kb/_client'; import { search } from '../src/commands/kb/_search'; async function test() { console.log('=== KB 闭环测试 ===\n'); // 1. 清理测试数据 console.log('1. 清理 test-domain...'); await execute(`DELETE FROM ${SCHEMA}.domains WHERE domain = 'test-kb-domain'`); console.log(' ✓\n'); // 2. 新建域 console.log('2. 新建 test-kb-domain...'); await execute( `INSERT INTO ${SCHEMA}.domains (domain, title, tags, keywords) VALUES ($1, $2, $3, $4)`, ['test-kb-domain', '测试域', ['test'], ['test keyword']] ); const domainId = (await query<{id:number}>(`SELECT id FROM ${SCHEMA}.domains WHERE domain = $1`, ['test-kb-domain']))[0].id; await execute(`INSERT INTO ${SCHEMA}.source_files (domain_id, path) VALUES ($1, $2)`, [domainId, 'test/path.md']); console.log(` ✓ Domain id=${domainId}\n`); // 3. 新增条目 console.log('3. 新增条目...'); const r1 = await query<{id:number}>( `INSERT INTO ${SCHEMA}.entries (domain_id, section, content) VALUES ($1, $2, $3) RETURNING id`, [domainId, '关键决策', '**decision**: test 关键决策'] ); const r2 = await query<{id:number}>( `INSERT INTO ${SCHEMA}.entries (domain_id, section, content) VALUES ($1, $2, $3) RETURNING id`, [domainId, '踩坑教训', '**lesson**: test 踩坑教训'] ); console.log(` ✓ Entry #${r1[0].id} and #${r2[0].id}\n`); // 4. 检索 (FTS5) console.log('4. search "test"...'); const results = await search({ query: 'test', limit: 5 }); console.log(` ✓ Found ${results.length} results`); console.log(` [${results[0].domain}/${results[0].section}] ${results[0].snippet.slice(0, 80)}...\n`); // 5. 过期测试 console.log('5. expire #1 to past...'); await execute(`UPDATE ${SCHEMA}.entries SET expires_on = '2026-07-01' WHERE id = $1`, [r1[0].id]); const afterExpire = await search({ query: 'test', limit: 5 }); console.log(` ✓ After expire: ${afterExpire.length} results (was ${results.length})\n`); // 6. search --all console.log('6. search --all "test"...'); const allResults = await search({ query: 'test', includeAll: true, limit: 5 }); console.log(` ✓ Found ${allResults.length} results (all status)\n`); // 7. renew console.log('7. renew #1...'); await execute(`UPDATE ${SCHEMA}.entries SET expires_on = NULL, last_reviewed = NOW() WHERE id = $1`, [r1[0].id]); const afterRenew = await search({ query: 'test', limit: 5 }); console.log(` ✓ After renew: ${afterRenew.length} results\n`); // 8. archive console.log('8. archive #2...'); await execute(`UPDATE ${SCHEMA}.entries SET status = 'archived' WHERE id = $1`, [r2[0].id]); const afterArchive = await search({ query: 'test', limit: 5 }); console.log(` ✓ After archive: ${afterArchive.length} results\n`); // 9. 清理 console.log('9. 清理 test-kb-domain...'); await execute(`DELETE FROM ${SCHEMA}.domains WHERE domain = 'test-kb-domain'`); console.log(' ✓\n'); console.log('=== 全部测试通过 ✓ ==='); await close(); } test().catch(e => { console.error('✗ Test failed:', e); process.exit(1); }); ``` ### 4.3 `.claude/skills/dacli/SKILL.md` 加 kb 速查 在 SKILL.md 末尾追加 (~15 行): ```markdown ## KB 知识库 (PostgreSQL 后端) 知识不入文件系统, 直接入 pg `ssw_kb` schema, AI 通过 `dacli kb` 命令检索。 ### 检索 (AI 日常用) ```bash dacli kb list # 列所有域 dacli kb show # 看域详情 dacli kb search "" # tsvector 全文检索 (BM25 排序) dacli kb search "" --domain= # 域过滤 dacli kb search "" --all # 含过期/archived dacli kb map # 域↔源文件 映射表 dacli kb audit stale # 90 天陈旧候选 ``` ### 写入 (开发者用) ```bash dacli kb init # 首次: 建 ssw_kb schema dacli kb add # 新建域 (交互式) dacli kb entry # 新增条目 (交互式) dacli kb renew # 续期 (重置 last_reviewed) dacli kb expire --on=YYYY-MM-DD # 设置过期 dacli kb archive --reason=... # 归档 dacli kb deprecate --replaced-by= # 废弃 + 链向新条目 dacli kb rebuild-fts # 重建 tsvector (兜底) ``` ### 自动特性 - `created_on` / `last_reviewed` 自动 NOW() - `expires_on` 过期自动从 `active_entries` 视图过滤 - `stale_candidates` 视图自动列 90 天未审查条目 - `search` 命中自动更新 `access_count` + `last_accessed` ### 跨进程访问 ```bash psql -h postgres -U ssw -d ssw -c "SELECT * FROM ssw_kb.active_entries WHERE search_vector @@ to_tsquery('dacli & form') LIMIT 5" ``` ``` ### 4.4 `.claude/CLAUDE.md` 加 KB 入口 找到 CLAUDE.md "常用命令" 段附近, 加 1 行: ```markdown dacli kb search "" # KB 知识库检索 (PostgreSQL 后端, 见 .claude/skills/dacli/SKILL.md) ``` ### 4.5 Commit 3 提交 ```bash cd /home/ubuntu/ccWorkDir/dacli git add tests/test-kb.ts git commit -m "dacli(kb): 闭环测试 test-kb.ts (commit 3a/3) 7 步测试: 清理 → 新建域 → 新增条目 → 检索 → 过期 → search --all → renew → archive 验证自动特性: active_entries 自动过滤过期, search 自动更新 access_count。 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude " git push origin main # 4 域初始数据 (手工 dacli kb add/entry 命令后, 不入 git) # 这些是数据库内容, 不是代码, 不需要 commit ``` 如果想把初始数据脚本化, 创建 `dacli/scripts/seed-kb.sh`: ```bash #!/bin/bash # seed-kb.sh — 4 域初始数据脚本 # 运行: cd dacli && bash scripts/seed-kb.sh set -e export PGHOST=postgres PGPORT=5432 PGUSER=ssw PGPASSWORD=*** PGDATABASE=ssw npx tsx src/cli.ts kb init npx tsx src/cli.ts kb add dacli < 各域添加 ~15 条目 (蒸馏) echo "✓ 4 域初始数据完成" ``` (脚本细节根据实际执行命令调整; **本期最简方案**: 直接手工 `dacli kb add/entry` 几十条, 不写脚本) 文档 commit: ```bash cd /home/ubuntu/ccWorkDir/.claude git add skills/dacli/SKILL.md CLAUDE.md git commit -m "CLAUDE.md + dacli/SKILL.md: 加 kb 命令速查段 (commit 3b/3) dacli kb 是 PostgreSQL 后端的知识库, 文档不入文件系统。 SKILL.md 末尾追加 kb 命令速查 (检索 + 写入 + 自动特性 + 跨进程访问)。 CLAUDE.md 常用命令段加 1 行 KB 入口。 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude " git push origin main ``` --- ## 5. 完整验证清单 ### 5.1 Commit 1 验证 ```bash cd /home/ubuntu/ccWorkDir/dacli export PGHOST=postgres PGPORT=5432 PGUSER=ssw PGPASSWORD= PGDATABASE=ssw npx tsx src/cli.ts kb init # 期望: "Schema 'ssw_kb' initialized: Tables (4): ... Triggers (1): ... Views (2): ..." ``` ### 5.2 Commit 2 验证 ```bash cd /home/ubuntu/ccWorkDir/dacli npx tsx src/cli.ts kb --help # 期望: 列出所有 kb 子命令 (init, list, show, search, map, audit, add, entry, ...) ``` ### 5.3 Commit 3 验证 ```bash cd /home/ubuntu/ccWorkDir/dacli npx tsx tests/test-kb.ts # 期望: "=== 全部测试通过 ✓ ===" ``` ### 5.4 源文件 md5 未变 (sanity check) ```bash cd /home/ubuntu/ccWorkDir md5sum dacli/src/cli.ts \ .claude/skills/dacli/SKILL.md \ .claude/skills/ssw-loop/SKILL.md \ .claude/skills/ssw-e2e-test/SKILL.md \ .claude/CLAUDE.md \ jnpf/后端/jnpf-java-boot/jnpf-admin/src/main/java/jnpf/JnpfAdminApplication.java # 对比 baseline (本次只改 dacli/ + .claude/skills/dacli/ + .claude/CLAUDE.md) ``` ### 5.5 AI 检索烟雾测试 (新会话) 新开会话, 输入: ``` 我应该用什么 dacli 命令做 X? ``` 期望 AI 输出 (之一): - 调 `dacli kb search ""` 看是否有相关经验 - 或读 `dacli/docs/cmd-review/` 命令审计 - 或调 `dacli --help` --- ## 6. 关键文件清单 (本次) | 路径 | 状态 | 说明 | |------|------|------| | `dacli/src/commands/kb/_client.ts` | 新建 | pg Pool | | `dacli/src/commands/kb/_schema.ts` | 新建 | PostgreSQL DDL | | `dacli/src/commands/kb/_init.ts` | 新建 | `dacli kb init` | | `dacli/src/commands/kb/_search.ts` | 新建 | tsvector 检索 | | `dacli/src/commands/kb/list.ts` | 新建 | | | `dacli/src/commands/kb/show.ts` | 新建 | | | `dacli/src/commands/kb/search.ts` | 新建 | | | `dacli/src/commands/kb/map.ts` | 新建 | | | `dacli/src/commands/kb/audit.ts` | 新建 | | | `dacli/src/commands/kb/add.ts` | 新建 | | | `dacli/src/commands/kb/entry.ts` | 新建 | | | `dacli/src/commands/kb/update.ts` | 新建 | | | `dacli/src/commands/kb/remove.ts` | 新建 | | | `dacli/src/commands/kb/expire.ts` | 新建 | | | `dacli/src/commands/kb/renew.ts` | 新建 | | | `dacli/src/commands/kb/archive.ts` | 新建 | | | `dacli/src/commands/kb/deprecate.ts` | 新建 | | | `dacli/src/commands/kb/rebuild-fts.ts` | 新建 | | | `dacli/src/commands/kb/serve.ts` | 新建 | REST wrapper | | `dacli/src/commands/kb/index.ts` | 新建 | 统一注册 | | `dacli/src/cli.ts` | 编辑 | 注册 `registerKb(program)` | | `dacli/.env.example` | 编辑 | 追加 PG* + KB_SCHEMA | | `dacli/package.json` | 编辑 | 加 `pg` 依赖 | | `dacli/tests/test-kb.ts` | 新建 | 闭环测试 | | `.claude/skills/dacli/SKILL.md` | 编辑 | kb 命令速查段 | | `.claude/CLAUDE.md` | 编辑 | KB 入口 1 行 | --- ## 7. 风险与回滚 | 风险 | 缓解 | |------|------| | pg 连接失败 | 检查 PG* 环境变量, 确认容器可达 | | tsvector 中文分词不准 | 用 `'simple'` 配置, 字符级匹配 (后续可换 `chinese_zh`) | | 触发器同步失败 | `dacli kb rebuild-fts` 兜底 | | `dacli kb init` 已运行, 重复无副作用 | DDL 全用 `IF NOT EXISTS` | | 4 域初始数据遗漏 | 跑 `dacli kb list` 看 entries 列, 补 `dacli kb entry` | **回滚** (每个 commit 独立可 revert): ```bash # dacli 仓 cd /home/ubuntu/ccWorkDir/dacli git log --oneline -5 # 找到 3 个 commit hash git revert # 单独 revert git revert git revert # .claude 仓 (CLAUDE.md + SKILL.md) cd /home/ubuntu/ccWorkDir/.claude git log --oneline -5 git revert ``` --- ## 8. 不在本次范围 - 业务 app 信息 (jxcj/jyzs/testspace) — **不入 KB** - Markdown KB 文件 — **不写** (PostgreSQL 是唯一知识层) - dacli/docs/archive/ — **不动**, 与 KB 并存 - dacli/docs/knowledge/ — **不创建** - dacli/src/ 注释审计 — 独立 workstream - pgvector 向量检索 — 留作未来扩展 (本期仅 tsvector) - JSON 备份 export/import — 留作未来 --- ## 9. 后续规划 (本次后) 1. **业务扩容**: 用户后续提需求时, `dacli kb add ` 2. **pgvector 升级**: KB > 200 条 + 语义查询时启用 3. **JSON 备份**: `dacli kb export --json` / `import --json` (pg COPY) 4. **CI 集成**: 检查 ssw_kb.domains 非空 5. **知识图谱**: 跨条目关系 (A 引用 B / A 矛盾 B) 6. **AI 自动入库**: AI 解决新问题时自动 `dacli kb entry` --- **文档版本**: 2026-07-02 **关联 plan**: `/home/ubuntu/.claude/plans/piped-pondering-moon.md` **作者**: Claude Code (会话协作)