@sakanano-moe/agenthelm 6.8.0 → 6.11.0-rc.2

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 (90) hide show
  1. package/README.md +1 -1
  2. package/README.zh-CN.md +2 -0
  3. package/package.json +1 -1
  4. package/runtime/index.json +6 -6
  5. package/runtime/plugins/agent-pack/.codex-plugin/plugin.json +1 -1
  6. package/runtime/plugins/agent-pack/hooks/hooks.json +32 -0
  7. package/runtime/plugins/agent-pack/plugin.json +1 -1
  8. package/runtime/plugins/agent-pack/references/local-only.md +126 -0
  9. package/runtime/plugins/agent-pack/references/nudge.en.md +58 -0
  10. package/runtime/plugins/agent-pack/references/nudge.md +58 -0
  11. package/runtime/plugins/agent-pack/runtime/agent_pack_nudge.py +613 -0
  12. package/runtime/plugins/agent-pack/runtime/agenthelm.py +1271 -221
  13. package/runtime/plugins/agent-pack/runtime/agenthelm_runtime.py +114 -65
  14. package/runtime/plugins/agent-pack/runtime/i18n_agent_pack.py +78 -0
  15. package/runtime/plugins/agent-pack/runtime/local_only.py +1132 -0
  16. package/runtime/plugins/agent-pack/runtime/locale/en.json +569 -0
  17. package/runtime/plugins/agent-pack/runtime/mcp_server.py +25 -0
  18. package/runtime/plugins/agent-pack/runtime/nudge_text.py +127 -0
  19. package/runtime/plugins/agent-pack/runtime/user_settings.py +275 -0
  20. package/runtime/plugins/agent-pack/skills/agent-pack/SKILL.md +11 -1
  21. package/runtime/plugins/agents-init/.codex-plugin/plugin.json +1 -1
  22. package/runtime/plugins/agents-init/content.json +4 -4
  23. package/runtime/plugins/agents-init/plugin.json +1 -1
  24. package/runtime/plugins/agents-init/skills/agents-init/AGENT.template.md +141 -5
  25. package/runtime/plugins/agents-init/skills/agents-init/SKILL.md +41 -8
  26. package/runtime/plugins/agents-init/skills/agents-init/project.schema.json +408 -80
  27. package/runtime/plugins/agents-init/skills/agents-init/scripts/adopt.py +615 -0
  28. package/runtime/plugins/agents-init/skills/agents-init/scripts/baseline.py +221 -0
  29. package/runtime/plugins/agents-init/skills/agents-init/scripts/i18n_init.py +78 -0
  30. package/runtime/plugins/agents-init/skills/agents-init/scripts/init_project.py +748 -159
  31. package/runtime/plugins/agents-init/skills/agents-init/scripts/locale/en.json +289 -0
  32. package/runtime/plugins/agents-init/skills/agents-init/scripts/merge3.py +149 -0
  33. package/runtime/plugins/agents-init/skills/agents-init/scripts/regions.py +99 -0
  34. package/runtime/plugins/agents-init/skills/agents-init/scripts/scaffold.py +594 -90
  35. package/runtime/plugins/agents-init/skills/agents-init/skeleton.json +2 -0
  36. package/runtime/plugins/agents-init/skills/agents-init/skill.json +1 -1
  37. package/runtime/plugins/opinion-manager/.codex-plugin/plugin.json +1 -1
  38. package/runtime/plugins/opinion-manager/plugin.json +1 -1
  39. package/runtime/plugins/opinion-manager/references/inbox.en.md +48 -0
  40. package/runtime/plugins/opinion-manager/references/inbox.md +48 -0
  41. package/runtime/plugins/opinion-manager/runtime/context.py +31 -26
  42. package/runtime/plugins/opinion-manager/runtime/i18n_opinion.py +78 -0
  43. package/runtime/plugins/opinion-manager/runtime/inbox.py +398 -0
  44. package/runtime/plugins/opinion-manager/runtime/inbox_text.py +114 -0
  45. package/runtime/plugins/opinion-manager/runtime/lifecycle.py +45 -44
  46. package/runtime/plugins/opinion-manager/runtime/locale/en.json +193 -0
  47. package/runtime/plugins/opinion-manager/runtime/opinion_manager.py +55 -50
  48. package/runtime/plugins/opinion-manager/runtime/versioned.py +90 -85
  49. package/runtime/plugins/opinion-manager/skills/opinion-manager/SKILL.md +15 -2
  50. package/runtime/plugins/project-orchestrator/.codex-plugin/plugin.json +1 -1
  51. package/runtime/plugins/project-orchestrator/content.json +30 -3
  52. package/runtime/plugins/project-orchestrator/plugin.json +1 -1
  53. package/runtime/plugins/project-orchestrator/references/case-workspaces.md +9 -1
  54. package/runtime/plugins/project-orchestrator/references/case.schema.json +1 -0
  55. package/runtime/plugins/project-orchestrator/references/sop-interview.md +83 -0
  56. package/runtime/plugins/project-orchestrator/references/sop.md +156 -0
  57. package/runtime/plugins/project-orchestrator/runtime/assets.py +52 -57
  58. package/runtime/plugins/project-orchestrator/runtime/case.py +139 -80
  59. package/runtime/plugins/project-orchestrator/runtime/case_structure.py +71 -0
  60. package/runtime/plugins/project-orchestrator/runtime/case_workspace.py +47 -46
  61. package/runtime/plugins/project-orchestrator/runtime/i18n_orchestrator.py +78 -0
  62. package/runtime/plugins/project-orchestrator/runtime/locale/en.json +1450 -0
  63. package/runtime/plugins/project-orchestrator/runtime/memory.py +45 -45
  64. package/runtime/plugins/project-orchestrator/runtime/private_paths.py +119 -0
  65. package/runtime/plugins/project-orchestrator/runtime/project_base.py +37 -19
  66. package/runtime/plugins/project-orchestrator/runtime/project_cli.py +307 -195
  67. package/runtime/plugins/project-orchestrator/runtime/project_demo.py +130 -48
  68. package/runtime/plugins/project-orchestrator/runtime/project_maintain.py +328 -221
  69. package/runtime/plugins/project-orchestrator/runtime/project_menu.py +167 -89
  70. package/runtime/plugins/project-orchestrator/runtime/project_real.py +187 -105
  71. package/runtime/plugins/project-orchestrator/runtime/project_write.py +58 -55
  72. package/runtime/plugins/project-orchestrator/runtime/sop.py +1670 -0
  73. package/runtime/plugins/project-orchestrator/runtime/sop_structure.py +226 -0
  74. package/runtime/plugins/project-orchestrator/runtime/wf.py +74 -70
  75. package/runtime/plugins/project-orchestrator/skills/project-orchestrator/SKILL.md +22 -0
  76. package/runtime/plugins/project-orchestrator/sop-templates/blank/SOP.en.md +57 -0
  77. package/runtime/plugins/project-orchestrator/sop-templates/blank/SOP.md +57 -0
  78. package/runtime/plugins/project-orchestrator/sop-templates/knowledge-digest/SOP.en.md +77 -0
  79. package/runtime/plugins/project-orchestrator/sop-templates/knowledge-digest/SOP.md +77 -0
  80. package/runtime/plugins/project-orchestrator/sop-templates/knowledge-digest/templates/digest.en.md +11 -0
  81. package/runtime/plugins/project-orchestrator/sop-templates/knowledge-digest/templates/digest.md +11 -0
  82. package/runtime/plugins/project-orchestrator/sop-templates/video-to-transcript/SOP.en.md +87 -0
  83. package/runtime/plugins/project-orchestrator/sop-templates/video-to-transcript/SOP.md +87 -0
  84. package/runtime/plugins/project-orchestrator/sop-templates/weekly-review/SOP.en.md +75 -0
  85. package/runtime/plugins/project-orchestrator/sop-templates/weekly-review/SOP.md +75 -0
  86. package/runtime/plugins/project-orchestrator/sop-templates/weekly-review/templates/review.en.md +11 -0
  87. package/runtime/plugins/project-orchestrator/sop-templates/weekly-review/templates/review.md +12 -0
  88. package/runtime/plugins/project-orchestrator/templates/CASE.en.md +39 -0
  89. package/runtime/plugins/agents-init/skills/agents-init/scripts/test_init_project.py +0 -678
  90. package/runtime/plugins/agents-init/skills/agents-init/scripts/test_scaffold.py +0 -551
@@ -159,13 +159,75 @@ Agent Plugins 1.0 可移植文件直接位于 `.agents/`:`plugin.json`、`skil
159
159
 
160
160
  不需要 Agent 也能运行 `ENTRY_COMMAND` 打开项目菜单:找资料、看进展、项目指南、检查与维护。Agent 需要同样的信息时调用它的子命令并加 `--output json`(例如 `ENTRY_COMMAND find <词> --output json`),不另写一套查找逻辑;写入类子命令默认只预览。
161
161
 
162
+ PRIVACY_SECTION
163
+
162
164
  ## 项目专属入口
163
165
 
164
166
  - 命令:TODO
165
167
  - 测试:TODO
166
168
  - 构建:TODO
167
169
  - 架构/文档:TODO
168
- - 隐私或禁止路径:未声明
170
+ - 用户规则:若存在 `AGENT.USER.md`(接管项目时从原 `AGENTS.md` 移出的用户内容),与本文件一并遵循。
171
+ ```
172
+ <!-- /agents-init:template -->
173
+
174
+ ### 隐私约定
175
+
176
+ `AGENTS.md` 模板里的 `PRIVACY_SECTION` 按 Project Profile 的 `privacy.forbidden_default_reads` 是否为空,取下面四个区块之一(随项目文件语言 `language` 选择中文或英文)。约定**引用字段名而不复制路径**:Agent 以 Profile 字段为准,修改字段里的路径不需要同步改 `AGENTS.md`;字段在“空”与“非空”之间变化时,`check` 报告 `AGENTS.md` 与 Profile 不一致。约定只写在 `AGENTS.md`,`CLAUDE.md` 只做跳转。英文区块只为这一条约定提供,其余英文模板另行推进。
177
+
178
+ <!-- agents-init:template privacy/declared -->
179
+ ```markdown
180
+ ## 隐私约定
181
+
182
+ 本项目的私有路径由 Project Profile 的 `privacy.forbidden_default_reads` 声明(新项目缺省为 `private/`),以该字段为准,本文件不重复列出路径。
183
+
184
+ - 默认不读:不读取、不列目录、不搜索这些路径下的内容。
185
+ - 需要读取时,先向用户列出要读的路径和用途,得到用户确认后再读。
186
+ - 一次确认只对当次任务和当次列出的路径有效,不延续到后续任务;后续任务需要再读,重新确认。
187
+ - 确认后用 `sop.py confirm-read <Case> <路径…> --apply` 记入该 Case 的决策记录(同时把 Case 标为 private);项目有自己的确认记录机制时,按项目的机制记录。
188
+ ```
189
+ <!-- /agents-init:template -->
190
+
191
+ <!-- agents-init:template privacy/undeclared -->
192
+ ```markdown
193
+ ## 隐私约定
194
+
195
+ 未声明私有路径:Project Profile 的 `privacy.forbidden_default_reads` 为空,没有需要先经用户确认才能读取的路径。
196
+ ```
197
+ <!-- /agents-init:template -->
198
+
199
+ <!-- agents-init:template privacy/declared.en -->
200
+ ```markdown
201
+ ## Privacy convention
202
+
203
+ This project's private paths are declared in the Project Profile field `privacy.forbidden_default_reads` (new projects default to `private/`). The field is the source of truth; this file does not repeat the paths.
204
+
205
+ - Do not read by default: do not read, list or search the content under these paths.
206
+ - When a read is needed, first list the paths and the purpose to the user and read only after the user confirms.
207
+ - One confirmation covers only the current task and the paths listed then; it does not carry over to later tasks. Ask again when a later task needs them.
208
+ - After confirmation, record it with `sop.py confirm-read <Case> <path…> --apply` (it goes into the Case's decision record and marks the Case private); if the project has its own confirmation record, use that.
209
+ ```
210
+ <!-- /agents-init:template -->
211
+
212
+ <!-- agents-init:template privacy/undeclared.en -->
213
+ ```markdown
214
+ ## Privacy convention
215
+
216
+ No private paths declared: the Project Profile field `privacy.forbidden_default_reads` is empty, so no path needs user confirmation before it is read.
217
+ ```
218
+ <!-- /agents-init:template -->
219
+
220
+ `AGENT.RULES.md` 的「隐私与外部系统」里“默认禁止读取”一行由 `PRIVACY_RULES_LINE` 渲染,同样**引用字段名而不复制路径**,与 `AGENTS.md` 的隐私约定保持一致(字段为空与非空文字相同,不再写死“未声明”)。英文版本只为这一行提供。已有项目的升级沿用 `update-content` 的既有流程:`AGENT.RULES.md` 未改过则直接更新,改过的走 `--keep` / `--append` / `--accept` / `--merge`。
221
+
222
+ <!-- agents-init:template privacy/rules-line -->
223
+ ```markdown
224
+ 默认禁止读取:以 Project Profile 的 `privacy.forbidden_default_reads` 为准(见 `AGENTS.md` 的“隐私约定”),本文件不重复列出路径;字段为空表示未声明
225
+ ```
226
+ <!-- /agents-init:template -->
227
+
228
+ <!-- agents-init:template privacy/rules-line.en -->
229
+ ```markdown
230
+ Do not read by default: the Project Profile field `privacy.forbidden_default_reads` is the source of truth (see "Privacy convention" in `AGENTS.md`); this file does not repeat the paths. An empty field means none declared
169
231
  ```
170
232
  <!-- /agents-init:template -->
171
233
 
@@ -194,7 +256,7 @@ Agent Plugins 1.0 可移植文件直接位于 `.agents/`:`plugin.json`、`skil
194
256
 
195
257
  ## 隐私与外部系统
196
258
 
197
- - 默认禁止读取:未声明
259
+ - PRIVACY_RULES_LINE
198
260
  - 需要授权的外部写入:全部,除非另有明确配置
199
261
 
200
262
  ## 记忆
@@ -222,6 +284,18 @@ Agent Plugins 1.0 可移植文件直接位于 `.agents/`:`plugin.json`、`skil
222
284
 
223
285
  ### CLAUDE.md 与 AGENT.md
224
286
 
287
+ Claude Code 在工作目录及其上级目录没有任何 `CLAUDE.md` 时才直接读取 `AGENTS.md`(v2.1.277 起),两者并存时只读 `CLAUDE.md`;旧版本、禁用内置插件以及部分会话也读不到 `AGENTS.md`。因此 `CLAUDE.md` 保留为一行 `@AGENTS.md` 的导入桩,`AGENTS.md` 是唯一内容来源,Claude 专属指令写在导入行下面。`AGENT.md` 给其他客户端,用文字路由。
288
+
289
+ <!-- agents-init:template CLAUDE.md -->
290
+ ```markdown
291
+ @AGENTS.md
292
+
293
+ ## Claude Code
294
+
295
+ Claude Code 专属指令写在这里;项目通用规则放在 `AGENTS.md` 与 `AGENT.RULES.md`。
296
+ ```
297
+ <!-- /agents-init:template -->
298
+
225
299
  <!-- agents-init:template ROUTE.md -->
226
300
  ```markdown
227
301
  # Agent 路由
@@ -230,6 +304,56 @@ Agent Plugins 1.0 可移植文件直接位于 `.agents/`:`plugin.json`、`skil
230
304
  ```
231
305
  <!-- /agents-init:template -->
232
306
 
307
+ ### 受管区块模板
308
+
309
+ 接管已有文件时,工具只向用户的文件追加带标记的区块(见 `scripts/regions.py`),区块之外的内容保持原样。区块正文来自下面的模板,随内容包更新;区块内部被改过时不会被覆盖,由用户选择。
310
+
311
+ <!-- agents-init:template region/claude-import -->
312
+ ```markdown
313
+ @AGENTS.md
314
+ ```
315
+ <!-- /agents-init:template -->
316
+
317
+ <!-- agents-init:template region/agents-contract -->
318
+ ```markdown
319
+ ## agenthelm 项目契约
320
+
321
+ 本项目由 agenthelm 管理项目生命周期。开始实质工作前:
322
+
323
+ 1. 加载 `project-orchestrator`,读取 `.agents/moe.sakanano.agent-pack/project.json`(Project Profile)。
324
+ 2. 项目专属约束见 `AGENT.RULES.md`;Plugin/Skill/MCP 管理交给 `agent-pack`;Opinion 交给 `opinion-manager`。
325
+ 3. 本文件其余部分是接管项目前就有的用户规则,与上述契约一并遵循。
326
+ ```
327
+ <!-- /agents-init:template -->
328
+
329
+ `privacy-contract` 是独立于 `agents-contract` 的区块:用户改过 `AGENTS.md` 的项目升级时,由 `update-content --append AGENTS.md` 补入;已发布的 `agents-contract` 区块正文不变。区块正文只有“已声明”一种(字段为空时不追加),英文版本为 `region/privacy-contract.en`。
330
+
331
+ <!-- agents-init:template region/privacy-contract -->
332
+ ```markdown
333
+ ## 隐私约定
334
+
335
+ 本项目的私有路径由 Project Profile 的 `privacy.forbidden_default_reads` 声明(新项目缺省为 `private/`),以该字段为准,本文件不重复列出路径。
336
+
337
+ - 默认不读:不读取、不列目录、不搜索这些路径下的内容。
338
+ - 需要读取时,先向用户列出要读的路径和用途,得到用户确认后再读。
339
+ - 一次确认只对当次任务和当次列出的路径有效,不延续到后续任务;后续任务需要再读,重新确认。
340
+ - 确认后用 `sop.py confirm-read <Case> <路径…> --apply` 记入该 Case 的决策记录(同时把 Case 标为 private);项目有自己的确认记录机制时,按项目的机制记录。
341
+ ```
342
+ <!-- /agents-init:template -->
343
+
344
+ <!-- agents-init:template region/privacy-contract.en -->
345
+ ```markdown
346
+ ## Privacy convention
347
+
348
+ This project's private paths are declared in the Project Profile field `privacy.forbidden_default_reads` (new projects default to `private/`). The field is the source of truth; this file does not repeat the paths.
349
+
350
+ - Do not read by default: do not read, list or search the content under these paths.
351
+ - When a read is needed, first list the paths and the purpose to the user and read only after the user confirms.
352
+ - One confirmation covers only the current task and the paths listed then; it does not carry over to later tasks. Ask again when a later task needs them.
353
+ - After confirmation, record it with `sop.py confirm-read <Case> <path…> --apply` (it goes into the Case's decision record and marks the Case private); if the project has its own confirmation record, use that.
354
+ ```
355
+ <!-- /agents-init:template -->
356
+
233
357
  ### 流程占位文件
234
358
 
235
359
  `.agent-doc/plan.md`:
@@ -330,10 +454,22 @@ Agent Plugins 1.0 可移植文件直接位于 `.agents/`:`plugin.json`、`skil
330
454
  5. 保持历史 Task/Case 与能力源完整,随后使用 `agent-pack` 盘点。
331
455
  6. 只有得到明确授权,才能把个人 Opinion 内容移入私有权威源。
332
456
 
457
+ ### 接管已有内容的目录
458
+
459
+ 目录里已经有自己的文件时,原则是**控制新增,不追溯历史**:与骨架冲突的旧文件可以长期并存,不是阻塞项;只有用户显式选择,才改动已有文件,且先备份到项目外。
460
+
461
+ 1. `--mode scan`(只读):列出路径碰撞、目录含义是否相同、`AGENTS.md` / `CLAUDE.md` 的状况,每项给出选项和推荐。
462
+ 2. `--mode adopt`(默认预览,`--apply` 才写入):已有文件原样保留,只补缺失的骨架;保留下来且与模板不同的文件记入决定文件,`check` 不再追问。
463
+ 3. 改动已有文件才需要显式选择(原件缺省自动备份到 `~/.agent-pack/recovery/`,`--recovery-dir` 可改到项目外的其他位置):`--agents-policy append|split|side-by-side`、`--claude-policy add-import`。`split` 用 `--route <章节序号>=<agents|rules|user|opinion|sop>` 指定每个章节的去向(建议来自关键词启发式,最终由用户决定;`opinion` / `sop` 先放进 `AGENT.USER.md` 并标注待交接)。
464
+ 4. 目录含义冲突的用 `--case-root` / `--memory-root` 另设位置,已有的工作容器目录用 `--register-root` 只读登记。
465
+ 5. 追加到用户文件里的内容是带标记的受管区块(见 `scripts/regions.py`),区块之外不动;区块内部被改过时升级不覆盖,用 `--mode region` 逐个 `--keep` / `--accept`。
466
+
467
+ 历史内容什么时候迁移由用户决定:之后可以用 `--mode adopt` 以外的迁移工具逐步把旧内容整理进标准结构,不影响日常使用。
468
+
333
469
  ### 将既有项目整理为 Case 工作目录
334
470
 
335
471
  1. 阅读同包 `project-orchestrator/references/case-workspaces.md`,明确 Case 的目标、子工作项与专属材料范围。
336
- 2. 使用 `--mode migrate --work-mode case-workspace --replace .agents/moe.sakanano.agent-pack/project.json --recovery-dir <项目外恢复目录>` 预演;旧 task 配置保存为 `legacy_task`,原业务文件保持在原位,等待独立的已授权数据迁移。
472
+ 2. 使用 `--mode migrate --work-mode case-workspace --replace .agents/moe.sakanano.agent-pack/project.json` 预演(原件缺省备份到 `~/.agent-pack/recovery/`,`--recovery-dir` 可改位置);旧 task 配置保存为 `legacy_task`,原业务文件保持在原位,等待独立的已授权数据迁移。
337
473
  3. Profile 替换保留项目自定义的 runtime、opinion、memory、capabilities 和 privacy。未显式选择模式时保留现有 `work` 段。
338
474
  4. 展示全部 Task、Case 专属输入和交付物的目标映射,Demo 通过后用 `case_workspace.py migrate` 实施;保留旧 TASK.md、progress、旧 ID 与真实完成或放弃证据。
339
475
  5. 用项目 Tool 校验 Case、链接和索引,验证旧名称检索与全量统计;迁移完成后关闭生产态 Task 创建入口。其他项目单独授权并迁移。
@@ -341,7 +477,7 @@ Agent Plugins 1.0 可移植文件直接位于 `.agents/`:`plugin.json`、`skil
341
477
  ### 为已初始化的项目补上人用入口
342
478
 
343
479
  1. `--mode entry --entry-name <名称>` 预览:只涉及 Profile 的 `entry` 段、根目录启动器与内容锁;加 `--readme-entry` 时在 README 末尾追加带标记的「怎样使用」。
344
- 2. 根目录已有同名文件时视为用户自己的文件:`--keep <名称>` 保留(不跟踪更新),`--accept <名称>` 用模板替换并先备份到 `--recovery-dir`;不选则不写入。
480
+ 2. 根目录已有同名文件时视为用户自己的文件:`--keep <名称>` 保留(不跟踪更新),`--accept <名称>` 用模板替换并先备份(缺省 `~/.agent-pack/recovery/`,`--recovery-dir` 可改位置);不选则不写入。
345
481
  3. 确认后加 `--apply`,再运行 `./<名称> health` 验证。也可以在菜单「检查项目与环境」里处理“项目根目录还没有人用入口”。
346
482
 
347
483
  ### 为既有 v6 项目补充记忆与分层加载
@@ -360,7 +496,7 @@ v5 把生命周期与扩展管理合并在 `project-runtime` 中,Profile 位
360
496
 
361
497
  1. 保留 `profile`、`capabilities`、`work`、`privacy`、`opinion` 与 `runtime` 中的项目自定义字段;
362
498
  2. 把 `runtime.skill` / `runtime.plugin` 改为 `project-orchestrator`,写入 `runtime.capability_manager = "agent-pack"`;
363
- 3. 写入新路径 `.agents/moe.sakanano.agent-pack/project.json`,并把旧文件移动到 `--recovery-dir`(必须位于项目外);
499
+ 3. 写入新路径 `.agents/moe.sakanano.agent-pack/project.json`,并把旧文件移动到恢复目录(缺省 `~/.agent-pack/recovery/`,`--recovery-dir` 可改位置,必须位于项目外);
364
500
  4. 入口文件中的 `project-runtime` 引用不自动改写,由用户逐项选择 `--replace` 或手动精简。
365
501
 
366
502
  迁移后在各客户端用 `agent-pack reconcile --retire-plugin project-runtime` 归档旧 Plugin。
@@ -51,16 +51,20 @@ python3 scripts/init_project.py --project /path/to/project \
51
51
  --stack python --runtime local --agent-cli codex --apply
52
52
  ```
53
53
 
54
- 新项目默认在根目录生成启动器 `menu`(人不经过 Agent 打开项目菜单),并在 Profile 写入 `entry` 段;用户想用别的名字时传 `--entry-name <名称>`,不要启动器时传 `--no-entry`。README.md 不存在时新建并写入「怎样使用」,已存在的不改动。
54
+ **项目文件语言**:初始化前先问用户项目里的文件用中文还是英文(用户没有特别要求时取当前对话的语言),用 `--language zh|en` 传入;不传时取当前界面语言(`AGENTHELM_LANG`、系统 locale,最后英文)。它写进 Profile 的 `language`,决定新建 Case 的小节名与默认文字、README 追加的使用说明用哪种语言,随项目同步,与各人的命令行界面语言无关;缺省的旧项目保持中文。`--mode migrate` 缺省保持中文,要改传 `--language en`。
55
55
 
56
- 为已初始化的项目补上入口只用 `--mode entry`,它只涉及 Profile 的 `entry` 段、启动器与内容锁;根目录已有同名文件时视为用户的文件,必须由用户选择 `--keep` 或 `--accept`(替换前备份到 `--recovery-dir`):
56
+ 已有项目没有 `language` 时按中文生成。要改,用 `--mode language --language zh|en`(或 `agenthelm config project-language zh|en`):默认只预览,`--apply` 只把 Profile 的 `language` 写成所选值(Profile 先备份),不改写任何已有文件;`check` 的 `project_language` 字段给出项目是否声明了它。
57
+
58
+ 新项目默认在根目录生成启动器 `menu`(人不经过 Agent 打开项目菜单),并在 Profile 写入 `entry` 段;用户想用别的名字时传 `--entry-name <名称>`,不要启动器时传 `--no-entry`。README.md 不存在时新建并写入使用说明小节(中文项目叫「怎样使用」,英文项目叫 How to use),已存在的不改动。
59
+
60
+ 为已初始化的项目补上入口只用 `--mode entry`,它只涉及 Profile 的 `entry` 段、启动器与内容锁;根目录已有同名文件时视为用户的文件,必须由用户选择 `--keep` 或 `--accept`(替换前自动备份,见下文“备份与还原”):
57
61
 
58
62
  ```bash
59
63
  python3 scripts/init_project.py --project /path/to/project --mode entry --entry-name menu
60
64
  python3 scripts/init_project.py --project /path/to/project --mode entry --entry-name menu --readme-entry --apply
61
65
  ```
62
66
 
63
- 迁移既有项目时,保留所有碰撞文件,只显式替换已审阅的路径。替换或退役旧 Profile 必须指定项目外恢复目录:
67
+ 迁移既有项目时,保留所有碰撞文件,只显式替换已审阅的路径。替换或退役旧 Profile 前,原件会先备份(缺省 `~/.agent-pack/recovery/`,也可用 `--recovery-dir` 指定项目外的目录):
64
68
 
65
69
  ```bash
66
70
  python3 scripts/init_project.py --mode migrate --project /path/to/project \
@@ -69,17 +73,38 @@ python3 scripts/init_project.py --mode migrate --project /path/to/project \
69
73
  --replace AGENTS.md --recovery-dir /safe/recovery/example-v6 --apply
70
74
  ```
71
75
 
72
- 已初始化的项目对照最新脚手架用 `--mode check`(只读);其余模式默认只预览,`--apply` 才写入,已有文件不被覆盖,替换前备份到 `--recovery-dir`:
76
+ 目录里已有自己的文件时(没有 Project Profile)先扫描,再接管。原则是控制新增、不追溯历史:与骨架冲突的旧文件可以长期并存,不是阻塞项;只有用户显式选择,才改动已有文件,且先自动备份到项目外:
77
+
78
+ ```bash
79
+ python3 scripts/init_project.py --project /path/to/project --mode scan # 只读:冲突、选项与推荐
80
+ python3 scripts/init_project.py --project /path/to/project --mode adopt \
81
+ --name example --project-type code --vcs github --stack python --runtime local --agent-cli codex # 预览
82
+ python3 scripts/init_project.py ... --mode adopt --agents-policy append --claude-policy add-import \
83
+ --apply # 改动已有文件须显式选择;原件自动备份
84
+ ```
85
+
86
+ - `AGENTS.md` 已有用户内容:`keep`(缺省,不动)、`append`(推荐:原文不动,追加带标记的项目契约区块)、`split`(`--route <章节序号>=<agents|rules|user|opinion|sop>`,未指定的章节留下)、`side-by-side`(原文整体移到 `AGENT.USER.md`)。章节去向建议只来自关键词启发式,逐段判断放在 session 里与用户确认,再把结果交给 `--route`;写入始终经由本命令。
87
+ - `CLAUDE.md` 已有内容但没有导入 `AGENTS.md`:Claude Code 两者并存时只读 `CLAUDE.md`,项目契约不会加载,推荐 `--claude-policy add-import`。
88
+ - `cases/`、`memory/` 被别的内容占用:并存,或 `--case-root` / `--memory-root` 另设位置;已有工作容器用 `--register-root` 只读登记。
89
+ - 追加进用户文件的是受管区块(`scripts/regions.py`):区块之外不动,区块内部被改过时升级不覆盖,用 `--mode region` 逐个 `--keep <文件>#<ID>` / `--accept <文件>#<ID>`。
90
+
91
+ 已初始化的项目对照最新脚手架用 `--mode check`(只读);其余模式默认只预览,`--apply` 才写入,已有文件不被覆盖,替换前自动备份:
73
92
 
74
93
  ```bash
75
- python3 scripts/init_project.py --project /path/to/project --mode check
94
+ python3 scripts/init_project.py --project /path/to/project --mode check # 退出码:有任何差异为 1;加 --required-only 则只有「需要处理」的发现为 1(与 agenthelm check 一致)
76
95
  python3 scripts/init_project.py --project /path/to/project --mode add-skeleton [--target docs/refs/README.md]
77
- python3 scripts/init_project.py --project /path/to/project --mode profile [--target runtime.commit_policy] --recovery-dir /safe/recovery/example
96
+ python3 scripts/init_project.py --project /path/to/project --mode profile [--target runtime.commit_policy]
78
97
  python3 scripts/init_project.py --project /path/to/project --mode repair-lock
79
98
  python3 scripts/init_project.py --project /path/to/project --mode decide --target skel:docs/drafts/.gitkeep --decision skip --reason "…" --apply
80
99
  python3 scripts/init_project.py --project /path/to/project --mode case-naming # 只给改名计划,不移动目录
81
100
  ```
82
101
 
102
+ **内容刷新(`--mode refresh`)遇到你改过的文件**:模板更新后,未改动的文件先备份再替换;你改过的文件必须逐个选择,不会被静默覆盖。没有内容锁基线的项目(早期版本初始化)里,所有与新模板不同的文件都算“你改过”,预览会写明这个原因和每个文件的差异摘要(`local_lines`、`template_lines`、`lines_added`、`lines_lost`)。选择:`--keep <文件>` 保留(建议;会被记住,之后不再追问);`--append <文件>`(只限 `AGENTS.md`、`CLAUDE.md`)保留原文、只在末尾追加带标记的受管区块;`--accept <文件>` 换成新模板,会丢弃 `lines_lost` 行本地内容,所以须再加 `--confirm-discard <文件>` 才会执行;`--diff <文件>` 只看完整差异,不写入。
103
+
104
+ **三方合并(`--merge <文件>`)**:你改过、新模板也变了的文件,用内容锁记录的版本找回旧内容包(本机运行时缓存 → 本地 git tag → GitHub Release,发布包核对 SHA-256),重新渲染出升级前的基线(渲染结果必须与内容锁里的文件摘要一致才采用),再按行做基线 / 你的版本 / 新模板的三方合并。无冲突的部分自动并入并给差异预览;有冲突的块保留两边与基线并标记,用 `--pick <文件>#<块序号>=mine|theirs|both` 逐块选择,没选完不写入。默认只预览,`--apply` 前先备份并输出恢复位置。取不到旧包(离线、没有 tag)或内容锁没有基线时整个文件退回 `--keep` / `--append` / `--accept`,不改任何文件;`AGENTHELM_NO_UPDATE_CHECK=1` 关闭联网。
105
+
106
+ **备份与还原**:`refresh`、`adopt`、`region`、`profile`、`entry`、`migrate` 这些会替换用户文件的模式,不必先想一个备份目录——`--apply` 时原件自动复制到 `~/.agent-pack/recovery/<UTC 时间>-agenthelm-<模式>/`(与 `agenthelm update`、`migrate` 的位置和命名一致),一次操作的所有被替换文件放在同一个目录。命令输出(文本和 `--output json` 的 `recovery`、`recovery_files`、`recovery_default` 字段)会说明备份位置;还原就是把备份里的文件按相同的相对路径复制回项目。显式传入的 `--recovery-dir` 仍然优先,但必须在项目外,项目内的目录会被拒绝。备份目录无法创建或写入时,命令在改动任何项目文件之前就失败并说明原因,不会跳过备份。预览(不带 `--apply`)不创建任何目录。
107
+
83
108
  期望骨架清单是 [skeleton.json](skeleton.json)(内容包 `agents-init/project-skeleton`);Opinion、Profile 里的项目自有字段与审计字段不参与比较。用户的跳过 / 保留决定写入 `.agents/moe.sakanano.agent-pack/check-decisions.json`,随项目同步。日常入口是 `agenthelm check` 与 `agenthelm fix`。
84
109
 
85
110
  ## 输出契约
@@ -107,6 +132,10 @@ cases/
107
132
  └── .gitkeep
108
133
  memory/
109
134
  └── .gitkeep
135
+ sops/
136
+ └── .gitkeep
137
+ private/
138
+ └── .gitignore
110
139
  docs/
111
140
  ├── refs/README.md
112
141
  └── drafts/.gitkeep
@@ -114,13 +143,17 @@ docs/
114
143
 
115
144
  `AGENTS.md` 是项目执行入口;`CLAUDE.md` 与 `AGENT.md` 是短路由文件;初始化产生的 `OPINION.md` 保持为空白配置入口。用户确认后由 `opinion-manager` 写入当前项目;用户内容禁止复制到公开模板、示例、测试或文档。
116
145
 
146
+ 新项目的 Profile 声明 `privacy.forbidden_default_reads: ["private/"]` 并建立 `private/`(里面的 `.gitignore` 让内容默认不进入 git):私有信息放在这里,Agent 默认不读,读之前须经用户确认;用到它的 Case 标为 `sensitivity: private`。已有项目没有声明时 `check` 不要求 `private/`,不会多出差异。
147
+
148
+ 新项目的 Profile 带 `sop: {"root": "sops"}`,并建立 `sops/`:用户自己的流程(SOP)放在这里,由 `project-orchestrator` 的 `runtime/sop.py` 管理。已有项目没有 `sop` 段时 `check` 不要求 `sops/`,想启用就在 Profile 加这一段并运行 `fix add-skeleton`。
149
+
117
150
  新项目默认 `work.mode=case-workspace`。`--work-mode legacy` 可保留旧分类;既有项目迁移时未显式选择模式就保持现有模式。Case 数据迁移由 `project-orchestrator` 的已审阅映射工具执行,初始化器只更新骨架与 Profile。
118
151
 
119
152
  ## 迁移规则
120
153
 
121
154
  - 只根据明确版本标记识别旧版本;禁止把陌生结构推断为 v4 或 v5。
122
- - 使用 `--mode migrate`;未选择的碰撞文件保持原样。写入新骨架文件前,每个 `--replace` 路径都必须备份到项目外。
123
- - 检测到 v5 Profile(`.agents/moe.sakanano.project-runtime/project.json`)时,初始化模式以 `migrate-required` 停止;迁移模式保留其项目自定义字段并升级到 `.agents/moe.sakanano.agent-pack/project.json`,旧文件移入 `--recovery-dir`。
155
+ - 使用 `--mode migrate`;未选择的碰撞文件保持原样。写入新骨架文件前,每个 `--replace` 路径都会先备份到项目外。
156
+ - 检测到 v5 Profile(`.agents/moe.sakanano.project-runtime/project.json`)时,初始化模式以 `migrate-required` 停止;迁移模式保留其项目自定义字段并升级到 `.agents/moe.sakanano.agent-pack/project.json`,旧文件移入备份目录。
124
157
  - 保留项目事实与本地约束。入口文件中的 `project-runtime` 引用由用户逐项选择 `--replace` 或手动精简。
125
158
  - 只有在 `project-orchestrator`、`agent-pack` 与 `opinion-manager` 可用后,才从 Agent 入口文件移除重复的职责说明。
126
159
  - 只有得到明确授权,才能把个人/全局规则移入用户的私有权威源;禁止提交到本公开模板。