project-agent 0.2.1__tar.gz → 0.2.4__tar.gz

{project_agent-0.2.1 → project_agent-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-agent
-Version: 0.2.1
+Version: 0.2.4
 Summary: Project Agent Python CLI core
 Requires-Python: >=3.11
 Requires-Dist: typer<1,>=0.12

{project_agent-0.2.1 → project_agent-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "project-agent"
-version = "0.2.1"
+version = "0.2.4"
 description = "Project Agent Python CLI core"
 requires-python = ">=3.11"
 dependencies = [

project_agent-0.2.4/src/project_agent/application/context/add_project_member.py

@@ -0,0 +1,50 @@
+from typing import Any, Protocol
+
+from project_agent.domain.project_context.models import AddProjectMemberResult, ProjectParticipantSummary
+
+
+class ProjectStore(Protocol):
+    def find_by_id(self, project_id: str) -> Any: ...
+
+
+class UserStore(Protocol):
+    def find_by_id(self, user_id: str) -> Any: ...
+
+
+class ParticipantWriteStore(Protocol):
+    def upsert_participant(self, payload: dict) -> dict: ...
+
+
+def add_project_member(
+    *,
+    project_id: str,
+    user_id: str,
+    project_store: ProjectStore,
+    user_store: UserStore,
+    participant_store: ParticipantWriteStore,
+) -> AddProjectMemberResult:
+    if not project_store.find_by_id(project_id):
+        raise ValueError(f"project not found: {project_id}")
+    if not user_store.find_by_id(user_id):
+        raise ValueError(f"user not found: {user_id}")
+
+    participant = participant_store.upsert_participant(
+        {
+            "project_id": project_id,
+            "user_id": user_id,
+            "role": "member",
+            "status": "active",
+        }
+    )
+    return AddProjectMemberResult(
+        status="ok",
+        participant=ProjectParticipantSummary(
+            participant_id=participant["participant_id"],
+            project_id=participant["project_id"],
+            user_id=participant["user_id"],
+            role=participant["role"],
+            status=participant["status"],
+            created_at=participant.get("created_at"),
+            updated_at=participant.get("updated_at"),
+        ),
+    )

project_agent-0.2.4/src/project_agent/application/context/get_project_context.py

@@ -0,0 +1,128 @@
+from typing import Any, Protocol
+
+from project_agent.application.shared.project_participants import build_project_participant_summaries
+from project_agent.application.shared.user_refs import build_structured_user_ref
+from project_agent.domain.project_context.models import ProjectContext
+from project_agent.domain.shared.project_mind_derived import build_project_intro, collect_participants
+
+
+class ProjectStore(Protocol):
+    def find_by_id(self, project_id: str) -> Any: ...
+
+
+class BindingStore(Protocol):
+    def list_by_project_id(self, project_id: str) -> list[Any]: ...
+
+
+class PendingStateStore(Protocol):
+    def list_open_by_project_id(self, project_id: str) -> list[Any]: ...
+
+
+class DocumentStore(Protocol):
+    def list_by_project_id(self, project_id: str) -> list[Any]: ...
+
+
+class ParticipantStore(Protocol):
+    def list_by_project_id(self, project_id: str) -> list[Any]: ...
+
+
+class VersionStore(Protocol):
+    def list_by_project_id(self, project_id: str) -> list[Any]: ...
+
+
+class TaskStore(Protocol):
+    def list_by_project_id(self, project_id: str, task_id: str | None = None) -> list[Any]: ...
+
+
+class UserStore(Protocol):
+    def find_by_id(self, user_id: str) -> Any: ...
+
+
+class UserIdentityStore(Protocol):
+    def list_by_user_id(self, user_id: str) -> list[Any]: ...
+
+
+def get_project_context(
+    *,
+    project_id: str,
+    channel: str | None = None,
+    project_store: ProjectStore,
+    binding_store: BindingStore | None = None,
+    pending_state_store: PendingStateStore | None = None,
+    document_store: DocumentStore | None = None,
+    participant_store: ParticipantStore | None = None,
+    version_store: VersionStore | None = None,
+    task_store: TaskStore | None = None,
+    user_store: UserStore | None = None,
+    identity_store: UserIdentityStore | None = None,
+) -> ProjectContext | None:
+    project = project_store.find_by_id(project_id)
+
+    if not project:
+        return None
+
+    bindings = []
+    if binding_store is not None:
+        bindings = binding_store.list_by_project_id(project_id)
+
+    pending_states = []
+    if pending_state_store is not None:
+        pending_states = pending_state_store.list_open_by_project_id(project_id)
+
+    documents = []
+    if document_store is not None:
+        documents = document_store.list_by_project_id(project_id)
+
+    participant_rows = []
+    if participant_store is not None:
+        participant_rows = participant_store.list_by_project_id(project_id)
+
+    versions = []
+    if version_store is not None:
+        versions = version_store.list_by_project_id(project_id)
+
+    tasks = []
+    if task_store is not None:
+        tasks = task_store.list_by_project_id(project_id)
+
+    owner_user = build_structured_user_ref(
+        user_id=project.get("owner_user_id"),
+        user_store=user_store,
+        user_identity_store=identity_store,
+        identity_cache={},
+        user_cache={},
+    )
+    user_cache: dict[str, dict | None] = {}
+    identity_cache: dict[str, list[dict]] = {}
+    participant_summaries = build_project_participant_summaries(
+        participant_user_ids=collect_participants(
+            versions=versions,
+            tasks=tasks,
+            participants=participant_rows,
+        ),
+        participant_rows=participant_rows,
+        owner_user_id=project.get("owner_user_id"),
+        user_store=user_store,
+        user_identity_store=identity_store,
+        channel=channel,
+        user_cache=user_cache,
+        identity_cache=identity_cache,
+    )
+
+    return ProjectContext(
+        project_id=project_id,
+        owner_user=owner_user,
+        primary_goal=project.get("primary_goal"),
+        project_intro=build_project_intro(project=project, versions=versions, tasks=tasks),
+        lifecycle_status=project["lifecycle_status"],
+        mind_stage=project["mind_stage"],
+        current_revision_id=project.get("current_revision_id"),
+        current_version_id=project.get("current_version_id"),
+        tracking_mode=project.get("tracking_mode") or "active",
+        tracking_paused_reason=project.get("tracking_paused_reason"),
+        tracking_paused_at=project.get("tracking_paused_at"),
+        bindings=bindings,
+        participants=participant_summaries,
+        pending_states=pending_states,
+        documents=documents,
+    )

project_agent-0.2.4/src/project_agent/application/context/project_summary.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from datetime import UTC, date, datetime
+from typing import Any, Protocol
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from project_agent.domain.project_context.models import (
+    PersonalTaskSummary,
+    ProjectSummaryResult,
+    TeamTaskSummary,
+)
+from project_agent.domain.shared.statuses import (
+    is_done_status,
+    is_terminal_task_status,
+    normalize_task_status,
+)
+
+
+class ProjectStore(Protocol):
+    def find_by_id(self, project_id: str) -> Any: ...
+
+
+class TaskStore(Protocol):
+    def list_by_project_id(self, project_id: str, task_id: str | None = None) -> list[Any]: ...
+
+
+def build_project_summary(
+    *,
+    project_id: str,
+    user_id: str,
+    timezone: str | None,
+    project_store: ProjectStore,
+    task_store: TaskStore,
+) -> ProjectSummaryResult | None:
+    project = project_store.find_by_id(project_id)
+    if not project:
+        return None
+
+    tz = resolve_summary_timezone(timezone or project.get("timezone") or "UTC")
+    today = datetime.now(tz).date()
+    tasks = task_store.list_by_project_id(project_id)
+
+    return ProjectSummaryResult(
+        project_id=project["project_id"],
+        project_name=project["project_name"],
+        team_task=_build_team_task_summary(tasks, today=today, tz=tz),
+        personal=_build_personal_task_summary(tasks, user_id=user_id, today=today, tz=tz),
+        updated_at=_utc_millis(project.get("last_updated_at")),
+    )
+
+
+def resolve_summary_timezone(value: str) -> ZoneInfo:
+    try:
+        return ZoneInfo(value)
+    except ZoneInfoNotFoundError as exc:
+        raise ValueError(f"unknown timezone: {value}") from exc
+
+
+def _build_team_task_summary(
+    tasks: list[Any],
+    *,
+    today: date,
+    tz: ZoneInfo,
+) -> TeamTaskSummary:
+    new_assigned_today_tasks = [
+        task for task in tasks if _is_today(_task_value(task, "created_at"), today, tz)
+    ]
+    new_assigned_today = len(new_assigned_today_tasks)
+    if new_assigned_today_tasks and all(
+        is_done_status(_task_value(task, "task_status")) for task in new_assigned_today_tasks
+    ):
+        new_assigned_today = 0
+
+    return TeamTaskSummary(
+        status="HAS_TASK" if tasks else "NO_TASK",
+        new_assigned_today=new_assigned_today,
+        completed_today=sum(
+            1
+            for task in tasks
+            if is_done_status(_task_value(task, "task_status"))
+            and _is_today(_task_value(task, "updated_at") or _task_value(task, "last_updated_at"), today, tz)
+        ),
+        in_progress=sum(
+            1
+            for task in tasks
+            if normalize_task_status(_task_value(task, "task_status")) == "in_progress"
+        ),
+    )
+
+
+def _build_personal_task_summary(
+    tasks: list[Any],
+    *,
+    user_id: str,
+    today: date,
+    tz: ZoneInfo,
+) -> PersonalTaskSummary:
+    personal_tasks = [task for task in tasks if _task_value(task, "owner_user_id") == user_id]
+    return PersonalTaskSummary(
+        new_tasks_today=sum(
+            1 for task in personal_tasks if _is_today(_task_value(task, "created_at"), today, tz)
+        ),
+        due_tasks_today=sum(
+            1
+            for task in personal_tasks
+            if _task_due_date(_task_value(task, "end_date"), tz=tz) == today
+            and not is_terminal_task_status(_task_value(task, "task_status"))
+        ),
+    )
+
+
+def _task_value(task: Any, key: str) -> Any:
+    if isinstance(task, dict):
+        return task.get(key)
+    return getattr(task, key, None)
+
+
+def _is_today(value: Any, today: date, tz: ZoneInfo) -> bool:
+    parsed = _parse_datetime(value, tz=tz)
+    return parsed is not None and parsed.date() == today
+
+
+def _task_due_date(value: Any, *, tz: ZoneInfo) -> date | None:
+    if value is None:
+        return None
+    if isinstance(value, date) and not isinstance(value, datetime):
+        return value
+    token = str(value).strip()
+    if not token:
+        return None
+    try:
+        return date.fromisoformat(token[:10])
+    except ValueError:
+        parsed = _parse_datetime(token, tz=tz)
+        return parsed.date() if parsed is not None else None
+
+
+def _parse_datetime(value: Any, *, tz: ZoneInfo) -> datetime | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        parsed = value
+    else:
+        token = str(value).strip()
+        if not token:
+            return None
+        try:
+            parsed = datetime.fromisoformat(token.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(tz)
+
+
+def _utc_millis(value: Any) -> int | None:
+    parsed = _parse_datetime(value, tz=ZoneInfo("UTC"))
+    if parsed is None:
+        return None
+    return int(parsed.timestamp() * 1000)

project_agent-0.2.4/src/project_agent/application/context/set_project_owner.py

@@ -0,0 +1,59 @@
+from typing import Any, Protocol
+
+from project_agent.domain.project_context.models import SetProjectOwnerResult
+
+
+class ProjectStore(Protocol):
+    def find_by_id(self, project_id: str) -> Any: ...
+
+    def update_owner_user_id(self, *, project_id: str, owner_user_id: str) -> dict: ...
+
+
+class UserStore(Protocol):
+    def find_by_id(self, user_id: str) -> Any: ...
+
+
+class ParticipantWriteStore(Protocol):
+    def upsert_participant(self, payload: dict) -> dict: ...
+
+
+def set_project_owner(
+    *,
+    project_id: str,
+    user_id: str,
+    project_store: ProjectStore,
+    user_store: UserStore,
+    participant_store: ParticipantWriteStore,
+) -> SetProjectOwnerResult:
+    project = project_store.find_by_id(project_id)
+    if not project:
+        raise ValueError(f"project not found: {project_id}")
+    if not user_store.find_by_id(user_id):
+        raise ValueError(f"user not found: {user_id}")
+
+    previous_owner_user_id = project.get("owner_user_id")
+    project_store.update_owner_user_id(project_id=project_id, owner_user_id=user_id)
+    participant_store.upsert_participant(
+        {
+            "project_id": project_id,
+            "user_id": user_id,
+            "role": "owner",
+            "status": "active",
+        }
+    )
+    if previous_owner_user_id and previous_owner_user_id != user_id:
+        participant_store.upsert_participant(
+            {
+                "project_id": project_id,
+                "user_id": previous_owner_user_id,
+                "role": "member",
+                "status": "active",
+            }
+        )
+
+    return SetProjectOwnerResult(
+        status="ok",
+        project_id=project_id,
+        owner_user_id=user_id,
+        previous_owner_user_id=previous_owner_user_id,
+    )

{project_agent-0.2.1 → project_agent-0.2.4}/src/project_agent/application/doc/render.py

@@ -34,6 +34,10 @@ class ParticipantStore(Protocol):
     def list_by_project_id(self, project_id: str) -> list[Any]: ...
 
 
+class UserStore(Protocol):
+    def find_by_id(self, user_id: str) -> Any: ...
+
+
 class DocumentStore(Protocol):
     def list_by_project_id(self, project_id: str) -> list[Any]: ...
 
@@ -74,9 +78,12 @@ def render_project_document(
     document_store: DocumentStore | None = None,
     doc_hub_entry_store: DocHubEntryStore | None = None,
     channel: str | None = None,
+    provider: str | None = None,
+    user_store: UserStore | None = None,
     user_identity_store: Any | None = None,
 ) -> DocRenderResult | None:
     del template_ref
+    provider = provider or channel
 
     project = project_store.find_by_id(project_id)
     if not project:
@@ -97,7 +104,9 @@ def render_project_document(
             tasks=tasks,
             version_id=version_id,
         )
-        _enrich_sections_with_channel_identities(sections, channel, user_identity_store)
+        _enrich_sections_with_user_display_values(sections, user_store)
+        if provider == "feishu":
+            _enrich_sections_with_channel_identities(sections, "feishu", user_identity_store)
         return _with_render_hash(DocRenderResult(
             project_id=project_id,
             doc_kind=doc_kind,
@@ -190,7 +199,9 @@ def render_project_document(
             ),
         ]
         title = project["project_name"]
-        _enrich_sections_with_channel_identities(sections, channel, user_identity_store)
+        _enrich_sections_with_user_display_values(sections, user_store)
+        if provider == "feishu":
+            _enrich_sections_with_channel_identities(sections, "feishu", user_identity_store)
         return _with_render_hash(DocRenderResult(
             project_id=project_id,
             doc_kind=doc_kind,
@@ -204,7 +215,7 @@ def render_project_document(
             project_id=project_id,
             doc_hub_entry_store=doc_hub_entry_store,
         )
-        sections = _build_docs_index_sections(entries=entries, relations=relations, channel=channel)
+        sections = _build_docs_index_sections(entries=entries, relations=relations, provider=provider)
         title = f"{project['project_name']} Docs Index"
         return _with_render_hash(DocRenderResult(
             project_id=project_id,
@@ -222,11 +233,11 @@ def render_project_document(
     planned_versions = _planned_versions(versions=versions, current_version_id=current_version_id)
     past_versions = _past_versions(versions=versions)
     documents = document_store.list_by_project_id(project_id) if document_store is not None else []
-    snapshot_links = _version_snapshot_links(documents=documents, channel=channel)
+    snapshot_links = _version_snapshot_links(documents=documents, provider=provider)
     docs_index_url = _single_document_link(
         documents=documents,
         doc_kind="docs_index",
-        channel=channel,
+        provider=provider,
     )
     sections = _build_overview_sections(
         project=project,
@@ -241,7 +252,9 @@ def render_project_document(
         docs_index_url=docs_index_url,
     )
     title = f"{project['project_name']} Overview"
-    _enrich_sections_with_channel_identities(sections, channel, user_identity_store)
+    _enrich_sections_with_user_display_values(sections, user_store)
+    if provider == "feishu":
+        _enrich_sections_with_channel_identities(sections, "feishu", user_identity_store)
     return _with_render_hash(DocRenderResult(
         project_id=project_id,
         doc_kind=doc_kind,
@@ -265,18 +278,38 @@ def _load_doc_hub_index_inputs(
 
 
 def _with_render_hash(result: DocRenderResult) -> DocRenderResult:
-    payload = result.model_dump(mode="json", by_alias=True, exclude={"render_hash", "status"})
+    payload = _strip_render_hash_ignored_hints(
+        result.model_dump(mode="json", by_alias=True, exclude={"render_hash", "status"})
+    )
     encoded = json.dumps(payload, ensure_ascii=True, sort_keys=True, separators=(",", ":"))
     return result.model_copy(update={"render_hash": hashlib.sha256(encoded.encode("utf-8")).hexdigest()})
 
 
+def _strip_render_hash_ignored_hints(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            key: _strip_render_hash_ignored_hints(item)
+            for key, item in value.items()
+            if key
+            not in {
+                "displayValue",
+                "userDisplayNames",
+                "task_owner_display_value",
+                "planned_version_owner_display_value",
+            }
+        }
+    if isinstance(value, list):
+        return [_strip_render_hash_ignored_hints(item) for item in value]
+    return value
+
+
 def _build_docs_index_sections(
     *,
     entries: list[Any],
     relations: list[Any],
-    channel: str | None,
+    provider: str | None,
 ) -> list[DocSection]:
-    index_payload = _build_docs_index_payload(entries=entries, relations=relations, channel=channel)
+    index_payload = _build_docs_index_payload(entries=entries, relations=relations, provider=provider)
     sections = [
         DocSection(
             heading="Registered Documents",
@@ -297,13 +330,13 @@ def _build_docs_index_payload(
     *,
     entries: list[Any],
     relations: list[Any],
-    channel: str | None,
+    provider: str | None,
 ) -> dict[str, list[dict]]:
     rows = []
     filtered_entry_ids: set[str] = set()
     entry_titles_by_id: dict[str, str] = {}
     for entry in entries:
-        if channel is not None and entry.get("provider") != channel:
+        if provider is not None and entry.get("provider") != provider:
             continue
         entry_id = entry.get("entry_id")
         filtered_entry_ids.add(entry_id)
@@ -341,6 +374,45 @@ def _build_docs_index_payload(
     return {"documents": rows, "relations": relation_rows}
 
 
+def _enrich_sections_with_user_display_values(
+    sections: list[DocSection],
+    user_store: UserStore | None,
+) -> None:
+    if user_store is None:
+        return
+
+    user_ids: set[str] = set()
+    _collect_user_ids(sections, user_ids)
+    if not user_ids:
+        return
+
+    display_names: dict[str, str] = {}
+    for uid in user_ids:
+        user = user_store.find_by_id(uid)
+        display_names[uid] = (user or {}).get("display_name") or uid
+
+    for section in sections:
+        for field in section.payload.get("fields", []):
+            value = field.get("value", "")
+            if not isinstance(value, str):
+                continue
+            uids = [token for token in value.split(", ") if token.startswith("usr_")]
+            if not uids:
+                continue
+            names = [display_names.get(uid, uid) for uid in uids]
+            field["displayValue"] = ", ".join(names)
+            if len(names) > 1:
+                field["userDisplayNames"] = names
+        for item in section.payload.get("tasks", []):
+            owner = item.get("task_owner", "")
+            if isinstance(owner, str) and owner.startswith("usr_"):
+                item["task_owner_display_value"] = display_names.get(owner, owner)
+        for item in section.payload.get("versions", []):
+            owner = item.get("planned_version_owner", "")
+            if isinstance(owner, str) and owner.startswith("usr_"):
+                item["planned_version_owner_display_value"] = display_names.get(owner, owner)
+
+
 def _enrich_sections_with_channel_identities(
     sections: list[DocSection],
     channel: str | None,
@@ -535,6 +607,11 @@ def _build_overview_sections(
                         "label": "Goal",
                         "value": (current_version or {}).get("version_goal") or "TBD",
                     },
+                    {
+                        "name": "version_summary",
+                        "label": "Version Summary",
+                        "value": (current_version or {}).get("version_summary") or "TBD",
+                    },
                     {
                         "name": "version_owner",
                         "label": "Owner",
@@ -693,6 +770,7 @@ def _build_planned_versions_payload(*, planned_versions: list[dict], current_ver
                     "planned_version_name": "TBD",
                     "planned_version_milestone": "TBD",
                     "planned_version_goal": "TBD",
+                    "planned_version_summary": "TBD",
                     "planned_version_owner": "TBD",
                     "planned_version_target_start_date": "TBD",
                     "planned_version_target_start_date_note": "（待补充）",
@@ -710,6 +788,7 @@ def _build_planned_versions_payload(*, planned_versions: list[dict], current_ver
                 "planned_version_name": version.get("version_name") or "TBD",
                 "planned_version_milestone": _display_milestone(version),
                 "planned_version_goal": version.get("version_goal") or "TBD",
+                "planned_version_summary": version.get("version_summary") or "TBD",
                 "planned_version_owner": version.get("owner_user_id") or "TBD",
                 "planned_version_target_start_date": version.get("start_date") or "TBD",
                 "planned_version_target_start_date_note": _planned_start_note(
@@ -765,6 +844,7 @@ def _build_version_snapshot(
                 "fields": [
                     {"name": "version_name", "label": "Version Name", "value": version.get("version_name") or "TBD"},
                     {"name": "version_goal", "label": "Goal", "value": version.get("version_goal") or "TBD"},
+                    {"name": "version_summary", "label": "Version Summary", "value": version.get("version_summary") or "TBD"},
                     {"name": "version_owner", "label": "Owner", "value": version.get("owner_user_id") or "TBD"},
                     {"name": "start_date", "label": "Start Date", "value": version.get("start_date") or "TBD"},
                     {
@@ -875,18 +955,19 @@ def _build_past_version_snapshots_payload(past_versions: list[dict], *, snapshot
     }
 
 
-def _version_snapshot_links(*, documents: list[dict], channel: str | None) -> dict[str, str]:
+def _version_snapshot_links(*, documents: list[dict], provider: str | None) -> dict[str, str]:
     links: dict[str, str] = {}
     for document in sorted(
         documents,
         key=lambda item: (
-            item.get("channel") or "",
+            item.get("provider") or item.get("channel") or "",
             item.get("document_id") or "",
         ),
     ):
         if document.get("doc_kind") != "version_snapshot":
             continue
-        if channel is not None and document.get("channel") != channel:
+        document_provider = document.get("provider") or document.get("channel")
+        if provider is not None and document_provider != provider:
             continue
         version_id = document.get("version_id")
         if not version_id or version_id in links:
@@ -897,17 +978,18 @@ def _version_snapshot_links(*, documents: list[dict], channel: str | None) -> di
     return links
 
 
-def _single_document_link(*, documents: list[dict], doc_kind: str, channel: str | None) -> str:
+def _single_document_link(*, documents: list[dict], doc_kind: str, provider: str | None) -> str:
     for document in sorted(
         documents,
         key=lambda item: (
-            item.get("channel") or "",
+            item.get("provider") or item.get("channel") or "",
             item.get("document_id") or "",
         ),
     ):
         if document.get("doc_kind") != doc_kind:
             continue
-        if channel is not None and document.get("channel") != channel:
+        document_provider = document.get("provider") or document.get("channel")
+        if provider is not None and document_provider != provider:
             continue
         url = document.get("url")
         if url and document.get("last_verified_render_hash"):