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）在插件卸载时释放。

Related MCP server: DSH Crew

环境要求

安装与构建

# 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 插件设置页）修改的模式/每日预算/任务上限会在下一轮开始时生效（引擎重读 settings.json）；dataDir 变更需要重启。

11 个原生工具

审批：

• 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 目录时需整体复制。

安全默认值（与旧版差异处已加严）

测试

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、代码执行沙盒逃逸/超时/配额。

故障恢复

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