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

package/runtime/plugins/agents-init/content.json

@@ -3,7 +3,7 @@
   "packs": [
     {
       "id": "agents-init/project-contract",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "kind": "template",
       "title": "项目契约模板",
       "description": "初始化时渲染为项目入口文件的中文模板与根目录启动器；更新后由用户逐文件选择是否重新渲染。",
@@ -20,7 +20,7 @@
       ],
       "project_lock": "agenthelm",
       "files": {
-        "skills/agents-init/AGENT.template.md": "cb35f9a20b845686f24823c03bc71c5b93683dc750b61bd4eae733da2085b056",
+        "skills/agents-init/AGENT.template.md": "780f32a1137044274ab9d8b8f736dc59875acfca58ff3963611182131398cbc1",
         "skills/agents-init/launcher.sh": "cf27d6cca786905a192446ea4eefe5635942914c3358c78d12117af912107cad"
       },
       "materializes_from_profile": [
@@ -29,7 +29,7 @@
     },
     {
       "id": "agents-init/project-skeleton",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "kind": "manifest",
       "title": "期望骨架清单",
       "description": "项目脚手架应有的文件、Profile 受检字段与不参与比较的字段（审计字段、Opinion 设置）；agenthelm check 据此对比项目，不写入项目。",
@@ -39,7 +39,7 @@
       "materializes": [],
       "project_lock": "none",
       "files": {
-        "skills/agents-init/skeleton.json": "70ea5e360f018c0d840d5d7aa022f811d665642a2d127f254f7a76335b4e77da"
+        "skills/agents-init/skeleton.json": "4a7c2ccaed293bc63ae2f3b3e6c8fa5e906292462f81c41a0fc88fcb22a3eeeb"
       }
     }
   ]

package/runtime/plugins/agents-init/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "agents-init",
-  "version": "6.7.0",
+  "version": "6.8.0",
   "description": "Initialize or migrate an Agent project contract (AGENTS.md, Project Profile, root launcher); ships with project-orchestrator, agent-pack and opinion-manager.",
   "author": {
     "name": "lc4t"

package/runtime/plugins/agents-init/skills/agents-init/AGENT.template.md

@@ -166,6 +166,7 @@ Agent Plugins 1.0 可移植文件直接位于 `.agents/`：`plugin.json`、`skil
 - 构建：TODO
 - 架构/文档：TODO
 - 隐私或禁止路径：未声明
+- 用户规则：若存在 `AGENT.USER.md`（接管项目时从原 `AGENTS.md` 移出的用户内容），与本文件一并遵循。
 ```
 <!-- /agents-init:template -->
 
@@ -222,6 +223,18 @@ Agent Plugins 1.0 可移植文件直接位于 `.agents/`：`plugin.json`、`skil
 
 ### CLAUDE.md 与 AGENT.md
 
+Claude Code 在工作目录及其上级目录没有任何 `CLAUDE.md` 时才直接读取 `AGENTS.md`（v2.1.277 起），两者并存时只读 `CLAUDE.md`；旧版本、禁用内置插件以及部分会话也读不到 `AGENTS.md`。因此 `CLAUDE.md` 保留为一行 `@AGENTS.md` 的导入桩，`AGENTS.md` 是唯一内容来源，Claude 专属指令写在导入行下面。`AGENT.md` 给其他客户端，用文字路由。
+
+<!-- agents-init:template CLAUDE.md -->
+```markdown
+@AGENTS.md
+
+## Claude Code
+
+Claude Code 专属指令写在这里；项目通用规则放在 `AGENTS.md` 与 `AGENT.RULES.md`。
+```
+<!-- /agents-init:template -->
+
 <!-- agents-init:template ROUTE.md -->
 ```markdown
 # Agent 路由
@@ -230,6 +243,28 @@ Agent Plugins 1.0 可移植文件直接位于 `.agents/`：`plugin.json`、`skil
 ```
 <!-- /agents-init:template -->
 
+### 受管区块模板
+
+接管已有文件时，工具只向用户的文件追加带标记的区块（见 `scripts/regions.py`），区块之外的内容保持原样。区块正文来自下面的模板，随内容包更新；区块内部被改过时不会被覆盖，由用户选择。
+
+<!-- agents-init:template region/claude-import -->
+```markdown
+@AGENTS.md
+```
+<!-- /agents-init:template -->
+
+<!-- agents-init:template region/agents-contract -->
+```markdown
+## agenthelm 项目契约
+
+本项目由 agenthelm 管理项目生命周期。开始实质工作前：
+
+1. 加载 `project-orchestrator`，读取 `.agents/moe.sakanano.agent-pack/project.json`（Project Profile）。
+2. 项目专属约束见 `AGENT.RULES.md`；Plugin/Skill/MCP 管理交给 `agent-pack`；Opinion 交给 `opinion-manager`。
+3. 本文件其余部分是接管项目前就有的用户规则，与上述契约一并遵循。
+```
+<!-- /agents-init:template -->
+
 ### 流程占位文件
 
 `.agent-doc/plan.md`:
@@ -330,6 +365,18 @@ Agent Plugins 1.0 可移植文件直接位于 `.agents/`：`plugin.json`、`skil
 5. 保持历史 Task/Case 与能力源完整，随后使用 `agent-pack` 盘点。
 6. 只有得到明确授权，才能把个人 Opinion 内容移入私有权威源。
 
+### 接管已有内容的目录
+
+目录里已经有自己的文件时，原则是**控制新增，不追溯历史**：与骨架冲突的旧文件可以长期并存，不是阻塞项；只有用户显式选择，才改动已有文件，且先备份到项目外。
+
+1. `--mode scan`（只读）：列出路径碰撞、目录含义是否相同、`AGENTS.md` / `CLAUDE.md` 的状况，每项给出选项和推荐。
+2. `--mode adopt`（默认预览，`--apply` 才写入）：已有文件原样保留，只补缺失的骨架；保留下来且与模板不同的文件记入决定文件，`check` 不再追问。
+3. 改动已有文件才需要显式选择，并带 `--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` 并标注待交接）。
+4. 目录含义冲突的用 `--case-root` / `--memory-root` 另设位置，已有的工作容器目录用 `--register-root` 只读登记。
+5. 追加到用户文件里的内容是带标记的受管区块（见 `scripts/regions.py`），区块之外不动；区块内部被改过时升级不覆盖，用 `--mode region` 逐个 `--keep` / `--accept`。
+
+历史内容什么时候迁移由用户决定：之后可以用 `--mode adopt` 以外的迁移工具逐步把旧内容整理进标准结构，不影响日常使用。
+
 ### 将既有项目整理为 Case 工作目录
 
 1. 阅读同包 `project-orchestrator/references/case-workspaces.md`，明确 Case 的目标、子工作项与专属材料范围。

package/runtime/plugins/agents-init/skills/agents-init/SKILL.md

@@ -51,7 +51,9 @@ python3 scripts/init_project.py --project /path/to/project \
   --stack python --runtime local --agent-cli codex --apply
 ```
 
-新项目默认在根目录生成启动器 `menu`（人不经过 Agent 打开项目菜单），并在 Profile 写入 `entry` 段；用户想用别的名字时传 `--entry-name <名称>`，不要启动器时传 `--no-entry`。README.md 不存在时新建并写入「怎样使用」，已存在的不改动。
+**项目文件语言**：初始化前先问用户项目里的文件用中文还是英文（用户没有特别要求时取当前对话的语言），用 `--language zh|en` 传入；不传时取当前界面语言（`AGENTHELM_LANG`、系统 locale，最后英文）。它写进 Profile 的 `language`，决定新建 Case 的小节名与默认文字、README 追加的使用说明用哪种语言，随项目同步，与各人的命令行界面语言无关；缺省的旧项目保持中文。`--mode migrate` 缺省保持中文，要改传 `--language en`。
+
+新项目默认在根目录生成启动器 `menu`（人不经过 Agent 打开项目菜单），并在 Profile 写入 `entry` 段；用户想用别的名字时传 `--entry-name <名称>`，不要启动器时传 `--no-entry`。README.md 不存在时新建并写入使用说明小节（中文项目叫「怎样使用」，英文项目叫 How to use），已存在的不改动。
 
 为已初始化的项目补上入口只用 `--mode entry`，它只涉及 Profile 的 `entry` 段、启动器与内容锁；根目录已有同名文件时视为用户的文件，必须由用户选择 `--keep` 或 `--accept`（替换前备份到 `--recovery-dir`）：
 
@@ -69,6 +71,21 @@ python3 scripts/init_project.py --mode migrate --project /path/to/project \
   --replace AGENTS.md --recovery-dir /safe/recovery/example-v6 --apply
 ```
 
+目录里已有自己的文件时（没有 Project Profile）先扫描，再接管。原则是控制新增、不追溯历史：与骨架冲突的旧文件可以长期并存，不是阻塞项；只有用户显式选择，才改动已有文件，且先备份到 `--recovery-dir`（项目外）：
+
+```bash
+python3 scripts/init_project.py --project /path/to/project --mode scan            # 只读：冲突、选项与推荐
+python3 scripts/init_project.py --project /path/to/project --mode adopt \
+  --name example --project-type code --vcs github --stack python --runtime local --agent-cli codex   # 预览
+python3 scripts/init_project.py ... --mode adopt --agents-policy append --claude-policy add-import \
+  --recovery-dir /safe/recovery/example --apply                                    # 改动已有文件须显式选择
+```
+
+- `AGENTS.md` 已有用户内容：`keep`（缺省，不动）、`append`（推荐：原文不动，追加带标记的项目契约区块）、`split`（`--route <章节序号>=<agents|rules|user|opinion|sop>`，未指定的章节留下）、`side-by-side`（原文整体移到 `AGENT.USER.md`）。章节去向建议只来自关键词启发式，逐段判断放在 session 里与用户确认，再把结果交给 `--route`；写入始终经由本命令。
+- `CLAUDE.md` 已有内容但没有导入 `AGENTS.md`：Claude Code 两者并存时只读 `CLAUDE.md`，项目契约不会加载，推荐 `--claude-policy add-import`。
+- `cases/`、`memory/` 被别的内容占用：并存，或 `--case-root` / `--memory-root` 另设位置；已有工作容器用 `--register-root` 只读登记。
+- 追加进用户文件的是受管区块（`scripts/regions.py`）：区块之外不动，区块内部被改过时升级不覆盖，用 `--mode region` 逐个 `--keep <文件>#<ID>` / `--accept <文件>#<ID>`。
+
 已初始化的项目对照最新脚手架用 `--mode check`（只读）；其余模式默认只预览，`--apply` 才写入，已有文件不被覆盖，替换前备份到 `--recovery-dir`：
 
 ```bash
@@ -107,6 +124,10 @@ cases/
 └── .gitkeep
 memory/
 └── .gitkeep
+sops/
+└── .gitkeep
+private/
+└── .gitignore
 docs/
 ├── refs/README.md
 └── drafts/.gitkeep
@@ -114,6 +135,10 @@ docs/
 
 `AGENTS.md` 是项目执行入口；`CLAUDE.md` 与 `AGENT.md` 是短路由文件；初始化产生的 `OPINION.md` 保持为空白配置入口。用户确认后由 `opinion-manager` 写入当前项目；用户内容禁止复制到公开模板、示例、测试或文档。
 
+新项目的 Profile 声明 `privacy.forbidden_default_reads: ["private/"]` 并建立 `private/`（里面的 `.gitignore` 让内容默认不进入 git）：私有信息放在这里，Agent 默认不读，读之前须经用户确认；用到它的 Case 标为 `sensitivity: private`。已有项目没有声明时 `check` 不要求 `private/`，不会多出差异。
+
+新项目的 Profile 带 `sop: {"root": "sops"}`，并建立 `sops/`：用户自己的流程（SOP）放在这里，由 `project-orchestrator` 的 `runtime/sop.py` 管理。已有项目没有 `sop` 段时 `check` 不要求 `sops/`，想启用就在 Profile 加这一段并运行 `fix add-skeleton`。
+
 新项目默认 `work.mode=case-workspace`。`--work-mode legacy` 可保留旧分类；既有项目迁移时未显式选择模式就保持现有模式。Case 数据迁移由 `project-orchestrator` 的已审阅映射工具执行，初始化器只更新骨架与 Profile。
 
 ## 迁移规则