Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
feat(dsh-weknora): DeepSeek Harness plugin exposing WeKnora retrieval tools (#2759)
lyingbug5b140206219e
diff --git a/.github/workflows/dsh-plugin.yml b/.github/workflows/dsh-plugin.ymlnew file mode 100644index 000000000..af4abef79--- /dev/null+++ b/.github/workflows/dsh-plugin.yml@@ -0,0 +1,238 @@+name: Build & Publish (dsh-weknora)++# Build, test, and publish the DeepSeek Harness plugin (packages/dsh-weknora/) to npm.+#+# Three jobs:+# test typecheck, unit tests, both halves of the contract, and a+# packaging check+# e2e install the package into a throwaway dsh profile and drive real+# tool calls through the harness agent loop against a mock backend+# publish on a `dsh-weknora-v*` tag only, publish to npm with provenance+#+# The e2e job pins the harness version so a plugin change is the only thing that+# can turn it red. The weekly drift job runs the same check against dsh@latest and+# is allowed to fail: it exists to notice a harness breaking change early, since+# dsh is in developer preview.++on:+ push:+ branches: [main]+ tags:+ - "dsh-weknora-v*"+ paths:+ - "packages/dsh-weknora/**"+ - ".github/workflows/dsh-plugin.yml"+ pull_request:+ paths:+ - "packages/dsh-weknora/**"+ - ".github/workflows/dsh-plugin.yml"+ schedule:+ # Monday 03:00 UTC: catch a harness release that breaks the plugin.+ - cron: "0 3 * * 1"+ workflow_dispatch:++concurrency:+ group: ${{ github.workflow }}-${{ github.ref }}+ cancel-in-progress: true++permissions:+ contents: read++env:+ # The harness release this plugin is verified against. Bump it together with+ # the compatibility note in packages/dsh-weknora/README.md.+ DSH_PINNED_SPEC: "@deepseek-ai/[email protected]"+ # The contract's Go half lives in this repository's module. app.yml runs it+ # only for a Go diff, so a change to the fixture or to the plugin alone would+ # otherwise skip the side that checks WeKnora still serves those calls.+ GO_VERSION: "1.26"+ # `dsh plugin add` shells out to pnpm to install into the profile, and the+ # runner image ships only npm and yarn. The profile it writes carries its+ # settings in pnpm-workspace.yaml, which pnpm 10 is the first to read.+ PNPM_VERSION: "10"++jobs:+ test:+ name: Typecheck, test, pack+ runs-on: ubuntu-latest+ timeout-minutes: 15+ defaults:+ run:+ working-directory: packages/dsh-weknora+ steps:+ - uses: actions/checkout@v6++ - uses: actions/setup-node@v4+ with:+ node-version: "24"++ - name: Install dependencies+ run: npm ci || npm install++ - name: Typecheck+ run: npm run typecheck++ - name: Build+ run: npm run build++ - name: Unit and contract tests+ run: node --test "test/*.test.mjs"++ - uses: actions/setup-go@v6+ with:+ go-version: ${{ env.GO_VERSION }}+ cache: true++ - name: Contract tests against WeKnora's Go types+ working-directory: ${{ github.workspace }}+ run: go test ./packages/dsh-weknora/contract/...++ - name: Pack and verify the published file list+ run: |+ set -e+ npm pack --dry-run --json > pack.json+ node -e "+ const files = require('./pack.json')[0].files.map(f => f.path);+ const required = ['dist/index.js', 'dist/index.d.ts', 'cordis.patch.yml', 'README.md', 'package.json'];+ const missing = required.filter(name => !files.includes(name));+ if (missing.length > 0) {+ console.error('missing from the tarball: ' + missing.join(', '));+ process.exit(1);+ }+ const leaked = files.filter(name => name.startsWith('test/') || name.startsWith('src/'));+ if (leaked.length > 0) {+ console.error('unexpected files in the tarball: ' + leaked.join(', '));+ process.exit(1);+ }+ console.log('tarball contents verified: ' + files.length + ' files');+ "+ rm pack.json++ e2e:+ name: End-to-end inside dsh (pinned)+ runs-on: ubuntu-latest+ timeout-minutes: 25+ defaults:+ run:+ working-directory: packages/dsh-weknora+ steps:+ - uses: actions/checkout@v6++ - uses: actions/setup-node@v4+ with:+ node-version: "24"++ - uses: pnpm/action-setup@v4+ with:+ version: ${{ env.PNPM_VERSION }}++ - name: Install dependencies+ run: npm ci || npm install++ - name: Build+ run: npm run build++ - name: Run the plugin inside a real dsh profile+ env:+ DSH_PACKAGE_SPEC: ${{ env.DSH_PINNED_SPEC }}+ DSH_E2E_LOG: ${{ runner.temp }}/dsh-weknora-e2e.log+ run: node test/e2e/run-in-dsh.mjs++ - name: Upload the transcript+ if: always()+ uses: actions/upload-artifact@v4+ with:+ name: dsh-weknora-e2e-transcript+ path: ${{ runner.temp }}/dsh-weknora-e2e.log+ if-no-files-found: ignore++ drift:+ name: End-to-end inside dsh (latest, advisory)+ if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'+ runs-on: ubuntu-latest+ timeout-minutes: 25+ continue-on-error: true+ defaults:+ run:+ working-directory: packages/dsh-weknora+ steps:+ - uses: actions/checkout@v6++ - uses: actions/setup-node@v4+ with:+ node-version: "24"++ - uses: pnpm/action-setup@v4+ with:+ version: ${{ env.PNPM_VERSION }}++ - name: Install dependencies+ run: npm ci || npm install++ - name: Build+ run: npm run build++ - name: Run against the latest harness release+ env:+ DSH_PACKAGE_SPEC: "@deepseek-ai/dsh@latest"+ run: node test/e2e/run-in-dsh.mjs++ publish:+ name: Publish to npm+ needs: [test, e2e]+ if: startsWith(github.ref, 'refs/tags/dsh-weknora-v')+ runs-on: ubuntu-latest+ timeout-minutes: 15+ permissions:+ contents: read+ id-token: write+ environment:+ name: npm-publish+ url: https://www.npmjs.com/package/@wxg-prc-cpg/dsh-weknora+ defaults:+ run:+ working-directory: packages/dsh-weknora+ steps:+ - uses: actions/checkout@v6++ - uses: actions/setup-node@v4+ with:+ node-version: "24"+ registry-url: "https://registry.npmjs.org"++ - name: Install dependencies+ run: npm ci || npm install++ - name: Build+ run: npm run build++ - name: Check the tag names the packaged version+ run: |+ set -e+ version="$(node -p "require('./package.json').version")"+ expected="dsh-weknora-v${version}"+ if [ "$GITHUB_REF_NAME" != "$expected" ]; then+ echo "::error::tag $GITHUB_REF_NAME does not name the packaged version $version (expected $expected)."+ echo "::error::Bump packages/dsh-weknora/package.json, or retag — publishing here would ship a version the tag does not name."+ exit 1+ fi++ - name: Check whether this version is already published+ id: check_npm+ run: |+ set -e+ name="$(node -p "require('./package.json').name")"+ version="$(node -p "require('./package.json').version")"+ echo "packaged: $name@$version"+ if npm view "$name@$version" version >/dev/null 2>&1; then+ echo "should_publish=false" >> "$GITHUB_OUTPUT"+ echo "::warning::$name $version is already on npm; skipping publish. Bump package.json to release."+ else+ echo "should_publish=true" >> "$GITHUB_OUTPUT"+ fi++ - name: Publish+ if: steps.check_npm.outputs.should_publish == 'true'+ run: npm publish --provenance --access public+ env:+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}diff --git a/README.md b/README.mdindex 94b6078e0..5758bb7bd 100644--- a/README.md+++ b/README.md@@ -181,6 +181,15 @@ The [WeKnora Mini Program](./miniprogram/README.md) provides a lightweight mobil- **Hybrid Search** — Search within or across knowledge bases with vector + keyword retrieval- **Knowledge Management** — List, browse, edit, and delete knowledge entries programmatically+## 🐋 DeepSeek Harness Plugin++[**`@wxg-prc-cpg/dsh-weknora`**](./packages/dsh-weknora/README.md) is the official [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) plugin. The harness ships no retrieval, embedding or knowledge-base capability of its own, so the plugin gives a coding agent your documents: `dsh plugin --profile web add @wxg-prc-cpg/dsh-weknora`, point it at a deployment, and four read-only tools appear in the agent's tool set.++- **`weknora_search`** — hybrid retrieval returning source passages verbatim, each with a reusable `knowledge_id`+- **`weknora_read_document`** — one document's passages reassembled in order, with paging+- **`weknora_ask`** — WeKnora's own composed answer with citations, over the RAG or the ReAct pipeline+- **`weknora_list_knowledge_bases`** — knowledge base names and ids, so the agent can scope its own search+## ⌨️ Command-Line Interface`weknora` is the official CLI for driving the API from a terminal or an AIdiff --git a/README_CN.md b/README_CN.mdindex 83b77b77f..17fd2371a 100644--- a/README_CN.md+++ b/README_CN.md@@ -181,6 +181,15 @@- **混合检索** — 在单个或多个知识库中进行向量 + 关键词混合搜索- **知识管理** — 以编程方式浏览、编辑和删除知识条目+## 🐋 DeepSeek Harness 插件++[**`@wxg-prc-cpg/dsh-weknora`**](./packages/dsh-weknora/README_CN.md) 是官方的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`)插件。harness 自身不带任何检索、向量或知识库能力,这个插件把你的文档接进编码 Agent:`dsh plugin --profile web add @wxg-prc-cpg/dsh-weknora`,指向一个部署,Agent 的工具集里就会出现四个只读工具。++- **`weknora_search`** — 混合检索,返回原文片段,每条都带可复用的 `knowledge_id`+- **`weknora_read_document`** — 把单个文档的分块按序拼回正文,支持翻页+- **`weknora_ask`** — WeKnora 自己带引用的成稿答案,走 RAG 或 ReAct 流水线+- **`weknora_list_knowledge_bases`** — 知识库名称与 id,便于 Agent 自己缩小检索范围+## 🚀 快速开始### 🛠 环境要求diff --git a/README_JA.md b/README_JA.mdindex b6bfb6198..a97f11727 100644--- a/README_JA.md+++ b/README_JA.md@@ -173,6 +173,15 @@ Feishu、Notion、Yuqueなどの外部プラットフォームからのナレッ- **ハイブリッド検索** — 単一または複数のナレッジベースをベクトル + キーワードで横断検索- **ナレッジ管理** — プログラムによるナレッジエントリの閲覧、編集、削除+## 🐋 DeepSeek Harness プラグイン++[**`@wxg-prc-cpg/dsh-weknora`**](./packages/dsh-weknora/README.md) は公式の [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`)プラグインです。harness 自体は検索・埋め込み・ナレッジベースの機能を持たないため、このプラグインがコーディングエージェントに自社ドキュメントを与えます。`dsh plugin --profile web add @wxg-prc-cpg/dsh-weknora` でインストールしてデプロイ先を指定すると、4 つの読み取り専用ツールがエージェントのツールセットに現れます。++- **`weknora_search`** — ハイブリッド検索。原文のパッセージをそのまま返し、各件に再利用可能な `knowledge_id` が付く+- **`weknora_read_document`** — 1 つのドキュメントのチャンクを順番に再構成、ページング対応+- **`weknora_ask`** — WeKnora 自身が引用付きで作成した回答(RAG または ReAct パイプライン)+- **`weknora_list_knowledge_bases`** — ナレッジベースの名前と id。エージェントが自分で検索範囲を絞れる+## 🚀 クイックスタートdiff --git a/README_KO.md b/README_KO.mdindex f209ec391..dce7fac3c 100644--- a/README_KO.md+++ b/README_KO.md@@ -183,6 +183,15 @@ Feishu, Notion, Yuque 등 외부 플랫폼에서 지식 자동 동기화를 지- **하이브리드 검색** — 단일 또는 다중 지식베이스에서 벡터 + 키워드 통합 검색- **지식 관리** — 프로그래밍 방식으로 지식 항목 조회, 편집, 삭제+## 🐋 DeepSeek Harness 플러그인++[**`@wxg-prc-cpg/dsh-weknora`**](./packages/dsh-weknora/README.md)는 공식 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`) 플러그인입니다. harness 자체에는 검색·임베딩·지식베이스 기능이 없으므로, 이 플러그인이 코딩 에이전트에 사내 문서를 제공합니다. `dsh plugin --profile web add @wxg-prc-cpg/dsh-weknora`로 설치하고 배포 주소를 지정하면 네 개의 읽기 전용 도구가 에이전트 도구 목록에 나타납니다.++- **`weknora_search`** — 하이브리드 검색. 원문 구절을 그대로 반환하며 각 항목에 재사용 가능한 `knowledge_id` 포함+- **`weknora_read_document`** — 한 문서의 청크를 순서대로 재조합, 페이징 지원+- **`weknora_ask`** — WeKnora가 직접 작성한 인용 포함 답변(RAG 또는 ReAct 파이프라인)+- **`weknora_list_knowledge_bases`** — 지식베이스 이름과 id로 에이전트가 검색 범위를 스스로 좁힘+## 🚀 시작하기diff --git a/packages/dsh-weknora/.gitignore b/packages/dsh-weknora/.gitignorenew file mode 100644index 000000000..1eae0cf67--- /dev/null+++ b/packages/dsh-weknora/.gitignore@@ -0,0 +1,2 @@+dist/+node_modules/diff --git a/packages/dsh-weknora/README.md b/packages/dsh-weknora/README.mdnew file mode 100644index 000000000..772922537--- /dev/null+++ b/packages/dsh-weknora/README.md@@ -0,0 +1,167 @@+# @wxg-prc-cpg/dsh-weknora++English | [简体中文](./README_CN.md)++A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) plugin that gives the harness agent+first-class access to a [WeKnora](https://github.com/Tencent/WeKnora) knowledge base: hybrid retrieval, full document+reading, and WeKnora's own composed answers with citations.++dsh ships no retrieval, embedding or knowledge-base capability of its own — its search tools (`grep`, `glob`) read the+workspace, and `web_search` reads the internet. This plugin fills that gap with your organization's documents.++## Install++```sh+# from npm (recommended: installs prebuilt code, no build permission needed)+dsh plugin --profile web add @wxg-prc-cpg/dsh-weknora++# or from a checkout of this repository+dsh plugin --profile web add ./packages/dsh-weknora+```++Then point it at your deployment. The shipped configuration layer reads environment variables, so the quickest start is:++```sh+export WEKNORA_BASE_URL=https://weknora.example.com # or http://localhost:8080+export WEKNORA_API_KEY=sk-... # a WeKnora API key with `retrieve` (+ `chat` for ask)+export WEKNORA_KNOWLEDGE_BASE_IDS=kb-123,kb-456 # optional default scope+dsh web+```++For anything beyond that, override the row from your profile's `cordis.patch.yml`+(`$DSH_HOME/profiles/<name>/cordis.patch.yml`):++```yaml+- id: weknora+ config:+ baseUrl: https://weknora.example.com+ apiKey: !!js process.env.WEKNORA_API_KEY+ knowledgeBaseIds:+ - kb-product-docs+ agentId: '' # a WeKnora custom agent id makes `weknora_ask` use the ReAct pipeline+ maxResults: 8+ maxChunkChars: 1200+ requestTimeoutMs: 30000+ chatTimeoutMs: 300000+ resourceUrls: handle # `public` asks WeKnora for directly loadable file URLs in citations+ toolPrefix: weknora # rename the tools, e.g. to mount two deployments side by side+ tools:+ listKnowledgeBases: true+ search: true+ readDocument: true+ ask: true+```++A patch replaces the row's whole `config`, so restate every field you keep. Invalid configuration fails the plugin load+with a message naming each violation, rather than failing inside the first tool call.++Mounting two deployments is two rows with two prefixes:++```yaml+- insert:+ - id: weknora-internal+ name: "@wxg-prc-cpg/dsh-weknora"+ config: { baseUrl: https://kb.internal.example.com, toolPrefix: internal_kb }+ - id: weknora-public+ name: "@wxg-prc-cpg/dsh-weknora"+ config: { baseUrl: https://kb.public.example.com, toolPrefix: public_kb }+```++## Tools++| Tool | WeKnora endpoint | What the model gets |+|---|---|---|+| `weknora_list_knowledge_bases` | `GET /knowledge-bases` | Knowledge base names and ids, to report what exists or to narrow a later search |+| `weknora_search` | `POST /knowledge-search` + `GET /knowledge/search` | Ranked passages verbatim, each with a `knowledge_id`, score and chunk index, plus any document the query names |+| `weknora_read_document` | `GET /chunks/:knowledge_id` + `GET /knowledge/:id` | One document's passages reassembled in order, led by its title and summary, with paging |+| `weknora_ask` | `POST /sessions` + `POST /knowledge-chat/:id` or `POST /agent-chat/:id` | WeKnora's own answer, its citations, the server-side tools it used, and a resumable `session_id` |++`weknora_search` is the workhorse: it returns the source text for the agent to reason over, which keeps the agent's own+reasoning auditable. It answers two questions the model cannot always tell apart — *where is this discussed* and *where+is the document called X* — by matching passage content and document names in the same call. A query that reads like a+title additionally reports the documents it names, so a document whose wording differs from its own title is still+reachable.++Scope works without configuration. An unscoped call is refused by the retrieval endpoint and answered from nothing by+the RAG one, so when `knowledgeBaseIds` is empty the plugin resolves every knowledge base the credential can see and+uses all of them, resolving that list once per process and sharing it between `weknora_search` and `weknora_ask`.+Making the model choose first would be worse: knowledge bases are frequently named too poorly to choose between.++`weknora_ask` delegates the whole question to WeKnora. Reserve it for broad or synthesis questions spanning many+documents, where retrieving passages yourself would take several rounds — it runs another model server-side, so it is+slow, and it returns a conclusion rather than the evidence behind it. With `agentId` set it leaves the scope alone: a+custom agent resolves its own from its KB selection mode, and ids sent from here would override that.++`weknora_read_document` exists because retrieval returns fragments: once a passage looks right, the agent usually needs+its neighbours. Every search hit carries the `knowledge_id` that call needs, and page 1 leads with the document's title+and WeKnora's generated summary so a long document can be judged without paging through it.++In [Code Mode](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/tools/README.md) the same tools+are available as `await tools.weknora_search({ query })`, which is a good fit for multi-hop retrieval: one program can+fan out across ten sub-questions without ten model round trips.++## Permissions and data flow++The plugin only reads. It never writes to WeKnora: no ingestion, no chunk edits, no deletion. A WeKnora API key scoped+to `retrieve` is enough for three of the four tools; `weknora_ask` additionally needs `chat`, because it creates a+session and streams an answer.++The key is sent as `X-API-Key`. Set `tenantId` as well if you use a platform-scoped key, which needs `X-Tenant-ID` to+select a workspace. Errors are reported with the HTTP status and WeKnora's own reason, never with the key.++Passage content is clipped to `maxChunkChars` before it reaches the model, so one oversized document cannot eat the+context window. The clip is reported to the model (`truncated: true`) instead of silently hiding text.++## Configuration reference++| Field | Default | Notes |+|---|---|---|+| `baseUrl` | `http://localhost:8080/api/v1` | `/api/v1` is appended when missing |+| `apiKey` | unset | `X-API-Key`; unset means an unauthenticated deployment |+| `tenantId` | unset | `X-Tenant-ID`, required for platform-scoped keys |+| `knowledgeBaseIds` | `[]` | Default scope when a call names none; empty means every knowledge base the credential can see |+| `agentId` | unset | Sends `weknora_ask` to the ReAct pipeline |+| `maxResults` | `8` | Also the ceiling for `max_results` and for cited references |+| `maxChunkChars` | `1200` | Per-passage character budget |+| `requestTimeoutMs` | `30000` | Retrieval and document reads |+| `chatTimeoutMs` | `300000` | `weknora_ask`, which waits on WeKnora's own model calls |+| `resourceUrls` | `handle` | `public` returns directly loadable file URLs |+| `toolPrefix` | `weknora` | Tool-name prefix, `^[a-z][a-z0-9_]*$` |+| `tools.*` | all `true` | Register fewer tools to spend fewer prompt tokens |++## Development++```sh+npm install+npm test # builds, then runs the unit and contract tests+npm run typecheck+```++The end-to-end check installs the package into a throwaway dsh profile, boots the headless profile against a mock+WeKnora backend and a deterministic OpenAI-compatible model, and asserts that the harness really called the tools and+answered from what they returned:++```sh+npm run build+node test/e2e/run-in-dsh.mjs # installs dsh from npm on first run+DSH_BIN=/path/to/dsh node test/e2e/run-in-dsh.mjs # or reuse an existing install+```++dsh needs a Node build with zstd support (Node ≥ 22.15 or ≥ 24) for its session persistence, and pnpm ≥ 10 on `PATH`,+because `dsh plugin add` installs into the profile through pnpm and the profile it writes keeps its settings in+`pnpm-workspace.yaml`. The plugin itself runs on Node ≥ 20.11 and needs neither.++`test/fixtures/api-contract.json` records every WeKnora call this plugin makes. `test/contract.test.mjs` asserts the+plugin still emits exactly those calls, and `contract/contract_test.go` asserts WeKnora's real Go request and response+types still accept and serve them — so a rename on either side fails CI instead of a user's agent.++## Compatibility++Verified against dsh `0.1.0-rc.8` and WeKnora `0.7.2`. dsh is in developer preview and states that breaking changes+will happen; this package deliberately has **no runtime dependencies** and hands `ctx.tools.register()` a plain object,+so it does not pin any harness package version. If a harness release changes the tool-definition contract, open an issue+against this repository.++## License++MIT, same as WeKnora and dsh.diff --git a/packages/dsh-weknora/README_CN.md b/packages/dsh-weknora/README_CN.mdnew file mode 100644index 000000000..fdde8d106--- /dev/null+++ b/packages/dsh-weknora/README_CN.md@@ -0,0 +1,155 @@+# @wxg-prc-cpg/dsh-weknora++[English](./README.md) | 简体中文++一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`)插件,让 harness 里的 Agent 直接用上+[WeKnora](https://github.com/Tencent/WeKnora) 知识库:混合检索、按文档通读、以及 WeKnora 自己带引用的成稿答案。++dsh 本身没有任何检索、向量或知识库能力——它的 `grep`、`glob` 只看工作区文件,`web_search` 只看互联网。这个插件把缺的这一+块换成你自己的文档。++## 安装++```sh+# 从 npm 安装(推荐:装到的是构建产物,用户无需授权执行构建脚本)+dsh plugin --profile web add @wxg-prc-cpg/dsh-weknora++# 或者从本仓库的检出目录安装+dsh plugin --profile web add ./packages/dsh-weknora+```++然后把它指向你的部署。插件自带的配置层会读环境变量,所以最快的起步方式是:++```sh+export WEKNORA_BASE_URL=https://weknora.example.com # 或 http://localhost:8080+export WEKNORA_API_KEY=sk-... # 需要 `retrieve` 能力(用 ask 还需要 `chat`)+export WEKNORA_KNOWLEDGE_BASE_IDS=kb-123,kb-456 # 可选的默认知识库范围+dsh web+```++超出这个范围的配置,在 profile 自己的 `cordis.patch.yml`(`$DSH_HOME/profiles/<name>/cordis.patch.yml`)里覆盖这一行:++```yaml+- id: weknora+ config:+ baseUrl: https://weknora.example.com+ apiKey: !!js process.env.WEKNORA_API_KEY+ knowledgeBaseIds:+ - kb-product-docs+ agentId: '' # 填 WeKnora 自定义 Agent id,`weknora_ask` 就走 ReAct 流水线+ maxResults: 8+ maxChunkChars: 1200+ requestTimeoutMs: 30000+ chatTimeoutMs: 300000+ resourceUrls: handle # 改成 `public`,引用里的图片和文件会给可直接加载的直链+ toolPrefix: weknora # 重命名工具,例如同时挂两个部署时+ tools:+ listKnowledgeBases: true+ search: true+ readDocument: true+ ask: true+```++patch 是整块替换该行的 `config`,所以要保留的字段需要一并写出。配置不合法会在插件加载阶段失败,并逐条列出问题,而不是等到+模型第一次调用工具时才报错。++同时挂两个部署,就是两行加两个前缀:++```yaml+- insert:+ - id: weknora-internal+ name: "@wxg-prc-cpg/dsh-weknora"+ config: { baseUrl: https://kb.internal.example.com, toolPrefix: internal_kb }+ - id: weknora-public+ name: "@wxg-prc-cpg/dsh-weknora"+ config: { baseUrl: https://kb.public.example.com, toolPrefix: public_kb }+```++## 工具++| 工具 | WeKnora 接口 | 模型拿到什么 |+|---|---|---|+| `weknora_list_knowledge_bases` | `GET /knowledge-bases` | 知识库名称与 id,用于说明有哪些库,或为后续检索缩小范围 |+| `weknora_search` | `POST /knowledge-search` + `GET /knowledge/search` | 原文片段与排序,每条带 `knowledge_id`、得分、分块序号,外加查询点名的文档 |+| `weknora_read_document` | `GET /chunks/:knowledge_id` + `GET /knowledge/:id` | 单个文档按序拼回的正文,开头给出标题与摘要,支持翻页 |+| `weknora_ask` | `POST /sessions` + `POST /knowledge-chat/:id` 或 `POST /agent-chat/:id` | WeKnora 自己的答案、引用、服务端用过的工具,以及可续聊的 `session_id` |++`weknora_search` 是主力:它把原文交给 Agent 自己推理,Agent 的结论因此是可审计的。它在同一次调用里同时匹配片段内容和+文档名,因为模型常常分不清自己要找的是「哪里讲了这件事」还是「那份叫 X 的文档在哪」。当查询读起来像个标题时,结果里会额外+列出被点名的文档——这样即便某份文档的正文用词与标题完全不同,也依然够得着。++范围不需要配置。没有指定知识库的调用,检索接口会直接拒绝,RAG 接口则会在什么都没检索到的情况下作答,因此当+`knowledgeBaseIds` 为空时,插件会自己解析出该凭据可见的全部知识库并一并使用;这份清单每个进程只解析一次,且由+`weknora_search` 与 `weknora_ask` 共用。让模型先去挑反而更糟:知识库的命名往往糟糕到无从选择。++`weknora_ask` 把整个问题委派给 WeKnora。它适合跨多篇文档、需要综合的宽泛问题,也就是自己检索要来回好几轮的场景;它在服务端+再跑一个模型,所以慢,而且返回的是结论而非支撑结论的证据。配了 `agentId` 时它不会自己填范围:自定义 Agent 会按自己的知识库+选择模式在服务端解析范围,从这里传 id 反而会把它覆盖掉。++`weknora_read_document` 的存在是因为检索返回的是碎片:一旦某个片段看起来对,Agent 通常还需要它的上下文。每条检索结果都带+着这次调用需要的 `knowledge_id`;第一页会先给出文档标题和 WeKnora 生成的摘要,长文档不必翻完才知道自己拿到的是什么。++在 [Code Mode](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/tools/README.md) 下,同样的工具+可以写成 `await tools.weknora_search({ query })`,特别适合多跳检索:一段程序里扇出十个子问题,而不是十次模型往返。++## 权限与数据流++插件只读。它不会写 WeKnora:不入库、不改分块、不删除。四个工具里有三个只需要 `retrieve` 能力的 API Key;`weknora_ask`+额外需要 `chat`,因为它要创建会话并流式取回答案。++Key 通过 `X-API-Key` 发送。如果用的是平台级 API Key,还需要配 `tenantId`,它会作为 `X-Tenant-ID` 选择工作空间。报错信息+只包含 HTTP 状态码和 WeKnora 自己给出的原因,不会带上 Key。++片段内容在进入模型前会按 `maxChunkChars` 截断,避免一份超大文档吃掉整个上下文窗口;截断这件事会明确告知模型+(`truncated: true`),而不是悄悄丢文本。++## 配置项++| 字段 | 默认值 | 说明 |+|---|---|---|+| `baseUrl` | `http://localhost:8080/api/v1` | 缺少 `/api/v1` 时自动补全 |+| `apiKey` | 未设置 | `X-API-Key`;不设表示部署无鉴权 |+| `tenantId` | 未设置 | `X-Tenant-ID`,平台级 Key 必填 |+| `knowledgeBaseIds` | `[]` | 调用未指定范围时的默认值;留空表示检索该凭据可见的全部知识库 |+| `agentId` | 未设置 | 让 `weknora_ask` 走 ReAct 流水线 |+| `maxResults` | `8` | 同时是 `max_results` 与引用条数的上限 |+| `maxChunkChars` | `1200` | 单个片段的字符预算 |+| `requestTimeoutMs` | `30000` | 检索与读文档 |+| `chatTimeoutMs` | `300000` | `weknora_ask`,要等 WeKnora 自己的模型调用 |+| `resourceUrls` | `handle` | `public` 返回可直接加载的文件直链 |+| `toolPrefix` | `weknora` | 工具名前缀,需匹配 `^[a-z][a-z0-9_]*$` |+| `tools.*` | 全部 `true` | 少注册几个工具就少占几分 prompt |++## 开发++```sh+npm install+npm test # 先构建,再跑单元测试与契约测试+npm run typecheck+```++端到端检查会把这个包装进一个临时 dsh profile,用 mock 的 WeKnora 后端和一个确定性的 OpenAI 兼容模型启动 headless+profile,并断言 harness 真的调用了工具、并且答案来自工具返回的内容:++```sh+npm run build+node test/e2e/run-in-dsh.mjs # 首次运行会从 npm 装一个 dsh+DSH_BIN=/path/to/dsh node test/e2e/run-in-dsh.mjs # 或者复用已有安装+```++dsh 的会话持久化需要带 zstd 的 Node(≥ 22.15 或 ≥ 24),并且 `PATH` 上要有 pnpm ≥ 10——`dsh plugin add` 通过 pnpm 装进+profile,而它写出的 profile 把设置放在 `pnpm-workspace.yaml` 里。插件自身只要求 Node ≥ 20.11,两者都不需要。++`test/fixtures/api-contract.json` 记录了本插件发出的每一个 WeKnora 调用。`test/contract.test.mjs` 断言插件仍然只发这些+调用,`contract/contract_test.go` 断言 WeKnora 真实的 Go 请求/响应类型仍然接受并提供这些字段——任何一侧改名都会在 CI 挂掉,+而不是在用户的 Agent 里挂掉。++## 兼容性++已针对 dsh `0.1.0-rc.8` 与 WeKnora `0.7.2` 验证。dsh 处于 developer preview 并明确会有破坏性变更;本包因此**没有任何运行+时依赖**,交给 `ctx.tools.register()` 的只是一个普通对象,不锁定任何 harness 包版本。如果 harness 的工具定义契约发生变化,+请在本仓库提 issue。++## 许可++MIT,与 WeKnora 和 dsh 一致。diff --git a/packages/dsh-weknora/contract/contract_test.go b/packages/dsh-weknora/contract/contract_test.gonew file mode 100644index 000000000..331cd44b4--- /dev/null+++ b/packages/dsh-weknora/contract/contract_test.go@@ -0,0 +1,245 @@+// Package contract asserts that the WeKnora API surface the dsh-weknora plugin+// speaks still exists on this server: the request bodies it sends must decode+// into the real handler request structs with no unknown fields, and the response+// fields it reads must still be produced by the real response types.+//+// The fixture is shared with the plugin's own JavaScript tests+// (packages/dsh-weknora/test/contract.test.mjs), which assert that the plugin+// still emits exactly these calls. Together the two sides catch a rename on+// either side at CI time instead of inside a user's agent.+package contract++import (+ "bytes"+ "encoding/json"+ "os"+ "path/filepath"+ "testing"++ "github.com/Tencent/WeKnora/internal/handler/session"+ "github.com/Tencent/WeKnora/internal/types"+)++type contractCall struct {+ Tool string `json:"tool"`+ Method string `json:"method"`+ Path string `json:"path"`+ Query map[string]string `json:"query"`+ Body json.RawMessage `json:"body"`+ GoRequestType *string `json:"goRequestType"`+}++type contractFixture struct {+ Calls []contractCall `json:"calls"`+ ResponseFieldsRead map[string][]string `json:"responseFieldsRead"`+ StreamResponseTypes []string `json:"streamResponseTypes"`+}++func loadFixture(t *testing.T) contractFixture {+ t.Helper()+ raw, err := os.ReadFile(filepath.Join("..", "test", "fixtures", "api-contract.json"))+ if err != nil {+ t.Fatalf("read fixture: %v", err)+ }+ var fixture contractFixture+ if err := json.Unmarshal(raw, &fixture); err != nil {+ t.Fatalf("parse fixture: %v", err)+ }+ if len(fixture.Calls) == 0 {+ t.Fatal("fixture declares no calls")+ }+ return fixture+}++// newRequestTarget returns an empty instance of the handler request struct the+// named call decodes into.+func newRequestTarget(t *testing.T, name string) any {+ t.Helper()+ switch name {+ case "session.SearchKnowledgeRequest":+ return &session.SearchKnowledgeRequest{}+ case "session.CreateSessionRequest":+ return &session.CreateSessionRequest{}+ case "session.CreateKnowledgeQARequest":+ return &session.CreateKnowledgeQARequest{}+ case "types.Pagination":+ return &types.Pagination{}+ default:+ t.Fatalf("fixture names an unknown Go request type %q", name)+ return nil+ }+}++// TestPluginRequestBodiesDecodeIntoHandlerTypes: every body the plugin sends is+// accepted by the struct its handler binds, with no field the server would drop.+func TestPluginRequestBodiesDecodeIntoHandlerTypes(t *testing.T) {+ fixture := loadFixture(t)+ decoded := 0+ for _, call := range fixture.Calls {+ if call.GoRequestType == nil || len(call.Body) == 0 || string(call.Body) == "null" {+ continue+ }+ target := newRequestTarget(t, *call.GoRequestType)+ decoder := json.NewDecoder(bytes.NewReader(call.Body))+ decoder.DisallowUnknownFields()+ if err := decoder.Decode(target); err != nil {+ t.Errorf("%s %s (%s) body rejected by %s: %v",+ call.Method, call.Path, call.Tool, *call.GoRequestType, err)+ continue+ }+ decoded+++ }+ if decoded == 0 {+ t.Fatal("no request body was checked; the fixture lost its bodies")+ }+}++// TestRetrievalRequestCarriesRequiredFields: the search body binds the fields+// the handler validates, so the plugin cannot send a request the handler rejects+// with 400 at runtime.+func TestRetrievalRequestCarriesRequiredFields(t *testing.T) {+ fixture := loadFixture(t)+ for _, call := range fixture.Calls {+ if call.Path != "/api/v1/knowledge-search" {+ continue+ }+ var request session.SearchKnowledgeRequest+ if err := json.Unmarshal(call.Body, &request); err != nil {+ t.Fatalf("decode search body: %v", err)+ }+ if request.Query == "" {+ t.Error("the plugin must always send a non-empty query; the handler rejects an empty one")+ }+ if len(request.KnowledgeBaseIDs) == 0 && len(request.KnowledgeIDs) == 0 {+ t.Error("the plugin must scope retrieval; the handler rejects a request with no target")+ }+ return+ }+ t.Fatal("the fixture no longer covers /knowledge-search")+}++// TestChatRequestSelectsThePipeline: the agent route must carry both the agent id+// and the agent-enabled flag, since the RAG and ReAct pipelines are selected by+// the same struct.+func TestChatRequestSelectsThePipeline(t *testing.T) {+ fixture := loadFixture(t)+ var sawRAG, sawAgent bool+ for _, call := range fixture.Calls {+ if call.GoRequestType == nil || *call.GoRequestType != "session.CreateKnowledgeQARequest" {+ continue+ }+ var request session.CreateKnowledgeQARequest+ if err := json.Unmarshal(call.Body, &request); err != nil {+ t.Fatalf("decode chat body: %v", err)+ }+ if request.Query == "" {+ t.Errorf("%s must send a query", call.Path)+ }+ if request.Channel != "api" {+ t.Errorf("%s must declare channel \"api\", got %q", call.Path, request.Channel)+ }+ switch {+ case request.AgentID != "":+ sawAgent = true+ if !request.AgentEnabled {+ t.Errorf("%s names an agent but leaves agent_enabled false", call.Path)+ }+ default:+ sawRAG = true+ }+ }+ if !sawRAG || !sawAgent {+ t.Fatal("the fixture must cover both the RAG and the agent chat route")+ }+}++// TestResponseFieldsThePluginReadsStillExist: marshal the real response types and+// confirm every JSON key the plugin depends on is present, so a renamed or+// dropped json tag fails here.+func TestResponseFieldsThePluginReadsStillExist(t *testing.T) {+ fixture := loadFixture(t)+ samples := map[string]any{+ "types.SearchResult": types.SearchResult{+ ID: "chunk-1",+ Content: "默认的 vector_threshold 是 0.5",+ KnowledgeID: "doc-1",+ ChunkIndex: 3,+ KnowledgeTitle: "检索流程.md",+ KnowledgeFilename: "检索流程.md",+ Score: 0.83,+ },+ "types.Knowledge": types.Knowledge{+ ID: "doc-1",+ Title: "检索流程.md",+ FileName: "检索流程.md",+ Description: "讲解 WeKnora 混合检索的召回与阈值。",+ KnowledgeBaseID: "kb-product",+ KnowledgeBaseName: "Product docs",+ },+ "types.Chunk": types.Chunk{+ ID: "chunk-1",+ Content: "默认的 vector_threshold 是 0.5",+ ChunkIndex: 3,+ KnowledgeID: "doc-1",+ },+ "types.StreamResponse": types.StreamResponse{+ ID: "event-1",+ ResponseType: types.ResponseTypeAnswer,+ Content: "答案",+ SessionID: "session-1",+ KnowledgeReferences: types.References{{ID: "chunk-1"}},+ ToolCalls: []types.LLMToolCall{{ID: "call-1", Type: "function"}},+ },+ "types.LLMToolCall": types.LLMToolCall{ID: "call-1", Type: "function"},+ "types.FunctionCall": types.FunctionCall{+ Name: "knowledge_search",+ Arguments: "{}",+ },+ }++ for typeName, fields := range fixture.ResponseFieldsRead {+ sample, ok := samples[typeName]+ if !ok {+ t.Errorf("fixture names %s but this test has no sample for it", typeName)+ continue+ }+ raw, err := json.Marshal(sample)+ if err != nil {+ t.Errorf("marshal %s: %v", typeName, err)+ continue+ }+ var asMap map[string]json.RawMessage+ if err := json.Unmarshal(raw, &asMap); err != nil {+ t.Errorf("re-decode %s: %v", typeName, err)+ continue+ }+ for _, field := range fields {+ if _, ok := asMap[field]; !ok {+ t.Errorf("%s no longer serializes %q, which dsh-weknora reads", typeName, field)+ }+ }+ }+}++// TestStreamResponseTypesThePluginHandlesStillExist: the SSE event names the+// plugin switches on must still be the server's constants.+func TestStreamResponseTypesThePluginHandlesStillExist(t *testing.T) {+ fixture := loadFixture(t)+ known := map[string]types.ResponseType{+ "answer": types.ResponseTypeAnswer,+ "references": types.ResponseTypeReferences,+ "tool_call": types.ResponseTypeToolCall,+ "error": types.ResponseTypeError,+ "complete": types.ResponseTypeComplete,+ }+ for _, name := range fixture.StreamResponseTypes {+ constant, ok := known[name]+ if !ok {+ t.Errorf("fixture handles stream event %q, which this test does not map to a server constant", name)+ continue+ }+ if string(constant) != name {+ t.Errorf("stream event %q is now spelled %q on the server", name, string(constant))+ }+ }+}diff --git a/packages/dsh-weknora/cordis.patch.yml b/packages/dsh-weknora/cordis.patch.ymlnew file mode 100644index 000000000..3709769ef--- /dev/null+++ b/packages/dsh-weknora/cordis.patch.yml@@ -0,0 +1,13 @@+# The configuration layer this bundle contributes when a profile lists it.+# Override the row from the profile's own cordis.patch.yml to point the plugin+# at your deployment; every field is documented in README.md.+- insert:+ - id: weknora+ # Must be the published package name — the loader imports this specifier.+ # Quoted because YAML reserves a leading '@' in plain scalars.+ name: "@wxg-prc-cpg/dsh-weknora"+ config:+ baseUrl: !!js process.env.WEKNORA_BASE_URL ?? 'http://localhost:8080/api/v1'+ apiKey: !!js process.env.WEKNORA_API_KEY+ knowledgeBaseIds: !!js (process.env.WEKNORA_KNOWLEDGE_BASE_IDS ?? '').split(',').filter(Boolean)+ agentId: !!js process.env.WEKNORA_AGENT_IDdiff --git a/packages/dsh-weknora/package-lock.json b/packages/dsh-weknora/package-lock.jsonnew file mode 100644index 000000000..169529e51--- /dev/null+++ b/packages/dsh-weknora/package-lock.json@@ -0,0 +1,51 @@+{+ "name": "@wxg-prc-cpg/dsh-weknora",+ "version": "0.1.0",+ "lockfileVersion": 3,+ "requires": true,+ "packages": {+ "": {+ "name": "@wxg-prc-cpg/dsh-weknora",+ "version": "0.1.0",+ "license": "MIT",+ "devDependencies": {+ "@types/node": "^22.13.0",+ "typescript": "^5.7.3"+ },+ "engines": {+ "node": ">=20.11"+ }+ },+ "node_modules/@types/node": {+ "version": "22.20.1",+ "resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.1.tgz",+ "integrity": "sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "undici-types": "~6.21.0"+ }+ },+ "node_modules/typescript": {+ "version": "5.9.3",+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",+ "dev": true,+ "license": "Apache-2.0",+ "bin": {+ "tsc": "bin/tsc",+ "tsserver": "bin/tsserver"+ },+ "engines": {+ "node": ">=14.17"+ }+ },+ "node_modules/undici-types": {+ "version": "6.21.0",+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",+ "dev": true,+ "license": "MIT"+ }+ }+}diff --git a/packages/dsh-weknora/package.json b/packages/dsh-weknora/package.jsonnew file mode 100644index 000000000..3f075bcbc--- /dev/null+++ b/packages/dsh-weknora/package.json@@ -0,0 +1,65 @@+{+ "name": "@wxg-prc-cpg/dsh-weknora",+ "version": "0.1.0",+ "publishConfig": {+ "access": "public",+ "registry": "https://registry.npmjs.org/"+ },+ "description": "WeKnora knowledge retrieval tools for DeepSeek Harness (dsh): semantic search, document reading and RAG/agent answers over your own knowledge bases.",+ "keywords": [+ "dsh",+ "dsh-plugin",+ "deepseek-harness",+ "cordis",+ "weknora",+ "rag",+ "retrieval",+ "knowledge-base"+ ],+ "license": "MIT",+ "author": "WeKnora",+ "homepage": "https://github.com/Tencent/WeKnora/tree/main/packages/dsh-weknora",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/Tencent/WeKnora.git",+ "directory": "packages/dsh-weknora"+ },+ "bugs": {+ "url": "https://github.com/Tencent/WeKnora/issues"+ },+ "type": "module",+ "main": "./dist/index.js",+ "types": "./dist/index.d.ts",+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "default": "./dist/index.js"+ },+ "./package.json": "./package.json"+ },+ "files": [+ "dist",+ "cordis.patch.yml",+ "README.md",+ "README_CN.md"+ ],+ "engines": {+ "node": ">=20.11"+ },+ "scripts": {+ "build": "tsc -p tsconfig.build.json",+ "prepare": "npm run build",+ "typecheck": "tsc -p tsconfig.json --noEmit",+ "test": "npm run build && node --test \"test/*.test.mjs\"",+ "e2e": "node test/e2e/run-in-dsh.mjs"+ },+ "dsh": {+ "bundle": {+ "patch": "./cordis.patch.yml"+ }+ },+ "devDependencies": {+ "@types/node": "^22.13.0",+ "typescript": "^5.7.3"+ }+}diff --git a/packages/dsh-weknora/src/client.ts b/packages/dsh-weknora/src/client.tsnew file mode 100644index 000000000..b76467775--- /dev/null+++ b/packages/dsh-weknora/src/client.ts@@ -0,0 +1,391 @@+/** Minimal WeKnora REST client: JSON endpoints plus the SSE chat streams. */++import type { ResolvedConfig } from './config.ts'++/** One retrieval hit, as returned by WeKnora's `SearchResult`. */+export interface SearchResult {+ id?: string+ content?: string+ knowledge_id?: string+ chunk_index?: number+ knowledge_title?: string+ knowledge_filename?: string+ score?: number+ match_type?: number | string+ [key: string]: unknown+}++/** A knowledge base as listed by `GET /knowledge-bases`. */+export interface KnowledgeBaseSummary {+ id?: string+ name?: string+ description?: string+ [key: string]: unknown+}++/** One stored chunk as returned by `GET /chunks/:knowledge_id`. */+export interface ChunkRecord {+ id?: string+ content?: string+ chunk_index?: number+ knowledge_id?: string+ [key: string]: unknown+}++/** A document as returned by the by-name search and by `GET /knowledge/:id`. */+export interface DocumentRecord {+ id?: string+ title?: string+ file_name?: string+ file_type?: string+ description?: string+ knowledge_base_id?: string+ knowledge_base_name?: string+ [key: string]: unknown+}++/** A page of chunks plus its pagination envelope. */+export interface ChunkPage {+ chunks: ChunkRecord[]+ total: number+ page: number+ pageSize: number+}++/** The assembled outcome of one streamed answer. */+export interface StreamedAnswer {+ answer: string+ references: SearchResult[]+ sessionId: string+ toolCalls: string[]+}++/** Raised for any non-2xx response or transport failure, with the key redacted. */+export class WeknoraApiError extends Error {+ readonly status: number | undefined++ constructor(message: string, status?: number) {+ super(message)+ this.name = 'WeknoraApiError'+ this.status = status+ }+}++interface Envelope<T> {+ success?: boolean+ data?: T+ error?: unknown+ message?: string+ total?: number+ page?: number+ page_size?: number+}++/** Trim a response body for an error message without leaking a whole page. */+function snippet(body: string): string {+ const collapsed = body.replace(/\s+/g, ' ').trim()+ return collapsed.length > 300 ? `${collapsed.slice(0, 300)}…` : collapsed+}++/** Extract a human-readable reason from WeKnora's error envelope. */+function reasonOf(body: string): string {+ try {+ const parsed = JSON.parse(body) as { error?: { message?: string } | string, message?: string }+ if (typeof parsed.error === 'string') return parsed.error+ if (parsed.error?.message !== undefined) return parsed.error.message+ if (parsed.message !== undefined) return parsed.message+ } catch {+ // Fall through to the raw snippet: a proxy may answer with HTML.+ }+ return snippet(body)+}++/**+ * Combine the caller's cancellation with this call's deadline. The tool body+ * must abort when the harness aborts, and a hung backend must not hold a turn+ * open forever.+ */+function deadline(signal: AbortSignal, timeoutMs: number): AbortSignal {+ return AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])+}++export class WeknoraClient {+ constructor(private readonly config: ResolvedConfig) {}++ private headers(): Record<string, string> {+ const headers: Record<string, string> = {+ 'Content-Type': 'application/json',+ 'Accept': 'application/json',+ }+ if (this.config.apiKey !== undefined) headers['X-API-Key'] = this.config.apiKey+ if (this.config.tenantId !== undefined) headers['X-Tenant-ID'] = this.config.tenantId+ return headers+ }++ private url(path: string, query?: Record<string, string | number | undefined>): string {+ const url = new URL(`${this.config.baseUrl}${path}`)+ if (this.config.resourceUrls === 'public') url.searchParams.set('resource_urls', 'public')+ for (const [key, value] of Object.entries(query ?? {})) {+ if (value !== undefined) url.searchParams.set(key, String(value))+ }+ return url.toString()+ }++ private async fetchJson<T>(+ path: string,+ init: { method: 'GET' | 'POST', body?: unknown, query?: Record<string, string | number | undefined> },+ signal: AbortSignal,+ ): Promise<Envelope<T>> {+ const url = this.url(path, init.query)+ let response: Response+ try {+ response = await fetch(url, {+ method: init.method,+ headers: this.headers(),+ ...init.body === undefined ? {} : { body: JSON.stringify(init.body) },+ signal: deadline(signal, this.config.requestTimeoutMs),+ })+ } catch (cause) {+ throw new WeknoraApiError(`${init.method} ${path} failed: ${describeTransportFailure(cause, signal)}`)+ }+ const text = await response.text()+ if (!response.ok) {+ throw new WeknoraApiError(`${init.method} ${path} failed with HTTP ${response.status}: ${reasonOf(text)}`, response.status)+ }+ try {+ return JSON.parse(text) as Envelope<T>+ } catch {+ throw new WeknoraApiError(`${init.method} ${path} returned a non-JSON body: ${snippet(text)}`, response.status)+ }+ }++ /** List the knowledge bases this credential can retrieve from. */+ async listKnowledgeBases(signal: AbortSignal): Promise<KnowledgeBaseSummary[]> {+ const envelope = await this.fetchJson<KnowledgeBaseSummary[]>('/knowledge-bases', { method: 'GET' }, signal)+ return Array.isArray(envelope.data) ? envelope.data : []+ }++ /** Hybrid (vector + keyword) retrieval across one or more knowledge bases. */+ async search(+ input: { query: string, knowledgeBaseIds: string[], knowledgeIds: string[] },+ signal: AbortSignal,+ ): Promise<SearchResult[]> {+ const envelope = await this.fetchJson<SearchResult[]>('/knowledge-search', {+ method: 'POST',+ body: {+ query: input.query,+ ...input.knowledgeBaseIds.length > 0 ? { knowledge_base_ids: input.knowledgeBaseIds } : {},+ ...input.knowledgeIds.length > 0 ? { knowledge_ids: input.knowledgeIds } : {},+ },+ }, signal)+ return Array.isArray(envelope.data) ? envelope.data : []+ }++ /**+ * Find documents by title or filename. Unlike `search` this spans every+ * knowledge base the credential can see and needs no scope, so it is what+ * answers "where is the document called X".+ */+ async findDocuments(+ input: { keyword: string, limit: number },+ signal: AbortSignal,+ ): Promise<DocumentRecord[]> {+ const envelope = await this.fetchJson<DocumentRecord[]>('/knowledge/search', {+ method: 'GET',+ query: { keyword: input.keyword, limit: input.limit },+ }, signal)+ return Array.isArray(envelope.data) ? envelope.data : []+ }++ /** A document's metadata, including the generated summary WeKnora stores as `description`. */+ async getDocument(knowledgeId: string, signal: AbortSignal): Promise<DocumentRecord> {+ const envelope = await this.fetchJson<DocumentRecord>(+ `/knowledge/${encodeURIComponent(knowledgeId)}`,+ { method: 'GET' },+ signal,+ )+ return envelope.data ?? {}+ }++ /** One page of a document's stored chunks, in storage order. */+ async listChunks(+ input: { knowledgeId: string, page: number, pageSize: number },+ signal: AbortSignal,+ ): Promise<ChunkPage> {+ const envelope = await this.fetchJson<ChunkRecord[]>(`/chunks/${encodeURIComponent(input.knowledgeId)}`, {+ method: 'GET',+ query: { page: input.page, page_size: input.pageSize },+ }, signal)+ const chunks = Array.isArray(envelope.data) ? envelope.data : []+ return {+ chunks,+ total: typeof envelope.total === 'number' ? envelope.total : chunks.length,+ page: typeof envelope.page === 'number' ? envelope.page : input.page,+ pageSize: typeof envelope.page_size === 'number' ? envelope.page_size : input.pageSize,+ }+ }++ /** Create a conversation container to hold one or more asked questions. */+ async createSession(title: string, signal: AbortSignal): Promise<string> {+ const envelope = await this.fetchJson<{ id?: string }>('/sessions', {+ method: 'POST',+ body: { title },+ }, signal)+ const id = envelope.data?.id+ if (typeof id !== 'string' || id === '') {+ throw new WeknoraApiError('POST /sessions returned no session id')+ }+ return id+ }++ /**+ * Ask a question and assemble the streamed answer. `agentId` selects the+ * ReAct pipeline (`/agent-chat`); without it the RAG pipeline answers+ * (`/knowledge-chat`).+ */+ async ask(+ input: {+ sessionId: string+ query: string+ knowledgeBaseIds: string[]+ agentId: string | undefined+ webSearch: boolean+ },+ signal: AbortSignal,+ ): Promise<StreamedAnswer> {+ const route = input.agentId === undefined ? 'knowledge-chat' : 'agent-chat'+ const path = `/${route}/${encodeURIComponent(input.sessionId)}`+ const body = {+ query: input.query,+ channel: 'api',+ ...input.knowledgeBaseIds.length > 0 ? { knowledge_base_ids: input.knowledgeBaseIds } : {},+ ...input.agentId === undefined ? {} : { agent_id: input.agentId, agent_enabled: true },+ ...input.webSearch ? { web_search_enabled: true } : {},+ }+ const combined = deadline(signal, this.config.chatTimeoutMs)+ let response: Response+ try {+ response = await fetch(this.url(path), {+ method: 'POST',+ headers: { ...this.headers(), Accept: 'text/event-stream' },+ body: JSON.stringify(body),+ signal: combined,+ })+ } catch (cause) {+ throw new WeknoraApiError(`POST ${path} failed: ${describeTransportFailure(cause, signal)}`)+ }+ if (!response.ok) {+ const text = await response.text()+ throw new WeknoraApiError(`POST ${path} failed with HTTP ${response.status}: ${reasonOf(text)}`, response.status)+ }+ if (response.body === null) {+ throw new WeknoraApiError(`POST ${path} returned no response body`)+ }+ return await assembleStream(response.body, input.sessionId, path, signal)+ }+}++/** Turn an aborted or refused fetch into a message that names the real cause. */+function describeTransportFailure(cause: unknown, callerSignal: AbortSignal): string {+ if (cause instanceof Error && cause.name === 'AbortError') {+ return callerSignal.aborted ? 'the call was cancelled' : 'the request timed out'+ }+ if (cause instanceof Error && cause.name === 'TimeoutError') return 'the request timed out'+ return cause instanceof Error ? cause.message : String(cause)+}++/** One decoded `data:` payload of the WeKnora stream. */+interface StreamEvent {+ response_type?: string+ content?: string+ knowledge_references?: SearchResult[]+ session_id?: string+ tool_calls?: { function?: { name?: string }, name?: string }[]+}++/**+ * Consume WeKnora's `text/event-stream` and assemble the parts a tool result+ * needs: the answer text, its citations, and the tool names the agent used.+ * Server-side `error` events become a thrown failure so the model is never+ * handed a silently empty answer.+ */+async function assembleStream(+ body: ReadableStream<Uint8Array>,+ sessionId: string,+ path: string,+ callerSignal: AbortSignal,+): Promise<StreamedAnswer> {+ const decoder = new TextDecoder()+ const reader = body.getReader()+ const answer: string[] = []+ const toolCalls: string[] = []+ let references: SearchResult[] = []+ let resolvedSessionId = sessionId+ let buffer = ''+ let completed = false++ const consumeLine = (line: string): void => {+ if (!line.startsWith('data:')) return+ const payload = line.slice(5).trim()+ if (payload === '' || payload === '[DONE]') return+ let event: StreamEvent+ try {+ event = JSON.parse(payload) as StreamEvent+ } catch {+ return+ }+ if (typeof event.session_id === 'string' && event.session_id !== '') resolvedSessionId = event.session_id+ switch (event.response_type) {+ case 'answer':+ if (typeof event.content === 'string') answer.push(event.content)+ break+ case 'references':+ if (Array.isArray(event.knowledge_references)) references = event.knowledge_references+ break+ case 'tool_call':+ for (const call of event.tool_calls ?? []) {+ const name = call.function?.name ?? call.name+ if (typeof name === 'string' && name !== '' && !toolCalls.includes(name)) toolCalls.push(name)+ }+ break+ case 'error':+ throw new WeknoraApiError(`POST ${path} streamed an error: ${event.content ?? 'unknown error'}`)+ case 'complete':+ completed = true+ break+ default:+ break+ }+ }++ try {+ while (!completed) {+ const { done, value } = await reader.read()+ if (done) break+ buffer += decoder.decode(value, { stream: true })+ let newline = buffer.indexOf('\n')+ while (newline >= 0) {+ consumeLine(buffer.slice(0, newline).replace(/\r$/, ''))+ buffer = buffer.slice(newline + 1)+ if (completed) break+ newline = buffer.indexOf('\n')+ }+ }+ if (!completed && buffer !== '') consumeLine(buffer.replace(/\r$/, ''))+ } catch (cause) {+ if (cause instanceof WeknoraApiError) throw cause+ throw new WeknoraApiError(`POST ${path} stream failed: ${describeTransportFailure(cause, callerSignal)}`)+ } finally {+ await reader.cancel().catch(() => undefined)+ }++ // WeKnora ends every answer with a `complete` event. Without it the stream was+ // cut short, and handing the model the partial text would present a truncated+ // answer as a whole one.+ if (!completed) {+ throw new WeknoraApiError(`POST ${path} ended before WeKnora completed the answer; `+ + `${answer.join('').length} character(s) had streamed`)+ }++ return { answer: answer.join(''), references, sessionId: resolvedSessionId, toolCalls }+}diff --git a/packages/dsh-weknora/src/config.ts b/packages/dsh-weknora/src/config.tsnew file mode 100644index 000000000..f746de080--- /dev/null+++ b/packages/dsh-weknora/src/config.ts@@ -0,0 +1,188 @@+/** Plugin configuration: shape, defaults, and load-time validation. */++/** Which tools the plugin registers. Omitted entries keep their default. */+export interface ToolToggles {+ listKnowledgeBases?: boolean+ search?: boolean+ readDocument?: boolean+ ask?: boolean+}++/** User-supplied configuration, as written in a Cordis patch row. */+export interface Config {+ /** WeKnora API root, with or without the `/api/v1` suffix. */+ baseUrl?: string+ /** Tenant or platform API key, sent as `X-API-Key`. */+ apiKey?: string+ /** Workspace id, required only for platform-scoped API keys (`X-Tenant-ID`). */+ tenantId?: string+ /** Default knowledge-base scope when a call names none. */+ knowledgeBaseIds?: string[]+ /** Default custom agent for `weknora_ask`; omitted uses the RAG pipeline. */+ agentId?: string+ /** Default and maximum number of chunks a search returns. */+ maxResults?: number+ /** Per-chunk character budget before the plugin truncates content. */+ maxChunkChars?: number+ /** Timeout for non-streaming requests. */+ requestTimeoutMs?: number+ /** Timeout for a streamed answer, which includes model and tool time. */+ chatTimeoutMs?: number+ /** `public` asks WeKnora for directly loadable file URLs in citations. */+ resourceUrls?: 'handle' | 'public'+ /** Tool-name prefix, so two instances can serve two deployments. */+ toolPrefix?: string+ /** Per-tool registration switches. */+ tools?: ToolToggles+}++/** Configuration after defaults and validation. */+export interface ResolvedConfig {+ baseUrl: string+ apiKey: string | undefined+ tenantId: string | undefined+ knowledgeBaseIds: string[]+ agentId: string | undefined+ maxResults: number+ maxChunkChars: number+ requestTimeoutMs: number+ chatTimeoutMs: number+ resourceUrls: 'handle' | 'public'+ toolPrefix: string+ tools: Required<ToolToggles>+}++const DEFAULTS = {+ baseUrl: 'http://localhost:8080/api/v1',+ maxResults: 8,+ maxChunkChars: 1200,+ requestTimeoutMs: 30_000,+ chatTimeoutMs: 300_000,+ resourceUrls: 'handle',+ toolPrefix: 'weknora',+} as const++/** Thrown when a patch row configures this plugin in a way it cannot serve. */+export class ConfigError extends Error {+ constructor(violations: string[]) {+ super(`dsh-weknora configuration is invalid:\n - ${violations.join('\n - ')}`)+ this.name = 'ConfigError'+ }+}++const API_ROOT = /\/api\/v\d+$/+const TOOL_PREFIX = /^[a-z][a-z0-9_]*$/++/**+ * Normalize a WeKnora base URL to an API root. Both `https://kb.example.com`+ * and `https://kb.example.com/api/v1` are accepted, because a deployment's+ * documented address is usually the bare origin.+ */+export function normalizeBaseUrl(raw: string): string {+ const trimmed = raw.trim().replace(/\/+$/, '')+ return API_ROOT.test(trimmed) ? trimmed : `${trimmed}/api/v1`+}++function positiveInt(value: unknown, field: string, violations: string[]): number | undefined {+ if (value === undefined) return undefined+ if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {+ violations.push(`${field} must be a positive number, received ${JSON.stringify(value)}`)+ return undefined+ }+ return Math.floor(value)+}++function stringList(value: unknown, field: string, violations: string[]): string[] | undefined {+ if (value === undefined) return undefined+ if (!Array.isArray(value) || value.some(entry => typeof entry !== 'string' || entry.trim() === '')) {+ violations.push(`${field} must be an array of non-empty strings`)+ return undefined+ }+ return (value as string[]).map(entry => entry.trim())+}++function optionalString(value: unknown, field: string, violations: string[]): string | undefined {+ if (value === undefined || value === null || value === '') return undefined+ if (typeof value !== 'string') {+ violations.push(`${field} must be a string`)+ return undefined+ }+ const trimmed = value.trim()+ return trimmed === '' ? undefined : trimmed+}++function toggle(value: unknown, field: string, fallback: boolean, violations: string[]): boolean {+ if (value === undefined) return fallback+ if (typeof value !== 'boolean') {+ violations.push(`${field} must be a boolean`)+ return fallback+ }+ return value+}++/**+ * Apply defaults and reject an unusable row while the plugin loads, so a typo+ * surfaces at boot rather than inside the first tool call the model makes.+ * @param raw - the `config` value from the Cordis row.+ * @returns configuration every consumer can read without re-checking.+ */+export function resolveConfig(raw: Config | undefined): ResolvedConfig {+ const violations: string[] = []+ const config = raw ?? {}+ if (typeof config !== 'object' || Array.isArray(config)) {+ throw new ConfigError(['config must be an object'])+ }++ const baseUrlInput = optionalString(config.baseUrl, 'baseUrl', violations) ?? DEFAULTS.baseUrl+ let baseUrl: string = DEFAULTS.baseUrl+ try {+ const url = new URL(normalizeBaseUrl(baseUrlInput))+ if (url.protocol !== 'http:' && url.protocol !== 'https:') {+ violations.push(`baseUrl must use http or https, received ${url.protocol}`)+ }+ baseUrl = url.toString().replace(/\/+$/, '')+ } catch {+ violations.push(`baseUrl must be an absolute URL, received ${JSON.stringify(baseUrlInput)}`)+ }++ const resourceUrls = config.resourceUrls ?? DEFAULTS.resourceUrls+ if (resourceUrls !== 'handle' && resourceUrls !== 'public') {+ violations.push(`resourceUrls must be "handle" or "public", received ${JSON.stringify(resourceUrls)}`)+ }++ const toolPrefix = optionalString(config.toolPrefix, 'toolPrefix', violations) ?? DEFAULTS.toolPrefix+ if (!TOOL_PREFIX.test(toolPrefix)) {+ violations.push(`toolPrefix must match ${String(TOOL_PREFIX)}, received ${JSON.stringify(toolPrefix)}`)+ }++ const toolToggles = config.tools ?? {}+ if (typeof toolToggles !== 'object' || Array.isArray(toolToggles)) {+ violations.push('tools must be an object of booleans')+ }++ const resolved: ResolvedConfig = {+ baseUrl,+ apiKey: optionalString(config.apiKey, 'apiKey', violations),+ tenantId: optionalString(config.tenantId, 'tenantId', violations),+ knowledgeBaseIds: stringList(config.knowledgeBaseIds, 'knowledgeBaseIds', violations) ?? [],+ agentId: optionalString(config.agentId, 'agentId', violations),+ maxResults: positiveInt(config.maxResults, 'maxResults', violations) ?? DEFAULTS.maxResults,+ maxChunkChars: positiveInt(config.maxChunkChars, 'maxChunkChars', violations) ?? DEFAULTS.maxChunkChars,+ requestTimeoutMs: positiveInt(config.requestTimeoutMs, 'requestTimeoutMs', violations) ?? DEFAULTS.requestTimeoutMs,+ chatTimeoutMs: positiveInt(config.chatTimeoutMs, 'chatTimeoutMs', violations) ?? DEFAULTS.chatTimeoutMs,+ resourceUrls: resourceUrls === 'public' ? 'public' : 'handle',+ toolPrefix,+ tools: {+ listKnowledgeBases: toggle(toolToggles.listKnowledgeBases, 'tools.listKnowledgeBases', true, violations),+ search: toggle(toolToggles.search, 'tools.search', true, violations),+ readDocument: toggle(toolToggles.readDocument, 'tools.readDocument', true, violations),+ ask: toggle(toolToggles.ask, 'tools.ask', true, violations),+ },+ }++ if (!Object.values(resolved.tools).some(Boolean)) {+ violations.push('at least one tool must stay enabled; remove the plugin row instead of disabling all of them')+ }+ if (violations.length > 0) throw new ConfigError(violations)+ return resolved+}diff --git a/packages/dsh-weknora/src/harness.ts b/packages/dsh-weknora/src/harness.tsnew file mode 100644index 000000000..a8e49f032--- /dev/null+++ b/packages/dsh-weknora/src/harness.ts@@ -0,0 +1,62 @@+/**+ * Structural types for the slice of the DeepSeek Harness contract this plugin+ * uses. Declaring them here keeps the package free of runtime dependencies on+ * harness internals: the shipped code only ever hands `ctx.tools.register()` a+ * plain object, so a harness release that adds optional definition fields does+ * not require a republish of this plugin.+ *+ * The shapes mirror `@deepseek-ai/dsh-tools` (`ToolDefinition`) and+ * `@deepseek-ai/dsh-llm` (`ContentBlock`, `ToolSchema`) as of dsh 0.1.0-rc.8.+ */++/** Supported subset of JSON Schema that the harness tool registry accepts. */+export interface JsonSchemaNode {+ type?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'+ properties?: Record<string, JsonSchemaNode>+ required?: string[]+ additionalProperties?: boolean+ items?: JsonSchemaNode+ enum?: (string | number | boolean | null)[]+ const?: string | number | boolean | null+ description?: string+ title?: string+}++/** Model-facing content block returned by `output.render`. */+export interface TextContentBlock {+ type: 'text'+ text: string+}++/** Execution context handed to a tool body. */+export interface ToolRunContext {+ readonly signal: AbortSignal+}++/** One registered model-facing tool. */+export interface ToolDefinition {+ readonly name: string+ readonly description: string+ readonly parameters: JsonSchemaNode+ readonly output: {+ readonly schema: JsonSchemaNode+ render(args: unknown, value: unknown): TextContentBlock[]+ }+ execute(args: unknown, exec: ToolRunContext): Promise<unknown>+ readonly timeoutMs?: number+ isConcurrencySafe?(args: unknown): boolean+}++/** The `ctx.tools` service seam. */+export interface ToolRegistry {+ register(definition: ToolDefinition): () => void+}++/** The slice of the Cordis context this plugin injects. */+export interface HarnessContext {+ readonly tools: ToolRegistry+ readonly logger?: {+ info(...args: unknown[]): void+ warn(...args: unknown[]): void+ }+}diff --git a/packages/dsh-weknora/src/index.ts b/packages/dsh-weknora/src/index.tsnew file mode 100644index 000000000..ae165708c--- /dev/null+++ b/packages/dsh-weknora/src/index.ts@@ -0,0 +1,37 @@+/**+ * dsh-weknora: a DeepSeek Harness plugin that gives the agent retrieval,+ * document reading and composed answers from a WeKnora knowledge base.+ * @module dsh-weknora+ */++import { WeknoraClient } from './client.ts'+import { resolveConfig } from './config.ts'+import type { HarnessContext } from './harness.ts'+import { createTools } from './tools.ts'++export const name = 'dsh-weknora'++/** Cordis waits for the tool registry before applying this plugin. */+export const inject = ['tools'] as const++export type { Config } from './config.ts'+export { ConfigError, normalizeBaseUrl, resolveConfig } from './config.ts'+export { WeknoraApiError, WeknoraClient } from './client.ts'+export { createTools } from './tools.ts'++/**+ * Register the configured tools. Each registration is an effect, so unloading+ * or reconfiguring the plugin withdraws the tools without a restart.+ * @param ctx - the Cordis context, with `ctx.tools` injected.+ * @param config - the plugin's `config` row; validated here so a typo fails the load.+ */+export function apply(ctx: HarnessContext, config: unknown): void {+ const resolved = resolveConfig(config as never)+ const client = new WeknoraClient(resolved)+ const registered: string[] = []+ for (const definition of createTools(client, resolved)) {+ ctx.tools.register(definition)+ registered.push(definition.name)+ }+ ctx.logger?.info(`dsh-weknora: registered ${registered.join(', ')} against ${resolved.baseUrl}`)+}diff --git a/packages/dsh-weknora/src/render.ts b/packages/dsh-weknora/src/render.tsnew file mode 100644index 000000000..2bcbdb01e--- /dev/null+++ b/packages/dsh-weknora/src/render.ts@@ -0,0 +1,25 @@+/** Pure projections from a tool's canonical value to model-facing text. */++/** Clip text to a character budget, reporting whether anything was dropped. */+export function clip(text: string, maxChars: number): { text: string, truncated: boolean } {+ const normalized = text.replace(/\r\n/g, '\n').trim()+ if (normalized.length <= maxChars) return { text: normalized, truncated: false }+ return { text: `${normalized.slice(0, maxChars).trimEnd()}…`, truncated: true }+}++/** Human-readable score, tolerant of a backend that omits it. */+export function formatScore(score: number): string {+ return Number.isFinite(score) ? score.toFixed(3) : 'n/a'+}++/**+ * Name a retrieval scope without spending the model's context on it. A+ * deployment can hold dozens of knowledge bases, and spelling out every id on+ * every search costs far more than the count is worth; the ids stay in the+ * tool's canonical value for anything that needs them.+ */+export function describeScope(ids: string[]): string {+ if (ids.length === 0) return '(deployment default)'+ if (ids.length <= 3) return ids.join(', ')+ return `${ids.length} knowledge bases`+}diff --git a/packages/dsh-weknora/src/tools.ts b/packages/dsh-weknora/src/tools.tsnew file mode 100644index 000000000..5be1999e3--- /dev/null+++ b/packages/dsh-weknora/src/tools.ts@@ -0,0 +1,562 @@+/** The model-facing tools this plugin contributes to `ctx.tools`. */++import type { ChunkRecord, DocumentRecord, SearchResult, WeknoraClient } from './client.ts'+import type { ResolvedConfig } from './config.ts'+import type { JsonSchemaNode, TextContentBlock, ToolDefinition } from './harness.ts'+import { clip, describeScope, formatScore } from './render.ts'++/** A retrieval hit projected onto the fields the model and follow-up calls need. */+interface SearchHit {+ rank: number+ chunk_id: string+ knowledge_id: string+ document: string+ chunk_index: number+ score: number+ content: string+ truncated: boolean+}++/** A document whose name matched, which passage retrieval alone would miss. */+interface DocumentMatch {+ knowledge_id: string+ title: string+ knowledge_base_id: string+ knowledge_base: string+}++interface SearchValue {+ query: string+ knowledge_base_ids: string[]+ count: number+ results: SearchHit[]+ documents: DocumentMatch[]+}++interface KnowledgeBasesValue {+ count: number+ knowledge_bases: { id: string, name: string, description: string }[]+}++interface DocumentValue {+ knowledge_id: string+ title: string+ summary: string+ page: number+ page_size: number+ total_chunks: number+ returned_chunks: number+ has_more: boolean+ truncated: boolean+ content: string+}++interface AskValue {+ answer: string+ session_id: string+ pipeline: 'rag' | 'agent'+ tool_calls: string[]+ references: { knowledge_id: string, document: string, chunk_index: number, content: string }[]+}++const text = (value: string): TextContentBlock[] => [{ type: 'text', text: value }]++const STRING_ARRAY: JsonSchemaNode = { type: 'array', items: { type: 'string' } }++/** Read an argument the harness passes as `unknown` without trusting its shape. */+function argRecord(args: unknown): Record<string, unknown> {+ return typeof args === 'object' && args !== null && !Array.isArray(args) ? args as Record<string, unknown> : {}+}++function requiredString(args: unknown, field: string, toolName: string): string {+ const value = argRecord(args)[field]+ if (typeof value !== 'string' || value.trim() === '') {+ throw new Error(`${toolName}: "${field}" is required and must be a non-empty string`)+ }+ return value.trim()+}++function optionalStringArg(args: unknown, field: string): string | undefined {+ const value = argRecord(args)[field]+ return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined+}++function stringArrayArg(args: unknown, field: string): string[] {+ const value = argRecord(args)[field]+ if (!Array.isArray(value)) return []+ return value.filter((entry): entry is string => typeof entry === 'string' && entry.trim() !== '').map(entry => entry.trim())+}++function boundedIntArg(args: unknown, field: string, fallback: number, max: number): number {+ const value = argRecord(args)[field]+ if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return fallback+ return Math.min(Math.floor(value), max)+}++/** Prefer a human title, then the source filename, then the opaque id. */+function documentLabel(result: SearchResult): string {+ const title = typeof result.knowledge_title === 'string' ? result.knowledge_title.trim() : ''+ if (title !== '') return title+ const filename = typeof result.knowledge_filename === 'string' ? result.knowledge_filename.trim() : ''+ if (filename !== '') return filename+ return typeof result.knowledge_id === 'string' && result.knowledge_id !== '' ? result.knowledge_id : '(untitled)'+}++function projectHit(result: SearchResult, rank: number, maxChunkChars: number): SearchHit {+ const clipped = clip(typeof result.content === 'string' ? result.content : '', maxChunkChars)+ return {+ rank,+ chunk_id: typeof result.id === 'string' ? result.id : '',+ knowledge_id: typeof result.knowledge_id === 'string' ? result.knowledge_id : '',+ document: documentLabel(result),+ chunk_index: typeof result.chunk_index === 'number' ? result.chunk_index : -1,+ // 0 rather than NaN: the canonical value must stay lossless JSON.+ score: typeof result.score === 'number' && Number.isFinite(result.score) ? result.score : 0,+ content: clipped.text,+ truncated: clipped.truncated,+ }+}++/**+ * Keep the by-name matches worth showing: inside the scope the caller asked+ * for, and not already represented by a passage hit. WeKnora's by-name search+ * spans the whole tenant, so the scope filter is what stops a narrowed call+ * from reporting documents outside it.+ */+function projectNamedDocuments(+ named: DocumentRecord[],+ passages: SearchHit[],+ knowledgeBaseIds: string[],+ knowledgeIds: string[],+): DocumentMatch[] {+ const already = new Set(passages.map(hit => hit.knowledge_id))+ const scope = new Set(knowledgeBaseIds)+ const wanted = new Set(knowledgeIds)+ const out: DocumentMatch[] = []+ for (const document of named) {+ const id = typeof document.id === 'string' ? document.id : ''+ const kbId = typeof document.knowledge_base_id === 'string' ? document.knowledge_base_id : ''+ if (id === '' || already.has(id)) continue+ if (wanted.size > 0 ? !wanted.has(id) : !scope.has(kbId)) continue+ const title = typeof document.title === 'string' && document.title.trim() !== ''+ ? document.title.trim()+ : typeof document.file_name === 'string' ? document.file_name : id+ out.push({+ knowledge_id: id,+ title,+ knowledge_base_id: kbId,+ knowledge_base: typeof document.knowledge_base_name === 'string' ? document.knowledge_base_name : kbId,+ })+ already.add(id)+ }+ return out+}++/** Assemble the four tool definitions for one configured deployment. */+export function createTools(client: WeknoraClient, config: ResolvedConfig): ToolDefinition[] {+ const name = (suffix: string): string => `${config.toolPrefix}_${suffix}`+ const scopeNote = config.knowledgeBaseIds.length > 0+ ? ` Searches knowledge base(s) ${config.knowledgeBaseIds.join(', ')} unless you name others.`+ : ' Searches every knowledge base this credential can see unless you narrow it with knowledge_base_ids.'++ // An unscoped call reaches WeKnora as a refusal on the retrieval route and as+ // an answer grounded in nothing on the RAG route, so an unconfigured+ // deployment resolves the full visible set once and reuses it. Making the+ // model pick a scope first is worse: knowledge bases are often named too+ // poorly to choose between, and fanning out across them is cheap while they+ // share a vector store.+ let everyId: Promise<string[]> | undefined+ const allKnowledgeBaseIds = async (signal: AbortSignal): Promise<string[]> => {+ everyId ??= client.listKnowledgeBases(signal).then(+ bases => bases.map(kb => typeof kb.id === 'string' ? kb.id : '').filter(id => id !== ''),+ (error: unknown) => {+ everyId = undefined+ throw error+ },+ )+ return await everyId+ }+ const resolveScope = async (requested: string[], knowledgeIds: string[], signal: AbortSignal): Promise<string[]> => {+ if (requested.length > 0) return requested+ if (config.knowledgeBaseIds.length > 0) return config.knowledgeBaseIds+ if (knowledgeIds.length > 0) return []+ return await allKnowledgeBaseIds(signal)+ }++ const definitions: ToolDefinition[] = []++ if (config.tools.listKnowledgeBases) {+ definitions.push({+ name: name('list_knowledge_bases'),+ description: 'List the WeKnora knowledge bases this deployment can retrieve from, with their ids. '+ + `${name('search')} already spans them all, so reach for this only to report what is available or to `+ + 'narrow a later search to one of them.',+ parameters: { type: 'object', properties: {}, additionalProperties: false },+ timeoutMs: config.requestTimeoutMs,+ isConcurrencySafe: () => true,+ output: {+ schema: {+ type: 'object',+ properties: {+ count: { type: 'integer' },+ knowledge_bases: {+ type: 'array',+ items: {+ type: 'object',+ properties: {+ id: { type: 'string' },+ name: { type: 'string' },+ description: { type: 'string' },+ },+ required: ['id', 'name', 'description'],+ additionalProperties: false,+ },+ },+ },+ required: ['count', 'knowledge_bases'],+ additionalProperties: false,+ },+ render: (_args, value) => {+ const result = value as KnowledgeBasesValue+ if (result.count === 0) return text('No knowledge base is available to this WeKnora credential.')+ const lines = result.knowledge_bases.map(kb => {+ const description = kb.description === '' ? '' : ` — ${kb.description}`+ return `- ${kb.name} (id: ${kb.id})${description}`+ })+ return text(`${result.count} knowledge base(s):\n${lines.join('\n')}`)+ },+ },+ async execute(_args, exec): Promise<KnowledgeBasesValue> {+ const bases = await client.listKnowledgeBases(exec.signal)+ return {+ count: bases.length,+ knowledge_bases: bases.map(kb => ({+ id: typeof kb.id === 'string' ? kb.id : '',+ name: typeof kb.name === 'string' ? kb.name : '',+ description: typeof kb.description === 'string' ? kb.description : '',+ })),+ }+ },+ })+ }++ if (config.tools.search) {+ definitions.push({+ name: name('search'),+ description: 'Search WeKnora knowledge bases and return the matching passages verbatim (hybrid vector + keyword '+ + 'retrieval, no model summarization). Use this to ground an answer in the organization\'s own documents, and '+ + 'also to locate a document by name — a query that reads like a title additionally returns the documents it '+ + 'names.' + scopeNote+ + ` Every hit carries a knowledge_id you can pass to ${name('read_document')} for the full document.`,+ parameters: {+ type: 'object',+ properties: {+ query: { type: 'string', description: 'Natural-language query; a full question retrieves better than keywords.' },+ knowledge_base_ids: { ...STRING_ARRAY, description: 'Restrict the search to these knowledge base ids.' },+ knowledge_ids: { ...STRING_ARRAY, description: 'Restrict the search to these document ids.' },+ max_results: { type: 'integer', description: `Maximum passages to return (default ${config.maxResults}).` },+ },+ required: ['query'],+ additionalProperties: false,+ },+ timeoutMs: config.requestTimeoutMs,+ isConcurrencySafe: () => true,+ output: {+ schema: {+ type: 'object',+ properties: {+ query: { type: 'string' },+ knowledge_base_ids: STRING_ARRAY,+ count: { type: 'integer' },+ results: {+ type: 'array',+ items: {+ type: 'object',+ properties: {+ rank: { type: 'integer' },+ chunk_id: { type: 'string' },+ knowledge_id: { type: 'string' },+ document: { type: 'string' },+ chunk_index: { type: 'integer' },+ score: { type: 'number' },+ content: { type: 'string' },+ truncated: { type: 'boolean' },+ },+ required: ['rank', 'chunk_id', 'knowledge_id', 'document', 'chunk_index', 'score', 'content', 'truncated'],+ additionalProperties: false,+ },+ },+ documents: {+ type: 'array',+ items: {+ type: 'object',+ properties: {+ knowledge_id: { type: 'string' },+ title: { type: 'string' },+ knowledge_base_id: { type: 'string' },+ knowledge_base: { type: 'string' },+ },+ required: ['knowledge_id', 'title', 'knowledge_base_id', 'knowledge_base'],+ additionalProperties: false,+ },+ },+ },+ required: ['query', 'knowledge_base_ids', 'count', 'results', 'documents'],+ additionalProperties: false,+ },+ render: (_args, value) => {+ const result = value as SearchValue+ const named = result.documents.length === 0+ ? ''+ : `\n\nDocuments named "${result.query}" (read them with ${name('read_document')}):\n`+ + result.documents.map(document =>+ `- ${document.title} · knowledge_id: ${document.knowledge_id} · in ${document.knowledge_base}`).join('\n')+ if (result.count === 0) {+ if (named === '') {+ return text(`Nothing in WeKnora matched "${result.query}" `+ + `(searched: ${describeScope(result.knowledge_base_ids)}). `+ + 'Try a differently worded query, or widen the knowledge base scope.')+ }+ return text(`No passage matched "${result.query}", but its name matches document(s).${named}`)+ }+ const blocks = result.results.map(hit =>+ `[${hit.rank}] ${hit.document} · score ${formatScore(hit.score)} · chunk ${hit.chunk_index} `+ + `· knowledge_id: ${hit.knowledge_id}\n${hit.content}${hit.truncated ? '\n(passage truncated)' : ''}`)+ return text(`${result.count} passage(s) for "${result.query}" `+ + `(searched: ${describeScope(result.knowledge_base_ids)}):\n\n${blocks.join('\n\n')}${named}`)+ },+ },+ async execute(args, exec): Promise<SearchValue> {+ const toolName = name('search')+ const query = requiredString(args, 'query', toolName)+ const knowledgeIds = stringArrayArg(args, 'knowledge_ids')+ const knowledgeBaseIds = await resolveScope(+ stringArrayArg(args, 'knowledge_base_ids'),+ knowledgeIds,+ exec.signal,+ )+ // Fail here rather than let WeKnora answer 400: the model can act on a+ // message naming the argument to supply, not on a transport error.+ if (knowledgeBaseIds.length === 0 && knowledgeIds.length === 0) {+ throw new Error(`${toolName}: this WeKnora credential can see no knowledge base, so there is `+ + 'nothing to search. Check the deployment\'s API key scope.')+ }+ const limit = boundedIntArg(args, 'max_results', config.maxResults, config.maxResults)+ const [hits, named] = await Promise.all([+ client.search({ query, knowledgeBaseIds, knowledgeIds }, exec.signal),+ // By-name matching is an enrichment, and older WeKnora builds may not+ // route it. Losing it must not cost the model its passages.+ client.findDocuments({ keyword: query, limit }, exec.signal).catch(() => []),+ ])+ const results = hits.slice(0, limit).map((hit, index) => projectHit(hit, index + 1, config.maxChunkChars))+ return {+ query,+ knowledge_base_ids: knowledgeBaseIds,+ count: results.length,+ results,+ documents: projectNamedDocuments(named, results, knowledgeBaseIds, knowledgeIds),+ }+ },+ })+ }++ if (config.tools.readDocument) {+ definitions.push({+ name: name('read_document'),+ description: 'Read a WeKnora document\'s stored passages in order, reassembled into text. '+ + `Use it after ${name('search')} when one passage is not enough context; page through long documents.`,+ parameters: {+ type: 'object',+ properties: {+ knowledge_id: { type: 'string', description: 'Document id, as returned in a search hit.' },+ page: { type: 'integer', description: 'Page of passages, starting at 1.' },+ page_size: { type: 'integer', description: 'Passages per page (max 100).' },+ },+ required: ['knowledge_id'],+ additionalProperties: false,+ },+ timeoutMs: config.requestTimeoutMs,+ isConcurrencySafe: () => true,+ output: {+ schema: {+ type: 'object',+ properties: {+ knowledge_id: { type: 'string' },+ title: { type: 'string' },+ summary: { type: 'string' },+ page: { type: 'integer' },+ page_size: { type: 'integer' },+ total_chunks: { type: 'integer' },+ returned_chunks: { type: 'integer' },+ has_more: { type: 'boolean' },+ truncated: { type: 'boolean' },+ content: { type: 'string' },+ },+ required: [+ 'knowledge_id', 'title', 'summary', 'page', 'page_size',+ 'total_chunks', 'returned_chunks', 'has_more', 'truncated', 'content',+ ],+ additionalProperties: false,+ },+ render: (_args, value) => {+ const result = value as DocumentValue+ const label = result.title === '' ? result.knowledge_id : `${result.title} (${result.knowledge_id})`+ if (result.returned_chunks === 0) {+ return text(`Document ${label} has no passage on page ${result.page} `+ + `(${result.total_chunks} passage(s) in total).`)+ }+ // The summary lets the model judge a long document from page 1+ // instead of paging blindly to find out what it is holding.+ const summary = result.summary === '' ? '' : `\n\nSummary: ${result.summary}`+ const more = result.has_more ? `\n\n(more passages available: request page ${result.page + 1})` : ''+ const cut = result.truncated ? '\n(content truncated)' : ''+ return text(`Document ${label}, passages ${result.returned_chunks} of ${result.total_chunks} `+ + `(page ${result.page}):${summary}\n\n${result.content}${cut}${more}`)+ },+ },+ async execute(args, exec): Promise<DocumentValue> {+ const toolName = name('read_document')+ const knowledgeId = requiredString(args, 'knowledge_id', toolName)+ const page = boundedIntArg(args, 'page', 1, 10_000)+ const pageSize = boundedIntArg(args, 'page_size', 20, 100)+ const [result, metadata] = await Promise.all([+ client.listChunks({ knowledgeId, page, pageSize }, exec.signal),+ // Only page 1 is worth the extra call and the summary's tokens: by+ // page 2 the model has already seen what this document is. Metadata+ // is context, not the payload, so a deployment that cannot serve it+ // must still hand over the text.+ page === 1+ ? client.getDocument(knowledgeId, exec.signal).catch(() => ({}) as DocumentRecord)+ : Promise.resolve({} as DocumentRecord),+ ])+ const ordered = [...result.chunks].sort(orderByChunkIndex)+ const joined = ordered.map(chunk => typeof chunk.content === 'string' ? chunk.content : '').join('\n\n')+ const clipped = clip(joined, config.maxChunkChars * Math.max(1, Math.min(ordered.length, 10)))+ const title = typeof metadata.title === 'string' && metadata.title.trim() !== ''+ ? metadata.title.trim()+ : typeof metadata.file_name === 'string' ? metadata.file_name.trim() : ''+ return {+ knowledge_id: knowledgeId,+ title,+ summary: clip(typeof metadata.description === 'string' ? metadata.description.trim() : '', config.maxChunkChars).text,+ page: result.page,+ page_size: result.pageSize,+ total_chunks: result.total,+ returned_chunks: ordered.length,+ has_more: result.page * result.pageSize < result.total,+ truncated: clipped.truncated,+ content: clipped.text,+ }+ },+ })+ }++ if (config.tools.ask) {+ const pipeline = config.agentId === undefined ? 'RAG' : 'agent'+ definitions.push({+ name: name('ask'),+ description: `Ask WeKnora a question and get its own composed answer with citations (${pipeline} pipeline runs `+ + 'server-side: query rewriting, retrieval, reranking and summarization). Reserve it for broad or '+ + 'synthesis questions whose answer spans many documents, where retrieving passages yourself would take '+ + `several rounds. For anything you can answer from specific passages, prefer ${name('search')}: it is far `+ + 'faster and leaves you the evidence to reason over rather than another model\'s conclusion.',+ parameters: {+ type: 'object',+ properties: {+ query: { type: 'string', description: 'The question to answer.' },+ knowledge_base_ids: { ...STRING_ARRAY, description: 'Restrict retrieval to these knowledge base ids.' },+ agent_id: { type: 'string', description: 'Custom agent id; selects the server-side ReAct pipeline.' },+ session_id: { type: 'string', description: 'Continue an earlier WeKnora session instead of starting one.' },+ web_search: { type: 'boolean', description: 'Let WeKnora also search the web, when its deployment allows it.' },+ },+ required: ['query'],+ additionalProperties: false,+ },+ timeoutMs: config.chatTimeoutMs,+ output: {+ schema: {+ type: 'object',+ properties: {+ answer: { type: 'string' },+ session_id: { type: 'string' },+ pipeline: { type: 'string', enum: ['rag', 'agent'] },+ tool_calls: STRING_ARRAY,+ references: {+ type: 'array',+ items: {+ type: 'object',+ properties: {+ knowledge_id: { type: 'string' },+ document: { type: 'string' },+ chunk_index: { type: 'integer' },+ content: { type: 'string' },+ },+ required: ['knowledge_id', 'document', 'chunk_index', 'content'],+ additionalProperties: false,+ },+ },+ },+ required: ['answer', 'session_id', 'pipeline', 'tool_calls', 'references'],+ additionalProperties: false,+ },+ render: (_args, value) => {+ const result = value as AskValue+ const parts: string[] = []+ parts.push(result.answer === ''+ ? 'WeKnora returned an empty answer. Retry with a more specific question, or retrieve passages instead.'+ : result.answer)+ if (result.references.length > 0) {+ const cited = result.references.map((reference, index) =>+ `[${index + 1}] ${reference.document} · chunk ${reference.chunk_index} · knowledge_id: ${reference.knowledge_id}`)+ parts.push(`Citations:\n${cited.join('\n')}`)+ }+ if (result.tool_calls.length > 0) parts.push(`WeKnora tools used: ${result.tool_calls.join(', ')}`)+ parts.push(`WeKnora session: ${result.session_id} (pass session_id to ask a follow-up in context)`)+ return text(parts.join('\n\n'))+ },+ },+ async execute(args, exec): Promise<AskValue> {+ const toolName = name('ask')+ const query = requiredString(args, 'query', toolName)+ const requested = stringArrayArg(args, 'knowledge_base_ids')+ const agentId = optionalStringArg(args, 'agent_id') ?? config.agentId+ // A custom agent resolves its own scope server-side from its+ // KBSelectionMode, and ids sent here would override that as an explicit+ // mention. The RAG pipeline has no such default: it retrieves only what+ // the request names, and answers from nothing when it names nothing.+ const knowledgeBaseIds = agentId === undefined+ ? await resolveScope(requested, [], exec.signal)+ : requested.length > 0 ? requested : config.knowledgeBaseIds+ if (agentId === undefined && knowledgeBaseIds.length === 0) {+ throw new Error(`${toolName}: this WeKnora credential can see no knowledge base, so there is `+ + 'nothing to answer from. Check the deployment\'s API key scope.')+ }+ const webSearch = argRecord(args)['web_search'] === true+ const sessionId = optionalStringArg(args, 'session_id')+ ?? await client.createSession(`dsh: ${clip(query, 60).text}`, exec.signal)+ const streamed = await client.ask({ sessionId, query, knowledgeBaseIds, agentId, webSearch }, exec.signal)+ return {+ answer: streamed.answer.trim(),+ session_id: streamed.sessionId,+ pipeline: agentId === undefined ? 'rag' : 'agent',+ tool_calls: streamed.toolCalls,+ references: streamed.references.slice(0, config.maxResults).map(reference => ({+ knowledge_id: typeof reference.knowledge_id === 'string' ? reference.knowledge_id : '',+ document: documentLabel(reference),+ chunk_index: typeof reference.chunk_index === 'number' ? reference.chunk_index : -1,+ content: clip(typeof reference.content === 'string' ? reference.content : '', config.maxChunkChars).text,+ })),+ }+ },+ })+ }++ return definitions+}++/** Storage order, so a reassembled document reads top to bottom. */+function orderByChunkIndex(left: ChunkRecord, right: ChunkRecord): number {+ const a = typeof left.chunk_index === 'number' ? left.chunk_index : 0+ const b = typeof right.chunk_index === 'number' ? right.chunk_index : 0+ return a - b+}diff --git a/packages/dsh-weknora/test/client.test.mjs b/packages/dsh-weknora/test/client.test.mjsnew file mode 100644index 000000000..1ba816c09--- /dev/null+++ b/packages/dsh-weknora/test/client.test.mjs@@ -0,0 +1,120 @@+import assert from 'node:assert/strict'+import { after, test } from 'node:test'++import { WeknoraApiError, WeknoraClient } from '../dist/client.js'+import { resolveConfig } from '../dist/config.js'+import { startMockWeknora } from './helpers/mock-weknora.mjs'++const never = new AbortController().signal++/** Start a mock backend and a client wired to it, closed after the test file. */+async function harness(overrides = {}, mockOptions = {}) {+ const mock = await startMockWeknora(mockOptions)+ after(() => mock.close())+ const config = resolveConfig({ baseUrl: mock.url, ...overrides })+ return { mock, client: new WeknoraClient(config), config }+}++test('lists knowledge bases and sends the API key header', async () => {+ const { mock, client } = await harness({ apiKey: 'secret-key' }, { apiKey: 'secret-key' })+ const bases = await client.listKnowledgeBases(never)+ assert.deepEqual(bases.map(base => base.id), ['kb-product', 'kb-ops'])+ assert.equal(mock.requests.at(-1).headers['x-api-key'], 'secret-key')+})++test('a rejected credential surfaces the status and the server reason', async () => {+ const { client } = await harness({ apiKey: 'wrong-key' }, { apiKey: 'right-key' })+ await assert.rejects(client.listKnowledgeBases(never), error => {+ assert.ok(error instanceof WeknoraApiError)+ assert.equal(error.status, 401)+ assert.match(error.message, /HTTP 401: invalid api key/)+ return true+ })+})++test('search posts the documented body and returns ranked hits', async () => {+ const { mock, client } = await harness()+ const results = await client.search(+ { query: '混合检索 的 阈值 是多少', knowledgeBaseIds: ['kb-product'], knowledgeIds: [] },+ never,+ )+ assert.ok(results.length > 0)+ assert.equal(mock.requests.at(-1).path, '/api/v1/knowledge-search')+ assert.deepEqual(mock.requests.at(-1).body.knowledge_base_ids, ['kb-product'])+ assert.ok(results[0].score >= results.at(-1).score)+})++test('resourceUrls=public is forwarded as a query parameter', async () => {+ const { mock, client } = await harness({ resourceUrls: 'public' })+ await client.listKnowledgeBases(never)+ assert.equal(mock.requests.at(-1).query.resource_urls, 'public')+})++test('chunk pages carry their pagination envelope', async () => {+ const { client } = await harness()+ const page = await client.listChunks({ knowledgeId: 'doc-retrieval-pipeline', page: 1, pageSize: 2 }, never)+ assert.equal(page.total, 3)+ assert.equal(page.chunks.length, 2)+ assert.equal(page.pageSize, 2)+})++test('ask creates a session, streams the answer, and collects citations', async () => {+ const { mock, client } = await harness()+ const sessionId = await client.createSession('dsh: 阈值', never)+ const answer = await client.ask(+ { sessionId, query: '默认的检索阈值是多少', knowledgeBaseIds: ['kb-product'], agentId: undefined, webSearch: false },+ never,+ )+ assert.equal(answer.sessionId, 'session-mock-1')+ assert.match(answer.answer, /vector_threshold|向量/)+ assert.ok(answer.references.length > 0)+ assert.deepEqual(answer.toolCalls, [])+ assert.equal(mock.requests.at(-1).path, `/api/v1/knowledge-chat/${sessionId}`)+ assert.equal(mock.requests.at(-1).body.channel, 'api')+})++test('an agent id routes to agent-chat and reports the server-side tools', async () => {+ const { mock, client } = await harness()+ const answer = await client.ask(+ { sessionId: 's1', query: '部署方式有哪些', knowledgeBaseIds: [], agentId: 'agent-9', webSearch: true },+ never,+ )+ assert.equal(mock.requests.at(-1).path, '/api/v1/agent-chat/s1')+ assert.equal(mock.requests.at(-1).body.agent_id, 'agent-9')+ assert.equal(mock.requests.at(-1).body.agent_enabled, true)+ assert.equal(mock.requests.at(-1).body.web_search_enabled, true)+ assert.deepEqual(answer.toolCalls, ['knowledge_search'])+})++test('a streamed error event becomes a failed call, not an empty answer', async () => {+ const { client } = await harness({}, { streamError: true })+ await assert.rejects(+ client.ask({ sessionId: 's1', query: 'x', knowledgeBaseIds: [], agentId: undefined, webSearch: false }, never),+ /streamed an error: model provider unavailable/,+ )+})++// A stream that stops before `complete` was cut short. Returning what arrived+// would present a truncated answer to the model as a whole one.+test('a stream that ends before completing becomes a failed call', async () => {+ const { client } = await harness({}, { streamTruncated: true })+ await assert.rejects(+ client.ask(+ { sessionId: 's1', query: '默认的检索阈值是多少', knowledgeBaseIds: ['kb-product'], agentId: undefined, webSearch: false },+ never,+ ),+ /ended before WeKnora completed the answer/,+ )+})++test('caller cancellation aborts an in-flight call', async () => {+ const { client } = await harness()+ const controller = new AbortController()+ controller.abort()+ await assert.rejects(client.listKnowledgeBases(controller.signal), /the call was cancelled/)+})++test('an unreachable backend reports a transport failure', async () => {+ const client = new WeknoraClient(resolveConfig({ baseUrl: 'http://127.0.0.1:1/api/v1', requestTimeoutMs: 1000 }))+ await assert.rejects(client.listKnowledgeBases(never), WeknoraApiError)+})diff --git a/packages/dsh-weknora/test/config.test.mjs b/packages/dsh-weknora/test/config.test.mjsnew file mode 100644index 000000000..c21488dc8--- /dev/null+++ b/packages/dsh-weknora/test/config.test.mjs@@ -0,0 +1,49 @@+import assert from 'node:assert/strict'+import { test } from 'node:test'++import { ConfigError, normalizeBaseUrl, resolveConfig } from '../dist/config.js'++test('base URLs are normalized to an API root', () => {+ assert.equal(normalizeBaseUrl('https://kb.example.com'), 'https://kb.example.com/api/v1')+ assert.equal(normalizeBaseUrl('https://kb.example.com/'), 'https://kb.example.com/api/v1')+ assert.equal(normalizeBaseUrl('https://kb.example.com/api/v1'), 'https://kb.example.com/api/v1')+ assert.equal(normalizeBaseUrl('https://kb.example.com/api/v2/'), 'https://kb.example.com/api/v2')+})++test('an empty config resolves to documented defaults', () => {+ const config = resolveConfig(undefined)+ assert.equal(config.baseUrl, 'http://localhost:8080/api/v1')+ assert.equal(config.maxResults, 8)+ assert.equal(config.toolPrefix, 'weknora')+ assert.equal(config.resourceUrls, 'handle')+ assert.deepEqual(config.knowledgeBaseIds, [])+ assert.deepEqual(config.tools, { listKnowledgeBases: true, search: true, readDocument: true, ask: true })+})++test('a bad row fails the load and names every violation', () => {+ assert.throws(+ () => resolveConfig({ baseUrl: 'not-a-url', maxResults: -1, resourceUrls: 'nope', toolPrefix: '9bad' }),+ error => {+ assert.ok(error instanceof ConfigError)+ assert.match(error.message, /baseUrl must be an absolute URL/)+ assert.match(error.message, /maxResults must be a positive number/)+ assert.match(error.message, /resourceUrls must be "handle" or "public"/)+ assert.match(error.message, /toolPrefix must match/)+ return true+ },+ )+})++test('disabling every tool is refused', () => {+ assert.throws(+ () => resolveConfig({ tools: { listKnowledgeBases: false, search: false, readDocument: false, ask: false } }),+ /at least one tool must stay enabled/,+ )+})++test('blank strings collapse to unset rather than empty headers', () => {+ const config = resolveConfig({ apiKey: ' ', tenantId: '', agentId: 'agent-7' })+ assert.equal(config.apiKey, undefined)+ assert.equal(config.tenantId, undefined)+ assert.equal(config.agentId, 'agent-7')+})diff --git a/packages/dsh-weknora/test/contract.test.mjs b/packages/dsh-weknora/test/contract.test.mjsnew file mode 100644index 000000000..c09c740fe--- /dev/null+++ b/packages/dsh-weknora/test/contract.test.mjs@@ -0,0 +1,136 @@+/**+ * The plugin side of the API contract: the calls this package makes must stay+ * exactly the ones recorded in test/fixtures/api-contract.json, which+ * contract/contract_test.go checks against WeKnora's real Go request and+ * response types. Change a request body and both sides tell you.+ */++import assert from 'node:assert/strict'+import { readFile } from 'node:fs/promises'+import { dirname, join } from 'node:path'+import { after, test } from 'node:test'+import { fileURLToPath } from 'node:url'++import { WeknoraClient } from '../dist/client.js'+import { resolveConfig } from '../dist/config.js'+import { createTools } from '../dist/tools.js'+import { startMockWeknora } from './helpers/mock-weknora.mjs'++const here = dirname(fileURLToPath(import.meta.url))+const fixture = JSON.parse(await readFile(join(here, 'fixtures', 'api-contract.json'), 'utf8'))+const exec = { signal: new AbortController().signal }++/** Replay every documented call against the mock and record what went out. */+async function replayCalls() {+ const mock = await startMockWeknora()+ after(() => mock.close())++ const ragConfig = resolveConfig({ baseUrl: mock.url, knowledgeBaseIds: ['kb-product'] })+ const ragTools = new Map(createTools(new WeknoraClient(ragConfig), ragConfig).map(tool => [tool.name, tool]))+ await ragTools.get('weknora_list_knowledge_bases').execute({}, exec)+ await ragTools.get('weknora_search').execute({ query: '默认的检索阈值是多少' }, exec)+ await ragTools.get('weknora_read_document').execute(+ { knowledge_id: 'doc-retrieval-pipeline', page: 1, page_size: 5 },+ exec,+ )+ await ragTools.get('weknora_ask').execute({ query: '默认的检索阈值是多少' }, exec)++ const agentConfig = resolveConfig({ baseUrl: mock.url, agentId: 'agent-42' })+ const agentAsk = createTools(new WeknoraClient(agentConfig), agentConfig)+ .find(tool => tool.name === 'weknora_ask')+ await agentAsk.execute({ query: '部署方式', session_id: 's1', web_search: true }, exec)++ return mock.requests.map(request => ({+ method: request.method,+ path: request.path,+ query: request.query,+ body: Object.keys(request.body).length === 0 ? null : request.body,+ }))+}++const observed = await replayCalls()++/** Order-insensitive key: a tool that fires two calls at once may land either way round. */+const callKey = call => `${call.method} ${call.path} ${JSON.stringify(call.query)} ${JSON.stringify(call.body)}`++test('the plugin makes exactly the documented WeKnora calls', () => {+ const expected = fixture.calls.map(call => ({+ method: call.method,+ path: call.path,+ query: call.query,+ body: call.body,+ }))+ assert.deepEqual(+ observed.map(callKey).sort(),+ expected.map(callKey).sort(),+ )+})++test('the fixture covers every endpoint the plugin touches', () => {+ const endpoints = new Set(observed.map(call => call.path.replace(/\/(session-mock-1|s1|doc-[\w-]+)$/, '/:id')))+ assert.deepEqual([...endpoints].sort(), [+ '/api/v1/agent-chat/:id',+ '/api/v1/chunks/:id',+ '/api/v1/knowledge-bases',+ '/api/v1/knowledge-search',+ '/api/v1/knowledge-chat/:id',+ '/api/v1/knowledge/search',+ '/api/v1/knowledge/:id',+ '/api/v1/sessions',+ ].sort())+})++test('every stream event the plugin handles is declared in the fixture', async () => {+ const mock = await startMockWeknora()+ after(() => mock.close())+ const config = resolveConfig({ baseUrl: mock.url, agentId: 'agent-42' })+ const client = new WeknoraClient(config)+ const answer = await client.ask(+ { sessionId: 's1', query: '默认的检索阈值是多少', knowledgeBaseIds: [], agentId: 'agent-42', webSearch: false },+ exec.signal,+ )+ // The mock streams tool_call, references, answer and complete; error is+ // covered in client.test.mjs. All four must be in the declared set.+ for (const event of ['answer', 'references', 'tool_call', 'complete', 'error']) {+ assert.ok(fixture.streamResponseTypes.includes(event), `${event} must be declared in the fixture`)+ }+ assert.notEqual(answer.answer, '')+ assert.notEqual(answer.references.length, 0)+ assert.deepEqual(answer.toolCalls, ['knowledge_search'])+})++test('the plugin only reads response fields the fixture declares', async () => {+ const mock = await startMockWeknora()+ after(() => mock.close())+ const config = resolveConfig({ baseUrl: mock.url })+ const client = new WeknoraClient(config)+ // A backend that serves nothing but the declared fields must still produce a+ // complete tool result, which is what "these are the fields we depend on" means.+ const declared = new Set(fixture.responseFieldsRead['types.SearchResult'])+ const results = await client.search({ query: '混合检索', knowledgeBaseIds: ['kb-product'], knowledgeIds: [] }, exec.signal)+ const trimmed = results.map(result => Object.fromEntries(+ Object.entries(result).filter(([key]) => declared.has(key)),+ ))+ const tools = createTools(new WeknoraClient(config), config)+ const search = tools.find(tool => tool.name === 'weknora_search')+ // Feed the trimmed shape back through the projection the tool uses.+ const projected = search.output.render({ query: '混合检索' }, {+ query: '混合检索',+ knowledge_base_ids: [],+ documents: [],+ count: trimmed.length,+ results: trimmed.map((result, index) => ({+ rank: index + 1,+ chunk_id: result.id ?? '',+ knowledge_id: result.knowledge_id ?? '',+ document: result.knowledge_title ?? result.knowledge_filename ?? '(untitled)',+ chunk_index: result.chunk_index ?? -1,+ score: result.score ?? 0,+ content: result.content ?? '',+ truncated: false,+ })),+ documents: [],+ })+ assert.match(projected[0].text, /knowledge_id: doc-/)+ assert.match(projected[0].text, /score \d\.\d{3}/)+})diff --git a/packages/dsh-weknora/test/e2e/fake-model.mjs b/packages/dsh-weknora/test/e2e/fake-model.mjsnew file mode 100644index 000000000..b736ea737--- /dev/null+++ b/packages/dsh-weknora/test/e2e/fake-model.mjs@@ -0,0 +1,141 @@+/**+ * A deterministic OpenAI-compatible model server for the end-to-end run. dsh's+ * `llm-pi-ai` adapter talks to it as an ordinary `openai-completions` gateway,+ * which lets the real harness agent loop drive real tool calls with no API key+ * and no nondeterminism.+ *+ * The scripted policy is: search the knowledge base, read the document a hit+ * points at, then answer using only what the tools returned. Every request is+ * recorded so the test can assert which tool schemas the model was offered.+ */++import { createServer } from 'node:http'++/** Emit one OpenAI streaming chunk. */+function chunk(response, model, delta, finishReason = null) {+ const payload = {+ id: 'chatcmpl-weknora-e2e',+ object: 'chat.completion.chunk',+ created: Math.floor(Date.now() / 1000),+ model,+ choices: [{ index: 0, delta, finish_reason: finishReason }],+ }+ response.write(`data: ${JSON.stringify(payload)}\n\n`)+}++function streamToolCall(response, model, name, args) {+ chunk(response, model, {+ role: 'assistant',+ content: null,+ tool_calls: [{ index: 0, id: `call_${name}`, type: 'function', function: { name, arguments: '' } }],+ })+ chunk(response, model, {+ tool_calls: [{ index: 0, function: { arguments: JSON.stringify(args) } }],+ })+ chunk(response, model, {}, 'tool_calls')+ response.write('data: [DONE]\n\n')+ response.end()+}++function streamText(response, model, text) {+ chunk(response, model, { role: 'assistant', content: '' })+ for (const piece of text.match(/.{1,40}/gs) ?? []) chunk(response, model, { content: piece })+ chunk(response, model, {}, 'stop')+ response.write('data: [DONE]\n\n')+ response.end()+}++/** The user's question, taken from the first user message in the request. */+function userQuestion(messages) {+ const first = messages.find(message => message.role === 'user')+ if (first === undefined) return ''+ return typeof first.content === 'string'+ ? first.content+ : (first.content ?? []).map(part => part.text ?? '').join(' ')+}++function toolMessages(messages) {+ return messages.filter(message => message.role === 'tool')+ .map(message => typeof message.content === 'string'+ ? message.content+ : (message.content ?? []).map(part => part.text ?? '').join('\n'))+}++/** Which of our tools the assistant already called, in order. */+function calledTools(messages) {+ return messages+ .filter(message => message.role === 'assistant' && Array.isArray(message.tool_calls))+ .flatMap(message => message.tool_calls.map(call => call.function?.name))+ .filter(name => typeof name === 'string')+}++/**+ * Start the fake model.+ * @param options.searchTool - tool name to call first.+ * @param options.readTool - tool name to call with a knowledge_id from the first result.+ * @returns the base URL (with `/v1`), the recorded requests, and a close function.+ */+export async function startFakeModel(options = {}) {+ const searchTool = options.searchTool ?? 'weknora_search'+ const readTool = options.readTool ?? 'weknora_read_document'+ const requests = []++ const server = createServer((request, response) => {+ const chunks = []+ request.on('data', part => chunks.push(part))+ request.on('end', () => {+ const url = new URL(request.url, 'http://fake-model.invalid')+ if (!url.pathname.endsWith('/chat/completions')) {+ response.writeHead(404, { 'Content-Type': 'application/json' })+ response.end(JSON.stringify({ error: { message: `no route for ${url.pathname}` } }))+ return+ }+ const body = JSON.parse(Buffer.concat(chunks).toString('utf8'))+ const messages = body.messages ?? []+ const offeredTools = (body.tools ?? []).map(tool => tool.function?.name).filter(Boolean)+ requests.push({+ model: body.model,+ offeredTools,+ roles: messages.map(message => message.role),+ toolResults: toolMessages(messages),+ })++ response.writeHead(200, {+ 'Content-Type': 'text/event-stream',+ 'Cache-Control': 'no-cache',+ 'Connection': 'keep-alive',+ })++ const already = calledTools(messages)+ const results = toolMessages(messages)++ if (!already.includes(searchTool)) {+ streamToolCall(response, body.model, searchTool, { query: userQuestion(messages) })+ return+ }++ if (!already.includes(readTool)) {+ const knowledgeId = /knowledge_id: (\S+)/.exec(results.join('\n'))?.[1]+ if (knowledgeId !== undefined) {+ streamToolCall(response, body.model, readTool, { knowledge_id: knowledgeId, page: 1, page_size: 5 })+ return+ }+ }++ // Answer strictly from what the tools returned, so the transcript proves+ // the retrieved bytes reached the model rather than a canned string.+ const grounding = results.join('\n').replace(/\s+/g, ' ').trim().slice(0, 400)+ streamText(response, body.model, `根据 WeKnora 知识库检索结果回答:${grounding}`)+ })+ })++ await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))+ const { port } = server.address()+ return {+ url: `http://127.0.0.1:${port}/v1`,+ requests,+ async close() {+ await new Promise(resolve => server.close(resolve))+ },+ }+}diff --git a/packages/dsh-weknora/test/e2e/run-in-dsh.mjs b/packages/dsh-weknora/test/e2e/run-in-dsh.mjsnew file mode 100644index 000000000..d77900aaf--- /dev/null+++ b/packages/dsh-weknora/test/e2e/run-in-dsh.mjs@@ -0,0 +1,270 @@+#!/usr/bin/env node+/**+ * End-to-end check inside a real DeepSeek Harness install: install this package+ * into a throwaway dsh profile with `dsh plugin add`, boot the headless profile+ * against a fake OpenAI-compatible model and a mock WeKnora backend, and assert+ * that the harness agent loop actually called the tools and answered from what+ * they returned.+ *+ * Three scenarios run, because all three are documented paths:+ * A. the bundle's shipped `cordis.patch.yml`, configured only by environment+ * variables — what a user gets straight after `dsh plugin add`.+ * B. a profile patch that overrides the row, including a renamed tool prefix,+ * which also proves configuration reaches the plugin.+ * C. a row with no knowledge base scope, where the plugin resolves the full+ * visible set itself — WeKnora refuses an unscoped search.+ *+ * Usage:+ * node test/e2e/run-in-dsh.mjs # installs dsh into a cache dir+ * DSH_BIN=/path/to/dsh node test/e2e/run-in-dsh.mjs+ * DSH_E2E_LOG=/tmp/transcript.log node test/e2e/run-in-dsh.mjs+ *+ * Environment:+ * DSH_PACKAGE_SPEC npm spec for the harness (default `@deepseek-ai/dsh@latest`)+ * DSH_INSTALL_DIR where to keep that install (default `<tmp>/dsh-e2e-install`)+ * DSH_E2E_KEEP_HOME keep the throwaway `DSH_HOME` for inspection+ */++import assert from 'node:assert/strict'+import { spawn } from 'node:child_process'+import { existsSync } from 'node:fs'+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'+import { tmpdir } from 'node:os'+import { dirname, join, resolve } from 'node:path'+import { fileURLToPath } from 'node:url'++import { startFakeModel } from './fake-model.mjs'+import { startMockWeknora } from '../helpers/mock-weknora.mjs'++const packageDir = resolve(dirname(fileURLToPath(import.meta.url)), '../..')+const installDir = process.env.DSH_INSTALL_DIR ?? join(tmpdir(), 'dsh-e2e-install')+const dshSpec = process.env.DSH_PACKAGE_SPEC ?? '@deepseek-ai/dsh@latest'+const API_KEY = 'e2e-api-key'+const QUESTION = 'WeKnora 的默认检索阈值是多少?请查知识库后回答。'+const transcript = []++function log(line) {+ transcript.push(line)+ process.stdout.write(`${line}\n`)+}++/** Run a command to completion, capturing both streams. */+function run(command, args, options = {}) {+ return new Promise((resolveRun, rejectRun) => {+ const child = spawn(command, args, {+ cwd: options.cwd ?? packageDir,+ env: { ...process.env, ...options.env },+ stdio: ['ignore', 'pipe', 'pipe'],+ })+ let stdout = ''+ let stderr = ''+ child.stdout.on('data', part => {+ stdout += part+ })+ child.stderr.on('data', part => {+ stderr += part+ })+ child.on('error', rejectRun)+ child.on('close', code => resolveRun({ code, stdout, stderr }))+ })+}++/** Resolve a dsh launcher, installing one from npm when none was supplied. */+async function resolveDsh() {+ if (process.env.DSH_BIN !== undefined) return process.env.DSH_BIN+ const binary = join(installDir, 'node_modules', '.bin', 'dsh')+ if (existsSync(binary)) {+ log(`# reusing the dsh install at ${installDir}`)+ return binary+ }+ log(`# installing ${dshSpec} into ${installDir} (first run only)`)+ await mkdir(installDir, { recursive: true })+ await writeFile(join(installDir, 'package.json'), JSON.stringify({ name: 'dsh-e2e-install', private: true }, null, 2))+ const install = await run('npm', ['install', '--no-audit', '--no-fund', dshSpec], { cwd: installDir })+ if (install.code !== 0) throw new Error(`npm install ${dshSpec} failed:\n${install.stderr}`)+ return binary+}++/** The two rows that make dsh talk to the fake model instead of DeepSeek. */+function modelPatchRows(modelUrl) {+ return [+ {+ id: 'agent-default-model',+ config: { provider: 'weknora-e2e', model: 'weknora-e2e-model' },+ },+ {+ id: 'llm-pi-ai',+ config: {+ providers: {+ 'weknora-e2e': {+ displayName: 'WeKnora e2e gateway',+ apiKeyEnv: 'WEKNORA_E2E_MODEL_KEY',+ api: 'openai-completions',+ baseURL: modelUrl,+ models: [{+ id: 'weknora-e2e-model',+ name: 'WeKnora e2e model',+ contextWindow: 65536,+ maxTokens: 4096,+ }],+ },+ },+ },+ },+ ]+}++/**+ * Boot the headless profile once and assert the whole path: the harness offered+ * the tools, the tools reached WeKnora, the retrieved passages reached the+ * model, and the printed answer is grounded in them.+ */+async function scenario(options) {+ const { label, dsh, home, env, patch, prefix, weknora, autoScope = false } = options+ const model = await startFakeModel({ searchTool: `${prefix}_search`, readTool: `${prefix}_read_document` })+ const requestsBefore = weknora.requests.length+ try {+ await writeFile(+ join(home, 'profiles', 'headless', 'cordis.patch.yml'),+ JSON.stringify([...patch, ...modelPatchRows(model.url)], null, 2),+ )++ const dump = await run(dsh, ['--profile', 'headless', '--dump-config'], { env })+ assert.equal(dump.code, 0, `--dump-config must succeed:\n${dump.stderr}`)+ assert.match(dump.stdout, /name: ["']?@wxg-prc-cpg\/dsh-weknora/, 'the composed tree must mount the plugin')++ log(`\n=== ${label} ===`)+ log(`$ dsh --profile headless "${QUESTION}"`)+ const boot = await run(dsh, ['--profile', 'headless', QUESTION], { env })+ log(`--- stdout ---\n${boot.stdout.trim()}`)+ if (boot.stderr.trim() !== '') log(`--- stderr ---\n${boot.stderr.trim()}`)+ assert.equal(boot.code, 0, 'the headless run must exit 0')++ const offered = (model.requests.at(0)?.offeredTools ?? []).filter(name => name.startsWith(`${prefix}_`))+ log(`# tools offered to the model: ${offered.join(', ')}`)+ for (const suffix of ['search', 'read_document', 'ask', 'list_knowledge_bases']) {+ assert.ok(offered.includes(`${prefix}_${suffix}`), `${prefix}_${suffix} must appear in the model's tool schemas`)+ }++ const calls = weknora.requests.slice(requestsBefore)+ const paths = calls.map(request => request.path)+ log(`# WeKnora received: ${paths.join(', ')}`)+ assert.ok(paths.includes('/api/v1/knowledge-search'), 'search must reach the retrieval endpoint')+ if (autoScope) {+ // WeKnora rejects an unscoped retrieval, so with nothing configured the+ // plugin has to resolve the full visible set itself — the model asked a+ // plain question and never named a knowledge base.+ assert.ok(+ paths.indexOf('/api/v1/knowledge-bases') >= 0+ && paths.indexOf('/api/v1/knowledge-bases') < paths.indexOf('/api/v1/knowledge-search'),+ 'the plugin must resolve the visible knowledge bases before retrieving',+ )+ const search = calls.find(request => request.path === '/api/v1/knowledge-search')+ assert.deepEqual(+ search.body.knowledge_base_ids,+ ['kb-product', 'kb-ops'],+ 'an unconfigured deployment must search every visible knowledge base',+ )+ }+ assert.ok(paths.some(path => path.startsWith('/api/v1/chunks/')), 'read_document must reach the chunk endpoint')+ assert.equal(+ weknora.requests.slice(requestsBefore).every(request => request.headers['x-api-key'] === API_KEY),+ true,+ 'every call must carry the configured API key',+ )++ const toolResults = model.requests.flatMap(request => request.toolResults).join('\n')+ assert.match(toolResults, /vector_threshold 是 0\.5/, 'the model must see the retrieved passage verbatim')+ assert.match(toolResults, /knowledge_id: doc-retrieval-pipeline/, 'search hits must carry a usable knowledge_id')+ assert.match(boot.stdout, /0\.5/, 'the printed answer must carry the retrieved threshold')++ log(`# PASS (${label}): ${prefix}_search and ${prefix}_read_document ran inside dsh against WeKnora, `+ + 'and the answer came from the retrieved passages.')+ } finally {+ await model.close()+ }+}++async function main() {+ if (!existsSync(join(packageDir, 'dist', 'index.js'))) {+ throw new Error('build the package first: npm run build')+ }++ const weknora = await startMockWeknora({ apiKey: API_KEY })+ const home = await mkdtemp(join(tmpdir(), 'dsh-weknora-home-'))+ const dsh = await resolveDsh()+ const env = {+ DSH_HOME: home,+ WEKNORA_E2E_MODEL_KEY: 'not-a-real-key',+ WEKNORA_BASE_URL: weknora.url,+ WEKNORA_API_KEY: API_KEY,+ WEKNORA_KNOWLEDGE_BASE_IDS: 'kb-product',+ }++ log(`# mock WeKnora ${weknora.url}`)+ log(`# DSH_HOME ${home}`)+ log(`# dsh launcher ${dsh}`)++ try {+ // Install this package into a fresh profile exactly as a user would.+ const install = await run(dsh, ['plugin', '--profile', 'headless', 'add', packageDir], { env })+ log(`\n$ dsh plugin --profile headless add ${packageDir}\n${install.stdout.trim()}\n${install.stderr.trim()}`)+ assert.equal(install.code, 0, 'dsh plugin add must succeed')++ const manifest = JSON.parse(await readFile(join(home, 'profiles', 'headless', 'package.json'), 'utf8'))+ log(`# profile bundles: ${JSON.stringify(manifest.dsh.profile.bundles)}`)+ assert.ok(+ manifest.dsh.profile.bundles.includes('@wxg-prc-cpg/dsh-weknora'),+ 'the bundle must join the profile layer list',+ )++ // A. The shipped bundle patch, configured only by environment variables.+ await scenario({ label: 'A · shipped bundle defaults from env', dsh, home, env, weknora, patch: [], prefix: 'weknora' })++ // B. A profile override, which also renames the tools.+ await scenario({+ label: 'B · profile override with a renamed tool prefix',+ dsh,+ home,+ env,+ weknora,+ prefix: 'kb',+ patch: [{+ id: 'weknora',+ config: {+ baseUrl: weknora.url,+ apiKey: API_KEY,+ knowledgeBaseIds: ['kb-product'],+ toolPrefix: 'kb',+ maxResults: 3,+ maxChunkChars: 400,+ },+ }],+ })++ // C. No configured scope at all, which is what the quickstart's optional+ // WEKNORA_KNOWLEDGE_BASE_IDS leaves behind.+ await scenario({+ label: 'C · no configured scope, resolved by the plugin',+ dsh,+ home,+ env,+ weknora,+ prefix: 'weknora',+ autoScope: true,+ patch: [{+ id: 'weknora',+ config: { baseUrl: weknora.url, apiKey: API_KEY },+ }],+ })++ log('\n# ALL SCENARIOS PASSED')+ } finally {+ await weknora.close()+ const logPath = process.env.DSH_E2E_LOG+ if (logPath !== undefined) await writeFile(logPath, `${transcript.join('\n')}\n`)+ if (process.env.DSH_E2E_KEEP_HOME === undefined) await rm(home, { recursive: true, force: true })+ }+}++await main()diff --git a/packages/dsh-weknora/test/fixtures/api-contract.json b/packages/dsh-weknora/test/fixtures/api-contract.jsonnew file mode 100644index 000000000..0b49193fd--- /dev/null+++ b/packages/dsh-weknora/test/fixtures/api-contract.json@@ -0,0 +1,119 @@+{+ "$comment": [+ "The exact WeKnora API calls this plugin makes, and the response fields it reads.",+ "test/contract.test.mjs asserts the plugin still emits these calls;",+ "contract/contract_test.go asserts the WeKnora server still accepts them and still",+ "serves those response fields, so a rename on either side fails CI instead of a user's agent."+ ],+ "calls": [+ {+ "tool": "weknora_list_knowledge_bases",+ "method": "GET",+ "path": "/api/v1/knowledge-bases",+ "query": {},+ "body": null,+ "goRequestType": null+ },+ {+ "tool": "weknora_search",+ "method": "POST",+ "path": "/api/v1/knowledge-search",+ "query": {},+ "body": {+ "query": "默认的检索阈值是多少",+ "knowledge_base_ids": ["kb-product"]+ },+ "goRequestType": "session.SearchKnowledgeRequest"+ },+ {+ "tool": "weknora_search",+ "method": "GET",+ "path": "/api/v1/knowledge/search",+ "query": { "keyword": "默认的检索阈值是多少", "limit": "8" },+ "body": null,+ "goRequestType": null+ },+ {+ "tool": "weknora_read_document",+ "method": "GET",+ "path": "/api/v1/chunks/doc-retrieval-pipeline",+ "query": { "page": "1", "page_size": "5" },+ "body": null,+ "goRequestType": "types.Pagination"+ },+ {+ "tool": "weknora_read_document",+ "method": "GET",+ "path": "/api/v1/knowledge/doc-retrieval-pipeline",+ "query": {},+ "body": null,+ "goRequestType": null+ },+ {+ "tool": "weknora_ask",+ "method": "POST",+ "path": "/api/v1/sessions",+ "query": {},+ "body": {+ "title": "dsh: 默认的检索阈值是多少"+ },+ "goRequestType": "session.CreateSessionRequest"+ },+ {+ "tool": "weknora_ask",+ "method": "POST",+ "path": "/api/v1/knowledge-chat/session-mock-1",+ "query": {},+ "body": {+ "query": "默认的检索阈值是多少",+ "channel": "api",+ "knowledge_base_ids": ["kb-product"]+ },+ "goRequestType": "session.CreateKnowledgeQARequest"+ },+ {+ "tool": "weknora_ask",+ "method": "POST",+ "path": "/api/v1/agent-chat/s1",+ "query": {},+ "body": {+ "query": "部署方式",+ "channel": "api",+ "agent_id": "agent-42",+ "agent_enabled": true,+ "web_search_enabled": true+ },+ "goRequestType": "session.CreateKnowledgeQARequest"+ }+ ],+ "responseFieldsRead": {+ "types.SearchResult": [+ "id",+ "content",+ "knowledge_id",+ "chunk_index",+ "knowledge_title",+ "knowledge_filename",+ "score"+ ],+ "types.Chunk": ["id", "content", "chunk_index", "knowledge_id"],+ "types.Knowledge": [+ "id",+ "title",+ "file_name",+ "description",+ "knowledge_base_id",+ "knowledge_base_name"+ ],+ "types.StreamResponse": [+ "response_type",+ "content",+ "knowledge_references",+ "session_id",+ "tool_calls"+ ],+ "types.LLMToolCall": ["function"],+ "types.FunctionCall": ["name"]+ },+ "streamResponseTypes": ["answer", "references", "tool_call", "error", "complete"]+}diff --git a/packages/dsh-weknora/test/helpers/json-schema.mjs b/packages/dsh-weknora/test/helpers/json-schema.mjsnew file mode 100644index 000000000..d1efb0148--- /dev/null+++ b/packages/dsh-weknora/test/helpers/json-schema.mjs@@ -0,0 +1,147 @@+/**+ * A validator for the JSON Schema subset the harness tool registry enforces+ * (see packages/core/tools/src/json-schema.ts in DeepSeek Harness). The tests+ * run every canonical value through it, so a tool whose body drifts from its+ * declared `output.schema` fails here rather than inside dsh at runtime.+ */++const SUPPORTED_KEYS = new Set([+ 'type', 'oneOf', 'properties', 'required', 'additionalProperties',+ 'items', 'enum', 'const', 'description', 'title', 'default', 'examples',+])++const TYPES = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'])++/** Reject a schema the harness would refuse at registration time. */+export function assertSupportedSchema(schema, path = '#') {+ const violations = []+ const walk = (node, at) => {+ if (typeof node !== 'object' || node === null || Array.isArray(node)) {+ violations.push(`${at}: schema node must be an object`)+ return+ }+ for (const key of Object.keys(node)) {+ if (!SUPPORTED_KEYS.has(key)) violations.push(`${at}: unsupported keyword "${key}"`)+ }+ if (node.type !== undefined && !TYPES.has(node.type)) violations.push(`${at}: unsupported type "${node.type}"`)+ for (const name of node.required ?? []) {+ if (node.properties?.[name] === undefined) {+ violations.push(`${at}: required property "${name}" is not declared in properties`)+ }+ }+ for (const [name, child] of Object.entries(node.properties ?? {})) walk(child, `${at}/${name}`)+ if (node.items !== undefined) walk(node.items, `${at}/items`)+ for (const [index, branch] of (node.oneOf ?? []).entries()) walk(branch, `${at}/oneOf/${index}`)+ }+ walk(schema, path)+ if (violations.length > 0) throw new Error(`unsupported JSON schema: ${violations.join('; ')}`)+}++/** Return every way `value` fails `schema`; an empty array means it validates. */+export function validate(schema, value, path = '#') {+ const violations = []+ const walk = (node, candidate, at) => {+ if (node.const !== undefined && candidate !== node.const) {+ violations.push(`${at}: expected const ${JSON.stringify(node.const)}`)+ return+ }+ if (node.enum !== undefined && !node.enum.includes(candidate)) {+ violations.push(`${at}: ${JSON.stringify(candidate)} is not one of ${JSON.stringify(node.enum)}`)+ return+ }+ if (node.oneOf !== undefined) {+ const matches = node.oneOf.filter(branch => validate(branch, candidate, at).length === 0)+ if (matches.length !== 1) violations.push(`${at}: expected exactly one oneOf branch to match, ${matches.length} did`)+ return+ }+ switch (node.type) {+ case undefined:+ return+ case 'object': {+ if (typeof candidate !== 'object' || candidate === null || Array.isArray(candidate)) {+ violations.push(`${at}: expected object, got ${describe(candidate)}`)+ return+ }+ for (const name of node.required ?? []) {+ if (!(name in candidate)) violations.push(`${at}: missing required property "${name}"`)+ }+ if (node.additionalProperties === false) {+ for (const name of Object.keys(candidate)) {+ if (node.properties?.[name] === undefined) violations.push(`${at}: undeclared property "${name}"`)+ }+ }+ for (const [name, child] of Object.entries(node.properties ?? {})) {+ if (name in candidate) walk(child, candidate[name], `${at}/${name}`)+ }+ return+ }+ case 'array': {+ if (!Array.isArray(candidate)) {+ violations.push(`${at}: expected array, got ${describe(candidate)}`)+ return+ }+ if (node.items !== undefined) {+ candidate.forEach((entry, index) => walk(node.items, entry, `${at}/${index}`))+ }+ return+ }+ case 'integer': {+ if (typeof candidate !== 'number' || !Number.isInteger(candidate)) {+ violations.push(`${at}: expected integer, got ${describe(candidate)}`)+ }+ return+ }+ case 'number': {+ if (typeof candidate !== 'number' || !Number.isFinite(candidate)) {+ violations.push(`${at}: expected finite number, got ${describe(candidate)}`)+ }+ return+ }+ case 'string': {+ if (typeof candidate !== 'string') violations.push(`${at}: expected string, got ${describe(candidate)}`)+ return+ }+ case 'boolean': {+ if (typeof candidate !== 'boolean') violations.push(`${at}: expected boolean, got ${describe(candidate)}`)+ return+ }+ case 'null': {+ if (candidate !== null) violations.push(`${at}: expected null, got ${describe(candidate)}`)+ return+ }+ default:+ violations.push(`${at}: unsupported type "${node.type}"`)+ }+ }+ walk(schema, value, path)+ return violations+}++/** Confirm the value is representable as lossless JSON, as the registry requires. */+export function assertLosslessJson(value, label) {+ const seen = new WeakSet()+ const walk = (candidate, at) => {+ if (candidate === null || typeof candidate === 'string' || typeof candidate === 'boolean') return+ if (typeof candidate === 'number') {+ if (!Number.isFinite(candidate)) throw new Error(`${label} ${at}: ${String(candidate)} is not lossless JSON`)+ return+ }+ if (typeof candidate !== 'object') throw new Error(`${label} ${at}: ${typeof candidate} is not lossless JSON`)+ if (seen.has(candidate)) throw new Error(`${label} ${at}: circular reference`)+ seen.add(candidate)+ if (Array.isArray(candidate)) {+ candidate.forEach((entry, index) => walk(entry, `${at}/${index}`))+ return+ }+ for (const [key, entry] of Object.entries(candidate)) {+ if (entry === undefined) throw new Error(`${label} ${at}/${key}: undefined is not lossless JSON`)+ walk(entry, `${at}/${key}`)+ }+ }+ walk(value, '#')+}++function describe(value) {+ if (value === null) return 'null'+ return Array.isArray(value) ? 'array' : typeof value+}diff --git a/packages/dsh-weknora/test/helpers/mock-weknora.mjs b/packages/dsh-weknora/test/helpers/mock-weknora.mjsnew file mode 100644index 000000000..fbc846031--- /dev/null+++ b/packages/dsh-weknora/test/helpers/mock-weknora.mjs@@ -0,0 +1,332 @@+/**+ * A stand-in WeKnora backend used by the unit tests and by the end-to-end run+ * inside dsh. It speaks the same routes, envelopes and SSE event types as the+ * real server (see internal/handler/session/qa.go and internal/types/chat.go),+ * so a test failure here means the plugin, not the fixture, drifted.+ */++import { createServer } from 'node:http'++const DOCUMENTS = [+ {+ knowledge_id: 'doc-retrieval-pipeline',+ knowledge_title: 'WeKnora 检索流程.md',+ knowledge_base_id: 'kb-product',+ // WeKnora stores the generated summary in `description`, not `summary`.+ description: '讲解 WeKnora 混合检索的召回、阈值与父子分块回溯。',+ chunks: [+ 'WeKnora 的混合检索先做向量召回,再做关键词召回,最后交给 rerank 模型统一排序。',+ '默认的 vector_threshold 是 0.5,keyword_threshold 是 0.3,可以在知识库配置里按库调整。',+ '父子分块开启后,命中子块会回溯父块,把更完整的上下文交给生成模型。',+ ],+ },+ {+ knowledge_id: 'doc-deployment',+ knowledge_title: 'WeKnora 部署手册.md',+ knowledge_base_id: 'kb-ops',+ description: '单机与 Kubernetes 部署方式,以及可选的向量库后端。',+ chunks: [+ 'WeKnora 支持 docker compose 单机部署,也提供 Helm chart 用于 Kubernetes。',+ '向量库可以选择 pgvector、Milvus、Qdrant、Weaviate、OpenSearch 等后端。',+ ],+ },+ {+ // Title and body share no wording on purpose: retrieving this document by+ // name is the only way to reach it, which is what the by-name search is for.+ knowledge_id: 'doc-release-checklist',+ knowledge_title: '灰度发布检查单.md',+ knowledge_base_id: 'kb-ops',+ description: '上线前的确认项与回滚准备。',+ chunks: [+ '上线前需确认监控告警、回滚预案与数据库变更脚本均已就绪,并由值班同学复核。',+ ],+ },+]++// Titled so a by-name query matches it while its text shares nothing with that+// query — the case passage retrieval alone cannot serve.+DOCUMENTS.push({+ knowledge_id: 'doc-release-checklist',+ knowledge_title: '灰度发布检查单.md',+ knowledge_base_id: 'kb-ops',+ description: '上线前的确认项与回滚方案。',+ chunks: ['本文列出上线前需要确认的配置项与回滚方案。'],+})++const KNOWLEDGE_BASES = [+ { id: 'kb-product', name: 'Product docs', description: 'WeKnora 产品与检索文档' },+ { id: 'kb-ops', name: 'Ops runbooks', description: '部署与运维手册' },+]++/**+ * Score a passage by character-bigram overlap. The real backend scores with+ * embeddings plus keyword match; bigrams are enough to make the fixture rank+ * plausibly for both Chinese and English queries.+ */+function scoreOf(query, content) {+ const normalized = query.replace(/[\s,,。??、!!::;;“”"']+/g, '')+ const shingles = new Set()+ for (let index = 0; index + 2 <= normalized.length; index += 1) {+ shingles.add(normalized.slice(index, index + 2))+ }+ if (shingles.size === 0) return 0+ const hits = [...shingles].filter(shingle => content.includes(shingle)).length+ return Math.min(0.99, 0.4 + (hits / shingles.size) * 0.5)+}++function searchResults(query, knowledgeBaseIds, knowledgeIds) {+ const documents = DOCUMENTS.filter(document =>+ (knowledgeIds.length === 0 || knowledgeIds.includes(document.knowledge_id))+ && (knowledgeBaseIds.length === 0 || knowledgeBaseIds.includes(document.knowledge_base_id)))+ return documents+ .flatMap(document => document.chunks.map((content, index) => ({+ id: `${document.knowledge_id}-chunk-${index}`,+ content,+ knowledge_id: document.knowledge_id,+ knowledge_title: document.knowledge_title,+ chunk_index: index,+ score: scoreOf(query, content),+ match_type: 2,+ start_at: 0,+ end_at: content.length,+ metadata: {},+ })))+ .filter(result => result.score > 0.4)+ .sort((left, right) => right.score - left.score)+}++/** The document shape the by-name search and `GET /knowledge/:id` both return. */+function documentRecord(document) {+ return {+ id: document.knowledge_id,+ title: document.knowledge_title,+ file_name: document.knowledge_title,+ file_type: 'md',+ description: document.description,+ knowledge_base_id: document.knowledge_base_id,+ knowledge_base_name: KNOWLEDGE_BASES.find(kb => kb.id === document.knowledge_base_id)?.name ?? '',+ parse_status: 'completed',+ summary_status: 'completed',+ }+}++/** Assemble the answer the fake RAG/agent pipeline streams back. */+function answerFor(query, results) {+ if (results.length === 0) return `没有检索到与「${query}」相关的内容。`+ const cited = results.slice(0, 2).map(result => result.content).join(' ')+ return `根据知识库内容:${cited}(问题:${query})`+}++/**+ * Start the mock backend.+ * @param options.apiKey - when set, requests must carry it as `X-API-Key`.+ * @param options.streamError - make the chat routes stream an `error` event.+ * @param options.streamTruncated - end the chat stream mid-answer, with no `complete`.+ * @returns the base URL, the recorded requests, and a close function.+ */+export async function startMockWeknora(options = {}) {+ const requests = []+ // Paths forced to fail, so a test can prove the plugin degrades rather than+ // breaks when a deployment does not serve one of the optional routes.+ const failures = new Map()+ const server = createServer((request, response) => {+ const url = new URL(request.url, 'http://mock.invalid')+ const chunks = []+ request.on('data', chunk => chunks.push(chunk))+ request.on('end', () => {+ const rawBody = Buffer.concat(chunks).toString('utf8')+ let body = {}+ if (rawBody !== '') {+ try {+ body = JSON.parse(rawBody)+ } catch {+ body = { _unparsed: rawBody }+ }+ }+ requests.push({+ method: request.method,+ path: url.pathname,+ query: Object.fromEntries(url.searchParams),+ headers: request.headers,+ body,+ })++ const json = (status, payload) => {+ response.writeHead(status, { 'Content-Type': 'application/json' })+ response.end(JSON.stringify(payload))+ }++ if (options.apiKey !== undefined && request.headers['x-api-key'] !== options.apiKey) {+ json(401, { success: false, error: { message: 'invalid api key' } })+ return+ }++ const forced = failures.get(url.pathname)+ if (forced !== undefined) {+ json(forced, { success: false, error: { message: `forced failure for ${url.pathname}` } })+ return+ }++ if (request.method === 'GET' && url.pathname === '/api/v1/knowledge-bases') {+ json(200, { success: true, data: KNOWLEDGE_BASES })+ return+ }++ // By-name document search. Spans every knowledge base and takes no+ // scope, matching the real /knowledge/search route.+ if (request.method === 'GET' && url.pathname === '/api/v1/knowledge/search') {+ const keyword = (url.searchParams.get('keyword') ?? url.searchParams.get('query') ?? '').trim()+ if (keyword === '') {+ json(400, { success: false, error: { message: 'missing search keyword: pass ?keyword=... or ?query=...' } })+ return+ }+ const limit = Number(url.searchParams.get('limit') ?? '20')+ json(200, {+ success: true,+ data: DOCUMENTS+ .filter(document => document.knowledge_title.toLowerCase().includes(keyword.toLowerCase()))+ .slice(0, limit)+ .map(document => documentRecord(document)),+ })+ return+ }++ if (request.method === 'GET' && url.pathname.startsWith('/api/v1/knowledge/')) {+ const knowledgeId = decodeURIComponent(url.pathname.slice('/api/v1/knowledge/'.length))+ const document = DOCUMENTS.find(entry => entry.knowledge_id === knowledgeId)+ if (document === undefined) {+ json(404, { success: false, error: { message: 'knowledge not found' } })+ return+ }+ json(200, { success: true, data: documentRecord(document) })+ return+ }++ if (request.method === 'POST' && url.pathname === '/api/v1/knowledge-search') {+ if (typeof body.query !== 'string' || body.query === '') {+ json(400, { success: false, error: { message: 'Query content cannot be empty' } })+ return+ }+ // Mirror the real handler, which refuses an unscoped retrieval+ // (internal/handler/session/qa.go). Answering one here would let the+ // plugin ship a call every deployment rejects.+ if ((body.knowledge_base_ids ?? []).length === 0+ && (body.knowledge_ids ?? []).length === 0+ && (body.tag_ids ?? []).length === 0) {+ json(400, {+ success: false,+ error: {+ message: 'At least one knowledge_base_id, knowledge_base_ids, knowledge_ids, or scoped tag must be provided',+ },+ })+ return+ }+ json(200, {+ success: true,+ data: searchResults(body.query, body.knowledge_base_ids ?? [], body.knowledge_ids ?? []),+ })+ return+ }++ if (request.method === 'GET' && url.pathname.startsWith('/api/v1/chunks/')) {+ const knowledgeId = decodeURIComponent(url.pathname.slice('/api/v1/chunks/'.length))+ const document = DOCUMENTS.find(entry => entry.knowledge_id === knowledgeId)+ if (document === undefined) {+ json(404, { success: false, error: { message: 'knowledge not found' } })+ return+ }+ const page = Number(url.searchParams.get('page') ?? '1')+ const pageSize = Number(url.searchParams.get('page_size') ?? '10')+ const start = (page - 1) * pageSize+ json(200, {+ success: true,+ data: document.chunks.slice(start, start + pageSize).map((content, index) => ({+ id: `${knowledgeId}-chunk-${start + index}`,+ knowledge_id: knowledgeId,+ knowledge_base_id: 'kb-product',+ content,+ chunk_index: start + index,+ is_enabled: true,+ })),+ total: document.chunks.length,+ page,+ page_size: pageSize,+ })+ return+ }++ if (request.method === 'POST' && url.pathname === '/api/v1/sessions') {+ json(201, { success: true, data: { id: 'session-mock-1', title: body.title ?? '' } })+ return+ }++ const chatMatch = /^\/api\/v1\/(knowledge-chat|agent-chat)\/(.+)$/.exec(url.pathname)+ if (request.method === 'POST' && chatMatch !== null) {+ const [, route, sessionId] = chatMatch+ response.writeHead(200, {+ 'Content-Type': 'text/event-stream',+ 'Cache-Control': 'no-cache',+ 'Connection': 'keep-alive',+ })+ const send = payload => response.write(`event:message\ndata:${JSON.stringify(payload)}\n\n`)+ if (options.streamError === true) {+ send({ id: 'e1', response_type: 'error', content: 'model provider unavailable', done: true })+ response.end()+ return+ }+ // The RAG route retrieves only what the request scopes: a session holds+ // no knowledge base of its own (CreateSessionRequest carries none), so+ // WeKnora has no default to fall back on and answers from nothing.+ // Retrieving here anyway would hide an unscoped ask from the tests. The+ // agent route does have a server-side default, its KBSelectionMode.+ const scoped = (body.knowledge_base_ids ?? []).length > 0 || (body.knowledge_ids ?? []).length > 0+ const results = route === 'agent-chat' || scoped+ ? searchResults(body.query ?? '', body.knowledge_base_ids ?? [], [])+ : []+ if (route === 'agent-chat') {+ send({+ id: 't1',+ response_type: 'tool_call',+ content: '',+ done: false,+ session_id: sessionId,+ tool_calls: [{ id: 'call-1', function: { name: 'knowledge_search', arguments: '{}' } }],+ })+ }+ send({ id: 'r1', response_type: 'references', content: '', done: false, knowledge_references: results })+ const pieces = answerFor(body.query ?? '', results).match(/.{1,24}/gs) ?? []+ // A stream cut off mid-answer, which is what a dropped connection or a+ // killed backend looks like: answer deltas but no `complete`.+ if (options.streamTruncated === true) {+ send({ id: 'a1', response_type: 'answer', content: pieces[0] ?? '', done: false, session_id: sessionId })+ response.end()+ return+ }+ for (const piece of pieces) {+ send({ id: 'a1', response_type: 'answer', content: piece, done: false, session_id: sessionId })+ }+ send({ id: 'c1', response_type: 'complete', content: '', done: true, session_id: sessionId })+ response.end()+ return+ }++ json(404, { success: false, error: { message: `no route for ${request.method} ${url.pathname}` } })+ })+ })++ await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))+ const { port } = server.address()+ return {+ url: `http://127.0.0.1:${port}/api/v1`,+ requests,+ /** Force `path` to answer `status` from now on. */+ fail(path, status) {+ failures.set(path, status)+ },+ async close() {+ await new Promise(resolve => server.close(resolve))+ },+ }+}++export { DOCUMENTS, KNOWLEDGE_BASES }diff --git a/packages/dsh-weknora/test/tools.test.mjs b/packages/dsh-weknora/test/tools.test.mjsnew file mode 100644index 000000000..c36f23bb2--- /dev/null+++ b/packages/dsh-weknora/test/tools.test.mjs@@ -0,0 +1,338 @@+import assert from 'node:assert/strict'+import { after, test } from 'node:test'++import { WeknoraClient } from '../dist/client.js'+import { resolveConfig } from '../dist/config.js'+import { apply } from '../dist/index.js'+import { createTools } from '../dist/tools.js'+import { assertLosslessJson, assertSupportedSchema, validate } from './helpers/json-schema.mjs'+import { startMockWeknora } from './helpers/mock-weknora.mjs'++const never = new AbortController().signal+const exec = { signal: never }++/** Build the tools against a live mock backend. */+async function toolset(overrides = {}) {+ const mock = await startMockWeknora()+ after(() => mock.close())+ const config = resolveConfig({ baseUrl: mock.url, ...overrides })+ const tools = createTools(new WeknoraClient(config), config)+ return { mock, config, byName: new Map(tools.map(tool => [tool.name, tool])), tools }+}++/** Run a tool the way the registry does: execute, then validate and render. */+async function call(tool, args) {+ const value = await tool.execute(args, exec)+ assertLosslessJson(value, tool.name)+ const violations = validate(tool.output.schema, value)+ assert.deepEqual(violations, [], `${tool.name} returned a value its output schema rejects`)+ const content = tool.output.render(args, value)+ assert.ok(Array.isArray(content) && content.length > 0 && content[0].type === 'text')+ return { value, text: content.map(block => block.text).join('\n') }+}++test('every declared schema stays inside the supported subset', async () => {+ const { tools } = await toolset()+ for (const tool of tools) {+ assertSupportedSchema(tool.parameters, `${tool.name}/parameters`)+ assertSupportedSchema(tool.output.schema, `${tool.name}/output`)+ assert.match(tool.name, /^[a-z][a-z0-9_]*$/)+ assert.ok(tool.description.length > 40, `${tool.name} needs a description the model can act on`)+ }+})++test('the default composition registers exactly the four documented tools', async () => {+ const { tools } = await toolset()+ assert.deepEqual(tools.map(tool => tool.name).sort(), [+ 'weknora_ask',+ 'weknora_list_knowledge_bases',+ 'weknora_read_document',+ 'weknora_search',+ ])+})++test('list_knowledge_bases renders ids the model can pass back', async () => {+ const { byName } = await toolset()+ const { value, text } = await call(byName.get('weknora_list_knowledge_bases'), {})+ assert.equal(value.count, 2)+ assert.match(text, /Product docs \(id: kb-product\)/)+})++test('search returns ranked passages carrying their knowledge_id', async () => {+ const { byName } = await toolset({ knowledgeBaseIds: ['kb-product'] })+ const { value, text } = await call(byName.get('weknora_search'), { query: '默认的检索阈值是多少' })+ assert.ok(value.count > 0)+ assert.equal(value.results[0].rank, 1)+ assert.ok(value.results[0].knowledge_id.startsWith('doc-'))+ assert.match(text, /passage\(s\) for "默认的检索阈值是多少"/)+ assert.match(text, /knowledge_id: doc-retrieval-pipeline/)+})++test('search respects max_results and the configured ceiling', async () => {+ const { byName } = await toolset({ maxResults: 2, knowledgeBaseIds: ['kb-product'] })+ const wide = await call(byName.get('weknora_search'), { query: '检索 部署 向量 阈值' })+ assert.ok(wide.value.count <= 2)+ const narrow = await call(byName.get('weknora_search'), { query: '检索 部署 向量 阈值', max_results: 1 })+ assert.equal(narrow.value.count, 1)+})++test('search falls back to the configured knowledge base scope', async () => {+ const { byName, mock } = await toolset({ knowledgeBaseIds: ['kb-ops'] })+ await call(byName.get('weknora_search'), { query: '部署 方式' })+ assert.deepEqual(mock.requests.at(-1).body.knowledge_base_ids, ['kb-ops'])+})++test('an empty result set tells the model what to try next', async () => {+ const { byName } = await toolset({ knowledgeBaseIds: ['kb-product'] })+ const { value, text } = await call(byName.get('weknora_search'), { query: '量子纠缠咖啡机保修期' })+ assert.equal(value.count, 0)+ assert.match(text, /Nothing in WeKnora matched/)+})++test('search rejects a missing query before touching the network', async () => {+ const { byName } = await toolset()+ await assert.rejects(byName.get('weknora_search').execute({}, exec), /"query" is required/)+})++// WeKnora answers 400 when a retrieval names no knowledge base, document or+// tag. Rather than make the model choose a scope it has no basis to choose,+// an unconfigured deployment searches everything the credential can see.+test('search spans every visible knowledge base when none is configured', async () => {+ const { byName, mock } = await toolset()+ const { value } = await call(byName.get('weknora_search'), { query: '默认的检索阈值是多少' })+ assert.deepEqual(value.knowledge_base_ids, ['kb-product', 'kb-ops'])+ const retrieval = mock.requests.find(request => request.path === '/api/v1/knowledge-search')+ assert.deepEqual(retrieval.body.knowledge_base_ids, ['kb-product', 'kb-ops'])+ assert.match(byName.get('weknora_search').description, /every knowledge base this credential can see/)+})++// A deployment can hold dozens of knowledge bases; spelling every id out on+// every search would cost more context than the passages themselves.+test('a wide scope is named by count rather than spelled out', async () => {+ const { byName } = await toolset({ knowledgeBaseIds: ['kb-a', 'kb-b', 'kb-c', 'kb-d'] })+ const { value, text } = await call(byName.get('weknora_search'), { query: '默认的检索阈值是多少' })+ assert.match(text, /searched: 4 knowledge bases/)+ assert.doesNotMatch(text, /kb-a/)+ assert.deepEqual(value.knowledge_base_ids, ['kb-a', 'kb-b', 'kb-c', 'kb-d'], 'the ids stay in the canonical value')+})++test('the resolved full scope is fetched once and reused', async () => {+ const { byName, mock } = await toolset()+ await call(byName.get('weknora_search'), { query: '混合检索 向量' })+ await call(byName.get('weknora_search'), { query: '部署 方式' })+ const listings = mock.requests.filter(request => request.path === '/api/v1/knowledge-bases')+ assert.equal(listings.length, 1, 'resolving the scope must not re-list on every search')+})++test('knowledge_ids alone is a scope WeKnora accepts', async () => {+ const { byName, mock } = await toolset()+ await call(byName.get('weknora_search'), {+ query: '默认的检索阈值是多少',+ knowledge_ids: ['doc-retrieval-pipeline'],+ })+ const retrieval = mock.requests.find(request => request.path === '/api/v1/knowledge-search')+ assert.deepEqual(retrieval.body.knowledge_ids, ['doc-retrieval-pipeline'])+ assert.equal(retrieval.body.knowledge_base_ids, undefined, 'a document-scoped call must not widen to every base')+})++test('a configured default scope is used verbatim', async () => {+ const { byName, mock } = await toolset({ knowledgeBaseIds: ['kb-product'] })+ await call(byName.get('weknora_search'), { query: '默认的检索阈值是多少' })+ assert.equal(mock.requests.some(request => request.path === '/api/v1/knowledge-bases'), false)+ assert.match(byName.get('weknora_search').description, /Searches knowledge base\(s\) kb-product/)+})++// A document nobody quotes is still the document the user asked for by name,+// which is exactly what passage retrieval on its own cannot find.+test('a query naming a document finds it even with no passage match', async () => {+ const { byName } = await toolset({ knowledgeBaseIds: ['kb-ops'] })+ const { value, text } = await call(byName.get('weknora_search'), { query: '灰度发布检查单' })+ assert.equal(value.count, 0)+ assert.deepEqual(value.documents.map(document => document.knowledge_id), ['doc-release-checklist'])+ assert.match(text, /No passage matched "灰度发布检查单", but its name matches document/)+ assert.match(text, /knowledge_id: doc-release-checklist · in Ops runbooks/)+})++test('by-name matches stay inside the scope the call asked for', async () => {+ const { byName } = await toolset({ knowledgeBaseIds: ['kb-product'] })+ const { value } = await call(byName.get('weknora_search'), { query: '灰度发布检查单' })+ assert.deepEqual(value.documents, [], 'a document in kb-ops must not surface in a kb-product search')+})++test('a passage hit is not repeated in the by-name section', async () => {+ const { byName } = await toolset({ knowledgeBaseIds: ['kb-product', 'kb-ops'] })+ const { value } = await call(byName.get('weknora_search'), { query: 'WeKnora 检索流程' })+ const passages = new Set(value.results.map(hit => hit.knowledge_id))+ assert.equal(value.documents.some(document => passages.has(document.knowledge_id)), false)+})++test('long passages are clipped and marked truncated', async () => {+ const { byName } = await toolset({ maxChunkChars: 20, knowledgeBaseIds: ['kb-product'] })+ const { value, text } = await call(byName.get('weknora_search'), { query: '混合检索 向量 关键词' })+ assert.ok(value.results[0].truncated)+ assert.ok(value.results[0].content.length <= 21)+ assert.match(text, /passage truncated/)+})++test('read_document reassembles passages in order and reports paging', async () => {+ const { byName } = await toolset({ maxChunkChars: 4000 })+ const first = await call(byName.get('weknora_read_document'), {+ knowledge_id: 'doc-retrieval-pipeline',+ page: 1,+ page_size: 2,+ })+ assert.equal(first.value.total_chunks, 3)+ assert.equal(first.value.returned_chunks, 2)+ assert.equal(first.value.has_more, true)+ assert.match(first.text, /request page 2/)+ const second = await call(byName.get('weknora_read_document'), {+ knowledge_id: 'doc-retrieval-pipeline',+ page: 2,+ page_size: 2,+ })+ assert.equal(second.value.has_more, false)+})++// A long document costs many pages to identify from its passages alone, so+// page 1 carries the title and WeKnora's generated summary.+test('read_document leads with the document title and summary', async () => {+ const { byName } = await toolset()+ const { value, text } = await call(byName.get('weknora_read_document'), {+ knowledge_id: 'doc-retrieval-pipeline',+ page: 1,+ page_size: 2,+ })+ assert.equal(value.title, 'WeKnora 检索流程.md')+ assert.match(value.summary, /混合检索/)+ assert.match(text, /Document WeKnora 检索流程\.md \(doc-retrieval-pipeline\)/)+ assert.match(text, /Summary: /)+})++test('read_document still returns text when the metadata call fails', async () => {+ const { byName, mock } = await toolset()+ mock.fail('/api/v1/knowledge/doc-retrieval-pipeline', 500)+ const { value } = await call(byName.get('weknora_read_document'), { knowledge_id: 'doc-retrieval-pipeline' })+ assert.equal(value.title, '')+ assert.equal(value.summary, '')+ assert.ok(value.content.length > 0, 'losing the metadata must not cost the model the document')+})++test('read_document leads with the title and summary, and only on page 1', async () => {+ const { byName, mock } = await toolset({ maxChunkChars: 4000 })+ const first = await call(byName.get('weknora_read_document'), {+ knowledge_id: 'doc-retrieval-pipeline',+ page: 1,+ page_size: 2,+ })+ assert.equal(first.value.title, 'WeKnora 检索流程.md')+ assert.match(first.text, /^Document WeKnora 检索流程\.md \(doc-retrieval-pipeline\)/)+ assert.match(first.text, /Summary: 讲解 WeKnora 混合检索/)++ const before = mock.requests.length+ const second = await call(byName.get('weknora_read_document'), {+ knowledge_id: 'doc-retrieval-pipeline',+ page: 2,+ page_size: 2,+ })+ assert.equal(second.value.summary, '')+ assert.doesNotMatch(second.text, /Summary:/)+ assert.equal(+ mock.requests.slice(before).some(request => request.path === '/api/v1/knowledge/doc-retrieval-pipeline'),+ false,+ 'a later page must not re-fetch metadata the model already has',+ )+})++test('read_document surfaces a backend 404 as a failed call', async () => {+ const { byName } = await toolset()+ await assert.rejects(+ byName.get('weknora_read_document').execute({ knowledge_id: 'missing-doc' }, exec),+ /HTTP 404/,+ )+})++test('ask returns the composed answer, citations and a resumable session', async () => {+ const { byName, mock } = await toolset()+ const { value, text } = await call(byName.get('weknora_ask'), { query: '默认的检索阈值是多少' })+ assert.equal(value.pipeline, 'rag')+ assert.equal(value.session_id, 'session-mock-1')+ assert.ok(value.references.length > 0)+ assert.match(text, /Citations:/)+ assert.match(text, /pass session_id to ask a follow-up/)+ assert.equal(mock.requests.some(request => request.path === '/api/v1/sessions'), true)+})++test('ask reuses a given session instead of creating one', async () => {+ const { byName, mock } = await toolset()+ await call(byName.get('weknora_ask'), { query: '部署方式', session_id: 'session-existing' })+ assert.equal(mock.requests.some(request => request.path === '/api/v1/sessions'), false)+ assert.equal(mock.requests.at(-1).path, '/api/v1/knowledge-chat/session-existing')+})++// The RAG pipeline retrieves only what the request scopes, so an unconfigured+// deployment must resolve the visible set for ask exactly as it does for search.+// Otherwise the quickstart's optional WEKNORA_KNOWLEDGE_BASE_IDS leaves ask+// answering from nothing while search works.+test('ask resolves its own scope when none is configured', async () => {+ const { byName, mock } = await toolset()+ const { value, text } = await call(byName.get('weknora_ask'), { query: '默认的检索阈值是多少' })+ const chat = mock.requests.find(request => request.path.startsWith('/api/v1/knowledge-chat/'))+ assert.deepEqual(chat.body.knowledge_base_ids, ['kb-product', 'kb-ops'])+ assert.ok(value.references.length > 0, 'an unconfigured ask must still retrieve')+ assert.doesNotMatch(text, /没有检索到/)+})++test('ask reuses the scope search already resolved', async () => {+ const { byName, mock } = await toolset()+ await call(byName.get('weknora_search'), { query: '混合检索 向量' })+ await call(byName.get('weknora_ask'), { query: '默认的检索阈值是多少' })+ const listings = mock.requests.filter(request => request.path === '/api/v1/knowledge-bases')+ assert.equal(listings.length, 1, 'search and ask must share the resolved scope')+})++test('a configured scope reaches ask without a listing call', async () => {+ const { byName, mock } = await toolset({ knowledgeBaseIds: ['kb-product'] })+ await call(byName.get('weknora_ask'), { query: '默认的检索阈值是多少' })+ assert.equal(mock.requests.some(request => request.path === '/api/v1/knowledge-bases'), false)+ const chat = mock.requests.find(request => request.path.startsWith('/api/v1/knowledge-chat/'))+ assert.deepEqual(chat.body.knowledge_base_ids, ['kb-product'])+})++// A custom agent resolves its scope server-side from its KBSelectionMode, and+// ids sent from here would override that as an explicit @mention.+test('an agent-pipeline ask leaves the scope to the server', async () => {+ const { byName, mock } = await toolset({ agentId: 'agent-42' })+ await call(byName.get('weknora_ask'), { query: '部署方式有哪些' })+ assert.equal(mock.requests.some(request => request.path === '/api/v1/knowledge-bases'), false)+ const chat = mock.requests.find(request => request.path.startsWith('/api/v1/agent-chat/'))+ assert.equal(chat.body.knowledge_base_ids, undefined)+})++test('a configured agent id switches ask to the agent pipeline', async () => {+ const { byName } = await toolset({ agentId: 'agent-42' })+ const { value, text } = await call(byName.get('weknora_ask'), { query: '部署方式有哪些' })+ assert.equal(value.pipeline, 'agent')+ assert.deepEqual(value.tool_calls, ['knowledge_search'])+ assert.match(text, /WeKnora tools used: knowledge_search/)+})++test('apply registers into ctx.tools and honours the prefix and toggles', () => {+ const registered = []+ const disposers = []+ const ctx = {+ tools: {+ register(definition) {+ registered.push(definition.name)+ const disposer = () => disposers.push(definition.name)+ return disposer+ },+ },+ }+ apply(ctx, { baseUrl: 'https://kb.example.com', toolPrefix: 'kb', tools: { ask: false, readDocument: false } })+ assert.deepEqual(registered.sort(), ['kb_list_knowledge_bases', 'kb_search'])+})++test('apply fails the plugin load on an invalid row', () => {+ const ctx = { tools: { register: () => () => undefined } }+ assert.throws(() => apply(ctx, { baseUrl: 'ftp://kb.example.com' }), /dsh-weknora configuration is invalid/)+})diff --git a/packages/dsh-weknora/tsconfig.build.json b/packages/dsh-weknora/tsconfig.build.jsonnew file mode 100644index 000000000..a0bfcab3e--- /dev/null+++ b/packages/dsh-weknora/tsconfig.build.json@@ -0,0 +1,7 @@+{+ "extends": "./tsconfig.json",+ "compilerOptions": {+ "outDir": "./dist",+ "rootDir": "./src"+ }+}diff --git a/packages/dsh-weknora/tsconfig.json b/packages/dsh-weknora/tsconfig.jsonnew file mode 100644index 000000000..989ac8ae2--- /dev/null+++ b/packages/dsh-weknora/tsconfig.json@@ -0,0 +1,21 @@+{+ "compilerOptions": {+ "target": "ES2023",+ "lib": ["ES2023"],+ "module": "NodeNext",+ "moduleResolution": "NodeNext",+ "types": ["node"],+ "strict": true,+ "exactOptionalPropertyTypes": true,+ "noUncheckedIndexedAccess": true,+ "noImplicitOverride": true,+ "verbatimModuleSyntax": true,+ "isolatedModules": true,+ "allowImportingTsExtensions": true,+ "rewriteRelativeImportExtensions": true,+ "declaration": true,+ "sourceMap": true,+ "skipLibCheck": true+ },+ "include": ["src/**/*.ts"]+}