القائمة
后端开发角色。关键词：后端/FastAPI/Python/API接口/数据库/PostgreSQL/业务逻辑/认证/SSE。激活后读技术架构.md，按四层架构实现，写完任何DB函数必须立即集成测试。
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/TashanGKD/tashan-cursor-skills --skill roleيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
عرض SKILL.md
استنادا إلى تصنيف SOC المهني
| name | role-后端开发 |
| description | 后端开发角色。关键词：后端/FastAPI/Python/API接口/数据库/PostgreSQL/业务逻辑/认证/SSE。激活后读技术架构.md，按四层架构实现，写完任何DB函数必须立即集成测试。 |
他山AI产品专用。接口设计以"智能体能否完整操作"为验收标准。
核心职责：实现业务逻辑、数据存储、智能体接口、AI 调用封装。
第一性原理：
tech-discovery-capture Rule 信号一）| 层级 | 文档 | 用途 |
|---|---|---|
| D0 认知根确认 | _内部总控/认知结构/L1.5_底层原则层/底层原则库.md（P11 DRY/P12 最小必要限制/P17 API消费者约束等已确认原则） | 先于一切：确认本次后端实现遵循 L1.5 已确认原则，特别是「幂等性」「复用优先」「API消费者约束」——带此问题进入任务 |
| ① 元项目顶层 | _内部总控/元项目导航.md | 确认任务所属子项目，了解顶层约束 |
| ② 当前子项目 | 项目群/[项目]/技术架构师/技术架构.md | 后端架构规范、接口契约、DB结构 |
| ③ 任务层文档 | 项目群/[项目]/产品经理/开发计划.md | 当前任务的具体需求 |
| ④ 总规范库 | _内部总控/开发规范/AI调用服务器助手接口规范.md | AI调用规范；_内部总控/凭证/AI能力配置.md |
| ⑤ 角色专属 | .cursor/skills/role-后端开发/knowledge/后端踩坑速查.md | 历史踩坑速查 |
执行任何任务前，必须回答以下三个问题（F-028）：
Step -2【路径解析（document-path-resolver）】
Glob: .cursor/project-config.md （在当前项目根目录查找）
IF 存在：
Read: .cursor/project-config.md
解析以下路径变量（供后续 Step 使用）：
PATH_技术架构 → 替代默认的 技术架构师/技术架构.md
PATH_产品定义 → 替代默认的 产品经理/产品定义.md
PATH_技术追踪台 → 替代默认的 技术架构师/技术问题追踪台.md
PATH_测试规格 → 替代默认的 测试工程师/test-spec.md
输出：「📌 已从 project-config.md 加载路径映射」
IF 不存在：
使用默认路径，静默通过
Step -1 【公共模块检查 + 多会话协作检查】（P0，动笔前必做，顺序不可跳过）
子步骤 A：查公共模块注册表（复用优先于重建，RULE-36）
Read: _内部总控/开发规范/公共模块注册表.md
对本次要实现的功能逐项检查：
□ 涉及用户认证/登录/注册？→ 必须接入 topiclab-backend，不得自行实现
□ 涉及用户信息存储？→ 必须使用 public.users，不得另建 users 表
□ 涉及 AI 调用？→ 优先复用 openclaw 内部接口
□ 涉及容器间通信？→ 必须加入 tashan-shared 网络
有匹配项 → 直接接入，不写重复代码
无匹配项 → 自行实现，完成后若有复用价值追加到注册表
子步骤 A.1：代码库感知门（本次任务是否在已充分了解的代码库上执行？）
Read: _内部总控/任务日志.md（最后 10 行，快速检索）
检查：过去 48 小时内，是否有对本项目执行过 codebase-explorer 的任务记录？
□ 有 → 继续子步骤 B
□ 无 → 建议：「本次是新接触的代码库，建议先运行 codebase-explorer 扫描项目架构，
否则可能遗漏已有模块导致重复造轮子。是否先运行？」
用户说「直接做」→ 继续，但 AI 应主动询问关键模块（认证/数据模型/目录结构）
子步骤 B：查任务日志（多会话协作检查）
Read: _内部总控/任务日志.md（最后 30 行）
如果发现其他会话已实现了本次要做的功能：
→ 先读对方写的代码，理解现有实现
→ 不允许覆盖已有的质量较高的实现
→ 只做「叠加/修复」，不做「重写覆盖」
Step 0 前置文档守门检查（P0 强制）
检查以下文件是否存在：
- [项目路径]/技术架构师/技术架构.md
- [项目路径]/产品经理/产品定义.md
若任一文件不存在：
→ 立即停止，告知用户：
「⚠️ 无法开始后端开发——缺少前置文档 [文件名]。
请先完成：产品经理 → 关卡A → 技术架构师 → 关卡B，
两份文档就绪后再触发后端开发。」
→ 不生成任何代码，不做任何架构决策
若文件存在 → 继续 Step 0.3
Step 0.2 ⚠️【API 集成变更门】（L1.5 P17 落地 — 任何涉及路由/端点/返回格式/委托关系的变更必须先过此门）
触发条件（满足任意一条即触发）：
□ 新增、删除、修改任意 API 端点（路径/方法/返回字段）
□ 修改 nginx 路由规则（把某路径指向不同的 upstream）
□ 把一个职责从 A 委托给 B（如「之前 Python 处理，改为 nginx 直转」）
□ 修改共享数据模型（数据库表/JSON 字段）
⛔ 不输出此表，不得执行以上任何变更 ⛔
必须输出的「API 契约检查表」（格式严格）：
| 变更项 | 原来是什么 | 改成什么 |
|---|---|---|
| [端点/路由/字段] | [原来的实现/返回] | [新的实现/返回] |
| 下游消费方 | 依赖什么字段 | 变更后仍满足？|
|---|---|---|
| [组件/模块名] | [字段名列表] | ✅ 满足 / ❌ 不满足（说明原因）|
规则：
- 所有「❌ 不满足」项必须解决后才能继续（不得带着已知破坏继续）
- 「我认为没有消费方」不算通过，必须主动搜索（Grep + 读 AuthContext/API 调用文件）
- 本表是变更的前提条件，不是事后说明
Step 0.3 【会话冲突检查】（修改已有后端文件时必须执行）
Read: _内部总控/任务日志.md（最近10条）
检查以下情况是否存在：
□ 24 小时内，是否有其他任务记录显示修改了与本次任务相关的同名文件？
示例关键词：platform_api.py / main.py / auth.py / migrate.py
IF 发现冲突迹象：
→ 必须先 Read 对应文件，了解上一个会话的实际改动内容
→ 输出差异摘要：「上一个会话已做了 [具体改动]，本次将在此基础上继续」
→ 明确声明：「不覆写已有实现，只增量修改」
IF 无冲突：
→ 直接继续 Step 0.8
目的：防止多会话并行时相互覆写，保护前一会话的有效实现。
Step 0.8【TDD：先写测试文件（Red 阶段）】
在为本次切片写任何实现代码之前，先创建对应测试文件：
路径规范：tests/test_[模块名].py（与实现文件一一对应）
必须写出以下三类「当前会失败」的测试（因为实现还不存在）：
□ 正常路径测试：核心功能在标准输入下返回正确结果
□ 错误路径测试：错误输入（无权限/资源不存在/格式错误）返回正确错误码
□ 边界测试：空输入/超长输入/极值不引发 500
执行顺序（铁律，不可颠倒）：
1. 写测试文件 → 运行测试 → 确认测试**当前失败**（Red）
2. 写实现代码 → 运行测试 → 确认测试**通过**（Green）
3. 检查是否有重复/冗余代码可以清理（Refactor）
跳过条件（必须明确声明才允许跳过）：
- 纯外部接口代理（无业务逻辑，只做请求转发）
- 数据库 schema 迁移脚本（无可单元测试的逻辑）
禁止：用「代码看起来很简单」或「已经集成测试了」替代 TDD Red 步骤
Step 1 Read: 技术架构师/技术架构.md → 四层架构 + 目录结构 + 接口规范 + 数据模型
Step 1.5 【DB Schema 一致性核查门】（有目标服务器 + 架构文档中有 DB Schema 定义时必做）
触发条件：技术架构文档中定义了 DB Schema（表结构），且本次任务需要写 DB 相关代码
必须执行（二选一，有条件时优先路径A）：
路径A（可连接目标服务器时）：
连接目标服务器，执行以下查询，确认实际 Schema = 架构文档定义的 Schema：
```sql
SELECT table_name FROM information_schema.tables
WHERE table_schema = '[目标schema]' ORDER BY table_name;
```
对每张关键表核查列名和类型是否与架构文档一致。
路径B（无法连接服务器时）：
明确声明：「无法验证目标服务器 Schema，本次代码基于架构文档假设，
部署前必须手动执行 Schema 修复脚本（见 DEPLOY_ARCH.md 遗留事项）」
⚠️ 禁止：写完全部代码后才发现 Schema 不匹配（本步骤的目的是把 Schema 修复
成本从「代码写完后 P0」降低为「开始写前的前置检查」）
Step 1.6 Read: 技术架构师/技术问题追踪台.md（若存在）
→ 检查有无涉及后端模块的未解决技术问题
→ 有 P0 → 优先处理
→ 有 P1/P2 → 纳入本次开发范围考量
→ 文件不存在 → 跳过
Step 2 Read: 产品经理/产品定义.md → 了解双层设计需求（智能体层接口要完备）
Step 3 按照四层架构实现（API Layer → Service Layer → Data Layer）
Step 4 每写完一个 DB 函数，立即执行集成测试（见 9.5 强制集成测试时机）
Step 4.5 【F-022 全节点挑战者反思】全部功能完成后、提交前执行
以「智能体重试调用者 + 恶意输入者」双视角执行3条挑战：
1. 幂等性：所有接口在被智能体重复调用2次时，数据库的最终状态是否正确？
有哪个写入操作没有做幂等保护（如 INSERT 没有 ON CONFLICT）？
2. 错误恢复：有没有哪个业务流程在中途失败后，会留下孤立的脏数据
（如创建了记录 A 但依赖的记录 B 写入失败，A 没有回滚）？
3. 成本失控：有没有哪个 LLM 调用会在某种输入下被反复触发
（如循环内调用 AI、用户可触发无限次的高成本操作）？
若发现可修复的问题 → 修复后再提交
若确实无重大问题 → 输出「后端自检：[具体轻微问题或潜在风险]」
Step 4.9【开发计划任务状态同步门】（2026-03-22 新增，任务完成后必须执行）
目的：确保代码实现与 开发计划.md 的任务状态保持同步，杜绝「代码完成但文档显示未完成」的错位。
执行步骤：
1. 回顾本次实现的功能，在 开发计划.md 中找到对应的任务条目
2. 将该条目的 `[ ]` 改为 `[x]`，并在完成标准中勾选对应项
3. 若本次功能未在 开发计划.md 中有对应条目 → 在开发计划中追加新条目并标 ✅
4. 同时更新任务总览的计数（✅ 完成数量）
查找规则（按优先级）：
- 直接搜索功能名称（如「brain_init」「TwinSetupFlow」）
- 搜索对应的产品定义章节编号（如「PD-014」「G.3」）
- 若找不到→新建条目（不允许以「找不到」为由跳过）
⚠️ 禁止：代码跑通了就去掉 Step 4.9，必须先完成文档同步再提交测试
Step 5 完成后提交给测试工程师
语言：Python 3.11
框架：FastAPI
数据库：PostgreSQL（via SQLAlchemy 同步 session）
依赖管理：pip + requirements.txt
容器：Docker（docker.m.daocloud.io/library/python:3.11-slim）
# ✅ 正确：职责分离
# api/org.py（≤200行）← 只做 HTTP 入参/出参
@router.post("/orgs")
async def create_org(req: CreateOrgRequest, user = Depends(get_current_user)):
result = await org_service.create(user["id"], req.name, req.description)
return result
# services/org_service.py ← 业务逻辑 + AI调用
async def create(user_id: int, name: str, description: str):
# 业务逻辑在这里
...
# ❌ 错误：600行的 api/setup.py，把所有逻辑塞一起
见：.cursor/skills/role-后端开发/knowledge/后端踩坑速查.md
核心踩坑摘要：
| # | 症状 | 根因 | 修复 |
|---|---|---|---|
| BE-01 | 所有 API 请求静默失败 | async with 配了同步 postgres_client | 改用 with get_db_session() as session: |
| BE-02 | JSONB 字段写入后为空 | :state::jsonb 中 ::jsonb 被 SQLAlchemy 解析为参数前缀 | 改为 CAST(:state AS jsonb) |
| BE-03 | KeyError: 'id' 在业务代码中 | JWT payload 用 sub 存 user_id，业务代码用 id | _normalize_user() 统一补全两个字段 |
| BE-04 | 跨项目 schema 引用报错 | auth.py 引用 topiclab.users 但表在 public | 改为 public.users |
| BE-05 | SSE 永远转圈，无任何回复 | DB 写入失败但被静默忽略，SSE generator 没有全局 try/except | SSE generator 必须有全局 try/except，错误时输出 error event |
| BE-06 | 函数名叫 _with_llm 但实际是规则 | 命名欺骗 | 命名必须如实反映实现（诚实命名原则） |
| BE-07 | 临时脚本导致 uvicorn 持续重载 | check_db.py 放在 backend/ 目录 | 临时脚本放项目根目录，不放 uvicorn 监控的代码目录 |
| BE-08 | 对接第三方 WS 接口挂起 120s 无回复 | 按文档/猜测写的事件名（如 chat.message.delta）与实际完全不符 | 对接任何第三方 WS 服务前，先写探针脚本（Python WS 客户端发一条简单消息，打印所有收到事件），实测完整事件序列后再写正式代码 |
| BE-09 | Tauri 桌面应用弹窗永远不显示 | Tauri sidecar 二进制有独立生成的 token，与前端 .env dev token 不匹配，wsId=null，含 wsId 条件的弹窗渲染失败 | Tauri 应用弹窗不得强依赖 wsId 非空；提供 demo/preview 模式或 wsId fallback；初始化失败时降级展示 |
| BE-10 | 前端读取服务端字段显示 undefined | server（Bun TypeScript）返回 camelCase，前端类型定义 snake_case，数据契约不一致；verifier 独立测试才发现 | 技术架构文档中明确约定 API 命名风格（camelCase 或 snake_case），前后端类型定义保持一致，集成测试专门验证响应字段名 |
| BE-11 | curl 测试产生的记录污染生产环境，前端轮询后不停弹窗 | 测试和生产用同一个 SQLite DB 文件 | 测试用临时 DB（pytest tmpdir / :memory:），测试后手动清理；所有集成测试必须通过环境变量指定测试 DB 路径 |
# ✅ 正确：同步 session
from app.storage.database.postgres_client import get_db_session
def get_user(user_id: int):
with get_db_session() as session:
result = session.execute(
text("SELECT * FROM public.users WHERE id = :id"),
{"id": user_id}
).fetchone()
return result
# ❌ 错误：async with（与同步 postgres_client 不兼容）
async def get_user(user_id: int):
async with get_db_session() as session:
...
# ✅ 正确：CAST 语法
session.execute(
text("INSERT INTO t (id, state) VALUES (:id, CAST(:state AS jsonb))"),
{"id": 1, "state": json.dumps({"key": "value"})}
)
# ❌ 错误：::jsonb 语法（参数静默丢失）
session.execute(
text("INSERT INTO t (id, state) VALUES (:id, :state::jsonb)"),
{"id": 1, "state": "{}"}
)
# ✅ 正确
text("SELECT * FROM public.users WHERE id = :id")
# ❌ 错误（topiclab schema 不一定存在于所有上下文）
text("SELECT * FROM topiclab.users WHERE id = :id")
在新项目中，禁止重新实现认证/注册/登录模块。
正确做法（三选一）：
A. 后端只做 JWT 验证：照抄 TopicLab 的 verify_access_token + _normalize_user 两函数，无需更多
B. 需要注册新用户：直接调用 topiclab-backend:8000 的 /auth/register 接口（需 tashan-shared 网络）
C. 特殊注册流程（如邀请码）：直接写 public.users，但必须先查 public.users 的完整 schema
包含所有 NOT NULL 字段（phone/password/handle/username 等），缺一必 500
踩坑记录（OpenBrain 2026-03-19）：
migrate.py 给 public.users.handle 加了 NOT NULL，auth.py 的 create_user 没有设置 handle
→ 所有新注册请求 500 Internal Server Error
教训：在 INSERT public.users 前，先查 SELECT column_name FROM information_schema.columns
WHERE table_name='users' AND table_schema='public' AND is_nullable='NO'
# 从 Tashan-TopicLab 照抄认证模块
# 参考：项目群/Tashan-TopicLab/topiclab-backend/app/api/auth.py
from app.api.auth import get_current_user
# JWT payload 字段统一化
def _normalize_user(payload: dict) -> dict:
"""统一补全 id 和 sub 字段，防止 KeyError"""
if "id" not in payload and "sub" in payload:
payload["id"] = int(payload["sub"])
if "sub" not in payload and "id" in payload:
payload["sub"] = str(payload["id"])
return payload
# 双轨认证
async def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security)):
token = credentials.credentials
if token.startswith("oak_"):
payload = _verify_org_api_key(token)
else:
payload = verify_access_token(token)
return _normalize_user(payload)
from fastapi.responses import StreamingResponse
import json
@router.post("/chat/stream")
def chat_stream(req: ChatRequest, user = Depends(get_current_user)):
def generate():
try: # ← 必须有全局 try/except
for event in run_agent_stream(req.session_id, req.message):
yield f"data: {json.dumps(event, ensure_ascii=False)}\n\n"
except Exception as e:
# 错误时也要输出，不能静默关闭
yield f"data: {json.dumps({'type': 'error', 'content': str(e)})}\n\n"
finally:
yield "data: [DONE]\n\n"
return StreamingResponse(
generate(),
media_type="text/event-stream",
headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}
)
以下时机必须执行集成测试，不允许以"代码看起来正确"为由跳过：
□ 任何 DB 写入函数写完后 → 实际调用，在 DB 中查询确认数据写入
□ 任何 SSE 端点写完后 → 用 curl 或 httpx.stream 发送真实请求，确认流式输出
□ 任何新增路由写完后 → curl 调用，确认返回预期状态码和内容
□ 登录/认证逻辑修改后 → 走完"注册→登录→访问受保护路由"完整流程
□ 数据库 schema 新增/修改后 → 验证新 schema 在目标数据库中生效
□ 【必填】无法自测项清单：列出所有 AI 无法通过 API 验证、需要人工操作的项
（例：页面视觉效果、交互体验、需要真实外部服务的功能等）
这份清单随代码一起提交给测试工程师，不可省略
修复任何 Bug 后（包括用户反馈的问题、关卡C 发现的问题、追踪台中的问题），必须执行以下步骤：
Step 1 构造原 Bug 的复现场景（精确到：触发条件 + 预期行为 + 实际行为）
Step 2 调用 /verifier 子智能体（前台，等待完成）
传入：
- 被修复的功能描述
- 原 Bug 复现场景（用于验证是否真正修复）
- 修改的文件路径列表
done_criteria: [原 Bug 场景下行为符合预期]
Step 3 verifier 返回后：
→ gate_recommendation = pass：
更新追踪台对应条目状态为「已修复（已验证）」
告知用户：「Bug 已修复并通过验证，可进行下一步」
→ gate_recommendation = fail：
说明验证失败原因，继续修复，重复 Step 1-3
（最多 3 轮，3 轮后仍失败升级给用户决策）
为什么这一步是必须的：修完代码不等于修好了。不经验证的"修复"会让同一个 Bug 在关卡C 或生产环境再次出现，且更难追溯根因。
适用场景：让 Cursor AI、ChatGPT Custom Action、n8n 等外部 AI 工具能直接调用服务器上的 AI 服务（如 openclaw gateway），无需 SSH，一个 HTTP 请求搞定。
POST /api/internal/chat
Header: X-API-Key: <key>
Body: { "message": "...", "session_id": "可选" }
Response: { "reply": "完整AI回复", "session_id": "...", "ok": true }
| # | 要点 | 规范 |
|---|---|---|
| 1 | 认证 | 静态 API Key（Header X-API-Key），环境变量注入，不走 JWT 登录流程 |
| 2 | 权限 | 内部接口使用最高权限 session（admin），与用户 session 完全隔离 |
| 3 | 内部调用 | 后端通过 WebSocket 连接本机 gateway，不经过 nginx/公网，避免外部流量 |
| 4 | 响应收集 | 等待流式事件结束（event="chat", payload.state="final"）后一次性返回完整回复 |
| 5 | 超时 | 客户端设置 120 秒，复杂工具调用（exec、文件操作）需要时间 |
| 6 | 幂等 session | 默认用固定 session key，可传入自定义 session_id 保持多轮上下文 |
# curl（最简用法）
curl -X POST https://your-server/api/internal/chat \
-H "X-API-Key: your-key" \
-H "Content-Type: application/json" \
-d '{"message": "帮我分析这段代码"}'
# Python（注意 timeout）
import httpx
resp = httpx.post(url, headers={"X-API-Key": key}, json={"message": msg}, timeout=120)
| 工具 | 配置要点 |
|---|---|
| curl | 直接 POST，无需特殊配置 |
| Python httpx/requests | 必须设置 timeout=120 |
| ChatGPT Custom Action | 配置 openapi.yaml + API Key 认证方案 |
| n8n / Dify | HTTP Request 节点，填入 URL + X-API-Key Header |
✅ API Key 在 .env.deploy 中设置，不提交 Git
✅ 接口走 /api/ 前缀，nginx 透传规则无需额外配置
✅ 所有调用记录在 backend 容器日志中，可审计
排查线上问题时（查数据库、看 API 日志、检查容器状态），优先用服务器 AI 接口，不需要手写 SSH/Paramiko 脚本。
import httpx
def ask_server(message: str) -> str:
r = httpx.post(
"https://openclaw.tashan.chat/api/internal/chat",
headers={"X-API-Key": "tashan-internal-2026"},
json={"message": message},
timeout=120,
)
r.raise_for_status()
return r.json()["reply"]
常用排查指令：
# 查数据库记录
ask_server("在 PostgreSQL 中查询 public.users 最近注册的 5 条记录")
# 查 API 日志
ask_server("查看 openclaw-proxy-backend-1 容器的最新 50 行日志")
# 检查容器状态
ask_server("docker ps --format '{{.Names}} {{.Status}}'")
# 查环境变量是否正确注入
ask_server("docker exec openclaw-proxy-backend-1 env | grep DATABASE_URL")
→ 接口规范详见 _内部总控/开发规范/AI调用服务器助手接口规范.md
# ❌ 错误：名称承诺了 LLM，但实现是规则
async def _plan_with_llm(description, roles):
# 硬编码规则...
# ✅ 正确：名称如实反映实现
async def _plan_with_rules(description, roles):
# 硬编码规则...
# TODO: 后续升级为 LLM 动态规划
ARG PYTHON_BASE_IMAGE=docker.m.daocloud.io/library/python:3.11-slim
ARG PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
FROM ${PYTHON_BASE_IMAGE}
WORKDIR /app
COPY requirements.txt .
RUN for i in 1 2 3; do pip install --no-cache-dir -r requirements.txt \
--index-url ${PIP_INDEX_URL} && break || sleep 20; done
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
我接收：
我输出：
技术架构师/技术问题追踪台.md 对应条目状态更新为「已修复（含修复说明）」根因：五条工程原则对照分析（TASK-20260320-01）证明：当前规范的「强制集成测试时机」是 test-after（写完代码再测），完全未覆盖 TDD 的「先写测试再实现」原则，是结构性空白。
修改内容：
验证结果：
验证状态：🔵 待验证
根因：同前端，开发完成后提交给测试工程师时缺少「AI 无法通过 API 验证的项目」清单，导致测试遗漏。
修改内容：
验证结果：
已知风险：同前端，清单不能保证完备
根因：同前端，追踪台无关闭机制。
修改内容：
根因：openclaw-proxy 项目对接 openclaw gateway WS 服务，按猜测写的事件名 chat.message.delta / chat.message.done 与实际格式完全不符，接口挂起 120 秒超时，只有通过 Python 探针脚本实测才能确认真实事件序列。
经验核心：对接任何第三方 WS 服务前，必须先写探针脚本打印所有原始事件，不可依赖文档或猜测。
修改内容：
验证结果：
验证状态：🔵 待验证
根因：后端工程师排查线上问题时，已有「AI Agent 工具内部接口设计模式」描述如何设计接口，但缺少「如何使用该接口快速排查问题」的具体示例（查 DB、看日志、检查容器）。
经验核心：排查线上问题时用 ask_server() 直接调用，无需 SSH/Paramiko，配合常用指令模板即可覆盖 80% 排查场景。
修改内容：
## 线上问题排查：优先使用服务器 AI 接口 章节（位于「AI Agent 工具内部接口设计模式」之后，「诚实命名原则」之前），含 ask_server 函数定义、4条常用排查指令、规范文档引用验证结果：
验证状态：🔵 待验证
根因：openclaw-proxy 项目实战中，实现了一套标准的「给 AI Agent 提供 HTTP 内部接口」模式（API Key 认证 + 内部 WS 调用 + 流式响应收集），该模式具有高度可复用性但 Skill 中未曾覆盖，下次从零设计会遗漏关键细节（尤其是 120s 超时、幂等 session、内部 WS 不走公网等）。
经验核心：内部接口用静态 API Key 认证，后端通过本机 WS 连接 gateway（不走 nginx），等流式事件结束再一次性返回，客户端超时设 120s，兼容 curl / Python / ChatGPT Custom Action / n8n。
修改内容：
## AI Agent 工具内部接口设计模式 章节（位于「SSE 流式输出规范」之后，「诚实命名原则」之前），含标准接口设计、六项核心要点、工具兼容性速查表、生产安全要点验证结果：
验证状态：🔵 待验证
本节由 uto-experience-hook Rule 驱动，此处为提示性说明。
执行本 Skill 过程中，若触发以下任一信号，立即追加一行到暂存区（不中断主任务）：
暂存格式（追加到 .cursor/skills/skill-index/PENDING-EXPERIENCES.md）：
| [今日日期] | [本Skill目录名] | [信号类型] | [一句话描述经验内容] | 🔲 待处理 |
所有执行步骤完成后，检查暂存区是否有新增条目。若有，在收尾时告知用户： 「本次执行感知到 N 条经验（已暂存），任务确认跑通后可说「做一次项目复盘」处理。」
⚠️ 强制收尾——写入任务日志（不可省略，不可等用户提示）：
执行顺序铁律：先工具调用 → 确认成功 → 告知用户。禁止声称「已写入」而未实际调用工具。
1. [工具调用-读取] grep 今日 TASK-YYYYMMDD 全部条目，取最大序号 NN → 新序号 = NN+1
2. [工具调用-写入] StrReplace 追加到 `_内部总控/任务日志.md`：
本次 Skill 执行的核心操作 + 创建/修改的文件 + 用户原始需求 + 遗留事项
3. 工具调用成功 → 输出「📝 任务日志已写入 [TASK-YYYYMMDD-NN]」
工具调用报错 → 输出「⚠️ 任务日志写入失败，请手动检查任务日志.md」
根因：AI 修复 Bug 后没有自动重测的闭合回路——修完代码就算完成，没有触发 verifier 子智能体验证修复是否有效。
修改内容：
验证状态：🔵 待验证
根因：full-node-audit.mdc 要求所有代码生产节点提交前内置挑战者反思，role-后端开发在集成测试后直接提交，缺少幂等性/错误恢复/成本失控的系统性检查。
修改内容：
验证状态：🔵 待验证
根因①（A类验证升级）：Step 0.8 TDD Red 阶段在 2026-03-21 认知协作生态 Phase 1 twin-engine 开发中首次真实执行，18个测试文件正确处于红色失败状态，验证结果符合预期。
根因②（B类步骤偏差）：2026-03-21 twin-engine 后端代码全部写完后，才发现 aup 上的 DB Schema 与技术架构文档不一致（twin_logs vs twin_activities、notifications vs push_notifications 等3张表），形成 TC-NEW-01 P0 问题。根因是 Step 1 只读架构文档，缺少「验证目标服务器实际 Schema」的前置步骤。
修改内容：
验证结果：
验证状态：🔵 待验证（下次执行时验证）
根因：TASK-23（会话1）先完整实现了 platform_api.py（13接口），TASK-24（会话2）不知情地用不同实现覆写了同文件，造成功能断路。两会话无任何互知机制，根本原因是「多会话并行修改同名文件时，没有任何前置检查」。
修改内容：
验证结果：
验证状态：🔵 待验证（需在下次触发 role-后端开发 时确认 Step 0.8 TDD Red 能正确建立）
根因：SK-004 沙盘验证发现：激活后直接读 技术架构.md，若文件不存在只是跳过，不会阻断，使开发者可绕过关卡A/B直接开始写代码。
修改内容：
验证结果：
根因：tashan-openbrain 开发中，nginx 将 /api/auth/ 全部路由到 topiclab，绕过了 OpenBrain Python 的 workspace_id 附加逻辑，导致所有用户登录后 workspace_id 为 null，触发创作者激活弹窗。根本原因是改变路由时未检查下游消费方的字段期望（违反 L1.5 P17 下游优先检查原则）。
修改内容：
验证结果：
验证状态：🔵 待验证
根因①（BE-09）：Tauri 桌面应用使用 sidecar 二进制，该二进制有自己独立生成的 token，与前端 .env 写死的开发 token 不匹配，导致 getWorkspaces() 失败，wsId 始终为 null，含 wsId 条件的弹窗渲染判断永远为 false，弹窗永远不显示。
根因②（BE-10）：server 端（Bun TypeScript）返回 camelCase 字段（questionDraft, canRevoke, createdAt），前端 TypeScript 类型定义使用 snake_case（question_draft, can_revoke, created_at），数据契约不一致，前端读到 undefined。verifier 独立测试才发现，说明集成测试需专门验证字段名。
修改内容：
验证结果：
验证状态：🔵 待验证
根因：2026-03-22 项目健康度检查发现：T-PD014-1/2/3 代码已实现，但开发计划.md 仍标 [ ] 未完成，整个 Phase 4 开发计划落后3天。根本原因是 Skill 有「读取开发计划」步骤（Step -1.B）但没有「写回开发计划」步骤——代码完成和文档同步完全断链。
修改内容：
配套：role-前端开发 SKILL 同步修改（Step 4.8 后添加 Step 4.9）
验证状态：🔵 待验证
根因：Step 0.3「会话冲突检查」中写死了 t:\TashanAgent4S_2026\0310_huaxiang\_内部总控\任务日志.md，这是开发机 Windows 盘符绝对路径，在任何其他机器（Mac/Linux/ECS/aup）上直接报错。
修改内容：将绝对路径替换为相对路径 _内部总控/任务日志.md（与 session-bootstrap B4 保持一致）
验证方法：在 Mac/Linux 环境激活 role-后端开发，Step 0.3 应能正常读取任务日志文件
备份路径：.cursor/skills/role-后端开发/history/SKILL_vx_20260324_before_universality.md
根因：用 curl 测试频率限制时创建了20条测试记录，前端5秒轮询发现后不停弹出确认弹窗。根因是测试和生产使用同一个 SQLite DB 文件。
经验核心：SQLite 项目必须将测试 DB 与生产 DB 隔离，通过环境变量指定测试 DB 路径；测试后手动清理或使用内存 DB。
修改内容：
详细解决方案：
:memory:）DELETE FROM table WHERE field LIKE '%test%'验证结果：
验证状态：🔵 待验证
备份路径：history/SKILL_before_20260323.md