@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.
Files changed (117) hide show
  1. package/package.json +1 -1
  2. package/runtime/index.json +6 -6
  3. package/runtime/plugins/agent-pack/.codex-plugin/plugin.json +1 -1
  4. package/runtime/plugins/agent-pack/plugin.json +1 -1
  5. package/runtime/plugins/agent-pack/references/capability-config.md +10 -0
  6. package/runtime/plugins/agent-pack/references/check-opinion-migrate.en.md +31 -0
  7. package/runtime/plugins/agent-pack/references/check-opinion-migrate.md +31 -0
  8. package/runtime/plugins/agent-pack/references/dedupe-contract.en.md +27 -0
  9. package/runtime/plugins/agent-pack/references/dedupe-contract.md +27 -0
  10. package/runtime/plugins/agent-pack/references/inventory-contract.en.md +83 -0
  11. package/runtime/plugins/agent-pack/references/inventory-contract.md +83 -0
  12. package/runtime/plugins/agent-pack/references/nudge.en.md +10 -2
  13. package/runtime/plugins/agent-pack/references/nudge.md +10 -2
  14. package/runtime/plugins/agent-pack/references/relocate-contract.en.md +41 -0
  15. package/runtime/plugins/agent-pack/references/relocate-contract.md +41 -0
  16. package/runtime/plugins/agent-pack/runtime/agent_pack_claude.py +572 -30
  17. package/runtime/plugins/agent-pack/runtime/agent_pack_clients.py +233 -0
  18. package/runtime/plugins/agent-pack/runtime/agent_pack_config.py +112 -4
  19. package/runtime/plugins/agent-pack/runtime/agent_pack_dedupe.py +502 -0
  20. package/runtime/plugins/agent-pack/runtime/agent_pack_desktop.py +92 -0
  21. package/runtime/plugins/agent-pack/runtime/agent_pack_ext_common.py +251 -0
  22. package/runtime/plugins/agent-pack/runtime/agent_pack_inventory.py +989 -0
  23. package/runtime/plugins/agent-pack/runtime/agent_pack_mcp_write.py +447 -0
  24. package/runtime/plugins/agent-pack/runtime/agent_pack_nudge.py +29 -4
  25. package/runtime/plugins/agent-pack/runtime/agent_pack_relocate.py +385 -0
  26. package/runtime/plugins/agent-pack/runtime/agent_pack_scope.py +233 -0
  27. package/runtime/plugins/agent-pack/runtime/agenthelm.py +183 -14
  28. package/runtime/plugins/agent-pack/runtime/locale/en.json +250 -1
  29. package/runtime/plugins/agent-pack/runtime/mcp_server.py +12 -0
  30. package/runtime/plugins/agent-pack/runtime/nudge_text.py +8 -2
  31. package/runtime/plugins/agent-pack/runtime/user_settings.py +2 -1
  32. package/runtime/plugins/agent-pack/skills/agent-pack/SKILL.md +15 -0
  33. package/runtime/plugins/agents-init/.codex-plugin/plugin.json +1 -1
  34. package/runtime/plugins/agents-init/content.json +4 -2
  35. package/runtime/plugins/agents-init/plugin.json +1 -1
  36. package/runtime/plugins/agents-init/skills/agents-init/SKILL.md +2 -0
  37. package/runtime/plugins/agents-init/skills/agents-init/launcher.en.sh +93 -0
  38. package/runtime/plugins/agents-init/skills/agents-init/project.schema.json +27 -0
  39. package/runtime/plugins/agents-init/skills/agents-init/scripts/baseline.py +4 -1
  40. package/runtime/plugins/agents-init/skills/agents-init/scripts/init_project.py +24 -9
  41. package/runtime/plugins/agents-init/skills/agents-init/skill.json +1 -1
  42. package/runtime/plugins/opinion-manager/.codex-plugin/plugin.json +1 -1
  43. package/runtime/plugins/opinion-manager/catalog/README.md +3 -1
  44. package/runtime/plugins/opinion-manager/catalog/rules/om.align-requirements/versions/1.1.0.json +34 -0
  45. package/runtime/plugins/opinion-manager/catalog/rules/om.assumptions-authority/versions/1.1.0.json +34 -0
  46. package/runtime/plugins/opinion-manager/catalog/rules/om.batch-questions/versions/1.1.0.json +34 -0
  47. package/runtime/plugins/opinion-manager/catalog/rules/om.bilingual-terms/versions/1.1.0.json +34 -0
  48. package/runtime/plugins/opinion-manager/catalog/rules/om.calculations/versions/1.1.0.json +34 -0
  49. package/runtime/plugins/opinion-manager/catalog/rules/om.chinese-response/versions/1.1.0.json +34 -0
  50. package/runtime/plugins/opinion-manager/catalog/rules/om.clean-deliverable/versions/1.1.0.json +34 -0
  51. package/runtime/plugins/opinion-manager/catalog/rules/om.complete-options/versions/1.1.0.json +34 -0
  52. package/runtime/plugins/opinion-manager/catalog/rules/om.conclusion-first/versions/1.1.0.json +34 -0
  53. package/runtime/plugins/opinion-manager/catalog/rules/om.concrete-titles/versions/1.1.0.json +34 -0
  54. package/runtime/plugins/opinion-manager/catalog/rules/om.consistent-items/versions/1.1.0.json +34 -0
  55. package/runtime/plugins/opinion-manager/catalog/rules/om.device-readable/versions/1.1.0.json +34 -0
  56. package/runtime/plugins/opinion-manager/catalog/rules/om.editable-diagrams/versions/1.1.0.json +34 -0
  57. package/runtime/plugins/opinion-manager/catalog/rules/om.evidence-inference/versions/1.1.0.json +34 -0
  58. package/runtime/plugins/opinion-manager/catalog/rules/om.maintenance-chinese/versions/1.1.0.json +34 -0
  59. package/runtime/plugins/opinion-manager/catalog/rules/om.maintenance-project-language/versions/1.1.0.json +34 -0
  60. package/runtime/plugins/opinion-manager/catalog/rules/om.markdown-structure/versions/1.1.0.json +34 -0
  61. package/runtime/plugins/opinion-manager/catalog/rules/om.portable-files/versions/1.1.0.json +34 -0
  62. package/runtime/plugins/opinion-manager/catalog/rules/om.report-context/versions/1.1.0.json +34 -0
  63. package/runtime/plugins/opinion-manager/catalog/rules/om.report-formats/versions/1.1.0.json +34 -0
  64. package/runtime/plugins/opinion-manager/catalog/rules/om.report-review/versions/1.1.0.json +34 -0
  65. package/runtime/plugins/opinion-manager/catalog/rules/om.response-brief/versions/1.1.0.json +34 -0
  66. package/runtime/plugins/opinion-manager/catalog/rules/om.response-dense/versions/1.1.0.json +34 -0
  67. package/runtime/plugins/opinion-manager/catalog/rules/om.rules-tools/versions/1.1.0.json +34 -0
  68. package/runtime/plugins/opinion-manager/catalog/rules/om.semantic-wrap/versions/1.1.0.json +34 -0
  69. package/runtime/plugins/opinion-manager/catalog/rules/om.solutions-proportional/versions/1.1.0.json +34 -0
  70. package/runtime/plugins/opinion-manager/catalog/rules/om.solutions-three-level/versions/1.1.0.json +34 -0
  71. package/runtime/plugins/opinion-manager/catalog/rules/om.tables-compact/versions/1.1.0.json +34 -0
  72. package/runtime/plugins/opinion-manager/catalog/rules/om.tables-list-first/versions/1.1.0.json +34 -0
  73. package/runtime/plugins/opinion-manager/catalog/rules/om.test-evidence/versions/1.1.0.json +34 -0
  74. package/runtime/plugins/opinion-manager/catalog/rules/om.versioned-files/versions/1.1.0.json +34 -0
  75. package/runtime/plugins/opinion-manager/catalog/templates/delivery-standard/compact-tables/versions/1.1.0.json +32 -0
  76. package/runtime/plugins/opinion-manager/catalog/templates/delivery-standard/list-first/versions/1.1.0.json +32 -0
  77. package/runtime/plugins/opinion-manager/catalog/templates/development-standard/chinese-maintenance/versions/1.1.0.json +26 -0
  78. package/runtime/plugins/opinion-manager/catalog/templates/development-standard/project-language/versions/1.1.0.json +26 -0
  79. package/runtime/plugins/opinion-manager/catalog/templates/response-style/brief-chinese/versions/1.1.0.json +30 -0
  80. package/runtime/plugins/opinion-manager/catalog/templates/response-style/dense-chinese/versions/1.1.0.json +30 -0
  81. package/runtime/plugins/opinion-manager/catalog/templates/scenario/concise-project/versions/1.1.0.json +181 -0
  82. package/runtime/plugins/opinion-manager/catalog/templates/scenario/reviewed-project/versions/1.1.0.json +179 -0
  83. package/runtime/plugins/opinion-manager/catalog/templates/work-method/proportional/versions/1.1.0.json +31 -0
  84. package/runtime/plugins/opinion-manager/catalog/templates/work-method/three-level/versions/1.1.0.json +31 -0
  85. package/runtime/plugins/opinion-manager/content.json +44 -3
  86. package/runtime/plugins/opinion-manager/plugin.json +1 -1
  87. package/runtime/plugins/opinion-manager/references/inbox.en.md +25 -4
  88. package/runtime/plugins/opinion-manager/references/inbox.md +25 -4
  89. package/runtime/plugins/opinion-manager/references/profile.schema.json +19 -2
  90. package/runtime/plugins/opinion-manager/references/rule.schema.json +25 -3
  91. package/runtime/plugins/opinion-manager/references/versioned-template.schema.json +5 -4
  92. package/runtime/plugins/opinion-manager/references/versioning.md +89 -4
  93. package/runtime/plugins/opinion-manager/runtime/context.py +26 -19
  94. package/runtime/plugins/opinion-manager/runtime/inbox.py +400 -25
  95. package/runtime/plugins/opinion-manager/runtime/inbox_relations.py +106 -0
  96. package/runtime/plugins/opinion-manager/runtime/inbox_routes.py +132 -0
  97. package/runtime/plugins/opinion-manager/runtime/inbox_text.py +117 -11
  98. package/runtime/plugins/opinion-manager/runtime/lifecycle.py +35 -5
  99. package/runtime/plugins/opinion-manager/runtime/locale/en.json +137 -2
  100. package/runtime/plugins/opinion-manager/runtime/migrate.py +582 -0
  101. package/runtime/plugins/opinion-manager/runtime/opinion_manager.py +9 -4
  102. package/runtime/plugins/opinion-manager/runtime/rule_lines.py +247 -0
  103. package/runtime/plugins/opinion-manager/runtime/tags.py +217 -0
  104. package/runtime/plugins/opinion-manager/runtime/versioned.py +289 -41
  105. package/runtime/plugins/opinion-manager/skills/opinion-manager/SKILL.md +8 -7
  106. package/runtime/plugins/project-orchestrator/.codex-plugin/plugin.json +1 -1
  107. package/runtime/plugins/project-orchestrator/plugin.json +1 -1
  108. package/runtime/plugins/project-orchestrator/runtime/locale/en.json +305 -3
  109. package/runtime/plugins/project-orchestrator/runtime/private_paths.py +11 -1
  110. package/runtime/plugins/project-orchestrator/runtime/project_cli.py +101 -1
  111. package/runtime/plugins/project-orchestrator/runtime/project_demo.py +13 -1
  112. package/runtime/plugins/project-orchestrator/runtime/project_ext_actions.py +415 -0
  113. package/runtime/plugins/project-orchestrator/runtime/project_extensions.py +971 -0
  114. package/runtime/plugins/project-orchestrator/runtime/project_extensions_demo.py +86 -0
  115. package/runtime/plugins/project-orchestrator/runtime/project_menu.py +345 -2
  116. package/runtime/plugins/project-orchestrator/runtime/project_real.py +17 -1
  117. 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