diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..f40ddac --- /dev/null +++ b/.editorconfig @@ -0,0 +1,21 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false + +# The upstream snapshot is retained without formatting changes. +[upstream/fd-engineering/**] +charset = unset +end_of_line = unset +insert_final_newline = unset +indent_style = unset +indent_size = unset +trim_trailing_whitespace = unset diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..ff5e773 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,11 @@ +* text=auto + +*.md text eol=lf +*.yaml text eol=lf +*.yml text eol=lf +.gitignore text eol=lf +.gitattributes text eol=lf +.editorconfig text eol=lf + +# Preserve the original upstream snapshot bytes. +upstream/fd-engineering/** -text diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bf01045 --- /dev/null +++ b/.gitignore @@ -0,0 +1,28 @@ +# Local configuration and credentials +.env +.env.* +!.env.example +*.pem +*.key +*.dpapi + +# Operating system and editor files +.DS_Store +Thumbs.db +Desktop.ini +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# Local tooling, caches and temporary outputs +__pycache__/ +*.py[cod] +.venv/ +.cache/ +/tmp/ +/temp/ +*.log + +# .agents/ and .tasks/ contain project deliverables and remain tracked. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..dc551a4 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,25 @@ +# 更新记录 + +本文件记录用户可见的变化。当前尚未发布带版本号的正式版本。 + +## 未发布 + +### 2026-11-16 · 仓库信息完善 + +- 新增 README,说明项目用途、安装、八阶段调用、工作方式及目录结构。 +- 新增贡献指南、更新记录和来源与许可状态说明。 +- 新增 `.gitignore`、`.gitattributes` 和 `.editorconfig`,约定本地文件排除、换行和编辑格式,并保留上游参考快照原样。 +- 完善 Gitea 仓库简介和主题标签。 + +### 2026-11-16 · 建立远端仓库 + +- 建立私有 Gitea 仓库 `FuDie0915/SB-Workflow`,使用 `main` 分支。 +- 提交并推送已有技能、项目级安装副本、原始参考和维护记录,共 47 个文件,初始提交为 `77def46`。 + +### 既有技能能力 + +- 通过 `$sb-workflow` 单入口选择研究、质询、规划、界面设计、执行、审查、工程交付和提交说明八阶段。 +- 按需加载 11 份参考文档,保留中文输出、六项工程约束、分层 TODO 与任务恢复机制。 +- 提供 Codex 界面元数据及项目级安装副本,并保留原始 `fd-engineering` 参考快照。 + +既有适配与安装的详细过程、检查证据和未实测范围见 [维护记录](.tasks/sb-workflow.md)。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3aa6a55 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# 参与维护 + +本仓库维护 `SB-Workflow` 技能及其使用文档。提出修改前,请先说明触发场景、目标行为和验收方式;涉及授权边界或阶段语义的调整,应明确说明行为影响。 + +## 报告问题 + +在 [Issues](https://stupidbrain.sbs/FuDie0915/SB-Workflow/issues) 中提供: + +- 使用的 Codex 环境,以及显式调用还是自动匹配。 +- 触发问题的提示词、当时的工作阶段和相关任务状态。 +- 预期行为、实际行为,以及可复现的最小示例。 +- 已完成的检查和脱敏后的必要证据。 + +提交建议时说明希望解决的问题、使用场景和验收条件。分享示例前移除账号凭据、私有项目内容和无关的个人信息。 + +## 修改位置 + +| 路径 | 维护约定 | +| --- | --- | +| `sb-workflow/` | 技能维护源目录;先在这里修改 | +| `.agents/skills/sb-workflow/` | 本仓库安装副本;技能变更时同步,包含新增、修改和删除的文件 | +| `upstream/fd-engineering/` | 原始参考快照;保持文件内容原样 | +| `.tasks/sb-workflow.md` | 项目的适配、验证与维护记录;保留历史证据 | +| 根目录文档 | 安装、用法、协作约定和变更说明 | + +技能引用应使用包内相对路径,不写入开发机绝对路径。修改文件时使用 UTF-8,遵循 `.editorconfig`;上游快照不参与格式整理。 + +## 提交前检查 + +在仓库根目录运行: + +```shell +git diff --check +git diff --exit-code -- upstream/fd-engineering +``` + +第一条检查差异中的空白错误,第二条核对原始快照没有本地改动。这些检查不能替代内容核对。 + +按修改范围完成以下验证,并在 Pull Request 中说明实际执行的项目: + +1. 新增或修改的 Markdown 本地链接指向存在的文件,代码块和表格可正常呈现。 +2. `sb-workflow/` 与 `.agents/skills/sb-workflow/` 的相对文件列表和 SHA-256 一致。 +3. 技能仍包含 `SKILL.md`、`agents/openai.yaml` 及 11 份参考文档;变更结构时更新相关引用和说明。 +4. 修改调用方式、阶段或授权规则时,逐项检查八阶段及相关边界场景。 +5. 修改技能发现相关内容时,在实际 Codex 环境检查;仅完成静态检查时明确标注。 + +仓库当前以指令文档为主,没有构建步骤或自动化测试套件。文档修改无需安装运行时依赖;不要将静态检查写成真实模型运行成功。 + +## 提交与评审 + +- 每次提交围绕一个明确目标,说明行为或文档发生了什么变化。 +- 用户可见的变更同步补充 [CHANGELOG.md](CHANGELOG.md);影响安装或用法时同步更新 [README.md](README.md)。 +- Pull Request 说明问题、最终修改、实际验证,以及仍未验证的部分。 +- 不提交令牌、密码、私钥或本地认证文件。Git 认证配置属于仓库元数据或本机凭据存储。 + +来源与当前许可状态见 [NOTICE.md](NOTICE.md)。 diff --git a/NOTICE.md b/NOTICE.md new file mode 100644 index 0000000..9a5abf5 --- /dev/null +++ b/NOTICE.md @@ -0,0 +1,21 @@ +# 来源与许可状态 + +## 来源 + +SB-Workflow 由 `fd-engineering` 工程工作流适配而来,用于 Codex 的单入口技能调用。 + +仓库内的 [适配记录](.tasks/sb-workflow.md) 记录了以下来源: + +- 原始项目:`Local-Cursor`。 +- 原始目录:`internal/skills/builtin/fd-engineering`。 +- 提取时对应提交:`8affd678b685993b6b347371e7f05dcc53361305`。 +- 保留的原始参考:[upstream/fd-engineering](upstream/fd-engineering),共 20 个文件。 +- 适配后的技能:[sb-workflow](sb-workflow),包含入口、参考文档与 Codex 界面元数据。 + +`upstream/fd-engineering/` 用于保存来源快照。维护时保留其文件内容,不将适配后的修改回写到该快照。 + +## 许可状态 + +当前仓库及保留的来源快照均未附带许可证文件,本仓库尚未声明开源许可证。维护者确认来源许可并选择适当的授权方式后,再补充许可证及必要的归属说明。 + +本文件记录来源和当前状态,不新增或替代许可证条款。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..50d117b --- /dev/null +++ b/README.md @@ -0,0 +1,124 @@ +# SB-Workflow + +面向 Codex 的工程协作工作流技能。使用 `$sb-workflow` 加自然语言选择研究、质询、规划、界面设计、执行、审查、工程交付或提交说明阶段,让需求、授权、任务进度和验证证据能够接续。 + +[快速开始](#快速开始) · [八个阶段](#八个阶段) · [目录结构](#目录结构) · [参与维护](CONTRIBUTING.md) · [更新记录](CHANGELOG.md) · [来源与许可](NOTICE.md) + +## 适合处理什么 + +- 调查陌生项目、定位问题,并区分已知事实与待验证假设。 +- 对方案中的关键决策进行质询,形成可执行的计划和验收条件。 +- 在已授权范围内持续实施、检查和自审,保留复杂任务的恢复记录。 +- 按实际需要处理 UI/UX 原型、代码审查、打包交付和提交说明。 + +技能采用单入口和按需加载的参考文档,无需每次走完全部阶段。普通概念问答、文案和插画无需完整流程。 + +## 快速开始 + +### 直接在本仓库使用 + +需要 Git、支持本地 Skills 的 Codex,以及本私有仓库的访问权限。技能本身是 Markdown 与 YAML 文件,没有需要安装的运行时依赖;实际任务使用的工具和权限由宿主环境提供。 + +```shell +git clone https://stupidbrain.sbs/FuDie0915/SB-Workflow.git +cd SB-Workflow +``` + +在 Codex 中打开克隆后的项目。本仓库已提交 `.agents/skills/sb-workflow/`,用于项目级技能发现。 + +输入以下内容开始使用: + +```text +$sb-workflow 研究这个项目 +``` + +也可以直接描述需求: + +```text +$sb-workflow 帮我调查这个报错的原因,先给出证据和修复方案 +``` + +### 安装到其他项目 + +将本仓库的 `sb-workflow/` 整个目录复制到目标项目的 `.agents/skills/sb-workflow/`。保留 `references/` 和 `agents/` 子目录,不能只复制 `SKILL.md`。 + +以下 PowerShell 示例从本仓库根目录运行;先把目标路径改为你的项目路径: + +```powershell +$targetProject = 'D:\path\to\your-project' +$source = (Resolve-Path -LiteralPath '.\sb-workflow').Path +$destination = Join-Path $targetProject '.agents\skills\sb-workflow' + +if (-not (Test-Path -LiteralPath $targetProject -PathType Container)) { + throw '目标项目目录不存在,请先修改 targetProject。' +} +if (Test-Path -LiteralPath $destination) { + throw '目标已安装 sb-workflow,请先比较版本,再决定如何更新。' +} + +New-Item -ItemType Directory -Path (Split-Path -Parent $destination) -Force | Out-Null +Copy-Item -LiteralPath $source -Destination $destination -Recurse +``` + +其他系统也按相同的目录结构完整复制即可。 + +安装后在 Codex 中打开目标项目,再使用 `$sb-workflow`。Codex 会检测技能变化;若未显示,可重启 Codex。项目级目录及发现规则见 [OpenAI 官方 Skills 文档](https://learn.chatgpt.com/docs/build-skills)。 + +## 八个阶段 + +| 阶段 | 调用示例 | 主要产出 | +| --- | --- | --- | +| 研究 / RESEARCH | `$sb-workflow 研究这个项目` | 事实、证据、范围与未知项 | +| 质询 / GRILL | `$sb-workflow 质询这个方案中的关键决策` | 关键决策、取舍与待解决问题 | +| 规划 / PLAN | `$sb-workflow 规划这个需求` | 实施步骤、分层 TODO 与验收条件 | +| 界面设计 / UIUX | `$sb-workflow 为这个页面设计原型` | 按确认的简报和候选数量制作原型 | +| 执行 / EXECUTE | `$sb-workflow 执行当前计划` | 已授权的实现、检查与自审证据 | +| 审查 / REVIEW | `$sb-workflow 审查当前修改` | 基于实际差异的审查结论 | +| 工程交付 / DEVOPS | `$sb-workflow 为这个项目制定打包交付方案` | 适合项目的环境、验证与交付方案 | +| 提交说明 / COMMIT | `$sb-workflow 生成提交说明` | 基于实际修改的提交说明草稿 | + +这些是同一技能的自然语言调用示例。可以明确指定阶段,也可以让技能根据需求和当前任务状态选择。 + +## 工作方式 + +**按事实推进。** 技能强调先复用、保持任务聚焦、区分事实与假设、解释复杂度、暴露失败,并以实际证据完成交付。 + +**保留可恢复的任务状态。** 短任务可在对话中记录计划和结果;复杂任务优先沿用项目已有约定,否则使用 `.tasks/.md` 保存计划、授权、分层 TODO 和验证证据。 + +**遵循当前授权与宿主能力。** 研究、规划、审查与提交说明各有范围;审查和提交说明不会自动修改源码或 Git 状态。实现、提交、推送或部署应遵循用户的实际授权。阶段名称描述工作职责,不能改变宿主权限或实际运行模式。 + +详细约定见 [技能入口](sb-workflow/SKILL.md) 和 [阶段与授权规则](sb-workflow/references/workflow.md)。 + +## 目录结构 + +```text +SB-Workflow/ +├── README.md # 项目介绍、安装与用法 +├── CONTRIBUTING.md # 维护约定与检查方法 +├── CHANGELOG.md # 更新记录 +├── NOTICE.md # 来源与许可状态 +├── .gitignore # 本地配置、凭据及临时文件忽略规则 +├── .gitattributes # 文本换行与上游快照保留规则 +├── .editorconfig # 编辑器编码与格式约定 +├── sb-workflow/ # 维护与安装使用的技能源目录 +│ ├── SKILL.md # 单入口、路由与共同约束 +│ ├── agents/openai.yaml # Codex 界面元数据 +│ └── references/ # 11 份按需读取的参考文档 +├── .agents/skills/sb-workflow/ # 本仓库的项目级安装副本 +├── .tasks/sb-workflow.md # 适配、安装与仓库维护记录 +└── upstream/fd-engineering/ # 原始参考快照,保留原样 +``` + +`sb-workflow/` 是维护源目录,`.agents/skills/sb-workflow/` 应与其保持一致。安装到其他项目时只需复制技能目录;`upstream/` 是来源参考,无需一并安装。 + +## 验证与当前状态 + +仓库维护检查包括 Markdown 引用、技能文件完整性、源目录与安装副本一致性,以及上游快照是否保持原样。具体要求见 [贡献指南](CONTRIBUTING.md),已有适配和本机技能发现的检查证据保存在 [维护记录](.tasks/sb-workflow.md)。 + +静态检查和技能发现检查覆盖文件结构与加载状态。真实模型的隐式触发、阶段选择及业务执行效果仍需在具体宿主和任务中验证。 + +## 反馈与维护 + +有访问权限的协作者可在 [Issues](https://stupidbrain.sbs/FuDie0915/SB-Workflow/issues) 报告问题或提出建议,通过 [Pull Requests](https://stupidbrain.sbs/FuDie0915/SB-Workflow/pulls) 提交修改。请附上触发示例、预期行为、实际结果和必要的脱敏证据。 + +本仓库尚未声明开源许可证。原始参考来源及许可状态见 [NOTICE.md](NOTICE.md)。