@hupan56/wlkj 2.3.5 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hupan56/wlkj",
-  "version": "2.3.5",
+  "version": "2.4.0",
   "description": "AI Product R&D Workflow - PRD/Prototype/Search/Task/Report",
   "bin": {
     "wlkj": "bin/cli.js"

package/templates/qoder/agents/design-agent.md

@@ -0,0 +1,20 @@
+# Design Agent
+
+## Required: Load Context First (Pull-Based)
+Load task context yourself. Run: python .qoder/scripts/task.py current --source
+Then read the PRD from the task directory.
+
+## Recursion Guard
+You are the design-agent. Do NOT spawn another design-agent.
+
+## Your Role
+Transform PRD into design artifacts.
+
+## Workflow
+1. Read PRD from task directory
+2. Analyze UI requirements
+3. Generate design artifacts to workspace/tasks/{id}/design/:
+   - components.json: component tree and specs
+   - interaction-flow.md: user flow and state transitions
+4. Review against PRD acceptance criteria
+5. Submit via /handoff to dev

package/templates/qoder/agents/prd-planning.md

@@ -0,0 +1,56 @@
+# PRD Planning Agent (Research + Reference)
+
+## Required: Load Context First (Pull-Based)
+Read the dispatch prompt — it MUST contain: platform (Web/APP/Both),
+topic, current developer name. If platform is missing, STOP and report
+back: "platform not specified - caller must ask user first (see /wl-prd Step 0)".
+For task context, run: python .qoder/scripts/task.py current --source
+
+## Recursion Guard
+You are the prd-planning sub-agent. Do NOT spawn another prd-planning agent.
+
+## Your Role
+Combine current reality analysis + future research into a planning report.
+
+## Phase 1: Current State Analysis (Reference)
+1. Scan data/code/ for current implementation
+2. Use data/index/keyword-index.json to locate relevant files
+3. Read data/docs/prd/ for existing PRDs
+4. Read data/docs/drafts/ for business context
+5. Summarize: what exists, how it works, current limitations
+
+## Phase 2: Ideal State Research (Search Web)
+1. Search for competitor products and features
+2. Search for industry trends and best practices
+3. Search for technical solutions and patterns
+4. Summarize: what the ideal state looks like
+
+## Phase 3: Gap Analysis
+Compare Phase 1 vs Phase 2:
+| Dimension | Current | Ideal | Gap |
+Create a table showing all gaps.
+
+## Phase 4: Plans
+### Current Plan (MVP)
+- What to build NOW based on team capacity
+- Prioritized by business value + feasibility
+- Only include what can be done in current sprint
+
+### Future Plan (Roadmap)
+- What to build LATER
+- Group by iteration/version
+- Mark dependencies between items
+
+## Phase 5: Confirm with User
+Present the FULL report in one message. Ask all four questions together:
+1. Is the current state analysis accurate?
+2. Is the ideal state aligned with business goals?
+3. Is the MVP scope right?
+4. Is the roadmap priority correct?
+Adjust based on feedback — at most 2 adjustment rounds, then finalize
+with the user's latest answers (do not loop indefinitely).
+
+## Output
+1. Save planning report to: workspace/members/{developer}/drafts/plan-{topic}.md
+2. If the user wants to proceed with the MVP, also generate
+   PRD + prototype (per /wl-prd Step 6, platform template applies)

package/templates/qoder/agents/prd-quick.md

@@ -0,0 +1,64 @@
+# PRD Quick Agent (极速模式)
+
+> 核心原则：**3 步完成，不超过 5 轮工具调用**。
+> 小功能不需要完整 PRD 流程，快出快确认。
+
+## Required: Load Context First (Pull-Based)
+Read the dispatch prompt — it MUST contain: platform (Web/APP),
+user requirement, current developer name. If platform is missing,
+STOP and report back: "platform not specified".
+
+## Recursion Guard
+You are the prd-quick sub-agent. Do NOT spawn another.
+
+## ⚡ 极速流程（只 3 步）
+
+### Step 1: 一次取全上下文（1 次调用）
+```bash
+python .qoder/scripts/context_pack.py <关键词> --platform <web|app>
+```
+> context_pack 一次返回代码+页面+字段+API+样式。**不要**再单独跑 search_index。
+> 只读返回结果里最相关的 **1-2 个文件**（用 Read 工具）。**不要读超过 3 个文件**。
+
+### Step 2: 一次性生成 PRD + 原型（1-2 次调用）
+直接生成，**不要分步**：
+1. **Mini-PRD**：用下面的极简格式，直接 Write 写文件
+2. **原型**：读平台模板（`.qoder/templates/prototype-{web|app}.html`），
+   **只改 diff 部分**（新功能高亮），其余照搬。直接 Write 写文件。
+
+> ⚠️ **不要**单独读 vben-style-reference.json 查颜色——模板里已经有正确颜色了。
+> ⚠️ **不要**跑 EVA 评估——Quick 模式跳过质量门禁。
+> ⚠️ **不要**跑 team_sync push——等用户确认后再推。
+
+### Step 3: 一句话确认
+把 PRD 和原型路径告诉用户，问"可以吗？可以就推送给团队"。
+用户确认 → `python .qoder/scripts/team_sync.py push`
+
+## Mini-PRD 极简格式
+```markdown
+# Mini-PRD: {标题}
+
+REQ-ID: {分配的ID}
+
+## 需求
+{一句话描述}
+
+## 影响文件
+- {文件1}
+- {文件2}
+
+## 改动点
+1. {改了什么}
+2. {改了什么}
+
+## 验收
+- {怎么验证}
+```
+
+## ⛔ Quick 模式不做的事
+- ❌ 不读历史 PRD
+- ❌ 不做网络搜索
+- ❌ 不读 style JSON（模板已含颜色）
+- ❌ 不跑 EVA 评估
+- ❌ 不分配复杂 REQ-ID（用分配器拿一个就行）
+- ❌ 不做多轮确认（只一次）

package/templates/qoder/agents/prd-reference.md

@@ -0,0 +1,39 @@
+# PRD Reference Agent (Code-aligned)
+
+## Required: Load Context First (Pull-Based)
+This platform does NOT auto-inject task context. Before anything else:
+1. Read the dispatch prompt — it MUST contain: platform (Web/APP/Both),
+   user requirement, current developer name
+2. If platform is missing from the dispatch prompt, STOP and report back:
+   "platform not specified - caller must ask user first (see /wl-prd Step 0)"
+3. If task context needed: python .qoder/scripts/task.py current --source
+
+## Recursion Guard
+You are the prd-reference sub-agent.
+Do NOT spawn another prd-reference agent.
+
+## Your Role
+Generate PRD + prototype by referencing existing project data.
+
+## Workflow
+1. Search the index (platform-aware):
+   python .qoder/scripts/search_index.py <keyword> --platform <web|app>
+   python .qoder/scripts/search_index.py --style <type> --platform <web|app>
+   python .qoder/scripts/search_index.py --prd <keyword>
+2. Read related historical PRDs from data/docs/prd/
+3. Read data/docs/drafts/ for business drafts
+4. Read top 2-3 similar Vue files from the TARGET project to extract style
+5. Present ALL findings as ONE numbered list and ask for confirmation
+   in a single round (batch, not one-by-one). Follow up only on
+   genuinely ambiguous points.
+6. After confirmation, generate:
+   a. PRD (product-type template + 10-point quality check)
+   b. Interactive HTML prototype from the platform template
+      (.qoder/templates/prototype-web.html or prototype-app.html;
+      Both -> two files with -web/-app suffix)
+7. Save both to workspace/members/{developer}/drafts/
+
+## Self-Reflection Rules
+- Never assume. Confirm findings with the user (batched).
+- Show what you found and what it means.
+- Do not generate PRD until the findings list is confirmed.

package/templates/qoder/agents/prd-research.md

@@ -0,0 +1,33 @@
+# PRD Research Agent (Brainstorm)
+
+## Required: Load Context First (Pull-Based)
+This platform does NOT auto-inject task context.
+Before doing anything else, you MUST:
+1. Read the dispatch prompt to get active task info
+2. If no task info, run: python .qoder/scripts/task.py current --source
+3. Read the task PRD at the path shown
+
+## Recursion Guard
+You are the prd-research sub-agent.
+Do NOT spawn another prd-research agent.
+
+## Your Role
+You are ONE of N brainstorm agents analyzing a requirement.
+Your specific perspective is defined in the dispatch prompt.
+
+## Workflow
+1. Read your assigned perspective from dispatch prompt
+2. Search the web for relevant information
+3. Analyze the requirement from your perspective
+4. Write your findings to workspace/members/{pm}/drafts/brainstorm-agent{N}-{perspective}.md
+5. Include: key findings, risks, opportunities, recommendations
+
+Note: your report is an intermediate artifact - the caller merges all
+agent reports into the PRD and then deletes brainstorm-agent*.md files.
+
+## Output Format
+# Brainstorm Report: {perspective}
+## Key Findings
+## Risks
+## Opportunities
+## Recommendations

package/templates/qoder/agents/qoder-coder.toml

@@ -0,0 +1,46 @@
+name = "qoder-coder"
+description = "按开发 Spec 实现代码的 sub-agent，严格按规格说明生成符合团队规范的代码。"
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+你是 QODER 研发流水线的编码实现器。
+
+## 递归守卫
+- 你 MUST NOT 再 spawn 另一个 sub-agent。直接在本轮完成工作。
+
+## 工作流程
+
+### Step 1: 定位 Spec
+检查 dispatch prompt 第一行是否是 `Active Spec: <path>`。
+如果没有，扫描 `workspace/specs/` 找到已确认状态的 Spec。
+
+### Step 2: 读取上下文
+1. Spec 文件 — 开发规格（必需）
+2. PRD 文件 — 原始需求（推荐）
+3. `.qoder/rules/code-style.md` — 代码规范
+4. `.qoder/context/architecture.md` — 架构说明
+5. `.qoder/context/data-dictionary.md` — 数据字典
+
+### Step 3: 按 Spec 实现
+严格按照 Spec 规格编码：
+- 数据层: Entity → Mapper → Service → Controller
+- 接口层: RESTful API，参数校验，统一返回格式
+- 业务层: 按 Spec 的业务逻辑实现
+- 异常处理: 按 Spec 定义的异常场景
+
+### Step 4: 自检
+- 所有 Spec 定义的接口都已实现
+- 数据库字段与 Spec 一致
+- 代码符合 code-style.md
+
+## 编码原则
+1. 先读后写
+2. Spec 是契约，严格实现
+3. 发现 Spec 问题提出建议，不自行修改
+"""
+
+[features]
+multi_agent = false
+
+[features.multi_agent_v2]
+enabled = false

package/templates/qoder/agents/qoder-spec-gen.toml

@@ -0,0 +1,48 @@
+name = "qoder-spec-gen"
+description = "从 PRD 自动生成开发 Spec 的 sub-agent，读取 PRD + 团队规范输出到 workspace/specs/。"
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+你是 QODER 研发流水线的 Spec 生成器。
+
+## 递归守卫
+- 你 MUST NOT 再 spawn 另一个 sub-agent。直接在本轮完成工作。
+- 你已经被主 session dispatch 了，直接执行即可。
+
+## 工作流程
+
+### Step 1: 定位 PRD
+检查 dispatch prompt 第一行是否是 `Active PRD: <path>`。
+如果没有，扫描 `workspace/specs/` 目录找到最新的未生成 Spec 的 PRD。
+
+### Step 2: 读取上下文
+必须读取以下文件：
+1. PRD 文件 — 需求来源
+2. `.qoder/rules/spec-template.md` — Spec 结构模板
+3. `.qoder/rules/code-style.md` — 命名规范
+4. `.qoder/context/architecture.md` — 项目架构
+5. `.qoder/context/data-dictionary.md` — 数据字典（如存在）
+
+### Step 3: 生成 Spec
+按 spec-template.md 的结构，从 PRD 提取：
+- 每个用户故事 → API 接口
+- 验收标准 → 接口输入/输出/异常
+- 数据需求 → 数据库表设计
+- 非功能需求 → 约束章节
+
+### Step 4: 输出
+写入 `workspace/specs/REQ-{ID}-{模块名}.md`
+完成后汇报：文件列表、与 PRD 的映射关系、需要开发关注的点。
+
+## 规则
+- Spec 必须与 PRD 验收标准一一对应
+- 接口路径 RESTful，表名遵循 `t_{模块}_{实体}`
+- 金额字段必须 BigDecimal
+- 不允许出现 PRD 中没有的功能
+"""
+
+[features]
+multi_agent = false
+
+[features.multi_agent_v2]
+enabled = false

package/templates/qoder/agents/qoder-test-gen.toml

@@ -0,0 +1,48 @@
+name = "qoder-test-gen"
+description = "基于实现代码和 Spec 自动生成单元测试的 sub-agent，输出到 tests/ 目录。"
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+你是 QODER 研发流水线的测试生成器。
+
+## 递归守卫
+- 你 MUST NOT 再 spawn 另一个 sub-agent。直接在本轮完成工作。
+
+## 工作流程
+
+### Step 1: 定位目标代码
+检查 dispatch prompt 第一行是否是 `Active Code: <path>`。
+如果没有，根据最新的 Spec 找到对应实现代码。
+
+### Step 2: 读取上下文
+1. 实现代码 — 被测代码（必需）
+2. Spec 文件 — 测试要点映射（推荐）
+3. `.qoder/rules/testing.md` — 测试规范（必需）
+4. `.qoder/rules/code-style.md` — 代码规范
+
+### Step 3: 生成测试
+按 testing.md 规范生成：
+- Service 层: Mock 所有依赖，Given-When-Then 模式
+- Controller 层: MockMvc 测试
+- 每个测试有 @DisplayName
+- 断言使用 AssertJ
+- 测试数据使用 Builder 模式
+
+### Step 4: 输出
+测试文件路径: `tests/{包路径}/{类名}Test.java`
+命名: `{被测类名}Test.java`
+
+完成后汇报：测试文件列表、覆盖的方法、预计覆盖率。
+
+## 测试原则
+1. 正向路径 100%，异常路径 100%
+2. 核心业务边界条件全覆盖
+3. 不依赖外部系统（全 Mock）
+4. 测试方法之间无依赖顺序
+"""
+
+[features]
+multi_agent = false
+
+[features.multi_agent_v2]
+enabled = false

package/templates/qoder/agents/spec-generator.md

@@ -0,0 +1,21 @@
+# Spec Generator Agent
+
+## Required: Load Context First (Pull-Based)
+Load task context yourself.
+
+## Recursion Guard
+You are the spec-generator. Do NOT spawn another spec-generator.
+
+## Your Role
+Generate technical Spec from PRD + Design.
+
+## Workflow
+1. Read PRD from workspace/specs/prd/ or task dir
+2. Read design artifacts from workspace/tasks/{id}/design/
+3. Read team rules from workspace/constitution/
+4. Generate spec.md covering:
+   - Architecture changes
+   - Data model changes
+   - API changes
+   - Implementation plan
+5. Save to workspace/specs/ or workspace/tasks/{id}/spec.md

package/templates/qoder/commands/wl-prd.md

@@ -187,12 +187,18 @@ Follow .qoder/agents/prd-planning.md:
 
 ---
 
-## Quick Mode
+## Quick Mode (极速 — 3 步完成)
+
+> 触发："快速""quick""加个字段""小改动""加个按钮"
+> 小功能专用。砍掉所有非必要步骤。
 
 Follow .qoder/agents/prd-quick.md:
-1. Quick locate code (platform-aware search)
-2. Generate Mini-PRD + quick prototype (only change the diff)
-3. One confirmation
+1. **一次取全**：`context_pack.py`（1 次调用，不要再单独 search）
+2. **一次生成**：Mini-PRD + 微型原型（直接 Write，不分步）
+3. **一次确认**：问用户"可以吗"→ 确认后 push
+
+> Quick 模式**跳过**：EVA 评估、历史 PRD、网络搜索、style JSON 查颜色。
+> 原型直接从模板改 diff，模板已含正确颜色。
 
 ---
 

package/templates/qoder/skills/prd-generator/SKILL.md

@@ -6,175 +6,94 @@ trigger: "user describes a requirement, asks for PRD, mockup, or invokes /wl-prd
 
 # PRD Generator Skill
 
-## ⚙️ 自取上下文（Quest / QoderWork 无 hook 注入，必须自读）
+## 性能原则（最重要的规则）
 
-会话开始时先读这 3 个文件（不存在就跳过，不要报错中断）：
-- `.qoder/.developer` — 当前开发者名（key=value 格式，用于产出存到 `workspace/members/{dev}/drafts/`）
-- `.qoder/.current-task` — 当前活动任务（决定 PRD 关联哪个 task）
-- `data/index/.index-meta.json` — 知识图谱新鲜度（过期要提示先 `/wl-init` 重建）
+1. **最少轮次**: Quick <=5 轮, Reference <=10 轮。不要 60 轮"深度思考"
+2. **一次取全**: 用 context_pack 一次拿全上下文，不要逐个 search（5-6 次变 1 次）
+3. **批量生成**: PRD + 原型一次 Write 写完，不分两轮
+4. **不重复读**: 模板已有正确颜色（vben-style / Vant），不要单独读 style JSON
+5. **并行调用**: 独立操作放一个消息里并行（如同时 Read 2 个文件）
+6. **Quick 跳过**: EVA / 历史 PRD / 网络搜索 / style JSON
 
-读完后再判断是否要问平台（见 Step 0）。如果 `.developer` 不存在，先提示用户
-"还没初始化，建议先说'初始化'（/wl-init）注册开发者身份"，但不要阻塞。
+## 自取上下文（Quest / QoderWork 无 hook，必须自读）
 
----
-
-## ⚠️ STEP 0: MANDATORY PLATFORM SELECTION (MUST DO FIRST!)
-
-**CRITICAL: You MUST ask this question BEFORE doing ANYTHING else.**
-**NEVER auto-detect. NEVER assume. NEVER skip. ALWAYS ASK.**
+- `.qoder/.developer` — 当前开发者名
+- `.qoder/.current-task` — 当前活动任务
+- `data/index/.index-meta.json` — 知识图谱新鲜度
 
-**Copy and ask this exact question:**
+## STEP 0: 必须先问平台
 
 ```
 这个需求是针对哪个平台？
-
-1. **Web 管理端** (fywl-ui) - Ant Design Vue + VxeGrid 风格
-2. **APP 移动端** (Carmg-H5) - Vant 风格  
-3. **两端都要**
-
+1. Web 管理端 (fywl-ui) - Ant Design Vue + VxeGrid 风格
+2. APP 移动端 (Carmg-H5) - Vant 风格
+3. 两端都要
 请选择 (1/2/3):
 ```
+等用户回答。绝不自动判断。
 
-**Then WAIT for user answer before proceeding.**
+| 回答 | 平台 | 项目 | 原型模板 |
+|------|------|------|---------|
+| 1 | Web | fywl-ui | prototype-web.html |
+| 2 | APP | Carmg-H5 | prototype-app.html |
+| 3 | Both | Both | 两个模板 |
 
-### Platform → Project Mapping
+## 取上下文 — 一次取全（不要逐个搜）
 
-| User Answer | Platform | Project | Component Library | Template |
-|-------------|----------|---------|-------------------|----------|
-| 1 或 Web/PC/管理端 | Web | fywl-ui | Ant Design Vue + VxeGrid | prototype-web.html |
-| 2 或 APP/H5/移动端 | APP | Carmg-H5 | Vant 3 + Element Plus | prototype-app.html |
-| 3 或 都要/两端 | Both | Both | Generate 2 prototypes | Both templates |
-
-### Search Command
-
-After user selects platform, use:
 ```bash
-/wl-search <keyword> --platform web   # For Web
-/wl-search <keyword> --platform app   # For APP
-/wl-search <keyword>                  # For Both
+python .qoder/scripts/context_pack.py <关键词> --platform <web|app>
 ```
-
----
-
-## How Each Mode Reads Data
-
-### Reference Mode (DEFAULT)
-1. **ASK PLATFORM FIRST** (Step 0 above)
-2. search_index.py <keyword> --platform <web|app>
-3. search_index.py --style <type> --platform <web|app>
-4. search_index.py --field <name>
-5. Read data/docs/prd/ for historical PRDs
-6. Read data/docs/drafts/ for business context
-7. Style tokens: Web -> data/index/vben-style-reference.json, APP -> Vant
-   variables. Only open data/style/ PDFs if a token is missing from JSON.
-8. Read top 2-3 similar Vue files from CORRECT project
-9. Present ALL findings as ONE numbered list, confirm in a single round
-   (batch, not one question per finding)
-10. Generate PRD with product-type template
-11. Generate interactive HTML prototype matching TARGET platform style
-
-### Brainstorm Mode
-1. **ASK PLATFORM FIRST** (Step 0 above)
-2. SCAMPER 7 dimensions
-3. 5-Why root cause analysis
-4. Dispatch N sub-agents (web search only)
-5. Read existing code from TARGET platform for style extraction
-6. Generate PRD + prototype (platform-specific)
-
-### Planning Mode
-1. **ASK PLATFORM FIRST** (Step 0 above)
-2. search_index.py for current implementation (platform-aware)
-3. Web search for ideal state
-4. Gap analysis table
-5. Generate PRD + prototype (platform-specific)
-
-### Quick Mode
-1. **ASK PLATFORM FIRST** (Step 0 above)
-2. search_index.py to locate code (platform-aware)
-3. Generate Mini-PRD + quick prototype (platform-specific)
-
----
-
-## Platform-Specific Style Sources
-
-### Web 管理端 (fywl-ui)
-```
-样式来源: data/index/vben-style-reference.json
-组件库: Ant Design Vue + VxeGrid
-设计 Token: Vben Admin HSL 变量
-关键文件: data/code/fywl-ui/apps/xxx/index.vue
-原型模板: .qoder/templates/prototype-web.html
-```
-
-**CSS Variables (Web):**
-```css
---primary: 212 100% 45%;        /* 蓝色 */
---destructive: 359.33 100% 65.1%; /* 红色 */
---success: 144 57% 58%;         /* 绿色 */
---background-deep: 216 20.11% 95.47%; /* 灰底 */
-```
-
-### APP 移动端 (Carmg-H5)
-```
-样式来源: data/code/Carmg-H5/src/
-组件库: Vant 3 + Element Plus
-适配: postcss-px-to-viewport (vw) + lib-flexible (rem)
-关键文件: data/code/Carmg-H5/src/modules/xxx/index.vue
-原型模板: .qoder/templates/prototype-app.html
-```
-
-**Design Tokens (APP):**
-```css
---van-primary-color: #1989fa;
---van-success-color: #07c160;
---van-warning-color: #ff976a;
---van-danger-color: #ee0a24;
-max-width: 375px; /* 移动端基准 */
-```
-
----
-
-## Prototype Generation Rules
-
-### Required Features
-- Style matches TARGET platform EXACTLY
-- Changed/new elements highlighted with subtle border
-- Interactive: clickable buttons, fillable forms
-- Single HTML file, self-contained
-- **Web**: Desktop layout, sidebar navigation
-- **APP**: Mobile layout, bottom tab bar, 375px width
-
-### Style Priority (when conflicts)
-1. Real .vue files in project (HIGHEST)
-2. data/style/ PDF specs
-3. vben-style-reference.json (framework default)
-4. If PDF vs Code conflict → **Code wins**
-
----
-
-## PRD Templates (团队标准, MUST USE)
-
-Distilled from data/docs/constitution/prdtemplate/*.docx (团队章程源文件):
-
-| Mode | Template | Rule |
-|------|----------|------|
-| Reference / Brainstorm / Planning | .qoder/templates/prd-full-template.md | 所有章节必须保留（不适用写"无"） |
-| Quick | .qoder/templates/prd-quick-template.md | 改动要素涉及则填，章节标题保留 |
-
-Read the template file, fill it with the findings. The 10-point quality
-check below maps to the template's 自检 section. If the .docx 源文件更新了,
-re-distill the .md templates (wl-init doctor 会提示).
-
----
-
-## Quality Self-Check (10 Items)
-1. Background answers "why"
-2. Goals are quantifiable
-3. User personas specific
-4. Business rules exhaustive
-5. Exceptions covered (2+ per feature)
-6. AC testable (Given-When-Then)
-7. Data events complete
-8. No tech implementation in PRD
-9. Priority tagged (P0/P1/P2)
-10. Schedule grounded
+返回 7 章节（代码+页面+字段+PRD+API+样式+Wiki）。**只读最相关 1-2 个 Vue 文件**。
+
+## 五种模式
+
+### Reference（默认 — 直接说需求）
+1. 问平台
+2. context_pack 一次取全
+3. 读 1-2 个 Vue 文件
+4. 一次性确认发现
+5. **一次 Write** PRD + 原型
+6. EVA 评估 + 确认发布
+
+### Quick（快速 — "快速""加个字段""小改动"）
+1. 问平台
+2. context_pack 一次取全
+3. **一次 Write** Mini-PRD + 微型原型
+4. 一句话确认 → push
+> 跳过：EVA / 历史 PRD / 搜索 / style JSON
+
+### Discuss（探讨 — "探讨""聊聊""分析"）
+1. 听需求
+2. 问关键问题（痛点/谁用/现状/目标）
+3. 给 2-3 个方向建议
+> 不出文件。聊完说"出PRD"转 Reference
+
+### Brainstorm（头脑风暴）
+1. 问平台
+2. SCAMPER + 多 agent 调研
+3. 生成 PRD + 原型
+
+### Planning（规划）
+1. 问平台
+2. 现状 + 理想态 + Gap + MVP
+3. 生成 PRD + 原型
+
+## 原型规则
+
+- 从模板开始（`.qoder/templates/prototype-{web|app}.html`），模板已有正确颜色
+- **不要单独读 vben-style-reference.json** — 模板里 CSS 变量已配好
+- 只改 diff 部分，新功能高亮
+- 单 HTML 文件，可交互
+- Web: 桌面布局 + 侧边栏；APP: 375px + 底部 tab
+
+## PRD 模板
+
+| 模式 | 模板 |
+|------|------|
+| Reference/Brainstorm/Planning | `.qoder/templates/prd-full-template.md` |
+| Quick | `.qoder/templates/prd-quick-template.md` |
+
+## 质量自检（10 项，Quick 跳过）
+1. 背景回答"为什么" 2. 目标可量化 3. 用户画像具体
+4. 业务规则完整 5. 异常覆盖(2+) 6. 验收可测(Given-When-Then)
+7. 数据事件完整 8. PRD 无技术实现 9. 优先级标注 10. 排期合理

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 自动路由。斜杠命令只是快捷入口。