- §1 修订说明: v0.11+→v0.13+ (--ai-json 已于 BS-新28 删除) - §6.6 错误处理: --ai-json=→--ai= - §10.2 一条龙: 整段替换为 --ai 描述模式 - §10 状态机: v0.11+→v0.13+ - 确认 --autoTable / --autoRelease 仍有效
52 KiB
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 个技术基础设施域 (本期初始化, 无业务信息):
- dacli — CLI 工具 (命令/架构/盲点)
- jnpf — 平台基线 (约束/机制)
- ssw-loop — 开发循环 (7 阶段/4 关卡)
- ssw-e2e-test — 测试模式 (TC-A/B)
1. 实施前环境检查
1.1 pg 容器可达性
# 试多种连接方式
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 现状
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 注册位置
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 完整代码
/**
* _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<T = any>(sql: string, params: any[] = []): Promise<T[]> {
const { rows } = await pool.query(sql, params);
return rows as T[];
}
/** 执行写操作 (INSERT/UPDATE/DELETE) */
export async function execute(sql: string, params: any[] = []): Promise<number> {
const result = await pool.query(sql, params);
return result.rowCount ?? 0;
}
/** 批量更新访问计数 (search 后调用) */
export async function trackAccess(entryIds: (number | bigint)[]): Promise<void> {
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<T = void>(
fn: (client: PoolClient) => Promise<T>
): Promise<T> {
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<boolean> {
try {
await pool.query('SELECT 1');
return true;
} catch {
return false;
}
}
/** 关闭连接 (进程退出时调用) */
export async function close(): Promise<void> {
await pool.end();
}
2.3 _schema.ts 完整代码
/**
* _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 完整代码
/**
* _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 追加
# === dacli KB (PostgreSQL backend) ===
# 复用已有 pg 容器, schema 隔离
PGHOST=postgres
PGPORT=5432
PGUSER=ssw
PGPASSWORD=
PGDATABASE=ssw
KB_SCHEMA=ssw_kb
2.6 package.json 追加依赖
{
"dependencies": {
"pg": "^8.11.0",
...
}
}
执行 cd /home/ubuntu/ccWorkDir/dacli && npm install
2.7 Commit 1 提交
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 <[email protected]>"
git push origin main
2.8 Commit 1 验证
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 <domain> |
src/commands/kb/search.ts |
新建 | kb search <query> |
src/commands/kb/map.ts |
新建 | kb map |
src/commands/kb/audit.ts |
新建 | kb audit [stale|renew] |
src/commands/kb/add.ts |
新建 | kb add <domain> |
src/commands/kb/entry.ts |
新建 | kb entry <domain> |
src/commands/kb/update.ts |
新建 | kb update <id> |
src/commands/kb/remove.ts |
新建 | kb remove <id> |
src/commands/kb/expire.ts |
新建 | kb expire <id> |
src/commands/kb/renew.ts |
新建 | kb renew <id> |
src/commands/kb/archive.ts |
新建 | kb archive <id> |
src/commands/kb/deprecate.ts |
新建 | kb deprecate <id> |
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 检索封装
/**
* _search.ts — tsvector 检索 + 访问计数
*
* 自动:
* - 默认仅返回 active (status='active' AND 未过期)
* - 命中后自动更新 access_count + last_accessed
* - ts_headline 生成 <mark>高亮 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<SearchResult[]> {
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=<mark>, StopSel=</mark>, 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<SearchResult>(sql, params);
// 自动更新访问计数
if (rows.length > 0) {
await trackAccess(rows.map(r => r.id));
}
return rows;
}
3.3 list.ts 列表
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<any>(`
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 <domain>`.');
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 单域详情
import { Command } from 'commander';
import { query, SCHEMA } from './_client';
export function registerShow(program: Command) {
program
.command('show <domain>')
.description('Show full KB content for a domain')
.action(async (domain: string) => {
const meta = await query<any>(
`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<string, string[]>();
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 检索命令
import { Command } from 'commander';
import { search } from './_search';
export function registerSearch(program: Command) {
program
.command('search <query>')
.description('Full-text search via tsvector (BM25-like ranking)')
.option('-d, --domain <domain>', 'Filter by domain')
.option('-l, --limit <n>', '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 映射表
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<any>(`
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<string, Array<{ path: string; kind: string }>>();
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<string, string[]>();
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 陈旧审计
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<any>(`
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 新建域
import { Command } from 'commander';
import * as readline from 'readline';
import { query, execute, SCHEMA } from './_client';
function ask(rl: readline.Interface, q: string): Promise<string> {
return new Promise(resolve => rl.question(q, resolve));
}
export function registerAdd(program: Command) {
program
.command('add <domain>')
.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 新增条目
import { Command } from 'commander';
import * as readline from 'readline';
import { query, execute, SCHEMA } from './_client';
function ask(rl: readline.Interface, q: string): Promise<string> {
return new Promise(resolve => rl.question(q, resolve));
}
export function registerEntry(program: Command) {
program
.command('entry <domain>')
.description('Add an entry to a domain (interactive)')
.option('-s, --section <section>', 'Section name', '关键决策')
.option('-c, --content <content>', 'Content (markdown)')
.option('-e, --expires-on <date>', '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 行):
// update.ts
import { Command } from 'commander';
import { execute, query, SCHEMA } from './_client';
export function registerUpdate(program: Command) {
program
.command('update <id>')
.description('Update entry content/section')
.option('-s, --section <section>', 'New section')
.option('-c, --content <content>', 'New content')
.option('-e, --expires-on <date>', '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.`);
});
}
// remove.ts
import { Command } from 'commander';
import { execute, SCHEMA } from './_client';
export function registerRemove(program: Command) {
program
.command('remove <id>')
.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.`);
});
}
// renew.ts
import { Command } from 'commander';
import { execute, SCHEMA } from './_client';
export function registerRenew(program: Command) {
program
.command('renew <id>')
.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.`);
});
}
// expire.ts
import { Command } from 'commander';
import { execute, SCHEMA } from './_client';
export function registerExpire(program: Command) {
program
.command('expire <id>')
.description('Set expiry date on an entry')
.requiredOption('-o, --on <date>', '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.`);
});
}
// archive.ts
import { Command } from 'commander';
import { execute, SCHEMA } from './_client';
export function registerArchive(program: Command) {
program
.command('archive <id>')
.description('Archive an entry (hidden from active_entries view)')
.option('-r, --reason <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.`);
});
}
// deprecate.ts
import { Command } from 'commander';
import { execute, SCHEMA } from './_client';
export function registerDeprecate(program: Command) {
program
.command('deprecate <id>')
.description('Deprecate an entry (link to replacement)')
.requiredOption('-r, --replaced-by <new_id>', 'New entry id that replaces this')
.option('--reason <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
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 (可选)
/**
* 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 <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 统一注册
/**
* 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(...) 的位置, 添加:
import { registerKb } from './commands/kb';
// 在其他命令注册处添加:
registerKb(program);
3.15 Commit 2 提交
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 <[email protected]>"
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-ts/SKILL.md
.claude/skills/dacli-ts/references/commands.md
.claude/skills/dacli-ts/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 域示例条目:
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=<id> --type=3 --urlAddress=model/<enCode> (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 闭环测试
/**
* 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-ts/SKILL.md 加 kb 速查
在 SKILL.md 末尾追加 (~15 行):
## KB 知识库 (PostgreSQL 后端)
知识不入文件系统, 直接入 pg `ssw_kb` schema, AI 通过 `dacli kb` 命令检索。
### 检索 (AI 日常用)
```bash
dacli kb list # 列所有域
dacli kb show <domain> # 看域详情
dacli kb search "<query>" # tsvector 全文检索 (BM25 排序)
dacli kb search "<query>" --domain=<domain> # 域过滤
dacli kb search "<query>" --all # 含过期/archived
dacli kb map # 域↔源文件 映射表
dacli kb audit stale # 90 天陈旧候选
写入 (开发者用)
dacli kb init # 首次: 建 ssw_kb schema
dacli kb add <domain> # 新建域 (交互式)
dacli kb entry <domain> # 新增条目 (交互式)
dacli kb renew <id> # 续期 (重置 last_reviewed)
dacli kb expire <id> --on=YYYY-MM-DD # 设置过期
dacli kb archive <id> --reason=... # 归档
dacli kb deprecate <id> --replaced-by=<new> # 废弃 + 链向新条目
dacli kb rebuild-fts # 重建 tsvector (兜底)
自动特性
created_on/last_reviewed自动 NOW()expires_on过期自动从active_entries视图过滤stale_candidates视图自动列 90 天未审查条目search命中自动更新access_count+last_accessed
跨进程访问
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 "<query>" # KB 知识库检索 (PostgreSQL 后端, 见 .claude/skills/dacli-ts/SKILL.md)
4.5 Commit 3 提交
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 <[email protected]>"
git push origin main
# 4 域初始数据 (手工 dacli kb add/entry 命令后, 不入 git)
# 这些是数据库内容, 不是代码, 不需要 commit
如果想把初始数据脚本化, 创建 dacli/scripts/seed-kb.sh:
#!/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 <<EOF
dacli CLI 工具 KB
dacli, cli, form, menu
dacli form create, dacli menu create
dacli/src/cli.ts
dacli/docs/cmd-review/_summary.md
dacli/docs/cmd-review/form.md
.claude/skills/dacli-ts/SKILL.md
.claude/skills/dacli-ts/references/commands.md
.claude/skills/dacli-ts/references/blindspots.md
EOF
# 类似 add jnpf / ssw-loop / ssw-e2e-test
# 然后 kb entry <domain> 各域添加 ~15 条目 (蒸馏)
echo "✓ 4 域初始数据完成"
(脚本细节根据实际执行命令调整; 本期最简方案: 直接手工 dacli kb add/entry 几十条, 不写脚本)
文档 commit:
cd /home/ubuntu/ccWorkDir/.claude
git add skills/dacli-ts/SKILL.md CLAUDE.md
git commit -m "CLAUDE.md + dacli-ts/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 <[email protected]>"
git push origin main
5. 完整验证清单
5.1 Commit 1 验证
cd /home/ubuntu/ccWorkDir/dacli
export PGHOST=postgres PGPORT=5432 PGUSER=ssw PGPASSWORD=<pwd> PGDATABASE=ssw
npx tsx src/cli.ts kb init
# 期望: "Schema 'ssw_kb' initialized: Tables (4): ... Triggers (1): ... Views (2): ..."
5.2 Commit 2 验证
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 验证
cd /home/ubuntu/ccWorkDir/dacli
npx tsx tests/test-kb.ts
# 期望: "=== 全部测试通过 ✓ ==="
5.4 源文件 md5 未变 (sanity check)
cd /home/ubuntu/ccWorkDir
md5sum dacli/src/cli.ts \
.claude/skills/dacli-ts/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-ts/ + .claude/CLAUDE.md)
5.5 AI 检索烟雾测试 (新会话)
新开会话, 输入:
我应该用什么 dacli 命令做 X?
期望 AI 输出 (之一):
- 调
dacli kb search "<X>"看是否有相关经验 - 或读
dacli/docs/cmd-review/命令审计 - 或调
dacli <command> --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-ts/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):
# dacli 仓
cd /home/ubuntu/ccWorkDir/dacli
git log --oneline -5 # 找到 3 个 commit hash
git revert <commit-3> # 单独 revert
git revert <commit-2>
git revert <commit-1>
# .claude 仓 (CLAUDE.md + SKILL.md)
cd /home/ubuntu/ccWorkDir/.claude
git log --oneline -5
git revert <kb-docs-commit>
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. 后续规划 (本次后)
- 业务扩容: 用户后续提需求时,
dacli kb add <new-domain> - pgvector 升级: KB > 200 条 + 语义查询时启用
- JSON 备份:
dacli kb export --json/import --json(pg COPY) - CI 集成: 检查 ssw_kb.domains 非空
- 知识图谱: 跨条目关系 (A 引用 B / A 矛盾 B)
- AI 自动入库: AI 解决新问题时自动
dacli kb entry
文档版本: 2026-07-02
关联 plan: /home/ubuntu/.claude/plans/piped-pondering-moon.md
作者: Claude Code (会话协作)