dsh-autolearn · DSH 自主学习插件（v2.0 / TypeScript）
把「学习目标 → 有界学习任务 → 可追溯知识库 → 证据核验 → 冲突检测 → 评估报告」
做成 DeepSeek Harness 的原生工具插件：一个 TypeScript 引擎，两个可选入口。
状态：v2.0.0。
- 业务逻辑全部在 TypeScript（
src/，11,126 行，46 模块），生产运行时 0 个外部依赖；
- 11 个 DSH 原生工具（由 60 个 MCP 工具收敛而来）+ 1 个用户侧 CLI；
- 保留可选 MCP 适配器（默认关闭，调用同一引擎）；
- 数据库 schema 与 v1.2 完全兼容（v7），旧知识库可直接打开；
- 测试：148 项 node:test 全过；旧 Python 实现保留为 legacy（197 项 pytest 仍可跑）。
详细审计、依赖地图、迁移状态与实测数据见 docs/refactor/。
架构
DSH Agent
│ ctx.tools.register（原生 JSON Schema + 运行时校验）
▼
adapters/dsh（11 工具 + 审批 hook） adapters/mcp（可选） cli（用户侧）
└──────────────┬───────────────────────┬───────────────┘
▼
application/services（唯一业务门面）
▼
Learning · Knowledge · Retrieval · Verification · Practice · Security · Storage
▼
node:sqlite（WAL/FTS 无关的自建倒排 + float32 向量索引）
- 0 个运行时循环依赖（脚本实测）。
- 业务逻辑不依赖 MCP 协议；原生与 MCP 入口调用同一套
AutolearnServices。
- 所有资源（SQLite 连接、索引文件锁、hook）在插件卸载时释放。
环境要求
| 项 | 要求 |
|---|
| Node.js | ≥ 22.6（使用内置 node:sqlite 与原生 TypeScript 运行测试） |
| DSH | 支持 Cordis 插件与 ctx.tools 的版本（本仓库验证于 0.2.0-rc.2 契约） |
| Python | 不需要（legacy 目录仅作参考） |
| 构建 | TypeScript 5.9（devDependency） |
安装与构建
# 1) 类型检查 + 构建（产出 dist/）
pnpm install # 常规环境
pnpm run typecheck
pnpm run build
# 若仓库位于 FAT/exFAT/共享存储（不支持 symlink），pnpm 会失败：
# npm i -g typescript && tsc -p tsconfig.build.json
把插件 link 进 DSH profile（路径按你的仓库位置替换）：
dsh plugin --profile web add link:/path/to/dsh-autolearn/plugins/autolearn
并在 profile 的 package.json 中确认：
{
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "...", "@local/dsh-autolearn"] } }
}
重启 DSH 后，模型可见工具为 learning_create / learning_run / knowledge_search 等 11 个。
引擎目录与旧数据
默认按以下顺序解析引擎目录（DSH_AL_HOME 可覆盖）：
DSH_AL_HOME<repo>/config.json 存在 → 仓库根<repo>/dsh_autonomous_learning/config.json 存在 → legacy 引擎目录（v1.2 的 data/ 在这里）- 仓库根
因此升级不会丢旧知识库；新目录也可以直接指向 data/。
| 环境变量 | 用途 | 缺省 |
|---|
DSH_AL_HOME | 引擎目录（config.json / data/） | 自动探测（见上） |
DSH_AL_DATA_DIR | 数据目录覆盖 | <home>/data |
DSH_AL_MODE | assisted / auto / lab | 配置文件 |
DSH_AL_ALLOW_NETWORK | 是否允许外部抓取 | false |
DSH_AL_CONFIG | 配置文件路径 | <home>/config.json |
DSH_AL_SETTINGS_FILE | 设置卡文件覆盖 | <home>/data/settings.json |
DSH_AL_LOG_LEVEL | DEBUG/INFO/WARNING/ERROR | INFO |
设置卡（DSH 插件设置页）修改的模式/每日预算/任务上限会在下一轮开始时生效（引擎重读 settings.json）；dataDir 变更需要重启。
11 个原生工具
| 工具 | 作用 | 风险 |
|---|
learning_create | 建项目 + 生成主题任务链（discover→extract→verify→practice + 缺口/评估/报告） | write |
learning_run | 跑一轮有界学习（预算/时长/任务数/停滞停止；失败重试与依赖阻塞） | write |
learning_status | 项目/任务/覆盖率/核验率/未达标项/最近运行/缺口 | read |
knowledge_search | BM25 + 特征哈希向量 + RRF 混合检索，带核验/冲突/时效/许可警告 | read |
knowledge_manage | save / update / invalidate / rollback / export / get / partitions | write（invalidate/rollback 需确认） |
knowledge_verify | verify / verify_formula / list_evidence / find_duplicates / detect_conflicts | read |
source_manage | discover / read / list（SSRF 防护、域名白名单、体积/超时限制） | read/external |
learning_evaluate | 覆盖率/核验率/来源完整率/冲突/实践通过率/成本 + 可选报告 | read |
learning_review | 失败/阻塞/耗尽重试/冲突/缺口复盘；可重置失败任务（需确认） | read/write |
system_diagnostics | 数据库/外键/索引一致性、schema、权限、网络策略、最近拒绝 | read |
system_maintenance | integrity / rebuild_index / backup / verify_backup / restore / delete_chunk / vacuum | destructive（宿主审批） |
审批：
- DSH 原生工具：
tools/pre-execute 返回 {kind:'ask'}，用户拒绝则不执行；判定异常失败关闭。
- MCP / CLI：使用本地确认令牌（作用域 = action + target、15 分钟有效、单次消费）。
用户侧 CLI
node dist/cli.js pending # 列出待确认操作
node dist/cli.js approve <token> # 批准（仅 user/CLI 通道）
node dist/cli.js reject <token> [note]
node dist/cli.js status [projectId]
node dist/cli.js diagnostics
node dist/cli.js search "滑点" <projectId>
可选 MCP 兼容层
node dist/adapters/mcp/server.js # stdio JSON-RPC 2.0
支持 initialize / tools/list / tools/call / ping；工具与原生入口完全同构（同一 buildNativeTools），不复制业务逻辑。默认不启用，避免与原生入口同时写同一数据库。
MCP 客户端配置示例：
{
"mcpServers": {
"autolearn": {
"command": "node",
"args": ["/path/to/dsh-autolearn/dist/adapters/mcp/server.js"],
"env": { "DSH_AL_HOME": "/path/to/dsh-autolearn/dsh_autonomous_learning" }
}
}
}
数据与兼容性
- schema：v7（与 v1.2 相同 DDL、相同迁移链、相同唯一索引/JSON/BOOL 编码）。
- 向量：
hashing:hashed-ngram:512，BLAKE2b-64 特征哈希；旧 vectors.npy / ids.json / manifest.json 可读，TS 写入的索引旧版也可读。
- 内容指纹、chunk_id、
normalizeText 与旧版逐字节一致（跨语言去重/幂等）。
- 备份：
system_maintenance(action=backup) 产出 SQLite 在线备份 + 索引目录 + sha256 清单；恢复前自动写 .pre-restore.sqlite3。
- 注意：文档正文存放在
data/documents/，不在 DB 备份清单内，备份 data 目录时需整体复制。
安全默认值（与旧版差异处已加严）
| 项 | 默认 | 说明 |
|---|
| 网络 | 关闭 | allow_network=true 才允许抓取；仅 http/https + 80/443/8080/8443 |
| SSRF | 默认拒绝私有/环回/链路本地/元数据/保留地址 | DNS 结果钉死到实际连接，逐跳重定向校验，防 rebinding |
| 路径 | 只允许授权根 + data 目录 | realpath 解析，符号链接逃逸与 ../ 都会被拒 |
| 密钥 | 写入知识库前扫描并拒绝 | sk-*/Bearer/AKIA/gh*/私钥等模式；日志脱敏 |
| 审批失败 | 失败关闭 | 判定异常 → ask，不自动放行 |
| 证据 | 无证据一律 fail | 观点/假设/未解决问题永远不能 verified；模型不能自称人工复核 |
| 检索作用域 | 无 project 作用域时只返回 visibility='global' | 防跨项目泄漏 |
测试
npm test # 148 tests / 31 suites（node:test）
npm run typecheck # strict TS
python3 -m pytest dsh_autonomous_learning/tests -q # legacy 基线：197 passed
覆盖：类型检查、单元、数据库集成、知识与全文检索、向量/索引一致性、版本回滚、任务恢复、预算、权限、审批拒绝、SSRF、路径穿越、跨项目隔离、并发写、备份恢复、DSH 工具注册/卸载、MCP 真实子进程、CLI 审批、旧库兼容。
故障恢复
| 症状 | 处理 |
|---|
| 索引与元数据不一致 | system_maintenance(action=integrity) 查看；rebuild_index 重建 |
| 误删/误改知识 | knowledge_manage(action=rollback, version=N)；或从备份 restore |
| 备份恢复被拒 | verify_backup 查看 issues（校验和/版本/清单）；校验失败时不会动原库 |
| 任务卡在 running | 下一轮 learning_run 自动 recover()；也可等超时后重试 |
| 插件加载失败 | 确认已 pnpm build（dist/ 存在）、Node ≥22.6、@local/dsh-autolearn 在 bundles |
| 需要回滚到 v1.2 | git checkout baseline-python-v1.2；数据库 v7 双向可读 |
已知限制（不假装完成）
- PDF/DOCX 解析未迁移：会明确报错并建议转换为 Markdown/TXT；HTML 用正则清洗（非 DOM）。
- 模型辅助（规划/抽取提议）未迁移：
use_model=true 会返回明确警告，只走规则链路。
- 代码执行只支持 JavaScript，仅 lab 模式、进程级隔离（不是安全沙箱）；Python 代码执行已移除。
- 调度 tick / 实验运行器 / 知识图谱查询 / 检索评测集未迁移（表结构保留）。
- 哈希向量是词汇级召回，不是语义模型；未做检索质量评测，不宣称提升。
- 真实 DSH profile 启动验证被缺失模型凭据阻塞；插件注册由契约级测试 + MCP 子进程验证覆盖。
docs/refactor/audit.md 记录了旧版 8 项安全缺陷与修复状态。
目录结构
src/
index.ts # 引擎装配（唯一 DI 点）
cli.ts # 用户侧 CLI（审批/诊断/检索）
core/ # 类型、错误、配置、校验、ID
security/ # 权限、审批、路径、网络、预算、审计、密钥
infrastructure/
database/ # schema(v7)/迁移/连接/事务/备份
retrieval/ # 分词器 + BM25
embeddings/ # BLAKE2b / 特征哈希 / npy / 向量索引
sources/ # 发现 / 读取 / 解析 / 元数据
domain/
knowledge/ # 存储、提取、质量、领域/分区
learning/ # 状态机、规划、缺口、评估、编排、报告、仓储
practice/ # 练习生成、公式求值、受限执行
application/services.ts # 11 个业务接口
adapters/dsh|mcp/ # 入口适配
tests/{unit,integration,security,regression}/
docs/refactor/ # 审计 / 依赖地图 / 迁移计划 / 阶段报告
dsh_autonomous_learning/ # legacy v1.2（保留，非默认运行时；迁移完成后再删除）
plugins/autolearn/ # Cordis 插件：设置卡 + 原生工具注册
plugins/approval/ # legacy MCP 审批闸门（原生工具不再依赖它）
许可
MIT
