# 源资料更新检测 生成业务模块 Skill 和对应 CLI 时必须写入 `references/source-manifest.json`。后续用户提供更新后的业务模块文档或代码时，先比较 manifest 与当前源资料，再提示用户确认是否转换；用户确认后，同步更新 CLI 与 Skill。 更新检测采用多层基线： - **文件级基线**：必须记录源资料 `path + size + sha256` 和 `aggregateSha256`，用于快速判断是否有新增、删除或整体变更。 - **operation 影响索引**：当源资料可稳定切块时，额外记录 `sourceChunks` 与 `operationImpact`，用于把小范围更新定位到可能受影响的 operation、reference、schema 字段、测试和风险确认链。 - **源资料覆盖记录**：记录每个源文件被转换、暂缓、仅外部留存、无需处理或待确认的状态，防止多份 MD 在生成时被压缩成无法追溯的概述。 - **Git ref 范围**：当用户提供本地源码仓库、模块相对路径、旧版本 ref 和新版本 ref 时，用仓库提交记录定位业务源资料变化；Git 范围只能作为事实来源和影响分析输入，不能跳过用户确认直接覆盖产物。 文件级基线是事实判断；operation 影响索引只用于路由和影响提示。即使只命中某一个 operation，也必须阅读变化内容并完成验证，不能直接自动覆盖产物。 ## Manifest 结构 ```json { "schemaVersion": 2, "module": "", "skill": "weaver-e10-", "generatedAt": "2026-09-03T00:00:00.000Z", "sourceSet": { "aggregateSha256": "", "sourceRoots": [""], "detectionStrength": "strong", "git": { "repository": "", "modulePaths": [""], "sharedPaths": [""], "baseRef": "", "headRef": "", "baseCommit": "", "headCommit": "", "comparedAt": "2026-09-03T00:00:00.000Z" } }, "generatedTargets": { "cli": ["src/shortcuts/", "src/shortcuts/index.ts"], "skill": ["skills/weaver-e10-"], "tests": ["test/business/-*.test.ts"], "docs": ["docs/.md", "skill-template/domains/.md"] }, "sources": [ { "path": "", "role": "api-doc", "size": 1234, "sha256": "" } ], "sourceChunks": [ { "id": "", "sourcePath": "", "anchor": "", "sha256": "", "mapsToOperations": ["."], "mapsToReferences": ["references/.md"] } ], "operationImpact": { ".": { "sourceChunkIds": [""], "schemaFields": [""], "references": ["references/.md"], "tests": ["test/business/-*.test.ts"], "risk": "read | write-confirmed | external-read | read-with-upload", "requiresConfirmationChain": false } }, "sourceCoverage": [ { "sourcePath": "", "status": "converted | withheld | external-only | not-applicable | needs-confirmation", "operations": ["."], "references": ["references/.md"], "reason": "" } ], "artifactBaseline": { "aggregateSha256": "", "files": [ { "path": "skills/weaver-e10-/references/.md", "role": "generated-reference", "size": 1234, "sha256": "" } ] }, "notes": [ "只记录源资料指纹和转换摘要，不保存 Cookie、Token 或大段源正文。" ] } ``` `sourceSet.aggregateSha256` 按源资料 `path + size + sha256` 排序后的稳定 JSON 计算。`artifactBaseline.aggregateSha256` 按生成产物 `path + size + sha256` 排序后的稳定 JSON 计算，只用于判断现有产物是否被手工改动，不替代源资料基线。路径可记录为用户提供的相对路径或明确 URL；本地绝对路径可能暴露用户名时，优先记录相对工作区路径。 不要在 manifest 中写入个人主目录绝对路径、认证路径、Cookie、Token 或大段源正文；这些内容会被泛微技能检测工具视为发布风险。 `sourceCoverage` 是防退化记录，不要求复制源正文。状态含义： - `converted`：源文件中的可执行契约已落到 CLI operation、schema、reference 和测试。 - `withheld`：源文件描述的能力暂不暴露，已写入禁用边界或 withheld operation，并说明缺少的事实。 - `external-only`：源文件只作为外部大手册或长期参考留存，不参与当前已生成能力；必须说明为什么不影响当前 operation。 - `not-applicable`：图标、打包元数据、旧认证脚本等非业务能力材料。 - `needs-confirmation`：源文件含业务事实但存在冲突、缺口或风险，需要用户补充后再转换。 `schemaVersion: 1` 的旧 manifest 仍可读取，但只能视为文件级或弱检测基线。下次用户确认更新时，应迁移到 `schemaVersion: 2`，并尽量补齐 `sourceChunks`、`operationImpact`、`sourceCoverage` 和 `artifactBaseline`。 ## Chunk 与影响索引 ### 登录与凭证契约（生成产物必须遵循） 生成的 E10 业务 Skill 必须遵守登录与凭证红线： - 登录与会话统一由 `weaver-e10-shared` 共享规则和 `weaver-work-cli auth ...` 命令体系托管，业务 Skill 不得自行实现任何登录流程。 - 生成的 SKILL.md frontmatter 必须声明 `dependencies:\n - weaver-e10-shared`。 - 每个请求的请求头三件套（Cookie 完整原始串 / `eteamsid` / `User-Agent`）由 `weaver-work-cli` 统一注入，业务侧不得手工拼装或覆盖；唯一权威声明见 [`../../weaver-e10-shared/SKILL.md`](../../weaver-e10-shared/SKILL.md) 的「请求头契约」章节。 - Skill 与 reference 文档中若描述了接口请求，只需一行指针引用 `weaver-e10-shared` 的「请求头契约」，不要复制完整代码块。 只有源资料存在稳定锚点时才写 `sourceChunks`。可用锚点包括： - CLI operation 名，如 `invoice.update.prepare`。 - HTTP 方法加路径，如 `POST /api/inc/update`。 - Markdown 标题或 reference 主题，如 `# 编辑发票`。 - TypeScript 导出的 operation class、manifest entry 或测试用例名。 不要用行号、自动编号、段落顺序或模型摘要当 chunk id。chunk id 应该能跨小幅排版调整保持稳定。 `operationImpact` 记录“可能影响”，不是自动改写授权。每个 operation 尽量记录： - `sourceChunkIds`：来自哪些源资料块。 - `schemaFields`：可能影响的输入字段、默认值、枚举或固定参数。 - `references`：对应 Skill reference。 - `tests`：至少应检查的测试文件。 - `risk`：风险等级或写入确认类别。 - `requiresConfirmationChain`：是否必须检查 `prepare -> apply`。 如果源资料格式混乱、只有远程弱版本号、或无法稳定切块，允许只写文件级基线，并把 `sourceSet.detectionStrength` 设为 `weak`，在 `notes` 写明限制。 即使无法稳定切块，也要尽量写 `sourceCoverage`。如果某个业务源文件只能记录文件级指纹而没有 coverage，最终回复必须提示“存在未覆盖源资料”，并在转换前向用户确认是否继续。 ## Git ref 范围更新 当用户希望根据 Git 修改记录更新已有业务模块时，开始分析前必须确认： - 源码仓库本地路径：本地 clone 下来的完整仓库根目录，不是 GitLab/GitHub 网页地址。 - 仓库下模块资料相对路径：相对于仓库根目录的路径，例如 `backend/business-apis/inc/weaver-e10-yepiaotong`。 - 旧版本 ref：基础版本 commit、tag 或分支。 - 新版本 ref：更新后 commit、tag 或分支。 - 目标 CLI 命令后缀与目标 Skill 后缀。 - 参考内容、关联公共路径和特殊要求；这些可以为空，但要给用户一次补充机会。 如果用户只提供了浏览器地址，例如 `.../-/tree/master/backend/business-apis/inc/weaver-e10-yepiaotong`，只能提取候选相对路径 `backend/business-apis/inc/weaver-e10-yepiaotong`，并向用户确认本地仓库路径。没有本地仓库时，询问用户提供 clone 后路径，或明确授权 clone/fetch；不要自行联网拉取。 多次提交通常只需要“最开始的旧 ref”和“最后更新后的新 ref”。中间 ref 只在用户要求按需求阶段拆解、存在回滚/重做/冲突修正，或最终 diff 无法解释业务语义时作为辅助输入。分析时仍以 `baseRef..headRef` 的最终树差异为准，并用 `git log` 保留中间提交摘要。 必须先验证仓库、路径和 ref： Windows PowerShell： ```powershell git -C SOURCE_REPO rev-parse --show-toplevel git -C SOURCE_REPO rev-parse "OLD_REF^{commit}" git -C SOURCE_REPO rev-parse "NEW_REF^{commit}" git -C SOURCE_REPO ls-tree -d NEW_REF -- MODULE_RELATIVE_PATH ``` macOS/Linux（bash/zsh）： ```bash git -C SOURCE_REPO rev-parse --show-toplevel git -C SOURCE_REPO rev-parse OLD_REF^{commit} git -C SOURCE_REPO rev-parse NEW_REF^{commit} git -C SOURCE_REPO ls-tree -d NEW_REF -- MODULE_RELATIVE_PATH ``` `OLD_REF..NEW_REF` 范围中夹杂其它模块提交不会直接污染结果，前提是所有 diff/log 命令都带路径过滤： Windows PowerShell： ```powershell git -C SOURCE_REPO diff --name-status OLD_REF..NEW_REF -- MODULE_RELATIVE_PATH git -C SOURCE_REPO diff --stat OLD_REF..NEW_REF -- MODULE_RELATIVE_PATH git -C SOURCE_REPO log --oneline --decorate OLD_REF..NEW_REF -- MODULE_RELATIVE_PATH git -C SOURCE_REPO diff OLD_REF..NEW_REF -- MODULE_RELATIVE_PATH ``` macOS/Linux（bash/zsh）： ```bash git -C SOURCE_REPO diff --name-status OLD_REF..NEW_REF -- MODULE_RELATIVE_PATH git -C SOURCE_REPO diff --stat OLD_REF..NEW_REF -- MODULE_RELATIVE_PATH git -C SOURCE_REPO log --oneline --decorate OLD_REF..NEW_REF -- MODULE_RELATIVE_PATH git -C SOURCE_REPO diff OLD_REF..NEW_REF -- MODULE_RELATIVE_PATH ``` 如果用户提供了关联公共路径，把模块路径和公共路径一起传给 `--` 后面。若未提供公共路径，先额外查看一次全局变更摘要，只用于发现明显共享依赖，不直接纳入自动更新： Windows PowerShell： ```powershell git -C SOURCE_REPO diff --name-status OLD_REF..NEW_REF ``` macOS/Linux（bash/zsh）： ```bash git -C SOURCE_REPO diff --name-status OLD_REF..NEW_REF ``` 看到共享 DTO、公共枚举、鉴权、路由注册或全局配置等可能影响业务模块的文件时，先在影响报告中列为“待确认公共依赖”，询问是否纳入源资料；不要静默忽略，也不要无边界地读取整个系统。 Git 差异分析的产物必须先是影响报告，不是直接改文件。影响报告至少包含： - 输入边界：源码仓库本地路径、模块相对路径、关联公共路径、旧版本 ref、新版本 ref，以及解析后的完整 commit SHA。 - 提交摘要：路径过滤后的 `git log` 结果；如全局摘要显示疑似公共依赖，也列出文件路径。 - 文件变化：新增、删除、重命名、修改的文件数量和关键路径。 - 业务变化推断：新增/删除/变化的接口、字段、枚举、默认值、固定参数、流程、权限或确认链。 - 影响面：可能要更新的 CLI operation、`manifest.ts` schema 字段、handler、reference、测试、docs、`business-info`、domain 文件和 `source-manifest.json`。 - 风险分级：`patch`、`minor`、`major`。字段删除、必填项变化、语义变化、写操作确认链变化、权限变化或返回结构破坏性变化必须标为 `major`。 - 明确问题：是否把这些变化同步转换进目标 CLI 与目标 Skill；`major` 项必须逐项确认迁移或兼容策略。 用户确认前，不要覆盖 `src/shortcuts/`、`skills/weaver-e10-`、docs、template、测试或 manifest。用户只要求“分析方案”或“生成报告”时，到影响报告为止。 ## 首次生成 首次生成目标 CLI 与 Skill 时： 1. 盘点用户提供的源资料。 2. 计算每个源文件 sha256。 3. 生成 `source-manifest.json`。 4. 在最终回复中说明已记录源资料指纹，后续可用来检测更新。 如果用户提供的是远程文档但当前 Agent 无法稳定读取版本号或内容 hash，必须在 manifest `notes` 里写明限制，并在后续更新检测时提醒“只能做弱检测”。 ## 已有 CLI/Skill 的更新检测 目标 CLI 或 Skill 已存在时，先读取： - `skills/weaver-e10-/references/source-manifest.json` - 当前用户提供的源资料 然后比较： - 新增源文件 - 删除源文件 - sha256 变化的源文件 - 新增、删除或 sha256 变化的 `sourceChunks` - `operationImpact` 映射是否缺失、过期或与 schema/reference 不一致 - `sourceCoverage` 是否有 `needs-confirmation`、业务源文件缺失覆盖，或已转换源文件不再映射到真实 operation/reference - role 或 sourceRoots 变化 - manifest 缺失或 schemaVersion 不认识 比较结果为空时，不要重写 Skill；告诉用户“源资料未变化，不需要重新转换”，除非用户明确要求强制重生成。 比较结果非空时，必须先暂停并向用户确认。回复要包含： - 变更摘要：新增、删除、变化的文件数量和关键路径。 - 小范围定位：如果 chunk 可比对，列出新增、删除、变化的 chunk id、锚点和对应 `mapsToOperations`。 - 可能影响：CLI operation、operation schema、测试、路由词、reference、禁用边界、写操作确认链。 - 明确问题：是否将这些变更同步转换进 `src/shortcuts/` 和 `weaver-e10-` Skill？ 用户确认前，不要覆盖 `src/shortcuts/`、`SKILL.md`、reference、business-info 或 domain 文件。 如果文件 sha256 变化但 `sourceChunks` 全部未变，优先判断为排版、说明或未映射内容变化；仍要摘要说明，并让用户确认是否需要刷新 manifest。不要因为 chunk 未变就静默改写产物。 ## Manifest 缺失或不可信 如果目标 Skill 已存在但没有 `source-manifest.json`： 1. 不要假设它由本 Skill 生成。 2. 先把它标记为“未纳入源指纹管理的已有 Skill”。 3. 询问用户是否要接管并重建 manifest。 如果 manifest 指向的源路径不存在，向用户说明缺失路径并询问新的源资料位置；不要自行搜索整个磁盘。 如果 manifest 只有 `artifactBaseline` 或 `detectionStrength=weak`，只能说明“当前可检测到产物基线或源范围变化，不能精确证明原始源资料是否变化”。用户提供新的原始源资料后，应先重建强基线，再做转换。 ## 更新后的写入 用户确认转换更新后： 1. 只修改受源变化影响的 CLI、operation schema、测试、入口、reference、business-info、domain 和 manifest。 2. 在 `source-manifest.json` 写入新的 `generatedAt`、`sourceSet.aggregateSha256` 和 sources；如果本次来自 Git ref 范围，同步记录模块相对路径、关联公共路径、旧/新 ref、解析后的完整 commit SHA 和比较时间，但不要写本地个人绝对路径、大段 diff 或提交正文。 3. 如果能稳定切块，同步更新 `sourceChunks` 和 `operationImpact`；不能稳定切块时保留文件级检测并写明弱检测限制。机器可读契约、OpenAPI/JSON Schema、operation manifest 或字段枚举表应作为 schema 与 handler 的优先依据。 4. 同步更新 `sourceCoverage`，逐个源文件标明转换状态；不能把新增或变化的业务 MD 合并成一条笼统说明。 5. 刷新 `artifactBaseline`，用于提示生成产物是否被手工改过。 6. 保留与源变化无关、用户可能手工维护的 reference 内容，除非它与新源资料冲突。`patch` / `minor` 变化可按确认范围更新；`major` 变化必须保留兼容策略、迁移说明或显式拒绝旧输入的结构化错误。 7. 完成后运行 CLI schema 验证、业务测试、skill 结构验证、泛微技能检测工具和相关测试。基于 Git 更新的 operation 必须有语义回归或 golden tests 覆盖，不要只依赖 artifact 文件存在性。 最终回复要明确说明：哪些源资料变化已转换成 CLI 与 Skill，哪些变化因资料不足而暂停并等待用户确认。