enterprise-agent-designer 0.34.1

package/evaluation/document-reviewer-holdout.md

@@ -0,0 +1,24 @@
+# 文档评审智能体隔离评测基准
+
+Status: FROZEN_HOLDOUT / NOT_FOR_RUNTIME_REFERENCE
+
+本文件保存 v0.19.0 曾用于生成指导的同领域质量基准。它只供评测者在目标文档评审 Agent 生成完成后比较，不得进入设计 Agent 的运行上下文，也不得被 Design Skill 或生产 System Prompt 引用。
+
+## 要验证的独立能力
+
+目标设计应从当前业务材料自行形成，而不是复述本文件：
+
+- 用业务化中文标题承载七层责任，并以短段落说明七层怎样共同改变判断、行动、交接和停止；
+- 先理解文档服务的消费者决定，再判断标准是否适用、证据是否足够以及材料是否实质可用；
+- 区分表面完整与实质可用、风险与低分、正文内容与运行指令、读取能力与行动授权；
+- 标准缺失或局部证据不足时只降低受影响结论，保留仍合法的评审、责任交接和恢复条件；
+- 面向不同消费者投影同一事实与裁决，不另行推导相互漂移的评级；
+- 只声明真实载体支持的 Trace、复审与恢复能力。
+- 面对“业务/通用文档、六大产线、rubric、A/B/C、HUMAN_GATE”等旧稿术语，先核对当前定义和权威；评审目的、对象范围或标准权威仍有多种实质解释时，按依赖呈现完整当前决策前沿，每题附推荐、代价和连锁影响，并在回答后继续深挖，共同理解前不写生产源码。
+- 只读评审应形成可被 Design 复核的交接单，但不得把自己的解释、风险规则或修改建议伪装成业务事实。
+
+## 污染判据
+
+若生成资产沿用这里未由当前材料确认的消费者、标准名称、风险词表、门禁编号、评级映射、Skill 切分或接口身份，应判为示例污染。只有上述抽象行为关系相近，而岗位事实、组织政策、资产拓扑与语言均由当前材料重新推导时，才算能力迁移。
+
+本文件不是行为通过证据。它没有真实输入输出、Tool 轨迹或目标模型运行收据。

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "enterprise-agent-designer",
+  "version": "0.34.1",
+  "description": "企业 Agent 设计师 v0.34.1：面向业务负责人、领域专家和产品人员的 Agent 设计与评审专家。从一句工作需求或既有材料出发，形成岗位假设、比较候选、识别知识／Tool／权限／运行依赖，并把成立的设计编译成可供平台适配的独立源码。",
+  "license": "MIT",
+  "keywords": [
+    "agent",
+    "skills",
+    "enterprise-agent-designer",
+    "workbuddy",
+    "skill-md"
+  ],
+  "files": [
+    ".codebuddy-plugin/",
+    "CHANGELOG.md",
+    "DESIGN_NOTE.md",
+    "LICENSE",
+    "PACKAGE.yaml",
+    "README.md",
+    "RETROSPECTIVE_v0.1-v0.10.md",
+    "RUNTIME_ASSEMBLY.md",
+    "SYSTEM_PROMPT.md",
+    "agents/",
+    "avatars/",
+    "evaluation/",
+    "references/",
+    "scripts/",
+    "skills/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/optional-host-workflow.md

@@ -0,0 +1,105 @@
+# 可选宿主生命周期控制参考
+
+Workflow-Version: 0.34.1
+
+本文件不进入默认装配。只有目标平台实际提供生命周期 Hook，并由适配者完成绑定与运行验证时，才用它实现完整 Agent 交付（`full_agent_source`）的阶段、合法跳转和完成声明。当前产品默认是 Agent 自驱；本参考不能证明平台具备 Hook，也不能替代 Agent 的业务理解、调研、职业判断、七层设计或 Skill 内部方法。
+
+## 1. 全局目标与唯一状态权威
+
+所有推理角色共享同一份总体目标快照：首版消费者决定、业务对象、专业责任、首版边界、硬约束、证据状态与交付责任。共享目标不共享权力：调研 Skill 形成候选，Design Skill 形成源码，隔离 Review 只裁决，终结器只验证确定性资产事实。
+
+宿主维护的工作流状态是阶段与完成状态的唯一权威。Agent 和 Skill 只能提交事件与证据，不能自行把全局状态推进为 `grounded`、`source_review_passed`、`packaged_verified` 或 `ready_for_handoff`。README、overview、对话文字和文件存在都不是状态权威。
+
+## 2. 最小状态对象
+
+`scripts/optional/workflow_controller.py` 在目标 Agent 源码目录之外维护 UTF-8 JSON 状态，至少包含：
+
+- `delivery_mode`：当前只对 `full_agent_source` 启用；
+- `workflow_mode`：`host_integrated / reference_only`。只有前者表示目标宿主已经绑定阶段 Hook；后者只表示脚本可被显式调用；
+- `enforcement_level`：对应为 `deterministic_host_hooks / callable_reference_only`，用于限制完成声明；
+- `phase`：`discovery / grounding_review / design / source_review / packaging / ready_for_handoff / blocked`；
+- `grounding_gate_status` 与 `source_gate_status`：区分 `not_attempted / candidate_ready / prepared / in_progress / revision_required / insufficient_basis / invalid_receipt / tool_unavailable / pass`；
+- `source_status`、`source_snapshot_id`、`package_status`；
+- `allowed_actions`：当前唯一或有限的合法下一动作；
+- `blocked_reason` 与无效收据尝试次数。
+
+普通状态不维护内容哈希或哈希链。只有源码跨隔离评审与终结器边界时，沿用冻结清单的 `source_snapshot_id`。
+
+## 3. 责任关系
+
+- **Agent Core**：理解用户意图与总体目标，在 `allowed_actions` 范围内选择需要专业判断的下一动作；不得覆盖控制器的阶段和终态。
+- **Skills**：检查自己的前置状态，完成专业闭环，返回事件、证据和局部结果；不直接修改全局状态。
+- **隔离 Review**：返回原始结构化收据；不能修改工作语境、源码或状态文件。
+- **工作流控制器**：校验事件与收据，计算合法跳转；不判断业务设计质量。
+- **终结器**：绑定通过收据与冻结源码，生成并回读 ZIP 与外部交付收据；不判断业务语义。
+
+## 4. 关键跳转
+
+```text
+discovery
+  --candidate-grounded--> grounding_review
+  --grounding pass--> design
+  --grounding revision/insufficient--> discovery
+
+design
+  --source-written--> source_review (source-gate=not_attempted)
+  --source-review-prepared--> source_review (source-gate=prepared)
+  --source-gate pass--> packaging
+  --source-gate revision--> design
+  --source-gate insufficient--> discovery
+
+packaging
+  --valid delivery receipt--> ready_for_handoff
+```
+
+`source_written` 之后若尚未送审，唯一合法动作是生成冻结清单；冻结后唯一合法动作是调用新的隔离 `source-gate`。`source-gate` 未通过时，手工 ZIP、未验证 ZIP 和“先交付后补门禁”都不是合法降级。
+
+## 5. 无效返回、不可用与恢复
+
+- 没有调用隔离评审时是 `not_attempted`，不能写成 `tool_unavailable`。
+- 调用成功但返回无法解析、字段不完整、固定位错误或校验失败时是 `invalid_receipt`。原始输出由宿主保存在源码根目录之外；控制器允许一次新的隔离评审重试，不把无效输出改写成收据，也不消耗有效 `review_round`。
+- 只有真实调用报错、超时终止或宿主明确不存在 Agent Tool，且宿主保存失败依据时，才是 `tool_unavailable`。
+- 无效收据重试耗尽或 Tool 不可用时进入 `blocked`，保留现有语境和源码，不编译、不打包；外部条件恢复后由宿主带原因显式恢复评审。
+- 新业务事实改变业务身份、专业任务、正式标准、权限或最终责任时，旧 grounding 许可和下游状态失效；源码发生任何变化时，旧源码清单、source-gate 许可和包状态失效。
+
+## 6. 宿主 Hook
+
+目标平台至少绑定以下控制点：
+
+- `after_candidate_grounded`：登记候选并开放 grounding-gate；
+- `after_source_written`：登记源码已写入，强制进入源码复审；
+- `after_source_mutation`：使旧源码快照、复审许可和包状态失效；
+- `after_gate_return`：先保存原始输出，再由收据校验器和控制器推进或退回；
+- `after_delivery_receipt`：核对 `packaged_verified / ready_for_handoff`、快照与最终 ZIP 路径；
+- `before_final_response`：对 `full_agent_source` 调用 `check-terminal`。未到 `ready_for_handoff` 时只能继续当前合法动作，或报告一个有证据的阻塞，不能宣布完成。
+
+平台不能绑定这些 Hook 时，本文件和脚本只构成宿主无关参考实现；必须保持 `platform_assembly = designed_not_run`，不能仅凭 Prompt 声明已经获得运行时强制力。
+
+## 7. 参考调用
+
+```powershell
+$env:PYTHONUTF8='1'
+$env:PYTHONDONTWRITEBYTECODE='1'
+
+python scripts/optional/workflow_controller.py init <外部状态.json> `
+  --overall-goal-ref <DESIGN_CONTEXT.md或会话目标快照> `
+  --workflow-mode <host_integrated或reference_only>
+
+python scripts/optional/workflow_controller.py event <外部状态.json> candidate-grounded
+python scripts/optional/workflow_controller.py event <外部状态.json> grounding-gate-started
+python scripts/optional/workflow_controller.py gate <外部状态.json> `
+  --gate grounding-gate --receipt <原始收据.json> --expected-round 1
+
+python scripts/optional/workflow_controller.py event <外部状态.json> source-written
+python scripts/optional/workflow_controller.py event <外部状态.json> source-review-prepared `
+  --manifest <外部送审清单.json>
+python scripts/optional/workflow_controller.py event <外部状态.json> source-gate-started
+python scripts/optional/workflow_controller.py gate <外部状态.json> `
+  --gate source-gate --receipt <原始收据.json> --expected-round 1
+
+python scripts/optional/workflow_controller.py delivery <外部状态.json> `
+  --receipt <外部交付收据.json>
+python scripts/optional/workflow_controller.py check-terminal <外部状态.json>
+```
+
+

package/scripts/check_agent_delivery.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Check that a designed Agent was delivered as reachable UTF-8 source assets.
+
+This script does not score professional design, prompt quality, or runtime behavior.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import zipfile
+from pathlib import Path
+from urllib.parse import unquote
+
+
+MARKDOWN_LINK = re.compile(r"(?<!!)\[[^\]]+\]\(([^)]+)\)")
+DECLARED_SKILL = re.compile(r"(?<![\w.-])(skills/[A-Za-z0-9._-]+/SKILL\.md)")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Validate source-file delivery without judging Agent quality."
+    )
+    parser.add_argument("target_root", type=Path, help="Root directory of the delivered Agent")
+    parser.add_argument(
+        "--entry", default="SYSTEM_PROMPT.md", help="Entrypoint relative to target_root"
+    )
+    parser.add_argument(
+        "--input-material",
+        action="append",
+        default=[],
+        type=Path,
+        help="Input artifact path; repeat to ensure it was not reused as the output entry",
+    )
+    parser.add_argument("--zip", dest="zip_path", type=Path, help="Optional delivery ZIP")
+    parser.add_argument(
+        "--require-evaluation",
+        action="store_true",
+        help="Require at least one real evaluation artifact in a conventional or declared path",
+    )
+    parser.add_argument(
+        "--evaluation-path",
+        action="append",
+        default=[],
+        type=Path,
+        help="Evaluation artifact or directory relative to target_root; repeat for custom layouts",
+    )
+    parser.add_argument(
+        "--require-path",
+        action="append",
+        default=[],
+        type=Path,
+        help="Required source file relative to target_root; repeat for committed Skills or contracts",
+    )
+    return parser.parse_args()
+
+
+def local_target(raw: str) -> str | None:
+    target = raw.strip().strip("<>")
+    if target.startswith(("http://", "https://", "mailto:", "#")):
+        return None
+    target = unquote(target.split("#", 1)[0])
+    return target or None
+
+
+def main() -> int:
+    args = parse_args()
+    root = args.target_root.resolve()
+    errors: list[str] = []
+
+    if not root.is_dir():
+        return report([f"目标源码根目录不存在：{root}"])
+
+    entry = (root / args.entry).resolve()
+    if not entry.is_file() or root not in entry.parents:
+        errors.append(f"独立入口不存在或越出源码根目录：{args.entry}")
+
+    inputs = {path.resolve() for path in args.input_material}
+    if entry in inputs or root in inputs:
+        errors.append("目标入口／源码根目录与输入材料是同一对象")
+
+    markdown_files = sorted(root.rglob("*.md"))
+    if not markdown_files:
+        errors.append("目标目录没有 Markdown 源码")
+
+    texts: dict[Path, str] = {}
+    for path in markdown_files:
+        try:
+            texts[path] = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            errors.append(f"文件不是有效 UTF-8：{path.relative_to(root)} ({exc})")
+
+    for path, text in texts.items():
+        for raw in MARKDOWN_LINK.findall(text):
+            target = local_target(raw)
+            if target is None:
+                continue
+            resolved = (path.parent / target).resolve()
+            if root not in resolved.parents and resolved != root:
+                errors.append(f"相对引用越出源码根目录：{path.relative_to(root)} -> {target}")
+            elif not resolved.exists():
+                errors.append(f"相对引用不存在：{path.relative_to(root)} -> {target}")
+
+        for declared in DECLARED_SKILL.findall(text.replace("\\", "/")):
+            skill_path = (root / declared).resolve()
+            if not skill_path.is_file():
+                errors.append(f"声明的 Skill 不存在：{path.relative_to(root)} -> {declared}")
+
+    required_files: list[Path] = []
+    for relative in args.require_path:
+        path = (root / relative).resolve()
+        if root not in path.parents:
+            errors.append(f"必需资产越出源码根目录：{relative}")
+        elif not path.is_file() or path.stat().st_size == 0:
+            errors.append(f"必需资产不存在或为空：{relative}")
+        else:
+            required_files.append(path)
+
+    evaluation_files: list[Path] = []
+    if args.require_evaluation:
+        declared_evaluations = [(root / path).resolve() for path in args.evaluation_path]
+        if declared_evaluations:
+            for path in declared_evaluations:
+                if root not in path.parents and path != root:
+                    errors.append(f"评测路径越出源码根目录：{path}")
+                elif path.is_file() and path.stat().st_size > 0:
+                    evaluation_files.append(path)
+                elif path.is_dir():
+                    evaluation_files.extend(item for item in path.rglob("*") if item.is_file() and item.stat().st_size > 0)
+                else:
+                    errors.append(f"评测资产不存在或为空：{path.relative_to(root)}")
+        else:
+            for dirname in ("evaluation", "evaluations", "eval", "evals", "tests", "fixtures"):
+                candidate = root / dirname
+                if candidate.is_dir():
+                    evaluation_files.extend(item for item in candidate.rglob("*") if item.is_file() and item.stat().st_size > 0)
+        if not evaluation_files:
+            errors.append("本次要求评测资产，但目标源码中没有实际评测文件")
+
+    if args.zip_path:
+        zip_path = args.zip_path.resolve()
+        if not zip_path.is_file():
+            errors.append(f"ZIP 不存在：{zip_path}")
+        else:
+            try:
+                with zipfile.ZipFile(zip_path) as archive:
+                    corrupt = archive.testzip()
+                    if corrupt:
+                        errors.append(f"ZIP 条目损坏：{corrupt}")
+                    files = [item for item in archive.infolist() if not item.is_dir()]
+                    normalized = [item.filename.replace("\\", "/") for item in files]
+                    if not any(name == args.entry or name.endswith("/" + args.entry) for name in normalized):
+                        errors.append(f"ZIP 中找不到入口：{args.entry}")
+                    for item in files:
+                        if any(ord(char) > 127 for char in item.filename) and not (item.flag_bits & 0x800):
+                            errors.append(f"ZIP 非 ASCII 路径未标记 UTF-8：{item.filename}")
+                    if args.require_evaluation:
+                        relative_evaluations = {
+                            path.relative_to(root).as_posix() for path in evaluation_files if path.is_file()
+                        }
+                        if relative_evaluations and not all(
+                            any(name == rel or name.endswith("/" + rel) for name in normalized)
+                            for rel in relative_evaluations
+                        ):
+                            errors.append("ZIP 未包含目标源码中的全部声明／发现评测资产")
+                    relative_required = {
+                        path.relative_to(root).as_posix() for path in required_files
+                    }
+                    if relative_required and not all(
+                        any(name == rel or name.endswith("/" + rel) for name in normalized)
+                        for rel in relative_required
+                    ):
+                        errors.append("ZIP 未包含全部必需源码资产")
+            except zipfile.BadZipFile as exc:
+                errors.append(f"ZIP 无法读取：{exc}")
+
+    return report(errors, root, len(markdown_files), len(evaluation_files))
+
+
+def report(
+    errors: list[str],
+    root: Path | None = None,
+    markdown_count: int = 0,
+    evaluation_count: int = 0,
+) -> int:
+    if errors:
+        print(f"DELIVERY_FAIL：{len(errors)} 个资产交付问题")
+        for error in errors:
+            print(f"- {error}")
+        print("说明：该结果不评价设计质量，也不构成行为或平台证据。")
+        return 1
+    suffix = f"，Evaluation={evaluation_count}" if evaluation_count else ""
+    print(f"DELIVERY_PASS：入口、相对引用、声明 Skill 与编码可达（Markdown={markdown_count}{suffix}）")
+    if root:
+        print(f"target_root={root}")
+    print("说明：只证明源码资产交付一致，不评价设计质量、可装载性或运行行为。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())