# deepseek-harness-study

**Repository Path**: ketty9527/deepseek-harness-study

## Basic Information

- **Project Name**: deepseek-harness-study
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepSeek Harness（个人学习仓库）

这是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）的个人学习用副本，用于系统学习一个"一切皆插件"的 Agent 框架是如何设计与实现的。仓库不参与上游开发，不做生产用途，仅服务于我自己的阅读、调试与小改动练习。

DeepSeek Harness 由 [DeepSeek AI](https://deepseek.com) 开发，基于 [Cordis](https://github.com/cordiverse/cordis)，设计思想参见论文 [_A Programming Paradigm for Spatiotemporal Composability_](https://github.com/cordiverse/paper)。

> 内容基线：2026 年 8 月 17 日。项目处于快速演进的预发布阶段，学习时先理解稳定的设计，再通过源码确认具体名称。

## 学习入口

主入口是 [`learning/dsh-从零开始学习指南.md`](learning/dsh-从零开始学习指南.md)——一份面向有 Java 工程经验、但刚接触大模型 / Agent / TypeScript / Node.js 的开发者的从零到精通教程。

这份指南不追求"看过项目"，而是要求最终能完成四件事：

- 解释一次 Agent 回合（turn）如何运行
- 定位一个需求应挂在哪个扩展点
- 独立实现、测试并组装一个插件
- 判断一个改动是否破坏日志、生命周期、能力 seam、包依赖或用户可见行为

> 学习指南是个人教程，**不属于**仓库受治理的 `docs/` 文档树。架构与 API 一律以 `docs/` 下的权威文档和源码为准，指南只负责把它们串成一条可走的学习路径。

## 八周学习路线

按每周 6–10 小时设计，时间不足可拉长，但不要跳过动手和验收。每周产出一张图、一段运行证据和一份不超过一页的总结。

| 周次 | 主题 | 目标 |
| --- | --- | --- |
| 第 1 周 | 环境、AI 基础与 TypeScript 最小集 | 能运行仓库检查，解释模型 / Agent / tool calling / streaming / context 的区别，能阅读普通 TypeScript |
| 第 2 周 | 完整完成 Cordis 教程 | 能独立写函数插件、Service、typed event、waterfall、Config schema 和 HMR-safe effect |
| 第 3 周 | 追踪一个完整 turn | 能从输入追到 `turn/end`，区分 durable event 与 live event |
| 第 4 周 | 工具、SessionEvent 与模型体验 | 能读懂并测试一个真实模型工具，理解模型可见内容如何落日志 |
| 第 5 周 | 吃透一个 capability seam | 能从 Service Definition 追到两个 Provider、一个 Consumer 和最终装配 |
| 第 6 周 | 组装、持久化与恢复 | 理解"代码存在"与"运行时已挂载"的区别，能解释 session 如何跨重启恢复 |
| 第 7 周 | 接入面、权限与真实产品行为 | 能画出 Web / CLI / SDK / ACP 中至少一条端到端调用路径，理解权限必须在执行入口强制 |
| 第 8 周 | 完成一个小型端到端贡献 | 把前七周拼成一个可运行、可验证的小改动 |

完整每周的阅读、动手、产出与验收标准见指南[第 16 节](learning/dsh-从零开始学习指南.md)。

## 指南目录

1. 如何使用这份指南
2. 先补齐 AI 与 Agent 基础
3. 从 Java 迁移到 TypeScript、Node.js 与 ESM
4. 建立 DeepSeek Harness 全局架构图
5. 理解 Cordis：一切皆插件的地基
6. 吃透一次 turn 的完整运行链路
7. 核心运行时子系统
8. 能力 seam：定义、提供方与消费者
9. 配置、profile、bundle 与 preset
10. 会话日志、持久化、查询与恢复
11. 交互、权限、前端、协议与外部接入
12. 仓库工程模型与代码规范
13. 如何设计并实现一个改动
14. 测试、快照与验证策略
15. 调试方法与常见误区
16. 八周学习与实战路线
17. 精通标准与自测题
18. 速查附录

## 从源码运行

学习过程中需要实际运行和调试仓库。环境要求：Node.js `^22.19.0 || >=24.0.0`，仓库固定 `pnpm@11.7.0`。

```sh
pnpm install            # 安装依赖
pnpm run typecheck      # 验证开发环境可用
pnpm run build          # 构建 lib/ 与运行时产物
pnpm dsh web            # 启动 Web UI（默认 http://127.0.0.1:3080）
```

涉及真实模型调用的命令（`pnpm dsh`、e2e 测试、部分 demo）需要 `DEEPSEEK_API_KEY`，可在根目录 `.env` 配置；无密钥时相关测试会自动跳过。常用命令完整清单见 [AGENTS.md](AGENTS.md#commands)。

## 权威文档

学习指南负责"怎么读"，`docs/` 负责"是什么"。遇到不一致一律以源码和 `docs/` 为准：

- [架构文档](docs/architecture.zh.md) — 改动 `packages/` 前必读
- [开发指南](docs/development.zh.md) — TypeScript 工程布局、编译面、规范
- [Cordis 入门](docs/cordis-primer.zh.md) 与 [Cordis 教程](docs/cordis-tutorial/index.zh.md) — 一切皆插件的地基
- [防御性编程模式](docs/defensive-patterns.zh.md) — 生命周期、并发、子进程、拆卸
- [测试策略](docs/testing.zh.md) — 测试层级与密钥策略
- [Agent 生命周期](docs/agent-lifecycle.md) — turn / step / inbox 流程

给 Agent 的工作约束见 [AGENTS.md](AGENTS.md)。

## 关于上游

本仓库是上游项目的只读学习副本，不接收 issue、不发布产物、不参与社区。上游的社区与贡献渠道：

- 反馈与讨论：[GitHub Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions)
- 插件发现：[`dsh-plugin`](https://github.com/topics/dsh-plugin) 话题
- 社区：[DeepSeek Harness Discord](https://discord.gg/Ycq5dCaS4)

## License

[MIT](LICENSE)。第三方依赖及许可证见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。