qiaoqichaoandClaude Code
8e2473cf3e
交接文档自身的提交会成为新的 HEAD，写死必然过期（本行刚被自己的提交证伪过）。 改为列本轮三个实质提交 + 以 git log 为准。 Co-Authored-By: Claude Code <noreply@anthropic.com>
184 lines
19 KiB
Markdown
184 lines
19 KiB
Markdown
# 开发交接与任务包：Claude Code / DeepSeek 等编码代理
|
||
|
||
版本：0.2 · 2026-09-29。用途：用小范围输入和明确验收降低重复阅读与返工成本。不是一次性让模型实现整个平台的提示词。规则统一由 [AGENTS.md](../../AGENTS.md) 管理，[CLAUDE.md](../../CLAUDE.md) 只做导入入口。
|
||
|
||
## 1. 接手时必须知道的事实
|
||
|
||
| 项 | 本次核验状态 |
|
||
|---|---|
|
||
| 当前仓库 | F:/mini-OpenClaw-local-stable；Next.js + FastAPI，非 Electron |
|
||
| 当前分支 / 文档更新前 HEAD | codex/xingbang-v2-docs-20260928 / 47ec30a562f12864b7485bb7a43b967fa8f5b755；后续以 git 为准 |
|
||
| 独立 v2 源码 | 尚未抽取；仓库内 v2/ 与候选 F:/mini-OpenClaw-v2 均未建立 |
|
||
| 已有演示 | docs/v2/prototypes/prescreen-workbench.html；静态交互，不是生产业务实现 |
|
||
| 真实数据 / 模型 | 无兴邦真实数据；Jev/Laya 接入未实现，未证明业务效果 |
|
||
| 概率 | 原型人工情景值；真实 probability=null |
|
||
| 恢复点 | 4d5a420 原版快照曾核验 Gitea SHA；不代表最新文档/原型已远程备份 |
|
||
| 暂不触碰 | .docker-codex、project-process.zip、Office 临时文件、现有运行数据、用户删除的旧页面 |
|
||
|
||
新会话先 git status --short，再 git log --oneline -6；阅读对应任务调用方。本文不是实时进度数据库；每次结束更新第 7 节，事实冲突以实际工作区和证据为准。
|
||
|
||
## 2. 三种模型配置必须分开
|
||
|
||
1. 编码代理：用户可以使用 Claude Code 连接 DeepSeek，负责写代码与测试。
|
||
2. 产品主审模型：miniOpenClaw 在运行时规划核查、调用批准工具、解释结果，独立配置。
|
||
3. 专项判断模型：Jev / 本地 Laya / 其他已验证本地模型 / disabled，见 [专项设计](11-judgment-providers.md)。
|
||
|
||
开发选 DeepSeek 不构成修改产品模型、数据出口或判定阈值的指令。专项模块不能把模型置信度写为项目审批概率。
|
||
|
||
Claude 官方说明支持从 CLAUDE.md 用 @AGENTS.md 导入统一规则，本仓已采用该入口。用户本机 Claude/DeepSeek 连通性、版本兼容和费用未测试；本轮不安装 CLI、不修改用户全局配置、不写 API Key。接入时依据 [Claude 项目指令文档](https://code.claude.com/docs/en/memory) 和 [DeepSeek 官方 Claude Code 指南](https://api-docs.deepseek.com/quick_start/agent_integrations/claude_code/) 核对当前参数。前者正文已查阅，后者官方搜索结果可发现但本次正文抓取超时；不据此写死模型名称和配置命令。
|
||
|
||
## 3. 最小阅读包
|
||
|
||
首次：AGENTS→project-process/README 与 XINGBANG-ADAPTATION→v2/README→本任务相关规格行和设计章节→对应阶段规范。之后不反复全文读取所有文档，但切换阶段必须读对应章节。
|
||
|
||
| 任务领域 | 必读 v2 文档 | 首先定位的已有代码（只作复用线索） |
|
||
|---|---|---|
|
||
| 材料/历史 | 01、03、14 第3/4/8节 | assistant_data.py、assistant_materials.py、assistant_store.py |
|
||
| 卡片/装配 | 01、03、14 第4/5节 | assistant_experiences.py、component_registry.py、component_evaluation.py |
|
||
| 编排/专项 | 02、03、11、14 第2/7节 | assistant_model.py、assistant_worker.py、project_assistant.py 的调用方 |
|
||
| UI/沙盘 | 04、DESIGN、13、14 第5/6节 | 当前 workbench 页面和已有原型；先确认路由仍存在 |
|
||
| 复盘/评测 | 06、14 第7/8节 | 既有运行存储、审计与经验治理，不改写历史记录 |
|
||
|
||
表中代码位于 backend/services；拟议新模块落点在完成 T00 的路径清单后才成为可写白名单。不要因为文档有一个新模块名字就新建完整框架。
|
||
|
||
## 4. 小步任务队列
|
||
|
||
状态说明：ready-docs=可立即完成文档/现状核对；blocked-gate=须补齐并评审对应设计才能写业务代码；planned=依赖前项；optional=没有也能交付主闭环。下列均未被标记实现完成。
|
||
|
||
每张任务卡必须记录 parent_task、目标 BR/E/AC、准确文件白名单、输入/输出契约、状态机、测试命令和证据路径。表中是边界，不是授权一次修改整个目录。
|
||
|
||
| ID / 状态 | 依赖 / 阅读 | 单次产物与边界 | 验收 / 下一步 |
|
||
|---|---|---|---|
|
||
| T00 ready-docs：设计收口与路径清单 | 当前文档；流程①–④ | 核对现有调用方；输出核心依赖白名单、独立路径/资源候选；完成首个切片六道门与接口/DDL/状态设计，记录审阅者及未决项 | 文档链接/编号/事实/diff；禁止顺带复制源码或启动服务；形成 T01 的准确文件清单 |
|
||
| T01 blocked-gate：独立基座 | T00；M1 | 从核验修订按白名单抽取可运行核心，排除密钥/库/依赖/旧凭据文档；独立 venv、端口和数据根 | 原版文件不变、独立健康检查、统一 verify 通过；不部署云端 |
|
||
| T02 planned：闭环契约与存储 | T01；03第9节 | 定案 Pydantic 模型、追加迁移、授权与版本引用；同步前端契约消费。按材料/卡片/运行子卡分次实现 | AC-13/14/23/28/34/36/43；迁移幂等、版本冲突、重启恢复；不接模型 |
|
||
| T03 planned：材料集合 | T02；14第3节 | 复用上传/确认入口，增加导入清单、定位和冲突候选；只处理 PDF/XLSX/CSV | AC-01/08/23/24；部分失败、重复/跨项目、未确认不生效 |
|
||
| T04 planned：模拟案例 | T02；14第8节 | 先边界 fixture，再可复现批量生成、分组划分和 manifest；运行输出不默认入 Git | AC-35/36；数量/时间/标签一致性、无保留集泄漏；不声称真实效果 |
|
||
| T05 planned：历史提炼与人工卡片 | T03/T04；14第4节 | 先 timeline，再候选，再编辑/测试/审核；每部分独立子卡，复用治理入口 | AC-02/03/04/25/26/27/43；自然语言修改不直接发布、不自批、硬规则有正式依据 |
|
||
| T06 planned：评审方案与维度 | T05；14第5节 | 数据/Skill/Rule 装配、依赖检查、冻结方案；维度去重和刻度冲突；没有 Tools 卡 | AC-28/29/44；草稿/撤回组件拒绝、旧版本不变；空/2/6/9维和异刻度 |
|
||
| T07 planned：预审执行 | T06；02/03 | 受限编排、确定性核查、缺证补件、结果约束；先 disabled 专项路径 | AC-05–10/12–14/21/45；工具越权拒绝、预算停止、硬阻断、失败不伪造；不实现真实概率 |
|
||
| T08 planned：专项离线质检 | T05；11第8节 | 先统一适配 fixture，再独立本地服务；验证 Laya 中文题库的提炼依据和轨迹质检，失败可保持禁用 | AC-17–21/38/39/40；fixture/live 分开、否定和例外、上下文超限、逐任务注册；不得把安装成功当能力通过 |
|
||
| T09 planned：预审与沙盘 UI | T07；04/DESIGN/13 | 分子卡实现组件、动态维度、证据抽屉、条件情景；演示值与真实字段分离 | AC-11/12/29/30/31/42/44；组合非加和、乱序丢弃、失败保基线、键盘与文字替代 |
|
||
| T10 planned：轨迹和结果复盘 | T07；03/14第7节 | 先只读 step 回放，再模拟会议结果追加/对齐，最后偏差记录；不改旧运行 | AC-22/32/33；一个 run 多 step、unmatched、结果更正、只读权限；人工缺失过程不补造 |
|
||
| T11 planned：改进对照与演示交付 | T08/T09/T10；06/08 | 固定版本做旧/新对照，ImprovementCandidate审核和发布；完成三模块演示脚本 | AC-15/16/34–37/41；泄漏拒绝、退化不发布；工程演示与模型效果分列 |
|
||
| T12 optional：Jev 与实时专项 | T08；有端点/凭据及授权 | Jev adapter 与独立 live 验证；通过逐任务效果门禁后再启用实时用途 | AC-17–20/38–40；无 Key 标未验证，不阻塞主闭环 |
|
||
| T13 future：真实数据与概率 | M5/M6；客户授权与 OQ | 接真实只读数据、映射会议标签、分组时间划分、训练/校准/盲测、适用范围与漂移门禁 | 高预测组通过率+覆盖率+校准+样本不确定性；新建概率详细规格，禁止照演示表实现 |
|
||
|
||
T08 可在 T05 后先做提炼质检；轨迹质检待 T10 提供轨迹。T09 不依赖 Jev，T11 可展示专项禁用或效果未达标的真实状态，不伪造模型成功。工作并行需要用户明确安排不同文件归属；默认同一工作区串行执行。
|
||
|
||
## 5. 通用执行提示词（替换任务编号即可）
|
||
|
||
```text
|
||
你在 F:\mini-OpenClaw-local-stable 工作。先读取 CLAUDE.md/AGENTS.md、
|
||
docs/project-process/README.md、XINGBANG-ADAPTATION.md，执行 git status --short
|
||
和 git log --oneline -6，再读取 docs/v2/15-development-handoff.md。
|
||
|
||
本轮只做 T00。按任务卡读取相关文档和当前调用方，不读取无关整个仓库。
|
||
先报告当前状态、该任务范围和验收项，然后完成已授权且不受门禁阻塞的工作。
|
||
用户已确认产品方向，无须重问；工程未决项先查代码/文档，无法解决才集中提出。
|
||
本任务若是文档收口，不写业务代码、不安装模型、不启动或部署服务。
|
||
若是后续实现任务，先验证该切片①–④门禁证据，列准确文件白名单，补对应测试，
|
||
用最小改动实现；行为变更必须用项目 backend/venv 运行 scripts/verify.py。
|
||
不得恢复已合并删除的旧页、复制真实数据库/密钥、用演示值充当真实概率，
|
||
不得把模型置信度当通过率或把反馈自动发布成正式规则。
|
||
每批完成自查 diff；记录日志与测试证据，更新第7节交接，不自动开始下一任务。
|
||
输出：本次改动、验证结果、未完成项、下一任务和所需输入。
|
||
```
|
||
|
||
已有用户授权的文档或可逆修复不额外请求确认；门禁缺口按明确的规格条目记录，不能靠再问一句“可以开始吗”代替完成设计。
|
||
|
||
## 6. 控制开发成本的方式
|
||
|
||
- 一个会话一张小任务卡；大表中的 T02/T05/T09 等必须先拆成单一可验证子卡。优先服务+契约+最薄界面构成一条业务切片。
|
||
- 每轮提交相同短交接格式，下一轮只读该卡及必要依赖；调用方用 rg 精确检索，避免上传整个仓库或反复读长日志。
|
||
- 先固定 fixture 和结构验证，真实模型调用集中在小型专项评测；没有新改动/失败不重复跑相同昂贵测试。每个行为批次仍须完整 verify，节省成本不能省略强制验证。
|
||
- 复杂度高的共享契约、数据隔离、概率口径和迁移先完成技术审阅；普通实现使用用户选定模型。模型不能仅凭自评宣称测试通过。
|
||
- 失败先看准确日志并定位，修复后重跑同一检查；若同一问题两次无进展，停止扩大改动，形成最小复现与待解决问题，交给用户或审阅者。
|
||
- 不预承诺节省比例；如需比较，记录每卡实际 token/费用（可得时）、耗时、返工和测试结果。
|
||
|
||
## 7. 当前交接记录
|
||
|
||
> **交付判定修正（2026-09-30）**：T05–T11 一律按**部分完成**记。审计
|
||
> （`test-evidence/20260930-v2-audit/audit.json`）确认：底层能力存在，但产品闭环未接通——
|
||
> 正常发起评审不产生新版预审记录、历史经验加工不在实时 API 调用图上、
|
||
> 轨迹/复盘/改进端点无前端消费、改进发布未接真实知识发布入口。
|
||
> 交付定义与四批顺序以 [16 交付纠偏规格](16-delivery-corrections.md) 为准；
|
||
> 下表的"已交付"只表示该任务包的代码与测试存在，不再表示产品功能可用。
|
||
|
||
- 日期：2026-10-01（**纠偏第四批实施轮**；第三批见 `ae89462`/`3e15bda`，
|
||
第二批见 `2e7e194`/`01c88af`，第一批见更早提交）。
|
||
- 仓库：`F:/mini-OpenClaw-v2`；远程 `http://192.168.10.111:3000/qiaoqichao/mini-openclaw-v2.git`
|
||
（OQ-06 Q2 的远程归属已定案；端口/资源/CI 三问仍 open；**本轮未推送**）。
|
||
- 完成范围：**纠偏第四批「接通评审反馈与改进发布」**——会议结果从页面录入并与材料版本对照；
|
||
改进候选接上**真实知识发布入口**，发布后新运行用新版本、旧运行仍可回放。
|
||
界面并入「轨迹复盘」模块（`/trajectory-center`），**不新增第四个导航入口**。
|
||
本轮另**首次做了真实浏览器端到端验证**（新增可选脚本 `scripts/browser-e2e.cjs`），
|
||
并因此发现并修掉 5 个源码守卫与生产构建都看不出的缺陷——其中一个是**三个模块页
|
||
在浏览器里根本渲染不出面板**（`/projects` 读错字段），见 17「浏览器验证发现的问题」。
|
||
`scripts/verify.py` **14 项检查**全通过（新增 `improvement-panel-ui` 源码守卫）。
|
||
- 验证入口：`cd F:/mini-OpenClaw-v2 && backend/venv/Scripts/python.exe scripts/verify.py`；
|
||
本轮证据：`test-evidence/20261001-030127-ff59d7e/`（14/14 PASS，backend-unit 572 项）。
|
||
浏览器验证证据：`node scripts/browser-e2e.cjs` → `test-evidence/e2e-batch4/`（19/19 PASS + 截图）。
|
||
**该脚本刻意不接入 verify.py**（verify 不应依赖浏览器），需手动跑。
|
||
- 测试规模：全量 **572 项** unittest 无回归（新增 `test_improvement_release.py` 4 项 +
|
||
`test_improvements.py` 1 项）。
|
||
- 卡片验收对照（详见 [17 四批交付记录](17-batch-delivery-records.md) 第四批）：
|
||
- **AC-57**：端点把 `_knowledge_publisher` 注入 `improvements.transition`；publisher 用候选声明的
|
||
`proposed_revision_ref` **精确**定位草稿（`组件id@版本`），调 `knowledge_cards.publish`
|
||
→ `component_registry.release`，写入不可变 `component_version` 并**覆盖 `release` 指针**。
|
||
端到端证明：同一方案发布前运行冻结 `卡片@1.0.0`，发布后**再跑一次**得到 `卡片@1.0.1`，
|
||
旧运行回放仍是 `1.0.0`。**不接受客户端自报版本号**（422）；非知识类目标 409 诚实拒绝。
|
||
- **AC-56**：`TrajectoryPanel` 可追加会议结果（原始结果码、会议编号、材料版本快照、
|
||
更正走 `supersedes_id`）；`matched` / `unmatched` 分组，未匹配单列且不计入分母。
|
||
- 未决项（阻塞后续）：
|
||
- **F17** 真实模型提炼未实测：本机未设置 `XINGBANG_LOCAL_MODEL_*`，
|
||
AC-50 前半句目前只有"不可用路径 + 假传输成功路径"两类证据。
|
||
需端点后按 17 的操作步骤补一次真实调用；在此之前不得宣称"真实提炼已跑通"。
|
||
- **F18** 例外边界未进入可求值条件语言；**F19** 卡片适用条件不参与运行内逐项判定。
|
||
（同第二批，本批未动。）
|
||
- **F11 部分关闭**：`/trajectory-center`（含本批的会议结果录入与改进面板）已在**真实 Chrome**
|
||
里端到端走过并通过（`scripts/browser-e2e.cjs`，19/19，有截图）。**仍开放的部分**：
|
||
① `/experience-center`、`/prescreen-workbench` 只验到"能渲染"，交互没有逐项点过；
|
||
② 该脚本不在 `verify.py` 里，需手动跑（本机 Chrome + 一次性 `--no-save puppeteer-core`）；
|
||
③ 无视觉基线比对、无多分辨率、无键盘/读屏检查。
|
||
深色底对比度仍是守卫内按 WCAG 实算，不是实测。
|
||
- **F27（新）浏览器验证暴露的缺陷已修但防线不全**：本批靠浏览器发现并修了 5 个缺陷
|
||
（见 17「浏览器验证发现的问题」）。其中只有"导航名折行"补进了源码守卫；
|
||
其余 4 个（读错 `/projects` 字段、漏传 `identity`、重复 React key、JSX 里的字面量 `**`）
|
||
目前只有 `browser-e2e.cjs` 覆盖，而它不在强制门禁里——**这类回归没有自动防线**。
|
||
是否把浏览器 E2E 接进 `verify.py`、是否把 `puppeteer-core` 写进 `package.json`，需人决策。
|
||
- **F28（新）模拟/演示数据随验证累积**：`scripts/xingbang_batch4_smoke.py` 与
|
||
`scripts/browser-e2e.cjs` 都**真的写演示库**（新建卡片、会议结果），重复运行会累积脏数据。
|
||
两者都在脚本头注明了这一点。
|
||
- **F20** 新旧经验入口并存（工作台旧「评审经验」页签）；**F21** 首页默认路由已变更
|
||
`/` → `/assistant`。两者都需确认后处理。
|
||
- **F23（新）改进端点仍无角色门禁**：既有候选/方案端点对评测与发布有 `role()` 门禁，
|
||
改进端点只有项目范围检查。本批 release 接上真实发布后后果变重，但加门禁会改变既有
|
||
端点行为（现有 API 测试以 `manager` 身份调用），未擅自扩大改动。
|
||
"不自批"已由服务端强制（`must_not_self_approve` + `registry.release()` 的 `edited_by`）。
|
||
- **F24（新）对照样本是人工录入的 JSON**，非真实保留集；`evaluation.independent` 仍是
|
||
客户端声明的布尔——服务端无法自证独立性。
|
||
- **F25（新）会议结果是模拟录入**，未经真实会议系统；真实标签映射与身份权限待确认（M5/M6）。
|
||
- **F26（新）题库/编排无真实发布入口**（`question_profile`/`orchestration`）：已按 409
|
||
诚实拒绝，非假接通。
|
||
- **F22 已关闭**（会议结果与轨迹的录入已在第四批实现）。
|
||
- **F15 已关闭**（改进发布已接真实知识发布入口，并经真实发布指针验证）。
|
||
- **F7** 各卡门禁仍 `proposed`，审阅者未指派——用户授权不等于评审通过。
|
||
- **F8** Docker 运行时冒烟未实测（本机 Docker Desktop 守护进程不可达）。
|
||
- **F6** OQ-06 Q3–Q5：端口冲突核验、运行资源、Gitea CI 是否启用仍 open。
|
||
- **F12/F14/F16** 仍有效；**F13** 已由第一批关闭。
|
||
- 下一任务：四批纠偏已全部有交付（均记**部分完成**）。**F11 已可自行推进**
|
||
（本机有 Chrome，脚本已入库，无需外部环境）；继续推进前需你定的两件事：
|
||
① 是否把浏览器 E2E 接进 `verify.py` / 写进 `package.json`（F27）；
|
||
② 是否继续用真实浏览器把 `/experience-center`、`/prescreen-workbench` 也逐项点完（F11 剩余部分）。
|
||
补 **F17** 仍需要你提供模型端点与调用时机。不要为了推进而把演示当验收。
|
||
- 待输入：模型端点与调用时机（F17）；真实数据/制度/会议标签映射与客户身份权限（M5/M6）；
|
||
Laya 硬件与中文效果需实机探测；Jev 端点与凭据。
|
||
- Git：本轮在 `codex/xingbang-v2-model-field-fix` 分支有 **3 个提交**，**均未推送**：
|
||
- `f775c6c` —— `feat(v2): 纠偏第四批——会议结果录入与改进发布接真实知识发布入口`
|
||
- `ff59d7e` —— `docs(v2): 第四批交接记录补记本轮提交号`
|
||
- `4720d72` —— `fix(v2): 浏览器端到端验证——修掉模块页在浏览器里渲染不出内容的缺陷`
|
||
核对命令 `git log --oneline -6`。**不在这里写死 HEAD**：交接文档自身的提交会成为新的
|
||
HEAD，写死必然过期；以上三个是本轮的实质提交，其后可能还有仅改文档的提交。
|
||
不得从旧恢复点 4d5a420 推断最新版本已备份。
|