sprout-files 0.2.1

Template-driven file and directory generator for project workflows

sprout CLI (v0.1)

sprout 是一个项目内模板驱动的文件/目录生成 CLI，面向 Agent 协同开发场景。

核心特性

• 发现规则：从当前目录向上查找首个 .sprout/（类似 .git）
• 命令包目录：.sprout/commands/<command>/
• 默认 authoring 格式：YAML（便于注释、示例和值说明）
• 输入模式：默认参数输入；-i/--interactive 才进入交互
• 基础类型：string / number / enum（number 支持可选 min/max）
• 插值语法：{{name}}（仅纯文本替换，不支持逻辑流）
• 冲突策略：fail / overwrite / skip / rename
• init 支持自定义骨架、可选示例命令包，并生成项目内 sprout-authoring Skill 文档
• 运行时兼容 yaml / yml / toml / json 配置与 manifest

快速开始

# 0) 可选：安装 YAML 支持（推荐）
uv add --optional yaml
# 或使用 pip: pip install pyyaml

# 1) 初始化
sprout init --with-examples

# 2) 查看命令
sprout list --all

# 3) 执行命令（默认参数模式，使用 = 连接键值）
sprout new issue name=my-task type=bug

# 4) 交互模式（程序会提示输入缺失的参数）
sprout new issue -i
# 程序提示: name: 
# 你输入: my-task
# 程序提示: type choices=['bug', 'feat', 'refactor'] [default=bug]:
# 你输入: bug (或直接回车使用默认值)

# 5) 预览模式（不实际创建文件）
sprout new issue name=test type=feat --dry-run

命令

sprout init [--profile minimal|docs] [--profile-file ./profile.json] [--with-examples]
sprout list [--all]
sprout doctor
sprout new <command> [key=value ...] [--set key=value] [-i|--interactive] [--conflict fail|overwrite|skip|rename]

.sprout/ 结构

.sprout/
  config.yaml
  commands/
    issue/
      manifest.yaml
      issue.md
  skills/
    sprout-authoring/
      SKILL.md

如何填写 .sprout/config.yaml

# sprout project defaults
version: 1

# Default conflict policy for generated assets.
# Allowed: fail | overwrite | skip | rename
conflict: fail

字段说明：

• version：整数，当前固定为 1
• conflict：项目级默认冲突策略；可选 fail / overwrite / skip / rename

如何填写 manifest.yaml

name: issue
description: Create issue

# Optional per-command conflict override.
# If omitted, sprout uses `.sprout/config.yaml`.
conflict: fail

inputs:
  - name: name
    type: string
    required: true
    description: Issue slug

  - name: type
    type: enum
    enum:
      - bug
      - feat
      - refactor
    default: bug
    description: Issue category

  - name: priority
    type: number
    required: false
    min: 1
    max: 5
    default: 3
    description: Optional priority

assets:
  - type: dir
    path: issues

  - type: file
    path: issues/{{YY}}-{{MM}}-{{DD}}_{{name}}.md
    template: issue.md

字段说明

inputs[*]

• name：必填，且在同一命令内唯一
• type：string / number / enum
• required：可选，默认 true
• description：可选，但建议填写，方便 Agent 理解用途
• default：可选默认值
• enum：当 type: enum 时必填
• min / max：仅 number 类型可用

assets[*]

• type：dir 或 file
• path：项目内相对路径
• template：文件资产引用的模板文件，路径相对当前命令目录
• content：简单文件可直接内联内容；与 template 二选一即可

变量上下文

除了输入变量，内置时间变量：

• YYYY, YY, MM, DD
• hh, mm, ss
• date, time, datetime, timestamp

冲突策略说明

当生成的文件或目录已存在时，sprout 会根据冲突策略处理：

• fail（默认）：报错并停止
• skip：跳过已存在的文件
• overwrite：覆盖已存在的文件
• rename：重命名新文件（添加 _02、_03 等后缀）

目录特殊处理：目录被视为容器而非内容，已存在的目录会自动复用（REUSE），不受冲突策略影响。只有文件冲突才会应用冲突策略。

示例：

# 第一次执行
sprout new issue name=test type=bug
# 输出：
#   + CREATE issues
#   + CREATE issues/26-04-11_test.md

# 第二次执行（目录已存在）
sprout new issue name=another type=feat
# 输出：
#   = REUSE issues              # 目录自动复用
#   + CREATE issues/26-04-11_another.md

# 第三次执行（文件冲突）
sprout new issue name=another type=feat
# 输出：
#   Error: Target already exists: issues/26-04-11_another.md
#   Hint: Use --conflict=skip or --conflict=overwrite

Agent authoring 建议

如果让 Agent 帮你写 .sprout，先让它读取：

• .sprout/skills/sprout-authoring/SKILL.md

然后先对齐：

1. 命令目的
2. 输入字段及类型
3. 输出文件/目录
4. 冲突策略

不要一上来直接让 Agent 写 manifest。

常见问题

• 找不到项目模板根：确认当前目录或父目录存在 .sprout/
• 命令不可用：执行 sprout doctor 检查 invalid/conflict 报告
• YAML 无法读取：安装 PyYAML，或继续使用 TOML / JSON