weaver-work-cli 0.1.0

package/dist/shortcuts/invoice/operations/update.js

@@ -0,0 +1,109 @@
+import { invoiceConfirmationError, invoicePartialError, invoiceValidationError, isInvoiceNetworkError } from '../errors.js';
+import { applyChanges, assertEditable, changePreview, detailInfo, getDetail, normalizeChanges, normalizeScope, objectFingerprint, operateType, preview, reqBase, sessionMatches, stripForbiddenKeys, verifyChangedFields, workflow, } from './shared.js';
+export class InvoiceUpdatePrepareOperation {
+    name = 'invoice.update.prepare';
+    async execute(input, { host, continuation }) {
+        const scope = normalizeScope(input.scope);
+        const info = detailInfo(await getDetail({ fid: input.fid }, host));
+        assertEditable(info);
+        const changes = normalizeChanges(input.changes);
+        const diffs = changePreview(info, changes).filter((item) => !Object.is(item.from, item.to));
+        if (!diffs.length)
+            throw invoiceValidationError('changes_noop', '所有修改值都与当前值相同');
+        const effectiveChanges = Object.fromEntries(diffs.map((item) => [item.field, item.to]));
+        const session = await host.getSession();
+        const continuationToken = await continuation.issue({
+            operation: 'invoice.update.apply',
+            workflow: workflow('invoice.update', 'AWAITING_CONFIRMATION'),
+            baseUrl: session.baseUrl,
+            profile: session.profile,
+            userId: session.userId,
+            fid: String(info.fid || info.id),
+            scope,
+            fingerprint: objectFingerprint(info),
+            changes: effectiveChanges,
+            preview: preview(info),
+        });
+        return {
+            status: 'AWAITING_CONFIRMATION',
+            data: { invoice: preview(info), changes: diffs, continuation: continuationToken, expiresInSeconds: 600, workflow: workflow('invoice.update', 'AWAITING_CONFIRMATION') },
+        };
+    }
+}
+export class InvoiceUpdateApplyOperation {
+    name = 'invoice.update.apply';
+    async execute(input, { host, continuation }) {
+        if (input.confirm !== true)
+            throw invoiceConfirmationError('invoice.update.apply', { hint: '重新调用时传入 confirm=true' });
+        const lease = await continuation.verify(input.continuation, 'invoice.update.apply');
+        if (!lease.scope || typeof lease.fid !== 'string' || typeof lease.fingerprint !== 'string' || !lease.changes || typeof lease.changes !== 'object') {
+            throw invoiceValidationError('continuation_invalid', '编辑 continuation 缺少有效上下文、目标或变更指纹');
+        }
+        const session = await host.getSession();
+        if (!sessionMatches(lease, session))
+            throw invoiceValidationError('context_mismatch', '确认上下文已变化，请重新准备编辑');
+        const current = detailInfo(await getDetail({ fid: lease.fid }, host));
+        if (objectFingerprint(current) !== lease.fingerprint)
+            throw invoiceValidationError('target_changed', '发票在确认后发生变化，请重新准备编辑');
+        assertEditable(current);
+        const updated = applyChanges(stripForbiddenKeys(current), normalizeChanges(lease.changes));
+        let result;
+        try {
+            result = await host.invoiceRequest({
+                path: '/api/inc/update',
+                method: 'POST',
+                body: {
+                    mask: 0,
+                    info: updated,
+                    operate_type: operateType(lease.scope),
+                    mod_file: false,
+                    needCompareChangeField: true,
+                    skipFlag: 0,
+                    req_base: reqBase(),
+                },
+            });
+        }
+        catch (error) {
+            if (isInvoiceNetworkError(error)) {
+                throw invoicePartialError('编辑请求发送后连接中断，结果不确定，禁止自动重试', {
+                    fid: lease.fid,
+                    changes: lease.changes,
+                    workflow: workflow('invoice.update', 'EXECUTING'),
+                }, { stage: 'update' });
+            }
+            throw error;
+        }
+        let after;
+        try {
+            after = detailInfo(await getDetail({ fid: lease.fid }, host));
+        }
+        catch {
+            throw invoicePartialError('编辑接口已返回成功，但详情回查失败，结果不确定', {
+                fid: lease.fid,
+                result,
+                workflow: workflow('invoice.update', 'VERIFYING'),
+            }, { stage: 'readback' });
+        }
+        if (!verifyChangedFields(after, lease.changes)) {
+            throw invoicePartialError('编辑接口已返回成功，但回查字段不一致', {
+                fid: lease.fid,
+                expected: lease.changes,
+                result,
+                workflow: workflow('invoice.update', 'VERIFYING'),
+            }, { stage: 'readback' });
+        }
+        return {
+            status: 'COMPLETE',
+            data: {
+                fid: lease.fid,
+                scope: lease.scope,
+                updated: true,
+                verified: true,
+                changes: changePreview(current, lease.changes),
+                info: after,
+                result,
+                workflow: workflow('invoice.update', 'COMPLETE'),
+            },
+        };
+    }
+}

package/dist/shortcuts/invoice/operations/upload.js

@@ -0,0 +1,8 @@
+import { uploadInvoiceFile, workflow } from './shared.js';
+export class InvoiceUploadOperation {
+    name = 'invoice.upload';
+    async execute(input, { host }) {
+        const upload = await uploadInvoiceFile(input, host);
+        return { status: 'UPLOADED', data: { upload, workflow: workflow('invoice.ocr.preview', 'UPLOADED') } };
+    }
+}

package/dist/shortcuts/invoice/operations/validate-preview.js

@@ -0,0 +1,39 @@
+import { InvoiceCliError } from '../errors.js';
+import { detailInfo, getDetail, identityFingerprint, normalizeScope, operateType, reqBase, validationPreview, workflow, } from './shared.js';
+export class InvoiceValidatePreviewOperation {
+    name = 'invoice.validate.preview';
+    async execute(input, { host }) {
+        const scope = normalizeScope(input.scope);
+        const detail = await getDetail({ fid: input.fid }, host);
+        const info = detailInfo(detail);
+        const result = await host.invoiceRequest({
+            path: '/api/inc/valid',
+            method: 'POST',
+            body: {
+                info,
+                flag: 100,
+                is_cut: 0,
+                is_save: 1,
+                operate_type: operateType(scope),
+                needLog: false,
+                req_base: reqBase({ numericTrace: true }),
+            },
+        });
+        if (!result?.info) {
+            throw new InvoiceCliError('api', 'validation_empty', '查验接口未返回发票信息', { details: { result }, exitCode: 1 });
+        }
+        if (identityFingerprint(result.info) !== identityFingerprint(info)) {
+            throw new InvoiceCliError('api', 'validation_target_mismatch', '查验返回的票面身份字段与目标发票不一致', { exitCode: 1 });
+        }
+        return {
+            status: 'COMPLETE',
+            data: {
+                preview: validationPreview(result.info, scope, input.fid),
+                info: result.info,
+                saved: false,
+                result,
+                workflow: workflow('invoice.validate.preview', 'COMPLETE'),
+            },
+        };
+    }
+}

package/dist/shortcuts/invoice/operations.js

@@ -0,0 +1,8 @@
+import { getInvoiceOperation } from './operations/registry.js';
+import { asObject, assertNoForbiddenKeys } from './operations/shared.js';
+export async function executeInvoiceOperation(operation, rawInput, context) {
+    const handler = getInvoiceOperation(operation);
+    const input = asObject(rawInput);
+    assertNoForbiddenKeys(input);
+    return handler.execute(input, context);
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/SKILL.md

@@ -0,0 +1,36 @@
+# weaver-work-cli 使用说明
+
+本包提供一套纯净的 CLI 基础框架，并内置隔离的 E10 适配模块。
+
+模块目录分为三类：
+
+- `src/cmd`：框架内置命令、平台命令和 `skills list/read`。
+- `src/internal/e10`：E10 session、profile、auth 文件和 API client。
+- `src/shortcuts`：面向人和 Agent 的高层业务 CLI 能力，按业务模块分目录；模块内每个业务 operation 用相对独立的 class 封装。
+- `skills`：随包发布的 Agent Skill，按业务模块分目录；每个模块对应一个独立 Skill，入口 `SKILL.md` 只做路由，具体操作细节放到 `references/`，公共约束通过 `weaver-work-cli-shared` 复用。
+- `skill-template`：新增或重写业务 Skill 的模板来源；结构参考飞书 CLI 的 `skill-template`，用于保持入口、路由关键词、业务域说明和 reference 拆分方式一致。
+
+使用内置 docs 命令可以把当前文档目录复制到业务工作区：
+
+```bash
+weaver-work-cli docs copy
+```
+
+后续业务 shortcut 应在 `src/shortcuts/<name>` 下维护源码，在 `skills/weaver-work-cli-<name>` 下维护对应 Agent Skill，在 `_catalog.md` 和 `skill-template/business-info.json` 中补充对应的加载规则。业务 Skill 直接声明并调用 `weaver-work-cli` bin，不为每个业务模块复制 bootstrap 脚本。
+
+业务 Skill 目录约定：
+
+```text
+skills/weaver-work-cli-<name>/
+  SKILL.md                  入口路由：共享规则、schema、reference 索引、禁用边界。
+  product.json              可选：Skill 包元信息。
+  references/               具体业务 reference，按用户意图和 operation 分文件。
+```
+
+入口 `SKILL.md` 不承载完整接口手册。把 schema 使用、查询、文件处理、写入确认、禁用能力等拆进 reference，让 Agent 只读取当前任务真正需要的内容。
+
+## 已内置业务模块
+
+- `invoice`：E10 业票通发票管理。源码说明先读 `docs/invoice.md`；面向 Agent 时先读 `skills/weaver-work-cli-invoice/SKILL.md`，再按入口路由读取对应 reference。
+
+Agent 调用业务能力时优先使用 `weaver-work-cli --json invoice run <operation> --input -`，不要绕过 CLI 直接拼业务 HTTP。

package/docs/_catalog.md

@@ -0,0 +1,12 @@
+# weaver-work-cli 文档索引
+
+| 用户意图 | 文档 |
+| --- | --- |
+| CLI 框架、钩子、system/platform/business 分层、新增模块 | `docs/SKILL.md` |
+| E10 鉴权、profile、共享 API client | `docs/e10-auth.md` |
+| Agent Skill 模板、业务域关键词、入口和 reference 拆分方式 | `skill-template/` |
+| Agent 共享规则、安装检查、JSON 输出、高风险写入 | `skills/weaver-work-cli-shared/SKILL.md` |
+| Agent 共享规则细节：安装、E10 登录、JSON 输出、写入协议 | `skills/weaver-work-cli-shared/references/` |
+| 业票通发票管理、invoice operation、写操作 prepare/apply | `docs/invoice.md` |
+| Agent 调用业票通 CLI 的入口路由 | `skills/weaver-work-cli-invoice/SKILL.md` |
+| Agent 调用业票通 CLI 的具体 reference | `skills/weaver-work-cli-invoice/references/` |

package/docs/agent-invoice.md

@@ -0,0 +1,53 @@
+# 业票通 Agent 说明
+
+本说明用于 AI Agent 调用安装后的 `weaver-work-cli`。Agent 只负责把用户意图映射到 CLI operation 和 JSON 参数；认证、Token、固定接口、写入确认、状态回查和错误判断都由 CLI 完成。
+
+安装后的 Agent Skill 已拆为入口和 references：
+
+- `skills/weaver-work-cli-shared/SKILL.md`：安装检查、E10 认证、JSON 输出、高风险写入和安全边界。
+- `skills/weaver-work-cli-invoice/SKILL.md`：业票通入口路由。
+- `skills/weaver-work-cli-invoice/references/`：按 schema、查询、文件预览、写入、暂缓能力拆分的具体说明。
+
+## 准备
+
+```bash
+weaver-work-cli --version
+weaver-work-cli doctor --e10
+weaver-work-cli invoice schema
+```
+
+如未登录，先让用户完成：
+
+```bash
+weaver-work-cli auth login --base-url "https://weapp.xxx.cn"
+```
+
+## 固定入口
+
+Agent 优先使用：
+
+```bash
+weaver-work-cli --json invoice run <operation> --input -
+```
+
+不要直接 `curl`、`fetch` 或浏览器自动化访问 E10 `/api/inc/*`。不要输出或索取 Cookie、ETEAMSID、发票 Token。
+
+## 推荐工作流
+
+处理“把这张发票录入业票通”的典型流程：
+
+1. 查询个人票夹和企业票夹，确认目标不存在。
+2. `invoice.ocr.preview` 预览文件识别结果，预览阶段固定不保存。
+3. 用户确认后执行 `invoice.import.prepare`，输入必须显式包含 `validate` 和 `syncToOa`。
+4. 把 prepare 返回的 `continuation` 原样交给 `invoice.import.apply`，并传 `confirm=true`。
+5. 使用返回的 `fid` 回查详情，按实际结果报告查验状态、写入状态和附件信息。
+
+删除、编辑、新增同样必须使用 `prepare -> apply`。出现 `partial/write_uncertain` 时停止，不能自动重试写操作。
+
+## 暂缓能力
+
+以下原始接口文档存在，但当前不暴露为 Agent 操作：
+
+- 共享发票：缺接收人的稳定 `appid/cid/uid` 解析和共享关系回查契约。
+- 转让发票：会改变持有人，缺接收人侧归属回查契约。
+- 标记发票：缺标签定义来源、当前关系查询和移除/替换语义。

package/docs/e10-auth.md

@@ -0,0 +1,51 @@
+# E10 鉴权适配模块
+
+E10 适配模块刻意与核心 CLI 框架隔离，避免平台逻辑污染通用命令基础设施。
+
+存储路径与密钥：
+
+- 鉴权根目录：`~/.weaver-work-cli/e10`
+- Profile 目录：`~/.weaver-work-cli/e10/profiles/<profile>`
+- 当前激活 profile：`~/.weaver-work-cli/e10/profile`
+- Keychain service/account：`weaver-work-cli` / `auth-key`
+
+`weaver-work-cli` 默认不读取、不迁移 `e10-login` / `e10-cli` 的 `~/.e10-cli`
+登录态，避免用户安装本插件后因为历史登录状态被自动授权。确需复用外部 auth
+文件时，可以显式传 `--auth <path>` 或设置 `E10_AUTH_PATH`。
+
+主要命令：
+
+```bash
+weaver-work-cli auth status
+weaver-work-cli auth login --base-url "https://weapp.xxx.cn"
+weaver-work-cli auth oidc --base-url "https://weapp.xxx.cn"
+weaver-work-cli auth set --eteamsid "PCACCOUNT_xxx" --base-url "https://weapp.xxx.cn"
+weaver-work-cli auth whoami
+weaver-work-cli auth whoami --live
+weaver-work-cli auth logout
+weaver-work-cli auth profile list
+weaver-work-cli auth profile use <name>
+weaver-work-cli auth export-weaver-env
+```
+
+`auth login` 和 `auth oidc` 都走 E10 OAuth2.0 浏览器授权登录，本地默认监听
+`http://127.0.0.1:19800/callback`。如端口被占用，可以使用
+`--port 19801` 指定其他端口；如需要区分客户端来源，可以使用
+`--agent_type <value>`，默认值为 `weaver-work-cli`。
+
+无法使用浏览器回调时，可以用 `auth set` 直接写入浏览器中复制到的
+`ETEAMSID`。命令会调用 `teamsCheck` 解析当前用户、租户和组织信息，并写入
+E10 兼容的 auth 文件。
+
+`auth whoami` 默认读取本地缓存，不发网络请求；`auth whoami --live` 会调用
+`teamsCheck` 获取实时信息。`auth export-weaver-env` 会输出
+`WEAVER_BASE_URL`、`WEAVER_ETEAMSID`、`WEAVER_COOKIE`、`WEAVER_USER_AGENT` 和
+`WEAVER_AGENT_TYPE`，可通过下面方式注入到当前 shell：
+
+`auth logout` 会清理当前 profile 的本地登录凭据；也可配合
+`--profile <name>` 清理指定 profile。该命令不删除 profile 配置和 keychain
+密钥。
+
+```bash
+eval "$(weaver-work-cli auth export-weaver-env)"
+```

package/docs/invoice.md

@@ -0,0 +1,99 @@
+# 业票通发票管理 CLI
+
+来源目录：`weaver-e10-yepiaotong`，内容版本 `1.1.0`。本模块把接口文档中可安全自动化的能力封装为 `weaver-work-cli invoice` 命令，供 AI Agent 通过结构化 JSON 调用。
+
+源码位于 `src/shortcuts/invoice`。命令注册、operation manifest 和业务执行逻辑分离；具体执行逻辑在 `src/shortcuts/invoice/operations` 中按 operation class 维护。
+
+面向 Agent 的说明位于 `skills/weaver-work-cli-invoice`。入口 `SKILL.md` 只负责共享规则和 reference 路由；具体细节拆在 `skills/weaver-work-cli-invoice/references/`，与飞书 CLI 的业务 Skill 组织方式保持一致。
+
+## 公共前置
+
+先通过 E10 鉴权模块登录：
+
+```bash
+weaver-work-cli auth login --base-url "https://weapp.xxx.cn"
+weaver-work-cli auth status --no-check
+```
+
+每个业票通业务请求由 CLI 托管：
+
+1. 读取当前 `weaver-work-cli auth` Profile 的 E10 会话。
+2. 调用或复用 `/api/inc/proxy/getToken?appType=1` 取得发票业务 Token。
+3. 业务请求同时携带 E10 Cookie/ETEAMSID 和 `token` Header。
+
+Agent 不得在业务 JSON 中传 `access_token`、`app_key`、`app_secret`、Cookie、ETEAMSID 或发票 Token。
+
+## Agent 入口
+
+优先使用 `invoice run <operation>`：
+
+```bash
+weaver-work-cli invoice schema
+echo '{"page_size":10,"start_pos":0}' | weaver-work-cli --json invoice run invoice.list --input -
+```
+
+成功和失败都使用 JSON envelope。成功写 stdout；失败写 stderr，并设置非 0 退出码。
+
+## Operation 目录
+
+| Operation | 风险 | 固定规则 |
+| --- | --- | --- |
+| `invoice.list` | 只读 | 个人票夹固定 `flag=0` |
+| `invoice.enterprise.list` | 只读 | 企业票夹固定 `flag=6`，权限失败不降级个人票夹 |
+| `invoice.get` | 只读 | `fid` 优先，或按 `number` 查询 |
+| `invoice.upload` | 外部制品 | 固定上传 `ocr=1` |
+| `invoice.ocr.preview` | 上传+只读 | 固定 `flag=13`、`is_sync=1`、`is_save=1`，不保存票夹 |
+| `invoice.validate.preview` | 外部查询 | 先取详情，固定 `flag=100`、`is_save=1`，不回写查验结果 |
+| `invoice.import.prepare/apply` | 高风险写 | continuation 绑定本地文件 SHA-256；显式声明 `validate` 和 `syncToOa` |
+| `invoice.add.prepare/apply` | 高风险写 | 单张票面校验、重复检查、确认后新增并回查 |
+| `invoice.update.prepare/apply` | 高风险写 | 基于完整详情修改白名单字段，保留附件并回查 |
+| `invoice.download` | 本地文件写 | 先校验 `fileId` 属于目标 `fid`，拒绝覆盖 |
+| `invoice.delete.prepare/apply` | 高风险写 | 固定软删除 `flag=0`，确认后执行并回查 |
+
+共享、转让和标签暂不暴露给 Agent：原始文档未给出稳定的接收人 `appid/cid/uid` 解析来源、标签关系查询和写后回查契约。
+
+## 常用命令
+
+```bash
+weaver-work-cli --json invoice list --input -
+weaver-work-cli --json invoice enterprise list --input -
+weaver-work-cli --json invoice get --fid <fid>
+weaver-work-cli --json invoice upload --file ./invoice.pdf
+weaver-work-cli --json invoice ocr preview --file ./invoice.pdf
+weaver-work-cli --json invoice validate preview --fid <fid> --scope personal
+weaver-work-cli --json invoice download --fid <fid> --file-id <fileId> --output ./invoice.pdf
+```
+
+写操作必须先 prepare，再 apply：
+
+```bash
+echo '{"file":"./invoice.pdf","validate":false,"syncToOa":false}' \
+  | weaver-work-cli --json invoice import prepare --input -
+
+echo '{"file":"./invoice.pdf","continuation":"<prepare返回值>","confirm":true}' \
+  | weaver-work-cli --json invoice import apply --input -
+```
+
+`validate=false` 表示跳过查验，不能描述为“查验通过”。写操作出现网络中断、部分成功或回查失败时，CLI 返回 `partial/write_uncertain`，Agent 禁止自动重复提交。
+
+## 编辑白名单
+
+`invoice.update.prepare` 只允许修改：
+
+```text
+code
+number
+comm_info.pro.date
+comm_info.price.amount
+comm_info.price.total
+comm_info.price.dtax
+comm_info.buyer.company
+comm_info.buyer.tcode
+comm_info.payer.company
+comm_info.payer.tcode
+fylx
+currency
+currencyName
+```
+
+禁止修改 `fid/id`、附件关联、`sedit`、Dubbo 字段、认证字段、`skipFlag=1` 等内部控制字段。

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "weaver-work-cli",
+  "version": "0.1.0",
+  "description": "面向泛微工作工具链的可扩展 TypeScript CLI 基础框架（E10 业票通等能力）",
+  "type": "module",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "docs",
+    "skills",
+    "skill-template",
+    "templates",
+    "scripts"
+  ],
+  "bin": {
+    "weaver-work-cli": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "clean": "node scripts/clean.mjs",
+    "build": "npm run clean && tsc",
+    "test": "node --test --import tsx \"test/**/*.test.ts\"",
+    "start": "node dist/index.js",
+    "build:skill": "node scripts/package-skill.mjs",
+    "build:invoice-skill": "node scripts/package-skill.mjs invoice",
+    "prepublishOnly": "npm run build && npm run test",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "weaver",
+    "泛微",
+    "e10",
+    "yepiaotong",
+    "业票通",
+    "invoice",
+    "cli"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "^1.3.0",
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/scripts/clean.mjs

@@ -0,0 +1,4 @@
+import { rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+rmSync(resolve('dist'), { recursive: true, force: true });

package/scripts/package-skill.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto'
+import { copyFile, mkdir, mkdtemp, readFile, readdir, rm, stat } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const skillsRoot = path.join(repositoryRoot, 'skills')
+const sharedSkillName = 'weaver-work-cli-shared'
+const [requestedSkillArg, outputArg] = process.argv.slice(2)
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+function run(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (chunk) => { stdout += chunk })
+    child.stderr.on('data', (chunk) => { stderr += chunk })
+    child.once('error', reject)
+    child.once('close', (code) => resolve({ code: code ?? 1, stdout, stderr }))
+  })
+}
+
+function normalizeSkillName(value) {
+  if (!value || value === 'all') return null
+  if (value.includes('/') || value.includes('\\') || value === '.' || value === '..') {
+    throw new Error(`非法 Skill 名称：${value}`)
+  }
+  if (!/^[A-Za-z0-9._-]+$/u.test(value)) {
+    throw new Error(`非法 Skill 名称：${value}`)
+  }
+  return value.startsWith('weaver-work-cli-') ? value : `weaver-work-cli-${value}`
+}
+
+async function exists(filename) {
+  try {
+    await stat(filename)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function listSkillDirs() {
+  const entries = await readdir(skillsRoot, { withFileTypes: true })
+  const skills = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const skillName = entry.name
+    if (await exists(path.join(skillsRoot, skillName, 'SKILL.md'))) skills.push(skillName)
+  }
+  return skills.sort()
+}
+
+async function resolveSkillNames() {
+  const requestedSkill = normalizeSkillName(requestedSkillArg)
+  const allSkills = await listSkillDirs()
+  if (!requestedSkill) return allSkills
+  if (!allSkills.includes(requestedSkill)) throw new Error(`未知 Skill：${requestedSkill}`)
+  const names = []
+  if (requestedSkill !== sharedSkillName && allSkills.includes(sharedSkillName)) names.push(sharedSkillName)
+  names.push(requestedSkill)
+  return names
+}
+
+function defaultOutput(skillNames) {
+  if (requestedSkillArg && requestedSkillArg !== 'all') {
+    const requestedSkill = normalizeSkillName(requestedSkillArg)
+    return path.join(repositoryRoot, 'dist', `${requestedSkill}-skill.zip`)
+  }
+  if (skillNames.length === 1) return path.join(repositoryRoot, 'dist', `${skillNames[0]}-skill.zip`)
+  return path.join(repositoryRoot, 'dist', 'weaver-work-cli-skills.zip')
+}
+
+function shouldSkip(entry, relativePath) {
+  if (entry.name === '.DS_Store' || entry.name.startsWith('.')) return true
+  if (entry.isDirectory() && ['assets', 'node_modules', 'scripts'].includes(entry.name)) return true
+  return false
+}
+
+function assertSafeRelativePath(relativePath) {
+  if (/(?:token|cookie|eteamsid)/iu.test(relativePath)) {
+    throw new Error(`Skill ZIP 包含禁止条目：${relativePath}`)
+  }
+}
+
+async function copySkill(skillName, stagingRoot, packagedEntries) {
+  const sourceRoot = path.join(skillsRoot, skillName)
+  const packageRoot = path.join(stagingRoot, skillName)
+  await stat(path.join(sourceRoot, 'SKILL.md'))
+
+  async function copyDir(relativeDir = '') {
+    const sourceDir = path.join(sourceRoot, relativeDir)
+    const targetDir = path.join(packageRoot, relativeDir)
+    await mkdir(targetDir, { recursive: true, mode: 0o700 })
+
+    const entries = (await readdir(sourceDir, { withFileTypes: true }))
+      .sort((a, b) => a.name.localeCompare(b.name))
+    for (const entry of entries) {
+      const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name
+      if (shouldSkip(entry, relativePath)) continue
+      assertSafeRelativePath(relativePath)
+      const source = path.join(sourceRoot, relativePath)
+      const target = path.join(packageRoot, relativePath)
+      if (entry.isDirectory()) {
+        await copyDir(relativePath)
+      } else if (entry.isFile()) {
+        await mkdir(path.dirname(target), { recursive: true, mode: 0o700 })
+        await copyFile(source, target)
+        packagedEntries.push(`${skillName}/${relativePath}`)
+      }
+    }
+  }
+
+  await copyDir()
+
+  const productJson = path.join(packageRoot, 'product.json')
+  if (await exists(productJson)) {
+    const product = JSON.parse(await readFile(productJson, 'utf8'))
+    if (product.product !== 'weaver-work-cli' || product.packageName !== 'weaver-work-cli') {
+      throw new Error(`${skillName}/product.json 包名不符合 weaver-work-cli`)
+    }
+  }
+}
+
+const skillNames = await resolveSkillNames()
+if (skillNames.length === 0) throw new Error('没有可打包的 Skill')
+
+const output = path.resolve(outputArg || defaultOutput(skillNames))
+const stagingRoot = await mkdtemp(path.join(os.tmpdir(), 'weaver-work-cli-skill-'))
+const packagedEntries = []
+
+try {
+  await mkdir(path.dirname(output), { recursive: true, mode: 0o700 })
+  for (const skillName of skillNames) {
+    await copySkill(skillName, stagingRoot, packagedEntries)
+  }
+
+  await rm(output, { force: true })
+  const zipResult = await run('zip', ['-X', '-q', '-r', output, ...skillNames], stagingRoot)
+  if (zipResult.code !== 0) throw new Error(`Skill ZIP 打包失败：${zipResult.stderr.trim()}`)
+
+  const archive = await readFile(output)
+  const listResult = await run('unzip', ['-Z1', output], repositoryRoot)
+  if (listResult.code !== 0) throw new Error(`Skill ZIP 校验失败：${listResult.stderr.trim()}`)
+
+  const actualEntries = listResult.stdout.trim().split(/\r?\n/u).filter((entry) => entry && !entry.endsWith('/')).sort()
+  const expectedEntries = packagedEntries.sort()
+  if (JSON.stringify(actualEntries) !== JSON.stringify(expectedEntries)) {
+    throw new Error(`Skill ZIP 闭包不匹配：${JSON.stringify(actualEntries)}`)
+  }
+  if (archive.length > 256 * 1024) throw new Error(`Skill ZIP 超过 256 KiB：${archive.length}`)
+
+  console.log(JSON.stringify({ ok: true, output, bytes: (await stat(output)).size, sha256: sha256(archive), skills: skillNames, entries: actualEntries }, null, 2))
+} finally {
+  await rm(stagingRoot, { recursive: true, force: true })
+}

package/scripts/sync-docs.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { existsSync, cpSync, rmSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const source = resolve(root, 'docs');
+const target = resolve(root, 'dist-docs');
+
+if (!existsSync(source)) {
+  console.error('[sync-docs] docs directory does not exist: ' + source);
+  process.exit(1);
+}
+
+rmSync(target, { recursive: true, force: true });
+cpSync(source, target, { recursive: true });
+console.log('[sync-docs] copied docs to ' + target);