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

200 lines
6.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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(用户要完整功能)