From dca4d45d4e145d9eb36861efef3a713422793426 Mon Sep 17 00:00:00 2001 From: Yaojia Wang Date: Wed, 24 Jun 2026 04:49:44 +0200 Subject: [PATCH] =?UTF-8?q?refactor(agents):=20prompt=20=E5=A4=96=E7=BD=AE?= =?UTF-8?q?=E6=96=B9=E6=A1=88A=20=E2=80=94=2021=20prompt=20=E6=95=A3?= =?UTF-8?q?=E6=96=87=E5=A4=96=E8=BF=81=20.md=20+=20SpecResolver?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 把 21 个内置 agent 的 system_prompt 从 specs.py 的 Python 常量外置为 prompts/.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 / 打包冒烟） --- .gitattributes | 3 + .github/workflows/ci.yml | 26 + apps/api/tests/test_generation.py | 4 +- docs/design/prompt-management.md | 424 ++++++++++ packages/agents/pyproject.toml | 8 + packages/agents/tests/_gen_golden.py | 55 ++ .../agents/tests/fixtures/prompt_hashes.json | 23 + packages/agents/tests/test_brainstorm_spec.py | 4 +- .../agents/tests/test_competitor_specs.py | 4 +- .../agents/tests/test_generation_specs.py | 8 +- packages/agents/tests/test_outliner_spec.py | 6 +- packages/agents/tests/test_prompt_loader.py | 198 +++++ packages/agents/tests/test_review_specs.py | 8 +- packages/agents/tests/test_specs.py | 4 +- packages/agents/tests/test_style_specs.py | 12 +- packages/agents/tests/test_toolbox_specs.py | 4 +- packages/agents/ww_agents/__init__.py | 10 + packages/agents/ww_agents/prompt_loader.py | 48 ++ packages/agents/ww_agents/prompts/blurb.md | 14 + .../agents/ww_agents/prompts/book-title.md | 14 + .../agents/ww_agents/prompts/brainstorm.md | 15 + .../agents/ww_agents/prompts/character-gen.md | 27 + packages/agents/ww_agents/prompts/continue.md | 15 + .../agents/ww_agents/prompts/continuity.md | 26 + packages/agents/ww_agents/prompts/de-ai.md | 19 + packages/agents/ww_agents/prompts/expand.md | 14 + .../agents/ww_agents/prompts/fine-outline.md | 18 + .../agents/ww_agents/prompts/foreshadow.md | 14 + packages/agents/ww_agents/prompts/glossary.md | 17 + .../agents/ww_agents/prompts/golden-finger.md | 17 + packages/agents/ww_agents/prompts/name.md | 17 + packages/agents/ww_agents/prompts/opening.md | 14 + packages/agents/ww_agents/prompts/outliner.md | 16 + packages/agents/ww_agents/prompts/pace.md | 16 + packages/agents/ww_agents/prompts/refiner.md | 15 + packages/agents/ww_agents/prompts/style.md | 17 + .../agents/ww_agents/prompts/style_extract.md | 31 + packages/agents/ww_agents/prompts/teardown.md | 17 + .../agents/ww_agents/prompts/worldbuilder.md | 15 + packages/agents/ww_agents/schema_catalog.py | 67 ++ packages/agents/ww_agents/spec_model.py | 33 + packages/agents/ww_agents/specs.py | 789 ++++-------------- .../skills/tests/test_skill_permissions.py | 4 +- packages/skills/tests/test_skill_registry.py | 63 +- packages/skills/tests/test_spec_resolver.py | 149 ++++ packages/skills/tests/test_toolbox.py | 4 +- .../skills/tests/test_toolbox_registry.py | 13 + packages/skills/ww_skills/__init__.py | 2 + packages/skills/ww_skills/skill_registry.py | 45 +- packages/skills/ww_skills/spec_resolver.py | 66 ++ packages/skills/ww_skills/toolbox_registry.py | 39 +- tests/test_prompt_externalize_regression.py | 117 +++ 52 files changed, 1907 insertions(+), 701 deletions(-) create mode 100644 .gitattributes create mode 100644 docs/design/prompt-management.md create mode 100644 packages/agents/tests/_gen_golden.py create mode 100644 packages/agents/tests/fixtures/prompt_hashes.json create mode 100644 packages/agents/tests/test_prompt_loader.py create mode 100644 packages/agents/ww_agents/prompt_loader.py create mode 100644 packages/agents/ww_agents/prompts/blurb.md create mode 100644 packages/agents/ww_agents/prompts/book-title.md create mode 100644 packages/agents/ww_agents/prompts/brainstorm.md create mode 100644 packages/agents/ww_agents/prompts/character-gen.md create mode 100644 packages/agents/ww_agents/prompts/continue.md create mode 100644 packages/agents/ww_agents/prompts/continuity.md create mode 100644 packages/agents/ww_agents/prompts/de-ai.md create mode 100644 packages/agents/ww_agents/prompts/expand.md create mode 100644 packages/agents/ww_agents/prompts/fine-outline.md create mode 100644 packages/agents/ww_agents/prompts/foreshadow.md create mode 100644 packages/agents/ww_agents/prompts/glossary.md create mode 100644 packages/agents/ww_agents/prompts/golden-finger.md create mode 100644 packages/agents/ww_agents/prompts/name.md create mode 100644 packages/agents/ww_agents/prompts/opening.md create mode 100644 packages/agents/ww_agents/prompts/outliner.md create mode 100644 packages/agents/ww_agents/prompts/pace.md create mode 100644 packages/agents/ww_agents/prompts/refiner.md create mode 100644 packages/agents/ww_agents/prompts/style.md create mode 100644 packages/agents/ww_agents/prompts/style_extract.md create mode 100644 packages/agents/ww_agents/prompts/teardown.md create mode 100644 packages/agents/ww_agents/prompts/worldbuilder.md create mode 100644 packages/agents/ww_agents/schema_catalog.py create mode 100644 packages/agents/ww_agents/spec_model.py create mode 100644 packages/skills/tests/test_spec_resolver.py create mode 100644 packages/skills/ww_skills/spec_resolver.py create mode 100644 tests/test_prompt_externalize_regression.py diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..dd4ca52 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# Prompt 散文外置文件：锁 LF 行尾，防 Windows/CI（core.autocrlf=true）静默引入 CRLF， +# 否则缓存断点字节漂移（不变量 #9）+ 文件层尾换行断言假红（见 docs/design/prompt-management.md §4/§8）。 +packages/agents/ww_agents/prompts/*.md text eol=lf diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4172d5a..77e4423 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,6 +37,32 @@ jobs: - name: pytest run: uv run pytest -q + # 打包冒烟：构建 ww-agents wheel → 装进裸 venv → import ww_agents 并断言 SPECS。 + # 证明 prompts/*.md 随 wheel 分发（源码树 pytest 测不出此漏带——见 + # docs/design/prompt-management.md §4/§6#16）。load_prompt 在 import 期读盘， + # 若 .md 漏带则抛 PromptNotFoundError，本步即红。 + agents-wheel-smoke: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v5 + - name: build ww-agents wheel + run: uv build --wheel packages/agents --out-dir dist + - name: install into bare venv + import SPECS + run: | + uv venv .smoke-venv + # 工作区兄弟包按路径装（解析其第三方依赖）；structlog 是 ww-llm-gateway + # import 期用到但未显式声明的传递依赖，显式补上以保证裸装可 import。 + uv pip install --python .smoke-venv \ + "ww-shared @ ./packages/shared" \ + "ww-config @ ./packages/config" \ + "ww-db @ ./packages/db" \ + "ww-llm-gateway @ ./packages/llm_gateway" \ + structlog + # 被测产物：装 wheel 本身，--no-deps 确保 import 的是它而非源码树。 + uv pip install --python .smoke-venv --no-deps dist/ww_agents-*.whl + .smoke-venv/bin/python -c "import ww_agents; assert ww_agents.SPECS" + frontend: runs-on: ubuntu-latest steps: diff --git a/apps/api/tests/test_generation.py b/apps/api/tests/test_generation.py index 712027a..2fd869c 100644 --- a/apps/api/tests/test_generation.py +++ b/apps/api/tests/test_generation.py @@ -144,8 +144,8 @@ def _skill_registry() -> SkillRegistry: system_prompt="取名", input_schema=None, output_schema=None, - reads=["characters"], - writes=["characters"], + reads=("characters",), + writes=("characters",), scope="custom", ) return SkillRegistry({spec.name: spec}) diff --git a/docs/design/prompt-management.md b/docs/design/prompt-management.md new file mode 100644 index 0000000..e74922f --- /dev/null +++ b/docs/design/prompt-management.md @@ -0,0 +1,424 @@ +# Prompt 管理重构 · 方案A 终版实施方案（v2，已折叠评审） + +> **执行摘要**：把 21 个内置 agent 的 prompt 散文从 `specs.py` 的 Python 三引号常量外置为 `prompts/.md` 文件，用 import 期确定性加载器 `load_prompt` 注入；建立 `SPECS` 名册与 `SCHEMA_CATALOG`（Pydantic 类型永留 Python）；新增 `SpecResolver` 统一内置/用户 skill 的只读解析入口。**核心约束**：缓存断点前块（不变量 #9）字节级不变——金标准 fixture 必须取自 **AST literal_eval 的运行时字符串值**（而非源码文本），因为现有常量大量使用反斜杠折行，物理换行 ≠ 运行时换行。 +> +> **预估工作量**：3–4 人日（@llm 步骤1–3 约 1.5 日 · @backend 步骤4–5 约 1 日 · @qa 集成回归约 0.5 日 · @devops 打包配置 + `.gitattributes` + CI wheel 冒烟约 0.5 日）。纯重构、零功能变更、零 schema 变更（前端无需 `pnpm gen:api`）。 +> +> **风险等级**：**中**。唯一真正的 CRITICAL 是缓存字节稳定性（反斜杠折行 + 尾换行 + BOM + Unicode 归一化四类漂移源），已在本版用「运行时值金标准 + 文件层契约 + CI 防护」三道锁覆盖。其余为可控的协作/打包/接线问题。 + +> 文档类型：架构设计（**只设计、不实现**）· 语言：中文 · 适用包：`packages/agents`（@llm）、`packages/skills`（@backend）、`packages/core/orchestrator`（@llm，本波不改）、repo-root config（@devops）。 +> 上游锚点：`ARCHITECTURE.md §5.1`（AgentSpec）/ `§5.6`（Skill registry）/ `§4.6`（缓存断点）；不变量 #2/#3/#9。 +> 既定方向（不推翻，仅细化）：① prompt 散文外置 `.md`，spec 声明留 Python，`system_prompt = load_prompt(name)`（import 时读盘 + 内存缓存 + 确定性 + fail-fast）；② 集中注册表 `SPECS: dict[name, AgentSpec]`；③ 统一 `SpecResolver.get(name)` 内置与用户 skill 同路径，`output_schema` 这类 Pydantic 类型永远留 Python，按 name 查 `SCHEMA_CATALOG`。 + +--- + +## 0. 现状基线（重构前事实，已逐字复核） + +- `specs.py` 共 804 行 = `AgentSpec` 类（39–53）+ 21 个 `*_SYSTEM_PROMPT` 多行字符串常量 + 21 个 `*_spec` 实例。 +- **CRITICAL 事实（决定整套字节稳定设计）**：21 个 `*_SYSTEM_PROMPT` 常量**大量使用反斜杠行延续**（行尾 `\`）。已逐字核验 `CONTINUITY_SYSTEM_PROMPT`（行56–85）：源码看似多行，但 `\` 在 Python 解析时塌缩为空——**源码里的物理换行 ≠ 运行时字符串里的换行**。所有常量**无 f-string / `.format` / 占位符**（纯静态文本，已核验）。 +- 所有 21 个 spec：`input_schema=None`（入参统一为 assemble 后的序列化文本，无结构化契约）；`scope="builtin"`；`output_schema` 为真 Pydantic 类（20 个有，`refiner` 唯一 `None`）。 +- 易错命名（已核验）：`style_drift_spec`（变量名）的 `name="style"`（行270–271，非 `"style_drift"`）；文件须按 **spec.name** 命名 → `style.md`、`character-gen.md`、`golden-finger.md` 等连字符名。 +- **完整消费方矩阵（6 个直接 import 点，跨 @llm / @backend 两个 owner）** —— 评审 HIGH 修正，原稿遗漏 3 处 apps/api 路由： + + | # | 文件 | import 的 spec | owner | 本波处理 | + |---|---|---|---|---| + | 1 | `packages/core/.../orchestrator/graph.py` `REVIEW_SPECS`（四审硬编码元组） | continuity/foreshadow/style/pace | @llm | **不改**（兼容期复用同一实例） | + | 2 | `packages/core/.../orchestrator/generation_node.py`（§6.5 入库前 continuity 校验） | `continuity_spec` | @llm | **不改** | + | 3 | `packages/core/.../orchestrator/chain/graph.py`（`review_specs` 默认参数 `from ..graph import REVIEW_SPECS`） | 四审 | @llm | **不改** | + | 4 | `packages/skills/.../toolbox_registry.py`（`GeneratorTool.spec`） | 8 个生成器 `*_spec` | @backend | **改**：走 `SPECS[""]` | + | 5 | `apps/api/.../routers/toolbox.py:22` | `continuity_spec`（world-entity 入库 precheck） | @backend | **本波保留 `*_spec`**（兼容期不动），后续波次再切 | + | 6 | `apps/api/.../routers/outline.py:23` + `style.py:25` | `outliner_spec` / `refiner_spec, style_extract_spec` | @backend | **本波保留 `*_spec`**（兼容期不动） | + + > 关键结论修正：因为 #5/#6 是 apps/api（@backend 写）import specs.py（@llm 写）的产物，**「加 agent 要改 4 处」的散落比原稿估计更广**。本波**不强行清空 `*_spec` 导出**；步骤6 的删除前置条件改为「`grep -rn '_spec' apps/api packages` 确认零消费方」（见 §5）。 +- 用户 skill 已有按 name 查表机制：`SkillRegistry.get(name) -> AgentSpec`（`_to_spec` 把 DB 行转 spec，`input_schema`/`output_schema` 强制 `None`），加载时 `validate_declaration` 校验 reads/writes ⊆ `KNOWN_TABLES`。**内置 spec 未走此路径——这是要弥合的缺口。** + +「加一个 agent 要改 4 处」指：①写 prompt 常量 ②写 spec 实例 ③`__init__.py` 导出 ④下游 import 注册。方案A 把 ①→文件、②③→注册表，消除 ①②③ 的散落（④ 的 apps/api 路由因兼容期保留 `*_spec` 而本波不消除，列为后续波次）。 + +--- + +## 1. 设计原则 + +1. **只外置「会变的散文」，不外置「类型」。** prompt 是自然语言、迭代频繁、与代码逻辑正交，外置成 `.md` 让非工程改稿不碰 Python、diff 干净。而 `output_schema`/`input_schema` 是 Pydantic 类型，承载结构化解析与 `isinstance` 校验（`generation_node.py:154`、`outline_node.py:68`、`style_extract_node.py:71`、`review_node.py:122`），**无法从文本推导、无法运行时安全构造**，必须留 Python，由 `SCHEMA_CATALOG` 作 name→type 的**唯一真相源**（见原则6）。 + +2. **一个 name 一个真相。** name 是全局稳定标识（LangGraph 节点 key、`state['reviews']` key、`chapter_reviews` 落库列、日志标签）。重构后 name 仍是唯一主键：`SPECS[name]`、`prompts/.md`、`SCHEMA_CATALOG[name]` 三者由 name 对齐，**任何一方缺失即 fail-fast**。**name 匹配语义锁死为精确字符串相等**——无大小写折叠、无连字符归一、无模糊匹配（评审 MEDIUM）。 + +3. **import 时确定性加载，绝不运行时惊喜。** `load_prompt` 在模块 import 期一次性读盘 + 内存缓存：保证 `spec.system_prompt` 是完整字符串（缓存断点前块 `cache=True` 要求字节稳定，不变量 #9），且单测可复现。文件缺失 = 启动失败（fail-fast），不 fallback、不用占位符。**`load_prompt` 不做任何动态插值（无 `.format`）；任何未来需要运行期占位符的 prompt 不走 `load_prompt`，明确划在本波范围外**（评审 MEDIUM：声明此约束）。 + +4. **内置与用户 skill 同构、同读接口，但权限边界不同。** 二者都产出 `AgentSpec`。`SpecResolver` 提供统一 `.get(name)`：内置走纯内存 `SPECS`（**零 DB 依赖**），用户走 `SkillRegistry`（DB，必过 `validate_declaration`）。统一**读接口**，不统一**信任级别**。**`get(name)` 命中内置 name 时绝不触发任何 DB 调用**（评审 HIGH，§3.5 + §6#7 断言）。 + +5. **不动缓存原理，只换 prompt 来源。** 字节稳定性的责任边界不变：`system_prompt` 仍整块进 `system` 且 `cache=True`，volatile（latest_state/outline）仍在断点后。改的只是「这块文本从常量来」→「从文件来」。 + +6. **缓存字节稳定 = 运行时值金标准 + 文件层契约（CRITICAL，本版新增的核心原则）。** 因为常量含反斜杠折行，**金标准 fixture 必须从 AST `literal_eval` 的运行时字符串值计算 sha256，绝不从源码文本计算**。`prompts/.md` 的**物理换行必须 ≡ 运行时字符串的换行**——即：导出时，凡运行时无换行处，`.md` 里就是同一物理长行（放弃反斜杠折行带来的「源码可读性」，换取「文件即运行时真相」）。这是字节稳定的根。 + +--- + +## 2. 目标目录结构（before / after） + +``` +packages/agents/ww_agents/ + __init__.py # before: 导出 21 个 *_spec + 22 schema 类 + AgentSpec + # after: 导出 AgentSpec(re-export from spec_model) + SPECS + # + load_prompt + SCHEMA_CATALOG + schema 类 + # + 兼容期保留 *_spec（用 __all__/as 显式 re-export 避 F401） + specs.py (804行) # before: AgentSpec 类 + 21 prompt 常量 + 21 spec 实例 +- ───────────────────────────────────────────────────────────────────── + spec_model.py (新, ~30) # after: 仅 AgentSpec 类定义（frozen Pydantic） + prompt_loader.py (新, ~55) # after: load_prompt(name) + PROMPTS_DIR + 缓存 + 规整 + fail-fast + schema_catalog.py (新, ~40) # after: SCHEMA_CATALOG: dict[name, type|None]（唯一真相源） + specs.py (~140) # after: 21 个 spec 声明（system_prompt=load_prompt(name), + # output_schema=SCHEMA_CATALOG[name]）+ SPECS dict + prompts/ # after: 21 个外置散文（文件名 = spec.name） + continuity.md outliner.md foreshadow.md pace.md style_extract.md + style.md # ← spec.name="style"（非 style_drift），易错点，单测覆盖 + refiner.md worldbuilder.md + character-gen.md # ← 连字符 name，非变量名 character_gen_spec + brainstorm.md book-title.md blurb.md name.md golden-finger.md + glossary.md opening.md fine-outline.md continue.md expand.md + de-ai.md teardown.md + +packages/skills/ww_skills/ + skill_registry.py # 改：加载/入库校验期拒绝与内置 name 同名的 skill（保留命名空间前移，见 §3.5） + spec_resolver.py (新, ~60) # after: SpecResolver：合并 SPECS(内置,内存) + SkillRegistry(用户,DB) + toolbox_registry.py # 改：GeneratorTool.spec 改按 SPECS 取，不直接 import *_spec + +# repo-root（@devops owns） + .gitattributes # 新增/改：prompts/*.md text eol=lf（防 CRLF 漂移） + packages/agents/pyproject... # 改：wheel/sdist include prompts/*.md（数据文件随包分发） + .github/workflows/ci.yml # 改：新增「build wheel→裸装→import SPECS」冒烟步骤 +``` + +**文件命名铁律**：`prompts/.md`，name 用 spec 的**连字符 name**，不是 Python 变量名。`style` agent 的 spec.name 是 `"style"` → `style.md`——已知易错点，单测必须覆盖。 + +--- + +## 3. 关键接口签名与归属包 + +### 3.1 `AgentSpec` 模型 — `packages/agents/ww_agents/spec_model.py`（@llm） + +从 `specs.py` 原样抽出，**字段不变**（保持 frozen、`system_prompt: str` 仍是 str，不改 Callable）： + +```python +class AgentSpec(BaseModel): + model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True) + name: str + tier: Tier + system_prompt: str # 仍是 str；值在 import 时由 load_prompt 填入 + input_schema: type[BaseModel] | None = None + output_schema: type[BaseModel] | None = None + reads: list[str] = Field(default_factory=list) + writes: list[str] = Field(default_factory=list) + genre: str | None = None + scope: str = "builtin" +``` + +> 决策：`system_prompt` 保持 `str`（import 时求值），不改 `Callable`——缓存断点前块要确定字符串；改 Callable 会破坏 frozen/序列化，且违背确定性加载。 +> **`__init__.py` re-export 纪律**（评审 MEDIUM）：`AgentSpec` 改从 `spec_model` re-export；现有 `from ww_agents import AgentSpec` 的全部消费方（`skill_registry`/`skill_permissions`/`graph`/`generation_node`/`toolbox` 路由等）**不受影响**（re-export 后 import 路径不变）。`__init__.py` 必须用显式 `__all__` 或 `import ... as ...` 重导出，避免 ruff `F401 unused-import`。§6 增 import-smoke 断言这些路径仍可用。 + +### 3.2 `load_prompt` — `packages/agents/ww_agents/prompt_loader.py`（@llm） + +```python +PROMPTS_DIR: Final = Path(__file__).parent / "prompts" +_CACHE: dict[str, str] = {} + +def load_prompt(name: str) -> str: + """按 spec.name 读 prompts/.md → 规整 → 缓存 → 返回完整 UTF-8 文本。""" +``` + +**规整规则（锁死缓存字节，决策级——已从「建议」升级，评审 HIGH/MEDIUM）**，依次： + +1. **去 BOM**：用 `encoding="utf-8-sig"` 读（或读后剥 ``）——`utf-8` **不会**自动剥 BOM，带 BOM 的 `.md` 会污染字符串首字节破缓存（评审 missingItem）。 +2. **行尾归一**：`.replace("\r\n", "\n").replace("\r", "\n")`（CRLF/CR → LF）。 +3. **Unicode 归一化**：`unicodedata.normalize("NFC", text)`——中文/全角标点存在 NFC/NFD 跨平台归一差异的理论缝隙，显式假定并强制 **NFC**（评审 missingItem）。 +4. **尾换行策略（决策，方案 B 顺生态）**：返回 `text.rstrip("\n")`（吞掉文件尾部所有 LF，**不补回**）。这样 `.md` 文件**允许**带 ≤1 个尾换行（顺 Prettier / editorconfig / `end-of-file-fixer` 默认），而运行时字符串无尾换行（与旧常量逐字等价，旧常量均以「。」结尾、无尾换行）。 + +**字节稳定的双层契约（评审 HIGH：堵住「loader rstrip 吞掉差异后文件与字符串解耦」的静默漂移）**： +- **真相源** = `load_prompt` 规整后的返回值（即 `spec.system_prompt`），由 §6#5 sha256 金标准锁死。 +- **文件层** 额外加一条独立断言：每个 `prompts/*.md` 的磁盘原始字节里，**尾部 LF 数量 ≤ 1**（§6#13）。这样即便有人误补多个尾换行，文件层测试先红，不会被 loader 静默吞掉。 + +**fail-fast**：文件不存在 → `PromptNotFoundError`（import 期崩，不 fallback、不返回 `""`）。 +**`.gitattributes`**（@devops 写）：`prompts/*.md text eol=lf` —— 管行尾风格；尾换行有无由上面文件层断言守。 + +### 3.3 `SCHEMA_CATALOG` — `packages/agents/ww_agents/schema_catalog.py`（@llm） + +**name→output type 的唯一真相源**（评审 LOW：消除 spec 字段与 catalog 双真相）。原稿的 `(input, output)` 元组**收敛为只存 output**（评审 KISS/YAGNI：21 个 input 恒 None、本波不启用，不造尚不存在的结构化入参槽）： + +```python +# name → output_schema（input 全 None，本波不建入参槽——YAGNI） +SCHEMA_CATALOG: Final[dict[str, type[BaseModel] | None]] = { + "continuity": ContinuityReview, + "outliner": OutlineResult, + # ...其余 18 个真类... + "refiner": None, # 唯一纯文本 writer，None 是合法值 +} + +def output_schema_for(name: str) -> type[BaseModel] | None: + return SCHEMA_CATALOG[name] +``` + +> 未来若真出现结构化入参，再新建 `INPUT_SCHEMA_CATALOG` 或回到元组；理由记入 `decisions.md`。 + +### 3.4 `SPECS` 注册表 — `packages/agents/ww_agents/specs.py`（@llm） + +**单向派生**：`system_prompt` 一律来自 `load_prompt(name)`，`output_schema` 一律来自 `SCHEMA_CATALOG[name]`（不再写「或直接 ContinuityReview」的二义来源，评审 LOW）： + +```python +continuity_spec = AgentSpec( + name="continuity", tier="analyst", + system_prompt=load_prompt("continuity"), # ← 唯一来自 loader + output_schema=SCHEMA_CATALOG["continuity"], # ← 唯一来自 catalog + reads=["chapter_digests", "characters", "world_entities"], writes=[], +) +# ...其余 20 个同形... + +SPECS: Final[dict[str, AgentSpec]] = {s.name: s for s in ( + continuity_spec, outliner_spec, foreshadow_spec, pace_spec, style_extract_spec, + style_drift_spec, refiner_spec, worldbuilder_spec, character_gen_spec, + brainstorm_spec, book_title_spec, blurb_spec, name_spec, golden_finger_spec, + glossary_spec, opening_spec, fine_outline_spec, continue_spec, expand_spec, + de_ai_spec, teardown_spec, +)} +assert len(SPECS) == 21, "SPECS name 冲突或缺失" # 唯一性 + 数量自检（import 期） + +# 四审受信保留名 —— 独立显式白名单（评审 MEDIUM），安全边界锚在此，不依附派生集合 +REVIEW_RESERVED_NAMES: Final[frozenset[str]] = frozenset( + {"continuity", "foreshadow", "style", "pace"} +) +``` + +> `*_spec` 模块变量在兼容期保留（toolbox / 节点 / apps/api 路由旧 import 不破）。**`SPECS[name] is *_spec`（同一实例）是不变量**（评审 LOW / missingItem）：兼容期绝不允许 `SPECS["continuity"]` 与 `continuity_spec` 是两个对象——否则缓存断点/日志 name 出现双真相。§6 锁定。 + +### 3.5 `SpecResolver` — `packages/skills/ww_skills/spec_resolver.py`（@backend） + +**依赖方向**：resolver 在 @backend，向上依赖 @llm 的 `SPECS` + 自包 `SkillRegistry`。**不反向**（已核验 `ww_agents` 不依赖任何下游）。 + +```python +class SpecResolver: + """内置(SPECS, 纯内存) + 用户 skill(SkillRegistry, DB) 的统一只读解析入口。""" + def __init__(self, builtin: dict[str, AgentSpec], skills: SkillRegistry) -> None: ... + + @classmethod + def build(cls, skills: SkillRegistry) -> "SpecResolver": + return cls(builtin=dict(SPECS), skills=skills) # 纯合并，不做冲突校验（已前移，见下） + + def get(self, name: str) -> AgentSpec: + """先查内置 SPECS（纯内存、零 DB）；未命中才查 SkillRegistry；都无 → NOT_FOUND。 + 内置 name 永不触发 DB 调用。""" + + def output_schema_for(self, name: str) -> type[BaseModel] | None: + """命中内置 → SCHEMA_CATALOG[name]；纯用户 skill → None（精确 name，无模糊命中）。""" + + def names(self) -> list[str]: ... + def list_scope(self, scope: str) -> list[AgentSpec]: ... +``` + +**override / 优先级裁决 —— 守卫前移（评审 HIGH，核心修正）**： +- 「内置 name 为保留命名空间、用户 skill 不可覆盖」的校验**前移到 SkillRegistry 的 skill 入库/加载校验处**（与 `validate_declaration` 同处），**不放在 `resolver.build` 的读路径**。 +- 理由：放读路径会让一个坏 skill（恰好叫 `continuity`）令**每次** `build` 抛错、把安全校验耦合进写章/审稿热路径、并可能让正常请求 500；而且 `build` 若每请求重建，「拒绝成败取决于请求时 DB 状态」违背原则3 的确定性。 +- 前移后：`get(name)` 对内置永远是**纯内存查表**（零 DB、零运行时分叉、确定性）；坏 skill 在**入库时**即被拒（`AppError(VALIDATION)`，错误归属清晰、早 fail-fast）。 +- 安全断言锚在 **`REVIEW_RESERVED_NAMES` 显式白名单**（§3.4），不依附会随重构漂移的 `set(SPECS)`。 + +> **`output_schema_for`（原 `bind_output_schema`）接线说明（评审 HIGH：原稿是悬空 API）**：当前 8 个工具箱新工具的 `spec` **本就是内置实例**（`output_schema` 非 None），故「内置 name 补绑」这条路径**本波实际无触发场景**。因此：本波**保留 `output_schema_for` 作为 resolver 的只读查询方法**，但**不接线进 `run_generator`、不在 §6 断言其被调用**，明确标注「为后续『用户 skill 复用内置 schema』路径留缝」。纯用户自定义（仅 DB JSON Schema dict，无 Python 类）→ 恒 `None`，运行期 JSON-Schema→Pydantic 动态构造**明确划出本波范围**（不引入不可信类型构造）。 + +**编排器本波不接 resolver**：`graph.py`/`review_node.py`（@llm）当前直接用 `REVIEW_SPECS`（内置元组），本波不强制改它走 resolver——避免本波跨两个 owner 大改。resolver 首个消费方是 @backend 的 `toolbox_registry`（按 name 取 spec）。 + +--- + +## 4. 逐文件改动清单 + +**packages/agents（@llm，sole writer）** +- 新增 `spec_model.py`：抽出 `AgentSpec`（零行为变化）。 +- 新增 `prompt_loader.py`：`PROMPTS_DIR` + `load_prompt` + `_CACHE` + `PromptNotFoundError`（去BOM / LF / NFC / rstrip尾LF / fail-fast）。 +- 新增 `schema_catalog.py`：`SCHEMA_CATALOG: dict[name, type|None]`（21 项，唯一真相源）+ `output_schema_for`。 +- 新增 `prompts/.md` ×21：每个文件 = 对应常量**运行时字符串值**的逐字外迁（程序化导出，物理换行 ≡ 运行时换行）。 +- 修改 `specs.py`：删 21 常量 + `AgentSpec` 类；`system_prompt=load_prompt(name)` + `output_schema=SCHEMA_CATALOG[name]`；建 `SPECS` + assert + `REVIEW_RESERVED_NAMES`；从 `spec_model` 重导出 `AgentSpec`。降至 ~140 行。 +- 修改 `__init__.py`：显式 `__all__` 重导出 `AgentSpec`/`SPECS`/`load_prompt`/`SCHEMA_CATALOG`/schema 类 + 兼容期 `*_spec`（避 F401）。 + +**packages/skills（@backend，sole writer）** +- 新增 `spec_resolver.py`：`SpecResolver`（build/get/output_schema_for/names/list_scope）。 +- 修改 `skill_registry.py`：**入库/加载校验期拒绝与内置 name（含 `REVIEW_RESERVED_NAMES`）同名的 skill**（保留命名空间前移）。`_to_spec` 仍 `output_schema=None` 不变。 +- 修改 `toolbox_registry.py`：`GeneratorTool.spec` 改按 `SPECS[""]` 取，删对 8 个生成器 `*_spec` 的直接 import；legacy `spec=None` 工具不变。 + +**packages/core/orchestrator（@llm）** — 本波**不改**（`REVIEW_SPECS` / 节点 / §6.5 precheck / chain 仍直接用内置 spec 实例，行为不变）。文档标注后续波次可改走 resolver。 + +**apps/api routers（@backend）** — 本波**不改**（`toolbox.py`/`outline.py`/`style.py` 兼容期继续 `from ww_agents import *_spec`；因 `SPECS[name] is *_spec`，拿到的是同一实例）。后续波次再切 `SPECS`。 + +**repo-root config（@devops，跨 owner——需 @backend/@llm 在 PROGRESS 开请求项，不可自行写）** +- 新增 `.gitattributes`：`prompts/*.md text eol=lf`（仓库当前**无** `.gitattributes`，由 @devops 新建）。 +- 修改 `packages/agents` 构建配置：wheel/sdist `force-include`/package-data 显式纳入 `prompts/*.md`。 +- 修改 `.github/workflows/ci.yml`：新增「build wheel → 裸环境安装 → `python -c "import ww_agents; assert ww_agents.SPECS"`」冒烟步骤。 + +**tests（@qa）/ 各 owner 单测** — 见 §6。 + +--- + +## 5. 有序迁移步骤（每步独立过门禁 = ruff + format + **mypy** + pytest，评审 missingItem 补 mypy） + +> 原则：先建能力且与旧常量**并存等价**，验证零字节差后再删常量，最后桥接消费方。 + +**步骤 0 — 运行时值金标准（防漏/防孤儿/防字节漂移的锚，CRITICAL 修正）** +- 一次性脚本/测试：对每个 `*_SYSTEM_PROMPT` 取 **AST `literal_eval` 的运行时字符串值**（**不是源码文本**，因含反斜杠折行），dump `{name: sha256(runtime_value)}` 到 `tests/fixtures/prompt_hashes.json`。这是迁移正确性的唯一金标准。 +- **TDD RED**：此 fixture 测试在 `prompt_loader` 实现前先提交并 RED（`load_prompt` 未实现 → ImportError 红），严格满足 RED→GREEN（评审 LOW）。 + +**步骤 1 — 抽 `AgentSpec` 到 `spec_model.py`** +- 纯搬移 + `specs.py`/`__init__.py` 改 import（含 `__all__` 重导出避 F401）。门禁绿（行为零变化）。 + +**步骤 2 — 落 `prompt_loader.py` + `prompts/*.md`（与常量并存）** +- 用脚本把每个常量的**运行时值**写入 `prompts/.md`（程序化导出，物理换行 ≡ 运行时换行，杜绝手抄漂移）。 +- 加测试 A：`for name: sha256(load_prompt(name)) == fixture[name]`（对齐步骤0 金标准）。 +- **加测试 B（步骤2 当步守卫，评审 MEDIUM）**：`{p.stem for p in PROMPTS_DIR.glob("*.md")} == set(fixture.keys())` —— 用 fixture 的 name 全集当锚，**当步**拦住多写/少写/拼错 `.md`（不等到步骤3 建 SPECS）。 +- 加测试 C（文件层）：每个 `.md` 尾部 LF ≤ 1。此刻 specs.py 仍用常量——**先证 loader≡常量逐字等价**。 + +**步骤 3 — 切 specs.py 到 `load_prompt` + 建 `SPECS` + `SCHEMA_CATALOG` + `REVIEW_RESERVED_NAMES`** +- 删 21 常量；`system_prompt=load_prompt(name)`、`output_schema=SCHEMA_CATALOG[name]`；建 `SPECS` + assert。 +- 回归：`sha256(SPECS[name].system_prompt) == fixture[name]`（证删常量后零字节差）；`SPECS[""] is _spec`（同一实例）；`all(SPECS[n].output_schema is SCHEMA_CATALOG[n])`。门禁绿。 + +**步骤 4 — `SpecResolver` + SkillRegistry 守卫前移（skills 包）** +- 实现 resolver（内置纯内存）+ SkillRegistry 入库期拒绝同名内置。单测：内置/用户对齐、内置 `get` 零 DB、入库同名拒绝。门禁绿。 + +**步骤 5 — 桥接 `toolbox_registry`** +- `GeneratorTool.spec` 改走 `SPECS`；删 8 个生成器 `*_spec` 的直接 import。前端契约不变（GeneratorTool 描述符字段不变），无需 `pnpm gen:api`。门禁绿。 + +**步骤 6 — 清理（前置条件已修正）** +- 前置条件：`grep -rn '_spec' apps/api packages` 确认**无任何消费方**依赖 `*_spec`（含 apps/api 3 路由 + 编排器）。 +- 因 apps/api 路由本波保留 `*_spec`，**本波不删 `*_spec` 导出**——仅更新 `ARCHITECTURE.md §5.1`、`memory/decisions.md`、`PROGRESS.md`，把「apps/api 路由 + 编排器切 resolver」列为后续波次。 + +**防孤儿 / 防漏（贯穿）**：步骤2 测试B（文件集 == fixture name 全集）+ 步骤3 三集合恒等 + 程序化导出（杜绝手抄）+ 运行时值 sha256 金标准（杜绝字节漂移）。 + +--- + +## 6. 测试计划（TDD，全程 mock，不触真 LLM） + +| # | 测试 | 类型 | 断言 | +|---|---|---|---| +| 1 | 注册表唯一性 | unit | `len(SPECS)==21`；无重复 name；import `specs` 不抛 | +| 2 | md ↔ spec ↔ catalog 一一对应 | unit | `set(SPECS) == {p.stem for p in PROMPTS_DIR.glob("*.md")} == set(SCHEMA_CATALOG)`（覆盖 `style.md`/`character-gen.md` 连字符） | +| 3 | `load_prompt` 正常 + 缓存 | unit | 已知 name 返非空 UTF-8；二次调用命中 `_CACHE` | +| 4 | `load_prompt` fail-fast | unit | 未知 name → `PromptNotFoundError`；不 fallback、不返 `""` | +| 5 | **缓存前缀字节回归（核心，CRITICAL）** | unit | `sha256(SPECS[name].system_prompt) == fixture[name]`（全21），**fixture 取自 AST literal_eval 运行时值** | +| 6 | 行尾确定性 | unit | 含 CRLF/CR 的临时 md 经 `load_prompt` 规整为 LF，hash 与 LF 版一致 | +| 6b | **BOM + NFC 规整** | unit | 带 BOM 的 md → 首字节无 ``；NFD 全角标点 md → 与 NFC 版 hash 一致 | +| 7 | resolver 内置/用户对齐 + **零 DB** | unit | `get("continuity")` 命中内置且**注入 fake registry 断言其未被调用**；`get("<用户skill>")` 命中 DB；都无 → `NOT_FOUND` | +| 8 | **内置保留名守卫前移** | unit | SkillRegistry **入库**与 `REVIEW_RESERVED_NAMES`/内置同名 skill → `VALIDATION`；resolver.build **不**因此抛 | +| 9 | `output_schema_for` | unit | 内置 name → `SCHEMA_CATALOG[name]` 真类；`refiner` → `None`；纯用户 skill → `None`；**拼错近似 name（`character_gen`）→ None 不抛、不误命中 `character-gen`** | +| 10 | 边界：refiner 纯文本 | unit | `SPECS["refiner"].output_schema is None`；`SCHEMA_CATALOG["refiner"] is None`；§2 一致性不因 None 误判 | +| 11 | toolbox 绑定 | unit | 每个新工具 `GeneratorTool.spec is SPECS[key]`；legacy 工具 `spec is None` 不变 | +| 12 | 编排器无回归 | integration | review/generation/outline/style_extract 节点用 `SPECS` 内置 spec，mock gateway，system 块文本 == 旧行为 | +| 13 | **文件层尾换行契约** | unit | 每个 `prompts/*.md` 磁盘原始字节尾部 LF ≤ 1 | +| 14 | **同一实例不变量** | unit | `SPECS["continuity"] is continuity_spec`；`REVIEW_RESERVED_NAMES ⊆ set(SPECS)`，且这4个 `scope=="builtin"` 且 `writes==[]` | +| 15 | **import-smoke（apps/api + 编排器）** | integration(@backend/@qa) | `from ww_agents import AgentSpec/outliner_spec/refiner_spec/style_extract_spec/continuity_spec` 不抛，且拿到的对象 `is SPECS[name]` | +| 16 | **打包冒烟** | CI(@devops) | build wheel → 裸装 → `import ww_agents; assert ww_agents.SPECS` 不 `PromptNotFoundError`（防 `.md` 漏带，源码树 pytest 测不出） | + +覆盖率沿用全局 ≥80%。所有 LLM 调用注 fake gateway（CLAUDE.md TDD 纪律）。 + +--- + +## 7. 风险表与缓解 + +| 风险 | 等级 | 说明 | 缓解 | +|---|---|---|---| +| **反斜杠折行 → 运行时换行塌缩 → 金标准取错来源** | CRITICAL | 常量含 `\`，源码物理换行 ≠ 运行时换行；若 fixture 从源码文本算 hash，会「看起来对、字节不对」静默破缓存 | 金标准 fixture 取 **AST `literal_eval` 运行时值**；导出时 `.md` 物理换行 ≡ 运行时换行（§6#5/原则6） | +| 缓存字节漂移（行尾/BOM/NFC/尾换行） | CRITICAL | CRLF/BOM/NFD/尾空行使 `system_prompt` 字节变化 → 缓存失配/语义微变（不变量#9） | `load_prompt` 去BOM(`utf-8-sig`)+LF归一+NFC+rstrip尾LF；§6#5/#6/#6b/#13；`.gitattributes eol=lf`（@devops） | +| 尾换行被编辑器/Prettier/end-of-file-fixer 注入 | HIGH | 工具默认补尾 `\n`，与「字节稳定」对抗 | 决策方案B（顺生态）：md 允许 ≤1 尾换行，loader `rstrip("\n")`；**双层契约**——文件层 §6#13 守「尾LF≤1」、运行时 §6#5 守真相源，二者解耦的静默漂移被堵 | +| SpecResolver 引入运行时不确定性 / 安全校验耦合热路径 | HIGH | build 每请求重建 + 读路径校验同名 → 解析结果依赖 DB 当下、坏 skill 让正常请求 500 | 守卫**前移**到 SkillRegistry 入库校验；`get` 内置纯内存零 DB（§3.5 / §6#7/#8） | +| `output_schema` 误外置 / bind 悬空无接线 | HIGH | 类型无法从文本推导；`output_schema_for` 原稿无消费方 | schema 永留 `SCHEMA_CATALOG`（唯一真相）；`output_schema_for` 本波**不接线、不断言被调用**，明标为后续留缝 | +| 消费方遗漏（apps/api 3 路由 + §6.5 precheck） | HIGH | 原稿漏点 → 步骤6 删 `*_spec` 会破 apps/api import | §0 补全 6 点矩阵；apps/api 本波保留 `*_spec`；步骤6 前置改为全仓 grep；§6#15 import-smoke | +| name 漂移破坏落库映射 / 节点 key | HIGH | 改名或文件名拼错（`style`≠`style_drift`、连字符） | name 冻结 + 精确匹配；§6#2 三集合恒等；程序化导出按 spec.name；`REVIEW_SPECS` 不改序 | +| 用户 skill 覆盖内置 name 偷换四审 prompt | HIGH（安全） | 不可信输入冒用 `continuity` 等 | SkillRegistry 入库期拒同名（锚 `REVIEW_RESERVED_NAMES` 显式白名单，非派生集合）；§6#8/#14 | +| **打包遗漏 `.md`（源码树 pytest 假绿）** | HIGH（升级） | wheel 默认不打非-.py 数据文件；CI 用源码树 pytest 测不出，fail-fast 仅在裸装时触发 | @devops 在构建配置 force-include `prompts/*.md`；CI 加「build wheel→裸装→import」冒烟（§4 / §6#16） | +| 跨 owner 改动（@llm specs ↔ @backend resolver/toolbox ↔ @devops config） | MEDIUM | 依赖方向 + `.gitattributes`/打包/CI 属 @devops | 依赖单向（skills→agents）；`.gitattributes`/pyproject/CI 由 @devops 实施，@llm/@backend 在 PROGRESS 开请求项 | +| 迁移分步中途半成品 | MEDIUM | 步骤2/3 之间 | 步骤2 先证 loader≡常量（运行时值 sha256）+ 目录完整性守卫（测试B），步骤3 才删常量；每步独立过门禁（含 mypy） | +| git 历史追溯 | LOW | 删 prompt 行后 `git log -p specs.py` 追不到旧演进 | 迁移 commit body 注明「prompt 逐字外迁至 prompts/.md，运行时值 sha256 见 fixture」；后续改动落 `prompts/*.md` 更聚焦 | + +--- + +## 8. 协作落点（多 agent 纪律） + +**`memory/contracts.md`**（C6 Agent specification 下登记）： +- `SpecResolver.get(name) -> AgentSpec` **是契约**（@backend 供 resolver + 入库守卫，@llm 供 `SPECS`/`SCHEMA_CATALOG`/`REVIEW_RESERVED_NAMES`/`load_prompt`）。约束：① 内置 name 为保留命名空间、不可被用户 skill 覆盖（守卫在 **SkillRegistry 入库期**）；② `get` 内置纯内存、零 DB；③ `load_prompt` import 期确定性（去BOM/LF/NFC/rstrip尾LF/fail-fast）；④ `SPECS[name] is *_spec` 兼容期同一实例。标 `稳定` 后 toolbox / 后续波次才动。 +- C1（LLM 网关）**不改**（`LlmRequest`/`Block.cache` 不动；`system_prompt` 仍整块 `cache=True`）。 + +**`memory/decisions.md`**（append，一条一事实）： +- 「prompt 外置方案A：散文→`prompts/.md`；`load_prompt` import 期读盘+缓存+去BOM(utf-8-sig)+LF归一+NFC+`rstrip('\n')`+fail-fast；**金标准 fixture 取 AST literal_eval 运行时值**（因常量含反斜杠折行，源码物理换行≠运行时换行）；`.md` 物理换行≡运行时换行；尾换行决策=方案B（md 允许≤1 尾LF，loader rstrip 不补回，文件层断言守 尾LF≤1）。」 +- 「`SCHEMA_CATALOG` 收敛为 `dict[name, type|None]`（去掉恒 None 的 input 槽，YAGNI）；是 name→output 唯一真相源，`SPECS[name].output_schema` 由它派生。」 +- 「内置 name（含 `REVIEW_RESERVED_NAMES`=continuity/foreshadow/style/pace）为保留命名空间，守卫**前移至 SkillRegistry 入库校验**（非 resolver 读路径），用户 skill 同名 → `VALIDATION`（安全边界，呼应不变量#3）。」 +- 「`load_prompt` 不支持运行期占位符/插值；需插值的 prompt 不走此路径，属本波范围外。」 + +**`memory/gotchas.md`**：`prompts/*.md` 文件名按 **spec.name（连字符）**，非 Python 变量名；`style` agent 的 name 是 `"style"` → `style.md`；常量含反斜杠折行——**外迁/比对必须用运行时值**，别用源码文本；`.gitattributes` 锁 `prompts/*.md text eol=lf`；wheel 必须 force-include `prompts/*.md`，否则裸装 import 崩（源码树 pytest 测不出）。 + +**`PROGRESS.md` 任务拆分**（新增一个 wave，每个 `🔵→✅` 独立过门禁，含 mypy）： +1. `@llm` — 步骤 0–3（fixture 取运行时值 / spec_model / loader / prompts / SPECS / SCHEMA_CATALOG / REVIEW_RESERVED_NAMES；删常量；sha256 回归）。 +2. `@backend` — 步骤 4–5（SpecResolver + SkillRegistry 入库守卫前移 + toolbox 桥接）。**依赖** 第1项 `SPECS` 稳定后开工。 +3. `@qa` — §6#12/#15 集成回归（编排器无回归 + apps/api import-smoke）。 +4. `@devops` — `.gitattributes` + wheel package-data + CI wheel 冒烟（§6#16）。**与第1项并行可起，CI 冒烟依赖第1项 prompts 落盘。** +5. `@llm`/`@backend`（**可选后续波**）— apps/api 3 路由 + 编排器节点改走 resolver，然后才删 `*_spec` 导出。 + +**跨所有权请求项（评审 missingItem，原稿漏）**：本方案**需要 @devops 触碰 repo-root config**（`.gitattributes` 新建 + `packages/agents` 打包配置 + CI）——@llm/@backend **不可自行写**这些文件，须在 `PROGRESS.md` 给 @devops 开请求项。@llm 只动 `packages/agents`，@backend 只动 `packages/skills`。对 `packages/shared`/OpenAPI **零触碰**（GeneratorTool 描述符字段不变 → 前端无需 `pnpm gen:api`）。 + +--- + +## 9. 边界情形显式处理 + +1. **`refiner`（无 output_schema 纯文本 writer）**：走 `load_prompt("refiner")` + `SPECS["refiner"]`；`output_schema=None` 合法，`SCHEMA_CATALOG["refiner"]=None`。§6#2 把 key 存在当断言（不断言值非 None）；节点侧 `if expected is not None: isinstance(...)` 逻辑不变。 +2. **input_schema 全 None**：21 个 `input_schema` 恒 None（入参为序列化文本）。`SCHEMA_CATALOG` **本波只存 output**（不造尚不存在的 input 槽，YAGNI）；未来需要时另建 `INPUT_SCHEMA_CATALOG`，理由记 decisions。 +3. **toolbox `GeneratorTool` 绑定**：8 个新工具 `spec` 改指 `SPECS[key]`（同一实例，§6#11）；3 个 legacy `spec=None` 不变。 +4. **用户 skill 与内置 schema 对齐**：用户 skill 经 `SkillRegistry` 出 `output_schema=None`；`output_schema_for(name)` 仅当 name **精确命中**内置 `SCHEMA_CATALOG` 时返真类，否则 None。**name 精确匹配**（无大小写/连字符归一）：拼错的近似 name（如 `character_gen` vs `character-gen`）→ 返 None 不报错，**这是预期行为非 bug**（§6#9）。本波该方法**不接线**，纯自定义 JSON-Schema→Pydantic 动态构造划出本波范围。 +5. **name 比较语义统一**：入库守卫（拒同名）与 `output_schema_for`（补绑）用**同一套精确字符串相等**比较，无二义。 + +--- + +## 10. 评审回应（逐条处理 CRITICAL / HIGH findings） + +裁决：架构不变量+缓存=`changes_requested` · 项目规约=`approve` · 完备性=`changes_requested`。下列意见已全部折叠进 v2。 + +### 视角一：架构不变量 + 缓存前缀字节稳定性 + +**[CRITICAL] 反斜杠行延续 → 运行时换行塌缩，金标准取错来源** —— **采纳（核心修正）**。已核验 `CONTINUITY_SYSTEM_PROMPT` 含 `\`，源码物理换行 ≠ 运行时换行。处理：① 新增**原则6**「运行时值金标准 + 文件层契约」；② 步骤0 fixture 改为取 **AST `literal_eval` 运行时值**算 sha256（§5 步骤0）；③ 锁死「`.md` 物理换行 ≡ 运行时字符串换行」（导出时凡运行时无换行处即同一物理长行，放弃反斜杠折行的源码可读性）；④ §6#5 断言明确「fixture 取自运行时值」；⑤ 风险表升为头号 CRITICAL；⑥ decisions/gotchas 记明。 + +**[HIGH] 尾换行策略与生态工具冲突** —— **采纳（选方案B）**。处理：① §3.2 尾换行从「建议」升级为**决策**——md 允许 ≤1 尾换行、loader `rstrip("\n")` 不补回；② **双层契约**：文件层 §6#13 断言「尾LF≤1」+ 运行时 §6#5 守真相源，堵住「rstrip 吞差异后文件与字符串解耦」的静默漂移；③ 风险表第3行 + decisions 记明。 + +**[HIGH] SpecResolver 引入运行时不确定性 / 安全校验耦合热路径** —— **采纳（守卫前移）**。处理：① §3.5 把「内置保留名守卫」**前移到 SkillRegistry 入库校验**，`resolver.build` 仅纯合并不校验；② `get` 内置纯内存、零 DB；③ §6#7 加「内置 get 注入 fake registry 断言其未被调用」；④ §6#8 断言入库期拒绝、build 不抛；⑤ §4 `skill_registry.py` 列入改动。 + +**[MEDIUM] 四审受信 name 缺独立显式白名单** —— **采纳**。§3.4 新增 `REVIEW_RESERVED_NAMES` 显式常量；安全校验锚此（非 `set(SPECS)`）；§6#14 断言 `⊆ set(SPECS)` 且这4个 `scope=="builtin"`、`writes==[]`。 + +**[MEDIUM] 打包分发风险被低估 / 源码树 pytest 假绿** —— **采纳（升级为 HIGH + 开工前必做）**。风险表升级；§4 列 @devops 在构建配置 force-include `prompts/*.md`；§6#16 加「build wheel→裸装→import」CI 冒烟；§8 列 @devops 请求项。 + +**[LOW] schema_catalog 与 spec 实例双真相** —— **采纳**。§3.3/§3.4 定死单向派生：`SPECS[name].output_schema` 一律来自 `SCHEMA_CATALOG[name]`，catalog 为唯一真相；§6 步骤3 断言 `all(SPECS[n].output_schema is SCHEMA_CATALOG[n])`。 + +**[missingItem] BOM / Unicode NFC 归一化** —— **采纳**。§3.2 规整加 `utf-8-sig` 去BOM + `unicodedata.normalize("NFC")`；§6#6b 断言；decisions 声明假定 NFC。 + +### 视角二：项目规约审查（verdict: approve） + +**[LOW] 全部 6 条（目录所有权/行数/TDD/命名不可变/协作/KISS-YAGNI/fail-fast 时机）** —— 合规，**采纳其改进建议**：① TDD RED——步骤0 fixture 在 loader 前先提交 RED（§5 步骤0）；② SCHEMA_CATALOG 收敛为只存 output dict（去恒 None 的 input 槽，§3.3，YAGNI）；③ 确认 catalog 非第二真相源（§3.3/§3.4 单向派生）；④ fail-fast 时机——守卫前移入库期（§3.5，与视角一 HIGH 同向）。 + +**[missingItem] mypy 未点名** —— **采纳**：§5「每步独立过门禁」明确含 `mypy packages apps`。 +**[missingItem] `__init__.py` re-export 的 F401** —— **采纳**：§3.1 + §4 要求显式 `__all__`/`as` 重导出避 F401。 +**[missingItem] `SPECS[name] is *_spec` 同一实例（覆盖 REVIEW_SPECS）** —— **采纳**：§3.4 列为不变量，§6#14 断言。 +**[missingItem] `.gitattributes` 跨 owner（@devops）** —— **采纳**：§4/§8 明确 `.gitattributes`/打包/CI 归 @devops，@llm/@backend 开 PROGRESS 请求项（仓库当前无 `.gitattributes`，已核验）。 + +### 视角三：完备性批评（漏了什么） + +**[HIGH] 消费方清单漏 3 个 apps/api 路由** —— **采纳**。已核验 `toolbox.py:22`/`outline.py:23`/`style.py:25` import 内置 `*_spec`。处理：① §0 补全 **6 点消费方矩阵**（含 owner + 本波处理）；② 修正「无需跨 owner」——apps/api 路由切换需 @backend 自有目录实施，本波**保留 `*_spec` 不动**；③ 步骤6 删除前置条件改为「全仓 grep（含 apps/api）确认零 `*_spec` import」；④ §6#15 import-smoke。 + +**[HIGH] `bind_output_schema` 悬空 API 无接线** —— **采纳**。处理：① 重命名为 `output_schema_for`（去掉「bind」暗示的写语义）；② §3.5 明确本波**无触发场景**（8 个新工具的 spec 本就是内置实例、output 非 None），故**保留为只读查询但不接线进 `run_generator`、不断言被调用**，标为后续留缝；③ §9.4 同步。 + +**[MEDIUM] name 精确匹配语义 + 拼错近似 name 失败模式** —— **采纳**。原则2 + §9.4/§9.5 声明**精确字符串相等**（无大小写/连字符归一）；§9.4 列「拼错近似 name → 返 None 不报错，是预期行为」；§6#9 加单测（`character_gen` → None，不误命中 `character-gen`）；入库守卫与补绑用同一套比较。 + +**[MEDIUM] 步骤2「独立过门禁」缺 prompts 目录完整性守卫** —— **采纳**。§5 步骤2 加测试B：`{md stem} == set(fixture.keys())`（用 fixture name 全集当锚），**当步**拦多写/少写/拼错 md，不等步骤3。 + +**[MEDIUM] 尾换行策略仍是「建议」+ 未声明无插值假设** —— **采纳**。§3.2 升级为**决策**（方案B，见视角一 HIGH）；原则3 + decisions 声明「`load_prompt` 不支持运行期占位符/插值，需插值的 prompt 属本波外」。 + +**[LOW] 回归未覆盖 apps/api 路由 + §6.5 precheck continuity 复用 + 同一实例断言** —— **采纳**。§6#14（`SPECS["continuity"] is continuity_spec`）+ §6#15（apps/api import-smoke，拿到对象 `is SPECS[name]`）；已核验 `generation_node.py` §6.5 precheck 复用 `continuity_spec`，因同一实例不变量而无回归。 + +**[missingItem] `__all__` 大改破坏面** —— **采纳**：§3.1 说明 `AgentSpec` 改 re-export 后 `from ww_agents import AgentSpec` 的全部现有消费方（skill_registry/skill_permissions/graph/generation_node/toolbox 路由）import 路径不变、不受影响；§6#15 import-smoke 覆盖。 + +--- + +## 附：相关文件路径（绝对） + +- 现状声明：`packages/agents/ww_agents/specs.py`、`.../__init__.py`、`.../schemas.py` +- 用户 skill（resolver 对齐基准 + 守卫前移落点）：`packages/skills/ww_skills/skill_registry.py`、`.../skill_permissions.py`、`.../toolbox.py`、`.../toolbox_registry.py` +- 编排器消费点（本波不改）：`packages/core/ww_core/orchestrator/{graph.py,review_node.py,generation_node.py,outline_node.py,style_extract_node.py,collect.py}`、`.../chain/graph.py` +- apps/api 路由消费点（本波保留 `*_spec`，评审补全）：`apps/api/ww_api/routers/{toolbox.py,outline.py,style.py}` +- 待外置目标目录（新建）：`packages/agents/ww_agents/prompts/` +- @devops 配置落点：`.gitattributes`（新建）、`packages/agents` 打包配置、`.github/workflows/ci.yml` +- 协作回写：`memory/{contracts.md,decisions.md,gotchas.md}`、`PROGRESS.md`、`ARCHITECTURE.md`（§5.1） diff --git a/packages/agents/pyproject.toml b/packages/agents/pyproject.toml index f27e912..809e89d 100644 --- a/packages/agents/pyproject.toml +++ b/packages/agents/pyproject.toml @@ -14,6 +14,14 @@ build-backend = "hatchling.build" [tool.hatch.build.targets.wheel] packages = ["ww_agents"] +# Prompt 散文是包数据：必须随 wheel/sdist 分发，否则裸装 import 时 load_prompt +# 抛 PromptNotFoundError（源码树 pytest 测不出，仅裸装暴露）。`artifacts` 显式声明 +# 这些非 .py 文件为收录目标，确保任何 VCS/.gitignore 规则都不会把它们排除掉 +# （见 docs/design/prompt-management.md §4/§6#16）。 +artifacts = ["ww_agents/prompts/*.md"] + +[tool.hatch.build.targets.sdist] +artifacts = ["ww_agents/prompts/*.md"] [tool.uv.sources] ww-shared = { workspace = true } diff --git a/packages/agents/tests/_gen_golden.py b/packages/agents/tests/_gen_golden.py new file mode 100644 index 0000000..fa243f7 --- /dev/null +++ b/packages/agents/tests/_gen_golden.py @@ -0,0 +1,55 @@ +"""一次性金标准生成器（Prompt 外置方案A · 步0）。 + +取每个内置 AgentSpec 的**运行时** `system_prompt` 值算 sha256，写入 +`fixtures/prompt_hashes.json`。这是 prompt 外置「字节级零变化」的唯一金标准 +（设计 docs/design/prompt-management.md §6 / 原则6）。 + +为何用 import 读 `spec.system_prompt` 而非源码文本：21 个 `*_SYSTEM_PROMPT` +常量大量使用反斜杠行延续（行尾 `\\`），源码物理换行 ≠ 运行时换行。Python 在 +import 时已把 `\\` 求值塌缩——`spec.system_prompt` 即生产实际发送的 +运行时字符串，等价于 AST literal_eval 且更直接。 + +用法（仅在步0 运行一次，之后**不要**再生成，否则会用新值覆盖金标准、掩盖漂移）： + uv run python packages/agents/tests/_gen_golden.py +漂移防护靠 test_prompt_loader.py 比对 load_prompt 输出 vs 本文件产出的 json， +而非重跑本脚本。 +""" + +from __future__ import annotations + +import hashlib +import json +from pathlib import Path + +import ww_agents +from ww_agents.specs import AgentSpec + +FIXTURE = Path(__file__).parent / "fixtures" / "prompt_hashes.json" + + +def _sha256(text: str) -> str: + return hashlib.sha256(text.encode("utf-8")).hexdigest() + + +def collect_builtin_specs() -> dict[str, AgentSpec]: + """ww_agents 命名空间里导出的全部内置 AgentSpec 实例（按 spec.name 去重）。""" + found: dict[str, AgentSpec] = {} + for value in vars(ww_agents).values(): + if isinstance(value, AgentSpec): + found[value.name] = value + return found + + +def main() -> None: + specs = collect_builtin_specs() + golden = {name: _sha256(spec.system_prompt) for name, spec in sorted(specs.items())} + FIXTURE.parent.mkdir(parents=True, exist_ok=True) + FIXTURE.write_text( + json.dumps(golden, ensure_ascii=False, indent=2, sort_keys=True) + "\n", + encoding="utf-8", + ) + print(f"wrote {len(golden)} golden hashes -> {FIXTURE}") + + +if __name__ == "__main__": + main() diff --git a/packages/agents/tests/fixtures/prompt_hashes.json b/packages/agents/tests/fixtures/prompt_hashes.json new file mode 100644 index 0000000..3423e9a --- /dev/null +++ b/packages/agents/tests/fixtures/prompt_hashes.json @@ -0,0 +1,23 @@ +{ + "blurb": "c6f89e3de577775aae1ff747a103876664b3075bdcb2ed118697593891707544", + "book-title": "bb6f0c091fdfb4770c3e398a5f44bc97ec2603a923d4624d784f15916820d305", + "brainstorm": "cbdc8f88a4eed5c1d34db03b522a77cec5fb3c15a474fd191399d05f58f071b5", + "character-gen": "7ef3075c5339174c4a40c92995ec7c71fd058936efbaa468d24c697a7cc9ee0e", + "continue": "d140ed43e508531798e24e708d79171f4f9c7a14d92e6523b217d00985507858", + "continuity": "043a838cf32bfab047d3ea271114733eb3634f091448406259f6464de46f2897", + "de-ai": "c8ef0e34bdd9806786aa0af1ec25b6334f6a31211a51fb025730c66b7a462835", + "expand": "c83fcff4c5820c4d0213e1f63609f19a57959d0a3660df1cbda8f752db4e083a", + "fine-outline": "f2941ce4c1df036fd14e110767c2118c28b6f7ea7fa50e79568313a56dbb6937", + "foreshadow": "df830dd27a51c79789fe4b9f9bc6a6e2228670d198d6b330c7b68063a3817227", + "glossary": "6526746766a67ae7b9bd082856410fc4be04a1efd200254bcd1f855cad69c376", + "golden-finger": "20b5b2c14474ec460e6f89a6e5aa1332fa73e49594fa8e81f7383caded4302f8", + "name": "3e5f631fd518ca77ea9cda7f68afcfcfd9636440dc3633fc496e94d0b40eba05", + "opening": "fa777ab5ffc861a4a0da6ceff629573f7388340173706ebe8452041d16a893b5", + "outliner": "c1ad0527d291a0a3914340086d3429740a3cc6860927485da64cc597b8622549", + "pace": "a4c8011c27904a7e8d1bfa0639e2d5b83f900a14e50ccd0a6f3051ecf6310674", + "refiner": "1a31b355938d95e99a4d17a80b3149c2c42e7dd1d40b9939c64f014d7380bbd2", + "style": "a527a540accb5902b405ac4b0e3421d63a6da792439a1ed429c711b48188d780", + "style_extract": "a8fbfce6f7885a9257e9036aeb2803bb0c623c250a559ab6bb6f1f6407855854", + "teardown": "ddde94186beec6c7f3edcfa060d3471fe86c223d24fd01bf9d37d5c80ab8a9cf", + "worldbuilder": "2fee12f3f001a24c8c8c97bf308436d979993c7a02a519ef511085622747c61d" +} diff --git a/packages/agents/tests/test_brainstorm_spec.py b/packages/agents/tests/test_brainstorm_spec.py index 9e4a18c..8f1040c 100644 --- a/packages/agents/tests/test_brainstorm_spec.py +++ b/packages/agents/tests/test_brainstorm_spec.py @@ -63,8 +63,8 @@ def test_brainstorm_spec_is_light_tier() -> None: def test_brainstorm_spec_reads_projects_writes_nothing() -> None: # 纯预览：读作品设定、不写任何业务表（不变量 #3） - assert brainstorm_spec.reads == ["projects"] - assert brainstorm_spec.writes == [] + assert brainstorm_spec.reads == ("projects",) + assert brainstorm_spec.writes == () def test_brainstorm_spec_output_schema() -> None: diff --git a/packages/agents/tests/test_competitor_specs.py b/packages/agents/tests/test_competitor_specs.py index c0b42ce..ce7c55c 100644 --- a/packages/agents/tests/test_competitor_specs.py +++ b/packages/agents/tests/test_competitor_specs.py @@ -51,8 +51,8 @@ def test_competitor_spec_declares_expected_contract( ) -> None: assert spec.name == name assert spec.tier == tier - assert spec.reads == reads - assert spec.writes == writes # 不变量 #3：续写/扩写/降AI 纯预览；拆书落 rules + assert list(spec.reads) == reads + assert list(spec.writes) == writes # 不变量 #3：续写/扩写/降AI 纯预览；拆书落 rules assert spec.output_schema is output_schema assert spec.scope == "builtin" assert spec.input_schema is None # 注入材料为序列化文本，非结构化入参 diff --git a/packages/agents/tests/test_generation_specs.py b/packages/agents/tests/test_generation_specs.py index fe340fb..1d0b72a 100644 --- a/packages/agents/tests/test_generation_specs.py +++ b/packages/agents/tests/test_generation_specs.py @@ -129,8 +129,8 @@ def test_worldbuilder_spec_is_writer_tier() -> None: def test_worldbuilder_spec_reads_projects_writes_world_entities() -> None: - assert worldbuilder_spec.reads == ["projects"] - assert worldbuilder_spec.writes == ["world_entities"] + assert worldbuilder_spec.reads == ("projects",) + assert worldbuilder_spec.writes == ("world_entities",) def test_worldbuilder_spec_output_schema() -> None: @@ -152,8 +152,8 @@ def test_character_gen_spec_is_writer_tier() -> None: def test_character_gen_spec_reads_world_and_characters() -> None: # reads=world_entities+characters（约束 + 防雷同对照），writes=characters - assert character_gen_spec.reads == ["world_entities", "characters"] - assert character_gen_spec.writes == ["characters"] + assert character_gen_spec.reads == ("world_entities", "characters") + assert character_gen_spec.writes == ("characters",) def test_character_gen_spec_output_schema() -> None: diff --git a/packages/agents/tests/test_outliner_spec.py b/packages/agents/tests/test_outliner_spec.py index 048f9b7..d61f6e3 100644 --- a/packages/agents/tests/test_outliner_spec.py +++ b/packages/agents/tests/test_outliner_spec.py @@ -87,17 +87,17 @@ def test_outliner_spec_is_analyst_tier() -> None: def test_outliner_spec_declares_expected_reads() -> None: - assert outliner_spec.reads == [ + assert outliner_spec.reads == ( "projects", "foreshadow", "characters", "world_entities", - ] + ) def test_outliner_spec_declares_outline_write() -> None: # 声明式 writes（经验收/T3.5 才真写库，不变量 #3） - assert outliner_spec.writes == ["outline"] + assert outliner_spec.writes == ("outline",) def test_outliner_spec_output_schema_is_outline_result() -> None: diff --git a/packages/agents/tests/test_prompt_loader.py b/packages/agents/tests/test_prompt_loader.py new file mode 100644 index 0000000..b3375eb --- /dev/null +++ b/packages/agents/tests/test_prompt_loader.py @@ -0,0 +1,198 @@ +"""prompt_loader 单测（Prompt 外置方案A）。 + +步0 先落「金标准比对」用例（此刻 load_prompt 未实现 → RED）；步2 补齐缓存/ +fail-fast/规整/目录完整性/文件层尾换行等用例。 + +金标准 = packages/agents/tests/fixtures/prompt_hashes.json，取自内置 spec 的 +运行时 system_prompt（见 _gen_golden.py）。比对 load_prompt 输出的 sha256 == 金标准， +即可证明 prompt 外置到 .md 后字节级零变化（不变量 #9 / 设计 §6）。 +""" + +from __future__ import annotations + +import hashlib +import json +from pathlib import Path + +import pytest +from ww_agents import ( + REVIEW_RESERVED_NAMES, + SCHEMA_CATALOG, + SPECS, + continuity_spec, + output_schema_for, +) +from ww_agents.prompt_loader import ( + _CACHE, + PROMPTS_DIR, + PromptNotFoundError, + load_prompt, +) + +FIXTURE = Path(__file__).parent / "fixtures" / "prompt_hashes.json" + + +def _golden() -> dict[str, str]: + data: dict[str, str] = json.loads(FIXTURE.read_text(encoding="utf-8")) + return data + + +def _sha256(text: str) -> str: + return hashlib.sha256(text.encode("utf-8")).hexdigest() + + +@pytest.mark.parametrize("name", sorted(_golden().keys())) +def test_load_prompt_matches_golden(name: str) -> None: + # Arrange + expected = _golden()[name] + # Act + actual = _sha256(load_prompt(name)) + # Assert + assert actual == expected, f"prompt {name!r} 字节漂移：load_prompt 输出与金标准不符" + + +# ---- #1 注册表唯一性 ---- +def test_specs_registry_len_is_21() -> None: + assert len(SPECS) == 21 + # name 即 key，dict 已去重；逐项确认 key == spec.name（无错位） + assert all(key == spec.name for key, spec in SPECS.items()) + + +# ---- #2 md ↔ spec ↔ catalog 一一对应（覆盖 style.md / character-gen.md 连字符）---- +def test_md_spec_catalog_one_to_one() -> None: + md_stems = {p.stem for p in PROMPTS_DIR.glob("*.md")} + assert set(SPECS) == md_stems == set(SCHEMA_CATALOG) + # 易错连字符 / 非变量名命名显式覆盖 + assert "style" in md_stems and "style_drift" not in md_stems + assert "character-gen" in md_stems + assert "golden-finger" in md_stems + assert "book-title" in md_stems + assert "fine-outline" in md_stems + assert "de-ai" in md_stems + + +# ---- #3 load_prompt 正常 + 缓存命中 ---- +def test_load_prompt_returns_text_and_caches() -> None: + # Arrange + _CACHE.pop("continuity", None) + # Act + first = load_prompt("continuity") + assert "continuity" in _CACHE # 首次调用后已缓存 + second = load_prompt("continuity") + # Assert + assert first and isinstance(first, str) + assert first is second # 二次调用命中 _CACHE，返回同一对象 + + +# ---- #4 load_prompt fail-fast ---- +def test_load_prompt_unknown_name_raises() -> None: + with pytest.raises(PromptNotFoundError): + load_prompt("does-not-exist-spec-name") + + +# ---- #6 行尾确定性（CRLF/CR → LF）---- +def test_load_prompt_normalizes_line_endings(tmp_path: Path) -> None: + # Arrange — 同一文本的 LF / CRLF / CR 三版 + body = "第一行\n第二行\n第三行" + (tmp_path / "lf.md").write_text(body + "\n", encoding="utf-8", newline="") + (tmp_path / "crlf.md").write_bytes((body + "\n").replace("\n", "\r\n").encode("utf-8")) + (tmp_path / "cr.md").write_bytes((body + "\n").replace("\n", "\r").encode("utf-8")) + + def _load(stem: str) -> str: + _CACHE.pop(stem, None) + from ww_agents import prompt_loader + + orig = prompt_loader.PROMPTS_DIR + prompt_loader.PROMPTS_DIR = tmp_path # type: ignore[misc] + try: + return prompt_loader.load_prompt(stem) + finally: + prompt_loader.PROMPTS_DIR = orig # type: ignore[misc] + + # Act / Assert — 三版规整后 hash 一致 + lf = _load("lf") + assert _sha256(lf) == _sha256(_load("crlf")) == _sha256(_load("cr")) + + +# ---- #6b BOM + NFC 规整 ---- +def test_load_prompt_strips_bom_and_normalizes_nfc(tmp_path: Path) -> None: + import unicodedata + + # Arrange — 带 BOM 的 NFD 全角文本 vs 干净 NFC + text_nfd = unicodedata.normalize("NFD", "全角：测试。") + (tmp_path / "bom.md").write_bytes("".encode() + (text_nfd + "\n").encode("utf-8")) + (tmp_path / "clean.md").write_text( + unicodedata.normalize("NFC", "全角：测试。") + "\n", encoding="utf-8" + ) + + from ww_agents import prompt_loader + + orig = prompt_loader.PROMPTS_DIR + prompt_loader.PROMPTS_DIR = tmp_path # type: ignore[misc] + try: + _CACHE.pop("bom", None) + _CACHE.pop("clean", None) + bom = prompt_loader.load_prompt("bom") + clean = prompt_loader.load_prompt("clean") + finally: + prompt_loader.PROMPTS_DIR = orig # type: ignore[misc] + + # Assert — 无 BOM 首字节，NFD → NFC 归一后与 clean 一致 + assert not bom.startswith("") + assert _sha256(bom) == _sha256(clean) + + +# ---- #9 / #10 output_schema_for + refiner None ---- +def test_output_schema_for_builtin_and_refiner() -> None: + assert output_schema_for("continuity") is SCHEMA_CATALOG["continuity"] + assert output_schema_for("refiner") is None + assert SCHEMA_CATALOG["refiner"] is None + # 精确匹配：拼错近似 name 不误命中连字符版（KeyError，调用方按需 catch） + with pytest.raises(KeyError): + output_schema_for("character_gen") + + +# ---- #13 文件层尾换行契约：每个 .md 磁盘尾部 LF ≤ 1 ---- +@pytest.mark.parametrize("md", sorted(PROMPTS_DIR.glob("*.md")), ids=lambda p: p.stem) +def test_md_trailing_lf_at_most_one(md: Path) -> None: + raw = md.read_bytes() + trailing = len(raw) - len(raw.rstrip(b"\n")) + assert trailing <= 1, f"{md.name} 尾部 LF={trailing} > 1" + + +# ---- #14 同一实例不变量 + 四审保留名安全边界 ---- +def test_specs_identity_and_review_reserved_names() -> None: + assert SPECS["continuity"] is continuity_spec # 同一实例（兼容期不双真相） + assert REVIEW_RESERVED_NAMES <= set(SPECS) + for name in REVIEW_RESERVED_NAMES: + spec = SPECS[name] + assert spec.scope == "builtin" + assert spec.writes == () + + +# ---- #15 reads/writes 为不可变 tuple：四审 writes 不可被 .append 旁路（不变量 #3）---- +def test_review_specs_writes_immutable_tuple() -> None: + for name in REVIEW_RESERVED_NAMES: + spec = SPECS[name] + assert isinstance(spec.writes, tuple) + assert isinstance(spec.reads, tuple) + # tuple 无 append/clear → 任何旁路 writes 守卫的尝试 fail-fast + with pytest.raises(AttributeError): + spec.writes.append("INJECTED") # type: ignore[attr-defined] + + +# ---- #16 SPECS 注册表运行时只读（MappingProxyType）：单一真相源不可被污染 ---- +def test_specs_registry_is_read_only() -> None: + with pytest.raises(TypeError): + SPECS["injected"] = continuity_spec # type: ignore[index] + with pytest.raises(TypeError): + del SPECS["outliner"] # type: ignore[attr-defined] + + +# ---- #17 .gitattributes 锁 prompts/*.md LF（防 CRLF 漂移，设计 §4/§8）---- +def test_gitattributes_locks_prompts_lf() -> None: + repo_root = Path(__file__).resolve().parents[3] + gitattributes = repo_root / ".gitattributes" + assert gitattributes.is_file(), ".gitattributes 缺失（防 CRLF 漂移守卫）" + content = gitattributes.read_text(encoding="utf-8") + assert "prompts/*.md text eol=lf" in content diff --git a/packages/agents/tests/test_review_specs.py b/packages/agents/tests/test_review_specs.py index 022b8c7..45e6255 100644 --- a/packages/agents/tests/test_review_specs.py +++ b/packages/agents/tests/test_review_specs.py @@ -111,11 +111,11 @@ def test_foreshadow_spec_is_analyst_tier() -> None: def test_foreshadow_spec_is_read_only() -> None: # 不变量 #3：四审只读 - assert foreshadow_spec.writes == [] + assert foreshadow_spec.writes == () def test_foreshadow_spec_reads_foreshadow() -> None: - assert foreshadow_spec.reads == ["foreshadow"] + assert foreshadow_spec.reads == ("foreshadow",) def test_foreshadow_spec_output_schema() -> None: @@ -136,12 +136,12 @@ def test_pace_spec_is_light_tier() -> None: def test_pace_spec_is_read_only() -> None: - assert pace_spec.writes == [] + assert pace_spec.writes == () def test_pace_spec_reads_rules() -> None: # genre 模板 DSL 经 rules（genre 级）注入 - assert pace_spec.reads == ["rules"] + assert pace_spec.reads == ("rules",) def test_pace_spec_output_schema() -> None: diff --git a/packages/agents/tests/test_specs.py b/packages/agents/tests/test_specs.py index 86ce03d..8385597 100644 --- a/packages/agents/tests/test_specs.py +++ b/packages/agents/tests/test_specs.py @@ -93,11 +93,11 @@ def test_continuity_spec_is_analyst_tier() -> None: def test_continuity_spec_is_read_only() -> None: # 不变量 #3：四审只读 - assert continuity_spec.writes == [] + assert continuity_spec.writes == () def test_continuity_spec_declares_expected_reads() -> None: - assert continuity_spec.reads == ["chapter_digests", "characters", "world_entities"] + assert continuity_spec.reads == ("chapter_digests", "characters", "world_entities") def test_continuity_spec_output_schema_is_continuity_review() -> None: diff --git a/packages/agents/tests/test_style_specs.py b/packages/agents/tests/test_style_specs.py index b3e5aa1..f3d3eb8 100644 --- a/packages/agents/tests/test_style_specs.py +++ b/packages/agents/tests/test_style_specs.py @@ -111,8 +111,8 @@ def test_style_extract_spec_is_analyst_tier() -> None: def test_style_extract_spec_reads_and_writes_fingerprint() -> None: - assert style_extract_spec.reads == ["style_fingerprint"] - assert style_extract_spec.writes == ["style_fingerprint"] + assert style_extract_spec.reads == ("style_fingerprint",) + assert style_extract_spec.writes == ("style_fingerprint",) def test_style_extract_spec_output_schema() -> None: @@ -134,11 +134,11 @@ def test_style_drift_spec_is_light_tier_named_style() -> None: def test_style_drift_spec_is_read_only() -> None: # 不变量 #3：四审只读 - assert style_drift_spec.writes == [] + assert style_drift_spec.writes == () def test_style_drift_spec_reads_fingerprint() -> None: - assert style_drift_spec.reads == ["style_fingerprint"] + assert style_drift_spec.reads == ("style_fingerprint",) def test_style_drift_spec_output_schema() -> None: @@ -165,8 +165,8 @@ def test_refiner_spec_output_schema_is_none() -> None: def test_refiner_spec_is_read_only_and_no_writes() -> None: # 回炉非持久（不变量 #3）：不写库，作者采纳经既有 draft 自动保存合入 - assert refiner_spec.reads == [] - assert refiner_spec.writes == [] + assert refiner_spec.reads == () + assert refiner_spec.writes == () def test_refiner_spec_has_nonempty_system_prompt() -> None: diff --git a/packages/agents/tests/test_toolbox_specs.py b/packages/agents/tests/test_toolbox_specs.py index 0c081c6..29c27c6 100644 --- a/packages/agents/tests/test_toolbox_specs.py +++ b/packages/agents/tests/test_toolbox_specs.py @@ -72,8 +72,8 @@ def test_toolbox_spec_declares_expected_contract( ) -> None: assert spec.name == name assert spec.tier == tier - assert spec.reads == reads - assert spec.writes == writes + assert list(spec.reads) == reads + assert list(spec.writes) == writes assert spec.output_schema is output_schema assert spec.scope == "builtin" assert spec.input_schema is None # 注入材料为序列化文本，非结构化入参 diff --git a/packages/agents/ww_agents/__init__.py b/packages/agents/ww_agents/__init__.py index fe18fdc..b877882 100644 --- a/packages/agents/ww_agents/__init__.py +++ b/packages/agents/ww_agents/__init__.py @@ -5,6 +5,8 @@ from __future__ import annotations +from .prompt_loader import PromptNotFoundError, load_prompt +from .schema_catalog import SCHEMA_CATALOG, output_schema_for from .schemas import ( Blurb, BlurbResult, @@ -47,6 +49,8 @@ from .schemas import ( WorldGenResult, ) from .specs import ( + REVIEW_RESERVED_NAMES, + SPECS, AgentSpec, blurb_spec, book_title_spec, @@ -72,6 +76,9 @@ from .specs import ( ) __all__ = [ + "REVIEW_RESERVED_NAMES", + "SCHEMA_CATALOG", + "SPECS", "AgentSpec", "Blurb", "BlurbResult", @@ -99,6 +106,7 @@ __all__ = [ "Opening", "OpeningResult", "OutlineChapter", + "PromptNotFoundError", "OutlineResult", "PaceIssue", "PaceReview", @@ -124,9 +132,11 @@ __all__ = [ "foreshadow_spec", "glossary_spec", "golden_finger_spec", + "load_prompt", "name_spec", "opening_spec", "outliner_spec", + "output_schema_for", "pace_spec", "refiner_spec", "style_drift_spec", diff --git a/packages/agents/ww_agents/prompt_loader.py b/packages/agents/ww_agents/prompt_loader.py new file mode 100644 index 0000000..f1df074 --- /dev/null +++ b/packages/agents/ww_agents/prompt_loader.py @@ -0,0 +1,48 @@ +"""Prompt 加载器（Prompt 外置方案A · 步2）。 + +`load_prompt(name)` 在模块 import 期一次性读盘 `prompts/.md` → 规整 → 内存缓存 +→ 返回完整 UTF-8 文本。保证 `spec.system_prompt` 字节稳定（缓存断点前块，不变量 #9） +且单测可复现。文件缺失 = fail-fast（`PromptNotFoundError`），不 fallback、不返回 ""。 + +规整规则（锁死缓存字节，设计 §3.2），依次： +1. 去 BOM：`encoding="utf-8-sig"` 读（`utf-8` 不自动剥 BOM，带 BOM 会污染首字节破缓存）； +2. 行尾归一：CRLF/CR → LF； +3. Unicode 归一化：`unicodedata.normalize("NFC", text)`（中文/全角标点的跨平台缝隙）； +4. 尾换行策略（方案 B，顺生态）：`text.rstrip("\n")`——吞掉文件尾部所有 LF、不补回。 + `.md` 允许带 ≤1 个尾换行（顺 Prettier / editorconfig），运行时字符串无尾换行 + （与旧常量逐字等价）。 + +`load_prompt` 不做任何动态插值（无 `.format`）；需运行期占位符的 prompt 不走此路径。 +""" + +from __future__ import annotations + +import unicodedata +from pathlib import Path +from typing import Final + +PROMPTS_DIR: Final = Path(__file__).parent / "prompts" +_CACHE: dict[str, str] = {} + + +class PromptNotFoundError(FileNotFoundError): + """按 spec.name 找不到对应 `prompts/.md`（import 期 fail-fast）。""" + + +def load_prompt(name: str) -> str: + """按 spec.name 读 `prompts/.md` → 规整 → 缓存 → 返回完整 UTF-8 文本。""" + cached = _CACHE.get(name) + if cached is not None: + return cached + + path = PROMPTS_DIR / f"{name}.md" + if not path.is_file(): + raise PromptNotFoundError(f"prompt not found for spec name {name!r}: {path}") + + raw = path.read_text(encoding="utf-8-sig") # 去 BOM + normalized = raw.replace("\r\n", "\n").replace("\r", "\n") # 行尾归一 + normalized = unicodedata.normalize("NFC", normalized) # Unicode 归一化 + text = normalized.rstrip("\n") # 尾换行：吞掉、不补回 + + _CACHE[name] = text + return text diff --git a/packages/agents/ww_agents/prompts/blurb.md b/packages/agents/ww_agents/prompts/blurb.md new file mode 100644 index 0000000..5fcfcaa --- /dev/null +++ b/packages/agents/ww_agents/prompts/blurb.md @@ -0,0 +1,14 @@ +你是中文网文的「简介生成器」（blurb，分析档）。职责：依据作品立意/题材与作者一句话需求，产出多版**差异化**的作品简介文案，每版给出简介正文 + 切入角度，供作者择优用于书页/榜单。 + +输入材料： +- 作品设定（projects：题材、立意、主线、卖点）； +- 作者的一句话需求/方向（可空——空则按题材自由发散）。 + +产出（每版一个 variant）： +- text：简介正文（一段抓人文案，立人设/抛钩子/留悬念，控制在书页可读篇幅）； +- angle：切入角度——从哪个卖点/钩子切入（如「金手指反差」「身份悬念」「群像冲突」）。 + +纪律： +- 多版之间**切入角度各异**，便于作者对比择优，避免雷同； +- 贴合作品立意与题材，简介与正文方向一致，不臆造剧情； +- 你只产结构化简介清单，**不改稿、不写库**（纯预览，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/book-title.md b/packages/agents/ww_agents/prompts/book-title.md new file mode 100644 index 0000000..1c40a86 --- /dev/null +++ b/packages/agents/ww_agents/prompts/book-title.md @@ -0,0 +1,14 @@ +你是中文网文的「书名生成器」（book-title，轻量档）。职责：依据作品立意/题材与作者一句话需求，发散产出一组**差异化**的书名候选，每个给出书名 + 取名理由，供作者快速选定。 + +输入材料： +- 作品设定（projects：题材、立意、主线、卖点）； +- 作者的一句话需求/方向（可空——空则按题材自由发散）。 + +产出（每条一个 title）： +- title：书名候选（贴合题材、抓人、朗朗上口）； +- rationale：取名理由——为何抓人/契合题材（爽点/反差/悬念/平台调性）。 + +纪律： +- 一次产出多条时**逐条差异化**——不同风格/切入点，避免一个模子； +- 贴合作品立意与题材；需求为空时按题材发散，不臆造与题材无关的设定； +- 你只产结构化书名清单，**不改稿、不写库**（纯预览，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/brainstorm.md b/packages/agents/ww_agents/prompts/brainstorm.md new file mode 100644 index 0000000..7cd2c9b --- /dev/null +++ b/packages/agents/ww_agents/prompts/brainstorm.md @@ -0,0 +1,15 @@ +你是中文网文的「脑洞生成器」（brainstorm，轻量档）。职责：依据作品立意/题材与作者一句话需求，发散产出一组**差异化**的故事脑洞，每条给出一句话前提 + 抓人钩子 + 适配题材，供作者快速选种立项。 + +输入材料： +- 作品设定（projects：题材、立意、主线、卖点；新立项时可能很少）； +- 作者的一句话需求/方向（可空——空则按题材自由发散）。 + +产出（每条一个 idea）： +- premise：一句话脑洞/设定前提（核心创意，独立成立）； +- hook：抓人钩子——为何让读者想追读（爽点/反差/悬念）； +- genre_fit：适配题材/赛道（若需求/设定已限定则贴合；否则可留空）。 + +纪律： +- 一次产出多条时**逐条差异化**——不同切入角度/赛道/爽点，避免一个模子； +- 贴合作品立意与题材；需求为空时按题材发散，不臆造与题材无关的设定； +- 你只产结构化脑洞清单，**不改稿、不写库**（纯预览，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/character-gen.md b/packages/agents/ww_agents/prompts/character-gen.md new file mode 100644 index 0000000..5884d32 --- /dev/null +++ b/packages/agents/ww_agents/prompts/character-gen.md @@ -0,0 +1,27 @@ +你是长篇连载小说的「角色设计师」（character-gen，写手档）。职责：依据一句话需求 + 世界观约束 + 已有角色，产出一组**完整结构化角色卡**。 + +输入材料： +- 角色需求（一句话，如「亦正亦邪的女二、与主角有宿命纠葛、出身敌对势力」）+ 数量 + 定位； +- 世界观约束（world_entities：力量体系、势力、地理硬规则——取名/能力须契合）； +- **已有角色**（characters：现有角色卡，新角色须与其区分、可与其建关系）； +- **本批已生成卡**（同一次批量里先产出的卡——后续卡须与它们差异化，避免雷同）。 + +产出（每张卡一条 card，字段齐全）： +- name：角色名（取名风格契合世界观）； +- role：角色定位（主角 / CP / 对手 / 导师 / 工具人 等）； +- traits：性格特质（核心-表层-阴影三层 / 核心动机、欲望、恐惧、价值观）； +- backstory：背景故事（出身、关键经历、创伤/转折点）； +- arc：人物弧光（起点 → 转变 → 终点，与剧情挂钩）； +- speech_tics：口癖/语言风格（用词偏好、口头禅，喂给文风一致性让对话有辨识度）； +- tags：人设标签/萌点（网文专属）； +- relations：关系网（与已有/同批角色建边：宿敌/师徒/CP…，给出对象 name + kind）。 + +**群像防雷同（批量，重要）**： +- 一次生成多张卡时，**逐张主动与「已有角色」和「本批已生成卡」对比**——分配差异化的定位、性格底色、动机与口癖，避免「一群人一个模子」； +- 能力/出身须契合世界观硬规则（力量体系不越界、势力/地理自洽）； +- 关系网优先与已有角色建边，让群像有结构而非孤立堆叠。 + +纪律： +- 你只产结构化角色卡，**不改稿、不写库、不直接互调其他 agent**——入库前由编排器追加一道 continuity 校验确认不与世界观/力量体系冲突（§6.5）； +- count 是几就产几张，不多不少；定位若给出则按定位分配； +- 不臆造与需求/世界观无关的设定。 diff --git a/packages/agents/ww_agents/prompts/continue.md b/packages/agents/ww_agents/prompts/continue.md new file mode 100644 index 0000000..6d77240 --- /dev/null +++ b/packages/agents/ww_agents/prompts/continue.md @@ -0,0 +1,15 @@ +你是中文网文的「续写器」（continue，写手档）。职责：依据作品立意/题材、前文正文与（可选的）本章大纲节拍，承接前文续写下文正文，保持人物、世界观、文风与剧情走向的一致，让续写可直接作为下文草稿。 + +输入材料： +- 作品设定（projects：题材、立意、主线、卖点）； +- 前文正文（最新已写正文——续写须无缝承接其情节、语气、人称、文风）； +- 本章大纲节拍（outline：若给出则续写须服务这些节拍，不另起炉灶；可空则按前文自然推进）； +- 作者的一句话需求/方向（可空则按前文与节拍自然续写）。 + +产出： +- text：续写正文（承接前文的成稿文本，信息密度合理、有推进、留钩子）。 + +纪律： +- **无缝承接前文**——人物言行、世界观硬规则、文风（句长/用词/人称）与前文一致，不跑题； +- 若给了大纲节拍则忠实服务节拍，不臆造与设定/前文冲突的剧情； +- 你只产结构化续写文本，**不改稿、不写库**（纯预览，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/continuity.md b/packages/agents/ww_agents/prompts/continuity.md new file mode 100644 index 0000000..38a71dc --- /dev/null +++ b/packages/agents/ww_agents/prompts/continuity.md @@ -0,0 +1,26 @@ +你是长篇连载小说的「一致性续审」。你的唯一职责：把本章草稿与作品的既有真相源逐项比对，找出一致性冲突，产出结构化冲突清单。 + +比对依据（注入材料）： +- 近况摘要（最近若干章的 chapter_digests）； +- 相关人物卡（性格、能力、关系、最新状态 latest_state）； +- 世界观硬规则（world_entities 的不可违背设定）。 + +按以下五类判定冲突，每条给出本章定位、来源引用与改法建议： +- 性格漂移：人物言行与其设定/既往表现不符； +- 能力不符：超出或低于已建立的能力/力量体系边界； +- 设定违例：违反世界观硬规则； +- 地理矛盾：地点/距离/空间关系与既有设定冲突； +- 时间线倒错：事件先后、时序与既有章节矛盾。 + +一键采纳补丁（original/replacement，可选但尽量给）： +- 若该冲突可由**一处局部改写**修复，额外给出 original 与 replacement，供作者「采纳改法」一键改入终稿： + - original：从本章草稿里**逐字摘录**的精确原文片段（含标点，**最小**到能定位的句/短语；不得改写、省略或加省略号）； + - replacement：把 original 改正后的文本（同等粒度，仅改必要处）。 +- 无法定位到单一连续片段（如跨多段、需补全新设定、整体视角问题）则 original/replacement 都留空，仅给 suggestion 让作者手改。 + +纪律： +- 你**只读、只报冲突**，不改稿、不写库、不产章节摘要（摘要在验收时从终稿另提）； + original/replacement 只是**提议**的补丁，是否改入终稿由作者裁决，你不直接改稿。 +- 只报有据可依的真冲突；无冲突则返回空列表，不要臆造。 +- 引用要具体（章节号、设定项、人物卡条目），便于作者就地裁决。 +- original 必须是草稿里真实存在的原文（逐字一致），否则前端无法定位——拿不准就留空。 diff --git a/packages/agents/ww_agents/prompts/de-ai.md b/packages/agents/ww_agents/prompts/de-ai.md new file mode 100644 index 0000000..691edd2 --- /dev/null +++ b/packages/agents/ww_agents/prompts/de-ai.md @@ -0,0 +1,19 @@ +你是中文网文的「降 AI 率改写器」（de-ai，分析档）。职责：把作者提供的原文改写得更像「人写的」——去除 AI 腔/机翻腔、模板化句式、空泛排比与过度对仗，让行文更自然、有个人质感，但**保留原文的情节信息与事实**。 + +输入材料： +- 作品设定（projects：题材、立意）； +- 待改写的原文片段； +- 作者的一句话需求/方向（如「更口语」「去掉排比腔」；可空则按通用「去 AI 味」目标）。 + +产出： +- text：降 AI 率改写后的正文（去机翻腔/模板感，更自然的人写质感，保留原情节与事实）。 + +典型 AI 腔特征（重点消除）： +- 空泛排比与过度对仗、千篇一律的「不是……而是……」句式； +- 形容词堆砌、抽象大词（如「彰显」「诠释」）滥用、缺乏具体感官细节； +- 段落起承转合过于工整、缺少口语停顿与个人语气。 + +纪律： +- **保留原文情节与关键事实**，不增删主线、不改人物言行； +- 贴合作品文风与原文语气，改写后更自然但不失原意； +- 你只产结构化改写文本，**不改稿、不写库**（纯预览，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/expand.md b/packages/agents/ww_agents/prompts/expand.md new file mode 100644 index 0000000..71f85aa --- /dev/null +++ b/packages/agents/ww_agents/prompts/expand.md @@ -0,0 +1,14 @@ +你是中文网文的「扩写器」（expand，写手档）。职责：在作者提供的原文基础上扩写、丰富——补足细节、铺陈描写、强化张力，但**不改变原文的情节走向与关键事实**，让扩写后的正文更饱满可读。 + +输入材料： +- 作品设定（projects：题材、立意、主线、卖点）； +- 待扩写的原文片段； +- 作者的一句话需求/方向（如「加强环境描写」「放慢节奏铺情绪」；可空则均衡扩写）。 + +产出： +- text：扩写后的正文（在原文基础上丰富细节/描写/铺陈，保留原情节与事实）。 + +纪律： +- **保留原文情节与关键事实**，不增删主线、不改人物言行的核心； +- 贴合作品文风与原文语气（句长、用词、人称一致），扩写自然不注水； +- 若给了需求则优先满足；你只产结构化扩写文本，**不改稿、不写库**（纯预览，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/fine-outline.md b/packages/agents/ww_agents/prompts/fine-outline.md new file mode 100644 index 0000000..16c4f28 --- /dev/null +++ b/packages/agents/ww_agents/prompts/fine-outline.md @@ -0,0 +1,18 @@ +你是中文网文的「细纲生成器」（fine-outline，分析档）。职责：把某一章的粗大纲节拍**展开为细粒度场景序列**，每个场景给出节拍、叙事目的、冲突与钩子，让作者据细纲直接落笔成章。 + +输入材料： +- 作品设定（projects：题材、立意、主线）； +- 大纲（outline：本章的章号与粗节拍要点——细纲须忠实展开这些节拍，不另起炉灶）； +- 作者的一句话需求/方向（可空则按章节拍自由展开）。 + +产出（每个场景一条 scene）： +- idx：场景序号（章内有序）； +- beat：场景节拍——本场具体发生什么； +- purpose：叙事目的——推动主线 / 塑造人物 / 铺垫或推进伏笔； +- conflict：本场冲突/张力来源； +- hook：场景钩子——驱动读者读下一场的悬念。 + +纪律： +- 场景须**忠实展开本章粗节拍**，顺序合理、推进主线，不跑题、不与大纲冲突； +- 每场都要有目的与张力，避免注水过场； +- 你只产结构化场景清单（idx/beat/purpose/conflict/hook），**不改稿、不写库**（落 outline 表经入库端点，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/foreshadow.md b/packages/agents/ww_agents/prompts/foreshadow.md new file mode 100644 index 0000000..0d64d3c --- /dev/null +++ b/packages/agents/ww_agents/prompts/foreshadow.md @@ -0,0 +1,14 @@ +你是长篇连载小说的「伏笔续审」（foreshadow-analyst）。职责：把本章草稿与作品已登记伏笔逐项比对，找出本章**新埋的伏笔**与**疑似回收/收束**的伏笔，产出结构化建议清单。 + +比对依据（注入材料）： +- 已登记伏笔（foreshadow：编码、标题、状态、期望回收窗口）； +- 本章草稿正文。 + +产出两组建议： +- planted（新埋）：本章疑似首次埋下的伏笔——给出标题、本章定位、要点说明；若与某已登记编码相关则填 code，否则留空由作者命名。 +- resolved（回收）：本章疑似回收/收束已登记伏笔——给出对应 code、本章定位、回收理由。 + +纪律： +- 你**只读、只产建议**，不改稿、不写库、不直接登记或改伏笔状态——登记/状态变更经作者在验收时裁决确认（不变量 #3 / #4）。 +- 只报有据可依的；无则两组都返回空列表，不要臆造。 +- 引用具体（伏笔编码、本章段落定位），便于作者就地确认。 diff --git a/packages/agents/ww_agents/prompts/glossary.md b/packages/agents/ww_agents/prompts/glossary.md new file mode 100644 index 0000000..c2adf42 --- /dev/null +++ b/packages/agents/ww_agents/prompts/glossary.md @@ -0,0 +1,17 @@ +你是中文网文的「术语表生成器」（glossary，分析档）。职责：依据作品世界观，整理一组关键术语（境界/功法/货币/度量/称谓/概念等），每条给出定义与**硬规则**，对齐世界观设定，供后续一致性校验引用比对。 + +输入材料： +- 作品设定（projects：题材、立意）； +- 世界观实体（world_entities：力量体系/势力/地理——术语须与之自洽）； +- 作者的术语需求（一句话或要点；可空则按世界观梳理核心术语）。 + +产出（每条一个 term）： +- name：术语名； +- type：术语类型（境界 / 功法 / 货币 / 度量 / 称谓 / 概念 等）； +- definition：术语定义（一句话释义，清晰无歧义）； +- rules：该术语的**硬规则清单**——不可违背的设定边界（如「金币 100 兑 1 银币」「炼气期不可飞行」），每条一句，可被 continuity 续审逐条引用比对。 + +纪律： +- 术语须与既有世界观自洽，不自相矛盾； +- **rules 要显式、可校验**——别把约束藏在 definition 里； +- 你只产结构化术语清单（name/type/definition/rules），**不改稿、不写库**（落 world_entities 表经入库端点，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/golden-finger.md b/packages/agents/ww_agents/prompts/golden-finger.md new file mode 100644 index 0000000..5adf178 --- /dev/null +++ b/packages/agents/ww_agents/prompts/golden-finger.md @@ -0,0 +1,17 @@ +你是中文网文的「金手指设计师」（golden-finger，写手档）。职责：依据作品立意/题材与作者需求，设计一组内部自洽的金手指（力量体系/系统/特殊能力），每个显式标注机制、成长路径与**限制代价**，供后续一致性校验引用。 + +输入材料： +- 作品设定（projects：题材、立意、主线、卖点）； +- 世界观实体（world_entities：已有力量体系/势力/地理——金手指须与之自洽不冲突）； +- 作者的金手指需求（一句话或要点）。 + +产出（每个一条 system）： +- name：金手指名称； +- mechanism：核心机制——如何运作、触发条件、与世界观力量体系的衔接； +- growth：成长路径——随剧情如何升级/进阶，给读者持续爽点反馈； +- limits：**限制与代价**——能力边界、副作用、冷却/门槛（防越级无敌，供 continuity 续审逐条引用比对，防「能力不符」）。 + +纪律： +- 金手指须内部自洽、与既有世界观力量体系不冲突； +- **limits 要显式、可校验**——别把约束藏在描述里；这是后续防能力越界的依据； +- 你只产结构化金手指（name/mechanism/growth/limits），**不改稿、不写库**（落 world_entities 表经入库端点，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/name.md b/packages/agents/ww_agents/prompts/name.md new file mode 100644 index 0000000..2c9b3fa --- /dev/null +++ b/packages/agents/ww_agents/prompts/name.md @@ -0,0 +1,17 @@ +你是中文网文的「取名生成器」（name，轻量档）。职责：依据作品世界观与作者需求，为人物/势力/地点/功法/物品等取一组**差异化**的名字，每个给出名字 + 类别 + 取意说明，须契合世界观术语与命名风格。 + +输入材料： +- 作品设定（projects：题材、立意）； +- 世界观实体（world_entities：力量体系、势力、地理——命名须契合其术语/风格）； +- 已有角色（characters：避免与既有名字撞名/混淆）； +- 作者的一句话需求（命名对象、数量、风格倾向；可空则按世界观自由发散）。 + +产出（每条一个 name）： +- name：建议的名字（契合世界观命名风格，朗朗上口、有辨识度）； +- kind：命名对象类别（人物 / 势力 / 地点 / 功法 / 物品 等）； +- note：取意说明（取自何意/出处，可缺）。 + +纪律： +- 名字须**契合世界观术语与命名风格**，不与已有角色撞名/易混； +- 一次产出多条时**逐条差异化**，避免一个模子； +- 你只产结构化命名清单，**不改稿、不写库**（纯预览，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/opening.md b/packages/agents/ww_agents/prompts/opening.md new file mode 100644 index 0000000..b2a65a4 --- /dev/null +++ b/packages/agents/ww_agents/prompts/opening.md @@ -0,0 +1,14 @@ +你是中文网文的「开篇生成器」（opening，写手档）。职责：依据作品立意/题材与首章大纲，产出多版**差异化**的开篇正文，每版都要在前几段立爽点/钩子/代入感（黄金三章），供作者择优作为正文起手。 + +输入材料： +- 作品设定（projects：题材、立意、主线、卖点）； +- 大纲（outline：首章/开篇章的节拍要点——开篇须服务这些节拍）； +- 作者的一句话需求/方向（可空则按题材与大纲自由发挥）。 + +产出（每版一个 variant）： +- text：开篇正文（一段成稿文本，开门见山立钩子、信息密度高、少铺垫慢热）。 + +纪律： +- 多版之间**切入方式各异**（如「冲突开场」「悬念开场」「金手指开场」），便于作者对比； +- 贴合作品立意、题材与首章大纲节拍，不跑题、不臆造与大纲冲突的剧情； +- 你只产结构化开篇文本清单，**不改稿、不写库**（纯预览，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/outliner.md b/packages/agents/ww_agents/prompts/outliner.md new file mode 100644 index 0000000..dfe0931 --- /dev/null +++ b/packages/agents/ww_agents/prompts/outliner.md @@ -0,0 +1,16 @@ +你是长篇连载小说的「大纲架构师」。职责：依据作品立意、人物与世界观，排出分卷分章的章节大纲，并为每条伏笔标注回收窗口。 + +输入材料： +- 作品设定（projects：题材、立意、主线、卖点）； +- 已登记伏笔（foreshadow：编码、标题、埋设/期望回收线索）； +- 主要人物（characters）与世界观实体（world_entities）。 + +产出要求（每章）： +- 章号有序、按卷推进； +- beats：本章核心节拍/情节要点，推动主线、服务人物弧光； +- foreshadow_windows：本章关联的伏笔回收窗口——给出伏笔编码、埋设章号、期望回收区间（下界/上界章号）。把每条伏笔的「埋设 → 回收」绑到具体章节。 + +纪律： +- 接近某伏笔的回收窗口时，在对应章 beats 里安排推进/收束该伏笔的情节，避免伏笔悬置过久； +- 你只产结构化大纲（章节 + 节拍 + 伏笔窗口），**不改稿、不写库**（落 outline 表经验收/端点）； +- 伏笔编码须与已登记 foreshadow.code 对应，便于后续按窗口提示与校验。 diff --git a/packages/agents/ww_agents/prompts/pace.md b/packages/agents/ww_agents/prompts/pace.md new file mode 100644 index 0000000..a169643 --- /dev/null +++ b/packages/agents/ww_agents/prompts/pace.md @@ -0,0 +1,16 @@ +你是长篇连载小说的「节奏续审」（pace-checker）。职责：按题材的节奏模板审本章草稿，找出注水段、判定章末钩子有无、给出爽点节拍图。 + +题材节奏模板（genre 级规则，注入材料里带本作题材的具体模板；无则用网文通用基线）： +- 黄金三章：开篇前三章须快速立爽点/钩子/代入感，信息密度高、少铺垫慢热； +- 章末钩子：每章结尾应留悬念/反转/期待，驱动追更； +- 爽点密度：按题材基线维持爽点节拍，避免长段平淡注水。 + +产出： +- water（注水段）：逐段审，标出信息密度低/重复/偏题/拖沓的段落，给本章定位与原因； +- hook（章末钩子）：本章结尾是否存在有效钩子（true/false）； +- beat_map（节拍图）：把本章按段切分，给每段一个爽点强度整数（如 0–5），形成逐段强度序列，供前端 ▁▃▅ 可视化节奏起伏。 + +纪律： +- 你**只读、只报节奏诊断**，不改稿、不写库（不变量 #3）。 +- 依据题材模板判定，不臆造；无注水段则 water 为空列表。 +- beat_map 长度应与切分段数一致、顺序即正文顺序，便于前端对齐渲染。 diff --git a/packages/agents/ww_agents/prompts/refiner.md b/packages/agents/ww_agents/prompts/refiner.md new file mode 100644 index 0000000..910233c --- /dev/null +++ b/packages/agents/ww_agents/prompts/refiner.md @@ -0,0 +1,15 @@ +你是长篇连载小说的「回炉改写器」（refiner）。职责：仅重写作者选中的**一个**段落，使其贴合作品既有文风与上下文语气，同时保留该段的情节信息与叙事推进。 + +输入： +- 待重写的段落正文； +- 可选的改写指令（作者的具体要求，如「去掉机翻腔」「加快节奏」「改成第三人称」）； +- 周边上下文/文风线索（若提供）。 + +产出： +- **只输出重写后的该段正文纯文本**，不要加任何前后缀、解释、标题或 markdown 包裹。 + +纪律： +- 保留原段的关键情节信息与人物言行，不增删主线事实； +- 贴合周边上下文与作品文风（语气、句长、用词、人称一致）； +- 若给了改写指令，优先满足指令；无指令则以「贴合文风、去除生硬/出戏表达」为默认目标； +- 只重写选中段，**不扩写到其他段落**，不改稿入库（作者采纳后经既有自动保存合入）。 diff --git a/packages/agents/ww_agents/prompts/style.md b/packages/agents/ww_agents/prompts/style.md new file mode 100644 index 0000000..6fba4ca --- /dev/null +++ b/packages/agents/ww_agents/prompts/style.md @@ -0,0 +1,17 @@ +你是长篇连载小说的「文风漂移续审」（style-auditor 打分轨，第四审）。职责：对照注入材料里的**文风指纹**，逐段为本章草稿打文风相似度分，标出明显偏离指纹的段落。 + +比对依据（注入材料）： +- 文风指纹（每维带取值与原文证据，来自作者样本提取）； +- 本章草稿正文（按段切分）。 + +产出： +- score：整章相对文风指纹的整体相似度（0–100，越高越贴合作者既有文风）； +- segments：逐段审，标出相似度明显偏低（疑似漂移）的段落——给出段索引 idx（0 起）、该段相似度 score（0–100）、可选 label 说明漂移类型（如「机翻腔」「叙述拖沓」「人称跳脱」「用词出戏」等）。相似度正常的段落不必列出。 + +**无指纹优雅降级（重要）**： +- 若注入材料中**没有文风指纹**（作者尚未学文风），你**无从对照**——此时直接返回 `score=100, segments=[]`（视为「无偏离」），不报错、不臆造漂移段。 + +纪律： +- 你**只读、只报漂移诊断**，不改稿、不写库（不变量 #3）。 +- 依据指纹判定，不臆造；无明显漂移段则 segments 为空列表。 +- idx 必须与正文段切分顺序一致，便于前端朱砂标注与一键回炉对齐。 diff --git a/packages/agents/ww_agents/prompts/style_extract.md b/packages/agents/ww_agents/prompts/style_extract.md new file mode 100644 index 0000000..6b11df1 --- /dev/null +++ b/packages/agents/ww_agents/prompts/style_extract.md @@ -0,0 +1,31 @@ +你是长篇连载小说的「文风指纹提取器」（style-auditor 提取轨）。职责：从作者提供的样本正文中，提取一份 **16 维**中文网文文风指纹，每一维都必须给出支撑判定的**原文证据**（样本原句摘录）。 + +16 维 = 9 通用维 + 7 中文网文专有维： +通用 9 维： +1. 句长节奏（长短句配比、断句习惯）； +2. 段落密度（段落长短、对话/叙述配比）； +3. 叙事人称与视角（第几人称、限知/全知、视角切换频率）； +4. 时态与语气（陈述/疑问/感叹密度、临场感）； +5. 用词风格（古雅/口语/书面、生僻字偏好）； +6. 修辞偏好（比喻/排比/夸张等惯用手法）； +7. 描写与白描配比（环境/心理/动作描写的取舍）； +8. 情绪基调（冷峻/热血/诙谐/悲怆）； +9. 标点习惯（破折号/省略号/感叹号的使用密度）。 +中文网文专有 7 维： +10. 爽感节拍（打脸/扮猪吃虎/升级反馈的节奏）； +11. 金手指呈现方式（系统流/面板/旁白提示风格）； +12. 章末钩子手法（悬念/反转/期待的固定套路）； +13. 对话腔调（角色台词的口癖、网感梗、语气词）； +14. 战斗/冲突描写密度与招式命名风格； +15. 称谓与世界观术语的使用习惯（道号/境界/势力称呼）； +16. 注水与信息密度倾向（铺垫慢热 vs 高密快节奏）。 + +产出要求（每维一条 dimension）： +- name：维度名（用上面 16 维的名目或等义表述）； +- value：该维在样本里的取值/概括（一句话刻画其风格特征）； +- evidence：从样本里摘 1–3 句**原文**作为证据，便于作者核验该结论的出处。 + +纪律： +- 只从给定样本提取，**不臆造**；样本未体现的维度，value 给「样本不足以判定」并留空 evidence。 +- 你只产结构化指纹，**不改稿、不写库**（落 style_fingerprint 表经端点）。 +- evidence 必须是样本原句的真实摘录，不得改写或编造。 diff --git a/packages/agents/ww_agents/prompts/teardown.md b/packages/agents/ww_agents/prompts/teardown.md new file mode 100644 index 0000000..f1af04c --- /dev/null +++ b/packages/agents/ww_agents/prompts/teardown.md @@ -0,0 +1,17 @@ +你是中文网文的「拆书师」（teardown，分析档）。职责：依据作者提供的样本作品（书名 + 章节/简介样本），把它拆解为可学习的结构化要素——核心主题、人物原型、叙事结构、抓人钩子，供作者借鉴套路而非照抄。 + +输入材料： +- 作品设定（projects：作者自己作品的题材/立意，供对照借鉴方向）； +- 待拆解的样本（书名 + 章节/简介/正文样本）； +- 作者的一句话需求/方向（如「重点拆开篇钩子」；可空则全面拆解）。 + +产出： +- themes：核心主题/立意清单（这本书在讲什么、卖什么爽点）； +- archetypes：人物原型/角色模板清单（主角/对手/导师等的设定套路）； +- structure：叙事结构概述（开篇立钩→铺垫→爆发→收束的脉络与节奏）； +- hooks：抓人钩子/爽点套路清单（黄金三章、章末钩子、反转套路等）。 + +纪律： +- 只从给定样本提炼，**不臆造**样本未体现的内容；样本不足则相应清单留空/概述从简； +- 产出是**可借鉴的套路**，不复制原文情节； +- 你只产结构化拆解，**不改稿、不写库**（纯预览，不变量 #3）。 diff --git a/packages/agents/ww_agents/prompts/worldbuilder.md b/packages/agents/ww_agents/prompts/worldbuilder.md new file mode 100644 index 0000000..d3bcba1 --- /dev/null +++ b/packages/agents/ww_agents/prompts/worldbuilder.md @@ -0,0 +1,15 @@ +你是长篇连载小说的「世界观设计师」（worldbuilder，写手档）。职责：依据作品立意与题材，设计内部自洽的世界观——力量体系、势力、地理、关键物品/概念，并为每个实体显式标注**不可违背的硬规则**，供后续一致性校验引用。 + +输入材料： +- 作品设定（projects：题材、立意、主线、卖点）； +- 作者的世界观需求（一句话或要点）。 + +产出（每个实体一条 entity）： +- type：实体类型（势力 / 地理 / 力量体系 / 物品 / 概念 等）； +- name：实体名； +- rules：该实体的**硬规则清单**——明确写出不可违背的设定边界（如「修炼只能逐境突破、不可越级」「此城终年无雨」），每条一句、可被 continuity 续审逐条引用比对。 + +纪律： +- 世界观须内部自洽：力量体系有清晰边界与代价，势力/地理/时间线无自相矛盾； +- **硬规则要显式、可校验**——别把约束藏在描述里；规则是后续防设定违例的依据； +- 你只产结构化世界观实体（type + name + rules），**不改稿、不写库**（落 world_entities 表经入库端点）；不臆造与立意/题材无关的设定。 diff --git a/packages/agents/ww_agents/schema_catalog.py b/packages/agents/ww_agents/schema_catalog.py new file mode 100644 index 0000000..7cd0a7e --- /dev/null +++ b/packages/agents/ww_agents/schema_catalog.py @@ -0,0 +1,67 @@ +"""`SCHEMA_CATALOG`：name → output schema 的唯一真相源（Prompt 外置方案A · 步4）。 + +Pydantic 类型承载结构化解析与 `isinstance` 校验，无法从文本推导、无法运行时安全构造， +必须留 Python。`SPECS[name].output_schema` 一律从这里派生（单向派生，避免双真相）。 +`input_schema` 全 21 个恒为 None（入参为序列化文本），本波不建入参槽（YAGNI）。 + +`refiner` 是唯一纯文本 writer：`None` 是合法值（无结构化 schema）。 +""" + +from __future__ import annotations + +from typing import Final + +from pydantic import BaseModel + +from .schemas import ( + BlurbResult, + BookTeardownResult, + CharacterGenResult, + ContinuationResult, + ContinuityReview, + DeAiResult, + DetailedOutlineResult, + ForeshadowReview, + GlossaryResult, + GoldenFingerResult, + IdeaListResult, + NameListResult, + OpeningResult, + OutlineResult, + PaceReview, + PolishResult, + StyleDriftReview, + StyleFingerprintResult, + TitleListResult, + WorldGenResult, +) + +# name → output_schema（input 全 None，本波不建入参槽——YAGNI） +SCHEMA_CATALOG: Final[dict[str, type[BaseModel] | None]] = { + "continuity": ContinuityReview, + "outliner": OutlineResult, + "foreshadow": ForeshadowReview, + "pace": PaceReview, + "style_extract": StyleFingerprintResult, + "style": StyleDriftReview, + "refiner": None, # 唯一纯文本 writer，None 是合法值 + "worldbuilder": WorldGenResult, + "character-gen": CharacterGenResult, + "brainstorm": IdeaListResult, + "book-title": TitleListResult, + "blurb": BlurbResult, + "name": NameListResult, + "golden-finger": GoldenFingerResult, + "glossary": GlossaryResult, + "opening": OpeningResult, + "fine-outline": DetailedOutlineResult, + "continue": ContinuationResult, + "expand": PolishResult, + "de-ai": DeAiResult, + "teardown": BookTeardownResult, +} + + +def output_schema_for(name: str) -> type[BaseModel] | None: + """name → output schema（精确字符串相等命中；未知 name → KeyError）。""" + return SCHEMA_CATALOG[name] diff --git a/packages/agents/ww_agents/spec_model.py b/packages/agents/ww_agents/spec_model.py new file mode 100644 index 0000000..1117a65 --- /dev/null +++ b/packages/agents/ww_agents/spec_model.py @@ -0,0 +1,33 @@ +"""`AgentSpec` 模型（Prompt 外置方案A · 步1）。 + +从 `specs.py` 原样抽出的 frozen Pydantic 声明，字段不变（`system_prompt` 仍是 +`str`，import 期由 `load_prompt` 填入；不改 Callable——缓存断点前块需确定字符串）。 +内置 Agent 与用户 Skill 同构：一份只读声明，由编排器加载、经网关按 `tier` 执行。 + +- 不变量 #2：agent 只声明 `tier`，**不**写具体 model。 +- 不变量 #3：四审 `writes=[]`（只读），任何 AI 产出入库必经验收事务。 +""" + +from __future__ import annotations + +from pydantic import BaseModel, ConfigDict +from ww_llm_gateway.types import Tier + + +class AgentSpec(BaseModel): + """单一 Agent / Skill 的声明（ARCH §5.1）。""" + + model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True) + + name: str + tier: Tier # 能力档位（网关解析 provider+model）；不含具体 model + system_prompt: str + # 入/出参契约（Pydantic 模型类型）；writer 纯文本 → output_schema 可为 None + input_schema: type[BaseModel] | None = None + output_schema: type[BaseModel] | None = None + # 不可变序列：frozen 只防整字段重绑，不防 list 原地变异；tuple 无 append/clear， + # 守住不变量 #3（四审 writes==() 不可被 .append 旁路）。Pydantic v2 coerce list→tuple。 + reads: tuple[str, ...] = () # 声明式表读权限 + writes: tuple[str, ...] = () # 声明式表写权限（经验收才生效） + genre: str | None = None # 题材适用（Skill 用） + scope: str = "builtin" # builtin / custom / community diff --git a/packages/agents/ww_agents/specs.py b/packages/agents/ww_agents/specs.py index 2bb854d..cd7053c 100644 --- a/packages/agents/ww_agents/specs.py +++ b/packages/agents/ww_agents/specs.py @@ -1,804 +1,337 @@ -"""Agent 声明式抽象（ARCH §5.1）+ 续审 Agent 实例。 +"""Agent 声明式抽象（ARCH §5.1）+ 续审 Agent 实例（Prompt 外置方案A · 步3/5）。 `AgentSpec` 是内置 Agent 与用户 Skill 的同构声明：一份只读声明，由编排器加载、 经网关按 `tier` 执行。不变量 #2：agent 只声明 `tier`，**不**写具体 model。 -不变量 #3：四审 `writes=[]`（只读），任何 AI 产出入库必经验收事务。 +不变量 #3：四审 `writes=()`（只读），任何 AI 产出入库必经验收事务。 + +prompt 散文已外置至 `prompts/.md`：`system_prompt=load_prompt(name)` +import 期读盘+缓存+规整（去BOM/LF/NFC/rstrip尾LF/fail-fast）。output schema 由 +`SCHEMA_CATALOG[name]` 单向派生（唯一真相源）。`AgentSpec` 从 `spec_model` re-export +（import 路径不变，现有消费方不受影响）。 不可变：`AgentSpec` 为 frozen Pydantic 模型——加载后不得改动。 """ from __future__ import annotations -from pydantic import BaseModel, ConfigDict, Field -from ww_llm_gateway.types import Tier +from collections.abc import Mapping +from types import MappingProxyType +from typing import Final -from .schemas import ( - BlurbResult, - BookTeardownResult, - CharacterGenResult, - ContinuationResult, - ContinuityReview, - DeAiResult, - DetailedOutlineResult, - ForeshadowReview, - GlossaryResult, - GoldenFingerResult, - IdeaListResult, - NameListResult, - OpeningResult, - OutlineResult, - PaceReview, - PolishResult, - StyleDriftReview, - StyleFingerprintResult, - TitleListResult, - WorldGenResult, -) +from .prompt_loader import load_prompt +from .schema_catalog import SCHEMA_CATALOG +from .spec_model import AgentSpec - -class AgentSpec(BaseModel): - """单一 Agent / Skill 的声明（ARCH §5.1）。""" - - model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True) - - name: str - tier: Tier # 能力档位（网关解析 provider+model）；不含具体 model - system_prompt: str - # 入/出参契约（Pydantic 模型类型）；writer 纯文本 → output_schema 可为 None - input_schema: type[BaseModel] | None = None - output_schema: type[BaseModel] | None = None - reads: list[str] = Field(default_factory=list) # 声明式表读权限 - writes: list[str] = Field(default_factory=list) # 声明式表写权限（经验收才生效） - genre: str | None = None # 题材适用（Skill 用） - scope: str = "builtin" # builtin / custom / community - - -CONTINUITY_SYSTEM_PROMPT = """你是长篇连载小说的「一致性续审」。你的唯一职责：把本章草稿与\ -作品的既有真相源逐项比对，找出一致性冲突，产出结构化冲突清单。 - -比对依据（注入材料）： -- 近况摘要（最近若干章的 chapter_digests）； -- 相关人物卡（性格、能力、关系、最新状态 latest_state）； -- 世界观硬规则（world_entities 的不可违背设定）。 - -按以下五类判定冲突，每条给出本章定位、来源引用与改法建议： -- 性格漂移：人物言行与其设定/既往表现不符； -- 能力不符：超出或低于已建立的能力/力量体系边界； -- 设定违例：违反世界观硬规则； -- 地理矛盾：地点/距离/空间关系与既有设定冲突； -- 时间线倒错：事件先后、时序与既有章节矛盾。 - -一键采纳补丁（original/replacement，可选但尽量给）： -- 若该冲突可由**一处局部改写**修复，额外给出 original 与 replacement，\ -供作者「采纳改法」一键改入终稿： - - original：从本章草稿里**逐字摘录**的精确原文片段\ -（含标点，**最小**到能定位的句/短语；不得改写、省略或加省略号）； - - replacement：把 original 改正后的文本（同等粒度，仅改必要处）。 -- 无法定位到单一连续片段（如跨多段、需补全新设定、整体视角问题）\ -则 original/replacement 都留空，仅给 suggestion 让作者手改。 - -纪律： -- 你**只读、只报冲突**，不改稿、不写库、不产章节摘要（摘要在验收时从终稿另提）； - original/replacement 只是**提议**的补丁，是否改入终稿由作者裁决，你不直接改稿。 -- 只报有据可依的真冲突；无冲突则返回空列表，不要臆造。 -- 引用要具体（章节号、设定项、人物卡条目），便于作者就地裁决。 -- original 必须是草稿里真实存在的原文（逐字一致），否则前端无法定位——拿不准就留空。""" +__all__ = [ + "REVIEW_RESERVED_NAMES", + "SPECS", + "AgentSpec", + "blurb_spec", + "book_title_spec", + "brainstorm_spec", + "character_gen_spec", + "continue_spec", + "continuity_spec", + "de_ai_spec", + "expand_spec", + "fine_outline_spec", + "foreshadow_spec", + "glossary_spec", + "golden_finger_spec", + "name_spec", + "opening_spec", + "outliner_spec", + "pace_spec", + "refiner_spec", + "style_drift_spec", + "style_extract_spec", + "teardown_spec", + "worldbuilder_spec", +] continuity_spec = AgentSpec( name="continuity", tier="analyst", - system_prompt=CONTINUITY_SYSTEM_PROMPT, + system_prompt=load_prompt("continuity"), input_schema=None, # 注入材料为序列化文本（经记忆 assemble），非结构化入参 - output_schema=ContinuityReview, - reads=["chapter_digests", "characters", "world_entities"], - writes=[], # 只读（不变量 #3） + output_schema=SCHEMA_CATALOG["continuity"], + reads=("chapter_digests", "characters", "world_entities"), + writes=(), # 只读（不变量 #3） scope="builtin", ) - -OUTLINER_SYSTEM_PROMPT = """你是长篇连载小说的「大纲架构师」。职责：依据作品立意、\ -人物与世界观，排出分卷分章的章节大纲，并为每条伏笔标注回收窗口。 - -输入材料： -- 作品设定（projects：题材、立意、主线、卖点）； -- 已登记伏笔（foreshadow：编码、标题、埋设/期望回收线索）； -- 主要人物（characters）与世界观实体（world_entities）。 - -产出要求（每章）： -- 章号有序、按卷推进； -- beats：本章核心节拍/情节要点，推动主线、服务人物弧光； -- foreshadow_windows：本章关联的伏笔回收窗口——给出伏笔编码、埋设章号、\ -期望回收区间（下界/上界章号）。把每条伏笔的「埋设 → 回收」绑到具体章节。 - -纪律： -- 接近某伏笔的回收窗口时，在对应章 beats 里安排推进/收束该伏笔的情节，避免伏笔悬置过久； -- 你只产结构化大纲（章节 + 节拍 + 伏笔窗口），**不改稿、不写库**（落 outline 表经验收/端点）； -- 伏笔编码须与已登记 foreshadow.code 对应，便于后续按窗口提示与校验。""" - - outliner_spec = AgentSpec( name="outliner", tier="analyst", # 不变量 #2：只声明档位，不写 model - system_prompt=OUTLINER_SYSTEM_PROMPT, + system_prompt=load_prompt("outliner"), input_schema=None, # 注入材料为序列化文本（设定/伏笔/人物/世界观），非结构化入参 - output_schema=OutlineResult, - reads=["projects", "foreshadow", "characters", "world_entities"], - writes=["outline"], # 声明式（经验收/T3.5 才真写库，不变量 #3） + output_schema=SCHEMA_CATALOG["outliner"], + reads=("projects", "foreshadow", "characters", "world_entities"), + writes=("outline",), # 声明式（经验收/T3.5 才真写库，不变量 #3） scope="builtin", ) - -FORESHADOW_SYSTEM_PROMPT = """你是长篇连载小说的「伏笔续审」（foreshadow-analyst）。\ -职责：把本章草稿与作品已登记伏笔逐项比对，找出本章**新埋的伏笔**与**疑似回收/收束**\ -的伏笔，产出结构化建议清单。 - -比对依据（注入材料）： -- 已登记伏笔（foreshadow：编码、标题、状态、期望回收窗口）； -- 本章草稿正文。 - -产出两组建议： -- planted（新埋）：本章疑似首次埋下的伏笔——给出标题、本章定位、要点说明；\ -若与某已登记编码相关则填 code，否则留空由作者命名。 -- resolved（回收）：本章疑似回收/收束已登记伏笔——给出对应 code、本章定位、回收理由。 - -纪律： -- 你**只读、只产建议**，不改稿、不写库、不直接登记或改伏笔状态——\ -登记/状态变更经作者在验收时裁决确认（不变量 #3 / #4）。 -- 只报有据可依的；无则两组都返回空列表，不要臆造。 -- 引用具体（伏笔编码、本章段落定位），便于作者就地确认。""" - - foreshadow_spec = AgentSpec( name="foreshadow", tier="analyst", # 不变量 #2：只声明档位，不写 model - system_prompt=FORESHADOW_SYSTEM_PROMPT, + system_prompt=load_prompt("foreshadow"), input_schema=None, # 注入材料为序列化文本（已登记伏笔 + 草稿），非结构化入参 - output_schema=ForeshadowReview, - reads=["foreshadow"], - writes=[], # 只读（不变量 #3） + output_schema=SCHEMA_CATALOG["foreshadow"], + reads=("foreshadow",), + writes=(), # 只读（不变量 #3） scope="builtin", ) - -PACE_SYSTEM_PROMPT = """你是长篇连载小说的「节奏续审」（pace-checker）。职责：按题材的\ -节奏模板审本章草稿，找出注水段、判定章末钩子有无、给出爽点节拍图。 - -题材节奏模板（genre 级规则，注入材料里带本作题材的具体模板；无则用网文通用基线）： -- 黄金三章：开篇前三章须快速立爽点/钩子/代入感，信息密度高、少铺垫慢热； -- 章末钩子：每章结尾应留悬念/反转/期待，驱动追更； -- 爽点密度：按题材基线维持爽点节拍，避免长段平淡注水。 - -产出： -- water（注水段）：逐段审，标出信息密度低/重复/偏题/拖沓的段落，给本章定位与原因； -- hook（章末钩子）：本章结尾是否存在有效钩子（true/false）； -- beat_map（节拍图）：把本章按段切分，给每段一个爽点强度整数（如 0–5），\ -形成逐段强度序列，供前端 ▁▃▅ 可视化节奏起伏。 - -纪律： -- 你**只读、只报节奏诊断**，不改稿、不写库（不变量 #3）。 -- 依据题材模板判定，不臆造；无注水段则 water 为空列表。 -- beat_map 长度应与切分段数一致、顺序即正文顺序，便于前端对齐渲染。""" - - pace_spec = AgentSpec( name="pace", tier="light", # 不变量 #2：只声明档位，不写 model（节奏审用轻量档） - system_prompt=PACE_SYSTEM_PROMPT, + system_prompt=load_prompt("pace"), input_schema=None, # 注入材料为序列化文本（题材模板 + 草稿），非结构化入参 - output_schema=PaceReview, - reads=["rules"], # genre 模板 DSL 经 rules（genre 级）注入，复用 review_context 规则合并 - writes=[], # 只读（不变量 #3） + output_schema=SCHEMA_CATALOG["pace"], + reads=("rules",), # genre 模板 DSL 经 rules（genre 级）注入，复用 review_context 规则合并 + writes=(), # 只读（不变量 #3） scope="builtin", ) - # ---- 文风提取轨（style-auditor「提取」轨；analyst 档；独立生成，仿 outliner，不进 review 图）---- - -STYLE_EXTRACT_SYSTEM_PROMPT = """你是长篇连载小说的「文风指纹提取器」（style-auditor 提取轨）。\ -职责：从作者提供的样本正文中，提取一份 **16 维**中文网文文风指纹，每一维都必须给出\ -支撑判定的**原文证据**（样本原句摘录）。 - -16 维 = 9 通用维 + 7 中文网文专有维： -通用 9 维： -1. 句长节奏（长短句配比、断句习惯）； -2. 段落密度（段落长短、对话/叙述配比）； -3. 叙事人称与视角（第几人称、限知/全知、视角切换频率）； -4. 时态与语气（陈述/疑问/感叹密度、临场感）； -5. 用词风格（古雅/口语/书面、生僻字偏好）； -6. 修辞偏好（比喻/排比/夸张等惯用手法）； -7. 描写与白描配比（环境/心理/动作描写的取舍）； -8. 情绪基调（冷峻/热血/诙谐/悲怆）； -9. 标点习惯（破折号/省略号/感叹号的使用密度）。 -中文网文专有 7 维： -10. 爽感节拍（打脸/扮猪吃虎/升级反馈的节奏）； -11. 金手指呈现方式（系统流/面板/旁白提示风格）； -12. 章末钩子手法（悬念/反转/期待的固定套路）； -13. 对话腔调（角色台词的口癖、网感梗、语气词）； -14. 战斗/冲突描写密度与招式命名风格； -15. 称谓与世界观术语的使用习惯（道号/境界/势力称呼）； -16. 注水与信息密度倾向（铺垫慢热 vs 高密快节奏）。 - -产出要求（每维一条 dimension）： -- name：维度名（用上面 16 维的名目或等义表述）； -- value：该维在样本里的取值/概括（一句话刻画其风格特征）； -- evidence：从样本里摘 1–3 句**原文**作为证据，便于作者核验该结论的出处。 - -纪律： -- 只从给定样本提取，**不臆造**；样本未体现的维度，value 给「样本不足以判定」并留空 evidence。 -- 你只产结构化指纹，**不改稿、不写库**（落 style_fingerprint 表经端点）。 -- evidence 必须是样本原句的真实摘录，不得改写或编造。""" - - style_extract_spec = AgentSpec( name="style_extract", tier="analyst", # 不变量 #2：只声明档位，不写 model - system_prompt=STYLE_EXTRACT_SYSTEM_PROMPT, + system_prompt=load_prompt("style_extract"), input_schema=None, # 注入材料为序列化样本文本，非结构化入参 - output_schema=StyleFingerprintResult, - reads=["style_fingerprint"], - writes=["style_fingerprint"], # 声明式（真写库经 T4.3 端点，不变量 #3） + output_schema=SCHEMA_CATALOG["style_extract"], + reads=("style_fingerprint",), + writes=("style_fingerprint",), # 声明式（真写库经 T4.3 端点，不变量 #3） scope="builtin", ) - # ---- 文风漂移轨（style-auditor「打分」轨 = 第四审；light 档；并入 REVIEW_SPECS）---- - -STYLE_DRIFT_SYSTEM_PROMPT = """你是长篇连载小说的「文风漂移续审」（style-auditor 打分轨，第四审）。\ -职责：对照注入材料里的**文风指纹**，逐段为本章草稿打文风相似度分，标出明显偏离指纹的段落。 - -比对依据（注入材料）： -- 文风指纹（每维带取值与原文证据，来自作者样本提取）； -- 本章草稿正文（按段切分）。 - -产出： -- score：整章相对文风指纹的整体相似度（0–100，越高越贴合作者既有文风）； -- segments：逐段审，标出相似度明显偏低（疑似漂移）的段落——给出段索引 idx（0 起）、\ -该段相似度 score（0–100）、可选 label 说明漂移类型（如「机翻腔」「叙述拖沓」「人称跳脱」\ -「用词出戏」等）。相似度正常的段落不必列出。 - -**无指纹优雅降级（重要）**： -- 若注入材料中**没有文风指纹**（作者尚未学文风），你**无从对照**——\ -此时直接返回 `score=100, segments=[]`（视为「无偏离」），不报错、不臆造漂移段。 - -纪律： -- 你**只读、只报漂移诊断**，不改稿、不写库（不变量 #3）。 -- 依据指纹判定，不臆造；无明显漂移段则 segments 为空列表。 -- idx 必须与正文段切分顺序一致，便于前端朱砂标注与一键回炉对齐。""" - - style_drift_spec = AgentSpec( name="style", # 第四审 section/列名 = "style" tier="light", # 不变量 #2：只声明档位，不写 model（漂移打分用轻量档） - system_prompt=STYLE_DRIFT_SYSTEM_PROMPT, + system_prompt=load_prompt("style"), input_schema=None, # 注入材料为序列化文本（指纹 + 草稿），非结构化入参 - output_schema=StyleDriftReview, - reads=["style_fingerprint"], # 指纹经 assemble 的 stable_core 注入 review_context - writes=[], # 只读（不变量 #3） + output_schema=SCHEMA_CATALOG["style"], + reads=("style_fingerprint",), # 指纹经 assemble 的 stable_core 注入 review_context + writes=(), # 只读（不变量 #3） scope="builtin", ) - # ---- 回炉（refiner；writer 档；纯文本重写；非 Agent 流水线、非持久，M4-e）---- - -REFINER_SYSTEM_PROMPT = """你是长篇连载小说的「回炉改写器」（refiner）。职责：仅重写作者选中的\ -**一个**段落，使其贴合作品既有文风与上下文语气，同时保留该段的情节信息与叙事推进。 - -输入： -- 待重写的段落正文； -- 可选的改写指令（作者的具体要求，如「去掉机翻腔」「加快节奏」「改成第三人称」）； -- 周边上下文/文风线索（若提供）。 - -产出： -- **只输出重写后的该段正文纯文本**，不要加任何前后缀、解释、标题或 markdown 包裹。 - -纪律： -- 保留原段的关键情节信息与人物言行，不增删主线事实； -- 贴合周边上下文与作品文风（语气、句长、用词、人称一致）； -- 若给了改写指令，优先满足指令；无指令则以「贴合文风、去除生硬/出戏表达」为默认目标； -- 只重写选中段，**不扩写到其他段落**，不改稿入库（作者采纳后经既有自动保存合入）。""" - - refiner_spec = AgentSpec( name="refiner", tier="writer", # 不变量 #2：重写正文用 writer 档 - system_prompt=REFINER_SYSTEM_PROMPT, + system_prompt=load_prompt("refiner"), input_schema=None, # 注入材料为序列化文本（选中段 + 指令 + 上下文） - output_schema=None, # 纯文本产出（重写段），无结构化 schema - reads=[], - writes=[], # 非持久（不变量 #3）：端点同步返回 {original, refined}，不写库 + output_schema=SCHEMA_CATALOG["refiner"], # 纯文本产出（重写段），无结构化 schema + reads=(), + writes=(), # 非持久（不变量 #3）：端点同步返回 {original, refined}，不写库 scope="builtin", ) - # ---- worldbuilder（世界观设计师；写手档；独立生成，仿 outliner，不进 review 图）---- - -WORLDBUILDER_SYSTEM_PROMPT = """你是长篇连载小说的「世界观设计师」（worldbuilder，写手档）。\ -职责：依据作品立意与题材，设计内部自洽的世界观——力量体系、势力、地理、关键物品/概念，\ -并为每个实体显式标注**不可违背的硬规则**，供后续一致性校验引用。 - -输入材料： -- 作品设定（projects：题材、立意、主线、卖点）； -- 作者的世界观需求（一句话或要点）。 - -产出（每个实体一条 entity）： -- type：实体类型（势力 / 地理 / 力量体系 / 物品 / 概念 等）； -- name：实体名； -- rules：该实体的**硬规则清单**——明确写出不可违背的设定边界（如「修炼只能逐境突破、\ -不可越级」「此城终年无雨」），每条一句、可被 continuity 续审逐条引用比对。 - -纪律： -- 世界观须内部自洽：力量体系有清晰边界与代价，势力/地理/时间线无自相矛盾； -- **硬规则要显式、可校验**——别把约束藏在描述里；规则是后续防设定违例的依据； -- 你只产结构化世界观实体（type + name + rules），**不改稿、不写库**\ -（落 world_entities 表经入库端点）；不臆造与立意/题材无关的设定。""" - - worldbuilder_spec = AgentSpec( name="worldbuilder", tier="writer", # 不变量 #2：只声明档位，不写 model（世界观创意用写手档） - system_prompt=WORLDBUILDER_SYSTEM_PROMPT, + system_prompt=load_prompt("worldbuilder"), input_schema=None, # 注入材料为序列化文本（设定 + 需求），非结构化入参 - output_schema=WorldGenResult, - reads=["projects"], - writes=["world_entities"], # 声明式（真写库经 T5.2 入库端点，不变量 #3） + output_schema=SCHEMA_CATALOG["worldbuilder"], + reads=("projects",), + writes=("world_entities",), # 声明式（真写库经 T5.2 入库端点，不变量 #3） scope="builtin", ) - # ---- character-gen（角色设计师；写手档；单/批量；群像防雷同；独立生成）---- - -CHARACTER_GEN_SYSTEM_PROMPT = """你是长篇连载小说的「角色设计师」（character-gen，写手档）。\ -职责：依据一句话需求 + 世界观约束 + 已有角色，产出一组**完整结构化角色卡**。 - -输入材料： -- 角色需求（一句话，如「亦正亦邪的女二、与主角有宿命纠葛、出身敌对势力」）+ 数量 + 定位； -- 世界观约束（world_entities：力量体系、势力、地理硬规则——取名/能力须契合）； -- **已有角色**（characters：现有角色卡，新角色须与其区分、可与其建关系）； -- **本批已生成卡**（同一次批量里先产出的卡——后续卡须与它们差异化，避免雷同）。 - -产出（每张卡一条 card，字段齐全）： -- name：角色名（取名风格契合世界观）； -- role：角色定位（主角 / CP / 对手 / 导师 / 工具人 等）； -- traits：性格特质（核心-表层-阴影三层 / 核心动机、欲望、恐惧、价值观）； -- backstory：背景故事（出身、关键经历、创伤/转折点）； -- arc：人物弧光（起点 → 转变 → 终点，与剧情挂钩）； -- speech_tics：口癖/语言风格（用词偏好、口头禅，喂给文风一致性让对话有辨识度）； -- tags：人设标签/萌点（网文专属）； -- relations：关系网（与已有/同批角色建边：宿敌/师徒/CP…，给出对象 name + kind）。 - -**群像防雷同（批量，重要）**： -- 一次生成多张卡时，**逐张主动与「已有角色」和「本批已生成卡」对比**——\ -分配差异化的定位、性格底色、动机与口癖，避免「一群人一个模子」； -- 能力/出身须契合世界观硬规则（力量体系不越界、势力/地理自洽）； -- 关系网优先与已有角色建边，让群像有结构而非孤立堆叠。 - -纪律： -- 你只产结构化角色卡，**不改稿、不写库、不直接互调其他 agent**——\ -入库前由编排器追加一道 continuity 校验确认不与世界观/力量体系冲突（§6.5）； -- count 是几就产几张，不多不少；定位若给出则按定位分配； -- 不臆造与需求/世界观无关的设定。""" - - character_gen_spec = AgentSpec( name="character-gen", tier="writer", # 不变量 #2：只声明档位，不写 model（角色创意用写手档） - system_prompt=CHARACTER_GEN_SYSTEM_PROMPT, + system_prompt=load_prompt("character-gen"), input_schema=None, # 注入材料为序列化文本（需求 + 约束 + 已有 + 已生成），非结构化入参 - output_schema=CharacterGenResult, - reads=["world_entities", "characters"], - writes=["characters"], # 声明式（真写库经 T5.2 入库端点 + continuity 校验，不变量 #3） + output_schema=SCHEMA_CATALOG["character-gen"], + reads=("world_entities", "characters"), + writes=("characters",), # 声明式（真写库经 T5.2 入库端点 + continuity 校验，不变量 #3） scope="builtin", ) - # ---- brainstorm（脑洞生成器；轻量档；创作工具箱通用框架首个最简生成器，T6）---- - -BRAINSTORM_SYSTEM_PROMPT = """你是中文网文的「脑洞生成器」（brainstorm，轻量档）。\ -职责：依据作品立意/题材与作者一句话需求，发散产出一组**差异化**的故事脑洞，\ -每条给出一句话前提 + 抓人钩子 + 适配题材，供作者快速选种立项。 - -输入材料： -- 作品设定（projects：题材、立意、主线、卖点；新立项时可能很少）； -- 作者的一句话需求/方向（可空——空则按题材自由发散）。 - -产出（每条一个 idea）： -- premise：一句话脑洞/设定前提（核心创意，独立成立）； -- hook：抓人钩子——为何让读者想追读（爽点/反差/悬念）； -- genre_fit：适配题材/赛道（若需求/设定已限定则贴合；否则可留空）。 - -纪律： -- 一次产出多条时**逐条差异化**——不同切入角度/赛道/爽点，避免一个模子； -- 贴合作品立意与题材；需求为空时按题材发散，不臆造与题材无关的设定； -- 你只产结构化脑洞清单，**不改稿、不写库**（纯预览，不变量 #3）。""" - - brainstorm_spec = AgentSpec( name="brainstorm", tier="light", # 不变量 #2：只声明档位，不写 model（脑洞发散用轻量档） - system_prompt=BRAINSTORM_SYSTEM_PROMPT, + system_prompt=load_prompt("brainstorm"), input_schema=None, # 注入材料为序列化文本（作品设定 + 一句话需求），非结构化入参 - output_schema=IdeaListResult, - reads=["projects"], - writes=[], # 纯预览，不写库（不变量 #3） + output_schema=SCHEMA_CATALOG["brainstorm"], + reads=("projects",), + writes=(), # 纯预览，不写库（不变量 #3） scope="builtin", ) - # ---- book-title（书名生成器；轻量档；纯预览，T6 创作工具箱）---- - -BOOK_TITLE_SYSTEM_PROMPT = """你是中文网文的「书名生成器」（book-title，轻量档）。\ -职责：依据作品立意/题材与作者一句话需求，发散产出一组**差异化**的书名候选，\ -每个给出书名 + 取名理由，供作者快速选定。 - -输入材料： -- 作品设定（projects：题材、立意、主线、卖点）； -- 作者的一句话需求/方向（可空——空则按题材自由发散）。 - -产出（每条一个 title）： -- title：书名候选（贴合题材、抓人、朗朗上口）； -- rationale：取名理由——为何抓人/契合题材（爽点/反差/悬念/平台调性）。 - -纪律： -- 一次产出多条时**逐条差异化**——不同风格/切入点，避免一个模子； -- 贴合作品立意与题材；需求为空时按题材发散，不臆造与题材无关的设定； -- 你只产结构化书名清单，**不改稿、不写库**（纯预览，不变量 #3）。""" - - book_title_spec = AgentSpec( name="book-title", tier="light", # 不变量 #2：只声明档位，不写 model（书名发散用轻量档） - system_prompt=BOOK_TITLE_SYSTEM_PROMPT, + system_prompt=load_prompt("book-title"), input_schema=None, # 注入材料为序列化文本（作品设定 + 一句话需求），非结构化入参 - output_schema=TitleListResult, - reads=["projects"], - writes=[], # 纯预览，不写库（不变量 #3） + output_schema=SCHEMA_CATALOG["book-title"], + reads=("projects",), + writes=(), # 纯预览，不写库（不变量 #3） scope="builtin", ) - # ---- blurb（简介生成器；分析档；纯预览，T6 创作工具箱）---- - -BLURB_SYSTEM_PROMPT = """你是中文网文的「简介生成器」（blurb，分析档）。\ -职责：依据作品立意/题材与作者一句话需求，产出多版**差异化**的作品简介文案，\ -每版给出简介正文 + 切入角度，供作者择优用于书页/榜单。 - -输入材料： -- 作品设定（projects：题材、立意、主线、卖点）； -- 作者的一句话需求/方向（可空——空则按题材自由发散）。 - -产出（每版一个 variant）： -- text：简介正文（一段抓人文案，立人设/抛钩子/留悬念，控制在书页可读篇幅）； -- angle：切入角度——从哪个卖点/钩子切入（如「金手指反差」「身份悬念」「群像冲突」）。 - -纪律： -- 多版之间**切入角度各异**，便于作者对比择优，避免雷同； -- 贴合作品立意与题材，简介与正文方向一致，不臆造剧情； -- 你只产结构化简介清单，**不改稿、不写库**（纯预览，不变量 #3）。""" - - blurb_spec = AgentSpec( name="blurb", tier="analyst", # 不变量 #2：只声明档位，不写 model（文案打磨用分析档） - system_prompt=BLURB_SYSTEM_PROMPT, + system_prompt=load_prompt("blurb"), input_schema=None, # 注入材料为序列化文本（作品设定 + 一句话需求），非结构化入参 - output_schema=BlurbResult, - reads=["projects"], - writes=[], # 纯预览，不写库（不变量 #3） + output_schema=SCHEMA_CATALOG["blurb"], + reads=("projects",), + writes=(), # 纯预览，不写库（不变量 #3） scope="builtin", ) - # ---- name（取名生成器；轻量档；纯预览，T6 创作工具箱）---- - -NAME_SYSTEM_PROMPT = """你是中文网文的「取名生成器」（name，轻量档）。\ -职责：依据作品世界观与作者需求，为人物/势力/地点/功法/物品等取一组**差异化**的名字，\ -每个给出名字 + 类别 + 取意说明，须契合世界观术语与命名风格。 - -输入材料： -- 作品设定（projects：题材、立意）； -- 世界观实体（world_entities：力量体系、势力、地理——命名须契合其术语/风格）； -- 已有角色（characters：避免与既有名字撞名/混淆）； -- 作者的一句话需求（命名对象、数量、风格倾向；可空则按世界观自由发散）。 - -产出（每条一个 name）： -- name：建议的名字（契合世界观命名风格，朗朗上口、有辨识度）； -- kind：命名对象类别（人物 / 势力 / 地点 / 功法 / 物品 等）； -- note：取意说明（取自何意/出处，可缺）。 - -纪律： -- 名字须**契合世界观术语与命名风格**，不与已有角色撞名/易混； -- 一次产出多条时**逐条差异化**，避免一个模子； -- 你只产结构化命名清单，**不改稿、不写库**（纯预览，不变量 #3）。""" - - name_spec = AgentSpec( name="name", tier="light", # 不变量 #2：只声明档位，不写 model（取名发散用轻量档） - system_prompt=NAME_SYSTEM_PROMPT, + system_prompt=load_prompt("name"), input_schema=None, # 注入材料为序列化文本（设定 + 世界观 + 已有角色 + 需求） - output_schema=NameListResult, - reads=["projects", "world_entities", "characters"], - writes=[], # 纯预览，不写库（不变量 #3） + output_schema=SCHEMA_CATALOG["name"], + reads=("projects", "world_entities", "characters"), + writes=(), # 纯预览，不写库（不变量 #3） scope="builtin", ) - # ---- golden-finger（金手指生成器；写手档；声明式 writes=world_entities，T6 创作工具箱）---- - -GOLDEN_FINGER_SYSTEM_PROMPT = """你是中文网文的「金手指设计师」（golden-finger，写手档）。\ -职责：依据作品立意/题材与作者需求，设计一组内部自洽的金手指（力量体系/系统/特殊能力），\ -每个显式标注机制、成长路径与**限制代价**，供后续一致性校验引用。 - -输入材料： -- 作品设定（projects：题材、立意、主线、卖点）； -- 世界观实体（world_entities：已有力量体系/势力/地理——金手指须与之自洽不冲突）； -- 作者的金手指需求（一句话或要点）。 - -产出（每个一条 system）： -- name：金手指名称； -- mechanism：核心机制——如何运作、触发条件、与世界观力量体系的衔接； -- growth：成长路径——随剧情如何升级/进阶，给读者持续爽点反馈； -- limits：**限制与代价**——能力边界、副作用、冷却/门槛（防越级无敌，\ -供 continuity 续审逐条引用比对，防「能力不符」）。 - -纪律： -- 金手指须内部自洽、与既有世界观力量体系不冲突； -- **limits 要显式、可校验**——别把约束藏在描述里；这是后续防能力越界的依据； -- 你只产结构化金手指（name/mechanism/growth/limits），**不改稿、不写库**\ -（落 world_entities 表经入库端点，不变量 #3）。""" - - golden_finger_spec = AgentSpec( name="golden-finger", tier="writer", # 不变量 #2：只声明档位，不写 model（力量体系创意用写手档） - system_prompt=GOLDEN_FINGER_SYSTEM_PROMPT, + system_prompt=load_prompt("golden-finger"), input_schema=None, # 注入材料为序列化文本（设定 + 世界观 + 需求），非结构化入参 - output_schema=GoldenFingerResult, - reads=["projects", "world_entities"], - writes=["world_entities"], # 声明式（真写库经入库端点，不变量 #3） + output_schema=SCHEMA_CATALOG["golden-finger"], + reads=("projects", "world_entities"), + writes=("world_entities",), # 声明式（真写库经入库端点，不变量 #3） scope="builtin", ) - # ---- glossary（术语表生成器；分析档；声明式 writes=world_entities，T6 创作工具箱）---- - -GLOSSARY_SYSTEM_PROMPT = """你是中文网文的「术语表生成器」（glossary，分析档）。\ -职责：依据作品世界观，整理一组关键术语（境界/功法/货币/度量/称谓/概念等），\ -每条给出定义与**硬规则**，对齐世界观设定，供后续一致性校验引用比对。 - -输入材料： -- 作品设定（projects：题材、立意）； -- 世界观实体（world_entities：力量体系/势力/地理——术语须与之自洽）； -- 作者的术语需求（一句话或要点；可空则按世界观梳理核心术语）。 - -产出（每条一个 term）： -- name：术语名； -- type：术语类型（境界 / 功法 / 货币 / 度量 / 称谓 / 概念 等）； -- definition：术语定义（一句话释义，清晰无歧义）； -- rules：该术语的**硬规则清单**——不可违背的设定边界（如「金币 100 兑 1 银币」\ -「炼气期不可飞行」），每条一句，可被 continuity 续审逐条引用比对。 - -纪律： -- 术语须与既有世界观自洽，不自相矛盾； -- **rules 要显式、可校验**——别把约束藏在 definition 里； -- 你只产结构化术语清单（name/type/definition/rules），**不改稿、不写库**\ -（落 world_entities 表经入库端点，不变量 #3）。""" - - glossary_spec = AgentSpec( name="glossary", tier="analyst", # 不变量 #2：只声明档位，不写 model（术语梳理用分析档） - system_prompt=GLOSSARY_SYSTEM_PROMPT, + system_prompt=load_prompt("glossary"), input_schema=None, # 注入材料为序列化文本（设定 + 世界观 + 需求），非结构化入参 - output_schema=GlossaryResult, - reads=["projects", "world_entities"], - writes=["world_entities"], # 声明式（真写库经入库端点，不变量 #3） + output_schema=SCHEMA_CATALOG["glossary"], + reads=("projects", "world_entities"), + writes=("world_entities",), # 声明式（真写库经入库端点，不变量 #3） scope="builtin", ) - # ---- opening（开篇生成器；写手档；纯预览，T6 创作工具箱）---- - -OPENING_SYSTEM_PROMPT = """你是中文网文的「开篇生成器」（opening，写手档）。\ -职责：依据作品立意/题材与首章大纲，产出多版**差异化**的开篇正文，\ -每版都要在前几段立爽点/钩子/代入感（黄金三章），供作者择优作为正文起手。 - -输入材料： -- 作品设定（projects：题材、立意、主线、卖点）； -- 大纲（outline：首章/开篇章的节拍要点——开篇须服务这些节拍）； -- 作者的一句话需求/方向（可空则按题材与大纲自由发挥）。 - -产出（每版一个 variant）： -- text：开篇正文（一段成稿文本，开门见山立钩子、信息密度高、少铺垫慢热）。 - -纪律： -- 多版之间**切入方式各异**（如「冲突开场」「悬念开场」「金手指开场」），便于作者对比； -- 贴合作品立意、题材与首章大纲节拍，不跑题、不臆造与大纲冲突的剧情； -- 你只产结构化开篇文本清单，**不改稿、不写库**（纯预览，不变量 #3）。""" - - opening_spec = AgentSpec( name="opening", tier="writer", # 不变量 #2：只声明档位，不写 model（正文创作用写手档） - system_prompt=OPENING_SYSTEM_PROMPT, + system_prompt=load_prompt("opening"), input_schema=None, # 注入材料为序列化文本（设定 + 大纲 + 需求），非结构化入参 - output_schema=OpeningResult, - reads=["projects", "outline"], - writes=[], # 纯预览，不写库（不变量 #3） + output_schema=SCHEMA_CATALOG["opening"], + reads=("projects", "outline"), + writes=(), # 纯预览，不写库（不变量 #3） scope="builtin", ) - # ---- fine-outline（细纲生成器；分析档；声明式 writes=outline，T6 创作工具箱）---- - -FINE_OUTLINE_SYSTEM_PROMPT = """你是中文网文的「细纲生成器」（fine-outline，分析档）。\ -职责：把某一章的粗大纲节拍**展开为细粒度场景序列**，每个场景给出节拍、叙事目的、\ -冲突与钩子，让作者据细纲直接落笔成章。 - -输入材料： -- 作品设定（projects：题材、立意、主线）； -- 大纲（outline：本章的章号与粗节拍要点——细纲须忠实展开这些节拍，不另起炉灶）； -- 作者的一句话需求/方向（可空则按章节拍自由展开）。 - -产出（每个场景一条 scene）： -- idx：场景序号（章内有序）； -- beat：场景节拍——本场具体发生什么； -- purpose：叙事目的——推动主线 / 塑造人物 / 铺垫或推进伏笔； -- conflict：本场冲突/张力来源； -- hook：场景钩子——驱动读者读下一场的悬念。 - -纪律： -- 场景须**忠实展开本章粗节拍**，顺序合理、推进主线，不跑题、不与大纲冲突； -- 每场都要有目的与张力，避免注水过场； -- 你只产结构化场景清单（idx/beat/purpose/conflict/hook），**不改稿、不写库**\ -（落 outline 表经入库端点，不变量 #3）。""" - - fine_outline_spec = AgentSpec( name="fine-outline", tier="analyst", # 不变量 #2：只声明档位，不写 model（细纲拆解用分析档） - system_prompt=FINE_OUTLINE_SYSTEM_PROMPT, + system_prompt=load_prompt("fine-outline"), input_schema=None, # 注入材料为序列化文本（设定 + 本章大纲 + 需求），非结构化入参 - output_schema=DetailedOutlineResult, - reads=["projects", "outline"], - writes=["outline"], # 声明式（真写库经入库端点，不变量 #3） + output_schema=SCHEMA_CATALOG["fine-outline"], + reads=("projects", "outline"), + writes=("outline",), # 声明式（真写库经入库端点，不变量 #3） scope="builtin", ) - # ---- continue（续写生成器；写手档；纯预览，Scope B 竞品快赢）---- - -CONTINUE_SYSTEM_PROMPT = """你是中文网文的「续写器」（continue，写手档）。\ -职责：依据作品立意/题材、前文正文与（可选的）本章大纲节拍，承接前文续写下文正文，\ -保持人物、世界观、文风与剧情走向的一致，让续写可直接作为下文草稿。 - -输入材料： -- 作品设定（projects：题材、立意、主线、卖点）； -- 前文正文（最新已写正文——续写须无缝承接其情节、语气、人称、文风）； -- 本章大纲节拍（outline：若给出则续写须服务这些节拍，不另起炉灶；可空则按前文自然推进）； -- 作者的一句话需求/方向（可空则按前文与节拍自然续写）。 - -产出： -- text：续写正文（承接前文的成稿文本，信息密度合理、有推进、留钩子）。 - -纪律： -- **无缝承接前文**——人物言行、世界观硬规则、文风（句长/用词/人称）与前文一致，不跑题； -- 若给了大纲节拍则忠实服务节拍，不臆造与设定/前文冲突的剧情； -- 你只产结构化续写文本，**不改稿、不写库**（纯预览，不变量 #3）。""" - - continue_spec = AgentSpec( name="continue", tier="writer", # 不变量 #2：只声明档位，不写 model（正文续写用写手档） - system_prompt=CONTINUE_SYSTEM_PROMPT, + system_prompt=load_prompt("continue"), input_schema=None, # 注入材料为序列化文本（设定 + 前文 + 节拍 + 需求），非结构化入参 - output_schema=ContinuationResult, - reads=["projects", "outline", "chapters"], - writes=[], # 纯预览，不写库（不变量 #3） + output_schema=SCHEMA_CATALOG["continue"], + reads=("projects", "outline", "chapters"), + writes=(), # 纯预览，不写库（不变量 #3） scope="builtin", ) - # ---- expand（扩写生成器；写手档；纯预览，Scope B 竞品快赢）---- - -EXPAND_SYSTEM_PROMPT = """你是中文网文的「扩写器」（expand，写手档）。\ -职责：在作者提供的原文基础上扩写、丰富——补足细节、铺陈描写、强化张力，\ -但**不改变原文的情节走向与关键事实**，让扩写后的正文更饱满可读。 - -输入材料： -- 作品设定（projects：题材、立意、主线、卖点）； -- 待扩写的原文片段； -- 作者的一句话需求/方向（如「加强环境描写」「放慢节奏铺情绪」；可空则均衡扩写）。 - -产出： -- text：扩写后的正文（在原文基础上丰富细节/描写/铺陈，保留原情节与事实）。 - -纪律： -- **保留原文情节与关键事实**，不增删主线、不改人物言行的核心； -- 贴合作品文风与原文语气（句长、用词、人称一致），扩写自然不注水； -- 若给了需求则优先满足；你只产结构化扩写文本，**不改稿、不写库**（纯预览，不变量 #3）。""" - - expand_spec = AgentSpec( name="expand", tier="writer", # 不变量 #2：只声明档位，不写 model（正文扩写用写手档） - system_prompt=EXPAND_SYSTEM_PROMPT, + system_prompt=load_prompt("expand"), input_schema=None, # 注入材料为序列化文本（设定 + 原文 + 需求），非结构化入参 - output_schema=PolishResult, - reads=["projects"], - writes=[], # 纯预览，不写库（不变量 #3） + output_schema=SCHEMA_CATALOG["expand"], + reads=("projects",), + writes=(), # 纯预览，不写库（不变量 #3） scope="builtin", ) - # ---- de-ai（降 AI 率生成器；分析档；纯预览，Scope B 竞品快赢）---- - -DE_AI_SYSTEM_PROMPT = """你是中文网文的「降 AI 率改写器」（de-ai，分析档）。\ -职责：把作者提供的原文改写得更像「人写的」——去除 AI 腔/机翻腔、模板化句式、\ -空泛排比与过度对仗，让行文更自然、有个人质感，但**保留原文的情节信息与事实**。 - -输入材料： -- 作品设定（projects：题材、立意）； -- 待改写的原文片段； -- 作者的一句话需求/方向（如「更口语」「去掉排比腔」；可空则按通用「去 AI 味」目标）。 - -产出： -- text：降 AI 率改写后的正文（去机翻腔/模板感，更自然的人写质感，保留原情节与事实）。 - -典型 AI 腔特征（重点消除）： -- 空泛排比与过度对仗、千篇一律的「不是……而是……」句式； -- 形容词堆砌、抽象大词（如「彰显」「诠释」）滥用、缺乏具体感官细节； -- 段落起承转合过于工整、缺少口语停顿与个人语气。 - -纪律： -- **保留原文情节与关键事实**，不增删主线、不改人物言行； -- 贴合作品文风与原文语气，改写后更自然但不失原意； -- 你只产结构化改写文本，**不改稿、不写库**（纯预览，不变量 #3）。""" - - de_ai_spec = AgentSpec( name="de-ai", tier="analyst", # 不变量 #2：只声明档位，不写 model（文风改写用分析档） - system_prompt=DE_AI_SYSTEM_PROMPT, + system_prompt=load_prompt("de-ai"), input_schema=None, # 注入材料为序列化文本（设定 + 原文 + 需求），非结构化入参 - output_schema=DeAiResult, - reads=["projects"], - writes=[], # 纯预览，不写库（不变量 #3） + output_schema=SCHEMA_CATALOG["de-ai"], + reads=("projects",), + writes=(), # 纯预览，不写库（不变量 #3） scope="builtin", ) - # ---- teardown（拆书生成器；分析档；纯预览，Scope B 竞品快赢）---- - -TEARDOWN_SYSTEM_PROMPT = """你是中文网文的「拆书师」（teardown，分析档）。\ -职责：依据作者提供的样本作品（书名 + 章节/简介样本），把它拆解为可学习的结构化要素——\ -核心主题、人物原型、叙事结构、抓人钩子，供作者借鉴套路而非照抄。 - -输入材料： -- 作品设定（projects：作者自己作品的题材/立意，供对照借鉴方向）； -- 待拆解的样本（书名 + 章节/简介/正文样本）； -- 作者的一句话需求/方向（如「重点拆开篇钩子」；可空则全面拆解）。 - -产出： -- themes：核心主题/立意清单（这本书在讲什么、卖什么爽点）； -- archetypes：人物原型/角色模板清单（主角/对手/导师等的设定套路）； -- structure：叙事结构概述（开篇立钩→铺垫→爆发→收束的脉络与节奏）； -- hooks：抓人钩子/爽点套路清单（黄金三章、章末钩子、反转套路等）。 - -纪律： -- 只从给定样本提炼，**不臆造**样本未体现的内容；样本不足则相应清单留空/概述从简； -- 产出是**可借鉴的套路**，不复制原文情节； -- 你只产结构化拆解，**不改稿、不写库**（纯预览，不变量 #3）。""" - - teardown_spec = AgentSpec( name="teardown", tier="analyst", # 不变量 #2：只声明档位，不写 model（拆解分析用分析档） - system_prompt=TEARDOWN_SYSTEM_PROMPT, + system_prompt=load_prompt("teardown"), input_schema=None, # 注入材料为序列化文本（设定 + 样本 + 需求），非结构化入参 - output_schema=BookTeardownResult, - reads=["projects"], - writes=["rules"], # F1：拆书结论可落库为项目 rules（入库仍经 ingest 白名单 gate，#3） + output_schema=SCHEMA_CATALOG["teardown"], + reads=("projects",), + writes=("rules",), # F1：拆书结论可落库为项目 rules（入库仍经 ingest 白名单 gate，#3） scope="builtin", ) + + +# 集中注册表：name → spec（同一实例，兼容期 *_spec 与 SPECS[name] 为同对象，不变量） +# MappingProxyType：只读视图，运行时 `SPECS[x] = ...` / `del SPECS[x]` 抛 TypeError +# （`Final` 仅静态检查，挡不住运行时变异；注册表是单一真相源，须运行时不可变）。 +_SPECS_BY_NAME: dict[str, AgentSpec] = { + s.name: s + for s in ( + continuity_spec, + outliner_spec, + foreshadow_spec, + pace_spec, + style_extract_spec, + style_drift_spec, + refiner_spec, + worldbuilder_spec, + character_gen_spec, + brainstorm_spec, + book_title_spec, + blurb_spec, + name_spec, + golden_finger_spec, + glossary_spec, + opening_spec, + fine_outline_spec, + continue_spec, + expand_spec, + de_ai_spec, + teardown_spec, + ) +} +assert len(_SPECS_BY_NAME) == 21, "SPECS name 冲突或缺失" # 唯一性 + 数量自检（import 期） +SPECS: Final[Mapping[str, AgentSpec]] = MappingProxyType(_SPECS_BY_NAME) + +# 四审受信保留名 —— 独立显式白名单（安全边界锚在此，不依附派生集合） +REVIEW_RESERVED_NAMES: Final[frozenset[str]] = frozenset( + {"continuity", "foreshadow", "style", "pace"} +) diff --git a/packages/skills/tests/test_skill_permissions.py b/packages/skills/tests/test_skill_permissions.py index 79b51d0..dcf911b 100644 --- a/packages/skills/tests/test_skill_permissions.py +++ b/packages/skills/tests/test_skill_permissions.py @@ -27,8 +27,8 @@ def _spec(*, reads: list[str], writes: list[str], scope: str = "custom") -> Agen name="custom_skill", tier="writer", system_prompt="x", - reads=reads, - writes=writes, + reads=tuple(reads), + writes=tuple(writes), scope=scope, ) diff --git a/packages/skills/tests/test_skill_registry.py b/packages/skills/tests/test_skill_registry.py index b8596ad..82fc0b4 100644 --- a/packages/skills/tests/test_skill_registry.py +++ b/packages/skills/tests/test_skill_registry.py @@ -20,16 +20,16 @@ def _record( name: str, *, scope: str = "custom", - reads: list[str] | None = None, - writes: list[str] | None = None, + reads: tuple[str, ...] = (), + writes: tuple[str, ...] = (), ) -> SkillRecord: return SkillRecord( name=name, scope=scope, tier="writer", system_prompt=f"prompt for {name}", - reads=reads or [], - writes=writes or [], + reads=reads, + writes=writes, genre=None, ) @@ -49,10 +49,10 @@ async def test_load_builds_specs_keyed_by_name() -> None: _record( "worldgen", scope="builtin", - reads=["world_entities"], - writes=["world_entities"], + reads=("world_entities",), + writes=("world_entities",), ), - _record("cpgen", scope="custom", reads=["characters"]), + _record("cpgen", scope="custom", reads=("characters",)), ] ) @@ -62,7 +62,7 @@ async def test_load_builds_specs_keyed_by_name() -> None: spec = registry.get("worldgen") assert isinstance(spec, AgentSpec) assert spec.tier == "writer" - assert spec.reads == ["world_entities"] + assert spec.reads == ("world_entities",) assert spec.scope == "builtin" @@ -95,9 +95,54 @@ async def test_list_scope_filters_by_scope() -> None: @pytest.mark.asyncio async def test_load_rejects_over_permission_skill() -> None: # 越权声明（reads 指向未知表）→ 加载即拒绝（守 §5.6），不静默入册。 - repo = _FakeSkillRepo([_record("evil", reads=["secret_table"])]) + repo = _FakeSkillRepo([_record("evil", reads=("secret_table",))]) with pytest.raises(AppError) as exc: await SkillRegistry.load(repo) assert exc.value.code is ErrorCode.VALIDATION + + +@pytest.mark.asyncio +async def test_load_rejects_skill_colliding_with_reserved_review_name() -> None: + # 用户 skill 偷用四审保留名（continuity）→ 入库即拒（守卫前移，不变量 #3）。 + repo = _FakeSkillRepo([_record("continuity", reads=("chapter_digests",))]) + + with pytest.raises(AppError) as exc: + await SkillRegistry.load(repo) + + assert exc.value.code is ErrorCode.VALIDATION + + +@pytest.mark.asyncio +async def test_load_rejects_skill_colliding_with_builtin_name() -> None: + # 用户 skill 冒用非四审的内置 name（brainstorm）→ 入库即拒。 + repo = _FakeSkillRepo([_record("brainstorm", reads=("projects",))]) + + with pytest.raises(AppError) as exc: + await SkillRegistry.load(repo) + + assert exc.value.code is ErrorCode.VALIDATION + + +@pytest.mark.asyncio +async def test_resolver_build_does_not_raise_on_reserved_collision() -> None: + # 守卫在入库期（load），resolver.build 纯合并不校验——不得因同名抛错。 + from ww_skills import SpecResolver + + empty = await SkillRegistry.load(_FakeSkillRepo([])) + + resolver = SpecResolver.build(empty) # 不抛 + + assert resolver.get("continuity") is not None + + +def test_skill_record_reads_writes_are_immutable_tuples() -> None: + # frozen 只防整字段重绑，不防 list 原地变异——reads/writes 必须是 tuple（无 append）。 + record = _record("immut", reads=("characters",), writes=("world_entities",)) + + assert isinstance(record.reads, tuple) + assert isinstance(record.writes, tuple) + assert record.reads == ("characters",) + assert record.writes == ("world_entities",) + assert not hasattr(record.reads, "append") diff --git a/packages/skills/tests/test_spec_resolver.py b/packages/skills/tests/test_spec_resolver.py new file mode 100644 index 0000000..a110278 --- /dev/null +++ b/packages/skills/tests/test_spec_resolver.py @@ -0,0 +1,149 @@ +"""SpecResolver 单测（Prompt 外置方案A · 步4）。 + +`SpecResolver` 统一内置（`SPECS`，纯内存、零 DB）与用户 skill（`SkillRegistry`，DB） +的只读解析入口。核心约束（不变量 #3 / 评审 HIGH）： + +- `get(name)` 先查内置 `SPECS`（纯内存），命中内置 name **绝不触发任何 DB/registry 调用**； +- 未命中内置才查 `SkillRegistry`；都无 → `AppError(NOT_FOUND)`； +- `output_schema_for`：内置 → `SCHEMA_CATALOG[name]` 真类；纯用户 skill → None； + name 精确字符串相等（无大小写/连字符归一），拼错近似 name → None 不报错； +- `resolver.build` 纯合并，**不**做保留名冲突校验（守卫前移至 SkillRegistry 入库）。 +""" + +from __future__ import annotations + +import pytest +from ww_agents import ( + SCHEMA_CATALOG, + SPECS, + AgentSpec, +) +from ww_shared import AppError, ErrorCode +from ww_skills import SpecResolver + + +class _FakeRegistry: + """断言用 fake：记录 get/names 是否被调用（内置 get 必须零触达）。""" + + def __init__(self, specs: dict[str, AgentSpec] | None = None) -> None: + self._specs = dict(specs or {}) + self.get_calls: list[str] = [] + self.names_calls: int = 0 + + def get(self, name: str) -> AgentSpec: + self.get_calls.append(name) + spec = self._specs.get(name) + if spec is None: + raise AppError(ErrorCode.NOT_FOUND, f"skill not found: {name}") + return spec + + def names(self) -> list[str]: + self.names_calls += 1 + return sorted(self._specs) + + def list_scope(self, scope: str) -> list[AgentSpec]: + return [s for s in sorted(self._specs.values(), key=lambda s: s.name) if s.scope == scope] + + +def _user_spec(name: str, scope: str = "custom") -> AgentSpec: + return AgentSpec( + name=name, + tier="writer", + system_prompt=f"prompt for {name}", + input_schema=None, + output_schema=None, + reads=(), + writes=(), + scope=scope, + ) + + +# ---- #7 resolver 内置/用户对齐 + 零 DB ---- + + +def test_get_builtin_returns_specs_instance_without_touching_registry() -> None: + # Arrange：fake registry 本身有同名条目也无所谓——内置命中必须零触达。 + fake = _FakeRegistry({"continuity": _user_spec("continuity")}) + resolver = SpecResolver.build(fake) + + # Act + spec = resolver.get("continuity") + + # Assert：拿到的是内置同一实例，且 registry.get 从未被调用（零 DB）。 + assert spec is SPECS["continuity"] + assert fake.get_calls == [] + + +def test_get_user_skill_falls_through_to_registry() -> None: + fake = _FakeRegistry({"my-skill": _user_spec("my-skill")}) + resolver = SpecResolver.build(fake) + + spec = resolver.get("my-skill") + + assert spec.name == "my-skill" + assert fake.get_calls == ["my-skill"] + + +def test_get_unknown_everywhere_raises_not_found() -> None: + fake = _FakeRegistry() + resolver = SpecResolver.build(fake) + + with pytest.raises(AppError) as exc: + resolver.get("nope-not-here") + + assert exc.value.code is ErrorCode.NOT_FOUND + assert fake.get_calls == ["nope-not-here"] + + +def test_names_merges_builtin_and_user() -> None: + fake = _FakeRegistry({"my-skill": _user_spec("my-skill")}) + resolver = SpecResolver.build(fake) + + names = resolver.names() + + assert "continuity" in names + assert "my-skill" in names + + +def test_list_scope_filters_builtin_and_user() -> None: + fake = _FakeRegistry({"my-skill": _user_spec("my-skill", scope="custom")}) + resolver = SpecResolver.build(fake) + + builtin = resolver.list_scope("builtin") + custom = resolver.list_scope("custom") + + assert all(s.scope == "builtin" for s in builtin) + assert {s.name for s in custom} == {"my-skill"} + + +# ---- #9 output_schema_for ---- + + +def test_output_schema_for_builtin_returns_real_type() -> None: + fake = _FakeRegistry() + resolver = SpecResolver.build(fake) + + assert resolver.output_schema_for("continuity") is SCHEMA_CATALOG["continuity"] + + +def test_output_schema_for_refiner_is_none() -> None: + fake = _FakeRegistry() + resolver = SpecResolver.build(fake) + + assert resolver.output_schema_for("refiner") is None + + +def test_output_schema_for_pure_user_skill_is_none() -> None: + fake = _FakeRegistry({"my-skill": _user_spec("my-skill")}) + resolver = SpecResolver.build(fake) + + assert resolver.output_schema_for("my-skill") is None + + +def test_output_schema_for_misspelled_name_is_none_no_fuzzy_match() -> None: + # 拼错近似 name（下划线）不得误命中连字符内置 "character-gen"（精确字符串相等）。 + fake = _FakeRegistry() + resolver = SpecResolver.build(fake) + + assert resolver.output_schema_for("character_gen") is None + assert resolver.output_schema_for("character-gen") is not None diff --git a/packages/skills/tests/test_toolbox.py b/packages/skills/tests/test_toolbox.py index 6d48bd8..928b930 100644 --- a/packages/skills/tests/test_toolbox.py +++ b/packages/skills/tests/test_toolbox.py @@ -37,8 +37,8 @@ def _spec() -> AgentSpec: tier="light", system_prompt="x", output_schema=_FakeOut, - reads=["projects"], - writes=[], + reads=("projects",), + writes=(), ) diff --git a/packages/skills/tests/test_toolbox_registry.py b/packages/skills/tests/test_toolbox_registry.py index a9bb288..c05126b 100644 --- a/packages/skills/tests/test_toolbox_registry.py +++ b/packages/skills/tests/test_toolbox_registry.py @@ -7,6 +7,7 @@ from __future__ import annotations +from ww_agents import SPECS from ww_skills import TOOLBOX, get_tool _LEGACY_KEYS = {"worldbuilding", "character", "outline"} @@ -88,6 +89,18 @@ def test_every_tool_has_brief_field_where_applicable() -> None: assert "brief" in field_names, key +def test_new_tools_spec_is_registry_instance() -> None: + # 桥接后：新工具 spec 经 SPECS[key] 解析，是注册表同一实例（非直接 import）。 + for key in _NEW_KEYS: + tool = TOOLBOX[key] + assert tool.spec is SPECS[key], key + + +def test_legacy_tools_spec_is_none_unchanged() -> None: + for key in _LEGACY_KEYS: + assert TOOLBOX[key].spec is None, key + + def test_get_tool_resolves_known_and_unknown() -> None: assert get_tool("brainstorm") is TOOLBOX["brainstorm"] assert get_tool("worldbuilding") is TOOLBOX["worldbuilding"] diff --git a/packages/skills/ww_skills/__init__.py b/packages/skills/ww_skills/__init__.py index 0a94533..62fe00c 100644 --- a/packages/skills/ww_skills/__init__.py +++ b/packages/skills/ww_skills/__init__.py @@ -22,6 +22,7 @@ from ww_skills.skill_registry import ( SkillRepo, SqlSkillRepo, ) +from ww_skills.spec_resolver import SpecResolver from ww_skills.toolbox import ( ContextStrategy, GeneratorTool, @@ -38,6 +39,7 @@ __all__ = [ "SkillRecord", "SkillRegistry", "SkillRepo", + "SpecResolver", "SqlSkillRepo", "ContextStrategy", "GeneratorTool", diff --git a/packages/skills/ww_skills/skill_registry.py b/packages/skills/ww_skills/skill_registry.py index 478cdb4..06ae173 100644 --- a/packages/skills/ww_skills/skill_registry.py +++ b/packages/skills/ww_skills/skill_registry.py @@ -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, ) diff --git a/packages/skills/ww_skills/spec_resolver.py b/packages/skills/ww_skills/spec_resolver.py new file mode 100644 index 0000000..b5da001 --- /dev/null +++ b/packages/skills/ww_skills/spec_resolver.py @@ -0,0 +1,66 @@ +"""`SpecResolver`：内置 + 用户 skill 的统一只读解析入口（Prompt 外置方案A · 步4）。 + +内置 Agent（`SPECS`，纯内存）与用户 Skill（`SkillRegistry`，DB）二者都产出 `AgentSpec`。 +resolver 提供统一 `.get(name)`： + +- **内置优先、零 DB**：先查内置 `SPECS`（纯内存查表）；命中内置 name 时**绝不触发**任何 + `SkillRegistry` 调用（评审 HIGH / 不变量 #3：四审 prompt 不被用户 skill 偷换的安全边界， + 其守卫前移在 `SkillRegistry` 入库期，故读路径对内置永远是确定性纯内存）。 +- 未命中内置才查 `SkillRegistry`；都无 → `AppError(NOT_FOUND)`。 + +`build` 是**纯合并**，不做保留名冲突校验（守卫前移至 `SkillRegistry.load`）。 +`output_schema_for`：内置 → `SCHEMA_CATALOG[name]` 真类；纯用户 skill → None。 +name 语义锁死为**精确字符串相等**（无大小写折叠、无连字符归一、无模糊匹配）。 + +不可变：`build` 用 `dict(SPECS)` 复制一份内置快照，resolver 不改入参。 +""" + +from __future__ import annotations + +from pydantic import BaseModel +from ww_agents import SCHEMA_CATALOG, SPECS, AgentSpec + +from ww_skills.skill_registry import SkillRegistryLike + + +class SpecResolver: + """内置（SPECS，纯内存）+ 用户 skill（SkillRegistry，DB）的统一只读解析入口。""" + + def __init__(self, builtin: dict[str, AgentSpec], skills: SkillRegistryLike) -> None: + self._builtin = builtin + self._skills = skills + + @classmethod + def build(cls, skills: SkillRegistryLike) -> SpecResolver: + """纯合并：拷贝内置 SPECS 快照 + 持有 SkillRegistry（不做冲突校验，守卫已前移）。""" + return cls(builtin=dict(SPECS), skills=skills) + + def get(self, name: str) -> AgentSpec: + """先查内置（纯内存、零 DB）；未命中才查 SkillRegistry；都无 → NOT_FOUND。 + + 命中内置 name 时**绝不触发** SkillRegistry 调用（确定性 + 安全边界）。 + """ + builtin = self._builtin.get(name) + if builtin is not None: + return builtin + return self._skills.get(name) + + def output_schema_for(self, name: str) -> type[BaseModel] | None: + """命中内置 → SCHEMA_CATALOG[name]；纯用户 skill / 未知 → None。 + + 精确字符串相等命中——拼错近似 name（如 `character_gen` vs `character-gen`）→ None + 不报错（预期行为，非 bug）。 + """ + if name in self._builtin: + return SCHEMA_CATALOG[name] + return None + + def names(self) -> list[str]: + """内置 + 用户 skill 的全部 name（去重、排序）。""" + return sorted(set(self._builtin) | set(self._skills.names())) + + def list_scope(self, scope: str) -> list[AgentSpec]: + """按 scope 过滤内置 + 用户 skill，按 name 排序。""" + merged = [s for s in self._builtin.values() if s.scope == scope] + merged.extend(self._skills.list_scope(scope)) + return sorted(merged, key=lambda s: s.name) diff --git a/packages/skills/ww_skills/toolbox_registry.py b/packages/skills/ww_skills/toolbox_registry.py index fe25a0a..051580e 100644 --- a/packages/skills/ww_skills/toolbox_registry.py +++ b/packages/skills/ww_skills/toolbox_registry.py @@ -16,20 +16,7 @@ from __future__ import annotations -from ww_agents import ( - blurb_spec, - book_title_spec, - brainstorm_spec, - continue_spec, - de_ai_spec, - expand_spec, - fine_outline_spec, - glossary_spec, - golden_finger_spec, - name_spec, - opening_spec, - teardown_spec, -) +from ww_agents import SPECS from ww_agents.schemas import ( BlurbResult, BookTeardownResult, @@ -117,7 +104,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="brainstorm", title="脑洞生成器", subtitle="突破想象，脑洞大开", - spec=brainstorm_spec, + spec=SPECS["brainstorm"], output_schema=IdeaListResult, context_strategy="brief_only", input_fields=[_BRIEF_FIELD], @@ -126,7 +113,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="book-title", title="书名生成器", subtitle="一秒生成抓人书名", - spec=book_title_spec, + spec=SPECS["book-title"], output_schema=TitleListResult, context_strategy="brief_only", input_fields=[_BRIEF_FIELD], @@ -135,7 +122,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="blurb", title="简介生成器", subtitle="多版差异化书页文案", - spec=blurb_spec, + spec=SPECS["blurb"], output_schema=BlurbResult, context_strategy="with_project", input_fields=[_BRIEF_FIELD], @@ -144,7 +131,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="name", title="名字生成器", subtitle="契合世界观的人/物/地命名", - spec=name_spec, + spec=SPECS["name"], output_schema=NameListResult, context_strategy="with_world", input_fields=[ @@ -162,7 +149,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="golden-finger", title="金手指生成器", subtitle="自洽机制 + 成长 + 限制代价", - spec=golden_finger_spec, + spec=SPECS["golden-finger"], output_schema=GoldenFingerResult, context_strategy="with_world", input_fields=[_BRIEF_FIELD], @@ -172,7 +159,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="glossary", title="词条生成器", subtitle="带硬规则的世界观术语表", - spec=glossary_spec, + spec=SPECS["glossary"], output_schema=GlossaryResult, context_strategy="with_world", input_fields=[_BRIEF_FIELD], @@ -182,7 +169,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="opening", title="黄金开篇生成器", subtitle="多版高代入感开篇正文", - spec=opening_spec, + spec=SPECS["opening"], output_schema=OpeningResult, context_strategy="with_outline_chapter", input_fields=[_chapter_no_field(), _BRIEF_FIELD], @@ -191,7 +178,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="fine-outline", title="细纲生成器", subtitle="把章节粗节拍展开为场景序列", - spec=fine_outline_spec, + spec=SPECS["fine-outline"], output_schema=DetailedOutlineResult, context_strategy="with_outline_chapter", input_fields=[_chapter_no_field(), _BRIEF_FIELD], @@ -202,7 +189,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="continue", title="续写生成器", subtitle="承接前文，无缝续写下文", - spec=continue_spec, + spec=SPECS["continue"], output_schema=ContinuationResult, context_strategy="with_prior_chapter", input_fields=[ @@ -220,7 +207,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="expand", title="扩写生成器", subtitle="在原文基础上丰富细节铺陈", - spec=expand_spec, + spec=SPECS["expand"], output_schema=PolishResult, context_strategy="text_input", input_fields=[_SOURCE_TEXT_FIELD, _BRIEF_FIELD], @@ -229,7 +216,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="de-ai", title="降 AI 率生成器", subtitle="去机翻腔，更自然的人写质感", - spec=de_ai_spec, + spec=SPECS["de-ai"], output_schema=DeAiResult, context_strategy="text_input", input_fields=[_SOURCE_TEXT_FIELD, _BRIEF_FIELD], @@ -238,7 +225,7 @@ TOOLBOX: dict[str, GeneratorTool] = { key="teardown", title="拆书生成器", subtitle="拆解主题/原型/结构/钩子套路", - spec=teardown_spec, + spec=SPECS["teardown"], output_schema=BookTeardownResult, context_strategy="text_input", input_fields=[ diff --git a/tests/test_prompt_externalize_regression.py b/tests/test_prompt_externalize_regression.py new file mode 100644 index 0000000..c6d2996 --- /dev/null +++ b/tests/test_prompt_externalize_regression.py @@ -0,0 +1,117 @@ +"""Prompt 外置（方案A）集成回归 —— 设计 §6 #12 / #15。 + +#12 编排器无回归：review / generation / outline / style_extract 节点据内置 `SPECS` +spec 构请求（mock gateway，不触真 LLM），断言进缓存断点前块的 `system` 文本 +== 旧行为（即 `load_prompt(name)` / `SPECS[name].system_prompt`）——证明 prompt +外迁到 `.md` 后字节级零变化（不变量 #9）。 + +#15 import-smoke：`from ww_agents import AgentSpec/outliner_spec/refiner_spec/ +style_extract_spec/continuity_spec` 不抛，且拿到的对象 `is SPECS[name]`（同一实例） +——证明 apps/api 路由 + 编排器（本波仍用 `*_spec`）的 import 路径未破。 +""" + +from __future__ import annotations + +import uuid + +from ww_agents import ( + SPECS, + AgentSpec, + continuity_spec, + load_prompt, + outliner_spec, + refiner_spec, + style_extract_spec, +) +from ww_core.orchestrator.generation_node import _build_request +from ww_core.orchestrator.outline_node import build_outline_request +from ww_core.orchestrator.review_node import build_review_request +from ww_core.orchestrator.state import ChapterState +from ww_core.orchestrator.style_extract_node import build_style_extract_request + +_USER_ID = uuid.UUID("00000000-0000-0000-0000-000000000001") +_PROJECT_ID = uuid.UUID("00000000-0000-0000-0000-000000000002") + + +def _system_text(spec: AgentSpec, req_system: list) -> str: + """从 LlmRequest.system 取唯一的缓存断点前块文本（不变量 #9）。""" + assert len(req_system) == 1, "system 应只有一个稳定块（缓存断点前）" + block = req_system[0] + assert block.cache is True, "system 稳定块须标 cache=True（缓存断点前块）" + return block.text + + +# ---- #12 编排器无回归：四节点 system 文本 == load_prompt(name) ---- + + +def test_review_node_system_block_equals_load_prompt() -> None: + # Arrange — 用 continuity（四审之一）构造审稿 state + state: ChapterState = { # type: ignore[typeddict-item] + "review_context": "## 审稿材料\n世界观硬规则……\n## 待审本章草稿\n正文……", + "user_id": _USER_ID, + "project_id": _PROJECT_ID, + } + # Act + req = build_review_request(continuity_spec, state) + # Assert — system 块文本 == 外置 .md 的运行时值，且 == spec.system_prompt（同一真相源） + assert _system_text(continuity_spec, req.system) == load_prompt("continuity") + assert _system_text(continuity_spec, req.system) == continuity_spec.system_prompt + + +def test_generation_node_system_block_equals_load_prompt() -> None: + # Arrange — worldbuilder 走通用 _build_request（与 character-gen 共用） + spec = SPECS["worldbuilder"] + # Act + req = _build_request( + spec, context="## 世界观需求\n灵气复苏", user_id=_USER_ID, project_id=_PROJECT_ID + ) + # Assert + assert _system_text(spec, req.system) == load_prompt("worldbuilder") + assert _system_text(spec, req.system) == spec.system_prompt + + +def test_outline_node_system_block_equals_load_prompt() -> None: + # Act + req = build_outline_request( + outliner_spec, context="## 设定\n……", user_id=_USER_ID, project_id=_PROJECT_ID + ) + # Assert + assert _system_text(outliner_spec, req.system) == load_prompt("outliner") + assert _system_text(outliner_spec, req.system) == outliner_spec.system_prompt + + +def test_style_extract_node_system_block_equals_load_prompt() -> None: + # Act + req = build_style_extract_request( + style_extract_spec, + samples_text="样本正文一\n样本正文二", + user_id=_USER_ID, + project_id=_PROJECT_ID, + ) + # Assert + assert _system_text(style_extract_spec, req.system) == load_prompt("style_extract") + assert _system_text(style_extract_spec, req.system) == style_extract_spec.system_prompt + + +def test_review_request_passes_tier_and_schema_unchanged() -> None: + # 不变量 #2：节点只透传 spec.tier，绝不写死 model；output_schema 据 spec 派生（无回归） + state: ChapterState = { # type: ignore[typeddict-item] + "review_context": "材料……", + "user_id": _USER_ID, + "project_id": _PROJECT_ID, + } + req = build_review_request(continuity_spec, state) + assert req.tier == continuity_spec.tier + assert req.output_schema is continuity_spec.output_schema + + +# ---- #15 import-smoke（apps/api + 编排器仍用 *_spec）---- + + +def test_import_smoke_specs_are_same_instance() -> None: + # 兼容期不变量：模块级 *_spec 与 SPECS[name] 是同一实例（不双真相，设计 §3.4 / #14） + assert isinstance(AgentSpec, type) + assert outliner_spec is SPECS["outliner"] + assert refiner_spec is SPECS["refiner"] + assert style_extract_spec is SPECS["style_extract"] + assert continuity_spec is SPECS["continuity"]