project-agent 0.1.22__tar.gz

project_agent-0.1.22/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: project-agent
+Version: 0.1.22
+Summary: Project Agent Python CLI core
+Requires-Python: >=3.12
+Requires-Dist: typer<1,>=0.12
+Requires-Dist: pydantic<3,>=2.8
+Requires-Dist: sqlalchemy<3,>=2.0
+Requires-Dist: pymysql<2,>=1.1
+Requires-Dist: pendulum<4,>=3
+Requires-Dist: chinesecalendar<2,>=1.10

project_agent-0.1.22/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "project-agent"
+version = "0.1.22"
+description = "Project Agent Python CLI core"
+requires-python = ">=3.12"
+dependencies = [
+  "typer>=0.12,<1",
+  "pydantic>=2.8,<3",
+  "sqlalchemy>=2.0,<3",
+  "pymysql>=1.1,<2",
+  "pendulum>=3,<4",
+  "chinesecalendar>=1.10,<2",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+]
+
+[project.scripts]
+project-agent = "interface.cli.app:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

project_agent-0.1.22/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

project_agent-0.1.22/src/application/__init__.py

@@ -0,0 +1 @@
+"""Application layer for Project Agent."""

project_agent-0.1.22/src/application/bootstrap/__init__.py

@@ -0,0 +1 @@
+"""Bootstrap application services."""

project_agent-0.1.22/src/application/bootstrap/checkpoint.py

@@ -0,0 +1,376 @@
+from typing import Any, Protocol
+
+import pendulum
+
+from domain.bootstrap.models import (
+    BootstrapCheckpointResult,
+    BootstrapMarkResult,
+    BootstrapMilestones,
+)
+from domain.shared.project_mind_derived import (
+    describe_missing_task_fields,
+    describe_missing_version_fields,
+    resolve_current_version,
+)
+
+MILESTONE_ALIGNMENT_INTRO = "alignment_intro_sent"
+MILESTONE_EXECUTION_CONFIRMATION = "execution_confirmation_sent"
+MILESTONE_KICKOFF = "kickoff_sent"
+
+REQUIRED_BOOTSTRAP_DOC_KINDS = ("project_card", "docs_index", "project_overview")
+
+_MILESTONE_STATE_KINDS = {
+    MILESTONE_ALIGNMENT_INTRO: "bootstrap_alignment_intro",
+    MILESTONE_EXECUTION_CONFIRMATION: "bootstrap_execution_confirmation",
+    MILESTONE_KICKOFF: "bootstrap_kickoff",
+}
+
+
+class BootstrapReadStore(Protocol):
+    def find_project_by_id(self, project_id: str) -> Any: ...
+
+    def list_bindings_by_project_id(self, project_id: str) -> list[Any]: ...
+
+    def list_versions_by_project_id(self, project_id: str) -> list[Any]: ...
+
+    def list_tasks_by_project_id(self, project_id: str) -> list[Any]: ...
+
+    def list_documents_by_project_id(self, project_id: str) -> list[Any]: ...
+
+
+class PendingStateStore(Protocol):
+    def upsert_open_state(self, payload: dict) -> Any: ...
+
+    def resolve_open_state(self, *, project_id: str, state_key: str) -> Any: ...
+
+    def find_latest_by_state_key(self, *, project_id: str, state_key: str) -> Any: ...
+
+
+def alignment_intro_state_key(project_id: str) -> str:
+    return f"project:{project_id}:bootstrap:alignment_intro"
+
+
+def execution_confirmation_state_key(project_id: str) -> str:
+    return f"project:{project_id}:bootstrap:execution_confirmation"
+
+
+def kickoff_state_key(project_id: str) -> str:
+    return f"project:{project_id}:bootstrap:kickoff"
+
+
+_STATE_KEY_BUILDERS = {
+    MILESTONE_ALIGNMENT_INTRO: alignment_intro_state_key,
+    MILESTONE_EXECUTION_CONFIRMATION: execution_confirmation_state_key,
+    MILESTONE_KICKOFF: kickoff_state_key,
+}
+
+
+def ensure_alignment_intro_pending(
+    *,
+    project_id: str,
+    pending_state_store: PendingStateStore,
+) -> bool:
+    """群绑定落地时登记"欠一条对齐引导"；已有任何落账记录（含已发）时不重复登记。"""
+    state_key = alignment_intro_state_key(project_id)
+    existing = pending_state_store.find_latest_by_state_key(
+        project_id=project_id, state_key=state_key
+    )
+    if existing is not None:
+        return False
+    pending_state_store.upsert_open_state(
+        {
+            "project_id": project_id,
+            "scope_kind": "project",
+            "scope_ref": project_id,
+            "state_kind": _MILESTONE_STATE_KINDS[MILESTONE_ALIGNMENT_INTRO],
+            "state_key": state_key,
+            "payload_json": {
+                "milestone": MILESTONE_ALIGNMENT_INTRO,
+                "openedAt": _now_iso(),
+            },
+            "status": "open",
+            "expires_at": None,
+        }
+    )
+    return True
+
+
+def evaluate_bootstrap_checkpoint(
+    *,
+    project_id: str,
+    bootstrap_store: BootstrapReadStore,
+    pending_state_store: PendingStateStore,
+) -> BootstrapCheckpointResult | None:
+    project = bootstrap_store.find_project_by_id(project_id)
+    if project is None:
+        return None
+
+    bindings = bootstrap_store.list_bindings_by_project_id(project_id)
+    has_group_binding = any(
+        binding.get("binding_kind") == "project_group" and binding.get("status") == "active"
+        for binding in bindings
+    )
+    documents = bootstrap_store.list_documents_by_project_id(project_id)
+    landed_doc_kinds = {document.get("doc_kind") for document in documents}
+    has_project_card_doc = "project_card" in landed_doc_kinds
+    doc_gaps = [kind for kind in REQUIRED_BOOTSTRAP_DOC_KINDS if kind not in landed_doc_kinds]
+
+    versions = bootstrap_store.list_versions_by_project_id(project_id)
+    tasks = bootstrap_store.list_tasks_by_project_id(project_id)
+    alignment_gaps = _build_alignment_gaps(project=project, versions=versions, tasks=tasks)
+    alignment_ready = _is_alignment_ready(project=project, versions=versions, tasks=tasks)
+
+    mind_stage = project.get("mind_stage") or "v0"
+    kickoff_sent = _is_milestone_marked(
+        project_id=project_id,
+        state_key=kickoff_state_key(project_id),
+        pending_state_store=pending_state_store,
+    )
+    # bootstrap 是否仍在进行，以 kickoff 是否已落账为准：create-version 会在团队对齐期
+    # 把 mind_stage 提前翻成 v1，但只要 kickoff 还没发，bootstrap 就还没结束。
+    bootstrap_active = not kickoff_sent
+
+    intro_status = _reconcile_alignment_intro(
+        project_id=project_id,
+        bootstrap_active=bootstrap_active,
+        has_group_binding=has_group_binding,
+        pending_state_store=pending_state_store,
+    )
+    confirmation_status = _reconcile_execution_confirmation(
+        project_id=project_id,
+        bootstrap_active=bootstrap_active,
+        intro_status=intro_status,
+        alignment_ready=alignment_ready,
+        pending_state_store=pending_state_store,
+    )
+    kickoff_status = _reconcile_kickoff(
+        confirmation_status=confirmation_status,
+        kickoff_sent=kickoff_sent,
+    )
+
+    return BootstrapCheckpointResult(
+        project_id=project_id,
+        mind_stage=mind_stage,
+        has_group_binding=has_group_binding,
+        has_project_card_doc=has_project_card_doc,
+        doc_gaps=doc_gaps,
+        alignment_ready=alignment_ready,
+        alignment_gaps=alignment_gaps,
+        milestones=BootstrapMilestones(
+            alignment_intro=intro_status,
+            execution_confirmation=confirmation_status,
+            kickoff=kickoff_status,
+        ),
+        next_action=_select_next_action(
+            bootstrap_active=bootstrap_active,
+            has_group_binding=has_group_binding,
+            has_project_card_doc=has_project_card_doc,
+            doc_gaps=doc_gaps,
+            intro_status=intro_status,
+            alignment_ready=alignment_ready,
+            confirmation_status=confirmation_status,
+        ),
+    )
+
+
+def mark_bootstrap_milestone(
+    *,
+    project_id: str,
+    milestone: str,
+    bootstrap_store: BootstrapReadStore,
+    pending_state_store: PendingStateStore,
+) -> BootstrapMarkResult | None:
+    if milestone not in _MILESTONE_STATE_KINDS:
+        raise ValueError(f"unknown bootstrap milestone: {milestone}")
+    project = bootstrap_store.find_project_by_id(project_id)
+    if project is None:
+        return None
+
+    state_key = _STATE_KEY_BUILDERS[milestone](project_id)
+    already_marked = False
+    resolved = pending_state_store.resolve_open_state(
+        project_id=project_id, state_key=state_key
+    )
+    if resolved is None:
+        existing = pending_state_store.find_latest_by_state_key(
+            project_id=project_id, state_key=state_key
+        )
+        if existing is not None and existing.get("status") != "open":
+            already_marked = True
+        else:
+            # 没有任何登记也允许补账，保证"发过什么"永远可核验。
+            pending_state_store.upsert_open_state(
+                {
+                    "project_id": project_id,
+                    "scope_kind": "project",
+                    "scope_ref": project_id,
+                    "state_kind": _MILESTONE_STATE_KINDS[milestone],
+                    "state_key": state_key,
+                    "payload_json": {
+                        "milestone": milestone,
+                        "markedAt": _now_iso(),
+                    },
+                    "status": "resolved",
+                    "expires_at": None,
+                }
+            )
+
+    checkpoint = evaluate_bootstrap_checkpoint(
+        project_id=project_id,
+        bootstrap_store=bootstrap_store,
+        pending_state_store=pending_state_store,
+    )
+    if checkpoint is None:
+        return None
+    return BootstrapMarkResult(
+        project_id=project_id,
+        milestone=milestone,
+        already_marked=already_marked,
+        checkpoint=checkpoint,
+    )
+
+
+def _build_alignment_gaps(
+    *, project: dict, versions: list[dict], tasks: list[dict]
+) -> list[str]:
+    current_version = resolve_current_version(project=project, versions=versions)
+    if current_version is None:
+        return ["missing_current_version"]
+    current_tasks = [
+        task for task in tasks if task.get("version_id") == current_version.get("version_id")
+    ]
+    gaps = [
+        f"current_version:{field}"
+        for field in describe_missing_version_fields(version=current_version, tasks=current_tasks)
+    ]
+    if not current_tasks:
+        gaps.append("missing_trackable_task")
+        return gaps
+    for task in current_tasks:
+        for field in describe_missing_task_fields(task=task):
+            gaps.append(f"task:{task.get('task_id') or 'unknown'}:{field}")
+    return gaps
+
+
+def _is_alignment_ready(*, project: dict, versions: list[dict], tasks: list[dict]) -> bool:
+    current_version = resolve_current_version(project=project, versions=versions)
+    if current_version is None:
+        return False
+    current_tasks = [
+        task for task in tasks if task.get("version_id") == current_version.get("version_id")
+    ]
+    if describe_missing_version_fields(version=current_version, tasks=current_tasks):
+        return False
+    # 执行启动确认只要求至少一个可追踪 Task 必填字段齐全。
+    return any(not describe_missing_task_fields(task=task) for task in current_tasks)
+
+
+def _is_milestone_marked(
+    *, project_id: str, state_key: str, pending_state_store: PendingStateStore
+) -> bool:
+    record = pending_state_store.find_latest_by_state_key(
+        project_id=project_id, state_key=state_key
+    )
+    return record is not None and record.get("status") != "open"
+
+
+def _reconcile_alignment_intro(
+    *,
+    project_id: str,
+    bootstrap_active: bool,
+    has_group_binding: bool,
+    pending_state_store: PendingStateStore,
+) -> str:
+    if not bootstrap_active or not has_group_binding:
+        return "not_required"
+    state_key = alignment_intro_state_key(project_id)
+    record = pending_state_store.find_latest_by_state_key(
+        project_id=project_id, state_key=state_key
+    )
+    if record is None:
+        ensure_alignment_intro_pending(
+            project_id=project_id, pending_state_store=pending_state_store
+        )
+        return "pending"
+    if record.get("status") == "open":
+        return "pending"
+    return "sent"
+
+
+def _reconcile_execution_confirmation(
+    *,
+    project_id: str,
+    bootstrap_active: bool,
+    intro_status: str,
+    alignment_ready: bool,
+    pending_state_store: PendingStateStore,
+) -> str:
+    if not bootstrap_active:
+        return "not_required"
+    state_key = execution_confirmation_state_key(project_id)
+    record = pending_state_store.find_latest_by_state_key(
+        project_id=project_id, state_key=state_key
+    )
+    if record is not None:
+        return "pending" if record.get("status") == "open" else "sent"
+    if intro_status != "sent" or not alignment_ready:
+        return "not_ready"
+    pending_state_store.upsert_open_state(
+        {
+            "project_id": project_id,
+            "scope_kind": "project",
+            "scope_ref": project_id,
+            "state_kind": _MILESTONE_STATE_KINDS[MILESTONE_EXECUTION_CONFIRMATION],
+            "state_key": state_key,
+            "payload_json": {
+                "milestone": MILESTONE_EXECUTION_CONFIRMATION,
+                "openedAt": _now_iso(),
+            },
+            "status": "open",
+            "expires_at": None,
+        }
+    )
+    return "pending"
+
+
+def _reconcile_kickoff(*, confirmation_status: str, kickoff_sent: bool) -> str:
+    if kickoff_sent:
+        return "sent"
+    if confirmation_status == "sent":
+        return "pending"
+    return "not_ready"
+
+
+def _select_next_action(
+    *,
+    bootstrap_active: bool,
+    has_group_binding: bool,
+    has_project_card_doc: bool,
+    doc_gaps: list[str],
+    intro_status: str,
+    alignment_ready: bool,
+    confirmation_status: str,
+) -> str:
+    if not bootstrap_active:
+        return "bootstrap_complete"
+    if not has_group_binding:
+        return "create_group_binding"
+    # 对齐引导唯一硬前置是 Project Card；缺它先驱动文档落地。
+    if intro_status == "pending" and not has_project_card_doc:
+        return "land_project_card"
+    if intro_status == "pending":
+        return "send_alignment_intro"
+    if confirmation_status == "pending":
+        return "send_execution_confirmation"
+    # 消息欠账还清后，剩余文档欠账由 agent 当轮补齐，不阻塞人侧流程。
+    if doc_gaps:
+        return "backfill_docs"
+    if not alignment_ready:
+        return "collect_alignment_fields"
+    if confirmation_status == "sent":
+        return "await_owner_confirmation"
+    return "collect_alignment_fields"
+
+
+def _now_iso() -> str:
+    return pendulum.now("UTC").to_iso8601_string()

project_agent-0.1.22/src/application/bootstrap/init.py

@@ -0,0 +1,201 @@
+from typing import Any, Protocol
+
+from application.bootstrap.checkpoint import (
+    PendingStateStore,
+    ensure_alignment_intro_pending,
+)
+from application.context.binding_normalization import (
+    normalize_binding_channel,
+    normalize_external_channel_id_for_write,
+)
+from application.loop.enqueue import enqueue_bootstrap_continue
+from domain.bootstrap.models import BootstrapBinding, BootstrapInitResult
+from domain.shared.project_mind_derived import (
+    build_project_intro,
+    collect_participants,
+    resolve_current_version,
+    resolve_target_release_date,
+)
+from domain.shared.project_mind_readiness import (
+    build_group_provisioning_gaps,
+    build_v1_readiness_gaps,
+)
+
+
+class BootstrapStore(Protocol):
+    def find_project_by_id(self, project_id: str) -> Any: ...
+
+    def upsert_project(self, payload: dict) -> Any: ...
+
+    def upsert_binding(self, payload: dict) -> Any: ...
+
+    def list_bindings_by_project_id(self, project_id: str) -> list[Any]: ...
+
+    def list_versions_by_project_id(self, project_id: str) -> list[Any]: ...
+
+    def list_tasks_by_project_id(self, project_id: str) -> list[Any]: ...
+
+    def list_participants_by_project_id(self, project_id: str) -> list[Any]: ...
+
+    def upsert_participant(self, payload: dict) -> Any: ...
+
+    def list_documents_by_project_id(self, project_id: str) -> list[Any]: ...
+
+    def find_monitoring_policy_by_project_id(self, project_id: str) -> Any: ...
+
+
+def init_project_bootstrap(
+    *,
+    project_id: str,
+    project_name: str,
+    owner_user_id: str,
+    primary_goal: str,
+    target_release_date: str | None,
+    timezone: str | None,
+    channel: str | None,
+    project_group_id: str | None,
+    participant_user_ids: list[str] | None,
+    bootstrap_store: BootstrapStore,
+    pending_state_store: PendingStateStore | None = None,
+    loop_job_store: Any | None = None,
+) -> BootstrapInitResult:
+    existing_project = bootstrap_store.find_project_by_id(project_id)
+    project = bootstrap_store.upsert_project(
+        {
+            "project_id": project_id,
+            "project_name": project_name,
+            "owner_user_id": owner_user_id,
+            "primary_goal": primary_goal or (existing_project or {}).get("primary_goal"),
+            "timezone": timezone,
+            "mind_stage": (existing_project or {}).get("mind_stage") or "v0",
+            "lifecycle_status": (existing_project or {}).get("lifecycle_status") or "active",
+            "current_revision_id": (existing_project or {}).get("current_revision_id"),
+            "current_version_id": (existing_project or {}).get("current_version_id"),
+            "target_release_date": target_release_date
+            if target_release_date is not None
+            else (existing_project or {}).get("target_release_date"),
+        }
+    )
+
+    if project_group_id:
+        effective_channel = normalize_binding_channel(channel)
+        bootstrap_store.upsert_binding(
+            {
+                "project_id": project_id,
+                "channel": effective_channel,
+                "external_channel_id": normalize_external_channel_id_for_write(
+                    channel=effective_channel,
+                    external_channel_id=project_group_id,
+                ),
+                "binding_kind": "project_group",
+                "status": "active",
+            }
+        )
+        # 群绑定是确定性写入点：在这里登记"欠对齐引导"，不依赖 skill 自觉补账。
+        if pending_state_store is not None and project.get("mind_stage") == "v0":
+            ensure_alignment_intro_pending(
+                project_id=project_id,
+                pending_state_store=pending_state_store,
+            )
+        if loop_job_store is not None:
+            enqueue_bootstrap_continue(
+                project_id=project_id,
+                loop_job_store=loop_job_store,
+                reason="project_group_binding_ready",
+                source="bootstrap_init",
+            )
+
+    bootstrap_store.upsert_participant(
+        {
+            "project_id": project_id,
+            "user_id": owner_user_id,
+            "role": "owner",
+            "status": "active",
+        }
+    )
+    for participant_user_id in _dedupe_participant_user_ids(participant_user_ids or []):
+        if participant_user_id == owner_user_id:
+            continue
+        bootstrap_store.upsert_participant(
+            {
+                "project_id": project_id,
+                "user_id": participant_user_id,
+                "role": "member",
+                "status": "active",
+            }
+        )
+
+    bindings = [
+        BootstrapBinding(
+            binding_kind=binding["binding_kind"],
+            channel=binding["channel"],
+            external_channel_id=binding["external_channel_id"],
+            status=binding["status"],
+        )
+        for binding in bootstrap_store.list_bindings_by_project_id(project_id)
+    ]
+    versions = bootstrap_store.list_versions_by_project_id(project_id)
+    tasks = bootstrap_store.list_tasks_by_project_id(project_id)
+    stored_participants = bootstrap_store.list_participants_by_project_id(project_id)
+    readiness_participants = [
+        *stored_participants,
+        *_participant_rows_from_project_mind(versions=versions, tasks=tasks),
+    ]
+    documents = bootstrap_store.list_documents_by_project_id(project_id)
+    monitoring_policy = bootstrap_store.find_monitoring_policy_by_project_id(project_id)
+    group_provisioning_gaps = build_group_provisioning_gaps(
+        project=project,
+        participants=readiness_participants,
+    )
+    v1_gaps = build_v1_readiness_gaps(
+        project=project,
+        bindings=[binding.model_dump(mode="json", by_alias=False) for binding in bindings],
+        monitoring_enabled=bool((monitoring_policy or {}).get("enabled")),
+        documents=documents,
+        versions=versions,
+        tasks=tasks,
+        participants=readiness_participants,
+    )
+    current_version = resolve_current_version(project=project, versions=versions)
+
+    return BootstrapInitResult(
+        project_id=project["project_id"],
+        project_name=project["project_name"],
+        owner_user_id=project["owner_user_id"],
+        primary_goal=project.get("primary_goal") or "",
+        target_release_date=resolve_target_release_date(
+            project=project,
+            current_version=current_version,
+        ),
+        participants=collect_participants(
+            versions=versions,
+            tasks=tasks,
+            participants=stored_participants,
+        ),
+        project_intro=build_project_intro(project=project, versions=versions, tasks=tasks),
+        last_updated_at=project.get("last_updated_at"),
+        mind_stage=project["mind_stage"],
+        lifecycle_status=project["lifecycle_status"],
+        timezone=project.get("timezone"),
+        bindings=bindings,
+        group_provisioning_ready=not group_provisioning_gaps,
+        group_provisioning_gaps=group_provisioning_gaps,
+        v1_ready=not v1_gaps,
+        v1_gaps=v1_gaps,
+    )
+
+
+def _dedupe_participant_user_ids(values: list[str]) -> list[str]:
+    ordered: list[str] = []
+    for value in values:
+        normalized = value.strip()
+        if normalized and normalized not in ordered:
+            ordered.append(normalized)
+    return ordered
+
+
+def _participant_rows_from_project_mind(*, versions: list[dict], tasks: list[dict]) -> list[dict]:
+    return [
+        {"user_id": user_id, "status": "active"}
+        for user_id in collect_participants(versions=versions, tasks=tasks)
+    ]