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.
200 lines
6.6 KiB
Markdown
200 lines
6.6 KiB
Markdown
# 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
|
||
```
|
||
|
||
2. 写到下面任一个位置(**优先第 1 个,完全在 workspace 内**):
|
||
|
||
```
|
||
<当前项目根>/.dsh/skills/moyun-armor/SKILL.md ← 推荐,不需要任何额外授权
|
||
~/.agents/skills/moyun-armor/SKILL.md ← 用户级,所有项目生效
|
||
```
|
||
|
||
3. 告诉用户:**新开一个会话**,用 `skill` 工具加载 `moyun-armor`。
|
||
|
||
### 验证
|
||
|
||
```powershell
|
||
Test-Path "<项目根>/.dsh/skills/moyun-armor/SKILL.md"
|
||
# 应为 True
|
||
```
|
||
|
||
不需要重启,不需要改任何配置。
|
||
|
||
---
|
||
|
||
## B. 提示词插件(只注入六段提示词,不联网、不碰权限)
|
||
|
||
**原理**:把插件包装进 profile,但用 `prompt-only` 的 bundle patch —— 只注入提示词,
|
||
不同步技能、不联网、不接管权限。
|
||
|
||
### 前置:确认 profile 目录
|
||
|
||
```powershell
|
||
$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. 拿到包**
|
||
|
||
```powershell
|
||
$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. 复制到两个位置**
|
||
|
||
```powershell
|
||
$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 覆盖**
|
||
|
||
```powershell
|
||
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` 两处**
|
||
|
||
先备份:
|
||
|
||
```powershell
|
||
$pkgJson = Join-Path $ProfileDir "package.json"
|
||
Copy-Item $pkgJson "$pkgJson.bak-moyun-$(Get-Date -Format 'yyyyMMdd-HHmmss')" -Force
|
||
```
|
||
|
||
在 `dependencies` 里加一行:
|
||
|
||
```json
|
||
"moyun-ultimate": "file:./plugins/moyun-ultimate",
|
||
```
|
||
|
||
在 `dsh.profile.bundles` 数组末尾加一项:
|
||
|
||
```json
|
||
"moyun-ultimate"
|
||
```
|
||
|
||
**改完必须验证 JSON 合法**:
|
||
|
||
```powershell
|
||
$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(用户要完整功能)
|