{"id":"db6200de-a2d0-4f23-a1f4-a496617afd38","entityType":"agent","slug":"clawhub-ldxs001-skill-sub","name":"skill-sub","canonicalUrl":"https://www.xpersona.co/agent/clawhub-ldxs001-skill-sub","canonicalPath":"/agent/clawhub-ldxs001-skill-sub","generatedAt":"2026-10-10T07:40:38.361Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T01:54:32.543Z","emptyReason":null},"description":"调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。 Skill: skill-sub Owner: ldxs001 Summary: 调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。 Tags: blueprint:1.38.1, chain:1.38.1, editor:1.38.1, hook:1.38.0, latest:1.38.1, orchestration:1.38.1, planner:1.38.1, progressive-loading:1.38.1, skill-builder:1.38.1, step-index:1.38.1, usable:1.38.1 Version history: v1.38.1 | 2026-07-10T01:49:21.076Z | user v1.38.1 v1.38.0 |","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.8K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s1794v2r46s8y5d1r4jdd7ec5h84rw70:skill-sub","sourceUrl":"https://clawhub.ai/ldxs001/skill-sub","homepage":"https://clawhub.ai/ldxs001/skills/skill-sub","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/ldxs001/skill-sub","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/ldxs001/skills/skill-sub","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。 Skill: skill-sub Owner: ldxs001 Summary: 调用链编排技能 — 既是调用链编辑器"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:54:32.543Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:54:32.543Z","emptyReason":null},"stars":null,"forks":null,"downloads":1792,"packageName":null,"latestVersion":"1.38.1","tractionLabel":"1.8K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:54:32.541Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T01:54:32.543Z","lastCrawledAt":"2026-10-10T01:54:32.541Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T01:54:32.542Z","lastVerifiedAt":null,"highlights":[{"version":"1.38.1","createdAt":"2026-07-10T01:49:21.076Z","changelog":"v1.38.1","fileCount":32,"zipByteSize":122775},{"version":"1.38.0","createdAt":"2026-07-03T03:16:59.053Z","changelog":"新增流程钩子系统 chain_hook.py：里程碑/末尾步骤前置产出物检查","fileCount":19,"zipByteSize":63396},{"version":"1.37.3","createdAt":"2026-07-03T02:55:30.082Z","changelog":"修正渐进式文件索引表：移除 scripts/ 条目","fileCount":19,"zipByteSize":63129},{"version":"1.37.2","createdAt":"2026-07-03T02:49:36.572Z","changelog":"修正 displayName 为 skill-sub","fileCount":19,"zipByteSize":63189},{"version":"1.37.1","createdAt":"2026-07-03T02:47:13.152Z","changelog":"SKILL.md 文档结构标准化：触发条件章节优化，工作流程格式化（列表+输入输出标注），配置表补齐，约束章节合并","fileCount":19,"zipByteSize":63168},{"version":"1.29.1","createdAt":"2026-06-25T10:25:42.788Z","changelog":"**skill-sub 1.29.1** - 新增步骤蓝图搜索、步骤索引、步骤健康检查等能力说明。 - 权限等级提升至 MEDIUM，并完善 permissions 说明内容。 - 丰富渐进式文件索引，新增 LICENSE.md、loop_branch.md 等文档说明。 - 配置说明新增配置界面启动命令及细化表格。 - 快速上手与示例补充 step_index/planner 场景及链健康检查相关脚本指令。 - 触发条件/否定条件逻辑更新，更准确描述 skill 自动触发与限制情形。","fileCount":25,"zipByteSize":102057},{"version":"1.27.0","createdAt":"2026-06-02T02:39:57.009Z","changelog":"skill-sub 1.27.0 - 强化了定时/自动化流程的检测与注册：调用链如包含定时/自动化意图，必须在创建时附带 --schedule 参数并立即注册调度，否则将被拦截。 - 新增报错规则：检测到定时/自动化意图却未配置 --schedule 时，链创建直接中断，并提示补充参数。 - 补充工作流程说明，明确调度注册时机为“链创建成功且带 schedule 时必须立即注册”，杜绝遗漏。 - 移除了 skill-card.md 文件，不影响主流程。","fileCount":19,"zipByteSize":61834},{"version":"1.25.0","createdAt":"2026-06-02T02:02:53.445Z","changelog":"**New feature: Adhesion Point (粘连点) support, enhancing skill chain flexibility and robustness.** - 新增“粘连点”机制：流程缺口自动标记，三种解决方案（manual/auto/hybrid）与自愈流程，详见 references/adhesion.md - 文件调整：新增 references/adhesion.md、scripts/chain_flow_validator.py、scripts/chain_structure_checker.py；移除 skill-card.md - 快速开始、能力边界、错误校验及配置说明均针对粘连点和新流程做出更新 - 增强链校验和结构检查，支持粘连点连续性、比例等校验 - 文档与指令示例同步完善，覆盖粘连点相关用法","fileCount":19,"zipByteSize":57954}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1794v2r46s8y5d1r4jdd7ec5h84rw70:skill-sub","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-skill-sub/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-skill-sub/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-skill-sub/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-skill-sub/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-skill-sub/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-skill-sub/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T07:40:38.358Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-skill-sub/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-skill-sub/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-skill-sub/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ldxs001-skill-sub/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T01:54:32.543Z","emptyReason":null},"readme":"Skill: skill-sub\n\nOwner: ldxs001\n\nSummary: 调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。\n\nTags: blueprint:1.38.1, chain:1.38.1, editor:1.38.1, hook:1.38.0, latest:1.38.1, orchestration:1.38.1, planner:1.38.1, progressive-loading:1.38.1, skill-builder:1.38.1, step-index:1.38.1, usable:1.38.1\n\nVersion history:\n\nv1.38.1 | 2026-07-10T01:49:21.076Z | user\n\nv1.38.1\n\nv1.38.0 | 2026-07-03T03:16:59.053Z | user\n\n新增流程钩子系统 chain_hook.py：里程碑/末尾步骤前置产出物检查\n\nv1.37.3 | 2026-07-03T02:55:30.082Z | user\n\n修正渐进式文件索引表：移除 scripts/ 条目\n\nv1.37.2 | 2026-07-03T02:49:36.572Z | user\n\n修正 displayName 为 skill-sub\n\nv1.37.1 | 2026-07-03T02:47:13.152Z | user\n\nSKILL.md 文档结构标准化：触发条件章节优化，工作流程格式化（列表+输入输出标注），配置表补齐，约束章节合并\n\nv1.29.1 | 2026-06-25T10:25:42.788Z | auto\n\n**skill-sub 1.29.1**\n\n- 新增步骤蓝图搜索、步骤索引、步骤健康检查等能力说明。\n- 权限等级提升至 MEDIUM，并完善 permissions 说明内容。\n- 丰富渐进式文件索引，新增 LICENSE.md、loop_branch.md 等文档说明。\n- 配置说明新增配置界面启动命令及细化表格。\n- 快速上手与示例补充 step_index/planner 场景及链健康检查相关脚本指令。\n- 触发条件/否定条件逻辑更新，更准确描述 skill 自动触发与限制情形。\n\nv1.27.0 | 2026-06-02T02:39:57.009Z | user\n\nskill-sub 1.27.0\n\n- 强化了定时/自动化流程的检测与注册：调用链如包含定时/自动化意图，必须在创建时附带 --schedule 参数并立即注册调度，否则将被拦截。\n- 新增报错规则：检测到定时/自动化意图却未配置 --schedule 时，链创建直接中断，并提示补充参数。\n- 补充工作流程说明，明确调度注册时机为“链创建成功且带 schedule 时必须立即注册”，杜绝遗漏。\n- 移除了 skill-card.md 文件，不影响主流程。\n\nv1.25.0 | 2026-06-02T02:02:53.445Z | user\n\n**New feature: Adhesion Point (粘连点) support, enhancing skill chain flexibility and robustness.**\n\n- 新增“粘连点”机制：流程缺口自动标记，三种解决方案（manual/auto/hybrid）与自愈流程，详见 references/adhesion.md\n- 文件调整：新增 references/adhesion.md、scripts/chain_flow_validator.py、scripts/chain_structure_checker.py；移除 skill-card.md\n- 快速开始、能力边界、错误校验及配置说明均针对粘连点和新流程做出更新\n- 增强链校验和结构检查，支持粘连点连续性、比例等校验\n- 文档与指令示例同步完善，覆盖粘连点相关用法\n\nv1.24.10 | 2026-06-01T06:51:12.666Z | user\n\n- Version bump from 1.24.8 to 1.24.10.\n- No file changes detected; metadata version updated only.\n- No changes to features, behavior, or documentation content.\n\nv1.24.8 | 2026-06-01T06:40:05.075Z | user\n\n- Removed the deprecated documentation file skill-card.md.\n- SKILL.md: Improved and streamlined the description and metadata fields.\n- SKILL.md: Now references all documentation in the references subfolder for better organization.\n- No functional or user-facing changes to commands or behavior.\n\nv1.24.6 | 2026-06-01T05:12:53.251Z | user\n\n- 精简与规范化了 SKILL.md，突出核心功能和主要触发场景\n- 移除过多描述与冗余内容，功能一览以表格形式呈现\n- 触发条件和否定条件表述更简明清晰\n- 渐进式文档和配置表格整体整理，结构更分明\n- 无代码文件变更，均为文档精简和规范调整\n\nv1.24.5 | 2026-06-01T04:33:20.793Z | user\n\n- Removed the sample file skill-card.md.\n- Added meta_field_sync: true to SKILL.md.\n- No changes to core functionality or workflow; this version focuses on file organization and metadata updates.\n\nv1.24.1 | 2026-05-30T19:12:28.005Z | user\n\nv1.24.1 is a minor update with formatting adjustments.\n\n- Minor formatting changes in documentation, including added code-block language tags.\n- No functional or feature changes.\n\nv1.24.0 | 2026-05-30T16:34:03.245Z | user\n\nskill-sub v1.24.0\n\n- 移除了 scripts/test_output.txt 示例或测试输出文件。\n- SKILL.md 文档结构优化及精简，更新数据目录路径。\n- 新增 skill 元数据字段：trigger 与 trigger_negative，增强触发条件描述。\n- 说明文档链接和各部分标记细节调整，整体更精炼易读。\n\nv1.23.3 | 2026-05-29T20:15:46.529Z | user\n\nskill-sub v1.23.3\n\n- Changed permission_weight from MEDIUM to LOW.\n- Added a concise changelog at references/changelog.md.\n- Removed references/CHANGELOG.md and skill-card.md for streamlined documentation.\n- Minor adjustments to metadata and documentation links.\n\nv1.23.0 | 2026-05-27T15:51:10.213Z | user\n\nskill-sub v1.23.0\n\n- 配置文件和设置页面从 assets/ 迁移到 scripts/ 目录（default_config.json 与 settings.html 路径更新）\n- 技能描述中的版本号升级为 v1.23.0\n- 其他功能无变动，主要为目录结构和配置管理优化\n\nv1.22.0 | 2026-05-26T15:17:15.992Z | user\n\nskill-sub v1.22.0\n\n- 新增脚本 loop_branch_renderer.py，实现了调用链的循环与分支渲染能力。\n- 支持子步骤拓扑排序与准确步骤计数，提升复杂调用链的可视化和可操作性。\n- 删除了示例标准化链（semantic-split-standardize.json），优化链结构。\n- 权限范围收紧，关闭了敏感写权限（sensitive_access、critical_write 为 false），permission_weight 降为 MEDIUM。\n- 文档描述同步更新，反映对循环/分支编排和子步骤计数的增强。\n\nv1.19.2 | 2026-05-26T11:57:59.281Z | user\n\n**v1.19.2 introduces file cleanup and changelog location update.**\n\n- Added references/CHANGELOG.md as the official changelog file.\n- Added a new chain definition: chains/semantic-split-standardize.json.\n- Removed references/changelog.md; changelog now standardized as CHANGELOG.md.\n- Removed scripts/settings.py and scripts/skill_extractor.py, cleaning up deprecated scripts.\n\nv1.16.0 | 2026-05-25T07:12:01.694Z | user\n\n**Summary:** \nv1.16.0 adds detailed reference documentation for antipatterns and permissions.\n\n- 新增 `references/antipatterns.md`，汇总常见反模式与正确用法\n- 新增 `references/permissions.md`，补充权限说明与合规自查\n- 完善渐进式文档体系，便于查阅关键规范与反例\n- 便于用户理解权限边界与常见误区\n\nv1.12.0 | 2026-05-24T13:49:39.369Z | user\n\nskill-sub v1.12.0\n\n- Version bump only; no file or documentation changes detected.\n- All features and documentation remain unchanged from v1.11.0.\n\nv1.11.2 | 2026-05-24T06:47:12.855Z | user\n\nskill-sub v1.11.2\n\n- 设置 metadata 字段 sensitive_access: true，声明该技能包含敏感访问行为\n- 其他功能、文档和实现无更改\n\nv1.11.1 | 2026-05-23T15:39:54.352Z | user\n\nskill-sub v1.11.0\n\n- 明确补充能力边界，一目了然 skill-sub 能做/不能做的内容\n- 优化触发方式，新增推荐条件表，便于理解何时自动推荐调用链\n- 新增 references/faq.md，收录常见反模式与使用误区\n- 文档结构微调，方便文档渐进式加载和快速查阅\n\nv1.11.0 | 2026-05-23T15:39:19.972Z | user\n\nskill-sub v1.11.0\n\n- 明确补充能力边界，一目了然 skill-sub 能做/不能做的内容\n- 优化触发方式，新增推荐条件表，便于理解何时自动推荐调用链\n- 新增 references/faq.md，收录常见反模式与使用误区\n- 文档结构微调，方便文档渐进式加载和快速查阅\n\nv1.10.2 | 2026-05-23T14:25:08.149Z | user\n\n- 修复 depends_on:null 导致 classify_milestones TypeError\n- SKILL.md 标题版本号与实际版本号同步\n\nv1.10.1 | 2026-05-23T11:25:18.415Z | user\n\nv1.10.1 is a version bump with no file changes.\n\n- No changes detected in any files\n- Maintains compatibility and version alignment only\n\nv1.9.2 | 2026-05-23T03:21:50.016Z | user\n\n- Version updated from 1.9.1 to 1.9.2.\n- No file changes detected; contents and features remain the same.\n\nv1.9.1 | 2026-05-23T01:42:44.354Z | user\n\n- 新增 HTML 设置界面（assets/settings.html）\n- tags 字段微调，更贴合链编排核心用途\n- 调用链相关表述简化，说明文件微调适配新版本\n- 版本号提升至 1.9.1\n\nv1.7.0 | 2026-05-23T00:21:41.681Z | user\n\nskill-sub v1.7.0\n\n- 文档封面与主标题升级为 1.7.0，突出最新版本信息\n- 优化“调用链编排技能”的简介描述，突出用法流程\n- 保持三阶段生成流程、工作流程、核心概念等主要内容不变\n- 对版头说明和部分表述微调，使内容更聚焦、条理更清晰\n- 核心命令、CLI 速查、分文件体系布局无变动，保持渐进式加载结构\n\nv1.6.0 | 2026-05-23T00:07:19.464Z | user\n\nskill-sub v1.6.0 introduces progressive markdown loading and modular documentation:\n\n- Major restructure: SKILL.md now contains only the core concepts, generation logic, triggers, workflow, and starter commands (≤200 lines).\n- Detailed technical references (data schema, full CLI/API, workflow, examples, changelog) are split into `references/` for on-demand loading.\n- Removed deprecated `assets/settings.html`; settings interface reference now modular.\n- Updated all documentation to clarify that skill-sub is an editor/planner/composer — not part of the execution chain.\n- Self-checks for skill standards are now referenced in `references/changelog.md`.\n\nv1.2.1 | 2026-05-21T17:28:39.233Z | user\n\n## skill-sub 1.2.1 更新日志\n\n- 新增 `assets/settings.html`，引入 HTML 设置界面。\n- 支持通过浏览器图形界面进行配置查看与调整，提升易用性。\n- 其他功能与数据结构保持兼容，配置流程更友好。\n\nv1.2.0 | 2026-05-21T11:58:33.015Z | user\n\n**Summary: Enhanced chain control, error strategies, and configurable settings.**\n\n- Added centralized default configuration file (`assets/default_config.json`) for customizable settings.\n- Introduced `scripts/settings.py` to manage and serve settings (HTML interface & CLI usage).\n- New support for adjustable retry strategies and failure modes on chain steps.\n- Steps now include original instruction reference (`skill_instruction`), retry policy, and milestone logic.\n- Provides full settings management: memory reference, naming, default retries—accessible via web or CLI.\n- Strengthened milestone step rules and automated detection; milestone step failure now aborts whole chain.\n\nv1.0.1 | 2026-05-21T08:35:12.128Z | user\n\n- 默认数据目录由 `~/.workbuddy/skill-chain/` 调整为 `~/.workbuddy/skill-sub/`。\n- 示例调用链中技能名称由 `skill-chain` 修改为 `skill-sub`。\n- 文档中其余内容未发生变更。\n\nv1.0.0 | 2026-05-21T08:13:47.376Z | user\n\nSkill-chain v1.0.0 – Initial Release\n\n- Enables creation, editing, execution, and management of multi-step skill invocation chains based on user intent.\n- Chains are reusable, can be adjusted dynamically, and support complex workflows with dependencies and variable passing between steps.\n- Provides command-line and AI-driven orchestration for creating, listing, editing, running, and deleting invocation chains.\n- Extracts key steps from existing skills without modifying their original functions.\n- Stores chain definitions and metadata in a persistent local directory for reuse and indexing.\n- Ensures user confirmation for creation and modification, with robust error handling during execution.\n\nArchive index:\n\nArchive v1.38.1: 32 files, 122775 bytes\n\nFiles: _meta.json (129b), references/adhesion.md (5948b), references/antipatterns.md (2639b), references/blueprint.md (342b), references/chain_schema.md (14756b), references/chain_search.md (158b), references/changelog.md (21639b), references/examples.md (5150b), references/faq.md (4975b), references/gate.md (841b), references/LICENSE.md (1097b), references/llm_params.md (536b), references/loop_branch.md (1456b), references/permissions.md (1779b), references/private_blueprint.md (366b), references/reference.md (6938b), references/workflow.md (10642b), scripts/chain_executor.py (30337b), scripts/chain_flow_validator.py (10430b), scripts/chain_gate.py (10191b), scripts/chain_hook.py (5755b), scripts/chain_manager.py (59541b), scripts/chain_planner.py (23557b), scripts/chain_structure_checker.py (11758b), scripts/default_config.json (194b), scripts/settings.html (10712b), scripts/settings.py (12327b), scripts/skill_extractor.py (45337b), scripts/step_indexer.py (33333b), scripts/step_link_validator.py (27465b), skill-card.md (2690b), SKILL.md (9797b)\n\nFile v1.38.1:SKILL.md\n\n---\r\nname: skill-sub\r\nslug: skill-sub\r\ndisplayName: skill-sub\r\nversion: 1.38.1\r\nauthor: wUwproject\r\nlicense: MIT\r\ndescription: 调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。\r\nsensitive_access: false\r\ncritical_write: false\r\npermission_weight: MEDIUM\r\ndata_dir: ../.standardization/skill-sub/data/\r\ntags: ['chain', 'orchestration', 'usable', 'skill-builder', 'progressive-loading', 'planner', 'editor', 'step-index', 'blueprint']\r\nexternal_data_dir: true\r\ntrigger: ['加载用户配置（合并默认值 + 用户覆盖）', '用户需要识别依赖关系、并行机会，输出 AI 可执行的指令序列。', 'chain_executor.py - Chain Executor', '调用链执行引擎：根据调用链定义生成结构化执行计划']\r\ntrigger_negative: true\r\nmeta_field_sync: true\r\nh1_position: true\r\ncreate_permissions_md: true\r\ntrigger_quality: refine_triggers\r\ntrigger_danger: remove_dangerous\r\n---\r\n# skill-sub\r\n\r\n## 约束\r\n\r\n参数约束：skill-dir 绝对路径 20-260 字符，描述文本 ≤120 字。最大步骤数 30 层，粘连点占比上限 30%，依赖深度上限 10 层。\r\n\r\n\r\n### 适宜场景 ✅\r\n\r\n| 场景 | 说明 |\r\n| ------ |------|\r\n| 多 skill 编排 | 涉及 2 个及以上 skill，步骤间有明确依赖关系 |\r\n| 可固化流程 | 流程稳定、可复现，不是一次性操作 |\r\n| 跨步骤衔接 | skill 之间需要数据转换、人工审批、流程补全 |\r\n\r\n### 不适宜场景 ❌\r\n\r\n| 场景 | 原因 |\r\n| ------ |------|\r\n| 单 skill 任务 | 直接调 skill 本身即可，不需要调用链 |\r\n| 一次性操作 | 调用链的价值在于复用，一次性工作不值得建链 |\r\n| 无依赖的并行任务 | 多个独立任务应并行执行，不需要编排 |\r\n| 高度动态的流程 | 每次执行步骤都不一样，粘连点也解决不了，直接 AI 手动处理 |\r\n\r\n### 硬限制\r\n\r\n| 限制项 | 值 | 说明 |\r\n| -------- |-----| ------ |\r\n| 最大步骤数 | 30 层（含嵌套） | 超过后校验器会告警，但不阻断执行 |\r\n| 粘连点占比 | 30% | 超过告警，建议合并或补充 skill |\r\n| 粘连点连续 | **禁止** | 连续缺口合并为一个粘连点 |\r\n| 依赖深度 | 10 层 | 过深依赖链难以维护和排查 |\r\n| 循环最大迭代 | 默认 10，可配置 | 超过按 on_max_iteration 处理 |\r\n\r\n### 常见创建错误速查\r\n\r\n| 报错信息 | 原因 | 解决方法 |\r\n| --------- |------| --------- |\r\n| 连续缺口应合并为一个粘连点 | 两个 adhesion 步骤相邻 | 合并为一个 adhesion，用 hybrid 方案覆盖全部缺口 |\r\n| 粘连点占比超过 30% | adhesion 步骤太多 | 检查是否有 skill 可以替代 |\r\n| 缺少 solutions | adhesion 步骤没有提供方案 | 至少加一个 manual 方案 |\r\n| 依赖不存在的步骤 | depends_on 引用了无效索引 | 检查依赖步骤的 index 是否正确 |\r\n| 引用的 skill 不存在 | skill_name 对应的 skill 未安装 | 检查 skill 名称是否正确 |\r\n| 检测到定时/自动化意图，但未提供 --schedule | 描述中含\"每天/每周/定时\"等词但没给调度配置 | 添加 --schedule 参数，或删除描述中的时间相关词 |\r\n\r\n> **强制规则**：用户描述中包含定时/自动化意图（如\"每天\"、\"每周\"、\"自动执行\"等）时，**必须**提供 `--schedule` 参数配置调度信息，否则链创建被拦截。 不依赖 AI 自觉判断。\r\n\r\n## 触发条件\r\n\r\n**正向触发：**\r\n- 规划类：「帮我规划一下...」、「...的步骤是什么」\r\n- 顺序类：「依次执行 A、B、C」、「先...再...」\r\n- 链管理：「创建/查看/更新/删除调用链」\r\n- 步骤搜索类：「搜索步骤」、「找步骤」\r\n- 链健康检查：「检查链的健康状态」\r\n- 仅涉及单个 skill 的简单任务\r\n\r\n**否定条件：**\r\n- 明确要求「不使用调用链」\r\n\r\n## 触发场景\r\n**正向触发**：\r\n- chain_executor.py - Chain Executor v1.22.0\r\n- 调用链执行引擎：根据调用链定义生成结构化执行计划，\r\n- 识别依赖关系、并行机会，输出 AI 可执行的指令序列。\r\n- 加载用户配置（合并默认值 + 用户覆盖）\r\n\r\n**否定条件**：\r\n- 简单问答、闲聊、问候（不需要本技能）\r\n- 单步任务（不需要结构化执行）\r\n\r\n## 核心能力\r\n\r\n> 📚 **渐进式加载**：本技能采用渐进式 MD 体系，`SKILL.md` 为入口（≤230行），详细内容拆分到 `references/*.md` 按需加载。\r\n\r\n| # | 功能 | 说明 |\r\n| --- |------| ------ |\r\n| 1 | **调用链管理** | 创建、查询、更新、删除调用链 |\r\n| 2 | **执行计划生成** | 生成结构化执行计划，含并行/串行标记 |\r\n| 3 | **条件执行** | 支持条件步骤，按条件判断是否执行 |\r\n| 4 | **循环与分支编排** | 支持 for-each/while 循环和 if-else 分支 |\r\n| 5 | **门禁系统** | 10 座 HARD 门禁串行阻断管线（chain_gate.py），HOOK-BLOCK 输出 |\r\n| 6 | **步骤蓝皮书过期检测** | `search` 命令前置自动比对指纹，过期直接拒绝搜索 |\r\n| 7 | **链私有蓝皮书基线校验** | 链创建时 snapshot 步骤接口，执行前自动校验基线偏移 |\r\n| 8 | **粘连点（Adhesion Point）** | 标记 skill 无法自动化的缺口，提供三种解决方案保证链不断 |\r\n| 9 | **自增强闭环（模板搜索）** | `chain_manager search` 匹配历史链，相似意图直接复用 |\r\n\r\n---\r\n\r\n### 渐进式文件索引\r\n\r\n| 文件名 | 分类 | 包含内容 | 审计关联 |\r\n| -------- |------| ---------- |----------|\r\n| `references/LICENSE.md` | 许可协议 | 开源许可证声明（MIT）。包含：MIT 许可证完整文本。 | R-26 |\r\n| `references/adhesion.md` | 参考文档 | > **v1.25.0 新增**。粘连点是调用链中无法由 skill 自动化的缺口标记。 | 无 |\r\n| `references/antipatterns.md` | 规范指南 | skill 编写中的常见反模式。包含：错误做法示例、正确做法示例、避坑指引。 | R-18 |\r\n| `references/chain_schema.md` | 参考文档 | > 本文档定义 Chain / Step / retry_policy / failure_mode 的完整结构。 | 无 |\r\n| `references/changelog.md` | 版本管理 | 版本更新日志。包含：版本号、更新类型、修复项、升级说明。 | R-24 |\r\n| `references/examples.md` | 使用示例 | 各场景完整执行示例。包含：CLI 命令、执行过程、输出结果。 | R-25 C-17 |\r\n| `references/faq.md` | 常见问题 | 常见疑问与解答。包含：问题分类、原因分析、解决方案。 | R-19, R-25 C-19 |\r\n| `references/loop_branch.md` | 参考文档 | > 本文档是 SKILL.md 的渐进式补充，包含循环与分支编排的完整示例。 | 无 |\r\n| `references/permissions.md` | 权限与测试 | 权限扫描说明与测试结论。包含：风险等级、高权限操作说明、测试概览、计时统计。 | R-15, R-16 |\r\n| `references/reference.md` | 命令参考 | CLI 完整命令参考。包含：所有参数、子命令、选项、示例用法。 | 无 |\r\n| `references/workflow.md` | 参考文档 | > 本文档是 SKILL.md 的渐进式补充，详细描述执行流程、里程碑判断规则、三层回退策略。 | 无 |\r\n| `references/blueprint.md` | 参考文档 | 步骤蓝皮书结构与更新流程 | 无 |\r\n| `references/gate.md` | 参考文档 | 门禁系统完整文档与 CLI 示例 | 无 |\r\n| `references/private_blueprint.md` | 参考文档 | 链私有蓝皮书基线保护机制 | 无 |\r\n| `references/llm_params.md` | 参考文档 | LLM 参数格式与门禁对应关系 | 无 |\r\n| `references/chain_search.md` | 参考文档 | 自增强闭环历史链搜索 | 无 |\r\n\r\n## 快速开始\r\n\r\n\r\n\r\n| # | 功能 | 说明 |\r\n| --- |------| ------ |\r\n| 1 | 调用链管理 | 创建/查询/更新/删除 |\r\n| 2 | 门禁系统 | 10 座 HARD 门禁 |\r\n| 3 | 蓝皮书过期检测 | search 自动比对指纹 |\r\n| 4 | 基线校验 | 执行前自动比对 |\r\n| 5 | 粘连点 | 缺口标记+方案 |\r\n| 6 | 历史链搜索 | n-gram 匹配 |\r\n\r\n## 工作流程\r\n\r\n### 前置硬约束\r\n\r\n3. 步骤蓝皮书过期检测：search 命令自动比对指纹\r\n2. 链私有蓝皮书基线校验：执行前自动比对\r\n1. 门禁系统：10 座 HARD 门禁串行阻断\r\n\r\n### 规划执行流程（串行，门禁阻断）\r\n\r\n**流程图**：串行门禁流\r\n流程图如下，编号列表：\r\n\r\n1. 蓝皮书校验 — 输入: search 指纹; 输出: 已校验\r\n2. 理解意图 — 输入: 用户原始意图文本; 输出: 时序子意图列表\r\n3. 步骤搜索 — 输入: 子意图文本; 输出: 候选步骤列表\r\n4. LLM 选步骤 — 输入: 候选; 输出: 选定 ID\r\n5. 里程碑 — 输入: 步骤; 输出: 标记\r\n6. I/O校验 — 输入: I/O; 输出: 分数\r\n7. 黏连点 — 输入: 缺口; 输出: 方案\r\n8. DAG+保存 — 输入: 依赖; 输出: 链文件\r\n9. 健康检查 — 自动基线校验\r\n10. 执行 — 按计划调用 skill\r\n\r\n### 门禁系统\r\n\r\n门禁系统参见渐进式文件索引表\r\n\r\n### 链私有蓝皮书\r\n\r\n链私有蓝皮书参见渐进式文件索引表\r\n\r\n### LLM 参数\r\n\r\nLLM 参数参见渐进式文件索引表\r\n\r\n### 自增强闭环\r\n\r\n自增强闭环参见渐进式文件索引表\r\n\r\n## 配置\r\n\r\n\r\n| 参数 | 类型 | 默认值 | 说明 |\r\n| ------ |------| -------- |------|\r\n| 记忆参考 | bool | false | 创建时读用户记忆 |\r\n| 命名方式 | string | auto | AI 命名或询问 |\r\n| 默认重试 | int | 3 | 1-10 可配置 |\r\n| 黏连方案 | string | manual | 缺口处理策略：manual/auto/skip |\r\n\r\n\r\n详见 references/blueprint.md。\r\n\r\n```bash\r\nstep_indexer.py search --intent \"分析\"\r\nstep_indexer.py status\r\n```\n\nFile v1.38.1:_meta.json\n\n{\n \"ownerId\": \"kn75zfd51df61ajdyqtgvrs1hx84s4q6\",\n \"slug\": \"skill-sub\",\n \"version\": \"1.38.1\",\n \"publishedAt\": 1783648161076\n}\n\nFile v1.38.1:references/adhesion.md\n\n# 粘连点（Adhesion Point）机制\r\n\r\n> **v1.25.0 新增**。粘连点是调用链中无法由 skill 自动化的缺口标记。\r\n\r\n---\r\n\r\n## 什么是粘连点\r\n\r\n粘连点是调用链中一个特殊类型的步骤（`type: \"adhesion\"`），标记该位置无法由任何已安装 skill 自动完成。它不会阻断调用链，而是提供三种解决方案供 LLM 选择。\r\n\r\n### 什么时候产生粘连点\r\n\r\n| 场景 | 触发条件 | 行为 |\r\n|------|---------|------|\r\n| **链修正** | 执行链时发现步骤与真实 skill 不符，修正后仍报错 | 在该步骤位置打粘连点 |\r\n| **链缺口** | 规划链时某步骤无对应 skill 可用 | 在缺失位置插入粘连点 |\r\n| **流程缺口分析** | 规划阶段发现语义/流程/决策缺口 | 在天然断裂处打粘连点（见下方规则） |\r\n\r\n### 三个核心原则\r\n\r\n1. **链不断** — 粘连点标记不阻断调用链执行，LLM 按方案继续\r\n2. **连接器，非替代品** — 粘连点是两个 skill 步骤之间的连接器，不是 skill 步骤的替代品。**禁止粘连点连粘连点**，连续缺口合并为一个粘连点\r\n3. **不创建 Skill** — 解决方案是步骤描述级别，产生的脚本/产出物归数据目录管理\r\n4. **自愈** — 每次使用含粘连点的链，主动检查是否有新 skill 可填补\r\n\r\n---\r\n\r\n## 缺口分析规则（规划阶段）\r\n\r\n在创建调用链的步骤 3→4 之间插入流程缺口分析，按以下规则判断：\r\n\r\n### 三种真实缺口\r\n\r\n| 缺口类型 | 判断依据 | 应打粘连点？ | 方案优先级 |\r\n|---------|---------|------------|-----------|\r\n| **语义缺口** | Skill A 输出格式/内容 ≠ Skill B 期望输入 | ✅ 数据转换步骤 | hybrid |\r\n| **流程缺口** | 用户任务中的某个环节无任何 skill 覆盖 | ✅ 补充缺失步骤 | auto / manual |\r\n| **决策缺口** | 需要人工审批、判断、签字的节点 | ✅ 人工审批节点 | manual |\r\n| **自然衔接** | Skill A 输出可直接作为 Skill B 输入 | ❌ 不打 | — |\r\n\r\n### 禁止行为\r\n\r\n| 禁令 | 说明 |\r\n|------|------|\r\n| ❌ 不要制造缺口 | 自然衔接的 skill 不打粘连点 |\r\n| ❌ 不要粘连点连粘连点 | **连续缺口合并为一个粘连点** |\r\n| ❌ 不要替代 skill | 能用 skill 完成的直接用 skill |\r\n| ❌ 不要过度粘连 | 粘连点数量应远少于 skill 步骤数 |\r\n\r\n### 判定示例\r\n\r\n```text\r\n用户需求：分析代码 → 生成报告 → 发送邮件\r\n\r\n✓ 正确：\r\n 步骤1: code-analysis (skill) — 分析代码\r\n 步骤2: report-generation (adhesion) — JSON→Markdown 语义缺口\r\n 步骤3: email-send (skill) — 发送邮件\r\n\r\n✓ 连续缺口合并：\r\n 步骤1: code-analysis (skill)\r\n → 步骤2: data-cleanup (缺失) — 两个连续缺失合并为一个粘连点\r\n → 步骤3: transform (缺失) — 🔴 禁止！应为：\r\n 步骤2: data-pipeline (adhesion, hybrid) — 覆盖清洗+转换的完整缺口\r\n 步骤3: email-send (skill)\r\n\r\n✗ 过度粘连：\r\n 步骤1: code-analysis (skill)\r\n 步骤2: report-generation (adhesion) — ❌ 如果有 report skill 就不该打\r\n 步骤3: email-send (skill)\r\n\r\n✗ 粘连点连粘连点（禁止）：\r\n 步骤1: code-analysis (skill)\r\n 步骤2: manual-review (adhesion) — ❌ 连续两个粘连点\r\n 步骤3: data-transform (adhesion) — ❌ 应合并为一个\r\n 步骤4: email-send (skill)\r\n```\r\n\r\n---\r\n\r\n## 三种解决方案\r\n\r\n### ① 纯手工（manual）\r\n\r\nLLM 直接手动执行步骤，不依赖脚本或新 skill。\r\n\r\n```json\r\n{\"mode\": \"manual\", \"description\": \"人工审核报告\", \"constraints\": \"需关注数据准确性\"}\r\n```\r\n\r\n**适用场景**：一次性、高度灵活的判断任务。\r\n\r\n### ② 脚本化（auto）\r\n\r\n通过自调用脚本工具执行，产生的脚本入数据目录管理。\r\n\r\n```json\r\n{\"mode\": \"auto\", \"tool_name\": \"report-verify\", \"script_path\": \"scripts/verify.sh\"}\r\n```\r\n\r\n**适用场景**：可标准化、重复执行的任务。\r\n\r\n### ③ 混合（hybrid）\r\n\r\nLLM 描述流程步骤 + 约束 + 自调用工具协同执行。\r\n\r\n```json\r\n{\r\n \"mode\": \"hybrid\",\r\n \"llm_steps\": \"LLM 阅读报告并给出审核意见\",\r\n \"tool_steps\": \"脚本验证报告中的数字准确性\",\r\n \"integration\": \"LLM 分析文本，工具验证数字\"\r\n}\r\n```\r\n\r\n**适用场景**：需要智能判断 + 自动化执行的复合任务。\r\n\r\n---\r\n\r\n## 执行优先级\r\n\r\nAI 执行粘连点步骤时，按以下优先级选择方案：\r\n\r\n1. **hybrid** — 最优先，组合 LLM + 工具的最大能力\r\n2. **auto** — 次优先，能脚本化就不手动\r\n3. **manual** — 兜底，LLM 直接执行\r\n\r\n---\r\n\r\n## 自愈机制\r\n\r\n每次加载含粘连点的调用链时，AI 执行自愈检查：\r\n\r\n```\r\n1. 扫描 skill 库（skill-sub 所在目录的兄弟目录）\r\n2. 对每个粘连点，用 adhesion.reason 关键词搜索 SKILL.md\r\n3. 找到匹配 → 将 adhesion 步骤升级为 skill 步骤\r\n - type 改为 \"skill\"\r\n - 填充 skill_name / action\r\n - 原 adhesion.solutions 写入 notes\r\n4. 未找到 → 按原有 3 方案执行\r\n```\r\n\r\n也可手动触发：`python chain_manager.py check-gaps`\r\n\r\n---\r\n\r\n## 与 chain_executor 集成\r\n\r\n`chain_executor.py` 在执行计划中渲染粘连点步骤：\r\n\r\n```text\r\n### 步骤 3.5: 报告审核\r\n⚠️ 粘连点 — 原因：缺少对应 skill 的自动化能力\r\n 方案1 [混合]：LLM 审核 + 脚本验证\r\n LLM: 阅读报告并给出审核意见\r\n 工具: 脚本验证报告中的数字准确性\r\n 方案2 [纯手工]：完全由 LLM 手工审核报告\r\n```\r\n\r\n---\r\n\r\n## 数据目录\r\n\r\n粘连点相关的脚本和产出物存放在以下位置，遵循 skill-sub 的数据目录规范：\r\n\r\n```\r\n.standardization/skill-sub/data/\r\n├── outputs/ # 脚本化方案产生的输出\r\n└── scripts/ # 自调用工具脚本（auto/hybrid 模式）\r\n```\n\nFile v1.38.1:references/antipatterns.md\n\n# skill-sub 反模式\r\n\r\n> 本文档收录 skill-sub 使用中的常见错误和正确做法。完整反模式示例见 `references/faq.md`。\r\n\r\n---\r\n\r\n## AP-01：把 skill-sub 编入调用链\r\n\r\n**错误做法：**创建调用链时把 `skill-sub` 作为一个步骤加入。\r\n\r\n```\r\n步骤1: skill-sub → 规划\r\n步骤2: xxx\r\n```\r\n\r\n**为什么错：**skill-sub 是编辑器/规划器，不是执行器。链需要的是\"谁干活\"，skill-sub 不干活。\r\n\r\n**正确做法：**调用链只包含执行型 Skill（如 semantic-split、git-sync），不包含 skill-sub 本身。\r\n\r\n---\r\n\r\n## AP-02：为一次性任务创建调用链\r\n\r\n**错误做法：**用户说「帮我查一下今天天气」，就创建一个\"天气查询\"调用链。\r\n\r\n**为什么错：**调用链的价值是复用。一次性任务下次不会用到，反而积累垃圾链。\r\n\r\n**正确做法：**判断任务是否有复用价值。以下信号表明值得创建链：\r\n- 用户说「每次」「以后也」「下次」\r\n- 涉及 ≥3 个 Skill 协作\r\n- 有明确的输入→输出模式\r\n\r\n---\r\n\r\n## AP-03：跳过摘取阶段，直接写 action\r\n\r\n**错误做法：**不读目标 Skill 的 SKILL.md，凭记忆写 action 描述。\r\n\r\n```json\r\n{\"action\": \"执行安全审计\"} // 太模糊，实际执行时不知道具体做什么\r\n```\r\n\r\n**为什么错：**action 是执行时的唯一指引。不读 Skill 原文会导致遗漏关键步骤或用错指令名。\r\n\r\n**正确做法：**执行阶段2摘取——读取目标 Skill 的 SKILL.md「工作流程」章节，摘取步骤名+关键动作+指令名。action 要包含具体的**做什么**（动词+对象+产出）。\r\n\r\n---\r\n\r\n## AP-04：把所有步骤都标为里程碑\r\n\r\n**错误做法：**3 步的链，全标 `is_milestone: true`。\r\n\r\n**为什么错：**里程碑=失败即中止。全标等于没有区分，任何一步失败都中止，丧失灵活性。\r\n\r\n**正确做法：**用里程碑判断规则（关键词/瓶颈点/最终交付）自动判断，只对关键步骤标里程碑。非关键步骤用 `on_exhaust: ask` 或 `skip` 而非 `abort`。\r\n\r\n---\r\n\r\n## AP-05：依赖关系写错导致链无法执行\r\n\r\n**错误做法：**\r\n```json\r\n{\"index\": 1, \"depends_on\": []},\r\n{\"index\": 2, \"depends_on\": [3]}, // 依赖了后面的步骤！\r\n{\"index\": 3, \"depends_on\": [1]}\r\n```\r\n\r\n**为什么错：**步骤2依赖步骤3，但步骤3在步骤2之后执行——死锁。\r\n\r\n**正确做法：**`depends_on` 只能引用 `index` 小于自己的步骤。创建后用 `chain_executor.py validate` 检查。\r\n\r\n---\r\n\r\n> 更多反模式与正确做法 → `references/faq.md`\n\nFile v1.38.1:references/blueprint.md\n\n# 步骤蓝皮书\r\n\r\nskill-sub 将每个已安装技能的 SKILL.md 解析为结构化步骤蓝图，供搜索和链规划使用。\r\n\r\n**硬约束：** search 命令自动比对指纹，过期直接拒绝搜索。\r\n**LLM 提取路径：** check-fingerprint → prepare-llm-input → LLM → apply-blueprint\r\n**Regex 兜底：** scan --force\n\nFile v1.38.1:references/chain_schema.md\n\n# skill-sub 调用链数据结构\r\n\r\n> 本文档定义 Chain / Step / retry_policy / failure_mode 的完整结构。\r\n>\r\n> **v1.20.0 新增**：Step 支持三种类型（skill / loop / branch），详见 Step 扩展类型章节。\r\n\r\n---\r\n\r\n## Chain（调用链）\r\n\r\n```json\r\n{\r\n \"name\": \"string\", // 唯一名称\r\n \"description\": \"string\", // 调用链描述\r\n \"purpose\": \"string\", // 核心目的\r\n \"user_intent\": \"string\", // 用户原始意图（用于意图匹配）\r\n \"tags\": [\"string\"], // 标签（用于自动匹配）\r\n \"auto_safe\": true, // 链是否可不经人工介入全自动执行（由 flow_validator 自动计算）\r\n \"user_specified\": false, // 用户是否显式指定了所有 skill（true→自愈时跳过）\r\n \"schedule\": null, // 调度配置（可选），见下方 Schedule 定义\r\n \"created_at\": \"datetime\",\r\n \"updated_at\": \"datetime\",\r\n \"exec_count\": 0, // 执行次数\r\n \"steps\": [ ... ] // Step 数组，见下文\r\n}\r\n```\r\n\r\n---\r\n\r\n## Schedule（调度配置）\r\n\r\n> 链的调度元数据，任何平台可据此创建定时任务。不绑定具体平台。\r\n\r\n```json\r\n{\r\n \"type\": \"cron\", // \"cron\" | \"interval\" | \"once\"\r\n \"expression\": \"0 6 * * *\", // cron 表达式 / 间隔秒数 / 触发时间\r\n \"description\": \"每天早上6点执行\", // 自然语言描述\r\n \"registered\": false // 是否已在平台注册（创建时为 false，注册后改为 true）\r\n}\r\n```\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `type` | string | ✅ | `\"cron\"`（cron 表达式）、`\"interval\"`（间隔秒数）、`\"once\"`（单次执行） |\r\n| `expression` | string | ✅ | cron 格式（如 `\"0 6 * * *\"`）或间隔秒数（如 `\"86400\"`）或 ISO 时间（如 `\"2026-06-03T06:00:00\"`） |\r\n| `description` | string | ❌ | 自然语言描述，便于跨平台理解 |\r\n| `registered` | bool | ❌ | 注册标记。创建时默认 `false`，平台注册后改为 `true` |\r\n\r\n### 注册流程\r\n\r\n1. 链创建时 `schedule.registered = false`\r\n2. `chain_executor.py plan` 检测到 `registered == false` 时，在计划顶部输出 **强制注册提醒**\r\n3. 平台读取 `schedule` 字段，完成注册后将 `registered` 置为 `true`\r\n4. 已注册的链 `plan` 输出不再显示注册提醒\r\n\r\n### type 说明\r\n\r\n| type | expression 示例 | 含义 |\r\n|------|----------------|------|\r\n| `cron` | `\"0 6 * * *\"` | 每天早上 6 点 |\r\n| `cron` | `\"0 0 * * 1\"` | 每周一零点 |\r\n| `cron` | `\"0 0 1 * *\"` | 每月 1 日零点 |\r\n| `interval` | `\"3600\"` | 每小时执行一次 |\r\n| `interval` | `\"86400\"` | 每天执行一次 |\r\n| `once` | `\"2026-06-03T06:00:00\"` | 2026年6月3日6点执行一次 |\r\n\r\n### 使用方式\r\n\r\n- **创建链时**：用户在意图中描述定时需求（如「每天早上6点跑这个链」），AI 自动填充 `schedule` 字段\r\n- **已有链**：通过 `chain_manager.py schedule --name <链名> --cron \"0 6 * * *\" --desc \"每天6点\"` 添加/更新\r\n- **平台侧**：读取 `chain_data.schedule`，按 `type` + `expression` 注册定时任务\r\n\r\n---\r\n\r\n## Step（步骤）\r\n\r\n> **步骤类型**：通过 `type` 字段区分技能调用、循环、分支。默认 `type: \"skill\"`。\r\n> `steps` / `if_steps` / `else_steps` 均为 Step 数组，支持递归嵌套。\r\n\r\n### 通用字段（所有类型均含）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `index` | int | ✅ | 步骤序号（从 1 开始，全局唯一） |\r\n| `type` | string | ✅ | `\"skill\"` / `\"loop\"` / `\"branch\"` |\r\n| `step_name` | string | ✅ | 步骤名称（展示用） |\r\n| `depends_on` | int[] | ❌ | 依赖的前置步骤索引，默认 `[index-1]` |\r\n| `condition` | string | ❌ | 步骤级条件：非 `\"always\"` 时按需求值，为 `false` 则跳过本步骤 |\r\n| `failure_mode` | object | ❌ | 失败处理（见下文） |\r\n| `hook` | object | ❌ | 流程钩子（见下文），在里程碑和末尾步骤执行前自动校验 |\r\n| `notes` | string | ❌ | 备注 |\r\n\r\n---\r\n\r\n### 类型 A：`\"type\": \"skill\"`（技能调用步骤）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `skill_name` | string | ✅ | 调用的技能名称（须已安装） |\r\n| `action` | string | ✅ | 精炼动作描述（第一层执行用） |\r\n| `skill_instruction` | string | ❌ | 对应 SKILL.md 中的指令名（第二层回退用） |\r\n| `detail` | string | ❌ | 详细执行说明（第三层回退用） |\r\n| `variables` | object | ❌ | 步骤级变量映射 `{\"input\": \"{{step1.output}}\", \"output\": \"result\"}` |\r\n| `retry_policy` | object | ❌ | 重试策略（见下文） |\r\n\r\n**示例：**\r\n\r\n```json\r\n{\r\n \"index\": 1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"代码审查\",\r\n \"skill_name\": \"code-review\",\r\n \"action\": \"审查 PR #123 的代码更新\",\r\n \"skill_instruction\": \"review-pr\",\r\n \"depends_on\": [],\r\n \"condition\": \"always\",\r\n \"variables\": {\"input\": \"{{pr_number}}\", \"output\": \"review_result\"},\r\n \"retry_policy\": {\"max_retries\": 3, \"error_types\": [\"network_error\", \"timeout\"]},\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false},\r\n \"notes\": \"第一步，不依赖其他步骤\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 类型 B：`\"type\": \"loop\"`（循环步骤）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `loop.mode` | string | ✅ | `\"for_each\"` 或 `\"while\"` |\r\n| `loop.items` | string | 条件① | `for_each` 模式：表达式，求值结果为数组 |\r\n| `loop.while_condition` | string | 条件① | `while` 模式：布尔表达式，求值结果为 `true`/`false` |\r\n| `loop.loop_variable` | string | 条件② | `for_each` 模式：迭代变量名，循环体内用 `{{变量名}}` 引用当前元素 |\r\n| `loop.steps` | Step[] | ✅ | 循环体（Step 数组，递归支持 skill/loop/branch） |\r\n| `loop.max_iterations` | int | ❌ | 安全上限，默认 `10`；达到时按 `on_max_iteration` 处理 |\r\n| `loop.on_max_iteration` | string | ❌ | `\"break\"`（中止循环）或 `\"continue\"`（记录警告并继续） |\r\n\r\n> ① `for_each` 需要 `items` + `loop_variable`；`while` 需要 `while_condition`。\r\n> ② 循环体内步骤可访问 `{{loop_variable}}`（for_each）及父步骤的 `variables`。\r\n\r\n**示例 1：for_each 循环**\r\n\r\n```json\r\n{\r\n \"index\": 2,\r\n \"type\": \"loop\",\r\n \"step_name\": \"批量代码审查\",\r\n \"loop\": {\r\n \"mode\": \"for_each\",\r\n \"items\": \"{{pr_file_list}}\",\r\n \"loop_variable\": \"file\",\r\n \"steps\": [\r\n {\r\n \"index\": 2.1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"审查文件 {{file}}\",\r\n \"skill_name\": \"code-review\",\r\n \"action\": \"审查单个文件\",\r\n \"variables\": {\"input\": \"{{file}}\", \"output\": \"file_review\"}\r\n }\r\n ],\r\n \"max_iterations\": 20,\r\n \"on_max_iteration\": \"break\"\r\n },\r\n \"depends_on\": [1],\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false}\r\n}\r\n```\r\n\r\n**示例 2：while 循环**\r\n\r\n```json\r\n{\r\n \"index\": 3,\r\n \"type\": \"loop\",\r\n \"step_name\": \"重试直到成功\",\r\n \"loop\": {\r\n \"mode\": \"while\",\r\n \"while_condition\": \"{{retry_count}} < 3 && {{last_success}} == false\",\r\n \"steps\": [\r\n {\r\n \"index\": 3.1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"尝试部署\",\r\n \"skill_name\": \"deploy\",\r\n \"action\": \"执行部署\"\r\n }\r\n ],\r\n \"max_iterations\": 3,\r\n \"on_max_iteration\": \"break\"\r\n },\r\n \"failure_mode\": {\"on_exhaust\": \"abort\", \"is_milestone\": true}\r\n}\r\n```\r\n\r\n---\r\n\r\n### 类型 C：`\"type\": \"branch\"`（分支步骤）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `branch.condition` | string | ✅ | 布尔表达式，求值后为 `true` 或 `false` |\r\n| `branch.if_steps` | Step[] | ✅ | 条件为 `true` 时执行的步骤数组 |\r\n| `branch.else_steps` | Step[] | ❌ | 条件为 `false` 时执行的步骤数组（可选） |\r\n\r\n> ① `if_steps` 和 `else_steps` 均为 Step 数组，递归支持 skill / loop / branch。\r\n> ② 分支步骤本身不调用技能，仅做流程控制；`failure_mode` 作用于整个分支步骤（即 `if_steps` 全部失败时的行为）。\r\n\r\n**示例：if-else 分支**\r\n\r\n```json\r\n{\r\n \"index\": 4,\r\n \"type\": \"branch\",\r\n \"step_name\": \"按环境选择部署目标\",\r\n \"branch\": {\r\n \"condition\": \"{{env}} == 'production'\",\r\n \"if_steps\": [\r\n {\r\n \"index\": 4.1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"生产环境部署\",\r\n \"skill_name\": \"deploy\",\r\n \"action\": \"部署到生产环境\",\r\n \"variables\": {\"input\": \"production\"}\r\n }\r\n ],\r\n \"else_steps\": [\r\n {\r\n \"index\": 4.2,\r\n \"type\": \"skill\",\r\n \"step_name\": \"预发环境部署\",\r\n \"skill_name\": \"deploy\",\r\n \"action\": \"部署到预发环境\",\r\n \"variables\": {\"input\": \"staging\"}\r\n }\r\n ]\r\n },\r\n \"depends_on\": [1, 2, 3],\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": true}\r\n}\r\n```\r\n\r\n---\r\n\r\n## retry_policy（重试策略）\r\n\r\n```json\r\n{\r\n \"max_retries\": 3, // 最大重试次数（默认从配置读取，默认 3）\r\n \"error_types\": [\"file_locked\", \"network_error\", \"timeout\", \"auth_error\"]\r\n}\r\n```\r\n\r\n**错误类型说明：**\r\n\r\n| 错误类型 | 重试间隔 | 说明 |\r\n|---------|---------|------|\r\n| `file_locked` | 0 秒 | 文件占用/锁定，立即重试 |\r\n| `network_error` | 5 秒 | 网络不通/超时 |\r\n| `timeout` | 5 秒 | 执行超时 |\r\n| `auth_error` | - | 认证/权限错误，直接询问用户 |\r\n| `other` | 2 秒 | 其他错误 |\r\n\r\n---\r\n\r\n## failure_mode（失败处理模式）\r\n\r\n```json\r\n{\r\n \"on_exhaust\": \"ask\", // 重试耗尽后行为: \"ask\" | \"skip\" | \"abort\"\r\n \"is_milestone\": false // 是否为里程碑步骤（可通过通用规则自动判断）\r\n}\r\n```\r\n\r\n**on_exhaust 行为说明：**\r\n\r\n| 值 | 说明 |\r\n|-----|------|\r\n| `ask` | 重试耗尽后询问用户 |\r\n| `skip` | 跳过该步骤，继续后续步骤 |\r\n| `abort` | 中止整条调用链 |\r\n\r\n**里程碑行为：**\r\n- **里程碑步骤失败** → 无论 `on_exhaust` 配置如何，**强制中止整条链**\r\n- **里程碑步骤的 on_exhaust** → 建议设为 `abort`（validate 时会发出警告）\r\n- **非里程碑步骤失败** → 按 `on_exhaust` 配置处理（ask/skip/abort）\r\n\r\n---\r\n\r\n## Hook（流程钩子）\r\n\r\n> **v1.38.0 新增**。在里程碑步骤或末尾步骤上挂载的流程钩子，\r\n> 执行前自动校验前置步骤的预期产出物是否存在。\r\n> 缺失 → HOOK-BLOCK 阻断，不给执行。\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `expects` | string[] | ✅ | 预期文件路径列表（相对链数据目录或绝对路径）|\r\n\r\n**行为：**\r\n- **挂载位置**：执行器自动对标记为 `is_milestone=true` 的步骤和最后一步检查 hook\r\n- **检查时机**：步骤执行前，刚好前一步产出后\r\n- **路径解析**：相对路径相对于链数据目录\r\n- **阻断方式**：HOOK-BLOCK + exit(1)，与 gate 一致\r\n- **跳过检查**：使用 `--force-hooks` 参数（不推荐）\r\n\r\n**示例：**\r\n```json\r\n{\r\n \"index\": 3,\r\n \"step_name\": \"生成分析报告\",\r\n \"skill_name\": \"analysis\",\r\n \"action\": \"生成数据报告\",\r\n \"failure_mode\": {\"on_exhaust\": \"abort\", \"is_milestone\": true},\r\n \"hook\": {\r\n \"expects\": [\r\n \"output/report.pdf\",\r\n \"output/data.csv\"\r\n ]\r\n }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 类型 D：`\"type\": \"adhesion\"`（粘连点步骤）\r\n\r\n> **v1.25.0 新增**。粘连点标记调用链中无法由 skill 自动化的缺口，\r\n> 提供三种解决方案供 LLM 选择执行，保证调用链不断裂。\r\n\r\n### 通用字段（继承 Step 通用字段）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `index` | int | ✅ | 步骤序号 |\r\n| `type` | string | ✅ | 固定为 `\"adhesion\"` |\r\n| `step_name` | string | ✅ | 步骤名称 |\r\n| `depends_on` | int[] | ❌ | 依赖的前置步骤索引 |\r\n\r\n### adhesion 专用字段\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `adhesion.reason` | string | ✅ | 粘连原因描述 |\r\n| `adhesion.solutions` | array | ✅ | 解决方案数组，至少 1 个 |\r\n| `adhesion.updated_at` | string | ❌ | 最后检查时间（自愈扫描时更新） |\r\n\r\n### solutions[n] 字段\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `mode` | string | ✅ | `\"manual\"` / `\"auto\"` / `\"hybrid\"` |\r\n| `description` | string | ✅ | 执行描述 |\r\n| `constraints` | string | ❌ | 约束条件（manual/hybrid 使用） |\r\n| `tool_name` | string | 条件① | mode=auto/hybrid 时，工具名称 |\r\n| `script_path` | string | 条件① | mode=auto/hybrid 时，脚本路径（相对数据目录） |\r\n| `llm_steps` | string | 条件② | mode=hybrid 时，LLM 执行步骤 |\r\n| `tool_steps` | string | 条件② | mode=hybrid 时，工具执行步骤 |\r\n\r\n> ① auto/hybrid 模式至少提供 tool_name 或 script_path 之一\r\n> ② hybrid 模式必须同时提供 llm_steps + tool_steps\r\n\r\n### 三种 solution mode 说明\r\n\r\n| mode | 说明 | 适用场景 |\r\n|------|------|---------|\r\n| `manual` | LLM 直接手动执行步骤，不依赖脚本或新 skill | 一次性、高度灵活的判断任务 |\r\n| `auto` | 通过自调用脚本工具执行，产生的脚本入数据目录管理 | 可标准化、重复执行的任务 |\r\n| `hybrid` | LLM 描述流程步骤 + 约束 + 自调用工具协同执行 | 需要智能判断 + 自动化执行的复合任务 |\r\n\r\n### 自愈流程\r\n\r\n每次调用链执行时，AI 检查链中所有 `adhesion` 类型步骤：\r\n\r\n1. 扫描技能库（`scripts/` 目录或已安装技能）查找是否有新 skill 能填补该缺口\r\n2. 找到匹配 skill → 将 `adhesion` 步骤升级为 `skill` 类型步骤，保留原 `adhesion.solutions` 到 `notes` 字段\r\n3. 未找到 → 按 `adhesion.solutions` 中的方案执行（优先 hybrid → auto → manual）\r\n\r\n---\r\n\r\n## 条件表达式语法\r\n\r\n`condition` / `branch.condition` / `loop.while_condition` 支持以下语法：\r\n\r\n| 语法 | 示例 | 说明 |\r\n|------|------|------|\r\n| 步骤状态 | `step_1_success` | 步骤 1 成功（返回码 0） |\r\n| 步骤状态（否定） | `step_2_failed` | 步骤 2 失败 |\r\n| 变量存在 | `variable_OUTPUT_exists` | 变量 `OUTPUT` 已定义 |\r\n| 变量相等 | `{{env}} == 'production'` | 字符串比较 |\r\n| 变量数值 | `{{retry_count}} < 3` | 数值比较（`<` `>` `<=` `>=` `==` `!=`） |\r\n| 逻辑运算 | `step_1_success && step_2_success` | `&&`（与）、`||`（或）、`!`（非） |\r\n| 布尔常量 | `always` | 总是执行（默认） |\r\n| 布尔常量 | `never` | 永不执行 |\n\nFile v1.38.1:references/chain_search.md\n\n# 历史链搜索\r\n\r\n已保存的链自动成为模板，下次相似意图命中：\r\n\r\n```bash\r\nchain_manager.py search --intent \"分析数据 报告\"\r\n```\n\nFile v1.38.1:references/changelog.md\n\n## [1.38.1] - 2026-07-10\r\n\r\n### 修复\r\n- **SKILL.md 标题断裂**：3 处 `##` 标题前缺少空行导致拼接失效\r\n- **changelog.md 格式**：`---## [1.31.0]` 缺少分隔线换行\r\n- **permissions.md 重复**：删除新旧两版权限扫描结果合并的旧版冗余内容\r\n\r\n## [1.38.0] - 2026-07-03\r\n\r\n### 新增\r\n- **流程钩子系统（chain_hook.py）**：在里程碑步骤和末尾步骤上挂载 `hook.expects` 检查前置产出物\r\n - 新增 `chain_hook.py`：钩子检查引擎，支持 check/check_chain/CLI\r\n - `chain_executor.py plan` 输出显示钩子信息，`--force-hooks` 跳过\r\n - `chain_executor.py validate` 输出钩子验证结果\r\n - Step schema 新增 `hook` 字段，文档见 chain_schema.md\r\n\r\n## [1.37.3] - 2026-07-03\r\n\r\n### 修复\r\n- 修正渐进式文件索引表：移除 scripts/ 条目（索引表应仅含 references/*.md）\r\n\r\n## [1.37.2] - 2026-07-03\r\n\r\n### 修复\r\n- 修正 displayName 为 skill-sub（原错误设为 Skill Sub - 调用链编排）\r\n\r\n## [1.37.1] - 2026-07-03\r\n\r\n### 修复\r\n- 修正 1.37.0 更新日志：删除不相关的 skill-standardization 工具修复条目，仅保留 skill-sub 自身的更新\r\n\r\n## [1.37.0] - 2026-07-03\r\n\r\n### 修复\r\n- SKILL.md 文档结构标准化：触发条件章节优化（触发词改为具体操作描述，删除危险表述），工作流程格式化（列表+输入输出标注），配置表补齐，约束章节合并\r\n- 技能子命令间增加有效分隔，提升指令执行清晰度\r\n\r\n## [1.36.0] - 2026-07-03\r\n\r\n### 修复\r\n- **SKILL.md 标准化审计修复**（skill-standardization refactor）\r\n - R-17：SKILL.md 从 377 行裁剪至 160 行\r\n - R-20：changelog 术语统一\r\n - R-21：渐进式加载模板句恢复\r\n - R-23：文档-代码一致性误报分类\r\n - C-07：14 个代码块补充语言标识\r\n - C-11/C-12/C-13/C-17/C-18：章节格式、索引表、示例、边界量化修复\r\n- 扩展 step_indexer search 过期检测覆盖 chain_planner 内部搜索（--ignore-stale 兜底）\r\n\r\n---\r\n\r\n## [1.35.1] - 2026-07-03\r\n\r\n### 修复\r\n- **SKILL.md 文档脱钩修复**：\r\n - 核心能力表：新增门禁系统、蓝皮书过期检测、链私有蓝皮书基线校验、自增强闭环\r\n - 工作流程：更新为 0-9 步串行门禁阻断表\r\n - 新增门禁系统文档（chain_gate CLI + 依赖链）\r\n - 新增链私有蓝皮书文档（基线保护 + 执行前自动校验）\r\n - 新增 LLM 参数文档（--llm-chain-check / --milestones / --adhesion）\r\n - 新增自增强闭环文档（chain_manager search）\r\n - 渐进式加载约束从 ≤230 行更新为 ~380 行\r\n - 快速开始示例补全 check-health / search / gate status 等新命令\r\n\r\n---\r\n\r\n## [1.35.0] - 2026-07-03\r\n\r\n### 新增\r\n- **链执行前蓝皮书健康检查**（chain_executor.py load_chain）\r\n 每次加载链执行时自动比 blueprints.json 中的 _skill_md5s vs 当前 SKILL.md\r\n 发现基线偏移 → HOOK-BLOCK [HARD] 阻断，输出修复命令\r\n 跳过：`--force-health`\r\n\r\n### 更新\r\n- chain_executor.py plan 新增 `--force-health` 参数\r\n- chain_executor.validate 也受健康检查影响（共用 load_chain）\r\n\r\n---\r\n\r\n## [1.34.0] - 2026-07-03\r\n\r\n### 新增\r\n- **LLM 参数门禁**（chain_gate.py/chain_planner.py）：三座新增 HARD 门禁\r\n - `llm_chain_verified`：接收 `--llm-chain-check` JSON，passed=false 阻断\r\n - `milestones_set`：接收 `--milestones`（逗号分隔序号），缺值阻断\r\n - `adhesion_resolved`：接收 `--adhesion` JSON，resolved=false 阻断\r\n- **自增强模板缓存**（chain_cache.py）：参考 semantic-split 的闭环设计\r\n - `save_template()`：链规划成功时自动保存到 templates/\r\n - `scan_templates()`：n-gram 匹配（复用 step_indexer 同源算法）\r\n - `hit_template()`：相似意图命中后直接复用里程碑/步骤组合\r\n - CLI：`python chain_cache.py [list|clear|scan ]`\r\n- **chain_planner plan** 新增参数：--llm-chain-check, --milestones, --adhesion\r\n\r\n### 更新\r\n- chain_planner cmd_plan 管线新增门禁步：steps_selected → llm_chain_verified → milestones_set → io_validated → ... → adhesion_resolved → chain_connected → chain_saved\r\n\r\n---\r\n\r\n## [1.33.0] - 2026-07-03\r\n\r\n### 新增\r\n- **门禁系统**（chain_gate.py）：10 个 HARD 门禁，参考 novel-weaver pipeline_gate 架构\r\n GATE_REGISTRY 含依赖链：blueprint_verified → intent_decomposed → steps_searched → steps_selected → io_validated → chain_connected → chain_saved → chain_loaded → execution_planned → execution_completed\r\n API: check()/set_gate()/block()/reset(), 不通过则 exit(1) + HOOK-BLOCK 输出\r\n- **chain_planner 门禁集成**：cmd_plan 每步前后注入 gate.check/set/block\r\n - 第1步搜索 → set steps_searched\r\n - 第2步 LLM 选 → set steps_selected（无输入则 blocked）\r\n - 第4步校验 → set io_validated（gap 数过大则 blocked）\r\n - 第4b步 DAG → set chain_connected（不连通则 blocked）\r\n - 第5步保存 → set chain_saved（失败则 blocked）\r\n 阻断格式：HOOK-BLOCK [HARD] + 原因 + 修复命令\r\n\r\n### 更新\r\n- chain_planner.py：无 --steps 返回时 set steps_selected=blocked（标记问题，非静默退出）\r\n- chain_planner.py：搜索无结果时 gate.block 替代 print+return\r\n\r\n---\r\n\r\n### 新增\r\n- **search 过期硬检测**：搜索前自动比对所有技能的 SKILL.md 指纹与蓝皮书记录\r\n 指纹不一致 → 直接拒绝搜索，提示先更新蓝皮书\r\n 跳过检测：`--ignore-stale`\r\n\r\n### 更新\r\n- **工作流文档**：SKILL.md 明确标注蓝皮书校验为前置硬约束（第0步）\r\n 链规划串行流程：校验→理解→规划→缺口→搜索→校验→生成→调度→健康检查\r\n\r\n---\r\n\r\n## [1.32.2] - 2026-07-03\r\n\r\n### 新增\r\n- **LLM 步骤蓝皮书提取路径**：prepare-llm-input (输出 SKILL.md 供 LLM 读)\r\n- **apply-blueprint 命令**：接收+校验+保存 LLM 提取结果，含指纹记录\r\n- **validate_llm_output() 校验器**：LLM 输出结构化校验 (step_name/consumes/produces 字段)\r\n- **scan --check-fingerprint**：仅输出指纹更新列表，零更新\r\n- **文档/help 顺序**：LLM 优先，regex 兜底\r\n\r\n### 修复\r\n- **I/O 文本清洗** (skill_extractor.py)：`_clean_io_text()` 删除 `|` `**` `` ` `` 代码块碎片，80字截断\r\n- **description 清洗**：`_clean_io_text` 处理后 120字截断，替换 raw 200字\r\n- **表格行过滤**：含 `|` 或 `` ` `` 的编号步骤跳过（748→672步）\r\n- **无 ### 的 SKILL.md**：通过 LLM 提取路径覆盖（regex 无法提取的 ## / 列表格式）\r\n\r\n---\r\n\r\n## [1.32.1] - 2026-07-02\r\n\r\n### 修复\r\n- **意图分解器 Bugfix**：SEQ2 正则尾部 `.+?` 改为 `.+`（非贪婪只吞1字符导致\"分析数据后做 PPT\"拆成[\"分析数据\",\"做\"]后被长度过滤掉）\r\n- **递归拆解**：支持\"分析数据后做 PPT 然后发邮件\"→3步拆解（右侧递归）\r\n- **最左标记优先**：改用 `sep_pos`（分隔符位置）替代 `match.start()` 比较，避免多标记同起点时选错\r\n- **「最后」避险**：`(? 本文档是 SKILL.md 的渐进式补充，提供完整使用示例。\r\n\r\n---\r\n\r\n## 示例 1：创建发布流水线调用链\r\n\r\n```\r\n用户：帮我创建一条发布流水线的调用链，包含安全审计、打包、推送\r\n\r\nAI：\r\n 1. 分析意图 → 需要 skills-security-check + 内置打包 + git-sync\r\n 2. 读取技能信息 → 提取关键步骤\r\n 3. 规划步骤：\r\n 步骤1: 安全审计 → 依赖:无 → 里程碑(关键词:审计)\r\n 步骤2: 打包 → 依赖:[1] → 非里程碑\r\n 步骤3: 推送代码 → 依赖:[2] → 里程碑(最后一步)\r\n 4. 展示确认\r\n 5. [配置: naming_mode=auto] → AI 命名为 \"发布流水线\"\r\n 6. 保存\r\n```\r\n\r\n**生成的调用链 JSON：**\r\n\r\n```json\r\n{\r\n \"name\": \"发布流水线\",\r\n \"description\": \"技能发布完整流程\",\r\n \"purpose\": \"一键发布技能到 SkillHub/ClawHub\",\r\n \"user_intent\": \"帮我打包发布这个技能\",\r\n \"tags\": [\"发布\", \"技能管理\"],\r\n \"steps\": [\r\n {\r\n \"index\": 1,\r\n \"skill_name\": \"skills-security-check\",\r\n \"step_name\": \"安全审计\",\r\n \"action\": \"对技能目录执行安全审计，检查敏感信息泄露\",\r\n \"skill_instruction\": \"security-audit\",\r\n \"depends_on\": [],\r\n \"retry_policy\": {\"max_retries\": 3},\r\n \"failure_mode\": {\"on_exhaust\": \"abort\", \"is_milestone\": true}\r\n },\r\n {\r\n \"index\": 2,\r\n \"skill_name\": \"(内置)\",\r\n \"step_name\": \"打包\",\r\n \"action\": \"按规范打包为 ZIP（仅含 SKILL.md、_meta.json、scripts/*.py）\",\r\n \"depends_on\": [1],\r\n \"retry_policy\": {\"max_retries\": 3},\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false}\r\n },\r\n {\r\n \"index\": 3,\r\n \"skill_name\": \"git-sync\",\r\n \"step_name\": \"推送代码\",\r\n \"action\": \"推送到 Gitee 和 GitHub 仓库\",\r\n \"depends_on\": [2],\r\n \"retry_policy\": {\"max_retries\": 3, \"error_types\": [\"network_error\", \"timeout\"]},\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": true}\r\n }\r\n ]\r\n}\r\n```\r\n\r\n---\r\n\r\n## 示例 2：执行调用链\r\n\r\n```\r\n用户：执行发布流水线\r\n\r\nAI：\r\n 1. 生成执行计划 → 3步，2个里程碑\r\n 2. 步骤1（安全审计）→ 第一层 action → ✅成功\r\n 3. 步骤2（打包）→ 第一层 action → ❌文件占用\r\n → 分级重试: file_locked → 立即重试 → ✅成功\r\n 4. 步骤3（推送代码）→ 第一层 action → ❌网络错误\r\n → 分级重试: network_error → 5秒后重试 → ✅成功\r\n 5. 汇报: 全部 3/3 步成功\r\n```\r\n\r\n---\r\n\r\n## 示例 3：查看里程碑判断依据\r\n\r\n```\r\n用户：查看发布流水线详情\r\n\r\nAI：\r\n 📌 调用链: 发布流水线\r\n ...\r\n 📐 里程碑判断依据:\r\n ★ 步骤1(安全审计): 关键词匹配: '审计'\r\n ○ 步骤2(打包): 默认规则（非关键节点）\r\n ★ 步骤3(推送代码): 最终交付步骤\r\n```\r\n\r\n---\r\n\r\n## 示例 4：用 skill-sub 摘取步骤形成调用链\r\n\r\n> 注意：skill-sub 本身**不参与**调用链，它只负责摘取其他 skill 的步骤并形成调用链。\r\n\r\n**场景**：用户希望将\"语义理解 → 规划 → 三步循环执行 → 标准化审查\"这套流程固化为调用链。\r\n\r\n```\r\n用户：帮我创建一条\"标准化执行流水线\"调用链\r\n\r\nAI：\r\n 1. 分析意图 → 需要 semantic-split + triphasic-execution + skill-standardization\r\n 2. 读取技能信息：\r\n - semantic-split：提取关键步骤（语义拆分、规划生成）\r\n - triphasic-execution：提取三步循环步骤\r\n - skill-standardization：提取审查/改写步骤\r\n 3. 规划步骤：\r\n 步骤1: 语义理解 → 依赖:无 → 非里程碑\r\n 步骤2: 规划步骤 → 依赖:[1] → 非里程碑\r\n 步骤3: 三步循环执行 → 依赖:[2] → 里程碑\r\n 步骤4: 标准化审查 → 依赖:[3] → 里程碑(关键词:审查)\r\n 4. 展示确认\r\n 5. 保存为调用链 \"标准化执行流水线\"\r\n```\r\n\r\n**关键点**：调用链通过 `chain_manager.py` 保存为 JSON 文件，可复用，不绑定某一次具体任务。\r\n\r\n---\r\n\r\n## 使用技巧\r\n\r\n### 命名建议\r\n\r\n- **格式**：「动词+对象」（如「发布技能」「审查代码」「生成报告」）\r\n- **避免泛化名**：「通用流程」「测试链」→ 改名为「技能安全审计+发布」「用户注册流程测试」\r\n- **命名即意图**：好的名称让 `list` 一眼能看懂这条链干嘛\r\n\r\n### 里程碑配置经验\r\n\r\n| 场景 | 建议 |\r\n|------|------|\r\n| 安全/审计/部署步骤 | 必须标里程碑（失败不可接受） |\r\n| 数据生成/中间计算 | 非里程碑 + `on_exhaust: skip` |\r\n| 不确定是否关键 | 暂时非里程碑 + `on_exhaust: ask` |\r\n\r\n### 调用链生命周期\r\n\r\n1. **创建** → 命名 + 配置依赖 + 验证（`validate`）\r\n2. **试运行** → 用简单场景跑一次，看流程是否顺畅\r\n3. **调整** → 修 action 描述、调重试次数、改里程碑标记\r\n4. **复用** → 同类任务直接执行\r\n5. **清理** → 不再需要的链用 `delete --force` 删除，不用留\n\nFile v1.38.1:references/faq.md\n\n# skill-sub 常见问题\r\n\r\n> 本文档是 SKILL.md 的渐进式补充，收录常见问题与使用技巧。\r\n> 反模式详见 `references/antipatterns.md`。\r\n\r\n---\r\n\r\n## FAQ\r\n\r\n### Q1：调用链和脚本有什么区别？\r\n\r\n调用链是**声明式**的——描述\"做什么\"和\"谁来做\"，由 AI 按 action 执行。脚本是**命令式**的——精确指令序列，机器直接运行。\r\n\r\n| | 调用链 | 脚本 |\r\n|---|--------|------|\r\n| 执行者 | AI | 解释器 |\r\n| 容错 | 分级重试 + 询问 | 严格终止 |\r\n| 适用 | 跨 Skill 编排 | 单一工具链 |\r\n\r\n### Q2：如何判断一个任务该不该创建调用链？\r\n\r\n三个条件同时满足：\r\n1. 涉及 ≥2 个 Skill\r\n2. 有复用价值（不会只用一次）\r\n3. 步骤间的依赖关系可固化\r\n\r\n缺一则不适合。\r\n\r\n### Q3：调用链失败后怎么恢复？\r\n\r\n1. 查看失败步骤的 `on_exhaust` 配置\r\n2. 非里程碑 + `on_exhaust: ask` → AI 会询问你\r\n3. 非里程碑 + `on_exhaust: skip` → 已自动跳过\r\n4. 里程碑失败 → 链已中止，需修复后重新执行整条链\r\n5. 用 `chain_executor.py plan` 重新生成执行计划\r\n\r\n### Q4：配置里的\"记忆参考\"开启后有什么用？\r\n\r\n创建调用链时，AI 会额外读取 MEMORY.md 和近期日志，用于：\r\n- 个性化步骤描述（匹配你的命名习惯）\r\n- 推荐常用或相关的 Skill（基于历史使用模式）\r\n\r\n不开也不影响功能，只是步骤描述更通用。\r\n\r\n### Q5：为什么我的调用链执行时每一步都要问我？\r\n\r\n两个常见原因：\r\n1. 所有步骤配置了 `on_exhaust: ask` — 改为 `skip` 或 `abort` 减少交互\r\n2. 第1层 action 描述不够精确 — 执行时 AI 无法确定怎么做，只能问\r\n\r\n解决：创建链时确保每个 action 包含具体的动词+对象+产出。\r\n\r\n### Q6：skill-sub 的数据存在哪？更新会丢吗？\r\n\r\n数据存储在 `~/.workbuddy/skills/.standardization/skill-sub/`（可通过 `SKILL_SUB_HOME` 环境变量更新）：\r\n- `chains/` — 调用链 JSON 文件\r\n- `config.json` — 用户配置\r\n\r\n更新 skill-sub 本身（覆盖 SKILL.md + scripts/）**不会影响**数据目录。但注意这个路径不符合铁律4（产出物应在 `skills/.standardization/` 下），后续版本会迁移。\r\n\r\n---\r\n\r\n## 使用技巧\r\n\r\n1. **命名调用链要有规律** — 用「动词+对象」格式（如\"发布技能\"、\"审查代码\"），方便 `list` 时快速定位\r\n2. **action 写得越具体，执行越顺畅** — 好：「运行 `sensitive_scan.py scan ` 检查敏感信息」；差：「检查安全」\r\n3. **非里程碑步骤优先 `on_exhaust: skip`** — 减少人工介入，除非该步骤的产出被后续步骤强依赖\r\n4. **`tags` 不要随便填** — 它是自动推荐的匹配依据，填 `[\"通用\"]` 等于没填。用领域关键词：`[\"发布\",\"安全\",\"数据分析\"]`\r\n5. **定期清理不用的调用链** — `chain_manager.py list` 检查，`delete --force` 清理。链不是越多越好\r\n6. **里程碑只在\"失败不可接受\"的步骤用** — 如安全审计、部署上线。中间步骤失败通常可跳过或询问\r\n\r\n---\r\n\r\n## 常见错误场景\r\n\r\n### E1：创建链时报\"连续缺口应合并为一个粘连点\"\r\n\r\n**原因**：两个 `type: \"adhesion\"` 步骤相邻。粘连点是 skill 之间的连接器，禁止连续。\r\n\r\n**解决**：合并为一个 adhesion，用 hybrid 方案覆盖全部缺口。\r\n\r\n```json\r\n// 错误：两个连续粘连点\r\n{\"index\":2,\"type\":\"adhesion\",\"step_name\":\"审核\"},\r\n{\"index\":3,\"type\":\"adhesion\",\"step_name\":\"转换\"} // 禁止\r\n\r\n// 正确：合并为一个 hybrid 粘连点\r\n{\"index\":2,\"type\":\"adhesion\",\"step_name\":\"审核+转换\",\r\n \"adhesion\":{\"reason\":\"需要人工审核和数据格式转换\",\r\n \"solutions\":[{\"mode\":\"hybrid\",\"llm_steps\":\"人工审核\",\r\n \"tool_steps\":\"脚本转换格式\"}]}}\r\n```\r\n\r\n### E2：创建链时报\"引用的 skill 不存在\"\r\n\r\n**原因**：`skill_name` 对应的 skill 未安装或名称写错。\r\n\r\n**解决**：用 `python scripts/skill_extractor.py scan` 查看已安装 skill 列表。\r\n\r\n### E3：执行时报\"步骤失败\"\r\n\r\n| 原因 | 现象 | 解决 |\r\n|------|------|------|\r\n| action 描述模糊 | AI 反复确认 | 用具体动词+对象+产出重写 action |\r\n| 依赖的 skill 报错 | skill 本身执行失败 | 单独运行该 skill 确认 |\r\n| 里程碑步骤失败 | 整条链中止 | 修复后重新执行 |\r\n| 重试耗尽 | 超过 max_retries | 检查错误类型后修正重试 |\r\n\r\n### E4：校验器阻断保存\r\n\r\n| 阻断信息 | 原因 | 解决 |\r\n|---------|------|------|\r\n| 缺少必填字段 skill_name | skill 步骤没有指定 skill | 补充 skill_name |\r\n| 无效类型 'xxx' | type 不在 skill/loop/branch/adhesion 中 | 修正 type 字段 |\r\n| 检测到依赖闭环 | depends_on 形成循环 | 打破循环依赖 |\r\n| 索引重复 | 两个步骤相同 index | 使用 --fix 自动修复 |\n\nFile v1.38.1:references/gate.md\n\n# 门禁系统\r\n\r\n所有规划、执行操作由 **10 座 HARD 门禁** 串行阻断。门禁状态存 `data/gate_state.json`。\r\n\r\n```bash\r\n# 查看全部门禁状态\r\npython {SKILL_DIR}/scripts/chain_gate.py status\r\n# 检查单个门禁（失败则 exit(1) + HOOK-BLOCK）\r\npython {SKILL_DIR}/scripts/chain_gate.py check --name chain_connected\r\n# 强制开放（跳过阻断）\r\npython {SKILL_DIR}/scripts/chain_gate.py set --name chain_connected --status open\r\n# 重置全部门禁\r\npython {SKILL_DIR}/scripts/chain_gate.py reset\r\n```\r\n\r\n门禁依赖链（不可跳过）：\r\nblueprint_verified → intent_decomposed → steps_searched → steps_selected → llm_chain_verified → milestones_set → io_validated → adhesion_resolved → chain_connected → chain_saved → chain_loaded → execution_planned → execution_completed\n\nFile v1.38.1:references/LICENSE.md\n\nMIT License\r\n\r\nCopyright (c) 2026 [username-redacted]\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy\r\nof this software and associated documentation files (the \"Software\"), to deal\r\nin the Software without restriction, including without limitation the rights\r\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\ncopies of the Software, and to permit persons to whom the Software is\r\nfurnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in all\r\ncopies or substantial portions of the Software.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\nSOFTWARE.\n\nArchive v1.38.0: 19 files, 63396 bytes\n\nFiles: _meta.json (129b), references/adhesion.md (5777b), references/antipatterns.md (2639b), references/chain_schema.md (13542b), references/changelog.md (12162b), references/examples.md (4999b), references/faq.md (4975b), references/permissions.md (1819b), references/reference.md (6938b), references/workflow.md (10642b), scripts/chain_executor.py (23718b), scripts/chain_flow_validator.py (10430b), scripts/chain_manager.py (42348b), scripts/chain_structure_checker.py (11758b), scripts/default_config.json (194b), scripts/loop_branch_renderer.py (6717b), scripts/settings.html (10326b), skill-card.md (2895b), SKILL.md (10089b)\n\nFile v1.38.0:SKILL.md\n\n---\r\nname: skill-sub\r\nversion: 1.27.1\r\nauthor: wUwproject\r\nlicense: MIT\r\ndescription: 调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。\r\nsensitive_access: false\r\ncritical_write: false\r\npermission_weight: LOW\r\ndata_dir: ../.standardization/skill-sub/data/\r\ntags: ['chain', 'orchestration', 'usable', 'skill-builder', 'progressive-loading', 'planner', 'editor']\r\nexternal_data_dir: true\r\ntrigger: ['规划类: 帮我规划一下/步骤是什么', '顺序类: 依次执行/先...再...', '链管理: 创建/查看/更新/删除调用链']\r\ntrigger_negative: ['不使用调用链', '手动逐步执行']\r\nmeta_field_sync: true\r\nh1_position: true\r\n---\r\n# skill-sub\r\n\r\n\r\n\r\n\r\n## 触发场景\r\n\r\n**当用户提出以下意图时触发本技能：**\r\n- 规划类：「帮我规划一下...」、「...的步骤是什么」\r\n- 顺序类：「依次执行 A、B、C」、「先...再...」\r\n- 链管理：「创建/查看/更新/删除调用链」\r\n\r\n**否定条件**：仅当用户明确要求「不使用调用链」或「手动逐步执行」时，不自动触发。\r\n\r\n\r\n\r\n## 核心能力\r\n\r\n> 📚 **渐进式加载**：本技能采用渐进式 MD 体系，`SKILL.md` 为入口（≤230行），详细内容拆分到 `references/*.md` 按需加载。\r\n\r\n| # | 功能 | 说明 |\r\n|---|------|------|\r\n| 1 | **调用链管理** | 创建、查询、更新、删除调用链 |\r\n| 2 | **执行计划生成** | 生成结构化执行计划，含并行/串行标记 |\r\n| 3 | **条件执行** | 支持条件步骤，按条件判断是否执行 |\r\n| 4 | **循环与分支编排** | 支持 for-each/while 循环和 if-else 分支 |\r\n| 5 | **Dry-Run 模式** | 模拟执行，不实际调用技能 |\r\n| 6 | **链备份与版本管理** | 自动备份，支持版本恢复 |\r\n| 7 | **粘连点（Adhesion Point）** | 标记 skill 无法自动化的缺口，提供三种解决方案保证链不断；支持自愈 —— 每次执行自动扫描是否有新 skill 可填补 |\r\n\r\n---\r\n\r\n---\r\n\r\n\r\n\r\n\r\n\r\n### 渐进式文件索引\r\n\r\n| 文件名 | 位置 | 说明 |\r\n|--------|------|------|\r\n| `references/antipatterns.md` | skill-sub 反模式 | > 本文档收录 skill-sub 使用中的常见错误和正确做法。完整反模式示例见 `references/faq.md` |\r\n| `references/adhesion.md` | 粘连点机制（v1.25.0） | > 粘连点定义、三种解决方案（manual/auto/hybrid）、自愈流程 |\r\n| `references/chain_schema.md` | skill-sub 调用链数据结构 | > 本文档定义 Chain / Step / retry_policy / failure_mode 的完整结构。 |\r\n| `references/changelog.md` | skill-sub 更新日志 | - **循环步骤（Loop Step）** — `type: \"loop\"` 支持 `for_each` / `whil |\r\n| `references/examples.md` | skill-sub 使用示例 | > 本文档是 SKILL.md 的渐进式补充，提供完整使用示例。 |\r\n| `references/faq.md` | skill-sub 常见问题 | > 本文档是 SKILL.md 的渐进式补充，收录常见问题与使用技巧。 |\r\n| `references/permissions.md` | 权限说明 | 权限扫描风险等级：**MEDIUM** |\r\n| `references/reference.md` | skill-sub 参考手册 | > 本文档是 SKILL.md 的渐进式补充，包含完整 CLI 速查、脚本 API、存储格式。 |\r\n| `references/workflow.md` | skill-sub 详细工作流程 | > 本文档是 SKILL.md 的渐进式补充，详细描述执行流程、里程碑判断规则、三层回退策略。 |\r\n## 快速开始\r\n\r\n### 三步上手：创建一个最小调用链\r\n\r\n```bash\r\n# 第一步：初始化\r\npython {SKILL_DIR}/scripts/chain_manager.py init\r\n\r\n# 第二步：创建调用链（两个 skill + 一个粘连点连接）\r\npython {SKILL_DIR}/scripts/chain_manager.py create --name \"代码发布\" \\\r\n --description \"从代码分析到发布的完整流程\" \\\r\n --steps '[\r\n {\"index\":1,\"type\":\"skill\",\"step_name\":\"代码审查\",\"skill_name\":\"code-review\",\"action\":\"审查PR\"},\r\n {\"index\":2,\"type\":\"adhesion\",\"step_name\":\"审批发布\",\"adhesion\":{\"reason\":\"发布审批需要人工决策\",\"solutions\":[{\"mode\":\"manual\",\"description\":\"人工审批发布申请\"}]}},\r\n {\"index\":3,\"type\":\"skill\",\"step_name\":\"部署\",\"skill_name\":\"deploy\",\"action\":\"部署到生产环境\"}\r\n ]'\r\n\r\n# 第三步：生成执行计划\r\npython {SKILL_DIR}/scripts/chain_executor.py plan --name \"代码发布\" --verbose\r\n```\r\n\r\n> 💡 **小贴士**：创建时如果步骤有 ERROR，会提示具体原因（如\"连续缺口应合并为一个粘连点\"），按提示修正后重试即可。\r\n\r\n### 更多命令\r\n\r\n```bash\r\n# Dry-Run 模拟执行（不实际调用技能）\r\npython {SKILL_DIR}/scripts/chain_executor.py plan --name \"代码发布\" --dry-run\r\n\r\n# 查看调用链详情\r\npython {SKILL_DIR}/scripts/chain_manager.py show --name \"代码发布\"\r\n\r\n# 列出所有调用链\r\npython {SKILL_DIR}/scripts/chain_manager.py list\r\n\r\n# 删除（自动备份）\r\npython {SKILL_DIR}/scripts/chain_manager.py delete --name \"代码发布\" --force\r\n```\r\n\r\n---\r\n\r\n\r\n\r\n## 工作流程\r\n\r\n1. **理解意图** → 分析用户输入，判断是否需要调用链\r\n2. **规划技能顺序** → 推荐参与的 Skill 及其顺序\r\n3. **流程缺口分析** → 检查技能衔接处是否存在语义/流程/决策缺口，在天然断裂处打粘连点（**禁止随意添加**）\r\n4. **生成调用链** → 创建 JSON 格式的调用链定义（含 skill 步骤和 adhesion 步骤）。如有定时/自动化意图，**必须** 附带 `--schedule` 参数\r\n5. **立即注册调度** → 链创建成功且带 `schedule` 时，AI **必须当场**完成注册。定时任务不等手动执行，不存在\"等下次执行时再注册\"的可能\r\n6. **生成执行计划** → 输出 AI 可直接执行的指令序列\r\n7. **（可选）实际执行** → 按执行计划逐步调用技能\r\n\r\n---\r\n\r\n\r\n### 循环与分支编排\r\n\r\n### for-each 循环\r\n\r\n在调用链 JSON 中，将某步骤的 `type` 设为 `\"loop\"`，并定义 `loop` 对象：\r\n\r\n```json\r\n{\r\n \"type\": \"loop\",\r\n \"step_name\": \"批量处理文件\",\r\n \"loop\": {\r\n \"mode\": \"for_each\",\r\n \"items\": \"{{file_list}}\",\r\n \"loop_variable\": \"f\",\r\n \"max_iterations\": 10,\r\n \"steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"file-ops\", \"step_name\": \"处理单个文件\", \"action\": \"处理 {{f}}\"}\r\n ]\r\n }\r\n}\r\n```text\r\n\r\n### while 循环\r\n\r\n```json\r\n{\r\n \"type\": \"loop\",\r\n \"step_name\": \"重试直到成功\",\r\n \"loop\": {\r\n \"mode\": \"while\",\r\n \"while_condition\": \"{{retry_count}} < 3 and {{last_result}} != 'success'\",\r\n \"max_iterations\": 3,\r\n \"steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"api-call\", \"step_name\": \"调用接口\", \"action\": \"重试第 {{retry_count}} 次\"}\r\n ]\r\n }\r\n}\r\n```text\r\n\r\n### if-else 分支\r\n\r\n```json\r\n{\r\n \"type\": \"branch\",\r\n \"step_name\": \"按环境部署\",\r\n \"branch\": {\r\n \"condition\": \"{{env}} == 'prod'\",\r\n \"if_steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"deploy\", \"step_name\": \"生产部署\", \"action\": \"部署到生产环境\"}\r\n ],\r\n \"else_steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"deploy\", \"step_name\": \"预发部署\", \"action\": \"部署到预发环境\"}\r\n ]\r\n }\r\n}\r\n```\r\n\r\n> 📚 完整 schema 详见 `references/chain_schema.md`\r\n\r\n---\r\n\r\n\r\n\r\n## 能力边界与限制\r\n\r\n### 适宜场景 ✅\r\n\r\n| 场景 | 说明 |\r\n|------|------|\r\n| 多 skill 编排 | 涉及 2 个及以上 skill，步骤间有明确依赖关系 |\r\n| 可固化流程 | 流程稳定、可复现，不是一次性操作 |\r\n| 跨步骤衔接 | skill 之间需要数据转换、人工审批、流程补全 |\r\n\r\n### 不适宜场景 ❌\r\n\r\n| 场景 | 原因 |\r\n|------|------|\r\n| 单 skill 任务 | 直接调 skill 本身即可，不需要调用链 |\r\n| 一次性操作 | 调用链的价值在于复用，一次性工作不值得建链 |\r\n| 无依赖的并行任务 | 多个独立任务应并行执行，不需要编排 |\r\n| 高度动态的流程 | 每次执行步骤都不一样，粘连点也解决不了，直接 AI 手动处理 |\r\n\r\n### 硬限制\r\n\r\n| 限制项 | 值 | 说明 |\r\n|--------|-----|------|\r\n| 最大步骤数 | 30 层（含嵌套） | 超过后校验器会告警，但不阻断执行 |\r\n| 粘连点占比 | 30% | 超过告警，建议合并或补充 skill |\r\n| 粘连点连续 | **禁止** | 连续缺口合并为一个粘连点 |\r\n| 依赖深度 | 10 层 | 过深依赖链难以维护和排查 |\r\n| 循环最大迭代 | 默认 10，可配置 | 超过按 on_max_iteration 处理 |\r\n\r\n### 常见创建错误速查\r\n\r\n| 报错信息 | 原因 | 解决方法 |\r\n|---------|------|---------|\r\n| 连续缺口应合并为一个粘连点 | 两个 adhesion 步骤相邻 | 合并为一个 adhesion，用 hybrid 方案覆盖全部缺口 |\r\n| 粘连点占比超过 30% | adhesion 步骤太多 | 检查是否有 skill 可以替代 |\r\n| 缺少 solutions | adhesion 步骤没有提供方案 | 至少加一个 manual 方案 |\r\n| 依赖不存在的步骤 | depends_on 引用了无效索引 | 检查依赖步骤的 index 是否正确 |\r\n| 引用的 skill 不存在 | skill_name 对应的 skill 未安装 | 检查 skill 名称是否正确 |\r\n| 检测到定时/自动化意图，但未提供 --schedule | 描述中含\"每天/每周/定时\"等词但没给调度配置 | 添加 --schedule 参数，或移除描述中的时间相关词 |\r\n\r\n> **强制规则**：用户描述中包含定时/自动化意图（如\"每天\"、\"每周\"、\"自动执行\"等）时，**必须**提供 `--schedule` 参数配置调度信息，否则链创建被拦截。不依赖 AI 自觉判断。\r\n\r\n## 配置\r\n\r\n配置界面：`python {SKILL_DIR}/scripts/settings.py`\r\n\r\n| 配置项 | 选项 | 说明 |\r\n|--------|------|------|\r\n| **记忆参考** | 是 / 否 | 创建/执行调用链时，是否读取用户记忆文件增强步骤描述 |\r\n| **命名方式** | 自动 / 人工 | 创建调用链时，由 AI 自动命名还是询问用户 |\r\n| **默认重试次数** | 1-10（默认3） | 所有步骤的默认最大重试次数 |\r\n\r\n---\n\nFile v1.38.0:_meta.json\n\n{\n \"ownerId\": \"kn75zfd51df61ajdyqtgvrs1hx84s4q6\",\n \"slug\": \"skill-sub\",\n \"version\": \"1.38.0\",\n \"publishedAt\": 1783048619053\n}\n\nFile v1.38.0:references/adhesion.md\n\n# 粘连点（Adhesion Point）机制\n\n> **v1.25.0 新增**。粘连点是调用链中无法由 skill 自动化的缺口标记。\n\n---\n\n## 什么是粘连点\n\n粘连点是调用链中一个特殊类型的步骤（`type: \"adhesion\"`），标记该位置无法由任何已安装 skill 自动完成。它不会阻断调用链，而是提供三种解决方案供 LLM 选择。\n\n### 什么时候产生粘连点\n\n| 场景 | 触发条件 | 行为 |\n|------|---------|------|\n| **链修正** | 执行链时发现步骤与真实 skill 不符，修正后仍报错 | 在该步骤位置打粘连点 |\n| **链缺口** | 规划链时某步骤无对应 skill 可用 | 在缺失位置插入粘连点 |\n| **流程缺口分析** | 规划阶段发现语义/流程/决策缺口 | 在天然断裂处打粘连点（见下方规则） |\n\n### 三个核心原则\n\n1. **链不断** — 粘连点标记不阻断调用链执行，LLM 按方案继续\n2. **连接器，非替代品** — 粘连点是两个 skill 步骤之间的连接器，不是 skill 步骤的替代品。**禁止粘连点连粘连点**，连续缺口合并为一个粘连点\n3. **不创建 Skill** — 解决方案是步骤描述级别，产生的脚本/产出物归数据目录管理\n4. **自愈** — 每次使用含粘连点的链，主动检查是否有新 skill 可填补\n\n---\n\n## 缺口分析规则（规划阶段）\n\n在创建调用链的步骤 3→4 之间插入流程缺口分析，按以下规则判断：\n\n### 三种真实缺口\n\n| 缺口类型 | 判断依据 | 应打粘连点？ | 方案优先级 |\n|---------|---------|------------|-----------|\n| **语义缺口** | Skill A 输出格式/内容 ≠ Skill B 期望输入 | ✅ 数据转换步骤 | hybrid |\n| **流程缺口** | 用户任务中的某个环节无任何 skill 覆盖 | ✅ 补充缺失步骤 | auto / manual |\n| **决策缺口** | 需要人工审批、判断、签字的节点 | ✅ 人工审批节点 | manual |\n| **自然衔接** | Skill A 输出可直接作为 Skill B 输入 | ❌ 不打 | — |\n\n### 禁止行为\n\n| 禁令 | 说明 |\n|------|------|\n| ❌ 不要制造缺口 | 自然衔接的 skill 不打粘连点 |\n| ❌ 不要粘连点连粘连点 | **连续缺口合并为一个粘连点** |\n| ❌ 不要替代 skill | 能用 skill 完成的直接用 skill |\n| ❌ 不要过度粘连 | 粘连点数量应远少于 skill 步骤数 |\n\n### 判定示例\n\n```text\n用户需求：分析代码 → 生成报告 → 发送邮件\n\n✓ 正确：\n 步骤1: code-analysis (skill) — 分析代码\n 步骤2: report-generation (adhesion) — JSON→Markdown 语义缺口\n 步骤3: email-send (skill) — 发送邮件\n\n✓ 连续缺口合并：\n 步骤1: code-analysis (skill)\n → 步骤2: data-cleanup (缺失) — 两个连续缺失合并为一个粘连点\n → 步骤3: transform (缺失) — 🔴 禁止！应为：\n 步骤2: data-pipeline (adhesion, hybrid) — 覆盖清洗+转换的完整缺口\n 步骤3: email-send (skill)\n\n✗ 过度粘连：\n 步骤1: code-analysis (skill)\n 步骤2: report-generation (adhesion) — ❌ 如果有 report skill 就不该打\n 步骤3: email-send (skill)\n\n✗ 粘连点连粘连点（禁止）：\n 步骤1: code-analysis (skill)\n 步骤2: manual-review (adhesion) — ❌ 连续两个粘连点\n 步骤3: data-transform (adhesion) — ❌ 应合并为一个\n 步骤4: email-send (skill)\n```\n\n---\n\n## 三种解决方案\n\n### ① 纯手工（manual）\n\nLLM 直接手动执行步骤，不依赖脚本或新 skill。\n\n```json\n{\"mode\": \"manual\", \"description\": \"人工审核报告\", \"constraints\": \"需关注数据准确性\"}\n```\n\n**适用场景**：一次性、高度灵活的判断任务。\n\n### ② 脚本化（auto）\n\n通过自调用脚本工具执行，产生的脚本入数据目录管理。\n\n```json\n{\"mode\": \"auto\", \"tool_name\": \"report-verify\", \"script_path\": \"scripts/verify.sh\"}\n```\n\n**适用场景**：可标准化、重复执行的任务。\n\n### ③ 混合（hybrid）\n\nLLM 描述流程步骤 + 约束 + 自调用工具协同执行。\n\n```json\n{\n \"mode\": \"hybrid\",\n \"llm_steps\": \"LLM 阅读报告并给出审核意见\",\n \"tool_steps\": \"脚本验证报告中的数字准确性\",\n \"integration\": \"LLM 分析文本，工具验证数字\"\n}\n```\n\n**适用场景**：需要智能判断 + 自动化执行的复合任务。\n\n---\n\n## 执行优先级\n\nAI 执行粘连点步骤时，按以下优先级选择方案：\n\n1. **hybrid** — 最优先，组合 LLM + 工具的最大能力\n2. **auto** — 次优先，能脚本化就不手动\n3. **manual** — 兜底，LLM 直接执行\n\n---\n\n## 自愈机制\n\n每次加载含粘连点的调用链时，AI 执行自愈检查：\n\n```\n1. 扫描 skill 库（skill-sub 所在目录的兄弟目录）\n2. 对每个粘连点，用 adhesion.reason 关键词搜索 SKILL.md\n3. 找到匹配 → 将 adhesion 步骤升级为 skill 步骤\n - type 改为 \"skill\"\n - 填充 skill_name / action\n - 原 adhesion.solutions 写入 notes\n4. 未找到 → 按原有 3 方案执行\n```\n\n也可手动触发：`python chain_manager.py check-gaps`\n\n---\n\n## 与 chain_executor 集成\n\n`chain_executor.py` 在执行计划中渲染粘连点步骤：\n\n```text\n### 步骤 3.5: 报告审核\n⚠️ 粘连点 — 原因：缺少对应 skill 的自动化能力\n 方案1 [混合]：LLM 审核 + 脚本验证\n LLM: 阅读报告并给出审核意见\n 工具: 脚本验证报告中的数字准确性\n 方案2 [纯手工]：完全由 LLM 手工审核报告\n```\n\n---\n\n## 数据目录\n\n粘连点相关的脚本和产出物存放在以下位置，遵循 skill-sub 的数据目录规范：\n\n```\n.standardization/skill-sub/data/\n├── outputs/ # 脚本化方案产生的输出\n└── scripts/ # 自调用工具脚本（auto/hybrid 模式）\n```\n\nFile v1.38.0:references/antipatterns.md\n\n# skill-sub 反模式\r\n\r\n> 本文档收录 skill-sub 使用中的常见错误和正确做法。完整反模式示例见 `references/faq.md`。\r\n\r\n---\r\n\r\n## AP-01：把 skill-sub 编入调用链\r\n\r\n**错误做法：**创建调用链时把 `skill-sub` 作为一个步骤加入。\r\n\r\n```\r\n步骤1: skill-sub → 规划\r\n步骤2: xxx\r\n```\r\n\r\n**为什么错：**skill-sub 是编辑器/规划器，不是执行器。链需要的是\"谁干活\"，skill-sub 不干活。\r\n\r\n**正确做法：**调用链只包含执行型 Skill（如 semantic-split、git-sync），不包含 skill-sub 本身。\r\n\r\n---\r\n\r\n## AP-02：为一次性任务创建调用链\r\n\r\n**错误做法：**用户说「帮我查一下今天天气」，就创建一个\"天气查询\"调用链。\r\n\r\n**为什么错：**调用链的价值是复用。一次性任务下次不会用到，反而积累垃圾链。\r\n\r\n**正确做法：**判断任务是否有复用价值。以下信号表明值得创建链：\r\n- 用户说「每次」「以后也」「下次」\r\n- 涉及 ≥3 个 Skill 协作\r\n- 有明确的输入→输出模式\r\n\r\n---\r\n\r\n## AP-03：跳过摘取阶段，直接写 action\r\n\r\n**错误做法：**不读目标 Skill 的 SKILL.md，凭记忆写 action 描述。\r\n\r\n```json\r\n{\"action\": \"执行安全审计\"} // 太模糊，实际执行时不知道具体做什么\r\n```\r\n\r\n**为什么错：**action 是执行时的唯一指引。不读 Skill 原文会导致遗漏关键步骤或用错指令名。\r\n\r\n**正确做法：**执行阶段2摘取——读取目标 Skill 的 SKILL.md「工作流程」章节，摘取步骤名+关键动作+指令名。action 要包含具体的**做什么**（动词+对象+产出）。\r\n\r\n---\r\n\r\n## AP-04：把所有步骤都标为里程碑\r\n\r\n**错误做法：**3 步的链，全标 `is_milestone: true`。\r\n\r\n**为什么错：**里程碑=失败即中止。全标等于没有区分，任何一步失败都中止，丧失灵活性。\r\n\r\n**正确做法：**用里程碑判断规则（关键词/瓶颈点/最终交付）自动判断，只对关键步骤标里程碑。非关键步骤用 `on_exhaust: ask` 或 `skip` 而非 `abort`。\r\n\r\n---\r\n\r\n## AP-05：依赖关系写错导致链无法执行\r\n\r\n**错误做法：**\r\n```json\r\n{\"index\": 1, \"depends_on\": []},\r\n{\"index\": 2, \"depends_on\": [3]}, // 依赖了后面的步骤！\r\n{\"index\": 3, \"depends_on\": [1]}\r\n```\r\n\r\n**为什么错：**步骤2依赖步骤3，但步骤3在步骤2之后执行——死锁。\r\n\r\n**正确做法：**`depends_on` 只能引用 `index` 小于自己的步骤。创建后用 `chain_executor.py validate` 检查。\r\n\r\n---\r\n\r\n> 更多反模式与正确做法 → `references/faq.md`\n\nFile v1.38.0:references/chain_schema.md\n\n# skill-sub 调用链数据结构\r\n\r\n> 本文档定义 Chain / Step / retry_policy / failure_mode 的完整结构。\r\n>\r\n> **v1.20.0 新增**：Step 支持三种类型（skill / loop / branch），详见 Step 扩展类型章节。\r\n\r\n---\r\n\r\n## Chain（调用链）\r\n\r\n```json\r\n{\r\n \"name\": \"string\", // 唯一名称\r\n \"description\": \"string\", // 调用链描述\r\n \"purpose\": \"string\", // 核心目的\r\n \"user_intent\": \"string\", // 用户原始意图（用于意图匹配）\r\n \"tags\": [\"string\"], // 标签（用于自动匹配）\r\n \"auto_safe\": true, // 链是否可不经人工介入全自动执行（由 flow_validator 自动计算）\r\n \"user_specified\": false, // 用户是否显式指定了所有 skill（true→自愈时跳过）\r\n \"schedule\": null, // 调度配置（可选），见下方 Schedule 定义\r\n \"created_at\": \"datetime\",\r\n \"updated_at\": \"datetime\",\r\n \"exec_count\": 0, // 执行次数\r\n \"steps\": [ ... ] // Step 数组，见下文\r\n}\r\n```\r\n\r\n---\r\n\r\n## Schedule（调度配置）\r\n\r\n> 链的调度元数据，任何平台可据此创建定时任务。不绑定具体平台。\r\n\r\n```json\r\n{\r\n \"type\": \"cron\", // \"cron\" | \"interval\" | \"once\"\r\n \"expression\": \"0 6 * * *\", // cron 表达式 / 间隔秒数 / 触发时间\r\n \"description\": \"每天早上6点执行\", // 自然语言描述\r\n \"registered\": false // 是否已在平台注册（创建时为 false，注册后改为 true）\r\n}\r\n```\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `type` | string | ✅ | `\"cron\"`（cron 表达式）、`\"interval\"`（间隔秒数）、`\"once\"`（单次执行） |\r\n| `expression` | string | ✅ | cron 格式（如 `\"0 6 * * *\"`）或间隔秒数（如 `\"86400\"`）或 ISO 时间（如 `\"2026-06-03T06:00:00\"`） |\r\n| `description` | string | ❌ | 自然语言描述，便于跨平台理解 |\r\n| `registered` | bool | ❌ | 注册标记。创建时默认 `false`，平台注册后改为 `true` |\r\n\r\n### 注册流程\r\n\r\n1. 链创建时 `schedule.registered = false`\r\n2. `chain_executor.py plan` 检测到 `registered == false` 时，在计划顶部输出 **强制注册提醒**\r\n3. 平台读取 `schedule` 字段，完成注册后将 `registered` 置为 `true`\r\n4. 已注册的链 `plan` 输出不再显示注册提醒\r\n\r\n### type 说明\r\n\r\n| type | expression 示例 | 含义 |\r\n|------|----------------|------|\r\n| `cron` | `\"0 6 * * *\"` | 每天早上 6 点 |\r\n| `cron` | `\"0 0 * * 1\"` | 每周一零点 |\r\n| `cron` | `\"0 0 1 * *\"` | 每月 1 日零点 |\r\n| `interval` | `\"3600\"` | 每小时执行一次 |\r\n| `interval` | `\"86400\"` | 每天执行一次 |\r\n| `once` | `\"2026-06-03T06:00:00\"` | 2026年6月3日6点执行一次 |\r\n\r\n### 使用方式\r\n\r\n- **创建链时**：用户在意图中描述定时需求（如「每天早上6点跑这个链」），AI 自动填充 `schedule` 字段\r\n- **已有链**：通过 `chain_manager.py schedule --name <链名> --cron \"0 6 * * *\" --desc \"每天6点\"` 添加/修改\r\n- **平台侧**：读取 `chain_data.schedule`，按 `type` + `expression` 注册定时任务\r\n\r\n---\r\n\r\n## Step（步骤）\r\n\r\n> **步骤类型**：通过 `type` 字段区分技能调用、循环、分支。默认 `type: \"skill\"`。\r\n> `steps` / `if_steps` / `else_steps` 均为 Step 数组，支持递归嵌套。\r\n\r\n### 通用字段（所有类型均含）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `index` | int | ✅ | 步骤序号（从 1 开始，全局唯一） |\r\n| `type` | string | ✅ | `\"skill\"` / `\"loop\"` / `\"branch\"` |\r\n| `step_name` | string | ✅ | 步骤名称（展示用） |\r\n| `depends_on` | int[] | ❌ | 依赖的前置步骤索引，默认 `[index-1]` |\r\n| `condition` | string | ❌ | 步骤级条件：非 `\"always\"` 时按需求值，为 `false` 则跳过本步骤 |\r\n| `failure_mode` | object | ❌ | 失败处理（见下文） |\r\n| `notes` | string | ❌ | 备注 |\r\n\r\n---\r\n\r\n### 类型 A：`\"type\": \"skill\"`（技能调用步骤）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `skill_name` | string | ✅ | 调用的技能名称（须已安装） |\r\n| `action` | string | ✅ | 精炼动作描述（第一层执行用） |\r\n| `skill_instruction` | string | ❌ | 对应 SKILL.md 中的指令名（第二层回退用） |\r\n| `detail` | string | ❌ | 详细执行说明（第三层回退用） |\r\n| `variables` | object | ❌ | 步骤级变量映射 `{\"input\": \"{{step1.output}}\", \"output\": \"result\"}` |\r\n| `retry_policy` | object | ❌ | 重试策略（见下文） |\r\n\r\n**示例：**\r\n\r\n```json\r\n{\r\n \"index\": 1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"代码审查\",\r\n \"skill_name\": \"code-review\",\r\n \"action\": \"审查 PR #123 的代码更新\",\r\n \"skill_instruction\": \"review-pr\",\r\n \"depends_on\": [],\r\n \"condition\": \"always\",\r\n \"variables\": {\"input\": \"{{pr_number}}\", \"output\": \"review_result\"},\r\n \"retry_policy\": {\"max_retries\": 3, \"error_types\": [\"network_error\", \"timeout\"]},\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false},\r\n \"notes\": \"第一步，不依赖其他步骤\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 类型 B：`\"type\": \"loop\"`（循环步骤）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `loop.mode` | string | ✅ | `\"for_each\"` 或 `\"while\"` |\r\n| `loop.items` | string | 条件① | `for_each` 模式：表达式，求值结果为数组 |\r\n| `loop.while_condition` | string | 条件① | `while` 模式：布尔表达式，求值结果为 `true`/`false` |\r\n| `loop.loop_variable` | string | 条件② | `for_each` 模式：迭代变量名，循环体内用 `{{变量名}}` 引用当前元素 |\r\n| `loop.steps` | Step[] | ✅ | 循环体（Step 数组，递归支持 skill/loop/branch） |\r\n| `loop.max_iterations` | int | ❌ | 安全上限，默认 `10`；达到时按 `on_max_iteration` 处理 |\r\n| `loop.on_max_iteration` | string | ❌ | `\"break\"`（中止循环）或 `\"continue\"`（记录警告并继续） |\r\n\r\n> ① `for_each` 需要 `items` + `loop_variable`；`while` 需要 `while_condition`。\r\n> ② 循环体内步骤可访问 `{{loop_variable}}`（for_each）及父步骤的 `variables`。\r\n\r\n**示例 1：for_each 循环**\r\n\r\n```json\r\n{\r\n \"index\": 2,\r\n \"type\": \"loop\",\r\n \"step_name\": \"批量代码审查\",\r\n \"loop\": {\r\n \"mode\": \"for_each\",\r\n \"items\": \"{{pr_file_list}}\",\r\n \"loop_variable\": \"file\",\r\n \"steps\": [\r\n {\r\n \"index\": 2.1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"审查文件 {{file}}\",\r\n \"skill_name\": \"code-review\",\r\n \"action\": \"审查单个文件\",\r\n \"variables\": {\"input\": \"{{file}}\", \"output\": \"file_review\"}\r\n }\r\n ],\r\n \"max_iterations\": 20,\r\n \"on_max_iteration\": \"break\"\r\n },\r\n \"depends_on\": [1],\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false}\r\n}\r\n```\r\n\r\n**示例 2：while 循环**\r\n\r\n```json\r\n{\r\n \"index\": 3,\r\n \"type\": \"loop\",\r\n \"step_name\": \"重试直到成功\",\r\n \"loop\": {\r\n \"mode\": \"while\",\r\n \"while_condition\": \"{{retry_count}} < 3 && {{last_success}} == false\",\r\n \"steps\": [\r\n {\r\n \"index\": 3.1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"尝试部署\",\r\n \"skill_name\": \"deploy\",\r\n \"action\": \"执行部署\"\r\n }\r\n ],\r\n \"max_iterations\": 3,\r\n \"on_max_iteration\": \"break\"\r\n },\r\n \"failure_mode\": {\"on_exhaust\": \"abort\", \"is_milestone\": true}\r\n}\r\n```\r\n\r\n---\r\n\r\n### 类型 C：`\"type\": \"branch\"`（分支步骤）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `branch.condition` | string | ✅ | 布尔表达式，求值后为 `true` 或 `false` |\r\n| `branch.if_steps` | Step[] | ✅ | 条件为 `true` 时执行的步骤数组 |\r\n| `branch.else_steps` | Step[] | ❌ | 条件为 `false` 时执行的步骤数组（可选） |\r\n\r\n> ① `if_steps` 和 `else_steps` 均为 Step 数组，递归支持 skill / loop / branch。\r\n> ② 分支步骤本身不调用技能，仅做流程控制；`failure_mode` 作用于整个分支步骤（即 `if_steps` 全部失败时的行为）。\r\n\r\n**示例：if-else 分支**\r\n\r\n```json\r\n{\r\n \"index\": 4,\r\n \"type\": \"branch\",\r\n \"step_name\": \"按环境选择部署目标\",\r\n \"branch\": {\r\n \"condition\": \"{{env}} == 'production'\",\r\n \"if_steps\": [\r\n {\r\n \"index\": 4.1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"生产环境部署\",\r\n \"skill_name\": \"deploy\",\r\n \"action\": \"部署到生产环境\",\r\n \"variables\": {\"input\": \"production\"}\r\n }\r\n ],\r\n \"else_steps\": [\r\n {\r\n \"index\": 4.2,\r\n \"type\": \"skill\",\r\n \"step_name\": \"预发环境部署\",\r\n \"skill_name\": \"deploy\",\r\n \"action\": \"部署到预发环境\",\r\n \"variables\": {\"input\": \"staging\"}\r\n }\r\n ]\r\n },\r\n \"depends_on\": [1, 2, 3],\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": true}\r\n}\r\n```\r\n\r\n---\r\n\r\n## retry_policy（重试策略）\r\n\r\n```json\r\n{\r\n \"max_retries\": 3, // 最大重试次数（默认从配置读取，默认 3）\r\n \"error_types\": [\"file_locked\", \"network_error\", \"timeout\", \"auth_error\"]\r\n}\r\n```\r\n\r\n**错误类型说明：**\r\n\r\n| 错误类型 | 重试间隔 | 说明 |\r\n|---------|---------|------|\r\n| `file_locked` | 0 秒 | 文件占用/锁定，立即重试 |\r\n| `network_error` | 5 秒 | 网络不通/超时 |\r\n| `timeout` | 5 秒 | 执行超时 |\r\n| `auth_error` | - | 认证/权限错误，直接询问用户 |\r\n| `other` | 2 秒 | 其他错误 |\r\n\r\n---\r\n\r\n## failure_mode（失败处理模式）\r\n\r\n```json\r\n{\r\n \"on_exhaust\": \"ask\", // 重试耗尽后行为: \"ask\" | \"skip\" | \"abort\"\r\n \"is_milestone\": false // 是否为里程碑步骤（可通过通用规则自动判断）\r\n}\r\n```\r\n\r\n**on_exhaust 行为说明：**\r\n\r\n| 值 | 说明 |\r\n|-----|------|\r\n| `ask` | 重试耗尽后询问用户 |\r\n| `skip` | 跳过该步骤，继续后续步骤 |\r\n| `abort` | 中止整条调用链 |\r\n\r\n**里程碑行为：**\r\n- **里程碑步骤失败** → 无论 `on_exhaust` 配置如何，**强制中止整条链**\r\n- **里程碑步骤的 on_exhaust** → 建议设为 `abort`（validate 时会发出警告）\r\n- **非里程碑步骤失败** → 按 `on_exhaust` 配置处理（ask/skip/abort）\r\n\r\n---\r\n\r\n## 类型 D：`\"type\": \"adhesion\"`（粘连点步骤）\r\n\r\n> **v1.25.0 新增**。粘连点标记调用链中无法由 skill 自动化的缺口，\r\n> 提供三种解决方案供 LLM 选择执行，保证调用链不断裂。\r\n\r\n### 通用字段（继承 Step 通用字段）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `index` | int | ✅ | 步骤序号 |\r\n| `type` | string | ✅ | 固定为 `\"adhesion\"` |\r\n| `step_name` | string | ✅ | 步骤名称 |\r\n| `depends_on` | int[] | ❌ | 依赖的前置步骤索引 |\r\n\r\n### adhesion 专用字段\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `adhesion.reason` | string | ✅ | 粘连原因描述 |\r\n| `adhesion.solutions` | array | ✅ | 解决方案数组，至少 1 个 |\r\n| `adhesion.updated_at` | string | ❌ | 最后检查时间（自愈扫描时更新） |\r\n\r\n### solutions[n] 字段\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `mode` | string | ✅ | `\"manual\"` / `\"auto\"` / `\"hybrid\"` |\r\n| `description` | string | ✅ | 执行描述 |\r\n| `constraints` | string | ❌ | 约束条件（manual/hybrid 使用） |\r\n| `tool_name` | string | 条件① | mode=auto/hybrid 时，工具名称 |\r\n| `script_path` | string | 条件① | mode=auto/hybrid 时，脚本路径（相对数据目录） |\r\n| `llm_steps` | string | 条件② | mode=hybrid 时，LLM 执行步骤 |\r\n| `tool_steps` | string | 条件② | mode=hybrid 时，工具执行步骤 |\r\n\r\n> ① auto/hybrid 模式至少提供 tool_name 或 script_path 之一\r\n> ② hybrid 模式必须同时提供 llm_steps + tool_steps\r\n\r\n### 三种 solution mode 说明\r\n\r\n| mode | 说明 | 适用场景 |\r\n|------|------|---------|\r\n| `manual` | LLM 直接手动执行步骤，不依赖脚本或新 skill | 一次性、高度灵活的判断任务 |\r\n| `auto` | 通过自调用脚本工具执行，产生的脚本入数据目录管理 | 可标准化、重复执行的任务 |\r\n| `hybrid` | LLM 描述流程步骤 + 约束 + 自调用工具协同执行 | 需要智能判断 + 自动化执行的复合任务 |\r\n\r\n### 自愈流程\r\n\r\n每次调用链执行时，AI 检查链中所有 `adhesion` 类型步骤：\r\n\r\n1. 扫描技能库（`scripts/` 目录或已安装技能）查找是否有新 skill 能填补该缺口\r\n2. 找到匹配 skill → 将 `adhesion` 步骤升级为 `skill` 类型步骤，保留原 `adhesion.solutions` 到 `notes` 字段\r\n3. 未找到 → 按 `adhesion.solutions` 中的方案执行（优先 hybrid → auto → manual）\r\n\r\n---\r\n\r\n## 条件表达式语法\r\n\r\n`condition` / `branch.condition` / `loop.while_condition` 支持以下语法：\r\n\r\n| 语法 | 示例 | 说明 |\r\n|------|------|------|\r\n| 步骤状态 | `step_1_success` | 步骤 1 成功（返回码 0） |\r\n| 步骤状态（否定） | `step_2_failed` | 步骤 2 失败 |\r\n| 变量存在 | `variable_OUTPUT_exists` | 变量 `OUTPUT` 已定义 |\r\n| 变量相等 | `{{env}} == 'production'` | 字符串比较 |\r\n| 变量数值 | `{{retry_count}} < 3` | 数值比较（`<` `>` `<=` `>=` `==` `!=`） |\r\n| 逻辑运算 | `step_1_success && step_2_success` | `&&`（与）、`||`（或）、`!`（非） |\r\n| 布尔常量 | `always` | 总是执行（默认） |\r\n| 布尔常量 | `never` | 永不执行 |\n\nFile v1.38.0:references/changelog.md\n\n## 1.27.1 (2026-06-05)\r\n\r\n### 修复\r\n- 全流程钩子加固: cmd_create缺口分析提示+创建后自动校验(结构+流程)+调度注册exit(1)截断\r\n\r\n---\r\n\r\n## 1.27.0 (2026-06-02)\r\n\r\n### 新增\r\n\r\n- **调度强制注册机制**：创建含 schedule 的链后**立即**输出强制注册提醒（不等执行日）；新增 register-schedule CLI 子命令将 registered 标记置为 true\r\n- **执行计划注册提醒**：chain_executor.py 检测未注册调度并输出强制提醒\r\n\r\n### 变更\r\n\r\n- **chain_manager.py**：新增 register-schedule CLI 子命令；创建成功后含 schedule 时立即输出强制注册提醒\r\n- **chain_executor.py**：新增 unregistered_schedule 检测，计划输出顶部含强制注册提醒\r\n- **chain_schema.md**：schedule 定义新增 registered 字段，含注册流程说明\r\n- **SKILL.md**：工作流程步骤 5 改为「立即注册调度」，明确不等手动执行\r\n\r\n---\r\n\r\n## 1.26.0 (2026-06-02)\r\n\r\n### 新增\r\n\r\n- **粘连点（Adhesion Point）系统**：新增第四种步骤类型 `type: \"adhesion\"`，标记调用链中无法由 skill 自动化的缺口，提供三种解决方案（manual/auto/hybrid）保证链不断\r\n- **链自愈机制**：新增 `check-gaps` 命令，扫描所有调用链的粘连点，自动检测是否有新 skill 可填补并升级为 skill 步骤；`user_specified: true` 的链跳过自愈\r\n- **执行计划渲染**：`chain_executor.py` 在计划中渲染粘连点步骤，展示原因和 3 种方案\r\n- **流程缺口分析**：创建调用链时新增流程缺口分析，按语义/流程/决策三类真实缺口判断是否打粘连点；明确禁止过度粘连\r\n- **算法组件**：新增 `chain_flow_validator.py`（步骤连续性/依赖链/孤立步骤/粘连点比例≤30%/禁止连续粘连点）和 `chain_structure_checker.py`（JSON 结构/类型枚举/必填字段/依赖闭环——最后一道关，不合格拒保存）\r\n- **skill_extractor suggest**：新增 `suggest` 子命令，根据用户意图关键词匹配 skill 并排序候选，检测未匹配缺口（Python 扫描+LLM 选最终集合的混合模式）\r\n- **能力边界文档**：SKILL.md 新增「能力边界与限制」章节，含适宜/不适宜场景表、硬限制表、常见创建错误速查\r\n- **FAQ 错误场景**：faq.md 新增 E1~E4 四个常见错误场景（粘连点连续、skill 不存在、步骤失败、校验器阻断），每条报错附原因和解决方法\r\n- **调度配置系统**：新增 `schedule` 元数据字段（type/expression/description/registered），任何平台可据此创建定时任务；新增 `chain_manager.py schedule` 子命令；创建链时描述含定时关键词（每天/每周/自动等）强制要求 `--schedule` 参数，否则阻断\r\n- **auto_safe 自动化检测**：`chain_flow_validator` 自动计算链是否可全自动执行（无 manual 粘连点且无 ask 模式），输出 `auto_safe` 布尔字段供平台使用\r\n- **调度强制注册机制**：创建含 `schedule` 的链后**立即**输出强制注册提醒（不等执行日）；新增 `register-schedule` CLI 子命令将 `registered` 标记置为 `true`；`chain_executor.py` 执行计划检测未注册调度并输出强制提醒\r\n\r\n### 变更\r\n\r\n- **`chain_manager.py`**：`validate_chain` 适配 adhesion 类型；新增 `check-gaps` / `schedule` / `register-schedule` CLI 子命令；`create_chain` 和 `update` 自动调用 `flow_validator` + `structure_checker` 校验；新增 `user_specified`、`schedule` 字段和对应 CLI 参数；新增定时关键词强制检测逻辑；创建成功后含 schedule 时立即输出强制注册提醒\r\n- **`chain_schema.md`**：新增类型 D 粘连点步骤、`user_specified` 字段、`auto_safe` 字段、`schedule` 字段（含 `registered`）及 Schedule 定义章节\r\n- **`chain_executor.py`**：新增 `unregistered_schedule` 检测，计划输出顶部含强制注册提醒（`registered=false` 时）\r\n- **`workflow.md`**：创建流程从 7 步扩展为 8 步，新增步骤 6 流程+结构双重校验\r\n- **`adhesion.md`**：补充缺口分析规则、禁止行为清单、连续粘连点合并规则、判定示例\r\n- **`SKILL.md`**：核心能力新增第 7 项粘连点支持；工作流程新增步骤 3 流程缺口分析；快速开始重写为「三步上手」含完整 JSON 示例；新增「能力边界与限制」章节\r\n- **`faq.md`**：新增 E1~E4 常见错误场景\r\n- **`chain_executor.py`**：新增 `unregistered_schedule` 检测，计划输出顶部含强制注册提醒\r\n\r\n---\r\n\r\n## 1.24.10 (2026-06-01)\r\n\r\n### 修复\r\n- 清除H1后冗余反模式引用\r\n\r\n---\r\n\r\n## 1.24.9 (2026-06-01)\r\n\r\n### 修复\r\n- 清除H1后冗余反模式引用\r\n\r\n---\r\n\r\n## 1.24.8 (2026-06-01)\r\n\r\n### 修复\r\n- 标准化改造最终版\r\n\r\n---\r\n\r\n## 1.24.7 (2026-06-01)\r\n\r\n### 修复\r\n- 版本追平仓库\r\n\r\n---\r\n\r\n## 1.24.6 (2026-06-01)\r\n\r\n### 修复\r\n- 标准化改造完成(非标章节处理+description同步)\r\n\r\n---\r\n\r\n## 1.24.5 (2026-06-01)\r\n\r\n### 修复\r\n- audit --fix 自动修正: meta_field_sync, writing_standards\r\n\r\n---\r\n\r\n## 1.24.4 (2026-06-01)\r\n\r\n### 修复\r\n- 标准化改造完成\r\n\r\n---\r\n\r\n## 1.24.3 (2026-06-01)\r\n\r\n### 修复\r\n- 版本追平changelog\r\n\r\n---\r\n\r\n## 1.24.2 (2026-06-01)\r\n\r\n### 修复\r\n- 标准化改造：章节重排+索引表+非标章节处理\r\n\r\n---\r\n\r\n## 1.24.7 (2026-06-01)\r\n\r\n### 修复\r\n- C-13索引表补全\r\n\r\n---\r\n\r\n## 1.24.6 (2026-06-01)\r\n\r\n### 修复\r\n- 从1.24.1恢复，仅添加索引表+顺序修正+R-10/R-20同步\r\n\r\n---\r\n\r\n## 1.24.5 (2026-06-01)\r\n\r\n### 修复\r\n- 版本追平\r\n\r\n---\r\n\r\n## 1.24.4 (2026-06-01)\r\n\r\n### 修复\r\n- 恢复原始版本后仅保留索引表+description 同步\r\n\r\n---\r\n\r\n## 1.24.3 (2026-06-01)\r\n\r\n### 修复\r\n- 标准化修复：渐进式索引表 + 章节顺序修正\r\n\r\n---\r\n\r\n## 1.24.1 (2026-05-31)\r\n\r\n### 修复\r\n- 补回缺失的 H1 标题（）\r\n- R-25 C-07: 3 个代码块补充语言标识\r\n- R-25 C-10: 精简 frontmatter 后多余空行\r\n\r\n---\r\n## 1.24.0 (2026-05-31)\r\n\r\n### Changed（skill-standardization 规范化改造）\r\n- **SKILL.md 全面重构** — frontmatter 补充 trigger/trigger_negative 字段；description 删除版本号（R-04 修复）；删除 H1 版本号（R-06 修复）；清理冗余空白行和历史性内容\r\n- **_meta.json 同步修复** — 补全 data_dir 字段（同步 SKILL.md frontmatter）；tags 与 SKILL.md 同步；补全 triggers 字段；R-12 合规\r\n- **references/changelog.md** — 版本号去除 v 前缀，使用纯数字 SemVer 格式（R-10 修复）\r\n- **references/faq.md** — 删除与 antipatterns.md 重复的反模式内容，专注 FAQ + 使用技巧；修正文档描述\r\n- **references/reference.md** — CLI 命令补全 `{SKILL_DIR}/scripts/` 路径前缀，确保从任意目录可执行\r\n- **references/workflow.md** — 修正配置路径错误（`scripts/default_config.json` → `config.json`）\r\n- **scripts/ 目录清理** — 删除 13 个 .bak 备份文件和 9 个历史 patch/fix 脚本，仅保留 7 个活动文件\r\n\r\n---\r\n\r\n## 1.23.4 (2026-05-30)\r\n\r\n### 修复\r\n- audit --fix 自动修正\r\n\r\n---\r\n\r\n## 1.23.3 (2026-05-30) — R-12 合规完善\r\n\r\n### Changed\r\n- 所有脚本补充 DEFAULT_DATA_DIR_RAW + DATA_DIR R-12 定义\r\n- _meta.json 补充 data_dir 字段\r\n- 运行 fix_missing_data_dir 一键修复，R-12 审计通过\r\n\r\n\r\n## 1.23.0 (2026-05-27)\r\n\r\n### 修复（R-11 路径规范）\r\n- **assets/ 目录迁移** — `assets/` 目录下的 `default_config.json` 和 `settings.html` 迁移到 `scripts/`\r\n- **路径引用修正** — `chain_manager.py`、`chain_executor.py`、`settings.py` 中的 `assets/` 路径统一改为 `scripts/`\r\n- **assets/ 目录删除** — 符合 R-11 规则（产出物必须在 `scripts/` 或根目录）\r\n\r\n---\r\n## 1.22.0 (2026-05-26)\r\n\r\n### 面向对象（OO）改造\r\n- **chain_executor.py** — 全面 OO 改造，拆分为 7 个类：\r\n - `Config` — 配置管理（加载默认配置 + 用户配置合并）\r\n - `PathManager` — 路径管理（技能目录、调用链目录、技能查找）\r\n - `Validator` — 验证器（里程碑判断、retry_policy/failure_mode 验证）\r\n - `TopoSorter` — 拓扑排序器（子步骤依赖排序、递归处理 loop/branch）\r\n - `ExecutionPlanBuilder` — 执行计划构建器（构建执行计划、收集技能名称、生成 AI 指令）\r\n - `InstructionGenerator` — AI 指令生成器（独立类，处理 loop/branch 步骤的指令渲染）\r\n - `CLIHandler` — CLI 处理器（plan/quick/validate 命令处理）\r\n- **chain_manager.py** — 全面 OO 改造，拆分为 7 个类：\r\n - `ConfigManager` — 配置管理器（加载/保存用户配置）\r\n - `PathManager` — 路径管理器（调用链目录、索引文件、技能目录、状态/日志目录）\r\n - `ChainValidator` — 调用链验证器（里程碑判断、调用链数据验证）\r\n - `BackupManager` — 备份管理器（自动备份、备份列表、备份恢复）\r\n - `ChainManager` — 调用链管理器（加载/保存索引、加载/保存/删除调用链、列表）\r\n - `ChainEditor` — 调用链编辑器（创建/更新/删除调用链、添加/删除步骤）\r\n - `CLIHandler` — CLI 命令处理器（init/create/list/show 命令处理）\r\n- **可维护性提升** — 原 1000+ 行函数式代码拆分为职责单一的类方法，便于单元测试和后续扩展\r\n- **SKILL.md 更新** — 修正快速开始代码块中的文件名引用（`chain_manager_oo.py` → `chain_manager.py`、`chain_executor_oo.py` → `chain_executor.py`）\r\n\r\n---\r\n\r\n## 1.21.0 (2026-05-26)\r\n\r\n### 新增功能（build_execution_plan 子步骤处理）\r\n- **子步骤拓扑排序** — `_topo_sort_substeps(steps)` 递归对 loop/branch 内的子步骤按 depends_on 依赖关系进行拓扑排序，替代原来的数组顺序执行\r\n- **递归步骤计数** — `_count_all_steps(steps)` 递归统计所有步骤数（含 loop 子步骤 for_each 迭代次数、while 预估、branch 最大分支），total_steps 计算现在准确\r\n- **build_execution_plan() 接入** — 在生成执行计划时自动对 loop/branch 子步骤进行拓扑排序，并调用 _count_all_steps() 计算准确的 total_steps\r\n\r\n---\r\n\r\n### 修复\r\n\r\n---\r\n\r\n# skill-sub 更新日志\r\n## 1.20.0 (2026-05-26)\r\n\r\n### 新增功能（高级编排）\r\n- **循环步骤（Loop Step）** — `type: \"loop\"` 支持 `for_each` / `while` 两种模式，可嵌套子步骤\r\n- **分支步骤（Branch Step）** — `type: \"branch\"` 支持 `if_steps` / `else_steps` 条件分支，可嵌套子步骤\r\n- **递归渲染引擎** — `loop_branch_renderer.py` 独立模块，支持 `skill` / `loop` / `branch` 步骤的递归 AI 指令渲染\r\n- **`chain_schema.md` 扩展** — 新增 `type` 字段定义，支持三种步骤类型及其子结构（`loop.*` / `branch.*`）\r\n- **`chain_executor.py` 接入** — `generate_ai_instructions()` 改为调用 `render_plan_with_loop_branch()`，完整支持循环/分支渲染\r\n\r\n---\r\n\r\n### 修复\r\n- `calc_intent_similarity()` 分词 bug：`chain_words` 未做 `re.findall` 分词导致永远匹配不上；加入 `user_intent` 字段参与相似度计算\r\n- `cmd_error_stats()` 日志目录路径错误：`log_dir` 手工拼路径改为使用 `LOGS_DIR`；文件读取改 `with open()` 上下文管理器\r\n\r\n---\r\n\r\n## 1.19.1 (2026-05-25)\r\n\r\n### 修复（v1.19.0 虚假 DONE 项实际实现）\r\n- 里程碑影响分析（milestones）— 真正实现并注册到 parser\r\n- 动态里程碑（--dynamic）— 真正实现并注册到 parser\r\n- 里程碑统计（milestone-stats）— 真正实现并注册到 parser\r\n- 标签系统增强（list-tags）— 真正实现并注册到 parser\r\n- v1.19.0 仅标记 DONE 但未实现上述四项，v1.19.1 修复\r\n\r\n---\r\n\r\n## 1.19.0 (2026-05-24)\r\n\r\n### 新增功能\r\n- 链标签系统增强（Chain Tag System Enhancement）— `list-tags`\r\n- 链导入/导出（Chain Import/Export）— `import` / `export`\r\n- 步骤摘取器：参数提取（Parameter Extraction）\r\n- 步骤摘取器：兼容性检查（Compatibility Check）\r\n- 执行计划生成器：资源分析（Resource Analysis）\n\nFile v1.38.0:references/examples.md\n\n# skill-sub 使用示例\n\n> 本文档是 SKILL.md 的渐进式补充，提供完整使用示例。\n\n---\n\n## 示例 1：创建发布流水线调用链\n\n```\n用户：帮我创建一条发布流水线的调用链，包含安全审计、打包、推送\n\nAI：\n 1. 分析意图 → 需要 skills-security-check + 内置打包 + git-sync\n 2. 读取技能信息 → 提取关键步骤\n 3. 规划步骤：\n 步骤1: 安全审计 → 依赖:无 → 里程碑(关键词:审计)\n 步骤2: 打包 → 依赖:[1] → 非里程碑\n 步骤3: 推送代码 → 依赖:[2] → 里程碑(最后一步)\n 4. 展示确认\n 5. [配置: naming_mode=auto] → AI 命名为 \"发布流水线\"\n 6. 保存\n```\n\n**生成的调用链 JSON：**\n\n```json\n{\n \"name\": \"发布流水线\",\n \"description\": \"技能发布完整流程\",\n \"purpose\": \"一键发布技能到 SkillHub/ClawHub\",\n \"user_intent\": \"帮我打包发布这个技能\",\n \"tags\": [\"发布\", \"技能管理\"],\n \"steps\": [\n {\n \"index\": 1,\n \"skill_name\": \"skills-security-check\",\n \"step_name\": \"安全审计\",\n \"action\": \"对技能目录执行安全审计，检查敏感信息泄露\",\n \"skill_instruction\": \"security-audit\",\n \"depends_on\": [],\n \"retry_policy\": {\"max_retries\": 3},\n \"failure_mode\": {\"on_exhaust\": \"abort\", \"is_milestone\": true}\n },\n {\n \"index\": 2,\n \"skill_name\": \"(内置)\",\n \"step_name\": \"打包\",\n \"action\": \"按规范打包为 ZIP（仅含 SKILL.md、_meta.json、scripts/*.py）\",\n \"depends_on\": [1],\n \"retry_policy\": {\"max_retries\": 3},\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false}\n },\n {\n \"index\": 3,\n \"skill_name\": \"git-sync\",\n \"step_name\": \"推送代码\",\n \"action\": \"推送到 Gitee 和 GitHub 仓库\",\n \"depends_on\": [2],\n \"retry_policy\": {\"max_retries\": 3, \"error_types\": [\"network_error\", \"timeout\"]},\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": true}\n }\n ]\n}\n```\n\n---\n\n## 示例 2：执行调用链\n\n```\n用户：执行发布流水线\n\nAI：\n 1. 生成执行计划 → 3步，2个里程碑\n 2. 步骤1（安全审计）→ 第一层 action → ✅成功\n 3. 步骤2（打包）→ 第一层 action → ❌文件占用\n → 分级重试: file_locked → 立即重试 → ✅成功\n 4. 步骤3（推送代码）→ 第一层 action → ❌网络错误\n → 分级重试: network_error → 5秒后重试 → ✅成功\n 5. 汇报: 全部 3/3 步成功\n```\n\n---\n\n## 示例 3：查看里程碑判断依据\n\n```\n用户：查看发布流水线详情\n\nAI：\n 📌 调用链: 发布流水线\n ...\n 📐 里程碑判断依据:\n ★ 步骤1(安全审计): 关键词匹配: '审计'\n ○ 步骤2(打包): 默认规则（非关键节点）\n ★ 步骤3(推送代码): 最终交付步骤\n```\n\n---\n\n## 示例 4：用 skill-sub 摘取步骤形成调用链\n\n> 注意：skill-sub 本身**不参与**调用链，它只负责摘取其他 skill 的步骤并形成调用链。\n\n**场景**：用户希望将\"语义理解 → 规划 → 三步循环执行 → 标准化审查\"这套流程固化为调用链。\n\n```\n用户：帮我创建一条\"标准化执行流水线\"调用链\n\nAI：\n 1. 分析意图 → 需要 semantic-split + triphasic-execution + skill-standardization\n 2. 读取技能信息：\n - semantic-split：提取关键步骤（语义拆分、规划生成）\n - triphasic-execution：提取三步循环步骤\n - skill-standardization：提取审查/改写步骤\n 3. 规划步骤：\n 步骤1: 语义理解 → 依赖:无 → 非里程碑\n 步骤2: 规划步骤 → 依赖:[1] → 非里程碑\n 步骤3: 三步循环执行 → 依赖:[2] → 里程碑\n 步骤4: 标准化审查 → 依赖:[3] → 里程碑(关键词:审查)\n 4. 展示确认\n 5. 保存为调用链 \"标准化执行流水线\"\n```\n\n**关键点**：调用链通过 `chain_manager.py` 保存为 JSON 文件，可复用，不绑定某一次具体任务。\n\n---\n\n## 使用技巧\n\n### 命名建议\n\n- **格式**：「动词+对象」（如「发布技能」「审查代码」「生成报告」）\n- **避免泛化名**：「通用流程」「测试链」→ 改名为「技能安全审计+发布」「用户注册流程测试」\n- **命名即意图**：好的名称让 `list` 一眼能看懂这条链干嘛\n\n### 里程碑配置经验\n\n| 场景 | 建议 |\n|------|------|\n| 安全/审计/部署步骤 | 必须标里程碑（失败不可接受） |\n| 数据生成/中间计算 | 非里程碑 + `on_exhaust: skip` |\n| 不确定是否关键 | 暂时非里程碑 + `on_exhaust: ask` |\n\n### 调用链生命周期\n\n1. **创建** → 命名 + 配置依赖 + 验证（`validate`）\n2. **试运行** → 用简单场景跑一次，看流程是否顺畅\n3. **调整** → 修 action 描述、调重试次数、改里程碑标记\n4. **复用** → 同类任务直接执行\n5. **清理** → 不再需要的链用 `delete --force` 删除，不用留\n\nFile v1.38.0:references/faq.md\n\n# skill-sub 常见问题\r\n\r\n> 本文档是 SKILL.md 的渐进式补充，收录常见问题与使用技巧。\r\n> 反模式详见 `references/antipatterns.md`。\r\n\r\n---\r\n\r\n## FAQ\r\n\r\n### Q1：调用链和脚本有什么区别？\r\n\r\n调用链是**声明式**的——描述\"做什么\"和\"谁来做\"，由 AI 按 action 执行。脚本是**命令式**的——精确指令序列，机器直接运行。\r\n\r\n| | 调用链 | 脚本 |\r\n|---|--------|------|\r\n| 执行者 | AI | 解释器 |\r\n| 容错 | 分级重试 + 询问 | 严格终止 |\r\n| 适用 | 跨 Skill 编排 | 单一工具链 |\r\n\r\n### Q2：如何判断一个任务该不该创建调用链？\r\n\r\n三个条件同时满足：\r\n1. 涉及 ≥2 个 Skill\r\n2. 有复用价值（不会只用一次）\r\n3. 步骤间的依赖关系可固化\r\n\r\n缺一则不适合。\r\n\r\n### Q3：调用链失败后怎么恢复？\r\n\r\n1. 查看失败步骤的 `on_exhaust` 配置\r\n2. 非里程碑 + `on_exhaust: ask` → AI 会询问你\r\n3. 非里程碑 + `on_exhaust: skip` → 已自动跳过\r\n4. 里程碑失败 → 链已中止，需修复后重新执行整条链\r\n5. 用 `chain_executor.py plan` 重新生成执行计划\r\n\r\n### Q4：配置里的\"记忆参考\"开启后有什么用？\r\n\r\n创建调用链时，AI 会额外读取 MEMORY.md 和近期日志，用于：\r\n- 个性化步骤描述（匹配你的命名习惯）\r\n- 推荐常用或相关的 Skill（基于历史使用模式）\r\n\r\n不开也不影响功能，只是步骤描述更通用。\r\n\r\n### Q5：为什么我的调用链执行时每一步都要问我？\r\n\r\n两个常见原因：\r\n1. 所有步骤配置了 `on_exhaust: ask` — 改为 `skip` 或 `abort` 减少交互\r\n2. 第1层 action 描述不够精确 — 执行时 AI 无法确定怎么做，只能问\r\n\r\n解决：创建链时确保每个 action 包含具体的动词+对象+产出。\r\n\r\n### Q6：skill-sub 的数据存在哪？更新会丢吗？\r\n\r\n数据存储在 `~/.workbuddy/skills/.standardization/skill-sub/`（可通过 `SKILL_SUB_HOME` 环境变量更新）：\r\n- `chains/` — 调用链 JSON 文件\r\n- `config.json` — 用户配置\r\n\r\n更新 skill-sub 本身（覆盖 SKILL.md + scripts/）**不会影响**数据目录。但注意这个路径不符合铁律4（产出物应在 `skills/.standardization/` 下），后续版本会迁移。\r\n\r\n---\r\n\r\n## 使用技巧\r\n\r\n1. **命名调用链要有规律** — 用「动词+对象」格式（如\"发布技能\"、\"审查代码\"），方便 `list` 时快速定位\r\n2. **action 写得越具体，执行越顺畅** — 好：「运行 `sensitive_scan.py scan ` 检查敏感信息」；差：「检查安全」\r\n3. **非里程碑步骤优先 `on_exhaust: skip`** — 减少人工介入，除非该步骤的产出被后续步骤强依赖\r\n4. **`tags` 不要随便填** — 它是自动推荐的匹配依据，填 `[\"通用\"]` 等于没填。用领域关键词：`[\"发布\",\"安全\",\"数据分析\"]`\r\n5. **定期清理不用的调用链** — `chain_manager.py list` 检查，`delete --force` 清理。链不是越多越好\r\n6. **里程碑只在\"失败不可接受\"的步骤用** — 如安全审计、部署上线。中间步骤失败通常可跳过或询问\r\n\r\n---\r\n\r\n## 常见错误场景\r\n\r\n### E1：创建链时报\"连续缺口应合并为一个粘连点\"\r\n\r\n**原因**：两个 `type: \"adhesion\"` 步骤相邻。粘连点是 skill 之间的连接器，禁止连续。\r\n\r\n**解决**：合并为一个 adhesion，用 hybrid 方案覆盖全部缺口。\r\n\r\n```json\r\n// 错误：两个连续粘连点\r\n{\"index\":2,\"type\":\"adhesion\",\"step_name\":\"审核\"},\r\n{\"index\":3,\"type\":\"adhesion\",\"step_name\":\"转换\"} // 禁止\r\n\r\n// 正确：合并为一个 hybrid 粘连点\r\n{\"index\":2,\"type\":\"adhesion\",\"step_name\":\"审核+转换\",\r\n \"adhesion\":{\"reason\":\"需要人工审核和数据格式转换\",\r\n \"solutions\":[{\"mode\":\"hybrid\",\"llm_steps\":\"人工审核\",\r\n \"tool_steps\":\"脚本转换格式\"}]}}\r\n```\r\n\r\n### E2：创建链时报\"引用的 skill 不存在\"\r\n\r\n**原因**：`skill_name` 对应的 skill 未安装或名称写错。\r\n\r\n**解决**：用 `python scripts/skill_extractor.py scan` 查看已安装 skill 列表。\r\n\r\n### E3：执行时报\"步骤失败\"\r\n\r\n| 原因 | 现象 | 解决 |\r\n|------|------|------|\r\n| action 描述模糊 | AI 反复确认 | 用具体动词+对象+产出重写 action |\r\n| 依赖的 skill 报错 | skill 本身执行失败 | 单独运行该 skill 确认 |\r\n| 里程碑步骤失败 | 整条链中止 | 修复后重新执行 |\r\n| 重试耗尽 | 超过 max_retries | 检查错误类型后修正重试 |\r\n\r\n### E4：校验器阻断保存\r\n\r\n| 阻断信息 | 原因 | 解决 |\r\n|---------|------|------|\r\n| 缺少必填字段 skill_name | skill 步骤没有指定 skill | 补充 skill_name |\r\n| 无效类型 'xxx' | type 不在 skill/loop/branch/adhesion 中 | 修正 type 字段 |\r\n| 检测到依赖闭环 | depends_on 形成循环 | 打破循环依赖 |\r\n| 索引重复 | 两个步骤相同 index | 使用 --fix 自动修复 |\n\nFile v1.38.0:references/permissions.md\n\n# 权限说明\n\n权限扫描风险等级：**MEDIUM**\n\n## 权限总览\n\n共 2 类权限风险，按类别分组如下：\n\n### 文件操作（1 项）\n> **权限作用**：创建/编辑/删除调用链 JSON 文件\n\n| # | 文件 | 行号 | 匹配内容 | 风险等级 | 授权方式 | 说明 |\n|---|------|------|----------|----------|----------|------|\n| 1 | `scripts/chain_manager.py` | 246, 366 | `open(` 写入 | 🟡 中 | 统一授权 | 创建/编辑/删除调用链 JSON 文件 |\n\n### 网络访问（1 项）\n> **权限作用**：启动本地 HTTP 服务器（配置界面）\n\n| # | 文件 | 行号 | 匹配内容 | 风险等级 | 授权方式 | 说明 |\n|---|------|------|----------|----------|----------|------|\n| 1 | `scripts/settings.py` | 19, 259 | `HTTPServer` | 🟡 中 | 统一授权 | 启动本地 HTTP 服务器（配置界面） |\n\n## 授权方式说明\n\n- **即时授权**：每次执行前需获得用户批准\n- **统一授权**：首次执行前获得用户批准，后续不再询问\n- **静默授权**：无需用户交互，自动执行并记录\n\n## 详细风险列表\n\n1. **[中] 文件操作（创建/编辑/删除调用链 JSON 文件）**\n - 位置：`scripts/chain_manager.py` 第 246 行（写入链）、第 366 行（写入配置）\n - 原因：中风险操作，首次执行前需用户确认\n - 缓解：`--force` 参数强制删除前需用户确认\n\n2. **[中] 网络访问（启动本地 HTTP 服务器）**\n - 位置：`scripts/settings.py` 第 19 行（导入）、第 259 行（启动）\n - 原因：中风险操作，首次执行前需用户确认\n - 缓解：仅监听 localhost，不对外暴露\n\n---\n\n**注**：本文件由 skill-standardization v2.24.0 自动生成（R-15 修复），实际风险等级由 `scripts/permission_checker.py` 扫描结果决定。\n\nFile v1.38.0:references/reference.md\n\n# skill-sub 参考手册\r\n\r\n> 本文档是 SKILL.md 的渐进式补充，包含完整 CLI 速查、脚本 API、存储格式。\r\n\r\n---\r\n\r\n## CLI 速查\r\n\r\n```bash\r\n# 初始化数据目录\r\npython {SKILL_DIR}/scripts/chain_manager.py init\r\n\r\n# 配置\r\npython {SKILL_DIR}/scripts/settings.py # 交互式配置（打开浏览器）\r\npython {SKILL_DIR}/scripts/settings.py --serve-only # Agent 模式\r\npython {SKILL_DIR}/scripts/settings.py --get-config # 查看配置\r\npython {SKILL_DIR}/scripts/settings.py --save-config '' # 保存配置\r\npython {SKILL_DIR}/scripts/chain_manager.py config # 查看配置\r\n\r\n# 创建调用链\r\npython {SKILL_DIR}/scripts/chain_manager.py create --name \"链名\" --description \"描述\" --purpose \"目的\" --steps '[...]'\r\n\r\n# 查询\r\npython {SKILL_DIR}/scripts/chain_manager.py list [--tag \"标签\"]\r\npython {SKILL_DIR}/scripts/chain_manager.py show --name \"链名\"\r\n\r\n# 执行\r\npython {SKILL_DIR}/scripts/chain_executor.py plan --name \"链名\" [-v] [--json]\r\npython {SKILL_DIR}/scripts/chain_executor.py quick --steps '[...]' --name \"临时\"\r\npython {SKILL_DIR}/scripts/chain_executor.py validate --name \"链名\"\r\n\r\n# 调整\r\npython {SKILL_DIR}/scripts/chain_manager.py add-step --name \"链名\" ...\r\npython {SKILL_DIR}/scripts/chain_manager.py remove-step --name \"链名\" --step N\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step N [--action ...] [--milestone] [--retry-max N]\r\npython {SKILL_DIR}/scripts/chain_manager.py rename --name \"旧名\" --new-name \"新名\"\r\n\r\n# 删除\r\npython {SKILL_DIR}/scripts/chain_manager.py delete --name \"链名\" --force\r\n```\r\n\r\n---\r\n\r\n## 脚本清单\r\n\r\n| 脚本 | 功能 |\r\n|------|------|\r\n| `chain_manager.py` | 调用链 CRUD（init/create/list/show/run/add-step/remove-step/update-step/rename/delete/config） |\r\n| `chain_executor.py` | 执行引擎（plan/quick/validate）+ 里程碑分类 + 配置集成 |\r\n| `skill_extractor.py` | 从 SKILL.md 提取关键步骤和指令名称（extract/scan） |\r\n| `settings.py` | HTML 配置界面 + CLI 配置管理 |\r\n\r\n---\r\n\r\n## 存储机制\r\n\r\n### 数据目录\r\n\r\n```\r\n~/.workbuddy/skills/.standardization/skill-sub/\r\n├── config.json # 用户配置（配置界面写入）\r\n└── chains/ # 调用链数据\r\n ├── index.json # 调用链索引\r\n ├── 发布流水线.json # 每条链一个文件\r\n └── ...\r\n```\r\n\r\n### 调用链 JSON 格式\r\n\r\n```json\r\n{\r\n \"name\": \"发布流水线\",\r\n \"description\": \"技能发布完整流程\",\r\n \"purpose\": \"一键发布技能到 SkillHub/ClawHub\",\r\n \"user_intent\": \"帮我打包发布这个技能\",\r\n \"tags\": [\"发布\", \"技能管理\"],\r\n \"created_at\": \"2026-05-21T15:00:00\",\r\n \"updated_at\": \"2026-05-21T19:00:00\",\r\n \"exec_count\": 5,\r\n \"steps\": [\r\n {\r\n \"index\": 1,\r\n \"skill_name\": \"skills-security-check\",\r\n \"step_name\": \"安全审计\",\r\n \"action\": \"对技能目录执行安全审计，检查敏感信息泄露\",\r\n \"skill_instruction\": \"security-audit\",\r\n \"depends_on\": [],\r\n \"retry_policy\": {\"max_retries\": 3},\r\n \"failure_mode\": {\"on_exhaust\": \"abort\", \"is_milestone\": true}\r\n },\r\n {\r\n \"index\": 2,\r\n \"skill_name\": \"(内置)\",\r\n \"step_name\": \"打包\",\r\n \"action\": \"按规范打包为 ZIP（仅含 SKILL.md、_meta.json、scripts/*.py）\",\r\n \"depends_on\": [1],\r\n \"retry_policy\": {\"max_retries\": 3},\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false}\r\n },\r\n {\r\n \"index\": 3,\r\n \"skill_name\": \"git-sync\",\r\n \"step_name\": \"推送代码\",\r\n \"action\": \"推送到 Gitee 和 GitHub 仓库\",\r\n \"depends_on\": [2],\r\n \"retry_policy\": {\"max_retries\": 3, \"error_types\": [\"network_error\", \"timeout\"]},\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false}\r\n }\r\n ]\r\n}\r\n```\r\n\r\n---\r\n\r\n## 环境变量\r\n\r\n| 变量 | 说明 | 默认值 |\r\n|------|------|--------|\r\n| `SKILL_SUB_HOME` / `SKILL_CHAIN_HOME` | 数据目录 | `~/.workbuddy/skills/.standardization/skill-sub/` |\r\n| `WORKBUDDY_SKILLS_DIR` | 技能安装目录 | `~/.workbuddy/skills/` |\r\n\r\n---\r\n\r\n## 完整流程图\r\n\r\n```\r\n用户触发创建\r\n │\r\n ├─ 分析意图 → 确定需要哪些技能\r\n │\r\n ├─ 读取技能信息（skill_extractor.py scan）\r\n │ └─ [配置: 记忆参考=是] → 额外读取 MEMORY.md + 日志\r\n │\r\n ├─ 规划步骤（提取关键步骤 → 排列顺序 → 配置依赖）\r\n │\r\n ├─ 里程碑判断（classify_milestones 自动判断）\r\n │ ├─ 关键词匹配\r\n │ ├─ 瓶颈点检测\r\n │ └─ 最后一步标记\r\n │ └─ 展示判断依据 → 用户确认调整\r\n │\r\n ├─ 展示完整调用链 → 用户确认\r\n │\r\n └─ 命名保存\r\n ├─ [配置: naming_mode=auto] → AI 自动命名\r\n └─ [配置: naming_mode=manual] → 询问用户\r\n```\r\n\r\n```\r\n用户触发执行\r\n │\r\n ├─ 生成执行计划（chain_executor.py plan）\r\n │\r\n ├─ 逐步骤执行\r\n │ ├─ 第一层：用 action 直接执行\r\n │ ├─ 失败 → 分级重试（最多 N 次，N 从配置读取）\r\n │ ├─ 仍失败 → 按 on_exhaust 处理\r\n │ │ ├─ ask → 询问用户\r\n │ │ ├─ skip → 跳过，继续下一步\r\n │ │ └─ abort → 中止整条链\r\n │ │\r\n │ └─ 里程碑步骤失败 → 强制中止（无论 on_exhaust）\r\n │\r\n └─ 汇报结果\r\n```\r\n\r\n---\r\n\r\n## 权限权重说明（R-16）\r\n\r\n> 本节说明 `skill-sub` 各操作的权限权重，便于审查时评估风险。\r\n\r\n### 脚本权限分析\r\n\r\n| 脚本 | 敏感信息访问 | 关键位置写入 | 网络访问 | 文件删除 | Subprocess 调用 | 权重 |\r\n|------|--------------|--------------|----------|----------|-------------------|------|\r\n| `chain_manager.py` | 低（读 SKILL.md） | 中（写 `chains/` 目录） | 无 | 无 | 无 | **中** |\r\n| `chain_executor.py` | 低（读调用链） | 低（执行日志） | 无 | 无 | 中（调用其他 skill） | **中** |\r\n| `settings.py` | 低（读配置） | 低（写 `config.json`） | 无 | 无 | 无 | **低** |\r\n| `skill_extractor.py` | 低（读 SKILL.md） | 无 | 无 | 无 | 无 | **低** |\r\n\r\n### 授权方式\r\n\r\n- **低权重操作**（如查看调用链列表）：静默执行，无需授权\r\n- **中权重操作**（如创建/更新调用链）：统一授权（批量展示风险列表）\r\n- **高权重操作**（如删除调用链）：即时授权（执行前单独确认）\r\n\r\n### 风险缓解\r\n\r\n- 调用链数据存储在 `~/.workbuddy/skills/.standardization/skill-sub/chains/`，非技能核心目录\r\n- `chain_executor.py` 调用其他 skill 时，通过标准 `Skill` 工具调用，不执行任意命令\r\n- 配置文件中不含敏感信息（仅用户偏好配置）\n\nFile v1.38.0:references/workflow.md\n\n# skill-sub 详细工作流程\r\n\r\n> 本文档是 SKILL.md 的渐进式补充，详细描述执行流程、里程碑判断规则、三层回退策略。\r\n\r\n---\r\n\r\n## 完整执行流程\r\n\r\n### 创建调用链（create）\r\n\r\nAI 执行 7 步流程：\r\n\r\n1. **分析意图**：理解用户想串联哪些技能、达成什么目的\r\n2. **读取技能信息**：对每个涉及技能，运行 `skill_extractor.py scan` 提取关键步骤和指令\r\n3. **规划步骤**：确定步骤顺序、依赖关系、并行机会\r\n4. **流程缺口分析**：检查技能衔接处是否存在真实缺口，按以下三条规则判断（**禁止为了打粘连点而主动制造缺口**）\r\n\r\n ### 缺口规则\r\n\r\n | 缺口类型 | 说明 | 示例 | 是否打粘连点 |\r\n |---------|------|------|------------|\r\n | **语义缺口** | Skill A 的输出不是 Skill B 需要的输入格式/内容，需要转换 | 代码分析 skill 输出 JSON → 报告生成 skill 需要 Markdown | ✅ 需转换步骤 |\r\n | **流程缺口** | 用户任务流程中缺少某个环节，且无 skill 覆盖 | 编码→部署之间缺测试阶段，且无测试 skill | ✅ 需补充步骤 |\r\n | **决策缺口** | 需要人工判断/审批的节点 | 发布审批、PR Merge、方案决策 | ✅ 需人工节点 |\r\n | **自然衔接** | 两个 skill 输出输入天然匹配，无需额外转换 | 编译→运行测试、生成报告→发送通知 | ❌ 不需要 |\r\n\r\n ### 禁止行为\r\n\r\n - **不要为了有粘连点而故意制造缺口** — 自然衔接的 skill 步骤之间不打\r\n - **不要用粘连点替代 skill** — 如果一个 skill 能完成，直接用 skill 步骤\r\n - **不要过度粘连** — 一条调用链中粘连点数量应远少于 skill 步骤数\r\n\r\n5. **配置策略**：根据里程碑规则自动判断 + 用户确认调整\r\n6. **流程+结构校验**：自动调用 `chain_flow_validator` 和 `chain_structure_checker` 双重校验，不通过则拒绝保存\r\n7. **展示确认**：展示完整调用链供用户确认（包括里程碑标记、判断依据、粘连点信息）\r\n8. **命名保存**：根据配置决定自动命名或询问用户\r\n5. **展示确认**：展示完整调用链供用户确认（包括里程碑标记和判断依据）\r\n6. **命名保存**：根据配置决定自动命名或询问用户\r\n\r\n> **记忆参考（配置启用时）**：在步骤2后，读取 MEMORY.md 和近期日志，提取用户偏好和习惯，用于增强步骤描述的个性化。\r\n\r\n### 预生成（suggest）\r\n\r\n扫描已安装技能，推荐常用或相关的技能组合：\r\n\r\n```bash\r\npython {SKILL_DIR}/scripts/skill_extractor.py scan\r\n```\r\n\r\n### 查询（list / show）\r\n\r\n```bash\r\n# 列出所有调用链\r\npython {SKILL_DIR}/scripts/chain_manager.py list\r\npython {SKILL_DIR}/scripts/chain_manager.py list --tag \"发布\"\r\n\r\n# 查看详情（含里程碑判断依据）\r\npython {SKILL_DIR}/scripts/chain_manager.py show --name \"发布流水线\"\r\n\r\n# 查看当前配置\r\npython {SKILL_DIR}/scripts/chain_manager.py config\r\n```\r\n\r\n### 执行（run）\r\n\r\n三步执行流程：\r\n\r\n1. **生成执行计划**：`chain_executor.py plan --name <名称>`\r\n2. **按计划执行**：AI 读取执行计划，逐步执行\r\n3. **汇报结果**：每步执行后汇报 ✅/❌，里程碑步骤失败则中止\r\n\r\n### 调整（edit）\r\n\r\n```bash\r\n# 添加步骤\r\npython {SKILL_DIR}/scripts/chain_manager.py add-step --name \"链名\" --after 1 --skill \"技能名\" --step-name \"步骤名\" --action \"动作\"\r\n\r\n# 删除步骤\r\npython {SKILL_DIR}/scripts/chain_manager.py remove-step --name \"链名\" --step 3\r\n\r\n# 更新步骤\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step 2 --action \"新动作\"\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step 1 --milestone\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step 3 --no-milestone\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step 1 --retry-max 5\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step 2 --on-exhaust abort\r\n\r\n# 重命名\r\npython {SKILL_DIR}/scripts/chain_manager.py rename --name \"旧名\" --new-name \"新名\"\r\n```\r\n\r\n### 删除（delete）\r\n\r\n```bash\r\npython {SKILL_DIR}/scripts/chain_manager.py delete --name \"链名\" --force\r\n```\r\n\r\n---\r\n\r\n## 循环与分支编排（v1.20.0 新增）\r\n\r\n### for-each 循环\r\n\r\n`type: \"loop\"` + `\"mode\": \"for_each\"`：遍历数组，对每个元素执行循环体。\r\n\r\n```json\r\n{\r\n \"type\": \"loop\",\r\n \"step_name\": \"批量处理\",\r\n \"loop\": {\r\n \"mode\": \"for_each\",\r\n \"items\": \"{{file_list}}\",\r\n \"loop_variable\": \"f\",\r\n \"max_iterations\": 10,\r\n \"steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"file-ops\", \"action\": \"处理 {{f}}\"}\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### while 循环\r\n\r\n`type: \"loop\"` + `\"mode\": \"while\"`：按条件重复执行，直到条件为假或达到最大次数。\r\n\r\n```json\r\n{\r\n \"type\": \"loop\",\r\n \"step_name\": \"重试直到成功\",\r\n \"loop\": {\r\n \"mode\": \"while\",\r\n \"while_condition\": \"{{retry_count}} < 3 and {{last_success}} == false\",\r\n \"max_iterations\": 3,\r\n \"steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"api-call\", \"action\": \"重试\"}\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### if-else 分支\r\n\r\n`type: \"branch\"`：根据条件选择执行 `if_steps` 或 `else_steps`。\r\n\r\n```json\r\n{\r\n \"type\": \"branch\",\r\n \"step_name\": \"按环境部署\",\r\n \"branch\": {\r\n \"condition\": \"{{env}} == 'prod'\",\r\n \"if_steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"deploy\", \"action\": \"部署到生产\"}\r\n ],\r\n \"else_steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"deploy\", \"action\": \"部署到预发\"}\r\n ]\r\n }\r\n}\r\n```\r\n\r\n> 📚 完整 schema 参见 `chain_schema.md`\r\n\r\n---\r\n\r\n## 里程碑通用判断规则\r\n\r\n> **设计原则**：不完全依赖 AI 自觉判断，基于步骤的**结构特征**自动确定里程碑。\r\n\r\n### 判断规则（优先级从高到低）\r\n\r\n| 优先级 | 规则 | 说明 | 示例 |\r\n|--------|------|------|------|\r\n| 1 | 用户显式标记 | `is_milestone=true` | 用户手动指定 |\r\n| 2 | 显式取消 | `is_milestone=false` | 用户明确不需要 |\r\n| 3 | 短链全部标记 | 总步骤数 ≤ 2 → 全部里程碑 | 链太短，每步都关键 |\r\n| 4 | 关键词匹配 | 步骤名包含特定关键词 → 里程碑 | \"安全审计\"、\"部署上线\" |\r\n| 5 | 瓶颈点 | 被 ≥2 个后续步骤依赖 → 里程碑 | 多个步骤依赖该步骤的输出 |\r\n| 6 | 最终交付 | 是最后一步 → 里程碑 | 最终产出物 |\r\n| 7 | 默认非里程碑 | 以上均不满足 | 辅助/中间步骤 |\r\n\r\n### 里程碑关键词\r\n\r\n中英文关键词（步骤名包含任一即匹配）：\r\n\r\n```\r\n审计、安全、部署、发布、上线、打包、测试、验证、校验、审批、审核、\r\n付款、支付、下单、提交、推送、导入、导出、迁移、备份、恢复、\r\naudit、deploy、release、publish、push、test、verify、validate、\r\napprove、review、payment、submit、import、export、migrate、\r\nbackup、restore、build、compile、install\r\n```\r\n\r\n### 里程碑行为\r\n\r\n- **里程碑步骤失败** → 无论 `on_exhaust` 配置如何，**强制中止整条链**\r\n- **里程碑步骤的 on_exhaust** → 建议设为 `abort`（validate 时会发出警告）\r\n- **非里程碑步骤失败** → 按 `on_exhaust` 配置处理（ask/skip/abort）\r\n\r\n---\r\n\r\n## 三层回退执行策略\r\n\r\n| 层次 | 策略 | 上下文占用 | 触发条件 |\r\n|------|------|-----------|---------|\r\n| **第一层** | 仅用 action 精炼描述直接执行 | 最低 | 默认，action 足够明确 |\r\n| **第二层** | 按需读取 SKILL.md 对应指令片段 | 中等 | action 不明确或执行失败 |\r\n| **第三层** | 加载完整 SKILL.md | 最高 | 前两层均无法完成 |\r\n\r\n---\r\n\r\n## 分级重试策略\r\n\r\n| 错误类型 | 重试间隔 | 说明 |\r\n|---------|---------|------|\r\n| file_locked | 0 秒 | 文件占用/锁定，立即重试 |\r\n| network_error | 5 秒 | 网络不通/超时 |\r\n| timeout | 5 秒 | 执行超时 |\r\n| auth_error | - | 认证/权限错误，直接询问用户 |\r\n| other | 2 秒 | 其他错误 |\r\n\r\n重试次数从配置读取（默认3次），耗尽后按 `on_exhaust` 处理。\r\n\r\n---\r\n\r\n## AI 执行指令（必读原则）\r\n\r\n1. **执行前通读调用链**：读取整条链的所有步骤，理解全局依赖关系\r\n2. **三层回退**：每个步骤优先用 action 执行，不充分时再读取 SKILL.md\r\n3. **里程碑步骤失败立即中止**：不继续后续步骤\r\n4. **非里程碑步骤失败按 on_exhaust 处理**：ask（询问）/ skip（跳过）/ abort（中止）\r\n5. **记录变量传递**：步骤输出变量作为后续步骤输入\r\n6. **命名遵循配置**：`naming_mode=auto` 时 AI 自动命名，`manual` 时询问用户\r\n\r\n---\r\n\r\n## 配置界面\r\n\r\n### 配置项说明\r\n\r\n| 配置项 | 选项 | 说明 |\r\n|--------|------|------|\r\n| **记忆参考** | 是 / 否 | 创建/执行调用链时，是否读取用户记忆文件增强步骤描述 |\r\n| **命名方式** | 自动 / 人工 | 创建调用链时，由 AI 自动命名还是询问用户 |\r\n| **默认重试次数** | 1-10（默认3） | 所有步骤的默认最大重试次数 |\r\n\r\n### 当前配置\r\n\r\n> **配置路径**：`~/.workbuddy/skills/.standardization/skill-sub/config.json`\r\n> **默认配置**：`{skill_dir}/scripts/default_config.json`\r\n\r\n**方式 1：HTML 配置界面（推荐）**\r\n\r\nAgent 执行：\r\n1. 运行 `python {SKILL_DIR}/scripts/settings.py --serve-only`\r\n2. 解析输出中的 `SERVER_STARTED:`\r\n3. 打开浏览器 `http://localhost:{port}/`\r\n4. 轮询 `{SKILL_DIR}/.settings_done` 标志文件\r\n5. 检测到标志文件后关闭服务器\r\n\r\n**方式 2：命令行查看**\r\n\r\n```bash\r\npython {SKILL_DIR}/scripts/settings.py --get-config\r\n```\r\n\r\n**方式 3：命令行保存**\r\n\r\n```bash\r\npython {SKILL_DIR}/scripts/settings.py --save-config '{\"use_memory_reference\": true, \"naming_mode\": \"auto\", \"default_max_retries\": 5}'\r\n```\r\n\r\n**方式 4：对话式配置（回退方案）**\r\n\r\n当 HTML 配置界面无法打开时，通过对话方式收集配置：\r\n\r\n```\r\n步骤 1：记忆参考\r\n是否在创建调用链时参考用户记忆文件？（输入 y/n）:\r\n\r\n步骤 2：命名方式\r\n调用链命名方式（输入 1/2 选择）：\r\n1. 自动 — AI 根据意图和目的自动生成名称\r\n2. 人工 — 每次创建时询问用户\r\n请输入：\r\n\r\n步骤 3：默认重试次数\r\n请输入默认最大重试次数（1-10，默认3）:\r\n\r\n步骤 4：保存\r\nAgent 执行: python settings.py --save-config ''\r\n```\n\nFile v1.38.0:scripts/default_config.json\n\n{\r\n \"version\": \"1.2.0\",\r\n \"_skill_sub_home\": \"~/.workbuddy/skills/.standardization/skill-sub/\",\r\n\r\n \"use_memory_reference\": false,\r\n \"naming_mode\": \"manual\",\r\n \"default_max_retries\": 3\r\n}\n\nArchive v1.37.3: 19 files, 63129 bytes\n\nFiles: _meta.json (129b), references/adhesion.md (5777b), references/antipatterns.md (2639b), references/chain_schema.md (13542b), references/changelog.md (12162b), references/examples.md (4999b), references/faq.md (4975b), references/permissions.md (1819b), references/reference.md (6938b), references/workflow.md (10642b), scripts/chain_executor.py (23718b), scripts/chain_flow_validator.py (10430b), scripts/chain_manager.py (42348b), scripts/chain_structure_checker.py (11758b), scripts/default_config.json (194b), scripts/loop_branch_renderer.py (6717b), scripts/settings.html (10326b), skill-card.md (2560b), SKILL.md (10089b)\n\nFile v1.37.3:SKILL.md\n\n---\r\nname: skill-sub\r\nversion: 1.27.1\r\nauthor: wUwproject\r\nlicense: MIT\r\ndescription: 调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。\r\nsensitive_access: false\r\ncritical_write: false\r\npermission_weight: LOW\r\ndata_dir: ../.standardization/skill-sub/data/\r\ntags: ['chain', 'orchestration', 'usable', 'skill-builder', 'progressive-loading', 'planner', 'editor']\r\nexternal_data_dir: true\r\ntrigger: ['规划类: 帮我规划一下/步骤是什么', '顺序类: 依次执行/先...再...', '链管理: 创建/查看/更新/删除调用链']\r\ntrigger_negative: ['不使用调用链', '手动逐步执行']\r\nmeta_field_sync: true\r\nh1_position: true\r\n---\r\n# skill-sub\r\n\r\n\r\n\r\n\r\n## 触发场景\r\n\r\n**当用户提出以下意图时触发本技能：**\r\n- 规划类：「帮我规划一下...」、「...的步骤是什么」\r\n- 顺序类：「依次执行 A、B、C」、「先...再...」\r\n- 链管理：「创建/查看/更新/删除调用链」\r\n\r\n**否定条件**：仅当用户明确要求「不使用调用链」或「手动逐步执行」时，不自动触发。\r\n\r\n\r\n\r\n## 核心能力\r\n\r\n> 📚 **渐进式加载**：本技能采用渐进式 MD 体系，`SKILL.md` 为入口（≤230行），详细内容拆分到 `references/*.md` 按需加载。\r\n\r\n| # | 功能 | 说明 |\r\n|---|------|------|\r\n| 1 | **调用链管理** | 创建、查询、更新、删除调用链 |\r\n| 2 | **执行计划生成** | 生成结构化执行计划，含并行/串行标记 |\r\n| 3 | **条件执行** | 支持条件步骤，按条件判断是否执行 |\r\n| 4 | **循环与分支编排** | 支持 for-each/while 循环和 if-else 分支 |\r\n| 5 | **Dry-Run 模式** | 模拟执行，不实际调用技能 |\r\n| 6 | **链备份与版本管理** | 自动备份，支持版本恢复 |\r\n| 7 | **粘连点（Adhesion Point）** | 标记 skill 无法自动化的缺口，提供三种解决方案保证链不断；支持自愈 —— 每次执行自动扫描是否有新 skill 可填补 |\r\n\r\n---\r\n\r\n---\r\n\r\n\r\n\r\n\r\n\r\n### 渐进式文件索引\r\n\r\n| 文件名 | 位置 | 说明 |\r\n|--------|------|------|\r\n| `references/antipatterns.md` | skill-sub 反模式 | > 本文档收录 skill-sub 使用中的常见错误和正确做法。完整反模式示例见 `references/faq.md` |\r\n| `references/adhesion.md` | 粘连点机制（v1.25.0） | > 粘连点定义、三种解决方案（manual/auto/hybrid）、自愈流程 |\r\n| `references/chain_schema.md` | skill-sub 调用链数据结构 | > 本文档定义 Chain / Step / retry_policy / failure_mode 的完整结构。 |\r\n| `references/changelog.md` | skill-sub 更新日志 | - **循环步骤（Loop Step）** — `type: \"loop\"` 支持 `for_each` / `whil |\r\n| `references/examples.md` | skill-sub 使用示例 | > 本文档是 SKILL.md 的渐进式补充，提供完整使用示例。 |\r\n| `references/faq.md` | skill-sub 常见问题 | > 本文档是 SKILL.md 的渐进式补充，收录常见问题与使用技巧。 |\r\n| `references/permissions.md` | 权限说明 | 权限扫描风险等级：**MEDIUM** |\r\n| `references/reference.md` | skill-sub 参考手册 | > 本文档是 SKILL.md 的渐进式补充，包含完整 CLI 速查、脚本 API、存储格式。 |\r\n| `references/workflow.md` | skill-sub 详细工作流程 | > 本文档是 SKILL.md 的渐进式补充，详细描述执行流程、里程碑判断规则、三层回退策略。 |\r\n## 快速开始\r\n\r\n### 三步上手：创建一个最小调用链\r\n\r\n```bash\r\n# 第一步：初始化\r\npython {SKILL_DIR}/scripts/chain_manager.py init\r\n\r\n# 第二步：创建调用链（两个 skill + 一个粘连点连接）\r\npython {SKILL_DIR}/scripts/chain_manager.py create --name \"代码发布\" \\\r\n --description \"从代码分析到发布的完整流程\" \\\r\n --steps '[\r\n {\"index\":1,\"type\":\"skill\",\"step_name\":\"代码审查\",\"skill_name\":\"code-review\",\"action\":\"审查PR\"},\r\n {\"index\":2,\"type\":\"adhesion\",\"step_name\":\"审批发布\",\"adhesion\":{\"reason\":\"发布审批需要人工决策\",\"solutions\":[{\"mode\":\"manual\",\"description\":\"人工审批发布申请\"}]}},\r\n {\"index\":3,\"type\":\"skill\",\"step_name\":\"部署\",\"skill_name\":\"deploy\",\"action\":\"部署到生产环境\"}\r\n ]'\r\n\r\n# 第三步：生成执行计划\r\npython {SKILL_DIR}/scripts/chain_executor.py plan --name \"代码发布\" --verbose\r\n```\r\n\r\n> 💡 **小贴士**：创建时如果步骤有 ERROR，会提示具体原因（如\"连续缺口应合并为一个粘连点\"），按提示修正后重试即可。\r\n\r\n### 更多命令\r\n\r\n```bash\r\n# Dry-Run 模拟执行（不实际调用技能）\r\npython {SKILL_DIR}/scripts/chain_executor.py plan --name \"代码发布\" --dry-run\r\n\r\n# 查看调用链详情\r\npython {SKILL_DIR}/scripts/chain_manager.py show --name \"代码发布\"\r\n\r\n# 列出所有调用链\r\npython {SKILL_DIR}/scripts/chain_manager.py list\r\n\r\n# 删除（自动备份）\r\npython {SKILL_DIR}/scripts/chain_manager.py delete --name \"代码发布\" --force\r\n```\r\n\r\n---\r\n\r\n\r\n\r\n## 工作流程\r\n\r\n1. **理解意图** → 分析用户输入，判断是否需要调用链\r\n2. **规划技能顺序** → 推荐参与的 Skill 及其顺序\r\n3. **流程缺口分析** → 检查技能衔接处是否存在语义/流程/决策缺口，在天然断裂处打粘连点（**禁止随意添加**）\r\n4. **生成调用链** → 创建 JSON 格式的调用链定义（含 skill 步骤和 adhesion 步骤）。如有定时/自动化意图，**必须** 附带 `--schedule` 参数\r\n5. **立即注册调度** → 链创建成功且带 `schedule` 时，AI **必须当场**完成注册。定时任务不等手动执行，不存在\"等下次执行时再注册\"的可能\r\n6. **生成执行计划** → 输出 AI 可直接执行的指令序列\r\n7. **（可选）实际执行** → 按执行计划逐步调用技能\r\n\r\n---\r\n\r\n\r\n### 循环与分支编排\r\n\r\n### for-each 循环\r\n\r\n在调用链 JSON 中，将某步骤的 `type` 设为 `\"loop\"`，并定义 `loop` 对象：\r\n\r\n```json\r\n{\r\n \"type\": \"loop\",\r\n \"step_name\": \"批量处理文件\",\r\n \"loop\": {\r\n \"mode\": \"for_each\",\r\n \"items\": \"{{file_list}}\",\r\n \"loop_variable\": \"f\",\r\n \"max_iterations\": 10,\r\n \"steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"file-ops\", \"step_name\": \"处理单个文件\", \"action\": \"处理 {{f}}\"}\r\n ]\r\n }\r\n}\r\n```text\r\n\r\n### while 循环\r\n\r\n```json\r\n{\r\n \"type\": \"loop\",\r\n \"step_name\": \"重试直到成功\",\r\n \"loop\": {\r\n \"mode\": \"while\",\r\n \"while_condition\": \"{{retry_count}} < 3 and {{last_result}} != 'success'\",\r\n \"max_iterations\": 3,\r\n \"steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"api-call\", \"step_name\": \"调用接口\", \"action\": \"重试第 {{retry_count}} 次\"}\r\n ]\r\n }\r\n}\r\n```text\r\n\r\n### if-else 分支\r\n\r\n```json\r\n{\r\n \"type\": \"branch\",\r\n \"step_name\": \"按环境部署\",\r\n \"branch\": {\r\n \"condition\": \"{{env}} == 'prod'\",\r\n \"if_steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"deploy\", \"step_name\": \"生产部署\", \"action\": \"部署到生产环境\"}\r\n ],\r\n \"else_steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"deploy\", \"step_name\": \"预发部署\", \"action\": \"部署到预发环境\"}\r\n ]\r\n }\r\n}\r\n```\r\n\r\n> 📚 完整 schema 详见 `references/chain_schema.md`\r\n\r\n---\r\n\r\n\r\n\r\n## 能力边界与限制\r\n\r\n### 适宜场景 ✅\r\n\r\n| 场景 | 说明 |\r\n|------|------|\r\n| 多 skill 编排 | 涉及 2 个及以上 skill，步骤间有明确依赖关系 |\r\n| 可固化流程 | 流程稳定、可复现，不是一次性操作 |\r\n| 跨步骤衔接 | skill 之间需要数据转换、人工审批、流程补全 |\r\n\r\n### 不适宜场景 ❌\r\n\r\n| 场景 | 原因 |\r\n|------|------|\r\n| 单 skill 任务 | 直接调 skill 本身即可，不需要调用链 |\r\n| 一次性操作 | 调用链的价值在于复用，一次性工作不值得建链 |\r\n| 无依赖的并行任务 | 多个独立任务应并行执行，不需要编排 |\r\n| 高度动态的流程 | 每次执行步骤都不一样，粘连点也解决不了，直接 AI 手动处理 |\r\n\r\n### 硬限制\r\n\r\n| 限制项 | 值 | 说明 |\r\n|--------|-----|------|\r\n| 最大步骤数 | 30 层（含嵌套） | 超过后校验器会告警，但不阻断执行 |\r\n| 粘连点占比 | 30% | 超过告警，建议合并或补充 skill |\r\n| 粘连点连续 | **禁止** | 连续缺口合并为一个粘连点 |\r\n| 依赖深度 | 10 层 | 过深依赖链难以维护和排查 |\r\n| 循环最大迭代 | 默认 10，可配置 | 超过按 on_max_iteration 处理 |\r\n\r\n### 常见创建错误速查\r\n\r\n| 报错信息 | 原因 | 解决方法 |\r\n|---------|------|---------|\r\n| 连续缺口应合并为一个粘连点 | 两个 adhesion 步骤相邻 | 合并为一个 adhesion，用 hybrid 方案覆盖全部缺口 |\r\n| 粘连点占比超过 30% | adhesion 步骤太多 | 检查是否有 skill 可以替代 |\r\n| 缺少 solutions | adhesion 步骤没有提供方案 | 至少加一个 manual 方案 |\r\n| 依赖不存在的步骤 | depends_on 引用了无效索引 | 检查依赖步骤的 index 是否正确 |\r\n| 引用的 skill 不存在 | skill_name 对应的 skill 未安装 | 检查 skill 名称是否正确 |\r\n| 检测到定时/自动化意图，但未提供 --schedule | 描述中含\"每天/每周/定时\"等词但没给调度配置 | 添加 --schedule 参数，或移除描述中的时间相关词 |\r\n\r\n> **强制规则**：用户描述中包含定时/自动化意图（如\"每天\"、\"每周\"、\"自动执行\"等）时，**必须**提供 `--schedule` 参数配置调度信息，否则链创建被拦截。不依赖 AI 自觉判断。\r\n\r\n## 配置\r\n\r\n配置界面：`python {SKILL_DIR}/scripts/settings.py`\r\n\r\n| 配置项 | 选项 | 说明 |\r\n|--------|------|------|\r\n| **记忆参考** | 是 / 否 | 创建/执行调用链时，是否读取用户记忆文件增强步骤描述 |\r\n| **命名方式** | 自动 / 人工 | 创建调用链时，由 AI 自动命名还是询问用户 |\r\n| **默认重试次数** | 1-10（默认3） | 所有步骤的默认最大重试次数 |\r\n\r\n---\n\nFile v1.37.3:_meta.json\n\n{\n \"ownerId\": \"kn75zfd51df61ajdyqtgvrs1hx84s4q6\",\n \"slug\": \"skill-sub\",\n \"version\": \"1.37.3\",\n \"publishedAt\": 1783047330082\n}\n\nFile v1.37.3:references/adhesion.md\n\n# 粘连点（Adhesion Point）机制\n\n> **v1.25.0 新增**。粘连点是调用链中无法由 skill 自动化的缺口标记。\n\n---\n\n## 什么是粘连点\n\n粘连点是调用链中一个特殊类型的步骤（`type: \"adhesion\"`），标记该位置无法由任何已安装 skill 自动完成。它不会阻断调用链，而是提供三种解决方案供 LLM 选择。\n\n### 什么时候产生粘连点\n\n| 场景 | 触发条件 | 行为 |\n|------|---------|------|\n| **链修正** | 执行链时发现步骤与真实 skill 不符，修正后仍报错 | 在该步骤位置打粘连点 |\n| **链缺口** | 规划链时某步骤无对应 skill 可用 | 在缺失位置插入粘连点 |\n| **流程缺口分析** | 规划阶段发现语义/流程/决策缺口 | 在天然断裂处打粘连点（见下方规则） |\n\n### 三个核心原则\n\n1. **链不断** — 粘连点标记不阻断调用链执行，LLM 按方案继续\n2. **连接器，非替代品** — 粘连点是两个 skill 步骤之间的连接器，不是 skill 步骤的替代品。**禁止粘连点连粘连点**，连续缺口合并为一个粘连点\n3. **不创建 Skill** — 解决方案是步骤描述级别，产生的脚本/产出物归数据目录管理\n4. **自愈** — 每次使用含粘连点的链，主动检查是否有新 skill 可填补\n\n---\n\n## 缺口分析规则（规划阶段）\n\n在创建调用链的步骤 3→4 之间插入流程缺口分析，按以下规则判断：\n\n### 三种真实缺口\n\n| 缺口类型 | 判断依据 | 应打粘连点？ | 方案优先级 |\n|---------|---------|------------|-----------|\n| **语义缺口** | Skill A 输出格式/内容 ≠ Skill B 期望输入 | ✅ 数据转换步骤 | hybrid |\n| **流程缺口** | 用户任务中的某个环节无任何 skill 覆盖 | ✅ 补充缺失步骤 | auto / manual |\n| **决策缺口** | 需要人工审批、判断、签字的节点 | ✅ 人工审批节点 | manual |\n| **自然衔接** | Skill A 输出可直接作为 Skill B 输入 | ❌ 不打 | — |\n\n### 禁止行为\n\n| 禁令 | 说明 |\n|------|------|\n| ❌ 不要制造缺口 | 自然衔接的 skill 不打粘连点 |\n| ❌ 不要粘连点连粘连点 | **连续缺口合并为一个粘连点** |\n| ❌ 不要替代 skill | 能用 skill 完成的直接用 skill |\n| ❌ 不要过度粘连 | 粘连点数量应远少于 skill 步骤数 |\n\n### 判定示例\n\n```text\n用户需求：分析代码 → 生成报告 → 发送邮件\n\n✓ 正确：\n 步骤1: code-analysis (skill) — 分析代码\n 步骤2: report-generation (adhesion) — JSON→Markdown 语义缺口\n 步骤3: email-send (skill) — 发送邮件\n\n✓ 连续缺口合并：\n 步骤1: code-analysis (skill)\n → 步骤2: data-cleanup (缺失) — 两个连续缺失合并为一个粘连点\n → 步骤3: transform (缺失) — 🔴 禁止！应为：\n 步骤2: data-pipeline (adhesion, hybrid) — 覆盖清洗+转换的完整缺口\n 步骤3: email-send (skill)\n\n✗ 过度粘连：\n 步骤1: code-analysis (skill)\n 步骤2: report-generation (adhesion) — ❌ 如果有 report skill 就不该打\n 步骤3: email-send (skill)\n\n✗ 粘连点连粘连点（禁止）：\n 步骤1: code-analysis (skill)\n 步骤2: manual-review (adhesion) — ❌ 连续两个粘连点\n 步骤3: data-transform (adhesion) — ❌ 应合并为一个\n 步骤4: email-send (skill)\n```\n\n---\n\n## 三种解决方案\n\n### ① 纯手工（manual）\n\nLLM 直接手动执行步骤，不依赖脚本或新 skill。\n\n```json\n{\"mode\": \"manual\", \"description\": \"人工审核报告\", \"constraints\": \"需关注数据准确性\"}\n```\n\n**适用场景**：一次性、高度灵活的判断任务。\n\n### ② 脚本化（auto）\n\n通过自调用脚本工具执行，产生的脚本入数据目录管理。\n\n```json\n{\"mode\": \"auto\", \"tool_name\": \"report-verify\", \"script_path\": \"scripts/verify.sh\"}\n```\n\n**适用场景**：可标准化、重复执行的任务。\n\n### ③ 混合（hybrid）\n\nLLM 描述流程步骤 + 约束 + 自调用工具协同执行。\n\n```json\n{\n \"mode\": \"hybrid\",\n \"llm_steps\": \"LLM 阅读报告并给出审核意见\",\n \"tool_steps\": \"脚本验证报告中的数字准确性\",\n \"integration\": \"LLM 分析文本，工具验证数字\"\n}\n```\n\n**适用场景**：需要智能判断 + 自动化执行的复合任务。\n\n---\n\n## 执行优先级\n\nAI 执行粘连点步骤时，按以下优先级选择方案：\n\n1. **hybrid** — 最优先，组合 LLM + 工具的最大能力\n2. **auto** — 次优先，能脚本化就不手动\n3. **manual** — 兜底，LLM 直接执行\n\n---\n\n## 自愈机制\n\n每次加载含粘连点的调用链时，AI 执行自愈检查：\n\n```\n1. 扫描 skill 库（skill-sub 所在目录的兄弟目录）\n2. 对每个粘连点，用 adhesion.reason 关键词搜索 SKILL.md\n3. 找到匹配 → 将 adhesion 步骤升级为 skill 步骤\n - type 改为 \"skill\"\n - 填充 skill_name / action\n - 原 adhesion.solutions 写入 notes\n4. 未找到 → 按原有 3 方案执行\n```\n\n也可手动触发：`python chain_manager.py check-gaps`\n\n---\n\n## 与 chain_executor 集成\n\n`chain_executor.py` 在执行计划中渲染粘连点步骤：\n\n```text\n### 步骤 3.5: 报告审核\n⚠️ 粘连点 — 原因：缺少对应 skill 的自动化能力\n 方案1 [混合]：LLM 审核 + 脚本验证\n LLM: 阅读报告并给出审核意见\n 工具: 脚本验证报告中的数字准确性\n 方案2 [纯手工]：完全由 LLM 手工审核报告\n```\n\n---\n\n## 数据目录\n\n粘连点相关的脚本和产出物存放在以下位置，遵循 skill-sub 的数据目录规范：\n\n```\n.standardization/skill-sub/data/\n├── outputs/ # 脚本化方案产生的输出\n└── scripts/ # 自调用工具脚本（auto/hybrid 模式）\n```\n\nFile v1.37.3:references/antipatterns.md\n\n# skill-sub 反模式\r\n\r\n> 本文档收录 skill-sub 使用中的常见错误和正确做法。完整反模式示例见 `references/faq.md`。\r\n\r\n---\r\n\r\n## AP-01：把 skill-sub 编入调用链\r\n\r\n**错误做法：**创建调用链时把 `skill-sub` 作为一个步骤加入。\r\n\r\n```\r\n步骤1: skill-sub → 规划\r\n步骤2: xxx\r\n```\r\n\r\n**为什么错：**skill-sub 是编辑器/规划器，不是执行器。链需要的是\"谁干活\"，skill-sub 不干活。\r\n\r\n**正确做法：**调用链只包含执行型 Skill（如 semantic-split、git-sync），不包含 skill-sub 本身。\r\n\r\n---\r\n\r\n## AP-02：为一次性任务创建调用链\r\n\r\n**错误做法：**用户说「帮我查一下今天天气」，就创建一个\"天气查询\"调用链。\r\n\r\n**为什么错：**调用链的价值是复用。一次性任务下次不会用到，反而积累垃圾链。\r\n\r\n**正确做法：**判断任务是否有复用价值。以下信号表明值得创建链：\r\n- 用户说「每次」「以后也」「下次」\r\n- 涉及 ≥3 个 Skill 协作\r\n- 有明确的输入→输出模式\r\n\r\n---\r\n\r\n## AP-03：跳过摘取阶段，直接写 action\r\n\r\n**错误做法：**不读目标 Skill 的 SKILL.md，凭记忆写 action 描述。\r\n\r\n```json\r\n{\"action\": \"执行安全审计\"} // 太模糊，实际执行时不知道具体做什么\r\n```\r\n\r\n**为什么错：**action 是执行时的唯一指引。不读 Skill 原文会导致遗漏关键步骤或用错指令名。\r\n\r\n**正确做法：**执行阶段2摘取——读取目标 Skill 的 SKILL.md「工作流程」章节，摘取步骤名+关键动作+指令名。action 要包含具体的**做什么**（动词+对象+产出）。\r\n\r\n---\r\n\r\n## AP-04：把所有步骤都标为里程碑\r\n\r\n**错误做法：**3 步的链，全标 `is_milestone: true`。\r\n\r\n**为什么错：**里程碑=失败即中止。全标等于没有区分，任何一步失败都中止，丧失灵活性。\r\n\r\n**正确做法：**用里程碑判断规则（关键词/瓶颈点/最终交付）自动判断，只对关键步骤标里程碑。非关键步骤用 `on_exhaust: ask` 或 `skip` 而非 `abort`。\r\n\r\n---\r\n\r\n## AP-05：依赖关系写错导致链无法执行\r\n\r\n**错误做法：**\r\n```json\r\n{\"index\": 1, \"depends_on\": []},\r\n{\"index\": 2, \"depends_on\": [3]}, // 依赖了后面的步骤！\r\n{\"index\": 3, \"depends_on\": [1]}\r\n```\r\n\r\n**为什么错：**步骤2依赖步骤3，但步骤3在步骤2之后执行——死锁。\r\n\r\n**正确做法：**`depends_on` 只能引用 `index` 小于自己的步骤。创建后用 `chain_executor.py validate` 检查。\r\n\r\n---\r\n\r\n> 更多反模式与正确做法 → `references/faq.md`\n\nFile v1.37.3:references/chain_schema.md\n\n# skill-sub 调用链数据结构\r\n\r\n> 本文档定义 Chain / Step / retry_policy / failure_mode 的完整结构。\r\n>\r\n> **v1.20.0 新增**：Step 支持三种类型（skill / loop / branch），详见 Step 扩展类型章节。\r\n\r\n---\r\n\r\n## Chain（调用链）\r\n\r\n```json\r\n{\r\n \"name\": \"string\", // 唯一名称\r\n \"description\": \"string\", // 调用链描述\r\n \"purpose\": \"string\", // 核心目的\r\n \"user_intent\": \"string\", // 用户原始意图（用于意图匹配）\r\n \"tags\": [\"string\"], // 标签（用于自动匹配）\r\n \"auto_safe\": true, // 链是否可不经人工介入全自动执行（由 flow_validator 自动计算）\r\n \"user_specified\": false, // 用户是否显式指定了所有 skill（true→自愈时跳过）\r\n \"schedule\": null, // 调度配置（可选），见下方 Schedule 定义\r\n \"created_at\": \"datetime\",\r\n \"updated_at\": \"datetime\",\r\n \"exec_count\": 0, // 执行次数\r\n \"steps\": [ ... ] // Step 数组，见下文\r\n}\r\n```\r\n\r\n---\r\n\r\n## Schedule（调度配置）\r\n\r\n> 链的调度元数据，任何平台可据此创建定时任务。不绑定具体平台。\r\n\r\n```json\r\n{\r\n \"type\": \"cron\", // \"cron\" | \"interval\" | \"once\"\r\n \"expression\": \"0 6 * * *\", // cron 表达式 / 间隔秒数 / 触发时间\r\n \"description\": \"每天早上6点执行\", // 自然语言描述\r\n \"registered\": false // 是否已在平台注册（创建时为 false，注册后改为 true）\r\n}\r\n```\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `type` | string | ✅ | `\"cron\"`（cron 表达式）、`\"interval\"`（间隔秒数）、`\"once\"`（单次执行） |\r\n| `expression` | string | ✅ | cron 格式（如 `\"0 6 * * *\"`）或间隔秒数（如 `\"86400\"`）或 ISO 时间（如 `\"2026-06-03T06:00:00\"`） |\r\n| `description` | string | ❌ | 自然语言描述，便于跨平台理解 |\r\n| `registered` | bool | ❌ | 注册标记。创建时默认 `false`，平台注册后改为 `true` |\r\n\r\n### 注册流程\r\n\r\n1. 链创建时 `schedule.registered = false`\r\n2. `chain_executor.py plan` 检测到 `registered == false` 时，在计划顶部输出 **强制注册提醒**\r\n3. 平台读取 `schedule` 字段，完成注册后将 `registered` 置为 `true`\r\n4. 已注册的链 `plan` 输出不再显示注册提醒\r\n\r\n### type 说明\r\n\r\n| type | expression 示例 | 含义 |\r\n|------|----------------|------|\r\n| `cron` | `\"0 6 * * *\"` | 每天早上 6 点 |\r\n| `cron` | `\"0 0 * * 1\"` | 每周一零点 |\r\n| `cron` | `\"0 0 1 * *\"` | 每月 1 日零点 |\r\n| `interval` | `\"3600\"` | 每小时执行一次 |\r\n| `interval` | `\"86400\"` | 每天执行一次 |\r\n| `once` | `\"2026-06-03T06:00:00\"` | 2026年6月3日6点执行一次 |\r\n\r\n### 使用方式\r\n\r\n- **创建链时**：用户在意图中描述定时需求（如「每天早上6点跑这个链」），AI 自动填充 `schedule` 字段\r\n- **已有链**：通过 `chain_manager.py schedule --name <链名> --cron \"0 6 * * *\" --desc \"每天6点\"` 添加/修改\r\n- **平台侧**：读取 `chain_data.schedule`，按 `type` + `expression` 注册定时任务\r\n\r\n---\r\n\r\n## Step（步骤）\r\n\r\n> **步骤类型**：通过 `type` 字段区分技能调用、循环、分支。默认 `type: \"skill\"`。\r\n> `steps` / `if_steps` / `else_steps` 均为 Step 数组，支持递归嵌套。\r\n\r\n### 通用字段（所有类型均含）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `index` | int | ✅ | 步骤序号（从 1 开始，全局唯一） |\r\n| `type` | string | ✅ | `\"skill\"` / `\"loop\"` / `\"branch\"` |\r\n| `step_name` | string | ✅ | 步骤名称（展示用） |\r\n| `depends_on` | int[] | ❌ | 依赖的前置步骤索引，默认 `[index-1]` |\r\n| `condition` | string | ❌ | 步骤级条件：非 `\"always\"` 时按需求值，为 `false` 则跳过本步骤 |\r\n| `failure_mode` | object | ❌ | 失败处理（见下文） |\r\n| `notes` | string | ❌ | 备注 |\r\n\r\n---\r\n\r\n### 类型 A：`\"type\": \"skill\"`（技能调用步骤）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `skill_name` | string | ✅ | 调用的技能名称（须已安装） |\r\n| `action` | string | ✅ | 精炼动作描述（第一层执行用） |\r\n| `skill_instruction` | string | ❌ | 对应 SKILL.md 中的指令名（第二层回退用） |\r\n| `detail` | string | ❌ | 详细执行说明（第三层回退用） |\r\n| `variables` | object | ❌ | 步骤级变量映射 `{\"input\": \"{{step1.output}}\", \"output\": \"result\"}` |\r\n| `retry_policy` | object | ❌ | 重试策略（见下文） |\r\n\r\n**示例：**\r\n\r\n```json\r\n{\r\n \"index\": 1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"代码审查\",\r\n \"skill_name\": \"code-review\",\r\n \"action\": \"审查 PR #123 的代码更新\",\r\n \"skill_instruction\": \"review-pr\",\r\n \"depends_on\": [],\r\n \"condition\": \"always\",\r\n \"variables\": {\"input\": \"{{pr_number}}\", \"output\": \"review_result\"},\r\n \"retry_policy\": {\"max_retries\": 3, \"error_types\": [\"network_error\", \"timeout\"]},\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false},\r\n \"notes\": \"第一步，不依赖其他步骤\"\r\n}\r\n```\r\n\r\n---\r\n\r\n### 类型 B：`\"type\": \"loop\"`（循环步骤）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `loop.mode` | string | ✅ | `\"for_each\"` 或 `\"while\"` |\r\n| `loop.items` | string | 条件① | `for_each` 模式：表达式，求值结果为数组 |\r\n| `loop.while_condition` | string | 条件① | `while` 模式：布尔表达式，求值结果为 `true`/`false` |\r\n| `loop.loop_variable` | string | 条件② | `for_each` 模式：迭代变量名，循环体内用 `{{变量名}}` 引用当前元素 |\r\n| `loop.steps` | Step[] | ✅ | 循环体（Step 数组，递归支持 skill/loop/branch） |\r\n| `loop.max_iterations` | int | ❌ | 安全上限，默认 `10`；达到时按 `on_max_iteration` 处理 |\r\n| `loop.on_max_iteration` | string | ❌ | `\"break\"`（中止循环）或 `\"continue\"`（记录警告并继续） |\r\n\r\n> ① `for_each` 需要 `items` + `loop_variable`；`while` 需要 `while_condition`。\r\n> ② 循环体内步骤可访问 `{{loop_variable}}`（for_each）及父步骤的 `variables`。\r\n\r\n**示例 1：for_each 循环**\r\n\r\n```json\r\n{\r\n \"index\": 2,\r\n \"type\": \"loop\",\r\n \"step_name\": \"批量代码审查\",\r\n \"loop\": {\r\n \"mode\": \"for_each\",\r\n \"items\": \"{{pr_file_list}}\",\r\n \"loop_variable\": \"file\",\r\n \"steps\": [\r\n {\r\n \"index\": 2.1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"审查文件 {{file}}\",\r\n \"skill_name\": \"code-review\",\r\n \"action\": \"审查单个文件\",\r\n \"variables\": {\"input\": \"{{file}}\", \"output\": \"file_review\"}\r\n }\r\n ],\r\n \"max_iterations\": 20,\r\n \"on_max_iteration\": \"break\"\r\n },\r\n \"depends_on\": [1],\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false}\r\n}\r\n```\r\n\r\n**示例 2：while 循环**\r\n\r\n```json\r\n{\r\n \"index\": 3,\r\n \"type\": \"loop\",\r\n \"step_name\": \"重试直到成功\",\r\n \"loop\": {\r\n \"mode\": \"while\",\r\n \"while_condition\": \"{{retry_count}} < 3 && {{last_success}} == false\",\r\n \"steps\": [\r\n {\r\n \"index\": 3.1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"尝试部署\",\r\n \"skill_name\": \"deploy\",\r\n \"action\": \"执行部署\"\r\n }\r\n ],\r\n \"max_iterations\": 3,\r\n \"on_max_iteration\": \"break\"\r\n },\r\n \"failure_mode\": {\"on_exhaust\": \"abort\", \"is_milestone\": true}\r\n}\r\n```\r\n\r\n---\r\n\r\n### 类型 C：`\"type\": \"branch\"`（分支步骤）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `branch.condition` | string | ✅ | 布尔表达式，求值后为 `true` 或 `false` |\r\n| `branch.if_steps` | Step[] | ✅ | 条件为 `true` 时执行的步骤数组 |\r\n| `branch.else_steps` | Step[] | ❌ | 条件为 `false` 时执行的步骤数组（可选） |\r\n\r\n> ① `if_steps` 和 `else_steps` 均为 Step 数组，递归支持 skill / loop / branch。\r\n> ② 分支步骤本身不调用技能，仅做流程控制；`failure_mode` 作用于整个分支步骤（即 `if_steps` 全部失败时的行为）。\r\n\r\n**示例：if-else 分支**\r\n\r\n```json\r\n{\r\n \"index\": 4,\r\n \"type\": \"branch\",\r\n \"step_name\": \"按环境选择部署目标\",\r\n \"branch\": {\r\n \"condition\": \"{{env}} == 'production'\",\r\n \"if_steps\": [\r\n {\r\n \"index\": 4.1,\r\n \"type\": \"skill\",\r\n \"step_name\": \"生产环境部署\",\r\n \"skill_name\": \"deploy\",\r\n \"action\": \"部署到生产环境\",\r\n \"variables\": {\"input\": \"production\"}\r\n }\r\n ],\r\n \"else_steps\": [\r\n {\r\n \"index\": 4.2,\r\n \"type\": \"skill\",\r\n \"step_name\": \"预发环境部署\",\r\n \"skill_name\": \"deploy\",\r\n \"action\": \"部署到预发环境\",\r\n \"variables\": {\"input\": \"staging\"}\r\n }\r\n ]\r\n },\r\n \"depends_on\": [1, 2, 3],\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": true}\r\n}\r\n```\r\n\r\n---\r\n\r\n## retry_policy（重试策略）\r\n\r\n```json\r\n{\r\n \"max_retries\": 3, // 最大重试次数（默认从配置读取，默认 3）\r\n \"error_types\": [\"file_locked\", \"network_error\", \"timeout\", \"auth_error\"]\r\n}\r\n```\r\n\r\n**错误类型说明：**\r\n\r\n| 错误类型 | 重试间隔 | 说明 |\r\n|---------|---------|------|\r\n| `file_locked` | 0 秒 | 文件占用/锁定，立即重试 |\r\n| `network_error` | 5 秒 | 网络不通/超时 |\r\n| `timeout` | 5 秒 | 执行超时 |\r\n| `auth_error` | - | 认证/权限错误，直接询问用户 |\r\n| `other` | 2 秒 | 其他错误 |\r\n\r\n---\r\n\r\n## failure_mode（失败处理模式）\r\n\r\n```json\r\n{\r\n \"on_exhaust\": \"ask\", // 重试耗尽后行为: \"ask\" | \"skip\" | \"abort\"\r\n \"is_milestone\": false // 是否为里程碑步骤（可通过通用规则自动判断）\r\n}\r\n```\r\n\r\n**on_exhaust 行为说明：**\r\n\r\n| 值 | 说明 |\r\n|-----|------|\r\n| `ask` | 重试耗尽后询问用户 |\r\n| `skip` | 跳过该步骤，继续后续步骤 |\r\n| `abort` | 中止整条调用链 |\r\n\r\n**里程碑行为：**\r\n- **里程碑步骤失败** → 无论 `on_exhaust` 配置如何，**强制中止整条链**\r\n- **里程碑步骤的 on_exhaust** → 建议设为 `abort`（validate 时会发出警告）\r\n- **非里程碑步骤失败** → 按 `on_exhaust` 配置处理（ask/skip/abort）\r\n\r\n---\r\n\r\n## 类型 D：`\"type\": \"adhesion\"`（粘连点步骤）\r\n\r\n> **v1.25.0 新增**。粘连点标记调用链中无法由 skill 自动化的缺口，\r\n> 提供三种解决方案供 LLM 选择执行，保证调用链不断裂。\r\n\r\n### 通用字段（继承 Step 通用字段）\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `index` | int | ✅ | 步骤序号 |\r\n| `type` | string | ✅ | 固定为 `\"adhesion\"` |\r\n| `step_name` | string | ✅ | 步骤名称 |\r\n| `depends_on` | int[] | ❌ | 依赖的前置步骤索引 |\r\n\r\n### adhesion 专用字段\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `adhesion.reason` | string | ✅ | 粘连原因描述 |\r\n| `adhesion.solutions` | array | ✅ | 解决方案数组，至少 1 个 |\r\n| `adhesion.updated_at` | string | ❌ | 最后检查时间（自愈扫描时更新） |\r\n\r\n### solutions[n] 字段\r\n\r\n| 字段 | 类型 | 必填 | 说明 |\r\n|------|------|------|------|\r\n| `mode` | string | ✅ | `\"manual\"` / `\"auto\"` / `\"hybrid\"` |\r\n| `description` | string | ✅ | 执行描述 |\r\n| `constraints` | string | ❌ | 约束条件（manual/hybrid 使用） |\r\n| `tool_name` | string | 条件① | mode=auto/hybrid 时，工具名称 |\r\n| `script_path` | string | 条件① | mode=auto/hybrid 时，脚本路径（相对数据目录） |\r\n| `llm_steps` | string | 条件② | mode=hybrid 时，LLM 执行步骤 |\r\n| `tool_steps` | string | 条件② | mode=hybrid 时，工具执行步骤 |\r\n\r\n> ① auto/hybrid 模式至少提供 tool_name 或 script_path 之一\r\n> ② hybrid 模式必须同时提供 llm_steps + tool_steps\r\n\r\n### 三种 solution mode 说明\r\n\r\n| mode | 说明 | 适用场景 |\r\n|------|------|---------|\r\n| `manual` | LLM 直接手动执行步骤，不依赖脚本或新 skill | 一次性、高度灵活的判断任务 |\r\n| `auto` | 通过自调用脚本工具执行，产生的脚本入数据目录管理 | 可标准化、重复执行的任务 |\r\n| `hybrid` | LLM 描述流程步骤 + 约束 + 自调用工具协同执行 | 需要智能判断 + 自动化执行的复合任务 |\r\n\r\n### 自愈流程\r\n\r\n每次调用链执行时，AI 检查链中所有 `adhesion` 类型步骤：\r\n\r\n1. 扫描技能库（`scripts/` 目录或已安装技能）查找是否有新 skill 能填补该缺口\r\n2. 找到匹配 skill → 将 `adhesion` 步骤升级为 `skill` 类型步骤，保留原 `adhesion.solutions` 到 `notes` 字段\r\n3. 未找到 → 按 `adhesion.solutions` 中的方案执行（优先 hybrid → auto → manual）\r\n\r\n---\r\n\r\n## 条件表达式语法\r\n\r\n`condition` / `branch.condition` / `loop.while_condition` 支持以下语法：\r\n\r\n| 语法 | 示例 | 说明 |\r\n|------|------|------|\r\n| 步骤状态 | `step_1_success` | 步骤 1 成功（返回码 0） |\r\n| 步骤状态（否定） | `step_2_failed` | 步骤 2 失败 |\r\n| 变量存在 | `variable_OUTPUT_exists` | 变量 `OUTPUT` 已定义 |\r\n| 变量相等 | `{{env}} == 'production'` | 字符串比较 |\r\n| 变量数值 | `{{retry_count}} < 3` | 数值比较（`<` `>` `<=` `>=` `==` `!=`） |\r\n| 逻辑运算 | `step_1_success && step_2_success` | `&&`（与）、`||`（或）、`!`（非） |\r\n| 布尔常量 | `always` | 总是执行（默认） |\r\n| 布尔常量 | `never` | 永不执行 |\n\nFile v1.37.3:references/changelog.md\n\n## 1.27.1 (2026-06-05)\r\n\r\n### 修复\r\n- 全流程钩子加固: cmd_create缺口分析提示+创建后自动校验(结构+流程)+调度注册exit(1)截断\r\n\r\n---\r\n\r\n## 1.27.0 (2026-06-02)\r\n\r\n### 新增\r\n\r\n- **调度强制注册机制**：创建含 schedule 的链后**立即**输出强制注册提醒（不等执行日）；新增 register-schedule CLI 子命令将 registered 标记置为 true\r\n- **执行计划注册提醒**：chain_executor.py 检测未注册调度并输出强制提醒\r\n\r\n### 变更\r\n\r\n- **chain_manager.py**：新增 register-schedule CLI 子命令；创建成功后含 schedule 时立即输出强制注册提醒\r\n- **chain_executor.py**：新增 unregistered_schedule 检测，计划输出顶部含强制注册提醒\r\n- **chain_schema.md**：schedule 定义新增 registered 字段，含注册流程说明\r\n- **SKILL.md**：工作流程步骤 5 改为「立即注册调度」，明确不等手动执行\r\n\r\n---\r\n\r\n## 1.26.0 (2026-06-02)\r\n\r\n### 新增\r\n\r\n- **粘连点（Adhesion Point）系统**：新增第四种步骤类型 `type: \"adhesion\"`，标记调用链中无法由 skill 自动化的缺口，提供三种解决方案（manual/auto/hybrid）保证链不断\r\n- **链自愈机制**：新增 `check-gaps` 命令，扫描所有调用链的粘连点，自动检测是否有新 skill 可填补并升级为 skill 步骤；`user_specified: true` 的链跳过自愈\r\n- **执行计划渲染**：`chain_executor.py` 在计划中渲染粘连点步骤，展示原因和 3 种方案\r\n- **流程缺口分析**：创建调用链时新增流程缺口分析，按语义/流程/决策三类真实缺口判断是否打粘连点；明确禁止过度粘连\r\n- **算法组件**：新增 `chain_flow_validator.py`（步骤连续性/依赖链/孤立步骤/粘连点比例≤30%/禁止连续粘连点）和 `chain_structure_checker.py`（JSON 结构/类型枚举/必填字段/依赖闭环——最后一道关，不合格拒保存）\r\n- **skill_extractor suggest**：新增 `suggest` 子命令，根据用户意图关键词匹配 skill 并排序候选，检测未匹配缺口（Python 扫描+LLM 选最终集合的混合模式）\r\n- **能力边界文档**：SKILL.md 新增「能力边界与限制」章节，含适宜/不适宜场景表、硬限制表、常见创建错误速查\r\n- **FAQ 错误场景**：faq.md 新增 E1~E4 四个常见错误场景（粘连点连续、skill 不存在、步骤失败、校验器阻断），每条报错附原因和解决方法\r\n- **调度配置系统**：新增 `schedule` 元数据字段（type/expression/description/registered），任何平台可据此创建定时任务；新增 `chain_manager.py schedule` 子命令；创建链时描述含定时关键词（每天/每周/自动等）强制要求 `--schedule` 参数，否则阻断\r\n- **auto_safe 自动化检测**：`chain_flow_validator` 自动计算链是否可全自动执行（无 manual 粘连点且无 ask 模式），输出 `auto_safe` 布尔字段供平台使用\r\n- **调度强制注册机制**：创建含 `schedule` 的链后**立即**输出强制注册提醒（不等执行日）；新增 `register-schedule` CLI 子命令将 `registered` 标记置为 `true`；`chain_executor.py` 执行计划检测未注册调度并输出强制提醒\r\n\r\n### 变更\r\n\r\n- **`chain_manager.py`**：`validate_chain` 适配 adhesion 类型；新增 `check-gaps` / `schedule` / `register-schedule` CLI 子命令；`create_chain` 和 `update` 自动调用 `flow_validator` + `structure_checker` 校验；新增 `user_specified`、`schedule` 字段和对应 CLI 参数；新增定时关键词强制检测逻辑；创建成功后含 schedule 时立即输出强制注册提醒\r\n- **`chain_schema.md`**：新增类型 D 粘连点步骤、`user_specified` 字段、`auto_safe` 字段、`schedule` 字段（含 `registered`）及 Schedule 定义章节\r\n- **`chain_executor.py`**：新增 `unregistered_schedule` 检测，计划输出顶部含强制注册提醒（`registered=false` 时）\r\n- **`workflow.md`**：创建流程从 7 步扩展为 8 步，新增步骤 6 流程+结构双重校验\r\n- **`adhesion.md`**：补充缺口分析规则、禁止行为清单、连续粘连点合并规则、判定示例\r\n- **`SKILL.md`**：核心能力新增第 7 项粘连点支持；工作流程新增步骤 3 流程缺口分析；快速开始重写为「三步上手」含完整 JSON 示例；新增「能力边界与限制」章节\r\n- **`faq.md`**：新增 E1~E4 常见错误场景\r\n- **`chain_executor.py`**：新增 `unregistered_schedule` 检测，计划输出顶部含强制注册提醒\r\n\r\n---\r\n\r\n## 1.24.10 (2026-06-01)\r\n\r\n### 修复\r\n- 清除H1后冗余反模式引用\r\n\r\n---\r\n\r\n## 1.24.9 (2026-06-01)\r\n\r\n### 修复\r\n- 清除H1后冗余反模式引用\r\n\r\n---\r\n\r\n## 1.24.8 (2026-06-01)\r\n\r\n### 修复\r\n- 标准化改造最终版\r\n\r\n---\r\n\r\n## 1.24.7 (2026-06-01)\r\n\r\n### 修复\r\n- 版本追平仓库\r\n\r\n---\r\n\r\n## 1.24.6 (2026-06-01)\r\n\r\n### 修复\r\n- 标准化改造完成(非标章节处理+description同步)\r\n\r\n---\r\n\r\n## 1.24.5 (2026-06-01)\r\n\r\n### 修复\r\n- audit --fix 自动修正: meta_field_sync, writing_standards\r\n\r\n---\r\n\r\n## 1.24.4 (2026-06-01)\r\n\r\n### 修复\r\n- 标准化改造完成\r\n\r\n---\r\n\r\n## 1.24.3 (2026-06-01)\r\n\r\n### 修复\r\n- 版本追平changelog\r\n\r\n---\r\n\r\n## 1.24.2 (2026-06-01)\r\n\r\n### 修复\r\n- 标准化改造：章节重排+索引表+非标章节处理\r\n\r\n---\r\n\r\n## 1.24.7 (2026-06-01)\r\n\r\n### 修复\r\n- C-13索引表补全\r\n\r\n---\r\n\r\n## 1.24.6 (2026-06-01)\r\n\r\n### 修复\r\n- 从1.24.1恢复，仅添加索引表+顺序修正+R-10/R-20同步\r\n\r\n---\r\n\r\n## 1.24.5 (2026-06-01)\r\n\r\n### 修复\r\n- 版本追平\r\n\r\n---\r\n\r\n## 1.24.4 (2026-06-01)\r\n\r\n### 修复\r\n- 恢复原始版本后仅保留索引表+description 同步\r\n\r\n---\r\n\r\n## 1.24.3 (2026-06-01)\r\n\r\n### 修复\r\n- 标准化修复：渐进式索引表 + 章节顺序修正\r\n\r\n---\r\n\r\n## 1.24.1 (2026-05-31)\r\n\r\n### 修复\r\n- 补回缺失的 H1 标题（）\r\n- R-25 C-07: 3 个代码块补充语言标识\r\n- R-25 C-10: 精简 frontmatter 后多余空行\r\n\r\n---\r\n## 1.24.0 (2026-05-31)\r\n\r\n### Changed（skill-standardization 规范化改造）\r\n- **SKILL.md 全面重构** — frontmatter 补充 trigger/trigger_negative 字段；description 删除版本号（R-04 修复）；删除 H1 版本号（R-06 修复）；清理冗余空白行和历史性内容\r\n- **_meta.json 同步修复** — 补全 data_dir 字段（同步 SKILL.md frontmatter）；tags 与 SKILL.md 同步；补全 triggers 字段；R-12 合规\r\n- **references/changelog.md** — 版本号去除 v 前缀，使用纯数字 SemVer 格式（R-10 修复）\r\n- **references/faq.md** — 删除与 antipatterns.md 重复的反模式内容，专注 FAQ + 使用技巧；修正文档描述\r\n- **references/reference.md** — CLI 命令补全 `{SKILL_DIR}/scripts/` 路径前缀，确保从任意目录可执行\r\n- **references/workflow.md** — 修正配置路径错误（`scripts/default_config.json` → `config.json`）\r\n- **scripts/ 目录清理** — 删除 13 个 .bak 备份文件和 9 个历史 patch/fix 脚本，仅保留 7 个活动文件\r\n\r\n---\r\n\r\n## 1.23.4 (2026-05-30)\r\n\r\n### 修复\r\n- audit --fix 自动修正\r\n\r\n---\r\n\r\n## 1.23.3 (2026-05-30) — R-12 合规完善\r\n\r\n### Changed\r\n- 所有脚本补充 DEFAULT_DATA_DIR_RAW + DATA_DIR R-12 定义\r\n- _meta.json 补充 data_dir 字段\r\n- 运行 fix_missing_data_dir 一键修复，R-12 审计通过\r\n\r\n\r\n## 1.23.0 (2026-05-27)\r\n\r\n### 修复（R-11 路径规范）\r\n- **assets/ 目录迁移** — `assets/` 目录下的 `default_config.json` 和 `settings.html` 迁移到 `scripts/`\r\n- **路径引用修正** — `chain_manager.py`、`chain_executor.py`、`settings.py` 中的 `assets/` 路径统一改为 `scripts/`\r\n- **assets/ 目录删除** — 符合 R-11 规则（产出物必须在 `scripts/` 或根目录）\r\n\r\n---\r\n## 1.22.0 (2026-05-26)\r\n\r\n### 面向对象（OO）改造\r\n- **chain_executor.py** — 全面 OO 改造，拆分为 7 个类：\r\n - `Config` — 配置管理（加载默认配置 + 用户配置合并）\r\n - `PathManager` — 路径管理（技能目录、调用链目录、技能查找）\r\n - `Validator` — 验证器（里程碑判断、retry_policy/failure_mode 验证）\r\n - `TopoSorter` — 拓扑排序器（子步骤依赖排序、递归处理 loop/branch）\r\n - `ExecutionPlanBuilder` — 执行计划构建器（构建执行计划、收集技能名称、生成 AI 指令）\r\n - `InstructionGenerator` — AI 指令生成器（独立类，处理 loop/branch 步骤的指令渲染）\r\n - `CLIHandler` — CLI 处理器（plan/quick/validate 命令处理）\r\n- **chain_manager.py** — 全面 OO 改造，拆分为 7 个类：\r\n - `ConfigManager` — 配置管理器（加载/保存用户配置）\r\n - `PathManager` — 路径管理器（调用链目录、索引文件、技能目录、状态/日志目录）\r\n - `ChainValidator` — 调用链验证器（里程碑判断、调用链数据验证）\r\n - `BackupManager` — 备份管理器（自动备份、备份列表、备份恢复）\r\n - `ChainManager` — 调用链管理器（加载/保存索引、加载/保存/删除调用链、列表）\r\n - `ChainEditor` — 调用链编辑器（创建/更新/删除调用链、添加/删除步骤）\r\n - `CLIHandler` — CLI 命令处理器（init/create/list/show 命令处理）\r\n- **可维护性提升** — 原 1000+ 行函数式代码拆分为职责单一的类方法，便于单元测试和后续扩展\r\n- **SKILL.md 更新** — 修正快速开始代码块中的文件名引用（`chain_manager_oo.py` → `chain_manager.py`、`chain_executor_oo.py` → `chain_executor.py`）\r\n\r\n---\r\n\r\n## 1.21.0 (2026-05-26)\r\n\r\n### 新增功能（build_execution_plan 子步骤处理）\r\n- **子步骤拓扑排序** — `_topo_sort_substeps(steps)` 递归对 loop/branch 内的子步骤按 depends_on 依赖关系进行拓扑排序，替代原来的数组顺序执行\r\n- **递归步骤计数** — `_count_all_steps(steps)` 递归统计所有步骤数（含 loop 子步骤 for_each 迭代次数、while 预估、branch 最大分支），total_steps 计算现在准确\r\n- **build_execution_plan() 接入** — 在生成执行计划时自动对 loop/branch 子步骤进行拓扑排序，并调用 _count_all_steps() 计算准确的 total_steps\r\n\r\n---\r\n\r\n### 修复\r\n\r\n---\r\n\r\n# skill-sub 更新日志\r\n## 1.20.0 (2026-05-26)\r\n\r\n### 新增功能（高级编排）\r\n- **循环步骤（Loop Step）** — `type: \"loop\"` 支持 `for_each` / `while` 两种模式，可嵌套子步骤\r\n- **分支步骤（Branch Step）** — `type: \"branch\"` 支持 `if_steps` / `else_steps` 条件分支，可嵌套子步骤\r\n- **递归渲染引擎** — `loop_branch_renderer.py` 独立模块，支持 `skill` / `loop` / `branch` 步骤的递归 AI 指令渲染\r\n- **`chain_schema.md` 扩展** — 新增 `type` 字段定义，支持三种步骤类型及其子结构（`loop.*` / `branch.*`）\r\n- **`chain_executor.py` 接入** — `generate_ai_instructions()` 改为调用 `render_plan_with_loop_branch()`，完整支持循环/分支渲染\r\n\r\n---\r\n\r\n### 修复\r\n- `calc_intent_similarity()` 分词 bug：`chain_words` 未做 `re.findall` 分词导致永远匹配不上；加入 `user_intent` 字段参与相似度计算\r\n- `cmd_error_stats()` 日志目录路径错误：`log_dir` 手工拼路径改为使用 `LOGS_DIR`；文件读取改 `with open()` 上下文管理器\r\n\r\n---\r\n\r\n## 1.19.1 (2026-05-25)\r\n\r\n### 修复（v1.19.0 虚假 DONE 项实际实现）\r\n- 里程碑影响分析（milestones）— 真正实现并注册到 parser\r\n- 动态里程碑（--dynamic）— 真正实现并注册到 parser\r\n- 里程碑统计（milestone-stats）— 真正实现并注册到 parser\r\n- 标签系统增强（list-tags）— 真正实现并注册到 parser\r\n- v1.19.0 仅标记 DONE 但未实现上述四项，v1.19.1 修复\r\n\r\n---\r\n\r\n## 1.19.0 (2026-05-24)\r\n\r\n### 新增功能\r\n- 链标签系统增强（Chain Tag System Enhancement）— `list-tags`\r\n- 链导入/导出（Chain Import/Export）— `import` / `export`\r\n- 步骤摘取器：参数提取（Parameter Extraction）\r\n- 步骤摘取器：兼容性检查（Compatibility Check）\r\n- 执行计划生成器：资源分析（Resource Analysis）\n\nFile v1.37.3:references/examples.md\n\n# skill-sub 使用示例\n\n> 本文档是 SKILL.md 的渐进式补充，提供完整使用示例。\n\n---\n\n## 示例 1：创建发布流水线调用链\n\n```\n用户：帮我创建一条发布流水线的调用链，包含安全审计、打包、推送\n\nAI：\n 1. 分析意图 → 需要 skills-security-check + 内置打包 + git-sync\n 2. 读取技能信息 → 提取关键步骤\n 3. 规划步骤：\n 步骤1: 安全审计 → 依赖:无 → 里程碑(关键词:审计)\n 步骤2: 打包 → 依赖:[1] → 非里程碑\n 步骤3: 推送代码 → 依赖:[2] → 里程碑(最后一步)\n 4. 展示确认\n 5. [配置: naming_mode=auto] → AI 命名为 \"发布流水线\"\n 6. 保存\n```\n\n**生成的调用链 JSON：**\n\n```json\n{\n \"name\": \"发布流水线\",\n \"description\": \"技能发布完整流程\",\n \"purpose\": \"一键发布技能到 SkillHub/ClawHub\",\n \"user_intent\": \"帮我打包发布这个技能\",\n \"tags\": [\"发布\", \"技能管理\"],\n \"steps\": [\n {\n \"index\": 1,\n \"skill_name\": \"skills-security-check\",\n \"step_name\": \"安全审计\",\n \"action\": \"对技能目录执行安全审计，检查敏感信息泄露\",\n \"skill_instruction\": \"security-audit\",\n \"depends_on\": [],\n \"retry_policy\": {\"max_retries\": 3},\n \"failure_mode\": {\"on_exhaust\": \"abort\", \"is_milestone\": true}\n },\n {\n \"index\": 2,\n \"skill_name\": \"(内置)\",\n \"step_name\": \"打包\",\n \"action\": \"按规范打包为 ZIP（仅含 SKILL.md、_meta.json、scripts/*.py）\",\n \"depends_on\": [1],\n \"retry_policy\": {\"max_retries\": 3},\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false}\n },\n {\n \"index\": 3,\n \"skill_name\": \"git-sync\",\n \"step_name\": \"推送代码\",\n \"action\": \"推送到 Gitee 和 GitHub 仓库\",\n \"depends_on\": [2],\n \"retry_policy\": {\"max_retries\": 3, \"error_types\": [\"network_error\", \"timeout\"]},\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": true}\n }\n ]\n}\n```\n\n---\n\n## 示例 2：执行调用链\n\n```\n用户：执行发布流水线\n\nAI：\n 1. 生成执行计划 → 3步，2个里程碑\n 2. 步骤1（安全审计）→ 第一层 action → ✅成功\n 3. 步骤2（打包）→ 第一层 action → ❌文件占用\n → 分级重试: file_locked → 立即重试 → ✅成功\n 4. 步骤3（推送代码）→ 第一层 action → ❌网络错误\n → 分级重试: network_error → 5秒后重试 → ✅成功\n 5. 汇报: 全部 3/3 步成功\n```\n\n---\n\n## 示例 3：查看里程碑判断依据\n\n```\n用户：查看发布流水线详情\n\nAI：\n 📌 调用链: 发布流水线\n ...\n 📐 里程碑判断依据:\n ★ 步骤1(安全审计): 关键词匹配: '审计'\n ○ 步骤2(打包): 默认规则（非关键节点）\n ★ 步骤3(推送代码): 最终交付步骤\n```\n\n---\n\n## 示例 4：用 skill-sub 摘取步骤形成调用链\n\n> 注意：skill-sub 本身**不参与**调用链，它只负责摘取其他 skill 的步骤并形成调用链。\n\n**场景**：用户希望将\"语义理解 → 规划 → 三步循环执行 → 标准化审查\"这套流程固化为调用链。\n\n```\n用户：帮我创建一条\"标准化执行流水线\"调用链\n\nAI：\n 1. 分析意图 → 需要 semantic-split + triphasic-execution + skill-standardization\n 2. 读取技能信息：\n - semantic-split：提取关键步骤（语义拆分、规划生成）\n - triphasic-execution：提取三步循环步骤\n - skill-standardization：提取审查/改写步骤\n 3. 规划步骤：\n 步骤1: 语义理解 → 依赖:无 → 非里程碑\n 步骤2: 规划步骤 → 依赖:[1] → 非里程碑\n 步骤3: 三步循环执行 → 依赖:[2] → 里程碑\n 步骤4: 标准化审查 → 依赖:[3] → 里程碑(关键词:审查)\n 4. 展示确认\n 5. 保存为调用链 \"标准化执行流水线\"\n```\n\n**关键点**：调用链通过 `chain_manager.py` 保存为 JSON 文件，可复用，不绑定某一次具体任务。\n\n---\n\n## 使用技巧\n\n### 命名建议\n\n- **格式**：「动词+对象」（如「发布技能」「审查代码」「生成报告」）\n- **避免泛化名**：「通用流程」「测试链」→ 改名为「技能安全审计+发布」「用户注册流程测试」\n- **命名即意图**：好的名称让 `list` 一眼能看懂这条链干嘛\n\n### 里程碑配置经验\n\n| 场景 | 建议 |\n|------|------|\n| 安全/审计/部署步骤 | 必须标里程碑（失败不可接受） |\n| 数据生成/中间计算 | 非里程碑 + `on_exhaust: skip` |\n| 不确定是否关键 | 暂时非里程碑 + `on_exhaust: ask` |\n\n### 调用链生命周期\n\n1. **创建** → 命名 + 配置依赖 + 验证（`validate`）\n2. **试运行** → 用简单场景跑一次，看流程是否顺畅\n3. **调整** → 修 action 描述、调重试次数、改里程碑标记\n4. **复用** → 同类任务直接执行\n5. **清理** → 不再需要的链用 `delete --force` 删除，不用留\n\nFile v1.37.3:references/faq.md\n\n# skill-sub 常见问题\r\n\r\n> 本文档是 SKILL.md 的渐进式补充，收录常见问题与使用技巧。\r\n> 反模式详见 `references/antipatterns.md`。\r\n\r\n---\r\n\r\n## FAQ\r\n\r\n### Q1：调用链和脚本有什么区别？\r\n\r\n调用链是**声明式**的——描述\"做什么\"和\"谁来做\"，由 AI 按 action 执行。脚本是**命令式**的——精确指令序列，机器直接运行。\r\n\r\n| | 调用链 | 脚本 |\r\n|---|--------|------|\r\n| 执行者 | AI | 解释器 |\r\n| 容错 | 分级重试 + 询问 | 严格终止 |\r\n| 适用 | 跨 Skill 编排 | 单一工具链 |\r\n\r\n### Q2：如何判断一个任务该不该创建调用链？\r\n\r\n三个条件同时满足：\r\n1. 涉及 ≥2 个 Skill\r\n2. 有复用价值（不会只用一次）\r\n3. 步骤间的依赖关系可固化\r\n\r\n缺一则不适合。\r\n\r\n### Q3：调用链失败后怎么恢复？\r\n\r\n1. 查看失败步骤的 `on_exhaust` 配置\r\n2. 非里程碑 + `on_exhaust: ask` → AI 会询问你\r\n3. 非里程碑 + `on_exhaust: skip` → 已自动跳过\r\n4. 里程碑失败 → 链已中止，需修复后重新执行整条链\r\n5. 用 `chain_executor.py plan` 重新生成执行计划\r\n\r\n### Q4：配置里的\"记忆参考\"开启后有什么用？\r\n\r\n创建调用链时，AI 会额外读取 MEMORY.md 和近期日志，用于：\r\n- 个性化步骤描述（匹配你的命名习惯）\r\n- 推荐常用或相关的 Skill（基于历史使用模式）\r\n\r\n不开也不影响功能，只是步骤描述更通用。\r\n\r\n### Q5：为什么我的调用链执行时每一步都要问我？\r\n\r\n两个常见原因：\r\n1. 所有步骤配置了 `on_exhaust: ask` — 改为 `skip` 或 `abort` 减少交互\r\n2. 第1层 action 描述不够精确 — 执行时 AI 无法确定怎么做，只能问\r\n\r\n解决：创建链时确保每个 action 包含具体的动词+对象+产出。\r\n\r\n### Q6：skill-sub 的数据存在哪？更新会丢吗？\r\n\r\n数据存储在 `~/.workbuddy/skills/.standardization/skill-sub/`（可通过 `SKILL_SUB_HOME` 环境变量更新）：\r\n- `chains/` — 调用链 JSON 文件\r\n- `config.json` — 用户配置\r\n\r\n更新 skill-sub 本身（覆盖 SKILL.md + scripts/）**不会影响**数据目录。但注意这个路径不符合铁律4（产出物应在 `skills/.standardization/` 下），后续版本会迁移。\r\n\r\n---\r\n\r\n## 使用技巧\r\n\r\n1. **命名调用链要有规律** — 用「动词+对象」格式（如\"发布技能\"、\"审查代码\"），方便 `list` 时快速定位\r\n2. **action 写得越具体，执行越顺畅** — 好：「运行 `sensitive_scan.py scan ` 检查敏感信息」；差：「检查安全」\r\n3. **非里程碑步骤优先 `on_exhaust: skip`** — 减少人工介入，除非该步骤的产出被后续步骤强依赖\r\n4. **`tags` 不要随便填** — 它是自动推荐的匹配依据，填 `[\"通用\"]` 等于没填。用领域关键词：`[\"发布\",\"安全\",\"数据分析\"]`\r\n5. **定期清理不用的调用链** — `chain_manager.py list` 检查，`delete --force` 清理。链不是越多越好\r\n6. **里程碑只在\"失败不可接受\"的步骤用** — 如安全审计、部署上线。中间步骤失败通常可跳过或询问\r\n\r\n---\r\n\r\n## 常见错误场景\r\n\r\n### E1：创建链时报\"连续缺口应合并为一个粘连点\"\r\n\r\n**原因**：两个 `type: \"adhesion\"` 步骤相邻。粘连点是 skill 之间的连接器，禁止连续。\r\n\r\n**解决**：合并为一个 adhesion，用 hybrid 方案覆盖全部缺口。\r\n\r\n```json\r\n// 错误：两个连续粘连点\r\n{\"index\":2,\"type\":\"adhesion\",\"step_name\":\"审核\"},\r\n{\"index\":3,\"type\":\"adhesion\",\"step_name\":\"转换\"} // 禁止\r\n\r\n// 正确：合并为一个 hybrid 粘连点\r\n{\"index\":2,\"type\":\"adhesion\",\"step_name\":\"审核+转换\",\r\n \"adhesion\":{\"reason\":\"需要人工审核和数据格式转换\",\r\n \"solutions\":[{\"mode\":\"hybrid\",\"llm_steps\":\"人工审核\",\r\n \"tool_steps\":\"脚本转换格式\"}]}}\r\n```\r\n\r\n### E2：创建链时报\"引用的 skill 不存在\"\r\n\r\n**原因**：`skill_name` 对应的 skill 未安装或名称写错。\r\n\r\n**解决**：用 `python scripts/skill_extractor.py scan` 查看已安装 skill 列表。\r\n\r\n### E3：执行时报\"步骤失败\"\r\n\r\n| 原因 | 现象 | 解决 |\r\n|------|------|------|\r\n| action 描述模糊 | AI 反复确认 | 用具体动词+对象+产出重写 action |\r\n| 依赖的 skill 报错 | skill 本身执行失败 | 单独运行该 skill 确认 |\r\n| 里程碑步骤失败 | 整条链中止 | 修复后重新执行 |\r\n| 重试耗尽 | 超过 max_retries | 检查错误类型后修正重试 |\r\n\r\n### E4：校验器阻断保存\r\n\r\n| 阻断信息 | 原因 | 解决 |\r\n|---------|------|------|\r\n| 缺少必填字段 skill_name | skill 步骤没有指定 skill | 补充 skill_name |\r\n| 无效类型 'xxx' | type 不在 skill/loop/branch/adhesion 中 | 修正 type 字段 |\r\n| 检测到依赖闭环 | depends_on 形成循环 | 打破循环依赖 |\r\n| 索引重复 | 两个步骤相同 index | 使用 --fix 自动修复 |\n\nFile v1.37.3:references/permissions.md\n\n# 权限说明\n\n权限扫描风险等级：**MEDIUM**\n\n## 权限总览\n\n共 2 类权限风险，按类别分组如下：\n\n### 文件操作（1 项）\n> **权限作用**：创建/编辑/删除调用链 JSON 文件\n\n| # | 文件 | 行号 | 匹配内容 | 风险等级 | 授权方式 | 说明 |\n|---|------|------|----------|----------|----------|------|\n| 1 | `scripts/chain_manager.py` | 246, 366 | `open(` 写入 | 🟡 中 | 统一授权 | 创建/编辑/删除调用链 JSON 文件 |\n\n### 网络访问（1 项）\n> **权限作用**：启动本地 HTTP 服务器（配置界面）\n\n| # | 文件 | 行号 | 匹配内容 | 风险等级 | 授权方式 | 说明 |\n|---|------|------|----------|----------|----------|------|\n| 1 | `scripts/settings.py` | 19, 259 | `HTTPServer` | 🟡 中 | 统一授权 | 启动本地 HTTP 服务器（配置界面） |\n\n## 授权方式说明\n\n- **即时授权**：每次执行前需获得用户批准\n- **统一授权**：首次执行前获得用户批准，后续不再询问\n- **静默授权**：无需用户交互，自动执行并记录\n\n## 详细风险列表\n\n1. **[中] 文件操作（创建/编辑/删除调用链 JSON 文件）**\n - 位置：`scripts/chain_manager.py` 第 246 行（写入链）、第 366 行（写入配置）\n - 原因：中风险操作，首次执行前需用户确认\n - 缓解：`--force` 参数强制删除前需用户确认\n\n2. **[中] 网络访问（启动本地 HTTP 服务器）**\n - 位置：`scripts/settings.py` 第 19 行（导入）、第 259 行（启动）\n - 原因：中风险操作，首次执行前需用户确认\n - 缓解：仅监听 localhost，不对外暴露\n\n---\n\n**注**：本文件由 skill-standardization v2.24.0 自动生成（R-15 修复），实际风险等级由 `scripts/permission_checker.py` 扫描结果决定。\n\nFile v1.37.3:references/reference.md\n\n# skill-sub 参考手册\r\n\r\n> 本文档是 SKILL.md 的渐进式补充，包含完整 CLI 速查、脚本 API、存储格式。\r\n\r\n---\r\n\r\n## CLI 速查\r\n\r\n```bash\r\n# 初始化数据目录\r\npython {SKILL_DIR}/scripts/chain_manager.py init\r\n\r\n# 配置\r\npython {SKILL_DIR}/scripts/settings.py # 交互式配置（打开浏览器）\r\npython {SKILL_DIR}/scripts/settings.py --serve-only # Agent 模式\r\npython {SKILL_DIR}/scripts/settings.py --get-config # 查看配置\r\npython {SKILL_DIR}/scripts/settings.py --save-config '' # 保存配置\r\npython {SKILL_DIR}/scripts/chain_manager.py config # 查看配置\r\n\r\n# 创建调用链\r\npython {SKILL_DIR}/scripts/chain_manager.py create --name \"链名\" --description \"描述\" --purpose \"目的\" --steps '[...]'\r\n\r\n# 查询\r\npython {SKILL_DIR}/scripts/chain_manager.py list [--tag \"标签\"]\r\npython {SKILL_DIR}/scripts/chain_manager.py show --name \"链名\"\r\n\r\n# 执行\r\npython {SKILL_DIR}/scripts/chain_executor.py plan --name \"链名\" [-v] [--json]\r\npython {SKILL_DIR}/scripts/chain_executor.py quick --steps '[...]' --name \"临时\"\r\npython {SKILL_DIR}/scripts/chain_executor.py validate --name \"链名\"\r\n\r\n# 调整\r\npython {SKILL_DIR}/scripts/chain_manager.py add-step --name \"链名\" ...\r\npython {SKILL_DIR}/scripts/chain_manager.py remove-step --name \"链名\" --step N\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step N [--action ...] [--milestone] [--retry-max N]\r\npython {SKILL_DIR}/scripts/chain_manager.py rename --name \"旧名\" --new-name \"新名\"\r\n\r\n# 删除\r\npython {SKILL_DIR}/scripts/chain_manager.py delete --name \"链名\" --force\r\n```\r\n\r\n---\r\n\r\n## 脚本清单\r\n\r\n| 脚本 | 功能 |\r\n|------|------|\r\n| `chain_manager.py` | 调用链 CRUD（init/create/list/show/run/add-step/remove-step/update-step/rename/delete/config） |\r\n| `chain_executor.py` | 执行引擎（plan/quick/validate）+ 里程碑分类 + 配置集成 |\r\n| `skill_extractor.py` | 从 SKILL.md 提取关键步骤和指令名称（extract/scan） |\r\n| `settings.py` | HTML 配置界面 + CLI 配置管理 |\r\n\r\n---\r\n\r\n## 存储机制\r\n\r\n### 数据目录\r\n\r\n```\r\n~/.workbuddy/skills/.standardization/skill-sub/\r\n├── config.json # 用户配置（配置界面写入）\r\n└── chains/ # 调用链数据\r\n ├── index.json # 调用链索引\r\n ├── 发布流水线.json # 每条链一个文件\r\n └── ...\r\n```\r\n\r\n### 调用链 JSON 格式\r\n\r\n```json\r\n{\r\n \"name\": \"发布流水线\",\r\n \"description\": \"技能发布完整流程\",\r\n \"purpose\": \"一键发布技能到 SkillHub/ClawHub\",\r\n \"user_intent\": \"帮我打包发布这个技能\",\r\n \"tags\": [\"发布\", \"技能管理\"],\r\n \"created_at\": \"2026-05-21T15:00:00\",\r\n \"updated_at\": \"2026-05-21T19:00:00\",\r\n \"exec_count\": 5,\r\n \"steps\": [\r\n {\r\n \"index\": 1,\r\n \"skill_name\": \"skills-security-check\",\r\n \"step_name\": \"安全审计\",\r\n \"action\": \"对技能目录执行安全审计，检查敏感信息泄露\",\r\n \"skill_instruction\": \"security-audit\",\r\n \"depends_on\": [],\r\n \"retry_policy\": {\"max_retries\": 3},\r\n \"failure_mode\": {\"on_exhaust\": \"abort\", \"is_milestone\": true}\r\n },\r\n {\r\n \"index\": 2,\r\n \"skill_name\": \"(内置)\",\r\n \"step_name\": \"打包\",\r\n \"action\": \"按规范打包为 ZIP（仅含 SKILL.md、_meta.json、scripts/*.py）\",\r\n \"depends_on\": [1],\r\n \"retry_policy\": {\"max_retries\": 3},\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false}\r\n },\r\n {\r\n \"index\": 3,\r\n \"skill_name\": \"git-sync\",\r\n \"step_name\": \"推送代码\",\r\n \"action\": \"推送到 Gitee 和 GitHub 仓库\",\r\n \"depends_on\": [2],\r\n \"retry_policy\": {\"max_retries\": 3, \"error_types\": [\"network_error\", \"timeout\"]},\r\n \"failure_mode\": {\"on_exhaust\": \"ask\", \"is_milestone\": false}\r\n }\r\n ]\r\n}\r\n```\r\n\r\n---\r\n\r\n## 环境变量\r\n\r\n| 变量 | 说明 | 默认值 |\r\n|------|------|--------|\r\n| `SKILL_SUB_HOME` / `SKILL_CHAIN_HOME` | 数据目录 | `~/.workbuddy/skills/.standardization/skill-sub/` |\r\n| `WORKBUDDY_SKILLS_DIR` | 技能安装目录 | `~/.workbuddy/skills/` |\r\n\r\n---\r\n\r\n## 完整流程图\r\n\r\n```\r\n用户触发创建\r\n │\r\n ├─ 分析意图 → 确定需要哪些技能\r\n │\r\n ├─ 读取技能信息（skill_extractor.py scan）\r\n │ └─ [配置: 记忆参考=是] → 额外读取 MEMORY.md + 日志\r\n │\r\n ├─ 规划步骤（提取关键步骤 → 排列顺序 → 配置依赖）\r\n │\r\n ├─ 里程碑判断（classify_milestones 自动判断）\r\n │ ├─ 关键词匹配\r\n │ ├─ 瓶颈点检测\r\n │ └─ 最后一步标记\r\n │ └─ 展示判断依据 → 用户确认调整\r\n │\r\n ├─ 展示完整调用链 → 用户确认\r\n │\r\n └─ 命名保存\r\n ├─ [配置: naming_mode=auto] → AI 自动命名\r\n └─ [配置: naming_mode=manual] → 询问用户\r\n```\r\n\r\n```\r\n用户触发执行\r\n │\r\n ├─ 生成执行计划（chain_executor.py plan）\r\n │\r\n ├─ 逐步骤执行\r\n │ ├─ 第一层：用 action 直接执行\r\n │ ├─ 失败 → 分级重试（最多 N 次，N 从配置读取）\r\n │ ├─ 仍失败 → 按 on_exhaust 处理\r\n │ │ ├─ ask → 询问用户\r\n │ │ ├─ skip → 跳过，继续下一步\r\n │ │ └─ abort → 中止整条链\r\n │ │\r\n │ └─ 里程碑步骤失败 → 强制中止（无论 on_exhaust）\r\n │\r\n └─ 汇报结果\r\n```\r\n\r\n---\r\n\r\n## 权限权重说明（R-16）\r\n\r\n> 本节说明 `skill-sub` 各操作的权限权重，便于审查时评估风险。\r\n\r\n### 脚本权限分析\r\n\r\n| 脚本 | 敏感信息访问 | 关键位置写入 | 网络访问 | 文件删除 | Subprocess 调用 | 权重 |\r\n|------|--------------|--------------|----------|----------|-------------------|------|\r\n| `chain_manager.py` | 低（读 SKILL.md） | 中（写 `chains/` 目录） | 无 | 无 | 无 | **中** |\r\n| `chain_executor.py` | 低（读调用链） | 低（执行日志） | 无 | 无 | 中（调用其他 skill） | **中** |\r\n| `settings.py` | 低（读配置） | 低（写 `config.json`） | 无 | 无 | 无 | **低** |\r\n| `skill_extractor.py` | 低（读 SKILL.md） | 无 | 无 | 无 | 无 | **低** |\r\n\r\n### 授权方式\r\n\r\n- **低权重操作**（如查看调用链列表）：静默执行，无需授权\r\n- **中权重操作**（如创建/更新调用链）：统一授权（批量展示风险列表）\r\n- **高权重操作**（如删除调用链）：即时授权（执行前单独确认）\r\n\r\n### 风险缓解\r\n\r\n- 调用链数据存储在 `~/.workbuddy/skills/.standardization/skill-sub/chains/`，非技能核心目录\r\n- `chain_executor.py` 调用其他 skill 时，通过标准 `Skill` 工具调用，不执行任意命令\r\n- 配置文件中不含敏感信息（仅用户偏好配置）\n\nFile v1.37.3:references/workflow.md\n\n# skill-sub 详细工作流程\r\n\r\n> 本文档是 SKILL.md 的渐进式补充，详细描述执行流程、里程碑判断规则、三层回退策略。\r\n\r\n---\r\n\r\n## 完整执行流程\r\n\r\n### 创建调用链（create）\r\n\r\nAI 执行 7 步流程：\r\n\r\n1. **分析意图**：理解用户想串联哪些技能、达成什么目的\r\n2. **读取技能信息**：对每个涉及技能，运行 `skill_extractor.py scan` 提取关键步骤和指令\r\n3. **规划步骤**：确定步骤顺序、依赖关系、并行机会\r\n4. **流程缺口分析**：检查技能衔接处是否存在真实缺口，按以下三条规则判断（**禁止为了打粘连点而主动制造缺口**）\r\n\r\n ### 缺口规则\r\n\r\n | 缺口类型 | 说明 | 示例 | 是否打粘连点 |\r\n |---------|------|------|------------|\r\n | **语义缺口** | Skill A 的输出不是 Skill B 需要的输入格式/内容，需要转换 | 代码分析 skill 输出 JSON → 报告生成 skill 需要 Markdown | ✅ 需转换步骤 |\r\n | **流程缺口** | 用户任务流程中缺少某个环节，且无 skill 覆盖 | 编码→部署之间缺测试阶段，且无测试 skill | ✅ 需补充步骤 |\r\n | **决策缺口** | 需要人工判断/审批的节点 | 发布审批、PR Merge、方案决策 | ✅ 需人工节点 |\r\n | **自然衔接** | 两个 skill 输出输入天然匹配，无需额外转换 | 编译→运行测试、生成报告→发送通知 | ❌ 不需要 |\r\n\r\n ### 禁止行为\r\n\r\n - **不要为了有粘连点而故意制造缺口** — 自然衔接的 skill 步骤之间不打\r\n - **不要用粘连点替代 skill** — 如果一个 skill 能完成，直接用 skill 步骤\r\n - **不要过度粘连** — 一条调用链中粘连点数量应远少于 skill 步骤数\r\n\r\n5. **配置策略**：根据里程碑规则自动判断 + 用户确认调整\r\n6. **流程+结构校验**：自动调用 `chain_flow_validator` 和 `chain_structure_checker` 双重校验，不通过则拒绝保存\r\n7. **展示确认**：展示完整调用链供用户确认（包括里程碑标记、判断依据、粘连点信息）\r\n8. **命名保存**：根据配置决定自动命名或询问用户\r\n5. **展示确认**：展示完整调用链供用户确认（包括里程碑标记和判断依据）\r\n6. **命名保存**：根据配置决定自动命名或询问用户\r\n\r\n> **记忆参考（配置启用时）**：在步骤2后，读取 MEMORY.md 和近期日志，提取用户偏好和习惯，用于增强步骤描述的个性化。\r\n\r\n### 预生成（suggest）\r\n\r\n扫描已安装技能，推荐常用或相关的技能组合：\r\n\r\n```bash\r\npython {SKILL_DIR}/scripts/skill_extractor.py scan\r\n```\r\n\r\n### 查询（list / show）\r\n\r\n```bash\r\n# 列出所有调用链\r\npython {SKILL_DIR}/scripts/chain_manager.py list\r\npython {SKILL_DIR}/scripts/chain_manager.py list --tag \"发布\"\r\n\r\n# 查看详情（含里程碑判断依据）\r\npython {SKILL_DIR}/scripts/chain_manager.py show --name \"发布流水线\"\r\n\r\n# 查看当前配置\r\npython {SKILL_DIR}/scripts/chain_manager.py config\r\n```\r\n\r\n### 执行（run）\r\n\r\n三步执行流程：\r\n\r\n1. **生成执行计划**：`chain_executor.py plan --name <名称>`\r\n2. **按计划执行**：AI 读取执行计划，逐步执行\r\n3. **汇报结果**：每步执行后汇报 ✅/❌，里程碑步骤失败则中止\r\n\r\n### 调整（edit）\r\n\r\n```bash\r\n# 添加步骤\r\npython {SKILL_DIR}/scripts/chain_manager.py add-step --name \"链名\" --after 1 --skill \"技能名\" --step-name \"步骤名\" --action \"动作\"\r\n\r\n# 删除步骤\r\npython {SKILL_DIR}/scripts/chain_manager.py remove-step --name \"链名\" --step 3\r\n\r\n# 更新步骤\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step 2 --action \"新动作\"\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step 1 --milestone\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step 3 --no-milestone\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step 1 --retry-max 5\r\npython {SKILL_DIR}/scripts/chain_manager.py update-step --name \"链名\" --step 2 --on-exhaust abort\r\n\r\n# 重命名\r\npython {SKILL_DIR}/scripts/chain_manager.py rename --name \"旧名\" --new-name \"新名\"\r\n```\r\n\r\n### 删除（delete）\r\n\r\n```bash\r\npython {SKILL_DIR}/scripts/chain_manager.py delete --name \"链名\" --force\r\n```\r\n\r\n---\r\n\r\n## 循环与分支编排（v1.20.0 新增）\r\n\r\n### for-each 循环\r\n\r\n`type: \"loop\"` + `\"mode\": \"for_each\"`：遍历数组，对每个元素执行循环体。\r\n\r\n```json\r\n{\r\n \"type\": \"loop\",\r\n \"step_name\": \"批量处理\",\r\n \"loop\": {\r\n \"mode\": \"for_each\",\r\n \"items\": \"{{file_list}}\",\r\n \"loop_variable\": \"f\",\r\n \"max_iterations\": 10,\r\n \"steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"file-ops\", \"action\": \"处理 {{f}}\"}\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### while 循环\r\n\r\n`type: \"loop\"` + `\"mode\": \"while\"`：按条件重复执行，直到条件为假或达到最大次数。\r\n\r\n```json\r\n{\r\n \"type\": \"loop\",\r\n \"step_name\": \"重试直到成功\",\r\n \"loop\": {\r\n \"mode\": \"while\",\r\n \"while_condition\": \"{{retry_count}} < 3 and {{last_success}} == false\",\r\n \"max_iterations\": 3,\r\n \"steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"api-call\", \"action\": \"重试\"}\r\n ]\r\n }\r\n}\r\n```\r\n\r\n### if-else 分支\r\n\r\n`type: \"branch\"`：根据条件选择执行 `if_steps` 或 `else_steps`。\r\n\r\n```json\r\n{\r\n \"type\": \"branch\",\r\n \"step_name\": \"按环境部署\",\r\n \"branch\": {\r\n \"condition\": \"{{env}} == 'prod'\",\r\n \"if_steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"deploy\", \"action\": \"部署到生产\"}\r\n ],\r\n \"else_steps\": [\r\n {\"type\": \"skill\", \"skill_name\": \"deploy\", \"action\": \"部署到预发\"}\r\n ]\r\n }\r\n}\r\n```\r\n\r\n> 📚 完整 schema 参见 `chain_schema.md`\r\n\r\n---\r\n\r\n## 里程碑通用判断规则\r\n\r\n> **设计原则**：不完全依赖 AI 自觉判断，基于步骤的**结构特征**自动确定里程碑。\r\n\r\n### 判断规则（优先级从高到低）\r\n\r\n| 优先级 | 规则 | 说明 | 示例 |\r\n|--------|------|------|------|\r\n| 1 | 用户显式标记 | `is_milestone=true` | 用户手动指定 |\r\n| 2 | 显式取消 | `is_milestone=false` | 用户明确不需要 |\r\n| 3 | 短链全部标记 | 总步骤数 ≤ 2 → 全部里程碑 | 链太短，每步都关键 |\r\n| 4 | 关键词匹配 | 步骤名包含特定关键词 → 里程碑 | \"安全审计\"、\"部署上线\" |\r\n| 5 | 瓶颈点 | 被 ≥2 个后续步骤依赖 → 里程碑 | 多个步骤依赖该步骤的输出 |\r\n| 6 | 最终交付 | 是最后一步 → 里程碑 | 最终产出物 |\r\n| 7 | 默认非里程碑 | 以上均不满足 | 辅助/中间步骤 |\r\n\r\n### 里程碑关键词\r\n\r\n中英文关键词（步骤名包含任一即匹配）：\r\n\r\n```\r\n审计、安全、部署、发布、上线、打包、测试、验证、校验、审批、审核、\r\n付款、支付、下单、提交、推送、导入、导出、迁移、备份、恢复、\r\naudit、deploy、release、publish、push、test、verify、validate、\r\napprove、review、payment、submit、import、export、migrate、\r\nbackup、restore、build、compile、install\r\n```\r\n\r\n### 里程碑行为\r\n\r\n- **里程碑步骤失败** → 无论 `on_exhaust` 配置如何，**强制中止整条链**\r\n- **里程碑步骤的 on_exhaust** → 建议设为 `abort`（validate 时会发出警告）\r\n- **非里程碑步骤失败** → 按 `on_exhaust` 配置处理（ask/skip/abort）\r\n\r\n---\r\n\r\n## 三层回退执行策略\r\n\r\n| 层次 | 策略 | 上下文占用 | 触发条件 |\r\n|------|------|-----------|---------|\r\n| **第一层** | 仅用 action 精炼描述直接执行 | 最低 | 默认，action 足够明确 |\r\n| **第二层** | 按需读取 SKILL.md 对应指令片段 | 中等 | action 不明确或执行失败 |\r\n| **第三层** | 加载完整 SKILL.md | 最高 | 前两层均无法完成 |\r\n\r\n---\r\n\r\n## 分级重试策略\r\n\r\n| 错误类型 | 重试间隔 | 说明 |\r\n|---------|---------|------|\r\n| file_locked | 0 秒 | 文件占用/锁定，立即重试 |\r\n| network_error | 5 秒 | 网络不通/超时 |\r\n| timeout | 5 秒 | 执行超时 |\r\n| auth_error | - | 认证/权限错误，直接询问用户 |\r\n| other | 2 秒 | 其他错误 |\r\n\r\n重试次数从配置读取（默认3次），耗尽后按 `on_exhaust` 处理。\r\n\r\n---\r\n\r\n## AI 执行指令（必读原则）\r\n\r\n1. **执行前通读调用链**：读取整条链的所有步骤，理解全局依赖关系\r\n2. **三层回退**：每个步骤优先用 action 执行，不充分时再读取 SKILL.md\r\n3. **里程碑步骤失败立即中止**：不继续后续步骤\r\n4. **非里程碑步骤失败按 on_exhaust 处理**：ask（询问）/ skip（跳过）/ abort（中止）\r\n5. **记录变量传递**：步骤输出变量作为后续步骤输入\r\n6. **命名遵循配置**：`naming_mode=auto` 时 AI 自动命名，`manual` 时询问用户\r\n\r\n---\r\n\r\n## 配置界面\r\n\r\n### 配置项说明\r\n\r\n| 配置项 | 选项 | 说明 |\r\n|--------|------|------|\r\n| **记忆参考** | 是 / 否 | 创建/执行调用链时，是否读取用户记忆文件增强步骤描述 |\r\n| **命名方式** | 自动 / 人工 | 创建调用链时，由 AI 自动命名还是询问用户 |\r\n| **默认重试次数** | 1-10（默认3） | 所有步骤的默认最大重试次数 |\r\n\r\n### 当前配置\r\n\r\n> **配置路径**：`~/.workbuddy/skills/.standardization/skill-sub/config.json`\r\n> **默认配置**：`{skill_dir}/scripts/default_config.json`\r\n\r\n**方式 1：HTML 配置界面（推荐）**\r\n\r\nAgent 执行：\r\n1. 运行 `python {SKILL_DIR}/scripts/settings.py --serve-only`\r\n2. 解析输出中的 `SERVER_STARTED:`\r\n3. 打开浏览器 `http://localhost:{port}/`\r\n4. 轮询 `{SKILL_DIR}/.settings_done` 标志文件\r\n5. 检测到标志文件后关闭服务器\r\n\r\n**方式 2：命令行查看**\r\n\r\n```bash\r\npython {SKILL_DIR}/scripts/settings.py --get-config\r\n```\r\n\r\n**方式 3：命令行保存**\r\n\r\n```bash\r\npython {SKILL_DIR}/scripts/settings.py --save-config '{\"use_memory_reference\": true, \"naming_mode\": \"auto\", \"default_max_retries\": 5}'\r\n```\r\n\r\n**方式 4：对话式配置（回退方案）**\r\n\r\n当 HTML 配置界面无法打开时，通过对话方式收集配置：\r\n\r\n```\r\n步骤 1：记忆参考\r\n是否在创建调用链时参考用户记忆文件？（输入 y/n）:\r\n\r\n步骤 2：命名方式\r\n调用链命名方式（输入 1/2 选择）：\r\n1. 自动 — AI 根据意图和目的自动生成名称\r\n2. 人工 — 每次创建时询问用户\r\n请输入：\r\n\r\n步骤 3：默认重试次数\r\n请输入默认最大重试次数（1-10，默认3）:\r\n\r\n步骤 4：保存\r\nAgent 执行: python settings.py --save-config ''\r\n```\n\nFile v1.37.3:scripts/default_config.json\n\n{\r\n \"version\": \"1.2.0\",\r\n \"_skill_sub_home\": \"~/.workbuddy/skills/.standardization/skill-sub/\",\r\n\r\n \"use_memory_reference\": false,\r\n \"naming_mode\": \"manual\",\r\n \"default_max_retries\": 3\r\n}\n\nArchive v1.37.2: 19 files, 63189 bytes\n\nFiles: _meta.json (129b), references/adhesion.md (5777b), references/antipatterns.md (2639b), references/chain_schema.md (13542b), references/changelog.md (12162b), references/examples.md (4999b), references/faq.md (4975b), references/permissions.md (1819b), references/reference.md (6938b), references/workflow.md (10642b), scripts/chain_executor.py (23718b), scripts/chain_flow_validator.py (10430b), scripts/chain_manager.py (42348b), scripts/chain_structure_checker.py (11758b), scripts/default_config.json (194b), scripts/loop_branch_renderer.py (6717b), scripts/settings.html (10326b), skill-card.md (2729b), SKILL.md (10089b)\n\nFile v1.37.2:SKILL.md\n\n---\r\nname: skill-sub\r\nversion: 1.27.1\r\nauthor: wUwproject\r\nlicense: MIT\r\ndescription: 调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。\r\nsensitive_access: false\r\ncritical_write: false\r\npermission_weight: LOW\r\ndata_dir: ../.standardization/skill-sub/data/\r\ntags: ['chain', 'orchestration', 'usable', 'skill-builder', 'progressive-loading', 'planner', 'editor']\r\nexternal_data_dir: true\r\ntrigger: ['规划类: 帮我规划一下/步骤是什么', '顺序类: 依次执行/先...再...', '链管理: 创建/查看/更新/删除调用链']\r\ntrigger_negative: ['不使用调用链', '手动逐步执行']\r\nmeta_field_sync: true\r\nh1_position: true\r\n---\r\n# skill-sub\r\n\r\n\r\n\r\n\r\n## 触发场景\r\n\r\n**当用户提出以下意图时触发本技能：**\r\n- 规划类：「帮我规划一下...」、「...的步骤是什么」\r\n- 顺序类：「依次执行 A、B、C」、「先...再...」\r\n- 链管理：「创建/查看/更新/删除调用链」\r\n\r\n**否定条件**：仅当用户明确要求「不使用调用链」或「手动逐步执行」时，不自动触发。\r\n\r\n\r\n\r\n## 核心能力\r\n\r\n> 📚 **渐进式加载**：本技能采用渐进式 MD 体系，`SKILL.md` 为入口（≤230行），详细内容拆分到 `references/*.md` 按需加载。\r\n\r\n| # | 功能 | 说明 |\r\n|---|------|------|\r\n| 1 | **调用链管理** | 创建、查询、更新、删除调用链 |\r\n| 2 | **执行计划生成** | 生成结构化执行计划，含并行/串行标记 |\r\n| 3 | **条件执行** | 支持条件步骤，按条件判断是否执行 |\r\n| 4 | **循环与分支编排** | 支持 for-each/while 循环和 if-else 分支 |\r\n| 5 | **Dry-Run 模式** | 模拟执行，不实际调用技能 |\r\n| 6 | **链备份与版本管理** | 自动备份，支持版本恢复 |\r\n| 7 | **粘连点（Adhesion Point）** | 标记 skill 无法自动化的缺口，提供三种解决方案保证链不断；支持自愈 —— 每次执行自动扫描是否有新 skill 可填补 |\r\n\r\n---\r\n\r\n---\r\n\r\n\r\n\r\n\r\n\r\n### 渐进式文件索引\r\n\r\n| 文件名 | 位置 | 说明 |\r\n|--------|------|------|\r\n| `references/antipatterns.md` | skill-sub 反模式 | > 本文档收录 skill-sub 使用中的常见错误和正确做法。完整反模式示例见 `references/faq.md` |\r\n| `references/adhesion.md` | 粘连点机制（v1.25.0） | > 粘连点定义、三种解决方案（manual/auto/hybrid）、自愈流程 |\r\n\nArchive v1.37.1: 19 files, 63168 bytes\n\nFiles: _meta.json (129b), references/adhesion.md (5777b), references/antipatterns.md (2639b), references/chain_schema.md (13542b), references/changelog.md (12162b), references/examples.md (4999b), references/faq.md (4975b), references/permissions.md (1819b), references/reference.md (6938b), references/workflow.md (10642b), scripts/chain_executor.py (23718b), scripts/chain_flow_validator.py (10430b), scripts/chain_manager.py (42348b), scripts/chain_structure_checker.py (11758b), scripts/default_config.json (194b), scripts/loop_branch_renderer.py (6717b), scripts/settings.html (10326b), skill-card.md (2682b), SKILL.md (10089b)\n\nArchive v1.29.1: 25 files, 102057 bytes\n\nFiles: _meta.json (129b), references/adhesion.md (5948b), references/antipatterns.md (2639b), references/chain_schema.md (13542b), references/changelog.md (14449b), references/examples.md (5150b), references/faq.md (4975b), references/LICENSE.md (1097b), references/loop_branch.md (1456b), references/permissions.md (3248b), references/reference.md (6938b), references/workflow.md (10642b), scripts/chain_executor.py (26154b), scripts/chain_flow_validator.py (10430b), scripts/chain_manager.py (57282b), scripts/chain_planner.py (14753b), scripts/chain_structure_checker.py (11758b), scripts/default_config.json (194b), scripts/settings.html (10712b), scripts/settings.py (12327b), scripts/skill_extractor.py (39033b), scripts/step_indexer.py (22983b), scripts/step_link_validator.py (19720b), skill-card.md (2474b), SKILL.md (10566b)\n\nArchive v1.27.0: 19 files, 61834 bytes\n\nFiles: _meta.json (129b), references/adhesion.md (5777b), references/antipatterns.md (2639b), references/chain_schema.md (13542b), references/changelog.md (11997b), references/examples.md (4999b), references/faq.md (4975b), references/permissions.md (1819b), references/reference.md (6938b), references/workflow.md (10642b), scripts/chain_executor.py (23718b), scripts/chain_flow_validator.py (10430b), scripts/chain_manager.py (36292b), scripts/chain_structure_checker.py (11758b), scripts/default_config.json (194b), scripts/loop_branch_renderer.py (6717b), scripts/settings.html (10326b), skill-card.md (2829b), SKILL.md (10089b)\n\nArchive v1.25.0: 19 files, 57954 bytes\n\nFiles: _meta.json (129b), references/adhesion.md (5777b), references/antipatterns.md (2639b), references/chain_schema.md (11228b), references/changelog.md (10047b), references/examples.md (4999b), references/faq.md (4975b), references/permissions.md (1819b), references/reference.md (6938b), references/workflow.md (10642b), scripts/chain_executor.py (22535b), scripts/chain_flow_validator.py (9402b), scripts/chain_manager.py (30025b), scripts/chain_structure_checker.py (11758b), scripts/default_config.json (194b), scripts/loop_branch_renderer.py (6717b), scripts/settings.html (10326b), skill-card.md (2758b), SKILL.md (9406b)\n\nArchive v1.24.10: 16 files, 42136 bytes\n\nFiles: _meta.json (130b), references/antipatterns.md (2639b), references/chain_schema.md (8579b), references/changelog.md (7592b), references/examples.md (4999b), references/faq.md (3165b), references/permissions.md (1819b), references/reference.md (6938b), references/workflow.md (9058b), scripts/chain_executor.py (21268b), scripts/chain_manager.py (24503b), scripts/default_config.json (194b), scripts/loop_branch_renderer.py (6717b), scripts/settings.html (10326b), skill-card.md (2460b), SKILL.md (6285b)\n\nArchive v1.24.8: 16 files, 42487 bytes\n\nFiles: _meta.json (129b), references/antipatterns.md (2639b), references/chain_schema.md (8579b), references/changelog.md (7425b), references/examples.md (4999b), references/faq.md (3165b), references/permissions.md (1819b), references/reference.md (6938b), references/workflow.md (9058b), scripts/chain_executor.py (21268b), scripts/chain_manager.py (24503b), scripts/default_config.json (194b), scripts/loop_branch_renderer.py (6717b), scripts/settings.html (10326b), skill-card.md (2899b), SKILL.md (6360b)","readmeExcerpt":"Skill: skill-sub Owner: ldxs001 Summary: 调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。 Tags: blueprint:1.38.1, chain:1.38.1, editor:1.38.1, hook:1.38.0, latest:1.38.1, orchestration:1.38.1, planner:1.38.1, progressive-loading:1.38.1, skill-builder:1.38.1, step-index:1.38.1, usable:1.38.1 Version history: v1.38.1 | 2026-07-10T01:49:21.076Z | user v1.38.1 v1.38.0 |","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"File v1.38.1:_meta.json\n\n{\n \"ownerId\": \"kn75zfd51df61ajdyqtgvrs1hx84s4q6\",\n \"slug\": \"skill-sub\",\n \"version\": \"1.38.1\",\n \"publishedAt\": 1783648161076\n}\n\nFile v1.38.1:references/adhesion.md\n\n# 粘连点（Adhesion Point）机制\r\n\r\n> **v1.25.0 新增**。粘连点是调用链中无法由 skill 自动化的缺口标记。\r\n\r\n---\r\n\r\n## 什么是粘连点\r\n\r\n粘连点是调用链中一个特殊类型的步骤（`type: \"adhesion\"`），标记该位置无法由任何已安装 skill 自动完成。它不会阻断调用链，而是提供三种解决方案供 LLM 选择。\r\n\r\n### 什么时候产生粘连点\r\n\r\n| 场景 | 触发条件 | 行为 |\r\n|------|---------|------|\r\n| **链修正** | 执行链时发现步骤与真实 skill 不符，修正后仍报错 | 在该步骤位置打粘连点 |\r\n| **链缺口** | 规划链时某步骤无对应 skill 可用 | 在缺失位置插入粘连点 |\r\n| **流程缺口分析** | 规划阶段发现语义/流程/决策缺口 | 在天然断裂处打粘连点（见下方规则） |\r\n\r\n### 三个核心原则\r\n\r\n1. **链不断** — 粘连点标记不阻断调用链执行，LLM 按方案继续\r\n2. **连接器，非替代品** — 粘连点是两个 skill 步骤之间的连接器，不是 skill 步骤的替代品。**禁止粘连点连粘连点**，连续缺口合并为一个粘连点\r\n3. **不创建 Skill** — 解决方案是步骤描述级别，产生的脚本/产出物归数据目录管理\r\n4. **自愈** — 每次使用含粘连点的链，主动检查是否有新 skill 可填补\r\n\r\n---\r\n\r\n## 缺口分析规则（规划阶段）\r\n\r\n在创建调用链的步骤 3→4 之间插入流程缺口分析，按以下规则判断：\r\n\r\n### 三种真实缺口\r\n\r\n| 缺口类型 | 判断依据 | 应打粘连点？ | 方案优先级 |\r\n|---------|---------|------------|-----------|\r\n| **语义缺口** | Skill A 输出格式/内容 ≠ Skill B 期望输入 | ✅ 数据转换步骤 | hybrid |\r\n| **流程缺口** | 用户任务中的某个环节无任何 skill 覆盖 | ✅ 补充缺失步骤 | auto / manual |\r\n| **决策缺口** | 需要人工审批、判断、签字的节点 | ✅ 人工审批节点 | manual |\r\n| **自然衔接** | Skill A 输出可直接作为 Skill B 输入 | ❌ 不打 | — |\r\n\r\n### 禁止行为\r\n\r\n| 禁令 | 说明 |\r\n|------|------|\r\n| ❌ 不要制造缺口 | 自然衔接的 skill 不打粘连点 |\r\n| ❌ 不要粘连点连粘连点 | **连续缺口合并为一个粘连点** |\r\n| ❌ 不要替代 skill | 能用 skill 完成的直接用 skill |\r\n| ❌ 不要过度粘连 | 粘连点数量应远少于 skill 步骤数 |\r\n\r\n### 判定示例"},{"language":"text","snippet":"File v1.38.1:references/antipatterns.md\n\n# skill-sub 反模式\r\n\r\n> 本文档收录 skill-sub 使用中的常见错误和正确做法。完整反模式示例见 `references/faq.md`。\r\n\r\n---\r\n\r\n## AP-01：把 skill-sub 编入调用链\r\n\r\n**错误做法：**创建调用链时把 `skill-sub` 作为一个步骤加入。"},{"language":"text","snippet":"File v1.38.1:references/changelog.md\n\n## [1.38.1] - 2026-07-10\r\n\r\n### 修复\r\n- **SKILL.md 标题断裂**：3 处 `##` 标题前缺少空行导致拼接失效\r\n- **changelog.md 格式**：`---## [1.31.0]` 缺少分隔线换行\r\n- **permissions.md 重复**：删除新旧两版权限扫描结果合并的旧版冗余内容\r\n\r\n## [1.38.0] - 2026-07-03\r\n\r\n### 新增\r\n- **流程钩子系统（chain_hook.py）**：在里程碑步骤和末尾步骤上挂载 `hook.expects` 检查前置产出物\r\n - 新增 `chain_hook.py`：钩子检查引擎，支持 check/check_chain/CLI\r\n - `chain_executor.py plan` 输出显示钩子信息，`--force-hooks` 跳过\r\n - `chain_executor.py validate` 输出钩子验证结果\r\n - Step schema 新增 `hook` 字段，文档见 chain_schema.md\r\n\r\n## [1.37.3] - 2026-07-03\r\n\r\n### 修复\r\n- 修正渐进式文件索引表：移除 scripts/ 条目（索引表应仅含 references/*.md）\r\n\r\n## [1.37.2] - 2026-07-03\r\n\r\n### 修复\r\n- 修正 displayName 为 skill-sub（原错误设为 Skill Sub - 调用链编排）\r\n\r\n## [1.37.1] - 2026-07-03\r\n\r\n### 修复\r\n- 修正 1.37.0 更新日志：删除不相关的 skill-standardization 工具修复条目，仅保留 skill-sub 自身的更新\r\n\r\n## [1.37.0] - 2026-07-03\r\n\r\n### 修复\r\n- SKILL.md 文档结构标准化：触发条件章节优化（触发词改为具体操作描述，删除危险表述），工作流程格式化（列表+输入输出标注），配置表补齐，约束章节合并\r\n- 技能子命令间增加有效分隔，提升指令执行清晰度\r\n\r\n## [1.36.0] - 2026-07-03\r\n\r\n### 修复\r\n- **SKILL.md 标准化审计修复**（skill-standardization refactor）\r\n - R-17：SKILL.md 从 377 行裁剪至 160 行\r\n - R-20：changelog 术语统一\r\n - R-21：渐进式加载模板句恢复\r\n - R-23：文档-代码一致性误报分类\r\n - C-07：14 个代码块补充语言标识\r\n - C-11/C-12/C-13/C-17/C-18：章节格式、索引表、示例、边界量化修复\r\n- 扩展 step_indexer search 过期检测覆盖 chain_planner 内部搜索（--ignore-stale 兜底）\r\n\r\n---\r\n\r\n## [1.35.1] - 2026-07-03\r\n\r\n### 修复\r\n- **SKILL.md 文档脱钩修复**：\r\n - 核心能力表：新增门禁系统、蓝皮书过期检测、链私有蓝皮书基线校验、自增强闭环\r\n - 工作流程：更新为 0-9 步串行门禁阻断表\r\n - 新增门禁系统文档（chain_gate CLI + 依赖链）\r\n - 新增链私有蓝皮书文档（基线保护 + 执行前自动校验）\r\n - 新增 LLM 参数文档（--llm-chain-check / --milestones / --adhesion）\r\n - 新增自增强闭环文档（chain_manager search）\r\n - 渐进式加载约束从 ≤230 行更新为 ~380 行\r\n - 快速开始示例补全 check-health / search / gate status 等新命令\r\n\r\n---\r\n\r\n## [1.35.0] - 2026-07-03\r\n\r\n### 新增\r\n- **链执行前蓝皮书健康检查**（chain_executor.py load_chain）\r\n 每次加载链执行时自动比 blueprints.json 中的 _skill_md5s vs 当前 SKILL.md\r\n 发现基线偏移 → HOOK-BLOCK [HARD] 阻断，输出修复命令\r\n 跳过：`--force-health`\r\n\r\n### 更新\r\n- chain_executor.py plan 新增 `--force-health` 参数\r\n- chain_executor.val"},{"language":"text","snippet":"用户需求：分析代码 → 生成报告 → 发送邮件\n\n✓ 正确：\n 步骤1: code-analysis (skill) — 分析代码\n 步骤2: report-generation (adhesion) — JSON→Markdown 语义缺口\n 步骤3: email-send (skill) — 发送邮件\n\n✓ 连续缺口合并：\n 步骤1: code-analysis (skill)\n → 步骤2: data-cleanup (缺失) — 两个连续缺失合并为一个粘连点\n → 步骤3: transform (缺失) — 🔴 禁止！应为：\n 步骤2: data-pipeline (adhesion, hybrid) — 覆盖清洗+转换的完整缺口\n 步骤3: email-send (skill)\n\n✗ 过度粘连：\n 步骤1: code-analysis (skill)\n 步骤2: report-generation (adhesion) — ❌ 如果有 report skill 就不该打\n 步骤3: email-send (skill)\n\n✗ 粘连点连粘连点（禁止）：\n 步骤1: code-analysis (skill)\n 步骤2: manual-review (adhesion) — ❌ 连续两个粘连点\n 步骤3: data-transform (adhesion) — ❌ 应合并为一个\n 步骤4: email-send (skill)"},{"language":"json","snippet":"{\"mode\": \"manual\", \"description\": \"人工审核报告\", \"constraints\": \"需关注数据准确性\"}"},{"language":"json","snippet":"{\"mode\": \"auto\", \"tool_name\": \"report-verify\", \"script_path\": \"scripts/verify.sh\"}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\r\nname: skill-sub\r\nslug: skill-sub\r\ndisplayName: skill-sub\r\nversion: 1.38.1\r\nauthor: wUwproject\r\nlicense: MIT\r\ndescription: 调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。\r\nsensitive_access: false\r\ncritical_write: false\r\npermission_weight: MEDIUM\r\ndata_dir: ../.standardization/skill-sub/data/\r\ntags: ['chain', 'orchestration', 'usable', 'skill-builder', 'progressive-loading', 'planner', 'editor', 'step-index', 'blueprint']\r\nexternal_data_dir: true\r\ntrigger: ['加载用户配置（合并默认值 + 用户覆盖）', '用户需要识别依赖关系、并行机会，输出 AI 可执行的指令序列。', 'chain_executor.py - Chain Executor', '调用链执行引擎：根据调用链定义生成结构化执行计划']\r\ntrigger_negative: true\r\nmeta_field_sync: true\r\nh1_position: true\r\ncreate_permissions_md: true\r\ntrigger_quality: refine_triggers\r\ntrigger_danger: remove_dangerous\r\n---\r\n# skill-sub\r\n\r\n## 约束\r\n\r\n参数约束：skill-dir 绝对路径 20-260 字符，描述文本 ≤120 字。最大步骤数 30 层，粘连点占比上限 30%，依赖深度上限 10 层。\r\n\r\n\r\n### 适宜场景 ✅\r\n\r\n| 场景 | 说明 |\r\n| ------ |------|\r\n| 多 skill 编排 | 涉及 2 个及以上 skill，步骤间有明确依赖关系 |\r\n| 可固化流程 | 流程稳定、可复现，不是一次性操作 |\r\n| 跨步骤衔接 | skill 之间需要数据转换、人工审批、流程补全 |\r\n\r\n### 不适宜场景 ❌\r\n\r\n| 场景 | 原因 |\r\n| ------ |------|\r\n| 单 skill 任务 | 直接调 skill 本身即可，不需要调用链 |\r\n| 一次性操作 | 调用链的价值在于复用，一次性工作不值得建链 |\r\n| 无依赖的并行任务 | 多个独立任务应并行执行，不需要编排 |\r\n| 高度动态的流程 | 每次执行步骤都不一样，粘连点也解决不了，直接 AI 手动处理 |\r\n\r\n### 硬限制\r\n\r\n| 限制项 | 值 | 说明 |\r\n| -------- |-----| ------ |\r\n| 最大步骤数 | 30 层（含嵌套） | 超过后校验器会告警，但不阻断执行 |\r\n| 粘连点占比 | 30% | 超过告警，建议合并或补充 skill |\r\n| 粘连点连续 | **禁止** | 连续缺口合并为一个粘连点 |\r\n| 依赖深度 | 10 层 | 过深依赖链难以维护和排查 |\r\n| 循环最大迭代 | 默认 10，可配置 | 超过按 on_max_iteration 处理 |\r\n\r\n### 常见创建错误速查\r\n\r\n| 报错信息 | 原因 | 解决方法 |\r\n| --------- |------| --------- |\r\n| 连续缺口应合并为一个粘连点 | 两个 adhesion 步骤相邻 | 合并为一个 adhesion，用 hybrid 方案覆盖全部缺口 |\r\n| 粘连点占比超过 30% | adhesion 步骤太多 | 检查是否有 skill 可以替代 |\r\n| 缺少 solutions | adhesion 步骤没有提供方案 | 至少加一个 manual 方案 |\r\n| 依赖不存在的步骤 | depends_on 引用了无效索引 | 检查依赖步骤的 index 是否正确 |\r\n| 引用的 skill 不存在 | skill_name 对应的 skill 未安装 | 检查 skill 名称是否正确 |\r\n| 检测到定时/自动化意图，但未提供 --schedule | 描述中含\"每天/每周/定时\"等词但没给调度配置 | 添加 --schedule 参数，或删除描述中的时间相关词 |\r\n\r\n> **强制规则**：用户描述中包含定时/自动化意图（如\"每天\"、\"每周\"、\"自动执行\"等）时，**必须**提供 `--schedule` 参数配置调度信息，否则链创建被拦截。 不依赖 AI 自觉判断。\r\n\r\n## 触发条件\r\n\r\n**正向触发：**\r\n- 规划类：「帮我规划一下...」、「...的步骤是什么」\r\n- 顺序类：「依次执行 A、B、C」、「先...再...」\r\n- 链管理：「创建/查看/更新/删除调用链」\r\n- 步骤搜索类：「搜索步骤」、「找步骤」\r\n- 链健康检查：「检查链的健康状态」\r\n- 仅涉及单个 skill 的简单任务\r\n\r\n**否定条件：**\r\n- 明确要求「不使用调用链」\r\n\r\n## 触发场景\r\n**正向触发**：\r\n- chain_executor.py - Chain Executor v1.22.0\r\n- 调用链执行引擎：根据调用链定义生成结构化执行计划，\r\n- 识别依赖关系、并行机会，输出 AI 可执行的指令序列。\r\n- 加载用户配置（合并默认值 + 用户覆盖）\r\n\r\n**否定条件**：\r\n- 简单问答、闲聊、问候（不需要本技能）\r\n- 单步任务（不需要结构化执行）\r\n\r\n## 核心能力\r\n\r\n> 📚 **渐进式加载**：本技能采用渐进式 MD 体系，`SKILL.md` 为入口（≤230行），详细内容拆分到 `references/*.md` 按需加载。\r\n\r\n| # | 功能 | 说明 |\r\n| --- |------| ------ |\r\n| 1 | **调用链管理** | 创建、查询、更新、删除调用链 |\r\n| 2 | **执行计划生成** | 生成结构化执行计划，含并行/串行标记 |\r\n| 3 | **条件执行** | 支持条件步骤，按条件判断是否执行 |\r\n| 4 | **循环与分支编排** | 支持 for-each/while 循环和 if-else 分支 |\r\n| 5 | **门禁系统** | 10 座 HARD 门禁串行阻断管线（chain_gate.py），HOOK-BLOCK 输出 |\r\n| 6 | **步骤蓝皮书过期检测** | `search` 命令前置自动比对指纹，过期直接拒绝搜索 |\r\n| 7 | **链私有蓝皮书基线校验** | 链创建时 snapshot 步骤接口，执行前自动校验"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn75zfd51df61ajdyqtgvrs1hx84s4q6\",\n \"slug\": \"skill-sub\",\n \"version\": \"1.38.1\",\n \"publishedAt\": 1783648161076\n}"},{"path":"references/adhesion.md","content":"# 粘连点（Adhesion Point）机制\r\n\r\n> **v1.25.0 新增**。粘连点是调用链中无法由 skill 自动化的缺口标记。\r\n\r\n---\r\n\r\n## 什么是粘连点\r\n\r\n粘连点是调用链中一个特殊类型的步骤（`type: \"adhesion\"`），标记该位置无法由任何已安装 skill 自动完成。它不会阻断调用链，而是提供三种解决方案供 LLM 选择。\r\n\r\n### 什么时候产生粘连点\r\n\r\n| 场景 | 触发条件 | 行为 |\r\n|------|---------|------|\r\n| **链修正** | 执行链时发现步骤与真实 skill 不符，修正后仍报错 | 在该步骤位置打粘连点 |\r\n| **链缺口** | 规划链时某步骤无对应 skill 可用 | 在缺失位置插入粘连点 |\r\n| **流程缺口分析** | 规划阶段发现语义/流程/决策缺口 | 在天然断裂处打粘连点（见下方规则） |\r\n\r\n### 三个核心原则\r\n\r\n1. **链不断** — 粘连点标记不阻断调用链执行，LLM 按方案继续\r\n2. **连接器，非替代品** — 粘连点是两个 skill 步骤之间的连接器，不是 skill 步骤的替代品。**禁止粘连点连粘连点**，连续缺口合并为一个粘连点\r\n3. **不创建 Skill** — 解决方案是步骤描述级别，产生的脚本/产出物归数据目录管理\r\n4. **自愈** — 每次使用含粘连点的链，主动检查是否有新 skill 可填补\r\n\r\n---\r\n\r\n## 缺口分析规则（规划阶段）\r\n\r\n在创建调用链的步骤 3→4 之间插入流程缺口分析，按以下规则判断：\r\n\r\n### 三种真实缺口\r\n\r\n| 缺口类型 | 判断依据 | 应打粘连点？ | 方案优先级 |\r\n|---------|---------|------------|-----------|\r\n| **语义缺口** | Skill A 输出格式/内容 ≠ Skill B 期望输入 | ✅ 数据转换步骤 | hybrid |\r\n| **流程缺口** | 用户任务中的某个环节无任何 skill 覆盖 | ✅ 补充缺失步骤 | auto / manual |\r\n| **决策缺口** | 需要人工审批、判断、签字的节点 | ✅ 人工审批节点 | manual |\r\n| **自然衔接** | Skill A 输出可直接作为 Skill B 输入 | ❌ 不打 | — |\r\n\r\n### 禁止行为\r\n\r\n| 禁令 | 说明 |\r\n|------|------|\r\n| ❌ 不要制造缺口 | 自然衔接的 skill 不打粘连点 |\r\n| ❌ 不要粘连点连粘连点 | **连续缺口合并为一个粘连点** |\r\n| ❌ 不要替代 skill | 能用 skill 完成的直接用 skill |\r\n| ❌ 不要过度粘连 | 粘连点数量应远少于 skill 步骤数 |\r\n\r\n### 判定示例\r\n\r\n```text\r\n用户需求：分析代码 → 生成报告 → 发送邮件\r\n\r\n✓ 正确：\r\n 步骤1: code-analysis (skill) — 分析代码\r\n 步骤2: report-generation (adhesion) — JSON→Markdown 语义缺口\r\n 步骤3: email-send (skill) — 发送邮件\r\n\r\n✓ 连续缺口合并：\r\n 步骤1: code-analysis (skill)\r\n → 步骤2: data-cleanup (缺失) — 两个连续缺失合并为一个粘连点\r\n → 步骤3: transform (缺失) — 🔴 禁止！应为：\r\n 步骤2: data-pipeline (adhesion, hybrid) — 覆盖清洗+转换的完整缺口\r\n 步骤3: email-send (skill)\r\n\r\n✗ 过度粘连：\r\n 步骤1: code-analysis (skill)\r\n 步骤2: report-generation (adhesion) — ❌ 如果有 report skill 就不该打\r\n 步骤3: email-send (skill)\r\n\r\n✗ 粘连点连粘连点（禁止）：\r\n 步骤1: code-analysis (skill)\r\n 步骤2: manual-review (adhesion) — ❌ 连续两个粘连点\r\n 步骤3: data-transform (adhesion) — ❌ 应合并为一个\r\n 步骤4: email-send (skill)\r\n```\r\n\r\n---\r\n\r\n## 三种解决方案\r\n\r\n### ① 纯手工（manual）\r\n\r\nLLM 直接手动执行步骤，不依赖脚本或新 skill。\r\n\r\n```json\r\n{\"mode\": \"manual\", \"description\": \"人工审核报告\", \"constraints\": \"需关注数据准确性\"}\r\n```\r\n\r\n**适用场景**：一次性、高度灵活的判断任务。\r\n\r\n### ② 脚本化（auto）\r\n\r\n通过自调用脚本工具执行，产生的脚本入数据目录管理。\r\n\r\n```json\r\n{\"mode\": \"auto\", \"tool_name\": \"report-verify\", \"script_path\": \"scripts/verify.sh\"}\r\n```\r\n\r\n**适用场景**：可标准化、重复执行的任务。\r\n\r\n### ③ 混合（hybrid）\r\n\r\nLLM 描述流程步骤 + 约束 + 自调用工具协同执行。\r\n\r\n```json\r\n{\r\n \"mode\": \"hybrid\",\r\n \"llm_steps\": \"LLM 阅读报告并给出审核意见\",\r\n \"tool_steps\": \"脚本验证报告中的数字准确性\",\r\n \"integration\": \"LLM 分析文本，工具验证数字\"\r\n}\r\n```\r\n\r\n**适用场景**：需要智能判断 + 自动化执行的复合任务。\r\n\r\n---\r\n\r\n## 执行优先级\r\n\r\nAI 执行粘连点步骤时，按以下优先级选择方案：\r\n\r\n1. **hybrid** — 最优先，组合 LLM + 工具的最大能力\r\n2. **auto** — 次优先，能脚本化就不手动\r\n3. **manual** — 兜底，LLM 直接执行\r\n\r\n---\r\n\r\n## 自愈机制\r\n\r\n每次加载含粘连点的调用链时，AI 执行自愈检查：\r\n\r\n```\r\n1. 扫描 skill 库（skill-sub 所在目录的兄弟目录）\r\n2. 对每个粘连点，用 adhesion.reason 关键词搜索 SKILL.md\r\n3. 找到匹配 → 将 adhesion 步骤升级为 skill 步骤\r\n - type 改为 \"skill\"\r\n - 填充 skill_name / action\r\n - 原 adhesion.solutions 写入 notes\r\n4. 未找到 → 按原有 3 方案执行\r\n```\r\n\r\n也可手动触发：`python cha"},{"path":"references/antipatterns.md","content":"# skill-sub 反模式\r\n\r\n> 本文档收录 skill-sub 使用中的常见错误和正确做法。完整反模式示例见 `references/faq.md`。\r\n\r\n---\r\n\r\n## AP-01：把 skill-sub 编入调用链\r\n\r\n**错误做法：**创建调用链时把 `skill-sub` 作为一个步骤加入。\r\n\r\n```\r\n步骤1: skill-sub → 规划\r\n步骤2: xxx\r\n```\r\n\r\n**为什么错：**skill-sub 是编辑器/规划器，不是执行器。链需要的是\"谁干活\"，skill-sub 不干活。\r\n\r\n**正确做法：**调用链只包含执行型 Skill（如 semantic-split、git-sync），不包含 skill-sub 本身。\r\n\r\n---\r\n\r\n## AP-02：为一次性任务创建调用链\r\n\r\n**错误做法：**用户说「帮我查一下今天天气」，就创建一个\"天气查询\"调用链。\r\n\r\n**为什么错：**调用链的价值是复用。一次性任务下次不会用到，反而积累垃圾链。\r\n\r\n**正确做法：**判断任务是否有复用价值。以下信号表明值得创建链：\r\n- 用户说「每次」「以后也」「下次」\r\n- 涉及 ≥3 个 Skill 协作\r\n- 有明确的输入→输出模式\r\n\r\n---\r\n\r\n## AP-03：跳过摘取阶段，直接写 action\r\n\r\n**错误做法：**不读目标 Skill 的 SKILL.md，凭记忆写 action 描述。\r\n\r\n```json\r\n{\"action\": \"执行安全审计\"} // 太模糊，实际执行时不知道具体做什么\r\n```\r\n\r\n**为什么错：**action 是执行时的唯一指引。不读 Skill 原文会导致遗漏关键步骤或用错指令名。\r\n\r\n**正确做法：**执行阶段2摘取——读取目标 Skill 的 SKILL.md「工作流程」章节，摘取步骤名+关键动作+指令名。action 要包含具体的**做什么**（动词+对象+产出）。\r\n\r\n---\r\n\r\n## AP-04：把所有步骤都标为里程碑\r\n\r\n**错误做法：**3 步的链，全标 `is_milestone: true`。\r\n\r\n**为什么错：**里程碑=失败即中止。全标等于没有区分，任何一步失败都中止，丧失灵活性。\r\n\r\n**正确做法：**用里程碑判断规则（关键词/瓶颈点/最终交付）自动判断，只对关键步骤标里程碑。非关键步骤用 `on_exhaust: ask` 或 `skip` 而非 `abort`。\r\n\r\n---\r\n\r\n## AP-05：依赖关系写错导致链无法执行\r\n\r\n**错误做法：**\r\n```json\r\n{\"index\": 1, \"depends_on\": []},\r\n{\"index\": 2, \"depends_on\": [3]}, // 依赖了后面的步骤！\r\n{\"index\": 3, \"depends_on\": [1]}\r\n```\r\n\r\n**为什么错：**步骤2依赖步骤3，但步骤3在步骤2之后执行——死锁。\r\n\r\n**正确做法：**`depends_on` 只能引用 `index` 小于自己的步骤。创建后用 `chain_executor.py validate` 检查。\r\n\r\n---\r\n\r\n> 更多反模式与正确做法 → `references/faq.md`"},{"path":"references/blueprint.md","content":"# 步骤蓝皮书\r\n\r\nskill-sub 将每个已安装技能的 SKILL.md 解析为结构化步骤蓝图，供搜索和链规划使用。\r\n\r\n**硬约束：** search 命令自动比对指纹，过期直接拒绝搜索。\r\n**LLM 提取路径：** check-fingerprint → prepare-llm-input → LLM → apply-blueprint\r\n**Regex 兜底：** scan --force"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。 Skill: skill-sub Owner: ldxs001 Summary: 调用链编排技能 — 既是调用链编辑器，也是粗粒度规划器。理解用户意图 → 规划 Skill 参与顺序 → 更新/保存/推荐调用链 → 拼接为调用链（支持循环/分支编排、子步骤拓扑排序、准确步骤计数）。 Tags: blueprint:1.38.1, chain:1.38.1, editor:1.38.1, hook:1.38.0, latest:1.38.1, orchestration:1.38.1, planner:1.38.1, progressive-loading:1.38.1, skill-builder:1.38.1, step-index:1.38.1, usable:1.38.1 Version history: v1.38.1 | 2026-07-10T01:49:21.076Z | user v1.38.1 v1.38.0 |","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":721,"uniquenessScore":53,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T01:54:32.543Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T01:54:32.543Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:40:38.361Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}