Files
SB-Workflow/.tasks/sb-workflow.md
T

94 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SB-Workflow Codex 工作流适配与安装
## 当前状态
- 协议阶段:DEVOPS / 工程交付,仓库信息完善已完成。
- 有效计划:v1 为已完成的本地适配与验证;本轮仓库完善范围为 README、协作与来源说明、更新记录、Git 与编辑器约定,以及 Gitea 简介和主题标签。
- 本轮授权:用户先要求为当前项目建立远端仓库,随后指出缺少 README 等标准仓库信息;本轮直接补齐并验证、提交、推送,沿用私有仓库与 `main` 分支。
- 独立项目:`D:\Project\SB-Workflow`;交付技能目录:项目内 `sb-workflow`。
- 后续授权:用户先要求安装到原工作目录 `D:\Project\QuQ`,随后要求迁移成独立项目并清理原目录;本轮又明确要求将 workflow 改名为 `SB-Workflow` 并安装到当前 QuQ 项目。
- 当前 TODO:适配、安装、建仓及本轮仓库信息完善均已完成。
- 下一步:按具体需求使用或维护技能;真实模型阶段选择与业务执行仍不属于本次验收。
- 当前边界:技能源目录和安装副本不作功能修改,`upstream/fd-engineering` 保持原样。远端为私有仓库 `https://stupidbrain.sbs/FuDie0915/SB-Workflow`,本地 `main` 跟踪 `origin/main`;认证配置仅在本项目 Git 元数据中。
## 目标、范围与验收
制作通过 `$sb-workflow` 加自然语言选择阶段的 Codex Skill,显示名称为 `SB-Workflow`;其前身名为 `fd-engineering`。保留八阶段、中文输出、六项工程约束、分层 TODO、任务记录与恢复机制。交付 `SKILL.md`、11 份参考文档及 `agents/openai.yaml`,使用可移植相对引用。
显式阶段优先;未指定时按意图和任务状态判断。任务授权与宿主权限分别核对,批准可复用,工作流阶段不能改变实际宿主模式。审查和提交说明不自动修改源码或 Git 状态。
## 研究依据与决策
- 源文件:原始 `fd-engineering` 下 20 个文件,当前保存于独立项目的 `upstream/fd-engineering`;适配前记录全部文件的 SHA-256,最终比较以确认原样保留。
- 原始内容来自 Local-Cursor 的 `internal/skills/builtin/fd-engineering`,提取时对应提交 `8affd678b685993b6b347371e7f05dcc53361305`。
- 用户选择:单入口工作流,先交付独立目录。
- 官方 Skill 说明:<https://learn.chatgpt.com/docs/build-skills>,规划阶段已读取;本次复用已核实的 `SKILL.md`、相对参考文件与 UI 元数据结构。
- 不再分发原来的 8 个 Cursor 命令文件;其阶段语义纳入主入口与相应参考文档。
- 不增加运行时脚本、MCP 或项目依赖;技能按需使用宿主实际可用工具。
## 有效计划与分层 TODO
- [x] 1 工作流适配(完成)。验收:13 个独立技能文件齐备,原始目录不变,静态检查通过,未安装与未实测范围已说明。
- [x] 1.1 主入口、八阶段路由与 UI 元数据(完成)。证据:V1、V2、V4;统一调用语法与阶段文档映射正确,自动匹配使用默认启用策略。
- [x] 1.2 11 份参考文档与宿主权限、授权恢复规则(完成)。证据:V2、V3、S1–S12;保留阶段边界、分层 TODO 与任务恢复机制。
- [x] 1.3 结构、元数据、引用、内容保留和原始文件检查(完成)。证据:V1–V5;原始 20 个文件全部未变。
- [x] 1.4 八阶段及授权、只读宿主、恢复场景静态走查与交付(完成)。证据:S1–S12;独立文件与调用示例齐备,技能安装与真实触发不计入本次完成范围。
- [x] 2 安装到当前项目并验证发现(完成)。验收:安装文件与交付版本一致,本机 Codex 对当前路径返回已启用的项目级技能。证据:V6、V7;后续授权不包含修改用户级配置或运行业务任务。
- [x] 3 迁移为独立项目并清理 QuQ(完成)。验收:47 个已有文件完整迁移,独立项目中的技能可发现,QuQ 不再加载该技能且无相关文件残留。证据:V8–V10。
- [x] 4 改名为 SB-Workflow 并重新安装到 QuQ(完成)。验收:独立项目、技能标识、显示名称、调用示例和阶段标记一致;QuQ 与独立项目均能发现并启用 `sb-workflow`,不再发现旧的 `fd-engineering` 入口。证据:V11–V13。
- [x] 5 建立项目私有远端仓库(完成)。验收:已有 47 个文件提交并推送到 `main`,远端提交和文件哈希与本地一致。证据:V14。
- [x] 6 完善标准仓库信息(完成)。验收:安装与用法清晰,协作、更新、来源和格式约定齐备,静态检查与远端核验通过。证据:V15–V17。
- [x] 6.1 补齐根目录文档与 Git、编辑器约定(完成)。验证:59 处 Markdown 本地链接有效,源与副本的 13 个文件一致,原始快照保持原样,14 个忽略规则样例及 `git diff --check` 通过。证据:V15。
- [x] 6.2 更新 Gitea 简介和主题标签并完成交付(完成)。验证:Gitea Markdown 渲染、简介与 5 个主题标签、推送后的远端提交及 54 个文件哈希均核验通过。证据:V16、V17。
## 验证证据
- 初始环境检查:系统 Python 3.13.18 与内置工作区 Python 均缺少 `yaml` 模块。最终通过现有 `uv` 的隔离临时运行环境加载 PyYAML 6.0.3 完成校验,没有向项目、系统 Python 或交付技能添加运行时依赖。
- V1:外层执行 `uv run --no-project --python D:\DevTools\Python313\python.exe --with PyYAML python -X utf8 -`,从标准输入运行审计代码。审计代码通过该解释器的子进程实际调用 skill-creator 的 `scripts/quick_validate.py` 检查交付目录,退出码为 0,输出 `Skill is valid!`。
- V2:同一审计检查通过。交付目录恰好包含 13 个文件(`SKILL.md`、11 份参考文档、`agents/openai.yaml`);44 处本地 Markdown 引用全部指向包内存在的文件;无旧命令 `/FD-*`、Cursor 路径、旧命令模板相对路径或开发机绝对路径残留。
- V3:逐份比较 11 份参考文档与规范化调用语法后的源文件。6 份仅调用语法变化;5 份(workflow、research、plan、execute、task-record)增加或修正单入口、宿主权限、计划展示、工具与持久化兼容说明。UIUX、TODO、Grill、审查、交付与提交说明的既有业务规则保留。主入口的六项工程约束与原文逐字一致;8 个固定中文阶段标记全部保留。
- V4:YAML 解析与约束检查通过。3 个 UI 字符串均使用引号,简短描述符合 25–64 字符范围,默认提示包含 `$fd-engineering`。未配置关闭隐式调用的策略,自动匹配保持默认启用;未声明外部工具依赖。八阶段路由与各自参考文档映射检查通过。
- V5:按适配前记录的 SHA-256 逐项比较源目录,20 个文件的相对路径、数量和哈希全部一致。
- V6:后续安装到当前项目 `.agents/skills/fd-engineering`。安装前不存在同名目标目录;复制后 13 个文件的相对路径、数量和 SHA-256 与独立交付版本全部一致。
- V7:使用本机 Codex 可执行文件生成的协议 Schema 核对参数后,启动临时、独立的本地 app-server,以当前目录请求 `skills/list`,参数为 `cwds: ["D:\\Project\\QuQ"]`、`forceReload: true`。实际返回 `name: fd-engineering`、`scope: repo`、`enabled: true`、`path: D:\Project\QuQ\.agents\skills\fd-engineering\SKILL.md`、`interface.displayName: FD 工程工作流`,该技能无解析错误。检查未启动模型回合或新建聊天,检查结束后关闭了本次启动的 app-server 进程。
- V8:迁移前对交付技能 13 个文件、原始参考 20 个文件、项目级安装 13 个文件及任务记录 1 个文件建立清单,共 47 个文件。预先核对源路径属于 QuQ、目标路径属于 `D:\Project\codex-workflow`,确认目标不存在、源目录无符号链接或目录联接。批量搬迁命令被自动审批拦截且未执行,随后改为逐个明确路径移动。移动后、更新本迁移记录前,全量 47 个文件的 SHA-256 与迁移前清单一致。
- V9:从独立项目启动临时本地 Codex app-server,对 QuQ 和独立项目同时请求 `skills/list`,使用 `forceReload: true`。实际结果:QuQ 的 `fd-engineering` 数量为 0;独立项目数量为 1,路径为 `D:\Project\codex-workflow\.agents\skills\fd-engineering\SKILL.md`,`scope: repo`、`enabled: true`,无该技能解析错误。检查结束后关闭了本次启动的进程,未启动模型回合。
- V10:移走文件后仅删除 QuQ 中已确认为空的 `.agents/skills`、`.agents` 和 `.tasks` 目录。最终 QuQ 仅剩迁移前已存在且受保护的 `Chiaki` 与 `SnowLuma-v2.4.2-win-x64-lite` 两个目录;`codex-workflow`、`fd-engineering`、`.agents` 和 `.tasks` 均无残留。
- V11:本轮开始时确认 QuQ 未安装 workflow。随后将独立项目重命名为 `D:\Project\SB-Workflow`,适配技能和独立项目安装目录改名为 `sb-workflow`,本记录改名为 `.tasks/sb-workflow.md`。运行文档中的调用名统一为 `$sb-workflow`,显示名称为 `SB-Workflow`,八个阶段标记改用 `[SB:...]`;原始参考目录的 20 个文件 SHA-256 全部未变。
- V12:再次实际运行 skill-creator 的 `quick_validate.py`,输出 `Skill is valid!`。源技能、独立项目安装、QuQ 安装各 13 个文件,三份 SHA-256 清单一致;44 处本地引用有效,八阶段路由和八个阶段标记齐全,六项工程约束原文保持一致。运行文档中无旧技能名或 FD 品牌残留,隐式调用保持默认启用。
- V13:通过本机 Codex app-server 对 `D:\Project\QuQ` 与 `D:\Project\SB-Workflow` 同时请求 `skills/list`,使用 `forceReload: true`。两处均返回唯一的 `name: sb-workflow`、`scope: repo`、`enabled: true`、`interface.displayName: SB-Workflow`,默认提示包含 `$sb-workflow`,路径指向各自的 `.agents/skills/sb-workflow/SKILL.md`。两处旧名称数量均为 0,无相关解析错误;检查后关闭了临时进程,未启动模型回合。
- V14:按后续建仓授权,将已有 47 个文件作为初始提交 `77def46c5fe840cd2660272d87ce95f88566ea00` 推送至私有 Gitea 仓库 `FuDie0915/SB-Workflow`。Git 远端引用、Gitea 分支 API 和文件树核验一致,默认分支为 `main`,本地跟踪 `origin/main`;认证配置仅保存于本项目 Git 元数据。
- V15:本轮新增 7 个根目录文件:README、CONTRIBUTING、CHANGELOG、NOTICE、`.gitignore`、`.gitattributes` 和 `.editorconfig`。通过一次性 Python 标准库检查:新增文档及技能源中的 59 处本地 Markdown 链接有效,README 目录锚点有效,7 个新文件均为 UTF-8 与 LF;14 个忽略规则样例符合预期,`.env.example`、技能、安装副本和维护记录不被忽略。源与安装副本各 13 个文件的 SHA-256 一致;除本维护记录外,原有 46 个文件的字节内容与初始 Git 快照一致,其中包含原始参考的 20 个文件。README 的 PowerShell 安装示例通过语法解析;本轮未实际安装到其他项目。`git diff --check` 和暂存差异检查均通过。
- V16:安装目录与发现说明核对了 [OpenAI 官方 Skills 文档](https://learn.chatgpt.com/docs/build-skills)。通过本机 Gitea 的 Markdown API 渲染 README,确认 10 个标题、1 个阶段表格、5 个代码块及页面内锚点结构正常。Gitea 简介已更新,主题标签为 `agent-skills`、`codex`、`documentation`、`engineering`、`workflow`;私有状态与 `main` 默认分支保持不变。本轮未选择开源许可证,来源及当前许可状态写入 NOTICE。
- V17:文档提交 `3dcc970256887153d06584bd3eeac0b86a7350d0` 已推送。Git 远端引用与 Gitea 分支 API 对应同一提交;Gitea 文件树中的 54 个文件路径和 blob SHA 与本地提交完全一致,远端 README 解码后的字节内容与本地文件相同。本轮只完善文档、格式约定与仓库元数据,不涉及技能行为修改或真实模型运行验证。
## 初版规则静态走查
下表保留改名前 `fd-engineering` 版本的场景记录。当前入口已统一更名为 `$sb-workflow`,阶段职责和授权边界不变;本轮重命名及安装验证见 V11–V13。场景走查检查的是指令覆盖与一致性,没有向另一个 Codex 会话发送这些提示,也不证明实际模型会按预期触发或执行。
| 编号 | 场景 | 文档规定的阶段与行为 | 走查结论 |
|---|---|---|---|
| S1 | `$fd-engineering 研究这个项目` | RESEARCH:调查入口、复用能力、事实和未知项,不进行业务实现 | 已覆盖 |
| S2 | `$fd-engineering 质询这个方案中的关键决策` | GRILL:先调查事实,每轮解决一个关键决策;回答不等于批准实现 | 已覆盖 |
| S3 | `$fd-engineering 规划这个需求` | PLAN:输出可审阅计划、分层 TODO 与验收;不自动实现 | 已覆盖 |
| S4 | `$fd-engineering 为这个页面设计原型` | UIUX:核实需求与参考范围、确认简报和候选数量后制作隔离原型;生产实现仍需授权 | 已覆盖 |
| S5 | `$fd-engineering 执行当前计划`,计划明确且有批准、宿主可写 | EXECUTE:核对计划版本与真实文件,连续实施、验证和自检 | 已覆盖 |
| S6 | `$fd-engineering 审查当前修改` | REVIEW:基于真实差异和证据报告问题,不自动修复源码、暂存或提交 | 已覆盖 |
| S7 | `$fd-engineering 为这个项目制定打包交付方案` | DEVOPS:先研究与规划;已授权时推进对应本地工作,外部操作需明确意图 | 已覆盖 |
| S8 | `$fd-engineering 生成提交说明` | COMMIT:从真实差异起草中文说明,不自动暂存、提交、推送或初始化仓库 | 已覆盖 |
| S9 | 要求执行,但没有可用已批准计划,且不符合小改动快速路径 | 转入 PLAN 完成前置规划,不把执行请求当作任意实现授权 | 已覆盖 |
| S10 | 用户已提供完整计划并明确要求实施 | 复用该计划与批准,不重复索取同一授权;照常核对宿主权限 | 已覆盖 |
| S11 | 宿主处于只读 Plan mode,即使已有实施批准 | 仅做宿主允许的调查与规划;禁止的文件写入保持待执行,批准保留在对话中 | 已覆盖 |
| S12 | 恢复已有复杂任务,部分检查已过期或存在其他用户修改 | 按明确选定的记录核对计划、批准、TODO、实际文件与证据;过期检查重新验证,保护无关改动 | 已覆盖 |
## 剩余风险与交付结论
本次独立目录适配已完成,结构、引用、内容保留与原始目录完整性检查通过,12 个规则场景已静态走查。调用示例位于交付技能的主入口路由表。
当前独立项目为 `D:\Project\SB-Workflow`,技能显示名称为 `SB-Workflow`,实际调用入口为 `$sb-workflow`。按本轮明确授权,QuQ 与独立项目均已安装并通过本机 Codex 的项目级发现、启用状态及 UI 元数据检查;旧入口已替换。原始参考、适配技能和维护记录仍保留在独立项目。
隐式触发、真实模型阶段选择、真实业务执行和当前桌面聊天的 UI 刷新尚未实测;这些项目不作为已通过项。文档约束依赖实际宿主和模型执行,静态校验及技能发现不等于运行时行为保证。
后续仓库交付已完成:私有远端、README、贡献指南、更新记录、来源与许可状态、Git 与编辑器约定,以及 Gitea 简介与主题标签均已补齐,相关静态检查和远端文件核验见 V14–V17。原始适配与安装证据保留为历史记录。