Agent Plan × DeepSeek Harness 实战落地

目录

1. 开篇：从"会聊天的模型"到"能干活的智能体"
2. 核心思想与整体架构
3. 环境搭建与首次配置
4. Agent Plan 五大能力组件拆解
5. 四种运行模式横向对比
6. Web UI 操作全景
7. 实战案例：三天搭出投资研究助手
8. 插件开发从零起步
9. 最佳实践与避坑速查
10. 生态地图与未来路线
11. 高频问题 FAQ
12. 附录：术语表与参考资料

1. 开篇：从"会聊天的模型"到"能干活的智能体"

1.1 模型再聪明，也只是"嘴"

过去三年，大语言模型迭代速度惊人。从 GPT-3.5 把行业点燃，到 DeepSeek V2/V3 在推理成本与中文能力上撕开突破口，再到 V4 在多步推理、工具调用精度上跨过一道门槛——模型确实越来越聪明。但任何一个真正想把 AI 用进业务里的开发者，都会撞上一堵墙：模型能聊，不等于能干活。

你可能也踩过类似场景：

• 让 AI"写个爬虫"，它输出几百行代码，跑起来缺依赖、路径错、Selector 失效，你得手改半天；
• 让它"分析某公司财报"，它基于训练数据里过时的信息编故事，还编得头头是道；
• 让它"持续跟踪几只股票"，对话一关，全部上下文蒸发，下次开新会话还得从头交代。

问题根源不在模型本身，而在模型和真实世界之间的那一层"基础设施"——业界称之为 Agent Harness（智能体挽具）。Harness 这个词本义是套在马身上的挽具，把马的力气导向车辆。放到 AI 语境里：模型是马，Harness 是底盘和操控系统。它决定：

• 模型能看哪些目录、不能碰哪些文件（安全边界）；
• 模型能调哪些工具、调用前要不要审批（工具治理）；
• 会话怎么保存、跨会话怎么续接记忆（状态管理）；
• 任务怎么拆解、半路崩了从哪续跑（执行规划）；
• 成果从网页、命令行还是代码里取（输出形态）。

DeepSeek Harness（下文简称 DSH）就是为填这层空白而生的——DeepSeek 官方下场开源了一套对标 Claude Code、但在架构灵活性上更激进的 Agent 运行底座。

1.2 Agent Plan：把"插槽"变成"配件包"

如果说 DSH 是"插槽标准"（像主板上的 PCIe 插槽），那火山方舟 Agent Plan 就是已经挑好、测好、装好的即插即用配件包：

一句话价值主张：DSH 给你插槽，Agent Plan 给你一套经过真实项目验证的"量大管饱"组件包，你不用在海量开源 Plugin 里一个个踩坑试错。

1.3 全文结构导图

2. 核心思想与整体架构

2.1 设计主张：一切皆插件

DSH 最具辨识度、也最激进的设计主张就是——一切皆插件（Everything is a Plugin）。

整个框架建立在 Cordis 微内核之上。内核本身极度克制，只做三件事：

1. 加载插件：按依赖顺序挂载；
2. 卸载插件：支持热插拔，运行时动态启停；
3. 依赖管理：插件 A 依赖 B 的服务时，自动按序启动。

除此之外，内核本身不提供任何业务能力——模型适配是插件、文件读写是插件、Shell 执行是插件、Web 搜索是插件、Skills 是插件、就连 Web UI 自身也是插件。任何一块不满意，拔掉换上你自己的实现就行，不用动框架源码。

这种设计的学术根基来自 Cordis 团队的论文《A Programming Paradigm for Spatiotemporal Composability》，核心思想是：把"什么能力在什么时空范围内生效"这件事，从硬编码里解耦出来，交给配置层去编排。

2.2 整体架构图

2.3 一条核心公式：Agent = Model + Harness

DSH 反复强调一个公式：Agent = Model + Harness。拆开看：

这个公式背后有一个关键的架构洞察：模型的能力边界由 Harness 决定，而不是模型本身。 同样一个 DeepSeek-V4 模型，接在普通聊天框里只能"说"；接在 DSH 里配好工具，它就能"做"——读文件、跑命令、查数据、写代码、部署应用。能力天花板被整体抬高了一个维度。

2.4 会话轨迹：每一次运行都留痕

DSH 的另一个关键设计是 Append-only Session Log（仅追加会话日志）。模型看到的一切、做过的一切，全部按时间序列原原本本记下来：

• 系统提示词的每一次注入；
• 模型的思维链（Chain of Thought）；
• 每一次工具调用的参数与返回结果；
• 子 Agent 的调度过程和输出；
• 审批流的通过 / 拒绝记录。

好处是：恢复（Resume）、分叉（Fork）、检索（Search）、回放（Replay） 四种高阶操作可以共享同一份事件流：

Web UI 的 Trajectory 视图里，你可以按来源过滤这些事件，一眼看清"模型到底看到了什么导致它做出这个决策"——这对调试 Agent 行为异常、定位工具调用错误至关重要。

3. 环境搭建与首次配置

3.1 系统要求一览

3.2 四条安装路径

DSH 提供四条安装路径，对应不同场景：

3.3 一键安装实操（推荐新手）

Step 1：检查 Node.js 环境

打开终端，输入：

node -v
# 期望输出：v22.xx.x 或更高
npm -v
# 期望输出：10.x.x 或更高

如果提示"不是内部或外部命令"，说明 Node.js 未安装，前往 nodejs.org 下载 LTS 版本，Windows 安装时记得勾选"Add to PATH"，安装后关闭终端重新打开让环境变量生效。

国内用户建议先切到镜像源加速：

npm config set registry https://registry.npmmirror.com
npm config get registry
# 期望输出：https://registry.npmmirror.com/

Step 2：一键启动 DSH Web UI

# 建议先 cd 到你准备存放项目的目录
cd /d E:\MyAgentProjects    # Windows 示例
# cd ~/MyAgentProjects      # Mac/Linux 示例

npx @deepseek-ai/dsh web

首次运行时，npx 会自动下载 @deepseek-ai/dsh 包及依赖，大约 1-3 分钟。启动成功后终端会打印：

  ➜  Local:   http://127.0.0.1:3080/
  ➜  Network: use --host to expose
  ➜  Profile: web (dsh.config.ts loaded from ~/.dsh/)

浏览器打开 http://127.0.0.1:3080/ 即可看到欢迎页面。

Step 3：配置 DeepSeek API Key

1. 前往 DeepSeek 开放平台 注册账号并创建 API Key（sk- 开头的一串字符）；
2. 在 DSH Web UI 右上角点齿轮图标进入「设置 → 模型」；
3. 找到 DeepSeek 卡片，粘贴 API Key，点保存。

DSH 会用只写（write-only）方式把密钥存放在 $DSH_HOME/.credentials.yaml（Windows 下一般是 C:\Users\你的用户名\.dsh\.credentials.yaml），界面上不再明文显示。

💡 Agent Plan 用户：如果你已经订阅火山方舟 Agent Plan，在「设置 → 模型」里选「添加自定义提供方」，填入 Agent Plan 专属 API 端点和 Key 即可。Agent Plan 的额度在方舟控制台统一结算，不用分别给多家模型厂商充值。

3.4 三种高阶安装方式

3.4.1 npm 全局安装（长期使用）

不希望每次都用 npx 临时拉取？全局安装固定版本：

npm install -g @deepseek-ai/dsh
dsh --version    # 验证安装成功

# 后续使用时直接：
dsh web          # 启动 Web UI
dsh              # 启动 TUI 终端模式（不开浏览器）
dsh --profile headless "帮我总结当前目录的代码结构"   # 无界面一次性任务

3.4.2 源码构建（插件开发）

想研究框架内部实现或开发自定义插件：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

# 安装依赖（需要先装 pnpm：npm install -g pnpm）
pnpm install

# 构建所有包
pnpm run build

# 启动开发模式（带热重载）
pnpm dsh web

源码模式下，改了任意插件代码 DSH 会自动热重载，非常适合插件开发调试。

3.4.3 Python SDK 集成（代码调用）

把 DSH 作为组件嵌入自己的 Python 后端服务：

# 安装 SDK（目前仅支持 Linux x64/arm64 和 macOS 14+ arm64，Windows 原生暂不支持）
python -m pip install deepseek-harness-sdk

调用示例：

from deepseek_harness import DeepSeekHarness

# 初始化，provider 选 deepseek-official 或自定义端点
with DeepSeekHarness(
    provider="deepseek-official",
    api_key="sk-你的key",
    workspace="./my_project"    # Agent 能操作的文件范围
) as harness:
    # 运行一次任务
    result = harness.run("帮我分析 my_project 下的 README.md，输出三句话摘要")
    print(result.final_response)
    
    # 也可以取完整轨迹（用于审计或调试）
    for event in result.trajectory:
        print(event.type, event.timestamp)

3.5 首次配置检查清单

4. Agent Plan 五大能力组件拆解

大脑（模型）就位后，真正决定 Agent "能不能干活、干得多好"的是 Harness 层的组件。Agent Plan 把火山方舟沉淀的产品能力，叠加广大开发者在真实项目里反复验证过的优选组件，打包成五大类。本章逐个拆解。

4.1 五位一体的能力拼图

4.2 豆包搜索：让 Agent 能上网，还能搜到可靠信息

4.2.1 不是"接个搜索引擎就完事"

很多人以为搜索就是"让 Agent 调一下 Google/Bing API"，实际用起来会发现三个大坑：

坑一：信息过时。 搜索引擎索引本身有延迟，再加上 API 返回的摘要经常截断，Agent 拿到的是断章取义的碎片。

坑二：来源不可信。 随便搜个"某某药疗效"，排前几的可能是广告站；搜技术问题，排前几的可能是 SEO 垃圾站抄的过时答案。

坑三：Query 不会写。 用户说"帮我看看这几家车企最近有啥动静"，Agent 如果原样丢给搜索引擎，返回结果稀碎——它不会自动把 Query 拆成"比亚迪 2026Q2 销量"“理想汽车 7 月新车型发布”"蔚来 财报 电话会纪要"这种精准子查询。

4.2.2 豆包搜索的三层能力

针对这三个问题，豆包搜索插件做了三层增强：

接入之后，你只需像平时一样对话，Agent 会在需要时自动触发豆包搜索，不用手动点按钮。典型触发场景：

• 用户问的事件发生在模型训练数据截止日期之后；
• 用户明确要求"查一下"“搜一下”；
• 模型对答案不确定，需要交叉验证；
• 需要带引用来源的回答（如研究报告、法律文书）。

4.2.3 高级用法：精细控制

# 示例：豆包搜索的配置项（Agent Plan 控制台）
doubao_search:
  # 只看权威来源（政府官网、交易所、SCI 期刊、上市公司 IR 站等）
  authoritative_only: true
  
  # 时间范围筛选：只看最近 30 天的结果
  time_range: "30d"    # 可选：7d / 30d / 90d / 1y / custom
  
  # 自动改写 Query
  query_rewrite:
    enabled: true
    max_sub_queries: 5    # 最多拆成几个子查询
    
  # 输出时必须带引用
  require_citations: true
  min_citation_count: 2   # 每个关键论断至少 2 个来源

4.3 专业数据集：给 Agent 喂硬核结构化数据

4.3.1 通用搜索做不到的事

想象一个场景：你让 Agent “帮我算一下比亚迪最近三年 ROE 变化趋势，与长城、吉利做对比”。

通用搜索怎么做？它搜出几篇财经文章，里面可能有人写过这个数字，但：

• 数字是不是最新的？不确定；
• 口径是否一致（扣非/归母、加权/摊薄）？不确定；
• 三年都有还是只写了一年？不确定；
• 能不能直接拿来画图？不能，还得手动抄进 Excel。

专业数据集插件就是解决这类问题的：它接入了付费商业数据库，在 Query 层做语义路由，自动把自然语言问题转发给对应的结构化数据库，返回标准格式 JSON——Agent 拿到后可以直接画图、生成表格、写进报告。

4.3.2 数据集覆盖范围

Agent Plan 专业数据集目前接入以下垂类库：

路由逻辑本身也是 Agent 决策的一部分——它根据用户问题的语义和上下文，选择最匹配的数据库调用。一个问题跨多个库时（“比亚迪 2025 年 ROE + 有没有司法纠纷 + 汉 EV 续航”），Agent 会依次调用三个库再整合结果。

4.3.3 数据可追溯

每条数据都带数据来源和更新时间戳，方便审计核验：

{
  "data_source": "东方财富 Choice 金融终端",
  "update_time": "2026-08-20T18:00:00+08:00",
  "company": "比亚迪股份",
  "stock_code": "002594.SZ",
  "roe": {
    "2023": 17.21,
    "2024": 21.45,
    "2025": 19.83
  },
  "unit": "%",
  "calculation_method": "加权平均净资产收益率（扣非归母）"
}

4.4 Agent 记忆系统：让 Agent 跨会话记得你

4.4.1 为什么"会话记忆"不够

普通 AI 聊天产品都有会话上下文——同一对话窗口里你说过的话它还记。但一关窗口、开新会话，它就失忆。

这对"长期干活"的 Agent 是致命的。比如做一个持续一周的项目：

• 周一：交代项目背景、目标、约束条件；
• 周二：让它继续做，但已经忘了周一说过啥，得从头再说一遍；
• 周三：你问它"上周我们定的方案呢"，它一脸懵。

Agent 记忆系统就是解决"跨会话持久化记忆"的问题。

4.4.2 架构设计：虚拟文件系统 + 语义检索

Agent Plan 的记忆系统基于 OpenViking Context 构建，核心是两个抽象：

虚拟文件系统（VFS） 的设计很巧妙：它把记忆、资源、技能统一抽象成"文件"，用熟悉的目录结构组织：

~/
├── memory/
│   ├── profile.md          # 我的基本信息、偏好
│   ├── projects/
│   │   ├── 股票持仓.md     # 关注哪些公司
│   │   └── ABC项目.md     # 某个长期项目的背景
│   └── preferences.md      # 输出风格、禁忌词等
├── resources/
│   ├── 比亚迪2025年报.pdf
│   └── VI规范.pdf
└── skills/
    ├── 生成研究简报.md     # 可复用的工作流模板
    └── 代码审查.md

你可以直接像编辑普通文件一样编辑这些记忆——觉得 AI 记错了什么，打开文件改就行，不用等它"学对"。

生命周期钩子是自动化的关键：

• 对话前钩子（Pre-hook）：每轮对话开始前，系统用当前用户输入的 query 去语义检索相关记忆，把最相关的 Top N 条注入到 System Prompt 的 Memory 区块，模型一上来就"记起"了相关背景；
• 对话后钩子（Post-hook）：每轮对话结束后，Evolve 组件（下一节讲）会判断这轮有没有新的事实、偏好或经验值得沉淀，如果有就增量写入对应的 memory 文件。

4.4.3 记忆的分层加载

记忆系统不是"把所有东西都塞进上下文"——那会超 token 限制，也会引入噪声。它做了三层加载策略：

4.5 Agent 进化系统：让 Agent 越用越聪明

4.5.1 痛点：同样的错误反复犯

你可能有这种体验：第一次让 Agent 写代码，它用了不规范的命名，你纠正"我们项目用驼峰命名法"，它当时改对了。下一次开新会话，它又用回下划线。你再纠正，第三次还是错——因为它根本没记住这个"经验"。

Evolve 进化组件就是让 Agent 能从历史交互中"学会"东西，沉淀成长期有效的指令，下次不用你再说第三遍。

4.5.2 工作原理：从会话轨迹中挖优化点

Evolve 的运行分四步：

关键的"人工确认"环节：Evolve 不会自己偷偷改你的指令文件。所有优化建议都以代码 Review 的形式展示——改了哪几行、基于哪段会话证据、风险等级（低/中/高）、置信度百分比。你点"接受"才写入，点"拒绝"就跳过，还可以在评论区补充说明，帮 Evolve 下次提得更准。

典型优化建议：

4.6 AI Native 应用开发底座：让 Agent 直接把东西做出来

4.6.1 从"能用"到"有用"的最后一公里

前四个组件（搜索、数据、记忆、进化）让 Agent 变聪明了，但很多任务的终点不是一段文字，而是一个真实的产品：

• 投资研究助手：每天生成的简报要存数据库，随时可以翻历史；
• 客户跟进系统：要区分不同用户的数据，要登录，要存文件；
• 团队内部工具：要部署在内网，要权限控制。

如果没有开发底座，这些都要手动建后端、搭数据库、写认证、配部署——一个 Demo 1 天能写完，变成能用的产品还要 2 周。

4.6.2 能力全景

Agent Plan 的 AI Native 开发底座基于火山引擎 Supabase 构建，给 Agent 一整套 Serverless 基础设施：

接入之后，Agent 可以直接用自然语言完成以前需要后端工程师干的活：

你：帮我建一张表叫 research_briefings，字段有 id、company、date、content、created_at，company 和 date 加联合索引。
Agent：[调用 Supabase API 建表] 建好了，SQL 如下：… 要不要加行级安全策略，让用户只能看自己的？
你：要，按 user_id 隔离。再写个边缘函数 /api/daily-summary 返回某公司最近 30 天的简报列表。
Agent：[5 秒后] 写完了，端点已部署到 https://你的项目.supabase-edge.app/api/daily-summary，我测了一下返回格式正常。

这就是"AI Native"的含义——整个应用的创建过程由 Agent 驱动，而不是人坐在 IDE 里敲代码。底座把底层复杂性全藏起来，Agent 和你只需要关注"做什么"，不用关心"怎么搭服务器"。

5. 四种运行模式横向对比

DSH 内置四种运行模式（Preset），对应不同场景。它们的本质是不同的插件组合配置——Cordis 内核根据 Profile 加载不同的插件集合，就呈现出不同的"模式"。

5.1 模式全景对比

5.2 Standard 标准模式：日常开发首选

定位：完整工具集的编码 Agent，覆盖 90% 的日常场景。

加载的核心插件：

适用场景：代码开发、重构、调试；文档撰写与整理；数据分析与报告生成；一般自动化任务。

5.3 Code 模式（PTC）：让模型自己写代码调工具

定位：在 Standard 基础上，把工具通过 Code Mode SDK 暴露给模型，让模型直接生成一段 TypeScript 程序来编排多轮工具调用。

打个比方：

• Standard 模式下：模型先想"我要读 A 文件 → 改 A 文件 → 读 B 文件 → 对比差异"，然后一步一步调用工具，每一步都是独立的 LLM 回合；
• Code 模式下：模型直接写一段 TS 代码，把这四步操作打包成一个函数，一次执行完，中间不需要再等 LLM 回合。

适用场景：批量操作大量文件（如批量重构、批量重命名）；工具调用之间有复杂条件分支和循环；对执行速度和 Token 效率敏感的任务。

5.4 Minimal 极简模式：基准测试专用

定位：只保留两个工具——持久化 bash 和 str_replace_editor（结构化文件编辑器），其他全部卸载。

为什么要这么"抠门"？因为做 LLM 编码能力基准测试时，希望不同模型在完全相同的工具集下公平对比。如果工具集太丰富（比如有高级 grep、有语义搜索），模型的"聪明程度"差异会被工具的"好用程度"掩盖。Minimal 模式就是为基准测试准备的"裸奔环境"。

适用场景：对比不同模型在相同任务上的编码能力；复现学术界编码 Benchmark（如 SWE-bench、HumanEval）；极低资源环境下使用。

5.5 Creator 创造模式：插件作者的实验台

定位：完整 Standard 能力 + 运行时检查 + 内存插件实验 + 预设编写指导。

这是给插件开发者和高级用户准备的模式。进入 Creator 模式后，你可以：

1. 检查当前运行时：查看哪些插件被加载了、它们暴露了哪些 Service、互相之间的依赖关系图；
2. 实验内存插件：写一个临时插件、不打包不安装，直接在运行时热加载，测完就丢；
3. 自定义 Preset：把自己常用的插件组合、模型配置、系统提示词模板，保存成一个新的 Preset（比如"我的投资研究模式"“我的前端开发模式”），下次一键切换；
4. 导出配置：把调好的 Preset 导出成 dsh.config.ts，分享给团队其他人，大家用同一套配置。

5.6 如何选择合适的模式

6. Web UI 操作全景

DSH 的 Web UI 是大多数用户的主入口。本章从界面布局到操作细节，完整走一遍。

6.1 界面布局总览

6.2 第一次使用四步走

Step 1：选择工作区

DSH 必须先选一个"工作目录"才能对话——这个目录就是 Agent 能"看到"和"操作"的文件边界。建议为不同项目建立不同工作目录，避免串台。

点击中间栏的「选择工作目录」按钮，选择一个空文件夹或已有项目文件夹。DSH 会：

• 建立 .dsh/ 子目录存放该工作区的配置和缓存；
• 把后续所有文件操作限制在这个目录内（除非你开了 Full Access 权限）。

Step 2：选择权限模式

左下角的盾牌图标是权限切换器，三级权限从安全到宽松：

⚠️ 安全建议：日常使用请停留在 Workspace Write。Full Access 模式下 Agent 理论上可以删除你硬盘上任意文件，谨慎使用。

Step 3：选择运行模式

中间栏顶部的下拉框，切换 Standard / Code / Minimal / Creator 四种模式（详见第 5 章）。新手建议用 Standard。

Step 4：发第一条消息

在输入框里输入任务描述，按回车发送。比如：

帮我分析一下这个项目的 README.md，用三句话告诉我它是做什么的、核心特性有哪些、怎么快速上手。

DSH 的执行过程会在右侧栏展开：

• 🧠 思考链：模型怎么拆解这个任务（默认折叠，点箭头展开）；
• 🔧 工具调用：调用了什么工具、传了什么参数、返回了什么结果（每一条可展开看详情）；
• 📋 审批弹窗：如果 Agent 想写文件或跑命令，会先让你点"确认"还是"拒绝"；
• ✅ 最终结果：任务完成后的回复。

6.3 审批流：高危操作前的安全闸

DSH 内置了操作审批流，不会让模型直接为所欲为。会触发审批的操作包括：

• 文件写入（Read Only 模式下所有写入；Workspace Write 模式下跨目录写入）；
• Shell 命令执行（Workspace Write 模式下默认全部审批；Full Access 下可配置自动放行）；
• 网络请求（非搜索插件的自定义 HTTP 调用）；
• 安装依赖 / 运行包管理器命令；
• 任何删除文件操作（无论什么权限模式，删除都会审批）。

审批弹窗会显示：操作类型、操作内容、Agent 理由，你的选项是：✅ 批准一次 / ✅✅ 批准所有同类操作（本次会话内） / ❌ 拒绝 / ⚠️ 拒绝并终止任务。

6.4 Trajectory 轨迹视图：回看不猜谜

做完一个复杂任务后，如果你想知道"Agent 到底是怎么一步步做出来的"，或者想定位"它在哪一步做错了"，切到 Trajectory 视图。

Trajectory 视图按时间顺序显示 Append-only 日志里的所有事件，支持：

• 按来源过滤：只看系统提示词 / 只看模型思考 / 只看工具调用 / 只看审批记录；
• 按关键词搜索：搜索文件名、函数名、具体参数；
• 时间轴跳转：点某个事件直接跳到对应消息位置；
• 导出轨迹：把完整事件流导出为 JSON，用于审计或 Bug 报告。

7. 实战案例：三天搭出投资研究助手

理论讲完了，我们通过一个完整实战案例把所有组件串起来。这个案例的素材来自独立开发者小曾的真实项目，他用 DSH + Agent Plan 用不到 3 天搭出了一个属于自己的投资研究助手。

7.1 需求分析：小曾到底想要什么

小曾是一名独立开发者，长期关注自己持有的几只股票。他的痛点是：

他的理想状态：每天早上起床，打开一个页面，三家公司的每日简报已经生成好了；点进去看详情，发现疑点可以继续追问 Agent；所有历史数据都存在自己的数据库里，随时可以统计分析。

7.2 架构设计：怎么把组件串起来

7.3 实施步骤详解

7.3.1 第一步：配置模型 + 五大组件

在 DSH 设置里完成以下配置（约 15 分钟）：

1. 模型：添加 Agent Plan 提供方，填入方舟 API Key；
2. 搜索：启用豆包搜索插件，开启"权威来源过滤" + “30 天时间范围”；
3. 数据：启用专业数据集插件，选择金融财经库 + 车型配置库；
4. 记忆：启用 OpenViking 记忆插件，初始化记忆目录结构；
5. 应用底座：启用 AI Native 开发底座，关联火山引擎 Supabase 项目。

7.3.2 第二步：给 DSH 第一个大任务

小曾给 DSH 的第一条任务描述写得很长——这是最佳实践，第一次任务描述越清晰，后面越省事：

我长期关注三家公司：比亚迪（002594.SZ / 1211.HK）、理想汽车（LI / 2015.HK）、蔚来（NIO / 9866.HK）。

帮我建立一套每日投资研究流程：

1. 数据采集：每天自动拉取这三家公司的：最新公告（交易所披露）；近 24 小时的新闻和行业动态（来源限定为权威财经媒体和公司官方渠道）；月初则更新上月全月销量数据；最近季度的核心财务指标（ROE / 毛利率 / 营收增速 / 净利润增速）。
2. 变化检测：对比昨天的数据和研究记录，找出值得关注的变化，标注重要程度（高/中/低），每一条变化必须有数据支持和来源引用。
3. 生成简报：每家公司一页研究简报，格式为"今日要点 → 数据详情 → 变化分析 → 后续关注"。三家公司汇总后生成一份总览。
4. 存储与通知：把每天的原始数据和简报都存在数据库里；如果有"高"重要程度的变化，通过微信通知我。
5. 可追问：以后我在对话里提到"比亚迪的简报"，你能调出历史记录；我问"为什么 7 月销量下滑"，你能结合历史数据回答。

我更关注：销量环比变化、毛利率变动趋势、新车型发布与交付节奏、管理层在业绩会上的指引变化。不需要做投资建议，只需要客观呈现事实和变化。

接下来请你：第一，把这套流程的实现方案列出来让我确认；第二，确认后自动搭建后端表、写调度函数、部署前端页面；第三，今天先手动跑一次，生成 8 月 20 日的简报。

这是一个很长的任务，但 DSH 的 Standard 模式支持多步规划——它会先把任务拆成 7-10 个子任务，列成 Todo 给你看，然后一项一项执行。

7.3.3 第三步：AI Native 底座发力，后端秒搭

DSH 拿到任务后，通过 AI Native 开发底座做了以下事情（全程自然语言驱动，小曾没写一行 SQL）：

1. 建表：在 Supabase PostgreSQL 里建了 4 张表：

   • companies（公司基本信息）
   • daily_raw_data（每天抓取的原始数据，JSON 字段存结构化内容）
   • research_briefings（每日研究简报，公司 × 日期唯一）
   • change_alerts（检测到的重要变化，带重要等级和引用）

2. 写边缘函数：写了三个 TypeScript 边缘函数：

   • fetch-daily-data：调用搜索 + 数据集插件，抓取当天数据并写入数据库；
   • generate-briefing：从数据库取当天原始数据，用大模型生成结构化简报；
   • detect-changes：对比今日与昨日数据，生成变化清单和通知。

3. 配定时调度：在 Supabase Edge Scheduler 里配了 Cron：

   • 每天 8:00 触发 fetch-daily-data；
   • 8:15 触发 detect-changes；
   • 8:30 触发 generate-briefing。

4. 写前端 + 部署：用 React + Vite 生成一个简单的单页应用，展示每日简报列表和详情。通过 git push 触发 Supabase Hosting 自动部署到全球 CDN。

整个过程从 DSH 开始执行到部署完成，大约 40 分钟——其中大模型思考和生成占了大头，底座的 API 调用都是毫秒级。小曾做的事情：中途审批了三次"写文件"和三次"执行部署命令"，每次点一下"确认"。

7.3.4 第四步：记忆系统上线，越用越懂你

助手用第一周后，发生了几个有趣的"学习"过程：

学习 1：自动记住关注点排序

头几天，小曾每次看到简报都吐槽"比亚迪的内容放最后？我最关心比亚迪"。到第 4 天，Evolve 组件弹出一条优化建议：

📝 建议修改：调整简报输出顺序
观察到的证据（5 次会话命中）：用户连续 4 次反馈比亚迪应该放前面。
建议 diff：在 CLAUDE.md 的投资研究偏好章节追加：“简报中公司顺序固定为：比亚迪 → 理想 → 蔚来，与用户持仓比重一致。”
风险：低（只是调整输出顺序，不影响数据逻辑）
置信度：98%

小曾点了"接受"，从那以后简报的公司顺序就对了。

学习 2：沉淀数据口径偏好

小曾发现 Agent 有时用"加权 ROE"有时用"摊薄 ROE"，手动纠正了两次。Evolve 第三次遇到时又弹了建议：

📝 建议修改：固化财务指标口径
观察到的证据：用户两次纠正 ROE 口径，要求统一用"扣非归母 + 加权平均"。
建议 diff：追加偏好声明，并在 skills/生成研究简报.md 中把所有财务指标的口径写成明确注释。
风险：低
置信度：92%

接受后，ROE 口径再也没乱过。

学习 3：从反复问答中沉淀 Skill

小曾经常问"XX 公司最近半年销量走势"——每次 Agent 都要重新查数据、重新组织回答格式。大概第 5 次问同样问题后，Evolve 建议：

📝 建议新增 Skill：生成半年销量走势分析
观察到的证据：近 7 天内相同模式的任务触发了 5 次，每次步骤高度雷同。
建议内容：把"查销量 → 算环比 → 画图 → 写点评"这套流程固化为 skills/半年销量走势.md，下次命中直接调用。
风险：低
置信度：95%

接受后，小曾再问同样问题，Agent 直接调 Skill，执行时间从 2 分钟降到 20 秒，Token 消耗下降约 60%。

7.4 效果复盘：3 天 vs 传统 3 周

小曾事后算了一笔账：

核心差距不在"能不能做出来"，而在"试错成本"——传统方案下，你花 3 周做出来发现思路不对，改方向又要 2 周；DSH 方案下，你半天就能跑一个最小闭环，发现方向不对推倒重来也就半天。这种"快速验证-快速迭代"的开发范式，就是 AI Native 开发底座真正的威力。

8. 插件开发从零起步

当开箱即用的组件不够用时，DSH 的插件生态就是你的扩展边界。本章用一个最小例子，带你走通"从 0 到 1 写一个插件"的完整流程。

8.1 Cordis 插件基础：一个插件就是一个 apply 函数

Cordis 插件系统的核心极简：一个插件就是一个导出了 apply 函数的 TypeScript 模块。apply 函数接收一个 ctx（上下文对象），你在里面注册能力、声明依赖、订阅事件。

最简单的 Hello World 插件：

// plugins/hello-world/index.ts
import { definePlugin } from '@cordis/loader'

export default definePlugin({
    name: 'hello-world',
    
    // 依赖哪些服务（可选）
    inject: {
        required: [],
        optional: ['model']
    },
    
    apply(ctx) {
        // 1. 注册一个 Service，其他插件可以通过 ctx.hello 访问
        ctx.provide('hello', {
            greet(name: string) {
                return `Hello, ${name}!`
            }
        })
        
        // 2. 注册一个 Tool，DSH 的 Agent 可以直接调用它
        ctx.tools.register({
            name: 'hello_greet',
            description: '向指定的人打招呼',
            schema: {
                name: { type: 'string', description: '要打招呼的人名' }
            },
            async execute({ name }) {
                return ctx.hello.greet(name)
            }
        })
        
        // 3. 订阅生命周期事件
        ctx.on('ready', () => {
            ctx.logger.info('hello-world 插件已加载')
        })
    }
})

就这么简单——没有复杂的基类继承，没有 XML 配置，没有注解魔法，一个 apply 函数就够了。

8.2 插件能做什么：七类扩展点

日常开发中，90% 的自定义插件集中在 Tool 扩展 和 Skill 扩展——这两类开发成本最低、收益最大。

8.3 实战：写一个"企业微信通知" Tool 插件

假设我们要给 DSH 加一个能力：Agent 完成重要任务时，通过企业微信机器人发消息通知你。一步步来。

Step 1：创建插件目录结构

my-plugins/
└── wecom-notify/
    ├── index.ts          # 插件主文件
    ├── package.json      # 依赖声明
    └── tsconfig.json

Step 2：写 package.json

{
  "name": "dsh-plugin-wecom-notify",
  "version": "0.1.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc"
  },
  "peerDependencies": {
    "@cordis/loader": "^0.1.0",
    "@deepseek-ai/dsh-core": "^0.1.0"
  },
  "dependencies": {
    "axios": "^1.7.0"
  }
}

Step 3：写插件主文件 index.ts

import { definePlugin } from '@cordis/loader'
import axios from 'axios'

/**
 * dsh-plugin-wecom-notify
 * 给 DSH 增加企业微信机器人通知能力
 */
export default definePlugin({
    name: 'wecom-notify',
    description: '企业微信机器人通知 Tool',
    
    // 可选依赖：如果有 logger 服务就用，没有就降级到 console
    inject: {
        optional: ['logger', 'config']
    },
    
    apply(ctx) {
        // 从配置中读取企业微信机器人 Webhook URL
        // 也支持通过环境变量 WECOM_WEBHOOK_URL 设置
        const getWebhookUrl = () => {
            return (ctx.config?.get?.('wecom.webhookUrl')) 
                || process.env.WECOM_WEBHOOK_URL
        }

        // 注册 Tool：Agent 在对话中可以调用这个工具
        ctx.tools.register({
            name: 'wecom_send_notification',
            description: `通过企业微信机器人发送通知消息。
当你完成了重要任务、检测到重要事件、或需要把结果推送给用户时，
可以调用这个工具发送消息到用户的企业微信。
必须在用户明确授权或任务要求通知时才使用，不要滥用。`,
            schema: {
                title: {
                    type: 'string',
                    description: '通知标题，不超过 32 字，必填',
                    required: true
                },
                content: {
                    type: 'string',
                    description: '通知正文，支持 Markdown，必填',
                    required: true
                },
                priority: {
                    type: 'string',
                    enum: ['normal', 'high', 'urgent'],
                    description: '优先级：normal 普通 / high 高 / urgent 紧急',
                    default: 'normal'
                }
            },
            async execute({ title, content, priority }) {
                const webhook = getWebhookUrl()
                if (!webhook) {
                    return {
                        success: false,
                        error: '未配置企业微信 Webhook URL。请设置环境变量 WECOM_WEBHOOK_URL 或在配置文件中添加 wecom.webhookUrl。'
                    }
                }

                // 根据优先级构造不同的 Markdown 样式
                const priorityTag = {
                    normal: '<font color="info">普通</font>',
                    high: '<font color="warning">高优</font>',
                    urgent: '<font color="comment">紧急</font>'
                }[priority!]
                
                const markdown = `### ${priorityTag} ${title}\n\n${content}`

                try {
                    const resp = await axios.post(webhook, {
                        msgtype: 'markdown',
                        markdown: { content: markdown }
                    })
                    
                    if (resp.data.errcode === 0) {
                        return {
                            success: true,
                            message: `通知已发送到企业微信，标题：${title}`
                        }
                    } else {
                        return {
                            success: false,
                            error: `企业微信 API 返回错误：${resp.data.errmsg}`
                        }
                    }
                } catch (e: any) {
                    return {
                        success: false,
                        error: `发送通知失败：${e.message}`
                    }
                }
            }
        })

        // 也对外暴露 Service，方便其他插件直接调用发通知
        ctx.provide('wecom', {
            sendNotification: async (params: {
                title: string
                content: string
                priority?: 'normal' | 'high' | 'urgent'
            }) => {
                // 复用上面 Tool 的实现逻辑（这里做简化演示）
                const tool = ctx.tools.lookup('wecom_send_notification')
                return tool?.execute(params)
            }
        })

        ctx.on('ready', () => {
            ctx.logger?.info?.('[wecom-notify] 插件加载完成')
        })
    }
})

Step 4：编译并加载到 DSH

cd my-plugins/wecom-notify
npm install
npm run build

然后在 DSH 的 Creator 模式下，把编译后的 dist/index.js 路径添加到配置的 plugins 数组中，或通过运行时热加载来测试。

Step 5：使用效果

加载完成后，你在对话里就可以说：

帮我分析一下比亚迪今天的新闻，如果有重大变化，生成简报并通过企业微信通知我。

Agent 在执行过程中，当它判断达到通知条件时，就会自动调用 wecom_send_notification 工具，把消息推到你的企业微信群里。

8.4 插件生态与资源

截至 2026 年 8 月，GitHub 上已有 8800+ 个带 dsh-plugin 标签的社区仓库。一些你可能感兴趣的方向：

9. 最佳实践与避坑速查

理论和案例都讲了，本章总结一些"社区踩过坑后沉淀的经验"——让你少走弯路。

9.1 任务描述的艺术：写好 Prompt 就成功了一半

DSH 的 Agent 虽然聪明，但"你说清楚了吗"直接决定结果质量。好的任务描述通常包含五个要素：

9.2 任务拆分：大任务不要一把梭哈

复杂任务直接扔给 Agent，结果很容易跑偏。拆成小步骤、每步确认，整体成功率会高很多。

9.3 文件操作安全：权限模式选择建议

黄金法则：永远用你能接受的最小权限。宁可多弹几次审批框点确认，也不要图省事开 Full Access 然后半夜后悔。

9.4 Token 成本优化：省下来的都是真金白银

模型调用按 Token 计费，几个小习惯每月能省不少钱：

1. 不用的会话及时关掉：每个新消息都会把整个会话历史重新发给模型，会话越长单次调用越贵。一个会话做到 30 轮以上，建议开新会话，手动把关键背景说一下就行。

2. 善用 Minimal 模式跑简单任务：只是改个文件里的字符串、跑个 Shell 命令，不需要搜索和 Skill——切到 Minimal 模式，System Prompt 更短，更省 Token。

3. 大文件不要让 Agent 全文读：给它具体行号或用 grep 先过滤。比如不要说"读 src/app.ts 看看有啥问题"，而要说"用 grep 搜 src/app.ts 里的 TODO 和 FIXME，把列出来的项逐一修复"。

4. 重复任务沉淀成 Skill：前一节案例里说过，同样的流程走了 5 次后沉淀成 Skill，单次 Token 消耗下降 60%——因为 System Prompt 里少了大量重复的"怎么干"的描述。

5. 用 Code 模式跑多步操作：如果一个任务需要连续 10 次工具调用，Standard 模式要 10+ 个 LLM 回合，Code 模式只要 1-2 个回合，Token 消耗差距可能是 3-5 倍。

9.5 常见坑位速查

10. 生态地图与未来路线

10.1 DSH 在 Agent 框架版图中的位置

DSH 的定位很清晰：不是和 Claude Code 比"开箱即用的体验"，而是给开发者一个可以自由重组的底座——你完全可以用 DSH 拼出一个比 Claude Code 更适合自己工作流的 Agent。

10.2 Agent Plan 的产品化路线

根据火山方舟公开 roadmap，Agent Plan 在 2026 年下半年到 2027 年有几个值得期待的方向：

10.3 更宏大的图景：从"辅助工具"到"数字员工"

把时间轴拉远来看，今天我们用 DSH 做的事情（写代码、做研究、生成报告），只是 Agent 落地的第一阶段。当 Harness 层的能力越来越完善，当工具链越来越丰富，当记忆和进化系统让 Agent 真的能"学"，Agent 的定位会从"辅助工具"演进到"数字员工"：

在这个演进过程中，Harness 层会是最大的价值蓄水池——因为模型越来越同质化（各家能力差距在缩小），而"怎么把模型和业务系统接起来、怎么让 Agent 稳定运行不出错、怎么从交互中沉淀知识"这些 Harness 层的问题，是每个行业、每个公司都不一样、需要长期积累的核心资产。

11. 高频问题 FAQ

Q1：DSH 和 Claude Code 是什么关系？我该选哪个？

A：定位不同。Claude Code 是 Anthropic 官方做的"成品型编码 Agent"，开箱即用、体验打磨得很细，但扩展能力受限于官方开放的接口。DSH 是 DeepSeek 开源的"框架型底座"，你可以自由替换模型、工具、UI、工作流，几乎没有上限，但需要自己组装。
建议：如果你是普通开发者，只是想"有个 AI 帮我写代码"，先试 Claude Code；如果你是高级开发者/团队技术负责人，想做深度定制、接入内部系统，或不喜欢被锁定在单一厂商，DSH 更值得投入。

Q2：DSH 只能用 DeepSeek 模型吗？

A：不是。DSH 名字里有 DeepSeek，但模型层完全是插件化的——官方默认支持 DeepSeek / Anthropic / OpenAI / Bedrock / Vertex / Azure / Codex 等多家厂商，也可以接任何 OpenAI 兼容端点。你甚至可以同时接多家模型，在 DSH 里按任务类型自动路由（简单任务用便宜的模型，复杂任务用强模型）。

Q3：Agent Plan 是免费的吗？

A：不是。Agent Plan 是火山方舟推出的订阅制产品包，包含模型额度 + 五大组件的使用权限。具体定价请参考火山方舟官网。
如果你不想付费，可以只用 DSH 开源框架本身（MIT 协议，100% 免费），然后自己去接各家的 API 和开源插件。DSH 和 Agent Plan 的关系就像"Android 系统是免费开源的，但你买预装了全套 GMS 和付费应用的手机需要花钱"。

Q4：我的数据安全吗？DSH 会不会上传我的代码？

A：DSH 默认是纯本地运行的——你的文件、会话日志、API Key 都存在你自己电脑的 ~/.dsh/ 目录下，框架本身不会上传任何数据到 DeepSeek 服务器。
唯一的网络通信是：1. 模型 API 调用（发给你配置的模型厂商的端点）；2. 你启用了网络搜索工具时，搜索请求发给搜索引擎；3. 你启用了 AI Native 开发底座时，数据发到你自己的 Supabase 项目。这些通信的目标方都是你主动配置的，DSH 不会偷偷发数据。
Agent Plan 组件中的数据处理请参考火山方舟的隐私政策和服务条款。

Q5：Windows 上能用 Python SDK 吗？

A：截至 v0.1 预览版，Python SDK 官方只支持 Linux x64/arm64 和 macOS 14+ arm64。Windows 用户如果需要 Python 集成，建议：1. 用 WSL2（Windows Subsystem for Linux）运行 Python SDK；2. 或者启动 DSH Web UI 后，通过 HTTP API 和它交互（DSH 本地有 REST 接口）。官方路线图里 Windows Python SDK 预计在 2026 Q4 支持。

Q6：Evolve 进化组件会不会改错我的指令文件？

A：不会"偷偷"改。Evolve 的设计是必须人工确认后才写入——它会把所有改动做成类似 GitHub Pull Request 的格式展示：改了哪几行、基于哪段会话证据、风险等级、置信度。你点"接受"才会写入 CLAUDE.md 或 Skill 文件，点"拒绝"就当无事发生。你也可以在设置里把 Evolve 调到"只建议不自动扫描"模式，完全手动触发。

Q7：插件开发有官方脚手架吗？

A：有。官方提供了 create-dsh-plugin 脚手架工具，一条命令生成完整的插件模板：

npm create @deepseek-ai/dsh-plugin@latest my-plugin
cd my-plugin
pnpm install
pnpm dev   # 自动热加载到本地 DSH 实例

模板包含 TypeScript 配置、构建脚本、测试用例、示例 Tool 和 Service。

Q8：团队协作怎么做？多人共用一套 Agent 配置。

A：三种方式任选：

1. 导出/导入配置：Creator 模式下把调好的 Preset 导出成 dsh.config.ts，提交到 Git，团队其他人 clone 下来导入；
2. 共享记忆目录：把 Agent Plan 记忆系统的 VFS 目录放在共享盘或 Git 仓库里，团队成员的 DSH 都指向同一个目录；
3. 等 2026 Q4 的团队协作版：Agent Plan 团队版会支持多人共享记忆、共享 Skill、统一权限管理。

12. 附录：术语表与参考资料

12.1 核心参考链接

12.2 术语表

12.3 文档版本与贡献说明

• 文档版本：v1.1（重写版，2026-08-21）
• 适用 DSH 版本：v0.1 开发者预览版
• 更新说明：由于 DSH 仍处于快速迭代的预览阶段，官方可能随时引入破坏性变更。建议实际操作前先对照官方最新文档确认 API 细节。

写在最后
DSH 和 Agent Plan 这套组合，最打动我的不是它今天已经有多完美（事实上预览阶段还有很多粗糙的地方），而是它背后的理念——把"造 Agent"这件事的门槛，从"需要一个团队开发半年"降到了"一个开发者花三天就能搭出一个能用的产品"。
三年前，做一个 AI 应用意味着你要懂模型部署、懂向量数据库、懂前后端、懂 DevOps；今天，你只需要想清楚"我要解决什么问题"，然后把模型、工具、记忆、底座像乐高积木一样拼起来。
最好的学习方式永远是"动手做"。花 10 分钟把 DSH 跑起来，给它一个你真实工作中遇到的任务——哪怕只是整理一份会议纪要、批量重命名一堆照片。你会发现，所谓"智能体"，其实离你没那么远。
祝玩得开心。