diff --git a/.cursor/skills/README.md b/.cursor/skills/README.md index 8ac0bd2d..21451456 100644 --- a/.cursor/skills/README.md +++ b/.cursor/skills/README.md @@ -20,6 +20,7 @@ | [`harness-loop-batch/`](harness-loop-batch/SKILL.md) | [`docs/tasks/skills/SKILL-harness-loop-batch.md`](../../docs/tasks/skills/SKILL-harness-loop-batch.md) | | [`docs-governance/`](docs-governance/SKILL.md) | [`docs/tasks/skills/SKILL-docs-governance.md`](../../docs/tasks/skills/SKILL-docs-governance.md) | | [`harness-task/`](harness-task/SKILL.md) | [`docs/tasks/skills/SKILL-harness-task.md`](../../docs/tasks/skills/SKILL-harness-task.md) | +| [`harness-looptask-handoff/`](harness-looptask-handoff/SKILL.md) | [`docs/tasks/skills/SKILL-harness-looptask-handoff.md`](../../docs/tasks/skills/SKILL-harness-looptask-handoff.md) | ## 修订记录 @@ -28,3 +29,4 @@ | 2026-05-24 | 初版：双轨说明 + `harness-meta-reinspect`（来源 P2-1 元复检） | | 2026-05-26 | 新增 `harness-loop-batch`（Wiki Loop A1–A4 蒸馏） | | 2026-05-27 | 新增 `docs-governance`、`harness-task`；`harness-loop-batch` 同步 v1.8 | +| 2026-06-01 | 新增 `harness-looptask-handoff`（LoopTask 止于 50 · 50 Prompt / 签收 / 人改 gate 表） | diff --git a/.cursor/skills/harness-looptask-handoff/SKILL.md b/.cursor/skills/harness-looptask-handoff/SKILL.md new file mode 100644 index 00000000..2c6023ab --- /dev/null +++ b/.cursor/skills/harness-looptask-handoff/SKILL.md @@ -0,0 +1,32 @@ +--- +name: harness-looptask-handoff +description: >- + LoopTask stop_after_hat:50 后交付 50 全文 Prompt、R1/R2/50 签收路径、以及人改 human_gate + 的「文件+表格字段+改前值→改后值」表。用于 CLOSE、HG-REINSPECT、Portfolio 跨仓关账。 + Use when looptask ends at 50, user asks for reinspect handoff, or manual gate edit checklist. +disable-model-invocation: true +--- + +# Harness LoopTask 交接（后端 · 止于 50） + +> **便携真值（跨 Agent）**：[`docs/tasks/skills/SKILL-harness-looptask-handoff.md`](../../docs/tasks/skills/SKILL-harness-looptask-handoff.md) +> **配对前端 skill**：`ai-ink-brain/.cursor/skills/harness-looptask-handoff/SKILL.md` + +## 硬规则（摘要） + +1. **50 Prompt**：占位符全替换 · 对话贴 **Handoff + §5 正文** · 禁止只给链接 +2. **签收清单**：R1 · R2 · 40 自检节 · 50 reinspect · invoke 链 · **写实际相对路径** +3. **人改 gate**：**禁止**笼统；**必须**表格式「文件 | 位置 | 改什么」 +4. **禁止 Agent**：代签 `HG-REINSPECT` · 代填 `### KPI（00）` · 擅自 `git mv` done + +## 本子仓路径速查 + +| 类型 | 路径 | +|------|------| +| task | `docs/tasks/active/task_*.md` | +| reviews | `docs/harness/reviews/by-task//` | +| invokes | `docs/harness/invokes/by-task//` | +| reinspect | `docs/tasks/reinspect_results/` | +| CLOSE | `docs/harness/prompts/handoff/HANDOFF_CLOSE_TRACE.md` | + +完整条文、Portfolio 跨仓示例、关账步骤 → **读便携真值 MD**（上链）。 diff --git a/docs/diary/samples/portfolio-rag-demo/NOTES-ci-plan-token-test-fix_20260601.md b/docs/diary/samples/portfolio-rag-demo/NOTES-ci-plan-token-test-fix_20260601.md new file mode 100644 index 00000000..34e66e30 --- /dev/null +++ b/docs/diary/samples/portfolio-rag-demo/NOTES-ci-plan-token-test-fix_20260601.md @@ -0,0 +1,94 @@ +# PR #101 CI：plan_execution_token 测试碰撞 · 复盘 + +> **日期**：2026-06-01 +> **PR**：[#101](https://github.com/Cyning12/ai-ink-brain-api-python/pull/101) · `task/portfolio-rag-demo-v1` +> **修复 commit**：`1823ba7` +> **关联测试**：`tests/test_unified_chat_backend_v2_agent.py::test_v3_plan_execution_token_invalid_json_denies_bypass` + +--- + +## 1. 现象 + +portfolio 文档 PR 的 CI 中 **pytest 红**，失败断言： + +```text +assert 'agent.clarify' in types_bad +``` + +表象像 Unified Chat 低置信澄清回归；**与 portfolio 文档改动无直接关系**（全仓 pytest 扫到既有用例）。 + +--- + +## 2. 根因 + +测试用「末位 base64 字符 `A`↔`B`」构造「无效」`plan_execution_token`： + +```python +tampered = tok[:-1] + ("A" if tok[-1] != "A" else "B") +``` + +在 **urlsafe base64** 下，末位有时只编码 **padding 位**。`A` 与 `B` 可能解码为**相同字节**，HMAC 验签仍通过 → 请求走全量 Text2SQL，不出现 `agent.clarify`。 + +本地可复现（示例）： + +| 操作 | `verify_clarify_plan_bypass_token` | +| --- | --- | +| 原 token | True | +| 末位 A→B（碰撞） | **True**（测试误以为已无效） | +| 中间字符翻转 | False | + +**结论**：实现逻辑正确；是测试篡改策略不可靠，非 ChatBI / portfolio 业务 bug。 + +--- + +## 3. 修复 + +改为翻转 **中间字符**，稳定构造无效 token： + +```python +mid = max(1, len(tok) // 2) +tampered = tok[:mid] + ("X" if tok[mid] != "X" else "Y") + tok[mid + 1 :] +``` + +--- + +## 4. 经验（可复用） + +### 4.1 文档 PR 也会跑全量 pytest + +后端 **任何 PR** 均跑 `pytest tests -m "not intent_eval and not intent_benchmark"`。文档-only 分支也可能因**无关测试**挡 merge。排查时先看失败栈是否在本 PR diff 内。 + +### 4.2 负向安全/鉴权测试的写法 + +1. 篡改后 **先断言** `verify_*()` 为 `False`，再测 HTTP 行为。 +2. **勿依赖** base64 末位单字符翻转 — 存在编码等价碰撞。 +3. 更稳的无效 token：中间位翻转、`tok + "x"`、或手工损坏 JSON/HMAC 段。 + +### 4.3 与 portfolio 鉴权勿混读 + +| 场景 | 机制 | +| --- | --- | +| 五问 Unified Chat | Bearer → `chatbi_access_tokens` 查库 | +| admin/sync ingest | `SYNC_ADMIN_SECRET`（前端）/ `CHAT_API_SECRET`（后端）同值 | + +本次失败与 admin/sync 迁移、五问 token **无关**。 + +### 4.4 CI 排查顺序（简表） + +- [ ] 失败是否在本 PR 改动文件内？ +- [ ] 本地单测能否复现？中间层（如 `verify_*`）结果如何？ +- [ ] flaky / 测试假设错 vs 实现回归？ +- [ ] 最小修复：只动测试还是动实现？ + +--- + +## 5. CI 结果（修复后） + +| Check | 结果 | +| --- | --- | +| pytest | pass | +| verify | pass | +| task_validate | pass | +| contract_check / manifest_check | pass | + +PR #101 Required checks 全绿，可 merge。 diff --git a/docs/diary/samples/portfolio-rag-demo/README.md b/docs/diary/samples/portfolio-rag-demo/README.md new file mode 100644 index 00000000..392b476b --- /dev/null +++ b/docs/diary/samples/portfolio-rag-demo/README.md @@ -0,0 +1,26 @@ +# Portfolio RAG Demo · 五问预跑留证（W5） + +> **task**：`docs/tasks/active/task_portfolio_rag_demo_v1.md` +> **RUNBOOK**：[`docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md`](../../../harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md) §6 +> **状态**：**待人执行** sync + 五问后落盘（Agent **禁止**代跑生产 sync） + +## 预期文件（留证清单） + +| 文件 | 说明 | +| --- | --- | +| `sync-job-final.json` | admin/sync job 终态摘要（脱敏） | +| `q1-sources-run1.json` / `q1-sources-run2.json` | Q1 两次预跑 sources | +| `q5-sources-run1.json` / `q5-sources-run2.json` | Q5 两次预跑 sources | +| `five-questions-results.md` | 五问 pass/fail + 重试次数 + category 摘要 | +| `screenshots/` | 可选 · 录屏帧或 Unified Chat 截图 | + +## 人工闸 + +- `HG-W5-SYNC`：sync `succeeded` 后人签 +- `HG-W5-FIVE-Q`：五问达标 + 本目录留证后人签 + +## 过程备忘（非 W5 留证） + +| 文件 | 说明 | +| --- | --- | +| [`NOTES-ci-plan-token-test-fix_20260601.md`](NOTES-ci-plan-token-test-fix_20260601.md) | PR #101 CI：plan token 测试 base64 碰撞复盘 · commit `1823ba7` | diff --git a/docs/harness/README.md b/docs/harness/README.md index 308b47e8..1c8a879a 100644 --- a/docs/harness/README.md +++ b/docs/harness/README.md @@ -15,6 +15,7 @@ | **三方复检** | `TEMPLATE-independent-reinspect` → [`../tasks/reinspect_results/`](../tasks/reinspect_results/README.md) | | 半自动 / 人工闸 | `HANDOFF_SEMI_AUTO` | | commit / 关账 | `HANDOFF_AUTO_COMMIT`、`HANDOFF_CLOSE_TRACE` | +| **LoopTask 止于 50 · 50 Prompt / 人改 gate 清单** | [`docs/tasks/skills/SKILL-harness-looptask-handoff.md`](../tasks/skills/SKILL-harness-looptask-handoff.md) · 安装 Prompt：[`prompts/PROMPT_install_harness_looptask_handoff_skill_v1_zh.md`](prompts/PROMPT_install_harness_looptask_handoff_skill_v1_zh.md) | | task 字段 | `HARNESS_V2_PLAN.md` §5 | | **KPI 评分 v1.2** | [`guides/KPI_RUBRIC_v1_2.md`](guides/KPI_RUBRIC_v1_2.md) · HatInstance / Task_KPI% | | **总调度 00** | [`prompts/hats/00-orchestrator.md`](prompts/hats/00-orchestrator.md) · [`TEMPLATE-orchestrator-invoke`](prompts/templates/TEMPLATE-orchestrator-invoke.md) | diff --git a/docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md b/docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md new file mode 100644 index 00000000..8712db9e --- /dev/null +++ b/docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md @@ -0,0 +1,184 @@ +# RUNBOOK — Portfolio 演示站 RAG 同源 sync 与五问验收（v1） + +| 项 | 内容 | +| --- | --- | +| **freeze_id** | `PORTFOLIO-RAG-DEMO@2026-06-01` | +| **关联 SPEC** | [`SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md`](../../spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md) | +| **投递计划** | [`投递冲刺_20260609_v1_zh.md`](../../spec/governance/投递冲刺_20260609_v1_zh.md) §2 | +| **env 真值** | [`PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md`](../../meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md) §C.1 | +| **留证目录** | [`docs/diary/samples/portfolio-rag-demo/`](../../diary/samples/portfolio-rag-demo/) | +| **入库路径** | **仅** `POST /api/py/admin/sync`（**禁止**本 RUNBOOK 使用 `admin/ingest` 备用） | + +--- + +## §1 前提与权限 + +### 1.1 执行环境 + +| 项 | 要求 | +| --- | --- | +| **五问预跑环境** | **预发 / Preview 与生产等价**：同 Supabase 项目、同 `EMBEDDING_DIM`、同 `CONTENT_ROOT` 挂载语义（SPEC Q-3） | +| **演示 URL** | portfolio 模式同一 Vercel 项目（如 `https://ai-ink-brain.vercel.app/unified-chat`）；BFF 转发至 Python API | +| **RAG 入口** | **`POST /api/py/unified/chat`** 或 **`/stream`**；Bearer **visitor** ChatBI token（**不禁 text2sql** · T-05） | +| **CONTENT_ROOT** | **必须**显式指向前端仓 `ai-ink-brain/content/`；**禁止**生产依赖后端仓 `REPO_ROOT/content` 回退 | + +### 1.2 前置检查（sync 前） + +```bash +# 1) 确认 CONTENT_ROOT 为目录且含三类文稿（目标态） +test -d "$CONTENT_ROOT/methodology" && test -d "$CONTENT_ROOT/resume" && test -d "$CONTENT_ROOT/evidence" +find "$CONTENT_ROOT/methodology" "$CONTENT_ROOT/resume" "$CONTENT_ROOT/evidence" -name '*.md' | head + +# 2) 确认 Python 服务可读 env（本地示例） +# CONTENT_ROOT=/path/to/ai-ink-brain/content +``` + +### 1.3 鉴权（不写明文密钥） + +| 用途 | Header | Secret 来源 | +| --- | --- | --- | +| **admin/sync** | `Authorization: Bearer `（推荐） | 前端 **`SYNC_ADMIN_SECRET`** 或 Python `CHAT_API_SECRET` / 服务端 admin 同值；**禁止** Portfolio 文档写 `NEXT_PUBLIC_ADMIN_SECRET` | +| **admin/sync（BFF 本地）** | `Authorization: Bearer $SYNC_ADMIN_SECRET` | 本仓 `.env.local` · **服务端 only** | +| **Unified Chat 五问** | `Authorization: Bearer ` | 邮件申请 visitor 秘钥（见投递计划 §3.4） | + +--- + +## §2 Sync 执行 + +### 2.1 创建 job + +```bash +export PY_API_URL="https://" # 或本地 http://127.0.0.1:8000 +export ADMIN_TOKEN="<从 Secrets 读取，勿写入 Git>" + +curl -sS -X POST "$PY_API_URL/api/py/admin/sync" \ + -H "Authorization: Bearer $ADMIN_TOKEN" \ + -H "Content-Type: application/json" +``` + +**期望**：HTTP **202**，响应含 `job.id` 与 `statusUrl`（形如 `/api/py/admin/sync?jobId=`）。 + +### 2.2 轮询 + +```bash +export JOB_ID="<上一步 job.id>" + +while true; do + curl -sS "$PY_API_URL/api/py/admin/sync?jobId=$JOB_ID" \ + -H "Authorization: Bearer $ADMIN_TOKEN" | tee /tmp/sync-job.json + STATUS=$(python3 -c "import json,sys; print(json.load(open('/tmp/sync-job.json'))['job']['status'])") + echo "status=$STATUS" + case "$STATUS" in + succeeded|failed) break ;; + *) sleep 3 ;; + esac +done +``` + +| 参数 | 值 | +| --- | --- | +| 轮询间隔 | **2～5s** | +| 总超时 | **≤60 min** | + +### 2.3 成功硬检查（全部满足才进入 §4 五问） + +| 检查项 | 阈值 | +| --- | --- | +| `job.status` | **`succeeded`** | +| `result.filesScanned` | **`> 0`**（`=0` 记 **FAIL** · Q-4） | +| `result.chunksUpserted` | **`> 0`** | +| 目录覆盖 | `methodology/`、`resume/`、`evidence/` **各 ≥1** 个 `.md` 被扫描 | + +**留证**：将终态 JSON 摘要保存至 `docs/diary/samples/portfolio-rag-demo/sync-job-final.json`（可删敏感字段）。 + +--- + +## §3 Sync 失败排障 + +| 错误特征 | 含义 | 处置 | 可重试 | +| --- | --- | --- | --- | +| `Embedding 维度为 … 与期望 … 不一致` | `EMBEDDING_DIM` 与 `vector(N)` 不一致 | 对齐 env 与 `supabase/sql/init.sql`；**勿**临时改库维度 | 修正后重跑 sync | +| `CONTENT_ROOT=… 不是目录` / `filesScanned=0` | 路径错或目录空 | 修正 mount；补三类 content 后再 sync | 是 | +| SiliconFlow / Supabase 失败 | 上游或密钥 | 查 `SILICONFLOW_API_KEY`、Supabase service role | 指数退避 | +| **`404 Job not found`** | redeploy / 单实例 job 丢失 | **重新 `POST`** 创建 job；sync 窗口 **避免** 并发 redeploy | 是 | +| ingest `400` + 「维度」 | 同维度不匹配 | 同上 Embedding 行 | 修正后重跑 | + +--- + +## §4 五问验收表 + +**通过口径**：**5/5** 非空切题；sources **≥4/5**；单问 **≤3** 次重试仍不达标则记 **FAIL**。 + +| # | 标准问句（chip 可粘贴） | 期望 `content/` 路径 | sources 主 `metadata.category` | 合格要点 | +| --- | --- | --- | --- | --- | +| **Q1** | 《AI 编程可闭环协作》**卷三**讲什么？Harness 和签收是什么？ | `methodology/vol3_*` | **`methodology`** | 任务单 + 书面签收 + 合并前 CI；sources 含 vol3 | +| **Q2** | **RAG 混合检索**怎么做的？ | `resume/*` | **`resume`** | 向量 + 混合检索 + rerank 至少两项 | +| **Q3** | **冷/温/热** 和 **架构三层** 区别？ | `evidence/*` | **`evidence` only** | 记忆分层 ≠ 架构分层；**methodology vol3 不计 Q3 通过** | +| **Q4** | **11 年经历**里 AI Coding 相关成果？ | `resume/*` | **`resume`** | 百果园 Cursor + Ink + 连载；不虚构 | +| **Q5** | 按需读图相对整图灌入 **token/效果**？**边界**？ | `evidence/*` | **`evidence`** | 约 1/9 或「约十分之一」+ **小样本、非全行业** | + +**Unified 调用示例（JSON）**： + +```bash +curl -sS -X POST "$PY_API_URL/api/py/unified/chat" \ + -H "Authorization: Bearer $VISITOR_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"query":"<上表问句>","session_id":"portfolio-five-q-smoke"}' \ + -D /tmp/unified-headers.txt | tee /tmp/unified-response.json +# sources：响应 JSON events 内 rag.sources，或响应头 x-sources（若 BFF 透传） +``` + +术语纠偏见 [`GUIDE_冷温热层_对内术语_v1_zh.md`](./GUIDE_冷温热层_对内术语_v1_zh.md)。 + +--- + +## §5 单问重试规则 + +1. 同一问 **最多 3 次**（可调 chip 文案或 session，**不得**刷通过率）。 +2. 第 3 次仍不达标 → 该问记 **FAIL**，写入留证表 blocker 列。 +3. 若多问 FAIL → 阻塞 6/9 全绿；须补 content 或修正 ingest 后 **重新 sync** 再跑。 + +--- + +## §6 Sources 留证 + +| 项 | 要求 | +| --- | --- | +| **强制** | **Q1**、**Q5** 保存 sources JSON（或 SSE `rag.sources` 片段） | +| **可复现** | 同 visitor token、**同问句** 预跑 **2 次**；主 `metadata.category` **须一致**（不一致记 FAIL · Q-9:A） | +| **落盘** | `docs/diary/samples/portfolio-rag-demo/q1-sources-run{1,2}.json`、`q5-sources-run{1,2}.json` | +| **五问汇总** | `five-questions-results.md`：问句 / pass-fail / 重试次数 / sources category 摘要 | + +--- + +## §7 卷四 / 卷五 release 后再 sync + +| 步骤 | 动作 | +| --- | --- | +| 1 | 公众仓卷四/卷五 release 后，确认 `content/methodology/` 已更新 | +| 2 | **24h 内**对同一 `CONTENT_ROOT` 执行 §2 sync | +| 3 | sync `succeeded` 后跑 **五问 smoke**（至少 **Q1 + Q5**） | +| 4 | sync `failed` → **不得**对外宣称 RAG 语料已更新 | + +--- + +## §8 附录 · 环境变量 + +完整表见 [`PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md`](../../meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md) **§C.1 Portfolio 演示站**。 + +| 变量 | portfolio 要点 | +| --- | --- | +| `CONTENT_ROOT` | 前端 `ai-ink-brain/content` 绝对路径 | +| Python `CHAT_API_SECRET` / `NEXT_PUBLIC_ADMIN_SECRET` | Python 进程 admin/sync 鉴权（**服务端** `.env`） | +| 前端 `SYNC_ADMIN_SECRET` | BFF 入站 + 转发 Bearer（**与 Python 同值** · shell 别名 `ADMIN_TOKEN`） | +| `EMBEDDING_DIM` | 与 Supabase `vector(N)` 一致（默认 1024） | +| `SILICONFLOW_API_KEY` | Embedding 必填 | +| `DEBUG_INGEST` | 生产 **关闭** | + +--- + +## 修订记录 + +| 日期 | 摘要 | +| --- | --- | +| 2026-06-01 | v1：30 帽落盘 · 对齐 `PORTFOLIO-RAG-DEMO@2026-06-01` | diff --git a/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_10_portfolio-rag-demo-requirements.md b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_10_portfolio-rag-demo-requirements.md new file mode 100644 index 00000000..ae593d44 --- /dev/null +++ b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_10_portfolio-rag-demo-requirements.md @@ -0,0 +1,64 @@ +# Invoke · 10 需求帽 · Portfolio RAG Demo task 草案 + +| 项 | 内容 | +| --- | --- | +| **帽** | 10 · 需求与任务分析 | +| **task_slug** | `portfolio-rag-demo` | +| **git_branch** | `task/portfolio-rag-demo-v1`（建议；10 帽可确认或调整） | +| **Open Folder** | `ai-ink-brain-api-python` | +| **freeze_id** | `PORTFOLIO-RAG-DEMO@2026-06-01` | +| **上游** | Prompt 00 SPEC 细化已关账（3/5 轮 · `active`） | +| **日期** | 2026-06-01 | + +--- + +## 快照（§3 全文 · 占位符已替换） + +```text +你正在扮演工作区 Harness「需求与任务分析帽」，严格遵循： +- docs/harness/prompts/hats/10-requirements.md（身份、只做什么、禁止什么、输出形状、停止条件、交接物） +- docs/harness/HARNESS_V2_PLAN.md §5（与 task 字段对齐时可引用） +- docs/spec/SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md（**SDD 三轮** · §4 待确认清单 · §5 完成后下一棒） + +输入（已由人工替换占位符；若你仍看到 {{…}} 字样，须先追问用户，不得开工）： + +【目标与上下文】 +冻结 SPEC `PORTFOLIO-RAG-DEMO@2026-06-01` 已 active。请从 `docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md` §7 工作包（W2 RUNBOOK · W3 env 文档 · W5 预跑留证）拆出本仓 **`docs/tasks/active/task_portfolio_rag_demo_v1.md`** 可执行 task 草案。硬 deadline：**2026-06-09** 投递前 ingest 对齐 + 五问 RUNBOOK + 预发/生产等价环境 sync 与五问预跑留证。**禁止**改 `api/`/`tests/` 业务实现（本帽仅 task）；**禁止**执行生产 `admin/sync`。 + +【已有材料路径或粘贴说明】 +ai-ink-brain-api-python/docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md +ai-ink-brain-api-python/docs/spec/governance/投递冲刺_20260609_v1_zh.md +ai-ink-brain-api-python/docs/spec/governance/PROMPT_00_SPEC-refine_Portfolio-RAG-Demo-v1_zh.md（只读 · 已关账） +ai-ink-brain/content/tasks/specs/SPEC-portfolio_demo_site_v1_zh.md（配对前端 · 只读） +ai-ink-brain-api-python/docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md（§C CONTENT_ROOT · §F admin/sync） + +【是否按任务审核文档回填】（无则写「无」；有则写相对路径） +无 + +【SDD 三轮状态】（§2 合法取值之一） +轮0+1+2 已完成，清单已人确认 + +【是否新建或重大修订 SPEC】 +否 + +你必须完成： +0. **Invoke 快照（开帽起点）**：在输出下列第 1 条起的实质性结果之前，先将 **本用户消息全文**（= 本模板 §3、占位符已全部替换）按 docs/harness/invokes/README.md 落盘到 `docs/harness/invokes/by-task//`（含元数据表 + 快照 fenced code）。同一会话内追问 **不** 再新增快照文件。 +1. **SDD 纪律（硬）**： + - 若 `否` = **是**：须遵守三轮模型（§1）；**禁止** 在本帽一次生成整本 L1 SPEC。 + - 若 `轮0+1+2 已完成，清单已人确认`：可据 §下一棒 A/B 规则推荐 A 或 B；**三轮完成 ≠ 自动跳过 22**（见 SPEC §5）。 + - 若 `否` 且状态 = **`轮0+1+2 已完成，清单已人确认`**：跳过待确认清单，直接 task 定稿。 +2. 输出结构化块：背景 / 范围 / 非范围 / 依赖链接 / 验收列表 / failure_paths / 给执行帽的必读列表；矛盾单独小节（若有）。 +2. 注明建议 test_strategy（required | recommended | not_applicable）及 test_strategy_note（若 not_applicable 须附理由）。 + - SPEC §7 建议：`test_strategy: recommended`；`failure_paths` 含 sync 维度失败、空 CONTENT_ROOT、job 404、五问 sources 不足。 + - task 元信息须含：`freeze_id: PORTFOLIO-RAG-DEMO@2026-06-01`、`semi_auto: true`（若适用）、`audit_profile: post_close`。 +3. 若 AUDIT 路径非「无」：按该审查文档的回填清单逐条映射到 task 小节建议，并在建议文末注明「按审查 R 回填」应指向的文件名。 +4. 禁止：写业务实现代码；改 CI；在 task 中写绝对本机路径；把未在依赖中声明的契约当真值；执行生产 sync。 +5. 对话回复 — **下一棒须输出两条 Prompt（由人择一执行，不可只给一条）**： + - 先输出 **推荐判定**（1～3 行）：依据 10-requirements §下一棒 A/B 与 task 元信息；本 Epic 以 **docs 为主 + 人工 RUNBOOK**，推荐 **路径 A（22）** 除非人明示 hotfix。 + - **路径 A · 22 任务审核**：标题 `### 下一棒 A：22 任务审核 R1（推荐）`。正文 = TEMPLATE-task-audit-invoke §3 全文（占位符指向 `task_portfolio_rag_demo_v1`）。 + - **路径 B · 30 执行（跳过 22）**：标题 `### 下一棒 B：30 执行（跳过 22）`。正文 = TEMPLATE-execute-invoke §3 全文。 +6. 回复末尾输出 HANDOFF_SEMI_AUTO §3.4 `📋 Harness 状态栏（版本 B）`。 +7. **自动 commit**：若本轮已落盘 invoke 或已按用户授权写入 task，按 HANDOFF_AUTO_COMMIT 分仓 commit。用户写明「不要 commit」则跳过。 + +**task 落盘路径（硬）**：`docs/tasks/active/task_portfolio_rag_demo_v1.md`（本仓；禁止只写工作区 invokes 不落 task）。 +``` diff --git a/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_10_portfolio-rag-demo.md b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_10_portfolio-rag-demo.md new file mode 100644 index 00000000..87c76750 --- /dev/null +++ b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_10_portfolio-rag-demo.md @@ -0,0 +1,49 @@ +# Invoke 快照 · 10 需求 · portfolio-rag-demo + +| 字段 | 值 | +|------|-----| +| hat_id | 10 | +| task_slug | portfolio-rag-demo | +| task_path | docs/tasks/active/task_portfolio_rag_demo_v1.md | +| git_branch | task/portfolio-rag-demo-v1 | +| freeze_id | PORTFOLIO-RAG-DEMO@2026-06-01 | +| date | 20260601 | +| sdd_status | 轮0+1+2 已完成，清单已人确认 | +| new_or_major_spec | 否 | + +--- + +## §3 调用体（快照） + +```text +你正在扮演工作区 Harness「需求与任务分析帽」，严格遵循： +- docs/harness/prompts/hats/10-requirements.md +- docs/harness/prompts/templates/TEMPLATE-requirements-invoke.md §3 +- docs/harness/HARNESS_V2_PLAN.md §5 +- docs/spec/SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md §5 + +Open Folder = ai-ink-brain-api-python +git_branch = task/portfolio-rag-demo-v1 + +【目标与上下文】 +冻结 SPEC `PORTFOLIO-RAG-DEMO@2026-06-01` 已 active。请从 `docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md` §7 工作包（W2 RUNBOOK · W3 env 文档 · W5 预跑留证）拆出本仓 **`docs/tasks/active/task_portfolio_rag_demo_v1.md`** 可执行 task 草案。硬 deadline：**2026-06-09** 投递前 ingest 对齐 + 五问 RUNBOOK + 预发/生产等价环境 sync 与五问预跑留证。**禁止**改 `api/`/`tests/` 业务实现（本帽仅 task）；**禁止**执行生产 `admin/sync`。 + +【已有材料路径】 +docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md +docs/spec/governance/投递冲刺_20260609_v1_zh.md +ai-ink-brain/content/tasks/specs/SPEC-portfolio_demo_site_v1_zh.md（配对前端 · 只读） +docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md + +【审查回填】无 +【SDD 状态】轮0+1+2 已完成，清单已人确认 +【新建 SPEC】否 + +你必须完成： +0. Invoke 落盘 → docs/harness/invokes/by-task/portfolio-rag-demo/ +1. 写 task 草案 → docs/tasks/active/task_portfolio_rag_demo_v1.md（含 freeze_id、failure_paths、test_strategy: recommended、semi_auto、audit_profile: post_close） +2. 输出下一棒 A（22 任务审核 R1 · 推荐）与 B（30 执行）**全文**，由人择一 +3. 回复末尾 Harness 状态栏（版本 B） +4. 用户未说「不要 commit」时，落盘 task + invoke 后 commit + +【人择路径】下一棒已选 A（22 任务审核 R1）；与前端 portfolio task 审查节奏对齐。 +``` diff --git a/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_22_portfolio-rag-demo.md b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_22_portfolio-rag-demo.md new file mode 100644 index 00000000..9ad01868 --- /dev/null +++ b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_22_portfolio-rag-demo.md @@ -0,0 +1,22 @@ +# Invoke 快照 · 22 任务审核 · portfolio-rag-demo + +| 字段 | 值 | +|------|-----| +| hat_id | 22 | +| task_slug | portfolio-rag-demo | +| task_path | docs/tasks/active/task_portfolio_rag_demo_v1.md | +| git_branch | task/portfolio-rag-demo-v1 | +| freeze_id | PORTFOLIO-RAG-DEMO@2026-06-01 | +| audit_round | R1 | +| date | 20260601 | +| review_path | docs/harness/reviews/by-task/portfolio-rag-demo/task_portfolio_rag_demo_v1_audit_R1_20260601.md | + +--- + +## §3 调用体（快照） + +```text +22 任务审核 R1 · semi_auto 链 · task_portfolio_rag_demo_v1 +结论：零阻塞 · HG-AUDIT-R1 approved · 30 可开工 W2/W3 +审查落盘：docs/harness/reviews/by-task/portfolio-rag-demo/task_portfolio_rag_demo_v1_audit_R1_20260601.md +``` diff --git a/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_30_portfolio-rag-demo.md b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_30_portfolio-rag-demo.md new file mode 100644 index 00000000..28a6873e --- /dev/null +++ b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_30_portfolio-rag-demo.md @@ -0,0 +1,25 @@ +# Invoke 快照 · 30 执行 · portfolio-rag-demo + +| 字段 | 值 | +|------|-----| +| hat_id | 30 | +| task_slug | portfolio-rag-demo | +| task_path | docs/tasks/active/task_portfolio_rag_demo_v1.md | +| git_branch | task/portfolio-rag-demo-v1 | +| freeze_id | PORTFOLIO-RAG-DEMO@2026-06-01 | +| audit_review | docs/harness/reviews/by-task/portfolio-rag-demo/task_portfolio_rag_demo_v1_audit_R1_20260601.md | +| date | 20260601 | + +--- + +## §3 调用体（快照） + +```text +30 执行 · W2 RUNBOOK + W3 PROJECT_CONFIG §C.1 · 禁止 api/tests/sync +交付： +- docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md +- docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md §C.1 +- docs/diary/samples/portfolio-rag-demo/README.md +验证：pytest 277 passed +下一棒：40 自检 +``` diff --git a/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_40_portfolio-rag-demo.md b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_40_portfolio-rag-demo.md new file mode 100644 index 00000000..297611a9 --- /dev/null +++ b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_40_portfolio-rag-demo.md @@ -0,0 +1,21 @@ +# Invoke 快照 · 40 自检 · portfolio-rag-demo + +| 字段 | 值 | +|------|-----| +| hat_id | 40 | +| task_slug | portfolio-rag-demo | +| task_path | docs/tasks/active/task_portfolio_rag_demo_v1.md | +| git_branch | task/portfolio-rag-demo-v1 | +| freeze_id | PORTFOLIO-RAG-DEMO@2026-06-01 | +| date | 20260601 | + +--- + +## §3 调用体（快照） + +```text +40 自检 · 文档 tranche · W5 defer（HG-W5-SYNC / HG-W5-FIVE-Q pending） +命令：pytest tests -m "not intent_eval and not intent_benchmark" → 277 passed +回填：task ### 自检结论（执行者） +下一棒：50 独立复检（Fresh Context 新会话） +``` diff --git a/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_50_portfolio-rag-demo.md b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_50_portfolio-rag-demo.md new file mode 100644 index 00000000..fb2adaa1 --- /dev/null +++ b/docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_50_portfolio-rag-demo.md @@ -0,0 +1,65 @@ +# Invoke 快照 · 50 独立复检 · portfolio-rag-demo + +| 字段 | 值 | +|------|-----| +| hat_id | 50 | +| task_slug | portfolio-rag-demo | +| task_path | docs/tasks/active/task_portfolio_rag_demo_v1.md | +| git_branch | task/portfolio-rag-demo-v1 | +| freeze_id | PORTFOLIO-RAG-DEMO@2026-06-01 | +| REINSPECT_MODE | 独立复检 | +| audit_R1 | docs/harness/reviews/by-task/portfolio-rag-demo/task_portfolio_rag_demo_v1_audit_R1_20260601.md | +| date | 20260601 | + +--- + +## §3 调用体（快照） + +```text +你正在扮演工作区 Harness「独立复检 + 全局验收帽」，严格遵循： +- docs/harness/prompts/50-independent-reinspect.md（§一 独立复检；§二 全局验收） +- docs/harness/HARNESS_V2_PLAN.md §5（test_strategy: required 时关注测试与实现关系） +- 根目录 AGENTS.md §8、docs/harness/HARNESS_V2_P0_ACCEPTANCE.md（若本次变更触及合并前必绿子仓） + +Open Folder = ai-ink-brain-api-python +git_branch = task/portfolio-rag-demo-v1 + +输入（已由人工替换占位符；若你仍看到 {{…}} 或 REINSPECT_MODE 非三选一字面，须先追问用户，不得开工）： +- 主 task 路径： +ai-ink-brain-api-python/docs/tasks/active/task_portfolio_rag_demo_v1.md +- 子仓根（相对 Projects/；用于理解 diff 与路径）： +ai-ink-brain-api-python +- 模式（必须恰好为以下之一：独立复检 / 全局验收 / 两者）： +独立复检 +- diff 或变更范围说明（全局验收单独模式可写「无」）： +git diff origin/main...HEAD -- docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md docs/tasks/active/task_portfolio_rag_demo_v1.md docs/harness/reviews/by-task/portfolio-rag-demo/ docs/harness/invokes/by-task/portfolio-rag-demo/ docs/diary/samples/portfolio-rag-demo/ +- 任务审核书面结论路径（无则「无」）： +ai-ink-brain-api-python/docs/harness/reviews/by-task/portfolio-rag-demo/task_portfolio_rag_demo_v1_audit_R1_20260601.md + +你必须完成： +0. **Invoke 快照（开帽起点）**：在输出下列分节实质性结果之前，先将 **本用户消息全文**（= 本模板 §3、占位符已全部替换）按 `docs/harness/invokes/README.md` 落盘到 `docs/harness/invokes/by-task/portfolio-rag-demo/`（含元数据表 + 快照 fenced code）。同一会话内追问 **不** 再新增快照文件。 + +【当模式为「独立复检」或「两者」时 — 对应 hat §一】 +1. 读取 task 内「### 自检结论（执行者）」；若缺失 → 阻塞首条：要求先跑 TEMPLATE-self-check-invoke + 40。 +2. 输入裁剪：以 diff、命令输出要点、自检验收表为主；避免执行过程长文。 +3. 对 task 每条验收项输出表格：验收项 | pass/fail | 证据（文件:行 / 测试名 / 日志片段）| 备注；fail 须写复现步骤或缺失证据。 +4. 汇总阻塞合并项；给出是否建议合并（供维护者决策）。 +5. 禁止：替执行者改代码（除非用户明确要求复检提交 patch）；缺口退回需求/审查帽。 +6. **W5 口径**：§6.2 / G-W5-* 若仍为「未测 / HG-W5 pending」，应标 **defer（非 30 阻塞）** 或 **fail（若声称 W5 已完成）**；勿与 W2/W3 文档 tranche 混判。 + +【当模式为「全局验收」或「两者」时 — 对应 hat §二】 +6. 若 task 声明 freeze_id：核对 PR 变更是否在冻结基准内；契约升级是否在 SPEC/task 显式记录。 +7. 输出 checklist 表（项 / 状态 / 签注栏「待人工」）；不伪造已签核；不跳过 CI 红灯叙事。 + +7. **落盘**：全文写入 `docs/tasks/reinspect_results/reinspect_portfolio_rag_demo_v1_20260601_v1.md`（结构见 ACCEPTANCE_LANDING / 50 帽）。 + +对话回复：若建议合并且无返工 → 输出「执行路线与 Commit 回溯」（docs/harness/prompts/handoff/HANDOFF_CLOSE_TRACE.md），勿编造下一棒 Prompt；若须打回 → 输出下一棒可复制 Prompt（含打回、二次审查、上一棒修复）。 +8. **自动 commit**：落盘后按 docs/harness/prompts/handoff/HANDOFF_AUTO_COMMIT.md 分仓 commit。用户写明「不要 commit」则跳过。 + +Judgment（本帽 · 对话末尾必填；任一项 warn/fail 须写 judgment_notes）： +- experience_capture: 维持 | 建议升级 required | 建议降 n/a | 维持 n/a（≤1 行理由） +- gate/risk: 无 | 须人审: | 证据不足 +- hat_self: pass | pass-with-notes | blocked + +Fresh Context（P1）：**禁止**阅读 30 invoke 全文；输入限于 task、reviews R1、diff 摘要、40 `### 自检结论`。 +``` diff --git a/docs/harness/prompts/PROMPT_install_harness_looptask_handoff_skill_v1_zh.md b/docs/harness/prompts/PROMPT_install_harness_looptask_handoff_skill_v1_zh.md new file mode 100644 index 00000000..b45500e2 --- /dev/null +++ b/docs/harness/prompts/PROMPT_install_harness_looptask_handoff_skill_v1_zh.md @@ -0,0 +1,103 @@ +# Prompt · 安装 Harness LoopTask 交接 SKILL（后端 Agent · 若缺失则创建） + +> **用途**：粘贴 **§3 全文** 到 **Open Folder = `ai-ink-brain-api-python`** 的对话；由 Agent **检测并补齐** `harness-looptask-handoff` 双轨 skill（与前端 Epic 对齐）。 +> **便携真值模板**：若本仓尚无正文，以 **`ai-ink-brain/docs/tasks/skills/` 不存在时** 复制前端 `.cursor/skills/harness-looptask-handoff/SKILL.md` 语义，并 **改路径** 为本仓 `docs/tasks/` · `docs/harness/` 约定（见 [`docs/harness/README.md`](../README.md) §2.1）。 +> **已存在时**：只做 diff 对齐 + 更新 README 索引，**禁止** 重复创建冲突目录。 + +--- + +## 1. 前置 + +| 项 | 说明 | +|----|------| +| Open Folder | **`ai-ink-brain-api-python`**（本子仓根） | +| 工作区只读 | 可 `@` `ai-ink-brain/.cursor/skills/harness-looptask-handoff/SKILL.md` 作前端对照 | +| 双轨约定 | [`.cursor/skills/README.md`](../../.cursor/skills/README.md) · [`docs/tasks/skills/README.md`](../../docs/tasks/skills/README.md) | + +--- + +## 2. 检测清单（Agent 先跑） + +```bash +# 在 ai-ink-brain-api-python 根执行 +test -f .cursor/skills/harness-looptask-handoff/SKILL.md && echo CURSOR=ok || echo CURSOR=missing +test -f docs/tasks/skills/SKILL-harness-looptask-handoff.md && echo PORTABLE=ok || echo PORTABLE=missing +``` + +| 结果 | 动作 | +|------|------| +| 两者 **ok** | 读 portable 真值 · 对照前端 skill · 仅补 README 索引行（若缺）· 输出「已安装 · 无需改动」或 patch 摘要 | +| 任一 **missing** | 按 §3 创建 **缺失文件** + 更新 **两个 README** + `docs/harness/README.md` §1 表一行 | +| 仅 Cursor 缺 | 写 `.cursor/skills/.../SKILL.md`（frontmatter + 链 portable） | +| 仅 portable 缺 | 写 `docs/tasks/skills/SKILL-harness-looptask-handoff.md`（完整条文） | + +--- + +## 3. 可复制 Prompt 正文（从下一行起） + +```text +## 角色 + +你是 **ai-ink-brain-api-python 仓 Harness 文档 Agent**，任务：**若缺失则安装** `harness-looptask-handoff` skill，并与前端 Portfolio LoopTask 交接规则对齐。 + +Open Folder = ai-ink-brain-api-python +禁止：改业务代码（api/ · tests/）；改 human_gate；提交 .env + +## 必读 + +- docs/harness/README.md §1 · §2.1（落盘 taxonomy） +- .cursor/skills/README.md（双轨说明） +- docs/tasks/skills/README.md（索引表） +- docs/tasks/skills/SKILL-harness-looptask-handoff.md（若已存在则 diff） +- 对照（只读）：ai-ink-brain/.cursor/skills/harness-looptask-handoff/SKILL.md + +## 你必须完成 + +1. **检测** §2 两条 `test -f`；在回复开头写 CURSOR / PORTABLE 状态。 +2. **若 missing**： + a. 创建 `docs/tasks/skills/SKILL-harness-looptask-handoff.md`（完整）：含 + - 何时选用 · Agent 必须交付三件事（50 Prompt / 签收清单 / 人改 gate 表） + - 本子仓路径：`docs/tasks/active/` · `docs/harness/reviews/by-task/` · `docs/harness/invokes/by-task/` · `docs/tasks/reinspect_results/` + - CLOSE 四步 · 人改 gate 模板表（文件+位置+改什么） + - **跨仓 Portfolio**：前端 W5 路径表 + 后端 `.env` 的 `CONTENT_ROOT` 可选行 + b. 创建 `.cursor/skills/harness-looptask-handoff/SKILL.md`：YAML frontmatter（name/description/disable-model-invocation）+ 摘要 + 链 portable 真值 + c. 更新 `.cursor/skills/README.md` 清单表增加一行 + d. 更新 `docs/tasks/skills/README.md` 六类一览表增加 `harness-looptask-handoff` 行 + 目录结构树 + e. 更新 `docs/harness/README.md` §1 日常读什么表增加一行：「LoopTask 止于 50 · 50 Prompt / 人改 gate」→ portable skill 路径 +3. **若已存在**：核对 portable 与 Cursor 摘要一致；缺 README 索引则只补索引。 +4. **输出给人**（无论新建或已存在）： + - skill 路径两行（Cursor + portable） + - **当前无 LoopTask 关账时**：给出「人改 HG-REINSPECT」**模板表**（相对 `docs/tasks/active/task_*.md`），不要写「需要人签」而不写文件 + - **Portfolio 跨仓**：列出前端 W5 签收文档路径（`ai-ink-brain/content/harness/reviews/...` 等） +5. **commit**（用户未说「不要 commit」时）：仅本轮 skill + README 路径；message 建议 `docs(harness): add harness-looptask-handoff skill (dual-track)` + +## 禁止 + +- 复制工作区 `Projects/docs/harness/prompts/` 整包到本仓 +- 用笼统语句代替「文件 | 位置 | 改什么」表 +- 代填任何 task 的 human_gate + +Judgment： +- hat_self: pass | pass-with-notes | blocked +- 若 blocked：列出缺哪条路径、需人提供什么 +``` + +--- + +## 4. 安装后期望落盘 + +| 文件 | 作用 | +|------|------| +| `docs/tasks/skills/SKILL-harness-looptask-handoff.md` | Git 便携真值 | +| `.cursor/skills/harness-looptask-handoff/SKILL.md` | Cursor `@` 入口 | +| `.cursor/skills/README.md` | 清单 +1 行 | +| `docs/tasks/skills/README.md` | 一览 +1 行 | +| `docs/harness/README.md` | §1 +1 行 | + +--- + +## 5. 修订记录 + +| 日期 | 摘要 | +|------|------| +| 2026-06-01 | v1：后端安装 Prompt · 对齐前端 Portfolio W5 LoopTask handoff | diff --git a/docs/harness/reviews/by-task/portfolio-rag-demo/task_portfolio_rag_demo_v1_audit_R1_20260601.md b/docs/harness/reviews/by-task/portfolio-rag-demo/task_portfolio_rag_demo_v1_audit_R1_20260601.md new file mode 100644 index 00000000..56aaed60 --- /dev/null +++ b/docs/harness/reviews/by-task/portfolio-rag-demo/task_portfolio_rag_demo_v1_audit_R1_20260601.md @@ -0,0 +1,84 @@ +# 任务审核报告：portfolio-rag-demo · R1 + +| 字段 | 值 | +|------|-----| +| task | `docs/tasks/active/task_portfolio_rag_demo_v1.md` | +| audit_round | R1 | +| freeze_id | `PORTFOLIO-RAG-DEMO@2026-06-01` | +| audit_profile | `post_close` | +| test_strategy | `recommended` | +| invoke_snapshot | `docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_22_portfolio-rag-demo.md` | +| reviewer | Agent（22 帽 · semi_auto） | +| date | 2026-06-01 | + +--- + +## 审查结论摘要 + +**零阻塞 · 可进入执行帽（W2/W3 文档 tranche）** + +task 自 SPEC §7 映射 W2/W3/W5 清晰；`failure_paths` FP-1～8 可操作；Q3 strict evidence 与 freeze_id 一致。W5 人驱动 sync/五问已通过 `HG-W5-*` 闸与 RUNBOOK 留证路径约束，**不阻塞** 30 文档落盘。 + +--- + +## 理论对齐检查表（P0） + +### §3.1 / §3.2 / §3.3 + +| # | 检查项 | 通过 | +|---|--------|------| +| 1 | `test_strategy: recommended` + 纯 docs | ☑ | +| 2 | `failure_paths` ≥1 行 | ☑（8 条 · 缺 Scenario ID 列 · **非阻塞** · 30 后可选补） | +| 3 | 非范围 + 验收含 pytest | ☑ | +| 4 | `semi_auto` + `post_close` | ☑ | +| 5 | 50 触发 | `recommended` + 无 `api/` → **50 可选 · 本链仍跑** | + +`harness_human_gate_check.py`：22 落盘前已 `HG-TASK-DRAFT` approved（semi_auto 人授权）。 + +--- + +## 非阻塞 + +| 项 | 说明 | +| --- | --- | +| OpenSpec Scenario ID | failure_paths 无 ID 列；docs task · 不阻塞 30 | +| W4 前端 content | `blocked_by` 已声明；sync/五问前须人确认就绪 | +| HG-W5-SYNC | 仍 `pending`；**不阻塞** 30/40 文档 tranche；阻塞 W5 关账 | + +--- + +## human_gate + +| gate_id | status | blocks_hats | 结论 | +|---------|--------|-------------|------| +| HG-TASK-DRAFT | approved | 22-R1,30 | semi_auto 授权 | +| HG-AUDIT-R1 | approved | 30 | R1 零阻塞 | +| HG-W5-SYNC | pending | — | 人执行 sync 后签 | +| HG-W5-FIVE-Q | pending | done | 五问留证后人签 | +| HG-REINSPECT | pending | done | 50 后人签 | + +--- + +## 阻塞项 + +**无阻塞。** + +--- + +## 是否建议执行帽开工 + +**是** — 范围 W2 RUNBOOK + W3 PROJECT_CONFIG §C.1；**禁止**改 `api/`/`tests/`；**禁止** Agent 执行生产 sync。 + +--- + +## 签收 / 关闭 + +- **R1**：30 可开工文档 tranche +- **W5**：待人 + RUNBOOK；40 可自检 §6.1/§6.3；§6.2 待 W5 +- **50**：Fresh Context 新会话；`test_strategy: recommended` · docs 变更 + +--- + +## 下一棒可复制 Prompt + +见 `docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_30_portfolio-rag-demo.md` §3。 diff --git a/docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md b/docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md index 7ad73c78..1e06da0c 100644 --- a/docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md +++ b/docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md @@ -115,6 +115,27 @@ 补充：`.cursorrules` 文本里提到 `SUPABASE_URL` / `SUPABASE_SERVICE_ROLE_KEY`，但代码实际优先读取 `NEXT_PUBLIC_SUPABASE_URL` 与 `SUPABASE_SERVICE_ROLE_KEY`（并支持别名）。**以代码为准**。 +### C.1 Portfolio 演示站（ingest / sync · `PORTFOLIO-RAG-DEMO@2026-06-01`） + +> **用途**：投递前 portfolio 演示站 RAG 语料与前端 `ai-ink-brain/content/` **同源**入库。 +> **操作 RUNBOOK**：[`docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md`](../harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md) +> **治理 SPEC**：[`docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md`](../spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md) + +| 项 | 真值 / 说明 | +| --- | --- | +| **CONTENT_ROOT** | **生产 / 预发必须显式设置**，指向前端仓 `content/` 根目录（含 `methodology/`、`resume/`、`evidence/`）。留空时代码回退 `REPO_ROOT/content`（后端仓内）——**禁止**作为 portfolio 生产真值。 | +| **本地示例** | `CONTENT_ROOT=/path/to/ai-ink-brain/content`（与 `.env.example` 注释一致；路径随本机 checkout 而变） | +| **category 规则** | ingest 取相对路径 **第一段** 为 `metadata.category`（`methodology` / `resume` / `evidence`）；见 `api/ingest_pipeline.py::get_all_markdown_chunks()` | +| **入库接口** | **仅** `POST /api/py/admin/sync`（异步 job）；portfolio RUNBOOK **不含** `admin/ingest` | +| **admin 鉴权** | `NEXT_PUBLIC_ADMIN_SECRET` 或 `CHAT_API_SECRET` → Bearer / `x-admin-token` | +| **Embedding** | `SILICONFLOW_API_KEY` + `EMBEDDING_DIM`（默认 1024）须与 Supabase `documents.embedding vector(N)` 一致 | +| **Supabase 写库** | `NEXT_PUBLIC_SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY` | +| **部署边界** | 演示 URL 沿用现有前端 Vercel 项目（`NEXT_PUBLIC_SITE_MODE=portfolio`）；**不**变更后端 API 域名或 Supabase 项目名（SPEC Q-3） | +| **DEBUG_INGEST** | 本地排障可 `1`；**生产关闭** | +| **Secrets** | **禁止**将 admin / Supabase / SiliconFlow 密钥提交 Git；平台 Secrets 或本地 `.env` | + +**生产 mount 语义（概念）**：Python 服务进程须能 `read` 挂载后的 `CONTENT_ROOT` 目录树；Vercel/serverless redeploy 期间 job 可能丢失（404 → 重新 POST sync）。 + --- ## D. 运行与脚本 diff --git a/docs/spec/README.md b/docs/spec/README.md index e9cadeac..ec97a732 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -14,6 +14,7 @@ | [`governance/`](./governance/README.md) | 治理 / Harness / Wiki | **2026-05 起** 非功能需求与推广顺序 | | [`SPEC-ChatBI-Enterprise-Gap.md`](./SPEC-ChatBI-Enterprise-Gap.md) | 企业差距 | 跨版本差距表 | | [`SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md`](./SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md) | **SDD 过程** | 起草 SPEC 的三轮意图对齐 + 10/20/22 映射 | +| [`governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md`](./governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md) | **治理 / Portfolio** | `active` · `PORTFOLIO-RAG-DEMO@2026-06-01` · RAG 语料与前端 `content/` 同源 ingest + 五问 RUNBOOK | --- diff --git a/docs/spec/governance/PROMPT_00_SPEC-refine_Portfolio-RAG-Demo-v1_zh.md b/docs/spec/governance/PROMPT_00_SPEC-refine_Portfolio-RAG-Demo-v1_zh.md new file mode 100644 index 00000000..7e41f408 --- /dev/null +++ b/docs/spec/governance/PROMPT_00_SPEC-refine_Portfolio-RAG-Demo-v1_zh.md @@ -0,0 +1,230 @@ +# Prompt 00 · SPEC 细化（阅读 → 提问 → 解决 · ≤5 轮） + +> **用途**：在 **冻结 `freeze_id` / 创建 task 之前**，对 [`SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md`](./SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md) 做多轮 **人-Agent 对齐**；每轮固定三步：**读 → 问 → 改 SPEC**。 +> **不是** Harness 链内 **00 总调度帽**（见 [`docs/harness/prompts/hats/00-orchestrator.md`](../../harness/prompts/hats/00-orchestrator.md)）；**不**替代 **10 需求帽** 或 **20 规格短评**。 +> **SDD 映射**：本 Prompt 覆盖 [`SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md`](../SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md) **轮 1→轮 2** 之间的 **待确认清单消化**；轮次上限 **5**（含首轮阅读）。 + +--- + +## 1. 占位符 + +| 占位符 | 含义 | 本 Epic 默认值 | +| --- | --- | --- | +| `{{SPEC_PATH}}` | 目标 SPEC | `docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md` | +| `{{FRONTEND_SPEC}}` | 配对前端 SPEC | `ai-ink-brain/content/tasks/specs/SPEC-portfolio_demo_site_v1_zh.md` | +| `{{PLANNING_DOC}}` | 五问真值（若可读） | `Projects/docs/planning/投递冲刺_20260609_v1_zh.md` §2 | +| `{{GIT_BRANCH}}` | 工作分支 | `task/portfolio-rag-demo-spec-v1` | +| `{{ROUND_N}}` | 当前轮次 | `1`～`5` | + +--- + +## 2. 角色与边界 + +### 2.1 你是谁 + +你是 **SPEC 细化 Agent（Prompt 00）**：把 `draft` SPEC 中的 **「待确认」**、**歧义**、**不可测验收** 收敛为 **可冻结** 条文；**只改 SPEC 与 RUNBOOK 大纲**（若 SPEC §5 已指向路径），**不写** `api/` / `tests/`。 + +### 2.2 允许 + +| 动作 | 说明 | +| --- | --- | +| 只读 | `{{SPEC_PATH}}`、配对 SPEC、`PROJECT_CONFIG` §C/F、`api/ingest_pipeline.py`（核对 §2）、`.env.example` | +| 只读 | `{{PLANNING_DOC}}`（存在则对齐 Q1～Q5 问句） | +| 修改 | `{{SPEC_PATH}}` 正文、**「SPEC 待确认清单」**、**修订记录** | +| 修改 | `docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md` **仅当** 某轮已冻结对应小节且 SPEC 引用需同步（**可选**；默认仍只改 SPEC） | + +### 2.3 禁止 + +- 创建 / 修改 `docs/tasks/active/task_*.md` +- 修改 `api/`、`tests/`、CI workflow +- 执行生产 `POST /api/py/admin/sync` 或写入真实密钥 +- 启动 Harness 22/30/40/50 链（冻结后可由人另开 10/22） +- **自问自答** 拍板：凡需业务裁决的项 **必须** 等人回复后再写入 SPEC「已拍板」表述 +- 超过 **5 轮** 仍有大块 pending → **停工**，输出 **阻塞清单** + 建议人会议 + +--- + +## 3. 五轮协议（阅读 → 提问 → 解决） + +```text +轮 1：通读 SPEC + 必读依赖 → 输出「缺口表」+ 提问（≤5 条，含 SPEC 文末待确认清单） +轮 2～5：人逐条答复 → Agent 改 SPEC → 若仍有 pending，再提问（每轮 ≤5 条） +终轮：待确认清单为空或全部标「延期至 task」→ 提议 freeze_id + 状态 draft→active +``` + +### 3.1 每轮 Agent 输出形状（硬） + +```text +## Prompt 00 · 第 {N}/5 轮 + +### 本轮阅读范围 +- （列出已打开路径） + +### 本轮提问（≤5 · 须人答复后再改 SPEC） +| # | 问题 | 关联 SPEC 节 | 建议选项 A / B | +| … | + +### 本轮 SPEC 变更（仅当 N≥2 且人已答复上一轮） +- （按节列出改动摘要；无则写「本轮仅提问，未改 SPEC」） + +### 待确认清单快照 +| # | 状态 pending / resolved / deferred | +| … | + +### 下一轮 +- 继续第 {N+1} 轮 | 建议冻结 | 停工（原因） +``` + +### 3.2 首轮（轮 1）必读顺序 + +| 序 | 路径 | 目的 | +| --- | --- | --- | +| 1 | `{{SPEC_PATH}}` 全文 | 主真值 | +| 2 | [`SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md`](../SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md) §4 | 待确认清单格式 | +| 3 | [`docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md`](../../meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md) §C `CONTENT_ROOT`、§F admin/sync | 核对 §2 现状 | +| 4 | `api/ingest_pipeline.py`（`get_all_markdown_chunks`、`sync_content_to_vector`） | 核对 category / job 语义 | +| 5 | `{{FRONTEND_SPEC}}`（**若存在**） | category 目录、演示 URL | +| 6 | `{{PLANNING_DOC}}` §2（**若可读**） | Q1～Q5 标准问句 | + +### 3.3 首轮种子提问（须与 SPEC 文末清单合并去重） + +| # | 种子问题 | 建议选项 | +| --- | --- | --- | +| S1 | **`freeze_id` 日期** | `PORTFOLIO-RAG-DEMO@2026-06-09` / 冻结当日 | +| S2 | **Q3 sources** | 严格 `evidence` / 允许 `methodology` 下 vol3 | +| S3 | **五问标准问句** | 粘贴计划 §2 全文 / 由 RUNBOOK 附录锁定 | +| S4 | **五问执行环境** | 必须生产 URL / 预发等价即可 | +| S5 | **sync 空库** | `filesScanned=0` 硬 FAIL / 允许首次占位 sync | +| S6 | **最小 content 文件集** | 三类各 ≥1 md / 前端 SPEC 锁定清单 | +| S7 | **job 404 / 多实例** | 接受单实例运维 / 必须文档化重试 SOP | +| S8 | **ingest vs sync 默认** | 仅 sync / sync 失败时允许 ingest 备用 | + +> 首轮提问 **总数仍 ≤5**：从 S1～S8 **按阻塞优先级** 选取；其余记入「次轮候选」。 + +### 3.4 「解决」写入 SPEC 的规则 + +| 人答复类型 | Agent 动作 | +| --- | --- | +| 明确二选一 | 改对应 § 表格为 **已拍板**；从待确认清单 **删除** 或标 `resolved` | +| 「待确认 / 稍后」 | 保留 pending；**不得** 伪造已拍板 | +| 「延期到 task」 | SPEC 标 `deferred` + 在 §7 Wn 或 task 草案字段注明 | +| 与已拍板决策冲突 | **停工** 列出矛盾，等人裁决 | + +### 3.5 冻结条件（建议终轮输出） + +- [ ] 「SPEC 待确认清单」**无** `pending`（允许 `deferred` 且 §7 已指向） +- [ ] §6 五问表含 **可粘贴问句**（非仅主题摘要） +- [ ] §4.4 / §5 RUNBOOK 大纲无「待确认」占位（或已 deferred） +- [ ] `freeze_id` 已定（建议 `PORTFOLIO-RAG-DEMO@YYYY-MM-DD`） +- [ ] SPEC 元信息 **状态** → `active`（人明示「仍 draft」则保持） + +**冻结后下一棒（不在本 Prompt 内）**：人确认 → 10 帽出 task 草案 → 22 或 30。 + +### 4.1 冻结后 · 10 帽起手 Prompt（SPEC 已 `active` 时粘贴） + +> Prompt 00 **已关账** 后使用；invoke 落盘示例：[`docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_10_portfolio-rag-demo-requirements.md`](../../harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_10_portfolio-rag-demo-requirements.md) + +```text +你正在扮演工作区 Harness「需求与任务分析帽」，严格遵循： +- docs/harness/prompts/hats/10-requirements.md +- docs/harness/prompts/templates/TEMPLATE-requirements-invoke.md §3 +- docs/harness/HARNESS_V2_PLAN.md §5 + +Open Folder = ai-ink-brain-api-python +git_branch = task/portfolio-rag-demo-v1 + +【目标与上下文】 +冻结 SPEC `PORTFOLIO-RAG-DEMO@2026-06-01` 已 active。从 SPEC §7（W2 RUNBOOK · W3 env · W5 预跑）拆出 `docs/tasks/active/task_portfolio_rag_demo_v1.md`。6/9 前交付 RUNBOOK + CONTENT_ROOT 文档 + 五问预跑留证；禁止本帽改 api/tests 或执行生产 sync。 + +【已有材料】 +docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md +docs/spec/governance/投递冲刺_20260609_v1_zh.md +ai-ink-brain/content/tasks/specs/SPEC-portfolio_demo_site_v1_zh.md（只读） +docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md + +【审查回填】无 +【SDD 状态】轮0+1+2 已完成，清单已人确认 +【新建 SPEC】否 + +须：写 task 草案落盘 · test_strategy recommended · failure_paths · freeze_id · 输出下一棒 A（22 推荐）/ B（30）全文 · Harness 状态栏 B。 +invoke 落盘：docs/harness/invokes/by-task/portfolio-rag-demo/ +``` + +--- + +## 4. 可复制 Prompt 正文（§3 · 新开对话粘贴） + +```text +## 角色 + +你是 **SPEC 细化 Agent（Prompt 00）**，严格遵循： +- docs/spec/governance/PROMPT_00_SPEC-refine_Portfolio-RAG-Demo-v1_zh.md +- docs/spec/SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md §4（待确认清单） + +Open Folder = ai-ink-brain-api-python +git_branch = task/portfolio-rag-demo-spec-v1 + +## 目标 SPEC + +docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md + +## 当前轮次 + +第 {{ROUND_N}} / 5 轮 + +## 上轮人答复（轮 1 留空） + +（粘贴人对上一轮「本轮提问」的逐条答复；无则写「首轮启动」） + +## 你必须完成 + +1. 按 PROMPT §3.2 顺序 **阅读**（轮 1 全读；轮 2+ 仅读变更相关节 + 人答复涉及路径）。 +2. 输出 **§3.1 固定形状**（提问 ≤5 条；若人已答复上一轮，**先改 SPEC** 再提新问）。 +3. 禁止：改 api/、tests/、创建 task、执行 admin/sync、代人人拍板。 +4. 若待确认清单已全部 resolved/deferred 且 §6 问句齐全 → 提议 **freeze_id** 与状态 **active**。 +5. 若已达第 5 轮仍有 pending → **停工** + 阻塞清单。 + +## 配对只读（若存在） + +- ai-ink-brain/content/tasks/specs/SPEC-portfolio_demo_site_v1_zh.md +- Projects/docs/planning/投递冲刺_20260609_v1_zh.md §2 + +## 本回合交付 + +- 更新后的 SPEC 路径 + diff 摘要 +- §3.1 形状全文 +- 若冻结：建议 freeze_id 一行 + 「建议下一棒：10 帽创建 task_portfolio_rag_demo_v1」 +``` + +--- + +## 5. 会话留盘（可选） + +多轮跨会话时，可在本目录追加 **`NOTES_00_SPEC-refine_Portfolio-RAG-Demo_round{N}.md`**（**非 Git 必交**；也可只用对话历史）。 +**禁止**把长对话全文写入 SPEC 正文。 + +--- + +## 6. 关联引用 + +| 用途 | 路径 | +| --- | --- | +| 目标 SPEC | [`SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md`](./SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md) | +| SDD 三轮 | [`SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md`](../SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md) | +| 10 需求帽 | [`docs/harness/prompts/hats/10-requirements.md`](../../harness/prompts/hats/10-requirements.md) | +| RUNBOOK 目标路径 | [`docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md`](../../harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md)（30 帽正文） | + +--- + +## 修订记录 + +| 日期 | 摘要 | +| --- | --- | +| 2026-06-01 | v1：Portfolio RAG Demo SPEC · ≤5 轮读问解协议 + §4 可复制 Prompt | +| 2026-06-01 | v1.1：§4.1 冻结后 10 帽起手 Prompt + invoke 指针 | + +--- + +## 给 Cursor + +`Prompt 00`、`SPEC 细化`、`阅读提问解决`、`PORTFOLIO-RAG-DEMO`、`待确认清单`、`freeze_id` diff --git a/docs/spec/governance/README.md b/docs/spec/governance/README.md index d6a47c40..a3fd14c9 100644 --- a/docs/spec/governance/README.md +++ b/docs/spec/governance/README.md @@ -16,6 +16,8 @@ | [`SPEC-Governance-Wiki-Agent-Readorder-v1.md`](./SPEC-Governance-Wiki-Agent-Readorder-v1.md) | `active` | 后端 Agent Coding Wiki 读序 | | [`SPEC-Governance-Wiki-Ingest-Batch-v1.md`](./SPEC-Governance-Wiki-Ingest-Batch-v1.md) | `active` | Batch-1 ingest（10 slug） | | [`SPEC-Governance-Wiki-CTX-AB-Representative-v1.md`](./SPEC-Governance-Wiki-CTX-AB-Representative-v1.md) | `active` | AB 代表性扩面 | +| [`SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md`](./SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md) | `active` | Portfolio 演示站 RAG 同源 ingest + 五问验收 RUNBOOK · `PORTFOLIO-RAG-DEMO@2026-06-01` | +| [`PROMPT_00_SPEC-refine_Portfolio-RAG-Demo-v1_zh.md`](./PROMPT_00_SPEC-refine_Portfolio-RAG-Demo-v1_zh.md) | `active` | 上述 SPEC · ≤5 轮读问解 · §4 可复制 Prompt | **SDD 起草**（全仓 SPEC 通用）：[`../SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md`](../SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md) diff --git a/docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md b/docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md new file mode 100644 index 00000000..be3c3c97 --- /dev/null +++ b/docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md @@ -0,0 +1,344 @@ +# SPEC — 治理：Portfolio 演示站 RAG 语料同源 ingest 与五问验收（v1） + +| 项 | 内容 | +| --- | --- | +| **状态** | `active` | +| **freeze_id** | `PORTFOLIO-RAG-DEMO@2026-06-01`（Prompt 00 轮 3 · 待确认清单清零 · 人可另议改日） | +| **Roadmap** | [`投递冲刺_20260609_v1_zh.md`](./投递冲刺_20260609_v1_zh.md) §2（五问真值 · **已对齐**） | +| **配对前端 SPEC** | `ai-ink-brain/content/tasks/specs/SPEC-portfolio_demo_site_v1_zh.md`（并行起草 · **draft**） | +| **Harness 映射** | **10** 需求（本稿）→ 人审冻结 → **22** task 审核 → **30** RUNBOOK / env 文档 → 生产五问预跑 | +| **SDD 过程** | 轮 0 意图卡并入 §1；轮 1 覆盖 §0～§4；[`SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md`](../SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md) | +| **细化 Prompt 00** | [`PROMPT_00_SPEC-refine_Portfolio-RAG-Demo-v1_zh.md`](./PROMPT_00_SPEC-refine_Portfolio-RAG-Demo-v1_zh.md)（≤5 轮 · 阅读→提问→改 SPEC） | + +--- + +## 0. 完成态（一句话） + +在 **2026-06-09 投递前**，portfolio 演示站生产环境的 RAG 向量库与前端仓 **`ai-ink-brain/content/`** 保持 **同源 ingest**（`CONTENT_ROOT` → `POST /api/py/admin/sync`），并有一份 **人可执行、可复现** 的五问验收 RUNBOOK，使 Q1～Q5 **5/5 可答**、**sources ≥4/5**、单问重试 **≤3 次** 时仍可通过预检。 + +--- + +## 1. 背景与立项条件 + +### 1.1 轮 0 · 意图卡（并入） + +| 项 | 结论 | +| --- | --- | +| **业务目标** | portfolio **演示站**（非完全公开博客）需在投递前展示 **RAG 问答能力**，语料与站点展示内容 **同源**，避免「页面有、向量库无」或 category 错位。 | +| **时间门槛** | **2026-06-09** 投递冲刺；本 Epic **6/9 前** 交付 ingest 对齐 + RUNBOOK + 生产五问预跑留证；**不** 将 ChatBI v3 preview 全链或双能力 handoff 纳入 6/9 硬门槛。 | +| **入库方式（已拍板）** | 现有 **`POST /api/py/admin/sync`** 异步 job 机制；**人**在生产/预发触发，本 SPEC 回合 **不执行** sync。 | +| **CONTENT_ROOT（已拍板）** | 指向前端仓 **`ai-ink-brain/content/`**（本地与 deploy 文档化；见 §4.4）。 | +| **visitor 策略（已拍板 · T-05）** | 演示站 visitor **不禁 text2sql**；库内为 **可公开** 样例数据。 | +| **release 节奏（已拍板）** | 卷四 / 卷五每次公众 release 后 **24h 内** → **再 sync 一轮**（运维 SOP，见 §4.3 · Q-8:A） | +| **sync 运维（已拍板 · Q-6:A · Q-7:A · Q-10:B）** | **单实例**接受：sync 时避免并发 redeploy；`404 Job not found` → 重新 `POST` 创建 job。**仅** `admin/sync` 入库路径；**不**在 RUNBOOK 中使用 `admin/ingest` 备用。轮询总超时 **≤60 min**。 | +| **依赖** | 前端 `content/methodology`、`content/resume`、`content/evidence` 目录与 metadata 约定（目标态；见 §4.1）；配对前端 SPEC；Supabase `documents` + SiliconFlow Embedding（维度与 `EMBEDDING_DIM` 一致）。 | +| **非范围（摘要）** | 改 Next 页面、新建向量 schema 大改、GraphRAG 试点、Wiki batch 重复 ingest、本 SPEC 内承诺 ChatBI v3 preview 全链。 | +| **部署边界（已拍板 · Prompt 00 轮 2 · Q-3）** | 演示 URL 沿用现有前端 Vercel 项目（当前 [`https://ai-ink-brain.vercel.app/`](https://ai-ink-brain.vercel.app/)）；`NEXT_PUBLIC_SITE_MODE=portfolio` **隐藏** Blog/Learning 等模块入口，**不删**路由代码。**不**变更后端 API 域名、Supabase 项目名或 Python 服务部署仓；本 Epic 允许 **新增** `documents` 入库相关 SQL/迁移（若尚未执行）。 | +| **五问执行环境（已拍板 · Q-3）** | **预发 / Preview 与生产等价**即可通过五问预检（同 `CONTENT_ROOT` 挂载语义、同 Supabase 项目、同 Embedding 维）；最终投递演示以 portfolio 模式下的 **同一 Vercel 项目 URL** 为准，**不**要求另起后端或 DB 域名。 | + +### 1.2 立项条件 + +- [ ] 人审本 SPEC 并冻结 `freeze_id` +- [ ] 前端 portfolio content 三类目录（或等价路径）与 category 映射 **书面确认** +- [ ] 生产/预发 `CONTENT_ROOT` 与 `NEXT_PUBLIC_ADMIN_SECRET`（或 `CHAT_API_SECRET`）**部署文档**就绪（不含真实密钥） + +--- + +## 2. 现状快照（基于代码扫描 · 2026-06-01） + +> 扫描范围：`api/ingest_pipeline.py`、`api/index.py`（admin/sync）、`docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md`、`.env.example`。 + +### 2.1 内容根与 category 规则 + +| 项 | 现状 | +| --- | --- | +| **CONTENT_ROOT** | `api/ingest_pipeline.py::get_all_markdown_chunks()` 读取 env `CONTENT_ROOT`；**留空**时回退 `REPO_ROOT/content`（后端仓内，会自动 `mkdir`）；**设置**则 `expanduser().resolve()` 后扫描；路径非目录时返回 **空 chunk 列表**（不抛错，`DEBUG_INGEST=1` 时打印跳过日志）。 | +| **扫描范围** | 递归遍历 `.md` / `.mdx`；跳过 `.` 前缀目录及 `node_modules`、`.next`。 | +| **metadata.category** | **相对路径第一段**：`parts = rel.split("/")` → `category = parts[0]`；缺省为 `uncategorized`。 | +| **其他 metadata** | `slug`（文件名去扩展名）、`relativePath`、`chunk_index`、`lastModified` / `mtime`；可选 `date_norm`（从 slug/filename 抽日期）。 | +| **增强文本** | `build_enhanced_chunk_text` 注入 `[Document Context]` + Title / Date / **Category** + Content，供 embedding 与检索展示。 | + +### 2.2 入库路径对比 + +| 接口 | 行为 | 同步/异步 | +| --- | --- | --- | +| **`POST /api/py/admin/ingest?type=markdown`** | `process_markdown_files()`：按 **relativePath** 删旧行再批量 insert；返回 JSON 统计 | **同步**（请求内完成） | +| **`POST /api/py/admin/sync`** | 创建内存 job → 后台线程执行 `sync_content_to_vector()`：按 **slug** 删旧行再逐 chunk embed + insert | **异步**（`202` + job 轮询） | + +`sync_content_to_vector()` 与 `process_markdown_files()` 均会调用 RPC `refresh_documents_fts_tokens_for_paths`（失败时 ingest 侧可跳过并仅在 `DEBUG_INGEST` 打印）。 + +### 2.3 admin/sync job 机制 + +| 字段 | 说明 | +| --- | --- | +| **创建** | `POST /api/py/admin/sync` → `create_sync_job()` → `BackgroundTasks` 调用 `run_sync_job_sync(job_id)` | +| **HTTP 202 体** | `{ ok, job, statusUrl: "/api/py/admin/sync?jobId=" }` | +| **轮询** | `GET /api/py/admin/sync?jobId=` → `{ ok, job }` | +| **job.status** | `queued` → `running` → `succeeded` \| `failed` | +| **job.result**（成功） | `filesScanned`, `chunksTotal`, `chunksUpserted`, `rowsDeleted` | +| **job.error**（失败） | 异常 `str(e)` 字符串（如 Embedding **维度不匹配**：`RuntimeError` 含「维度」文案） | +| **持久性** | **内存** `JOBS` 字典；**单实例**（**已拍板 · Q-6:A**）；serverless redeploy 后 job 丢失 → **重新 POST**；**不**做持久化 job 方案 | +| **鉴权** | `_require_auth`：`Authorization: Bearer ` 或 `x-admin-token` / `x-blog-admin-token`；secret 来自 `NEXT_PUBLIC_ADMIN_SECRET` / `CHAT_API_SECRET`（`api/rag_env.py::admin_secret()`）。**前端 BFF** 维护者侧已迁移 **`SYNC_ADMIN_SECRET`**（与 Python **同值** · 见前端 [`SPEC-portfolio_admin_sync_auth_v1_zh.md`](../../../../ai-ink-brain/content/tasks/specs/SPEC-portfolio_admin_sync_auth_v1_zh.md)） | + +### 2.4 前端 content 目录（目标态 · 扫描 2026-06-01） + +本机 `ai-ink-brain/content/` **尚未** 存在 `methodology/`、`resume/`、`evidence/` 顶层目录（仅有 `tasks/`、`harness/`、`diary/` 等）。portfolio 演示语料按 **目标态** 与前端 SPEC 对齐创建；ingest 侧 **无需改代码** 即可在目录就绪后通过 category 第一段映射入库。 + +### 2.5 Unified Chat 入口（只读 · 与验收相关） + +- 演示站 RAG 问答预期走 **`POST /api/py/unified/chat`** 或 **`/stream`**（Bearer ChatBI token；visitor 不禁 text2sql）。 +- Legacy `POST /api/py/chat` 仍存在；五问 RUNBOOK **默认**以 Unified 路径为准（具体 BFF 转发以前端 SPEC 为准）。 + +--- + +## 3. 范围 / 非范围 + +| 在范围（6/9 前） | 说明 | +| --- | --- | +| **CONTENT_ROOT 部署文档** | 本地 / 生产 / CI 如何指向前端 `content/` | +| **category 对齐** | `methodology` / `resume` / `evidence` 与 ingest `metadata.category` 一致 | +| **sync RUNBOOK** | 人触发 `POST /api/py/admin/sync`、轮询、失败语义、卷四/五 release 后再 sync | +| **五问验收 RUNBOOK** | Q1～Q5 提问句、期望 category、sources 检查、重试规则 | +| **生产预跑留证** | 录屏 / 日志 / diary 样本（路径由 RUNBOOK 指定，非本回合落盘） | +| **本 SPEC + 索引** | 治理级 SDD；冻结后驱动 task | + +| 非范围 | 说明 | +| --- | --- | +| **前端 Next 页面 / UX** | 属 `ai-ink-brain` + 前端 SPEC | +| **新建或大幅变更 `documents` schema** | 沿用现有 `vector(N)` + metadata JSON | +| **GraphRAG 试点** | 不在本 Epic | +| **Wiki batch 重复 ingest** | 见 [`SPEC-Governance-Wiki-Ingest-Batch-v1.md`](./SPEC-Governance-Wiki-Ingest-Batch-v1.md)；portfolio 语料 **独立** content 树 | +| **ChatBI v3 preview 全链** | 低置信 RAG preview 等属其他 Epic；本 SPEC **不承诺** | +| **本回合执行生产 sync** | 仅规格与 RUNBOOK | +| **6/9 后 P1-B 双能力 handoff 实现** | 仅 §8 占位 | + +--- + +## 4. 行为与操作需求 + +### 4.1 content 目录与 metadata.category 映射 + +| 前端目录（`content/` 下） | ingest `metadata.category` | 五问关联 | 内容类型（目标态） | +| --- | --- | --- | --- | +| **`methodology/`** | `methodology` | **Q1**（卷三 / Harness / 签收） | 方法论、Harness 工程、卷三相关文稿 | +| **`resume/`** | `resume` | **Q2**（RAG 混合检索）、**Q4**（11 年 AI Coding 成果） | 履历、项目段、个人成果叙事 | +| **`evidence/`** | `evidence` | **Q3**（冷温热 vs 架构三层 · sources **仅** `evidence`）、**Q5**（token/效果 + 边界） | 证据、实验、效果与边界说明 | + +**规则（与现码一致）**： + +1. 文件须为 `.md` 或 `.mdx`，且位于上述目录 **子树** 内；`relativePath` 形如 `methodology/xxx.md`。 +2. **禁止**依赖后端仓内默认 `REPO_ROOT/content` 作为 portfolio 真值（生产必须显式 `CONTENT_ROOT`）。 +3. 若文稿需跨 category 引用，仍以 **物理路径第一段** 为准；交叉引用通过文内链接，**不**伪造 category。 +4. 前端若在 frontmatter 声明 category，须与目录第一段 **一致**（以前端 SPEC 为准；ingest **当前不读** frontmatter）。 + +### 4.2 sync 触发、job 轮询、失败语义 + +#### 4.2.1 触发（人执行） + +```http +POST /api/py/admin/sync +Authorization: Bearer +``` + +期望：**HTTP 202**，记录 `job.id` 与 `statusUrl`。 + +#### 4.2.2 轮询 + +```http +GET /api/py/admin/sync?jobId= +Authorization: Bearer +``` + +| job.status | 操作 | +| --- | --- | +| `queued` / `running` | 继续轮询（间隔 2～5s；总超时 **≤60 min** · **已拍板 · Q-10:B**） | +| `succeeded` | **硬检查**（**已拍板 · Q-4**）：`result.filesScanned > 0` **且** `chunksUpserted > 0`；`filesScanned=0` **视为 sync FAIL**，不得进入五问 | +| `failed` | 读 `error`；按下列语义处置 **不得** 标记五问通过 | + +#### 4.2.3 失败语义（SPEC 级） + +| 错误特征 | 含义 | 建议处置 | +| --- | --- | --- | +| `Embedding 维度为 … 与期望 … 不一致` | `EMBEDDING_DIM` / 模型与 Supabase `vector(N)` 不一致 | 修正 env 与 `init.sql` 一致后重跑；**勿**改库维度的临时 hack | +| `CONTENT_ROOT=… 不是目录` / `filesScanned=0` | 路径错误或目录空（**已拍板 · Q-4**：`filesScanned=0` **硬 FAIL**） | 修正 mount / 路径；确认 `methodology/`、`resume/`、`evidence/` **各 ≥1** `.md` 后再 sync | +| SiliconFlow / Supabase 网络或鉴权失败 | 上游或密钥问题 | 查 `SILICONFLOW_API_KEY`、Supabase service role；指数退避后重试 | +| `404 Job not found` | 进程重启或 redeploy（**已拍板 · Q-6:A**） | **重新 `POST`** 创建 job；sync 窗口内 **避免** 并发 redeploy | +| ingest 同步接口 `400` + 「维度」 | 同维度不匹配 | 与上表第一行相同 | + +**与 `POST /api/py/admin/ingest` 差异**：ingest 为同步且按 path 删；sync 为异步且按 slug 删。portfolio **仅**用 **`admin/sync`**（**已拍板 · Q-7:A**）；RUNBOOK **不包含** ingest 备用路径。 + +### 4.3 卷四 / 卷五 release 后再 sync 的运维节奏 + +| 事件 | 动作 | 负责人 | +| --- | --- | --- | +| 卷四或卷五 **公众 release** 合并/发布 | 确认前端 `content/` 已更新对应文稿 | 内容 + 前端 | +| release 后 **24h 内**（**已拍板 · Q-8:A**） | 对 **同一 CONTENT_ROOT** 执行一轮 `POST /api/py/admin/sync` | 运维 / 后端负责人 | +| sync `succeeded` | 跑 **五问 smoke**（至少 Q1 + Q5） | 验收负责人 | +| sync `failed` | 阻塞标记 release RAG 就绪；不得对外宣称语料已更新 | — | + +### 4.4 生产 / 本地 env 文档（须由 30 帽落盘 · 不含真实密钥） + +| 变量 | 用途 | 本地示例 | 生产要求 | +| --- | --- | --- | --- | +| **`CONTENT_ROOT`** | Markdown 扫描根 | `/path/to/ai-ink-brain/content`（见 `.env.example`） | 部署 mount 或 CI checkout 路径 **必须**指向前端 content 真值 | +| **`CHAT_API_SECRET`** 或 **`NEXT_PUBLIC_ADMIN_SECRET`**（Python 服务端 `.env`） | admin/sync 鉴权（Python 进程） | 本地 `.env` | 平台 Secrets；**禁止**进 Git；**值须与** 前端 **`SYNC_ADMIN_SECRET`** 一致 | +| **前端 `SYNC_ADMIN_SECRET`**（配对仓 · 服务端 only） | BFF `/api/admin/sync` 入站 + 转发 Bearer | 本机 `.env.local` | Vercel Secrets；文档 shell 别名 **`ADMIN_TOKEN`** | +| **`SILICONFLOW_API_KEY`** | Embedding | 本地 | 生产 Secrets | +| **`EMBEDDING_DIM`** / **`SILICONFLOW_EMBEDDING_DIMENSIONS`** | 与 `vector(N)` 一致 | `1024` | 与生产 Supabase 一致 | +| **`NEXT_PUBLIC_SUPABASE_URL`** + **`SUPABASE_SERVICE_ROLE_KEY`** | 写 `documents` | 本地 | 生产 | +| **`DEBUG_INGEST`** | 可选调试 | `1` 仅本地 | 生产 **关闭** | + +**文档落点（30 帽）**：`docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md` §C 增补 portfolio 段落，或独立 `docs/harness/guides/` 运维页（与 RUNBOOK 交叉链接）。 + +--- + +## 5. RUNBOOK 规格 + +本 SPEC **要求**另建可操作 RUNBOOK（30 帽正文），路径： + +**`docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md`** + +### 5.1 RUNBOOK 必含目录（大纲） + +| # | 小节 | 必含内容 | +| --- | --- | --- | +| 1 | **前提与权限** | 生产 URL、Bearer token 获取方式（不写明文）、`CONTENT_ROOT` 确认命令 | +| 2 | **Sync 执行** | `POST /api/py/admin/sync` curl 模板、轮询、`succeeded` 字段检查 | +| 3 | **Sync 失败排障** | §4.2.3 对照表 + 维度 / 空目录 / job 404 | +| 4 | **五问验收表** | Q1～Q5 标准问句、期望 category、通过标准（5/5 可答、sources ≥4/5） | +| 5 | **单问重试规则** | 同一问最多 **3** 次；仍失败则记录 blocker | +| 6 | **Sources 留证** | Q1、Q5 **必须**保存 `x-sources` 或 SSE sources 片段（Unified 路径） | +| 7 | **卷四/五 release 后再 sync** | §4.3 检查清单 | +| 8 | **附录：环境变量表** | 链 PROJECT_CONFIG §C | + +### 5.2 附录 A — RUNBOOK 大纲（本回合 · 非正文） + +```text +§1 前提 + - 演示站 Unified Chat 入口（BFF：同 Vercel 项目 portfolio 模式，如 https://ai-ink-brain.vercel.app/unified-chat） + - ChatBI visitor token（不禁 text2sql）；预发/Preview 与生产等价（§6.1） +§2 Sync + - curl POST/GET admin/sync；轮询间隔 2～5s；总超时 ≤60min + - 仅 sync（不含 admin/ingest 备用） +§3 失败排障 + - 维度 / CONTENT_ROOT / job 404（404 → 重新 POST；避免 redeploy 窗口） +§4 五问表（见 §6） +§5 重试 ≤3 +§6 Sources 留证（Q1/Q5 强制） +§7 Release 后再 sync +§8 Env 指针 +``` + +--- + +## 6. 验收标准（SPEC 级） + +### 6.1 Sync job + +- [ ] 人对 **预发 / Preview 或生产等价环境**（**已拍板 · Q-3**）执行 `POST /api/py/admin/sync`，job 终态 **`succeeded`** +- [ ] **硬门槛**（**已拍板 · Q-4**）：`result.filesScanned > 0`；`filesScanned=0` **记 FAIL** +- [ ] `result.filesScanned` 覆盖 `methodology/`、`resume/`、`evidence/` **各 ≥1** 个 `.md`（目标态参考 [`投递冲刺_20260609_v1_zh.md`](./投递冲刺_20260609_v1_zh.md) §3.2：`methodology/vol3_*`、`resume/cv-online.md`、`evidence/methodology-card.md`） +- [ ] `result.chunksUpserted > 0` + +### 6.2 五问 RAG 验收 + +**通过口径（已拍板）**： + +| 指标 | 阈值 | +| --- | --- | +| 可答率 | **5/5** 问均得到 **非空、切题** 回答 | +| Sources | **≥4/5** 问有可追溯 sources（Unified JSON `sources` / header `x-sources` / SSE 等价字段） | +| 单问重试 | 同一问 **≤3** 次仍不达标则记 FAIL，不得刷通过率 | + +**五问真值表**（问句与 [`投递冲刺_20260609_v1_zh.md`](./投递冲刺_20260609_v1_zh.md) §2 **逐字对齐** · Prompt 00 轮 2 · Q-1:A）： + +| # | 标准问句（chip / RUNBOOK 可粘贴） | 期望命中 `content/` 路径 | sources 主 `metadata.category`（硬约束） | 合格回答要点 | +| --- | --- | --- | --- | --- | +| **Q1** | 《AI 编程可闭环协作》**卷三**讲什么？Harness 和签收是什么？ | `methodology/vol3_*` | **`methodology`** | 任务单 + 书面签收 + 合并前 CI；sources 含 vol3 | +| **Q2** | **RAG 混合检索**怎么做的？ | `resume/*` 或项目段 | **`resume`** | 向量 + 混合检索 + rerank 至少两项 | +| **Q3** | **冷/温/热** 和 **架构三层** 区别？ | `evidence/*` | **`evidence` only**（**已拍板 · Q-2:A**；`methodology` 下 vol3 **不计** Q3 通过） | 记忆分层 ≠ 架构分层 | +| **Q4** | **11 年经历**里 AI Coding 相关成果？ | `resume/*` | **`resume`** | 百果园 Cursor + Ink + 连载；不虚构 | +| **Q5** | 按需读图相对整图灌入 **token/效果**？**边界**？ | `evidence/*` | **`evidence`** | 约 1/9 或「约十分之一」+ **小样本、非全行业** | + +**强制留证**（**已拍板 · Q-9:A**）： + +- [ ] **Q1**、**Q5** 的 sources JSON **可复现**：同 token、同问句预跑 **2 次**，sources 主 `metadata.category` **须一致**（不一致记 FAIL） + +### 6.3 文档 + +- [ ] RUNBOOK 正文落盘（§5 路径）且与 §4、§6 一致 +- [ ] `CONTENT_ROOT` 生产配置有 **非密钥** 留证（deploy 文档或 diary 样本） + +--- + +## 7. 工作包拆分（→ 未来 task 建议 · 本回合不创建 task） + +| ID | 工作包 | 交付物 | 建议 Harness | +| --- | --- | --- | --- | +| **W1** | SPEC 人审与 `freeze_id` | 本文件状态 → `active`/`done` | 人 | +| **W2** | RUNBOOK 正文 | `RUNBOOK_portfolio_rag_five_questions_v1_zh.md` | 30 | +| **W3** | env / deploy 文档 | PROJECT_CONFIG 或 guides 增补 `CONTENT_ROOT` 生产路径 | 30 | +| **W4** | 前端 content 三类目录 | 前端仓 `methodology|resume|evidence` + 前端 SPEC | 前端 30 | +| **W5** | 生产 sync + 五问预跑 | diary 留证、录屏 | 人 + 40 自检 | +| **W6** | task 创建 | `task_portfolio_rag_demo_v1` | 22 后 | + +**建议 task 字段草案**（冻结后填写）： + +- `test_strategy`: `recommended`（五问以人工 RUNBOOK 为主；可选 smoke pytest 由 task 择要） +- `failure_paths`: sync 维度失败、空 CONTENT_ROOT、job 404、五问 sources 不足 +- Open Folder: `ai-ink-brain-api-python`（W2/W3）；联调时开双仓 + +--- + +## 8. 后续 Epic（6/10+ · 非 6/9 门槛）— P1-B 双能力 handoff + +> **意图占位 only**；本 SPEC **不**写实现、不纳入 6/9 验收。 + +| 项 | 占位说明 | +| --- | --- | +| **目标** | Unified Chat SSE 上 **双能力 handoff** 最小闭环：例如 RAG 低置信 → 澄清 / Text2SQL handoff，事件类型 **`agent.handoff`**（名称 **待确认**，以 `_contract_manifest.json` 冻结为准） | +| **接口面** | `POST /api/py/unified/chat/stream` · Bearer ChatBI principal · 事件链见 `api/unified_chat.py`、`api/agent.py` | +| **与 portfolio 关系** | 演示站 visitor 已不禁 text2sql；handoff 为 **体验增强**，**不**替代本 Epic 的 ingest + 五问 | +| **依赖 SPEC** | ChatBI v3 系列 L1（如 LowConfidence / Events）；**禁止**在本治理 SPEC 内展开实现细节 | + +--- + +## 9. 关联引用 + +| 用途 | 路径 | +| --- | --- | +| 项目真值表 | [`docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md`](../../meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md) | +| ingest 实现 | [`api/ingest_pipeline.py`](../../../api/ingest_pipeline.py) | +| admin/sync 路由 | [`api/index.py`](../../../api/index.py)（`py_admin_sync_post` / `py_admin_sync_get`） | +| 投递计划（五问 §2） | [`投递冲刺_20260609_v1_zh.md`](./投递冲刺_20260609_v1_zh.md) | +| 配对前端 SPEC | `ai-ink-brain/content/tasks/specs/SPEC-portfolio_demo_site_v1_zh.md` | +| SDD 起草 | [`SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md`](../SPEC-SDD-Drafting-Intent-Rounds-v1_zh.md) | +| Wiki ingest（勿重复） | [`SPEC-Governance-Wiki-Ingest-Batch-v1.md`](./SPEC-Governance-Wiki-Ingest-Batch-v1.md) | +| 冷温热术语 | [`docs/harness/guides/GUIDE_冷温热层_对内术语_v1_zh.md`](../../harness/guides/GUIDE_冷温热层_对内术语_v1_zh.md) | +| Unified 契约 | [`docs/_tech_graph/_contract_manifest.json`](../../_tech_graph/_contract_manifest.json) | + +--- + +## 修订记录 + +| 日期 | 摘要 | +| --- | --- | +| 2026-06-01 | v1 **draft**：Harness 10 帽轮 1；§0～§9 + RUNBOOK 大纲；候选 `PORTFOLIO-RAG-DEMO@2026-06-0?` | +| 2026-06-01 | Prompt 00 **轮 2**：消化 Q-1～Q-5（五问 §2 写入 §6.2；Q3 strict evidence；预发等价；sync 空库 FAIL；freeze_id 冻结当日策略） | +| 2026-06-01 | Prompt 00 **轮 3**：消化 Q-6～Q-10；待确认清单清零 → **`active`** · `PORTFOLIO-RAG-DEMO@2026-06-01` | + +--- + +## SPEC 待确认清单 + +| # | 决策点 | 状态 | +| --- | --- | --- | +| 1～10 | Prompt 00 轮 1～3 全部决策点 | **resolved**（见 §1.1、§4.2、§4.3、§6.2 已拍板条文） | + +> **冻结说明**：本 Epic 6/9 范围内 **无 pending**；§8 P1-B handoff 事件名仍随 ChatBI 契约演进，**不阻塞**本 SPEC 冻结。 + +--- + +## 给 Cursor + +`portfolio`、`CONTENT_ROOT`、`admin/sync`、`五问验收`、`methodology`、`resume`、`evidence`、`PORTFOLIO-RAG-DEMO`、`RUNBOOK_portfolio_rag_five_questions` diff --git "a/docs/spec/governance/\346\212\225\351\200\222\345\206\262\345\210\272_20260609_v1_zh.md" "b/docs/spec/governance/\346\212\225\351\200\222\345\206\262\345\210\272_20260609_v1_zh.md" new file mode 100644 index 00000000..8e6f1e7e --- /dev/null +++ "b/docs/spec/governance/\346\212\225\351\200\222\345\206\262\345\210\272_20260609_v1_zh.md" @@ -0,0 +1,378 @@ +# 投递冲刺计划 · 2026-06-09 上午 + +| 项 | 内容 | +| --- | --- | +| **版本** | v1.2 | +| **日期** | 2026-06-01 | +| **状态** | `active` — 6/9 上午投递硬门槛 | +| **投递日** | **2026-06-09（周一）上午** | +| **关联** | [`NEXT_PRIORITIES_面试与项目落地_v1_zh.md`](./NEXT_PRIORITIES_面试与项目落地_v1_zh.md) · [`../JD/投递优先级合并_20260529.md`](../JD/投递优先级合并_20260529.md) · [`../JD/月之暗面/投递清单_最终_20260528.md`](../JD/月之暗面/投递清单_最终_20260528.md) | +| **公众连载真值** | [`ai-coding-closed-loop-articles`](../../Projects/ai-coding-closed-loop-articles/) · 当前 **v1.1.0**（卷一～三 release） | + +--- + +## 0. 决策摘要（已拍板） + +| # | 决策 | +| --- | --- | +| 1 | 演示：**改现有 `ai-ink-brain`**，portfolio 模式；**不开放**；简历注明 **邮件申请临时访客秘钥**（visitor / visitor-admin 两档、带失效） | +| 2 | 文章：**6/1 卷四 release** → 系列 **v1.2.0**；**6/3 前卷五 release** → 系列 **v1.3.0**；均发公众仓 | +| 3 | RAG：**五问生产预跑 + 录屏**；Vercel/Supabase 免费层不稳定，**单问重试 ≤3 次**算通过 | +| 4 | 多 Agent：**6/9 前不做**；下周 **双能力 handoff 最小闭环**；ChatBI v3 preview **下周再议** | +| 5 | STAR：**6/9 前骨架**；完整版 **下周**补（般果 Cursor 带教） | +| 6 | 简历：**本周再同步一次**（v1.3.0 连载、Vercel 子域、秘钥说明） | +| 7 | 投递顺序：**练手司 6/8** → **小红书 6/9 前段** → **月之暗面 6/9 后段（最后）** | +| 8 | 月之暗面：只投 **1 则** — **AI Coding Mentor（欢迎 Geek-Coder 投递！）· 加急** | +| 9 | 演示 URL：**临时 Vercel 子域**可写进简历 | +| 10 | 6/9 全绿：未全绿可砍 scope；**剩余项预计 6/9 上午前可完成 → 视为通过** | +| 11 | **T-01～T-06 已确认** — 见 §10 | + +--- + +## 1. 硬门槛 vs 可延后 + +### 1.1 6/9 上午前必须完成（P0） + +| ID | 交付物 | 完成标准 | +| --- | --- | --- | +| P0-A | 卷四 + 卷五 **公众 release** | 公众仓 tag/表头 **v1.3.0**；私仓 SERIES_VERSION 同步 | +| P0-B | **portfolio 演示站** | 四屏：首页 / 简历 / 方法论 / Unified Chat；`NEXT_PUBLIC_SITE_MODE=portfolio` | +| P0-C | **RAG 同源入库** | `content/methodology` + `resume` + `evidence` sync 后 **五问验收** | +| P0-D | **录屏** | 3～5 min：方法论 → 访客解锁说明 → Q1 + Q5 → sources | +| P0-E | **访客秘钥** | visitor / visitor-admin 可用；邮件回复模板就绪 | +| P0-F | **简历同步（6/6 一次性）** | 在线版 + 粘贴块 + **新 PDF**；含子域 URL（未定则 `[DEMO_URL]`）、邮件 **231127227@qq.com**、连载 v1.3.0 | +| P0-G | **Moonshot 专用包** | 6/8 前写好自荐 + PDF，6/9 只点发送 | + +### 1.2 6/9 后可完成（不挡投递） + +| ID | 交付物 | +| --- | --- | +| P1-A | STAR 完整版（般果带教） | +| P1-B | 双能力 handoff 最小闭环 + 5 demo 问句 | +| P1-C | ChatBI v3 preview 评估 | +| P1-D | 附册 A–C 合并 release（系列 v1.4.0） | + +--- + +## 2. RAG 五问验收（生产预跑 + 录屏） + +演示页建议做成 **预设 chip**；验收在 **生产 URL** 执行，失败 **同一问重试 ≤3 次**。 + +| # | 提问 | 期望命中 `content/` | 合格回答要点 | +| --- | --- | --- | --- | +| **Q1** | 《AI 编程可闭环协作》**卷三**讲什么？Harness 和签收是什么？ | `methodology/vol3_*` | 任务单 + 书面签收 + 合并前 CI；sources 含 vol3 | +| **Q2** | **RAG 混合检索**怎么做的？ | `resume/*` 或项目段 | 向量 + 混合检索 + rerank 至少两项 | +| **Q3** | **冷/温/热** 和 **架构三层** 区别？ | `evidence/*` 或 vol3 | 记忆分层 ≠ 架构分层 | +| **Q4** | **11 年经历**里 AI Coding 相关成果？ | `resume/*` | 百果园 Cursor + Ink + 连载；不虚构 | +| **Q5** | 按需读图相对整图灌入 **token/效果**？**边界**？ | `evidence/*` | 约 1/9 或「约十分之一」+ **小样本、非全行业** | + +**全绿判定：** 5/5 能答；sources **至少 4/5** 指向正确 category。 +**备份：** 录屏文件必留；线上面挂时主动播放。 + +**每次 release 新卷后：** 再跑 `admin/sync`，否则 Q1 仍可能只命中旧摘要。 + +--- + +## 3. 演示站方案（`ai-ink-brain` · 不新建前端仓） + +### 3.1 portfolio 模式 + +```bash +NEXT_PUBLIC_SITE_MODE=portfolio # development 保持原导航 +``` + +| 模式 | 公开导航 | Unified Chat | +| --- | --- | --- | +| `portfolio` | 首页 / 简历 / 方法论 / 对话 | 需 **访客秘钥**；隐藏 debug 面板 | +| 默认 | 现有全量 | admin 门槛不变 | + +**保留但不链出：** `/blog`、`/learning`、`/projects`、`/chat`、`/text2sql`、`/chain-chat`。 + +### 3.2 内容目录（展示 + RAG 同源） + +```text +ai-ink-brain/content/ +├── methodology/ # sync 自 ai-coding-closed-loop-articles（卷一～五 release 后） +├── resume/ +│ └── cv-online.md # 来自 docs/resume/cv/ +└── evidence/ + └── methodology-card.md # 1 页证据卡 + 卷四 §17 摘要 + 五问 chip 文案 +``` + +### 3.3 入库 + +```bash +# 后端 .env +CONTENT_ROOT=/path/to/ai-ink-brain/content + +curl -X POST "$PY_API_URL/api/py/admin/sync" \ + -H "Authorization: Bearer $ADMIN_TOKEN" +# 轮询 /api/py/admin/sync?jobId=… 至 done +``` + +### 3.4 访客秘钥（不对外开放） + +| 类型 | 权限 | 建议 TTL | 发放方式 | +| --- | --- | --- | --- | +| **visitor** | 方法论 + Unified Chat（**含 RAG + Text2SQL**；库内为可公开数据） | 72h | 邮件 **231127227@qq.com** | +| **visitor-admin** | 上述 + timeline / 部分 debug（**无** ingest/sync） | 24h | 二面申请 | + +**简历/邮件一句：** + +> 演示站：`[DEMO_URL]`（Vercel 子域，deploy 后补）· 对话请 **邮件 231127227@qq.com 申请临时访客秘钥**（普通/深度两档，过期失效）。 + +**6/9 前最小实现：** 预生成 2～3 组秘钥（env 或本地表）；`/api/auth/unlock` 扩展 role；portfolio 下无有效 session 显示「申请说明页」。 + +--- + +## 4. 文章 release 节奏 + +| 日期 | 动作 | 系列版 | +| --- | --- | --- | +| 已完成 | 卷一～三 release | **v1.1.0** | +| **6/1** | 卷四定稿 → 测评（可选）→ 公众仓 + 私仓 sync | **v1.2.0** | +| **≤6/3** | 卷五定稿 → 公众 release | **v1.3.0** | +| 6/9 后 | 附册 A 部分 / B 模板（可选） | v1.4.0 规划 | + +**私仓 → 公众仓：** 按 [`ai-coding-closed-loop-articles/SYNC_CHECKLIST.md`](../../Projects/ai-coding-closed-loop-articles/SYNC_CHECKLIST.md) 执行；删测评/内部指引行。 + +**release 后必做：** sync `content/methodology/` → admin sync → **重跑五问**。 + +--- + +## 5. 日程（6/1 → 6/9 上午） + +| 日期 | 重心 | 产出 | +| --- | --- | --- | +| **6/1 日** | 卷四全文 + release v1.2.0 | 公众稿 + 开写 portfolio task 单 | +| **6/2 一** | 卷五起草 | methodology sync 脚本 | +| **6/3 二** | 卷五 release v1.3.0 | content 五卷齐 | +| **6/4 三** | portfolio 页面 + 证据卡 | `/resume` `/methodology` | +| **6/5 四** | deploy + admin sync + **五问预跑** | 录屏 | +| **6/6 五** | **简历一次性同步** + 新 PDF + 访客秘钥 | 邮件模板（231127227@qq.com） | +| **6/7 六** | 模拟面 1 轮 + Moonshot 包 | STAR 骨架 | +| **6/8 日** | **Wave 1 练手投递** + 6/9 checklist | 智谱 / MiniMax | +| **6/9 上午** | Wave 2 小红书 → Wave 3 **月之暗面** | 见 §6 | + +--- + +## 6. 投递波次与岗位 + +### 6.1 Wave 1 · 练手（6/8） + +| 公司 | 岗位 | 备注 | +| --- | --- | --- | +| 智谱 | [GLM Coding Agent 数据与自动化迭代体系](https://app.mokahr.com/social-recruitment/zphz/148983?locale=zh-CN#/job/eb6e44ae-8d5e-4122-965d-b72f3922d08c) | 强调治理 + 数据迭代 | +| 智谱 | [AI Native 全栈（偏前端）](https://app.mokahr.com/social-recruitment/zphz/148983?locale=zh-CN#/job/df2018cf-348b-4519-bc1e-b5b3e9e1723b) | 强调 portfolio + AI Coding | +| MiniMax | [AGI 服务端工程师-Talkie&星野](https://vrfi1sk8a0.jobs.feishu.cn/index/position/7641108307957270820/detail)（**80.0**） | **无「AI Coding」专岗**；主轴选 Agent 应用服务端 | +| MiniMax（备选 1） | [AI Native 工程负责人 — AI 效能方向](https://vrfi1sk8a0.jobs.feishu.cn/index/position/7643719270614665535/detail)（73.8） | 与方法论/效能最接近，时间紧可二选一 | +| MiniMax（备选 2） | [AGI 服务端工程师（AI Agent / AI App）](https://vrfi1sk8a0.jobs.feishu.cn/index/position/7494586225161046282/detail)（74.0） | 练手备档 | + +> MiniMax JD 库中 **无** 月之暗面式「AI Coding Mentor」标题岗；「AI Coding」多出现在 Infra JD 要求里作工具技能，非岗位主轴。 + +（每司微调自荐 1 段即可；**PDF 6/6 新导**后共用。） + +### 6.2 Wave 2 · 小红书（6/9 上午前段） + +| 岗位 | 链接 | +| --- | --- | +| 大模型研发专家-AI Coding | [14358](https://job.xiaohongshu.com/social/position/14358) | +| 【急】AI Agent 产品研发 | [16393](https://job.xiaohongshu.com/social/position/16393) | + +### 6.3 Wave 3 · 月之暗面（6/9 上午后段 · **最后**） + +| 投 | 不投 | +| --- | --- | +| **[AI Coding Mentor（欢迎 Geek-Coder 投递！）· 加急](https://app.mokahr.com/apply/moonshot/148506#/job/722b8fdc-8473-4c73-bff5-fe5e4be38c00)** | 另一则非加急「AI Coding Mentor」（`a3c65002…`）— 同岗重复 | + +**Moonshot 叙事主轴：** 连载 v1.3.0 + 演示站（邮件秘钥）+ Harness/图谱有证据 v1 + AI 主导 Ink 交付 + 11 年工程底座。 + +--- + +## 7. 6/9 上午 Checklist + +### 全绿 + +- [ ] 公众仓 **v1.3.0**（卷四+卷五） +- [ ] Vercel **portfolio** 可访问；子域已写入简历 +- [ ] 生产 **五问** 通过（或每问 ≤3 次重试） +- [ ] **录屏** 就绪 +- [ ] **visitor / visitor-admin** 秘钥实测 +- [ ] **简历三件套（6/6）** 在线版 + 粘贴块 + 新 PDF；邮箱 **231127227@qq.com**；URL 未定则 `[DEMO_URL]` +- [ ] **Moonshot** 自荐 + PDF 预填，仅差提交 + +### 有条件通过 + +- 卷五若 **6/9 0:00 前** 可 release → 不挡 Wave 3；否则 Moonshot 自荐注明「卷五 24h 内 release」 +- ③ handoff、STAR 完整版 **不在门槛内** + +--- + +## 8. 面试叙事（Next.js 不熟悉 · AI Coding） + +> 个人站点是有意的 **AI 主导交付实验**：本人负责信息架构、SSE 契约、RAG 语料边界与 Harness task 验收；页面与 BFF 由 Cursor Agent 在 task 单下实现，我不手写 JSX 细节，但可追问路由、代理与流式行为。 + +**禁止 overclaim：** ChatBI 多 Agent 平台成熟 · 维护成本归零 · 全行业普适数字。 + +**6/9 后可说：** 「双能力 handoff 最小闭环（文档助手 / 分析助手）」— 见下周后端 task。 + +--- + +## 9. STAR 骨架（6/9 前 · 完整版下周） + +| | 内容 | +| --- | --- | +| **S** | 般果运营管理平台，团队开始用 Cursor 做日常需求 | +| **T** | 避免 AI 改乱架构、合并无签收 | +| **A** | 引入 task 说明 + 变更范围 + 自测清单；[待确认：带 1～2 同事试点] | +| **R** | [待确认：交付周期/返工率 — 无数字则写定性 + 边界] | + +--- + +## 10. 已确认项（2026-06-01） + +| ID | 结论 | +| --- | --- | +| **T-01** | Vercel 子域 **未定**；简历先用 `[DEMO_URL]`，deploy 后 **一次性回填**（6/6 简历改动时优先填） | +| **T-02** | 演示秘钥申请邮箱：**231127227@qq.com** | +| **T-03** | MiniMax **无 AI Coding 专岗** → Wave 1 主投 **AGI 服务端工程师-Talkie&星野**；备选自 §6.1 | +| **T-04** | **6/6 新导 PDF**；在线版/粘贴块 **6/6 针对性一次性改动**（此前不零散改简历） | +| **T-05** | visitor **不禁 text2sql**（个人项目、库内可公开） | +| **T-06** | 卷五 **主文优先**；**不含**附册 A 合并 release；见 §10.1 内容优先级 | + +### 10.1 附册 A vs 冷/温/热单独篇 — 优先级（导师建议） + +**6/9 前：二者均不挡投递**；卷五 **§23 FAQ #0 + 对照小表** 已承担「易混纠偏」最低义务。 + +| 内容 | 相对优先级 | 理由 | +| --- | --- | --- | +| **卷四 + 卷五主文 release** | **P0（最高）** | 6/9 叙事与 RAG 五问依赖 | +| **冷/温/热单独篇章** | **P1（6/9 后 · 高于附册 A）** | 读者最大误读点；卷三已发不宜改正文；独立篇可深讲愿景与操作纪律，**Moonshot Mentor 二面加分**；私仓已有 [`ARTICLE_黑盒模型白盒轨迹_冷温热层…`](../../Projects/ai_coding_governance/narrative/ARTICLE_黑盒模型白盒轨迹_冷温热层与可追责协作_draft_v1_zh.md) 可续写 | +| **附册 A（术语索引表）** | **P2（低于单独篇）** | 查阅型、可 patch；卷五 §23 + 单独篇发表后，**从两稿抽表** 合成附册 A 更高效，避免三处重复维护 | + +**建议排期：** + +```text +6/1–6/3 卷四 + 卷五 release（§23 含冷温热 FAQ 对照表） +6/9 投递 +6/10–6/16 冷/温/热单独篇 v0.1（公众或专栏；可不进系列 semver MINOR） +6/16+ 附册 A v1.0（从卷五 §23 + 单独篇 **抽取** 术语表，非重写） +``` + +**勿在 6/3 前为附册 A 或单独篇拖卷五主文。** + +--- + +## 11. 跨仓 Agent Prompt + +> **前后端 portfolio / RAG**：先 **10 帽出 SPEC**，人审冻结后再开 task 链（见 [`prompts/README.md`](./prompts/README.md)）。 +> **禁止**跳过 SPEC 直接写 `task_*.md` 或改业务代码。 + +| 仓 | 阶段 | Prompt 文件 | SPEC 落盘路径 | +| --- | --- | --- | --- | +| `ai-ink-brain` | 10 · SDD 起草 | [`prompts/PROMPT_10_SPEC_portfolio_frontend_v1_zh.md`](./prompts/PROMPT_10_SPEC_portfolio_frontend_v1_zh.md) | `content/tasks/specs/SPEC-portfolio_demo_site_v1_zh.md` | +| `ai-ink-brain-api-python` | 10 · SDD 起草 | [`prompts/PROMPT_10_SPEC_portfolio_backend_v1_zh.md`](./prompts/PROMPT_10_SPEC_portfolio_backend_v1_zh.md) | `docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md` | + +**推荐顺序**：前后端 **并行** 跑 10 帽 SPEC → 人对齐 §8 待确认 → 冻结 `freeze_id` → 各仓 **另 Prompt** 从 task/30 实施（本计划暂不附实现 Prompt）。 + +--- + + +### 11.1 `docs`（personal-docs） + +```markdown +## 任务：投递冲刺文档与简历同步（docs 仓） + +**背景**：投递日 2026-06-09 上午。真值计划见 `planning/投递冲刺_20260609_v1_zh.md`。 + +**执行日**：**6/6 一次性**（此前不零散改在线简历）。 + +**请完成**： +1. 更新 `resume/cv/cv-online-ai-coding-202606.md`： + - 连载 **系列 v1.3.0**（卷一～五） + - GitHub 连载 + `[DEMO_URL]`（deploy 后填，无则留占位） + - 演示秘钥：**231127227@qq.com** 邮件申请（普通/深度、过期失效） +2. 同步 `resume/cv/cv-online-ai-coding-粘贴块.txt` +3. **新导 PDF**（替换 `刘新宁-11年-AICoding.pdf` 或同目录新文件名，与在线版一致） +4. 新建 `planning/邮件模板_演示站访客秘钥_v1_zh.md`（发件人说明用 231127227@qq.com） +5. 新建 `planning/STAR_般果Cursor带教_骨架_v1_zh.md`（完整版下周；6/6 可先落骨架） + +**禁止**：虚构指标；6/6 前勿多次半套改动导致版本混乱。 + +**验收**：在线版 = 粘贴块 = PDF 三件套一致。 +``` + +--- + +### 11.2 `ai_coding_governance`（私仓叙事） + +```markdown +## 任务：卷四 release（6/1）+ 卷五 release（≤6/3） + +**背景**：公众仓已 v1.1.0（卷一～三）。投递冲刺见 docs 仓 `planning/投递冲刺_20260609_v1_zh.md`。 +**Skill**：`.cursor/skills/public-narrative-zh/SKILL.md` + vol4/vol5 revision-workflow。 + +**卷四（今日目标）**： +1. 读 `narrative/ARTICLE_*_vol4_OUTLINE骨架_v1_zh.md` §0 P0 扫描清单并勾选 +2. 写 `narrative/ARTICLE_*_vol4_draft_v1_zh.md` §17–§20（公众可读；AB 数字带 §7.2 边界） +3. 可选 DeepSeek 测评 → 小改 +4. 同步到 `../ai-coding-closed-loop-articles/` 按 SYNC_CHECKLIST；系列 **v1.2.0** + +**卷五（≤6/3）**： +1. 按 `vol5_OUTLINE` 写 §21–§26；§23 FAQ 为主载体（冷温热对照表等） +2. 案例 **匿名化**；不写未 done 的 ChatBI 为已发布 +3. 公众 release；系列 **v1.3.0** + +**同时产出（供 RAG）**： +- `docs/planning/` 或 narrative 内 1 页 **方法论证据卡** markdown（可拷贝到 ink-brain `content/evidence/`） + +**禁止**：PR 号、真实 task slug、维护归零、merge KPI。 + +**验收**：私仓 draft 状态改 release；`SERIES_VERSION_v1_zh.md` §3 更新。 +``` + +--- + +### 11.3 `ai-coding-closed-loop-articles`（公众仓） + +```markdown +## 任务：接收卷四/卷五 release 并维护系列版本 + +**背景**：当前 v1.1.0。6/1 卷四 → v1.2.0；≤6/3 卷五 → v1.3.0。 + +**请完成**（每卷 release 一次）： +1. 从私仓 `ai_coding_governance/narrative/` cp 定稿 md + 更新 OUTLINE +2. 执行 `SYNC_CHECKLIST.md`：删内部元信息行、更新 README 表、SERIES_VERSION.md +3. 卷四/卷五若需粘贴版：在 `assets/PUBLISH_卷四_*` / `卷五_*` 生成（可选 `node scripts/publish-final.mjs`） +4. Git tag：`series-v1.2.0` / `series-v1.3.0` + +**验收**：README 阅读顺序含卷四/五；GitHub 可直读；无测评 prompt 链接进正文。 +``` + +--- + +### 11.4 `ai-ink-brain`（前端 · **仅 SPEC**） + +→ 打开 [`prompts/PROMPT_10_SPEC_portfolio_frontend_v1_zh.md`](./prompts/PROMPT_10_SPEC_portfolio_frontend_v1_zh.md)，复制 **「Agent 指令块」** 整段。 + +**本阶段交付**：`content/tasks/specs/SPEC-portfolio_demo_site_v1_zh.md`（`draft`）+ 待确认清单 ≤5 条。 +**下一阶段**（人审后另开）：由 SPEC §7 工作包拆 `task_portfolio_demo_site_v1.md` → 22→30→50。 + +--- + +### 11.5 `ai-ink-brain-api-python`（后端 · **仅 SPEC**） + +→ 打开 [`prompts/PROMPT_10_SPEC_portfolio_backend_v1_zh.md`](./prompts/PROMPT_10_SPEC_portfolio_backend_v1_zh.md)，复制 **「Agent 指令块」** 整段。 + +**本阶段交付**：`docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md`（`draft`）+ RUNBOOK 大纲 + 待确认清单。 +**6/10+ 另 Epic**：双能力 handoff — 本 SPEC 仅 §后续 Epic 占位，**不在本 Prompt 展开**。 + +--- + +## 12. 修订记录 + +| 版本 | 日期 | 说明 | +| --- | --- | --- | +| v1.0 | 2026-06-01 | 初稿：6/9 投递、五问、portfolio、三波次序、跨仓 Prompt | +| v1.1 | 2026-06-01 | 回填 T-01～T-06；MiniMax 岗位；6/6 简历/PDF；冷温热单独篇 > 附册 A | +| v1.2 | 2026-06-01 | §11 前后端改为 10 帽 SPEC-only；新增 `planning/prompts/` | diff --git a/docs/tasks/active/task_portfolio_rag_demo_v1.md b/docs/tasks/active/task_portfolio_rag_demo_v1.md new file mode 100644 index 00000000..539cc633 --- /dev/null +++ b/docs/tasks/active/task_portfolio_rag_demo_v1.md @@ -0,0 +1,257 @@ +# Task：Portfolio 演示站 RAG — RUNBOOK · env 文档 · 五问预跑留证（后端） + +> **状态**：`in_progress`（30 W2/W3 done · W5 待人 · 40 文档 tranche 自检完成） +> **schedule_ref**：投递冲刺 [`投递冲刺_20260609_v1_zh.md`](../spec/governance/投递冲刺_20260609_v1_zh.md) · P0-C +> **硬 deadline**：**2026-06-09 上午**（投递前 ingest 对齐 + 五问 RUNBOOK + 预发/生产等价环境 sync 与五问预跑留证） +> **治理 SPEC（L1 · 已冻结）**：[`SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md`](../spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md) · `PORTFOLIO-RAG-DEMO@2026-06-01` +> **配对前端 SPEC（只读）**：`ai-ink-brain/content/tasks/specs/SPEC-portfolio_demo_site_v1_zh.md` +> **关联图谱**：[`docs/_tech_graph/10_flow_ingest.ai.md`](../_tech_graph/10_flow_ingest.ai.md)（ingest/sync 只读对照） + +--- + +## Harness 元信息（执行 Agent 必读） + +| 字段 | 值 | +|------|-----| +| **task_slug** | `portfolio-rag-demo` | +| **test_strategy** | `recommended` | +| **test_strategy_note** | 验收以 **人工 RUNBOOK**（sync 轮询 + 五问预跑 + sources 留证）为主；可选补 smoke pytest（如 ingest env 解析）由 30 择要，**非** red-green 硬门槛 | +| **freeze_id** | `PORTFOLIO-RAG-DEMO@2026-06-01` | +| **gates_before_code** | `failure_paths`、必读列表、验收命令、W4 前端 content 就绪确认 | +| **semi_auto** | `true` | +| **audit_profile** | `post_close` | +| **experience_capture** | `recommended` | +| **kpi_rubric** | `KPI_RUBRIC_v1_2` | +| **kpi_aggregator** | `CLOSE` | +| **git_branch** | `task/portfolio-rag-demo-v1` | +| **Open Folder** | `ai-ink-brain-api-python`（W2/W3 落盘）；W5 预跑须开双仓读前端 content / Unified Chat | +| **推荐路径** | **A（22 R1）** — 与前端 portfolio task 审查节奏对齐 | + +### 工作包映射（SPEC §7 → 本 task） + +| SPEC ID | 工作包 | 本 task 范围 | 执行帽 | +|---------|--------|--------------|--------| +| W2 | RUNBOOK 正文 | **在范围** | 30 | +| W3 | env / deploy 文档 | **在范围** | 30 | +| W5 | 生产 sync + 五问预跑留证 | **在范围**（人触发 sync；40 回填留证） | 人 + 40 | +| W4 | 前端 content 三类目录 | **依赖 · 非本仓 commit** | 前端 30 | +| W1 | SPEC 冻结 | **已完成** | — | + +### 跨仓依赖 + +| 项 | 说明 | +|----|------| +| **blocked_by** | 前端 W4：`ai-ink-brain/content/{methodology,resume,evidence}/` 目标态文稿就绪（见 [`投递冲刺_20260609_v1_zh.md`](../spec/governance/投递冲刺_20260609_v1_zh.md) §3.2） | +| **blocks** | 投递 P0-C / P0-D 录屏；前端 portfolio 演示站五问 chip 联调 | +| **配对 task** | `ai-ink-brain` · `task_portfolio_demo_site_v1`（并行 Harness · 22 R1 节奏对齐） | + +### 人工闸 `human_gate` + +| human_gate_id | status | blocks_hats | 说明 | +|---------------|--------|-------------|------| +| HG-TASK-DRAFT | approved | 22-R1,30 | semi_auto 链式执行人授权 · 2026-06-01 | +| HG-AUDIT-R1 | approved | 30 | 22 R1 零阻塞 · `reviews/.../audit_R1_20260601.md` | +| HG-W5-SYNC | pending | — | **人**在预发/生产等价环境 sync `succeeded` 后改 approved | +| HG-W5-FIVE-Q | pending | done | 五问预跑 + diary 留证人签 | +| HG-REINSPECT | approved | done | 50 复检后人签、合并 PR 前 | + +--- + +## 1. 背景与目标 + +Portfolio 演示站需在 **2026-06-09 投递前** 展示与前端 `content/` **同源** 的 RAG 问答能力：语料经 **`POST /api/py/admin/sync`** 入库（`CONTENT_ROOT` → 前端仓 `ai-ink-brain/content/`），并通过 **可复现的五问 RUNBOOK** 验收 Q1～Q5。 + +**本 task 完成态（后端仓）**： + +1. **W2**：可操作 RUNBOOK 落盘 [`docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md`](../harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md)，与 SPEC §4～§6 一致。 +2. **W3**：`CONTENT_ROOT` 及 admin/sync 相关 env 的 **生产/本地部署说明** 落盘（`PROJECT_CONFIG` §C 增补 portfolio 段落，与 RUNBOOK §8 交叉链接）。 +3. **W5**：在 **预发 / Preview 与生产等价环境**（同 Supabase、同 Embedding 维、同 `CONTENT_ROOT` 挂载语义）由 **人** 执行 sync + 五问预跑，留证于 `docs/diary/samples/portfolio-rag-demo/`（路径由 RUNBOOK 指定）；40 帽回填 task **`### 自检结论（执行者）`**。 + +**现网 ingest 行为无需改码**（SPEC §2 扫描结论）：category = 相对路径第一段；portfolio 仅 **`admin/sync`** 路径。 + +--- + +## 2. 范围 + +### 2.1 W2 · RUNBOOK（30 帽交付） + +- [x] **G-W2-1** 新建 RUNBOOK，必含 SPEC §5.1 八节：前提与权限 / Sync 执行 / 失败排障 / 五问验收表 / 单问重试 ≤3 / Sources 留证（Q1、Q5 强制）/ 卷四·五 release 后再 sync / Env 指针 +- [x] **G-W2-2** 五问问句与 [`投递冲刺_20260609_v1_zh.md`](../spec/governance/投递冲刺_20260609_v1_zh.md) §2 **逐字对齐**（SPEC §6.2 真值表） +- [x] **G-W2-3** Q3 sources 硬约束：**仅** `metadata.category == evidence`（不含 methodology vol3） +- [x] **G-W2-4** Sync 硬检查：`succeeded` 且 `filesScanned > 0` 且 `chunksUpserted > 0`；三目录各 ≥1 `.md` +- [x] **G-W2-5** 仅 `admin/sync`；**不含** `admin/ingest` 备用路径 +- [x] **G-W2-6** 轮询间隔 2～5s，总超时 ≤60 min；`404 Job not found` → 重新 POST + +### 2.2 W3 · env / deploy 文档（30 帽交付） + +- [x] **G-W3-1** 在 [`PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md`](../meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md) **§C** 增补 **portfolio 演示站** 段落：`CONTENT_ROOT`、`NEXT_PUBLIC_ADMIN_SECRET`/`CHAT_API_SECRET`、`EMBEDDING_DIM`、`SILICONFLOW_*`、Supabase 写库变量（**不含真实密钥**） +- [x] **G-W3-2** 说明本地 `CONTENT_ROOT` 指向前端仓 `content/` 的示例；生产 mount / CI checkout 语义与 Vercel 部署边界（SPEC §1.1 Q-3） +- [x] **G-W3-3** 明确 **禁止** 生产依赖后端仓默认 `REPO_ROOT/content` 回退作为 portfolio 真值 +- [x] **G-W3-4** RUNBOOK §8 与 PROJECT_CONFIG 双向链接 + +### 2.3 W5 · 预跑留证（人 + 40 帽 · 本 task 验收项） + +> **Agent 禁止** 在本 task 内对生产/预发执行 `POST /api/py/admin/sync`；仅 RUNBOOK 与留证目录规范。 + +- [ ] **G-W5-1** 前置：HG-W5-SYNC 人签 — 预发/生产等价环境 sync job **`succeeded`**，且 `filesScanned` 覆盖 `methodology/`、`resume/`、`evidence/` **各 ≥1** +- [ ] **G-W5-2** 五问预跑：**5/5** 非空切题；sources **≥4/5**；单问重试 **≤3** 次 +- [ ] **G-W5-3** Q1、Q5 sources JSON **可复现**：同 token、同问句预跑 **2 次**，主 `metadata.category` **一致** +- [ ] **G-W5-4** 留证落盘 `docs/diary/samples/portfolio-rag-demo/`：sync job 终态 JSON 摘要、Q1/Q5 sources 片段、五问结果表（pass/fail + 重试次数）；可选录屏路径索引链 [`投递冲刺_20260609_v1_zh.md`](../spec/governance/投递冲刺_20260609_v1_zh.md) P0-D +- [ ] **G-W5-5** Unified Chat 路径（`/api/py/unified/chat` 或 `/stream` + visitor token）；visitor **不禁 text2sql**（T-05） + +--- + +## 3. 非范围 + +- 改 `api/`、`tests/` **业务实现**（ingest 现码已满足 SPEC §2） +- 前端 Next 页面 / portfolio UX / 访客秘钥实现（前端 SPEC + task） +- 本 task 回合 **执行** 生产或预发 `admin/sync`（仅 RUNBOOK 与留证规范） +- 新建或大幅变更 `documents` schema、GraphRAG、Wiki batch ingest +- ChatBI v3 preview 全链、§8 P1-B 双能力 handoff（6/9 后 Epic） +- 卷四/卷五 **内容创作** 与公众 release（属 docs / 公众仓；release 后再 sync 见 RUNBOOK §7） + +--- + +## 行为变更（Delta） + +**无** — 本 task 为 **文档 + 运维 RUNBOOK + 人工验收留证**；不修改对外 API 契约。关账时可把 RUNBOOK 路径写入 SPEC §9 关联表（可选 patch，非本 task 硬门槛）。 + +--- + +## 5. 依赖与引用 + +| 依赖项 | 路径 / 说明 | +|--------|-------------| +| 治理 SPEC | [`SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md`](../spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md) | +| 投递计划 | [`投递冲刺_20260609_v1_zh.md`](../spec/governance/投递冲刺_20260609_v1_zh.md) §2 五问 · §3.2 content 树 | +| PROJECT_CONFIG | [`PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md`](../meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md) | +| ingest 实现（只读） | `api/ingest_pipeline.py`、`api/index.py`（admin/sync） | +| 冷温热术语 | [`GUIDE_冷温热层_对内术语_v1_zh.md`](../harness/guides/GUIDE_冷温热层_对内术语_v1_zh.md) | +| Unified 契约 | [`docs/_tech_graph/_contract_manifest.json`](../_tech_graph/_contract_manifest.json) | +| `.env.example` | 仓库根 · `CONTENT_ROOT` 注释 | + +--- + +## 验收标准 + +### 6.1 文档（30 完成后） + +- [x] RUNBOOK 路径存在且 §5.1 八节齐全 +- [x] PROJECT_CONFIG §C portfolio 段落存在且无真实密钥 +- [x] RUNBOOK 与 SPEC §4.2.3 失败语义表 **一致** + +### 6.2 预跑（W5 · 40 + 人签） + +- [ ] sync job 终态 `succeeded` + 硬检查通过（§2.3 G-W5-1） +- [ ] 五问指标达标（§2.3 G-W5-2～G-W5-3） +- [ ] `docs/diary/samples/portfolio-rag-demo/` 留证可读（§2.3 G-W5-4） +- [ ] HG-W5-SYNC、HG-W5-FIVE-Q → `approved` + +### 6.3 CI + +- [ ] `pytest tests -m "not intent_eval and not intent_benchmark"` 仍绿（本 task **不应** 引入 api 变更；若仅 docs 则作回归确认） + +--- + +## 失败路径 + +| # | Scenario ID | 触发条件 | 系统行为 | 可重试 | 用户可见 / RUNBOOK 处置 | +|---|-------------|----------|----------|--------|-------------------------| +| F1 | `fp-portfolio-embed-dim` | Embedding 维度与 `vector(N)` 不一致 | sync job `failed`；`error` 含「维度」 | 修正 env 后 **重跑 sync** | RUNBOOK §3 对照表第一行 | +| F2 | `fp-portfolio-files-scanned-zero` | `CONTENT_ROOT` 非目录或空树；`filesScanned=0` | job 可能 `succeeded` 但 **硬 FAIL**（Q-4） | 修正 mount / 补 content 后重跑 | **不得**进入五问 | +| F3 | `fp-portfolio-job-404` | `404 Job not found`（redeploy） | GET 轮询 404 | **重新 POST** 创建 job | sync 窗口避免并发 redeploy | +| F4 | `fp-portfolio-upstream-auth` | SiliconFlow / Supabase 鉴权或网络失败 | job `failed` 或超时 | 指数退避；查 Secrets | RUNBOOK §3 | +| F5 | `fp-portfolio-five-q-retry` | 五问单问 3 次仍不达标 | 记该问 **FAIL** | 可调 query/chip 或补 content 后再 sync | 不得刷通过率；阻塞 6/9 全绿 | +| F6 | `fp-portfolio-sources-drift` | Q1/Q5 两次预跑 sources category 不一致 | 记 **FAIL**（Q-9:A） | 查 ingest category / 文稿路径 | diary 留证须标注 blocker | +| F7 | `fp-portfolio-q3-evidence` | Q3 sources 命中 `methodology` | Q3 **FAIL**（strict evidence） | 调整 evidence 文稿或检索参数 | RUNBOOK 五问表须写明 | +| F8 | `fp-portfolio-w4-blocked` | 前端 W4 未就绪即 sync | `filesScanned` 不足三目录 | 等待前端 content 后再 sync | task `blocked_by` | + +--- + +## 8. 给执行帽的必读列表（30 · 按序） + +1. 本 task 全文 + **`failure_paths`** + **`human_gate`** +2. [`SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md`](../spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md) §4～§6 +3. [`投递冲刺_20260609_v1_zh.md`](../spec/governance/投递冲刺_20260609_v1_zh.md) §2 五问表 +4. [`PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md`](../meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md) §C（改前读现表） +5. `api/ingest_pipeline.py` · `get_all_markdown_chunks()`（只读 · category 规则） +6. `api/index.py` · admin/sync 路由（只读 · job 字段） +7. 22 R1 审查 [`docs/harness/reviews/task_portfolio_rag_demo_v1_audit_R1_*.md`](../harness/reviews/)（**30 开工前须存在且零阻塞**） + +**验证命令（合并前）**：`pytest tests -m "not intent_eval and not intent_benchmark"` + +--- + +## 9. 文档矛盾（须以 freeze_id 为准） + +| 矛盾 | 出处 A | 出处 B | task 口径 | +|------|--------|--------|-----------| +| Q3 期望路径 | 投递冲刺 §2：「`evidence/*` **或 vol3**」 | SPEC §6.2（Q-2:A）：sources **仅** `evidence` | **以 SPEC / freeze_id 为准**；RUNBOOK 写 strict evidence | + +--- + +### 6.3 CI + +- [x] `pytest tests -m "not intent_eval and not intent_benchmark"` 仍绿（本 task **不应** 引入 api 变更；若仅 docs 则作回归确认） + +--- + +## 10. 实现备忘（30 回填） + +| 文件 | 动作 | 状态 | +|------|------|------| +| `docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md` | **新建** | done · 30 | +| `docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md` | §C.1 增补 portfolio | done · 30 | +| `docs/diary/samples/portfolio-rag-demo/README.md` | W5 留证索引 | done · 30（正文待人） | +| `api/`、`tests/` | **不改** | — | + +--- + +### 自检结论（执行者） + +> **40 帽 · 2026-06-01 · 分支 `task/portfolio-rag-demo-v1`** + +#### 命令与退出码 + +| 命令 | cwd | 退出码 | 摘要 | +|------|-----|--------|------| +| `pytest tests -m "not intent_eval and not intent_benchmark" -q` | 仓库根 | **0** | **277 passed**, 1 skipped, 2 deselected | + +#### 验收表（文档 tranche） + +| 验收项 | 结果 | 证据 | +|--------|------|------| +| §6.1 RUNBOOK 八节 | pass | `docs/harness/guides/RUNBOOK_portfolio_rag_five_questions_v1_zh.md` | +| §6.1 PROJECT_CONFIG §C.1 | pass | `docs/meta/PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md` | +| §6.1 失败语义一致 | pass | RUNBOOK §3 ↔ SPEC §4.2.3 | +| §6.3 pytest 回归 | pass | 见上表 | +| §6.2 W5 sync + 五问 | **未测** | `HG-W5-SYNC` / `HG-W5-FIVE-Q` pending；待人按 RUNBOOK 执行 | +| §2.3 G-W5-1～5 | **未测** | 留证目录仅 README 索引 | + +#### OpenSpec × TDD 三维（docs task） + +| 维度 | 结果 | +|------|------| +| Completeness | pass（W2/W3 交付物齐；W5 显式 defer） | +| Correctness | pass（五问/Q3 strict 与 freeze_id 一致） | +| Coherence | pass（RUNBOOK ↔ PROJECT_CONFIG ↔ SPEC） | + +#### 已知未测项 + +- 生产/预发 `admin/sync` 与五问预跑（**禁止 Agent 执行**） +- 前端 W4 content 三类目录就绪性（跨仓 · 人确认） + +--- + +## 11. 修订记录 + +| 日期 | 摘要 | +|------|------| +| 2026-06-01 | 10 帽草案：自 SPEC §7 W2/W3/W5 拆 task；`PORTFOLIO-RAG-DEMO@2026-06-01` | +| 2026-06-01 | 22 R1 零阻塞 · 30 W2/W3 落盘 · 40 文档 tranche 自检（W5 defer） | + +--- + +## 给 Cursor + +`portfolio-rag-demo`、`CONTENT_ROOT`、`admin/sync`、`五问验收`、`RUNBOOK_portfolio_rag_five_questions`、`freeze_id`、`failure_paths`、`HG-W5-SYNC` diff --git a/docs/tasks/reinspect_results/reinspect_portfolio_rag_demo_v1_20260601_v1.md b/docs/tasks/reinspect_results/reinspect_portfolio_rag_demo_v1_20260601_v1.md new file mode 100644 index 00000000..8f026ad5 --- /dev/null +++ b/docs/tasks/reinspect_results/reinspect_portfolio_rag_demo_v1_20260601_v1.md @@ -0,0 +1,117 @@ +# 独立复检报告 · portfolio-rag-demo v1 + +| 字段 | 值 | +|------|-----| +| **task** | `docs/tasks/active/task_portfolio_rag_demo_v1.md` | +| **task_slug** | `portfolio-rag-demo` | +| **freeze_id** | `PORTFOLIO-RAG-DEMO@2026-06-01` | +| **模式** | 独立复检（未执行全局验收 §二） | +| **git_branch** | `task/portfolio-rag-demo-v1` | +| **diff 范围** | `origin/main...HEAD` · RUNBOOK / PROJECT_CONFIG §C.1 / task / reviews / invokes / diary samples | +| **audit_R1** | `docs/harness/reviews/by-task/portfolio-rag-demo/task_portfolio_rag_demo_v1_audit_R1_20260601.md` | +| **50 invoke** | `docs/harness/invokes/by-task/portfolio-rag-demo/invoke_20260601_50_portfolio-rag-demo.md` | +| **复检员** | Agent（50 帽 · Fresh Context） | +| **日期** | 2026-06-01 | + +--- + +## 1. 开帽检查 + +| 检查项 | 结果 | +|--------|------| +| `### 自检结论（执行者）` 存在 | **pass** · task L210–242 | +| REINSPECT_MODE 字面 | **独立复检** | +| 30 invoke 全文 | **未读**（P1 Fresh Context） | +| R1 审查 | **零阻塞** · 与 W2/W3 tranche 一致 | + +--- + +## 2. 独立复检 · 验收矩阵 + +### 2.1 W2 · RUNBOOK + +| 验收项 | pass/fail/defer | 证据 | 备注 | +|--------|-----------------|------|------| +| G-W2-1 八节齐全 | **pass** | `RUNBOOK_portfolio_rag_five_questions_v1_zh.md` §1–§8 | 对应 SPEC §5.1 | +| G-W2-2 五问问句逐字 | **pass** | RUNBOOK §4 L113–117 ↔ `投递冲刺_20260609_v1_zh.md` §2 L63–67 | 问句一致；Q3 路径以 freeze strict evidence 为准 | +| G-W2-3 Q3 strict evidence | **pass** | RUNBOOK §4 Q3 L115–116 | 明示 methodology vol3 不计通过 | +| G-W2-4 Sync 硬检查 | **pass** | RUNBOOK §2.3 L84–90 | filesScanned/chunksUpserted/三目录 | +| G-W2-5 仅 admin/sync | **pass** | RUNBOOK 表头 L11、§2；全文无 `admin/ingest` 操作路径 | 与 SPEC §4.2.3 末行一致 | +| G-W2-6 轮询与 404 | **pass** | RUNBOOK §2.2 L77–80、§3 L102 | 2–5s、≤60min、重新 POST | + +### 2.2 W3 · env 文档 + +| 验收项 | pass/fail/defer | 证据 | 备注 | +|--------|-----------------|------|------| +| G-W3-1 PROJECT_CONFIG §C.1 | **pass** | `PROJECT_CONFIG_AI_INK_BRAIN_API_PYTHON.md` L118–137 | 无真实密钥 | +| G-W3-2 本地示例与部署边界 | **pass** | PROJECT_CONFIG L127–128、133–137 | Vercel/portfolio 边界 | +| G-W3-3 禁止 REPO_ROOT 回退 | **pass** | PROJECT_CONFIG L126 | 与 RUNBOOK §1.1 一致 | +| G-W3-4 双向链接 | **pass** | PROJECT_CONFIG L121 ↔ RUNBOOK §8 L172–174 | — | + +### 2.3 W5 · 预跑留证（defer 口径） + +| 验收项 | pass/fail/defer | 证据 | 备注 | +|--------|-----------------|------|------| +| G-W5-1 sync succeeded + 三目录 | **defer** | task 自检 §6.2 **未测**；`HG-W5-SYNC` pending | **非** 30/文档 tranche 阻塞 | +| G-W5-2 五问指标 | **defer** | 同上 | 待人按 RUNBOOK §4 | +| G-W5-3 Q1/Q5 双跑一致 | **defer** | `diary/samples/` 无 `q*-sources-run*.json` | — | +| G-W5-4 留证落盘 | **defer** | 仅 `README.md` L1–20 索引 | 预期文件未生成 | +| G-W5-5 Unified 路径 | **defer** | RUNBOOK §1.1、§4 已写明；**未执行**预跑 | 规范 pass，执行 defer | + +### 2.4 §6 关账勾选 + +| 验收项 | pass/fail/defer | 证据 | 备注 | +|--------|-----------------|------|------| +| §6.1 RUNBOOK 八节 | **pass** | 同 G-W2-1 | — | +| §6.1 PROJECT_CONFIG portfolio | **pass** | §C.1 | — | +| §6.1 失败语义一致 | **pass** | RUNBOOK §3 ↔ SPEC §4.2.3 L160–166 | 维度/CONTENT_ROOT/404/ingest 400 对齐 | +| §6.2 sync + 五问 | **defer** | 40 自检 L228–229 | W5 口径 | +| §6.2 留证可读 | **defer** | README 占位 | — | +| §6.2 HG-W5-* approved | **defer** | task human_gate 表 L54–55 pending | **须人审** | +| §6.3 pytest | **pass** | 50 复检：`277 passed, 1 skipped`（exit 0） | 与 40 报告一致 | + +--- + +## 3. 阻塞合并项（维护者） + +| ID | 阻塞？ | 说明 | +|----|--------|------| +| W2/W3 文档交付 | **否** | 全部 pass | +| W5 预跑 / §6.2 | **否（本 PR diff）** | **defer**；不判 fail（未声称 W5 完成） | +| pytest / api 变更 | **否** | 无 `api/`/`tests/` diff；pytest 绿 | +| HG-REINSPECT | **合并 PR 前须人签** | 50 不代填 `approved` | +| HG-W5-SYNC / HG-W5-FIVE-Q | **关账前须人签** | sync + 五问后 | + +--- + +## 4. 合并建议 + +| 维度 | 建议 | +|------|------| +| **本分支 docs tranche（W2/W3 + 40 自检）** | **建议合并** — 无返工打回 30；`test_strategy: recommended` 已满足文档 + pytest 回归 | +| **task 全绿关账（含 W5）** | **不建议此刻关账** — §6.2 / G-W5-* 仍为 defer；待人执行 RUNBOOK 后 40 回填 + 二次 50 或关账签收 | + +--- + +## 5. R1 对照（摘要） + +22 R1：**零阻塞** · W5 不阻塞 30 文档 tranche。50 复检结论与 R1、40 自检 **一致**，未发现 40 虚报 pass。 + +--- + +## 6. Judgment（50 帽） + +| 字段 | 值 | +|------|-----| +| **experience_capture** | **维持** `recommended` — 验收以人工 RUNBOOK 为主，与 task 声明一致 | +| **gate/risk** | **须人审:** `HG-W5-SYNC`, `HG-W5-FIVE-Q`, `HG-REINSPECT` | +| **hat_self** | **pass-with-notes** — W5 整包 defer；文档 tranche 无 fail | +| **judgment_notes** | 未将 §6.2 defer 误判为 30 阻塞；未阅读 30 invoke 全文 | + +--- + +## 7. 修订记录 + +| 日期 | 摘要 | +|------|------| +| 2026-06-01 | v1：50 独立复检 · docs tranche 建议合并 · W5 defer | diff --git a/docs/tasks/skills/README.md b/docs/tasks/skills/README.md index 7cef27ea..f86a3e0d 100644 --- a/docs/tasks/skills/README.md +++ b/docs/tasks/skills/README.md @@ -32,6 +32,7 @@ | [`harness-task`](SKILL-harness-task.md) | **22 起 · 单 task** | active task + Harness 模板 | 帽链索引 · 落盘路径 · 关账 checklist · **非 Loop** · **v1 草案** | | [`harness-loop-batch`](SKILL-harness-loop-batch.md) | 10 Batch + Loop 执行 | 母单 + N 子 task、单 PR、`LOOP_MANIFEST` | Batch-10 一次；22→关账 × N；`HG-LOOP-BATCH`；cross-round 授权仅 `PROMPT_START` | | [`harness-meta-reinspect`](SKILL-harness-meta-reinspect.md) | 50 后 / 合并后 | 首轮 reinspect + git 历史 + invoke 链 | **零上下文**流程元复检：`human_gate` commit diff、同会话偏差、对拍首轮 50；落盘 `reinspect_*_meta_vN.md` | +| [`harness-looptask-handoff`](SKILL-harness-looptask-handoff.md) | **50 后 STOP** / CLOSE 前 | LoopTask `stop_after_hat:50` · task + R1/R2/50 路径 | **50 全文 Prompt** + 签收清单 + **人改 gate 表**（文件·位置·改什么）；跨仓 Portfolio 指针 | | [`pr-post-ci`](SKILL-pr-post-ci.md) | 开 PR / push 后 | PR 号、是否 docs-only | CI 监听、body/Test plan 同步、`automerge` 白名单；见 `SPEC-Governance-PR-Post-CI-v1` | **跨平台执行测评（实验轨）**：[`docs/harness/experiments/skill_cross_platform_v1/README.md`](../../harness/experiments/skill_cross_platform_v1/README.md) — 记录 SKILL 在 Claude Code 等平台的 scorecard，**非** SKILL 正文真值。 @@ -82,6 +83,7 @@ docs/tasks/skills/ SKILL-harness-task.md SKILL-harness-loop-batch.md SKILL-harness-meta-reinspect.md + SKILL-harness-looptask-handoff.md SKILL-pr-post-ci.md ``` @@ -99,3 +101,4 @@ docs/tasks/skills/ | 2026-05-26 | `harness-loop-batch` v1.1：人审泛化（R1…Rn、模式文件名、三选一流程） | | 2026-05-26 | `harness-loop-batch` v1.2：META 关账、合规自检、试点过程债、accepted 晋升 | | 2026-05-27 | 新增 `SKILL-docs-governance`、`SKILL-harness-task` 草案（T4+L2 Loop 蒸馏）；`reinspect_results/README` 命名；loop-batch v1.8 | +| 2026-06-01 | 新增 `SKILL-harness-looptask-handoff`（LoopTask 止于 50 交接） | diff --git a/docs/tasks/skills/SKILL-harness-looptask-handoff.md b/docs/tasks/skills/SKILL-harness-looptask-handoff.md new file mode 100644 index 00000000..917e7846 --- /dev/null +++ b/docs/tasks/skills/SKILL-harness-looptask-handoff.md @@ -0,0 +1,116 @@ +# SKILL：Harness LoopTask 止于 50 · 交接（50 Prompt + 签收 + 人改 gate 清单） + +> **SKILL ID**：`harness-looptask-handoff` +> **状态**：`active`（2026-06-01） +> **适用**：`harness_mode: looptask` 且 `stop_after_hat: 50`；50 落盘后或 CLOSE 前；维护者索要 **50 Prompt / 签收文档** +> **Cursor 入口**： [`.cursor/skills/harness-looptask-handoff/SKILL.md`](../../.cursor/skills/harness-looptask-handoff/SKILL.md) +> **配对前端**：`ai-ink-brain/.cursor/skills/harness-looptask-handoff/SKILL.md`（路径以 `content/` 为 task/harness 根） + +--- + +## 何时选用 + +| 适用 | 不适用 | +|------|--------| +| LoopTask 在 **50 + reinspect 落盘后 STOP**（不关账） | 单 task 无 `stop_after_hat: 50`（见 [`SKILL-harness-task.md`](SKILL-harness-task.md)） | +| 维护者要 **50 全文 Prompt**、**R1/R2/50 路径**、**HG-REINSPECT 改哪一行** | 工作区 `Projects/docs/harness/tasks/` 跨仓 task（Open `Projects/`，见工作区规则） | +| **CLOSE** 帽关账前交接 | Loop Batch 母单（见 [`SKILL-harness-loop-batch.md`](SKILL-harness-loop-batch.md)） | + +--- + +## Agent 必须交付的三件事 + +### 1. 50 Prompt（占位符须全部替换） + +| 项 | 本子仓路径 | +|----|------------| +| 规范（若已链出） | `docs/tasks/specs/PROMPT_50_invoke__v1_zh.md` 或 task 依赖列出的路径 | +| invoke 快照 | `docs/harness/invokes/by-task//invoke_YYYYMMDD_50_.md` | +| 帽真值 | [`docs/harness/prompts/hats/50-independent-reinspect.md`](../harness/prompts/hats/50-independent-reinspect.md) | + +对话中输出 **§4 Handoff + §5 子 Agent 正文** 合并的 **单一 `text` 围栏**（可 `Task` 粘贴）。**禁止**只写「见 PROMPT_50」而不贴全文（除非用户 **只要路径**）。 + +### 2. 签收文档路径清单（按帽序 · 相对本子仓根） + +| 帽 | 典型路径 | +|----|----------| +| 22 R1 | `docs/harness/reviews/by-task//task__audit_R1_YYYYMMDD.md` | +| 22 R2 | `docs/harness/reviews/by-task//task__audit_R2_YYYYMMDD.md` | +| 40 | `docs/tasks/active/task_.md` → **`### 自检结论（执行者）`** | +| 50 | `docs/tasks/reinspect_results/task__reinspect_YYYYMMDD.md` | +| invoke 链 | `docs/harness/invokes/by-task//invoke_*` | + +> **历史扁平路径**：若 reviews 在 `docs/harness/reviews/task_*_audit_*.md`（无 `by-task/`），以 **task 实现备忘 / invoke 元信息** 为准，仍须在清单中写出 **实际相对路径**。 + +未落盘 → 写 **「未落盘 · 阻塞」**，不得省略。 + +### 3. 人工改动：文件 + 位置 + 改什么（禁止笼统） + +**禁止**只说「需要人签 HG-REINSPECT」「请改 gate」。 + +**必须**用表： + +| 步骤 | 文件（相对本子仓根） | 位置 | 改什么 | +|------|----------------------|------|--------| +| … | … | … | … | + +**禁止 Agent**：`human_gate` 的 `pending` → `approved`；代填 **`### KPI（00）`**；`git mv` → `done/`（除非用户 **明示** 授权代关账）。 + +--- + +## CLOSE 关账（人 / 新会话 CLOSE 帽） + +1. **HG-REINSPECT** → 见下节「本子仓 task 示例」或当前 task 的 `human_gate` 表 +2. **KPI** → 同一 task **`### KPI（00）`** · [`docs/harness/guides/KPI_RUBRIC_v1_2.md`](../harness/guides/KPI_RUBRIC_v1_2.md) +3. **归档** → [`docs/tasks/README.md`](../tasks/README.md)：`git mv docs/tasks/active/… docs/tasks/done/`，更新 `docs/tasks/_views/done.md` +4. **回溯** → [`docs/harness/prompts/handoff/HANDOFF_CLOSE_TRACE.md`](../harness/prompts/handoff/HANDOFF_CLOSE_TRACE.md) + +--- + +## 本子仓 task 关账示例（字段位置模板） + +任意 `docs/tasks/active/task_*.md` 含 LoopTask 元信息时，人改 gate 通常如下： + +| 步骤 | 文件 | 位置 | 改什么 | +|------|------|------|--------| +| 1 | `docs/tasks/active/task_.md` | **`### 人工闸 human_gate`** · 行 **`HG-REINSPECT`** · 列 **`status`** | `pending` → **`approved`** | +| 2 | 同上 | **`### KPI（00）`** | 删占位；CLOSE 按 KPI_RUBRIC_v1_2 填写 | +| 3 | 同上 | 文首 **`> 状态`** 或元信息 **状态** | 关账后 **`done`**（与 `git mv` 同步） | +| 4 | Git | — | `git mv docs/tasks/active/task_.md docs/tasks/done/task_.md` | + +--- + +## 跨仓 · Portfolio Epic（前端 W5 / 后端 W6 协作） + +后端 Agent **只读** 前端落盘时，路径相对 **`ai-ink-brain/`**： + +| 文档 | 路径 | +|------|------| +| 前端 W5 task | `content/tasks/active/task_portfolio_content_sync_script_v1.md` | +| 50 Prompt 规范 | `content/tasks/specs/PROMPT_50_invoke_portfolio_content_sync_w5_v1_zh.md` | +| R1 / R2 / 50 | `content/harness/reviews/task_portfolio_content_sync_v1_audit_R*.md` · `content/tasks/reinspect_results/task_portfolio_content_sync_v1_reinspect_20260601.md` | +| 后端 ingest SPEC | `docs/spec/governance/SPEC-Governance-Portfolio-RAG-Demo-v1_zh.md` | + +**后端人改（ingest 烟测 · 非关账阻塞）**： + +| 步骤 | 文件 | 位置 | 改什么 | +|------|------|------|--------| +| 可选 | `.env`（**勿提交 Git**） | 键 **`CONTENT_ROOT`** | `<绝对路径>/ai-ink-brain/content` | +| 可选 | 本机 shell | — | `Authorization: Bearer $SYNC_ADMIN_SECRET` 经 BFF 或 `$ADMIN_TOKEN` 直连 Python（见前端 `tools/README-portfolio-content-sync.md`） | + +--- + +## 新 LoopTask 从模板复制时 + +1. 22 R2 链出 `PROMPT_50_invoke__v1_zh.md`（或 task specs 目录） +2. R2 审查 md **须**含「下一棒 50 Prompt」或指向 PROMPT 文件 +3. STOP 回复须含 `reinspect:` **完整相对路径** +4. 关账交接 **须**含「人改 gate」四列表（见上） + +--- + +## 修订记录 + +| 日期 | 摘要 | +|------|------| +| 2026-06-01 | v1：源于前端 Portfolio W5 LoopTask；后端双轨 + 跨仓 Portfolio 指针 | diff --git a/tests/test_unified_chat_backend_v2_agent.py b/tests/test_unified_chat_backend_v2_agent.py index 94323d89..f925c29a 100644 --- a/tests/test_unified_chat_backend_v2_agent.py +++ b/tests/test_unified_chat_backend_v2_agent.py @@ -1391,7 +1391,9 @@ async def _fake_decide_intent_v2( assert "agent.clarify" in types_wq assert calls["reg"] == 0 - tampered = (tok[:-1] + ("A" if tok[-1] != "A" else "B")) if tok else "not-a-token" + # 末位 A↔B 可能仅改 padding 位，解码后与原文相同（base64url 碰撞）；改中间字符必失败。 + mid = max(1, len(tok) // 2) + tampered = tok[:mid] + ("X" if tok[mid] != "X" else "Y") + tok[mid + 1 :] res_bad = client.post( "/api/py/unified/chat", headers={"Authorization": "Bearer api-key-123"},