powerquant-cli 0.2.7__tar.gz → 0.2.10__tar.gz

{powerquant_cli-0.2.7 → powerquant_cli-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: powerquant-cli
-Version: 0.2.7
+Version: 0.2.10
 Summary: Power Quant local research CLI
 Project-URL: Repository, https://github.com/Kepler452Byte/power-quant
 License-Expression: LicenseRef-PowerQuant-Proprietary AND MIT
@@ -14,6 +14,7 @@ Requires-Dist: numpy<3,>=2
 Requires-Dist: pandas<4,>=3
 Requires-Dist: polars<2,>=1.36
 Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: pyyaml<7,>=6
 Requires-Dist: scipy<2,>=1.17
 Requires-Dist: typer>=0.27.2
 Requires-Dist: tzdata>=2026.3
@@ -51,7 +52,7 @@ pq config show
 
 家庭 LAN 可配置 `http://192.168.8.142:18026/market/api/v1`；公网 IP 临时入口为 `http://82.157.167.33/market/api/v1`。公网 HTTP 会明文传输 Token，只适合已明确接受风险的临时接入；长期公网访问使用可信 HTTPS 或 SSH/WireGuard 加密链路。直接使用 `https://82.157.167.33` 与现有域名证书不匹配。
 
-配置保存在当前系统用户的 `~/.powerquant/config.json`，与工作目录无关，不自动加载 `.env`。这是本地明文配置：POSIX 新目录权限 700、文件权限 600；Windows 依赖用户目录 ACL，不声称加密存储。不要提交或分享该文件。
+配置保存在当前系统用户的 `~/.powerquant/config.yml`，与工作目录无关，不自动加载 `.env`。这是本地明文配置：POSIX 新目录权限 700、文件权限 600；Windows 依赖用户目录 ACL，不声称加密存储。不要提交或分享该文件。
 
 每项配置按环境变量 > 用户文件 > 默认值解析。默认地址为 `http://localhost:8002/api/v1`，默认 Token 为空。环境变量只影响当前终端及其启动的子进程，不改文件；显式空 Token 环境变量会覆盖已保存密钥。
 
@@ -77,10 +78,32 @@ cd powerquant-examples/selection
 pq data prepare --config prepare.json
 ```
 
-按实际覆盖调整 prepare.json 的股票和日期，将返回 manifest_path 写入 compute.json、select.json；按示例 README 执行 compute、select 和 backtest。不同使用目的的快照须分别通过完整性检查。
+按实际覆盖调整 prepare.json 的股票和日期，将返回的 data.manifest_path 写入 compute.json、select.json；按示例 README 执行 compute、select 和 backtest。不同使用目的的快照须分别通过完整性检查。
 
 密钥到期或撤销后在线准备会失败，已下载快照仍可离线使用。行情密钥不用于定义发布；发布定义另使用 PQ_QUANT_URL/PQ_QUANT_TOKEN。默认本地目录为 ~/.powerquant。
 
+## Agent 使用
+
+命令结果统一输出 JSON `{status,data}`；错误以 JSON 写入 stderr，保留业务错误码、消息和 request_id，并返回非零退出码。
+
+```sh
+pq --version
+pq skill list
+pq skill show pq-bootstrap
+pq skill check
+pq init
+```
+
+`pq init` 先返回安装计划。使用返回的 `data.expected_plan` 执行 `pq init --confirm --expected-plan <expected_plan>`，默认安装到 Codex 的 `~/.agents/skills` 和 Claude Code 的 `~/.claude/skills`。可用 `--agent codex|claude|both` 选择客户端，或用 `--skills-dir` 指定项目目录。Hint 仅写入显式提供的 `--hint-file`，保留受管块外的内容。
+
+没有 Token 也可以初始化；需要连接行情时，按 bootstrap Skill 申请权限并通过 `pq config token` 安全录入。行情运维通过 PQData API/MCP 提交任务。
+
+`pq upgrade` 先预览，再用 `--confirm --expected-plan <expected_plan>` 启动后台升级；通过 `pq agent upgrade-status <operation_id>` 查询结果。升级沿用 uv tool 或 pipx 安装渠道，并同步已登记的资源目录。`pq upgrade --skip-package` 仅同步资源。独立资源同步使用 `pq agent sync`，同样先预览再确认。
+
+## 依赖生命周期
+
+ApplicationContainer 接收 ApplicationSettings，按需组装明确的因子、回测、研究应用 Service，CLI 从 ctx.obj 获取。Service 依赖由构造函数显式传入；不维护通用 Repository 缓存、不查询全局容器、不在缺少上下文时静默创建容器。MarketClient 按需创建并由调用方 async with 关闭，本地 Repository 使用短事务。配置、帮助和资源查看不初始化数据库或联网。
+
 ## Python
 
 公开请求模型与调用入口位于 quant_cli.api，与 CLI 使用同一应用服务。

{powerquant_cli-0.2.7 → powerquant_cli-0.2.10}/README.md

@@ -30,7 +30,7 @@ pq config show
 
 家庭 LAN 可配置 `http://192.168.8.142:18026/market/api/v1`；公网 IP 临时入口为 `http://82.157.167.33/market/api/v1`。公网 HTTP 会明文传输 Token，只适合已明确接受风险的临时接入；长期公网访问使用可信 HTTPS 或 SSH/WireGuard 加密链路。直接使用 `https://82.157.167.33` 与现有域名证书不匹配。
 
-配置保存在当前系统用户的 `~/.powerquant/config.json`，与工作目录无关，不自动加载 `.env`。这是本地明文配置：POSIX 新目录权限 700、文件权限 600；Windows 依赖用户目录 ACL，不声称加密存储。不要提交或分享该文件。
+配置保存在当前系统用户的 `~/.powerquant/config.yml`，与工作目录无关，不自动加载 `.env`。这是本地明文配置：POSIX 新目录权限 700、文件权限 600；Windows 依赖用户目录 ACL，不声称加密存储。不要提交或分享该文件。
 
 每项配置按环境变量 > 用户文件 > 默认值解析。默认地址为 `http://localhost:8002/api/v1`，默认 Token 为空。环境变量只影响当前终端及其启动的子进程，不改文件；显式空 Token 环境变量会覆盖已保存密钥。
 
@@ -56,10 +56,32 @@ cd powerquant-examples/selection
 pq data prepare --config prepare.json
 ```
 
-按实际覆盖调整 prepare.json 的股票和日期，将返回 manifest_path 写入 compute.json、select.json；按示例 README 执行 compute、select 和 backtest。不同使用目的的快照须分别通过完整性检查。
+按实际覆盖调整 prepare.json 的股票和日期，将返回的 data.manifest_path 写入 compute.json、select.json；按示例 README 执行 compute、select 和 backtest。不同使用目的的快照须分别通过完整性检查。
 
 密钥到期或撤销后在线准备会失败，已下载快照仍可离线使用。行情密钥不用于定义发布；发布定义另使用 PQ_QUANT_URL/PQ_QUANT_TOKEN。默认本地目录为 ~/.powerquant。
 
+## Agent 使用
+
+命令结果统一输出 JSON `{status,data}`；错误以 JSON 写入 stderr，保留业务错误码、消息和 request_id，并返回非零退出码。
+
+```sh
+pq --version
+pq skill list
+pq skill show pq-bootstrap
+pq skill check
+pq init
+```
+
+`pq init` 先返回安装计划。使用返回的 `data.expected_plan` 执行 `pq init --confirm --expected-plan <expected_plan>`，默认安装到 Codex 的 `~/.agents/skills` 和 Claude Code 的 `~/.claude/skills`。可用 `--agent codex|claude|both` 选择客户端，或用 `--skills-dir` 指定项目目录。Hint 仅写入显式提供的 `--hint-file`，保留受管块外的内容。
+
+没有 Token 也可以初始化；需要连接行情时，按 bootstrap Skill 申请权限并通过 `pq config token` 安全录入。行情运维通过 PQData API/MCP 提交任务。
+
+`pq upgrade` 先预览，再用 `--confirm --expected-plan <expected_plan>` 启动后台升级；通过 `pq agent upgrade-status <operation_id>` 查询结果。升级沿用 uv tool 或 pipx 安装渠道，并同步已登记的资源目录。`pq upgrade --skip-package` 仅同步资源。独立资源同步使用 `pq agent sync`，同样先预览再确认。
+
+## 依赖生命周期
+
+ApplicationContainer 接收 ApplicationSettings，按需组装明确的因子、回测、研究应用 Service，CLI 从 ctx.obj 获取。Service 依赖由构造函数显式传入；不维护通用 Repository 缓存、不查询全局容器、不在缺少上下文时静默创建容器。MarketClient 按需创建并由调用方 async with 关闭，本地 Repository 使用短事务。配置、帮助和资源查看不初始化数据库或联网。
+
 ## Python
 
 公开请求模型与调用入口位于 quant_cli.api，与 CLI 使用同一应用服务。

{powerquant_cli-0.2.7 → powerquant_cli-0.2.10}/bundled/pqdata/client.py

@@ -30,6 +30,7 @@ from pqdata.schema.reference_schema import (
     TradingRuleResponse,
 )
 from pqdata.schema.reliability_schema import DatasetHealthResult
+from pqdata.schema.snapshot_schema import PREPARATION_DATASETS, DatasetSnapshot, SnapshotQuery
 
 
 class MarketClient:
@@ -101,12 +102,50 @@ class MarketClient:
             await response.aclose()
             await asyncio.sleep(delay)
         if not response.is_success:
-            raise MarketAPIError(response.status_code, response.headers.get("x-request-id"))
+            code: str | int | None = None
+            message: str | None = None
+            request_id = response.headers.get("x-request-id")
+            if "application/json" in response.headers.get("content-type", ""):
+                try:
+                    error = response.json()
+                except ValueError:
+                    error = None
+                if isinstance(error, dict):
+                    candidate = error.get("error_code", error.get("code"))
+                    if isinstance(candidate, (str, int)) and not isinstance(candidate, bool):
+                        code = candidate
+                    candidate = error.get("message")
+                    if isinstance(candidate, str) and 0 < len(candidate) <= 512:
+                        message = candidate
+                    candidate = error.get("request_id")
+                    if isinstance(candidate, str) and len(candidate) <= 128:
+                        request_id = request_id or candidate
+            raise MarketAPIError(response.status_code, request_id, code=code, message=message)
         try:
             return TypeAdapter(response_type).validate_json(response.content)
         except ValidationError as error:
             raise MarketProtocolError("Invalid market response") from error
 
+    async def resolve_snapshot(
+        self,
+        datasets: list[str],
+        *,
+        instrument_ids: list[str] | None = None,
+        start: date | None = None,
+        end: date | None = None,
+    ) -> DatasetSnapshot:
+        query = SnapshotQuery(
+            datasets=datasets, instrument_ids=instrument_ids or [], start=start, end=end
+        )
+        return await self._request(
+            "POST", "snapshots/resolve", DatasetSnapshot, body=query.model_dump(mode="json")
+        )
+
+    async def inspect_snapshot(self, snapshot_id: str) -> DatasetSnapshot:
+        return await self._request(
+            "GET", f"snapshots/{quote(snapshot_id, safe='')}", DatasetSnapshot
+        )
+
     async def get_instrument(self, instrument_id: str) -> InstrumentResponse:
         return await self._request(
             "GET",
@@ -115,6 +154,9 @@ class MarketClient:
         )
 
     async def get_history_facts(self, query: HistoryFactsQuery) -> HistoryFacts:
+        if query.revision is None:
+            snapshot = await self.resolve_snapshot(PREPARATION_DATASETS)
+            query = query.model_copy(update={"revision": snapshot.snapshot_id})
         result = await self._request(
             "POST", "history/facts", HistoryFacts, body=query.model_dump(mode="json")
         )
@@ -170,8 +212,11 @@ class MarketClient:
         frequency: str,
         start: datetime,
         end: datetime,
+        *,
+        revision: str,
     ) -> DatasetHealthResult:
         query = DataHealthQuery(
+            revision=revision,
             instrument_id=instrument_id,
             frequency=TypeAdapter(BarFrequency).validate_python(frequency),
             start=start,
@@ -187,8 +232,11 @@ class MarketClient:
         frequency: str,
         start: datetime,
         end: datetime,
+        *,
+        revision: str,
     ) -> DatasetHealthResult:
         query = DataHealthQuery(
+            revision=revision,
             instrument_id=instrument_id,
             frequency=TypeAdapter(BarFrequency).validate_python(frequency),
             start=start,
@@ -206,8 +254,12 @@ class MarketClient:
         instrument_id: str,
         start: datetime,
         end: datetime,
+        *,
+        revision: str,
     ) -> DatasetHealthResult:
-        query = DataHealthQuery(instrument_id=instrument_id, start=start, end=end)
+        query = DataHealthQuery(
+            revision=revision, instrument_id=instrument_id, start=start, end=end
+        )
         return await self._request(
             "POST",
             "verify/corporate-actions",
@@ -215,23 +267,13 @@ class MarketClient:
             body=query.model_dump(mode="json"),
         )
 
-    async def snapshot(self, start: date, end: date) -> dict[str, str]:
-        return await self._request(
-            "GET",
-            "revisions",
-            dict[str, str],
-            params={
-                "start": start.isoformat(),
-                "end": end.isoformat(),
-            },
-        )
-
     async def search_instruments(
         self,
         keyword: str | None = None,
         instrument_type: str | None = None,
         exchange: str | None = None,
         limit: int = 100,
+        revision: str | None = None,
     ) -> list[InstrumentResponse]:
         params = {
             key: value
@@ -243,6 +285,8 @@ class MarketClient:
             }.items()
             if value is not None
         }
+        if revision is not None:
+            params["revision"] = revision
         return await self._request("GET", "instruments", list[InstrumentResponse], params=params)
 
     async def list_instruments_on(
@@ -337,6 +381,9 @@ class MarketClient:
 
     async def query_bars(self, query: BarQuery) -> BarPage:
         """读取一页数据；错误内容不混入行情结果。"""
+        if query.revision is None:
+            snapshot = await self.resolve_snapshot(["bar"])
+            query = query.model_copy(update={"revision": snapshot.snapshot_id})
         page = await self._request(
             "POST", "bars/query", BarPage, body=query.model_dump(mode="json")
         )
@@ -359,6 +406,9 @@ class MarketClient:
 
     async def describe_bars(self, query: BarQuery) -> BarContent:
         """只传输范围摘要；服务端仍需扫描数据，不能视为常数成本的查询。"""
+        if query.revision is None:
+            snapshot = await self.resolve_snapshot(["bar"])
+            query = query.model_copy(update={"revision": snapshot.snapshot_id})
         if query.cursor is not None:
             raise ValueError("Content queries must start at the first page")
         result = await self._request(

{powerquant_cli-0.2.7 → powerquant_cli-0.2.10}/bundled/pqdata/exceptions.py

@@ -4,10 +4,14 @@
 class MarketAPIError(Exception):
     """服务拒绝请求；保留状态码和可追踪的请求 ID，不暴露凭据。"""
 
-    def __init__(self, status_code: int, request_id: str | None = None) -> None:
+    def __init__(self, status_code: int, request_id: str | None = None,
+                 *, code: str | int | None = None, message: str | None = None) -> None:
         self.status_code = status_code
         self.request_id = request_id
-        super().__init__(f"Market request failed (HTTP {status_code}, request_id={request_id})")
+        self.code = code if code is not None else f"HTTP_{status_code}"
+        self.message = message or f"行情请求失败（HTTP {status_code}）"
+        super().__init__(self.message)
+
 
 
 class MarketProtocolError(Exception):

{powerquant_cli-0.2.7 → powerquant_cli-0.2.10}/bundled/pqdata/schema/query_schema.py

@@ -47,6 +47,7 @@ class PITWindowQuery(BaseModel):
 
 
 class DataHealthQuery(BaseModel):
+    revision: str
     instrument_id: str
     frequency: BarFrequency = "1d"
     start: AwareDatetime

powerquant_cli-0.2.10/bundled/pqdata/schema/snapshot_schema.py

@@ -0,0 +1,50 @@
+"""固定的数据集版本组合；内容身份和覆盖凭证独立表达。"""
+
+from datetime import date
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+PREPARATION_DATASETS = [
+    "bar",
+    "instrument",
+    "trading_calendar",
+    "trading_rule",
+    "instrument_daily_fact",
+    "adjustment_factor",
+    "corporate_action",
+]
+
+
+class SnapshotQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    datasets: list[str] = Field(min_length=1, max_length=9)
+    instrument_ids: list[str] = Field(default_factory=list, max_length=10000)
+    start: date | None = None
+    end: date | None = None
+
+    @model_validator(mode="after")
+    def scoped(self) -> "SnapshotQuery":
+        if (self.start is None) != (self.end is None):
+            raise ValueError("start 和 end 必须同时提供")
+        if self.start is not None and self.end is not None:
+            if not self.instrument_ids or not 0 <= (self.end - self.start).days <= 3660:
+                raise ValueError("范围解析需要标的及不超过十年的有效日期区间")
+            if not {"instrument", "trading_calendar"}.issubset(self.datasets):
+                raise ValueError("范围解析需要标的和交易日历数据集")
+        elif self.instrument_ids:
+            raise ValueError("标的范围需要日期区间")
+        return self
+
+
+class DatasetVersionInfo(BaseModel):
+    rules_version: int = Field(ge=1)
+    contract_version: int = Field(ge=1)
+    version_id: str
+    root_hash: str
+    coverage: dict
+
+
+class DatasetSnapshot(BaseModel):
+    snapshot_id: str
+    root_hash: str
+    datasets: dict[str, DatasetVersionInfo]

{powerquant_cli-0.2.7 → powerquant_cli-0.2.10}/examples/full_market_screen.py

@@ -43,8 +43,10 @@ async def run(day: date, output: Path, minimum_amount: Decimal, top: int) -> dic
     if observed_at <= end:
         raise ValueError("只支持已结束的历史交易日")
     async with build_market_query() as client:
-        revision = (await client.snapshot(day, day))["canonical"]
-        catalog = await client.search_instruments(limit=10000)
+        revision = (
+            await client.resolve_snapshot(["bar", "instrument", "trading_calendar"])
+        ).snapshot_id
+        catalog = await client.search_instruments(limit=10000, revision=revision)
         if len(catalog) >= 10000:
             raise ValueError("标的目录可能截断，拒绝冒充全市场")
         stocks = [i for i in catalog if i.instrument_type == "stock"]
@@ -72,8 +74,6 @@ async def run(day: date, output: Path, minimum_amount: Decimal, top: int) -> dic
                         raise ValueError("同一证券出现重复日线")
                     bars[bar.instrument_id] = bar
             print(f"已读取 {min(offset + 1000, len(ids))}/{len(ids)} 只候选", flush=True)
-        if (await client.snapshot(day, day))["canonical"] != revision:
-            raise ValueError("读取期间数据修订变化，请重新运行")
     if not bars:
         raise ValueError("当日无日线数据")
     reasons = dict.fromkeys(unknown_listing, "unknown_listing_date")

{powerquant_cli-0.2.7 → powerquant_cli-0.2.10}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "powerquant-cli"
-version = "0.2.7"
+version = "0.2.10"
 description = "Power Quant local research CLI"
 readme = "README.md"
 requires-python = ">=3.12"
 license = "LicenseRef-PowerQuant-Proprietary AND MIT"
 license-files = ["LICENSE", "licenses/LICENSE.vnpy"]
-dependencies = ["pydantic>=2.5,<3", "polars>=1.36,<2", "numpy>=2,<3", "scipy>=1.17,<2", "pandas>=3,<4", "tzdata>=2026.3", "typer>=0.27.2", "httpx>=0.28,<1", "duckdb>=1.4,<2", "filelock>=3.20,<4"]
+dependencies = ["pydantic>=2.5,<3", "polars>=1.36,<2", "numpy>=2,<3", "scipy>=1.17,<2", "pandas>=3,<4", "tzdata>=2026.3", "typer>=0.27.2", "httpx>=0.28,<1", "duckdb>=1.4,<2", "filelock>=3.20,<4", "pyyaml>=6,<7"]
 
 [project.urls]
 Repository = "https://github.com/Kepler452Byte/power-quant"
@@ -19,7 +19,7 @@ build-backend = "hatchling.build"
 packages = ["src/quant_cli"]
 
 [dependency-groups]
-dev = ["powerquant-core==0.2.6", "powerquant-market==0.2.6", "pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.6", "pyright>=1.1.380"]
+dev = ["powerquant-core==0.2.6", "powerquant-market==0.3.0", "pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.6", "pyright>=1.1.380"]
 [tool.ruff]
 line-length = 100
 target-version = "py312"

powerquant_cli-0.2.10/src/quant_cli/app/agent_resources/cli/agent_resource_cli.py

@@ -0,0 +1,70 @@
+"""Agent 资源命令：发现随包内容、预览安装与同步。"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from quant_cli.app.agent_resources.schema.agent_resource_schema import AgentTarget
+from quant_cli.app.cli_dependency import container
+from quant_cli.common.command_error_handler import CommandGroup
+from quant_cli.common.command_help import Command
+from quant_cli.common.utils.cli_utils import cli_errors, output
+
+app = typer.Typer(cls=CommandGroup, no_args_is_help=True, help="安装和同步受管 Agent 资源")
+skill_app = typer.Typer(cls=CommandGroup, no_args_is_help=True, help="查看并校验随包 Skill")
+
+
+@skill_app.command("list", cls=Command)
+@cli_errors
+def list_skills(ctx: typer.Context) -> None:
+    output(container(ctx).agent_resource_service.list_skills())
+
+
+@skill_app.command("show", cls=Command)
+@cli_errors
+def show_skill(ctx: typer.Context, name: str, file: str = typer.Option("SKILL.md")) -> None:
+    output(container(ctx).agent_resource_service.show(name, file))
+
+
+@skill_app.command("check", cls=Command)
+@cli_errors
+def check_skills(ctx: typer.Context) -> None:
+    output(container(ctx).agent_resource_service.check())
+
+
+@app.command("install", cls=Command)
+@cli_errors
+def install_agent(
+    ctx: typer.Context,
+    agent: Annotated[AgentTarget, typer.Option()] = AgentTarget.BOTH,
+    skills_dir: Annotated[
+        Path | None, typer.Option(help="自定义 Skill 目录，替代客户端默认目录")
+    ] = None,
+    hint_file: Annotated[list[Path] | None, typer.Option(help="显式 Hint 目标，可重复")] = None,
+    confirm: bool = typer.Option(False),
+    expected_plan: str | None = typer.Option(None),
+) -> None:
+    result = container(ctx).bootstrap_service.install(
+        agent.value, skills_dir, tuple(hint_file or ()), confirm, expected_plan
+    )
+    output(result, status="applied" if confirm else "planned")
+
+
+@app.command("sync", cls=Command)
+@cli_errors
+def sync_agent(
+    ctx: typer.Context,
+    confirm: bool = typer.Option(False),
+    expected_plan: str | None = typer.Option(None),
+) -> None:
+    output(
+        container(ctx).agent_resource_service.sync(confirm, expected_plan),
+        status="applied" if confirm else "planned",
+    )
+
+
+def register_agent_commands(root: typer.Typer) -> typer.Typer:
+    root.add_typer(skill_app, name="skill")
+    root.add_typer(app, name="agent")
+    return app

powerquant_cli-0.2.10/src/quant_cli/app/agent_resources/interface/public/agent_resource_sync.py

@@ -0,0 +1,14 @@
+"""Public resource alignment port used by system upgrade."""
+
+from pathlib import Path
+from typing import Protocol
+
+
+class IAgentResourceSync(Protocol):
+    def sync(
+        self,
+        confirm: bool = False,
+        expected_plan: str | None = None,
+        skills_dirs: tuple[Path, ...] = (),
+        hint_files: tuple[Path, ...] = (),
+    ) -> dict[str, object]: ...

powerquant_cli-0.2.10/src/quant_cli/app/agent_resources/repository/agent_resource_repository.py

@@ -0,0 +1,57 @@
+"""Read packaged assets and persist explicitly addressed files."""
+
+from contextlib import AbstractContextManager
+from importlib import metadata, resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+from quant_cli.common.filesystem import atomic_write, read_bytes, safe_path, write_lock
+
+
+class AgentResourceRepository:
+    def __init__(
+        self, distribution: str, command: str, state_root: Path, package: str = "quant_cli"
+    ):
+        self.distribution = distribution
+        self.command = command
+        self.state_root = state_root.expanduser().absolute()
+        self.package = package
+        self.registry_path = self.state_root / "resources.json"
+
+    def assets(self) -> dict[str, bytes]:
+        root = resources.files(self.package).joinpath("resources", "skills")
+        assets: dict[str, bytes] = {}
+
+        def visit(node: Traversable, prefix: str) -> None:
+            for child in sorted(node.iterdir(), key=lambda item: item.name):
+                relative = prefix + child.name
+                if child.is_dir():
+                    visit(child, relative + "/")
+                else:
+                    assets[relative] = child.read_bytes()
+
+        if root.is_dir():
+            visit(root, "")
+        return assets
+
+    def version(self) -> str:
+        return metadata.version(self.distribution)
+
+    def hint(self) -> bytes:
+        path = resources.files(self.package).joinpath("resources", "agent_hint.md")
+        return path.read_bytes() if path.is_file() else b""
+
+    def resolve(self, path: Path) -> Path:
+        return safe_path(path)
+
+    def read(self, path: Path) -> bytes | None:
+        return read_bytes(path)
+
+    def write(self, path: Path, content: bytes) -> None:
+        atomic_write(path, content)
+
+    def remove(self, path: Path) -> None:
+        safe_path(path).unlink(missing_ok=True)
+
+    def lock(self, targets: list[Path]) -> AbstractContextManager[None]:
+        return write_lock(self.state_root, targets)

powerquant_cli-0.2.10/src/quant_cli/app/agent_resources/schema/agent_resource_schema.py

@@ -0,0 +1,89 @@
+"""Resource ownership records and explicit synchronization plans."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from quant_cli.common.hashing import digest
+from quant_cli.common.operation_error import OperationError
+
+
+class AgentTarget(StrEnum):
+    CODEX = "codex"
+    CLAUDE = "claude"
+    BOTH = "both"
+
+
+@dataclass(frozen=True)
+class OwnedFile:
+    path: str
+    kind: str
+
+
+@dataclass
+class Registry:
+    distribution: str
+    skills: list[str]
+    hints: list[str]
+    files: list[OwnedFile]
+
+    @classmethod
+    def load(cls, raw: bytes, distribution: str) -> Registry:
+        try:
+            data = json.loads(raw)
+            if (
+                not isinstance(data, dict)
+                or set(data) != {"distribution", "skills", "hints", "files"}
+                or data.get("distribution") != distribution
+            ):
+                raise ValueError("identity")
+            skills, hints, files = data["skills"], data["hints"], data["files"]
+            if not all(isinstance(items, list) for items in (skills, hints, files)):
+                raise ValueError("lists")
+            if not all(isinstance(item, str) for item in [*skills, *hints]):
+                raise ValueError("paths")
+            if not all(Path(item).is_absolute() for item in [*skills, *hints]):
+                raise ValueError("absolute paths")
+            owned: list[OwnedFile] = []
+            for item in files:
+                if (
+                    not isinstance(item, dict)
+                    or set(item) != {"path", "kind"}
+                    or not all(isinstance(item.get(key), str) for key in ("path", "kind"))
+                ):
+                    raise ValueError("files")
+                if item["kind"] not in {"skill", "hint"}:
+                    raise ValueError("kind")
+                owned.append(OwnedFile(item["path"], item["kind"]))
+            if len({item.path for item in owned}) != len(owned):
+                raise ValueError("duplicate paths")
+            return cls(distribution, skills, hints, owned)
+        except (ValueError, KeyError, TypeError) as exc:
+            raise OperationError(
+                "Resource registry is invalid; preserve it and repair explicitly",
+                "invalid-registry",
+            ) from exc
+
+    def encode(self) -> bytes:
+        return (
+            json.dumps(asdict(self), sort_keys=True, ensure_ascii=False, indent=2) + "\n"
+        ).encode()
+
+
+@dataclass(frozen=True)
+class Change:
+    path: Path
+    before: str
+    content: bytes | None
+    action: str
+
+    def describe(self) -> dict[str, str]:
+        return {
+            "path": str(self.path),
+            "action": self.action,
+            "expected_hash": self.before,
+            "new_hash": digest(self.content),
+        }