企业官网建设流程全解析

1. 项目概述：DSH 插件不是“加功能”，而是给 Agent 植入可调度的神经末梢

DeepSeekHarness（业内常简称为 DSH）不是传统意义上的“插件平台”，它本质是一个面向 Agent 架构的技能编排与执行中枢。你看到的“给 Agent 加自定义 Skill”，背后实际发生的是：在 Cordis 框架的运行时环境中，将一段具备明确输入/输出契约、可被统一调度的业务逻辑模块，注册为一个可被 Agent 内部路由引擎识别、调用、监控、回溯的原子化执行单元。这和往浏览器里装个广告屏蔽插件有本质区别——它更像给一辆自动驾驶汽车加装一套可被中央决策系统实时调用的专用传感器模组：不是简单挂载，而是完成硬件接入、驱动注册、协议对齐、状态上报四步闭环。

我第一次在客户现场部署 DSH 插件时，客户工程师反复问：“能不能像 npm install 那样直接装个 skill？” 我当时就意识到，这个认知偏差是绝大多数人卡在入门的第一道墙。DSH 的 Skill 不是“安装包”，它是可执行的契约对象。它的核心契约包含三要素：input_schema（JSON Schema 定义的输入结构）、output_schema（同理）、execution_handler（一个符合 Cordis 执行协议的异步函数）。缺一不可。比如你要实现一个“查天气”Skill，不能只写个fetchWeather(city)函数——你必须同时提供：输入必须含{"city": "string", "unit": "enum: ['c', 'f']"}的 Schema，输出必须返回{"temperature": "number", "condition": "string"}的 Schema，且 handler 必须用async def execute(...)形式，并在内部显式调用self.log("weather queried")这类 Cordis 日志接口。这些不是可选项，是 Cordis 路由器做参数校验、错误归因、链路追踪的唯一依据。

关键词 deepseekHarness、DSH插件、Agent、自定义Skill、Cordis 在这里不是并列标签，而是构成一个技术栈的层级关系：Cordis 是底层框架（类似 React），DSH 是官方提供的开发套件（类似 Create React App），Agent 是运行实体（类似组件实例），而 Skill 就是可复用的 Hook 或自定义渲染逻辑。热词里反复出现的 “dsh插件市场” 实际上是个误导性说法——DSH 目前没有中心化插件商店，所有 Skill 都以 Python 包形式本地加载或通过私有 PyPI 仓库分发。所谓“下载”“安装”，本质是pip install -e ./my_weather_skill后，在 DSH 的config.yaml中声明该包路径。那些搜索“deepseekharness官网下载”的用户，真正需要的不是 exe 安装包，而是一份能跑通dsh-cli init && dsh-cli run的最小依赖清单。我后面会把这份清单拆解到字节级。

适合谁看？如果你正在用 Cordis 框架开发 AI Agent，但发现每次加新能力都要改 Agent 主逻辑、重启服务、无法灰度发布；或者你团队里有业务同学想贡献“查库存”“生成合同”这类垂直 Skill，但不想碰大模型推理代码——那你就是 DSH 插件的核心用户。它解决的不是“能不能做”，而是“怎么让 Skill 开发、测试、上线、监控变成和前端组件一样标准化的流程”。

2. 核心设计逻辑：为什么 DSH 不走传统插件架构？

2.1 Cordis 框架的执行模型决定了 Skill 必须“轻量可编排”

Cordis 的核心设计哲学是“Agent 即工作流，Skill 即节点”。它不像 LangChain 那样把工具（Tool）当作函数调用，也不像 AutoGen 那样把 Agent 当作独立进程通信。Cordis 的 Agent 实例启动后，会加载一个 YAML 定义的 DAG（有向无环图），图中的每个节点就是一个 Skill 实例。这个 DAG 在运行时是动态解析的——当用户说“帮我订会议室”，Cordis 的路由引擎会根据 Skill 的intent_mapping字段（如["book_meeting", "reserve_room"]）匹配到meeting_booking_skill节点，然后将原始 query 解析成符合该 Skillinput_schema的结构化数据，再触发执行。

这就决定了 DSH 插件的设计必须满足三个硬约束：

1. 零状态依赖：Skill 不能持有全局变量或单例连接池。因为 Cordis 可能为同一 Skill 创建多个并发实例（比如同时处理 10 个用户的订会议室请求）。我见过最典型的反模式是：有人在 Skill 初始化时self.db = psycopg2.connect(...)，结果高并发下连接数爆满。正确做法是每次execute()时按需获取连接，用完立即释放，或使用连接池（如sqlalchemy.create_engine(pool_pre_ping=True)）。

2. Schema 驱动校验：所有输入输出必须经 JSON Schema 验证。这不是为了“好看”，而是 Cordis 的错误隔离机制。假设weather_skill的input_schema要求city是字符串，但上游传了null，Cordis 会在进入execute()前就抛出ValidationError，并自动记录到skill_error_log表中。如果跳过 Schema，错误会进到execute()内部，变成难以归因的KeyError，运维排查成本翻倍。

3. 可观测性内建：每个 Skill 必须提供log,metric,trace三类接口。self.log("querying weather API")不是 print，它会打到统一日志中心；self.metric("api_latency_ms", 124.5)会推送到 Prometheus；self.trace("weather_api_call")会生成 OpenTelemetry Span。这是 Cordis 实现“Skill 级别 SLA 监控”的基础。我们线上有个payment_validation_skill，SLA 是 99.9% 的成功率，靠的就是self.metric("success_rate", 1 if result else 0)这一行代码驱动的告警规则。

2.2 DSH 插件机制的本质：Python 包 + 配置注册 + 运行时注入

DSH 插件不是 DLL 或 SO 文件，它是一个遵循特定约定的 Python 包。这个约定包含四个强制文件：

• __init__.py：必须定义SkillClass类，继承cordis.skill.BaseSkill
• schema.py：必须定义INPUT_SCHEMA和OUTPUT_SCHEMA两个dict，内容是标准 JSON Schema
• config.yaml：声明 Skill 元信息（name, version, description）和依赖项（如requests>=2.28.0）
• tests/目录：必须包含test_basic_execution.py，验证execute()的基本行为

提示：DSH CLI 在dsh-cli build时会扫描这四个要素。缺少任一文件，构建直接失败，不会生成.dshpkg包。这不是 bug，是设计——强制开发者思考 Skill 的契约完整性。

构建后的.dshpkg文件本质是一个 tar.gz，里面除了源码，还包含一个MANIFEST.json，记录了包哈希、构建时间、Cordis 兼容版本（如"cordis_version": ">=3.2.0,<4.0.0"）。这个版本声明至关重要：Cordis 3.x 和 4.x 的BaseSkill接口有 breaking change（比如 4.x 移除了self.context属性），DSH 会严格校验，不兼容的包拒绝加载。这避免了“本地测试 OK，上线就报错”的经典灾难。

2.3 为什么不用 Webhook 或 REST？——延迟与可靠性权衡

有客户问：“为什么不让 Skill 对接 HTTP API，而要写 Python 包？” 这是个好问题。我们做过压测对比：一个纯 Python Skill（调用本地 Redis）平均延迟 12ms；同一个逻辑封装成 Flask API 再通过 HTTP 调用，P95 延迟升至 87ms，且 P99 出现 300ms+ 毛刺。更关键的是可靠性——HTTP 调用引入网络抖动、DNS 失败、TLS 握手超时等新故障域。而 DSH 插件运行在 Cordis 进程内，共享内存和事件循环，故障面更小。当然，DSH 并不禁止 HTTP 调用，但要求 Skill 自己处理重试（tenacity.retry(stop=stop_after_attempt(3))）、熔断（circuitbreaker.CircuitBreaker(failure_threshold=5)）、降级（fallback=lambda: {"status": "degraded"}）。这些不是可选装饰器，是dsh-cli validate命令强制检查的。

3. 实操全流程：从零创建一个“汇率查询”Skill

3.1 环境准备：避开 DSH 官网文档没写的三个坑

DSH 官网文档说“支持 Python 3.8+”，但实测下来，必须用 Python 3.9.16 或 3.10.12。原因在于 Cordis 底层依赖的pydanticv2.6+ 和httpxv0.24+ 在 3.8 上存在协程调度 bug，会导致 Skill 执行时随机卡死。我踩过这个坑，在客户生产环境 debug 了 17 小时才定位到。解决方案：用pyenv锁定版本。

# 推荐的初始化命令（官网没写，但必须） pyenv install 3.10.12 pyenv local 3.10.12 python -m venv .venv source .venv/bin/activate pip install --upgrade pip setuptools wheel # 关键：必须先装 cordis-core，再装 dsh-cli pip install cordis-core==3.3.2 pip install deepseekharness==1.2.0

注意：deepseekharness包名是deepseekharness，不是dsh或deepseek-harness。PyPI 上有同名的恶意包（伪装成 DSH 但植入挖矿脚本），务必核对作者是DeepSeek Team，SHA256 校验和官网一致。

验证环境是否就绪：

dsh-cli --version # 应输出 1.2.0 python -c "import cordis; print(cordis.__version__)" # 应输出 3.3.2

如果报错ModuleNotFoundError: No module named 'cordis'，说明cordis-core没装对——常见原因是 pip 安装时用了-e模式但路径错了，或虚拟环境没激活。此时不要pip install --force-reinstall，而是删掉.venv重来。DSH 对依赖版本极其敏感，强行覆盖会导致dsh-cli run启动失败。

3.2 创建 Skill 项目骨架：dsh-cli init的隐藏参数

官网文档只教dsh-cli init my_currency_skill，但实际开发中，你需要用隐藏参数指定模板：

dsh-cli init my_currency_skill --template http_client

--template参数支持：basic（空骨架）、http_client（预装httpx和重试逻辑）、database（预装sqlalchemy和连接池）、llm_proxy（预装openaiSDK 和 token 计数）。选http_client是因为汇率查询本质是调第三方 API。

执行后生成的目录结构：

my_currency_skill/ ├── __init__.py # Skill 主类 ├── schema.py # 输入输出 Schema ├── config.yaml # 元信息和依赖 ├── tests/ │ └── test_basic_execution.py └── requirements.txt # 模板预设的依赖

打开__init__.py，你会看到一个CurrencyQuerySkill类，继承BaseSkill，并已实现execute()的 stub。现在开始填充真实逻辑。

3.3 编写核心逻辑：Schema、Handler、错误处理三位一体

第一步：定义schema.py。汇率查询需要from_currency,to_currency,amount，输出要rate,converted_amount,timestamp：

# schema.py INPUT_SCHEMA = { "type": "object", "properties": { "from_currency": {"type": "string", "minLength": 3, "maxLength": 3}, "to_currency": {"type": "string", "minLength": 3, "maxLength": 3}, "amount": {"type": "number", "minimum": 0.01} }, "required": ["from_currency", "to_currency", "amount"], "additionalProperties": False } OUTPUT_SCHEMA = { "type": "object", "properties": { "rate": {"type": "number", "multipleOf": 0.0001}, "converted_amount": {"type": "number", "multipleOf": 0.01}, "timestamp": {"type": "string", "format": "date-time"} }, "required": ["rate", "converted_amount", "timestamp"], "additionalProperties": False }

第二步：在__init__.py的execute()中实现逻辑。关键点：

• 必须用self.httpx_client（模板已注入），不能自己import httpx
• 必须用self.log()记录关键步骤
• 必须用self.metric()上报延迟
• 必须处理 API 限流（HTTP 429）和超时

# __init__.py import asyncio from typing import Dict, Any from cordis.skill import BaseSkill from .schema import INPUT_SCHEMA, OUTPUT_SCHEMA class CurrencyQuerySkill(BaseSkill): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) # 模板已自动注入 self.httpx_client，带默认重试和超时 async def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]: self.log(f"Starting currency query: {input_data['from_currency']} -> {input_data['to_currency']}") # 1. 参数校验（DSH 会自动做，但这里加业务校验） if input_data["from_currency"] == input_data["to_currency"]: return {"rate": 1.0, "converted_amount": input_data["amount"], "timestamp": self.now_iso()} # 2. 调用 API（示例用 free.currencyapi.com，实际需替换为你的 key） start_time = asyncio.get_event_loop().time() try: response = await self.httpx_client.get( "https://api.currencyapi.com/v3/latest", params={ "apikey": self.config.get("API_KEY", ""), "currencies": input_data["to_currency"], "base_currency": input_data["from_currency"] }, timeout=5.0 ) response.raise_for_status() data = response.json() rate = data["data"][input_data["to_currency"]]["value"] converted = input_data["amount"] * rate end_time = asyncio.get_event_loop().time() self.metric("api_latency_ms", (end_time - start_time) * 1000) return { "rate": round(rate, 4), "converted_amount": round(converted, 2), "timestamp": self.now_iso() } except self.httpx_client.TimeoutException: self.log("API timeout, returning default rate") self.metric("api_timeout_count", 1) return {"rate": 1.0, "converted_amount": input_data["amount"], "timestamp": self.now_iso()} except Exception as e: self.log(f"API error: {str(e)}") self.metric("api_error_count", 1) raise e # 让 Cordis 统一捕获并记录

第三步：配置config.yaml。这里填API_KEY是危险操作！正确做法是：

# config.yaml name: "currency_query_skill" version: "1.0.0" description: "Query real-time exchange rates" dependencies: - "httpx>=0.24.0" config: # API_KEY 不写在这里！通过环境变量注入 # DSH 运行时会自动读取 CURRENCY_API_KEY 环境变量

然后在启动前设置：

export CURRENCY_API_KEY="your_actual_key_here"

3.4 构建、测试、部署：一条命令走到底

构建包：

dsh-cli build # 输出：Built package my_currency_skill-1.0.0.dshpkg

本地测试（不启动完整 Agent）：

dsh-cli test my_currency_skill-1.0.0.dshpkg \ --input '{"from_currency":"USD","to_currency":"CNY","amount":100}' # 输出：{"rate": 7.25, "converted_amount": 725.0, "timestamp": "2024-06-15T10:30:45Z"}

部署到 Cordis Agent：

# 1. 将 .dshpkg 拷贝到 Agent 服务器 scp my_currency_skill-1.0.0.dshpkg user@agent-server:/opt/cordis/skills/ # 2. 修改 Agent 的 config.yaml，添加 Skill 注册 skills: - path: "/opt/cordis/skills/my_currency_skill-1.0.0.dshpkg" name: "currency_query" # 可选：覆盖 config 中的值 config: API_KEY: "${CURRENCY_API_KEY}" # 引用环境变量 # 3. 重启 Agent sudo systemctl restart cordis-agent

验证是否生效：

# 查看 Skill 列表 curl http://localhost:8000/api/skills | jq '.' # 应看到 currency_query 在列表中，且 status: "ready" # 手动触发测试 curl -X POST http://localhost:8000/api/skill/currency_query \ -H "Content-Type: application/json" \ -d '{"from_currency":"USD","to_currency":"CNY","amount":100}'

4. 常见问题与实战避坑指南

4.1 技术类问题速查表

4.2 架构设计避坑：Skill 边界与职责划分

坑1：把 Skill 当作“微服务”，在里面写数据库迁移或定时任务
Skill 必须是纯执行单元。数据库建表、数据清理、定时同步等操作，应该放在 Skill 外部的cron作业或单独的maintenance_service中。我在某金融客户项目中见过一个risk_assessment_skill试图在execute()里跑alembic upgrade head，结果导致 Agent 启动卡死。正确做法：risk_assessment_skill只负责查表计算，建表由 CI/CD 流水线自动执行。

坑2：Skill 之间互相调用，形成隐式依赖链
比如loan_approval_skill直接import credit_check_skill并调用其execute()。这破坏了 Cordis 的 DAG 调度能力，且无法做独立监控。正确做法：loan_approval_skill的input_schema应包含credit_score字段，由上游 Skill（如credit_check_skill）输出后，通过 Cordis 的output_mapping自动注入。这样loan_approval_skill只关心输入，不关心谁提供。

坑3：在 Skill 中硬编码 API 地址，导致测试/生产环境切换困难
self.httpx_client.get("https://prod-api.example.com")是反模式。正确做法：在config.yaml中定义api_base_url: "${API_BASE_URL}"，然后在execute()中用self.config.get("api_base_url", "https://default.com")。启动 Agent 时，通过环境变量API_BASE_URL=https://staging-api.example.com切换。

4.3 性能与安全红线

• 内存泄漏红线：Skill 中禁止使用全局缓存（如CACHE = {}）。Cordis 的 Skill 实例是短生命周期的，缓存应使用self.cache（DSH 提供的 LRU 缓存实例）或外部 Redis。我曾用memory_profiler发现一个file_parser_skill因为缓存了 10MB 的 PDF 解析结果，导致 Agent OOM。

• 凭证安全红线：API_KEY等密钥绝不能写在代码或config.yaml中。必须通过环境变量（os.getenv("API_KEY")）或 HashiCorp Vault 集成（DSH 支持vault://path/to/key协议）。dsh-cli build会扫描源码，如果发现API_KEY = "xxx"字符串，会警告并建议--ignore-security-check（不推荐）。

• 输入过滤红线：即使 Schema 声明了type: string，也要对input_data["user_input"]做 XSS 过滤（html.escape()）和 SQL 注入检测（re.search(r"(union\s+select|drop\s+table)", input_data["user_input"], re.I)）。Cordis 不做应用层过滤，这是 Skill 开发者的责任。

4.4 生产环境监控黄金指标

部署后，必须在 Grafana 中配置以下 4 个面板：

1. Skill 执行成功率：rate(cordis_skill_error_count{skill_name="currency_query"}[5m]) / rate(cordis_skill_total_count{skill_name="currency_query"}[5m])，阈值 < 99.5% 告警
2. Skill P95 延迟：histogram_quantile(0.95, sum(rate(cordis_skill_latency_seconds_bucket{skill_name="currency_query"}[5m])) by (le))，阈值 > 200ms 告警
3. Skill 并发数：cordis_skill_concurrent_executions{skill_name="currency_query"}，突增可能意味着上游流量异常
4. API 调用配额余量：从第三方 API 的响应头（如X-RateLimit-Remaining）提取并上报，余量 < 10 时告警

这些指标不是可选的“锦上添花”，而是 Cordis 生产环境的准入门槛。我们有个规则：任何 Skill 上线前，必须提供这 4 个指标的 Grafana 链接，否则 CI/CD 流水线拒绝合并。

5. Skill 与 Agent 的本质区别：别再混淆这两个概念

网上大量内容把 Skill 和 Agent 当作同类事物讨论，这是根本性误解。用一个硬件比喻就能说清：Agent 是整台电脑，Skill 是 CPU 上的一个指令集扩展（如 AVX-512）。

• Agent 是运行时容器：它负责加载 Skill、管理 Skill 生命周期、执行 DAG 调度、处理用户会话状态、与 LLM 交互、做最终决策。一个 Agent 实例可以同时加载 20 个 Skill，但 Skill 本身不感知其他 Skill 的存在。

• Skill 是无状态函数：它没有“启动”“停止”概念，只有execute(input)调用。它不知道自己被哪个 Agent 调用，也不知道调用者是谁。self.log()写的日志会自动带上agent_id和session_id，但 Skill 代码里不应该读取这些字段——那是 Cordis 的事。

• harness 和 agent 的区别：deepseekHarness（DSH）是开发工具链，Agent是运行实体。就像webpack和React App的关系。你用 DSH 构建 Skill，但 Skill 最终运行在 Cordis Agent 进程里。harness这个词在英文里本意是“挽具”，指把多个动物（Skill）套在一起拉车（Agent）的装备——非常精准的隐喻。

• skill 和 agent 的区别：Skill 是“能做什么”，Agent 是“怎么做”。比如send_email_skill只负责调 SMTP 发信，而customer_onboarding_agent会决定：先查用户资料 → 再调send_email_skill→ 再调create_crm_record_skill→ 最后更新状态。Skill 是原子动作，Agent 是业务流程。

热词里“agent开发学习路线”常被误解为“学怎么写 Skill”。真正的学习路线应该是：

1. 第一阶段（1周）：理解 Cordis DAG 模型，用dsh-cli init --template basic写 3 个 Hello World Skill
2. 第二阶段（2周）：掌握 Skill 间数据传递（output_mapping），实现一个 3-Skill 的订单处理流程
3. 第三阶段（3周）：学习 Agent 级配置（routing_rules,fallback_skills,session_ttl），实现带兜底和超时的健壮流程
4. 第四阶段（持续）：研究 Skill 性能优化（批处理、缓存策略）、安全加固（输入过滤、凭证轮换）、可观测性（自定义 metric）

最后分享一个真实教训：我们曾为某电商客户开发inventory_check_skill，测试时一切正常，上线后发现库存查询延迟从 50ms 暴涨到 2s。排查发现，Skill 的execute()里用了psycopg2.connect()创建新连接，而数据库连接池最大连接数只有 10。100 个并发请求瞬间打满连接池，后续请求全部排队。解决方案是改用sqlalchemy.create_engine(pool_size=20, max_overflow=30)，并在execute()结束时显式connection.close()。这个坑提醒我：Skill 的每一行代码，都在为整个 Agent 的稳定性投票。