GitHub 项目导读：DeepSeek Harness 开源生态与学习路径
按 7 天学会 DeepSeek Harness 每日实验卡阅读对应仓库目录，在 插件社区 对照示例插件。
导读：为何要学会「读仓库」
DeepSeek Harness 的能力以 Cordis 插件 + Bundle 配置 形式分布在多个 GitHub 仓库中。只会 npm install 而不读源码，遇到以下问题时仍会束手无策：某工具在 Minimal 可用、Standard 不可用——需查 Preset 依赖哪几个官方插件；审批策略与文档描述不一致——需追 approval 服务实现在哪个包；想贡献社区插件——需对齐 manifest、peerDependencies 与 CI 模板。
本文提供 可复用的读仓库方法论、官方与生态对照表、贡献与路线图管理建议，并给出 Fork 实验工作流，帮助你在开源世界中持续积累 Agent 运行时工程能力。
第一章：官方 仓库 deepseek-ai/deepseek-harness
1.1 仓库定位
| 维度 | 说明 |
|---|---|
| 组织 | deepseek-ai |
| 许可证 | 以仓库 LICENSE 为准（阅读时确认） |
| 问题追踪 | GitHub Issues / Discussions |
| 发布 | GitHub Releases + npm 包（若提供） |
主仓库是 单一事实来源（SSOT） for 架构决策、官方插件实现、CLI 与文档。社区插件应 peer 依赖 主仓库发布的 runtime，而非 fork 并改内核。
1.2 推荐阅读顺序
- README.md：30 秒认知 + 快速启动命令
- docs/architecture.md（或
docs/architecture/）：三平面、无特权核心、Session 模型 - AGENTS.md：Agent 行为约定、工具调用规范、对贡献者的设计意图
- CONTRIBUTING.md：分支策略、commit 规范、CI 要求
- packages/ 或 plugins/：按你关心的服务（tools / sessions）深入
- examples/：最小 Bundle 与插件样板
1.3 目录结构如何读
典型 monorepo 布局（名称以实际仓库为准）：
| 路径 | 关注点 |
|---|---|
packages/cordis-* | 插件内核、类型定义 |
packages/dsh-* | Host、CLI、官方插件 |
packages/client-* | Web UI 与 Client 槽位 |
docs/ | 架构、ADR、迁移指南 |
examples/bundles/ | Profile / Patch 范例 |
scripts/ | 发布与 codegen |
.github/workflows/ | CI 矩阵、发布流水线 |
读代码技巧：
- 从
apply(ctx)全局搜索入口，而非从main.ts线性读 - 用 GitHub Code Search：
repo:deepseek-ai/deepseek-harness ctx.provide - 对照类型定义文件（
*.d.ts）理解服务键命名空间
1.4 docs/architecture 深度阅读笔记
阅读架构文档时，建议自建对照表：
| 架构概念 | 代码锚点 | 插件扩展点 |
|---|---|---|
| 三平面 Host/Preset/Client | host 启动流程 | Bundle 配置 |
| Session Log | sessions 包 | 压缩插件 |
| 工具管道 | tools + sandbox | register tool |
| 审批 | approval | registerPolicy |
| MCP | mcp-client 插件 | 外部 server |
架构文档中的 无特权核心 含义：任何能力都应能通过插件卸载；内核不应硬编码业务工具。读 Issue 时若提议「把某工具写进内核」，应对照此原则判断合理性。
1.5 Issue 礼仪
| 场景 | 建议 |
|---|---|
| Bug | 提供 Host 版本、Bundle、复现 Session ID、期望/实际 |
| Feature | 说明用例、安全影响、是否可插件化 |
| 提问 | 先搜 Discussions；附最小复现 |
| 安全 | 走私下披露流程（见 SECURITY.md） |
高质量 Issue 模板要素：
## 环境
- dsh / runtime 版本：
- 预设：Standard / Code / ...
- OS：
## 复现步骤
1.
2.
## 期望行为
## 实际行为
## 日志 / Session ID（可打码）
1.6 Pull Request 礼仪
- 单一职责：一个 PR 解决一个问题；插件与内核分 PR
- 测试：包含 mount/unmount 或工具 golden test
- 文档：用户可见行为变更必须更新 docs/
- 兼容性：注明 peerDependencies 与迁移步骤
- Review 响应：48h 内回复 review comment；rebase 保持线性历史（若仓库要求）
避免 巨型 PR（>500 行无测试）——在 Agent 运行时项目中，Review 者需要验证 Effect Teardown 与审批边界，大 diff 几乎不可审。
第二章：Cordis 与相关生态仓库对照学习
2.1 Cordis 内核
Cordis 是 Harness 的 插件与 DI 内核。学习路径：
- 阅读
ctx.effect实现与 Teardown 栈 - 阅读依赖图解析（deps / inject）
- 对比其他 DI：NestJS Module、VS Code Extension Host
| 学习问题 | 在源码中寻找 |
|---|---|
| 插件排序 | topological sort |
| 作用域 | scope / child ctx |
| 热重载 | reload lifecycle |
2.2 官方插件包
建议 逐个 clone 插件包 并跑单测，而非只读 monorepo 根目录：
| 插件域 | 学习价值 |
|---|---|
| tools | Schema 注册范例 |
| llm | Provider 路由 |
| sessions | 事件溯源 |
| sandbox | 安全边界 |
| mcp | 外部协议桥接 |
2.3 与 MCP 官方 SDK 对照
| 项目 | 仓库 | 与 DSH 关系 |
|---|---|---|
| MCP TypeScript SDK | modelcontextprotocol/typescript-sdk | DSH 作 MCP Client |
| MCP Python SDK | modelcontextprotocol/python-sdk | 写 MCP Server 供 DSH 调 |
| MCP 规范 | modelcontextprotocol/specification | 工具/资源语义 |
读 MCP SDK 时关注：Tool 描述如何映射到 JSON Schema——与 DSH 描述工程一致（见 开发指南 第五章）。
2.4 与 OpenClaw / 网关型项目
OpenClaw 等侧重 多通道消息网关（Slack、邮件）；DSH 侧重 Agent 运行时。二者可组合：网关收消息 → 调用 DSH Host API → 回复通道。读 OpenClaw 时重点看 会话与通道解耦，而非插件内核。
第三章：社区插件发现（dsh-plugin Topic）
3.1 GitHub Topic 搜索
在 GitHub 搜索：
topic:dsh-plugin
topic:deepseek-harness
或组合：
topic:dsh-plugin stars:>5
3.2 评估社区插件五问
| # | 问题 | 红旗 |
|---|---|---|
| 1 | manifest 是否规范 | 无 peerDependencies |
| 2 | 最近 6 个月是否更新 | 仅 README 变更 |
| 3 | 是否有 mount 测试 | 零测试 |
| 4 | 权限是否最小 | 默认 shell 全开 |
| 5 | Issue 响应 | 长期无维护者 |
3.3 安装前检查清单
- 阅读插件 README 兼容性矩阵
- 在 隔离 VM 用 Minimal 预设试挂载
- 检查
approval与sandbox交互 - 不信任预构建 bundle 中的 postinstall 脚本
第四章：开源 Agent Runtime / Harness / MCP 对照表
以下均为 真实知名项目，用于建立行业坐标；DSH 强调 Cordis 插件与可逆 Effect，对比时抓住 扩展模型 差异。
| 项目 | 仓库/组织 | 核心抽象 | 扩展方式 | 与 DSH 对比 |
|---|---|---|---|---|
| DeepSeek Harness | deepseek-ai/deepseek-harness | Cordis 插件 | provide / effect | 本文主线 |
| LangGraph | langchain-ai/langgraph | 状态图 | Node 函数 | 图编排 vs 运行时 |
| LangChain | langchain-ai/langchain | Chain / Agent | Python/TS 模块 | 管道原型快 |
| AutoGen | microsoft/autogen | 多 Agent 对话 | Agent 类 | 对话编排 |
| CrewAI | crewAIInc/crewAI | Role / Task | YAML + Python | 角色剧本 |
| OpenAI Agents SDK | openai/openai-agents-python | Agent / Handoff | Python API | 厂商绑定 |
| Semantic Kernel | microsoft/semantic-kernel | Plugin / Planner | SK Functions | 企业 .NET/Python |
| Mastra | mastra-ai/mastra | Workflow | TS 框架 | 全栈 TS |
| MCP Servers | modelcontextprotocol/servers | MCP Tool | 独立进程 | DSH 作 Client |
| Continue | continuedev/continue | IDE 扩展 | config.yaml | 编辑器内 Agent |
| Aider | Aider-AI/aider | CLI 结对 | git 集成 | 轻量编码 |
| OpenHands | All-Hands-AI/OpenHands | 沙箱 + Agent | Docker | 重沙箱 |
| SWE-agent | SWE-agent/SWE-agent | 修 Issue | 工具集 | 研究向 |
| e2b | e2b-dev/e2b | 云沙箱 | API | 执行环境 |
| Phoenix / Arize | Arize-ai/phoenix | 追踪评估 | OpenTelemetry | 可观测互补 |
如何用好对照表：不是选「谁更强」，而是 组合。例如 DSH + MCP Servers + Phoenix 追踪，是常见的「运行时 + 工具 + 可观测」三角。
第五章：如何贡献
5.1 贡献类型
| 类型 | 门槛 | 价值 |
|---|---|---|
| 文档 typo | 低 | 高（降低新手摩擦） |
| 示例插件 | 中 | 高 |
| 官方插件修复 | 中 | 很高 |
| 内核 Effect 语义 | 高 | 需深度 Review |
5.2 首次贡献推荐路径
- Fork → 本地跑通 CI 子集
- 选
good first issue或文档任务 - 小 PR 合并建立信任
- 再挑战 tools / sessions 域
5.3 插件 README 必备章节
# @my-org/dsh-plugin-xxx
## 概述
一句话说明能力与安全边界。
## 兼容性矩阵
| 插件版本 | @dsh/runtime | @cordis/core | 预设 |
|----------|--------------|--------------|------|
| 1.0.x | >=0.8.0 | ^1.2.0 | Standard, Code |
## 安装
\`\`\`bash
dsh plugin add @my-org/dsh-plugin-xxx
\`\`\`
## 配置
| 键 | 类型 | 默认 | 说明 |
## 工具列表
| 工具名 | 读写 | 需审批 |
## 开发
\`\`\`bash
pnpm install && pnpm test
\`\`\`
## 许可证
5.4 兼容性矩阵维护
主版本升级时 必须 更新矩阵列：
- runtime 最低版本
- Cordis peer 范围
- 支持的 Preset（Minimal 可能无 llm）
- 已知冲突插件
第六章：GitHub Projects / Issues 管理插件路线图
6.1 为何用 Projects
个人或团队维护多个插件时，Issues 扁平列表难以表达 依赖关系与发布列车。GitHub Projects（v2）提供：
- 表格 / 看板 / 路线图视图
- 自定义字段：优先级、目标 Bundle 版本、安全审查状态
- 跨仓库 Issue 聚合（org 级）
6.2 推荐字段
| 字段 | 类型 | 用途 |
|---|---|---|
| Stage | Single select | ideation / dev / review / released |
| Target | Text | 目标 runtime 版本 |
| Preset | Multi select | Standard / Code / ... |
| Risk | Single select | low / medium / high（安全） |
6.3 Issue 与 Project 联动
6.4 里程碑建议
| Milestone | 内容 |
|---|---|
| v0.1 | 最小可挂载 + README |
| v0.5 | 测试 + validate CI |
| v1.0 | 兼容性矩阵 + 安全审计 |
| v1.x | 新工具向后兼容 |
第七章：学习用 Fork 实验工作流
7.1 原则
- Fork 用于实验，PR 用于回馈；长期 drift 的 fork 难以 rebase
- 每个实验 独立分支：
exp/spawn-timeout、exp/approval-chain - 上游同步每周一次：
git fetch upstream && git rebase upstream/main
7.2 实验记录模板
在 Fork 的 docs/experiments/ 维护 Markdown：
# 实验：Minimal 预设下 Mock LLM
## 假设
无网络可跑通工具链。
## 步骤
1. bundle.test.yaml 替换 llm 插件
2. 跑 session replay sess_demo
## 结论
通过 / 失败
## 上游 Issue
#123
7.3 可复现实验清单
- 记录 commit SHA
- 导出 Bundle yaml
- 附加 Session ID（脱敏）
- 截图插件树
7.4 从实验到贡献
若实验验证某行为是 bug：
- 最小复现分支推送到 Fork
- 开 Issue 链接分支
- 若愿意修复，同一分支转 PR
若实验是 新功能，先在 Discussions 对齐是否适合内核 vs 独立插件。
第八章：资源链接与学习路径
8.1 本站与子站
| 资源 | URL | 用途 |
|---|---|---|
| 七天学会 DSH | https://dsh.chenxiaoshivivid.top/ | Day1–7 课表与实验 |
| 技能实验室 | https://dsh.chenxiaoshivivid.top/lab.html | 内核可视化、审批模拟 |
| 插件社区 | https://dsh.chenxiaoshivivid.top/community.html | 社区插件导航 |
| 入门介绍 | /docs/dsh/intro | 架构认知 |
| 开发指南 | /docs/dsh/development | Cordis API |
| 最佳实践 | /docs/dsh/best-practices | 生产安全 |
| 从零到一 | /docs/dsh/from-zero-to-one | 7 天路径 |
8.2 外部必读
| 资源 | 说明 |
|---|---|
| deepseek-ai/deepseek-harness | 官方主仓库 |
| modelcontextprotocol.io | MCP 协议 |
| OpenTelemetry 文档 | 与 DSH 追踪集成 |
8.3 14 天开源学习日历（建议）
| 天 | 任务 |
|---|---|
| 1–2 | 读 architecture + 跑通 Web UI |
| 3–4 | 读 tools/sessions 源码 |
| 5 | 跟写最小插件 |
| 6–7 | 读 MCP SDK + 接一个 server |
| 8 | 对照 LangGraph 文档写对比笔记 |
| 9–10 | Fork 实验 + Session Replay |
| 11 | 读社区 dsh-plugin 三个 |
| 12 | 写兼容性矩阵草稿 |
| 13 | 提文档 PR 或 Issue |
| 14 | 规划个人插件 Roadmap Project |
第九章：失败模式与避坑
| 坑 | 后果 | 预防 |
|---|---|---|
| 只 star 不读 | 选型失误 | 按本文顺序读 |
| fork 不 sync | rebase 地狱 | 每周 upstream |
| 社区插件直装生产 | 供应链风险 | 隔离试挂载 |
| 无兼容性矩阵 | 用户版本踩雷 | README 必填 |
| 巨型 PR | 无法 merge | 拆分 |
第十章：工程总清单
读仓库
- README → architecture → AGENTS → CONTRIBUTING
- 定位 packages 与 examples
- Code Search 找 apply / provide
选生态项目
- 填对照表扩展列
- 明确 DSH 负责运行时哪一层
贡献
- Issue 含版本与复现
- PR 含测试与文档
- README 含兼容性矩阵
管理
- GitHub Project 路线图
- Milestone 与发布列车
- Fork 实验记录 commit SHA
结语
DeepSeek Harness 的工程知识分布在 官方 monorepo、Cordis 内核、MCP 生态与社区插件 之中。掌握「读 architecture → 找服务实现 → 写可卸载插件 → 用 Issue/Projects 管理路线」的闭环，你就不再依赖零散教程，而能在 Agent 运行时领域持续迭代。
下一步：打开 开发指南 编写第一个可测试插件，并在 七天学会子站 Day 7 完成毕业大作业。
附录 A：deepseek-harness 各 package 阅读笔记模板
建议为每个关注的 package 建一页笔记，包含：职责一句话、导出插件列表、核心服务键、关键 effect、对外配置键、关联 Issue。示例结构：
| 字段 | packages/dsh-tools 填法 |
|---|---|
| 职责 | 工具注册与执行管道 |
| 插件名 | @dsh/plugin-tools |
| 服务键 | tools, tools.registry |
| 必读文件 | register.ts, execute.ts |
| 测试目录 | tests/tools/ |
阅读时同步运行 package 级单测 而非只读代码：pnpm --filter @dsh/plugin-tools test。测试即规格；比注释可靠。若单测使用 mock sandbox，对照 mock 行为理解生产 sandbox 差异。
packages 之间的 internal 与 public API 边界以 package.json 的 exports 字段为准。不应 import 深层路径 @dsh/plugin-tools/dist/internal/...——会在 patch 版本 breakage。社区插件只依赖 exports 暴露的类型与服务键。
关注 release note 中的 BREAKING 段：Cordis effect 语义变更往往影响所有插件。升级 runtime 前先在 staging Host 挂载全量插件跑 smoke test。
文档目录除 architecture 外，常见还有 docs/plugins/、docs/cli/、docs/deployment/。用仓库内搜索 mkdocs.yml 或 sidebars.js 找完整文档树。若文档与代码漂移，以代码为准并提 docs PR——这是高价值贡献入口。
读 AGENTS.md 时留意 工具调用约定：是否要求先 plan 再 execute、是否禁止未审批写操作——这些约定会反映在默认 Preset 的 system prompt 与 approval 插件，而非散落在文档各处。
.github/workflows/ 中 publish workflow 展示 哪些包发 npm、版本策略、是否需要 changeset。贡献者发插件不一定走同一 workflow，但可对齐 test matrix 的 Node 版本。
examples/minimal-bundle/ 类目录是 最快理解 Bundle yaml 语法 的地方；对照 快速开始 本地启动命令，改 yaml 观察插件树变化。
SECURITY.md 描述漏洞披露流程；勿在公开 Issue 贴 exploit。插件供应链问题（恶意 postinstall）报告给维护者而非只删仓库。
Discussions 区适合 「是否该进内核」 的开放设计讨论；Issue 适合可复现 bug。先 Discussion 再 Issue 可减少 invalid issue 噪音。
附录 B：Issue / PR Review 检查清单（维护者视角）
Review 插件 PR 时，维护者脑中清单：Teardown 完整？工具是否绕过 sandbox？审批默认 deny 还是 allow？日志是否泄露 secret？peerDependencies 范围是否过宽？ 贡献者在开 PR 前自检可显著缩短 merge 时间。
对内核 PR，额外关注：是否破坏无特权核心？是否增加默认暴露的攻击面？Session 格式是否向后兼容？ Session 不兼容需 major bump 与迁移工具。
Issue triage 标签建议：bug、enhancement、plugin、security、docs、good first issue。security 标签 Issue 不应公开讨论 exploit 细节。
PR 描述应含 Before/After 行为 与 测试方式。仅写「fix bug」的 PR 几乎必被要求补充。Attach 截图或终端录屏对 UI 插件尤其有效。
Rebase 策略：若仓库要求 linear history，贡献者应 git rebase upstream/main 而非 merge main into feature——保持 commit 清晰。多个 wip commit 可在 PR merge 时 squash（若维护者允许）。
对长期 Feature Issue，维护者可请求 RFC 文档 在 docs/rfcs/ 先合并，再写实现——避免大 PR 方向错误。RFC 应含安全分析与替代方案。
Review 时运行 本地 Replay fixture：维护者 checkout PR 分支，用 CI 上传的 session fixture replay，对比 main 分支 tool 调用次数差异。
Dependabot PR：插件仓库应谨慎 merge major 依赖；跑 full validate + mount test 再 merge。
CODEOWNERS 文件指示哪些路径需要哪团队 approve；贡献者 PR 触及 packages/cordis-* 预期等待更久 review。
CLA：部分 org 要求签署 Contributor License Agreement；Fork 前读 CONTRIBUTING 底部说明。
Review comment 礼仪：提问而非命令；引用代码行号；区分 nit vs blocker。贡献者不应 force-push 覆盖他人 co-author commit без 沟通。
附录 C：社区插件生态与 dsh-plugin Topic 深度运营
创建社区插件时，在 GitHub 仓库 Settings → Topics 添加 dsh-plugin、deepseek-harness、cordis、agent-runtime 等，便于检索。README 徽章可链接到主仓库与 七天学会子站。
组织级维护多个插件时，建 GitHub Organization 统一 CI 与 secret，用 reusable workflow 跑 validate/test。用户信任 org 下的统一安全基线胜过 scattered 个人仓库。
插件市场（若官方或社区提供）通常要求 签名 pack 或 checksum；本地 dsh plugin pack 后验证 sha256 再上传。供应链攻击在 Agent 运行时领域后果极高——工具插件等价于 RCE 面。
举办插件挑战赛（子站 community 页常有活动）时，评审维度应含：Teardown 测试、描述质量、审批友好、文档完整，而非仅功能炫技。安全分权重应不低于功能分。
跟踪竞品框架的新特性（如 LangGraph checkpoint）时，写 对照笔记 到 Discussions，讨论是否适合 Cordis 插件化而非内置——保持内核 slim。
Topic 之外，npm 搜索 @dsh-plugin scope（若官方定义）或关键词 deepseek harness plugin。注意 typosquatting 包名——只安装 README 链接的官方 registry。
社区插件 semver 应与 runtime major 对齐说明；用户 pin 版本。插件作者发 breaking 前在 Discussions 公告并 @mention 已知依赖方。
插件合集 repo（awesome-dsh-plugins 类）维护 inclusion 标准：有测试、有矩阵、6 个月内更新。本站 插件社区 可作为 curated 列表入口。
恶意插件指标：postinstall curl bash、请求 broad filesystem、无 Teardown 测试、copy-paste 官方插件改 secret exfil。举报流程走 GitHub report 与 DeepSeek security email。
Localization：社区插件 README 英文为主，中文可选；本站文档中文教学与英文 README 互补，避免 fork 仅翻译 README 而无代码更新。
附录 D：开源 Agent 项目阅读法（通用）
读 LangGraph 源码：抓住 StateGraph、checkpoint、interrupt 三概念，对比 DSH Session Log 的异同——前者偏编排状态机，后者偏事件溯源与插件副作用。笔记表列：LangGraph node 对应 DSH 何物（多为 Host 外编排或 tool 序列）。
读 AutoGen：关注 Agent 间消息协议与 human-in-the-loop 钩子；可借鉴到 DSH 审批 UI 设计，而非替换 Cordis。GroupChat manager 类似 Spawn 多子 Agent，但缺少 DSH 统一 sandbox。
读 CrewAI：Role/Task YAML 声明式；对比 DSH Preset yaml 声明工具集。CrewAI 快速 demo；DSH 强在生产 Teardown 与 Replay。
读 OpenHands：重点看 Docker 沙箱如何隔离命令执行；与 DSH sandbox 服务对比 allowlist 粒度。可 inspire 社区插件 @community/dsh-sandbox-docker。
读 MCP servers 官方仓库：filesystem、git、postgres 各是一个 工具域样板。学习 Schema 描述写法，移植到 开发指南 描述工程。
读 Continue / Aider：IDE/CLI 内 Agent 工具描述与 user approval 交互；对比 DSH Client 槽位审批 UX。Continue config.yaml 类似 Profile patch。
读 Semantic Kernel：Planner + Plugin 模型；SK function 类似 tools.register。企业 .NET 栈可参考其 policy 层设计 org approval 插件。
读 Mastra：TS workflow 与 DSH 三平面 Client/Host 分工对照；Mastra 偏应用框架，DSH 偏 runtime 内核。
读 SWE-agent / OpenDevin 系：研究 benchmark 如何测 Agent；可借鉴 Session fixture 到插件 CI，而非照搬其 sandbox。
读 e2b / Modal：云沙箱 API；若插件需 burst 执行，Spawn 子 Agent 调云沙箱而非本地 shell——架构图 Draw 清边界。
读 Phoenix / LangSmith / Braintrust：追踪与 eval；DSH OTel 导出后可接这些平台做 tool 失败率 dashboard。
不要试图读完所有项目；每个项目选一个代表模块深读 即可。用本文对照表选与当前任务最相关的 2–3 个仓库，14 天日历已分配节奏。
论文与博客（ReAct、Toolformer）补充 描述工程 理论背景；读 AGENTS.md 时交叉引用，理解设计选择非随意。
Star 数不是选型唯一指标；看 issue 关闭率、release 频率、security policy 同样重要。
附录 E：GitHub Projects 视图配置示例
创建 Roadmap 视图：X 轴时间（Quarter），Y 轴自定义字段 Stage。每列卡片为 Issue，链接到插件仓库 PR。适合向非工程干系人汇报插件版本列车。
创建 Priority 表格视图：按 Risk 降序排列 security 相关 Issue，确保高危先关闭。字段 Color 标记 blocked 项。
创建 Preset 矩阵视图：行是插件，列是 Standard/Code/Minimal/Creator 支持勾选，一目了然缺口。
自动化：Issue 添加 label released 时，GitHub Action 更新 Project 字段 Stage → released，并 comment 兼容性矩阵链接。
与 Discord / 论坛同步：重大 Release 发 Announcement 帖，帖内链接 GitHub Release 与 快速开始 升级段。
个人学习者无 org 时，仍可用 单用户 Project 管理 Fork 实验 Issue，字段简化：Status、Experiment、Upstream PR。
定期（每月）清理 stale Issue：无复现的 close；有复现无资源的转 help wanted 吸引贡献者。
Fork 实验分支命名规范：exp/YYYYMMDD-简短描述，便于 Project 筛选与批量删除 merged 实验分支。
跨仓库 Project：org 下 dsh-plugins 组所有 repo Issue 汇总到一个 Project，字段 Target runtime 统一规划升级。
Iteration 字段：按 sprint 或按 runtime minor 版本划分， retrospective 时移动卡片到 done 并链 Release note。
模板 Issue 表单：New plugin / Bug / Security / Docs 四种模板，创建时自动加入 Project 默认 backlog 列。
Insights：GitHub Project 内置图表看 cycle time；插件从 ideation 到 released 超过 90 天应拆分 scope。
附录 F：从开源阅读到生产落地的桥梁
读源码的最终目的是 可预测的 production 行为。建议维护一份「我们用的 Bundle 与 upstream 差异表」：哪些插件 pin 版本、哪些 Patch 覆盖了何配置、为何不能 upstream 合并（通常含内网 MCP endpoint 或 org 审批策略）。
Staging 环境应 每周自动跟踪 upstream main 的 nightly（若团队承受得起），跑 Session Replay 回归套件。失败则开 internal Issue 关联 upstream commit range。
生产 Incident 时，先用 Session Replay 定位是模型、工具还是插件；再查 GitHub Release 是否刚升级 runtime——若是，回滚 runtime 比改 Prompt 更快验证。
培训新成员：第一周按本文 14 天日历前 7 天；第二周配对 Review 一个社区插件 PR（即使不 merge，练 Review 清单）。
文档站点（本站 /docs/dsh）与 GitHub docs 互补：本站偏 工程教学与中文，GitHub 偏 权威 API 与英文。冲突时以 GitHub 为准，向本站提 PR 修正。
七天学会子站实验完成后，将实验记录 PR 到个人 Fork 的 docs/experiments/，形成可展示的开源学习 portfolio，对求职与团队内部分享均有价值。
内部 mirror：企业可 mirror deepseek-harness 到 GitLab/GHE，CI 从 mirror 拉取；关注 upstream security advisory 邮件列表同步 cherry-pick。
合规存档：金融等行业要求依赖 SBOM；dsh plugin pack 产物附 npm ls / cyclonedx，存 artifact registry。
多团队共用 Host：各团队 Plugin 走不同 org repo，Project 字段 Owner team 避免互相 block merge。
Vendor 插件：第三方 ISV 插件按 SLA review；兼容性矩阵由 ISV 维护，企业 SRE 只 pin 已审计版本。
下线插件：Project 卡片 Stage → deprecated，README banner 链迁移指南，Bundle patch 移除插件前给 90 天 notice。
Knowledge base：Confluence/Notion 链 GitHub Issue/PR 永久链接，避免只存截图丢失上下文。
On-call runbook 一页纸：Replay 命令、回滚 bundle tag、联系插件 owner GitHub handle。
Post-incident：blameless postmortem Issue 模板，链 Session id 与 merged fix PR。
Cost：读代码不是为了重写内核，而是 写更少、更安全的插件；复用 official packages exports 而非 copy-paste。
附录 G：兼容性矩阵与版本语义详解
兼容性矩阵最小四列：插件版本、@dsh/runtime、@cordis/core、支持的 Preset。可选列：Node 版本、已知冲突、E2E 状态、最后验证日期。
semver 规则：插件 major bump 当工具 Schema breaking 或移除工具；minor 当新增工具 backward compatible；patch 当文档或内部 fix 无行为变。
runtime major bump 可能要求所有插件 re-validate；组织 Project 开 epic「runtime 0.9 升级」统一跟踪各插件 PR。
Cordis peer 范围：^1.2.0 表示 >=1.2.0 <2.0.0；勿写 *。CI 应用 lowest 与 highest supported runtime 各测一次。
Preset 列：写「Standard, Code」而非「all」——Creator 通常需额外安全审查。Minimal 若不支持，写「不支持（需 llm）」。
Node 列：写 20.x / 22.x；原生 addon 插件写全平台 matrix（linux/darwin/win）。
冲突列：例「与 @foo/bar 1.x 冲突，需 bar 2.0+」。
E2E 列：链接 GitHub Actions badge或 last run date。
验证日期：提醒用户「矩阵过期 >6 个月请开 Issue 询问」。
预发布：矩阵增加 1.0.0-beta.1 行，Preset 列可能缩窄。
LTS：组织可定义 plugin LTS 分支 release-1.0，只 backport security；Project 字段 LTS yes/no。
Deprecation：矩阵删除行前 strikethrough 一行「deprecated，替代 @new/plugin」。
自动化：CI 读 README 表格 json 化 diff，PR 改代码未改矩阵则 fail。
用户侧：生产 pin exact plugin version； Renovate bot 开 PR 时人读矩阵 changelog。
内核插件版本与社区插件版本 独立 semver；勿假设同号对齐。
翻译：中文 README 矩阵与英文一致；数字版本不翻译。
示例矩阵见 开发指南 插件 README 章节与本文 §5.3。
纠纷：用户报「矩阵说支持但失败」——维护者复现后更新矩阵或发 patch，Issue 标签 matrix-bug。
附录 H：Fork 实验工作流进阶
实验环境隔离：每实验新 VM 或 devcontainer，避免上一个实验修改 ~/.dsh 污染下一个。实验结束 snapshot 命名含 commit SHA。
upstream 同步脚本：git remote add upstream https://github.com/deepseek-ai/deepseek-harness.git；每周 cron fetch + rebase；冲突时开 exp/rebase-YYYYMMDD 专门解决，不污染 feature 分支。
双 Fork 策略：一个 Fork 保持 clean 跟 upstream；一个 Fork 专门乱实验 force-push。避免实验 commit 污染准备 PR 的 Fork。
Cherry-pick 实验：实验分支只 1–3 commit，验证后可 cherry-pick 到新 feature 分支开 PR，丢弃 exp 分支。
Session fixture 共享：实验成功后将 anonymized session 导出到 fixtures/replay/，CI 引用；失败 fixture 也可存「回归防再犯」。
Bundle yaml diff：实验前后 git diff bundle.yaml 贴 Issue；Review 者一眼见配置变更。
插件 graph 附件：dsh plugin graph --format mermaid > graph.mmd 贴 PR 说明依赖变化。
时间盒：实验超过 4h 无结论，写 docs/experiments/xxx-aborted.md 记录假设与否定结果，同样有价值。
结对实验：Discord 找同好 screen share Replay，减少独自迷路。
录屏：asciinema 录 CLI 实验，README 嵌入，比静态截图更易复现。
License：实验代码若含 copy upstream 大段，注意 LICENSE 头；独立实验脚本可 MIT。
Publish 实验插件：即使不 merge upstream，可发个人 npm @yourname/dsh-plugin-exp-* 供他人引用，Topic 仍 dsh-plugin。
Archive：GitHub Archive 仓库只读；实验完成 close repo 或 archive，避免 Google 搜到过时 fork 当官方。
Re-open 实验：Issue 链旧实验结论；新 Comment 更新而非 开重复 Issue。
Teaching：七天学会子站 Day 作业可要求 Fork 实验记录链接，讲师 batch clone 批改。
Security 实验：只在 offline VM 测 exploit；勿对 production Host 或他人 Session 做未授权测试。
Performance 实验：fork 测 Spawn 100 子 Agent 内存曲线，结果贴 Discussions 供内核优化，非必须 PR。
文档实验：仅改 docs 也可走 Fork → PR；低门槛贡献入门。
附录 I：贡献 deepseek-harness 内核 vs 社区插件决策树
应走插件：单一 SaaS 集成、企业内部 MCP、定制 approval、Client 皮肤、特定 cloud sandbox 适配。
应走内核：Cordis effect 语义 bug、Session 格式安全漏洞、tools 管道 universal fix、官方 Preset 默认行为错误。
灰色地带：新 Preset 类型——可先社区 Bundle 验证需求，再提议进官方 examples。
文档-only PR：修正 architecture 与代码不一致；中文翻译通常在本站 chenxiaoshivivid 而非 upstream，除非官方要 i18n。
示例插件：upstream examples/ 欢迎；比改内核加 demo 更安全。
性能优化：需 benchmark 数字；Issue 先贴 flamegraph 或 Replay 慢点 Session。
Breaking change：必须 migration guide + major version；Project 开 tracking issue 列下游插件。
Revert policy：maintainer 可能 revert 有问题的 merge；contributor 勿视为个人攻击，fix forward。
Co-maintain：长期贡献者可请求 plugin package maintainer；见 CONTRIBUTING governance 段。
Code of Conduct：违反 CoC 的 Issue/PR 会被 close；保持技术讨论对事不对人。
Embargo：security fix 在 release 前勿公开 PR title 含漏洞细节。
Release party：大版本 Release 时 Discussions 写 upgrade guide，链 从零到一 差异节。
Thank you：合并后 bot 可能发 thank you；继续帮忙 triage Issue 是更好贡献。
附录 J：资源链接扩展与学习社区
| 类型 | 链接 | 说明 |
|---|---|---|
| 七天学会 | https://dsh.chenxiaoshivivid.top/ | 中文课表 Day1–7 |
| 实验室 | https://dsh.chenxiaoshivivid.top/lab.html | 可视化实验 |
| 社区 | https://dsh.chenxiaoshivivid.top/community.html | 插件与挑战 |
| 官方仓库 | https://github.com/deepseek-ai/deepseek-harness | SSOT |
| MCP | https://modelcontextprotocol.io | 协议与 SDK |
| OTel | https://opentelemetry.io/docs/ | 追踪集成 |
本站文档索引：intro、getting-started、development、best-practices、faq、from-zero-to-one。
Discord / 论坛入口以官方 README 为准；提问带 Session id 与版本号。
DeepSeek 官方博客 / 发布说明：关注 Agent runtime 相关 post，但 API 以 GitHub 为准。
Conference talk：若社区有 QCon、AI Engineer Summit 相关 talk 视频，作入门动机，细节仍回源码。
Book club：团队每两周读一个 package + 写笔记 Issue 链 PR，强制输出防只读不练。
University course：可将 14 天日历作 syllabus 实验部分，学生 PR 到个人 Fork experiments。
Certification（若有）：官方若有认证，以官方为准；本站七天学会可作自学证明 portfolio。
Newsletter：订阅 GitHub Watch Release only 防邮件过多；Watch custom 选 security alerts。
Twitter/X、Mastodon 关注 maintainers 获 release 即时消息，但配置以 GitHub Release note 为准。
镜像站：ghproxy 等仅加速 clone，勿 从非官方 fork 下载 pack 安装插件。
VPN / 网络：企业 proxy 下 MCP egress 需额外配置；Issue 搜 proxy 看是否已有 patch 插件。
Windows WSL：读仓库与跑 Host 推荐 WSL2；路径注册问题见 开发指南 绝对路径节。
Apple Silicon：native 依赖插件查 matrix 是否含 darwin/arm64。
Raspberry Pi：Minimal 预设 + mock llm 可作 edge demo；性能预期管理。
Offline air-gap：vendor pack tgz + bundle yaml 进内网；Discussions 有 air-gap 最佳实践帖可搜。
Legal：企业法务 review LICENSE 与第三方插件 license 兼容性；GPL 插件谨慎 link。
Accessibility：Client 插件贡献也欢迎 a11y fix；Issue 标签 a11y。
i18n：欢迎 docs 翻译 PR；代码 comment 英文为主便于 global review。
结束语重复强调：读 → 实验 → 贡献 → 管理 Project 闭环；开发指南 与本文互补，一文插件工程，一文开源协作。
附录 K：GitHub 与开源协作术语表
| 术语 | 含义 |
|---|---|
| SSOT | 单一事实来源，指 official repo |
| upstream | 官方原仓库 |
| Fork | 个人/组织副本用于 PR |
| PR | Pull Request 合并请求 |
| Issue | 问题/功能追踪 |
| Discussions | 论坛式讨论 |
| Projects | GitHub 项目看板 v2 |
| Topic | 仓库标签 dsh-plugin |
| Release | 版本发布含 changelog |
| peerDependencies | npm 同伴依赖 Cordis/runtime |
| compatibility matrix | README 版本兼容表 |
| good first issue | 新手友好任务 |
| RFC | 设计提案先于大改 |
| CLA | 贡献者许可协议 |
| SBOM | 软件物料清单 |
| CODEOWNERS | 路径负责人 |
| changeset | monorepo 版本变更记录 |
| Replay | Session 重放调试 |
| Bundle | 插件集合配置 |
| Preset | Standard/Code/Minimal/Creator |
| Cordis | 插件内核 |
| MCP | Model Context Protocol |
| OTel | OpenTelemetry 可观测 |
| Teardown | 插件卸载清理 |
| sandbox | 执行沙箱 |
| Spawn/Fork | 子 Agent 模式 |
| validate | dsh plugin validate 命令 |
| pack | 插件打包 tgz |
| staging/canary/prod | 部署阶段 |
| semver | 语义化版本 |
| breaking | 不兼容变更 |
| backport | 向后移植 fix 到 LTS 分支 |
| cherry-pick | 挑选 commit 应用 |
| rebase | 变基同步 upstream |
| squash merge | 压扁 commit 合并 |
| Draft PR | 草稿 PR 提前 CI |
| Review | 代码审查 |
| Triage | Issue 分诊打标签 |
| Stale | 长期无活动 Issue |
| Dependabot | 依赖自动 PR |
| Security advisory | 安全公告 |
| Exploit | 漏洞利用勿公开贴 |
| air-gap | 离线隔离环境 |
| typosquatting | 恶意相似包名 |
| postinstall | npm 安装脚本风险 |
| MIT/Apache | 宽松许可证 |
| GPL | copyleft 注意传染 |
| mirror | 仓库镜像只读 copy |
| devcontainer | VS Code 容器开发环境 |
| fixture | 测试用 Session 样本 |
| mermaid graph | 依赖图可视化 |
| CI matrix | 多版本并行测试 |
| artifact | CI 构建产物 |
| changelog | 版本变更日志 |
| milestone | GitHub 里程碑 |
| roadmap | 路线图视图 |
| epic | 大项 Issue 容器 |
| help wanted | 欢迎社区接手 |
| wontfix | 不修复关闭 |
| duplicate | 重复 Issue 关闭 |
| regression | 回归 bug |
| smoke test | 冒烟测试 |
| E2E | 端到端测试 |
| HIL | 硬件/集成在环 |
| portfolio | 实验记录作品集 |
| Day1-7 | 七天学会课表 |
| lab | 技能实验室子站 |
| community | 插件社区页 |
| chenxiaoshivivid | 本站域名 |
| deepseek-ai | GitHub 组织名 |
| langchain-ai | LangChain 组织 |
| microsoft | AutoGen SK 等 |
| modelcontextprotocol | MCP 官方 org |
| continuedev | Continue IDE |
| All-Hands-AI | OpenHands |
| e2b-dev | e2b 沙箱 |
| Arize-ai | Phoenix 追踪 |
| mastra-ai | Mastra 框架 |
| crewAIInc | CrewAI |
| openai | OpenAI Agents SDK |
| SWE-agent | 修 Issue Agent |
| Aider-AI | Aider CLI |
| OpenClaw | 多通道网关参考 |
| LangGraph | 图编排参考 |
| Semantic Kernel | 企业 Plugin 参考 |
| Phoenix | eval 追踪参考 |
| Braintrust | eval 可选 |
| LangSmith | LangChain 追踪 |
| Stack Overflow | 搜错误次选 GitHub Issues |
| GitHub Code Search | 搜 ctx.provide |
| GitHub Advanced Security | 企业 secret scan |
| GHE | GitHub Enterprise |
| GitLab | 可 mirror 替代 |
| Discord | 社区实时聊天 |
| SECURITY.md | 安全披露流程 |
| CONTRIBUTING.md | 贡献流程 |
| AGENTS.md | Agent 设计意图 |
| architecture.md | 架构 SSOT 文档 |
| examples/ | 示例 Bundle 插件 |
| packages/ | monorepo 包 |
| plugins/ | 可能插件目录名 |
| .github/workflows | CI 定义 |
| LICENSE | 许可证文件 |
| README | 首读入口 |
| Release note | 版本说明 breaking |
| Watch | GitHub 订阅 release |
| Star | 收藏非等于已读 |
| Fork count | 社区关注度参考 |
| Contributor graph | 谁改哪块代码 |
| Blame | 行级历史 |
| Bisect | git bisect 找回归 commit |
| Patch | Bundle 局部覆盖 |
| Profile | 环境 yaml |
| Host | 运行时进程 |
| Client | Web UI 槽位 |
| Preset lab | 子站预设对比 |
| approval sim | 子站审批模拟 |
| kernel viz | 子站内核可视化 |
| graduation | Day7 毕业作业 |
| plugin market | 插件市场概念 |
| challenge | 插件挑战赛 |
| experiment branch | exp/ 前缀分支 |
| clean fork | 跟 upstream 无实验 |
| dirty fork | 专做实验 |
| anonymized session | 脱敏 Replay |
| matrix-bug | 矩阵与行为不符 |
| plugin owner | 插件维护者 handle |
| on-call | 运维值班 |
| postmortem | 事故复盘 Issue |
| blameless | 无责复盘文化 |
| vendor plugin | 第三方 ISV |
| deprecated | 弃用通知 |
| LTS | 长期支持分支 |
| beta | 预发布 semver |
| lowest highest | peer 测试边界 |
| native addon | 原生模块平台 |
| darwin arm64 | Apple Silicon |
| WSL2 | Windows Linux 子系统 |
| proxy egress | 企业网络出口 |
| ghproxy | clone 加速非官方 |
| air-gap best practice | 离线部署帖 |
| legal review | 法务审 license |
| a11y | 无障碍 |
| i18n | 国际化 |
| portfolio experiments | Fork 实验 docs |
| book club | 团队读书 Issue |
| syllabus | 教学大纲 |
| certification | 官方认证若有 |
| newsletter release | 订阅方式 |
| maintainer | 维护者 |
| triage | 分诊 |
| co-maintain | 共同维护 |
| governance | 项目治理 |
| embargo | 安全发布前保密 |
| upgrade guide | 大版本升级指南 |
| thank you bot | 合并感谢 bot |
| 读仓库 | 本文核心技能 |
| 对照学习 | 与其他 Agent 框架比 |
| 贡献 | Issue PR RFC |
| Projects 路线图 | 插件版本管理 |
| Fork 实验 | 低风险学习 |
| 七天学会链接 | https://dsh.chenxiaoshivivid.top/ |
| 插件工程 | 见 development 文档 |
| 闭环 | 读实验贡献管理 |
附录 K：GitHub 与开源协作术语表
| 术语 | 含义 |
|---|---|
| SSOT | 单一事实来源，指 official repo |
| upstream | 官方原仓库 |
| Fork | 个人/组织副本用于 PR |
| PR | Pull Request 合并请求 |
| Issue | 问题/功能追踪 |
| Discussions | 论坛式讨论 |
| Projects | GitHub 项目看板 v2 |
| Topic | 仓库标签 dsh-plugin |
| Release | 版本发布含 changelog |
| compatibility matrix | README 版本兼容表 |
| good first issue | 新手友好任务 |
| RFC | 设计提案先于大改 |
| CLA | 贡献者许可协议 |
| SBOM | 软件物料清单 |
| CODEOWNERS | 路径负责人 |
| changeset | monorepo 版本变更记录 |
| Replay | Session 重放调试 |
| Bundle | 插件集合配置 |
| Cordis | 插件内核 |
| MCP | Model Context Protocol |
| OTel | OpenTelemetry 可观测 |
| Teardown | 插件卸载清理 |
| sandbox | 执行沙箱 |
| Spawn/Fork | 子 Agent 模式 |
| validate | dsh plugin validate 命令 |
| pack | 插件打包 tgz |
| staging/canary/prod | 部署阶段 |
| semver | 语义化版本 |
| breaking | 不兼容变更 |
| backport | 向后移植 fix 到 LTS 分支 |
| cherry-pick | 挑选 commit 应用 |
| rebase | 变基同步 upstream |
| squash merge | 压扁 commit 合并 |
| Draft PR | 草稿 PR 提前 CI |
| Review | 代码审查 |
| Triage | Issue 分诊打标签 |
| Stale | 长期无活动 Issue |
| Dependabot | 依赖自动 PR |
| Security advisory | 安全公告 |
| Exploit | 漏洞利用勿公开贴 |
| air-gap | 离线隔离环境 |
| typosquatting | 恶意相似包名 |
| postinstall | npm 安装脚本风险 |
| MIT/Apache | 宽松许可证 |
| GPL | copyleft 注意传染 |
| mirror | 仓库镜像只读 copy |
| devcontainer | VS Code 容器开发环境 |
| fixture | 测试用 Session 样本 |
| mermaid graph | 依赖图可视化 |
| CI matrix | 多版本并行测试 |
| artifact | CI 构建产物 |
| changelog | 版本变更日志 |
| milestone | GitHub 里程碑 |
| roadmap | 路线图视图 |
| epic | 大项 Issue 容器 |
| help wanted | 欢迎社区接手 |
| wontfix | 不修复关闭 |
| duplicate | 重复 Issue 关闭 |
| regression | 回归 bug |
| smoke test | 冒烟测试 |
| E2E | 端到端测试 |
| HIL | 硬件/集成在环 |
| portfolio | 实验记录作品集 |
| Day1-7 | 七天学会课表 |
| lab | 技能实验室子站 |
| community | 插件社区页 |
| chenxiaoshivivid | 本站域名 |
| deepseek-ai | GitHub 组织名 |
| langchain-ai | LangChain 组织 |
| microsoft | AutoGen SK 等 |
| modelcontextprotocol | MCP 官方 org |
| continuedev | Continue IDE |
| All-Hands-AI | OpenHands |
| e2b-dev | e2b 沙箱 |
| Arize-ai | Phoenix 追踪 |
| mastra-ai | Mastra 框架 |
| crewAIInc | CrewAI |
| openai | OpenAI Agents SDK |
| SWE-agent | 修 Issue Agent |
| Aider-AI | Aider CLI |
| OpenClaw | 多通道网关参考 |
| LangGraph | 图编排参考 |
| Semantic Kernel | 企业 Plugin 参考 |
| Phoenix | eval 追踪参考 |
| Braintrust | eval 可选 |
| LangSmith | LangChain 追踪 |
| GitHub Code Search | 搜 ctx.provide |
| GHE | GitHub Enterprise |
| GitLab | 可 mirror 替代 |
| Discord | 社区实时聊天 |
| SECURITY.md | 安全披露流程 |
| CONTRIBUTING.md | 贡献流程 |
| AGENTS.md | Agent 设计意图 |
| architecture.md | 架构 SSOT 文档 |
| examples/ | 示例 Bundle 插件 |
| packages/ | monorepo 包 |
| plugins/ | 可能插件目录名 |
| .github/workflows | CI 定义 |
| LICENSE | 许可证文件 |
| README | 首读入口 |
| Release note | 版本说明 breaking |
| Watch | GitHub 订阅 release |
| Star | 收藏非等于已读 |
| Fork count | 社区关注度参考 |
| Contributor graph | 谁改哪块代码 |
| Blame | 行级历史 |
| Bisect | git bisect 找回归 commit |
| Patch | Bundle 局部覆 盖 |
| Profile | 环境 yaml |
| Host | 运行时进程 |
| Client | Web UI 槽位 |
| Preset lab | 子站预设对比 |
| approval sim | 子站审批模拟 |
| kernel viz | 子站内核可视化 |
| graduation | Day7 毕业作业 |
| plugin market | 插件市场概念 |
| challenge | 插件挑战赛 |
| experiment branch | exp/ 前缀分支 |
| clean fork | 跟 upstream 无实验 |
| dirty fork | 专做实验 |
| anonymized session | 脱敏 Replay |
| matrix-bug | 矩阵与行为不符 |
| plugin owner | 插件维护者 handle |
| on-call | 运维值班 |
| postmortem | 事故复盘 Issue |
| blameless | 无责复盘文化 |
| vendor plugin | 第三方 ISV |
| deprecated | 弃用通知 |
| LTS | 长期支持分支 |
| beta | 预发布 semver |
| lowest highest | peer 测试边界 |
| native addon | 原生模块平台 |
| darwin arm64 | Apple Silicon |
| WSL2 | Windows Linux 子系统 |
| proxy egress | 企业网络出口 |
| ghproxy | clone 加速非官方 |
| air-gap best practice | 离线部署帖 |
| legal review | 法务审 license |
| a11y | 无障碍 |
| i18n | 国际化 |
| book club | 团队读书 Issue |
| syllabus | 教学大纲 |
| certification | 官方认证若有 |
| newsletter release | 订阅方式 |
| maintainer | 维护者 |
| triage | 分诊 |
| co-maintain | 共同维护 |
| governance | 项目治理 |
| embargo | 安全发布前保密 |
| upgrade guide | 大版本升级指南 |
| thank you bot | 合并感谢 bot |
| 读仓库 | 本文核心技能 |
| 对照学习 | 与其他 Agent 框架比 |
| 贡献 | Issue PR RFC |
| Projects 路线图 | 插件版本管理 |
| Fork 实验 | 低风险学习 |
| 插件工程 | 见 development 文档 |
| 闭环 | 读实验贡献管理 |
附录 K：GitHub 与开源协作术语表
附录 L：deepseek-harness 源码阅读周计划（可打印）
周一：Fork 官方仓库，读 README + LICENSE，本地 pnpm install（或文档指定包管理器），跑 pnpm test 子集。输出：环境版本记录 Issue 自用笔记。
周二：精读 docs/architecture.md 全文，做概念对照表（本文 §1.4）。输出：architecture 笔记 markdown 链 intro 交叉链接。
周三：Code Search ctx.effect，读 3 个官方插件 apply 实现 （tools、sessions、sandbox 各一）。输出：Effect Teardown 模式摘录。
周四：读 packages/dsh-cli 或等价 CLI 包，理解 dsh plugin validate 实现。输出：manifest 必填字段清单。
周五：读 examples/minimal-bundle，改 yaml 增减插件，本地 Host 观察插件树。输出：before/after graph mermaid。
周六：读 MCP client 插件 + 官方 MCP servers 一个 server。输出：tool 描述对照表。
周日：写 Discussions 或个人博客「一周读 DSH 仓库总结」，链 七天学会 对应 Day。可选：提 docs typo PR。
第二周重复 packages 轮换（llm、approval、client、otel），并读一个社区 topic:dsh-plugin 仓库对比 README 矩阵。第三周起尝试 good first issue 或发布最小插件。
周计划失败模式：只 clone 不 build；只读 README 不读 tests；跳过 architecture 直接写插件——后期必返工。坚持 测试驱动读源码（读前先跑 test 看期望行为）。
团队版：五人每组分工读不同 package，周五 internal demo 互讲；GitHub Project 卡 Track「读源码 sprint」。
导师版：学员提交每 day 笔记 PR 到 Fork docs/reading-notes/，导师 Review 提问而非给答案。
企业版：air-gap mirror 后内网 GitHub Enterprise 同样流程；Session fixture 不出内网。
记录模板：docs/reading-notes/YYYY-MM-DD-package-name.md 含 commit SHA、问题列表、待开 Issue 链接。
问题升级：读源码发现 bug → 先搜 Issues → 无则开 Issue 附最小复现 → 可选 PR fix。
Celebrate：读完 architecture + 3 packages + 1 example 已超越多数 star 不读用户；继续 开发指南 写插件巩固。
附录 M：知名 MCP Server 与 DSH 组合场景
| MCP Server（官方 servers repo） | 工具域 | DSH 组合方式 | 安全注意 |
|---|---|---|---|
| filesystem | 读写文件 | mcp-client 插件连接 | path allowlist |
| git | 版本控制 | Code 预设 + 审批 | 禁止 force push 默认 |
| postgres | SQL 查询 | 只读账号 + deny DDL | SQL 注入 prompt 防护 |
| fetch | HTTP 获取 | Creator 慎用 | SSRF allowlist |
| memory | 知识图谱 | 长会话补充 | PII Retention |
| brave-search | 搜索 | Standard 可选 | API key 环境变量 |
| puppeteer | 浏览器 | 隔离网络 | 资源 limit |
组合架构：DSH Host → mcp-client 插件 → stdio/socket MCP server → 外部系统。DSH 负责 Session、审批、Replay；MCP 负责工具协议标准化。
读 servers 源码顺序：先看 README 工具列表 → 看 index.ts tool 注册 → 看 Schema 定义 → 本地 npx @modelcontextprotocol/inspector 连接测。
DSH 插件作者可 包装 MCP server 为「一键 Bundle patch」，企业用户不需手配 command line；社区插件命名 @org/dsh-mcp-postgres 等。
失败模式：MCP server 进程泄漏——DSH mcp-client 插件 Teardown 必须 kill 子进程；读 upstream mcp-client effect 学习。
多 server：Profile patch 列 servers 数组；注意 tool 名 prefix 防冲突（见 开发指南）。
Eval：同一 prompt 走 native tools vs MCP tools 对比 latency 与 success rate；结果写 experiments/。
合规：postgres MCP 查生产库只读 replica；audit log 写 DSH Session。
未来：MCP 规范演进 watch specification repo Releases；DSH peer 版本在 matrix 声明。
附录 M：知名 MCP Server 与 DSH 组合场景
| puppeteer | 浏览器 | 隔离网络 | 资源 limit |
附录 N：插件路线图 GitHub Project 实例（虚构组织示例）
组织 example-org 维护插件 A/B/C，Project「DSH Plugins 2026」列：Backlog / Design / In Dev / Security Review / Released / Deprecated。
插件 A v2.0 epic：Issue #101 新增 tool，#102 矩阵更新，#103 docs；Target runtime 0.9；Preset Standard+Code；Risk medium（写文件）。
插件 B security：Issue #201 CVE 依赖升级；Priority P0；Stage Security Review；Assignee on-call。
插件 C deprecated：Stage Deprecated；Issue #301 链替代插件 D；Milestone「2026-Q2 cleanup」。
Automation rule：PR merge to main with label release → 移动 Project 到 Released → 发 GitHub Release → Discord bot webhook。
View「By Preset」：筛选 Preset 含 Creator 的卡片，季度 review 是否仍必要。
View「Risk high」：每月安全例会过一遍；无进展 escalate。
Insights：cycle time 从 In Dev 到 Released median 14 days；超 30 days 拆 Issue。
Contributor 外协：Fork 插件 C fix，Project 字段 External yes，Contract SLA 30 days merge or close。
Reporting：导出 Project CSV 给管理层，列 Released 数、open security、upcoming runtime bump。
与 从零到一 Day7 对齐：个人学习者简化版 Project 仅 3 列 Todo/Doing/Done 跟踪自己的第一个插件。
模板 duplicate：GitHub Project template duplicate 到新 org，改字段 Preset 选项即可复用。
Closing：Project 不是 bureaucracy，而是 多插件版本列车不撞车 的最低成本工具；单插件可只用 Milestone，三插件以上强烈推荐 Project。
附录 O：开源 Agent 运行时深度对照（扩展论述）
O.1 DeepSeek Harness 的独特价值
在对照表中，DeepSeek Harness 占据「高运行时深度 + 较高编排灵活度」象 限。其差异点不在于再提供一个 Chain API，而在于 Cordis 可逆 Effect + Append-only Session + 三平面 Bundle 配置。读 LangChain 时你获得丰富集成；读 DSH 时你获得 可卸载、可 Replay、可审计 的生产 Agent 宿主。企业若需要「谁挂载了什么插件、何时 Teardown、工具谁批准」的答案，DSH 的数据模型更自然。
O.2 LangGraph 与 DSH 协作而非替代
LangGraph 适合显式状态机：节点=步骤，边=条件，checkpoint=持久状态。DSH Session Log 是 事件流 而非图节点状态。协作模式：LangGraph 在外部编排高层业务流程，每个节点调用 DSH Host API 执行一轮 Agent+Tools；DSH 返回 Session id 与 structured output 作为图状态输入。避免在 LangGraph 内重复实现 sandbox/approval。
O.3 MCP 生态位置
MCP 是 工具 wire format；DSH 是 工具 runtime 宿主。类似 HTTP 与 Web Server。读 MCP specification 的 tools/list 与 tools/call；读 DSH tools 服务的 register/execute——映射关系清晰。社区可同时维护 MCP server（Python）与 DSH 策略插件（TS），服务不同客户：MCP 通用，DSH 企业策略。
O.4 OpenHands / e2b 沙箱层
OpenHands 强在 Docker 隔离与 GUI；e2b 强在云 API 弹性。DSH sandbox 服务可配置为 调用 e2b API 作为 execute 后端——插件 @integration/dsh-e2b 概念设计。读 OpenHands 源码看 container lifecycle；读 DSH effect Teardown 看进程清理——合并最佳实践。
O.5 Continue / Aider 开发者体验
Continue 的 config.yaml 声明 models 与 rules；Aider 的 git integration 自动 commit。DSH Code 预设可借鉴 git 工具描述 与 edit 格式，但 Session Replay 是 DSH 独有调试优势。开发者可 Continue 写代码、DSH Host 跑长任务 Agent，各取所长。
O.6 评估选型工作坊（90 分钟）
- 列需求：插件化、Replay、MCP、多 Agent、沙箱强度、语言栈。
- 对照本文第四章表格打分 1–5。
- 若插件化+Replay 权重最高 → DSH 优先。
- 若快速 Python demo → LangChain/CrewAI 可能更快。
- 若修开源 Issue benchmark → SWE-agent 参考。
- 结论写入 ADR，链 GitHub Project 卡片「Architecture Decision」。
O.7 读仓库时的知识产权与合规
Fork 实验遵守 LICENSE；Apache-2.0 注意 NOTICE 文件；GPL 插件勿与专有内核静态链接混淆（DSH 以 MIT/Apache 类为主，以官方为准）。贡献者 CLA 授予 patent grant；企业 contributor 需法务批准。
O.8 持续学习信号
Watch deepseek-harness Release、MCP spec Release、LangGraph minor Release。每季度更新个人对照表笔记。参加 七天学会子站 挑战赛获取反馈。
O.9 从读者到维护者
读完官方仓库 + 3 社区插件 + 1 对照项目后，你具备 triage Issue 能力。再完成 1 合并 PR + 1 插件 README 矩阵，你具备 plugin maintainer 初阶能力。GitHub Projects 管理你的插件 Roadmap，Fork experiments 文件夹证明学习能力——这是开源 Agent 运行时领域的 可验证成长路径。
O.10 与站内文档体系的关系
| 文档 | 角色 |
|---|---|
| intro | 架构入门 |
| getting-started | 安装运行 |
| development | 插件 API 工程 |
| best-practices | 生产安全 |
| from-zero-to-one | 7 天路径 |
| faq | 概念澄清 |
| 本文 github-projects | 开源阅读与协作 |
建议书签顺序：intro → getting-started → 本文 §1 官方仓库 → development → 本文 §4 对照表 → from-zero-to-one 实操 → best-practices 上线前。
O.11 结语（扩展）
GitHub 不仅是代码托管，更是 DeepSeek Harness 生态的协作界面。会读 deepseek-ai/deepseek-harness、会搜 dsh-plugin、会在 Projects 上管理版本列车、会用 Fork 做可复现实验——这四项技能组合，等价于在 Agent 运行时领域拥有 持续自我升级 的能力。立即打开官方仓库 README，开始 Week1 阅读计划；同时在 七天学会 DeepSeek Harness 注册 Day1 实验，读写结合，一周见成效。
附录 P：快速参考卡片
官方仓库首读路径：README → docs/architecture.md → AGENTS.md → CONTRIBUTING.md → packages → examples。
社区插件搜索：GitHub topic:dsh-plugin；安装前查 README 兼容性矩阵与五问评估（§3.2）。
贡献最小路径：Fork → good first issue → 小 PR（含测试）→ 响应 Review → merge。
插件 README 必填：概述、兼容性矩阵、安装、配置表、工具列表、开发命令、许可证。
GitHub Projects 字段：Stage / Target runtime / Preset / Risk。
Fork 实验分支：exp/YYYYMMDD-描述；记录于 docs/experiments/；每周 sync upstream。
对照学习推荐组合：DSH + MCP servers + Phoenix OTel；读 LangGraph 写对比笔记即可，不必全读。
资源主链：七天学会 DeepSeek Harness · 开发指南 · 入门介绍 · deepseek-ai/deepseek-harness。
Session 调试三板斧：插件树 CLI、依赖 graph mermaid、Session Replay breakpoint。
版本升级顺序：读 Release note → 更新矩阵 → staging Replay → canary → prod pin。
安全红线：不装无 peerDependencies 的社区插件；不 skip validate；Creator 仅隔离环境。
完成标准：能独立开 Issue（含 Session id）、能 Review 社区 PR Teardown、能维护插件 Project 路线图——即可自称熟悉 DSH 开源生态。
附录 Q：文档维护说明
本文与 开发指南 由本站维护，随 DeepSeek Harness 官方 Release 迭代。若发现 upstream 目录结构或命令变更，请提 Issue 或 PR 更新本站 docs/dsh 目录。版本锚点以读者阅读日期的 GitHub main 分支为准；生产环境务必 pin Release tag 而非跟踪 main。教学目的的开源链接均已在 §8 与附录列出；外部链接失效时以 GitHub 组织页搜索为准。欢迎将 Fork 实验笔记反向链到 插件社区 供他人参考与复现。
补充：企业团队可将本文 §6 Projects 模板复制到 GitHub Organization，字段名保持英文便于工具集成，卡片描述使用中文便于日常站会。个人学习者将 §7 Fork 实验记录链接到 从零到一 Day7 毕业作业提交清单，形成完整学习证据链。配合 最佳实践 做上线前安全检查；遇概念问题查阅 常见问题。
附录：开源协作实战剧本
S1. 第一次有效 Issue
模板：环境（OS/Node/DSH 版本）→ 最小复现 Profile → 期望/实际 → Session 片段（脱敏）→ 是否 Replay 可复现。缺少 Session 的 Issue 很难被处理。
S2. PR 分层
| 类型 | 审查重点 |
|---|---|
| 文档 | 是否与代码路径一致 |
| 插件 | Teardown、inject、测试 |
| 内核 | 兼容性与 semver |
| 安全 | 审批默认是否收紧 |
S3. 用 Projects 管插件路线图
列：Idea / Designing / Implementing / Review / Released。卡片字段：目标 Profile、风险级（含是否触及 Creator）、兼容版本。每周只允许有限 WIP，防止半成品插件污染 Bundle。
S4. Fork 学习法
- Fork 后只改一个插件；
- 写对比文档「改前/改后 Session」；
- 还原官方行为再尝试下一改动。避免一上来大爆炸式重构。
S5. 生态对照阅读（建议顺序）
Cordis/Koishi 插件生命周期 → DSH architecture → MCP 工具协议 → 任一 Agent 评测基准的工具面设计。对照问题：「能力如何注册？如何撤销？如何审计？」
S6. 社区发现
搜索 GitHub topic dsh-plugin；阅读其兼容性矩阵再装。无矩阵的插件默认视为实验。
S7. 贡献决策树
修文档？直接 PR。修插件 bug？附测试。改默认审批？先开 Issue 讨论威胁模型。涉及 Creator 默认放宽？应被拒绝。
S8. 发布后观察
关注：Issue 中 schema 变更投诉、Replay 失败、与新 Bundle 的 peer 冲突。维护 COMPAT.md 比维护华丽 README 更重要。