DeepSeek Harness实战：从零构建LLM Wiki知识库系统

最近技术社区里经常有人讨论用 DeepSeek Harness 这类 LLM Agent 框架10 轮提示就能完成一个工业级项目。很多人第一次看到这个说法会觉得是夸大宣传毕竟常规经验里“让 AI 写一个完整项目”往往是先生成一套骨架然后陷入“报错—修改—再报错”的循环能跑通已经不错更别说达到工业级。但如果你真的把一个完整项目从头到尾跑一遍会发现“10 轮”这个数字并不是关键。关键的变化是开发流程被拆成了可控的阶段模型行为被一套配置约束住领域知识被打包成 Skills外部系统通过插件接入。换句话说AI 辅助开发正在从“一次性聊天”变成“工作流编排”。这篇文章以一个实际项目为例从零开发一个 LLM Wiki也就是一个面向团队内部的知识库问答系统。整个开发过程拆成 11 个阶段覆盖需求、数据、检索、生成、插件、部署的完整链路并重点讲清楚 DeepSeek Harness以下简称 DSH中 Preset、Skills、插件分别承担什么职责怎么配置怎么用。读完这篇文章你可以把这套方法直接迁移到自己的知识库、内部工具或 Agent 项目中。1. DeepSeek Harness 是什么它真正解决什么问题DSH 是一个面向 LLM 应用开发的工程化框架。它的名字里 “Harness” 很有意思英文原意是“马具”引申为“驾驭”。在 LLM 开发语境下它强调的不是让模型自由发挥而是通过结构化的配置和工具把模型的输出约束在可控范围内。它解决的第一个问题是上下文管理。LLM 的上下文窗口有限一个完整的项目需要读文档、查代码、看规范如果全部塞进一次对话很快就会超出边界。DSH 通过工作区Workspace、索引和按需检索把“什么时候读什么上下文”变成可编排的逻辑。它解决的第二个问题是知识沉淀。普通对话是一次性的但 DSH 里的 Skills 可以把领域专业知识固化成文件Preset 可以把模型参数和提示模板固化下来插件可以把外部 API 能力固化下来。下次做类似项目时直接复用不需要从头再调一遍。它解决的第三个问题是流程可控。传统 Agent 常常“一跑到底”中途出错很难恢复。DSH 把开发拆成阶段每个阶段有明确的输入输出这既是它能压缩提示轮次的原因也是工业级项目能落地的原因。所以DSH 真正降低的不是“写代码”的成本而是“把 LLM 接入工程流程”的成本。这个判断会影响你之后的使用方式如果你只是把它当成聊天窗口那它和大模型网页版没有本质区别如果你把它当成一个开发框架来对待才能体会到 Preset、Skills、插件组合起来的力量。2. 为什么用 LLM Wiki 做实战项目选 LLM Wiki 作为实战项目首先是因为文档知识库是一个很真实的需求。团队里文档越堆越多查找困难维护成本高传统 Wiki 依赖人工编辑经常出现“文档过期”和“找不到内容”两个问题。而 LLM 可以自动解析文档、生成摘要、归纳关键词并且支持自然语言问答正好补上传统知识库的短板。业界讨论的 “LLM Wiki” 范式核心思路是把大模型当作一种可检索、可更新的知识库引擎。它不是把维基百科塞进模型而是用模型去理解文档再通过检索增强生成的方式回答用户问题。这样知识库可以随时更新模型不需要重新训练成本低效果可控。从技术训练的角度看LLM Wiki 项目也足够典型。它包含完整的工程链路数据层要做文档采集、清洗、分块索引层要做向量化、索引存储生成层要做检索增强问答交互层要提供命令行或 Web 入口扩展层要接插件比如外部搜索、定时更新。这一套链路做下来几乎把 LLM 应用开发的核心环节都覆盖了。这个项目不会太简单它有真实的技术深度也不会太复杂核心只需要解决文档读取、索引、问答三条链路。对一个想学习 DSH 的开发者来说是一个性价比很高的练习项目。3. 核心概念Preset、Skills、插件与工作流的关系在使用 DSH 之前先要把几个核心概念的关系理清楚。概念类比职责在 LLM Wiki 中的例子Preset运行模式固定模型参数、提示模板、工具开关问答模式 temperature0.2Skills领域专家封装专业能力完成某个具体任务文档解析、检索、问答插件手和脚连接外部系统外部搜索 API、Git 文档同步Workspace工作区存放项目和知识资产docs、index、output 目录Agent项目经理根据目标调度上述组件根据问题自动调用检索和问答它们的关系可以这样理解Agent 根据用户目标选择要使用的 SkillsSkills 内部调用模型能力和工具外部依赖由插件完成Preset 决定整个过程的模型参数和上下文策略。五者组合在一起才构成一个完整的可运行项目。新手最容易混淆的是 Skill 和插件。简单说Skill 解决的是“用模型做一个专业任务”的问题比如总结文档、抽取关键词插件解决的是“让程序访问外部系统”的问题比如调用搜索接口、读写数据库。两者方向不同但经常配合使用。4. 环境准备与安装DSH 目前主要通过 Node.js 工具链安装从社区反馈来看使用 pnpm 方式比较常见。下面的步骤给出通用安装路径具体版本以官方仓库 README 为准。4.1 安装基础依赖建议环境如下操作系统Ubuntu 22.04、macOS 13 或 Windows 10 配合 WSL2运行时Node.js 18Python 3.10用于 Skills 脚本包管理pnpm 8安装 DSH# 克隆官方仓库 git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness # 安装依赖 pnpm install # 构建 pnpm build # 启动 Web 控制台 pnpm dsh web这里重点提醒如果执行pnpm dsh web后长时间卡住大概率不是命令问题而是pnpm install没有完整安装依赖或者本地端口被占用。这个问题后面会专门讲。4.2 验证安装并初始化项目# 验证 CLI 是否可用 pnpm dsh --help # 初始化项目 pnpm dsh init my-llm-wiki cd my-llm-wiki初始化完成之后典型项目结构如下my-llm-wiki/ ├── presets/ # Preset 配置 ├── skills/ # Skills 技能包 ├── plugins/ # 插件目录 ├── docs/ # Wiki 原始文档 ├── index/ # 生成的索引 └── dsh.config.yaml # 项目主配置这套目录结构本身就是一个工程约定它让同一个项目的多个参与者能快速找到对应模块也方便后续把 Preset、Skills、插件分别做成可复用的资产。5. 11 阶段开发流程总览整个 LLM Wiki 项目可以拆成 11 个阶段。每个阶段解决一个明确问题完成一个阶段再进入下一阶段这也是“10 轮提示”能成立的工程基础。阶段核心任务主要产物DSH 对应能力1 需求与范围明确 Wiki 主题、目标用户、功能边界PRD 文档Workspace2 环境搭建安装 DSH初始化项目可运行项目骨架CLI3 数据准备采集和清洗文档确定格式标准化的 docs 文档文件解析4 知识建模设计分类、标签、层级Wiki 目录结构Workspace5 模型接入配置模型和预设提示模板Preset 配置文件Preset6 检索链路分块、向量化、建立索引索引文件、检索模块Skills7 问答工作流编写 RAG 问答流程QA SkillSkills8 人机交互命令行或 Web 对话入口CLI 或 Web 页面Web Console9 插件扩展对接搜索、定时更新插件代码Plugin10 测试评估效果测试和质量评分测试报告Evaluation11 部署发布打包上线、持续更新部署脚本插件/CI这个流程的核心原则是先定义清楚“项目边界”再动手写配置和代码。很多 Agent 项目翻车不是因为模型能力不够而是因为需求不明确目标一变再变提示词和上下文不断膨胀。阶段化开发正好解决了这个问题。6. 核心配置实战Preset 与模型接入Preset 是 DSH 里最值得先掌握的配置项。它的作用是把模型参数、prompt、检索参数、日志策略固化成一个可复用的配置文件。6.1 Preset 文件结构在presets/目录下创建一个qa.yaml# 文件路径presets/qa.yaml name: qa description: 面向 Wiki 问答的基础预设 model: provider: deepseek name: deepseek-chat temperature: 0.2 max_tokens: 2048 top_p: 0.9 context: system_prompt: | 你是一个团队内部 Wiki 问答助手。请只根据检索到的文档内容回答 不要编造事实。如果文档内容不足以回答请明确说明。 knowledge_base: index_path: ./index/wiki.idx retrieval_top_k: 5 skills: include: - doc-parse - retriever - qa-engine logging: level: info output: ./logs/qa.log6.2 关键参数说明provider和name指定模型供应商和模型名具体以你实际能访问的模型服务为准。temperature控制随机性。知识库问答建议设置在 0.2 到 0.3 之间太低会显得死板太高容易偏离文档事实。retrieval_top_k表示检索时返回的文档片段数量。5 是一个比较稳妥的起点文档质量差时可以适当提高到 8。system_prompt是系统提示词它的约束力直接影响回答质量。对 Wiki 问答来说必须明确要求“只根据检索到的内容回答”否则模型会用训练数据里的常识补全产生幻觉。skills.include列出这个 Preset 会启用的技能。配置完成后通过命令行指定并运行pnpm dsh run --preset qa --prompt 什么是项目立项流程这里真正容易踩坑的地方是Preset 里的模型配置和实际 API 密钥没有对应上。如果密钥没配置或者模型名写错请求会在启动阶段就报错。建议把密钥放到环境变量里而不是直接写进 YAML 文件。export DSK_API_KEYyour_api_key_here7. 核心能力实战Skills 与检索问答工作流Skills 是 DSH 最核心的扩展单元。一个 Skill 可以理解成一个“可复用的专业任务包”它通常包含三部分任务描述、提示词模板、处理脚本。7.1 Skill 目录结构我们为 LLM Wiki 设计了三个 Skillskills/ ├── doc-parse/ │ ├── skill.yaml │ ├── prompt.md │ └── main.py ├── retriever/ │ ├── skill.yaml │ ├── prompt.md │ └── main.py └── qa-engine/ ├── skill.yaml ├── prompt.md └── main.py以doc-parse为例skill.yaml用于声明技能信息# 文件路径skills/doc-parse/skill.yaml name: doc-parse description: 解析 Markdown 文档生成标题、摘要与关键词 version: 1.0.0 inputs: - file_path outputs: - title - summary - keywords entry: main.pyprompt.md是指导模型工作的提示词模板你是文档解析专家。请阅读给定文档输出以下字段 1. 文档标题 2. 150 字以内的摘要 3. 3 到 5 个关键词 要求简洁、准确不要加入文档之外的信息。main.py是实际执行的脚本负责读取输入、调用模型、返回结构化结果# 文件路径skills/doc-parse/main.py import sys from pathlib import Path def parse_doc(file_path: str) - dict: text Path(file_path).read_text(encodingutf-8) # 实际项目中这里应把 text 交给 LLM 做结构化抽取 return { title: Path(file_path).stem, summary: text[:150], keywords: [], } if __name__ __main__: result parse_doc(sys.argv[1]) print(result)这是一个演示逻辑关键在于理解 Skill 的输入输出约定。真正的生产环境里摘要和关键词需要调用模型生成而不是简单截断。7.2 检索问答工作流当用户提出一个问题时完整的工作流是这样的用户输入问题。retrieverSkill 从向量库中检索相关文档片段。检索结果与原始问题一起传给qa-engineSkill。模型基于检索内容生成回答并附上引用来源。这个流程就是业界的 RAGRetrieval-Augmented Generation检索增强生成模式。它最大的优势是回答可以溯源并且知识库更新时不需要重新训练模型只需要重新建立索引。运行方式pnpm dsh run --preset qa --skill qa-engine --prompt 开源协议有哪些类型8. 扩展能力实战插件开发与外部系统对接Skill 解决的是“用模型做任务”的问题插件解决的是“让 DSH 访问外部系统”的问题。对 LLM Wiki 来说最典型的插件是外部搜索插件它能让知识库不局限于本地文档可以实时获取最新信息。8.1 插件的基本结构plugins/ └── web-search/ ├── plugin.yaml ├── main.py └── requirements.txtplugin.yaml声明插件信息# 文件路径plugins/web-search/plugin.yaml name: web-search version: 1.0.0 description: 调用外部搜索 API 补充资料 entry: main.py permissions: - networkmain.py实现具体逻辑# 文件路径plugins/web-search/main.py import requests class WebSearchPlugin: def __init__(self, api_key: str ): self.api_key api_key def search(self, query: str, limit: int 5) - list: url https://api.example.com/search params {q: query, limit: limit} resp requests.get(url, paramsparams, timeout5) resp.raise_for_status() return resp.json().get(results, []) def register(manager): manager.register(web-search, WebSearchPlugin)外部搜索 API 通常需要申请密钥。使用时密钥要放在环境变量中不要硬编码进插件文件。export SEARCH_API_KEYyour_search_api_key8.2 如何在 DSH 中加载插件在命令行中指定启用插件即可pnpm dsh run --preset qa --plugin web-search --prompt 查找最新的 LLM Agent 框架对比插件让 LLM Wiki 从“只读知识库”升级成“可实时更新的信息门户”。不过要注意插件权限越大风险越高。如果插件需要执行 Shell 命令或访问数据库务必做最小权限设计不能在插件代码里写死管理员密码或敏感 token。9. 运行验证与效果评估全流程搭好之后不能只看“能跑”就结束。工业级项目要求可验证、可度量。9.1 运行与预期输出pnpm dsh run --preset qa --skill qa-engine --prompt 开源协议有哪些类型预期输出是带有引用来源的结构化回答类似于{ answer: 常见的开源协议包括 MIT、Apache 2.0、GPL 等其中 MIT 协议约束最少适合商业项目引用。, sources: [docs/open-source-license.md] }判断运行成功的三个标准能准确引用文档来源、回答中没有明显幻觉、端到端延迟在可接受范围。9.2 评估维度评估指标目标值说明检索命中率85%前 5 条检索结果中包含正确答案回答准确率90%人工抽样式评估幻觉率5%回答中出现文档中不存在的事实端到端延迟3 秒检索 生成总耗时这里需要特别说明评估集要提前沉淀。每轮测试的问题、标准答案、检索来源都要记录成 JSON形成回归测试集。后续修改 prompt 或调整分块策略时用同一套评估集对比才能知道改动是变好还是变坏。10. 常见问题与排查思路从社区反馈和实际开发经验来看下面几个问题出现频率最高。问题现象可能原因排查方式解决方案启动失败依赖版本冲突查看错误日志和依赖树统一版本或重新安装依赖pnpm dsh web 卡住依赖没装完或端口被占用检查 pnpm install 是否完整查看端口占用情况清空 node_modules 重新安装换端口模型请求超时API 密钥或网络问题查看日志中的 HTTP 状态码检查环境变量密钥确认网络连通检索结果为空索引未生成或路径错误检查 index/ 目录内容重新执行索引构建脚本回答出现幻觉检索质量差或 prompt 约束不足检查 top_k 和分块大小提高 top_k增强 system_prompt优化分块策略输出格式不稳定没有用结构化输出约束查看模型实际返回内容在 prompt 中明确 JSON 格式必要时增加输出校验脚本“pnpm dsh web 卡住”这个问题的排查顺序是先看终端日志是否停在依赖安装阶段再用lsof -i :8080这类命令检查端口占用最后确认是不是网络原因导致依赖下载不完整。大多数情况是第一个原因而不是 DSH 本身的问题。11. 最佳实践与工程建议把整个项目流程走通之后有几条经验值得沉淀下来。第一命名规范要统一。Skills 建议按“动词对象”命名比如parse-doc、search-index、generate-answer。插件按功能命名如web-search、git-sync。命名清晰后Agent 在选择 Skill 时更准确人阅读配置时也更直观。第二Preset 要分环境管理。开发、测试、生产环境的模型参数可以不一样。开发环境可以用较高 temperature 让模型多产出不同方案测试和生产环境应该固定为低 temperature保证输出稳定。第三敏感配置一律不进 Git。API 密钥、数据库连接串、内部服务地址都要通过环境变量或密钥管理服务注入。插件和脚本里也不要出现真实的密钥。第四文档分块策略要重视。分块太小会丢失上下文分块太大会引入无关信息。通用建议是按 Markdown 的标题层级分块每块控制在 500 到 800 字块与块之间保留少量重叠。这个策略需要结合自己的文档结构反复调整。第五建立回归评估集。把测试问题、标准答案、预期来源都记录成 JSON每次修改 Prompt、调整检索参数或更新文档后跑一遍回归测试。这是工业级项目区别于“跑通就好”的关键。第六注意 Token 成本和调用延迟。记录每个任务的输入输出 token 数给长任务设置max_tokens上限。如果检索结果数量大可以先用粗检索筛掉明显不相关的片段再做精排。第七安全边界要守好。外部输入不能直接拼接进系统指令插件权限要最小化不要让 LLM Agent 直接执行未经验证的 Shell 命令。尤其在生产环境涉及删除、写库、发布操作时必须增加人工确认环节。12. 总结这篇文章的核心观点是DSH 这类工具的真正价值不是让 AI 一次性帮你写完整个项目而是把开发过程拆成可控的环节让 Preset、Skills、插件各司其职最终把“10 轮提示”从口号变成可复用的工作流。我们通过一个 LLM Wiki 项目完整走过了需求定义、环境搭建、数据准备、知识建模、模型配置、检索链路、问答工作流、插件扩展、测试评估和部署发布的 11 个阶段。如果你接下来要实践建议先照本文的结构做一个最小 Demo两个文档、一个检索 Skill、一个问答 Skill、一个简单的 Preset。跑通之后再逐步加入更多文档、优化分块、接入外部搜索插件。核心原则是每加一个功能就加一个评估指标确保改动方向始终正确。后续可以继续深入的方向包括 RAG 检索优化、Agent 评测体系、Model Context Protocol 工具协议、以及多 Agent 协作编排。这些话题都以本文的基础结构为起点值得花时间逐个突破。