dsh-plugin-dev-kb 1.0.0

package/kb/meta/site-pages.txt

@@ -0,0 +1,168 @@
+develop_basic_config.md
+develop_basic_index.md
+develop_basic_publish.md
+develop_basic_tool.md
+develop_cordis-tutorial_01-first-plugin.md
+develop_cordis-tutorial_02-lifecycle-and-effects.md
+develop_cordis-tutorial_03-services.md
+develop_cordis-tutorial_04-events.md
+develop_cordis-tutorial_05-config.md
+develop_cordis-tutorial_06-composition-and-hmr.md
+develop_cordis-tutorial_07-into-the-harness.md
+develop_cordis-tutorial_index.md
+develop_framework_events.md
+develop_framework_index.md
+develop_framework_service.md
+develop_practice_index.md
+develop_practice_llm-adapter.md
+en_develop_basic_config.md
+en_develop_basic_index.md
+en_develop_basic_publish.md
+en_develop_basic_tool.md
+en_develop_cordis-tutorial_01-first-plugin.md
+en_develop_cordis-tutorial_02-lifecycle-and-effects.md
+en_develop_cordis-tutorial_03-services.md
+en_develop_cordis-tutorial_04-events.md
+en_develop_cordis-tutorial_05-config.md
+en_develop_cordis-tutorial_06-composition-and-hmr.md
+en_develop_cordis-tutorial_07-into-the-harness.md
+en_develop_cordis-tutorial_index.md
+en_develop_framework_events.md
+en_develop_framework_index.md
+en_develop_framework_service.md
+en_develop_practice_index.md
+en_develop_practice_llm-adapter.md
+en_guide_providers.md
+en_guide_python-sdk.md
+en_guide_quickstart.md
+en_index.md
+en_reference_agent-lifecycle.md
+en_reference_capability-seams.md
+en_reference_config-catalog.md
+en_reference_cookbook_adding-a-conversation-node.md
+en_reference_cookbook_adding-an-llm-adapter.md
+en_reference_cookbook_adding-a-package.md
+en_reference_cookbook_adding-a-settings-card.md
+en_reference_cookbook_adding-a-tool.md
+en_reference_cookbook_extension-cookbook.md
+en_reference_cordis-api_context.md
+en_reference_cordis-api_events.md
+en_reference_cordis-api_fiber.md
+en_reference_cordis-api_inherited.md
+en_reference_cordis-api_registry.md
+en_reference_cordis-api_service.md
+en_reference_cordis-primer.md
+en_reference_index.md
+en_reference_persistence-catalog.md
+en_reference_subsystems_approval.md
+en_reference_subsystems_client-modules.md
+en_reference_subsystems_code-runtime.md
+en_reference_subsystems_commands.md
+en_reference_subsystems_compaction.md
+en_reference_subsystems_core.md
+en_reference_subsystems_credentials.md
+en_reference_subsystems_filesystem.md
+en_reference_subsystems_goal.md
+en_reference_subsystems_index.md
+en_reference_subsystems_invariants.md
+en_reference_subsystems_jobs.md
+en_reference_subsystems_llm-streaming.md
+en_reference_subsystems_lsp.md
+en_reference_subsystems_permission-presets.md
+en_reference_subsystems_persistence.md
+en_reference_subsystems_plan.md
+en_reference_subsystems_sandbox.md
+en_reference_subsystems_schedule.md
+en_reference_subsystems_scope.md
+en_reference_subsystems_session.md
+en_reference_subsystems_session-projection.md
+en_reference_subsystems_session-query.md
+en_reference_subsystems_session-reference.md
+en_reference_subsystems_session-telemetry.md
+en_reference_subsystems_session-title.md
+en_reference_subsystems_settings.md
+en_reference_subsystems_shell.md
+en_reference_subsystems_skills.md
+en_reference_subsystems_spill.md
+en_reference_subsystems_storage.md
+en_reference_subsystems_subagent.md
+en_reference_subsystems_subprocess.md
+en_reference_subsystems_system-prompt.md
+en_reference_subsystems_terminal.md
+en_reference_subsystems_token-meter.md
+en_reference_subsystems_tools.md
+en_reference_subsystems_typert.md
+en_reference_subsystems_user-questions.md
+en_reference_subsystems_web.md
+en_reference_subsystems_web-server.md
+en_reference_subsystems_workflow.md
+en_reference_subsystems_workspace.md
+en_reference_tool-catalog.md
+en_reference_tool-execution-pipeline.md
+guide_providers.md
+guide_python-sdk.md
+guide_quickstart.md
+index.md
+reference_agent-lifecycle.md
+reference_capability-seams.md
+reference_config-catalog.md
+reference_cookbook_adding-a-conversation-node.md
+reference_cookbook_adding-an-llm-adapter.md
+reference_cookbook_adding-a-package.md
+reference_cookbook_adding-a-settings-card.md
+reference_cookbook_adding-a-tool.md
+reference_cookbook_extension-cookbook.md
+reference_cordis-api_context.md
+reference_cordis-api_events.md
+reference_cordis-api_fiber.md
+reference_cordis-api_inherited.md
+reference_cordis-api_registry.md
+reference_cordis-api_service.md
+reference_cordis-primer.md
+reference_index.md
+reference_persistence-catalog.md
+reference_subsystems_approval.md
+reference_subsystems_client-modules.md
+reference_subsystems_code-runtime.md
+reference_subsystems_commands.md
+reference_subsystems_compaction.md
+reference_subsystems_core.md
+reference_subsystems_credentials.md
+reference_subsystems_filesystem.md
+reference_subsystems_goal.md
+reference_subsystems_index.md
+reference_subsystems_invariants.md
+reference_subsystems_jobs.md
+reference_subsystems_llm-streaming.md
+reference_subsystems_lsp.md
+reference_subsystems_permission-presets.md
+reference_subsystems_persistence.md
+reference_subsystems_plan.md
+reference_subsystems_sandbox.md
+reference_subsystems_schedule.md
+reference_subsystems_scope.md
+reference_subsystems_session.md
+reference_subsystems_session-projection.md
+reference_subsystems_session-query.md
+reference_subsystems_session-reference.md
+reference_subsystems_session-telemetry.md
+reference_subsystems_session-title.md
+reference_subsystems_settings.md
+reference_subsystems_shell.md
+reference_subsystems_skills.md
+reference_subsystems_spill.md
+reference_subsystems_storage.md
+reference_subsystems_subagent.md
+reference_subsystems_subprocess.md
+reference_subsystems_system-prompt.md
+reference_subsystems_terminal.md
+reference_subsystems_token-meter.md
+reference_subsystems_tools.md
+reference_subsystems_typert.md
+reference_subsystems_user-questions.md
+reference_subsystems_web.md
+reference_subsystems_web-server.md
+reference_subsystems_workflow.md
+reference_subsystems_workspace.md
+reference_tool-catalog.md
+reference_tool-execution-pipeline.md

package/kb/meta/source.json

@@ -0,0 +1,13 @@
+{
+  "knowledgeBase": "DeepSeek Harness 官方文档知识库",
+  "source": "官方文档站点 https://deepseek-harness.github.io/deepseek-harness/ （VitePress）",
+  "repository": "https://github.com/deepseek-ai/deepseek-harness",
+  "branch": "master",
+  "commit": "99f6f02fecdb7dff40c3fbc9470f5907c29f74ca",
+  "fetchedAt": "2026-08-17T11:21:17.298Z",
+  "siteBase": "https://deepseek-harness.github.io/deepseek-harness",
+  "publishedMarkdownPages": 168,
+  "siteFiles": 172,
+  "images": 4,
+  "extraFiles": 50
+}

package/kb/meta/topics.md

@@ -0,0 +1,75 @@
+# 主题导航（Topics）
+
+> 用途：按**任务场景**快速定位要读的文档。路径相对于知识库根 `kb/`（绝对路径：`D:\dsh\plugins\dsh-plugin-dev-kb\kb\`）。
+> 中文优先读 `site/` 下的文件；英文原文在 `site/en/` 对应路径（如 `site/en/develop/basic/index.md`）。
+> 每个主题：**核心** = 先读这些；**扩展** = 需要细节时再读。
+
+## 1. 入门：第一个插件
+- 核心：`site/develop/basic/index.md`（插件 = 导出 `apply(ctx)` 的模块；`ctx.effect()` 自动清理；三种插件形态：函数/对象/类）
+- 扩展：`site/develop/cordis-tutorial/01-first-plugin.md`、`site/develop/framework/index.md`
+
+## 2. 开发一个 Tool
+- 核心：`site/develop/basic/tool.md`（工具定义 DSL）、`site/reference/cookbook/adding-a-tool.md`（完整步骤 + 验证）
+- 扩展：`site/reference/tool-catalog.md`（全部内置工具 schema，大文件请 grep）、`site/reference/subsystems/tools.md`（注册表与执行流水线）、`site/reference/tool-execution-pipeline.md`
+
+## 3. 插件配置
+- 核心：`site/develop/basic/config.md`、`site/develop/cordis-tutorial/05-config.md`
+- 扩展：`site/reference/config-catalog.md`（全量配置项，大文件请 grep）
+
+## 4. 服务与依赖注入
+- 核心：`site/develop/framework/service.md`、`site/develop/cordis-tutorial/03-services.md`
+- 扩展：`site/reference/cordis-api/service.md`、`site/reference/capability-seams.md`（能力三层：Service Definition / Provider / Consumer）
+
+## 5. 事件系统
+- 核心：`site/develop/framework/events.md`、`site/develop/cordis-tutorial/04-events.md`
+- 扩展：`site/reference/cordis-api/events.md`、`site/reference/persistence-catalog.md`（持久化事件目录）、`extra/event-producer-consumer.md`
+
+## 6. 生命周期与副作用
+- 核心：`site/develop/framework/index.md`、`site/develop/cordis-tutorial/02-lifecycle-and-effects.md`
+- 扩展：`site/reference/agent-lifecycle.md`、`site/reference/cordis-api/context.md`、`extra/defensive-patterns.md`（生命周期/并发/子进程防御模式）
+
+## 7. 打包与发布插件
+- 核心：`site/develop/basic/publish.md`
+- 扩展：`extra/cookbook/adding-a-vendored-package.md`（vendored 包）
+
+## 8. LLM 适配器
+- 核心：`site/develop/practice/llm-adapter.md`、`site/reference/cookbook/adding-an-llm-adapter.md`
+- 扩展：`site/reference/subsystems/llm-streaming.md`（流式响应/Message/ContentBlock/StreamChunk）
+
+## 9. 扩展点与能力分层
+- 核心：`site/develop/practice/index.md`（能力三层拆分）、`site/reference/capability-seams.md`
+- 扩展：`site/reference/cookbook/extension-cookbook.md`（扩展模式）、`site/reference/cookbook/adding-a-conversation-node.md`
+
+## 10. 新增 Package / 设置卡片 / Conversation Node
+- 核心：`site/reference/cookbook/adding-a-package.md`、`site/reference/cookbook/adding-a-settings-card.md`、`site/reference/cookbook/adding-a-conversation-node.md`
+
+## 11. 子系统能力速查（按需）
+- 总览：`site/reference/subsystems/index.md`；README 约定见 `site/reference/subsystems/README.md`
+- 内核与作用域：`core.md`、`scope.md`、`invariants.md`（运行时不变式）
+- 会话与持久化：`session.md`、`session-query.md`、`session-reference.md`、`session-title.md`、`session-projection.md`、`persistence.md`、`spill.md`、`session-telemetry.md`
+- 模型与上下文：`llm-streaming.md`、`token-meter.md`、`system-prompt.md`、`compaction.md`（上下文压缩）
+- 执行与工具：`tools.md`、`shell.md`（Bash）、`subprocess.md`、`terminal.md`（PTY）、`jobs.md`（后台任务）、`filesystem.md`、`lsp.md`、`code-runtime.md`、`web.md`、`skills.md`、`workflow.md`、`subagent.md`
+- 策略与交互：`approval.md`（审批）、`permission-presets.md`、`sandbox.md`、`plan.md`（计划模式）、`user-questions.md`、`commands.md`、`goal.md`、`schedule.md`
+- 平台与接入：`web-server.md`（HTTP 服务器）、`typert.md`、`client-modules.md`、`storage.md`、`workspace.md`、`settings.md`、`credentials.md`
+- 以上均在 `site/reference/subsystems/` 下（如 `site/reference/subsystems/session.md`）
+
+## 12. 架构与核心概念
+- 核心：`site/reference/index.md`（架构总览：组合、核心包、循环、seam、扩展点）、`site/reference/cordis-primer.md`（Cordis 入门）
+- 扩展：`extra/glossary.md`（术语表：capability seam 等）、`extra/module-graph.md`（模块依赖全景图，大文件请 grep）、`extra/graph-atlas.md`
+
+## 13. 系统提示词 / Token / 上下文压缩
+- `site/reference/subsystems/system-prompt.md`、`token-meter.md`、`compaction.md`
+
+## 14. 测试与防御
+- `extra/testing.md`（测试策略：快照/e2e/单测边界）、`extra/defensive-patterns.md`、`extra/postmortem/`（事故复盘 4 篇，含沙箱/进程故障模式）
+
+## 15. 文档规范与贡献
+- `extra/AGENTS.md`（文档分层标准：tutorial/reference、字数预算）、`extra/development.md`（开发环境与工作流）、`extra/i18n/`（双语规范与术语）
+
+## 16. 中英对照
+- 英文站：`site/en/`（结构与中文站一致：`guide/`、`develop/`、`reference/`）；`INDEX.md` 有全部 URL ↔ 文件对照
+
+## 检索技巧
+- 全量索引：`meta/search-index.json`（220 个文件的 path/url/title/字符数）
+- 大文件（config-catalog / tool-catalog / module-graph / subsystems/session 等 ≥100KB）先用 grep 定位关键行，再 read 局部，不要整读
+- 常用检索关键词：`ctx.effect`、`ctx.on`、`ctx.tools.register`、`inject`、`Service Definition`、`cordis.yml`、`SessionEventMap`

package/kb/site/develop/basic/config.md

@@ -0,0 +1,108 @@
+---
+editSource: "docs/user/develop/basic/config.zh.md"
+---
+
+# 插件配置
+
+让你的插件接受用户在 `cordis.yml` 中传入的配置。
+
+## 定义 Config 类型
+
+在插件中导出一个 `Config` 类型和同名的 Schemastery schema；默认值直接写在 schema 中：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import Schema from '@deepseek-ai/schemastery'
+
+export const name = 'my-plugin'
+
+export interface Config {
+  greeting: string
+  maxRetries: number
+  verbose?: boolean
+}
+
+export const Config: Schema<Config> = Schema.object({
+  greeting: Schema.string().default('Hello'),
+  maxRetries: Schema.number().default(3),
+  verbose: Schema.boolean().default(false),
+})
+
+export function apply(ctx: Context, config: Config) {
+  console.log(config.greeting)  // User value or schema default.
+}
+```
+
+在 `scratch-plugin/cordis.yml` 新插入的本地插件行中添加配置：
+
+```yaml
+- insert:
+    - id: hello
+      name: './src/my-plugin.ts'
+      config:
+        greeting: 'Hi there'
+        maxRetries: 5
+```
+
+插件加载时，Cordis 会通过导出的 schema 校验配置，并填充未提供字段的默认值。不要导出普通对象作为 `Config`，因为它不满足 Cordis 要求的 Standard Schema 接口。
+
+## Schema 校验
+
+对于需要严格校验的场景，使用 Schemastery 定义 schema：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import Schema from '@deepseek-ai/schemastery'
+
+export const name = 'validated-plugin'
+
+export interface Config {
+  apiKey: string
+  timeout: number
+  mode: 'fast' | 'accurate'
+}
+
+export const Config = Schema.object({
+  apiKey: Schema.string().required(),
+  timeout: Schema.number().default(30000),
+  mode: Schema.union(['fast', 'accurate']).default('fast'),
+})
+
+export function apply(ctx: Context, config: Config) {
+  // config is validated and type-safe.
+}
+```
+
+Schema 在插件加载时执行校验。如果配置不合法，插件会加载失败并给出明确错误信息。
+
+## 设计原则
+
+### 无硬编码可调参数
+
+Harness 的约定：**凡是不同部署可能需要采用不同值的参数，都必须定义为配置字段**。
+
+```ts
+// Wrong: hardcoded timeout.
+const TIMEOUT = 30000
+
+// Correct: configurable.
+export interface Config {
+  timeoutMs: number  // Defaults to 30000.
+}
+```
+
+检验标准：能否在 `cordis.yml` 中改变这个值，而不需要修改代码？
+
+### 配置错误要响亮
+
+在 schema 中表达自身完备的约束，使无效配置在插件加载时失败。对服务或已注册资源的引用需要依赖注入；[服务教程](../framework/service.md) 会介绍这项约定。
+
+## 配合 HMR
+
+配置变更会触发插件热替换：修改 `cordis.yml` 中某个插件的 `config` 后，框架会卸载旧实例并加载新实例。由于注册都属于 effect 并会自动清理，替换后不会保留旧实例的注册。
+
+## 下一步
+
+- [打包与安装插件](./publish.md) — 把插件以可安装包的形式交付
+- [插件与生命周期](../framework/index.md) — 深入了解插件的完整生命周期
+- [服务与依赖](../framework/service.md) — 让你的插件对外提供服务

package/kb/site/develop/basic/index.md

@@ -0,0 +1,146 @@
+---
+editSource: "docs/user/develop/basic/index.zh.md"
+---
+
+# 第一个插件
+
+本教程会创建一个最小的 Harness 插件，并将其加载到 Web UI 中。请从已完成[从源码运行路径](https://github.com/deepseek-ai/deepseek-harness/blob/master/README.md#run-from-source)的仓库检出开始。
+
+## 创建本地项目
+
+在仓库根目录创建本教程使用的临时项目：
+
+```sh
+mkdir -p scratch-plugin/src
+```
+
+## 插件是什么
+
+在 Harness 中，插件是一个导出 `apply` 函数的 TypeScript 模块。框架在加载时调用 `apply`，传入一个 `ctx`（上下文对象），你通过 `ctx` 注册能力：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'my-plugin'
+
+export function apply(ctx: Context) {
+  // Register capabilities here.
+}
+```
+
+这就是完整配置。
+
+## 创建插件文件
+
+创建 `scratch-plugin/src/my-plugin.ts`：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'hello-plugin'
+
+export function apply(ctx: Context) {
+  // Required dependencies are ready before apply runs.
+  console.log('[hello-plugin] plugin loaded!')
+}
+```
+
+## 注册到 cordis.yml
+
+在仓库根目录运行 `pwd`，然后创建 `scratch-plugin/cordis.yml`，作为插入本地插件的 Web 覆盖层。请将下文的 `/absolute/path/to/deepseek-harness` 替换为命令打印的路径：
+
+```yaml
+- insert:
+    - id: hello
+      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
+```
+
+插件路径必须是绝对路径。patch 文件只贡献配置，不会改变 loader 解析模块路径时使用的 profile 目录。
+
+使用该覆盖层启动 Web UI：
+
+```sh
+pnpm dsh web --patch ./scratch-plugin/cordis.yml
+```
+
+打开 `http://127.0.0.1:3080`。启动期间，终端会打印 `[hello-plugin] plugin loaded!`。
+
+## 自动清理
+
+通过 `ctx` 注册的任何东西——事件监听、工具、定时器——在插件卸载时都会被自动清理。你不需要手动 removeListener 或 clearInterval。
+
+如果你有需要手动清理的资源（比如一个网络连接），用 `ctx.effect()` 告诉框架怎么清理：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export function apply(ctx: Context) {
+  ctx.effect(() => {
+    const timer = setInterval(() => {
+      console.log('heartbeat')
+    }, 5000)
+
+    // The returned function runs when the plugin unloads.
+    return () => clearInterval(timer)
+  })
+}
+```
+
+## 声明依赖
+
+如果你的插件需要使用其他服务（如 `tools`、`llm`），需要声明 `inject`：
+
+```ts ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'my-tool-plugin'
+export const inject = ['tools']
+
+export function apply(ctx: Context) {
+  // ctx.tools is ready here.
+  ctx.tools.register(/* ... */)
+}
+```
+
+框架会确保依赖的服务就绪后才加载你的插件。
+
+## 插件的三种形态
+
+除了函数形式，插件还支持对象形式和类形式：
+
+### 对象形式
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export default {
+  name: 'my-plugin',
+  inject: ['tools'],
+  apply(ctx: Context) {
+    // ...
+  },
+}
+```
+
+### 类形式
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+export default class MyService extends Service {
+  static inject = ['tools']
+
+  constructor(ctx: Context) {
+    super(ctx, 'myService')
+    // Perform synchronous initialization in the constructor.
+  }
+}
+```
+
+大多数情况下，函数形式足够了。当插件需要向其他插件提供服务时，可使用类形式（见 [服务与依赖](../framework/service.md)）。
+
+## 下一步
+
+- [开发一个工具](./tool.md) — 了解工具定义 DSL
+- [插件配置](./config.md) — 让插件接受用户配置
+- [Cordis 框架教程](../cordis-tutorial/index.md) — 底层的插件框架，在临时目录中动手构建，无需 API 密钥