weaver-work-cli 0.1.0

package/skills/weaver-work-cli-shared/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: weaver-work-cli-shared
+description: weaver-work-cli 共享规则：安装检查、E10 认证、JSON 输出、高风险写入、安全边界和引用路由。
+metadata:
+  requires:
+    bins: ["weaver-work-cli"]
+---
+
+# weaver-work-cli 共享规则
+
+所有 `weaver-work-cli-*` Skill 共享的底座：命令可用性、E10 认证、JSON 输出契约与高风险操作。
+
+## 通用准则
+
+1. 执行业务命令前先确认用法：优先读当前业务 Skill 和被路由到的 reference，必要时跑对应命令的 `--help` 或 `schema`，不要猜参数。
+
+2. 首次使用先确认 CLI 可用：
+
+```bash
+weaver-work-cli --version
+weaver-work-cli doctor --e10
+```
+
+3. 业务输入只描述业务对象和意图。认证、Cookie、ETEAMSID、业务 Token、接口地址和回查细节都由 CLI 托管。
+
+## 输出契约
+
+Agent 调用业务能力时优先加 `--json`。成功看进程退出码 0 和 JSON envelope 的 `ok=true`；失败看非 0 退出码和 stderr JSON 的 `error.type/subtype/message`。不要用老式 `code == 0` 判断成功。
+
+返回 `partial`、`write_uncertain`、登录失效、回查失败或网络中断时，立即停止当前写流程，不自动重试写入或删除。
+
+## Reference 强触发索引
+
+命中任一触发条件时，执行下一步前读取对应 reference。命中多条时按表中顺序读取，同一 reference 只读取一次。
+
+| 强触发条件 | Reference |
+| --- | --- |
+| 命令不可用、安装、构建、全局 link、检查可用 skill | [`weaver-work-cli-installation.md`](references/weaver-work-cli-installation.md) |
+| 登录、profile、E10 会话、baseUrl、auth 文件、`WEAVER_*` 环境变量；**未登录或登录失效（需要用户提供登录域名）** | [`e10-auth-and-session.md`](references/e10-auth-and-session.md) |
+| 判断 stdout/stderr、JSON envelope、退出码、脚本封装、自动化调用 | [`json-output-contract.md`](references/json-output-contract.md) |
+| 准备执行写入/删除/导入/更新、遇到 `confirmation.required`、`partial.write_uncertain`、网络中断或回查失败 | [`high-risk-write.md`](references/high-risk-write.md) |
+
+## 安全规则
+
+1. 禁止输出或索取 Cookie、ETEAMSID、业务 Token、access token、app key、app secret。
+
+2. 禁止绕过 `weaver-work-cli` 直接 `curl`、`fetch`、浏览器自动化或访问 E10 业务接口。
+
+3. 写入、删除、导入、更新等高风险操作必须使用 CLI 提供的确认流程；业务 Skill 要求 `prepare -> apply` 时，必须把 prepare 返回的 continuation 原样传给 apply，并在 apply 前取得用户明确确认。
+
+4. 不能猜测 CLI 未暴露的内部字段、接口路径、ID 解析逻辑或回查语义。
+
+5. 未登录或登录失效（`authentication` / `session_expired` / `auth status` 未登录）时，必须先通过宿主提问或弹框向用户确认 E10 登录域名，或用 `auth profile list` 让用户选择已有 profile；**禁止**使用示例占位域名登录，也禁止在拿到域名前反复重试业务命令。具体流程读取 [`e10-auth-and-session.md`](references/e10-auth-and-session.md)。

package/skills/weaver-work-cli-shared/references/e10-auth-and-session.md

@@ -0,0 +1,83 @@
+# E10 认证与会话
+
+## 什么时候读取
+
+用户需要登录、切换 profile、诊断 E10 连接、处理登录失效，或任务涉及 `base-url`、auth 文件、Keychain、`WEAVER_*` 环境变量时读取本文件。
+
+## 基本检查
+
+```bash
+weaver-work-cli auth status --no-check
+weaver-work-cli auth whoami
+```
+
+`--no-check` 只读取本地登录态；需要实际验证服务端可用性时使用业务命令或明确带 live 校验的命令。
+
+## 未登录 / 登录失效：必须先向用户提问登录域名，再登录
+
+业务命令依赖 E10 登录态。出现以下任一情况即判定为未登录或登录失效：
+
+- `weaver-work-cli auth status` 输出 `loggedIn: false`，或本地不存在 auth 文件
+- `weaver-work-cli doctor --e10` 的 `e10AuthFile` 检查为 `ok: false`
+- 业务命令失败，stderr JSON 中 `error.type === "authentication"`（如 `E10 auth not found`）
+- 业务命令返回 `error.subtype === "session_expired"`（E10 登录态 401/302 失效）
+
+此时**禁止**：
+
+- 使用示例占位域名（如 `https://weapp.xxx.cn`）或自行猜测域名执行登录
+- 未向用户确认登录域名前，反复重试业务命令
+- 要求用户提供 Cookie、ETEAMSID、业务 Token（见安全边界）
+
+**正确流程（按序执行，缺一不可）：**
+
+1. **先调用宿主提供的提问 / 弹框能力询问用户**，让用户二选一：
+   - 输入本次要登录的 E10 登录域名（base URL），形如 `https://<企业域名>`；或
+   - 从已有 profile 中选择一个已登录环境：先运行 `weaver-work-cli auth profile list` 列出候选，让用户选择。
+2. 用户提供了**新域名**时，用真实域名执行浏览器 OAuth 登录：
+   ```bash
+   weaver-work-cli auth login --base-url "<用户输入的域名>"
+   ```
+   端口冲突时加 `--port 19801`。
+3. 用户选择了**已有 profile** 时，切换后验证登录态：
+   ```bash
+   weaver-work-cli auth profile use <name>
+   weaver-work-cli auth status
+   ```
+4. 登录成功后再继续原业务操作。仍失败时，把 `error.type/subtype/message` 原样反馈给用户并停止，不要自动重试。
+
+登录域名一律以用户实际提供为准；拿不到域名前，不要执行任何依赖登录态的业务命令。
+
+## 登录
+
+先取得用户确认的登录域名（见上节流程），再让用户通过浏览器 OAuth 登录：
+
+```bash
+weaver-work-cli auth login --base-url "<用户确认的登录域名>"
+```
+
+如果端口冲突：
+
+```bash
+weaver-work-cli auth login --base-url "<用户确认的登录域名>" --port 19801
+```
+
+保底方式是让用户手动写入浏览器中的 `ETEAMSID`：
+
+```bash
+weaver-work-cli auth set --eteamsid "PCACCOUNT_xxx" --base-url "<用户确认的登录域名>"
+```
+
+## Profile 与环境
+
+```bash
+weaver-work-cli auth profile list
+weaver-work-cli auth profile current
+weaver-work-cli auth profile use <name>
+weaver-work-cli --profile <name> auth status --no-check
+```
+
+通过 `weaver-work-cli run` 执行外部命令时，CLI 会按当前 profile 注入 `WEAVER_BASE_URL`、`WEAVER_ETEAMSID`、`WEAVER_COOKIE`、`WEAVER_USER_AGENT` 和 `WEAVER_AGENT_TYPE`。这些值只给子进程使用，不应在回复或日志中明文展示。
+
+## 安全边界
+
+Agent 不要要求用户贴 Cookie、ETEAMSID、业务 Token、app key 或 app secret。业务 Skill 只负责调用 CLI；登录态读取、Cookie 拼接、业务 Token 获取和 HTTP header 注入都由 `weaver-work-cli` 内部完成。

package/skills/weaver-work-cli-shared/references/high-risk-write.md

@@ -0,0 +1,36 @@
+# 高风险写入协议
+
+## 什么时候读取
+
+准备执行新增、导入、更新、删除、确认写入，或看到 `confirmation.required`、`partial.write_uncertain`、网络中断、回查失败时读取本文件。
+
+## 固定流程
+
+高风险业务能力必须由 CLI 的 `prepare -> apply` 流程承载：
+
+1. 调用 `.prepare` 获取 `preview`、`continuation`、`expiresInSeconds` 和 `workflow`。
+2. 把 `preview` 中的目标对象、变更内容、风险和关键参数展示给用户。
+3. 用户明确确认后，调用对应 `.apply`，传入 prepare 返回的 `continuation` 和 `confirm=true`，或使用命令行 `--yes`。
+4. `.apply` 成功后以 CLI 回查结果为准报告结果。
+
+`continuation` 由 CLI 生成并验证，可能绑定当前 `baseUrl`、profile、userId、目标对象指纹、本地文件 SHA-256 和业务选项。不要修改、解码、复用或手工构造 continuation。
+
+## 停止条件
+
+出现以下任一情况时停止写流程，不自动重复提交：
+
+- `error.type === "partial"` 且 `error.subtype === "write_uncertain"`
+- 写入请求发送后网络中断
+- 服务端返回部分成功
+- 写入接口返回成功但详情回查失败
+- 回查结果与预期目标或变更不一致
+- CLI 提示上下文、目标文件、目标对象或 continuation 已变化
+
+停止后向用户说明已知的 `workflow.state`、已尝试目标、成功/失败项和需要人工确认的点。
+
+## 不允许的做法
+
+- 在用户未确认前补 `confirm=true` 或 `--yes`
+- 将失败的 `.apply` 静默重跑
+- 用当前输入重新拼一个 apply payload 代替 prepare 结果
+- 猜测 CLI 未暴露的接口路径、Token、Cookie、内部控制字段或写后回查语义

package/skills/weaver-work-cli-shared/references/json-output-contract.md

@@ -0,0 +1,61 @@
+# JSON 输出契约
+
+## 什么时候读取
+
+需要判断命令成功或失败、编写脚本封装、处理 stdout/stderr，或连续执行多个 Agent operation 时读取本文件。
+
+## 成功 envelope
+
+成功写入 stdout，退出码为 0：
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "operation": "invoice.list",
+  "data": {},
+  "meta": { "status": "COMPLETE" },
+  "warnings": []
+}
+```
+
+判断成功使用退出码 0 和 `ok === true`。不要用 `code === 0`，成功 envelope 没有顶层 `code/msg`。
+
+## 失败 envelope
+
+失败写入 stderr，退出码非 0：
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": false,
+  "error": {
+    "type": "validation",
+    "subtype": "input_invalid",
+    "message": "必须提供 fid 或 number",
+    "retryable": false
+  }
+}
+```
+
+错误判断优先看：
+
+- `error.type`
+- `error.subtype`
+- `error.message`
+- `error.retryable`
+- `error.stage`
+- 进程退出码
+
+## 退出码
+
+| 退出码 | 含义 |
+| --- | --- |
+| `0` | 成功 |
+| `2` | 参数或业务输入错误 |
+| `3` | 认证错误 |
+| `4` | 网络错误 |
+| `10` | 需要明确确认 |
+| `11` | 部分完成或结果不确定 |
+
+`retryable=true` 只表示读操作或准备阶段可能可以重试；写入请求已经发出后，遇到 `partial/write_uncertain` 必须停止并交给用户判断。

package/skills/weaver-work-cli-shared/references/weaver-work-cli-installation.md

@@ -0,0 +1,61 @@
+# 安装与可用性检查
+
+## 什么时候读取
+
+命令不可用、版本不确定、用户刚安装、全局命令可能指向旧版本，或需要确认当前安装包含哪些 Agent Skill 时读取本文件。
+
+## 检查命令
+
+```bash
+weaver-work-cli --version
+weaver-work-cli setup invoice
+weaver-work-cli doctor --e10
+weaver-work-cli skills list
+```
+
+`weaver-work-cli skills list` 只证明包内 Skill 文件可读，不证明业务 API 可用；E10 登录态和 live API 仍需按业务命令实际验证。
+
+## 本地源码安装
+
+开发或本机调试时可以从源码构建并 link：
+
+```bash
+# 在克隆到本地的仓库根目录执行（将 <repo-root> 替换为实际路径）
+cd <repo-root>
+npm install
+npm run build
+npm link
+weaver-work-cli --help
+```
+
+如果怀疑全局 `weaver-work-cli` 仍是旧版本，在仓库内验证时优先直接调用当前构建产物：
+
+```bash
+node dist/index.js --version
+node dist/index.js commands list
+node dist/index.js skills list
+```
+
+## 推荐交付模式
+
+`weaver-work-cli` npm 包是唯一必须安装的运行时，包含 CLI 命令、E10 鉴权、
+发票业务 operation 和随包 Agent Skill 文档。普通用户安装 npm 包后即可使用：
+
+```bash
+npm install -g weaver-work-cli
+weaver-work-cli setup invoice
+weaver-work-cli auth login --base-url "<E10_BASE_URL>"
+weaver-work-cli invoice schema
+```
+
+如果当前环境需要让 Codex/Agent 直接加载发票 Skill，优先使用随包一键安装：
+
+```bash
+weaver-work-cli skills install invoice
+```
+
+该命令会同时安装 `weaver-work-cli-shared` 和 `weaver-work-cli-invoice` 到
+`$CODEX_HOME/skills`；未设置 `CODEX_HOME` 时使用 `~/.codex/skills`。
+
+交付给 Agent 的 Skill ZIP 不内置运行时，只声明依赖本机可用的 `weaver-work-cli`
+bin。ZIP 主要用于平台导入、离线分发或版本归档，不应作为普通用户的必经安装步骤。

package/templates/shortcut/index.ts.tpl

@@ -0,0 +1,19 @@
+import { MODULE_NAMEPingOperation } from './operations/ping.js';
+import type { CliCommand } from '../../types.js';
+
+const pingOperation = new MODULE_NAMEPingOperation();
+
+export const MODULE_NAME_SHORTCUT: CliCommand = {
+  name: 'MODULE_NAME',
+  description: 'MODULE_NAME business shortcut',
+  category: 'shortcut',
+  register({ program, action }) {
+    const command = program.command('MODULE_NAME').description('MODULE_NAME business commands');
+
+    command.command('ping')
+      .description('Test MODULE_NAME business shortcut wiring')
+      .action(action(async (ctx) => {
+        ctx.output.write(await pingOperation.execute(ctx));
+      }));
+  },
+};

package/templates/shortcut/operations/ping.ts.tpl

@@ -0,0 +1,7 @@
+import type { CliContext } from '../../../core/context.js';
+
+export class MODULE_NAMEPingOperation {
+  async execute(_ctx: CliContext): Promise<Record<string, unknown>> {
+    return { shortcut: 'MODULE_NAME', ok: true };
+  }
+}