177 lines
6.5 KiB
Markdown
177 lines
6.5 KiB
Markdown
# External Signal Recommendation Content Upgrade Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Make recommendation-only external signal-source answers produce concrete, business-natural candidates with reasons instead of abstract boundary talk.
|
|
|
|
**Architecture:** Keep the new interaction-boundary routing intact, but add a recommendation content layer in `external_query_service` that first builds a structured recommendation packet and then renders user-facing natural Chinese. Route correctness stays in semantic planning; candidate quality and wording live in the recommendation packet and presenter.
|
|
|
|
**Tech Stack:** Python 3.11, Pydantic, existing PMFlow LLM service, pytest
|
|
|
|
---
|
|
|
|
### Task 1: Lock Business-Natural Recommendation Expectations
|
|
|
|
**Files:**
|
|
- Modify: `backend/tests/test_external_query_planner.py`
|
|
- Modify: `backend/tests/test_feishu_card_action_contract.py`
|
|
|
|
- [ ] **Step 1: Write failing tests for concrete recommendation candidates**
|
|
|
|
Add tests that require:
|
|
- at least 3 concrete candidate signal-source types
|
|
- each candidate has a business reason
|
|
- different project contexts produce meaningfully different candidates
|
|
- answer text avoids architect jargon like “主链 / 这一层 / packet / analysis”
|
|
|
|
- [ ] **Step 2: Run focused tests to verify they fail**
|
|
|
|
Run:
|
|
```bash
|
|
cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && PYTHONPATH=backend /Users/yuuuu/Documents/AIProjectManger/backend/venv/bin/python -m pytest backend/tests/test_external_query_planner.py -k "signal_source_recommendation or recommendation" -q
|
|
```
|
|
|
|
Expected: FAIL on missing concrete candidates / wording assertions.
|
|
|
|
- [ ] **Step 3: Add Feishu rendering red tests**
|
|
|
|
Add a rendered-text test that requires final recommendation replies to look like business advice, not route/boundary analysis.
|
|
|
|
- [ ] **Step 4: Run Feishu recommendation tests to verify they fail**
|
|
|
|
Run:
|
|
```bash
|
|
cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && PYTHONPATH=backend /Users/yuuuu/Documents/AIProjectManger/backend/venv/bin/python -m pytest backend/tests/test_feishu_card_action_contract.py -k "recommendation" -q
|
|
```
|
|
|
|
Expected: FAIL on abstract / non-concrete output.
|
|
|
|
### Task 2: Add Recommendation Packet Contracts
|
|
|
|
**Files:**
|
|
- Modify: `backend/app/services/external_query_service/schemas.py`
|
|
- Modify: `backend/app/services/external_query_service/presenter.py`
|
|
|
|
- [ ] **Step 1: Add structured recommendation candidate models**
|
|
|
|
Define minimal packet models for:
|
|
- recommendation candidate name
|
|
- business value reason
|
|
- project relevance / watch point
|
|
|
|
- [ ] **Step 2: Add packet validation tests implicitly through presenter tests**
|
|
|
|
No separate schema-only test unless needed; keep packet surface small.
|
|
|
|
### Task 3: Build Concrete Recommendation Candidates
|
|
|
|
**Files:**
|
|
- Modify: `backend/app/services/external_query_service/presenter.py`
|
|
- Modify: `backend/app/config/ai_prompts_catalog/part_scenes_06.py`
|
|
- Modify: `backend/app/config/ai_prompts.py`
|
|
- Modify: `backend/app/config/ai_prompts_catalog/__init__.py`
|
|
|
|
- [ ] **Step 1: Build a structured recommendation packet first**
|
|
|
|
Implement presenter flow:
|
|
- use `generate_structured_object` when available
|
|
- grounded by project summary, recommendation goal, object anchors, objectives, and source summaries
|
|
- fallback to deterministic business-safe packet if structured generation fails
|
|
|
|
- [ ] **Step 2: Render packet into natural business Chinese**
|
|
|
|
Render to:
|
|
- one short lead sentence
|
|
- `1 / 2 / 3` concrete candidates
|
|
- each with a plain-language reason
|
|
- one short caveat that this is recommendation, not confirmed integration
|
|
|
|
- [ ] **Step 3: Keep wording constraints**
|
|
|
|
Reject or rewrite answers that:
|
|
- leak internal terms
|
|
- drift into architecture tone
|
|
- only say “信息不足 / 先不判断”
|
|
|
|
- [ ] **Step 4: Run focused tests and make them pass**
|
|
|
|
Run:
|
|
```bash
|
|
cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && PYTHONPATH=backend /Users/yuuuu/Documents/AIProjectManger/backend/venv/bin/python -m pytest backend/tests/test_external_query_planner.py backend/tests/test_feishu_card_action_contract.py -k "recommendation" -q
|
|
```
|
|
|
|
Expected: PASS
|
|
|
|
### Task 4: Verify Project Variation and Runtime Safety
|
|
|
|
**Files:**
|
|
- Modify: `backend/tests/test_external_query_planner.py`
|
|
- Modify: `backend/tests/test_feishu_card_action_contract.py`
|
|
|
|
- [ ] **Step 1: Add cross-project variation checks**
|
|
|
|
Use business scenarios such as:
|
|
- 自动开票系统
|
|
- AI客服
|
|
- 门店库存异常日报助手
|
|
|
|
Require that candidate sets differ in sensible ways.
|
|
|
|
- [ ] **Step 2: Run broader affected backend slice**
|
|
|
|
Run:
|
|
```bash
|
|
cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && PYTHONPATH=backend /Users/yuuuu/Documents/AIProjectManger/backend/venv/bin/python -m pytest backend/tests/test_external_query_planner.py backend/tests/test_feishu_card_action_contract.py backend/tests/test_ai_pmo_ingress_mainline.py -q
|
|
```
|
|
|
|
Expected: PASS
|
|
|
|
### Task 5: Final Verification and Runtime Refresh
|
|
|
|
**Files:**
|
|
- Modify if behavior/docs changed: `docs/architecture/RUNTIME_GUARDRAILS.md`, `docs/architecture/CODE_REFERENCE_INDEX.md`, `docs/architecture/ARCHITECTURE_INVENTORY.md`, `CLAUDE.md`
|
|
|
|
- [ ] **Step 1: Run compile verification**
|
|
|
|
Run:
|
|
```bash
|
|
cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && python3 -m py_compile backend/app/services/external_query_service/presenter.py backend/app/services/external_query_service/schemas.py
|
|
```
|
|
|
|
Expected: no output
|
|
|
|
- [ ] **Step 2: Rebuild backend**
|
|
|
|
Run:
|
|
```bash
|
|
cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && docker compose -p aiprojectmanger --env-file /Users/yuuuu/Documents/AIProjectManger/.env up -d --build backend
|
|
```
|
|
|
|
Expected: backend container recreated successfully
|
|
|
|
- [ ] **Step 3: Check health**
|
|
|
|
Run:
|
|
```bash
|
|
curl -s http://127.0.0.1:8000/healthz
|
|
```
|
|
|
|
Expected:
|
|
```json
|
|
{"code":0,"message":"success","data":{"status":"ok"}}
|
|
```
|
|
|
|
- [ ] **Step 4: Export business-style live IO samples**
|
|
|
|
Capture 3-5 recommendation examples with:
|
|
- natural business inputs
|
|
- final model reply
|
|
- per-case score
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add backend/app/services/external_query_service backend/tests docs/architecture CLAUDE.md docs/superpowers/plans/2026-04-19-external-signal-recommendation-content-upgrade.md
|
|
git commit -m "feat: improve external signal recommendation content"
|
|
```
|