Template.php 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117
  1. <?php
  2. namespace App\Services\Markup\Templates;
  3. use App\Services\Markup\Dialect;
  4. use App\Services\Markup\Format;
  5. use App\Services\Markup\Ir\Call;
  6. use App\Services\Markup\Ir\Document;
  7. use App\Services\Markup\Ir\Params;
  8. use App\Services\Markup\Render\RenderContext;
  9. use App\Services\Markup\Resolve\Resolver;
  10. /**
  11. * 模板基类。一个模板一个子类,在 {@see TemplateRegistry} 登记名字。
  12. *
  13. * 生命周期:
  14. * 1. 解析:{@see Params()} 声明参数(位置、默认值、是否 markdown);markdown 参数递归解析成 slot
  15. * 2. 取数:{@see collect()} 把要查的键交给 Resolver,同类模板一次批量查完(不再逐个查库)
  16. * 3. 输出:tree 用 {@see component()} + {@see props()} + {@see children()};html / 纯文本 / markdown
  17. * 各有一个方法,默认都退回 {@see text()},只有真的不同才覆盖
  18. *
  19. * 模板实例无状态(单例),每次调用的数据都在 {@see Call} 上。
  20. */
  21. abstract class Template
  22. {
  23. /** tree 输出的组件名(前端按它分发) */
  24. protected string $component = 'unknown';
  25. /**
  26. * @return array<string, ParamSpec>
  27. */
  28. public function params(): array
  29. {
  30. return [];
  31. }
  32. /**
  33. * 参数片段 → 参数表。
  34. *
  35. * `name=value` 当命名参数的条件:名字全是小写字母(v2 口径);E2 方言下还要求名字是 {@see Params()}
  36. * 声明过的,否则整段按位置参数处理——LLM 写的 `x=y` 不会被误认成参数。
  37. *
  38. * @param list<string> $segments
  39. */
  40. public function parseParams(array $segments, Dialect $dialect): Params
  41. {
  42. $declared = $this->params();
  43. $named = [];
  44. $positional = [];
  45. foreach ($segments as $offset => $segment) {
  46. if (preg_match('/^([a-z]+)=(.*)$/s', $segment, $m) === 1
  47. && ($dialect === Dialect::Markdown || $this->acceptsAnyName() || isset($declared[$m[1]]))) {
  48. $named[$m[1]] = $m[2];
  49. } else {
  50. $positional[$offset + 1] = $segment;
  51. }
  52. }
  53. return new Params($named, $positional);
  54. }
  55. /**
  56. * 是否接受任意名字的命名参数(Tpl 模板把参数原样交给 Mustache)。
  57. */
  58. protected function acceptsAnyName(): bool
  59. {
  60. return false;
  61. }
  62. public function collect(Call $call, Resolver $resolver): void {}
  63. public function component(Call $call, RenderContext $ctx): string
  64. {
  65. return $this->component;
  66. }
  67. /**
  68. * tree 输出的 props。值可以是 {@see Document},由渲染器按当前格式展开。
  69. *
  70. * @return array<string, mixed>
  71. */
  72. public function props(Call $call, RenderContext $ctx): array
  73. {
  74. return [];
  75. }
  76. /**
  77. * tree 输出的 children。
  78. */
  79. public function children(Call $call, RenderContext $ctx): ?Document
  80. {
  81. return null;
  82. }
  83. /**
  84. * 纯文本表示:text / simple / prompt / markdown / html 的默认输出都从它来。
  85. */
  86. public function text(Call $call, RenderContext $ctx): string
  87. {
  88. return '';
  89. }
  90. public function plain(Call $call, RenderContext $ctx, Format $format): string
  91. {
  92. return $this->text($call, $ctx);
  93. }
  94. public function html(Call $call, RenderContext $ctx): string
  95. {
  96. return e($this->text($call, $ctx));
  97. }
  98. public function markdown(Call $call, RenderContext $ctx): string
  99. {
  100. return $this->text($call, $ctx);
  101. }
  102. }