campfire-cli 0.1.1__tar.gz → 0.1.3__tar.gz

{campfire_cli-0.1.1 → campfire_cli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: campfire-cli
-Version: 0.1.1
+Version: 0.1.3
 Summary: Local-first shared context and governance CLI for humans and agents
 License-Expression: MIT
 License-File: LICENSE
@@ -32,7 +32,18 @@ Vault 根目录的 `.campfire.yaml` 是可跨设备同步的 Workspace/Project
 
 ## 安装与调用
 
-开发机安装：
+标准安装（已发布至 PyPI，无需源码仓库）：
+
+```bash
+uv tool install campfire-cli
+campfire version
+```
+
+升级使用 `uv tool upgrade campfire-cli`（或 `pipx upgrade campfire-cli`），随后运行 `campfire upgrade`（别名 `campfire update`）对齐本机治理资源：SQLite Schema 迁移、全局 Skill、Base 与全局提示词路标。
+
+`campfire setup` 初始化时会向 `~/.claude/CLAUDE.md` 与 `~/.agents/AGENTS.md` 注入 campfire 路标块（幂等、带注释标记、不触碰块外内容；可用 `CAMPFIRE_AGENT_HINT_PATH` 覆盖目标文件列表），让 Agent 冷启动时知道本机装有 campfire。
+
+开发机安装（跟随本地源码）：
 
 ```bash
 uv tool install --editable /path/to/campfire-cli

{campfire_cli-0.1.1 → campfire_cli-0.1.3}/README.md

@@ -16,7 +16,18 @@ Vault 根目录的 `.campfire.yaml` 是可跨设备同步的 Workspace/Project
 
 ## 安装与调用
 
-开发机安装：
+标准安装（已发布至 PyPI，无需源码仓库）：
+
+```bash
+uv tool install campfire-cli
+campfire version
+```
+
+升级使用 `uv tool upgrade campfire-cli`（或 `pipx upgrade campfire-cli`），随后运行 `campfire upgrade`（别名 `campfire update`）对齐本机治理资源：SQLite Schema 迁移、全局 Skill、Base 与全局提示词路标。
+
+`campfire setup` 初始化时会向 `~/.claude/CLAUDE.md` 与 `~/.agents/AGENTS.md` 注入 campfire 路标块（幂等、带注释标记、不触碰块外内容；可用 `CAMPFIRE_AGENT_HINT_PATH` 覆盖目标文件列表），让 Agent 冷启动时知道本机装有 campfire。
+
+开发机安装（跟随本地源码）：
 
 ```bash
 uv tool install --editable /path/to/campfire-cli

{campfire_cli-0.1.1 → campfire_cli-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "campfire-cli"
-version = "0.1.1"
+version = "0.1.3"
 description = "Local-first shared context and governance CLI for humans and agents"
 readme = "README.md"
 license = "MIT"

{campfire_cli-0.1.1 → campfire_cli-0.1.3}/src/campfire_cli/__init__.py

@@ -1,3 +1,3 @@
 """Campfire CLI package."""
 
-__version__ = "0.1.1"
+__version__ = "0.1.3"

campfire_cli-0.1.3/src/campfire_cli/common/agent_hints.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from campfire_cli.common.filesystem import atomic_write
+
+HINT_START = "<!-- campfire:agent-hints:start -->"
+HINT_END = "<!-- campfire:agent-hints:end -->"
+
+HINT_BODY = """## Campfire 文档治理
+
+本机装有 campfire CLI（`campfire --help`），Obsidian Vault 已注册为文档工作区。
+当用户要求"沉淀/记录/写文档/归档/跟踪问题"到知识库或项目文档时，先运行
+`campfire workspace resolve` 解析工作区，再按 campfire skill 流程处理；
+不要直接在代码仓库里创建笔记文件。文档分类不确定时用"记录-"前缀兜底，
+字段规则以 `campfire document inspect` 返回的有效 Profile 为准。"""
+
+
+def default_hint_paths() -> list[Path]:
+    override = os.environ.get("CAMPFIRE_AGENT_HINT_PATH")
+    if override:
+        return [Path(item).expanduser().resolve() for item in override.split(os.pathsep) if item]
+    home = Path.home()
+    return [home / ".claude" / "CLAUDE.md", home / ".agents" / "AGENTS.md"]
+
+
+def render_hint_block() -> str:
+    return f"{HINT_START}\n{HINT_BODY}\n{HINT_END}"
+
+
+def inject_agent_hint(path: Path) -> str:
+    """幂等地向 path 写入 campfire 路标块，返回 created/appended/updated/kept。
+
+    块由 HTML 注释标记包围；已存在时整体替换以升级内容，块外用户内容不动。
+    """
+    block = render_hint_block()
+    current = path.read_text(encoding="utf-8") if path.is_file() else ""
+    if HINT_START in current and HINT_END in current:
+        start = current.index(HINT_START)
+        end = current.index(HINT_END) + len(HINT_END)
+        updated = current[:start] + block + current[end:]
+        action = "updated" if updated != current else "kept"
+    elif current:
+        separator = "" if current.endswith("\n\n") else ("\n" if current.endswith("\n") else "\n\n")
+        updated = current + separator + block + "\n"
+        action = "appended"
+    else:
+        updated = block + "\n"
+        action = "created"
+    if action != "kept":
+        atomic_write(path, updated)
+    return action

{campfire_cli-0.1.1 → campfire_cli-0.1.3}/src/campfire_cli/container.py

@@ -28,6 +28,7 @@ from campfire_cli.app.workspace.service.domain_restructure_service import (
 )
 from campfire_cli.app.workspace.service.restructure_service import RestructureService
 from campfire_cli.app.workspace.service.workspace_service import WorkspaceService
+from campfire_cli.common.agent_hints import default_hint_paths, inject_agent_hint
 from campfire_cli.common.database import create_sqlite_engine, open_session, upgrade_database
 from campfire_cli.common.exceptions import ConfigurationError
 from campfire_cli.config.defaults import effective_config
@@ -60,10 +61,40 @@ class AppContainer:
                 "config": WorkspaceConfigService(settings).check().model_dump(mode="json"),
                 "skills": container.skill.sync(dry_run=False).model_dump(mode="json"),
                 "bases": container.base.sync(dry_run=False).model_dump(mode="json"),
+                "agent_hints": cls._inject_hints(),
             },
             "health": container.maintenance.check(summary=True).model_dump(mode="json"),
         }
 
+    @classmethod
+    def upgrade(cls) -> dict:
+        """对齐本机治理资源与当前包版本：Schema 迁移、Skill、Base 与提示词路标。"""
+        home = campfire_home()
+        upgrade_database(home / "campfire.db")
+        workspaces = []
+        for workspace_id in SqliteWorkspaceRepository(home).load_registry().workspaces:
+            container = cls.build(workspace_id)
+            workspaces.append(
+                {
+                    "workspace_id": workspace_id,
+                    "bases": container.base.sync(dry_run=False).model_dump(mode="json"),
+                }
+            )
+        return {
+            "status": "ok",
+            "database": {"status": "up-to-date"},
+            "skills": cls.build_skill().sync(dry_run=False).model_dump(mode="json"),
+            "agent_hints": cls._inject_hints(),
+            "workspaces": workspaces,
+        }
+
+    @staticmethod
+    def _inject_hints() -> list[dict[str, str]]:
+        return [
+            {"path": str(path), "action": inject_agent_hint(path)}
+            for path in default_hint_paths()
+        ]
+
     @classmethod
     def build_skill(cls) -> SkillService:
         """Build the global Skill service without requiring a registered Workspace."""

{campfire_cli-0.1.1 → campfire_cli-0.1.3}/src/campfire_cli/main.py

@@ -121,13 +121,63 @@ def tree(ctx: typer.Context) -> None:
 
 @app.command("setup")
 def setup(
-    workspace: Path = typer.Option(..., "--workspace", help="要初始化的 Workspace 根目录"),
+    workspace: Path | None = typer.Option(
+        None, "--workspace", help="要初始化的 Workspace 根目录；缺省时输出接入引导"
+    ),
     make_default: bool = typer.Option(False, "--default", help="设为默认 Workspace"),
 ) -> None:
     """从 .campfire.yaml 配置本机，或为已注册 Workspace 创建首份 Manifest。"""
+    if workspace is None:
+        typer.echo(
+            json.dumps(
+                {
+                    "status": "needs-input",
+                    "message": "需要指定 Vault 根目录；按场景选择以下入口之一",
+                    "paths": [
+                        {
+                            "scenario": "接入已有 Vault（目录已存在，含或不含 .campfire.yaml）",
+                            "command": "campfire setup --workspace <vault路径> --default",
+                        },
+                        {
+                            "scenario": "从零创建新 Workspace（初始化目录结构并注册）",
+                            "command": (
+                                "campfire workspace create --id <id> --path <路径> --default"
+                            ),
+                        },
+                        {
+                            "scenario": "暂不接入 Vault，仅安装全局资源（Skill 与提示词路标）",
+                            "command": "campfire upgrade",
+                        },
+                    ],
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+        return
     try:
         result = AppContainer.setup(workspace, make_default)
     except AppError as exc:
         typer.echo(json.dumps({"status": "error", "message": str(exc)}, ensure_ascii=False))
         raise typer.Exit(exc.exit_code) from exc
     typer.echo(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+@app.command("upgrade")
+def upgrade() -> None:
+    """升级本机治理资源：SQLite Schema 迁移、全局 Skill、Base 与提示词路标。"""
+    try:
+        result = AppContainer.upgrade()
+    except AppError as exc:
+        typer.echo(
+            json.dumps({"status": "error", "message": str(exc)}, ensure_ascii=False),
+            err=True,
+        )
+        raise typer.Exit(exc.exit_code) from exc
+    typer.echo(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+@app.command("update", hidden=True)
+def update() -> None:
+    """campfire upgrade 的等价别名。"""
+    upgrade()

{campfire_cli-0.1.1 → campfire_cli-0.1.3}/tests/conftest.py

@@ -8,6 +8,12 @@ from campfire_cli.app.workspace.repository.workspace_repository import SqliteWor
 from campfire_cli.app.workspace.schema.workspace_schema import WorkspaceEntry, WorkspaceRegistry
 
 
+@pytest.fixture(autouse=True)
+def _isolate_agent_hints(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """所有测试的提示词注入一律落在临时目录，绝不触碰用户真实全局文件。"""
+    monkeypatch.setenv("CAMPFIRE_AGENT_HINT_PATH", str(tmp_path / "agent-hints"))
+
+
 @pytest.fixture
 def workspace(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
     campfire_home = tmp_path / "_campfire"

{campfire_cli-0.1.1 → campfire_cli-0.1.3}/tests/integration/test_cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 from pathlib import Path
 
@@ -2097,3 +2098,63 @@ def test_project_resolve_does_not_match_by_shared_remote_alone(
     )
     assert within["status"] == "matched"
     assert within["matches"][0]["project"]["id"] == "registered-app"
+
+
+def test_setup_injects_agent_hints_idempotently(
+    workspace: Path, monkeypatch
+) -> None:
+    claude_md = workspace / "CLAUDE.md"
+    agents_md = workspace / "AGENTS.md"
+    monkeypatch.setenv(
+        "CAMPFIRE_AGENT_HINT_PATH", f"{claude_md}{os.pathsep}{agents_md}"
+    )
+    first = runner.invoke(app, ["setup", "--workspace", str(workspace)])
+    assert first.exit_code == 0, first.output
+    payload = json.loads(first.output)
+    actions = payload["resources"]["agent_hints"]
+    assert {item["action"] for item in actions} == {"created"}
+    for item in [claude_md, agents_md]:
+        assert "campfire:agent-hints:start" in item.read_text(encoding="utf-8")
+
+    second = runner.invoke(app, ["setup", "--workspace", str(workspace)])
+    assert second.exit_code == 0, second.output
+    assert {
+        item["action"] for item in json.loads(second.output)["resources"]["agent_hints"]
+    } == {"kept"}
+
+
+def test_upgrade_syncs_resources_and_accepts_update_alias(
+    workspace: Path, monkeypatch
+) -> None:
+    claude_md = workspace / "CLAUDE.md"
+    monkeypatch.setenv("CAMPFIRE_AGENT_HINT_PATH", str(claude_md))
+    stale = workspace / "_global_skills" / "campfire-document-capture" / "SKILL.md"
+    result = runner.invoke(app, ["upgrade"])
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["status"] == "ok"
+    assert payload["database"]["status"] == "up-to-date"
+    assert payload["skills"]["status"] == "synced"
+    assert payload["agent_hints"][0]["action"] == "created"
+    assert [item["workspace_id"] for item in payload["workspaces"]] == ["test"]
+    assert stale.is_file()
+    stale.write_text("过时内容\n", encoding="utf-8")
+
+    alias = runner.invoke(app, ["update"])
+    assert alias.exit_code == 0, alias.output
+    aliased = json.loads(alias.output)
+    assert aliased["skills"]["status"] == "synced"
+    assert aliased["agent_hints"][0]["action"] == "kept"
+    assert stale.read_text(encoding="utf-8") != "过时内容\n"
+
+
+def test_setup_without_workspace_prints_guidance(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setenv("CAMPFIRE_HOME", str(tmp_path / "home"))
+    result = runner.invoke(app, ["setup"])
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["status"] == "needs-input"
+    commands = {item["command"] for item in payload["paths"]}
+    assert "campfire setup --workspace <vault路径> --default" in commands
+    assert any("workspace create" in command for command in commands)
+    assert any("upgrade" in command for command in commands)

campfire_cli-0.1.3/tests/unit/test_agent_hints.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from campfire_cli.common.agent_hints import (
+    HINT_END,
+    HINT_START,
+    inject_agent_hint,
+)
+
+
+def test_inject_creates_then_keeps(tmp_path: Path) -> None:
+    target = tmp_path / "CLAUDE.md"
+    assert inject_agent_hint(target) == "created"
+    content = target.read_text(encoding="utf-8")
+    assert content.startswith(HINT_START)
+    assert content.endswith(HINT_END + "\n")
+    assert inject_agent_hint(target) == "kept"
+
+
+def test_inject_appends_without_touching_existing_content(tmp_path: Path) -> None:
+    target = tmp_path / "CLAUDE.md"
+    original = "# 我的规范\n\n- 保持原样\n"
+    target.write_text(original, encoding="utf-8")
+    assert inject_agent_hint(target) == "appended"
+    content = target.read_text(encoding="utf-8")
+    assert content.startswith(original)
+    assert HINT_END in content
+
+
+def test_inject_replaces_stale_block_only(tmp_path: Path) -> None:
+    target = tmp_path / "CLAUDE.md"
+    stale = f"# 头部\n\n{HINT_START}\n旧内容\n{HINT_END}\n# 尾部\n"
+    target.write_text(stale, encoding="utf-8")
+    assert inject_agent_hint(target) == "updated"
+    content = target.read_text(encoding="utf-8")
+    assert "旧内容" not in content
+    assert content.startswith("# 头部")
+    assert content.endswith("# 尾部\n")

{campfire_cli-0.1.1 → campfire_cli-0.1.3}/uv.lock

@@ -36,7 +36,7 @@ wheels = [
 
 [[package]]
 name = "campfire-cli"
-version = "0.1.1"
+version = "0.1.3"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },