# 临时设计草案：内置 authoring 文档 + `sprout doc`

> 状态：临时讨论稿（非正式 change）
> 日期：2026-04-12 16:55 +08:00

---

## Clarify

### 用户意图

当前 `sprout init` 会把 `SKILL.md` 复制到项目内，导致：

1. 初次初始化后，后续版本无法可靠更新该文档
2. `init` 同时承担“建工作区”和“安装文档副本”两种职责
3. repo 根目录的 `docs/agent-collaboration.md` 已经过时，希望直接删除

### 问题边界

**In scope**
- 重新定义 authoring 文档的分发方式
- 为内置文档提供 CLI 访问入口
- 删除过时的 `docs/agent-collaboration.md`
- 同步 README / user-guide / 测试

**Out of scope**
- 改动 `sprout new` / manifest / runtime 行为
- 引入复杂文档系统或在线文档站点
- 保留项目内 `.sprout/skills/sprout-authoring/SKILL.md` 作为默认初始化产物

### 结论化理解

本次不是“修复 init 覆盖逻辑”，而是**取消把 authoring 指南作为项目内副本分发**，改为**包内内置文档 + CLI 暴露**。

---

## Design

## Problem Statement

`sprout init` 当前通过 `_write_if_missing()` 将 `skill-authoring.md` 写入项目内 `.sprout/skills/sprout-authoring/SKILL.md`，导致官方文档一旦初始化后就无法通过升级 `sprout` 自动更新，同时形成 repo 内多处文档入口，增加漂移风险。

## Approach

将 `sprout-authoring` 从“初始化时复制到项目内的 Skill 文档”改为“安装包内置的 authoring guide”。

新增 `sprout doc` 子命令，作为统一文档访问入口。`init` 仅负责创建工作区与示例命令，不再写入 `.sprout/skills/sprout-authoring/SKILL.md`。

同时删除过时的 `docs/agent-collaboration.md`，将仍然有效的协作说明并入 `sprout/docs/user-guide.md` 与新的 `sprout/docs/command-authoring-guide.md`。

## Key Change

- **CLI Docs: 新增内置文档访问入口**  
  增加 `sprout doc`，允许查看内置文档内容或路径。

- **Scaffold Simplification: init 不再生成本地 Skill 副本**  
  删除 `.sprout/skills/sprout-authoring/SKILL.md` 的初始化写入逻辑。

- **Doc Canonicalization: command authoring 指南迁入 `sprout/docs/`**  
  将现有 `sprout/templates/skill-authoring.md` 改为内置文档文件，由 wheel 一起分发。

- **Doc Boundary: 明确 user-guide 与 command-authoring-guide 的职责边界**  
  `user-guide` 面向使用者，说明如何使用 sprout；`command-authoring-guide` 面向命令包作者与 Agent，说明如何创建和维护 `.sprout/commands/*`。

- **Doc Cleanup: 删除过期入口**  
  删除 `docs/agent-collaboration.md`，避免用户与 Agent 读取旧说明。

## Scope Summary

| Path | Change |
|---|---|
| `sprout/cli.py` | 新增 `doc` 子命令与文档定位/展示逻辑 |
| `sprout/scaffold.py` | 删除 `SKILL.md` 写入与对应提示文案 |
| `sprout/docs/command-authoring-guide.md` | 新增，承接原 skill-authoring 内容，并明确命令包编写边界 |
| `sprout/docs/user-guide.md` | 更新文档入口、CLI 用法，并收敛为“使用手册” |
| `README.md` | 更新 init / docs / Agent 协作说明 |
| `tests/test_init.py` | 删除对本地 `SKILL.md` 存在性的断言 |
| `docs/agent-collaboration.md` | 删除 |
| `sprout/templates/skill-authoring.md` | 删除或停止使用 |

## Interface Sketch

```text
sprout doc list
sprout doc show user-guide
sprout doc show command-authoring-guide
sprout doc path command-authoring-guide
```

### 推荐行为

| Command | Behavior |
|---|---|
| `sprout doc list` | 列出内置文档名称 |
| `sprout doc show <name>` | 将文档内容打印到 stdout |
| `sprout doc path <name>` | 输出内置文档实际路径 |

## Document Positioning

### `user-guide`

**定位**：使用手册（operator guide）  
**目标问题**：用户如何初始化、查看、执行、排查 sprout 命令。

应包含：
- `sprout init/list/doctor/new` 的基本用法
- 输入方式、交互模式、dry-run、冲突策略的运行时行为
- `.sprout/` 结构的高层概览
- FAQ / 排错 / 进一步阅读入口

不应深入：
- `manifest.yaml` 全字段细则
- `inputs/assets/actions` 的完整 authoring 规则
- Agent 在写命令包前的需求对齐流程

### `command-authoring-guide`

**定位**：命令包编写手册（author guide）  
**目标问题**：如何创建、修改、验证 `.sprout/commands/*` 命令包。

应包含：
- `.sprout/config.yaml` 与 `manifest.yaml` 的字段规范
- `inputs/assets/actions` 的 authoring 规则
- 模板变量、asset ref、路径约束
- authoring checklist 与验证命令
- Agent 协作流程：先对齐命令目的 / inputs / assets / conflict，再写文件

不应重复：
- 大段 CLI 快速开始
- 面向普通用户的教程式用法说明

### Boundary Rule

> `user-guide` 讲“怎么使用 sprout”；`command-authoring-guide` 讲“怎么编写 sprout 命令包”。

判断规则：
- 不编辑 `.sprout/commands/*` 也需要知道的内容 → `user-guide`
- 只在创建/维护命令包时才需要的内容 → `command-authoring-guide`

## Behavioral Notes

```text
init:
  create .sprout/
  create config / commands / examples
  do not create .sprout/skills/sprout-authoring/SKILL.md

user wants docs:
  use `sprout doc ...`
  read packaged markdown under sprout/docs/

README:
  short entry only
  point to user-guide and command-authoring-guide
```

## Option Comparison

| Option | Summary | Pros | Cons | Verdict |
|---|---|---|---|---|
| A | 继续写项目内 `SKILL.md`，加 `--refresh-skill` | 改动小 | 仍有副本同步问题；会碰用户本地修改 | 不推荐 |
| B | 内置 command-authoring-guide + `sprout doc` | 单一真源；易升级；结构清晰；与 user-guide 边界更清楚 | Agent 自然发现性略降 | **推荐** |
| C | 保留项目内副本并记录版本号同步 | 折中 | 机制复杂；收益有限 | 不推荐 |

## Migration Path

1. 将 `sprout/templates/skill-authoring.md` 内容迁入 `sprout/docs/command-authoring-guide.md`
2. 在文档中明确 `user-guide` 与 `command-authoring-guide` 的职责边界
3. 在 `cli.py` 中加入 `doc` 子命令
4. 删除 `scaffold.py` 中生成 `SKILL.md` 的逻辑与 note
5. 更新 README / user-guide 的文档入口描述
6. 删除 `docs/agent-collaboration.md`
7. 调整 init 测试与 CLI 测试

## Risks

| Risk | Impact | Mitigation |
|---|---|---|
| Agent 不再从项目目录自然发现 Skill 文件 | 中 | README / user-guide 明确提示 `sprout doc show command-authoring-guide` |
| 用户仍按旧路径提示 Agent | 低 | 错误信息或文档中明确说明旧路径已废弃 |
| `doc show` 输出过长 | 低 | 先做最简单 stdout 输出，必要时后续再扩展分页/export |

## Recommendation

采用 **方案 B：内置 command-authoring-guide + `sprout doc`**，并直接删除 `docs/agent-collaboration.md`。

其中最关键的不是“文档搬家”，而是先明确边界：
- `user-guide` = 面向使用者的 CLI 使用手册
- `command-authoring-guide` = 面向命令包作者与 Agent 的编写手册

这是一次小型、边界清晰的文档分发机制调整，收益明确，且不会影响核心生成逻辑。
