@hupan56/wlkj 2.3.4 → 2.4.0

package/templates/root//345/256/214/346/225/264/345/221/275/344/273/244/344/270/216/346/223/215/344/275/234/346/214/207/345/215/227.md

@@ -0,0 +1,630 @@
+# wlkj 工作流 —— 完整命令与操作指南
+
+> **版本**：`@hupan56/wlkj@2.3.3`
+> **适用**：Qoder IDE / Quest / QoderWork / 任何终端
+> **对象**：产品经理、开发者、新用户（不需要懂 git / Python）
+>
+> 本文档涵盖**从零安装到日常使用的全部命令和操作**。
+
+---
+
+## 目录
+
+1. [前置环境安装](#1-前置环境安装)
+2. [初始化](#2-初始化)
+3. [升级](#3-升级)
+4. [日常使用：在 Qoder 里](#4-日常使用在-qoder-里)
+5. [日常使用：在终端里](#5-日常使用在终端里)
+6. [代码搜索（10 种模式）](#6-代码搜索10-种模式)
+7. [PRD 生成（4 种模式 + 评估）](#7-prd-生成4-种模式--评估)
+8. [任务管理（13 个子命令）](#8-任务管理13-个子命令)
+9. [报告与导出](#9-报告与导出)
+10. [团队协作与冲突处理](#10-团队协作与冲突处理)
+11. [QoderWork 桌面端](#11-qoderwork-桌面端)
+12. [故障排查](#12-故障排查)
+13. [命令速查表](#13-命令速查表)
+
+---
+
+## 1. 前置环境安装
+
+### 1.1 只需装一样：Node.js
+
+`npx` 是 Node.js 自带的。没有 Node.js 跑不了 `npx`。
+
+| 系统 | 怎么装 |
+|------|--------|
+| **Windows** | 打开 https://nodejs.org → 下载 **LTS 版** → 双击安装，一路下一步 → **重新打开终端** |
+| **Mac** | `brew install node` 或去 nodejs.org 下载 .pkg |
+| **Linux** | `curl -fsSL https://deb.nodesource.com/setup_lts.x \| sudo -E bash - && sudo apt install -y nodejs` |
+
+验证：
+```bash
+node --version    # 看到 v20.x.x 或更高
+```
+
+> **注**：装完 Node.js **必须重新打开终端窗口**，否则 `npx` 命令找不到。
+
+### 1.2 自动装其余（Python + git）
+
+```bash
+npx @hupan56/wlkj install-env
+```
+> **作用**：检测并自动安装 Python（引擎需要）和 git（团队同步需要）。
+> 用 winget（Win）/ brew（Mac）/ apt（Linux）自动装。
+> **三个都已装** → 全部跳过，不做任何事。
+
+只检测不装：
+```bash
+npx @hupan56/wlkj install-env --check
+```
+> **输出**：`Node.js: [OK] v20.x` / `Python: [OK] 3.x` / `git: [OK] 2.x`
+> 三个 `[OK]` 就可以往下走了。
+
+### 1.3 装到非 C 盘（可选）
+
+```bash
+npx @hupan56/wlkj install-env --location D:\wldev
+```
+> **作用**：尝试把三个软件装到 D:\wldev。
+> **注意**：winget 的 --location 对 Python 不一定生效。如果没装到指定目录，
+> 手动去官网下载安装包选目录，然后用 add-path 加进 PATH。
+
+### 1.4 手动加 PATH
+
+```bash
+npx @hupan56/wlkj add-path D:\wldev\nodejs
+npx @hupan56/wlkj add-path D:\wldev\Python312
+```
+> **作用**：把目录加到系统 PATH（幂等，重复跑不会加两次）。
+> 跑完**重新打开终端**生效。
+
+---
+
+## 2. 初始化
+
+### 2.1 一键安装（新用户必跑）
+
+```bash
+mkdir my-project        # 建一个空文件夹
+cd my-project           # 进去
+npx @hupan56/wlkj init 你的名字
+```
+> **作用**：一键完成以下全部：
+> 1. 拷贝完整引擎（.qoder/ 全部脚本 + 技能 + 命令 + 规则 + 模板）
+> 2. 建 workspace / data 目录结构
+> 3. git init（如果没有）
+> 4. 写 .gitignore（保护敏感文件不提交）
+> 5. **注册身份**（写 member.json + 生成签名密钥 → push 门禁的前提）
+> 6. **配 git**（检测 git config，没配就用你的名字设 local）
+> 7. clone 代码仓库（Carmg-H5 / fywl-ics / fywl-ui）
+> 8. 建知识图谱（14000+ 文件索引）
+> 9. 写版本戳
+>
+> **耗时**：首次约 3-5 分钟（clone 大仓库 + 建索引）。之后秒级。
+> **幂等**：可以重复跑，不会覆盖你已有的草稿和任务。
+
+### 2.2 验证初始化
+
+```bash
+npx @hupan56/wlkj status
+```
+> **预期输出**：
+> ```
+> dev: 你的名字
+> Current task: (none)
+> PRDs: 0
+> engine: 2.3.3 (最新: v2.3.3) [最新]
+> ```
+
+### 2.3 切换开发者（同一台机器换人用）
+
+```bash
+npx @hupan56/wlkj init 另一个人的名字
+```
+> **作用**：更新 `.developer` 文件，切换身份。
+> 会自动清除上一个开发者的活跃任务指针（防误操作）。
+
+### 2.4 环境体检
+
+```bash
+python .qoder/scripts/init_doctor.py
+```
+> **作用**：9 段检查：
+> 1. 基础环境（Python / git）
+> 2. 开发者身份
+> 3. 团队仓库同步
+> 4. 源码仓库（data/code/）
+> 5. 知识图谱（data/index/）
+> 6. 风格约束
+> 7. PRD 模板 + Qoder 载体
+> 8. 周五自动构建
+> 9. QoderWork 技能
+
+自动修复：
+```bash
+python .qoder/scripts/init_doctor.py --fix
+```
+
+---
+
+## 3. 升级
+
+### 3.1 已装用户升级（新版本发布后）
+
+```bash
+npx @hupan56/wlkj update
+```
+> **作用**：
+> - 刷新所有引擎文件（.py / .md / .html）
+> - **保护 config.yaml**（你的团队 git URL 不动）
+> - **保护 settings.json**（你的权限配置不动）
+> - 强制刷新 QoderWork commands
+> - 写入新版本号
+>
+> **不碰**：.developer / .current-task / workspace/ / data/ 业务数据
+>
+> 跑完**重启 Qoder / 新建对话**生效。
+
+### 3.2 检查是否最新
+
+```bash
+npx @hupan56/wlkj status
+```
+> 如果落后会显示：`engine: 2.2.0 (最新: v2.3.3) [可升级: npx @hupan56/wlkj update]`
+
+---
+
+## 4. 日常使用：在 Qoder 里
+
+### 4.1 斜杠命令（输 `/` 就看到）
+
+| 命令 | 做什么 | 自动确认 |
+|------|--------|---------|
+| `/wl-init` | 初始化 / 切换开发者 | ✅ |
+| `/wl-prd` | 生成 PRD + 原型 | ✅ |
+| `/wl-search` | 搜代码 / API / 字段 / PRD / Wiki | ✅ |
+| `/wl-task` | 任务管理 | ✅ |
+| `/wl-status` | 项目健康度 + 进度 | ✅ |
+| `/wl-spec` | 从 PRD 生成技术规格 | ✅ |
+| `/wl-report` | 日报 / 周报 | ✅ |
+| `/wl-insight` | 反馈分析 + 指标回顾 | ✅ |
+| `/wl-code` | 按 Spec 写代码 | ⚠️ 需确认 |
+| `/wl-test` | 写单元测试 | ⚠️ 需确认 |
+| `/wl-commit` | 提交代码 + push | ⚠️ 需确认 |
+
+### 4.2 自然语言（最推荐，不用记命令）
+
+| 你说什么 | 触发什么 |
+|---------|---------|
+| "写个 XX 的需求" | PRD + 原型生成 |
+| "查一下 XX 代码在哪" | 代码搜索 |
+| "建个任务，优先级高" | 任务创建 |
+| "项目进度怎么样" | 项目状态 |
+| "写个日报" | 日报生成 |
+| "生成规格" | Spec 生成 |
+| "开始写代码" | 代码实现 |
+| "写单元测试" | 测试生成 |
+| "提交代码" | git commit + push |
+| "用户反馈怎么样" | 反馈分析 |
+
+> AI 会自动路由到对应技能。不需要记斜杠命令。
+
+---
+
+## 5. 日常使用：在终端里
+
+### 5.1 状态查看
+
+```bash
+npx @hupan56/wlkj status
+```
+
+### 5.2 中文 Git 命令（不懂 git 也能用）
+
+| 命令 | 等价于 | 作用 |
+|------|--------|------|
+| `npx @hupan56/wlkj 提交` | `git add . && commit && push` | 全部提交并推送 |
+| `npx @hupan56/wlkj 提交PRD` | 只提交 `workspace/specs/prd/` | 提交 PRD |
+| `npx @hupan56/wlkj 提交Spec` | 只提交 `workspace/specs/` | 提交技术规格 |
+| `npx @hupan56/wlkj 提交任务` | 只提交 `workspace/tasks/` | 提交任务 |
+| `npx @hupan56/wlkj 推送` | `git push` | 只推送 |
+| `npx @hupan56/wlkj 拉取最新` | `git pull` | 拉队友最新 |
+| `npx @hupan56/wlkj 同步` | `git pull` | 同上 |
+| `npx @hupan56/wlkj 查看状态` | `git status` | 看改了哪些文件 |
+
+---
+
+## 6. 代码搜索（10 种模式）
+
+### 6.1 关键词搜索（最常用）
+```bash
+python .qoder/scripts/search_index.py 考勤
+```
+> 搜全项目。中文自动分词（"异常记录"→异常+记录→abnormal+record）。
+
+### 6.2 平台过滤
+```bash
+python .qoder/scripts/search_index.py 考勤 --platform web    # 只搜 Web 管理端 (fywl-ui)
+python .qoder/scripts/search_index.py 考勤 --platform app    # 只搜 APP 移动端 (Carmg-H5)
+```
+
+### 6.3 搜 API
+```bash
+python .qoder/scripts/search_index.py --api salary
+```
+> 返回 API 路径 + 所在文件。
+
+### 6.4 搜字段
+```bash
+python .qoder/scripts/search_index.py --field nickName
+```
+> 返回字段名 → 中文标题 → 使用文件。写 PRD 时用来查字段命名约定。
+
+### 6.5 搜页面样式
+```bash
+python .qoder/scripts/search_index.py --style table --platform web
+python .qoder/scripts/search_index.py --style form --platform web
+```
+> 类型：table / form / detail / modal / dashboard。返回同类页面示例。
+
+### 6.6 搜历史 PRD
+```bash
+python .qoder/scripts/search_index.py --prd 保险
+```
+
+### 6.7 搜 Repo Wiki（语义级，最精准）
+```bash
+python .qoder/scripts/search_index.py --wiki 保险
+```
+> 搜 Qoder IDE 生成的模块文档。带行号引用，比读源码精准。
+> **前提**：项目已用 Qoder IDE 生成 Repo Wiki。
+
+### 6.8 组件统计
+```bash
+python .qoder/scripts/search_index.py --components
+```
+
+### 6.9 模块概览
+```bash
+python .qoder/scripts/search_index.py --modules
+```
+
+### 6.10 一次取全（Fast Path，写 PRD 前用）
+```bash
+python .qoder/scripts/context_pack.py 保险 --platform web
+```
+> 一次返回 7 章节：代码 + 页面 + 字段 + PRD + API + 样式 + Wiki。
+> 比逐个 search 省 5-6 次往返。
+
+---
+
+## 7. PRD 生成（4 种模式 + 评估）
+
+### 7.1 Reference 模式（默认）
+```
+/wl-prd 异常列表新增项目类型筛选
+```
+> 参考现有代码 + 历史 PRD 生成。适合"照着已有的做类似的"。
+
+### 7.2 Brainstorm 模式（创新需求）
+```
+/wl-prd 头脑风暴：如何优化车辆调度效率
+```
+> SCAMPER 7 维度 + 多 agent 并行调研。适合"想不出怎么做"。
+
+### 7.3 Planning 模式（规划类）
+```
+/wl-prd 规划：下季度车辆管理模块重构
+```
+> 现状分析 + 理想态研究 + Gap 分析 + MVP。适合"大方向"。
+
+### 7.4 Quick 模式（小改动）
+```
+/wl-prd 快速：列表加个导出按钮
+```
+> 快速定位 + Mini-PRD + 微型原型（只改 diff）。适合"小功能"。
+
+### 7.5 EVA 质量门禁
+```bash
+python .qoder/scripts/eval_prd.py <prd.md> [prototype.html]
+```
+> 10 维度打分。≥80% 才能发布。<80% 会列出缺什么，修完再评估。
+> **PRD 发布前自动跑**，不过不放行。
+
+### 7.6 生成时会自动做
+1. **先问平台**（Web / APP / 两端）—— 强制，不跳过
+2. 分配 REQ-ID（原子分配器，防撞号）
+3. 生成匹配平台风格的原型（Ant Design / Vant）
+4. 跑 EVA 评估
+5. 发布到 `workspace/specs/prd/`
+6. 自动 team_sync push
+7. 飞书通知团队
+
+---
+
+## 8. 任务管理（13 个子命令）
+
+### 8.1 创建
+```bash
+python .qoder/scripts/task.py create "异常筛选功能" --priority P0
+```
+> 优先级：P0（紧急）/ P1（高）/ P2（中）/ P3（低）
+
+### 8.2 列表
+```bash
+python .qoder/scripts/task.py list          # 全部
+python .qoder/scripts/task.py list --mine   # 只看我的
+```
+
+### 8.3 查看详情
+```bash
+python .qoder/scripts/task.py show 06-15-异常筛选功能
+```
+
+### 8.4 开始
+```bash
+python .qoder/scripts/task.py start 06-15-异常筛选功能
+```
+> planning → in_progress。记录开始时间戳。
+
+### 8.5 当前任务
+```bash
+python .qoder/scripts/task.py current
+```
+
+### 8.6 完成
+```bash
+python .qoder/scripts/task.py finish
+```
+> 完成当前任务。→ completed。记录完成时间 + 算用时 + 飞书通知。
+
+### 8.7 归档
+```bash
+python .qoder/scripts/task.py archive 06-15-异常筛选功能
+```
+> 移到 archive/。**自动清理其他任务对它的依赖引用**（防僵尸任务）。
+
+### 8.8 截止日期
+```bash
+python .qoder/scripts/task.py set-due 06-15-异常筛选功能 2026-12-31
+```
+
+### 8.9 阻塞关系
+```bash
+python .qoder/scripts/task.py block 06-15-任务B 06-15-任务A    # B 被 A 阻塞
+python .qoder/scripts/task.py unblock 06-15-任务B 06-15-任务A  # 解除
+```
+
+### 8.10 子任务
+```bash
+python .qoder/scripts/task.py add-subtask 06-15-父任务 06-15-子任务
+python .qoder/scripts/task.py remove-subtask 06-15-父任务 06-15-子任务
+```
+> 子任务必须是已存在的任务（关联，不是创建）。
+
+### 8.11 甘特图
+```bash
+python .qoder/scripts/task.py gantt
+```
+
+---
+
+## 9. 报告与导出
+
+### 9.1 日报
+```bash
+python .qoder/scripts/report.py daily
+python .qoder/scripts/report.py daily --push-feishu    # 同时发飞书
+```
+> 内容：今日完成 / 进行中 / 明日计划 / 提交统计。
+
+### 9.2 周报
+```bash
+python .qoder/scripts/report.py weekly
+python .qoder/scripts/report.py weekly --push-feishu
+```
+
+### 9.3 导出 Jira CSV
+```bash
+python .qoder/scripts/export.py jira
+```
+
+### 9.4 导出 OpenAPI
+```bash
+python .qoder/scripts/export.py openapi
+```
+> 从 Java Controller 提取 API 规范。
+
+### 9.5 导出调用图
+```bash
+python .qoder/scripts/export.py callgraph
+```
+
+### 9.6 项目状态
+```bash
+python .qoder/scripts/status.py
+```
+> 健康度（6 维加权）+ 阻塞图 + 截止日期 + 周期时间。
+
+---
+
+## 10. 团队协作与冲突处理
+
+### 10.1 提交产出（PRD / 任务 / 索引）
+
+```bash
+python .qoder/scripts/team_sync.py push
+```
+> **这是团队协作的核心命令**。会自动完成：
+> 1. 白名单 staging（只提交 workspace/ + data/docs + data/index，不提交敏感文件）
+> 2. 四道门禁检查（身份 / git 作者 / 秘密扫描 / REQ-ID 撞号 / EVA）
+> 3. commit
+> 4. **先 `git pull --rebase`** 再 push（处理远端有新提交的情况）
+> 5. push
+
+### 10.2 拉取队友产出
+```bash
+python .qoder/scripts/team_sync.py pull
+```
+> `git pull --rebase --autostash`。本地未提交改动会被 stash 保护。
+
+### 10.3 提交前会先拉吗？
+
+**会。** push 流程的第 4 步就是 `git pull --rebase`：
+```
+push → commit → pull --rebase → push
+```
+先拉远端最新，rebase 到本地提交之上，然后才 push。
+
+### 10.4 会有冲突吗？
+
+**可能有**，但很少。原因和概率：
+
+| 场景 | 冲突概率 | 原因 |
+|------|---------|------|
+| 两人改**同一个 PRD 文件** | 高 | 同文件同行 |
+| 两人各建**自己的 PRD/任务** | 极低 | 不同路径，git 自动合并 |
+| 两人都改**索引文件** | 低 | team_sync 用 FileLock 串行化，不会同时改 |
+| 两人离线各建**同号 PRD** | 中 | REQ-ID 撞号（门禁会拦住，不会真的冲突） |
+
+> **大多数情况不冲突**，因为每人的产出在 `workspace/members/{你的名字}/` 下，路径不交叉。
+
+### 10.5 冲突了怎么办？
+
+如果 push 时检测到 rebase 冲突，会输出：
+```
+SYNC_CONFLICT: 自动同步遇到冲突, 已安全回退 (本地产出未丢失)。
+AI 请按以下步骤解决冲突:
+  1. git status                              # 看哪些文件冲突
+  2. git pull --rebase origin master         # 重新拉取
+  3. 编辑冲突文件 (<<<<<<< 标记处), 保留双方改动
+  4. git add <解决后的文件>                  # 标记已解决
+  5. git rebase --continue                   # 继续 rebase
+  6. git push                                # 推送
+```
+> **用户不需要自己跑这些** —— AI（Qoder 里的对话）会自动帮你执行。
+> 本地产出不会丢（已安全回退）。
+
+### 10.6 四道门禁（提交前自动检查）
+
+| 门禁 | 检查什么 | 失败怎么办 |
+|------|---------|-----------|
+| ① 身份 | member.json + 签名密钥存在 | 跑 `init 你的名字` |
+| ② Git 作者 | git config 跟注册一致 | 按 TODO 提示跑 git config |
+| ③ 秘密扫描 | 无 AWS/GitHub/私钥泄露 | 删掉敏感内容 |
+| ④ REQ-ID | 无撞号 / 跳号 | 改其中一个的编号 |
+| ⑤ EVA | PRD 质量达标（≥80%） | 补全缺失章节 |
+
+> 门禁失败 → staging 撤销，不提交，打印原因。修完重跑即可。
+
+---
+
+## 11. QoderWork 桌面端
+
+### 11.1 安装技能到 QoderWork
+```bash
+python .qoder/scripts/install_qoderwork.py
+```
+> 把 .qoder/skills/ 安装到 `~/.qoderwork/skills/`（junction 方式）。
+> 装完重启 QoderWork，按 `/` 就能看到 11 个 `/wl-*` 命令。
+
+### 11.2 强制刷新 commands（升级后用）
+```bash
+python .qoder/scripts/install_qoderwork.py --force-commands
+```
+
+### 11.3 检查安装状态
+```bash
+python .qoder/scripts/install_qoderwork.py --check
+```
+
+### 11.4 飞书通知
+
+**方式 A：QoderWork IM Channel（交互式）**
+> Settings → IM Channels → 绑定 Lark（飞书）→ 扫码
+> 之后说"写日报发飞书"，QoderWork 自动用连接器发。
+
+**方式 B：webhook（任何环境）**
+```bash
+python .qoder/scripts/report.py daily --push-feishu
+```
+> 在 `.qoder/config.yaml` 里配飞书 bot webhook URL。
+> PRD 发布 / 任务完成 / 截止提醒 / 评估拒绝 → 自动发飞书卡片。
+
+---
+
+## 12. 故障排查
+
+### 12.1 环境问题
+```bash
+python .qoder/scripts/init_doctor.py --fix    # 自动修复
+```
+
+### 12.2 命令找不到
+> 重新打开终端（PATH 可能没刷新）。
+
+### 12.3 看不到斜杠命令
+> Qoder IDE / Quest：新建对话。
+> QoderWork：重启应用 + 新建对话。
+
+### 12.4 git push 被拒
+> 队友先推了。team_sync 会自动 `pull --rebase` 重试 3 次。
+> 如果还是失败，按 SYNC_CONFLICT 提示让 AI 解决冲突。
+
+### 12.5 知识图谱过期
+> 代码改了但搜索结果不更新？跑：
+```bash
+python .qoder/scripts/git_sync.py --index-only
+```
+
+### 12.6 性能基准
+```bash
+python .qoder/scripts/benchmark.py
+```
+
+---
+
+## 13. 命令速查表
+
+### 新用户（第一次用）
+```bash
+# 1. 装 Node.js（手动，一次性）
+# 2. 装其余
+npx @hupan56/wlkj install-env
+# 3. 安装引擎
+mkdir my-project && cd my-project
+npx @hupan56/wlkj init 你的名字
+# 4. 开始用！在 Qoder 里说 "写个 XX 的需求"
+```
+
+### 已装用户（升级）
+```bash
+npx @hupan56/wlkj update
+```
+
+### 日常（在 Qoder 里）
+```
+/wl-prd       写需求
+/wl-search    查代码
+/wl-task      建任务
+/wl-status    看进度
+/wl-report    写日报
+/wl-spec      出技术方案
+/wl-code      写代码
+/wl-test      写测试
+/wl-commit    提交
+```
+
+### 日常（在终端里）
+```bash
+npx @hupan56/wlkj status              # 看状态
+npx @hupan56/wlkj 提交                # 提交全部
+npx @hupan56/wlkj 拉取最新            # 拉队友最新
+python .qoder/scripts/report.py daily # 日报
+python .qoder/scripts/git_sync.py     # 刷新知识图谱
+```
+
+---
+
+> **一句话**：不会命令就说中文，AI 自动路由。斜杠命令只是快捷入口。