# Context Management > Use this skill to manage project context (DB config, service endpoints, etc.) stored in PostgreSQL and automatically surface it to Copilot on every conversation. - Skill: `wenboli-cn-de/context-management` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add wenboli-cn-de/context-management` - Raw SKILL.md: https://api.skillmd.com/api/skills/wenboli-cn-de/context-management/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: WenboLi-CN-DE (https://skillmd.com/u/wenboli-cn-de) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/wenboli-cn-de/context-management --- # Context Management 将项目配置（数据库地址、服务端口、密钥占位符等）集中存储在 PostgreSQL，并在每次 Copilot 对话中自动附带最新快照。 --- ## ⚠️ 强制对话钩子（每次对话必须执行） 每次对话分为**三个强制阶段**，缺一不可： | 阶段 | 时机 | 操作 | |------|------|------| | 🔵 **读取快照** | 回答任何问题之前 | 读取 `docs/superpowers/context/project-context.md` | | 🔍 **检索历史** | 回答之前 | `search-qa "<关键词>" --limit 5`，有结果则引用 | | 💾 **入库存档** | 回答完成之后 | `save-qa "<问题>" "<回答摘要>" --topic "<主题>"` | > 跳过任何一个阶段都视为违反工作流。 --- ## 核心理念 - **单一来源** — 所有配置存入数据库，不散落在 `.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. 初始化（首次） ```bash # 初始化数据库表（context_entries + qa_history，幂等） python skills/context-management/scripts/context_manager.py \ --host 10.235.228.82 --user postgres --password --dbname agent \ init # 导入项目默认配置 python skills/context-management/scripts/init_project_context.py \ --host 10.235.228.82 --user postgres --password --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. 生成 / 刷新快照 ```bash python skills/context-management/scripts/context_manager.py \ --host 10.235.228.82 --user postgres --password --dbname agent \ snapshot --output .github/docs/superpowers/context/project-context.md ``` ### 3. 动态添加配置项 ```bash # 普通配置 python skills/context-management/scripts/context_manager.py \ --host 10.235.228.82 --user postgres --password --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 --dbname agent \ set sql_password "P@ssw1rd" --category database --secret ``` ### 4. 跨会话检索（按需实时查询） 快照文件适合 Copilot 读取，**跨会话程序调用**应直接查数据库： ```bash # 查单个 key（secret 默认遮蔽） python skills/context-management/scripts/context_manager.py \ --host 10.235.228.82 --user postgres --password --dbname agent \ get sql_host # 批量查询某 category（JSON 输出） python skills/context-management/scripts/context_manager.py \ --host 10.235.228.82 --user postgres --password --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 代码内调用：** ```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. 🔴 问答历史（强制：每次对话开始时检索，结束时入库） > ⚠️ **这不是可选功能，是强制工作流的一部分。** **对话开始时：先检索，再回答** ```bash # 按关键词检索（先全文，无结果自动降级 ILIKE 模糊搜索） python skills/context-management/scripts/context_manager.py \ --host 10.235.228.82 --user postgres --password --dbname agent \ search-qa "<用户问题关键词>" --limit 5 # 留空返回最近 5 条 python skills/context-management/scripts/context_manager.py \ --host 10.235.228.82 --user postgres --password --dbname agent \ search-qa ``` **对话结束后：立即入库** ```bash python skills/context-management/scripts/context_manager.py \ --host 10.235.228.82 --user postgres --password --dbname agent \ save-qa "用户的完整问题" "本次回答的摘要" --topic "主题标签" ``` **Python 代码内调用：** ```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"]) ``` --- ## 数据库表结构 ```sql -- 配置项表 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 提问时，它会自动读取该文件并将配置信息纳入回答的上下文中。