# 业务模块 Skill 生成流程 本流程用于把用户提供的新业务模块文档或代码转换成 `weaver-e10-*` Agent Skill，并同步生成或更新对应 `src/shortcuts/` CLI。目标是让其它 Agent 先读业务 Skill，再通过 `weaver-work-cli --json run --input-json ''` 或 `--input ` 调用真实 operation，而不是绕过 CLI 猜接口。 生成出的 docs、Skill reference、模板提示词和 CLI 示例必须同时兼容 Windows 和 macOS/Linux。凡涉及 JSON 输入、用户目录、路径分隔符、Python 启动器、文件删除、目录查看或文件比对，必须同时给出 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例；Agent 先根据当前系统和 shell 选择对应示例，不确定时用 `node -p "process.platform"` 判断。简单 JSON 优先生成 `--input-json ''` 示例；复杂 JSON 可保存为 UTF-8 文件后按平台传给 `--input`。Windows/PowerShell 示例不要使用 `printf`、`$HOME/...`、`~/...`、bash 反斜杠续行、`rm/ls/diff/python3` 等 Unix-only 写法。 ## 1. 明确输入和输出 开始前确认这些事，其中两个命名必须分别确认、可以不同： - **CLI 命令后缀 ``**：只用小写字母、数字和连字符，例如 `invoice`、`contract`、`expense-claim`。决定 `weaver-work-cli `、operation 前缀 `.` 和 `src/shortcuts/`。 - **Skill 后缀 ``**：同样只用小写字母、数字和连字符，但通常用业务系统名或拼音，例如 `yepiaotong`、`wenshuding`。决定 `skills/weaver-e10-` 目录名与 frontmatter `name`。 - 源资料：用户提供的文档、代码目录、接口说明、样例 JSON、已有 Skill 或需求说明。 - 输出位置：默认是当前仓库的 `skills/weaver-e10-`；如果用户指定外部 Agent skill 目录，以用户指定为准。 两个命名任一不清楚时都不要从文件夹名硬猜；候选名可以给出，但要等用户确认。尤其不要把 CLI 命令后缀直接当成 Skill 后缀：例如发票模块 CLI 命令是 `invoice`、Skill 名是 `yepiaotong`，目录应是 `weaver-e10-yepiaotong` 而不是 `weaver-e10-invoice`。不要因为当前没有 `weaver-work-cli ` 命令就追问是否补 CLI；CLI 同步生成/更新是默认范围。只有源资料缺少实现 CLI 所需的接口路径、请求方式、关键字段、认证边界、幂等/回查或写入确认信息时，才停下来向用户确认缺口。停下前必须已经读取用户提供的相关源资料和仓库内现有 reference；最终回复必须列出具体缺口和一个明确问题，不能只说“需要确认细节”。 当用户要求“根据源码仓库提交记录更新业务模块 Skill/CLI”时，把 Git 范围视为源资料的一部分。开始差异分析前，主动确认以下信息；用户没有提供时先提问，不能用网页 URL、目录名或最近提交自行补齐： - **源码仓库本地路径**：本地 clone 下来的仓库根目录，例如 `<本地仓库根目录>`（如 Windows 的 `C:\work\weaver-interface`、macOS/Linux 的 `~/work/weaver-interface`）。线上 GitLab/GitHub URL 只能作为来源说明；除非用户明确允许 clone/fetch 并提供访问能力，否则不要把远程 URL 当作可直接执行的仓库路径。 - **仓库下模块资料相对路径**：相对于仓库根目录的路径，例如 `backend/business-apis/inc/weaver-e10-yepiaotong`。如果用户给的是完整浏览器地址，去掉 `/-/tree//` 之前的部分并向用户确认相对路径。 - **旧版本 ref** 与 **新版本 ref**：可以是完整 commit SHA、唯一短 SHA、tag 或 branch/ref。多次提交通常只需要最开始旧 ref 和最后新 ref；中间 ref 只作为阶段说明或需求来源记录。 - **关联公共路径**：可选。若业务模块依赖共享 DTO、路由注册、公共枚举、鉴权或全局配置，让用户补充这些仓库相对路径；没有提供时先用模块路径过滤，并在影响报告中说明可能漏掉公共依赖。 - **参考内容**：可选。用户对需求单、截图、接口说明、历史 Skill、人工总结或特殊业务语义的补充；这些内容用于解释 diff，不能替代 Git ref 事实。 - **特殊要求**：可选。包括不要改某些 operation、兼容旧字段、按需求号分阶段输出、只生成报告不 apply、检测工具路径或额外测试命令等。 缺少源码仓库本地路径、模块相对路径、旧版本 ref、新版本 ref、CLI 命令后缀或 Skill 后缀时，不要进入写入阶段；先一次性向用户索取缺失项。目标产物路径通常可按 `` / `` 在当前 `weaver-work-cli` 仓库中推断，不必要求用户提供全路径。 ## 2. 盘点源资料 只读取用户明确提供或与模块直接相关的资料。对每个源文件记录： - `path` - `size` - `sha256` - 可选的 `role`：`api-doc`、`code`、`sample`、`existing-skill`、`requirement` 用户本轮明确提供为输入的业务文档、代码目录、接口说明和样例，可以直接读取用于转换；转换阶段必须阅读与业务模块相关的正文并抽取可执行契约，不能只拿文件名或摘要生成能力。读取后不要复制整份源文档、无关叙述或敏感内容，但必须把稳定规则、字段、约束和流程细节保真迁移到生成产物。源资料是附件、图片、远程 URL、二进制文件，或需要上传到外部解析/OCR 服务时，先按 shared 规则提示风险并等待用户确认。仅拿文件路径做 manifest 指纹只适用于“更新检测预检”或“用户只要求建基线”的场景，不能作为首次转换的业务依据。 如果源资料中存在机器可读契约，例如 `business-module.json`、OpenAPI/JSON Schema、导出的 operation manifest、接口路由表或字段枚举表，优先把这些契约作为 WHAT 的权威来源；源码 diff、需求说明和截图用于解释 WHY 与 WHEN。契约与源码实现冲突时，在影响报告中列为阻断或待确认项，不要让 Agent 从源码自由猜测字段语义。 如果源资料有稳定锚点，还要写入 `sourceChunks` 和 `operationImpact`：用 operation 名、HTTP 方法加路径、Markdown 标题或导出的 operation class 作为 chunk id，并把 chunk 映射到可能受影响的 CLI operation、schema 字段、reference、测试和风险确认链。不要用行号、段落顺序或模型摘要当 chunk id。源资料无法稳定切块时，只保留文件级指纹，并在 manifest 标记弱检测。 同时写入或更新 `sourceCoverage`：逐个源文件记录 `converted`、`withheld`、`external-only`、`not-applicable` 或 `needs-confirmation` 状态，以及对应 operation/reference/原因。任何 `api-doc`、`existing-skill` 或 `code` 源文件如果没有映射到 `sourceChunks` 或 `sourceCoverage`，都必须在最终回复中说明原因并视为待确认风险。 还要为每个 operation 写入或更新参数覆盖矩阵，至少记录在 `source-manifest.json` 的 `operationImpact[operation].parameterCoverage` 或等价结构中。矩阵必须以源资料参数为起点，逐项记录参数名、源位置、类型/必填/枚举/默认值等已知事实、落到的 `inputSchema` 字段，以及状态： - `converted`：已进入 `inputSchema`，并由 handler/host 使用。 - `fixed`：源接口要求但不暴露给 Agent 的固定参数，写入 manifest 的 `fixed` 或 handler 常量。 - `derived`：由 CLI 内部查询、解析或 continuation 绑定得到，例如名称转 ID、当前用户、prepare 输出。 - `deprecatedAlias`：兼容旧字段，写入 `deprecatedInputAliases` 并测试冲突规则。 - `withheld`：源资料有该参数或能力，但当前 CLI 不支持，写清原因。 - `needs-confirmation`：源资料只出现字段名或片段，缺少类型、是否必填、来源、枚举、权限、回查或绑定规则，等待用户补充。 - `not-applicable`：接口内部字段或展示字段，不应暴露为 Agent 入参；返回字段不得仅标为 not-applicable，必须继续纳入 `outputSchema` 或输出覆盖矩阵。 还要为每个 operation 写入或更新输出覆盖矩阵，至少记录在 `source-manifest.json` 的 `operationImpact[operation].outputFields` / `outputSchemaCoverage` 或等价结构中。矩阵必须以源资料响应字段表、返回示例或代码中的稳定返回对象为起点，逐项记录返回字段名、源位置、类型、必填或可选、数组元素、嵌套对象、枚举/状态码和落到的 `outputSchema` 路径。源资料缺少响应字段表但有响应示例时，可以从示例抽取稳定字段并标注来源；源资料完全缺少响应事实时，登记 `missingOutputSchema` 或 `needs-confirmation`，不能用通用 `object`、`raw` 或 `result` 代替逐字段转换。 入参 example 采用分级规则，不能因源资料没有 example 就阻断整个生成： - 源资料已有请求样例、历史 Skill 样例或可运行脚本入参时，必须原样抽取业务含义并写入 manifest 的 `inputExamples`（或等价字段），标明 `source`；未迁移视为生成失败。 - 源资料没有 example，但字段表、必填、枚举和默认值足够完整时，可以生成 `source: "synthetic"` 的推导样例，必须只用明显假值或占位值，并标明“由 schema 推导，需业务复核”。 - 源资料没有 example 且参数事实不完整时，不得编造样例；在 manifest/source-manifest 中记录 `missingExamples`，并在最终回复列出需要用户后续补充的 operation 和缺少事实。 - 测试应失败的情况是：源资料有 example 但 manifest 缺失、example JSON 不可解析、example 字段不在 schema 中、最小 example 缺少 required 字段，或 reference 命令示例与 manifest/schema 不一致。仅“源资料未提供 example”只能作为 WARN/needs-confirmation。 ## 3. 抽取业务语义 从源资料中提炼这些稳定信息： - 业务对象和高优先级触发词。 - operation 清单、命令名、输入字段、输出字段、分页字段和风险等级。 - 写入、删除、导入、更新等高风险操作的确认链；能做 `prepare -> apply` 的必须写清。 - 文件上传、OCR、导入、下载、远程 URL 读取等数据处理风险。 - 已知禁用能力：文档中存在但 CLI 未暴露、缺少稳定 ID、缺少回查或风险不可自动化的能力。 - 认证边界：业务 Skill 只调用 CLI，不复制 Cookie、ETEAMSID、Token 或内部登录逻辑。 ### 业务语义保真清单 不要把多份源 MD 压缩成一个“能力概述”。对每个业务对象或 operation，至少检查并迁移以下可执行细节： - 字段表：字段名、类型、必填、默认值、枚举/状态、单位、时间格式、ID 精度、别名、互斥/二选一/至少一个、固定参数和废弃字段兼容策略。 - 请求与响应：接口路径、请求方法、query/body/form/file 位置、分页/排序/筛选口径、返回结构、返回字段名/类型/必填/数组元素/嵌套对象、成功判定、错误码、空结果语义和大结果展示规则。 - 业务流程：前置查询、版本门禁、权限/scope、对象状态流转、跨链路差异、ID/名称解析、缓存或字典依赖、写前回查、写后回查和不确定结果处理。 - 示例与边界：源资料已有入参 example 时必须迁移到 manifest 和 reference；源资料没有 example 时按参数完整度生成 `synthetic` 样例或登记 `missingExamples`，并在最终报告中列出待补充项；如果源资料区分成功、失败、不同链路或不同对象类型，要分别保留能影响执行的差异。 - 禁用与缺口：源资料出现但未生成 CLI operation 的能力，必须进入 schema 的 withheld/disabled 信息或 reference 的禁用边界，并写清缺少的事实和为什么阻断。 迁移方式要按所有权落点分配：`manifest.ts` / `schema` 承载 WHAT，handler 和 host 承载请求形状与校验，`references/` 承载条件化 HOW，测试承载关键语义回归。不能只把细节写在自然语言里，也不能只在代码里实现而不让 Skill/reference 指到对应用法。若源资料给出 JSON 请求体字段表，`inputSchema.properties` 必须逐项暴露这些业务字段；不能把整段请求体塌缩成 `payload`/`body`/`requestPayload` 一个 object 后宣称已转换。若源资料给出响应字段表或返回示例，`outputSchema.properties` 必须按 CLI 成功 envelope 的 `data` 结构逐项暴露稳定返回字段；不能只把整段响应塌缩成 `result`/`data`/`raw` 一个 object 后宣称已转换。 如果源资料描述的是底层接口，但仓库还没有对应 operation，按 [`module-cli-generation.md`](module-cli-generation.md) 先实现 CLI，再让 Skill 调用该 operation。确实缺少实现依据时，把缺口列入待确认清单并问用户，不能生成假 operation；缺口只阻断对应 operation，已确认的能力继续生成 CLI、测试、docs 和 Skill reference。 ## 4. 同步实现 CLI 生成 Skill 前先读取 [`module-cli-generation.md`](module-cli-generation.md)，用飞书 CLI 的 contract-first 思路完成对应业务 shortcut：先定正确实现面，再实现 operation、schema、测试和文档。实现后确认 CLI 暴露的真实能力： ```text weaver-work-cli MODULE_COMMAND --help weaver-work-cli MODULE_COMMAND schema weaver-work-cli skills list ``` Skill 必须以 `schema` 为准；源文档和 schema 冲突时，先修正 CLI 或记录冲突并向用户确认。新增或更新 operation 后，Skill 里的命令统一写成： Windows PowerShell： ```powershell weaver-work-cli --json MODULE_COMMAND run MODULE_NAME.operation --input-json '{"key":"value"}' ``` macOS/Linux（bash/zsh）： ```bash weaver-work-cli --json MODULE_COMMAND run MODULE_NAME.operation --input-json '{"key":"value"}' ``` 不要在 Skill 中要求 Agent 直接 `curl`、`fetch`、浏览器自动化或拼 E10 原始接口。 ## 5. 生成 artifact 按 `weaver-skill-style.md` 生成： - 入口 `SKILL.md`：只放共享前置、路由优先级、operation 表、处理链、执行原则和不在范围。 - `references/`：每类意图或每个 operation 一个 reference，写具体输入、命令示例、输出摘要、注意事项和失败处理。 - `skill-template/product.json`：统一声明 `weaver-work-cli` 运行时；打包或安装时为每个 Skill 产物注入 `product.json`。 - `references/source-manifest.json`：记录源资料指纹、可选的 `sourceChunks` / `operationImpact` 和生成产物基线，用于后续更新检测。 - `src/shortcuts/`：注册命令、schema/run、operation manifest、执行逻辑、错误 envelope 和测试。 - `skill-template/business-info.json` 与 `skill-template/domains/.md`：让聚合模板知道如何路由。 - Skill 质检确认与泛微技能检测结果：每次创建或更新 Skill 后，先按 `detector-validation.md` 询问用户是否现在进行 Skill 质检；用户同意后运行检测，确保生成出的 Skill 至少无 BLOCK/FAIL 项。未得到确认、未运行检测或检测失败时，只能报告待质检状态，不能安装、发布或宣布完成。 - 安装确认：检测通过后按 `post-generation-install.md` 询问用户是否安装，确认后再打包并安装到当前智能体。 写 reference 时保留执行所需的全部事实和约束，不复制整份接口手册里的无关叙述。复杂字段优先使用 manifest 中的 `inputExamples` 展示小而完整的 JSON 示例；没有源 example 时，reference 必须说明该示例是 `synthetic` 或该 operation 缺少样例，不能伪装成源资料事实。字段表、枚举、流程分支、错误处理和禁用边界过长时，按 operation、业务对象或源文档标题拆成多个 reference，而不是删减成摘要。reference 应做到：对已生成的 operation，Agent 只依赖当前 Skill 包和 `weaver-work-cli schema` 就能正确执行，不需要再回源资料包补读业务规则。 ## 6. 验证 在仓库内生成时至少运行： Windows PowerShell： ```powershell weaver-work-cli skills list weaver-work-cli skills read weaver-e10-MODULE_NAME weaver-work-cli MODULE_NAME schema npm test -- test/skills/layout.test.ts npm test -- "test/business/MODULE_NAME-*.test.ts" weaver-work-cli skills validate skills\weaver-e10-MODULE_NAME --json --no-html ``` macOS/Linux（bash/zsh）： ```bash weaver-work-cli skills list weaver-work-cli skills read weaver-e10-MODULE_NAME weaver-work-cli MODULE_NAME schema npm test -- test/skills/layout.test.ts npm test -- "test/business/MODULE_NAME-*.test.ts" weaver-work-cli skills validate skills/weaver-e10-MODULE_NAME --json --no-html ``` 如果新增或修改了 TypeScript CLI 代码，再运行构建和相关业务测试。运行泛微技能检测工具前必须先询问用户是否现在进行 Skill 质检；用户同意后再执行 detector 命令。若验证失败，优先修正 CLI 合约、artifact 结构、frontmatter、reference 链接和 business-info 对齐问题。检测通过后，进入安装确认流程；用户未确认前不要安装。