@alphalawyer/alpha-classic-cli 0.1.1

package/README.md

@@ -0,0 +1,212 @@
+# alpha-classic-cli
+
+Alpha Classic CLI 是为 **Alpha 律所管理系统** 开发的 AI-friendly CLI，用来验证 Codex/Claude Code 等 Agent 是否能稳定、安全地通过 CLI 访问 Alpha 业务数据。
+
+- CLI 命令能访问 Web 应用 API
+- Codex 能通过 Skill 理解该怎么调用 CLI
+- 登录、诊断、业务查询形成最小闭环
+- 环境在构建时固化，运行时不能切换，避免误连 dev/prod
+
+## 安装依赖
+
+```bash
+npm install
+```
+
+## 构建
+
+```bash
+npm run build:dev
+```
+
+构建脚本会把环境写入产物：
+
+```bash
+npm run build:local
+npm run build:dev
+npm run build:test
+npm run build:prod
+```
+
+当前 dev 环境：
+
+```text
+baseUrl/apiBaseUrl: https://dev.alphalawyer.cn
+current user API: GET /im/v1/users/me
+auth header: token: <token>
+device header: deviceType: ai
+```
+
+## 运行
+
+项目已配置 bin：
+
+```bash
+alpha-classic-cli version
+alpha-classic-cli env current
+alpha-classic-cli login
+alpha-classic-cli doctor
+alpha-classic-cli matter search --keyword 合同 --limit 10
+alpha-classic-cli matter search --status 进行中+预立项 --scope 所有项目 --limit 10
+alpha-classic-cli matter detail --id <项目ID> --logs 5
+alpha-classic-cli matter task --id <项目ID> --state 未完成 --limit 20
+alpha-classic-cli appro list --scope my --limit 10
+alpha-classic-cli appro initiators --keyword 张三
+alpha-classic-cli appro detail --id <审批ID>
+```
+
+`env use` 已移除。只保留 `env list` 和 `env current`；切换环境必须重新构建对应环境版本。
+
+源码调试时也可以使用：
+
+```bash
+npm run dev -- doctor
+```
+
+## 登录
+
+默认使用 CLI 设备授权登录：
+
+```bash
+alpha-classic-cli login
+```
+
+CLI 会创建授权、展示 user code 和二维码，并尝试自动打开浏览器。用户在前端确认后，CLI 保存本地 session。最终输出始终是 JSON envelope，且不会输出 token 或 refreshToken。
+
+Agent 异步登录建议使用两阶段流程：
+
+```bash
+alpha-classic-cli login --no-wait --json
+```
+
+把返回的 `data.verification_url` 原样交给用户打开确认。用户确认后执行：
+
+```bash
+alpha-classic-cli login --device-code <device_code>
+```
+
+调试场景暂时保留手动 token fallback：
+
+```bash
+alpha-classic-cli login --token <token>
+```
+
+不要把 token 或 refreshToken 写入回答、日志或 URL。
+
+## 安装智能体说明
+
+```bash
+alpha-classic-cli install
+```
+
+默认安装 Codex Skill：
+
+```text
+~/.codex/skills/alpha-classic-cli/SKILL.md
+```
+
+用户也可以选择安装目标：
+
+```bash
+alpha-classic-cli install --agent codex
+alpha-classic-cli install --agent claude
+alpha-classic-cli install --agent alphaclaw
+alpha-classic-cli install --agent all
+```
+
+卸载智能体说明：
+
+```bash
+alpha-classic-cli uninstall --agent codex
+alpha-classic-cli uninstall --agent claude
+alpha-classic-cli uninstall --agent alphaclaw
+alpha-classic-cli uninstall --agent all
+```
+
+Alpha-claw 安装方式会跟随 CLI 构建环境，例如 dev 构建安装到：
+
+```text
+~/.openclaw-devalphaclaw/workspace/skills/alpha-classic-cli/SKILL.md
+```
+
+Claude Code 安装方式：
+
+```text
+~/.claude/alpha-classic-cli.md
+```
+
+并在用户级：
+
+```text
+~/.claude/CLAUDE.md
+```
+
+追加 import：
+
+```text
+@~/.claude/alpha-classic-cli.md
+```
+
+Skill 会引导智能体优先使用稳定 CLI 命令，例如：
+
+```bash
+alpha-classic-cli doctor
+alpha-classic-cli login
+alpha-classic-cli version
+alpha-classic-cli matter search --keyword 合同 --limit 10
+alpha-classic-cli matter detail --id <项目ID> --logs 5
+alpha-classic-cli matter task --id <项目ID> --state 未完成 --limit 20
+```
+
+## 通用智能体对接
+
+通用智能体优先读取仓库根目录：
+
+```text
+AGENTS.md
+CLAUDE.md
+```
+
+也可以通过命令发现 CLI 能力：
+
+```bash
+alpha-classic-cli capabilities
+```
+
+`capabilities` 输出机器可读 JSON，包含登录流程、环境规则、业务命令、参数和安全边界。
+
+## 当前接口
+
+当前默认调用：
+
+- `GET /im/v1/users/me`
+- `GET /matterserver/api/v1/customFields/dashboard/MATTER_LIST`
+- `POST /matterserver/api/v2/matter/search`
+- `GET /matterserver/api/v2/matters/{matterId}`
+- `GET /notice/v1/dynamics/matters/{matterId}`
+- `GET /taskserver/api/v1/tasks/listTaskByMatter`
+- `GET /taskserver/api/v1/tasks/{taskId}`
+- `GET /taskserver/api/v1/checkitem/{taskId}`
+- `GET /taskserver/api/v1/tasks/attachment/{taskId}`
+- `GET /document-engine/api/v1/dir/list`
+- `GET /taskserver/api/v2/timing/timing/task/{taskId}`
+- `GET /ilaw/api/v2/comment/queryCommentsAndDynamic`
+- `POST /appro/api/v2/approval/search`
+- `GET /appro/api/v2/appros/{approId}`
+- `GET /common/api/v1/file/batch`
+- `GET /user/api/v1/users/listOfficeUser?deleted=0&status=1`
+
+接入真实 Web 应用时，优先修改：
+
+- `src/commands/matter.ts`
+- `src/commands/appro.ts`
+- `src/http/api-client.ts`
+- `src/config/environments.ts`
+
+## 设计原则
+
+- 默认输出 JSON envelope，方便 AI 解析。
+- 只支持查询，不执行写操作。
+- 不在终端输出 token。
+- 不接受运行时 baseUrl/apiBaseUrl 参数。
+- Skill 负责告诉 AI 什么时候用哪个命令。

package/assets/alpha-classic-skill/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: alpha-classic-cli
+description: 使用 alpha-classic-cli 查询 Alpha 律所管理系统里的项目、审批等数据。先运行 doctor，优先使用稳定 CLI 命令，不自行猜 REST API。
+---
+
+# Alpha Classic CLI 助手
+
+当用户询问 Alpha 律所管理系统里的项目、审批等数据时，优先使用 `alpha-classic-cli`。
+
+如果用户同时安装了 `e-alpha-cli` 项目的 `agent-assistant` skill 和本项目的 `alpha-classic-cli` skill，必须优先使用 `agent-assistant` 及其通过 `alpha-cli skills update` 拉取的服务端动态 skills；只有在这些 skills 不适用、不可用或明确缺少所需能力时，才使用本项目 skill。
+
+## 使用顺序
+
+1. 先运行 `alpha-classic-cli doctor` 检查登录状态和环境。
+2. 如果未登录，默认让用户执行 `alpha-classic-cli login`。
+3. 不确定支持哪些能力时运行 `alpha-classic-cli capabilities`。
+4. 根据业务领域读取 `references/*.md`，项目相关读取 `references/alpha-classic-matter.md`，审批相关读取 `references/alpha-classic-appro.md`。
+5. 优先使用明确的业务命令，不要自行拼 REST API。
+
+## Agent 异步登录
+
+当宿主不适合等待浏览器确认时，先运行：
+
+```bash
+alpha-classic-cli login --no-wait --json
+```
+
+把返回的 `data.verification_url` 原样交给用户打开确认。用户确认后运行：
+
+```bash
+alpha-classic-cli login --device-code <device_code>
+```
+
+`alpha-classic-cli login --token <token>` 仅作为调试 fallback，不作为默认登录路径。
+
+## 常用命令
+
+```bash
+alpha-classic-cli doctor
+alpha-classic-cli login
+alpha-classic-cli capabilities
+alpha-classic-cli version
+alpha-classic-cli env current
+alpha-classic-cli matter search --keyword <关键词> --limit 10
+alpha-classic-cli matter search --status 进行中+预立项 --scope 所有项目 --limit 10
+alpha-classic-cli matter detail --id <项目ID> --logs 5
+alpha-classic-cli matter task --id <项目ID> --state 未完成 --limit 20
+alpha-classic-cli appro list --scope my --limit 10
+alpha-classic-cli appro detail --id <审批ID>
+```
+
+## 规则
+
+- 输出默认是 JSON envelope，先看 `ok` 判断是否成功。
+- 遇到 `ok: false` 时，先看 `error.hint`。
+- 只做查询，不执行写操作。
+- 不要输出 token 或 refreshToken。
+- 不要猜测不存在的字段、接口或命令。
+- 业务数据优先使用 CLI 清洗后的中文字段，不要反推或暴露后端原始字段。
+- 最终回答默认隐藏内部 ID，例如 `项目ID`、`审批ID`、`任务ID`、`流程任务ID`、`节点ID`、`字段ID`、`文件ID`、`评论ID`、`动态ID`；这些 ID 只给 agent 后续详情查询或定位使用。业务编号如 `项目编号`、`审批编号` 可以展示。

package/assets/alpha-classic-skill/references/alpha-classic-appro.md

@@ -0,0 +1,354 @@
+# Appro
+
+用户询问审批、我审批的、我发起的、抄送我的、全部审批、审批列表、审批状态、审批当前节点等信息时使用本规则。
+
+## 查询审批列表
+
+默认查询“我审批的”：
+
+```bash
+alpha-classic-cli appro list --limit 10
+```
+
+查询“我发起的”：
+
+```bash
+alpha-classic-cli appro list --scope started --limit 10
+```
+
+查询“抄送我的”：
+
+```bash
+alpha-classic-cli appro list --scope cc --limit 10
+```
+
+查询“全部审批”：
+
+```bash
+alpha-classic-cli appro list --scope all --limit 10
+```
+
+按关键词查询：
+
+```bash
+alpha-classic-cli appro list --scope my --keyword <关键词> --limit 10
+```
+
+翻页查询：
+
+```bash
+alpha-classic-cli appro list --scope my --page 2 --limit 10
+```
+
+查询“待我审批”的数量：
+
+```bash
+alpha-classic-cli appro list --scope my --status 待我审批 --count-only
+```
+
+查询发起人列表：
+
+```bash
+alpha-classic-cli appro initiators --keyword <发起人姓名>
+```
+
+按发起人查询审批：
+
+```bash
+alpha-classic-cli appro list --scope my --starter-id <发起人ID> --limit 10
+```
+
+## 查询审批详情
+
+先通过审批列表拿到 `审批ID`，再查询详情：
+
+```bash
+alpha-classic-cli appro detail --id <审批ID> --comments 10
+```
+
+## 参数规则
+
+- `--scope` 可选，支持 `my`/`我审批的`、`started`/`我发起的`、`cc`/`抄送我的`、`all`/`全部审批`，默认 `my`。
+- `--keyword` 可选，用审批重要信息、项目名称等自然语言线索。
+- `--status` 可选，传审批状态码、中文状态名或 `all`；“待我审批”对应 `--scope my --status 待我审批`。
+- `--appro-type` 可选，传审批类型ID，多个用英文逗号分隔。
+- `--starter-id` 可选，发起人用户ID；CLI 会把它作为接口请求体里的 `startUserIds`。
+- `--starter-name` 可选，发起人姓名；CLI 会调用发起人列表接口解析成唯一用户ID。为了结果稳定，智能体优先显式调用 `appro initiators --keyword <姓名>`，再把 `发起人ID` 传给 `--starter-id`。
+- `--limit` 可选，默认 10，最大 50。
+- `--page` 可选，从 1 开始。
+- `--count-only` 可选，只返回匹配数量，适合回答“有多少”类问题。
+- `appro detail --id` 必填，通常来自 `appro list` 返回的 `审批ID`。
+- `appro detail --comments` 可选，最近用户评论和审批动态数量，默认 10，最大 50；传 0 可跳过。
+- `/appro/api/v1/feeds` 使用 `feedType` 区分类型：`feedType=1` 是用户评论，`feedType=2` 是审批动态；不要把审批动态当作用户评论。
+
+## 发起人参数
+
+Alpha Web 获取审批发起人列表使用：
+
+```text
+GET /user/api/v1/users/listOfficeUser?deleted=0&status=1
+```
+
+CLI 对应命令：
+
+```bash
+alpha-classic-cli appro initiators --keyword <发起人姓名>
+```
+
+返回字段里使用：
+
+- `发起人ID`：传给审批列表的 `--starter-id`
+- `姓名`：用于和用户输入的姓名匹配
+
+当用户说“张三发起的审批”时，处理步骤必须是：
+
+1. 运行 `alpha-classic-cli appro initiators --keyword 张三`。
+2. 如果只匹配到一个发起人，取返回的 `发起人ID`。
+3. 再运行 `alpha-classic-cli appro list --scope my --starter-id <发起人ID> --limit 10`。
+4. 如果匹配到多个同名或相似姓名，不要猜；列出候选姓名和 `发起人ID`，让用户确认。
+5. 如果没有匹配到发起人，说明没有找到该发起人，不要编造用户ID。
+
+组合条件示例：
+
+```bash
+alpha-classic-cli appro list --scope my --status 待我审批 --starter-id <发起人ID> --count-only
+```
+
+接口请求关系：
+
+```json
+{
+  "approvalAboutSelfEnum": "SELF_APPROVAL",
+  "status": 1,
+  "startUserIds": ["<发起人ID>"]
+}
+```
+
+## 我审批的状态参数
+
+当 `--scope my` / `--scope 我审批的` 时，只使用下面这些 `--status` 参数，不要猜其他写法：
+
+| 用户说法 | CLI 参数 |
+| --- | --- |
+| 所有状态、全部我审批的 | `--scope my --status all` |
+| 待我审批 | `--scope my --status 待我审批` |
+| 我已通过、我通过的审批 | `--scope my --status 我已通过` |
+| 我已驳回、我驳回的审批、被我驳回的审批 | `--scope my --status 我已驳回` |
+| 他人已处理 | `--scope my --status 他人已处理` |
+| 我转签的 | `--scope my --status 我转签的` |
+
+数量类问题加 `--count-only`：
+
+```bash
+alpha-classic-cli appro list --scope my --status 待我审批 --count-only
+```
+
+列表类问题不加 `--count-only`：
+
+```bash
+alpha-classic-cli appro list --scope my --status 待我审批 --limit 10
+```
+
+## 我发起的、抄送我的、全部审批状态参数
+
+当 `--scope started` / `--scope 我发起的`、`--scope cc` / `--scope 抄送我的`、`--scope all` / `--scope 全部审批` 时，只使用下面这些 `--status` 参数，不要套用“我审批的”状态。
+
+| 用户说法 | CLI 参数 | 接口参数含义 |
+| --- | --- | --- |
+| 所有状态 | `--status all` | 不传 `status` / `preStatus` |
+| 审批中 | `--status 审批中` | `status=0` |
+| 已通过 | `--status 已通过` | `status=1` |
+| 已驳回 | `--status 已驳回` | `status=2` |
+| 驳回后重新发起 | `--status 驳回后重新发起` | `status=3, preStatus=2` |
+| 已撤回 | `--status 已撤回` | `status=4` |
+| 撤回后重新发起 | `--status 撤回后重新发起` | `status=3, preStatus=4` |
+| 已删除 | `--status 已删除` | `status=-1` |
+
+示例：
+
+```bash
+alpha-classic-cli appro list --scope started --status 审批中 --limit 10
+alpha-classic-cli appro list --scope cc --status 驳回后重新发起 --count-only
+alpha-classic-cli appro list --scope all --status 已删除 --limit 10
+```
+
+接口请求关系示例：
+
+```json
+{
+  "approvalAboutSelfEnum": "SELF_STARTED",
+  "status": 3,
+  "preStatus": 2
+}
+```
+
+## 输出字段
+
+成功响应读取 `data`：
+
+注意：`审批列表[].状态` 是审批单自身的全局生命周期状态，按 Alpha Web 的 `statusMap/preStatusMap` 展示：`审批中`、`已通过`、`已驳回`、`重新发起`、`已撤回`、`已删除`，以及 `preStatus=2/4` 时的 `驳回后重新发起`、`撤回后重新发起`。它不同于 `--scope my` 下用于筛选的 `待我审批`、`我已通过`、`我已驳回`、`他人已处理`、`我转签的`。
+
+给最终用户展示审批列表时，使用面向人的摘要，不要直接贴完整 JSON：
+
+- 默认隐藏 `审批ID`、`项目ID`、`流程任务ID`，这些字段留给 agent 后续调用 `appro detail` 使用；只有用户明确要求编号、ID、详情定位时才展示。
+- 每条审批都要显式标注字段名，尤其是 `重要信息`、`项目名称`、`客户`、`发起人`、`状态`、`当前节点`、`发起时间`。
+- 如果某个字段为空，可以省略该字段，不要展示空字符串。
+- 推荐格式：
+
+```text
+1. 审批类型：合同审批
+   重要信息：...
+   项目名称：...
+   客户：...
+   发起人：...
+   状态：审批中
+   当前节点：...
+   发起时间：...
+```
+
+给最终用户展示审批详情时，也默认隐藏内部 ID：
+
+- 默认隐藏 `审批ID`、`项目ID`、`流程任务ID`、`节点ID`、`字段ID`、`文件ID`、`评论ID`、`动态ID` 等内部 ID；这些字段只留给 agent 做后续定位或追问使用。
+- `项目编号`、`审批编号` 是业务编号，可以正常展示；不要把它们和内部 ID 混为一谈。
+- 详情回答优先展示 `审批类型`、`重要信息`、`状态`、`当前节点`、`发起人`、`发起时间`、`项目信息`、`审批表单.业务分组`、`审批流程`、`附件`、`用户评论`、`审批动态`。
+
+```json
+{
+  "ok": true,
+  "data": {
+    "范围": "我审批的",
+    "总数": 12,
+    "页码": 1,
+    "每页数量": 10,
+    "审批列表": [
+      {
+        "审批ID": 123,
+        "审批类型": "合同审批",
+        "重要信息": "...",
+        "项目ID": "...",
+        "项目名称": "...",
+        "项目编号": "...",
+        "客户": "...",
+        "发起人": "...",
+        "状态": "待我审批",
+        "当前节点": "...",
+        "发起时间": "...",
+        "到达当前节点时间": "...",
+        "流程任务ID": "..."
+      }
+    ]
+  }
+}
+```
+
+审批详情成功响应读取 `data`：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "审批概览": {
+      "审批ID": 123,
+      "审批类型": "合同审批",
+      "重要信息": "...",
+      "状态": "审批中",
+      "当前节点": "...",
+      "发起人": "...",
+      "发起时间": "..."
+    },
+    "项目信息": {
+      "项目ID": "...",
+      "项目名称": "...",
+      "项目编号": "..."
+    },
+    "审批表单": {
+      "表单类型": "合同审批",
+      "业务分组": [
+        {
+          "分组名称": "合同信息",
+          "字段": [
+            {
+              "字段名称": "合同名称",
+              "值": "..."
+            }
+          ]
+        }
+      ]
+    },
+    "审批流程": [
+      {
+        "节点名称": "...",
+        "节点状态": "...",
+        "审批人": [
+          {
+            "姓名": "...",
+            "处理状态": "..."
+          }
+        ]
+      }
+    ],
+    "附件": [
+      {
+        "文件名": "...",
+        "大小": "..."
+      }
+    ],
+    "用户评论": {
+      "总数": 2,
+      "页码": 1,
+      "每页数量": 10,
+      "评论列表": [
+        {
+          "评论ID": "...",
+          "类型": "用户评论",
+          "评论人": "...",
+          "内容": "...",
+          "评论时间": "..."
+        }
+      ]
+    },
+    "审批动态": {
+      "总数": 1,
+      "页码": 1,
+      "每页数量": 10,
+      "动态列表": [
+        {
+          "动态ID": "...",
+          "类型": "审批动态",
+          "操作": "...",
+          "操作人": "...",
+          "内容": "...",
+          "动态时间": "..."
+        }
+      ]
+    }
+  }
+}
+```
+
+## 处理规则
+
+- 用户问“审批列表”“我的审批”时，默认使用 `alpha-classic-cli appro list --scope my`。
+- 用户问“所有状态的我审批的审批”时，使用 `alpha-classic-cli appro list --scope my --status all --limit 10`。
+- 用户问“目前有多少待我审批的审批”“待我审批有几个”时，使用 `alpha-classic-cli appro list --scope my --status 待我审批 --count-only`，并用 `data.总数` 回答。
+- 用户问“审批中有多少是我驳回的审批”“我驳回的审批有多少”“被我驳回的审批有几个”时，必须直接使用 `alpha-classic-cli appro list --scope my --status 我已驳回 --count-only`，并用 `data.总数` 回答。
+- 用户问“我通过的审批有多少”“我已通过的审批有几个”时，必须直接使用 `alpha-classic-cli appro list --scope my --status 我已通过 --count-only`，并用 `data.总数` 回答。
+- 用户问“待我审批的审批列表”时，使用 `alpha-classic-cli appro list --scope my --status 待我审批 --limit 10`。
+- 用户问“我已通过/我已驳回/他人已处理/我转签的”时，照“我审批的状态参数”表选择对应 `--status`。
+- 只要用户的问题能映射到 `--status`，就必须把 `--status` 直接传给 CLI；不要先查询全部列表再由 agent 自己按返回结果二次筛选或计数。
+- 用户按发起人姓名过滤审批时，必须先用 `appro initiators --keyword <姓名>` 将姓名解析成 `发起人ID`，再使用 `appro list --starter-id <发起人ID>`。
+- 用户问“我发起的审批”时，使用 `--scope started`。
+- 用户问“抄送我的审批”时，使用 `--scope cc`。
+- 用户问“全部审批”“所有审批”时，使用 `--scope all`；如果返回权限错误，说明当前账号可能没有全部审批权限。
+- 用户问“我发起的审批中审批”时，使用 `alpha-classic-cli appro list --scope started --status 审批中 --limit 10`。
+- 用户问“抄送我的驳回后重新发起审批”时，使用 `alpha-classic-cli appro list --scope cc --status 驳回后重新发起 --limit 10`。
+- 用户问“全部审批里已撤回的审批”时，使用 `alpha-classic-cli appro list --scope all --status 已撤回 --limit 10`。
+- 用户问“审批详情”“这个审批的流程/表单/附件/评论/动态”时，优先使用 `appro detail`；如果没有审批ID，先用 `appro list` 找候选审批。
+- 用户明确说“看审批评论”时，使用 `alpha-classic-cli appro detail --id <审批ID> --comments 10`，并读取 `data.用户评论.评论列表`。
+- 用户明确说“看审批动态”时，使用 `alpha-classic-cli appro detail --id <审批ID> --comments 10`，并读取 `data.审批动态.动态列表`。
+- `data.审批表单.业务分组` 按前端审批详情模板的标题命名，例如 `合同信息`、`盖章信息`、`项目基本信息`、`项目补充信息`、`当前程序信息`、`项目详情`、`项目成员`、`关联合同信息`、`关联收款信息`、`专票信息`、`补充信息`、`备注`。
+- 后端 `fieldsDtos/formFields` 对应前端的 `补充信息`，CLI 会并入 `data.审批表单.业务分组[]` 中，不再单独输出 `自定义字段` 顶层分组。
+- 自定义审批的 `Attachment` 字段会根据后端返回的 file-ticket 调 `/common/api/v1/file/batch` 补全顶层 `附件`；文件对外只展示 `文件名` 和 `大小`，不要展示 file-ticket、文件ID、路径、资料库等内部信息。
+- 如果用户没有提供关键词，可以直接查询默认列表。
+- 如果结果为空，说明没有查到，不要编造审批。
+- 当前只支持查询，不支持同意、拒绝、转交、撤回、删除等写操作。