ZhenYi/gitdataai

Fork 0

ZhenYi 86d7cd2fe1 chore: add gene.md and public fonts

2026-05-17 17:32:39 +08:00

19 KiB

Raw Blame History

Gene 方案

这份文档针对什么

这个项目里，Skill 已经不是一个抽象概念，而是完整的业务实体：

后端有 project_skill 持久化模型
Git 同步会扫描仓库里的 SKILL.md
聊天构建会把启用的技能注入上下文
前端有技能列表、详情、编辑、删除、扫描
内建技能模板也已经存在

所以这里不应该“用 Gene 替换 Skill”，而应该是：

Skill 继续负责执行和交付能力
Gene 作为新增元层，负责让技能可演化、可比较、可追踪、可继承

设计结论

Gene 的正确位置不是新的执行系统，也不是 Skill 的替代品，而是 Skill 的生命周期治理层。

Skill = 可执行内容 + 上下文注入 + 业务交付
Gene = 演化族 + 版本谱系 + 评估记录 + 选择记录

更准确地说：

Skill 是可执行的技能内容，负责被扫描、编辑、启用、注入和交付能力。

Gene 是 Skill 的演化族，负责组织一个 Skill 在项目内的版本、来源、谱系、评估和选择记录。

GeneRevision 是 Gene 下的不可变版本节点，绑定到某个 Skill 内容快照。

GeneEvaluation 是对某个 GeneRevision 的评估结果。

GeneSelection 是对当前有效 GeneRevision 的显式选择记录。

项目现状

Skill 已经落在这些地方

libs/models/projects/project_skill.rs
- 定义了 project_skill 实体
- 已包含 source
- 已包含 repo_id
- 已包含 commit_sha
- 已包含 blob_hash
- 已包含 content
- 已包含 metadata
- 已包含 enabled
libs/git/hook/sync/mod.rs
- 扫描仓库中的 SKILL.md
- 从 frontmatter 解析 name、description、license、compatibility
- 用 commit_sha 和 blob_hash 做增量同步
libs/agent/skills/templates.rs
- 内建技能模板已经编译进程序
- 这些模板本质上是“系统内置 Skill”
libs/agent/chat/message_builder.rs
- 读取项目中启用的技能
- 把技能注入对话上下文
- 和 embedding / perception 一起影响模型行为
src/app/project/skills/*
- 已有技能管理 UI
- 能查看、编辑、删除、扫描技能

现有 Skill 的问题

当前 Skill 已经能用，但还不够“可进化”：

只有内容，没有明确的演化关系
只有当前状态，没有谱系
只有启用/禁用，没有版本选择
只有来源信息，没有变体比较
只有同步时间和 blob hash，没有“为什么变成这样”的记录
有评估空间，但没有评估结果和版本绑定
有扫描和编辑能力，但没有可审计的回滚与选择记录

换句话说，现在的 Skill 更像“静态资产”，还不是“进化单元”。

设计原则

1. Skill 仍然是唯一执行实体

Skill 继续负责：

被扫描
被编辑
被启用或禁用
被注入聊天上下文
交付实际能力

Gene 不直接执行任务，不直接调用工具，不直接参与上下文拼装。

2. Gene 只管理 Skill 的演化元数据

Gene 管理的是：

版本
来源
父子关系
变体
评估
选择
淘汰
回滚

它不应该成为第二套 Skill 系统。

3. GeneRevision 必须不可变

Skill 可以是当前可编辑对象。

GeneRevision 是不可变演化节点。一旦创建，不应再修改：

内容快照
父代关系
来源信息
commit_sha
blob_hash
content_hash
mutation_reason
mutation_diff

后续任何内容变化、prompt 变化、工具权限变化、上下文注入规则变化，都应该产生新的 GeneRevision。

4. Evaluation 必须绑定到具体 Revision

评估不是评价一个抽象的 Gene，而是评价某个具体版本。

因此：

GeneEvaluation 必须绑定 revision_id。

否则同一个 Gene 下存在多个版本时，评估结果无法精确归因。

5. Selection 必须显式记录

如果系统选择了某个版本作为当前有效版本，必须记录：

选中了哪个 revision
为什么选它
谁选的
依据什么策略选的
什么时候选的
是否仍然 active

这能支持审计、回滚和后续自动选择。

6. SKILL.md 仍然是仓库内 Skill 的事实来源

仓库里的 SKILL.md 仍然是 Git 同步的事实来源。

Gene 只记录它如何演化，不改变仓库同步的基本语义。

核心概念

Skill

Skill 是现有业务实体。

它负责：

可执行内容
上下文注入
用户可见编辑
Git 扫描
启用 / 禁用
业务交付

Gene

Gene 是某个 Skill 的演化族。

它负责组织这个 Skill 的生命周期：

这个能力从哪里来
经历过哪些版本
有哪些变体
评估结果如何
当前选择哪个版本
哪些版本被淘汰

GeneRevision

GeneRevision 是 Gene 下的一个不可变版本节点。

它绑定某个 Skill 的内容状态，例如：

skill_id
skill_slug
commit_sha
blob_hash
content_hash
content_snapshot_ref

GeneEvaluation

GeneEvaluation 是对某个 GeneRevision 的评估结果。

它回答：

这个版本好不好？
在哪个数据集上测的？
指标是什么？
是否通过？
成本和延迟如何？
失败样本是什么？

GeneSelection

GeneSelection 是对当前有效版本的显式选择记录。

它回答：

当前选中哪个 revision？
为什么选它？
谁选的？
依据什么策略？
是否还在生效？

Gene 和 Skill 的关系

可以把关系理解为：

Gene 1 ── has many ── GeneRevision
GeneRevision ── references ── Skill snapshot
GeneRevision ── has many ── GeneEvaluation
Gene ── has one active ── GeneSelection
GeneSelection ── selects ── GeneRevision
Skill ── executes ── actual capability

也就是说：

Skill 解决“能不能做”
Gene 解决“该保留哪个版本、为什么保留、怎么变体、怎么传播”
GeneRevision 解决“这个能力在某一刻具体长什么样”
GeneEvaluation 解决“这个版本是否足够好”
GeneSelection 解决“当前应该用哪个版本”

数据模型

ProjectGene

ProjectGene
  - gene_id
  - project_uuid
  - skill_id
  - skill_slug
  - name
  - description
  - owner
  - status
  - created_at
  - updated_at

说明：

gene_id 是 Gene 的唯一标识
project_uuid 绑定项目
skill_id / skill_slug 绑定现有 Skill
status 可为 active、archived、deprecated
owner 用于责任归属

ProjectGeneRevision

ProjectGeneRevision
  - revision_id
  - gene_id
  - version
  - parent_revision_id
  - origin
  - source
  - skill_id
  - skill_slug
  - commit_sha
  - blob_hash
  - content_hash
  - content_snapshot_ref
  - mutation_reason
  - mutation_diff
  - created_by
  - created_at

说明：

revision_id 是内部唯一版本节点
version 是用户可见版本号，不承担唯一性职责
parent_revision_id 表示单父版本关系
origin 表示来源，例如 git_sync、manual_edit、builtin_template、migration
source 复用现有 Skill.source
commit_sha / blob_hash 记录 Git 来源
content_hash 记录内容稳定标识
content_snapshot_ref 用于指向当时的内容快照
mutation_reason 记录为什么产生这个版本
mutation_diff 记录相对父版本的变化

ProjectGeneEvaluation

ProjectGeneEvaluation
  - evaluation_id
  - gene_id
  - revision_id
  - eval_name
  - evaluator
  - dataset_ref
  - dataset_version
  - metric_name
  - score
  - threshold
  - passed
  - sample_count
  - failure_count
  - latency_ms_avg
  - cost
  - result_summary
  - result_json
  - evaluated_at

说明：

revision_id 必填
score 不应脱离 metric_name 单独解释
threshold 用于判断是否通过
sample_count 和 failure_count 用于判断评估可信度
result_json 存放详细结果、失败样本、分项指标等

ProjectGeneSelection

ProjectGeneSelection
  - selection_id
  - gene_id
  - selected_revision_id
  - project_uuid
  - policy
  - reason
  - selected_by
  - selected_at
  - active

说明：

同一个 gene_id 同一时间只能有一个 active selection
policy 可以是 manual、latest_passed、best_score、stable_low_cost
reason 用于审计和回滚
selected_by 可以是用户、系统或自动策略

关于 GeneLineage

MVP 阶段不单独引入 GeneLineage 表。

原因是：如果每个版本只有一个父版本，ProjectGeneRevision.parent_revision_id 已经足够表达谱系。

MVP：单父版本树
Future：多父 DAG / merge / cross-skill inheritance

未来如果需要支持合并、交叉继承或复杂谱系，再引入：

ProjectGeneEdge
  - parent_revision_id
  - child_revision_id
  - edge_type
  - mutation_reason
  - mutation_diff

关于 Variant

Variant 是 Gene 的重要能力，但不一定是 MVP 的独立表。

这些变化都可以先作为新的 GeneRevision 表达：

更严格的 prompt
更短的 prompt
不同工具权限
不同上下文注入规则
不同评估阈值

MVP 中：

不单独引入 ProjectGeneVariant。
所有变体先作为 GeneRevision 表达。

当系统需要以下能力时，再引入 GeneExperiment / GeneVariant：

A/B 实验
并行流量分配
实验分组
统计显著性
多候选版本同时比较

Git 同步流程

当前 Git 同步已经会扫描仓库中的 SKILL.md，并使用 commit_sha 和 blob_hash 做增量同步。

引入 Gene 后，Git 同步流程建议变成：

当 Git 同步发现 SKILL.md 的 blob_hash 变化时：

1. 正常创建或更新 project_skill。
2. 查找该 skill 对应的 project_gene。
3. 如果不存在 project_gene，则创建一个。
4. 查找该 gene 下最新的 project_gene_revision。
5. 如果新的 blob_hash / content_hash 不同，则创建新的 GeneRevision。
6. 将上一 revision 设为 parent_revision_id。
7. mutation_reason 默认记录为 git_sync。
8. mutation_diff 记录上一个 SKILL.md 与当前 SKILL.md 的 diff。
9. 不自动改变 selected_revision，除非选择策略明确允许。

关键约束：

Git sync 可以产生新的 GeneRevision。
Git sync 不应默认切换当前线上选中版本。

这样可以避免仓库变更自动导致线上行为漂移。

手动编辑流程

当用户在 UI 中编辑 Skill 内容时：

1. 更新 project_skill。
2. 计算新的 content_hash。
3. 查找对应 project_gene。
4. 创建新的 project_gene_revision。
5. parent_revision_id 指向编辑前的 revision。
6. mutation_reason 记录为 manual_edit。
7. mutation_diff 记录编辑前后的差异。
8. 可选择是否自动把新 revision 标记为 selected。

建议 MVP 默认：

手动编辑后创建新 revision，但不自动覆盖 active selection。
由用户显式选择是否启用该 revision。

如果产品希望“编辑即生效”，也可以让 selection 同步更新，但必须记录：

policy = manual_edit_auto_select
reason = "User edited skill content"

聊天上下文注入流程

现有流程中，libs/agent/chat/message_builder.rs 读取项目中启用的 Skill，并把技能注入对话上下文。

引入 Gene 后，这个原则不变：

message_builder 不直接读取 Gene 内容。
message_builder 仍然读取启用的 Skill。
Gene 只影响哪个 Skill revision 被视为推荐版本或当前选中版本。

如果未来要让 GeneSelection 影响上下文注入，推荐路径是：

GeneSelection
  -> resolve selected GeneRevision
  -> materialize / update project_skill
  -> message_builder reads project_skill

不建议：

message_builder
  -> read Gene
  -> assemble prompt

因为这会让 Gene 偷偷变成新的执行层。

API 设计

MVP API 可以包括：

GET    /projects/:project_uuid/skills/:skill_id/gene
POST   /projects/:project_uuid/skills/:skill_id/gene

GET    /projects/:project_uuid/genes/:gene_id/revisions
POST   /projects/:project_uuid/genes/:gene_id/revisions

GET    /projects/:project_uuid/genes/:gene_id/evaluations
POST   /projects/:project_uuid/genes/:gene_id/evaluations

GET    /projects/:project_uuid/genes/:gene_id/selection
POST   /projects/:project_uuid/genes/:gene_id/select

选择接口示例：

{
  "selected_revision_id": "rev_123",
  "policy": "manual",
  "reason": "Higher pass rate on regression eval"
}

评估写入接口示例：

{
  "revision_id": "rev_123",
  "eval_name": "skill_regression_eval",
  "dataset_ref": "datasets/skill-regression-v1",
  "dataset_version": "2026-01-01",
  "metric_name": "task_success_rate",
  "score": 0.92,
  "threshold": 0.85,
  "passed": true,
  "sample_count": 100,
  "failure_count": 8,
  "latency_ms_avg": 1200,
  "cost": 0.34
}

UI 设计

Gene 不替代现有技能管理 UI。

推荐把它放在 Skill Detail 页面中的一个“演化”标签页。

Skill Detail
  - 基本信息
  - 内容编辑
  - 启用状态
  - Evolution / Gene
      - 当前选中 revision
      - 版本列表
      - 父子关系
      - 每个版本的 diff
      - 每个版本的评估结果
      - 选择按钮
      - 回滚按钮

MVP UI 可以先做只读：

1. 显示 Gene 信息
2. 显示 Revision 列表
3. 显示每个 Revision 的来源、时间、commit_sha、blob_hash
4. 显示相邻 Revision 的 diff

第二阶段再加入：

1. 手动选择 revision
2. 回滚 revision
3. 展示评估结果
4. 根据评估结果推荐版本

评估指标

Gene 的核心不是“更像生物学”，而是“更像可验证的演化对象”。

每个 GeneRevision 都应该支持评估，例如：

任务成功率
失败率
平均耗时
误触发率
人工接受率
回滚率
成本
稳定性
安全失败数
用户满意度

没有评估的 Gene，只是重命名后的 Skill 管理。

选择策略

如果存在多个 GeneRevision，系统应该能选择更优版本。

MVP 阶段不做自动选择，只做人工选择和可审计回滚。

后续选择规则可以逐步加入：

1. 先看是否通过基础测试
2. 再看近期成功率
3. 再看失败率
4. 再看成本
5. 再看延迟
6. 再看稳定性
7. 再看人工接受率

可选策略：

manual
latest_passed
best_score
stable_low_cost
lowest_latency
highest_acceptance_rate

自动选择必须满足：

有评估数据
有样本量
有失败分类
有回滚机制
有选择审计记录

Migration 策略

对于已有的 project_skill，可以执行一次初始化迁移：

对每个 project_skill：

1. 创建 project_gene。
2. 创建初始 project_gene_revision。
3. revision.origin = migration。
4. revision.skill_id = project_skill.id。
5. revision.skill_slug = project_skill.slug。
6. revision.commit_sha = project_skill.commit_sha。
7. revision.blob_hash = project_skill.blob_hash。
8. revision.content_hash = hash(project_skill.content)。
9. revision.content_snapshot_ref = 当前 Skill 内容快照。
10. 创建 active project_gene_selection。
11. selected_revision_id = 初始 revision。
12. policy = migration。
13. reason = "Initial gene selection from existing project_skill"。

这样现有 Skill 都可以无损进入 Gene 生命周期模型。

落地判断标准

一个能力如果只是：

能被扫描
能被编辑
能被启用或禁用
能被注入上下文
能交付业务能力

它还是 Skill。

一个能力如果还能：

被追踪来源
被比较版本
被记录变体
被评估好坏
被继承和淘汰
被审计选择
被安全回滚

它才进入 Gene 管理范畴。

非目标

Gene MVP 不做以下事情：

1. 不替换 project_skill。
2. 不改变 SKILL.md 作为仓库技能事实来源的地位。
3. 不直接参与聊天上下文构建。
4. 不直接执行工具调用。
5. 不自动改写 Skill 内容。
6. 不在没有评估和回滚机制的情况下自动切换线上版本。
7. 不一开始支持复杂遗传算法、交叉、随机变异或自动进化。
8. 不新增一套和 Skill 并列的执行 UI。

风险与约束

1. Gene 变成另一个 Skill

风险：

Gene 中也开始存 prompt、工具权限、上下文注入规则，并且聊天时直接读取 Gene。

规避：

Gene 不存放执行主内容。
执行内容仍然归 Skill 所有。
GeneRevision 只引用或快照 Skill 的某个状态。

2. 评估绑定到可变 Skill

风险：

评估结果只挂在 skill_id 上，Skill 内容变化后，评估记录失真。

规避：

评估必须绑定 revision_id + content_hash / blob_hash。

3. 自动选择过早上线

风险：

没有足够评估数据时自动切换版本，导致线上行为漂移。

规避：

MVP 只做人工选择和可审计回滚。
自动选择必须依赖稳定评估和回滚机制。

4. mutation_diff 膨胀

风险：

每个版本都保存完整 diff，长期可能膨胀。

规避：

MVP 可直接存 mutation_diff。
后续引入 mutation_diff_ref 或对象存储引用。

5. version 语义不清

风险：

version 同时承担用户展示、唯一标识、Git 版本等多种含义。

规避：

revision_id = 系统内部唯一版本节点
version = 用户可见版本号
commit_sha / blob_hash = Git 来源版本标识
content_hash = 内容稳定标识

最终结论

这个项目已经具备 Skill 的完整工程闭环。

Gene 的正确位置不是替换它，而是补上它缺失的演化层：

Skill 负责落地执行
Gene 负责生命周期治理
GeneRevision 负责不可变版本节点
GeneEvaluation 负责版本质量判断
GeneSelection 负责显式选择和回滚

两者结合后，技能系统才从“可配置”变成“可进化”。

19 KiB Raw Blame History Unescape Escape