sdlc-cli

SDLC 最小集 CLI —— 本地即真源的中间产物仓库与工作区装配。

sdlc-cli 把软件开发生命周期(SDLC)的中间产物(需求、技术方案、测试用例/记录)以结构化文件 + git 提交的形式沉淀在本地,并按一次开发任务把 中间产物 + 代码仓 worktree + 知识库 装配进一个工作区。CLI 只负责定位、校验、装配;自然语言交互由配套的 assembling-workspace skill 承担,通过 needs 协议回报缺失项、由 skill 补齐后重调。

特性

• 中间产物仓(context-repo):Jira / PRD 的 manifest.yaml、tech-spec/、prd/、test-cases/、test-runs/ 骨架,可版本化、可事务提交。
• 工作区装配:一条命令把 context-repo、代码仓 worktree、知识库装进 ~/sdlc-workspaces/<id>/。
• 两种装配入口:--jira(dev 视图,装代码仓 + 建 Jira 骨架)与 --prd(product 视图,建 PRD 骨架)。
• 多知识库:knowledge_base 支持单个或数组,全部克隆。
• 工作区引导文件:装配时首次生成 AGENTS.md 真源与 CLAUDE.md import stub,refresh 不覆盖手改内容。
• 本地/远程代码仓:repos.<id>.local 配本地路径则直接用(不拉 mirror);远程仓 clone 到全局共享 mirror ~/sdlc-workspaces/.mirrors/<name>,复用时自动 fetch 刷新。
• worktree 基分支:默认基于 origin/main,回退 origin/master,皆无则报错;可用 --repo-base <逻辑id>=<分支> 按仓指定从哪个远程分支拉。
• needs 协议:装配缺信息时不做破坏性动作,一次性回报所有 *_MISSING,便于上层对话补齐。

环境要求

• Node.js ≥ 20
• git

安装

# 从 registry 安装(全局)
npm i -g @g7e6-sdlc/sdlc-cli

# 或用 npx 直接跑
npx @g7e6-sdlc/sdlc-cli --help

安装时 postinstall 会调用 sdlc-cli install:在 ~/.sdlc/config.yaml 缺失时写入默认配置模板(已存在则不覆盖),并把随包 skills/ 注册到 ~/.claude/skills 与 ~/.agents/skills。

若通过 npx @g7e6-sdlc/sdlc-cli install 运行(检测到从 npx 临时目录执行),install 还会自动 npm i -g @g7e6-sdlc/sdlc-cli(安装与当前相同的版本),让终端直接拥有全局 sdlc-cli 命令。已全局安装则跳过;在全局安装的 postinstall / 本地 pnpm install 场景下不会触发(避免递归与误装)。自安装失败仅告警、不影响退出码,可按提示手动 npm i -g @g7e6-sdlc/sdlc-cli。pnpm dlx / yarn dlx 不在自动识别范围,请手动全局安装。也可手动初始化:

sdlc-cli install          # 确保配置存在,并注册随包 skills
# 或
sdlc-cli config init      # 仅确保配置模板存在

快速开始

# 1) 初始化全局配置
sdlc-cli install

# 2) 登记代码仓逻辑地址(顶层全局,与产品无关)
sdlc-cli config set repos.backend.remote [email protected]:checkout/backend.git
#   本地已有 clone 时可直接用本地路径(不拉 mirror):
sdlc-cli config set repos.backend.local  ~/code/backend

# 3)(可选)登记产品预设,便于按 Jira 前缀自动带出地址
sdlc-cli config set products.checkout.context_repo   [email protected]:sdlc/checkout-context.git
sdlc-cli config set products.checkout.knowledge_base '[[email protected]:kb/checkout-kb.git]'
sdlc-cli config set products.checkout.jira_prefixes  '[PROJ, CHK]'
sdlc-cli config set products.checkout.keywords       '[结账, 支付, checkout]'
sdlc-cli config set products.checkout.epic           'CHK-100'
sdlc-cli config set products.checkout.repos          '[backend, frontend]'

# 4) 装配一个 dev 工作区(围绕 Jira)
sdlc-cli ws create --jira PROJ-123 \
  --epic EPIC-1 --title "登录 SSO 后端" \
  --repo backend --prd-ref PRD-login

# 装配结果:~/sdlc-workspaces/PROJ-123/
#   context-repo/   —— 中间产物(已建 Jira 骨架并提交)
#   repos/backend/  —— 代码仓 worktree(分支 feature/PROJ-123-<时间戳>)
#   knowledge/      —— 知识库
#   AGENTS.md       —— 工作区操作引导(首次生成,refresh 不覆盖)

若装配缺少必需信息(如 context-repo / 知识库地址),命令不会做破坏性动作,而是以 needs-input 返回所有缺失项(如 CONTEXT_REPO_MISSING、KNOWLEDGE_MISSING),补齐后重跑即可。dev 视图的 --prd-ref 为必填:缺省时待 context-repo 就绪后报 PRD_REF_REQUIRED(回带 context-repo 已有 PRD 候选 candidates[],供 skill 语义推导/选择),补齐后重跑;--epic / --title 为非必填:缺省不报 need、不阻断装配(epic 缺省不写 manifest,title 缺省兜底为主 id),可后补。

核心概念

中间产物仓(context-repo)

一个工作区唯一的中间产物 git 仓,存放结构化的需求/设计/测试产物:

context-repo/
├── requirements/<jira>/      # dev 视图:Jira 中间产物
│   ├── manifest.yaml         #   身份、标题、epic、prd.ref、repos[] 声明
│   ├── tech-spec/            #   技术方案
│   └── test-runs/            #   测试执行记录
└── prds/<prd>/               # product 视图:PRD 中间产物
    ├── manifest.yaml
    ├── prd/                  #   PRD 正文
    └── test-cases/           #   测试用例

"本地即真源" = 真相落在这套本地文件里,通过 ctx 命令读写、ctx commit 事务提交、ctx impact 做影响分析。

工作区布局

~/sdlc-workspaces/
├── .mirrors/<name>/          # 远程代码仓的全局共享 mirror(跨工作区复用)
└── <id>/                     # 一个工作区(id = Jira 号或 PRD 号)
    ├── context-repo/         # 中间产物仓(单实例)
    ├── repos/<name>/         # 代码仓 worktree
    ├── knowledge/<name>/     # 知识库(可多个)
    ├── AGENTS.md             # 工作区真源引导(首次生成)
    ├── CLAUDE.md             # @AGENTS.md import stub
    └── .workspace-cache.yaml # 身份缓存(再次装配可省略参数)

配置文件 ~/.sdlc/config.yaml

单层全局配置:

workspace:
  root: ~/sdlc-workspaces          # 远程 mirror 落在 <root>/.mirrors，全局共享
products: {}                       # 可选:地址预设分组(缺产品也能装配)
#  checkout:
#    context_repo:   [email protected]:sdlc/checkout-context.git
#    knowledge_base:                # 单个字符串或数组均可
#      - [email protected]:kb/checkout-kb.git
#      - [email protected]:kb/common-kb.git
#    jira_prefixes:  [PROJ, CHK]    # 便利:jira 号自动带出上面两个地址
#    description: "结账支付系统"    # 可选:展示用产品说明
#    keywords:                      # 可选:供语义匹配的关键词
#      - 结账
#      - 支付
#      - checkout
#    epic: DEMO-100                 # 本产品默认 epic/迭代 id（可选，首次装配自动带出）
#    repos: [backend, frontend]     # 本产品默认要装的逻辑仓 id（可选，对应下方 repos 表的 key）
repos: {}                          # 逻辑 id → 地址(顶层全局)
#  backend:  { remote: [email protected]:checkout/backend.git, local: ~/code/backend }
#  frontend: { remote: [email protected]:checkout/frontend.git }

• repos.<id>.local 存在(~ 会展开)则直接用本地路径建 worktree,不拉 mirror;否则用 remote clone 到全局 mirror。
• products 是可选的地址预设:通过 jira_prefixes 让 Jira 号自动带出 context_repo / knowledge_base;description / keywords 供上层 skill 展示与语义匹配;epic / repos 供装配首次兜底（命中产品后自动带出默认 epic 与代码仓清单，无需再手传 --epic/--repo）。缺产品不阻断装配,命令行显式地址优先。
• 顶层与产品子键均为 strict schema:顶层只允许 workspace / products / repos;产品只允许 context_repo / knowledge_base / jira_prefixes / description / keywords / epic / repos。
• 测试可用环境变量 SDLC_CONFIG 覆盖配置文件路径。

命令参考

install

初始化 ~/.sdlc/config.yaml(缺失则写默认模板,已存在则跳过),并把随包 skills 覆盖注册到 ~/.claude/skills 与 ~/.agents/skills。skill 复制失败只进入告警,不改变退出码。

config —— 全局配置

| 命令 | 说明 | | --- | --- | | config init | 写入默认配置模板(不覆盖已有) | | config get <key> | 读一项(点号 key,如 repos.backend.remote) | | config set <key> <value> | 写一项(value 经 YAML 解析,支持数组/数字/布尔),写前整体 schema 校验 | | config list | 打印全部配置 |

ctx —— 中间产物仓库

context-repo 根定位(所有 ctx 子命令通用):①显式 --repo <路径> → ②从 cwd 向上查找(目录同时含 prds/ 和 requirements/ 即为根)→ ③按 workspace id fallback。因此只要 cwd 在 context-repo 内(或其子目录),--repo 可省略,无需装配 workspace 即可就地运行;cwd 不在 repo 内时用 --repo <路径>(当前目录即 repo 根可用 --repo .)。零环境依赖类 skill(如 generating-tests、requirement-split-estimator)据此在 context-repo 下直接落库,不强制走 workspace。

| 命令 | 关键选项 | 说明 | | --- | --- | --- | | ctx resolve | --jira 或 --prd,可选 --kind、--repo | 解析实体根目录或某类产物落位目录 | | ctx new <kind> | --jira 或 --prd,可选 --name、--repo | 在落位目录创建带 frontmatter 的空壳 .md | | ctx commit <entity> | -m/--message,可选 --local、--dry-run、--repo | 事务提交该实体的中间产物改动(只本地,不 push;--local 保留为兼容默认) | | ctx manifest get <entity> <key> | 可选 --repo | 读 manifest 字段 | | ctx manifest set <entity> <key> <value> | 可选 --repo | 写 manifest 字段 | | ctx status <entity> | 可选 --repo | 查看 Jira 派生阶段 | | ctx impact --prd <id> | 可选 --repo | 分析 PRD 本地改动与受影响 Jira | | ctx feedback add | --prd、--type <defect\|supplement>、--from-jira、--title,可选 --repo | 追加一条 PRD 反馈(下游发现的缺陷/补充) | | ctx feedback list | --prd 或 --jira,可选 --type、--open、--repo | 列反馈(读时扫 feedback/) | | ctx feedback digest --prd <id> | 可选 --repo | 聚合 open defect 成待回写清单 |

ctx feedback:下游(技术方案)发现「PRD 需要改」时,就近沉淀为 append-only 反馈,落 prds/<PRD>/feedback/,不阻塞方案设计。type 只有 defect(PRD 缺陷待回写)/supplement(技术侧补充不必回写)两值;id 形如 FB-<YYYYMMDDTHHmmss>-<rand4>(时间戳+随机后缀,多 Jira 并发写同一 PRD 不撞名)。list 的 --prd/--jira 二选一(--jira 跨多 PRD 反查),--open 只留未闭环。闭环 = 人工把 FB-*.md 移入 feedback/resolved/,「是否闭环」由文件所在目录读时算出,不存状态字段。本次不实现「据 digest 更新 PRD 正文」那一步(digest 到清单为止)。

ctx new/resolve 的合法 kind: prd-doc、req-analysis、prototype、test-cases、estimation、tech-spec、task-breakdown、plan、retro、test-run。位置参数 <entity> 会自动判别:PRD-* 为 PRD,其余为 Jira;--jira / --prd 入口会显式指定实体类型。

ws —— 工作区装配与变更

| 命令 | 关键选项 | 说明 | | --- | --- | --- | | ws create | --jira <id> 或 --prd <id>,可选 --product、--context-repo、--knowledge(可多次)、--epic、--title、--prd-ref、--repo(可多次)、--repo-remote name=url(可多次)、--repo-base name=ref(可多次)、--branch | 装配/刷新工作区。默认工作分支 feature/<id>-<时间戳>(首次生成并持久化,重跑读回);--branch 显式覆盖 | | ws sync <entity> | 位置参数为 Jira/PRD id | context-repo pull --rebase(不 push) | | ws destroy <entity> | 位置参数为 Jira/PRD id | 拆各代码仓 worktree 后删除工作区目录(不删共享 mirror) | | ws mount --repo <id> | --jira <id>,可选 --branch、--repo-remote <url>、--repo-base <ref> | 挂代码仓 worktree(复用工作区 feature/<id>-<时间戳>)并写入 manifest.repos[] | | ws unmount --repo <id> | --jira <id>,可选 --force | 卸代码仓(脏工作树需 --force) | | ws mount --kb <url> | --jira <id> | 挂知识库(只改当前工作区视图) | | ws unmount --kb <name/url> | --jira <id>,可选 --force | 摘知识库 |

具体子命令形态以 sdlc-cli ws -h 为准。装配缺信息时以 needs 协议回报,常见码:CONTEXT_REPO_MISSING、KNOWLEDGE_MISSING、REPO_REMOTE_MISSING、PRD_REF_REQUIRED(dev 必填,回带 candidates[];--epic / --title 非必填,缺省不报 need);非阻断告警包含 PRD_REF_NOT_FOUND(给的 PRD 尚不在 context-repo,仍先装配)、ALREADY_PRESENT 等。

所有命令支持 --json 输出结构化结果,便于 skill / 脚本消费。

开发

pnpm install
pnpm build        # tsup 打包到 dist/
pnpm test         # vitest 运行测试
pnpm typecheck    # tsc --noEmit
pnpm dev          # tsup --watch

• 技术栈:TypeScript(ESM)、clipanion(命令)、zod(schema 校验)、simple-git、gray-matter / yaml。
• 测试通过 SDLC_CONFIG 环境变量隔离配置路径,用临时目录 + git 仓构造夹具。

License

私有 / 内部使用。