This commit is contained in:
xuhd committed 2026-05-18 10:25:51 +08:00
commit 8f88427d4e
19 files changed
+751 -76

No files matched your search

@@ -228,6 +228,7 @@ FastAPI application on port 8001 with health check at `GET /health`. Set `GATEWA
| **Memory V2** (`/api/memory/v2`) | `GET /` - builtin data (USER.md/MEMORY.md); `POST/PUT/DELETE /entries` - add/replace/remove entry; `GET/PATCH/DELETE /config` - effective config + per-user overrides; `POST /search` - Hindsight recall/reflect proxy |
| **Agents** (`/api/agents`) | `GET /` - list built-in, owned, and published agents; `POST /` - create user-owned agent; `GET/PUT/DELETE /{id}` - read/update/delete by stable agent id; `GET /check` - validate non-empty display name (duplicates allowed) |
| **Skills** (`/api/skills`) | `GET /` - list skills (optional `search` fuzzy-name + `tag_id` filters; each item carries `tags`); `GET /{name}` - details; `PUT /{name}` - update enabled; `POST /install` - install from .skill archive (accepts standard optional frontmatter like `version`, `author`, `compatibility`) |
| **Skills** (`/api/skills`) | `GET /` - list skills (optional `search` fuzzy-name + `tag_id` filters; each item carries `tags` + owner-authored `detail`); `GET /{name}` - details; `PUT /{name}` - update enabled; `PUT /{name}/detail` - set the long-form `detail` text (custom skill: owner or admin; built-in/public: admin only — materializes a `skills` row on demand); `POST /install` - install from .skill archive (accepts standard optional frontmatter like `version`, `author`, `compatibility`) |
| **Memory** (`/api/memory`) | `GET /` - memory data; `POST /reload` - force reload; `GET /config` - config; `GET /status` - config + data |
| **Agents** (`/api/agents`) | `GET /` - list built-in, owned, and published agents (optional `search` + `tag_id` filters; each item carries `tags`); `POST /` - create user-owned agent; `GET/PUT/DELETE /{id}` - read/update/delete by stable agent id; `GET /check` - validate non-empty display name (duplicates allowed) |
| **Tags** (`/api/tags`) | `GET /` - list tags (optional `tag_type` filter; open to all); `POST /` - create tag (admin); `PUT /{id}` / `DELETE /{id}` - update/delete tag (admin); `GET /assignments/{target_type}/{target_id}` - tags on a resource; `PUT /assignments/{target_type}/{target_id}` - replace a resource's tags (admin). Tags are typed `agent`/`skill`/`scheduled_task` and may only tag resources of their own type. |
@@ -96,6 +96,7 @@ class SkillResponse(BaseModel):
owner_user_id: str | None = Field(default=None, description="Custom skill owner (null = built-in or legacy)")
published: bool = Field(default=False, description="Whether the owner has made this skill visible to other users")
builtin: bool = Field(default=False, description="True when owner_user_id is null (no human owner)")
detail: str | None = Field(default=None, description="Human-authored long-form detail text (Markdown), editable by owner/admin")
tags: list[dict] = Field(default_factory=list, description="Tags assigned to this skill")
@@ -180,10 +181,12 @@ def _skill_to_response(skill: Skill, ownership: dict[str, Any] | None = None) ->
owner_user_id: str | None = None
published = False
builtin = skill.category != SkillCategory.CUSTOM
detail: str | None = None
if ownership is not None:
owner_user_id = ownership.get("owner_user_id")
published = bool(ownership.get("published", False))
builtin = bool(ownership.get("builtin", owner_user_id is None))
detail = ownership.get("detail")
return SkillResponse(
name=skill.name,
@@ -201,6 +204,7 @@ def _skill_to_response(skill: Skill, ownership: dict[str, Any] | None = None) ->
owner_user_id=owner_user_id,
published=published,
builtin=builtin,
detail=detail,
)
@@ -251,7 +255,9 @@ async def list_skills(
# Public/built-in skills (no DB row) are visible to everyone.
# Custom skills must have an ownership record in the visible set.
if skill.category != SkillCategory.CUSTOM:
responses.append(_skill_to_response(skill))
# Built-in skills usually have no DB row, but an admin-authored
# ``detail`` annotation materializes one — surface it when present.
responses.append(_skill_to_response(skill, ownership.get(skill.name)))
continue
record = ownership.get(skill.name)
if record is None:
@@ -828,7 +834,12 @@ async def rollback_custom_skill(skill_name: str, request: SkillRollbackRequest,
summary="Get Skill Details",
description="Retrieve detailed information about a specific skill by its name.",
)
async def get_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> SkillResponse:
async def get_skill(
skill_name: str,
request: Request,
config: AppConfig = Depends(get_config),
skill_store: SkillStore = Depends(get_skill_store),
) -> SkillResponse:
try:
skill_name = skill_name.replace("\r\n", "").replace("\n", "")
skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
@@ -837,7 +848,9 @@ async def get_skill(skill_name: str, config: AppConfig = Depends(get_config)) ->
if skill is None:
raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
return _skill_to_response(skill)
# Attach ownership (owner/published/detail) when the caller may see it.
ownership = await skill_store.get_visible(skill_name, _current_user_id(request))
return _skill_to_response(skill, ownership)
except HTTPException:
raise
except Exception as e:
@@ -926,6 +939,71 @@ async def update_skill(skill_name: str, request: SkillUpdateRequest, config: App
raise HTTPException(status_code=500, detail=f"Failed to update skill: {str(e)}")
class SkillDetailRequest(BaseModel):
"""Request body for setting a skill's human-authored detail text."""
detail: str = Field(default="", description="详情说明文本,支持 Markdown;传空字符串表示清空")
class SkillDetailResponse(BaseModel):
"""Response model for the skill-detail update endpoint."""
name: str = Field(..., description="Skill name")
detail: str | None = Field(default=None, description="Persisted detail text (null when cleared)")
@router.put(
"/skills/{skill_name}/detail",
response_model=SkillDetailResponse,
summary="Update Skill Detail",
description="设置技能的详情说明。自定义技能由其所有者或管理员编辑;内置/公开技能仅管理员可编辑。",
)
async def update_skill_detail(
skill_name: str,
body: SkillDetailRequest,
request: Request,
config: AppConfig = Depends(get_config),
skill_store: SkillStore = Depends(get_skill_store),
) -> SkillDetailResponse:
try:
skill_name = skill_name.replace("\r\n", "").replace("\n", "")
user_id = _current_user_id(request)
is_admin = _is_admin_user(request)
skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
skill = next((s for s in skills if s.name == skill_name), None)
if skill is None:
raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
# Empty / whitespace-only input clears the annotation.
detail_value: str | None = body.detail.strip() or None
if skill.category == SkillCategory.CUSTOM:
# Owner edits their own skill; admins may edit anyone's.
_record, mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
if mode == "admin":
updated = await skill_store.update_admin(skill_name, {"detail": detail_value})
else:
updated = await skill_store.update(skill_name, user_id, {"detail": detail_value})
else:
# Built-in / public skill — only admins may annotate it. These carry
# no DB row by default, so materialize one before writing detail.
if not is_admin:
raise HTTPException(status_code=403, detail="Only admin users can edit built-in skill details")
if await skill_store.get_any(skill_name) is None:
await skill_store.ensure_legacy({"name": skill_name, "owner_user_id": None, "published": True})
updated = await skill_store.update_admin(skill_name, {"detail": detail_value})
if updated is None:
raise HTTPException(status_code=500, detail="Failed to persist skill detail")
return SkillDetailResponse(name=skill_name, detail=updated.get("detail"))
except HTTPException:
raise
except Exception as e:
logger.error("Failed to update detail for %s: %s", skill_name, e, exc_info=True)
raise HTTPException(status_code=500, detail=f"Failed to update skill detail: {str(e)}")
class SkillPinRequest(BaseModel):
pinned: bool = Field(..., description="Whether to pin or unpin the skill")
@@ -0,0 +1,42 @@
"""Add detail column to skills table.
Revision ID: 20260518_01
Revises: 20260515_01
Create Date: 2026-05-18
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
from sqlalchemy import inspect
revision = "20260518_01"
down_revision = "20260515_01"
branch_labels = None
depends_on = None
def _has_table(table_name: str) -> bool:
inspector = inspect(op.get_bind())
return table_name in inspector.get_table_names()
def _has_column(table_name: str, column_name: str) -> bool:
if not _has_table(table_name):
return False
inspector = inspect(op.get_bind())
return any(col["name"] == column_name for col in inspector.get_columns(table_name))
def upgrade() -> None:
# ``skills`` may not exist yet on a brand-new DB — create_all handles that
# case with the column already present, so only patch existing tables.
if _has_table("skills") and not _has_column("skills", "detail"):
op.add_column("skills", sa.Column("detail", sa.Text(), nullable=True))
def downgrade() -> None:
if _has_column("skills", "detail"):
op.drop_column("skills", "detail")
@@ -69,6 +69,7 @@ class MemorySkillStore(SkillStore):
"name": name,
"owner_user_id": data.get("owner_user_id"),
"published": bool(data.get("published", False)),
"detail": data.get("detail"),
"created_at": _now(),
"updated_at": _now(),
}
@@ -83,6 +84,7 @@ class MemorySkillStore(SkillStore):
"name": name,
"owner_user_id": data.get("owner_user_id"),
"published": bool(data.get("published", True)),
"detail": data.get("detail"),
"created_at": _now(),
"updated_at": _now(),
}
@@ -98,6 +100,8 @@ class MemorySkillStore(SkillStore):
return None
if "published" in data:
record["published"] = bool(data["published"])
if "detail" in data:
record["detail"] = data["detail"]
record["updated_at"] = _now()
return _with_derived(_copy(record)) # type: ignore[arg-type]
@@ -109,6 +113,8 @@ class MemorySkillStore(SkillStore):
record["published"] = bool(data["published"])
if "owner_user_id" in data:
record["owner_user_id"] = data["owner_user_id"]
if "detail" in data:
record["detail"] = data["detail"]
record["updated_at"] = _now()
return _with_derived(_copy(record)) # type: ignore[arg-type]
@@ -10,7 +10,7 @@ from __future__ import annotations
from datetime import UTC, datetime
from sqlalchemy import Boolean, DateTime, String
from sqlalchemy import Boolean, DateTime, String, Text
from sqlalchemy.orm import Mapped, mapped_column
from deerflow.persistence.base import Base
@@ -24,5 +24,10 @@ class SkillRow(Base):
name: Mapped[str] = mapped_column(String(64), primary_key=True)
owner_user_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
published: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False, index=True)
# Human-authored long-form detail/introduction, editable by the skill owner
# or an admin. Distinct from the skill ``description`` parsed from SKILL.md;
# kept in the DB so admins can annotate built-in skills without rewriting
# the shared on-disk SKILL.md file.
detail: Mapped[str | None] = mapped_column(Text, nullable=True, default=None)
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC))
updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC))
@@ -63,6 +63,7 @@ class SkillRepository(SkillStore):
name=data["name"],
owner_user_id=data.get("owner_user_id"),
published=bool(data.get("published", False)),
detail=data.get("detail"),
created_at=now,
updated_at=now,
)
@@ -81,6 +82,7 @@ class SkillRepository(SkillStore):
name=data["name"],
owner_user_id=data.get("owner_user_id"),
published=bool(data.get("published", True)),
detail=data.get("detail"),
created_at=now,
updated_at=now,
)
@@ -101,6 +103,8 @@ class SkillRepository(SkillStore):
return None
if "published" in data:
row.published = bool(data["published"])
if "detail" in data:
row.detail = data["detail"]
row.updated_at = datetime.now(UTC)
await session.commit()
await session.refresh(row)
@@ -115,6 +119,8 @@ class SkillRepository(SkillStore):
row.published = bool(data["published"])
if "owner_user_id" in data:
row.owner_user_id = data["owner_user_id"]
if "detail" in data:
row.detail = data["detail"]
row.updated_at = datetime.now(UTC)
await session.commit()
await session.refresh(row)
@@ -153,6 +153,43 @@ def _resolve_skills_path(path: str) -> str:
return _join_path_preserving_style(skills_host, relative)
def _custom_skill_name_from_path(path: str) -> str | None:
"""从虚拟技能路径里解析出 custom 技能名,用于"被使用"埋点。
只识别 ``{skills_container}/custom/{name}/...`` 形式 —— public 技能不参与
策展,给它们埋点只会往 ``.usage.json`` 写无用条目。读技能目录下任意文件
(SKILL.md 或 references/templates/scripts 支持文件)都算一次该技能的使用。
解析不出技能名时返回 None。
"""
skills_container = _get_skills_container_path()
if not (path == skills_container or path.startswith(f"{skills_container}/")):
return None
relative = path[len(skills_container) :].lstrip("/")
parts = [segment for segment in relative.split("/") if segment]
if len(parts) >= 2 and parts[0] == "custom":
return parts[1]
return None
def _record_skill_read(virtual_path: str) -> None:
"""技能文件被 ``read_file`` 读取时记一次 use —— 技能"被使用"的真实信号。
技能正文不进 system prompt(prompt 里只有 name/description/location),Agent
按 Progressive Loading 用 ``read_file`` 加载 SKILL.md 才算真正用到该技能。
curator 的年龄流转据此判断闲置,没有这个埋点会把每天都在用的技能误判为陈旧。
best-effort:埋点失败绝不影响 ``read_file`` 本身。
"""
try:
name = _custom_skill_name_from_path(virtual_path)
if name is None:
return
from deerflow.skills.usage import bump_use
bump_use(name)
except Exception:
pass
def _is_acp_workspace_path(path: str) -> bool:
"""Check if a path is under the ACP workspace virtual path."""
return path == _ACP_WORKSPACE_VIRTUAL_PATH or path.startswith(f"{_ACP_WORKSPACE_VIRTUAL_PATH}/")
@@ -1467,6 +1504,9 @@ def read_file_tool(
path = _resolve_and_validate_user_data_path(path, thread_data)
# Custom mount paths are resolved by LocalSandbox._resolve_path()
content = sandbox.read_file(path)
# 读成功即记一次技能使用 —— requested_path 仍是虚拟路径(本地/容器沙箱都一样),
# 非技能路径会被 _record_skill_read 自行忽略。
_record_skill_read(requested_path)
if not content:
return "(empty)"
if start_line is not None and end_line is not None:
@@ -66,6 +66,21 @@ async def _to_thread(func, /, *args, **kwargs):
return await asyncio.to_thread(func, *args, **kwargs)
async def _bump_patch_best_effort(name: str) -> None:
"""记一次技能维护活动(patch / edit)。
刷新 ``.usage.json`` 的 ``patch_count`` 与 ``last_patched_at``,让 curator 的
年龄流转把"Agent 正在主动维护的技能"算作活跃,而不是误判为闲置后归档。
best-effort:埋点失败只记 DEBUG 日志,绝不影响技能写入主流程。
"""
try:
from deerflow.skills.usage import bump_patch
await _to_thread(bump_patch, name)
except Exception:
logger.debug("Failed to bump patch count for %r", name, exc_info=True)
async def _ensure_skill_db_registered(store: SkillStore, name: str, user_id: str) -> None:
"""Idempotently record an agent-created skill's ownership in the DB.
@@ -229,6 +244,7 @@ async def _skill_manage_impl(
name,
_history_record(action="edit", file_path=SKILL_MD_FILE, prev_content=prev_content, new_content=content, thread_id=thread_id, scanner=scan),
)
await _bump_patch_best_effort(name)
await refresh_skills_system_prompt_cache_async()
return f"Updated custom skill '{name}'."
@@ -253,6 +269,7 @@ async def _skill_manage_impl(
name,
_history_record(action="patch", file_path=SKILL_MD_FILE, prev_content=prev_content, new_content=new_content, thread_id=thread_id, scanner=scan),
)
await _bump_patch_best_effort(name)
await refresh_skills_system_prompt_cache_async()
return f"Patched custom skill '{name}' ({replacement_count} replacement(s) applied, {occurrences} match(es) found)."
@@ -0,0 +1,162 @@
"""Tests for the skill ``detail`` field (long-form annotation editable by
the skill owner or an admin).
Covers:
- ``SkillStore`` persists ``detail`` through create / ensure_legacy / update /
update_admin, and owner-only ``update`` still refuses non-owners.
- ``_skill_to_response`` surfaces ``detail`` from the ownership record.
- ``SkillResponse`` / ``SkillDetailRequest`` model shapes.
"""
from __future__ import annotations
from types import SimpleNamespace
import pytest
from app.gateway.routers.skills import (
SkillDetailRequest,
SkillResponse,
_skill_to_response,
)
from deerflow.config import paths as paths_module
from deerflow.persistence.skills import MemorySkillStore
from deerflow.skills.types import SkillCategory
@pytest.fixture
def isolated_paths(tmp_path, monkeypatch):
"""Redirect get_paths() at a fresh temp directory so usage lookups in
``_skill_to_response`` never touch real state."""
monkeypatch.setenv("DEER_FLOW_HOME", str(tmp_path))
monkeypatch.setattr(paths_module, "_paths", None)
yield tmp_path
monkeypatch.setattr(paths_module, "_paths", None)
# ---------------------------------------------------------------------------
# SkillStore: detail persistence
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_skill_store_create_carries_detail() -> None:
store = MemorySkillStore()
created = await store.create(
{"name": "alpha-tool", "owner_user_id": "user-a", "detail": "初始详情"}
)
assert created["detail"] == "初始详情"
fetched = await store.get_any("alpha-tool")
assert fetched is not None and fetched["detail"] == "初始详情"
@pytest.mark.asyncio
async def test_skill_store_create_defaults_detail_to_none() -> None:
store = MemorySkillStore()
created = await store.create({"name": "alpha-tool", "owner_user_id": "user-a"})
assert created["detail"] is None
@pytest.mark.asyncio
async def test_skill_store_owner_can_set_and_clear_detail() -> None:
store = MemorySkillStore()
await store.create({"name": "alpha-tool", "owner_user_id": "user-a"})
updated = await store.update("alpha-tool", "user-a", {"detail": "技能用途说明"})
assert updated is not None and updated["detail"] == "技能用途说明"
# Clearing the annotation persists None.
cleared = await store.update("alpha-tool", "user-a", {"detail": None})
assert cleared is not None and cleared["detail"] is None
@pytest.mark.asyncio
async def test_skill_store_update_detail_rejects_non_owner() -> None:
store = MemorySkillStore()
await store.create({"name": "alpha-tool", "owner_user_id": "user-a"})
# A different user cannot write detail via the owner-scoped update.
assert await store.update("alpha-tool", "user-b", {"detail": "x"}) is None
record = await store.get_any("alpha-tool")
assert record is not None and record["detail"] is None
@pytest.mark.asyncio
async def test_skill_store_admin_can_set_detail_on_any_skill() -> None:
store = MemorySkillStore()
await store.create({"name": "alpha-tool", "owner_user_id": "user-a"})
# Admin override writes detail regardless of ownership.
updated = await store.update_admin("alpha-tool", {"detail": "管理员补充说明"})
assert updated is not None and updated["detail"] == "管理员补充说明"
@pytest.mark.asyncio
async def test_skill_store_partial_update_preserves_detail() -> None:
"""Updating only ``published`` must not wipe an existing ``detail``."""
store = MemorySkillStore()
await store.create({"name": "alpha-tool", "owner_user_id": "user-a"})
await store.update("alpha-tool", "user-a", {"detail": "保留我"})
await store.update("alpha-tool", "user-a", {"published": True})
record = await store.get_any("alpha-tool")
assert record is not None
assert record["detail"] == "保留我"
assert record["published"] is True
@pytest.mark.asyncio
async def test_skill_store_ensure_legacy_carries_detail() -> None:
store = MemorySkillStore()
record = await store.ensure_legacy(
{"name": "builtin-skill", "owner_user_id": None, "published": True, "detail": "内置技能说明"}
)
assert record["detail"] == "内置技能说明"
# ---------------------------------------------------------------------------
# Response mapping
# ---------------------------------------------------------------------------
def test_skill_response_detail_defaults_to_none() -> None:
resp = SkillResponse(name="x", description="d", category=SkillCategory.CUSTOM)
assert resp.detail is None
def test_skill_detail_request_defaults_to_empty_string() -> None:
assert SkillDetailRequest().detail == ""
assert SkillDetailRequest(detail="hello").detail == "hello"
def test_skill_to_response_surfaces_detail_from_ownership(isolated_paths) -> None:
skill = SimpleNamespace(
name="alpha-tool",
description="desc",
license=None,
category=SkillCategory.CUSTOM,
enabled=True,
)
ownership = {
"name": "alpha-tool",
"owner_user_id": "user-a",
"published": False,
"builtin": False,
"detail": "这是技能的详细介绍",
}
resp = _skill_to_response(skill, ownership)
assert resp.detail == "这是技能的详细介绍"
assert resp.owner_user_id == "user-a"
def test_skill_to_response_detail_none_without_ownership(isolated_paths) -> None:
skill = SimpleNamespace(
name="builtin-skill",
description="desc",
license=None,
category=SkillCategory.PUBLIC,
enabled=True,
)
resp = _skill_to_response(skill, None)
assert resp.detail is None
assert resp.builtin is True