aaione/mini-agent-harness

mini-agent-harness

为深度理解而生的 Agent 运行时极简复刻系列 —— 从 DeepSeek Harness 起步，未来扩展 Codex、PI、Claude Code 等主流 Agent 实现的最小化可读投影。

项目定位

| 维度 | 说明 |
|------|------|
| 核心目的 | 让复杂 Agent 架构「可读、可跑、可对照、可实验」 |
| 目标受众 | 想在源码级深度理解 Agent 运行时原理的工程师、研究者 |
| 设计原则 | 单文件 ≤ 400 行、核心不变量可验证、逐行对照上游源码 |
| 实现策略 | 极简复刻 —— 保留架构骨架，剥离工程细节，保持可运行 |
| 扩展方向 | mini-codex / mini-pi / mini-claude-code / build-your-own-* 系列 |

当前包结构

mini-agent-harness/
├── packages/
│   ├── mini-deepseek-harness/      # 核心运行时复刻 (当前主包)
│   ├── code-surfer-anything/       # 通用代码冲浪轨道组件
│   ├── build-your-own-deepseek-harness/  # DeepSeek Harness 架构冲浪站
│   └── (未来) mini-codex / mini-pi / mini-claude-code / build-your-own-*
├── apps/
│   └── demo/                       # 外部消费验证
└── docs/                           # 架构对齐、设计系统、冲浪锚点

核心运行时：mini-deepseek-harness

~2000 行可读 ESM，复刻 DeepSeek Harness 架构骨架

| 模块 | 职责 | 关键设计 |
|------|------|----------|
| Session | 只追加事件日志 | 模型可见消息 = 投影得出，非存储 |
| AgentLoop | inbox 驱动 turn/step | 并发工具调度、step 内重试不增编号 |
| ToolRuntime | schema/execute 分离 | pre-execute → dispatch → post-execute → finalize |
| LlmRuntime | Provider 仅 complete/stream | Loop 零 SDK 依赖 |
| PromptRegistry | section + variable | scoped 遮蔽、waterfall 最终改写 |
| Scope | Cordis fiber 隔离 | 事件/插件/生命周期随 dispose 自动释放 |
| Composition | 8 行 CORE_BUNDLE | patch 整行替换，依赖图固化 |

pnpm add @mini-agent-harness/mini-deepseek-harness

import { createHeadlessHarness, jsonlSessionPersistence } from '@mini-agent-harness/mini-deepseek-harness'

const root = await createHeadlessHarness()
await root.plugin(jsonlSessionPersistence({ directory: './sessions' }))

root.effect(() => root.miniPrompts.register({
id: 'identity', order: 0, render: () => 'You are a helpful assistant.'
}))

root.effect(() => root.miniTools.register({
name: 'search', description: 'Search the web',
execute: async ({ query }) => Results for: ${query}
}))

const agent = root.miniAgents.create({ id: 'demo', provider: 'openai' })
const result = await agent.followup('What is DeepSeek Harness?')

完整包文档 →

研习基础设施

code-surfer-anything
通用代码冲浪轨道组件 —— 供所有 build-your-own- 复用

- Sticky per-stage 代码面板 + lesson-addressed focus 高亮
- Token 主题：近黑 #0B0B0B + 技术蓝 #6799FE
- 响应式 24px 移动端安全边距、硬件加速动效

pnpm add @mini-agent-harness/code-surfer-anything

build-your-own-deepseek-harness
从 mini 源码生成的架构冲浪站

- 8 版本化课程：src/versions/0.1.0-rc.x/ → Session → Agent → Tool → LLM → Prompt → Scope → Loop → Composition
- 滚动同步代码高亮，设计系统遵循 docs/design/DESIGN.md
- 推送 main 自动部署 GitHub Pages

未来每个 mini- 都将配套一个 build-your-own- 冲浪站，复用同一代码冲浪轨道。

快速开始

安装依赖
pnpm install

完整 CI：类型检查 + 测试 + 上游对齐 + 构建
pnpm run check

仅构建
pnpm run build

启动冲浪站开发
pnpm run dev

构建冲浪站 (→ _site/)
pnpm run build:site

验证包作为 linked dependency 可用
pnpm run verify:link

命令速查

| 命令 | 说明 |
|------|------|
| pnpm run check | 全流水线 (CI 入口) |
| pnpm run build | 构建所有包 |
| pnpm run dev | 冲浪站开发服务器 |
| pnpm run build:site | 生成静态站点 |
| pnpm run verify:link | 外部消费验证 |
| pnpm run typecheck | 类型检查 |
| pnpm run test | Vitest 测试 |
| pnpm run check:upstream | 对齐上游源码 (需网络) |
| pnpm run publish:harness | 发布核心运行时 |
| pnpm run publish:surfer | 发布冲浪轨道 |

开发者参考

核心源码 (mini-deepseek-harness/src/)

session.js           # 事件日志 + 投影 + restore/claim
agent.js             # Agent 定义 + inbox 驱动循环
agent-loop-invariant.js  # turn/step 状态机不变量
tools.js             # ToolRuntime 4阶段管线
llm.js               # LlmRuntime Provider 接口
prompt.js            # PromptRegistry section/variable
scope.js             # Cordis fiber 隔离
composition.js       # CORE_BUNDLE (8行) + patch
persistence.js       # JSONL 序列化
invariants.js        # 核心不变量注册表
types.js             # 类型定义

关键架构文档

| 文档 | 说明 |
|------|------|
| docs/architecture/UPSTREAM_ALIGNMENT.md | 逐模块对齐上游 DeepSeek Harness |
| docs/architecture/UPSTREAM_CORE_DEPENDENCY_MAP.md | 依赖图谱对比 |
| docs/architecture/MINI_ARCHITECTURE_REVIEW.md | 架构评审与取舍记录 |
| docs/design/DESIGN.md | 设计系统规范 (色彩/字体/间距/动效/断点) |

常见问题

| 问题 | 解决 |
|------|------|
| GitHub Pages 404 | Settings → Pages → Source: GitHub Actions |
| Node 版本报警 | 用 Node ≥ 22.19.0 (engines 在根 package.json) |
| pnpm 未找到 | corepack enable && corepack prepare pnpm@10.33.3 --activate |
| 类型检查失败 | 先构建核心包生成类型：pnpm -F @mini-agent-harness/mini-deepseek-harness run build |
| 冲浪锚点不同步 | pnpm run generate:source-snapshot && pnpm run check:upstream |
| demo 验证失败 | 确保核心包已构建 |
| Vite 启动卡住 | rm -rf node_modules/.vite && pnpm run dev |

设计系统 (冲浪站统一约束)

- 画布：#0B0B0B
- 唯一强调色：#6799FE
- 字体："Atkinson Hyperlegible Mono", "JetBrains Mono", monospace
- 移动端：24px 安全边距，断点 640/1024
- 动效：尊重 prefers-reduced-motion，仅 transform/opacity

路线图

- [ ] mini-codex — OpenAI Codex 运行时极简复刻
- [ ] mini-pi — PI (Personal Intelligence) 架构最小化复刻
- [ ] mini-claude-code — Anthropic Claude Code 运行时核心复刻
- [ ] 每新增 mini- 配套 build-your-own-* 冲浪站
- [ ] 统一冲浪轨道支持多运行时对照研习

贡献

提交前
pnpm run check

Commit 规范 (Conventional Commits)：

feat(core): add tool retry invariant
fix(site): correct mobile gutter to 24px
docs(design): add motion token spec

LICENSE

MIT