Context Management

Context Management

将项目配置（数据库地址、服务端口、密钥占位符等）集中存储在 PostgreSQL，并在每次 Copilot 对话中自动附带最新快照。

⚠️ 强制对话钩子（每次对话必须执行）

每次对话分为三个强制阶段，缺一不可：

跳过任何一个阶段都视为违反工作流。

核心理念

• 单一来源 — 所有配置存入数据库，不散落在 .env 或硬编码。
• 密码遮蔽 — is_secret=true 的字段在快照中显示为 ***。
• 可测试 — 生成逻辑有单元测试覆盖（tests/unit/test_context_snapshot.py）。
• 可复用 — 快照由 copilot-instructions.md 引用，Copilot 每次自动读取。
• 问答持久化 — 每次问答自动入库，支持跨会话全文检索，形成知识积累。

文件结构

skills/context-management/
  SKILL.md                          ← 本文档
  scripts/
    context_manager.py              ← 核心库 + CLI
    init_project_context.py         ← 一次性初始化脚本（写入项目默认配置）
.github/docs/superpowers/context/
  project-context.md                ← 自动生成的快照（由 CI 或手动刷新）
tests/unit/
  test_context_snapshot.py          ← TDD 单元测试

使用流程

1. 初始化（首次）

# 初始化数据库表（context_entries + qa_history，幂等）
python skills/context-management/scripts/context_manager.py \
  --host 10.235.228.82 --user postgres --password <pwd> --dbname agent \
  init

# 导入项目默认配置
python skills/context-management/scripts/init_project_context.py \
  --host 10.235.228.82 --user postgres --password <pwd> --dbname agent

💡 自动表检测与重建：所有 CLI 命令、auto_connect() 以及每个公共 API 函数（get_context、query_context、upsert_context、save_qa、search_qa、generate_snapshot）在执行前都会通过 is_tables_initialized(conn) 查询 information_schema.tables，自动判断表是否存在。若表被删除，下次调用任意函数即自动重建，无需手动执行 init 命令。

2. 生成 / 刷新快照

python skills/context-management/scripts/context_manager.py \
  --host 10.235.228.82 --user postgres --password <pwd> --dbname agent \
  snapshot --output .github/docs/superpowers/context/project-context.md

3. 动态添加配置项

# 普通配置
python skills/context-management/scripts/context_manager.py \
  --host 10.235.228.82 --user postgres --password <pwd> --dbname agent \
  set sql_host 10.235.228.82 --category database

# 敏感配置（快照中显示 ***）
python skills/context-management/scripts/context_manager.py \
  --host 10.235.228.82 --user postgres --password <pwd> --dbname agent \
  set sql_password "P@ssw1rd" --category database --secret

4. 跨会话检索（按需实时查询）

快照文件适合 Copilot 读取，跨会话程序调用应直接查数据库：

# 查单个 key（secret 默认遮蔽）
python skills/context-management/scripts/context_manager.py \
  --host 10.235.228.82 --user postgres --password <pwd> --dbname agent \
  get sql_host

# 批量查询某 category（JSON 输出）
python skills/context-management/scripts/context_manager.py \
  --host 10.235.228.82 --user postgres --password <pwd> --dbname agent \
  query --category database

# 带完整元数据（含 category / is_secret）
python skills/context-management/scripts/context_manager.py ... query --metadata

# 显示 secret 明文（谨慎使用）
python skills/context-management/scripts/context_manager.py ... get sql_password --reveal

Python 代码内调用：

import psycopg2
from skills.context_management.scripts.context_manager import get_context, query_context

conn = psycopg2.connect(host="10.235.228.82", user="postgres", password="...", dbname="agent")

# 单条（secret 默认 ***)
host = get_context(conn, "sql_host")       # "10.235.228.82"
pwd  = get_context(conn, "sql_password")   # "***"

# 批量（按 category 过滤）
db = query_context(conn, category="database")
# {"sql_host": "10.235.228.82", "sql_port": "5432", "sql_password": "***", ...}

# 带元数据
full = query_context(conn, include_metadata=True)
# {"sql_host": {"value": "10.235.228.82", "category": "database", "is_secret": False}, ...}

5. 🔴 问答历史（强制：每次对话开始时检索，结束时入库）

⚠️ 这不是可选功能，是强制工作流的一部分。

对话开始时：先检索，再回答

# 按关键词检索（先全文，无结果自动降级 ILIKE 模糊搜索）
python skills/context-management/scripts/context_manager.py \
  --host 10.235.228.82 --user postgres --password <pwd> --dbname agent \
  search-qa "<用户问题关键词>" --limit 5

# 留空返回最近 5 条
python skills/context-management/scripts/context_manager.py \
  --host 10.235.228.82 --user postgres --password <pwd> --dbname agent \
  search-qa

对话结束后：立即入库

python skills/context-management/scripts/context_manager.py \
  --host 10.235.228.82 --user postgres --password <pwd> --dbname agent \
  save-qa "用户的完整问题" "本次回答的摘要" --topic "主题标签"

Python 代码内调用：

from skills.context_management.scripts.context_manager import auto_connect, save_qa, search_qa

# auto_connect 自动建表，无需预先 init
conn = auto_connect()  # 使用项目默认配置

# 每次问答结束后持久化
qa_id = save_qa(conn, question="如何配置数据库？", answer="...", topic="database")

# 下次提问前先检索历史
history = search_qa(conn, "数据库配置", limit=3)
for item in history:
    print(item["question"], "→", item["answer"])

数据库表结构

-- 配置项表
CREATE TABLE context_entries (
    id          SERIAL PRIMARY KEY,
    category    TEXT NOT NULL DEFAULT 'general',
    key         TEXT NOT NULL UNIQUE,
    value       TEXT NOT NULL,
    is_secret   BOOLEAN NOT NULL DEFAULT FALSE,
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 问答历史表（带全文索引）
CREATE TABLE qa_history (
    id          SERIAL PRIMARY KEY,
    topic       TEXT NOT NULL DEFAULT 'general',
    question    TEXT NOT NULL,
    answer      TEXT NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    tsv         TSVECTOR GENERATED ALWAYS AS (
                    to_tsvector('simple', question || ' ' || answer)
                ) STORED
);
CREATE INDEX qa_history_tsv_idx ON qa_history USING GIN(tsv);

与 Copilot 集成

快照路径 docs/superpowers/context/project-context.md 已在 .github/copilot-instructions.md 中声明为强制上下文。 每次向 Copilot 提问时，它会自动读取该文件并将配置信息纳入回答的上下文中。