# 文书定档案管理 CLI

来源 Skill：`weaver-e10-wenshuding`。本模块把接口文档中可安全自动化的能力封装为 `weaver-work-cli archive` 命令，供 AI Agent 通过结构化 JSON 调用。

源码位于 `src/shortcuts/archive`。命令注册、`operation manifest` 和业务执行逻辑分离：manifest 由 `operations/registry.ts` 汇总各 operation 定义生成，具体执行逻辑在 `src/shortcuts/archive/operations` 中按业务分组维护（全宗、检索、档案信息、借阅车、借阅单、下载、流程 URL、上传）。

面向 Agent 的说明位于 `skills/weaver-e10-wenshuding`。入口 `SKILL.md` 只负责共享规则和 reference 路由；具体细节拆在 `skills/weaver-e10-wenshuding/references/`，与飞书 CLI 的业务 Skill 组织方式保持一致。

## 公共前置

先通过 E10 鉴权模块登录：

```text
weaver-work-cli auth login --base-url "https://weapp.xxx.cn" --agent_type "<当前智能体名称>"
weaver-work-cli auth status --no-check
```

每个档案业务请求由 CLI 托管：

1. 读取当前 `weaver-work-cli auth` Profile 的 E10 会话。
2. 请求统一走 `/api/` 路径，由 CLI 携带 E10 Cookie/ETEAMSID 与必要的业务头。
3. 响应按 WeaResult（`code`/`status`/`data`）或 ebuilder 自定义接口（`datajson.status`）判定业务成功。

Agent 不得在业务 JSON 中传 Cookie、ETEAMSID、Token 或内部控制字段。

## Agent 入口

优先使用 `archive run <operation>`：

Windows PowerShell：

```powershell
weaver-work-cli archive schema
weaver-work-cli --json archive run archive.borrow-car.list --input-json '{"pageNo":1,"pageSize":10}'
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli archive schema
weaver-work-cli --json archive run archive.borrow-car.list --input-json '{"pageNo":1,"pageSize":10}'
```

成功和失败都使用 JSON envelope。成功写 stdout；失败写 stderr，并设置非 0 退出码。

当前输出层是完整 JSON 直接写 stdout，不提供飞书 CLI 的 `--jq`、`--format table/ndjson` 或通用 `--page-all`。Agent 使用时应默认小页读取和摘要渲染：列表先 `pageSize=10`，按 `pageNo` 继续；回复只展示关键字段和数量，超长响落本地文件后给路径。

## Operation 目录

| Operation | 风险 | 固定规则 |
| --- | --- | --- |
| `archive.fonds.list` | 只读 | 默认 `menuSign=collectLib`；`id` 供后续链路复用 |
| `archive.prelib.tree` | 只读 | 只返回识别出的电子文件库节点，其 `id` 即上传 `treeId` |
| `archive.search.run` | 只读 | `key` 必填；结果行 `id`+`formId` 组成 `{档案ID}_{表单ID}` |
| `archive.info.get` | 只读 | `arcDangan` 与 `dataId`+`formId` 二选一 |
| `archive.borrow-car.list` | 只读 | 首选自定义接口 `myBorrowCar`，不可用时自动回退 ebuilder 链路 |
| `archive.borrow-car.add` | 写（免确认） | 直接传 `formAndIds` 分组；`logFlag=archiveSet`；全宗字段不参与加入借阅车 |
| `archive.borrow-list.list` | 只读 | 首选自定义接口 `myBorrowList`，不可用时回退「我的借阅」视图 |
| `archive.borrow-list.detail` | 只读 | 返回明细、可下载判定与流程 requestId |
| `archive.borrow-list.download.prepare/apply` | 高风险写 | prepare 校验未超期且有可下载原文；apply 轮询打包并落盘「下载」目录 |
| `archive.flow.borrow-car.prepare/apply` | 高风险写 | 缓存档案与借阅车两组参数，返回流程创建页 URL |
| `archive.flow.search.prepare/apply` | 高风险写 | 只缓存档案参数，返回流程创建页 URL |
| `archive.flow.renew.prepare/apply` | 高风险写 | 不缓存，`arcDataId` 直接传借阅单 `dataId`，URL 带 `isReNew=1` |
| `archive.upload.prelib.prepare/apply` | 高风险写 | continuation 绑定本地文件路径、全宗和 treeId；`preUploadCheck` → `module/upload` → `saveFile` |

未绑定借阅流程时，`archive.flow.*.prepare` 返回 `validation/borrow_flow_unbound`，需要管理员先在档案设置中绑定借阅流程。

## 常用命令

```text
weaver-work-cli --json archive fonds --input-json '{"menuSign":"collectLib"}'
weaver-work-cli --json archive search --key 会计凭证 --page-size 10
weaver-work-cli archive search --key 会计凭证 --page-size 10 --format card
weaver-work-cli archive search --key 会计凭证 --page-size 10 --format html --output ./search.html
weaver-work-cli --json archive borrow-car list --page-no 1 --page-size 10
weaver-work-cli --json archive borrow-list list --page-no 1 --page-size 10
weaver-work-cli --json archive borrow-list detail --data-id BORROW_DATA_ID
weaver-work-cli --json archive info --arc-dangan 1252600626189156465_1190991330335571989
```

加入借阅车是低风险写操作，直接调用、不需要确认：

Windows PowerShell：

```powershell
weaver-work-cli --json archive run archive.borrow-car.add --input .\borrow-car-add.json
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli --json archive run archive.borrow-car.add --input ./borrow-car-add.json
```

`borrow-car-add.json` 示例：

```json
{ "formAndIds": [{ "formId": "1190991330335571989", "ids": ["1252600626189156465"] }] }
```

其余写操作（下载、发起借阅/续借、预归档上传）仍需 prepare、再 apply：

Windows PowerShell：

```powershell
weaver-work-cli --json archive run archive.borrow-list.download.prepare --input-json '{"dataId":"BORROW_DATA_ID"}'

weaver-work-cli --json archive run archive.upload.prelib.prepare --input-json '{"file":"./档案.pdf","fondsId":"FONDS_ID"}'
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli --json archive run archive.borrow-list.download.prepare --input-json '{"dataId":"BORROW_DATA_ID"}'

weaver-work-cli --json archive run archive.upload.prelib.prepare --input-json '{"file":"./档案.pdf","fondsId":"FONDS_ID"}'
```

## 行为约定

- 全文检索结果的**默认返回显示样式是「卡片视图」**：`archive search --format card` 直接输出三段式 Markdown 卡片（标题可点击档案视图、命中词加粗、全宗/分类/日期一行），除用户明确要求外一律用该样式，不要用普通表格或 JSON 代替；`--format html` 可渲染成可落盘的 HTML。
- 借阅车/借阅单列表的默认返回显示样式是 **Markdown 表格**（列：序号/题名/类型/分类/时间/状态等可读字段），表头与各列内容 **居中显示**（分隔行用 `| :---: |`），不要用卡片、编号列表或 JSON 代替。
- 借阅车/借阅单列表优先自定义接口；接口未发布或报错时自动回退，回退行额外提供 `fields`/`display`。
- 加入借阅车（`archive.borrow-car.add`）是免确认写操作，直接提交；全宗信息只在预归档上传（`upload`）时查询，检索/借阅/下载流程不需要。
- 下载的 `.apply` 是异步任务：提交后每 2 秒轮询进度，完成后把 zip 保存到当前用户的「下载」目录（可用 `output` 指定路径），已存在同名文件时自动加序号。
- 发起借阅/续借只返回流程创建页 URL，CLI 不自动打开浏览器；上层 Agent 收到 URL 后默认调用**系统默认浏览器**打开，只有用户明确要求内置视图时才使用 IDE 内置浏览器。
- 写操作的 continuation 由 CLI 签发并绑定环境与登录账号，换环境或换账号必须重新 prepare。
- 写操作出现网络中断、部分成功或回查失败时返回 `partial/write_uncertain`，Agent 禁止自动重复提交。
- 涉及本地文件上传或原文下载时，必须先提醒用户文件内容可能进入大模型上下文，并取得明确确认。