@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,502 @@
1
+ #!/usr/bin/env python3
2
+ """``agenthelm dedupe``: handle one duplicate group reported by ``agenthelm inventory`` (preview by default).
3
+
4
+ Dispositions:
5
+ * ``--keep <ref> --retire-others``: Skill copies are archived (a move into the recovery directory, never a delete);
6
+ MCP copies the project's agent-pack state owns (managed) are removed by ``agent_pack_mcp_write`` (original JSON
7
+ fragment into the 0600 recovery directory, byte-exact backup, atomic edit, byte-exact rollback); every other MCP
8
+ copy only gets the official manual command and a backup reminder (not archivable by the tool).
9
+ * ``--keep-all --note "..."`` / ``--ignore`` / ``--unignore``: write only the machine-level decision file
10
+ (``~/.config/agenthelm/ext-decisions.json``, mode 0600, no values); no configuration is changed.
11
+ * ``--desktop-snippet``: read-only paste-ready ``claude_desktop_config.json`` fragment for the kept MCP entry.
12
+
13
+ A copy whose evidence is ``unknown`` is read-only: it can never be retired. Group ids are stable
14
+ (``kind|client|name-or-fingerprint``), so they do not change when other entries appear.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import hashlib
20
+ import json
21
+ import os
22
+ import re
23
+ import shlex
24
+ import sys
25
+ from datetime import UTC, datetime
26
+ from pathlib import Path
27
+ from typing import Any
28
+
29
+ RUNTIME_DIR = Path(__file__).resolve().parent
30
+ if str(RUNTIME_DIR) not in sys.path:
31
+ sys.path.insert(0, str(RUNTIME_DIR))
32
+ import agent_pack_desktop as desktop # noqa: E402
33
+ import agent_pack_ext_common as ext # noqa: E402
34
+ import agent_pack_inventory as inv # noqa: E402
35
+ import agent_pack_mcp_write as mcp_write # noqa: E402
36
+ from i18n_agent_pack import _, N_ # noqa: E402
37
+
38
+ DECISIONS_SCHEMA = 1
39
+ NOTE_LIMIT = 200
40
+ SECRET_LIKE = re.compile(r"(sk-[A-Za-z0-9]{12,}|gh[pousr]_[A-Za-z0-9]{12,}|xox[abp]-[A-Za-z0-9-]{8,}|Bearer\s+\S{8,}"
41
+ r"|[A-Za-z0-9+/_-]{32,}|://[^/\s:@]+:[^/\s@]+@)")
42
+
43
+
44
+ # Manual-removal commands per client, as data (no per-client branches in the code): a client without an entry only
45
+ # gets an instruction to delete the entry in its file by hand. ``{scope}`` and ``{name}`` are filled in.
46
+ MANUAL_REMOVE = mcp_write.MANUAL_REMOVE
47
+ MANUAL_BACKUP = mcp_write.MANUAL_BACKUP
48
+
49
+
50
+ def decisions_path(home: Path) -> Path:
51
+ return home / ".config" / "agenthelm" / "ext-decisions.json"
52
+
53
+
54
+ # ------------------------------------------------------------------ groups
55
+
56
+ def group_id(kind: str, client: str, key: str) -> str:
57
+ return "g-" + hashlib.sha256(f"{kind}|{client}|{key}".encode("utf-8")).hexdigest()[:10]
58
+
59
+
60
+ def list_groups(report: dict) -> list[dict]:
61
+ """Every duplicate group of the inventory as ``{id, kind, group_kind, client, key, members[], relation, ...}``."""
62
+ groups = []
63
+ for dup in report["duplicates"]["skills"]:
64
+ members = [item for item in report["skills"] if item["client"] == dup["client"] and item["name"] == dup["name"]
65
+ and item["path"] in dup["stores"]]
66
+ groups.append({"id": group_id("skill", dup["client"], dup["name"]), "kind": "skill", "group_kind": "same-name",
67
+ "client": dup["client"], "key": dup["name"], "relation": dup["relation"],
68
+ "effective": dup.get("effective"), "members": members})
69
+ for dup in report["duplicates"]["mcps"]:
70
+ if dup["kind"] == "same-name":
71
+ members = [item for item in report["mcps"] if item["client"] == dup["client"] and item["name"] == dup["names"][0]
72
+ and item["store"] in dup["stores"]]
73
+ key = dup["names"][0]
74
+ else:
75
+ members = [item for item in report["mcps"] if item["client"] == dup["client"]
76
+ and item.get("fingerprint") == dup.get("fingerprint")]
77
+ key = dup["fingerprint"]
78
+ groups.append({"id": group_id("mcp", dup["client"], key), "kind": "mcp", "group_kind": dup["kind"],
79
+ "client": dup["client"], "key": key if dup["kind"] == "same-name" else "|".join(dup["names"]),
80
+ "relation": dup["relation"], "effective": dup.get("effective"), "members": members})
81
+ return groups
82
+
83
+
84
+ def members_digest(group: dict) -> str:
85
+ return hashlib.sha256(ext.canonical(sorted(item["ref"] for item in group["members"])).encode("utf-8")).hexdigest()[:16]
86
+
87
+
88
+ def read_decisions(home: Path) -> dict:
89
+ path = decisions_path(home)
90
+ try:
91
+ data = json.loads(path.read_text(encoding="utf-8"))
92
+ except (OSError, ValueError):
93
+ return {"schema_version": DECISIONS_SCHEMA, "decisions": {}}
94
+ if not isinstance(data, dict) or not isinstance(data.get("decisions"), dict):
95
+ return {"schema_version": DECISIONS_SCHEMA, "decisions": {}}
96
+ return data
97
+
98
+
99
+ def _summary(group: dict, decisions: dict) -> dict:
100
+ decision = decisions["decisions"].get(group["id"])
101
+ state = None
102
+ if decision:
103
+ state = {"decision": decision.get("decision"), "note": decision.get("note", ""), "at": decision.get("at"),
104
+ "stale": decision.get("members_digest") != members_digest(group)}
105
+ return {"id": group["id"], "kind": group["kind"], "group_kind": group["group_kind"], "client": group["client"],
106
+ "key": group["key"], "relation": group["relation"],
107
+ "members": [{"ref": item["ref"], "path": item.get("path") or item.get("store"), "evidence": item["evidence"],
108
+ "precedence": item["precedence"]} for item in group["members"]],
109
+ "decision": state}
110
+
111
+
112
+ def cross_client_hint(report: dict, group: dict) -> list[dict]:
113
+ """D-CB4: the same MCP fingerprint in several clients is intentional by default and is never recommended for retirement."""
114
+ if group["kind"] != "mcp":
115
+ return []
116
+ prints = {item["fingerprint"] for item in group["members"] if item.get("fingerprint")}
117
+ others = sorted({item["ref"] for item in report["mcps"] if item["client"] != group["client"]
118
+ and item.get("fingerprint") in prints})
119
+ return [ext.warning("cross-client-keep-recommended",
120
+ _("其他客户端里有同指纹的条目:跨客户端的相同 MCP 不冲突,建议保留,不推荐退役"), refs=others)] if others else []
121
+
122
+
123
+ # ------------------------------------------------------------------ plan
124
+
125
+ def build_plan(home: Path, project: Path, group: str, keep: str | None, retire_others: bool, keep_all: bool,
126
+ ignore: bool, unignore: bool, note: str | None, recovery_override: Path | None = None) -> tuple[dict, dict]:
127
+ home = home.expanduser().resolve()
128
+ project = project.expanduser().resolve()
129
+ report = inv.observe(home, project, None, "all", "all")
130
+ decisions = read_decisions(home)
131
+ plan: dict[str, Any] = {
132
+ "group": group, "kind": None, "disposition": None, "status": "blocked", "members": [], "steps": [],
133
+ "blocked": [], "warnings": [], "manual": [], "keep": keep, "retire": [],
134
+ "recovery_base": ext.display(ext.recovery_base(home, recovery_override), home, project),
135
+ }
136
+ ctx: dict[str, Any] = {"home": home, "project": project, "recovery_override": recovery_override, "report": report}
137
+ blocks = plan["blocked"]
138
+ chosen = [flag for flag, on in (("retire-others", retire_others), ("keep-all", keep_all), ("ignore", ignore),
139
+ ("unignore", unignore)) if on]
140
+ if len(chosen) != 1:
141
+ blocks.append(ext.blocked("choose-one-disposition", _("必须且只能选一个:--keep <ref> --retire-others、--keep-all、--ignore、--unignore")))
142
+ return _finish(plan), ctx
143
+ plan["disposition"] = chosen[0]
144
+ found = next((item for item in list_groups(report) if item["id"] == group), None)
145
+ if found is None:
146
+ blocks.append(ext.blocked("group-not-found", _("没有这个重复分组;先用 --list 查看"),
147
+ candidates=[item["id"] for item in list_groups(report)]))
148
+ return _finish(plan), ctx
149
+ plan["kind"] = found["kind"]
150
+ plan["members"] = _summary(found, decisions)["members"]
151
+ plan["members_digest"] = members_digest(found)
152
+ plan["existing_decision"] = (decisions["decisions"].get(group) or {}).get("decision")
153
+ plan["warnings"].extend(cross_client_hint(report, found))
154
+ ctx["group"] = found
155
+
156
+ if chosen[0] in ("keep-all", "ignore", "unignore"):
157
+ _plan_decision(plan, ctx, found, chosen[0], note, decisions)
158
+ else:
159
+ _plan_retire(plan, ctx, found, keep, home, project)
160
+ plan["status"] = "blocked" if blocks else ("manual-only" if plan["manual"] and not plan["retire"] else "ready")
161
+ return _finish(plan), ctx
162
+
163
+
164
+ def _plan_decision(plan: dict, ctx: dict, group: dict, which: str, note: str | None, decisions: dict) -> None:
165
+ blocks = plan["blocked"]
166
+ if which == "keep-all":
167
+ if not note or not note.strip():
168
+ blocks.append(ext.blocked("note-required", _("--keep-all 需要 --note 写明保留理由")))
169
+ elif len(note) > NOTE_LIMIT:
170
+ blocks.append(ext.blocked("note-too-long", _("备注最长 {0} 个字符").format(NOTE_LIMIT)))
171
+ elif SECRET_LIKE.search(note):
172
+ blocks.append(ext.blocked("note-looks-like-secret", _("备注疑似含有令牌或口令,不写入;决定文件不保存任何凭据")))
173
+ if which == "unignore" and plan["existing_decision"] != "ignore":
174
+ blocks.append(ext.blocked("not-ignored", _("这个分组当前不是 ignore 状态")))
175
+ if blocks:
176
+ return
177
+ decision = {"keep-all": "keep-all", "ignore": "ignore", "unignore": None}[which]
178
+ plan["decision"] = {"decision": decision, "note": (note or "").strip() if which == "keep-all" else "",
179
+ "members_digest": plan["members_digest"]}
180
+ plan["steps"].append(ext.step("s1", "write-decision" if decision else "remove-decision", "certain",
181
+ to="~/.config/agenthelm/ext-decisions.json"))
182
+ plan["warnings"].append(ext.warning("config-untouched", _("只写决定文件,不改任何客户端配置")))
183
+ ctx["decisions"] = decisions
184
+
185
+
186
+ def _plan_retire(plan: dict, ctx: dict, group: dict, keep: str | None, home: Path, project: Path) -> None:
187
+ blocks = plan["blocked"]
188
+ members = group["members"]
189
+ kept = next((item for item in members if item["ref"] == keep), None)
190
+ if keep is None:
191
+ blocks.append(ext.blocked("keep-required", _("--retire-others 需要 --keep <ref>"), candidates=[m["ref"] for m in members]))
192
+ return
193
+ if kept is None:
194
+ blocks.append(ext.blocked("keep-not-in-group", _("--keep 的引用不在这个分组里"), candidates=[m["ref"] for m in members]))
195
+ return
196
+ others = [item for item in members if item is not kept]
197
+ for item in members:
198
+ if item["evidence"] != "file":
199
+ blocks.append(ext.blocked("evidence-unknown", _("{0} 没有文件级证据:只读,不能退役").format(item["ref"]), ref=item["ref"]))
200
+ if blocks:
201
+ return
202
+ if group["kind"] == "mcp":
203
+ _plan_mcp(plan, ctx, group, kept, others, home, project)
204
+ return
205
+ kept_real = os.path.realpath(_entry_path(kept, home, project))
206
+ for item in others:
207
+ path = _entry_path(item, home, project)
208
+ real = os.path.realpath(path)
209
+ if not path.is_symlink() and (kept_real == real or kept_real.startswith(real + os.sep)):
210
+ blocks.append(ext.blocked("keep-depends-on-retired", _("保留的条目依赖要退役的目录:{0}").format(item["ref"]), ref=item["ref"]))
211
+ if blocks:
212
+ return
213
+ if group["relation"] == "different":
214
+ plan["warnings"].append(ext.warning("content-differs", _("各副本内容不同:退役的副本只是归档,之后可手工移回")))
215
+ steps = plan["steps"]
216
+ steps.append(ext.step("s1", "create-recovery-dir", "certain", to=plan["recovery_base"]))
217
+ several = len(others) > 1
218
+ for index, item in enumerate(others, start=1):
219
+ bucket_name = item["name"] if not several else f"{item['name']}@" + re.sub(r"[^A-Za-z0-9]+", "-", item["store"]).strip("-")
220
+ plan["retire"].append({"ref": item["ref"], "path": item["path"], "bucket_name": bucket_name,
221
+ "content_sha256": item["content_sha256"], "is_symlink": item["is_symlink"]})
222
+ steps.append(ext.step(f"s{index + 1}", "archive-copy", "certain", **{"from": item["path"], "bucket_name": bucket_name}))
223
+ if item["origin"]["type"] in ("plugin", "marketplace"):
224
+ plan["warnings"].append(ext.warning("managed-origin", _("{0} 由插件管理:退役后下次同步可能又会出现").format(item["ref"]), ref=item["ref"]))
225
+ steps.append(ext.step(f"s{len(others) + 2}", "confirm-in-client", "best-effort", client=group["client"]))
226
+ ctx["kept_path"] = kept_real
227
+
228
+
229
+ def _plan_mcp(plan: dict, ctx: dict, group: dict, kept: dict, others: list[dict], home: Path, project: Path) -> None:
230
+ """Managed copies (the project's agent-pack state owns them) are retired by the tool; the rest only get the official
231
+ manual command, flagged as not archivable by this tool."""
232
+ root, package, _layout = mcp_write._root_and_package(project)
233
+ ctx["root"], ctx["package"], ctx["retire_items"] = root, package, []
234
+ steps = plan["steps"]
235
+ managed: list[dict] = []
236
+ for item in others:
237
+ raw, problem = (mcp_write.read_entry(home, root, item["scope"], item["name"])
238
+ if item["client"] in mcp_write.MCP_WRITERS else (None, "unsupported"))
239
+ owner = mcp_write.ownership(home, package, item["scope"], item["name"]) if raw is not None and not problem else None
240
+ if owner and owner["managed"] and isinstance(raw, dict):
241
+ store = mcp_write.STORE_PATH[item["scope"]]
242
+ managed.append({"ref": item["ref"], "client": item["client"], "scope": item["scope"], "store": store,
243
+ "name": item["name"], "managed": True, "entry_digest": mcp_write.entry_hash(raw)[:16]})
244
+ ctx["retire_items"].append({"scope": item["scope"], "name": item["name"], "entry": raw})
245
+ if owner["recorded_hash"] and owner["recorded_hash"] != mcp_write.entry_hash(raw):
246
+ plan["warnings"].append(ext.warning("modified-since-sync", _("{0} 自上次同步后被改过:仍按受管处理,原片段会完整存入恢复目录").format(item["ref"]), ref=item["ref"]))
247
+ else:
248
+ plan["manual"].append(mcp_write.manual_entry(item["ref"], item["client"], item["scope"], item["store"], item["name"]))
249
+ if managed:
250
+ plan["retire"] = managed
251
+ steps.append(ext.step("s1", "create-recovery-dir", "certain", to=plan["recovery_base"]))
252
+ for entry in managed:
253
+ steps.append(ext.step(f"s{len(steps) + 1}", "retire-mcp-entry", "certain", name=entry["name"], **{"from": entry["store"]}))
254
+ steps.append(ext.step(f"s{len(steps) + 1}", "drop-state", "certain", name=entry["name"]))
255
+ for entry in plan["manual"]:
256
+ steps.append(ext.step(f"s{len(steps) + 1}", "manual-remove-mcp", "cannot-promise", ref=entry["ref"]))
257
+ if plan["manual"]:
258
+ plan["warnings"].append(ext.warning("mcp-not-archivable", _("MCP 副本不可由工具归档:配置文件可能含本地凭据,本工具不编辑它,只给手工命令")))
259
+ if group["client"] in MANUAL_BACKUP:
260
+ plan["warnings"].append(ext.warning("backup-first", _("先自己备份 ~/.claude.json,再执行下面的命令")))
261
+ else:
262
+ plan["warnings"].append(ext.warning("backup-first", _("先自己备份相关配置文件,再手工修改")))
263
+ if (group.get("effective") or {}).get("evidence") != "file":
264
+ plan["warnings"].append(ext.warning("precedence-unknown", _("哪一份生效官方文档没有给出(或需要读设置),请自行确认后再执行")))
265
+ if managed:
266
+ steps.append(ext.step(f"s{len(steps) + 1}", "confirm-in-client", "best-effort", client=group["client"]))
267
+
268
+
269
+ def _entry_path(item: dict, home: Path, project: Path) -> Path:
270
+ root = inv.resolve_store(item["store"], home, project)
271
+ return root / item["name"]
272
+
273
+
274
+ def _finish(plan: dict) -> dict:
275
+ plan["plan_digest"] = ext.plan_digest(plan)
276
+ return plan
277
+
278
+
279
+ # ------------------------------------------------------------------ apply
280
+
281
+ def apply_plan(plan: dict, ctx: dict) -> dict:
282
+ home, project = ctx["home"], ctx["project"]
283
+ if plan["disposition"] in ("keep-all", "ignore", "unignore"):
284
+ return _apply_decision(plan, ctx)
285
+ if not plan["retire"]:
286
+ return {"status": "manual-only", "written": False, "manual": plan["manual"]}
287
+ if plan["kind"] == "mcp":
288
+ return _apply_mcp(plan, ctx)
289
+ moved: list[tuple[Path, Path]] = []
290
+ recovery: Path | None = None
291
+ try:
292
+ recovery = ext.new_recovery_dir(ext.recovery_base(home, ctx["recovery_override"]), f"dedupe-{plan['group']}")
293
+ ext.write_private_json(recovery / "dedupe.json", {
294
+ "schema_version": ext.SCHEMA_VERSION, "group": plan["group"], "keep": plan["keep"], "plan_digest": plan["plan_digest"],
295
+ "retired": [{"ref": item["ref"], "path": item["path"], "archived_as": item["bucket_name"]} for item in plan["retire"]]})
296
+ for item in plan["retire"]:
297
+ report_item = next(entry for entry in ctx["group"]["members"] if entry["ref"] == item["ref"])
298
+ path = _entry_path(report_item, home, project)
299
+ moved.append((ext.archive(path, recovery, "skills", item["bucket_name"]), path))
300
+ if not _kept_still_intact(ctx):
301
+ raise ext.ExtError("the kept copy changed while retiring")
302
+ except Exception as exc: # noqa: BLE001
303
+ ext.rollback_moves(moved)
304
+ return {"status": "rolled-back", "written": False, "reason": type(exc).__name__,
305
+ "message": _("失败,已回滚:{0}").format(str(exc)),
306
+ "recovery_dir": ext.display(recovery, home, project) if recovery else None}
307
+ return {"status": "applied", "written": True, "recovery_dir": ext.display(recovery, home, project),
308
+ "archived": [ext.display(a, home, project) for a, _o in moved],
309
+ "restore": [ext.restore_line(a, o, home) for a, o in moved],
310
+ "restore_note": _("恢复:把归档目录移回原位(本版没有 restore 命令)")}
311
+
312
+
313
+ def _apply_mcp(plan: dict, ctx: dict) -> dict:
314
+ home, project = ctx["home"], ctx["root"]
315
+ recovery: Path | None = None
316
+ try:
317
+ recovery = ext.new_recovery_dir(ext.recovery_base(home, ctx["recovery_override"]), f"dedupe-{plan['group']}")
318
+ ext.write_private_json(recovery / "dedupe.json", {
319
+ "schema_version": ext.SCHEMA_VERSION, "group": plan["group"], "keep": plan["keep"], "plan_digest": plan["plan_digest"],
320
+ "retired": [{"ref": item["ref"], "store": item["store"], "entry_digest": item["entry_digest"]} for item in plan["retire"]]})
321
+ result = mcp_write.retire_group(home, project, recovery, ctx["package"], ctx["retire_items"])
322
+ except Exception as exc: # noqa: BLE001
323
+ return {"status": "rolled-back", "written": False, "reason": type(exc).__name__,
324
+ "message": _("失败,已回滚:{0}").format(str(exc)),
325
+ "recovery_dir": ext.display(recovery, home, project) if recovery else None}
326
+ return {"status": "applied", "written": True, "recovery_dir": ext.display(recovery, home, project),
327
+ "archived": [ext.display(path, home, project) for path in result["fragments"]],
328
+ "restore": mcp_write.restore_lines(recovery, home, result["fragments"], result["edits"]),
329
+ "manual": plan["manual"]}
330
+
331
+
332
+ def _kept_still_intact(ctx: dict) -> bool:
333
+ return Path(ctx["kept_path"]).is_dir() and (Path(ctx["kept_path"]) / "SKILL.md").is_file()
334
+
335
+
336
+ def _apply_decision(plan: dict, ctx: dict) -> dict:
337
+ home = ctx["home"]
338
+ path = decisions_path(home)
339
+ data = read_decisions(home)
340
+ decision = plan["decision"]
341
+ try:
342
+ if decision["decision"] is None:
343
+ data["decisions"].pop(plan["group"], None)
344
+ else:
345
+ group = ctx["group"]
346
+ data["decisions"][plan["group"]] = {
347
+ "decision": decision["decision"], "note": decision["note"], "kind": group["kind"], "client": group["client"],
348
+ "key": group["key"], "members_digest": decision["members_digest"],
349
+ "at": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")}
350
+ data["schema_version"] = DECISIONS_SCHEMA
351
+ ext.write_private_json(path, data)
352
+ except OSError as exc:
353
+ return {"status": "failed", "written": False, "message": _("失败:{0}").format(type(exc).__name__)}
354
+ return {"status": "applied", "written": True, "decision_file": "~/.config/agenthelm/ext-decisions.json",
355
+ "decision": decision["decision"]}
356
+
357
+
358
+ # ------------------------------------------------------------------ text
359
+
360
+ ACTION_TEXT = {
361
+ "create-recovery-dir": N_("在 {to} 下建恢复目录(权限 0700)"),
362
+ "archive-copy": N_("归档 {from} 到恢复目录(归档不是删除)"),
363
+ "confirm-in-client": N_("下一步:重启 {client} 或重新进入项目,确认结果(工具不执行客户端命令)"),
364
+ "manual-remove-mcp": N_("{ref}:不可由工具归档,见下面的手工命令"),
365
+ "retire-mcp-entry": mcp_write.ACTION_TEXT["retire-mcp-entry"],
366
+ "drop-state": N_("从 agent-pack 的归属记录里去掉 {name}"),
367
+ "write-decision": N_("写入决定文件 {to}(权限 0600,不含任何值)"),
368
+ "remove-decision": N_("从决定文件 {to} 移除这个分组的决定"),
369
+ }
370
+
371
+
372
+ def render_list(groups: list[dict], decisions: dict) -> str:
373
+ if not groups:
374
+ return _("没有发现重复分组。") + "\n"
375
+ lines = [_("重复分组(用 id 调用 dedupe):")]
376
+ for group in groups:
377
+ info = _summary(group, decisions)
378
+ decision = ""
379
+ if info["decision"]:
380
+ decision = " " + _("[已决定:{0}{1}]").format(info["decision"]["decision"], _(",过期") if info["decision"]["stale"] else "")
381
+ lines.append(f"- {group['id']} {group['kind']}/{group['group_kind']} {group['client']} {group['key']} ({group['relation']}){decision}")
382
+ for member in info["members"]:
383
+ lines.append(f" {member['ref']} {member['path']} [{member['evidence']}]")
384
+ return "\n".join(lines) + "\n"
385
+
386
+
387
+ def render_text(plan: dict, applied: dict | None, command: str) -> str:
388
+ lines = [_("agenthelm dedupe:预览(未写入任何文件)") if applied is None else _("agenthelm dedupe:已执行")]
389
+ lines.append(_("分组:{0}({1})").format(plan["group"], plan["kind"] or "-"))
390
+ for member in plan["members"]:
391
+ lines.append(f" {member['ref']} {member['path']} [{member['evidence']}]")
392
+ for entry in plan["steps"]:
393
+ lines.append(f" {entry['id']} [{entry['promise']}] " + _(ACTION_TEXT[entry["action"]]).format(**entry))
394
+ for entry in plan["manual"]:
395
+ lines.append(_("手工(不可由工具归档):{0}").format(entry.get("command") or entry.get("instruction")))
396
+ if entry.get("backup"):
397
+ lines.append(_(" 先备份:{0}").format(entry["backup"]))
398
+ for warning in plan["warnings"]:
399
+ lines.append(_("注意:{0}").format(warning["message"]))
400
+ for entry in plan["blocked"]:
401
+ lines.append(_("已阻止 [{0}]:{1}").format(entry["code"], entry["message"]))
402
+ for candidate in entry.get("candidates", []):
403
+ lines.append(f" - {candidate}")
404
+ if applied is None:
405
+ lines.append(_("计划指纹:{0}").format(plan["plan_digest"]))
406
+ if plan["status"] == "ready":
407
+ lines.append(_("确认后执行:{0}").format(command))
408
+ else:
409
+ lines.append(_("结果:{0}").format(applied["status"]))
410
+ if applied.get("message"):
411
+ lines.append(applied["message"])
412
+ if applied.get("recovery_dir"):
413
+ lines.append(_("恢复目录:{0}").format(applied["recovery_dir"]))
414
+ for line in applied.get("restore", []):
415
+ lines.append(_("手工恢复:{0}").format(line))
416
+ return "\n".join(lines) + "\n"
417
+
418
+
419
+ # ------------------------------------------------------------------ CLI
420
+
421
+ def run(args: Any, home: Path) -> int:
422
+ """Exit codes: 0 ok / preview without blockers, 1 blockers or failure, 2 usage."""
423
+ if args.lang and args.lang != "auto":
424
+ os.environ["AGENTHELM_LANG"] = args.lang
425
+ if sys.platform != "darwin" and not sys.platform.startswith("linux"):
426
+ sys.stderr.write(_("只支持 macOS 与 Linux\n"))
427
+ return 2
428
+ if args.apply and not args.expect_plan:
429
+ sys.stderr.write(_("--apply 必须带 --expect-plan <计划指纹>(先预览取得)\n"))
430
+ return 2
431
+ project = (args.project or Path.cwd()).resolve()
432
+ home = home.expanduser().resolve()
433
+ if args.list or args.group is None:
434
+ report = inv.observe(home, project, None, "all", "all")
435
+ groups = list_groups(report)
436
+ decisions = read_decisions(home)
437
+ if args.output == "json":
438
+ print(json.dumps({"schema_version": ext.SCHEMA_VERSION, "command": "dedupe", "mode": "list",
439
+ "groups": [_summary(group, decisions) for group in groups]}, ensure_ascii=False, indent=2))
440
+ else:
441
+ sys.stdout.write(render_list(groups, decisions))
442
+ return 0
443
+ if args.desktop_snippet:
444
+ return _run_snippet(args, home, project)
445
+ plan, ctx = build_plan(home, project, args.group, args.keep, args.retire_others, args.keep_all, args.ignore,
446
+ args.unignore, args.note, getattr(args, "recovery_root", None))
447
+ command = _command_text(args, plan)
448
+ plan["next"] = {"apply": command}
449
+ applied = None
450
+ code = 1 if plan["blocked"] else 0
451
+ if args.apply:
452
+ if plan["plan_digest"] != args.expect_plan:
453
+ applied = {"status": "refused", "reason": "plan-digest-mismatch", "written": False,
454
+ "message": _("计划指纹与预览不一致(源、目标或参数已变化),未写入;请重新预览。当前指纹:{0}").format(plan["plan_digest"])}
455
+ code = 1
456
+ elif plan["blocked"]:
457
+ applied = {"status": "refused", "reason": "blocked", "written": False}
458
+ else:
459
+ applied = apply_plan(plan, ctx)
460
+ code = 0 if applied["status"] in ("applied", "manual-only") else 1
461
+ if args.output == "json":
462
+ print(json.dumps({"schema_version": ext.SCHEMA_VERSION, "command": "dedupe",
463
+ "mode": "apply" if args.apply else "preview", "plan": plan, "applied": applied},
464
+ ensure_ascii=False, indent=2))
465
+ else:
466
+ sys.stdout.write(render_text(plan, applied, command))
467
+ return code
468
+
469
+
470
+ def _run_snippet(args: Any, home: Path, project: Path) -> int:
471
+ report = inv.observe(home, project, None, "mcp", "all")
472
+ group = next((item for item in list_groups(report) if item["id"] == args.group), None)
473
+ entry = None
474
+ if group is not None and args.keep:
475
+ entry = next((item for item in group["members"] if item["ref"] == args.keep), None)
476
+ if entry is None:
477
+ document = {"ref": args.keep, "path": desktop.config_path(), "snippet": None, "notes": [], "promise": "cannot-promise",
478
+ "blocked": [ext.blocked("keep-required", _("--desktop-snippet 需要有效的分组 id 和 --keep <mcp 引用>"),
479
+ candidates=[m["ref"] for m in group["members"]] if group else [])]}
480
+ else:
481
+ document = desktop.build(entry)
482
+ if args.output == "json":
483
+ print(json.dumps({"schema_version": ext.SCHEMA_VERSION, "command": "dedupe", "mode": "desktop-snippet",
484
+ "desktop": document}, ensure_ascii=False, indent=2))
485
+ else:
486
+ sys.stdout.write(desktop.render_text(document))
487
+ return 1 if document["blocked"] else 0
488
+
489
+
490
+ def _command_text(args: Any, plan: dict) -> str:
491
+ parts = [args.group]
492
+ if args.keep:
493
+ parts += ["--keep", shlex.quote(args.keep)]
494
+ for flag, on in (("--retire-others", args.retire_others), ("--keep-all", args.keep_all), ("--ignore", args.ignore),
495
+ ("--unignore", args.unignore)):
496
+ if on:
497
+ parts.append(flag)
498
+ if args.note:
499
+ parts += ["--note", shlex.quote(args.note)]
500
+ if args.project:
501
+ parts += ["--project", shlex.quote(str(args.project))]
502
+ return f"agenthelm dedupe {' '.join(parts)} --apply --expect-plan {plan['plan_digest']}"
@@ -0,0 +1,92 @@
1
+ #!/usr/bin/env python3
2
+ """Read-only paste-ready snippet for Claude Desktop's ``claude_desktop_config.json`` (writes nothing, ever).
3
+
4
+ Built from an ``agenthelm inventory`` MCP entry, which is already redacted: only the structure (``command``, ``args``,
5
+ ``url``) and variable *names* appear; every credential is a placeholder. An entry with an inline secret is blocked and
6
+ produces no snippet at all.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import sys
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ RUNTIME_DIR = Path(__file__).resolve().parent
16
+ if str(RUNTIME_DIR) not in sys.path:
17
+ sys.path.insert(0, str(RUNTIME_DIR))
18
+ import agent_pack_ext_common as ext # noqa: E402
19
+ import agent_pack_inventory as inv # noqa: E402
20
+ from i18n_agent_pack import _ # noqa: E402
21
+
22
+ REDACTED = "<redacted>"
23
+
24
+
25
+ def config_path(platform: str | None = None) -> str | None:
26
+ """Documented location of ``claude_desktop_config.json`` (the inventory owns the platform table)."""
27
+ return inv.desktop_store(platform)
28
+
29
+
30
+ def placeholder(variable: str) -> str:
31
+ return _("<在此填入你的 {0}>").format(variable)
32
+
33
+
34
+ def build(entry: dict, platform: str | None = None) -> dict:
35
+ """``{path, snippet, blocked, notes, restart}`` for one inventory MCP entry (no file is read or written)."""
36
+ path = config_path(platform)
37
+ result: dict[str, Any] = {"ref": entry["ref"], "path": path, "snippet": None, "blocked": [], "notes": [],
38
+ "promise": "cannot-promise",
39
+ "restart": _("保存后请完全退出并重启 Claude Desktop")}
40
+ if path is None:
41
+ result["blocked"].append(ext.blocked("unsupported-platform", _("只支持 macOS 与 Linux")))
42
+ return result
43
+ if entry.get("evidence") != "file":
44
+ result["blocked"].append(ext.blocked("evidence-unknown", _("这个条目没有文件级证据,只读")))
45
+ if entry.get("has_inline_secret"):
46
+ result["blocked"].append(ext.blocked(
47
+ "inline-secret", _("这个条目含有内联的凭据值:不生成片段。请先把凭据改成环境变量引用,再重新运行")))
48
+ if result["blocked"]:
49
+ return result
50
+ server: dict[str, Any] = {}
51
+ transport = entry.get("transport")
52
+ if entry.get("command"):
53
+ server["command"] = entry["command"]
54
+ args = [placeholder(_("凭据")) if str(arg) == REDACTED else arg for arg in entry.get("args") or []]
55
+ if any(str(arg) == REDACTED for arg in entry.get("args") or []):
56
+ result["notes"].append(ext.warning("args-redacted", _("参数里有被脱敏的值,已换成占位符,请自行填入")))
57
+ if args:
58
+ server["args"] = args
59
+ elif entry.get("url"):
60
+ server["url"] = placeholder("URL") if REDACTED in str(entry["url"]) else entry["url"]
61
+ result["notes"].append(ext.warning("remote-unconfirmed",
62
+ _("官方文档没有说明 claude_desktop_config.json 是否加载远程 url 条目:未确认")))
63
+ else:
64
+ result["blocked"].append(ext.blocked("no-launch-spec", _("条目里没有 command 或 url,无法生成片段")))
65
+ return result
66
+ names = list(entry.get("env_names") or [])
67
+ if names:
68
+ server["env"] = {name: placeholder(name) for name in names}
69
+ if entry.get("header_names"):
70
+ result["notes"].append(ext.warning("headers-not-included", _("请求头 {0} 未写入片段:Desktop 是否支持未确认").format(
71
+ ", ".join(entry["header_names"])), header_names=list(entry["header_names"])))
72
+ if transport == "sse":
73
+ result["notes"].append(ext.warning("sse-transport", _("这是 SSE 传输;Desktop 是否加载未确认")))
74
+ result["snippet"] = {"mcpServers": {entry["name"]: server}}
75
+ result["notes"].append(ext.warning("desktop-load-unknown", _("Desktop 是否会加载这一项没有可核实的证据,工具只给出文件内容")))
76
+ return result
77
+
78
+
79
+ def render_text(document: dict) -> str:
80
+ import json # noqa: PLC0415
81
+ lines = [_("Claude Desktop 配置片段(只读输出,不写任何文件):{0}").format(document["ref"])]
82
+ lines.append(_("目标文件:{0}").format(document["path"] or "-"))
83
+ for item in document["blocked"]:
84
+ lines.append(_("已阻止 [{0}]:{1}").format(item["code"], item["message"]))
85
+ if document["snippet"] is not None:
86
+ lines.append(_("把下面的内容合并进文件里的 mcpServers(已有同名条目先自行比较):"))
87
+ lines.append(json.dumps(document["snippet"], ensure_ascii=False, indent=2))
88
+ for item in document["notes"]:
89
+ lines.append(_("注意:{0}").format(item["message"]))
90
+ if document["snippet"] is not None:
91
+ lines.append(document["restart"])
92
+ return "\n".join(lines) + "\n"