🛠️ SkillForge｜Agent 受控执行与技能演进框架

一个已有工具和基础模型的 Agent，仍然会遇到三个问题：

1. 新任务没有现成技能：只靠通用 Prompt，缺少当前业务的步骤、约束和输出要求。
2. 失败反馈难以转化为改进：不知道问题来自技能、工具、权限还是验证器；盲目重试可能越修越错。
3. 经验不能稳定复用：把一次成功直接写进全局指令，容易固化偶然策略；修改技能又可能破坏原有能力。

SkillForge 的主线是 “快速生成 → 当前任务试用 → 带证据演进 → 后续检索复用”，不是训练基础模型权重，也不是让 Agent 无限制地重写自己。

核心理念：记住一次经历，与接受一项长期能力，是两个不同的决策。

用户说：“查一下订单中所有包裹的物流，汇总状态并给出处理建议。”

下面是业务流程示意；完整机制由离线集成场景覆盖，真实模型实验分别验证了失败修补与用户变向后的复用分支。

flowchart TB
    Q["短需求 / 对话"] --> D["任务内 Draft<br/>目标、约束与来源"]
    F["正式 Skill 检索<br/>权限 / 依赖 / 验证 / 部署筛选"] --> R
    D --> R["AgentRuntime<br/>冻结正文、预算与取消"]
    R --> B["Tool Broker<br/>工具准入与参数校验"]
    B --> A["任务输出与工具轨迹"]

    A --> V["产物验证 / ValidationReceipt"]
    V -->|可修产物缺陷| N["窄域局部修复"]
    N --> V

    A --> E["Collector → Episode<br/>任务、意图、版本与用途"]
    E --> M["模式提炼 / 用例提案 / 失败归因"]
    M --> C["Skill Candidate / RepairJob"]
    C --> G["共同门禁与行为回归"]
    G -->|允许的异常、显式启用| L["有界 LangGraph 恢复"]
    L --> C
    G -->|有效 PASS + 显式确认| P["正式 Skill 与版本治理"]
    P --> F

    classDef run fill:#eff6ff,stroke:#2563eb;
    classDef repair fill:#fef2f2,stroke:#dc2626;
    classDef learn fill:#faf5ff,stroke:#7c3aed;
    classDef gate fill:#fffbeb,stroke:#d97706;
    class R,B,A run;
    class V,N repair;
    class E,M,C,L learn;
    class G,P,F gate;

任务内闭环修复当前产物；跨任务闭环改进长期技能。两者共享责任边界，但不是同一种修复对象，也不共用一个“无限重试”入口。

解决什么： 不必等到积累多次成功经历才生成草稿；同时，用户改目标时不能只改一个标签，或让旧运行悄悄读到新正文。

如何实现：

• generate_candidate_from_requirement 接受需求 / 对话来源，生成任务内 Draft；同任务重复请求去重，私有草稿不跨任务共享。
• TaskContext 区分任务意图修订与 Skill 发布版本。明确变向修订草稿正文；同义措辞不重复生成，模糊变化先确认。
• Runtime 在启动时持久化完整正文与版本绑定，重建后仍读取旧快照；迟到结果归回旧意图，而不是成为新目标的成功正例。

为何这样设计： 草稿降低新任务的使用门槛；快照把“本次到底执行了哪份指令”固定下来，使变向、复现与后续归因有明确参照。会话级目标变化也不会全局废除仍适用的正式 Skill。

🔎 生成器 · 任务上下文 · 生成与试用专项 · 快照 / 迁移专项

解决什么： “运行失败”太宽泛。权限被拒、工具不可用、业务输出错误，不能都靠修改 Skill 解决。

如何实现：

• AgentRuntime 管理预算、超时与取消；ToolBroker 在 handler 执行前检查权限与参数，并记录输入、结果和错误。
• ValidationReceipt 记录规则、问题位置、允许修复动作和责任层，并绑定产物内容与验证器配置。
• 产物级 repair_artifact 只修允许的局部路径，最多两轮，重复指纹停止；finalize_run 对当前产物重新验证。
• 长期 Skill 的 RepairJob 使用经历与业务失败反馈修补指令，不把 policy / tool / evaluator 等问题直接归为技能缺陷。

为何这样设计： 结构化反馈告诉修复器“哪里错、允许改什么”；责任层限制“该不该修”；交付重验防止拿旧 PASS 为新内容背书。应用层 Broker 与 macOS Seatbelt 进程隔离相互补充，但前者不能替代 OS 沙箱。

🔎 Runtime / Broker · Receipt · 平台沙箱 · 局部修复专项

解决什么： 一次偶然成功不应直接变成长期规则；针对一个 Badcase 的修补也可能损害正常能力。

如何实现：

• EpisodeStore 持久化任务、工具轨迹、意图与版本；学习入口按 ID 读取规范内容，拒绝评测用途或伪造经历。
• 三层记忆区分 Semantic 事实、Episodic 经历与 Procedural 技能；需求 / 文档不冒充 Episode。
• PatternMining 先按业务范围、意图与工具契约分组，再按相似度与独立任务支持度提炼；成功样本帮助描述适用范围，失败样本暴露边界。
• trace 提纯为带工具快照和独立预期的开发 / 回归用例提案；开发反馈与锁定评测按来源、派生家族及近重复关系隔离。
• 共同门禁串起来源、结构、长度、依赖与行为验证；criteria_v1 用评测前冻结的 Rubric 分别判断 Baseline 与 Skill，模型只返回规则状态与证据，分数和关键性由代码决定。任务完成度与鲁棒性优先使用代码 Oracle；可读性保留顺序平衡的 Pairwise，效率依据执行日志。
• 关键规则确证 FAIL 时，即使冷启动或总分高也拒绝晋升；UNKNOWN / 解析异常使评测无效并 fail-closed，但不当作确认的业务缺陷。评分策略或 Rubric 变化会使旧验证／缓存失效，旧、新策略不直接比较。
• 权威验证记录绑定候选正文、规范基线、意图、验证配置（含评分策略与 Rubric 指纹）及数据集；任何绑定漂移都不能沿用旧 PASS。

为何这样设计： 来源回答“改进依据是什么”，独立 oracle 回答“业务是否正确”，正常回归提供“没有修坏原能力”的反证。用途隔离旨在避免把看过的评测答案重新当作能力证据；门禁仍取决于用例质量，不等于证明普遍泛化。

Judge 校准证据（2026-10-03）： glm-5.3-flash 在 16 个合成答案、64 项主规则上的总体匹配率为 52/64（81.25%）；排除 3 条无法解析主评记录后的子集为 51/52（98.08%），不能当总体准确率。当前夹具的关键违规捕获 5/5、确证违规虚警 0/25，但合规关键判定仍有 5/25 UNKNOWN；仅完成的 2 组重测状态向量一致 0/2、门禁一致 1/2。这是独立 Judge 校准，不是业务 Agent 全链路或 Skill 收益实验，不能据此声称全域零误判或稳定性已验证。详见 原始结果。

长度护栏的取舍： 单章节增长 >25% 且 净增 >1000 policy tokens，或全文 >1.20 倍 且 净增 >1000 tokens，才触发长度 REVIEW。这样允许短草稿从几十 tokens 合理扩展，同时关注较大的绝对增量。无基线新建另设默认 3000 字符上限。1000 是可配置工程策略，cl100k_base 用于一致计数，不代表 GLM 原生 token 或已验证的注意力临界点。

🔎 经历与候选 Store · 模式提炼 · 用例提案 · 评测门禁 · Criteria 评测指南 · 数据用途专项

解决什么： 修补过程可能中断、重复生成或消耗失控；即便产生了好候选，也不能在图节点中绕过验证直接覆盖正式版。

如何实现：

• 实际 repair_skill_failure(enable_shadow_recovery=True) 入口接入 LangGraph 恢复节点与当前 RepairJob；普通小改不强制走图。
• 复用既有 SQLite 检查点与序列化基础设施，适配当前演进链的业务节点，避免与旧 Evolver 混用两套预算和发布路径。
• 图与内部修补共享尝试、调用、token 和原始截止期限；重建不重置预算，重复候选、无进展或绑定漂移停止恢复。
• 图只返回重验后的候选；正式晋升仍需权威验证记录与显式确认。
• 正式 Skill 通过检索筛选与运行级版本固定进入新任务；部署层使用 expected_revision / CAS 检查，支持灰度与受控版本回滚。
• 拆分器只提出建议：不同意图 / 前提、可分路由与独立评测才是拆分依据，不因 Skill 长或共享工具就自动拆。

为何这样设计： 检查点保存恢复位置，候选与 RepairJob 保存业务状态；预算提供终止条件，显式晋升提供接受能力的边界。固定版本使旧运行可追溯，版本回滚则只改变后续选择，不声称撤销已发生的外部副作用。

🔎 有界恢复 · 实际修补入口 · 正式检索 · 版本部署 · 恢复集成专项

“为何这样设计”是机制解释；“实际验证了什么”要看独立断言、运行轨迹和原始结果。 项目分别用离线集成测试与真实模型小样本验证不同层面的能力。

2026-10-01，指定 8 文件回归实跑 61 passed，exit 0（含恢复专项 11 项）；不是全仓测试总数。

离线物流专项还覆盖生成、试用、变向、业务失败、修补、确认晋升和后续复用。FakeLLM 用于让故障与边界可重复触发；它验证框架行为，不用于宣称真实模型能力提升。

使用 Ark glm-5.3-flash 和 synthetic 多包裹订单，已有两条分别保留的真实模型分支：

• 失败修补分支：真实生成 V1，基于 DEV 经历 / 反馈修补 V2，并保存小样本 A/B/C 输出及工具轨迹。
• 用户变向与复用分支：修订为 STATUS_ONLY，通过当前验证与显式确认后，在临时测试库晋升；后续新任务不手填 Skill ID，经实际 Runtime / Broker 执行，Collector 回收新 Episode。

历史标为 LOCKED 的 6 项结果是 A 无 Skill 5/6、B V1 5/6、C V2 6/6。这说明该批记录中观察到一次配对改善；由于修订前冻结与派生血缘证据不完整，不能据此证明干净 heldout 上的泛化或统计显著收益。

📊 真实模型原始记录 · 物流实验总索引 · 调用账本

git clone https://github.com/SuperGODOG/skillforge.git
cd skillforge
git switch linux

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/skillforge --help

Python 3.10+；macOS 可使用 Seatbelt 平台接口，其他平台不具有同等 OS 隔离证据。

CLI 保留 demo、route、evaluate、evolve。快速生成、变向与新恢复链通过 Python 接口和集成场景展示，旧 CLI demo 不等于全部生命周期。

# 需求 → Draft → 当前任务试用（FakeLLM）
.venv/bin/pytest tests/test_quick_gen_and_trial.py -v

# 用户改目标：正文修订、旧运行隔离与权限边界（FakeLLM）
.venv/bin/pytest tests/test_p3_goal_shift_and_revision.py -v

# 从实际修补入口进入 LangGraph，检查共享预算与恢复（FakeLLM）
.venv/bin/pytest tests/test_p5_langgraph_repair_integration.py -v

这些专项帮助定位实现与断言，不需要模型 API key。完整指定回归命令放在下面，避免把测试总数当成项目亮点本身。

.venv/bin/pytest \
  tests/test_p5_langgraph_repair_integration.py \
  tests/test_p5_bounded_recovery_and_split.py \
  tests/test_p2d_langgraph.py \
  tests/test_source_snapshot_and_migration_closure.py \
  tests/test_runtime_and_tool_broker.py \
  tests/test_failure_attribution_and_patching.py \
  tests/test_receipt_and_narrow_repair.py \
  tests/test_p2_gate_and_lifecycle.py -q

evaluate、evolve 及真实实验脚本可能访问模型服务，需要自行配置凭据与预算；不要提交 .env、密钥、运行数据库或真实订单。仓库 checkpoint JSON 是脱敏实验记录，不是可直接接管的生产状态。

src/skillforge/
├── skill_generator.py     # 短需求 / 对话 → Draft / Candidate
├── task_context.py        # 任务契约、意图修订与运行归属
├── runtime.py             # 冻结快照、预算、ToolBroker、产物修复
├── sandbox.py             # 平台沙箱接口与依赖探测
├── receipt.py             # 结构化诊断凭据与修复边界
├── collector.py           # 执行轨迹 → Episode
├── episode.py             # EpisodeStore / CandidateStore / 验证记录
├── memory.py              # Semantic / Episodic / Procedural 分层
├── pattern_mining.py      # 兼容分组、支持度与模式提炼
├── trace_purification.py  # trace → 可复现用例提案
├── data_partition.py      # 用途、家族与评测分区
├── repair.py              # 失败归因、RepairJob、显式晋升
├── bounded_recovery.py    # 适配当前演进链的 LangGraph 恢复
├── langgraph_loop.py      # 既有图基础设施与 SQLite 检查点
├── skill_splitter.py      # 拆分建议，不自动发布
├── retrieval.py           # 正式 Skill 筛选与检索
├── deployments.py         # CAS、灰度与受控版本回滚
├── evaluator/             # 结构 / 长度 / 依赖 / 行为门禁
└── scenarios/             # synthetic 物流与模型实验

项目基于 HelloAgents、LangGraph 等开源组件实现。当前仓库未提供独立 LICENSE 文件，使用与再分发前请确认项目及各依赖的许可条件。