merge: candidate agent-reply-llm-narrative-2026-09-28 into dev
This commit is contained in:
weichen
@@ -18,6 +18,7 @@
|
||||
|
||||
| owner | task | branch | worktree | mutex | status |
|
||||
|---|---|---|---|---|---|
|
||||
| Cursor | agent-reply-llm-narrative-2026-09-28 | feature/agent-reply-llm-narrative-2026-09-28 | .worktrees/agent-reply-llm-narrative-2026-09-28 | chat+coordinator | in_progress |
|
||||
| Cursor | test-user-doc-issues-2026-09-28 | fix/test-user-doc-issues-2026-09-28 | .worktrees/test-user-doc-issues-2026-09-28 | intent-write-verb | done |
|
||||
| Cursor | pi-runner-env-mismatch-2026-09-28 | fix/pi-runner-env-mismatch-2026-09-28 | .worktrees/pi-runner-env-mismatch-2026-09-28 | pi-runner-env | done |
|
||||
| Cursor | error-events-pg-roundtrip-2026-09-28 | feature/error-events-pg-roundtrip-2026-09-28 | .worktrees/error-events-pg-roundtrip-2026-09-28 | error-events-pg-evidence | done |
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: "助手回复智能体叙述优先"
|
||||
task_id: "agent-reply-llm-narrative-2026-09-28"
|
||||
status: in_progress
|
||||
created: 2026-09-28
|
||||
updated: 2026-09-28
|
||||
owner: Cursor
|
||||
task_type: implementation
|
||||
task_tier: multi_stage
|
||||
policy_revision: "agent-governance-2026-09-21-r1 @ 8f77053f5169502eaf3e4e4135a082e8914f3704"
|
||||
branch: feature/agent-reply-llm-narrative-2026-09-28
|
||||
worktree: .worktrees/agent-reply-llm-narrative-2026-09-28
|
||||
base_dev_sha: "8f77053f5169502eaf3e4e4135a082e8914f3704"
|
||||
write_scope: ["internal/coordinator", ".doc"]
|
||||
allowed_environments: ["dev"]
|
||||
head_sha: ""
|
||||
mutex: "chat+coordinator"
|
||||
review_state: pending
|
||||
integration_state: pending
|
||||
deployment: pending
|
||||
cleanup: pending
|
||||
cleanup_owner: "独立维护者"
|
||||
cleanup_trigger: "dev 合入且验收证据落盘后复查 worktree"
|
||||
remote_sync: not_requested
|
||||
---
|
||||
|
||||
# 助手回复智能体叙述优先
|
||||
|
||||
## 用户目标与授权
|
||||
|
||||
- 用户目标：助手回复尽可能由智能体生成，减少模板直答。授权来自本会话「实施助手回复智能化改造方案」。
|
||||
- 交付终点：T1/T2 叙述与 T3 结果通报走 PI Agent，失败回退模板；T4 安全话术保持模板；单测与 dev 真实 Runner 证据落盘后合入 local dev。
|
||||
- 禁止项：不 push、不晋升 test/main、不改确认卡结构与权限拒绝话术。
|
||||
- 例外：注册本任务前，`integrate-attachment-only-turn-2026-09-28` 以 scope `.` 仍为 active，但其分支已是当时 dev 祖先且队列为空。已将其 task state 记为 done 以解除 same_scope 硬门禁。未删除其 worktree。
|
||||
|
||||
## 范围与非目标
|
||||
|
||||
- 允许写入：`internal/coordinator` 叙述管道与意图 handler；本任务记录与测试报告。
|
||||
- 非目标：不改交互卡、挂起期望、澄清追问、权限不足与安全拦截文案的生成路径；不替换 `templates/docs` 交付物模板。
|
||||
|
||||
## 相关问题与经验
|
||||
|
||||
- issue_ids：无对应未关闭问题。
|
||||
- 开工检索 ISSUES / lessons INDEX（模板回复、答非所问、reply_source）：无命中可复用条目。
|
||||
- 不新增 lesson：本次是既有「LLM 优先、模板兜底」机制的扩展，尚未出现新的复发机制。
|
||||
|
||||
## 步骤与验收
|
||||
|
||||
1. [x] 统一 `narrateReply` / `applyNarrative`，事实块进入提示词，开关 `AGENT_REPLY_LLM_ENABLED`。
|
||||
2. [x] T1 查询、T2 帮助、T3 已受理/已完成通报接入；确认提问与权限拒绝不接入。
|
||||
3. [x] `go test -short ./...`、`go vet`、`arch-check --mode block`，以及 `RUN_PI_E2E=1` 的真实 Runner 叙述用例。验收见 [测试报告](../../test-reports/2026-09-28-agent-reply-llm-narrative-test-report.md)。
|
||||
|
||||
按 [验证契约](../2026-09-21-validation-contract.md)：Go 单测 + 产品 PI 受影响链路。
|
||||
|
||||
## 验证与证据
|
||||
|
||||
| 范围 / 被测 SHA | 命令与环境 | 预期 | 实际 / 判定 | 证据 / 脱敏说明 |
|
||||
|---|---|---|---|---|
|
||||
| coordinator 单测与全量 short | `go test -short ./...`；`arch-check --mode block`；`go vet ./...` | PASS | PASS | 见测试报告 |
|
||||
| 真实 Runner T1/T2/T3 | `RUN_PI_E2E=1 go test -run TestIntentReply_RealPI`，模型 MiniMax-M2.7-highspeed | reply_source=pi-agent | PASS（26.90s） | [测试报告](../../test-reports/2026-09-28-agent-reply-llm-narrative-test-report.md)；未记录 token |
|
||||
|
||||
## 收口与交接
|
||||
|
||||
- 剩余工作：真实 Runner 证据、合入 local dev。
|
||||
- 本地提交 / dev 集成 / 部署 / 远端：尚未提交。
|
||||
- cleanup：合入后由独立维护者复查。
|
||||
- 需求目录：`R-agent-reply-llm-narrative`。
|
||||
|
||||
## 相关链接
|
||||
|
||||
- 方案：助手回复智能化改造（LLM 叙述优先、模板兜底）
|
||||
@@ -0,0 +1,83 @@
|
||||
# 助手回复智能体叙述 测试报告
|
||||
|
||||
## 一、 测试背景 (Background)
|
||||
|
||||
项目助手大量查询、帮助和操作回执仍由 Go 硬编码模板直接返回。本轮把这些路径改为：系统先生成确定性事实底稿，再由产品 PI Agent Runner 组织自然语言；Runner 失败、开关关闭或无 backend 时回退原模板。安全拦截、权限不足和确认提问不进入叙述。
|
||||
|
||||
## 二、 测试目标 (Test Objectives)
|
||||
|
||||
- T1 权责查询、T2 能力帮助、T3 暂缓回执由真实 Runner 生成，`reply_source=pi-agent`，且保留底稿中的人名、文档名或项目名。
|
||||
- Runner 失败时回退模板，并记录 `agent_reply_fallback`。
|
||||
- 开关关闭时不调用 backend。
|
||||
- 安全拦截话术不被叙述改写。
|
||||
- 存量 `go test -short ./...` 与 `arch-check --mode block` 通过。
|
||||
|
||||
## 三、 测试方案与环境 (Test Plan & Environment)
|
||||
|
||||
- OS：Linux。Go 模块测试在任务 worktree `feature/agent-reply-llm-narrative-2026-09-28`，基线 dev `8f77053f5169502eaf3e4e4135a082e8914f3704`。
|
||||
- 真实 Runner：宿主机 `http://127.0.0.1:18865/health` 返回 200。模型按本机批准配置 `PI_AGENT_PROVIDER=minimax`、`PI_AGENT_MODEL=MiniMax-M2.7-highspeed`。凭证只从本机 `.env` 读取，不写入报告。
|
||||
- 层级：Go 单测（scripted backend）+ 受影响产品 PI 链路（`RUN_PI_E2E=1`）。未跑 nightly 五项全量，因为本变更不改工作流生成链。
|
||||
|
||||
## 四、 预期结果 (Expected Results)
|
||||
|
||||
- 有 backend 且开关开启：`ReplySource=pi-agent`，提示词含「系统确定性底稿」。
|
||||
- backend 返回失败：`ReplySource=template`，正文仍含模板标题「我能帮您做什么」。
|
||||
- `AGENT_REPLY_LLM` 测试开关关闭：不调用 backend。
|
||||
- `SECURITY_FORBIDDEN`：正文不含脚本注入的智能体改写句。
|
||||
- 真实 Runner 三轮均 `source=pi-agent`，且分别保留「张工/用户需求表」「查询/补充」「肌骨超声项目」。
|
||||
|
||||
## 五、 实际测试结果与判定 (Actual Results & Evaluation)
|
||||
|
||||
### 用例 1：真实 Runner T1/T2/T3
|
||||
|
||||
- **测试输入 (Input)**：`RUN_PI_E2E=1 go test -count=1 -timeout 8m -v ./internal/coordinator/ -run TestIntentReply_RealPI_NarratesQueryHelpAndDecline`
|
||||
- **实际输出 (Actual Output)**：
|
||||
|
||||
```text
|
||||
intent=QUERY_USER_RIGHTS source=pi-agent duration=8.919s
|
||||
intent=HELP_CAPABILITIES source=pi-agent duration=11.655s
|
||||
intent=DECLINE_EXPECTATION source=pi-agent duration=6.329s
|
||||
--- PASS: TestIntentReply_RealPI_NarratesQueryHelpAndDecline (26.90s)
|
||||
```
|
||||
|
||||
权责回复含「张工」与「用户需求表」；帮助回复含「查询项目进展与风险」「补充项目事实」，并保留「请前往项目设置界面」；暂缓回复含「肌骨超声项目暂不推进」。路由日志里的 `channel=TEMPLATE` 是 R0 意图通道名，不是回复来源；回复来源字段为 `pi-agent`。
|
||||
|
||||
- **评价判定**：PASS
|
||||
- **性能与耗时**：三轮合计 26.90s（8.919s / 11.655s / 6.329s）
|
||||
|
||||
### 用例 2：backend 失败回退模板
|
||||
|
||||
- **测试输入**：`go test -short -v -run TestIntentReply_BackendFailureFallsBackToTemplate`
|
||||
- **实际输出**：
|
||||
|
||||
```text
|
||||
INFO agent_reply_fallback handler=handleHelpCapabilities intent=HELP_CAPABILITIES reason="forced failure"
|
||||
--- PASS: TestIntentReply_BackendFailureFallsBackToTemplate (0.00s)
|
||||
```
|
||||
|
||||
- **评价判定**：PASS
|
||||
- **性能与耗时**：<1s（scripted backend，非真实 Runner）
|
||||
|
||||
### 用例 3：开关关闭与安全话术
|
||||
|
||||
- **测试输入**：`TestIntentReply_FlagOffKeepsTemplate`、`TestIntentReply_SecurityForbiddenStaysTemplate`
|
||||
- **实际输出**：两者 PASS。安全用例未调用 dialogue backend。
|
||||
- **评价判定**：PASS
|
||||
- **性能与耗时**：<1s
|
||||
|
||||
## 六、 自动化测试套件汇总 (Test Suite Execution)
|
||||
|
||||
| 检查 | 结果 |
|
||||
|---|---|
|
||||
| `./scripts/arch-check.sh --mode block` | PASS（production gate passed） |
|
||||
| `go vet ./...` | PASS（exit 0） |
|
||||
| `go test -short -count=1 -timeout 8m ./...` | PASS（含 `internal/coordinator` 0.042s、`internal/server` 20.498s） |
|
||||
| `RUN_PI_E2E=1` 叙述三轮 | PASS（26.90s） |
|
||||
|
||||
未运行 nightly 全量五项。不把未运行记为产品全链路 PASS。
|
||||
|
||||
## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
|
||||
|
||||
授权范围内的叙述改造达到本轮验收：真实 Runner 能在保留确定性事实的前提下改写查询、帮助和暂缓回执；失败与安全边界仍走模板。
|
||||
|
||||
后续可观察线上 `agent_reply_fallback` 比例，再决定是否把仍保持模板的确认提问也改为叙述。确认卡选项与权限拒绝本轮故意不改。
|
||||
Reference in New Issue
Block a user