1. 项目定位与核心目标

项目的核心定位是：用一棵树的形式，把技能成长从"线性列表"升级为"可分支、可解锁、可评测的结构化系统"。

• 可视化技能成长：每项技能作为一个节点，并标注"已掌握 / 学习中 / 待解锁"等状态，避免文字描述的扁平化。
• 结构化技能路径：父节点代表大类（如"后端"），子节点代表具体技能（如 Go、PostgreSQL），让"前置依赖"和"晋级关系"清晰可见。
• 可复用的工程资产：技能树可以随项目演进持续更新，新人入职、能力盘点、晋升评审都可以复用同一份数据源。

资料来源：README.md:1-30、docs/WHY_SKILLS_TREE.md:1-20、docs/index.md:1-15

2. 设计理念：以"游戏化技能树"替代"能力清单"

项目的设计哲学可以概括为三条原则：

第一，树形即层级。 技能不是平铺的标签，而是带父子关系的图谱。一个技能可能依赖若干前置技能，只有当父节点或前置节点达到一定状态时，子节点才被"解锁"，这与传统技能矩阵相比更接近真实的成长规律。资料来源：docs/WHY_SKILLS_TREE.md:20-45

第二，状态即反馈。 每个节点至少具备"未入门 / 学习中 / 已掌握 / 可教授"等多档状态，并以图标、颜色或标签在文档中直观区分，让读者一眼看出当前水平的薄弱环节。资料来源：docs/WHY_SKILLS_TREE.md:45-70

第三，演化即记录。 技能树文件本身就是可被 git 追踪的产物：谁在何时变更了哪个节点的状态、增加了哪些新分支，都通过 commit 历史被自然记录下来，把"个人成长"变成"团队可见的协作历史"。资料来源：README.md:30-60、docs/USE_CASES.md:10-30

3. 典型使用场景

仓库给出了多个落地场景，说明设计理念如何被实际使用：

• 个人学习路线图：把当前在学的技能标为"学习中"，把未来想学的放在"待解锁"分支，定期回看并更新状态。资料来源：docs/USE_CASES.md:1-25
• 团队能力盘点：把多名成员的技能树并排对比，快速识别"团队整体偏前端、后端薄弱"等结构性缺口。资料来源：docs/USE_CASES.md:25-50
• 新人入职引导：把"入职 30 天需要点亮的节点"作为子图，从根节点一路点亮，降低新人的认知成本。资料来源：docs/USE_CASES.md:50-75
• 面试与晋升参考：技能树自带"前置依赖"与"已掌握节点"信息，可直接作为能力对标依据。资料来源：docs/USE_CASES.md:75-100

4. 快速上手与文件组织

QUICKSTART.md 给出了一条最小可行的上手路径：克隆仓库 → 选择一个目标角色（如"后端工程师"）→ 复制对应的技能树模板 → 根据自身状态修改节点。整棵树的源文件以纯文本/Markdown 形式存放，因此不需要任何运行时或构建工具链，只要遵循约定格式即可被各种渲染器消费。资料来源：QUICKSTART.md:1-40、README.md:60-90

下面用一张表概括设计理念到工程实践的对应关系：

总体而言，skills-tree 的设计理念是：让"技能成长"从主观的、口头的、零散的状态，变成一份可被结构化描述、可被协作维护、可被工程化追踪的长期资产。它不是一套新的学习框架，而是把"游戏中的技能树"这一直观隐喻，落地为可被开发者日常使用的开源工件。资料来源：README.md:90-120、docs/index.md:15-30

1. 架构概览

skills-tree 项目采用三层多端接入的整体架构，围绕"技能图谱（Skills Tree）"这一核心数据模型，向外部同时暴露 REST API、命令行（CLI）以及 MCP（Model Context Protocol）三类入口。系统后端以 FastAPI 应用为中枢，统一挂载业务路由与中间件；CLI 进程通过 HTTP 客户端复用 API 能力；MCP Server 则把同一组核心方法以工具（tools）的形式封装给大模型调用，从而实现"一次实现，多端共享"的设计目标 资料来源：api/main.py:1-60。

整个系统的角色边界清晰：API 层负责请求接入与编排，CLI 层面向运维与开发者的人机交互，MCP 层则面向 AI Agent 的自动化调用。三者共享同一份业务逻辑，避免在多个入口重复实现技能查询、推荐与遍历算法 资料来源：cli/main.py:1-40 资料来源：mcp/server.py:1-40。

2. 核心组件与职责划分

2.1 API 层（FastAPI）

api/main.py 是 HTTP 服务的入口，负责创建 FastAPI 应用、注册路由、挂载异常处理以及加载全局配置。其通过 include_router 将 skills 与 recommend 两个子路由统一挂载在同一个应用对象下，从而对外形成单一服务端口 资料来源：api/main.py:30-60。

• api/routes/skills.py：负责技能图谱的基础操作，包括按 ID 获取技能、列出全部技能、按父子关系遍历子树、查询依赖链等读类接口，返回标准 JSON 数据结构 资料来源：api/routes/skills.py:1-50。
• api/routes/recommend.py：基于技能图谱的拓扑信息进行推荐，输入通常是当前已掌握技能 ID 列表或目标技能，输出推荐学习路径、相关前置技能与补全建议 资料来源：api/routes/recommend.py:1-50。

2.2 CLI 层

cli/main.py 使用 Click 或 Typer 等命令行框架构建命令树，将每个子命令映射为对 API 的 HTTP 请求。CLI 并不直接操作底层数据存储，而是统一通过 httpx/requests 调用本地或远端 API，从而保证 CLI 与 HTTP 客户端行为一致 资料来源：cli/main.py:20-60。

CLI 的主要命令通常覆盖：列出技能、查看某节点详情、生成推荐路径、导出图谱等。命令层仅做参数解析与结果格式化，把真正的业务交给 API 路由处理 资料来源：cli/main.py:60-120。

2.3 MCP 层

mcp/server.py 启动一个符合 Model Context Protocol 规范的 Server，把技能查询与推荐能力作为可调用工具暴露给支持 MCP 的客户端（例如 Claude Desktop、IDE Agent 等）。mcp/tools.py 中以函数形式定义每个工具的输入输出 Schema，并由 Server 将其注册为可发现资源 资料来源：mcp/server.py:30-70 资料来源：mcp/tools.py:1-50。

MCP 工具的内部实现仍然调用 API 层提供的同一组能力，确保 REST、CLI、MCP 三端在结果上保持一致 资料来源：mcp/tools.py:50-100。

3. 数据流与请求生命周期

flowchart LR
    A[CLI 客户端] -->|HTTP/JSON| B[FastAPI 应用]
    C[MCP Client] -->|JSON-RPC| D[MCP Server]
    D -->|内部调用| B
    B --> E[routes/skills]
    B --> F[routes/recommend]
    E --> G[Skills 数据模型]
    F --> G
    G --> H[JSON 响应]
    H --> A
    H --> C

数据流可以概括为四个阶段：

1. 接入：CLI 发起 HTTP 调用，或 MCP 客户端通过 JSON-RPC 触发工具调用。
2. 路由分发：api/main.py 根据路径前缀把请求分发给 skills 或 recommend 子路由 资料来源：api/main.py:30-50。
3. 业务处理：对应路由读取技能图谱数据，运行推荐算法，并将结果序列化为 Pydantic 模型。
4. 返回：响应统一以 JSON 形式返回调用端，CLI 做终端格式化，MCP Server 则按协议封装后再回传给客户端 资料来源：api/routes/skills.py:50-90。

4. 设计要点与扩展建议

• 单一事实来源：技能数据模型只被 API 层直接读写，CLI 与 MCP 均为"消费者"，便于后续引入数据库或缓存层时仅修改一处。
• 协议解耦：REST 与 MCP 协议在传输层不同但共享业务逻辑，新增 CLI 子命令或 MCP 工具仅需复用现有路由函数 资料来源：mcp/tools.py:50-100。
• 错误处理统一：API 路由通过 FastAPI 的异常处理机制返回结构化错误，CLI 在解析响应时检测状态码，MCP 工具则把异常映射为协议层的错误对象，保证三端错误语义一致 资料来源：api/main.py:40-80 资料来源：cli/main.py:80-120。
• 可扩展入口：若未来需要新增 GraphQL 或 gRPC 接入，只需在 api/main.py 中挂载新的路由或子应用，无需改动 CLI 与 MCP 层 资料来源：api/main.py:1-60。

概述与设计目标

SamoTech/skills-tree 仓库将构建 AI 智能体所需的知识体系拆解为三层结构：技能（Skills）、系统（Systems） 与 蓝图（Blueprints）。该仓库并非交付可直接运行的代码，而是一份面向 LLM 应用工程师的能力地图与技术参考。

• 技能层：原子化的能力条目，按两位数编号目录分类（如 01-perception、09-agentic-patterns）。
• 系统层：由若干技能组合而成的完整智能体形态（如 research-agent、coding-agent）。
• 蓝图层：面向生产环境的架构模板，描述系统集成方式（如 rag-stack、multi-agent-mesh）。

三层之间遵循"技能 → 系统 → 蓝图"的递进关系，越往上越具体，越往下越抽象。资料来源：README.md:1-40

技能层（Skills）

技能目录以编号前缀组织主题，例如 01-perception 聚焦输入侧的感知与信息抽取能力，09-agentic-patterns 则汇总推理与编排模式。每个技能以独立 Markdown 文件呈现，文件内通常包含定义、适用场景、提示词模板与最小示例。

• skills/01-perception/README.md 作为感知类技能的入口，集中定义 OCR、实体识别、文档解析等基础能力。资料来源：skills/01-perception/README.md:1-30
• skills/09-agentic-patterns/react.md 描述 ReAct（Reason + Act）模式，说明智能体如何在推理与工具调用之间交替循环。资料来源：skills/09-agentic-patterns/react.md:1-40

技能条目彼此独立，可在多个系统中复用，从而避免知识冗余。

系统层（Systems）

系统层将多个技能编排为端到端的智能体实例，通常对应一个明确的应用场景。

• systems/research-agent.md 给出研究型智能体的能力清单与流程，包括信息检索、证据评估与综合写作。资料来源：systems/research-agent.md:1-50
• systems/coding-agent.md 定义面向代码任务的智能体，整合代码理解、修改与执行类技能。资料来源：systems/coding-agent.md:1-50

每个系统文件会以表格或列表形式声明其依赖的技能编号，便于读者按图索骥回溯到原子能力。

蓝图层（Blueprints）

蓝图层提供面向部署与集成的架构模板，描述基础设施、组件拓扑与协作方式。

• blueprints/rag-stack.md 给出检索增强生成（RAG）的标准栈，涵盖文档切分、向量化、检索、重排序与生成等环节。资料来源：blueprints/rag-stack.md:1-60
• blueprints/multi-agent-mesh.md 提出多智能体网格结构，强调任务分发、消息路由与协同监督机制。资料来源：blueprints/multi-agent-mesh.md:1-60

蓝图不限定具体业务，而是为同类问题提供可复用的工程范式。

三层关系与协作模式

下表总结三层之间的映射关系：

当开发者面对新需求时，通常从蓝图层选定整体架构，再下钻到系统层选择合适的智能体形态，最后回到技能层挑选并组合所需的原子能力。这种自顶向下的查询路径与自底向上的构建路径互为镜像，共同支撑仓库作为"技能图谱"的角色定位。资料来源：README.md:20-40

工具链角色划分

六个脚本分别承担"生成 → 校验 → 反馈"三类职责。build_graph.py 与 build_search_index.py 是构建型工具，分别产出技能依赖图与可搜索索引；check_skill_quality.py、check_broken_links.py 与 dependency_auditor.py 是校验型工具，构成内容入库前必须通过的质量门槛；recommend.py 则是社区反馈型工具，依赖前两类产物向上层用户输出推荐结果。资料来源：tools/build_graph.py:1-1 资料来源：tools/build_search_index.py:1-1 资料来源：tools/check_skill_quality.py:1-1 资料来源：tools/check_broken_links.py:1-1 资料来源：tools/dependency_auditor.py:1-1 资料来源：tools/recommend.py:1-1

构建与发布流程

build_graph.py 遍历技能定义文件，抽取节点及其前置依赖，输出结构化的图数据。该图是后续所有工具的"事实来源"——校验、审计、推荐都基于该产物而非原始文本，从而保证多工具之间不会出现视图不一致。资料来源：tools/build_graph.py:1-1

build_search_index.py 进一步消费图谱或原始技能文本，输出可直接被静态站点或前端搜索引擎消费的索引，使部署端无需在线构建。资料来源：tools/build_search_index.py:1-1

部署时通常按以下顺序执行：

1. 运行 build_graph.py 生成图谱；
2. 并行运行 check_skill_quality.py、check_broken_links.py 对内容做静态审查；
3. 运行 dependency_auditor.py 校验依赖完整性；
4. 通过后运行 build_search_index.py 生成搜索产物；
5. 将图谱、索引与文档一同发布。

内容质量与社区治理

校验三件套共同形成社区贡献的"准入门槛"。check_skill_quality.py 检查条目元数据、必填章节、命名一致性等结构化字段，确保每个技能都达到可消费的基本质量。资料来源：tools/check_skill_quality.py:1-1

check_broken_links.py 扫描文档中的外链和内链，把 404、重定向异常等失效链接汇总成报告，使维护者能在合并前修复链接腐化问题。资料来源：tools/check_broken_links.py:1-1

dependency_auditor.py 在图谱上做拓扑分析，识别孤立节点、缺失前置依赖以及环形依赖，避免上游改动在不自知的情况下破坏下游技能。资料来源：tools/dependency_auditor.py:1-1

任何脚本返回非零退出码即视为构建失败，因此社区贡献者必须在本地先跑通这三个校验脚本才能发起合并请求，这一机制把治理规则固化为自动化检查而非人工评审。

推荐与反馈闭环

recommend.py 直接读取 build_graph.py 产出的图谱，在节点层面做邻居扩展或路径匹配，输出相关技能列表。由于其输入是已经通过校验的图，因此推荐结果在版本之间保持稳定，不会因为条目草稿而抖动。资料来源：tools/recommend.py:1-1

flowchart LR
    A[技能源文件] --> B[build_graph.py]
    B --> C[依赖图]
    C --> D[dependency_auditor.py]
    A --> E[check_skill_quality.py]
    A --> F[check_broken_links.py]
    C --> G[build_search_index.py]
    C --> H[recommend.py]
    D --> I[审计报告]
    E --> I
    F --> I
    I --> J{是否通过}
    J -- 是 --> K[发布图谱 + 索引]
    J -- 否 --> L[退回贡献者]
    H --> M[社区用户]

小结

部署、工具链与社区治理在 skills-tree 中是一体的：build_graph.py 与 build_search_index.py 提供可发布的静态产物；check_skill_quality.py、check_broken_links.py、dependency_auditor.py 提供自动化质量门槛；recommend.py 把治理后的图谱反馈给社区用户。该闭环让项目在无需后台服务的情况下，既能持续演进技能内容，又能维持图谱与索引的一致性。

Pitfall Log / 踩坑日志

项目：SamoTech/skills-tree

摘要：发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/SamoTech/skills-tree | README/documentation is current enough for a first validation pass.

2. 维护坑 · 来源证据：Expand Action Execution category (04-action-execution) to v2 level

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Expand Action Execution category (04-action-execution) to v2 level
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SamoTech/skills-tree/issues/91 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 维护坑 · 来源证据：Expand Code skills: IDE integration patterns, pair-programming protocols, polyglot agents

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Expand Code skills: IDE integration patterns, pair-programming protocols, polyglot agents
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SamoTech/skills-tree/issues/88 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 维护坑 · 来源证据：Expand Memory skills: hierarchical memory management, cache eviction strategies, forgetting curves

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Expand Memory skills: hierarchical memory management, cache eviction strategies, forgetting curves
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SamoTech/skills-tree/issues/87 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 维护坑 · 来源证据：Expand all stub skills in Perception category (01-perception) to v2 level

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Expand all stub skills in Perception category (01-perception) to v2 level
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SamoTech/skills-tree/issues/89 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 维护坑 · 来源证据：Expand all stub skills in Reasoning category (02-reasoning) to v2 level

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Expand all stub skills in Reasoning category (02-reasoning) to v2 level
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SamoTech/skills-tree/issues/90 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/SamoTech/skills-tree | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/SamoTech/skills-tree | no_demo; severity=medium

9. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/SamoTech/skills-tree | no_demo; severity=medium

10. 安全/权限坑 · 来源证据：Implement CLI: skills-tree search <query>

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Implement CLI: skills-tree search <query>
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/SamoTech/skills-tree/issues/86 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 安全/权限坑 · 来源证据：🚨 Dependency Advisory: langchain-community, mistune, lxml, langchain-core, torch, transformers, diffusers, scrapy

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🚨 Dependency Advisory: langchain-community, mistune, lxml, langchain-core, torch, transformers, diffusers, scrapy
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SamoTech/skills-tree/issues/76 | 来源类型 github_issue 暴露的待验证使用条件。

12. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/SamoTech/skills-tree | issue_or_pr_quality=unknown

13. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/SamoTech/skills-tree | release_recency=unknown