Files
dacli/docs/cmd-review/kb-implementation-plan.md
T
ssw 209f8d50d6 fix(docs): 修复规范文档过时示例 (--ai-json→--ai, v0.13+)
- §1 修订说明: v0.11+→v0.13+ (--ai-json 已于 BS-新28 删除)
- §6.6 错误处理: --ai-json=→--ai=
- §10.2 一条龙: 整段替换为 --ai 描述模式
- §10 状态机: v0.11+→v0.13+
- 确认 --autoTable / --autoRelease 仍有效
2026-07-03 16:46:03 +08:00

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 个技术基础设施域 (本期初始化, 无业务信息):

  1. dacli — CLI 工具 (命令/架构/盲点)
  2. jnpf — 平台基线 (约束/机制)
  3. ssw-loop — 开发循环 (7 阶段/4 关卡)
  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. 后续规划 (本次后)

  1. 业务扩容: 用户后续提需求时, dacli kb add <new-domain>
  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 (会话协作)