@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
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sakanano-moe/agenthelm",
|
|
3
|
-
"version": "6.
|
|
3
|
+
"version": "6.14.0",
|
|
4
4
|
"description": "agenthelm CLI: install, check and update the agenthelm plugins for Claude Code, Codex and Cursor; a user-level runtime; and a project menu that works without any AI agent.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"bin": {
|
package/runtime/index.json
CHANGED
|
@@ -4,14 +4,14 @@
|
|
|
4
4
|
"name": "agenthelm",
|
|
5
5
|
"description": "Cross-agent project management plugins: project contract, lifecycle, extension capabilities and behavior rules. 跨 Agent 的项目管理插件集。",
|
|
6
6
|
"version": "0.7.0",
|
|
7
|
-
"updated_at": "2026-11-
|
|
7
|
+
"updated_at": "2026-11-21",
|
|
8
8
|
"homepage": "./index.html",
|
|
9
9
|
"domain": "agenthelm.sakanano.moe",
|
|
10
10
|
"legacy_domain": "skill.sakanano.moe"
|
|
11
11
|
},
|
|
12
12
|
"plugin": {
|
|
13
13
|
"manifest": "./plugins/agents-init/plugin.json",
|
|
14
|
-
"version": "6.
|
|
14
|
+
"version": "6.14.0",
|
|
15
15
|
"install_unit": "marketplace",
|
|
16
16
|
"bundled_plugins": [
|
|
17
17
|
"./plugins/project-orchestrator/plugin.json",
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"id": "agents-init",
|
|
31
31
|
"name": "agents-init v6 / Project Profile initialization and migration",
|
|
32
32
|
"description": "Create or migrate the project skeleton and root launcher; checks that project-orchestrator, agent-pack and opinion-manager from the same release are present before writing.",
|
|
33
|
-
"version": "6.
|
|
33
|
+
"version": "6.10.0",
|
|
34
34
|
"status": "stable",
|
|
35
35
|
"entrypoints": {
|
|
36
36
|
"browser": "./plugins/agents-init/skills/agents-init/index.html",
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
"id": "project-orchestrator",
|
|
44
44
|
"name": "project-orchestrator / project lifecycle orchestration",
|
|
45
45
|
"description": "Organizes Case workspaces or keeps existing Task/Case layouts; search, lossless migration, verification, scoped Git delivery, and a project menu that works without any AI agent.",
|
|
46
|
-
"version": "1.
|
|
46
|
+
"version": "1.12.0",
|
|
47
47
|
"status": "stable",
|
|
48
48
|
"entrypoints": {
|
|
49
49
|
"agent": "./plugins/project-orchestrator/skills/project-orchestrator/SKILL.md",
|
|
@@ -55,7 +55,7 @@
|
|
|
55
55
|
"id": "agent-pack",
|
|
56
56
|
"name": "agent-pack / Agent extension capability management",
|
|
57
57
|
"description": "Inventory, verify, install, sync, migrate and reconcile Plugins, Skills and MCP between projects and Codex / Cursor / Claude; the agenthelm command line and user-level runtime.",
|
|
58
|
-
"version": "1.
|
|
58
|
+
"version": "1.14.0",
|
|
59
59
|
"status": "stable",
|
|
60
60
|
"entrypoints": {
|
|
61
61
|
"agent": "./plugins/agent-pack/skills/agent-pack/SKILL.md",
|
|
@@ -68,7 +68,7 @@
|
|
|
68
68
|
"id": "opinion-manager",
|
|
69
69
|
"name": "opinion-manager / Agent behavior rule management",
|
|
70
70
|
"description": "Three first-run entry points plus optional memory candidates; one content confirmation, then Profile, body and lock are saved separately, with exact versions and protection of personal edits.",
|
|
71
|
-
"version": "0.
|
|
71
|
+
"version": "0.7.0",
|
|
72
72
|
"status": "experimental",
|
|
73
73
|
"entrypoints": {
|
|
74
74
|
"agent": "./plugins/opinion-manager/skills/opinion-manager/SKILL.md",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
|
|
3
3
|
"name": "agent-pack",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.14.0",
|
|
5
5
|
"description": "Deterministic Agent-extension capability management: inventory, doctor, bootstrap, sync, transfer, and reconcile Agent Plugins / Skills / MCP servers across Codex, Cursor, Claude Code, and project sources. Ships a stdio MCP.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "lc4t"
|
|
@@ -77,6 +77,16 @@ python3 /path/to/agent-pack/runtime/agent_pack_config.py --output json bootstrap
|
|
|
77
77
|
- 预览和结果在有冲突时给出 `conflicts`(按类型计数),并在 `warnings` 里提示:用户级 Skill 与 MCP 条目对所有项目生效,被替换的原件进恢复目录。
|
|
78
78
|
- 显式的 `--retire-skill` / `--retire-plugin` 不受 `--only` 过滤。Codex 与 Cursor 把 Skill、MCP 与清单装在同一个包里,只接受全部类型(`--only mcp,skills,plugins` 等价于不带);部分选择与 `--replace-skills` 会明确报错、不写入。`--replace-mcp` 在 Codex 等同于对原生远程 MCP 条目使用 `--replace`。`bootstrap` 已有按名称选择的 `--skill` / `--mcp`,不增加 `--only`。
|
|
79
79
|
|
|
80
|
+
- **作用域声明(`capabilities.default_scope` / `mcp_scope` / `skill_scope`,#67)**:`default_scope` 取 `user`(缺省,对本机所有项目生效)或 `project`(只对本项目生效);`mcp_scope`、`skill_scope` 是「名称 → `user|project`」的映射,覆盖 `default_scope`。取值非法会明确报错。旧版运行时忽略这些键。不写这些键时,`sync` / `reconcile` 的输出、`state` 与磁盘内容与以前完全相同。`--project-store local|file`(缺省 `local`,仅 Claude;MCP Tool 参数 `projectStore`)选择项目级 MCP 的存储。
|
|
81
|
+
- 声明为 `project` 的条目**不会写到用户级**。Claude 的 MCP 条目写到 `--project-store` 指定的位置:`local`(缺省)是 `~/.claude.json` 里 `projects[<项目绝对路径>].mcpServers`(私有、不进版本库;该位置是否弹批准,官方文档未说明,**未确认**);`file` 是项目根 `.mcp.json`,**只允许与机器无关的条目**,命令、参数、工作目录或 env 里含绝对路径、`~`、家目录或本项目路径的条目被拒绝(报错只列字段名,如 `args[0]`,不含值),`.mcp.json` 条目也不保留本机认证值。写 local 时先把原 `~/.claude.json` 备份到恢复目录 `claude.json.before`(权限 `0600`,是用户自己文件的原样副本,输出与我们生成的元数据里没有任何值),原子改写并保持原权限,任一步失败按字节恢复原文件。目标不可写、`projects` 结构无法识别、`.mcp.json` 是符号链接或无法解析时,该条目 `skip-mcp` 并在 `skipped`、`warnings` 里说明原因,**不回退写用户级**。
|
|
82
|
+
- 项目级条目经项目包启动(凭据启动器)时,`--scope project` 要求项目包已安装,否则提示先同步载体(`--scope user` 或 `--only plugins`)。受管项目级条目从项目里删除后,同步会从它所在的 store 移除(只动 `state` 里归属为 `project:local` / `project:file` 的条目)。
|
|
83
|
+
- **Claude 的项目级 Skill**:`<项目>/.claude/skills/<名>` 是指向 Skill 源目录的**相对符号链接**(例如 `../../.agents/skills/<名>`,项目整体搬家后仍有效),不写用户级;项目位于 iCloud、Dropbox、OneDrive、Google Drive 目录(按路径识别)时改为**复制**,预览在 `degraded` 与 `warnings` 里写明(同步盘对符号链接的行为未核实)。同名真实目录或指向别处的链接不属于本包时算冲突,需要 `--replace-skills`(原件进恢复目录 `replaced-project-skills/`)。`.claude` 或 `.claude/skills` 是符号链接、源目录不在项目内时 `skip-skill`,不写入也不回退写用户级。项目里删除该 Skill 或改回用户级时,只归档 `state` 里归属为 `project:link|copy` 的那一份(进恢复目录 `project-skills/`)。
|
|
84
|
+
- Codex 与 Cursor 的项目级当前 `skip-*`:它们的 MCP 不写进用户级包,Skill 由项目 `.agents/skills` 原生加载。
|
|
85
|
+
- **作用域迁移**:条目的声明从 `user` 改为 `project`(收窄)或反向(放宽)时,预览用 `migrations` 列出「写入新位置」与「从旧位置退役」两步(`--scope` 只选其中一侧时不退役另一侧)。Skill 的旧位置由同一事务归档(用户级链接只在指向本包时才归档;用户自己的同名 Skill 不动,并给出屏蔽提示);MCP 的旧位置**不自动编辑**,只给手工命令(`claude mcp remove --scope user|local|project <名>`,因为 `~/.claude.json` 可能含本地凭据)。放宽另有一条 `warnings`:此后所有项目都会看到它。`sync` / `reconcile` 本身不编辑 MCP 旧位置;受管条目的迁移与退役改用 `agenthelm relocate`([relocate-contract.md](relocate-contract.md))或 `agenthelm dedupe --keep <ref> --retire-others`([dedupe-contract.md](dedupe-contract.md)),手工装的条目仍只给手工命令。
|
|
86
|
+
- **屏蔽检测(建议级)**:同名条目出现在多个存储且官方文档明确优先级时给出 `shadowed`(也进 `warnings`,`doctor --client claude` 的 `advisories`),规则取自 inventory 层已有的 effective 判断(Claude Skill:个人 > 项目;MCP:local > project > user,但 `.mcp.json` 依赖未读取的批准状态,不下结论)。只在项目声明了作用域后出现;不影响 `ok`、`in_sync` 与退出码。
|
|
87
|
+
- 一旦项目声明了作用域(或传了 `--scope`),预览才多出这些键:每条 `operations` 带 `scope`(`user|project`)与 `store`,另有 `by_scope`、`narrowing`、`skipped`、`migrations`、`shadowed`、`degraded`(有内容才出现),文本输出按存储分组;`state` 追加 `scopes`(条目实际所在位置:`user`、`project:local`、`project:file`,缺省视为 `user`)。
|
|
88
|
+
- `--scope user|project|all`(缺省 `all`,仅 Claude;MCP Tool 参数 `scope`)与 `--only` 正交:`user` 只规划用户级条目与载体包,`project` 只规划声明为项目级的条目,不碰用户级。
|
|
89
|
+
|
|
80
90
|
- 安装记录原来指向别的目录(旧做法:`bootstrap --plugin ~/.agents/plugins/plugins/<name> --client claude`)时,第一次同步自动迁移:旧记录指向写入恢复目录的 `record.json`,指向旧目录的 Skill 链接改为指向新包。此后 Codex 端的包怎么变、是否删除,都不影响 Claude。
|
|
81
91
|
- 默认只预览;`--apply` 时整笔操作写入同一个恢复目录,任一步失败全部回滚。
|
|
82
92
|
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# The Opinion migration hint in check
|
|
2
|
+
|
|
3
|
+
中文:[check-opinion-migrate.md](check-opinion-migrate.md)
|
|
4
|
+
|
|
5
|
+
Since 6.14.0 opinion-manager supports on-demand tag loading and `opinion_manager.py migrate`. An existing project's opinion never changes by itself; `agenthelm check` only tells the user that there is something to migrate. The user previews and confirms with `migrate` themselves.
|
|
6
|
+
|
|
7
|
+
## When it runs, and how it is ranked
|
|
8
|
+
|
|
9
|
+
- Advisory: it does not change the exit code, is not part of `summary.up_to_date`, and `--strict` does not fail because of it.
|
|
10
|
+
- Only the explicit `agenthelm check` runs it. The session-start hook (`check --hook`), the nudge, `doctor` and `update` never call migrate.
|
|
11
|
+
- When the project has `opinion.lock.json` and opinion-manager can be found (the copy next to agent-pack first, then the newest installed one), one read-only preview runs per project, writes nothing, and times out after 5 seconds:
|
|
12
|
+
|
|
13
|
+
`python3 <opinion-manager>/runtime/opinion_manager.py migrate --project <project> --output json`
|
|
14
|
+
|
|
15
|
+
- agent-pack and opinion-manager only call each other through a subprocess, never by import. `--offline` and `--client` make no difference (migrate does not use the network).
|
|
16
|
+
|
|
17
|
+
## Results and hints
|
|
18
|
+
|
|
19
|
+
- `status: preview` (exit code 0): one hint with the target profile and schema, a summary of the updates, the `inbox.incomplete` count, and a copyable preview command (paths are shell-quoted, so spaces and quotes still run as written). The hint carries neither `--apply` nor the confirmation fingerprint; the confirmation step comes from migrate's own preview.
|
|
20
|
+
- `status: cannot-migrate` with `reason` `manual-edit-conflict` or `catalog-conflict` (exit code 3): one short note and the same preview command. The wording is generated by agent-pack per reason (it follows the UI language); the manager's `message` goes into the JSON only.
|
|
21
|
+
- Everything else is silent: `unchanged`, `nothing-to-migrate`, `migrated`, `rolled-back`, `refused`, `failed`, any other reason, no lock, no opinion-manager installed, timeout, non-JSON output, non-object output, an unknown status, and a preview with a non-zero exit code.
|
|
22
|
+
|
|
23
|
+
## JSON
|
|
24
|
+
|
|
25
|
+
`check --output json` gains a top-level `opinion_migrate` array when a hint is shown. When silent the field is absent and existing output is byte-identical. Each item:
|
|
26
|
+
|
|
27
|
+
- `kind`: always `"opinion-migrate"`; `status`: `"preview"` or `"cannot-migrate"`; `reason`: `null` for a preview; `command`: the preview command.
|
|
28
|
+
- preview: `target{profile, schema_version}`, `updates[{kind, id, current, target, action}]`, `inbox_incomplete` (integer).
|
|
29
|
+
- cannot-migrate: `message` (the manager's own text, possibly empty).
|
|
30
|
+
|
|
31
|
+
If you do not migrate, nothing changes and current behaviour is unaffected. For the migration itself see `plugins/opinion-manager/references/versioning.md`, "Migration".
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# check 的 Opinion 迁移提示
|
|
2
|
+
|
|
3
|
+
English: [check-opinion-migrate.en.md](check-opinion-migrate.en.md)
|
|
4
|
+
|
|
5
|
+
6.14.0 起 opinion-manager 支持标签按需加载与 `opinion_manager.py migrate`。已有项目的 opinion 不会自动变化;`agenthelm check` 只负责告诉用户“有可迁移的内容”,预览与确认由用户用 `migrate` 自己完成。
|
|
6
|
+
|
|
7
|
+
## 触发与分级
|
|
8
|
+
|
|
9
|
+
- 建议项(advisory):不改退出码,不计入 `summary.up_to_date`,`--strict` 不会因它失败。
|
|
10
|
+
- 只在显式的 `agenthelm check` 里运行。会话开始的 hook(`check --hook`)、nudge、`doctor`、`update` 都不调用 migrate。
|
|
11
|
+
- 项目有 `opinion.lock.json` 且能找到 opinion-manager(与 agent-pack 同目录的副本优先,其次各客户端已安装的最新版)时,对该项目只运行一次只读预览,零写入,超时 5 秒:
|
|
12
|
+
|
|
13
|
+
`python3 <opinion-manager>/runtime/opinion_manager.py migrate --project <项目> --output json`
|
|
14
|
+
|
|
15
|
+
- agent-pack 与 opinion-manager 只经子进程互调,不 import。`--offline`、`--client` 不影响(migrate 不联网)。
|
|
16
|
+
|
|
17
|
+
## 结果与提示
|
|
18
|
+
|
|
19
|
+
- `status: preview`(退出码 0):提示一条,含目标 Profile 与 schema、更新项摘要、`inbox.incomplete` 条数,以及可直接复制的预览命令(路径按 shell 规则引用,含空格或引号也能直接运行)。提示不含 `--apply` 与确认指纹;确认步骤由 migrate 自己的预览给出。
|
|
20
|
+
- `status: cannot-migrate` 且 `reason` 为 `manual-edit-conflict` 或 `catalog-conflict`(退出码 3):提示一条简短说明与同一条查看命令。文字由 agent-pack 按 reason 生成(跟随界面语言),manager 的 `message` 只放进 JSON。
|
|
21
|
+
- 其余一律静默:`unchanged`、`nothing-to-migrate`、`migrated`、`rolled-back`、`refused`、`failed`、其他 reason、没有锁、没有安装 opinion-manager、超时、非 JSON 输出、非对象输出、未知 status、preview 但退出码非 0。
|
|
22
|
+
|
|
23
|
+
## JSON
|
|
24
|
+
|
|
25
|
+
`check --output json` 在有提示时多一个顶层数组 `opinion_migrate`;静默时不出现该字段,既有输出逐字节不变。每项:
|
|
26
|
+
|
|
27
|
+
- `kind`:固定 `"opinion-migrate"`;`status`:`"preview"` 或 `"cannot-migrate"`;`reason`:preview 为 `null`;`command`:预览命令。
|
|
28
|
+
- preview:`target{profile, schema_version}`、`updates[{kind, id, current, target, action}]`、`inbox_incomplete`(整数)。
|
|
29
|
+
- cannot-migrate:`message`(manager 原文,可能为空)。
|
|
30
|
+
|
|
31
|
+
不迁移则保持原样,不影响现有行为。迁移本身见 `plugins/opinion-manager/references/versioning.md`「迁移」。
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# `agenthelm dedupe` contract (schema_version 1)
|
|
2
|
+
|
|
3
|
+
中文:[dedupe-contract.md](dedupe-contract.md)
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
agenthelm dedupe --list [--output json]
|
|
7
|
+
agenthelm dedupe <group-id> (--keep <ref> --retire-others | --keep-all --note "..." | --ignore | --unignore)
|
|
8
|
+
[--project DIR] [--output json|text] [--lang zh|en|auto] [--apply --expect-plan <plan_digest>]
|
|
9
|
+
agenthelm dedupe <group-id> --keep <mcp ref> --desktop-snippet [--output json|text]
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Groups come from the `duplicates` of `agenthelm inventory`. A group id is stable: `g-` + the first 10 hex digits of SHA-256(`kind|client|name-or-fingerprint`); it does not change when other entries appear. Preview by default, zero writes; `--apply` must carry the `--expect-plan` a preview printed and refuses on a mismatch (exit 1). Exit codes: 0 success or a preview without blockers; 1 blockers, digest mismatch or failure; 2 usage error. macOS and Linux only.
|
|
13
|
+
|
|
14
|
+
## Dispositions
|
|
15
|
+
|
|
16
|
+
- **`--keep <ref> --retire-others`** (Skill copies only): the other copies are moved to `~/.agent-pack/recovery/<timestamp>-dedupe-<group id>/skills/<name>` (the same recovery layout; several copies get a store suffix). Archiving is a move, not a delete; failures move everything back. The result gives `recovery_dir` and a one-line manual `mv`; this version has no `restore` command. A kept entry that points inside a directory to be retired -> `keep-depends-on-retired`.
|
|
17
|
+
- **A copy with `unknown` evidence is read-only**: if any member is `unknown` the plan is `blocked: evidence-unknown` and nothing is retired.
|
|
18
|
+
- **MCP copies**: only a **managed** entry (the state of this project's package records ownership: `mcps` for user level, `scopes.mcps` for local/project) is retired by the tool: `plan.retire[]` lists it (`managed: true`, a 16-hex `entry_digest`, no values); its original JSON fragment goes to `mcp/<name>@<scope>.json` in the recovery directory, the whole config file is first backed up byte for byte (`claude.json.before` / `project-mcp.json.before`, all 0600, directory 0700, never printed), `~/.claude.json` is rewritten atomically, the state drops the ownership, and any failure restores every file byte for byte; preview = apply (`plan_digest` includes the entry digest; a mismatch refuses with zero writes). Recovery stays manual: the result's `restore[]` gives the steps (put the fragment back, or restore the whole backup); there is no `restore` command. An **unmanaged** copy (hand-installed, or owned by another package name) is **never edited**: `plan.manual[]` gives the official command `claude mcp remove --scope <user|local|project> <name>` and the `cp ~/.claude.json ~/.claude.json.bak` backup reminder, each `not_archivable_by_tool: true`, `promise: cannot-promise`; non-Claude clients only get an instruction to delete the entry in that file by hand. With only unmanaged copies, `--apply` returns `manual-only` and writes nothing. A member with `unknown` evidence is still `blocked: evidence-unknown`. When another client has an entry with the same fingerprint, `warnings` has `cross-client-keep-recommended` (the same MCP across clients does not conflict; keep it, no retirement is offered).
|
|
19
|
+
- **`--keep-all --note`** / **`--ignore`** / **`--unignore`**: write only the machine-level decision file `~/.config/agenthelm/ext-decisions.json` (0600, atomic); its content is just `{decision, note, kind, client, key, members_digest, at}` with no values. A note is at most 200 characters and a token-like note is refused. After the group's members change, `--list` marks the decision `stale`. `--ignore` is undone with `--unignore`. None of the three changes any client configuration.
|
|
20
|
+
|
|
21
|
+
## Paste-ready Desktop snippet (read-only)
|
|
22
|
+
|
|
23
|
+
`--desktop-snippet` prints the path of `claude_desktop_config.json` (macOS `~/Library/Application Support/Claude/`, Linux `~/.config/Claude/`), a JSON fragment to merge into `mcpServers` (structure `command`/`args`/`url` only; environment variables are listed by name with a `<fill in your NAME>` placeholder) and the hint to fully quit and restart Desktop. An entry with an inline credential is `blocked: inline-secret` and yields no snippet. Whether Desktop loads remote `url` entries, headers or SSE is not documented; the snippet carries `notes` marked unconfirmed, and `promise` is always `cannot-promise`. The Desktop config file is neither read nor written.
|
|
24
|
+
|
|
25
|
+
## JSON
|
|
26
|
+
|
|
27
|
+
`{schema_version, command: "dedupe", mode: "list"|"preview"|"apply"|"desktop-snippet", ...}`. `plan` keys: `group`, `kind`, `disposition`, `status` (`ready|blocked|manual-only`), `members[]`, `steps[{id,action,promise}]`, `blocked[{code,message}]`, `warnings[{code,message}]`, `manual[]`, `retire[]`, `plan_digest`, `next.apply`. `plan_digest` does not depend on the interface language. Keys are only appended; output contains no env values, header values or tokens.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# `agenthelm dedupe` 契约(schema_version 1)
|
|
2
|
+
|
|
3
|
+
English: [dedupe-contract.en.md](dedupe-contract.en.md)
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
agenthelm dedupe --list [--output json]
|
|
7
|
+
agenthelm dedupe <分组id> (--keep <ref> --retire-others | --keep-all --note "…" | --ignore | --unignore)
|
|
8
|
+
[--project 目录] [--output json|text] [--lang zh|en|auto] [--apply --expect-plan <plan_digest>]
|
|
9
|
+
agenthelm dedupe <分组id> --keep <mcp ref> --desktop-snippet [--output json|text]
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
分组来自 `agenthelm inventory` 的 `duplicates`。分组 id 稳定:`g-` + SHA-256(`kind|客户端|名字或指纹`) 前 10 位,不随其他条目出现而变。默认预览、零写入;`--apply` 必须带预览给出的 `--expect-plan`,不一致就拒绝(退出码 1)。退出码:0 成功或预览无阻止项;1 阻止项、指纹不一致或失败;2 参数错误。只支持 macOS 与 Linux。
|
|
13
|
+
|
|
14
|
+
## 处置
|
|
15
|
+
|
|
16
|
+
- **`--keep <ref> --retire-others`**(只对 Skill 副本生效):其余副本移动到 `~/.agent-pack/recovery/<时间戳>-dedupe-<分组id>/skills/<名>`(同一恢复目录布局,多个副本时目录名带存储后缀)。归档是移动,不是删除;失败逆序移回。结果给出 `recovery_dir` 与手工恢复的单行 `mv`,本版没有 `restore` 命令。保留项指向要退役目录内部时 `keep-depends-on-retired`。
|
|
17
|
+
- **证据为 `unknown` 的副本只读**:任何一份为 `unknown` 就 `blocked: evidence-unknown`,不能退役。
|
|
18
|
+
- **MCP 副本**:仅**已受管**的条目(本项目包名的 state 记录了归属:user 级看 `mcps`,local/project 看 `scopes.mcps`)由工具退役:`plan.retire[]` 列出(`managed: true`、16 位 `entry_digest`,无值),原 JSON 片段存入恢复目录 `mcp/<名>@<作用域>.json`,整个配置文件先逐字节备份(`claude.json.before` / `project-mcp.json.before`,均 0600,目录 0700,不打印),`~/.claude.json` 原子改写,state 去掉该归属,任一步失败按字节回滚;预览 = 应用(`plan_digest` 含条目摘要,不一致拒绝且零写入)。恢复沿用手工方式:结果的 `restore[]` 给出放回片段或整份还原备份的步骤,没有 `restore` 命令。**未受管**的副本(手工装的、别的包名的)工具**不编辑**:`plan.manual[]` 给出官方命令 `claude mcp remove --scope <user|local|project> <名>` 与 `cp ~/.claude.json ~/.claude.json.bak` 备份提示,每项 `not_archivable_by_tool: true`、`promise: cannot-promise`;非 Claude 客户端只给「手工删除某文件里的某条目」的说明。只有未受管副本时 `--apply` 的结果为 `manual-only`,零写入。证据 `unknown` 的成员仍 `blocked: evidence-unknown`。其他客户端有同指纹条目时 `warnings` 含 `cross-client-keep-recommended`(跨客户端相同 MCP 不冲突,建议保留,不提供退役)。
|
|
19
|
+
- **`--keep-all --note`** / **`--ignore`** / **`--unignore`**:只写机器级决定文件 `~/.config/agenthelm/ext-decisions.json`(0600,原子写);内容只有 `{decision, note, kind, client, key, members_digest, at}`,不含任何值。备注最长 200 个字符,疑似令牌的备注拒绝。分组成员变化后 `--list` 把决定标为 `stale`。`--ignore` 可用 `--unignore` 撤销。这三个动作不改任何客户端配置。
|
|
20
|
+
|
|
21
|
+
## Desktop 可粘贴片段(只读)
|
|
22
|
+
|
|
23
|
+
`--desktop-snippet`:输出 `claude_desktop_config.json` 的路径(macOS `~/Library/Application Support/Claude/`,Linux `~/.config/Claude/`)、要合并进 `mcpServers` 的 JSON 片段(只含 `command`/`args`/`url` 结构,环境变量只列名字并以 `<在此填入你的 NAME>` 占位)与「完全退出并重启 Desktop」提示。含内联凭据的条目 `blocked: inline-secret`,不生成片段。远程 `url`、请求头、SSE 是否被 Desktop 加载官方文档未说明,片段带 `notes` 标「未确认」;`promise` 恒为 `cannot-promise`。不读不写 Desktop 配置文件。
|
|
24
|
+
|
|
25
|
+
## JSON
|
|
26
|
+
|
|
27
|
+
`{schema_version, command: "dedupe", mode: "list"|"preview"|"apply"|"desktop-snippet", ...}`。`plan` 的键:`group`、`kind`、`disposition`、`status`(`ready|blocked|manual-only`)、`members[]`、`steps[{id,action,promise}]`、`blocked[{code,message}]`、`warnings[{code,message}]`、`manual[]`、`retire[]`、`plan_digest`、`next.apply`。`plan_digest` 与界面语言无关。键只追加;输出不含 env 值、headers 值或令牌。
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# `agenthelm inventory` output contract (schema_version 1)
|
|
2
|
+
|
|
3
|
+
中文:[inventory-contract.md](inventory-contract.md)
|
|
4
|
+
|
|
5
|
+
A read-only command that answers: which Skills and MCP servers does each client see now, in which store and scope do they live, which are duplicated, and which have a recognizable origin. The output is for people and for later write commands and menus, so the JSON is a contract: **keys are only appended, never removed or redefined**; a breaking change must bump `schema_version`.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
agenthelm inventory [--output json|text] [--client claude|codex|cursor|claude-desktop|all]... [--type skills|mcp|all]
|
|
9
|
+
[--scope project|user|all] [--project DIR] [--include-description] [--lang zh|en|auto]
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
- By default it reads all three clients, all types and scopes; `--project` defaults to the current directory. `--scope project` also includes Claude's `local` level.
|
|
13
|
+
- It writes no file, runs no client command line, reads no settings key and no token store. Exit code 0; 2 for argument errors. A missing file means the store does not exist; a present but corrupt file is recorded in `unknown[]` and never crashes the command.
|
|
14
|
+
- `--output text` follows the interface language (`AGENTHELM_LANG` or `--lang`); JSON keys and values (including reason codes) are fixed English identifiers.
|
|
15
|
+
- Description text is not printed by default; `--include-description` adds it as `frontmatter.description` (truncated to 1,536 characters).
|
|
16
|
+
- Paths are abbreviated with `~` (home) and `<project>` (project root); a symlink target outside both stays absolute.
|
|
17
|
+
|
|
18
|
+
## Evidence level `evidence`
|
|
19
|
+
|
|
20
|
+
`file` (read from a file), `setting` (read from a settings key), `cli` (asked the client command line), `unknown` (the official documentation gives no way to decide, or the file is corrupt). **This version produces only `file` and `unknown`**; `setting` and `cli` are reserved. An `unknown` entry takes part in no "takes effect" conclusion. The contract has no "removable" field; later commands give disposal advice separately and only when the evidence is sufficient.
|
|
21
|
+
|
|
22
|
+
## Top level
|
|
23
|
+
|
|
24
|
+
`schema_version`, `generated_by`, `project`, `clients`, `filters{type,scope}`, `skills[]`, `mcps[]`, `summary.per_client`, `duplicates{skills[],mcps[]}`, `overlap_hints[]`, `unknown[]`.
|
|
25
|
+
|
|
26
|
+
## Skill entry
|
|
27
|
+
|
|
28
|
+
`ref`, `name`, `client`, `scope` (`user|project`), `store`, `path`, `frontmatter{name[,description]}|null`, `description_bytes`, `description_chars`, `when_to_use_chars`, `when_to_use_bytes` (the frontmatter `when_to_use`, 0 when absent), `skill_md_bytes`, `skill_md_lines`, `dir_bytes`, `file_count` (total bytes and number of files in the skill directory; symlinks inside are counted, not followed; `null` with `dir-too-large` above 20000 files), `content_sha256` (whole SKILL.md), `name_matches_dir` (`null` when the frontmatter has no name), `frontmatter_ok` (has name and description), `is_symlink`, `link_target_kind` (`relative|absolute|outside-home|null`; `absolute` means an absolute path inside the home directory), `symlink{is_symlink,target}`, `origin`, `version`, `stale`, `loaded`, `precedence`, `shadowed_by`, `evidence`, `issues[]`.
|
|
29
|
+
|
|
30
|
+
- `origin`: `{kind, detail}` are the first-version keys; the structured form is `{type, id, version, latest_known, evidence}`: `type` is `plugin` (a recognized agenthelm plugin), `marketplace` (a plugin in a client marketplace cache directory), `git` (the symlink target lies inside a git repository) or `unknown`; `latest_known` is the highest version of the same plugin found in this machine's client plugin directories, **never fetched online**, `"unknown"` when none is found. There is no `manual` value: placed-by-hand cannot be told from unknown origin, so it is `unknown`. `kind`: `agenthelm-plugin` (after resolving symlinks it lies inside a plugin whose `plugin.json` names the agenthelm repository), `state-record` (listed in Claude's sync state records `~/.claude/agent-pack/state/*.json`), `unknown`.
|
|
31
|
+
- `stale` is `true|false` only for `agenthelm-plugin`: `true` when the version is below the highest version of the same plugin found in this machine's client plugin directories; `false` only means no newer copy exists on this machine, not that it is the newest in the cloud. Everything else is `"unknown"`; nothing is guessed.
|
|
32
|
+
- `loaded` is always `"unknown"` in this version (deciding it needs settings keys such as `skillOverrides` and `[[skills.config]]`, which this version does not read; evidence level `setting` is reserved). `precedence`: `unique` (no same name), `winner`, `shadowed`, `both-load`, `unknown`; `shadowed_by{store,rule,evidence,source_url}` is given only where the official documentation states a precedence and this entry loses.
|
|
33
|
+
- `issues[]`: `broken-symlink`, `frontmatter-missing`, `description-missing`, `name-mismatch`, `skill-md-too-large`, `dir-too-large`.
|
|
34
|
+
- Stores read: Claude `~/.claude/skills`, `<project>/.claude/skills`; Codex `~/.codex/skills`, `~/.agents/skills`, `<project>/.agents/skills`; Cursor `~/.cursor/skills`, `~/.agents/skills`, `<project>/.cursor/skills`, `<project>/.agents/skills`. Entries starting with a dot (such as `.system`) are skipped. Not covered: enterprise/admin directories, scanning from subdirectories up to the repository root, Cursor's compatibility loading of `.claude/skills`.
|
|
35
|
+
|
|
36
|
+
## MCP entry
|
|
37
|
+
|
|
38
|
+
`ref`, `name`, `client`, `scope` (`user|local|project`), `store`, `transport` (`stdio|http|sse|unknown`), `command`, `args[]`, `url`, `url_host` (remote only; host name only, no port or query), `env_names[]` (keys of `env`), `env_var_names[]` (environment variable names involved: `env` keys plus `${VAR}` references, names only), `header_names[]`, `has_inline_secret` (boolean: whether an inline credential value exists; no key name, no value), `fingerprint`, `fingerprint_fields[]` (fields that went into the fingerprint: `["command","args"]` or `["url"]`), `origin`, `loaded` (always `"unknown"`), `precedence`, `shadowed_by`, `evidence`, `notes[]`.
|
|
39
|
+
|
|
40
|
+
- **`env` values, `headers` values and tokens are never printed**: only key names (`env_names`, `header_names`). Credential-looking values in `args` and `url` become `<redacted>`, as do URL userinfo and query values; `${VAR:-default}` keeps only `${VAR}`.
|
|
41
|
+
- `fingerprint`: SHA-256 of the **redacted** `command+args` or `url`, used to find duplicates; it excludes `env` and `headers`.
|
|
42
|
+
- Stores read: Claude `~/.claude.json` (user-level `mcpServers`), `projects[<absolute project path>].mcpServers` inside `~/.claude.json` (local level, read in the shape of the official example; any other shape is `unknown`), `<project>/.mcp.json`; Codex `~/.codex/config.toml` (`mcp_servers`), `<project>/.codex/config.toml` (with `notes: ["codex-project-requires-trust"]`, because the trust record cannot be read); Cursor `~/.cursor/mcp.json`, `<project>/.cursor/mcp.json`.
|
|
43
|
+
|
|
44
|
+
## Entry reference `ref` and version compatibility
|
|
45
|
+
|
|
46
|
+
- `ref` = `<kind>:<name>@<client>:<scope>`, `kind` being `skill` or `mcp`, for example `skill:pdf-notes@claude:user`, `mcp:github@claude:local`. For one client and scope, a Skill outside the "primary store" gets the suffix `#agents` (primary stores: Claude `~/.claude/skills` and `<project>/.claude/skills`; Codex `~/.codex/skills` and `<project>/.agents/skills`; Cursor `~/.cursor/skills` and `<project>/.cursor/skills`; the rest are `~/.agents/skills` and Cursor's `<project>/.agents/skills`), so a `ref` is unique within one output and does not change when other entries appear.
|
|
47
|
+
- Compatibility: **adding keys does not bump `schema_version`**; removing a key, changing a key's meaning or narrowing its value set does. A consumer that meets an unknown `schema_version` should degrade to "unavailable" and not guess field meanings; it should ignore unknown new keys.
|
|
48
|
+
|
|
49
|
+
## Summary and duplicates
|
|
50
|
+
|
|
51
|
+
- `summary.per_client.<client>`: `skill_count`, `description_bytes_total` (sum of each entry's description bytes; excludes the name and any truncation or formatting by the client), `description_bytes_distinct_files` (entries pointing at one file count once), `mcp_count`.
|
|
52
|
+
- `duplicates.skills[]`: same name in different stores within one client. `relation`: `same-file` (one file after resolving), `identical` (same SKILL.md content), `different`, `unknown`. Across clients is not a duplicate.
|
|
53
|
+
- `duplicates.mcps[]`: `kind: same-name` (same client, same name, different stores; `relation` by fingerprint) and `kind: same-fingerprint` (same fingerprint, different names).
|
|
54
|
+
- `effective` ("which one takes effect"): carries a `store` only where the official documentation states a precedence; otherwise `store: null` with a `rule` and `evidence: unknown`.
|
|
55
|
+
- Claude Skill: enterprise > personal > project (the user level wins; the enterprise level is not read). Source: <https://code.claude.com/docs/en/skills> ("Resolve skills that share a name", read 2026-11-18).
|
|
56
|
+
- Claude MCP: local > project > user, the entry is used whole with no field merge. Source: <https://code.claude.com/docs/en/mcp> ("Scope hierarchy and precedence", read 2026-11-18). A project-level `.mcp.json` needs per-project approval and this version does not read the approval state, so a conclusion is given only when local wins; otherwise `project-approval-unknown`.
|
|
57
|
+
- Codex Skill: same names are not merged and both appear in the selector, `rule: both-load`. Source: <https://learn.chatgpt.com/docs/build-skills> (read 2026-11-18).
|
|
58
|
+
- Codex MCP: the official page (<https://learn.chatgpt.com/docs/extend/mcp?surface=cli>, read 2026-11-18) says only that project-level config applies to trusted projects and states no precedence, so `project-trust-unknown`.
|
|
59
|
+
- Cursor: same-name precedence is not documented (design document #82 §2.3; **not re-read this time, unconfirmed**), recorded as `precedence-undocumented`.
|
|
60
|
+
- `overlap_hints[]`: different names, same client, token-set Jaccard similarity of the descriptions >= 0.8 (at least 5 tokens each side; English words, Chinese adjacent character pairs). `hint_only: true`; a mechanical hint that does not claim the two mean the same.
|
|
61
|
+
|
|
62
|
+
## Known trade-offs and limits
|
|
63
|
+
|
|
64
|
+
- **Cursor's compatibility loading is deliberately not modelled**: design document #82 §2.3 records that Cursor also reads `~/.claude/skills` and `~/.codex/skills` (and the project's `.claude/skills` and `.codex/skills`). This version lists only Cursor's own stores (`~/.cursor/skills`, `~/.agents/skills`, `<project>/.cursor/skills`, `<project>/.agents/skills`). Reasons: the behaviour rests on one reading in #82 that was not re-read this time (**unconfirmed**); the official documentation states neither same-name precedence nor where the disable switch is stored; and modelling it would list one file under both `claude` and `cursor`, distorting the duplicate and byte-total figures. It can be added later as new keys or stores without changing existing keys. Cursor's Skill list and description-byte total may therefore be lower than what it actually loads.
|
|
65
|
+
- **The fingerprint is computed from redacted arguments**: `fingerprint` hashes `command+args` or `url` after credential values became `<redacted>`, so two entries that differ only in a redacted position (for example two different secrets in `args`, or different tokens in a URL query) get the same fingerprint and count as identical. This is the accepted price of a digest that cannot leak credentials; `has_inline_secret` flags such entries, and a duplicate verdict for them is a hint only.
|
|
66
|
+
|
|
67
|
+
## `unknown[]`
|
|
68
|
+
|
|
69
|
+
`{store, client, reason}`. `reason`: `invalid-json`, `invalid-toml`, `unreadable`, `too-large`, `unexpected-structure`, `claude-local-structure-unrecognized`.
|
|
70
|
+
|
|
71
|
+
## Claude Desktop (`claude-desktop`, read-only)
|
|
72
|
+
|
|
73
|
+
`--client claude-desktop` reads the Claude Desktop app's `claude_desktop_config.json` as a **separate target**, not merged into `claude` (the standalone CLI does not read that file). It is **not in the default client set**: name it with `--client claude-desktop` or use `--client all`; default output is unchanged.
|
|
74
|
+
|
|
75
|
+
- Location (official documentation, <https://modelcontextprotocol.io/docs/develop/connect-local-servers>, read 2026-11-18): macOS `~/Library/Application Support/Claude/claude_desktop_config.json`, Linux `~/.config/Claude/claude_desktop_config.json`; Windows is `%APPDATA%\Claude\claude_desktop_config.json`, which this command does not resolve (it records `platform-unsupported` in `unknown[]`).
|
|
76
|
+
- Entries: `client: claude-desktop`, `scope: user`, `store: "desktop-config"` (a symbolic name; the real path is in the top-level `desktop.path`), same fields as any MCP entry; a top-level `desktop{path, exists, parse_ok}` is appended (only when `claude-desktop` is selected; `parse_ok` is `null` when the file does not exist). The file's `store` in `unknown[]` is likewise `desktop-config`; there is no Skill directory and no project level, so `--type skills` and `--scope project` yield nothing. An entry containing `${...}` carries `notes: ["variable-expansion-unconfirmed"]` (the documentation does not say whether this file expands variables).
|
|
77
|
+
- A missing file is `unknown` with `not-found`; a corrupt one is `invalid-json` or `unexpected-structure`.
|
|
78
|
+
- `doctor --client claude-desktop` is read-only, reports observations and warnings only, never produces `issues`, and never changes `ok` or the exit code.
|
|
79
|
+
- `doctor --client claude`: when a project-managed MCP server also exists under the same name in `claude_desktop_config.json`, `clients.claude.shadowed_by[]` gains an advisory entry (the key appears only when there is a finding): `{name, by, store, applies_to: "desktop-local-code-tab", cli_affected: false, severity: "advisory", evidence: "file", precedence_confirmed: false, source_url}`, and a line is added to `warnings`. The hint concerns the Desktop local Code tab only; the standalone CLI is unaffected. **Precedence is unconfirmed**: design document #82 (read 2026-11-11) quoted "with the same name, the Code tab uses the `claude_desktop_config.json` definition"; re-reading <https://code.claude.com/docs/en/desktop#mcp-servers-from-the-claude-desktop-chat-app> on 2026-11-18, the page says only that Desktop loads that file's servers into local Code tab sessions alongside those from `~/.claude.json` and `.mcp.json`, with no same-name precedence. Hence `precedence_confirmed` is `false` and the wording is "may use".
|
|
80
|
+
|
|
81
|
+
## Platforms
|
|
82
|
+
|
|
83
|
+
Path resolution supports macOS and Linux; Windows paths are described in documentation only and not resolved by this command.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# `agenthelm inventory` 输出契约(schema_version 1)
|
|
2
|
+
|
|
3
|
+
English: [inventory-contract.en.md](inventory-contract.en.md)
|
|
4
|
+
|
|
5
|
+
只读命令,回答「各客户端现在能看到哪些 Skill 与 MCP、装在哪个存储与作用域、哪些重复、哪些来源可识别」。输出供人阅读,也供后续写入命令与菜单界面读取,所以 JSON 是契约:**键只追加,不删除、不改含义**;破坏性变化必须升 `schema_version`。
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
agenthelm inventory [--output json|text] [--client claude|codex|cursor|claude-desktop|all]… [--type skills|mcp|all]
|
|
9
|
+
[--scope project|user|all] [--project 目录] [--include-description] [--lang zh|en|auto]
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
- 默认读全部三个客户端、全部类型与作用域;`--project` 缺省为当前目录。`--scope project` 同时包含 Claude 的 `local` 级。
|
|
13
|
+
- 不写任何文件、不执行客户端命令行、不读设置键、不读令牌存储。退出码 0;参数错误 2。文件缺失视为没有该存储;文件存在但损坏则写入 `unknown[]`,不崩溃。
|
|
14
|
+
- `--output text` 随界面语言(`AGENTHELM_LANG` 或 `--lang`);JSON 的键与取值(含原因代码)固定为英文标识。
|
|
15
|
+
- 默认不输出 description 文本;`--include-description` 才在 `frontmatter.description` 给出(截断到 1,536 个字符)。
|
|
16
|
+
- 路径用 `~`(家目录)与 `<project>`(项目根)缩写;符号链接目标位于这两处之外时保持绝对路径。
|
|
17
|
+
|
|
18
|
+
## 证据等级 `evidence`
|
|
19
|
+
|
|
20
|
+
`file`(读文件得到)、`setting`(读设置键得到)、`cli`(问客户端命令行得到)、`unknown`(官方文档没有给出判定手段,或文件损坏)。**本版本只产生 `file` 与 `unknown`**,`setting`、`cli` 为后续版本保留。证据为 `unknown` 的条目不参与任何「生效」结论;契约里没有「可删除」类字段,处置建议由后续命令在证据充分时另行给出。
|
|
21
|
+
|
|
22
|
+
## 顶层
|
|
23
|
+
|
|
24
|
+
`schema_version`、`generated_by`、`project`、`clients`、`filters{type,scope}`、`skills[]`、`mcps[]`、`summary.per_client`、`duplicates{skills[],mcps[]}`、`overlap_hints[]`、`unknown[]`。
|
|
25
|
+
|
|
26
|
+
## Skill 条目
|
|
27
|
+
|
|
28
|
+
`ref`、`name`、`client`、`scope`(`user|project`)、`store`、`path`、`frontmatter{name[,description]}|null`、`description_bytes`、`description_chars`、`when_to_use_chars`、`when_to_use_bytes`(frontmatter 的 `when_to_use`,没有则 0)、`skill_md_bytes`、`skill_md_lines`、`dir_bytes`、`file_count`(技能目录内文件总字节数与个数,目录内符号链接只计不跟随;超过 20000 个文件时为 `null` 并带 `dir-too-large`)、`content_sha256`(SKILL.md 全文)、`name_matches_dir`(frontmatter 无 name 时为 `null`)、`frontmatter_ok`(有 name 与 description)、`is_symlink`、`link_target_kind`(`relative|absolute|outside-home|null`,`absolute` 指家目录内的绝对路径)、`symlink{is_symlink,target}`、`origin`、`version`、`stale`、`loaded`、`precedence`、`shadowed_by`、`evidence`、`issues[]`。
|
|
29
|
+
|
|
30
|
+
- `origin`:`{kind, detail}` 为第一版键;结构化形式 `{type, id, version, latest_known, evidence}`:`type` 为 `plugin`(可识别的 agenthelm 插件)、`marketplace`(位于客户端市场缓存目录的插件)、`git`(符号链接目标位于某个 git 仓库内)、`unknown`;`latest_known` 是本机各客户端插件目录里找到的同名插件最高版本,**不联网**,找不到为 `"unknown"`。没有 `manual` 值:无法区分「手工放置」与「来源不明」,一律 `unknown`。`kind`:`agenthelm-plugin`(解析符号链接后位于 `plugin.json` 声明为 agenthelm 仓库的插件内)、`state-record`(Claude 的同步状态记录 `~/.claude/agent-pack/state/*.json` 登记了它)、`unknown`。
|
|
31
|
+
- `stale` 只对 `agenthelm-plugin` 给 `true|false`:版本低于本机各客户端插件目录里找到的同名插件最高版本为 `true`;`false` 只表示本机没有更新的副本,不代表云端最新。其余一律 `"unknown"`,不猜。
|
|
32
|
+
- `loaded`:本版本恒为 `"unknown"`(要判定须读 `skillOverrides`、`[[skills.config]]` 等设置键,本版不读,证据等级为 `setting`,保留)。`precedence`:`unique`(无同名)、`winner`、`shadowed`、`both-load`、`unknown`;`shadowed_by{store,rule,evidence,source_url}` 只在官方文档明确优先级且本条目落败时给出。
|
|
33
|
+
- `issues[]`:`broken-symlink`、`frontmatter-missing`、`description-missing`、`name-mismatch`、`skill-md-too-large`、`dir-too-large`。
|
|
34
|
+
- 读取的存储:Claude `~/.claude/skills`、`<project>/.claude/skills`;Codex `~/.codex/skills`、`~/.agents/skills`、`<project>/.agents/skills`;Cursor `~/.cursor/skills`、`~/.agents/skills`、`<project>/.cursor/skills`、`<project>/.agents/skills`。以点开头的条目(如 `.system`)跳过。未覆盖:企业/管理员级目录、从子目录向上逐级扫描、Cursor 对 `.claude/skills` 的兼容加载。
|
|
35
|
+
|
|
36
|
+
## MCP 条目
|
|
37
|
+
|
|
38
|
+
`ref`、`name`、`client`、`scope`(`user|local|project`)、`store`、`transport`(`stdio|http|sse|unknown`)、`command`、`args[]`、`url`、`url_host`(仅远程,只有主机名,不含端口与 query)、`env_names[]`(`env` 的键名)、`env_var_names[]`(涉及的环境变量名:`env` 键名加 `${VAR}` 引用,仅名字)、`header_names[]`、`has_inline_secret`(布尔:是否存在内联的凭据值;不给键名、不给值)、`fingerprint`、`fingerprint_fields[]`(参与指纹的字段名:`["command","args"]` 或 `["url"]`)、`origin`、`loaded`(恒 `"unknown"`)、`precedence`、`shadowed_by`、`evidence`、`notes[]`。
|
|
39
|
+
|
|
40
|
+
- **绝不输出 `env` 值、`headers` 值、令牌**:只给键名(`env_names`、`header_names`)。`args` 与 `url` 里疑似凭据的值替换为 `<redacted>`,URL 的用户信息与查询值同理;`${VAR:-默认值}` 只保留 `${VAR}`。
|
|
41
|
+
- `fingerprint`:对**已脱敏**的 `command+args` 或 `url` 取 SHA-256,用于判重,不含 `env` 与 `headers`。
|
|
42
|
+
- 读取的存储:Claude `~/.claude.json`(用户级 `mcpServers`)、`~/.claude.json` 内 `projects[<项目绝对路径>].mcpServers`(local 级,按官方文档示例的结构读取,结构不符记 `unknown`)、`<project>/.mcp.json`;Codex `~/.codex/config.toml`(`mcp_servers`)、`<project>/.codex/config.toml`(带 `notes: ["codex-project-requires-trust"]`,信任记录读不到);Cursor `~/.cursor/mcp.json`、`<project>/.cursor/mcp.json`。
|
|
43
|
+
|
|
44
|
+
## 条目引用 `ref` 与版本兼容约定
|
|
45
|
+
|
|
46
|
+
- `ref` = `<kind>:<name>@<客户端>:<作用域>`,`kind` 为 `skill` 或 `mcp`,例如 `skill:pdf-notes@claude:user`、`mcp:github@claude:local`。同一客户端与作用域下,Skill 位于「主存储」之外的条目加后缀 `#agents`(主存储:Claude `~/.claude/skills` 与 `<project>/.claude/skills`;Codex `~/.codex/skills` 与 `<project>/.agents/skills`;Cursor `~/.cursor/skills` 与 `<project>/.cursor/skills`;其余即 `~/.agents/skills`、Cursor 的 `<project>/.agents/skills`),所以 `ref` 在一份输出内唯一,且不随其他条目的出现而变化。
|
|
47
|
+
- 兼容约定:**新增键不升 `schema_version`**;删除键、改变键含义或取值集合的收窄才升主版本。消费方遇到不认识的 `schema_version` 应降级为「不可用」,不要猜测字段含义;遇到不认识的新键应忽略。
|
|
48
|
+
|
|
49
|
+
## 汇总与重复
|
|
50
|
+
|
|
51
|
+
- `summary.per_client.<客户端>`:`skill_count`、`description_bytes_total`(每个条目的 description 字节数之和,不含 name,不含客户端的截断或格式化)、`description_bytes_distinct_files`(指向同一文件的只算一次)、`mcp_count`。
|
|
52
|
+
- `duplicates.skills[]`:同一客户端内同名且位于不同存储。`relation`:`same-file`(解析后是同一文件)、`identical`(SKILL.md 内容相同)、`different`、`unknown`。跨客户端不算重复。
|
|
53
|
+
- `duplicates.mcps[]`:`kind: same-name`(同客户端同名跨存储,`relation` 按指纹)与 `kind: same-fingerprint`(同指纹不同名)。
|
|
54
|
+
- `effective`:「哪一份生效」,只在官方文档给出优先级时有 `store`,否则 `store: null` 并给 `rule` 与 `evidence: unknown`。
|
|
55
|
+
- Claude Skill:企业 > 个人 > 项目(用户级胜出;企业级未读)。出处 <https://code.claude.com/docs/en/skills>(「Resolve skills that share a name」,2026-11-18 读取)。
|
|
56
|
+
- Claude MCP:local > project > user,整条目取用不合并字段。出处 <https://code.claude.com/docs/en/mcp>(「Scope hierarchy and precedence」,2026-11-18 读取)。项目级 `.mcp.json` 需要逐项目批准而批准状态本版不读,所以只有 local 胜出时给结论,其余为 `project-approval-unknown`。
|
|
57
|
+
- Codex Skill:同名不合并,两份都出现在选择器,`rule: both-load`。出处 <https://learn.chatgpt.com/docs/build-skills>(2026-11-18 读取)。
|
|
58
|
+
- Codex MCP:官方页面(<https://learn.chatgpt.com/docs/extend/mcp?surface=cli>,2026-11-18 读取)只说项目级仅对受信任项目生效,没有给同名优先级,记 `project-trust-unknown`。
|
|
59
|
+
- Cursor:同名优先级文档未说明(设计文档 #82 §2.3,**本次未重读,未确认**),记 `precedence-undocumented`。
|
|
60
|
+
- `overlap_hints[]`:不同名、同客户端、description 的词元集合 Jaccard 相似度 ≥ 0.8(每边至少 5 个词元;英文按单词,中文按相邻二字)。`hint_only: true`,只是机械提示,不声称语义相同。
|
|
61
|
+
|
|
62
|
+
## 已知取舍与局限
|
|
63
|
+
|
|
64
|
+
- **Cursor 的兼容加载未建模(有意)**:设计文档 #82 §2.3 记载 Cursor 还会兼容读取 `~/.claude/skills`、`~/.codex/skills`(及项目的 `.claude/skills`、`.codex/skills`)。本版本只列 Cursor 自己的存储(`~/.cursor/skills`、`~/.agents/skills`、`<project>/.cursor/skills`、`<project>/.agents/skills`),原因:该行为依据的是 #82 的一次读取,本次未重读,**未确认**;同名优先级与停用开关的落盘位置官方文档均未说明;建模会让同一个文件同时出现在 `claude` 与 `cursor` 两个客户端下,影响重复与字节汇总的口径。后续可作为新增键或新存储追加,不改既有键。因此 Cursor 的 Skill 清单与 description 字节汇总可能少于它实际加载的数量。
|
|
65
|
+
- **指纹基于脱敏后的参数**:`fingerprint` 取的是已替换为 `<redacted>` 的 `command+args` 或 `url`,所以仅在被脱敏的位置上取值不同(例如 `args` 里两个不同的密钥值,或 URL 查询里不同的 token)的两条会得到同一个指纹,被判为「内容相同」。这是为了让摘要不泄露凭据而接受的取舍;`has_inline_secret` 可提示该条目含内联凭据,判重结论对这类条目只作提示。
|
|
66
|
+
|
|
67
|
+
## `unknown[]`
|
|
68
|
+
|
|
69
|
+
`{store, client, reason}`。`reason`:`invalid-json`、`invalid-toml`、`unreadable`、`too-large`、`unexpected-structure`、`claude-local-structure-unrecognized`。
|
|
70
|
+
|
|
71
|
+
## Claude Desktop(`claude-desktop`,只读)
|
|
72
|
+
|
|
73
|
+
`--client claude-desktop` 读取 Claude Desktop 应用的 `claude_desktop_config.json`,作为**独立目标**,不并入 `claude`(独立 CLI 不读该文件)。**不在默认客户端集合内**:须点名 `--client claude-desktop` 或用 `--client all`;默认输出与此前一致。
|
|
74
|
+
|
|
75
|
+
- 位置(官方文档,<https://modelcontextprotocol.io/docs/develop/connect-local-servers>,2026-11-18 读取):macOS `~/Library/Application Support/Claude/claude_desktop_config.json`,Linux `~/.config/Claude/claude_desktop_config.json`;Windows 为 `%APPDATA%\Claude\claude_desktop_config.json`,本命令不解析,只在 `unknown[]` 记 `platform-unsupported`。
|
|
76
|
+
- 条目:`client: claude-desktop`、`scope: user`、`store: "desktop-config"`(符号名;真实路径在顶层 `desktop.path`),字段同 MCP 条目;顶层追加 `desktop{path, exists, parse_ok}`(仅选择了 `claude-desktop` 时出现;`parse_ok` 在文件不存在时为 `null`)。`unknown[]` 里该文件的 `store` 同为 `desktop-config`。没有 Skill 目录,也没有项目级,所以 `--type skills`、`--scope project` 下为空。文件里含 `${...}` 的条目带 `notes: ["variable-expansion-unconfirmed"]`(官方文档没有说明该文件是否展开变量)。
|
|
77
|
+
- 文件不存在记 `unknown` 的 `not-found`;损坏记 `invalid-json`、`unexpected-structure`。
|
|
78
|
+
- `doctor --client claude-desktop` 只读、只给观测与警告,永不产生 `issues`,不改变 `ok` 与退出码。
|
|
79
|
+
- `doctor --client claude`:项目受管的 MCP 若在 `claude_desktop_config.json` 里也有同名条目,`clients.claude.shadowed_by[]` 追加一条建议级提示(键只在有发现时出现):`{name, by, store, applies_to: "desktop-local-code-tab", cli_affected: false, severity: "advisory", evidence: "file", precedence_confirmed: false, source_url}`,并写入 `warnings`。该提示仅涉及 Desktop 本地 Code 标签;独立 CLI 不受影响。**优先级未确认**:设计文档 #82(2026-11-11 读取)引用过「同名时 Code 标签使用 `claude_desktop_config.json` 的定义」,2026-11-18 重读 <https://code.claude.com/docs/en/desktop#mcp-servers-from-the-claude-desktop-chat-app> 时该页只写「Desktop 把该文件的服务器与 `~/.claude.json`、`.mcp.json` 里的一起加载进本地 Code 标签」,没有同名优先级,所以 `precedence_confirmed` 为 `false`,措辞为「可能改用」。
|
|
80
|
+
|
|
81
|
+
## 平台
|
|
82
|
+
|
|
83
|
+
支持 macOS 与 Linux 的路径解析;Windows 路径只在文档说明,本命令不解析。
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
- **Claude Code**: the plugin ships `hooks/hooks.json`, effective after installation. SessionStart (`startup|resume|clear|compact`) injects the protocol; UserPromptSubmit reminds when a keyword matches; Stop uses `additionalContext` to make the Agent confirm with the user when the conditions are met.
|
|
10
10
|
- **Codex**: reads the same `hooks/hooks.json` (Codex also provides `CLAUDE_PLUGIN_ROOT`). By Codex's rules a plugin hook runs only after the user reviews and trusts it in `/hooks`. Stop uses `decision: "block"` with a `reason`, and the reason text becomes the next turn's continuation prompt.
|
|
11
|
-
- **Cursor**: has no prompt-level injection (`beforeSubmitPrompt` can only allow or block). Run `agenthelm nudge install-hooks --client cursor` to preview and add `--apply` to write sessionStart and stop into `~/.cursor/hooks.json` (`--scope project` writes the project's `.cursor/hooks.json`; `--remove` undoes it and deletes only the entries agenthelm wrote). When run through `npx`, the hook commands never point into npx's temporary cache (`…/_npx/<hash>/…`; the hooks would break once the cache is cleaned). They use an installed stable entry instead: first `~/.cursor/plugins/local/agent-pack/runtime/agenthelm.py`, then `<data dir>/agenthelm/current/plugins/agent-pack/runtime/agenthelm.py` after `agenthelm runtime install` (the temporary folders of pnpm dlx, yarn dlx and bunx are recognised too). If neither exists, the preview warns and `--apply` refuses to write, exiting with code 2; run `agenthelm install --client cursor --apply` or `agenthelm runtime install --apply` first. `--remove` is not affected. The stable entry's path deliberately carries no version, so the entry picked may be an old one (an old agent-pack in the Cursor plugin directory, or `current` still linked to an old `runtimes/<version>`), and the generated hooks then call that old version's nudge: before installing the hooks, update the plugin (`agenthelm update --client cursor --apply`) or switch to the target version with `agenthelm runtime use <target version> --apply`, then run `install-hooks`. Cursor's `stop` prompt appears as a "user message", so it is off by default. The community reports cases where sessionStart's `additional_context` does not reach the model (see the Cursor forum), so the protocol is also written in opinion-manager's Skill and can be triggered on demand without the hook.
|
|
11
|
+
- **Cursor**: has no prompt-level injection (`beforeSubmitPrompt` can only allow or block). Run `agenthelm nudge install-hooks --client cursor` to preview and add `--apply` to write sessionStart and stop into `~/.cursor/hooks.json` (`--scope project` writes the project's `.cursor/hooks.json`; `--remove` undoes it and deletes only the entries agenthelm wrote). When run through `npx`, the hook commands never point into npx's temporary cache (`…/_npx/<hash>/…`; the hooks would break once the cache is cleaned). They use an installed stable entry instead: first `~/.cursor/plugins/local/agent-pack/runtime/agenthelm.py`, then `<data dir>/agenthelm/current/plugins/agent-pack/runtime/agenthelm.py` after `agenthelm runtime install` (the temporary folders of pnpm dlx, yarn dlx and bunx are recognised too). If neither exists, the preview warns and `--apply` refuses to write, exiting with code 2; run `agenthelm install --client cursor --apply` or `agenthelm runtime install --apply` first. `--remove` is not affected. The stable entry's path deliberately carries no version, so the entry picked may be an old one (an old agent-pack in the Cursor plugin directory, or `current` still linked to an old `runtimes/<version>`), and the generated hooks then call that old version's nudge: before installing the hooks, update the plugin (`agenthelm update --client cursor --apply`) or switch to the target version with `agenthelm runtime use <target version> --apply`, then run `install-hooks`. Running `nudge install-hooks` from a temporary extraction directory makes the hooks point into that directory; for long-term use, first run `agenthelm install --client cursor --apply` or `agenthelm runtime install --apply`. Cursor's `stop` prompt appears as a "user message", so it is off by default. The community reports cases where sessionStart's `additional_context` does not reach the model (see the Cursor forum), so the protocol is also written in opinion-manager's Skill and can be triggered on demand without the hook.
|
|
12
12
|
|
|
13
13
|
All three clients share these properties: the hook always exits 0 and stays silent on any error; it produces output only in projects that use opinion-manager (the Project Profile's `opinion.provider` is `opinion-manager`, or `.opinion/` or `opinion.lock.json` exists), so other directories never notice it.
|
|
14
14
|
|
|
@@ -16,7 +16,7 @@ All three clients share these properties: the hook always exits 0 and stays sile
|
|
|
16
16
|
|
|
17
17
|
- **Session start**: always injects the protocol and the full text of trial candidates (up to 6000 characters); after `compact` it only re-injects. When the number of pending candidates reaches `pending_threshold`, or the oldest one is older than `stale_days`, and the last reminder is older than `reminder_repeat_hours`, the user also gets one visible line.
|
|
18
18
|
- **User message**: the message is at most 1500 characters and contains any word from `keywords` (case-insensitive), at most `capture_hints_per_session` reminders per session. Keywords only raise the hit rate; the semantic judgement stays with the Agent. Long messages are mostly pasted content and are skipped.
|
|
19
|
-
- **End of turn**: candidates from this session exist that have not been shown yet, `stop_prompt` allows it, `max_prompts_per_session` is not exceeded and (with `on-completion`) the last reply contains one of `completion_keywords`. Continuation turns (`stop_hook_active`, or Cursor's `loop_count`) never trigger it. The candidates are marked as shown when the request is sent.
|
|
19
|
+
- **End of turn**: `confirm` is `ask`, candidates from this session exist that have not been shown yet, `stop_prompt` allows it, `max_prompts_per_session` is not exceeded, `inbox gate` allows it (at most one request per project within `prompt_cooldown_hours`, across sessions; checked with `--peek` first and recorded only when a request is really sent; a damaged gate state keeps the hook silent) and (with `on-completion`) the last reply contains one of `completion_keywords`. Continuation turns (`stop_hook_active`, or Cursor's `loop_count`) never trigger it. The candidates are marked as shown when the request is sent.
|
|
20
20
|
|
|
21
21
|
## Configuration
|
|
22
22
|
|
|
@@ -27,6 +27,8 @@ Locations (later overrides earlier): built-in defaults → the Project Profile's
|
|
|
27
27
|
- `pending_threshold`: remind when at least this many candidates are pending, default `5`.
|
|
28
28
|
- `stale_days`: remind when the oldest pending candidate is older than this, default `7`.
|
|
29
29
|
- `max_prompts_per_session`: upper limit of end-of-turn confirmation requests per session, default `1`.
|
|
30
|
+
- `confirm`: `ask` (default) / `digest` / `quiet`. `ask`: ask at the end of a task, limited per session and by the cooldown; `digest`: no separate ask in the conversation, one closing sentence in a reply plus the session-start summary; `quiet`: the session-start summary only. Under `digest` and `quiet`, `stop` prints nothing. Session start calls `inbox brief --mode` with this value; the protocol is generated by opinion-manager and is the single source for when to confirm.
|
|
31
|
+
- `prompt_cooldown_hours`: minimum interval between two confirmation requests of the same project (hours, non-negative integer, `0` means no cooldown), default `24`; also passed to `inbox brief --cooldown-hours` (written into the protocol's `inbox gate` when it differs from the default).
|
|
30
32
|
- `capture_hints_per_session`: upper limit of keyword reminders per session, default `3`.
|
|
31
33
|
- `trial_expire_days`: a trial not made formal within this many days returns to pending, default `30`.
|
|
32
34
|
- `reminder_repeat_hours`: shortest interval between visible session-start reminders, default `24`.
|
|
@@ -35,6 +37,12 @@ Locations (later overrides earlier): built-in defaults → the Project Profile's
|
|
|
35
37
|
|
|
36
38
|
The environment variable `AGENTHELM_NO_NUDGE=1` temporarily silences all output; `AGENTHELM_NUDGE_DEBUG=1` prints internal hook exceptions to stderr. `agenthelm nudge status [--project P]` shows the effective configuration, the current summary and whether a new session would remind.
|
|
37
39
|
|
|
40
|
+
## Hard limits and known boundaries
|
|
41
|
+
|
|
42
|
+
- **The hook path has hard limits**: `stop` fires at most once per session (`max_prompts_per_session`) and is also bound across sessions by `prompt_cooldown_hours`; the state is the project's `.opinion/ask-state.json`. Cursor's `stop_prompt` stays `off` by default.
|
|
43
|
+
- **The model-judged path cannot be hard-limited**: in clients without hooks, or when the model decides by itself when to ask, only the protocol wording applies (the `ask` protocol requires running `inbox gate` first; `digest` / `quiet` contain no ask at task completion) and nothing is guaranteed.
|
|
44
|
+
- **Unverified**: Cursor's sessionStart injection, Codex `/hooks` trust and how Claude Stop's `additionalContext` behaves across versions have not been verified in real clients; they belong in the on-device acceptance checks.
|
|
45
|
+
|
|
38
46
|
## Message language
|
|
39
47
|
|
|
40
48
|
The messages shown to the user and the protocol injected into the model use the same language; Chinese (`zh`) and English (`en`) are supported. The language is decided in this order: the config `nudge.language` (when it is not `auto`) → the environment variable `AGENTHELM_LANG` → the `language` key of the user config `~/.config/agenthelm/config.json` (shared by every agenthelm command) → the system locale (`LC_ALL`, `LC_MESSAGES`, `LANG`) → English. A Chinese locale gets Chinese; a locale of any other language gets English for now; `C` / `POSIX` / empty means "not specified", so the next variable is consulted, and English applies when none names a language. The user config's `nudge.language` overrides the Project Profile, so you can override the team's setting with your own language.
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
- **Claude Code**:插件随附 `hooks/hooks.json`,安装后自动生效。SessionStart(`startup|resume|clear|compact`)注入协议;UserPromptSubmit 在命中关键词时提醒;Stop 在满足条件时用 `additionalContext` 让 Agent 向用户确认。
|
|
10
10
|
- **Codex**:读取同一个 `hooks/hooks.json`(Codex 同时提供 `CLAUDE_PLUGIN_ROOT`)。按 Codex 的规则,插件 hook 需要用户在 `/hooks` 中审阅并信任后才会运行。Stop 使用 `decision: "block"` 加 `reason`,原因文本成为下一轮的续写提示。
|
|
11
|
-
- **Cursor**:没有 prompt 级注入(`beforeSubmitPrompt` 只能放行或拦截)。运行 `agenthelm nudge install-hooks --client cursor` 预览,加 `--apply` 把 sessionStart 与 stop 写入 `~/.cursor/hooks.json`(`--scope project` 写项目的 `.cursor/hooks.json`;`--remove` 撤销,只删除 agenthelm 写入的条目)。经 `npx` 运行时,hook 命令不会指向 npx 的临时缓存(`…/_npx/<哈希>/…`,缓存被清理后 hook 会失效):改用已安装的稳定入口,先找 `~/.cursor/plugins/local/agent-pack/runtime/agenthelm.py`,再找 `agenthelm runtime install` 之后的 `<数据目录>/agenthelm/current/plugins/agent-pack/runtime/agenthelm.py`(pnpm dlx、yarn dlx、bunx 的临时目录同样识别);两处都没有时预览给出警告,`--apply` 拒绝写入并以退出码 2 退出,请先运行 `agenthelm install --client cursor --apply` 或 `agenthelm runtime install --apply`。`--remove` 不受影响。稳定入口的路径刻意不含版本号,选中的入口可能是旧版本(Cursor 插件目录里是旧的 agent-pack,或 `current` 仍指向旧的 `runtimes/<版本>`),生成的 hook 会调用该旧版本的 nudge:安装 hook 前先更新插件(`agenthelm update --client cursor --apply`),或用 `agenthelm runtime use <目标版本> --apply` 切到目标版本,再运行 `install-hooks`。Cursor 的 `stop` 提示以“用户消息”的形式出现,默认关闭。社区有 sessionStart 的 `additional_context` 未到达模型的反馈(见 Cursor 论坛),所以协议同时写在 opinion-manager 的 Skill 里,不依赖 hook 也能按需触发。
|
|
11
|
+
- **Cursor**:没有 prompt 级注入(`beforeSubmitPrompt` 只能放行或拦截)。运行 `agenthelm nudge install-hooks --client cursor` 预览,加 `--apply` 把 sessionStart 与 stop 写入 `~/.cursor/hooks.json`(`--scope project` 写项目的 `.cursor/hooks.json`;`--remove` 撤销,只删除 agenthelm 写入的条目)。经 `npx` 运行时,hook 命令不会指向 npx 的临时缓存(`…/_npx/<哈希>/…`,缓存被清理后 hook 会失效):改用已安装的稳定入口,先找 `~/.cursor/plugins/local/agent-pack/runtime/agenthelm.py`,再找 `agenthelm runtime install` 之后的 `<数据目录>/agenthelm/current/plugins/agent-pack/runtime/agenthelm.py`(pnpm dlx、yarn dlx、bunx 的临时目录同样识别);两处都没有时预览给出警告,`--apply` 拒绝写入并以退出码 2 退出,请先运行 `agenthelm install --client cursor --apply` 或 `agenthelm runtime install --apply`。`--remove` 不受影响。稳定入口的路径刻意不含版本号,选中的入口可能是旧版本(Cursor 插件目录里是旧的 agent-pack,或 `current` 仍指向旧的 `runtimes/<版本>`),生成的 hook 会调用该旧版本的 nudge:安装 hook 前先更新插件(`agenthelm update --client cursor --apply`),或用 `agenthelm runtime use <目标版本> --apply` 切到目标版本,再运行 `install-hooks`。从临时解压目录运行 `nudge install-hooks` 会让 hook 指向该目录;长期使用请先 `agenthelm install --client cursor --apply` 或 `agenthelm runtime install --apply`。Cursor 的 `stop` 提示以“用户消息”的形式出现,默认关闭。社区有 sessionStart 的 `additional_context` 未到达模型的反馈(见 Cursor 论坛),所以协议同时写在 opinion-manager 的 Skill 里,不依赖 hook 也能按需触发。
|
|
12
12
|
|
|
13
13
|
三个客户端的共同点:hook 永远退出 0,任何异常都静默;只在项目启用了 opinion-manager(Project Profile 的 `opinion.provider` 为 `opinion-manager`,或存在 `.opinion/`、`opinion.lock.json`)时才有输出,其他目录完全无感。
|
|
14
14
|
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
|
|
17
17
|
- **会话开始**:总是注入协议与试行候选全文(上限 6000 字符);`compact` 后只重新注入。待确认候选数 ≥ `pending_threshold`,或最久一条超过 `stale_days`,且距上次提示超过 `reminder_repeat_hours` 时,另给用户一行可见提示。
|
|
18
18
|
- **用户消息**:消息 ≤1500 字符且包含 `keywords` 中任一词(不区分大小写),每个会话最多提醒 `capture_hints_per_session` 次。关键词只是提高命中率的辅助,语义判断仍由 Agent 做;长消息多为粘贴内容,跳过。
|
|
19
|
-
-
|
|
19
|
+
- **回合结束**:`confirm` 为 `ask`,本会话暂存且没展示过的候选存在、`stop_prompt` 允许、未超过 `max_prompts_per_session`、`inbox gate` 放行(同项目 `prompt_cooldown_hours` 小时内最多一次,跨会话;先用 `--peek` 判断,真要发请求时才记账;gate 状态损坏时 hook 静默),且(`on-completion` 时)最后一条回复含 `completion_keywords` 之一。续写回合(`stop_hook_active` 或 Cursor 的 `loop_count`)不再触发。发出请求时把这些候选标记为已展示。
|
|
20
20
|
|
|
21
21
|
## 配置
|
|
22
22
|
|
|
@@ -27,6 +27,8 @@
|
|
|
27
27
|
- `pending_threshold`:待确认候选 ≥ 此数就提示,默认 `5`。
|
|
28
28
|
- `stale_days`:最久一条待确认候选超过此天数就提示,默认 `7`。
|
|
29
29
|
- `max_prompts_per_session`:每会话回合结束的确认请求上限,默认 `1`。
|
|
30
|
+
- `confirm`:`ask`(默认)/ `digest` / `quiet`。`ask`:任务收尾时询问,受每会话上限与冷却限制;`digest`:对话里不单独询问,只在回复末尾顺带一句,会话开始汇总;`quiet`:只在会话开始汇总。`digest` 与 `quiet` 下 `stop` 不输出。会话开始时按此值调用 `inbox brief --mode`,协议由 opinion-manager 生成,是确认时机的单一来源。
|
|
31
|
+
- `prompt_cooldown_hours`:同项目两次确认请求的最短间隔(小时,非负整数,`0` 为不设冷却),默认 `24`;同时传给 `inbox brief --cooldown-hours`(与缺省不同时写进协议里的 `inbox gate`)。
|
|
30
32
|
- `capture_hints_per_session`:每会话关键词提醒上限,默认 `3`。
|
|
31
33
|
- `trial_expire_days`:试行超过此天数未转正退回待确认,默认 `30`。
|
|
32
34
|
- `reminder_repeat_hours`:会话开始的可见提示最短间隔,默认 `24`。
|
|
@@ -35,6 +37,12 @@
|
|
|
35
37
|
|
|
36
38
|
环境变量 `AGENTHELM_NO_NUDGE=1` 临时关闭全部输出;`AGENTHELM_NUDGE_DEBUG=1` 把 hook 内部异常打印到 stderr。`agenthelm nudge status [--project P]` 显示生效配置、当前汇总以及开新会话是否会提示。hook 内部的异常(含 opinion-manager 调用失败)仍然静默、退出码为 0,但会把最近 5 次的摘要(时间、钩子名、异常类型、一行截断消息,不含用户原话)记到用户状态目录的 `agenthelm/hook-errors.json`;`nudge status`(JSON 字段 `last_hook_error`)与 `agenthelm doctor` 会显示最近一次,`nudge status --clear-errors` 清除。
|
|
37
39
|
|
|
40
|
+
## 硬限制与已知边界
|
|
41
|
+
|
|
42
|
+
- **hook 路径有硬限制**:`stop` 每会话最多一次(`max_prompts_per_session`),跨会话还受 `prompt_cooldown_hours` 约束,状态在项目的 `.opinion/ask-state.json`。Cursor 的 `stop_prompt` 默认 `off`。
|
|
43
|
+
- **模型自判路径无法硬限制**:无 hook 的客户端,或模型自己决定何时询问,只能靠协议措辞(`ask` 协议要求先运行 `inbox gate`,`digest` / `quiet` 不含任务完成时询问),不保证。
|
|
44
|
+
- **未验证**:Cursor 的 sessionStart 注入、Codex `/hooks` 信任、Claude Stop 的 `additionalContext` 在各版本的表现,均未在真实客户端验证,列入实机验收。
|
|
45
|
+
|
|
38
46
|
## 提示语言
|
|
39
47
|
|
|
40
48
|
给用户看的提示和注入给模型的协议使用同一种语言,目前支持中文(`zh`)和英文(`en`)。按这个顺序决定:配置 `nudge.language`(不是 `auto` 时)→ 环境变量 `AGENTHELM_LANG` → 用户配置 `~/.config/agenthelm/config.json` 的 `language`(所有 agenthelm 命令共用)→ 系统 locale(`LC_ALL`、`LC_MESSAGES`、`LANG`)→ 英文。中文 locale 用中文;其他语言的 locale 暂用英文;`C` / `POSIX` / 空值视为未指定,继续看下一个变量,都没有就用英文。用户配置的 `nudge.language` 优先于项目 Profile,所以你可以按自己的语言覆盖团队的设置。
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# `agenthelm relocate` contract (schema_version 1)
|
|
2
|
+
|
|
3
|
+
中文:[relocate-contract.md](relocate-contract.md)
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
agenthelm relocate <ref> --to <client>:<scope> [--mode copy|link] [--project DIR] [--allow-widen] [--keep-source]
|
|
7
|
+
[--confirm-project-content] [--output json|text] [--lang zh|en|auto]
|
|
8
|
+
[--apply --expect-plan <plan_digest>]
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Skills and MCP entries (below); for a Skill `<ref>` is `skills[].ref` from `agenthelm inventory` (`skill:<name>@<client>:<scope>`, with `#agents` outside the primary store). **Preview by default, zero writes.** `--apply` must carry the `--expect-plan` a preview printed; if the recomputed `plan_digest` differs the command refuses (exit 1, nothing written). Exit codes: 0 success or a preview without blockers; 1 blockers, digest mismatch or a failed write; 2 usage error. macOS and Linux only.
|
|
12
|
+
|
|
13
|
+
## Target stores
|
|
14
|
+
|
|
15
|
+
`claude:user` -> `~/.claude/skills`; `claude:project` -> `<project>/.claude/skills`; `codex:user` -> `~/.agents/skills`; `codex:project` and `cursor:project` -> `<project>/.agents/skills`; `cursor:user` -> `~/.cursor/skills`. When the source already sits in a store the target client reads natively, `plan.status` is `native` and nothing is written.
|
|
16
|
+
|
|
17
|
+
## Rules
|
|
18
|
+
|
|
19
|
+
- **Never overwrites**: an existing same-name target -> `blocked: target-exists-identical|target-exists-different`; no rename, no merge.
|
|
20
|
+
- **Copy vs link**: across scopes (home <-> project) always copy (`--mode link` is blocked with `link-cross-scope`). Within one scope `--mode link` creates a relative symbolic link and implies keeping the source. A path containing a synced-folder name (iCloud, Dropbox, OneDrive, ...; a heuristic) downgrades the link to a copy, `warnings` has `sync-folder-demoted`, and the last step's `promise` is `cannot-promise`.
|
|
21
|
+
- **The source**: by default archived after verification to `~/.agent-pack/recovery/<timestamp>-relocate-<name>/skills/<name>` (a move, not a delete; same layout as the recovery directory of `reconcile --retire-skill`: `<timestamp>-<label>/skills/<name>`, asserted equal by a test); `--keep-source` copies and keeps it. The result gives `recovery_dir` and a one-line manual `mv` restore step; this version has no `restore` command.
|
|
22
|
+
- **Write order and rollback**: recovery directory (0700) -> copy under a temporary name beside the target -> read back (relative path and content digest per file; the `SKILL.md` digest equals the source's) -> rename into place -> archive the source. Any failure removes only what this run created, moves archived sources back and keeps the recovery directory. Symbolic links inside the directory that point outside it -> `source-has-external-symlink`.
|
|
23
|
+
- **Widening** (project -> user level) needs `--allow-widen`, `direction: "widen"`, shown in red in a terminal's text preview.
|
|
24
|
+
- **Entering a project repository** (user -> project level): `confirmations` says the content will enter the project directory and may be committed; `--apply` additionally needs `--confirm-project-content`. License and private content are for the user to judge; the tool cannot.
|
|
25
|
+
- A source without `file` evidence (broken directory, oversized `SKILL.md`) is read-only: `source-not-file-evidence`. Other kinds: `unsupported-kind`.
|
|
26
|
+
|
|
27
|
+
## MCP entries (`mcp:<name>@claude:<user|local|project>`)
|
|
28
|
+
|
|
29
|
+
`<ref>` is `mcps[].ref`; `--to claude:user|local|project` (`project` is the project's `.mcp.json`). Same shell (preview, `plan_digest`, `--expect-plan`, `blocked`, `promise`); writes reuse the Claude sync's local and `.mcp.json` readers and helpers, implemented in `agent_pack_mcp_write.py`. `plan.kind` is `mcp`, `source.managed` says whether agent-pack's state records ownership, and `plan.manual[]` carries the manual command for an unmanaged source.
|
|
30
|
+
|
|
31
|
+
- **Copy only, never overwrite**: an existing target entry of that name → `target-exists-identical|different` (compares a hash of the whole entry, says only same or different, shows no value). `--mode link` → `link-unsupported`.
|
|
32
|
+
- **Direction**: `user` is wider than `local`/`project`; widening (→ `user`) needs `--allow-widen` and is marked red; `local` ↔ `project` is `same`. A `project` target also needs `--confirm-project-content` on `--apply` (the entry enters version control).
|
|
33
|
+
- **Limits for `.mcp.json`**: an inline secret value → `inline-secret-in-project-file` (turn it into a `${VAR}` reference first; the tool never rewrites entries); a machine path → `machine-specific-in-project-file`. A client whose `project_write_supported` is false → `project-write-unsupported`; across clients → `cross-client-unsupported`.
|
|
34
|
+
- **Disposition of the source**: an entry is **managed** only when the state of this project's package records ownership (`mcps` for user level, `scopes.mcps` for local/project). Managed and without `--keep-source`: the target write and the source removal are one atomic replace of `~/.claude.json` (`.mcp.json` is its own atomic write); the whole original file is first backed up byte for byte into the recovery directory (`claude.json.before` / `project-mcp.json.before`), the removed entry's original JSON fragment goes to `mcp/<name>@<scope>.json` (all 0600, directory 0700, never printed), and the state is updated (the `mcps` key still means user level only). On any failure every touched file is restored byte for byte. **Unmanaged** (hand-installed, or owned by another package name): only copied to the new place, the original is left alone, and `plan.manual[]` gives `claude mcp remove --scope <scope> <name>` plus a backup reminder, `not_archivable_by_tool: true`.
|
|
35
|
+
- Recovery: no `restore` command in this version; the result's `restore[]` lists the manual steps (put the fragment back by hand, or restore the whole backup, which loses later changes to that file).
|
|
36
|
+
- Output, `relocate.json` and the plan carry only names, scopes, paths and a 16-hex entry digest, never env values, headers or tokens; only `claude.json.before` and `mcp/*.json` hold the user's own values.
|
|
37
|
+
- When the project Profile's `mcp_scope` differs from the target scope, `warnings` has `declaration-differs` (the next sync follows the declaration).
|
|
38
|
+
|
|
39
|
+
## JSON
|
|
40
|
+
|
|
41
|
+
`{schema_version, command: "relocate", mode: "preview"|"apply", plan, applied}`. `plan`: `ref`, `kind`, `source`, `target`, `mode`, `retire_source`, `direction` (`narrow|same|widen`), `status` (`ready|blocked|native`), `steps[{id,action,promise,...}]`, `blocked[{code,message,...}]`, `warnings[{code,message}]`, `confirmations[{id,text,flag}]`, `recovery_base`, `plan_digest`, `next.apply`. `promise`: `certain` (file-level fact), `best-effort` (needs a client restart or re-entering the project to confirm it shows up), `cannot-promise` (the tool guarantees file changes, not client behavior). `plan_digest` does not depend on the interface language (`message` / `text` are excluded). `applied.status`: `applied|rolled-back|refused|native`. Keys are only appended; the output has no file contents, only names, paths (abbreviated with `~` and `<project>`) and digests.
|