@sakanano-moe/agenthelm 6.13.1 → 6.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/runtime/index.json +6 -6
- package/runtime/plugins/agent-pack/.codex-plugin/plugin.json +1 -1
- package/runtime/plugins/agent-pack/plugin.json +1 -1
- package/runtime/plugins/agent-pack/references/capability-config.md +10 -0
- package/runtime/plugins/agent-pack/references/check-opinion-migrate.en.md +31 -0
- package/runtime/plugins/agent-pack/references/check-opinion-migrate.md +31 -0
- package/runtime/plugins/agent-pack/references/dedupe-contract.en.md +27 -0
- package/runtime/plugins/agent-pack/references/dedupe-contract.md +27 -0
- package/runtime/plugins/agent-pack/references/inventory-contract.en.md +83 -0
- package/runtime/plugins/agent-pack/references/inventory-contract.md +83 -0
- package/runtime/plugins/agent-pack/references/nudge.en.md +10 -2
- package/runtime/plugins/agent-pack/references/nudge.md +10 -2
- package/runtime/plugins/agent-pack/references/relocate-contract.en.md +41 -0
- package/runtime/plugins/agent-pack/references/relocate-contract.md +41 -0
- package/runtime/plugins/agent-pack/runtime/agent_pack_claude.py +572 -30
- package/runtime/plugins/agent-pack/runtime/agent_pack_clients.py +233 -0
- package/runtime/plugins/agent-pack/runtime/agent_pack_config.py +112 -4
- package/runtime/plugins/agent-pack/runtime/agent_pack_dedupe.py +502 -0
- package/runtime/plugins/agent-pack/runtime/agent_pack_desktop.py +92 -0
- package/runtime/plugins/agent-pack/runtime/agent_pack_ext_common.py +251 -0
- package/runtime/plugins/agent-pack/runtime/agent_pack_inventory.py +989 -0
- package/runtime/plugins/agent-pack/runtime/agent_pack_mcp_write.py +447 -0
- package/runtime/plugins/agent-pack/runtime/agent_pack_nudge.py +29 -4
- package/runtime/plugins/agent-pack/runtime/agent_pack_relocate.py +385 -0
- package/runtime/plugins/agent-pack/runtime/agent_pack_scope.py +233 -0
- package/runtime/plugins/agent-pack/runtime/agenthelm.py +183 -14
- package/runtime/plugins/agent-pack/runtime/locale/en.json +250 -1
- package/runtime/plugins/agent-pack/runtime/mcp_server.py +12 -0
- package/runtime/plugins/agent-pack/runtime/nudge_text.py +8 -2
- package/runtime/plugins/agent-pack/runtime/user_settings.py +2 -1
- package/runtime/plugins/agent-pack/skills/agent-pack/SKILL.md +15 -0
- package/runtime/plugins/agents-init/.codex-plugin/plugin.json +1 -1
- package/runtime/plugins/agents-init/content.json +4 -2
- package/runtime/plugins/agents-init/plugin.json +1 -1
- package/runtime/plugins/agents-init/skills/agents-init/SKILL.md +2 -0
- package/runtime/plugins/agents-init/skills/agents-init/launcher.en.sh +93 -0
- package/runtime/plugins/agents-init/skills/agents-init/project.schema.json +27 -0
- package/runtime/plugins/agents-init/skills/agents-init/scripts/baseline.py +4 -1
- package/runtime/plugins/agents-init/skills/agents-init/scripts/init_project.py +24 -9
- package/runtime/plugins/agents-init/skills/agents-init/skill.json +1 -1
- package/runtime/plugins/opinion-manager/.codex-plugin/plugin.json +1 -1
- package/runtime/plugins/opinion-manager/catalog/README.md +3 -1
- package/runtime/plugins/opinion-manager/catalog/rules/om.align-requirements/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.assumptions-authority/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.batch-questions/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.bilingual-terms/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.calculations/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.chinese-response/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.clean-deliverable/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.complete-options/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.conclusion-first/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.concrete-titles/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.consistent-items/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.device-readable/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.editable-diagrams/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.evidence-inference/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.maintenance-chinese/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.maintenance-project-language/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.markdown-structure/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.portable-files/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.report-context/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.report-formats/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.report-review/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.response-brief/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.response-dense/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.rules-tools/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.semantic-wrap/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.solutions-proportional/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.solutions-three-level/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.tables-compact/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.tables-list-first/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.test-evidence/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/rules/om.versioned-files/versions/1.1.0.json +34 -0
- package/runtime/plugins/opinion-manager/catalog/templates/delivery-standard/compact-tables/versions/1.1.0.json +32 -0
- package/runtime/plugins/opinion-manager/catalog/templates/delivery-standard/list-first/versions/1.1.0.json +32 -0
- package/runtime/plugins/opinion-manager/catalog/templates/development-standard/chinese-maintenance/versions/1.1.0.json +26 -0
- package/runtime/plugins/opinion-manager/catalog/templates/development-standard/project-language/versions/1.1.0.json +26 -0
- package/runtime/plugins/opinion-manager/catalog/templates/response-style/brief-chinese/versions/1.1.0.json +30 -0
- package/runtime/plugins/opinion-manager/catalog/templates/response-style/dense-chinese/versions/1.1.0.json +30 -0
- package/runtime/plugins/opinion-manager/catalog/templates/scenario/concise-project/versions/1.1.0.json +181 -0
- package/runtime/plugins/opinion-manager/catalog/templates/scenario/reviewed-project/versions/1.1.0.json +179 -0
- package/runtime/plugins/opinion-manager/catalog/templates/work-method/proportional/versions/1.1.0.json +31 -0
- package/runtime/plugins/opinion-manager/catalog/templates/work-method/three-level/versions/1.1.0.json +31 -0
- package/runtime/plugins/opinion-manager/content.json +44 -3
- package/runtime/plugins/opinion-manager/plugin.json +1 -1
- package/runtime/plugins/opinion-manager/references/inbox.en.md +25 -4
- package/runtime/plugins/opinion-manager/references/inbox.md +25 -4
- package/runtime/plugins/opinion-manager/references/profile.schema.json +19 -2
- package/runtime/plugins/opinion-manager/references/rule.schema.json +25 -3
- package/runtime/plugins/opinion-manager/references/versioned-template.schema.json +5 -4
- package/runtime/plugins/opinion-manager/references/versioning.md +89 -4
- package/runtime/plugins/opinion-manager/runtime/context.py +26 -19
- package/runtime/plugins/opinion-manager/runtime/inbox.py +400 -25
- package/runtime/plugins/opinion-manager/runtime/inbox_relations.py +106 -0
- package/runtime/plugins/opinion-manager/runtime/inbox_routes.py +132 -0
- package/runtime/plugins/opinion-manager/runtime/inbox_text.py +117 -11
- package/runtime/plugins/opinion-manager/runtime/lifecycle.py +35 -5
- package/runtime/plugins/opinion-manager/runtime/locale/en.json +137 -2
- package/runtime/plugins/opinion-manager/runtime/migrate.py +582 -0
- package/runtime/plugins/opinion-manager/runtime/opinion_manager.py +9 -4
- package/runtime/plugins/opinion-manager/runtime/rule_lines.py +247 -0
- package/runtime/plugins/opinion-manager/runtime/tags.py +217 -0
- package/runtime/plugins/opinion-manager/runtime/versioned.py +289 -41
- package/runtime/plugins/opinion-manager/skills/opinion-manager/SKILL.md +8 -7
- package/runtime/plugins/project-orchestrator/.codex-plugin/plugin.json +1 -1
- package/runtime/plugins/project-orchestrator/plugin.json +1 -1
- package/runtime/plugins/project-orchestrator/runtime/locale/en.json +305 -3
- package/runtime/plugins/project-orchestrator/runtime/private_paths.py +11 -1
- package/runtime/plugins/project-orchestrator/runtime/project_cli.py +101 -1
- package/runtime/plugins/project-orchestrator/runtime/project_demo.py +13 -1
- package/runtime/plugins/project-orchestrator/runtime/project_ext_actions.py +415 -0
- package/runtime/plugins/project-orchestrator/runtime/project_extensions.py +971 -0
- package/runtime/plugins/project-orchestrator/runtime/project_extensions_demo.py +86 -0
- package/runtime/plugins/project-orchestrator/runtime/project_menu.py +345 -2
- package/runtime/plugins/project-orchestrator/runtime/project_real.py +17 -1
- package/runtime/plugins/project-orchestrator/skills/project-orchestrator/SKILL.md +2 -0
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Declarative client-driver registry (#134 Phase 1).
|
|
3
|
+
|
|
4
|
+
A *driver* describes how a client is recognised and how it takes plugins, as data: detection evidence (executable
|
|
5
|
+
names, configuration directories), the distribution driver type (``marketplace-cli`` | ``directory-dropin`` |
|
|
6
|
+
``none``), where Skills and MCP servers are stored, and capability flags. Code asks the registry (``default_ids``,
|
|
7
|
+
``supports``, ``detect``) instead of listing client names.
|
|
8
|
+
|
|
9
|
+
User declarations in ``~/.config/agenthelm/clients.d/*.json`` are read and validated only. They never run a command,
|
|
10
|
+
never write a file and never enter the ``--client`` set in this version; an invalid one is a warning and is ignored.
|
|
11
|
+
Standard library only, so every entry point can import it.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import json
|
|
17
|
+
import os
|
|
18
|
+
import re
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
from typing import Any, Callable
|
|
21
|
+
|
|
22
|
+
from i18n_agent_pack import _
|
|
23
|
+
|
|
24
|
+
DISTRIBUTIONS = ("marketplace-cli", "directory-dropin", "none")
|
|
25
|
+
SCOPES = ("user", "local", "project")
|
|
26
|
+
FORMATS = ("json", "toml", "dir")
|
|
27
|
+
CAPABILITIES = ("default_set", "read_only", "project_mcp_write")
|
|
28
|
+
ID_PATTERN = re.compile(r"^[a-z][a-z0-9-]{0,31}$")
|
|
29
|
+
DECLARATION_KEYS = {"schema_version", "id", "display", "detect", "distribution", "stores", "capabilities"}
|
|
30
|
+
MAX_DECLARATION_BYTES = 64 * 1024
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _store(scope: str, path: str, fmt: str) -> dict:
|
|
34
|
+
return {"scope": scope, "path": path, "format": fmt}
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _driver(id_: str, display: str, executables: list[str], dirs: list[dict], distribution: str,
|
|
38
|
+
skills: list[dict], mcp: list[dict], *, default: bool = True, read_only: bool = False,
|
|
39
|
+
project_mcp: bool = False) -> dict:
|
|
40
|
+
return {
|
|
41
|
+
"schema_version": 1, "id": id_, "display": display,
|
|
42
|
+
"detect": {"executables": executables, "dirs": dirs},
|
|
43
|
+
"distribution": distribution,
|
|
44
|
+
"stores": {"skills": skills, "mcp": mcp},
|
|
45
|
+
"capabilities": {"default_set": default, "read_only": read_only, "project_mcp_write": project_mcp},
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
# Order is the order the previous hard-coded tuple had; claude-desktop follows the default set.
|
|
50
|
+
# ``project_mcp_write`` mirrors what agenthelm writes today (Claude only); W-a reads it as the single source.
|
|
51
|
+
BUILTIN: tuple[dict, ...] = (
|
|
52
|
+
_driver("claude", "Claude Code", ["claude"], [{"path": "~/.claude", "env": "CLAUDE_CONFIG_DIR"}], "marketplace-cli",
|
|
53
|
+
[_store("user", "~/.claude/skills", "dir"), _store("project", "<project>/.claude/skills", "dir")],
|
|
54
|
+
[_store("user", "~/.claude.json", "json"), _store("local", "~/.claude.json#projects", "json"),
|
|
55
|
+
_store("project", "<project>/.mcp.json", "json")], project_mcp=True),
|
|
56
|
+
_driver("codex", "Codex", ["codex"], [{"path": "~/.codex", "env": "CODEX_HOME"}], "marketplace-cli",
|
|
57
|
+
[_store("user", "~/.codex/skills", "dir"), _store("user", "~/.agents/skills", "dir"),
|
|
58
|
+
_store("project", "<project>/.agents/skills", "dir")],
|
|
59
|
+
[_store("user", "~/.codex/config.toml", "toml"), _store("project", "<project>/.codex/config.toml", "toml")]),
|
|
60
|
+
_driver("cursor", "Cursor", [], [{"path": "~/.cursor"}], "directory-dropin",
|
|
61
|
+
[_store("user", "~/.cursor/skills", "dir"), _store("user", "~/.agents/skills", "dir"),
|
|
62
|
+
_store("project", "<project>/.cursor/skills", "dir"), _store("project", "<project>/.agents/skills", "dir")],
|
|
63
|
+
[_store("user", "~/.cursor/mcp.json", "json"), _store("project", "<project>/.cursor/mcp.json", "json")]),
|
|
64
|
+
_driver("claude-desktop", "Claude Desktop", [],
|
|
65
|
+
[{"path": "~/Library/Application Support/Claude"}, {"path": "~/.config/Claude"}], "none",
|
|
66
|
+
[], [_store("user", "<per-platform>/claude_desktop_config.json", "json")], default=False, read_only=True),
|
|
67
|
+
)
|
|
68
|
+
BUILTIN_IDS = tuple(item["id"] for item in BUILTIN)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def default_ids() -> tuple[str, ...]:
|
|
72
|
+
return tuple(item["id"] for item in BUILTIN if item["capabilities"]["default_set"])
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def all_ids() -> tuple[str, ...]:
|
|
76
|
+
return BUILTIN_IDS
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def get(client: str) -> dict | None:
|
|
80
|
+
return next((item for item in BUILTIN if item["id"] == client), None)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def display_names() -> dict[str, str]:
|
|
84
|
+
"""Display names of the default set (what the old ``CLIENT_NAMES`` held)."""
|
|
85
|
+
return {item["id"]: item["display"] for item in BUILTIN if item["capabilities"]["default_set"]}
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def supports(client: str, capability: str) -> bool:
|
|
89
|
+
"""Capability flag of a built-in driver; an unknown client or flag is ``False``."""
|
|
90
|
+
driver = get(client)
|
|
91
|
+
return bool(driver and driver["capabilities"].get(capability))
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
# ---------------------------------------------------------------- detection (facts, not names)
|
|
95
|
+
|
|
96
|
+
def _expand(template: str, home: Path) -> Path:
|
|
97
|
+
return home / template[2:] if template.startswith("~/") else Path(template)
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def detect(driver: dict, home: Path, getenv: Callable[[str], str | None],
|
|
101
|
+
find_cli: Callable[[str], str | None]) -> dict:
|
|
102
|
+
"""``{detected, evidence}``: the first matching fact (executable, then directory), else not detected."""
|
|
103
|
+
for name in driver["detect"].get("executables", []):
|
|
104
|
+
found = find_cli(name)
|
|
105
|
+
if found:
|
|
106
|
+
return {"detected": True, "evidence": {"kind": "executable", "name": name}}
|
|
107
|
+
for item in driver["detect"].get("dirs", []):
|
|
108
|
+
override = getenv(item["env"]) if item.get("env") else None
|
|
109
|
+
path = Path(override) if override else _expand(item["path"], home)
|
|
110
|
+
if path.is_dir():
|
|
111
|
+
return {"detected": True, "evidence": {"kind": "directory", "name": item["path"]}}
|
|
112
|
+
return {"detected": False, "evidence": None}
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
# ---------------------------------------------------------------- user declarations (validate only)
|
|
116
|
+
|
|
117
|
+
def declaration_dir(home: Path, getenv: Callable[[str], str | None]) -> Path:
|
|
118
|
+
base = getenv("XDG_CONFIG_HOME")
|
|
119
|
+
return (Path(base) if base else home / ".config") / "agenthelm" / "clients.d"
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def _is_text(value: Any, limit: int = 64) -> bool:
|
|
123
|
+
return isinstance(value, str) and 0 < len(value) <= limit and not any(ord(c) < 32 for c in value)
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def validate_declaration(data: Any) -> str | None:
|
|
127
|
+
"""The reason a declaration is invalid (``None`` when valid). Only data fields are accepted."""
|
|
128
|
+
if not isinstance(data, dict):
|
|
129
|
+
return _("顶层必须是对象")
|
|
130
|
+
extra = sorted(set(data) - DECLARATION_KEYS)
|
|
131
|
+
if extra:
|
|
132
|
+
return _("含不支持的字段:{0}").format(_("、").join(map(str, extra)))
|
|
133
|
+
if data.get("schema_version") != 1:
|
|
134
|
+
return _("schema_version 必须为 1")
|
|
135
|
+
if not isinstance(data.get("id"), str) or not ID_PATTERN.match(data["id"]):
|
|
136
|
+
return _("id 必须匹配 ^[a-z][a-z0-9-]{0,31}$")
|
|
137
|
+
if data["id"] in BUILTIN_IDS or data["id"] == "all":
|
|
138
|
+
return _("id 与内置客户端冲突:{0}").format(data["id"])
|
|
139
|
+
if not _is_text(data.get("display")):
|
|
140
|
+
return _("display 必须是 1–64 字符的单行文本")
|
|
141
|
+
detect_part = data.get("detect")
|
|
142
|
+
if not isinstance(detect_part, dict) or set(detect_part) - {"executables", "dirs"}:
|
|
143
|
+
return _("detect 必须是只含 executables / dirs 的对象")
|
|
144
|
+
executables = detect_part.get("executables", [])
|
|
145
|
+
if not isinstance(executables, list) or not all(isinstance(x, str) and re.fullmatch(r"[A-Za-z0-9._-]{1,64}", x)
|
|
146
|
+
for x in executables):
|
|
147
|
+
return _("detect.executables 必须是可执行文件名列表(不含路径与参数)")
|
|
148
|
+
dirs = detect_part.get("dirs", [])
|
|
149
|
+
if not isinstance(dirs, list) or not all(isinstance(x, str) and x.startswith("~/") and ".." not in x.split("/")
|
|
150
|
+
and _is_text(x, 200) for x in dirs):
|
|
151
|
+
return _("detect.dirs 必须是 ~/ 开头、不含 .. 的路径列表")
|
|
152
|
+
if not executables and not dirs:
|
|
153
|
+
return _("detect 至少要有一项检测依据")
|
|
154
|
+
if data.get("distribution") not in DISTRIBUTIONS:
|
|
155
|
+
return _("distribution 必须是:{0}").format(_("、").join(DISTRIBUTIONS))
|
|
156
|
+
stores = data.get("stores", {})
|
|
157
|
+
if not isinstance(stores, dict) or set(stores) - {"skills", "mcp"}:
|
|
158
|
+
return _("stores 必须是只含 skills / mcp 的对象")
|
|
159
|
+
for kind in stores:
|
|
160
|
+
entries = stores[kind]
|
|
161
|
+
if not isinstance(entries, list) or not all(
|
|
162
|
+
isinstance(e, dict) and set(e) == {"scope", "path", "format"} and e["scope"] in SCOPES
|
|
163
|
+
and e["format"] in FORMATS and _is_text(e["path"], 200) for e in entries):
|
|
164
|
+
return _("stores.{0} 的每一项必须是 scope / path / format(取值见文档)").format(kind)
|
|
165
|
+
capabilities = data.get("capabilities", {})
|
|
166
|
+
if not isinstance(capabilities, dict) or not all(k in CAPABILITIES and isinstance(v, bool)
|
|
167
|
+
for k, v in capabilities.items()):
|
|
168
|
+
return _("capabilities 只能含布尔值的:{0}").format(_("、").join(CAPABILITIES))
|
|
169
|
+
return None
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def load_declarations(home: Path, getenv: Callable[[str], str | None]) -> tuple[list[dict], list[dict]]:
|
|
173
|
+
"""(valid declarations, warnings). Reads ``clients.d/*.json`` only; nothing in them is ever executed."""
|
|
174
|
+
folder = declaration_dir(home, getenv)
|
|
175
|
+
declarations: list[dict] = []
|
|
176
|
+
warnings: list[dict] = []
|
|
177
|
+
if not folder.is_dir():
|
|
178
|
+
return declarations, warnings
|
|
179
|
+
seen: set[str] = set()
|
|
180
|
+
for path in sorted(folder.glob("*.json")):
|
|
181
|
+
label = path.name
|
|
182
|
+
try:
|
|
183
|
+
if path.is_symlink() or not path.is_file() or path.stat().st_size > MAX_DECLARATION_BYTES:
|
|
184
|
+
raise ValueError(_("不是普通文件或超过 {0} 字节").format(MAX_DECLARATION_BYTES))
|
|
185
|
+
data = json.loads(path.read_text(encoding="utf-8"))
|
|
186
|
+
reason = validate_declaration(data)
|
|
187
|
+
if reason is None and data["id"] in seen:
|
|
188
|
+
reason = _("id 重复:{0}").format(data["id"])
|
|
189
|
+
except (OSError, ValueError, UnicodeDecodeError) as error:
|
|
190
|
+
reason = _("无法读取:{0}").format(error)
|
|
191
|
+
if reason:
|
|
192
|
+
warnings.append({"file": label, "reason": reason})
|
|
193
|
+
continue
|
|
194
|
+
seen.add(data["id"])
|
|
195
|
+
declarations.append(data)
|
|
196
|
+
return declarations, warnings
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
# ---------------------------------------------------------------- the ``agenthelm clients`` report
|
|
200
|
+
|
|
201
|
+
def report(home: Path, getenv: Callable[[str], str | None], find_cli: Callable[[str], str | None]) -> dict:
|
|
202
|
+
clients = []
|
|
203
|
+
for item in BUILTIN:
|
|
204
|
+
found = detect(item, home, getenv, find_cli)
|
|
205
|
+
clients.append({"id": item["id"], "display": item["display"], "source": "builtin", **found,
|
|
206
|
+
"distribution": item["distribution"], "capabilities": dict(item["capabilities"]),
|
|
207
|
+
"install_supported": item["distribution"] != "none"})
|
|
208
|
+
declared, warnings = load_declarations(home, getenv)
|
|
209
|
+
for item in declared:
|
|
210
|
+
probe = {"detect": {"executables": item["detect"].get("executables", []),
|
|
211
|
+
"dirs": [{"path": path} for path in item["detect"].get("dirs", [])]}}
|
|
212
|
+
found = detect(probe, home, getenv, find_cli) # looks up executables and directories; runs nothing
|
|
213
|
+
clients.append({"id": item["id"], "display": item["display"], "source": "declared", **found,
|
|
214
|
+
"distribution": item["distribution"],
|
|
215
|
+
"capabilities": {key: bool(item.get("capabilities", {}).get(key, False)) for key in CAPABILITIES},
|
|
216
|
+
"install_supported": False})
|
|
217
|
+
return {"schema_version": 1, "clients": clients, "warnings": warnings}
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def render_text(data: dict) -> str:
|
|
221
|
+
lines = [_("客户端驱动(内置与用户声明):")]
|
|
222
|
+
for item in data["clients"]:
|
|
223
|
+
evidence = item["evidence"]
|
|
224
|
+
seen = (_("已检测到({0}:{1})").format(_("可执行文件") if evidence["kind"] == "executable" else _("目录"),
|
|
225
|
+
evidence["name"]) if item["detected"] else _("未检测到"))
|
|
226
|
+
if item["source"] == "declared":
|
|
227
|
+
seen = _("已声明,本版未支持安装")
|
|
228
|
+
flags = [key for key, value in item["capabilities"].items() if value]
|
|
229
|
+
lines.append(" " + _("{0}({1}):{2};分发 {3};能力 {4}").format(
|
|
230
|
+
item["id"], item["display"], seen, item["distribution"], ", ".join(flags) or "-"))
|
|
231
|
+
for warning in data["warnings"]:
|
|
232
|
+
lines.append(_("警告:忽略声明 {0}:{1}").format(warning["file"], warning["reason"]))
|
|
233
|
+
return "\n".join(lines) + "\n"
|
|
@@ -151,6 +151,43 @@ class ProjectLayout:
|
|
|
151
151
|
mcp_client_policy: dict[str, dict[str, tuple[str, ...]]]
|
|
152
152
|
destination_skill_root: Path
|
|
153
153
|
destination_mcp: Path
|
|
154
|
+
# Scope declaration (#67): ``user`` serves every project, ``project`` only this one. Absent keys mean ``user``.
|
|
155
|
+
default_scope: str = "user"
|
|
156
|
+
mcp_scope: dict[str, str] = field(default_factory=dict)
|
|
157
|
+
skill_scope: dict[str, str] = field(default_factory=dict)
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
SCOPES = ("user", "project")
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def project_write_supported(client: str) -> bool:
|
|
164
|
+
"""Whether a sync can write a project-level store for this client. The one place that decides it; the answer is
|
|
165
|
+
the ``project_mcp_write`` capability of the client's driver (``agent_pack_clients``), not a client name."""
|
|
166
|
+
import agent_pack_clients # noqa: PLC0415 - shipped next to this file; imported late (python3 -I path set in main)
|
|
167
|
+
return agent_pack_clients.supports(client, "project_mcp_write")
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def declared_scope(layout: ProjectLayout, kind: str, name: str) -> str:
|
|
171
|
+
"""The scope the project declares for one Skill (``kind="skill"``) or MCP server (``kind="mcp"``)."""
|
|
172
|
+
mapping = layout.skill_scope if kind == "skill" else layout.mcp_scope
|
|
173
|
+
return mapping.get(name, layout.default_scope)
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def _parse_scopes(config: dict[str, Any]) -> tuple[str, dict[str, str], dict[str, str]]:
|
|
177
|
+
default = config.get("default_scope", "user")
|
|
178
|
+
if default not in SCOPES:
|
|
179
|
+
raise AgentPackError(f"capabilities.default_scope must be one of {', '.join(SCOPES)}: {default!r}")
|
|
180
|
+
parsed: dict[str, dict[str, str]] = {}
|
|
181
|
+
for key in ("mcp_scope", "skill_scope"):
|
|
182
|
+
value = config.get(key, {})
|
|
183
|
+
if not isinstance(value, dict):
|
|
184
|
+
raise AgentPackError(f"capabilities.{key} must be an object mapping names to user|project")
|
|
185
|
+
for name, scope in value.items():
|
|
186
|
+
if not isinstance(name, str) or not name or scope not in SCOPES:
|
|
187
|
+
raise AgentPackError(
|
|
188
|
+
f"capabilities.{key}.{name} must be one of {', '.join(SCOPES)}: {scope!r}")
|
|
189
|
+
parsed[key] = dict(value)
|
|
190
|
+
return default, parsed["mcp_scope"], parsed["skill_scope"]
|
|
154
191
|
|
|
155
192
|
|
|
156
193
|
def _read_json(path: Path) -> dict[str, Any]:
|
|
@@ -306,6 +343,7 @@ def load_project_layout(project: Path) -> ProjectLayout:
|
|
|
306
343
|
destination_mcp = _resolve_profile_paths(
|
|
307
344
|
root, [config.get("destination_mcp", ".agents/mcp.json")], [".agents/mcp.json"]
|
|
308
345
|
)[0]
|
|
346
|
+
default_scope, mcp_scope, skill_scope = _parse_scopes(config)
|
|
309
347
|
return ProjectLayout(
|
|
310
348
|
root=root,
|
|
311
349
|
profile_path=profile_path if profile_path.is_file() else None,
|
|
@@ -318,6 +356,9 @@ def load_project_layout(project: Path) -> ProjectLayout:
|
|
|
318
356
|
mcp_client_policy=mcp_client_policy,
|
|
319
357
|
destination_skill_root=destination_skill,
|
|
320
358
|
destination_mcp=destination_mcp,
|
|
359
|
+
default_scope=default_scope,
|
|
360
|
+
mcp_scope=mcp_scope,
|
|
361
|
+
skill_scope=skill_scope,
|
|
321
362
|
)
|
|
322
363
|
|
|
323
364
|
|
|
@@ -883,6 +924,8 @@ def _mcp_allowed(layout: ProjectLayout, name: str, client: str) -> bool:
|
|
|
883
924
|
policy = layout.mcp_client_policy.get(name, {})
|
|
884
925
|
include = policy.get("include", ())
|
|
885
926
|
exclude = policy.get("exclude", ())
|
|
927
|
+
if not project_write_supported(client) and declared_scope(layout, "mcp", name) == "project":
|
|
928
|
+
return False # project-level write for these clients comes later; never fall back to the user level
|
|
886
929
|
return (not include or client in include) and client not in exclude
|
|
887
930
|
|
|
888
931
|
|
|
@@ -1038,6 +1081,9 @@ def _portable_package_from_inventory(
|
|
|
1038
1081
|
skills_root = destination / "skills"
|
|
1039
1082
|
skills_root.mkdir()
|
|
1040
1083
|
for item in inventory.skills:
|
|
1084
|
+
if (client is not None and not project_write_supported(client) and layout is not None
|
|
1085
|
+
and declared_scope(layout, "skill", item.name) == "project"):
|
|
1086
|
+
continue # project-native for these clients (.agents/skills); never copied to the user-level package
|
|
1041
1087
|
_copy_skill(Path(item.path), skills_root / item.name, allowed_root=project_root)
|
|
1042
1088
|
|
|
1043
1089
|
system_env = _system_env_values(home)
|
|
@@ -1639,6 +1685,8 @@ def reconcile_project(
|
|
|
1639
1685
|
only: Iterable[str] | None = None,
|
|
1640
1686
|
replace_mcp: bool = False,
|
|
1641
1687
|
replace_skills: bool = False,
|
|
1688
|
+
scope: str = "all",
|
|
1689
|
+
project_store: str = "local",
|
|
1642
1690
|
) -> dict[str, Any]:
|
|
1643
1691
|
"""Reconcile one project package and explicitly selected legacy components.
|
|
1644
1692
|
|
|
@@ -1657,9 +1705,17 @@ def reconcile_project(
|
|
|
1657
1705
|
return agent_pack_claude.sync_project(
|
|
1658
1706
|
project, home=home, apply=apply, replace=replace, reset_overrides=reset_overrides,
|
|
1659
1707
|
recovery_root=recovery_root, retire_skills=retire_skills, retire_plugins=retire_plugins,
|
|
1660
|
-
retire_only=retire_only, only=only, replace_mcp=replace_mcp, replace_skills=replace_skills
|
|
1708
|
+
retire_only=retire_only, only=only, replace_mcp=replace_mcp, replace_skills=replace_skills,
|
|
1709
|
+
scope=scope, project_store=project_store)
|
|
1661
1710
|
import agent_pack_claude # noqa: PLC0415 - shipped next to this file
|
|
1662
1711
|
|
|
1712
|
+
if scope != "all":
|
|
1713
|
+
raise AgentPackError(f"--scope user|project is supported for the claude client only: {client} has no "
|
|
1714
|
+
"project-level write yet")
|
|
1715
|
+
if project_store != "local":
|
|
1716
|
+
raise AgentPackError(f"--project-store is supported for the claude client only: {client} has no "
|
|
1717
|
+
"project-level write yet")
|
|
1718
|
+
|
|
1663
1719
|
if agent_pack_claude.normalize_only(only) != frozenset(agent_pack_claude.SYNC_TYPES) and not retire_only:
|
|
1664
1720
|
raise AgentPackError(
|
|
1665
1721
|
f"--only mcp|skills|plugins is supported for the claude client only: {client} installs one package "
|
|
@@ -1737,6 +1793,12 @@ def reconcile_project(
|
|
|
1737
1793
|
if native_plan is not None:
|
|
1738
1794
|
operations.extend(native_plan["operations"])
|
|
1739
1795
|
extras = {"residuals": residuals} if residuals else {}
|
|
1796
|
+
skipped = _project_scope_skips(layout, authority, client)
|
|
1797
|
+
if skipped: # declared project-level entries are skipped for this client, never written to the user level
|
|
1798
|
+
extras["skipped"] = skipped
|
|
1799
|
+
import agent_pack_scope # noqa: PLC0415 - shipped next to this file
|
|
1800
|
+
|
|
1801
|
+
extras["warnings"] = [agent_pack_scope.skipped_warning(item) for item in skipped]
|
|
1740
1802
|
if not apply:
|
|
1741
1803
|
return {"ok": True, "applied": False, "states": states, "operations": operations, **extras}
|
|
1742
1804
|
|
|
@@ -1822,10 +1884,22 @@ def sync_project(
|
|
|
1822
1884
|
only: Iterable[str] | None = None,
|
|
1823
1885
|
replace_mcp: bool = False,
|
|
1824
1886
|
replace_skills: bool = False,
|
|
1887
|
+
scope: str = "all",
|
|
1888
|
+
project_store: str = "local",
|
|
1825
1889
|
) -> dict[str, Any]:
|
|
1826
1890
|
return reconcile_project(project, client, home=home, apply=apply, replace=replace,
|
|
1827
1891
|
reset_overrides=reset_overrides, recovery_root=recovery_root,
|
|
1828
|
-
only=only, replace_mcp=replace_mcp, replace_skills=replace_skills
|
|
1892
|
+
only=only, replace_mcp=replace_mcp, replace_skills=replace_skills, scope=scope,
|
|
1893
|
+
project_store=project_store)
|
|
1894
|
+
|
|
1895
|
+
|
|
1896
|
+
def _project_scope_skips(layout: ProjectLayout, authority: Inventory, client: str) -> list[dict[str, str]]:
|
|
1897
|
+
"""Project-declared entries a codex / cursor sync leaves out (their project level is not written yet)."""
|
|
1898
|
+
skipped = [{"kind": "mcp", "name": item.name, "client": client, "reason": "client-project-unsupported"}
|
|
1899
|
+
for item in authority.mcps if item.portable and declared_scope(layout, "mcp", item.name) == "project"]
|
|
1900
|
+
skipped += [{"kind": "skill", "name": item.name, "client": client, "reason": "project-native"}
|
|
1901
|
+
for item in authority.skills if declared_scope(layout, "skill", item.name) == "project"]
|
|
1902
|
+
return sorted(skipped, key=lambda item: (item["kind"], item["name"]))
|
|
1829
1903
|
|
|
1830
1904
|
|
|
1831
1905
|
def _update_personal_marketplace(home: Path, package_name: str) -> None:
|
|
@@ -1988,8 +2062,23 @@ def doctor(project: Path, clients: Iterable[str] = (), home: Path | None = None)
|
|
|
1988
2062
|
issues.append(str(exc))
|
|
1989
2063
|
reports: dict[str, Any] = {}
|
|
1990
2064
|
for client in dict.fromkeys(clients):
|
|
2065
|
+
if client == "claude-desktop": # read-only observation of claude_desktop_config.json; never a drift issue
|
|
2066
|
+
import agent_pack_inventory # noqa: PLC0415 - shipped next to this file
|
|
2067
|
+
|
|
2068
|
+
report = agent_pack_inventory.desktop_report(home or Path.home())
|
|
2069
|
+
warnings.extend(report.pop("warnings"))
|
|
2070
|
+
reports[client] = report
|
|
2071
|
+
continue
|
|
1991
2072
|
report = client_drift(layout.root, client, home)
|
|
1992
2073
|
reports[client] = report
|
|
2074
|
+
if client == "claude": # advisory only: it never changes ``ok`` or the exit code
|
|
2075
|
+
import agent_pack_inventory # noqa: PLC0415 - shipped next to this file
|
|
2076
|
+
|
|
2077
|
+
shadows = agent_pack_inventory.desktop_shadow_findings(
|
|
2078
|
+
home or Path.home(), [item.name for item in inventory.mcps if _mcp_allowed(layout, item.name, "claude")])
|
|
2079
|
+
if shadows:
|
|
2080
|
+
report["shadowed_by"] = shadows
|
|
2081
|
+
warnings.extend(agent_pack_inventory.shadow_warning(item) for item in shadows)
|
|
1993
2082
|
for kind in ("missing", "different", "stale", "dangling", "missing_env"):
|
|
1994
2083
|
issues.extend(f"{client}: {kind} {item}" for item in report[kind])
|
|
1995
2084
|
if report["coupled"]:
|
|
@@ -2025,6 +2114,15 @@ def _print(value: dict[str, Any], output: str) -> None:
|
|
|
2025
2114
|
summary = value.get("conflicts")
|
|
2026
2115
|
if isinstance(summary, dict):
|
|
2027
2116
|
print("conflicts: " + ", ".join(f"{key}={number}" for key, number in summary.items()))
|
|
2117
|
+
if "by_scope" in value: # a project declares scopes (or --scope was given): group by store
|
|
2118
|
+
import agent_pack_scope # noqa: PLC0415 - shipped next to this file; imported late (python3 -I path set in main)
|
|
2119
|
+
|
|
2120
|
+
for line in agent_pack_scope.grouped_lines(value):
|
|
2121
|
+
print(line)
|
|
2122
|
+
for line in (agent_pack_scope.narrowing_lines(value) + agent_pack_scope.migration_lines(value)
|
|
2123
|
+
+ agent_pack_scope.skipped_lines(value)):
|
|
2124
|
+
print(line)
|
|
2125
|
+
value = {**value, "operations": []}
|
|
2028
2126
|
for operation in value.get("operations", []):
|
|
2029
2127
|
target = operation.get("to") or operation.get("from", "")
|
|
2030
2128
|
print(f"- {operation['action']}: {operation.get('name', '')} -> {target}")
|
|
@@ -2037,6 +2135,13 @@ def _print(value: dict[str, Any], output: str) -> None:
|
|
|
2037
2135
|
|
|
2038
2136
|
|
|
2039
2137
|
def _add_scope_arguments(parser: argparse.ArgumentParser) -> None:
|
|
2138
|
+
parser.add_argument("--scope", choices=("user", "project", "all"), default="all",
|
|
2139
|
+
help="claude: act on the user-level entries only (user), the entries the project declares "
|
|
2140
|
+
"project-level only (project), or both (all, default). Combines with --only")
|
|
2141
|
+
parser.add_argument("--project-store", choices=("local", "file"), default="local",
|
|
2142
|
+
help="claude: where project-level MCP entries go: local (~/.claude.json, under the project's "
|
|
2143
|
+
"path; default) or file (the project's .mcp.json, only for entries that do not depend on "
|
|
2144
|
+
"this machine)")
|
|
2040
2145
|
parser.add_argument("--only", action="append", default=[], metavar="TYPE",
|
|
2041
2146
|
help="claude: sync only these types (repeat or comma separate): mcp, skills, plugins; "
|
|
2042
2147
|
"default is all. plugins = the package and its install record. Other types are left untouched")
|
|
@@ -2059,8 +2164,9 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
2059
2164
|
|
|
2060
2165
|
doctor_parser = sub.add_parser("doctor")
|
|
2061
2166
|
doctor_parser.add_argument("--project", type=Path, default=Path.cwd())
|
|
2062
|
-
doctor_parser.add_argument("--client", action="append", default=[], choices=("codex", "cursor", "claude"),
|
|
2063
|
-
help="also compare this client's installed capabilities with the project (repeatable)"
|
|
2167
|
+
doctor_parser.add_argument("--client", action="append", default=[], choices=("codex", "cursor", "claude", "claude-desktop"),
|
|
2168
|
+
help="also compare this client's installed capabilities with the project (repeatable); "
|
|
2169
|
+
"claude-desktop only reads claude_desktop_config.json and must be named")
|
|
2064
2170
|
doctor_parser.add_argument("--home", type=Path)
|
|
2065
2171
|
|
|
2066
2172
|
transfer_parser = sub.add_parser("transfer")
|
|
@@ -2142,6 +2248,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
2142
2248
|
args.project, args.client, home=args.home, apply=args.apply, replace=args.replace,
|
|
2143
2249
|
reset_overrides=args.reset_overrides, recovery_root=args.recovery_root,
|
|
2144
2250
|
only=args.only, replace_mcp=args.replace_mcp, replace_skills=args.replace_skills,
|
|
2251
|
+
scope=args.scope, project_store=args.project_store,
|
|
2145
2252
|
)
|
|
2146
2253
|
elif args.command == "bootstrap":
|
|
2147
2254
|
result = install_plugin(
|
|
@@ -2168,6 +2275,7 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
2168
2275
|
replace=args.replace,
|
|
2169
2276
|
reset_overrides=args.reset_overrides,
|
|
2170
2277
|
only=args.only, replace_mcp=args.replace_mcp, replace_skills=args.replace_skills,
|
|
2278
|
+
scope=args.scope, project_store=args.project_store,
|
|
2171
2279
|
)
|
|
2172
2280
|
_print(result, args.output)
|
|
2173
2281
|
return 0 if result.get("ok", True) else 1
|