5.6 KiB
5.6 KiB
设计契约 · 续补三件(拆书入库 / 续写式链 / 模板库)
分支
feat/backlog-followups· 实施前唯一契约源。Agent 先读本文 + CLAUDE.md 不变量。范围 = 用户选定「全部可建的续补」(排除多租户/市场/push/browse/K1)。
Context
Scope B 已合并(链 UI + 4 生成器)。本批补三个贴现有框架的续补功能:把竞品对标的剩余可建项做完。守不变量 #1/#2/#3/#9;preview→ingest 经验收闸;单用户原型(owner_id stub)。
F1 · 拆书落库成 rules(teardown → rules ingest)
现状:teardown 生成器是 preview-only。目标:可把拆书结论入库为项目 rules,供写章注入。
- @llm(packages/agents):
teardown_spec.writes=["rules"](其余不动;只声明 tier #2)。 - @backend(packages/skills + apps/api):
skill_permissions.KNOWN_TABLES加"rules"(确认未在则加)。toolbox_registryteardown entry 加ingest=IngestSpec(table="rules")。routers/toolbox.py:在通用 ingest dispatcher(现_ingest_world_entities/_ingest_outline,:344-365 的 "其余表未实现" 分支)加_ingest_ruleshandler——把BookTeardownResult(themes/archetypes/structure/hooks) 转成rules行(scope=project 级,复用既有rulesrepo/表;规则文本由结构化字段拼成可读条目)。partition_writes白名单已据 spec.writes 放行;rules 无需 continuity 预检(meta 规则非设定卡)→ ingest 直接落库(仿_ingest_outline无 409 路径)。
- @frontend(apps/web):teardown 现 output_kind 已可预览;因 registry 加了 ingest,
GeneratorRunner的入库分支应自动出现「入库为规则」按钮(复用既有 ingest UI)。确认渲染 +pnpm gen:api。 - @qa:ingest E2E(teardown generate→ingest→
rules真落行;负向:预览仍不写库)。 - DoD:后端门禁绿;teardown 可入 rules;不变量 #3(入库经白名单)守住。
F2 · 续写式链(continue_volume chain)
现状:链只有 draft_volume(从 start 章按记忆写)。目标:新增 continue_volume——每章写作以上一章 accepted 正文末尾作前文引子(复用 build_continuation_context),比纯 digest 续写更顺。
- @llm(packages/core/orchestrator/chain):
write_chapter节点支持「续写模式」——据 state 的chain_key,continue_volume时调build_continuation_context(prior_text=上一章 accepted 正文)(经注入的 reader,仿现有 accept_op 注入;core 不 import apps/api);draft_volume保持原行为。ChainState 加chain_key(已有则复用)。 - @backend(apps/api):
SUPPORTED_CHAINS(chain.py:63)加"continue_volume";run 端点据 chain_key 选模式;chain_runner 注入「读上一章 accepted 正文」的 reader 给图。 - @frontend(apps/web):
ChainStarter加链类型选择(draft_volume=从头写 / continue_volume=续写),传 chain_key。 - @qa:E2E(continue_volume 两章:第二章请求上下文含第一章正文末尾;其余同链 E2E 范式,mock 网关零 token)。
- DoD:两种链都可跑;续写模式前文注入经 E2E 断言;守不变量 #1/#5。
F3 · 提示词/模板库(单用户本地版)
现状:无。目标:作者保存/复用提示词模板,可一键填入生成器的 brief/text。不做分享/市场(需多租户)。
- @db(packages/db):新表
prompt_templates(UuidPk+CreatedAt+Basemixin;列:owner_id(stub)、title:str、body:str、category:str|None、tool_key:str|None(可选关联生成器))+ alembic 迁移。alembic check无漂移。 - @backend(packages/core/domain + apps/api):
TemplateRepo/SqlTemplateRepo(list/create/delete,owner stub 过滤)+routers/templates.py(GET/POST/DELETE /templates,POST 校验 title/body 非空→422)+schemas/templates.py+ main 注册。 - @frontend(apps/web):
pnpm gen:api;模板库页app/templates/page.tsx(列表/新建/删除)+ nav 入口;生成器 Runner 可选「从模板填入」(把模板 body 填进 brief/text 输入)。 - @qa:E2E(创建→列出→删除 真 pg;title 空→422)。
- DoD:模板 CRUD 可用 + 可填入生成器;后端+前端门禁绿。
Workflow 结构(顺序建造避免共享树写冲突 → 交叉评审 → 全门禁)
- Phase F1(1-2 agent)→ Phase F2(@llm+@backend 顺序 + @frontend)→ Phase F3(@db→@backend→@frontend,+@qa)→ 各 feature E2E。
- 交叉评审(并行只读):python / fastapi / typescript / 不变量。
- 全门禁(并行独立复跑):后端 ruff/format/mypy/alembic check/pytest · 前端 lint/tsc/vitest/build。
- 我汇总 review;CRITICAL/HIGH → 派 fix agent 复绿再合并。
验证
- 后端:
uv run ruff check . && uv run mypy packages apps && uv run alembic check && uv run pytest -q(pg 在跑)。 - 前端:
cd apps/web && pnpm gen:api && pnpm lint && pnpm typecheck && pnpm test && pnpm build。 - 实景(app 在 localhost:3000/8000,需 provider key):teardown 可入 rules;链可选 continue_volume;模板库可建/填入。
风险/取舍
- F1 rules 入库:rules 表结构若与拆书结构化字段不匹配,则拍平为可读规则文本(一条 teardown=一/多条 rule),E2E 断真落行即可。
- F2 续写 reader 跨层:端点读 chapter accepted 正文→注入图节点(仿 accept_op,core 不 import apps/api)。
- F3 模板填入生成器:前端把模板 body 写进现有 brief/text 输入即可,不改生成器后端。
- owner_id 全程 stub(单用户原型);分享/市场不做。