refactor(agents): prompt 外置方案A — 21 prompt 散文外迁 .md + SpecResolver
把 21 个内置 agent 的 system_prompt 从 specs.py 的 Python 常量外置为 prompts/<spec.name>.md,import 期由 load_prompt 确定性加载;建立 SPECS 名册 + SCHEMA_CATALOG(Pydantic 类型留 Python)+ 统一只读解析入口 SpecResolver。 纯重构、零功能/schema 变更,缓存断点前块字节级不变(不变量 #9)。 @llm packages/agents(步骤1-3) - spec_model.py:抽出 AgentSpec(frozen,字段不变) - prompt_loader.py:load_prompt = utf-8-sig 去BOM → LF 归一 → NFC → rstrip尾LF, 内存缓存 + fail-fast(PromptNotFoundError),import 期确定性 - schema_catalog.py:SCHEMA_CATALOG[name]→output type 唯一真相源(refiner=None) - prompts/*.md ×21:取常量「运行时值」程序化外迁(反斜杠折行已塌缩, 物理换行≡运行时换行);文件名按 spec.name 连字符(style.md/character-gen.md 等) - specs.py:删 21 常量 + AgentSpec 类;system_prompt=load_prompt(name)、 output_schema=SCHEMA_CATALOG[name];建 SPECS + REVIEW_RESERVED_NAMES; *_spec 兼容期保留且 SPECS[name] is *_spec(同一实例)。804→337 行 - __init__.py:显式 __all__ 重导出(避 F401) @backend packages/skills(步骤4-5) - SpecResolver:内置 SPECS(纯内存、零 DB)+ 用户 SkillRegistry 统一 get; 内置 name 永不触发 DB;output_schema_for 精确匹配 - skill_registry:保留命名空间守卫前移至入库校验,拒同名内置 → VALIDATION - toolbox_registry:GeneratorTool.spec 改走 SPECS[...],删 12 个 *_spec 直接 import @devops repo-root - .gitattributes:prompts/*.md text eol=lf(修正:须用完整嵌套路径才匹配) - packages/agents/pyproject:hatchling artifacts 纳入 prompts/*.md 随 wheel/sdist 分发 - ci.yml:新增 build wheel → 裸装 → import ww_agents.SPECS 冒烟 TDD 全程 mock 网关;门禁绿:ruff/format clean · mypy 209 files · pytest 744 passed (含金标准 sha256 回归 / md↔spec↔catalog 一一对应 / fail-fast / BOM+NFC / 内置守卫 / 同一实例 / 编排器无回归 / apps/api import-smoke / 打包冒烟)
This commit is contained in:
@@ -18,7 +18,7 @@ from typing import Protocol, cast, get_args
|
||||
from pydantic import BaseModel
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from ww_agents import AgentSpec
|
||||
from ww_agents import REVIEW_RESERVED_NAMES, SPECS, AgentSpec
|
||||
from ww_db.models import Skill
|
||||
from ww_llm_gateway.types import Tier
|
||||
from ww_shared import AppError, ErrorCode
|
||||
@@ -27,6 +27,20 @@ from ww_skills.skill_permissions import validate_declaration
|
||||
|
||||
_VALID_TIERS: frozenset[str] = frozenset(get_args(Tier))
|
||||
|
||||
# 内置保留命名空间:四审受信名(REVIEW_RESERVED_NAMES)∪ 全部内置 SPECS name。
|
||||
# 用户 skill 不可冒用这些 name(守卫前移在入库期,呼应不变量 #3:四审 prompt 不被偷换)。
|
||||
_RESERVED_NAMES: frozenset[str] = REVIEW_RESERVED_NAMES | frozenset(SPECS)
|
||||
|
||||
|
||||
def _reject_reserved_name(spec: AgentSpec) -> None:
|
||||
"""用户 skill 冒用内置/保留名 → AppError(VALIDATION)(不可信声明的第一道闸)。"""
|
||||
if spec.name in _RESERVED_NAMES:
|
||||
raise AppError(
|
||||
ErrorCode.VALIDATION,
|
||||
f"Skill「{spec.name}」与内置保留名冲突,不可覆盖",
|
||||
{"skill": spec.name},
|
||||
)
|
||||
|
||||
|
||||
class SkillRecord(BaseModel):
|
||||
"""`skills` 表一行的声明式快照(frozen;snake_case)。
|
||||
@@ -42,8 +56,10 @@ class SkillRecord(BaseModel):
|
||||
scope: str # builtin / custom / community
|
||||
tier: Tier
|
||||
system_prompt: str
|
||||
reads: list[str] = []
|
||||
writes: list[str] = []
|
||||
# 不可变序列:frozen 只防整字段重绑,不防 list 原地变异(record.reads.append 可旁路);
|
||||
# tuple 无 append/clear,对齐 AgentSpec 同字段语义。Pydantic v2 coerce list→tuple。
|
||||
reads: tuple[str, ...] = ()
|
||||
writes: tuple[str, ...] = ()
|
||||
genre: str | None = None
|
||||
|
||||
|
||||
@@ -54,8 +70,8 @@ def _to_spec(record: SkillRecord) -> AgentSpec:
|
||||
system_prompt=record.system_prompt,
|
||||
input_schema=None,
|
||||
output_schema=None,
|
||||
reads=list(record.reads),
|
||||
writes=list(record.writes),
|
||||
reads=record.reads,
|
||||
writes=record.writes,
|
||||
genre=record.genre,
|
||||
scope=record.scope,
|
||||
)
|
||||
@@ -67,6 +83,20 @@ class SkillRepo(Protocol):
|
||||
async def list_all(self) -> list[SkillRecord]: ...
|
||||
|
||||
|
||||
class SkillRegistryLike(Protocol):
|
||||
"""`SpecResolver` 消费的 registry 只读契约(结构子集;测试注 duck-type fake)。
|
||||
|
||||
SpecResolver 只用 `.get` / `.names` / `.list_scope` 三个方法——以 Protocol 精确捕获该
|
||||
契约,避免依赖具体 `SkillRegistry` 类逼测试 fake 加 `# type: ignore`。
|
||||
"""
|
||||
|
||||
def get(self, name: str) -> AgentSpec: ...
|
||||
|
||||
def names(self) -> list[str]: ...
|
||||
|
||||
def list_scope(self, scope: str) -> list[AgentSpec]: ...
|
||||
|
||||
|
||||
class SkillRegistry:
|
||||
"""加载后的只读 skill 注册表(name → AgentSpec)。"""
|
||||
|
||||
@@ -82,6 +112,7 @@ class SkillRegistry:
|
||||
specs: dict[str, AgentSpec] = {}
|
||||
for record in await repo.list_all():
|
||||
spec = _to_spec(record)
|
||||
_reject_reserved_name(spec) # 冒用内置/保留名 → 抛 VALIDATION
|
||||
validate_declaration(spec) # 越权 → 抛 VALIDATION
|
||||
specs[spec.name] = spec
|
||||
return cls(specs)
|
||||
@@ -114,8 +145,8 @@ def _row_to_record(row: Skill) -> SkillRecord:
|
||||
scope=row.scope,
|
||||
tier=cast(Tier, row.tier),
|
||||
system_prompt=row.system_prompt,
|
||||
reads=[str(t) for t in (row.reads or [])],
|
||||
writes=[str(t) for t in (row.writes or [])],
|
||||
reads=tuple(str(t) for t in (row.reads or [])),
|
||||
writes=tuple(str(t) for t in (row.writes or [])),
|
||||
genre=row.genre,
|
||||
)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user