diff --git a/docs/spec/README.md b/docs/spec/README.md index 0238280..e9cadea 100644 --- a/docs/spec/README.md +++ b/docs/spec/README.md @@ -1,7 +1,7 @@ # docs/spec（后端 SDD 规格目录） > **性质**：**行为/架构规格**（SDD）真值；与 `docs/tasks/`（执行单）、`docs/harness/`（过程工件）、`docs/_tech_graph/`（拓扑）分工。 -> **排期**：**最高优先** 理论对齐见 [`governance/SPEC-Governance-Harness-Theory-Align-P0-v1.md`](./governance/SPEC-Governance-Harness-Theory-Align-P0-v1.md)（P1 链式依赖）；**当前 Loop** 见 [`governance/SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md`](./governance/SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md)（RECENT **§0.6**）；Wiki 实验见 [`governance/SPEC-Governance-Wiki-Harness-Roadmap-v1.md`](./governance/SPEC-Governance-Wiki-Harness-Roadmap-v1.md)；任务级顺序见 [`../tasks/RECENT_TASK_SCHEDULE.md`](../tasks/RECENT_TASK_SCHEDULE.md) **§0.5**。 +> **排期**：理论对齐 [`SPEC-Governance-Harness-Theory-Align-P0-v1.md`](./governance/SPEC-Governance-Harness-Theory-Align-P0-v1.md)（done）；OpenSpec×TDD P0 [`SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md`](./governance/SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md)（**done · #94**）；Wiki 实验见 [`governance/SPEC-Governance-Wiki-Harness-Roadmap-v1.md`](./governance/SPEC-Governance-Wiki-Harness-Roadmap-v1.md)；任务级顺序见 [`../tasks/RECENT_TASK_SCHEDULE.md`](../tasks/RECENT_TASK_SCHEDULE.md) **§0.5–§0.6**。 --- diff --git a/docs/spec/governance/README.md b/docs/spec/governance/README.md index 0b8b303..d6a47c4 100644 --- a/docs/spec/governance/README.md +++ b/docs/spec/governance/README.md @@ -5,7 +5,7 @@ | 文件 | 状态 | 说明 | | --- | --- | --- | | [`SPEC-Governance-Harness-Theory-Align-P0-v1.md`](./SPEC-Governance-Harness-Theory-Align-P0-v1.md) | **`done` · P0 最高** | 培训理论 vs 落地 · 任务单/AGENTS/22/50（**压过业务队列**） | -| [`SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md`](./SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md) | **`active` · Loop 当前** | OpenSpec 写法 × TDD 纪律 · validate/22/40/status · RECENT **§0.6** | +| [`SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md`](./SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md) | **`done` · #94** | OpenSpec 写法 × TDD 纪律 · validate/22/40/status · RECENT **§0.6** | | [`SPEC-Governance-Harness-Theory-Align-P1-v1.md`](./SPEC-Governance-Harness-Theory-Align-P1-v1.md) | `active`（依赖 P0） | Fresh Context、半自动推广、首条领域 Linter | | [`SPEC-Governance-Wiki-Harness-Roadmap-v1.md`](./SPEC-Governance-Wiki-Harness-Roadmap-v1.md) | `active` | **整体安排表**（T0～T4、Wiki-CTX-AB P1/P2） | | [`SPEC-Governance-Wiki-TechGraph-Bridge-v1.md`](./SPEC-Governance-Wiki-TechGraph-Bridge-v1.md) | `active` | **T4** Wiki `graph_nodes` ↔ L0 / `graph_query` 桥接 · `GOV-T4-SPEC-ACTIVE@2026-05-27` | diff --git a/docs/spec/governance/SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md b/docs/spec/governance/SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md index e47a060..c631af0 100644 --- a/docs/spec/governance/SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md +++ b/docs/spec/governance/SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md @@ -2,12 +2,12 @@ | 项 | 内容 | | --- | --- | -| **状态** | `active`（Loop R1–R3 执行中 · Step 0 模板 done） | +| **状态** | `done`（Loop 关账 · PR #94 · 2026-05-30） | | **freeze_id** | `GOV-HARNESS-OPENSPEC-TDD-P0@2026-05-30` | | **排期** | [`docs/tasks/RECENT_TASK_SCHEDULE.md`](../../tasks/RECENT_TASK_SCHEDULE.md) **§0.6** | -| **Loop 母单** | [`docs/tasks/active/task_harness_p0_openspec_tdd_loop_v1.md`](../../tasks/active/task_harness_p0_openspec_tdd_loop_v1.md) | +| **Loop 母单** | [`docs/tasks/done/task_harness_p0_openspec_tdd_loop_v1.md`](../../tasks/done/task_harness_p0_openspec_tdd_loop_v1.md) | | **Manifest** | [`docs/harness/invokes/by-task/p0-openspec-tdd/LOOP_MANIFEST.md`](../../harness/invokes/by-task/p0-openspec-tdd/LOOP_MANIFEST.md) | -| **分支** | `task/harness-p0-openspec-tdd`（单 PR） | +| **REPORT** | [`REPORT_completion_20260530_v1.md`](../../harness/invokes/by-task/p0-openspec-tdd/REPORT_completion_20260530_v1.md) | > **背景**：OpenSpec / Harness 对比分析与 TDD 架构评估；**不**引入 `openspec/` 目录、不全员 strict TDD。 > **原则**：OpenSpec **写法 P0** 与 TDD **纪律 P0** **合并 Sprint A**（同一 `task_validate` + 22/40 补丁），不拆两波 PR。 @@ -16,7 +16,7 @@ ## 1. O1～O3 是否完成态？ -**结论：模板级 ✅ 完成；全仓 adoption ❌ 未做。** +**结论：模板级 ✅ 完成；工具与帽链 ✅ 完成（R1–R3 · #94）；全仓存量 adoption 仍可选（Sprint C）。** | ID | 内容 | 完成度 | 说明 | |----|------|--------|------| @@ -25,14 +25,15 @@ | **O3** | 大 task §规划 artifact（proposal/design/tasks 等价） | **✅ 模板完成** | 同文件 L129–147 | | — | README / HARNESS_V2 指针 | **✅ 文档完成** | [`docs/tasks/README.md`](../../tasks/README.md)、[`docs/harness/HARNESS_V2_PLAN.md`](../../harness/HARNESS_V2_PLAN.md) §5.1 | -**尚未完成（不算 O1–O3 闭环）**： +**Loop 已交付（#94）**： -- [ ] 存量 `docs/tasks/active/*.md` **未回填** Delta/Scenario -- [ ] 22 帽 **未**增格式勾选项 -- [ ] **无** `task_validate` 机械校验 -- [ ] 关账合并 Delta → `docs/spec/` 的 checklist **未**写进 50/关账流 +- [x] `tools/harness_task_validate.py` + pytest +- [x] 22/40 帽格式勾选项与三维自检 +- [x] 关账合并 Delta → SPEC 的 checklist **仍可选**（OpenSpec P2 · O7） -**因此**：对新 task Copy 模板即完成 Step 0；全仓 **Step 1–3** 由 Loop **R1–R3** 交付。 +**仍可选（Sprint C）**： + +- [ ] 存量 `docs/tasks/active/*.md` **未全量回填** Delta/Scenario --- @@ -45,18 +46,18 @@ | O1 | Delta Spec 小节 | ✅ 模板 | — | | O2 | Scenario ID | ✅ 模板 | — | | O3 | 规划 artifact 分节 | ✅ 模板 | — | -| O4 | `tools/harness_task_validate.py` | ⬜ 待做 | **R1** | -| O5 | `tools/harness_change_status.py`（`--json`） | ⬜ 待做 | **R3** | -| O6 | `.cursor/commands/harness-*.md` | ⬜ 待做 | **R3** | +| O4 | `tools/harness_task_validate.py` | ✅ done | **R1** | +| O5 | `tools/harness_change_status.py`（`--json`） | ✅ done | **R3** | +| O6 | `.cursor/commands/harness-*.md` | ✅ done | **R3** | ### 2.2 TDD 纪律 P0 | ID | 项 | 状态 | Loop | |----|-----|------|------| -| T1 | 22 帽：`api/` 禁滥用 `not_applicable` | ⬜ 待做 | **R2** | -| T2 | 22 帽：Scenario / test_strategy 勾选项 | ⬜ 待做 | **R2** | -| T3 | 40 帽：Completeness/Correctness/Coherence 三维提示 | ⬜ 待做 | **R2** | -| T4 | `task_validate` 内嵌 test_strategy 规则 | ⬜ 待做 | **R1**（与 O4 合并） | +| T1 | 22 帽：`api/` 禁滥用 `not_applicable` | ✅ done | **R2** | +| T2 | 22 帽：Scenario / test_strategy 勾选项 | ✅ done | **R2** | +| T3 | 40 帽：Completeness/Correctness/Coherence 三维提示 | ✅ done | **R2** | +| T4 | `task_validate` 内嵌 test_strategy 规则 | ✅ done | **R1**（与 O4 合并） | | T5 | 存量 active task 抽样回填 | ⬜ 可选 | Sprint C | ### 2.3 重叠说明 @@ -197,3 +198,4 @@ python tools/harness_task_validate.py --json docs/tasks/active/task_foo.md |------|------| | 2026-05-30 | 初版：O1–O3 完成态；Sprint A/B/C；O4 与 TDD P0 合并 | | 2026-05-30 | 自 `docs/diary/tmp/` 迁入 `docs/spec/governance/`；对齐 Loop R1–R3 与 RECENT §0.6 | +| 2026-05-30 | Loop 关账 · PR #94 · 状态表 O4–T4 标 done；Sprint C 标可选 | diff --git a/docs/tasks/RECENT_TASK_SCHEDULE.md b/docs/tasks/RECENT_TASK_SCHEDULE.md index 8fc18e0..9109a91 100644 --- a/docs/tasks/RECENT_TASK_SCHEDULE.md +++ b/docs/tasks/RECENT_TASK_SCHEDULE.md @@ -12,10 +12,10 @@ > **改进工程状态**：P0 + P1 **done**（PR #45/#46/#49）；[`HARNESS_V2_PLAN.md`](../harness/HARNESS_V2_PLAN.md) 已 **`accepted`**。下文 §0.1～0.4 为**历史阶段记录**，不再表示「仍在试点/测试阶段」。 > **Git**：本地 **勿在 `main` 上改/提交**；远程合入须 **PR**。 -> **近期当前（单 Loop · 2026-05-29 整合 · META done）**： -> - **ChatBI P2 Loop**：**done** · 母单 [`task_chatbi_v3_p2_resilience_loop_v1.md`](done/task_chatbi_v3_p2_resilience_loop_v1.md) · R1+R2 已关账 · REPORT [`REPORT_completion_chatbi_v3_p2_loop_v1.md`](../harness/invokes/by-task/chatbi-v3-p2-loop/REPORT_completion_chatbi_v3_p2_loop_v1.md) -> - 下一业务棒：见 §1.1 active（低置信 §5.1 / P3 chain events 等） -> Wiki 排期 hub **done**（#85）；T4 ops **done**（#83）；Batch-4 ingest 另单。 +> **近期当前（2026-05-30）**： +> - **P0 OpenSpec×TDD Loop**：**done** · PR [#94](https://github.com/Cyning12/ai-ink-brain-api-python/pull/94) · REPORT [`REPORT_completion_20260530_v1.md`](../harness/invokes/by-task/p0-openspec-tdd/REPORT_completion_20260530_v1.md) +> - **ChatBI P2 Loop**：**done** · 见 §5 P2-1 全完成 +> - 下一业务棒：见 §1.1 active（低置信 §5.1 / P3 chain events 等） ### 0.0 关账常模（改进后默认 · 非「测试阶段」） @@ -41,22 +41,21 @@ **P0 要点（执行顺序）**：22 清单增补 → AGENTS ≤120 行 → active task Harness 字段回填 → 样例 22 审查。 -### 0.6 P0 OpenSpec 写法 × TDD 纪律 Loop（**当前** · 2026-05-30） +### 0.6 P0 OpenSpec 写法 × TDD 纪律 Loop（**done** · 2026-05-30） -> **分支**：`task/harness-p0-openspec-tdd` · **单 PR** +> **PR**：[#94](https://github.com/Cyning12/ai-ink-brain-api-python/pull/94) · merge `d55f15d` > **SPEC**：[`SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md`](../spec/governance/SPEC-Governance-Harness-OpenSpec-TDD-P0-v1.md) -> **Step 0 done**：`TASK_TEMPLATE` Delta/Scenario/规划 artifact（首 commit） -> **Manifest**：[`docs/harness/invokes/by-task/p0-openspec-tdd/LOOP_MANIFEST.md`](../harness/invokes/by-task/p0-openspec-tdd/LOOP_MANIFEST.md) -> **母单**：[`task_harness_p0_openspec_tdd_loop_v1.md`](active/task_harness_p0_openspec_tdd_loop_v1.md) · **闸**：`HG-LOOP-BATCH` **approved** +> **REPORT**：[`REPORT_completion_20260530_v1.md`](../harness/invokes/by-task/p0-openspec-tdd/REPORT_completion_20260530_v1.md) +> **母单**：[`task_harness_p0_openspec_tdd_loop_v1.md`](done/task_harness_p0_openspec_tdd_loop_v1.md) -| round | task | 交付 | +| round | task | 状态 | | ----- | ---- | ---- | -| R1 | `task_harness_p0_task_validate_v1.md` | `tools/harness_task_validate.py` + pytest | -| R2 | `task_harness_p0_audit_selfcheck_v1.md` | 22/40 帽补丁 | -| R3 | `task_harness_p0_status_cursor_v1.md` | `change_status --json` + Cursor commands | -| META | 母单关账 + `REPORT_completion_*` | 三轮均 `done/` 后 | +| R1 | `task_harness_p0_task_validate_v1.md` | **done** · `harness_task_validate` + pytest | +| R2 | `task_harness_p0_audit_selfcheck_v1.md` | **done** · 22/40 帽补丁 | +| R3 | `task_harness_p0_status_cursor_v1.md` | **done** · `change_status --json` + Cursor commands | +| META | 母单 | **done** | -**卷三公众稿**：可按 P0/P1 SPEC **应然** 起草；需仓库实测的句子标 `【待后端 P0/P1 验收后核对】`（见 narrative vol3 **§0.4**）。 +**卷三公众稿**：P0 工具已落地；实测句可对照 validate/status 命令核对（见 narrative vol3 **§0.4**）。 ### 0.1 阶段 0 — Git / 分支 @@ -111,20 +110,20 @@ --- -## 1. 现状快照（2026-05-29 更新） +## 1. 现状快照（2026-05-30 更新） | 维度 | 结论 | | --------------------- | ---------------------------------------------------------------------------------------------- | | **本表角色** | **最近任务安排真值** | | **排期 Wiki hub** | [`concepts/task-schedule-ink-backend.md`](../coding_wiki/concepts/task-schedule-ink-backend.md) · **不**替代本表 | -| **active/** | **10** 个任务相关文件（含 P0 Loop 母+3 子 + 1 附属 AGENT_PROMPT） | -| **done/** | **61+** 个 `.md`（含 P2 Loop R1/R2/META） | -| **_views/done.md** | 随关账同步 | +| **active/** | **6** 个 task + 1 附属 AGENT_PROMPT | +| **done/** | **65+** 个 `.md`（含 P0 OpenSpec×TDD Loop 母+3 子） | +| **_views/done.md** | 随关账同步（含 P0 Loop 四单 · 2026-05-30） | | **Harness 改进** | **done**（P0+P1 收口） | | **Harness 关账** | **常模**：`required` 实现 task → **50 必落盘**（见 §0.0） | | **Wiki 治理** | **阶段收口**（#83 · diary 验收 · #87 文稿 · W1 **done** Loop R1） | -| **近期当前** | P2 Loop **done** · 见 §5 P2-1 全完成 | +| **近期当前** | P0 OpenSpec×TDD Loop **done**（#94）· P2 Loop **done** · 见 §1.1 业务 active | | **V3 P2-1 韧性** | P2-1a/b/c **done** · Loop **done** | @@ -133,7 +132,6 @@ | # | 任务文件 | 状态 | 主题 | 排期 | | ----- | -------- | ---- | ---- | ---- | -| **0** | `task_harness_p0_openspec_tdd_loop_v1.md` + R1–R3 子单 | `in_progress` / `pending` | **P0 OpenSpec×TDD Loop** | **§0.6 当前** | | 1 | `task_ui_chain_events_backend.md` | `pending` | Chain Events 统一事件 | P3 | | 2 | `task_rag_graphrag_pilot_explore_v1.md` | （见 task 头） | GraphRAG 探索 | 按需 | | 3 | `task_chatbi_v3_planning_after_resume_v1.md` | `planning` | V3 统筹索引 | P4 | diff --git a/docs/tasks/active/task_chatbi_v3_low_confidence_plan_preview_confirm_v1.md b/docs/tasks/active/task_chatbi_v3_low_confidence_plan_preview_confirm_v1.md index 0670731..ba1211d 100644 --- a/docs/tasks/active/task_chatbi_v3_low_confidence_plan_preview_confirm_v1.md +++ b/docs/tasks/active/task_chatbi_v3_low_confidence_plan_preview_confirm_v1.md @@ -32,11 +32,21 @@ ## 失败路径 -| # | 触发条件 | 系统行为 | 可重试 | 用户可见 | -|---|----------|----------|--------|----------| -| F1 | 低置信未确认即执行 | 澄清 / 预览 SSE，不升格 | 是 | 需用户确认 | -| F2 | 确认令牌无效 | `403` + 结构化错误 | 否 | 确认失效 | -| F3 | 预览生成失败 | `error` chain 事件 | 是 | 方案生成失败 | +| # | Scenario ID | 触发条件 | 系统行为 | 可重试 | 用户可见 | +|---|-------------|----------|----------|--------|----------| +| F1 | `fp-lowconf-unconfirmed-exec` | 低置信未确认即执行 | 澄清 / 预览 SSE，不升格 | 是 | 需用户确认 | +| F2 | `fp-lowconf-token-invalid` | 确认令牌无效 | `403` + 结构化错误 | 否 | 确认失效 | +| F3 | `fp-lowconf-preview-fail` | 预览生成失败 | `error` chain 事件 | 是 | 方案生成失败 | + +--- + +## 验收标准 + +> 分项明细见 **§5**；本节供 Harness validate 与关账核对。 + +- [ ] **§5.0** 方案 B 首包已验收（2026-05-13）；**§5.1** 母单大项仍 backlog，后续 PR 逐项关闭 +- [ ] 合并前 **`pytest tests -m "not intent_eval and not intent_benchmark"`** 全绿；触达契约时 **`python tools/tech_graph_contract_check.py`** 通过 +- [ ] 母单剩余 implementation 关账前 **50** 复检落盘（`reinspect_results/`） --- diff --git a/docs/tasks/active/task_ui_chain_events_backend.md b/docs/tasks/active/task_ui_chain_events_backend.md index a72169d..bd91e1c 100644 --- a/docs/tasks/active/task_ui_chain_events_backend.md +++ b/docs/tasks/active/task_ui_chain_events_backend.md @@ -55,13 +55,32 @@ --- +## 行为变更（Delta） + +### ADDED + +- **Requirement**：Chain Chat 最小事件流 API，响应含 `events[]` 时间线。 + - **Scenario**：`chain-events-happy` — GIVEN 合法请求 WHEN `POST /api/py/chain/chat` THEN `ok: true` 且 `events[]` 含 `assistant.message` / 工具与 `sql.result` 等约定 type。 +- **Requirement**：错误路径仍返回结构化 `events[]`。 + - **Scenario**：`chain-events-error` — GIVEN 内部失败 WHEN 请求处理 THEN `events[]` 含 `error` 事件且 `ok: false`（或等价字段）。 + +### MODIFIED + +无（Previously: 无统一 chain 事件 JSON 面） + +### REMOVED + +无 + +--- + ## 失败路径 -| # | 触发条件 | 系统行为 | 可重试 | 用户可见 | -|---|----------|----------|--------|----------| -| F1 | 参数非法 | `422` + 结构化 `detail` | 否 | 字段级错误 | -| F2 | Text2SQL / 工具内部错误 | `events[]` 含 `error` 事件，`ok: false` | 视错误 | 时间线错误节点 | -| F3 | 数据库不可用 | `500 DATABASE_DISCONNECT` 或等价 | 是 | 服务暂不可用 | +| # | Scenario ID | 触发条件 | 系统行为 | 可重试 | 用户可见 | +|---|-------------|----------|----------|--------|----------| +| F1 | `fp-chain-events-422` | 参数非法 | `422` + 结构化 `detail` | 否 | 字段级错误 | +| F2 | `fp-chain-events-tool-error` | Text2SQL / 工具内部错误 | `events[]` 含 `error` 事件，`ok: false` | 视错误 | 时间线错误节点 | +| F3 | `fp-chain-events-db-down` | 数据库不可用 | `500 DATABASE_DISCONNECT` 或等价 | 是 | 服务暂不可用 | ---