@knowflow/dsh-knowflow

August 16, 2026 · View on GitHub

一个原生 DeepSeek Harness（DSH）组合包（bundle）：它只把 knowflow_retrieve(query, top_k?) 注册为 DSH Tool，并随包提供 knowflow-knowledge Skill。DSH Agent 负责推理和写作；Knowflow 服务端负责检索、账号状态、群组、文档 ACL、设备令牌撤销以及“是否允许送入外部 AI”的策略。

它不是 MCP server，也不包含文档起草、文件下载、用户/群组参数或管理员能力。

当前交付边界

这是一个可独立维护的开源插件包；本次没有修改、调用或迁移现有 Agent/ 主项目。它不会自动读取当前项目里的本地资料库。只有将来某个 Knowflow 服务端实现下文的严格只读接口后，插件才会真正返回资料；在此之前，它仍可被安装、发现和做本地模拟测试，但不会绕过权限去访问任何现有数据。

安全边界

插件配置只能有：

serverUrl
spaceMode：personal-local、personal-cloud 或 work
credentialRef
timeoutMs

Tool 的 HTTP body 永远只有 query 和可选 top_k；不会上传 user ID、部门、项目组、角色、文件路径或 ACL。每次调用都通过 DSH 的 ctx.credentials.resolve() 重新解析设备凭据；插件不会缓存、打印或写入 token，也不会保存网页登录密码。

服务端必须把 token 绑定到一个空间/设备能力，因此请求体无需也不得指定空间。服务端每次请求都必须检查：账号仍启用、设备 token 未撤销、当前群组、文档 ACL 和 external_ai_policy=allow。deny 资料即使该用户在 Knowflow Web 中可读，也不能被这个接口返回。

后端契约（本包已用 mock 测试）

POST /api/integrations/dsh/v1/retrieve
Authorization: Bearer <revocable-device-token>
Content-Type: application/json

{"query":"...","top_k":5}

成功响应必须严格为：

{
  "results": [
    {
      "citation_id": "cit-123",
      "title": "资料标题",
      "locator": "第 2.1 节",
      "excerpt": "允许进入模型上下文的最小片段"
    }
  ]
}

本包拒绝多余字段。因此服务端的原始文件路径、下载 URL、上传人、完整 ACL、群组、内部异常及原始文档内容都不会意外进入模型上下文。

安装与三个 Profile

此包锁定 DSH 0.1.0-rc.6（以及它实际使用的 Cordis 4.0.1）和 Node ^22.19.0 || >=24.0.0。不要用浮动的 latest 安装或升级 DSH；每次升级都应重新跑本包的完整发布门禁。

cd dsh-knowflow
pnpm install
pnpm run check
pnpm pack --pack-destination .artifacts

从构建好的 tarball 安装，而不是让员工直接从 Git 源码执行：

dsh plugin --profile personal-local add ./.artifacts/knowflow-dsh-knowflow-0.1.0.tgz
dsh plugin --profile personal-cloud add ./.artifacts/knowflow-dsh-knowflow-0.1.0.tgz
dsh plugin --profile work add ./.artifacts/knowflow-dsh-knowflow-0.1.0.tgz

然后把 profiles/ 内同名 patch 复制到 $DSH_HOME/profiles/<profile>/cordis.patch.yml，按实际服务域名替换 knowflow.example.invalid。每个 Profile 使用不同的 credentialRef。

连接过程由 Knowflow Web 端的浏览器配对页完成：用户先登录 Knowflow，批准一台设备，再把返回的可撤销只读 token 交给 DSH 的 credential provider 保存。不要把密码、浏览器 JWT 或管理员 token 写入 patch、终端历史、环境文件或 Git。这个 bundle 只消费已配置的 credential reference；配对页面和 token 发放端点属于 Knowflow 后端。

安装后先检查组成的层：

dsh --profile personal-local --dump-config
dsh --profile personal-cloud --dump-config
dsh --profile work --dump-config

输出必须出现 @knowflow/dsh-knowflow/knowflow 层。要在浏览器界面使用，先把 bundle 装入 web profile（或把团队 profile 作为 Web profile 的一层），然后运行：

dsh web

DSH 的 profile 和 bundle 安装格式遵循官方的打包与安装插件、 Tools、 Skills 与 Credentials 公开 API。

开发与发布门禁

pnpm run validate      # manifest、patch 与源码边界
pnpm run typecheck     # 用锁定 DSH seam 的公开类型编译
pnpm test              # HTTP 契约、拒绝敏感字段、配置与包装检查
pnpm run build
pnpm run pack:check    # tarball 中必须有 lib、patch、Skill asset
pnpm run dsh:smoke     # 临时 DSH_HOME 安装 tarball + --dump-config

pnpm run check 包含除 DSH 进程 smoke 外的所有门禁；CI 同时运行两者。发布时记录：

shasum -a 256 .artifacts/knowflow-dsh-knowflow-0.1.0.tgz

并保存 DSH 版本、tarball SHA-256、--dump-config 输出和 CI 测试报告。当前 DSH 仍处于 Developer Preview；这套证据证明“对锁定版本符合官方公开规范”，不能替代未来版本升级后重新验证。

.github/workflows/ci.yml 已按“本项目就是插件仓库根目录”编写；推送到 GitHub 后，这份工作流会直接生效，不会影响网页项目的 CI。package.json 中的 private: true 只用于防止误发布到 npm，不影响源码以 MIT 许可证公开。