weaver-work-cli 0.1.6 → 0.1.7

package/dist/shortcuts/workflow/operations.js

@@ -0,0 +1,119 @@
+import { workflowSuccess } from './operations/types.js';
+import { getWorkflowOperation } from './operations/registry.js';
+import { assertNoForbiddenKeys, asObject } from './operations/shared.js';
+import { WorkflowCliError, CLARIFICATION_SUBTYPE } from './errors.js';
+/**
+ * 幂等回报：一次性 continuation 被**重复执行**时，若上一次已经执行成功，就不能把成功报成失败。
+ *
+ * 场景（2026-09-16 线上）：apply 命令被执行两次——沙箱内首跑已成功写入并消费句柄，宿主逃逸重跑
+ * 只能报 `continuation_consumed`，把**已经生效的写入表达成失败**；模型无法分辨真假，只能靠三次
+ * 零散查询把真相拼回来。现在底层（continuation.ts）会把「上一次已成功」标成
+ * `continuation_already_applied`，在这一层转成**成功信封**（`status: ALREADY_APPLIED`），
+ * 并把上一次的执行结果一并回给调用方。
+ */
+function idempotentReplayEnvelope(error, operation) {
+    if (!(error instanceof WorkflowCliError) || error.subtype !== 'continuation_already_applied')
+        return null;
+    const details = (error.details ?? {});
+    const finishedAt = Number(details.finishedAt);
+    const onlyCommitted = details.stage === 'committed' && details.result == null;
+    const previous = typeof details.operation === 'string' && details.operation ? details.operation : operation;
+    // 单命令写操作（没有 Prepare 可重跑，如 workflow.batchSubmit）不能沿用"不要重跑 Prepare"的措辞。
+    const hasPrepare = /Apply$/u.test(previous);
+    const retryHint = hasPrepare
+        ? '不要重跑 Prepare，也不要再次提交'
+        : '不要重复提交同一批 requestId';
+    return workflowSuccess(operation, {
+        status: 'ALREADY_APPLIED',
+        operation: previous,
+        requestId: typeof details.requestId === 'string' && details.requestId ? details.requestId : null,
+        confirmedAt: Number.isFinite(finishedAt) ? new Date(finishedAt).toISOString() : null,
+        previousResult: details.result ?? null,
+        note: onlyCommitted
+            ? '该 continuation 对应的上一次执行已经写入成功（服务端已返回成功回执，只是没来得及写回本地结果），'
+                + `本次未重复执行——${retryHint}；目标流程按上面的 requestId 查即可。`
+            : `该 continuation 已经执行过且已成功，本次未重复写入（幂等回报）——${retryHint}。`,
+    });
+}
+/**
+ * 名称→ID 澄清：查询参数里的名称**匹配不到**、或**匹配到多个且其中没有全名精确匹配**时，
+ * 不能把结果当成「查到了 0 条流程」——那是把「没听懂你的条件」伪装成「查无数据」。
+ *
+ * 底层解析函数（`read.ts`）无法直接产出信封，故以 `needs_clarification` 错误向上抛；在这一层
+ * 转成**成功信封**（`ok:true` + `status: NEEDS_CLARIFICATION`），把候选与澄清问题原样带回给模型。
+ *
+ * 形态对齐 V11.3：`e10_workflow.py:10356-10400` 与 `resolve_system_name_condition`（L8262）
+ * 都返回 `success:true` + `needClarification:true`（多命中时带 `candidates` +
+ * `clarificationType` + `clarificationKeyword`）。与 `workflow.createList` 已有的
+ * `ok:true` + `status:NEEDS_SELECTION` 是同一套约定。
+ *
+ * 注意：这是「本次查询**未执行**」的语义，不是「查询已执行且结果为空」——
+ * 文案必须让模型把候选原样摆给用户，而不是转述成「无匹配流程」。
+ */
+function clarificationEnvelope(error, operation) {
+    if (!(error instanceof WorkflowCliError) || error.subtype !== CLARIFICATION_SUBTYPE)
+        return null;
+    const details = (error.details ?? {});
+    const candidates = Array.isArray(details.candidates) ? details.candidates : [];
+    const question = typeof details.clarificationQuestion === 'string' && details.clarificationQuestion
+        ? details.clarificationQuestion
+        : error.message;
+    return workflowSuccess(operation, {
+        type: 'workflowClarification',
+        status: 'NEEDS_CLARIFICATION',
+        clarificationType: details.clarificationType ?? null,
+        clarificationKeyword: details.clarificationKeyword ?? null,
+        clarificationQuestion: question,
+        candidates,
+        candidateCount: candidates.length,
+        note: '这不是失败，也**不代表查询已执行**：本次查询已停止，没有返回任何流程数据。'
+            + '请把澄清问题与候选**原样**交给用户确认（逐条列出「名称(ID)」），'
+            + '拿到确认后用「名称(ID)」格式重发同一条命令。'
+            + '**不要**把本次结果转述成「没有匹配的流程」「查询结果为 0 条」或自行挑一个候选继续查。'
+            + (candidates.length === 0
+                ? '当前没有任何候选——请让用户给出准确的完整名称（或纠正名称里的错别字）后重发。'
+                : ''),
+    });
+}
+/**
+ * 写入成功后回写 continuation 的执行结果（best-effort），使重复执行能回报「上一次已成功」，
+ * 而不是一句无法分辨的「已使用」。
+ *
+ * 只覆盖**apply 自带 continuation 入参**的高风险写操作：表单系的 `xxxPrepare` 消费的是上一步
+ * （createForm／editLoad）签发的租约，不属于本操作自身的执行结果，不能在此回写。
+ */
+async function settleAppliedContinuation(input, result, context, definition) {
+    if (definition.risk !== 'high-risk-write')
+        return;
+    // 单条/批量/共享的句柄入参叫 `continuation`；发起（createApply）与修改（editApply）的句柄
+    // 从 createForm／editLoad 一路传下来，入参名是 `context`（同一个本机托管句柄）。
+    // 原先只认 `continuation` ⇒ 发起/修改成功后从不回写结果，重放只能报"已使用"，
+    // 模型被迫反查 OA 才能确认到底有没有发起（2026-09-16 线上）。
+    const raw = typeof input.continuation === 'string' ? input.continuation
+        : typeof input.context === 'string' ? input.context : '';
+    const reference = raw.trim();
+    if (!reference)
+        return;
+    await context.continuation.settle(reference, result.data, definition.action || definition.name);
+}
+export async function executeWorkflowOperation(operation, rawInput, context) {
+    const definition = getWorkflowOperation(operation);
+    const input = asObject(rawInput);
+    assertNoForbiddenKeys(input);
+    let result;
+    try {
+        result = await definition.handler(input, context);
+    }
+    catch (error) {
+        // 澄清要先于幂等回报判断：澄清是**本次查询的前提条件没满足**，与 continuation 无关。
+        const clarified = clarificationEnvelope(error, operation);
+        if (clarified)
+            return clarified;
+        const replayed = idempotentReplayEnvelope(error, operation);
+        if (replayed)
+            return replayed;
+        throw error;
+    }
+    await settleAppliedContinuation(input, result, context, definition);
+    return result;
+}

package/dist/shortcuts/workflow/state.js

@@ -0,0 +1,182 @@
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+function stateRoot(ctx) {
+    const configured = ctx?.config?.path();
+    if (configured)
+        return resolve(configured, '..');
+    return process.env.WEAVER_WORK_CLI_HOME
+        || process.env.WORK_CLI_HOME
+        || resolve(homedir(), '.weaver-work-cli');
+}
+/**
+ * 本地状态可写根目录列表（主目录 → 系统临时目录回退）。
+ *
+ * 沙箱/受限环境下主状态目录可能不可写。序号索引属于「查询后定位」的便利设施，
+ * **任何落盘失败都不得让读操作失败**；主目录不可写时退回临时目录，保证同一台机器上
+ * 后续 `--index` 定位仍可用。
+ */
+function stateRoots(ctx) {
+    const primary = stateRoot(ctx);
+    const fallback = resolve(tmpdir(), 'weaver-work-cli');
+    return primary === fallback ? [primary] : [primary, fallback];
+}
+function indexPath(root) {
+    return resolve(root, 'state', 'workflow', 'search-index.json');
+}
+export function workflowIndexFile(ctx) {
+    return indexPath(stateRoot(ctx));
+}
+/** 本地状态文件路径（主目录优先，调用方在写失败时自行回退）。 */
+export function workflowStateFile(name, ctx) {
+    return resolve(stateRoot(ctx), 'state', 'workflow', name);
+}
+export function workflowFallbackStateFile(name) {
+    return resolve(tmpdir(), 'weaver-work-cli', 'state', 'workflow', name);
+}
+/** 读取本地状态文件（主目录 → 回退目录），不存在或不可读返回 null。 */
+export async function readStateFile(name, ctx) {
+    for (const root of stateRoots(ctx)) {
+        const file = resolve(root, 'state', 'workflow', name);
+        if (!existsSync(file))
+            continue;
+        try {
+            return await readFile(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * 落盘单个状态文件：**直接覆盖写**。
+ *
+ * 与 V11.3 的 `save_session_maps` / `save_config` / `_save_runtime_file_cache` 一致
+ * （Python 侧 `Path.write_text` 直接覆盖目标文件）。
+ *
+ * 此前实现是「写固定名 `*.tmp` + `rename` 原子替换」，但在宿主沙箱里 `rename` 实测恒被拦
+ * （EPERM，且该标志是进程内记忆、CLI 每次命令都是新进程，于是每次落盘都要重试一次），
+ * 于是每次落盘都额外产生两次**删除**动作：`rename` 被宿主视作「删除目标文件」、失败路径里的
+ * `unlink(tmp)` 被视作「删除临时文件」。宿主因此弹出文件删除审批（审计日志里成对出现的
+ * `search-index.json` + `search-index.json.tmp` 即由此而来），并留下 `.tmp` 残留。
+ * 本文件只承载「查询后定位」的便利设施（见文件头注释），不值得为原子替换付出这类环境代价，
+ * 故对齐 V11.3 直接覆盖写，写路径**不产生任何删除动作**。
+ */
+async function writeStatePayload(file, payload) {
+    await writeFile(file, payload, { mode: 0o600 });
+    if (process.platform !== 'win32')
+        await chmod(file, 0o600).catch(() => undefined);
+}
+/**
+ * 尽力写入本地状态文件，返回实际写入路径；全部失败返回 null（调用方按"无落盘"降级）。
+ * 语义：本地状态是缓存/便利设施，写入失败绝不能向上抛错。
+ */
+export async function writeStateFileBestEffort(name, payload, ctx) {
+    const roots = stateRoots(ctx);
+    for (const root of roots) {
+        const file = resolve(root, 'state', 'workflow', name);
+        try {
+            await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+            await writeStatePayload(file, payload);
+            return file;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function emptyIndex() {
+    return { queryId: '', updatedAt: '', groups: {}, items: [] };
+}
+function asItems(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => Boolean(item) && typeof item === 'object');
+}
+function asGroups(value) {
+    const groups = {};
+    if (!value || typeof value !== 'object')
+        return groups;
+    for (const [kind, raw] of Object.entries(value)) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const record = raw;
+        groups[kind] = {
+            ...record,
+            kind,
+            items: asItems(record.items),
+        };
+    }
+    return groups;
+}
+export async function loadSearchIndex(ctx) {
+    for (const root of stateRoots(ctx)) {
+        const file = indexPath(root);
+        if (!existsSync(file))
+            continue;
+        try {
+            const parsed = JSON.parse(await readFile(file, 'utf8'));
+            return {
+                queryId: typeof parsed.queryId === 'string' ? parsed.queryId : '',
+                updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : '',
+                groups: asGroups(parsed.groups),
+                items: asItems(parsed.items),
+                ...(parsed.summary && typeof parsed.summary === 'object'
+                    ? { summary: parsed.summary }
+                    : {}),
+            };
+        }
+        catch {
+            continue;
+        }
+    }
+    return emptyIndex();
+}
+/**
+ * 落盘序号索引。**best-effort**：主状态目录不可写时回退临时目录，全部失败也不抛错
+ * ——索引只是"查询后按序号定位"的便利设施，不能让读操作本身失败
+ * （直接覆盖写，写路径零删除动作；受限环境下也不会因碰删除而被宿主拦下）。
+ */
+export async function saveSearchIndex(entry, ctx) {
+    const index = {
+        queryId: entry.queryId || newDateQueryId(),
+        updatedAt: new Date().toISOString(),
+        groups: asGroups(entry.groups),
+        items: asItems(entry.items),
+        ...(entry.summary && typeof entry.summary === 'object'
+            ? { summary: entry.summary }
+            : {}),
+    };
+    const payload = JSON.stringify(index, null, 2);
+    for (const root of stateRoots(ctx)) {
+        const file = indexPath(root);
+        try {
+            await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+            await writeStatePayload(file, payload);
+            return index;
+        }
+        catch {
+            continue;
+        }
+    }
+    return index;
+}
+function newDateQueryId() {
+    return new Date().toISOString();
+}
+/**
+ * 按 `--group` + `--index` 定位条目。
+ *
+ * - `group` 省略时在平铺条目里按序取第 `index` 条；
+ * - `group` 命中分组时在该分组条目里取第 `index` 条（1 基）。
+ * 返回 null 表示定位不到（调用方按"索引失效，需要重新查询"处理）。
+ */
+export function findIndexedItem(index, group, position) {
+    const list = group ? index.groups[group]?.items ?? [] : index.items;
+    if (!Number.isInteger(position) || position < 1 || position > list.length)
+        return null;
+    return list[position - 1] ?? null;
+}

package/docs/SKILL.md

@@ -8,7 +8,7 @@
 - `src/internal/e10`：E10 session、profile、auth 文件和 API client。
 - `src/shortcuts`：面向人和 Agent 的高层业务 CLI 能力，按业务模块分目录；模块内每个业务 operation 用相对独立的 class 封装。使用 Skill Maker 新增业务模块时，默认同步生成或更新对应 shortcut。
 - `skills`：随包发布的 Agent Skill，按业务模块分目录；每个模块对应一个独立 Skill，入口 `SKILL.md` 只做路由，具体操作细节放到 `references/`，公共约束通过 `weaver-e10-shared` 复用。
-- `skill-template`：新增或重写业务 Skill 的模板来源；结构参考飞书 CLI 的 `skill-template`，用于保持入口、路由关键词、业务域说明和 reference 拆分方式一致。
+- `skill-template`：新增或重写业务 Skill 的模板来源；结构参考飞书 CLI 的 `skill-template`，用于保持入口、路由关键词、业务域说明、产品元信息和 reference 拆分方式一致。
 
 使用内置 docs 命令可以把当前文档目录复制到业务工作区：
 
@@ -21,9 +21,9 @@ weaver-work-cli docs copy
 业务 Skill 目录约定：
 
 ```text
+skill-template/product.json  共享产品元信息模板；打包/安装时注入到每个 Skill 产物。
 skills/weaver-e10-<name>/
   SKILL.md                  入口路由：共享规则、schema、reference 索引、禁用边界。
-  product.json              可选：Skill 包元信息。
   references/               具体业务 reference，按用户意图和 operation 分文件。
 ```
 
@@ -35,6 +35,8 @@ skills/weaver-e10-<name>/
 - `fna`：E10 齐业成费控中心（预算查询/费用中心/借款管理/发票核销）。源码说明先读 `docs/fna.md`；面向 Agent 时先读 `skills/weaver-e10-qiyecheng/SKILL.md`，再按入口路由读取对应 reference。写操作（提醒还款/催票）走 prepare/apply 确认链。
 - `plan`：E10 计划报告（报告查询/新建/修改/发布/撤回/提交提醒/评论），自动适配标准版与 e10-ebuilder 两套报告接口链路。源码说明先读 `docs/plan.md`；面向 Agent 时先读 `skills/weaver-e10-plan/SKILL.md`，再按入口路由读取对应 reference。写操作走 prepare/apply 确认链。
 - `esb`：E10 ESB 中心自定义触发动作流（入参模板查询 + 触发）。源码说明先读 `docs/esb.md`；面向 Agent 时先读 `skills/weaver-e10-esb/SKILL.md`，再按入口路由读取对应 reference。触发动作流是写操作，走 prepare/apply 确认链。
-- `skill-maker`：把用户提供的新业务模块文档或代码转换成 `weaver-e10-*` Agent Skill，通过源资料指纹检测更新，用泛微技能检测工具做发布前静态质检，并在检测通过后询问是否安装到当前智能体。面向 Agent 时先读 `skills/weaver-e10-skill-maker/SKILL.md`。
+- `okr`：E10 OKR 目标管理（目标分页查询/详情、关键成果查询与保存、目标对齐、目标评论、详情页链接），按 `ver_name` 自动适配 e10 标准版与 e10-ebuilder 两套接口链路。源码说明先读 `docs/okr.md`；面向 Agent 时先读 `skills/weaver-e10-okr/SKILL.md`，再按入口路由读取对应 reference。写操作（新建/编辑目标、保存关键成果、添加目标对齐）走 prepare/apply 确认链。
+- `ebuilder-form`：E10 eBuilder 表单（菜单定位、List/NList 分页和配置、字段/选项/浏览字段解析、OpenAPI 与已发布自定义接口读写）。源码说明先读 `docs/ebuilder-form.md`；面向 Agent 时先读 `skills/weaver-e10-ebuilder-form/SKILL.md`，再按入口路由读取对应 reference。写操作走 prepare/apply 确认链。
+- `skill-maker`：把用户提供的新业务模块文档或代码转换成 `weaver-e10-*` Agent Skill，通过源资料指纹检测更新；每次创建或更新 Skill 后先询问是否现在进行 Skill 质检，用户确认后用泛微技能检测工具做发布前静态质检，并在检测通过后询问是否安装到当前智能体。面向 Agent 时先读 `skills/weaver-e10-skill-maker/SKILL.md`。
 
 Agent 调用业务能力时优先使用 `weaver-work-cli --json <command> run <operation> --input-json '<json>'`；复杂或多行 JSON 用 UTF-8 文件和 `--input <path>`，只有确认当前 shell 能稳定传管道时才使用 `--input -`。不要绕过 CLI 直接拼业务 HTTP。新增业务模块时，如果源资料不足以实现 CLI，先向用户列出缺口并确认，不生成假 operation。

package/docs/_catalog.md

@@ -13,7 +13,10 @@
 | 齐业成费控中心（预算/费用中心/借款管理/发票核销）、fna operation、提醒还款与催票 prepare/apply | `docs/fna.md` |
 | 文书定档案管理（全宗/检索/借阅车/借阅单/发起借阅/预归档上传）、wenshuding operation | `docs/wenshuding.md` |
 | 计划报告管理（报告查询/新建/修改/发布/撤回/提交提醒/评论）、plan operation、写操作 prepare/apply | `docs/plan.md` |
+| OKR 目标管理（目标查询/详情、关键成果、目标对齐、评论）、okr operation、标准版与 ebuilder 双链路、写操作 prepare/apply | `docs/okr.md` |
+| eBuilder 表单（菜单定位、List/NList、字段/浏览、OpenAPI 与自定义接口）、ebuilder-form operation、写操作 prepare/apply | `docs/ebuilder-form.md` |
 | E10 ESB 中心自定义触发动作流（入参模板查询 / prepare-apply 触发）、esb operation | `docs/esb.md` |
+| 事井然项目管理（项目/任务/字典/字段解析）、project operation、写操作 prepare/apply | `docs/project.md` |
 | 快速安装 CLI，并使用 CLI/Skill Maker 生成、验证、打包和安装业务模块 Skill | `docs/operation-manual.md` |
 | 把随包 Agent Skill 安装/升级到本机 Agent（Codex/WorkBuddy 目录、从本地仓库发布最新版） | `docs/agent-skill-install.md` |
 | Agent 调用业票通 CLI 的入口路由 | `skills/weaver-e10-yepiaotong/SKILL.md` |
@@ -26,11 +29,17 @@
 | Agent 调用齐业成费控 CLI 的具体 reference | `skills/weaver-e10-qiyecheng/references/` |
 | Agent 调用计划报告 CLI 的入口路由 | `skills/weaver-e10-plan/SKILL.md` |
 | Agent 调用计划报告 CLI 的具体 reference | `skills/weaver-e10-plan/references/` |
+| Agent 调用 OKR 目标管理 CLI 的入口路由 | `skills/weaver-e10-okr/SKILL.md` |
+| Agent 调用 OKR 目标管理 CLI 的具体 reference | `skills/weaver-e10-okr/references/` |
 | Agent 调用 ESB 动作流 CLI 的入口路由 | `skills/weaver-e10-esb/SKILL.md` |
 | Agent 调用 ESB 动作流 CLI 的具体 reference | `skills/weaver-e10-esb/references/` |
+| Agent 调用 eBuilder 表单 CLI 的入口路由 | `skills/weaver-e10-ebuilder-form/SKILL.md` |
+| Agent 调用 eBuilder 表单 CLI 的具体 reference | `skills/weaver-e10-ebuilder-form/references/` |
 | Agent 调用会议管理 CLI 的入口路由 | `skills/weaver-e10-meeting/SKILL.md` |
 | Agent 调用会议管理 CLI 的具体 reference | `skills/weaver-e10-meeting/references/` |
-| 易秒办即时通讯（消息/群组/会话/系统消息）、yimiaoban operation、写操作 prepare/apply | `docs/yimiaoban.md` |
+| 易秒办即时通讯（消息/群组/会话/系统消息）、im operation、写操作 prepare/apply | `docs/im.md` |
 | Agent 调用易秒办 CLI 的入口路由 | `skills/weaver-e10-yimiaoban/SKILL.md` |
 | Agent 调用易秒办 CLI 的具体 reference | `skills/weaver-e10-yimiaoban/references/` |
+| Agent 调用事井然项目管理 CLI 的入口路由 | `skills/weaver-e10-shijingran/SKILL.md` |
+| Agent 调用事井然项目管理 CLI 的具体 reference | `skills/weaver-e10-shijingran/references/` |
 | 将新业务模块文档或代码同步转换为 weaver-work-cli 业务 CLI 与 Skill、检测源资料更新 | `skills/weaver-e10-skill-maker/SKILL.md` |

package/docs/agent-invoice.md

@@ -55,7 +55,7 @@ weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"s
 
 1. 查询个人票夹和企业票夹，确认目标不存在。
 2. `invoice.ocr.preview` 预览文件识别结果，预览阶段固定不保存。
-3. 用户确认后执行 `invoice.import.prepare`，输入必须显式包含 `validate` 和 `syncToOa`；默认传 `validate=true`、`syncToOa=true`，表示导入时请求服务端查验并按服务端要求同步 OA。
+3. 用户确认后执行 `invoice.import.prepare`，输入必须显式包含 `validate` 和 `syncToOa`；默认传 `validate=true`、`syncToOa=true`，表示导入时请求服务端查验并按服务端要求同步 OA。使用 `filedMap` 时保持 JSON 对象输入，不要转成字符串。
 4. 把 prepare 返回的 `continuation` 原样交给 `invoice.import.apply`，并传 `confirm=true`。
 5. 使用返回的 `fid` 回查详情，按实际结果报告查验状态、写入状态和附件信息。
 
@@ -63,7 +63,7 @@ weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"s
 
 删除、编辑、新增同样必须使用 `prepare -> apply`。出现 `partial/write_uncertain` 时停止，不能自动重试写操作。
 
-处理“把发票填进流程表单”的场景，使用 `invoice.browse-field.data` 生成浏览按钮控件所需 JSON。处理“报销发票/自动填单”时，先读取 `invoice-reim.md`，用报销相关只读 operation 获取事前申请、工作流、表单结构、预填信息和人员上级；Agent 组装 payload 后，必须通过 `invoice.reim.flow.create.prepare/apply` 或 `invoice.reim.flow.update.prepare/apply` 写入。处理“开票/存台账”时，先读取 `invoice-issuing.md`，字段提取、税率确认和金额校验完成后，再走 `invoice.issuing.make.prepare/apply`。
+处理“把发票填进流程表单”的场景，使用 `invoice.browse-field.data` 生成浏览按钮控件所需 JSON。处理“报销发票/自动填单”时，先读取 `invoice-reim.md`，用报销相关只读 operation 获取事前申请、工作流、表单结构、预填信息和人员上级；Agent 组装报销单结构化 JSON 后，必须通过 `invoice.reim.flow.create.prepare/apply` 或 `invoice.reim.flow.update.prepare/apply` 写入，创建报销单的 `work_flow_id/mainFormId/request_name/main_fields/detail_rows` 等字段在 operation 顶层传入，不包通用 `payload`。处理“开票/存台账”时，先读取 `invoice-issuing.md` 和 `invoice-issuing-field-rules.md`，从用户输入或附件提取购方、税号、明细、税率和金额；资料不足时追问用户补齐，再走 `invoice.issuing.make.prepare/apply`。当前修正资料包没有客户档案查询或红字发票红冲接口，`invoice.customer.*` 和 `invoice.red.*` 不能调用或绕过。
 
 ## 暂缓能力
 

package/docs/agent-skill-install.md

@@ -115,7 +115,7 @@ weaver-work-cli skills install skill-maker --target-dir "$HOME/.workbuddy/skills
 2. **`skills install` 是拷贝语义**：装出的是真实副本，不与源目录联动。之后源里改动 Skill，已安装目录不会自动更新，需重跑安装；覆盖安装只写入与覆盖同名文件，**不会清理目标里已不存在的旧文件**，需要干净结果时先整目录移除再安装。
 3. **目标目录已有旧条目（旧副本或软链）时不能直接覆盖**：命令内部是递归拷贝，目标为软链时会报 `ERR_FS_CP_DIR_TO_NON_DIR` 失败；先移除该条目再安装（移除软链只断链，不影响其指向的目录）。
 4. **本机 CLI 若为 `npm link` 指向本地仓库**，`skills list/install` 反映的是仓库当前工作区内容，包含未提交改动——开发期可直接发布最新工作区。
-5. 拷贝会过滤 dotfiles、`scripts/`、`assets/`、`node_modules/`；`SKILL.md`、`references/`、`product.json` 会完整拷贝。
+5. 拷贝会过滤 dotfiles、`scripts/`、`assets/`、`node_modules/`；`SKILL.md`、`references/` 会完整拷贝，`product.json` 由 `skill-template/product.json` 和 `package.json` 注入到每个安装产物。
 
 ## 首次安装
 
@@ -195,7 +195,7 @@ diff -q skills/weaver-e10-shared/SKILL.md "$HOME/.workbuddy/skills/weaver-e10-sh
 
 安装本身不校验业务 API。要确认对 Agent 生效：
 
-- 目录结构正确：用户主目录下的 `.workbuddy/skills/weaver-e10-yepiaotong` 包含 `SKILL.md`、`product.json`、`references/`，且 `weaver-e10-shared` 包含 `SKILL.md`、`references/`。
+- 目录结构正确：用户主目录下的 `.workbuddy/skills/weaver-e10-yepiaotong` 包含 `SKILL.md`、安装生成的 `product.json`、`references/`，且 `weaver-e10-shared` 包含 `SKILL.md`、`references/`。
 - 内容一致：Windows 使用上述 `Get-FileHash`，macOS/Linux 使用上述 `diff -q`；或用 `weaver-work-cli skills read weaver-e10-yepiaotong` 与仓库内容比对。
 - **Agent 需重新加载**：新建会话或按 Agent 规则重载 Skill 后才读取新内容；已打开的会话不会热更新。
 - 业务可用性：安装后仍需完成 E10 登录（`weaver-work-cli auth login --base-url "<E10_BASE_URL>" --agent_type "<当前智能体名称>"`），并可按 `weaver-work-cli invoice schema` 验证 operation 契约。

package/docs/e10-auth.md

@@ -38,7 +38,9 @@ weaver-work-cli auth export-weaver-env
 环境变量推断当前宿主，最后回落为 `weaver-work-cli`。浏览器授权地址会同时携带
 `agent_type=<value>` 和 `from=<value>`，其中 `from` 用于 E10 授权确认页展示客户端名称。
 
-小 E 宿主环境中，`auth login` / `auth oidc` / `auth xiaoe` 会先尝试从 `XIAOE_*` 环境变量读取当前域名对应的统一登录凭证。域名匹配且凭证可用时，CLI 直接保存登录态，保存的 `agentType` 固定为 `Xiao.E`；未显式传域名时，会优先使用小 E 环境变量里的首个支持域名，其次才使用当前 profile 配置，仍没有支持域名时保留资料包默认域名 `https://www.e-cology.com.cn`。业务命令在未显式指定 `--auth` / `--profile` 时，也会自动优先尝试小 E 统一登录。小 E 凭证校验失败、当前域名不在支持范围内，或用户切换了访问域名时，会自动降级到原浏览器 OAuth2.0 登录。
+XiaoE 宿主环境中，`auth login` / `auth oidc` / `auth xiaoe` 会先尝试读取宿主 `xiaoeUserData/tokens.py`；脚本不可用（不存在、执行失败，或所用 Python 缺少 `requests` 等依赖）时，CLI 改用内置的原生等价实现读取 XiaoE 客户端本地会话（macOS `~/Library/Application Support/XiaoE/Robots/*/user_settings.json`，Windows `%LOCALAPPDATA%/XiaoE/Robots/*/user_settings.json`，或 `XIAOE_USER_TOKEN`）并换取 `eteamId`，该链路不依赖本机 Python 环境；仍没有可用凭证时，再从 `XIAOE_*` 环境变量读取当前域名对应的统一登录凭证。凭证可用时，CLI 直接保存登录态，保存的 `agentType` 固定为 `XiaoE`；凭证只返回 `eteamId` 时，会使用凭证中的域名或资料包默认域名 `https://www.e-cology.com.cn`；仍没有可用凭证时才考虑当前 profile 配置。业务命令在未显式指定 `--auth` / `--profile` 时，也会自动优先尝试 XiaoE 统一登录。XiaoE 凭证校验失败、当前域名不在支持范围内，或用户切换了访问域名时，`auth xiaoe` 会先反馈未拿到登录信息的原因，再自动降级到原浏览器 OAuth2.0 登录。
+
+脚本链路按 `python3`、`/usr/bin/python3`、`python` 顺序探测可用解释器；可用 `XIAOE_TOKEN_SCRIPT_PYTHON` 指定解释器，用 `XIAOE_TOKEN_SCRIPT_PATH` 指定脚本路径。
 
 无法使用浏览器回调时，可以用 `auth set` 直接写入浏览器中复制到的
 `ETEAMSID`。命令会调用 `teamsCheck` 解析当前用户、租户和组织信息，并写入

package/docs/ebuilder-form.md

@@ -0,0 +1,38 @@
+# eBuilder 表单 CLI
+
+`ebuilder-form` 将 eBuilder 菜单定位、List/NList 页面查询、字段/选项/浏览字段解析、OpenAPI 表单数据和已发布自定义接口统一成 `weaver-work-cli` shortcut。
+
+## 命令
+
+```text
+weaver-work-cli ebuilder-form --help
+weaver-work-cli ebuilder-form schema
+weaver-work-cli --json ebuilder-form run <operation> --input-json '<json>'
+```
+
+复杂 JSON 使用 UTF-8 文件和 `--input <path>`。Agent Skill 入口是 `skills/weaver-e10-ebuilder-form/SKILL.md`。
+
+## Operation 分组
+
+| 分组 | Operation |
+| --- | --- |
+| 上下文 | `ebuilder-form.menu.search`、`ebuilder-form.context.resolve`、`ebuilder-form.views.list` |
+| List/NList | `ebuilder-form.list.config`、`ebuilder-form.list.query`、`ebuilder-form.nlist.config`、`ebuilder-form.nlist.query` |
+| 字段与浏览 | `ebuilder-form.fields.get`、`ebuilder-form.options.get`、`ebuilder-form.mapping.get`、`ebuilder-form.browser.resolve` |
+| OpenAPI 只读 | `ebuilder-form.openapi.detail`、`ebuilder-form.openapi.query`、`ebuilder-form.openapi.count` |
+| OpenAPI 写入 | `ebuilder-form.openapi.add/update/delete.prepare` → `*.apply` |
+| 自定义接口 | `ebuilder-form.custom.detail/query/count`、`ebuilder-form.custom.add/update/delete.prepare` → `*.apply` |
+
+## 关键实现规则
+
+- `SEARCH` 菜单映射为 `List`，`VIEWPORT` 菜单映射为 `NList`。
+- `/api/ebuilder/form/**` 根据 `isIndependentDeploy(appId)` 路由到 `/api/ebuilder` 或 `/api/ebuilder{appId}`；`/api/ebuilder/common/**` 和浏览接口不拼 appId。
+- List 查询必须另调 `getListDataCount` 取真实总数。
+- NList 查询会把 `customConfig` JSON 编成 eBuilder 运行时要求的 LZW 数字串。
+- OpenAPI 写入默认 `fieldNoFindIgnore=false`、`checkRight=true`。
+- 自定义字段若字段定义中 `name == id`，写入键使用 `config.dataKey`。
+- 新增、修改、删除都是高风险写操作，必须走 continuation 绑定的 prepare/apply 确认链。
+
+## 不在范围
+
+本模块不创建菜单、不改页面配置、不调用 `/api/bs/`、不上传文件、不做 OCR、不读本地凭证目录，也不根据字段标题猜浏览接口。

package/docs/im.md

@@ -0,0 +1,104 @@
+# 易秒办即时通讯（im）
+
+`im` 是 E10 易秒办即时通讯的聚合命令，覆盖**消息（msg）**、**必达（ding）**、**群组（group）**、**会话（session）**、**系统消息（sysmsg）**，以及支撑能力人员解析（person）、文件上传/预览/下载（file）、用户状态与免打扰设置（user）、i18n 标签（i18n）。
+
+Skill 名与命令名不同：Skill 目录是 `skills/weaver-e10-yimiaoban`，CLI 命令后缀是 `im`（`weaver-work-cli im ...`）。
+
+```text
+weaver-work-cli im --help
+weaver-work-cli im schema
+weaver-work-cli --json im run <operation> --input-json '{"key":"value"}'
+```
+
+`schema` 是能力清单的唯一事实来源，包含每个 operation 的 `inputSchema`、`risk`、`requiresConfirmation` 和 `deprecatedInputAliases`。
+
+## 实现位置
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/shortcuts/im/index.ts` | 命令注册与 JSON envelope |
+| `src/shortcuts/im/manifest.ts` | `schema` 契约 |
+| `src/shortcuts/im/host.ts` | E10 会话桥接、认证头、executeIm/文件上传、hrm 人员解析、i18n、媒体 URL |
+| `src/shortcuts/im/continuation.ts` | 写操作确认链的 HMAC-SHA256 token |
+| `src/shortcuts/im/operations/` | 按业务域拆分的 operation 实现 |
+| `src/shortcuts/im/operations/registry.ts` | operation 注册表与去重校验 |
+| `skills/weaver-e10-yimiaoban/` | Agent Skill（入口 + 按能力拆分的 reference） |
+
+## 认证
+
+复用 `src/internal/e10` 的 E10 会话（`requireE10Session`），请求自动携带 `Cookie`、`eteamsid` 与 `X-Requested-With: XMLHttpRequest`。IM 接口前缀 `/api/em/msg/executeIm`，必达例外走 `/api/em/msg/createDing`。业务代码不接触认证目录，路径强制以 `/api/` 开头。
+
+## 红线（模块内强制）
+
+- 请求体禁止传操作人字段（`user`/`sender`/`creator`/`operator`），操作者由 `eteamsid` 识别。
+- 本人 IM 身份（`imCid`/`imUid`）只用于本机组装搜索条件、撤回/必达消息体、建群自检和「我」的判定（`teamsCheck` 解析，进程内缓存），**绝不入请求体**，也不接受调用方传入。
+- 人名一律走 hrm：`/api/hrm/common/getEmployeeByIds` 解析，禁止用 IM 群成员 `name` 字段展示姓名。
+- uid/cid/群 id 是 uint64，一律字符串传输且非 0。
+- 过滤全部服务端完成；有界区间自动翻页（最多 100 页），无界区间只拉一页。
+- 时间范围查询换算为消息 id 区间（`MakeMinAndMaxIdByTm`），跨度 > 7 天自动收敛为该范围最后 7 个自然日并在响应里给出提示。
+- 全空白文本不算内容（拒绝发送空白消息）；普通请求 15 秒超时即失败不重试（上传 15/60 秒）。
+- 媒体只给需登录态的 URL，真要看内容用 `im.file.download` 落地到本地（父目录须存在、拒绝覆盖）。
+- 消息内容完整透出，不截断；展示规则见 Skill `references/safety-boundaries.md`。
+
+## 消息拉取与展示
+
+`im.msg.sync.single`（对方 `fromUid`+`fromCid` 必填）、`im.msg.sync.group`（`groupId` 必填，type=0 固定）为倒序拉取：
+
+- 每页默认 50 条、上限 50；**有界区间**（`from`/`to`、缺省当天或显式 `end`/`endId`）自动循环翻页拉完再返回；**无界区间**（`latest:true`）只拉一页，用 `nextStart` 续拉。
+- `actionMsg.code=1303` 表示无聊天记录，按成功空列表处理，并返回 `empty:true` + `emptyReason`（区分当天无消息/时间范围无消息/会话无历史）。
+- 响应带 `pages`/`autoPaged`/`pageSize`/`exhausted`/`hasMore`/`nextStart`/`range`/`rangeShrink`；消息按消息 id 从新到旧排序。
+
+返回的 `messages[]` 已按 msgParser 语义解析为结构化行：
+
+- `msgid`；`sender`（自己显示「我」）；`time`；`typeName`；`content` 完整正文（@ 提及已还原、媒体显示 `[图片]名称`/`[视频]名称`/`[文件]名称`）；`must` 必达标记。
+- `fileName`：媒体消息原始文件名；`media`：图片/视频/文件的预览与下载 URL（需登录态）。
+
+## 系统消息
+
+`im.sysmsg.query` 与聊天消息同一分页口径；`start` 为排除边界（返回 id `< start`），返回 `dealMode` 表示该分组以处理状态（`已处理/未处理`）还是阅读状态（`已读/未读`）为准。分组/类型 id 来自 `im.sysmsg.groupSearch` / `im.sysmsg.typeSync`。
+
+## 写协议与 continuation
+
+所有写操作（send/withdraw/top.set/ding/group 系列）统一 `prepare → apply`：
+
+- `prepare`：只读校验（成员解析、源消息读取、接收人计算），返回 `summary` + `continuation`（HMAC-SHA256 签名，10 分钟有效，含 baseUrl/profile/userId 指纹与 snapshot 指纹）。
+- `apply`：必须 `confirm:true` + 有效 continuation；校验租户/账号一致（`context_mismatch`）与目标指纹（`target_changed`）；执行后不确定结果返回 `partial/write_uncertain`，禁止自动重试。
+
+会话提醒设置（`im.user.setRemind`，接口 `POST /api/em/msg/executeIm/user/setMsgRemind`）走同一确认链：`sessionType` 取 `1` 单聊会话（`toUid`+`toCid`）、`2` 群聊会话（`groupId`）、`4` 系统会话（`group`）；`reminder` 取 `0` 消息接收提醒 / `1` 消息接收但不提醒（免打扰）。操作者身份由 CLI 用当前登录人填充，调用方不能自带。
+
+## 分组速览（以 schema 为准）
+
+| 前缀 | 覆盖 |
+| --- | --- |
+| `im.person.*` | resolve / resolveByIds |
+| `im.msg.sync.*` / `im.msg.top.sync` / `im.msg.read.*` | 消息拉取/置顶/阅读状态 |
+| `im.msg.send.*` / `im.msg.withdraw` / `im.msg.top.set` | 发送/撤回/置顶（写，两段式） |
+| `im.ding.send.*` | 必达/转必达（写，两段式） |
+| `im.group.search/info/users/admins/exist/userExist/announce.*` | 群读 |
+| `im.group.create/invite/kick/exit/destroy/join/modify/rename/announce.modify` | 群写（两段式） |
+| `im.session.list` / `im.sysmsg.*` | 会话与系统消息 |
+| `im.file.upload/preview/download` / `im.user.state` / `im.user.setRemind` / `im.i18n.labels` | 文件/状态/免打扰/翻译 |
+
+## 平台示例
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json im run im.msg.sync.group --input-json '{"groupId":"1788334281700000004","num":50,"latest":true}'
+weaver-work-cli --json im run im.group.users --input-json '{"groupId":"1788334281700000004"}'
+weaver-work-cli --json im run im.session.list --input-json '{"num":20}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json im run im.msg.sync.group --input-json '{"groupId":"1788334281700000004","num":50,"latest":true}'
+weaver-work-cli --json im run im.group.users --input-json '{"groupId":"1788334281700000004"}'
+weaver-work-cli --json im run im.session.list --input-json '{"num":20}'
+```
+
+## 关联文档
+
+- Agent 路由入口：`skills/weaver-e10-yimiaoban/SKILL.md`
+- 条件化细节：`skills/weaver-e10-yimiaoban/references/`
+- 源资料清单与影响索引：`skills/weaver-e10-yimiaoban/references/source-manifest.json`

package/docs/invoice.md

@@ -55,7 +55,7 @@ weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"s
 | `invoice.upload` | 外部制品 | 固定上传 `ocr=0`，只取上传文件 ID，不做上传阶段解析 |
 | `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=true`、`syncToOa=true` |
+| `invoice.import.prepare/apply` | 高风险写 | continuation 绑定本地文件 SHA-256 或远程 URL；导入默认推荐 `validate=true`、`syncToOa=true`，`filedMap` 在 inputSchema 中保持 JSON object |
 | `invoice.add.prepare/apply` | 高风险写 | 单张票面校验、重复检查、确认后新增并回查 |
 | `invoice.update.prepare/apply` | 高风险写 | 基于完整详情修改白名单字段，保留附件并回查 |
 | `invoice.download` | 本地文件写 | 先校验 `fileId` 属于目标 `fid`，拒绝覆盖 |
@@ -68,8 +68,8 @@ weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"s
 | `invoice.reim.row-info` | 只读 | 使用 urlencoded 请求获取单张发票明细行预填信息 |
 | `invoice.reim.employee-superiors` | 只读 | 获取当前人员和上级信息 |
 | `invoice.reim.field.search` | 只读 | 搜索表单关联字段值，用于用户修正或出差客户确认 |
-| `invoice.reim.flow.create.prepare/apply` | 高风险写 | continuation 绑定已组装报销单 payload；确认后调用 `createFlowNew` |
-| `invoice.reim.flow.update.prepare/apply` | 高风险写 | continuation 绑定更新 payload；确认后调用 `updateFlow` |
+| `invoice.reim.flow.create.prepare/apply` | 高风险写 | continuation 绑定已组装报销单 JSON；`work_flow_id/mainFormId/request_name/main_fields/detail_rows` 等字段在 schema 顶层逐项暴露，确认后调用 `createFlowNew` |
+| `invoice.reim.flow.update.prepare/apply` | 高风险写 | continuation 绑定更新报销单 JSON；确认后调用 `updateFlow` |
 | `invoice.issuing.make.prepare/apply` | 高风险写 | 固定销方信息，确认后调用 `makeInvoice` 开票或存台账 |
 
 共享、转让和标签仍暂不暴露给 Agent：新版源资料给出了提交接口，但还缺少稳定的接收人 `appid/cid/uid` 解析来源、标签关系查询和写后回查契约。
@@ -118,9 +118,9 @@ weaver-work-cli --json invoice run invoice.reim.flow.create.prepare --input ./re
 weaver-work-cli --json invoice run invoice.issuing.make.prepare --input ./issuing.json
 ```
 
-导入本地发票文件时，面向 Agent 的正常链路是先 `invoice.ocr.preview`，再 `invoice.import.prepare` 使用 `validate=true`、`syncToOa=true`。只有用户明确要求跳过查验或离线导入时才传 `validate=false`；`validate=false` 表示跳过查验，不能描述为“查验通过”。
+导入发票文件或远程 URL 时，面向 Agent 的正常链路是先 `invoice.ocr.preview`，再 `invoice.import.prepare` 使用 `validate=true`、`syncToOa=true`。只有用户明确要求跳过查验或离线导入时才传 `validate=false`；`validate=false` 表示跳过查验，不能描述为“查验通过”。`filedMap`、嵌套字段映射等 JSON 参数在 `--input-json` 中保持对象，CLI 只在 multipart 提交前序列化。
 
-报销单创建和开票/存台账只接受 Agent 已组装好的 payload。CLI 不负责猜测事前申请匹配、出差客户或税率；这些规则在 Skill reference 中指导 Agent 组装和展示预览。写操作出现网络中断、部分成功、缺少回执 ID 或回查失败时，CLI 返回 `partial/write_uncertain`，Agent 禁止自动重复提交。
+报销单创建和开票/存台账只接受 Agent 已组装好的结构化 JSON。CLI 不负责猜测事前申请匹配、出差客户或税率；这些规则在 Skill reference 中指导 Agent 组装和展示预览。报销单创建的字段必须在 operation 顶层逐项传入，不再包一层通用 `payload`。当前修正资料包没有客户档案查询或红字发票红冲接口，`invoice.customer.*` 和 `invoice.red.*` 不暴露为 operation，Agent 不能绕过 CLI 调用原始接口。写操作出现网络中断、部分成功、缺少回执 ID 或回查失败时，CLI 返回 `partial/write_uncertain`，Agent 禁止自动重复提交。
 
 ## 编辑白名单