一张图,喂不饱所有人

同一个系统,不同人关心完全不同的侧面:程序员想知道代码怎么分包,运维想知道跑在哪台机器,用户只关心"它到底给我带来什么"。硬要用一张图全部说清,结果是谁都看不懂。

4+1 = 4 个视图 + 1 个场景

四角是四个视图,中间的「场景」是把它们黏在一起的那个 +1。

xskill 三个模块,一句话各是什么

xskill 做的事:把 coding agent 的轨迹(trajectory)自动炼成可复用的技能(skill)——"一个人解决,人人复用"。这条流水线分三段:

场景视图 Scenarios = story

逻辑视图 Logical → 类图

classDiagram
    class Ingester {
        +scan_and_bridge()
    }
    Ingester <|-- TraeIngester
    Ingester <|-- JsonlIngester
    Ingester <|-- SqliteIngester
    class Trajectory {
        +traj_id
        +session_id
        +markdown
    }
    class DirectoryWatcher {
        +scan_once()
        +state_machine
    }
    class AtomTask {
        +atom_id
    }
    class Skill {
        +name
        +SKILL_md
        +branch_baby_main
    }
    class Canary {
        +ux_score
        +promote_or_reject()
    }
    Ingester --> Trajectory : produces
    DirectoryWatcher --> Trajectory : consumes
    DirectoryWatcher --> AtomTask : splits
    AtomTask --> Skill : cluster_merge
    Skill --> Canary : canary
        

进程视图 Process → 时序图

sequenceDiagram
    autonumber
    participant Bob as Agent(Bob)
    participant I as Ingester ①
    participant W as Watcher ②
    participant S as Skill 仓库 ②
    participant C as Canary ③
    participant Al as 同事 Alice ③
    Bob->>I: 产生轨迹 (vscdb/jsonl)
    I->>W: 桥接 traj_*.md (discovered)
    W->>W: split → index → cluster
    W->>S: 归并出 baby skill
    S->>C: 达阈值 → 进 staging 灰度
    C->>Al: 按概率分流试用
    Al-->>C: 回传 ux_score
    C->>S: 收齐样本 → promote 到 main
    S->>Al: install 到 ~/.claude/skills 等
        

开发视图 Development → 包结构

物理视图 Physical → 部署图

类图 / 时序图 / story 与 4+1 的关系

它们不是三个并列的"图",而是各自挂在不同视图上的表达工具:

🥥 记忆法:story 给出题目,类图说明"长什么样",时序图说明"怎么跑起来"。

五个视图,各回答一句话

写 xskill 的 story 时:先用场景(+1)把主线讲清,再分别用类图(逻辑)和时序图(进程)把"长什么样 / 怎么跑"补齐,开发与物理视图交代给程序员和运维。🥥

↓ 继续翻 · 深入「模块① 轨迹的入口与索引」的 4+1 →

驱动这个模块的 story

先讲清「①要支撑哪几条故事」,其余四视图都为它服务。

类图:① 由什么构成

两层:入口层 ecosystems/(每家 agent 一个适配器) + 索引层 pipeline/。两层通过「桥接目录 + 统一格式」解耦。

classDiagram
    class Ingester {
        +scan_and_bridge()
        +start()
        +stop()
    }
    Ingester <|-- JsonlIngester
    Ingester <|-- SqliteIngester
    Ingester <|-- CCSessionIngester
    Ingester <|-- TraeIngester
    class Trajectory {
        +traj_id
        +session_id
        +markdown
    }
    class DirectoryWatcher {
        +scan_once()
    }
    class AtomTask {
        +atom_id
    }
    class AtomTaskStore {
        +index_pkl
    }
    class Registry {
        +trajectories_table
    }
    Ingester --> Trajectory : bridge
    DirectoryWatcher --> Trajectory : discover
    DirectoryWatcher --> AtomTask : split
    AtomTask --> AtomTaskStore : store
    DirectoryWatcher --> Registry : status
    

时序图:一条轨迹的旅程

两个独立循环:Ingester 各自轮询桥接 / Watcher 线程池推进 split+index。

sequenceDiagram
    autonumber
    participant AG as Agent 本地目录
    participant IN as Ingester
    participant BR as 桥接目录
    participant W as DirectoryWatcher
    participant R as Registry / Store
    AG->>IN: 落盘原生轨迹
    IN->>IN: dedup(seen) 去重
    IN->>BR: 写 traj md + json(meta)
    W->>BR: _scan_once 轮询发现
    W->>R: discover → discovered
    W->>W: split → 拆 AtomTask
    W->>R: split_done
    W->>W: embed → index.pkl
    W->>R: indexed（交给模块②）
    

状态机:registry 里的 status 流转

flowchart LR
    D[discovered] -->|split| S[splitting] --> SD[split_done] -->|embed| I[indexed]
    D -->|校验不合格| F[filtered]
    S -->|异常| E[error] -->|retry 带计数| D
    I --> C["② clustering …"]
    style I fill:#E2F1F2,stroke:#0E7C86
    style C fill:#FCE5DC,stroke:#E0613B
    

代码怎么组织 · 程序员在哪改

依赖方向:pipeline 不依赖具体 agent;ecosystems 只负责「产出统一 traj_*.md」——这正是类图里那条 produces/consumes 边界。

数据从哪进 · 落在哪 · 跑在哪

模块① 一句话回顾

模块① 完。模块②(生成 Skill) 与 模块③(评价与推送) 将照同一结构展开。🥥

← 回头再看