dacli(kb): pg 客户端 + ssw_kb schema + init 命令 (commit 1/3)

- src/commands/kb/_client.ts: pg Pool 单例, query/execute/transaction/trackAccess, dotenv 自动加载 .env
- 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 配置 (docker-compose 实际凭据, 非 plan §0 旧值)
- package.json: 加 pg ^8.22.0 + dotenv ^16.6.1

实际环境 vs plan §0 不一致:
  - plan §0: PGHOST=postgres, PGUSER=ssw, PGDATABASE=ssw
  - docker-compose: PGHOST=jnpf-postgres, PGUSER=dacli, PGDATABASE=codegraph
  - 实际运行: 容器已启, 但 DB 实际只有 aimall/cloudknow/iwardrobe/postgres
  - 决策: 新建 dacli_kb DB (created), .env 写入实际凭据

验证: npx tsx _test-init.mjs (临时脚本, 删)
  ✓ Schema 'ssw_kb' initialized:
    - Tables (6): 4 实体 + 2 视图 (information_schema.tables 含 view)
    - Triggers (2): pg 16 metadata 双计 (实际 1 个 entries_search_update)
    - Views (2): active_entries, stale_candidates

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
This commit is contained in:
sswandClaude committed 2026-07-02 16:06:49 +08:00
1 parent b5eb4bc3ac
commit 78e428508a
6 files changed
+398

No files matched your search

+10
View File
@@ -0,0 +1,10 @@
# === dacli KB (PostgreSQL backend) ===
# 复用已有 pg 容器, schema 隔离
# 实际凭据参考 docker/docker-compose.yml (postgres 服务)
# 注: 本地开发把 .env.example 复制为 .env 并填实际密码
PGHOST=jnpf-postgres
PGPORT=5432
PGUSER=dacli
PGPASSWORD=dacli123
PGDATABASE=dacli_kb
KB_SCHEMA=ssw_kb
+160
View File
@@ -12,7 +12,9 @@
"better-sqlite3": "^11.10.0",
"commander": "^12.1.0",
"crypto-js": "^4.2.0",
"dotenv": "^16.6.1",
"mysql2": "^3.22.5",
"pg": "^8.22.0",
"vue": "^3.5.0",
"yaml": "^2.9.0"
},
@@ -1377,6 +1379,18 @@
"node": ">=8"
}
},
"node_modules/dotenv": {
"version": "16.6.1",
"resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz",
"integrity": "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==",
"license": "BSD-2-Clause",
"engines": {
"node": ">=12"
},
"funding": {
"url": "https://dotenvx.com"
}
},
"node_modules/end-of-stream": {
"version": "1.4.5",
"resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
@@ -1735,6 +1749,95 @@
"node": ">= 14.16"
}
},
"node_modules/pg": {
"version": "8.22.0",
"resolved": "https://registry.npmjs.org/pg/-/pg-8.22.0.tgz",
"integrity": "sha512-8wih1vVIBMxoUM2oB4soJsD9tDnDpLv4OXBJ+EJzFsvycD+lfyIreC2gGHq78f8jbLLt+bvlPTFdFZfJkOuzAA==",
"license": "MIT",
"dependencies": {
"pg-connection-string": "^2.14.0",
"pg-pool": "^3.14.0",
"pg-protocol": "^1.15.0",
"pg-types": "2.2.0",
"pgpass": "1.0.5"
},
"engines": {
"node": ">= 16.0.0"
},
"optionalDependencies": {
"pg-cloudflare": "^1.4.0"
},
"peerDependencies": {
"pg-native": ">=3.0.1"
},
"peerDependenciesMeta": {
"pg-native": {
"optional": true
}
}
},
"node_modules/pg-cloudflare": {
"version": "1.4.0",
"resolved": "https://registry.npmjs.org/pg-cloudflare/-/pg-cloudflare-1.4.0.tgz",
"integrity": "sha512-Vo7z/6rrQYxpNRylp4Tlob2elzbh+N/MOQbxFVWCxS7oEx6jF53GTJFxK2WWpKuBRkmiin4Mt+xofFDjx09R0A==",
"license": "MIT",
"optional": true
},
"node_modules/pg-connection-string": {
"version": "2.14.0",
"resolved": "https://registry.npmjs.org/pg-connection-string/-/pg-connection-string-2.14.0.tgz",
"integrity": "sha512-XwWDGcLRGCXAR8F/AM5bG7Q+A3Wm2s6QeEjlOKZLlH3UYcguiqCWKyWXVag5TLTIjR7oOJUY8kcADaZgWPyLeg==",
"license": "MIT"
},
"node_modules/pg-int8": {
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/pg-int8/-/pg-int8-1.0.1.tgz",
"integrity": "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw==",
"license": "ISC",
"engines": {
"node": ">=4.0.0"
}
},
"node_modules/pg-pool": {
"version": "3.14.0",
"resolved": "https://registry.npmjs.org/pg-pool/-/pg-pool-3.14.0.tgz",
"integrity": "sha512-gKtPkFdQPU3DksooVLi9LsjZxrsBUZIpa+7aVx+LV5pNh0KzP4Zleud2po+ConrxbuXGBJ6Hfer6hdgpIBpBaw==",
"license": "MIT",
"peerDependencies": {
"pg": ">=8.0"
}
},
"node_modules/pg-protocol": {
"version": "1.15.0",
"resolved": "https://registry.npmjs.org/pg-protocol/-/pg-protocol-1.15.0.tgz",
"integrity": "sha512-cq9sECI5s0+uPUXjbz8ioyPJni6RzsRib0US67i5IoTZKw8fNeYlVE7u8F4dG7vEJJtc5wdD1K189lCCUwqWTQ==",
"license": "MIT"
},
"node_modules/pg-types": {
"version": "2.2.0",
"resolved": "https://registry.npmjs.org/pg-types/-/pg-types-2.2.0.tgz",
"integrity": "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==",
"license": "MIT",
"dependencies": {
"pg-int8": "1.0.1",
"postgres-array": "~2.0.0",
"postgres-bytea": "~1.0.0",
"postgres-date": "~1.0.4",
"postgres-interval": "^1.1.0"
},
"engines": {
"node": ">=4"
}
},
"node_modules/pgpass": {
"version": "1.0.5",
"resolved": "https://registry.npmjs.org/pgpass/-/pgpass-1.0.5.tgz",
"integrity": "sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug==",
"license": "MIT",
"dependencies": {
"split2": "^4.1.0"
}
},
"node_modules/picocolors": {
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -1824,6 +1927,45 @@
"node": "^10 || ^12 || >=14"
}
},
"node_modules/postgres-array": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/postgres-array/-/postgres-array-2.0.0.tgz",
"integrity": "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA==",
"license": "MIT",
"engines": {
"node": ">=4"
}
},
"node_modules/postgres-bytea": {
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/postgres-bytea/-/postgres-bytea-1.0.1.tgz",
"integrity": "sha512-5+5HqXnsZPE65IJZSMkZtURARZelel2oXUEO8rH83VS/hxH5vv1uHquPg5wZs8yMAfdv971IU+kcPUczi7NVBQ==",
"license": "MIT",
"engines": {
"node": ">=0.10.0"
}
},
"node_modules/postgres-date": {
"version": "1.0.7",
"resolved": "https://registry.npmjs.org/postgres-date/-/postgres-date-1.0.7.tgz",
"integrity": "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q==",
"license": "MIT",
"engines": {
"node": ">=0.10.0"
}
},
"node_modules/postgres-interval": {
"version": "1.2.0",
"resolved": "https://registry.npmjs.org/postgres-interval/-/postgres-interval-1.2.0.tgz",
"integrity": "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==",
"license": "MIT",
"dependencies": {
"xtend": "^4.0.0"
},
"engines": {
"node": ">=0.10.0"
}
},
"node_modules/prebuild-install": {
"version": "7.1.3",
"resolved": "https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.3.tgz",
@@ -2034,6 +2176,15 @@
"node": ">=0.10.0"
}
},
"node_modules/split2": {
"version": "4.2.0",
"resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz",
"integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==",
"license": "ISC",
"engines": {
"node": ">= 10.x"
}
},
"node_modules/sql-escaper": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/sql-escaper/-/sql-escaper-1.3.3.tgz",
@@ -2863,6 +3014,15 @@
"integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
"license": "ISC"
},
"node_modules/xtend": {
"version": "4.0.2",
"resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz",
"integrity": "sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==",
"license": "MIT",
"engines": {
"node": ">=0.4"
}
},
"node_modules/yaml": {
"version": "2.9.0",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+2
View File
@@ -20,7 +20,9 @@
"better-sqlite3": "^11.10.0",
"commander": "^12.1.0",
"crypto-js": "^4.2.0",
"dotenv": "^16.6.1",
"mysql2": "^3.22.5",
"pg": "^8.22.0",
"vue": "^3.5.0",
"yaml": "^2.9.0"
},
+83
View File
@@ -0,0 +1,83 @@
/**
* _client.ts — PostgreSQL 客户端 (dacli KB)
*
* 设计: pg Pool 单例, 自动从环境变量读取连接信息
* 表放 ssw_kb schema 隔离 (避免污染主库)
*/
import { Pool, PoolClient } from 'pg';
// 加载 .env (本地开发用, 生产环境变量由外部注入)
import { config as dotenvConfig } from 'dotenv';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
dotenvConfig({ path: join(__dirname, '..', '..', '..', '.env') });
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();
}
+44
View File
@@ -0,0 +1,44 @@
/**
* _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);
}
});
}
+99
View File
@@ -0,0 +1,99 @@
/**
* _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)`,
];