moyun-ultimate/AGENT.md
moyun 7b3e7f0ec8 feat: 0.9.1 - AGENT.md so "have your agent install it" actually works
Telling an agent "install https://.../moyun-ultimate" currently fails, because
the first thing it finds is install.ps1 and running a third-party script is
exactly what it is right to refuse.

AGENT.md gives it three paths that involve no script at all:

  A (recommended) copy standalone/moyun-armor/SKILL.md into <project>/.dsh/skills/
     - stays inside the workspace, so no extra permission is needed
  B install as a prompt-only plugin using pure file operations
     - copy two directories, add two lines to package.json, verify JSON
  C full plugin, with the impact table it must show the user first

It also states where the agent should stop and ask (writing \,
running scripts, changing package.json without a backup), a troubleshooting
table, and a one-liner to ask the user which tier they want.

README now opens with a pointer to it, so any agent landing on the repo sees it
before anything else.
2026-11-17 15:50:38 +08:00

6.6 KiB
Raw Blame History

AGENT.md — 给 AI agent 的安装说明

人类用户对你说「帮我装 https://git.lingdongjiansuo.cn/moyun/moyun-ultimate 这个插件」时, 按这份文件操作,不要执行仓库里的 install.ps1。

零、先确认一件事

这个仓库提供三种级别的安装,侵入性依次递增。先问用户要哪一种,或者按下面的默认建议选。

级别 会写什么 会联网 要重启
A. 技能版(推荐先试) 只写目标技能目录 ❌ ❌
B. 提示词插件 $DSH_HOME 下插件目录 + package.json 两行 ❌ ✅
C. 完整插件 同上 + $DSH_HOME/skills 63 个目录 ✅ 启动时一次 ✅

如果用户只是想要「人格 / 不废话 / 先给产物」这类行为改变,选 A。 它不需要碰系统。


A. 技能版(零系统改动)

原理:SKILL.md 是纯文本行为准则,复制到技能目录即可被 agent 加载。

步骤

  1. 下载这个文件的内容:
https://git.lingdongjiansuo.cn/moyun/moyun-ultimate/raw/branch/main/standalone/moyun-armor/SKILL.md
  1. 写到下面任一个位置(优先第 1 个,完全在 workspace 内):
<当前项目根>/.dsh/skills/moyun-armor/SKILL.md     ← 推荐,不需要任何额外授权
~/.agents/skills/moyun-armor/SKILL.md             ← 用户级,所有项目生效
  1. 告诉用户:新开一个会话,用 skill 工具加载 moyun-armor。

验证

Test-Path "<项目根>/.dsh/skills/moyun-armor/SKILL.md"
# 应为 True

不需要重启,不需要改任何配置。


B. 提示词插件(只注入六段提示词,不联网、不碰权限)

原理:把插件包装进 profile,但用 prompt-only 的 bundle patch —— 只注入提示词, 不同步技能、不联网、不接管权限。

前置:确认 profile 目录

$DshHome = if ($env:DSH_HOME) { $env:DSH_HOME } elseif (Test-Path "$env:USERPROFILE\.dsh") { "$env:USERPROFILE\.dsh" } else { throw "找不到 DSH_HOME" }
$ProfileDir = Join-Path $DshHome "profiles\desktop"
Test-Path $ProfileDir      # 应为 True;如果不在这里,列一下 profiles 目录看有哪些

如果 profiles\desktop 不存在,列出 $DshHome\profiles 下的目录,让用户确认用哪个。

步骤(全部是文件操作,不跑脚本)

1. 拿到包

$tmp = Join-Path $env:TEMP ("moyun-" + [guid]::NewGuid().ToString('N').Substring(0,8))
Invoke-WebRequest "https://git.lingdongjiansuo.cn/moyun/moyun-ultimate/archive/main.tar.gz" -OutFile "$tmp.tgz"
tar -xzf "$tmp.tgz" -C (Split-Path $tmp)

解压后目录形如 moyun-ultimate\。

2. 复制到两个位置

$src = "<解压出来的 moyun-ultimate 目录>"
$plugDir = Join-Path $ProfileDir "plugins\moyun-ultimate"
$runDir  = Join-Path $ProfileDir "node_modules\moyun-ultimate"
foreach ($d in @($plugDir, $runDir)) {
    if (Test-Path $d) { Remove-Item $d -Recurse -Force }
    New-Item -ItemType Directory -Force -Path $d | Out-Null
    Copy-Item "$src\*" $d -Recurse -Force
}

3. 用 prompt-only 的 patch 覆盖

foreach ($d in @($plugDir, $runDir)) {
    Copy-Item (Join-Path $src "cordis.patch.prompt-only.yml") (Join-Path $d "cordis.patch.yml") -Force
}

4. 改 package.json 两处

先备份:

$pkgJson = Join-Path $ProfileDir "package.json"
Copy-Item $pkgJson "$pkgJson.bak-moyun-$(Get-Date -Format 'yyyyMMdd-HHmmss')" -Force

在 dependencies 里加一行:

"moyun-ultimate": "file:./plugins/moyun-ultimate",

在 dsh.profile.bundles 数组末尾加一项:

"moyun-ultimate"

改完必须验证 JSON 合法:

$j = Get-Content $pkgJson -Raw -Encoding UTF8 | ConvertFrom-Json
$j.dependencies.'moyun-ultimate'                      # 应输出 file:./plugins/moyun-ultimate
$j.dsh.profile.bundles -contains 'moyun-ultimate'     # 应为 True

注意:PowerShell 5.1 的 ConvertFrom-Json 对无 BOM 的 UTF-8 中文有时会误报。 如果报错但文件其实没问题,改用 python 验证: python -c "import json;json.load(open(r'<路径>',encoding='utf-8'))"

5. 告诉用户重启 DSH(完全退出,包括托盘图标)

验证

重启后让 agent 调用:

moyun_ultimate_profile

期望返回里看到:

  • version 是包里的版本号
  • layers 是 6 项且全部 enabled: true
  • permission.builtin: false(prompt-only 不接管权限)
  • update.checked 为 false 或 checkUpdate 未开启

C. 完整插件(含权限层 + 63 技能 + 联网查更新)

只有用户明确说「我要完整功能 / 我要工具能直接跑」时才做这个。

把 B 的第 3 步跳过(不要覆盖成 prompt-only),直接用包里自带的 cordis.patch.yml, 其余步骤相同。

额外影响(必须先告知用户):

影响 说明 能否关
沙箱放开 工具可读写任意路径 permission: false
审批自动通过 工具调用不弹窗 同上
写 $DSH_HOME/skills 同步 63 个技能目录 syncSkills: false
启动联网 GET 一次 Release 元数据 checkUpdate: false

详细清单在仓库根的 SECURITY.md。


拒绝执行的边界(给 agent 自己看)

以下情况应该先问用户,不能自行决定:

  1. 写 $DSH_HOME(workspace 之外)—— 需要用户明确同意
  2. 执行 install.ps1、update.ps1 等脚本 —— 能不用就不用,优先走本文件的文件操作
  3. 改 package.json —— 必须先备份,并在改完后验证 JSON 合法
  4. 完整模式(C)—— 必须先把上面的影响表告诉用户

出错了怎么办

现象 处理
moyun_ultimate_profile 找不到工具 插件没加载:检查 dsh.profile.bundles 里有没有那一项
状态条不显示 检查 package.json 的 exports["./client"] 是否为 ./client.js
提示 client-modules ... exports no "./client" 同上
JSON 解析失败 用备份 package.json.bak-moyun-* 还原,重来
想全部撤掉 删两个插件目录 + 从 package.json 移除那两处,或用备份还原

最省事的做法(推荐给 agent)

先问用户一句:

这个插件有两种装法:一种只复制一个文本文件(不改系统),一种要装进 DSH(会写 $DSH_HOME 并要求重启)。你要哪种?

  • 用户选「一个文本文件」→ 走 A,30 秒完成,零风险
  • 用户选「装进 DSH」→ 走 B(默认)或 C(用户要完整功能)