SkillLite 架构优化分析报告：项目开发日记

skilllite作者2026-04-17 8:09

一、项目规模与结构概览

1.1 代码规模

指标 数值
Rust 总行数（粗估） ~76,400 行 --- skilllite/ + crates/skilllite-* 下全部 *.rs，排除 node_modules/、target/、dist/（2026-04-16 wc）
主要 crates 11 个 workspace 成员：skilllite、core、fs 、artifact 、sandbox、executor、agent、evolution、commands、swarm；桌面 skilllite-assistant 单独 manifest，不在默认 workspace members
单文件最大（当前 Top） 见 §1.3；chat_session / scope / integrations 等已上千行量级

1.2 各 Crate 行数分布

Crate 总行数（.rs，同上排除规则） 备注
skilllite-agent ~22,600 Agent 循环、规划、扩展、内置测试等
skilllite-sandbox ~11,700 沙箱、runtime_deps、scanner 等
skilllite-evolution ~11,100 scope、external_learner、门禁与材料管线
skilllite-commands ~7,300 子命令；evolution.rs 体量仍大
skilllite-assistant ~6,600 仅 src-tauri Rust；前端 TS/React 未计入
skilllite-core ~6,500 metadata、paths、协议与 skill 元数据
skilllite（主包） ~5,700 thin 入口 + MCP/stdio 等仍集中于此
skilllite-executor ~1,500 会话、转写、记忆
skilllite-swarm ~1,300 P2P / mDNS
skilllite-fs ~1,200 文件系统、grep、atomic_write
skilllite-artifact ~960 Run-scoped artifact；agent 依赖 local feature 路径

1.3 单文件 Top 10（当前快照）

文件 行数 说明
skilllite-assistant/.../skilllite_bridge/integrations.rs ~1922 桌面与子进程/协议集成
skilllite-agent/chat_session.rs ~1458 会话与 RPC 编排
skilllite-evolution/scope.rs ~1431 进化范围与策略
skilllite-agent/extensions/builtin/tests.rs ~1392 内置扩展测试
skilllite-agent/agent_loop/helpers.rs ~1275 Agent 循环辅助
skilllite-sandbox/env/runtime_deps.rs ~1165 Python/Node 运行时解析与下载
skilllite-agent/agent_loop/mod.rs ~1111 循环主模块
skilllite-commands/evolution.rs ~1070 CLI 进化子命令
skilllite-agent/agent_loop/execution.rs ~1021 执行路径
skilllite-core/skill/metadata.rs ~978 Skill 元数据

1.4 依赖关系（简要）

复制代码 
skilllite (主二进制，thin 入口)
  ├── skilllite-commands
  │     ├── skilllite-core, skilllite-fs, skilllite-sandbox
  │     └── skilllite-agent (agent feature)
  ├── skilllite-swarm (swarm feature)
  └── skilllite-core

skilllite-agent
  ├── skilllite-core
  ├── skilllite-artifact（run artifact，默认 local feature）
  ├── skilllite-evolution
  ├── skilllite-fs
  ├── skilllite-sandbox
  └── skilllite-executor

skilllite-evolution
  ├── skilllite-core (含 planning 共享类型)
  ├── skilllite-fs
  └── skilllite-sandbox (L4 扫描)

skilllite-commands
  ├── skilllite-core
  ├── skilllite-evolution
  ├── skilllite-fs
  ├── skilllite-sandbox
  └── skilllite-agent (optional，evolution run 需 LlmClient)

skilllite-swarm
  └── skilllite-core

二、架构层面优化点

2.1 【高】主 Crate 职责过重 ✅ 已大幅缓解

现状（2026-04-16）：

  • skilllite 主包约 ~5,700 行 （thin 入口 + MCP / stdio_rpc / artifact-serve wiring 等仍集中于此，较 2026-03 统计上升属预期）
  • skilllite-commands 已拆成独立 crate（~7,300 行），承担各子命令实现
  • 命令注册表模式已实现：CommandRegistry + dispatch::register_all，新增命令通过 register 注册
  • lib.rs 仅负责 CLI 解析、注册表构建、reg.dispatch(&cli.command) 分发

遗留：

  • stdio_rpc、mcp 仍在 skilllite 内，可考虑后续抽成独立 crate
  • 主二进制仍包含 protocol、mcp、stdio_rpc 等协议层代码

2.2 【高】技能发现逻辑 ✅ 已统一

现状（2026-03-01 已完成）：

  • skilllite-core::skill::discovery 提供统一接口：
    • discover_skills_in_workspace(workspace, search_dirs?) -> Vec<PathBuf>
    • discover_skill_dirs_for_loading(workspace, search_dirs?) -> Vec<String>（供 load_skills 使用）
  • 搜索目录常量 SKILL_SEARCH_DIRS 集中定义：.skills, skills, .agents/skills, .claude/skills, .
  • skill add、chat、agent-rpc 均复用 core 的 discovery 模块

遗留 ：skilllite/commands/skill/add/discovery.rs 中的 discover_skills 为 add 命令的薄封装，内部调用 discover_skills_in_workspace，可考虑后续内联简化

2.3 【高】跨 Crate 类型转换 ✅ 已迁移

现状（2026-03-16）：

  • metadata_into_hint 已迁移至 skilllite-commands/src/security.rs
  • 将 SkillMetadata (core) 转为 MetadataHint (sandbox)，由 commands 作为胶水层实现
  • 主 crate 不再承担类型转换逻辑，职责更清晰

遗留 ：若后续有更多类似转换，可考虑统一放到 skilllite-commands 的 common 或 types 模块

2.4 【中】skilllite-agent 体积过大 ⚠️ 需持续关注

现状（2026-04-16）：

  • evolution 已拆成独立 crate skilllite-evolution，通过 EvolutionLlm trait 与 agent 交互
  • agent workspace Rust ~22.6k 行 （较 2026-03 统计显著增长：chat_session、agent_loop、builtin/tests 等均在千行以上）
  • 已依赖 skilllite-artifact（run-scoped 产物与 HTTP 路径由独立 crate 承载，利于控制 feature 面）
  • 共享类型 PlanningRule、SourceRegistry 等在 skilllite-core::planning
  • skilllite-fs 已抽离文件系统操作

遗留：

  • types.rs 已拆成 types/ 子模块 ✅
  • chat_session.rs（~1458 行）、task_planner.rs（~955 行） 仍是首要拆分候选；agent_loop/mod / execution / helpers 可继续按领域切分

2.5 【中】配置加载分散 ✅ 已部分统一

现状（2026-03-16 已优化）：

  • skilllite_core::config：配置加载、env、paths（data_root、chat_root 已集中）
  • skilllite_agent::types::AgentConfig：Agent 配置
  • skilllite_swarm：直接调用 skilllite_core::config::load_dotenv_from_dir
  • skilllite-assistant：load_dotenv_for_child 已改为调用 skilllite_core::config::parse_dotenv_walking_up，复用 core 解析逻辑

实现要点：

  • core 新增 parse_dotenv_from_dir、parse_dotenv_walking_up，返回 Vec<(String, String)> 供子进程 env 传入
  • load_dotenv、load_dotenv_from_dir 内部复用 parse_dotenv_content，解析规则统一

遗留 ：无。配置来源优先级已文档化于 docs/zh/ENV_REFERENCE.md、docs/en/ENV_REFERENCE.md 及 skilllite-core/config/mod.rs

2.6 【中】路径解析 ✅ 已部分统一

现状（2026-03-16）：

  • skilllite_core::paths 已集中 data_root()、chat_root() 逻辑，为全仓库唯一来源
  • 规则：SKILLLITE_WORKSPACE（绝对路径）→ 否则 ~/.skilllite；chat 根 = data_root/chat

遗留：

  • skilllite-assistant 中 find_project_root 与 executor 的 workspace 逻辑可能仍有重复
  • 建议 assistant 的 find_project_root 改为调用 core 或 executor 的接口
  • 建立路径约定文档，避免各 crate 自行实现

2.7 【中】dependency_resolver 命名易混淆

现状：

  • skilllite-core::skill::dependency_resolver：同步解析（whitelist、lock）
  • skilllite-agent::dependency_resolver：在 core 之上增加 LLM 推断

建议：

  • 将 agent 中的重命名为 llm_dependency_resolver 或 inferred_dependency_resolver，避免与 core 混淆

2.8 【低】skilllite-assistant 与主项目协议同步

现状（2026-04）：

  • assistant 不依赖 workspace 内 skilllite crate，通过子进程调用 skilllite agent-rpc
  • skilllite_bridge 已演化为多文件（如 integrations.rs 体量很大），路径与协议仍与引擎侧 手动对齐
  • 近期已完成 桌面与 core 技能发现一致 （TASK-2026-030 等），但 JSON-RPC / 事件 契约仍无单一 schema 真源

建议：

  1. 建立 协议变更检查清单 （与 ARCHITECTURE-REVIEW-2026-04.md §2.2「桌面未进 CI」结合：发版前至少手跑桌面 smoke）
  2. 中长期：将稳定 DTO 抽到 core 或 skilllite-protocol 小 crate，Tauri 仅引用类型定义（需评估构建链）
  3. 为 skilllite_bridge 增加 契约测试（golden JSON 或最小集成用例）

2.9 【低】文档与对外叙事维护

现状（2026-04）：

  • docs/en/ARCHITECTURE.md 与 ENTRYPOINTS-AND-DOMAINS.md 已反映 artifact crate、多入口 等（以仓库为准；若个别段落滞后，以 ARCHITECTURE-REVIEW-2026-04.md 为补遗）
  • 根 README.md：Pick your path 分流（英文 hub + 链到中文 START_PATHS）、进化叙事 改为「不降低安全门槛」（已移除 易过时的「自进化 Agent 逐框架对比表」）；桌面折叠区补充 Settings 页签 与截图 docs/images/assistant-settings-model-api.png
  • docs/en/START_PATHS.md / docs/zh/START_PATHS.md：心智分流入口，与 monorepo 代码同仓、叙事分路 策略一致

建议：

  1. 大改 crate 边界或默认 feature 时，同步 ARCHITECTURE.md + CHANGELOG + 根 README 中与安装/安全相关的句子（见 spec/docs-sync.md）
  2. 竞品对比类表格 谨慎恢复；若恢复需标注日期与数据来源，避免与「安全约束进化」主叙事打架

三、架构健康度评分

维度 评分 说明
依赖结构 9/10 无循环依赖，分层合理；commands 已拆出，主 crate 瘦身
职责划分 8/10 core/sandbox/executor/evolution/commands/fs 清晰；agent 体积略大
可扩展性 8/10 ProtocolHandler、ExtensionRegistry、CommandRegistry 设计良好
重复代码 8/10 技能发现、路径、fs、.env 解析已统一
测试覆盖 6/10 单元测试较多；集成测试、端到端测试不足
文档 8/10 多入口 + START_PATHS + README 分流；ARCHITECTURE-REVIEW-2026-04 承载工程缺口；仍需警惕 桌面/Tauri 与主 CI 不同步

四、优化优先级与实施建议

4.1 短期（1--2 周）

优先级 项 工作量 收益 状态
P0 统一技能发现逻辑 中 消除重复、行为一致 ✅ 已完成 (2026-03-01)
P0 更新 docs/en/ARCHITECTURE.md 低 文档与实现一致 ✅ 已更新 (2026-03-15)
P1 将 metadata_into_hint 迁移到 commands 低 减轻主 crate 胶水逻辑 ✅ 已完成
P1 将 evolution 拆成独立 crate 高 降低 agent 复杂度 ✅ 已完成 (2026-03-01)
P1 将 commands 拆成独立 crate 高 主 crate 瘦身 ✅ 已完成
P1 命令注册表模式 中 主 crate 可维护性 ✅ 已完成 (2026-03-02)

4.2 中期（1--2 个月）

优先级 项 工作量 收益 状态
P1 统一配置与 .env 加载（assistant 复用 core） 中 减少重复、清晰分层 ✅ 已完成
P2 拆分 agent types.rs 为 types/ 子模块 中 降低单文件复杂度 ✅ 已完成 (2026-03-16)
P2 Replan 校验与增强（sanitize_task_hints、auto_enhance_tasks） 中 重规划质量 待办（见 PLANNING-REPLAN-ANALYSIS）

4.3 长期（3--6 个月）

优先级 项 工作量 收益
P2 将 stdio_rpc、mcp 抽成独立 crate 中 主 crate 进一步瘦身
P2 增加集成测试与端到端测试 中 回归保障
P3 assistant 协议共享与兼容性测试 中 协议变更安全
P3 C 端本地安装包（dmg/pkg、msi、AppImage） 高 C 端分发形态（见 C-END-POSITIONING-AND-GAPS）

4.4 建议下一步优化方向

基于当前状态（types 已拆分），推荐优先级如下：

优先级 方向 工作量 收益 依据
1 拆分 chat_session.rs（~1458 行） 高 降低 agent 单点复杂度 §1.3、§2.4
2 拆分 task_planner.rs（~955 行） 与 agent_loop 子模块 高 规划与执行边界清晰 同上
3 CI 矩阵 / 桌面可选构建 （TASK-2026-003、见 ARCHITECTURE-REVIEW §2.2--2.3） 中 减少跨平台与「core 改了桌面未编」回归 board Ready
4 Replan 校验与增强 中 重规划质量 PLANNING-REPLAN-ANALYSIS
5 拆分 builtin/tests.rs （~1392 行）与桌面 integrations.rs（~1922 行） 中 测试与集成可维护性 §1.3
6 Artifact HTTP 鉴权模型与文档/OpenAPI 对齐 中 若暴露非 loopback，避免与 Swarm token 故事分裂 ARCHITECTURE-REVIEW §2.4

建议 ：优先 chat_session 或 agent_loop 垂直切片；与 TASK-2026-003（CI/矩阵）并行不冲突------前者降复杂度，后者降发布风险。

五、单文件过大需关注

文件 / 区域 行数（约） 建议
assistant skilllite_bridge/integrations.rs ~1922 按协议域（RPC、artifact、进化 UI）拆文件；与 §2.8 契约测试联动
chat_session.rs ~1458 会话状态机 vs RPC glue 分层
skilllite-evolution/scope.rs ~1431 与门禁/材料管线边界再切
extensions/builtin/tests.rs ~1392 按工具域或 fixture 拆目录
agent_loop/helpers.rs ~1275 与 mod / execution 重复逻辑下沉
sandbox/env/runtime_deps.rs ~1165 平台分支与「解析策略」分离
agent_loop/mod.rs ~1111 继续瘦身：仅编排，细节进子模块
skilllite-commands/evolution.rs ~1070 CLI 面与 lib 调用边界
agent_loop/execution.rs ~1021 执行策略与工具分发拆分
skilllite-core/skill/metadata.rs ~978 解析 / 校验 / 序列化分文件

六、未来需优化点（综合自关联文档）

6.1 自进化维度（14-EVOLUTION-ARCHITECTURE-ANALYSIS）

项 说明
External 学习与 Changelog 一致 external_learner 修改 rules.json 未反映到当次 txn 的 changelog
Memory 进化去重 当前增量追加，可考虑定期「knowledge 合并」全量去重
Evolution 门禁可观测性 L1--L3 门禁决策可增加结构化日志

6.2 规划与重规划（PLANNING-REPLAN-ANALYSIS）

项 说明
Replan 校验与增强 handle_update_task_plan 需应用 sanitize_task_hints、auto_enhance_tasks
空任务列表迭代优化 planner.is_empty() 时可设较小迭代上限
Replan 次数熔断 单轮对话 replan 次数上限（如 2--3 次）

6.3 C 端产品（C-END-POSITIONING-AND-GAPS）

项 说明
本地安装包 dmg/pkg、msi、AppImage，用户「下载→安装→打开」即用
Onboarding 流程 首次启动引导：API Key、模型选择、工作区
零配置默认 自动检测 Ollama / 本地模型

6.4 架构与工程

项 说明
统一 .env 加载 ✅ assistant 已复用 core 的 parse_dotenv_walking_up
Artifact HTTP 与安全门控 默认 feature 与 SKILLLITE_ARTIFACT_SERVE_ALLOW 等已文档化；非 loopback 绑定与 token 策略见 CHANGELOG [Unreleased] 与 ARCHITECTURE-REVIEW §2.4
集成/端到端测试 回归保障；桌面仍建议发版前手跑或加可选 CI job
stdio_rpc、mcp 抽离 主 crate 进一步瘦身（§2.1 遗留）
CI 多 OS / 矩阵 TASK-2026-003 仍在 Ready（tasks/board.md）

七、总结

已解决：

  1. 主 crate 职责过重 → commands 已拆出；主包仍承担协议/MCP 等，行数见 §1.2（stdio_rpc / mcp 抽离仍为长期项）
  2. 命令与实现紧耦合 → CommandRegistry 注册表模式
  3. 技能发现逻辑分散 → 已统一至 core discovery
  4. metadata_into_hint 在主 crate → 已迁至 skilllite-commands
  5. evolution 在 agent 内 → 已拆成 skilllite-evolution
  6. 路径解析分散 → core paths 已集中 data_root、chat_root
  7. 文件系统操作分散 → skilllite-fs 已抽离
  8. .env 解析在 assistant 重复 → 已复用 core 的 parse_dotenv_walking_up

待优化：

  1. 配置与 .env 加载重复 → assistant 已复用 core 的 parse_dotenv_walking_up
  2. agent types.rs 单文件过大 → 已拆成 types/ 子模块 ✅
  3. chat_session、task_planner 等单文件仍较大
  4. Replan 校验与增强
  5. 集成/端到端测试不足
  6. C 端本地安装包与 Onboarding

架构方向：

  • 保持当前多 crate 分层，依赖方向合理；artifact 与 agent 解耦大 blob 与 HTTP 面
  • 通过拆分与去重降低单点复杂度（优先 chat_session / agent_loop / 桌面 integrations）
  • 建立共享类型与路径约定，减少胶水代码；协议 DTO 长期可集中真源
  • evolution 通过 trait 与 agent 解耦；工程门禁（CI 矩阵、桌面 smoke）与代码结构同等重要

八、近期变更记录

2026-04-16 更新（本版）

变更 说明
规模数据刷新 Workspace Rust ~76.4k 行（统计口径见 §1.1）；各 crate 与 Top 文件表已按当前树更新
artifact 进依赖图 skilllite-agent → skilllite-artifact；与 2026-Q1 以来 artifact HTTP、run-scoped 存储等任务线一致（TASK-2026-025～028 等已 Done，见 tasks/board.md）
对外文档 根 README：Pick your path、START_PATHS、进化段落重述、桌面截图；不再维护「逐框架自进化对比表」
工程 backlog 指针 TASK-2026-003（CI 矩阵）仍为 Ready；ARCHITECTURE-REVIEW-2026-04.md 为 4 月工程真源

2026-03-16 更新（历史）

变更 说明
types.rs 拆分 拆成 types/ 子模块：string_utils、config、chat、feedback、event_sink、task、env_config，保持向后兼容
统一 .env 解析 core 新增 parse_dotenv_from_dir、parse_dotenv_walking_up；assistant 复用，消除重复实现
代码规模（当时） 总行数约 ~50.3k；主 crate 已瘦身
skilllite-commands / skilllite-fs 独立 crate；路径与 metadata_into_hint 等迁移见上文 §2.x

2026-03-01 evolution 独立 crate 拆分

变更 说明
新增 skilllite-evolution 自进化引擎（prompts、skills、memory）独立为 crate
EvolutionLlm trait agent 通过 EvolutionLlmAdapter 实现
共享类型上移 PlanningRule、SourceRegistry 迁至 skilllite-core::planning

本报告 §1 规模数据为 2026-04-16 在仓库内 find+wc 抽样；细节以当时 main 为准。战略与发布清单另见 todo/ARCHITECTURE-REVIEW-2026-04.md 与 tasks/board.md。

相关推荐
进击的荆棘2 小时前
C++起始之路——AVL树的实现
开发语言·数据结构·c++·stl·avl
斌味代码2 小时前
Elasticsearch 性能调优实战：内存管理、连接池与查询优化全指南
大数据·elasticsearch·jenkins
进击的荆棘2 小时前
C++起始之路——红黑树的实现
开发语言·数据结构·c++·stl·红黑树
AI先驱体验官2 小时前
BotCash：AI智能体知识管理新基建，GitNexus带来的技术范式转移
大数据·运维·人工智能·aigc·交互
海南java第二人3 小时前
Flink 核心概念深度解析：从字符串大小写转换看 Job 与 Task 的本质区别
大数据·flink
橘子编程3 小时前
Flink从入门到精通：全面实战指南
大数据·flink
SeaTunnel3 小时前
深度解析 Apache SeaTunnel 核心引擎三大技术创新：高可靠异步持久化与 CDC 架构优化实战
大数据·数据库·架构·apache·seatunnel
DolphinScheduler社区4 小时前
第 8 篇｜Apache DolphinScheduler 与 Flink Spark 数据引擎的边界、协同与最佳实践
大数据·flink·spark·开源·apache·海豚调度·大数据工作流调度
黄焖鸡能干四碗4 小时前
企业元数据梳理和元数据管理方案（PPT方案）
大数据·运维·网络·分布式·spark
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点03一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛042026 年 AI 编程助手全面对比评测：Cursor vs Copilot vs Claude Code vs GitHub Copilot Free05GPT-6发布日深度解析-Symphony架构200万Token实战06基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南07GPT-6核心能力解析及与现有主流大模型对比08AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析09零成本！Ollama本地部署国产大模型全指南（支持Kimi-K2.5/GLM-5/Qwen，新手秒上手）10从限购到畅通：GLM-5.1 Coding Plan接入攻略