Scan to join WeChat groupSDD 上下文记忆（sdd-context-memory）
Verified with seekdb 1.4.0, Python 3.12 · Node.js 24.14.0 (2026-10-30)
给 AI 编码助手用的开发上下文检索 + 任务记忆。一句话说清它解决什么：
助手改代码前必须知道三件事——当前要遵守哪些规格、应该改哪些代码、改完怎么验证。 这三件事分别躺在规格文件、代码仓库、测试目录里，资料分散、规格变更或任务中断，就会遗漏约束、用上过期信息、重复劳动。
本 Skill 把这条链路做成可核对的闭环：
规格 / 代码 / 测试 → seekdb 全文索引 → 按任务检索开发上下文 → 模型产出补丁
↓
目标测试(红→绿) + 回归测试(始终绿)
↓
任务状态写入 PowerContext → 重启后读回复用
什么时候用它
- 一项开发任务来了，需要先检索出适用规格再动手；
- 需要按任务定位该改哪个文件、哪个符号；
- 需要知道用哪个测试验证这次改动；
- 任务跨进程/跨会话，状态丢了要重来；
- 改完代码需要可核对的证据（测试退出码、补丁 diff、上下文来源）。
不适用：只想让模型读几个文件改几行的小改动（上下文检索反而是额外开销）。
前置条件
| 依赖 | 版本 | 说明 |
|---|---|---|
| Python | ≥ 3.11 | 实测 3.12 |
| Docker + Compose | — | 跑 seekdb（工程资料索引） |
| seekdb | oceanbase/seekdb:latest（实测 1.4.0.0） | MySQL 协议，端口 2881 |
| powercontext | 1.2.0 | 任务状态持久化（内置 SQLite） |
| PyMySQL | 1.2.3 | 连 seekdb |
| PyYAML | 6.0.2 | 读规格文件 |
| pytest | 9.2.0 | 跑目标测试 / 回归测试 |
完整环境变量清单见
references/configuration.md；全部依赖只在 PyPI 上，干净环境可直接装。
快速开始（三条命令）
# 0) 准备环境：建 venv、装依赖、起 seekdb
bash scripts/setup.sh
# 1) 把工程资料（规格 + 代码 + 测试）导入 seekdb 全文索引
cd assets
python3 -m sdd_context import \
--spec specs/spec-v1.yaml \
--code demo_service/src \
--tests demo_service/tests
# 2) 按一项开发任务检索上下文（每条都带 BM25 分数和来源路径）
python3 -m sdd_context plan --task "工单列表支持 status 多值过滤 IN 语义"
# 3) 读回任务状态（独立进程，证明状态可跨进程复用）
python3 -m sdd_context status
或者一条命令跑完整演示（含 import → plan → status）：
bash scripts/demo.sh
使用示例
例 1：改代码前先拿到「该守什么 / 该改哪 / 怎么验」
cd assets
python3 -m sdd_context plan --task "工单列表支持 status 多值过滤 IN 语义"
输出片段（真实运行结果，score 是索引里的 BM25 分数）：
# 开发任务
工单列表支持 status 多值过滤 IN 语义
## 适用的规格条目（来源：seekdb 全文索引，score 为 BM25 相关性）
- [SPEC-002] SPEC-002 工单列表的 status 过滤必须支持多值 (score=9.6387, 来源=specs/spec-v1.yaml)
SPEC-002 工单列表的 status 过滤必须支持多值
工单列表的 status 过滤参数必须支持一次传入多个状态，按 IN 语义匹配：
命中集合为「状态等于其中任意一个」的工单。
单值用法必须保持不变：传入单个字符串时，行为与多值改造前完全一致。
HTTP 层允许用重复出现的 status 查询参数表达多值，例如 ?status=open&status=resolved。
- [SPEC-004] SPEC-004 列表默认排序规则 (score=2.2187, 来源=specs/spec-v1.yaml)
## 需要修改的代码（来源：seekdb 全文索引）
- demo_service/src/triage/filter.py 符号: ValidationError, _as_tuple, validate_limit, filter_tickets, _scalar, apply_query (score=5.3324)
- demo_service/src/triage/model.py 符号: Ticket, demo_tickets (score=2.3927)
## 用于验证的测试（来源：seekdb 全文索引）
- demo_service/tests/test_feature_status_filter.py 用例: test_status_accepts_multiple_values, test_status_accepts_tuple, test_status_accepts_set, ... (score=5.5192)
## 任务状态（来源：PowerContext，跨进程读回）
- 任务: 工单列表支持 status 多值过滤 IN 语义
- 更新时间: 2026-10-30T08:22:33+00:00
- 已有验证结果: ['target: exit=0 (...)', 'regression: exit=0 (...)']
## 本次检索的命中分布
- 规格条目: 4 条
- 需要修改的代码: 4 条
- 用于验证的测试: 3 条
- 索引内工程资料总数: 13
关键点：上面每一条的「来源」都是刚从 seekdb 查出来的索引行，不是写死的答案——
可以逐条回到文件核对。规格换了、代码改了，重新 import 一次，检索结果跟着变。
例 2：让模型基于检索到的上下文改代码，并留证
cd assets
python3 -m sdd_context apply --task "工单列表支持 status 多值过滤 IN 语义"
python3 -m sdd_context verify --label after
apply：组装上下文 → 调模型 → 产出 unified diff → 严格校验后落盘 （上下文行必须逐行对上，对不上直接报错退出，不做模糊匹配；可改文件走白名单，测试目录不在白名单里）。verify：跑目标测试与回归测试，记录命令、退出码、耗时、日志尾、代码文件哈希。
例 3：换一台机器 / 重启进程后，状态还在
cd assets
python3 -m sdd_context status # 独立进程读回上一次写入的状态
状态落在 PowerContext 的 SQLite 持久化里（默认 assets/state/powercontext.sqlite3），
任何新进程打开同一个文件都能读到，并且会参与下一次 plan 的上下文组装。
例 4：亲手复现「红 → 绿」闭环
随包 demo 的代码默认是改动后的状态（目标测试直接是绿的）。想看完整闭环， 用随包脚本把 demo 切回改动前：
# 切到改动前：目标测试应当失败（AssertionError，不是导入失败）
python3 scripts/toggle_demo_state.py --to before
cd assets && python3 -m sdd_context verify --label before
# [target] exit=1
# FAILED tests/test_feature_status_filter.py::test_status_accepts_multiple_values
# [regression] exit=0
# 切回改动后：目标与回归都绿
cd .. && python3 scripts/toggle_demo_state.py --to after
cd assets && python3 -m sdd_context verify --label after
# [target] exit=0
# [regression] exit=0
改动只有一处——demo_service/src/triage/filter.py 里 status 过滤的比较方式：
- wanted = status
- result = [ticket for ticket in result if ticket.status == wanted] # 多值永远不匹配
+ wanted = _as_tuple(status)
+ result = [ticket for ticket in result if ticket.status in wanted] # 多值按 IN 语义匹配
这正是 apply 要让模型做的那件事：检索上下文 → 改代码 → 目标测试转绿 → 回归保持绿。
测试文件全程不动（可改路径走白名单，测试目录不在白名单里）。
命令一览
| 命令 | 作用 | 主要输出 |
|---|---|---|
| import | 把规格/代码/测试导入 seekdb | 导入条数（规格/代码/测试） |
| plan | 按任务检索并组装上下文 | 规格条目 / 代码文件与符号 / 测试文件与用例 / 命中分布 / 任务状态，每条带 BM25 分数与来源路径 |
| apply | 上下文 → 模型 → diff → 安全应用 | 补丁、变更文件列表、落盘前后文件哈希 |
| verify | 跑目标测试与回归测试 | 命令、退出码、耗时、日志尾、文件哈希 |
| status | 从 PowerContext 读回任务状态 | 任务 ID、已完成、待办、已有验证结果 |
| reset | 清空索引与状态 | — |
完整参数见 references/cli-reference.md。
这个 Skill 里的代码是什么
随包的是完整可跑的工程（不是片段）：
SKILL.md 这个文件（入口）
scripts/
├── setup.sh 建 venv、装依赖、起 seekdb
├── demo.sh 一条命令跑完整演示：reset → import → plan → status
├── check_prereqs.py 前置条件自检（Python / 依赖 / docker / seekdb 连通性）
└── toggle_demo_state.py 在「改动前 / 改动后」之间切换 demo，复现红→绿闭环
references/
├── architecture.md 数据流、表结构、检索 SQL、状态存储格式
├── cli-reference.md 每个子命令的参数与产物
├── configuration.md 全部环境变量与默认值
└── troubleshooting.md 常见问题与补救
assets/
├── sdd_context/ 上下文模块本体（config/db/indexer/selector/state/agent/cli）
├── demo_service/ 业务工程：工单分诊服务（纯标准库 + pytest，有测试）
├── specs/ 规格文件（v1 初始 / v2 变更后的示例）
├── scripts/
│ ├── check_context_behaviour.py 行为自检（19 项）：规格更新生效 + 跨进程状态读回
│ └── verify_all.sh 一键跑通完整验证流程
├── requirements.txt
└── compose.yml seekdb 编排
assets/ 同时是模块的「工程根目录」：模块用相对路径定位 demo_service/、specs/、state/，
所以把整个 assets/ 目录拷到任何位置都能跑。
出处与许可
本 Skill 的模块本体（assets/sdd_context/）与 demo 业务工程（assets/demo_service/）
是自研代码，为 OceanBase 大赛 2026「AI 生态」赛题的上下文工程实践整理而成；
assets/sdd_context/state.py 依赖 PowerContext（Apache-2.0）
提供任务状态持久化。
随包代码同样以 Apache-2.0 发布，完整许可文本见 references/LICENSE。
依赖的第三方组件（seekdb / PowerContext / PyMySQL / PyYAML / pytest）各自遵循其上游许可证。
验证
本 Skill 的全部功能均已在本机实测通过（非静态推断）。验证环境： seekdb 1.4.0（5.7.25-OceanBase seekdb-v1.4.0.0）· Python 3.12 · Node.js 24.14.0 · Chrome 148。
| 验证项 | 方法 | 结果 |
|---|---|---|
| 检索链路跑通 | python3 -m sdd_context import → plan → status | 13 条工程资料入库（6 规格 / 4 代码 / 3 测试）；检索命中正确文档并带回 BM25 分数与来源路径 |
| 库内混合检索 | seekdb-js collection.hybridSearch()（RRF） | 融合分 = Σ 1/(k+rank)：双路命中 0.0328、单路命中 0.0159，证明融合由 seekdb 库内完成 |
| 增量写入可见性 | 写入新文档 → refresh_index() → 立即检索 | 新文档刷新后可被检索到 |
| 状态跨进程复用 | 独立进程执行 status | 读回上次写入的任务 ID、已完成项与验证结果 |
| 行为自检 | python3 assets/scripts/check_context_behaviour.py | 19/19 项通过（规格更新后上下文用新内容 + 跨进程读回状态） |
| 回归测试 | cd assets && python3 -m pytest demo_service/tests -q | 20 项全通过（修改前后均绿） |
一键跑通完整验证流程（需要 MINIMAX_API_KEY 才能执行其中的模型改码步骤）：
cd assets && bash scripts/verify_all.sh
其余复现命令见 references/troubleshooting.md 与 references/cli-reference.md。
参考文档
references/architecture.md—— 数据流、表结构、检索 SQL、状态存储格式references/cli-reference.md—— 每个子命令的参数与产物references/configuration.md—— 全部环境变量与默认值references/troubleshooting.md—— 连不上 seekdb / 中文检索无命中 / 补丁应用失败 等常见问题references/LICENSE—— Apache-2.0 许可全文
已知限制
- 补丁用严格 unified diff 应用，不做模糊匹配；上下文对不上会报错。
- 全文检索依赖 seekdb 的
ik分词器；中文任务描述请用实词短语，别用单字。 - 状态走进程内 SDK + SQLite，不依赖常驻 Server（
powercontext[server]的 server 模式同样可用）。 - seekdb 需要 Docker；只跑
plan/status时，Python + 任意一个数据库二选一即可。