@cat-kit/agent-context 1.1.6 → 1.2.1

package/README.md

@@ -15,13 +15,17 @@
 
 ```text
 .agent-context/
-├── plan-{N}/          # 当前计划（最多一个）
-│   ├── plan.md
-│   └── patch-{N}.md
-├── preparing/         # 待执行计划队列
-│   └── plan-{N}/
-└── done/              # 已归档计划
-    └── plan-{N}-{YYYYMMDD}/
+├── .env               # SCOPE 配置（SCOPE=<name>）
+├── .gitignore
+└── {scope}/           # 作用域目录（按协作者隔离）
+    ├── index.md       # 计划索引（自动生成）
+    ├── plan-{N}/      # 当前计划（最多一个）
+    │   ├── plan.md
+    │   └── patch-{N}.md
+    ├── preparing/     # 待执行计划队列
+    │   └── plan-{N}/
+    └── done/          # 已归档计划
+        └── plan-{N}-{YYYYMMDD}/
 ```
 
 生命周期如下：
@@ -82,15 +86,15 @@ agent-context install --tools claude,codex,cursor
 
 下面的 action 不是 CLI 子命令，而是你对 AI 说的话。AI 安装 Skill 后，会把这些话映射到固定协议。
 
-| Action | 何时使用 | 当前状态要求 | 结果 |
-| ------ | -------- | ------------ | ---- |
-| `init` | 项目还没建立好协作约定，或者 `AGENTS.md` 不完整 | 无 | 生成或补全 `AGENTS.md`，新项目可继续进入计划 |
-| `plan` | 新需求需要正式拆分步骤 | 当前没有冲突中的已执行计划 | 创建 `plan.md`，必要时拆成当前计划 + preparing 队列 |
-| `replan` | 计划还没实施，但拆分方式或技术路线要改 | 目标计划必须仍是 `未执行` | 重写计划结构，保留单当前计划模型 |
-| `implement` | 计划已经明确，开始真正落地 | 当前计划存在且状态为 `未执行` | 实施全部步骤，验证通过后把计划改为 `已执行` |
-| `patch` | 已执行计划上出现 Bug、遗漏项或增量需求 | 当前计划必须是 `已执行` | 执行修补，生成 `patch-{N}.md`，更新影响范围 |
-| `rush` | 任务范围很清晰，不想先单独经历 plan 再 implement | 当前不能存在未实施计划 | 直接创建单计划并立刻实施 |
-| `done` | 当前计划已经真正完成，需要收尾归档 | 当前计划必须是 `已执行` | 把当前计划移入 `done/`，必要时晋升下一个 preparing 计划 |
+| Action      | 何时使用                                         | 当前状态要求                  | 结果                                                    |
+| ----------- | ------------------------------------------------ | ----------------------------- | ------------------------------------------------------- |
+| `init`      | 项目还没建立好协作约定，或者 `AGENTS.md` 不完整  | 无                            | 生成或补全 `AGENTS.md`，新项目可继续进入计划            |
+| `plan`      | 新需求需要正式拆分步骤                           | 当前没有冲突中的已执行计划    | 创建 `plan.md`，必要时拆成当前计划 + preparing 队列     |
+| `replan`    | 计划还没实施，但拆分方式或技术路线要改           | 目标计划必须仍是 `未执行`     | 重写计划结构，保留单当前计划模型                        |
+| `implement` | 计划已经明确，开始真正落地                       | 当前计划存在且状态为 `未执行` | 实施全部步骤，验证通过后把计划改为 `已执行`             |
+| `patch`     | 已执行计划上出现 Bug、遗漏项或增量需求           | 当前计划必须是 `已执行`       | 执行修补，生成 `patch-{N}.md`，更新影响范围             |
+| `rush`      | 任务范围很清晰，不想先单独经历 plan 再 implement | 当前不能存在未实施计划        | 直接创建单计划并立刻实施                                |
+| `done`      | 当前计划已经真正完成，需要收尾归档               | 当前计划必须是 `已执行`       | 把当前计划移入 `done/`，必要时晋升下一个 preparing 计划 |
 
 ### `init`
 
@@ -235,10 +239,42 @@ rush 一下，把 README 里的命令表更新为最新版本
 
 `rush` 很适合这种“知道要改什么，也知道验收标准”的任务，但不适合目标模糊的大需求。
 
+## 多人协作
+
+`agent-context` 通过 SCOPE 机制支持多人在同一项目中独立管理计划：
+
+- 每位协作者拥有独立的作用域目录（`{scope}/`），互不干扰
+- SCOPE 名称自动取自 git 配置的 `user.name`
+- 计划编号在各 SCOPE 内独立递增
+- 首次使用时运行 `agent-context init` 初始化作用域
+
+```text
+.agent-context/
+├── alice/             # Alice 的计划
+│   ├── index.md
+│   ├── plan-1/
+│   └── done/
+├── bob/               # Bob 的计划
+│   ├── index.md
+│   ├── plan-3/
+│   └── done/
+└── .env               # 当前用户的 SCOPE
+```
+
 ## CLI 命令参考
 
 CLI 只负责文件安装、同步和状态管理，不负责替代 action。
 
+### `agent-context init`
+
+初始化作用域。首次在项目中使用时运行，会自动检测 git `user.name` 作为 SCOPE 名称，并创建必要的目录结构。
+
+```bash
+agent-context init
+agent-context init --scope alice
+agent-context init --yes
+```
+
 ### `agent-context install`
 
 安装 Skill 文件。
@@ -289,22 +325,33 @@ agent-context done
 agent-context done --yes
 ```
 
+### `agent-context index`
+
+生成或更新当前 SCOPE 的计划索引文件 `.agent-context/{scope}/index.md`。索引按 done、当前计划、preparing 分类，每项为 `- [x/ ] [标题](相对路径)` 格式。
+
+归档计划时（`done`）会自动调用，也可手动运行：
+
+```bash
+agent-context index
+```
+
 ## 通用选项
 
-| 选项 | 适用命令 | 说明 |
-| ---- | -------- | ---- |
-| `--tools <tools>` | `install` / `sync` | 指定目标工具，逗号分隔 |
-| `--check` | `install` / `sync` | 只检查是否有变更，不写文件 |
-| `--yes` | `install` / `done` | 跳过交互确认；`install` 会优先复用已安装工具 |
+| 选项              | 适用命令                    | 说明                                         |
+| ----------------- | --------------------------- | -------------------------------------------- |
+| `--tools <tools>` | `install` / `sync`          | 指定目标工具，逗号分隔                       |
+| `--check`         | `install` / `sync`          | 只检查是否有变更，不写文件                   |
+| `--yes`           | `install` / `init` / `done` | 跳过交互确认；`install` 会优先复用已安装工具 |
+| `--scope <name>`  | `init`                      | 手动指定 SCOPE 名称，不使用 git user.name    |
 
 ## 支持的工具
 
-| 工具 | Skill 目录 |
-| ---- | ---------- |
-| Claude | `.claude/skills/agent-context/` |
-| Codex | `.codex/skills/agent-context/` |
-| Cursor | `.cursor/skills/agent-context/` |
-| Antigravity | `.agent/skills/agent-context/` |
+| 工具           | Skill 目录                      |
+| -------------- | ------------------------------- |
+| Claude         | `.claude/skills/agent-context/` |
+| Codex          | `.codex/skills/agent-context/`  |
+| Cursor         | `.cursor/skills/agent-context/` |
+| Antigravity    | `.agent/skills/agent-context/`  |
 | GitHub Copilot | `.github/skills/agent-context/` |
 
 其中 Codex 会额外生成 `agents/openai.yaml` 元数据文件，其余工具只生成 Skill 内容本身。

package/dist/cli.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{doneCommand as e}from"./commands/done.js";import{installCommand as t}from"./commands/install.js";import{statusCommand as n}from"./commands/status.js";import{syncCommand as r}from"./commands/sync.js";import{validateCommand as i}from"./commands/validate.js";import{readFileSync as a}from"node:fs";import{Command as o}from"commander";const s=JSON.parse(a(new URL(`../package.json`,import.meta.url),`utf8`)),c=typeof s.version==`string`?s.version:`0.0.0`,l=new o;l.name(`agent-context`).description(`Agent Context Skills 安装工具`).version(c),l.command(`install`).description(`安装 ac-workflow Skill`).option(`--tools <tools>`,`指定目标工具，逗号分隔：claude,codex,cursor,antigravity,copilot`).option(`--yes`,`非交互模式：优先复用已安装工具，否则安装全部工具`).option(`--check`,`仅检查是否存在待更新内容，不写入文件`).action(t),l.command(`sync`).description(`同步已安装的 ac-workflow Skill`).option(`--tools <tools>`,`指定目标工具，逗号分隔：claude,codex,cursor,antigravity,copilot`).option(`--check`,`仅检查是否存在待更新内容，不写入文件`).action(r),l.command(`validate`).description(`校验 .agent-context 目录结构`).action(i),l.command(`status`).description(`查看当前 agent-context 状态`).action(n),l.command(`done`).description(`归档当前已执行计划`).option(`--yes`,`跳过确认，直接归档`).action(e),l.parseAsync().catch(e=>{let t=e instanceof Error?e.message:String(e);console.error(`\n❌ ${t}`),process.exitCode=1});export{};
+import{doneCommand as e}from"./commands/done.js";import{indexCommand as t}from"./commands/index-cmd.js";import{initCommand as n}from"./commands/init.js";import{installCommand as r}from"./commands/install.js";import{statusCommand as i}from"./commands/status.js";import{syncCommand as a}from"./commands/sync.js";import{validateCommand as o}from"./commands/validate.js";import{readFileSync as s}from"node:fs";import{Command as c}from"commander";const l=JSON.parse(s(new URL(`../package.json`,import.meta.url),`utf8`)),u=typeof l.version==`string`?l.version:`0.0.0`,d=new c;d.name(`agent-context`).description(`Agent Context Skills 安装工具`).version(u),d.command(`install`).description(`安装 ac-workflow Skill`).option(`--tools <tools>`,`指定目标工具，逗号分隔：claude,codex,cursor,antigravity,copilot`).option(`--yes`,`非交互模式：优先复用已安装工具，否则安装全部工具`).option(`--check`,`仅检查是否存在待更新内容，不写入文件`).action(r),d.command(`sync`).description(`同步已安装的 ac-workflow Skill`).option(`--tools <tools>`,`指定目标工具，逗号分隔：claude,codex,cursor,antigravity,copilot`).option(`--check`,`仅检查是否存在待更新内容，不写入文件`).action(a),d.command(`init`).description(`初始化 SCOPE（从 git user.name 自动获取或手动指定）`).option(`--scope <name>`,`手动指定 SCOPE 名称`).option(`--yes`,`非交互模式：自动覆盖已存在的 SCOPE`).action(n),d.command(`validate`).description(`校验 .agent-context 目录结构`).action(o),d.command(`status`).description(`查看当前 agent-context 状态`).action(i),d.command(`done`).description(`归档当前已执行计划`).option(`--yes`,`跳过确认，直接归档`).action(e),d.command(`index`).description(`生成或更新计划索引文件`).action(t),d.parseAsync().catch(e=>{let t=e instanceof Error?e.message:String(e);console.error(`\n❌ ${t}`),process.exitCode=1});export{};

package/dist/commands/done.js

@@ -1 +1 @@
-import{readRawContext as e}from"../context/reader.js";import{validate as t}from"../context/validator.js";import{archive as n}from"../context/archiver.js";import{basename as r}from"node:path";import{confirm as i}from"@inquirer/prompts";async function a(a){let{snapshot:o,currentPlanCount:s}=await e(process.cwd()),c=t(o,s);if(!c.valid){for(let e of c.errors)console.log(`❌ ${e}`);process.exitCode=1;return}if(!o||!o.currentPlan){console.log(`❌ 无当前计划`),process.exitCode=1;return}if(o.currentPlan.status!==`已执行`){console.log(`❌ 当前计划 plan-${o.currentPlan.number} 尚未执行，无法归档。`),process.exitCode=1;return}if(!a.yes&&!await i({message:`确认归档 plan-${o.currentPlan.number}？`})){console.log(`已取消`);return}let l=await n(o),u=r(l.archivedTo);console.log(`✅ 已归档: plan-${o.currentPlan.number} → done/${u}`),l.promoted!==null&&console.log(`📋 已晋升: plan-${l.promoted} 为新的当前计划`),l.remainingPreparing>0?console.log(`📋 待执行队列剩余 ${l.remainingPreparing} 个计划`):l.promoted===null&&console.log(`ℹ 无更多待执行计划`)}export{a as doneCommand};
+import{readContext as e,readRawContext as t}from"../context/reader.js";import{validate as n}from"../context/validator.js";import{archive as r}from"../context/archiver.js";import{generateIndex as i}from"../context/indexer.js";import{basename as a}from"node:path";import{confirm as o}from"@inquirer/prompts";async function s(s){let{snapshot:c,currentPlanCount:l}=await t(process.cwd()),u=n(c,l);if(!u.valid){for(let e of u.errors)console.log(`❌ ${e}`);process.exitCode=1;return}if(!c||!c.currentPlan){console.log(`❌ 无当前计划`),process.exitCode=1;return}if(c.currentPlan.status!==`已执行`){console.log(`❌ 当前计划 plan-${c.currentPlan.number} 尚未执行，无法归档。`),process.exitCode=1;return}if(!s.yes&&!await o({message:`确认归档 plan-${c.currentPlan.number}？`})){console.log(`已取消`);return}let d=await r(c),f=a(d.archivedTo);console.log(`✅ 已归档: plan-${c.currentPlan.number} → done/${f}`),d.promoted!==null&&console.log(`📋 已晋升: plan-${d.promoted} 为新的当前计划`),d.remainingPreparing>0?console.log(`📋 待执行队列剩余 ${d.remainingPreparing} 个计划`):d.promoted===null&&console.log(`ℹ 无更多待执行计划`);let p=await e(process.cwd());p&&(await i(p),console.log(`📇 已更新索引`))}export{s as doneCommand};

package/dist/commands/index-cmd.js

@@ -0,0 +1 @@
+import{readRawContext as e}from"../context/reader.js";import{validate as t}from"../context/validator.js";import{generateIndex as n}from"../context/indexer.js";import{relative as r}from"node:path";async function i(){let i=process.cwd(),{snapshot:a,currentPlanCount:o}=await e(i),s=t(a,o);if(!s.valid){for(let e of s.errors)console.log(`❌ ${e}`);process.exitCode=1;return}if(!a){console.log(`❌ 未找到 .agent-context 目录`),process.exitCode=1;return}let c=await n(a);console.log(`✅ 已生成索引: ${r(i,c.path)}（${c.entries} 个计划）`)}export{i as indexCommand};

package/dist/commands/init.js

@@ -0,0 +1 @@
+import{initScope as e}from"../context/scope.js";import{existsSync as t}from"node:fs";import{join as n}from"node:path";import{confirm as r}from"@inquirer/prompts";import{mkdir as i,readFile as a}from"node:fs/promises";async function o(o={}){let s=n(process.cwd(),`.agent-context`);await i(s,{recursive:!0});let c=n(s,`.env`);if(t(c)){let e=(await a(c,`utf-8`)).match(/^SCOPE=(.+)$/m)?.[1]?.trim();if(e&&(console.log(`当前 SCOPE: ${e}`),!o.yes&&!await r({message:`是否覆盖当前 SCOPE？`}))){console.log(`已取消`);return}}let l=await e(s,o.scope);console.log(`✅ SCOPE 已设置: ${l}`),console.log(`   目录: .agent-context/${l}/`)}export{o as initCommand};

package/dist/commands/install.js

@@ -1 +1 @@
-import{DEFAULT_TOOL_ORDER as e,detectConfiguredToolIds as t,getToolChoices as n,parseToolIds as r}from"../tools.js";import{runInstall as i}from"../runner.js";import{printCheckResult as a,printRunSummary as o}from"./printer.js";import{checkbox as s}from"@inquirer/prompts";async function c(e={}){let t=process.cwd(),n=await l(t,e),r=e.check??!1,s=await i({cwd:t,tools:n,check:r});if(r){a(s,t),s.changed.length>0&&(process.exitCode=1);return}o(s,t)}async function l(i,a){let o=a.tools;if(!o||o.trim().length===0){let r=t(i);return a.yes?r.length>0?r:[...e]:s({message:`请选择要安装 ac-workflow Skill 的工具（可多选）：`,choices:n().map(e=>({name:e.name,value:e.id,checked:r.includes(e.id)})),required:!0})}return r(o)}export{c as installCommand};
+import{DEFAULT_TOOL_ORDER as e,detectConfiguredToolIds as t,getToolChoices as n,parseToolIds as r}from"../tools.js";import{runInstall as i}from"../runner.js";import{printCheckResult as a,printRunSummary as o}from"./printer.js";import{checkbox as s}from"@inquirer/prompts";async function c(e={}){let t=process.cwd(),n=await l(t,e),r=e.check??!1,s=await i({cwd:t,check:r,...n?{tools:n}:{}});if(r){a(s,t),s.changed.length>0&&(process.exitCode=1);return}o(s,t)}async function l(i,a){let o=a.tools;if(!o||o.trim().length===0){let r=t(i);return a.yes?r.length>0?r:[...e]:s({message:`请选择要安装 ac-workflow Skill 的工具（可多选）：`,choices:n().map(e=>({name:e.name,value:e.id,checked:r.includes(e.id)})),required:!0})}return r(o)}export{c as installCommand};

package/dist/commands/status.js

@@ -1 +1 @@
-import{readRawContext as e}from"../context/reader.js";import{validate as t}from"../context/validator.js";async function n(){let{snapshot:n,currentPlanCount:r}=await e(process.cwd()),i=t(n,r);if(!i.valid){for(let e of i.errors)console.log(`❌ ${e}`);process.exitCode=1;return}if(i.context===null){console.log(`ℹ 无活跃上下文`);return}let a=i.context,o=a.currentPlan?`plan-${a.currentPlan.number} (${a.currentPlan.status})`:`无`,s=a.preparing.length>0?a.preparing.map(e=>`plan-${e.number}`).join(`, `):`无`;console.log(``),console.log(`Agent Context Status`),console.log(`────────────────────`),console.log(`当前计划:  ${o}`),console.log(`待执行队列: ${s}`),console.log(`已归档:    ${a.done.length} 个`)}export{n as statusCommand};
+import{readRawContext as e}from"../context/reader.js";import{validate as t}from"../context/validator.js";async function n(){let{snapshot:n,currentPlanCount:r}=await e(process.cwd()),i=t(n,r);if(!i.valid){for(let e of i.errors)console.log(`❌ ${e}`);process.exitCode=1;return}if(i.context===null){console.log(`ℹ 无活跃上下文`);return}let a=i.context,o=a.currentPlan?`plan-${a.currentPlan.number} (${a.currentPlan.status})`:`无`,s=a.preparing.length>0?a.preparing.map(e=>`plan-${e.number}`).join(`, `):`无`;console.log(``),console.log(`Agent Context Status`),console.log(`────────────────────`),console.log(`当前作用域: ${a.scope}`),console.log(`当前计划:  ${o}`),console.log(`待执行队列: ${s}`),console.log(`已归档:    ${a.done.length} 个`)}export{n as statusCommand};

package/dist/commands/sync.js

@@ -1 +1 @@
-import{detectConfiguredToolIds as e,parseToolIds as t}from"../tools.js";import{runSync as n}from"../runner.js";import{printCheckResult as r,printRunSummary as i}from"./printer.js";async function a(e={}){let t=process.cwd(),a=o(t,e.tools),s=e.check??!1,c=await n({cwd:t,tools:a,check:s});if(s){r(c,t),c.changed.length>0&&(process.exitCode=1);return}i(c,t)}function o(n,r){if(!r||r.trim().length===0){let t=e(n);if(t.length>0)return t;throw Error(`未检测到已安装的 Skill，请先执行 install 或通过 --tools 显式指定工具`)}return t(r)}export{a as syncCommand};
+import{detectConfiguredToolIds as e,parseToolIds as t}from"../tools.js";import{runSync as n}from"../runner.js";import{printCheckResult as r,printRunSummary as i}from"./printer.js";async function a(e={}){let t=process.cwd(),a=o(t,e.tools),s=e.check??!1,c=await n({cwd:t,check:s,...a?{tools:a}:{}});if(s){r(c,t),c.changed.length>0&&(process.exitCode=1);return}i(c,t)}function o(n,r){if(!r||r.trim().length===0){let t=e(n);if(t.length>0)return t;throw Error(`未检测到已安装的 Skill，请先执行 install 或通过 --tools 显式指定工具`)}return t(r)}export{a as syncCommand};

package/dist/commands/validate.js

@@ -1 +1 @@
-import{readRawContext as e}from"../context/reader.js";import{validate as t}from"../context/validator.js";async function n(){let{snapshot:n,currentPlanCount:r}=await e(process.cwd()),i=t(n,r);if(i.context===null){console.log(`⚠️ 无 .agent-context 目录`);return}if(i.valid){console.log(`✅ 校验通过`);let e=i.context,t=e.currentPlan?`plan-${e.currentPlan.number} (${e.currentPlan.status})`:`无`;console.log(`  当前计划: ${t}`),console.log(`  待执行: ${e.preparing.length} 个`),console.log(`  已归档: ${e.done.length} 个`);return}for(let e of i.errors)console.log(`❌ ${e}`);process.exitCode=1}export{n as validateCommand};
+import{readRawContext as e}from"../context/reader.js";import{validate as t}from"../context/validator.js";async function n(){let{snapshot:n,currentPlanCount:r}=await e(process.cwd()),i=t(n,r);if(i.context===null){console.log(`⚠️ 无 .agent-context 目录`);return}if(i.valid){console.log(`✅ 校验通过`);let e=i.context;console.log(`  当前作用域: ${e.scope}`);let t=e.currentPlan?`plan-${e.currentPlan.number} (${e.currentPlan.status})`:`无`;console.log(`  当前计划: ${t}`),console.log(`  待执行: ${e.preparing.length} 个`),console.log(`  已归档: ${e.done.length} 个`);return}for(let e of i.errors)console.log(`❌ ${e}`);process.exitCode=1}export{n as validateCommand};

package/dist/content/actions.js

@@ -4,6 +4,13 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
 
 可附带描述参数，用于补充项目背景、技术栈、特殊约束。
 
+## 前置检查
+
+- 若已存在 \`.agent-context/\`：运行 \`agent-context validate\`，不通过则中止并报告错误。
+- 若 \`.agent-context/\` 不存在：确认这是首次初始化场景；若目录残缺或状态异常，向用户报告，不可继续假设。
+- 新项目缺少关键决策信息时，必须主动提问或确认，不可直接生成 \`AGENTS.md\` 或进入 plan。
+- 遇到阻塞问题应向用户报告，不可静默跳过。
+
 ## 执行步骤
 
 1. **判断项目类型**：检测根目录是否存在有效代码文件和目录结构。
@@ -13,11 +20,16 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
 
 2. **处理 AGENTS.md**：
    - 新项目：
-     1. 通过提问澄清以下要点（已从描述中获取的可跳过）：项目目标与核心功能、技术栈与版本、代码规范与工具链（lint/formatter/测试）、目录结构偏好。
-     2. 生成高质量 \`AGENTS.md\`（须满足下方质量标准，不满足则重新优化直至满足）。
-     3. 继续执行 plan 创建初始计划。
+     1. 先收集或确认以下信息，其中前两类属于**必须主动确认**的决策项，即使描述已部分涵盖也不能整体跳过；可基于描述用确认式问题补问，而不是完全重问。
+        - 必须主动确认：技术栈与版本（语言、运行时、框架、构建/测试工具等）
+        - 必须主动确认：架构偏好（目录结构、分层模式、关键框架或方案选型）
+        - 可基于描述补充：项目目标与核心功能
+        - 可基于描述补充：代码规范与工具链细节（lint、formatter、测试约定等）
+     2. 对高价值决策类问题必须在计划前澄清，例如：是否使用 monorepo、前后端如何拆分、采用哪个框架与测试工具。
+     3. 生成高质量 \`AGENTS.md\`（须满足下方质量标准，不满足则重新优化直至满足）。
+     4. 继续执行 plan 创建初始计划。
    - 旧项目：
-     1. 若不存在 \`AGENTS.md\`：通过提问与代码阅读收集信息后生成。
+     1. 若不存在 \`AGENTS.md\`：优先通过代码与配置读取收集信息；仅对无法可靠判断的内容提问后生成。
      2. 若已存在 \`AGENTS.md\`：按质量标准评估，不足时增补优化。
      3. 默认不创建计划（除非用户明确要求）。
 
@@ -33,7 +45,7 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
 - 大型单体仓库按子包拆分维护本地 \`AGENTS.md\`。
 `}function r(){return`# plan
 
-创建新的执行计划，写入 \`.agent-context/plan-{number}/plan.md\`。按复杂度可拆分为多个计划，维护「单当前计划 + preparing 队列」结构。
+创建新的执行计划，写入 \`.agent-context/{scope}/plan-{number}/plan.md\`。按复杂度可拆分为多个计划，维护「单当前计划 + preparing 队列」结构。
 
 必须附带计划描述。
 
@@ -53,7 +65,7 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
    - 存在显著不同的技术路径需用户决策。
    - 验收标准不明确：无法判断何时算"完成"。
 2. 按复杂度决定单计划或多计划拆分。
-3. 多计划拆分时：最小编号进入 \`.agent-context/\` 作为当前计划，其余进入 \`.agent-context/preparing/\`。单计划直接创建。
+3. 多计划拆分时：最小编号进入 \`.agent-context/{scope}/\` 作为当前计划，其余进入 \`.agent-context/{scope}/preparing/\`。单计划直接创建。
 4. 每个计划创建 \`plan.md\`，遵循下方模板。
 5. **自检**（不通过则修改后重新检查）：
    - 每个步骤可独立执行且有明确完成标准。
@@ -100,9 +112,9 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
 
 ## 作用域
 
-- 默认作用域：\`.agent-context/preparing/\` 中全部未实施计划。
+- 默认作用域：\`.agent-context/{scope}/preparing/\` 中全部未实施计划。
 - 可通过描述指定仅重规划部分计划（如"重规划 plan-3 和 plan-5"）。
-- 当前计划为 \`已执行\` → 禁止重写，仅允许重规划 \`preparing/\` 队列。
+- 当前计划为 \`已执行\` → 禁止重写，仅允许重规划 \`{scope}/preparing/\` 队列。
 - 当前计划为 \`未执行\` 且用户明确要求 → 可纳入重规划范围。
 
 ## 执行步骤
@@ -112,7 +124,7 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
 3. 生成新的拆分方案，保持「单当前计划 + 若干 preparing 计划」结构。
 4. 新增计划编号：全局 max(N)+1 递增分配；未改动计划保持原编号。
 5. 更新目录结构，确保每个新计划的 \`plan.md\` 遵循标准模板。
-`}function a(){return"# implement\n\n实施当前计划 `.agent-context/plan-{number}/plan.md` 中的全部步骤，通过验证循环后将状态更新为「已执行」。\n\n不接受额外描述。\n\n## 前置检查\n\n- 运行 `agent-context validate`，不通过则中止并报告错误。\n- 带描述 → 拒绝执行。\n- 当前计划不存在 → 拒绝执行，提示先创建计划。\n- 当前计划状态为 `已执行` → 拒绝执行，提示使用 patch 修补或运行 `agent-context done` 归档。\n- `## 目标` 或 `## 内容` 为空 → 拒绝执行，提示补充。\n- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。\n- 仅操作当前计划，不直接操作 `preparing/` 中的计划。\n- 遇到阻塞问题应向用户报告，不可静默跳过。\n\n## 执行步骤\n\n1. **读取计划**：读取当前 `plan.md`，理解 `## 目标` 与 `## 内容`。\n2. **实施变更**：依据 `## 内容` 的步骤逐项实施。\n3. **验证循环（WHILE 循环检查）**：\n   - **3.1 检查对照**：对照 `## 内容`，确保每个步骤均已实施完毕，无遗漏。\n   - **3.2 运行验证**：\n     - **IF** (编码任务) **THEN**：必须运行代码检查（Lint/Typecheck）与相关测试命令。\n     - **ELSE IF** (非编码任务，如纯文档修改或项目规划) **THEN**：无需运行外部命令，仅凭逻辑和视觉排版审阅是否符合验收标准。\n   - **3.3 结果判断**：\n     - **IF** (存在未通过的验证报错、未完成项或遗漏项) **THEN**：修复发现的问题，然后 **GOTO 3.1**（重新检查）。\n     - **ELSE IF** (验证全部通过 或 非编码任务验收合格) **THEN**：退出验证循环，即 **GOTO 4** 继续执行。\n4. **更新状态**：将 `plan.md` 的状态行修改为 `> 状态: 已执行`。\n5. **记录范围**：更新 `## 影响范围`，详细记录本次变动的具体文件路径。`.agent-context/` 目录下的文件不计入影响范围。\n"}function o(){return`# patch
+`}function a(){return"# implement\n\n实施当前计划 `.agent-context/{scope}/plan-{number}/plan.md` 中的全部步骤，通过验证循环后将状态更新为「已执行」。\n\n不接受额外描述。\n\n## 前置检查\n\n- 运行 `agent-context validate`，不通过则中止并报告错误。\n- 带描述 → 拒绝执行。\n- 当前计划不存在 → 拒绝执行，提示先创建计划。\n- 当前计划状态为 `已执行` → 拒绝执行，提示使用 patch 修补或运行 `agent-context done` 归档。\n- `## 目标` 或 `## 内容` 为空 → 拒绝执行，提示补充。\n- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。\n- 仅操作当前计划，不直接操作 `preparing/` 中的计划。\n- 遇到阻塞问题应向用户报告，不可静默跳过。\n\n## 执行步骤\n\n1. **读取计划**：读取当前 `plan.md`，理解 `## 目标` 与 `## 内容`。\n2. **实施变更**：依据 `## 内容` 的步骤逐项实施。\n3. **验证循环（WHILE 循环检查）**：\n   - **3.1 检查对照**：对照 `## 内容`，确保每个步骤均已实施完毕，无遗漏。\n   - **3.2 运行验证**：\n     - **IF** (编码任务) **THEN**：必须运行代码检查（Lint/Typecheck）与相关测试命令。\n     - **ELSE IF** (非编码任务，如纯文档修改或项目规划) **THEN**：无需运行外部命令，仅凭逻辑和视觉排版审阅是否符合验收标准。\n   - **3.3 结果判断**：\n     - **IF** (存在未通过的验证报错、未完成项或遗漏项) **THEN**：修复发现的问题，然后 **GOTO 3.1**（重新检查）。\n     - **ELSE IF** (验证全部通过 或 非编码任务验收合格) **THEN**：退出验证循环，即 **GOTO 4** 继续执行。\n4. **更新状态**：将 `plan.md` 的状态行修改为 `> 状态: 已执行`。\n5. **记录范围**：更新 `## 影响范围`，详细记录本次变动的具体文件路径。`.agent-context/` 目录下的文件不计入影响范围。\n"}function o(){return`# patch
 
 基于当前已执行计划创建增量补丁，修复问题或追加变更。
 
@@ -125,13 +137,16 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
 - 当前计划不存在 → 拒绝执行，提示先创建计划。
 - 当前计划状态为 \`未执行\` → 拒绝执行，提示先实施。
 - 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
+- 补丁需求与当前计划完全无关 → 拒绝执行，提示先运行 \`agent-context done\` 归档后再创建新计划。
 - 补丁不改变计划状态，完成后保持 \`已执行\`。
 
 ## 执行步骤
 
 1. 阅读 \`plan.md\` 与已有 \`patch-{number}.md\`，了解上下文与历史，避免重复修复。
 2. 根据描述执行补丁所需的代码变更。
-3. 完成必要验证（测试、类型检查等）。
+3. 完成验证：
+   - **IF** (编码任务) **THEN**：运行相关测试，以及必要的 Lint/Typecheck。
+   - **ELSE IF** (非编码任务，如纯文档修改) **THEN**：仅凭逻辑与排版审阅确认验收通过。
 4. 创建 \`patch-{number}.md\`（编号：扫描当前计划目录已有补丁取 max+1），遵循下方模板。
 5. 回写 \`plan.md\`：
    - \`## 历史补丁\`：追加 \`- patch-{number}: {补丁名称}\`，按编号去重。
@@ -162,6 +177,7 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
 
 - 运行 \`agent-context validate\`，不通过则中止并报告错误。
 - 描述为空 → 拒绝执行。
+- 描述仍存在范围边界、技术路径或验收标准歧义 → 拒绝执行，提示改用 \`plan\`。
 - 存在未归档的已执行当前计划 → 判断新需求与当前计划的关联性：
   - 相关联或用户本意是修补 → 拒绝执行，提示改用 patch。
   - 完全无关 → 拒绝执行，提示先运行 \`agent-context done\` 归档后再创建新计划。
@@ -173,7 +189,7 @@ const e=[`init`,`plan`,`replan`,`implement`,`patch`,`rush`],t={init:n,plan:r,rep
 
 ### 阶段一：plan（差异）
 
-- 跳过「需求澄清」步骤——rush 要求描述本身已足够明确。
+- 仅在描述本身已足够明确时跳过「需求澄清」步骤；否则不得继续 rush。
 - 强制单计划，不拆分，不进入 preparing 队列。
 - 完成 plan 后**不等待用户确认**，直接进入阶段二。
 

package/dist/content/index.js

@@ -6,7 +6,7 @@ import{ACTION_NAMES as e,ACTION_RENDERERS as t}from"./actions.js";function n(n){
 ## 执行纪律
 
 - **协议先行**：匹配到动作后，必须先读取对应 \`actions/*.md\` 协议文件的完整内容，再逐步执行。禁止凭记忆、摘要或猜测跳过协议步骤。
-- **前置检查必做**：所有动作（done 除外）均包含「前置检查」，必须逐条执行，不可跳过。包括运行 \`agent-context validate\`。
+- **前置检查必做**：所有动作（done 除外）均包含「前置检查」，必须逐条执行，不可跳过。凡协议写明需运行 \`agent-context validate\` 时必须执行；\`init\` 在首次初始化且 \`.agent-context/\` 尚不存在时，先确认初始化场景成立，再按协议继续。
 - **禁止直接改动**：在 plan / rush 创建计划之前，不得直接修改项目代码文件。任何代码变更必须在已创建计划（implement）或已创建补丁（patch）的上下文中进行。
 - **顺序执行**：协议步骤必须按编号顺序逐项执行，不可跳步、合并或并行。
 
@@ -29,7 +29,7 @@ import{ACTION_NAMES as e,ACTION_RENDERERS as t}from"./actions.js";function n(n){
 ## 全局约束
 
 - 状态机两态：\`未执行\`、\`已执行\`。
-- 任意时刻最多一个当前计划：\`.agent-context/plan-{number}\`。
+- 任意时刻最多一个当前计划：\`.agent-context/{scope}/plan-{number}\`。
 - 多个当前计划 → 拒绝执行，提示恢复单活跃状态。
 - 计划编号全局递增，不复用。补丁编号在单计划目录内递增，不复用。
 - 影响范围（\`## 影响范围\`）不得包含 \`.agent-context/\` 目录下的文件。
@@ -38,17 +38,20 @@ import{ACTION_NAMES as e,ACTION_RENDERERS as t}from"./actions.js";function n(n){
 
 \`\`\`text
 .agent-context/
-├── plan-{N}/          # 当前计划（最多一个）
-│   ├── plan.md
-│   └── patch-{N}.md
-├── preparing/         # 待执行计划队列
-│   └── plan-{N}/
-└── done/              # 已归档计划
-    └── plan-{N}-{YYYYMMDD}/
+├── .env               # SCOPE 配置（SCOPE=<name>）
+├── .gitignore
+└── {scope}/           # 作用域目录（按协作者隔离）
+    ├── plan-{N}/      # 当前计划（最多一个）
+    │   ├── plan.md
+    │   └── patch-{N}.md
+    ├── preparing/     # 待执行计划队列
+    │   └── plan-{N}/
+    └── done/          # 已归档计划
+        └── plan-{N}-{YYYYMMDD}/
 \`\`\`
 
-编号规则：扫描全部 \`plan-N\` 目录取 \`max(N)+1\`。
-`}function i(e){let t=[`---`,`name: ac-workflow`,`description: 管理 .agent-context 计划生命周期，按 init、plan、replan、implement、patch、rush、done 协议推进任务。`];return e.frontmatterProfile===`claude`&&t.push(`argument-hint: [request]`),e.frontmatterProfile===`copilot`&&t.push(`license: MIT`),t.push(`---`,``),`${t.join(`
+编号规则：在当前 scope 内扫描全部 \`plan-N\` 目录取 \`max(N)+1\`。
+`}function i(e){let t=[`---`,`name: ac-workflow`,`description: 管理 .agent-context 计划生命周期，按 init、plan、replan、implement、patch、rush、done 协议推进任务。`];return e.frontmatterProfile!==`copilot`&&t.push(`argument-hint: [request]`),e.frontmatterProfile===`copilot`&&t.push(`license: MIT`),t.push(`---`,``),`${t.join(`
 `)}\n`}function a(){return`interface:
   display_name: "Agent Context Workflow"
   short_description: "统一管理 .agent-context 计划生命周期"

package/dist/context/indexer.js

@@ -0,0 +1,3 @@
+import{existsSync as e}from"node:fs";import{join as t,relative as n}from"node:path";import{readFile as r,writeFile as i}from"node:fs/promises";const a=/^#\s+(.+)$/m;async function o(e){let r=[];for(let t of e.done){let i=await s(t.dir),a=`./${n(e.root,t.dir)}/plan.md`;r.push(`- [x] [${i}](${a})`)}if(e.currentPlan){let t=await s(e.currentPlan.dir),i=`./${n(e.root,e.currentPlan.dir)}/plan.md`,a=e.currentPlan.status===`已执行`?`x`:` `;r.push(`- [${a}] [${t}](${i})`)}for(let t of e.preparing){let i=await s(t.dir),a=`./${n(e.root,t.dir)}/plan.md`;r.push(`- [ ] [${i}](${a})`)}let a=t(e.root,`index.md`);return await i(a,r.join(`
+`)+`
+`,`utf-8`),{path:a,entries:r.length}}async function s(n){let i=t(n,`plan.md`);return e(i)?(await r(i,`utf-8`)).match(a)?.[1]?.trim()??`plan-${n.split(`/`).pop()??`unknown`}`:`plan-${n.split(`/`).pop()??`unknown`}`}export{o as generateIndex};

package/dist/context/reader.js

@@ -1 +1 @@
-import{existsSync as e}from"node:fs";import{join as t}from"node:path";import{readFile as n,readdir as r}from"node:fs/promises";const i=/^plan-(\d+)$/,a=/^plan-(\d+)(?:-\d{8})?$/,o=/^>\s*状态:\s*(未执行|已执行)$/m,s=/^>?[ \t]*状态[：:].*$/m;async function c(n){let r=t(n,`.agent-context`);if(!e(r))return{snapshot:null,currentPlanCount:0};let i=await u(r),a=await u(t(r,`preparing`)),o=await d(t(r,`done`));return{snapshot:{root:r,currentPlan:i[0]??null,preparing:a,done:o},currentPlanCount:i.length}}async function l(r){let i=t(r,`plan.md`);if(!e(i))return`未执行`;let a=await n(i,`utf-8`),c=a.match(o);return c?c[1]:s.test(a)?`未知`:`未执行`}async function u(n){if(!e(n))return[];let a=await r(n,{withFileTypes:!0}),o=[];for(let e of a){if(!e.isDirectory())continue;let r=e.name.match(i);if(!r?.[1])continue;let a=parseInt(r[1],10),s=t(n,e.name),c=await l(s);o.push({number:a,status:c,dir:s})}return o.sort((e,t)=>e.number-t.number)}async function d(n){if(!e(n))return[];let i=await r(n,{withFileTypes:!0}),o=[];for(let e of i){if(!e.isDirectory())continue;let r=e.name.match(a);r?.[1]&&o.push({number:parseInt(r[1],10),dir:t(n,e.name)})}return o.sort((e,t)=>e.number-t.number)}export{c as readRawContext};
+import{resolveScope as e}from"./scope.js";import{existsSync as t}from"node:fs";import{join as n}from"node:path";import{readFile as r,readdir as i}from"node:fs/promises";const a=/^plan-(\d+)$/,o=/^plan-(\d+)(?:-\d{8})?$/,s=/^>\s*状态:\s*(未执行|已执行)$/m,c=/^>?[ \t]*状态[：:].*$/m;async function l(e){let{snapshot:t}=await u(e);return t}async function u(r){let i=n(r,`.agent-context`);if(!t(i))return{snapshot:null,currentPlanCount:0};let a=await e(i),o=n(i,a),s=await f(o),c=await f(n(o,`preparing`)),l=await p(n(o,`done`));return{snapshot:{root:o,scope:a,currentPlan:s[0]??null,preparing:c,done:l},currentPlanCount:s.length}}async function d(e){let i=n(e,`plan.md`);if(!t(i))return`未执行`;let a=await r(i,`utf-8`),o=a.match(s);return o?o[1]:c.test(a)?`未知`:`未执行`}async function f(e){if(!t(e))return[];let r=await i(e,{withFileTypes:!0}),o=[];for(let t of r){if(!t.isDirectory())continue;let r=t.name.match(a);if(!r?.[1])continue;let i=parseInt(r[1],10),s=n(e,t.name),c=await d(s);o.push({number:i,status:c,dir:s})}return o.sort((e,t)=>e.number-t.number)}async function p(e){if(!t(e))return[];let r=await i(e,{withFileTypes:!0}),a=[];for(let t of r){if(!t.isDirectory())continue;let r=t.name.match(o);r?.[1]&&a.push({number:parseInt(r[1],10),dir:n(e,t.name)})}return a.sort((e,t)=>e.number-t.number)}export{l as readContext,u as readRawContext};

package/dist/context/scope.js

@@ -0,0 +1,5 @@
+import{existsSync as e}from"node:fs";import{join as t}from"node:path";import{mkdir as n,readFile as r,writeFile as i}from"node:fs/promises";import{execSync as a}from"node:child_process";async function o(n){let i=t(n,`.env`);if(e(i)){let e=(await r(i,`utf-8`)).match(/^SCOPE=(.+)$/m);if(e?.[1])return e[1].trim()}return s(n)}async function s(e,r){let o;if(r)o=c(r);else{let e;try{e=a(`git config user.name`,{encoding:`utf-8`}).trim()}catch{throw Error(`未找到 git user.name，请先运行 git config user.name <name>`)}if(!e)throw Error(`未找到 git user.name，请先运行 git config user.name <name>`);o=c(e)}return await i(t(e,`.env`),`SCOPE=${o}\n`,`utf-8`),await l(e),await n(t(e,o),{recursive:!0}),o}function c(e){return e.toLowerCase().replace(/[^a-z0-9]/g,`-`).replace(/^-+|-+$/g,``).replace(/-{2,}/g,`-`)}async function l(n){let a=t(n,`.gitignore`);if(e(a)){let e=await r(a,`utf-8`);e.split(`
+`).some(e=>e.trim()===`.env`)||await i(a,e.trimEnd()+`
+.env
+`,`utf-8`)}else await i(a,`.env
+`,`utf-8`)}export{s as initScope,o as resolveScope};

package/dist/stats.html

@@ -4930,7 +4930,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"cli.d.ts","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/cli.d.ts","uid":"993aa054-1"}]},{"name":"cli.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/cli.ts","uid":"993aa054-3"}]},{"name":"commands/done.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/done.ts","uid":"993aa054-5"}]},{"name":"commands/install.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/install.ts","uid":"993aa054-7"}]},{"name":"commands/printer.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/printer.ts","uid":"993aa054-9"}]},{"name":"commands/status.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/status.ts","uid":"993aa054-11"}]},{"name":"commands/sync.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/sync.ts","uid":"993aa054-13"}]},{"name":"commands/validate.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/commands/validate.ts","uid":"993aa054-15"}]},{"name":"content/actions.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/content/actions.ts","uid":"993aa054-17"}]},{"name":"content/index.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/content/index.ts","uid":"993aa054-19"}]},{"name":"context/archiver.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/context/archiver.ts","uid":"993aa054-21"}]},{"name":"context/reader.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/context/reader.ts","uid":"993aa054-23"}]},{"name":"context/validator.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/context/validator.ts","uid":"993aa054-25"}]},{"name":"runner.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/runner.ts","uid":"993aa054-27"}]},{"name":"tools.js","children":[{"name":"home/whj/codes/cat-kit/packages/agent-context/src/tools.ts","uid":"993aa054-29"}]}],"isRoot":true},"nodeParts":{"993aa054-1":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-0"},"993aa054-3":{"renderedLength":1518,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-2"},"993aa054-5":{"renderedLength":1349,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-4"},"993aa054-7":{"renderedLength":985,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-6"},"993aa054-9":{"renderedLength":909,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-8"},"993aa054-11":{"renderedLength":946,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-10"},"993aa054-13":{"renderedLength":745,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-12"},"993aa054-15":{"renderedLength":763,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-14"},"993aa054-17":{"renderedLength":9909,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-16"},"993aa054-19":{"renderedLength":4006,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-18"},"993aa054-21":{"renderedLength":1012,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-20"},"993aa054-23":{"renderedLength":2081,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-22"},"993aa054-25":{"renderedLength":1905,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-24"},"993aa054-27":{"renderedLength":2037,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-26"},"993aa054-29":{"renderedLength":2174,"gzipLength":0,"brotliLength":0,"metaUid":"993aa054-28"}},"nodeMetas":{"993aa054-0":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/cli.d.ts","moduleParts":{"cli.d.ts":"993aa054-1"},"imported":[],"importedBy":[],"isEntry":true},"993aa054-2":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/cli.ts","moduleParts":{"cli.js":"993aa054-3"},"imported":[{"uid":"993aa054-30"},{"uid":"993aa054-31"},{"uid":"993aa054-4"},{"uid":"993aa054-6"},{"uid":"993aa054-10"},{"uid":"993aa054-12"},{"uid":"993aa054-14"}],"importedBy":[],"isEntry":true},"993aa054-4":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/done.ts","moduleParts":{"commands/done.js":"993aa054-5"},"imported":[{"uid":"993aa054-32"},{"uid":"993aa054-33"},{"uid":"993aa054-34"}],"importedBy":[{"uid":"993aa054-2"}]},"993aa054-6":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/install.ts","moduleParts":{"commands/install.js":"993aa054-7"},"imported":[{"uid":"993aa054-33"},{"uid":"993aa054-26"},{"uid":"993aa054-28"},{"uid":"993aa054-8"}],"importedBy":[{"uid":"993aa054-2"}]},"993aa054-8":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/printer.ts","moduleParts":{"commands/printer.js":"993aa054-9"},"imported":[{"uid":"993aa054-32"}],"importedBy":[{"uid":"993aa054-6"},{"uid":"993aa054-12"}]},"993aa054-10":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/status.ts","moduleParts":{"commands/status.js":"993aa054-11"},"imported":[{"uid":"993aa054-34"}],"importedBy":[{"uid":"993aa054-2"}]},"993aa054-12":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/sync.ts","moduleParts":{"commands/sync.js":"993aa054-13"},"imported":[{"uid":"993aa054-26"},{"uid":"993aa054-28"},{"uid":"993aa054-8"}],"importedBy":[{"uid":"993aa054-2"}]},"993aa054-14":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/commands/validate.ts","moduleParts":{"commands/validate.js":"993aa054-15"},"imported":[{"uid":"993aa054-34"}],"importedBy":[{"uid":"993aa054-2"}]},"993aa054-16":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/content/actions.ts","moduleParts":{"content/actions.js":"993aa054-17"},"imported":[],"importedBy":[{"uid":"993aa054-18"}]},"993aa054-18":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/content/index.ts","moduleParts":{"content/index.js":"993aa054-19"},"imported":[{"uid":"993aa054-16"}],"importedBy":[{"uid":"993aa054-26"}]},"993aa054-20":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/context/archiver.ts","moduleParts":{"context/archiver.js":"993aa054-21"},"imported":[{"uid":"993aa054-35"},{"uid":"993aa054-32"}],"importedBy":[{"uid":"993aa054-34"}]},"993aa054-22":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/context/reader.ts","moduleParts":{"context/reader.js":"993aa054-23"},"imported":[{"uid":"993aa054-30"},{"uid":"993aa054-35"},{"uid":"993aa054-32"}],"importedBy":[{"uid":"993aa054-34"}]},"993aa054-24":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/context/validator.ts","moduleParts":{"context/validator.js":"993aa054-25"},"imported":[{"uid":"993aa054-30"},{"uid":"993aa054-32"}],"importedBy":[{"uid":"993aa054-34"}]},"993aa054-26":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/runner.ts","moduleParts":{"runner.js":"993aa054-27"},"imported":[{"uid":"993aa054-30"},{"uid":"993aa054-35"},{"uid":"993aa054-32"},{"uid":"993aa054-18"},{"uid":"993aa054-28"}],"importedBy":[{"uid":"993aa054-6"},{"uid":"993aa054-12"}]},"993aa054-28":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/tools.ts","moduleParts":{"tools.js":"993aa054-29"},"imported":[{"uid":"993aa054-30"},{"uid":"993aa054-32"}],"importedBy":[{"uid":"993aa054-6"},{"uid":"993aa054-12"},{"uid":"993aa054-26"}]},"993aa054-30":{"id":"node:fs","moduleParts":{},"imported":[],"importedBy":[{"uid":"993aa054-2"},{"uid":"993aa054-26"},{"uid":"993aa054-28"},{"uid":"993aa054-22"},{"uid":"993aa054-24"}]},"993aa054-31":{"id":"commander","moduleParts":{},"imported":[],"importedBy":[{"uid":"993aa054-2"}]},"993aa054-32":{"id":"node:path","moduleParts":{},"imported":[],"importedBy":[{"uid":"993aa054-4"},{"uid":"993aa054-26"},{"uid":"993aa054-28"},{"uid":"993aa054-8"},{"uid":"993aa054-22"},{"uid":"993aa054-24"},{"uid":"993aa054-20"}]},"993aa054-33":{"id":"@inquirer/prompts","moduleParts":{},"imported":[],"importedBy":[{"uid":"993aa054-4"},{"uid":"993aa054-6"}]},"993aa054-34":{"id":"/home/whj/codes/cat-kit/packages/agent-context/src/context/index.ts","moduleParts":{},"imported":[{"uid":"993aa054-22"},{"uid":"993aa054-24"},{"uid":"993aa054-20"}],"importedBy":[{"uid":"993aa054-4"},{"uid":"993aa054-10"},{"uid":"993aa054-14"}]},"993aa054-35":{"id":"node:fs/promises","moduleParts":{},"imported":[],"importedBy":[{"uid":"993aa054-26"},{"uid":"993aa054-22"},{"uid":"993aa054-20"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":false,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"cli.d.ts","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/cli.d.ts","uid":"2800e162-1"}]},{"name":"cli.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/cli.ts","uid":"2800e162-3"}]},{"name":"commands/done.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/commands/done.ts","uid":"2800e162-5"}]},{"name":"commands/index-cmd.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/commands/index-cmd.ts","uid":"2800e162-7"}]},{"name":"commands/init.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/commands/init.ts","uid":"2800e162-9"}]},{"name":"commands/install.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/commands/install.ts","uid":"2800e162-11"}]},{"name":"commands/printer.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/commands/printer.ts","uid":"2800e162-13"}]},{"name":"commands/status.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/commands/status.ts","uid":"2800e162-15"}]},{"name":"commands/sync.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/commands/sync.ts","uid":"2800e162-17"}]},{"name":"commands/validate.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/commands/validate.ts","uid":"2800e162-19"}]},{"name":"content/actions.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/content/actions.ts","uid":"2800e162-21"}]},{"name":"content/index.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/content/index.ts","uid":"2800e162-23"}]},{"name":"context/archiver.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/context/archiver.ts","uid":"2800e162-25"}]},{"name":"context/indexer.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/context/indexer.ts","uid":"2800e162-27"}]},{"name":"context/reader.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/context/reader.ts","uid":"2800e162-29"}]},{"name":"context/scope.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/context/scope.ts","uid":"2800e162-31"}]},{"name":"context/validator.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/context/validator.ts","uid":"2800e162-33"}]},{"name":"runner.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/runner.ts","uid":"2800e162-35"}]},{"name":"tools.js","children":[{"name":"Users/whj/Codes/cat-kit/packages/agent-context/src/tools.ts","uid":"2800e162-37"}]}],"isRoot":true},"nodeParts":{"2800e162-1":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-0"},"2800e162-3":{"renderedLength":1863,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-2"},"2800e162-5":{"renderedLength":1508,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-4"},"2800e162-7":{"renderedLength":629,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-6"},"2800e162-9":{"renderedLength":718,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-8"},"2800e162-11":{"renderedLength":1005,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-10"},"2800e162-13":{"renderedLength":909,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-12"},"2800e162-15":{"renderedLength":993,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-14"},"2800e162-17":{"renderedLength":765,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-16"},"2800e162-19":{"renderedLength":813,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-18"},"2800e162-21":{"renderedLength":11445,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-20"},"2800e162-23":{"renderedLength":4355,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-22"},"2800e162-25":{"renderedLength":1012,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-24"},"2800e162-27":{"renderedLength":1274,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-26"},"2800e162-29":{"renderedLength":2276,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-28"},"2800e162-31":{"renderedLength":1479,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-30"},"2800e162-33":{"renderedLength":1905,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-32"},"2800e162-35":{"renderedLength":2037,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-34"},"2800e162-37":{"renderedLength":2174,"gzipLength":0,"brotliLength":0,"metaUid":"2800e162-36"}},"nodeMetas":{"2800e162-0":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/cli.d.ts","moduleParts":{"cli.d.ts":"2800e162-1"},"imported":[],"importedBy":[],"isEntry":true},"2800e162-2":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/cli.ts","moduleParts":{"cli.js":"2800e162-3"},"imported":[{"uid":"2800e162-38"},{"uid":"2800e162-39"},{"uid":"2800e162-4"},{"uid":"2800e162-6"},{"uid":"2800e162-8"},{"uid":"2800e162-10"},{"uid":"2800e162-14"},{"uid":"2800e162-16"},{"uid":"2800e162-18"}],"importedBy":[],"isEntry":true},"2800e162-4":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/commands/done.ts","moduleParts":{"commands/done.js":"2800e162-5"},"imported":[{"uid":"2800e162-40"},{"uid":"2800e162-41"},{"uid":"2800e162-42"}],"importedBy":[{"uid":"2800e162-2"}]},"2800e162-6":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/commands/index-cmd.ts","moduleParts":{"commands/index-cmd.js":"2800e162-7"},"imported":[{"uid":"2800e162-40"},{"uid":"2800e162-42"}],"importedBy":[{"uid":"2800e162-2"}]},"2800e162-8":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/commands/init.ts","moduleParts":{"commands/init.js":"2800e162-9"},"imported":[{"uid":"2800e162-38"},{"uid":"2800e162-43"},{"uid":"2800e162-40"},{"uid":"2800e162-41"},{"uid":"2800e162-30"}],"importedBy":[{"uid":"2800e162-2"}]},"2800e162-10":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/commands/install.ts","moduleParts":{"commands/install.js":"2800e162-11"},"imported":[{"uid":"2800e162-41"},{"uid":"2800e162-34"},{"uid":"2800e162-36"},{"uid":"2800e162-12"}],"importedBy":[{"uid":"2800e162-2"}]},"2800e162-12":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/commands/printer.ts","moduleParts":{"commands/printer.js":"2800e162-13"},"imported":[{"uid":"2800e162-40"}],"importedBy":[{"uid":"2800e162-10"},{"uid":"2800e162-16"}]},"2800e162-14":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/commands/status.ts","moduleParts":{"commands/status.js":"2800e162-15"},"imported":[{"uid":"2800e162-42"}],"importedBy":[{"uid":"2800e162-2"}]},"2800e162-16":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/commands/sync.ts","moduleParts":{"commands/sync.js":"2800e162-17"},"imported":[{"uid":"2800e162-34"},{"uid":"2800e162-36"},{"uid":"2800e162-12"}],"importedBy":[{"uid":"2800e162-2"}]},"2800e162-18":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/commands/validate.ts","moduleParts":{"commands/validate.js":"2800e162-19"},"imported":[{"uid":"2800e162-42"}],"importedBy":[{"uid":"2800e162-2"}]},"2800e162-20":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/content/actions.ts","moduleParts":{"content/actions.js":"2800e162-21"},"imported":[],"importedBy":[{"uid":"2800e162-22"}]},"2800e162-22":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/content/index.ts","moduleParts":{"content/index.js":"2800e162-23"},"imported":[{"uid":"2800e162-20"}],"importedBy":[{"uid":"2800e162-34"}]},"2800e162-24":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/context/archiver.ts","moduleParts":{"context/archiver.js":"2800e162-25"},"imported":[{"uid":"2800e162-43"},{"uid":"2800e162-40"}],"importedBy":[{"uid":"2800e162-42"}]},"2800e162-26":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/context/indexer.ts","moduleParts":{"context/indexer.js":"2800e162-27"},"imported":[{"uid":"2800e162-38"},{"uid":"2800e162-43"},{"uid":"2800e162-40"}],"importedBy":[{"uid":"2800e162-42"}]},"2800e162-28":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/context/reader.ts","moduleParts":{"context/reader.js":"2800e162-29"},"imported":[{"uid":"2800e162-38"},{"uid":"2800e162-43"},{"uid":"2800e162-40"},{"uid":"2800e162-30"}],"importedBy":[{"uid":"2800e162-42"}]},"2800e162-30":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/context/scope.ts","moduleParts":{"context/scope.js":"2800e162-31"},"imported":[{"uid":"2800e162-44"},{"uid":"2800e162-38"},{"uid":"2800e162-43"},{"uid":"2800e162-40"}],"importedBy":[{"uid":"2800e162-8"},{"uid":"2800e162-42"},{"uid":"2800e162-28"}]},"2800e162-32":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/context/validator.ts","moduleParts":{"context/validator.js":"2800e162-33"},"imported":[{"uid":"2800e162-38"},{"uid":"2800e162-40"}],"importedBy":[{"uid":"2800e162-42"}]},"2800e162-34":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/runner.ts","moduleParts":{"runner.js":"2800e162-35"},"imported":[{"uid":"2800e162-38"},{"uid":"2800e162-43"},{"uid":"2800e162-40"},{"uid":"2800e162-22"},{"uid":"2800e162-36"}],"importedBy":[{"uid":"2800e162-10"},{"uid":"2800e162-16"}]},"2800e162-36":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/tools.ts","moduleParts":{"tools.js":"2800e162-37"},"imported":[{"uid":"2800e162-38"},{"uid":"2800e162-40"}],"importedBy":[{"uid":"2800e162-10"},{"uid":"2800e162-16"},{"uid":"2800e162-34"}]},"2800e162-38":{"id":"node:fs","moduleParts":{},"imported":[],"importedBy":[{"uid":"2800e162-2"},{"uid":"2800e162-8"},{"uid":"2800e162-30"},{"uid":"2800e162-34"},{"uid":"2800e162-36"},{"uid":"2800e162-28"},{"uid":"2800e162-32"},{"uid":"2800e162-26"}]},"2800e162-39":{"id":"commander","moduleParts":{},"imported":[],"importedBy":[{"uid":"2800e162-2"}]},"2800e162-40":{"id":"node:path","moduleParts":{},"imported":[],"importedBy":[{"uid":"2800e162-4"},{"uid":"2800e162-6"},{"uid":"2800e162-8"},{"uid":"2800e162-30"},{"uid":"2800e162-34"},{"uid":"2800e162-36"},{"uid":"2800e162-12"},{"uid":"2800e162-28"},{"uid":"2800e162-32"},{"uid":"2800e162-24"},{"uid":"2800e162-26"}]},"2800e162-41":{"id":"@inquirer/prompts","moduleParts":{},"imported":[],"importedBy":[{"uid":"2800e162-4"},{"uid":"2800e162-8"},{"uid":"2800e162-10"}]},"2800e162-42":{"id":"/Users/whj/Codes/cat-kit/packages/agent-context/src/context/index.ts","moduleParts":{},"imported":[{"uid":"2800e162-28"},{"uid":"2800e162-32"},{"uid":"2800e162-24"},{"uid":"2800e162-26"},{"uid":"2800e162-30"}],"importedBy":[{"uid":"2800e162-4"},{"uid":"2800e162-6"},{"uid":"2800e162-14"},{"uid":"2800e162-18"}]},"2800e162-43":{"id":"node:fs/promises","moduleParts":{},"imported":[],"importedBy":[{"uid":"2800e162-8"},{"uid":"2800e162-30"},{"uid":"2800e162-34"},{"uid":"2800e162-28"},{"uid":"2800e162-24"},{"uid":"2800e162-26"}]},"2800e162-44":{"id":"node:child_process","moduleParts":{},"imported":[],"importedBy":[{"uid":"2800e162-30"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":false,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-kit/agent-context",
-  "version": "1.1.6",
+  "version": "1.2.1",
   "description": "代理上下文管理工具",
   "bin": {
     "agent-context": "./dist/cli.js"
@@ -12,11 +12,11 @@
   ],
   "type": "module",
   "dependencies": {
-    "@inquirer/prompts": "^8.3.0",
+    "@inquirer/prompts": "^8.3.2",
     "commander": "^14.0.3"
   },
   "devDependencies": {
-    "@cat-kit/tsconfig": "1.0.0",
+    "@cat-kit/tsconfig": "2.0.0",
     "@types/node": "^24.12.0"
   }
 }

package/src/cli.ts

@@ -5,6 +5,8 @@ import { readFileSync } from 'node:fs'
 import { Command } from 'commander'
 
 import { doneCommand } from './commands/done.js'
+import { indexCommand } from './commands/index-cmd.js'
+import { initCommand } from './commands/init.js'
 import { installCommand } from './commands/install.js'
 import { statusCommand } from './commands/status.js'
 import { syncCommand } from './commands/sync.js'
@@ -34,6 +36,13 @@ program
   .option('--check', '仅检查是否存在待更新内容，不写入文件')
   .action(syncCommand)
 
+program
+  .command('init')
+  .description('初始化 SCOPE（从 git user.name 自动获取或手动指定）')
+  .option('--scope <name>', '手动指定 SCOPE 名称')
+  .option('--yes', '非交互模式：自动覆盖已存在的 SCOPE')
+  .action(initCommand)
+
 program.command('validate').description('校验 .agent-context 目录结构').action(validateCommand)
 
 program.command('status').description('查看当前 agent-context 状态').action(statusCommand)
@@ -44,6 +53,8 @@ program
   .option('--yes', '跳过确认，直接归档')
   .action(doneCommand)
 
+program.command('index').description('生成或更新计划索引文件').action(indexCommand)
+
 program.parseAsync().catch((error: unknown) => {
   const message = error instanceof Error ? error.message : String(error)
   console.error(`\n❌ ${message}`) // eslint-disable-line no-console

package/src/commands/done.ts

@@ -2,7 +2,7 @@ import { basename } from 'node:path'
 
 import { confirm } from '@inquirer/prompts'
 
-import { archive, readRawContext, validate } from '../context/index.js'
+import { archive, generateIndex, readContext, readRawContext, validate } from '../context/index.js'
 
 export async function doneCommand(options: { yes?: boolean }): Promise<void> {
   const { snapshot, currentPlanCount } = await readRawContext(process.cwd())
@@ -50,4 +50,10 @@ export async function doneCommand(options: { yes?: boolean }): Promise<void> {
   } else if (archiveResult.promoted === null) {
     console.log('ℹ 无更多待执行计划') // eslint-disable-line no-console
   }
+
+  const freshSnapshot = await readContext(process.cwd())
+  if (freshSnapshot) {
+    await generateIndex(freshSnapshot)
+    console.log('📇 已更新索引') // eslint-disable-line no-console
+  }
 }

package/src/commands/index-cmd.ts

@@ -0,0 +1,26 @@
+import { relative } from 'node:path'
+
+import { readRawContext, validate, generateIndex } from '../context/index.js'
+
+export async function indexCommand(): Promise<void> {
+  const cwd = process.cwd()
+  const { snapshot, currentPlanCount } = await readRawContext(cwd)
+  const result = validate(snapshot, currentPlanCount)
+
+  if (!result.valid) {
+    for (const error of result.errors) {
+      console.log(`❌ ${error}`) // eslint-disable-line no-console
+    }
+    process.exitCode = 1
+    return
+  }
+
+  if (!snapshot) {
+    console.log('❌ 未找到 .agent-context 目录') // eslint-disable-line no-console
+    process.exitCode = 1
+    return
+  }
+
+  const indexResult = await generateIndex(snapshot)
+  console.log(`✅ 已生成索引: ${relative(cwd, indexResult.path)}（${indexResult.entries} 个计划）`) // eslint-disable-line no-console
+}

package/src/commands/init.ts

@@ -0,0 +1,43 @@
+import { existsSync } from 'node:fs'
+import { readFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { confirm } from '@inquirer/prompts'
+
+import { initScope } from '../context/scope.js'
+
+export interface InitCommandOptions {
+  scope?: string
+  yes?: boolean
+}
+
+export async function initCommand(options: InitCommandOptions = {}): Promise<void> {
+  const cwd = process.cwd()
+  const acRoot = join(cwd, '.agent-context')
+
+  await mkdir(acRoot, { recursive: true })
+
+  const envPath = join(acRoot, '.env')
+
+  if (existsSync(envPath)) {
+    const content = await readFile(envPath, 'utf-8')
+    const match = content.match(/^SCOPE=(.+)$/m)
+    const existing = match?.[1]?.trim()
+
+    if (existing) {
+      console.log(`当前 SCOPE: ${existing}`) // eslint-disable-line no-console
+
+      if (!options.yes) {
+        const overwrite = await confirm({ message: '是否覆盖当前 SCOPE？' })
+        if (!overwrite) {
+          console.log('已取消') // eslint-disable-line no-console
+          return
+        }
+      }
+    }
+  }
+
+  const scope = await initScope(acRoot, options.scope)
+  console.log(`✅ SCOPE 已设置: ${scope}`) // eslint-disable-line no-console
+  console.log(`   目录: .agent-context/${scope}/`) // eslint-disable-line no-console
+}

package/src/commands/install.ts

@@ -20,7 +20,7 @@ export async function installCommand(options: InstallCommandOptions = {}): Promi
   const cwd = process.cwd()
   const tools = await resolveTools(cwd, options)
   const check = options.check ?? false
-  const result = await runInstall({ cwd, tools, check })
+  const result = await runInstall({ cwd, check, ...(tools ? { tools } : {}) })
 
   if (check) {
     printCheckResult(result, cwd)

package/src/commands/status.ts

@@ -27,6 +27,7 @@ export async function statusCommand(): Promise<void> {
   console.log('')
   console.log('Agent Context Status')
   console.log('────────────────────')
+  console.log(`当前作用域: ${ctx.scope}`)
   console.log(`当前计划:  ${current}`)
   console.log(`待执行队列: ${preparing}`)
   console.log(`已归档:    ${ctx.done.length} 个`)

package/src/commands/sync.ts

@@ -12,7 +12,7 @@ export async function syncCommand(options: SyncCommandOptions = {}): Promise<voi
   const cwd = process.cwd()
   const tools = resolveTools(cwd, options.tools)
   const check = options.check ?? false
-  const result = await runSync({ cwd, tools, check })
+  const result = await runSync({ cwd, check, ...(tools ? { tools } : {}) })
 
   if (check) {
     printCheckResult(result, cwd)

package/src/commands/validate.ts

@@ -12,6 +12,7 @@ export async function validateCommand(): Promise<void> {
   if (result.valid) {
     console.log('✅ 校验通过')
     const ctx = result.context
+    console.log(`  当前作用域: ${ctx.scope}`)
     const current = ctx.currentPlan
       ? `plan-${ctx.currentPlan.number} (${ctx.currentPlan.status})`
       : '无'

package/src/content/actions.ts

@@ -17,6 +17,13 @@ function renderInit(): string {
 
 可附带描述参数，用于补充项目背景、技术栈、特殊约束。
 
+## 前置检查
+
+- 若已存在 \`.agent-context/\`：运行 \`agent-context validate\`，不通过则中止并报告错误。
+- 若 \`.agent-context/\` 不存在：确认这是首次初始化场景；若目录残缺或状态异常，向用户报告，不可继续假设。
+- 新项目缺少关键决策信息时，必须主动提问或确认，不可直接生成 \`AGENTS.md\` 或进入 plan。
+- 遇到阻塞问题应向用户报告，不可静默跳过。
+
 ## 执行步骤
 
 1. **判断项目类型**：检测根目录是否存在有效代码文件和目录结构。
@@ -26,11 +33,16 @@ function renderInit(): string {
 
 2. **处理 AGENTS.md**：
    - 新项目：
-     1. 通过提问澄清以下要点（已从描述中获取的可跳过）：项目目标与核心功能、技术栈与版本、代码规范与工具链（lint/formatter/测试）、目录结构偏好。
-     2. 生成高质量 \`AGENTS.md\`（须满足下方质量标准，不满足则重新优化直至满足）。
-     3. 继续执行 plan 创建初始计划。
+     1. 先收集或确认以下信息，其中前两类属于**必须主动确认**的决策项，即使描述已部分涵盖也不能整体跳过；可基于描述用确认式问题补问，而不是完全重问。
+        - 必须主动确认：技术栈与版本（语言、运行时、框架、构建/测试工具等）
+        - 必须主动确认：架构偏好（目录结构、分层模式、关键框架或方案选型）
+        - 可基于描述补充：项目目标与核心功能
+        - 可基于描述补充：代码规范与工具链细节（lint、formatter、测试约定等）
+     2. 对高价值决策类问题必须在计划前澄清，例如：是否使用 monorepo、前后端如何拆分、采用哪个框架与测试工具。
+     3. 生成高质量 \`AGENTS.md\`（须满足下方质量标准，不满足则重新优化直至满足）。
+     4. 继续执行 plan 创建初始计划。
    - 旧项目：
-     1. 若不存在 \`AGENTS.md\`：通过提问与代码阅读收集信息后生成。
+     1. 若不存在 \`AGENTS.md\`：优先通过代码与配置读取收集信息；仅对无法可靠判断的内容提问后生成。
      2. 若已存在 \`AGENTS.md\`：按质量标准评估，不足时增补优化。
      3. 默认不创建计划（除非用户明确要求）。
 
@@ -50,7 +62,7 @@ function renderInit(): string {
 function renderPlan(): string {
   return `# plan
 
-创建新的执行计划，写入 \`.agent-context/plan-{number}/plan.md\`。按复杂度可拆分为多个计划，维护「单当前计划 + preparing 队列」结构。
+创建新的执行计划，写入 \`.agent-context/{scope}/plan-{number}/plan.md\`。按复杂度可拆分为多个计划，维护「单当前计划 + preparing 队列」结构。
 
 必须附带计划描述。
 
@@ -70,7 +82,7 @@ function renderPlan(): string {
    - 存在显著不同的技术路径需用户决策。
    - 验收标准不明确：无法判断何时算"完成"。
 2. 按复杂度决定单计划或多计划拆分。
-3. 多计划拆分时：最小编号进入 \`.agent-context/\` 作为当前计划，其余进入 \`.agent-context/preparing/\`。单计划直接创建。
+3. 多计划拆分时：最小编号进入 \`.agent-context/{scope}/\` 作为当前计划，其余进入 \`.agent-context/{scope}/preparing/\`。单计划直接创建。
 4. 每个计划创建 \`plan.md\`，遵循下方模板。
 5. **自检**（不通过则修改后重新检查）：
    - 每个步骤可独立执行且有明确完成标准。
@@ -121,9 +133,9 @@ function renderReplan(): string {
 
 ## 作用域
 
-- 默认作用域：\`.agent-context/preparing/\` 中全部未实施计划。
+- 默认作用域：\`.agent-context/{scope}/preparing/\` 中全部未实施计划。
 - 可通过描述指定仅重规划部分计划（如"重规划 plan-3 和 plan-5"）。
-- 当前计划为 \`已执行\` → 禁止重写，仅允许重规划 \`preparing/\` 队列。
+- 当前计划为 \`已执行\` → 禁止重写，仅允许重规划 \`{scope}/preparing/\` 队列。
 - 当前计划为 \`未执行\` 且用户明确要求 → 可纳入重规划范围。
 
 ## 执行步骤
@@ -139,7 +151,7 @@ function renderReplan(): string {
 function renderImplement(): string {
   return `# implement
 
-实施当前计划 \`.agent-context/plan-{number}/plan.md\` 中的全部步骤，通过验证循环后将状态更新为「已执行」。
+实施当前计划 \`.agent-context/{scope}/plan-{number}/plan.md\` 中的全部步骤，通过验证循环后将状态更新为「已执行」。
 
 不接受额外描述。
 
@@ -185,13 +197,16 @@ function renderPatch(): string {
 - 当前计划不存在 → 拒绝执行，提示先创建计划。
 - 当前计划状态为 \`未执行\` → 拒绝执行，提示先实施。
 - 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
+- 补丁需求与当前计划完全无关 → 拒绝执行，提示先运行 \`agent-context done\` 归档后再创建新计划。
 - 补丁不改变计划状态，完成后保持 \`已执行\`。
 
 ## 执行步骤
 
 1. 阅读 \`plan.md\` 与已有 \`patch-{number}.md\`，了解上下文与历史，避免重复修复。
 2. 根据描述执行补丁所需的代码变更。
-3. 完成必要验证（测试、类型检查等）。
+3. 完成验证：
+   - **IF** (编码任务) **THEN**：运行相关测试，以及必要的 Lint/Typecheck。
+   - **ELSE IF** (非编码任务，如纯文档修改) **THEN**：仅凭逻辑与排版审阅确认验收通过。
 4. 创建 \`patch-{number}.md\`（编号：扫描当前计划目录已有补丁取 max+1），遵循下方模板。
 5. 回写 \`plan.md\`：
    - \`## 历史补丁\`：追加 \`- patch-{number}: {补丁名称}\`，按编号去重。
@@ -226,6 +241,7 @@ function renderRush(): string {
 
 - 运行 \`agent-context validate\`，不通过则中止并报告错误。
 - 描述为空 → 拒绝执行。
+- 描述仍存在范围边界、技术路径或验收标准歧义 → 拒绝执行，提示改用 \`plan\`。
 - 存在未归档的已执行当前计划 → 判断新需求与当前计划的关联性：
   - 相关联或用户本意是修补 → 拒绝执行，提示改用 patch。
   - 完全无关 → 拒绝执行，提示先运行 \`agent-context done\` 归档后再创建新计划。
@@ -237,7 +253,7 @@ function renderRush(): string {
 
 ### 阶段一：plan（差异）
 
-- 跳过「需求澄清」步骤——rush 要求描述本身已足够明确。
+- 仅在描述本身已足够明确时跳过「需求澄清」步骤；否则不得继续 rush。
 - 强制单计划，不拆分，不进入 preparing 队列。
 - 完成 plan 后**不等待用户确认**，直接进入阶段二。
 

package/src/content/index.ts

@@ -32,7 +32,7 @@ function renderNavigator(target: ToolTarget): string {
 ## 执行纪律
 
 - **协议先行**：匹配到动作后，必须先读取对应 \`actions/*.md\` 协议文件的完整内容，再逐步执行。禁止凭记忆、摘要或猜测跳过协议步骤。
-- **前置检查必做**：所有动作（done 除外）均包含「前置检查」，必须逐条执行，不可跳过。包括运行 \`agent-context validate\`。
+- **前置检查必做**：所有动作（done 除外）均包含「前置检查」，必须逐条执行，不可跳过。凡协议写明需运行 \`agent-context validate\` 时必须执行；\`init\` 在首次初始化且 \`.agent-context/\` 尚不存在时，先确认初始化场景成立，再按协议继续。
 - **禁止直接改动**：在 plan / rush 创建计划之前，不得直接修改项目代码文件。任何代码变更必须在已创建计划（implement）或已创建补丁（patch）的上下文中进行。
 - **顺序执行**：协议步骤必须按编号顺序逐项执行，不可跳步、合并或并行。
 
@@ -55,7 +55,7 @@ function renderNavigator(target: ToolTarget): string {
 ## 全局约束
 
 - 状态机两态：\`未执行\`、\`已执行\`。
-- 任意时刻最多一个当前计划：\`.agent-context/plan-{number}\`。
+- 任意时刻最多一个当前计划：\`.agent-context/{scope}/plan-{number}\`。
 - 多个当前计划 → 拒绝执行，提示恢复单活跃状态。
 - 计划编号全局递增，不复用。补丁编号在单计划目录内递增，不复用。
 - 影响范围（\`## 影响范围\`）不得包含 \`.agent-context/\` 目录下的文件。
@@ -64,16 +64,19 @@ function renderNavigator(target: ToolTarget): string {
 
 \`\`\`text
 .agent-context/
-├── plan-{N}/          # 当前计划（最多一个）
-│   ├── plan.md
-│   └── patch-{N}.md
-├── preparing/         # 待执行计划队列
-│   └── plan-{N}/
-└── done/              # 已归档计划
-    └── plan-{N}-{YYYYMMDD}/
+├── .env               # SCOPE 配置（SCOPE=<name>）
+├── .gitignore
+└── {scope}/           # 作用域目录（按协作者隔离）
+    ├── plan-{N}/      # 当前计划（最多一个）
+    │   ├── plan.md
+    │   └── patch-{N}.md
+    ├── preparing/     # 待执行计划队列
+    │   └── plan-{N}/
+    └── done/          # 已归档计划
+        └── plan-{N}-{YYYYMMDD}/
 \`\`\`
 
-编号规则：扫描全部 \`plan-N\` 目录取 \`max(N)+1\`。
+编号规则：在当前 scope 内扫描全部 \`plan-N\` 目录取 \`max(N)+1\`。
 `
 }
 
@@ -82,7 +85,7 @@ function renderNavigator(target: ToolTarget): string {
 function renderFrontmatter(target: ToolTarget): string {
   const lines = ['---', `name: ${SKILL_NAME}`, `description: ${SKILL_DESCRIPTION}`]
 
-  if (target.frontmatterProfile === 'claude') {
+  if (target.frontmatterProfile !== 'copilot') {
     lines.push('argument-hint: [request]')
   }
 

package/src/context/index.ts

@@ -1,3 +1,5 @@
 export { readContext, readRawContext, readPlanStatus } from './reader.js'
 export { validate } from './validator.js'
 export { archive } from './archiver.js'
+export { generateIndex } from './indexer.js'
+export { resolveScope, initScope, normalizeScope } from './scope.js'

package/src/context/indexer.ts

@@ -0,0 +1,52 @@
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+import type { ContextSnapshot } from '../types.js'
+
+const H1_RE = /^#\s+(.+)$/m
+
+export interface IndexResult {
+  path: string
+  entries: number
+}
+
+export async function generateIndex(context: ContextSnapshot): Promise<IndexResult> {
+  const lines: string[] = []
+
+  for (const plan of context.done) {
+    const title = await extractTitle(plan.dir)
+    const rel = `./${relative(context.root, plan.dir)}/plan.md`
+    lines.push(`- [x] [${title}](${rel})`)
+  }
+
+  if (context.currentPlan) {
+    const title = await extractTitle(context.currentPlan.dir)
+    const rel = `./${relative(context.root, context.currentPlan.dir)}/plan.md`
+    const check = context.currentPlan.status === '已执行' ? 'x' : ' '
+    lines.push(`- [${check}] [${title}](${rel})`)
+  }
+
+  for (const plan of context.preparing) {
+    const title = await extractTitle(plan.dir)
+    const rel = `./${relative(context.root, plan.dir)}/plan.md`
+    lines.push(`- [ ] [${title}](${rel})`)
+  }
+
+  const indexPath = join(context.root, 'index.md')
+  await writeFile(indexPath, lines.join('\n') + '\n', 'utf-8')
+
+  return { path: indexPath, entries: lines.length }
+}
+
+async function extractTitle(planDir: string): Promise<string> {
+  const planFile = join(planDir, 'plan.md')
+
+  if (!existsSync(planFile)) {
+    return `plan-${planDir.split('/').pop() ?? 'unknown'}`
+  }
+
+  const content = await readFile(planFile, 'utf-8')
+  const match = content.match(H1_RE)
+  return match?.[1]?.trim() ?? `plan-${planDir.split('/').pop() ?? 'unknown'}`
+}

package/src/context/reader.ts

@@ -3,6 +3,7 @@ import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import type { ContextSnapshot, PlanInfo, PlanStatus } from '../types.js'
+import { resolveScope } from './scope.js'
 
 const PLAN_DIR_RE = /^plan-(\d+)$/
 const DONE_DIR_RE = /^plan-(\d+)(?:-\d{8})?$/
@@ -19,17 +20,26 @@ export async function readContext(cwd: string): Promise<ContextSnapshot | null>
 export async function readRawContext(
   cwd: string
 ): Promise<{ snapshot: ContextSnapshot | null; currentPlanCount: number }> {
-  const root = join(cwd, '.agent-context')
+  const acRoot = join(cwd, '.agent-context')
 
-  if (!existsSync(root)) {
+  if (!existsSync(acRoot)) {
     return { snapshot: null, currentPlanCount: 0 }
   }
 
+  const scope = await resolveScope(acRoot)
+  const root = join(acRoot, scope)
+
   const currentPlans = await readPlanDirs(root)
   const preparing = await readPlanDirs(join(root, 'preparing'))
   const done = await readDonePlans(join(root, 'done'))
 
-  const snapshot: ContextSnapshot = { root, currentPlan: currentPlans[0] ?? null, preparing, done }
+  const snapshot: ContextSnapshot = {
+    root,
+    scope,
+    currentPlan: currentPlans[0] ?? null,
+    preparing,
+    done
+  }
 
   return { snapshot, currentPlanCount: currentPlans.length }
 }

package/src/context/scope.ts

@@ -0,0 +1,70 @@
+import { execSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export async function resolveScope(acRoot: string): Promise<string> {
+  const envPath = join(acRoot, '.env')
+
+  if (existsSync(envPath)) {
+    const content = await readFile(envPath, 'utf-8')
+    const match = content.match(/^SCOPE=(.+)$/m)
+    if (match?.[1]) {
+      return match[1].trim()
+    }
+  }
+
+  return initScope(acRoot)
+}
+
+export async function initScope(acRoot: string, manualScope?: string): Promise<string> {
+  let scope: string
+
+  if (manualScope) {
+    scope = normalizeScope(manualScope)
+  } else {
+    let userName: string
+    try {
+      userName = execSync('git config user.name', { encoding: 'utf-8' }).trim()
+    } catch {
+      throw new Error('未找到 git user.name，请先运行 git config user.name <name>')
+    }
+
+    if (!userName) {
+      throw new Error('未找到 git user.name，请先运行 git config user.name <name>')
+    }
+
+    scope = normalizeScope(userName)
+  }
+
+  const envPath = join(acRoot, '.env')
+  await writeFile(envPath, `SCOPE=${scope}\n`, 'utf-8')
+
+  await ensureGitignoreHasEnv(acRoot)
+
+  const scopeDir = join(acRoot, scope)
+  await mkdir(scopeDir, { recursive: true })
+
+  return scope
+}
+
+export function normalizeScope(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-')
+}
+
+async function ensureGitignoreHasEnv(acRoot: string): Promise<void> {
+  const gitignorePath = join(acRoot, '.gitignore')
+
+  if (existsSync(gitignorePath)) {
+    const content = await readFile(gitignorePath, 'utf-8')
+    if (!content.split('\n').some((line) => line.trim() === '.env')) {
+      await writeFile(gitignorePath, content.trimEnd() + '\n.env\n', 'utf-8')
+    }
+  } else {
+    await writeFile(gitignorePath, '.env\n', 'utf-8')
+  }
+}

package/src/types.ts

@@ -50,6 +50,7 @@ export interface PlanInfo {
 
 export interface ContextSnapshot {
   root: string
+  scope: string
   currentPlan: PlanInfo | null
   preparing: PlanInfo[]
   done: Pick<PlanInfo, 'number' | 'dir'>[]