an-init

name	an-init
description	将现有工作区转换为 AI Native 上下文结构。当用户想要：1) 将现有工作内容纳入 AI Native 格式 2) 为已有材料生成 background/conventions/artifacts 文档 3) 执行 /an-init 命令 4) 让 AI 理解并接管现有工作区 5) 从空模板开始建立通用 AI Native 上下文时触发此技能。**始终使用中文与用户沟通。**

AI Native 上下文初始化

调用此 skill 时若需要使用子代理则默认授权。

将现有工作区（或空工作区）转换为 AI Native 上下文结构。

支持将一个或多个工作单元放入 projects/ 目录，每个子目录视为一个独立工作单元。

前置检查

执行前检查：

1. 检查 projects/ 目录内容

   • 如果已有工作区材料：继续执行
   • 如果为空（仅有 .gitkeep）或不存在：
     • 询问用户是否从空模板开始
     • 若用户确认，则创建一个最小通用上下文结构（不报错停止）
     • 若用户希望先放入材料，提示用户复制材料后重新执行 /an-init

2. 默认授权使用子代理并行处理独立扫描

   我可以用两个子代理并行处理初始化中的独立扫描：
   
   1. 动作探测子代理：探测验证、构建、生成、检查等可执行动作并生成 .agents/recipes.json
   2. 背景扫描子代理：抽取工作区结构、能力/工具栈、对外边界、领域模型等线索
   
   此 skill 默认授权使用子代理并行处理这两项；如果用户明确拒绝、跳过或当前环境不支持子代理，则主代理本地顺序执行同样脚本。
   

   无需再次询问即可启动子代理；用户明确拒绝、跳过或当前环境不支持子代理时，主代理本地顺序执行同样脚本。

---

执行流程

阶段一：工作区分析（静默执行）

扫描 projects/ 目录下的每个子目录，提取客观信息。

子代理并行策略：

执行者	职责	输出
主代理	识别工作单元、提问、合并文档、最终报告	AGENTS.md、background/、conventions/
动作探测子代理	探测验证、构建、检查、生成、导出等可执行动作	.agents/recipes.json 和动作摘要
背景扫描子代理	抽取工作区结构、能力/工具栈、对外边界、领域模型等线索	背景扫描摘要

动作探测子代理任务：

在当前仓库中运行：
node skills/an-recipes/scripts/detect-recipes.mjs --root projects --write .agents/recipes.json

返回：
1. 识别到的工作单元和动作数量
2. 每个工作单元的验证、构建、生成、检查、导出等动作
3. 低置信度或缺失的动作
4. 非代码工作区时的处理结果

背景扫描子代理任务：

在当前仓库中运行：
node skills/an-refresh/scripts/scan-projects.mjs --root projects --artifacts artifacts --format markdown

返回：
1. 工作区结构、文件类型和工具链摘要
2. 对外入口和交互边界线索
3. 数据结构和领域模型线索
4. 已有验证或质量评价报告线索
5. 需要主代理人工判断的待确认项

工作单元列表识别：

• 扫描 projects/ 下的所有一级子目录
• 每个子目录视为一个独立工作单元
• 若 projects/ 为空，则记录为“空工作区”，不停止初始化

工作区类型识别（对每个工作单元分别执行以下检查）：

对每个工作单元子目录：
1. 进入 projects/{工作单元名}/
2. 检查是否存在能表明工作区类型的特征文件
3. 根据文件内容总结工作区类型与能力/工具栈

证据	输出
特征文件、依赖、脚本、配置	能力/工具栈摘要
目录结构和入口文件	工作单元职责摘要
构建、验证、检查配置	可执行动作线索

目录结构分析：

• 扫描每个工作单元生成目录树
• 推断各目录用途

风格分析：

• 命名规范（camelCase/kebab-case/PascalCase）
• 文件组织方式
• 注释/标注风格
• 动作探测子代理和背景扫描子代理返回的结构化摘要

分析原则：

• 所有结论必须基于工作区中的客观事实（文件存在性、依赖列表、脚本名）。
• 禁止根据文件名、目录名推测业务功能、用户意图或未实现的需求。
• 无法确认的信息标记为"待确认"，不得编造。

---

阶段二：自主补全与待确认

分析完成后，AI 应先基于工作区事实、README、配置文件、包信息、注释、已有文档和子代理摘要自主生成背景草稿，不要默认暂停询问用户。

自主补全原则：

• 工作区类型、工具栈、入口、脚本、对外边界线索、交付线索等可由材料事实分析的信息，必须由 AI 自行提取和写入。
• 主题定位、目标用户、外部文档、设计稿等业务语义信息，应先检索仓库内 README、docs、注释、配置命名和已有文档。
• 能从证据中合理归纳的内容可以写为“基于工作区事实推断”，并标注来源；置信度不足时写入“待确认”，不得编造。
• 不要把可由 AI 根据材料事实和领域常识判断的问题转交给用户填表。
• 初始化流程不应因为缺少业务补充而阻塞；缺失信息写入文档的“待确认”项或留空。

仅当缺失信息会影响初始化产物的正确性，且无法通过材料、README、配置或已有文档推断时，才一次性向用户提出必要问题：

我已分析 projects/ 目录，识别到以下工作单元：

{遍历 projects/ 下的子目录，每个输出一行}
- {工作单元名}：{工作区类型} - {主要工具/能力摘要}

以下信息无法从仓库事实中确认，已在文档中标记为“待确认”。如果你愿意，可以补充：

1. 这个工作区整体是做什么的？（一句话描述）
2. 目标用户/读者是谁？

条件待确认项：

条件待确认项只能基于工作区中的可验证事实决定是否附加：

工作区事实	附加问题
检测到对外接口、服务入口或发布格式	是否有接口协议、集成文档或交付规范？
检测到用户界面、可视化或设计相关文件	是否有设计稿或交互规范？

• 禁止 AI 自行判断"是否有后台管理功能"等无法从材料客观验证的事项。
• 如果无法确定是否满足条件，默认写入待确认项而非跳过。

提问是例外路径，不是默认路径。默认路径是 AI 先完成初始化文档，把无法确认的业务信息标记为“待确认”。

---

阶段三：文档生成

根据分析、已有仓库文档和用户已提供的信息生成以下文档。

文档生成原则：文档中的每条信息只能来自两个来源——①用户明确输入 ②工作区客观分析。禁止编造、推测或填充未经验证的信息。无法确认的内容标记为"待确认"或留空。

已有文档处理：如果目标文件已存在（如重复执行 an-init），基于实际情况合并——保留有效内容，补充新增信息，删除过时内容。

AGENTS.md（更新工作区背景）

## 工作区背景

{AI 基于仓库事实归纳的主题描述；若无法确认则写“待确认”}

> **缩写说明**：对话中出现的 "AN" 一般指 AI Native 的缩写。

### 工作区列表

| 工作区 | 类型 | 描述 |
|--------|------|------|
| {projects下的子目录名} | {工作区类型} | {简要说明} |

### 必读文档

| 路径 | 描述 |
|------|------|
| background/ | 上下文背景知识 |
| conventions/ | 上下文约定规范、对话长期规则与优化记录 |

### 能力/工具栈

{从工作区分析得出的能力/工具栈概要}

### 关键链接

| 资源 | 链接 |
|------|------|
| 设计或交互文档 | {仓库内已发现的路径；若无法发现则留空或写“待确认”} |
| 对外契约/交付规范文档 | {仓库内已发现的路径；若无法发现则留空或写“待确认”} |

## 工作流阶段

| 阶段 | 说明 |
|------|------|
| raw-input | 原始输入，原模原样保存用户描述 |
| requirements | 基于 raw-input 生成的结构化需求与验收标准 |
| design | 方案设计，讨论采用什么方案 |
| tech-spec | 执行规范，输出可执行的变更清单 |
| implementation | 按变更清单执行并产出 |
| testing | 基于前面的规范生成验证用例并执行验证 |
| deployment | 交付/归档 |

## AI 行为约束

- 禁止自行脑补未提及的需求、功能或业务逻辑。
- 所有背景知识必须来自工作区材料或用户明确输入。
- 从工作区材料反推的信息要标注来源；无法确认的信息标记为"待确认"。

## 必读规范

| 规范 | 用途 |
|------|------|
| [rules](conventions/rules.md) | 对话过程中的长期记忆感知与沉淀 |
| [memories](conventions/memories/AGENTS.md) | 对话优化记录索引 |

## Skill 路由

当用户描述执行意图（如"我要做一个XXX"、"写XXX"、"分析XXX"、"设计XXX"、"添加XXX"、"修复XXX"、"重构XXX"等）时，
使用 `/an-task`。AI 根据 [flow-policy](conventions/flow-policy.md) 自主判断 L0/L1/L2/L3 流程等级、方案、验证动作和推进顺序。

- L0/L1：可直接实现和验证，完成后总结改动、理由和验证结果。
- L2/L3：创建并维护对应 artifacts，按所需阶段推进并记录决策。
- 不要要求用户在"完整流程 / 快速修复 / 自由对话"中选择。
- 只有需求目标不明确、业务语义必须由用户决定、涉及权限/数据/安全/部署等高风险边界、破坏性操作或外部授权时，才暂停请求确认。

background/product/overview.md

# 产品/主题概述

## 名称

{从工作单元名称或用户输入提取}

## 定位

{AI 基于仓库事实归纳；若无法确认则写“待确认”}

## 目标用户/读者

{AI 基于仓库事实归纳；若无法确认则写“待确认”}

## 工作区关系

{描述各工作区之间的关系}

background/tech/stack.md

# 能力/工具栈

{按工作单元分节}

{遍历 projects/ 下的子目录，为每个工作单元生成一节}

## {工作单元名}

| 工具/能力 | 版本 | 用途 |
|-----------|------|------|
| ... | ... | ... |

## 通用工具链

| 工具 | 用途 |
|------|------|
| ... | ... |

background/AGENTS.md

# background 目录说明

`background/` 存放工作区的稳定背景知识，包括主题定位、领域模型、能力/工具栈、结构决策和交付状态。

## AI 行为

- 需要理解业务或技术背景时，按需读取相关文档。
- 除 `/an-init`、`/an-refresh` 或用户明确要求外，不主动修改本目录。
- 更新时保持增量，不重写人工补充内容。
- 从工作区材料反推的信息要标注来源；无法确认的信息标记为“待确认”。
- 背景文档与 `projects/` 工作区内容冲突时，先以材料事实为准，并在更新摘要中说明冲突。

conventions/structure.md

# 工作区结构规范

## projects/ 目录结构

{扫描 projects/ 生成的目录树}

## 工作单元说明

| 目录 | 工作单元 | 职责 |
|------|----------|------|
| projects/{工作单元A} | {工作单元A名称} | {说明} |
| projects/{工作单元B} | {工作单元B名称} | {说明} |

conventions/style-guide.md

# 风格规范

## 命名规范

{从工作区推断}

## 文件组织

{从工作区推断}

## 标注/注释风格

{从工作区推断}

.agents/recipes.json

由 /an-recipes 或动作探测子代理探测生成，记录验证、构建、生成、检查、导出等可执行动作清单。

conventions/rules.md

# 对话长期记忆规则

## 目标

AI 在任意对话过程中持续感知用户是否正在“纠错、约束、提升”AI 的工作方式。若满足长期沉淀条件，应写入 `conventions/memories/` 中对应功能主题文件；若同名主题已存在，则追加到该文件。

## 写入规则

- `conventions/rules.md` 只保存长期记忆机制的指导规则，不作为具体记忆内容的回写目标。
- `conventions/memories/` 保存具体优化记录、来源、分类、判断依据和后续追加内容。
- memory 文件使用功能性名字，不带日期，例如 `dialog-memory.md`、`git-workflow.md`。
- 写入前先查找同名或同主题 memory 文件；找到则追加，找不到才创建新文件。
- 不要把对话流水直接追加到 `rules.md`；具体记录写入 `memories/`。
- 不写入密钥、凭据、隐私数据、临时路径或不可泛化的上下文。

conventions/memories/AGENTS.md

# memories

| Memory | 描述 |
|--------|------|
| - | - |

artifacts/AGENTS.md

# artifacts 目录说明

`artifacts/` 存放任务产出。每个任务使用独立目录，命名为 `YYYYMMDD__feature-name`。

## 约定结构

artifacts/{YYYYMMDD}__{feature-name}/
├── AGENTS.md
├── raw-input/
├── requirements/
├── design/
├── tech-spec/
├── implementation/
├── testing/
└── deployment/

## AI 行为

- 新任务优先创建独立产出目录，并在根 `AGENTS.md` 的活跃 Artifacts 表中登记。
- 产出目录只存过程文档、决策、报告和临时分析，不存放最终交付物本身（最终交付物应写入 `projects/` 或用户指定的交付位置）。
- 每个产出目录可包含自己的 `AGENTS.md` 作为任务索引。
- 任务完成后，可使用 `/an-archive` 移动到 `artifacts/archive/`。
- 恢复历史任务时先匹配目录名，再读取对应产出内容，避免无谓加载大量文档。

初始化完成后不保留 background/README.md 或 artifacts/README.md。目录级说明统一放入对应的 AGENTS.md，避免 README 与 Codex 双入口漂移。

---

输出格式

单工作区示例：

✅ AI Native 上下文初始化完成！

识别到 1 个工作单元：
- workspace-a：{工作区类型} - {主要能力/工具摘要}

生成文件：
...

多工作区示例：

✅ AI Native 上下文初始化完成！

识别到 2 个工作单元：
- workspace-a：{工作区类型} - {主要能力/工具摘要}
- workspace-b：{工作区类型} - {主要能力/工具摘要}

生成文件：
- AGENTS.md（更新工作区背景）
- background/product/overview.md
- background/tech/stack.md（按工作单元记录能力/工具栈）
- conventions/structure.md（包含各工作单元的目录结构）
- conventions/style-guide.md（包含风格约定）
- conventions/rules.md（对话长期记忆机制）
- conventions/memories/AGENTS.md（对话优化记录索引）
- .agents/recipes.json（可执行动作清单）
- background/AGENTS.md
- artifacts/AGENTS.md

下一步：
1. 在 artifacts/ 中创建你的第一个任务产出目录
2. 参考 background/ 了解上下文背景
3. 规范已写入 conventions/，编辑工作区、目录结构和对话长期记忆时自动生效

空工作区示例：

✅ AI Native 上下文初始化完成！

projects/ 目录为空，已创建最小通用上下文结构。

生成文件：
- AGENTS.md
- background/AGENTS.md
- artifacts/AGENTS.md
- conventions/rules.md
- conventions/memories/AGENTS.md

你可以在 projects/ 中放入工作区材料后重新执行 /an-init，也可以直接开始创建任务产出。

---

阶段四：安装运行期技能与清理

如果未使用动作探测子代理，生成文档后运行动作探测：

node skills/an-recipes/scripts/detect-recipes.mjs --root projects --write .agents/recipes.json

如果未使用背景扫描子代理，需要本地运行背景扫描并将结果纳入文档：

node skills/an-refresh/scripts/scan-projects.mjs --root projects --artifacts artifacts --format markdown

初始化完成后，将运行期技能安装到激活目录：

mkdir -p .agents/skills
mv skills/* .agents/skills/
rmdir skills

安装规则：

• .agents/skills/an-init/ 在模板阶段保留，用于自动激活初始化能力。
• skills/ 暂存目录中的其他技能不在模板阶段激活；只在初始化完成后移动到 .agents/skills/。
• 移动完成后删除空的 skills/ 目录，避免项目中保留模板暂存结构。

删除模板专用文件：

1. 删除 ./README.md（模板说明文档，仅供人类阅读）
2. 删除 background/README.md 和 artifacts/README.md（如存在），目录级说明统一使用 AGENTS.md
3. 删除 projects/.gitkeep（初始化占位文件，如存在）

---

错误处理

情况	处理
projects/ 为空（仅有 .gitkeep）	询问用户是否从空模板开始；若确认则创建最小上下文结构，不报错停止
projects/ 下无子目录	提示用户创建工作单元子目录或选择从空模板开始
无法识别工作区类型	跳过自动识别，询问用户
用户取消	不生成任何文件