campfire-cli 0.1.0__py3-none-any.whl

campfire_cli/app/base/service/base_service.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from campfire_cli.app.base.repository.base_repository import BaseRepository
+from campfire_cli.app.base.schema.base_schema import BaseInfo, BaseResult
+from campfire_cli.common.governance import enrich_issue, optimistic_write_lock
+from campfire_cli.common.hashing import file_sha256, text_sha256
+from campfire_cli.config.defaults import config_section
+from campfire_cli.config.settings import WorkspaceSettings
+
+
+class BaseService:
+    def __init__(self, settings: WorkspaceSettings, repository: BaseRepository) -> None:
+        self._settings = settings
+        self._repository = repository
+
+    def list(self) -> BaseResult:
+        return BaseResult(status="ok", bases=self._bases())
+
+    def show(self, name: str, source: str = "ssot") -> BaseResult:
+        filename = name if name.endswith(".base") else f"{name}.base"
+        root = self._source_root() if source == "ssot" else self._target_root()
+        path = root / filename
+        if not path.is_file():
+            return BaseResult(
+                status="not-found", issues=[{"code": "base-missing", "path": str(path)}]
+            )
+        return BaseResult(
+            status="ok", bases=[self._info(path, root)], content=self._repository.read(path)
+        )
+
+    def check(self) -> BaseResult:
+        bases = self._bases()
+        configured = set(self._managed_names())
+        available = {item.name for item in bases}
+        issues: list[dict[str, str]] = []
+        for name in sorted(configured - available):
+            issues.append({"code": "ssot-base-missing", "path": name})
+        for item in bases:
+            if item.name in configured and item.status != "current":
+                issues.append({"code": "managed-base-not-current", "path": item.path})
+            try:
+                payload = yaml.safe_load(self._repository.read(self._source_root() / item.path))
+                if not isinstance(payload, dict) or not isinstance(payload.get("views"), list):
+                    issues.append({"code": "base-views-missing", "path": item.path})
+            except yaml.YAMLError as exc:
+                issues.append({"code": "base-yaml-invalid", "path": item.path, "detail": str(exc)})
+        return BaseResult(status="ok" if not issues else "needs-review", bases=bases, issues=issues)
+
+    def sync(self, dry_run: bool = False) -> BaseResult:
+        operations: list[dict[str, str]] = []
+        writes: list[tuple[Path, str, str | None]] = []
+        for name in self._managed_names():
+            source = self._source_root() / name
+            if not source.is_file():
+                continue
+            target = self._target_root() / name
+            content = self._repository.read(source)
+            current = self._repository.read(target) if target.is_file() else None
+            if current is not None and self._same_definition(current, content):
+                continue
+            operations.append(
+                {
+                    "action": "update" if target.exists() else "create",
+                    "path": name,
+                    "sha256": text_sha256(content),
+                }
+            )
+            expected = file_sha256(target) if target.is_file() else None
+            writes.append((target, content, expected))
+        if not dry_run and writes:
+            snapshot = {
+                path.relative_to(self._settings.vault_root).as_posix(): expected
+                for path, _content, expected in writes
+            }
+            with optimistic_write_lock(
+                self._settings.state_root, snapshot, self._settings.vault_root
+            ) as changed:
+                if changed:
+                    return BaseResult(
+                        status="blocked",
+                        issues=[
+                            enrich_issue({"code": "concurrent-change", "path": path})
+                            for path in changed
+                        ],
+                    )
+                for target, content, _expected in writes:
+                    self._repository.write(target, content)
+        return BaseResult(status="dry-run" if dry_run else "synced", operations=operations)
+
+    def _bases(self) -> list[BaseInfo]:
+        return [
+            self._info(path, self._source_root())
+            for path in sorted(self._source_root().glob("*.base"))
+        ]
+
+    def _info(self, path: Path, root: Path) -> BaseInfo:
+        payload = yaml.safe_load(self._repository.read(path)) or {}
+        views = [
+            str(view.get("name", "")) for view in payload.get("views", []) if isinstance(view, dict)
+        ]
+        target = self._target_root() / path.name
+        status = "missing-or-stale"
+        if target.is_file() and self._same_definition(
+            self._repository.read(target), self._repository.read(path)
+        ):
+            status = "current"
+        return BaseInfo(
+            name=path.name, path=path.relative_to(root).as_posix(), status=status, views=views
+        )
+
+    def _source_root(self) -> Path:
+        return self._repository.source_root()
+
+    def _target_root(self) -> Path:
+        return self._settings.vault_root / self._settings.bases.get("target", "治理视图")
+
+    def _managed_names(self) -> list[str]:
+        return list(config_section("bases").get("managed_bases", []))
+
+    @staticmethod
+    def _same_definition(left: str, right: str) -> bool:
+        try:
+            return yaml.safe_load(left) == yaml.safe_load(right)
+        except yaml.YAMLError:
+            return left == right

campfire_cli/app/decision/SPEC.md

@@ -0,0 +1,16 @@
+# Decision App SPEC
+
+本模块维护人类或高级 Agent 必须作出的显式判断。调用方不判断交互模式：不能唯一决定时创建 Decision，得到答案后写入并关闭；尚未回答的 Decision 自然跨会话保留。
+
+SQLite 的 `decisions` 保存当前状态，`decision_events` 追加保存审计历史，两者是 Decision 的 SSOT。Vault 中 `_协作/decisions/` 按 `pending/`、`answered/`、`closed/`、`cancelled/` 保存全状态只读投影，目录与状态一一对应。投影可由 `decision sync` 重建，不接受反向写入。
+
+状态机保持最小：
+
+```text
+pending ──answer──> answered ──close──> closed
+   └──────────────cancel─────────────> cancelled
+```
+
+`dedupe_key` 在一个 Workspace 内唯一。重复创建仍处于 `pending` 的同一事项时刷新内容而不产生重复 Decision；已经回答、关闭或取消的 key 不得静默复用。
+
+Decision 不发送通知、不调度 Agent，也不直接修改关联文档。未来 Notification 消费 Decision Event，Task Channel 通过稳定 `decision_id` 关联阻塞和恢复事件。

campfire_cli/app/decision/__init__.py

@@ -0,0 +1 @@
+"""Persistent human/agent decision workflow."""

campfire_cli/app/decision/cli/decision_cli.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+import typer
+
+from campfire_cli.common.exceptions import AppError
+
+decision_cli = typer.Typer(
+    help="维护需要人类或高级 Agent 回答的持久 Decision",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def emit(result: object) -> None:
+    typer.echo(json.dumps(result.model_dump(mode="json"), ensure_ascii=False, indent=2))
+
+
+def invoke(operation: Callable[[], Any]) -> None:
+    try:
+        emit(operation())
+    except AppError as exc:
+        typer.echo(json.dumps({"status": "error", "message": str(exc)}, ensure_ascii=False))
+        raise typer.Exit(exc.exit_code) from exc
+
+
+@decision_cli.command("create")
+def create(
+    ctx: typer.Context,
+    key: str = typer.Option(..., "--key", help="Workspace 内稳定的幂等键"),
+    question: str = typer.Option(..., "--question"),
+    source_type: str = typer.Option(..., "--source-type"),
+    context: str = typer.Option("", "--context"),
+    recommendation: str = typer.Option("", "--recommendation"),
+    option: list[str] | None = typer.Option(None, "--option"),
+    related_document: list[str] | None = typer.Option(None, "--related-document"),
+    source_id: str | None = typer.Option(None, "--source-id"),
+    session_provider: str | None = typer.Option(None, "--session-provider"),
+    session_id: str | None = typer.Option(None, "--session-id"),
+    actor: str | None = typer.Option(None, "--actor"),
+) -> None:
+    """创建或刷新一个仍处于 pending 的幂等 Decision。"""
+    invoke(
+        lambda: ctx.obj.decision.create(
+            key=key,
+            question=question,
+            source_type=source_type,
+            context=context,
+            recommendation=recommendation,
+            options=option,
+            related_documents=related_document,
+            source_id=source_id,
+            session_provider=session_provider,
+            session_id=session_id,
+            actor=actor,
+        )
+    )
+
+
+@decision_cli.command("list")
+def list_decisions(
+    ctx: typer.Context,
+    status: str | None = typer.Option(None, "--status"),
+) -> None:
+    """列出当前 Workspace 的 Decision。"""
+    invoke(lambda: ctx.obj.decision.list(status))
+
+
+@decision_cli.command("show")
+def show(ctx: typer.Context, decision_id: str) -> None:
+    """显示 Decision 当前内容和完整事件历史。"""
+    invoke(lambda: ctx.obj.decision.show(decision_id))
+
+
+@decision_cli.command("answer")
+def answer(
+    ctx: typer.Context,
+    decision_id: str,
+    answer_text: str = typer.Option(..., "--answer"),
+    answered_by: str = typer.Option(..., "--answered-by"),
+) -> None:
+    """回答 pending Decision，并转为 answered。"""
+    invoke(lambda: ctx.obj.decision.answer(decision_id, answer_text, answered_by))
+
+
+@decision_cli.command("close")
+def close(
+    ctx: typer.Context,
+    decision_id: str,
+    actor: str | None = typer.Option(None, "--actor"),
+) -> None:
+    """关闭已经回答且被消费的 Decision。"""
+    invoke(lambda: ctx.obj.decision.close(decision_id, actor))
+
+
+@decision_cli.command("cancel")
+def cancel(
+    ctx: typer.Context,
+    decision_id: str,
+    reason: str = typer.Option(..., "--reason"),
+    actor: str | None = typer.Option(None, "--actor"),
+) -> None:
+    """显式取消不再需要回答的 pending Decision。"""
+    invoke(lambda: ctx.obj.decision.cancel(decision_id, reason, actor))
+
+
+@decision_cli.command("sync")
+def sync(ctx: typer.Context) -> None:
+    """从 SQLite 重建全部 Decision 的 Vault 投影。"""
+    invoke(ctx.obj.decision.sync)

campfire_cli/app/decision/repository/decision_repository.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from campfire_cli.app.decision.schema.decision_schema import DecisionEntry, DecisionEventEntry
+from campfire_cli.common.database.models import Decision, DecisionEvent, utc_now
+from campfire_cli.common.exceptions import GovernanceBlockedError
+
+
+class SqliteDecisionRepository:
+    """Persist Decision snapshots and their append-only audit events atomically."""
+
+    def __init__(self, session: Session, workspace_id: str) -> None:
+        self._session = session
+        self._workspace_id = workspace_id
+
+    def create_or_refresh(
+        self,
+        decision_id: str,
+        values: dict[str, Any],
+        actor: str | None,
+    ) -> DecisionEntry:
+        try:
+            row = self._session.scalar(
+                select(Decision).where(
+                    Decision.workspace_id == self._workspace_id,
+                    Decision.dedupe_key == values["dedupe_key"],
+                )
+            )
+            event_type = "decision.created"
+            if row is None:
+                row = Decision(id=decision_id, workspace_id=self._workspace_id)
+                self._session.add(row)
+            elif row.status != "pending":
+                raise GovernanceBlockedError(
+                    f"Decision key 已经结束，不能静默复用：{values['dedupe_key']}"
+                )
+            else:
+                event_type = "decision.refreshed"
+            self._assign_content(row, values)
+            row.updated_at = utc_now()
+            self._append_event(row, event_type, actor, {"dedupe_key": row.dedupe_key})
+            self._session.commit()
+        except Exception:
+            self._session.rollback()
+            raise
+        return self._entry(row)
+
+    def list(self, status: str | None = None) -> list[DecisionEntry]:
+        statement = select(Decision).where(Decision.workspace_id == self._workspace_id)
+        if status is not None:
+            statement = statement.where(Decision.status == status)
+        statement = statement.order_by(Decision.created_at.desc(), Decision.id)
+        rows = self._session.scalars(statement).all()
+        return [self._entry(row) for row in rows]
+
+    def get(self, decision_id: str) -> DecisionEntry:
+        row = self._row(decision_id)
+        return self._entry(row)
+
+    def events(self, decision_id: str) -> list[DecisionEventEntry]:
+        self._row(decision_id)
+        rows = self._session.scalars(
+            select(DecisionEvent)
+            .where(
+                DecisionEvent.workspace_id == self._workspace_id,
+                DecisionEvent.decision_id == decision_id,
+            )
+            .order_by(DecisionEvent.id)
+        ).all()
+        return [
+            DecisionEventEntry(
+                event_type=row.event_type,
+                actor=row.actor,
+                payload=json.loads(row.payload_json),
+                created_at=row.created_at,
+            )
+            for row in rows
+        ]
+
+    def answer(self, decision_id: str, answer: str, actor: str) -> DecisionEntry:
+        try:
+            row = self._row(decision_id)
+            self._require_status(row, "pending")
+            now = utc_now()
+            row.status = "answered"
+            row.answer = answer
+            row.answered_by = actor
+            row.answered_at = now
+            row.updated_at = now
+            self._append_event(row, "decision.answered", actor, {"answer": answer})
+            self._session.commit()
+        except Exception:
+            self._session.rollback()
+            raise
+        return self._entry(row)
+
+    def close(self, decision_id: str, actor: str | None) -> DecisionEntry:
+        try:
+            row = self._row(decision_id)
+            self._require_status(row, "answered")
+            now = utc_now()
+            row.status = "closed"
+            row.closed_at = now
+            row.updated_at = now
+            self._append_event(row, "decision.closed", actor, {})
+            self._session.commit()
+        except Exception:
+            self._session.rollback()
+            raise
+        return self._entry(row)
+
+    def cancel(self, decision_id: str, reason: str, actor: str | None) -> DecisionEntry:
+        try:
+            row = self._row(decision_id)
+            self._require_status(row, "pending")
+            now = utc_now()
+            row.status = "cancelled"
+            row.cancellation_reason = reason
+            row.closed_at = now
+            row.updated_at = now
+            self._append_event(row, "decision.cancelled", actor, {"reason": reason})
+            self._session.commit()
+        except Exception:
+            self._session.rollback()
+            raise
+        return self._entry(row)
+
+    def _row(self, decision_id: str) -> Decision:
+        row = self._session.get(Decision, decision_id)
+        if row is None or row.workspace_id != self._workspace_id:
+            raise GovernanceBlockedError(f"Decision 不存在：{decision_id}")
+        return row
+
+    @staticmethod
+    def _require_status(row: Decision, expected: str) -> None:
+        if row.status != expected:
+            raise GovernanceBlockedError(
+                f"Decision 状态不允许当前操作：expected={expected}, actual={row.status}"
+            )
+
+    def _append_event(
+        self,
+        row: Decision,
+        event_type: str,
+        actor: str | None,
+        payload: dict[str, Any],
+    ) -> None:
+        self._session.add(
+            DecisionEvent(
+                workspace_id=self._workspace_id,
+                decision_id=row.id,
+                event_type=event_type,
+                actor=actor,
+                payload_json=json.dumps(payload, ensure_ascii=False),
+            )
+        )
+
+    @staticmethod
+    def _assign_content(row: Decision, values: dict[str, Any]) -> None:
+        row.dedupe_key = values["dedupe_key"]
+        row.question = values["question"]
+        row.context = values["context"]
+        row.recommendation = values["recommendation"]
+        row.options_json = json.dumps(values["options"], ensure_ascii=False)
+        row.related_documents_json = json.dumps(values["related_documents"], ensure_ascii=False)
+        row.source_type = values["source_type"]
+        row.source_id = values["source_id"]
+        row.session_provider = values["session_provider"]
+        row.session_id = values["session_id"]
+
+    @staticmethod
+    def _entry(row: Decision) -> DecisionEntry:
+        return DecisionEntry(
+            id=row.id,
+            workspace_id=row.workspace_id,
+            dedupe_key=row.dedupe_key,
+            question=row.question,
+            context=row.context,
+            recommendation=row.recommendation,
+            options=json.loads(row.options_json),
+            related_documents=json.loads(row.related_documents_json),
+            source_type=row.source_type,
+            source_id=row.source_id,
+            session_provider=row.session_provider,
+            session_id=row.session_id,
+            status=row.status,
+            answer=row.answer,
+            answered_by=row.answered_by,
+            cancellation_reason=row.cancellation_reason,
+            created_at=row.created_at,
+            updated_at=row.updated_at,
+            answered_at=row.answered_at,
+            closed_at=row.closed_at,
+        )

campfire_cli/app/decision/schema/decision_schema.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+DecisionStatus = Literal["pending", "answered", "closed", "cancelled"]
+
+
+class DecisionEntry(BaseModel):
+    id: str
+    workspace_id: str
+    dedupe_key: str
+    question: str
+    context: str = ""
+    recommendation: str = ""
+    options: list[str] = Field(default_factory=list)
+    related_documents: list[str] = Field(default_factory=list)
+    source_type: str
+    source_id: str | None = None
+    session_provider: str | None = None
+    session_id: str | None = None
+    status: DecisionStatus = "pending"
+    answer: str | None = None
+    answered_by: str | None = None
+    cancellation_reason: str | None = None
+    created_at: datetime
+    updated_at: datetime
+    answered_at: datetime | None = None
+    closed_at: datetime | None = None
+
+
+class DecisionEventEntry(BaseModel):
+    event_type: str
+    actor: str | None = None
+    payload: dict[str, object] = Field(default_factory=dict)
+    created_at: datetime
+
+
+class DecisionResult(BaseModel):
+    status: str
+    decision: DecisionEntry | None = None
+    events: list[DecisionEventEntry] = Field(default_factory=list)
+    projection_operations: list[dict[str, str]] = Field(default_factory=list)
+
+
+class DecisionListResult(BaseModel):
+    status: str = "ok"
+    decisions: list[DecisionEntry] = Field(default_factory=list)
+
+
+class DecisionSyncResult(BaseModel):
+    status: str
+    pending_count: int
+    operations: list[dict[str, str]] = Field(default_factory=list)

campfire_cli/app/decision/service/decision_projection_service.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from campfire_cli.app.decision.schema.decision_schema import DecisionEntry, DecisionSyncResult
+from campfire_cli.common.filesystem import atomic_write, workspace_write_lock
+from campfire_cli.config.settings import WorkspaceSettings
+
+GENERATED_MARKER = "<!-- AUTO-GENERATED:CAMPFIRE-DECISION -->"
+STATUS_DIRECTORIES = ("pending", "answered", "closed", "cancelled")
+
+
+class DecisionProjectionService:
+    """Project SQLite Decisions into disposable, human-readable Markdown."""
+
+    def __init__(self, settings: WorkspaceSettings) -> None:
+        self._settings = settings
+
+    def sync(self, decisions: list[DecisionEntry]) -> DecisionSyncResult:
+        root = self._projection_root()
+        expected = {self._path(item): self._render(item) for item in decisions}
+        directories = [root / status for status in STATUS_DIRECTORIES]
+        managed = {
+            path
+            for path in root.rglob("Decision-*.md")
+            if GENERATED_MARKER in path.read_text(encoding="utf-8")
+        }
+        operations: list[dict[str, str]] = []
+        for path in directories:
+            if not path.is_dir():
+                operations.append(
+                    {
+                        "action": "create-directory",
+                        "path": path.relative_to(self._settings.vault_root).as_posix(),
+                    }
+                )
+        for path, content in expected.items():
+            current = path.read_text(encoding="utf-8") if path.is_file() else None
+            if current != content:
+                operations.append(
+                    {
+                        "action": "update" if current is not None else "create",
+                        "path": path.relative_to(self._settings.vault_root).as_posix(),
+                    }
+                )
+        for path in sorted(managed - expected.keys()):
+            operations.append(
+                {
+                    "action": "delete-projection",
+                    "path": path.relative_to(self._settings.vault_root).as_posix(),
+                }
+            )
+        if operations:
+            with workspace_write_lock(self._settings.state_root):
+                root.mkdir(parents=True, exist_ok=True)
+                for path in directories:
+                    path.mkdir(parents=True, exist_ok=True)
+                for path, content in expected.items():
+                    if not path.is_file() or path.read_text(encoding="utf-8") != content:
+                        atomic_write(path, content)
+                for path in managed - expected.keys():
+                    path.unlink()
+        return DecisionSyncResult(
+            status="synced",
+            pending_count=sum(item.status == "pending" for item in decisions),
+            operations=operations,
+        )
+
+    def _projection_root(self) -> Path:
+        return self._settings.vault_root / "_协作" / "decisions"
+
+    def _path(self, decision: DecisionEntry) -> Path:
+        return self._projection_root() / decision.status / f"Decision-{decision.id}.md"
+
+    @staticmethod
+    def _render(decision: DecisionEntry) -> str:
+        title = DecisionProjectionService._title(decision.question)
+        answered_at = decision.answered_at.isoformat() if decision.answered_at else None
+        closed_at = decision.closed_at.isoformat() if decision.closed_at else None
+        lines = [
+            "---",
+            f"name: {json.dumps(title, ensure_ascii=False)}",
+            "object_type: decision",
+            f"decision_id: {decision.id}",
+            f"decision_status: {decision.status}",
+            f"source_type: {json.dumps(decision.source_type, ensure_ascii=False)}",
+            f"source_id: {json.dumps(decision.source_id, ensure_ascii=False)}",
+            f"answered_by: {json.dumps(decision.answered_by, ensure_ascii=False)}",
+            f"created_at: {decision.created_at.isoformat()}",
+            f"updated_at: {decision.updated_at.isoformat()}",
+            f"answered_at: {json.dumps(answered_at)}",
+            f"closed_at: {json.dumps(closed_at)}",
+            "---",
+            "",
+            GENERATED_MARKER,
+            "",
+            f"# {title}",
+            "",
+            "> 此文档由 Campfire 根据 SQLite Decision 自动生成。"
+            "请通过 `campfire decision answer` 回答，不要手工修改。",
+            "",
+            f"- Decision ID：`{decision.id}`",
+            f"- 来源：`{decision.source_type}`",
+            f"- 来源对象：`{decision.source_id or '-'}`",
+            f"- 来源 Session：`{decision.session_provider or '-'} / {decision.session_id or '-'}`",
+            "",
+            "## 问题",
+            "",
+            decision.question,
+        ]
+        if decision.context:
+            lines.extend(["", "## 背景与已确认事实", "", decision.context])
+        if decision.options:
+            lines.extend(["", "## 可选方案", ""])
+            lines.extend(f"- {option}" for option in decision.options)
+        if decision.recommendation:
+            lines.extend(["", "## Agent 建议", "", decision.recommendation])
+        if decision.related_documents:
+            lines.extend(["", "## 关联文档", ""])
+            lines.extend(f"- `{path}`" for path in decision.related_documents)
+        if decision.answer:
+            lines.extend(
+                [
+                    "",
+                    "## 回答",
+                    "",
+                    decision.answer,
+                    "",
+                    f"回答者：`{decision.answered_by or '-'}`",
+                ]
+            )
+        elif decision.status == "pending":
+            lines.extend(
+                [
+                    "",
+                    "## 回答方式",
+                    "",
+                    "```bash",
+                    f"campfire decision answer {decision.id} "
+                    '--answer "<回答>" --answered-by "<回答者>"',
+                    "```",
+                ]
+            )
+        lines.append("")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _title(question: str) -> str:
+        compact = " ".join(question.split())
+        return compact if len(compact) <= 48 else compact[:47] + "…"