@meritsandtree/mt-os-cli 0.1.2

package/README.md

@@ -0,0 +1,223 @@
+# `@meritsandtree/mt-os-cli`
+
+`mt-os-cli` 是 MTOS 律所管理系统的本地安装、登录、诊断和 HTTP Tool 调用工具。常规调用链路是：
+
+```text
+Codex / Claude Code -> MTOS MCP -> 业务 tools
+```
+
+不走 MCP 时，也可以直接通过 CLI 调用服务端 HTTP Tool：
+
+```text
+mt-os-cli tool list/get/call/upload -> MTOS HTTP Tool 接口
+```
+
+默认环境是 `test`，默认服务地址是 `https://testlaw.meritsandtree.com`。
+
+## 安装
+
+```bash
+npm i -g @meritsandtree/mt-os-cli
+```
+
+本地开发仓库调试时可直接执行：
+
+```bash
+npm link /Users/june/IdeaProjects/e-mt-os-cli
+```
+
+## 自动更新
+
+CLI 会按本地缓存轻量提醒新版本，不会在普通业务命令里静默替用户升级。真正安装新版本需要显式执行：
+
+```bash
+mt-os-cli update --check
+mt-os-cli update
+```
+
+- `mt-os-cli update --check`：只检查 npm 最新版本，不执行安装，也不刷新本机 skill。
+- `mt-os-cli update`：检测当前安装方式；如果当前命令来自 npm 全局安装且本机有 npm，会执行 `npm install -g @meritsandtree/mt-os-cli@<latest>`，成功后再执行 `mt-os-cli skills update`。
+- JSON 输出会在有缓存命中新版本时附加 `_notice.update`，提示执行 `mt-os-cli update`；如需关闭提醒，可设置 `MT_OS_CLI_NO_UPDATE_NOTIFIER=1`。
+
+## 环境预设
+
+`mt-os-cli` 内置 4 套环境预设：
+
+- `local`：`http://localhost:8087`
+- `dev`：`http://localhost:8087`
+- `test`：`https://testlaw.meritsandtree.com`
+- `prod`：`https://law.meritsandtree.com`
+
+默认就是 `test`，因此测试环境可直接执行：
+
+```bash
+mt-os-cli auth login
+mt-os-cli auth check
+```
+
+本地联调时先启动 `law-app`，再显式执行：
+
+```bash
+mt-os-cli env use local
+```
+
+生产环境使用前需要显式切换：
+
+```bash
+mt-os-cli env use prod
+```
+
+## 常用命令
+
+```bash
+mt-os-cli env list
+mt-os-cli env current
+mt-os-cli env use test
+mt-os-cli auth login
+mt-os-cli auth login --no-wait --json
+mt-os-cli auth login --device-code <device_code>
+mt-os-cli auth token --env test --token <token>
+mt-os-cli auth status
+mt-os-cli auth check
+mt-os-cli auth whoami
+mt-os-cli auth refresh
+mt-os-cli doctor
+mt-os-cli skills
+mt-os-cli skills update
+mt-os-cli skill codex
+mt-os-cli skill claude
+mt-os-cli skill openclaw
+mt-os-cli mcp
+mt-os-cli mcp install
+mt-os-cli mcp install openclaw
+mt-os-cli tool list
+mt-os-cli tool get query_customer --format json
+mt-os-cli schema query_customer
+mt-os-cli tool call query_customer --args-json '{}' --format json
+mt-os-cli tool upload ./合同附件.pdf
+mt-os-cli api GET /law/api/v1/cli/tools --query-json '{"domain":"customer"}'
+mt-os-cli api GET /agent/api/v1/cli/skills
+```
+
+## 推荐使用流程
+
+首次使用：
+
+```bash
+mt-os-cli auth login
+```
+
+- 登录会创建设备授权码，在终端打印二维码和授权链接，用户在浏览器里确认授权后保存本地登录态。
+- 登录成功后会安装 Codex、Claude、OpenClaw 可读取的本地技能/指令，并从 `/agent/api/v1/cli/skills` 拉取服务端最新 skill。
+- 登录不会默认写入 MCP 配置；需要 MCP 时单独执行 `mt-os-cli mcp install [codex|claude|openclaw|all]`。
+- Agent 代用户登录时，推荐用 `mt-os-cli auth login --no-wait --json`，把输出里的 `verification_url` 原样发给用户，再用 `mt-os-cli auth login --device-code <device_code>` 继续轮询授权结果。
+- `mt-os-cli auth check` 只校验 token 是否有效，token 失效会以非 0 退出码返回结构化错误。
+- `mt-os-cli doctor` 用来检查本地 session、客户端安装状态、MCP 配置是否完整。
+
+## 已安装内容
+
+- Codex skill：`~/.codex/skills/mt-os/SKILL.md`
+- Claude 入口指令：`~/.claude/CLAUDE.md`
+- Claude skill：`~/.claude/skills/mt-os/SKILL.md`
+- OpenClaw skill：`~/.openclaw/skills/mt-os/SKILL.md`
+- 远程 MCP 服务名：`mt-os`
+- 业务能力说明以 `mt-os-cli tool list/get/schema` 返回的实时 Tool 元数据为准。
+
+## Tool 调用
+
+先看服务端实时开放能力：
+
+```bash
+mt-os-cli tool list --format table
+mt-os-cli tool list --domain customer --format table
+mt-os-cli schema query_customer
+```
+
+再调用具体 Tool：
+
+```bash
+mt-os-cli tool call query_customer --args-json '{}' --format json
+mt-os-cli tool call create_customer --args-json '{"customerName":"测试客户"}' --dry-run
+```
+
+如果命令返回 `confirmation_required`，需要确认参数和风险后再追加 `--confirm` 重试。
+
+## Raw API 调试
+
+`mt-os-cli api` 用于排查 HTTP 层问题，默认只允许白名单路径前缀：
+
+```bash
+mt-os-cli api GET /law/api/v1/cli/tools --query-json '{"domain":"customer"}'
+mt-os-cli api GET /agent/api/v1/cli/skills
+mt-os-cli api POST /law/api/v1/cli/tools/query_customer/invoke --data-json '{"arguments":{}}' --confirm
+```
+
+- 允许前缀：`/law/api/v1/cli/tools`、`/agent/api/v1/cli/skills`、`/user/api/v1/token/check`、`/user/api/v1/token/refresh`、`/user/api/v1/cli-device-auth`。
+- 非 GET 请求必须显式加 `--confirm`。
+- 返回 HTTP 状态码、响应头和原始响应体，适合调试服务端协议差异。
+
+## Skill 更新流程
+
+`mt-os-cli skills update` 默认先请求服务端 `/agent/api/v1/cli/skills`，把服务端动态 skill 写到 Codex、Claude 和 OpenClaw 的本机 skills 目录。只有远程不可用时，才写入 npm 包内置的 bootstrap skill 兜底。
+
+当前 npm 包只保留非业务 bootstrap 模板：
+
+- `assets/agent-skill/SKILL.md`
+- `assets/claude/CLAUDE.md`
+
+模板更新流程：
+
+1. 修改 `assets/agent-skill/SKILL.md` 或 `assets/claude/CLAUDE.md`。
+2. 执行 `npm run typecheck && npm test && npm run build`。
+3. 重新执行 `mt-os-cli skills update --source bundled`、`mt-os-cli auth login` 或 `mt-os-cli install codex/claude/openclaw`，把 bootstrap 覆盖到用户目录。
+4. 如果要对外发布，再升级 `package.json` 版本并发布 npm。
+
+服务端动态 skill 更新流程：
+
+1. 业务模块返回自己的 `CliSkillFileVO` 列表。
+2. 部署服务端后执行 `mt-os-cli skills update --source remote`，只拉远程 skill。
+3. 日常使用 `mt-os-cli skills update` 即可；远程成功时以服务端清单为准，远程不可用时写入 bootstrap 兜底。
+4. CLI 会在各客户端 skills 根目录记录 `.mt-os-cli-remote-skills.json`，并按服务端清单清理旧文件。
+
+## MCP 测试
+
+Codex：
+
+```bash
+mt-os-cli mcp install codex
+codex exec --skip-git-repo-check "查一下我名下有多少个客户"
+```
+
+Claude Code：
+
+```bash
+mt-os-cli mcp install claude
+claude mcp list
+claude mcp get mt-os
+claude -p --permission-mode bypassPermissions "查一下我参与的进行中项目，给我前5个"
+```
+
+OpenClaw：
+
+```bash
+mt-os-cli mcp install openclaw
+openclaw mcp show mt-os --json
+```
+
+## 彻底卸载
+
+如果你要做一次完全干净的本机复测，推荐按下面两步执行：
+
+```bash
+mt-os-cli uninstall
+npm uninstall -g @meritsandtree/mt-os-cli
+```
+
+- `mt-os-cli uninstall` 会清理 Keychain 中的本地登录态、Codex/Claude/OpenClaw 的 MTOS MCP 配置、由 `mt-os-cli` 安装或远程下发的 `mt-os`、`agent-*`、`tool-index` 等技能、Claude 托管指令区块，以及 `~/.config/mt-os-cli`。
+- `npm uninstall -g @meritsandtree/mt-os-cli` 只会移除全局 `mt-os-cli` 命令；如果直接执行这一步，npm 不会替你清理 Keychain session 和本地配置，所以必须先执行 `mt-os-cli uninstall`。
+
+## 诊断建议
+
+- `mt-os-cli doctor` 应至少看到 `session: present` 和 `api_check: ok`。
+- `mt-os-cli auth check` 适合 Agent 在执行业务命令前轻量校验 token；失败时按返回的 JSON 错误 hint 重新登录。
+- `mt-os-cli auth refresh` 适合在 token 即将过期时主动刷新；如果客户端 MCP Bearer 也需要更新，再执行 `mt-os-cli mcp install`。

package/assets/agent-skill/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: mt-os
+description: 使用 mt-os-cli 或服务端已开放 Tool 处理 MTOS 律所管理系统客户、项目、审批、计时、附件、财务、报销和看板统计等业务请求时使用。
+---
+
+# MTOS
+
+## 启动规则
+
+- 首次安装或怀疑本机技能说明已更新时，先执行 `mt-os-cli skills update --source bundled codex`，刷新 `~/.codex/skills/mt-os/SKILL.md`。
+- 业务能力以当前服务端开放的 Tool 清单为准；不要只凭历史工具名猜测 MTOS 工具名或参数。
+- 先执行 `mt-os-cli tool list --format table` 查看可用 Tool，再用 `mt-os-cli schema <toolName>` 或 `mt-os-cli tool get <toolName>` 确认实时参数。
+- 优先使用已开放的 MCP tools；MCP 不可用但本机已经登录时，用 `mt-os-cli tool list/get/call/upload` 做 HTTP 直调。
+- 不要自行拼未开放 REST 接口，不要猜测工具名、参数名或返回结构。
+
+## 登录和刷新
+
+- 登录态不确定时，先执行 `mt-os-cli auth check`。
+- 需要代用户登录时，执行 `mt-os-cli auth login --no-wait --json`，把输出里的 `verification_url` 原样给用户，再执行 `mt-os-cli auth login --device-code <device_code>` 等待授权结果。
+- token 失效时先执行 `mt-os-cli auth refresh`；refresh 失败再重新执行 `mt-os-cli auth login`。
+- 如果当前宿主使用 MCP 且 Bearer 需要更新，再执行 `mt-os-cli mcp install`。
+
+## 安全边界
+
+- `confirmPolicy` 为 `ALWAYS` 或 `confirmationRequired` 为 `true` 的工具必须等待用户明确确认。
+- 命令返回 `confirmation_required` 且退出码为 `10` 时，不要当普通失败处理；先向用户确认风险和关键参数，再追加 `--confirm` 重试。
+- 上传本地附件时，使用 `mt-os-cli tool upload <filePath>`，拿到真实文件地址后再用于后续工具。
+- 结果为空、权限不足、同名歧义时，要明确告诉用户当前状态。
+- 没有出现在 `mt-os-cli tool list`、`mt-os-cli schema` 或 MCP 工具列表里的能力，按暂未开放处理。

package/assets/claude/CLAUDE.md

@@ -0,0 +1,10 @@
+# Agent Skills Entry
+
+当用户在 Claude Code 中通过当前 CLI 处理 MTOS 业务数据时：
+
+- 先查看 `~/.claude/skills/mt-os/SKILL.md`
+- 首次安装或怀疑本机技能说明已更新时，先执行 `mt-os-cli skills update --source bundled claude`
+- 优先使用已开放的 MCP tools，不要自行拼 REST 接口
+- 如果 MCP 工具不可用，但本机已经执行过 `mt-os-cli auth login`，可以用 `mt-os-cli auth check`、`mt-os-cli schema`、`mt-os-cli tool list/get/call/upload` 做 HTTP 直调烟测
+- 需要代用户登录时，用 `mt-os-cli auth login --no-wait --json` 发起授权，原样转发 `verification_url`，再用 `mt-os-cli auth login --device-code <device_code>` 等待结果
+- token 过期时，先用 `mt-os-cli auth refresh` 刷新本机登录态；需要更新 Claude MCP Bearer 时再执行 `mt-os-cli mcp install claude`