dsh-achievements 🏆

> DeepSeek Harness（DSH） 的游戏化插件：68 个成就横跨七条五档成长线、会话行为徽章与轨迹链——实时解锁 toast、设置页徽章墙、可分享成就卡、Agent Wrapped，以及面向第三方 Pack 的公开 SDK。零核心改动。

English | 简体中文

📸 运行效果

✨ 亮点

• 68 个成就、三条产品线 —— 七条五档终身成长线（稀有度严格 普通 → 罕见 → 稀有 → 史诗 → 传说）、10 个单会话行为徽章、以及四条额外链上的 20 个会话轨迹成就（其中一条完全隐藏）。每次解锁都赚取 XP、提升等级与 persona，并在徽章墙上留下时间戳。
• 实时解锁，无需额外服务 —— 新成就经 SSE 实时推送到浏览器，另有 30s 轮询兜底（窗口聚焦/可见时立即刷新）。首次快照只做基线，重装与升级永远不会触发 toast 风暴。
• 零核心改动 —— Host 半只监听官方 session/event 事件缝：turn/end、step/start、assistant/message、step/end、tool/call、tool/result，以及 Code Mode 的 tool/code-dispatch。全部只读事件，不打核心补丁、不改运行时。
• 纯函数、可独立单测的核心 —— 严格三层流水线：事件分类器 → 状态 reducer → 解锁 evaluate。每一层都是纯函数且有独立测试：19 个测试文件、251 个用例，全部通过。
• 跨会话持久化、平滑升级 —— v2 状态（profile + 会话桶）以 JSON 存在 DSH 主目录；v1 状态无损迁移。终身计数落在 profile 上，不依赖 64 会话保留窗口；升级时缺失计数保守回填为可证明下界，已满足的里程碑在启动时静默补解锁（不走 reducer、不写 session、不广播）。
• O(1) 轨迹统计 —— P7 会话事实只在低频边界维护（step/start、assistant/message、step/end、settled 工具调用）；逐 token 的 chunk 从不被消费或持久化。
• 隐私安全内建 —— 分享文本、分享卡、Agent Wrapped 与成就链只读聚合计数、成就元数据、persona 与等级；文件路径与命令字符串永不离开引擎。
• 开放 SDK —— 第三方 Host 插件通过 ctx.achievements.register / registerPack 注册成就，与内置成就走完全相同的求值路径；重复 id 立即抛错。其它客户端插件经 ctx.achievementsState 读取状态。

🏅 成就体系（68 个）

成就分两条产品线。七条长期成长线各含五档，稀有度严格 普通 → 罕见 → 稀有 → 史诗 → 传说（新增里程碑 XP 为 10 / 30 / 75 / 175 / 400）：

| 成长线 | 普通 | 罕见 | 稀有 | 史诗 | 传说 |
|---|---|---:|---:|---:|---:|---:|
| 🎬 回合 | 1 | 25 | 50 | 100 | 500 |
| 🔧 工具调用 | 1 | 25 | 100 | 500 | 2000 |
| 💬 会话 | 1 | 10 | 50 | 200 | 500 |
| 🌅 活跃天数 | 1 | 7 | 30 | 100 | 365 |
| 📖 文件读取 | 10 | 100 | 500 | 2500 | 10000 |
| ✏️ 文件修改 | 1 | 10 | 50 | 250 | 1000 |
| 🧪 测试运行 | 1 | 10 | 50 | 250 | 1000 |

特殊成就 —— 连续天数（streak-3 / streak-7）、早期额外节点 ten-turns，以及 10 个单会话行为徽章：

P7 轨迹链（20 个成就，稀有度严格 普通 → 罕见 → 稀有 → 史诗 → 传说，XP 10 / 20 / 40 / 70 / 120）。只读低频边界，不逐 token 持久化：

⚙️ 架构

DSH session/event（turn/end、step/start、assistant/message、step/end、tool/call、tool/result、tool/code-dispatch）
→ src/events.ts        分类器    — 原始 payload → 标准化 AchievementEvent + ToolSummary
→ src/reducer.ts       reducer   — 纯 reduceState：profile 计数 + 会话行为 + P7 轨迹事实
→ src/achievements.ts  evaluate  — applyEvent：buildContext + 对每个未解锁 def 求值
→ src/index.ts         Host      — 持久化 JSON → SSE 推送（unlock）+ 只读 HTTP API；启动静默 reconcile
→ src/client/          Browser   — EventSource + 30s 轮询 → 徽章墙 + 解锁 toast

三层完全解耦、可独立单测；规则层永远不直接读 Harness 的 tool payload。浏览器 bundle 只能运行时 import 浏览器安全的模块（tsdown.config.ts 的纯度门禁会拦截任何 node:* 越界导入）。

📦 安装

前置：DSH（dsh web 可运行）、Node ≥ 22.19。

# GitHub 安装（预构建 lib/ 已提交，无需 allowBuilds）
dsh plugin --profile web add "github:Blaczz/dsh-achievements#main"

# 本地目录安装（Windows 上 npm pack 最稳，别用 `link:`）
cd dsh-achievements && npm install --legacy-peer-deps && npm run build
npm pack --ignore-scripts
dsh plugin --profile web add "<绝对路径>\dsh-achievements-0.2.0.tgz"

安装后重启 dsh web，然后正常使用——完成第一个回合即解锁第一个成就（所有统计走官方事件缝，正常对话即可）。

🎮 使用

1. 正常对话、让 agent 干活——回合、工具调用、新会话、每日活跃都会静默累计；解锁新成就时右下角弹出 toast（带稀有度配色、XP 与风味文本）。
2. 设置 → 🏆 成就 展示完整体验：
   - 档案卡 —— persona、等级与 XP 进度、已解锁/总数、常用工具与稀有度分布；
   - 终身计数 —— 回合 / 工具调用 / 会话 / 活跃天数 / 读取 / 修改 / 测试，外加当前与最长连续天数；
   - 徽章墙 —— 按七条成长路线与特殊/轨迹链折叠，组 header 直接显示进度条；支持"全部 / 未解锁 / 已解锁"筛选；已解锁带时间戳、未解锁置灰，隐藏成就未解锁时仅显示 ???；
   - 会话战报 —— 最近会话的回合、步骤、最深单轮、工具调用与读/改/测拆分；
   - 🎁 Agent Wrapped 与 📤 分享 —— 本地、私密的年度总结与可分享成就卡。

🔌 开发者：ctx.achievements SDK

从宿主插件注册自定义成就——内置与第三方 Pack 共享同一条求值路径与同一个 registry（重复 id 抛错）：

export const inject = ['achievements']

export function apply(ctx: Context): void {
ctx.achievements.register({
id: 'python-first-run',
icon: '🐍',
title: { zh: '蟒蛇出洞', en: 'First Python Run' },
description: { zh: '首次运行 Python', en: 'Run Python for the first time' },
rarity: 'uncommon',
xp: 20,
scope: 'session',
evaluate: ctx => ({ unlocked: ctx.session.toolCalls >= 1 }),
})
}

也可注册整个 Pack：ctx.achievements.registerPack({ id, version, name, achievements })。注册即 reconcile——已满足的 lifetime Pack 无需等待下一个实时事件即可解锁。完整指南见 docs/SDK.md，可运行示例见 examples/python-pack.ts。

浏览器侧，其它客户端插件通过 ctx.achievementsState.refresh() / ctx.achievementsState.unlockedIds() 读取状态。

🛠️ 本地开发

npm install --legacy-peer-deps
$env:DSH_NODE_MODULES = "$env:USERPROFILE\.dsh\profiles\node_modules"   # PowerShell；本地运行时 symlink
npm run setup:dsh-workspace
npm run verify     # ★ 一键门禁：clean + typecheck + test + build（含浏览器纯度门禁）
npm test           # vitest — 19 文件 / 251 用例（引擎规则、连击、幂等、SDK、manifest…）

> 注：若 npm run build 报 Failed to import module "unrun"，先执行一次 npm install --no-save unrun（tsdown optional peer，建议 Node ≥ 22.19）。

📁 目录结构

dsh-achievements/
├── package.json            # dsh.bundle.patch + dsh.client 双契约
├── cordis.patch.yml        # bundle 补丁层
├── tsdown.config.ts        # client bundle + 浏览器纯度门禁
├── scripts/                # build / clean / setup-dsh-workspace / verify
├── docs/SDK.md             # 第三方作者指南
├── examples/python-pack.ts # 可运行的示例 Pack
├── src/
│   ├── index.ts            # Host 半：事件接线、registry、持久化、HTTP + SSE、SDK
│   ├── events.ts           # ★ 事件分类器（标准化 AchievementEvent + ToolSummary）
│   ├── reducer.ts          # ★ 纯 reducer（reduceState / buildContext）
│   ├── achievements.ts     # ★ 纯引擎（applyEvent）+ 领域模型 + 68 个内置成就
│   ├── state.ts            # State v2（profile + sessions）、迁移、JSON 持久化
│   ├── sdk.ts              # createAchievementRegistry + AchievementPack
│   ├── gamification.ts     # levelOf / xpForLevel / RARITY_META（浏览器安全）
│   ├── profile.ts          # Profile ViewModel + persona + 稀有度汇总（浏览器安全）
│   ├── share.ts            # 分享卡 / Agent Wrapped / 成就链（浏览器安全、隐私安全）
│   ├── api.ts              # API 路径常量 + SSE 帧格式（浏览器安全）
│   └── client/             # 浏览器半
│       ├── index.ts        # apply：ctx.achievementsState + 轮询 + SSE + 槽位注入
│       ├── achievements-client.ts  # 状态 HTTP client
│       ├── badge-panel.tsx # 徽章墙（settings.section），分组源自链模型而非硬编码
│       ├── toast.ts        # 解锁 toast（零依赖 DOM）
│       └── unlock-tracker.ts  # toast 基线去重（纯函数）
└── tests/                  # 19 个 spec：classifier / reducer / evaluate / state / SDK / 链…

🧩 生态定位

• 填补空白 —— DSH 生态此前无统一成就/徽章系统（社区调研明确点名"暂无真正游戏化任务/成就/等级系统"）。
• 与 dsh-soundscape 同一套双面包范式 —— Host 走官方事件缝驱动纯引擎；浏览器半是 client 插件（settings.section + 状态轮询）。
• 零核心改动 —— 只读事件 + 自有状态文件 + ctx.effect 注册。本仓库是 Blaczz/dsh-achievements 的 fork，在其基础上扩展了行为 + 轨迹成就、SDK 与分享层。

🛡️ DSH STORE 上架契约

• 清单身份 —— repository 指向 canonical Blaczz/dsh-achievements；bundle 入口 id（cordis.patch.yml）为插件自有 dsh-achievements，与已批准目录占用的 achievements / ui-achievements（旧 @wjnct55555/dsh-achievements-bundle）保持区分，只做增量注册、不冒用他人入口。
• 兼容声明 —— dsh.compatibility 声明 DSH 范围、Node 范围与 dshReleases 逐版本精确记录；只有在该精确版本上真实跑过一次一次性 Profile 才标 compatible，其余保持 unknown。
• 一次性 Profile 证据 —— scripts/store-evidence.mjs 会引导隔离 Profile（全新临时 $DSH_HOME、固定官方 @deepseek-ai/dsh@ + @deepseek-ai/dsh-web-app@）、安装打包产物、校验组合配置、无头启动 web 至监听、再卸载并清理 Profile。已捕获运行：
• docs/store-evidence-0.1.5-alpha.1.md —— 在 @deepseek-ai/[email protected] 上 install / start / uninstall 通过。

⚖️ License

MIT © 2026 Blaczz（上游）。独立社区插件，与 DeepSeek Harness 无关。