# Agent Skill 安装与升级

本文说明如何把 `weaver-work-cli` 随包 Agent Skill（以 `yepiaotong` 为例）安装或升级到本机 Agent 的 skill 目录。适用两类读者：

- 首次让 Codex / WorkBuddy 等 Agent 识别发票业务的使用者；
- 在本仓库修改 Skill 内容后，需要把最新版同步到本机 Agent 环境的开发者。

Agent 运行期调用规则不在这里，见 `skills/weaver-e10-shared/SKILL.md` 与 `skills/weaver-e10-yepiaotong/SKILL.md`。人类视角的安装总览见 `README.md`。

本文命令示例按平台选择执行。涉及用户目录、路径、文件删除、目录查看或文件比对时，同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例。Agent 应先判断当前环境，Windows 或 PowerShell 用 Windows 示例，macOS/Linux、bash 或 zsh 用 macOS/Linux 示例；不确定时用 `node -p "process.platform"` 判断。

## Agent 自动安装 CLI 运行时

如果安装 Skill 前发现 `weaver-work-cli` 命令不可用，Agent 可以在用户明确同意后代装运行时。提示必须让用户选择安装来源：npm 源，或本地代码。选择本地代码时，用户必须提供 `weaver-work-cli` 仓库目录的绝对路径。

建议提示词：

```text
未检测到可用的 weaver-work-cli。是否允许我为当前智能体安装运行时？

请选择安装来源：
1. npm 源安装：使用当前 npm registry；如需公司私有 registry，请同时提供 registry 地址。
2. 本地代码安装：请提供 weaver-work-cli 仓库目录的绝对路径。

我会先检查 node/npm 版本，安装后再运行 weaver-work-cli --version 和 weaver-work-cli skills list 验证。
```

npm 源安装命令；如用户指定公司 registry，把 `npm install -g weaver-work-cli` 替换为 `npm install -g weaver-work-cli --registry "<NPM_REGISTRY_URL>"`：

```text
node --version
npm --version
npm config get registry
npm install -g weaver-work-cli
weaver-work-cli --version
weaver-work-cli skills list
```

本地代码安装命令：

Windows PowerShell：

```powershell
$WeaverWorkCliRoot = "C:\path\to\weaver-work-cli"
if (-not (Test-Path "$WeaverWorkCliRoot\package.json")) { throw "invalid weaver-work-cli path" }
Set-Location $WeaverWorkCliRoot
npm install
npm run build
npm link
weaver-work-cli --version
weaver-work-cli skills list
```

macOS/Linux（bash/zsh）：

```bash
WEAVER_WORK_CLI_ROOT="/path/to/weaver-work-cli"
test -f "$WEAVER_WORK_CLI_ROOT/package.json" || exit 1
cd "$WEAVER_WORK_CLI_ROOT"
npm install
npm run build
npm link
weaver-work-cli --version
weaver-work-cli skills list
```

## 最短命令

Windows PowerShell：

```powershell
$AgentSkillsRoot = "C:\path\to\agent-skills"
if (-not (Test-Path "$AgentSkillsRoot\weaver-e10-shared\SKILL.md")) {
  weaver-work-cli skills install shared --target-dir "$AgentSkillsRoot"
}
weaver-work-cli skills install yepiaotong --target-dir "$AgentSkillsRoot"
```

macOS/Linux（bash/zsh）：

```bash
AGENT_SKILLS_ROOT="/path/to/agent-skills"
if [ ! -f "$AGENT_SKILLS_ROOT/weaver-e10-shared/SKILL.md" ]; then
  weaver-work-cli skills install shared --target-dir "$AGENT_SKILLS_ROOT"
fi
weaver-work-cli skills install yepiaotong --target-dir "$AGENT_SKILLS_ROOT"
```

- Agent 代装业务 Skill 时，必须先判断目标目录里的 `weaver-e10-shared/SKILL.md` 是否存在；未安装时先执行 `weaver-work-cli skills install shared --target-dir "<agent-skills-root>"`，再安装业务 Skill。
- `skills install yepiaotong` 的 CLI 层会同时安装 `weaver-e10-shared` 与 `weaver-e10-yepiaotong`，用于命令兜底；但提示词和自动安装流程仍需显式展示 shared 前置检查。
- 安装目录优先级为：`--target-dir` → 通用环境变量 `WEAVER_SKILLS_ROOT` → 当前进程明确识别出的 Codex/WorkBuddy 宿主 → 当前用户目录下唯一已存在的已知 skills 目录。
- `WEAVER_AGENT_TYPE=codex|workbuddy` 可明确当前宿主；未设置时，CLI 优先比较当前进程中的 `CODEX_*` / `WORKBUDDY_*` 运行时信号，再参考可能被长期配置的 `CODEX_HOME` / `WORKBUDDY_HOME`。两个 `*_HOME` 表示宿主主目录，CLI 会追加 `skills`；`WEAVER_SKILLS_ROOT` 则直接表示最终的 skills 根目录。
- 两个已知宿主目录都存在、完全没有可靠信号，或检测到其它智能体但没有取得其 skills 路径时，CLI 不会猜测或写入，而是要求使用 `--target-dir` 或 `WEAVER_SKILLS_ROOT` 后重试。
- Agent 在业务 Skill 内自行推断目标目录时，取**当前这份 SKILL.md 所在目录的上一级绝对目录**（即与本技能同级的 skills 根目录），不要省略 `--target-dir`——省略后若宿主信号不足，CLI 会拒绝安装；仅靠已有目录推断也可能不是当前宿主。
- 安装是文件拷贝，不需要 E10 登录；登录只在执行业务命令（`invoice run ...`）前需要。
- 名称支持短名（如 `skill-maker`）、全名 `weaver-e10-skill-maker` 和旧前缀 `weaver-work-cli-skill-maker`；旧前缀会转换为当前名称。建议使用短名，避免不同版本的前缀差异。
- Skill 生成器拼写为 `maker`，不是 `marker`。名称不存在时会提示相近名称和查询命令，不会自动安装猜测的 Skill。

安装 Skill 生成器到 WorkBuddy（macOS/Linux）：

```bash
weaver-work-cli skills install skill-maker --target-dir "$HOME/.workbuddy/skills"
```

## 各 Agent 环境的 skill 目录

| Agent 环境 | skill 根目录 | 安装方式 |
| --- | --- | --- |
| Codex CLI | `CODEX_HOME` 下的 `skills`；默认当前用户主目录下的 `.codex/skills` | 当前进程带有 Codex 环境信号时可直接执行 `skills install yepiaotong`；否则显式指定目录 |
| WorkBuddy（桌面端） | `WORKBUDDY_HOME` 下的 `skills`；默认当前用户主目录下的 `.workbuddy/skills` | 当前进程带有 WorkBuddy 环境信号时可直接执行；否则用 `--target-dir` 或 `WEAVER_SKILLS_ROOT` |
| 其它 Agent | 由 Agent 配置决定 | `skills install yepiaotong --target-dir <path>`，或先把 `WEAVER_SKILLS_ROOT` 设置为该路径 |

安装输出的第一行会写明实际使用的目标目录与判定来源。Windows 可执行 `$env:WEAVER_SKILLS_ROOT = "$env:USERPROFILE\.<agent>\skills"`；macOS/Linux 可执行 `export WEAVER_SKILLS_ROOT="$HOME/.<agent>/skills"`。这里只读取当前登录用户的主目录，不扫描其它用户目录。

不确定 Agent 读哪个目录时先问用户，不要盲目同时安装到多个目录。装到用户主目录下的 `.workbuddy/skills` 不会同步 `.codex/skills`，反之亦然。

## 核心事实（先读，避免误操作）

1. **内容源是包内 `skills/` 目录**，不经过编译；`npm run build` 只保证 CLI 代码通过构建期 TS 校验，不产出 Skill。
2. **`skills install` 是拷贝语义**：装出的是真实副本，不与源目录联动。之后源里改动 Skill，已安装目录不会自动更新，需重跑安装；覆盖安装只写入与覆盖同名文件，**不会清理目标里已不存在的旧文件**，需要干净结果时先整目录移除再安装。
3. **目标目录已有旧条目（旧副本或软链）时不能直接覆盖**：命令内部是递归拷贝，目标为软链时会报 `ERR_FS_CP_DIR_TO_NON_DIR` 失败；先移除该条目再安装（移除软链只断链，不影响其指向的目录）。
4. **本机 CLI 若为 `npm link` 指向本地仓库**，`skills list/install` 反映的是仓库当前工作区内容，包含未提交改动——开发期可直接发布最新工作区。
5. 拷贝会过滤 dotfiles、`scripts/`、`assets/`、`node_modules/`；`SKILL.md`、`references/` 会完整拷贝，`product.json` 由 `skill-template/product.json` 和 `package.json` 注入到每个安装产物。

## 首次安装

Windows PowerShell：

```powershell
# 1. 确认命令可用且能看到随包 Skill
weaver-work-cli --version
weaver-work-cli skills list

# 2. 安装到目标目录（示例：WorkBuddy）
weaver-work-cli skills install yepiaotong --target-dir "$env:USERPROFILE\.workbuddy\skills"

# 3. 验证：结果是真实目录，不是软链
Get-ChildItem -Force "$env:USERPROFILE\.workbuddy\skills"
```

macOS/Linux（bash/zsh）：

```bash
# 1. 确认命令可用且能看到随包 Skill
weaver-work-cli --version
weaver-work-cli skills list

# 2. 安装到目标目录（示例：WorkBuddy）
weaver-work-cli skills install yepiaotong --target-dir "$HOME/.workbuddy/skills"

# 3. 验证：结果是真实目录，不是软链
ls -la "$HOME/.workbuddy/skills"
```

## 从本地开发仓库升级到最新

在仓库根目录执行：

Windows PowerShell：

```powershell
# 1. 前置检查：确认全局 CLI 来源与待发布的工作区状态
Get-Command weaver-work-cli
git status --short

# 2. 重新构建，通过构建期 TS 校验（clean + tsc）
npm run build

# 3. 移除目标目录旧条目（软链/旧副本），再安装
Remove-Item -Recurse -Force "$env:USERPROFILE\.workbuddy\skills\weaver-e10-yepiaotong", "$env:USERPROFILE\.workbuddy\skills\weaver-e10-shared"
weaver-work-cli skills install yepiaotong --target-dir "$env:USERPROFILE\.workbuddy\skills"

# 4. 验证安装的是最新内容（与仓库工作区一致）
if ((Get-FileHash "skills\weaver-e10-yepiaotong\SKILL.md").Hash -ne (Get-FileHash "$env:USERPROFILE\.workbuddy\skills\weaver-e10-yepiaotong\SKILL.md").Hash) { throw "yepiaotong skill differs" }
if ((Get-FileHash "skills\weaver-e10-shared\SKILL.md").Hash -ne (Get-FileHash "$env:USERPROFILE\.workbuddy\skills\weaver-e10-shared\SKILL.md").Hash) { throw "shared skill differs" }
```

macOS/Linux（bash/zsh）：

```bash
# 1. 前置检查：确认全局 CLI 来源与待发布的工作区状态
command -v weaver-work-cli
git status --short

# 2. 重新构建，通过构建期 TS 校验（clean + tsc）
npm run build

# 3. 移除目标目录旧条目（软链/旧副本），再安装
rm -rf "$HOME/.workbuddy/skills/weaver-e10-yepiaotong" "$HOME/.workbuddy/skills/weaver-e10-shared"
weaver-work-cli skills install yepiaotong --target-dir "$HOME/.workbuddy/skills"

# 4. 验证安装的是最新内容（与仓库工作区一致）
diff -q skills/weaver-e10-yepiaotong/SKILL.md "$HOME/.workbuddy/skills/weaver-e10-yepiaotong/SKILL.md"
diff -q skills/weaver-e10-shared/SKILL.md "$HOME/.workbuddy/skills/weaver-e10-shared/SKILL.md"
```

构建失败（tsc 报错）时先修复 TS 错误再安装；`skills install` 的内容源不依赖 `dist/`，但发布前应保证仓库可构建。

## 验证清单与生效

安装本身不校验业务 API。要确认对 Agent 生效：

- 目录结构正确：用户主目录下的 `.workbuddy/skills/weaver-e10-yepiaotong` 包含 `SKILL.md`、安装生成的 `product.json`、`references/`，且 `weaver-e10-shared` 包含 `SKILL.md`、`references/`。
- 内容一致：Windows 使用上述 `Get-FileHash`，macOS/Linux 使用上述 `diff -q`；或用 `weaver-work-cli skills read weaver-e10-yepiaotong` 与仓库内容比对。
- **Agent 需重新加载**：新建会话或按 Agent 规则重载 Skill 后才读取新内容；已打开的会话不会热更新。
- 业务可用性：安装后仍需完成 E10 登录（`weaver-work-cli auth login --base-url "<E10_BASE_URL>" --agent_type "<当前智能体名称>"`），并可按 `weaver-work-cli invoice schema` 验证 operation 契约。

## 常见问题

| 现象 | 处理 |
| --- | --- |
| `weaver-work-cli: command not found` | 先安装运行时：`npm install -g weaver-work-cli`，再 `setup invoice` |
| 安装报 `ERR_FS_CP_DIR_TO_NON_DIR` | 目标目录对应条目是软链；Windows 用 `Remove-Item -Recurse -Force "C:\path\to\skills\weaver-e10-*"`，macOS/Linux 用 `rm -rf "/path/to/skills"/weaver-e10-*` 断链再安装 |
| `unknown packaged skill` | 确认 `weaver-work-cli skills list` 输出的包内 Skill 名称；目标是全名或 `yepiaotong` 等短名 |
| 改了仓库 Skill 但 Agent 看不到 | 已安装目录是拷贝，需重跑安装；且 Agent 需新会话重载 |
| 需要离线/平台导入的独立归档 | 用 `npm run build:yepiaotong-skill`，产物 `dist/weaver-e10-yepiaotong-skill.zip`；日常本机安装优先用 `skills install` |