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），旧知识库可直接打开；
• 测试：171 项 node:test 全过；旧 Python 实现保留为 legacy（197 项 pytest 仍可跑）。

• 审计/评测/性能基线：reports/（含 12 份报告与原始 JSON），可重复脚本见 scripts/。

详细审计、依赖地图、迁移状态与实测数据见 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 可覆盖）：

1. DSH_AL_HOME
2. <repo>/config.json 存在 → 仓库根
3. <repo>/dsh_autonomous_learning/config.json 存在 → legacy 引擎目录（v1.2 的 data/ 在这里）
4. 仓库根

因此升级不会丢旧知识库；新目录也可以直接指向 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'	防跨项目泄漏
代码执行	strict 沙盒	降权 nobody + unshare -n 网络命名空间 + Node --permission（仅产物目录可读写，禁 child_process/worker/addons）；能力不足时失败关闭，process 需显式配置

测试

npm test             # 171 tests / 42 suites（node:test）
npm run typecheck    # strict TS
python3 -m pytest dsh_autonomous_learning/tests -q   # legacy 基线：197 passed

覆盖：类型检查、单元、数据库集成、知识与全文检索、向量/索引一致性、版本回滚、任务恢复、预算、权限、审批拒绝、SSRF（含 IPv6）、路径穿越、跨项目隔离、并发写、备份恢复、DSH 工具注册/卸载、MCP 真实子进程、CLI 审批、旧库兼容、本地 HTTP 抓取策略、Prompt Injection、代码执行沙盒逃逸/超时/配额。

故障恢复

症状	处理
索引与元数据不一致	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 双向可读

2026-10-20 · 插件 entry 激活失败（webServer 未注入）

现象：启动日志出现 cannot get property "webServer" without inject，紧随 autolearn (@local/dsh-autolearn): Error: … 与 dsh: warning: N entries did not activate。 apply() 虽然先打印了 [dsh-autolearn] 原生工具已注册: 11 个，但 entry 整体激活失败， 注册随 fiber 一并回滚——11 个原生工具和设置卡全部不可用。

根因：Cordis 对未在 inject 中声明的服务做属性取值会抛错。原实现写的是 ctx?.webServer ?? ctx?.get?.('webServer')，第一个操作数就抛错，?? 右边没有机会执行； 而顶层声明只有 export const inject = ['tools']。

修复：把「挂设置卡路由」放进子注入上下文 ctx.inject(['webServer'], …)， 主插件仍然只硬依赖 tools。不能简单把 webServer 写进顶层 inject——headless/CLI profile 没有 web server，entry 会永久 pending，工具同样失效。修好后的 web profile 会打印 [dsh-autolearn] settings API ready: <settingsPath>。

细节（含 headless / web 两场景验证表）见 docs/修复记录-2026-10-20-webServer注入.md。

已知限制（不假装完成）

1. PDF/DOCX 解析未迁移：会明确报错并建议转换为 Markdown/TXT；HTML 用正则清洗（非 DOM）。
2. 模型辅助（规划/抽取提议）未迁移：use_model=true 会返回明确警告，只走规则链路。
3. 代码执行只支持 JavaScript，仅 lab 模式；默认 strict 沙盒（权限 + 命名空间 + Permission Model），但不是 seccomp/LSM 内核沙箱；security.exec_sandbox=process 是显式降级。Python 代码执行已移除。
4. 调度 tick / 实验运行器 / 知识图谱查询 / 检索评测集未迁移（表结构保留）。
5. 哈希向量是词汇级召回，不是语义模型；未做检索质量评测，不宣称提升。
6. 真实 DSH profile 启动验证被缺失模型凭据阻塞；插件注册由契约级测试 + MCP 子进程验证覆盖。
7. 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