agpa-dsh-plugin

agpa-dsh-plugin

English | 中文

把 AGPA（Agent Player Achievements，npm @eiainano/agpa，源码在 ~/WorkSpace/forClaude/AgentPlayerAchievements）接到 DeepSeek Harness (dsh) 的 Cordis 插件。

设计目标（最高性价比）：DSH 侧不复制任何成就逻辑。所有 achievement_* 工具都是薄壳，把参数原样转发给已发布的 AGPA MCP 服务（@eiainano/agpa 的 agpa-mcp bin）。于是 AGPA 的引擎、成就定义、profile、~/.agent-achievements 数据在 Claude Code / DSH / 其他工具之间完全共享——cross_agent 成就自动生效。

分层与文件

目录结构

forDSH/agpa-dsh-plugin/
├─ cordis.patch.yml        # insert 行 id=agpa name=agpa-dsh-plugin
├─ package.json            # dsh.bundle.patch → cordis.patch.yml
├─ tsconfig.json           # NodeNext → lib/
├─ src/
│  ├─ index.ts             # export name='agpa'; inject=['tools']; apply()
│  ├─ tools.ts             # 7 × ctx.tools.register(defineTool(...))
│  ├─ agpa-bridge.ts       # 最小 MCP 客户端（spawn agpa-mcp）
│  ├─ events.ts            # session/event → CC-style 归一（AutoTrackFeed）
│  └─ hook-runner.ts       # 串行 spawn `agpa-hook auto` 摄入子进程
├─ scripts/
│  ├─ install-skills.mjs   # 复制 skills → $DSH_AGENTS_HOME/skills
│  └─ smoke-bridge.mjs     # 真机冒烟：调 AGPA 只读 stats
└─ skills/agpa/SKILL.md    # AGPA 工作流手册

命令

npm install --legacy-peer-deps   # 仅用于类型检查的开发依赖
npm run typecheck                # 对着真实 @deepseek-ai/dsh-tools 类型检查
npm run build                    # tsc → lib/
npm run smoke:bridge             # 真机验证 bridge ↔ AGPA MCP（只读 stats）
npm run install-skills           # 复制 skills/agpa → ~/.agents/skills/agpa
npm pack                         # 产出 agpa-dsh-plugin-<版本>.tgz

装进 dsh

已发布到 npm：agpa-dsh-plugin。

# 1) 从 registry 加入 profile（bundle 层，重启生效）
dsh plugin --profile web add agpa-dsh-plugin

# 2) 安装模型工作流 skill：包内已带 skills/agpa，复制到 skills 根即可
#    （git clone 开发时用：npm run install-skills）
cp -r ~/.dsh/profiles/web/node_modules/agpa-dsh-plugin/skills/agpa ~/.agents/skills/

# 3) 重启后离线检查合成树里是否出现 agpa 行
dsh --profile web --dump-config | grep -A3 agpa

本地开发（改源码时）：

npm run build && npm pack                 # prepack 会自动先 build
dsh plugin --profile web add ./agpa-dsh-plugin-<版本>.tgz

出现行但工具列表里没有 → 代码问题（看 dsh 日志）；行都没出现 → 组合问题 （name 未解析 / files 漏了 cordis.patch.yml）。

环境变量

桥接/摄入子进程固定注入 AGPA_TOOL_SOURCE=dsh，让事件正确打上工具来源 （落库为 tool_source:"dsh"，与 Claude Code 的 claude-code 并存于同一 store）。

状态 / 路线

• Phase 1（本仓库）：7 个工具壳 + MCP 桥（已验证可连真实 AGPA，返回 stats 且 tool_source=dsh）+ SKILL
  • 2026-09-09 已在真实 dsh 0.1.2-rc.1 端到端验证：dsh plugin --profile web|headless add <tgz> 装进两个 profile； headless 实跑任务成功调用 achievement_stats，经桥接返回共享 store 真实数据（75/212、level 6、10,592 XP）。
• Phase 2（本仓库，0.1.11 已发布 npm）：事件自动采集，真机 e2e 通过、开箱即用。
  • events.ts 订阅 dsh session/event，把 tool/call+tool/result → PostToolUse(Failure)、 user/message（source.kind==='user'）→ UserPromptSubmit 归一成 CC-style payload（source:'dsh'）； 每个 payload spawn 一个 agpa-hook auto 摄入进程（hook-runner.ts）。
  • headless 实跑（Write/Bash）后，~/.agent-achievements/profiles/neo/event.log 出现 tool_source:"dsh" 的 file.create/file.write/command.run/tool.complete 等行。
  • 实测关键坑：tool/result.data 顶层没有 callId（tool/call 才有）； 关联键 ${turn}:${step}:${callId} 的 callId 藏在 result.data.message.source.callId （= content[].toolCallId）。事件名一律以锁定的 dsh 0.1.2-rc.1 实测为准 （session/event 还广播 permission/preset、assistant/chunk 等噪音类型，均已忽略）。
  • AGPA 0.1.10 已发布并带 agpa-hook bin，插件的默认摄入命令 npx -y -p @eiainano/agpa@0.1.10 agpa-hook auto 开箱即用（仅 AGPA_AUTOTRACK=1 即验证通过）。 本地开发仍可用 AGPA_HOOK_CMD 指 checkout 的 tsx src/cli/hook.ts auto。
  • 摄入子进程 detached 启动：短命 headless 进程退出不会 SIGTERM 掉在途摄入 （首次 npx 冷缓存下载时可能较慢，detached 保证事件不丢；常驻 web 会话本就不受影响）。
• Phase 3：可选 dsh.client 的 XP/成就小组件，或直接复用 AGPA dashboard(:3867)。

已知注意点

1. 本机 dsh 暂无法启动（2026-09-09 修，2026-09-15 二次修）：workbuddy 的 binary manager 升级 node 时会整个替换带版本的 prefix（versions/22.22.2-2 → versions/22.22.2-3）， 清空其中全局包。所以 dsh/pnpm 已不再装在版本 prefix 里，改到稳定目录 ~/.local/share/dsh-runtime；~/.local/bin/dsh 动态读 ~/.workbuddy/binaries/node/versions/current 取 node 版本，并把 $DSH_HOME/bin（pnpm） 与该 node 的 bin 加进 PATH。安装 prefix 内全局包务必显式用 "$NODE" "$PREFIX/lib/node_modules/npm/bin/npm-cli.js" i -g <pkg> --prefix "$PREFIX"， 否则 npm wrapper 的 shebang 会落到 PATH 上的 homebrew node。
2. 运行期解析：外部插件裸 import @deepseek-ai/dsh-tools（value）与 @deepseek-ai/cordis（type-only）经 dsh host 映射到 in-box 树，均可在 0.1.2-rc.1 解析（本插件的 defineTool value import 已实跑验证）。
3. DSH 是 developer preview：cordis.patch.yml/dsh 字段/事件名都可能随版本变化。 package.json 的 peer 只声明 @deepseek-ai/cordis（类型与闭包注入由 dsh 提供）。
4. 事件名以 pinned 版本为准：采集所订阅的类型已在锁定的 0.1.2-rc.1 上真机核过 （见 Phase 2）；若 dsh 升级，先打开对应版本的 SessionEventMap 复核，别照搬 master 文档。
5. 工具 schema 用了 JSON-schema 风格字面量；如需数值范围校验，AGPA 侧目前未做 强校验，描述里已注明允许范围。
6. 若装不进 profile，先确认 npm pack 的 files 里确实有 cordis.patch.yml。