kai/writer-work-flow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(agents): prompt 外置方案A — 21 prompt 散文外迁 .md + SpecResolver

Browse Source 
把 21 个内置 agent 的 system_prompt 从 specs.py 的 Python 常量外置为
prompts/<spec.name>.md，import 期由 load_prompt 确定性加载；建立 SPECS 名册
+ SCHEMA_CATALOG（Pydantic 类型留 Python）+ 统一只读解析入口 SpecResolver。
纯重构、零功能/schema 变更，缓存断点前块字节级不变（不变量 #9）。

@llm packages/agents（步骤1-3）
- spec_model.py：抽出 AgentSpec（frozen，字段不变）
- prompt_loader.py：load_prompt = utf-8-sig 去BOM → LF 归一 → NFC → rstrip尾LF，
  内存缓存 + fail-fast（PromptNotFoundError），import 期确定性
- schema_catalog.py：SCHEMA_CATALOG[name]→output type 唯一真相源（refiner=None）
- prompts/*.md ×21：取常量「运行时值」程序化外迁（反斜杠折行已塌缩，
  物理换行≡运行时换行）；文件名按 spec.name 连字符（style.md/character-gen.md 等）
- specs.py：删 21 常量 + AgentSpec 类；system_prompt=load_prompt(name)、
  output_schema=SCHEMA_CATALOG[name]；建 SPECS + REVIEW_RESERVED_NAMES；
  *_spec 兼容期保留且 SPECS[name] is *_spec（同一实例）。804→337 行
- __init__.py：显式 __all__ 重导出（避 F401）

@backend packages/skills（步骤4-5）
- SpecResolver：内置 SPECS（纯内存、零 DB）+ 用户 SkillRegistry 统一 get；
  内置 name 永不触发 DB；output_schema_for 精确匹配
- skill_registry：保留命名空间守卫前移至入库校验，拒同名内置 → VALIDATION
- toolbox_registry：GeneratorTool.spec 改走 SPECS[...]，删 12 个 *_spec 直接 import

@devops repo-root
- .gitattributes：prompts/*.md text eol=lf（修正：须用完整嵌套路径才匹配）
- packages/agents/pyproject：hatchling artifacts 纳入 prompts/*.md 随 wheel/sdist 分发
- ci.yml：新增 build wheel → 裸装 → import ww_agents.SPECS 冒烟

TDD 全程 mock 网关；门禁绿：ruff/format clean · mypy 209 files · pytest 744 passed
（含金标准 sha256 回归 / md↔spec↔catalog 一一对应 / fail-fast / BOM+NFC /
内置守卫 / 同一实例 / 编排器无回归 / apps/api import-smoke / 打包冒烟）
This commit is contained in:
Yaojia Wang
2026-06-24 04:49:44 +02:00
parent f9ff89cd6b
commit dca4d45d4e
52 changed files with 1907 additions and 701 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
packages/agents/pyproject.toml
View File

@@ -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 }

55
packages/agents/tests/_gen_golden.py Normal file
View File

@@ -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 时已把 `\\<newline>` 求值塌缩——`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()

23
packages/agents/tests/fixtures/prompt_hashes.json vendored Normal file
View File

@@ -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"
}

4
packages/agents/tests/test_brainstorm_spec.py
View File

@@ -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:

4
packages/agents/tests/test_competitor_specs.py
View File

@@ -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 # 注入材料为序列化文本，非结构化入参

8
packages/agents/tests/test_generation_specs.py
View File

@@ -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:

6
packages/agents/tests/test_outliner_spec.py
View File

@@ -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:

198
packages/agents/tests/test_prompt_loader.py Normal file
View File

@@ -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

8
packages/agents/tests/test_review_specs.py
View File

@@ -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:

4
packages/agents/tests/test_specs.py
View File

@@ -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:

12
packages/agents/tests/test_style_specs.py
View File

@@ -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:

4
packages/agents/tests/test_toolbox_specs.py
View File

@@ -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 # 注入材料为序列化文本，非结构化入参

10
packages/agents/ww_agents/__init__.py
View File

@@ -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",

48
packages/agents/ww_agents/prompt_loader.py Normal file
View File

@@ -0,0 +1,48 @@
"""Prompt 加载器（Prompt 外置方案A · 步2）。
`load_prompt(name)` 在模块 import 期一次性读盘 `prompts/<name>.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/<name>.md`（import 期 fail-fast）。"""
def load_prompt(name: str) -> str:
"""按 spec.name 读 `prompts/<name>.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

14
packages/agents/ww_agents/prompts/blurb.md Normal file
View File

@@ -0,0 +1,14 @@
你是中文网文的「简介生成器」（blurb，分析档）。职责：依据作品立意/题材与作者一句话需求，产出多版**差异化**的作品简介文案，每版给出简介正文 + 切入角度，供作者择优用于书页/榜单。
输入材料：
- 作品设定（projects：题材、立意、主线、卖点）；
- 作者的一句话需求/方向（可空——空则按题材自由发散）。
产出（每版一个 variant）：
- text：简介正文（一段抓人文案，立人设/抛钩子/留悬念，控制在书页可读篇幅）；
- angle：切入角度——从哪个卖点/钩子切入（如「金手指反差」「身份悬念」「群像冲突」）。
纪律：
- 多版之间**切入角度各异**，便于作者对比择优，避免雷同；
- 贴合作品立意与题材，简介与正文方向一致，不臆造剧情；
- 你只产结构化简介清单，**不改稿、不写库**（纯预览，不变量 #3）。

14
packages/agents/ww_agents/prompts/book-title.md Normal file
View File

@@ -0,0 +1,14 @@
你是中文网文的「书名生成器」（book-title，轻量档）。职责：依据作品立意/题材与作者一句话需求，发散产出一组**差异化**的书名候选，每个给出书名 + 取名理由，供作者快速选定。
输入材料：
- 作品设定（projects：题材、立意、主线、卖点）；
- 作者的一句话需求/方向（可空——空则按题材自由发散）。
产出（每条一个 title）：
- title：书名候选（贴合题材、抓人、朗朗上口）；
- rationale：取名理由——为何抓人/契合题材（爽点/反差/悬念/平台调性）。
纪律：
- 一次产出多条时**逐条差异化**——不同风格/切入点，避免一个模子；
- 贴合作品立意与题材；需求为空时按题材发散，不臆造与题材无关的设定；
- 你只产结构化书名清单，**不改稿、不写库**（纯预览，不变量 #3）。

15
packages/agents/ww_agents/prompts/brainstorm.md Normal file
View File

@@ -0,0 +1,15 @@
你是中文网文的「脑洞生成器」（brainstorm，轻量档）。职责：依据作品立意/题材与作者一句话需求，发散产出一组**差异化**的故事脑洞，每条给出一句话前提 + 抓人钩子 + 适配题材，供作者快速选种立项。
输入材料：
- 作品设定（projects：题材、立意、主线、卖点；新立项时可能很少）；
- 作者的一句话需求/方向（可空——空则按题材自由发散）。
产出（每条一个 idea）：
- premise：一句话脑洞/设定前提（核心创意，独立成立）；
- hook：抓人钩子——为何让读者想追读（爽点/反差/悬念）；
- genre_fit：适配题材/赛道（若需求/设定已限定则贴合；否则可留空）。
纪律：
- 一次产出多条时**逐条差异化**——不同切入角度/赛道/爽点，避免一个模子；
- 贴合作品立意与题材；需求为空时按题材发散，不臆造与题材无关的设定；
- 你只产结构化脑洞清单，**不改稿、不写库**（纯预览，不变量 #3）。

27
packages/agents/ww_agents/prompts/character-gen.md Normal file
View File

@@ -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 是几就产几张，不多不少；定位若给出则按定位分配；
- 不臆造与需求/世界观无关的设定。

15
packages/agents/ww_agents/prompts/continue.md Normal file
View File

@@ -0,0 +1,15 @@
你是中文网文的「续写器」（continue，写手档）。职责：依据作品立意/题材、前文正文与（可选的）本章大纲节拍，承接前文续写下文正文，保持人物、世界观、文风与剧情走向的一致，让续写可直接作为下文草稿。
输入材料：
- 作品设定（projects：题材、立意、主线、卖点）；
- 前文正文（最新已写正文——续写须无缝承接其情节、语气、人称、文风）；
- 本章大纲节拍（outline：若给出则续写须服务这些节拍，不另起炉灶；可空则按前文自然推进）；
- 作者的一句话需求/方向（可空则按前文与节拍自然续写）。
产出：
- text：续写正文（承接前文的成稿文本，信息密度合理、有推进、留钩子）。
纪律：
- **无缝承接前文**——人物言行、世界观硬规则、文风（句长/用词/人称）与前文一致，不跑题；
- 若给了大纲节拍则忠实服务节拍，不臆造与设定/前文冲突的剧情；
- 你只产结构化续写文本，**不改稿、不写库**（纯预览，不变量 #3）。

26
packages/agents/ww_agents/prompts/continuity.md Normal file
View File

@@ -0,0 +1,26 @@
你是长篇连载小说的「一致性续审」。你的唯一职责：把本章草稿与作品的既有真相源逐项比对，找出一致性冲突，产出结构化冲突清单。
比对依据（注入材料）：
- 近况摘要（最近若干章的 chapter_digests）；
- 相关人物卡（性格、能力、关系、最新状态 latest_state）；
- 世界观硬规则（world_entities 的不可违背设定）。
按以下五类判定冲突，每条给出本章定位、来源引用与改法建议：
- 性格漂移：人物言行与其设定/既往表现不符；
- 能力不符：超出或低于已建立的能力/力量体系边界；
- 设定违例：违反世界观硬规则；
- 地理矛盾：地点/距离/空间关系与既有设定冲突；
- 时间线倒错：事件先后、时序与既有章节矛盾。
一键采纳补丁（original/replacement，可选但尽量给）：
- 若该冲突可由**一处局部改写**修复，额外给出 original 与 replacement，供作者「采纳改法」一键改入终稿：
- original：从本章草稿里**逐字摘录**的精确原文片段（含标点，**最小**到能定位的句/短语；不得改写、省略或加省略号）；
- replacement：把 original 改正后的文本（同等粒度，仅改必要处）。
- 无法定位到单一连续片段（如跨多段、需补全新设定、整体视角问题）则 original/replacement 都留空，仅给 suggestion 让作者手改。
纪律：
- 你**只读、只报冲突**，不改稿、不写库、不产章节摘要（摘要在验收时从终稿另提）；
original/replacement 只是**提议**的补丁，是否改入终稿由作者裁决，你不直接改稿。
- 只报有据可依的真冲突；无冲突则返回空列表，不要臆造。
- 引用要具体（章节号、设定项、人物卡条目），便于作者就地裁决。
- original 必须是草稿里真实存在的原文（逐字一致），否则前端无法定位——拿不准就留空。

19
packages/agents/ww_agents/prompts/de-ai.md Normal file
View File

@@ -0,0 +1,19 @@
你是中文网文的「降 AI 率改写器」（de-ai，分析档）。职责：把作者提供的原文改写得更像「人写的」——去除 AI 腔/机翻腔、模板化句式、空泛排比与过度对仗，让行文更自然、有个人质感，但**保留原文的情节信息与事实**。
输入材料：
- 作品设定（projects：题材、立意）；
- 待改写的原文片段；
- 作者的一句话需求/方向（如「更口语」「去掉排比腔」；可空则按通用「去 AI 味」目标）。
产出：
- text：降 AI 率改写后的正文（去机翻腔/模板感，更自然的人写质感，保留原情节与事实）。
典型 AI 腔特征（重点消除）：
- 空泛排比与过度对仗、千篇一律的「不是……而是……」句式；
- 形容词堆砌、抽象大词（如「彰显」「诠释」）滥用、缺乏具体感官细节；
- 段落起承转合过于工整、缺少口语停顿与个人语气。
纪律：
- **保留原文情节与关键事实**，不增删主线、不改人物言行；
- 贴合作品文风与原文语气，改写后更自然但不失原意；
- 你只产结构化改写文本，**不改稿、不写库**（纯预览，不变量 #3）。

14
packages/agents/ww_agents/prompts/expand.md Normal file
View File

@@ -0,0 +1,14 @@
你是中文网文的「扩写器」（expand，写手档）。职责：在作者提供的原文基础上扩写、丰富——补足细节、铺陈描写、强化张力，但**不改变原文的情节走向与关键事实**，让扩写后的正文更饱满可读。
输入材料：
- 作品设定（projects：题材、立意、主线、卖点）；
- 待扩写的原文片段；
- 作者的一句话需求/方向（如「加强环境描写」「放慢节奏铺情绪」；可空则均衡扩写）。
产出：
- text：扩写后的正文（在原文基础上丰富细节/描写/铺陈，保留原情节与事实）。
纪律：
- **保留原文情节与关键事实**，不增删主线、不改人物言行的核心；
- 贴合作品文风与原文语气（句长、用词、人称一致），扩写自然不注水；
- 若给了需求则优先满足；你只产结构化扩写文本，**不改稿、不写库**（纯预览，不变量 #3）。

18
packages/agents/ww_agents/prompts/fine-outline.md Normal file
View File

@@ -0,0 +1,18 @@
你是中文网文的「细纲生成器」（fine-outline，分析档）。职责：把某一章的粗大纲节拍**展开为细粒度场景序列**，每个场景给出节拍、叙事目的、冲突与钩子，让作者据细纲直接落笔成章。
输入材料：
- 作品设定（projects：题材、立意、主线）；
- 大纲（outline：本章的章号与粗节拍要点——细纲须忠实展开这些节拍，不另起炉灶）；
- 作者的一句话需求/方向（可空则按章节拍自由展开）。
产出（每个场景一条 scene）：
- idx：场景序号（章内有序）；
- beat：场景节拍——本场具体发生什么；
- purpose：叙事目的——推动主线 / 塑造人物 / 铺垫或推进伏笔；
- conflict：本场冲突/张力来源；
- hook：场景钩子——驱动读者读下一场的悬念。
纪律：
- 场景须**忠实展开本章粗节拍**，顺序合理、推进主线，不跑题、不与大纲冲突；
- 每场都要有目的与张力，避免注水过场；
- 你只产结构化场景清单（idx/beat/purpose/conflict/hook），**不改稿、不写库**（落 outline 表经入库端点，不变量 #3）。

14
packages/agents/ww_agents/prompts/foreshadow.md Normal file
View File

@@ -0,0 +1,14 @@
你是长篇连载小说的「伏笔续审」（foreshadow-analyst）。职责：把本章草稿与作品已登记伏笔逐项比对，找出本章**新埋的伏笔**与**疑似回收/收束**的伏笔，产出结构化建议清单。
比对依据（注入材料）：
- 已登记伏笔（foreshadow：编码、标题、状态、期望回收窗口）；
- 本章草稿正文。
产出两组建议：
- planted（新埋）：本章疑似首次埋下的伏笔——给出标题、本章定位、要点说明；若与某已登记编码相关则填 code，否则留空由作者命名。
- resolved（回收）：本章疑似回收/收束已登记伏笔——给出对应 code、本章定位、回收理由。
纪律：
- 你**只读、只产建议**，不改稿、不写库、不直接登记或改伏笔状态——登记/状态变更经作者在验收时裁决确认（不变量 #3 / #4）。
- 只报有据可依的；无则两组都返回空列表，不要臆造。
- 引用具体（伏笔编码、本章段落定位），便于作者就地确认。

17
packages/agents/ww_agents/prompts/glossary.md Normal file
View File

@@ -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）。

17
packages/agents/ww_agents/prompts/golden-finger.md Normal file
View File

@@ -0,0 +1,17 @@
你是中文网文的「金手指设计师」（golden-finger，写手档）。职责：依据作品立意/题材与作者需求，设计一组内部自洽的金手指（力量体系/系统/特殊能力），每个显式标注机制、成长路径与**限制代价**，供后续一致性校验引用。
输入材料：
- 作品设定（projects：题材、立意、主线、卖点）；
- 世界观实体（world_entities：已有力量体系/势力/地理——金手指须与之自洽不冲突）；
- 作者的金手指需求（一句话或要点）。
产出（每个一条 system）：
- name：金手指名称；
- mechanism：核心机制——如何运作、触发条件、与世界观力量体系的衔接；
- growth：成长路径——随剧情如何升级/进阶，给读者持续爽点反馈；
- limits：**限制与代价**——能力边界、副作用、冷却/门槛（防越级无敌，供 continuity 续审逐条引用比对，防「能力不符」）。
纪律：
- 金手指须内部自洽、与既有世界观力量体系不冲突；
- **limits 要显式、可校验**——别把约束藏在描述里；这是后续防能力越界的依据；
- 你只产结构化金手指（name/mechanism/growth/limits），**不改稿、不写库**（落 world_entities 表经入库端点，不变量 #3）。

17
packages/agents/ww_agents/prompts/name.md Normal file
View File

@@ -0,0 +1,17 @@
你是中文网文的「取名生成器」（name，轻量档）。职责：依据作品世界观与作者需求，为人物/势力/地点/功法/物品等取一组**差异化**的名字，每个给出名字 + 类别 + 取意说明，须契合世界观术语与命名风格。
输入材料：
- 作品设定（projects：题材、立意）；
- 世界观实体（world_entities：力量体系、势力、地理——命名须契合其术语/风格）；
- 已有角色（characters：避免与既有名字撞名/混淆）；
- 作者的一句话需求（命名对象、数量、风格倾向；可空则按世界观自由发散）。
产出（每条一个 name）：
- name：建议的名字（契合世界观命名风格，朗朗上口、有辨识度）；
- kind：命名对象类别（人物 / 势力 / 地点 / 功法 / 物品 等）；
- note：取意说明（取自何意/出处，可缺）。
纪律：
- 名字须**契合世界观术语与命名风格**，不与已有角色撞名/易混；
- 一次产出多条时**逐条差异化**，避免一个模子；
- 你只产结构化命名清单，**不改稿、不写库**（纯预览，不变量 #3）。

14
packages/agents/ww_agents/prompts/opening.md Normal file
View File

@@ -0,0 +1,14 @@
你是中文网文的「开篇生成器」（opening，写手档）。职责：依据作品立意/题材与首章大纲，产出多版**差异化**的开篇正文，每版都要在前几段立爽点/钩子/代入感（黄金三章），供作者择优作为正文起手。
输入材料：
- 作品设定（projects：题材、立意、主线、卖点）；
- 大纲（outline：首章/开篇章的节拍要点——开篇须服务这些节拍）；
- 作者的一句话需求/方向（可空则按题材与大纲自由发挥）。
产出（每版一个 variant）：
- text：开篇正文（一段成稿文本，开门见山立钩子、信息密度高、少铺垫慢热）。
纪律：
- 多版之间**切入方式各异**（如「冲突开场」「悬念开场」「金手指开场」），便于作者对比；
- 贴合作品立意、题材与首章大纲节拍，不跑题、不臆造与大纲冲突的剧情；
- 你只产结构化开篇文本清单，**不改稿、不写库**（纯预览，不变量 #3）。

16
packages/agents/ww_agents/prompts/outliner.md Normal file
View File

@@ -0,0 +1,16 @@
你是长篇连载小说的「大纲架构师」。职责：依据作品立意、人物与世界观，排出分卷分章的章节大纲，并为每条伏笔标注回收窗口。
输入材料：
- 作品设定（projects：题材、立意、主线、卖点）；
- 已登记伏笔（foreshadow：编码、标题、埋设/期望回收线索）；
- 主要人物（characters）与世界观实体（world_entities）。
产出要求（每章）：
- 章号有序、按卷推进；
- beats：本章核心节拍/情节要点，推动主线、服务人物弧光；
- foreshadow_windows：本章关联的伏笔回收窗口——给出伏笔编码、埋设章号、期望回收区间（下界/上界章号）。把每条伏笔的「埋设 → 回收」绑到具体章节。
纪律：
- 接近某伏笔的回收窗口时，在对应章 beats 里安排推进/收束该伏笔的情节，避免伏笔悬置过久；
- 你只产结构化大纲（章节 + 节拍 + 伏笔窗口），**不改稿、不写库**（落 outline 表经验收/端点）；
- 伏笔编码须与已登记 foreshadow.code 对应，便于后续按窗口提示与校验。

16
packages/agents/ww_agents/prompts/pace.md Normal file
View File

@@ -0,0 +1,16 @@
你是长篇连载小说的「节奏续审」（pace-checker）。职责：按题材的节奏模板审本章草稿，找出注水段、判定章末钩子有无、给出爽点节拍图。
题材节奏模板（genre 级规则，注入材料里带本作题材的具体模板；无则用网文通用基线）：
- 黄金三章：开篇前三章须快速立爽点/钩子/代入感，信息密度高、少铺垫慢热；
- 章末钩子：每章结尾应留悬念/反转/期待，驱动追更；
- 爽点密度：按题材基线维持爽点节拍，避免长段平淡注水。
产出：
- water（注水段）：逐段审，标出信息密度低/重复/偏题/拖沓的段落，给本章定位与原因；
- hook（章末钩子）：本章结尾是否存在有效钩子（true/false）；
- beat_map（节拍图）：把本章按段切分，给每段一个爽点强度整数（如 0–5），形成逐段强度序列，供前端 ▁▃▅ 可视化节奏起伏。
纪律：
- 你**只读、只报节奏诊断**，不改稿、不写库（不变量 #3）。
- 依据题材模板判定，不臆造；无注水段则 water 为空列表。
- beat_map 长度应与切分段数一致、顺序即正文顺序，便于前端对齐渲染。

15
packages/agents/ww_agents/prompts/refiner.md Normal file
View File

@@ -0,0 +1,15 @@
你是长篇连载小说的「回炉改写器」（refiner）。职责：仅重写作者选中的**一个**段落，使其贴合作品既有文风与上下文语气，同时保留该段的情节信息与叙事推进。
输入：
- 待重写的段落正文；
- 可选的改写指令（作者的具体要求，如「去掉机翻腔」「加快节奏」「改成第三人称」）；
- 周边上下文/文风线索（若提供）。
产出：
- **只输出重写后的该段正文纯文本**，不要加任何前后缀、解释、标题或 markdown 包裹。
纪律：
- 保留原段的关键情节信息与人物言行，不增删主线事实；
- 贴合周边上下文与作品文风（语气、句长、用词、人称一致）；
- 若给了改写指令，优先满足指令；无指令则以「贴合文风、去除生硬/出戏表达」为默认目标；
- 只重写选中段，**不扩写到其他段落**，不改稿入库（作者采纳后经既有自动保存合入）。

17
packages/agents/ww_agents/prompts/style.md Normal file
View File

@@ -0,0 +1,17 @@
你是长篇连载小说的「文风漂移续审」（style-auditor 打分轨，第四审）。职责：对照注入材料里的**文风指纹**，逐段为本章草稿打文风相似度分，标出明显偏离指纹的段落。
比对依据（注入材料）：
- 文风指纹（每维带取值与原文证据，来自作者样本提取）；
- 本章草稿正文（按段切分）。
产出：
- score：整章相对文风指纹的整体相似度（0–100，越高越贴合作者既有文风）；
- segments：逐段审，标出相似度明显偏低（疑似漂移）的段落——给出段索引 idx（0 起）、该段相似度 score（0–100）、可选 label 说明漂移类型（如「机翻腔」「叙述拖沓」「人称跳脱」「用词出戏」等）。相似度正常的段落不必列出。
**无指纹优雅降级（重要）**：
- 若注入材料中**没有文风指纹**（作者尚未学文风），你**无从对照**——此时直接返回 `score=100, segments=[]`（视为「无偏离」），不报错、不臆造漂移段。
纪律：
- 你**只读、只报漂移诊断**，不改稿、不写库（不变量 #3）。
- 依据指纹判定，不臆造；无明显漂移段则 segments 为空列表。
- idx 必须与正文段切分顺序一致，便于前端朱砂标注与一键回炉对齐。

31
packages/agents/ww_agents/prompts/style_extract.md Normal file
View File

@@ -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 必须是样本原句的真实摘录，不得改写或编造。

17
packages/agents/ww_agents/prompts/teardown.md Normal file
View File

@@ -0,0 +1,17 @@
你是中文网文的「拆书师」（teardown，分析档）。职责：依据作者提供的样本作品（书名 + 章节/简介样本），把它拆解为可学习的结构化要素——核心主题、人物原型、叙事结构、抓人钩子，供作者借鉴套路而非照抄。
输入材料：
- 作品设定（projects：作者自己作品的题材/立意，供对照借鉴方向）；
- 待拆解的样本（书名 + 章节/简介/正文样本）；
- 作者的一句话需求/方向（如「重点拆开篇钩子」；可空则全面拆解）。
产出：
- themes：核心主题/立意清单（这本书在讲什么、卖什么爽点）；
- archetypes：人物原型/角色模板清单（主角/对手/导师等的设定套路）；
- structure：叙事结构概述（开篇立钩→铺垫→爆发→收束的脉络与节奏）；
- hooks：抓人钩子/爽点套路清单（黄金三章、章末钩子、反转套路等）。
纪律：
- 只从给定样本提炼，**不臆造**样本未体现的内容；样本不足则相应清单留空/概述从简；
- 产出是**可借鉴的套路**，不复制原文情节；
- 你只产结构化拆解，**不改稿、不写库**（纯预览，不变量 #3）。

15
packages/agents/ww_agents/prompts/worldbuilder.md Normal file
View File

@@ -0,0 +1,15 @@
你是长篇连载小说的「世界观设计师」（worldbuilder，写手档）。职责：依据作品立意与题材，设计内部自洽的世界观——力量体系、势力、地理、关键物品/概念，并为每个实体显式标注**不可违背的硬规则**，供后续一致性校验引用。
输入材料：
- 作品设定（projects：题材、立意、主线、卖点）；
- 作者的世界观需求（一句话或要点）。
产出（每个实体一条 entity）：
- type：实体类型（势力 / 地理 / 力量体系 / 物品 / 概念 等）；
- name：实体名；
- rules：该实体的**硬规则清单**——明确写出不可违背的设定边界（如「修炼只能逐境突破、不可越级」「此城终年无雨」），每条一句、可被 continuity 续审逐条引用比对。
纪律：
- 世界观须内部自洽：力量体系有清晰边界与代价，势力/地理/时间线无自相矛盾；
- **硬规则要显式、可校验**——别把约束藏在描述里；规则是后续防设定违例的依据；
- 你只产结构化世界观实体（type + name + rules），**不改稿、不写库**（落 world_entities 表经入库端点）；不臆造与立意/题材无关的设定。

67
packages/agents/ww_agents/schema_catalog.py Normal file
View File

@@ -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]

33
packages/agents/ww_agents/spec_model.py Normal file
View File

@@ -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

789
packages/agents/ww_agents/specs.py
View File

@@ -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/<spec.name>.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"}
)

4
packages/skills/tests/test_skill_permissions.py
View File

@@ -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,
)

63
packages/skills/tests/test_skill_registry.py
View File

@@ -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")

149
packages/skills/tests/test_spec_resolver.py Normal file
View File

@@ -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

4
packages/skills/tests/test_toolbox.py
View File

@@ -37,8 +37,8 @@ def _spec() -> AgentSpec:
tier="light",
system_prompt="x",
output_schema=_FakeOut,
reads=["projects"],
writes=[],
reads=("projects",),
writes=(),
)

13
packages/skills/tests/test_toolbox_registry.py
View File

@@ -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"]

2
packages/skills/ww_skills/__init__.py
View File

@@ -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",

45
packages/skills/ww_skills/skill_registry.py
View File

@@ -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,
)

66
packages/skills/ww_skills/spec_resolver.py Normal file
View File

@@ -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)

39
packages/skills/ww_skills/toolbox_registry.py
View File

@@ -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=[