@chenguangyao/devflow-kit 0.1.43

package/CHANGELOG.md

@@ -0,0 +1,232 @@
+# Changelog
+
+本项目遵循 [Keep a Changelog](https://keepachangelog.com/),版本号遵循 [Semver](https://semver.org/)。
+
+## [0.1.6] — `devflow init` 默认不再每个项目都写 IDE 文件(全局 skill 已覆盖)
+
+### 改进(Changed)
+
+- **`devflow init` 默认 IDE 行为改为"按需写"**:
+  - 检测到用户级 skill (`~/.cursor/skills/devflow-kit/`) 已装 → **不再生成** `.claude/CLAUDE.md` / `.cursor/rules/devflow.mdc` / `AGENTS.md`
+  - 没装用户级 skill → 跟以前一样,3 个文件全写(老行为兜底)
+  - 原因:这 3 个文件里 `workflow` 段(命令速查表,30 行)在每个项目里**完全相同**,而且全局 skill 的 `df-orchestrator/SKILL.md` 已经是它的超集;`project-overview` 一行引用也已经被 skill 在每次会话开头从 `devflow/config.json#projectOverview.referencedFile` 读取,无需中转
+- **新增 `--ide=auto|full|minimal|none`** 显式控制:
+  - `auto`(默认):有全局 skill → minimal,没有 → full
+  - `full`:每个目标都写完整 marker(老行为)
+  - `minimal`:跳过所有 IDE 文件,依赖全局 skill + `devflow/config.json` 给 AI 上下文
+  - `none`:连 minimal 那一行提示日志都不打,完全静默跳过
+- `cfg.ide.mode` 写进 `devflow/config.json`,后续 `devflow update` 会按这个模式继续工作
+
+### 新增(Added)
+
+- **`devflow update --ide-clean`** —— 一键清理已有的 IDE marker 段(从老的 `--ide=full` init 留下的)
+  - 只删 `<!-- BEGIN devflow:* -->` 区段,保留用户在同一文件里的其他内容
+  - marker 删完后文件变空(比如 `.cursor/rules/devflow.mdc` 通常就是只有 marker)→ 整个文件一并删除
+  - 升级/切换到 minimal 模式后跑一次,一键回收冗余文件
+- minimal 模式下,如果检测到旧 `--ide=full` 留下的文件,会在日志里提示"`devflow update --ide-clean` 一键清理",不强制改
+
+### 迁移建议
+
+- 现有项目在升级到 0.1.6 后,**重跑 `devflow init`** 会自动按新默认走 minimal,但**老 IDE 文件不会被自动删**(怕你在里面加了别的内容)
+- 想清理:`devflow update --ide-clean`,**只删** devflow marker 段,其他内容保留;文件全空就连文件一起删
+- 想保留老行为:`devflow init --ide=full`,所有项目继续写 3 份文件
+
+---
+
+## [0.1.5] — `~/.config/devflow/providers.json` 默认创建 + `provider setup` 引导式向导
+
+### 新增(Added)
+
+- **`devflow provider setup`** —— 一行命令的引导式向导(对标 oh-my-claude / openclaw 那种交互式安装):
+  - 列出 6 个内置预设(`intake.qs-bridge` / `issue.qs-bridge` / `vcs.qs-bridge` / `ci.qs-bridge` / `notify.smtp` / `kb.weknora`),已配置的会标 `[configured]`
+  - 选择支持 `1,3,5` / `1 3 5` / `all` / `none`,空选默认 `all`
+  - 选中的逐个走"字段级提示词":每个字段有 `# help` 说明,可以填具体值、敲 `env:NAME` 引用环境变量、或回车跳过用默认/已有值
+  - 已配置的 provider 询问 (k)eep / (e)dit / (s)kip,不会强行覆盖
+  - 全部填完一次性 `chmod 0600` 写入,然后逐个 `validate`,有失败给出 `devflow provider rotate <name>` 的修补提示
+  - 默认写 `~/.config/devflow/providers.json`(`--scope=user`),`--scope=project` 写仓库级
+  - 非 TTY 直接退出并提示用 `devflow provider add --no-prompt`(脚本化场景)
+- **`devflow init` 完成后自动提示**:如果 `~/.config/devflow/providers.json` 还是空 `{}`,会在 "next:" 段顶端高亮 `devflow provider setup` 这一行
+- **SMTP 引导补全 `user / pass / authMethod`**(原本 hints 里漏了认证字段)
+- **自动创建 `~/.config/devflow/providers.json`**(空 `{}`,chmod 0600),在两处时机都会做:
+  - `npm i -g @chenguangyao/devflow-kit` 的 `postinstall` 钩子执行时(即使 skill 已存在,只要配置文件缺失也会补)
+  - `devflow init` 在每个项目里执行时(不会覆盖已有内容)
+- 同目录顺手生成 **`README.md`**,包含 schema 示例、6 类 provider(intake / issue / vcs / ci / notify / kb)的填法、`${env:VAR}` 引用约定、resolution order 与 secret hygiene 说明
+- 目录权限 `0700`,文件权限 `0600`,**每次调用都会重新强制**(防止用户/工具误改宽)
+- 新增 helper `src/providers/userconfig.js#ensureUserConfig()`,可被 init / postinstall / 任意子命令复用
+- **`devflow provider add/remove/rotate` 默认走 user scope**,即写入 `~/.config/devflow/providers.json`
+  - 新增 `--scope=user|project` 显式切换,`--scope=project` 仍写到 `<repo>/devflow/providers.json`(用于仓库级覆盖)
+  - 兼容旧行为:`provider load()` 的合并顺序仍是 project > user > 内置 local
+- 18 项新测试:`userconfig.test.js`(6 个,覆盖创建/幂等/权限/perms re-apply)+ `provider-setup.test.js`(9 个,覆盖 `parseSelection` 边界 + 预设目录 + TTY 拒绝 + 端到端 stub readline)+ `init` & `postinstall` 各补 1 个回归 + 1 个升级场景(skills 已装但 config 不存在)
+
+### 内部
+
+- `init.test.js` 中遗漏的 `withCleanHome` 包裹补齐,避免测试污染开发者真实 `~/.config/devflow/`
+- `provider.js` 的所有 user-facing 错误信息从 `df xxx` 同步到 `devflow xxx`
+
+### 升级建议
+
+- 现有用户**无需手动迁移**:下次跑 `devflow init` 或 `npm i -g @chenguangyao/devflow-kit` 升级时,该文件会自动补建
+- 已经把 provider 写在 `<repo>/devflow/providers.json` 里也**不用动**,resolution order 没变
+- 只想保留一套配置的用户可以执行 `devflow provider add <name> --scope=user`(或编辑 `~/.config/devflow/providers.json`),然后从 repo 里删掉
+
+---
+
+## [0.1.4] — skill 装在独立 `devflow-kit/` 子目录,不再散在 IDE skills 顶层
+
+### 破坏性变更(Breaking,但带向后兼容)
+
+- **skill 安装目录从扁平改为 namespace**。安装路径从 `<skills>/<skill-name>/` 改为 `<skills>/devflow-kit/<skill-name>/`,11 个 skill 整套打包,不再污染 `~/.cursor/skills` / `~/.claude/skills` 顶层。Cursor / Claude Code 都会递归扫描 SKILL.md,运行时透明无影响。
+- 原有 0.1.x **扁平布局自动迁移**:
+  - 直接跑 `devflow skills install --scope=user` 时,检测到顶层散落的 11 个 skill 文件夹会**自动**搬进 `devflow-kit/`,不重复
+  - `userSkillsInstalled()` 同时识别两种布局,旧版用户不会被告知"未安装"
+- 新增 **`devflow skills migrate [--scope=user|project]`** —— 显式迁移命令,安全幂等,只动我们 ship 的 11 个目录,不碰任何第三方 skill(如 `superpowers/`)
+
+### 新增(Added)
+
+- `devflow skills status` 输出多了 layout 标记,清晰展示是 `devflow-kit/`(新)还是 `(flat — legacy)`(旧),并对旧布局提示一行迁移建议
+- `devflow skills uninstall` 同时清理 namespace 目录和遗留扁平 skill 目录,不留尾巴
+- 4 项新测试覆盖 namespace 布局、自动迁移、显式迁移、uninstall 多源清理
+
+### 内部
+
+- `src/cli/commands/skills.js` 引入 `NAMESPACE` / `SHIPPED_SKILLS` / `detectLegacyFlat` / `migrateFlatToNamespace`,布局策略集中可演进
+
+---
+
+## [0.1.3] — postinstall bug fix:在 dev 仓库内做 `-g` 安装也能装 skill 了
+
+### 修复(Fixed)
+
+- **postinstall 不再被自身 dev 仓库目录拦截**。0.1.2 引入了一道 "dev-on-self" 守卫,它检查 `INIT_CWD/package.json` 是否就是本包,然后跳过安装。但当用户 `cd <devflow-kit 仓库> && npm i -g @chenguangyao/devflow-kit`(从仓库内做全局安装)时,这个守卫会误伤,导致 `~/.cursor/skills` 和 `~/.claude/skills` 全空。
+- 现在仅靠 `npm_config_global !== 'true'` 一道关卡处理 dev-on-self —— 在仓库内 `npm install` 装 devDeps 时 `npm_config_global` 不为 true,自然跳过;而 `npm i -g .` / `npm i -g <pkg>` 是用户的明确意图,**不再**被拦。
+- 增加回归测试 `postinstall: still installs even if INIT_CWD is our own repo, as long as -g is set` 锁定该行为。
+
+### 内部
+
+- skill 安装日志显示 `~/.cursor/skills/foo`(用户级)/`./.cursor/skills/foo`(项目级)而不是混乱的 `../../../.cursor/skills/foo` 相对路径。
+- `init.test.js` 用 `withCleanHome()` 隔离开发者真实 `~/.cursor/skills`,避免本机已装用户级 skill 时 init 测试假阳性失败。
+
+---
+
+## [0.1.2] — `npm i -g` 自动装 skill
+
+### 新增(Added)
+
+- **`postinstall` 钩子** —— `npm i -g @chenguangyao/devflow-kit` 完成后自动把 11 个 SKILL 安装到 `~/.cursor/skills/` + `~/.claude/skills/`,真正做到**装一次,所有项目共用**。
+  - 仅在 **全局安装**(`npm_config_global=true`)时触发;`npm i` 本地装 / `npm install` 在 devflow-kit 仓库内自身开发时**不**触发
+  - 已存在则**不覆盖**(用户可能改过 skill),只 log 一行提示
+  - 失败 **绝不**让 `npm install` 整体失败 —— 任何错误只 warn,引导用户跑 `devflow skills install --scope=user` 兜底
+  - 三条逃生通道:`DEVFLOW_SKIP_POSTINSTALL=1` / `npm i -g --ignore-scripts` / `CI=true` 任一即跳过
+- 新增 6 项 postinstall 端到端测试(skip-when-not-global / DEVFLOW_SKIP_POSTINSTALL / CI / dev-on-self / clean install / 已装不覆盖)
+
+### 内部
+
+- `package.json` 加入 `scripts.postinstall` + `files` 增加 `scripts/`(打包包含 `scripts/postinstall.js`)
+
+---
+
+## [0.1.1] — 改名 + 全局共享 skill
+
+### 破坏性变更(Breaking)
+
+- 包名改为 **`@chenguangyao/devflow-kit`**(scoped)。安装方式:`npm i -g @chenguangyao/devflow-kit`。
+- CLI 主命令从 `df` 改为 **`devflow`**(macOS 自带的 `df` = disk free,会和 npm 全局 bin 冲突)。短别名 `dfk` 同时注册,二选一。所有文档、CI 模板、skill 引用、状态机、help 文本同步更新。
+- `devflow skills install --target=claude` 现在写到 **项目内** `.claude/skills/`(此前是 `~/.claude/skills/` 用户级)。用户级安装请改用 `--scope=user`(见下)。
+
+### 新增(Added)
+
+#### 全局共享 skill(推荐)
+
+- **`devflow skills install --scope=user`** —— 一次性把 11 个 SKILL 放进 `~/.cursor/skills/` 和 `~/.claude/skills/`。所有项目共用,无需在每个 repo 重复 `devflow init` 才能用上 skill。
+- **`devflow init` 自动检测用户级安装**:发现 `~/.cursor/skills/df-orchestrator/` 和 `~/.claude/skills/df-orchestrator/` 都存在时,跳过本地 skill 拷贝,**只**生成 `devflow/` 目录 + IDE marker。
+- **`df-orchestrator` 增加 "项目上下文加载" 章节**:用户级 skill 会在每次会话开头读 `<repo>/devflow/config.json#projectOverview.referencedFile` → 加载项目自带的 `CLAUDE.md` / `AGENTS.md` / `README.md` 等作为本次会话背景。"通用 skill + 项目化 context" 通过 config 串起来。
+- **`devflow skills status`** —— 列出用户级 / 项目级 skill 当前安装位置
+- **`devflow skills uninstall --scope=user|project`** —— 反操作
+
+#### 沿用本地安装(legacy / 老仓库适配)
+
+- 没装用户级时,`devflow init` 仍自动把 SKILL 拷到当前工程的 `.cursor/skills/` / `.claude/skills/` / `.agents/skills/`(取决于 `--targets` 选了哪几个 IDE,默认全装)。
+  - 关闭:`devflow init --no-skills`
+  - 单独覆盖目标:`devflow init --skills-target=cursor`(逗号分隔多个)
+- `--target=cursor,claude,agents` 多目标支持
+
+#### 内部 API + 测试
+
+- `skills.installForInit(root, targets, opts)` / `skills.userSkillsInstalled()` 程序化入口
+- 新增 9 项单测覆盖 auto-install、`--no-skills`、`--skills-target` 覆盖、`installForInit` 多目标、`--scope=user` 写入、`userSkillsInstalled` 检测、init 跳过本地拷贝、uninstall 清理、CLAUDE.md / AGENTS.md 自动 detect 为 projectOverview
+
+### 修复(Fixed)
+
+- `bin/df.js` 重命名为 `bin/devflow.js`(配套 `package.json#bin` / `npm start` 同步)
+
+---
+
+## [0.1.0] — 首个公开里程碑
+
+### 新增(Added)
+
+**CLI 主干**
+- `devflow` CLI 骨架(短别名 `dfk`)+ 多 IDE 指令文件(`.claude/CLAUDE.md` / `.cursor/rules/devflow.mdc` / `AGENTS.md`)marker 段幂等写入
+- change-folder 模型 + `state.json` 状态机(phases / iterations / tasks / rounds / auditLog)
+- `df init / update / uninstall` 幂等接入;`df init` 自动识别 git remote / 语言栈 / 构建工具,推断 Jenkins job 候选并写入 `config.detect`(对齐 arb `init-project.py`)
+- `df ingest <input>` 多入口路由(URL / JIRA ID / incident)→ refs/ + proposal.md
+- `df new / propose / requirement / design / plan`
+- `df apply` — 支持 `--task=N --start|--done|--skip|--fail --note="..." --no-worktree`,自动建/关联 worktree
+- `df review` — 3 轮闭环:`--round` / `--status` / `--force-pass --reason="..."` / `--continue-rounds`,自动从 `review.md` 解析 MUST/SHOULD/NIT
+- `df worktree create|list|cleanup` — 每 task 一份 `.devflow-worktrees/<slug>/task-N/` + 分支 `devflow/<slug>/task-N`
+- `df verify / test <kind> / report`(9 种测试框架 + 5 种覆盖率格式)
+- `df deliver --mode=pr|merge|keep|discard`
+- `df archive` — spec delta 自动合并到 `devflow/specs/`,change folder 迁入 `archive/`
+- `df status` — 阶段/artifacts/apply-tasks/review-rounds/next-hint 全览
+- `df doctor` — 7 维度全景体检(env / config / provider / cred / change / knowledge / overview / git),`--scope --fix --json`
+- `df provider list/status/add/relogin/rotate/logout/remove/audit`
+- `df knowledge init/query/deposit/sync/migrate/validate`
+- `df skills install`
+- `df enable / disable / switch project-overview / sync project --check`
+
+**质量闸门**
+- `df verify` 前置检查 `review.status=completed`,可 `--skip-review-gate --reason="..."` 审计覆盖
+- `df deliver` 前置 `verify.status=completed` + `review.status=completed` + `df doctor --scope change,git,cred` 无错误,可 `--skip-doctor --reason="..."` 审计覆盖
+- `df review` 3 轮硬规则:round ≤ 3 且 must > 0 → back_to_apply;round 3 且 must > 0 → blocked(exit 1);round > 3 拒绝除非 `--continue-rounds`
+- `df review --force-pass` 必须带 `--reason`
+
+**Provider 生态**
+- Provider 协议 + `local` 默认实现
+- `intake-qs-bridge` / `issue-qs-bridge` / `ci-qs-bridge` 适配器(wiki / jira / jenkins via qs-bridge CLI)
+- `kb-weknora` **配置驱动** 适配器 —— 只内置一套通用最小契约(Bearer + `/api/v1/kb/{kb_id}/*`),`auth` / `paths` / `body` / `responsePath` / `idempotent` 全部可通过 `providers.json` 覆盖。为避免把任何具体内网形状打进 npm 包,arb-WeKnora 的 endpoint shape 以本地参考片段维护(见 `.internal/` + `.gitignore` + `.npmignore`,不提交、不打包、不推 npm)。`df provider add kb.weknora --from <local.json>` 可一键导入
+- `df provider add --from <file>` — JSON 片段导入,支持 "整段 provider 条目" 或 "裸 config{} 片段" 两种结构;配合 `.internal/` 的本地参考,团队只要下发一次模板,人人都能 `df provider add ... --from ...` 秒接内网 KB
+- `df provider add` 引导提示增强 —— 对 `weknora` / `smtp` / `qs-bridge` 等 driver 按字段提供行内 help 文字、默认值、布尔/枚举选项提示,新手无参考文档也能顺势填完
+- `notify-smtp` **零依赖 SMTP driver**,Node.js 手写(`tls`/`net`),对齐 arb `deploy-submit/send-email.py`:SMTPS(465)/ STARTTLS(587)/ plain 三种连接模式,`AUTH PLAIN` / `AUTH LOGIN` 自动协商,Markdown→HTML(表格/列表/标题/粗体/行内代码),多附件,RFC 2047 中文 Subject 编码
+- `df deliver --notify` / `--notify-dry-run` 在 MR 建完后自动发提测邮件,审计留痕 `deliver.notify`
+- Provider 生命周期:`loadOrAuth` / `withAutoRetry`(AuthExpiredError 自动 relogin)/ `securityCheck`(plaintext token 审计 + chmod 0600)
+
+**知识库子系统**
+- 4 域 9 类改良骨架:`1-domain/{concepts,scenarios,rules}` / `2-system/{services,contracts,decisions}` / `3-ops/{runbooks,incidents,environments}` / `4-archive/solutions`
+- `.meta.json` + SHA256 增量同步协议
+- `df knowledge deposit` 自动按分类归位 `learnings.md` 小节
+- `df knowledge sync` 增量推到 provider(支持 create/update/delete,空分类也能正确处理)
+- `df knowledge migrate --from=arb-7 --to=improved-9`
+- CI 模板:`.github/workflows/devflow-kb-sync.yml` / `.gitlab-ci.devflow.yml`
+
+**Skills**
+- 11 个 SKILL.md:`df-orchestrator` / `brainstorm` / `requirement-analysis` / `tech-spec` / `test-spec` / `plan` / `apply`(worktree-swarm)/ `code-review`(3 轮)/ `verify` / `deliver` / `archive`
+
+**文档 / 样例**
+- `README.md` + `CHANGELOG.md`
+- `docs/RFC-001-devflow-kit.md`
+- `docs/migration-from-arb.md`(arb-workflow-kit → devflow-kit 对照表)
+- `docs/internal-gitlab-setup.md` — 企业内部 GitLab + Jenkins + 私有 registry 完整落地指引(A/B/C 分发策略 + provider 配置 + 团队推行 checklist + FAQ)
+- `examples/coupon-grant-api/` — 完整 change folder + delta/ + reports/ + archive/ + knowledge/ 端到端样例
+
+**测试**
+- 78 用例覆盖 parsers(9 框架 + 5 覆盖率格式)/ worktree / apply / review / verify-gate / kb-weknora(built-in 默认契约 + arb-shape 全量 override + 部分 path 合并 override + auth 覆盖)/ notify-smtp(md→html + MIME + SMTP 协议全路径含 STARTTLS)/ autodetect(5 种 remote 格式 + 8 种语言)
+
+### 已知限制
+
+- `df migrate from-arb`(从 arb 仓库整库迁移的自动化)未实现,仅文档指导
+- `df deliver --mode=merge|discard` 为 stub,当前版本引导手动操作
+- 部分 provider 驱动(`confluence-cloud` / `notion` / `feishu-doc` 等)为接口占位,未完整实现
+
+### 贡献者
+
+- chenguangyao

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chenguangyao and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.