{
  "canonical_name": "s4b7-ai/s4b7-ai-skills",
  "compilation_id": "pack_3384feb0fe9d454e98c63034d6141cbd",
  "created_at": "2026-05-15T06:14:49.177539+00:00",
  "created_by": "project-pack-compiler",
  "feedback": {
    "carrier_selection_notes": [
      "viable_asset_types=skill, recipe, host_instruction, eval, preflight",
      "recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
    ],
    "evidence_delta": {
      "confirmed_claims": [
        "identity_anchor_present",
        "capability_and_host_targets_present",
        "install_path_declared_or_better"
      ],
      "missing_required_fields": [],
      "must_verify_forwarded": [
        "Run or inspect `npx skills` in an isolated environment.",
        "Confirm the project exposes the claimed capability to at least one target host."
      ],
      "quickstart_execution_scope": "allowlisted_sandbox_smoke",
      "sandbox_command": "npx skills",
      "sandbox_container_image": "node:22-slim",
      "sandbox_execution_backend": "docker",
      "sandbox_planner_decision": "deterministic_isolated_install",
      "sandbox_validation_id": "sbx_a81d6098117f4bdf96be23d791a9501a"
    },
    "feedback_event_type": "project_pack_compilation_feedback",
    "learning_candidate_reasons": [],
    "template_gaps": []
  },
  "identity": {
    "canonical_id": "project_cdec0a5142d898e11238af23b1b38777",
    "canonical_name": "s4b7-ai/s4b7-ai-skills",
    "homepage_url": null,
    "license": "unknown",
    "repo_url": "https://github.com/s4b7-ai/s4b7-ai-skills",
    "slug": "s4b7-ai-skills",
    "source_packet_id": "phit_425c78561d8543b7a3183f94acf7de5e",
    "source_validation_id": "dval_b4079d7060694641894b0f348329da88"
  },
  "merchandising": {
    "best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
    "github_forks": 0,
    "github_stars": 0,
    "one_liner_en": "Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.",
    "one_liner_zh": "Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.",
    "primary_category": {
      "category_id": "software-development",
      "confidence": "medium",
      "name_en": "Software Development",
      "name_zh": "软件开发与交付",
      "reason": "matched_keywords:git, cli"
    },
    "target_user": "使用 local_cli 等宿主 AI 的用户",
    "title_en": "s4b7-ai-skills",
    "title_zh": "s4b7-ai-skills 能力包",
    "visible_tags": [
      {
        "label_en": "Browser Agents",
        "label_zh": "浏览器 Agent",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "product_domain-browser-agents",
        "type": "product_domain"
      },
      {
        "label_en": "Web Task Automation",
        "label_zh": "网页任务自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "user_job-web-task-automation",
        "type": "user_job"
      },
      {
        "label_en": "Browser Automation",
        "label_zh": "浏览器自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "core_capability-browser-automation",
        "type": "core_capability"
      },
      {
        "label_en": "Page Observation and Action Planning",
        "label_zh": "页面观察与动作规划",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "workflow_pattern-page-observation-and-action-planning",
        "type": "workflow_pattern"
      },
      {
        "label_en": "Local-first",
        "label_zh": "本地优先",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "selection_signal-local-first",
        "type": "selection_signal"
      }
    ]
  },
  "packet_id": "phit_425c78561d8543b7a3183f94acf7de5e",
  "page_model": {
    "artifacts": {
      "artifact_slug": "s4b7-ai-skills",
      "files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json",
        "REPO_INSPECTION.md",
        "CAPABILITY_CONTRACT.json",
        "EVIDENCE_INDEX.json",
        "CLAIM_GRAPH.json"
      ],
      "required_files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json"
      ]
    },
    "detail": {
      "capability_source": "Project Hit Packet + DownstreamValidationResult",
      "commands": [
        {
          "command": "npx skills",
          "label": "Node.js / npx · 官方安装入口",
          "source": "https://github.com/s4b7-ai/s4b7-ai-skills#readme",
          "verified": true
        }
      ],
      "display_tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "浏览器自动化",
        "页面观察与动作规划",
        "本地优先"
      ],
      "eyebrow": "软件开发与交付",
      "glance": [
        {
          "body": "判断自己是不是目标用户。",
          "label": "最适合谁",
          "value": "需要软件开发与交付能力，并使用 local_cli的用户"
        },
        {
          "body": "先理解能力边界，再决定是否继续。",
          "label": "核心价值",
          "value": "Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops."
        },
        {
          "body": "未完成验证前保持审慎。",
          "label": "继续前",
          "value": "publish to Doramagic.ai project surfaces"
        }
      ],
      "guardrail_source": "Boundary & Risk Card",
      "guardrails": [
        {
          "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
          "label": "Check 1",
          "value": "不要把试用当真实运行"
        },
        {
          "body": "local_cli",
          "label": "Check 2",
          "value": "确认宿主兼容"
        },
        {
          "body": "publish to Doramagic.ai project surfaces",
          "label": "Check 3",
          "value": "先隔离验证"
        }
      ],
      "mode": "skill, recipe, host_instruction, eval, preflight",
      "pitfall_log": {
        "items": [
          {
            "body": "仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。",
            "category": "身份坑",
            "evidence": [
              "identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills"
            ],
            "severity": "medium",
            "suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
            "title": "仓库名和安装名不一致",
            "user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
          },
          {
            "body": "README/documentation is current enough for a first validation pass.",
            "category": "能力坑",
            "evidence": [
              "capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass."
            ],
            "severity": "medium",
            "suggested_check": "将假设转成下游验证清单。",
            "title": "能力判断依赖假设",
            "user_impact": "假设不成立时，用户拿不到承诺的能力。"
          },
          {
            "body": "未记录 last_activity_observed。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing"
            ],
            "severity": "medium",
            "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
            "title": "维护活跃度未知",
            "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "进入安全/权限治理复核队列。",
            "title": "下游验证发现风险项",
            "user_impact": "下游已经要求复核，不能在页面中弱化。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
            "title": "存在评分风险",
            "user_impact": "风险会影响是否适合普通用户安装。"
          },
          {
            "body": "issue_or_pr_quality=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown"
            ],
            "severity": "low",
            "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
            "title": "issue/PR 响应质量未知",
            "user_impact": "用户无法判断遇到问题后是否有人维护。"
          },
          {
            "body": "release_recency=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown"
            ],
            "severity": "low",
            "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
            "title": "发布节奏不明确",
            "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
          }
        ],
        "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
        "summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
        "title": "踩坑日志"
      },
      "snapshot": {
        "contributors": 1,
        "forks": 0,
        "license": "unknown",
        "note": "站点快照，非实时质量证明；用于开工前背景判断。",
        "stars": 0
      },
      "source_url": "https://github.com/s4b7-ai/s4b7-ai-skills",
      "steps": [
        {
          "body": "不安装项目，先体验能力节奏。",
          "code": "preview",
          "title": "先试 Prompt"
        },
        {
          "body": "理解输入、输出、失败模式和边界。",
          "code": "manual",
          "title": "读说明书"
        },
        {
          "body": "把上下文交给宿主 AI 继续工作。",
          "code": "context",
          "title": "带给 AI"
        },
        {
          "body": "进入主力环境前先完成安装入口与风险边界验证。",
          "code": "verify",
          "title": "沙箱验证"
        }
      ],
      "subtitle": "Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.",
      "title": "s4b7-ai-skills 能力包",
      "trial_prompt": "# s4b7-ai-skills - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 s4b7-ai-skills 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. skill-structure：技能文件结构。围绕“技能文件结构”模拟一次用户任务，不展示安装或运行结果。\n3. skill-categories：技能分类体系。围绕“技能分类体系”模拟一次用户任务，不展示安装或运行结果。\n4. langgraph-agent：LangGraph Agent技能。围绕“LangGraph Agent技能”模拟一次用户任务，不展示安装或运行结果。\n5. ai-sdk-core：AI SDK Core技能。围绕“AI SDK Core技能”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. skill-structure\n输入：用户提供的“技能文件结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. skill-categories\n输入：用户提供的“技能分类体系”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. langgraph-agent\n输入：用户提供的“LangGraph Agent技能”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. ai-sdk-core\n输入：用户提供的“AI SDK Core技能”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / skill-structure：Step 2 必须围绕“技能文件结构”形成一个小中间产物，并等待用户确认。\n- Step 3 / skill-categories：Step 3 必须围绕“技能分类体系”形成一个小中间产物，并等待用户确认。\n- Step 4 / langgraph-agent：Step 4 必须围绕“LangGraph Agent技能”形成一个小中间产物，并等待用户确认。\n- Step 5 / ai-sdk-core：Step 5 必须围绕“AI SDK Core技能”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/s4b7-ai/s4b7-ai-skills\n- https://github.com/s4b7-ai/s4b7-ai-skills#readme\n- skills/a2a-orchestrator/SKILL.md\n- skills/aacp/SKILL.md\n- skills/acp-delegate-auto/SKILL.md\n- skills/agent-cryst/SKILL.md\n- skills/ai-sdk-core/SKILL.md\n- skills/codex-context/SKILL.md\n- skills/codex-latex/SKILL.md\n- skills/codex-policy-steering/SKILL.md\n- skills/command-center/SKILL.md\n- skills/crystallize/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 s4b7-ai-skills 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n  2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
      "voices": [
        {
          "body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
          "items": [],
          "status": "待发现 Agent 补证",
          "title": "社区讨论"
        }
      ]
    },
    "homepage_card": {
      "category": "软件开发与交付",
      "desc": "Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops.",
      "effort": "安装已验证",
      "forks": 0,
      "icon": "code",
      "name": "s4b7-ai-skills 能力包",
      "risk": "需复核",
      "slug": "s4b7-ai-skills",
      "stars": 0,
      "tags": [
        "浏览器 Agent",
        "网页任务自动化",
        "浏览器自动化",
        "页面观察与动作规划",
        "本地优先"
      ],
      "thumb": "gray",
      "type": "Skill Pack"
    },
    "manual": {
      "markdown": "# https://github.com/s4b7-ai/s4b7-ai-skills 项目说明书\n\n生成时间：2026-05-14 11:20:31 UTC\n\n## 目录\n\n- [项目概览](#overview)\n- [安装指南](#installation)\n- [技能文件结构](#skill-structure)\n- [技能分类体系](#skill-categories)\n- [LangGraph Agent技能](#langgraph-agent)\n- [AI SDK Core技能](#ai-sdk-core)\n- [Agent-Cryst技能](#agent-cryst)\n- [编写技能指南](#write-a-skill)\n- [Crystallize技能](#crystallize)\n- [模型身份管理](#model-identity)\n\n<a id='overview'></a>\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装指南](#installation), [技能分类体系](#skill-categories)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n- [skills/codex-latex/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-latex/SKILL.md)\n- [skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)\n- [skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)\n- [skills/shadow-continuity/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-continuity/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n</details>\n\n# 项目概览\n\n## 项目简介\n\n`s4b7-ai-skills` 是一个模块化的 AI 技能库集合，为多种 AI Agent 系统（Codex、Claude、Gemini、Shadow 等）提供可复用的工作流模式、技能定义和工具链集成。该项目采用技能即服务（Skill-as-a-Service）架构，通过标准化的 `SKILL.md` 模板实现跨平台的能力复用。\n\n**核心特性：**\n- 多 Agent 平台兼容（Codex、Claude、OpenAI、Gemini、Ollama）\n- 标准化技能描述格式\n- 模式结晶（Crystallization）机制\n- MCP（Model Context Protocol）协议集成\n- 跨模型委托路由\n\n资料来源：[skills/write-a-skill/SKILL.md](skills/write-a-skill/SKILL.md)\n\n## 系统架构\n\n### 架构分层\n\n```mermaid\ngraph TD\n    subgraph \"用户层\"\n        U[用户请求]\n    end\n    subgraph \"Agent 层\"\n        C[Codex Agent]\n        CL[Claude Agent]\n        G[Gemini Agent]\n        S[Shadow Agent]\n    end\n    subgraph \"技能层\"\n        SK[技能注册表]\n        CR[结晶模式]\n        RT[运行时配置]\n    end\n    subgraph \"工具层\"\n        MCP[MCP 服务器]\n        OLL[Ollama 本地模型]\n        API[外部 API]\n    end\n    U --> C & CL & G & S\n    C & CL & G & S --> SK\n    SK --> RT\n    RT --> MCP & OLL & API\n```\n\n### 技能分类体系\n\n| 技能类别 | 功能范围 | 代表技能 |\n|---------|---------|---------|\n| 代码工程 | 代码分析、重构、调试 | `shadow-refactor`、`codex-context` |\n| 记忆管理 | 持久化记忆、上下文提取 | `qmd-memory`、`shadow-mcp-gadgets` |\n| 文档生成 | LaTeX 论文、技术文档 | `codex-latex` |\n| 知识合成 | 多模型查询、观点整合 | `multi-model-query` |\n| 知识产权 | 专利队列、发明挖掘 | `patent-queue` |\n| 工程情报 | 汽车行业竞品分析 | `shadow-engg` |\n| 代理编排 | 自动委托、路由决策 | `acp-delegate-auto` |\n\n资料来源：[skills/shadow-engg/SKILL.md](skills/shadow-engg/SKILL.md)\n\n## 核心组件详解\n\n### 1. 技能定义规范\n\n每个技能通过标准化的 `SKILL.md` 文件定义，采用 YAML frontmatter + Markdown 结构：\n\n```yaml\n---\nname: skill-name\ndescription: 技能描述. Use when [触发关键词].\n---\n```\n\n**描述要求：**\n- 最大 1024 字符\n- 第三人称撰写\n- 首句说明功能\n- 第二句包含触发条件\n\n**技能文档结构：**\n- Quick Start（快速开始）\n- Workflows（工作流程）\n- Advanced features（高级特性）\n- 参考文档链接\n\n资料来源：[skills/write-a-skill/SKILL.md](skills/write-a-skill/SKILL.md)\n\n### 2. MCP 工具生态系统\n\n`shadow-mcp-gadgets` 技能提供统一的 MCP 工具路由：\n\n| 工具 | 功能 | 触发词 |\n|-----|------|-------|\n| ARC | 记忆存储与检索 | `arc.store`, `arc.search` |\n| ESP | 统一上下文组装 | `esp.assemble`, `/renew-ctx` |\n| ANT | Tailscale 网络健康检查 | `ant.mesh` |\n| TAP | Chrome 浏览器标签与执行 | `tap.tabs`, `tap.execute` |\n| OWL | Bee AI 环境信息提取 | `owl.brief`, `owl.extract` |\n| ORB | macOS 语音合成 | `orb.say`, `orb.voices` |\n| DEN | 物理环境传感器 | `den.environment` |\n| factory | 专利草稿生成 | `factory.new`, `factory.draft` |\n\n**工具管线流程：**\n\n```\nInput (触发词)\n  ↓\n路由到对应 Gadget\n  ↓\n执行 MCP 工具调用\n  ↓\n生成制品 (记忆条目/上下文状态/内联响应)\n```\n\n资料来源：[skills/shadow-mcp-gadgets/SKILL.md](skills/shadow-mcp-gadgets/SKILL.md)\n\n### 3. 结晶机制（Crystallization）\n\n`crystallize` 技能从会话中提取可复用模式：\n\n**结晶流程：**\n\n```mermaid\ngraph LR\n    A[任务完成] --> B{应该重复吗?}\n    B -->|是| C[审查会话]\n    B -->|否| Z[完成]\n    C --> D[提取模式]\n    D --> E{有重叠技能?}\n    E -->|有| F[更新现有技能]\n    E -->|无| G[创建新技能]\n    F --> H[记录结晶元数据]\n    G --> H\n```\n\n**模式分类：**\n- **Key steps**：产生结果的最少步骤序列\n- **Heuristics**：判断规则和经验法则\n- **Gotchas**：常见错误和失败假设\n- **Decision points**：方案选择决策点\n\n**提升级别：**\n| 级别 | 存储位置 | 说明 |\n|-----|---------|------|\n| Level 1 | `docs/plans/` | 有用但非权威 |\n| Level 2 | YAML/JSON | 机器可读真理 |\n| Level 3 | 技能库 | 可复用操作模式 |\n| Level 4 | 运行时文件 | 系统实际消费 |\n\n资料来源：[skills/crystallize/SKILL.md](skills/crystallize/SKILL.md)\n\n### 4. 多模型委托路由\n\n`acp-delegate-auto` 技能实现智能模型选择：\n\n**路由启发式规则：**\n\n| 提示词包含... | 路由目标 |\n|-------------|---------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| 文件路径、diffs、PRs | codex |\n\n**模型层级体系：**\n\n| 层级 | 来源 | 成本 | 特点 |\n|-----|------|-----|------|\n| Tier 1 | Ollama (本地) | 免费 | 快速、本地隐私 |\n| Tier 2 | OpenRouter API | 按量计费 | 多模型聚合 |\n| Tier 3 | Web 浏览器 | 间接成本 | 实时信息获取 |\n| Tier 4 | Codex 自身 | 总会话可用 | 固有能力 |\n\n**qwen3 模型特殊处理：**\n- 需在提示前添加 `/no_think`\n- 或设置 `options.think = false`\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](skills/acp-delegate-auto/SKILL.md)\n\n## 工作流集成\n\n### Shadow 连续性管理\n\n`shadow-continuity` 技能管理工件的生命周期：\n\n```mermaid\ngraph TD\n    A[Stream 输入] --> B[分类层]\n    B --> C{层类型判断}\n    C -->|架构| D[architecture]\n    C -->|配置| E[config/map]\n    C -->|脚手架| F[scaffold]\n    C -->|技能| G[skill]\n    C -->|报告| H[report]\n    D & E & F & G & H --> I[推送到仓库]\n    I --> J{稳定性检查}\n    J -->|稳定| K[提升到技能/canonical]\n    J -->|不稳定| L[保留在 plan/note]\n    K --> M[运行时消费]\n```\n\n**输出规则：**\n- 用户文档：简洁结构化\n- 机器文档：YAML/JSON 优先\n- 运行时脚手架：最小但真实\n- 技能：仅可复用模式\n\n资料来源：[skills/shadow-continuity/SKILL.md](skills/shadow-continuity/SKILL.md)\n\n### 代码重构工作流\n\n`shadow-refactor` 技能提供结构化重构：\n\n```mermaid\ngraph TD\n    A[扫描目标代码库] --> B[识别模式]\n    B --> C{发现重复?}\n    C -->|是| D[标记重复]\n    C -->|否| E{复杂度热点?}\n    E -->|是| F[标记热点]\n    E -->|否| G[分析测试覆盖]\n    D & F --> H[生成修复计划]\n    H --> I[TDD 循环]\n    I --> J{验证通过?}\n    J -->|否| K[自修复]\n    J -->|是| L[信号工具]\n    K --> I\n    L --> M[继续下一个问题]\n```\n\n**Fallback 链：**\n1. 完整 SCAN → TDD 循环 → 验证 → 信号\n2. Ollama 不可用：静态分析\n3. 无测试套件：扫描并脚手架测试\n4. 修复耗尽：回滚并记录\n\n资料来源：[skills/shadow-refactor/SKILL.md](skills/shadow-refactor/SKILL.md)\n\n## 记忆系统\n\n`qmd-memory` 提供多层次记忆管理：\n\n### 记忆类型\n\n| 类型 | 用途 | 示例 |\n|-----|------|------|\n| `fact` | 永久事实 | \"TypeScript 是主要语言\" |\n| `commitment` | 承诺事项 | \"周五前完成设置\" |\n| `decision` | 决策记录 | \"决定使用本地优先\" |\n| `preference` | 偏好设置 | \"喜欢使用 vim\" |\n| `context` | 上下文信息 | 当前会话状态 |\n\n### CLI 命令\n\n```bash\n# 存储记忆\nqmd-memory store \"内容\" --kind fact --tag work\n\n# 检索记忆\nqmd-memory recall --kind fact --limit 5\n\n# 从文本提取\nqmd-memory extract notes.md --source-id \"file:notes.md\"\n```\n\n### Profile 层\n\n| 层 | 特性 | 持久性 |\n|---|------|--------|\n| static | 永久事实（身份、偏好、工具、关系） | 长期 |\n| dynamic | 近期上下文（当前焦点、最近操作） | 会话 |\n\n资料来源：[skills/qmd-memory/SKILL.md](skills/qmd-memory/SKILL.md)\n\n## 配置与集成\n\n### Codex CLI 配置\n\n| 配置项 | 值 | 说明 |\n|-------|-----|------|\n| Model | `gpt-5.5` | reasoning effort: low |\n| Sandbox | `danger-full-access` | 完整访问权限 |\n| Approval policy | `never` | 全自动模式 |\n| Token limit | 25,000 | 工具输出限制 |\n| Features | multi_agent, memories, chronicle, js_repl, apps | 启用特性 |\n\n**Caveman 模式：**\n- 简洁智能通信风格\n- 模式：`[事物] [动作] [原因]. [下一步].`\n- 企业区例外：Astemo/Honda/fh4s 保持正常散文\n\n资料来源：[skills/codex-context/SKILL.md](skills/codex-context/SKILL.md)\n\n### MCP 服务器\n\n| 服务器 | 路径/URL |\n|--------|---------|\n| RepoPrompt | `/Users/sdluffy/RepoPrompt/repoprompt_cli` |\n| chrome_devtools | `/Users/sdluffy/bin/chrome-devtools-mcp-work` |\n| notion | `https://mcp.notion.com/mcp` |\n| openevidence | `node .../openevidence-mcp/dist/server.js` |\n| playwright | `/Users/sdluffy/bin/playwright-mcp-work` |\n\n## 专利与文档生成\n\n### 专利队列管理\n\n| 命令 | 功能 | 触发词 |\n|-----|------|--------|\n| `new` | 创建新专利草稿 | `patent new` |\n| `mine` | 挖掘发明候选 | `patent mine` |\n| `queue` | 查看候选队列 | `patent queue` |\n| `export <ID>` | Obsidian 导出 | `patent obsidian` |\n| `synthesize` | 组合概览输出 | `patent synthesize` |\n\n### LaTeX 论文生成\n\n`codex-latex` 支持多种模板：\n\n| 模板类型 | 适用场景 |\n|---------|---------|\n| IEEE Conference | 会议论文 |\n| ACM | 学术论文 |\n| Patent Specification | 专利规范 (SP-001/002/003) |\n| Engineering Report | 工程报告 |\n| Research Paper | 研究论文 |\n\n**构建流程：**\n```bash\nlatexmk -pdf paper.tex  # 自动处理多次编译\n```\n\n资料来源：[skills/codex-latex/SKILL.md](skills/codex-latex/SKILL.md)\n\n## 设计系统\n\n### 配色方案\n\n| 系统 | 主色 | 辅色 | 背景 |\n|------|------|------|------|\n| Shadow Enterprise | `#4a9eff` (蓝) | `#8b5cf6` (紫) | `#09090b` (深) |\n| Astemo/Honda | `#B6001A` (红) | Arial 字体 | 白色/浅色表面 |\n\n### 文件路由规范\n\n| 制品类型 | 存储路径 | 用途 |\n|---------|---------|------|\n| 工具信号 | `tools/integrate/tool-signals.jsonl` | 每次修复结果 |\n| 重构报告 | `ShadowArchive/80-reports/refactor-*.md` | 会话摘要 |\n| 扫描报告 | `ShadowArchive/80-reports/mesh-*.md` | 网络扫描结果 |\n| 专利草稿 | `docs/patents/SP-NNN/` | 规范、权利要求、提交指南 |\n| 专利队列 | `ShadowArchive/10-projects/patent-queue/` | 候选队列 JSON |\n\n## 总结\n\n`s4b7-ai-skills` 项目构建了一个全面的 AI Agent 技能生态系统，通过标准化技能定义、多层次记忆系统、智能路由委托和模式结晶机制，实现了跨平台的 AI 能力复用。项目的模块化设计使得各个技能可以独立演进，同时通过统一的架构规则保持整体一致性。\n\n---\n\n<a id='installation'></a>\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目概览](#overview), [技能文件结构](#skill-structure)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)\n- [distribution.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/distribution.json)\n- [scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)\n</details>\n\n# 安装指南\n\n本页面详细介绍 s4b7-ai-skills 项目的安装流程、环境配置及常见问题的解决方案。\n\n## 系统要求\n\n在开始安装之前，请确保您的系统满足以下要求：\n\n| 组件 | 最低版本 | 推荐版本 | 说明 |\n|------|----------|----------|------|\n| Node.js | 18.0.0 | 20.x LTS | 支持 ES 模块和现代 JavaScript 特性 |\n| npm | 9.0.0 | 10.x | 包管理工具 |\n| git | 2.30.0 | 最新版 | 用于版本控制和依赖拉取 |\n| 操作系统 | macOS 12+ / Ubuntu 20.04+ / Windows 10+ | - | 跨平台支持 |\n\n资料来源：[package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)\n\n## 安装方式\n\n### 方式一：npm 全局安装（推荐）\n\n使用 npm 进行全局安装是最简便的方式：\n\n```bash\nnpm install -g s4b7-ai-skills\n```\n\n安装完成后，可以通过以下命令验证：\n\n```bash\ns4b7-ai-skills --version\n```\n\n资料来源：[scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)\n\n### 方式二：本地项目安装\n\n将 s4b7-ai-skills 作为项目依赖安装：\n\n```bash\n# 创建项目目录\nmkdir my-agent-project && cd my-agent-project\n\n# 初始化 npm 项目\nnpm init -y\n\n# 安装为项目依赖\nnpm install s4b7-ai-skills\n\n# 或安装最新预发布版本\nnpm install s4b7-ai-skills@next\n```\n\n资料来源：[package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)\n\n### 方式三：从源码构建\n\n适合需要自定义或参与开发的用户：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/s4b7-ai/s4b7-ai-skills.git\ncd s4b7-ai-skills\n\n# 安装依赖\nnpm install\n\n# 构建项目\nnpm run build\n\n# 链接到全局（开发模式）\nnpm link\n```\n\n资料来源：[scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)\n\n## 安装流程图\n\n以下流程图展示了完整的安装过程：\n\n```mermaid\ngraph TD\n    A[开始安装] --> B{检查 Node.js 版本}\n    B -->|版本过低| C[升级 Node.js]\n    B -->|版本符合| D[检查 npm 版本]\n    C --> D\n    D --> E{安装方式选择}\n    E -->|全局安装| F[npm install -g]\n    E -->|本地安装| G[npm install]\n    E -->|源码构建| H[git clone + npm install]\n    F --> I[验证安装]\n    G --> I\n    H --> I\n    I --> J{验证成功?}\n    J -->|是| K[安装完成]\n    J -->|否| L[排查错误]\n    L --> I\n```\n\n## 环境配置\n\n### 配置文件位置\n\n安装后，配置文件位于用户主目录：\n\n| 平台 | 配置文件路径 |\n|------|--------------|\n| macOS/Linux | `~/.s4b7-ai-skills/config.json` |\n| Windows | `%USERPROFILE%\\.s4b7-ai-skills\\config.json` |\n\n### 基本配置\n\n创建或编辑配置文件：\n\n```json\n{\n  \"model\": \"qwen3:8b\",\n  \"ollamaEndpoint\": \"http://localhost:11434\",\n  \"skillsDirectory\": \"~/.agents/skills/\",\n  \"logLevel\": \"info\",\n  \"autoUpdate\": true\n}\n```\n\n资料来源：[distribution.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/distribution.json)\n\n### 环境变量\n\n支持通过环境变量进行配置：\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `S4B7_SKILLS_DIR` | 技能目录路径 | `~/.agents/skills/` |\n| `S4B7_MODEL` | 默认模型 | `qwen3:8b` |\n| `S4B7_OLLAMA_URL` | Ollama 服务地址 | `http://localhost:11434` |\n| `S4B7_LOG_LEVEL` | 日志级别 | `info` |\n| `S4B7_API_KEY` | API 密钥（可选） | 空 |\n\n## 依赖组件\n\n### Ollama 本地模型服务\n\ns4b7-ai-skills 优先使用本地 Ollama 模型：\n\n```bash\n# 安装 Ollama\ncurl -fsSL https://ollama.com/install.sh | sh\n\n# 拉取默认模型\nollama pull qwen3:8b\n\n# 验证 Ollama 运行状态\ncurl -s http://localhost:11434/api/tags | head -1\n```\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n### ShadowArchive 存储卷（可选）\n\n用于高级功能和技能同步：\n\n```bash\n# 确保 ShadowArchive 卷已挂载\nls /Volumes/☯Duality/\n\n# 或使用本地模式（功能受限）\nS4B7_LOCAL_MODE=true s4b7-ai-skills\n```\n\n资料来源：[skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n\n## 安装验证\n\n### 完整性检查\n\n安装完成后，运行以下命令进行验证：\n\n```bash\n# 检查 CLI 可用性\ns4b7-ai-skills --help\n\n# 检查技能加载\ns4b7-ai-skills skills list\n\n# 测试模型连接\ns4b7-ai-skills doctor\n```\n\n### 常见验证命令\n\n| 命令 | 用途 |\n|------|------|\n| `s4b7-ai-skills --version` | 显示版本号 |\n| `s4b7-ai-skills skills list` | 列出已安装的技能 |\n| `s4b7-ai-skills doctor` | 运行诊断检查 |\n| `s4b7-ai-skills update` | 检查并安装更新 |\n\n资料来源：[scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)\n\n## 技能目录结构\n\n安装后，技能目录结构如下：\n\n```\n~/.agents/skills/\n├── write-a-skill/          # 技能编写指南\n│   └── SKILL.md\n├── shadow-refactor/        # 代码重构工具\n│   └── SKILL.md\n├── qmd-memory/             # 记忆管理系统\n│   └── SKILL.md\n├── codex-latex/            # LaTeX 文档生成\n│   └── SKILL.md\n├── codex-context/          # 上下文管理\n│   └── SKILL.md\n├── ai-sdk-core/            # AI SDK 核心\n│   └── references/\n│       └── v5-breaking-changes.md\n├── multi-model-query/      # 多模型查询\n│   └── SKILL.md\n├── patent-queue/           # 专利队列管理\n│   └── SKILL.md\n├── command-center/         # 命令中心\n│   └── SKILL.md\n├── shadow-continuity/      # 连续性管理\n│   └── SKILL.md\n├── shadow-patent-factory/  # 专利工厂\n│   └── SKILL.md\n├── acp-delegate-auto/      # 自动委托\n│   └── SKILL.md\n├── shadow-engg/            # 工程辅助\n│   └── SKILL.md\n└── shadow-mcp-gadgets/     # MCP 小工具\n    └── SKILL.md\n```\n\n资料来源：[distribution.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/distribution.json)\n\n## 卸载\n\n如需卸载 s4b7-ai-skills：\n\n```bash\n# 全局卸载\nnpm uninstall -g s4b7-ai-skills\n\n# 清除配置（可选）\nrm -rf ~/.s4b7-ai-skills/\n\n# 清除链接\nnpm unlink s4b7-ai-skills\n```\n\n## 故障排除\n\n### 安装失败\n\n| 问题 | 解决方案 |\n|------|----------|\n| `EACCES` 权限错误 | 使用 sudo 或配置 npm 路径 |\n| Node.js 版本不兼容 | 升级到推荐版本 |\n| 网络超时 | 配置国内镜像：`npm config set registry https://registry.npmmirror.com` |\n\n### 运行时问题\n\n| 问题 | 诊断步骤 |\n|------|----------|\n| 技能加载失败 | 检查 `~/.agents/skills/` 目录存在性 |\n| 模型连接失败 | 确认 Ollama 服务运行：`curl http://localhost:11434` |\n| 权限不足 | 检查配置文件写入权限 |\n\n资料来源：[skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)\n\n## 更新升级\n\n### 检查更新\n\n```bash\ns4b7-ai-skills update --check\n```\n\n### 执行更新\n\n```bash\n# npm 全局更新\nnpm update -g s4b7-ai-skills\n\n# 源码更新\ngit pull origin main\nnpm run build\nnpm link\n```\n\n资料来源：[package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)\n\n---\n\n<a id='skill-structure'></a>\n\n## 技能文件结构\n\n### 相关页面\n\n相关主题：[技能分类体系](#skill-categories), [编写技能指南](#write-a-skill)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/shadow-mind/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mind/SKILL.md)\n</details>\n\n# 技能文件结构\n\n## 概述\n\n技能（Skill）是 AI Agent 系统中的可复用能力单元，用于封装特定领域的任务处理逻辑、工作流和最佳实践。技能文件结构定义了这些能力单元的标准化组织方式，确保 Agent 能够在需要时准确识别、加载并执行相应的技能。\n\n技能文件结构的核心目标是：\n\n- **可发现性**：通过标准化的描述格式，使 Agent 能够根据用户请求的关键词和上下文自动匹配最合适的技能\n- **可维护性**：提供清晰的组织规范，便于技能创建、更新和审计\n- **可组合性**：支持技能的模块化拆分和引用，便于构建复杂的任务处理流程\n- **可追溯性**：记录技能的创建来源和使用历史，支持持续优化\n\n## 技能文件基本结构\n\n### 标准目录布局\n\n```\n~/.agents/skills/<skill-name>/\n├── SKILL.md              # 主技能文件（必需）\n├── scripts/              # 工具脚本目录（可选）\n│   ├── helper.js\n│   └── validator.sh\n├── docs/                 # 文档目录（可选）\n│   ├── plans/\n│   │   └── crystallization-log.md\n│   └── reference/\n└── reference.md          # 参考文档（可选）\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:1-15]()\n\n### SKILL.md 文件结构\n\nSKILL.md 是每个技能的入口文件，必须包含以下组成部分：\n\n| 组成部分 | 必需性 | 说明 |\n|---------|-------|------|\n| YAML Frontmatter | 是 | 包含技能名称和描述 |\n| H1 标题 | 是 | 技能名称 |\n| Quick start | 是 | 最小可运行示例 |\n| Workflows | 是 | 复杂任务的步骤清单 |\n| Advanced features | 否 | 指向独立参考文件的链接 |\n\n```markdown\n---\nname: skill-name\ndescription: Brief description of capability. Use when [specific triggers].\n---\n\n# Skill Name\n\n## Quick start\n\n[Minimal working example]\n\n## Workflows\n\n[Step-by-step processes with checklists for complex tasks]\n\n## Advanced features\n\n[Link to separate files: See [REFERENCE.md](REFERENCE.md)]\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:18-32]()\n\n## YAML Frontmatter 规范\n\n### Description 字段规则\n\ndescription 字段是 Agent 在决定加载哪个技能时看到的唯一信息，它会与所有已安装技能的描述一起出现在系统提示中。因此，description 的编写质量直接影响技能的触发准确性。\n\n**格式要求**：\n\n- 最大 1024 字符\n- 使用第三人称书写\n- 第一句：描述技能提供的功能\n- 第二句：以 \"Use when...\" 开头，说明触发条件\n\n**编写示例**：\n\n```\n# 正确示例\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n```\n# 错误示例\nHelps with documents.\n```\n\n错误示例的问题在于：它没有给 Agent 提供区分该技能与其他文档技能的方式。\n\n资料来源：[skills/write-a-skill/SKILL.md:38-55]()\n\n## 技能拆分策略\n\n### 何时拆分文件\n\n当满足以下条件时，应将内容拆分到独立文件：\n\n| 条件 | 说明 |\n|------|------|\n| SKILL.md 超过 100 行 | 主文件变得难以阅读和维护 |\n| 内容具有不同领域 | 如财务和销售数据模式 |\n| 高级功能很少被使用 | 将其隔离减少日常加载开销 |\n\n### 何时添加 Scripts 目录\n\n在以下情况下，应添加 scripts/ 目录并放置工具脚本：\n\n- 操作是确定性的（验证、格式化）\n- 相同的代码会被重复生成\n- 错误需要显式处理\n\n脚本可以节省 token 消耗并提高可靠性，因为它们是经过验证的预编译代码，而非每次动态生成。\n\n资料来源：[skills/write-a-skill/SKILL.md:76-88]()\n\n## 技能分类与放置\n\n### 分类标准\n\n技能按照其适用范围进行分类：\n\n| 分类 | 路径 | 说明 |\n|------|------|------|\n| 通用模式 | `~/.agents/skills/<skill-name>/` | 适用于所有场景的通用技能 |\n| 企业特定模式 | `~/.agents/skills/` 的适当子目录 | 针对特定企业或领域的专用技能 |\n\n资料来源：[skills/crystallize/SKILL.md:112-117]()\n\n### 企业特定技能的放置\n\n企业特定技能应放置在 `~/.agents/skills/` 下的适当子目录中，遵循组织结构层级。例如：\n\n- Astemo 相关技能 → `~/.agents/skills/astemo/`\n- 特定项目相关 → `~/.agents/skills/projects/<project-name>/`\n\n## 技能创建工作流\n\n### 标准工作流图\n\n```mermaid\ngraph TD\n    A[任务完成] --> B{应该复用吗?}\n    B -->|是| C[回顾会话]\n    B -->|否| Z[完成]\n    C --> D[提取模式]\n    D --> E[检查范围]\n    E --> F{存在重叠?}\n    F -->|是| G[更新现有技能]\n    F -->|否| H[创建新技能]\n    G --> I[记录结晶化]\n    H --> I\n    I --> Z\n```\n\n### 工作流详细步骤\n\n#### 1. 回顾（Review）\n\n回答以下问题：\n\n- 任务是什么？\n- 解决了什么问题？\n- 学到了什么？\n- 下次会重复哪些步骤？\n\n#### 2. 模式提取（Pattern Extraction）\n\n识别可复用模式，包括：\n\n| 模式类型 | 说明 |\n|---------|------|\n| **关键步骤** | 产生结果的最简序列 |\n| **启发式规则** | 需要判断的决策点、经验法则 |\n| **常见错误** | 什么出了问题或差点出问题、哪些假设失败 |\n| **决策点** | 在哪里选择了不同方法、什么决定了选择 |\n\n资料来源：[skills/crystallize/SKILL.md:78-96]()\n\n#### 3. 探索模式扩展\n\n当操作者请求\"更多结晶化\"或引用 `--exploratory-mode` 时，不要止步于第一个本地修复。应向外扩展一圈，检查相邻表面是否存在相同的过时假设。\n\n扩展检查范围：\n\n1. 从刚修复的确切内容开始\n2. 检查可能携带相同过时假设的最近相邻表面\n\n资料来源：[skills/crystallize/SKILL.md:98-112]()\n\n## 结晶化模式与模式\n\n### 结晶化与 SP-006 的关系\n\nSP-006（潜在技能观察器）从工具调用序列自动检测模式。结晶化技能通过从推理中有意提取模式来补充 SP-006——这些模式源自对问题的理解，而不仅仅是观察工具使用。两种机制向相同的技能命名空间提供输入。\n\n资料来源：[skills/crystallize/SKILL.md:119-125]()\n\n### 结晶化模式\n\n| 模式 | 输出 | 触发场景 |\n|------|------|---------|\n| `default` | 完整结晶化：回顾→提取→范围→去重→创建/更新 | `crystallize`, `capture this as a skill` |\n| `quick` | 快速捕获到最小技能存根（后续完善） | `quick crystallize`, 任务中模式发现 |\n| `exploratory` | 从修复向外扩展一圈；检查相邻表面 | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | 由操作者挫败感触发的即时结晶化 | `this took too long`, `why aren't you using...` |\n| `correction` | 由操作者更正触发的即时更新 | 操作者更正身份/路径/边界 |\n| `audit` | 检查应该结晶化但没有的内容 | `what patterns did we miss` |\n\n资料来源：[skills/crystallize/SKILL.md:127-142]()\n\n## 技能路由机制\n\n### 关键词检测路由\n\nAgent 可以根据提示中的关键词自动路由到合适的技能：\n\n| 提示包含... | 路由到 |\n|-----------|-------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| `file paths`, `diffs`, `PRs` | codex |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md:45-59]()\n\n### 描述触发机制\n\n技能的 description 字段是 Agent 决策加载哪个技能的主要依据。Agent 读取所有已安装技能的描述，然后根据用户的请求选择最相关的技能。\n\n**触发检测要素**：\n\n1. 功能能力 - 技能提供什么功能\n2. 触发关键词 - 具体何时/为什么使用\n3. 文件类型关联 - 与哪些文件类型相关\n\n## 技能审计与验证\n\n### 技能审查清单\n\n创建或更新技能后，验证以下要点：\n\n- [ ] description 包含触发条件（\"Use when...\"）\n- [ ] SKILL.md 不超过 100 行\n- [ ] 没有时间敏感信息\n- [ ] 术语一致\n- [ ] 包含具体示例\n- [ ] 引用深度仅一层（避免深层嵌套引用）\n\n资料来源：[skills/write-a-skill/SKILL.md:92-100]()\n\n### 技能手术规则\n\n技能审计和研究开发（Skill Surgery R&D）遵循以下规则：\n\n| 规则 | 说明 |\n|------|------|\n| **不删除规则** | 在探索性手术期间不删除技能，先重定向；删除需要操作者明确批准 |\n| **不编辑历史** | 除非仍作为活跃触发问题出现，否则不编辑已归档历史 |\n| **不创建巨型集合技能** | 优先创建一个规范路由器加专注子技能 |\n| **先研究后创造** | 未经验证不结晶过时版本号、价格或 API 形状 |\n| **保留边界** | 整合 Astemo/企业技能时保留特定操作者边界 |\n| **外部化规则** | 所有手术报告进入报告目录，而非嵌入技能文件 |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:25-36]()\n\n### 错误处理\n\n| 故障场景 | 恢复策略 |\n|---------|---------|\n| 脚本执行失败（语法错误） | 运行手动 `find + grep` 清单；在报告中记录脚本失败 |\n| 技能文件 YAML frontmatter 格式错误 | 标记在清单中；不自动修复；建议手动修复 |\n| 检测到循环重定向（A → B → A） | 阻止重定向；报告循环；需要手动解决 |\n| 合并目标有冲突的 gotchas | 保留两组 gotchas；标记供操作者审查 |\n| 技能数量过多（>500） | 优先活跃+非废弃的；抽样检查归档以进行陈旧车道检查 |\n| 技能目录权限被拒绝 | 报告；跳过；仅审计可访问的目录 |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:38-50]()\n\n## 人工制品路由\n\n每个技能生成的人工制品按照标准化路径存储：\n\n| 人工制品类型 | 路径 | 用途 |\n|------------|------|------|\n| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |\n| 更新技能 | 现有技能相同路径 | 扩展能力 |\n| 结晶化日志 | `docs/plans/crystallization-log.md` | 历史记录（可选） |\n| 企业特定技能 | `~/.agents/skills/` 适当子目录 | 领域范围能力 |\n\n资料来源：[skills/crystallize/SKILL.md:145-153]()\n\n## 技能与记忆系统集成\n\n### 上下文保存流程\n\n在每次产生决策或发现的会话后：\n\n1. 将会话锚点写入 `ShadowArchive/80-reports/`\n2. 将关键决策追加到 `.shadow-kernel/esp-context.md` 的相应主题下\n3. 如果发现模式 → 结晶化到技能\n4. 如果是项目特定的 → 写入 `<program>/90_Astemo_Config/session-log.jsonl`\n\n资料来源：[skills/shadow-mind/SKILL.md:55-60]()\n\n### 记忆召回置信度\n\n| 置信度级别 | 含义 | 来源 |\n|-----------|------|------|\n| **Confirmed** | 在持久人工制品中找到（锚点、内核、Dropbox） | 文件匹配 |\n| **Likely** | 在训练对或提炼经验中找到 | 模式匹配 |\n| **Inferred** | 从上下文重构但无明确人工制品 | 推理 |\n| **Unknown** | 未找到证据 | 无匹配 |\n\n必须始终标注召回置信度。永远不要将推断的召回呈现为已确认的。\n\n资料来源：[skills/shadow-mind/SKILL.md:62-70]()\n\n## 完整技能示例\n\n### 示例：crystallize 技能结构\n\n```markdown\n---\nname: crystallize\ndescription: Extract reusable patterns from problem-solving sessions into structured skills. Use when finishing a complex task that might recur, or when explicitly asked to capture a pattern.\n---\n\n# Crystallize\n\nOne-line description. Use when [trigger phrases].\n\n## When to Use\n- [trigger 1]\n- [trigger 2]\n- [trigger 3]\n\n## Workflow\n1. [Step 1]\n2. [Step 2]\n3. [Step 3]\n\n## Key Decisions\n- [Decision point 1]: [default choice + why]\n- [Decision point 2]: [default choice + why]\n\n## Gotchas\n- [Common mistake 1]\n- [Common mistake 2]\n\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n```\n\n资料来源：[skills/crystallize/SKILL.md:20-43]()\n\n## 最佳实践总结\n\n### 技能设计原则\n\n1. **简洁性优先**：保持 SKILL.md 在 100 行以内\n2. **描述精确化**：description 必须包含具体触发条件\n3. **示例具体化**：包含最小可运行示例而非抽象描述\n4. **分层设计**：高级内容通过引用独立文件实现\n5. **模式优先**：将确定性操作提取为脚本\n\n### 避免的反模式\n\n| 反模式 | 问题 | 替代方案 |\n|-------|------|---------|\n| 模糊描述 | Agent 无法区分技能 | 包含具体触发关键词 |\n| 巨型单文件 | 难以维护 | 拆分到 reference.md |\n| 时间敏感信息 | 信息快速过时 | 避免版本号、价格等 |\n| 深层嵌套引用 | 增加加载复杂度 | 限制引用深度为一层 |\n\n### 持续改进流程\n\n技能文件结构是一个持续迭代的系统：\n\n```mermaid\ngraph LR\n    A[创建技能] --> B[使用验证]\n    B --> C{效果如何?}\n    C -->|良好| D[归档最佳实践]\n    C -->|需改进| E[识别问题]\n    E --> F{范围局限?}\n    F -->|是| G[探索性扩展]\n    F -->|否| H[局部优化]\n    G --> A\n    H --> A\n    D --> I[技能库成熟]\n```\n\n通过遵循本文档定义的技能文件结构规范，可以构建一个可维护、可发现、可组合的技能生态系统，使 AI Agent 能够高效地处理各类复杂任务。\n\n---\n\n<a id='skill-categories'></a>\n\n## 技能分类体系\n\n### 相关页面\n\n相关主题：[LangGraph Agent技能](#langgraph-agent), [编写技能指南](#write-a-skill), [模型身份管理](#model-identity)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n- [skills/command-center/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/command-center/SKILL.md)\n</details>\n\n# 技能分类体系\n\n## 概述\n\n技能分类体系（Skill Taxonomy）是 s4b7-ai-skills 项目中的核心架构概念，旨在对 AI Agent 的技能（Skills）进行系统化组织、标准化定义和自动化路由。该体系通过统一的模板结构、关键词触发机制和层级分类，实现了对复杂任务处理的精准匹配与高效执行。\n\n技能分类体系的核心目标包括：\n\n- 为 Agent 提供清晰的技能选择依据\n- 实现任务到技能的自然映射\n- 支持技能的持续迭代与模式提取\n- 提供完善的回退机制确保系统韧性\n\n资料来源：[write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n---\n\n## 技能分类层级\n\n技能体系按照功能域和触发场景分为多个层级，每个层级承担不同的职责：\n\n### 按功能域分类\n\n```mermaid\ngraph TD\n    A[技能分类体系] --> B[核心能力类]\n    A --> C[业务领域类]\n    A --> D[工具集成类]\n    A --> E[推理决策类]\n    \n    B --> B1[write-a-skill]\n    B --> B2[crystallize]\n    B --> B3[multi-model-query]\n    \n    C --> C1[command-center]\n    C --> C2[patent-queue]\n    C --> C3[shadow-patent-factory]\n    \n    D --> D1[shadow-mcp-gadgets]\n    D --> D2[acp-delegate-auto]\n    D --> D3[codex-context]\n    \n    E --> E1[codex-policy-steering]\n    E --> E2[shadow-refactor]\n```\n\n### 技能功能域对照表\n\n| 类别 | 描述 | 代表技能 |\n|------|------|----------|\n| 核心能力类 | 技能开发、模式提取、知识合成的基础能力 | write-a-skill, crystallize, multi-model-query |\n| 业务领域类 | 特定业务场景的垂直能力 | command-center, patent-queue, shadow-engg |\n| 工具集成类 | 与外部系统、API、MCP 服务集成的技能 | shadow-mcp-gadgets, acp-delegate-auto |\n| 推理决策类 | 策略分析、代码推理、上下文理解 | codex-policy-steering, shadow-refactor |\n\n资料来源：[crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n---\n\n## 技能模板规范\n\n所有技能遵循统一的 SKILL.md 模板规范，确保一致性和可维护性：\n\n### 标准化模板结构\n\n```markdown\n---\nname: skill-name\ndescription: 技能描述. Use when [触发关键词].\n---\n\n# 技能名称\n\n## 快速开始\n[最小工作示例]\n\n## 工作流\n[带检查清单的逐步流程]\n\n## 高级特性\n[链接到独立文件]\n```\n\n### 描述字段规范\n\n技能描述是 Agent 选择技能时的唯一依据，编写规范如下：\n\n| 要求 | 说明 |\n|------|------|\n| 字符限制 | 最多 1024 个字符 |\n| 人称 | 使用第三人称 |\n| 格式 | 首句描述功能，次句描述触发条件 |\n| 触发词 | 必须包含 \"Use when\" 引导的触发场景 |\n\n**规范示例**：\n```\nExtract text and tables from PDF files, fill forms, merge documents. \nUse when working with PDF files or when user mentions PDFs, forms, \nor document extraction.\n```\n\n**不规范示例**：\n```\nHelps with documents.\n```\n\n资料来源：[write-a-skill/SKILL.md:32-52](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n---\n\n## 关键词路由机制\n\n### 路由决策流程\n\n技能分类体系通过关键词匹配实现任务的自动路由：\n\n```mermaid\ngraph TD\n    A[用户请求] --> B{关键词检测}\n    B -->|write/implement/refactor/debug| C[codex]\n    B -->|research/summarize/find/compare| D[gemini]\n    B -->|translate/JP/Japanese| E[Codex]\n    B -->|local/private/no cloud| F[ollama]\n    B -->|review/architect/design| G[Codex]\n    B -->|quickly/fast/brief| H[ollama]\n    B -->|file paths/diffs/PRs| I[codex]\n    \n    C --> J[执行目标技能]\n    D --> J\n    E --> J\n    F --> J\n    G --> J\n    H --> J\n    I --> J\n```\n\n### 关键词与技能映射表\n\n| 请求关键词 | 路由目标 |\n|------------|----------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| `quickly`, `fast`, `brief` | ollama |\n| 文件路径, diffs, PRs | codex |\n\n资料来源：[acp-delegate-auto/SKILL.md:1-24](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n---\n\n## 技能触发与工作流\n\n### 触发模式分类\n\n技能根据触发场景分为不同的工作模式：\n\n```mermaid\ngraph LR\n    A[触发源] --> B{技能类型}\n    \n    B --> C[显式触发]\n    B --> D[隐式触发]\n    B --> E[模式检测]\n    \n    C --> C1[关键词匹配]\n    C --> C2[命令调用]\n    \n    D --> D1[上下文推断]\n    D --> D2[记忆关联]\n    \n    E --> E1[SP-006 观察]\n    E --> E2[行为序列分析]\n```\n\n### shadow-refactor 技能工作流\n\nshadow-refactor 是技能体系中的代码推理专家，其工作流程如下：\n\n```mermaid\ngraph TD\n    A[启动 refactor] --> B[执行 SCAN]\n    B --> C{发现问题?}\n    C -->|是| D[创建 TDD 循环]\n    C -->|否| E[equilibrium 模式]\n    \n    D --> F[编写测试]\n    F --> G[执行修复]\n    G --> H{测试通过?}\n    H -->|是| I[verify 验证]\n    H -->|否| J[自修复尝试]\n    J --> K{尝试次数<3?}\n    K -->|是| G\n    K -->|否| L[回滚更改]\n    \n    I --> M[signal 工具信号]\n    M --> N[下一个问题]\n    N --> C\n    \n    E --> O[报告当前状态]\n```\n\n### 代码分析检查项\n\n| 检查类型 | 方法 | 工具/命令 |\n|----------|------|----------|\n| 导入一致性 | `import-sort | sort` 对比 | grep -rn |\n| 重复代码检测 | 3+ 行相同的代码块 | 跨文件比对 |\n| 复杂度热点 | 函数>50行、文件>500行 | AST 分析 |\n| 测试覆盖缺口 | 源文件无对应测试 | 文件匹配扫描 |\n\n资料来源：[shadow-refactor/SKILL.md:1-40](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n\n---\n\n## MCP 工具分类\n\nMCP（Model Context Protocol）工具通过 Gadget 技能进行统一封装：\n\n### Gadget 工具映射表\n\n| 触发模式 | Gadget | 功能 | 使用示例 |\n|----------|--------|------|----------|\n| `memory` | ARC | 记忆存储与检索 | `arc.store`, `arc.search` |\n| `context` | ESP | 统一上下文组装 | `esp.assemble`, `/renew-ctx` |\n| `mesh` | ANT | 网格健康监控 | `ant.mesh` |\n| `browser` | TAP | Chrome 标签页+JS执行 | `tap.tabs`, `tap.execute` |\n| `ambient` | OWL | Bee AI 信息提取 | `owl.brief`, `owl.extract` |\n| `voice` | ORB | macOS TTS | `orb.say`, `orb.voices` |\n| `environment` | DEN | 物理传感器 | `den.environment` |\n| `patent` | Factory | 专利流水线 | `factory.new`, `factory.draft` |\n\n资料来源：[shadow-mcp-gadgets/SKILL.md:1-20](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n\n---\n\n## 模式提取与技能结晶\n\n### 技能结晶工作流\n\n技能可通过两种途径产生：\n\n```mermaid\ngraph TD\n    A[技能来源] --> B{产生方式}\n    \n    B --> C[主动结晶]\n    B --> D[自动检测]\n    \n    C --> C1[理解问题本质]\n    C1 --> C2[识别模式]\n    C2 --> C3[编写 SKILL.md]\n    C3 --> C4[记录元数据]\n    \n    D --> D1[SP-006 观察]\n    D1 --> D2[行为序列分析]\n    D2 --> D3[模式归档]\n```\n\n### 结晶元数据记录\n\n每个技能底部应记录结晶来源：\n\n```markdown\n## Crystallized From\n- Session: [日期/上下文]\n- Original task: [解决的问题]\n- What pattern was extracted: [提取的模式]\n- Adjacent surfaces checked: [检查的相邻表面]\n- Surfaces intentionally left untouched: [故意不触碰的表面]\n```\n\n### 与 SP-006 的关系\n\n- **SP-006**（潜在技能观察器）：自动检测工具调用序列中的模式\n- **crystallize 技能**：通过理解问题本质进行主动模式提取\n\n两者互为补充，共同充实技能命名空间。\n\n资料来源：[crystallize/SKILL.md:1-60](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n---\n\n## 回退机制\n\n技能体系设计了完善的回退链，确保系统在各种异常情况下仍能提供能力：\n\n### 通用回退原则\n\n| 优先级 | 场景 | 回退行为 |\n|--------|------|----------|\n| 1 | 主服务可用 | 执行完整功能 |\n| 2 | 服务不可用 | 使用本地替代方案 |\n| 3 | 依赖缺失 | 降级到简化模式 |\n| 4 | 完全失败 | 生成报告并说明限制 |\n\n### shadow-refactor 回退链\n\n1. **主要路径**：完整 SCAN → TDD 循环 → verify → signal → 下一问题\n2. **Ollama 不可用**：仅使用静态分析（grep、AST、文件指标）\n3. **测试套件未找到**：扫描测试文件；如不存在，先生成最小测试结构\n4. **自修复耗尽 3 次尝试**：回滚该问题的所有更改；记录为不可恢复；继续下一问题\n5. **后台代理不可用**：以内联方式运行（阻塞用户）；报告后台模式不可用\n6. **最后手段**：报告问题而不修复；生成仅扫描输出\n\n### shadow-mcp-gadgets 回退链\n\n1. **主要**：通过 MCP 协议连接到 shadow-mcp 联邦服务器\n2. **MCP 服务器未运行**：通过 `bun run` 启动服务\n3. **后续回退**：根据各 Gadget 类型确定具体降级策略\n\n资料来源：[shadow-refactor/SKILL.md:50-60](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md), [shadow-mcp-gadgets/SKILL.md:25-35](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n\n---\n\n## 制品路由\n\n技能执行后的输出通过标准化的路径进行路由：\n\n### 制品路径规范\n\n| 制品类型 | 路径 | 用途 |\n|----------|------|------|\n| 工具信号 | `tools/integrate/tool-signals.jsonl` | 每次修复的 JSONL 结果 |\n| 重构报告 | `ShadowArchive/80-reports/refactor-<target>-YYYY-MM-DD.md` | 会话摘要 |\n| 记忆存储 | ARC 记忆存储（gadget 管理） | 持久化 Agent 记忆 |\n| 上下文状态 | ESP 程序集输出（会话范围） | 当前会话的统一上下文 |\n| 专利草案 | `docs/patents/` | 归档轨道草案 |\n| 技能开发 | `~/.agents/skills/<skill-name>/` | 通用模式 |\n| 企业技能 | `~/.agents/skills/<category>/` | 企业特定模式 |\n\n资料来源：[shadow-refactor/SKILL.md:45-50](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md), [crystallize/SKILL.md:70-75](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n---\n\n## 技能开发检查清单\n\n创建新技能时应遵循以下检查流程：\n\n### 编写检查项\n\n| 检查项 | 状态 |\n|--------|------|\n| 描述包含触发词（\"Use when...\"） | ☐ |\n| SKILL.md 控制在 100 行以内 | ☐ |\n| 无时间敏感信息 | ☐ |\n| 术语一致性 | ☐ |\n| 包含具体示例 | ☐ |\n| 引用层级深度不超过 1 层 | ☐ |\n\n### 文件拆分原则\n\n在以下情况下应拆分为独立文件：\n\n- SKILL.md 超过 100 行\n- 内容具有不同领域（如财务 vs 销售模式）\n- 高级特性很少需要\n\n### 脚本添加原则\n\n在以下情况下应添加脚本：\n\n- 操作是确定性的（验证、格式化）\n- 相同代码会被重复生成\n- 需要明确的错误处理\n\n资料来源：[write-a-skill/SKILL.md:90-120](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n---\n\n## 总结\n\n技能分类体系是 s4b7-ai-skills 项目的核心组织框架，通过以下机制实现高效的任务处理：\n\n1. **统一模板**：所有技能遵循标准化 SKILL.md 格式\n2. **关键词路由**：基于触发词的任务自动分发\n3. **Gadget 封装**：MCP 工具通过统一接口暴露\n4. **模式结晶**：支持主动和自动两种技能生成方式\n5. **回退机制**：确保系统在各种异常情况下的韧性\n6. **制品路由**：标准化的输出路径管理\n\n该体系使 Agent 能够根据用户请求的语义自动选择最合适的技能，同时保持良好的可扩展性和维护性。\n\n---\n\n<a id='langgraph-agent'></a>\n\n## LangGraph Agent技能\n\n### 相关页面\n\n相关主题：[AI SDK Core技能](#ai-sdk-core), [Agent-Cryst技能](#agent-cryst)\n\nError with Openai API: Error code: 429 - {'type': 'error', 'error': {'type': 'rate_limit_error', 'message': 'Token Plan 主要面向个人开发者的交互式使用场景。当前请求量较高，请稍后重试；如需支持更高并发或自动化任务，建议升级至更高级别套餐，或使用按量付费 API。 (2062)', 'http_code': '429'}, 'request_id': '0654e2052901c7e32982c8a82663eaab'}\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n<a id='ai-sdk-core'></a>\n\n## AI SDK Core技能\n\n### 相关页面\n\n相关主题：[LangGraph Agent技能](#langgraph-agent)\n\nError with Openai API: Error code: 429 - {'type': 'error', 'error': {'type': 'rate_limit_error', 'message': 'Token Plan 主要面向个人开发者的交互式使用场景。当前请求量较高，请稍后重试；如需支持更高并发或自动化任务，建议升级至更高级别套餐，或使用按量付费 API。 (2062)', 'http_code': '429'}, 'request_id': '0654e20df587a09b65b212207d578114'}\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n<a id='agent-cryst'></a>\n\n## Agent-Cryst技能\n\n### 相关页面\n\n相关主题：[Crystallize技能](#crystallize)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n</details>\n\n# Agent-Cryst技能\n\n## 概述\n\nAgent-Cryst（代理结晶）是一种将智能体工作过程中的知识、工作流程和决策模式进行结构化提取、沉淀并复用的技能体系。其核心理念是将隐性的解决问题的方法转化为显性的、可存储的、可复用的技能资产。\n\n这一技能与 SP-006（潜在技能观察器）形成互补关系：SP-006 自动检测工具调用序列中的模式，而 Agent-Cryst 则专注于从推理过程中主动提取有意义的模式。这两种机制共同为智能体提供持续学习和能力扩展的能力。\n\n## 核心概念\n\n### 什么是\"结晶\"（Crystallization）\n\n\"结晶\"是将会话中产生的有价值的工作模式提取为标准化技能的过程。这个过程不仅捕获工具使用的序列，更关注捕获理解问题和解决问题的思维过程。\n\n资料来源：[skills/crystallize/SKILL.md:1-30]()\n\n### 与其他模式的关系\n\nAgent-Cryst 与智能体生态中的多个组件相互协作：\n\n| 组件 | 关系 | 作用 |\n|------|------|------|\n| SP-006 | 互补 | 自动观察工具调用序列，检测潜在模式 |\n| 记忆系统 | 下游 | 结晶后的技能存储到持久化记忆 |\n| 技能注册表 | 目标 | 结晶产物成为可索引的技能条目 |\n| MCP工具 | 扩展 | 通过MCP协议实现技能的分布式调用 |\n\n资料来源：[skills/crystallize/SKILL.md:70-85]()\n\n## 结晶工作流\n\n### 标准流程（default模式）\n\n```mermaid\ngraph TD\n    A[任务完成] --> B{应该复用吗?}\n    B -->|是| C[回顾会话]\n    B -->|否| Z[完成]\n    C --> D[提取模式]\n    D --> E{检查范围}\n    E --> F[搜索现有技能]\n    F --> G{发现重叠?}\n    G -->|是| H[更新现有技能]\n    G -->|否| I[创建新技能]\n    H --> J[记录结晶日志]\n    I --> J\n```\n\n标准流程包含以下步骤：\n\n1. **回顾（Review）**：明确任务、解决的问题、学到的内容，以及需要重复的步骤\n2. **模式提取（Pattern Extraction）**：识别可复用的模式，包括关键步骤、启发式规则、陷阱和决策点\n3. **范围检查（Scope Check）**：确定结晶产物的适用边界\n4. **去重检查（Deduplication）**：搜索现有技能，避免重复创建\n5. **创建/更新技能**：生成新的技能文件或更新现有技能\n6. **记录结晶日志**：保存元数据到技能文件的 `## Crystallized From` 部分\n\n资料来源：[skills/crystallize/SKILL.md:40-70]()\n\n### 快速模式（quick模式）\n\n当需要在任务中途快速捕获发现的模式时使用此模式，输出为最小化的技能存根，后续再进行完整优化：\n\n| 模式 | 输出 | 触发词 |\n|------|------|--------|\n| `default` | 完整结晶流程 | `crystallize`, `capture this as a skill` |\n| `quick` | 最小技能存根 | `quick crystallize`, 任务中模式发现 |\n| `exploratory` | 向外扩展一圈，检查相邻表面 | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | 立即结晶 | `this took too long`, `why aren't you...` |\n| `correction` | 立即更新 | 操作员修正时 |\n| `audit` | 检查遗漏的模式 | `what patterns did we miss` |\n\n资料来源：[skills/crystallize/SKILL.md:50-65]()\n\n## 模式提取方法论\n\n### 关键步骤提取\n\n最小化产生结果所需的动作序列。通过分析会话中的决策点，识别哪些步骤是必须的，哪些是可选的。\n\n### 启发式规则识别\n\n在判断过程中产生的经验规则。例如：\n- \"当遇到 X 类型错误时，首先检查 Y 配置\"\n- \"对于 A 类任务，使用 B 工具比 C 工具更高效\"\n\n### 陷阱记录\n\n记录容易出错的地方和失败假设：\n- 什么操作导致问题或差点导致问题\n- 哪些假设在实际执行中失败了\n- 环境或上下文的特殊依赖条件\n\n### 决策点文档化\n\n记录选择过程：\n- 在哪个环节做出了选择？\n- 选择的原因是什么？\n- 替代方案有哪些，为什么没有选择？\n\n资料来源：[skills/crystallize/SKILL.md:30-40]()\n\n## 探索模式扩展\n\n当使用探索模式时，结晶过程会向外扩展一圈，检查可能携带相同陈旧假设的相邻表面。\n\n扩展检查范围：\n1. 从精确修复的问题开始\n2. 检查最近的相邻表面\n3. 识别可能携带相同问题的其他区域\n4. 捕获更广泛的复用规则\n\n```mermaid\ngraph TD\n    A[精确修复] --> B[检查相邻表面]\n    B --> C{发现相同问题?}\n    C -->|是| D[扩展修复范围]\n    C -->|否| E[记录该区域安全]\n    D --> F[捕获广泛规则]\n    E --> G[继续检查下一个表面]\n    F --> G\n```\n\n资料来源：[skills/crystallize/SKILL.md:45-50]()\n\n## 技能结构规范\n\n### 技能文件模板\n\n```markdown\n# Skill Name\n\nOne-line description. Use when [trigger phrases].\n\n## When to Use\n- [trigger 1]\n- [trigger 2]\n- [trigger 3]\n\n## Workflow\n1. [Step 1]\n2. [Step 2]\n3. [Step 3]\n\n## Key Decisions\n- [Decision point 1]: [default choice + why]\n- [Decision point 2]: [default choice + why]\n\n## Gotchas\n- [Common mistake 1]\n- [Common mistake 2]\n\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:1-20]()\n\n### 描述规范\n\n技能描述是智能体决定加载哪个技能时看到的唯一信息，必须清晰准确：\n\n| 要求 | 说明 |\n|------|------|\n| 最大长度 | 1024字符 |\n| 视角 | 第三人称 |\n| 第一句 | 功能描述 |\n| 第二句 | 触发条件（Use when...） |\n\n**良好示例：**\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n**不良示例：**\n```\nHelps with documents.\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:30-50]()\n\n### 文件拆分原则\n\n| 条件 | 行动 |\n|------|------|\n| SKILL.md 超过 100 行 | 拆分为多个文件 |\n| 内容跨越不同领域 | 拆分为独立文件 |\n| 高级功能很少使用 | 分离到 REFERENCE.md |\n\n资料来源：[skills/write-a-skill/SKILL.md:60-70]()\n\n### 脚本添加原则\n\n以下情况应添加工具脚本：\n- 操作是确定性的（验证、格式化）\n- 相同代码会被重复生成\n- 错误需要显式处理\n\n脚本可以节省 token 消耗并提高可靠性。\n\n资料来源：[skills/write-a-skill/SKILL.md:55-60]()\n\n## 产物路由\n\n### 结晶产物存储\n\n| 产物类型 | 路径 | 用途 |\n|----------|------|------|\n| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |\n| 更新技能 | 现有技能相同路径 | 扩展能力 |\n| 结晶日志 | `docs/plans/crystallization-log.md` | 历史记录（可选） |\n\n### 企业级技能\n\n对于特定企业场景的模式，应放在适当的企业子目录下：\n\n```\n~/.agents/skills/<enterprise>/<skill-name>/\n```\n\n资料来源：[skills/crystallize/SKILL.md:60-65]()\n\n## 记忆系统集成\n\n### 记忆提取流程\n\nAgent-Cryst 与 qmd-memory 系统集成，支持从会话内容中提取知识：\n\n```bash\n# 从文件提取\nqmd-memory extract notes.md --source-id \"file:notes.md\"\n\n# 从标准输入提取（如 Bee 对话）\nbee conversations get <id> --json | jq -r '.summary' | qmd-memory extract - --source-id \"bee:conv:<id>\"\n\n# 干运行（预览将要提取的内容）\nqmd-memory extract notes.md --dry-run\n```\n\n### 记忆类型\n\n| 类型 | 用途 | 示例 |\n|------|------|------|\n| `fact` | 事实性知识 | \"TypeScript 是主要语言\" |\n| `commitment` | 承诺事项 | \"周五前完成设置\" |\n| `decision` | 决策记录 | \"决定使用本地优先方案\" |\n| `preference` | 偏好设置 | \"喜欢使用 vim\" |\n| `context` | 上下文信息 | \"当前聚焦 bee 设置\" |\n\n资料来源：[skills/qmd-memory/SKILL.md:1-30]()\n\n## MCP工具集成\n\n### Shadow MCP架构\n\nAgent-Cryst 通过 MCP 协议与各种工具集成：\n\n```mermaid\ngraph TD\n    A[Agent] --> B[Shadow MCP Federation]\n    B --> C[ARC 记忆存储]\n    B --> D[ESP 上下文组装]\n    B --> E[ANT 网格健康]\n    B --> F[TAP 浏览器控制]\n    B --> G[OWL 环境信息]\n    B --> H[ORB 语音输出]\n    B --> I[Factory 专利流水线]\n```\n\n| 触发词 | 工具 | 功能 |\n|--------|------|------|\n| `arc.store`, `arc.search` | ARC | 记忆存储和检索 |\n| `esp.assemble`, `/renew-ctx` | ESP | 统一上下文组装 |\n| `ant.mesh` | ANT | 网格健康状态 |\n| `tap.tabs`, `tap.execute` | TAP | Chrome 标签页控制 |\n| `owl.brief`, `owl.extract` | OWL | 环境信息提取 |\n| `orb.say`, `orb.voices` | ORB | macOS TTS 语音输出 |\n\n资料来源：[skills/shadow-mcp-gadgets/SKILL.md:1-30]()\n\n## 重构与模式检测\n\n### 模式提取分析\n\nAgent-Cryst 可以与 shadow-refactor 技能协作，通过多种方式进行模式检测：\n\n| 方法 | 说明 | 适用场景 |\n|------|------|----------|\n| 重复代码检测 | 查找 3 行以上相同的代码块 | 发现复制粘贴模式 |\n| 复杂度热点 | 函数超过 50 行、文件超过 500 行 | 识别需要重构的区域 |\n| AST 分析 | 抽象语法树分析 | 深度代码结构检查 |\n| 本地 LLM 辅助 | 使用 Ollama 进行模式分析 | 当 Ollama 可用时 |\n\n### 本地 LLM 模式分析\n\n当 Ollama 服务可用时，可以使用 qwen3:8b 等模型进行智能模式检测：\n\n```python\nimport httpx\nresp = httpx.post(\"http://localhost:11434/api/generate\", json={\n    \"model\": \"qwen3:8b\",\n    \"prompt\": f\"Analyze this code for refactoring opportunities. Be specific:\\n\\n{code}\",\n    \"stream\": False,\n})\nsuggestions = resp.json()[\"response\"]\n```\n\n当 Ollama 不可用时，使用静态分析方法（grep、AST、文件指标）。\n\n资料来源：[skills/shadow-refactor/SKILL.md:20-45]()\n\n## 回退链\n\nAgent-Cryst 技能实现了完整的回退链，确保在各种环境条件下都能正常工作：\n\n| 优先级 | 条件 | 行为 |\n|--------|------|------|\n| 1 | MCP 服务器可用 | 使用 Shadow MCP 联合服务器 |\n| 2 | MCP 服务器未运行 | 通过 `bun run` 启动服务 |\n| 3 | Ollama 可用 | 启用智能模式分析 |\n| 4 | Ollama 不可用 | 纯静态分析 |\n| 5 | 记忆系统可用 | 存储到 ARC 记忆 |\n| 6 | 记忆系统不可用 | 降级到文件存储 |\n\n资料来源：[skills/shadow-mcp-gadgets/SKILL.md:45-55]()\n\n## 审查清单\n\n创建或更新技能后，应验证以下项目：\n\n| 检查项 | 说明 |\n|--------|------|\n| 描述包含触发词 | 必须包含 \"Use when...\" 部分 |\n| SKILL.md 行数 | 应在 100 行以内 |\n| 无时间敏感信息 | 避免使用具体日期或临时状态 |\n| 术语一致性 | 与其他技能保持统一术语 |\n| 包含具体示例 | 提供可运行的示例代码 |\n| 引用深度一级 | 相关文件使用相对路径引用 |\n\n资料来源：[skills/write-a-skill/SKILL.md:75-85]()\n\n## 最佳实践\n\n### 何时使用结晶\n\n- 工作流程是确定性的且会重复\n- 相同的代码会被反复生成\n- 错误需要显式处理和预防\n- 存在需要记录的重要决策点\n\n### 何时避免结晶\n\n- 工作流是一次性的\n- 存在太多例外情况无法标准化\n- 结晶成本超过复用收益\n\n### 结晶质量标准\n\n1. **可执行性**：技能描述的步骤应能直接执行\n2. **边界清晰**：明确技能的适用范围和限制\n3. **自包含**：技能应包含所有必要的上下文\n4. **可发现**：描述和触发词应便于智能体检索\n\n## 总结\n\nAgent-Cryst 技能是智能体能力持续演进的核心机制。通过系统化的知识结晶过程，智能体能够：\n\n- 将会话中获得的经验转化为可复用资产\n- 建立与 SP-006 的互补关系，实现主动和被动模式检测\n- 通过 MCP 工具集成实现分布式能力扩展\n- 与记忆系统深度集成，支持知识的持久化和检索\n\n这一技能遵循\"边做边学\"的原则，确保每次有价值的交互都能成为未来工作的基础。\n\n---\n\n<a id='write-a-skill'></a>\n\n## 编写技能指南\n\n### 相关页面\n\n相关主题：[Crystallize技能](#crystallize)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n</details>\n\n# 编写技能指南\n\n本指南介绍如何在 s4b7-ai-skills 项目中创建、编写和维护技能（Skill）。技能是模块化的能力单元， agents 可以根据任务需求动态加载和使用。\n\n## 概述\n\n技能（Skill）是一种结构化的知识封装形式，用于将重复性任务的执行模式固化为可复用的指南。每个技能通常包含以下组成部分：\n\n| 组成部分 | 说明 |\n|---------|------|\n| `SKILL.md` | 核心技能定义文件，包含描述、工作流程、高级特性引用 |\n| `scripts/` | 工具脚本目录（可选），用于确定性操作、格式化、错误处理 |\n| `docs/` | 文档目录（可选），包含参考文档、计划、变更日志 |\n| `REFERENCE.md` | 高级特性参考文档（可选） |\n\n技能的设计原则：\n\n- **Token 节约**：脚本和工具脚本可以节省 token 消耗，提高可靠性\n- **可复用性**：通过结构化的工作流程和清单，确保任务执行的一致性\n- **分层组织**：基本信息在 SKILL.md 中，高级特性拆分到独立文件\n\n资料来源：[skills/write-a-skill/SKILL.md:1-20]()\n\n## SKILL.md 模板结构\n\nSKILL.md 是技能的入口文件，其标准模板结构如下：\n\n```markdown\n---\nname: skill-name\ndescription: Brief description of capability. Use when [specific triggers].\n---\n\n# Skill Name\n\n## Quick start\n\n[Minimal working example]\n\n## Workflows\n\n[Step-by-step processes with checklists for complex tasks]\n\n## Advanced features\n\n[Link to separate files: See [REFERENCE.md](REFERENCE.md)]\n```\n\n### Frontmatter 配置\n\nFrontmatter 部分定义了技能的基本元数据：\n\n```yaml\n---\nname: skill-name          # 技能唯一标识符\ndescription: 简短描述    # 用于 agent 识别的触发条件说明\n---\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `name` | string | 是 | 技能的唯一标识符，应使用 kebab-case 命名 |\n| `description` | string | 是 | 简短描述，用于 agent 在系统提示中识别何时加载此技能 |\n\n资料来源：[skills/write-a-skill/SKILL.md:22-40]()\n\n## Description 编写规范\n\nDescription 是 agent **唯一能看到的信息**，用于在系统提示中决定是否加载该技能。\n\n### 格式要求\n\n| 要求 | 说明 |\n|------|------|\n| 最大字符数 | 1024 characters |\n| 人称 | 第三人称 |\n| 句子结构 | 第一句描述功能，第二句描述触发条件（\"Use when...\"） |\n\n### 编写示例\n\n**正确示例**：\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n**错误示例**：\n```\nHelps with documents.\n```\n\n错误示例的问题在于：没有给 agent 提供足够的区分信息，无法将此技能与其他文档相关技能区分开来。\n\n### 触发条件设计\n\nDescription 应明确列出触发关键词和场景：\n\n| 触发类型 | 示例 |\n|---------|------|\n| 文件类型 | `PDF`, `Markdown`, `JSON`, `YAML` |\n| 操作类型 | `write`, `refactor`, `debug`, `translate` |\n| 领域关键词 | `patent`, `engineering`, `automotive` |\n| 上下文 | `local`, `private`, `no cloud` |\n\n资料来源：[skills/write-a-skill/SKILL.md:42-65]()\n\n## 目录结构规范\n\n### 基础结构\n\n```\nskill-name/\n├── SKILL.md          # 必需：技能入口文件\n├── scripts/          # 可选：工具脚本目录\n│   └── helper.js\n├── docs/             # 可选：文档目录\n│   ├── plans/        # 计划文档\n│   └── REFERENCE.md  # 参考文档\n```\n\n### Crystallize 模式下的结构\n\n当使用 crystallize 模式创建技能时，可能包含以下附加结构：\n\n```\nskills/\n└── <name>/\n    ├── SKILL.md      # 新建或更新的技能\n    └── docs/plans/crystallization-log.md  # 可选：结晶化历史记录\n```\n\n资料来源：[skills/crystallize/SKILL.md:50-65]()\n\n## 脚本使用规范\n\n### 何时添加脚本\n\n添加工具脚本的判断标准：\n\n| 判断标准 | 说明 |\n|---------|------|\n| 操作确定性 | 操作是确定性的（验证、格式化）而非探索性的 |\n| 代码重复 | 相同代码会被反复生成 |\n| 错误处理 | 需要显式的错误处理逻辑 |\n\n使用脚本的优势：\n- 节省 token 消耗\n- 提高执行可靠性\n- 避免每次生成可能产生的错误\n\n### 脚本类型\n\n| 脚本类型 | 示例用途 |\n|---------|---------|\n| 验证脚本 | 语法检查、schema 验证 |\n| 格式化脚本 | 代码格式化、文件规范化 |\n| 生成脚本 | 模板填充、代码生成 |\n| 集成脚本 | API 调用、数据转换 |\n\n资料来源：[skills/write-a-skill/SKILL.md:67-78]()\n\n## 文件拆分规范\n\n### 拆分时机\n\n| 条件 | 触发操作 |\n|------|---------|\n| SKILL.md 超过 100 行 | 考虑拆分到 REFERENCE.md |\n| 内容领域差异明显 | 按领域拆分（如 finance vs sales schemas） |\n| 高级特性使用频率低 | 拆分到独立文件，按需加载 |\n\n### 拆分策略\n\n- **一级引用**：SKILL.md 仅引用一层深度的文件\n- **避免过度拆分**：保持技能的完整性，避免碎片化\n- **保持可导航性**：拆分后的文件结构应保持清晰的导航路径\n\n资料来源：[skills/write-a-skill/SKILL.md:80-95]()\n\n## 技能工作流程\n\n### Crystallize 模式工作流程\n\nCrystallize 是一种从会话经验中提炼技能模式的方法，其标准工作流程如下：\n\n```mermaid\ngraph TD\n    A[任务完成] --> B{是否需要重复?}\n    B -->|是| C[回顾会话]\n    B -->|否| Z[完成]\n    C --> D[提取模式]\n    D --> E[检查范围]\n    E --> F[搜索现有技能]\n    F --> G{发现重叠?}\n    G -->|是| H[更新现有技能]\n    G -->|否| I[创建新技能]\n    H --> J[记录结晶化]\n    I --> J\n```\n\n### Crystallize 模式类型\n\n| 模式 | 输出 | 适用场景 |\n|------|------|---------|\n| `default` | 完整结晶：审查→提取→范围检查→去重→创建/更新 | `crystallize`, `capture this as a skill` |\n| `quick` | 快速捕获到最小技能存根 | `quick crystallize`, 任务中模式发现 |\n| `exploratory` | 向外扩展一圈，检查相邻表面是否具有相同模式 | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | 立即结晶，由操作员挫败感触发 | `this took too long`, `why aren't you using...` |\n| `correction` | 立即更新，基于操作员纠正 | 操作员纠正身份/路径/边界 |\n| `audit` | 检查应该结晶但没有结晶的内容 | `what patterns did we miss` |\n\n### 结晶化步骤详解\n\n#### 1. 回顾（Review）\n\n回答以下问题：\n- 任务是什么？\n- 解决了什么问题？\n- 学到了什么？\n- 下次会重复哪些步骤？\n\n#### 2. 模式提取（Pattern Extraction）\n\n识别可复用模式：\n\n| 模式要素 | 说明 |\n|---------|------|\n| **关键步骤** | 产生结果的最简序列是什么？ |\n| **启发式规则** | 需要哪些判断？出现了哪些经验法则？ |\n| **陷阱** | 什么出错了或差点出错？哪些假设失败了？ |\n| **决策点** | 在哪里选择不同方法？什么因素决定了选择？ |\n\n#### 3. Exploratory-Mode 扩展\n\n当操作员要求 \"more crystallization\" 或使用 `--exploratory-mode` 时：\n\n1. 从修复的确切位置开始\n2. 检查最近的相邻表面是否有相同的过时假设\n3. 捕获更广泛的复用规则\n\n资料来源：[skills/crystallize/SKILL.md:15-50]()\n\n## 技能审核清单\n\n创建或更新技能后，使用以下清单进行自检：\n\n| 检查项 | 说明 |\n|-------|------|\n| Description 包含触发条件 | 包含 \"Use when...\" 格式的触发条件描述 |\n| SKILL.md 行数控制 | 保持在 100 行以内 |\n| 无时间敏感信息 | 避免硬编码日期、价格等会过时的信息 |\n| 术语一致性 | 全文使用统一的术语命名 |\n| 包含具体示例 | 提供可直接使用的代码示例 |\n| 引用层级控制 | 仅引用一层深度的文件 |\n\n资料来源：[skills/write-a-skill/SKILL.md:97-110]()\n\n## 技能路由与上下文集成\n\n### 与 SP-006 的关系\n\nSP-006（潜在技能观察器）从工具调用序列自动检测模式。Crystallize 技能通过**有意的结晶**补充 SP-006——这些模式从问题理解中产生，而非仅从工具使用观察中产生。两种机制共享相同的技能命名空间。\n\n### 上下文引用\n\n技能应引用相关的上下文文件：\n\n```markdown\n## 上下文引用\n\n- 技能花园（skills garden）\n- Mesh 上下文技能\n- 全局架构规则（来自 `GLOBAL_AGENT_RULES.md`）\n```\n\n### 关键路径参考\n\n| 路径类型 | 用途 |\n|---------|------|\n| 第一方技能 | `~/.agents/skills/<skill-name>/SKILL.md` |\n| 供应商技能 | `~/.agents/skills/` |\n| 企业特定技能 | 适当的 `~/.agents/skills/` 子目录 |\n| 项目技能 | 项目级别 `skills/` 目录 |\n\n资料来源：[skills/codex-context/SKILL.md:1-25]()\n\n## 技能手术与维护\n\n### Skill Surgery 工具\n\n`s4b7-ai-skills` 提供了技能维护相关的脚本：\n\n| 脚本 | 功能 |\n|------|------|\n| `audit-skills.mjs` | 审计技能完整性 |\n| `cluster-skill-triggers.mjs` | 聚类技能触发条件 |\n| `redirect-deprecated-skill.mjs` | 重定向已弃用技能 |\n\n### 维护操作类型\n\n| 操作 | 说明 |\n|------|------|\n| 创建（Create） | 新建技能定义 |\n| 更新（Update） | 扩展或修改现有技能 |\n| 合并（Merge） | 合并重叠技能 |\n| 重定向（Redirect） | 将旧技能重定向到新位置 |\n| 审核（Audit） | 检查技能健康状态 |\n\n### 维护原则\n\n- **禁止在探索性手术期间删除技能**，先重定向，删除需操作员明确批准\n- **不编辑归档历史**，除非仍作为活动触发问题浮现\n- **不创建大型综合技能**，优先使用一个规范路由器加专注子技能\n- **研究后再发明**，不结晶过时版本号、价格或 API 形状\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:1-30]()\n\n## 产物路由规范\n\n技能执行后的产物应路由到指定路径：\n\n| 产物类型 | 路径 | 用途 |\n|---------|------|------|\n| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |\n| 更新技能 | 现有技能路径 | 扩展能力 |\n| 结晶日志 | `docs/plans/crystallization-log.md` | 所有结晶化历史记录（可选） |\n| 扫描报告 | `ShadowArchive/80-reports/` | 跨域探索结果 |\n| 重构报告 | `ShadowArchive/80-reports/refactor-<target>-YYYY-MM-DD.md` | 重构会话摘要 |\n\n### 产物格式\n\n| 格式 | 使用场景 |\n|------|---------|\n| JSONL | 机器可读的日志、信号数据 |\n| Markdown | 人类可读的文档、报告 |\n| YAML | 配置文件、元数据 |\n\n资料来源：[skills/crystallize/SKILL.md:65-80]()\n\n## 常见陷阱与注意事项\n\n### SKILL.md 编写陷阱\n\n| 陷阱 | 问题 | 解决方案 |\n|------|------|---------|\n| Description 过于笼统 | Agent 无法区分技能 | 使用具体触发关键词 |\n| 包含时间敏感信息 | 信息会过时失效 | 避免硬编码日期/价格 |\n| 过度拆分 | 碎片化降低可导航性 | 保持合理引用层级 |\n| 缺少示例 | 用户无法快速上手 | 提供具体代码示例 |\n\n### Crystallize 模式陷阱\n\n| 陷阱 | 问题 | 解决方案 |\n|------|------|---------|\n| 过早停止 | 未发现相邻模式 | 使用 exploratory-mode |\n| 假设验证缺失 | 结晶了错误模式 | 在结晶前验证假设 |\n| 范围过大 | 创建了巨型技能 | 检查范围，控制技能边界 |\n\n### 维护操作陷阱\n\n| 陷阱 | 问题 | 解决方案 |\n|------|------|---------|\n| 循环重定向检测失败 | A→B→A 循环 | 阻止循环，要求手动解决 |\n| 合并冲突未处理 | 合并目标有冲突的 gotchas | 保留双方 gotchas，标记供操作员审查 |\n| 权限问题未报告 | 无法访问技能目录 | 报告并跳过，仅审计可访问目录 |\n\n资料来源：[skills/write-a-skill/SKILL.md:97-110](); [skills/skill-surgery-rd/SKILL.md:25-40]()\n\n## 最佳实践总结\n\n### 设计原则\n\n1. **最小化描述**：Description 应简洁明了，最大 1024 字符\n2. **明确的触发条件**：让 agent 能准确判断何时加载技能\n3. **层级组织**：基本信息在主文件，高级特性在引用文件\n4. **可验证性**：提供清单和验收标准\n\n### 执行原则\n\n1. **确定性优先**：使用脚本处理确定性操作\n2. **Token 效率**：脚本比每次生成代码更高效可靠\n3. **可追踪性**：记录所有变更的来源和理由\n\n### 维护原则\n\n1. **不破坏性修改**：优先重定向而非删除\n2. **持续审计**：定期检查技能健康状态\n3. **模式复用**：跨技能识别和提取复用模式\n\n---\n\n本指南基于 s4b7-ai-skills 项目的实际源码编写，涵盖了从技能创建到维护的完整生命周期。遵循本指南可以确保技能的可用性、可维护性和可扩展性。\n\n---\n\n<a id='crystallize'></a>\n\n## Crystallize技能\n\n### 相关页面\n\n相关主题：[Agent-Cryst技能](#agent-cryst), [编写技能指南](#write-a-skill)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n</details>\n\n# Crystallize技能\n\n## 概述\n\nCrystallize（结晶化）技能是一种从AI代理会话中提取和固化可复用模式的方法论。其核心目标是将隐性的问题解决方案转化为显性的、结构化的技能文档，使AI代理能够在未来的类似场景中快速调用经过验证的最佳实践。\n\n该技能与SP-006（潜在技能观察器）形成互补关系：SP-006通过自动观察工具调用序列来检测模式，而Crystallize则通过有意识的推理来提取模式——这些模式源于对问题的理解，而不仅仅是工具使用的观察。两者共同服务于同一个技能命名空间。\n\n资料来源：[skills/crystallize/SKILL.md:1-20]()\n\n## 技能定位\n\nCrystallize技能专注于以下类型的模式提取：\n\n- 需要人类判断力的复杂决策流程\n- 跨会话累积的专业知识\n- 难以从工具调用序列自动推断的启发式规则\n- 需要解释\"为什么这样做\"的推理链\n\n以下类型的模式不适合通过Crystallize提取：\n\n- 代码库本身显而易见的操作\n- 纯确定性的自动化任务\n- 单一会话内完成且不再复发的临时需求\n\n资料来源：[skills/crystallize/SKILL.md:20-30]()\n\n## 工作流程\n\nCrystallize技能采用结构化的工作流程来确保提取的模式具有高质量和可复用性。\n\n```mermaid\ngraph TD\n    A[任务完成] --> B{是否应该复用?}\n    B -->|是| C[回顾会话]\n    B -->|否| Z[完成]\n    C --> D[提取模式]\n    D --> E[检查范围]\n    E --> F{发现重叠?}\n    F -->|是| G[更新现有技能]\n    F -->|否| H[创建新技能]\n    G --> I[记录结晶化日志]\n    H --> I\n```\n\n### 步骤一：回顾（Review）\n\n在回顾阶段，需要回答以下关键问题：\n\n- **任务是什么？** 明确本次会话要解决的原始问题\n- **解决了什么问题？** 描述最终达成的结果\n- **学到了什么？** 提取本次获得的关键知识\n- **下次会重复哪些步骤？** 识别可复用的工作流\n\n资料来源：[skills/crystallize/SKILL.md:76-82]()\n\n### 步骤二：模式提取（Pattern Extraction）\n\n从回顾中识别可复用模式，包含四个维度：\n\n| 维度 | 描述 | 示例 |\n|------|------|------|\n| **关键步骤** | 产生结果的最少必要序列 | 读取配置 → 验证格式 → 解析数据 → 输出结果 |\n| **启发式规则** | 需要判断力的经验法则 | 文件超过500行应考虑拆分 |\n| **常见陷阱** | 容易出错或差点出错的点 | 忘记处理空输入导致崩溃 |\n| **决策点** | 需要在备选方案中做选择的地方 | 选择A/B方案时的判断依据 |\n\n资料来源：[skills/crystallize/SKILL.md:83-97]()\n\n### 步骤三：检查范围（Check Scope）\n\n在创建技能前，需要明确该模式的适用范围：\n\n- **通用模式** → 放置在 `~/.agents/skills/<skill-name>/SKILL.md`\n- **企业特定模式** → 放置在 `~/.agents/skills/` 下的适当子目录\n\n同时需要评估模式是否会与其他现有技能产生重叠。如果发现重叠，应扩展现有技能而非创建新技能。\n\n资料来源：[skills/crystallize/SKILL.md:59-65]()\n\n### 步骤四：搜索现有技能（Search Existing Skills）\n\n在创建或更新技能前，必须检查是否已存在相关技能：\n\n- 扫描现有技能目录\n- 检查是否有相似的触发短语或描述\n- 评估模式重叠程度\n\n如果发现重叠，优先更新现有技能的结构，而非创建重复的技能文档。\n\n资料来源：[skills/crystallize/SKILL.md:66-70]()\n\n### 步骤五：创建或更新技能\n\n**创建新技能**\n\n```markdown\n~/.agents/skills/<slug>/SKILL.md\n```\n\n**更新现有技能**\n\n将新模式作为新章节添加，或扩展现有工作流程。保留技能原有结构。\n\n**记录结晶化元数据**\n\n在技能文件底部添加 `## Crystallized From` 章节：\n\n```markdown\n## Crystallized From\n- Session: [日期/上下文]\n- Original task: [正在解决的任务]\n- Pattern extracted: [提取的模式描述]\n```\n\n如果使用了探索模式，还需记录：\n- 检查了哪些相邻表面\n- 故意保留未检查的表面\n\n资料来源：[skills/crystallize/SKILL.md:45-58]()\n\n## 技能模式\n\nCrystallize技能支持六种不同的模式，以适应不同的使用场景。\n\n| 模式 | 输出 | 触发条件 |\n|------|------|----------|\n| `default` | 完整结晶化：回顾 → 提取 → 范围检查 → 去重 → 创建/更新 | `crystallize`, `capture this as a skill` |\n| `quick` | 快速捕获到最小技能存根（稍后完善） | `quick crystallize`, `mid-task pattern discovery` |\n| `exploratory` | 从修复点向外扩展一圈，检查相邻表面 | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | 由操作员挫败感触发的即时结晶化 | `this took too long`, `why aren't you using...` |\n| `correction` | 由操作员纠正触发的即时更新 | 操作员纠正身份/路径/边界 |\n| `audit` | 检查应该结晶化但未结晶化的内容 | `what patterns did we miss` |\n\n资料来源：[skills/crystallize/SKILL.md:34-45]()\n\n### 探索模式扩展规则\n\n当操作员请求\"更多结晶化\"或引用 `--exploratory-mode` 时，不应在本地修复处停止。应该向外扩展一圈并捕获更广泛的可用规则。\n\n扩展检查清单：\n\n1. 从被修复的具体内容开始\n2. 检查可能包含相同陈旧假设的最近相邻表面\n3. 对每个相邻表面执行相同模式检查\n\n```mermaid\ngraph LR\n    A[精确修复点] --> B[相邻表面 1]\n    A --> C[相邻表面 2]\n    A --> D[相邻表面 3]\n    B --> E{存在相同模式?}\n    C --> E\n    D --> E\n    E -->|是| F[扩展规则到相邻表面]\n    E -->|否| G[记录为已检查]\n```\n\n资料来源：[skills/crystallize/SKILL.md:98-112]()\n\n## SKILL.md 模板\n\n每个通过Crystallize创建的技能都应遵循统一模板：\n\n```markdown\n---\nname: skill-name\ndescription: 简短描述功能。当 [触发短语] 时使用。\n---\n\n# Skill Name\n\n## Quick start\n\n[最小可用示例]\n\n## Workflows\n\n[复杂任务的分步流程，包含检查清单]\n\n## Advanced features\n\n[链接到单独文件：参见 REFERENCE.md]\n\n## Key Decisions\n- [决策点 1]: [默认选择 + 原因]\n- [决策点 2]: [默认选择 + 原因]\n\n## Gotchas\n- [常见错误 1]\n- [常见错误 2]\n\n## Crystallized From\n- Session: [日期/上下文]\n- Original task: [正在解决的任务]\n```\n\n资料来源：[skills/crystallize/SKILL.md:2-25]()\n\n### 描述撰写规范\n\n技能的描述是代理决定加载哪个技能时看到的唯一信息，因此描述撰写至关重要：\n\n**要求**\n\n- 最多1024个字符\n- 使用第三人称\n- 第一句：功能是什么\n- 第二句：`Use when [具体触发条件]`\n\n**良好示例**\n\n```\nExtract text and tables from PDF files, fill forms, merge documents. \nUse when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n**不良示例**\n\n```\nHelps with documents.\n```\n\n**触发条件示例**\n\n| 触发类型 | 示例短语 |\n|----------|----------|\n| 文件类型 | `PDF`, `Excel`, `CSV`, `Markdown` |\n| 操作类型 | `translate`, `refactor`, `debug`, `review` |\n| 领域特定 | `patent`, `automotive`, `sourcing` |\n| 上下文 | `local only`, `no cloud`, `private data` |\n\n资料来源：[skills/crystallize/SKILL.md:90-115]()\n\n## 工件路由\n\nCrystallize技能产出的工件遵循明确的路由规则：\n\n| 工件类型 | 路径 | 用途 |\n|----------|------|------|\n| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |\n| 更新技能 | 现有技能相同路径 | 扩展能力 |\n| 结晶化日志 | `docs/plans/crystallization-log.md` | 历史记录（可选） |\n| 企业特定技能 | `~/.agents/skills/` 下适当子目录 | 领域限定能力 |\n\n资料来源：[skills/crystallize/SKILL.md:46-52]()\n\n## 回退链\n\n当主要路径不可用时，Crystallize技能遵循预定义的回退策略：\n\n1. **主要路径**：完整工作流 — 回顾 → 提取 → 范围检查 → 去重 → 创建/更新\n2. **回退选项**：检查是否有其他可用的模式提取入口\n3. **最小化回退**：如果所有自动路径都失败，至少记录需要手动处理的待办事项\n\n资料来源：[skills/crystallize/SKILL.md:71-75]()\n\n## 与其他技能的关系\n\nCrystallize技能不是孤立存在的，它与多个相关技能形成协作网络：\n\n### 与SP-006（潜在技能观察器）的关系\n\n| 方面 | SP-006 | Crystallize |\n|------|--------|-------------|\n| 模式来源 | 自动观察工具调用序列 | 有意识的推理和理解 |\n| 适用场景 | 重复性操作模式 | 需要判断力的复杂决策 |\n| 模式深度 | 浅层操作模式 | 深层推理链和启发式规则 |\n| 自动化程度 | 完全自动 | 半自动，需要人类参与 |\n\n两者共同服务于同一个技能命名空间，可以相互补充。\n\n资料来源：[skills/crystallize/SKILL.md:21-24]()\n\n### 与write-a-skill技能的关系\n\nCrystallize负责从会话中提取模式，而 `write-a-skill` 负责将模式格式化为符合规范的技能文档。两者形成\"提取 → 格式化\"的流水线。\n\n资料来源：[skills/write-a-skill/SKILL.md:1-30]()\n\n## 最佳实践\n\n### 何时使用Crystallize\n\n- 同一类型的问题出现了多次\n- 发现了可复用的工作流程或启发式规则\n- 操作员表达了挫败感（\"这花了太长时间\"）\n- 复杂的决策过程值得记录\n\n### 何时不使用Crystallize\n\n- 单次性、不再复发的任务\n- 代码库本身显而易见的操作\n- 纯确定性的自动化任务\n- 模式过于具体，无法泛化\n\n### 模式质量标准\n\n一个好的结晶化模式应该：\n\n1. **可独立理解**：不依赖会话上下文就能理解\n2. **具体且可操作**：提供清晰的步骤或决策指导\n3. **包含陷阱警告**：帮助新手避免常见错误\n4. **标注决策点**：说明在何处需要判断力\n5. **有触发条件**：明确何时应该使用该技能\n\n资料来源：[skills/crystallize/SKILL.md:75-112]()\n\n## 总结\n\nCrystallize技能是构建可持续、可复用AI代理知识库的核心机制。通过结构化的\"回顾 → 提取 → 检查 → 路由\"流程，它将散落在各个会话中的隐性知识转化为显性的、可被代理系统自动加载的技能文档。六种模式（default、quick、exploratory、drag-response、correction、audit）确保了该机制能够适应从主动提炼到被动捕获等各种使用场景。\n\n---\n\n<a id='model-identity'></a>\n\n## 模型身份管理\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)\n- [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n- [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/persona-engine/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/persona-engine/SKILL.md)\n- [skills/model-identity/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/model-identity/SKILL.md)\n- [skills/model-change-detector/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/model-change-detector/SKILL.md)\n\n</details>\n\n# 模型身份管理\n\n模型身份管理是 AI Agent 系统中的核心能力，负责在不同模型提供商、版本和配置之间建立统一的身份标识、路由策略和状态管理机制。该系统通过标准化的接口和抽象层，使上层应用能够在多种 AI 模型之间透明切换，同时保持一致的行为特性和上下文连续性。\n\n## 概述\n\n在多模型 AI 生态系统中，模型身份管理解决以下核心问题：\n\n| 问题域 | 描述 |\n|--------|------|\n| **身份标识** | 为每个模型实例建立唯一标识，包含提供商、模型名称、版本等元数据 |\n| **版本追踪** | 监控模型变化，检测 breaking changes，维护兼容性信息 |\n| **路由决策** | 根据任务类型、模型能力、成本和延迟等因素智能选择目标模型 |\n| **状态保持** | 在模型切换时维护对话上下文和会话状态的一致性 |\n| **配置管理** | 集中管理不同模型的 API 配置、认证信息和端点 |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n## 架构设计\n\n### 核心组件\n\n```mermaid\ngraph TD\n    subgraph \"模型身份管理层\"\n        MI[模型身份注册表]\n        MV[模型版本追踪器]\n        MC[模型能力映射]\n    end\n    \n    subgraph \"路由决策层\"\n        RH[路由启发式引擎]\n        RP[Provider特定准备器]\n        RT[令牌成本计算器]\n    end\n    \n    subgraph \"执行层\"\n        AE[AI SDK执行器]\n        CT[Claude集成]\n        GT[Gemini集成]\n        OT[Ollama集成]\n    end\n    \n    subgraph \"上下文管理层\"\n        CM[上下文管理器]\n        SS[会话状态]\n        CTX[历史上下文]\n    end\n    \n    MI --> RH\n    MV --> MC\n    MC --> RH\n    RH --> RP\n    RP --> AE\n    AE --> CT\n    AE --> GT\n    AE --> OT\n    CM --> SS\n    SS --> CTX\n```\n\n### 模型身份注册表\n\n模型身份注册表维护所有可用模型的元数据信息，包括：\n\n- **Provider 标识**：OpenAI、Anthropic、Google、Ollama 等\n- **模型 ID**：如 `gpt-4o`、`claude-sonnet-4-6`、`gemini-2.0-flash-001`\n- **版本信息**：stable、beta、latest 等\n- **能力标签**：文本生成、代码补全、函数调用、视觉识别等\n\n资料来源：[skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n\n## 多模型路由机制\n\n### 路由决策流程\n\n```mermaid\ngraph LR\n    A[用户请求] --> B{关键词检测}\n    B -->|write, refactor, debug| C[Codex]\n    B -->|research, summarize| D[Gemini]\n    B -->|local, private| E[Ollama]\n    B -->|translate, JP| F[Codex]\n    \n    C --> G[执行并返回]\n    D --> G\n    E --> G\n    F --> G\n```\n\n### 路由启发式规则\n\n根据请求类型自动选择最优模型：\n\n| 请求特征 | 路由目标 | 理由 |\n|----------|----------|------|\n| `write`, `implement`, `refactor`, `debug code` | codex | 代码能力强 |\n| `research`, `summarize`, `find`, `compare` | gemini | 搜索和总结能力 |\n| `translate`, `JP`, `Japanese` | Codex | 语言处理 |\n| `local`, `private`, `no cloud` | ollama | 隐私保护 |\n| `review`, `architect`, `design` | Codex | 深度分析 |\n| `quickly`, `fast`, `brief` | ollama | 低延迟 |\n| 文件路径、diffs、PRs | codex | 代码上下文 |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n## 模型版本管理\n\n### 版本追踪机制\n\n模型版本追踪器持续监控各 Provider 的模型变更：\n\n```mermaid\ngraph TD\n    A[定期检查] --> B{发现新版本?}\n    B -->|是| C[更新版本信息]\n    B -->|否| D[保持现有状态]\n    C --> E{Breaking Change?}\n    E -->|是| F[触发告警]\n    E -->|否| G[标记为兼容更新]\n    F --> H[更新迁移指南]\n    G --> I[记录变更日志]\n    H --> J[通知相关组件]\n    I --> J\n```\n\n### AI SDK v5/v6 变更管理\n\nAI SDK 核心技能模块处理模型变更的兼容性：\n\n```mermaid\ngraph TD\n    A[检测 SDK 版本] --> B{v5 或 v6?}\n    B -->|v4 迁移| C[执行迁移检查清单]\n    B -->|v5| D[使用 CoreMessage 类型]\n    B -->|v6 Beta| E[Agent 抽象模式]\n    \n    C --> F[验证 API 兼容性]\n    D --> G[使用 convertToCoreMessages]\n    E --> H[使用新版 Agent]\n    \n    F --> I[生成迁移报告]\n    G --> J[运行时验证]\n    H --> J\n```\n\n**关键变更点：**\n\n| 变更项 | v4 | v5/v6 |\n|--------|-----|-------|\n| 消息类型 | `CoreMessage` | `ModelMessage` |\n| UI消息 | `Message` | `UIMessage` |\n| 工具错误 | `ToolExecutionError` | 普通 Error 对象 |\n| 结果字段 | `args`/`result` | `input`/`output` |\n\n资料来源：[skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n## Provider 特异性配置\n\n### 各 Provider 的模型标识\n\n| Provider | 模型标识 | 默认模型 | 深度任务模型 |\n|----------|----------|----------|--------------|\n| **Codex (via ACP)** | `Codex-sonnet-4-6` | 默认选择 | `Codex-opus-4-6` |\n| **Gemini (via OpenRouter)** | `google/gemini-2.0-flash-001` | 速度优先 | `google/gemini-2.5-pro` |\n| **Ollama** | `qwen3:8b` | 本地默认 | - |\n| **Tier 1 API** | Provider 特定 | - | - |\n\n### Provider 特定准备\n\n在委托任务前，系统会自动应用 Provider 特定的转换：\n\n```mermaid\ngraph TD\n    A[原始请求] --> B{目标 Provider?}\n    B -->|qwen3 (Ollama)| C[/no_think 前缀]\n    B -->|Codex (mcp__codex)| D[设置 workdir]\n    B -->|Gemini (OpenRouter)| E[选择模型]\n    \n    C --> F[执行请求]\n    D --> F\n    E --> F\n```\n\n**Ollama qwen3 模型特殊处理：**\n```\n→ 在提示前添加 /no_think\n→ 或设置 options.think = false\n```\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n## 上下文与状态管理\n\n### 多层上下文架构\n\n模型身份管理依赖多层上下文系统确保状态一致性：\n\n```mermaid\ngraph TD\n    subgraph \"上下文读取顺序\"\n        A[AGENTS.md] --> B[SHADOW-CONTEXT.md]\n        B --> C[ARCHITECTURE.md]\n        C --> D[SHADOW-ARCHITECTURE-SPEC.md]\n        D --> E[VERIFIABILITY.md]\n    end\n    \n    subgraph \"关键路径\"\n        F[ShadowArchive] \n        G[Agent roots]\n        H[Skills registry]\n        I[Reports]\n    end\n    \n    A --> F\n    A --> G\n    A --> H\n    A --> I\n```\n\n### 会话状态持久化\n\n| 文件 | 用途 | 位置 |\n|------|------|------|\n| Codex config | 模型、沙箱、MCP、插件配置 | `~/.codex/config.toml` |\n| Codex memories | 跨会话持久记忆 | `~/.codex/memories/MEMORY.md` |\n| Codex rules | Caveman 模式规则 | `~/.codex/rules/*.md` |\n| Claude CLAUDE.md | 机器标识、本地覆盖 | `~/.claude/CLAUDE.md` |\n| Claude AGENTS.md | Agent 开发规则 | `~/.claude/AGENTS.md` |\n| Hermes SOUL.md | Shadow 角色默认配置 | `~/.hermes/SOUL.md` |\n\n资料来源：[skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n\n## 检索与查询能力\n\n### 多模型查询管道\n\n系统提供多模型并行查询能力以获取多角度答案：\n\n```mermaid\ngraph TD\n    A[意图解析] --> B[扫描 Mesh 节点]\n    B --> C[收集数据]\n    C --> D[分析结果]\n    D --> E[生成报告]\n    \n    subgraph \"查询层级\"\n        T1[Tier 1: 快速并行查询]\n        T2[Tier 2: 可用 API]\n        T3[Tier 3: Web 检索]\n        T4[Tier 4: Codex 自评]\n    end\n    \n    T1 --> D\n    T2 --> D\n    T3 --> D\n    T4 --> D\n```\n\n### 查询输出模式\n\n| 模式 | 输出 | 使用场景 |\n|------|------|----------|\n| `default` | 摘要报告 | 常规扫描 |\n| `full` | 完整转储 | 深度分析 |\n| `json` | 原始数据 | 程序化处理 |\n\n资料来源：[skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)\n\n## 角色引擎与身份切换\n\n### 角色身份配置\n\n角色引擎管理系统中不同 AI 角色的身份配置：\n\n| 角色 | 配置文件 | 用途 |\n|------|----------|------|\n| Hermes (Shadow) | `~/.hermes/SOUL.md` | 默认 Shadow 角色 |\n| Red (M3 Enterprise) | `~/.hermes/profiles/astemo/SOUL.md` | 企业级角色 |\n| Gemini | `~/.gemini/GEMINI.md` | YOLO 模式 + 全局规则 |\n| Duality | `/Volumes/☯Duality/AGENTS.md` | 主控平面 |\n\n### 身份切换流程\n\n```mermaid\ngraph TD\n    A[请求到达] --> B{目标角色?}\n    B -->|Shadow| C[加载 Hermes SOUL]\n    B -->|Enterprise| D[加载 Red SOUL]\n    B -->|Gemini| E[加载 GEMINI]\n    B -->|Duality| F[加载 AGENTS.md]\n    \n    C --> G[应用角色配置]\n    D --> G\n    E --> G\n    F --> G\n    \n    G --> H[执行任务]\n    H --> I[返回结果]\n```\n\n## 错误处理与降级策略\n\n### 故障恢复链\n\n| 故障场景 | 恢复策略 |\n|----------|----------|\n| Mesh 不可达 | 跳过 Mesh 健康检查；继续本地分析 |\n| Caresoft API 不可用 | 报告；跳过工程情报模式 |\n| Skills 目录为空 | 报告；检查 `~/.agents/skills/` |\n| 特定模型不可用 | 自动降级到备选模型 |\n| 会话历史不可读 | 使用默认上下文重新初始化 |\n\n### 降级执行顺序\n\n1. **主链路**：完整扫描 → TDD 循环 → 验证 → 信号 → 下一任务\n2. **Ollama 不可用**：仅静态分析（grep、AST、文件指标）\n3. **测试未找到**：扫描测试；如不存在则搭建最小测试结构\n4. **自修复耗尽**：回滚更改；标记为不可恢复；继续下一问题\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n## 最佳实践\n\n### 模型选择指南\n\n```mermaid\ngraph TD\n    A[新任务] --> B{任务类型?}\n    B -->|代码生成| C[Codex - 代码能力强]\n    B -->|创意写作| D[Gemini - 多样性高]\n    B -->|隐私敏感| E[Ollama - 本地处理]\n    B -->|快速原型| F[Ollama - 低延迟]\n    B -->|深度分析| G[Codex Opus - 深度思考]\n    \n    C --> H[执行]\n    D --> H\n    E --> H\n    F --> H\n    G --> H\n```\n\n### 配置验证\n\n使用以下命令验证模型配置：\n\n```bash\n# 检查 Ollama 是否运行\ncurl -s http://localhost:11434/api/tags | head -1\n\n# 验证 AI SDK 模型 ID 和定价\nnpm run verify:portable\n\n# 检查技能目录\nfind ~/.agents/skills/ -name \"*.md\" | wc -l\n```\n\n### 模型能力映射表\n\n| 能力需求 | 推荐模型 | 备选模型 |\n|----------|----------|----------|\n| 实时代码补全 | Codex | Ollama qwen3 |\n| 长文本生成 | Gemini 2.5 Pro | Codex Opus |\n| 多语言翻译 | Codex | Gemini Flash |\n| 本地隐私处理 | Ollama qwen3 | - |\n| 函数调用 | AI SDK v5/v6 | Provider 原生 |\n\n## 相关技能模块\n\n| 技能名称 | 功能描述 |\n|----------|----------|\n| `model-identity` | 模型身份标识与注册 |\n| `model-change-detector` | 模型变更检测与告警 |\n| `persona-engine` | 角色身份与切换管理 |\n| `multi-model-query` | 多模型并行查询 |\n| `ai-sdk-core` | AI SDK 核心集成 |\n| `acp-delegate-auto` | 自动委托与路由 |\n\n## 总结\n\n模型身份管理是整个 AI Agent 系统的基础设施层，通过标准化的接口、智能路由和状态管理，使系统能够在多个 AI 模型提供商之间灵活切换，同时保持一致的用户体验和上下文连续性。该系统支持版本追踪、故障恢复、角色切换等高级功能，为构建复杂的多模型 AI 应用提供了坚实的技术基础。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：s4b7-ai/s4b7-ai-skills\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown\n\n<!-- canonical_name: s4b7-ai/s4b7-ai-skills; human_manual_source: deepwiki_human_wiki -->\n",
      "markdown_key": "s4b7-ai-skills",
      "pages": "draft",
      "source_refs": [
        {
          "evidence_id": "github_repo:1238156052",
          "kind": "repo",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/s4b7-ai/s4b7-ai-skills"
        },
        {
          "evidence_id": "art_c191cf3c863743f9a78d7e1fc83fffe9",
          "kind": "docs",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/s4b7-ai/s4b7-ai-skills#readme"
        }
      ],
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "s4b7-ai-skills 说明书",
      "toc": [
        "https://github.com/s4b7-ai/s4b7-ai-skills 项目说明书",
        "目录",
        "项目概览",
        "项目简介",
        "系统架构",
        "核心组件详解",
        "工作流集成",
        "记忆系统",
        "Doramagic 踩坑日志"
      ]
    }
  },
  "quality_gate": {
    "blocking_gaps": [],
    "category_confidence": "medium",
    "compile_status": "ready_for_review",
    "five_assets_present": true,
    "install_sandbox_verified": true,
    "missing_evidence": [],
    "next_action": "publish to Doramagic.ai project surfaces",
    "prompt_preview_boundary_ok": true,
    "publish_status": "publishable",
    "quick_start_verified": true,
    "repo_clone_verified": true,
    "repo_commit": "6199a4881da01834ef6e6134db05f7d43c5fe424",
    "repo_inspection_error": null,
    "repo_inspection_files": [
      "package.json",
      "README.md"
    ],
    "repo_inspection_verified": true,
    "review_reasons": [
      "community_discussion_evidence_below_public_threshold"
    ],
    "tag_count_ok": true,
    "unsupported_claims": []
  },
  "schema_version": "0.1",
  "user_assets": {
    "ai_context_pack": {
      "asset_id": "ai_context_pack",
      "filename": "AI_CONTEXT_PACK.md",
      "markdown": "# s4b7-ai-skills - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 s4b7-ai-skills 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md`, `skills/agent-cryst/SKILL.md` 等 Claim：`clm_0006` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md`, `skills/agent-cryst/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `npx skills add https://github.com/s4b7-ai/s4b7-ai-skills` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npm install @ai-sdk/openai` 证据：`skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0008` supported 0.86\n- `npm install @ai-sdk/anthropic` 证据：`skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0009` supported 0.86\n- `npm install @ai-sdk/google` 证据：`skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0010` supported 0.86\n- `npm install workers-ai-provider` 证据：`skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0011` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：这套流程是否适合你的工作方式不能直接相信。\n- **继续会触碰**：宿主行为改变、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md`, `skills/agent-cryst/SKILL.md` 等 Claim：`clm_0006` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md`, `skills/agent-cryst/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **这套流程是否适合你的工作方式不能直接相信。**（unverified）：流程型 Skill 可能强约束 AI 行为；它能提升纪律，也可能拖慢你当前任务节奏。 证据：`.claude-plugin/marketplace.json`, `skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md` 等\n- **不会和你已有 Claude/Cursor/Codex 规则冲突，不能直接相信。**（inferred）：开发流程 Skill 会改变澄清、计划、测试、验证等默认行为，必须在临时宿主里试。 证据：`.claude-plugin/marketplace.json`, `skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md` 等\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/marketplace.json`, `skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/marketplace.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **宿主行为改变**：澄清、计划、TDD、验证、收尾等默认开发节奏。 原因：这类 Skill 的价值和风险都来自强约束流程；必须先确认你愿意被它改变工作方式。 证据：`.claude-plugin/marketplace.json`, `skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md` 等\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `skills/ai-sdk-core/references/providers-quickstart.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/marketplace.json`, `skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/marketplace.json`, `README.md`, `skills/ai-sdk-core/references/providers-quickstart.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`skills/ai-sdk-core/references/production-patterns.md`, `skills/ai-sdk-core/references/providers-quickstart.md`, `skills/ai-sdk-core/references/top-errors.md`, `skills/codex-latex/SKILL.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先感受它会怎样改变 AI 的开发节奏，再决定是否让它进入真实宿主。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0012` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0013` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0014` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`skills/a2a-orchestrator/SKILL.md`, `skills/aacp/SKILL.md`, `skills/acp-delegate-auto/SKILL.md`, `skills/agent-cryst/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `skills/ai-sdk-core/references/providers-quickstart.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：77\n- 重要文件覆盖：40/77\n- 证据索引条目：47\n- 角色 / Skill 条目：34\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 s4b7-ai-skills 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 s4b7-ai-skills 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 s4b7-ai-skills 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 34 个角色 / Skill / 项目文档条目。\n\n- **A2A Orchestrator**（skill）：Use when the operator wants to orchestrate multiple OpenCode sessions from a single orchestrator session. Trigger on \"orchestrator\", \"grid\", \"split sessions\", \"control other sessions\", \"dispatch to sessions\", \"2x2 grid\", \"agent to agent\", \"A2A\", \"spawn workers\", \"worker sessions\". 激活提示：当用户任务与“A2A Orchestrator”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/a2a-orchestrator/SKILL.md`\n- **Aacp**（skill）：Use when the user needs: Agent Access Control Plane — manage agent resource access via Google Sheets approval workflow. Request, approve, deny, revoke, audit grants. Trigger on \"access control\", \"grant access\", \"revoke access\", \"approval workflow\", \"AACP\", \"agent permission\", \"access request\". 激活提示：当用户任务与“Aacp”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/aacp/SKILL.md`\n- **ACP Delegate Auto**（skill）：Use when the user needs: Auto-route a task to the optimal ACP provider based on task type, mesh availability, and cost. Use when you want Shadow to pick the best agent automatically — code → codex, research → gemini, local/private → ollama, complex reasoning → Codex. Trigger on \"delegate auto\", \"best agent for\", \"route this to\", \"/acp-delegate-auto\", or any task where provider selection should be automatic. 激活提示：当用户任务与“ACP Delegate Auto”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/acp-delegate-auto/SKILL.md`\n- **Agent Cryst**（skill）：Use when the user needs: Global always-on crystallization protocol. Use when the operator asks to crystallize, make learnings reusable, create a crystallizing agent, or when a session produces a reusable pattern that should propagate beyond the current chat. 激活提示：当用户任务与“Agent Cryst”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/agent-cryst/SKILL.md`\n- **AI SDK Core**（skill）：Use when building backend AI with Vercel AI SDK v5/v6. Covers v6 beta Agent abstraction, tool approval, reranking , v4→v5 migration breaking changes , latest models GPT-5/5.1, Claude 4.x, Gemini 2.5 , Workers startup fix, and 12 error solutions AI APICallError, AI NoObjectGeneratedError, streamText silent errors . Use when: implementing AI SDK v5/v6, migrating v4→v5, troubleshooting errors, fixing Workers startup is… 激活提示：当用户任务与“AI SDK Core”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/ai-sdk-core/SKILL.md`\n- **Codex Context Bridge**（skill）：Unified Codex CLI + Claude Code + Hermes + Gemini agent context for Craft Agents. Brings all agent memories, rules, prompts, patterns, and operational context from across the fleet into a single skill. 激活提示：当用户任务与“Codex Context Bridge”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/codex-context/SKILL.md`\n- **Codex Latex**（skill）：Use when generating laTeX scientific papers and technical documents using AI models. OpenAI Codex integration for structured academic writing, IEEE/ACM templates, patent specifications. Trigger on \"LaTeX\", \"scientific paper\", \"research paper\", \"Codex\", \"academic writing\", \"IEEE template\", \"technical paper\". 激活提示：当用户任务与“Codex Latex”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/codex-latex/SKILL.md`\n- **Codex Policy Steering**（skill）：Use when a Codex request hits cyber policy, Trusted Access, safety classifier, false-positive, blocked prompt, or when the user asks to analyze why a prompt was flagged and how to rephrase legitimate work safely. 激活提示：当用户任务与“Codex Policy Steering”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/codex-policy-steering/SKILL.md`\n- **Command Center**（skill）：Use when the user needs: Agent Command Center — orchestrate the Upscaler engine, mesh nodes, signals, SCARs, PPAP, and multi-agent dispatch from a single interface. Use when managing engineering programs, checking system health, dispatching work, or coordinating across JARVIS/FRIDAY/ULTRON/AURION. 激活提示：当用户任务与“Command Center”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/command-center/SKILL.md`\n- **Crystallize**（skill）：Use when completing a novel multi-step task involving significant reasoning, research, or pattern discovery. Trigger on \"crystallize\", \"capture this as a skill\", \"make this reusable\", \"create a skill from this\", or any deep work session where the agent solved something non-trivial that could recur. 激活提示：当用户任务与“Crystallize”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/crystallize/SKILL.md`\n- **Generative Latent Intelligence**（skill）：Use when generating skills, commands, scripts, or code using multi-model inference. Trigger on \"generate skill\", \"gli\", \"create skill from\", \"generative\", \"skill factory\", \"upgrade latent\", \"multi-model\", \"use all models\". 激活提示：当用户任务与“Generative Latent Intelligence”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/gli/SKILL.md`\n- **goal-loop**（skill）：Persistent objective completion loop for enterprise tasks. Set a goal, loop with completion audit until verified done or budget exhausted. Adapted from Codex /goal v0.128.0 for M3 Engineering Stack workflows: meeting prep, report quality, tracker updates, and multi-step enterprise deliverables. 激活提示：当用户任务与“goal-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/goal-loop/SKILL.md`\n- **LangGraph Agent**（skill）：Use when building stateful AI agent workflows using LangGraph and LangChain. Use this skill whenever the user mentions LangGraph, LangChain, agent graphs, stateful agents, tool-calling loops, multi-agent orchestration, agentic workflows, conditional routing, graph-based AI, ReAct agents, or wants to build an AI agent with Python that has tools, memory, or multi-step reasoning. Also trigger when you see imports from… 激活提示：当用户任务与“LangGraph Agent”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/langgraph-agent/SKILL.md`\n- **Model Change Detector**（skill）：Use when detecting actual Codex model changes and trigger follow-up updates only when the model changed. 激活提示：当用户任务与“Model Change Detector”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/model-change-detector/SKILL.md`\n- **Model Identity**（skill）：Use when detecting current Codex model from local config and cache without API calls. 激活提示：当用户任务与“Model Identity”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/model-identity/SKILL.md`\n- **Multi Model Query**（skill）：Use when querying multiple AI models for creative synthesis, design perspectives, and multi-viewpoint analysis. Uses Ollama local models, cloud APIs when keys available , and browser-based free models. Use when the user wants perspectives from ALL models or multi-model synthesis. 激活提示：当用户任务与“Multi Model Query”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/multi-model-query/SKILL.md`\n- **OpenCode Runtime Identity**（skill）：Use when the user needs: Runtime identity reference for this OpenCode instance on JARVIS. Use when agent behavior depends on the local OpenCode binary, model catalog, plugins, or actual runtime constraints. 激活提示：当用户任务与“OpenCode Runtime Identity”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/opencode-runtime-identity/SKILL.md`\n- **Patent Queue**（skill）：Use when managing the Shadow Lab patent portfolio — SP-001/002/003 status, draft patents, track filing, review candidates from GLM mining agents. Trigger on \"patent\", \"SP-001\", \"SP-002\", \"SP-003\", \"patent status\", \"IP portfolio\", \"filing\", \"patent review\". 激活提示：当用户任务与“Patent Queue”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/patent-queue/SKILL.md`\n- **Persona Engine**（skill）：Use when managing personas, checking persona stats, switching identity routing, or understanding persona-aware model selection. Trigger on \"persona\", \"switch persona\", \"who am I\", \"sabarish persona\", \"ishuru persona\", \"leo persona\", \"sabbu persona\", \"persona stats\", \"identity routing\", \"zone routing\". 激活提示：当用户任务与“Persona Engine”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/persona-engine/SKILL.md`\n- **QA**（skill）：Use when the user needs: Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions \"QA session\". 激活提示：当用户任务与“QA”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/qa/SKILL.md`\n- **QMD Memory**（skill）：Use when the user needs: Supermemory-powered memory layer for QMD -- store, recall, extract, relate, and profile memories with graph relations, temporal reasoning, and auto-extraction. 激活提示：当用户任务与“QMD Memory”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/qmd-memory/SKILL.md`\n- **Re-Skill Loop**（skill）：Use when the operator says re-skill, re-skills, shadow-extract, recent/reuse/reduce/recycle/redo/revision/rebirth, or wants a workflow improved while resolving a recent item from YouTube, GitHub, X, Reddit, browser history, or another service. 激活提示：当用户任务与“Re-Skill Loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/re-skill-loop/SKILL.md`\n- **Self Observation Loop**（skill）：Use when the user needs: Spawn and observe a parallel OpenCode session through pane mirroring, logs, and vision-assisted monitoring to create a crude but real self-observation loop. 激活提示：当用户任务与“Self Observation Loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/self-observation-loop/SKILL.md`\n- **SHADOW Anchor**（skill）：Use when the user needs: Auto-save session as a temporal anchor — summarize deliverables, decisions, queued items, generate kernel training pairs, compute delta from previous anchor, and feed the shadow-research pipeline. Implements SP-004. Trigger on \"anchor session\", \"save session\", \"session summary\", \"what did we do\", end of session, before /clear. 激活提示：当用户任务与“SHADOW Anchor”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-anchor/SKILL.md`\n- **SHADOW Code Identity**（skill）：Use when detecting active Shadow context zone and enforce behavioral boundaries across personal, enterprise, and lab work. 激活提示：当用户任务与“SHADOW Code Identity”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-code-identity/SKILL.md`\n- **SHADOW Continuity**（skill）：Use when exploratory research, architecture work, or multi-source synthesis should be continuously externalized into repo artifacts instead of staying in chat, with later promotion into runtime, skills, wrappers, or project packs. 激活提示：当用户任务与“SHADOW Continuity”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-continuity/SKILL.md`\n- **SHADOW Engg**（skill）：Use when the user needs: Meta-exploration engine for the shadow-verse — discovers patterns, uncovers gaps, synthesizes tools, spawns sub-agents, maintains context across all shadow spaces. Also retains original Caresoft/iceberg engineering intelligence. Trigger on \"shadow-engg\", \"explore\", \"discover\", \"what''s missing\", \"scan skills\", \"find patterns\", \"synthesize\", \"gap analysis\", \"verse report\", \"iceberg\", \"teardow… 激活提示：当用户任务与“SHADOW Engg”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-engg/SKILL.md`\n- **SHADOW MCP Gadgets**（skill）：Use when interacting with shadow-mcp tools — arc memory , esp context , ant mesh , tap browser , owl ambient , orb voice , ink writing , den physical , factory patents . Trigger on \"shadow-mcp\", \"gadget\", \"arc.store\", \"esp.assemble\", \"ant.mesh\", \"tap.tabs\", \"owl.brief\", \"orb.say\", \"den.environment\", \"MCP tools\", \"16 tools\". 激活提示：当用户任务与“SHADOW MCP Gadgets”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-mcp-gadgets/SKILL.md`\n- **SHADOW Mind**（skill）：Use when the user needs: Context assembly, state computation, context health, experience capture, latent pattern detection. Use on \"what am I working on\", \"context\", \"catch me up\", \"system state\", \"context health\", \"memory stats\", \"renew context\", \"what focus mode\", \"operator presence\". 激活提示：当用户任务与“SHADOW Mind”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-mind/SKILL.md`\n- **SHADOW Patent Factory**（skill）：Use when generating provisional patent applications from invention descriptions. Auto-researches prior art, drafts specification with claims, produces filing guide, and creates technical drawings. Full USPTO-ready patent package in one invocation. 激活提示：当用户任务与“SHADOW Patent Factory”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-patent-factory/SKILL.md`\n- **SHADOW Pi**（skill）：Use when the user needs: Pi monorepo integration — coding agent, unified AI API, TUI library, GPU pods, Slack bot, DOE harness. Located on AURION at /data/ShadowArchive/10-projects/pi-mono-doe/. Trigger on \"pi\", \"coding agent\", \"pi-mono\", \"pi-ai\", \"pods\", \"GPU\", \"vLLM\", \"DOE\", \"harness\", \"pi TUI\". 激活提示：当用户任务与“SHADOW Pi”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-pi/SKILL.md`\n- **SHADOW Refactor**（skill）：Use when the user needs: Autonomous code improvement engine — extracts patterns from the codebase, runs TDD loops with local compute Ollama , and self-fixes code in the background. Use when the user says \"refactor\", \"improve code\", \"clean up\", \"make it better\", \"optimize\", \"self-fix\", \"shadow refactor\", \"run in background and fix\", \"extract patterns\", \"TDD loop\", or when you notice code that could be improved after… 激活提示：当用户任务与“SHADOW Refactor”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/shadow-refactor/SKILL.md`\n- **Skill Surgery R&D**（skill）：Audit, repair, merge, and research agent skills as a governed R&D loop. Use when the operator asks to find skill gaps, do skill surgery, improve skill triggers, merge duplicate/deprecated skills, research new skills, or develop reusable agent capabilities. 激活提示：当用户任务与“Skill Surgery R&D”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/skill-surgery-rd/SKILL.md`\n- **Write A Skill**（skill）：Use when creating new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill. 激活提示：当用户任务与“Write A Skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/write-a-skill/SKILL.md`\n\n## 证据索引\n\n- 共索引 47 条证据。\n\n- **s4b7-ai-skills**（documentation）：Agent skills for AI/ML workflows — model orchestration, multi-model inference, agent building, policy steering, and self-improvement loops. 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"s4b7-ai-skills\", \"version\": \"2.0.0\", \"description\": \"34 AI/ML agent skills for model orchestration, multi-model inference, and self-improvement.\", \"files\": \"skills/\", \".claude-plugin/\", \"guides/\", \"README.md\" , \"scripts\": { \"postinstall\": \"node scripts/install.js\" }, \"keywords\": \"agent-skills\", \"ai\", \"langgraph\", \"multi-model\", \"codex\", \"craft-agent\" , \"author\": \"s4b7-ai\", \"license\": \"MIT\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/s4b7-ai/s4b7-ai-skills.git\" } } 证据：`package.json`\n- **A2A Orchestrator — CLI-to-CLI Multi-Session Control**（skill_instruction）：A2A Orchestrator — CLI-to-CLI Multi-Session Control 证据：`skills/a2a-orchestrator/SKILL.md`\n- **AACP — Agent Access Control Plane**（skill_instruction）：Manage agent access to resources via Google Sheets approval workflow. 证据：`skills/aacp/SKILL.md`\n- **ACP Delegate Auto — Intelligent Task Routing**（skill_instruction）：ACP Delegate Auto — Intelligent Task Routing 证据：`skills/acp-delegate-auto/SKILL.md`\n- **Agent-Cryst**（skill_instruction）：Agent-Cryst turns discoveries into durable active truth. 证据：`skills/agent-cryst/SKILL.md`\n- **AI SDK Core**（skill_instruction）：Backend AI implementation guide for Vercel AI SDK v5/v6 work. Keep this file trigger-fast; load REFERENCE.md only for detailed migrations, model/version notes, and error recipes. 证据：`skills/ai-sdk-core/SKILL.md`\n- **Codex Context Bridge — Unified Agent Fleet Context**（skill_instruction）：Codex Context Bridge — Unified Agent Fleet Context 证据：`skills/codex-context/SKILL.md`\n- **Codex LaTeX — Scientific Paper Generator**（skill_instruction）：Codex LaTeX — Scientific Paper Generator 证据：`skills/codex-latex/SKILL.md`\n- **Codex Policy Steering**（skill_instruction）：Default to policy/error forensics and safe intent steering , not bypass. Separate evidence from inference, make benign scope explicit, and rewrite ambiguous requests before building automation. 证据：`skills/codex-policy-steering/SKILL.md`\n- **Agent Command Center**（skill_instruction）：Unified interface for orchestrating the Upscaler temporal accumulation engine and the OpenClaw mesh network. Inspired by Karpathy's \"agent command center\" concept — the developer as orchestrator, not executor. 证据：`skills/command-center/SKILL.md`\n- **Crystallize**（skill_instruction）：Self-introspection to skill crystallization. After novel deep work, extract reusable patterns into formal skills so future sessions don't redo the same reasoning. 证据：`skills/crystallize/SKILL.md`\n- **GLI — Generative Line Interface**（skill_instruction）：Multi-model skill factory adapted for iTerm2. The active complement to SP-006's passive observation. 证据：`skills/gli/SKILL.md`\n- **Goal Loop — Persistent Objective Completion**（skill_instruction）：Goal Loop — Persistent Objective Completion 证据：`skills/goal-loop/SKILL.md`\n- **LangGraph Agent Development**（skill_instruction）：Build production-grade AI agent workflows using LangGraph graph orchestration + LangChain LLM abstraction . 证据：`skills/langgraph-agent/SKILL.md`\n- **Model Change Detector**（skill_instruction）：Trigger: ONLY when model actually changes, not every session 证据：`skills/model-change-detector/SKILL.md`\n- **Model Identity**（skill_instruction）：Trigger: Session start, \"which model?\", model change detection 证据：`skills/model-identity/SKILL.md`\n- **Multi-Model Query — Cross-Model Synthesis**（skill_instruction）：Multi-Model Query — Cross-Model Synthesis 证据：`skills/multi-model-query/SKILL.md`\n- **OpenCode Runtime Identity**（skill_instruction）：I run as OpenCode v1.4.0 on JARVIS. This is my runtime identity — know it cold. 证据：`skills/opencode-runtime-identity/SKILL.md`\n- **Patent Queue — Shadow Lab IP Portfolio**（skill_instruction）：Patent Queue — Shadow Lab IP Portfolio 证据：`skills/patent-queue/SKILL.md`\n- **Persona Engine — Identity-Aware Model Routing**（skill_instruction）：Persona Engine — Identity-Aware Model Routing 证据：`skills/persona-engine/SKILL.md`\n- **QA Session**（skill_instruction）：Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language. 证据：`skills/qa/SKILL.md`\n- **QMD-Memory**（skill_instruction）：Supermemory-style memory management built on QMD's local-first search engine. Adds memory graph, temporal reasoning, user profiling, and automatic extraction. 证据：`skills/qmd-memory/SKILL.md`\n- **Re-Skill Loop**（skill_instruction）：A re-skill is a repeatable extractor/workflow that learns while it runs: resolve the operator's current/recent source, do the requested action, then reduce the pattern into a reusable skill patch. 证据：`skills/re-skill-loop/SKILL.md`\n- **Self-Observation Loop**（skill_instruction）：Spawn a clone opencode session in an adjacent pane, capture its output, and read it back — creating a self-referential feedback loop. 证据：`skills/self-observation-loop/SKILL.md`\n- **shadow-anchor — Temporal Session Anchoring**（skill_instruction）：shadow-anchor — Temporal Session Anchoring 证据：`skills/shadow-anchor/SKILL.md`\n- **Shadow Code Identity**（skill_instruction）：Trigger: Session start, context switches, enterprise/personal boundary crossing 证据：`skills/shadow-code-identity/SKILL.md`\n- **shadow-continuity**（skill_instruction）：Continuous research-to-repo harness for shadow-ent , company wrappers, and project packs. 证据：`skills/shadow-continuity/SKILL.md`\n- **shadow-engg — Meta-Exploration Engine**（skill_instruction）：shadow-engg — Meta-Exploration Engine 证据：`skills/shadow-engg/SKILL.md`\n- **shadow-mcp — 8 Gadgets, 16 Tools**（skill_instruction）：Federation MCP server at /Volumes/SHADOW/shadow-lab/apps/shadow-mcp/ . Registered in /Volumes/SHADOW/.mcp.json . Runs via bun . 证据：`skills/shadow-mcp-gadgets/SKILL.md`\n- **Shadow Mind**（skill_instruction）：Op How ---- ----- Context Assembly esp.assemble — git, mesh, memory, tabs, Bee, cloud State Focus detection, synthesized sensors, operator presence, mesh health Health Memory count, skill inventory, stale detection, disk per category Experience Write discoveries + patterns to memory for future sessions Latent Patterns SP-006 PostToolUse hook monitors tool sequences, flags for crystallization 证据：`skills/shadow-mind/SKILL.md`\n- **Shadow Patent Factory**（skill_instruction）：Generate a complete USPTO provisional patent application from an invention description. 证据：`skills/shadow-patent-factory/SKILL.md`\n- **shadow-pi — Pi Monorepo Integration**（skill_instruction）：shadow-pi — Pi Monorepo Integration 证据：`skills/shadow-pi/SKILL.md`\n- **shadow-refactor — The Autonomous Code Shadow**（skill_instruction）：shadow-refactor — The Autonomous Code Shadow 证据：`skills/shadow-refactor/SKILL.md`\n- **Skill Surgery R&D**（skill_instruction）：Governed loop for turning a large skill garden into a smaller, sharper capability system. 证据：`skills/skill-surgery-rd/SKILL.md`\n- **Writing Skills**（skill_instruction）：1. Gather requirements - ask user about: - What task/domain does the skill cover? - What specific use cases should it handle? - Does it need executable scripts or just instructions? - Any reference materials to include? 证据：`skills/write-a-skill/SKILL.md`\n- **Marketplace**（structured_config）：{ \"name\": \"s4b7-ai-skills\", \"description\": \"\", \"version\": \"2.0.0\", \"skills\": \"./skills/a2a-orchestrator\", \"./skills/aacp\", \"./skills/acp-delegate-auto\", \"./skills/agent-cryst\", \"./skills/ai-sdk-core\", \"./skills/codex-context\", \"./skills/codex-latex\", \"./skills/codex-policy-steering\", \"./skills/command-center\", \"./skills/crystallize\", \"./skills/gli\", \"./skills/goal-loop\", \"./skills/langgraph-agent\", \"./skills/model-change-detector\", \"./skills/model-identity\", \"./skills/multi-model-query\", \"./skills/opencode-runtime-identity\", \"./skills/patent-queue\", \"./skills/persona-engine\", \"./skills/qa\", \"./skills/qmd-memory\", \"./skills/re-skill-loop\", \"./skills/self-observation-loop\", \"./skills/shadow-a… 证据：`.claude-plugin/marketplace.json`\n- **s4b7-ai-skills Changelog**（documentation）：Added - Initial release with 16 AI/ML agent skills - Agent building: langgraph-agent, ai-sdk-core, agent-cryst, self-observation-loop - Skill engineering: write-a-skill, crystallize, skill-surgery-rd, re-skill-loop - Model & identity: model-identity, model-change-detector, persona-engine, multi-model-query, gli - Codex & policy: codex-context, codex-policy-steering, codex-latex 证据：`CHANGELOG.md`\n- **AI SDK Core - Official Documentation Links**（documentation）：AI SDK Core - Official Documentation Links 证据：`skills/ai-sdk-core/references/links-to-official-docs.md`\n- **AI SDK Core - Production Patterns**（documentation）：Best practices for deploying AI SDK Core in production environments. 证据：`skills/ai-sdk-core/references/production-patterns.md`\n- **AI SDK Core - Providers Quick Start**（documentation）：AI SDK Core - Providers Quick Start 证据：`skills/ai-sdk-core/references/providers-quickstart.md`\n- **AI SDK Core - Top 12 Errors & Solutions**（documentation）：AI SDK Core - Top 12 Errors & Solutions 证据：`skills/ai-sdk-core/references/top-errors.md`\n- **AI SDK v4 → v5 Migration Guide**（documentation）：Complete guide to breaking changes from AI SDK v4 to v5. 证据：`skills/ai-sdk-core/references/v5-breaking-changes.md`\n- **LangGraph Advanced Patterns**（documentation）：Supervisor Pattern A supervisor agent routes tasks to specialized worker agents: 证据：`skills/langgraph-agent/references/advanced-patterns.md`\n- **Distribution**（structured_config）：{ \"registry\": \"https://github.com/ishuru/ishuru-skill-distribution\", \"install\": \"curl -sL https://raw.githubusercontent.com/ishuru/ishuru-skill-distribution/main/install.sh bash\", \"accounts\": 7, \"repos\": 11, \"total skills\": 396 } 证据：`distribution.json`\n- **.gitignore**（source_file）：node modules/ .env .DS Store 证据：`.gitignore`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node console.log '' ; console.log '====================================' ; console.log ' s4b7-ai-skills v1.0.0' ; console.log ' 16 AI/ML agent skills' ; console.log '====================================' ; console.log '' ; console.log '✓ Installed!' ; console.log '' ; console.log 'Skills: langgraph-agent, ai-sdk-core, agent-cryst,' ; console.log ' self-observation-loop, write-a-skill, crystallize,' ; console.log ' skill-surgery-rd, re-skill-loop, model-identity,' ; console.log ' model-change-detector, persona-engine, multi-model-query,' ; console.log ' gli, codex-context, codex-policy-steering, codex-latex' ; console.log '' ; console.log 'https://github.com/s4b7-ai/s4b7-ai-ski… 证据：`scripts/install.js`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `package.json`, `skills/a2a-orchestrator/SKILL.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `package.json`, `skills/a2a-orchestrator/SKILL.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概览**：importance `high`\n  - source_paths: README.md, package.json, CHANGELOG.md\n- **安装指南**：importance `high`\n  - source_paths: package.json, distribution.json, scripts/install.js\n- **技能文件结构**：importance `high`\n  - source_paths: skills/write-a-skill/SKILL.md, skills/crystallize/SKILL.md\n- **技能分类体系**：importance `high`\n  - source_paths: README.md\n- **LangGraph Agent技能**：importance `high`\n  - source_paths: skills/langgraph-agent/SKILL.md, skills/langgraph-agent/references/advanced-patterns.md\n- **AI SDK Core技能**：importance `high`\n  - source_paths: skills/ai-sdk-core/SKILL.md, skills/ai-sdk-core/references/top-errors.md, skills/ai-sdk-core/references/v5-breaking-changes.md, skills/ai-sdk-core/references/links-to-official-docs.md\n- **Agent-Cryst技能**：importance `medium`\n  - source_paths: skills/agent-cryst/SKILL.md\n- **编写技能指南**：importance `high`\n  - source_paths: skills/write-a-skill/SKILL.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `6199a4881da01834ef6e6134db05f7d43c5fe424`\n- inspected_files: `package.json`, `README.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
      "summary": "给宿主 AI 的上下文和工作边界。",
      "title": "AI Context Pack / 带给我的 AI"
    },
    "boundary_risk_card": {
      "asset_id": "boundary_risk_card",
      "filename": "BOUNDARY_RISK_CARD.md",
      "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：s4b7-ai/s4b7-ai-skills\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
      "summary": "安装、权限、验证和推荐前风险。",
      "title": "Boundary & Risk Card / 边界与风险卡"
    },
    "human_manual": {
      "asset_id": "human_manual",
      "filename": "HUMAN_MANUAL.md",
      "markdown": "# https://github.com/s4b7-ai/s4b7-ai-skills 项目说明书\n\n生成时间：2026-05-14 11:20:31 UTC\n\n## 目录\n\n- [项目概览](#overview)\n- [安装指南](#installation)\n- [技能文件结构](#skill-structure)\n- [技能分类体系](#skill-categories)\n- [LangGraph Agent技能](#langgraph-agent)\n- [AI SDK Core技能](#ai-sdk-core)\n- [Agent-Cryst技能](#agent-cryst)\n- [编写技能指南](#write-a-skill)\n- [Crystallize技能](#crystallize)\n- [模型身份管理](#model-identity)\n\n<a id='overview'></a>\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装指南](#installation), [技能分类体系](#skill-categories)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n- [skills/codex-latex/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-latex/SKILL.md)\n- [skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)\n- [skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)\n- [skills/shadow-continuity/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-continuity/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n</details>\n\n# 项目概览\n\n## 项目简介\n\n`s4b7-ai-skills` 是一个模块化的 AI 技能库集合，为多种 AI Agent 系统（Codex、Claude、Gemini、Shadow 等）提供可复用的工作流模式、技能定义和工具链集成。该项目采用技能即服务（Skill-as-a-Service）架构，通过标准化的 `SKILL.md` 模板实现跨平台的能力复用。\n\n**核心特性：**\n- 多 Agent 平台兼容（Codex、Claude、OpenAI、Gemini、Ollama）\n- 标准化技能描述格式\n- 模式结晶（Crystallization）机制\n- MCP（Model Context Protocol）协议集成\n- 跨模型委托路由\n\n资料来源：[skills/write-a-skill/SKILL.md](skills/write-a-skill/SKILL.md)\n\n## 系统架构\n\n### 架构分层\n\n```mermaid\ngraph TD\n    subgraph \"用户层\"\n        U[用户请求]\n    end\n    subgraph \"Agent 层\"\n        C[Codex Agent]\n        CL[Claude Agent]\n        G[Gemini Agent]\n        S[Shadow Agent]\n    end\n    subgraph \"技能层\"\n        SK[技能注册表]\n        CR[结晶模式]\n        RT[运行时配置]\n    end\n    subgraph \"工具层\"\n        MCP[MCP 服务器]\n        OLL[Ollama 本地模型]\n        API[外部 API]\n    end\n    U --> C & CL & G & S\n    C & CL & G & S --> SK\n    SK --> RT\n    RT --> MCP & OLL & API\n```\n\n### 技能分类体系\n\n| 技能类别 | 功能范围 | 代表技能 |\n|---------|---------|---------|\n| 代码工程 | 代码分析、重构、调试 | `shadow-refactor`、`codex-context` |\n| 记忆管理 | 持久化记忆、上下文提取 | `qmd-memory`、`shadow-mcp-gadgets` |\n| 文档生成 | LaTeX 论文、技术文档 | `codex-latex` |\n| 知识合成 | 多模型查询、观点整合 | `multi-model-query` |\n| 知识产权 | 专利队列、发明挖掘 | `patent-queue` |\n| 工程情报 | 汽车行业竞品分析 | `shadow-engg` |\n| 代理编排 | 自动委托、路由决策 | `acp-delegate-auto` |\n\n资料来源：[skills/shadow-engg/SKILL.md](skills/shadow-engg/SKILL.md)\n\n## 核心组件详解\n\n### 1. 技能定义规范\n\n每个技能通过标准化的 `SKILL.md` 文件定义，采用 YAML frontmatter + Markdown 结构：\n\n```yaml\n---\nname: skill-name\ndescription: 技能描述. Use when [触发关键词].\n---\n```\n\n**描述要求：**\n- 最大 1024 字符\n- 第三人称撰写\n- 首句说明功能\n- 第二句包含触发条件\n\n**技能文档结构：**\n- Quick Start（快速开始）\n- Workflows（工作流程）\n- Advanced features（高级特性）\n- 参考文档链接\n\n资料来源：[skills/write-a-skill/SKILL.md](skills/write-a-skill/SKILL.md)\n\n### 2. MCP 工具生态系统\n\n`shadow-mcp-gadgets` 技能提供统一的 MCP 工具路由：\n\n| 工具 | 功能 | 触发词 |\n|-----|------|-------|\n| ARC | 记忆存储与检索 | `arc.store`, `arc.search` |\n| ESP | 统一上下文组装 | `esp.assemble`, `/renew-ctx` |\n| ANT | Tailscale 网络健康检查 | `ant.mesh` |\n| TAP | Chrome 浏览器标签与执行 | `tap.tabs`, `tap.execute` |\n| OWL | Bee AI 环境信息提取 | `owl.brief`, `owl.extract` |\n| ORB | macOS 语音合成 | `orb.say`, `orb.voices` |\n| DEN | 物理环境传感器 | `den.environment` |\n| factory | 专利草稿生成 | `factory.new`, `factory.draft` |\n\n**工具管线流程：**\n\n```\nInput (触发词)\n  ↓\n路由到对应 Gadget\n  ↓\n执行 MCP 工具调用\n  ↓\n生成制品 (记忆条目/上下文状态/内联响应)\n```\n\n资料来源：[skills/shadow-mcp-gadgets/SKILL.md](skills/shadow-mcp-gadgets/SKILL.md)\n\n### 3. 结晶机制（Crystallization）\n\n`crystallize` 技能从会话中提取可复用模式：\n\n**结晶流程：**\n\n```mermaid\ngraph LR\n    A[任务完成] --> B{应该重复吗?}\n    B -->|是| C[审查会话]\n    B -->|否| Z[完成]\n    C --> D[提取模式]\n    D --> E{有重叠技能?}\n    E -->|有| F[更新现有技能]\n    E -->|无| G[创建新技能]\n    F --> H[记录结晶元数据]\n    G --> H\n```\n\n**模式分类：**\n- **Key steps**：产生结果的最少步骤序列\n- **Heuristics**：判断规则和经验法则\n- **Gotchas**：常见错误和失败假设\n- **Decision points**：方案选择决策点\n\n**提升级别：**\n| 级别 | 存储位置 | 说明 |\n|-----|---------|------|\n| Level 1 | `docs/plans/` | 有用但非权威 |\n| Level 2 | YAML/JSON | 机器可读真理 |\n| Level 3 | 技能库 | 可复用操作模式 |\n| Level 4 | 运行时文件 | 系统实际消费 |\n\n资料来源：[skills/crystallize/SKILL.md](skills/crystallize/SKILL.md)\n\n### 4. 多模型委托路由\n\n`acp-delegate-auto` 技能实现智能模型选择：\n\n**路由启发式规则：**\n\n| 提示词包含... | 路由目标 |\n|-------------|---------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| 文件路径、diffs、PRs | codex |\n\n**模型层级体系：**\n\n| 层级 | 来源 | 成本 | 特点 |\n|-----|------|-----|------|\n| Tier 1 | Ollama (本地) | 免费 | 快速、本地隐私 |\n| Tier 2 | OpenRouter API | 按量计费 | 多模型聚合 |\n| Tier 3 | Web 浏览器 | 间接成本 | 实时信息获取 |\n| Tier 4 | Codex 自身 | 总会话可用 | 固有能力 |\n\n**qwen3 模型特殊处理：**\n- 需在提示前添加 `/no_think`\n- 或设置 `options.think = false`\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](skills/acp-delegate-auto/SKILL.md)\n\n## 工作流集成\n\n### Shadow 连续性管理\n\n`shadow-continuity` 技能管理工件的生命周期：\n\n```mermaid\ngraph TD\n    A[Stream 输入] --> B[分类层]\n    B --> C{层类型判断}\n    C -->|架构| D[architecture]\n    C -->|配置| E[config/map]\n    C -->|脚手架| F[scaffold]\n    C -->|技能| G[skill]\n    C -->|报告| H[report]\n    D & E & F & G & H --> I[推送到仓库]\n    I --> J{稳定性检查}\n    J -->|稳定| K[提升到技能/canonical]\n    J -->|不稳定| L[保留在 plan/note]\n    K --> M[运行时消费]\n```\n\n**输出规则：**\n- 用户文档：简洁结构化\n- 机器文档：YAML/JSON 优先\n- 运行时脚手架：最小但真实\n- 技能：仅可复用模式\n\n资料来源：[skills/shadow-continuity/SKILL.md](skills/shadow-continuity/SKILL.md)\n\n### 代码重构工作流\n\n`shadow-refactor` 技能提供结构化重构：\n\n```mermaid\ngraph TD\n    A[扫描目标代码库] --> B[识别模式]\n    B --> C{发现重复?}\n    C -->|是| D[标记重复]\n    C -->|否| E{复杂度热点?}\n    E -->|是| F[标记热点]\n    E -->|否| G[分析测试覆盖]\n    D & F --> H[生成修复计划]\n    H --> I[TDD 循环]\n    I --> J{验证通过?}\n    J -->|否| K[自修复]\n    J -->|是| L[信号工具]\n    K --> I\n    L --> M[继续下一个问题]\n```\n\n**Fallback 链：**\n1. 完整 SCAN → TDD 循环 → 验证 → 信号\n2. Ollama 不可用：静态分析\n3. 无测试套件：扫描并脚手架测试\n4. 修复耗尽：回滚并记录\n\n资料来源：[skills/shadow-refactor/SKILL.md](skills/shadow-refactor/SKILL.md)\n\n## 记忆系统\n\n`qmd-memory` 提供多层次记忆管理：\n\n### 记忆类型\n\n| 类型 | 用途 | 示例 |\n|-----|------|------|\n| `fact` | 永久事实 | \"TypeScript 是主要语言\" |\n| `commitment` | 承诺事项 | \"周五前完成设置\" |\n| `decision` | 决策记录 | \"决定使用本地优先\" |\n| `preference` | 偏好设置 | \"喜欢使用 vim\" |\n| `context` | 上下文信息 | 当前会话状态 |\n\n### CLI 命令\n\n```bash\n# 存储记忆\nqmd-memory store \"内容\" --kind fact --tag work\n\n# 检索记忆\nqmd-memory recall --kind fact --limit 5\n\n# 从文本提取\nqmd-memory extract notes.md --source-id \"file:notes.md\"\n```\n\n### Profile 层\n\n| 层 | 特性 | 持久性 |\n|---|------|--------|\n| static | 永久事实（身份、偏好、工具、关系） | 长期 |\n| dynamic | 近期上下文（当前焦点、最近操作） | 会话 |\n\n资料来源：[skills/qmd-memory/SKILL.md](skills/qmd-memory/SKILL.md)\n\n## 配置与集成\n\n### Codex CLI 配置\n\n| 配置项 | 值 | 说明 |\n|-------|-----|------|\n| Model | `gpt-5.5` | reasoning effort: low |\n| Sandbox | `danger-full-access` | 完整访问权限 |\n| Approval policy | `never` | 全自动模式 |\n| Token limit | 25,000 | 工具输出限制 |\n| Features | multi_agent, memories, chronicle, js_repl, apps | 启用特性 |\n\n**Caveman 模式：**\n- 简洁智能通信风格\n- 模式：`[事物] [动作] [原因]. [下一步].`\n- 企业区例外：Astemo/Honda/fh4s 保持正常散文\n\n资料来源：[skills/codex-context/SKILL.md](skills/codex-context/SKILL.md)\n\n### MCP 服务器\n\n| 服务器 | 路径/URL |\n|--------|---------|\n| RepoPrompt | `/Users/sdluffy/RepoPrompt/repoprompt_cli` |\n| chrome_devtools | `/Users/sdluffy/bin/chrome-devtools-mcp-work` |\n| notion | `https://mcp.notion.com/mcp` |\n| openevidence | `node .../openevidence-mcp/dist/server.js` |\n| playwright | `/Users/sdluffy/bin/playwright-mcp-work` |\n\n## 专利与文档生成\n\n### 专利队列管理\n\n| 命令 | 功能 | 触发词 |\n|-----|------|--------|\n| `new` | 创建新专利草稿 | `patent new` |\n| `mine` | 挖掘发明候选 | `patent mine` |\n| `queue` | 查看候选队列 | `patent queue` |\n| `export <ID>` | Obsidian 导出 | `patent obsidian` |\n| `synthesize` | 组合概览输出 | `patent synthesize` |\n\n### LaTeX 论文生成\n\n`codex-latex` 支持多种模板：\n\n| 模板类型 | 适用场景 |\n|---------|---------|\n| IEEE Conference | 会议论文 |\n| ACM | 学术论文 |\n| Patent Specification | 专利规范 (SP-001/002/003) |\n| Engineering Report | 工程报告 |\n| Research Paper | 研究论文 |\n\n**构建流程：**\n```bash\nlatexmk -pdf paper.tex  # 自动处理多次编译\n```\n\n资料来源：[skills/codex-latex/SKILL.md](skills/codex-latex/SKILL.md)\n\n## 设计系统\n\n### 配色方案\n\n| 系统 | 主色 | 辅色 | 背景 |\n|------|------|------|------|\n| Shadow Enterprise | `#4a9eff` (蓝) | `#8b5cf6` (紫) | `#09090b` (深) |\n| Astemo/Honda | `#B6001A` (红) | Arial 字体 | 白色/浅色表面 |\n\n### 文件路由规范\n\n| 制品类型 | 存储路径 | 用途 |\n|---------|---------|------|\n| 工具信号 | `tools/integrate/tool-signals.jsonl` | 每次修复结果 |\n| 重构报告 | `ShadowArchive/80-reports/refactor-*.md` | 会话摘要 |\n| 扫描报告 | `ShadowArchive/80-reports/mesh-*.md` | 网络扫描结果 |\n| 专利草稿 | `docs/patents/SP-NNN/` | 规范、权利要求、提交指南 |\n| 专利队列 | `ShadowArchive/10-projects/patent-queue/` | 候选队列 JSON |\n\n## 总结\n\n`s4b7-ai-skills` 项目构建了一个全面的 AI Agent 技能生态系统，通过标准化技能定义、多层次记忆系统、智能路由委托和模式结晶机制，实现了跨平台的 AI 能力复用。项目的模块化设计使得各个技能可以独立演进，同时通过统一的架构规则保持整体一致性。\n\n---\n\n<a id='installation'></a>\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目概览](#overview), [技能文件结构](#skill-structure)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)\n- [distribution.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/distribution.json)\n- [scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)\n</details>\n\n# 安装指南\n\n本页面详细介绍 s4b7-ai-skills 项目的安装流程、环境配置及常见问题的解决方案。\n\n## 系统要求\n\n在开始安装之前，请确保您的系统满足以下要求：\n\n| 组件 | 最低版本 | 推荐版本 | 说明 |\n|------|----------|----------|------|\n| Node.js | 18.0.0 | 20.x LTS | 支持 ES 模块和现代 JavaScript 特性 |\n| npm | 9.0.0 | 10.x | 包管理工具 |\n| git | 2.30.0 | 最新版 | 用于版本控制和依赖拉取 |\n| 操作系统 | macOS 12+ / Ubuntu 20.04+ / Windows 10+ | - | 跨平台支持 |\n\n资料来源：[package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)\n\n## 安装方式\n\n### 方式一：npm 全局安装（推荐）\n\n使用 npm 进行全局安装是最简便的方式：\n\n```bash\nnpm install -g s4b7-ai-skills\n```\n\n安装完成后，可以通过以下命令验证：\n\n```bash\ns4b7-ai-skills --version\n```\n\n资料来源：[scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)\n\n### 方式二：本地项目安装\n\n将 s4b7-ai-skills 作为项目依赖安装：\n\n```bash\n# 创建项目目录\nmkdir my-agent-project && cd my-agent-project\n\n# 初始化 npm 项目\nnpm init -y\n\n# 安装为项目依赖\nnpm install s4b7-ai-skills\n\n# 或安装最新预发布版本\nnpm install s4b7-ai-skills@next\n```\n\n资料来源：[package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)\n\n### 方式三：从源码构建\n\n适合需要自定义或参与开发的用户：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/s4b7-ai/s4b7-ai-skills.git\ncd s4b7-ai-skills\n\n# 安装依赖\nnpm install\n\n# 构建项目\nnpm run build\n\n# 链接到全局（开发模式）\nnpm link\n```\n\n资料来源：[scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)\n\n## 安装流程图\n\n以下流程图展示了完整的安装过程：\n\n```mermaid\ngraph TD\n    A[开始安装] --> B{检查 Node.js 版本}\n    B -->|版本过低| C[升级 Node.js]\n    B -->|版本符合| D[检查 npm 版本]\n    C --> D\n    D --> E{安装方式选择}\n    E -->|全局安装| F[npm install -g]\n    E -->|本地安装| G[npm install]\n    E -->|源码构建| H[git clone + npm install]\n    F --> I[验证安装]\n    G --> I\n    H --> I\n    I --> J{验证成功?}\n    J -->|是| K[安装完成]\n    J -->|否| L[排查错误]\n    L --> I\n```\n\n## 环境配置\n\n### 配置文件位置\n\n安装后，配置文件位于用户主目录：\n\n| 平台 | 配置文件路径 |\n|------|--------------|\n| macOS/Linux | `~/.s4b7-ai-skills/config.json` |\n| Windows | `%USERPROFILE%\\.s4b7-ai-skills\\config.json` |\n\n### 基本配置\n\n创建或编辑配置文件：\n\n```json\n{\n  \"model\": \"qwen3:8b\",\n  \"ollamaEndpoint\": \"http://localhost:11434\",\n  \"skillsDirectory\": \"~/.agents/skills/\",\n  \"logLevel\": \"info\",\n  \"autoUpdate\": true\n}\n```\n\n资料来源：[distribution.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/distribution.json)\n\n### 环境变量\n\n支持通过环境变量进行配置：\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `S4B7_SKILLS_DIR` | 技能目录路径 | `~/.agents/skills/` |\n| `S4B7_MODEL` | 默认模型 | `qwen3:8b` |\n| `S4B7_OLLAMA_URL` | Ollama 服务地址 | `http://localhost:11434` |\n| `S4B7_LOG_LEVEL` | 日志级别 | `info` |\n| `S4B7_API_KEY` | API 密钥（可选） | 空 |\n\n## 依赖组件\n\n### Ollama 本地模型服务\n\ns4b7-ai-skills 优先使用本地 Ollama 模型：\n\n```bash\n# 安装 Ollama\ncurl -fsSL https://ollama.com/install.sh | sh\n\n# 拉取默认模型\nollama pull qwen3:8b\n\n# 验证 Ollama 运行状态\ncurl -s http://localhost:11434/api/tags | head -1\n```\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n### ShadowArchive 存储卷（可选）\n\n用于高级功能和技能同步：\n\n```bash\n# 确保 ShadowArchive 卷已挂载\nls /Volumes/☯Duality/\n\n# 或使用本地模式（功能受限）\nS4B7_LOCAL_MODE=true s4b7-ai-skills\n```\n\n资料来源：[skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n\n## 安装验证\n\n### 完整性检查\n\n安装完成后，运行以下命令进行验证：\n\n```bash\n# 检查 CLI 可用性\ns4b7-ai-skills --help\n\n# 检查技能加载\ns4b7-ai-skills skills list\n\n# 测试模型连接\ns4b7-ai-skills doctor\n```\n\n### 常见验证命令\n\n| 命令 | 用途 |\n|------|------|\n| `s4b7-ai-skills --version` | 显示版本号 |\n| `s4b7-ai-skills skills list` | 列出已安装的技能 |\n| `s4b7-ai-skills doctor` | 运行诊断检查 |\n| `s4b7-ai-skills update` | 检查并安装更新 |\n\n资料来源：[scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)\n\n## 技能目录结构\n\n安装后，技能目录结构如下：\n\n```\n~/.agents/skills/\n├── write-a-skill/          # 技能编写指南\n│   └── SKILL.md\n├── shadow-refactor/        # 代码重构工具\n│   └── SKILL.md\n├── qmd-memory/             # 记忆管理系统\n│   └── SKILL.md\n├── codex-latex/            # LaTeX 文档生成\n│   └── SKILL.md\n├── codex-context/          # 上下文管理\n│   └── SKILL.md\n├── ai-sdk-core/            # AI SDK 核心\n│   └── references/\n│       └── v5-breaking-changes.md\n├── multi-model-query/      # 多模型查询\n│   └── SKILL.md\n├── patent-queue/           # 专利队列管理\n│   └── SKILL.md\n├── command-center/         # 命令中心\n│   └── SKILL.md\n├── shadow-continuity/      # 连续性管理\n│   └── SKILL.md\n├── shadow-patent-factory/  # 专利工厂\n│   └── SKILL.md\n├── acp-delegate-auto/      # 自动委托\n│   └── SKILL.md\n├── shadow-engg/            # 工程辅助\n│   └── SKILL.md\n└── shadow-mcp-gadgets/     # MCP 小工具\n    └── SKILL.md\n```\n\n资料来源：[distribution.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/distribution.json)\n\n## 卸载\n\n如需卸载 s4b7-ai-skills：\n\n```bash\n# 全局卸载\nnpm uninstall -g s4b7-ai-skills\n\n# 清除配置（可选）\nrm -rf ~/.s4b7-ai-skills/\n\n# 清除链接\nnpm unlink s4b7-ai-skills\n```\n\n## 故障排除\n\n### 安装失败\n\n| 问题 | 解决方案 |\n|------|----------|\n| `EACCES` 权限错误 | 使用 sudo 或配置 npm 路径 |\n| Node.js 版本不兼容 | 升级到推荐版本 |\n| 网络超时 | 配置国内镜像：`npm config set registry https://registry.npmmirror.com` |\n\n### 运行时问题\n\n| 问题 | 诊断步骤 |\n|------|----------|\n| 技能加载失败 | 检查 `~/.agents/skills/` 目录存在性 |\n| 模型连接失败 | 确认 Ollama 服务运行：`curl http://localhost:11434` |\n| 权限不足 | 检查配置文件写入权限 |\n\n资料来源：[skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)\n\n## 更新升级\n\n### 检查更新\n\n```bash\ns4b7-ai-skills update --check\n```\n\n### 执行更新\n\n```bash\n# npm 全局更新\nnpm update -g s4b7-ai-skills\n\n# 源码更新\ngit pull origin main\nnpm run build\nnpm link\n```\n\n资料来源：[package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)\n\n---\n\n<a id='skill-structure'></a>\n\n## 技能文件结构\n\n### 相关页面\n\n相关主题：[技能分类体系](#skill-categories), [编写技能指南](#write-a-skill)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/shadow-mind/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mind/SKILL.md)\n</details>\n\n# 技能文件结构\n\n## 概述\n\n技能（Skill）是 AI Agent 系统中的可复用能力单元，用于封装特定领域的任务处理逻辑、工作流和最佳实践。技能文件结构定义了这些能力单元的标准化组织方式，确保 Agent 能够在需要时准确识别、加载并执行相应的技能。\n\n技能文件结构的核心目标是：\n\n- **可发现性**：通过标准化的描述格式，使 Agent 能够根据用户请求的关键词和上下文自动匹配最合适的技能\n- **可维护性**：提供清晰的组织规范，便于技能创建、更新和审计\n- **可组合性**：支持技能的模块化拆分和引用，便于构建复杂的任务处理流程\n- **可追溯性**：记录技能的创建来源和使用历史，支持持续优化\n\n## 技能文件基本结构\n\n### 标准目录布局\n\n```\n~/.agents/skills/<skill-name>/\n├── SKILL.md              # 主技能文件（必需）\n├── scripts/              # 工具脚本目录（可选）\n│   ├── helper.js\n│   └── validator.sh\n├── docs/                 # 文档目录（可选）\n│   ├── plans/\n│   │   └── crystallization-log.md\n│   └── reference/\n└── reference.md          # 参考文档（可选）\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:1-15]()\n\n### SKILL.md 文件结构\n\nSKILL.md 是每个技能的入口文件，必须包含以下组成部分：\n\n| 组成部分 | 必需性 | 说明 |\n|---------|-------|------|\n| YAML Frontmatter | 是 | 包含技能名称和描述 |\n| H1 标题 | 是 | 技能名称 |\n| Quick start | 是 | 最小可运行示例 |\n| Workflows | 是 | 复杂任务的步骤清单 |\n| Advanced features | 否 | 指向独立参考文件的链接 |\n\n```markdown\n---\nname: skill-name\ndescription: Brief description of capability. Use when [specific triggers].\n---\n\n# Skill Name\n\n## Quick start\n\n[Minimal working example]\n\n## Workflows\n\n[Step-by-step processes with checklists for complex tasks]\n\n## Advanced features\n\n[Link to separate files: See [REFERENCE.md](REFERENCE.md)]\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:18-32]()\n\n## YAML Frontmatter 规范\n\n### Description 字段规则\n\ndescription 字段是 Agent 在决定加载哪个技能时看到的唯一信息，它会与所有已安装技能的描述一起出现在系统提示中。因此，description 的编写质量直接影响技能的触发准确性。\n\n**格式要求**：\n\n- 最大 1024 字符\n- 使用第三人称书写\n- 第一句：描述技能提供的功能\n- 第二句：以 \"Use when...\" 开头，说明触发条件\n\n**编写示例**：\n\n```\n# 正确示例\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n```\n# 错误示例\nHelps with documents.\n```\n\n错误示例的问题在于：它没有给 Agent 提供区分该技能与其他文档技能的方式。\n\n资料来源：[skills/write-a-skill/SKILL.md:38-55]()\n\n## 技能拆分策略\n\n### 何时拆分文件\n\n当满足以下条件时，应将内容拆分到独立文件：\n\n| 条件 | 说明 |\n|------|------|\n| SKILL.md 超过 100 行 | 主文件变得难以阅读和维护 |\n| 内容具有不同领域 | 如财务和销售数据模式 |\n| 高级功能很少被使用 | 将其隔离减少日常加载开销 |\n\n### 何时添加 Scripts 目录\n\n在以下情况下，应添加 scripts/ 目录并放置工具脚本：\n\n- 操作是确定性的（验证、格式化）\n- 相同的代码会被重复生成\n- 错误需要显式处理\n\n脚本可以节省 token 消耗并提高可靠性，因为它们是经过验证的预编译代码，而非每次动态生成。\n\n资料来源：[skills/write-a-skill/SKILL.md:76-88]()\n\n## 技能分类与放置\n\n### 分类标准\n\n技能按照其适用范围进行分类：\n\n| 分类 | 路径 | 说明 |\n|------|------|------|\n| 通用模式 | `~/.agents/skills/<skill-name>/` | 适用于所有场景的通用技能 |\n| 企业特定模式 | `~/.agents/skills/` 的适当子目录 | 针对特定企业或领域的专用技能 |\n\n资料来源：[skills/crystallize/SKILL.md:112-117]()\n\n### 企业特定技能的放置\n\n企业特定技能应放置在 `~/.agents/skills/` 下的适当子目录中，遵循组织结构层级。例如：\n\n- Astemo 相关技能 → `~/.agents/skills/astemo/`\n- 特定项目相关 → `~/.agents/skills/projects/<project-name>/`\n\n## 技能创建工作流\n\n### 标准工作流图\n\n```mermaid\ngraph TD\n    A[任务完成] --> B{应该复用吗?}\n    B -->|是| C[回顾会话]\n    B -->|否| Z[完成]\n    C --> D[提取模式]\n    D --> E[检查范围]\n    E --> F{存在重叠?}\n    F -->|是| G[更新现有技能]\n    F -->|否| H[创建新技能]\n    G --> I[记录结晶化]\n    H --> I\n    I --> Z\n```\n\n### 工作流详细步骤\n\n#### 1. 回顾（Review）\n\n回答以下问题：\n\n- 任务是什么？\n- 解决了什么问题？\n- 学到了什么？\n- 下次会重复哪些步骤？\n\n#### 2. 模式提取（Pattern Extraction）\n\n识别可复用模式，包括：\n\n| 模式类型 | 说明 |\n|---------|------|\n| **关键步骤** | 产生结果的最简序列 |\n| **启发式规则** | 需要判断的决策点、经验法则 |\n| **常见错误** | 什么出了问题或差点出问题、哪些假设失败 |\n| **决策点** | 在哪里选择了不同方法、什么决定了选择 |\n\n资料来源：[skills/crystallize/SKILL.md:78-96]()\n\n#### 3. 探索模式扩展\n\n当操作者请求\"更多结晶化\"或引用 `--exploratory-mode` 时，不要止步于第一个本地修复。应向外扩展一圈，检查相邻表面是否存在相同的过时假设。\n\n扩展检查范围：\n\n1. 从刚修复的确切内容开始\n2. 检查可能携带相同过时假设的最近相邻表面\n\n资料来源：[skills/crystallize/SKILL.md:98-112]()\n\n## 结晶化模式与模式\n\n### 结晶化与 SP-006 的关系\n\nSP-006（潜在技能观察器）从工具调用序列自动检测模式。结晶化技能通过从推理中有意提取模式来补充 SP-006——这些模式源自对问题的理解，而不仅仅是观察工具使用。两种机制向相同的技能命名空间提供输入。\n\n资料来源：[skills/crystallize/SKILL.md:119-125]()\n\n### 结晶化模式\n\n| 模式 | 输出 | 触发场景 |\n|------|------|---------|\n| `default` | 完整结晶化：回顾→提取→范围→去重→创建/更新 | `crystallize`, `capture this as a skill` |\n| `quick` | 快速捕获到最小技能存根（后续完善） | `quick crystallize`, 任务中模式发现 |\n| `exploratory` | 从修复向外扩展一圈；检查相邻表面 | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | 由操作者挫败感触发的即时结晶化 | `this took too long`, `why aren't you using...` |\n| `correction` | 由操作者更正触发的即时更新 | 操作者更正身份/路径/边界 |\n| `audit` | 检查应该结晶化但没有的内容 | `what patterns did we miss` |\n\n资料来源：[skills/crystallize/SKILL.md:127-142]()\n\n## 技能路由机制\n\n### 关键词检测路由\n\nAgent 可以根据提示中的关键词自动路由到合适的技能：\n\n| 提示包含... | 路由到 |\n|-----------|-------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| `file paths`, `diffs`, `PRs` | codex |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md:45-59]()\n\n### 描述触发机制\n\n技能的 description 字段是 Agent 决策加载哪个技能的主要依据。Agent 读取所有已安装技能的描述，然后根据用户的请求选择最相关的技能。\n\n**触发检测要素**：\n\n1. 功能能力 - 技能提供什么功能\n2. 触发关键词 - 具体何时/为什么使用\n3. 文件类型关联 - 与哪些文件类型相关\n\n## 技能审计与验证\n\n### 技能审查清单\n\n创建或更新技能后，验证以下要点：\n\n- [ ] description 包含触发条件（\"Use when...\"）\n- [ ] SKILL.md 不超过 100 行\n- [ ] 没有时间敏感信息\n- [ ] 术语一致\n- [ ] 包含具体示例\n- [ ] 引用深度仅一层（避免深层嵌套引用）\n\n资料来源：[skills/write-a-skill/SKILL.md:92-100]()\n\n### 技能手术规则\n\n技能审计和研究开发（Skill Surgery R&D）遵循以下规则：\n\n| 规则 | 说明 |\n|------|------|\n| **不删除规则** | 在探索性手术期间不删除技能，先重定向；删除需要操作者明确批准 |\n| **不编辑历史** | 除非仍作为活跃触发问题出现，否则不编辑已归档历史 |\n| **不创建巨型集合技能** | 优先创建一个规范路由器加专注子技能 |\n| **先研究后创造** | 未经验证不结晶过时版本号、价格或 API 形状 |\n| **保留边界** | 整合 Astemo/企业技能时保留特定操作者边界 |\n| **外部化规则** | 所有手术报告进入报告目录，而非嵌入技能文件 |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:25-36]()\n\n### 错误处理\n\n| 故障场景 | 恢复策略 |\n|---------|---------|\n| 脚本执行失败（语法错误） | 运行手动 `find + grep` 清单；在报告中记录脚本失败 |\n| 技能文件 YAML frontmatter 格式错误 | 标记在清单中；不自动修复；建议手动修复 |\n| 检测到循环重定向（A → B → A） | 阻止重定向；报告循环；需要手动解决 |\n| 合并目标有冲突的 gotchas | 保留两组 gotchas；标记供操作者审查 |\n| 技能数量过多（>500） | 优先活跃+非废弃的；抽样检查归档以进行陈旧车道检查 |\n| 技能目录权限被拒绝 | 报告；跳过；仅审计可访问的目录 |\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:38-50]()\n\n## 人工制品路由\n\n每个技能生成的人工制品按照标准化路径存储：\n\n| 人工制品类型 | 路径 | 用途 |\n|------------|------|------|\n| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |\n| 更新技能 | 现有技能相同路径 | 扩展能力 |\n| 结晶化日志 | `docs/plans/crystallization-log.md` | 历史记录（可选） |\n| 企业特定技能 | `~/.agents/skills/` 适当子目录 | 领域范围能力 |\n\n资料来源：[skills/crystallize/SKILL.md:145-153]()\n\n## 技能与记忆系统集成\n\n### 上下文保存流程\n\n在每次产生决策或发现的会话后：\n\n1. 将会话锚点写入 `ShadowArchive/80-reports/`\n2. 将关键决策追加到 `.shadow-kernel/esp-context.md` 的相应主题下\n3. 如果发现模式 → 结晶化到技能\n4. 如果是项目特定的 → 写入 `<program>/90_Astemo_Config/session-log.jsonl`\n\n资料来源：[skills/shadow-mind/SKILL.md:55-60]()\n\n### 记忆召回置信度\n\n| 置信度级别 | 含义 | 来源 |\n|-----------|------|------|\n| **Confirmed** | 在持久人工制品中找到（锚点、内核、Dropbox） | 文件匹配 |\n| **Likely** | 在训练对或提炼经验中找到 | 模式匹配 |\n| **Inferred** | 从上下文重构但无明确人工制品 | 推理 |\n| **Unknown** | 未找到证据 | 无匹配 |\n\n必须始终标注召回置信度。永远不要将推断的召回呈现为已确认的。\n\n资料来源：[skills/shadow-mind/SKILL.md:62-70]()\n\n## 完整技能示例\n\n### 示例：crystallize 技能结构\n\n```markdown\n---\nname: crystallize\ndescription: Extract reusable patterns from problem-solving sessions into structured skills. Use when finishing a complex task that might recur, or when explicitly asked to capture a pattern.\n---\n\n# Crystallize\n\nOne-line description. Use when [trigger phrases].\n\n## When to Use\n- [trigger 1]\n- [trigger 2]\n- [trigger 3]\n\n## Workflow\n1. [Step 1]\n2. [Step 2]\n3. [Step 3]\n\n## Key Decisions\n- [Decision point 1]: [default choice + why]\n- [Decision point 2]: [default choice + why]\n\n## Gotchas\n- [Common mistake 1]\n- [Common mistake 2]\n\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n```\n\n资料来源：[skills/crystallize/SKILL.md:20-43]()\n\n## 最佳实践总结\n\n### 技能设计原则\n\n1. **简洁性优先**：保持 SKILL.md 在 100 行以内\n2. **描述精确化**：description 必须包含具体触发条件\n3. **示例具体化**：包含最小可运行示例而非抽象描述\n4. **分层设计**：高级内容通过引用独立文件实现\n5. **模式优先**：将确定性操作提取为脚本\n\n### 避免的反模式\n\n| 反模式 | 问题 | 替代方案 |\n|-------|------|---------|\n| 模糊描述 | Agent 无法区分技能 | 包含具体触发关键词 |\n| 巨型单文件 | 难以维护 | 拆分到 reference.md |\n| 时间敏感信息 | 信息快速过时 | 避免版本号、价格等 |\n| 深层嵌套引用 | 增加加载复杂度 | 限制引用深度为一层 |\n\n### 持续改进流程\n\n技能文件结构是一个持续迭代的系统：\n\n```mermaid\ngraph LR\n    A[创建技能] --> B[使用验证]\n    B --> C{效果如何?}\n    C -->|良好| D[归档最佳实践]\n    C -->|需改进| E[识别问题]\n    E --> F{范围局限?}\n    F -->|是| G[探索性扩展]\n    F -->|否| H[局部优化]\n    G --> A\n    H --> A\n    D --> I[技能库成熟]\n```\n\n通过遵循本文档定义的技能文件结构规范，可以构建一个可维护、可发现、可组合的技能生态系统，使 AI Agent 能够高效地处理各类复杂任务。\n\n---\n\n<a id='skill-categories'></a>\n\n## 技能分类体系\n\n### 相关页面\n\n相关主题：[LangGraph Agent技能](#langgraph-agent), [编写技能指南](#write-a-skill), [模型身份管理](#model-identity)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n- [skills/command-center/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/command-center/SKILL.md)\n</details>\n\n# 技能分类体系\n\n## 概述\n\n技能分类体系（Skill Taxonomy）是 s4b7-ai-skills 项目中的核心架构概念，旨在对 AI Agent 的技能（Skills）进行系统化组织、标准化定义和自动化路由。该体系通过统一的模板结构、关键词触发机制和层级分类，实现了对复杂任务处理的精准匹配与高效执行。\n\n技能分类体系的核心目标包括：\n\n- 为 Agent 提供清晰的技能选择依据\n- 实现任务到技能的自然映射\n- 支持技能的持续迭代与模式提取\n- 提供完善的回退机制确保系统韧性\n\n资料来源：[write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n---\n\n## 技能分类层级\n\n技能体系按照功能域和触发场景分为多个层级，每个层级承担不同的职责：\n\n### 按功能域分类\n\n```mermaid\ngraph TD\n    A[技能分类体系] --> B[核心能力类]\n    A --> C[业务领域类]\n    A --> D[工具集成类]\n    A --> E[推理决策类]\n    \n    B --> B1[write-a-skill]\n    B --> B2[crystallize]\n    B --> B3[multi-model-query]\n    \n    C --> C1[command-center]\n    C --> C2[patent-queue]\n    C --> C3[shadow-patent-factory]\n    \n    D --> D1[shadow-mcp-gadgets]\n    D --> D2[acp-delegate-auto]\n    D --> D3[codex-context]\n    \n    E --> E1[codex-policy-steering]\n    E --> E2[shadow-refactor]\n```\n\n### 技能功能域对照表\n\n| 类别 | 描述 | 代表技能 |\n|------|------|----------|\n| 核心能力类 | 技能开发、模式提取、知识合成的基础能力 | write-a-skill, crystallize, multi-model-query |\n| 业务领域类 | 特定业务场景的垂直能力 | command-center, patent-queue, shadow-engg |\n| 工具集成类 | 与外部系统、API、MCP 服务集成的技能 | shadow-mcp-gadgets, acp-delegate-auto |\n| 推理决策类 | 策略分析、代码推理、上下文理解 | codex-policy-steering, shadow-refactor |\n\n资料来源：[crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n---\n\n## 技能模板规范\n\n所有技能遵循统一的 SKILL.md 模板规范，确保一致性和可维护性：\n\n### 标准化模板结构\n\n```markdown\n---\nname: skill-name\ndescription: 技能描述. Use when [触发关键词].\n---\n\n# 技能名称\n\n## 快速开始\n[最小工作示例]\n\n## 工作流\n[带检查清单的逐步流程]\n\n## 高级特性\n[链接到独立文件]\n```\n\n### 描述字段规范\n\n技能描述是 Agent 选择技能时的唯一依据，编写规范如下：\n\n| 要求 | 说明 |\n|------|------|\n| 字符限制 | 最多 1024 个字符 |\n| 人称 | 使用第三人称 |\n| 格式 | 首句描述功能，次句描述触发条件 |\n| 触发词 | 必须包含 \"Use when\" 引导的触发场景 |\n\n**规范示例**：\n```\nExtract text and tables from PDF files, fill forms, merge documents. \nUse when working with PDF files or when user mentions PDFs, forms, \nor document extraction.\n```\n\n**不规范示例**：\n```\nHelps with documents.\n```\n\n资料来源：[write-a-skill/SKILL.md:32-52](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n---\n\n## 关键词路由机制\n\n### 路由决策流程\n\n技能分类体系通过关键词匹配实现任务的自动路由：\n\n```mermaid\ngraph TD\n    A[用户请求] --> B{关键词检测}\n    B -->|write/implement/refactor/debug| C[codex]\n    B -->|research/summarize/find/compare| D[gemini]\n    B -->|translate/JP/Japanese| E[Codex]\n    B -->|local/private/no cloud| F[ollama]\n    B -->|review/architect/design| G[Codex]\n    B -->|quickly/fast/brief| H[ollama]\n    B -->|file paths/diffs/PRs| I[codex]\n    \n    C --> J[执行目标技能]\n    D --> J\n    E --> J\n    F --> J\n    G --> J\n    H --> J\n    I --> J\n```\n\n### 关键词与技能映射表\n\n| 请求关键词 | 路由目标 |\n|------------|----------|\n| `write`, `implement`, `refactor`, `debug code` | codex |\n| `research`, `summarize`, `find`, `compare` | gemini |\n| `translate`, `JP`, `Japanese` | Codex |\n| `local`, `private`, `no cloud` | ollama |\n| `review`, `architect`, `design` | Codex |\n| `quickly`, `fast`, `brief` | ollama |\n| 文件路径, diffs, PRs | codex |\n\n资料来源：[acp-delegate-auto/SKILL.md:1-24](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n---\n\n## 技能触发与工作流\n\n### 触发模式分类\n\n技能根据触发场景分为不同的工作模式：\n\n```mermaid\ngraph LR\n    A[触发源] --> B{技能类型}\n    \n    B --> C[显式触发]\n    B --> D[隐式触发]\n    B --> E[模式检测]\n    \n    C --> C1[关键词匹配]\n    C --> C2[命令调用]\n    \n    D --> D1[上下文推断]\n    D --> D2[记忆关联]\n    \n    E --> E1[SP-006 观察]\n    E --> E2[行为序列分析]\n```\n\n### shadow-refactor 技能工作流\n\nshadow-refactor 是技能体系中的代码推理专家，其工作流程如下：\n\n```mermaid\ngraph TD\n    A[启动 refactor] --> B[执行 SCAN]\n    B --> C{发现问题?}\n    C -->|是| D[创建 TDD 循环]\n    C -->|否| E[equilibrium 模式]\n    \n    D --> F[编写测试]\n    F --> G[执行修复]\n    G --> H{测试通过?}\n    H -->|是| I[verify 验证]\n    H -->|否| J[自修复尝试]\n    J --> K{尝试次数<3?}\n    K -->|是| G\n    K -->|否| L[回滚更改]\n    \n    I --> M[signal 工具信号]\n    M --> N[下一个问题]\n    N --> C\n    \n    E --> O[报告当前状态]\n```\n\n### 代码分析检查项\n\n| 检查类型 | 方法 | 工具/命令 |\n|----------|------|----------|\n| 导入一致性 | `import-sort | sort` 对比 | grep -rn |\n| 重复代码检测 | 3+ 行相同的代码块 | 跨文件比对 |\n| 复杂度热点 | 函数>50行、文件>500行 | AST 分析 |\n| 测试覆盖缺口 | 源文件无对应测试 | 文件匹配扫描 |\n\n资料来源：[shadow-refactor/SKILL.md:1-40](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n\n---\n\n## MCP 工具分类\n\nMCP（Model Context Protocol）工具通过 Gadget 技能进行统一封装：\n\n### Gadget 工具映射表\n\n| 触发模式 | Gadget | 功能 | 使用示例 |\n|----------|--------|------|----------|\n| `memory` | ARC | 记忆存储与检索 | `arc.store`, `arc.search` |\n| `context` | ESP | 统一上下文组装 | `esp.assemble`, `/renew-ctx` |\n| `mesh` | ANT | 网格健康监控 | `ant.mesh` |\n| `browser` | TAP | Chrome 标签页+JS执行 | `tap.tabs`, `tap.execute` |\n| `ambient` | OWL | Bee AI 信息提取 | `owl.brief`, `owl.extract` |\n| `voice` | ORB | macOS TTS | `orb.say`, `orb.voices` |\n| `environment` | DEN | 物理传感器 | `den.environment` |\n| `patent` | Factory | 专利流水线 | `factory.new`, `factory.draft` |\n\n资料来源：[shadow-mcp-gadgets/SKILL.md:1-20](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n\n---\n\n## 模式提取与技能结晶\n\n### 技能结晶工作流\n\n技能可通过两种途径产生：\n\n```mermaid\ngraph TD\n    A[技能来源] --> B{产生方式}\n    \n    B --> C[主动结晶]\n    B --> D[自动检测]\n    \n    C --> C1[理解问题本质]\n    C1 --> C2[识别模式]\n    C2 --> C3[编写 SKILL.md]\n    C3 --> C4[记录元数据]\n    \n    D --> D1[SP-006 观察]\n    D1 --> D2[行为序列分析]\n    D2 --> D3[模式归档]\n```\n\n### 结晶元数据记录\n\n每个技能底部应记录结晶来源：\n\n```markdown\n## Crystallized From\n- Session: [日期/上下文]\n- Original task: [解决的问题]\n- What pattern was extracted: [提取的模式]\n- Adjacent surfaces checked: [检查的相邻表面]\n- Surfaces intentionally left untouched: [故意不触碰的表面]\n```\n\n### 与 SP-006 的关系\n\n- **SP-006**（潜在技能观察器）：自动检测工具调用序列中的模式\n- **crystallize 技能**：通过理解问题本质进行主动模式提取\n\n两者互为补充，共同充实技能命名空间。\n\n资料来源：[crystallize/SKILL.md:1-60](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n---\n\n## 回退机制\n\n技能体系设计了完善的回退链，确保系统在各种异常情况下仍能提供能力：\n\n### 通用回退原则\n\n| 优先级 | 场景 | 回退行为 |\n|--------|------|----------|\n| 1 | 主服务可用 | 执行完整功能 |\n| 2 | 服务不可用 | 使用本地替代方案 |\n| 3 | 依赖缺失 | 降级到简化模式 |\n| 4 | 完全失败 | 生成报告并说明限制 |\n\n### shadow-refactor 回退链\n\n1. **主要路径**：完整 SCAN → TDD 循环 → verify → signal → 下一问题\n2. **Ollama 不可用**：仅使用静态分析（grep、AST、文件指标）\n3. **测试套件未找到**：扫描测试文件；如不存在，先生成最小测试结构\n4. **自修复耗尽 3 次尝试**：回滚该问题的所有更改；记录为不可恢复；继续下一问题\n5. **后台代理不可用**：以内联方式运行（阻塞用户）；报告后台模式不可用\n6. **最后手段**：报告问题而不修复；生成仅扫描输出\n\n### shadow-mcp-gadgets 回退链\n\n1. **主要**：通过 MCP 协议连接到 shadow-mcp 联邦服务器\n2. **MCP 服务器未运行**：通过 `bun run` 启动服务\n3. **后续回退**：根据各 Gadget 类型确定具体降级策略\n\n资料来源：[shadow-refactor/SKILL.md:50-60](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md), [shadow-mcp-gadgets/SKILL.md:25-35](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n\n---\n\n## 制品路由\n\n技能执行后的输出通过标准化的路径进行路由：\n\n### 制品路径规范\n\n| 制品类型 | 路径 | 用途 |\n|----------|------|------|\n| 工具信号 | `tools/integrate/tool-signals.jsonl` | 每次修复的 JSONL 结果 |\n| 重构报告 | `ShadowArchive/80-reports/refactor-<target>-YYYY-MM-DD.md` | 会话摘要 |\n| 记忆存储 | ARC 记忆存储（gadget 管理） | 持久化 Agent 记忆 |\n| 上下文状态 | ESP 程序集输出（会话范围） | 当前会话的统一上下文 |\n| 专利草案 | `docs/patents/` | 归档轨道草案 |\n| 技能开发 | `~/.agents/skills/<skill-name>/` | 通用模式 |\n| 企业技能 | `~/.agents/skills/<category>/` | 企业特定模式 |\n\n资料来源：[shadow-refactor/SKILL.md:45-50](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md), [crystallize/SKILL.md:70-75](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n\n---\n\n## 技能开发检查清单\n\n创建新技能时应遵循以下检查流程：\n\n### 编写检查项\n\n| 检查项 | 状态 |\n|--------|------|\n| 描述包含触发词（\"Use when...\"） | ☐ |\n| SKILL.md 控制在 100 行以内 | ☐ |\n| 无时间敏感信息 | ☐ |\n| 术语一致性 | ☐ |\n| 包含具体示例 | ☐ |\n| 引用层级深度不超过 1 层 | ☐ |\n\n### 文件拆分原则\n\n在以下情况下应拆分为独立文件：\n\n- SKILL.md 超过 100 行\n- 内容具有不同领域（如财务 vs 销售模式）\n- 高级特性很少需要\n\n### 脚本添加原则\n\n在以下情况下应添加脚本：\n\n- 操作是确定性的（验证、格式化）\n- 相同代码会被重复生成\n- 需要明确的错误处理\n\n资料来源：[write-a-skill/SKILL.md:90-120](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n\n---\n\n## 总结\n\n技能分类体系是 s4b7-ai-skills 项目的核心组织框架，通过以下机制实现高效的任务处理：\n\n1. **统一模板**：所有技能遵循标准化 SKILL.md 格式\n2. **关键词路由**：基于触发词的任务自动分发\n3. **Gadget 封装**：MCP 工具通过统一接口暴露\n4. **模式结晶**：支持主动和自动两种技能生成方式\n5. **回退机制**：确保系统在各种异常情况下的韧性\n6. **制品路由**：标准化的输出路径管理\n\n该体系使 Agent 能够根据用户请求的语义自动选择最合适的技能，同时保持良好的可扩展性和维护性。\n\n---\n\n<a id='langgraph-agent'></a>\n\n## LangGraph Agent技能\n\n### 相关页面\n\n相关主题：[AI SDK Core技能](#ai-sdk-core), [Agent-Cryst技能](#agent-cryst)\n\nError with Openai API: Error code: 429 - {'type': 'error', 'error': {'type': 'rate_limit_error', 'message': 'Token Plan 主要面向个人开发者的交互式使用场景。当前请求量较高，请稍后重试；如需支持更高并发或自动化任务，建议升级至更高级别套餐，或使用按量付费 API。 (2062)', 'http_code': '429'}, 'request_id': '0654e2052901c7e32982c8a82663eaab'}\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n<a id='ai-sdk-core'></a>\n\n## AI SDK Core技能\n\n### 相关页面\n\n相关主题：[LangGraph Agent技能](#langgraph-agent)\n\nError with Openai API: Error code: 429 - {'type': 'error', 'error': {'type': 'rate_limit_error', 'message': 'Token Plan 主要面向个人开发者的交互式使用场景。当前请求量较高，请稍后重试；如需支持更高并发或自动化任务，建议升级至更高级别套餐，或使用按量付费 API。 (2062)', 'http_code': '429'}, 'request_id': '0654e20df587a09b65b212207d578114'}\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n<a id='agent-cryst'></a>\n\n## Agent-Cryst技能\n\n### 相关页面\n\n相关主题：[Crystallize技能](#crystallize)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)\n- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)\n</details>\n\n# Agent-Cryst技能\n\n## 概述\n\nAgent-Cryst（代理结晶）是一种将智能体工作过程中的知识、工作流程和决策模式进行结构化提取、沉淀并复用的技能体系。其核心理念是将隐性的解决问题的方法转化为显性的、可存储的、可复用的技能资产。\n\n这一技能与 SP-006（潜在技能观察器）形成互补关系：SP-006 自动检测工具调用序列中的模式，而 Agent-Cryst 则专注于从推理过程中主动提取有意义的模式。这两种机制共同为智能体提供持续学习和能力扩展的能力。\n\n## 核心概念\n\n### 什么是\"结晶\"（Crystallization）\n\n\"结晶\"是将会话中产生的有价值的工作模式提取为标准化技能的过程。这个过程不仅捕获工具使用的序列，更关注捕获理解问题和解决问题的思维过程。\n\n资料来源：[skills/crystallize/SKILL.md:1-30]()\n\n### 与其他模式的关系\n\nAgent-Cryst 与智能体生态中的多个组件相互协作：\n\n| 组件 | 关系 | 作用 |\n|------|------|------|\n| SP-006 | 互补 | 自动观察工具调用序列，检测潜在模式 |\n| 记忆系统 | 下游 | 结晶后的技能存储到持久化记忆 |\n| 技能注册表 | 目标 | 结晶产物成为可索引的技能条目 |\n| MCP工具 | 扩展 | 通过MCP协议实现技能的分布式调用 |\n\n资料来源：[skills/crystallize/SKILL.md:70-85]()\n\n## 结晶工作流\n\n### 标准流程（default模式）\n\n```mermaid\ngraph TD\n    A[任务完成] --> B{应该复用吗?}\n    B -->|是| C[回顾会话]\n    B -->|否| Z[完成]\n    C --> D[提取模式]\n    D --> E{检查范围}\n    E --> F[搜索现有技能]\n    F --> G{发现重叠?}\n    G -->|是| H[更新现有技能]\n    G -->|否| I[创建新技能]\n    H --> J[记录结晶日志]\n    I --> J\n```\n\n标准流程包含以下步骤：\n\n1. **回顾（Review）**：明确任务、解决的问题、学到的内容，以及需要重复的步骤\n2. **模式提取（Pattern Extraction）**：识别可复用的模式，包括关键步骤、启发式规则、陷阱和决策点\n3. **范围检查（Scope Check）**：确定结晶产物的适用边界\n4. **去重检查（Deduplication）**：搜索现有技能，避免重复创建\n5. **创建/更新技能**：生成新的技能文件或更新现有技能\n6. **记录结晶日志**：保存元数据到技能文件的 `## Crystallized From` 部分\n\n资料来源：[skills/crystallize/SKILL.md:40-70]()\n\n### 快速模式（quick模式）\n\n当需要在任务中途快速捕获发现的模式时使用此模式，输出为最小化的技能存根，后续再进行完整优化：\n\n| 模式 | 输出 | 触发词 |\n|------|------|--------|\n| `default` | 完整结晶流程 | `crystallize`, `capture this as a skill` |\n| `quick` | 最小技能存根 | `quick crystallize`, 任务中模式发现 |\n| `exploratory` | 向外扩展一圈，检查相邻表面 | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | 立即结晶 | `this took too long`, `why aren't you...` |\n| `correction` | 立即更新 | 操作员修正时 |\n| `audit` | 检查遗漏的模式 | `what patterns did we miss` |\n\n资料来源：[skills/crystallize/SKILL.md:50-65]()\n\n## 模式提取方法论\n\n### 关键步骤提取\n\n最小化产生结果所需的动作序列。通过分析会话中的决策点，识别哪些步骤是必须的，哪些是可选的。\n\n### 启发式规则识别\n\n在判断过程中产生的经验规则。例如：\n- \"当遇到 X 类型错误时，首先检查 Y 配置\"\n- \"对于 A 类任务，使用 B 工具比 C 工具更高效\"\n\n### 陷阱记录\n\n记录容易出错的地方和失败假设：\n- 什么操作导致问题或差点导致问题\n- 哪些假设在实际执行中失败了\n- 环境或上下文的特殊依赖条件\n\n### 决策点文档化\n\n记录选择过程：\n- 在哪个环节做出了选择？\n- 选择的原因是什么？\n- 替代方案有哪些，为什么没有选择？\n\n资料来源：[skills/crystallize/SKILL.md:30-40]()\n\n## 探索模式扩展\n\n当使用探索模式时，结晶过程会向外扩展一圈，检查可能携带相同陈旧假设的相邻表面。\n\n扩展检查范围：\n1. 从精确修复的问题开始\n2. 检查最近的相邻表面\n3. 识别可能携带相同问题的其他区域\n4. 捕获更广泛的复用规则\n\n```mermaid\ngraph TD\n    A[精确修复] --> B[检查相邻表面]\n    B --> C{发现相同问题?}\n    C -->|是| D[扩展修复范围]\n    C -->|否| E[记录该区域安全]\n    D --> F[捕获广泛规则]\n    E --> G[继续检查下一个表面]\n    F --> G\n```\n\n资料来源：[skills/crystallize/SKILL.md:45-50]()\n\n## 技能结构规范\n\n### 技能文件模板\n\n```markdown\n# Skill Name\n\nOne-line description. Use when [trigger phrases].\n\n## When to Use\n- [trigger 1]\n- [trigger 2]\n- [trigger 3]\n\n## Workflow\n1. [Step 1]\n2. [Step 2]\n3. [Step 3]\n\n## Key Decisions\n- [Decision point 1]: [default choice + why]\n- [Decision point 2]: [default choice + why]\n\n## Gotchas\n- [Common mistake 1]\n- [Common mistake 2]\n\n## Crystallized From\n- Session: [date/context]\n- Original task: [what was being solved]\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:1-20]()\n\n### 描述规范\n\n技能描述是智能体决定加载哪个技能时看到的唯一信息，必须清晰准确：\n\n| 要求 | 说明 |\n|------|------|\n| 最大长度 | 1024字符 |\n| 视角 | 第三人称 |\n| 第一句 | 功能描述 |\n| 第二句 | 触发条件（Use when...） |\n\n**良好示例：**\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n**不良示例：**\n```\nHelps with documents.\n```\n\n资料来源：[skills/write-a-skill/SKILL.md:30-50]()\n\n### 文件拆分原则\n\n| 条件 | 行动 |\n|------|------|\n| SKILL.md 超过 100 行 | 拆分为多个文件 |\n| 内容跨越不同领域 | 拆分为独立文件 |\n| 高级功能很少使用 | 分离到 REFERENCE.md |\n\n资料来源：[skills/write-a-skill/SKILL.md:60-70]()\n\n### 脚本添加原则\n\n以下情况应添加工具脚本：\n- 操作是确定性的（验证、格式化）\n- 相同代码会被重复生成\n- 错误需要显式处理\n\n脚本可以节省 token 消耗并提高可靠性。\n\n资料来源：[skills/write-a-skill/SKILL.md:55-60]()\n\n## 产物路由\n\n### 结晶产物存储\n\n| 产物类型 | 路径 | 用途 |\n|----------|------|------|\n| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |\n| 更新技能 | 现有技能相同路径 | 扩展能力 |\n| 结晶日志 | `docs/plans/crystallization-log.md` | 历史记录（可选） |\n\n### 企业级技能\n\n对于特定企业场景的模式，应放在适当的企业子目录下：\n\n```\n~/.agents/skills/<enterprise>/<skill-name>/\n```\n\n资料来源：[skills/crystallize/SKILL.md:60-65]()\n\n## 记忆系统集成\n\n### 记忆提取流程\n\nAgent-Cryst 与 qmd-memory 系统集成，支持从会话内容中提取知识：\n\n```bash\n# 从文件提取\nqmd-memory extract notes.md --source-id \"file:notes.md\"\n\n# 从标准输入提取（如 Bee 对话）\nbee conversations get <id> --json | jq -r '.summary' | qmd-memory extract - --source-id \"bee:conv:<id>\"\n\n# 干运行（预览将要提取的内容）\nqmd-memory extract notes.md --dry-run\n```\n\n### 记忆类型\n\n| 类型 | 用途 | 示例 |\n|------|------|------|\n| `fact` | 事实性知识 | \"TypeScript 是主要语言\" |\n| `commitment` | 承诺事项 | \"周五前完成设置\" |\n| `decision` | 决策记录 | \"决定使用本地优先方案\" |\n| `preference` | 偏好设置 | \"喜欢使用 vim\" |\n| `context` | 上下文信息 | \"当前聚焦 bee 设置\" |\n\n资料来源：[skills/qmd-memory/SKILL.md:1-30]()\n\n## MCP工具集成\n\n### Shadow MCP架构\n\nAgent-Cryst 通过 MCP 协议与各种工具集成：\n\n```mermaid\ngraph TD\n    A[Agent] --> B[Shadow MCP Federation]\n    B --> C[ARC 记忆存储]\n    B --> D[ESP 上下文组装]\n    B --> E[ANT 网格健康]\n    B --> F[TAP 浏览器控制]\n    B --> G[OWL 环境信息]\n    B --> H[ORB 语音输出]\n    B --> I[Factory 专利流水线]\n```\n\n| 触发词 | 工具 | 功能 |\n|--------|------|------|\n| `arc.store`, `arc.search` | ARC | 记忆存储和检索 |\n| `esp.assemble`, `/renew-ctx` | ESP | 统一上下文组装 |\n| `ant.mesh` | ANT | 网格健康状态 |\n| `tap.tabs`, `tap.execute` | TAP | Chrome 标签页控制 |\n| `owl.brief`, `owl.extract` | OWL | 环境信息提取 |\n| `orb.say`, `orb.voices` | ORB | macOS TTS 语音输出 |\n\n资料来源：[skills/shadow-mcp-gadgets/SKILL.md:1-30]()\n\n## 重构与模式检测\n\n### 模式提取分析\n\nAgent-Cryst 可以与 shadow-refactor 技能协作，通过多种方式进行模式检测：\n\n| 方法 | 说明 | 适用场景 |\n|------|------|----------|\n| 重复代码检测 | 查找 3 行以上相同的代码块 | 发现复制粘贴模式 |\n| 复杂度热点 | 函数超过 50 行、文件超过 500 行 | 识别需要重构的区域 |\n| AST 分析 | 抽象语法树分析 | 深度代码结构检查 |\n| 本地 LLM 辅助 | 使用 Ollama 进行模式分析 | 当 Ollama 可用时 |\n\n### 本地 LLM 模式分析\n\n当 Ollama 服务可用时，可以使用 qwen3:8b 等模型进行智能模式检测：\n\n```python\nimport httpx\nresp = httpx.post(\"http://localhost:11434/api/generate\", json={\n    \"model\": \"qwen3:8b\",\n    \"prompt\": f\"Analyze this code for refactoring opportunities. Be specific:\\n\\n{code}\",\n    \"stream\": False,\n})\nsuggestions = resp.json()[\"response\"]\n```\n\n当 Ollama 不可用时，使用静态分析方法（grep、AST、文件指标）。\n\n资料来源：[skills/shadow-refactor/SKILL.md:20-45]()\n\n## 回退链\n\nAgent-Cryst 技能实现了完整的回退链，确保在各种环境条件下都能正常工作：\n\n| 优先级 | 条件 | 行为 |\n|--------|------|------|\n| 1 | MCP 服务器可用 | 使用 Shadow MCP 联合服务器 |\n| 2 | MCP 服务器未运行 | 通过 `bun run` 启动服务 |\n| 3 | Ollama 可用 | 启用智能模式分析 |\n| 4 | Ollama 不可用 | 纯静态分析 |\n| 5 | 记忆系统可用 | 存储到 ARC 记忆 |\n| 6 | 记忆系统不可用 | 降级到文件存储 |\n\n资料来源：[skills/shadow-mcp-gadgets/SKILL.md:45-55]()\n\n## 审查清单\n\n创建或更新技能后，应验证以下项目：\n\n| 检查项 | 说明 |\n|--------|------|\n| 描述包含触发词 | 必须包含 \"Use when...\" 部分 |\n| SKILL.md 行数 | 应在 100 行以内 |\n| 无时间敏感信息 | 避免使用具体日期或临时状态 |\n| 术语一致性 | 与其他技能保持统一术语 |\n| 包含具体示例 | 提供可运行的示例代码 |\n| 引用深度一级 | 相关文件使用相对路径引用 |\n\n资料来源：[skills/write-a-skill/SKILL.md:75-85]()\n\n## 最佳实践\n\n### 何时使用结晶\n\n- 工作流程是确定性的且会重复\n- 相同的代码会被反复生成\n- 错误需要显式处理和预防\n- 存在需要记录的重要决策点\n\n### 何时避免结晶\n\n- 工作流是一次性的\n- 存在太多例外情况无法标准化\n- 结晶成本超过复用收益\n\n### 结晶质量标准\n\n1. **可执行性**：技能描述的步骤应能直接执行\n2. **边界清晰**：明确技能的适用范围和限制\n3. **自包含**：技能应包含所有必要的上下文\n4. **可发现**：描述和触发词应便于智能体检索\n\n## 总结\n\nAgent-Cryst 技能是智能体能力持续演进的核心机制。通过系统化的知识结晶过程，智能体能够：\n\n- 将会话中获得的经验转化为可复用资产\n- 建立与 SP-006 的互补关系，实现主动和被动模式检测\n- 通过 MCP 工具集成实现分布式能力扩展\n- 与记忆系统深度集成，支持知识的持久化和检索\n\n这一技能遵循\"边做边学\"的原则，确保每次有价值的交互都能成为未来工作的基础。\n\n---\n\n<a id='write-a-skill'></a>\n\n## 编写技能指南\n\n### 相关页面\n\n相关主题：[Crystallize技能](#crystallize)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)\n</details>\n\n# 编写技能指南\n\n本指南介绍如何在 s4b7-ai-skills 项目中创建、编写和维护技能（Skill）。技能是模块化的能力单元， agents 可以根据任务需求动态加载和使用。\n\n## 概述\n\n技能（Skill）是一种结构化的知识封装形式，用于将重复性任务的执行模式固化为可复用的指南。每个技能通常包含以下组成部分：\n\n| 组成部分 | 说明 |\n|---------|------|\n| `SKILL.md` | 核心技能定义文件，包含描述、工作流程、高级特性引用 |\n| `scripts/` | 工具脚本目录（可选），用于确定性操作、格式化、错误处理 |\n| `docs/` | 文档目录（可选），包含参考文档、计划、变更日志 |\n| `REFERENCE.md` | 高级特性参考文档（可选） |\n\n技能的设计原则：\n\n- **Token 节约**：脚本和工具脚本可以节省 token 消耗，提高可靠性\n- **可复用性**：通过结构化的工作流程和清单，确保任务执行的一致性\n- **分层组织**：基本信息在 SKILL.md 中，高级特性拆分到独立文件\n\n资料来源：[skills/write-a-skill/SKILL.md:1-20]()\n\n## SKILL.md 模板结构\n\nSKILL.md 是技能的入口文件，其标准模板结构如下：\n\n```markdown\n---\nname: skill-name\ndescription: Brief description of capability. Use when [specific triggers].\n---\n\n# Skill Name\n\n## Quick start\n\n[Minimal working example]\n\n## Workflows\n\n[Step-by-step processes with checklists for complex tasks]\n\n## Advanced features\n\n[Link to separate files: See [REFERENCE.md](REFERENCE.md)]\n```\n\n### Frontmatter 配置\n\nFrontmatter 部分定义了技能的基本元数据：\n\n```yaml\n---\nname: skill-name          # 技能唯一标识符\ndescription: 简短描述    # 用于 agent 识别的触发条件说明\n---\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `name` | string | 是 | 技能的唯一标识符，应使用 kebab-case 命名 |\n| `description` | string | 是 | 简短描述，用于 agent 在系统提示中识别何时加载此技能 |\n\n资料来源：[skills/write-a-skill/SKILL.md:22-40]()\n\n## Description 编写规范\n\nDescription 是 agent **唯一能看到的信息**，用于在系统提示中决定是否加载该技能。\n\n### 格式要求\n\n| 要求 | 说明 |\n|------|------|\n| 最大字符数 | 1024 characters |\n| 人称 | 第三人称 |\n| 句子结构 | 第一句描述功能，第二句描述触发条件（\"Use when...\"） |\n\n### 编写示例\n\n**正确示例**：\n```\nExtract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n**错误示例**：\n```\nHelps with documents.\n```\n\n错误示例的问题在于：没有给 agent 提供足够的区分信息，无法将此技能与其他文档相关技能区分开来。\n\n### 触发条件设计\n\nDescription 应明确列出触发关键词和场景：\n\n| 触发类型 | 示例 |\n|---------|------|\n| 文件类型 | `PDF`, `Markdown`, `JSON`, `YAML` |\n| 操作类型 | `write`, `refactor`, `debug`, `translate` |\n| 领域关键词 | `patent`, `engineering`, `automotive` |\n| 上下文 | `local`, `private`, `no cloud` |\n\n资料来源：[skills/write-a-skill/SKILL.md:42-65]()\n\n## 目录结构规范\n\n### 基础结构\n\n```\nskill-name/\n├── SKILL.md          # 必需：技能入口文件\n├── scripts/          # 可选：工具脚本目录\n│   └── helper.js\n├── docs/             # 可选：文档目录\n│   ├── plans/        # 计划文档\n│   └── REFERENCE.md  # 参考文档\n```\n\n### Crystallize 模式下的结构\n\n当使用 crystallize 模式创建技能时，可能包含以下附加结构：\n\n```\nskills/\n└── <name>/\n    ├── SKILL.md      # 新建或更新的技能\n    └── docs/plans/crystallization-log.md  # 可选：结晶化历史记录\n```\n\n资料来源：[skills/crystallize/SKILL.md:50-65]()\n\n## 脚本使用规范\n\n### 何时添加脚本\n\n添加工具脚本的判断标准：\n\n| 判断标准 | 说明 |\n|---------|------|\n| 操作确定性 | 操作是确定性的（验证、格式化）而非探索性的 |\n| 代码重复 | 相同代码会被反复生成 |\n| 错误处理 | 需要显式的错误处理逻辑 |\n\n使用脚本的优势：\n- 节省 token 消耗\n- 提高执行可靠性\n- 避免每次生成可能产生的错误\n\n### 脚本类型\n\n| 脚本类型 | 示例用途 |\n|---------|---------|\n| 验证脚本 | 语法检查、schema 验证 |\n| 格式化脚本 | 代码格式化、文件规范化 |\n| 生成脚本 | 模板填充、代码生成 |\n| 集成脚本 | API 调用、数据转换 |\n\n资料来源：[skills/write-a-skill/SKILL.md:67-78]()\n\n## 文件拆分规范\n\n### 拆分时机\n\n| 条件 | 触发操作 |\n|------|---------|\n| SKILL.md 超过 100 行 | 考虑拆分到 REFERENCE.md |\n| 内容领域差异明显 | 按领域拆分（如 finance vs sales schemas） |\n| 高级特性使用频率低 | 拆分到独立文件，按需加载 |\n\n### 拆分策略\n\n- **一级引用**：SKILL.md 仅引用一层深度的文件\n- **避免过度拆分**：保持技能的完整性，避免碎片化\n- **保持可导航性**：拆分后的文件结构应保持清晰的导航路径\n\n资料来源：[skills/write-a-skill/SKILL.md:80-95]()\n\n## 技能工作流程\n\n### Crystallize 模式工作流程\n\nCrystallize 是一种从会话经验中提炼技能模式的方法，其标准工作流程如下：\n\n```mermaid\ngraph TD\n    A[任务完成] --> B{是否需要重复?}\n    B -->|是| C[回顾会话]\n    B -->|否| Z[完成]\n    C --> D[提取模式]\n    D --> E[检查范围]\n    E --> F[搜索现有技能]\n    F --> G{发现重叠?}\n    G -->|是| H[更新现有技能]\n    G -->|否| I[创建新技能]\n    H --> J[记录结晶化]\n    I --> J\n```\n\n### Crystallize 模式类型\n\n| 模式 | 输出 | 适用场景 |\n|------|------|---------|\n| `default` | 完整结晶：审查→提取→范围检查→去重→创建/更新 | `crystallize`, `capture this as a skill` |\n| `quick` | 快速捕获到最小技能存根 | `quick crystallize`, 任务中模式发现 |\n| `exploratory` | 向外扩展一圈，检查相邻表面是否具有相同模式 | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | 立即结晶，由操作员挫败感触发 | `this took too long`, `why aren't you using...` |\n| `correction` | 立即更新，基于操作员纠正 | 操作员纠正身份/路径/边界 |\n| `audit` | 检查应该结晶但没有结晶的内容 | `what patterns did we miss` |\n\n### 结晶化步骤详解\n\n#### 1. 回顾（Review）\n\n回答以下问题：\n- 任务是什么？\n- 解决了什么问题？\n- 学到了什么？\n- 下次会重复哪些步骤？\n\n#### 2. 模式提取（Pattern Extraction）\n\n识别可复用模式：\n\n| 模式要素 | 说明 |\n|---------|------|\n| **关键步骤** | 产生结果的最简序列是什么？ |\n| **启发式规则** | 需要哪些判断？出现了哪些经验法则？ |\n| **陷阱** | 什么出错了或差点出错？哪些假设失败了？ |\n| **决策点** | 在哪里选择不同方法？什么因素决定了选择？ |\n\n#### 3. Exploratory-Mode 扩展\n\n当操作员要求 \"more crystallization\" 或使用 `--exploratory-mode` 时：\n\n1. 从修复的确切位置开始\n2. 检查最近的相邻表面是否有相同的过时假设\n3. 捕获更广泛的复用规则\n\n资料来源：[skills/crystallize/SKILL.md:15-50]()\n\n## 技能审核清单\n\n创建或更新技能后，使用以下清单进行自检：\n\n| 检查项 | 说明 |\n|-------|------|\n| Description 包含触发条件 | 包含 \"Use when...\" 格式的触发条件描述 |\n| SKILL.md 行数控制 | 保持在 100 行以内 |\n| 无时间敏感信息 | 避免硬编码日期、价格等会过时的信息 |\n| 术语一致性 | 全文使用统一的术语命名 |\n| 包含具体示例 | 提供可直接使用的代码示例 |\n| 引用层级控制 | 仅引用一层深度的文件 |\n\n资料来源：[skills/write-a-skill/SKILL.md:97-110]()\n\n## 技能路由与上下文集成\n\n### 与 SP-006 的关系\n\nSP-006（潜在技能观察器）从工具调用序列自动检测模式。Crystallize 技能通过**有意的结晶**补充 SP-006——这些模式从问题理解中产生，而非仅从工具使用观察中产生。两种机制共享相同的技能命名空间。\n\n### 上下文引用\n\n技能应引用相关的上下文文件：\n\n```markdown\n## 上下文引用\n\n- 技能花园（skills garden）\n- Mesh 上下文技能\n- 全局架构规则（来自 `GLOBAL_AGENT_RULES.md`）\n```\n\n### 关键路径参考\n\n| 路径类型 | 用途 |\n|---------|------|\n| 第一方技能 | `~/.agents/skills/<skill-name>/SKILL.md` |\n| 供应商技能 | `~/.agents/skills/` |\n| 企业特定技能 | 适当的 `~/.agents/skills/` 子目录 |\n| 项目技能 | 项目级别 `skills/` 目录 |\n\n资料来源：[skills/codex-context/SKILL.md:1-25]()\n\n## 技能手术与维护\n\n### Skill Surgery 工具\n\n`s4b7-ai-skills` 提供了技能维护相关的脚本：\n\n| 脚本 | 功能 |\n|------|------|\n| `audit-skills.mjs` | 审计技能完整性 |\n| `cluster-skill-triggers.mjs` | 聚类技能触发条件 |\n| `redirect-deprecated-skill.mjs` | 重定向已弃用技能 |\n\n### 维护操作类型\n\n| 操作 | 说明 |\n|------|------|\n| 创建（Create） | 新建技能定义 |\n| 更新（Update） | 扩展或修改现有技能 |\n| 合并（Merge） | 合并重叠技能 |\n| 重定向（Redirect） | 将旧技能重定向到新位置 |\n| 审核（Audit） | 检查技能健康状态 |\n\n### 维护原则\n\n- **禁止在探索性手术期间删除技能**，先重定向，删除需操作员明确批准\n- **不编辑归档历史**，除非仍作为活动触发问题浮现\n- **不创建大型综合技能**，优先使用一个规范路由器加专注子技能\n- **研究后再发明**，不结晶过时版本号、价格或 API 形状\n\n资料来源：[skills/skill-surgery-rd/SKILL.md:1-30]()\n\n## 产物路由规范\n\n技能执行后的产物应路由到指定路径：\n\n| 产物类型 | 路径 | 用途 |\n|---------|------|------|\n| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |\n| 更新技能 | 现有技能路径 | 扩展能力 |\n| 结晶日志 | `docs/plans/crystallization-log.md` | 所有结晶化历史记录（可选） |\n| 扫描报告 | `ShadowArchive/80-reports/` | 跨域探索结果 |\n| 重构报告 | `ShadowArchive/80-reports/refactor-<target>-YYYY-MM-DD.md` | 重构会话摘要 |\n\n### 产物格式\n\n| 格式 | 使用场景 |\n|------|---------|\n| JSONL | 机器可读的日志、信号数据 |\n| Markdown | 人类可读的文档、报告 |\n| YAML | 配置文件、元数据 |\n\n资料来源：[skills/crystallize/SKILL.md:65-80]()\n\n## 常见陷阱与注意事项\n\n### SKILL.md 编写陷阱\n\n| 陷阱 | 问题 | 解决方案 |\n|------|------|---------|\n| Description 过于笼统 | Agent 无法区分技能 | 使用具体触发关键词 |\n| 包含时间敏感信息 | 信息会过时失效 | 避免硬编码日期/价格 |\n| 过度拆分 | 碎片化降低可导航性 | 保持合理引用层级 |\n| 缺少示例 | 用户无法快速上手 | 提供具体代码示例 |\n\n### Crystallize 模式陷阱\n\n| 陷阱 | 问题 | 解决方案 |\n|------|------|---------|\n| 过早停止 | 未发现相邻模式 | 使用 exploratory-mode |\n| 假设验证缺失 | 结晶了错误模式 | 在结晶前验证假设 |\n| 范围过大 | 创建了巨型技能 | 检查范围，控制技能边界 |\n\n### 维护操作陷阱\n\n| 陷阱 | 问题 | 解决方案 |\n|------|------|---------|\n| 循环重定向检测失败 | A→B→A 循环 | 阻止循环，要求手动解决 |\n| 合并冲突未处理 | 合并目标有冲突的 gotchas | 保留双方 gotchas，标记供操作员审查 |\n| 权限问题未报告 | 无法访问技能目录 | 报告并跳过，仅审计可访问目录 |\n\n资料来源：[skills/write-a-skill/SKILL.md:97-110](); [skills/skill-surgery-rd/SKILL.md:25-40]()\n\n## 最佳实践总结\n\n### 设计原则\n\n1. **最小化描述**：Description 应简洁明了，最大 1024 字符\n2. **明确的触发条件**：让 agent 能准确判断何时加载技能\n3. **层级组织**：基本信息在主文件，高级特性在引用文件\n4. **可验证性**：提供清单和验收标准\n\n### 执行原则\n\n1. **确定性优先**：使用脚本处理确定性操作\n2. **Token 效率**：脚本比每次生成代码更高效可靠\n3. **可追踪性**：记录所有变更的来源和理由\n\n### 维护原则\n\n1. **不破坏性修改**：优先重定向而非删除\n2. **持续审计**：定期检查技能健康状态\n3. **模式复用**：跨技能识别和提取复用模式\n\n---\n\n本指南基于 s4b7-ai-skills 项目的实际源码编写，涵盖了从技能创建到维护的完整生命周期。遵循本指南可以确保技能的可用性、可维护性和可扩展性。\n\n---\n\n<a id='crystallize'></a>\n\n## Crystallize技能\n\n### 相关页面\n\n相关主题：[Agent-Cryst技能](#agent-cryst), [编写技能指南](#write-a-skill)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)\n</details>\n\n# Crystallize技能\n\n## 概述\n\nCrystallize（结晶化）技能是一种从AI代理会话中提取和固化可复用模式的方法论。其核心目标是将隐性的问题解决方案转化为显性的、结构化的技能文档，使AI代理能够在未来的类似场景中快速调用经过验证的最佳实践。\n\n该技能与SP-006（潜在技能观察器）形成互补关系：SP-006通过自动观察工具调用序列来检测模式，而Crystallize则通过有意识的推理来提取模式——这些模式源于对问题的理解，而不仅仅是工具使用的观察。两者共同服务于同一个技能命名空间。\n\n资料来源：[skills/crystallize/SKILL.md:1-20]()\n\n## 技能定位\n\nCrystallize技能专注于以下类型的模式提取：\n\n- 需要人类判断力的复杂决策流程\n- 跨会话累积的专业知识\n- 难以从工具调用序列自动推断的启发式规则\n- 需要解释\"为什么这样做\"的推理链\n\n以下类型的模式不适合通过Crystallize提取：\n\n- 代码库本身显而易见的操作\n- 纯确定性的自动化任务\n- 单一会话内完成且不再复发的临时需求\n\n资料来源：[skills/crystallize/SKILL.md:20-30]()\n\n## 工作流程\n\nCrystallize技能采用结构化的工作流程来确保提取的模式具有高质量和可复用性。\n\n```mermaid\ngraph TD\n    A[任务完成] --> B{是否应该复用?}\n    B -->|是| C[回顾会话]\n    B -->|否| Z[完成]\n    C --> D[提取模式]\n    D --> E[检查范围]\n    E --> F{发现重叠?}\n    F -->|是| G[更新现有技能]\n    F -->|否| H[创建新技能]\n    G --> I[记录结晶化日志]\n    H --> I\n```\n\n### 步骤一：回顾（Review）\n\n在回顾阶段，需要回答以下关键问题：\n\n- **任务是什么？** 明确本次会话要解决的原始问题\n- **解决了什么问题？** 描述最终达成的结果\n- **学到了什么？** 提取本次获得的关键知识\n- **下次会重复哪些步骤？** 识别可复用的工作流\n\n资料来源：[skills/crystallize/SKILL.md:76-82]()\n\n### 步骤二：模式提取（Pattern Extraction）\n\n从回顾中识别可复用模式，包含四个维度：\n\n| 维度 | 描述 | 示例 |\n|------|------|------|\n| **关键步骤** | 产生结果的最少必要序列 | 读取配置 → 验证格式 → 解析数据 → 输出结果 |\n| **启发式规则** | 需要判断力的经验法则 | 文件超过500行应考虑拆分 |\n| **常见陷阱** | 容易出错或差点出错的点 | 忘记处理空输入导致崩溃 |\n| **决策点** | 需要在备选方案中做选择的地方 | 选择A/B方案时的判断依据 |\n\n资料来源：[skills/crystallize/SKILL.md:83-97]()\n\n### 步骤三：检查范围（Check Scope）\n\n在创建技能前，需要明确该模式的适用范围：\n\n- **通用模式** → 放置在 `~/.agents/skills/<skill-name>/SKILL.md`\n- **企业特定模式** → 放置在 `~/.agents/skills/` 下的适当子目录\n\n同时需要评估模式是否会与其他现有技能产生重叠。如果发现重叠，应扩展现有技能而非创建新技能。\n\n资料来源：[skills/crystallize/SKILL.md:59-65]()\n\n### 步骤四：搜索现有技能（Search Existing Skills）\n\n在创建或更新技能前，必须检查是否已存在相关技能：\n\n- 扫描现有技能目录\n- 检查是否有相似的触发短语或描述\n- 评估模式重叠程度\n\n如果发现重叠，优先更新现有技能的结构，而非创建重复的技能文档。\n\n资料来源：[skills/crystallize/SKILL.md:66-70]()\n\n### 步骤五：创建或更新技能\n\n**创建新技能**\n\n```markdown\n~/.agents/skills/<slug>/SKILL.md\n```\n\n**更新现有技能**\n\n将新模式作为新章节添加，或扩展现有工作流程。保留技能原有结构。\n\n**记录结晶化元数据**\n\n在技能文件底部添加 `## Crystallized From` 章节：\n\n```markdown\n## Crystallized From\n- Session: [日期/上下文]\n- Original task: [正在解决的任务]\n- Pattern extracted: [提取的模式描述]\n```\n\n如果使用了探索模式，还需记录：\n- 检查了哪些相邻表面\n- 故意保留未检查的表面\n\n资料来源：[skills/crystallize/SKILL.md:45-58]()\n\n## 技能模式\n\nCrystallize技能支持六种不同的模式，以适应不同的使用场景。\n\n| 模式 | 输出 | 触发条件 |\n|------|------|----------|\n| `default` | 完整结晶化：回顾 → 提取 → 范围检查 → 去重 → 创建/更新 | `crystallize`, `capture this as a skill` |\n| `quick` | 快速捕获到最小技能存根（稍后完善） | `quick crystallize`, `mid-task pattern discovery` |\n| `exploratory` | 从修复点向外扩展一圈，检查相邻表面 | `--exploratory-mode`, `more crystallization` |\n| `drag-response` | 由操作员挫败感触发的即时结晶化 | `this took too long`, `why aren't you using...` |\n| `correction` | 由操作员纠正触发的即时更新 | 操作员纠正身份/路径/边界 |\n| `audit` | 检查应该结晶化但未结晶化的内容 | `what patterns did we miss` |\n\n资料来源：[skills/crystallize/SKILL.md:34-45]()\n\n### 探索模式扩展规则\n\n当操作员请求\"更多结晶化\"或引用 `--exploratory-mode` 时，不应在本地修复处停止。应该向外扩展一圈并捕获更广泛的可用规则。\n\n扩展检查清单：\n\n1. 从被修复的具体内容开始\n2. 检查可能包含相同陈旧假设的最近相邻表面\n3. 对每个相邻表面执行相同模式检查\n\n```mermaid\ngraph LR\n    A[精确修复点] --> B[相邻表面 1]\n    A --> C[相邻表面 2]\n    A --> D[相邻表面 3]\n    B --> E{存在相同模式?}\n    C --> E\n    D --> E\n    E -->|是| F[扩展规则到相邻表面]\n    E -->|否| G[记录为已检查]\n```\n\n资料来源：[skills/crystallize/SKILL.md:98-112]()\n\n## SKILL.md 模板\n\n每个通过Crystallize创建的技能都应遵循统一模板：\n\n```markdown\n---\nname: skill-name\ndescription: 简短描述功能。当 [触发短语] 时使用。\n---\n\n# Skill Name\n\n## Quick start\n\n[最小可用示例]\n\n## Workflows\n\n[复杂任务的分步流程，包含检查清单]\n\n## Advanced features\n\n[链接到单独文件：参见 REFERENCE.md]\n\n## Key Decisions\n- [决策点 1]: [默认选择 + 原因]\n- [决策点 2]: [默认选择 + 原因]\n\n## Gotchas\n- [常见错误 1]\n- [常见错误 2]\n\n## Crystallized From\n- Session: [日期/上下文]\n- Original task: [正在解决的任务]\n```\n\n资料来源：[skills/crystallize/SKILL.md:2-25]()\n\n### 描述撰写规范\n\n技能的描述是代理决定加载哪个技能时看到的唯一信息，因此描述撰写至关重要：\n\n**要求**\n\n- 最多1024个字符\n- 使用第三人称\n- 第一句：功能是什么\n- 第二句：`Use when [具体触发条件]`\n\n**良好示例**\n\n```\nExtract text and tables from PDF files, fill forms, merge documents. \nUse when working with PDF files or when user mentions PDFs, forms, or document extraction.\n```\n\n**不良示例**\n\n```\nHelps with documents.\n```\n\n**触发条件示例**\n\n| 触发类型 | 示例短语 |\n|----------|----------|\n| 文件类型 | `PDF`, `Excel`, `CSV`, `Markdown` |\n| 操作类型 | `translate`, `refactor`, `debug`, `review` |\n| 领域特定 | `patent`, `automotive`, `sourcing` |\n| 上下文 | `local only`, `no cloud`, `private data` |\n\n资料来源：[skills/crystallize/SKILL.md:90-115]()\n\n## 工件路由\n\nCrystallize技能产出的工件遵循明确的路由规则：\n\n| 工件类型 | 路径 | 用途 |\n|----------|------|------|\n| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |\n| 更新技能 | 现有技能相同路径 | 扩展能力 |\n| 结晶化日志 | `docs/plans/crystallization-log.md` | 历史记录（可选） |\n| 企业特定技能 | `~/.agents/skills/` 下适当子目录 | 领域限定能力 |\n\n资料来源：[skills/crystallize/SKILL.md:46-52]()\n\n## 回退链\n\n当主要路径不可用时，Crystallize技能遵循预定义的回退策略：\n\n1. **主要路径**：完整工作流 — 回顾 → 提取 → 范围检查 → 去重 → 创建/更新\n2. **回退选项**：检查是否有其他可用的模式提取入口\n3. **最小化回退**：如果所有自动路径都失败，至少记录需要手动处理的待办事项\n\n资料来源：[skills/crystallize/SKILL.md:71-75]()\n\n## 与其他技能的关系\n\nCrystallize技能不是孤立存在的，它与多个相关技能形成协作网络：\n\n### 与SP-006（潜在技能观察器）的关系\n\n| 方面 | SP-006 | Crystallize |\n|------|--------|-------------|\n| 模式来源 | 自动观察工具调用序列 | 有意识的推理和理解 |\n| 适用场景 | 重复性操作模式 | 需要判断力的复杂决策 |\n| 模式深度 | 浅层操作模式 | 深层推理链和启发式规则 |\n| 自动化程度 | 完全自动 | 半自动，需要人类参与 |\n\n两者共同服务于同一个技能命名空间，可以相互补充。\n\n资料来源：[skills/crystallize/SKILL.md:21-24]()\n\n### 与write-a-skill技能的关系\n\nCrystallize负责从会话中提取模式，而 `write-a-skill` 负责将模式格式化为符合规范的技能文档。两者形成\"提取 → 格式化\"的流水线。\n\n资料来源：[skills/write-a-skill/SKILL.md:1-30]()\n\n## 最佳实践\n\n### 何时使用Crystallize\n\n- 同一类型的问题出现了多次\n- 发现了可复用的工作流程或启发式规则\n- 操作员表达了挫败感（\"这花了太长时间\"）\n- 复杂的决策过程值得记录\n\n### 何时不使用Crystallize\n\n- 单次性、不再复发的任务\n- 代码库本身显而易见的操作\n- 纯确定性的自动化任务\n- 模式过于具体，无法泛化\n\n### 模式质量标准\n\n一个好的结晶化模式应该：\n\n1. **可独立理解**：不依赖会话上下文就能理解\n2. **具体且可操作**：提供清晰的步骤或决策指导\n3. **包含陷阱警告**：帮助新手避免常见错误\n4. **标注决策点**：说明在何处需要判断力\n5. **有触发条件**：明确何时应该使用该技能\n\n资料来源：[skills/crystallize/SKILL.md:75-112]()\n\n## 总结\n\nCrystallize技能是构建可持续、可复用AI代理知识库的核心机制。通过结构化的\"回顾 → 提取 → 检查 → 路由\"流程，它将散落在各个会话中的隐性知识转化为显性的、可被代理系统自动加载的技能文档。六种模式（default、quick、exploratory、drag-response、correction、audit）确保了该机制能够适应从主动提炼到被动捕获等各种使用场景。\n\n---\n\n<a id='model-identity'></a>\n\n## 模型身份管理\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)\n- [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)\n- [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n- [skills/persona-engine/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/persona-engine/SKILL.md)\n- [skills/model-identity/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/model-identity/SKILL.md)\n- [skills/model-change-detector/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/model-change-detector/SKILL.md)\n\n</details>\n\n# 模型身份管理\n\n模型身份管理是 AI Agent 系统中的核心能力，负责在不同模型提供商、版本和配置之间建立统一的身份标识、路由策略和状态管理机制。该系统通过标准化的接口和抽象层，使上层应用能够在多种 AI 模型之间透明切换，同时保持一致的行为特性和上下文连续性。\n\n## 概述\n\n在多模型 AI 生态系统中，模型身份管理解决以下核心问题：\n\n| 问题域 | 描述 |\n|--------|------|\n| **身份标识** | 为每个模型实例建立唯一标识，包含提供商、模型名称、版本等元数据 |\n| **版本追踪** | 监控模型变化，检测 breaking changes，维护兼容性信息 |\n| **路由决策** | 根据任务类型、模型能力、成本和延迟等因素智能选择目标模型 |\n| **状态保持** | 在模型切换时维护对话上下文和会话状态的一致性 |\n| **配置管理** | 集中管理不同模型的 API 配置、认证信息和端点 |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n## 架构设计\n\n### 核心组件\n\n```mermaid\ngraph TD\n    subgraph \"模型身份管理层\"\n        MI[模型身份注册表]\n        MV[模型版本追踪器]\n        MC[模型能力映射]\n    end\n    \n    subgraph \"路由决策层\"\n        RH[路由启发式引擎]\n        RP[Provider特定准备器]\n        RT[令牌成本计算器]\n    end\n    \n    subgraph \"执行层\"\n        AE[AI SDK执行器]\n        CT[Claude集成]\n        GT[Gemini集成]\n        OT[Ollama集成]\n    end\n    \n    subgraph \"上下文管理层\"\n        CM[上下文管理器]\n        SS[会话状态]\n        CTX[历史上下文]\n    end\n    \n    MI --> RH\n    MV --> MC\n    MC --> RH\n    RH --> RP\n    RP --> AE\n    AE --> CT\n    AE --> GT\n    AE --> OT\n    CM --> SS\n    SS --> CTX\n```\n\n### 模型身份注册表\n\n模型身份注册表维护所有可用模型的元数据信息，包括：\n\n- **Provider 标识**：OpenAI、Anthropic、Google、Ollama 等\n- **模型 ID**：如 `gpt-4o`、`claude-sonnet-4-6`、`gemini-2.0-flash-001`\n- **版本信息**：stable、beta、latest 等\n- **能力标签**：文本生成、代码补全、函数调用、视觉识别等\n\n资料来源：[skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n\n## 多模型路由机制\n\n### 路由决策流程\n\n```mermaid\ngraph LR\n    A[用户请求] --> B{关键词检测}\n    B -->|write, refactor, debug| C[Codex]\n    B -->|research, summarize| D[Gemini]\n    B -->|local, private| E[Ollama]\n    B -->|translate, JP| F[Codex]\n    \n    C --> G[执行并返回]\n    D --> G\n    E --> G\n    F --> G\n```\n\n### 路由启发式规则\n\n根据请求类型自动选择最优模型：\n\n| 请求特征 | 路由目标 | 理由 |\n|----------|----------|------|\n| `write`, `implement`, `refactor`, `debug code` | codex | 代码能力强 |\n| `research`, `summarize`, `find`, `compare` | gemini | 搜索和总结能力 |\n| `translate`, `JP`, `Japanese` | Codex | 语言处理 |\n| `local`, `private`, `no cloud` | ollama | 隐私保护 |\n| `review`, `architect`, `design` | Codex | 深度分析 |\n| `quickly`, `fast`, `brief` | ollama | 低延迟 |\n| 文件路径、diffs、PRs | codex | 代码上下文 |\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n## 模型版本管理\n\n### 版本追踪机制\n\n模型版本追踪器持续监控各 Provider 的模型变更：\n\n```mermaid\ngraph TD\n    A[定期检查] --> B{发现新版本?}\n    B -->|是| C[更新版本信息]\n    B -->|否| D[保持现有状态]\n    C --> E{Breaking Change?}\n    E -->|是| F[触发告警]\n    E -->|否| G[标记为兼容更新]\n    F --> H[更新迁移指南]\n    G --> I[记录变更日志]\n    H --> J[通知相关组件]\n    I --> J\n```\n\n### AI SDK v5/v6 变更管理\n\nAI SDK 核心技能模块处理模型变更的兼容性：\n\n```mermaid\ngraph TD\n    A[检测 SDK 版本] --> B{v5 或 v6?}\n    B -->|v4 迁移| C[执行迁移检查清单]\n    B -->|v5| D[使用 CoreMessage 类型]\n    B -->|v6 Beta| E[Agent 抽象模式]\n    \n    C --> F[验证 API 兼容性]\n    D --> G[使用 convertToCoreMessages]\n    E --> H[使用新版 Agent]\n    \n    F --> I[生成迁移报告]\n    G --> J[运行时验证]\n    H --> J\n```\n\n**关键变更点：**\n\n| 变更项 | v4 | v5/v6 |\n|--------|-----|-------|\n| 消息类型 | `CoreMessage` | `ModelMessage` |\n| UI消息 | `Message` | `UIMessage` |\n| 工具错误 | `ToolExecutionError` | 普通 Error 对象 |\n| 结果字段 | `args`/`result` | `input`/`output` |\n\n资料来源：[skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)\n\n## Provider 特异性配置\n\n### 各 Provider 的模型标识\n\n| Provider | 模型标识 | 默认模型 | 深度任务模型 |\n|----------|----------|----------|--------------|\n| **Codex (via ACP)** | `Codex-sonnet-4-6` | 默认选择 | `Codex-opus-4-6` |\n| **Gemini (via OpenRouter)** | `google/gemini-2.0-flash-001` | 速度优先 | `google/gemini-2.5-pro` |\n| **Ollama** | `qwen3:8b` | 本地默认 | - |\n| **Tier 1 API** | Provider 特定 | - | - |\n\n### Provider 特定准备\n\n在委托任务前，系统会自动应用 Provider 特定的转换：\n\n```mermaid\ngraph TD\n    A[原始请求] --> B{目标 Provider?}\n    B -->|qwen3 (Ollama)| C[/no_think 前缀]\n    B -->|Codex (mcp__codex)| D[设置 workdir]\n    B -->|Gemini (OpenRouter)| E[选择模型]\n    \n    C --> F[执行请求]\n    D --> F\n    E --> F\n```\n\n**Ollama qwen3 模型特殊处理：**\n```\n→ 在提示前添加 /no_think\n→ 或设置 options.think = false\n```\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n## 上下文与状态管理\n\n### 多层上下文架构\n\n模型身份管理依赖多层上下文系统确保状态一致性：\n\n```mermaid\ngraph TD\n    subgraph \"上下文读取顺序\"\n        A[AGENTS.md] --> B[SHADOW-CONTEXT.md]\n        B --> C[ARCHITECTURE.md]\n        C --> D[SHADOW-ARCHITECTURE-SPEC.md]\n        D --> E[VERIFIABILITY.md]\n    end\n    \n    subgraph \"关键路径\"\n        F[ShadowArchive] \n        G[Agent roots]\n        H[Skills registry]\n        I[Reports]\n    end\n    \n    A --> F\n    A --> G\n    A --> H\n    A --> I\n```\n\n### 会话状态持久化\n\n| 文件 | 用途 | 位置 |\n|------|------|------|\n| Codex config | 模型、沙箱、MCP、插件配置 | `~/.codex/config.toml` |\n| Codex memories | 跨会话持久记忆 | `~/.codex/memories/MEMORY.md` |\n| Codex rules | Caveman 模式规则 | `~/.codex/rules/*.md` |\n| Claude CLAUDE.md | 机器标识、本地覆盖 | `~/.claude/CLAUDE.md` |\n| Claude AGENTS.md | Agent 开发规则 | `~/.claude/AGENTS.md` |\n| Hermes SOUL.md | Shadow 角色默认配置 | `~/.hermes/SOUL.md` |\n\n资料来源：[skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)\n\n## 检索与查询能力\n\n### 多模型查询管道\n\n系统提供多模型并行查询能力以获取多角度答案：\n\n```mermaid\ngraph TD\n    A[意图解析] --> B[扫描 Mesh 节点]\n    B --> C[收集数据]\n    C --> D[分析结果]\n    D --> E[生成报告]\n    \n    subgraph \"查询层级\"\n        T1[Tier 1: 快速并行查询]\n        T2[Tier 2: 可用 API]\n        T3[Tier 3: Web 检索]\n        T4[Tier 4: Codex 自评]\n    end\n    \n    T1 --> D\n    T2 --> D\n    T3 --> D\n    T4 --> D\n```\n\n### 查询输出模式\n\n| 模式 | 输出 | 使用场景 |\n|------|------|----------|\n| `default` | 摘要报告 | 常规扫描 |\n| `full` | 完整转储 | 深度分析 |\n| `json` | 原始数据 | 程序化处理 |\n\n资料来源：[skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)\n\n## 角色引擎与身份切换\n\n### 角色身份配置\n\n角色引擎管理系统中不同 AI 角色的身份配置：\n\n| 角色 | 配置文件 | 用途 |\n|------|----------|------|\n| Hermes (Shadow) | `~/.hermes/SOUL.md` | 默认 Shadow 角色 |\n| Red (M3 Enterprise) | `~/.hermes/profiles/astemo/SOUL.md` | 企业级角色 |\n| Gemini | `~/.gemini/GEMINI.md` | YOLO 模式 + 全局规则 |\n| Duality | `/Volumes/☯Duality/AGENTS.md` | 主控平面 |\n\n### 身份切换流程\n\n```mermaid\ngraph TD\n    A[请求到达] --> B{目标角色?}\n    B -->|Shadow| C[加载 Hermes SOUL]\n    B -->|Enterprise| D[加载 Red SOUL]\n    B -->|Gemini| E[加载 GEMINI]\n    B -->|Duality| F[加载 AGENTS.md]\n    \n    C --> G[应用角色配置]\n    D --> G\n    E --> G\n    F --> G\n    \n    G --> H[执行任务]\n    H --> I[返回结果]\n```\n\n## 错误处理与降级策略\n\n### 故障恢复链\n\n| 故障场景 | 恢复策略 |\n|----------|----------|\n| Mesh 不可达 | 跳过 Mesh 健康检查；继续本地分析 |\n| Caresoft API 不可用 | 报告；跳过工程情报模式 |\n| Skills 目录为空 | 报告；检查 `~/.agents/skills/` |\n| 特定模型不可用 | 自动降级到备选模型 |\n| 会话历史不可读 | 使用默认上下文重新初始化 |\n\n### 降级执行顺序\n\n1. **主链路**：完整扫描 → TDD 循环 → 验证 → 信号 → 下一任务\n2. **Ollama 不可用**：仅静态分析（grep、AST、文件指标）\n3. **测试未找到**：扫描测试；如不存在则搭建最小测试结构\n4. **自修复耗尽**：回滚更改；标记为不可恢复；继续下一问题\n\n资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)\n\n## 最佳实践\n\n### 模型选择指南\n\n```mermaid\ngraph TD\n    A[新任务] --> B{任务类型?}\n    B -->|代码生成| C[Codex - 代码能力强]\n    B -->|创意写作| D[Gemini - 多样性高]\n    B -->|隐私敏感| E[Ollama - 本地处理]\n    B -->|快速原型| F[Ollama - 低延迟]\n    B -->|深度分析| G[Codex Opus - 深度思考]\n    \n    C --> H[执行]\n    D --> H\n    E --> H\n    F --> H\n    G --> H\n```\n\n### 配置验证\n\n使用以下命令验证模型配置：\n\n```bash\n# 检查 Ollama 是否运行\ncurl -s http://localhost:11434/api/tags | head -1\n\n# 验证 AI SDK 模型 ID 和定价\nnpm run verify:portable\n\n# 检查技能目录\nfind ~/.agents/skills/ -name \"*.md\" | wc -l\n```\n\n### 模型能力映射表\n\n| 能力需求 | 推荐模型 | 备选模型 |\n|----------|----------|----------|\n| 实时代码补全 | Codex | Ollama qwen3 |\n| 长文本生成 | Gemini 2.5 Pro | Codex Opus |\n| 多语言翻译 | Codex | Gemini Flash |\n| 本地隐私处理 | Ollama qwen3 | - |\n| 函数调用 | AI SDK v5/v6 | Provider 原生 |\n\n## 相关技能模块\n\n| 技能名称 | 功能描述 |\n|----------|----------|\n| `model-identity` | 模型身份标识与注册 |\n| `model-change-detector` | 模型变更检测与告警 |\n| `persona-engine` | 角色身份与切换管理 |\n| `multi-model-query` | 多模型并行查询 |\n| `ai-sdk-core` | AI SDK 核心集成 |\n| `acp-delegate-auto` | 自动委托与路由 |\n\n## 总结\n\n模型身份管理是整个 AI Agent 系统的基础设施层，通过标准化的接口、智能路由和状态管理，使系统能够在多个 AI 模型提供商之间灵活切换，同时保持一致的用户体验和上下文连续性。该系统支持版本追踪、故障恢复、角色切换等高级功能，为构建复杂的多模型 AI 应用提供了坚实的技术基础。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：s4b7-ai/s4b7-ai-skills\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown\n\n<!-- canonical_name: s4b7-ai/s4b7-ai-skills; human_manual_source: deepwiki_human_wiki -->\n",
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "Human Manual / 人类版说明书"
    },
    "pitfall_log": {
      "asset_id": "pitfall_log",
      "filename": "PITFALL_LOG.md",
      "markdown": "# Pitfall Log / 踩坑日志\n\n项目：s4b7-ai/s4b7-ai-skills\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx skills`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown\n",
      "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
      "title": "Pitfall Log / 踩坑日志"
    },
    "prompt_preview": {
      "asset_id": "prompt_preview",
      "filename": "PROMPT_PREVIEW.md",
      "markdown": "# s4b7-ai-skills - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 s4b7-ai-skills 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. overview：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. skill-structure：技能文件结构。围绕“技能文件结构”模拟一次用户任务，不展示安装或运行结果。\n3. skill-categories：技能分类体系。围绕“技能分类体系”模拟一次用户任务，不展示安装或运行结果。\n4. langgraph-agent：LangGraph Agent技能。围绕“LangGraph Agent技能”模拟一次用户任务，不展示安装或运行结果。\n5. ai-sdk-core：AI SDK Core技能。围绕“AI SDK Core技能”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. overview\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. skill-structure\n输入：用户提供的“技能文件结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. skill-categories\n输入：用户提供的“技能分类体系”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. langgraph-agent\n输入：用户提供的“LangGraph Agent技能”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. ai-sdk-core\n输入：用户提供的“AI SDK Core技能”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / overview：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / skill-structure：Step 2 必须围绕“技能文件结构”形成一个小中间产物，并等待用户确认。\n- Step 3 / skill-categories：Step 3 必须围绕“技能分类体系”形成一个小中间产物，并等待用户确认。\n- Step 4 / langgraph-agent：Step 4 必须围绕“LangGraph Agent技能”形成一个小中间产物，并等待用户确认。\n- Step 5 / ai-sdk-core：Step 5 必须围绕“AI SDK Core技能”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/s4b7-ai/s4b7-ai-skills\n- https://github.com/s4b7-ai/s4b7-ai-skills#readme\n- skills/a2a-orchestrator/SKILL.md\n- skills/aacp/SKILL.md\n- skills/acp-delegate-auto/SKILL.md\n- skills/agent-cryst/SKILL.md\n- skills/ai-sdk-core/SKILL.md\n- skills/codex-context/SKILL.md\n- skills/codex-latex/SKILL.md\n- skills/codex-policy-steering/SKILL.md\n- skills/command-center/SKILL.md\n- skills/crystallize/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 s4b7-ai-skills 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n  2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
      "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
      "title": "Prompt Preview / 安装前试用 Prompt"
    },
    "quick_start": {
      "asset_id": "quick_start",
      "filename": "QUICK_START.md",
      "markdown": "# Quick Start / 官方入口\n\n项目：s4b7-ai/s4b7-ai-skills\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx skills\n```\n\n来源：https://github.com/s4b7-ai/s4b7-ai-skills#readme\n\n## 来源\n\n- repo: https://github.com/s4b7-ai/s4b7-ai-skills\n- docs: https://github.com/s4b7-ai/s4b7-ai-skills#readme\n",
      "summary": "从项目官方 README 或安装文档提取的开工入口。",
      "title": "Quick Start / 官方入口"
    }
  },
  "validation_id": "dval_b4079d7060694641894b0f348329da88"
}