第 11 章 生态、坑与 FAQ：少走弯路
11.1 生态现状：你正站在起跑线上
发布两天，GitHub Star 突破 10 万（据公开报道），dsh-plugin 话题下的插件仓库 24 小时内就攒到 288 个。社区里已经能看到这些方向的插件：
•
UI 与体验：浏览器式会话标签页、使用量仪表盘、会话管理；
•
能力扩展：技能（skill）插件、MCP 服务器插件、安全审计技能包；
•
垂直场景：可视化、PPT、编码、游戏开发（如 Godot）、自动研究循环（Loops）；
•
迁移与集成：从 Claude Code、Codex 迁移配置的工具，用量计费、绿电计量等。
官方社区入口：
•
GitHub Discussions：反馈与讨论；
•
Discord：官方社区；
•
企微群 + 微信公众号：官方 README 里有二维码；
•
插件发现：给仓库打 dsh-plugin 话题，方便被发现。
对你意味着什么：现在做插件，竞争者少、被看到概率大；而且生态刚起步，缺什么插件，你就有机会补什么。
11.2 必须知道的坑
坑 1：开发者预览版，兼容性会变
官方原话：正在快速迭代，未来将出现破坏兼容性的变更。对策：
•
生产环境锁定版本（全局安装固定版本，不要天天 npx 最新）；
•
升级前看官方 Release 说明和迁移文档；
•
你的插件别依赖"恰好能用的内部细节"，优先用文档化扩展点。
坑 2：Python SDK 暂不支持 Windows
官方示例的持久 PTY 后端需要 POSIX 环境。Windows 用户用 WSL、Linux 服务器或容器。
坑 3：git 安装插件的 prepare 坑
从 GitHub 装 TypeScript 插件时，没有构建产物会加载失败；pnpm ≥10 默认拒绝运行 prepare 脚本。对策在第 8 章：作者给 prepare，用户显式 allowBuilds。只对可信源码授权。
坑 4：危险的全权限
SDK 最小示例和某些组合默认 danger-full-access：Bash 和编辑器能改任何路径。永远在可丢弃的环境里跑，或换上严格的沙箱策略。
坑 5：Key 管理
API Key 在 Web UI 里是只写的（存 $DSH_HOME/.credentials.yaml）。但脚本和 CI 里，别把 Key 写进代码或提交到 git，用环境变量或密钥服务。
坑 6：模型与推理档位
DeepSeek 适配器默认路由是 deepseek-official，默认模型 deepseek-v4-flash / deepseek-v4-pro，默认上下文窗口 100 万 token，输出上限默认 256,000 token，推理档位 off | high | max（默认 high，thinking 默认开启）。需要按部署调这些时，改配置而不是改代码。
11.3 FAQ 十问
Q1：没有 API Key 能玩吗？
能启动界面，但不能跑任务。Key 从 DeepSeek 开放平台申请。
Q2：MISSING_CREDENTIAL 是什么？
模型路由没配好凭据：去设置里存 Key，或提供被引用的环境变量。
Q3：UNKNOWN_MODEL 怎么办？
选择已配置的模型；自定义提供方则需要添加缺失的模型。
Q4：端口被占用了？
dsh web --port 8080（--port 是 web 应用的参数，放在 dsh 自己的参数之后）。
Q5：能接别的模型吗？
能。设置里可添加 Anthropic、OpenAI 等目录提供方，或自定义 OpenAI 兼容端点。自定义提供方的 Provider ID 是永久的，改名要新建再删除。
Q6：自定义提供方的视觉模型不认图片？
手动录入的模型默认按纯文本处理；在 $DSH_HOME/settings.yaml 给该模型加 input: [text, image]。
Q7：插件改了配置没生效？
配置变更会触发热重载；但 patch 是整行替换 config，检查你是否重述了目标行的所有键。
Q8：日志在哪？
会话日志是 JSONL（Python SDK 场景在 session_root 下）；Key 在 $DSH_HOME/.credentials.yaml；机器级配置在 $DSH_HOME/cordis.patch.yml。
Q9：Windows 能跑 Web UI 吗？
能，Web UI 和源码构建在 Windows 没问题；受限制的是 Python SDK 官方示例。
Q10：想给官方提反馈？
GitHub Discussions；给插件仓库加 dsh-plugin 话题提升被发现概率。
11.4 本章小结
•
生态刚起步，插件方向多、竞争者少，是入局的好时机；
•
预览版的三件事：锁版本、看迁移、用文档化扩展点；
•
安全三红线：可信源码才授权、危险全权限只在隔离环境、Key 绝不进 git。
最后一章，给你一张继续深入的地图。