pipeline.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322
  1. """Observable design → four roles → deterministic compiler → bounded repair."""
  2. from __future__ import annotations
  3. import json
  4. import re
  5. import time
  6. from html.parser import HTMLParser
  7. from typing import Any, Callable
  8. from .agents import (
  9. AgentConfigurationError, AgentContractError, AgentInvocationError, HelloAgentsRoles, RoleRunner,
  10. TrackedRoles, iter_nodes, make_prompt, validate_analysis, validate_plan,
  11. validate_review,
  12. )
  13. from .compiler import compile_project
  14. from .design import normalize_design
  15. class PipelineError(RuntimeError):
  16. """A failed run keeps its trace; it is never replaced with a demo success."""
  17. def __init__(self, stage: str, message: str, events: list[dict], metrics: dict, error_code: str = "pipeline_error"):
  18. super().__init__(message)
  19. self.stage = stage
  20. self.events = events
  21. self.metrics = metrics
  22. self.error_code = error_code
  23. class _NodeParser(HTMLParser):
  24. def __init__(self) -> None:
  25. super().__init__(convert_charrefs=True)
  26. self.node_ids: list[str] = []
  27. self.node_tags: dict[str, str] = {}
  28. def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
  29. for name, value in attrs:
  30. if name == "data-node-id" and value is not None:
  31. self.node_ids.append(value)
  32. self.node_tags[value] = tag
  33. def review_project(design: dict, files: dict[str, str], plan: dict) -> dict:
  34. """Static structure/semantics checks, explicitly not a visual fidelity score."""
  35. nodes = list(iter_nodes(design["root"]))
  36. ids = {node["id"] for node in nodes}
  37. parser = _NodeParser()
  38. parser.feed(files.get("preview.html", ""))
  39. rendered = set(parser.node_ids)
  40. missing = sorted(ids - rendered)
  41. unexpected = sorted(rendered - ids)
  42. duplicate_ids = sorted({node_id for node_id in rendered if parser.node_ids.count(node_id) > 1})
  43. required = {"src/App.tsx", "src/styles.css", "preview.html", "manifest.json"}
  44. absent = sorted(path for path in required if not isinstance(files.get(path), str) or not files[path].strip())
  45. issues: list[dict] = []
  46. checks = []
  47. def check(name: str, passed: bool, detail: str) -> None:
  48. checks.append({"name": name, "passed": passed, "detail": detail})
  49. check("required_files", not absent, "必备文件齐全" if not absent else "缺少文件:" + ", ".join(absent))
  50. check("node_coverage", not missing and not unexpected and not duplicate_ids,
  51. f"设计节点 {len(ids)};预览匹配 {len(ids & rendered)};缺失 {len(missing)};额外 {len(unexpected)};重复 {len(duplicate_ids)}")
  52. try:
  53. manifest = json.loads(files.get("manifest.json", ""))
  54. manifest_valid = isinstance(manifest, dict)
  55. except (ValueError, TypeError):
  56. manifest_valid = False
  57. check("manifest_json", manifest_valid, "manifest 是有效 JSON 对象" if manifest_valid else "manifest 不是有效 JSON 对象")
  58. for node_id in missing:
  59. issues.append({"node_id": node_id, "severity": "error", "message": "预览缺失导入节点", "source": "static"})
  60. for node_id in duplicate_ids:
  61. issues.append({"node_id": node_id, "severity": "error", "message": "预览重复输出节点", "source": "static"})
  62. # Inspect emitted tags: the compiler may safely turn a button's children into
  63. # spans. A check against the proposed plan would misreport the actual DOM.
  64. tags = parser.node_tags
  65. semantic_issues = []
  66. for tag in ("main", "h1"):
  67. matching = [node_id for node_id, assigned in tags.items() if assigned == tag]
  68. if len(matching) > 1:
  69. semantic_issues.append({"node_id": matching[1], "severity": "error", "message": f"单页存在多个 {tag} 标签", "source": "static"})
  70. for node in nodes:
  71. if tags.get(node["id"]) == "button":
  72. descendants = list(iter_nodes(node))
  73. text = " ".join(str(item.get("text", "")) for item in descendants).strip()
  74. if not text:
  75. semantic_issues.append({"node_id": node["id"], "severity": "error", "message": "按钮缺少可访问文本名称", "source": "static"})
  76. if any(tags.get(child["id"]) == "button" for child in descendants[1:]):
  77. semantic_issues.append({"node_id": node["id"], "severity": "error", "message": "按钮不能嵌套按钮", "source": "static"})
  78. issues.extend(semantic_issues)
  79. check("basic_accessibility", not semantic_issues,
  80. "通过基础语义检查;不代表完整 WCAG 合规" if not semantic_issues else "发现按钮或标题语义问题")
  81. passed = all(item["passed"] for item in checks)
  82. return {
  83. "status": "passed" if passed else "failed",
  84. "passed": passed,
  85. "checks": checks,
  86. "issues": issues,
  87. "node_coverage_percent": round(100 * len(ids & rendered) / len(ids), 2) if ids else 0,
  88. "node_count": len(ids),
  89. "rendered_node_count": len(ids & rendered),
  90. "scope": "仅静态结构与基础语义校验;未执行生成代码,未进行截图比较,不是像素还原率。",
  91. }
  92. def _demo_analysis(design: dict) -> dict:
  93. nodes = list(iter_nodes(design["root"]))
  94. text_count = sum(node.get("type") == "TEXT" for node in nodes)
  95. return {
  96. "summary": f"离线规则分析:{design.get('name', '设计')},共 {len(nodes)} 个可编译节点。",
  97. "observations": [
  98. f"保留 {text_count} 个文本节点和 {len(nodes) - text_count} 个容器或图形节点。",
  99. "编译器根据设计模型生成 React、CSS 与独立 HTML 预览;组件计划只选择语义标签。",
  100. ],
  101. "warnings": ["demo 使用确定性规则,没有调用任何大模型。", *design.get("warnings", [])[:10]],
  102. }
  103. def _demo_plan(design: dict) -> dict:
  104. nodes = list(iter_nodes(design["root"]))
  105. components = []
  106. heading_assigned = False
  107. button_descendants: set[str] = set()
  108. for index, node in enumerate(nodes):
  109. if len(components) >= 40:
  110. break
  111. # Preorder traversal sees a button before its children. Let the compiler
  112. # render its entire subtree as safe inline content; no heading or landmark
  113. # heuristic should override that inherited content model.
  114. if node["id"] in button_descendants:
  115. continue
  116. node_type = node.get("type")
  117. name = str(node.get("name", "")).lower()
  118. tag = None
  119. if index == 0 and node_type != "TEXT":
  120. tag = "main"
  121. elif node_type == "TEXT":
  122. size = node.get("style", {}).get("fontSize", 0)
  123. try:
  124. is_title = float(str(size).removesuffix("px")) >= 28
  125. except ValueError:
  126. is_title = False
  127. if not heading_assigned and (is_title or re.search(r"(^|[ _-])(title|headline)([ _-]|$)|标题", name)):
  128. tag, heading_assigned = "h1", True
  129. elif "button" in name or "按钮" in name or name == "cta":
  130. # Button placeholders remain disabled; no invented business actions.
  131. descendants = list(iter_nodes(node))
  132. if any(item.get("text", "").strip() for item in descendants):
  133. tag = "button"
  134. button_descendants.update(item["id"] for item in descendants[1:])
  135. elif "header" in name or "导航栏" in name:
  136. tag = "header"
  137. elif "footer" in name or "页脚" in name:
  138. tag = "footer"
  139. elif name in ("nav", "navigation", "导航"):
  140. tag = "nav"
  141. if tag:
  142. components.append({"node_id": node["id"], "name": f"Node{index + 1}", "tag": tag})
  143. return {
  144. "components": components,
  145. "notes": ["离线演示只做有限的名称与字号规则推断;未识别业务逻辑。", "未列入计划的节点仍由编译器完整保留。"],
  146. }
  147. def run_pipeline(
  148. payload: dict, *, node_id: str | None = None, mode: str = "demo", brief: str = "",
  149. on_event: Callable[[dict], None] | None = None,
  150. role_runner: RoleRunner | None = None,
  151. ) -> dict:
  152. """Run synchronously; ``role_runner`` is an internal offline test seam.
  153. Live mode requires real credentials unless a caller explicitly injects a test
  154. runner. The web API never accepts a runner from request data. No mode fallback
  155. is performed on configuration, network, schema, compiler or review failures.
  156. """
  157. if mode not in ("demo", "live"):
  158. raise ValueError("mode 只能是 demo 或 live")
  159. if not isinstance(brief, str) or len(brief) > 4_000:
  160. raise ValueError("brief 必须是最多 4000 字符的字符串")
  161. started = time.perf_counter()
  162. events: list[dict] = []
  163. tracked: TrackedRoles | None = None
  164. design: dict = {}
  165. files: dict = {}
  166. review: dict = {}
  167. def metrics() -> dict:
  168. calls = tracked.calls if tracked else []
  169. return {
  170. "duration_ms": round((time.perf_counter() - started) * 1000, 2),
  171. "llm_calls": len(calls),
  172. "llm_latency_ms": round(sum(call.get("duration_ms", 0) for call in calls), 2),
  173. "input_chars": sum(call.get("input_chars", 0) for call in calls),
  174. "output_chars": sum(call.get("output_chars", 0) for call in calls),
  175. "input_chars_note": "输入字符数统计摘要 JSON,不含角色系统提示词。",
  176. "context_omitted_nodes": max((call.get("omitted_nodes", 0) for call in calls), default=0),
  177. "truncated_context_calls": sum(bool(call.get("context_truncated")) or bool(call.get("omitted_nodes")) for call in calls),
  178. "token_usage": None if calls else {"input": 0, "output": 0},
  179. "estimated_cost_usd": None if calls else 0,
  180. "cost_note": "HelloAgents 0.2.2 不暴露 usage;未估算 token 或费用,请以供应商账单为准。" if calls else "离线运行,无 LLM 请求与 LLM 费用。",
  181. "files_count": len(files),
  182. "node_count": design.get("stats", {}).get("node_count", 0),
  183. "node_coverage_percent": review.get("node_coverage_percent", 0),
  184. "coverage_note": "节点覆盖率仅表示导入节点出现在预览 DOM 中,不是视觉还原率。",
  185. "calls": [dict(call) for call in calls],
  186. "runner": "injected_test_runner" if role_runner is not None and mode == "live" else ("hello_agents.SimpleAgent" if mode == "live" else "deterministic_demo"),
  187. }
  188. def emit(stage: str, status: str, message: str, duration_ms: float | None = None, error_code: str | None = None) -> None:
  189. event = {"stage": stage, "status": status, "message": message}
  190. if duration_ms is not None:
  191. event["duration_ms"] = duration_ms
  192. if error_code is not None:
  193. event["error_code"] = error_code
  194. events.append(event)
  195. if on_event:
  196. on_event(dict(event))
  197. def execute(stage: str, message: str, action: Callable[[], Any]) -> Any:
  198. step_started = time.perf_counter()
  199. emit(stage, "running", message)
  200. try:
  201. value = action()
  202. except Exception as exc:
  203. # Provider errors can contain URLs/request details: do not expose them.
  204. if isinstance(exc, (AgentConfigurationError, AgentContractError, AgentInvocationError, ValueError)):
  205. detail = str(exc)[:600]
  206. else:
  207. detail = f"{type(exc).__name__}:执行失败,请检查服务配置与连接;详细原因见服务端日志。"
  208. if isinstance(exc, AgentInvocationError):
  209. error_code = exc.error_code
  210. elif isinstance(exc, AgentConfigurationError):
  211. error_code = "configuration"
  212. elif isinstance(exc, AgentContractError):
  213. error_code = "model_invalid_output"
  214. elif stage == "import":
  215. error_code = "invalid_input"
  216. elif stage in ("generate", "repair"):
  217. error_code = "compilation_failed"
  218. else:
  219. error_code = "pipeline_error"
  220. elapsed = round((time.perf_counter() - step_started) * 1000, 2)
  221. emit(stage, "failed", detail, elapsed, error_code)
  222. raise PipelineError(stage, detail, list(events), metrics(), error_code) from exc
  223. emit(stage, "completed", message + " · 完成", round((time.perf_counter() - step_started) * 1000, 2))
  224. return value
  225. design = execute("import", "导入并规范化选中设计节点", lambda: normalize_design(payload, node_id=node_id))
  226. node_ids = {node["id"] for node in iter_nodes(design["root"])}
  227. node_types = {node["id"]: node.get("type", "") for node in iter_nodes(design["root"])}
  228. def analyze() -> dict:
  229. nonlocal tracked
  230. if mode == "demo":
  231. return _demo_analysis(design)
  232. tracked = TrackedRoles(role_runner if role_runner is not None else HelloAgentsRoles())
  233. return validate_analysis(tracked.run("DesignAnalyst", make_prompt(design, brief)))
  234. analysis = execute("analyze", "离线规则分析" if mode == "demo" else "DesignAnalyst 分析设计", analyze)
  235. def plan_components() -> dict:
  236. if mode == "demo":
  237. return validate_plan(_demo_plan(design), node_ids, node_types)
  238. assert tracked is not None
  239. return validate_plan(tracked.run("ComponentPlanner", make_prompt(design, brief, analysis=analysis)), node_ids, node_types)
  240. candidate = execute("plan", "规划已有节点的语义组件", plan_components)
  241. def generate() -> tuple[dict, dict]:
  242. if mode == "demo":
  243. final_plan = candidate
  244. else:
  245. assert tracked is not None
  246. final_plan = validate_plan(tracked.run("CodeEngineer", make_prompt(design, brief, candidate=candidate)), node_ids, node_types)
  247. return final_plan, compile_project(design, final_plan)
  248. plan, files = execute("generate", "生成受约束的 React 与 CSS 项目", generate)
  249. def review_output() -> tuple[dict, dict | None]:
  250. static = review_project(design, files, plan)
  251. if mode == "demo":
  252. return static, None
  253. assert tracked is not None
  254. model_review = validate_review(tracked.run("Reviewer", make_prompt(
  255. design, brief, plan=plan,
  256. static_review={"status": static["status"], "checks": static["checks"], "issues": static["issues"][:10]},
  257. )), node_ids, node_types)
  258. return static, model_review
  259. review, model_review = execute("review", "校验节点覆盖与基础可访问性", review_output)
  260. repair_applied = False
  261. if model_review and model_review["plan"] is not None and model_review["plan"] != plan:
  262. replacement = model_review["plan"]
  263. def repair() -> tuple[dict, dict]:
  264. revised_files = compile_project(design, replacement)
  265. return revised_files, review_project(design, revised_files, replacement)
  266. files, review = execute("repair", "按 Reviewer 计划执行唯一一次修复并重新静态校验", repair)
  267. plan = replacement
  268. repair_applied = True
  269. review["repair_applied"] = repair_applied
  270. review["repair_count"] = int(repair_applied)
  271. review["model_review"] = model_review
  272. if tracked and any(call.get("omitted_nodes") or call.get("context_truncated") for call in tracked.calls):
  273. omitted = max(call.get("omitted_nodes", 0) for call in tracked.calls)
  274. analysis["warnings"].append(
  275. f"为限制模型上下文,部分角色只收到设计摘要(单次最多省略 {omitted} 个节点),或收到截短的上游结果;全部导入节点仍由确定性编译器保留。详情见 metrics.calls。"
  276. )
  277. if model_review and model_review["issues"]:
  278. # Preserve original reviewer feedback. A repaired plan has only been
  279. # statically rechecked; it must not be portrayed as a second LLM review.
  280. review["issues"].extend({**issue, "source": "model_before_repair" if repair_applied else "model"} for issue in model_review["issues"])
  281. if review["status"] == "passed":
  282. review["status"] = "passed_with_advisories"
  283. review["model_review_note"] = "模型建议供人工复核;修复后仅重新进行了静态检查,没有再次调用 Reviewer。" if repair_applied else "模型建议供人工复核,不是视觉检测结论。"
  284. return {
  285. "design": design, "analysis": analysis, "plan": plan, "files": files,
  286. "review": review, "events": events, "mode": mode, "metrics": metrics(),
  287. }