Skill Weave — 技能牌组编织器

将技能牌编织成链。比喻：每张技能是一张牌，链是手牌组合（顺子/飞机/王炸）。

> 🧩 想要开箱即用的预设链？ → skill-weave-chains
> 基于 skill-weave 引擎构建的 13 条预设技能链 + SAD 反馈闭环 + DAG 编排，三行代码跑通第一条链。

哲学

• 测试是为了修，不是为了攒。每轮推演发现 P0 立即修，修完重测验证。
• 挑核心王牌，散牌自然搁置。高频技能重点维护，低频技能不浪费精力。
• 子Agent不落地。注册子Agent只出补丁，由父Agent审核链序（E2E结论优先于注册设计）后再落地。

十二条核心链（R12 审计后）

> ⚡=对子链(2独立步骤可并行) | →=顺子/飞机/箭矢(严格串行)。并行由 detect_parallelism() 自动检测。
> R12 变更 (2026-07-03)：新增验证门/资产规范/并行检测/失败归因。基准 22/23=95.65%。

> ⚠️ 搜索后端陷阱（2026-06-08）：web_search 工具默认走 Firecrawl 后端（DDG 被 GFW 阻断 → 静默返回空）。触发箭矢链搜索步骤时，必须优先使用 MCP 工具（Bright Data search_engine/discover）或 Bocha bocha_search.py，不得直接调用 web_search。详见 multi-search-engine 降级链。

能力索引（非串行链）

基准测试

运行链识别基准测试（23 个标准查询，测试 identify_chain() 准确率）。

脚本位置：/opt/data/skills/workflow/skill-weave/scripts/benchmark_chain_routing.py

cd /opt/data && PYTHONPATH="/opt/data/.local:$PYTHONPATH" python3 /opt/data/skills/workflow/skill-weave/scripts/benchmark_chain_routing.py

> ⚠️ 不要用 pytest tests/：/opt/data/skill-weave/ 下没有 tests/ 目录，pytest 在该 venv 也无法安装（权限不足）。链识别准确率才是核心指标。详见 references/cron-setup.md。

变更检测与日志

> 📋 完整 cron 配置和文件格式说明见 references/cron-setup.md

文件位置（均在 /opt/data/skill-weave/ 下，独立于 git repo）：

典型 cron 工作流：
1. 运行脚本，收集 stdout
2. 与 last_benchmark.txt 比对准确率/失败列表
3. 若有变化 → 报告差异；若无变化 → SILENT
4. 追加新记录到 benchmark_history.jsonl
5. 用本次结果覆盖 last_benchmark.txt

> ⚠️ 脚本输出 JSON 格式（accuracy/total/correct/skills_loaded/chain_count/failures），last_benchmark.txt 需自行转换。两文件格式不一致：benchmark_history.jsonl 额外包含 timestamp 和 regression_from_previous。

已知边缘案例和误判模式见 references/chain-routing-edge-cases.md。

拆·织·验 执行流（实现类任务的标准工作流）

当 v0.4 头脑风暴完成、设计已收敛时，用此流程替代「议」：

接口契约模板

每个子Agent任务必须包含：
- 任务目标（一句话）
- 现有代码的完整上下文（读入 context，不让子Agent自己读）
- 外源可借鉴的设计（Darwin/SkillOpt/SKILLWEAVER）
- 约束（零新依赖、向后兼容、不改哪些文件）
- 验证命令（具体的 pytest 命令）

适用条件

• 使用「拆·织·验」: 昨天已充分讨论，今天编码执行（设计收敛 → 实现）
• 使用「议」: 方向未定，需要多模型发散讨论（探索 → 收敛）
• 使用「新链推演」: 需要注册新技能链（验证 → 注册）

与 Loop Engineering 的对应

拆·织·验 是 Anthropic Loop Engineering 六部分架构的一个实例。详见 references/loop-engineering-research-2026-06-27.md。

v0.4.0 模块架构

v0.4.0 新增了韧性层、状态层、验证层和卡片系统。完整架构见 references/v0.4-architecture.md。

卡片制注意力 (card.py)

核心理念：每轮循环结束时写一张 LoopCard（~200字节），下一轮只读卡片不读全量 MEMORY.md（~13KB）。认知负荷降低 ~98%。

from skill_weave.card import LoopCard, CardChain

chain = CardChain('/opt/data/shared/cards/default/loop_cards.jsonl')
chain.append(LoopCard(task="搜索AI论文", selected_skill="deep-research-pro",
                      result="PASS", next_hint="下次优先查缓存"))

# 子Agent 注入 — 不读全量上下文，只读最近3张卡片
context += chain.context_for_delegate()

跨 Profile 共享

架构基因和卡片链放在 /opt/data/shared/cards/，所有 profile 可读写：

• architecture_gene.json — 当前架构基因（全 profile 对齐）
• cross_profile_board.json — 公共决策板
• {profile}/loop_cards.jsonl — 各 profile 卡片链
• scripts/inject_card_context.py — 读取卡片链生成子Agent context

子Agent spawn 时不瞎猜——卡片告诉它"做到哪了"，基因告诉它"用什么架构做"。

大规模链发现工作流（v1.7 新增）

技能库从 181→269 增长后，手动逐链推演不适用。

三路并行探索模式（2026-07-03 验证）

delegate_task([
    {"goal": "扫描全部技能，发现新的可编织工作流链", ...},  # 链探索者
    {"goal": "筛选单点高质量技能，评估是否应加入现有链", ...}, # 质量探员
    {"goal": "审查现有架构，提出优化方案", ...},            # 编织优化师
])
# 三路并行，orchestrator级（可自行spawn子Agent探究细节）
# 结果汇总→父Agent终审→注册新链新牌

探索→编织→注册 闭环

1. 三路结果汇总
2. 父Agent裁决：确认新链 → 验证链序 → 设计触发词
3. 更新 weave_chains.py（CHAINS + CHAIN_TAGS + SYNONYMS）
4. 运行 benchmark_chain_routing.py 验证无回归
5. 更新链表格 + Stats

元技能编排模式（v1.7 新增）

链提供串行工作流，但 12 链 72 牌规模下，用户常面临"我该用哪个技能？"的导航问题。元技能是 操作手册式的索引入口——从导航直达子技能，不加载全量。

元技能 vs 链

元技能模板

name: <domain>-manual
tier: 0                      # 元技能最高层，只路由不执行
description: "操作手册入口——索引导航到 N 个子技能"
when: "<中文触发词集合>"
when_not: "单一子技能已覆盖的场景——直接加载对应子技能"
related_skills: [子技能1, 子技能2, ...]

主体结构：
1. 快速导航表 — 功能域分组 + 子技能一句话定位 + skill_view() 跳转
2. 场景速查 — "遇到X问题→加载Y技能"
3. 架构全景图 — 层次/阶段可视化
4. 决策树 — "我该用哪个？"
5. 加载路径 — 每个子技能的具体调用方法

已创建元技能（13 个，2026-07-03 批量生成）

> 13 元技能覆盖全部 12 链 + 知识生命周期。总 196KB。4 批子Agent并行生成，每批 ~70 秒。Hermes 自动发现注册。

并行生成模式

元技能可用子Agent并行批量生成：

派 3 个 orchestrator 子Agent，各领 1 条链
→ 各自加载相关子技能 SKILL.md
→ 按模板生成元技能 SKILL.md
→ 写入磁盘 → Hermes 自动发现

3 条元技能约 60-70 秒并行完成。12 链可 4 批覆盖。

新链推演工作流（三子Agent并行审计）

每轮推演使用 3 个子 Agent 并行，最后父 Agent 审核修正落地：

子Agent分工

父Agent审核清单

从 E2E 实测子Agent的报告中提取关键发现，逐项核对后再落地：

1. 链序是否正确：实测子Agent可能发现注册子Agent设计的顺序不对。典型案例：
   - 创作链：注册子Agent 设计 copy-editor → fiction-writing，实测发现应该 先写后编 → 修正为 fiction-writing → copy-editor → humanizer-zh
   - Git链：注册子Agent 设计 PR → commit，实测发现 commit message 在开 PR 之前生成 → 修正为 smart-commit-gen → github-pr-workflow → github-code-review
   - 规则：E2E 结论 > 注册设计。父Agent 必须读实测报告，不能直接信任注册补丁。

2. 技能兼容性：链中每个技能对前置步骤的输出是否兼容：
   - copy-editor 7轮框架有 5/7 轮对法律文书无意义 → 应从法槌链移除
   - copy-editor 第四轮「证据」对创作文本应跳过 → 链描述标注

3. 功能重叠：相邻步骤是否做同样的事：
   - legal-risk-analyzer 和 legal-document-review 都有法条核实 → 确认分工不同（一个出报告、一个改文档）则保留
   - smart-commit-gen 和 github-pr-workflow 都有 Conventional Commits → 链描述标注冗余

4. 伪链检测：三个技能是否真的形成串行数据流，还是只是并列能力拼在一起：
   - 飞书链是能力栈非串行管道 → 注册但标注 ⚠️，链描述写明

落地步骤

1. 先修技能（校检子Agent发现的问题）→ patch SKILL.md
2. 再修链序（根据实测子Agent结论）→ patch CHAINS
3. 最后注册（应用修正后的注册补丁）→ 更新 weave_chains.py + SYNONYMS
4. Stats更新 → memory() + MEMORY.md stats行 + Hindsight快照

常见问题速查

链验证规则

E2E 实测必须检查以下维度：

1. 顺序：步骤 N 的产出能否作为步骤 N+1 的输入？实际工作流中哪步先发生？
2. 重叠：相邻步骤是否有 30%+ 功能重叠？重叠是否互补（诊断 vs 治疗）还是冗余？
3. 兼容性：中间步骤是否会改变前一步产出的关键信息（如 copy-editor 改法律术语 → risk-analyzer 误判）？
4. 真实性：是真正的数据管道，还是三个独立能力硬拼成串？
5. when_not 冲突：链路中某个技能的 when_not 是否明确排除了前/后步骤的适用场景？

使用方式

# 路由任务到链
python3 /opt/data/scripts/weave_chains.py route "研究新能源汽车政策"

# 查看牌组
python3 /opt/data/scripts/weave_chains.py list
python3 /opt/data/scripts/weave_chains.py chains

# 反馈学习
python3 /opt/data/scripts/weave_chains.py feedback deep-research-pro success 3.0

仪式交接协议 (task_graph + worker + archive)

任务图是真相之源。Worker 是执行引擎。归档是自动清理。

核心组件

task_graph.yaml 格式

projects:
  project-name:
    status: in_progress
    scene: A
    priority: P0
    subtasks:
      - id: task-1
        title: 任务标题
        owner: router
        deps: []
        checks: ["验证条件1", "验证条件2"]

执行流程

task_graph.yaml（蓝图）
  → worker cron 轮询（每个 profile 每分钟）
  → 找自己的 executable 节点 → running → verifying → done
  → auto_archive 自动触发（打包 + 清理）

依赖语义

• [] — 无依赖，立即可执行
• task-id — 同项目内依赖
• project-id.task-id — 跨项目依赖

接口契约（关键教训）

给子Agent写 dataclass field names，不是自然语言描述。 三个模块由不同子Agent并行编码，接口断裂的三个来源：
1. 字段名不一致（assigned_to vs owner）
2. 重复定义（两个文件各写一份 WorkCard）
3. 必需字段过多（archive 不关心的字段导致测试炸）

统一规范：唯一定义在 work_card_worker.py；其他模块 from work_card_worker import WorkCard；接口契约用 dataclass 定义。

跨 Profile 部署

python3 scripts/work_card_worker.py --profile router --once
python3 scripts/work_card_worker.py --profile challenger --once
python3 scripts/work_card_worker.py --profile default --once

设计文档：references/ritual-handoff-protocol.md。

路由原理

三步闭环：

1. 链识别 v2 → 加权触发词匹配(1-3分)+链优先级+bigram模糊回退（规则层，零 token）
2. 标签过滤 → 缩小候选集到链相关技能
3. Thompson 采样 → 质量/新鲜度/成本/语义 四维评分

反馈学习：记录每次调用的成功/失败和成本，Thompson 采样根据历史表现调整路由权重。

冷启动教训：新注册技能初始评分相同，必须灌入初始反馈数据（基于推演验证的已知表现），路由才能分出高低。

当前牌组

72 张已验证技能牌：

添加新链

1. 校检子Agent → 验证所有技能 SKILL.md 完整性
2. 实测子Agent → 端到端检查链序/重叠/兼容性
3. 注册子Agent → 出补丁（不落地）
4. 父Agent 审核 → 修正链序和元数据
5. 落地 → 更新 weave_chains.py（CHAINS, SKILLS, CHAIN_TAGS） + advanced.py（SYNONYMS）
6. Stats → 更新 MEMORY.md stats 行 + Hindsight 快照

链识别 v2（2026-06-29 升级）

identify_chain() 从精确子串匹配升级为三层机制，准确率 73.91% → 100% (23/23)：

三层评分机制

1. 加权触发词 — 核心触发词 3 分（如"智能提交"），通用词 1 分（如"信息"），消除歧义词劫持路由
2. 链优先级 — 平分时按优先级打破平局（技能治理 > 法槌 > 代码审查 > 搜索 > Git工程 > 研究 > 创作 > 需求 > 记忆），替代 dict insertion order 随机性
3. Bigram 模糊兜底 — 无精确匹配时用中文 bigram 重叠评分，阈值 ≥2 命中

触发词扩展

每条链从 3-11 → 8-15 词，新增中文口语变体：
- 搜索链：搜一下 爬 检索 找资料
- 研究链：评测 翻译 数据科学 深度学习 写文章
- 技能治理：审查技能 审查外部技能
- Git链：智能提交 提交信息 commit信息

代码位置

/opt/data/scripts/weave_chains.py — identify_chain()、_tokenize_bigrams()、TRIGGER_WEIGHTS、CHAIN_PRIORITY

三误判根因及修复

架构审计发现 (2026-07-03)

> 详细分析见 references/architecture-audit-2026-07-03.md。

P0: v0.4 "幽灵架构"

v0.4 编码了 6 个新模块（circuit_breaker/telemetry/embedding/spine/verifier/card，共 2928 行，111 测试），但 weave_chains.py 只导入了 SkillRouter，未使用任何 v0.4 模块。韧性层和验证层完全未接入主路由流。

验证命令：
grep -r "circuit_breaker\|telemetry\|verifier\|embedding\|spine\|card" /opt/data/scripts/weave_chains.py
# 预期输出：空（即未接入）

P1: 注册鸿沟（待解决）

磁盘有 254 个技能，牌组只注册了 72 个。缺失的高价值独立技能：fic-pipeline、a2a-agent-mail、computer-use、self-improving、deepblue-rss-gating 等。缺失的链：MLOps 链、内容管线链、记忆加固链。

R12 质量层（2026-07-03 新增，借鉴万有DAG）

万有DAG的三个关键启发在 R12 落地为3个新函数，零新依赖。

验证协议门 verify_chain_output()

每步执行后强制5项检查（从万有的 Step 4 协议借鉴）：

返回 {status: PASS|WARN|FAIL, checks: {...}, issues: [...]}。

result = verify_chain_output('research-to-writing', 'deep-research-pro',
    {'has_output': True, 'fields': ['title','sources','findings','citations'],
     'format': 'markdown', 'context_consumed': True, 'consumable': True})
# → {status: 'PASS', passed: 5, total: 5}

资产传递规范 CHAIN_OUTPUT_SCHEMAS

定义每链每步的标准输出格式，确保步骤间数据可消费。5条主链已定义：

CHAIN_OUTPUT_SCHEMAS = {
    "research-to-writing": {
        "deep-research-pro": {
            "format": "markdown",
            "required": ["title", "sources", "findings", "citations"],
            "pass_to_next": "findings + sources → copy-editor 的事实基础",
        },
        ...
    },
    "search-to-fetch": {...},
    "legal-document-chain": {...},
    ...
}

并行度检测 detect_parallelism()

分析链步骤间的数据依赖，自动识别可并行组：

代码审查: [codebase-inspection, requesting-code-review] → ⚡1组可并行
记忆→研究: [memory-maintenance, deep-research-pro] → ⚡1组
研究→写作: [deep-research-pro][copy-editor] → 2组串行

对子链（2独立步骤）自动标记可并行 → 父Agent可派2个子Agent同时执行。

失败归因四分类 feedback()

从二元成功/失败升级为四态（借鉴万有 SUCCESS/PARTIAL/FAILED/ERROR）：

python3 weave_chains.py feedback deep-research-pro SUCCESS 3.0  # ✅
python3 weave_chains.py feedback deep-research-pro PARTIAL 2.0  # ⚠️
python3 weave_chains.py feedback deep-research-pro FAILED  1.0  # ❌
python3 weave_chains.py feedback deep-research-pro ERROR   0.5  # 💥
## 技能采购管道（SkillHub）

SkillHub (skillhub.cn) 可作为补充技能采购渠道。已部署：

```bash
# CLI 已安装
skillhub search <关键词>
skillhub install <slug> --dir /opt/data/skills

# 采购→审查→入库 流程
find-skill-skillhub（搜索推荐） → skill-vetter（安全审查） → 注册入牌组

skill-weave 已发布至 SkillHub（#94647, @user_03812eb9），详情见 references/skillhub-publishing.md。

已知限制

• 语义匹配基于关键字重叠，非 embedding 相似度
• 新注册技能需手动灌反馈或等待自然积累
• 只做路由推荐，不自动执行链
• CJK Tokenization Bug（TreeFilter _expand_query）：bigram 展开已修复（n=2），jieba 已安装暂未启用
• 飞书协作链是能力栈非串行管道 —— 链描述已标注 ⚠️
• 基准测试：scripts/benchmark_chain_routing.py — 当前 22/23 = 95.65%（R12 无回归）

外源研究摘要 (2026-06-27)

skill-weave v0.4 规划中研究了三个外部项目/论文，提取可借鉴设计思路。

Darwin-skill (alchaincyf, 4.3k⭐)

• 定位: Skill 优化器（非路由器），自动评估和优化 SKILL.md
• 核心机制: 棘轮（Ratchet，分数只升不降）+ 9维评估体系（总分100，实测占23分）+ 5阶段优化循环
• 独立评分: 每个优化循环启动2个独立子Agent评分，下一轮换评委避免锚定效应
• 可借鉴: 棘轮→skill-weave的熔断回滚；9维评估→skill质量维度特征；独立评分→路由验证层
• 局限: 非路由框架，单skill优化视角，评估成本高（需spawn多子Agent）

微软 SkillOpt (arxiv 2605.23904)

• 定位: 文本空间优化器——把skill文档当"可训练权重"，用训练循环迭代优化
• 核心机制: Rollout→Minibatch Reflection→Bounded Text Update→Validation Gate→Epoch-Wise Meta Update
• 关键设计: 文本学习率（编辑预算）控制改动幅度；双模型分离（target/optimizer）；零推理开销部署
• 可借鉴: Validation Gate→路由更新前held-out验证；Rejected Buffer→失败路由硬约束；文本学习率→路由权重调整步长上限
• 局限: 不做多skill路由，训练成本高（0.6-3.6M tokens/pt），依赖明确验证器

阿里 SKILLWEAVER (arxiv 2606.18051)

• 定位: 组合技能路由——拆解复杂任务→检索子技能→组合成DAG
• 核心机制: Decompose(LLM)→Retrieve(Bi-encoder+FAISS)→Compose(DAG)。创新：SAD反馈回路（用检索结果校正拆解）
• 数据: 2209个MCP技能池；拆解精度51%→67.7%（+SAD）；Token消耗降低99%
• 与我们关系: 互补——他们做任务拆解+技能组合，我们做多技能路由+在线学习。我们是生产级实现。
• 可借鉴: SAD反馈→我们的FeedbackLearner可以加retrieval-informed re-ranking

Hugging Face Harness 实验 (Niklaus 2026-07-06)

• 定位: 验证"外层执行机制 > 模型能力"——冻结权重，只优化Harness
• 数据: DS V4 Pro 同一模型，5种Harness → pooled score 从 3.5% → 80.1%（波动 76 分）
• 关键发现: 0 分来自文件名存储错误（推理全对）；Harness 可跨模型迁移（+14.4 分）；22 轮自动迭代追平 Claude Sonnet 4.6
• 与我们关系: 第三次独立验证（skill-weave v1.7 + SkillWeaver + Harness 实验同一周汇聚）→ 外层编排是正确方向
• 可借鉴: 12 组件 Harness 框架 → 深蓝成熟度自评（kanban t_d93d4633）；Loop Engineering → 缺少自动化验证+迭代层
• 详见 references/niklaus-harness-experiment-2026-07.md

详见 references/skill-weave-brainstorm-clusters-2026-06-27.md。Anthropic Loop Engineering 调研见 references/loop-engineering-research-2026-06-27.md。

v0.4 规划结论

六大集群编织完成。P0六项（零新依赖）：熔断器+OpenTelemetry日志+~~失效检测~~✅+嵌入缓存+双模后端(Ollama+Dify@192.168.0.10:8090)+~~冷启动预热~~✅。学习层复用5个已有技能(error-learning-loop/memory-gating/skill-vetter/skill-routing/skill-weave)。

> ✅ 已实现：失效检测（滑动窗口降权）+ 冷启动预热（tag相似度继承）。详见 references/learner-v2-staleness-warmstart.md。

SkillOpt（上交+微软, 2026.5）提出了将技能文档视为可训练状态的范式——独立优化器模型通过 Rollout→Reflection→Bounded Edit→Validation Gate→Meta Update 五步法自动打磨单个技能。详见 references/skillopt-comparison-2026-06-25.md。

对 Skill Weave 的三个启发：

融合方向 OptiWeave：Skill Weave 负责宏观编排（不变），SkillOpt 负责离线打磨单牌——解决"Weave 不知如何把烂牌变好牌"的核心缺口。

Phase 4 集成：技能路由引擎 (2026-06-23)

Skill Weave 的链语义和触发词体系被选为 Hermes 技能路由的底层引擎，替代原计划的 JSON 倒排索引方案。核心理由：Weave 编码的不只是关键词——是工作流依赖关系（链内先后序、重叠/兼容性检测、伪链识别）。

扩展组件

路由流程

用户消息 → Weave 关键词匹配 (零 token) → Top-10 候选
         → 置信度 < 0.7 → DeepSeek 精排 → Top-3
         → 置信度 ≥ 0.7 → 直接 Top-3

测试结果 (6/6 全命中)

记忆查询 → memory-maintenance ✅ | VM 查询 → nas-ssh-login ✅ | 代码审查 → github-code-review ✅ | 搜索 → search-routing ✅ | 写作 → copy-editor ✅ | 飞书 → feishu-lark-mcp ✅

设计决策：手动中文关键词优于自动 bigram

Weave 的 identify_chain() 基于英文触发词（SKILL.md 的 when 字段），但用户查询是中文。自动 bigram 提取导致"帮我""一下""系统"等通用词污染匹配。手动 24 域 × 精选映射在准确率上远超自动方法。映射表位于 scripts/skill_router.py 的 CN_KEYWORD_MAP 字典中，随新技能增删同步维护。

```