@aibyzero/byz 0.1.1 → 0.1.3

package/workflows/cm-plugin/skills/codebase-context/SKILL.md

@@ -0,0 +1,489 @@
+---
+name: codebase-context
+description: 项目代码库上下文管理。通读项目生成参考文档(scan)，或加载文档辅助开发(dev)。
+trigger: manual
+metadata:
+  argument-hint: "<scan|dev> [project-name] [--full]"
+---
+
+# codebase-context — 项目代码库上下文管理
+
+这是一份写给 AI 执行的 SOP。目的：把"每次开发前重读整个代码库"这个昂贵动作**一次性固化成结构化文档缓存**，后续开发直接加载文档当上下文。
+
+- **scan（生产）**：系统通读源码，生成结构化参考文档。
+- **dev（消费）**：加载参考文档进上下文辅助开发，开发完成后自动评估并回写更新文档。
+
+## 参数解析
+
+调用格式：`/codebase-context <mode> [project-name] [--full]`
+
+1. 解析第一个参数为 `mode`：
+   - 值为 `scan` → 进入 scan 模式
+   - 值为 `dev` → 进入 dev 模式
+   - 缺失或为其他值 → 输出用法提示 `用法: /codebase-context <scan|dev> [project-name] [--full]` 并终止
+2. 解析第二个非 `--` 开头参数为 `project-name`：
+   - 已提供 → 直接使用
+   - 未提供 → 用 Bash 执行 `basename "$PWD"`，取当前工作目录最后一段路径名作为 project-name
+3. 检查是否存在 `--full` 参数：
+   - 存在且 mode=scan → 强制全量扫描
+   - 存在且 mode=dev → 忽略该参数并提示"--full 仅 scan 模式有效"
+4. 设定文档目录 `DOC_DIR = {PROJECT_ROOT}/docs/codebase-context/`（存于项目工程内,随 git 提交、团队共享、换机不丢）
+5. 设定项目根 `PROJECT_ROOT = 当前工作目录`
+
+## 产物清单（固定 10 份文档 + 1 份元数据）
+
+全部存于 `DOC_DIR` 下，文件名固定，不得增删改名：
+
+| 文件 | 内容 |
+| ---- | ---- |
+| 00-index.md | 索引与快速导航 |
+| 01-overview.md | 项目概述与技术栈 |
+| 02-directory.md | 目录结构 |
+| 03-architecture.md | 架构设计与模块关系 |
+| 04-api-routes.md | API 接口汇总 |
+| 05-data-models.md | 数据模型与类型 |
+| 06-core-modules.md | 核心模块（组件/Hooks/Store） |
+| 07-business-logic.md | 关键业务逻辑 |
+| 08-conventions.md | 编码规范与约定 |
+| 09-changelog.md | 文档变更记录 |
+| .scan-meta.json | `{"lastScanTime":"UTC时间","scanType":"full|incremental","projectRoot":"绝对路径"}` |
+
+---
+
+## scan 模式流程
+
+### 步骤 1：初始化
+
+1. 按参数解析规则推导 project-name
+1.5 **多项目仓库检测（禁止扫仓库根）**：用 Glob 匹配 `*/package.json`、`*/*/package.json`（及 Cargo.toml/go.mod 等）——若当前目录自身不是单一项目根（无 src/），而多个子目录各含项目描述文件 → **列出候选子项目并让用户选定**（或用 project-name 参数匹配子目录名）；选定后 `PROJECT_ROOT`/`DOC_DIR` 重设为该子项目根。把多个不相干项目扫进一张地图，查重与波及面全部失真——**脏地图比没地图更危险**（实跑教训：4 项目混装仓库靠人肉 cd 才扫对）
+2. 设定 DOC_DIR
+3. 判断扫描模式（分支条件显式如下）：
+   - DOC_DIR 不存在 → **全量扫描**
+   - 带 `--full` 参数 → **全量扫描**
+   - DOC_DIR 已存在 且 存在 `.scan-meta.json` 且 无 `--full` → **增量扫描**
+   - DOC_DIR 已存在 但 缺 `.scan-meta.json` → **全量扫描**（元数据缺失视同首扫）
+4. 用 Bash 执行 `mkdir -p {DOC_DIR}` 创建目录
+
+### 全量扫描
+
+#### 步骤 2a：系统读取代码（分 7 轮，每轮用 Glob/Grep/Read）
+
+**规模档位（先数源码文件再动手）**：≤200 个源文件 → 按下述七轮正常执行；**>200 个** → 第 4/5/6 轮不逐个 Read，改用 Grep 收 export 签名清单入表（函数名/类型名/位置），精读仍限抽样 3–5 个最复杂文件；**>500 个** → 同上，并提示用户"项目较大，建议按模块分次 scan（cd 到子模块根分别执行）"。防止扫到一半上下文耗尽——成本花了、地图没产出是最差结果。
+
+**第 1 轮 项目元信息**：用 Read 读取 `package.json`、`README.md`；用 Glob 匹配构建配置 `vite.config.*`、`webpack.config.*`、`tsconfig.json`、`next.config.*`、`.env.example`，逐个 Read。提取：项目名/版本/依赖清单/脚本命令/构建工具/环境变量键名。
+
+**第 2 轮 目录结构**：用 Bash 执行 `ls -R`（或用 Glob `src/*/*` 展开 src 两层）。识别 `pages/`、`components/`、`api/`、`store/`、`hooks/`、`utils/`、`types/` 等目录及其职责。
+
+**第 3 轮 入口与路由**：用 Glob 定位 `main.*`、`index.*`、`App.*`、`router/`、`routes/`，逐个 Read；用 Grep 搜索全局 store 初始化与全局 service 入口。提取：启动链路、路由表、全局状态挂载点。
+
+**第 4 轮 API 接口层**：用 Glob 匹配 `**/api/**` 与 `**/services/**`，逐个 Read。提取每个接口函数的：函数名 / HTTP 方法 / URL / 参数 / 返回类型 / 定义位置（文件:函数）。
+
+**第 5 轮 数据模型与类型**：用 Glob 匹配 `**/types/**`、`**/models/**`、`**/interfaces/**`、`**/enums/**`，逐个 Read。提取：实体 / 枚举 / DTO 及各自定义位置。
+
+**第 6 轮 核心模块**：用 Glob 展开 `components/`（区分公共组件 vs 业务组件）、`hooks/`、`store/`，逐个 Read 提取签名与职责；再用 Grep 按 import 次数与文件行数**抽样精读 3–5 个最复杂的页面/组件**（Read 全文），提取其状态、关键流程。
+
+**第 7 轮 规范与工具**：用 Glob 匹配 `**/constants/**`、`**/config/**`、`**/utils/**` 及 `.eslintrc*`、`.prettierrc*`，逐个 Read。提取：常量清单 / 工具函数清单 / 可推断的代码规范。
+
+#### 步骤 3a：生成文档
+
+依据下方【文档模板】，按 00 → 09 顺序逐份用 Write 生成 10 份文档，照模板填空。
+
+#### 步骤 4a：写元数据与摘要
+
+1. 用 Bash 执行 `date -u +"%Y-%m-%dT%H:%M:%SZ"` 取 UTC 时间
+2. 用 Write 写 `.scan-meta.json`：`{"lastScanTime":"{UTC}","scanType":"full","projectRoot":"{PROJECT_ROOT}"}`
+3. 输出终端摘要：
+
+```text
+✅ codebase-context 全量扫描完成 — {project-name}
+📁 文档目录: {DOC_DIR}
+📄 生成文档: 10 份（00-index ~ 09-changelog）
+📊 扫描统计: 接口 {N} 个 | 类型 {N} 个 | 组件 {N} 个 | Hooks {N} 个 | 精读页面 {N} 个
+▶ 开发时执行: /codebase-context dev {project-name}
+```
+
+### 增量扫描
+
+#### 步骤 2b：变更检测
+
+1. 用 Read 读 `.scan-meta.json`，取 `lastScanTime` 与 `projectRoot`
+2. 用 Bash 执行：
+
+```bash
+find {projectRoot}/src -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.vue" -o -name "*.json" \) -newer {DOC_DIR}/.scan-meta.json
+```
+
+3. 将结果与 `02-directory.md` 记录的文件清单对比，推断**新增文件**（结果里有、文档里无）与**删除文件**（文档里有、磁盘上无——用 Bash `test -f` 验证）
+4. 若变更文件数为 0 且无新增/删除 → 输出 `📭 自上次扫描({lastScanTime})以来无变更，文档已是最新` 并**结束**
+
+#### 步骤 3b：确定受影响轮次（映射表）
+
+按下表将每个变更文件路径映射到扫描轮次，**只重跑受影响的轮次**：
+
+| 文件路径模式 | 扫描轮次 | 需更新文档 |
+| ---- | ---- | ---- |
+| package.json / README / vite・webpack・tsconfig・next 配置 / .env.example | 第 1 轮 | 01-overview |
+| 目录新增/删除（任何路径层级变化） | 第 2 轮 | 02-directory |
+| main.* / index.* / App.* / router/ / routes/ / 全局 store・service 入口 | 第 3 轮 | 03-architecture |
+| \*\*/api/\*\* 、 \*\*/services/\*\* | 第 4 轮 | 04-api-routes |
+| \*\*/types/\*\* 、 \*\*/models/\*\* 、 \*\*/interfaces/\*\* 、 \*\*/enums/\*\* | 第 5 轮 | 05-data-models |
+| components/ 、 hooks/ 、 store/ | 第 6 轮 | 06-core-modules |
+| pages/ 下的页面文件 | 第 6 轮 | 06-core-modules、07-business-logic |
+| \*\*/constants/\*\* 、 \*\*/config/\*\* 、 \*\*/utils/\*\* 、 eslint/prettier 配置 | 第 7 轮 | 08-conventions |
+| （任何变更，无条件） | — | 09-changelog、00-index（日期） |
+
+#### 步骤 4b：增量合并
+
+1. 用 Read 读取受影响的现有文档（只读需更新的那几份）
+2. 用 Read **只读变更文件**（不重读全库）
+3. 用 Edit 增量合并，禁止全量覆盖：
+   - 新增内容 → 在对应章节**追加**行/条目
+   - 修改内容 → **替换**对应行/条目
+   - 删除文件涉及的条目 → **移除**对应行/条目
+
+#### 步骤 5b：收尾更新
+
+1. 用 Edit 更新 `00-index.md` 的"最后更新"日期
+2. 用 Edit 在 `09-changelog.md` 追加本次条目（日期/类型 incremental/变更摘要/涉及文档）
+3. 用 Bash 取 UTC 时间，用 Write 更新 `.scan-meta.json`（`scanType: "incremental"`）
+
+#### 步骤 6b：输出变更检测摘要
+
+```text
+✅ codebase-context 增量扫描完成 — {project-name}
+🔍 变更检测: 新增 {N} 个 | 修改 {N} 个 | 删除 {N} 个
+📄 已更新文档: {文档列表，如 04-api-routes、05-data-models、09-changelog、00-index}
+```
+
+---
+
+## dev 模式流程
+
+### 步骤 1：加载
+
+1. 按参数解析规则推导 project-name，设定 DOC_DIR
+2. 分支判断：
+   - DOC_DIR 不存在 或 缺少 00-index.md → 输出 `⚠ 未找到 {project-name} 的参考文档。请先执行: /codebase-context scan {project-name}` 并**结束**
+   - 文档齐全 → 继续
+3. 按 00 → 09 顺序用 Read 读取全部 10 份文档进上下文
+4. 输出已加载确认（一句话概要从 01-overview.md 的"项目定位"提取）：
+
+```text
+📚 已加载 {project-name} 参考文档（10 份，最后更新 {日期}）
+📌 项目概要: {01-overview 提取的一句话}
+```
+
+### 步骤 2：辅助开发
+
+开发过程中强制遵循：
+
+1. 编码风格遵循 `08-conventions.md` 的规范与约定
+2. 调用接口前先查 `04-api-routes.md`——**已有接口直接复用，不重复造**
+3. 定义类型前先查 `05-data-models.md`——**已有类型直接引用，不重复定义**
+4. 写组件/Hook 前先查 `06-core-modules.md`——**已有组件/Hook 直接复用**
+5. 新代码放置位置参考 `03-architecture.md` 的分层与模块归属
+
+### 步骤 3：开发完成后强制评估回写
+
+开发结束时**必须**执行本步骤，按下表评估本次变更需要更新哪些文档：
+
+| 变更类型 | 需更新文档 |
+| ---- | ---- |
+| 新增/修改/删除 API 调用 | 04-api-routes |
+| 新增/修改/删除 类型・实体・枚举 | 05-data-models |
+| 新增/修改 组件・Hook・Store 模块 | 06-core-modules |
+| 修改业务流程・新增业务规则 | 07-business-logic |
+| 新增/删除 目录或文件结构变化 | 02-directory |
+| 架构调整（新模块/依赖方向变化/新分层） | 03-architecture |
+| 新增依赖/修改构建配置/新增环境变量 | 01-overview |
+| 引入新的编码约定/常量/工具函数 | 08-conventions |
+| （任何以上更新发生时，无条件） | 09-changelog 追加条目、00-index 更新日期 |
+
+更新方式：用 Edit 直接编辑对应文档的对应章节（新增追加/修改替换/删除移除），随后用 Edit 在 09-changelog 追加条目（类型标 `dev回写`）、更新 00-index 日期。若评估结果为"无需更新任何文档"，在回复中显式说明"本次变更不影响参考文档"。
+
+---
+
+## 文档模板
+
+生成时照模板填空；某章节在本项目无对应内容时保留标题并填"本项目未发现此类文件"。
+
+### 00-index.md
+
+````markdown
+# {project-name} — 代码库参考文档索引
+
+- 最后更新: {YYYY-MM-DD HH:MM UTC}
+- 扫描类型: {full | incremental}
+- 项目根: {projectRoot}
+
+## 文档导航
+
+| 文档 | 内容 | 什么时候看 |
+| ---- | ---- | ---- |
+| 01-overview | 项目概述与技术栈 | 初次接触项目 |
+| 02-directory | 目录结构 | 找文件放哪/在哪 |
+| 03-architecture | 架构与模块关系 | 新代码归属、理解依赖方向 |
+| 04-api-routes | API 接口汇总 | 调接口前查重 |
+| 05-data-models | 数据模型与类型 | 定义类型前查重 |
+| 06-core-modules | 组件/Hooks/Store | 写组件前查复用 |
+| 07-business-logic | 关键业务逻辑 | 改业务流程前看线路 |
+| 08-conventions | 编码规范与约定 | 动手写代码前 |
+| 09-changelog | 文档变更记录 | 追溯文档演进 |
+
+## 快速定位
+
+| 我想找… | 去 |
+| ---- | ---- |
+| 某个接口怎么调 | 04-api-routes |
+| 某个字段的类型定义 | 05-data-models |
+| 有没有现成组件/Hook | 06-core-modules |
+| 某业务流程的完整线路 | 07-business-logic |
+| 命名/风格规矩 | 08-conventions |
+````
+
+### 01-overview.md
+
+````markdown
+# 项目概述与技术栈
+
+## 项目定位
+
+{一句话说明这个项目是什么、给谁用、解决什么问题}
+
+## 技术栈
+
+| 层 | 技术 | 版本 |
+| ---- | ---- | ---- |
+| 语言 | {TypeScript/…} | {x.y} |
+| 框架 | {React/Vue/…} | {x.y} |
+| 构建 | {Vite/Webpack/…} | {x.y} |
+| 状态管理 | {…} | {x.y} |
+| 其他关键依赖 | {…} | {x.y} |
+
+## 脚本命令
+
+| 命令 | 作用 |
+| ---- | ---- |
+| `npm run dev` | {…} |
+| `npm run build` | {…} |
+| `npm run test` | {…} |
+
+## 环境变量（仅键名与用途，不含值）
+
+| 键 | 用途 | 来源 |
+| ---- | ---- | ---- |
+| {ENV_KEY} | {…} | .env.example |
+````
+
+### 02-directory.md
+
+````markdown
+# 目录结构
+
+## 目录树（src 两层）
+
+```text
+src/
+├── pages/          # {职责}
+├── components/     # {职责}
+├── api/            # {职责}
+├── store/          # {职责}
+├── hooks/          # {职责}
+├── utils/          # {职责}
+└── types/          # {职责}
+```
+
+## 目录职责
+
+| 目录 | 职责 | 典型文件 |
+| ---- | ---- | ---- |
+| {src/pages} | {…} | {…} |
+
+## 文件清单（供增量扫描对比新增/删除）
+
+| 文件 | 所属轮次 |
+| ---- | ---- |
+| {src/api/user.ts} | 4 |
+````
+
+### 03-architecture.md
+
+````markdown
+# 架构设计与模块关系
+
+## 分层结构
+
+```text
+{页面层 pages}
+    ↓ 调用
+{逻辑层 hooks / store}
+    ↓ 调用
+{服务层 api / services}
+    ↓ 请求
+{后端 / 云函数}
+```
+
+## 启动链路
+
+{main.* → App.* → 路由挂载 → 全局 store 初始化，逐步说明，每步带 文件:位置}
+
+## 路由表
+
+| 路径 | 页面 | 定义位置 |
+| ---- | ---- | ---- |
+| {/home} | {pages/home} | {router/index.ts} |
+
+## 模块依赖关系
+
+| 模块 | 依赖谁 | 被谁依赖 |
+| ---- | ---- | ---- |
+| {store/user} | {api/user} | {pages/*, hooks/useAuth} |
+````
+
+### 04-api-routes.md
+
+````markdown
+# API 接口汇总
+
+## {模块名，如 user}
+
+| 函数名 | 方法 | URL | 参数 | 返回类型 | 定义位置 |
+| ---- | ---- | ---- | ---- | ---- | ---- |
+| {getUser} | GET | {/api/user/:id} | {id: string} | {User} | {src/api/user.ts} |
+
+（按模块分节重复上表；无 api/ 与 services/ 目录时填"本项目未发现此类文件"）
+````
+
+### 05-data-models.md
+
+````markdown
+# 数据模型与类型
+
+## 实体
+
+| 名称 | 字段摘要 | 定义位置 | 主要使用方 |
+| ---- | ---- | ---- | ---- |
+| {User} | {id, name, role…} | {src/types/user.ts} | {api/user, store/user} |
+
+## 枚举
+
+| 名称 | 取值 | 定义位置 |
+| ---- | ---- | ---- |
+| {OrderStatus} | {pending/paid/closed} | {src/types/order.ts} |
+
+## DTO / 请求响应类型
+
+| 名称 | 用于接口 | 定义位置 |
+| ---- | ---- | ---- |
+| {CreateOrderReq} | {POST /api/order} | {src/types/dto.ts} |
+````
+
+### 06-core-modules.md
+
+````markdown
+# 核心模块
+
+## 公共组件
+
+| 组件 | Props 摘要 | 定义位置 | 复用场景 |
+| ---- | ---- | ---- | ---- |
+| {Button} | {type, onClick…} | {src/components/common/} | {全局} |
+
+## 业务组件
+
+| 组件 | 职责 | 定义位置 | 所属业务 |
+| ---- | ---- | ---- | ---- |
+
+## Hooks
+
+| 名称 | 输入 | 输出 | 定义位置 |
+| ---- | ---- | ---- | ---- |
+| {useAuth} | {—} | {user, login, logout} | {src/hooks/useAuth.ts} |
+
+## Store
+
+| 模块 | state 摘要 | 主要 actions | 定义位置 |
+| ---- | ---- | ---- | ---- |
+
+## 复杂页面精读（3–5 个）
+
+### {页面名}（{文件路径}）
+
+- 职责: {…}
+- 关键状态: {…}
+- 关键流程: {步骤 1 → 步骤 2 → …，每步带函数名}
+````
+
+### 07-business-logic.md
+
+````markdown
+# 关键业务逻辑
+
+## {业务线名，如：下单}
+
+**线路**：{页面 pages/order} → {hook useOrder} → {api createOrder} → {POST /api/order} → {模型 Order}
+（每个环节标注 文件:函数）
+
+**关键规则**：
+
+- {规则 1，如：金额用分存储，展示层才转元 —— src/utils/money.ts}
+- {规则 2}
+
+**边界与注意**：
+
+- {已知坑/特殊分支/兼容逻辑，带位置}
+
+（按业务线重复本节）
+````
+
+### 08-conventions.md
+
+````markdown
+# 编码规范与约定
+
+## 命名
+
+| 对象 | 规则 | 示例 |
+| ---- | ---- | ---- |
+| 组件文件 | {PascalCase} | {UserCard.tsx} |
+| hooks | {use 前缀} | {useAuth} |
+
+## 代码风格（自 ESLint/Prettier 推断）
+
+- {缩进/引号/分号/import 排序 等要点}
+
+## 常量
+
+| 常量 | 值/含义 | 定义位置 |
+| ---- | ---- | ---- |
+
+## 工具函数
+
+| 函数 | 用途 | 定义位置 |
+| ---- | ---- | ---- |
+
+## 其他约定
+
+- {错误处理方式/请求封装规则/目录放置约定}
+````
+
+### 09-changelog.md
+
+````markdown
+# 文档变更记录
+
+| 日期(UTC) | 类型 | 变更摘要 | 涉及文档 |
+| ---- | ---- | ---- | ---- |
+| {2026-07-14T08:00Z} | full | 首次全量扫描 | 全部 10 份 |
+| {…} | incremental | {新增 2 接口/修改 1 类型} | {04、05} |
+| {…} | dev回写 | {开发 xx 功能后回写} | {04、06、07} |
+````
+
+---
+
+## 错误处理
+
+1. **无 package.json**：项目根不存在 package.json → 输出 `⚠ 当前目录未发现 package.json，请确认 {PROJECT_ROOT} 是正确的项目目录（回复继续则按非 npm 项目扫描）`，等用户确认后再继续。
+2. **某轮目标目录不存在**（如无 `api/`）：跳过该轮，在对应文档的相应章节标注"本项目未发现此类文件"，不报错不中断。
+3. **超大文件（>1000 行）**：不复制全文，只用 Grep/Read 提取关键导出（export 的函数/类/类型签名），并在文档条目备注 `(大文件,仅提取签名)`。
+4. **dev 模式文档不存在**：明确引导 `请先执行: /codebase-context scan {project-name}`，不猜测、不凭记忆辅助开发。

package/workflows/cm-plugin/skills/darwin-skill/NOTICE.md

@@ -0,0 +1,24 @@
+# 来源与许可
+
+- 上游: https://github.com/alchaincyf/darwin-skill (master, 收编于 2026-07-15)
+- 许可: MIT(依据上游 README 徽章声明;上游仓库暂缺 LICENSE 文件,如上游补充以其为准)
+- 本地修改(仅 2 处,均为移植性修补,SKILL.md 未改一字):
+  1. scripts/screenshot.mjs: playwright-core 改为标准解析(原版写死作者机器绝对路径)
+  2. scripts/screenshot.mjs: open 命令加 macOS 平台判断(原版非跨平台)
+- 定位: 独立工具 skill(同 idea-to-prd/codebase-context),不属于 N1-N8 流程;
+  用途:对本仓库 skills/(含 cm-* 角色技能)做 9 维评分与受控优化,人类守关三层不可跳过
+
+# 本仓库使用注意(v0.9.25-26 实跑沉淀,SKILL.md 原样未改,以下为运行时补丁规则)
+
+1. **baseline 对照组必污染,勿用 A/B 对比**: 被测 skill 已装入会话的环境里,"不带 skill"
+   的对照子 agent 会因任务措辞匹配 description 而通过 Skill 工具自行加载它(实测 3/3
+   全污染;验证法: grep 子 agent transcript 中的 `"name":"Skill"` 调用)。dim8 改用两类
+   证据: ① 执行者逐条报告"skill 没写清、不得不猜的地方",歧义清单收敛度=改进度;
+   ② 夹具埋陷阱复测,看上轮违规行为是否被新规则挡住。
+2. **9 维 rubric 需叠加本仓库四原则**: 通用 rubric 可能把"实跑教训括号注"判为冗余——
+   它们在本仓库是防删护栏,评分时计入 dim5/dim7 加分项,优化时禁止删除。
+3. **cm-* skill 是强耦合网络**: 每轮改动后必须跑引用护栏(/cm-plugin:check 相关子集:
+   孤儿角色、rules 生成方、跨文件配对),PASSED 才算该轮有效——这是 darwin 棘轮
+   之外的本仓库附加回滚条件。
+4. **工程师类 skill 的 dim9 低分是架构使然**: 纪律按设计在 agents/*.md 层
+   ("agent 管纪律,skill 管技术"),勿按 rubric 给其 SKILL.md 补黑名单。