快速開始

Agent = dsh + 一组插件。 本索引同时浏览与分发这两者 —— DeepSeek Harness 生态的插件， 以及由它们组装成的完整 Agent。

站点：https://sunrisepeak.github.io/dsh-index

这个项目是什么#

1 · 生态浏览站。 收录值得装的 dsh 插件，可搜索，标明它做什么、字节从哪来， 以及生态随时间的增长曲线。

2 · 一条命令安装，两条路可选。 dsh 自己就能装插件，所以每个插件页先给出它的 原生命令；本索引的命令排在下面，补上 dsh 给不了的东西：sha256 校验与 CN 镜像。

3 · Agent 的分发渠道。 Agent = dsh + 一组插件 —— 在 dsh 自己的模型里 就是一个 profile。这里每个 Agent 是一个 xpkg 描述文件，xlings install 会解析成员、装齐、写好 profile，并注册一个以包名命名的命令。 一次安装，一个词就能跑：

xlings install dsh:agent-web-coding -y   →   agent-web-coding

profile 名同样是包名，所以 dsh --profile agent-web-coding 是同一件事的长写法。

快速开始#

xlings install dsh -y
xlings config --index-repo dsh:https://github.com/Sunrisepeak/dsh-index.git

xlings install dsh:agent-web-coding -y   # 一个完整 Agent
agent-web-coding                         # 运行它 —— 包名就是命令

最后一行不是笔误。装完一个 Agent，你会得到一个以它命名的命令， 经 xlings 的 xvm 注册，本质是 dsh --profile agent-web-coding 的别名。 因为这个名字归 xvm 管，带版本、按 subos 是白拿的：

xlings install dsh:agent-web-coding@0.2.0 -y
xlings use agent-web-coding 0.1.0        # 切换，只影响当前 subos

dsh --profile agent-web-coding 依然可用 —— 命令是别名，不是替代。

curl -fsSL https://d2learn.org/xlings-install.sh | bash

irm https://d2learn.org/xlings-install.ps1.txt | iex

三层#

插件组和 Agent 没有自己的字节，它们是几百字节的清单，载荷在成员身上。 成员必须是已镜像的包 —— 一个内容要在启动时回上游拉的"精选集"， 会把镜像本来要消除的失败模式全部继承回来。

dsh --profile agent-web-coding --patch ./extra.yml

Error: dsh: plugin tree failed to load: failed to apply loader entry include

安装#

每个插件页都给出两条命令，它们不等价：

# dsh 原生 —— 装了 dsh 就能用，直连源头
dsh plugin --profile web add dsh-cc-tui@0.1.6

# 本索引 —— sha256 校验，许可证允许时还有 CN 镜像
xlings install dsh:dsh-cc-tui -y

原生命令的 spec 逐包不同，在站点构建时实测决定，绝不靠猜：npm 确实按我们 pin 的版本提供的走名字，其余走 pin 死的 commit。今天是 17 个走名字、51 个走 commit —— 裸 bundle_name 只是包自己 package.json 的 name，不代表已发布。

# 添加本索引（namespace: dsh）
xlings config --index-repo dsh:https://github.com/Sunrisepeak/dsh-index.git

# 搜索与查看
xlings search dsh:tui
xlings list dsh:dsh-cc-tui

# 安装
xlings install dsh:agent-web-coding -y      # 一个 Agent
xlings install dsh:group-web-essentials -y  # 一个插件组
xlings install dsh:dsh-cc-tui -y            # 单个插件
xlings install dsh:dsh-cc-tui@0.1.6 -y      # 指定版本

# 改掉插件打印那一行里的 profile 名
XIM_DSH_PROFILE=work xlings install dsh:dsh-at-file -y

# 按 subos 切换版本 —— 对 Agent 来说就是切换它的命令指向哪个版本，
# 所以两个版本可以同时装着
xlings use agent-web-coding 0.1.0

# 卸载
xlings remove dsh:dsh-cc-tui -y

dsh-at-file is downloaded and pinned. It is not in any profile yet.
  Add it:     dsh plugin --profile web add /…/dsh-at-file-0.1.0.tgz
  Launch it:  dsh web

# 实际装了什么，以及层的组合顺序
cat ~/.dsh/profiles/<profile>/package.json
dsh --profile <profile> --dump-config | grep '^# == '

已镜像 vs 直连#

每个插件二选一，站点上有标：

由许可证决定，不是偏好：镜像即再分发。在 dsh-plugin topic 调研的 169 个 bundle 里，29 个完全没有 LICENSE，另有 13 个无法识别 —— 本索引无权镜像它们， 所以它们保持直连并如实标注。

定义一个 Agent#

这是本仓库最重要的一类贡献：把已经存在的插件组合成一个别人可以直接运行的东西。 Agent 是一份清单 —— 几百字节，列出成员，自己没有载荷。

Agent 和插件组是生成的，改源文件、不要改描述符；CI 会重跑展开，两者不会漂移。

// tools/agents.json
"agents": [
  { "name": "agent-web-coding", "version": "0.1.0",
    "description": { "en": "…", "zh": "…" },
    "groups": ["group-web-essentials"],   // 展开进 members
    "extra": ["dsh-notification"] }       // 再加这些插件
]

tools/gen_agents.py            # 写出描述符
tools/gen_agents.py --check    # CI 跑的

三条规则，全是拒绝而不是告警 —— 因为这里是索引在选组合：

成员被 pin 到版本和 commit，所以一个 Agent 指代一批固定的字节。

新增一个插件#

让扫描器去收集事实 —— 它先 pin 住 head sha，再在那个 sha 上读 package.json：

tools/discover.py --new --json /tmp/new.json
tools/sync.py --new /tmp/new.json

pkgs/<首字母>/<名字>.lua 下的描述符是纯数据 —— 没有 hook、没有 xpm、 没有 type。全部生命周期来自 template.lua，由 pkgindex-build.lua 在索引构建 时追加到每个描述符。

package = {
    spec = "1",
    name = "dsh-cc-tui",
    description = "Claude Code 风格全屏终端界面",
    repo = "https://github.com/ccch1mneyyy/dsh-cc-tui",
    licenses = {"BSD-3-Clause"},

    dsh = {
        kind = "plugin",                -- plugin | group | profile
        profile = "cc-tui",             -- 它自己 README 让读者输入的名字
        bundle_name = "dsh-cc-tui",
        versions = { ["0.1.6"] = { commit = "<40 位 sha>" } },
        latest = "0.1.6",
        needs_build = false,
    },
}

永远 pin 40 位 commit。这个生态里包名不可信：36 个社区仓库把自己命名进了 DeepSeek 在 npm 上真正拥有的 @deepseek-ai/ 作用域，裸名可能悄悄解析到别的代码。

用 agent 参与这个项目#

编写规范都写成了 skill，把路径给你自己的 agent，它就拿到了完整约定 —— 逐字段规则、两个 Lua 运行时各自会静默失败的缺口、以及提 PR 的要求。

阅读 https://github.com/Sunrisepeak/dsh-index —— 一个 xlings 包索引，分发
DeepSeek Harness 的 Agent，其中 Agent = Harness + Plugins。动手前先读
.agents/skills/xpkg-creater/SKILL.md 了解包的编写约定，读
.agents/skills/pr-workflow/SKILL.md 了解变更如何合入，设计依据在 .agents/docs/。
然后 <你要做的事>。

短路径见 docs/contributing.md。

保持跟进#

tools/discover.py 扫描 dsh-plugin topic，回答三个分开的问题， 每个问题各自成为一个 PR：

tools/discover.py --new     # 索引还没收录的仓库
tools/discover.py --bump    # 已收录但上游发了新版
tools/discover.py --audit   # 已收录但 pin 的 commit 在上游消失了

--audit 永不自动合入。pin 的 sha 消失意味着 force push 或删库， 静默跟进会让"本索引 pin 死这些字节"这个承诺无声失效。

检查#

lua5.4 tests/libxpkg_sandbox_harness.lua .   # 索引构建回归门
git checkout -- pkgs/                        # harness 会追加，跑完还原
pytest -q                                    # 描述符 schema 与策略
tools/gen_agents.py --check                  # 组合包与其源文件一致

沙箱门不是可选项。xlings 在 libxpkg 的最小 plain-Lua 沙箱里运行 pkgindex-build.lua，那里 cprintf / try / raise 全是 nil； 混进任何一个，构建出的索引会静默丢掉全部 xpm 段， 走 artifact 路径的所有用户安装都会挂。

相关链接#

• DeepSeek Harness · 插件文档
• dsh-plugin topic —— 上游的发现入口
• xim-pkgindex —— xlings 官方索引（xim:dsh 在那里）
• awesome-dsh-plugins —— 生态兼容性报告

许可证#

Apache-2.0。每个被收录的插件保留自己的许可证；本仓库只再分发许可证允许的那些。