# weaver-work-cli 操作手册

本文面向普通使用者和业务模块建设者，说明如何快速安装 `weaver-work-cli`，以及如何使用随包能力生成、验证、打包和安装业务模块 Agent Skill。

## 1. 适用范围

`weaver-work-cli` 是面向泛微工作工具链的 TypeScript CLI。框架层保持业务无关，E10 登录、profile 和 HTTP client 由 `src/internal/e10` 托管，具体业务能力放在 `src/shortcuts/<module>`，对应的 Agent Skill 放在 `skills/weaver-e10-<module>`。

当前随包内置业务模块：

| 模块 | CLI 命令 | Agent Skill | 说明 |
| --- | --- | --- | --- |
| 业票通 | `weaver-work-cli invoice` | `weaver-e10-yepiaotong` | 发票查询、详情、OCR/查验、下载、导入/新增/编辑/删除确认链 |
| 文书定 | `weaver-work-cli wenshuding` | `weaver-e10-wenshuding` | 全宗、档案检索、借阅车、借阅单、发起借阅、预归档上传 |
| Skill Maker | `weaver-work-cli skills ...` + Agent 生成流程 | `weaver-e10-skill-maker` | 把新业务模块资料转换成业务 CLI 与 Skill，并做检测和安装确认 |

注意：当前 CLI 不提供独立的 `skills generate` 子命令。新业务模块的生成由 `weaver-e10-skill-maker` 这个 Agent Skill 编排完成；CLI 提供运行时、`schema/run` 合约、随包 Skill 读写安装能力和打包脚本。

## 2. 环境要求

- Node.js 18 或更高版本。
- npm。
- 可访问组织 npm registry 或本地源码包。
- 执行业务 operation 前需要 E10 登录；仅安装 Agent Skill 不需要登录。

本手册的命令示例按平台选择执行。完全相同的 `node`、`npm`、`git` 和 `weaver-work-cli` 命令可作为通用示例；涉及 JSON 输入、用户目录、路径分隔符、Python 启动器、文件删除、目录查看或文件比对时，同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例。Agent 应先判断当前环境，Windows 或 PowerShell 用 Windows 示例，macOS/Linux、bash 或 zsh 用 macOS/Linux 示例；不确定时用 `node -p "process.platform"` 判断。Windows/PowerShell 下不要使用 `printf`、`$HOME/...`、`~/...`、bash 反斜杠续行、`rm/ls/diff/python3` 等 Unix-only 写法。

## 3. 快速安装 CLI

### 3.1 从 npm 或公司 registry 安装

```text
npm install -g weaver-work-cli
weaver-work-cli --version
weaver-work-cli --help
weaver-work-cli commands list
weaver-work-cli skills list
```

`skills list` 能输出 `weaver-e10-shared`、`weaver-e10-yepiaotong`、`weaver-e10-wenshuding`、`weaver-e10-skill-maker` 等条目，说明发布包中的 Skill 内容可读。

### 3.2 从源码安装到本机全局命令

```text
git clone GIT_REPO_URL weaver-work-cli
cd weaver-work-cli
npm install
npm run build
npm link
weaver-work-cli --version
```

如果怀疑全局命令指向旧版本，可在仓库根目录直接调用当前构建产物：

```text
node dist/index.js --version
node dist/index.js commands list
node dist/index.js skills list
```

### 3.3 从本地 tgz 包安装

Windows PowerShell：

```powershell
cd C:\path\to\weaver-work-cli
npm install
npm run build
npm pack
npm install -g .\weaver-work-cli-VERSION.tgz
weaver-work-cli --version
```

macOS/Linux（bash/zsh）：

```bash
cd /path/to/weaver-work-cli
npm install
npm run build
npm pack
npm install -g ./weaver-work-cli-VERSION.tgz
weaver-work-cli --version
```

## 4. 登录和可用性检查

执行业务接口前先登录 E10：

```text
weaver-work-cli auth login --base-url "<E10_BASE_URL>" --agent_type "<当前智能体名称>"
weaver-work-cli auth status
weaver-work-cli doctor --e10
```

如果不能打开浏览器登录，也可以手动写入当前浏览器中的 `ETEAMSID`：

```text
weaver-work-cli auth set --eteamsid "<PCACCOUNT_xxx>" --base-url "<E10_BASE_URL>" --agent_type "<当前智能体名称>"
weaver-work-cli auth whoami --live
```

`<当前智能体名称>` 使用发起登录验证的宿主标识，例如 WorkBuddy 用 `workbuddy`，Codex 用 `codex`。CLI 会把该值同时写入授权 URL 的 `agent_type` 和 `from` 参数；未显式传入时，CLI 会尝试从环境变量推断。

多环境可用 profile 隔离：

```text
weaver-work-cli auth profile list
weaver-work-cli auth profile use PROFILE_NAME
weaver-work-cli --profile PROFILE_NAME auth status
```

认证、Cookie、Token 只应通过 `weaver-work-cli auth ...` 管理。不要让 Agent 直接读取、复制或展示本机认证文件、Keychain、Cookie、`ETEAMSID` 或业务 Token。

## 5. 安装已有业务模块 Skill

### 5.1 安装到当前 Agent

```text
weaver-work-cli skills install yepiaotong
weaver-work-cli skills install wenshuding
```

CLI 优先使用 `--target-dir` 或通用环境变量 `WEAVER_SKILLS_ROOT`。未显式指定时，会根据当前进程的 Codex/WorkBuddy 环境信号选择当前用户的 skills 目录；如果宿主不明确、存在多个候选目录，或者当前为其它 Agent 且未提供路径，则停止安装并要求显式指定，避免装错位置。安装非 shared 业务 Skill 时，CLI 会自动带上 `weaver-e10-shared`。

### 5.2 显式安装到 WorkBuddy 或其它 Agent

Windows PowerShell：

```powershell
weaver-work-cli skills install yepiaotong --target-dir "$env:USERPROFILE\.workbuddy\skills"
weaver-work-cli skills install wenshuding --target-dir "$env:USERPROFILE\.workbuddy\skills"
```

macOS/Linux（bash/zsh）：

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

其它 Agent 使用自己的 skills 根目录：

Windows PowerShell：

```powershell
weaver-work-cli skills install MODULE_NAME --target-dir "C:\path\to\agent-skills"
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli skills install MODULE_NAME --target-dir "/path/to/agent-skills"
```

经常使用同一 Agent 时，也可以设置通用目录环境变量：

```powershell
$env:WEAVER_SKILLS_ROOT = "$env:USERPROFILE\.other-agent\skills"
weaver-work-cli skills install MODULE_NAME
```

```bash
export WEAVER_SKILLS_ROOT="$HOME/.other-agent/skills"
weaver-work-cli skills install MODULE_NAME
```

`<module>` 可以传短名，例如 `yepiaotong`、`wenshuding`、`skill-maker`，也可以传完整名，例如 `weaver-e10-yepiaotong`。传 `all` 会安装包内全部 Skill。

### 5.3 验证安装结果

Windows PowerShell：

```powershell
weaver-work-cli skills list
weaver-work-cli skills read weaver-e10-yepiaotong
weaver-work-cli skills list weaver-e10-yepiaotong/references
Get-ChildItem -Force "C:\path\to\agent-skills"
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli skills list
weaver-work-cli skills read weaver-e10-yepiaotong
weaver-work-cli skills list weaver-e10-yepiaotong/references
ls -la "/path/to/agent-skills"
```

Agent 需要新建会话或按宿主规则重载 Skill 后才会读取新内容。

### 5.4 安装语义

- `skills install` 是文件拷贝，不是软链；源目录后续修改不会自动同步到已安装目录。
- 覆盖安装只覆盖同名文件，不会清理目标目录里源端已删除的旧文件；需要干净升级时先移除目标 Skill 目录再安装。
- 拷贝会过滤 dotfile、`scripts/`、`assets/`、`node_modules/`；保留 `SKILL.md`、`references/` 等文本内容，并根据 `skill-template/product.json` 与 `package.json` 给每个安装产物补写 `product.json`。
- 目标已有软链时可能报 `ERR_FS_CP_DIR_TO_NON_DIR`，先删除目标软链或旧副本再重装。

## 6. 使用业务 CLI

Agent 和自动化脚本优先使用统一 JSON operation 入口：

Windows PowerShell：

```powershell
weaver-work-cli MODULE_NAME schema
weaver-work-cli --json MODULE_NAME run MODULE_NAME.operation --input-json '{"key":"value"}'
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli MODULE_NAME schema
weaver-work-cli --json MODULE_NAME run MODULE_NAME.operation --input-json '{"key":"value"}'
```

示例：

Windows PowerShell：

```powershell
weaver-work-cli invoice schema
weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'

weaver-work-cli wenshuding schema
weaver-work-cli --json wenshuding run wenshuding.search --input-json '{"key":"合同","page":0,"page_size":10}'
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli invoice schema
weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'

weaver-work-cli wenshuding schema
weaver-work-cli --json wenshuding run wenshuding.search --input-json '{"key":"合同","page":0,"page_size":10}'
```

成功输出统一 JSON envelope：

```json
{
  "schemaVersion": 1,
  "ok": true,
  "operation": "<module>.<action>",
  "data": {},
  "meta": { "status": "COMPLETE" },
  "warnings": []
}
```

失败也会输出结构化 envelope，重点看 `error.type`、`error.subtype`、`error.message` 和退出码。写入类 operation 采用 `prepare -> apply`，`apply` 必须携带 `confirm: true` 和 prepare 返回的 continuation；写请求已发出后如出现 `partial/write_uncertain`，不要自动重试，先做只读回查。

## 7. 启用业务模块 Skill 生成能力

先把 Skill Maker 安装到当前 Agent 的 skills 目录：

```text
weaver-work-cli skills install skill-maker
```

WorkBuddy 示例：

Windows PowerShell：

```powershell
weaver-work-cli skills install skill-maker --target-dir "$env:USERPROFILE\.workbuddy\skills"
```

macOS/Linux（bash/zsh）：

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

安装后新建 Agent 会话，并用类似提示触发生成流程：

```text
请使用 weaver-e10-skill-maker，把 <源资料路径或文档列表> 转换为 <module> 业务模块。

要求：
- 模块短名：<module>
- 输出到当前 weaver-work-cli 仓库
- 同步生成或更新 src/shortcuts/<module> 与 skills/weaver-e10-<module>
- 生成的 docs、Skill reference、提示词和 CLI 示例必须同时兼容 Windows 和 macOS/Linux；涉及 JSON 输入、用户目录、路径、Python、删除、目录查看或文件比对时，同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例，并让 Agent 根据当前环境选择；Windows/PowerShell 简单 JSON 优先使用 `--input-json`，复杂 JSON 使用临时 UTF-8 文件和 `--input <path>`，不要使用 `printf`
- 不要把资料包里的多份 MD 压缩成概述；字段表、枚举/状态、默认值、固定参数、分页/排序口径、权限前置、ID 解析、流程分支、错误码、返回结构、示例和禁用能力都要落到 schema、handler、reference、测试或禁用边界
- 只实现源资料能确认的 operation；资料不足的能力写入禁用边界或待确认清单
- 在 source-manifest.json 记录 sourceChunks、operationImpact 和 sourceCoverage，说明每个业务源文件已转换、暂缓、外部留存、无需处理或待确认
- 生成后运行 schema 和测试；每次创建或更新 Skill 后必须询问我是否现在进行 Skill 质检，我确认后再运行泛微技能检测工具
- 检测通过后询问我是否安装到 <agent-skills-root>
```

源资料至少应提供：

- 业务模块短名，例如 `contract`、`expense-claim`。
- 接口文档、现有代码、样例 JSON、业务说明或已有 Skill。
- 每个 operation 的接口路径、请求方法、关键字段、分页语义和返回结构。
- 写入、删除、导入、上传等高风险操作的确认条件、幂等要求和写后回查方式。
- 权限、租户、scope、固定参数和不可自动化边界。

如果这些事实不足，Skill Maker 会只生成已能确认的能力，并把缺口列出来让用户确认；它不应编造接口、字段或写入确认链。

## 8. 生成后的产物结构

一个新业务模块生成后，默认会同步维护这些文件：

```text
src/shortcuts/<module>/
  index.ts
  manifest.ts
  operations.ts
  errors.ts
  host.ts
  continuation.ts
  operations/
    registry.ts
    types.ts
    shared.ts
    <operation>.ts

skills/weaver-e10-<module>/
  SKILL.md
  references/
    <operation-or-topic>.md
    source-manifest.json

skill-template/product.json

docs/<module>.md
skill-template/business-info.json
skill-template/domains/<module>.md
test/business/<module>-*.test.ts
```

分工规则：

- `manifest.ts` 和 `<module> schema` 拥有 operation、字段、风险、权限、固定参数等 WHAT 合约。
- `docs/<module>.md` 说明维护者视角的 WHEN：模块来源、命令结构、operation 表和安全边界。
- `skills/weaver-e10-<module>/SKILL.md` 只做 Agent 路由、共享规则入口、工作流和禁用边界。
- `references/*.md` 写具体 HOW：命令示例、输入要点、输出处理、失败处理和回查策略。
- `source-manifest.json` 记录源资料路径、大小、sha256、聚合指纹、sourceChunks、operationImpact 和 sourceCoverage，后续源资料更新时先比较差异和覆盖状态，再确认是否覆盖生成结果。

## 9. 验证、检测和打包

在仓库根目录验证生成结果：

```text
npm run build
npm test -- test/skills/layout.test.ts
npm test -- "test/business/MODULE_NAME-*.test.ts"
weaver-work-cli MODULE_NAME schema
weaver-work-cli skills read weaver-e10-MODULE_NAME
```

每次 Skill Maker 创建或更新业务模块 Skill 后，静态质检都是必需门槛。运行 detector 前必须先询问用户是否现在进行 Skill 质检；用户确认后，使用泛微技能检测工具做静态质检。用户拒绝、未回复或检测器不可用时，只能停在待质检状态，不要打包、安装或声明完成。

Windows PowerShell：

```powershell
weaver-work-cli skills validate skills\weaver-e10-MODULE_NAME --json --no-html
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli skills validate skills/weaver-e10-MODULE_NAME --json --no-html
```

检测通过后打包：

```text
node scripts/package-skill.mjs MODULE_NAME
```

该脚本使用纯 Node 生成 ZIP，不依赖系统 `zip`/`unzip` 命令，Windows、macOS 和 Linux 下命令一致。

默认输出：

```text
dist/weaver-e10-<module>-skill.zip
```

打包单个业务模块时会自动包含 `weaver-e10-shared`。zip 用于平台导入、离线分发或版本归档；本机日常安装优先使用 `weaver-work-cli skills install <module>`。

## 10. 安装新生成的业务模块 Skill

检测通过并得到用户确认后安装：

Windows PowerShell：

```powershell
weaver-work-cli skills install MODULE_NAME --target-dir "C:\path\to\agent-skills"
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli skills install MODULE_NAME --target-dir "/path/to/agent-skills"
```

如果全局命令还没更新，但当前仓库已构建，可用当前构建产物安装：

Windows PowerShell：

```powershell
node dist/index.js skills install MODULE_NAME --target-dir "C:\path\to\agent-skills"
```

macOS/Linux（bash/zsh）：

```bash
node dist/index.js skills install MODULE_NAME --target-dir "/path/to/agent-skills"
```

安装后验证：

Windows PowerShell：

```powershell
weaver-work-cli skills list
weaver-work-cli skills read weaver-e10-MODULE_NAME
Get-ChildItem -Force "C:\path\to\agent-skills\weaver-e10-shared"
Get-ChildItem -Force "C:\path\to\agent-skills\weaver-e10-MODULE_NAME"
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli skills list
weaver-work-cli skills read weaver-e10-MODULE_NAME
ls -la "/path/to/agent-skills/weaver-e10-shared"
ls -la "/path/to/agent-skills/weaver-e10-MODULE_NAME"
```

## 11. 升级已有业务模块

源文档或代码更新后，用下面的提示让 Agent 先做差异检测：

```text
请使用 weaver-e10-skill-maker，检查 <module> 的源资料 <路径> 是否相对
skills/weaver-e10-<module>/references/source-manifest.json 发生变化。
先给出新增、删除、sha256 变化；如果 manifest 有 sourceChunks/operationImpact，
再列出变化 chunk、锚点、可能影响的 operation、schema、reference、测试和写入确认链，
然后问我是否同步转换。
```

确认转换后，Agent 才应更新 `src/shortcuts/<module>`、`skills/weaver-e10-<module>`、测试、docs、`business-info.json`、domain 文件和 manifest。无变化时不要重写 Skill；只有文件级变化但 chunk 未变时，也要先说明差异并等待确认。

## 12. 常见问题

| 现象 | 处理 |
| --- | --- |
| `weaver-work-cli: command not found` | 先执行 `npm install -g weaver-work-cli` 或在源码仓库 `npm link` |
| `unknown packaged skill` | 先运行 `weaver-work-cli skills list`，确认传入的是短名或完整 Skill 名 |
| Agent 安装后没识别新 Skill | 新建会话或按 Agent 规则重载 Skill；确认安装到了该 Agent 实际读取的 skills 目录 |
| 安装后内容不是最新 | `skills install` 是拷贝语义，重新安装；需要干净升级时先删除旧目标目录 |
| 目标目录已有软链导致安装失败 | 删除该目标条目后重试，例如删除 `<agent-skills-root>/weaver-e10-<module>` |
| `schema` 能看见但业务执行失败 | 先 `weaver-work-cli auth status` 和 `doctor --e10`，再看失败 envelope 的 `error.type/subtype` |
| 生成器要求补资料 | 按 `operation -> 缺少事实 -> 为什么阻断` 补接口路径、字段、权限、幂等或回查契约 |